diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 4701c66b..c66b8d88 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -14,18 +14,55 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4.2.2
+        with:
+          fetch-depth: 0
       - uses: actions/setup-node@v4.2.0
         with:
           node-version: 20
           cache: npm
           cache-dependency-path: package-lock.json
       - run: npm ci
+      - run: npm audit --audit-level=moderate
+      - run: npx playwright install --with-deps chromium
       - run: npm run format
+      - name: Check changed-line whitespace
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            git diff --check "origin/${{ github.base_ref }}...HEAD"
+          else
+            git diff --check "${{ github.event.before }}...HEAD"
+          fi
       - run: git diff --exit-code
       - run: npm run check-undefined
       - run: npm run lint
+      - run: npm run typecheck:critical
+      - run: npm run release-readiness
       - run: npm run depcheck
+      - run: npm run check-mcp-clients
+      - run: npm run test-bench-unit
       - run: npm test
+      - name: Create localhost HTTPS cert
+        run: |
+          mkdir -p certs
+          openssl req -x509 -newkey rsa:2048 -nodes \
+            -keyout certs/localhost-key.pem \
+            -out certs/localhost.pem \
+            -days 1 \
+            -subj "/CN=localhost" \
+            -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"
+      - name: Start HTTPS server
+        run: |
+          npm run start-https > /tmp/lemmings-http.log 2>&1 &
+          echo $! > /tmp/lemmings-http.pid
+          node -e "const https=require('node:https'); const started=Date.now(); const tick=()=>{const req=https.get('https://localhost:8080/?e2e=1',{rejectUnauthorized:false},res=>{res.resume(); process.exit(0);}); req.on('error',()=>{if(Date.now()-started>30000) process.exit(1); setTimeout(tick,500);});}; tick();"
+      - run: npm run test-mcp-smoke
+      - run: npm run bench-smoke
+      - name: Stop HTTPS server
+        if: always()
+        run: |
+          if [ -f /tmp/lemmings-http.pid ]; then
+            kill "$(cat /tmp/lemmings-http.pid)" || true
+          fi
       - run: npm run coverage
       - uses: actions/upload-artifact@v4
         with:
diff --git a/.gitignore b/.gitignore
index 93724ef1..a6482f35 100644
--- a/.gitignore
+++ b/.gitignore
@@ -36,3 +36,4 @@ test/processhtmlfile.test.js
 test/processhtmlfile.test.js
 playwright-report/
 test-results/
+temp/
diff --git a/MCP_COMPAT_PUBLISHING/manifest.example.json b/MCP_COMPAT_PUBLISHING/manifest.example.json
index 937c912f..ad80a4a4 100644
--- a/MCP_COMPAT_PUBLISHING/manifest.example.json
+++ b/MCP_COMPAT_PUBLISHING/manifest.example.json
@@ -16,7 +16,8 @@
       "args": ["${__dirname}/server/index.js"],
       "env": {
         "LOG_LEVEL": "info",
-        "API_KEY": "${user_config.api_key}"
+        "API_KEY": "${user_config.api_key}",
+        "LEMMINGS_MCP_SURFACES": "game,editor,interact"
       }
     }
   },
diff --git a/README.md b/README.md
index 3fabae57..d6cfea6c 100644
--- a/README.md
+++ b/README.md
@@ -151,23 +151,33 @@ Keybindings are configurable in `keybindings.json`. The in-game defaults map to
 
 ## MIDI
 
-- Enable MIDI from the left control panel (toggle persists). 
-  - When disabled, WebMIDI is not enabled and the MIDI router is detached.
-- Use the I/O section for Input/Output, Input channel, and `MIDI reset`.
-  - Input channel defaults to `Omni` and can be set to a specific 1-16 channel.
-- Use `reset all` to clear stored configuration and UI state.
-- Base BPM is the sequencing anchor; current BPM shows `speed x base`, plus ticks per second/beat/measure.
-- Global FX tab:
-  - Intensity and Accent adjust default velocity and density scaling.
-  - Positional Modifiers add X/Y mappings (with optional operators) and per-target min/max ranges.
-  - Global Repeat applies a beat window, max count, target, and amount to scale parameters on rapid repeats.
-- Events/Triggers tabs:
-  - Configure each SFX event or trigger with mode (note/degree/chord), key+octave, or scale degree + octave.
-  - Chords support triad, seventh, sixth, ninth, power, sus2, sus4, and octave.
-  - Arps support up/down/updown; triggers can optionally run independent arps per source.
-- ADSR tab lets you target Global, a specific SFX, or a trigger to override envelope values.
-- UI state is stored in localStorage. Defaults come from `midi-mapping.json` and apply only on first run or when a value is missing.
-- Full defaults and customization notes live in `midi-mapping.json` and `docs/midi-mapping.md`.
+- The in-game MIDI sequencer workspace is layered over `/` with transport
+  setup, source browser, track routing, inspector, clip editing, and output
+  status regions.
+- Enable MIDI from the transport strip, then choose WebMIDI input/output
+  devices and an input channel. Panic sends all-notes-off and clears queued
+  notes.
+- Editable state is stored only as `lemmings.midi.project.v1`. Fresh projects
+  are created from the checked-in `midi-mapping.json` factory template, and
+  legacy MIDI storage keys are cleared on load.
+- Use the source browser to search and filter SFX events, trigger types, MIDI
+  flags, system events, changed sources, sources available in the current
+  level, assigned/unassigned sources, and conflict status.
+- Tracks route sources to channels and output devices with mute, solo, arm,
+  velocity scale, priority, and voice budget controls.
+- The inspector edits direct note/degree/chord/velocity/duration/envelope
+  mappings, assigns clips, audits conflicts, and auditions the selected source
+  or clip through the selected track.
+- Clips support step, chord, and arp types. Step clips expose note, velocity,
+  probability, hold, and tie controls, plus keyboard navigation across the grid.
+- Save Template, Export, and Import move sanitized project/template JSON through
+  the project validator.
+- Learn captures a pending MIDI note assignment for a selected direct source.
+  Record captures a short mocked or live MIDI phrase into consecutive clip
+  steps.
+- Full defaults and runtime mapping notes live in `midi-mapping.json` and
+  `docs/midi-mapping.md`. Current UI behavior is documented in
+  `docs/midi-ui.md`.
 
 ### MIDI input mapping
 
@@ -229,6 +239,7 @@ Keybindings are configurable in `keybindings.json`. The in-game defaults map to
 
 ## Docs
 
+- Index: [docs/README.md](docs/README.md)
 - Usage: [docs/usage.md](docs/usage.md)
 - Offline tools: [docs/offline-tools.md](docs/offline-tools.md)
 - Exporting sprites: [docs/exporting-sprites.md](docs/exporting-sprites.md)
@@ -249,7 +260,8 @@ mode. Touch input still needs polish, so please file bugs for any issues you hit
 
 ## Roadmap
 
-See [docs/roadmap.md](docs/roadmap.md) for the consolidated roadmap and phases.
+See [docs/roadmap.md](docs/roadmap.md) for the active roadmap. Completed
+phases live in git history.
 
 ## Credits
 
diff --git a/css/editor.css b/css/editor.css
index e652dc19..14cb83da 100644
--- a/css/editor.css
+++ b/css/editor.css
@@ -111,13 +111,31 @@ body {
   color: #fff;
 }
 
+.editor-controls button:focus-visible,
+.editor-controls select:focus-visible,
+.editor-controls input:focus-visible,
+.tool-grid button:focus-visible,
+.palette-tabs button:focus-visible,
+.palette-recent button:focus-visible,
+.palette-view-toggle button:focus-visible,
+.palette-list button:focus-visible,
+.editor-button:focus-visible,
+.inspector-grid input:focus-visible,
+.inspector-grid select:focus-visible,
+.control-row input:focus-visible,
+.control-row select:focus-visible,
+.shortcut-overlay__close:focus-visible {
+  outline: 3px solid rgba(210, 106, 60, 0.55);
+  outline-offset: 2px;
+}
+
 .editor-main {
   display: grid;
   grid-template-columns: minmax(200px, 280px) 1fr minmax(220px, 320px);
   gap: 12px;
   padding: 8px 12px 12px;
   min-height: 0;
-  height: 100%;
+  overflow: hidden;
 }
 
 .editor-panel {
@@ -130,6 +148,8 @@ body {
   flex-direction: column;
   gap: 10px;
   min-height: 0;
+  overflow-x: hidden;
+  overflow-y: auto;
 }
 
 .panel-title {
@@ -245,6 +265,14 @@ body {
   image-rendering: pixelated;
 }
 
+.palette-preview.pending {
+  background:
+    linear-gradient(90deg, rgba(210, 106, 60, 0.08), rgba(210, 106, 60, 0.18), rgba(210, 106, 60, 0.08)),
+    #fffdf9;
+  background-size: 180% 100%;
+  animation: palette-preview-pulse 900ms linear infinite;
+}
+
 .palette-preview.empty {
   background:
     repeating-linear-gradient(
@@ -257,6 +285,15 @@ body {
     #fffdf9;
 }
 
+@keyframes palette-preview-pulse {
+  from {
+    background-position: 100% 0;
+  }
+  to {
+    background-position: -100% 0;
+  }
+}
+
 .palette-label {
   display: block;
   line-height: 1.25;
@@ -268,6 +305,34 @@ body {
   gap: 8px;
 }
 
+.palette-recent {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  padding: 6px;
+  border: 1px solid var(--panel-border);
+  background: #fffdf9;
+}
+
+.palette-recent[hidden] {
+  display: none;
+}
+
+.palette-recent button {
+  border: 1px solid var(--panel-border);
+  background: #f6efe5;
+  color: var(--ink);
+  cursor: pointer;
+  font-size: 11px;
+  min-height: 26px;
+  padding: 3px 6px;
+}
+
+.palette-recent button.active {
+  border-color: var(--accent);
+  background: #f7d6c5;
+}
+
 #editorPaletteSearch {
   width: 150px;
   min-width: 120px;
@@ -377,6 +442,40 @@ body {
   gap: 8px;
 }
 
+.compact-row {
+  align-items: flex-start;
+  gap: 6px;
+}
+
+.inline-controls {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  justify-content: flex-end;
+}
+
+.inline-controls input[type="number"],
+.inline-controls input[type="text"] {
+  min-width: 64px;
+  max-width: 120px;
+  padding: 4px 6px;
+  border: 1px solid var(--panel-border);
+  background: #fffdf9;
+}
+
+.inline-controls .editor-button {
+  text-align: center;
+  white-space: nowrap;
+}
+
+.inline-toggle {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  font-size: 11px;
+  color: var(--muted);
+}
+
 .selection-flags {
   border: 1px solid var(--panel-border);
   border-radius: 8px;
@@ -410,6 +509,39 @@ body {
   gap: 8px;
 }
 
+.validation-toolbar {
+  display: grid;
+  gap: 6px;
+}
+
+.validation-toolbar .editor-button {
+  text-align: center;
+}
+
+.validation-status {
+  border: 1px solid var(--panel-border);
+  background: #fffdf9;
+  color: var(--muted);
+  font-size: 12px;
+  line-height: 1.35;
+  padding: 6px 8px;
+}
+
+.validation-status[data-status="ok"] {
+  border-left: 4px solid #2f7a48;
+  color: var(--ink);
+}
+
+.validation-status[data-status="warnings"] {
+  border-left: 4px solid var(--warn);
+  color: var(--ink);
+}
+
+.validation-status[data-status="unavailable"] {
+  border-left: 4px solid var(--error);
+  color: var(--ink);
+}
+
 .issue-item {
   padding: 8px;
   border: 1px solid var(--panel-border);
@@ -445,7 +577,42 @@ body {
   border-left: 4px solid var(--warn);
 }
 
-.issue-item button {
+.issue-item.has-destructive-fix {
+  background: #fff8ee;
+}
+
+.issue-severity {
+  align-self: flex-start;
+  border-radius: 4px;
+  padding: 2px 6px;
+  font-size: 10px;
+  font-weight: 700;
+  text-transform: uppercase;
+  background: #efe6d9;
+  color: var(--muted);
+}
+
+.issue-item.error .issue-severity {
+  background: rgba(179, 54, 45, 0.12);
+  color: var(--error);
+}
+
+.issue-item.warning .issue-severity {
+  background: rgba(199, 124, 47, 0.14);
+  color: var(--warn);
+}
+
+.issue-message {
+  line-height: 1.35;
+}
+
+.issue-note {
+  color: var(--warn);
+  font-size: 11px;
+  line-height: 1.3;
+}
+
+.issue-action {
   align-self: flex-start;
   background: var(--accent);
   color: #fff;
@@ -455,9 +622,53 @@ body {
   font-size: 11px;
 }
 
+.issue-action.destructive {
+  background: var(--warn);
+  border: 1px solid #9b6326;
+}
+
 @media (max-width: 1100px) {
   .editor-main {
     grid-template-columns: 1fr;
+    align-content: start;
+    grid-auto-rows: max-content;
+    overflow-y: auto;
+  }
+
+  .editor-canvas-panel {
+    min-height: min(70vh, 640px);
+  }
+}
+
+@media (max-width: 640px) {
+  .editor-header {
+    flex-direction: column;
+    align-items: stretch;
+    gap: 10px;
+    padding: 12px;
+  }
+
+  .editor-title {
+    font-size: 16px;
+  }
+
+  .editor-controls {
+    width: 100%;
+    gap: 8px;
+  }
+
+  .editor-controls label {
+    flex: 1 1 140px;
+  }
+
+  .editor-controls select,
+  .editor-controls input,
+  .editor-controls button {
+    max-width: 100%;
+  }
+
+  .editor-main {
+    padding: 6px;
   }
 }
 
diff --git a/css/game.css b/css/game.css
index 09266fe0..5ffd3c83 100644
--- a/css/game.css
+++ b/css/game.css
@@ -90,7 +90,11 @@ canvas {
 }
 
 .game_container.small > .arrow_l {
-    zoom: 0.6
+    zoom: 0.6;
+    padding-left: 10px;
+    padding-right: 10px;
+    margin-left: -10px;
+    margin-right: -10px;
 }
 
 .arrow_r {
@@ -102,7 +106,11 @@ canvas {
 }
 
 .game_container.small > .arrow_r {
-    zoom: 0.6
+    zoom: 0.6;
+    padding-left: 10px;
+    padding-right: 10px;
+    margin-left: -10px;
+    margin-right: -10px;
 }
 
 /* style level selection dropdowns */
@@ -147,414 +155,700 @@ canvas {
     font-size: 10px;
 }
 
-.control-panel {
-    position: absolute;
-    top: 8px;
-    width: 240px;
-    max-height: calc(100vh - 16px);
-    padding: 10px 12px;
-    color: #e7e7e7;
-    background: rgba(10, 12, 18, 0.85);
-    border: 1px solid rgba(255, 255, 255, 0.15);
-    border-radius: 8px;
-    box-shadow: 0 8px 18px rgba(0, 0, 0, 0.35);
-    overflow-x: hidden;
-    overflow-y: auto;
-    z-index: 6;
-    box-sizing: border-box;
+#levelSelects,
+#levelName,
+#levelPrevButton,
+#levelNextButton {
+    position: relative;
+    z-index: 8;
 }
 
-.control-panel.left {
-    left: 8px;
+#levelPrevButton:focus-visible,
+#levelNextButton:focus-visible {
+    outline: 2px solid #0f0;
+    outline-offset: 3px;
 }
 
-.control-panel.right {
-    right: 8px;
+.midi-sequencer {
+    position: fixed;
+    inset: 8px;
+    z-index: 9;
+    display: grid;
+    grid-template-rows: auto minmax(0, 1fr);
+    gap: 8px;
+    color: #e9eef2;
+    font-family: Arial, Helvetica, sans-serif;
+    pointer-events: none;
 }
 
-.control-panel * {
-    overflow: visible;
+.midi-sequencer *,
+.midi-sequencer *::before,
+.midi-sequencer *::after {
     box-sizing: border-box;
-    max-width: 100%;
 }
 
-.control-panel summary {
-    list-style: none;
-}
-
-.control-panel summary::-webkit-details-marker {
-    display: none;
+.midi-transport,
+.midi-region {
+    pointer-events: auto;
+    background: rgba(9, 12, 16, 0.88);
+    border: 1px solid rgba(185, 207, 213, 0.22);
+    border-radius: 8px;
+    box-shadow: 0 12px 26px rgba(0, 0, 0, 0.34);
+    backdrop-filter: blur(10px);
 }
 
-body.midi-disabled #controlRight {
-    display: none;
+.midi-transport {
+    display: grid;
+    grid-template-columns: auto auto minmax(120px, 1fr) minmax(120px, 1fr) 86px 72px minmax(120px, 1fr) repeat(5, auto) minmax(140px, 1.2fr);
+    align-items: end;
+    gap: 8px;
+    min-height: 58px;
+    padding: 8px;
 }
 
-body.midi-disabled #controlLeft .panel-section:not(.panel-header) {
+.midi-hidden-file-input {
     display: none;
 }
 
-body.midi-disabled #controlLeft .panel-header > :not(.midi-enable-row) {
-    display: none;
+.midi-transport__title {
+    align-self: center;
+    white-space: nowrap;
+    font-size: 13px;
+    font-weight: 700;
+    letter-spacing: 0.04em;
+    text-transform: uppercase;
+    color: #d7fff5;
 }
 
-body.midi-disabled #controlLeft .panel-header {
-    border-bottom: 0;
-    margin-bottom: 0;
-    padding-bottom: 0;
+.midi-workspace-grid {
+    display: grid;
+    grid-template-columns: minmax(220px, 0.85fr) minmax(280px, 1.15fr) minmax(260px, 0.95fr);
+    grid-template-rows: minmax(0, 1fr) auto;
+    gap: 8px;
+    min-height: 0;
 }
 
-body.midi-disabled #controlLeft .tab-panel {
-    display: none;
+.midi-region {
+    min-width: 0;
+    min-height: 0;
+    padding: 10px;
+    overflow: hidden;
 }
 
-body.midi-disabled #controlLeft {
-    width: auto;
-    height: auto;
-    max-height: none;
-    padding: 10px 12px;
-    min-width: 0;
+.midi-region__header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 8px;
+    min-height: 28px;
+    margin-bottom: 8px;
 }
 
-body.midi-disabled #controlLeft.control-panel.collapsed {
-    width: auto;
-    padding: 10px 12px;
+.midi-region__header--compact {
+    min-height: 24px;
+    margin-bottom: 6px;
 }
 
-body.portrait-small .control-panel {
-    max-height: 40vh;
+.midi-region__header h2,
+.midi-inspector-group h3 {
+    margin: 0;
+    color: #d7fff5;
+    letter-spacing: 0.04em;
+    text-transform: uppercase;
 }
 
-.panel-section {
-    margin-bottom: 12px;
-    padding-bottom: 10px;
-    border-bottom: 1px solid rgba(255, 255, 255, 0.08);
+.midi-region__header h2 {
+    font-size: 12px;
 }
 
-.panel-section:last-child {
-    margin-bottom: 0;
-    padding-bottom: 0;
-    border-bottom: 0;
+.midi-inspector-group h3 {
+    font-size: 11px;
+    color: #9fc7d1;
 }
 
-.panel-title {
+.midi-field {
     display: flex;
     align-items: center;
-    justify-content: space-between;
-    gap: 8px;
-    width: 100%;
+    gap: 6px;
     min-width: 0;
-    flex-wrap: nowrap;
-    font-size: 12px;
-    letter-spacing: 0.08em;
-    text-transform: uppercase;
-    color: #9fd6ff;
-    margin-bottom: 6px;
+    font-size: 11px;
+    color: rgba(233, 238, 242, 0.8);
 }
 
-.panel-toggle {
-    cursor: pointer;
+.midi-field--stacked {
+    flex-direction: column;
+    align-items: stretch;
+    gap: 4px;
+    margin-bottom: 8px;
 }
 
-.panel-title-row {
-    display: flex;
+.midi-field--toggle {
     align-items: center;
-    justify-content: flex-start;
-    gap: 8px;
-    flex: 1;
-    width: 100%;
+}
+
+.midi-field--compact {
     min-width: 0;
-    flex-wrap: nowrap;
 }
 
-.panel-title-text {
-    flex: 1 1 auto;
-    min-width: 6ch;
+.midi-field span {
     white-space: nowrap;
     overflow: hidden;
     text-overflow: ellipsis;
-    color: inherit;
 }
 
-.panel-title-toggle {
-    display: inline-flex;
-    align-items: center;
-    gap: 6px;
-    font-size: 10px;
-    text-transform: none;
-    letter-spacing: 0.04em;
-    color: rgba(255, 255, 255, 0.7);
-    flex: 0 0 auto;
-    margin-left: auto;
-    white-space: nowrap;
-    width: auto;
+.midi-sequencer input,
+.midi-sequencer select,
+.midi-sequencer button {
+    min-width: 0;
+    min-height: 30px;
+    border: 1px solid rgba(210, 228, 232, 0.26);
+    border-radius: 6px;
+    background: rgba(19, 24, 30, 0.94);
+    color: #f7fbfc;
+    font-size: 12px;
+    letter-spacing: 0;
+}
+
+.midi-sequencer input,
+.midi-sequencer select {
+    width: 100%;
+    padding: 4px 6px;
+    user-select: text;
 }
 
-.control-panel .panel-title-toggle {
-    width: auto;
+.midi-sequencer input[type="checkbox"] {
+    width: 16px;
+    min-width: 16px;
+    height: 16px;
+    min-height: 16px;
+    padding: 0;
 }
 
-.panel-row-wide {
-    font-size: 9px;
-    line-height: 1.1;
-    justify-content: flex-start;
-    white-space: nowrap;
-    max-width: 100%;
-    overflow: hidden;
+.midi-sequencer button {
+    padding: 4px 10px;
+    cursor: pointer;
+    color: #d7fff5;
 }
 
-.panel-row-wide > span {
-    display: block;
-    width: 100%;
-    max-width: 100%;
-    overflow: hidden;
-    text-overflow: ellipsis;
+.midi-sequencer button:hover,
+.midi-source-row:hover,
+.midi-track-row:hover,
+.midi-clip-row:hover {
+    border-color: rgba(134, 245, 216, 0.62);
+    background: rgba(28, 42, 44, 0.96);
+}
+
+.midi-sequencer button:focus-visible,
+.midi-sequencer input:focus-visible,
+.midi-sequencer select:focus-visible,
+.midi-source-list:focus-visible,
+.midi-track-list:focus-visible,
+.midi-clip-list:focus-visible,
+.midi-source-row:focus-visible,
+.midi-track-row:focus-visible,
+.midi-clip-row:focus-visible {
+    outline: 2px solid rgba(134, 245, 216, 0.84);
+    outline-offset: 2px;
 }
 
-.control-panel.collapsed {
-    width: 64px;
-    padding: 10px 6px;
+.midi-status,
+.midi-error {
+    align-self: center;
+    min-width: 0;
+    font-size: 11px;
+    line-height: 1.25;
+}
+
+.midi-status {
+    color: rgba(233, 238, 242, 0.82);
     overflow: hidden;
-    height: auto;
-    max-height: none;
+    text-overflow: ellipsis;
+    white-space: nowrap;
 }
 
-.control-panel.collapsed .panel-section:not(.panel-header) {
+.midi-error {
+    grid-column: 1 / -1;
     display: none;
+    color: #ffb4a8;
+    line-height: 1.3;
+    overflow: visible;
+    overflow-wrap: anywhere;
+    white-space: normal;
 }
 
-.control-panel.collapsed .panel-header {
-    border-bottom: 0;
-    margin-bottom: 0;
-    padding-bottom: 0;
-    text-align: center;
+.midi-error:not(:empty) {
+    display: block;
 }
 
-.panel-row {
+.midi-filter-row,
+.midi-assignment-row,
+.midi-inline-fields,
+.midi-button-row,
+.midi-toggle-row {
     display: flex;
     align-items: center;
-    justify-content: space-between;
     gap: 8px;
-    font-size: 12px;
-    margin-bottom: 6px;
     min-width: 0;
-    flex-wrap: nowrap;
 }
 
-.panel-row > span {
-    flex: 1;
-    min-width: 0;
-    white-space: nowrap;
-    overflow: hidden;
-    text-overflow: ellipsis;
+.midi-filter-row {
+    margin-bottom: 8px;
 }
 
-.panel-row > .range-input,
-.panel-row > .input-pair {
-    flex: 1;
-    min-width: 0;
+.midi-inline-fields {
+    margin-bottom: 8px;
 }
 
-.panel-row > input,
-.panel-row > select,
-.panel-row > button,
-.panel-row > .axis-toggle {
-    flex-shrink: 0;
+.midi-inline-fields > .midi-field {
+    flex: 1 1 0;
 }
 
-#midiIoSection .panel-row > span {
+.midi-inline-fields > button {
     flex: 0 0 auto;
-    max-width: 45%;
+    align-self: end;
 }
 
-#midiIoSection .panel-row > select {
-    flex: 1 1 0;
-    min-width: 0;
-}
-
-details.panel-section > summary.panel-title {
-    cursor: pointer;
-    width: 100%;
-    min-width: 0;
+.midi-button-row {
+    flex-wrap: wrap;
 }
 
-.panel-tabs {
-    padding-bottom: 6px;
+.midi-toggle-row {
+    flex-wrap: wrap;
+    font-size: 11px;
 }
 
-.range-row {
+.midi-toggle-row label {
+    display: inline-flex;
     align-items: center;
+    gap: 5px;
 }
 
-.range-input {
+.midi-source-list,
+.midi-track-list,
+.midi-clip-list {
     display: flex;
-    align-items: center;
+    flex-direction: column;
     gap: 6px;
-    flex: 1;
-    min-width: 120px;
+    overflow-x: hidden;
+    overflow-y: auto;
 }
 
-.range-input input[type="range"] {
-    flex: 1;
-    min-width: 90px;
+.midi-source-list {
+    max-height: calc(100% - 102px);
 }
 
-.range-label {
-    min-width: 28px;
-    font-size: 10px;
-    color: rgba(255, 255, 255, 0.6);
-    text-align: center;
+.midi-track-list {
+    max-height: 32%;
+    margin-bottom: 8px;
 }
 
-.axis-toggle {
+.midi-track-workspace {
     display: flex;
-    align-items: center;
-    gap: 6px;
+    flex-direction: column;
+    min-height: 0;
+    overflow: hidden;
 }
 
-.axis-checkbox {
-    display: inline-flex;
-    align-items: center;
-    gap: 4px;
-    font-size: 11px;
+.midi-clip-library {
+    display: flex;
+    flex-direction: column;
+    min-height: 0;
+    margin-bottom: 8px;
 }
 
-.axis-toggle select {
-    min-width: 48px;
+.midi-clip-list {
+    min-height: 0;
+    max-height: 180px;
 }
 
-.input-pair {
-    display: flex;
-    align-items: center;
-    gap: 6px;
+.midi-source-row,
+.midi-track-row,
+.midi-clip-row {
+    display: grid;
+    width: 100%;
+    min-height: 44px;
+    padding: 7px 8px;
+    border: 1px solid rgba(210, 228, 232, 0.14);
+    border-radius: 6px;
+    background: rgba(18, 23, 28, 0.86);
+    color: inherit;
+    text-align: left;
+    cursor: pointer;
 }
 
-.input-compact {
-    width: 56px;
-    min-width: 56px;
+.midi-source-row {
+    grid-template-columns: minmax(0, 1fr) auto auto auto;
+    gap: 4px 8px;
 }
 
-.input-mini {
-    width: 44px;
-    min-width: 44px;
+.midi-clip-row {
+    min-height: 40px;
 }
 
-.input-align-right {
-    text-align: right;
+.midi-source-row.is-selected,
+.midi-track-row.is-selected,
+.midi-clip-row.is-selected {
+    border-color: rgba(134, 245, 216, 0.72);
+    background: rgba(26, 49, 49, 0.95);
 }
 
-.control-panel label {
-    width: 100%;
+.midi-source-row.is-disabled {
+    opacity: 0.58;
+}
+
+.midi-source-row.has-conflict {
+    border-color: rgba(255, 197, 112, 0.56);
 }
 
-.control-panel input:not([type="checkbox"]):not([type="radio"]),
-.control-panel select,
-.control-panel button {
+.midi-source-row.is-changed {
+    background: rgba(22, 31, 34, 0.9);
+}
+
+.midi-source-row__label,
+.midi-track-row__label,
+.midi-clip-row__label {
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
     font-size: 12px;
-    background: rgba(20, 22, 30, 0.9);
-    color: #fff;
-    border: 1px solid rgba(255, 255, 255, 0.2);
-    border-radius: 4px;
-    padding: 2px 6px;
-    min-width: 80px;
-    user-select: text;
+    color: #f7fbfc;
 }
 
-.control-panel input[type="checkbox"],
-.control-panel input[type="radio"] {
+.midi-source-row__meta,
+.midi-track-row__meta,
+.midi-clip-row__meta {
+    grid-column: 1 / -1;
     min-width: 0;
-    width: 14px;
-    height: 14px;
-    padding: 0;
-    margin: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    font-size: 10px;
+    color: rgba(233, 238, 242, 0.62);
 }
 
-.control-panel input[type="range"] {
-    padding: 0;
-    min-width: 120px;
+.midi-conflict-badge {
+    align-self: start;
+    min-width: 20px;
+    height: 20px;
+    padding: 2px 5px;
+    border-radius: 999px;
+    background: rgba(255, 190, 92, 0.18);
+    color: #ffd79a;
+    font-size: 10px;
+    line-height: 16px;
+    text-align: center;
 }
 
-.control-panel .input-compact {
-    width: 56px;
-    min-width: 56px;
+.midi-pill {
+    align-self: start;
+    min-width: 48px;
+    padding: 2px 6px;
+    border-radius: 999px;
+    background: rgba(134, 245, 216, 0.12);
+    color: #bffced;
+    font-size: 10px;
+    text-align: center;
+    text-transform: uppercase;
 }
 
-.control-panel .input-mini {
-    width: 44px;
-    min-width: 44px;
+.midi-pill--changed {
+    background: rgba(138, 171, 255, 0.16);
+    color: #cad6ff;
 }
 
-.control-panel button {
-    width: 100%;
-    margin-top: 6px;
-    cursor: pointer;
+.midi-selection-summary {
+    min-height: 54px;
+    margin: 8px 0;
+    padding: 8px;
+    border: 1px solid rgba(210, 228, 232, 0.14);
+    border-radius: 6px;
+    color: rgba(233, 238, 242, 0.74);
+    font-size: 12px;
+    line-height: 1.35;
+    overflow-y: auto;
 }
 
-.control-panel .button-danger {
-    background: rgba(70, 20, 20, 0.9);
-    border-color: rgba(255, 120, 120, 0.6);
-    color: #ffd6d6;
+.midi-conflict-summary {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+    min-height: 34px;
+    margin: 0 0 8px;
+    padding: 7px 8px;
+    border: 1px solid rgba(210, 228, 232, 0.14);
+    border-radius: 6px;
+    color: rgba(233, 238, 242, 0.68);
+    font-size: 11px;
+    line-height: 1.3;
+}
+
+.midi-conflict-summary.has-conflict {
+    border-color: rgba(255, 197, 112, 0.5);
+    color: #ffd79a;
+}
+
+.midi-conflict-summary__item {
+    min-width: 0;
+    overflow-wrap: anywhere;
+}
+
+.midi-conflict-summary__item[data-severity="error"] {
+    color: #ffb4a8;
+}
+
+.midi-learn-panel {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) auto;
+    gap: 8px;
+    align-items: center;
+    min-height: 38px;
+    margin: 0 0 8px;
+    padding: 7px 8px;
+    border: 1px solid rgba(134, 245, 216, 0.18);
+    border-radius: 6px;
+    background: rgba(14, 21, 25, 0.78);
 }
 
-.control-panel .button-compact {
-    width: 25%;
-    min-width: 70px;
-    margin-right: auto;
+.midi-learn-panel.is-active {
+    border-color: rgba(134, 245, 216, 0.62);
+    background: rgba(22, 44, 43, 0.86);
 }
 
-.panel-error {
-    color: #ff7b7b;
+.midi-learn-status {
+    min-width: 0;
+    overflow-wrap: anywhere;
+    color: rgba(233, 238, 242, 0.72);
     font-size: 11px;
-    margin-top: 6px;
+    line-height: 1.25;
 }
 
-.tabs {
+.midi-automation-list {
     display: flex;
+    flex-direction: column;
     gap: 6px;
-    margin-bottom: 8px;
+    min-width: 0;
 }
 
-.tab-button {
-    flex: 1;
-    padding: 4px 6px;
-    border-radius: 4px;
-    border: 1px solid rgba(255, 255, 255, 0.2);
-    background: rgba(28, 30, 42, 0.9);
-    color: #cfd8e3;
-    cursor: pointer;
+.midi-automation-row {
+    display: grid;
+    grid-template-columns: auto minmax(72px, 1fr) minmax(48px, 0.7fr) minmax(52px, 0.7fr) minmax(52px, 0.7fr) minmax(52px, 0.7fr) minmax(52px, 0.7fr) minmax(52px, 0.7fr) auto;
+    gap: 6px;
+    align-items: end;
+    min-width: 0;
+    padding: 6px;
+    border: 1px solid rgba(210, 228, 232, 0.14);
+    border-radius: 6px;
+    background: rgba(18, 23, 28, 0.72);
 }
 
-.tab-button.active {
-    background: rgba(70, 120, 180, 0.85);
-    color: #fff;
+.midi-automation-row .midi-field {
+    min-width: 0;
 }
 
-.tab-panel {
-    display: none;
+.midi-inspector {
+    overflow-y: auto;
 }
 
-.tab-panel.active {
-    display: block;
+.midi-inspector-group {
+    padding-top: 8px;
+    margin-top: 8px;
+    border-top: 1px solid rgba(210, 228, 232, 0.12);
 }
 
-@media (max-width: 960px) {
-    .control-panel {
-        width: 200px;
-        font-size: 11px;
+.midi-inspector-group:first-of-type {
+    padding-top: 0;
+    margin-top: 0;
+    border-top: 0;
+}
+
+.midi-step-grid {
+    display: grid;
+    grid-template-columns: repeat(4, minmax(0, 1fr));
+    gap: 6px;
+    min-width: 0;
+}
+
+.midi-step-cell {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+    gap: 4px;
+    min-width: 0;
+    padding: 6px;
+    border: 1px solid rgba(210, 228, 232, 0.14);
+    border-radius: 6px;
+    background: rgba(18, 23, 28, 0.76);
+}
+
+.midi-step-cell__index {
+    grid-column: 1 / -1;
+    color: rgba(233, 238, 242, 0.68);
+    font-size: 10px;
+}
+
+.midi-step-cell label {
+    display: grid;
+    min-width: 0;
+    gap: 2px;
+    color: rgba(233, 238, 242, 0.68);
+    font-size: 10px;
+}
+
+.midi-step-cell input[type="checkbox"] {
+    justify-self: start;
+}
+
+.midi-step-cell input,
+.midi-step-cell select,
+.midi-step-cell button {
+    min-height: 26px;
+    padding: 2px 4px;
+    font-size: 11px;
+}
+
+.midi-output-status {
+    grid-column: 1 / -1;
+    display: grid;
+    grid-template-columns: minmax(180px, 0.35fr) minmax(0, 1fr);
+    gap: 10px;
+    min-height: 54px;
+    max-height: 88px;
+    font-size: 11px;
+    color: rgba(233, 238, 242, 0.78);
+}
+
+.midi-output-log {
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
+body.midi-disabled .midi-region:not(.midi-output-status) {
+    opacity: 0.74;
+}
+
+body.midi-disabled .midi-region button,
+body.midi-disabled .midi-region input,
+body.midi-disabled .midi-region select {
+    border-color: rgba(210, 228, 232, 0.16);
+}
+
+@media (max-width: 1080px) {
+    .midi-transport {
+        grid-template-columns: repeat(4, minmax(0, 1fr));
+    }
+
+    .midi-transport__title,
+    .midi-status,
+    .midi-error {
+        grid-column: 1 / -1;
+    }
+
+    .midi-workspace-grid {
+        grid-template-columns: minmax(190px, 0.8fr) minmax(240px, 1fr) minmax(230px, 0.9fr);
+    }
+}
+
+@media (max-width: 820px) {
+    .midi-sequencer {
+        position: absolute;
+        inset: 6px;
+        bottom: auto;
+        height: auto;
+        min-height: calc(100vh - 12px);
+        grid-template-rows: auto auto;
+        align-content: start;
+        overflow-y: visible;
+        pointer-events: auto;
+    }
+
+    .midi-transport,
+    .midi-workspace-grid {
+        grid-template-columns: 1fr 1fr;
+    }
+
+    .midi-transport__title,
+    .midi-status,
+    .midi-error {
+        grid-column: 1 / -1;
+    }
+
+    .midi-workspace-grid {
+        grid-template-rows: auto;
+        min-height: auto;
+    }
+
+    .midi-region,
+    .midi-output-status {
+        max-height: none;
+    }
+
+    .midi-track-workspace,
+    .midi-inspector {
+        overflow: visible;
+    }
+
+    .midi-source-browser,
+    .midi-track-workspace,
+    .midi-inspector,
+    .midi-output-status {
+        grid-column: 1 / -1;
+    }
+
+    .midi-source-list,
+    .midi-track-list,
+    .midi-clip-list {
+        max-height: 220px;
+    }
+
+    .midi-output-log {
+        overflow: visible;
+        overflow-wrap: anywhere;
+        text-overflow: clip;
+        white-space: normal;
+    }
+
+    .midi-step-grid {
+        grid-template-columns: repeat(2, minmax(0, 1fr));
+    }
+
+    .midi-automation-row {
+        grid-template-columns: auto minmax(80px, 1fr) minmax(56px, 0.8fr) minmax(56px, 0.8fr) minmax(56px, 0.8fr) minmax(56px, 0.8fr) minmax(56px, 0.8fr) minmax(56px, 0.8fr) auto;
+    }
+
+    .midi-learn-panel {
+        grid-template-columns: 1fr;
     }
 }
 
-@media (max-width: 720px) {
-    .control-panel.left {
-        left: 4px;
-        top: auto;
-        bottom: 4px;
-        max-height: 45vh;
+@media (max-width: 520px) {
+    .midi-transport,
+    .midi-workspace-grid,
+    .midi-output-status,
+    .midi-inline-fields,
+    .midi-assignment-row,
+    .midi-filter-row,
+    .midi-automation-row,
+    .midi-button-row {
+        grid-template-columns: 1fr;
+        flex-direction: column;
+        align-items: stretch;
+    }
+
+    .midi-step-grid {
+        grid-template-columns: 1fr;
+    }
+
+    .midi-automation-row {
+        grid-template-columns: 1fr 1fr;
+        align-items: stretch;
     }
-    .control-panel.right {
-        right: 4px;
-        top: 4px;
-        max-height: 45vh;
+
+    .midi-sequencer button,
+    .midi-sequencer input,
+    .midi-sequencer select {
+        min-height: 34px;
     }
 }
 
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000..ecf9146a
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,100 @@
+# Documentation Index
+
+This directory is the source of truth for project documentation. Completed
+roadmap phases live in git history; active roadmap work is in
+[`roadmap.md`](roadmap.md).
+
+## Canonical User And Developer Docs
+
+These files describe current behavior and should be kept in sync with code:
+
+- [`usage.md`](usage.md): local browser startup, editor entry point, E2E harness
+  entry point.
+- [`TESTING.md`](TESTING.md): unit/static/benchmark/Playwright test workflow.
+- [`playwright-tests.md`](playwright-tests.md): Playwright server setup,
+  disposable visual capture tooling, and probe usage.
+- [`e2e-state.md`](e2e-state.md): `window.__E2E__` game/runtime harness API.
+- [`e2e-editor-state.md`](e2e-editor-state.md): editor-specific E2E state.
+- [`ci.md`](ci.md): current GitHub Actions gate order.
+- [`release-readiness.md`](release-readiness.md): validated release checklist.
+- [`config.md`](config.md): `config.json`, runtime profiles, and bench profiles.
+- [`analytics.md`](analytics.md): local opt-in analytics controls.
+- [`keybindings-design.md`](keybindings-design.md): keyboard binding format.
+- [`gamepad-bindings.md`](gamepad-bindings.md): gamepad binding format.
+- [`midi-ui.md`](midi-ui.md): current MIDI UI controls and persistence.
+- [`midi-mapping.md`](midi-mapping.md): default MIDI mapping file reference.
+- [`procgen.md`](procgen.md): current procgen runtime behavior and validation.
+- [`performance-benchmarks.md`](performance-benchmarks.md): runtime benchmark
+  modes and scripts.
+- [`offline-tools.md`](offline-tools.md): Node asset and pack tooling.
+- [`exporting-sprites.md`](exporting-sprites.md): quick export/patch workflow.
+- [`levelpacks.md`](levelpacks.md): level pack folder layout.
+- [`replays.md`](replays.md): replay command format.
+- [`architecture-internals.md`](architecture-internals.md): renderer, history,
+  MCP, and profile internals.
+
+## Level Editor Docs
+
+The level editor docs are canonical for the current classic-subset editor unless
+the file explicitly says it is backlog:
+
+- [`level-editor/workflows.md`](level-editor/workflows.md)
+- [`level-editor/audit.md`](level-editor/audit.md)
+- [`level-editor/classic-subset-contract.md`](level-editor/classic-subset-contract.md)
+- [`level-editor/design-overview.md`](level-editor/design-overview.md)
+- [`level-editor/data-model.md`](level-editor/data-model.md)
+- [`level-editor/ui-and-tools.md`](level-editor/ui-and-tools.md)
+- [`level-editor/ui-spec.md`](level-editor/ui-spec.md)
+- [`level-editor/runtime-preview.md`](level-editor/runtime-preview.md)
+- [`level-editor/history.md`](level-editor/history.md)
+- [`level-editor/remaining.md`](level-editor/remaining.md): out-of-scope backlog.
+- [`level-editor/neolemmix-expansion.md`](level-editor/neolemmix-expansion.md):
+  NeoLemmix expansion backlog.
+
+## MCP Docs
+
+The current MCP entry points are:
+
+- [`mcp/README.md`](mcp/README.md): server usage, surfaces, tool naming, smoke
+  checklist.
+- [`mcp/protocol-v2.md`](mcp/protocol-v2.md): current compact protocol defaults.
+- [`mcp/editor-apply.md`](mcp/editor-apply.md): shipped `editor_apply` contract.
+- [`mcp/call-examples.md`](mcp/call-examples.md): short-name call examples.
+- [`mcp/publishing.md`](mcp/publishing.md): MCPB packaging and registry notes.
+- [`mcp/protocol-mappings.json`](mcp/protocol-mappings.json): protocol mapping
+  metadata consumed by code/tests.
+- [`mcp/client-compatibility.json`](mcp/client-compatibility.json): host
+  compatibility matrix.
+- `mcp/config-examples/*`: checked client config snippets.
+
+The `mcp/lemmings-mcp-*-memresources.*` files are retained as historical design
+and schema reference notes. Prefer the current README/protocol docs for shipped
+behavior.
+
+## File Format And Asset References
+
+These are reference material, not product roadmap docs:
+
+- [`compression-format.md`](compression-format.md)
+- [`level-file-format.md`](level-file-format.md)
+- [`nl-file-format.md`](nl-file-format.md)
+- [`nl-objects.md`](nl-objects.md)
+- [`nl-skills.md`](nl-skills.md)
+- [`nl-pack-toolkit.md`](nl-pack-toolkit.md)
+- Every file under [`camanis/`](camanis/)
+- [`reading-list/particle-handling.md`](reading-list/particle-handling.md)
+
+## Historical Source Notes
+
+These are useful implementation references, but they are not authoritative for
+current JavaScript behavior:
+
+- Every file under [`port-info/`](port-info/)
+- [`webmidi-evaluation.md`](webmidi-evaluation.md)
+
+## Test Status Reports
+
+The repo no longer keeps stale broken/fixable/incoherent test reports. Current
+test status is the command output from `npm test`, Playwright commands, and CI.
+[`excluded-tests.md`](excluded-tests.md) is retained only to document deliberate
+manual exclusions; it currently states that none are excluded.
diff --git a/docs/TESTING.md b/docs/TESTING.md
index cc0d9a63..e8aa4d91 100644
--- a/docs/TESTING.md
+++ b/docs/TESTING.md
@@ -6,33 +6,219 @@ common subsets of the suite:
 ```bash
 npm test                # runs all tests
 npm run test-core       # core game logic
-npm run test-bench      # performance benchmarks
-npm run bench-performance # standalone bench (Playwright + E2E harness)
-npm run bench-history   # history stress test (Playwright + E2E harness)
+npm run test-bench      # bench-related unit/integration tests (Mocha only)
+npm run test-bench-smoke # browser benchmark smoke gate (Playwright + E2E harness)
+npm run bench-smoke     # fast benchmark smoke gate (short dev-loop default)
+npm run bench-performance # standalone perf bench (smoke profile by default)
+npm run bench-performance-smoke # explicit perf smoke profile
+npm run bench-history   # history stress bench (smoke profile by default)
+npm run bench-history-smoke # explicit history smoke profile
+npm run bench-long-session # long-session benchmark gate (smoke profile by default)
+npm run bench-long-session-smoke # explicit long-session smoke profile
+npm run bench-performance-soak # long perf soak run (explicit opt-in)
+npm run bench-history-soak # long history soak run (explicit opt-in)
+npm run bench-long-session-soak # long replay/memory/event-queue soak run
 npm run test-workflow   # GitHub workflow helpers
 npm run test-tools      # command line tools
 npm run test-offline-tools # offline asset tooling
 npm run test-editor     # editor-related tests
+npm run test:changed    # infer the smallest safe Mocha subset from git changes
 npm run coverage-editor # 100% coverage for editor modules
 npm run test-mcp-smoke  # MCP stdio smoke test (requires start-https)
+npm run typecheck:critical # targeted checkJs guard for runtime-critical modules
+npm run release-readiness # release checklist gate (strict by default)
 ```
 Categories map to the glob patterns defined in `scripts/runTests.js`.
+`npm run test:changed` resolves its comparison base in this order: explicit
+`--base=<ref>`, current branch upstream, `origin/HEAD`, then known default
+branch names. Add `--print-selection` (or `--dry-run`) to print the resolved
+base ref, changed files, inferred categories, and Mocha args without running
+guards or tests.
+The maintained subset scripts (`test-core`, `test-bench-unit`,
+`test-workflow`, `test-tools`, `test-offline-tools`, and `test-editor`) all go
+through `scripts/runTests.js`, so they share the same runtime-global guard,
+critical typecheck guard, and runtime budget reporting as `npm test`.
 
-Tests that require significant manual setup or large downloads are documented in
-[`excluded-tests.md`](excluded-tests.md). They are skipped in continuous
-integration.
+Tests that require significant manual setup or large downloads belong in
+[`excluded-tests.md`](excluded-tests.md). No tests are currently excluded.
 
 The tests require no special environment variables. A minimal `lemmings` object
 is created and temporary files are written under your operating system's temp
 directory.
 
+## Benchmark profiles
+
+Benchmark scripts default to short smoke settings so local perf checks stay
+within a quick dev-loop budget. Use explicit soak mode for long runs:
+
+```bash
+npm run bench-performance -- --soak
+npm run bench-history -- --soak
+npm run bench-smoke -- --soak
+```
+
+`test-bench` and `bench-*` intentionally have different semantics:
+
+- `test-bench`: runs deterministic Mocha tests under `test/*bench*.test.js`.
+- `bench-*`: runs live browser benchmarks (requires local HTTPS server and
+  browser automation support).
+
+`bench-history` is the replay-invariant guardrail for compression/rewind work:
+
+- It runs random seek/replay probes and fails on replay-hash divergence
+  (`HISTORY_REQUIRE_REPLAY_PARITY`, defaults to `true`).
+- It fails when bounded history retention is not enabled
+  (`HISTORY_REQUIRE_BOUNDED_RETENTION`, defaults to `true`).
+- Non-smoke profiles also require cold compaction activity
+  (`HISTORY_REQUIRE_COLD_COMPACTION`, defaults to `true` for `default`/`soak`).
+
+`bench-hotpaths` now reports percentile and allocation diagnostics per section:
+
+- `avgMs`, `p50Ms`, `p95Ms`, `p99Ms`, `worstMs`
+- `allocBytesAvg`, `allocBytesP95`, `allocBytesWorst`
+
+For render experiments, use canonical query flags in non-default runs and keep
+rollback ready:
+
+- `offscreenPresent=true`: requests the Canvas2D staging plus `drawImage`
+  present-path experiment when supported.
+- `workerOffscreen=true`: requests worker/offscreen path; runtime falls back
+  automatically when unsupported.
+
+Runtime diagnostics now expose capability matrix and rollout-flag snapshots
+through `window.__E2E__.getDiagnostics()` / `window.__E2E__.getState()`:
+
+- `capabilities.webMidi`, `capabilities.offscreenCanvas`,
+  `capabilities.imageBitmap`, `capabilities.worker`.
+- `capabilities.renderPaths` for deterministic fallback selection. Diagnostics
+  use `presentPathSupported`/`drawimage_present`.
+- `rolloutFlags` for staged rollout / emergency rollback state.
+
+Rollout and rollback query toggles:
+
+- `rollbackAll=1`: disables all high-risk rollout flags.
+- `rollbackRenderPresent=1`: disables offscreen/worker present-path experiments.
+- `rollbackHistoryCodec=1`: disables cold history compression/dedupe.
+
+`bench-long-session` enforces thresholds for:
+
+- replay-hash integrity
+- heap growth and heap churn proxies
+- sound-event queue ratio and queue-growth bounds
+- history span growth and trigger-count drift
+
+Release gates are defined in [`release-readiness.md`](release-readiness.md) and
+validated by `npm run release-readiness`. Override strictness via
+`LEMMINGS_RELEASE_READINESS_STRICT=false` when validating checklist structure
+without requiring all items checked.
+
+## Runtime profiles
+
+Runtime boot/query presets use these profile IDs:
+
+- `classic`
+- `midi`
+- `editor`
+- `e2e`
+- `perf`
+
+Legacy `profile=gameplay` links are normalized to `classic`.
+
+## Analytics controls
+
+Privacy-first analytics is opt-in and local-only by default. See
+[`analytics.md`](analytics.md) for consent defaults, event schema constraints,
+local buffer export/import, optional managed beacon settings, and hard/runtime
+kill switches.
+
 ## npm test workflow
 
-Run `npm run check-undefined` manually before `npm test` to verify no uninitialized references remain in the build. GitHub Actions performs the same checks on **Node 20** during the CI job after running `npm run lint`.
+Run `npm run check-undefined` before `npm test` to catch low-cost JS hygiene
+regressions early. GitHub Actions also runs `git diff --check` against the
+changed lines after `npm run format` to catch trailing-whitespace and EOF
+blank-line issues without a custom baseline.
+
+`npm test` now reports total runtime and supports optional guardrails for local
+suite budgets:
 
-To mirror the CI environment locally:
+- `LEMMINGS_TEST_ENFORCE_BUDGET=true`: fail when runtime budget is exceeded.
+- `LEMMINGS_TEST_BUDGET_MS=<ms>`: override the default 180000ms budget.
+- `npm run test:budget`: convenience wrapper with enforcement enabled.
+
+To cover the main CI static/test gates locally:
 
 ```bash
 npm run lint
+git diff --check origin/master...HEAD
+npm run check-undefined
 npm test
 ```
+
+## Playwright base URL overrides
+
+Playwright defaults to `https://localhost:8080`. Override the origin with
+`LEMMINGS_E2E_BASE_URL` when validating another same-machine or LAN URL:
+
+```powershell
+npm run test-e2e -- e2e/service-worker.spec.js
+$env:LEMMINGS_E2E_BASE_URL = "https://127.0.0.1:8080"
+npm run test-e2e -- e2e/service-worker.spec.js
+Remove-Item Env:\LEMMINGS_E2E_BASE_URL
+```
+
+The service-worker smoke asserts same-origin scope instead of literal localhost,
+so the same spec should pass for localhost and non-localhost origins served by
+the configured HTTPS server.
+
+## Visual capture smoke
+
+Disposable local screenshots are documented in
+[`playwright-tests.md`](playwright-tests.md). Start `npm run start-https` first
+when invoking the capture CLI directly:
+
+```bash
+npm run capture:e2e:midi
+npm run capture:e2e:editor
+npm run capture:e2e:procgen
+npm run capture:e2e:game-hud
+```
+
+Output stays under ignored `temp/e2e-captures/`.
+
+## Milestone checkpoint evidence
+
+Milestone work should leave a short, reproducible evidence note before issue
+closeout. Keep working artifacts under ignored `temp/` and commit only the code,
+tests, and durable docs needed by the feature.
+
+Use this compact format for each lane or issue group:
+
+```text
+Issues:
+Commands:
+Temp artifacts:
+GitHub closeout:
+Skipped checks:
+Unrelated failures:
+Follow-up risks:
+```
+
+The Capture matrix below is the standard milestone map for the current
+editor, procgen, solver, MIDI, and validation work. Run the narrow lane checks
+while a lane is in progress, then run the standard gate before final closeout.
+
+| Area | Issues | Capture matrix | Required checkpoint commands | Disposable evidence |
+| --- | --- | --- | --- | --- |
+| MIDI polish | #924-#928 | `midi-transport`, `midi-source-browser`, `midi-track-workspace`, `midi-clip-library`, `midi-inspector`, `midi-learn`, `midi-record`, `midi-output-status`; desktop/tablet/mobile when layout changes | `npm run test-e2e -- e2e/midi-ui.spec.js`; `npm run capture:e2e:midi -- --viewport=desktop --json`; `npm run capture:e2e:midi -- --viewport=tablet --json`; `npm run capture:e2e:midi -- --viewport=mobile --json` | `temp/e2e-captures/`, `temp/midi-lane-*.md` |
+| Editor productization | #929-#932 | states `shell`, `canvas-palette-inspector`, `validation`, `save-import-export`, `playtest`; desktop required, tablet/mobile when controls change | `npm run test-editor`; `npm run test-e2e:harness`; `npm run capture:e2e:editor -- --viewport=desktop --json` | `temp/e2e-captures/`, `temp/editor-lane-*.md` |
+| Procgen productization | #933-#938 | states `overview`, `frontier`, `newest-pieces`; desktop required for seed review, targeted mobile only for shell/layout changes | `npm run test-e2e -- e2e/procgen.spec.js`; `npm run capture:e2e:procgen -- --viewport=desktop --json`; `npm run bench-procgen-soak`; `npm run test-bench-unit` | `temp/e2e-captures/`, `temp/procgen-lane-*.md` |
+| Solver platform | #939-#949 | no standalone screenshot gate until a UI/editor advisory surface changes; capture editor advisory or solver failure surfaces only when they are user-visible | `npm test`; focused `test/solver*.test.js`; `npm run test-e2e:harness` when runtime adapters or editor advisory flows change; MCP checks after solver tools change | `temp/solver-lane-*.md`, optional `temp/solver-failures/` |
+| Validation and closeout | #950-#951 | capture docs and runner drift are checked by tests; do not create committed galleries or manifests | `npm run format`; `npm run check-undefined`; `npm run lint`; `npm run typecheck:critical`; `npm test`; `npm run test-bench-unit` | `temp/milestone-integration-*.md` |
+
+GitHub issue closeout comments should cite the commands that actually ran, any
+relevant ignored artifact paths, and any skipped checks with the concrete
+reason. Do not close an issue on visual captures alone when behavior changed;
+pair captures with a deterministic unit, harness, or E2E check where available.
+Keep capture output disposable: do not create committed galleries or manifests.
+Use `npm run release-readiness` only when the release checklist or release gate
+scripts change; it is not the issue closeout checklist.
diff --git a/docs/analytics.md b/docs/analytics.md
new file mode 100644
index 00000000..ab391f64
--- /dev/null
+++ b/docs/analytics.md
@@ -0,0 +1,81 @@
+# Privacy-First Analytics
+
+This project uses a privacy-first analytics model with an explicit opt-in
+consent default and a local-only event buffer.
+
+## Consent Defaults
+
+- Default state: analytics is disabled.
+- No cookies are required.
+- No device fingerprinting or cross-site identity is used.
+- Consent is stored locally in `localStorage` only:
+  - key: `lemmings.analytics.consent.v1`
+  - values: `granted` or `denied`
+
+Runtime query overrides:
+
+- `?analytics=1` enables consent for the session and stores `granted`.
+- `?analytics=0` (or `?analytics=off`) disables consent and stores `denied`.
+- `?analyticsOff=1` forces runtime disable regardless of consent.
+
+## Data Minimization
+
+Analytics events are schema-locked and low-cardinality:
+
+- `visitor.page_view`
+- `gameplay.level_select`
+- `gameplay.midi_toggle`
+- `gameplay.saved_level`
+- `editor.action`
+- `runtime.boot_error`
+
+Only bounded enum/boolean/integer fields are captured. Free-form text payloads
+and high-cardinality identifiers are intentionally excluded.
+
+## Local Ring Buffer
+
+Events are stored in a fixed-size in-memory ring buffer and mirrored to
+`localStorage`:
+
+- key: `lemmings.analytics.buffer.v1`
+- schema version: `1`
+- explicit export/import API for local workflows:
+  - `window.__LEMMINGS_ANALYTICS__.exportBuffer()`
+  - `window.__LEMMINGS_ANALYTICS__.importBuffer(data, { replace })`
+  - `window.__LEMMINGS_ANALYTICS__.clearBuffer()`
+
+This supports development telemetry with no backend service.
+
+## Optional Managed Beacon Path
+
+Managed beacon delivery is optional and disabled by default.
+
+Enable only when all conditions are met:
+
+1. consent is granted,
+2. a valid HTTPS endpoint is configured,
+3. managed beacon is explicitly requested.
+
+Runtime controls:
+
+- `?analyticsBeacon=1` requests managed beacon delivery.
+- `?analyticsSample=<0..1>` sets managed-beacon sampling.
+
+Endpoint sources:
+
+- runtime override (`__LEMMINGS_ANALYTICS_BEACON_ENDPOINT__`)
+- `<meta name="lemmings-analytics-endpoint" content="https://...">`
+
+## Kill Switches
+
+Hard-disable (deployment-wide):
+
+- `__LEMMINGS_ANALYTICS_HARD_DISABLED__ = true`
+- or `<meta name="lemmings-analytics" content="off">`
+
+Runtime disable:
+
+- `__LEMMINGS_ANALYTICS_DISABLED__ = true`
+- or query `?analyticsOff=1`
+
+Even when analytics code is present, these switches keep collection disabled.
diff --git a/docs/architecture-internals.md b/docs/architecture-internals.md
new file mode 100644
index 00000000..8be93fa2
--- /dev/null
+++ b/docs/architecture-internals.md
@@ -0,0 +1,82 @@
+# Architecture Internals
+
+This document is implementation-first guidance for the three subsystems that
+currently carry most runtime complexity: renderer, time travel/history, and MCP.
+
+## Renderer internals (`js/render/*`, `js/game/GameView.js`)
+
+### Pipeline and ownership
+- `Frame`: low-level RGBA + mask container used by decoded terrain/object frames.
+- `DisplayImage`: mutable world image buffer for a layer (game or HUD). Writes
+  happen here (`drawFrame`, rects, overlays), not in `Stage`.
+- `Stage`: presentation/compositing layer. It owns the visible canvas and copies
+  `DisplayImage` buffers into offscreen canvases, then onto the stage canvas.
+
+### Hot-path rules
+- Keep rendering Canvas2D-only.
+- Prefer typed-array writes (`Uint32Array`) in `DisplayImage`/`Frame` paths.
+- Use dirty-region updates (`markDirtyRect` / `consumeDirtyRects`) so
+  offscreen `putImageData` work is scoped to changed regions.
+- Avoid per-frame transient allocations:
+  - xBRZ/HQX resized variants are cached per frame/version/target size.
+  - stage context state writes (`globalAlpha`, `fillStyle`) are coalesced.
+
+### Safe extension points
+- Add new debug/perf overlays in `Stage.drawPerfOverlay`.
+- Add new sprite draw modes by extending `DisplayImage._blit` and reusing
+  `scaleNearest`/`scaleXbrz`/`scaleHqx` helpers.
+- If you mutate a `Frame`, preserve `_version` invalidation semantics so cached
+  scaled variants cannot go stale.
+
+## Time travel internals (`js/game/HistoryStore.js`, `js/game/TimeTravelController.js`)
+
+### Storage model
+- History is snapshot + delta based.
+- Deltas are grouped into fixed-size blocks to lower metadata overhead and speed
+  seeks over long sessions.
+- Cold blocks can be canonically encoded, deduplicated by hash, and optionally
+  compressed.
+- Idle ranges are tokenized as no-op spans to reduce repetitive growth.
+
+### Determinism guardrails
+- Replay integrity is verified through replay hashes over tick ranges.
+- Compression and block thaw/rehydration paths must preserve delta semantics.
+- Any new mutable game state must be represented in snapshot/delta extraction,
+  otherwise rewind/seek divergence is likely.
+
+### Practical change workflow
+- Update `HistoryStore` extraction/apply logic first.
+- Add or update `test/history-store.test.js` and
+  `test/time-travel-controller.test.js`.
+- Validate long-run memory behavior with `npm run bench-history`.
+
+## MCP internals (`mcp/*`, `js/app/e2eHarness.js`)
+
+### Surface split
+- Tool registration is split by surface modules:
+  - `mcp/tools/game.js`
+  - `mcp/tools/editor.js`
+  - `mcp/tools/interact.js`
+- Shared session/resource/watch infrastructure remains centralized.
+- Runtime routing is strict by enabled surfaces
+  (`LEMMINGS_MCP_SURFACES`) to prevent cross-surface leakage.
+
+### Contract and evolution
+- Tool names are short-first; only shipped underscore names are accepted.
+- Harness methods are the source of runtime behavior for tool handlers.
+- When adding a tool:
+  1. add harness capability,
+  2. add tool schema + handler,
+  3. add smoke/client tests,
+  4. update docs/examples to shipped names only.
+
+### Stability checks
+- Compatibility checks: `npm run check-mcp-clients`
+- Smoke checks: `npm run test-mcp-smoke`
+
+## Startup profiles and mode boundaries
+
+Runtime profiles (`classic`, `midi`, `editor`, `e2e`, `perf`) exist to avoid
+paying for subsystems that are not needed in a given mode. Legacy
+`profile=gameplay` URLs normalize to `classic`. Keep new mode-sensitive
+features profile-aware in `js/app/boot.js` and `js/game/GameView.js`.
diff --git a/docs/broken-tests.md b/docs/broken-tests.md
deleted file mode 100644
index daa82a97..00000000
--- a/docs/broken-tests.md
+++ /dev/null
@@ -1,93 +0,0 @@
-# Broken tests
-
-The following unit tests are currently failing and need additional investigation:
-
-- [`test/gametimer.test.js`](../test/gametimer.test.js) – the *pause/resume via visibilitychange stops ticks* and *catchupSpeedAdjust scales across repeated delays* cases do not yield the expected `speedFactor` when run with fake timers. Mocked `requestAnimationFrame` calls and changes to the timer logic were unable to match the test expectations.
-
-
-The following additional tests failed during the agent's review and could not be fixed:
-
-### Core tests
-- `test/action-systems.test.js` – *ActionDrowningSystem behavior - draw records death once frame >= 15*
-- `test/action-systems.test.js` – *ActionExplodingSystem behavior - clears ground and exits at frame 52*
-- `test/action-systems.test.js` – *ActionExplodingSystem behavior - process increments frameIndex and disables on first frame*
-- `test/action-systems.test.js` – *ActionMineSystem state handling - returns SHRUG when steel or arrow under mask*
-- `test/action-systems.test.js` – *ActionMineSystem state handling - increments y at frame 3 and falls without ground*
-- `test/action-systems.test.js` – *ActionMineSystem state handling - clears ground and continues when unobstructed*
-- `test/action-systems.test.js` – *Action Systems process() - ActionExplodingSystem clears mask and exits*
-- `test/action-systems.test.js` – *Action Systems process() - ActionFryingSystem burns then exits*
-- `test/action-systems.test.js` – *Action Systems process() - ActionExplodingSystem clears mask on first frame*
-- `test/bench-sequence-start.test.js` – *benchSequenceStart - computes extras and starts bench with first count*
-- `test/bench-tps.test.js` – *bench TPS - render shows queued frames and TPS in bench mode*
-- `test/bitreader.test.js` – *BitReader - reads across byte boundary and errors at EOF*
-- `test/displayimage.primitives.test.js` – *DisplayImage primitives - drawDashedRect draws dashed pattern*
-- `test/displayimage.primitives.test.js` – *DisplayImage primitives - drawVerticalLine and drawHorizontalLine write pixels*
-- `test/displayimage.test.js` – *DisplayImage drawing and scaling - drawVerticalLine clamps to bounds*
-- `test/displayimage.test.js` – *DisplayImage drawing and scaling - blits frames with nearest scaling*
-- `test/exportScripts.test.js` – *exportPanelSprite.js writes PNG*
-- `test/game.test.js` – *Game - timer tick triggers logic, game over check and rendering*
-- `test/gamegui.test.js` – *GameGui - setGuiDisplay attaches listeners and creates MiniMap*
-- `test/gamegui.test.js` – *GameGui - render draws digits and letters when flags set*
-- `test/gamegui.test.js` – *GameGui - mouse clicks adjust release rate and speed*
-- `test/gamegui.test.js` – *GameGui - drawSpeedChange and drawSelection trigger drawing*
-- `test/gamegui.test.js` – *GameGui - pauses and resumes with pause button*
-- `test/gamegui.test.js` – *GameGui - changes speed with fast-forward buttons*
-- `test/gamegui.test.js` – *GameGui - queues nuke command after confirmation*
-- `test/gamegui.test.js` – *GameGui - selects skills and dispatches command*
-- `test/gamegui.test.js` – *GameGui - renders minimap view*
-- `test/gametimer.test.js` – *GameTimer - pause/resume via visibilitychange stops ticks*
-- `test/gametimer.test.js` – *GameTimer - catchupSpeedAdjust scales across repeated delays*
-- `test/gamevictory.test.js` – *Game victory condition - emits GameResult on game end*
-- `test/gameview.applyquery.test.js` – *GameView.moveToLevel offsets - advances to next level within group*
-- `test/gameview.helpers.test.js` – *moveToLevel transitions - advances to next game type when past last group*
-- `test/gameview.test.js` – *GameView - calls updateStageSize when canvas is set*
-- `test/gameview.test.js` – *GameView - suspendWithColor fades and resumes timer*
-- `test/gameview.test.js` – *GameView - resetFade is called when loading a level*
-- `test/keyboardshortcuts.loop.test.js` – *KeyboardShortcuts _step loop - "before each" hook for "updates view when panning"*
-- `test/keyboardshortcuts.loop.test.js` – *KeyboardShortcuts _step loop - "after each" hook for "updates view when panning"*
-- `test/keyboardshortcuts.test.js` – *KeyboardShortcuts - pans right when ArrowRight held*
-- `test/keyboardshortcuts.test.js` – *KeyboardShortcuts - starts and stops loop when arrow key released*
-- `test/keyboardshortcuts.zoomClear.test.js` – *KeyboardShortcuts zoom redraw clearing - "before each" hook for "clears both layers when zooming with keyboard"*
-- `test/keyboardshortcuts.zoomClear.test.js` – *KeyboardShortcuts zoom redraw clearing - "after each" hook for "clears both layers when zooming with keyboard"*
-- `test/stage.updateStageSize.test.js` – *Stage updateStageSize - initializes with HUD offset without resize*
-- `test/stage.updateviewpoint.test.js` – *Stage updateViewPoint - keeps cursor position stable while zooming*
-- `test/stage.updateviewpoint.test.js` – *Stage updateViewPoint - keeps level bottom glued to the HUD when zooming*
-- `test/stage.updateviewpoint.test.js` – *Stage updateViewPoint - preserves world coords at multiple cursor positions*
-- `test/stage.updateviewpoint.test.js` – *Stage updateViewPoint - glues bottom when view taller than world*
-- `test/stage.utilities.test.js` – *Stage utilities - "before each" hook for "snapScale clamps and snaps to gcd step"*
-- `test/stage.utils.test.js` – *Stage utils - clampViewPoint centers or clamps within world*
-
-### Tools and misc tests
-- `test/tools/exportAllSprites.integration.test.js` – *exportAllSprites integration - uses default output path and writes sprites*
-- `test/tools/exportAllSprites.integration.test.js` – *exportAllSprites integration - accepts custom paths*
-- `test/tools/exportAllSprites.test.js` – *exportAllSprites tool - uses defaults when no arguments provided*
-- `test/tools/exportAllSprites.test.js` – *exportAllSprites tool - accepts pack path and output dir arguments*
-- `test/tools/exportAllSprites.test.js` – *exportAllSprites tool - exports panel letters and numbers*
-- `test/tools/exportAllSprites.test.js` – *exportAllSprites tool - exports lemming sheets and ground objects*
-- `test/tools/exportAllSprites.test.js` – *exportAllSprites tool - skips a ground pair when loadBinary throws*
-- `test/tools/exportGroundImages.test.js` – *tools/exportGroundImages.js - exports a real ground file*
-- `test/tools/exportGroundImages.test.js` – *tools/exportGroundImages.js - with mock NodeFileProvider - writes PNGs using a mock NodeFileProvider*
-- `test/tools/exportGroundImages.test.js` – *tools/exportGroundImages.js - with mock NodeFileProvider - uses config.json when run without arguments*
-- `test/tools/exportGroundImages.test.js` – *tools/exportGroundImages.js - with mock NodeFileProvider - fails for an out-of-range index*
-- `test/tools/exportGroundImages.test.js` – *tools/exportGroundImages.js - with mock NodeFileProvider - defaults to lemmings when config.json is unreadable*
-- `test/tools/exportGroundImages.test.js` – *tools/exportGroundImages.js - with mock NodeFileProvider - handles missing files without output*
-- `test/tools/exportScripts.test.js` – *export scripts default path - exportAllPacks.js exports under ./exports*
-- `test/tools/exportScripts.test.js` – *export scripts default path - exportAllSprites.js exports under ./exports*
-- `test/tools/exportScripts.test.js` – *export scripts default path - exportGroundImages.js exports under ./exports*
-- `test/tools/exportScripts.test.js` – *export scripts default path - exportLemmingsSprites.js exports under ./exports*
-- `test/tools/exportScripts.test.js` – *export scripts default path - exportPanelSprite.js exports under ./exports*
-- `test/tools/exportScripts.test.js` – *export scripts default path - renderCursorSizes.js exports under ./exports*
-- `test/tools/exportScripts.test.js` – *export scripts default path - scanGreenPanel.js exports under ./exports*
-- `test/tools/listSprites.stdout.test.js` – *tools/listSprites.js stdout - prints sprite listing when no output file is given*
-- `test/tools/listSprites.test.js` – *tools/listSprites.js - writes sprite listing to a file*
-- `test/tools/listSprites.test.js` – *tools/listSprites.js - writes spriteList.txt with sprite names*
-- `test/nodefileprovider.test.js` – *NodeFileProvider - _validateEntry rejects absolute or parent paths*
-- `test/nodefileprovider.test.js` – *NodeFileProvider - _findZipEntry matches case-insensitively*
-- `test/tools/packLevels.test.js` – *tools/packLevels.js - packs a directory of levels into a DAT file*
-- `test/tools/patchSprites.test.js` – *tools/patchSprites.js - patches sprite data using PNG files*
-- `test/tools/patchSprites.test.js` – *tools/patchSprites.js - patches multiple sprites and preserves palette offsets*
-- `test/tools/patchSprites.test.js` – *tools/patchSprites.js (mocked PNG) - updates frames in an existing sprite sheet*
-- `test/processHtmlFile.test.js` – *processHtmlFile - extracts inline event handler attributes*
-- `test/squooshhqx.test.js` – *squooshhqx initSync - initializes wasm and forwards resize arguments*
-- `test/tools/scanGreenPanel.test.js` – *tools/scanGreenPanel.js - marks green pixels blue*
-- `test/tools/scanGreenPanel.test.js` – *tools/scanGreenPanel.js - handles missing panel sprite*
diff --git a/docs/camanis/README.md b/docs/camanis/README.md
new file mode 100644
index 00000000..2b81ce20
--- /dev/null
+++ b/docs/camanis/README.md
@@ -0,0 +1,9 @@
+# Camanis Format References
+
+This folder contains external Lemmings file-format reference material mirrored
+or converted from Camanis/community sources. Treat these files as historical
+format references, not as canonical descriptions of current project behavior.
+
+When current code disagrees with these notes, the repo implementation and tests
+win. Keep this material intact unless a file is duplicated, malformed, or
+actively misleading.
diff --git a/docs/ci.md b/docs/ci.md
index 36dd67ea..b81e5309 100644
--- a/docs/ci.md
+++ b/docs/ci.md
@@ -1,24 +1,34 @@
 # Continuous Integration
 
-This project uses GitHub Actions to run tests on every push and pull request targeting the `master` branch.
+GitHub Actions runs on pushes and pull requests targeting `master`.
 
-The workflow is defined in [`.github/workflows/test.yml`](../.github/workflows/test.yml). Although the `package.json` requires Node 20 or newer, the workflow installs **Node 20**:
+Workflow source: [`.github/workflows/test.yml`](../.github/workflows/test.yml).
+The job installs Node 20, installs Playwright Chromium, runs the static/unit
+gates, starts the local HTTPS server for browser-backed checks, and uploads
+coverage.
 
-```yaml
-- uses: actions/setup-node@v4
-  with:
-    node-version: 20
-```
-
-The CI job performs the following steps:
+Current gate order:
 
 1. `npm ci`
-2. `npm run format`
-3. `git diff --exit-code`
-4. `npm run check-undefined`
-5. `npm run lint`
-6. `npm run depcheck`
-7. `npm test`
-8. `npm run coverage`
+2. `npm audit --audit-level=moderate`
+3. `npx playwright install --with-deps chromium`
+4. `npm run format`
+5. `git diff --check` against changed lines
+6. `git diff --exit-code`
+7. `npm run check-undefined`
+8. `npm run lint`
+9. `npm run typecheck:critical`
+10. `npm run release-readiness`
+11. `npm run depcheck`
+12. `npm run check-mcp-clients`
+13. `npm run test-bench-unit`
+14. `npm test`
+15. generate temporary localhost HTTPS certs
+16. start `npm run start-https`
+17. `npm run test-mcp-smoke`
+18. `npm run bench-smoke`
+19. stop the HTTPS server
+20. `npm run coverage`
 
-All tests must pass before code is merged.
+All generated certs, server logs, coverage, and browser artifacts are CI-local
+or ignored unless explicitly uploaded as artifacts.
diff --git a/docs/compression-format.md b/docs/compression-format.md
index f40a17cb..057bf642 100644
--- a/docs/compression-format.md
+++ b/docs/compression-format.md
@@ -258,6 +258,60 @@ export const patchPack = (origBuf, patches) => {
 
 * **`ldecomp` (C decoder)** — [https://www.camanis.net/lemmings/tools.php](https://www.camanis.net/lemmings/tools.php)
 * **Format write‑up & Compressor.cpp** — [https://www.camanis.net/lemmings/files/docs/lemmings\_dat\_file\_format.txt](https://www.camanis.net/lemmings/files/docs/lemmings_dat_file_format.txt)
+
+---
+
+## 10 · Replay Cold-Block Binary Layout
+
+`HistoryStore` cold compaction now uses a binary payload (`js/game/HistoryStore.js`)
+instead of JSON clone/serialize. This is an internal replay format used only for
+in-memory cold blocks.
+
+### 10.1 Block Envelope
+
+* `magic` (`u32`, LE): `0x42534c48` (`HLSB`)
+* `version` (`u8`): `1`
+* `noOpCount` (`varuint`)
+* repeated `noOpCount` times:
+  * `startOffset` (`varuint`)
+  * `length` (`varuint`)
+* `deltaCount` (`varuint`)
+* `deltaOffsets[deltaCount]` (`varuint[]`)
+* `deltaLengths[deltaCount]` (`varuint[]`)
+* `deltaPayloadBytes` (concatenated byte slices)
+
+The envelope may optionally be RLE-compressed by the existing cold-block
+compression toggle.
+
+### 10.2 Delta Payload
+
+Each delta payload starts with:
+
+* `deltaCodecVersion` (`u8`): `1`
+* `flags` (`u32`, LE): section bitmap
+
+Sections are written in flag order. Lemming mutation streams are field-packed in
+typed-array style sections (contiguous per field) for:
+
+* `lemChanges`
+* `lemAdded`
+* `lemRemoved`
+
+Non-lemming sections use canonical tagged-value encoding with sorted object keys
+to keep payload bytes deterministic for hashing/deduping.
+
+### 10.3 Cold-Block Dedupe Dictionary
+
+Cold blocks can be feature-gated with:
+
+* `enableColdBlockCompression` (RLE envelope compression)
+* `enableColdBlockDedupe` (dictionary-style byte sharing by encoded payload)
+
+The dedupe key includes encoding, FNV-1a payload hash, and encoded length.
+Hash collisions are handled safely by a byte-for-byte equality check before
+reusing a dictionary entry, so mismatched payloads stay isolated even when
+bucket keys collide.
+
 * **NeoLemmix DAT Manager (C#)** — [https://www.neolemmix.com/old/lemtools.html](https://www.neolemmix.com/old/lemtools.html)
 * **Lemmix Pascal source** — [https://github.com/arjanadriaanse/lemmix](https://github.com/arjanadriaanse/lemmix)
 * **Community edge‑case thread** — [https://www.lemmingsforums.net/index.php?topic=6902.0](https://www.lemmingsforums.net/index.php?topic=6902.0)
diff --git a/docs/config.md b/docs/config.md
index a7279ab9..d929dc26 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -13,4 +13,28 @@
 - `level.useOddTable` – Set to `true` when the pack uses an ODDTABLE resource.
 - `mechanics` *(optional)* – Object of gameplay flags that override or extend the defaults.
 
-`packMechanics.js` supplies defaults like `classicBuilder` or `bomberAssist` for each pack. `ConfigReader` merges these defaults with the `mechanics` object from `config.json` so game code only needs to consult a single merged `mechanics` field.
+`packMechanics.js` supplies defaults like `classicBuilder`, `bomberAssist`, `pauseGlitch`, `nukeGlitch`, and `rightClickGlitch` for each pack. `ConfigReader` merges these defaults with the `mechanics` object from `config.json` so game code only needs to consult a single merged `mechanics` field.
+
+## Runtime startup profiles
+
+The browser runtime also supports URL startup profiles:
+
+- `profile=classic` (default): normal gameplay startup behavior.
+- `profile=editor`: boots gameplay once, then enters editor mode and loads the selected level into the editor.
+- `profile=midi`: normal gameplay with MIDI UI startup defaults.
+- `profile=e2e`: E2E-oriented startup defaults.
+- `profile=perf`: enables perf-focused runtime defaults (`performanceAPI=true` and `perfOverlay=true`).
+
+Short alias: `pr=<classic|midi|editor|e2e|perf>`.
+
+Legacy `profile=gameplay` URLs are normalized to `classic`.
+
+## Bench Profiles
+
+`scripts/bench-performance.js` supports benchmark profiles:
+
+- `--profile=default`: sequence benchmark with perf instrumentation.
+- `--profile=stress`: high-entity stress run (`bench2` path).
+- `--profile=reverse`: sustained reverse-playback stress run.
+
+Overrides (`--mode`, `--duration`, `--sample`, `--entrances`) still apply per run.
diff --git a/docs/e2e-editor-state.md b/docs/e2e-editor-state.md
index 91af51cd..c8a1d1ee 100644
--- a/docs/e2e-editor-state.md
+++ b/docs/e2e-editor-state.md
@@ -3,6 +3,10 @@
 Editor state is returned under `window.__E2E__.getState().editor`. This document
 lists every field surfaced by the harness for editor mode.
 
+Editor mutations for Playwright and MCP go through
+`window.__E2E__.editorApply(ops, options)`. The operation contract is documented
+in [`mcp/editor-apply.md`](mcp/editor-apply.md).
+
 ## Top-level editor fields
 - `mode`: `true` when editor mode is active.
 - `playtest`: editor playtest toggle (from GameView).
diff --git a/docs/e2e-state.md b/docs/e2e-state.md
index a919df6a..12f9ac05 100644
--- a/docs/e2e-state.md
+++ b/docs/e2e-state.md
@@ -5,7 +5,20 @@ API at `window.__E2E__` for Playwright to read state and drive time travel.
 
 ## API
 - `window.__E2E__.getState()` returns a JSON-safe snapshot.
+- `window.__E2E__.getDiagnostics()` returns deterministic environment diagnostics
+  (runtime profile, rollout/capability snapshots, feature flags, and active
+  cache snapshots).
+- `window.__E2E__.getCanvasMetrics()` returns canvas/stage sizing diagnostics.
+- `window.__E2E__.getCaptureRects(options?)` returns page-space CSS rectangles
+  for visual capture tooling.
 - `window.__E2E__.getBuffer(name)` returns one heavy buffer at a time.
+- `window.__E2E__.stageWorldFromPage(point)` converts a page point to a game
+  world point.
+- `window.__E2E__.stagePageFromWorld(point)` converts a game world point to a
+  page point.
+- `window.__E2E__.centerStageOn(point)` centers the stage on a world point.
+- `window.__E2E__.getMinimapPagePoint(options?)` returns a usable page point in
+  the minimap.
 - `window.__E2E__.step(count)` steps forward/backward (negative allowed).
 - `window.__E2E__.seek(tickIndex)` seeks via time travel (if available).
 - `window.__E2E__.pause()` / `window.__E2E__.resume()` control the game timer.
@@ -17,11 +30,88 @@ API at `window.__E2E__` for Playwright to read state and drive time travel.
 - `window.__E2E__.startBenchSequence()` starts the sequence bench run.
 - `window.__E2E__.startBench(entrances)` starts a single bench run.
 - `window.__E2E__.stopBench()` stops bench flags.
+- `window.__E2E__.getDelta(tickIndex)` and
+  `window.__E2E__.getDeltas(fromTick, toTick, maxTicks?)` return history deltas.
 - `window.__E2E__.setEditorPlaytest(enabled)` toggles editor playtest.
 - `window.__E2E__.getEditorHistoryEntry(index)` returns one editor history
   entry with full text.
 - `window.__E2E__.selectLemmingById(id)` selects a lemming by ID (returns
   `true` on success).
+- `window.__E2E__.midiGetProject()` returns the current MIDI project.
+- `window.__E2E__.midiGetRuntimeConfig()` returns the lowered runtime MIDI
+  config used by the existing MIDI router and scheduler.
+- `window.__E2E__.midiDispatchProjectIntent(intent)` dispatches a MIDI project
+  intent.
+- `window.__E2E__.midiResetProject(templateId)` resets the project from the
+  factory template or a saved template.
+- `window.__E2E__.midiExportProject(options)` returns a sanitized MIDI project
+  export payload.
+- `window.__E2E__.midiImportProject(payload)` imports a sanitized MIDI project
+  or template payload.
+- `window.__E2E__.midiSaveProjectTemplate(options)` stores the current project
+  as a user template.
+- `window.__E2E__.midiGetProjectTemplates()` returns saved MIDI templates.
+- `window.__E2E__.midiGetUiMetrics()` returns MIDI UI render metrics.
+- `window.__E2E__.midiStartLearn()` / `midiConfirmLearn()` /
+  `midiCancelLearn()` drive MIDI learn.
+- `window.__E2E__.midiCaptureLearnNote(note, velocity, channel)` injects a
+  learned note into the active learn capture.
+- `window.__E2E__.midiStartRecording()` / `midiCommitRecording()` /
+  `midiCancelRecording()` drive MIDI clip recording.
+- `window.__E2E__.midiCaptureRecordMessage(message)` injects a MIDI message into
+  the active recording capture.
+- `window.__E2E__.midiAudition(request)` triggers project audition through the
+  live MIDI router.
+
+## getCaptureRects(options?)
+
+`getCaptureRects` returns:
+
+```js
+{
+  version: 1,
+  rects: {
+    canvas: { x, y, width, height }
+  },
+  diagnostics: {
+    route,
+    mode,
+    missing,
+    available
+  }
+}
+```
+
+Runtime rectangle ids are omitted when the current route cannot provide them.
+Known ids include:
+
+- `canvas`: `#gameCanvas` or `#editorCanvas`.
+- `stageCanvas`: the Stage canvas element.
+- `game`: the rendered game image rectangle.
+- `gui`: the rendered HUD image rectangle.
+- `minimap`: the minimap area inside the HUD.
+- `editorCanvas`: the editor canvas element.
+- `editorSelection`: current editor selection bounds when a selection exists.
+
+For world-space capture, pass a world rectangle and optional padding:
+
+```js
+window.__E2E__.getCaptureRects({
+  worldRect: {
+    id: 'lead-area',
+    rect: { x: 0, y: 0, width: 320, height: 160 },
+    padding: 8
+  }
+});
+```
+
+All returned rectangles are finite positive CSS-pixel rectangles suitable for
+the Playwright visual capture helper. The helper writes disposable screenshots
+under ignored `temp/e2e-captures/`; no manifests, baselines, or generated images
+are checked in.
+
+`diagnostics.missing` explains omitted ids. Missing surfaces are expected on
+routes that do not expose that surface.
 
 ## getState() structure
 
@@ -35,7 +125,9 @@ Top-level fields:
 - `game`: game simulation state (null before load).
 - `editor`: editor state snapshot (see `docs/e2e-editor-state.md`).
 - `bench`: bench metrics snapshot (if available).
+- `diagnostics`: runtime profile + feature flags + cache snapshot summary.
 - `midi`: midi enable/router summary.
+- `procgen`: compact procgen debug state when the procgen controller is active.
 
 ### view
 - `gameType`, `levelGroupIndex`, `levelIndex`.
@@ -49,6 +141,38 @@ Top-level fields:
 - `midiEnabled`.
 - `configName`, `configPath` from the active pack config.
 
+### diagnostics
+- `version`: schema version (currently `1`).
+- `profile`: runtime profile (`classic`, `midi`, `editor`, `e2e`, `perf`,
+  etc.). Legacy `gameplay` query values are normalized to `classic`.
+- `rolloutFlags`: active staged-rollout/rollback flags.
+- `capabilities`: runtime/browser capability matrix for WebMIDI and render
+  paths.
+- `featureFlags`: normalized boolean flag snapshot from `GameView`.
+- `caches.fileProvider`: `memoryEntries`, `localStorageBytes`,
+  `indexedDbBytes` when available.
+- `caches.cacheStorageKeys`: sorted Cache Storage keys (`null` in
+  `getState()`, populated by `getDiagnostics()`).
+- `serviceWorker`: `supported`, `controlled`.
+- `location`: `protocol`, `hostname`, `pathname`.
+
+### midi
+- `enabled`: current MIDI enabled state.
+- `hasRouter`: whether the runtime MIDI router is attached.
+- `outputName`: selected MIDI output device name (or `null`).
+- `projectId`: current MIDI project id.
+- `selectedTrackId`: selected MIDI track id.
+- `selectedSourceId`: selected MIDI source id.
+
+### procgen
+- `selectedTheme`: selected style/theme for the seeded run.
+- `seed`: normalized procgen seed.
+- `generatedEndX`: current generated terrain extent.
+- `frontier`: live rightmost viable lemming summary.
+- `lookahead`: threshold/distance data used to decide when to generate.
+- `recentChunks`, `recentPieces`, `recentAssists`: bounded debug lists.
+- `trackingSizes`: sizes of bounded procgen tracking structures.
+
 ### stage
 - `panEnabled`.
 - `cursor` (screen coords).
diff --git a/docs/excluded-tests.md b/docs/excluded-tests.md
index cad167ac..5e7fff47 100644
--- a/docs/excluded-tests.md
+++ b/docs/excluded-tests.md
@@ -1,3 +1,4 @@
 # Excluded tests
 
-No tests are currently excluded from CI.
+No tests are currently excluded from CI. Keep this file as the only place for
+deliberate manual exclusions if one is added later.
diff --git a/docs/exporting-sprites.md b/docs/exporting-sprites.md
index d58b78a0..2d20a672 100644
--- a/docs/exporting-sprites.md
+++ b/docs/exporting-sprites.md
@@ -16,7 +16,8 @@
   - `npm run export-ground-images` – export ground and object images from a single ground set
   - `npm run export-all-sprites` – export the panel, lemmings and ground sprites for one level pack
   - `npm run list-sprites` – list sprite names with sizes and frame counts
-  - `npm run patch-sprites` – verify a directory of edited sprites (patching not yet implemented)
+  - `npm run patch-sprites` – replace sprites in an existing DAT archive from
+    edited PNG frames or sprite sheets
 
 All exported assets now reside under the `exports/` directory.
 
diff --git a/docs/fixable-tests.md b/docs/fixable-tests.md
deleted file mode 100644
index 0b5f41a7..00000000
--- a/docs/fixable-tests.md
+++ /dev/null
@@ -1,4 +0,0 @@
-# Fixable tests
-
-At this time the agent was unable to repair any failing tests. Most failures stem from missing browser APIs or complex game logic that requires extensive refactoring.
-
diff --git a/docs/gamepad-bindings.md b/docs/gamepad-bindings.md
new file mode 100644
index 00000000..40e46bfe
--- /dev/null
+++ b/docs/gamepad-bindings.md
@@ -0,0 +1,53 @@
+# Gamepad Bindings
+
+Gamepad input is action-driven, like keyboard bindings.
+
+- Default mappings are in `gamepadbindings.json`.
+- Runtime parser/dispatcher lives in `js/input/GamepadInputController.js`.
+- Gameplay bindings are consumed by `js/input/KeyboardShortcuts.js`.
+- Editor bindings are consumed by `js/input/EditorKeybindings.js`.
+
+## Mapping Format
+
+```json
+{
+  "version": 1,
+  "bindings": {
+    "gameplay": {
+      "togglePause": ["button:9"],
+      "panLeft": ["button:14", "axis:0:-:0.35"]
+    },
+    "editor": {
+      "editorToolTerrain": ["button:0"],
+      "editorNudgeRight": ["button:15", "axis:0:+:0.35"]
+    }
+  }
+}
+```
+
+Binding token formats:
+
+- `button:<index>[:threshold]`
+- `axis:<index>:<+|->[:deadZone]`
+
+Examples:
+
+- `button:0` -> face button 0 press.
+- `button:7:0.7` -> trigger press with analog threshold.
+- `axis:1:+:0.35` -> axis 1 positive direction past dead-zone.
+
+## Remapping and Persistence
+
+- Bindings are composed in this order:
+  1. hardcoded defaults
+  2. file defaults from `gamepadbindings.json`
+  3. persisted user overrides
+  4. in-session overrides
+- Runtime remaps can be applied via:
+  - `KeyboardShortcuts.setGamepadBindings(config, options)`
+  - `EditorKeybindings.setGamepadBindings(config, options)`
+- Persisted remaps are stored in local storage key
+  `lem-gamepad-bindings-v1`.
+- Only the persisted user-override layer is written to local storage. File
+  defaults can change without clobbering user overrides, and non-persisted
+  session remaps are discarded on reload.
diff --git a/docs/incoherent-tests.md b/docs/incoherent-tests.md
deleted file mode 100644
index c468b0ff..00000000
--- a/docs/incoherent-tests.md
+++ /dev/null
@@ -1,102 +0,0 @@
-# Incoherent tests
-
-These tests were removed because they are outside the core game simulation focus (browser/UI rendering or offline tooling/asset export paths), or rely on behavior that cannot be reliably exercised in the test runner.
-
-| Test | Reason |
-| --- | --- |
-| `test/bench-entrance-placement.test.js` | Bench mode depends on RAF/visibility timing and UI scheduling, not core simulation. |
-| `test/bench-measure-extras.test.js` | Bench mode depends on RAF/visibility timing and UI scheduling, not core simulation. |
-| `test/bench-no-end.test.js` | Bench mode depends on RAF/visibility timing and UI scheduling, not core simulation. |
-| `test/bench-sequence-start.test.js` | Bench mode depends on RAF/visibility timing and UI scheduling, not core simulation. |
-| `test/bench-sequence.test.js` | Bench mode depends on RAF/visibility timing and UI scheduling, not core simulation. |
-| `test/bench-speed-adjust.test.js` | Bench mode depends on RAF/visibility timing and UI scheduling, not core simulation. |
-| `test/bench-start.test.js` | Bench mode depends on RAF/visibility timing and UI scheduling, not core simulation. |
-| `test/bench-tps.test.js` | Bench mode depends on RAF/visibility timing and UI scheduling, not core simulation. |
-| `test/crosshaircursor.test.js` | Cursor rendering is UI-only, not core simulation. |
-| `test/displayimage.primitives.test.js` | Pixel rendering utilities are view-layer concerns, not core simulation. |
-| `test/displayimage.scaling.test.js` | Pixel rendering utilities are view-layer concerns, not core simulation. |
-| `test/displayimage.test.js` | Pixel rendering utilities are view-layer concerns, not core simulation. |
-| `test/gamedisplay.extra.test.js` | Render buffer and click-selection plumbing are display-layer concerns, not core simulation. |
-| `test/gamedisplay.test.js` | Render buffer and click-selection plumbing are display-layer concerns, not core simulation. |
-| `test/gamegui.behavior.test.js` | HUD/controls rendering and command wiring live in the UI layer, not core simulation. |
-| `test/gamegui.drawhelpers.test.js` | HUD/controls rendering and command wiring live in the UI layer, not core simulation. |
-| `test/gamegui.misc.test.js` | HUD/controls rendering and command wiring live in the UI layer, not core simulation. |
-| `test/gamegui.release-rate.render.test.js` | HUD/controls rendering and command wiring live in the UI layer, not core simulation. |
-| `test/gamegui.test.js` | HUD/controls rendering and command wiring live in the UI layer, not core simulation. |
-| `test/gametimer.test.js` | GameTimer ties to document visibility and RAF scheduling, which is browser-specific. |
-| `test/gameview.applyquery.test.js` | GameView wires browser UI, canvas setup, and view lifecycle; out of scope for core simulation. |
-| `test/gameview.canvas-reset.test.js` | GameView wires browser UI, canvas setup, and view lifecycle; out of scope for core simulation. |
-| `test/gameview.controls.test.js` | GameView wires browser UI, canvas setup, and view lifecycle; out of scope for core simulation. |
-| `test/gameview.dispose.test.js` | GameView wires browser UI, canvas setup, and view lifecycle; out of scope for core simulation. |
-| `test/gameview.enableDebug.test.js` | GameView wires browser UI, canvas setup, and view lifecycle; out of scope for core simulation. |
-| `test/gameview.frames-no-game.test.js` | GameView wires browser UI, canvas setup, and view lifecycle; out of scope for core simulation. |
-| `test/gameview.helperExtras.test.js` | GameView wires browser UI, canvas setup, and view lifecycle; out of scope for core simulation. |
-| `test/gameview.helpers.test.js` | GameView wires browser UI, canvas setup, and view lifecycle; out of scope for core simulation. |
-| `test/gameview.loadlevel-missing.test.js` | GameView wires browser UI, canvas setup, and view lifecycle; out of scope for core simulation. |
-| `test/gameview.loadlevel.test.js` | GameView wires browser UI, canvas setup, and view lifecycle; out of scope for core simulation. |
-| `test/gameview.loadReplay.test.js` | GameView wires browser UI, canvas setup, and view lifecycle; out of scope for core simulation. |
-| `test/gameview.menu-selects.test.js` | GameView wires browser UI, canvas setup, and view lifecycle; out of scope for core simulation. |
-| `test/gameview.movelevel.paths.test.js` | GameView wires browser UI, canvas setup, and view lifecycle; out of scope for core simulation. |
-| `test/gameview.onGameEnd.test.js` | GameView wires browser UI, canvas setup, and view lifecycle; out of scope for core simulation. |
-| `test/gameview.setup.test.js` | GameView wires browser UI, canvas setup, and view lifecycle; out of scope for core simulation. |
-| `test/gameview.sound.test.js` | GameView wires browser UI, canvas setup, and view lifecycle; out of scope for core simulation. |
-| `test/gameview.start-existing.test.js` | GameView wires browser UI, canvas setup, and view lifecycle; out of scope for core simulation. |
-| `test/gameview.stepSpeed.test.js` | GameView wires browser UI, canvas setup, and view lifecycle; out of scope for core simulation. |
-| `test/gameview.suspendWithColor.test.js` | GameView wires browser UI, canvas setup, and view lifecycle; out of scope for core simulation. |
-| `test/gameview.test.js` | GameView wires browser UI, canvas setup, and view lifecycle; out of scope for core simulation. |
-| `test/keyboardshortcuts.branches.test.js` | Keyboard input loops rely on browser events/RAF, not core simulation. |
-| `test/keyboardshortcuts.eventpaths.test.js` | Keyboard input loops rely on browser events/RAF, not core simulation. |
-| `test/keyboardshortcuts.instantNuke.test.js` | Keyboard input loops rely on browser events/RAF, not core simulation. |
-| `test/keyboardshortcuts.keys.test.js` | Keyboard input loops rely on browser events/RAF, not core simulation. |
-| `test/keyboardshortcuts.loop.test.js` | Keyboard input loops rely on browser events/RAF, not core simulation. |
-| `test/keyboardshortcuts.test.js` | Keyboard input loops rely on browser events/RAF, not core simulation. |
-| `test/keyboardshortcuts.zoomClear.test.js` | Keyboard input loops rely on browser events/RAF, not core simulation. |
-| `test/lemmingsnamespace.test.js` | Global window namespace attachment is browser integration, not core simulation. |
-| `test/minimap.extra.test.js` | Minimap rendering is UI visualization, not core simulation. |
-| `test/minimap.test.js` | Minimap rendering is UI visualization, not core simulation. |
-| `test/overlay-ants.test.js` | Overlay rendering effects are UI-only, not core simulation. |
-| `test/particletable.lookup.test.js` | Tests the window.atob browser branch, not core simulation. |
-| `test/smoothscroller.test.js` | Scroll animation and viewport smoothing are UI-only, not core simulation. |
-| `test/stage.draw.test.js` | Stage/camera surfaces and GUI layout depend on canvas sizing, not core simulation. |
-| `test/stage.drawbranches.test.js` | Stage/camera surfaces and GUI layout depend on canvas sizing, not core simulation. |
-| `test/stage.lifecycle.test.js` | Stage/camera surfaces and GUI layout depend on canvas sizing, not core simulation. |
-| `test/stage.overlayfade.test.js` | Stage/camera surfaces and GUI layout depend on canvas sizing, not core simulation. |
-| `test/stage.setGameViewPointPosition.test.js` | Stage/camera surfaces and GUI layout depend on canvas sizing, not core simulation. |
-| `test/stage.test.js` | Stage/camera surfaces and GUI layout depend on canvas sizing, not core simulation. |
-| `test/stage.updateStageSize.test.js` | Stage/camera surfaces and GUI layout depend on canvas sizing, not core simulation. |
-| `test/stage.updateviewpoint.test.js` | Stage/camera surfaces and GUI layout depend on canvas sizing, not core simulation. |
-| `test/stage.utilities.test.js` | Stage/camera surfaces and GUI layout depend on canvas sizing, not core simulation. |
-| `test/stage.utils.test.js` | Stage/camera surfaces and GUI layout depend on canvas sizing, not core simulation. |
-| `test/stageimageprops.test.js` | Stage/camera surfaces and GUI layout depend on canvas sizing, not core simulation. |
-| `test/userinput.dispose.test.js` | Pointer event translation depends on DOM/canvas coordinates, not core simulation. |
-| `test/userinput.events.test.js` | Pointer event translation depends on DOM/canvas coordinates, not core simulation. |
-| `test/userinput.test.js` | Pointer event translation depends on DOM/canvas coordinates, not core simulation. |
-| `test/viewpoint.test.js` | Viewpoint/camera math is presentation-layer logic, not core simulation. |
-| `test/exportLemmingsSprites.test.js` | Sprite export relies on full asset packs and filesystem output; outside core simulation. |
-| `test/exportScripts.test.js` | Export script integration depends on asset packs and filesystem layout; outside core simulation. |
-| `test/listSprites.defaultPack.test.js` | CLI sprite listing depends on pack files/config and tool output, not core simulation. |
-| `test/listSprites.stdout.test.js` | CLI sprite listing depends on pack files/config and tool output, not core simulation. |
-| `test/listsprites.test.js` | CLI sprite listing depends on pack files/config and tool output, not core simulation. |
-| `test/patchSprites.cli.test.js` | CLI patching depends on tool entrypoints and file IO, not core simulation. |
-| `test/tools/exportAllSprites.integration.test.js` | Integration export depends on asset packs and filesystem output, not core simulation. |
-| `test/fileprovider.test.js` | `_hashBuffer throws when crypto unavailable` relied on mutating `node:crypto` exports, which is not supported in ESM. |
-| `test/levelloader.test.js` | `uses OddTableReader when configured` tried to stub static imports that `LevelLoader` does not resolve from dependencies. |
-| `test/tools/archiveDir.test.js` | Offline tooling tests depend on local archives and filesystem layout, not core simulation. |
-| `test/tools/cleanExports.test.js` | Offline tooling tests depend on local exports layout, not core simulation. |
-| `test/tools/exportAllPacks.test.js` | Offline tooling tests depend on asset packs and script entrypoints, not core simulation. |
-| `test/tools/exportAllSprites.test.js` | Offline tooling tests depend on asset packs and script entrypoints, not core simulation. |
-| `test/tools/exportGroundImages.test.js` | Offline tooling tests depend on asset packs and filesystem output, not core simulation. |
-| `test/tools/exportScripts.test.js` | Offline tooling tests depend on script entrypoints and filesystem output, not core simulation. |
-| `test/tools/listSprites.test.js` | Offline tooling tests depend on asset packs and script output, not core simulation. |
-| `test/tools/packLevels.test.js` | Offline tooling tests depend on pack inputs/outputs, not core simulation. |
-| `test/tools/patchSprites.test.js` | Offline tooling tests depend on pack inputs/outputs, not core simulation. |
-| `test/tools/processHtmlFile.snippets.test.js` | Offline tooling tests are for HTML processing utilities, not core simulation. |
-| `test/tools/processHtmlFile.test.js` | Offline tooling tests are for HTML processing utilities, not core simulation. |
-| `test/tools/scanGreenPanel.test.js` | Offline tooling tests depend on sprite assets, not core simulation. |
-| `test/archiveDir.test.js` | Offline tooling tests depend on local archives and filesystem layout, not core simulation. |
-| `test/exportPanelSprite.defaultPack.test.js` | Offline tooling tests depend on asset packs and filesystem output, not core simulation. |
-| `test/packLevels.test.js` | Offline tooling tests depend on pack inputs/outputs, not core simulation. |
-| `test/patchSprites.coverage.test.js` | Offline tooling tests depend on pack inputs/outputs, not core simulation. |
-| `test/patchsprites.test.js` | Offline tooling tests depend on pack inputs/outputs, not core simulation. |
-| `test/nodefileprovider.test.js` | Node-only file provider tests are for offline tooling, not core simulation. |
-| `test/vgaspecreader.test.js` | `handles run-length chunks across sections` expected decode output that does not match the current VGASpecReader behavior. |
diff --git a/docs/keybindings-design.md b/docs/keybindings-design.md
index 482e828d..cdfaeb0f 100644
--- a/docs/keybindings-design.md
+++ b/docs/keybindings-design.md
@@ -1,19 +1,19 @@
-# Keybindings Configuration Design
+# Keybindings Configuration
 
-## Overview
-Introduce a JSON-driven keyboard binding system so every action handled by `KeyboardShortcuts` can be remapped without code changes. The config is loaded at runtime from `keybindings.json` and falls back to built-in defaults if the file is missing or invalid.
+Keyboard bindings are JSON-driven so gameplay and editor actions can be
+remapped without code changes. The current file-level defaults live in
+[`../keybindings.json`](../keybindings.json); this document describes the format
+and loading rules rather than duplicating the full action list.
 
-## Goals
-- Make every keyboard action configurable through JSON.
-- Allow multiple bindings per action.
-- Keep defaults stable and documented.
-- Preserve existing behavior when no config file is present.
+## Scope
 
-## Non-goals
-- UI for live rebinding in-game.
-- Saving keybindings to localStorage (future work).
+- Gameplay actions: pause/step/reverse, rate and speed controls, skill
+  selection, nuke/restart, level navigation, panning/zooming, shortcut overlay.
+- Editor actions: mode toggle, tool selection, MIDI flag tool, copy/paste,
+  duplicate, nudge, ordering, playtest, undo/redo/delete, shortcut overlay.
+- Multiple bindings per action are supported.
 
-## JSON Schema
+## JSON shape
 
 ```json
 {
@@ -21,91 +21,41 @@ Introduce a JSON-driven keyboard binding system so every action handled by `Keyb
   "bindings": {
     "togglePause": ["Space"],
     "stepForward": ["BracketRight"],
-    "stepBackward": ["BracketLeft", "Alt+BracketRight"],
-    "toggleReverse": ["KeyB"],
-    "panLeft": ["ArrowLeft"],
-    "panRight": ["ArrowRight"],
-    "panUp": ["ArrowUp"],
-    "panDown": ["ArrowDown"],
-    "panBoost": ["ShiftLeft", "ShiftRight"],
-    "zoomIn": ["KeyZ"],
-    "zoomOut": ["KeyX"],
-    "zoomReset": ["KeyV"],
-    "releaseRateDown": ["Digit1"],
-    "releaseRateDownMax": ["Shift+Digit1"],
-    "releaseRateUp": ["Digit2"],
-    "releaseRateUpMax": ["Shift+Digit2"],
-    "selectSkillClimber": ["Digit3"],
-    "selectSkillFloater": ["Digit4"],
-    "selectSkillBomber": ["Digit5"],
-    "selectSkillBlocker": ["Digit6"],
-    "selectSkillBuilder": ["KeyQ"],
-    "selectSkillBasher": ["KeyW"],
-    "selectSkillMiner": ["KeyE"],
-    "selectSkillDigger": ["KeyR"],
-    "cycleSkillNext": ["Tab"],
-    "cycleSkillPrev": ["Shift+Tab"],
-    "applySkillToSelected": ["KeyK"],
-    "nuke": ["KeyT"],
-    "nukeInstant": ["Shift+KeyT"],
-    "restartLevel": ["Backspace"],
-    "toggleDebug": ["Backslash"],
-    "speedDown": ["Minus", "NumpadSubtract", "Alt+Equal", "Alt+NumpadAdd"],
-    "speedDownFast": ["Shift+Minus", "Shift+NumpadSubtract", "Alt+Shift+Equal", "Alt+Shift+NumpadAdd"],
-    "speedUp": ["Equal", "NumpadAdd"],
-    "speedUpFast": ["Shift+Equal", "Shift+NumpadAdd"],
-    "levelPrev": ["Comma"],
-    "levelNext": ["Period"],
-    "levelGroupPrev": ["Shift+Comma"],
-    "levelGroupNext": ["Shift+Period"],
-    "editorToggle": ["Shift+Backquote"],
-    "editorToolSelect": ["KeyS"],
     "editorToolTerrain": ["KeyT"],
-    "editorToolGadget": ["KeyG"],
-    "editorToolTrigger": ["KeyR"],
-    "editorToolEntrance": ["KeyE"],
-    "editorToolExit": ["KeyX"],
-    "editorToolSteel": ["KeyF"],
-    "editorToolBrush": ["KeyB"],
-    "editorToolEraser": ["KeyD"],
-    "editorCopy": ["Ctrl+KeyC"],
-    "editorPaste": ["Ctrl+KeyV"],
-    "editorDuplicate": ["Ctrl+KeyD"],
-    "editorNudgeLeft": ["ArrowLeft"],
-    "editorNudgeRight": ["ArrowRight"],
-    "editorNudgeUp": ["ArrowUp"],
-    "editorNudgeDown": ["ArrowDown"],
-    "editorNudgeLeftFast": ["Shift+ArrowLeft"],
-    "editorNudgeRightFast": ["Shift+ArrowRight"],
-    "editorNudgeUpFast": ["Shift+ArrowUp"],
-    "editorNudgeDownFast": ["Shift+ArrowDown"],
-    "editorSnapSelection": ["Ctrl+KeyG"],
-    "editorTogglePlaytest": ["KeyP"],
-    "editorUndo": ["KeyZ"],
-    "editorRedo": ["Shift+KeyZ"],
-    "editorDelete": ["Delete", "Backspace"]
+    "editorBringToFront": ["Ctrl+Shift+BracketRight"]
   }
 }
 ```
 
-## Parsing Rules
-- Binding strings use `+` to join modifiers with a physical key `code` (e.g. `Shift+KeyT`).
-- Modifiers are case-insensitive: `Ctrl`, `Control`, `Alt`, `Shift`, `Meta`, `Cmd`, `Command`, `Win`.
-- The final token is treated as a `KeyboardEvent.code` value.
-- For pure modifier keys, use `ShiftLeft`, `ShiftRight`, `ControlLeft`, etc.
+## Parsing rules
+
+- Binding strings use `+` to join modifiers with a physical
+  `KeyboardEvent.code`, for example `Shift+KeyT`.
+- Modifiers are case-insensitive: `Ctrl`, `Control`, `Alt`, `Shift`, `Meta`,
+  `Cmd`, `Command`, `Win`.
+- The final token is treated as the physical key code.
+- Pure modifier keys use physical codes such as `ShiftLeft`, `ShiftRight`, or
+  `ControlLeft`.
 - Invalid bindings are ignored and do not crash the loader.
 
-## Loading Flow
-- `KeyboardShortcuts` loads defaults immediately.
-- It attempts to load `keybindings.json` from the project root via `FileProvider.loadString` and overrides defaults if parsing succeeds.
-- If loading fails (missing file, non-browser tests), defaults remain active.
+## Loading flow
+
+- Built-in defaults are available immediately.
+- `KeyboardShortcuts` attempts to load `keybindings.json` via
+  `FileProvider.loadString`.
+- If the file is missing, invalid, or unavailable in a test harness, built-in
+  defaults remain active.
+- Runtime code can update bindings through `KeyboardShortcuts.keybindings` APIs.
+
+## Conflict resolution
 
-## Conflict Resolution
-- Multiple actions can bind to the same chord; all are dispatched in declaration order.
-- If an exact modifier match exists, only those actions fire.
-- If no exact match exists, Shift is treated as optional unless Ctrl/Alt/Meta are pressed.
-- If Ctrl/Alt/Meta are pressed and no exact match exists, the event is ignored to preserve browser shortcuts.
+- Multiple actions can bind to the same chord; actions dispatch in declaration
+  order.
+- If an exact modifier match exists, only exact-match actions fire.
+- If no exact match exists, Shift is optional unless Ctrl, Alt, or Meta are
+  pressed.
+- If Ctrl, Alt, or Meta are pressed and no exact match exists, the event is
+  ignored to preserve browser shortcuts.
 
-## Extensibility
-- Future actions can be added by extending the defaults and adding handlers in `KeyboardShortcuts`.
-- A UI layer can update bindings by calling `KeyboardShortcuts.keybindings.setConfig()`.
+Gamepad binding format is documented separately in
+[`gamepad-bindings.md`](gamepad-bindings.md).
diff --git a/docs/level-editor/audit.md b/docs/level-editor/audit.md
new file mode 100644
index 00000000..1cb72433
--- /dev/null
+++ b/docs/level-editor/audit.md
@@ -0,0 +1,111 @@
+# Level Editor Productization Audit
+
+Date: 2026-05-06
+
+## Scope Decision
+
+This checkpoint productizes the editor as a classic-subset editor. It may import
+and preserve `.nxlv` data that is outside the classic subset, but it does not
+claim NeoLemmix feature parity. Unsupported or lossy operations must be visible
+before export, quick-fix, playtest, or import acceptance can surprise a user.
+
+## Docs vs Code
+
+| Area | Documented | Current implementation | Gap |
+| --- | --- | --- | --- |
+| Standalone editor | `editor.html` with canvas, palette, inspector, validation, local save, import/export | Implemented through `EditorUiController`, editor session, controller, and E2E harness | Product status and warnings need to state classic-subset limits directly in the UI |
+| `.nxlv` import/export | Structured editor model with comments and unknown sections preserved | Parser/writer preserves top-level unknown lines, section-local unknown lines, unknown sections, and terrain groups | Round-trip coverage must prove semantic preservation for comments, unknown sections, and grouped terrain |
+| Classic `.lvl` import/export | Supported as classic workflow | Implemented via `LevelReader`, `LevelWriter`, and classic conversion helpers | Export is intentionally lossy; the UI and validation need explicit warnings before users rely on it |
+| Validation | Errors/warnings with quick fixes | Implemented in `EditorValidator` and rendered in the validation panel | Destructive fixes need clear labels/metadata so users can distinguish repair from data-dropping cleanup |
+| Playtest | Toggle playtest without leaving editor | Implemented through editor preview/runtime path | Capture coverage should show both edit and playtest states |
+| NeoLemmix expansion | Documented as out of scope | Parser preserves some unsupported data but runtime preview remains classic | Unsupported sections/properties must be visible warnings, not silent preservation claims |
+
+## Implemented vs Claimed
+
+Implemented and suitable for productized classic-subset use:
+
+- Create blank levels and edit headers, skill counts, terrain, gadgets, steel,
+  MIDI flags, and entrance/exit gadgets.
+- Select, multi-select, marquee-select, move, nudge, duplicate, copy/paste,
+  reorder, align/distribute, replace, randomize, and delete entries.
+- Save and load editor levels from local storage.
+- Export/import `.nxlv` editor levels.
+- Import/export classic `.lvl` through the classic runtime representation.
+- Validate common structural issues and apply quick fixes.
+- Playtest the editor level through the game runtime.
+- Expose editor state and operations through `window.__E2E__` for Playwright and
+  MCP tooling.
+
+Not implemented or not claimed in this checkpoint:
+
+- Full NeoLemmix section semantics for `$TERRAINGROUP`, `$TALISMAN`,
+  `$PRETEXT`, `$POSTTEXT`, multiple entrances/exits beyond classic limits,
+  custom trigger boxes, or style metadata.
+- Classic `.lvl` preservation of editor-only terrain flags such as `ONE_WAY`,
+  editor-only transforms, comments, unknown sections, or grouped terrain.
+- Solver-backed export blocking.
+- Pack/project bundle export.
+
+## Workflow Coverage Map
+
+| Workflow | Current coverage | Required checkpoint coverage |
+| --- | --- | --- |
+| Create playable level | Unit and harness coverage exists for editor state, tools, entrance/exit, round-trip workflow | Keep semantic create/validate/playtest/save/export/import test green |
+| Import `.nxlv` with unknown data | Parser/writer tests cover parts of preservation | Add explicit semantic round-trip for comments, unknown sections, terrain groups, and unsupported data warnings |
+| Classic `.lvl` import/export | Harness coverage exports/imports a classic level | Add lossy-export contract tests and cap validation before export |
+| Import failures | UI file handlers catch some read errors, but failures can still be console-oriented | Surface parse/read failures in editor status/validation UI |
+| Validation quick fixes | Unit coverage exists for validation and fix callbacks | Mark destructive fixes and expose that status to UI/E2E |
+| Visual states | Editor capture target exists | Split capture states for shell, palette/inspector, validation, file controls, and playtest |
+
+## UX Issues
+
+1. Classic-subset boundaries are too implicit. Users can import a richer `.nxlv`
+   and see a playable preview without understanding which data is preserved but
+   unsupported by preview/export.
+2. Classic `.lvl` export is available next to `.nxlv` export, but its lossy
+   nature is not prominent enough.
+3. Validation quick fixes can remove or clamp data. The UI needs to label those
+   actions as destructive when they drop unsupported properties or entries.
+4. Import failures should land in the same status/validation surface as normal
+   editor issues, not only browser alerts or console errors.
+5. Multi-selection is powerful but status text should keep reflecting batch
+   scope and avoid implying single-entry edits when multiple entries are active.
+
+## Correctness And Data-Integrity Risks
+
+1. Unknown `.nxlv` sections are preserved by the parser/writer, but regressions
+   would be easy without a focused semantic test.
+2. Terrain groups are preserved in the editor model and serialized back, but the
+   classic preview/runtime path does not implement full group behavior.
+3. Classic `.lvl` export cannot carry comments, unknown sections, terrain
+   groups, `ONE_WAY` terrain flags, or unsupported transforms.
+4. Classic runtime caps need validation before export: title length, object
+   count, terrain count, steel count, level size, entrance/exit limits, and
+   unsupported props.
+5. Object/gadget round-trip tests should compare meaningful fields, not merely
+   assert that import succeeds.
+
+## Prioritized Fixes
+
+P0:
+
+- Add visible classic-subset warnings for unknown sections, terrain groups,
+  unsupported NeoLemmix data, destructive fixes, and classic `.lvl` export.
+- Add semantic `.nxlv` and classic lossy round-trip tests.
+- Add classic export cap validation.
+- Fix import error reporting so bad `.nxlv` and `.lvl` files update editor
+  status/validation.
+
+P1:
+
+- Expand editor E2E coverage for visible warnings, import failures, and
+  semantic import/export acceptance.
+- Split editor capture targets by workflow state and keep outputs under
+  ignored `temp/`.
+
+P2:
+
+- Add a small multi-selection batch edit affordance only where the controller
+  already supports safe bulk operations.
+- Use audit captures to decide whether palette favorites or stronger recent
+  item affordances are worth the next editor milestone.
diff --git a/docs/level-editor/classic-subset-contract.md b/docs/level-editor/classic-subset-contract.md
new file mode 100644
index 00000000..816ab871
--- /dev/null
+++ b/docs/level-editor/classic-subset-contract.md
@@ -0,0 +1,51 @@
+# Classic-Subset Editor Contract
+
+The editor is productized as a classic-subset editor in this checkpoint. It can
+load richer `.nxlv` files, but the editable and playable contract is the classic
+runtime subset.
+
+## `.nxlv`
+
+- `.nxlv` is the preferred editor format.
+- Header fields, classic skill counts, terrain entries, gadget entries, steel
+  rectangles, comments, unknown lines, unknown sections, and terrain-group data
+  are preserved when parsing and writing the editor model.
+- Preserved does not mean previewed or editable. Unsupported sections remain
+  data-preservation payloads until NeoLemmix expansion work implements their
+  runtime and UI semantics.
+- Importing unsupported sections must produce a warning in the editor surface.
+
+## Classic `.lvl`
+
+- Classic `.lvl` import/export is for DOS/classic-compatible level data.
+- Export to `.lvl` is lossy by design. It cannot preserve comments, unknown
+  sections, terrain groups, editor-only terrain flags, custom NeoLemmix
+  sections, or unsupported transforms.
+- Classic export should run validation first and warn about classic caps before
+  bytes are written.
+- Classic import produces a clean editor model from the runtime-readable data;
+  any data absent from the classic format is not recoverable.
+
+## Validation And Quick Fixes
+
+- Errors identify conditions that make a level invalid for the editor's current
+  export/playtest path.
+- Warnings identify lossy, unsupported, or risky conditions that still allow
+  editing.
+- Quick fixes that clamp, delete, strip, or synthesize data must be visible as
+  data-changing actions. They should not be described as harmless cleanup when
+  they can drop unsupported properties or entries.
+
+## NeoLemmix Data
+
+The following NeoLemmix-oriented data is preserved where the current parser can
+round-trip it, but is not implemented as editor/runtime behavior in this pass:
+
+- `$TERRAINGROUP` semantics beyond preservation.
+- `$TALISMAN`, `$PRETEXT`, `$POSTTEXT`, pack metadata, and unlock rules.
+- Multiple entrances/exits beyond classic limits.
+- Custom trigger boxes and non-classic gadget semantics.
+- Advanced style metadata and non-classic skill definitions.
+
+Future NeoLemmix expansion should add parser/model/runtime/UI support before
+removing these warnings.
diff --git a/docs/level-editor/data-model.md b/docs/level-editor/data-model.md
index 3e0f5647..cbbc4509 100644
--- a/docs/level-editor/data-model.md
+++ b/docs/level-editor/data-model.md
@@ -55,5 +55,9 @@ Editor asset metadata is loaded from classic DAT files and used for:
 The editor mapping converts `EditorLevel` to classic runtime data:
 - `STYLE` -> `graphicSet1` via `StyleRegistry` ground set.
 - Terrain and gadget entries -> `LevelElement` with `DrawProperties`.
+- Terrain `ONE_WAY` is an editor/NXLV terrain flag and does not lower into
+  classic `.lvl` terrain data. Classic arrow behavior comes from one-way object
+  triggers, so preserving it requires explicit arrow gadgets rather than a
+  terrain flag round-trip.
 - `TIME_LIMIT` of `INFINITE` -> 6039 seconds (99:99) for classic runtime.
 - Steel rectangles are projected into classic `Level.steel` ranges.
diff --git a/docs/level-editor/design-overview.md b/docs/level-editor/design-overview.md
index 7d0fc116..e62689fe 100644
--- a/docs/level-editor/design-overview.md
+++ b/docs/level-editor/design-overview.md
@@ -1,8 +1,9 @@
 # Level Editor Design Overview
 
 ## Goals
-- Provide a fully featured in-game level editor for NeoLemmix `.nxlv`.
-- Support save/load to localStorage and import/export `.nxlv` files.
+- Provide a classic-subset level editor for `.nxlv` workflows.
+- Support save/load to localStorage plus import/export for `.nxlv` and
+  classic `.lvl` files.
 - Offer comprehensive tools for terrain, gadgets, triggers, entrances, exits, steel, and selection edits.
 - Keep editor logic deterministic and testable (100% coverage in `js/editor/**`).
 
@@ -38,7 +39,8 @@
 - LocalStorage entries:
   - `lemmings.editor.levels` (index)
   - `lemmings.editor.level.<id>` (NXLV text)
-- Import/Export uses file picker + Blob download.
+- Import/Export uses file picker + Blob download for text `.nxlv` and binary
+  classic `.lvl` payloads.
 
 ## Testing
 - All `js/editor/**` logic is covered at 100% via `npm run coverage-editor`.
diff --git a/docs/level-editor/history.md b/docs/level-editor/history.md
index 0a43081a..797ffba9 100644
--- a/docs/level-editor/history.md
+++ b/docs/level-editor/history.md
@@ -23,8 +23,14 @@
 
 ## Limits and coalescing
 
-- History keeps a configurable number of snapshots; the editor UI sets this to a very large cap for full-session history.
-- Drag operations coalesce into a single snapshot when the drag completes.
+- History keeps configurable entry and byte limits. The editor UI uses bounded
+  defaults (`maxEntries` and `maxBytes`) so long sessions cannot grow without a
+  retention cap.
+- Drag and brush operations commit one snapshot when the pointer interaction
+  completes. Programmatic batch edits can use explicit transactions to produce
+  one undo step.
+- When configured, adjacent snapshots with the same label can coalesce within a
+  short time window. History exposes `getStats()` for UI/debug telemetry.
 
 ## API
 
@@ -32,3 +38,5 @@
 - `undo()` / `redo()`
 - `canUndo()` / `canRedo()`
 - `clear()`
+- `getStats()`
+- `beginTransaction(label)` / `endTransaction(label)` / `cancelTransaction()`
diff --git a/docs/level-editor/neolemmix-expansion.md b/docs/level-editor/neolemmix-expansion.md
index a4c4af05..b7af7187 100644
--- a/docs/level-editor/neolemmix-expansion.md
+++ b/docs/level-editor/neolemmix-expansion.md
@@ -34,8 +34,42 @@ Status: no NeoLemmix expansion features are implemented yet; this is a backlog.
 - Custom trigger areas and rotation modes not supported by classic renderer.
 - Gimmicks (zombies, water, clock terrain, etc.) need engine support to preview.
 
-## Suggested phasing
-1. Parser/writer expansion for the new sections.
-2. Editor data model additions + UI panels.
-3. Validation + pack metadata tooling.
-4. Runtime preview parity work.
+## Phased implementation plan
+
+1. Parser and writer preservation:
+   - Parse and round-trip `$LEMMING`, `$TALISMAN`, `$PRETEXT`, `$POSTTEXT`,
+     `$TERRAINGROUP`, expanded `$GADGET` fields, `levels.nxmi`, and
+     `info.nxmi`.
+   - Acceptance: unknown values survive save/export, unsupported sections are
+     visible in validation, and classic subset export warnings remain explicit.
+
+2. Data model hard cutover:
+   - Add typed model fields for placed lemmings, terrain groups, talismans,
+     text blocks, custom trigger boxes, style metadata, and pack metadata.
+   - Acceptance: editor state has one canonical owner for each feature; no
+     compatibility aliases or duplicate editable paths are introduced.
+
+3. UI editing slices:
+   - Add focused panels for terrain-group order/visibility, talisman goals,
+     pre/post text, lemming placement flags, custom trigger boxes, and pack
+     metadata.
+   - Acceptance: unsupported runtime-preview behavior is shown as warning-only
+     state beside the relevant controls.
+
+4. Validation and pack tooling:
+   - Extend validation reports from classic caps into NeoLemmix metadata,
+     cross-level references, missing style aliases, talisman constraints, and
+     pack ordering.
+   - Acceptance: pack export can emit a single report covering level-level and
+     pack-level issues without claiming solver-backed solvability.
+
+5. Runtime preview parity:
+   - Implement only the preview/runtime mechanics needed to make the UI truthful:
+     placed lemmings, custom trigger areas, rotation variants, zombies/water
+     where supported by engine work, and style variant resolution.
+   - Acceptance: features without runtime parity stay editable only when the UI
+     clearly marks them as preserved/unpreviewed data.
+
+Classic-subset behavior remains the stable baseline throughout these phases.
+Expansion work should add explicit unsupported-state warnings before enabling
+editing for any feature the runtime cannot preview truthfully.
diff --git a/docs/level-editor/remaining.md b/docs/level-editor/remaining.md
index 302d5abd..d09a7f82 100644
--- a/docs/level-editor/remaining.md
+++ b/docs/level-editor/remaining.md
@@ -19,9 +19,36 @@ The classic subset editor is implemented; items below remain out of scope.
 
 ## Workflow
 - Live keybinding editing UI.
-- Project export bundles (pack structure, metadata, validation).
 - Level versioning and multi-file history.
 
 ## Validation
-- Pack-level consistency checks (cross-level references).
 - Advanced rule validation (talismans, skill gating).
+
+## Project and Pack Workflow Design
+
+Project work should extend the current single-level editor without creating a
+second roadmap file. The durable contract is:
+
+- Local project storage owns editable project metadata, level ordering, the
+  active level id, and per-level `.nxlv` text.
+- Exported `.nxlv` owns one level and preserves comments or unknown sections
+  that the editor does not understand.
+- Classic `.lvl` export remains a lossy compatibility target and must keep
+  validation warnings for classic caps, unsupported properties, and preserved
+  NeoLemmix data.
+- Pack bundles own `levels.nxmi`, `info.nxmi`, style references, level order,
+  and a validation report summary for every included level.
+
+Initial UI entry points should stay small: project name, level list,
+duplicate/rename/delete, import errors, validation report export, and pack
+export. Pack export should refuse only true validation errors; classic
+lossiness and solver advisory findings remain warnings.
+
+## Pack-Level Validation
+
+The validation report contract is implemented as JSON so editor UI, harnesses,
+and future pack export code can share one shape. A report entry includes
+severity, blocker/export-blocker flags, target, message, destructive-fix
+metadata, and unsupported preserved-data markers. Pack-level checks currently
+cover missing levels, duplicate ids/titles, missing styles, and missing
+style-asset references when a style map is available.
diff --git a/docs/level-editor/ui-and-tools.md b/docs/level-editor/ui-and-tools.md
index 827e1e4b..4a2380d1 100644
--- a/docs/level-editor/ui-and-tools.md
+++ b/docs/level-editor/ui-and-tools.md
@@ -5,8 +5,12 @@ See `docs/level-editor/workflows.md` for end-to-end editing flows.
 ## UI layout
 
 - **Editor toolbar** (left of canvas): tool buttons and mode status.
-- **Palette panel** (right of canvas): tabs for Terrain, Gadgets, Triggers.
-- **Inspector panel**: properties for selected entry (position, flags, delete).
+- **Palette panel** (left side, below tools): tabs for Terrain, Objects, and
+  Triggers, with List/Grid view modes and Ctrl+wheel grid-density changes in
+  grid view.
+- **Inspector panel** (right side): properties for selected entry (position,
+  flags, ordering, alignment/distribution, piece replacement, randomized
+  replacement, transform scale, and delete).
 - **Saved levels**: the existing Saved dropdown stays available while editing.
 
 ## Tools
@@ -15,6 +19,7 @@ See `docs/level-editor/workflows.md` for end-to-end editing flows.
 - **Terrain stamp**: place a single terrain piece at cursor.
 - **Gadget stamp**: place a gadget (objects like entrance/exit/traps).
 - **Trigger stamp**: place gadgets filtered to trigger-only objects.
+- **MIDI Flag**: place the MIDI flag gadget used by MIDI-trigger workflows.
 - **Entrance**: places the entrance gadget.
 - **Exit**: places the exit gadget.
 - **Steel**: place a resizable steel rectangle (editor-only).
@@ -26,7 +31,8 @@ See `docs/level-editor/workflows.md` for end-to-end editing flows.
 
 - Selected entry is outlined on the preview.
 - Inspector reflects the selected entry’s properties.
-- Resize is offered when the entry exposes `WIDTH/HEIGHT`.
+- Resize is currently offered for steel rectangles; terrain/gadget dimensions
+  come from asset metadata unless a specific entry type supports sizing.
 - Copy/paste/duplicate operate on the current selection.
 
 ## Keyboard and mouse
@@ -39,7 +45,7 @@ See `docs/level-editor/workflows.md` for end-to-end editing flows.
 - Right click cancels placement or clears selection.
 - Alt-drag duplicates the active selection before moving it.
 - Arrow keys nudge the selection; shift+arrows nudge by the grid size.
-- Mouse wheel zoom and arrow-key panning still work in editor mode.
+- Mouse wheel zoom remains available. Arrow keys nudge selections while editing.
 - Preview reloads preserve the current viewport during edit operations.
 
 ## Brush feasibility
diff --git a/docs/level-editor/ui-spec.md b/docs/level-editor/ui-spec.md
index 2f2a922b..5f444a18 100644
--- a/docs/level-editor/ui-spec.md
+++ b/docs/level-editor/ui-spec.md
@@ -19,7 +19,8 @@ This spec defines the standalone editor page UI and interaction model for the cl
   - Left: tool palette, piece palettes, brush/snap controls.
   - Center: game canvas preview + status strip.
   - Right: header fields, selection inspector, validation output.
-- DOM overlay panels layered over the canvas using CSS grid; no canvas-rendered UI.
+- Side panels and the canvas are arranged in the editor CSS grid shell; no
+  canvas-rendered UI.
 
 ## Visual Style
 - High-contrast, print-like UI with warm neutrals.
@@ -30,10 +31,12 @@ This spec defines the standalone editor page UI and interaction model for the cl
 ## Header Bar
 - Title: "Lemmings Editor".
 - Level selectors (game type, group, level) for classic levels.
-- Saved levels dropdown (localStorage) with Save/Export/Import buttons.
+- Saved levels dropdown (localStorage) with New Level, Save, Export, Export
+  LVL, Import, Import LVL, Undo/Redo, dirty state, and Playtest controls.
 - Save prompts for a name before writing to localStorage.
 - Playtest toggle that resumes gameplay without leaving the editor.
-- Status chip showing: current style, selected tool, last action, playtest state.
+- Dirty chip shows Saved/Unsaved; the status strip shows cursor, grid,
+  edit/playtest state, and selection summary.
 
 ## Tools Panel (Left)
 - Tool buttons in a vertical stack:
@@ -41,6 +44,7 @@ This spec defines the standalone editor page UI and interaction model for the cl
   - Terrain Stamp
   - Object
   - Trigger
+  - MIDI Flag
   - Entrance
   - Exit
   - Steel
@@ -64,6 +68,9 @@ This spec defines the standalone editor page UI and interaction model for the cl
   - Optional flags (steel, trigger)
 - Active selection highlight per tab.
 - Search/filter input to narrow list (client-side only).
+- Recently used pieces appear in a compact strip, capped to the most recent
+  eight terrain/object/trigger selections.
+- List and Grid view modes; Ctrl+wheel adjusts grid density in grid view.
 
 ## Canvas Preview (Center)
 - Uses existing game renderer for live preview.
@@ -75,10 +82,11 @@ This spec defines the standalone editor page UI and interaction model for the cl
 - Selection summary:
   - Type (terrain/gadget)
   - Piece name + id
-  - Bounding box (from WIDTH/HEIGHT or asset sizes)
+  - Bounding box (from steel WIDTH/HEIGHT or terrain/gadget asset sizes)
 - Transform fields:
   - X, Y (number)
-  - WIDTH, HEIGHT (number, optional)
+  - WIDTH, HEIGHT for steel rectangles; terrain/gadget size fields are
+    informational unless supported.
   - Rotate (number, degrees, snapped to 0/90/180/270)
   - Flip H, Flip V (checkboxes)
 - Terrain-only flags:
@@ -119,7 +127,8 @@ This spec defines the standalone editor page UI and interaction model for the cl
 ## Interaction Model
 - Click to select; shift-click to multi-select; drag to move.
 - Drag a marquee box (marching ants) to select multiple entries.
-- Resize handles appear for single selection.
+- Resize handles appear for single resizable selections, currently steel
+  rectangles.
 - Brush/eraser: click and drag to paint/erase terrain stamps along the drag path.
 - Alt-drag duplicates the current selection before moving it.
 - Right-click clears selection.
@@ -131,7 +140,7 @@ This spec defines the standalone editor page UI and interaction model for the cl
 ## Accessibility
 - All buttons and inputs are keyboard-focusable.
 - Tool buttons are `<button>` elements with `aria-pressed`.
-- Validation list uses semantic headings and badges.
+- Validation list shows severity-styled issue rows and optional fix buttons.
 
 ## Errors & Warnings
 - Errors should block export but not prevent saving to localStorage.
@@ -139,5 +148,4 @@ This spec defines the standalone editor page UI and interaction model for the cl
 
 ## Future Extensions (Out of Scope)
 - Full NeoLemmix terrain groups and pre-placed skillsets.
-- Steel area editor tool.
 - Arbitrary terrain brush.
diff --git a/docs/level-editor/workflows.md b/docs/level-editor/workflows.md
index fe393cf2..5a097bc1 100644
--- a/docs/level-editor/workflows.md
+++ b/docs/level-editor/workflows.md
@@ -8,23 +8,43 @@ intentionally brief so it can stay current.
 1. Open `editor.html`.
 2. Use the tool list to pick Terrain, Object, Trigger, Entrance, Exit, Steel,
    Brush, or Eraser.
-3. Use the palette to pick a piece, then click or drag in the canvas.
+3. Use the palette to pick a piece, or reselect a recent piece from the palette
+   strip, then click or drag in the canvas.
 4. Use the inspector to edit coordinates, dimensions, or flags.
 5. Use Playtest to run the level without leaving the editor.
 
 ## Selection and transforms
 
 - Click to select an entry; shift-click or marquee to multi-select.
-- Drag to move selections; handles resize single selections.
+- Drag to move selections; handles resize single steel selections.
 - Use copy/paste/duplicate, and nudge with arrow keys (shift = grid size).
+- Use ordering, align/distribute, replace piece, randomize pieces with optional
+  seed/same-size matching, and transform scale for bulk selection edits.
 
-## Saved levels
+## Saved levels and files
 
+- New Level creates a blank editor level.
 - Save stores to localStorage and refreshes the Saved selector.
-- Export `.nxlv` for NeoLemmix-style workflows.
-- Import `.nxlv` or classic `.lvl` files to convert into editor levels.
+- The dirty chip shows Saved/Unsaved state for the current editor session.
+- Export and Import handle `.nxlv` editor levels.
+- Export LVL and Import LVL handle classic `.lvl` files.
+- Terrain `ONE_WAY` flags are preserved by `.nxlv` import/export only. Classic
+  `.lvl` export/import drops terrain `ONE_WAY`; classic one-way behavior must be
+  modeled as arrow/object gadgets separately.
 
 ## Validation
 
 The Validation panel lists issues with quick-fix actions where possible. Fix
 errors before exporting.
+
+## Visual checks
+
+Use `npm run capture:e2e:editor` for a disposable desktop capture. The capture
+setup stages a selected terrain entry, a saved-level option, validation issues,
+and playtest mode, then records the shell, canvas, palette, inspector, file
+controls, selection actions, validation list, playtest status, header rectangle,
+and viewport. The PNGs are written under ignored `temp/e2e-captures/` and can be
+attached manually to issues or review notes.
+
+For non-desktop checks, run the capture CLI directly with `--viewport=tablet` or
+`--viewport=mobile`.
diff --git a/docs/mcp/README.md b/docs/mcp/README.md
index c493deff..8280ac03 100644
--- a/docs/mcp/README.md
+++ b/docs/mcp/README.md
@@ -1,15 +1,17 @@
 # MCP docs
 
-This directory contains the MCP interface spec, implementation notes, and the Zod schema reference.
+This directory contains the shipped MCP usage docs, protocol reference, editor
+mutation contract, examples, and historical design notes.
 
 Files:
-- `docs/mcp/lemmings-mcp-interface-spec-memresources.md`
-- `docs/mcp/lemmings-mcp-implementation-notes-memresources.md`
-- `docs/mcp/lemmings-mcp-zod-schema.ts`
 - `docs/mcp/protocol-v2.md`
+- `docs/mcp/editor-apply.md`
 - `docs/mcp/protocol-mappings.json`
 - `docs/mcp/call-examples.md`
 - `docs/mcp/publishing.md`
+- `docs/mcp/lemmings-mcp-interface-spec-memresources.md` (historical design reference)
+- `docs/mcp/lemmings-mcp-implementation-notes-memresources.md` (historical implementation notes)
+- `docs/mcp/lemmings-mcp-zod-schema.ts` (schema reference snapshot)
 
 ## Server usage
 - Start the game server: `npm run start-https` (serves `https://localhost:8080`).
@@ -17,6 +19,8 @@ Files:
 - Override defaults with environment variables:
   - `LEMMINGS_MCP_BASE_URL` (default `https://localhost:8080`)
   - `LEMMINGS_MCP_PATH` (default `/?e2e=1`)
+  - `LEMMINGS_MCP_SURFACES` (optional CSV of enabled tool surfaces:
+    `game,editor,interact`; default enables all)
 
 ## Host notes
 - Codex CLI: configure a stdio MCP server that runs `node mcp/server.js`.
@@ -37,11 +41,20 @@ Files:
 ## Tool naming
 - Tool names are exposed with dots replaced by underscores (for host validation).
   Example: `state.get` becomes `state_get` (full tool: `lemmings.state_get`).
-- Short tool names are primary; legacy aliases remain for compatibility.
+- Short underscore tool names are the only supported call names.
+- MCP calls use the shipped underscore tool names exactly.
+
+## Tool surfaces
+- `game`: `session.*`, `time.*`, `state.*`, `lemming.*`, `skill.*`
+- `editor`: `editor.apply`, `objects.list`, `objects.place`,
+  `objects.update`, `objects.delete`
+- `interact`: `input.*`, `vision.*`, `watch.*`, `events.*`
+- Surface gating is controlled via `LEMMINGS_MCP_SURFACES`.
 
 ## Defaults (protocol v2)
 - `state.get` defaults to the compact preset.
 - Events default to `minimal` (only non-agent, trimmed fields).
+- `session.create.protocol` includes versioning and hard-cut tool naming metadata.
 
 ## Smoke test checklist
 - `session.create` returns a session id and `ready=true`.
diff --git a/docs/mcp/call-examples.md b/docs/mcp/call-examples.md
index 80d2bacd..17569b5e 100644
--- a/docs/mcp/call-examples.md
+++ b/docs/mcp/call-examples.md
@@ -3,6 +3,15 @@
 These examples use the short tool names (dots replaced with underscores) and the
 compact `state.get` preset defaults.
 
+Available tool sets by surface:
+- `game`: `session_create`, `session_close`, `time_pause`, `time_resume`,
+  `time_step`, `state_get`, `state_delta`, `lemming_summary`,
+  `lemming_select`, `skill_apply`
+- `editor`: `editor_apply`, `objects_list`, `objects_place`,
+  `objects_update`, `objects_delete`
+- `interact`: `input_action`, `input_keys`, `vision_capture`,
+  `vision_captureSequence`, `watch_create`, `watch_cancel`, `events_poll`
+
 ## Create a session with minimal events
 
 ```json
@@ -58,6 +67,62 @@ compact `state.get` preset defaults.
 }
 ```
 
+## List editor objects with paging + revision delta
+
+```json
+{
+  "sessionId": "<id>",
+  "kind": "terrain",
+  "page": 0,
+  "pageSize": 50,
+  "fields": "compact",
+  "sinceRevision": 12
+}
+```
+
+## Place, update, and delete editor objects via typed tools
+
+```json
+{
+  "sessionId": "<id>",
+  "objects": [
+    {
+      "kind": "terrain",
+      "piece": 1,
+      "x": 120,
+      "y": 80
+    }
+  ],
+  "options": {
+    "returnState": "editor"
+  }
+}
+```
+
+```json
+{
+  "sessionId": "<id>",
+  "updates": [
+    {
+      "ref": { "kind": "terrain", "uid": "t_123" },
+      "set": { "X": 140, "Y": 88 }
+    }
+  ],
+  "options": {
+    "returnState": "editor"
+  }
+}
+```
+
+```json
+{
+  "sessionId": "<id>",
+  "refs": [
+    { "kind": "terrain", "uid": "t_123" }
+  ]
+}
+```
+
 ## Debug: full state as a resource
 
 ```json
diff --git a/mcp_editor_apply_spec.md b/docs/mcp/editor-apply.md
similarity index 82%
rename from mcp_editor_apply_spec.md
rename to docs/mcp/editor-apply.md
index 5eda1df7..c2e7c731 100644
--- a/mcp_editor_apply_spec.md
+++ b/docs/mcp/editor-apply.md
@@ -1,13 +1,17 @@
 # MCP Tool Spec: `editor.apply` (Full Level Editor Control)
 
-This repository already exposes an MCP server (`mcp/server.js`) that can:
+This repository exposes an MCP server (`mcp/server.js`) that can:
 - create sessions and drive the UI with Playwright
 - fetch rich, structured state via `state.get` (including editor session + assets + validation issues)
 - apply in-game skills and input actions
 
-**What’s missing for “LLM-grade” level editing** is a *first-class mutating API* for the editor: something that can directly inspect and modify the editor model (header, skillset, terrain, gadgets, steel, selection, history), without relying on fragile mouse/keyboard automation.
+The `editor.apply` tool is the first-class mutating API for the editor. It can
+directly inspect and modify the editor model (header, skillset, terrain,
+gadgets, steel, selection, history), without relying on fragile mouse/keyboard
+automation.
 
-This spec defines **one new MCP tool**—`editor.apply`—that provides **complete read/write coverage of the editor’s functionality**, matching every editor UI tool and enabling reliable programmatic manipulation of every item in a level.
+This spec defines the shipped `editor.apply` contract. The server exposes it as
+`editor_apply`.
 
 ---
 
@@ -45,8 +49,8 @@ This spec defines **one new MCP tool**—`editor.apply`—that provides **comple
 
 ## Tool name
 
-Internal tool name (MCP server): `editor.apply`  
-External tool name (as exported by `mcp/server.js`): `editor_apply` (because the server replaces `.` with `_`)
+Internal canonical name: `editor.apply`
+External call name: `editor_apply`
 
 ---
 
@@ -274,7 +278,7 @@ Loads a full NXLV text blob into the editor session.
 ---
 
 #### `level.loadSaved`
-Loads a saved level from local storage (as listed in `state.get.editor.storage.savedLevels`).
+Loads a saved level from local storage (as listed in `state.get.editor.savedLevels`).
 
 **Args**
 ```jsonc
@@ -667,44 +671,25 @@ Runs `validateLevel` and returns issues (same as editor UI list).
 | Selection inspector edits | `entry.update` (or `selection.set` + `entry.update`) |
 | Ordering buttons | `entry.reorder` |
 | Delete selection | `entry.remove` |
-| Validation fixes | `validate.run` with `autoFix`, or `issue.fix` optional future op |
+| Validation fixes | `validate.run` with `autoFix` |
 | Undo/Redo | `history.undo`, `history.redo` |
 | Viewport preservation | `preview.preserveViewport` |
 
 ---
 
-## Implementation notes (where to hook in this codebase)
+## Implementation map
 
-### A) Extend the E2E harness (`js/app/e2eHarness.js`)
-Add a new method, e.g.:
+This contract is shipped.
 
-- `editorApply(ops, options)`
-- `editorExport(format, options)`
-- `editorHistoryGet(index)`
-
-These should:
-- locate the editor controller via `context.view.editorUi?.controller`
-- mutate `controller.session.level` via existing controller methods whenever possible
-- call `controller.history.pushSnapshot(...)` when requested
-- trigger preview via the already-wired `onPreviewRequest` callback *or* by calling `view.loadEditorPreviewLevel(...)` directly when `preview.refresh=true`
-- return structured results (per-op success + values)
-
-### B) Add the MCP tool in `mcp/server.js`
-- Define `EditorApplySchema` (zod) matching this spec
-- Add tool entry `{ name: 'editor.apply', ... }` into `TOOL_SPECS`
-- Implement handler:
-  - validate session exists
-  - call `callE2E(session, 'editorApply', ops, options)`
-  - if `level.export` produces bytes/text: store via `resourceStore.put(...)`
-  - return resources + optionally new state
-
-### C) Stable `uid` support
-This is the single biggest usability win for LLM editing.
-
-Suggested implementation strategy:
-- when a level is loaded or created, walk all entries and ensure `entry.uid` exists
-- preserve `uid` on clone/duplicate/paste when desired, or generate new ones for clones
-- update selection serialization in `e2eHarness` to include `uid` in selection entries and refs
+- Browser harness entry: `window.__E2E__.editorApply(ops, options)`.
+- Harness implementation: `js/app/e2e/E2EEditorApply.js`.
+- MCP schema: `EditorApplySchema` in `mcp/schemas.js`.
+- MCP handler: `editorApplyTool` in `mcp/editorObjectTools.js`.
+- MCP routing: semantic `editor.apply`, exposed call name `editor_apply`.
+- Export results are returned as MCP session resources when the operation emits
+  text or bytes.
+- Stable entry `uid` values are ensured by the editor serialization/apply path
+  and are accepted in entry refs.
 
 ---
 
@@ -729,31 +714,30 @@ Suggested implementation strategy:
 }
 ```
 
-### Example 2: “Move every exit 32px right”
+### Example 2: “Move a known gadget 32px right”
 ```jsonc
 {
   "sessionId": "S1",
   "ops": [
-    { "type": "query.find", "args": { "kind": "gadget", "where": { "triggerEffectId": "EXIT_LEVEL" } } },
     { "type": "entry.update", "args": { "ref": { "kind": "gadget", "uid": "g_..." }, "set": { "X": 1232 } } }
   ]
 }
 ```
 
-(Where `query.find` is an optional but strongly recommended quality-of-life op.)
-
 ---
 
-## Recommended “minimum viable” subset (if you want to implement iteratively)
-
-If you want to ship quickly, implement in this order:
-
-1. `level.new`, `level.loadText`, `level.export`
-2. `entry.add`, `entry.update`, `entry.remove`
-3. `history.undo`, `history.redo`
-4. `validate.run`
-5. Tool parity wrappers: `tool.place`, `tool.stroke`, `tool.steelRect`
-6. Stable `uid` support + `query.find` + `selection.hitTest`
-
-That already enables an LLM to fully build and modify levels without UI automation.
+## Shipped operation families
 
+- Session/editor guard: `editor.ensure`.
+- Level lifecycle: `level.new`, `level.loadText`, `level.loadSaved`,
+  `level.save`, `level.export`, `level.importClassicLvl`, `level.patchHeader`,
+  `level.patchSkillset`.
+- Editor controls: `editor.setTool`, `editor.setBrushSettings`,
+  `editor.setPaletteSelection`.
+- Selection: `selection.clear`, `selection.set`, `selection.hitTest`,
+  `selection.boxSelect`.
+- Entries: `entry.add`, `entry.update`, `entry.remove`, `entry.duplicate`,
+  `entry.reorder`.
+- Tool parity: `tool.place`, `tool.stroke`, `tool.erase`, `tool.steelRect`.
+- History and validation: `history.undo`, `history.redo`,
+  `history.getEntry`, `validate.run`.
diff --git a/docs/mcp/lemmings-mcp-implementation-notes-memresources.md b/docs/mcp/lemmings-mcp-implementation-notes-memresources.md
index 4f9154d6..8f048f15 100644
--- a/docs/mcp/lemmings-mcp-implementation-notes-memresources.md
+++ b/docs/mcp/lemmings-mcp-implementation-notes-memresources.md
@@ -1,5 +1,9 @@
 # LemmingsJS MCP Implementation Notes (Playwright + MCP SDK/Inspector + In‑Memory Resources)
 
+Status: historical implementation notes. The shipped server is under `mcp/`,
+with current usage documented in [`README.md`](README.md) and
+[`protocol-v2.md`](protocol-v2.md).
+
 This document is the “how to build it” companion to the interface spec. It focuses on practical implementation choices, recommended dependencies, and development workflow using the MCP SDK + Inspector.
 
 ---
diff --git a/docs/mcp/lemmings-mcp-interface-spec-memresources.md b/docs/mcp/lemmings-mcp-interface-spec-memresources.md
index e5d324b4..24e73fcf 100644
--- a/docs/mcp/lemmings-mcp-interface-spec-memresources.md
+++ b/docs/mcp/lemmings-mcp-interface-spec-memresources.md
@@ -1,5 +1,10 @@
 # LemmingsJS MCP Interface Spec (Playwright + Keyboard-First + In‑Memory Resources)
 
+Status: historical design reference. The shipped MCP behavior is summarized in
+[`README.md`](README.md), [`protocol-v2.md`](protocol-v2.md), and
+[`editor-apply.md`](editor-apply.md). Use this file for design background, not
+as the current call contract.
+
 This document defines a **practical MCP (Model Context Protocol) interface** for an agent to (1) control the LemmingsJS-MIDI game reliably using **existing keyboard shortcuts**, (2) **select a specific lemming by ID** and apply a skill, (3) query **structured state** (individual + aggregate lemming summaries), and (4) request **images** of the full game or subregions **on demand**, **every X ticks**, **as a sequence**, or **when a value changes**.
 
 It assumes the game is launched with the existing **E2E harness** enabled (`?e2e=1`), exposing `window.__E2E__` for state snapshots and deterministic time control.
@@ -142,10 +147,9 @@ to fetch the latest envelope when needed.
 ## 6) Tool names and responsibilities
 
 ### High-level tool groups
-Note: the MCP server exposes short tool names (primary) with dots replaced by
-underscores (`state.get` → `state_get`) to satisfy host naming constraints. The
-canonical names below are dotted; use underscores when calling (full tool:
-`lemmings.state_get`). Legacy aliases remain for compatibility.
+Note: the MCP server exposes short tool names with underscores (`state_get`) to
+satisfy host naming constraints. The grouped names below are for documentation;
+use underscores when calling (full tool: `lemmings.state_get`).
 
 ### High-level tool groups
 - **Session**: `session.*`
@@ -187,6 +191,8 @@ Create a new session and launch the game page.
 
 **Notes**
 - Must wait until `__E2E__.getState().ready === true` before returning.
+- `spectator.openBrowser` is not supported. This server does not open a local
+  browser window for spectators.
 
 ---
 
@@ -298,6 +304,12 @@ Apply editor mutations through the E2E harness (batch ops + optional validation)
 **Outputs**
 - `{ ok, results[], state?, resources?, events }`
 
+**Failure modes**
+- `ok=false` with `reason="validation_failed" | "invalid_ops" | "editor_unavailable"`
+- When `atomic=true`, partial mutation failures must be rolled back.
+  If rollback itself fails, return `ok=false` and
+  `reason="rollback_failed"` with enough detail for operator triage.
+
 ---
 
 ### 7.8 `lemming.summary`
@@ -335,9 +347,9 @@ Directly select a specific lemming by ID.
 **Inputs**
 - `sessionId`
 - `lemmingId` (number)
-- `alsoCenterView` (optional, default `false`)  
+- `alsoCenterView` (optional, default `false`)
   If true, the server may pan the view so the selected lemming is visible (best-effort).
-- `confirm` (optional, default `true`)  
+- `confirm` (optional, default `true`)
   If true, re-read state and confirm `selectedIndex === lemmingId`.
 
 **Outputs**
diff --git a/docs/mcp/lemmings-mcp-zod-schema.ts b/docs/mcp/lemmings-mcp-zod-schema.ts
index d58a2822..78330b3e 100644
--- a/docs/mcp/lemmings-mcp-zod-schema.ts
+++ b/docs/mcp/lemmings-mcp-zod-schema.ts
@@ -1,6 +1,9 @@
 /**
  * LemmingsJS MCP - Zod Schemas (v1, memory-backed resources)
  *
+ * Historical schema reference snapshot. The current runtime schemas live in
+ * ../../mcp/schemas.js.
+ *
  * This file defines Zod schemas for tool inputs/outputs and shared types.
  * It targets the v1 MCP SDK and mirrors the interface spec in docs/mcp.
  *
diff --git a/docs/mcp/protocol-mappings.json b/docs/mcp/protocol-mappings.json
index b1a0c328..47bac80f 100644
--- a/docs/mcp/protocol-mappings.json
+++ b/docs/mcp/protocol-mappings.json
@@ -1,4 +1,9 @@
 {
+  "version": "2.1.0",
+  "schemaFrozenAt": "2026-02-23",
+  "acceptedToolNameForms": [
+    "underscore"
+  ],
   "skillNames": [
     "climber",
     "floater",
diff --git a/docs/mcp/protocol-v2.md b/docs/mcp/protocol-v2.md
index b62d067c..d3fa8b8b 100644
--- a/docs/mcp/protocol-v2.md
+++ b/docs/mcp/protocol-v2.md
@@ -10,8 +10,19 @@ implementation notes in this folder.
 - `state.get` defaults to the compact preset.
 - Events are minimal by default (`events.mode=minimal`), and tool
   responses include only non-agent events with trimmed fields.
-- Tool names are short and primary (dots mapped to underscores by hosts), with
-  legacy aliases retained for backward compatibility.
+- Tool names are short (dots mapped to underscores by hosts), and only the
+  short underscore forms are accepted.
+- `session.create.protocol` returns protocol version/freeze metadata and
+  hard-cut tool naming metadata.
+
+## Semantic editor object tools
+
+- `objects.list` provides typed listing with paging, bbox filters, and
+  revision-aware deltas.
+- `objects.place` inserts terrain/gadget/steel entries using typed payloads.
+- `objects.update` applies typed entry updates by index/uid references.
+- `objects.delete` removes entries by typed references.
+- `editor.apply` remains the batch editor mutation tool.
 
 ## Protocol mappings
 
@@ -28,7 +39,7 @@ implementation notes in this folder.
 
 ## state.delta
 
-- New tool for returning filtered history deltas.
+- Returns filtered history deltas.
 - Defaults to changes since the last `state.get` tick.
 - Supports filtering lemming fields and excluding x/y motion churn.
 
diff --git a/docs/mcp/publishing.md b/docs/mcp/publishing.md
index 4b2d78c8..bd4acc66 100644
--- a/docs/mcp/publishing.md
+++ b/docs/mcp/publishing.md
@@ -7,9 +7,9 @@ bundles plus GitHub registry publication. Streamable HTTP is not wired up yet.
 
 The MCPB bundle uses the repo root as the runtime base:
 
-- `mcp/server.js` (stdio server entry)
-- `mcp/spectator.html` (optional spectator UI)
+- `mcp/` (stdio server entry, tools, spectator UI, and support modules)
 - `keybindings.json` (tool input mappings)
+- `manifest.json`, `package.json`, `server.json`, `.mcpbignore`
 
 Use the MCPB bundle templates in `mcpb/` and build a staging bundle with:
 
@@ -19,6 +19,25 @@ node scripts/build-mcpb-bundle.js
 
 This creates `dist/mcpb/` with the files and templates needed for `mcpb`.
 
+Surface bundles are also available:
+
+```
+node scripts/build-mcpb-bundle.js --surface game
+node scripts/build-mcpb-bundle.js --surface editor
+node scripts/build-mcpb-bundle.js --surface interact
+```
+
+These output to `dist/mcpb-game/`, `dist/mcpb-editor/`, and
+`dist/mcpb-interact/` using the surface templates when present:
+
+- `mcpb/manifest.<surface>.json`
+- `mcpb/package.<surface>.json`
+- `mcpb/server.<surface>.json`
+
+If a surface-specific template is missing, the build falls back to the generic
+template for that file. The current repo ships surface-specific metadata for all
+three public surfaces.
+
 ## Dependencies
 
 The MCP server depends on `@modelcontextprotocol/sdk`, `@playwright/test`, `ws`,
@@ -43,7 +62,9 @@ npx @anthropic-ai/mcpb pack dist/lemmings-mcp.mcpb
 
 1. Create a GitHub release (tag `vX.Y.Z`) and upload the `.mcpb` asset.
 2. Compute SHA-256 for the `.mcpb` file.
-3. Update `mcpb/server.json` with the release URL and SHA-256.
+3. Update `mcpb/server.json` or the matching `mcpb/server.<surface>.json` with
+   the release URL and SHA-256.
 4. Publish with the MCP registry tooling (manual for now).
 
-See `mcpb/README.md` and `mcpb/server.json` for the exact fields and placeholders.
+See `mcpb/README.md` and the relevant `mcpb/server*.json` file for the exact
+fields and placeholders.
diff --git a/docs/midi-mapping.md b/docs/midi-mapping.md
index 01665c0c..49fa02c1 100644
--- a/docs/midi-mapping.md
+++ b/docs/midi-mapping.md
@@ -1,7 +1,9 @@
 # MIDI Mapping Cheatsheet
 
-This document summarizes the default MIDI mappings in `midi-mapping.json`.
-Edit that file to customize your setup.
+This document summarizes the factory MIDI template in
+[`../midi-mapping.json`](../midi-mapping.json). Fresh sequencer projects are
+created from this file, then editable state is stored in
+`lemmings.midi.project.v1`.
 
 For UI behavior and controls, see `docs/midi-ui.md`.
 
@@ -41,9 +43,6 @@ Default skill order:
 | 11 | accent | 0-1 | 0.4 |
 | 16 | scale.root | 0-11 | 0 |
 | 17 | scale.name | chromatic-minor, major, minor, dorian, mixolydian, pentatonic, chromatic | chromatic-minor |
-| 18 | position.xToNote | toggle | off |
-| 19 | position.yToVelocity | toggle | on |
-| 20 | position.yToTimbre | toggle | on |
 | 21 | position.viewPan | toggle | off |
 | 22 | repeat.maxRepeats | 0-32 | 0 |
 | 23 | repeat.windowBeats | 1-8 | 4 |
@@ -58,6 +57,21 @@ Default skill order:
 | 80 | timing.timeSignature.beats | 1-12 | 4 |
 | 81 | timing.timeSignature.unit | 1, 2, 4, 8, 16 | 4 |
 
+Position routing in the runtime mapper uses explicit entries in
+`position.mappings`. Legacy toggle-style flags such as `position.xToNote`,
+`position.yToVelocity`, and `position.yToTimbre` may still appear in older local
+data or input CC metadata, but they are ignored by the event mapper unless they
+are represented as explicit mapping entries.
+
+Fresh sequencer projects import those explicit `position.mappings` as project
+automation lanes. The sequencer lowers enabled lanes back into the runtime
+mapping, while global intensity, accent, envelope defaults, and view pan are
+stored in the project global block.
+
+Project import/export JSON is sanitized through the same canonical project
+model. Exported templates use the same project shape with hardware device ids
+and enabled state cleared before storage or reset.
+
 ## Target ranges
 
 These ranges are used by positional modifiers and defaults when min/max values
@@ -76,9 +90,12 @@ are omitted. Values outside the ranges are clamped.
 
 ## Customization tips
 
-- Edit the `input` section in `midi-mapping.json` to change note or CC mappings.
-- Use `input.channel` to switch between omni and a specific MIDI channel.       
-- Mapping changes take effect on refresh.
+- Use the in-game sequencer UI for editable mappings, clips, tracks, devices,
+  modulation, import/export, user templates, and audition.
+- Edit `midi-mapping.json` only to change the factory template used by fresh
+  projects and reset.
+- Use project `devices.inputChannel` to switch between omni and a specific MIDI
+  channel.
 - There is no standard MIDI CC for time signatures; the defaults use CC 80/81,
   but you can remap or disable them in `midi-mapping.json`.
 
diff --git a/docs/midi-sequencer-architecture.md b/docs/midi-sequencer-architecture.md
new file mode 100644
index 00000000..5ecaf82c
--- /dev/null
+++ b/docs/midi-sequencer-architecture.md
@@ -0,0 +1,126 @@
+# MIDI Sequencer Architecture
+
+The in-game MIDI surface is now project based. `midi-mapping.json` remains the
+factory template, but editable state lives only in
+`lemmings.midi.project.v1`.
+
+## Project Model
+
+`js/midi/project/MidiProject.js` owns the canonical `MidiProject` shape:
+
+- project metadata, devices, transport, global ranges, tracks, sources, clips,
+  automation, and UI selection.
+- direct mappings, including chord, arp, pan, timbre, and pitch-bend payloads,
+  plus clip-backed source routing for audition and gameplay routing.
+- validation for channels, notes, velocities, durations, selected ids, clips,
+  tracks, and malformed source mappings.
+- sanitized project/template import and export envelopes for JSON interchange.
+- conflict detection for duplicate runtime keys, missing references, muted or
+  solo-hidden routes, empty mappings, output availability, and range clamping.
+- deterministic reducer intents for setup, device selection, track creation,
+  source assignment, direct mapping edits, clip creation, step edits,
+  automation lane edits, global modulation edits, and UI selection.
+
+Tracks carry channel, instrument label, mute, solo, arm, velocity scale,
+priority, and voice budget. Sources carry a source kind/key, label, track route,
+direct-or-clip mode, direct mapping, and optional clip id.
+
+Clips currently support compact step, chord, and arp payloads. Step data stores
+note, velocity, optional duration, probability, hold, and tie. Arp payloads
+store a direction mode and optional pattern preset. The first clip runtime
+adapter lowers playable steps into existing direct mapping fields:
+simultaneous clip notes become `notes`, and arp clips add the existing `arp`
+mapping shape.
+
+Automation lanes are project-owned positional mappings. The factory template's
+`position.mappings` entries import as automation lanes with axis operators, and
+the adapter lowers enabled global lanes back into explicit runtime
+`position.mappings`. Global envelope defaults lower alongside direct mapping
+overrides. Global
+intensity, accent/density, envelope defaults, and view pan live under
+`project.global`; per-track velocity scale is applied to both direct and clip
+runtime mappings.
+
+## Storage Cutover
+
+`js/midi/project/MidiProjectStorage.js` reads and writes only
+`lemmings.midi.project.v1` for the active editable project. User templates are
+stored separately in `lemmings.midi.templates.v1`; they are sanitized snapshots
+of a project with hardware device ids and enabled state cleared.
+
+On load and reset the storage layer removes obsolete MIDI keys such as
+`lemmings.midi.intent`, `lemmings.midi.overrides`, old device ids, tab state,
+section state, schema hash, and the old audition feature flag.
+
+Old local override data is intentionally not migrated, and runtime override
+fallback paths are hard-cut from the sequencer path. A missing project creates a
+fresh project from the current factory template. Reset can target the factory
+template or a saved user template.
+
+## Runtime Adapter
+
+`projectToMidiConfig(project, factoryConfig)` converts the active project into
+the runtime `MidiMapping` config consumed by `MidiEventRouter` and
+`MidiScheduler`. The runtime path remains project-driven; legacy override
+fallback paths are not editable contracts.
+
+`detectMidiProjectConflicts(project, options)` is a pure project-domain report
+used by the UI and tests. It inspects raw references before sanitizer repair,
+then groups issues by source, track, and clip so the browser can badge sources
+and the inspector can explain the selected route.
+
+The adapter:
+
+- preserves direct SFX and trigger mapping behavior.
+- lowers clip-mode sources into the same SFX/trigger mapping maps by emitting
+  `note`, `notes`, `velocity`, `durationTicks`, and optional `arp`.
+- writes SFX sources to `config.sfx` and trigger/MIDI flag sources to
+  `config.triggers`.
+- applies project enabled state, input channel, transport tempo/meter plus
+  quantize/swing settings, scale, ranges, MPE, limits, density/accent, envelope
+  defaults, automation mappings, and reverse settings.
+- maps track channel and priority into direct mappings.
+- honors mute and solo by disabling mappings hidden by track state.
+- applies per-track velocity scale to direct and clip mappings before routing.
+
+Per-track output ids and voice budgets lower into runtime mappings and are
+resolved by the router/scheduler dispatch path. Tracks without an explicit
+output use the selected project output.
+
+## UI Regions
+
+The `/` route uses `#midiSequencerWorkspace` over the game canvas:
+
+- `#midiTransportStrip`: enable, input, output, input channel, BPM, time
+  signature, template selection, reset, project import/export, panic, status,
+  and device errors.
+- `#midiSourceBrowser`: source search, category filter, assignment/conflict
+  filter, and source list with conflict badges.
+- `#midiTrackWorkspace`: track list, clip library, selected-source summary,
+  and assignment controls.
+- `#midiInspector`: selected track, source mapping, conflict summary,
+  modulation controls, clip assignment, and step pattern controls.
+- `#midiOutputStatus`: scheduler pressure and recent output log.
+
+The old two-pane Events/Triggers/ADSR tabs and their storage behavior are
+removed.
+
+Learn and record modes are intentionally transient UI state. `MidiInputController`
+supports note capture for Learn and message capture for recording; the sequencer
+installs those hooks only while the mode is active, then clears them on commit,
+cancel, dispose, or controller replacement. Learn captures one selected
+direct-source note assignment. Recording captures note-on/note-off messages into
+consecutive steps of the selected clip and commits through normal
+`clip.step.update` reducer intents.
+
+## Validation
+
+Focused unit coverage lives in:
+
+- `test/midi/midi-project.test.js`
+- `test/midi/midi-project-storage.test.js`
+- `test/midi/midi-ui-controller.test.js`
+
+Playwright coverage for the visible workspace lives in `e2e/midi-ui.spec.js`.
+Disposable visual captures use `npm run capture:e2e:midi` and write under
+`temp/e2e-captures/`.
diff --git a/docs/midi-ui.md b/docs/midi-ui.md
index 10de86b5..d825b8ce 100644
--- a/docs/midi-ui.md
+++ b/docs/midi-ui.md
@@ -1,28 +1,132 @@
-# MIDI UI guide
+# MIDI UI Guide
 
-The MIDI UI is split into left and right control panes. Enable MIDI before
-editing mappings; the toggle state persists in localStorage.
+The MIDI UI is an in-game sequencer workspace layered over `/`.
 
-## Left pane
+## Setup
 
-- MIDI enabled: master toggle. Disabling detaches the router.
-- Reset all: clears stored overrides and UI state back to defaults.
-- I/O section: input, output, input channel, and MIDI reset.
-- Base BPM: master sequencing tempo; current BPM reflects game speed.
-- MIDI Debug: shows the last MIDI input and output message.
-- Global FX tab:
-  - Intensity and Accent sliders adjust velocity and density scaling.
-  - Positional Modifiers map X/Y to targets with optional operators and min/max
-    ranges.
-  - Global Repeat applies a beat window, max count, and scaling target.
+- Enable: attaches or detaches MIDI routing.
+- Input and Project Output: select the WebMIDI input and default output device
+  when available.
+- Channel: input channel, either `omni` or 1-16.
+- BPM, Beats, Unit, Key, Scale, Quant, Swing: transport tempo, meter, key/scale,
+  and quantize/swing project settings exposed to the MIDI runtime config.
+- Template: choose the factory template or a saved user template for reset.
+- Reset: creates a fresh project from the selected template.
+- Reverse Panic: enables all-notes-off when reverse playback is toggled.
+- Save Template, Export, Import: save reusable project templates and move
+  sanitized project JSON in or out of the sequencer.
+- Panic: sends all-notes-off and clears queued MIDI notes.
 
-## Right pane
+## Workspace
 
-- Events: configure each SFX event with note/degree/chord modes.
-- Triggers: map trigger events with optional arpeggiators.
-- ADSR: per-target envelope overrides for attack/decay/sustain/release.
+- Sources: browse SFX, triggers, MIDI flags, system, and procgen sources with
+  search, category, changed, current-level availability, assignment, conflict,
+  and clean filters. Filter counts are announced as status text, and conflicted
+  rows expose the first conflict message in the row label.
+- Tracks: create and select tracks, set optional per-track output, channel,
+  instrument label, mute, solo, arm, velocity scale, priority, and voice budget.
+- Keyboard navigation: focus the Sources, Tracks, Clips, or step-pattern grid
+  fields and use Arrow keys, Home, and End to move through the active region.
+- Modulation: set global intensity, velocity range, note range, accent, density
+  window, density duration scale, view pan range/dead zone, timbre range, X-note
+  offset range, safety limits, duration defaults/range, and add, edit, or remove
+  compact position lanes with axis operators for note, velocity, pan, duration,
+  timbre, and envelope targets. Global envelope defaults set the baseline for
+  direct mappings unless a source has an envelope override.
+- Clips: create reusable step, chord, or arp clips, set arp direction and
+  pattern preset, and edit compact step patterns with note, velocity, duration,
+  probability, hold, tie, and rest controls.
+- Assignment: route the selected source to a selected track, or switch it from
+  direct mode to clip mode and assign a selected clip.
+- Inspector: edit the selected source direct mapping with note, degree, octave,
+  chord type/inversion, arp direction, velocity, duration, pan, timbre, pitch
+  bend, envelope override, clip, audition controls, and conflict warnings for
+  the selected route.
+  Changed sources can be reverted to the factory template mapping, or to the
+  project default for sources not present in the factory template.
+- Learn: arm a selected direct source, capture the next MIDI note-on as a
+  pending note/velocity/channel assignment, then commit or cancel it.
+- Record: capture a short mocked or live MIDI phrase into consecutive steps of
+  the selected step clip, then commit or cancel the transient recording.
+- Output Status: shows recent audition/output activity and scheduler pressure.
+
+## Conflict Checks
+
+The sequencer marks actionable source conflicts in the browser and explains the
+selected source in the inspector. Current checks cover duplicate runtime source
+keys, missing track or clip references, muted or solo-hidden routes, empty
+direct/clip mappings, unavailable output ids when device data is supplied, and
+notes that clamp outside the project range.
 
 ## Persistence
 
-UI state is stored in localStorage. Defaults come from `midi-mapping.json` and
-apply only when no stored value exists or after Reset all.
+Editable MIDI state is stored only in `lemmings.midi.project.v1`.
+`midi-mapping.json` is the factory template source for fresh projects and reset.
+Legacy localStorage keys from the old UI are deleted on load and are not
+migrated into the project.
+
+User templates are stored separately in `lemmings.midi.templates.v1`. Imported
+projects and saved templates are sanitized through the same project validator as
+factory projects.
+
+## E2E Hooks
+
+`window.__LEMMINGS_MIDI_UI__` exposes project-oriented methods:
+
+- `getProject()`
+- `dispatchProjectIntent(intent)`
+- `setProject(project)`
+- `resetProject(templateId?)`
+- `exportProject({ asTemplate?, download? })`
+- `importProject(payload)`
+- `importProjectFile(file)`
+- `saveProjectTemplate({ id?, name? })`
+- `getProjectTemplates()`
+- `getUiMetrics()`
+- `startLearn()`
+- `confirmLearn()`
+- `cancelLearn()`
+- `captureLearnNote(note, velocity, channel)`
+- `startRecording()`
+- `commitRecording()`
+- `cancelRecording()`
+- `captureRecordMessage(message)`
+- `audition({ sourceId?, trackId?, mapping?, clipId? })`
+- `panic()`
+
+`window.__E2E__` exposes:
+
+- `midiGetProject()`
+- `midiGetRuntimeConfig()`
+- `midiDispatchProjectIntent(intent)`
+- `midiResetProject(templateId)`
+- `midiExportProject(options)`
+- `midiImportProject(payload)`
+- `midiSaveProjectTemplate(options)`
+- `midiGetProjectTemplates()`
+- `midiGetUiMetrics()`
+- `midiStartLearn()`
+- `midiConfirmLearn()`
+- `midiCancelLearn()`
+- `midiCaptureLearnNote(note, velocity, channel)`
+- `midiStartRecording()`
+- `midiCommitRecording()`
+- `midiCancelRecording()`
+- `midiCaptureRecordMessage(message)`
+- `midiAudition(request)`
+
+## Visual and E2E Coverage
+
+- `npm run capture:e2e:midi` captures the sequencer regions under
+  `temp/e2e-captures/`.
+- Hardware-free MIDI checkpoint commands:
+  `npm run test-e2e -- e2e/midi-ui.spec.js`,
+  `npm run capture:e2e:midi -- --viewport=desktop --json`,
+  `npm run capture:e2e:midi -- --viewport=tablet --json`, and
+  `npm run capture:e2e:midi -- --viewport=mobile --json`.
+- `e2e/midi-ui.spec.js` covers first-run project creation, fresh-reset legacy
+  cleanup, setup, transport meter, project and per-track output routing, direct
+  mapping, clip creation/editing, clip assignment, import/export/template reset,
+  learn capture, short recording, modulation controls, track and clip removal,
+  clip duplication, audition, persistence, filters, conflict warnings, E2E
+  helper metrics, and responsive overflow checks.
diff --git a/docs/nl-pack-toolkit.md b/docs/nl-pack-toolkit.md
index 82044314..55c5adb4 100644
--- a/docs/nl-pack-toolkit.md
+++ b/docs/nl-pack-toolkit.md
@@ -21,7 +21,7 @@ Advanced tutorials describe how to modify files directly. The Toolkit saves
 
 ## Relation to this repository
 
-Each level pack directory in the repo (`lemmings/`, `lemmings_ohNo/`, `xmas91/`, `xmas92/`, `holiday93/`, `holiday94/`) contains files extracted from its original game or pack archive. The folders follow the general NeoLemmix layout described in [docs/levelpacks.md](docs/levelpacks.md) so the Node tools can load them via `NodeFileProvider`. `config.json` lists the packs and their level orders.
+Each level pack directory in the repo (`lemmings/`, `lemmings_ohNo/`, `xmas91/`, `xmas92/`, `holiday93/`, `holiday94/`) contains files extracted from its original game or pack archive. The folders follow the general NeoLemmix layout described in [levelpacks.md](levelpacks.md) so the Node tools can load them via `NodeFileProvider`. `config.json` lists the packs and their level orders.
 
 Custom graphics, music and sprites may be replaced in these folders if you
 wish to experiment with your own pack built from NeoLemmix assets.
diff --git a/docs/offline-tools.md b/docs/offline-tools.md
index d9cf7ac6..fc0e648a 100644
--- a/docs/offline-tools.md
+++ b/docs/offline-tools.md
@@ -74,6 +74,10 @@ Replaces sprites in an existing DAT archive with PNG data. Multiple frames can
 be supplied as a sprite sheet when `--sheet-orientation` matches the sheet
 layout.
 
+Implementation note:
+- Output serialization is streamed with backpressure handling, so patching large
+  DAT archives does not require a single full-size output allocation.
+
 ## packLevels.js
 
 ```
@@ -83,6 +87,32 @@ node tools/packLevels.js <level dir> <out DAT>
 Compresses a directory of 2048 byte `.lvl` files into a single DAT file. Useful
 for building custom level packs.
 
+Implementation note:
+- Packed bytes are streamed to disk as each level is processed to keep memory
+  usage stable on large level directories.
+
+## packPipeline.js
+
+```
+node tools/packPipeline.js unpack <input DAT> <out dir>
+node tools/packPipeline.js pack <meta.json> <out DAT>
+node tools/packPipeline.js patch <input DAT> <out DAT> --part <index> --offset <byte> --file <patch bin>
+```
+
+Provides a generic DAT workflow:
+- `unpack` writes each decompressed part to `part-###.bin` plus a `meta.json`
+  manifest.
+- `pack` rebuilds a DAT archive from the manifest and part files.
+- `patch` applies a binary patch to one decompressed part and writes a rebuilt
+  DAT in one step.
+
+Implementation notes:
+- `pack` rejects absolute, null-byte, or parent-traversal part paths in
+  `meta.json`; part files must stay inside the metadata directory.
+- Archive caches used by `NodeFileProvider` are bounded by entry count and
+  estimated payload bytes and can still be cleared explicitly with
+  `clearCache()`.
+
 ## archiveDir.js
 
 ```
diff --git a/docs/performance-benchmarks.md b/docs/performance-benchmarks.md
index 48d9ad34..cbe1fa35 100644
--- a/docs/performance-benchmarks.md
+++ b/docs/performance-benchmarks.md
@@ -20,8 +20,8 @@ are recorded consistently and without UI timing variance.
 1. Use the E2E harness and run the benchmark script:
    - `npm run bench-performance -- --mode=sequence`
 2. Review the JSON output for max TPS, max speed, and per-sample values.
-3. If investigating reverse playback cost, run with `--mode=reverse` once the
-   bench-reverse entry point is wired for that mode.
+3. If investigating reverse playback cost, run with `--profile=reverse` or
+   `--mode=reverse`.
 
 ## History stress test
 
diff --git a/docs/playwright-tests.md b/docs/playwright-tests.md
index ab965691..fec6df1e 100644
--- a/docs/playwright-tests.md
+++ b/docs/playwright-tests.md
@@ -1,30 +1,140 @@
 # Playwright Tests
 
-Playwright tests are opt-in end-to-end checks that live under `e2e/` and do not
-run as part of `npm test`.
+Playwright tests are opt-in end-to-end checks under `e2e/`. They do not run as
+part of `npm test`.
 
 ## Running
+
 - `npm run test-e2e:install`
 - `npm run test-e2e`
 - `npm run test-e2e:ui`
+- `npm run test-e2e -- e2e/harness.game.spec.js`
+
+Playwright defaults to `https://localhost:8080` and starts the HTTPS server via
+`npm run start-https`. To point tests at another same-origin server:
+
+```powershell
+$env:LEMMINGS_E2E_BASE_URL = "https://127.0.0.1:8080"
+npm run test-e2e
+Remove-Item Env:\LEMMINGS_E2E_BASE_URL
+```
+
+The server uses the self-signed certs in `certs/`. Replace those files locally
+if a trusted certificate is needed for a device or VM.
 
-## HTTPS dev server
-Playwright runs against `https://localhost:8080` and starts the server via
-`npm run start-https`, which uses the self-signed cert in `certs/`. If you need
-a trusted local cert, replace the files in `certs/` with your own.
+## E2E Harness
 
-## E2E harness
-Add `?e2e=1` to enable the test harness and `window.__E2E__` API. The current
-schema is documented in:
-- `docs/e2e-state.md`
-- `docs/e2e-editor-state.md`
+Add `?e2e=1` to enable `window.__E2E__`. The current schemas are documented in:
+
+- [`e2e-state.md`](e2e-state.md)
+- [`e2e-editor-state.md`](e2e-editor-state.md)
+
+Playwright specs use this harness for deterministic state snapshots, time
+control, editor mutations, MIDI project automation, and runtime capture
+rectangles.
 
 ## WebMIDI
-E2E tests can grant real MIDI permissions (Chromium-only) or use the stub in
-`e2e/helpers/webmidiStub.js` to avoid hardware dependencies. The stub is
-optional and should be used only when real MIDI access is unavailable.
-
-## Phased coverage plan
-1) MIDI UI: enable/disable flow, pane visibility, event list sanity.
-2) Level editor: load, tool selection, save/import basics.
-3) Game: initial load, basic controls, level navigation.
+
+Chromium can be granted MIDI permission through Playwright context options. For
+hardware-independent tests, use `e2e/helpers/webmidiStub.js`.
+
+## Disposable Visual Captures
+
+The visual capture CLI is a local developer aid for UI, editor, procgen, HUD,
+and docs review. It writes PNGs only under ignored `temp/e2e-captures/`. Do not
+commit generated screenshots, manifests, baselines, or image inventories.
+
+Start the server first when running the CLI directly:
+
+```powershell
+npm run start-https
+```
+
+Common commands:
+
+- `npm run capture:e2e:midi`
+- `npm run capture:e2e:editor`
+- `npm run capture:e2e:procgen`
+- `npm run capture:e2e:game-hud`
+
+Direct CLI form:
+
+- `node scripts/e2e-capture-rects.js --config=e2e/capture-targets/midi.js`
+- `node scripts/e2e-capture-rects.js --config=e2e/capture-targets/editor.js --viewport=tablet`
+- `node scripts/e2e-capture-rects.js --config=e2e/capture-targets/game-hud.js --target=game-runtime-hud --json`
+
+Supported flags:
+
+- `--config=<path>`: required config module.
+- `--base-url=<origin>`: overrides `LEMMINGS_E2E_BASE_URL` and the Playwright
+  default.
+- `--out-dir=<path>`: output directory; it must stay under
+  `temp/e2e-captures/`.
+- `--viewport=desktop|tablet|mobile`: viewport preset.
+- `--target=name[,name...]`: capture only named targets.
+- `--json`: machine-readable output.
+
+Capture configs export a plain object with optional async setup:
+
+```js
+export default {
+  name: 'example',
+  route: '/',
+  async setup(page) {
+    await page.waitForFunction(() => window.__E2E__?.getState?.()?.ready);
+  },
+  targets: [
+    { name: 'controls', type: 'selector', selector: '#midiSequencerWorkspace' },
+    { name: 'header', type: 'pageRect', rect: { x: 0, y: 0, width: 480, height: 120 } },
+    { name: 'canvas', type: 'runtimeRect', id: 'canvas' },
+    { name: 'stage-parts', type: 'runtimeRects', ids: ['game', 'gui', 'minimap'] },
+    { name: 'world-start', type: 'worldRect', rect: { x: 0, y: 0, width: 320, height: 160 }, padding: 8 },
+    { name: 'viewport', type: 'viewport' },
+    { name: 'page', type: 'fullPage' }
+  ],
+  probes: [
+    {
+      name: 'controls-overflow',
+      selector: '#midiSequencerWorkspace',
+      checks: ['horizontalOverflow', 'verticalOverflow', 'unexpectedScrollbar']
+    }
+  ]
+};
+```
+
+Target types:
+
+- `selector`: exactly one visible Playwright locator match.
+- `pageRect`: explicit page-space CSS-pixel rectangle.
+- `runtimeRect`: one rectangle id from `window.__E2E__.getCaptureRects()`.
+- `runtimeRects`: multiple runtime ids, or all available ids when `ids` is
+  omitted.
+- `worldRect`: world-space rectangle converted through the E2E harness.
+- `viewport`: current viewport screenshot.
+- `fullPage`: full-page screenshot.
+
+Visual probes report warnings by default. A probe with `required: true` makes
+matching issues fail the CLI. Supported checks are `horizontalOverflow`,
+`verticalOverflow`, `clippedText`, `zeroSizeVisibleText`, `hiddenFocusedElement`,
+`smallTapTarget`, and `unexpectedScrollbar`.
+
+When captures are useful for an issue or review, attach selected PNGs from the
+run directory manually. Keep `temp/e2e-captures/` disposable.
+
+## Milestone Capture Matrix
+
+Use the capture scripts as disposable review evidence for the active milestone
+lanes. They check layout overflow and produce local PNGs and JSON summaries, but
+they are not a replacement for behavior tests.
+
+| Surface | Command | Expected use |
+| --- | --- | --- |
+| MIDI desktop/tablet/mobile | `npm run capture:e2e:midi -- --viewport=desktop --json`; repeat for `tablet` and `mobile` | Verify setup, track mixer, source browser, clip editor, inspector, diagnostics, and import/export states after MIDI polish changes. |
+| Editor desktop | `npm run capture:e2e:editor -- --viewport=desktop --json` | Verify editor shell, palette, canvas, inspector, validation, import/export, and playtest states after editor changes. |
+| Procgen desktop | `npm run capture:e2e:procgen -- --viewport=desktop --json` | Verify the selected theme, generated frontier, newest pieces, debug panels, and camera readability after procgen changes. |
+| Solver advisory surfaces | `npm run capture:e2e:editor -- --viewport=desktop --target="validation-warnings,validation-inspector-with-warnings" --json` | Verify user-visible solver/editor advisory warnings and compact failure text after advisory surface changes. |
+| Shared HUD/runtime | `npm run capture:e2e:game-hud -- --viewport=desktop --json` | Verify game HUD and runtime capture rectangles after shared harness or HUD changes. |
+
+Record the capture command output directory in the issue closeout note. Leave
+the files under `temp/e2e-captures/`; do not commit screenshots, capture JSON,
+or generated manifests.
diff --git a/docs/port-info/README.md b/docs/port-info/README.md
index 2d5a3f29..7f9d20e9 100644
--- a/docs/port-info/README.md
+++ b/docs/port-info/README.md
@@ -1,24 +1,36 @@
 # Port Information
 
-This folder collects notes on porting the original Pascal Lemmix codebase to the JavaScript/Node project. Each document covers a specific subsystem or topic.
+This folder collects historical notes from porting the Pascal Lemmix codebase to
+the JavaScript/Node project. These files are source notes and comparison aids,
+not canonical descriptions of current JavaScript behavior.
 
-- [Prog infrastructure overview](prog-infrastructure.md)
-- [TApp lifecycle overview](TApp-overview.md)
-- [Lemmix Configuration Summary](lemix-config.md)
-- [Sound system overview](sound-system-overview.md)
+- [Architecture overview](architecture-overview.md)
 - [Base utilities overview](base-utilities.md)
+- [BASS integration notes](bass-integration.md)
+- [Compiler and resource includes](compiler-includes.md)
+- [Configuration formats](config-formats.md)
 - [DOS resource handling](dos-resource-handling.md)
-- [Game controller overview](game-controller.md)
 - [Forms and screen lifecycle](forms-overview.md)
+- [Game controller overview](game-controller.md)
+- [Game screen base](game-screen-base.md)
 - [GameScreen internals](gamescreens-others.md)
+- [Graphics32 integration](graphics32-integration.md)
+- [Lemmix actions](lemmix-actions.md)
+- [Lemmix configuration summary](lemix-config.md)
+- [Lemmix game logger](lemmix-game-logger.md)
+- [Lemmix game menu port](lemmix-game-menu-port.md)
+- [Lemmix lemming fields](lemmix-lemming-fields.md)
+- [Lemmix renderer](lemmix-renderer.md)
+- [Lemmix transition](lemmix-transition.md)
+- [Level base overview](level-base-overview.md)
 - [Level utilities](level-utilities.md)
 - [Meta.Structures constants and types](meta-structures.md)
-- [Voice Manager](lemmix-voice.md)
-- [Architecture overview](architecture-overview.md)
+- [Prog infrastructure overview](prog-infrastructure.md)
+- [Replay and hashing](replay-and-hashing.md)
+- [Resource packaging](resource-packaging.md)
+- [Skill assignments](skill-assignments.md)
+- [Skill panel toolbar](skill-panel-toolbar.md)
 - [Sound system overview](sound-system-overview.md)
 - [Styles system](styles-system.md)
+- [TApp lifecycle overview](TApp-overview.md)
 - [Voice manager](voice-manager.md)
-- [Compiler and resource includes](compiler-includes.md)
-- [BASS integration notes](bass-integration.md)
-- [Graphics32 integration](graphics32-integration.md)
-- [Configuration formats](config-formats.md)
diff --git a/docs/port-info/prog-infrastructure.md b/docs/port-info/prog-infrastructure.md
index c9693bd6..d9bd8a49 100644
--- a/docs/port-info/prog-infrastructure.md
+++ b/docs/port-info/prog-infrastructure.md
@@ -16,6 +16,6 @@ Caches keep heavy data like replays and styles in memory so screens can switch q
 
 ## Helper utilities (`Prog.Base`, `Prog.Data`, `Prog.Tools` and `Prog.Voice`)
 
-`Prog.Base` defines enums and constants shared across the engine. `Prog.Data` loads resources such as graphics or data files. `Prog.Tools` collects assorted helper procedures used throughout the codebase. `Prog.Voice` implements the voice manager that announces events; see [Lemmix Voice Manager Overview](../../port-info/lemmix-voice.md) for details.
+`Prog.Base` defines enums and constants shared across the engine. `Prog.Data` loads resources such as graphics or data files. `Prog.Tools` collects assorted helper procedures used throughout the codebase. `Prog.Voice` implements the voice manager that announces events; see [Voice manager](voice-manager.md) for details.
 
 These modules hide platform specifics so the game logic can stay portable. The JavaScript port implements similar helpers to keep code organized.
diff --git a/docs/procgen.md b/docs/procgen.md
index 788076a8..4e25b5ca 100644
--- a/docs/procgen.md
+++ b/docs/procgen.md
@@ -1,49 +1,137 @@
-# Procgen (Endless) Specification
+# Procgen Level-Piece Streaming Specification
 
-This page describes the standalone `procgen.html` experience: an endless,
-full-viewport Lemmings run with no HUD/minimap/cursor and a procedural ground
-generator that keeps the lemmings moving to the right.
+This page describes the standalone `procgen.html` runtime: an endless,
+full-viewport Lemmings run with procedural terrain streaming, no HUD/minimap,
+and no MIDI UI.
 
 ## Scope
-- Use the second pack (Oh No) assets and the second classic style (fire).
-- Full-viewport canvas, no MIDI UI, no HUD/minimap, no cursor.
-- Endless spawning: the level never ends and lemmings keep releasing.
-- Procedural ground extends to the right so lemmings continue traveling.
-- Camera stays centered on the rightmost lemming, with smooth follow.
-
-## Fixed constants
-- Game type: `OHNO` (second pack).
-- Style: `fire` (groundSet 1).
-- Level width: 8192 (long runway without reallocating buffers).
-- Level height: `DEFAULT_LEVEL_HEIGHT` (classic height).
-- Release rate: 50, release count: 50, save requirement: 0.
-- Time limit: `INFINITE` (endless mode handles time).
-- Ground height: 8 px.
-- Initial ground width: 240 px.
-- Ground segment width: 160 px.
-- Ground extension threshold: 80 px.
-- Lookahead distance: 240 px.
-- Camera follow lerp: 0.12.
-
-## Level bootstrap
-- Create an empty editor level and convert it via `loadEditorLevel`.
-- Add a single entrance gadget (`PIECE: 1`) near the left edge.
-- Place initial ground beneath the entrance so the first lemmings land safely.
-- Set `endless = true` on the view so spawning never stops.
-
-## Procedural ground rules
-- Track the rightmost lemming X.
-- If `rightmostX + lookahead >= groundEndX - threshold`, append a new ground
-  segment starting at `groundEndX`.
-- Clamp ground placement within level bounds.
-- Ground uses a single palette index for now (no terrain sprites yet).
-
-## Camera follow
-- Each tick, compute target X so the rightmost lemming is centered.
-- Smoothly lerp the camera toward the target (no snapping).
-- Use Stage clamping to keep the view within bounds.
-
-## E2E smoke checks
-- Page loads and `__E2E__.getState().ready` is true.
-- Lemmings spawn over time (count increases after steps).
-- View X increases as the rightmost lemming advances.
+- Pick exactly one compatible visual style/theme for a seeded run, then keep the
+  run visually coherent with that style's real terrain/decor pieces.
+- Run full-viewport canvas mode with hidden GUI/cursor and endless spawning.
+- Stream level pieces to the right while keeping camera follow smooth.
+- Track progression from the live rightmost viable lemming frontier, not from
+  lemming id or selected-lemming state.
+- Use minimal assists for generated local challenges without turning procgen
+  into constant AI control.
+- Keep long-run memory bounded for generated chunks, frontier tracking, and
+  assist decisions.
+
+## Runtime constants
+- Game type: `OHNO`.
+- Level width: `65535`.
+- Level height: `DEFAULT_LEVEL_HEIGHT`.
+- Release rate: `50`, release count: `50`, save requirement: `0`.
+- Time limit: `INFINITE`.
+- Ground height: `4`.
+- Initial ground width: `280`.
+- Camera follow smoothing: frame-time-based interpolation.
+- Seeded randomness: `?seed=<value>` controls deterministic style selection,
+  terrain placement, lookahead variation, and assist decisions.
+
+## Bootstrap flow
+- Build an `EditorLevel`, set procgen headers, and place one entrance gadget.
+- Convert via `loadEditorLevel`, then load into `Game` through `GameFactory`.
+- Set `view.endless = true` so release never stops.
+- Pick one style compatible with the active pack path. The selected style is the
+  run's theme and is exposed in debug/E2E state.
+- Resolve a procgen seed from `?seed=...` (fallback: stored value or timestamp),
+  derive independent RNG streams for style and terrain/AI, and persist the
+  active seed for replayability.
+
+## Theme and piece streaming
+- Terrain comes from the selected theme's actual asset catalog:
+  - ground-capable terrain pieces for the walkable route.
+  - sparse decorative terrain pieces away from the active route.
+  - simple obstacle shapes only when they are compatible with the route and the
+    current assist budget.
+- Piece placement maintains a stable baseline path with bounded rises, dips,
+  small gaps, small barriers, and safe landing surfaces.
+- Decoration must stay readable: avoid dense clusters around the active route,
+  overlapping decorative clutter, and pieces that obscure the next challenge.
+- Generated chunk tracking is bounded. Keep recent chunks/pieces for debugging,
+  but prune old entries once they are far behind the frontier.
+
+## Frontier and lookahead
+- The frontier is the rightmost viable live lemming position.
+- A viable lemming is active, not removed/disabled/dead/exploded, has finite
+  coordinates, and is not stale-stuck behind the active route.
+- If the previous frontier dies, turns around, or gets stuck, recompute from the
+  current live set instead of following its id.
+- Selected lemming changes do not affect frontier calculation.
+- The generator extends terrain when the distance from frontier to generated end
+  drops below a safe threshold. Threshold variation is allowed, but it must stay
+  inside fixed min/max bounds and never allow lemmings to reach an ungenerated
+  edge.
+
+## Minimal assist behavior
+- Assist decisions are local and budgeted.
+- Small gaps should prefer the minimum useful builder action.
+- Small barriers should prefer bash/dig/mine only when a local scan indicates a
+  real obstruction.
+- Safe drops should avoid spending a skill; intentional risky drops can assign a
+  floater before splat range.
+- Traversable terrain should produce a no-op decision and no skill spend.
+- Repeated failed attempts on the same lemming/challenge should be cooled down.
+- Generated local gaps emit bounded challenge certificates. The local tactical
+  solver verifies those certificates synchronously during generation; rejected
+  gaps are simplified or replaced with extended terrain according to the solver
+  fallback decision.
+- Dynamic non-gap assists also emit compact local challenge certificates for
+  barrier clearing and unsafe falls. These certificates record synchronous
+  accept/extend/replace/simplify decisions for debug and review, but they do
+  not mark a run solved; runtime replay remains the only full-route authority.
+
+## Production hardening notes
+- Hazard scans use a rebuilt hazard index instead of per-scan trigger-set
+  allocation.
+- Gap backlog pruning runs even with no active lemmings to avoid stale growth.
+- Terrain stamping reuses cached destination typed-array views per level buffer.
+- Asset-piece selection avoids temporary filtered arrays in hot paths.
+- Debug lists for recent chunks, generated pieces, assist decisions, and
+  per-lemming trackers are fixed-size rings or pruned arrays.
+
+## Debug and E2E state
+
+`window.__E2E__.getState().procgen` is the stable procgen debug surface. It
+should remain compact and JSON-safe:
+
+- `selectedTheme`: style/theme selected for this run.
+- `seed`: normalized procgen seed.
+- `generatedEndX`: current generated terrain extent.
+- `frontier`: rightmost viable lemming summary with `x`, `y`, `id`, `reason`,
+  and `tick`.
+- `lookahead`: current lookahead distance, threshold, and distance to generated
+  end.
+- `recentChunks`: bounded list of recent generated route chunks.
+- `recentCertificates`: bounded list of recent local challenge certificate
+  decisions, including source, result type, fallback action, and assist reason
+  when applicable.
+- E2E/debug URLs can force deterministic certificate coverage with
+  `gapChance`, `gapMinWidth`, `gapMaxWidth`, `recentCertificateLimit`, and
+  `procgenCertificateVerification` query parameters.
+- `recentPieces`: bounded list of recent stamped pieces, including style/theme.
+- `recentAssists`: bounded list of recent assist decisions and no-op scans.
+- `trackingSizes`: sizes of cooldown, stuck, gap, chunk, piece, and assist
+  tracking structures.
+
+This state is for tests and local debugging. It is not a save format.
+
+## Validation
+- `e2e/procgen.spec.js` verifies readiness, endless spawn progression, and
+  camera advance. Productization coverage also verifies one selected theme,
+  frontier/generated-end debug state, and bounded tracking summaries.
+- Unit tests in `test/procgen-controller.test.js`,
+  `test/procgen-terrain-stamper.test.js`, and
+  `test/procgen-asset-manager.test.js` cover stability/perf-sensitive behavior.
+- `npm run capture:e2e:procgen` captures the procgen viewport, canvas/runtime
+  rects, the frontier area, and newest generated pieces into ignored
+  `temp/e2e-captures/` for visual inspection.
+
+## Productization status
+
+This checkpoint productizes themed piece streaming, frontier-driven lookahead,
+minimal assists, and local certificate checks for generated gaps, non-gap
+barriers, and unsafe falls. The checks are bounded and local: terrain generation
+can simplify or replace local chunks, dynamic assists only record their local
+decision, and the runtime replay verifier remains authoritative for complete
+solutions.
diff --git a/docs/release-readiness.md b/docs/release-readiness.md
new file mode 100644
index 00000000..b6fc30f8
--- /dev/null
+++ b/docs/release-readiness.md
@@ -0,0 +1,24 @@
+# Release Readiness Checklist
+
+This checklist is validated by `npm run release-readiness`.
+All required sections must exist and remain fully checked before release.
+
+## Compatibility
+- [x] MCP semantic tool surfaces (`game`, `editor`, `interact`) verified against `docs/mcp/protocol-v2.md` and `docs/mcp/README.md`.
+- [x] Runtime/browser fallbacks validated for WebMIDI, OffscreenCanvas, ImageBitmap, and worker/offscreen render paths.
+
+## Migration
+- [x] MCP tool naming is hard-cut to shipped underscore names only.
+- [x] Persisted storage migrations were replayed on existing local data for editor and MIDI settings.
+
+## Performance
+- [x] Bench smoke gates pass (`npm run bench-smoke`) with no threshold regressions.
+- [x] Long-session gate logic is validated in CI tests (`test/bench-long-session.test.js`) and soak script is available for staged runs (`npm run bench-long-session-soak`).
+
+## Accessibility
+- [x] MIDI expressive controls keep keyboard navigation, labels, and focus behavior across desktop and mobile layouts.
+- [x] MIDI mapping and audition controls expose deterministic automation hooks for E2E coverage.
+
+## Runtime Controls
+- [x] Runtime query controls were exercised (`rollbackAll`, `rollbackRenderPresent`, `rollbackHistoryCodec`).
+- [x] MCP surface gating is controlled only by `LEMMINGS_MCP_SURFACES`.
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 573596b7..9492fafe 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -1,216 +1,759 @@
 # Roadmap
 
-This roadmap consolidates outstanding items from the README (In Progress,
-Roadmap, Bugs and Misc) plus the current workstreams. It is the single place to
-track ongoing and future work. Keep this roadmap current as work lands.
-
-## Phase 1: E2E harness adoption and baseline testing
-- [x] Expand game E2E coverage using `window.__E2E__` (startup, navigation,
-  saved-level ordering, time travel invariants, reverse playback).
-- [x] Add harness-backed regression tests for input and view controls.
-- [x] Add harness-backed MIDI UI tests once permission flows are stable.
-
-Notes:
-- "Ready" means the level is loaded, everything is visible and interactable, and
-  the game can advance without error.
-- Saved levels always follow default packs under a separate group label, sorted
-  by name then time.
-- Input/view regression should cover all controls.
-- MIDI UI tests should be UI-only when reliable MIDI access is not available.
-- Define and enforce invariants (state hash symmetry, lemming counts/positions,
-  minimap state, command log, sound events).
-
-## Phase 2: Editor testing and completion (multi-phase)
-- [x] Phase 2.0: Fix editor page layout (game view too low, side panels too large, top of game should be at top of window just like the game page)
-- [x] Phase 2.1: Verify core editor tools plus overlay/inspector coverage
-  (palette, placement, selection, brush, triggers, steel).
-- [x] Phase 2.2: Verify edit-mode toggle, input suppression, and level selection
-  loads into the editor while editing; confirm playtest flow.
-- [x] Phase 2.3: Cover editing workflows (multi-select, drag/resize,
-  copy/paste/duplicate, undo/redo, snap/nudge, delete/duplicate).
-- [x] Phase 2.4: Validate saved-level pipeline (saved dropdown, localStorage
-  persistence, import/export for `.nxlv` and classic `.lvl`).
-- [x] Phase 2.5: Evaluate brush/eraser feasibility (tileable assets + grid size)
-  and style registry coverage for terrain/gadgets.
-- [x] Phase 2.6: Ensure steel rectangle editing and resizable gadgets behave
-  correctly; enforce classic limits.
-- [x] Phase 2.7: Defer `.nxlv` round-trip tests/unknown section handling for now;
-  focus on editor runtime mapping validation (blank level defaults, preview
-  mapping, trigger behavior).
-- [x] Phase 2.8: Fix editor view jumps (layout/canvas offsets, scale, event
-  ordering).
-- [x] Phase 2.9: Polish UI/UX and editor documentation.
-
-Notes:
-- Cover all tools and inspector fields.
-- Show the saved-level selector only when saved levels exist; ordering/naming
-  is not important.
-- Brush grid sizes: 1/2/4/8/16/32; skip if assets are not tileable.
-- Define edit-mode toggle expectations (pause state, HUD visibility, command
-  suppression, playtest lock).
-- Clarify steel behavior/limits (mask rules, overlap handling, limit enforcement).
-- View-jump repro steps pending; do a brief exploration first.
-- Keep editor docs brief.
-
-## Phase 3: UX, input, and presentation
-- [x] Add a shortcut overlay toggle (game/editor) that fades in/out and is easy
-  to dismiss.
-- [x] Fix keyboard view navigation acceleration (too fast at either speed).
-- [x] Robust touch controls and ensure scaling on iPad.
-- [x] Improve the website (summary metadata for social embeds).
-
-Notes:
-- Overlay fade duration is 250 ms; use F1 and ? if possible; separate overlays
-  for game and editor.
-- Keyboard view acceleration should be smooth with a low max speed cap; Shift
-  should still feel useful for faster pan.
-- Touch targets: landscape by default; portrait only on larger tablets; use
-  sensible gesture mappings.
-
-## Phase 4: Time travel and history coverage
-- [x] Expand HistoryStore snapshots/deltas to cover mutable gameplay state
-  (lemmings, manager, triggers, objects, ground, minimap deaths, victory,
-  skills, timer, sound events).
-- [x] Reverse playback (toggle + step) with input suppression and HUD direction
-  indicator.
-- [x] Reverse playback updates minimap deaths and emits reverse sound events.
-- [x] Ignore game speed changes during reverse playback (speedFactor remains
-  stable while rewinding).
-
-Notes:
-- Determinism is explicitly out of scope for this phase.
-
-## Phase 5: MIDI sequencing and UI
-- [x] Iterate on the MIDI UI and mapping UX.
-- [x] Add MIDI debug display.
-- [ ] [Deferred] Ability to place flags to trigger MIDI events.
-
-## Phase 6: Performance and benchmarks
-- [x] Ensure any bench-specific metrics are surfaced via the e2e harness, ideally through their own function
-- [x] Evaluate bench modes (bench, bench2, benchSequence, benchReverse) for     
-  effectiveness and necessity.
-- [x] Standalone updated performance benchmark.
-- [x] Standalone stress test for history memory (ticks at 30x/60x/120x until    
-  exhaustion).
-- [x] Investigate GameTimer catchup slowdown as a perf spike failsafe.
-
-## Phase 7: Gameplay parity, packs, and assets
-- [ ] Find external references that confirm these things before implementing
-- [ ] Arrow walls: confirm builder bounce behavior, fix 2-2-19 left arrows,
-  consider built-stairs handling.
-- [ ] Traps: add missing squish, fix generic trap using splat death.
-- [ ] Bombs: remove ground overlapping steel to reveal it.
-- [ ] Super lemmings act twice per tick.
-- [ ] No palette-swapped frying animation (2-2-9, 1-4-30).
-- [ ] Building stairs off horizontal edge causes wraparound steps.
-- [ ] Pack navigation bugs: previous pack flashing/crash when navigating
-  1 -> 2 then past 2-4-20; cannot go back to version 1 from version 2.
-- [ ] Xmas 91/92 and Holiday 93/94 polish (steel sprite data, triggers,
-  palettes).
-- [ ] Pack decompression/patch/compression pipeline.
-- [ ] Full support for pack-specific glitches.
-- [ ] Support for other popular pack types.
-- [ ] High resolution and 32-bit color sprite support.
-- [ ] Procedural endless level generation.
-
-## Phase 9: Gamepad support (deferred)
-- [ ] [Deferred] Add `joypad.js` as a dependency and implement full gamepad
-  support (gameplay + editor bindings, navigation, remapping).
-
-## Phase 10: MCP automation + in-memory resources
-- [x] Build MCP server with `@modelcontextprotocol/sdk` (v1) and stdio transport,
-  plus npm scripts for local runs.
-- [x] Session management + Playwright boot for `https://localhost:8080/?e2e=1`
-  with localhost cert handling and focus management.
-- [x] Harness additions for MCP (notably `selectLemmingById`) and doc updates in
-  `docs/e2e-state.md` and `docs/mcp/`.
-- [x] Implement core tools: time control, `state.get`, lemmings summary, input
-  actions/keys, lemming select, and skill apply.
-- [x] In-memory resource store with LRU/TTL and `resources/read` (plus optional
-  `resources/list`) for `lemmings://` URIs.
-- [x] Vision capture tools (single + sequence) with manifest support.
-- [x] Events queue, watch create/cancel, and events poll with per-call envelopes.
-- [x] Spectator UI plus human input relay (opt-in).
-- [x] Host setup notes and smoke tests for Codex CLI, Claude Code, and LM Studio.
-
-Notes:
-- Default to stdio; LM Studio can use HTTP if needed.
-- Always include the events envelope when non-empty.
-
-## Phase 11: MCP client compatibility checks
-- [x] Add automated checks that capture Codex CLI/Claude Code/LM Studio versions,
-  verify MCP config formats, and flag format updates we need to track.
-
-## Phase 12: Broken tests
-- [ ] None recorded (latest run: `npm test`, no errors).
-
-## Phase 13: Procedural endless mode (procgen)
-- [x] Add `procgen.html` with full-viewport canvas, no HUD/minimap/cursor, no MIDI UI.
-- [x] Use pack/style 2 assets for the procgen level bootstrap.
-- [x] Define a basic procgen spec doc (fixed constants, endless spawning, safe landing platform, rightward ground extension).
-- [x] Implement rightmost-lemming camera tracking with clamping and smooth follow.
-- [x] Add minimal E2E smoke coverage for procgen readiness and endless spawning.
-
-## Phase 14: MCP v2 compact defaults and tool ergonomics
-- [x] Switch tool responses to compact JSON by default (no pretty printing) and
-  omit excluded sections instead of returning null placeholders.
-- [x] Make short tool names primary (dots mapped to underscores) and retain
-  legacy aliases for compatibility.
-- [x] Set default event envelopes to `minimal` and avoid auto-attaching agent
-  echo events unless explicitly requested.
-- [x] Shorten session/resource/watch/event IDs to reduce payload size and URI
-  length in responses.
-
-## Phase 15: MCP v2 deltas, summaries, and skill semantics
-- [x] Expose HistoryStore deltas via the harness and implement `state.delta`
-  with filtering defaults that suppress x/y motion churn.
-- [x] Fix lemming summary counts and top-K selection heuristics; support both
-  rect schemas and include selected lemming when requested.
-- [x] Add protocol mappings on `session.create` (skill names + lemming field
-  codes) and clamp non-finite skill counts to JSON-safe values.
-- [x] Improve `skill.apply` verification with skill-specific checks and
-  fast-fail when skills are unavailable.
-
-## Phase 16: MCP v2 docs, examples, and compatibility checks
-- [x] Document compact defaults, delta usage, and event modes in `docs/mcp/`.
-- [x] Update client call examples/configs for the short tool names and default  
-  compact preset.
-- [x] Add smoke tests for `state.get`/`state.delta`/`skill.apply` using the new  
-  defaults and update the compatibility matrix.
-
-## Phase 17: MCP client compatibility + MCPB publishing readiness
-- [x] Fold LM Studio into the MCP config examples and add Claude Desktop + VS
-  Code examples.
-- [x] Add MCPB bundle templates (manifest, server registry entry, mcpb ignore)
-  and document the packaging steps.
-- [x] Add a disabled-by-default CI workflow for MCPB validation (Windows/macOS).
-- [x] Update MCP docs with publishing/registry checklist and compatibility notes.
-
-## Phase 18: MCP editor.apply tool (editor mutation API)
-- [x] Add stable UID support for editor entries and expose them in editor state.
-- [x] Implement `editor.apply` in the E2E harness (ops, batching, history,
-  preview refresh, validation, export).
-- [x] Add `editor.apply` tool in MCP server + schema + docs and resources export.
-- [x] Add tests for editor.apply flows (new/load/save/export, entry CRUD,
-  selection, history, validate).
-
-## Phase 19: Editor audit fixes + parity guardrails
-  - [x] Load `terrainGroups` into editor preview/runtime or warn as unsupported.
-  - [x] Preserve section-local comments in NXLV round-trips.
-  - [x] Add validation caps for width/height/brush/steel sizes and unsafe header
-    values; clarify INFINITE time handling.
-  - [x] Hide/disable or implement unsupported inspector fields (rotate, flip H,
-    resize, one-way) and add warnings for gadget-only props in classic mode.
-  - [x] Add editor UX safety upgrades (history cap, dirty indicator, undo/redo
-    buttons, preview refresh label coalescing).
-
-## Phase 20: Procgen terrain stamping + assets
-- [x] Add procgen asset manager (terrain/object categorization from packs).
-- [x] Replace pixel writes with terrain-piece stamping and chunk streaming.
-- [x] Add decoration and hazard placement with counterplay rules.
-
-## Phase 21: Procgen AI director + solvability
-- [x] Add environment sensing primitives (drop/wall/gap/hazard scans).
-- [x] Implement skill-assist behaviors (builder, bash, mine, dig, floater,
-  blocker coordination).
-- [x] Add pacing/budget controls plus debug overlay for AI decisions.
+Historical completed roadmap entries live in git history. This file is the
+current source of truth for future work and should stay focused on active
+product and tooling direction.
+
+## Format
+
+Each milestone uses the same shape:
+
+- **Outcome:** What should be true for users or maintainers when the milestone
+  is done.
+- **Scope:** Work that belongs in the milestone.
+- **Workflow Coverage:** Real workflows that must be exercised, preferably by
+  headless Playwright or deterministic unit/integration tests.
+- **Deliverables:** Concrete code, docs, tools, or artifacts.
+- **Acceptance:** Observable completion criteria.
+- **Out of Scope:** Tempting work that should not be mixed into the milestone.
+
+Prefer hard cutovers over aliases, shims, fallbacks, or retired behavior tests.
+When a milestone replaces an old path, remove the old path in the same phase.
+
+## Sequencing
+
+1. Level editor audit and productization.
+2. Procedural generation productization.
+3. Solver and solvability platform.
+4. MIDI sequencer follow-up polish only when captures, tests, or real workflow
+   use expose a concrete gap.
+
+## Milestone 1: DAW-Like Multichannel MIDI Sequencer UI
+
+**Outcome:** The MIDI surface is a DAW-like multichannel sequencer for gameplay
+events. It should let users design, route, audition, sequence, automate, and
+perform MIDI responses with the polish expected from music software, while
+remaining deterministic and testable without real hardware.
+
+Current status: checkpointed on May 6, 2026. The project-based sequencer,
+source browser filters, track/clip editing, learn/record flows, modulation
+lanes, template import/export, legacy storage cleanup, per-track output
+dispatch, targeted mocked-device coverage, and disposable desktop/tablet/mobile
+captures are implemented. Remaining Milestone 1 work should stay limited to
+focused polish, missing runtime-confidence tests, and small editor controls
+rather than broad sequencer rewrites.
+
+**Product Goals**
+
+- Make first-run setup obvious: enable MIDI, pick devices, confirm permissions,
+  choose a starter template, hear a preview, and recover from device errors.
+- Treat game events, trigger flags, procgen events, and global modulation as
+  sequencer sources that can be assigned to tracks and channels.
+- Support multichannel routing with clear track strips, output devices,
+  channels, instruments, mute/solo/arm, velocity, priority, and panic controls.
+- Make editing musical: piano-roll style note entry, step sequencing, chord
+  editing, arpeggiators, envelopes, repeats, probability, swing, quantization,
+  and automation lanes.
+- Make mappings easy to understand at a glance: what is enabled, what changed,
+  what conflicts, what is silent, what track/channel it routes through, and what
+  global rules affect it.
+- Make live performance safe: all-notes-off, stuck-note detection, scheduler
+  pressure display, output log, device reconnect handling, and readable status.
+- Make recovery safe: undo/reset per field, mapping, clip, track, profile, and
+  whole project.
+
+**Sequencer Model**
+
+- Preserve the existing intent-style state model, but expand it into a canonical
+  MIDI project model:
+  - project metadata and schema version.
+  - devices and output routing.
+  - tracks with channel/output/instrument labels.
+  - event sources mapped to clips or direct mappings.
+  - clips/patterns for notes, chords, arps, repeats, and automation.
+  - global tempo/key/scale/quantization/swing settings.
+  - per-track and per-mapping envelopes, velocity curves, priority, and limits.
+  - diagnostics and migration metadata.
+- Hard-cut obsolete duplicate persistence paths after migration; do not keep
+  legacy aliases as editable contracts.
+- Define import/export JSON for MIDI projects and templates.
+- Support factory templates and user templates.
+
+**Interface Scope**
+
+- Transport and setup:
+  - device chooser.
+  - input channel and output routing.
+  - tempo/BPM and game-speed relationship.
+  - quantization and swing.
+  - MIDI reset and panic.
+  - device health and permission state.
+- Track mixer:
+  - multiple MIDI tracks.
+  - output device and channel per track.
+  - track name and instrument label.
+  - mute/solo/arm.
+  - track volume/velocity scale.
+  - priority and voice budget.
+  - scheduler pressure and recent output indicators.
+- Source browser:
+  - SFX events.
+  - trigger types.
+  - MIDI flags.
+  - procgen/challenge events when available.
+  - global/system events.
+  - search, category filters, changed-only, enabled-only, conflict-only,
+    available-in-level, and assigned/unassigned views.
+- Arrangement and pattern editing:
+  - map an event source directly to a note/chord/arp or to a reusable clip.
+  - clip/pattern library.
+  - step sequencer grid with note, rest, hold, tie, velocity, probability, and
+    channel/track awareness.
+  - compact piano-roll style editor for short MIDI phrases.
+  - chord builder with common shapes, inversions, voicing, and scale locking.
+  - arpeggiator editor with direction, pattern, rate, octave range, gate, and
+    reset behavior.
+  - repeat/rhythm editor that reads as musical timing rather than raw config.
+- Automation and modulation:
+  - envelope editor with curve preview.
+  - velocity curves.
+  - global intensity and accent.
+  - position-based modulation mapped to velocity, pitch, CC, repeat, density, or
+    track selection.
+  - per-track and per-event automation lanes where they add real value.
+- Inspector:
+  - selected source, track, clip, or step.
+  - contextual controls only.
+  - validation/conflict status.
+  - audition controls.
+  - reset/revert at the smallest useful scope.
+- Learn and recording:
+  - global Learn mode.
+  - arm a target from the inspector.
+  - capture note/channel/velocity.
+  - show pending assignment before commit.
+  - record a short step pattern from mocked or real MIDI input.
+  - detect and resolve conflicts.
+  - keyboard-only capture flow with mocked WebMIDI in tests.
+- Audition:
+  - preview selected mapping.
+  - preview clip/pattern.
+  - preview chord/arp over a short beat window.
+  - preview through the selected track/channel/output.
+  - preview with current key/scale/global shaping.
+  - visible output log and all-notes-off/panic.
+- Layout:
+  - desktop: stable DAW-like workspace with transport, browser, track/mixer, and
+    inspector regions.
+  - tablet: collapsible browser/inspector with the sequencer grid still usable.
+  - phone/narrow: task-focused single-column flows for setup, browse, edit, and
+    audition without clipped labels.
+- Accessibility:
+  - semantic controls.
+  - focus order matching visual order.
+  - keyboard navigation for browser, track list, piano keys, step grid, tabs,
+    template operations, and inspector controls.
+  - visible focus states.
+  - aria labels for icon-only controls.
+  - no hidden focused element when panels change.
+- Performance:
+  - no full mapping or track rebuild for single-field edits.
+  - large mapping sets and clip libraries remain responsive.
+  - no recurring layout thrash while MIDI input is active.
+  - UI refresh metrics exposed to diagnostics in E2E mode.
+
+**Workflow Coverage**
+
+- First-run no-device state with clear permission and device messaging.
+- First-run with mocked input/output devices.
+- Enable MIDI, choose input/output, configure tracks/channels, send reset, and
+  use panic.
+- Create a project from a factory template; edit it, duplicate it, export it,
+  import it, and reset it.
+- Create multiple tracks and route different event sources to different
+  channels.
+- Search and filter sources by text, category, enabled state, changed state,
+  conflict state, assigned state, and current-level availability.
+- Assign an event source to:
+  - direct note.
+  - chord.
+  - arp.
+  - step pattern.
+  - reusable clip.
+  - automation/modulation target.
+- Edit a step pattern with note/rest/hold/velocity/probability and verify the
+  generated MIDI events.
+- Use learn mode to capture a mocked note and resolve a conflict.
+- Record a short mocked MIDI phrase into a step pattern.
+- Audition a track, source mapping, chord, arp, and clip without real hardware.
+- Verify persistence across reload.
+- Verify migration hard-cuts obsolete storage after migration.
+- Desktop/tablet/mobile visual capture runs for setup, track mixer, source
+  browser, sequencer grid, inspector, learn, diagnostics, and import/export.
+
+**Deliverables**
+
+- New MIDI sequencer architecture docs.
+- Expanded canonical MIDI project state and migration.
+- Refactored UI modules for transport/setup, tracks, source browser, sequencer
+  grid, inspector, templates, learn, audition, diagnostics, and layout.
+- Project/template import/export UI.
+- Conflict detection and validation.
+- Expanded Playwright coverage using mocked WebMIDI and generic visual capture
+  helpers.
+- Focused unit coverage for project validation, sequencing, conflict detection,
+  scheduler reservations, migrations, and intent/project updates.
+
+**Acceptance**
+
+- A user can build a multichannel MIDI project from scratch without editing
+  JSON.
+- Game events can drive multiple tracks/channels with note, chord, arp, clip,
+  and automation behavior.
+- The UI works without MIDI hardware through the mocked test path.
+- Major MIDI sequencer states have disposable local captures and overflow
+  checks.
+- No obsolete legacy mapping UI or duplicate persistence path remains after the
+  migration/cutover phase.
+
+**Out of Scope**
+
+- Audio recording, audio mixing, plugin hosting, soft synths, or waveform
+  editing.
+- Supporting non-WebMIDI browser APIs.
+- Network sync or cloud project storage.
+
+## Milestone 2: Level Editor Audit and Productization
+
+**Outcome:** The level editor is evaluated from real workflows, then upgraded
+into a trustworthy creation tool with documented capabilities, clear limits,
+usable UX, and robust workflow tests.
+
+**Audit Scope**
+
+- Perform a current-state editor audit before changing behavior:
+  - layout screenshots across desktop/tablet/mobile.
+  - local `temp/` captures for major flows where visual evidence is useful.
+  - docs-vs-code matrix.
+  - implemented vs claimed feature matrix.
+  - severity-ranked UX issues.
+  - severity-ranked correctness/data-integrity issues.
+  - test coverage map for each workflow.
+- Evaluate the editor as a product, not just as code:
+  - how quickly a user can create a playable level.
+  - how easy it is to select, move, inspect, duplicate, align, reorder, and
+    delete pieces.
+  - whether validation explains problems and offers safe fixes.
+  - whether playtest flow feels connected to editing.
+  - whether import/export errors are understandable.
+  - whether classic subset limits are obvious.
+  - whether NeoLemmix limitations are explicit.
+
+**Productization Scope**
+
+- Workflow and navigation:
+  - New level.
+  - Open classic level.
+  - Open saved level.
+  - Import `.nxlv`.
+  - Import classic `.lvl`.
+  - Save locally.
+  - Export `.nxlv`.
+  - Export classic `.lvl`.
+  - Playtest and return to editing.
+  - Undo/redo across all meaningful edits.
+- Canvas UX:
+  - pan/zoom behavior that never fights placement.
+  - selection outlines and handles that remain visible at common zoom levels.
+  - marquee select.
+  - drag, nudge, duplicate, copy/paste.
+  - align/distribute and ordering controls.
+  - grid/snap controls that are visible and predictable.
+  - context actions for common operations.
+- Palette UX:
+  - terrain/object/trigger browsing with thumbnails.
+  - search/filter/sort.
+  - style switch behavior.
+  - missing asset handling.
+  - recently used pieces.
+  - favorites or pinned pieces if audit shows palette scanning is slow.
+- Inspector UX:
+  - single selection editor.
+  - multi-selection summary and batch edit.
+  - safe numeric editing with commit/revert behavior.
+  - transform controls.
+  - flags/properties only where they apply.
+  - selected entry identity, uid, type, and source style.
+- Validation UX:
+  - clear error/warning separation.
+  - fix buttons grouped by issue.
+  - export blocking only for true blockers.
+  - validation report export.
+  - pack-level consistency checks where data is available.
+- Data integrity:
+  - round-trip `.nxlv` comments and unknown sections.
+  - preserve unknown data that the editor does not understand.
+  - hard-cut unsupported runtime preview paths into explicit warnings.
+  - no silent data loss during import, save, export, playtest, or style switch.
+- NeoLemmix decision track:
+  - decide whether the editor remains a classic subset or expands.
+  - if expanding, phase parser/model/UI/runtime work for `$TERRAINGROUP`,
+    `$TALISMAN`, `$PRETEXT`, `$POSTTEXT`, lemming placement, custom trigger
+    boxes, and style metadata.
+  - document unsupported NeoLemmix features in the UI, not only in docs.
+- Project workflow:
+  - project or pack export bundle plan.
+  - level metadata and level list handling.
+  - local project storage strategy.
+  - import/export validation reports.
+
+**Workflow Coverage**
+
+- Create a blank level, place entrance/exit/terrain/steel/trap/MIDI flag,
+  validate, playtest, save, export, import back, and compare semantic state.
+- Load a built-in classic level, modify it, save locally, reload, and export.
+- Import `.nxlv` with comments, unknown sections, terrain groups, and unsupported
+  props; verify preservation or explicit warnings.
+- Exercise selection:
+  - click select.
+  - shift multi-select.
+  - marquee select.
+  - move.
+  - resize where supported.
+  - duplicate.
+  - copy/paste.
+  - reorder.
+  - delete.
+  - undo/redo each.
+- Exercise palette:
+  - search.
+  - style switch.
+  - thumbnail loading.
+  - missing asset state.
+- Exercise validation:
+  - missing entrance.
+  - missing exit.
+  - out-of-bounds pieces.
+  - invalid counts.
+  - unsupported classic props.
+  - terrain groups.
+  - steel bounds.
+- Exercise playtest:
+  - timer state.
+  - input suppression while editing.
+  - return to editor.
+  - history/seek/reverse interactions where relevant.
+- Run visual capture matrices for editor shell, canvas, palette, inspector,
+  validation, save/import/export, and playtest states.
+
+**Deliverables**
+
+- Editor audit report committed under `docs/level-editor/`.
+- Updated editor docs based on current behavior.
+- Expanded Playwright editor workflows using generic visual capture tooling.
+- UX fixes prioritized from the audit.
+- Clear classic-subset vs NeoLemmix-expansion decision and follow-up plan.
+- Optional project export design if the audit confirms it is the next highest
+  value editor workflow.
+
+**Acceptance**
+
+- The editor can create and round-trip a playable level through tested
+  workflows.
+- Major UX states have screenshot captures and overflow checks.
+- Unsupported or lossy operations are impossible or explicitly warned.
+- Editor docs match current behavior.
+
+**Out of Scope**
+
+- Implementing every NeoLemmix feature before the audit is complete.
+- Adding solver-backed validation before the solver milestone produces a stable
+  interface.
+
+## Milestone 3: Procedural Level-Piece Streaming
+
+**Outcome:** Procgen is an endless left-to-right mode that picks one visual
+theme, then efficiently and tastefully adds level pieces ahead of the lemmings
+as they progress. It should feel like a coherent generated Lemmings level, not
+random pixels or a stress-test mode with hazards sprinkled around.
+
+**Core Behavior**
+
+- Pick one theme/style for the run and stay visually coherent.
+- Build the world out of real level pieces from that theme:
+  - terrain pieces.
+  - decorative pieces.
+  - simple obstacles.
+  - occasional gadgets only when they make sense for the theme and generated
+    path.
+- Stream pieces from left to right as the lemmings advance.
+- Track progression from the actual rightmost viable lemming position, not from
+  lemming id. Lemmings can turn around, bounce, die, or get stuck, so the
+  generator must derive the lead edge from current positions and viability.
+- Maintain a generation lookahead that varies enough to avoid a mechanical feel
+  but always creates needed terrain before lemmings reach it.
+- Keep generation bounded and efficient:
+  - avoid full scans over all historic lemmings or pieces.
+  - prune old tracking state.
+  - track only recent/near-future generated chunks.
+  - avoid unnecessary allocations in per-tick logic.
+- Use minimal automatic skill assists only where basic generated challenges
+  require them:
+  - build over smaller gaps.
+  - dig or mine through smaller barriers.
+  - bash through simple horizontal obstructions.
+  - assign floaters only for small, intentional fall challenges.
+- Do not spam skills. The ideal run should look like occasional purposeful
+  interventions, not constant AI control.
+
+**Generation Scope**
+
+- Theme selection:
+  - choose a compatible style from available packs.
+  - expose the selected theme in the URL/debug state.
+  - allow deterministic seeds for repros.
+- Piece placement:
+  - maintain a stable baseline path.
+  - add rises, dips, small gaps, small barriers, and visual variety.
+  - use pieces with sensible overlap and no obvious floating/ugly seams.
+  - avoid unreadable clutter around the active path.
+  - prefer tasteful, theme-appropriate decoration away from the route.
+- Lookahead and pacing:
+  - calculate a lead lemming/frontier each update.
+  - decide when more terrain is needed based on distance to generated end,
+    current speed, release rate, and recent lead movement.
+  - vary the lookahead threshold within safe bounds.
+  - guarantee the next playable segment exists before it can be reached.
+- Challenge design:
+  - small gaps that can be bridged with a low number of builders.
+  - small barriers that can be dug, mined, or bashed.
+  - safe landing surfaces for intentional drops.
+  - avoid unavoidable traps, impossible gaps, hard steel blockers, and
+    challenge chains that require precise expert timing.
+- Assist design:
+  - detect the next simple challenge before contact.
+  - spend the smallest useful skill.
+  - prefer the lead viable lemming.
+  - avoid repeated attempts on the same failed situation.
+  - expose recent assist decisions for debugging.
+- Camera:
+  - follow progression smoothly.
+  - do not jump because an old or wrong-id lemming becomes selected.
+  - keep the generated path readable ahead of the lead.
+
+**Workflow Coverage**
+
+- Start procgen and verify it chooses exactly one theme for the run.
+- Verify generated pieces come from the selected theme.
+- Step through fixed seeds and assert generated end stays safely ahead of the
+  rightmost viable lemming.
+- Verify the lead frontier changes correctly when the previous lead turns,
+  bounces, dies, or gets stuck.
+- Verify small gaps trigger minimal builder usage.
+- Verify small barriers trigger minimal dig/mine/bash usage.
+- Verify no assist is spent when terrain is already traversable.
+- Verify generation continues for a long run without unbounded tracking growth.
+- Capture temporary local screenshots around the lead and newest generated
+  pieces when debugging visual quality.
+
+**Deliverables**
+
+- Clear procgen spec in `docs/procgen.md` matching this product intent.
+- Theme selection and seed repro path.
+- Efficient rightmost viable lemming/frontier tracker.
+- Piece-streaming planner using real theme assets.
+- Safe lookahead policy with bounded variation.
+- Minimal skill-assist planner for basic generated challenges.
+- Debug state for selected theme, generated end, lead frontier, recent pieces,
+  and recent assists.
+- E2E and unit coverage for frontier tracking, lookahead, piece placement, and
+  minimal assists.
+- Long-run benchmark coverage for bounded memory and allocation behavior.
+
+**Acceptance**
+
+- Procgen reliably adds coherent theme pieces before lemmings need them.
+- The generated level reads as tasteful themed terrain, not noise.
+- Rightmost progression is based on live viable positions, not lemming id.
+- Small generated gaps/barriers are handled with minimal appropriate skills.
+- Long runs do not grow tracking state without bound.
+
+**Out of Scope**
+
+- Full campaign/level-pack generation.
+- Complex puzzle design requiring precise human timing.
+- Guaranteeing every possible seed is solvable before the solver milestone.
+
+## Milestone 4: Solver and Solvability Platform
+
+**Outcome:** The project gains a comprehensive deterministic solver platform
+that can reason about levels, replay candidate solutions through the real game
+runtime, verify procgen chunks, and eventually provide useful editor
+solvability guidance. The solver should be ambitious, but honest about result
+types: solved, failed, unknown, timed out, or unsupported.
+
+**Core Principles**
+
+- The real game runtime is the authority. Any proposed solution must replay
+  successfully in the actual simulation.
+- Solver state extraction can be optimized, but it must not become a divergent
+  gameplay implementation.
+- Every solver run is deterministic for a fixed level, seed, skill set, options,
+  and budget.
+- Bounded "unknown" is a valid result. Hanging or unbounded search is not.
+- Explanations matter: a failed or unknown solve should say what blocked
+  progress.
+
+**Foundations**
+
+- Deterministic headless runner:
+  - load built-in levels, editor levels, procgen chunks, and synthetic fixtures.
+  - step/pause/seek through existing runtime APIs.
+  - isolate solver runs from UI state.
+  - support fixed random seeds.
+- State snapshot and hashing:
+  - terrain mask.
+  - steel and one-way constraints.
+  - entrances/exits.
+  - hazards/traps/water.
+  - blockers.
+  - lemming positions, actions, directions, fall distance, timers, skills.
+  - active builder stairs and terrain mutations.
+  - victory/save counts and timer state.
+- Action script format:
+  - skill type.
+  - target lemming selector.
+  - tick or tick window.
+  - preconditions.
+  - expected postconditions.
+  - optional rationale.
+- Replay verifier:
+  - apply candidate scripts to the real runtime.
+  - confirm exit/save target.
+  - emit final state summary.
+  - detect divergence from expected postconditions.
+
+**Environment Understanding**
+
+- Geometry analysis:
+  - walkable surfaces.
+  - cliffs and fall distances.
+  - small gaps.
+  - large gaps.
+  - walls/barriers.
+  - ceilings.
+  - steel-blocked dig/bash/mine paths.
+  - landing zones.
+  - route continuity.
+- Hazard analysis:
+  - trap trigger areas.
+  - water/drown zones.
+  - fire/frying zones.
+  - fall-death zones.
+  - unavoidable hazards.
+  - hazards avoidable by route, bridge, dig, or timing.
+- Skill affordance analysis:
+  - builder reach and stair landing.
+  - basher horizontal tunnel candidates.
+  - miner diagonal tunnel candidates.
+  - digger vertical shaft candidates.
+  - floater/parachute survival.
+  - blocker turnarounds and crowd control.
+  - climber-specific routes where available.
+  - bomber/destructive changes only when allowed by pack mechanics and scope.
+- Reachability graph:
+  - coarse segments connected by walking, falling, building, digging, mining,
+    bashing, turning, and exiting.
+  - annotations for required skills, estimated timing windows, hazards, and
+    uncertainty.
+  - incremental invalidation when terrain changes.
+
+**Solver Layers**
+
+- Tactical local solvers:
+  - bridge small gaps with minimal builders.
+  - cross larger but bounded gaps with multiple builders when skill budget
+    allows.
+  - dig through small vertical barriers.
+  - bash through horizontal barriers.
+  - mine through diagonal barriers or down to a landing.
+  - survive falls with floaters.
+  - turn around with blockers when needed.
+  - route around or neutralize simple hazards.
+  - reach a nearby exit from a bounded local area.
+- Route planner:
+  - find candidate paths from entrance/frontier to exit.
+  - score routes by required skills, timing difficulty, hazard exposure, and
+    terrain mutations.
+  - prefer minimal-skill, low-risk routes.
+  - produce a plan skeleton before exact timing search.
+- Timing search:
+  - choose assignment ticks/windows.
+  - handle lemming identity changes, crowding, and selection ambiguity.
+  - use deterministic pruning for equivalent states.
+  - support beam/A-star-style search with explicit node/time/depth budgets.
+  - keep route-plan guidance separate from runtime verification.
+- Multi-lemming reasoning:
+  - identify useful candidate lemmings by position/action/direction.
+  - reason about lead lemming vs crowd.
+  - detect when a blocker or crowd-control action is required.
+  - avoid plans that save one lemming while dooming the required save count.
+- Terrain mutation planning:
+  - model generated builder stairs, dig shafts, bash tunnels, and mine tunnels.
+  - update reachability after replayed mutations.
+  - detect destructive actions blocked by steel or one-way constraints.
+- Pack/mechanics awareness:
+  - respect pack-specific mechanics that affect skill behavior.
+  - record unsupported mechanics as explicit unsupported result reasons.
+
+**Search and Budgeting**
+
+- Solver options:
+  - max ticks.
+  - max nodes.
+  - max wall time.
+  - max actions.
+  - skill subset.
+  - target save count.
+  - allowed/destructive skills.
+  - tactical-only vs route search vs full search.
+- Result types:
+  - `solved`: verified in runtime.
+  - `failed`: proof-like local reason within supported scope.
+  - `unknown`: search exhausted or unsupported complexity.
+  - `timeout`: wall-time budget reached.
+  - `unsupported`: required mechanic is outside solver scope.
+- Explanations:
+  - no route to exit.
+  - missing landing.
+  - gap exceeds builder budget.
+  - barrier blocked by steel.
+  - hazard unavoidable.
+  - timing window too narrow.
+  - save count unreachable.
+  - state explosion.
+  - unsupported mechanic.
+
+**Procgen Integration**
+
+- Each generated challenge can include an intended solution certificate:
+  - challenge type.
+  - expected skill.
+  - rough assignment window.
+  - expected landing/exit segment.
+  - minimal skill count.
+- Procgen verifies generated gap certificates synchronously through the local
+  tactical solver before placement.
+- Failed local verification causes procgen to simplify, replace, or extend
+  terrain rather than creating impossible content.
+- Fixed procgen seeds replay small generated gap certificates through solver
+  verification and expose accepted decisions through E2E debug state.
+
+**Editor Integration**
+
+- Validation can surface bounded solver advisory warnings when the editor has a
+  rendered preview or other source with route geometry.
+- Dedicated advisory "check solvability" command now refreshes the preview and
+  reports bounded ok/warning guidance without blocking editing or export.
+- Show solver result as guidance, not as an absolute guarantee.
+- Highlight likely problem areas:
+  - unreachable exit.
+  - impossible gap.
+  - lethal drop.
+  - steel-blocked intended dig/bash/mine.
+  - insufficient skill budget.
+  - missing entrance/exit.
+- Allow saving a temporary local failure capture under `temp/` for debugging.
+- Attach concise solver explanations and stable advisory codes to editor
+  validation output.
+
+**MCP/E2E Integration**
+
+- Expose solver runs through deterministic local APIs first.
+- Add MCP tools only after the local API and result schema stabilize.
+- Return compact result JSON with optional references to `temp/` captures during
+  local development.
+- Avoid huge state dumps by default.
+
+**Workflow Coverage**
+
+- Solve tactical positive fixtures for gap, wall, dig, mine, bash, floater, and
+  blocker cases.
+- Return meaningful failed/unknown/unsupported results for negative fixtures.
+- Replay every positive solver result in the real runtime.
+- Solve a small built-in classic level or curated mini-level end to end.
+- Verify procgen local challenge certificates for fixed seeds through unit and
+  E2E debug-state coverage.
+- Run editor-created levels through bounded advisory checks.
+- Verify deterministic output for repeated runs with identical inputs.
+- Verify all budgets terminate cleanly.
+- Save temporary local captures for selected solver failures when requested.
+
+**Deliverables**
+
+- Solver module tree with clear boundaries:
+  - runtime runner.
+  - state extraction.
+  - geometry analysis.
+  - hazard analysis.
+  - skill affordance analysis.
+  - reachability graph.
+  - tactical solvers.
+  - route planner.
+  - timing search.
+  - replay verifier.
+  - result/explanation formatting.
+- Action script schema and replay verifier.
+- Synthetic fixture suite.
+- Curated classic-level mini corpus.
+- Procgen challenge certificate API.
+- Editor advisory integration for validation plus dedicated advisory controls.
+- Solver docs covering capabilities, limits, result meanings, budgets, and
+  reproduction.
+
+**Acceptance**
+
+- Tactical fixtures are solved or rejected deterministically.
+- Positive solutions replay successfully in the real runtime.
+- Negative results are useful enough to guide a developer or level designer.
+- Procgen can use solver checks to avoid simple impossible generated chunks.
+- Editor solvability checks are advisory, bounded, and never block normal work.
+- The solver never hangs or silently exceeds budgets.
+
+**Out of Scope**
+
+- Claiming complete solvability for every original or custom Lemmings level.
+- Replacing gameplay logic with a separate authoritative simulation.
+- Non-deterministic external services.
+- Cloud solving.
+
+## Cross-Cutting Validation
+
+Use the narrowest useful validation while work is in progress. Before merging a
+complete milestone, run the relevant subset plus the standard repo checks:
+
+- `npm run format`
+- `npm run check-undefined`
+- `npm run lint`
+- `npm run typecheck:critical`
+- `npm test`
+- `npm run test-bench-unit`
+
+Milestones that touch Playwright should also run targeted E2E commands. Long
+soaks and broad seed corpuses should stay opt-in unless explicitly promoted to
+CI.
+
+Milestone closeout evidence uses the shared checkpoint format in
+[`TESTING.md`](TESTING.md): commands run, ignored `temp/` artifact paths,
+GitHub issues closed, skipped checks with reasons, unrelated failures, and
+follow-up risks. Capture artifacts remain disposable and must not become a
+second roadmap, gallery, or committed manifest.
+
+## Roadmap Maintenance Rules
+
+- Keep this file focused on active and future work.
+- Do not add separate plan files unless explicitly requested. If one is created,
+  absorb the durable work back into this file and remove the plan file.
+- Remove completed detail when it stops being useful; git preserves history.
+- Prefer observable deliverables over vague intentions.
+- Record hard-cut decisions directly in the relevant milestone.
diff --git a/docs/solver.md b/docs/solver.md
new file mode 100644
index 00000000..3b65636c
--- /dev/null
+++ b/docs/solver.md
@@ -0,0 +1,86 @@
+# Solver Foundation
+
+The solver is a deterministic local advisory platform. It can propose action
+scripts, but the real runtime replay verifier is the authority for accepting a
+solution.
+
+## Result Contract
+
+Every solver entrypoint returns:
+
+- `resultType`: one of `solved`, `failed`, `unknown`, `timeout`, or
+  `unsupported`.
+- `summary`: deterministic one-line summary.
+- `actions`: ordered action script entries when a candidate route exists.
+- `explanations`: stable explanation codes with optional detail.
+- `budgetUsage`: ticks, nodes, actions, and wall time consumed.
+- `replaySummary`: verifier output, or `null` when replay did not run.
+- `captures`: optional local `temp/` artifact references.
+
+## Input Contract
+
+Solver input includes a level source, fixed seed/options, skill subset, target
+save count, max ticks, max nodes, max actions, max wall time, and mode:
+`tactical`, `route`, or `full`.
+
+## Action Script
+
+Each action carries a skill type, target selector, tick or tick window,
+preconditions, expected postconditions, and a rationale. Script replay must run
+against the runtime verifier before the result can be `solved`.
+
+Target selectors are intentionally semantic at this layer. A selector can refer
+to the frontier lemming, a lemming id, a position window, or a fixture-defined
+role. The replay adapter resolves that selector against runtime state at the
+assignment tick.
+
+## Budgets
+
+All entrypoints normalize and enforce:
+
+- `maxTicks`
+- `maxNodes`
+- `maxActions`
+- `maxWallTimeMs`
+
+Budget exhaustion returns `timeout` with `budget-exhausted`; unsupported
+source types or mechanics return `unsupported`. Search exhaustion inside a
+supported scope returns `unknown`, not `timeout`.
+
+## Replay Authority
+
+The runtime runner exposes a small adapter contract: step ticks, apply an action
+script entry, snapshot current state, and summarize the replay. Synthetic
+fixtures use the same adapter shape as real runtime runs so tests can exercise
+deterministic replay without a browser.
+
+## MCP Tools
+
+The MCP solver surface is available after the local result schema is stabilized:
+
+- `solver.snapshot`: extracts compact state hashes and counts without returning
+  terrain masks.
+- `solver.route`: builds a bounded reachability route skeleton. It returns
+  `unknown` until timing search and runtime replay verify a candidate.
+- `solver.replay`: runs action scripts through the same replay authority path
+  used by local tests.
+
+These tools return compact JSON for local development and automation. They do
+not claim full level solvability unless the replay result is `solved`.
+
+## Current Scope
+
+This checkpoint establishes local modules for runtime replay, state extraction,
+geometry analysis, tactical fixtures, procgen certificates, and editor advisory
+checks. The solver is bounded and advisory; editor/export workflows must not be
+blocked by solver output.
+
+Editor validation now surfaces solver advisory findings as warning-only issues
+when a level or rendered editor preview exposes route geometry. Advisory
+warnings carry stable `solver_advisory_*` codes for E2E diagnostics, but they do
+not add quick fixes and must never block editing, saving, or export.
+
+The editor also exposes a manual **Check Solvability** command in the validation
+panel. It refreshes the preview, runs the same bounded advisory pass, and reports
+a compact ok/warning status for designers and E2E without changing validation or
+export blocking behavior.
diff --git a/docs/time-travel-state-audit.md b/docs/time-travel-state-audit.md
deleted file mode 100644
index f31a774c..00000000
--- a/docs/time-travel-state-audit.md
+++ /dev/null
@@ -1,25 +0,0 @@
-# Time Travel State Audit
-
-## Snapshot coverage (HistoryStore)
-- Lemming: position, facing, frame index, action/state, climb/parachute flags,
-  removed/disabled, countdown + exploded flag, last trigger type.
-- Lemming manager: selected index, spawn total, release tick, minimap tick,
-  nuke queue index + target ids; active list rebuilt on apply.
-- Level: ground mask + ground image, entrance open state.
-- Triggers: static cooldowns, dynamic trigger add/remove + cooldown updates.
-- Objects: animation first-frame index + finished flag.
-- Skills: selected skill, cheat mode, per-skill counts.
-- Victory: release rate, min rate, left/out/survivor counts, finalize flag.
-- Timer: tick index + speed factor.
-- Minimap: dead dots/TTLs + dead count (live dots are recomputed in forward ticks).
-- Game: final game state.
-
-## Known omissions (intentional)
-- UI-only state (debug overlays, minimap live dots/selection, viewport).
-- Bench/debug flags and URL parameters.
-- Seeded RNG and deterministic replay outside history capture.
-
-## Notes
-- The audit did not find additional mutable simulation fields beyond the items
-  listed above. Any future gameplay flags should be added to HistoryStore
-  snapshots if they can affect simulation.
diff --git a/docs/usage.md b/docs/usage.md
index e7ed810a..f31f2f5c 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -10,6 +10,8 @@ browser-based Lemmings port with optional MIDI control and a standalone editor.
 - `npm start`
 - Open `http://127.0.0.1:8080`
 - Editor: `http://127.0.0.1:8080/editor.html`
+- HTTPS test server: `npm run start-https`, served at
+  `https://127.0.0.1:8080`.
 
 ## Saved levels
 
@@ -19,7 +21,8 @@ Use the Saved selector to pick them, or export/import `.nxlv` files.
 ## E2E harness
 
 Add `?e2e=1` to enable the E2E harness and `window.__E2E__` API. See
-`docs/e2e-state.md` for the full snapshot and buffer formats.
+`docs/e2e-state.md` for the full snapshot, buffer, and capture-rectangle
+formats.
 
 ## URL parameters
 
diff --git a/e2e/capture-targets/editor.js b/e2e/capture-targets/editor.js
new file mode 100644
index 00000000..f4a48c6d
--- /dev/null
+++ b/e2e/capture-targets/editor.js
@@ -0,0 +1,316 @@
+const waitForEditorReady = async (page) => {
+  await page.waitForSelector('#editorStatus', { state: 'visible' });
+  await page.waitForFunction(() => {
+    const state = window.__E2E__?.getState?.();
+    return Boolean(state?.editor?.session?.level && state?.editor?.assets?.terrain?.length);
+  });
+};
+
+const applyEditorOps = (page, ops, options = {}) => page.evaluate(
+  ({ ops, options }) => window.__E2E__?.editorApply?.(ops, options),
+  { ops, options }
+);
+
+const getEditorAssetIds = (page) => page.evaluate(() => {
+  const assets = window.__E2E__?.getState?.()?.editor?.assets || {};
+  const entranceId = assets.entranceId;
+  const exitId = assets.exitId;
+  const gadget = (assets.gadgets || []).find(entry => (
+    Number.isFinite(entry?.id) &&
+    entry.id !== entranceId &&
+    entry.id !== exitId
+  )) || assets.gadgets?.[0];
+  return {
+    terrainId: assets.terrain?.[0]?.id,
+    entranceId,
+    exitId,
+    gadgetId: gadget?.id,
+    triggerId: assets.triggers?.[0]?.id
+  };
+});
+
+const assertRequiredAssetIds = (ids) => {
+  for (const key of ['terrainId', 'entranceId', 'exitId']) {
+    if (!Number.isFinite(ids[key])) {
+      throw new Error(`Editor capture assets are missing ${key}.`);
+    }
+  }
+};
+
+const createWorkflowLevel = async (page, title = 'Capture Workflow') => {
+  await page.evaluate(() => window.__E2E__?.setEditorPlaytest?.(false));
+  await applyEditorOps(page, [
+    {
+      type: 'level.new',
+      args: {
+        header: {
+          TITLE: title,
+          STYLE: 'dirt',
+          WIDTH: 640,
+          HEIGHT: 192,
+          LEMMINGS: 8,
+          SAVE_REQUIREMENT: 5,
+          TIME_LIMIT: 'INFINITE',
+          MAX_SPAWN_INTERVAL: 50,
+          START_X: 0,
+          START_Y: 0
+        },
+        resetHistory: true
+      }
+    }
+  ], { history: { record: false }, preview: { refresh: false }, returnState: 'editor' });
+
+  const ids = await getEditorAssetIds(page);
+  assertRequiredAssetIds(ids);
+  const ops = [
+    { type: 'entry.add', args: { kind: 'terrain', props: { PIECE: ids.terrainId, X: 48, Y: 112 } } },
+    { type: 'entry.update', args: { ref: { kind: 'terrain', index: 0 }, set: { ONE_WAY: true } } },
+    { type: 'entry.add', args: { kind: 'steel', props: { X: 64, Y: 132, WIDTH: 64, HEIGHT: 16 } } },
+    { type: 'entry.add', args: { kind: 'gadget', props: { PIECE: ids.entranceId, X: 32, Y: 80 } } },
+    { type: 'entry.add', args: { kind: 'gadget', props: { PIECE: ids.exitId, X: 560, Y: 80 } } }
+  ];
+
+  if (Number.isFinite(ids.triggerId)) {
+    ops.push(
+      { type: 'entry.add', args: { kind: 'gadget', props: { PIECE: ids.triggerId, X: 184, Y: 104 } } },
+      {
+        type: 'entry.update',
+        args: {
+          ref: { kind: 'gadget', index: 2 },
+          set: { MIDI_FLAG: true, MIDI_FLAG_ID: 7, MIDI_FLAG_COOLDOWN: 4 }
+        }
+      }
+    );
+  } else if (Number.isFinite(ids.gadgetId)) {
+    ops.push({ type: 'entry.add', args: { kind: 'gadget', props: { PIECE: ids.gadgetId, X: 184, Y: 104 } } });
+  }
+
+  ops.push({ type: 'selection.set', args: { selection: [{ kind: 'terrain', index: 0 }] } });
+  await applyEditorOps(page, ops, {
+    history: { record: false },
+    preview: { refresh: true, preserveViewport: true },
+    validate: { run: true },
+    returnState: 'full'
+  });
+  await page.waitForFunction((expectedTitle) => {
+    const state = window.__E2E__?.getState?.();
+    return state?.editor?.session?.level?.header?.TITLE === expectedTitle &&
+      state?.editor?.validation?.hasErrors === false;
+  }, title);
+};
+
+const buildWarningImportText = (ids) => [
+  '# Capture preserves unsupported NeoLemmix data as editor warnings.',
+  'TITLE Capture Warning Import',
+  'STYLE dirt',
+  'WIDTH 640',
+  'HEIGHT 192',
+  'LEMMINGS 8',
+  'SAVE_REQUIREMENT 5',
+  '$TERRAINGROUP',
+  '  STEEL true',
+  '  $TERRAIN',
+  `    PIECE ${ids.terrainId}`,
+  '    X 80',
+  '    Y 120',
+  '    ROTATE 45',
+  '    WIDTH 32',
+  '  $END',
+  '$END',
+  '$TERRAIN',
+  `  PIECE ${ids.terrainId}`,
+  '  X 120',
+  '  Y 128',
+  '  ROTATE 45',
+  '  FLIP_HORIZONTAL true',
+  '$END',
+  '$GADGET',
+  `  PIECE ${ids.entranceId}`,
+  '  X 32',
+  '  Y 80',
+  '$END',
+  '$GADGET',
+  `  PIECE ${ids.exitId}`,
+  '  X 560',
+  '  Y 80',
+  '$END',
+  '$TALISMAN',
+  '  TITLE Preserved Capture Data',
+  '$END',
+  ''
+].join('\n');
+
+const stageValidationWarnings = async (page) => {
+  await page.evaluate(() => window.__E2E__?.setEditorPlaytest?.(false));
+  const ids = await getEditorAssetIds(page);
+  assertRequiredAssetIds(ids);
+  await page.setInputFiles('#editorSavedImportInput', {
+    name: 'capture-warning-import.nxlv',
+    mimeType: 'text/plain',
+    buffer: Buffer.from(buildWarningImportText(ids), 'utf-8')
+  });
+  await page.waitForFunction(() => (
+    window.__E2E__?.getState?.()?.editor?.session?.level?.header?.TITLE === 'Capture Warning Import'
+  ));
+  await page.waitForSelector('#editorIssuesList .issue-item[data-severity="warning"]');
+};
+
+const stageSaveImportExport = async (page) => {
+  await createWorkflowLevel(page, 'Capture Save Import Export');
+  const text = await page.evaluate(() => window.__E2E__?.getEditorLevelText?.() || '');
+  await page.setInputFiles('#editorSavedImportInput', {
+    name: 'capture-import.nxlv',
+    mimeType: 'text/plain',
+    buffer: Buffer.from(text, 'utf-8')
+  });
+  await page.waitForFunction(() => {
+    const state = window.__E2E__?.getState?.();
+    return state?.editor?.session?.level?.header?.TITLE === 'Capture Save Import Export';
+  });
+  await page.click('#editorSavedSave');
+  await page.waitForFunction(() => {
+    const saved = document.getElementById('editorSavedSelect');
+    return Array.from(saved?.options || []).some(option => option.textContent === 'Capture Save');
+  });
+};
+
+const stagePlaytest = async (page) => {
+  await createWorkflowLevel(page, 'Capture Playtest');
+  await page.click('#editorPlaytestToggle');
+  await page.waitForFunction(() => {
+    const state = window.__E2E__?.getState?.();
+    return state?.editor?.playtest === true &&
+      document.getElementById('editorPlaytestToggle')?.textContent === 'Playtest On';
+  });
+};
+
+const config = {
+  name: 'editor',
+  route: '/editor.html',
+  async setup(page) {
+    await waitForEditorReady(page);
+    await page.evaluate(() => {
+      try {
+        window.localStorage?.clear?.();
+      } catch (error) {}
+      window.prompt = () => 'Capture Save';
+      window.alert = (message) => {
+        window.__EDITOR_CAPTURE_ALERT__ = String(message || '');
+      };
+    });
+  },
+  states: [
+    {
+      name: 'shell',
+      async setup(page) {
+        await createWorkflowLevel(page, 'Capture Shell');
+      },
+      targets: [
+        { name: 'app', type: 'selector', selector: '.editor-app' },
+        { name: 'header-controls', type: 'selector', selector: '.editor-header' },
+        { name: 'viewport', type: 'viewport' }
+      ],
+      probes: [
+        {
+          name: 'app',
+          selector: '.editor-app',
+          checks: ['horizontalOverflow', 'verticalOverflow', 'unexpectedScrollbar']
+        },
+        {
+          name: 'header-controls',
+          selector: '.editor-controls',
+          checks: ['horizontalOverflow', 'clippedText']
+        }
+      ]
+    },
+    {
+      name: 'canvas-palette-inspector',
+      async setup(page) {
+        await createWorkflowLevel(page, 'Capture Canvas Palette Inspector');
+        await page.locator('#editorPaletteTerrain button[data-type="terrain"]').first().click();
+        await page.locator('#editorSelectionFlags').evaluate((element) => {
+          element.open = true;
+        });
+      },
+      targets: [
+        { name: 'canvas-panel', type: 'selector', selector: '.editor-canvas-panel' },
+        { name: 'canvas-runtime', type: 'runtimeRect', id: 'editorCanvas' },
+        { name: 'palette', type: 'selector', selector: '.palette-block' },
+        { name: 'inspector', type: 'selector', selector: 'aside.editor-panel:has(#editorHeaderTitle)' },
+        { name: 'selection-actions', type: 'selector', selector: '#editorSelectionActions' }
+      ],
+      probes: [
+        {
+          name: 'canvas-panel',
+          selector: '.editor-canvas-panel',
+          checks: ['horizontalOverflow', 'verticalOverflow', 'unexpectedScrollbar']
+        },
+        {
+          name: 'palette',
+          selector: '.palette-block',
+          checks: ['horizontalOverflow']
+        },
+        {
+          name: 'selection-actions',
+          selector: '#editorSelectionActions',
+          checks: ['horizontalOverflow', 'clippedText']
+        }
+      ]
+    },
+    {
+      name: 'validation',
+      async setup(page) {
+        await stageValidationWarnings(page);
+      },
+      targets: [
+        { name: 'warnings', type: 'selector', selector: '#editorIssuesList' },
+        { name: 'inspector-with-warnings', type: 'selector', selector: 'aside.editor-panel:has(#editorIssuesList .issue-item)' }
+      ],
+      probes: [
+        {
+          name: 'warnings',
+          selector: '#editorIssuesList',
+          checks: ['horizontalOverflow', 'clippedText']
+        }
+      ]
+    },
+    {
+      name: 'save-import-export',
+      async setup(page) {
+        await stageSaveImportExport(page);
+      },
+      targets: [
+        { name: 'file-controls', type: 'selector', selector: '.editor-controls' },
+        { name: 'saved-select', type: 'selector', selector: '#editorSavedSelect' },
+        { name: 'status-strip', type: 'selector', selector: '.status-strip' }
+      ],
+      probes: [
+        {
+          name: 'file-controls',
+          selector: '.editor-controls',
+          checks: ['horizontalOverflow', 'clippedText']
+        }
+      ]
+    },
+    {
+      name: 'playtest',
+      async setup(page) {
+        await stagePlaytest(page);
+      },
+      targets: [
+        { name: 'status-strip', type: 'selector', selector: '.status-strip' },
+        { name: 'canvas-runtime', type: 'runtimeRect', id: 'editorCanvas' },
+        { name: 'viewport', type: 'viewport' }
+      ],
+      probes: [
+        {
+          name: 'status-strip',
+          selector: '.status-strip',
+          checks: ['horizontalOverflow', 'clippedText']
+        }
+      ]
+    }
+  ]
+};
+
+export default config;
diff --git a/e2e/capture-targets/game-hud.js b/e2e/capture-targets/game-hud.js
new file mode 100644
index 00000000..eb112d66
--- /dev/null
+++ b/e2e/capture-targets/game-hud.js
@@ -0,0 +1,27 @@
+const config = {
+  name: 'game-hud',
+  route: '/',
+  async setup(page) {
+    await page.waitForFunction(() => window.__E2E__?.getState?.()?.ready === true);
+    await page.evaluate(() => window.__E2E__?.pause?.());
+  },
+  targets: [
+    { name: 'game-level-selects', type: 'selector', selector: '#levelSelects' },
+    { name: 'game-runtime-hud', type: 'runtimeRects', ids: ['canvas', 'game', 'gui', 'minimap'] },
+    { name: 'game-viewport', type: 'viewport' }
+  ],
+  probes: [
+    {
+      name: 'game-shell',
+      selector: '.game',
+      checks: ['horizontalOverflow', 'verticalOverflow', 'unexpectedScrollbar']
+    },
+    {
+      name: 'game-level-selects',
+      selector: '#levelSelects',
+      checks: ['horizontalOverflow', 'verticalOverflow', 'unexpectedScrollbar']
+    }
+  ]
+};
+
+export default config;
diff --git a/e2e/capture-targets/midi.js b/e2e/capture-targets/midi.js
new file mode 100644
index 00000000..4303b7bd
--- /dev/null
+++ b/e2e/capture-targets/midi.js
@@ -0,0 +1,171 @@
+const config = {
+  name: 'midi',
+  route: '/',
+  webMidiStub: { withDevices: true },
+  async setup(page) {
+    await page.waitForSelector('#midiEnabledToggle', { state: 'visible' });
+    await page.locator('#midiEnabledToggle').check();
+    await page.waitForSelector('#midiSequencerWorkspace', { state: 'visible' });
+    await page.waitForSelector('#midiSourceList .midi-source-row');
+    await page.evaluate(() => {
+      if (!window.__E2E__?.midiGetProject?.().clips.length) {
+        window.__E2E__?.midiDispatchProjectIntent?.({
+          type: 'clip.add',
+          clip: { id: 'capture-clip', name: 'Capture Clip', lengthSteps: 8 }
+        });
+      }
+      window.__E2E__?.midiSaveProjectTemplate?.({
+        id: 'capture-template',
+        name: 'Capture Template',
+        now: 1
+      });
+      window.__E2E__?.midiDispatchProjectIntent?.({
+        type: 'clip.step.update',
+        clipId: 'capture-clip',
+        stepIndex: 0,
+        patch: { note: 64, velocity: 90 }
+      });
+      window.__E2E__?.midiDispatchProjectIntent?.({
+        type: 'source.clip.assign',
+        sourceId: 'sfx-1',
+        clipId: 'capture-clip'
+      });
+      const project = window.__E2E__?.midiGetProject?.();
+      const source = project?.sources?.find(entry => entry.id === 'sfx-1');
+      if (source) {
+        const ensureLane = (lanes, lane) => (
+          lanes.some(entry => entry.id === lane.id) ? lanes : [...lanes, lane]
+        );
+        let automation = project.automation || [];
+        automation = ensureLane(automation, { id: 'capture-note-lane', name: 'Capture Note', target: 'note', axis: 'x', min: -7, max: 7, enabled: true });
+        automation = ensureLane(automation, { id: 'capture-pan-lane', name: 'Capture Pan', target: 'pan', axis: 'x', min: -80, max: 80, enabled: true });
+        automation = ensureLane(automation, { id: 'capture-duration-lane', name: 'Capture Duration', target: 'duration', axis: 'y', min: 3, max: 18, enabled: true });
+        window.__E2E__?.midiDispatchProjectIntent?.({
+          type: 'project.set',
+          project: {
+            ...project,
+            global: {
+              ...project.global,
+              velocityRange: { ...project.global.velocityRange, default: 96 },
+              density: { ...project.global.density, velocityBoost: 0.8 },
+              position: { ...project.global.position, viewPan: true }
+            },
+            tracks: project.tracks.map(track => (
+              track.id === 'track-1' ? { ...track, velocityScale: 0.75 } : track
+            )),
+            sources: project.sources.some(entry => entry.id === 'capture-sfx-conflict')
+              ? project.sources
+              : [
+                ...project.sources,
+                {
+                  ...source,
+                  id: 'capture-sfx-conflict',
+                  label: 'Capture Conflict'
+                }
+              ],
+            automation,
+            ui: {
+              ...project.ui,
+              selectedSourceId: 'sfx-1',
+              selectedClipId: 'capture-clip'
+            }
+          }
+        });
+      }
+      window.__E2E__?.midiStartLearn?.();
+      window.__E2E__?.midiCaptureLearnNote?.(86, 104, 6);
+      window.__E2E__?.midiStartRecording?.();
+      window.__E2E__?.midiCaptureRecordMessage?.({ type: 0x90, note: 62, velocity: 90, channel: 1, timestamp: 0 });
+      window.__E2E__?.midiCaptureRecordMessage?.({ type: 0x80, note: 62, velocity: 0, channel: 1, timestamp: 240 });
+      window.__E2E__?.midiAudition?.({ sourceId: 'sfx-1' });
+    });
+    await page.waitForSelector('#midiClipList .midi-clip-row');
+    await page.waitForSelector('#midiStepPatternGrid .midi-step-cell');
+    await page.waitForSelector('#midiSourceList .midi-conflict-badge');
+    await page.waitForFunction(() => (
+      /Audition Capture Clip ->/.test(document.getElementById('midiOutputLog')?.textContent || '')
+    ));
+  },
+  targets: [
+    { name: 'midi-transport', type: 'selector', selector: '#midiTransportStrip' },
+    { name: 'midi-canvas', type: 'runtimeRect', id: 'canvas' },
+    { name: 'midi-viewport', type: 'viewport' },
+    { name: 'midi-source-browser', type: 'selector', selector: '#midiSourceBrowser' },
+    { name: 'midi-track-workspace', type: 'selector', selector: '#midiTrackWorkspace' },
+    { name: 'midi-clip-library', type: 'selector', selector: '#midiClipLibrary' },
+    { name: 'midi-inspector', type: 'selector', selector: '#midiInspector' },
+    { name: 'midi-conflict-summary', type: 'selector', selector: '#midiConflictSummary' },
+    { name: 'midi-learn', type: 'selector', selector: '#midiLearnPanel' },
+    { name: 'midi-record', type: 'selector', selector: '#midiRecordPanel' },
+    { name: 'midi-modulation', type: 'selector', selector: '#midiModulationInspector' },
+    { name: 'midi-step-pattern', type: 'selector', selector: '#midiStepPatternGrid' },
+    { name: 'midi-output-status', type: 'selector', selector: '#midiOutputStatus' },
+    { name: 'midi-level-prev-arrow', type: 'selector', selector: '#levelPrevButton' },
+    { name: 'midi-level-next-arrow', type: 'selector', selector: '#levelNextButton' }
+  ],
+  probes: [
+    {
+      name: 'midi-workspace-focus',
+      selector: '#midiSequencerWorkspace',
+      checks: ['hiddenFocusedElement'],
+      required: true
+    },
+    {
+      name: 'midi-source-browser',
+      selector: '#midiSourceBrowser',
+      checks: ['horizontalOverflow']
+    },
+    {
+      name: 'midi-track-workspace',
+      selector: '#midiTrackWorkspace',
+      checks: ['horizontalOverflow']
+    },
+    {
+      name: 'midi-clip-library',
+      selector: '#midiClipLibrary',
+      checks: ['horizontalOverflow']
+    },
+    {
+      name: 'midi-inspector',
+      selector: '#midiInspector',
+      checks: ['horizontalOverflow']
+    },
+    {
+      name: 'midi-conflict-summary',
+      selector: '#midiConflictSummary',
+      checks: ['horizontalOverflow', 'clippedText']
+    },
+    {
+      name: 'midi-learn',
+      selector: '#midiLearnPanel',
+      checks: ['horizontalOverflow', 'clippedText']
+    },
+    {
+      name: 'midi-record',
+      selector: '#midiRecordPanel',
+      checks: ['horizontalOverflow', 'clippedText']
+    },
+    {
+      name: 'midi-modulation',
+      selector: '#midiModulationInspector',
+      checks: ['horizontalOverflow']
+    },
+    {
+      name: 'midi-step-pattern',
+      selector: '#midiStepPatternGrid',
+      checks: ['horizontalOverflow']
+    },
+    {
+      name: 'midi-output-status',
+      selector: '#midiOutputStatus',
+      checks: ['horizontalOverflow', 'clippedText']
+    },
+    {
+      name: 'midi-level-arrows',
+      selector: '#levelPrevButton, #levelNextButton',
+      checks: ['smallTapTarget']
+    }
+  ]
+};
+
+export default config;
diff --git a/e2e/capture-targets/procgen.js b/e2e/capture-targets/procgen.js
new file mode 100644
index 00000000..0eef983b
--- /dev/null
+++ b/e2e/capture-targets/procgen.js
@@ -0,0 +1,92 @@
+const waitForProcgenReady = async (page) => {
+  await page.waitForFunction(() => window.__E2E__?.getState?.()?.ready === true);
+};
+
+const stepProcgen = async (page, count = 240) => {
+  await page.evaluate((ticks) => {
+    window.__E2E__?.pause?.();
+    window.__E2E__?.step?.(ticks);
+  }, count);
+};
+
+const centerOnProcgenFrontier = async (page) => {
+  await page.evaluate(() => {
+    const state = window.__E2E__?.getState?.();
+    const frontier = state?.procgen?.frontier || null;
+    if (!Number.isFinite(frontier?.x) || !Number.isFinite(frontier?.y)) return;
+    window.__E2E__?.centerStageOn?.({
+      x: frontier.x + 80,
+      y: frontier.y - 24
+    });
+  });
+};
+
+const centerOnNewestGeneratedPiece = async (page) => {
+  await page.evaluate(() => {
+    const state = window.__E2E__?.getState?.();
+    const pieces = state?.procgen?.recentPieces || [];
+    const newest = pieces.length ? pieces[pieces.length - 1] : null;
+    const generatedEndX = state?.procgen?.generatedEndX;
+    const frontierY = state?.procgen?.frontier?.y;
+    const x = Number.isFinite(newest?.x)
+      ? newest.x
+      : (Number.isFinite(generatedEndX) ? generatedEndX - 120 : null);
+    const y = Number.isFinite(newest?.y)
+      ? newest.y
+      : (Number.isFinite(frontierY) ? frontierY - 24 : 120);
+    if (!Number.isFinite(x) || !Number.isFinite(y)) return;
+    window.__E2E__?.centerStageOn?.({ x, y });
+  });
+};
+
+const gameTargets = [
+  { name: 'procgen-game', type: 'runtimeRect', id: 'game' },
+  { name: 'procgen-canvas-selector', type: 'selector', selector: '#gameCanvas' }
+];
+
+const config = {
+  name: 'procgen',
+  route: '/procgen.html?seed=visual-capture&aiDebug=1',
+  async setup(page) {
+    await waitForProcgenReady(page);
+    await stepProcgen(page, 360);
+  },
+  states: [
+    {
+      name: 'overview',
+      targets: [
+        { name: 'procgen-viewport', type: 'viewport' },
+        { name: 'procgen-runtime', type: 'runtimeRects', ids: ['canvas', 'game'] },
+        {
+          name: 'procgen-ground-band',
+          type: 'worldRect',
+          rect: { x: 0, y: 120, width: 360, height: 60 },
+          padding: 8
+        }
+      ]
+    },
+    {
+      name: 'frontier',
+      async setup(page) {
+        await centerOnProcgenFrontier(page);
+      },
+      targets: gameTargets
+    },
+    {
+      name: 'newest-pieces',
+      async setup(page) {
+        await centerOnNewestGeneratedPiece(page);
+      },
+      targets: gameTargets
+    }
+  ],
+  probes: [
+    {
+      name: 'procgen-canvas',
+      selector: '#gameCanvas',
+      checks: ['horizontalOverflow', 'verticalOverflow', 'unexpectedScrollbar']
+    }
+  ]
+};
+
+export default config;
diff --git a/e2e/editor.spec.js b/e2e/editor.spec.js
index a6ee89e8..67fa087d 100644
--- a/e2e/editor.spec.js
+++ b/e2e/editor.spec.js
@@ -1,3 +1,4 @@
+import fs from 'node:fs/promises';
 import { expect, test } from '@playwright/test';
 import { installExternalAssetStubs } from './helpers/externalAssets.js';
 
@@ -10,10 +11,115 @@ test.beforeEach(async ({ page }) => {
     window.prompt = () => 'E2E Save';
     window.alert = () => {};
   });
-  await page.goto('/editor.html');
+  await page.goto('/editor.html?e2e=1');
   await expect(page.locator('#editorStatus')).toContainText('Tool:');
+  await page.waitForFunction(() => typeof window.__E2E__?.getEditorLevelText === 'function');
 });
 
+const setEditorField = async (page, selector, value) => {
+  await page.locator(selector).evaluate((element, nextValue) => {
+    element.value = String(nextValue);
+    element.dispatchEvent(new Event('change', { bubbles: true }));
+  }, value);
+};
+
+const applyEditorOps = (page, ops, options = {}) => page.evaluate(
+  ({ ops, options }) => window.__E2E__.editorApply(ops, options),
+  { ops, options }
+);
+
+const sortByJson = (items) => [...items].sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+const propNumber = (value) => {
+  if (Number.isFinite(value)) return value;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+};
+const propBoolean = (value) => (
+  value === true || value === 1 || value === 'true' || value === '1'
+);
+
+const getEditorAssetIds = (page) => page.evaluate(() => {
+  const assets = window.__E2E__.getState().editor.assets;
+  return {
+    terrainId: assets.terrain[0]?.id,
+    triggerId: assets.triggers[0]?.id,
+    entranceId: assets.entranceId,
+    exitId: assets.exitId
+  };
+});
+
+const semanticSummary = (level) => ({
+  header: {
+    TITLE: level.header?.TITLE || '',
+    STYLE: level.header?.STYLE || '',
+    LEMMINGS: propNumber(level.header?.LEMMINGS),
+    SAVE_REQUIREMENT: propNumber(level.header?.SAVE_REQUIREMENT),
+    WIDTH: propNumber(level.header?.WIDTH),
+    HEIGHT: propNumber(level.header?.HEIGHT)
+  },
+  terrains: sortByJson((level.terrains || []).map(entry => ({
+    PIECE: propNumber(entry.props?.PIECE),
+    X: propNumber(entry.props?.X),
+    Y: propNumber(entry.props?.Y),
+    ONE_WAY: propBoolean(entry.props?.ONE_WAY)
+  }))),
+  gadgets: sortByJson((level.gadgets || []).map(entry => ({
+    PIECE: propNumber(entry.props?.PIECE),
+    X: propNumber(entry.props?.X),
+    Y: propNumber(entry.props?.Y),
+    MIDI_FLAG: propBoolean(entry.props?.MIDI_FLAG),
+    MIDI_FLAG_ID: propNumber(entry.props?.MIDI_FLAG_ID),
+    MIDI_FLAG_COOLDOWN: propNumber(entry.props?.MIDI_FLAG_COOLDOWN)
+  }))),
+  steel: sortByJson((level.steel || []).map(entry => ({
+    X: propNumber(entry.props?.X),
+    Y: propNumber(entry.props?.Y),
+    WIDTH: propNumber(entry.props?.WIDTH),
+    HEIGHT: propNumber(entry.props?.HEIGHT)
+  })))
+});
+
+const buildWarningImportText = ({ terrainId, entranceId, exitId }) => [
+  '# E2E warning import keeps unsupported NeoLemmix data visible.',
+  'TITLE E2E Warning Import',
+  'STYLE dirt',
+  'WIDTH 640',
+  'HEIGHT 192',
+  'LEMMINGS 8',
+  'SAVE_REQUIREMENT 5',
+  '$TERRAINGROUP',
+  '  STEEL true',
+  '  $TERRAIN',
+  `    PIECE ${terrainId}`,
+  '    X 64',
+  '    Y 112',
+  '    ROTATE 45',
+  '    WIDTH 32',
+  '  $END',
+  '$END',
+  '$TERRAIN',
+  `  PIECE ${terrainId}`,
+  '  X 120',
+  '  Y 128',
+  '  ROTATE 45',
+  '  FLIP_HORIZONTAL true',
+  '$END',
+  '$GADGET',
+  `  PIECE ${entranceId}`,
+  '  X 32',
+  '  Y 80',
+  '$END',
+  '$GADGET',
+  `  PIECE ${exitId}`,
+  '  X 560',
+  '  Y 80',
+  '$END',
+  '$TALISMAN',
+  '  TITLE Preserved Unsupported Data',
+  '$END',
+  ''
+].join('\n');
+
 test('Editor UI loads and tool selection updates state', async ({ page }) => {
   await expect(page.locator('#editorCanvas')).toBeVisible();
 
@@ -27,15 +133,23 @@ test('Editor UI loads and tool selection updates state', async ({ page }) => {
 });
 
 test('Palette tabs switch visible lists', async ({ page }) => {
+  const terrainTab = page.locator('#editorPaletteTabs button[data-tab="terrain"]');
   const gadgetsTab = page.locator('#editorPaletteTabs button[data-tab="gadgets"]');
+  const triggersTab = page.locator('#editorPaletteTabs button[data-tab="triggers"]');
+  await expect(terrainTab).toHaveAttribute('aria-pressed', 'true');
+  await expect(gadgetsTab).toHaveAttribute('aria-pressed', 'false');
+
   await gadgetsTab.click();
+  await expect(terrainTab).toHaveAttribute('aria-pressed', 'false');
+  await expect(gadgetsTab).toHaveAttribute('aria-pressed', 'true');
   await expect(page.locator('#editorPaletteGadgets')).toHaveJSProperty('hidden', false);
   await expect(page.locator('#editorPaletteGadgets')).toBeVisible();
   await expect(page.locator('#editorPaletteTerrain')).toHaveJSProperty('hidden', true);
   await expect(page.locator('#editorPaletteTerrain')).toBeHidden();
 
-  const triggersTab = page.locator('#editorPaletteTabs button[data-tab="triggers"]');
   await triggersTab.click();
+  await expect(gadgetsTab).toHaveAttribute('aria-pressed', 'false');
+  await expect(triggersTab).toHaveAttribute('aria-pressed', 'true');
   await expect(page.locator('#editorPaletteTriggers')).toHaveJSProperty('hidden', false);
   await expect(page.locator('#editorPaletteTriggers')).toBeVisible();
   await expect(page.locator('#editorPaletteTerrain')).toHaveJSProperty('hidden', true);
@@ -48,23 +162,54 @@ test('Palette view toggle switches list and grid layouts', async ({ page }) => {
   const terrainList = page.locator('#editorPaletteTerrain');
 
   await expect(listButton).toHaveClass(/active/);
+  await expect(listButton).toHaveAttribute('aria-pressed', 'true');
+  await expect(gridButton).toHaveAttribute('aria-pressed', 'false');
   await expect(terrainList).not.toHaveClass(/grid/);
 
   await gridButton.click();
   await expect(gridButton).toHaveClass(/active/);
+  await expect(listButton).toHaveAttribute('aria-pressed', 'false');
+  await expect(gridButton).toHaveAttribute('aria-pressed', 'true');
   await expect(terrainList).toHaveClass(/grid/);
 
   await listButton.click();
   await expect(listButton).toHaveClass(/active/);
+  await expect(listButton).toHaveAttribute('aria-pressed', 'true');
+  await expect(gridButton).toHaveAttribute('aria-pressed', 'false');
   await expect(terrainList).not.toHaveClass(/grid/);
 });
 
+test('Palette recent strip records and reselects pieces', async ({ page }) => {
+  const terrainButton = page.locator('#editorPaletteTerrain button[data-type="terrain"]').first();
+  const terrainId = Number(await terrainButton.getAttribute('data-id'));
+  expect(Number.isFinite(terrainId)).toBe(true);
+
+  await terrainButton.click();
+  const recentTerrain = page.locator(`#editorPaletteRecent button[data-type="terrain"][data-id="${terrainId}"]`);
+  await expect(recentTerrain).toBeVisible();
+  await expect(recentTerrain).toHaveAttribute('aria-pressed', 'true');
+
+  await page.locator('#editorPaletteTabs button[data-tab="gadgets"]').click();
+  const gadgetButton = page.locator('#editorPaletteGadgets button[data-type="gadget"]').first();
+  const gadgetId = Number(await gadgetButton.getAttribute('data-id'));
+  expect(Number.isFinite(gadgetId)).toBe(true);
+  await gadgetButton.click();
+
+  const recentButtons = page.locator('#editorPaletteRecent button');
+  await expect(recentButtons.first()).toHaveAttribute('data-type', 'gadget');
+  await expect(recentButtons.first()).toHaveAttribute('data-id', String(gadgetId));
+
+  await recentTerrain.click();
+  const selectedTerrainId = await page.evaluate(() => window.__E2E__.getState().editor.controller.selectedTerrainId);
+  expect(selectedTerrainId).toBe(terrainId);
+});
+
 test('Save and import keep saved list wired up', async ({ page }) => {
   await page.click('#editorSavedSave');
   await expect(page.locator('#editorSavedSelect')).toContainText('E2E Save');
 
   const text = await page.evaluate(() => {
-    return window.lemmings?.getEditorLevelText?.() || '';
+    return window.__E2E__?.getEditorLevelText?.() || '';
   });
   expect(text.length).toBeGreaterThan(0);
 
@@ -80,6 +225,221 @@ test('Save and import keep saved list wired up', async ({ page }) => {
   });
 });
 
+test('Validation panel renders and applies fix buttons', async ({ page }) => {
+  await setEditorField(page, '#editorHeaderLemmings', 5);
+  await setEditorField(page, '#editorHeaderSaveRequirement', 8);
+
+  await expect(page.locator('#editorIssuesList')).toHaveAttribute('role', 'list');
+  await expect(page.locator('#editorIssuesList')).toHaveAttribute('aria-live', 'polite');
+  const issue = page.locator('#editorIssuesList .issue-item', {
+    hasText: 'Save requirement exceeds lemmings.'
+  });
+  await expect(issue).toBeVisible();
+  await expect(issue).toHaveAttribute('data-severity', 'error');
+  await expect(issue).toHaveAttribute('aria-label', 'Error: Save requirement exceeds lemmings.');
+  await expect(issue.locator('.issue-severity')).toHaveText('Error');
+  await expect(issue.locator('.issue-message')).toHaveText('Save requirement exceeds lemmings.');
+  await issue.getByRole('button', { name: 'Clamp save requirement' }).click();
+  await expect(page.locator('#editorIssuesList')).not.toContainText('Save requirement exceeds lemmings.');
+
+  const header = await page.evaluate(() => window.__E2E__.getState().editor.session.level.header);
+  expect(header.SAVE_REQUIREMENT).toBe(5);
+  expect(header.LEMMINGS).toBe(5);
+});
+
+test('Solvability check reports bounded advisory guidance', async ({ page }) => {
+  const ids = await getEditorAssetIds(page);
+  expect(Number.isFinite(ids.terrainId)).toBe(true);
+  expect(Number.isFinite(ids.entranceId)).toBe(true);
+  expect(Number.isFinite(ids.exitId)).toBe(true);
+
+  await applyEditorOps(page, [
+    {
+      type: 'level.new',
+      args: {
+        header: {
+          TITLE: 'E2E Solvability Advisory',
+          STYLE: 'dirt',
+          WIDTH: 640,
+          HEIGHT: 192,
+          LEMMINGS: 8,
+          SAVE_REQUIREMENT: 5
+        },
+        resetHistory: true
+      }
+    },
+    { type: 'entry.add', args: { kind: 'terrain', props: { PIECE: ids.terrainId, X: 64, Y: 120, ONE_WAY: true } } },
+    { type: 'entry.add', args: { kind: 'gadget', props: { PIECE: ids.entranceId, X: 32, Y: 88 } } }
+  ], {
+    history: { record: false },
+    preview: { refresh: true, preserveViewport: true },
+    validate: { run: true },
+    returnState: 'editor'
+  });
+
+  await page.click('#editorSolvabilityCheck');
+  await expect(page.locator('#editorSolvabilityStatus')).toHaveAttribute('data-status', 'warnings');
+  await expect(page.locator('#editorSolvabilityStatus')).toContainText('Solvability: 1 advisory warning');
+
+  const solvability = await page.evaluate(() => window.__E2E__.getState().editor.ui.solvability);
+  expect(solvability.status).toBe('warnings');
+  expect(solvability.warningCount).toBe(1);
+  expect(solvability.warnings.map(warning => warning.code)).toContain('missing-exit');
+  expect(solvability.budgetUsage).toBeTruthy();
+});
+
+test('Unsupported NeoLemmix data imports with visible warnings and preserved export text', async ({ page }) => {
+  const ids = await getEditorAssetIds(page);
+  expect(Number.isFinite(ids.terrainId)).toBe(true);
+  expect(Number.isFinite(ids.entranceId)).toBe(true);
+  expect(Number.isFinite(ids.exitId)).toBe(true);
+
+  await page.setInputFiles('#editorSavedImportInput', {
+    name: 'warning-import.nxlv',
+    mimeType: 'text/plain',
+    buffer: Buffer.from(buildWarningImportText(ids), 'utf-8')
+  });
+
+  const warningList = page.locator('#editorIssuesList');
+  await expect(warningList.locator('.issue-item[data-severity="warning"]', {
+    hasText: 'Terrain groups are not exported to classic .lvl'
+  })).toBeVisible();
+  await expect(warningList.locator('.issue-item[data-severity="warning"]', {
+    hasText: 'Terrain entries include properties classic .lvl cannot export'
+  })).toBeVisible();
+  await expect(warningList.locator('.issue-item[data-severity="warning"]', {
+    hasText: 'Classic LVL export is lossy'
+  })).toBeVisible();
+
+  const state = await page.evaluate(() => window.__E2E__.getState().editor);
+  expect(state.validation.hasErrors).toBe(false);
+  expect(state.session.level.terrainGroups).toHaveLength(1);
+  expect(state.session.level.unknownSections.some(section => section.name === 'TALISMAN')).toBe(true);
+
+  const exported = await page.evaluate(() => window.__E2E__.getEditorLevelText());
+  expect(exported).toContain('$TERRAINGROUP');
+  expect(exported).toContain('$TALISMAN');
+  expect(exported).toContain('ROTATE 45');
+});
+
+test('Empty editor import reports a visible failure without replacing the current level', async ({ page }) => {
+  const titleBefore = await page.evaluate(() => window.__E2E__.getState().editor.session.level.header.TITLE);
+
+  await page.setInputFiles('#editorSavedImportInput', {
+    name: 'empty-import.nxlv',
+    mimeType: 'text/plain',
+    buffer: Buffer.from('', 'utf-8')
+  });
+
+  await expect(page.locator('#editorStatus')).toContainText('NXLV import failed');
+  await expect(page.locator('#editorIssuesList .issue-item[data-severity="error"]', {
+    hasText: 'NXLV import failed: Level file is empty.'
+  })).toBeVisible();
+  const titleAfter = await page.evaluate(() => window.__E2E__.getState().editor.session.level.header.TITLE);
+  expect(titleAfter).toBe(titleBefore);
+});
+
+test('UI export and import accepts the same semantic editor state', async ({ page }) => {
+  const ids = await getEditorAssetIds(page);
+  expect(Number.isFinite(ids.terrainId)).toBe(true);
+  expect(Number.isFinite(ids.triggerId)).toBe(true);
+  expect(Number.isFinite(ids.entranceId)).toBe(true);
+  expect(Number.isFinite(ids.exitId)).toBe(true);
+
+  await applyEditorOps(page, [
+    {
+      type: 'level.new',
+      args: {
+        header: {
+          TITLE: 'E2E UI Semantic Roundtrip',
+          STYLE: 'dirt',
+          WIDTH: 640,
+          HEIGHT: 192,
+          LEMMINGS: 10,
+          SAVE_REQUIREMENT: 6,
+          TIME_LIMIT: 'INFINITE',
+          MAX_SPAWN_INTERVAL: 50
+        },
+        resetHistory: true
+      }
+    },
+    { type: 'entry.add', args: { kind: 'terrain', props: { PIECE: ids.terrainId, X: 64, Y: 120 } } },
+    { type: 'entry.update', args: { ref: { kind: 'terrain', index: 0 }, set: { ONE_WAY: true } } },
+    { type: 'entry.add', args: { kind: 'steel', props: { X: 72, Y: 136, WIDTH: 48, HEIGHT: 12 } } },
+    { type: 'entry.add', args: { kind: 'gadget', props: { PIECE: ids.entranceId, X: 32, Y: 88 } } },
+    { type: 'entry.add', args: { kind: 'gadget', props: { PIECE: ids.exitId, X: 560, Y: 88 } } },
+    { type: 'entry.add', args: { kind: 'gadget', props: { PIECE: ids.triggerId, X: 196, Y: 104 } } },
+    {
+      type: 'entry.update',
+      args: {
+        ref: { kind: 'gadget', index: 2 },
+        set: { MIDI_FLAG: true, MIDI_FLAG_ID: 9, MIDI_FLAG_COOLDOWN: 3 }
+      }
+    }
+  ], {
+    history: { record: false },
+    preview: { refresh: true, preserveViewport: true },
+    validate: { run: true },
+    returnState: 'full'
+  });
+
+  await page.waitForFunction(() => window.__E2E__.getState().editor.validation.hasErrors === false);
+  const beforeLevel = await page.evaluate(() => window.__E2E__.getState().editor.session.level);
+  const before = semanticSummary(beforeLevel);
+
+  const [download] = await Promise.all([
+    page.waitForEvent('download'),
+    page.click('#editorSavedExport')
+  ]);
+  const downloadPath = await download.path();
+  const exportedText = await fs.readFile(downloadPath, 'utf-8');
+  expect(exportedText).toContain('E2E UI Semantic Roundtrip');
+  expect(exportedText).toContain('MIDI_FLAG true');
+
+  await page.setInputFiles('#editorSavedImportInput', {
+    name: 'semantic-roundtrip.nxlv',
+    mimeType: 'text/plain',
+    buffer: Buffer.from(exportedText, 'utf-8')
+  });
+  await page.waitForFunction(() => (
+    window.__E2E__.getState().editor.session.level.header.TITLE === 'E2E UI Semantic Roundtrip'
+  ));
+
+  const afterLevel = await page.evaluate(() => window.__E2E__.getState().editor.session.level);
+  expect(semanticSummary(afterLevel)).toEqual(before);
+});
+
+test('Selection inspector toggles terrain one-way flags', async ({ page }) => {
+  const terrainId = await page.evaluate(() => window.__E2E__.getState().editor.assets.terrain[0]?.id);
+  expect(Number.isFinite(terrainId)).toBe(true);
+
+  await applyEditorOps(page, [
+    { type: 'entry.add', args: { kind: 'terrain', props: { PIECE: terrainId, X: 32, Y: 32 } } },
+    { type: 'entry.add', args: { kind: 'steel', props: { X: 96, Y: 32, WIDTH: 16, HEIGHT: 16 } } },
+    { type: 'selection.set', args: { selection: [{ kind: 'terrain', index: 0 }] } }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+
+  const oneWay = page.locator('#editorSelOneWay');
+  await page.locator('#editorSelectionFlags').evaluate(element => {
+    element.open = true;
+  });
+  await expect(oneWay).toBeEnabled();
+  await expect(oneWay).not.toBeChecked();
+
+  await oneWay.check();
+  const checkedProps = await page.evaluate(() => window.__E2E__.getState().editor.session.level.terrains[0].props);
+  expect(checkedProps.ONE_WAY).toBe(true);
+
+  await oneWay.uncheck();
+  const uncheckedProps = await page.evaluate(() => window.__E2E__.getState().editor.session.level.terrains[0].props);
+  expect(Object.prototype.hasOwnProperty.call(uncheckedProps, 'ONE_WAY')).toBe(false);
+
+  await applyEditorOps(page, [
+    { type: 'selection.set', args: { selection: [{ kind: 'steel', index: 0 }] } }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+  await expect(oneWay).toBeDisabled();
+});
+
 test('Canvas interaction clears focused editor inputs', async ({ page }) => {
   const titleInput = page.locator('#editorHeaderTitle');
   await titleInput.focus();
@@ -87,3 +447,21 @@ test('Canvas interaction clears focused editor inputs', async ({ page }) => {
   await page.locator('#editorCanvas').click({ position: { x: 12, y: 12 }, force: true });
   await expect(titleInput).not.toBeFocused();
 });
+
+test('Shortcut overlay focuses close control and restores focus on Escape', async ({ page }) => {
+  const opener = page.locator('#editorSavedSave');
+  const overlay = page.locator('#editorShortcutOverlay');
+  const close = overlay.locator('.shortcut-overlay__close');
+
+  await page.waitForSelector('#editorShortcutOverlay .shortcut-row');
+  await opener.focus();
+  await expect(opener).toBeFocused();
+
+  await page.keyboard.press('F1');
+  await expect(overlay).toHaveAttribute('aria-hidden', 'false');
+  await expect(close).toBeFocused();
+
+  await page.keyboard.press('Escape');
+  await expect(overlay).toHaveAttribute('aria-hidden', 'true');
+  await expect(opener).toBeFocused();
+});
diff --git a/e2e/game.spec.js b/e2e/game.spec.js
index 0943b884..7292df06 100644
--- a/e2e/game.spec.js
+++ b/e2e/game.spec.js
@@ -8,15 +8,15 @@ test.beforeEach(async ({ page }) => {
       window.localStorage?.clear?.();
     } catch (error) {}
   });
-  await page.goto('/');
+  await page.goto('/?e2e=1');
 });
 
 test('Game loads the first level on startup', async ({ page }) => {
   await page.waitForFunction(() => {
-    return Boolean(window.lemmings?.game?.level);
+    return window.__E2E__?.getState?.()?.ready === true;
   });
-  const hasLevel = await page.evaluate(() => Boolean(window.lemmings?.game?.level));
-  expect(hasLevel).toBe(true);
+  const ready = await page.evaluate(() => window.__E2E__?.getState?.()?.ready === true);
+  expect(ready).toBe(true);
 });
 
 test('Arrow navigation updates the selected level', async ({ page }) => {
@@ -41,6 +41,35 @@ test('Arrow navigation updates the selected level', async ({ page }) => {
   }, initialValue);
 });
 
+test('Level arrows support keyboard activation', async ({ page }) => {
+  const levelSelect = page.locator('#levelIndexSelect');
+  await page.waitForFunction(() => {
+    const select = document.getElementById('levelIndexSelect');
+    return select && select.options.length > 1;
+  });
+  const initialValue = await levelSelect.inputValue();
+  const next = page.locator('#levelNextButton');
+  const prev = page.locator('#levelPrevButton');
+
+  await expect(next).toHaveAttribute('role', 'button');
+  await expect(next).toHaveAttribute('aria-label', 'Next level');
+  await next.focus();
+  await expect(next).toBeFocused();
+  await page.keyboard.press('Enter');
+  await page.waitForFunction((prevValue) => {
+    const select = document.getElementById('levelIndexSelect');
+    return select && select.value !== prevValue;
+  }, initialValue);
+
+  await prev.focus();
+  await expect(prev).toBeFocused();
+  await page.keyboard.press('Space');
+  await page.waitForFunction((prevValue) => {
+    const select = document.getElementById('levelIndexSelect');
+    return select && select.value === prevValue;
+  }, initialValue);
+});
+
 test('Space toggles pause state', async ({ page }) => {
   await page.goto('/?e2e=1');
   await page.waitForFunction(() => window.__E2E__?.getState?.().ready);
@@ -51,3 +80,27 @@ test('Space toggles pause state', async ({ page }) => {
   await page.keyboard.press('Space');
   await page.waitForFunction(() => window.__E2E__?.getState?.().game?.timer?.running === true);
 });
+
+test('Game shortcut overlay focuses close control and restores canvas focus', async ({ page }) => {
+  await page.waitForFunction(() => window.__E2E__?.getState?.().ready);
+  await page.waitForSelector('#shortcutOverlay .shortcut-row');
+  const canvas = page.locator('#gameCanvas');
+  const overlay = page.locator('#shortcutOverlay');
+  const close = overlay.locator('.shortcut-overlay__close');
+
+  await canvas.evaluate(element => {
+    element.setAttribute('tabindex', '-1');
+  });
+  await canvas.focus();
+  await expect(canvas).toBeFocused();
+
+  await expect(async () => {
+    await page.keyboard.press('F1');
+    await expect(overlay).toHaveAttribute('aria-hidden', 'false', { timeout: 1000 });
+  }).toPass({ timeout: 5000 });
+  await expect(close).toBeFocused();
+
+  await page.keyboard.press('Escape');
+  await expect(overlay).toHaveAttribute('aria-hidden', 'true');
+  await expect(canvas).toBeFocused();
+});
diff --git a/e2e/harness.controls.spec.js b/e2e/harness.controls.spec.js
index eac165ec..9f2514db 100644
--- a/e2e/harness.controls.spec.js
+++ b/e2e/harness.controls.spec.js
@@ -8,18 +8,12 @@ const focusGameCanvas = async (page) => {
   if (!canvasBox) {
     throw new Error('gameCanvas is not visible');
   }
-  const panelBox = await page.locator('#controlLeft').boundingBox();
-  let clickX = canvasBox.x + canvasBox.width * 0.5;
-  const clickY = canvasBox.y + canvasBox.height * 0.5;
-  if (panelBox) {
-    const safeX = panelBox.x + panelBox.width + 20;
-    if (safeX < canvasBox.x + canvasBox.width - 5) {
-      clickX = Math.max(clickX, safeX);
-    } else {
-      clickX = canvasBox.x + canvasBox.width - 5;
-    }
-  }
-  await page.mouse.click(clickX, clickY);
+  await page.evaluate(() => {
+    const canvasElement = document.getElementById('gameCanvas');
+    if (!canvasElement) return;
+    canvasElement.setAttribute('tabindex', '-1');
+    canvasElement.focus();
+  });
 };
 
 test.beforeEach(async ({ page }) => {
diff --git a/e2e/harness.editor-mode.spec.js b/e2e/harness.editor-mode.spec.js
index 83a28106..7f804634 100644
--- a/e2e/harness.editor-mode.spec.js
+++ b/e2e/harness.editor-mode.spec.js
@@ -8,18 +8,12 @@ const focusGameCanvas = async (page) => {
   if (!canvasBox) {
     throw new Error('gameCanvas is not visible');
   }
-  const panelBox = await page.locator('#controlLeft').boundingBox();
-  let clickX = canvasBox.x + canvasBox.width * 0.5;
-  const clickY = canvasBox.y + canvasBox.height * 0.5;
-  if (panelBox) {
-    const safeX = panelBox.x + panelBox.width + 20;
-    if (safeX < canvasBox.x + canvasBox.width - 5) {
-      clickX = Math.max(clickX, safeX);
-    } else {
-      clickX = canvasBox.x + canvasBox.width - 5;
-    }
-  }
-  await page.mouse.click(clickX, clickY);
+  await page.evaluate(() => {
+    const canvasElement = document.getElementById('gameCanvas');
+    if (!canvasElement) return;
+    canvasElement.setAttribute('tabindex', '-1');
+    canvasElement.focus();
+  });
 };
 
 test.beforeEach(async ({ page }) => {
@@ -35,22 +29,19 @@ test('Editor mode toggle suppresses input and pauses timer', async ({ page }) =>
   const stateBefore = await page.evaluate(() => window.__E2E__.getState());
   expect(stateBefore.view.editorMode).toBe(false);
   expect(stateBefore.stage.panEnabled).toBe(true);
-  const inputBefore = await page.evaluate(() => window.lemmings?.game?.inputEnabled);
-  expect(inputBefore).toBe(true);
+  expect(stateBefore.game.inputEnabled).toBe(true);
 
   await page.keyboard.press('Shift+Backquote');
   await page.waitForFunction(() => window.__E2E__.getState().view.editorMode === true);
   await page.waitForFunction(() => window.__E2E__.getState().game.timer.running === false);
   const stateEdit = await page.evaluate(() => window.__E2E__.getState());
   expect(stateEdit.stage.panEnabled).toBe(false);
-  const inputEdit = await page.evaluate(() => window.lemmings?.game?.inputEnabled);
-  expect(inputEdit).toBe(false);
+  expect(stateEdit.game.inputEnabled).toBe(false);
 
   await page.keyboard.press('Shift+Backquote');
   await page.waitForFunction(() => window.__E2E__.getState().view.editorMode === false);
   await page.waitForFunction(() => window.__E2E__.getState().game.timer.running === true);
   const stateAfter = await page.evaluate(() => window.__E2E__.getState());
   expect(stateAfter.stage.panEnabled).toBe(true);
-  const inputAfter = await page.evaluate(() => window.lemmings?.game?.inputEnabled);
-  expect(inputAfter).toBe(true);
+  expect(stateAfter.game.inputEnabled).toBe(true);
 });
diff --git a/e2e/harness.editor.01-editor-harness-exposes-state-and-history.spec.js b/e2e/harness.editor.01-editor-harness-exposes-state-and-history.spec.js
new file mode 100644
index 00000000..515c4730
--- /dev/null
+++ b/e2e/harness.editor.01-editor-harness-exposes-state-and-history.spec.js
@@ -0,0 +1,473 @@
+import { expect, test } from '@playwright/test';
+import { installExternalAssetStubs } from './helpers/externalAssets.js';
+
+const waitForEditorHarness = async (page) => {
+  await page.waitForFunction(() => {
+    const api = window.__E2E__;
+    if (!api?.getState) return false;
+    const state = api.getState();
+    return Boolean(
+      state.editor?.session?.level?.header
+      && state.editor?.assets?.terrain?.length
+    );
+  });
+};
+
+const getEditorState = (page) => page.evaluate(() => window.__E2E__.getState());
+const applyEditorOps = (page, ops, options = {}) => page.evaluate(
+  ({ ops, options }) => window.__E2E__.editorApply(ops, options),
+  { ops, options }
+);
+
+const getCanvasBox = async (page) => {
+  const canvas = page.locator('#editorCanvas');
+  await expect(canvas).toBeVisible();
+  const box = await canvas.boundingBox();
+  if (!box) {
+    throw new Error('Editor canvas is not visible.');
+  }
+  return box;
+};
+
+const clickCanvas = async (page, xRatio, yRatio) => {
+  const box = await getCanvasBox(page);
+  await page.mouse.click(
+    box.x + box.width * xRatio,
+    box.y + box.height * yRatio
+  );
+};
+
+const getCanvasPoint = async (page, xRatio, yRatio) => {
+  const box = await getCanvasBox(page);
+  return {
+    x: box.x + box.width * xRatio,
+    y: box.y + box.height * yRatio
+  };
+};
+
+const getWorldPointFromPage = async (page, point) => {
+  return page.evaluate(({ x, y }) => {
+    return window.__E2E__?.stageWorldFromPage?.({ x, y }) || null;
+  }, { x: point.x, y: point.y });
+};
+
+const snapWorldValue = (value, gridSize, snapEnabled) => {
+  if (!snapEnabled || !Number.isFinite(gridSize) || gridSize <= 1) {
+    return Math.round(value);
+  }
+  return Math.round(value / gridSize) * gridSize;
+};
+
+const getWorldPointFromRatio = (state, xRatio, yRatio) => {
+  const viewRect = state?.stage?.viewRect;
+  if (!viewRect) {
+    throw new Error('Missing viewRect for world coordinate lookup.');
+  }
+  return {
+    x: viewRect.x + viewRect.w * xRatio,
+    y: viewRect.y + viewRect.h * yRatio
+  };
+};
+
+const dragCanvas = async (page, start, end) => {
+  const box = await getCanvasBox(page);
+  const startX = box.x + box.width * start.x;
+  const startY = box.y + box.height * start.y;
+  const endX = box.x + box.width * end.x;
+  const endY = box.y + box.height * end.y;
+  await page.mouse.move(startX, startY);
+  await page.mouse.down();
+  await page.mouse.move(endX, endY);
+  await page.mouse.up();
+};
+
+const worldToPage = (state, canvasBox, point) => {
+  const viewRect = state?.stage?.viewRect;
+  const gamePos = state?.stage?.gamePosition;
+  const scale = state?.stage?.gameScale ?? 1;
+  if (!viewRect || !gamePos || !Number.isFinite(scale)) {
+    throw new Error('Missing stage transform data for editor canvas.');
+  }
+  const canvasX = gamePos.x + (point.x - viewRect.x) * scale;
+  const canvasY = gamePos.y + (point.y - viewRect.y) * scale;
+  return {
+    x: canvasBox.x + canvasX,
+    y: canvasBox.y + canvasY
+  };
+};
+
+const getPagePointFromWorld = async (page, point) => {
+  return page.evaluate((worldPoint) => {
+    return window.__E2E__?.stagePageFromWorld?.(worldPoint) || null;
+  }, point);
+};
+
+const centerViewportOn = async (page, point) => {
+  await page.evaluate((targetPoint) => {
+    window.__E2E__?.centerStageOn?.(targetPoint);
+  }, point);
+};
+
+const selectPaletteItem = async (page, containerSelector, id) => {
+  const button = page.locator(`${containerSelector} button[data-id="${id}"]`);
+  await button.scrollIntoViewIfNeeded();
+  await button.click();
+};
+
+const captureSelectionScreenshot = async (page, name) => {
+  const canvas = page.locator('#editorCanvas');
+  await expect(canvas).toBeVisible();
+  const path = test.info().outputPath(name);
+  await canvas.screenshot({ path });
+  await test.info().attach(name, { path, contentType: 'image/png' });
+};
+
+const placeSelectAndSnapshot = async (page, options) => {
+  const {
+    tool,
+    paletteContainer,
+    id,
+    clickRatio,
+    snapshotName
+  } = options;
+  const before = await getEditorState(page);
+  const worldClick = getWorldPointFromRatio(before, clickRatio.x, clickRatio.y);
+  await centerViewportOn(page, worldClick);
+  const centered = await getEditorState(page);
+  const canvasBox = await getCanvasBox(page);
+  const pagePoint = worldToPage(centered, canvasBox, worldClick);
+
+  await page.click(`#editorToolList button[data-tool="${tool}"]`);
+  await selectPaletteItem(page, paletteContainer, id);
+  await page.mouse.click(pagePoint.x, pagePoint.y);
+
+  await page.evaluate(() => {
+    window.__E2E__?.pause?.();
+  });
+  await page.click('#editorToolList button[data-tool="select"]');
+  await page.mouse.click(pagePoint.x, pagePoint.y);
+  await captureSelectionScreenshot(page, snapshotName);
+  await page.keyboard.press('Control+Z');
+};
+
+const coerceNumber = (value, fallback = 0) => (
+  Number.isFinite(value) ? value : fallback
+);
+
+const getEntryCenter = (entry, meta) => {
+  const props = entry?.props || {};
+  const width = Number.isFinite(props.WIDTH)
+    ? props.WIDTH
+    : Number.isFinite(meta?.width)
+      ? meta.width
+      : 1;
+  const height = Number.isFinite(props.HEIGHT)
+    ? props.HEIGHT
+    : Number.isFinite(meta?.height)
+      ? meta.height
+      : 1;
+  const centerX = coerceNumber(props.X, 0) + Math.floor(Math.max(1, width) / 2);
+  const centerY = coerceNumber(props.Y, 0) + Math.floor(Math.max(1, height) / 2);
+  return { x: centerX, y: centerY };
+};
+
+const parseLevelName = (label) => {
+  const text = String(label || '');
+  const idx = text.indexOf(':');
+  const raw = idx === -1 ? text : text.slice(idx + 1);
+  return raw.replace(/\0/g, '').trim();
+};
+
+test.beforeEach(async ({ page }) => {
+  await installExternalAssetStubs(page);
+  await page.addInitScript(() => {
+    try {
+      window.localStorage?.clear?.();
+    } catch (error) {}
+    window.prompt = () => 'E2E Save';
+    window.alert = () => {};
+    if ('serviceWorker' in navigator) {
+      const noopRegister = async () => ({ unregister: async () => true });
+      navigator.serviceWorker.register = noopRegister;
+      navigator.serviceWorker.getRegistrations = async () => [];
+    }
+  });
+  await page.goto(`/editor.html?e2e=1&cacheBust=${Date.now()}`);
+  await waitForEditorHarness(page);
+});
+
+test('Editor harness exposes state and history', async ({ page }) => {
+  const state = await getEditorState(page);
+  expect(state.mode).toBe('editor');
+  expect(state.editor).toBeTruthy();
+  expect(state.editor.session).toBeTruthy();
+  expect(state.editor.controller).toBeTruthy();
+  expect(state.editor.history).toBeTruthy();
+  expect(state.editor.controller.tool).toBe('select');
+  expect(state.editor.history.count).toBeGreaterThan(0);
+  expect(Array.isArray(state.editor.validation.issues)).toBe(true);
+  expect(Array.isArray(state.editor.savedLevels)).toBe(true);
+
+  const title = state.editor.session.level.header.TITLE;
+  expect(String(title || '')).not.toBe('');
+  expect(Array.isArray(state.editor.session.level.headerOrder)).toBe(true);
+  expect(state.editor.assets.terrain.length).toBeGreaterThan(0);
+
+  const entry = await page.evaluate(() => window.__E2E__.getEditorHistoryEntry(0));
+  expect(entry.text.length).toBeGreaterThan(0);
+
+  const missingEntry = await page.evaluate(() => window.__E2E__.getEditorHistoryEntry(9999));
+  expect(missingEntry).toBeNull();
+});
+
+test('Editor playtest toggles timer and input state', async ({ page }) => {
+  let state = await getEditorState(page);
+  expect(state.view.editorMode).toBe(true);
+  expect(state.editor.playtest).toBe(false);
+  expect(state.game.timer.running).toBe(false);
+  expect(state.stage.panEnabled).toBe(false);
+  expect(state.game.inputEnabled).toBe(false);
+
+  await page.click('#editorPlaytestToggle');
+  await page.waitForFunction(() => {
+    const next = window.__E2E__.getState();
+    return next.editor.playtest === true && next.game.timer.running === true;
+  });
+  state = await getEditorState(page);
+  expect(state.stage.panEnabled).toBe(true);
+  expect(state.game.inputEnabled).toBe(true);
+
+  await page.click('#editorPlaytestToggle');
+  await page.waitForFunction(() => {
+    const next = window.__E2E__.getState();
+    return next.editor.playtest === false && next.game.timer.running === false;
+  });
+  state = await getEditorState(page);
+  expect(state.stage.panEnabled).toBe(false);
+  expect(state.game.inputEnabled).toBe(false);
+});
+
+test('Editor level selection loads into editor session', async ({ page }) => {
+  const state = await getEditorState(page);
+  const levelSelect = page.locator('#editorLevelIndexSelect');
+  const optionCount = await levelSelect.locator('option').count();
+  expect(optionCount).toBeGreaterThan(1);
+
+  const currentIndex = state.view.levelIndex ?? 0;
+  const targetIndex = currentIndex === 0 ? 1 : 0;
+  const targetOption = levelSelect.locator(`option[value="${targetIndex}"]`);
+  const targetLabel = await targetOption.textContent();
+  const targetName = parseLevelName(targetLabel);
+  expect(targetName).not.toBe('');
+
+  await levelSelect.selectOption(String(targetIndex));
+  await page.waitForFunction((name) => {
+    const title = window.__E2E__.getState().editor.session.level.header.TITLE || '';
+    return title.replace(/\0/g, '').trim() === name;
+  }, targetName);
+
+  const nextState = await getEditorState(page);
+  expect(nextState.view.editorMode).toBe(true);
+  expect(nextState.view.levelIndex).toBe(targetIndex);
+  const normalizedTitle = String(nextState.editor.session.level.header.TITLE || '')
+    .replace(/\0/g, '')
+    .trim();
+  expect(normalizedTitle).toBe(targetName);
+});
+
+test('Editor built-in classic level can be edited, saved, reloaded, and exported', async ({ page }) => {
+  const state = await getEditorState(page);
+  const levelSelect = page.locator('#editorLevelIndexSelect');
+  const optionCount = await levelSelect.locator('option').count();
+  expect(optionCount).toBeGreaterThan(1);
+
+  const currentIndex = state.view.levelIndex ?? 0;
+  const targetIndex = currentIndex === 0 ? 1 : 0;
+  const targetOption = levelSelect.locator(`option[value="${targetIndex}"]`);
+  const targetLabel = await targetOption.textContent();
+  const targetName = parseLevelName(targetLabel);
+  expect(targetName).not.toBe('');
+
+  await levelSelect.selectOption(String(targetIndex));
+  await page.waitForFunction((name) => {
+    const title = window.__E2E__.getState().editor.session.level.header.TITLE || '';
+    return title.replace(/\0/g, '').trim() === name;
+  }, targetName);
+
+  const loaded = await getEditorState(page);
+  const terrainId = loaded.editor.assets.terrain[0]?.id;
+  expect(Number.isFinite(terrainId)).toBe(true);
+
+  const editedTitle = 'Classic Edited E2E';
+  const uniqueX = 137;
+  const uniqueY = 93;
+  const edited = await applyEditorOps(page, [
+    { type: 'level.patchHeader', args: { set: { TITLE: editedTitle } } },
+    { type: 'entry.add', args: { kind: 'terrain', props: { PIECE: terrainId, X: uniqueX, Y: uniqueY } } },
+    { type: 'level.save', args: { name: 'classic-edited-e2e' } }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+  expect(edited.ok).toBe(true);
+  const saveResult = edited.results.find(result => result.type === 'level.save');
+  const savedId = saveResult?.value?.savedId;
+  expect(savedId).toBeTruthy();
+
+  const reloaded = await applyEditorOps(page, [
+    { type: 'level.patchHeader', args: { set: { TITLE: 'Unsaved Noise' } } },
+    { type: 'level.loadSaved', args: { savedId, resetHistory: true } },
+    { type: 'level.export', args: { format: 'classicLvl', filename: 'classic-edited-e2e.lvl' } }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+
+  expect(reloaded.ok).toBe(true);
+  expect(reloaded.state.session.level.header.TITLE).toBe(editedTitle);
+  expect(reloaded.state.session.level.terrains.some(entry =>
+    entry.props?.PIECE === terrainId
+    && entry.props?.X === uniqueX
+    && entry.props?.Y === uniqueY
+  )).toBe(true);
+  const exported = reloaded.resources.find(resource => resource.meta?.format === 'classicLvl');
+  expect(exported?.encoding).toBe('base64');
+  expect(exported?.data?.length || 0).toBeGreaterThan(0);
+});
+
+test('Editor new level seeds entrance and exit', async ({ page }) => {
+  await page.click('#editorNewLevel');
+  await page.waitForFunction(() => {
+    const state = window.__E2E__?.getState?.();
+    return (state?.editor?.session?.level?.gadgets?.length || 0) >= 1;
+  });
+  const state = await getEditorState(page);
+  const entranceId = state.editor.assets.entranceId;
+  const exitId = state.editor.assets.exitId;
+  const gadgets = state.editor.session.level.gadgets || [];
+  const entrance = gadgets.find(entry => entry?.props?.PIECE === entranceId);
+  const exit = gadgets.find(entry => entry?.props?.PIECE === exitId);
+  expect(entrance).toBeTruthy();
+  expect(exit).toBeTruthy();
+
+  const viewRect = state.stage.viewRect;
+  const entranceX = entrance?.props?.X ?? 0;
+  const exitX = exit?.props?.X ?? 0;
+  expect(entranceX).toBeGreaterThanOrEqual(viewRect.x);
+  expect(entranceX).toBeLessThanOrEqual(viewRect.x + viewRect.w);
+  expect(exitX).toBeGreaterThanOrEqual(viewRect.x);
+  expect(exitX).toBeLessThanOrEqual(viewRect.x + viewRect.w);
+});
+
+test('Editor tool.place uses centered terrain placement', async ({ page }) => {
+  const before = await getEditorState(page);
+  const terrainId = before.editor.assets.terrain[0]?.id;
+  expect(Number.isFinite(terrainId)).toBe(true);
+
+  const clickRatio = { x: 0.25, y: 0.35 };
+  const worldClick = getWorldPointFromRatio(before, clickRatio.x, clickRatio.y);
+
+  const result = await applyEditorOps(page, [
+    {
+      type: 'tool.place',
+      args: {
+        tool: 'terrain',
+        pieceId: terrainId,
+        x: worldClick.x,
+        y: worldClick.y
+      }
+    }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+
+  expect(result.ok).toBe(true);
+  const after = result.state;
+  const terrains = after.session.level.terrains;
+  const placed = terrains[terrains.length - 1];
+  expect(placed.props.PIECE).toBe(Number(terrainId));
+  const terrainMeta = after.assets.terrain.find(item => item.id === terrainId);
+  const offsetX = terrainMeta?.width ? Math.floor(terrainMeta.width / 2) : 0;
+  const offsetY = terrainMeta?.height ? Math.floor(terrainMeta.height / 2) : 0;
+  const snappedX = snapWorldValue(worldClick.x, after.controller.gridSize, after.controller.snapEnabled);
+  const snappedY = snapWorldValue(worldClick.y, after.controller.gridSize, after.controller.snapEnabled);
+  expect(placed.props.X).toBe(snappedX - offsetX);
+  expect(placed.props.Y).toBe(snappedY - offsetY);
+});
+
+test('Editor layer order buttons reorder selection', async ({ page }) => {
+  const state = await getEditorState(page);
+  const terrainId = state.editor.assets.terrain[0]?.id;
+  expect(Number.isFinite(terrainId)).toBe(true);
+  const result = await applyEditorOps(page, [
+    { type: 'entry.add', args: { kind: 'terrain', props: { PIECE: terrainId, X: 10, Y: 10 } } },
+    { type: 'entry.add', args: { kind: 'terrain', props: { PIECE: terrainId, X: 30, Y: 10 } } },
+    { type: 'selection.set', args: { selection: [{ kind: 'terrain', index: 0 }] } }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+  expect(result.ok).toBe(true);
+
+  await page.waitForFunction(() => {
+    return window.__E2E__.getState().editor.controller.selectionEntries.length === 1;
+  });
+
+  const beforeIndex = await page.evaluate(
+    () => window.__E2E__.getState().editor.controller.selectionEntries[0].index
+  );
+  await page.click('#editorSelectionMoveForward');
+  const afterIndex = await page.evaluate(
+    () => window.__E2E__.getState().editor.controller.selectionEntries[0].index
+  );
+  expect(afterIndex).toBe(beforeIndex + 1);
+});
+
+test('Editor gadget and trigger placement use centered tool placement', async ({ page }) => {
+  let state = await getEditorState(page);
+  const gadgetId = state.editor.assets.gadgets[0]?.id;
+  expect(Number.isFinite(gadgetId)).toBe(true);
+
+  const gadgetClick = { x: 64, y: 64 };
+  let result = await applyEditorOps(page, [
+    {
+      type: 'tool.place',
+      args: {
+        tool: 'gadget',
+        pieceId: gadgetId,
+        x: gadgetClick.x,
+        y: gadgetClick.y
+      }
+    }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+
+  expect(result.ok).toBe(true);
+  state = result.state;
+  let gadgets = state.session.level.gadgets;
+  let placed = gadgets[gadgets.length - 1];
+  expect(placed.props.PIECE).toBe(Number(gadgetId));
+  const gadgetMeta = state.assets.gadgets.find(item => item.id === gadgetId);
+  const offsetX = gadgetMeta?.width ? Math.floor(gadgetMeta.width / 2) : 0;
+  const offsetY = gadgetMeta?.height ? Math.floor(gadgetMeta.height / 2) : 0;
+  const snappedX = snapWorldValue(gadgetClick.x, state.controller.gridSize, state.controller.snapEnabled);
+  const snappedY = snapWorldValue(gadgetClick.y, state.controller.gridSize, state.controller.snapEnabled);
+  expect(placed.props.X).toBe(snappedX - offsetX);
+  expect(placed.props.Y).toBe(snappedY - offsetY);
+
+  const triggerId = state.assets.triggers[0]?.id;
+  expect(Number.isFinite(triggerId)).toBe(true);
+  const triggerClick = { x: 96, y: 96 };
+  result = await applyEditorOps(page, [
+    {
+      type: 'tool.place',
+      args: {
+        tool: 'trigger',
+        pieceId: triggerId,
+        x: triggerClick.x,
+        y: triggerClick.y
+      }
+    }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+
+  expect(result.ok).toBe(true);
+  state = result.state;
+  gadgets = state.session.level.gadgets;
+  placed = gadgets[gadgets.length - 1];
+  expect(placed.props.PIECE).toBe(Number(triggerId));
+  const triggerMeta = state.assets.gadgets.find(item => item.id === triggerId);
+  const triggerOffsetX = triggerMeta?.width ? Math.floor(triggerMeta.width / 2) : 0;
+  const triggerOffsetY = triggerMeta?.height ? Math.floor(triggerMeta.height / 2) : 0;
+  const triggerX = snapWorldValue(triggerClick.x, state.controller.gridSize, state.controller.snapEnabled);
+  const triggerY = snapWorldValue(triggerClick.y, state.controller.gridSize, state.controller.snapEnabled);
+  expect(placed.props.X).toBe(triggerX - triggerOffsetX);
+  expect(placed.props.Y).toBe(triggerY - triggerOffsetY);
+});
diff --git a/e2e/harness.editor.02-editor-pack-switch-refreshes-palettes-and-placem.spec.js b/e2e/harness.editor.02-editor-pack-switch-refreshes-palettes-and-placem.spec.js
new file mode 100644
index 00000000..d1e2d6eb
--- /dev/null
+++ b/e2e/harness.editor.02-editor-pack-switch-refreshes-palettes-and-placem.spec.js
@@ -0,0 +1,430 @@
+import { expect, test } from '@playwright/test';
+import { installExternalAssetStubs } from './helpers/externalAssets.js';
+
+const waitForEditorHarness = async (page) => {
+  await page.waitForFunction(() => {
+    const api = window.__E2E__;
+    if (!api?.getState) return false;
+    const state = api.getState();
+    return Boolean(
+      state.editor?.session?.level?.header
+      && state.editor?.assets?.terrain?.length
+    );
+  });
+};
+
+const getEditorState = (page) => page.evaluate(() => window.__E2E__.getState());
+const applyEditorOps = (page, ops, options = {}) => page.evaluate(
+  ({ ops, options }) => window.__E2E__.editorApply(ops, options),
+  { ops, options }
+);
+
+const getCanvasBox = async (page) => {
+  const canvas = page.locator('#editorCanvas');
+  await expect(canvas).toBeVisible();
+  const box = await canvas.boundingBox();
+  if (!box) {
+    throw new Error('Editor canvas is not visible.');
+  }
+  return box;
+};
+
+const clickCanvas = async (page, xRatio, yRatio) => {
+  const box = await getCanvasBox(page);
+  await page.mouse.click(
+    box.x + box.width * xRatio,
+    box.y + box.height * yRatio
+  );
+};
+
+const getCanvasPoint = async (page, xRatio, yRatio) => {
+  const box = await getCanvasBox(page);
+  return {
+    x: box.x + box.width * xRatio,
+    y: box.y + box.height * yRatio
+  };
+};
+
+const getWorldPointFromPage = async (page, point) => {
+  return page.evaluate(({ x, y }) => {
+    return window.__E2E__?.stageWorldFromPage?.({ x, y }) || null;
+  }, { x: point.x, y: point.y });
+};
+
+const snapWorldValue = (value, gridSize, snapEnabled) => {
+  if (!snapEnabled || !Number.isFinite(gridSize) || gridSize <= 1) {
+    return Math.round(value);
+  }
+  return Math.round(value / gridSize) * gridSize;
+};
+
+const getWorldPointFromRatio = (state, xRatio, yRatio) => {
+  const viewRect = state?.stage?.viewRect;
+  if (!viewRect) {
+    throw new Error('Missing viewRect for world coordinate lookup.');
+  }
+  return {
+    x: viewRect.x + viewRect.w * xRatio,
+    y: viewRect.y + viewRect.h * yRatio
+  };
+};
+
+const dragCanvas = async (page, start, end) => {
+  const box = await getCanvasBox(page);
+  const startX = box.x + box.width * start.x;
+  const startY = box.y + box.height * start.y;
+  const endX = box.x + box.width * end.x;
+  const endY = box.y + box.height * end.y;
+  await page.mouse.move(startX, startY);
+  await page.mouse.down();
+  await page.mouse.move(endX, endY);
+  await page.mouse.up();
+};
+
+const worldToPage = (state, canvasBox, point) => {
+  const viewRect = state?.stage?.viewRect;
+  const gamePos = state?.stage?.gamePosition;
+  const scale = state?.stage?.gameScale ?? 1;
+  if (!viewRect || !gamePos || !Number.isFinite(scale)) {
+    throw new Error('Missing stage transform data for editor canvas.');
+  }
+  const canvasX = gamePos.x + (point.x - viewRect.x) * scale;
+  const canvasY = gamePos.y + (point.y - viewRect.y) * scale;
+  return {
+    x: canvasBox.x + canvasX,
+    y: canvasBox.y + canvasY
+  };
+};
+
+const getPagePointFromWorld = async (page, point) => {
+  return page.evaluate((worldPoint) => {
+    return window.__E2E__?.stagePageFromWorld?.(worldPoint) || null;
+  }, point);
+};
+
+const centerViewportOn = async (page, point) => {
+  await page.evaluate((targetPoint) => {
+    window.__E2E__?.centerStageOn?.(targetPoint);
+  }, point);
+};
+
+const selectPaletteItem = async (page, containerSelector, id) => {
+  const button = page.locator(`${containerSelector} button[data-id="${id}"]`);
+  await button.scrollIntoViewIfNeeded();
+  await button.click();
+};
+
+const captureSelectionScreenshot = async (page, name) => {
+  const canvas = page.locator('#editorCanvas');
+  await expect(canvas).toBeVisible();
+  const path = test.info().outputPath(name);
+  await canvas.screenshot({ path });
+  await test.info().attach(name, { path, contentType: 'image/png' });
+};
+
+const placeSelectAndSnapshot = async (page, options) => {
+  const {
+    tool,
+    paletteContainer,
+    id,
+    clickRatio,
+    snapshotName
+  } = options;
+  const before = await getEditorState(page);
+  const worldClick = getWorldPointFromRatio(before, clickRatio.x, clickRatio.y);
+  await centerViewportOn(page, worldClick);
+  const centered = await getEditorState(page);
+  const canvasBox = await getCanvasBox(page);
+  const pagePoint = worldToPage(centered, canvasBox, worldClick);
+
+  await page.click(`#editorToolList button[data-tool="${tool}"]`);
+  await selectPaletteItem(page, paletteContainer, id);
+  await page.mouse.click(pagePoint.x, pagePoint.y);
+
+  await page.evaluate(() => {
+    window.__E2E__?.pause?.();
+  });
+  await page.click('#editorToolList button[data-tool="select"]');
+  await page.mouse.click(pagePoint.x, pagePoint.y);
+  await captureSelectionScreenshot(page, snapshotName);
+  await page.keyboard.press('Control+Z');
+};
+
+const coerceNumber = (value, fallback = 0) => (
+  Number.isFinite(value) ? value : fallback
+);
+
+const getEntryCenter = (entry, meta) => {
+  const props = entry?.props || {};
+  const width = Number.isFinite(props.WIDTH)
+    ? props.WIDTH
+    : Number.isFinite(meta?.width)
+      ? meta.width
+      : 1;
+  const height = Number.isFinite(props.HEIGHT)
+    ? props.HEIGHT
+    : Number.isFinite(meta?.height)
+      ? meta.height
+      : 1;
+  const centerX = coerceNumber(props.X, 0) + Math.floor(Math.max(1, width) / 2);
+  const centerY = coerceNumber(props.Y, 0) + Math.floor(Math.max(1, height) / 2);
+  return { x: centerX, y: centerY };
+};
+
+const parseLevelName = (label) => {
+  const text = String(label || '');
+  const idx = text.indexOf(':');
+  const raw = idx === -1 ? text : text.slice(idx + 1);
+  return raw.replace(/\0/g, '').trim();
+};
+
+test.beforeEach(async ({ page }) => {
+  await installExternalAssetStubs(page);
+  await page.addInitScript(() => {
+    try {
+      window.localStorage?.clear?.();
+    } catch (error) {}
+    window.prompt = () => 'E2E Save';
+    window.alert = () => {};
+    if ('serviceWorker' in navigator) {
+      const noopRegister = async () => ({ unregister: async () => true });
+      navigator.serviceWorker.register = noopRegister;
+      navigator.serviceWorker.getRegistrations = async () => [];
+    }
+  });
+  await page.goto(`/editor.html?e2e=1&cacheBust=${Date.now()}`);
+  await waitForEditorHarness(page);
+});
+
+test('Editor pack switch refreshes palettes and placement', async ({ page }) => {
+  const state = await getEditorState(page);
+  const gameTypeSelect = page.locator('#editorGameTypeSelect');
+  const selectInfo = await page.evaluate(() => {
+    const select = document.getElementById('editorGameTypeSelect');
+    if (!select) return null;
+    const values = Array.from(select.options).map(option => option.value);
+    return { selectedIndex: select.selectedIndex, values };
+  });
+  expect(selectInfo?.values?.length).toBeGreaterThan(1);
+  const nextIndex = selectInfo.selectedIndex === 0 ? 1 : 0;
+  const nextValue = selectInfo.values[nextIndex];
+
+  await gameTypeSelect.selectOption(nextValue);
+  await page.waitForFunction((prevType) => {
+    return window.__E2E__.getState().view.gameType !== prevType;
+  }, state.view.gameType);
+
+  const nextState = await getEditorState(page);
+  expect(nextState.view.gameType).not.toBe(state.view.gameType);
+  expect(nextState.editor.assets.terrain.length).toBeGreaterThan(0);
+
+  const firstTerrain = nextState.editor.assets.terrain[0];
+  const paletteFirstId = await page.locator('#editorPaletteTerrain button').first().getAttribute('data-id');
+  expect(Number(paletteFirstId)).toBe(firstTerrain.id);
+
+  const clickPoint = getWorldPointFromRatio(nextState, 0.2, 0.3);
+  const result = await applyEditorOps(page, [
+    {
+      type: 'tool.place',
+      args: {
+        tool: 'terrain',
+        pieceId: firstTerrain.id,
+        x: clickPoint.x,
+        y: clickPoint.y
+      }
+    }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+
+  expect(result.ok).toBe(true);
+  const placed = result.state.session.level.terrains.slice(-1)[0];
+  expect(placed.props.PIECE).toBe(firstTerrain.id);
+});
+
+test('Editor selection overlays render for every asset', async ({ page }) => {
+  test.slow();
+  await page.fill('#editorPaletteSearch', '');
+  await page.click('#editorPaletteTabs button[data-tab="terrain"]');
+  const terrainIds = await page.$$eval('#editorPaletteTerrain button', (buttons) => (
+    buttons.map(button => Number(button.dataset.id)).filter(Number.isFinite)
+  ));
+  const gadgetIds = await page.$$eval('#editorPaletteGadgets button', (buttons) => (
+    buttons.map(button => Number(button.dataset.id)).filter(Number.isFinite)
+  ));
+  const triggerIds = await page.$$eval('#editorPaletteTriggers button', (buttons) => (
+    buttons.map(button => Number(button.dataset.id)).filter(Number.isFinite)
+  ));
+
+  const clickRatio = { x: 0.3, y: 0.35 };
+
+  for (const id of terrainIds) {
+    await placeSelectAndSnapshot(page, {
+      tool: 'terrain',
+      paletteContainer: '#editorPaletteTerrain',
+      id,
+      clickRatio,
+      snapshotName: `editor-selection-terrain-${id}.png`
+    });
+  }
+
+  await page.click('#editorPaletteTabs button[data-tab="gadgets"]');
+  for (const id of gadgetIds) {
+    await placeSelectAndSnapshot(page, {
+      tool: 'gadget',
+      paletteContainer: '#editorPaletteGadgets',
+      id,
+      clickRatio,
+      snapshotName: `editor-selection-gadget-${id}.png`
+    });
+  }
+
+  await page.click('#editorPaletteTabs button[data-tab="triggers"]');
+  for (const id of triggerIds) {
+    await placeSelectAndSnapshot(page, {
+      tool: 'trigger',
+      paletteContainer: '#editorPaletteTriggers',
+      id,
+      clickRatio,
+      snapshotName: `editor-selection-trigger-${id}.png`
+    });
+  }
+});
+
+test('Editor placement preserves viewport when panned', async ({ page }) => {
+  let state = await getEditorState(page);
+  const scale = state.stage.gameScale || 2;
+  const viewRect = state.stage.viewRect;
+  const stage = state.stage;
+  if (!viewRect || !stage) {
+    throw new Error('Missing stage view data');
+  }
+  const targetX = Math.max(0, viewRect.x + viewRect.w * 0.6);
+  await page.evaluate(({ x, y, scale }) => {
+    window.__E2E__?.centerStageOn?.({ x, y, scale });
+  }, { x: targetX + viewRect.w / 2, y: viewRect.y + viewRect.h / 2, scale });
+
+  await page.waitForFunction((x) => {
+    const rect = window.__E2E__.getState().stage.viewRect;
+    return rect && rect.x >= x - 1;
+  }, targetX);
+
+  state = await getEditorState(page);
+  const beforeX = state.stage.viewRect.x;
+  const beforeScale = state.stage.gameScale;
+  const canvasBox = await getCanvasBox(page);
+
+  await page.click('#editorToolList button[data-tool="gadget"]');
+  const gadgetEntry = state.editor.assets.gadgets.find(entry => entry.width > 0 || entry.height > 0);
+  if (!gadgetEntry) {
+    throw new Error('No gadget entry found');
+  }
+  await page.click(`#editorPaletteGadgets button[data-id="${gadgetEntry.id}"]`);
+
+  const placePoint = {
+    x: beforeX + Math.min(80, state.stage.viewRect.w * 0.4),
+    y: 80
+  };
+  const pagePoint = worldToPage(state, canvasBox, placePoint);
+  await page.mouse.click(pagePoint.x, pagePoint.y);
+
+  await page.waitForFunction((expected) => {
+    const next = window.__E2E__.getState().stage.viewRect;
+    return next && Math.abs(next.x - expected) < 1;
+  }, beforeX);
+
+  state = await getEditorState(page);
+  expect(Math.abs(state.stage.gameScale - beforeScale)).toBeLessThan(0.01);
+});
+
+test('Editor selection updates inspector state', async ({ page }) => {
+  const before = await getEditorState(page);
+  const terrainId = before.editor.assets.terrain[0]?.id;
+  expect(Number.isFinite(terrainId)).toBe(true);
+
+  const clickPoint = getWorldPointFromRatio(before, 0.3, 0.55);
+  const placeResult = await applyEditorOps(page, [
+    {
+      type: 'tool.place',
+      args: {
+        tool: 'terrain',
+        pieceId: terrainId,
+        x: clickPoint.x,
+        y: clickPoint.y
+      }
+    }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+
+  expect(placeResult.ok).toBe(true);
+  const placedIndex = placeResult.state.session.level.terrains.length - 1;
+  await applyEditorOps(page, [
+    { type: 'selection.set', args: { selection: [{ kind: 'terrain', index: placedIndex }] } }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+
+  await page.waitForFunction(() => {
+    return window.__E2E__.getState().editor.controller.selectionEntries.length === 1;
+  });
+
+  const state = await getEditorState(page);
+  const selected = state.editor.controller.selectionEntries[0];
+  expect(selected.type).toBe('terrain');
+  expect(selected.entry.props.PIECE).toBe(Number(terrainId));
+
+  await expect(page.locator('#editorSelType')).toHaveText('terrain');
+  await expect(page.locator('#editorSelName')).not.toHaveText('');
+  await expect(page.locator('#editorSelX')).toBeEnabled();
+});
+
+test('Editor brush and steel tools modify level data', async ({ page }) => {
+  const before = await getEditorState(page);
+  const terrainBefore = before.editor.session.level.terrains.length;
+  const brushStart = getWorldPointFromRatio(before, 0.2, 0.3);
+  const brushEnd = getWorldPointFromRatio(before, 0.35, 0.4);
+  const brushResult = await applyEditorOps(page, [
+    { type: 'editor.setBrushSettings', args: { brushSize: 2 } },
+    {
+      type: 'tool.stroke',
+      args: {
+        tool: 'brush',
+        points: [brushStart, brushEnd]
+      }
+    }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+
+  expect(brushResult.ok).toBe(true);
+  const terrainAfter = brushResult.state.session.level.terrains.length;
+  expect(terrainAfter).toBeGreaterThan(terrainBefore + 1);
+
+  const steelBefore = brushResult.state.session.level.steel.length;
+  const steelRect = {
+    x: Math.round(brushStart.x + 40),
+    y: Math.round(brushStart.y + 20),
+    width: 12,
+    height: 12
+  };
+  const steelResult = await applyEditorOps(page, [
+    { type: 'tool.steelRect', args: { rects: [steelRect] } }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+
+  expect(steelResult.ok).toBe(true);
+  const steel = steelResult.state.session.level.steel;
+  expect(steel.length).toBeGreaterThan(steelBefore);
+  const placed = steel[steel.length - 1];
+  expect(placed.props.WIDTH).toBeGreaterThan(1);
+  expect(placed.props.HEIGHT).toBeGreaterThan(1);
+});
+
+test('Editor brush respects grid size snapping', async ({ page }) => {
+  const before = await getEditorState(page);
+  const clickPoint = getWorldPointFromRatio(before, 0.22, 0.32);
+  const result = await applyEditorOps(page, [
+    { type: 'editor.setBrushSettings', args: { gridSize: 8, snapEnabled: true, brushSize: 1 } },
+    { type: 'tool.stroke', args: { tool: 'brush', points: [clickPoint] } }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+
+  expect(result.ok).toBe(true);
+  const placed = result.state.session.level.terrains[result.state.session.level.terrains.length - 1];
+  const meta = result.state.assets.terrain.find(item => item.id === placed.props.PIECE);
+  const offsetX = meta?.width ? Math.floor(meta.width / 2) : 0;
+  const offsetY = meta?.height ? Math.floor(meta.height / 2) : 0;
+  expect((placed.props.X + offsetX) % 8).toBe(0);
+  expect((placed.props.Y + offsetY) % 8).toBe(0);
+});
diff --git a/e2e/harness.editor.03-editor-eraser-removes-terrain-entries.spec.js b/e2e/harness.editor.03-editor-eraser-removes-terrain-entries.spec.js
new file mode 100644
index 00000000..67575a18
--- /dev/null
+++ b/e2e/harness.editor.03-editor-eraser-removes-terrain-entries.spec.js
@@ -0,0 +1,426 @@
+import { expect, test } from '@playwright/test';
+import { installExternalAssetStubs } from './helpers/externalAssets.js';
+
+const waitForEditorHarness = async (page) => {
+  await page.waitForFunction(() => {
+    const api = window.__E2E__;
+    if (!api?.getState) return false;
+    const state = api.getState();
+    return Boolean(
+      state.editor?.session?.level?.header
+      && state.editor?.assets?.terrain?.length
+    );
+  });
+};
+
+const getEditorState = (page) => page.evaluate(() => window.__E2E__.getState());
+const applyEditorOps = (page, ops, options = {}) => page.evaluate(
+  ({ ops, options }) => window.__E2E__.editorApply(ops, options),
+  { ops, options }
+);
+
+const getCanvasBox = async (page) => {
+  const canvas = page.locator('#editorCanvas');
+  await expect(canvas).toBeVisible();
+  const box = await canvas.boundingBox();
+  if (!box) {
+    throw new Error('Editor canvas is not visible.');
+  }
+  return box;
+};
+
+const clickCanvas = async (page, xRatio, yRatio) => {
+  const box = await getCanvasBox(page);
+  await page.mouse.click(
+    box.x + box.width * xRatio,
+    box.y + box.height * yRatio
+  );
+};
+
+const getCanvasPoint = async (page, xRatio, yRatio) => {
+  const box = await getCanvasBox(page);
+  return {
+    x: box.x + box.width * xRatio,
+    y: box.y + box.height * yRatio
+  };
+};
+
+const getWorldPointFromPage = async (page, point) => {
+  return page.evaluate(({ x, y }) => {
+    return window.__E2E__?.stageWorldFromPage?.({ x, y }) || null;
+  }, { x: point.x, y: point.y });
+};
+
+const snapWorldValue = (value, gridSize, snapEnabled) => {
+  if (!snapEnabled || !Number.isFinite(gridSize) || gridSize <= 1) {
+    return Math.round(value);
+  }
+  return Math.round(value / gridSize) * gridSize;
+};
+
+const getWorldPointFromRatio = (state, xRatio, yRatio) => {
+  const viewRect = state?.stage?.viewRect;
+  if (!viewRect) {
+    throw new Error('Missing viewRect for world coordinate lookup.');
+  }
+  return {
+    x: viewRect.x + viewRect.w * xRatio,
+    y: viewRect.y + viewRect.h * yRatio
+  };
+};
+
+const dragCanvas = async (page, start, end) => {
+  const box = await getCanvasBox(page);
+  const startX = box.x + box.width * start.x;
+  const startY = box.y + box.height * start.y;
+  const endX = box.x + box.width * end.x;
+  const endY = box.y + box.height * end.y;
+  await page.mouse.move(startX, startY);
+  await page.mouse.down();
+  await page.mouse.move(endX, endY);
+  await page.mouse.up();
+};
+
+const worldToPage = (state, canvasBox, point) => {
+  const viewRect = state?.stage?.viewRect;
+  const gamePos = state?.stage?.gamePosition;
+  const scale = state?.stage?.gameScale ?? 1;
+  if (!viewRect || !gamePos || !Number.isFinite(scale)) {
+    throw new Error('Missing stage transform data for editor canvas.');
+  }
+  const canvasX = gamePos.x + (point.x - viewRect.x) * scale;
+  const canvasY = gamePos.y + (point.y - viewRect.y) * scale;
+  return {
+    x: canvasBox.x + canvasX,
+    y: canvasBox.y + canvasY
+  };
+};
+
+const getPagePointFromWorld = async (page, point) => {
+  return page.evaluate((worldPoint) => {
+    return window.__E2E__?.stagePageFromWorld?.(worldPoint) || null;
+  }, point);
+};
+
+const centerViewportOn = async (page, point) => {
+  await page.evaluate((targetPoint) => {
+    window.__E2E__?.centerStageOn?.(targetPoint);
+  }, point);
+};
+
+const selectPaletteItem = async (page, containerSelector, id) => {
+  const button = page.locator(`${containerSelector} button[data-id="${id}"]`);
+  await button.scrollIntoViewIfNeeded();
+  await button.click();
+};
+
+const captureSelectionScreenshot = async (page, name) => {
+  const canvas = page.locator('#editorCanvas');
+  await expect(canvas).toBeVisible();
+  const path = test.info().outputPath(name);
+  await canvas.screenshot({ path });
+  await test.info().attach(name, { path, contentType: 'image/png' });
+};
+
+const placeSelectAndSnapshot = async (page, options) => {
+  const {
+    tool,
+    paletteContainer,
+    id,
+    clickRatio,
+    snapshotName
+  } = options;
+  const before = await getEditorState(page);
+  const worldClick = getWorldPointFromRatio(before, clickRatio.x, clickRatio.y);
+  await centerViewportOn(page, worldClick);
+  const centered = await getEditorState(page);
+  const canvasBox = await getCanvasBox(page);
+  const pagePoint = worldToPage(centered, canvasBox, worldClick);
+
+  await page.click(`#editorToolList button[data-tool="${tool}"]`);
+  await selectPaletteItem(page, paletteContainer, id);
+  await page.mouse.click(pagePoint.x, pagePoint.y);
+
+  await page.evaluate(() => {
+    window.__E2E__?.pause?.();
+  });
+  await page.click('#editorToolList button[data-tool="select"]');
+  await page.mouse.click(pagePoint.x, pagePoint.y);
+  await captureSelectionScreenshot(page, snapshotName);
+  await page.keyboard.press('Control+Z');
+};
+
+const coerceNumber = (value, fallback = 0) => (
+  Number.isFinite(value) ? value : fallback
+);
+
+const getEntryCenter = (entry, meta) => {
+  const props = entry?.props || {};
+  const width = Number.isFinite(props.WIDTH)
+    ? props.WIDTH
+    : Number.isFinite(meta?.width)
+      ? meta.width
+      : 1;
+  const height = Number.isFinite(props.HEIGHT)
+    ? props.HEIGHT
+    : Number.isFinite(meta?.height)
+      ? meta.height
+      : 1;
+  const centerX = coerceNumber(props.X, 0) + Math.floor(Math.max(1, width) / 2);
+  const centerY = coerceNumber(props.Y, 0) + Math.floor(Math.max(1, height) / 2);
+  return { x: centerX, y: centerY };
+};
+
+const parseLevelName = (label) => {
+  const text = String(label || '');
+  const idx = text.indexOf(':');
+  const raw = idx === -1 ? text : text.slice(idx + 1);
+  return raw.replace(/\0/g, '').trim();
+};
+
+test.beforeEach(async ({ page }) => {
+  await installExternalAssetStubs(page);
+  await page.addInitScript(() => {
+    try {
+      window.localStorage?.clear?.();
+    } catch (error) {}
+    window.prompt = () => 'E2E Save';
+    window.alert = () => {};
+    if ('serviceWorker' in navigator) {
+      const noopRegister = async () => ({ unregister: async () => true });
+      navigator.serviceWorker.register = noopRegister;
+      navigator.serviceWorker.getRegistrations = async () => [];
+    }
+  });
+  await page.goto(`/editor.html?e2e=1&cacheBust=${Date.now()}`);
+  await waitForEditorHarness(page);
+});
+
+test('Editor eraser removes terrain entries', async ({ page }) => {
+  const before = await getEditorState(page);
+  const clickPoint = getWorldPointFromRatio(before, 0.25, 0.4);
+  const placeResult = await applyEditorOps(page, [
+    {
+      type: 'tool.place',
+      args: {
+        tool: 'terrain',
+        pieceId: before.editor.assets.terrain[0]?.id,
+        x: clickPoint.x,
+        y: clickPoint.y
+      }
+    }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+
+  expect(placeResult.ok).toBe(true);
+  const afterCount = placeResult.state.session.level.terrains.length;
+
+  const eraseResult = await applyEditorOps(page, [
+    { type: 'tool.erase', args: { points: [clickPoint] } }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+
+  expect(eraseResult.ok).toBe(true);
+  expect(eraseResult.state.session.level.terrains.length).toBeLessThan(afterCount);
+});
+
+test('Editor exports and imports classic levels via editor.apply', async ({ page }) => {
+  const exportResult = await applyEditorOps(page, [
+    { type: 'level.export', args: { format: 'classicLvl', filename: 'e2e.lvl' } }
+  ], { preview: { refresh: false } });
+
+  expect(exportResult.ok).toBe(true);
+  const resource = exportResult.resources?.[0];
+  expect(resource?.data).toBeTruthy();
+
+  const importResult = await applyEditorOps(page, [
+    {
+      type: 'level.importClassicLvl',
+      args: {
+        bytesBase64: resource.data,
+        resetHistory: true,
+        sourceLabel: 'Import LVL'
+      }
+    }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+
+  expect(importResult.ok).toBe(true);
+  const entries = importResult.state.history?.entries || [];
+  expect(entries[entries.length - 1]?.label).toBe('Import LVL');
+});
+
+test('Editor selection workflows support multi-select, nudge, and delete', async ({ page }) => {
+  const before = await getEditorState(page);
+  const terrainId = before.editor.assets.terrain[0]?.id;
+  expect(Number.isFinite(terrainId)).toBe(true);
+
+  const placeResult = await applyEditorOps(page, [
+    { type: 'entry.add', args: { kind: 'terrain', props: { PIECE: terrainId, X: 12, Y: 12 } } },
+    { type: 'entry.add', args: { kind: 'terrain', props: { PIECE: terrainId, X: 24, Y: 12 } } }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+
+  expect(placeResult.ok).toBe(true);
+  const terrainBefore = placeResult.state.session.level.terrains.length;
+  await applyEditorOps(page, [
+    { type: 'selection.set', args: { selection: [
+      { kind: 'terrain', index: terrainBefore - 2 },
+      { kind: 'terrain', index: terrainBefore - 1 }
+    ] } }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+
+  await page.waitForFunction(() => {
+    return window.__E2E__.getState().editor.controller.selectionEntries.length === 2;
+  });
+
+  let state = await getEditorState(page);
+  const entriesBefore = state.editor.controller.selectionEntries.map((entry) => ({
+    x: entry.entry.props.X,
+    y: entry.entry.props.Y
+  }));
+
+  await page.keyboard.press('ArrowRight');
+
+  await page.waitForFunction((beforeEntries) => {
+    const entries = window.__E2E__.getState().editor.controller.selectionEntries;
+    if (entries.length !== 2) return false;
+    return entries.every((entry, idx) => entry.entry.props.X === beforeEntries[idx].x + 1);
+  }, entriesBefore);
+
+  await page.keyboard.press('Delete');
+  await page.waitForFunction((count) => {
+    return window.__E2E__.getState().editor.session.level.terrains.length === count - 2;
+  }, terrainBefore);
+});
+
+test('Editor snap-to-grid aligns selection to grid size', async ({ page }) => {
+  const before = await getEditorState(page);
+  const terrainId = before.editor.assets.terrain[0]?.id;
+  expect(Number.isFinite(terrainId)).toBe(true);
+  const placeResult = await applyEditorOps(page, [
+    { type: 'entry.add', args: { kind: 'terrain', props: { PIECE: terrainId, X: 16, Y: 16 } } }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+
+  expect(placeResult.ok).toBe(true);
+  const placedIndex = placeResult.state.session.level.terrains.length - 1;
+  await applyEditorOps(page, [
+    { type: 'selection.set', args: { selection: [{ kind: 'terrain', index: placedIndex }] } }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+
+  await page.waitForFunction(() => {
+    return window.__E2E__.getState().editor.controller.selectionEntries.length === 1;
+  });
+
+  const selX = page.locator('#editorSelX');
+  const selY = page.locator('#editorSelY');
+  await selX.fill('3');
+  await selX.dispatchEvent('change');
+  await selY.fill('5');
+  await selY.dispatchEvent('change');
+
+  await page.waitForFunction(() => {
+    const entry = window.__E2E__.getState().editor.controller.selectionEntries[0];
+    return entry && entry.entry.props.X === 3 && entry.entry.props.Y === 5;
+  });
+
+  const grid = 8;
+  await applyEditorOps(page, [
+    { type: 'editor.setBrushSettings', args: { gridSize: grid, snapEnabled: true } }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+
+  const snappedX = Math.round(3 / grid) * grid;
+  const snappedY = Math.round(5 / grid) * grid;
+  await applyEditorOps(page, [
+    {
+      type: 'entry.update',
+      args: {
+        ref: { kind: 'terrain', index: placedIndex },
+        set: { X: snappedX, Y: snappedY }
+      }
+    }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+
+  await page.waitForFunction(({ x, y }) => {
+    const entry = window.__E2E__.getState().editor.controller.selectionEntries[0];
+    return entry && entry.entry.props.X === x && entry.entry.props.Y === y;
+  }, { x: snappedX, y: snappedY });
+});
+
+test('Editor copy/paste/duplicate and undo/redo update terrain counts', async ({ page }) => {
+  const before = await getEditorState(page);
+  const terrainId = before.editor.assets.terrain[0]?.id;
+  expect(Number.isFinite(terrainId)).toBe(true);
+  const placeResult = await applyEditorOps(page, [
+    { type: 'entry.add', args: { kind: 'terrain', props: { PIECE: terrainId, X: 16, Y: 16 } } }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+
+  expect(placeResult.ok).toBe(true);
+  const placedIndex = placeResult.state.session.level.terrains.length - 1;
+  await applyEditorOps(page, [
+    { type: 'selection.set', args: { selection: [{ kind: 'terrain', index: placedIndex }] } }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+
+  await page.waitForFunction(() => {
+    return window.__E2E__.getState().editor.controller.selectionEntries.length === 1;
+  });
+
+  let state = await getEditorState(page);
+  const terrainBefore = state.editor.session.level.terrains.length;
+
+  await page.keyboard.press('Control+KeyC');
+  await page.keyboard.press('Control+KeyV');
+
+  await page.waitForFunction((count) => {
+    return window.__E2E__.getState().editor.session.level.terrains.length === count + 1;
+  }, terrainBefore);
+
+  state = await getEditorState(page);
+  const afterPaste = state.editor.session.level.terrains.length;
+
+  await page.keyboard.press('Control+KeyD');
+  await page.waitForFunction((count) => {
+    return window.__E2E__.getState().editor.session.level.terrains.length === count + 1;
+  }, afterPaste);
+
+  state = await getEditorState(page);
+  const afterDuplicate = state.editor.session.level.terrains.length;
+
+  await page.keyboard.press('KeyZ');
+  await page.waitForFunction((count) => {
+    return window.__E2E__.getState().editor.session.level.terrains.length === count - 1;
+  }, afterDuplicate);
+
+  await page.keyboard.press('Shift+KeyZ');
+  await page.waitForFunction((count) => {
+    return window.__E2E__.getState().editor.session.level.terrains.length === count;
+  }, afterDuplicate);
+});
+
+test('Editor entry.update adjusts steel position and size', async ({ page }) => {
+  const before = await getEditorState(page);
+  const placeResult = await applyEditorOps(page, [
+    { type: 'entry.add', args: { kind: 'steel', props: { X: 40, Y: 40, WIDTH: 12, HEIGHT: 12 } } }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+
+  expect(placeResult.ok).toBe(true);
+  const steelIndex = placeResult.state.session.level.steel.length - 1;
+  const beforeEntry = placeResult.state.session.level.steel[steelIndex];
+  const updateResult = await applyEditorOps(page, [
+    {
+      type: 'entry.update',
+      args: {
+        ref: { kind: 'steel', index: steelIndex },
+        set: {
+          X: beforeEntry.props.X + 4,
+          Y: beforeEntry.props.Y + 3,
+          WIDTH: beforeEntry.props.WIDTH + 4,
+          HEIGHT: beforeEntry.props.HEIGHT + 5
+        }
+      }
+    }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+
+  expect(updateResult.ok).toBe(true);
+  const updated = updateResult.state.session.level.steel[steelIndex];
+  expect(updated.props.X).toBe(beforeEntry.props.X + 4);
+  expect(updated.props.Y).toBe(beforeEntry.props.Y + 3);
+  expect(updated.props.WIDTH).toBe(beforeEntry.props.WIDTH + 4);
+  expect(updated.props.HEIGHT).toBe(beforeEntry.props.HEIGHT + 5);
+});
diff --git a/e2e/harness.editor.04-editor-entrance-and-exit-tools-enforce-classic-l.spec.js b/e2e/harness.editor.04-editor-entrance-and-exit-tools-enforce-classic-l.spec.js
new file mode 100644
index 00000000..dd290313
--- /dev/null
+++ b/e2e/harness.editor.04-editor-entrance-and-exit-tools-enforce-classic-l.spec.js
@@ -0,0 +1,377 @@
+import { expect, test } from '@playwright/test';
+import { installExternalAssetStubs } from './helpers/externalAssets.js';
+
+const waitForEditorHarness = async (page) => {
+  await page.waitForFunction(() => {
+    const api = window.__E2E__;
+    if (!api?.getState) return false;
+    const state = api.getState();
+    return Boolean(
+      state.editor?.session?.level?.header
+      && state.editor?.assets?.terrain?.length
+    );
+  });
+};
+
+const getEditorState = (page) => page.evaluate(() => window.__E2E__.getState());
+const applyEditorOps = (page, ops, options = {}) => page.evaluate(
+  ({ ops, options }) => window.__E2E__.editorApply(ops, options),
+  { ops, options }
+);
+
+const getCanvasBox = async (page) => {
+  const canvas = page.locator('#editorCanvas');
+  await expect(canvas).toBeVisible();
+  const box = await canvas.boundingBox();
+  if (!box) {
+    throw new Error('Editor canvas is not visible.');
+  }
+  return box;
+};
+
+const clickCanvas = async (page, xRatio, yRatio) => {
+  const box = await getCanvasBox(page);
+  await page.mouse.click(
+    box.x + box.width * xRatio,
+    box.y + box.height * yRatio
+  );
+};
+
+const getCanvasPoint = async (page, xRatio, yRatio) => {
+  const box = await getCanvasBox(page);
+  return {
+    x: box.x + box.width * xRatio,
+    y: box.y + box.height * yRatio
+  };
+};
+
+const getWorldPointFromPage = async (page, point) => {
+  return page.evaluate(({ x, y }) => {
+    return window.__E2E__?.stageWorldFromPage?.({ x, y }) || null;
+  }, { x: point.x, y: point.y });
+};
+
+const snapWorldValue = (value, gridSize, snapEnabled) => {
+  if (!snapEnabled || !Number.isFinite(gridSize) || gridSize <= 1) {
+    return Math.round(value);
+  }
+  return Math.round(value / gridSize) * gridSize;
+};
+
+const getWorldPointFromRatio = (state, xRatio, yRatio) => {
+  const viewRect = state?.stage?.viewRect;
+  if (!viewRect) {
+    throw new Error('Missing viewRect for world coordinate lookup.');
+  }
+  return {
+    x: viewRect.x + viewRect.w * xRatio,
+    y: viewRect.y + viewRect.h * yRatio
+  };
+};
+
+const dragCanvas = async (page, start, end) => {
+  const box = await getCanvasBox(page);
+  const startX = box.x + box.width * start.x;
+  const startY = box.y + box.height * start.y;
+  const endX = box.x + box.width * end.x;
+  const endY = box.y + box.height * end.y;
+  await page.mouse.move(startX, startY);
+  await page.mouse.down();
+  await page.mouse.move(endX, endY);
+  await page.mouse.up();
+};
+
+const worldToPage = (state, canvasBox, point) => {
+  const viewRect = state?.stage?.viewRect;
+  const gamePos = state?.stage?.gamePosition;
+  const scale = state?.stage?.gameScale ?? 1;
+  if (!viewRect || !gamePos || !Number.isFinite(scale)) {
+    throw new Error('Missing stage transform data for editor canvas.');
+  }
+  const canvasX = gamePos.x + (point.x - viewRect.x) * scale;
+  const canvasY = gamePos.y + (point.y - viewRect.y) * scale;
+  return {
+    x: canvasBox.x + canvasX,
+    y: canvasBox.y + canvasY
+  };
+};
+
+const getPagePointFromWorld = async (page, point) => {
+  return page.evaluate((worldPoint) => {
+    return window.__E2E__?.stagePageFromWorld?.(worldPoint) || null;
+  }, point);
+};
+
+const centerViewportOn = async (page, point) => {
+  await page.evaluate((targetPoint) => {
+    window.__E2E__?.centerStageOn?.(targetPoint);
+  }, point);
+};
+
+const selectPaletteItem = async (page, containerSelector, id) => {
+  const button = page.locator(`${containerSelector} button[data-id="${id}"]`);
+  await button.scrollIntoViewIfNeeded();
+  await button.click();
+};
+
+const captureSelectionScreenshot = async (page, name) => {
+  const canvas = page.locator('#editorCanvas');
+  await expect(canvas).toBeVisible();
+  const path = test.info().outputPath(name);
+  await canvas.screenshot({ path });
+  await test.info().attach(name, { path, contentType: 'image/png' });
+};
+
+const placeSelectAndSnapshot = async (page, options) => {
+  const {
+    tool,
+    paletteContainer,
+    id,
+    clickRatio,
+    snapshotName
+  } = options;
+  const before = await getEditorState(page);
+  const worldClick = getWorldPointFromRatio(before, clickRatio.x, clickRatio.y);
+  await centerViewportOn(page, worldClick);
+  const centered = await getEditorState(page);
+  const canvasBox = await getCanvasBox(page);
+  const pagePoint = worldToPage(centered, canvasBox, worldClick);
+
+  await page.click(`#editorToolList button[data-tool="${tool}"]`);
+  await selectPaletteItem(page, paletteContainer, id);
+  await page.mouse.click(pagePoint.x, pagePoint.y);
+
+  await page.evaluate(() => {
+    window.__E2E__?.pause?.();
+  });
+  await page.click('#editorToolList button[data-tool="select"]');
+  await page.mouse.click(pagePoint.x, pagePoint.y);
+  await captureSelectionScreenshot(page, snapshotName);
+  await page.keyboard.press('Control+Z');
+};
+
+const coerceNumber = (value, fallback = 0) => (
+  Number.isFinite(value) ? value : fallback
+);
+
+const getEntryCenter = (entry, meta) => {
+  const props = entry?.props || {};
+  const width = Number.isFinite(props.WIDTH)
+    ? props.WIDTH
+    : Number.isFinite(meta?.width)
+      ? meta.width
+      : 1;
+  const height = Number.isFinite(props.HEIGHT)
+    ? props.HEIGHT
+    : Number.isFinite(meta?.height)
+      ? meta.height
+      : 1;
+  const centerX = coerceNumber(props.X, 0) + Math.floor(Math.max(1, width) / 2);
+  const centerY = coerceNumber(props.Y, 0) + Math.floor(Math.max(1, height) / 2);
+  return { x: centerX, y: centerY };
+};
+
+const parseLevelName = (label) => {
+  const text = String(label || '');
+  const idx = text.indexOf(':');
+  const raw = idx === -1 ? text : text.slice(idx + 1);
+  return raw.replace(/\0/g, '').trim();
+};
+
+test.beforeEach(async ({ page }) => {
+  await installExternalAssetStubs(page);
+  await page.addInitScript(() => {
+    try {
+      window.localStorage?.clear?.();
+    } catch (error) {}
+    window.prompt = () => 'E2E Save';
+    window.alert = () => {};
+    if ('serviceWorker' in navigator) {
+      const noopRegister = async () => ({ unregister: async () => true });
+      navigator.serviceWorker.register = noopRegister;
+      navigator.serviceWorker.getRegistrations = async () => [];
+    }
+  });
+  await page.goto(`/editor.html?e2e=1&cacheBust=${Date.now()}`);
+  await waitForEditorHarness(page);
+});
+
+test('Editor entrance and exit tools enforce classic limits', async ({ page }) => {
+  let state = await getEditorState(page);
+  const entranceId = state.editor.assets.entranceId;
+  const exitId = state.editor.assets.exitId;
+  expect(Number.isFinite(entranceId)).toBe(true);
+  expect(Number.isFinite(exitId)).toBe(true);
+
+  await page.click('#editorToolList button[data-tool="entrance"]');
+  for (let i = 0; i < 5; i += 1) {
+    await clickCanvas(page, 0.18 + i * 0.04, 0.3);
+  }
+
+  state = await getEditorState(page);
+  const entranceCount = state.editor.session.level.gadgets
+    .filter(entry => entry?.props?.PIECE === entranceId).length;
+  expect(entranceCount).toBeLessThanOrEqual(4);
+
+  await page.click('#editorToolList button[data-tool="exit"]');
+  for (let i = 0; i < 5; i += 1) {
+    await clickCanvas(page, 0.18 + i * 0.04, 0.6);
+  }
+
+  state = await getEditorState(page);
+  const exitCount = state.editor.session.level.gadgets
+    .filter(entry => entry?.props?.PIECE === exitId).length;
+  expect(exitCount).toBeLessThanOrEqual(4);
+});
+
+test('Editor entry.update writes gadget width and height props', async ({ page }) => {
+  const before = await getEditorState(page);
+  const gadgetId = before.editor.assets.gadgets[0]?.id;
+  expect(Number.isFinite(gadgetId)).toBe(true);
+  const placeResult = await applyEditorOps(page, [
+    { type: 'entry.add', args: { kind: 'gadget', props: { PIECE: gadgetId, X: 32, Y: 32 } } }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+
+  expect(placeResult.ok).toBe(true);
+  const gadgetIndex = placeResult.state.session.level.gadgets.length - 1;
+  const beforeEntry = placeResult.state.session.level.gadgets[gadgetIndex];
+  const updateResult = await applyEditorOps(page, [
+    {
+      type: 'entry.update',
+      args: {
+        ref: { kind: 'gadget', index: gadgetIndex },
+        set: {
+          WIDTH: (beforeEntry.props.WIDTH || 8) + 6,
+          HEIGHT: (beforeEntry.props.HEIGHT || 8) + 4
+        }
+      }
+    }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+
+  expect(updateResult.ok).toBe(true);
+  const updated = updateResult.state.session.level.gadgets[gadgetIndex];
+  expect(updated.props.WIDTH).toBeGreaterThan(0);
+  expect(updated.props.HEIGHT).toBeGreaterThan(0);
+});
+
+test('Editor view stays stable during edit actions', async ({ page }) => {
+  let state = await getEditorState(page);
+  const initialRect = state.stage.viewRect;
+  expect(initialRect).toBeTruthy();
+  const terrainId = state.editor.assets.terrain[0]?.id;
+  expect(Number.isFinite(terrainId)).toBe(true);
+  const clickPoint = getWorldPointFromRatio(state, 0.3, 0.35);
+  const placeResult = await applyEditorOps(page, [
+    { type: 'tool.place', args: { tool: 'terrain', pieceId: terrainId, x: clickPoint.x, y: clickPoint.y } }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+
+  expect(placeResult.ok).toBe(true);
+  const placedIndex = placeResult.state.session.level.terrains.length - 1;
+  await applyEditorOps(page, [
+    { type: 'selection.set', args: { selection: [{ kind: 'terrain', index: placedIndex }] } }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+  await page.keyboard.press('ArrowRight');
+
+  state = await getEditorState(page);
+  const nextRect = state.stage.viewRect;
+  expect(nextRect).toEqual(initialRect);
+});
+
+test('Editor apply API supports entry edits and exports', async ({ page }) => {
+  const result = await page.evaluate(() => {
+    const state = window.__E2E__.getState();
+    const terrainId = state.editor.assets.terrain[0]?.id ?? 0;
+    return window.__E2E__.editorApply([
+      { type: 'level.new', args: { header: { TITLE: 'E2E Apply', STYLE: 'dirt' } } },
+      { type: 'entry.add', args: { kind: 'terrain', props: { PIECE: terrainId, X: 64, Y: 64 } } },
+      { type: 'level.export', args: { format: 'nxlv', filename: 'apply-test.nxlv' } }
+    ], { preview: { refresh: false }, returnState: 'editor' });
+  });
+
+  expect(result.ok).toBe(true);
+  expect(Array.isArray(result.results)).toBe(true);
+  expect(result.resources?.length || 0).toBeGreaterThan(0);
+  expect(result.state?.session?.level?.terrains?.length || 0).toBeGreaterThan(0);
+  const entry = result.state?.session?.level?.terrains?.[0];
+  expect(entry?.uid).toBeTruthy();
+});
+
+test('Editor MIDI flag triggers survive playtest seek and reverse replay', async ({ page }) => {
+  const editorState = await getEditorState(page);
+  const gadgetId = editorState.editor.assets.gadgets[0]?.id;
+  expect(Number.isFinite(gadgetId)).toBe(true);
+
+  const setup = await applyEditorOps(page, [
+    { type: 'level.new', args: { header: { TITLE: 'MIDI Flag Replay', STYLE: 'dirt' } } },
+    {
+      type: 'entry.add',
+      args: {
+        kind: 'gadget',
+        insert: { index: 0 },
+        props: { PIECE: gadgetId, X: 96, Y: 80 }
+      }
+    },
+    {
+      type: 'entry.update',
+      args: {
+        ref: { kind: 'gadget', index: 0 },
+        set: {
+          MIDI_FLAG: true,
+          MIDI_FLAG_ID: 2,
+          MIDI_FLAG_COOLDOWN: 3
+        }
+      }
+    }
+  ], {
+    history: { record: false },
+    preview: { refresh: true, preserveViewport: true },
+    validate: { run: false },
+    returnState: 'full'
+  });
+  expect(setup.ok).toBe(true);
+
+  await page.evaluate(() => window.__E2E__.setEditorPlaytest(true));
+  await page.evaluate(() => window.__E2E__.pause());
+  await page.waitForFunction(() => {
+    const triggers = window.__E2E__.getState().game?.triggers?.entries || [];
+    return triggers.some(trigger => trigger.ownerKind === 'midi_flag' && trigger.ownerData?.midiFlagId === 2);
+  });
+
+  const baseline = await page.evaluate(() => {
+    const state = window.__E2E__.getState();
+    const trigger = state.game.triggers.entries.find(entry =>
+      entry.ownerKind === 'midi_flag' && entry.ownerData?.midiFlagId === 2
+    );
+    return {
+      tick: state.game.timer.tickIndex,
+      trigger
+    };
+  });
+  expect(baseline.trigger?.ownerId).toContain('midi_flag_2');
+  expect(baseline.trigger?.ownerData?.triggerType).toBeGreaterThan(1000);
+
+  await page.evaluate(() => window.__E2E__.step(8));
+  await page.evaluate((tick) => window.__E2E__.seek(tick), baseline.tick);
+  const restored = await page.evaluate(() => {
+    const state = window.__E2E__.getState();
+    return state.game.triggers.entries.find(entry =>
+      entry.ownerKind === 'midi_flag' && entry.ownerData?.midiFlagId === 2
+    );
+  });
+  expect(restored).toEqual(baseline.trigger);
+
+  await page.evaluate(() => window.__E2E__.step(10));
+  const tickBeforeReverse = await page.evaluate(() => window.__E2E__.getState().game.timer.tickIndex);
+  await page.evaluate(() => window.__E2E__.startReverse());
+  await page.waitForFunction((startTick) => {
+    return window.__E2E__.getState().game.timer.tickIndex < startTick;
+  }, tickBeforeReverse);
+  await page.evaluate(() => window.__E2E__.stopReverse());
+  const afterReverse = await page.evaluate(() => {
+    const state = window.__E2E__.getState();
+    return state.game.triggers.entries.find(entry =>
+      entry.ownerKind === 'midi_flag' && entry.ownerData?.midiFlagId === 2
+    );
+  });
+  expect(afterReverse?.ownerData).toEqual(baseline.trigger.ownerData);
+});
diff --git a/e2e/harness.editor.05-editor-roundtrip-workflow.spec.js b/e2e/harness.editor.05-editor-roundtrip-workflow.spec.js
new file mode 100644
index 00000000..f701c76a
--- /dev/null
+++ b/e2e/harness.editor.05-editor-roundtrip-workflow.spec.js
@@ -0,0 +1,142 @@
+import { expect, test } from '@playwright/test';
+import { installExternalAssetStubs } from './helpers/externalAssets.js';
+
+const waitForEditorHarness = async (page) => {
+  await page.waitForFunction(() => {
+    const api = window.__E2E__;
+    if (!api?.getState) return false;
+    const state = api.getState();
+    return Boolean(
+      state.editor?.session?.level?.header
+      && state.editor?.assets?.terrain?.length
+    );
+  });
+};
+
+const getEditorState = (page) => page.evaluate(() => window.__E2E__.getState());
+const applyEditorOps = (page, ops, options = {}) => page.evaluate(
+  ({ ops, options }) => window.__E2E__.editorApply(ops, options),
+  { ops, options }
+);
+
+const sortByJson = (items) => [...items].sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+const propNumber = (value) => {
+  if (Number.isFinite(value)) return value;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+};
+const propBoolean = (value) => (
+  value === true || value === 1 || value === 'true' || value === '1'
+);
+
+const semanticSummary = (level) => ({
+  header: {
+    TITLE: level.header?.TITLE || '',
+    STYLE: level.header?.STYLE || '',
+    LEMMINGS: propNumber(level.header?.LEMMINGS),
+    SAVE_REQUIREMENT: propNumber(level.header?.SAVE_REQUIREMENT),
+    WIDTH: propNumber(level.header?.WIDTH),
+    HEIGHT: propNumber(level.header?.HEIGHT)
+  },
+  terrains: sortByJson((level.terrains || []).map(entry => ({
+    PIECE: propNumber(entry.props?.PIECE),
+    X: propNumber(entry.props?.X),
+    Y: propNumber(entry.props?.Y),
+    ONE_WAY: propBoolean(entry.props?.ONE_WAY)
+  }))),
+  gadgets: sortByJson((level.gadgets || []).map(entry => ({
+    PIECE: propNumber(entry.props?.PIECE),
+    X: propNumber(entry.props?.X),
+    Y: propNumber(entry.props?.Y),
+    MIDI_FLAG: propBoolean(entry.props?.MIDI_FLAG),
+    MIDI_FLAG_ID: propNumber(entry.props?.MIDI_FLAG_ID),
+    MIDI_FLAG_COOLDOWN: propNumber(entry.props?.MIDI_FLAG_COOLDOWN)
+  }))),
+  steel: sortByJson((level.steel || []).map(entry => ({
+    X: propNumber(entry.props?.X),
+    Y: propNumber(entry.props?.Y),
+    WIDTH: propNumber(entry.props?.WIDTH),
+    HEIGHT: propNumber(entry.props?.HEIGHT)
+  })))
+});
+
+test.beforeEach(async ({ page }) => {
+  await installExternalAssetStubs(page);
+  await page.addInitScript(() => {
+    try {
+      window.localStorage?.clear?.();
+    } catch (error) {}
+    window.prompt = () => 'E2E Save';
+    window.alert = () => {};
+  });
+  await page.goto(`/editor.html?e2e=1&cacheBust=${Date.now()}`);
+  await waitForEditorHarness(page);
+});
+
+test('Editor blank level round-trips semantic state through NXLV', async ({ page }) => {
+  const initial = await getEditorState(page);
+  const terrainId = initial.editor.assets.terrain[0]?.id;
+  const triggerId = initial.editor.assets.triggers[0]?.id;
+  const entranceId = initial.editor.assets.entranceId;
+  const exitId = initial.editor.assets.exitId;
+  expect(Number.isFinite(terrainId)).toBe(true);
+  expect(Number.isFinite(triggerId)).toBe(true);
+  expect(Number.isFinite(entranceId)).toBe(true);
+  expect(Number.isFinite(exitId)).toBe(true);
+
+  const created = await applyEditorOps(page, [
+    {
+      type: 'level.new',
+      args: {
+        header: {
+          TITLE: 'E2E Round Trip',
+          STYLE: 'dirt',
+          WIDTH: 640,
+          HEIGHT: 160,
+          LEMMINGS: 10,
+          SAVE_REQUIREMENT: 5
+        },
+        resetHistory: true
+      }
+    }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+  expect(created.ok).toBe(true);
+  const baseGadgetCount = created.state.session.level.gadgets.length;
+
+  const edited = await applyEditorOps(page, [
+    { type: 'entry.add', args: { kind: 'terrain', props: { PIECE: terrainId, X: 64, Y: 96 } } },
+    { type: 'entry.update', args: { ref: { kind: 'terrain', index: 0 }, set: { ONE_WAY: true } } },
+    { type: 'entry.add', args: { kind: 'steel', props: { X: 80, Y: 120, WIDTH: 24, HEIGHT: 12 } } },
+    { type: 'entry.add', args: { kind: 'gadget', props: { PIECE: entranceId, X: 32, Y: 88 } } },
+    { type: 'entry.add', args: { kind: 'gadget', props: { PIECE: exitId, X: 560, Y: 88 } } },
+    { type: 'entry.add', args: { kind: 'gadget', props: { PIECE: triggerId, X: 192, Y: 96 } } },
+    { type: 'entry.add', args: { kind: 'gadget', props: { PIECE: triggerId, X: 256, Y: 96 } } },
+    {
+      type: 'entry.update',
+      args: {
+        ref: { kind: 'gadget', index: baseGadgetCount + 3 },
+        set: { MIDI_FLAG: true, MIDI_FLAG_ID: 3, MIDI_FLAG_COOLDOWN: 7 }
+      }
+    },
+    { type: 'level.export', args: { format: 'nxlv', filename: 'roundtrip.nxlv' } }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+
+  expect(edited.ok).toBe(true);
+  expect(edited.state.validation.hasErrors).toBe(false);
+  const before = semanticSummary(edited.state.session.level);
+  const exported = edited.resources.find(resource => resource.meta?.format === 'nxlv');
+  expect(exported?.data).toContain('E2E Round Trip');
+  expect(exported?.data).toContain('ONE_WAY true');
+  expect(exported?.data).toContain('MIDI_FLAG true');
+
+  const imported = await applyEditorOps(page, [
+    {
+      type: 'level.loadText',
+      args: { text: exported.data, resetHistory: true, sourceLabel: 'Roundtrip Import' }
+    }
+  ], { preview: { refresh: false }, returnState: 'editor' });
+
+  expect(imported.ok).toBe(true);
+  expect(imported.state.validation.hasErrors).toBe(false);
+  expect(semanticSummary(imported.state.session.level)).toEqual(before);
+});
diff --git a/e2e/harness.editor.06-editor-playtest-runtime-workflow.spec.js b/e2e/harness.editor.06-editor-playtest-runtime-workflow.spec.js
new file mode 100644
index 00000000..1fb82722
--- /dev/null
+++ b/e2e/harness.editor.06-editor-playtest-runtime-workflow.spec.js
@@ -0,0 +1,138 @@
+import { expect, test } from '@playwright/test';
+import { installExternalAssetStubs } from './helpers/externalAssets.js';
+
+const waitForEditorHarness = async (page) => {
+  await page.waitForFunction(() => {
+    const api = window.__E2E__;
+    if (!api?.getState) return false;
+    const state = api.getState();
+    return Boolean(
+      state.editor?.session?.level?.header
+      && state.editor?.assets?.terrain?.length
+      && state.editor?.assets?.gadgets?.length
+    );
+  });
+};
+
+const getEditorState = (page) => page.evaluate(() => window.__E2E__.getState());
+const applyEditorOps = (page, ops, options = {}) => page.evaluate(
+  ({ ops, options }) => window.__E2E__.editorApply(ops, options),
+  { ops, options }
+);
+
+test.beforeEach(async ({ page }) => {
+  await installExternalAssetStubs(page);
+  await page.addInitScript(() => {
+    try {
+      window.localStorage?.clear?.();
+    } catch (error) {}
+    window.prompt = () => 'E2E Save';
+    window.alert = () => {};
+  });
+  await page.goto(`/editor.html?e2e=1&cacheBust=${Date.now()}`);
+  await waitForEditorHarness(page);
+});
+
+test('Edited level lowers into playtest runtime and returns to editing', async ({ page }) => {
+  const initial = await getEditorState(page);
+  const terrainId = initial.editor.assets.terrain[0]?.id;
+  const gadgetId = initial.editor.assets.gadgets[0]?.id;
+  const entranceId = initial.editor.assets.entranceId;
+  const exitId = initial.editor.assets.exitId;
+  expect(Number.isFinite(terrainId)).toBe(true);
+  expect(Number.isFinite(gadgetId)).toBe(true);
+  expect(Number.isFinite(entranceId)).toBe(true);
+  expect(Number.isFinite(exitId)).toBe(true);
+
+  const edited = await applyEditorOps(page, [
+    {
+      type: 'level.new',
+      args: {
+        header: {
+          TITLE: 'Playtest Runtime Edit Slice',
+          STYLE: 'dirt',
+          WIDTH: 640,
+          HEIGHT: 320,
+          LEMMINGS: 10,
+          SAVE_REQUIREMENT: 5,
+          START_X: 0,
+          START_Y: 0
+        },
+        resetHistory: true
+      }
+    },
+    { type: 'entry.add', args: { kind: 'terrain', props: { PIECE: terrainId, X: 80, Y: 180 } } },
+    { type: 'entry.add', args: { kind: 'steel', props: { X: 96, Y: 192, WIDTH: 32, HEIGHT: 16 } } },
+    { type: 'entry.add', args: { kind: 'gadget', props: { PIECE: entranceId, X: 64, Y: 128 } } },
+    { type: 'entry.add', args: { kind: 'gadget', props: { PIECE: exitId, X: 480, Y: 128 } } },
+    { type: 'entry.add', args: { kind: 'gadget', props: { PIECE: gadgetId, X: 192, Y: 96 } } },
+    {
+      type: 'entry.update',
+      args: {
+        ref: { kind: 'gadget', index: 2 },
+        set: {
+          MIDI_FLAG: true,
+          MIDI_FLAG_ID: 4,
+          MIDI_FLAG_COOLDOWN: 2
+        }
+      }
+    }
+  ], {
+    history: { record: false },
+    preview: { refresh: true, preserveViewport: true },
+    validate: { run: true },
+    returnState: 'full'
+  });
+  expect(edited.ok).toBe(true);
+  expect(edited.state.editor.validation.hasErrors).toBe(false);
+
+  await page.evaluate(() => window.__E2E__.setEditorPlaytest(true));
+  await page.waitForFunction(() => {
+    const state = window.__E2E__.getState();
+    return state.editor?.playtest === true
+      && state.game?.timer?.running === true
+      && state.game?.level?.name === 'Playtest Runtime Edit Slice';
+  });
+  await page.evaluate(() => window.__E2E__.pause());
+  await page.waitForFunction(() => {
+    const triggers = window.__E2E__.getState().game?.triggers?.entries || [];
+    return triggers.some(trigger =>
+      trigger.ownerKind === 'midi_flag'
+      && trigger.ownerData?.midiFlagId === 4
+    );
+  });
+
+  const runtime = await getEditorState(page);
+  expect(runtime.game.level.entrances.length).toBeGreaterThan(0);
+  expect(runtime.game.objects.entries.some(object => object.x === 192 && object.y === 96)).toBe(true);
+  expect(runtime.game.steel.entries).toContainEqual({
+    x: 96,
+    y: 192,
+    width: 32,
+    height: 16
+  });
+  expect(runtime.game.triggers.entries.some(trigger =>
+    trigger.ownerKind === 'midi_flag'
+    && trigger.ownerData?.midiFlagId === 4
+  )).toBe(true);
+
+  await page.evaluate(() => window.__E2E__.setEditorPlaytest(false));
+  await page.waitForFunction(() => {
+    const state = window.__E2E__.getState();
+    return state.editor?.playtest === false && state.game?.timer?.running === false;
+  });
+
+  const exported = await applyEditorOps(page, [
+    { type: 'entry.add', args: { kind: 'terrain', props: { PIECE: terrainId, X: 128, Y: 184 } } },
+    { type: 'level.export', args: { format: 'nxlv', filename: 'playtest-runtime-edit-slice.nxlv' } }
+  ], {
+    preview: { refresh: true, preserveViewport: true },
+    returnState: 'full'
+  });
+
+  const resource = exported.resources.find(item => item.meta?.format === 'nxlv');
+  expect(exported.ok).toBe(true);
+  expect(exported.state.editor.playtest).toBe(false);
+  expect(exported.state.editor.session.level.terrains.length).toBe(2);
+  expect(resource?.data).toContain('Playtest Runtime Edit Slice');
+});
diff --git a/e2e/harness.editor.spec.js b/e2e/harness.editor.spec.js
deleted file mode 100644
index 0d425461..00000000
--- a/e2e/harness.editor.spec.js
+++ /dev/null
@@ -1,1017 +0,0 @@
-import { expect, test } from '@playwright/test';
-import { installExternalAssetStubs } from './helpers/externalAssets.js';
-
-const waitForEditorHarness = async (page) => {
-  await page.waitForFunction(() => {
-    const api = window.__E2E__;
-    if (!api?.getState) return false;
-    const state = api.getState();
-    return Boolean(
-      state.editor?.session?.level?.header
-      && state.editor?.assets?.terrain?.length
-    );
-  });
-};
-
-const getEditorState = (page) => page.evaluate(() => window.__E2E__.getState());
-const applyEditorOps = (page, ops, options = {}) => page.evaluate(
-  ({ ops, options }) => window.__E2E__.editorApply(ops, options),
-  { ops, options }
-);
-
-const getCanvasBox = async (page) => {
-  const canvas = page.locator('#editorCanvas');
-  await expect(canvas).toBeVisible();
-  const box = await canvas.boundingBox();
-  if (!box) {
-    throw new Error('Editor canvas is not visible.');
-  }
-  return box;
-};
-
-const clickCanvas = async (page, xRatio, yRatio) => {
-  const box = await getCanvasBox(page);
-  await page.mouse.click(
-    box.x + box.width * xRatio,
-    box.y + box.height * yRatio
-  );
-};
-
-const getCanvasPoint = async (page, xRatio, yRatio) => {
-  const box = await getCanvasBox(page);
-  return {
-    x: box.x + box.width * xRatio,
-    y: box.y + box.height * yRatio
-  };
-};
-
-const getWorldPointFromPage = async (page, point, canvasBox) => {
-  return page.evaluate(({ x, y, canvasX, canvasY }) => {
-    const stage = window.lemmings?.stage;
-    if (!stage) return null;
-    const img = stage.gameImgProps;
-    const localX = (x - canvasX) - img.x;
-    const localY = (y - canvasY) - img.y;
-    return {
-      x: img.viewPoint.getSceneX(localX),
-      y: img.viewPoint.getSceneY(localY)
-    };
-  }, { x: point.x, y: point.y, canvasX: canvasBox.x, canvasY: canvasBox.y });
-};
-
-const snapWorldValue = (value, gridSize, snapEnabled) => {
-  if (!snapEnabled || !Number.isFinite(gridSize) || gridSize <= 1) {
-    return Math.round(value);
-  }
-  return Math.round(value / gridSize) * gridSize;
-};
-
-const getWorldPointFromRatio = (state, xRatio, yRatio) => {
-  const viewRect = state?.stage?.viewRect;
-  if (!viewRect) {
-    throw new Error('Missing viewRect for world coordinate lookup.');
-  }
-  return {
-    x: viewRect.x + viewRect.w * xRatio,
-    y: viewRect.y + viewRect.h * yRatio
-  };
-};
-
-const dragCanvas = async (page, start, end) => {
-  const box = await getCanvasBox(page);
-  const startX = box.x + box.width * start.x;
-  const startY = box.y + box.height * start.y;
-  const endX = box.x + box.width * end.x;
-  const endY = box.y + box.height * end.y;
-  await page.mouse.move(startX, startY);
-  await page.mouse.down();
-  await page.mouse.move(endX, endY);
-  await page.mouse.up();
-};
-
-const worldToPage = (state, canvasBox, point) => {
-  const viewRect = state?.stage?.viewRect;
-  const gamePos = state?.stage?.gamePosition;
-  const scale = state?.stage?.gameScale ?? 1;
-  if (!viewRect || !gamePos || !Number.isFinite(scale)) {
-    throw new Error('Missing stage transform data for editor canvas.');
-  }
-  const canvasX = gamePos.x + (point.x - viewRect.x) * scale;
-  const canvasY = gamePos.y + (point.y - viewRect.y) * scale;
-  return {
-    x: canvasBox.x + canvasX,
-    y: canvasBox.y + canvasY
-  };
-};
-
-const getPagePointFromWorld = async (page, point) => {
-  return page.evaluate(({ x, y }) => {
-    const stage = window.lemmings?.stage;
-    const canvas = stage?.stageCav;
-    const rect = canvas?.getBoundingClientRect?.();
-    const viewRect = stage?.getGameViewRect?.();
-    const scale = stage?.gameImgProps?.viewPoint?.scale ?? 1;
-    if (!rect || !viewRect) return null;
-    const localX = (stage.gameImgProps?.x ?? 0) + (x - viewRect.x) * scale;
-    const localY = (stage.gameImgProps?.y ?? 0) + (y - viewRect.y) * scale;
-    return {
-      x: rect.left + localX,
-      y: rect.top + localY
-    };
-  }, point);
-};
-
-const centerViewportOn = async (page, point) => {
-  await page.evaluate(({ x, y }) => {
-    const stage = window.lemmings?.stage;
-    if (!stage) return;
-    const viewRect = stage.getGameViewRect?.();
-    if (!viewRect) return;
-    const scale = stage.gameImgProps?.viewPoint?.scale ?? 1;
-    stage.applyViewport(
-      stage.gameImgProps,
-      x - viewRect.w / 2,
-      y - viewRect.h / 2,
-      scale
-    );
-    stage.redraw?.();
-  }, point);
-};
-
-const selectPaletteItem = async (page, containerSelector, id) => {
-  const button = page.locator(`${containerSelector} button[data-id="${id}"]`);
-  await button.scrollIntoViewIfNeeded();
-  await button.click();
-};
-
-const captureSelectionScreenshot = async (page, name) => {
-  const canvas = page.locator('#editorCanvas');
-  await expect(canvas).toBeVisible();
-  const path = test.info().outputPath(name);
-  await canvas.screenshot({ path });
-  await test.info().attach(name, { path, contentType: 'image/png' });
-};
-
-const placeSelectAndSnapshot = async (page, options) => {
-  const {
-    tool,
-    paletteContainer,
-    id,
-    clickRatio,
-    snapshotName
-  } = options;
-  const before = await getEditorState(page);
-  const worldClick = getWorldPointFromRatio(before, clickRatio.x, clickRatio.y);
-  await centerViewportOn(page, worldClick);
-  const centered = await getEditorState(page);
-  const canvasBox = await getCanvasBox(page);
-  const pagePoint = worldToPage(centered, canvasBox, worldClick);
-
-  await page.click(`#editorToolList button[data-tool="${tool}"]`);
-  await selectPaletteItem(page, paletteContainer, id);
-  await page.mouse.click(pagePoint.x, pagePoint.y);
-
-  await page.evaluate(() => {
-    window.__E2E__?.pause?.();
-  });
-  await page.click('#editorToolList button[data-tool="select"]');
-  await page.mouse.click(pagePoint.x, pagePoint.y);
-  await captureSelectionScreenshot(page, snapshotName);
-  await page.keyboard.press('Control+Z');
-};
-
-const coerceNumber = (value, fallback = 0) => (
-  Number.isFinite(value) ? value : fallback
-);
-
-const getEntryCenter = (entry, meta) => {
-  const props = entry?.props || {};
-  const width = Number.isFinite(props.WIDTH)
-    ? props.WIDTH
-    : Number.isFinite(meta?.width)
-      ? meta.width
-      : 1;
-  const height = Number.isFinite(props.HEIGHT)
-    ? props.HEIGHT
-    : Number.isFinite(meta?.height)
-      ? meta.height
-      : 1;
-  const centerX = coerceNumber(props.X, 0) + Math.floor(Math.max(1, width) / 2);
-  const centerY = coerceNumber(props.Y, 0) + Math.floor(Math.max(1, height) / 2);
-  return { x: centerX, y: centerY };
-};
-
-const parseLevelName = (label) => {
-  const text = String(label || '');
-  const idx = text.indexOf(':');
-  const raw = idx === -1 ? text : text.slice(idx + 1);
-  return raw.replace(/\0/g, '').trim();
-};
-
-test.beforeEach(async ({ page }) => {
-  await installExternalAssetStubs(page);
-  await page.addInitScript(() => {
-    try {
-      window.localStorage?.clear?.();
-    } catch (error) {}
-    window.prompt = () => 'E2E Save';
-    window.alert = () => {};
-    if ('serviceWorker' in navigator) {
-      const noopRegister = async () => ({ unregister: async () => true });
-      navigator.serviceWorker.register = noopRegister;
-      navigator.serviceWorker.getRegistrations = async () => [];
-    }
-  });
-  await page.goto(`/editor.html?e2e=1&cacheBust=${Date.now()}`);
-  await waitForEditorHarness(page);
-});
-
-test('Editor harness exposes state and history', async ({ page }) => {
-  const state = await getEditorState(page);
-  expect(state.mode).toBe('editor');
-  expect(state.editor).toBeTruthy();
-  expect(state.editor.session).toBeTruthy();
-  expect(state.editor.controller).toBeTruthy();
-  expect(state.editor.history).toBeTruthy();
-  expect(state.editor.controller.tool).toBe('select');
-  expect(state.editor.history.count).toBeGreaterThan(0);
-  expect(Array.isArray(state.editor.validation.issues)).toBe(true);
-  expect(Array.isArray(state.editor.savedLevels)).toBe(true);
-
-  const title = state.editor.session.level.header.TITLE;
-  expect(String(title || '')).not.toBe('');
-  expect(Array.isArray(state.editor.session.level.headerOrder)).toBe(true);
-  expect(state.editor.assets.terrain.length).toBeGreaterThan(0);
-
-  const entry = await page.evaluate(() => window.__E2E__.getEditorHistoryEntry(0));
-  expect(entry.text.length).toBeGreaterThan(0);
-
-  const missingEntry = await page.evaluate(() => window.__E2E__.getEditorHistoryEntry(9999));
-  expect(missingEntry).toBeNull();
-});
-
-test('Editor playtest toggles timer and input state', async ({ page }) => {
-  let state = await getEditorState(page);
-  expect(state.view.editorMode).toBe(true);
-  expect(state.editor.playtest).toBe(false);
-  expect(state.game.timer.running).toBe(false);
-  expect(state.stage.panEnabled).toBe(false);
-  const inputBefore = await page.evaluate(() => window.lemmings?.game?.inputEnabled);
-  expect(inputBefore).toBe(false);
-
-  await page.click('#editorPlaytestToggle');
-  await page.waitForFunction(() => {
-    const next = window.__E2E__.getState();
-    return next.editor.playtest === true && next.game.timer.running === true;
-  });
-  state = await getEditorState(page);
-  expect(state.stage.panEnabled).toBe(true);
-  const inputAfter = await page.evaluate(() => window.lemmings?.game?.inputEnabled);
-  expect(inputAfter).toBe(true);
-
-  await page.click('#editorPlaytestToggle');
-  await page.waitForFunction(() => {
-    const next = window.__E2E__.getState();
-    return next.editor.playtest === false && next.game.timer.running === false;
-  });
-  state = await getEditorState(page);
-  expect(state.stage.panEnabled).toBe(false);
-  const inputStopped = await page.evaluate(() => window.lemmings?.game?.inputEnabled);
-  expect(inputStopped).toBe(false);
-});
-
-test('Editor level selection loads into editor session', async ({ page }) => {  
-  const state = await getEditorState(page);
-  const levelSelect = page.locator('#editorLevelIndexSelect');
-  const optionCount = await levelSelect.locator('option').count();
-  expect(optionCount).toBeGreaterThan(1);
-
-  const currentIndex = state.view.levelIndex ?? 0;
-  const targetIndex = currentIndex === 0 ? 1 : 0;
-  const targetOption = levelSelect.locator(`option[value="${targetIndex}"]`);
-  const targetLabel = await targetOption.textContent();
-  const targetName = parseLevelName(targetLabel);
-  expect(targetName).not.toBe('');
-
-  await levelSelect.selectOption(String(targetIndex));
-  await page.waitForFunction((name) => {
-    const title = window.__E2E__.getState().editor.session.level.header.TITLE || '';
-    return title.replace(/\0/g, '').trim() === name;
-  }, targetName);
-
-  const nextState = await getEditorState(page);
-  expect(nextState.view.editorMode).toBe(true);
-  expect(nextState.view.levelIndex).toBe(targetIndex);
-  const normalizedTitle = String(nextState.editor.session.level.header.TITLE || '')
-    .replace(/\0/g, '')
-    .trim();
-  expect(normalizedTitle).toBe(targetName);
-});
-
-test('Editor new level seeds entrance and exit', async ({ page }) => {
-  await page.click('#editorNewLevel');
-  await page.waitForFunction(() => {
-    const state = window.__E2E__?.getState?.();
-    return (state?.editor?.session?.level?.gadgets?.length || 0) >= 1;
-  });
-  const state = await getEditorState(page);
-  const entranceId = state.editor.assets.entranceId;
-  const exitId = state.editor.assets.exitId;
-  const gadgets = state.editor.session.level.gadgets || [];
-  const entrance = gadgets.find(entry => entry?.props?.PIECE === entranceId);
-  const exit = gadgets.find(entry => entry?.props?.PIECE === exitId);
-  expect(entrance).toBeTruthy();
-  expect(exit).toBeTruthy();
-
-  const viewRect = state.stage.viewRect;
-  const entranceX = entrance?.props?.X ?? 0;
-  const exitX = exit?.props?.X ?? 0;
-  expect(entranceX).toBeGreaterThanOrEqual(viewRect.x);
-  expect(entranceX).toBeLessThanOrEqual(viewRect.x + viewRect.w);
-  expect(exitX).toBeGreaterThanOrEqual(viewRect.x);
-  expect(exitX).toBeLessThanOrEqual(viewRect.x + viewRect.w);
-});
-
-test('Editor tool.place uses centered terrain placement', async ({ page }) => {
-  const before = await getEditorState(page);
-  const terrainId = before.editor.assets.terrain[0]?.id;
-  expect(Number.isFinite(terrainId)).toBe(true);
-
-  const clickRatio = { x: 0.25, y: 0.35 };
-  const worldClick = getWorldPointFromRatio(before, clickRatio.x, clickRatio.y);
-
-  const result = await applyEditorOps(page, [
-    {
-      type: 'tool.place',
-      args: {
-        tool: 'terrain',
-        pieceId: terrainId,
-        x: worldClick.x,
-        y: worldClick.y
-      }
-    }
-  ], { preview: { refresh: false }, returnState: 'editor' });
-
-  expect(result.ok).toBe(true);
-  const after = result.state;
-  const terrains = after.session.level.terrains;
-  const placed = terrains[terrains.length - 1];
-  expect(placed.props.PIECE).toBe(Number(terrainId));
-  const terrainMeta = after.assets.terrain.find(item => item.id === terrainId);
-  const offsetX = terrainMeta?.width ? Math.floor(terrainMeta.width / 2) : 0;
-  const offsetY = terrainMeta?.height ? Math.floor(terrainMeta.height / 2) : 0;
-  const snappedX = snapWorldValue(worldClick.x, after.controller.gridSize, after.controller.snapEnabled);
-  const snappedY = snapWorldValue(worldClick.y, after.controller.gridSize, after.controller.snapEnabled);
-  expect(placed.props.X).toBe(snappedX - offsetX);
-  expect(placed.props.Y).toBe(snappedY - offsetY);
-});
-
-test('Editor layer order buttons reorder selection', async ({ page }) => {      
-  const state = await getEditorState(page);
-  const terrainId = state.editor.assets.terrain[0]?.id;
-  expect(Number.isFinite(terrainId)).toBe(true);
-  const result = await applyEditorOps(page, [
-    { type: 'entry.add', args: { kind: 'terrain', props: { PIECE: terrainId, X: 10, Y: 10 } } },
-    { type: 'entry.add', args: { kind: 'terrain', props: { PIECE: terrainId, X: 30, Y: 10 } } },
-    { type: 'selection.set', args: { selection: [{ kind: 'terrain', index: 0 }] } }
-  ], { preview: { refresh: false }, returnState: 'editor' });
-  expect(result.ok).toBe(true);
-
-  await page.waitForFunction(() => {
-    return window.__E2E__.getState().editor.controller.selectionEntries.length === 1;
-  });
-
-  const beforeIndex = await page.evaluate(
-    () => window.__E2E__.getState().editor.controller.selectionEntries[0].index
-  );
-  await page.click('#editorSelectionMoveForward');
-  const afterIndex = await page.evaluate(
-    () => window.__E2E__.getState().editor.controller.selectionEntries[0].index
-  );
-  expect(afterIndex).toBe(beforeIndex + 1);
-});
-
-test('Editor gadget and trigger placement use centered tool placement', async ({ page }) => {
-  let state = await getEditorState(page);
-  const gadgetId = state.editor.assets.gadgets[0]?.id;
-  expect(Number.isFinite(gadgetId)).toBe(true);
-
-  const gadgetClick = { x: 64, y: 64 };
-  let result = await applyEditorOps(page, [
-    {
-      type: 'tool.place',
-      args: {
-        tool: 'gadget',
-        pieceId: gadgetId,
-        x: gadgetClick.x,
-        y: gadgetClick.y
-      }
-    }
-  ], { preview: { refresh: false }, returnState: 'editor' });
-
-  expect(result.ok).toBe(true);
-  state = result.state;
-  let gadgets = state.session.level.gadgets;
-  let placed = gadgets[gadgets.length - 1];
-  expect(placed.props.PIECE).toBe(Number(gadgetId));
-  const gadgetMeta = state.assets.gadgets.find(item => item.id === gadgetId);
-  const offsetX = gadgetMeta?.width ? Math.floor(gadgetMeta.width / 2) : 0;
-  const offsetY = gadgetMeta?.height ? Math.floor(gadgetMeta.height / 2) : 0;
-  const snappedX = snapWorldValue(gadgetClick.x, state.controller.gridSize, state.controller.snapEnabled);
-  const snappedY = snapWorldValue(gadgetClick.y, state.controller.gridSize, state.controller.snapEnabled);
-  expect(placed.props.X).toBe(snappedX - offsetX);
-  expect(placed.props.Y).toBe(snappedY - offsetY);
-
-  const triggerId = state.assets.triggers[0]?.id;
-  expect(Number.isFinite(triggerId)).toBe(true);
-  const triggerClick = { x: 96, y: 96 };
-  result = await applyEditorOps(page, [
-    {
-      type: 'tool.place',
-      args: {
-        tool: 'trigger',
-        pieceId: triggerId,
-        x: triggerClick.x,
-        y: triggerClick.y
-      }
-    }
-  ], { preview: { refresh: false }, returnState: 'editor' });
-
-  expect(result.ok).toBe(true);
-  state = result.state;
-  gadgets = state.session.level.gadgets;
-  placed = gadgets[gadgets.length - 1];
-  expect(placed.props.PIECE).toBe(Number(triggerId));
-  const triggerMeta = state.assets.gadgets.find(item => item.id === triggerId);
-  const triggerOffsetX = triggerMeta?.width ? Math.floor(triggerMeta.width / 2) : 0;
-  const triggerOffsetY = triggerMeta?.height ? Math.floor(triggerMeta.height / 2) : 0;
-  const triggerX = snapWorldValue(triggerClick.x, state.controller.gridSize, state.controller.snapEnabled);
-  const triggerY = snapWorldValue(triggerClick.y, state.controller.gridSize, state.controller.snapEnabled);
-  expect(placed.props.X).toBe(triggerX - triggerOffsetX);
-  expect(placed.props.Y).toBe(triggerY - triggerOffsetY);
-});
-
-test('Editor pack switch refreshes palettes and placement', async ({ page }) => {
-  const state = await getEditorState(page);
-  const gameTypeSelect = page.locator('#editorGameTypeSelect');
-  const selectInfo = await page.evaluate(() => {
-    const select = document.getElementById('editorGameTypeSelect');
-    if (!select) return null;
-    const values = Array.from(select.options).map(option => option.value);
-    return { selectedIndex: select.selectedIndex, values };
-  });
-  expect(selectInfo?.values?.length).toBeGreaterThan(1);
-  const nextIndex = selectInfo.selectedIndex === 0 ? 1 : 0;
-  const nextValue = selectInfo.values[nextIndex];
-
-  await gameTypeSelect.selectOption(nextValue);
-  await page.waitForFunction((prevType) => {
-    return window.__E2E__.getState().view.gameType !== prevType;
-  }, state.view.gameType);
-
-  const nextState = await getEditorState(page);
-  expect(nextState.view.gameType).not.toBe(state.view.gameType);
-  expect(nextState.editor.assets.terrain.length).toBeGreaterThan(0);
-
-  const firstTerrain = nextState.editor.assets.terrain[0];
-  const paletteFirstId = await page.locator('#editorPaletteTerrain button').first().getAttribute('data-id');
-  expect(Number(paletteFirstId)).toBe(firstTerrain.id);
-
-  const clickPoint = getWorldPointFromRatio(nextState, 0.2, 0.3);
-  const result = await applyEditorOps(page, [
-    {
-      type: 'tool.place',
-      args: {
-        tool: 'terrain',
-        pieceId: firstTerrain.id,
-        x: clickPoint.x,
-        y: clickPoint.y
-      }
-    }
-  ], { preview: { refresh: false }, returnState: 'editor' });
-
-  expect(result.ok).toBe(true);
-  const placed = result.state.session.level.terrains.slice(-1)[0];
-  expect(placed.props.PIECE).toBe(firstTerrain.id);
-});
-
-test('Editor selection overlays render for every asset', async ({ page }) => {
-  test.slow();
-  await page.fill('#editorPaletteSearch', '');
-  await page.click('#editorPaletteTabs button[data-tab="terrain"]');
-  const terrainIds = await page.$$eval('#editorPaletteTerrain button', (buttons) => (
-    buttons.map(button => Number(button.dataset.id)).filter(Number.isFinite)
-  ));
-  const gadgetIds = await page.$$eval('#editorPaletteGadgets button', (buttons) => (
-    buttons.map(button => Number(button.dataset.id)).filter(Number.isFinite)
-  ));
-  const triggerIds = await page.$$eval('#editorPaletteTriggers button', (buttons) => (
-    buttons.map(button => Number(button.dataset.id)).filter(Number.isFinite)
-  ));
-
-  const clickRatio = { x: 0.3, y: 0.35 };
-
-  for (const id of terrainIds) {
-    await placeSelectAndSnapshot(page, {
-      tool: 'terrain',
-      paletteContainer: '#editorPaletteTerrain',
-      id,
-      clickRatio,
-      snapshotName: `editor-selection-terrain-${id}.png`
-    });
-  }
-
-  await page.click('#editorPaletteTabs button[data-tab="gadgets"]');
-  for (const id of gadgetIds) {
-    await placeSelectAndSnapshot(page, {
-      tool: 'gadget',
-      paletteContainer: '#editorPaletteGadgets',
-      id,
-      clickRatio,
-      snapshotName: `editor-selection-gadget-${id}.png`
-    });
-  }
-
-  await page.click('#editorPaletteTabs button[data-tab="triggers"]');
-  for (const id of triggerIds) {
-    await placeSelectAndSnapshot(page, {
-      tool: 'trigger',
-      paletteContainer: '#editorPaletteTriggers',
-      id,
-      clickRatio,
-      snapshotName: `editor-selection-trigger-${id}.png`
-    });
-  }
-});
-
-test('Editor placement preserves viewport when panned', async ({ page }) => {
-  let state = await getEditorState(page);
-  const scale = state.stage.gameScale || 2;
-  const viewRect = state.stage.viewRect;
-  const stage = state.stage;
-  if (!viewRect || !stage) {
-    throw new Error('Missing stage view data');
-  }
-  const targetX = Math.max(0, viewRect.x + viewRect.w * 0.6);
-  await page.evaluate(({ x, scale }) => {
-    const stage = window.lemmings?.stage;
-    if (!stage) return;
-    stage.applyViewport(stage.gameImgProps, x, 0, scale);
-    stage.redraw();
-  }, { x: targetX, scale });
-
-  await page.waitForFunction((x) => {
-    const rect = window.__E2E__.getState().stage.viewRect;
-    return rect && rect.x >= x - 1;
-  }, targetX);
-
-  state = await getEditorState(page);
-  const beforeX = state.stage.viewRect.x;
-  const beforeScale = state.stage.gameScale;
-  const canvasBox = await getCanvasBox(page);
-
-  await page.click('#editorToolList button[data-tool="gadget"]');
-  const gadgetEntry = state.editor.assets.gadgets.find(entry => entry.width > 0 || entry.height > 0);
-  if (!gadgetEntry) {
-    throw new Error('No gadget entry found');
-  }
-  await page.click(`#editorPaletteGadgets button[data-id="${gadgetEntry.id}"]`);
-
-  const placePoint = {
-    x: beforeX + Math.min(80, state.stage.viewRect.w * 0.4),
-    y: 80
-  };
-  const pagePoint = worldToPage(state, canvasBox, placePoint);
-  await page.mouse.click(pagePoint.x, pagePoint.y);
-
-  await page.waitForFunction((expected) => {
-    const next = window.__E2E__.getState().stage.viewRect;
-    return next && Math.abs(next.x - expected) < 1;
-  }, beforeX);
-
-  state = await getEditorState(page);
-  expect(Math.abs(state.stage.gameScale - beforeScale)).toBeLessThan(0.01);
-});
-
-test('Editor selection updates inspector state', async ({ page }) => {
-  const before = await getEditorState(page);
-  const terrainId = before.editor.assets.terrain[0]?.id;
-  expect(Number.isFinite(terrainId)).toBe(true);
-
-  const clickPoint = getWorldPointFromRatio(before, 0.3, 0.55);
-  const placeResult = await applyEditorOps(page, [
-    {
-      type: 'tool.place',
-      args: {
-        tool: 'terrain',
-        pieceId: terrainId,
-        x: clickPoint.x,
-        y: clickPoint.y
-      }
-    }
-  ], { preview: { refresh: false }, returnState: 'editor' });
-
-  expect(placeResult.ok).toBe(true);
-  const placedIndex = placeResult.state.session.level.terrains.length - 1;
-  await applyEditorOps(page, [
-    { type: 'selection.set', args: { selection: [{ kind: 'terrain', index: placedIndex }] } }
-  ], { preview: { refresh: false }, returnState: 'editor' });
-
-  await page.waitForFunction(() => {
-    return window.__E2E__.getState().editor.controller.selectionEntries.length === 1;
-  });
-
-  const state = await getEditorState(page);
-  const selected = state.editor.controller.selectionEntries[0];
-  expect(selected.type).toBe('terrain');
-  expect(selected.entry.props.PIECE).toBe(Number(terrainId));
-
-  await expect(page.locator('#editorSelType')).toHaveText('terrain');
-  await expect(page.locator('#editorSelName')).not.toHaveText('');
-  await expect(page.locator('#editorSelX')).toBeEnabled();
-});
-
-test('Editor brush and steel tools modify level data', async ({ page }) => {    
-  const before = await getEditorState(page);
-  const terrainBefore = before.editor.session.level.terrains.length;
-  const brushStart = getWorldPointFromRatio(before, 0.2, 0.3);
-  const brushEnd = getWorldPointFromRatio(before, 0.35, 0.4);
-  const brushResult = await applyEditorOps(page, [
-    { type: 'editor.setBrushSettings', args: { brushSize: 2 } },
-    {
-      type: 'tool.stroke',
-      args: {
-        tool: 'brush',
-        points: [brushStart, brushEnd]
-      }
-    }
-  ], { preview: { refresh: false }, returnState: 'editor' });
-
-  expect(brushResult.ok).toBe(true);
-  const terrainAfter = brushResult.state.session.level.terrains.length;
-  expect(terrainAfter).toBeGreaterThan(terrainBefore + 1);
-
-  const steelBefore = brushResult.state.session.level.steel.length;
-  const steelRect = {
-    x: Math.round(brushStart.x + 40),
-    y: Math.round(brushStart.y + 20),
-    width: 12,
-    height: 12
-  };
-  const steelResult = await applyEditorOps(page, [
-    { type: 'tool.steelRect', args: { rects: [steelRect] } }
-  ], { preview: { refresh: false }, returnState: 'editor' });
-
-  expect(steelResult.ok).toBe(true);
-  const steel = steelResult.state.session.level.steel;
-  expect(steel.length).toBeGreaterThan(steelBefore);
-  const placed = steel[steel.length - 1];
-  expect(placed.props.WIDTH).toBeGreaterThan(1);
-  expect(placed.props.HEIGHT).toBeGreaterThan(1);
-});
-
-test('Editor brush respects grid size snapping', async ({ page }) => {
-  const before = await getEditorState(page);
-  const clickPoint = getWorldPointFromRatio(before, 0.22, 0.32);
-  const result = await applyEditorOps(page, [
-    { type: 'editor.setBrushSettings', args: { gridSize: 8, snapEnabled: true, brushSize: 1 } },
-    { type: 'tool.stroke', args: { tool: 'brush', points: [clickPoint] } }
-  ], { preview: { refresh: false }, returnState: 'editor' });
-
-  expect(result.ok).toBe(true);
-  const placed = result.state.session.level.terrains[result.state.session.level.terrains.length - 1];
-  const meta = result.state.assets.terrain.find(item => item.id === placed.props.PIECE);
-  const offsetX = meta?.width ? Math.floor(meta.width / 2) : 0;
-  const offsetY = meta?.height ? Math.floor(meta.height / 2) : 0;
-  expect((placed.props.X + offsetX) % 8).toBe(0);
-  expect((placed.props.Y + offsetY) % 8).toBe(0);
-});
-
-test('Editor eraser removes terrain entries', async ({ page }) => {
-  const before = await getEditorState(page);
-  const clickPoint = getWorldPointFromRatio(before, 0.25, 0.4);
-  const placeResult = await applyEditorOps(page, [
-    {
-      type: 'tool.place',
-      args: {
-        tool: 'terrain',
-        pieceId: before.editor.assets.terrain[0]?.id,
-        x: clickPoint.x,
-        y: clickPoint.y
-      }
-    }
-  ], { preview: { refresh: false }, returnState: 'editor' });
-
-  expect(placeResult.ok).toBe(true);
-  const afterCount = placeResult.state.session.level.terrains.length;
-
-  const eraseResult = await applyEditorOps(page, [
-    { type: 'tool.erase', args: { points: [clickPoint] } }
-  ], { preview: { refresh: false }, returnState: 'editor' });
-
-  expect(eraseResult.ok).toBe(true);
-  expect(eraseResult.state.session.level.terrains.length).toBeLessThan(afterCount);
-});
-
-test('Editor exports and imports classic levels via editor.apply', async ({ page }) => {
-  const exportResult = await applyEditorOps(page, [
-    { type: 'level.export', args: { format: 'classicLvl', filename: 'e2e.lvl' } }
-  ], { preview: { refresh: false } });
-
-  expect(exportResult.ok).toBe(true);
-  const resource = exportResult.resources?.[0];
-  expect(resource?.data).toBeTruthy();
-
-  const importResult = await applyEditorOps(page, [
-    {
-      type: 'level.importClassicLvl',
-      args: {
-        bytesBase64: resource.data,
-        resetHistory: true,
-        sourceLabel: 'Import LVL'
-      }
-    }
-  ], { preview: { refresh: false }, returnState: 'editor' });
-
-  expect(importResult.ok).toBe(true);
-  const entries = importResult.state.history?.entries || [];
-  expect(entries[entries.length - 1]?.label).toBe('Import LVL');
-});
-
-test('Editor selection workflows support multi-select, nudge, and delete', async ({ page }) => {
-  const before = await getEditorState(page);
-  const terrainId = before.editor.assets.terrain[0]?.id;
-  expect(Number.isFinite(terrainId)).toBe(true);
-
-  const placeResult = await applyEditorOps(page, [
-    { type: 'entry.add', args: { kind: 'terrain', props: { PIECE: terrainId, X: 12, Y: 12 } } },
-    { type: 'entry.add', args: { kind: 'terrain', props: { PIECE: terrainId, X: 24, Y: 12 } } }
-  ], { preview: { refresh: false }, returnState: 'editor' });
-
-  expect(placeResult.ok).toBe(true);
-  const terrainBefore = placeResult.state.session.level.terrains.length;
-  await applyEditorOps(page, [
-    { type: 'selection.set', args: { selection: [
-      { kind: 'terrain', index: terrainBefore - 2 },
-      { kind: 'terrain', index: terrainBefore - 1 }
-    ] } }
-  ], { preview: { refresh: false }, returnState: 'editor' });
-
-  await page.waitForFunction(() => {
-    return window.__E2E__.getState().editor.controller.selectionEntries.length === 2;
-  });
-
-  let state = await getEditorState(page);
-  const entriesBefore = state.editor.controller.selectionEntries.map((entry) => ({
-    x: entry.entry.props.X,
-    y: entry.entry.props.Y
-  }));
-
-  await page.keyboard.press('ArrowRight');
-
-  await page.waitForFunction((beforeEntries) => {
-    const entries = window.__E2E__.getState().editor.controller.selectionEntries;
-    if (entries.length !== 2) return false;
-    return entries.every((entry, idx) => entry.entry.props.X === beforeEntries[idx].x + 1);
-  }, entriesBefore);
-
-  await page.keyboard.press('Delete');
-  await page.waitForFunction((count) => {
-    return window.__E2E__.getState().editor.session.level.terrains.length === count - 2;
-  }, terrainBefore);
-});
-
-test('Editor snap-to-grid aligns selection to grid size', async ({ page }) => {
-  const before = await getEditorState(page);
-  const terrainId = before.editor.assets.terrain[0]?.id;
-  expect(Number.isFinite(terrainId)).toBe(true);
-  const placeResult = await applyEditorOps(page, [
-    { type: 'entry.add', args: { kind: 'terrain', props: { PIECE: terrainId, X: 16, Y: 16 } } }
-  ], { preview: { refresh: false }, returnState: 'editor' });
-
-  expect(placeResult.ok).toBe(true);
-  const placedIndex = placeResult.state.session.level.terrains.length - 1;
-  await applyEditorOps(page, [
-    { type: 'selection.set', args: { selection: [{ kind: 'terrain', index: placedIndex }] } }
-  ], { preview: { refresh: false }, returnState: 'editor' });
-
-  await page.waitForFunction(() => {
-    return window.__E2E__.getState().editor.controller.selectionEntries.length === 1;
-  });
-
-  const selX = page.locator('#editorSelX');
-  const selY = page.locator('#editorSelY');
-  await selX.fill('3');
-  await selX.dispatchEvent('change');
-  await selY.fill('5');
-  await selY.dispatchEvent('change');
-
-  await page.waitForFunction(() => {
-    const entry = window.__E2E__.getState().editor.controller.selectionEntries[0];
-    return entry && entry.entry.props.X === 3 && entry.entry.props.Y === 5;
-  });
-
-  const grid = 8;
-  await applyEditorOps(page, [
-    { type: 'editor.setBrushSettings', args: { gridSize: grid, snapEnabled: true } }
-  ], { preview: { refresh: false }, returnState: 'editor' });
-
-  const snappedX = Math.round(3 / grid) * grid;
-  const snappedY = Math.round(5 / grid) * grid;
-  await applyEditorOps(page, [
-    {
-      type: 'entry.update',
-      args: {
-        ref: { kind: 'terrain', index: placedIndex },
-        set: { X: snappedX, Y: snappedY }
-      }
-    }
-  ], { preview: { refresh: false }, returnState: 'editor' });
-
-  await page.waitForFunction(({ x, y }) => {
-    const entry = window.__E2E__.getState().editor.controller.selectionEntries[0];
-    return entry && entry.entry.props.X === x && entry.entry.props.Y === y;
-  }, { x: snappedX, y: snappedY });
-});
-
-test('Editor copy/paste/duplicate and undo/redo update terrain counts', async ({ page }) => {
-  const before = await getEditorState(page);
-  const terrainId = before.editor.assets.terrain[0]?.id;
-  expect(Number.isFinite(terrainId)).toBe(true);
-  const placeResult = await applyEditorOps(page, [
-    { type: 'entry.add', args: { kind: 'terrain', props: { PIECE: terrainId, X: 16, Y: 16 } } }
-  ], { preview: { refresh: false }, returnState: 'editor' });
-
-  expect(placeResult.ok).toBe(true);
-  const placedIndex = placeResult.state.session.level.terrains.length - 1;
-  await applyEditorOps(page, [
-    { type: 'selection.set', args: { selection: [{ kind: 'terrain', index: placedIndex }] } }
-  ], { preview: { refresh: false }, returnState: 'editor' });
-
-  await page.waitForFunction(() => {
-    return window.__E2E__.getState().editor.controller.selectionEntries.length === 1;
-  });
-
-  let state = await getEditorState(page);
-  const terrainBefore = state.editor.session.level.terrains.length;
-
-  await page.keyboard.press('Control+KeyC');
-  await page.keyboard.press('Control+KeyV');
-
-  await page.waitForFunction((count) => {
-    return window.__E2E__.getState().editor.session.level.terrains.length === count + 1;
-  }, terrainBefore);
-
-  state = await getEditorState(page);
-  const afterPaste = state.editor.session.level.terrains.length;
-
-  await page.keyboard.press('Control+KeyD');
-  await page.waitForFunction((count) => {
-    return window.__E2E__.getState().editor.session.level.terrains.length === count + 1;
-  }, afterPaste);
-
-  state = await getEditorState(page);
-  const afterDuplicate = state.editor.session.level.terrains.length;
-
-  await page.keyboard.press('KeyZ');
-  await page.waitForFunction((count) => {
-    return window.__E2E__.getState().editor.session.level.terrains.length === count - 1;
-  }, afterDuplicate);
-
-  await page.keyboard.press('Shift+KeyZ');
-  await page.waitForFunction((count) => {
-    return window.__E2E__.getState().editor.session.level.terrains.length === count;
-  }, afterDuplicate);
-});
-
-test('Editor entry.update adjusts steel position and size', async ({ page }) => {
-  const before = await getEditorState(page);
-  const placeResult = await applyEditorOps(page, [
-    { type: 'entry.add', args: { kind: 'steel', props: { X: 40, Y: 40, WIDTH: 12, HEIGHT: 12 } } }
-  ], { preview: { refresh: false }, returnState: 'editor' });
-
-  expect(placeResult.ok).toBe(true);
-  const steelIndex = placeResult.state.session.level.steel.length - 1;
-  const beforeEntry = placeResult.state.session.level.steel[steelIndex];
-  const updateResult = await applyEditorOps(page, [
-    {
-      type: 'entry.update',
-      args: {
-        ref: { kind: 'steel', index: steelIndex },
-        set: {
-          X: beforeEntry.props.X + 4,
-          Y: beforeEntry.props.Y + 3,
-          WIDTH: beforeEntry.props.WIDTH + 4,
-          HEIGHT: beforeEntry.props.HEIGHT + 5
-        }
-      }
-    }
-  ], { preview: { refresh: false }, returnState: 'editor' });
-
-  expect(updateResult.ok).toBe(true);
-  const updated = updateResult.state.session.level.steel[steelIndex];
-  expect(updated.props.X).toBe(beforeEntry.props.X + 4);
-  expect(updated.props.Y).toBe(beforeEntry.props.Y + 3);
-  expect(updated.props.WIDTH).toBe(beforeEntry.props.WIDTH + 4);
-  expect(updated.props.HEIGHT).toBe(beforeEntry.props.HEIGHT + 5);
-});
-
-test('Editor entrance and exit tools enforce classic limits', async ({ page }) => {
-  let state = await getEditorState(page);
-  const entranceId = state.editor.assets.entranceId;
-  const exitId = state.editor.assets.exitId;
-  expect(Number.isFinite(entranceId)).toBe(true);
-  expect(Number.isFinite(exitId)).toBe(true);
-
-  await page.click('#editorToolList button[data-tool="entrance"]');
-  for (let i = 0; i < 5; i += 1) {
-    await clickCanvas(page, 0.18 + i * 0.04, 0.3);
-  }
-
-  state = await getEditorState(page);
-  const entranceCount = state.editor.session.level.gadgets
-    .filter(entry => entry?.props?.PIECE === entranceId).length;
-  expect(entranceCount).toBeLessThanOrEqual(4);
-
-  await page.click('#editorToolList button[data-tool="exit"]');
-  for (let i = 0; i < 5; i += 1) {
-    await clickCanvas(page, 0.18 + i * 0.04, 0.6);
-  }
-
-  state = await getEditorState(page);
-  const exitCount = state.editor.session.level.gadgets
-    .filter(entry => entry?.props?.PIECE === exitId).length;
-  expect(exitCount).toBeLessThanOrEqual(4);
-});
-
-test('Editor entry.update writes gadget width and height props', async ({ page }) => {
-  const before = await getEditorState(page);
-  const gadgetId = before.editor.assets.gadgets[0]?.id;
-  expect(Number.isFinite(gadgetId)).toBe(true);
-  const placeResult = await applyEditorOps(page, [
-    { type: 'entry.add', args: { kind: 'gadget', props: { PIECE: gadgetId, X: 32, Y: 32 } } }
-  ], { preview: { refresh: false }, returnState: 'editor' });
-
-  expect(placeResult.ok).toBe(true);
-  const gadgetIndex = placeResult.state.session.level.gadgets.length - 1;
-  const beforeEntry = placeResult.state.session.level.gadgets[gadgetIndex];
-  const updateResult = await applyEditorOps(page, [
-    {
-      type: 'entry.update',
-      args: {
-        ref: { kind: 'gadget', index: gadgetIndex },
-        set: {
-          WIDTH: (beforeEntry.props.WIDTH || 8) + 6,
-          HEIGHT: (beforeEntry.props.HEIGHT || 8) + 4
-        }
-      }
-    }
-  ], { preview: { refresh: false }, returnState: 'editor' });
-
-  expect(updateResult.ok).toBe(true);
-  const updated = updateResult.state.session.level.gadgets[gadgetIndex];
-  expect(updated.props.WIDTH).toBeGreaterThan(0);
-  expect(updated.props.HEIGHT).toBeGreaterThan(0);
-});
-
-test('Editor view stays stable during edit actions', async ({ page }) => {      
-  let state = await getEditorState(page);
-  const initialRect = state.stage.viewRect;
-  expect(initialRect).toBeTruthy();
-  const terrainId = state.editor.assets.terrain[0]?.id;
-  expect(Number.isFinite(terrainId)).toBe(true);
-  const clickPoint = getWorldPointFromRatio(state, 0.3, 0.35);
-  const placeResult = await applyEditorOps(page, [
-    { type: 'tool.place', args: { tool: 'terrain', pieceId: terrainId, x: clickPoint.x, y: clickPoint.y } }
-  ], { preview: { refresh: false }, returnState: 'editor' });
-
-  expect(placeResult.ok).toBe(true);
-  const placedIndex = placeResult.state.session.level.terrains.length - 1;
-  await applyEditorOps(page, [
-    { type: 'selection.set', args: { selection: [{ kind: 'terrain', index: placedIndex }] } }
-  ], { preview: { refresh: false }, returnState: 'editor' });
-  await page.keyboard.press('ArrowRight');
-
-  state = await getEditorState(page);
-  const nextRect = state.stage.viewRect;
-  expect(nextRect).toEqual(initialRect);
-});
-
-test('Editor apply API supports entry edits and exports', async ({ page }) => {
-  const result = await page.evaluate(() => {
-    const state = window.__E2E__.getState();
-    const terrainId = state.editor.assets.terrain[0]?.id ?? 0;
-    return window.__E2E__.editorApply([
-      { type: 'level.new', args: { header: { TITLE: 'E2E Apply', STYLE: 'dirt' } } },
-      { type: 'entry.add', args: { kind: 'terrain', props: { PIECE: terrainId, X: 64, Y: 64 } } },
-      { type: 'level.export', args: { format: 'nxlv', filename: 'apply-test.nxlv' } }
-    ], { preview: { refresh: false }, returnState: 'editor' });
-  });
-
-  expect(result.ok).toBe(true);
-  expect(Array.isArray(result.results)).toBe(true);
-  expect(result.resources?.length || 0).toBeGreaterThan(0);
-  expect(result.state?.session?.level?.terrains?.length || 0).toBeGreaterThan(0);
-  const entry = result.state?.session?.level?.terrains?.[0];
-  expect(entry?.uid).toBeTruthy();
-});
diff --git a/e2e/harness.game.spec.js b/e2e/harness.game.spec.js
index ac363ff3..5ac80062 100644
--- a/e2e/harness.game.spec.js
+++ b/e2e/harness.game.spec.js
@@ -1,13 +1,12 @@
 import { expect, test } from '@playwright/test';
 import { installExternalAssetStubs } from './helpers/externalAssets.js';
 import { decodeE2EBuffer } from './helpers/e2eState.js';
-import { clearLocalStorage, waitForHarnessReady } from './helpers/harness.js';
+import { HarnessGamePage } from './helpers/pageObjects.js';
 
 test.beforeEach(async ({ page }) => {
   await installExternalAssetStubs(page);
-  await clearLocalStorage(page);
-  await page.goto('/?e2e=1');
-  await waitForHarnessReady(page);
+  const harness = new HarnessGamePage(page);
+  await harness.goto();
 });
 
 const snapshotInvariantState = (state) => {
@@ -83,7 +82,7 @@ test('Time travel restores invariant state', async ({ page }) => {
   expect(restoredSnapshot).toEqual(baselineSnapshot);
 });
 
-test('Reverse playback toggles and rewinds ticks', async ({ page }) => {        
+test('Reverse playback toggles and rewinds ticks', async ({ page }) => {
   await page.evaluate(() => window.__E2E__.pause());
   await page.evaluate(() => window.__E2E__.step(10));
   const tickBefore = await page.evaluate(() => window.__E2E__.getState().game.timer.tickIndex);
@@ -114,7 +113,7 @@ test('Reverse playback does not change speed factor', async ({ page }) => {
   await page.evaluate(() => window.__E2E__.stopReverse());
 });
 
-test('Harness returns buffers with decodable metadata', async ({ page }) => {   
+test('Harness returns buffers with decodable metadata', async ({ page }) => {
   const groundMask = await page.evaluate(() => window.__E2E__.getBuffer('ground-mask'));
   expect(groundMask).toBeTruthy();
   const decodedMask = decodeE2EBuffer(groundMask);
@@ -149,20 +148,7 @@ test('Minimap click preserves zoom scale', async ({ page }) => {
     () => window.__E2E__?.getState?.().stage?.gameScale ?? 1
   );
 
-  const minimapPoint = await page.evaluate(() => {
-    const stage = window.lemmings?.stage;
-    const gui = stage?.guiImgProps;
-    const display = gui?.display;
-    const rect = stage?.stageCav?.getBoundingClientRect?.();
-    if (!stage || !gui || !display || !rect) return null;
-    const destX = display.worldDataSize.width - 127;
-    const destY = display.worldDataSize.height - 24 - 1;
-    const scale = gui.viewPoint?.scale ?? 1;
-    return {
-      x: rect.left + gui.x + destX * scale + 2,
-      y: rect.top + gui.y + destY * scale + 2
-    };
-  });
+  const minimapPoint = await page.evaluate(() => window.__E2E__?.getMinimapPagePoint?.() || null);
   if (!minimapPoint) throw new Error('Missing minimap position.');
   await page.mouse.click(minimapPoint.x, minimapPoint.y);
 
diff --git a/e2e/helpers/pageObjects.js b/e2e/helpers/pageObjects.js
new file mode 100644
index 00000000..fe03700f
--- /dev/null
+++ b/e2e/helpers/pageObjects.js
@@ -0,0 +1,249 @@
+import { clearLocalStorage, waitForHarnessReady } from './harness.js';
+
+const midiUiSelectors = Object.freeze({
+  enabledToggle: '#midiEnabledToggle',
+  workspace: '#midiSequencerWorkspace',
+  sourceRows: '#midiSourceList .midi-source-row',
+  sourceAssignFilter: '#midiSourceAssignFilter',
+  conflictRows: '#midiSourceList .midi-source-row.has-conflict',
+  trackRows: '#midiTrackList .midi-track-row',
+  trackRemoveButton: '#midiTrackRemove',
+  clipRows: '#midiClipList .midi-clip-row',
+  clipAddButton: '#midiClipAddButton',
+  clipDuplicateButton: '#midiClipDuplicateButton',
+  clipRemoveButton: '#midiClipRemoveButton',
+  clipInspector: '#midiClipInspector',
+  clipAuditionButton: '#midiClipAuditionButton',
+  sourceModeSelect: '#midiSourceModeSelect',
+  sourceClipSelect: '#midiSourceClipSelect',
+  conflictSummary: '#midiConflictSummary',
+  conflictBadges: '#midiSourceList .midi-conflict-badge',
+  modulationInspector: '#midiModulationInspector',
+  automationRows: '#midiAutomationList .midi-automation-row',
+  automationRemoveButtons: '#midiAutomationList .midi-automation-remove',
+  automationAddButton: '#midiAutomationAddButton',
+  automationPointBeatFields: '#midiAutomationList .midi-automation-point-beat',
+  automationPointValueFields: '#midiAutomationList .midi-automation-point-value',
+  templateSelect: '#midiTemplateSelect',
+  templateSaveButton: '#midiTemplateSaveButton',
+  projectExportButton: '#midiProjectExportButton',
+  projectImportButton: '#midiProjectImportButton',
+  learnPanel: '#midiLearnPanel',
+  learnButton: '#midiLearnButton',
+  learnConfirmButton: '#midiLearnConfirmButton',
+  learnStatus: '#midiLearnStatus',
+  recordPanel: '#midiRecordPanel',
+  recordButton: '#midiRecordButton',
+  recordCommitButton: '#midiRecordCommitButton',
+  recordStatus: '#midiRecordStatus',
+  stepCells: '#midiStepPatternGrid .midi-step-cell',
+  inspector: '#midiInspector',
+  outputLog: '#midiOutputLog'
+});
+
+class MidiUiPage {
+  constructor(page) {
+    this.page = page;
+  }
+
+  async goto(path = '/') {
+    await this.page.goto(path);
+    await this.page.waitForSelector(midiUiSelectors.enabledToggle);
+  }
+
+  enabledToggle() {
+    return this.page.locator(midiUiSelectors.enabledToggle);
+  }
+
+  async enable() {
+    await this.enabledToggle().check();
+  }
+
+  workspace() {
+    return this.page.locator(midiUiSelectors.workspace);
+  }
+
+  sourceRows() {
+    return this.page.locator(midiUiSelectors.sourceRows);
+  }
+
+  sourceAssignFilter() {
+    return this.page.locator(midiUiSelectors.sourceAssignFilter);
+  }
+
+  conflictRows() {
+    return this.page.locator(midiUiSelectors.conflictRows);
+  }
+
+  trackRows() {
+    return this.page.locator(midiUiSelectors.trackRows);
+  }
+
+  trackRemoveButton() {
+    return this.page.locator(midiUiSelectors.trackRemoveButton);
+  }
+
+  clipRows() {
+    return this.page.locator(midiUiSelectors.clipRows);
+  }
+
+  clipAddButton() {
+    return this.page.locator(midiUiSelectors.clipAddButton);
+  }
+
+  clipDuplicateButton() {
+    return this.page.locator(midiUiSelectors.clipDuplicateButton);
+  }
+
+  clipRemoveButton() {
+    return this.page.locator(midiUiSelectors.clipRemoveButton);
+  }
+
+  clipInspector() {
+    return this.page.locator(midiUiSelectors.clipInspector);
+  }
+
+  clipAuditionButton() {
+    return this.page.locator(midiUiSelectors.clipAuditionButton);
+  }
+
+  sourceModeSelect() {
+    return this.page.locator(midiUiSelectors.sourceModeSelect);
+  }
+
+  sourceClipSelect() {
+    return this.page.locator(midiUiSelectors.sourceClipSelect);
+  }
+
+  conflictSummary() {
+    return this.page.locator(midiUiSelectors.conflictSummary);
+  }
+
+  conflictBadges() {
+    return this.page.locator(midiUiSelectors.conflictBadges);
+  }
+
+  modulationInspector() {
+    return this.page.locator(midiUiSelectors.modulationInspector);
+  }
+
+  automationRows() {
+    return this.page.locator(midiUiSelectors.automationRows);
+  }
+
+  automationRemoveButtons() {
+    return this.page.locator(midiUiSelectors.automationRemoveButtons);
+  }
+
+  automationAddButton() {
+    return this.page.locator(midiUiSelectors.automationAddButton);
+  }
+
+  automationPointBeatFields() {
+    return this.page.locator(midiUiSelectors.automationPointBeatFields);
+  }
+
+  automationPointValueFields() {
+    return this.page.locator(midiUiSelectors.automationPointValueFields);
+  }
+
+  runtimeConfig() {
+    return this.page.evaluate(() => window.__E2E__.midiGetRuntimeConfig());
+  }
+
+  uiMetrics() {
+    return this.page.evaluate(() => window.__E2E__.midiGetUiMetrics());
+  }
+
+  templateSelect() {
+    return this.page.locator(midiUiSelectors.templateSelect);
+  }
+
+  templateSaveButton() {
+    return this.page.locator(midiUiSelectors.templateSaveButton);
+  }
+
+  projectExportButton() {
+    return this.page.locator(midiUiSelectors.projectExportButton);
+  }
+
+  projectImportButton() {
+    return this.page.locator(midiUiSelectors.projectImportButton);
+  }
+
+  learnPanel() {
+    return this.page.locator(midiUiSelectors.learnPanel);
+  }
+
+  learnButton() {
+    return this.page.locator(midiUiSelectors.learnButton);
+  }
+
+  learnConfirmButton() {
+    return this.page.locator(midiUiSelectors.learnConfirmButton);
+  }
+
+  learnStatus() {
+    return this.page.locator(midiUiSelectors.learnStatus);
+  }
+
+  recordPanel() {
+    return this.page.locator(midiUiSelectors.recordPanel);
+  }
+
+  recordButton() {
+    return this.page.locator(midiUiSelectors.recordButton);
+  }
+
+  recordCommitButton() {
+    return this.page.locator(midiUiSelectors.recordCommitButton);
+  }
+
+  recordStatus() {
+    return this.page.locator(midiUiSelectors.recordStatus);
+  }
+
+  stepCells() {
+    return this.page.locator(midiUiSelectors.stepCells);
+  }
+
+  inspector() {
+    return this.page.locator(midiUiSelectors.inspector);
+  }
+
+  outputLog() {
+    return this.page.locator(midiUiSelectors.outputLog);
+  }
+}
+
+class HarnessGamePage {
+  constructor(page) {
+    this.page = page;
+  }
+
+  async goto({ resetStorage = true } = {}) {
+    if (resetStorage) {
+      await clearLocalStorage(this.page);
+    }
+    await this.page.goto('/?e2e=1');
+    await waitForHarnessReady(this.page);
+  }
+
+  async invoke(method, ...args) {
+    return this.page.evaluate(([name, params]) => {
+      const api = window.__E2E__;
+      if (!api || typeof api[name] !== 'function') return null;
+      return api[name](...params);
+    }, [method, args]);
+  }
+
+  async state() {
+    return this.page.evaluate(() => window.__E2E__?.getState?.());
+  }
+}
+
+export {
+  HarnessGamePage,
+  MidiUiPage,
+  midiUiSelectors
+};
diff --git a/e2e/helpers/visualCapture.js b/e2e/helpers/visualCapture.js
new file mode 100644
index 00000000..0f492ad2
--- /dev/null
+++ b/e2e/helpers/visualCapture.js
@@ -0,0 +1,604 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const DEFAULT_CAPTURE_ROOT = path.resolve('temp', 'e2e-captures');
+const DEFAULT_IMAGE_EXTENSION = 'png';
+const DEFAULT_MIN_TAP_TARGET_SIZE = 32;
+const CAPTURE_TARGET_TYPES = Object.freeze(new Set([
+  'selector',
+  'pageRect',
+  'runtimeRect',
+  'runtimeRects',
+  'worldRect',
+  'viewport',
+  'fullPage'
+]));
+
+const sanitizeCaptureName = (name) => {
+  const cleaned = String(name || '')
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 96);
+  return cleaned || 'capture';
+};
+
+const makeCaptureTimestamp = (date = new Date()) => (
+  date.toISOString().replace(/[:.]/g, '-')
+);
+
+const isPathInside = (parent, child) => {
+  const relative = path.relative(parent, child);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+};
+
+const resolveCaptureOutputDir = async (outDir, options = {}) => {
+  const root = path.resolve(options.captureRoot || DEFAULT_CAPTURE_ROOT);
+  const resolved = path.resolve(outDir || path.join(root, makeCaptureTimestamp()));
+  if (!isPathInside(root, resolved)) {
+    throw new Error(`Capture output must stay under ${root}: ${resolved}`);
+  }
+  await fs.mkdir(resolved, { recursive: true });
+  return resolved;
+};
+
+const normalizeClipRect = (rect, viewport = null) => {
+  const x = Number(rect?.x ?? rect?.left);
+  const y = Number(rect?.y ?? rect?.top);
+  const width = Number(rect?.width);
+  const height = Number(rect?.height);
+  if (
+    !Number.isFinite(x) ||
+    !Number.isFinite(y) ||
+    !Number.isFinite(width) ||
+    !Number.isFinite(height) ||
+    width <= 0 ||
+    height <= 0
+  ) {
+    throw new Error(`Invalid clip rectangle: ${JSON.stringify(rect)}`);
+  }
+
+  if (!viewport) return { x, y, width, height };
+  const viewportWidth = Number(viewport.width);
+  const viewportHeight = Number(viewport.height);
+  if (!Number.isFinite(viewportWidth) || !Number.isFinite(viewportHeight)) {
+    return { x, y, width, height };
+  }
+  const left = Math.max(0, x);
+  const top = Math.max(0, y);
+  const right = Math.min(viewportWidth, x + width);
+  const bottom = Math.min(viewportHeight, y + height);
+  if (right <= left || bottom <= top) {
+    throw new Error(`Clip rectangle is outside the viewport: ${JSON.stringify(rect)}`);
+  }
+  return {
+    x: left,
+    y: top,
+    width: right - left,
+    height: bottom - top
+  };
+};
+
+const summarizeTarget = (target) => {
+  const parts = [
+    `target=${target?.name || '(unnamed)'}`,
+    `type=${target?.type || '(missing)'}`
+  ];
+  if (target?.selector) parts.push(`selector=${target.selector}`);
+  if (target?.id) parts.push(`id=${target.id}`);
+  return parts.join(' ');
+};
+
+const getRouteLabel = (page, options = {}) => {
+  if (options.route) return options.route;
+  try {
+    const url = page.url?.();
+    if (!url) return '(unknown route)';
+    const parsed = new URL(url);
+    return `${parsed.pathname}${parsed.search}`;
+  } catch {
+    return page.url?.() || '(unknown route)';
+  }
+};
+
+const collectNearbySelectors = async (page) => {
+  try {
+    return await page.evaluate(() => {
+      const nodes = Array.from(document.querySelectorAll('[id], [class]')).slice(0, 36);
+      return nodes.map((node) => {
+        const tag = node.tagName.toLowerCase();
+        const id = node.id ? `#${node.id}` : '';
+        const className = typeof node.className === 'string'
+          ? node.className.trim().split(/\s+/).filter(Boolean).slice(0, 3).map(item => `.${item}`).join('')
+          : '';
+        return `${tag}${id}${className}`;
+      });
+    });
+  } catch {
+    return [];
+  }
+};
+
+const createCaptureError = (message, { page, target, options = {}, availableRuntimeRectIds = [], nearby = [] }) => {
+  const lines = [
+    message,
+    `Route: ${getRouteLabel(page, options)}`,
+    `Target: ${summarizeTarget(target)}`
+  ];
+  if (availableRuntimeRectIds.length) {
+    lines.push(`Available runtime rect ids: ${availableRuntimeRectIds.join(', ')}`);
+  }
+  if (nearby.length) {
+    lines.push(`Nearby page ids/classes: ${nearby.join(', ')}`);
+  }
+  return new Error(lines.join('\n'));
+};
+
+const validateTarget = (target) => {
+  if (!target || typeof target !== 'object') {
+    throw new Error('Capture target must be an object.');
+  }
+  if (!target.name || typeof target.name !== 'string') {
+    throw new Error(`Capture target is missing a string name: ${JSON.stringify(target)}`);
+  }
+  if (!CAPTURE_TARGET_TYPES.has(target.type)) {
+    throw new Error(`Unsupported capture target type for ${target.name}: ${target.type}`);
+  }
+};
+
+const getRuntimeCaptureRects = async (page, captureOptions = null, target = null, options = {}) => {
+  const result = await page.evaluate((rectOptions) => {
+    const api = window.__E2E__;
+    if (!api || typeof api.getCaptureRects !== 'function') {
+      return { missingApi: true };
+    }
+    return api.getCaptureRects(rectOptions || undefined);
+  }, captureOptions);
+  if (result?.missingApi) {
+    throw createCaptureError('window.__E2E__.getCaptureRects() is not available.', {
+      page,
+      target,
+      options
+    });
+  }
+  if (!result || result.version !== 1 || !result.rects) {
+    throw createCaptureError('window.__E2E__.getCaptureRects() returned an invalid payload.', {
+      page,
+      target,
+      options
+    });
+  }
+  return result;
+};
+
+const buildResolvedTarget = ({ target, name, type, rect = null, clip = null, mode = 'clip', runtimeId = null }) => ({
+  name,
+  type,
+  sourceTarget: target,
+  runtimeId,
+  rect,
+  clip,
+  mode
+});
+
+const resolveSelectorTarget = async (page, target, options, viewport) => {
+  if (!target.selector || typeof target.selector !== 'string') {
+    throw createCaptureError('Selector capture target is missing a selector.', { page, target, options });
+  }
+  const locator = page.locator(target.selector);
+  const count = await locator.count();
+  if (count !== 1) {
+    const nearby = await collectNearbySelectors(page);
+    throw createCaptureError(`Expected exactly one element but found ${count}.`, {
+      page,
+      target,
+      options,
+      nearby
+    });
+  }
+  const element = locator.first();
+  await element.scrollIntoViewIfNeeded();
+  const visible = await element.isVisible();
+  if (options.requireVisibleSelectors !== false && !visible) {
+    throw createCaptureError('Selector matched one element, but it is not visible.', {
+      page,
+      target,
+      options
+    });
+  }
+  const rect = await element.boundingBox();
+  if (!rect) {
+    throw createCaptureError('Selector matched one element, but it has no bounding box.', {
+      page,
+      target,
+      options
+    });
+  }
+  const clip = normalizeClipRect(rect, options.clipToViewport === false ? null : viewport);
+  return buildResolvedTarget({
+    target,
+    name: target.name,
+    type: target.type,
+    rect,
+    clip
+  });
+};
+
+const resolveRuntimeRectTarget = async (page, target, options, viewport) => {
+  const runtime = await getRuntimeCaptureRects(page, null, target, options);
+  const available = Object.keys(runtime.rects).sort();
+  const rect = runtime.rects[target.id];
+  if (!rect) {
+    throw createCaptureError('Requested runtime rectangle is not available.', {
+      page,
+      target,
+      options,
+      availableRuntimeRectIds: available
+    });
+  }
+  const clip = normalizeClipRect(rect, options.clipToViewport === false ? null : viewport);
+  return buildResolvedTarget({
+    target,
+    name: target.name,
+    type: target.type,
+    rect,
+    clip,
+    runtimeId: target.id
+  });
+};
+
+const resolveRuntimeRectsTarget = async (page, target, options, viewport) => {
+  const runtime = await getRuntimeCaptureRects(page, null, target, options);
+  const available = Object.keys(runtime.rects).sort();
+  const requested = Array.isArray(target.ids) && target.ids.length
+    ? target.ids.map(id => String(id))
+    : available;
+  const captures = [];
+  const missing = [];
+  for (const id of requested) {
+    const rect = runtime.rects[id];
+    if (!rect) {
+      missing.push(id);
+      continue;
+    }
+    const clip = normalizeClipRect(rect, options.clipToViewport === false ? null : viewport);
+    const name = target.name === id ? id : `${target.name}-${id}`;
+    captures.push(buildResolvedTarget({
+      target,
+      name,
+      type: target.type,
+      rect,
+      clip,
+      runtimeId: id
+    }));
+  }
+  if (!captures.length) {
+    throw createCaptureError('No requested runtime rectangles are available.', {
+      page,
+      target,
+      options,
+      availableRuntimeRectIds: available
+    });
+  }
+  if (missing.length) {
+    captures[0].warnings = [`Missing runtime rect ids: ${missing.join(', ')}`];
+  }
+  return captures;
+};
+
+const resolveWorldRectTarget = async (page, target, options, viewport) => {
+  const runtime = await getRuntimeCaptureRects(page, {
+    worldRect: {
+      id: target.name,
+      rect: target.rect,
+      padding: target.padding
+    }
+  }, target, options);
+  const available = Object.keys(runtime.rects).sort();
+  const rect = runtime.rects[target.name];
+  if (!rect) {
+    throw createCaptureError('World rectangle could not be converted to a page rectangle.', {
+      page,
+      target,
+      options,
+      availableRuntimeRectIds: available
+    });
+  }
+  const clip = normalizeClipRect(rect, options.clipToViewport === false ? null : viewport);
+  return buildResolvedTarget({
+    target,
+    name: target.name,
+    type: target.type,
+    rect,
+    clip,
+    runtimeId: target.name
+  });
+};
+
+const resolveCaptureTargets = async (page, targets, options = {}) => {
+  if (!Array.isArray(targets)) {
+    throw new Error('Capture targets must be an array.');
+  }
+  const viewport = options.viewport || page.viewportSize?.() || null;
+  const resolved = [];
+  for (const target of targets) {
+    validateTarget(target);
+    switch (target.type) {
+    case 'selector':
+      resolved.push(await resolveSelectorTarget(page, target, options, viewport));
+      break;
+    case 'pageRect': {
+      const clip = normalizeClipRect(target.rect, options.clipToViewport === false ? null : viewport);
+      resolved.push(buildResolvedTarget({
+        target,
+        name: target.name,
+        type: target.type,
+        rect: target.rect,
+        clip
+      }));
+      break;
+    }
+    case 'runtimeRect':
+      resolved.push(await resolveRuntimeRectTarget(page, target, options, viewport));
+      break;
+    case 'runtimeRects':
+      resolved.push(...await resolveRuntimeRectsTarget(page, target, options, viewport));
+      break;
+    case 'worldRect':
+      resolved.push(await resolveWorldRectTarget(page, target, options, viewport));
+      break;
+    case 'viewport':
+      resolved.push(buildResolvedTarget({
+        target,
+        name: target.name,
+        type: target.type,
+        mode: 'viewport'
+      }));
+      break;
+    case 'fullPage':
+      resolved.push(buildResolvedTarget({
+        target,
+        name: target.name,
+        type: target.type,
+        mode: 'fullPage'
+      }));
+      break;
+    default:
+      throw new Error(`Unsupported capture target type: ${target.type}`);
+    }
+  }
+  return resolved;
+};
+
+const nextCapturePath = (outDir, name, usedNames, extension = DEFAULT_IMAGE_EXTENSION) => {
+  const base = sanitizeCaptureName(name);
+  let candidate = base;
+  let index = 2;
+  while (usedNames.has(candidate)) {
+    candidate = `${base}-${index}`;
+    index += 1;
+  }
+  usedNames.add(candidate);
+  return path.join(outDir, `${candidate}.${extension}`);
+};
+
+const captureTargets = async (page, targets, options = {}) => {
+  const outDir = await resolveCaptureOutputDir(options.outDir, options);
+  const resolved = await resolveCaptureTargets(page, targets, options);
+  const usedNames = new Set();
+  const captures = [];
+  for (const item of resolved) {
+    const outputPath = nextCapturePath(outDir, item.name, usedNames, options.extension);
+    if (item.mode === 'fullPage') {
+      await page.screenshot({ path: outputPath, fullPage: true });
+    } else if (item.mode === 'viewport') {
+      await page.screenshot({ path: outputPath });
+    } else {
+      await page.screenshot({ path: outputPath, clip: item.clip });
+    }
+    captures.push({
+      name: item.name,
+      type: item.type,
+      runtimeId: item.runtimeId,
+      rect: item.rect || null,
+      clip: item.clip || null,
+      path: outputPath,
+      warnings: item.warnings || []
+    });
+  }
+  return {
+    version: 1,
+    outDir,
+    captures
+  };
+};
+
+const normalizeProbe = (probe) => {
+  if (typeof probe === 'string') {
+    return { name: probe, selector: probe, required: false };
+  }
+  return {
+    name: probe?.name || probe?.selector || 'probe',
+    selector: probe?.selector,
+    required: probe?.required === true,
+    checks: Array.isArray(probe?.checks) ? probe.checks : null
+  };
+};
+
+const runVisualProbes = async (page, probes = [], options = {}) => {
+  const normalized = probes.map(normalizeProbe);
+  const issues = await page.evaluate(({ probes: browserProbes, probeOptions }) => {
+    const allChecks = new Set([
+      'missingSelector',
+      'horizontalOverflow',
+      'verticalOverflow',
+      'clippedText',
+      'zeroSizeVisibleText',
+      'hiddenFocusedElement',
+      'smallTapTarget',
+      'unexpectedScrollbar'
+    ]);
+    const minTapTargetSize = Number.isFinite(probeOptions.minTapTargetSize)
+      ? probeOptions.minTapTargetSize
+      : 32;
+    const issueList = [];
+    const describeNode = (node) => {
+      if (!node) return '(missing)';
+      const tag = node.tagName?.toLowerCase?.() || 'node';
+      const id = node.id ? `#${node.id}` : '';
+      const cls = typeof node.className === 'string' && node.className.trim()
+        ? `.${node.className.trim().split(/\s+/).slice(0, 3).join('.')}`
+        : '';
+      return `${tag}${id}${cls}`;
+    };
+    const rectFor = (node) => {
+      const rect = node.getBoundingClientRect();
+      return {
+        x: rect.x,
+        y: rect.y,
+        width: rect.width,
+        height: rect.height
+      };
+    };
+    const isRendered = (node) => {
+      if (!node || typeof node.getBoundingClientRect !== 'function') return false;
+      const style = window.getComputedStyle(node);
+      if (style.display === 'none' || style.visibility === 'hidden' || Number(style.opacity) === 0) {
+        return false;
+      }
+      const rect = node.getBoundingClientRect();
+      return rect.width > 0 && rect.height > 0;
+    };
+    const hasCheck = (probe, check) => !probe.checks || probe.checks.includes(check);
+    const pushIssue = (probe, code, message, node = null) => {
+      if (probe.checks && !allChecks.has(code)) return;
+      issueList.push({
+        probe: probe.name,
+        selector: probe.selector,
+        required: probe.required === true,
+        code,
+        message,
+        target: describeNode(node),
+        rect: node ? rectFor(node) : null
+      });
+    };
+
+    for (const probe of browserProbes) {
+      if (!probe.selector) {
+        issueList.push({
+          probe: probe.name,
+          selector: '',
+          required: probe.required === true,
+          code: 'missingSelector',
+          message: 'Probe is missing a selector.',
+          target: '(probe)',
+          rect: null
+        });
+        continue;
+      }
+      const roots = Array.from(document.querySelectorAll(probe.selector));
+      if (!roots.length) {
+        pushIssue(probe, 'missingSelector', 'Probe selector did not match any elements.');
+        continue;
+      }
+      for (const root of roots) {
+        if (hasCheck(probe, 'horizontalOverflow') && root.scrollWidth > root.clientWidth + 1) {
+          pushIssue(probe, 'horizontalOverflow', 'Element scrollWidth exceeds clientWidth.', root);
+        }
+        if (hasCheck(probe, 'verticalOverflow') && root.scrollHeight > root.clientHeight + 1) {
+          pushIssue(probe, 'verticalOverflow', 'Element scrollHeight exceeds clientHeight.', root);
+        }
+        const candidates = [root, ...Array.from(root.querySelectorAll('*'))];
+        for (const node of candidates) {
+          const text = String(node.textContent || '').trim();
+          if (!text) continue;
+          const style = window.getComputedStyle(node);
+          const rect = node.getBoundingClientRect();
+          const visibleByStyle = style.display !== 'none' &&
+            style.visibility !== 'hidden' &&
+            node.getClientRects().length > 0;
+          if (
+            hasCheck(probe, 'zeroSizeVisibleText') &&
+            visibleByStyle &&
+            (rect.width <= 0 || rect.height <= 0)
+          ) {
+            pushIssue(probe, 'zeroSizeVisibleText', 'Visible text node has zero-size layout.', node);
+          }
+          if (
+            hasCheck(probe, 'clippedText') &&
+            isRendered(node) &&
+            (node.scrollWidth > node.clientWidth + 1 || node.scrollHeight > node.clientHeight + 1)
+          ) {
+            pushIssue(probe, 'clippedText', 'Text content is clipped by its element box.', node);
+          }
+        }
+        const tapTargets = candidates.filter(node => (
+          node.matches?.('button, a[href], input, select, textarea, [role="button"], [tabindex]')
+        ));
+        for (const node of tapTargets) {
+          if (!isRendered(node)) continue;
+          const rect = node.getBoundingClientRect();
+          if (
+            hasCheck(probe, 'smallTapTarget') &&
+            (rect.width < minTapTargetSize || rect.height < minTapTargetSize)
+          ) {
+            pushIssue(probe, 'smallTapTarget', 'Interactive target is below the minimum practical size.', node);
+          }
+        }
+        const rootStyle = window.getComputedStyle(root);
+        const scrollX = /auto|scroll/.test(rootStyle.overflowX) && root.scrollWidth > root.clientWidth + 1;
+        const scrollY = /auto|scroll/.test(rootStyle.overflowY) && root.scrollHeight > root.clientHeight + 1;
+        if (hasCheck(probe, 'unexpectedScrollbar') && (scrollX || scrollY)) {
+          pushIssue(probe, 'unexpectedScrollbar', 'Element has a visible overflow scrollbar.', root);
+        }
+      }
+    }
+
+    const focused = document.activeElement;
+    if (focused && focused !== document.body && !isRendered(focused)) {
+      for (const probe of browserProbes) {
+        if (hasCheck(probe, 'hiddenFocusedElement')) {
+          pushIssue(probe, 'hiddenFocusedElement', 'Focused element is hidden or zero-size.', focused);
+        }
+      }
+    }
+    const doc = document.documentElement;
+    const body = document.body;
+    const hasPageScrollbar = (
+      doc.scrollWidth > window.innerWidth + 2 ||
+      body.scrollWidth > window.innerWidth + 2 ||
+      doc.scrollHeight > window.innerHeight + 2 ||
+      body.scrollHeight > window.innerHeight + 2
+    );
+    if (hasPageScrollbar) {
+      for (const probe of browserProbes) {
+        if (hasCheck(probe, 'unexpectedScrollbar')) {
+          pushIssue(probe, 'unexpectedScrollbar', 'Page has an unexpected document-level scrollbar.', doc);
+        }
+      }
+    }
+    return issueList;
+  }, {
+    probes: normalized,
+    probeOptions: {
+      minTapTargetSize: options.minTapTargetSize || DEFAULT_MIN_TAP_TARGET_SIZE
+    }
+  });
+  return {
+    version: 1,
+    issues,
+    warnings: issues.filter(issue => !issue.required),
+    failures: issues.filter(issue => issue.required)
+  };
+};
+
+export {
+  DEFAULT_CAPTURE_ROOT,
+  captureTargets,
+  makeCaptureTimestamp,
+  normalizeClipRect,
+  resolveCaptureOutputDir,
+  resolveCaptureTargets,
+  runVisualProbes,
+  sanitizeCaptureName
+};
diff --git a/e2e/helpers/webmidiStub.js b/e2e/helpers/webmidiStub.js
index 60b90dc3..789085a7 100644
--- a/e2e/helpers/webmidiStub.js
+++ b/e2e/helpers/webmidiStub.js
@@ -1,39 +1,109 @@
-export async function installWebMidiStub(page, { withDevices = true } = {}) {
-  await page.addInitScript(({ withDevices }) => {
-    const createPort = (type, id, name) => ({
-      id,
-      name,
-      manufacturer: 'Playwright',
-      type,
-      state: 'connected',
-      connection: 'open',
-      onstatechange: null,
-      onmidimessage: null,
-      addEventListener: () => {},
-      removeEventListener: () => {},
-      open: async () => {},
-      close: async () => {},
-      send: () => {},
-      clear: () => {}
-    });
+export async function installWebMidiStub(page, { withDevices = true, permission = 'granted' } = {}) {
+  await page.addInitScript(({ withDevices, permission }) => {
+    const createPort = (type, id, name) => {
+      const listeners = new Map();
+      const port = {
+        id,
+        name,
+        manufacturer: 'Playwright',
+        type,
+        state: 'connected',
+        connection: 'open',
+        onstatechange: null,
+        onmidimessage: null,
+        addEventListener: (eventName, handler) => {
+          const list = listeners.get(eventName) || [];
+          list.push(handler);
+          listeners.set(eventName, list);
+        },
+        removeEventListener: (eventName, handler) => {
+          const list = listeners.get(eventName) || [];
+          listeners.set(eventName, list.filter(entry => entry !== handler));
+        },
+        open: async () => {},
+        close: async () => {},
+        send: () => {},
+        clear: () => {},
+        _emit(eventName, event) {
+          for (const handler of listeners.get(eventName) || []) handler(event);
+          const prop = `on${eventName}`;
+          if (typeof port[prop] === 'function') port[prop](event);
+        }
+      };
+      return port;
+    };
 
+    let midiAccess = null;
     const inputs = new Map();
     const outputs = new Map();
+    const listeners = new Map();
+
+    const emitAccessEvent = (eventName, event) => {
+      for (const handler of listeners.get(eventName) || []) handler(event);
+      const prop = `on${eventName}`;
+      if (typeof midiAccess?.[prop] === 'function') midiAccess[prop](event);
+    };
+
+    const emitStateChange = (port) => {
+      if (!midiAccess) return;
+      const event = { port, timeStamp: performance.now() };
+      emitAccessEvent('statechange', event);
+    };
+
+    const addPort = (type, id, name, { emit = true } = {}) => {
+      const target = type === 'input' ? inputs : outputs;
+      const existing = target.get(id);
+      if (existing) {
+        existing.state = 'connected';
+        existing.connection = 'open';
+        if (emit) emitStateChange(existing);
+        return existing;
+      }
+      const port = createPort(type, id, name);
+      target.set(id, port);
+      if (emit) emitStateChange(port);
+      return port;
+    };
+
+    const removePort = (type, id) => {
+      const target = type === 'input' ? inputs : outputs;
+      const port = target.get(id);
+      if (!port) return false;
+      target.delete(id);
+      port.state = 'disconnected';
+      port.connection = 'pending';
+      emitStateChange(port);
+      return true;
+    };
+
     if (withDevices) {
-      const input = createPort('input', 'pw-input-1', 'Playwright Input');
-      const output = createPort('output', 'pw-output-1', 'Playwright Output');
-      inputs.set(input.id, input);
-      outputs.set(output.id, output);
+      addPort('input', 'pw-input-1', 'Playwright Input', { emit: false });
+      addPort('output', 'pw-output-1', 'Playwright Output', { emit: false });
     }
 
-    const requestMIDIAccess = async () => ({
-      inputs,
-      outputs,
-      sysexEnabled: false,
-      onstatechange: null,
-      addEventListener: () => {},
-      removeEventListener: () => {}
-    });
+    const requestMIDIAccess = async () => {
+      if (permission === 'denied') {
+        const error = new Error('Permission denied');
+        error.name = 'NotAllowedError';
+        return Promise.reject(error);
+      }
+      midiAccess = {
+        inputs,
+        outputs,
+        sysexEnabled: false,
+        onstatechange: null,
+        addEventListener(eventName, handler) {
+          const list = listeners.get(eventName) || [];
+          list.push(handler);
+          listeners.set(eventName, list);
+        },
+        removeEventListener(eventName, handler) {
+          const list = listeners.get(eventName) || [];
+          listeners.set(eventName, list.filter(entry => entry !== handler));
+        }
+      };
+      return midiAccess;
+    };
 
     try {
       Object.defineProperty(navigator, 'requestMIDIAccess', {
@@ -43,5 +113,41 @@ export async function installWebMidiStub(page, { withDevices = true } = {}) {
     } catch (error) {
       navigator.requestMIDIAccess = requestMIDIAccess;
     }
-  }, { withDevices });
+
+    window.__WEBMIDI_STUB__ = {
+      sendInput(data, inputId = 'pw-input-1') {
+        const input = inputs.get(inputId);
+        if (!input) return false;
+        input._emit('midimessage', {
+          data: new Uint8Array(data),
+          receivedTime: performance.now()
+        });
+        return true;
+      },
+      sendNoteOn(note, velocity = 100, channel = 1, inputId = 'pw-input-1') {
+        return this.sendInput([0x90 + Math.max(0, Math.min(15, channel - 1)), note, velocity], inputId);
+      },
+      sendNoteOff(note, velocity = 0, channel = 1, inputId = 'pw-input-1') {
+        return this.sendInput([0x80 + Math.max(0, Math.min(15, channel - 1)), note, velocity], inputId);
+      },
+      disconnectInput(inputId = 'pw-input-1') {
+        return removePort('input', inputId);
+      },
+      reconnectInput(inputId = 'pw-input-1', name = 'Playwright Input') {
+        return !!addPort('input', inputId, name);
+      },
+      disconnectOutput(outputId = 'pw-output-1') {
+        return removePort('output', outputId);
+      },
+      reconnectOutput(outputId = 'pw-output-1', name = 'Playwright Output') {
+        return !!addPort('output', outputId, name);
+      },
+      listDevices() {
+        return {
+          inputs: Array.from(inputs.values()).map(input => ({ id: input.id, name: input.name, state: input.state })),
+          outputs: Array.from(outputs.values()).map(output => ({ id: output.id, name: output.name, state: output.state }))
+        };
+      }
+    };
+  }, { withDevices, permission });
 }
diff --git a/e2e/midi-ui.spec.js b/e2e/midi-ui.spec.js
index 8db9c020..0d3f9cac 100644
--- a/e2e/midi-ui.spec.js
+++ b/e2e/midi-ui.spec.js
@@ -1,133 +1,983 @@
 import { expect, test } from '@playwright/test';
 import { installExternalAssetStubs } from './helpers/externalAssets.js';
+import { clearLocalStorage, waitForHarnessReady } from './helpers/harness.js';
+import { MidiUiPage } from './helpers/pageObjects.js';
+import { installWebMidiStub } from './helpers/webmidiStub.js';
 
 test.beforeEach(async ({ page }) => {
   await installExternalAssetStubs(page);
 });
 
-test('MIDI UI starts disabled and hides panels', async ({ page }) => {
-  await page.goto('/');
-  await page.waitForSelector('#midiEnabledToggle');
+const openMidiUi = async (page, { resetStorage = false, withDevices = true, permission = 'granted' } = {}) => {
+  if (resetStorage) await clearLocalStorage(page);
+  await installWebMidiStub(page, { withDevices, permission });
+  const midi = new MidiUiPage(page);
+  await midi.goto('/?e2e=1');
+  await waitForHarnessReady(page);
+  await page.waitForSelector('#midiSourceList .midi-source-row');
+  return midi;
+};
+
+const setFieldValue = async (page, selector, value) => {
+  await page.locator(selector).evaluate((element, nextValue) => {
+    element.value = String(nextValue);
+    element.dispatchEvent(new Event('change', { bubbles: true }));
+  }, value);
+};
+
+test('MIDI sequencer gives editor controls scoped accessible names', async ({ page }) => {
+  const midi = await openMidiUi(page);
+  await expect(midi.workspace()).toBeVisible();
+
+  const labels = await page.locator([
+    '#midiProjectResetButton',
+    '#midiPanicButton',
+    '#midiTemplateSaveButton',
+    '#midiProjectExportButton',
+    '#midiProjectImportButton',
+    '#midiTrackAdd',
+    '#midiTrackRemove',
+    '#midiClipAddButton',
+    '#midiClipDuplicateButton',
+    '#midiClipRemoveButton',
+    '#midiAssignSourceButton',
+    '#midiAuditionButton',
+    '#midiClipAuditionButton',
+    '#midiSourceRevertButton',
+    '#midiAssignClipButton',
+    '#midiLearnButton',
+    '#midiLearnConfirmButton',
+    '#midiLearnCancelButton',
+    '#midiAutomationAddButton',
+    '#midiRecordButton',
+    '#midiRecordCommitButton',
+    '#midiRecordCancelButton'
+  ].join(', ')).evaluateAll(buttons => Object.fromEntries(
+    buttons.map(button => [button.id, button.getAttribute('aria-label')])
+  ));
+
+  expect(labels).toEqual({
+    midiProjectResetButton: 'Reset MIDI project',
+    midiPanicButton: 'Panic all MIDI notes',
+    midiTemplateSaveButton: 'Save MIDI template',
+    midiProjectExportButton: 'Export MIDI project',
+    midiProjectImportButton: 'Import MIDI project',
+    midiTrackAdd: 'Add MIDI track',
+    midiTrackRemove: 'Remove selected MIDI track',
+    midiClipAddButton: 'Add MIDI clip',
+    midiClipDuplicateButton: 'Duplicate selected MIDI clip',
+    midiClipRemoveButton: 'Remove selected MIDI clip',
+    midiAssignSourceButton: 'Assign selected source to track',
+    midiAuditionButton: 'Audition selected source',
+    midiClipAuditionButton: 'Audition selected clip',
+    midiSourceRevertButton: 'Revert selected source mapping',
+    midiAssignClipButton: 'Assign selected clip to source',
+    midiLearnButton: 'Start MIDI learn',
+    midiLearnConfirmButton: 'Commit MIDI learn',
+    midiLearnCancelButton: 'Cancel MIDI learn',
+    midiAutomationAddButton: 'Add modulation lane',
+    midiRecordButton: 'Start MIDI recording',
+    midiRecordCommitButton: 'Commit MIDI recording',
+    midiRecordCancelButton: 'Cancel MIDI recording'
+  });
+
+  const statuses = await page.locator([
+    '#midiConflictSummary',
+    '#midiLearnStatus',
+    '#midiRecordStatus',
+    '#midiSchedulerPressure',
+    '#midiOutputLog',
+    '#midiSourceCount'
+  ].join(', ')).evaluateAll(elements => Object.fromEntries(
+    elements.map(element => [element.id, {
+      role: element.getAttribute('role'),
+      live: element.getAttribute('aria-live') || ''
+    }])
+  ));
+
+  expect(statuses).toEqual({
+    midiConflictSummary: { role: 'status', live: 'polite' },
+    midiLearnStatus: { role: 'status', live: '' },
+    midiRecordStatus: { role: 'status', live: '' },
+    midiSchedulerPressure: { role: 'status', live: 'polite' },
+    midiOutputLog: { role: 'status', live: 'polite' },
+    midiSourceCount: { role: 'status', live: 'polite' }
+  });
+});
+
+test('MIDI sequencer creates a fresh project and clears legacy storage', async ({ page }) => {
+  await page.addInitScript(() => {
+    window.localStorage?.setItem?.('lemmings.midi.intent', '{"revision":99}');
+    window.localStorage?.setItem?.('lemmings.midi.overrides', '{"sfx":{"1":{"note":99}}}');
+    window.localStorage?.setItem?.('lemmings.midi.inputId', 'legacy-input');
+  });
+  const midi = await openMidiUi(page, { resetStorage: false, withDevices: false });
+
+  await expect(midi.workspace()).toBeVisible();
   await expect(page.locator('body')).toHaveClass(/midi-disabled/);
-  await expect(page.locator('#midiEnabledToggle')).not.toBeChecked();
-  await expect(page.locator('#controlRight')).toBeHidden();
-});
-
-test('Enabling MIDI reveals panels and inputs', async ({ page }) => {
-  await page.goto('/');
-  const toggle = page.locator('#midiEnabledToggle');
-  await toggle.check();
-  await expect(page.locator('body')).not.toHaveClass(/midi-disabled/);
-  await expect(page.locator('#controlRight')).toBeVisible();
-  const inputState = await page.evaluate(() => {
-    const input = document.getElementById('midiInSelect');
-    const output = document.getElementById('midiOutSelect');
-    const error = document.getElementById('errorDisplay');
+  const state = await page.evaluate(() => ({
+    legacyIntent: window.localStorage.getItem('lemmings.midi.intent'),
+    legacyOverrides: window.localStorage.getItem('lemmings.midi.overrides'),
+    legacyInput: window.localStorage.getItem('lemmings.midi.inputId'),
+    project: window.__E2E__.midiGetProject()
+  }));
+
+  expect(state.legacyIntent).toBeNull();
+  expect(state.legacyOverrides).toBeNull();
+  expect(state.legacyInput).toBeNull();
+  expect(state.project.version).toBe(1);
+  expect(state.project.sources.some(source => source.kind === 'sfx' && source.sourceKey === '1')).toBe(true);
+
+  await midi.enable();
+  await expect(page.locator('#midiInSelect')).toContainText('No input devices');
+  await expect(page.locator('#midiOutSelect')).toContainText('No output devices');
+  await expect(page.locator('#errorDisplay')).toContainText('No input device');
+  await expect(page.locator('#errorDisplay')).toContainText('No output device');
+});
+
+test('MIDI sequencer reports permission denial and mocked device lifecycle', async ({ page }) => {
+  let midi = await openMidiUi(page, { permission: 'denied' });
+  await midi.enable();
+  await expect(page.locator('#errorDisplay')).toContainText('WebMIDI permission denied');
+
+  await page.goto('about:blank');
+  midi = await openMidiUi(page);
+  await midi.enable();
+  await expect(page.locator('#midiInSelect')).toHaveValue('pw-input-1');
+  await expect(page.locator('#midiOutSelect')).toHaveValue('pw-output-1');
+
+  const disconnected = await page.evaluate(() => ({
+    input: window.__WEBMIDI_STUB__.disconnectInput('pw-input-1'),
+    output: window.__WEBMIDI_STUB__.disconnectOutput('pw-output-1')
+  }));
+  expect(disconnected).toEqual({ input: true, output: true });
+  await expect(page.locator('#midiInSelect')).toContainText('No input devices');
+  await expect(page.locator('#midiOutSelect')).toContainText('No output devices');
+  await expect(page.locator('#errorDisplay')).toContainText('No input device');
+  await expect(page.locator('#errorDisplay')).toContainText('No output device');
+
+  const reconnected = await page.evaluate(() => ({
+    input: window.__WEBMIDI_STUB__.reconnectInput('pw-input-2', 'Recovered Input'),
+    output: window.__WEBMIDI_STUB__.reconnectOutput('pw-output-2', 'Recovered Output')
+  }));
+  expect(reconnected).toEqual({ input: true, output: true });
+  await expect(page.locator('#midiInSelect')).toHaveValue('pw-input-2');
+  await expect(page.locator('#midiOutSelect')).toHaveValue('pw-output-2');
+  await expect(page.locator('#errorDisplay')).toHaveText('');
+});
+
+test('MIDI sequencer supports setup, track routing, direct mapping, and audition', async ({ page }) => {
+  const midi = await openMidiUi(page);
+  const setField = async (selector, value) => {
+    await page.locator(selector).evaluate((element, nextValue) => {
+      element.value = String(nextValue);
+      element.dispatchEvent(new Event('change', { bubbles: true }));
+    }, value);
+  };
+  await midi.enable();
+  await expect(page.locator('#midiInSelect')).toHaveValue('pw-input-1');
+  await expect(page.locator('#midiOutSelect')).toHaveValue('pw-output-1');
+  await page.locator('#midiTrackOutputSelect').selectOption('pw-output-1');
+  await page.locator('#midiScaleRoot').selectOption('2');
+  await page.locator('#midiScaleName').selectOption('major');
+  await page.locator('#midiQuantize').selectOption('1/8');
+  await setField('#midiSwing', '0.25');
+  await page.locator('#midiReversePanicToggle').check();
+
+  const project = await page.evaluate(() => {
+    let next = window.__E2E__.midiDispatchProjectIntent({ type: 'track.add', track: { id: 'lead', name: 'Lead', channel: 3 } });
+    next = window.__E2E__.midiDispatchProjectIntent({ type: 'source.assignTrack', sourceId: 'sfx-1', trackId: 'lead' });
+    next = window.__E2E__.midiDispatchProjectIntent({ type: 'source.mapping.update', sourceId: 'sfx-1', patch: { note: 72, velocity: 96, durationTicks: 5 } });
+    window.__E2E__.midiAudition({ sourceId: 'sfx-1', trackId: 'lead' });
+    return next;
+  });
+  await setField('#midiTrackPriority', '4');
+  await setField('#midiTrackVoiceBudget', '6');
+  await setField('#midiTrackVelocityScale', '0.75');
+  await page.locator('#midiTrackMute').check();
+  await page.locator('#midiTrackMute').uncheck();
+  await page.locator('#midiTrackSolo').check();
+  await page.locator('#midiTrackArm').check();
+  await page.locator('#midiMappingArp').selectOption('down');
+  await setField('#midiMappingPan', '-24');
+  await setField('#midiMappingTimbre', '88');
+  await setField('#midiMappingPitchBend', '0.5');
+  const updatedProject = await page.evaluate(() => window.__E2E__.midiGetProject());
+  const runtime = await page.evaluate(() => window.__E2E__.midiGetRuntimeConfig());
+  const updatedMapping = updatedProject.sources.find(source => source.id === 'sfx-1').mapping;
+  const updatedTrack = updatedProject.tracks.find(track => track.id === 'lead');
+
+  expect(project.tracks.some(track => track.id === 'lead' && track.channel === 3)).toBe(true);
+  expect(project.tracks.find(track => track.id === 'track-1').outputId).toBe('pw-output-1');
+  expect(project.sources.find(source => source.id === 'sfx-1').trackId).toBe('lead');
+  expect(updatedTrack).toMatchObject({
+    priority: 4,
+    voiceBudget: 6,
+    velocityScale: 0.75,
+    mute: false,
+    solo: true,
+    arm: true
+  });
+  expect(updatedProject.global.scale).toMatchObject({ name: 'major', root: 2 });
+  expect(updatedProject.global.scale.degrees).toEqual([0, 2, 4, 5, 7, 9, 11]);
+  expect(updatedProject.global.reverse.allNotesOffOnToggle).toBe(true);
+  expect(updatedProject.transport).toMatchObject({ quantize: '1/8', swing: 0.25 });
+  expect(updatedMapping).toMatchObject({ note: 72, velocity: 96, durationTicks: 5, pan: -24, timbre: 88, pitchBend: 0.5 });
+  expect(updatedMapping.arp).toMatchObject({ enabled: true, mode: 'down' });
+  expect(runtime.sfx['1']).toMatchObject({
+    note: 72,
+    velocity: 72,
+    durationTicks: 5,
+    channel: 3,
+    trackId: 'lead',
+    priority: 4,
+    voiceBudget: 6,
+    pan: -24,
+    timbre: 88,
+    pitchBend: 0.5
+  });
+  expect(runtime.sfx['1'].arp).toMatchObject({ enabled: true, mode: 'down' });
+  await expect(midi.outputLog()).toContainText(/Audition|skipped/);
+  await expect(page.locator('#midiTrackList')).toContainText('Lead');
+  await expect(page.locator('#midiSelectedSourceSummary')).toContainText('Lead');
+});
+
+test('MIDI sequencer lowers direct chord mappings into runtime config', async ({ page }) => {
+  const midi = await openMidiUi(page);
+  const setField = async (selector, value) => {
+    await page.locator(selector).evaluate((element, nextValue) => {
+      element.value = String(nextValue);
+      element.dispatchEvent(new Event('change', { bubbles: true }));
+    }, value);
+  };
+  await midi.enable();
+
+  await page.locator('#midiMappingChord').selectOption('seventh');
+  await setField('#midiMappingDegree', '2');
+  await setField('#midiMappingOctave', '5');
+  await setField('#midiMappingChordInversion', '1');
+  const state = await page.evaluate(() => ({
+    auditioned: window.__E2E__.midiAudition({ sourceId: 'sfx-1' }),
+    project: window.__E2E__.midiGetProject(),
+    runtime: window.__E2E__.midiGetRuntimeConfig()
+  }));
+  const mapping = state.project.sources.find(source => source.id === 'sfx-1').mapping;
+
+  expect(mapping).toMatchObject({
+    note: null,
+    degree: 2,
+    octave: 5,
+    chord: { type: 'seventh', inversion: 1 }
+  });
+  expect(state.runtime.sfx['1']).toMatchObject({
+    degree: 2,
+    octave: 5,
+    chord: { type: 'seventh', inversion: 1 }
+  });
+  expect(state.runtime.sfx['1'].note).toBeUndefined();
+  expect(state.auditioned).toBe(true);
+  await expect(midi.outputLog()).toContainText('Audition');
+});
+
+test('MIDI sequencer routes multiple sources to separate track channels', async ({ page }) => {
+  await openMidiUi(page);
+
+  const state = await page.evaluate(() => {
+    window.__E2E__.midiDispatchProjectIntent({ type: 'track.add', track: { id: 'melody', name: 'Melody', channel: 2 } });
+    window.__E2E__.midiDispatchProjectIntent({ type: 'track.add', track: { id: 'drums', name: 'Drums', channel: 10 } });
+    window.__E2E__.midiDispatchProjectIntent({ type: 'source.assignTrack', sourceId: 'sfx-1', trackId: 'melody' });
+    window.__E2E__.midiDispatchProjectIntent({ type: 'source.assignTrack', sourceId: 'sfx-2', trackId: 'drums' });
+    window.__E2E__.midiDispatchProjectIntent({
+      type: 'source.mapping.update',
+      sourceId: 'sfx-2',
+      patch: { note: 36, velocity: 110 }
+    });
     return {
-      inputDisabled: input?.disabled ?? null,
-      outputDisabled: output?.disabled ?? null,
-      inputLabel: input?.options?.[0]?.textContent ?? '',
-      outputLabel: output?.options?.[0]?.textContent ?? '',
-      errorText: error?.textContent ?? ''
+      project: window.__E2E__.midiGetProject(),
+      runtime: window.__E2E__.midiGetRuntimeConfig()
     };
   });
-  if (inputState.inputDisabled) {
-    expect(inputState.inputLabel).toContain('No input');
-    expect(inputState.errorText).toContain('No input device');
-  } else {
-    await expect(page.locator('#midiInSelect')).toBeEnabled();
-  }
-  if (inputState.outputDisabled) {
-    expect(inputState.outputLabel).toContain('No output');
-    expect(inputState.errorText).toContain('No output device');
-  } else {
-    await expect(page.locator('#midiOutSelect')).toBeEnabled();
-  }
+
+  expect(state.project.sources.find(source => source.id === 'sfx-1')).toMatchObject({ trackId: 'melody' });
+  expect(state.project.sources.find(source => source.id === 'sfx-2')).toMatchObject({ trackId: 'drums' });
+  expect(state.runtime.sfx['1']).toMatchObject({ trackId: 'melody', channel: 2 });
+  expect(state.runtime.sfx['2']).toMatchObject({ trackId: 'drums', channel: 10, note: 36, velocity: 110 });
+  await expect(page.locator('#midiTrackList')).toContainText('Melody');
+  await expect(page.locator('#midiTrackList')).toContainText('Drums');
 });
 
-test('MIDI panels match layout snapshots', async ({ page }) => {
-  await page.goto('/');
-  await page.locator('#midiEnabledToggle').check();
-  await page.waitForSelector('#midiEventList details');
-  const leftPanel = page.locator('#controlLeft');
-  const rightPanel = page.locator('#controlRight');
-  await expect(leftPanel).toHaveScreenshot('midi-left-default.png');
-  await expect(rightPanel).toHaveScreenshot('midi-right-events.png');
-  await page.locator('[data-tab-target="midiTabTriggers"]').click();
-  await expect(page.locator('#midiTabTriggers')).toHaveClass(/active/);
-  await expect(rightPanel).toHaveScreenshot('midi-right-triggers.png');
-  await page.locator('[data-tab-target="midiTabAdsr"]').click();
-  await expect(page.locator('#midiTabAdsr')).toHaveClass(/active/);
-  await expect(rightPanel).toHaveScreenshot('midi-right-adsr.png');
-  await page.locator('[data-tab-target="midiTabGlobalFx"]').click();
-  await expect(page.locator('#midiTabGlobalFx')).toHaveClass(/active/);
-  await expect(leftPanel).toHaveScreenshot('midi-left-global-fx.png');
-});
-
-test('MIDI event and trigger titles render with width', async ({ page }) => {   
-  await page.goto('/');
-  await page.locator('#midiEnabledToggle').check();
-  await page.waitForSelector('#midiEventList details');
-  await expect(page.locator('#controlRight')).toBeVisible();
-  await page.waitForSelector('#midiEventList summary .panel-title-text', { state: 'visible' });
-  const eventTitle = page.locator('#midiEventList summary .panel-title-text').first();
-  await expect(eventTitle).toContainText('#');
-  const eventWidth = await eventTitle.evaluate(el => el.getBoundingClientRect().width);
-  expect(eventWidth).toBeGreaterThan(20);
-  await page.locator('[data-tab-target="midiTabTriggers"]').click();
-  await page.waitForSelector('#midiTriggerList summary .panel-title-text', { state: 'visible' });
-  const triggerTitle = page.locator('#midiTriggerList summary .panel-title-text').first();
-  await expect(triggerTitle).toContainText('#');
-  const triggerWidth = await triggerTitle.evaluate(el => el.getBoundingClientRect().width);
-  expect(triggerWidth).toBeGreaterThan(20);
-});
-
-test('MIDI event list excludes unknown-0B', async ({ page }) => {
-  await page.goto('/');
-  await page.locator('#midiEnabledToggle').check();
-  await page.waitForSelector('#midiEventList details');
-  await expect(page.locator('#midiEventList')).not.toContainText('unknown-0B');
-});
-
-test('MIDI panels warn when scrolling is required', async ({ page }, testInfo) => {
-  await page.goto('/');
-  await page.locator('#midiEnabledToggle').check();
-  const selectors = ['#controlLeft', '#controlRight'];
-  for (const selector of selectors) {
-    const metrics = await page.evaluate((sel) => {
-      const panel = document.querySelector(sel);
-      if (!panel) return null;
-      const styles = window.getComputedStyle(panel);
-      const paddingLeft = Number.parseFloat(styles.paddingLeft) || 0;
-      const paddingRight = Number.parseFloat(styles.paddingRight) || 0;
-      return {
-        scrollHeight: panel.scrollHeight,
-        clientHeight: panel.clientHeight,
-        scrollWidth: panel.scrollWidth,
-        clientWidth: panel.clientWidth,
-        paddingX: paddingLeft + paddingRight
-      };
-    }, selector);
-    if (!metrics) continue;
-    expect(metrics.scrollWidth).toBeLessThanOrEqual(
-      metrics.clientWidth + metrics.paddingX + 2
-    );
-    if (metrics.scrollHeight > metrics.clientHeight + 2) {
-      testInfo.annotations.push({
-        type: 'warning',
-        description: `${selector} requires scrolling at default size.`
-      });
+test('MIDI sequencer removes tracks and manages clip library controls', async ({ page }) => {
+  const midi = await openMidiUi(page);
+  await expect(midi.trackRemoveButton()).toBeDisabled();
+  await expect(midi.clipDuplicateButton()).toBeDisabled();
+  await expect(midi.clipRemoveButton()).toBeDisabled();
+
+  await page.evaluate(() => {
+    window.__E2E__.midiDispatchProjectIntent({ type: 'track.add', track: { id: 'lead', name: 'Lead', channel: 3 } });
+    window.__E2E__.midiDispatchProjectIntent({ type: 'track.add', track: { id: 'drums', name: 'Drums', channel: 10 } });
+    window.__E2E__.midiDispatchProjectIntent({ type: 'source.assignTrack', sourceId: 'sfx-1', trackId: 'drums' });
+    window.__E2E__.midiDispatchProjectIntent({
+      type: 'automation.add',
+      automation: { id: 'lane-drums', scope: 'track', trackId: 'drums', target: 'velocity', axis: 'y' }
+    });
+    window.__E2E__.midiDispatchProjectIntent({ type: 'track.select', trackId: 'drums' });
+  });
+  await expect(midi.trackRemoveButton()).toBeEnabled();
+  await midi.trackRemoveButton().click();
+
+  let project = await page.evaluate(() => window.__E2E__.midiGetProject());
+  expect(project.tracks.map(track => track.id)).toEqual(['track-1', 'lead']);
+  expect(project.ui.selectedTrackId).toBe('lead');
+  expect(project.sources.find(source => source.id === 'sfx-1').trackId).toBe('lead');
+  expect(project.automation.some(lane => lane.id === 'lane-drums')).toBe(false);
+  expect(project.automation.every(lane => lane.trackId !== 'drums')).toBe(true);
+
+  await page.evaluate(() => {
+    window.__E2E__.midiDispatchProjectIntent({ type: 'clip.add', clip: { id: 'riff', name: 'Riff', lengthSteps: 4 } });
+    window.__E2E__.midiDispatchProjectIntent({ type: 'clip.step.update', clipId: 'riff', stepIndex: 0, patch: { note: 65, velocity: 90 } });
+    window.__E2E__.midiDispatchProjectIntent({ type: 'clip.add', clip: { id: 'fill', name: 'Fill', lengthSteps: 4 } });
+    window.__E2E__.midiDispatchProjectIntent({ type: 'source.clip.assign', sourceId: 'sfx-1', clipId: 'riff' });
+    window.__E2E__.midiDispatchProjectIntent({ type: 'clip.select', clipId: 'riff' });
+  });
+  await expect(midi.clipDuplicateButton()).toBeEnabled();
+  await expect(midi.clipRemoveButton()).toBeEnabled();
+  await midi.clipDuplicateButton().click();
+
+  project = await page.evaluate(() => window.__E2E__.midiGetProject());
+  expect(project.clips.map(clip => clip.id)).toEqual(['riff', 'fill', 'riff-copy']);
+  expect(project.ui.selectedClipId).toBe('riff-copy');
+  expect(project.clips.find(clip => clip.id === 'riff-copy').steps[0]).toMatchObject({ note: 65, velocity: 90 });
+  expect(project.sources.find(source => source.id === 'sfx-1')).toMatchObject({ mode: 'clip', clipId: 'riff' });
+
+  await page.evaluate(() => window.__E2E__.midiDispatchProjectIntent({ type: 'clip.select', clipId: 'riff' }));
+  await midi.clipRemoveButton().click();
+  project = await page.evaluate(() => window.__E2E__.midiGetProject());
+  expect(project.clips.map(clip => clip.id)).toEqual(['fill', 'riff-copy']);
+  expect(project.ui.selectedClipId).toBe('fill');
+  expect(project.sources.find(source => source.id === 'sfx-1')).toMatchObject({ mode: 'direct', clipId: null });
+});
+
+test('MIDI sequencer panic button logs feedback', async ({ page }) => {
+  const midi = await openMidiUi(page);
+  await midi.enable();
+
+  await expect(midi.outputLog()).toHaveAttribute('role', 'status');
+  await expect(midi.outputLog()).toHaveAttribute('aria-live', 'polite');
+  await page.locator('#midiPanicButton').click();
+  await expect(midi.outputLog()).toContainText('Panic sent');
+});
+
+test('MIDI project persists across reload', async ({ page }) => {
+  await openMidiUi(page);
+  await page.evaluate(() => {
+    window.__E2E__.midiDispatchProjectIntent({ type: 'source.mapping.update', sourceId: 'sfx-1', patch: { note: 74 } });
+  });
+
+  await page.reload();
+  await waitForHarnessReady(page);
+  await page.waitForSelector('#midiSourceList .midi-source-row');
+  const note = await page.evaluate(() => (
+    window.__E2E__.midiGetProject().sources.find(source => source.id === 'sfx-1').mapping.note
+  ));
+  expect(note).toBe(74);
+});
+
+test('MIDI sequencer imports, exports, saves templates, and resets from templates', async ({ page }) => {
+  const midi = await openMidiUi(page);
+
+  const state = await page.evaluate(() => {
+    window.__E2E__.midiDispatchProjectIntent({
+      type: 'source.mapping.update',
+      sourceId: 'sfx-1',
+      patch: { note: 79 }
+    });
+    const exported = window.__E2E__.midiExportProject({ download: false, exportedAt: 1 });
+    const template = window.__E2E__.midiSaveProjectTemplate({
+      id: 'lead-template',
+      name: 'Lead Template',
+      now: 1
+    });
+    const imported = window.__E2E__.midiImportProject(JSON.stringify({
+      kind: 'lemmings.midi.project',
+      version: 1,
+      project: {
+        ...exported.project,
+        name: 'Imported MIDI',
+        sources: exported.project.sources.map(source => (
+          source.id === 'sfx-1'
+            ? { ...source, mapping: { ...source.mapping, note: 84 } }
+            : source
+        ))
+      }
+    }));
+    const reset = window.__E2E__.midiResetProject('lead-template');
+    return {
+      exported,
+      template,
+      importedNote: imported.sources.find(source => source.id === 'sfx-1').mapping.note,
+      resetNote: reset.sources.find(source => source.id === 'sfx-1').mapping.note,
+      templates: window.__E2E__.midiGetProjectTemplates()
+    };
+  });
+
+  expect(state.exported.kind).toBe('lemmings.midi.project');
+  expect(state.template).toMatchObject({ id: 'lead-template', name: 'Lead Template' });
+  expect(state.importedNote).toBe(84);
+  expect(state.resetNote).toBe(79);
+  expect(state.templates.map(template => template.id)).toContain('lead-template');
+  await expect(midi.templateSelect()).toContainText('Lead Template');
+});
+
+test('MIDI sequencer learns a selected direct source note and resolves range warnings', async ({ page }) => {
+  const midi = await openMidiUi(page);
+  await midi.enable();
+  const setField = async (selector, value) => {
+    await page.locator(selector).evaluate((element, nextValue) => {
+      element.value = String(nextValue);
+      element.dispatchEvent(new Event('change', { bubbles: true }));
+    }, value);
+  };
+
+  await setField('#midiGlobalNoteMax', '80');
+  await expect(midi.learnPanel()).toBeVisible();
+  await midi.learnButton().click();
+  await expect(midi.learnStatus()).toContainText('Listening');
+  const sent = await page.evaluate(() => window.__WEBMIDI_STUB__.sendNoteOn(86, 104, 6));
+  expect(sent).toBe(true);
+  await expect(midi.learnStatus()).toContainText('Pending note 86');
+  await expect(midi.learnStatus()).toContainText('1 warning');
+  await midi.learnConfirmButton().click();
+  await expect(midi.conflictSummary()).toContainText('outside the project note range');
+
+  const project = await page.evaluate(() => window.__E2E__.midiGetProject());
+  const source = project.sources.find(entry => entry.id === 'sfx-1');
+  expect(source.mapping).toMatchObject({ note: 86, velocity: 104, degree: null, chord: null });
+  await setField('#midiGlobalNoteMax', '96');
+  await page.evaluate(() => window.__E2E__.midiDispatchProjectIntent({ type: 'source.select', sourceId: 'sfx-1' }));
+  await expect.poll(() => page.evaluate(() => window.__E2E__.midiGetProject().ui.selectedSourceId)).toBe('sfx-1');
+  await expect(midi.conflictSummary()).not.toContainText('outside the project note range');
+});
+
+test('MIDI sequencer records mocked MIDI notes into a step clip', async ({ page }) => {
+  const midi = await openMidiUi(page);
+  await midi.enable();
+
+  await midi.clipAddButton().click();
+  await expect(midi.recordPanel()).toBeVisible();
+  await midi.recordButton().click();
+  await expect(midi.recordStatus()).toContainText('Recording');
+  await page.evaluate(() => {
+    window.__WEBMIDI_STUB__.sendNoteOn(62, 90, 1);
+    window.__WEBMIDI_STUB__.sendNoteOff(62, 0, 1);
+    window.__WEBMIDI_STUB__.sendNoteOn(65, 88, 1);
+  });
+  await midi.recordCommitButton().click();
+
+  const project = await page.evaluate(() => window.__E2E__.midiGetProject());
+  const clip = project.clips.find(entry => entry.id === project.ui.selectedClipId);
+  expect(clip.steps[0]).toMatchObject({ note: 62, velocity: 90 });
+  expect(clip.steps[1]).toMatchObject({ note: 65, velocity: 88 });
+});
+
+test('MIDI sequencer creates, edits, assigns, auditions, and persists a clip', async ({ page }) => {
+  const midi = await openMidiUi(page);
+  await midi.enable();
+  const setField = async (selector, value) => {
+    await page.locator(selector).evaluate((element, nextValue) => {
+      element.value = String(nextValue);
+      element.dispatchEvent(new Event('change', { bubbles: true }));
+    }, value);
+  };
+
+  await midi.clipAddButton().click();
+  await setField('#midiClipName', 'Lead Clip');
+  await page.locator('#midiClipType').selectOption('arp');
+  await page.locator('#midiClipArpMode').selectOption('updown');
+  await page.locator('#midiClipArpPattern').selectOption('custom');
+  await setField('.midi-step-note[data-step-index="0"]', 66);
+  await setField('.midi-step-velocity[data-step-index="0"]', 91);
+  await setField('.midi-step-duration[data-step-index="0"]', 9);
+  await setField('.midi-step-note[data-step-index="1"]', 70);
+  await midi.sourceModeSelect().selectOption('clip');
+  await page.locator('#midiAssignClipButton').click();
+  await midi.clipAuditionButton().click();
+
+  const project = await page.evaluate(() => window.__E2E__.midiGetProject());
+  const clip = project.clips.find(entry => entry.name === 'Lead Clip');
+  const source = project.sources.find(entry => entry.id === 'sfx-1');
+  expect(clip).toMatchObject({
+    type: 'arp',
+    arp: {
+      mode: 'updown',
+      pattern: { preset: 'custom' }
     }
-  }
+  });
+  expect(clip.steps[0]).toMatchObject({ note: 66, velocity: 91, durationTicks: 9 });
+  expect(clip.steps[1]).toMatchObject({ note: 70 });
+  expect(source).toMatchObject({ mode: 'clip', clipId: clip.id });
+  const runtime = await page.evaluate(() => window.__E2E__.midiGetRuntimeConfig());
+  expect(runtime.sfx['1']).toMatchObject({
+    note: 66,
+    velocity: 91,
+    durationTicks: 9,
+    clipId: clip.id
+  });
+  expect(runtime.sfx['1'].notes).toEqual([66, 70]);
+  await expect(midi.outputLog()).toContainText(/Audition|skipped/);
+
+  await page.reload();
+  await waitForHarnessReady(page);
+  await page.waitForSelector('#midiClipList .midi-clip-row');
+  const reloaded = await page.evaluate(() => window.__E2E__.midiGetProject());
+  expect(reloaded.clips.find(entry => entry.name === 'Lead Clip').steps[0].note).toBe(66);
+  expect(reloaded.sources.find(entry => entry.id === 'sfx-1').mode).toBe('clip');
+});
+
+test('MIDI clip inspector moves focus when arp controls hide', async ({ page }) => {
+  const midi = await openMidiUi(page);
+  await midi.clipAddButton().click();
+  await page.locator('#midiClipType').selectOption('arp');
+  await expect(page.locator('#midiClipArpPatternField')).toBeVisible();
+  await page.locator('#midiClipArpPattern').focus();
+
+  const clipId = await page.evaluate(() => window.__E2E__.midiGetProject().ui.selectedClipId);
+  await page.evaluate(selectedClipId => {
+    window.__E2E__.midiDispatchProjectIntent({
+      type: 'clip.update',
+      clipId: selectedClipId,
+      patch: { type: 'stepPattern' }
+    });
+  }, clipId);
+
+  await expect(page.locator('#midiClipArpPatternField')).toBeHidden();
+  await expect.poll(() => page.evaluate(() => document.activeElement?.id)).toBe('midiClipType');
+});
+
+test('MIDI source browser search and filters remain usable', async ({ page }) => {
+  const midi = await openMidiUi(page);
+  await expect(midi.sourceRows().first()).toBeVisible();
+
+  await midi.sourceAssignFilter().selectOption('changed');
+  await expect(page.locator('#midiSourceList')).toContainText('No sources match');
+  await expect(page.locator('#midiSourceCount')).toHaveAttribute('aria-label', '0 sources shown');
+  await page.evaluate(() => {
+    window.__E2E__.midiDispatchProjectIntent({
+      type: 'source.mapping.update',
+      sourceId: 'sfx-1',
+      patch: { note: 91 }
+    });
+  });
+  await expect(midi.sourceRows()).toHaveCount(1);
+  await expect(page.locator('#midiSourceCount')).toHaveAttribute('aria-label', '1 source shown');
+  await expect(midi.sourceRows().first()).toContainText('Changed');
+  await page.locator('#midiSourceRevertButton').click();
+  await expect(page.locator('#midiSourceList')).toContainText('No sources match');
+  await midi.sourceAssignFilter().selectOption('all');
+
+  await page.evaluate(() => {
+    const project = window.__E2E__.midiGetProject();
+    window.__E2E__.midiDispatchProjectIntent({
+      type: 'project.set',
+      project: {
+        ...project,
+        sources: [
+          ...project.sources,
+          {
+            id: 'system-e2e-unavailable',
+            kind: 'system',
+            sourceKey: 'e2e-unavailable',
+            label: 'E2E unavailable system',
+            enabled: true,
+            trackId: project.tracks[0]?.id || 'track-1',
+            mode: 'direct',
+            mapping: { note: 60 },
+            clipId: null
+          }
+        ]
+      }
+    });
+  });
+  await midi.sourceAssignFilter().selectOption('available');
+  const availableIds = await midi.sourceRows().evaluateAll(rows => rows.map(row => row.dataset.sourceId));
+  expect(availableIds).toContain('sfx-16');
+  expect(availableIds).not.toContain('system-e2e-unavailable');
+  await midi.sourceAssignFilter().selectOption('all');
+
+  await page.evaluate(() => {
+    window.__E2E__.midiDispatchProjectIntent({
+      type: 'source.update',
+      sourceId: 'sfx-2',
+      patch: { enabled: false }
+    });
+  });
+  await midi.sourceAssignFilter().selectOption('disabled');
+  const disabledIds = await midi.sourceRows().evaluateAll(rows => rows.map(row => row.dataset.sourceId));
+  expect(disabledIds).toContain('sfx-2');
+  await midi.sourceAssignFilter().selectOption('enabled');
+  const enabledIds = await midi.sourceRows().evaluateAll(rows => rows.map(row => row.dataset.sourceId));
+  expect(enabledIds).not.toContain('sfx-2');
+  await midi.sourceAssignFilter().selectOption('assigned');
+  await expect(midi.sourceRows().first()).toBeVisible();
+  await midi.sourceAssignFilter().selectOption('unassigned');
+  await expect(page.locator('#midiSourceList')).toContainText('No sources match');
+  await midi.sourceAssignFilter().selectOption('all');
+
+  await page.locator('#midiSourceSearch').fill('skill');
+  await expect(midi.sourceRows().first()).toContainText(/skill/i);
+  await page.locator('#midiSourceKindFilter').selectOption('trigger');
+  await expect(page.locator('#midiSourceList')).toContainText(/No sources|Trigger|MIDI_FLAG/i);
+  await page.locator('#midiSourceSearch').fill('no-such-source-name');
+  await expect(page.locator('#midiSourceList')).toContainText('No sources match');
+});
+
+test('MIDI source filters keep an active listbox option', async ({ page }) => {
+  const midi = await openMidiUi(page);
+  await page.evaluate(() => {
+    const project = window.__E2E__.midiGetProject();
+    window.__E2E__.midiDispatchProjectIntent({
+      type: 'project.set',
+      project: {
+        ...project,
+        sources: [
+          ...project.sources,
+          {
+            id: 'system-e2e-unavailable',
+            kind: 'system',
+            sourceKey: 'e2e-unavailable',
+            label: 'E2E unavailable system',
+            enabled: true,
+            trackId: project.tracks[0]?.id || 'track-1',
+            mode: 'direct',
+            mapping: { note: 60 },
+            clipId: null
+          }
+        ],
+        ui: {
+          ...project.ui,
+          selectedSourceId: 'system-e2e-unavailable'
+        }
+      }
+    });
+  });
+
+  await midi.sourceAssignFilter().selectOption('available');
+  await expect(midi.sourceRows().first()).toBeVisible();
+  const listState = await page.evaluate(() => {
+    const list = document.getElementById('midiSourceList');
+    const rows = Array.from(list.querySelectorAll('.midi-source-row'));
+    const activeId = list.getAttribute('aria-activedescendant');
+    const active = document.getElementById(activeId);
+    return {
+      activeId,
+      firstId: rows[0]?.id || '',
+      activeTabIndex: active?.tabIndex,
+      activeSelected: active?.getAttribute('aria-selected') || '',
+      selectedSourceId: window.__E2E__.midiGetProject().ui.selectedSourceId
+    };
+  });
+
+  expect(listState.activeId).not.toBe('');
+  expect(listState.activeId).toBe(listState.firstId);
+  expect(listState.activeTabIndex).toBe(0);
+  expect(listState.activeSelected).toBe('false');
+  expect(listState.selectedSourceId).toBe('system-e2e-unavailable');
+});
+
+test('MIDI sequencer edits modulation controls', async ({ page }) => {
+  const midi = await openMidiUi(page);
+  await expect(midi.modulationInspector()).toBeVisible();
+  const setField = async (selector, value) => {
+    await page.locator(selector).evaluate((element, nextValue) => {
+      element.value = String(nextValue);
+      element.dispatchEvent(new Event('change', { bubbles: true }));
+    }, value);
+  };
+  const automationCount = await midi.automationRows().count();
+
+  await setField('#midiTrackVelocityScale', '0.5');
+  await setField('#midiGlobalIntensity', '96');
+  await setField('#midiGlobalVelocityMin', '20');
+  await setField('#midiGlobalVelocityMax', '110');
+  await setField('#midiGlobalNoteMin', '36');
+  await setField('#midiGlobalNoteMax', '96');
+  await setField('#midiGlobalAccent', '0.8');
+  await setField('#midiGlobalDensityWindow', '12');
+  await setField('#midiGlobalDurationScale', '0.25');
+  await setField('#midiGlobalMaxActiveNotes', '24');
+  await setField('#midiGlobalMaxEventsPerTick', '16');
+  await setField('#midiGlobalEnvAttack', '1.25');
+  await setField('#midiGlobalEnvRelease', '0.75');
+  await page.locator('#midiGlobalViewPan').check();
+  await setField('#midiGlobalPanMin', '-48');
+  await setField('#midiGlobalPanMax', '48');
+  await setField('#midiGlobalPanDeadZone', '0.08');
+  await setField('#midiGlobalTimbreMin', '12');
+  await setField('#midiGlobalTimbreMax', '100');
+  await setField('#midiGlobalXNoteMin', '-18');
+  await setField('#midiGlobalXNoteMax', '18');
+  await page.locator('#midiEnvelopeOverrideToggle').check();
+  await midi.automationAddButton().click();
+  const laneLayout = await page.locator('.midi-automation-row').last().evaluate(row => {
+    const children = Array.from(row.children);
+    const rowRect = row.getBoundingClientRect();
+    const removeRect = children[children.length - 1].getBoundingClientRect();
+    return {
+      childCount: children.length,
+      rowHeight: rowRect.height,
+      removeTopOffset: removeRect.top - rowRect.top
+    };
+  });
+  expect(laneLayout.childCount).toBe(9);
+  expect(laneLayout.removeTopOffset).toBeLessThan(laneLayout.rowHeight / 2);
+  const laneA11y = await page.locator('.midi-automation-row').last().evaluate(row => ({
+    role: row.getAttribute('role'),
+    rowLabel: row.getAttribute('aria-label'),
+    controlLabels: Array.from(row.querySelectorAll('input, select, button'))
+      .map(control => control.getAttribute('aria-label') || '')
+  }));
+  const laneName = laneA11y.rowLabel.replace(/^Modulation lane /, '');
+  expect(laneA11y.role).toBe('group');
+  expect(laneA11y.rowLabel).toBe(`Modulation lane ${laneName}`);
+  expect(laneA11y.controlLabels).toEqual(expect.arrayContaining([
+    `Enable modulation lane ${laneName}`,
+    `${laneName} target`,
+    `${laneName} axis`,
+    `${laneName} operator`,
+    `${laneName} minimum`,
+    `${laneName} maximum`,
+    `${laneName} point beat`,
+    `${laneName} point value`,
+    `Remove modulation lane ${laneName}`
+  ]));
+  await page.locator('.midi-automation-axis-op').last().selectOption('mul');
+  await midi.automationPointBeatFields().last().evaluate(element => {
+    element.value = '2';
+    element.dispatchEvent(new Event('change', { bubbles: true }));
+  });
+  await midi.automationPointValueFields().last().evaluate(element => {
+    element.value = '0.7';
+    element.dispatchEvent(new Event('change', { bubbles: true }));
+  });
+
+  const project = await page.evaluate(() => window.__E2E__.midiGetProject());
+  const runtime = await midi.runtimeConfig();
+  expect(project.tracks[0].velocityScale).toBe(0.5);
+  expect(project.global.velocityRange).toMatchObject({ default: 96, min: 20, max: 110 });
+  expect(project.global.noteRange).toMatchObject({ min: 36, max: 96 });
+  expect(project.global.density).toMatchObject({ velocityBoost: 0.8, windowTicks: 12, durationScale: 0.25 });
+  expect(project.global.limits).toMatchObject({ maxActiveNotes: 24, maxEventsPerTick: 16 });
+  expect(project.global.envelope).toMatchObject({ attack: 1.25, release: 0.75 });
+  expect(project.global.position.viewPan).toBe(true);
+  expect(project.global.position.panRange).toMatchObject({ min: -48, max: 48 });
+  expect(project.global.position.panDeadZonePct).toBe(0.08);
+  expect(project.global.position.timbreRange).toMatchObject({ min: 12, max: 100 });
+  expect(project.global.position.xNoteRange).toMatchObject({ min: -18, max: 18 });
+  expect(project.sources.find(source => source.id === 'sfx-1').mapping.envelope).toMatchObject({
+    attack: 1,
+    decay: 0,
+    sustain: 1,
+    release: 1
+  });
+  expect(project.automation.length).toBeGreaterThan(automationCount);
+  expect(project.automation.at(-1).axisOp).toBe('mul');
+  expect(project.automation.at(-1).points[0]).toEqual({ beat: 2, value: 0.7 });
+  expect(runtime.position.mappings.at(-1).points).toEqual([{ beat: 2, value: 0.7 }]);
+
+  await midi.automationRemoveButtons().last().click();
+  await expect(midi.automationRows()).toHaveCount(automationCount);
+  const afterRemove = await page.evaluate(() => window.__E2E__.midiGetProject());
+  expect(afterRemove.automation.length).toBe(automationCount);
+});
+
+test('MIDI sequencer surfaces source conflicts in the browser and inspector', async ({ page }) => {
+  const midi = await openMidiUi(page);
+  await page.evaluate(() => {
+    const project = window.__E2E__.midiGetProject();
+    const source = project.sources.find(entry => entry.id === 'sfx-1');
+    window.__E2E__.midiDispatchProjectIntent({
+      type: 'project.set',
+      project: {
+        ...project,
+        sources: [
+          ...project.sources,
+          {
+            ...source,
+            id: 'sfx-1-conflict',
+            label: 'Duplicate Skill Select'
+          }
+        ],
+        ui: {
+          ...project.ui,
+          selectedSourceId: 'sfx-1'
+        }
+      }
+    });
+  });
+
+  await expect(midi.conflictRows().first()).toBeVisible();
+  expect(await midi.conflictBadges().count()).toBeGreaterThanOrEqual(2);
+  await expect(midi.conflictRows().first()).toHaveAttribute('aria-label', /Duplicate runtime key/);
+  await expect(midi.conflictSummary()).toContainText('Duplicate runtime key');
+
+  await midi.sourceAssignFilter().selectOption('clean');
+  await expect(midi.conflictRows()).toHaveCount(0);
+  await midi.sourceAssignFilter().selectOption('conflicts');
+  expect(await midi.conflictBadges().count()).toBeGreaterThanOrEqual(2);
+  await expect(midi.conflictRows().first()).toHaveAttribute('aria-label', /Duplicate runtime key/);
+});
+
+test('MIDI sequencer listboxes support keyboard navigation', async ({ page }) => {
+  await openMidiUi(page);
+  const optionId = (kind, id) => `midi-${kind}-option-${String(id).replace(/[^a-zA-Z0-9_-]+/g, '-')}`;
+  const visibleSources = await page.locator('#midiSourceList .midi-source-row').evaluateAll(rows => rows.map(row => row.dataset.sourceId));
+  expect(visibleSources.length).toBeGreaterThan(1);
+
+  await page.locator('#midiSourceList').focus();
+  await page.keyboard.press('ArrowDown');
+  await expect.poll(() => page.evaluate(() => window.__E2E__.midiGetProject().ui.selectedSourceId)).toBe(visibleSources[1]);
+  await expect(page.locator('#midiSourceList')).toHaveAttribute('aria-activedescendant', optionId('source', visibleSources[1]));
+
+  await page.evaluate(() => {
+    window.__E2E__.midiDispatchProjectIntent({ type: 'track.add', track: { id: 'keys', name: 'Keys', channel: 2 } });
+    window.__E2E__.midiDispatchProjectIntent({ type: 'track.add', track: { id: 'pad', name: 'Pad', channel: 3 } });
+    window.__E2E__.midiDispatchProjectIntent({ type: 'track.select', trackId: 'track-1' });
+  });
+  await page.locator('#midiTrackList').focus();
+  await page.keyboard.press('End');
+  await expect.poll(() => page.evaluate(() => window.__E2E__.midiGetProject().ui.selectedTrackId)).toBe('pad');
+  await expect(page.locator('#midiTrackList')).toHaveAttribute('aria-activedescendant', 'midi-track-option-pad');
+
+  await page.evaluate(() => {
+    window.__E2E__.midiDispatchProjectIntent({ type: 'clip.add', clip: { id: 'riff', name: 'Riff', lengthSteps: 4 } });
+    window.__E2E__.midiDispatchProjectIntent({ type: 'clip.add', clip: { id: 'fill', name: 'Fill', lengthSteps: 4 } });
+    window.__E2E__.midiDispatchProjectIntent({ type: 'clip.select', clipId: 'riff' });
+  });
+  await page.locator('#midiClipList').focus();
+  await page.keyboard.press('End');
+  await expect.poll(() => page.evaluate(() => window.__E2E__.midiGetProject().ui.selectedClipId)).toBe('fill');
+  await expect(page.locator('#midiClipList')).toHaveAttribute('aria-activedescendant', 'midi-clip-option-fill');
+});
+
+test('MIDI step grid keyboard navigation preserves the edited field', async ({ page }) => {
+  await openMidiUi(page);
+  await page.evaluate(() => {
+    window.__E2E__.midiDispatchProjectIntent({ type: 'clip.add', clip: { id: 'grid-clip', name: 'Grid Clip', lengthSteps: 8 } });
+    window.__E2E__.midiDispatchProjectIntent({ type: 'clip.select', clipId: 'grid-clip' });
+  });
+  const activeStep = () => page.evaluate(() => {
+    const element = document.activeElement;
+    return {
+      className: element?.className || '',
+      stepIndex: element?.dataset?.stepIndex || '',
+      label: element?.getAttribute?.('aria-label') || ''
+    };
+  });
+
+  await page.locator('.midi-step-note[data-step-index="0"]').focus();
+  await page.keyboard.press('ArrowRight');
+  await expect.poll(activeStep).toMatchObject({ className: 'midi-step-note', stepIndex: '1' });
+  await page.keyboard.press('ArrowDown');
+  await expect.poll(activeStep).toMatchObject({ className: 'midi-step-note', stepIndex: '5' });
+  await page.keyboard.press('End');
+  await expect.poll(activeStep).toMatchObject({ className: 'midi-step-note', stepIndex: '7', label: 'Step 8 note' });
+
+  await page.locator('.midi-step-probability[data-step-index="3"]').focus();
+  await page.keyboard.press('Home');
+  await expect.poll(activeStep).toMatchObject({ className: 'midi-step-probability', stepIndex: '0', label: 'Step 1 probability' });
+  await setFieldValue(page, '.midi-step-probability[data-step-index="0"]', '0.25');
+  await expect.poll(activeStep).toMatchObject({ className: 'midi-step-probability', stepIndex: '0', label: 'Step 1 probability' });
+});
+
+test('MIDI step grid supports rest controls', async ({ page }) => {
+  await openMidiUi(page);
+  await page.evaluate(() => {
+    window.__E2E__.midiDispatchProjectIntent({ type: 'clip.add', clip: { id: 'rest-clip', name: 'Rest Clip', lengthSteps: 4 } });
+    window.__E2E__.midiDispatchProjectIntent({
+      type: 'clip.step.update',
+      clipId: 'rest-clip',
+      stepIndex: 0,
+      patch: {
+        note: 72,
+        velocity: 96,
+        durationTicks: 12,
+        probability: 0.5,
+        hold: true,
+        tie: true
+      }
+    });
+    window.__E2E__.midiDispatchProjectIntent({ type: 'clip.select', clipId: 'rest-clip' });
+  });
+
+  const restButton = page.locator('.midi-step-rest[data-step-index="0"]');
+  await expect(restButton).toHaveAttribute('aria-label', 'Step 1 rest');
+  await restButton.click();
+
+  const step = await page.evaluate(() => {
+    const clip = window.__E2E__.midiGetProject().clips.find(entry => entry.id === 'rest-clip');
+    return clip.steps[0];
+  });
+  expect(step).toMatchObject({
+    index: 0,
+    note: null,
+    velocity: null,
+    durationTicks: null,
+    probability: 1,
+    hold: false,
+    tie: false
+  });
+  await expect(page.locator('.midi-step-note[data-step-index="0"]')).toHaveValue('');
+  await expect(page.locator('.midi-step-velocity[data-step-index="0"]')).toHaveValue('');
+  await expect(page.locator('.midi-step-duration[data-step-index="0"]')).toHaveValue('');
+  await expect(page.locator('.midi-step-hold[data-step-index="0"]')).not.toBeChecked();
+  await expect(page.locator('.midi-step-tie[data-step-index="0"]')).not.toBeChecked();
 });
 
-test('Canvas interaction clears focused MIDI inputs', async ({ page }) => {
-  await page.goto('/');
-  await page.locator('#midiEnabledToggle').check();
-  const bpmInput = page.locator('#midiBpmBase');
-  await bpmInput.focus();
-  await expect(bpmInput).toBeFocused();
-  const canvas = page.locator('#gameCanvas');
-  await canvas.click({ position: { x: 20, y: 20 }, force: true });
-  await expect(bpmInput).not.toBeFocused();
+test('MIDI E2E helpers expose runtime config and UI metrics', async ({ page }) => {
+  const midi = await openMidiUi(page);
+  const before = await midi.uiMetrics();
+
+  await setFieldValue(page, '#midiMappingNote', 77);
+
+  const after = await midi.uiMetrics();
+  const runtime = await midi.runtimeConfig();
+  expect(before).toMatchObject({
+    renderCount: expect.any(Number),
+    queuedRenderCount: expect.any(Number),
+    lastRenderDurationMs: expect.any(Number)
+  });
+  expect(after.renderCount).toBeGreaterThan(before.renderCount);
+  expect(after.lastRenderDurationMs).toBeGreaterThanOrEqual(0);
+  expect(runtime.sfx['1']).toMatchObject({ note: 77, trackId: 'track-1' });
+});
+
+test('MIDI sequencer layout avoids horizontal overflow at desktop, tablet, and phone sizes', async ({ page }) => {
+  for (const viewport of [
+    { width: 1280, height: 900 },
+    { width: 820, height: 1180 },
+    { width: 390, height: 844 }
+  ]) {
+    await page.setViewportSize(viewport);
+    await openMidiUi(page);
+    const metrics = await page.evaluate(() => {
+      const selectors = ['#midiSequencerWorkspace', '#midiSourceBrowser', '#midiSourceList', '#midiTrackWorkspace', '#midiInspector', '#midiConflictSummary', '#midiModulationInspector', '#midiAutomationList'];
+      return selectors.map(selector => {
+        const el = document.querySelector(selector);
+        return {
+          selector,
+          scrollWidth: el?.scrollWidth ?? 0,
+          clientWidth: el?.clientWidth ?? 0
+        };
+      });
+    });
+    for (const metric of metrics) {
+      expect(metric.scrollWidth).toBeLessThanOrEqual(metric.clientWidth + 2);
+    }
+    const stack = await page.evaluate(() => ({
+      sequencer: Number(window.getComputedStyle(document.getElementById('midiSequencerWorkspace')).zIndex),
+      previous: Number(window.getComputedStyle(document.getElementById('levelPrevButton')).zIndex),
+      next: Number(window.getComputedStyle(document.getElementById('levelNextButton')).zIndex)
+    }));
+    expect(stack.sequencer).toBeGreaterThan(stack.previous);
+    expect(stack.sequencer).toBeGreaterThan(stack.next);
+  }
 });
diff --git a/e2e/midi-ui.spec.js-snapshots/midi-left-default-win32.png b/e2e/midi-ui.spec.js-snapshots/midi-left-default-win32.png
deleted file mode 100644
index 8c20bc58..00000000
Binary files a/e2e/midi-ui.spec.js-snapshots/midi-left-default-win32.png and /dev/null differ
diff --git a/e2e/midi-ui.spec.js-snapshots/midi-left-global-fx-win32.png b/e2e/midi-ui.spec.js-snapshots/midi-left-global-fx-win32.png
deleted file mode 100644
index a60e1fe5..00000000
Binary files a/e2e/midi-ui.spec.js-snapshots/midi-left-global-fx-win32.png and /dev/null differ
diff --git a/e2e/midi-ui.spec.js-snapshots/midi-right-adsr-win32.png b/e2e/midi-ui.spec.js-snapshots/midi-right-adsr-win32.png
deleted file mode 100644
index ac8b77c0..00000000
Binary files a/e2e/midi-ui.spec.js-snapshots/midi-right-adsr-win32.png and /dev/null differ
diff --git a/e2e/midi-ui.spec.js-snapshots/midi-right-events-win32.png b/e2e/midi-ui.spec.js-snapshots/midi-right-events-win32.png
deleted file mode 100644
index c929924f..00000000
Binary files a/e2e/midi-ui.spec.js-snapshots/midi-right-events-win32.png and /dev/null differ
diff --git a/e2e/midi-ui.spec.js-snapshots/midi-right-triggers-win32.png b/e2e/midi-ui.spec.js-snapshots/midi-right-triggers-win32.png
deleted file mode 100644
index 3d5bfe35..00000000
Binary files a/e2e/midi-ui.spec.js-snapshots/midi-right-triggers-win32.png and /dev/null differ
diff --git a/e2e/procgen.spec.js b/e2e/procgen.spec.js
index 69b07dc2..9a109298 100644
--- a/e2e/procgen.spec.js
+++ b/e2e/procgen.spec.js
@@ -30,3 +30,74 @@ test('procgen loads and spawns endlessly', async ({ page }) => {
   expect(afterRightmost).toBeGreaterThanOrEqual(initialRightmost);
   expect(after.stage.viewRect.x).toBeGreaterThanOrEqual(initialViewX);
 });
+
+test('procgen exposes debug state and records no-op assist decisions', async ({ page }) => {
+  await page.goto('/procgen.html?e2e=1&seed=debug-state&aiDebug=1');
+  await waitForHarnessReady(page);
+  await page.evaluate(() => window.__E2E__.pause());
+  await page.evaluate(() => window.__E2E__.step(180));
+
+  const state = await page.evaluate(() => window.__E2E__.getState());
+  const procgen = state.procgen;
+
+  expect(procgen.selectedTheme).toEqual(expect.any(String));
+  expect(procgen.seed).not.toBeNull();
+  expect(procgen.generatedEndX).toBeGreaterThan(0);
+  expect(procgen.frontier).toEqual(expect.objectContaining({
+    viableCount: expect.any(Number),
+    rightMovingCount: expect.any(Number)
+  }));
+  expect(procgen.recentChunks.length).toBeGreaterThan(0);
+  expect(procgen.recentPieces.length).toBeGreaterThan(0);
+  expect(procgen.recentPieces.every(piece => piece.theme === procgen.selectedTheme)).toBe(true);
+  expect(procgen.trackingSizes.recentChunks).toBeLessThanOrEqual(64);
+  expect(procgen.trackingSizes.recentPieces).toBeLessThanOrEqual(128);
+  expect(procgen.trackingSizes.recentAssists).toBeLessThanOrEqual(32);
+
+  await expect.poll(async () => {
+    await page.evaluate(() => window.__E2E__.step(30));
+    return page.evaluate(() => {
+      const assists = window.__E2E__?.getState?.()?.procgen?.recentAssists || [];
+      return assists.some(assist => (
+        assist.type === 'noop' &&
+        (assist.reason === 'traversable' || assist.reason === 'safe-drop')
+      ));
+    });
+  }).toBe(true);
+});
+
+test('procgen exposes solver-verified gap certificates for fixed seeds', async ({ page }) => {
+  await page.goto('/procgen.html?e2e=1&seed=certificate-e2e&aiDebug=1&gapChance=1&gapMinWidth=5&gapMaxWidth=5&recentCertificateLimit=8');
+  await waitForHarnessReady(page);
+  await page.evaluate(() => window.__E2E__.pause());
+
+  await expect.poll(async () => {
+    await page.evaluate(() => window.__E2E__.step(120));
+    return page.evaluate(() => {
+      const certificates = window.__E2E__?.getState?.()?.procgen?.recentCertificates || [];
+      return certificates.some(entry => (
+        entry.challengeType === 'bridge-gap' &&
+        entry.decision === 'accept' &&
+        entry.resultType === 'solved'
+      ));
+    });
+  }, { timeout: 10000 }).toBe(true);
+
+  const procgen = await page.evaluate(() => window.__E2E__.getState().procgen);
+  const accepted = procgen.recentCertificates.find(entry => (
+    entry.challengeType === 'bridge-gap' &&
+    entry.decision === 'accept' &&
+    entry.resultType === 'solved'
+  ));
+
+  expect(accepted).toEqual(expect.objectContaining({
+    expectedSkill: 'builder',
+    width: 5
+  }));
+  expect(procgen.recentChunks.some(entry => (
+    entry.type === 'gap' &&
+    entry.certificateDecision === 'accept' &&
+    entry.certificateResultType === 'solved'
+  ))).toBe(true);
+  expect(procgen.trackingSizes.recentCertificates).toBeLessThanOrEqual(8);
+});
diff --git a/e2e/service-worker.spec.js b/e2e/service-worker.spec.js
index f7536827..68214c58 100644
--- a/e2e/service-worker.spec.js
+++ b/e2e/service-worker.spec.js
@@ -43,12 +43,19 @@ test.beforeEach(async ({ page }) => {
   await installExternalAssetStubs(page);
 });
 
+function expectRootServiceWorkerScope(scope, pageUrl) {
+  const scopeUrl = new URL(scope);
+  const originUrl = new URL(pageUrl);
+  expect(scopeUrl.origin).toBe(originUrl.origin);
+  expect(scopeUrl.pathname).toBe('/');
+}
+
 test('Service worker controls the game page and checks for updates', async ({ page }, testInfo) => {
-  await page.goto('/');
+  await page.goto('/?sw=1');
   const result = await ensureServiceWorkerControls(page);
   expect(result).not.toBeNull();
   expect(result?.state).toBeTruthy();
-  expect(result?.scope).toContain('localhost');
+  expectRootServiceWorkerScope(result?.scope || '', page.url());
   expect(result?.hasRegistrationAfterReload).toBe(true);
   if (!result?.registeredByApp) {
     testInfo.annotations.push({
@@ -58,17 +65,19 @@ test('Service worker controls the game page and checks for updates', async ({ pa
   }
 });
 
-test('Service worker controls the editor page and checks for updates', async ({ page }, testInfo) => {
+test('Editor page bypasses active service workers', async ({ page }) => {
+  await page.goto('/?sw=1');
+  const gameResult = await ensureServiceWorkerControls(page);
+  expect(gameResult).not.toBeNull();
+  expect(gameResult?.state).toBeTruthy();
+  expectRootServiceWorkerScope(gameResult?.scope || '', page.url());
+  expect(gameResult?.hasRegistrationAfterReload).toBe(true);
+
   await page.goto('/editor.html');
-  const result = await ensureServiceWorkerControls(page);
-  expect(result).not.toBeNull();
-  expect(result?.state).toBeTruthy();
-  expect(result?.scope).toContain('localhost');
-  expect(result?.hasRegistrationAfterReload).toBe(true);
-  if (!result?.registeredByApp) {
-    testInfo.annotations.push({
-      type: 'warning',
-      description: 'Service worker was registered manually during the smoke test.'
+  await expect.poll(async () => {
+    return await page.evaluate(async () => {
+      const registration = await navigator.serviceWorker.getRegistration();
+      return !!registration;
     });
-  }
+  }).toBe(false);
 });
diff --git a/e2e/tools/midi-explore.spec.js b/e2e/tools/midi-explore.spec.js
deleted file mode 100644
index 323fd0dd..00000000
--- a/e2e/tools/midi-explore.spec.js
+++ /dev/null
@@ -1,265 +0,0 @@
-import { test } from '@playwright/test';
-import { installExternalAssetStubs } from '../helpers/externalAssets.js';
-import {
-  collectPageErrors,
-  enableWebMidi,
-  getEventRowIndexMap,
-  getMidiErrorDisplay,
-  MIDI_SELECTORS,
-  openFirstMidiEvent,
-  openMidiUi,
-  readMidiOverrides,
-  rowByLabel
-} from './midiUiSnippets.js';
-
-const IGNORED_MIDI_WARNINGS = [
-  /permission to use web midi api was not granted/i,
-  /webmidi permission denied/i
-];
-
-const isIgnoredMidiWarning = (text) => {
-  if (!text) return false;
-  return IGNORED_MIDI_WARNINGS.some(pattern => pattern.test(text));
-};
-
-const filterMidiWarnings = (text) => {
-  if (!text) return '';
-  const lines = text.split(/\r?\n/).map(line => line.trim()).filter(Boolean);
-  return lines.filter(line => !isIgnoredMidiWarning(line)).join('\n');
-};
-
-test('Explore MIDI UI mappings', async ({ page }) => {
-  const errors = collectPageErrors(page);
-  const issues = [];
-  let crashed = false;
-  page.on('crash', () => {
-    crashed = true;
-    issues.push('Page crashed during MIDI init.');
-  });
-  page.on('request', (request) => {
-    if (request.url().includes('sneakyness.com')) {
-      console.log('stats request:', request.url());
-    }
-  });
-  page.on('requestfailed', (request) => {
-    if (request.url().includes('sneakyness.com')) {
-      console.log('stats request failed:', request.url(), request.failure());
-    }
-  });
-  await installExternalAssetStubs(page);
-  await page.context().grantPermissions(['midi']);
-
-  await page.addInitScript(() => {
-    try {
-      window.localStorage?.setItem?.('lemmings.midi.enabled', 'true');
-      window.localStorage?.removeItem?.('lemmings.midi.panelCollapsed');
-    } catch (error) {}
-  });
-  await page.goto('/');
-  const webMidiStatus = await enableWebMidi(page);
-  if (webMidiStatus.ok || !isIgnoredMidiWarning(webMidiStatus.reason)) {
-    console.log('webmidi enable result:', webMidiStatus);
-  }
-  if (!webMidiStatus.ok && !isIgnoredMidiWarning(webMidiStatus.reason)) {
-    issues.push(`WebMIDI enable failed: ${webMidiStatus.reason || 'unknown'}`);
-  }
-  if (crashed) {
-    console.log('midi exploration issues:', JSON.stringify(issues, null, 2));
-    return;
-  }
-
-  try {
-    const readyState = await page.evaluate(() => document.readyState);
-    const toggleCount = await page.locator('#midiEnabledToggle').count();
-    console.log('ready state:', readyState, 'toggle count:', toggleCount);
-  } catch (error) {
-    issues.push(`Unable to read MIDI toggle state: ${error?.message || error}`);
-  }
-
-  try {
-    await openMidiUi(page, { navigate: false });
-  } catch (error) {
-    issues.push(`Unable to open MIDI UI: ${error?.message || error}`);
-    console.log('midi exploration issues:', JSON.stringify(issues, null, 2));
-    return;
-  }
-  const webdriverFlag = await page.evaluate(() => navigator.webdriver);
-  console.log('navigator.webdriver:', webdriverFlag);
-  const externalResources = await page.evaluate(() => {
-    const origin = window.location.origin;
-    const resources = performance.getEntriesByType('resource').map(entry => entry.name);
-    return resources.filter(name => !name.startsWith(origin));
-  });
-  if (externalResources.length) {
-    console.log('external resources:', JSON.stringify(externalResources, null, 2));
-  }
-  const errorDisplay = await getMidiErrorDisplay(page);
-  const filteredErrorDisplay = filterMidiWarnings(errorDisplay);
-  if (filteredErrorDisplay) {
-    issues.push(`MIDI error display: ${filteredErrorDisplay}`);
-  }
-
-  const keySelect = page.locator(MIDI_SELECTORS.keySelect);
-  const scaleSelect = page.locator(MIDI_SELECTORS.scaleSelect);
-  const keyCount = await keySelect.locator('option').count();
-  const scaleCount = await scaleSelect.locator('option').count();
-  if (keyCount < 1) issues.push('Key select has no options.');
-  if (scaleCount < 1) issues.push('Scale select has no options.');
-
-  if (keyCount > 1) {
-    await keySelect.selectOption('1');
-    const overrides = await readMidiOverrides(page);
-    if (overrides?.scale?.root !== 1) {
-      issues.push('Key select did not update scale.root override.');
-    }
-  }
-
-  if (scaleCount > 1) {
-    const nextScale = await scaleSelect.locator('option').nth(1).getAttribute('value');
-    if (nextScale) {
-      await scaleSelect.selectOption(nextScale);
-      const overrides = await readMidiOverrides(page);
-      if (overrides?.scale?.name !== nextScale) {
-        issues.push('Scale select did not update scale.name override.');
-      }
-    }
-  }
-
-  const { details, sfxId } = await openFirstMidiEvent(page);
-  if (!sfxId) issues.push('Unable to read an SFX id from the first MIDI event.');
-
-  const rowIndexMap = await getEventRowIndexMap(details);
-  const modeSelect = rowByLabel(details, rowIndexMap, 'Mode').locator('select');
-  const keyRowSelect = rowByLabel(details, rowIndexMap, 'Key').locator('select');
-  const noteOctaveInput = rowByLabel(details, rowIndexMap, 'Octave').locator('input[type="number"]');
-  const degreeInput = rowByLabel(details, rowIndexMap, 'Degree').locator('input[type="number"]');
-  const scaleOctaveInput = rowByLabel(details, rowIndexMap, 'Scale octave').locator('input[type="number"]');
-  const chordSelect = rowByLabel(details, rowIndexMap, 'Chord').locator('select');
-  const arpToggle = rowByLabel(details, rowIndexMap, 'Arp').locator('input[type="checkbox"]');
-  const arpMode = rowByLabel(details, rowIndexMap, 'Arp mode').locator('select');
-  const arpLength = rowByLabel(details, rowIndexMap, 'Arp length').locator('input[type="number"]');
-
-  const ensureVisible = async (locator, label) => {
-    const visible = await locator.isVisible().catch(() => false);
-    if (!visible) {
-      issues.push(`${label} is not visible in event details.`);
-    }
-    return visible;
-  };
-  const trySelectOption = async (locator, value, label) => {
-    try {
-      await locator.selectOption(value, { timeout: 1000 });
-      return true;
-    } catch (error) {
-      issues.push(`${label} select not visible/enabled for option "${value}".`);
-      return false;
-    }
-  };
-
-  if ((await modeSelect.count()) < 1) issues.push('Mode select missing from event details.');
-  if ((await chordSelect.count()) < 1) issues.push('Chord select missing from event details.');
-  if ((await arpMode.count()) < 1) issues.push('Arp mode select missing from event details.');
-
-  if ((await modeSelect.count()) > 0 && sfxId) {
-    const modeSelected = await trySelectOption(modeSelect, 'note', 'Mode');
-    if (!modeSelected) {
-      if (issues.length) {
-        console.log('midi exploration issues:', JSON.stringify(issues, null, 2));
-      }
-      return;
-    }
-    if (await keyRowSelect.isDisabled()) issues.push('Key select disabled in note mode.');
-    if (await noteOctaveInput.isDisabled()) issues.push('Octave disabled in note mode.');
-    if (!(await degreeInput.isDisabled())) issues.push('Degree enabled in note mode.');
-    if (!(await scaleOctaveInput.isDisabled())) issues.push('Scale octave enabled in note mode.');
-    if (!(await chordSelect.isDisabled())) issues.push('Chord enabled in note mode.');
-
-    await trySelectOption(keyRowSelect, '1', 'Key');
-    if (!(await ensureVisible(noteOctaveInput, 'Octave input'))) {
-      if (issues.length) {
-        console.log('midi exploration issues:', JSON.stringify(issues, null, 2));
-      }
-      return;
-    }
-    await noteOctaveInput.fill('4');
-    await noteOctaveInput.dispatchEvent('change');
-
-    const noteEntry = await page.evaluate((id) => {
-      return window.lemmingsMidiOverrides?.sfx?.[id] ?? null;
-    }, sfxId);
-    if (noteEntry?.note !== 49) {
-      issues.push('Note selection did not update overrides (expected note 49).');
-    }
-
-    const chordModeSelected = await trySelectOption(modeSelect, 'chord', 'Mode');
-    if (!chordModeSelected) {
-      if (issues.length) {
-        console.log('midi exploration issues:', JSON.stringify(issues, null, 2));
-      }
-      return;
-    }
-    if (!(await keyRowSelect.isDisabled())) issues.push('Key select enabled in chord mode.');
-    if (!(await noteOctaveInput.isDisabled())) issues.push('Octave enabled in chord mode.');
-    if (await degreeInput.isDisabled()) issues.push('Degree disabled in chord mode.');
-    if (await scaleOctaveInput.isDisabled()) issues.push('Scale octave disabled in chord mode.');
-    if (await chordSelect.isDisabled()) issues.push('Chord disabled in chord mode.');
-
-    if (!(await ensureVisible(degreeInput, 'Degree input'))
-      || !(await ensureVisible(scaleOctaveInput, 'Scale octave input'))) {
-      if (issues.length) {
-        console.log('midi exploration issues:', JSON.stringify(issues, null, 2));
-      }
-      return;
-    }
-    await degreeInput.fill('2');
-    await degreeInput.dispatchEvent('change');
-    await scaleOctaveInput.fill('4');
-    await scaleOctaveInput.dispatchEvent('change');
-    await trySelectOption(chordSelect, 'sus4', 'Chord');
-    if (await ensureVisible(arpToggle, 'Arp toggle')) {
-      await arpToggle.check();
-    }
-    await trySelectOption(arpMode, 'down', 'Arp mode');
-    await arpLength.fill('5');
-    await arpLength.dispatchEvent('change');
-
-    const chordEntry = await page.evaluate((id) => {
-      return window.lemmingsMidiOverrides?.sfx?.[id] ?? null;
-    }, sfxId);
-    if (chordEntry?.degree !== 2 || chordEntry?.octave !== 4) {
-      issues.push('Chord degree/octave did not update overrides.');
-    }
-    if (chordEntry?.chord?.type !== 'sus4') {
-      issues.push('Chord type did not update overrides.');
-    }
-    if (!chordEntry?.arp?.enabled || chordEntry?.arp?.mode !== 'down' || chordEntry?.arp?.length !== 5) {
-      issues.push('Arp settings did not update overrides.');
-    }
-  }
-
-  await page.locator('button[data-tab-target="midiTabTriggers"]').click();
-  const triggerCount = await page.locator('#midiTriggerList details').count();
-  if (triggerCount < 1) issues.push('Trigger list is empty.');
-
-  await page.locator('button[data-tab-target="midiTabAdsr"]').click();
-  const adsrTargetCount = await page.locator('#midiEnvTarget option').count();
-  if (adsrTargetCount < 1) issues.push('ADSR target list is empty.');
-  const adsrAttack = page.locator('#midiEnvAttack');
-  if ((await adsrAttack.count()) > 0) {
-    await adsrAttack.fill('1.5');
-    await adsrAttack.dispatchEvent('change');
-    const overrides = await readMidiOverrides(page);
-    if (overrides?.envelope?.attack !== 1.5) {
-      issues.push('ADSR attack did not update overrides.');
-    }
-  }
-
-  if (errors.length) {
-    issues.push(`Console/page errors: ${JSON.stringify(errors)}`);
-  }
-  if (issues.length) {
-    console.log('midi exploration issues:', JSON.stringify(issues, null, 2));
-  } else {
-    console.log('midi exploration issues: none');
-  }
-});
diff --git a/e2e/tools/midiUiSnippets.js b/e2e/tools/midiUiSnippets.js
deleted file mode 100644
index 7cf478fe..00000000
--- a/e2e/tools/midiUiSnippets.js
+++ /dev/null
@@ -1,116 +0,0 @@
-export const MIDI_SELECTORS = {
-  enableToggle: '#midiEnabledToggle',
-  errorDisplay: '#errorDisplay',
-  eventList: '#midiEventList details',
-  keySelect: '#midiKeySelect',
-  scaleSelect: '#midiScaleSelect'
-};
-
-export const collectPageErrors = (page) => {
-  const errors = [];
-  const ignored = [
-    /SSL certificate error occurred when fetching the script\./i
-  ];
-  page.on('pageerror', (error) => errors.push(error.message));
-  page.on('console', (message) => {
-    if (message.type() === 'error') {
-      const location = message.location();
-      const detail = location?.url
-        ? `${message.text()} (${location.url}:${location.lineNumber || 0})`
-        : message.text();
-      if (!ignored.some(pattern => pattern.test(detail))) {
-        errors.push(detail);
-      }
-    }
-  });
-  page.on('requestfailed', (request) => {
-    const failure = request.failure();
-    if (failure?.errorText) {
-      const detail = `requestfailed: ${failure.errorText} (${request.url()})`;
-      if (!ignored.some(pattern => pattern.test(detail))) {
-        errors.push(detail);
-      }
-    }
-  });
-  return errors;
-};
-
-export const readMidiOverrides = (page) => {
-  return page.evaluate(() => window.lemmingsMidiOverrides);
-};
-
-export const enableWebMidi = async (page) => {
-  return page.evaluate(async () => {
-    try {
-      if (!window.WebMidi) {
-        return { ok: false, reason: 'WebMidi missing' };
-      }
-      if (window.WebMidi.enabled) {
-        return { ok: true, enabled: true };
-      }
-      await window.WebMidi.enable();
-      return { ok: true, enabled: true };
-    } catch (error) {
-      return {
-        ok: false,
-        reason: error?.message || String(error)
-      };
-    }
-  });
-};
-
-export const openMidiUi = async (page, { url = '/', navigate = true } = {}) => {
-  if (navigate) {
-    await page.goto(url);
-  }
-  await page.waitForSelector(MIDI_SELECTORS.enableToggle, { state: 'attached' });
-  const toggle = page.locator(MIDI_SELECTORS.enableToggle);
-  if (await toggle.isVisible() && !(await toggle.isChecked())) {
-    await toggle.check();
-  }
-  await page.waitForSelector(MIDI_SELECTORS.eventList, { state: 'attached' });
-  await page.waitForSelector('#controlRight', { state: 'visible' });
-};
-
-export const getMidiErrorDisplay = async (page) => {
-  const text = await page.locator(MIDI_SELECTORS.errorDisplay).innerText();
-  return text.trim();
-};
-
-export const openFirstMidiEvent = async (page) => {
-  const details = page.locator(MIDI_SELECTORS.eventList).first();
-  await details.waitFor({ state: 'attached' });
-  await details.locator('summary').waitFor({ state: 'visible' });
-  await details.locator('summary').click();
-  await details.evaluate((node) => {
-    node.open = true;
-  });
-  const sfxId = await page.evaluate(() => {
-    const entry = document.querySelector('#midiEventList details');
-    const summary = entry?.querySelector('summary');
-    const text = summary?.textContent || '';
-    const match = text.match(/#(\d+)/);
-    if (match) return match[1];
-    const fallback = text.match(/SFX\s+(\d+)/i);
-    return fallback ? fallback[1] : null;
-  });
-  return { details, sfxId };
-};
-
-export const getEventRowIndexMap = async (details) => {
-  return details.evaluate((node) => {
-    const rows = Array.from(node.querySelectorAll('label'));
-    return rows.reduce((acc, row, idx) => {
-      const text = row.querySelector('span')?.textContent?.trim();
-      if (text) acc[text] = idx;
-      return acc;
-    }, {});
-  });
-};
-
-export const rowByLabel = (details, indexMap, label) => {
-  const index = indexMap[label];
-  return typeof index === 'number'
-    ? details.locator('label').nth(index)
-    : details.locator('label').first().locator('select').locator('nonexistent');
-};
diff --git a/e2e/visual-capture.spec.js b/e2e/visual-capture.spec.js
new file mode 100644
index 00000000..f0f449f1
--- /dev/null
+++ b/e2e/visual-capture.spec.js
@@ -0,0 +1,90 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { expect, test } from '@playwright/test';
+import { installExternalAssetStubs } from './helpers/externalAssets.js';
+import {
+  DEFAULT_CAPTURE_ROOT,
+  captureTargets,
+  resolveCaptureTargets,
+  runVisualProbes
+} from './helpers/visualCapture.js';
+
+const waitForHarnessReady = async (page) => {
+  await page.waitForFunction(() => window.__E2E__?.getState?.()?.ready === true);
+};
+
+const isInside = (root, filePath) => {
+  const relative = path.relative(path.resolve(root), path.resolve(filePath));
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+};
+
+test.beforeEach(async ({ page }) => {
+  await installExternalAssetStubs(page);
+  await page.addInitScript(() => {
+    try {
+      window.localStorage?.clear?.();
+    } catch (error) {}
+  });
+});
+
+test('captures selector, page rect, runtime rect, and viewport targets under temp', async ({ page }) => {
+  const outDir = path.join(DEFAULT_CAPTURE_ROOT, `smoke-${Date.now()}`);
+  await fs.rm(outDir, { recursive: true, force: true });
+  await page.goto('/?e2e=1');
+  await waitForHarnessReady(page);
+  await page.evaluate(() => window.__E2E__?.pause?.());
+
+  const result = await captureTargets(page, [
+    { name: 'level-selects', type: 'selector', selector: '#levelSelects' },
+    { name: 'top-left-page-rect', type: 'pageRect', rect: { x: 0, y: 0, width: 160, height: 120 } },
+    { name: 'runtime-canvas', type: 'runtimeRect', id: 'canvas' },
+    { name: 'viewport', type: 'viewport' }
+  ], {
+    outDir,
+    route: '/'
+  });
+
+  expect(result.captures).toHaveLength(4);
+  for (const capture of result.captures) {
+    expect(isInside(DEFAULT_CAPTURE_ROOT, capture.path)).toBe(true);
+    const stat = await fs.stat(capture.path);
+    expect(stat.size).toBeGreaterThan(0);
+  }
+});
+
+test('reports missing selectors with route and nearby page selectors', async ({ page }) => {
+  await page.goto('/?e2e=1');
+  await waitForHarnessReady(page);
+  let message = '';
+  try {
+    await resolveCaptureTargets(page, [
+      { name: 'missing-control', type: 'selector', selector: '#missingCaptureTarget' }
+    ], { route: '/' });
+  } catch (error) {
+    message = error.message;
+  }
+  expect(message).toContain('#missingCaptureTarget');
+  expect(message).toContain('Route: /');
+  expect(message).toContain('Target: target=missing-control type=selector');
+  expect(message).toContain('Nearby page ids/classes:');
+});
+
+test('returns overflow probe output for a known selector', async ({ page }) => {
+  await page.goto('/?e2e=1');
+  await page.evaluate(() => {
+    const probe = document.createElement('div');
+    probe.id = 'captureOverflowProbe';
+    probe.style.cssText = 'position:absolute;left:0;top:0;width:20px;height:10px;overflow:hidden;';
+    probe.innerHTML = '<span style="display:inline-block;width:120px;">Overflow probe text</span>';
+    document.body.appendChild(probe);
+  });
+  const result = await runVisualProbes(page, [
+    {
+      name: 'overflow-probe',
+      selector: '#captureOverflowProbe',
+      required: true,
+      checks: ['horizontalOverflow', 'clippedText']
+    }
+  ]);
+  expect(result.failures.some(issue => issue.code === 'horizontalOverflow')).toBe(true);
+});
diff --git a/editor.html b/editor.html
index 9ee50c93..6f061a6b 100644
--- a/editor.html
+++ b/editor.html
@@ -3,6 +3,8 @@
 <head>
   <title>Lemmings Editor</title>
   <meta charset="UTF-8" />
+  <meta name="lemmings-analytics" content="runtime" />
+  <meta name="lemmings-analytics-endpoint" content="" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <link rel="icon" type="image/png" href="img/favicon.png" />
   <link type="text/css" rel="stylesheet" href="css/editor.css">
@@ -35,7 +37,7 @@
         <button class="secondary" id="editorRedo" type="button" title="Redo the last undone change.">Redo</button>
         <span id="editorDirtyStatus" class="dirty-indicator" title="Shows whether there are unsaved changes.">Saved</span>
         <button id="editorSavedExport" type="button" title="Export the current level in editor format (.nxlv).">Export</button>
-        <button id="editorSavedExportClassic" type="button" title="Export the current level as a classic LVL file.">Export LVL</button>
+        <button id="editorSavedExportClassic" type="button" title="Export a lossy classic LVL file; use NXLV to preserve editor and NeoLemmix data.">Export LVL</button>
         <button class="secondary" id="editorSavedImport" type="button" title="Import a saved editor level (.nxlv).">Import</button>
         <button class="secondary" id="editorSavedImportClassic" type="button" title="Import a classic LVL file into the editor.">Import LVL</button>
         <button class="secondary" id="editorPlaytestToggle" type="button" title="Toggle playtest mode to run the level.">Playtest</button>
@@ -47,11 +49,12 @@
     <div class="editor-main">
       <aside class="editor-panel">
         <div class="panel-title">Tools</div>
-        <div class="tool-grid" id="editorToolList">
+        <div class="tool-grid" id="editorToolList" role="group" aria-label="Editor tools">
           <button type="button" data-tool="select" data-tooltip="Select and move existing items.">Select</button>
           <button type="button" data-tool="terrain" data-tooltip="Place terrain pieces.">Terrain</button>
           <button type="button" data-tool="gadget" data-tooltip="Place interactive objects.">Object</button>
           <button type="button" data-tool="trigger" data-tooltip="Place trigger regions.">Trigger</button>
+          <button type="button" data-tool="midi-flag" data-tooltip="Place MIDI flag triggers.">MIDI Flag</button>
           <button type="button" data-tool="entrance" data-tooltip="Place entrances (spawners).">Entrance</button>
           <button type="button" data-tool="exit" data-tooltip="Place exits.">Exit</button>
           <button type="button" data-tool="steel" data-tooltip="Draw steel areas.">Steel</button>
@@ -79,18 +82,19 @@
 
         <div class="panel-title">Palette</div>
         <div class="palette-block">
-          <div class="palette-tabs" id="editorPaletteTabs" title="Switch between terrain, object, and trigger palettes.">
-            <button type="button" data-tab="terrain" class="active" title="Show terrain palette.">Terrain</button>
-            <button type="button" data-tab="gadgets" title="Show object palette.">Objects</button>
-            <button type="button" data-tab="triggers" title="Show trigger palette.">Triggers</button>
+          <div class="palette-tabs" id="editorPaletteTabs" role="group" aria-label="Palette categories" title="Switch between terrain, object, and trigger palettes.">
+            <button type="button" data-tab="terrain" class="active" aria-pressed="true" title="Show terrain palette.">Terrain</button>
+            <button type="button" data-tab="gadgets" aria-pressed="false" title="Show object palette.">Objects</button>
+            <button type="button" data-tab="triggers" aria-pressed="false" title="Show trigger palette.">Triggers</button>
           </div>
           <div class="palette-toolbar">
             <input id="editorPaletteSearch" type="text" placeholder="Filter pieces" title="Filter palette entries by name or id." />
             <div class="palette-view-toggle" role="group" aria-label="Palette view mode">
-              <button type="button" id="editorPaletteViewList" class="active" title="List view">List</button>
-              <button type="button" id="editorPaletteViewGrid" title="Grid view">Grid</button>
+              <button type="button" id="editorPaletteViewList" class="active" aria-pressed="true" title="List view">List</button>
+              <button type="button" id="editorPaletteViewGrid" aria-pressed="false" title="Grid view">Grid</button>
             </div>
           </div>
+          <div class="palette-recent" id="editorPaletteRecent" role="group" aria-label="Recently used palette pieces" hidden></div>
           <div class="palette-list" id="editorPaletteTerrain"></div>
           <div class="palette-list" id="editorPaletteGadgets" hidden></div>
           <div class="palette-list" id="editorPaletteTriggers" hidden></div>
@@ -99,7 +103,7 @@
 
       <section class="editor-canvas-panel">
         <div class="canvas-wrap">
-          <canvas id="editorCanvas" width="800" height="480"></canvas>
+          <canvas id="editorCanvas" width="800" height="480" aria-label="Level editor canvas"></canvas>
         </div>
         <div class="status-strip">
           <span id="editorCursorStatus">X:— Y:—</span>
@@ -140,6 +144,14 @@
         </div>
         <details class="selection-flags" id="editorSelectionFlags">
           <summary title="Toggle placement flags for the selected item.">Placement Flags</summary>
+          <label class="control-row" title="Emit a dedicated MIDI trigger event for this gadget trigger area.">
+            MIDI Flag
+            <input id="editorSelMidiFlag" type="checkbox" title="Emit a dedicated MIDI trigger event for this gadget trigger area." />
+          </label>
+          <label class="control-row" title="MIDI flag id used for trigger mapping in the MIDI sequencer.">
+            MIDI Flag ID
+            <input id="editorSelMidiFlagId" type="number" min="1" max="9999" title="MIDI flag id used for trigger mapping in the MIDI sequencer." />
+          </label>
           <label class="control-row" title="Flip the selection horizontally.">
             Flip H
             <input id="editorSelFlipH" type="checkbox" title="Flip the selection horizontally." />
@@ -168,18 +180,60 @@
             <button class="editor-button" id="editorSelectionMoveBackward" type="button" title="Move selection backward by one layer.">Move Back</button>
             <button class="editor-button" id="editorSelectionSendBack" type="button" title="Send selection to back (bottom layer).">Send to Back</button>
           </div>
-          <button class="editor-button" id="editorDeleteSelection" type="button" title="Delete the current selection.">Delete Object</button>
+          <div class="selection-order">
+            <button class="editor-button" id="editorSelectionAlignLeft" type="button" title="Align selected items to the left edge.">Align Left</button>
+            <button class="editor-button" id="editorSelectionAlignCenter" type="button" title="Align selected items to the horizontal center.">Align Center</button>
+            <button class="editor-button" id="editorSelectionAlignRight" type="button" title="Align selected items to the right edge.">Align Right</button>
+            <button class="editor-button" id="editorSelectionDistributeX" type="button" title="Distribute selected items evenly across X.">Distribute X</button>
+            <button class="editor-button" id="editorSelectionAlignTop" type="button" title="Align selected items to the top edge.">Align Top</button>
+            <button class="editor-button" id="editorSelectionAlignMiddle" type="button" title="Align selected items to the vertical center.">Align Middle</button>
+            <button class="editor-button" id="editorSelectionAlignBottom" type="button" title="Align selected items to the bottom edge.">Align Bottom</button>
+            <button class="editor-button" id="editorSelectionDistributeY" type="button" title="Distribute selected items evenly across Y.">Distribute Y</button>
+          </div>
+          <label class="control-row compact-row" title="Replace selected terrain/object pieces with this id.">
+            Replace Piece
+            <div class="inline-controls">
+              <input id="editorSelectionReplacePiece" type="number" title="Piece id to apply to the current selection." />
+              <button class="editor-button" id="editorSelectionReplaceApply" type="button" title="Apply replacement piece id to selected terrain/object entries.">Apply</button>
+            </div>
+          </label>
+          <label class="control-row compact-row" title="Randomize selected terrain/object entries from a piece-id list.">
+            Randomize Pieces
+            <div class="inline-controls">
+              <input id="editorSelectionRandomPieces" type="text" placeholder="1,2,3" title="Comma-separated piece ids to randomize from." />
+              <input id="editorSelectionRandomSeed" type="number" placeholder="seed" title="Optional seed for deterministic randomization." />
+              <label class="inline-toggle" title="Only choose pieces with matching width and height.">
+                <input id="editorSelectionRandomSameSize" type="checkbox" />
+                Same size
+              </label>
+              <button class="editor-button" id="editorSelectionRandomApply" type="button" title="Randomize selected terrain/object pieces using these ids.">Apply</button>
+            </div>
+          </label>
+          <label class="control-row compact-row" title="Scale selected entries around their selection center.">
+            Transform
+            <div class="inline-controls">
+              <input id="editorSelectionScaleX" type="number" value="1" step="0.05" title="Horizontal scale factor." />
+              <input id="editorSelectionScaleY" type="number" value="1" step="0.05" title="Vertical scale factor." />
+              <button class="editor-button" id="editorSelectionTransformApply" type="button" title="Scale the current selection group around its center.">Apply</button>
+            </div>
+          </label>
+          <button class="editor-button" id="editorDeleteSelection" type="button" title="Delete the current selection.">Delete Selection</button>
         </div>
 
         <div class="panel-title">Validation</div>
-        <div class="issue-list" id="editorIssuesList"></div>
+        <div class="validation-toolbar">
+          <button class="editor-button" id="editorSolvabilityCheck" type="button" title="Run a bounded advisory solvability check.">Check Solvability</button>
+          <button class="editor-button" id="editorValidationReportExport" type="button" title="Export current validation issues and pack consistency checks as JSON.">Export Report</button>
+          <span id="editorSolvabilityStatus" class="validation-status" data-status="idle" aria-live="polite">Solvability not checked</span>
+        </div>
+        <div class="issue-list" id="editorIssuesList" role="list" aria-live="polite"></div>
       </aside>
     </div>
   </div>
   <div id="editorShortcutOverlay" class="shortcut-overlay" aria-hidden="true">
-    <div class="shortcut-overlay__panel" role="dialog" aria-modal="true">
+    <div class="shortcut-overlay__panel" role="dialog" aria-modal="true" aria-labelledby="editorShortcutOverlayTitle">
       <div class="shortcut-overlay__header">
-        <div class="shortcut-overlay__title">Editor Shortcuts</div>
+        <div class="shortcut-overlay__title" id="editorShortcutOverlayTitle">Editor Shortcuts</div>
         <button type="button" class="shortcut-overlay__close" title="Close the shortcut overlay.">Close</button>
       </div>
       <div class="shortcut-overlay__content"></div>
diff --git a/editor_audit_and_procgen_enhancements.md b/editor_audit_and_procgen_enhancements.md
deleted file mode 100644
index 1065b120..00000000
--- a/editor_audit_and_procgen_enhancements.md
+++ /dev/null
@@ -1,428 +0,0 @@
-# Level Editor Audit + Procgen Enhancement Plan (LemmingsJS-MIDI)
-
-This document covers three things:
-
-1) **Editor audit**: bugs, errors, mistakes, mismatches, missing features, and quality-of-life improvements  
-2) **Editor ↔ engine parity gaps**: places where the editor exposes properties that the runtime does not honor  
-3) **Procgen mode upgrade plan**: terrain-pack-driven generation, triggers, decoration, and richer lemming behaviors (AI-driven skill use)
-
----
-
-## 1) Editor audit
-
-### A. High-impact bugs / correctness gaps
-
-- **`$TERRAINGROUP` is parsed and preserved… but never loaded into the preview/runtime**
-  - `NxlvParser` populates `EditorLevel.terrainGroups`, and `NxlvWriter` can write them back out.
-  - However `loadEditorLevel()` / `EditorLevelLoader.js` only reads:
-    - `editorLevel.terrains`
-    - `editorLevel.gadgets`
-    - `editorLevel.steel`
-  - Result:
-    - Levels that rely on `terrainGroups` will appear incomplete in preview/playtest.
-    - Export-to-classic (`.lvl`) will silently omit grouped terrain.
-  - **Fix**: extend `EditorLevelLoader.createLevelElements()` to also flatten `terrainGroups` into elements (while preserving order semantics), or explicitly block/flag unsupported sections via validation.
-
-- **Several selection inspector fields do not affect preview or classic export**
-  - In `editor.html`, the selection inspector supports:
-    - `Rotate`, `Flip H`, `One Way`, and explicit `Width`/`Height`
-  - But `EditorLevelLoader.createDrawProperties()` only maps:
-    - `FLIP_VERTICAL`, `NO_OVERWRITE`, `ERASE`
-  - The renderer (`render/GroundRenderer.js`) also only supports vertical flip + overwrite/erase flags.
-  - Result:
-    - Users can edit properties that have **no effect** (misleading).
-  - **Fix options**:
-    1) Hide/disable these fields unless the runtime supports them, **or**
-    2) Implement them end-to-end:
-       - add horizontal flip / rotation in terrain blitting
-       - define semantics for `ONE_WAY`
-       - define semantics for `WIDTH/HEIGHT` (scale? crop? trigger-only resize?)
-
-- **NXLV comment preservation bug: comments inside sections are mis-filed**
-  - In `NxlvParser`, any line whose trimmed form starts with `#` is appended to `level.unknownLines` **even if it appears inside a section** (e.g., inside `$TERRAIN`, `$GADGETS`, etc.).
-  - Result:
-    - Exporting a level can reorder/move comments, breaking round-trip fidelity.
-  - **Fix**: when `ctx` is active, append comment lines to `ctx.data.unknownLines` instead of `level.unknownLines`.
-
-- **Unlimited editor history can grow without bound**
-  - `EditorUiController` sets `MAX_HISTORY = Number.MAX_SAFE_INTEGER` and uses it for `EditorHistory`.
-  - Each snapshot stores full serialized NXLV text → memory growth is unbounded during long sessions.
-  - **Fix**: cap history entries (e.g., 200–1000) and/or implement “delta history” (structural diffs) or compression.
-
-- **Very large level sizes can freeze/crash the browser**
-  - Header `WIDTH`/`HEIGHT` are only validated as numeric; there is **no max bound**.
-  - Preview loads allocate:
-    - `groundImage` RGBA array (`width * height * 4`)
-    - `groundMask` arrays
-  - A typo like `WIDTH=1000000` will likely hang or crash.
-  - **Fix**: enforce max sizes in validation + input clamping (reasonable bounds based on engine limits).
-
-- **Export LVL “INFINITE” time limit semantics are unclear / inconsistent**
-  - `EditorLevelLoader.resolveTimeLimit()` converts `TIME_LIMIT='INFINITE'` into a very large number.
-  - The engine timer expects time limit in **minutes** (`GameTimer` multiplies by 60).
-  - Current behavior effectively sets *thousands of minutes*, producing odd UI values.
-  - **Fix**:
-    - Either treat `INFINITE` as `lemmings.endless` in preview, or
-    - Introduce a clear sentinel and adjust timer display accordingly (e.g., show `∞`).
-
----
-
-### B. Medium-impact bugs / design footguns
-
-- **Preview refresh coalescing can drop “latest label” context**
-  - `EditorController._requestPreview()` ignores calls while a timer is pending.
-  - If multiple edits happen quickly, the preview refresh reason/label can become stale.
-  - **Enhancement**: store the *latest* requested label/options and run once after debounce.
-
-- **LocalStorage pressure from previews and saved levels**
-  - `EditorPreviewCache` stores thumbnail data URLs.
-  - Saved levels are also stored in localStorage.
-  - Browsers have limited quotas; storage write failures are caught, but UX may degrade silently.
-  - **Enhancement**:
-    - LRU eviction strategy
-    - configurable “cache off”
-    - storage usage indicator + clear-cache button
-
-- **Brush/eraser performance scales poorly with brush size**
-  - Brush/eraser loop over `(2*brushSize+1)^2` points per pointer event.
-  - Each eraser stamp does hit tests scanning entries (O(N)).
-  - **Enhancement**:
-    - clamp max brush size
-    - spatial index for hit testing (grid buckets / quadtree)
-    - batch paint/erase operations into a single history snapshot (already mostly done, but the per-point hit test remains expensive)
-
-- **No explicit “dirty” indicator for unsaved changes**
-  - The editor can save/export, but there’s no persistent UI indicator (“*unsaved changes*”).
-  - **Enhancement**: set dirty flag when history diverges from last save; show in title bar and on navigation.
-
-- **No dedicated Undo/Redo buttons in UI**
-  - Undo/Redo exist in keybindings, but UI lacks buttons.
-  - **Enhancement**: add toolbar buttons + show current history label.
-
----
-
-### C. Editor ↔ engine parity gaps (missing or partial implementations)
-
-These are not necessarily “bugs” if the intent is classic Lemmings compatibility, but they *are* feature gaps relative to the editor surface area and NXLV semantics.
-
-- **Horizontal flip (`FLIP_HORIZONTAL`)**: editor supports editing; runtime ignores.
-- **Rotation (`ROTATE`)**: editor supports editing; runtime ignores.
-- **Resizing (`WIDTH`/`HEIGHT`)**: editor supports drag handles + numeric edits; runtime ignores.
-- **One-way terrain (`ONE_WAY`)**: editor supports flag; runtime ignores (engine uses arrow trigger ranges, not terrain flag).
-- **Per-object skill / lemming count / pairing (`SKILL`, `LEMMINGS`, `PAIRING`)**:
-  - Editor supports fields.
-  - Engine’s entrance spawns are global and ignore per-entrance lemming counts.
-  - Pairing/skill appear unused in runtime.
-- **Per-entry STYLE override (multi-style levels)**:
-  - Editor always uses header STYLE for new placements.
-  - Loader resolves ids using header STYLE.
-  - True multi-style NXLV levels are not supported.
-
-**Recommendation:** Either:
-- (A) explicitly scope the editor to “classic” and hide unsupported fields, or
-- (B) commit to NXLV features and implement runtime support.
-
----
-
-## 2) Editor enhancements (feature roadmap)
-
-### A. Reliability + safety
-- Add hard caps and validation rules for:
-  - WIDTH/HEIGHT maximums
-  - brush size maximum
-  - steel rect maximum size
-  - spawn interval and lemming counts (reasonable bounds)
-- Add “unsupported feature” validation warnings:
-  - terrainGroups present
-  - ROTATE / FLIP_HORIZONTAL / WIDTH / HEIGHT / ONE_WAY present
-  - SKILL/PAIRING/LEMMINGS used on gadgets
-- Add robust round-trip support for NXLV comments/unknown lines:
-  - preserve blank lines
-  - preserve section-local comments
-
-### B. Editing power
-- Multi-select property editing:
-  - allow editing X/Y offsets for all selected
-  - allow toggling flags across selection
-- Paste-at-cursor (or paste at last click) mode
-- Duplicate hotkey (explicit) separate from alt-drag
-- “Align / distribute” commands:
-  - align left/right/top/bottom/center
-  - distribute spacing evenly
-- Layer visibility toggles:
-  - show/hide terrain
-  - show/hide objects
-  - show/hide triggers
-  - show/hide steel overlay
-
-### C. UX + discoverability
-- Style picker as dropdown (backed by `StyleRegistry.getStyleNames()`)
-- Palette filters:
-  - “steel only”
-  - “trigger only”
-  - “decorations only”
-- Better tool cursors:
-  - show brush radius
-  - show terrain piece bounding box
-  - show object trigger rectangle when placing triggers
-- Mini-map / overview
-- Shortcut overlay improvements:
-  - show current bindings from keybindings.json
-  - include “search shortcuts” field
-
-### D. Engine parity improvements (if desired)
-- Implement horizontal flip and rotation in `GroundRenderer` blitting.
-- Define semantics for WIDTH/HEIGHT:
-  - option 1: scale piece (nearest neighbor) into terrain bitmap
-  - option 2: crop from source sprite
-  - option 3: treat width/height as “trigger override area” only for objects
-- Implement one-way terrain:
-  - either by translating `ONE_WAY` terrain into directional trigger ranges
-  - or by adding collision rule in lemming movement (more work)
-- Implement terrain groups:
-  - load into preview
-  - preserve export ordering
-  - optional UI support (group list, group visibility)
-
----
-
-## 3) Procgen mode: comprehensive enhancement plan
-
-Current procgen (`js/app/procgenController.js`) does:
-- paint ground via direct pixel writes (`level.setGroundAt`)
-- occasional bomb / nuke
-- fixed game type + style (`OHNO` + `fire`)
-- no terrain pieces, no objects/triggers beyond the entrance, no decoration variety
-
-Below is a concrete upgrade plan.
-
----
-
-### A. Terrain + objects from *all* level packs
-
-#### 1) Support choosing **pack** and **style** dynamically
-- Add procgen options:
-  - `gameType`: choose from config.json packs (`lemmings`, `ohno`, `xmas91`, etc.)
-  - `style`: choose from `StyleRegistry.getStyleNames()` or by groundSet
-  - `seed`: deterministic generation
-- Implement “biome rotation”:
-  - every N chunks, switch style (and optionally pack) with a smooth transition
-
-#### 2) Load real terrain/object assets for the chosen pack/style
-- Reuse `EditorAssetCache.loadStyleAssets(styleName, config, fileProvider)` to get:
-  - `terrainImages` with masks and steel flags
-  - `gadgetImages` (objects) with trigger metadata
-  - `terrain/gadgets/triggers` metadata lists
-- Categorize assets once:
-  - **terrainSolid**: most terrain pieces
-  - **terrainSteel**: terrain with `isSteel`
-  - **objectsDecor**: `triggerEffectId == 0`
-  - **objectsHazard**: traps/drown/fry/kill
-  - **objectsExit/Entrance**: special trigger types
-
-#### 3) Replace “flat painted ground” with **terrain-piece stamping**
-Instead of writing palette indices directly, build the ground by *blitting terrain pieces* into:
-- `level.groundMask`
-- `level.groundImage`
-
-Implementation options (in increasing “properness”):
-1. **Simple blit**: iterate pixels of a terrain image and call `level.setGroundAt(x, y, ...)` for solid pixels.  
-   - easy, but slower
-2. **Direct array copy**: copy pixels directly into `level.groundImage` and update `groundMask` bits.  
-   - faster, but you must match `GroundRenderer` mask semantics
-3. **Reuse GroundRenderer**: create a “streaming ground renderer” that can stamp pieces incrementally.  
-   - best long-term
-
-#### 4) Chunk-based streaming world generation
-The existing procgen effectively preallocates a giant width. Consider chunk streaming:
-
-- Maintain:
-  - `chunkSize = 256 or 512 px`
-  - `generatedUntilX`
-  - a ring-buffer or world arrays sized to `visibleRange + safetyMargin`
-- As camera approaches `generatedUntilX - margin`, generate next chunk:
-  - platforms
-  - gaps
-  - obstacles
-  - hazards
-  - decorations
-- Optionally recycle old chunks behind camera to keep memory bounded.
-
----
-
-### B. Place “occasional triggers” + decoration
-
-#### 1) Decoration pass
-- Place non-trigger objects (`triggerEffectId == 0`) on:
-  - ceilings
-  - platform edges
-  - background zones (if you implement non-solid decorative layers)
-- Use spacing constraints so decoration doesn’t become clutter:
-  - minimum distance between objects
-  - per-chunk density cap
-
-#### 2) Hazard / trigger pass
-Place trigger objects occasionally, but with guard rails:
-
-- Use weighted random selection by trigger type:
-  - 70%: none
-  - 20%: mild hazard (small trap)
-  - 8%: major hazard (water / fire)
-  - 2%: special (teleporter if supported, etc.)
-
-- Always ensure there is a counterplay route:
-  - add nearby terrain pieces that allow building over
-  - add a tunnelable wall for bashing/mining
-  - add a “safe ledge” for blockers
-
-#### 3) Runtime trigger integration
-Because procgen is running during gameplay:
-- Create `level.addObject(...)` helper that:
-  - instantiates `MapObject`
-  - adds it to `level.objects`
-  - creates and registers `Trigger` rectangles with `game.triggerManager.add(...)`
-  - updates arrow areas if you ever use arrow triggers
-
----
-
-### C. Make procgen levels *intentionally solvable*
-
-Procedural levels are only fun if they’re usually solvable (or at least “recoverable”).
-
-Recommended approach:
-1) Generate a **golden path** from entrance → “forward progress” direction.
-2) Sprinkle optional hazards/bonuses around it.
-3) Run a lightweight **simulator** (or heuristic check) to ensure:
-   - no unavoidable splats
-   - no unavoidable drown/fry sections
-   - at least one feasible route forward within skill budget
-
-You do not need full search/pathfinding to start:
-- start with rule-based constraints and a “forward progress” invariant
-
----
-
-## 4) “More interesting behavior” for lemmings in procgen
-
-The core engine already contains classic skill systems (builder, basher, miner, blocker, climber, etc.). Procgen currently only uses builder defensively.
-
-### A. Add a Procgen “AI director”
-Add a module that:
-- watches leading lemmings
-- predicts imminent failure states
-- assigns skills to 1–N lemmings to maintain forward progress
-
-This should be purely optional and tunable:
-- “spectator” mode (minimal interventions)
-- “assist” mode (prevents cheap deaths)
-- “solver” mode (actively pushes through obstacles)
-
-### B. Environment sensing primitives (needed for any AI)
-Add helpers in procgen controller:
-- `measureDropAhead(lem, lookRight, maxScan)`
-- `measureWallHeightAhead(lem, lookRight, maxScan)`
-- `findGapWidthAhead(lem, lookRight, maxScan)`
-- `isHazardAhead(lem, lookRight, distance)`
-- `isCrowdedAt(x, y)` (for blocker decisions)
-- `estimateBuildNeededForGap(gapWidth)`
-
-These can query:
-- `level.hasGroundAt(x, y)`
-- trigger manager ranges (hazards)
-
-### C. Skill decision heuristics (concrete behaviors)
-
-Below are behaviors you specifically asked for, with feasible triggers:
-
-#### 1) Bash through terrain
-- Condition:
-  - lemming hits a wall (blocked horizontally)
-  - wall thickness within a bashable limit
-- Action:
-  - `doLemmingAction(lemming, ActionType.BASH)`
-- Safety:
-  - don’t bash into water/fire trigger zones without an escape route
-  - avoid bashing steel
-
-#### 2) Mine / dig down
-- Condition:
-  - next chunk goal is below current platform
-  - or lemming needs to descend but drop is lethal
-- Action:
-  - `ActionType.MINE` (angled) or `ActionType.DIG` (vertical)
-- Safety:
-  - ensure there’s ground below to land on
-  - avoid digging into hazards
-
-#### 3) Climb up walls
-- Condition:
-  - encountering frequent vertical walls in the forward direction
-  - climber skill budget available
-- Action:
-  - assign `CLIMBER` (trait) if your engine supports it as a permanent trait, or trigger climb action.
-- Safety:
-  - climbers can walk off cliffs → combine with floater or proactive builder.
-
-#### 4) Block to prevent lemmings going off ledges while ramp is built
-This is a classic multi-lemming coordination pattern:
-
-- Detect a lethal drop ahead with a gap that requires a builder ramp.
-- Pick a lemming *near the ledge* to become a blocker.
-- While the crowd is contained, assign builder to create a safe ramp.
-- Release blocker:
-  - bash into blocker
-  - dig under blocker
-  - or bomb a small hole next to blocker (if you want occasional chaos)
-
-Implementation details:
-- maintain a “current construction site” state:
-  - `blockerId`
-  - `builderId`
-  - `rampTargetComplete` flag
-- do not place multiple blockers too close.
-
-#### 5) Floater assignment (optional, but makes procgen feel smarter)
-- When a lemming is about to fall farther than the safe height:
-  - assign floater, not builder, if you want variety
-- Builders then become “progress” tools instead of pure safety tools.
-
-### D. Add “skill budget” and pacing
-To keep procgen interesting:
-- Provide infinite skills (arcade mode), or
-- Provide skill regeneration over distance/time, or
-- Provide per-chunk skill allowances.
-
-### E. Add “events” for emergent gameplay
-- occasional “rescue bonus” (temporary skill surge)
-- occasional “storm” that increases spawn rate
-- occasional “boss obstacle” chunk requiring 2–3 coordinated skills
-
----
-
-## 5) Concrete implementation checklist (engineering tasks)
-
-### A. Procgen terrain stamping
-- [ ] Add `ProcgenAssetManager` using `EditorAssetCache`
-- [ ] Categorize terrain/object assets
-- [ ] Add `stampTerrainPiece(pieceId, x, y, {flipV,noOverwrite,erase})`
-- [ ] Add chunk generator that picks terrain pieces and places platforms
-
-### B. Runtime object + trigger placement
-- [ ] Implement `addObjectAt(pieceId, x, y)` that registers triggers via `game.triggerManager.add(...)`
-- [ ] Add decoration object placement rules (spacing + density caps)
-- [ ] Add hazard placement rules (always with counterplay route)
-
-### C. AI director
-- [ ] Add environment sensing primitives
-- [ ] Add skill decision state machine
-- [ ] Add coordinated “blocker + builder + release” pattern
-- [ ] Add safety constraints to avoid infinite loops and self-sabotage
-
-### D. Debugging/visibility
-- [ ] On-screen debug overlay for procgen:
-  - current seed
-  - current chunk index
-  - recent AI decisions (“builder @ x=…”, “bash @ x=…”)
-- [ ] Toggleable visualization of triggers and steel
-
----
\ No newline at end of file
diff --git a/eslint.config.js b/eslint.config.js
index a30f6cea..78642d77 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -1,8 +1,11 @@
+import { lintGlobals, testLintGlobals } from './scripts/lint-globals.js';
+
 export default [
   {
     files: ['**/*.js'],
     ignores: [
       'node_modules/**',
+      'js/vendor/**',
       'holiday93/**',
       'holiday94/**',
       'lemmings/**',
@@ -14,12 +17,58 @@ export default [
     ],
     languageOptions: {
       ecmaVersion: 2022,
-      sourceType: 'module'
+      sourceType: 'module',
+      globals: lintGlobals
     },
     rules: {
       indent: ['error', 2],
       quotes: ['error', 'single'],
-      semi: ['error', 'always']
+      semi: ['error', 'always'],
+      'no-undef': ['error', { typeof: true }],
+      radix: ['error', 'always']
+    }
+  },
+  {
+    files: ['test/**/*.js', 'e2e/**/*.js'],
+    languageOptions: {
+      globals: testLintGlobals
+    }
+  },
+  {
+    files: [
+      'js/app/**/*.js',
+      'js/editor/**/*.js',
+      'js/game/**/*.js',
+      'js/lemmings/**/*.js',
+      'js/midi/**/*.js',
+      'js/render/**/*.js',
+      'js/util/**/*.js'
+    ],
+    rules: {
+      'no-restricted-globals': ['error',
+        {
+          name: 'lemmings',
+          message: 'Use explicit app context via dependencies instead of implicit global lemmings.'
+        }
+      ],
+      'no-restricted-properties': ['error',
+        {
+          object: 'globalThis',
+          property: 'lemmings',
+          message: 'Use explicit app context via dependencies instead of globalThis.lemmings.'
+        },
+        {
+          object: 'window',
+          property: 'lemmings',
+          message: 'Use explicit app context via dependencies instead of window.lemmings.'
+        }
+      ]
+    }
+  },
+  {
+    files: ['js/actions/**/*.js', 'js/game/**/*.js', 'js/lemmings/**/*.js'],
+    rules: {
+      eqeqeq: ['error', 'always', { null: 'ignore' }]
     }
   }
 ];
diff --git a/gamepadbindings.json b/gamepadbindings.json
new file mode 100644
index 00000000..8bb161a0
--- /dev/null
+++ b/gamepadbindings.json
@@ -0,0 +1,44 @@
+{
+  "version": 1,
+  "bindings": {
+    "gameplay": {
+      "togglePause": ["button:9"],
+      "stepBackward": ["button:2"],
+      "stepForward": ["button:3"],
+      "toggleReverse": ["button:10"],
+      "nuke": ["button:8"],
+      "restartLevel": ["button:11"],
+      "cycleSkillPrev": ["button:4"],
+      "cycleSkillNext": ["button:5"],
+      "applySkillToSelected": ["button:0"],
+      "levelPrev": ["button:6"],
+      "levelNext": ["button:7"],
+      "toggleShortcutOverlay": ["button:16"],
+      "panLeft": ["button:14", "axis:0:-:0.35"],
+      "panRight": ["button:15", "axis:0:+:0.35"],
+      "panUp": ["button:12", "axis:1:-:0.35"],
+      "panDown": ["button:13", "axis:1:+:0.35"],
+      "zoomIn": ["axis:3:-:0.35"],
+      "zoomOut": ["axis:3:+:0.35"],
+      "zoomReset": ["button:1"]
+    },
+    "editor": {
+      "editorToolSelect": ["button:10"],
+      "editorToolTerrain": ["button:0"],
+      "editorToolGadget": ["button:1"],
+      "editorToolTrigger": ["button:2"],
+      "editorToolMidiFlag": ["button:3"],
+      "editorToolBrush": ["button:4"],
+      "editorToolEraser": ["button:5"],
+      "editorUndo": ["button:6"],
+      "editorRedo": ["button:7"],
+      "editorDelete": ["button:8"],
+      "editorTogglePlaytest": ["button:9"],
+      "editorToggleShortcutOverlay": ["button:16"],
+      "editorNudgeLeft": ["button:14", "axis:0:-:0.35"],
+      "editorNudgeRight": ["button:15", "axis:0:+:0.35"],
+      "editorNudgeUp": ["button:12", "axis:1:-:0.35"],
+      "editorNudgeDown": ["button:13", "axis:1:+:0.35"]
+    }
+  }
+}
diff --git a/index.html b/index.html
index 5d569e60..971c77f7 100644
--- a/index.html
+++ b/index.html
@@ -3,6 +3,8 @@
 <head>
   <title>Lemmings - Lemmings / Oh no! More Lemmings</title>
   <meta charset="UTF-8" />
+  <meta name="lemmings-analytics" content="runtime" />
+  <meta name="lemmings-analytics-endpoint" content="" />
   <meta name="viewport" content="width=device-width, height=device-height, initial-scale=1.0, maximum-scale=1.0, user-scalable=0.0, viewport-fit=cover"/>
   <meta name="description" content="Classic Lemmings reimplementation with WebMIDI controls, editor, and E2E harness." />
   <meta property="og:title" content="LemmingsJS-MIDI" />
@@ -36,188 +38,483 @@
       };
     }
   </script>
-  <script type="text/javascript" src="js/vendor/jquery.js"></script>
   <script type="text/javascript" src="js/vendor/webmidi.js"></script>
   <script type="module" src="js/app/boot.js"></script>
 </head>
 <body oncontextmenu="return false;">
-  <div id="controlLeft" class="control-panel left">
-    <div class="panel-section panel-header">
-      <div class="panel-title panel-toggle" id="midiPanelToggle">MIDI</div>     
-      <label class="panel-row midi-enable-row">
-        <span>MIDI enabled</span>
+  <div id="midiSequencerWorkspace" class="midi-sequencer" aria-label="MIDI sequencer workspace">
+    <div id="midiTransportStrip" class="midi-transport">
+      <div class="midi-transport__title">MIDI Sequencer</div>
+      <label class="midi-field midi-field--toggle">
+        <span>Enable</span>
         <input type="checkbox" id="midiEnabledToggle" />
       </label>
-      <button id="midiDefaultsButton" type="button" class="button-danger">reset all</button>
-    </div>
-    <div class="panel-section panel-tabs">
-      <div class="tabs" data-tab-group="midi-left">
-        <button class="tab-button active" data-tab-group="midi-left" data-tab-target="midiTabLeft">MIDI</button>
-        <button class="tab-button" data-tab-group="midi-left" data-tab-target="midiTabGlobalFx">Global FX</button>
-      </div>
+      <label class="midi-field">
+        <span>Input</span>
+        <select id="midiInSelect"></select>
+      </label>
+      <label class="midi-field">
+        <span>Output</span>
+        <select id="midiOutSelect"></select>
+      </label>
+      <label class="midi-field midi-field--compact">
+        <span>Channel</span>
+        <select id="midiInputChannel"></select>
+      </label>
+      <label class="midi-field midi-field--compact">
+        <span>BPM</span>
+        <input type="number" id="midiBpmBase" min="40" max="240" step="1" />
+      </label>
+      <label class="midi-field midi-field--compact">
+        <span>Beats</span>
+        <input type="number" id="midiTimeSignatureBeats" min="1" max="16" step="1" />
+      </label>
+      <label class="midi-field midi-field--compact">
+        <span>Unit</span>
+        <select id="midiTimeSignatureUnit">
+          <option value="1">1</option>
+          <option value="2">2</option>
+          <option value="4">4</option>
+          <option value="8">8</option>
+          <option value="16">16</option>
+        </select>
+      </label>
+      <label class="midi-field midi-field--compact">
+        <span>Key</span>
+        <select id="midiScaleRoot"></select>
+      </label>
+      <label class="midi-field midi-field--compact">
+        <span>Scale</span>
+        <select id="midiScaleName"></select>
+      </label>
+      <label class="midi-field midi-field--compact">
+        <span>Quant</span>
+        <select id="midiQuantize">
+          <option value="off">Off</option>
+          <option value="1/4">1/4</option>
+          <option value="1/8">1/8</option>
+          <option value="1/16">1/16</option>
+          <option value="1/32">1/32</option>
+        </select>
+      </label>
+      <label class="midi-field midi-field--compact">
+        <span>Swing</span>
+        <input type="number" id="midiSwing" min="0" max="1" step="0.05" />
+      </label>
+      <label class="midi-field">
+        <span>Template</span>
+        <select id="midiTemplateSelect"></select>
+      </label>
+      <button id="midiProjectResetButton" type="button" aria-label="Reset MIDI project">Reset</button>
+      <button id="midiPanicButton" type="button" aria-label="Panic all MIDI notes">Panic</button>
+      <label class="midi-field midi-field--toggle">
+        <span>Reverse Panic</span>
+        <input type="checkbox" id="midiReversePanicToggle" />
+      </label>
+      <button id="midiTemplateSaveButton" type="button" aria-label="Save MIDI template">Save Template</button>
+      <button id="midiProjectExportButton" type="button" aria-label="Export MIDI project">Export</button>
+      <button id="midiProjectImportButton" type="button" aria-label="Import MIDI project">Import</button>
+      <input id="midiProjectImportInput" class="midi-hidden-file-input" type="file" accept="application/json,.json" />
+      <div id="midiProjectStatus" class="midi-status" role="status">Project loading</div>
+      <div id="errorDisplay" class="midi-error" role="status"></div>
     </div>
-    <div class="tab-panel active" id="midiTabLeft" data-tab-group="midi-left">
-      <details class="panel-section" id="midiIoSection" data-section-key="io" open>
-        <summary class="panel-title">I/O</summary>
-        <label class="panel-row">
-          <span>Input</span>
-          <select id="midiInSelect"></select>
-        </label>
-        <label class="panel-row">
-          <span>Output</span>
-          <select id="midiOutSelect"></select>
-        </label>
-        <label class="panel-row">
-          <span>Input channel</span>
-          <select id="midiInputChannel"></select>
-        </label>
-        <button id="midiResetButton" type="button">MIDI reset</button>
-        <label class="panel-row">
-          <span>View pan</span>
-          <input type="checkbox" id="midiViewPanToggle" />
+    <div class="midi-workspace-grid">
+      <section id="midiSourceBrowser" class="midi-region midi-source-browser" aria-label="MIDI source browser">
+        <div class="midi-region__header">
+          <h2>Sources</h2>
+          <span id="midiSourceCount" role="status" aria-live="polite" aria-label="0 sources shown">0</span>
+        </div>
+        <label class="midi-field midi-field--stacked">
+          <span>Search</span>
+          <input id="midiSourceSearch" type="search" autocomplete="off" />
         </label>
-        <div id="errorDisplay" class="panel-error"></div>
-      </details>
-      <div class="panel-section">
-        <div class="panel-title panel-title-row">
-          <span>Base BPM</span>
-          <input type="number" id="midiBpmBase" min="40" max="240" step="1" class="input-compact input-align-right" />
+        <div class="midi-filter-row">
+          <select id="midiSourceKindFilter" aria-label="Source category">
+            <option value="all">All categories</option>
+            <option value="sfx">SFX</option>
+            <option value="trigger">Triggers</option>
+            <option value="midiFlag">MIDI flags</option>
+            <option value="system">System</option>
+            <option value="procgen">Procgen</option>
+          </select>
+          <select id="midiSourceAssignFilter" aria-label="Assignment filter">
+            <option value="all">All sources</option>
+            <option value="changed">Changed</option>
+            <option value="available">Available in level</option>
+            <option value="assigned">Assigned</option>
+            <option value="unassigned">Unassigned</option>
+            <option value="enabled">Enabled</option>
+            <option value="disabled">Disabled</option>
+            <option value="conflicts">Conflicts</option>
+            <option value="clean">Clean</option>
+          </select>
         </div>
-        <div class="panel-row panel-row-wide">
-          <span id="midiBpmCurrent">--</span>
+        <div id="midiSourceList" class="midi-source-list" role="listbox" aria-label="Event sources"></div>
+      </section>
+      <section id="midiTrackWorkspace" class="midi-region midi-track-workspace" aria-label="MIDI tracks">
+        <div class="midi-region__header">
+          <h2>Tracks</h2>
+          <button id="midiTrackAdd" type="button" aria-label="Add MIDI track">Add</button>
+          <button id="midiTrackRemove" type="button" aria-label="Remove selected MIDI track">Remove</button>
         </div>
-      </div>
-      <details class="panel-section" id="midiDebugSection" data-section-key="debug">
-        <summary class="panel-title">MIDI Debug</summary>
-        <div class="panel-row panel-row-wide">
-          <span id="midiDebugInput">Input: --</span>
+        <div id="midiTrackList" class="midi-track-list" role="listbox" aria-label="Project tracks"></div>
+        <div id="midiClipLibrary" class="midi-clip-library">
+          <div class="midi-region__header midi-region__header--compact">
+            <h2>Clips</h2>
+            <button id="midiClipAddButton" type="button" aria-label="Add MIDI clip">Add</button>
+            <button id="midiClipDuplicateButton" type="button" aria-label="Duplicate selected MIDI clip">Duplicate</button>
+            <button id="midiClipRemoveButton" type="button" aria-label="Remove selected MIDI clip">Remove</button>
+          </div>
+          <div id="midiClipList" class="midi-clip-list" role="listbox" aria-label="Project clips"></div>
         </div>
-        <div class="panel-row panel-row-wide">
-          <span id="midiDebugOutput">Output: --</span>
+        <div id="midiSelectedSourceSummary" class="midi-selection-summary">No source selected</div>
+        <div class="midi-assignment-row">
+          <select id="midiAssignTrackSelect" aria-label="Assign source to track"></select>
+          <button id="midiAssignSourceButton" type="button" aria-label="Assign selected source to track">Assign Source</button>
         </div>
-      </details>
-    </div>
-    <div class="tab-panel" id="midiTabGlobalFx" data-tab-group="midi-left">
-      <div class="panel-section">
-        <label class="panel-row range-row">
-          <span>Intensity</span>
-          <div class="range-input">
-            <span class="range-label">10</span>
-            <input type="range" id="midiIntensity" min="10" max="127" step="1" />
-            <span class="range-label">127</span>
+      </section>
+      <section id="midiInspector" class="midi-region midi-inspector" aria-label="MIDI inspector">
+        <div class="midi-region__header">
+          <h2>Inspector</h2>
+          <div class="midi-button-row">
+            <button id="midiAuditionButton" type="button" aria-label="Audition selected source">Audition</button>
+            <button id="midiClipAuditionButton" type="button" aria-label="Audition selected clip">Clip</button>
           </div>
-        </label>
-        <label class="panel-row range-row">
-          <span>Accent</span>
-          <div class="range-input">
-            <span class="range-label">0</span>
-            <input type="range" id="midiAccent" min="0" max="1" step="0.01" />
-            <span class="range-label">1</span>
+        </div>
+        <div id="midiTrackInspector" class="midi-inspector-group">
+          <h3>Track</h3>
+          <label class="midi-field midi-field--stacked">
+            <span>Name</span>
+            <input id="midiTrackName" type="text" />
+          </label>
+          <label class="midi-field midi-field--stacked">
+            <span>Instrument</span>
+            <input id="midiTrackInstrument" type="text" />
+          </label>
+          <label class="midi-field midi-field--stacked">
+            <span>Output</span>
+            <select id="midiTrackOutputSelect"></select>
+          </label>
+          <div class="midi-inline-fields">
+            <label class="midi-field midi-field--compact">
+              <span>Channel</span>
+              <input id="midiTrackChannel" type="number" min="1" max="16" step="1" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Priority</span>
+              <input id="midiTrackPriority" type="number" min="0" max="4" step="1" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Voices</span>
+              <input id="midiTrackVoiceBudget" type="number" min="1" max="32" step="1" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Scale</span>
+              <input id="midiTrackVelocityScale" type="number" min="0" max="4" step="0.05" />
+            </label>
+          </div>
+          <div class="midi-toggle-row">
+            <label><input id="midiTrackMute" type="checkbox" /> Mute</label>
+            <label><input id="midiTrackSolo" type="checkbox" /> Solo</label>
+            <label><input id="midiTrackArm" type="checkbox" /> Arm</label>
           </div>
-        </label>
-      </div>
-      <details class="panel-section" id="midiPositionSection" data-section-key="position" open>
-        <summary class="panel-title">Positional Modifiers</summary>
-        <div class="panel-row">
-          <span>Position mappings</span>
-          <button id="midiPositionAdd" type="button">Add mapping</button>
         </div>
-        <div id="midiPositionList"></div>
-      </details>
-      <details class="panel-section" id="midiRepeatSection" data-section-key="repeat">
-        <summary class="panel-title panel-title-row">
-          <span>Global Repeat</span>
-          <label class="panel-title-toggle">
+        <div id="midiSourceInspector" class="midi-inspector-group">
+          <h3>Source</h3>
+          <div class="midi-button-row">
+            <button id="midiSourceRevertButton" type="button" aria-label="Revert selected source mapping">Revert Source</button>
+          </div>
+          <label class="midi-field midi-field--toggle">
             <span>Enabled</span>
-            <input type="checkbox" id="midiRepeatEnabled" />
+            <input id="midiSourceEnabled" type="checkbox" />
           </label>
-        </summary>
-        <label class="panel-row">
-          <span>Repeat max count</span>
-          <input type="number" id="midiRepeatCount" min="0" max="32" step="1" />
-        </label>
-        <label class="panel-row">
-          <span>Repeat window (beats)</span>
-          <select id="midiRepeatSpacing"></select>
-        </label>
-        <label class="panel-row">
-          <span>Repeat target</span>
-          <select id="midiRepeatTarget"></select>
-        </label>
-        <label class="panel-row range-row">
-          <span>Repeat amount</span>
-          <div class="range-input">
-            <span class="range-label">-1</span>
-            <input type="range" id="midiRepeatAmount" min="-1" max="1" step="0.05" />
-            <span class="range-label">1</span>
+          <label class="midi-field midi-field--stacked">
+            <span>Route</span>
+            <select id="midiSourceTrackSelect"></select>
+          </label>
+          <div class="midi-inline-fields">
+            <label class="midi-field midi-field--compact">
+              <span>Mode</span>
+              <select id="midiSourceModeSelect">
+                <option value="direct">Direct</option>
+                <option value="clip">Clip</option>
+              </select>
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Clip</span>
+              <select id="midiSourceClipSelect"></select>
+            </label>
+            <button id="midiAssignClipButton" type="button" aria-label="Assign selected clip to source">Assign Clip</button>
           </div>
-        </label>
-      </details>
-    </div>
-  </div>
-  <div id="controlRight" class="control-panel right">
-    <div class="tabs" data-tab-group="midi-right">
-      <button class="tab-button active" data-tab-group="midi-right" data-tab-target="midiTabEvents">Events</button>
-      <button class="tab-button" data-tab-group="midi-right" data-tab-target="midiTabTriggers">Triggers</button>
-      <button class="tab-button" data-tab-group="midi-right" data-tab-target="midiTabAdsr">ADSR</button>
-    </div>
-    <div class="tab-panel active" id="midiTabEvents" data-tab-group="midi-right">
-      <div class="panel-section">
-        <div class="panel-title">Key and scale</div>
-        <label class="panel-row">
-          <span>Key</span>
-          <select id="midiKeySelect"></select>
-        </label>
-        <label class="panel-row">
-          <span>Scale</span>
-          <select id="midiScaleSelect"></select>
-        </label>
-      </div>
-      <div id="midiEventList"></div>
-    </div>
-    <div class="tab-panel" id="midiTabTriggers" data-tab-group="midi-right">
-      <div id="midiTriggerList"></div>
-    </div>
-    <div class="tab-panel" id="midiTabAdsr" data-tab-group="midi-right">
-      <div class="panel-section">
-        <div class="panel-title">Envelope</div>
-        <label class="panel-row">
-          <span>Target</span>
-          <select id="midiEnvTarget"></select>
-        </label>
-        <label class="panel-row range-row">
-          <span>Attack</span>
-          <div class="range-input">
-            <span class="range-label">0</span>
-            <input type="range" id="midiEnvAttack" min="0" max="2" step="0.05" />
-            <span class="range-label">2</span>
+          <div id="midiConflictSummary" class="midi-conflict-summary" role="status" aria-live="polite">
+            No conflicts for the selected source.
           </div>
-        </label>
-        <label class="panel-row range-row">
-          <span>Decay</span>
-          <div class="range-input">
-            <span class="range-label">0</span>
-            <input type="range" id="midiEnvDecay" min="0" max="1" step="0.05" />
-            <span class="range-label">1</span>
+          <div id="midiLearnPanel" class="midi-learn-panel" aria-live="polite">
+            <div id="midiLearnStatus" class="midi-learn-status" role="status">Learn waits for the next note-on.</div>
+            <div class="midi-button-row">
+              <button id="midiLearnButton" type="button" aria-label="Start MIDI learn">Learn</button>
+              <button id="midiLearnConfirmButton" type="button" aria-label="Commit MIDI learn">Commit</button>
+              <button id="midiLearnCancelButton" type="button" aria-label="Cancel MIDI learn">Cancel</button>
+            </div>
           </div>
-        </label>
-        <label class="panel-row range-row">
-          <span>Sustain</span>
-          <div class="range-input">
-            <span class="range-label">0.25</span>
-            <input type="range" id="midiEnvSustain" min="0.25" max="2" step="0.05" />
-            <span class="range-label">2</span>
+          <div class="midi-toggle-row">
+            <label><input id="midiEnvelopeOverrideToggle" type="checkbox" /> Envelope override</label>
           </div>
-        </label>
-        <label class="panel-row range-row">
-          <span>Release</span>
-          <div class="range-input">
-            <span class="range-label">0</span>
-            <input type="range" id="midiEnvRelease" min="0" max="2" step="0.05" />
-            <span class="range-label">2</span>
+          <div class="midi-inline-fields">
+            <label class="midi-field midi-field--compact">
+              <span>Note</span>
+              <input id="midiMappingNote" type="number" min="0" max="127" step="1" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Degree</span>
+              <input id="midiMappingDegree" type="number" min="0" max="24" step="1" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Octave</span>
+              <input id="midiMappingOctave" type="number" min="0" max="10" step="1" />
+            </label>
           </div>
-        </label>
-      </div>
+          <div class="midi-inline-fields">
+            <label class="midi-field midi-field--compact">
+              <span>Velocity</span>
+              <input id="midiMappingVelocity" type="number" min="1" max="127" step="1" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Duration</span>
+              <input id="midiMappingDuration" type="number" min="1" max="96" step="1" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Chord</span>
+              <select id="midiMappingChord">
+                <option value="">None</option>
+                <option value="triad">Triad</option>
+                <option value="seventh">Seventh</option>
+                <option value="sixth">Sixth</option>
+                <option value="ninth">Ninth</option>
+                <option value="power">Power</option>
+                <option value="sus2">Sus2</option>
+                <option value="sus4">Sus4</option>
+                <option value="octave">Octave</option>
+              </select>
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Inversion</span>
+              <input id="midiMappingChordInversion" type="number" min="0" max="4" step="1" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Arp</span>
+              <select id="midiMappingArp">
+                <option value="">None</option>
+                <option value="up">Up</option>
+                <option value="down">Down</option>
+                <option value="updown">Up/Down</option>
+              </select>
+            </label>
+          </div>
+          <div class="midi-inline-fields">
+            <label class="midi-field midi-field--compact">
+              <span>Pan</span>
+              <input id="midiMappingPan" type="number" min="-127" max="127" step="1" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Timbre</span>
+              <input id="midiMappingTimbre" type="number" min="0" max="127" step="1" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Bend</span>
+              <input id="midiMappingPitchBend" type="number" min="-1" max="1" step="0.05" />
+            </label>
+          </div>
+          <div class="midi-inline-fields">
+            <label class="midi-field midi-field--compact">
+              <span>Attack</span>
+              <input id="midiEnvAttack" type="number" min="0" max="2" step="0.05" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Decay</span>
+              <input id="midiEnvDecay" type="number" min="0" max="2" step="0.05" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Sustain</span>
+              <input id="midiEnvSustain" type="number" min="0" max="2" step="0.05" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Release</span>
+              <input id="midiEnvRelease" type="number" min="0" max="2" step="0.05" />
+            </label>
+          </div>
+        </div>
+        <div id="midiModulationInspector" class="midi-inspector-group">
+          <div class="midi-region__header midi-region__header--compact">
+            <h3>Modulation</h3>
+            <button id="midiAutomationAddButton" type="button" aria-label="Add modulation lane">Add Mod</button>
+          </div>
+          <div class="midi-inline-fields">
+            <label class="midi-field midi-field--compact">
+              <span>Intensity</span>
+              <input id="midiGlobalIntensity" type="number" min="1" max="127" step="1" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Vel Min</span>
+              <input id="midiGlobalVelocityMin" type="number" min="1" max="127" step="1" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Vel Max</span>
+              <input id="midiGlobalVelocityMax" type="number" min="1" max="127" step="1" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Note Min</span>
+              <input id="midiGlobalNoteMin" type="number" min="0" max="127" step="1" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Note Max</span>
+              <input id="midiGlobalNoteMax" type="number" min="0" max="127" step="1" />
+            </label>
+          </div>
+          <div class="midi-inline-fields">
+            <label class="midi-field midi-field--compact">
+              <span>Accent</span>
+              <input id="midiGlobalAccent" type="number" min="0" max="4" step="0.05" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Density Win</span>
+              <input id="midiGlobalDensityWindow" type="number" min="0" max="960" step="1" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Dur Scale</span>
+              <input id="midiGlobalDurationScale" type="number" min="0" max="1" step="0.05" />
+            </label>
+            <label class="midi-field midi-field--toggle midi-field--compact">
+              <span>View Pan</span>
+              <input id="midiGlobalViewPan" type="checkbox" />
+            </label>
+          </div>
+          <div class="midi-inline-fields">
+            <label class="midi-field midi-field--compact">
+              <span>Pan Min</span>
+              <input id="midiGlobalPanMin" type="number" min="-127" max="127" step="1" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Pan Max</span>
+              <input id="midiGlobalPanMax" type="number" min="-127" max="127" step="1" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Pan Dead</span>
+              <input id="midiGlobalPanDeadZone" type="number" min="0" max="0.5" step="0.01" />
+            </label>
+          </div>
+          <div class="midi-inline-fields">
+            <label class="midi-field midi-field--compact">
+              <span>Timbre Min</span>
+              <input id="midiGlobalTimbreMin" type="number" min="0" max="127" step="1" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Timbre Max</span>
+              <input id="midiGlobalTimbreMax" type="number" min="0" max="127" step="1" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>X Offset Min</span>
+              <input id="midiGlobalXNoteMin" type="number" min="-48" max="48" step="1" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>X Offset Max</span>
+              <input id="midiGlobalXNoteMax" type="number" min="-48" max="48" step="1" />
+            </label>
+          </div>
+          <div class="midi-inline-fields">
+            <label class="midi-field midi-field--compact">
+              <span>Max Notes</span>
+              <input id="midiGlobalMaxActiveNotes" type="number" min="1" max="512" step="1" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Per Tick</span>
+              <input id="midiGlobalMaxEventsPerTick" type="number" min="1" max="512" step="1" />
+            </label>
+          </div>
+          <div class="midi-inline-fields">
+            <label class="midi-field midi-field--compact">
+              <span>Dur</span>
+              <input id="midiGlobalDurationDefault" type="number" min="1" max="960" step="1" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Min Dur</span>
+              <input id="midiGlobalDurationMin" type="number" min="1" max="960" step="1" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Max Dur</span>
+              <input id="midiGlobalDurationMax" type="number" min="1" max="960" step="1" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Attack</span>
+              <input id="midiGlobalEnvAttack" type="number" min="0" max="2" step="0.05" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Decay</span>
+              <input id="midiGlobalEnvDecay" type="number" min="0" max="2" step="0.05" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Sustain</span>
+              <input id="midiGlobalEnvSustain" type="number" min="0" max="2" step="0.05" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Release</span>
+              <input id="midiGlobalEnvRelease" type="number" min="0" max="2" step="0.05" />
+            </label>
+          </div>
+          <div id="midiAutomationList" class="midi-automation-list" aria-label="Position modulation lanes"></div>
+        </div>
+          <div id="midiClipInspector" class="midi-inspector-group">
+            <h3>Clip</h3>
+          <div class="midi-inline-fields">
+            <label class="midi-field midi-field--compact">
+              <span>Name</span>
+              <input id="midiClipName" type="text" />
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Type</span>
+              <select id="midiClipType">
+                <option value="stepPattern">Steps</option>
+                <option value="chord">Chord</option>
+                <option value="arp">Arp</option>
+              </select>
+            </label>
+            <label id="midiClipArpModeField" class="midi-field midi-field--compact">
+              <span>Arp</span>
+              <select id="midiClipArpMode">
+                <option value="up">Up</option>
+                <option value="down">Down</option>
+                <option value="updown">Up/Down</option>
+              </select>
+            </label>
+            <label id="midiClipArpPatternField" class="midi-field midi-field--compact">
+              <span>Pattern</span>
+              <select id="midiClipArpPattern">
+                <option value="up">Up</option>
+                <option value="down">Down</option>
+                <option value="updown">Up/Down</option>
+                <option value="custom">Custom</option>
+              </select>
+            </label>
+            <label class="midi-field midi-field--compact">
+              <span>Steps</span>
+              <input id="midiClipLengthSteps" type="number" min="1" max="32" step="1" />
+            </label>
+          </div>
+          <div id="midiRecordPanel" class="midi-learn-panel" aria-live="polite">
+            <div id="midiRecordStatus" class="midi-learn-status" role="status">Record writes captured notes into clip steps.</div>
+            <div class="midi-button-row">
+              <button id="midiRecordButton" type="button" aria-label="Start MIDI recording">Record</button>
+              <button id="midiRecordCommitButton" type="button" aria-label="Commit MIDI recording">Commit</button>
+              <button id="midiRecordCancelButton" type="button" aria-label="Cancel MIDI recording">Cancel</button>
+            </div>
+          </div>
+          <div id="midiStepPatternGrid" class="midi-step-grid" role="grid" aria-label="Step pattern"></div>
+        </div>
+      </section>
+      <section id="midiOutputStatus" class="midi-region midi-output-status" aria-label="MIDI output status">
+        <div id="midiSchedulerPressure" role="status" aria-live="polite">Scheduler: idle</div>
+        <div id="midiOutputLog" class="midi-output-log" role="status" aria-live="polite">No output yet</div>
+      </section>
     </div>
   </div>
   <div id="etc" style="color:#fff; position: absolute; bottom:0; left: 0;">
@@ -242,27 +539,38 @@
         </div>
       </div>
       <span id="levelName" class="level_name"></span>
-      <img class="arrow_l" src="img/arrow_l.png" width="37" height="58" onclick="lemmings.moveToLevel(-1)"/>
-      <img class="arrow_r" src="img/arrow_r.png" width="37" height="58" onclick="lemmings.moveToLevel(1)"/>
+      <img
+        id="levelPrevButton"
+        class="arrow_l"
+        src="img/arrow_l.png"
+        width="37"
+        height="58"
+        alt="Previous level"
+        role="button"
+        tabindex="0"
+        aria-label="Previous level"
+      />
+      <img
+        id="levelNextButton"
+        class="arrow_r"
+        src="img/arrow_r.png"
+        width="37"
+        height="58"
+        alt="Next level"
+        role="button"
+        tabindex="0"
+        aria-label="Next level"
+      />
     </div>
   </div>
   <div id="shortcutOverlay" class="shortcut-overlay" aria-hidden="true">
-    <div class="shortcut-overlay__panel" role="dialog" aria-modal="true">
+    <div class="shortcut-overlay__panel" role="dialog" aria-modal="true" aria-labelledby="shortcutOverlayTitle">
       <div class="shortcut-overlay__header">
-        <div class="shortcut-overlay__title">Game Shortcuts</div>
+        <div class="shortcut-overlay__title" id="shortcutOverlayTitle">Game Shortcuts</div>
         <button type="button" class="shortcut-overlay__close">Close</button>
       </div>
       <div class="shortcut-overlay__content"></div>
     </div>
   </div>
-  <script>
-    if (!navigator.webdriver) {
-      const statsPixel = document.createElement('img');
-      statsPixel.src = 'https://sneakyness.com/stats/lemmings-MIDI';
-      statsPixel.alt = '';
-      statsPixel.style.display = 'none';
-      document.body.appendChild(statsPixel);
-    }
-  </script>
 </body>
 </html>
diff --git a/js/actions/ActionBaseSystem.js b/js/actions/ActionBaseSystem.js
index 3e63187e..a4616fb7 100644
--- a/js/actions/ActionBaseSystem.js
+++ b/js/actions/ActionBaseSystem.js
@@ -13,10 +13,11 @@ class ActionBaseSystem {
      * @param {*} [options.masks] Mask provider
      * @param {*} [options.maskTypes] mask type or {left, right} pair
      */
-  constructor({sprites=null, spriteType=null, singleSprite=false, masks=null, maskTypes=null, actionName=null} = {}) {
+  constructor({sprites=null, spriteType=null, singleSprite=false, masks=null, maskTypes=null, actionName=null, runtime=null} = {}) {
     this.sprites = null;
     this.masks   = null;
     this.actionName = actionName || '';
+    this.runtime = runtime;
 
     if (sprites && spriteType !== null) {
       const cacheKey = this.actionName || spriteType;
@@ -59,6 +60,10 @@ class ActionBaseSystem {
     }
   }
 
+  setRuntime(runtime = null) {
+    this.runtime = runtime;
+  }
+
   /** Default implementation simply returns configured actionName. */
   getActionName() {
     return this.actionName || '';
diff --git a/js/actions/ActionBashSystem.js b/js/actions/ActionBashSystem.js
index 96bb3248..8eb23a64 100644
--- a/js/actions/ActionBashSystem.js
+++ b/js/actions/ActionBashSystem.js
@@ -1,8 +1,9 @@
 import { ActionBaseSystem } from './ActionBaseSystem.js';
-import { SoundEventTypes, SoundEffectIds, getSoundBus } from '../game/SoundEvents.js';
+import { SoundEventTypes, SoundEffectIds } from '../game/SoundEvents.js';
 import { LemmingStateType } from '../lemmings/LemmingStateType.js';
 import { MaskTypes } from '../render/MaskTypes.js';
 import { SpriteTypes } from '../lemmings/SpriteTypes.js';
+import { getRuntimeSoundEvents } from '../game/GameRuntime.js';
 
 const clamp = (value, min, max) => Math.max(min, Math.min(max, value));
 const countClearable = (mask) => {
@@ -42,7 +43,7 @@ class ActionBashSystem extends ActionBaseSystem {
       lem.x += (lem.lookRight ? 1 : -1);
       const yDelta = this.findGapDelta(groundMask, lem.x, lem.y);
       lem.y += yDelta;
-      if (yDelta == 3) {
+      if (yDelta === 3) {
         return LemmingStateType.FALLING;
       }
     }
@@ -52,7 +53,7 @@ class ActionBashSystem extends ActionBaseSystem {
       const subMask = this.masks.get(lem.getDirection()).GetMask(state - 2);
       if (state === 3) {
         if (level.hasSteelUnderMask(subMask, lem.x, lem.y)) {
-          const soundBus = getSoundBus();
+          const soundBus = getRuntimeSoundEvents(this.runtime);
           soundBus?.emitSfx?.(
             SoundEventTypes.STEEL_HIT,
             SoundEffectIds.STEEL_HIT,
@@ -60,7 +61,7 @@ class ActionBashSystem extends ActionBaseSystem {
           );
           return LemmingStateType.SHRUG;
         }
-        if (level.hasArrowUnderMask(subMask, lem.x, lem.y, lem.lookRight)) {    
+        if (level.hasArrowUnderMask(subMask, lem.x, lem.y, lem.lookRight)) {
           return LemmingStateType.SHRUG;
         }
       }
@@ -69,7 +70,7 @@ class ActionBashSystem extends ActionBaseSystem {
         : (level.clearGroundWithMask(subMask, lem.x, lem.y), 0);
       const intensity = scaleIntensity(removed, countClearable(subMask));
       if (removed > 0) {
-        const soundBus = getSoundBus();
+        const soundBus = getRuntimeSoundEvents(this.runtime);
         soundBus?.emitSfx?.(
           SoundEventTypes.LEMMING_BASH,
           SoundEffectIds.BASH,
@@ -85,16 +86,16 @@ class ActionBashSystem extends ActionBaseSystem {
     }
 
     // check if end of solid
-    if (state == 5) {
+    if (state === 5) {
       if (this.findHorizontalSpace(groundMask, lem.x + (lem.lookRight ? 8 : -8),
-        lem.y - 6, lem.lookRight) == 4) {
+        lem.y - 6, lem.lookRight) === 4) {
         return LemmingStateType.WALKING;
       }
     }
 
     return LemmingStateType.NO_STATE_TYPE;
   }
-  
+
   findGapDelta(groundMask, x, y) {
     for (let i = 0; i < 3; i++) {
       if (groundMask.hasGroundAt(x, y + i)) {
diff --git a/js/actions/ActionBlockerSystem.js b/js/actions/ActionBlockerSystem.js
index 45efc3f8..ed593f18 100644
--- a/js/actions/ActionBlockerSystem.js
+++ b/js/actions/ActionBlockerSystem.js
@@ -12,7 +12,7 @@ class ActionBlockerSystem extends ActionBaseSystem {
   }
 
   process(level, lem) {
-    if (lem.state == 0) {
+    if (lem.state === 0) {
       const trigger1 = new Trigger(TriggerTypes.BLOCKER_LEFT, lem.x - 6, lem.y + 4, lem.x - 3, lem.y - 10, 0, 0, lem);
       const trigger2 = new Trigger(TriggerTypes.BLOCKER_RIGHT, lem.x + 7, lem.y + 4, lem.x + 4, lem.y - 10, 0, 0, lem);
       this.triggerManager.add(trigger1);
diff --git a/js/actions/ActionBuildSystem.js b/js/actions/ActionBuildSystem.js
index b42be870..23beb6f5 100644
--- a/js/actions/ActionBuildSystem.js
+++ b/js/actions/ActionBuildSystem.js
@@ -1,21 +1,34 @@
 import { ActionBaseSystem } from './ActionBaseSystem.js';
-import { SoundEventTypes, SoundEffectIds, getSoundBus } from '../game/SoundEvents.js';
+import { SoundEventTypes, SoundEffectIds } from '../game/SoundEvents.js';
 import { LemmingStateType } from '../lemmings/LemmingStateType.js';
 import { SpriteTypes } from '../lemmings/SpriteTypes.js';
+import { getRuntimeSoundEvents } from '../game/GameRuntime.js';
 
 class ActionBuildSystem extends ActionBaseSystem {
   constructor(sprites) {
     super({ sprites, spriteType: SpriteTypes.BUILDING, actionName: 'building' });
   }
   process(level, lem) {
+    const levelWidth = Number.isFinite(level?.width) ? level.width : null;
+    const levelHeight = Number.isFinite(level?.height) ? level.height : null;
+    const inHorizontalBounds = (x) => levelWidth == null || (x >= 0 && x < levelWidth);
+    const inVerticalBounds = (y) => levelHeight == null || (y >= 0 && y < levelHeight);
+    const hitsOpposingArrow = (x, y) => (
+      typeof level?.isArrowAt === 'function' &&
+      level.isArrowAt(x, y, lem.lookRight)
+    );
+
     lem.frameIndex = (lem.frameIndex + 1) % 16;
-    if (lem.frameIndex == 9) {
+    if (lem.frameIndex === 9) {
       /// lay brick
       const startX = lem.x + (lem.lookRight ? 0 : -4);
+      const brickY = lem.y - 1;
       for (let i = 0; i < 6; i++) {
-        level.setGroundAt(startX + i, lem.y - 1, 7);
+        const brickX = startX + i;
+        if (!inHorizontalBounds(brickX) || !inVerticalBounds(brickY)) continue;
+        level.setGroundAt(brickX, brickY, 7);
       }
-      const soundBus = getSoundBus();
+      const soundBus = getRuntimeSoundEvents(this.runtime);
       soundBus?.emitSfx?.(
         SoundEventTypes.BUILDER_STEP,
         SoundEffectIds.BUILDER_STEP,
@@ -30,17 +43,36 @@ class ActionBuildSystem extends ActionBaseSystem {
       }
       return LemmingStateType.NO_STATE_TYPE;
     }
-    if (lem.frameIndex == 0) {
+    if (lem.frameIndex === 0) {
       lem.y--;
       for (let i = 0; i < 2; i++) {
-        lem.x += (lem.lookRight ? 1 : -1);
+        const nextX = lem.x + (lem.lookRight ? 1 : -1);
+        if (!inHorizontalBounds(nextX)) {
+          lem.lookRight = !lem.lookRight;
+          return LemmingStateType.WALKING;
+        }
+        if (hitsOpposingArrow(nextX, lem.y - 1)) {
+          // One-way walls should reflect builders without dropping them to walk.
+          lem.lookRight = !lem.lookRight;
+          return LemmingStateType.NO_STATE_TYPE;
+        }
+        lem.x = nextX;
         if (level.hasGroundAt(lem.x, lem.y - 1)) {
           lem.lookRight = !lem.lookRight;
           return LemmingStateType.WALKING;
         }
       }
       if (++lem.state >= 12) return LemmingStateType.SHRUG;
-      if (level.hasGroundAt(lem.x + (lem.lookRight ? 2 : -2), lem.y - 9)) {
+      const nextHeadX = lem.x + (lem.lookRight ? 2 : -2);
+      if (!inHorizontalBounds(nextHeadX)) {
+        lem.lookRight = !lem.lookRight;
+        return LemmingStateType.WALKING;
+      }
+      if (hitsOpposingArrow(nextHeadX, lem.y - 9)) {
+        lem.lookRight = !lem.lookRight;
+        return LemmingStateType.NO_STATE_TYPE;
+      }
+      if (level.hasGroundAt(nextHeadX, lem.y - 9)) {
         lem.lookRight = !lem.lookRight;
         return LemmingStateType.WALKING;
       }
diff --git a/js/actions/ActionCountdownSystem.js b/js/actions/ActionCountdownSystem.js
index bb5408a3..f7851b26 100644
--- a/js/actions/ActionCountdownSystem.js
+++ b/js/actions/ActionCountdownSystem.js
@@ -1,13 +1,14 @@
 import { ActionBaseSystem } from './ActionBaseSystem.js';
-import { SoundEventTypes, SoundEffectIds, getSoundBus } from '../game/SoundEvents.js';
+import { SoundEventTypes, SoundEffectIds } from '../game/SoundEvents.js';
 import { LemmingStateType } from '../lemmings/LemmingStateType.js';
 import { MaskTypes } from '../render/MaskTypes.js';
+import { getRuntimeSoundEvents } from '../game/GameRuntime.js';
 
 class ActionCountdownSystem extends ActionBaseSystem {
   static numberMasks = new Map();
   constructor(masks) {
     super({ actionName: 'countdown' });
-    if (ActionCountdownSystem.numberMasks.size == 0) {
+    if (ActionCountdownSystem.numberMasks.size === 0) {
       ActionCountdownSystem.numberMasks.set('numbers', masks.GetMask(MaskTypes.NUMBERS));
     }
   }
@@ -30,9 +31,9 @@ class ActionCountdownSystem extends ActionBaseSystem {
       return LemmingStateType.NO_STATE_TYPE;
     }
     lem.countdown--;
-    if (lem.countdown == 0) {
+    if (lem.countdown === 0) {
       lem.setCountDown(null);
-      const soundBus = getSoundBus();
+      const soundBus = getRuntimeSoundEvents(this.runtime);
       soundBus?.emitSfx?.(
         SoundEventTypes.LEMMING_OHNO,
         SoundEffectIds.OHNO,
diff --git a/js/actions/ActionDiggSystem.js b/js/actions/ActionDiggSystem.js
index 9b1d7c80..3d607c9a 100644
--- a/js/actions/ActionDiggSystem.js
+++ b/js/actions/ActionDiggSystem.js
@@ -1,8 +1,9 @@
 import { ActionBaseSystem } from './ActionBaseSystem.js';
-import { SoundEventTypes, SoundEffectIds, getSoundBus } from '../game/SoundEvents.js';
+import { SoundEventTypes, SoundEffectIds } from '../game/SoundEvents.js';
 import { LemmingStateType } from '../lemmings/LemmingStateType.js';
 import { SpriteTypes } from '../lemmings/SpriteTypes.js';
-        
+import { getRuntimeSoundEvents } from '../game/GameRuntime.js';
+
 const clamp = (value, min, max) => Math.max(min, Math.min(max, value));
 const scaleIntensity = (removed, maxCount) => {
   if (!removed || removed <= 0) return 1;
@@ -19,7 +20,7 @@ class ActionDiggSystem extends ActionBaseSystem {
     if (level.isSteelGround(lem.x, lem.y) ||
                 level.isSteelGround(lem.x, lem.y - 1) ||
                 level.isSteelGround(lem.x, lem.y - 2)) {
-      const soundBus = getSoundBus();
+      const soundBus = getRuntimeSoundEvents(this.runtime);
       soundBus?.emitSfx?.(
         SoundEventTypes.STEEL_HIT,
         SoundEffectIds.STEEL_HIT,
@@ -27,7 +28,7 @@ class ActionDiggSystem extends ActionBaseSystem {
       );
       return LemmingStateType.SHRUG;
     }
-    if (lem.state == 0) {
+    if (lem.state === 0) {
       this.digRow(level, lem, lem.y - 2);
       this.digRow(level, lem, lem.y - 1);
       lem.state = 1;
@@ -46,6 +47,25 @@ class ActionDiggSystem extends ActionBaseSystem {
     return LemmingStateType.NO_STATE_TYPE;
   }
   digRow(level, lem, y) {
+    if (typeof level.clearGroundRow === 'function') {
+      const removed = level.clearGroundRow(lem.x - 4, y, 9);
+      const intensity = scaleIntensity(removed, 9);
+      if (removed > 0) {
+        const soundBus = getRuntimeSoundEvents(this.runtime);
+        soundBus?.emitSfx?.(
+          SoundEventTypes.LEMMING_DIG,
+          SoundEffectIds.DIG,
+          {
+            lemmingId: lem.id,
+            x: lem.x,
+            y,
+            removed,
+            intensity
+          }
+        );
+      }
+      return removed > 0;
+    }
     let removeCount = 0;
     for (let x = lem.x - 4; x < lem.x + 5; x++) {
       if (level.hasGroundAt(x, y)) {
@@ -55,7 +75,7 @@ class ActionDiggSystem extends ActionBaseSystem {
     }
     const intensity = scaleIntensity(removeCount, 9);
     if (removeCount > 0) {
-      const soundBus = getSoundBus();
+      const soundBus = getRuntimeSoundEvents(this.runtime);
       soundBus?.emitSfx?.(
         SoundEventTypes.LEMMING_DIG,
         SoundEffectIds.DIG,
diff --git a/js/actions/ActionDrowningSystem.js b/js/actions/ActionDrowningSystem.js
index 680e3355..f65b6aa4 100644
--- a/js/actions/ActionDrowningSystem.js
+++ b/js/actions/ActionDrowningSystem.js
@@ -1,7 +1,8 @@
 import { ActionBaseSystem } from './ActionBaseSystem.js';
-import { SoundEventTypes, SoundEffectIds, getSoundBus } from '../game/SoundEvents.js';
+import { SoundEventTypes, SoundEffectIds } from '../game/SoundEvents.js';
 import { LemmingStateType } from '../lemmings/LemmingStateType.js';
 import { SpriteTypes } from '../lemmings/SpriteTypes.js';
+import { getRuntimeMiniMap, getRuntimeSoundEvents } from '../game/GameRuntime.js';
 
 class ActionDrowningSystem extends ActionBaseSystem {
   constructor(sprites) {
@@ -13,15 +14,14 @@ class ActionDrowningSystem extends ActionBaseSystem {
   draw(gameDisplay, lem) {
     super.draw(gameDisplay, lem);
     if (lem.frameIndex === 15) {
-      const miniMap = globalThis?.lemmings?.game?.lemmingManager?.miniMap;
-      if (miniMap) miniMap.addDeath(lem.x, lem.y);
+      getRuntimeMiniMap(this.runtime)?.addDeath(lem.x, lem.y);
     }
   }
   process(level, lem) {
     lem.disable();
     if (lem.frameIndex === 0) {
       const triggerType = lem.lastTriggerType ?? null;
-      const soundBus = getSoundBus();
+      const soundBus = getRuntimeSoundEvents(this.runtime);
       soundBus?.emitSfx?.(
         SoundEventTypes.LEMMING_DROWN,
         SoundEffectIds.DROWN,
diff --git a/js/actions/ActionExitingSystem.js b/js/actions/ActionExitingSystem.js
index 0c183266..ad126dd6 100644
--- a/js/actions/ActionExitingSystem.js
+++ b/js/actions/ActionExitingSystem.js
@@ -1,7 +1,8 @@
 import { ActionBaseSystem } from './ActionBaseSystem.js';
-import { SoundEventTypes, SoundEffectIds, getSoundBus } from '../game/SoundEvents.js';
+import { SoundEventTypes, SoundEffectIds } from '../game/SoundEvents.js';
 import { LemmingStateType } from '../lemmings/LemmingStateType.js';
 import { SpriteTypes } from '../lemmings/SpriteTypes.js';
+import { getRuntimeSoundEvents } from '../game/GameRuntime.js';
 
 class ActionExitingSystem extends ActionBaseSystem {
   constructor(sprites, gameVictoryCondition) {
@@ -18,7 +19,7 @@ class ActionExitingSystem extends ActionBaseSystem {
     lem.disable();
     if (lem.frameIndex === 0) {
       const triggerType = lem.lastTriggerType ?? null;
-      const soundBus = getSoundBus();
+      const soundBus = getRuntimeSoundEvents(this.runtime);
       soundBus?.emitSfx?.(
         SoundEventTypes.LEMMING_EXIT,
         SoundEffectIds.EXIT,
diff --git a/js/actions/ActionExplodingSystem.js b/js/actions/ActionExplodingSystem.js
index 904b2bc4..a8509648 100644
--- a/js/actions/ActionExplodingSystem.js
+++ b/js/actions/ActionExplodingSystem.js
@@ -1,8 +1,9 @@
 import { ActionBaseSystem } from './ActionBaseSystem.js';
-import { SoundEventTypes, SoundEffectIds, getSoundBus } from '../game/SoundEvents.js';
+import { SoundEventTypes, SoundEffectIds } from '../game/SoundEvents.js';
 import { LemmingStateType } from '../lemmings/LemmingStateType.js';
 import { MaskTypes } from '../render/MaskTypes.js';
 import { SpriteTypes } from '../lemmings/SpriteTypes.js';
+import { getRuntimeMiniMap, getRuntimeSoundEvents } from '../game/GameRuntime.js';
 
 class ActionExplodingSystem extends ActionBaseSystem {
 
@@ -25,7 +26,7 @@ class ActionExplodingSystem extends ActionBaseSystem {
   }
 
   draw(gameDisplay, lem) {
-    if (lem.frameIndex == 0) {
+    if (lem.frameIndex === 0) {
       const ani = this.sprites.get('both');
       const frame = ani.getFrame(lem.frameIndex);
       gameDisplay.drawFrame(frame, lem.x-10, lem.y-8);
@@ -37,7 +38,7 @@ class ActionExplodingSystem extends ActionBaseSystem {
   process(level, lem) {
     lem.disable();
     if (lem.frameIndex === 0) {
-      const soundBus = getSoundBus();
+      const soundBus = getRuntimeSoundEvents(this.runtime);
       soundBus?.emitSfx?.(
         SoundEventTypes.LEMMING_EXPLODE,
         SoundEffectIds.EXPLOSION,
@@ -45,11 +46,11 @@ class ActionExplodingSystem extends ActionBaseSystem {
       );
     }
     lem.frameIndex++;
-    if (lem.frameIndex == 1) {
+    if (lem.frameIndex === 1) {
       this.triggerManager.removeByOwner(lem);
       const mask = this.masks.get('both').GetMask(0);
-      const changed = level.clearGroundWithMask(mask, lem.x, lem.y);
-      const miniMap = globalThis?.lemmings?.game?.lemmingManager?.miniMap;
+      const changed = level.clearGroundWithMask(mask, lem.x, lem.y, { revealSteel: true });
+      const miniMap = getRuntimeMiniMap(this.runtime);
       if (changed && miniMap) {
         miniMap.invalidateRegion(
           lem.x + mask.offsetX,
@@ -60,7 +61,7 @@ class ActionExplodingSystem extends ActionBaseSystem {
       }
       if (miniMap) miniMap.addDeath(lem.x, lem.y);
     }
-    if (lem.frameIndex == 52) {
+    if (lem.frameIndex === 52) {
       return LemmingStateType.OUT_OF_LEVEL;
     }
     return LemmingStateType.NO_STATE_TYPE;
diff --git a/js/actions/ActionFallSystem.js b/js/actions/ActionFallSystem.js
index 9deeed84..50eabfc7 100644
--- a/js/actions/ActionFallSystem.js
+++ b/js/actions/ActionFallSystem.js
@@ -26,7 +26,7 @@ class ActionFallSystem extends ActionBaseSystem {
       }
     }
     lem.y += i;
-    if (i == 3) {
+    if (i === 3) {
       lem.state += i;
       return LemmingStateType.NO_STATE_TYPE;
     } else {
diff --git a/js/actions/ActionFryingSystem.js b/js/actions/ActionFryingSystem.js
index 9cf24cd3..962730b0 100644
--- a/js/actions/ActionFryingSystem.js
+++ b/js/actions/ActionFryingSystem.js
@@ -1,6 +1,7 @@
 import { ActionBaseSystem } from './ActionBaseSystem.js';
 import { LemmingStateType } from '../lemmings/LemmingStateType.js';
 import { SpriteTypes } from '../lemmings/SpriteTypes.js';
+import { getRuntimeMiniMap } from '../game/GameRuntime.js';
 
 class ActionFryingSystem extends ActionBaseSystem {
   constructor(sprites) {
@@ -22,10 +23,9 @@ class ActionFryingSystem extends ActionBaseSystem {
     }
     lem.frameIndex++;
     if (lem.frameIndex === 13) {
-      const miniMap = globalThis?.lemmings?.game?.lemmingManager?.miniMap;
-      if (miniMap) miniMap.addDeath(lem.x, lem.y);
+      getRuntimeMiniMap(this.runtime)?.addDeath(lem.x, lem.y);
     }
-    if (lem.frameIndex == 14) {
+    if (lem.frameIndex === 14) {
       return LemmingStateType.OUT_OF_LEVEL;
     }
     if (!level.hasGroundAt(lem.x + (lem.lookRight ? 8 : -8), lem.y)) {
diff --git a/js/actions/ActionJumpSystem.js b/js/actions/ActionJumpSystem.js
index 15c5d8e4..b2d1a3b7 100644
--- a/js/actions/ActionJumpSystem.js
+++ b/js/actions/ActionJumpSystem.js
@@ -20,7 +20,7 @@ class ActionJumpSystem extends ActionBaseSystem {
     lem.frameIndex++;
     lem.x += (lem.lookRight ? 1 : -1);
 
-    if (lem.state == null) {
+    if (lem.state === null || lem.state === undefined) {
       lem.state = 0; // how far we've jumped so far
     }
 
diff --git a/js/actions/ActionMineSystem.js b/js/actions/ActionMineSystem.js
index 66351efb..5f78d182 100644
--- a/js/actions/ActionMineSystem.js
+++ b/js/actions/ActionMineSystem.js
@@ -1,8 +1,9 @@
 import { ActionBaseSystem } from './ActionBaseSystem.js';
-import { SoundEventTypes, SoundEffectIds, getSoundBus } from '../game/SoundEvents.js';
+import { SoundEventTypes, SoundEffectIds } from '../game/SoundEvents.js';
 import { LemmingStateType } from '../lemmings/LemmingStateType.js';
 import { MaskTypes } from '../render/MaskTypes.js';
 import { SpriteTypes } from '../lemmings/SpriteTypes.js';
+import { getRuntimeSoundEvents } from '../game/GameRuntime.js';
 
 const clamp = (value, min, max) => Math.max(min, Math.min(max, value));
 const countClearable = (mask) => {
@@ -41,7 +42,7 @@ class ActionMineSystem extends ActionBaseSystem {
       let maskIndex = lem.frameIndex - 1;
       let subMask   = mask.GetMask(maskIndex);
       if (level.hasSteelUnderMask(subMask, lem.x, lem.y)) {
-        const soundBus = getSoundBus();
+        const soundBus = getRuntimeSoundEvents(this.runtime);
         soundBus?.emitSfx?.(
           SoundEventTypes.STEEL_HIT,
           SoundEffectIds.STEEL_HIT,
@@ -49,7 +50,7 @@ class ActionMineSystem extends ActionBaseSystem {
         );
         return LemmingStateType.SHRUG;
       }
-      if (level.hasArrowUnderMask(subMask, lem.x, lem.y, lem.lookRight)) {      
+      if (level.hasArrowUnderMask(subMask, lem.x, lem.y, lem.lookRight)) {
         return LemmingStateType.SHRUG;
       }
       const removed = typeof level.clearGroundWithMaskCount === 'function'
@@ -57,7 +58,7 @@ class ActionMineSystem extends ActionBaseSystem {
         : (level.clearGroundWithMask(subMask, lem.x, lem.y), 0);
       const intensity = scaleIntensity(removed, countClearable(subMask));
       if (removed > 0) {
-        const soundBus = getSoundBus();
+        const soundBus = getRuntimeSoundEvents(this.runtime);
         soundBus?.emitSfx?.(
           SoundEventTypes.LEMMING_MINE,
           SoundEffectIds.MINE,
diff --git a/js/actions/ActionOhNoSystem.js b/js/actions/ActionOhNoSystem.js
index 5cabf2a1..d4822bf8 100644
--- a/js/actions/ActionOhNoSystem.js
+++ b/js/actions/ActionOhNoSystem.js
@@ -1,7 +1,8 @@
 import { ActionBaseSystem } from './ActionBaseSystem.js';
 import { LemmingStateType } from '../lemmings/LemmingStateType.js';
 import { SpriteTypes } from '../lemmings/SpriteTypes.js';
-    
+import { getRuntimeMiniMap } from '../game/GameRuntime.js';
+
 class ActionOhNoSystem extends ActionBaseSystem {
   constructor(sprites) {
     super({ sprites, spriteType: SpriteTypes.OHNO, singleSprite: true, actionName: 'oh-no' });
@@ -14,16 +15,15 @@ class ActionOhNoSystem extends ActionBaseSystem {
   draw(gameDisplay, lem) {
     super.draw(gameDisplay, lem);
     if (lem.frameIndex === 15) {
-      const miniMap = globalThis?.lemmings?.game?.lemmingManager?.miniMap;
-      if (miniMap) miniMap.addDeath(lem.x, lem.y);
+      getRuntimeMiniMap(this.runtime)?.addDeath(lem.x, lem.y);
     }
   }
-    
+
   process(level, lem) {
-    if (++lem.frameIndex == 16) {
+    if (++lem.frameIndex === 16) {
       return LemmingStateType.EXPLODING;
     }
-        
+
     // fall down!
     for (let i = 0; i < 3; i++) {
       if (!level.hasGroundAt(lem.x, lem.y + 1)) {
diff --git a/js/actions/ActionSplatterSystem.js b/js/actions/ActionSplatterSystem.js
index 30cbccf7..3ffa28da 100644
--- a/js/actions/ActionSplatterSystem.js
+++ b/js/actions/ActionSplatterSystem.js
@@ -1,9 +1,10 @@
 import { ActionBaseSystem } from './ActionBaseSystem.js';
-import { SoundEventTypes, SoundEffectIds, getSoundBus } from '../game/SoundEvents.js';
+import { SoundEventTypes, SoundEffectIds } from '../game/SoundEvents.js';
 import { LemmingStateType } from '../lemmings/LemmingStateType.js';
 import { SpriteTypes } from '../lemmings/SpriteTypes.js';
 import { TriggerTypes } from '../level/TriggerTypes.js';
-        
+import { getRuntimeMiniMap, getRuntimeSoundEvents } from '../game/GameRuntime.js';
+
 class ActionSplatterSystem extends ActionBaseSystem {
   constructor(sprites) {
     super({ sprites, spriteType: SpriteTypes.SPLATTING, singleSprite: true, actionName: 'splatter' });
@@ -14,8 +15,7 @@ class ActionSplatterSystem extends ActionBaseSystem {
   draw(gameDisplay, lem) {
     super.draw(gameDisplay, lem);
     if (lem.frameIndex === 15) {
-      const miniMap = globalThis?.lemmings?.game?.lemmingManager?.miniMap;
-      if (miniMap) miniMap.addDeath(lem.x, lem.y);
+      getRuntimeMiniMap(this.runtime)?.addDeath(lem.x, lem.y);
     }
   }
   process(level, lem) {
@@ -26,7 +26,7 @@ class ActionSplatterSystem extends ActionBaseSystem {
             triggerType === TriggerTypes.TRAP ||
             triggerType === TriggerTypes.KILL;
       if (!isTrapDeath) {
-        const soundBus = getSoundBus();
+        const soundBus = getRuntimeSoundEvents(this.runtime);
         soundBus?.emitSfx?.(
           SoundEventTypes.LEMMING_SPLAT,
           SoundEffectIds.SPLAT,
diff --git a/js/actions/ActionWalkSystem.js b/js/actions/ActionWalkSystem.js
index 50e11130..44c41e56 100644
--- a/js/actions/ActionWalkSystem.js
+++ b/js/actions/ActionWalkSystem.js
@@ -17,7 +17,7 @@ class ActionWalkSystem extends ActionBaseSystem {
 
     const groundMask = level.getGroundMaskLayer();
     const upDelta = groundMask.getColumnStepHeight(lem.x, lem.y - 7, 8);
-    if (upDelta == 8) {
+    if (upDelta === 8) {
       // collision with obstacle
       lem.x = prevX; // revert movement into wall
       if (lem.canClimb) {
@@ -40,7 +40,7 @@ class ActionWalkSystem extends ActionBaseSystem {
     } else {
       let downDelta = groundMask.getColumnGapDepth(lem.x, lem.y + 1, 3);
       lem.y += downDelta;
-      if (downDelta == 4) {
+      if (downDelta === 4) {
         return LemmingStateType.FALLING;
       } else {
         return LemmingStateType.NO_STATE_TYPE;
diff --git a/js/app/analytics.js b/js/app/analytics.js
new file mode 100644
index 00000000..796902a0
--- /dev/null
+++ b/js/app/analytics.js
@@ -0,0 +1,581 @@
+import { DEFAULT_RUNTIME_PROFILE, normalizeRuntimeProfile } from '../core/runtimeProfiles.js';
+
+const ANALYTICS_SCHEMA_VERSION = 1;
+const DEFAULT_ANALYTICS_BUFFER_CAPACITY = 256;
+const MAX_ANALYTICS_BUFFER_CAPACITY = 4096;
+const MAX_ANALYTICS_IMPORT_EVENTS = 4096;
+
+const analyticsStorageKeys = Object.freeze({
+  consent: 'lemmings.analytics.consent.v1',
+  buffer: 'lemmings.analytics.buffer.v1'
+});
+
+const ANALYTICS_EVENT_TYPES = Object.freeze({
+  VISITOR_PAGE_VIEW: 'visitor.page_view',
+  GAMEPLAY_LEVEL_SELECT: 'gameplay.level_select',
+  GAMEPLAY_MIDI_TOGGLE: 'gameplay.midi_toggle',
+  GAMEPLAY_SAVED_LEVEL: 'gameplay.saved_level',
+  EDITOR_ACTION: 'editor.action',
+  RUNTIME_BOOT_ERROR: 'runtime.boot_error'
+});
+
+const ALLOWED_SURFACES = new Set(['game', 'editor', 'procgen']);
+const ALLOWED_LEVEL_SELECT_CONTROLS = new Set(['gameType', 'levelGroup', 'levelIndex']);
+const ALLOWED_SAVED_LEVEL_ACTIONS = new Set(['save', 'export', 'import', 'load']);
+const ALLOWED_EDITOR_ACTIONS = new Set(['new', 'save', 'export', 'import', 'playtest']);
+const ALLOWED_BOOT_ERROR_CODES = new Set(['boot_error', 'midi_error', 'resource_error']);
+
+const BOOL_TRUE_VALUES = new Set(['', '1', 'true', 'yes', 'on', 'enabled', 'enable', 'granted', 'grant']);
+const BOOL_FALSE_VALUES = new Set(['0', 'false', 'no', 'off', 'disabled', 'disable', 'denied', 'deny']);
+
+const clampInt = (value, min, max, fallback = null) => {
+  const num = Number(value);
+  if (!Number.isFinite(num)) return fallback;
+  const truncated = Math.trunc(num);
+  if (truncated < min) return min;
+  if (truncated > max) return max;
+  return truncated;
+};
+
+const parseBoolish = (value) => {
+  if (value == null) return null;
+  const normalized = String(value).trim().toLowerCase();
+  if (BOOL_TRUE_VALUES.has(normalized)) return true;
+  if (BOOL_FALSE_VALUES.has(normalized)) return false;
+  return null;
+};
+
+const parseSampleRate = (value, fallback = 1) => {
+  const num = Number(value);
+  if (!Number.isFinite(num)) return fallback;
+  if (num <= 0) return 0;
+  if (num >= 1) return 1;
+  return num;
+};
+
+const asObject = (value) => (
+  value && typeof value === 'object' && !Array.isArray(value) ? value : {}
+);
+
+const sanitizeSurface = (value, fallback = 'game') => {
+  const normalized = String(value || '').trim().toLowerCase();
+  if (ALLOWED_SURFACES.has(normalized)) return normalized;
+  return fallback;
+};
+
+const sanitizeProfile = (value, fallback = DEFAULT_RUNTIME_PROFILE) => {
+  return normalizeRuntimeProfile(value || fallback);
+};
+
+const sanitizePath = (value, fallback = '/') => {
+  const raw = String(value || '').trim();
+  if (!raw) return fallback;
+  const withoutQuery = raw.split('?')[0].split('#')[0];
+  const path = withoutQuery.startsWith('/') ? withoutQuery : `/${withoutQuery}`;
+  return path.slice(0, 120) || fallback;
+};
+
+const sanitizeBootErrorCode = (value) => {
+  const normalized = String(value || '').trim().toLowerCase();
+  if (ALLOWED_BOOT_ERROR_CODES.has(normalized)) return normalized;
+  return 'boot_error';
+};
+
+const sanitizeBeaconEndpoint = (value) => {
+  const raw = String(value || '').trim();
+  if (!raw) return '';
+  if (!/^https?:\/\//i.test(raw)) return '';
+  return raw.slice(0, 512);
+};
+
+const readQueryValue = (params, names = []) => {
+  if (!params) return null;
+  for (const name of names) {
+    if (!params.has(name)) continue;
+    return params.get(name);
+  }
+  return null;
+};
+
+const readMetaContent = (documentRef, name) => {
+  if (!documentRef?.querySelector) return null;
+  const node = documentRef.querySelector(`meta[name="${name}"]`);
+  const content = node?.getAttribute?.('content');
+  return content == null ? null : String(content);
+};
+
+const isDevLocation = (locationRef) => {
+  if (!locationRef) return false;
+  if (String(locationRef.protocol || '').toLowerCase() === 'file:') return true;
+  const host = String(locationRef.hostname || '').toLowerCase();
+  return host === 'localhost' || host === '127.0.0.1' || host === '::1' || host === '0.0.0.0';
+};
+
+const isHardDisabledByMeta = (value) => {
+  const normalized = String(value || '').trim().toLowerCase();
+  return normalized === 'off' || normalized === 'disabled' || normalized === 'hard-off' || normalized === 'hard_disabled';
+};
+
+const safeStorageGet = (storage, key) => {
+  try {
+    return storage?.getItem?.(key) ?? null;
+  } catch {
+    return null;
+  }
+};
+
+const safeStorageSet = (storage, key, value) => {
+  try {
+    storage?.setItem?.(key, value);
+  } catch {
+    // ignored
+  }
+};
+
+const safeStorageRemove = (storage, key) => {
+  try {
+    storage?.removeItem?.(key);
+  } catch {
+    // ignored
+  }
+};
+
+const readStoredConsent = (storage) => {
+  const value = safeStorageGet(storage, analyticsStorageKeys.consent);
+  if (value == null) return null;
+  if (value === 'granted') return true;
+  if (value === 'denied') return false;
+  const parsed = parseBoolish(value);
+  return parsed == null ? null : parsed;
+};
+
+const writeStoredConsent = (storage, granted) => {
+  if (granted === true) {
+    safeStorageSet(storage, analyticsStorageKeys.consent, 'granted');
+    return;
+  }
+  if (granted === false) {
+    safeStorageSet(storage, analyticsStorageKeys.consent, 'denied');
+    return;
+  }
+  safeStorageRemove(storage, analyticsStorageKeys.consent);
+};
+
+const createSessionId = (now, random) => {
+  const nowPart = clampInt(now(), 0, Number.MAX_SAFE_INTEGER, 0).toString(36);
+  const randPart = Math.trunc(Math.max(0, Math.min(1, random())) * 0x7fffffff).toString(36);
+  return `${nowPart}-${randPart}`;
+};
+
+const createRingBuffer = (capacity = DEFAULT_ANALYTICS_BUFFER_CAPACITY) => {
+  const cap = clampInt(capacity, 1, MAX_ANALYTICS_BUFFER_CAPACITY, DEFAULT_ANALYTICS_BUFFER_CAPACITY);
+  const entries = new Array(cap);
+  let start = 0;
+  let count = 0;
+
+  const push = (value) => {
+    if (!value) return;
+    const writeIndex = (start + count) % cap;
+    entries[writeIndex] = value;
+    if (count < cap) {
+      count += 1;
+      return;
+    }
+    start = (start + 1) % cap;
+  };
+
+  const clear = () => {
+    for (let i = 0; i < count; i += 1) {
+      entries[(start + i) % cap] = undefined;
+    }
+    start = 0;
+    count = 0;
+  };
+
+  const values = () => {
+    const out = new Array(count);
+    for (let i = 0; i < count; i += 1) {
+      out[i] = entries[(start + i) % cap];
+    }
+    return out;
+  };
+
+  const replace = (list) => {
+    clear();
+    if (!Array.isArray(list)) return;
+    for (const item of list) {
+      push(item);
+    }
+  };
+
+  return {
+    capacity: cap,
+    size: () => count,
+    push,
+    clear,
+    values,
+    replace
+  };
+};
+
+const sanitizeEventPayload = (type, payload, defaults = {}) => {
+  const data = asObject(payload);
+  switch (type) {
+  case ANALYTICS_EVENT_TYPES.VISITOR_PAGE_VIEW:
+    return {
+      surface: sanitizeSurface(data.surface, sanitizeSurface(defaults.surface, 'game')),
+      profile: sanitizeProfile(data.profile, sanitizeProfile(defaults.profile, DEFAULT_RUNTIME_PROFILE)),
+      embedMode: !!data.embedMode,
+      path: sanitizePath(data.path, sanitizePath(defaults.path || '/'))
+    };
+  case ANALYTICS_EVENT_TYPES.GAMEPLAY_LEVEL_SELECT: {
+    const control = String(data.control || '').trim();
+    if (!ALLOWED_LEVEL_SELECT_CONTROLS.has(control)) return null;
+    const value = clampInt(data.value, 0, 9999, null);
+    if (value == null) return null;
+    return { control, value };
+  }
+  case ANALYTICS_EVENT_TYPES.GAMEPLAY_MIDI_TOGGLE:
+    return { enabled: !!data.enabled };
+  case ANALYTICS_EVENT_TYPES.GAMEPLAY_SAVED_LEVEL: {
+    const action = String(data.action || '').trim().toLowerCase();
+    if (!ALLOWED_SAVED_LEVEL_ACTIONS.has(action)) return null;
+    return { action };
+  }
+  case ANALYTICS_EVENT_TYPES.EDITOR_ACTION: {
+    const action = String(data.action || '').trim().toLowerCase();
+    if (!ALLOWED_EDITOR_ACTIONS.has(action)) return null;
+    const output = { action };
+    if (typeof data.enabled === 'boolean') {
+      output.enabled = data.enabled;
+    }
+    return output;
+  }
+  case ANALYTICS_EVENT_TYPES.RUNTIME_BOOT_ERROR:
+    return {
+      code: sanitizeBootErrorCode(data.code),
+      surface: sanitizeSurface(data.surface, sanitizeSurface(defaults.surface, 'game')),
+      profile: sanitizeProfile(data.profile, sanitizeProfile(defaults.profile, DEFAULT_RUNTIME_PROFILE)),
+      embedMode: !!data.embedMode
+    };
+  default:
+    return null;
+  }
+};
+
+const sanitizeEnvelopeEvents = (value, max = MAX_ANALYTICS_IMPORT_EVENTS) => {
+  if (!Array.isArray(value)) return [];
+  const out = [];
+  const limit = clampInt(max, 1, MAX_ANALYTICS_IMPORT_EVENTS, MAX_ANALYTICS_IMPORT_EVENTS);
+  for (let i = 0; i < value.length && out.length < limit; i += 1) {
+    const entry = asObject(value[i]);
+    const type = String(entry.type || '').trim();
+    const payload = sanitizeEventPayload(type, entry.data || entry.payload || {}, {
+      surface: entry.surface,
+      profile: entry.profile,
+      path: entry.path
+    });
+    if (!payload) continue;
+    const event = {
+      v: ANALYTICS_SCHEMA_VERSION,
+      id: String(entry.id || `import-${out.length + 1}`).slice(0, 128),
+      ts: clampInt(entry.ts, 0, Number.MAX_SAFE_INTEGER, 0),
+      type,
+      surface: sanitizeSurface(entry.surface, 'game'),
+      profile: sanitizeProfile(entry.profile, DEFAULT_RUNTIME_PROFILE),
+      data: payload
+    };
+    out.push(event);
+  }
+  return out;
+};
+
+const readStoredBuffer = (storage) => {
+  const raw = safeStorageGet(storage, analyticsStorageKeys.buffer);
+  if (!raw) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    return sanitizeEnvelopeEvents(parsed?.events || []);
+  } catch {
+    return [];
+  }
+};
+
+const writeStoredBuffer = (storage, events) => {
+  if (!storage) return;
+  safeStorageSet(
+    storage,
+    analyticsStorageKeys.buffer,
+    JSON.stringify({
+      version: ANALYTICS_SCHEMA_VERSION,
+      events
+    })
+  );
+};
+
+const createAnalyticsService = (options = {}) => {
+  const now = typeof options.now === 'function' ? options.now : () => Date.now();
+  const random = typeof options.random === 'function' ? options.random : Math.random;
+  const windowRef = options.window || null;
+  const documentRef = options.document || windowRef?.document || null;
+  const navigatorRef = options.navigator || windowRef?.navigator || null;
+  const locationRef = options.location || windowRef?.location || null;
+  const storage = options.localStorage || null;
+  const queryParams = typeof URLSearchParams === 'function'
+    ? new URLSearchParams(locationRef?.search || '')
+    : null;
+
+  let surface = sanitizeSurface(options.surface, 'game');
+  let profile = sanitizeProfile(options.profile, DEFAULT_RUNTIME_PROFILE);
+  let hardDisabled = options.hardDisabled === true || isHardDisabledByMeta(readMetaContent(documentRef, 'lemmings-analytics'));
+  let runtimeDisabled = options.runtimeDisabled === true;
+
+  const queryDisable = parseBoolish(readQueryValue(queryParams, ['analyticsOff', 'noAnalytics']));
+  if (queryDisable === true) runtimeDisabled = true;
+  if (queryDisable === false) runtimeDisabled = false;
+
+  const queryHardDisable = parseBoolish(readQueryValue(queryParams, ['analyticsHardOff']));
+  if (queryHardDisable === true) hardDisabled = true;
+
+  let consentGranted = readStoredConsent(storage);
+  const queryConsent = parseBoolish(readQueryValue(queryParams, ['analytics', 'analyticsConsent']));
+  if (queryConsent != null) {
+    consentGranted = queryConsent;
+    writeStoredConsent(storage, consentGranted);
+  }
+  if (typeof options.consent === 'boolean') {
+    consentGranted = options.consent;
+  }
+  if (consentGranted == null) {
+    consentGranted = false;
+  }
+
+  // Development hosts stay opt-in by default.
+  if (isDevLocation(locationRef) && queryConsent == null && readStoredConsent(storage) !== true) {
+    consentGranted = false;
+  }
+
+  const metaEndpoint = readMetaContent(documentRef, 'lemmings-analytics-endpoint');
+  let beaconEndpoint = sanitizeBeaconEndpoint(options.managedBeaconEndpoint || metaEndpoint || '');
+  let managedBeaconRequested = options.enableManagedBeacon === true;
+  const queryBeacon = parseBoolish(readQueryValue(queryParams, ['analyticsBeacon']));
+  if (queryBeacon != null) managedBeaconRequested = queryBeacon;
+  let sampleRate = parseSampleRate(options.sampleRate, 1);
+  const querySampleRate = readQueryValue(queryParams, ['analyticsSample']);
+  if (querySampleRate != null) {
+    sampleRate = parseSampleRate(querySampleRate, sampleRate);
+  }
+
+  const ringBuffer = createRingBuffer(options.maxEvents);
+  ringBuffer.replace(readStoredBuffer(storage));
+  let pendingBeaconEvents = [];
+  const sessionId = createSessionId(now, random);
+  let sequence = 0;
+
+  const isEnabled = () => !hardDisabled && !runtimeDisabled && consentGranted === true;
+  const isBeaconEnabled = () => isEnabled() && managedBeaconRequested && !!beaconEndpoint;
+
+  const persist = () => {
+    writeStoredBuffer(storage, ringBuffer.values());
+  };
+
+  const flushManagedBeacon = () => {
+    const attempted = pendingBeaconEvents.length;
+    if (!attempted) return { ok: false, attempted: 0, sent: 0 };
+    if (!isBeaconEnabled()) return { ok: false, attempted, sent: 0 };
+    if (typeof navigatorRef?.sendBeacon !== 'function') return { ok: false, attempted, sent: 0 };
+    const payload = JSON.stringify({
+      version: ANALYTICS_SCHEMA_VERSION,
+      sessionId,
+      surface,
+      profile,
+      sentAt: clampInt(now(), 0, Number.MAX_SAFE_INTEGER, 0),
+      events: pendingBeaconEvents.slice()
+    });
+    const ok = !!navigatorRef.sendBeacon(beaconEndpoint, payload);
+    if (ok) {
+      pendingBeaconEvents = [];
+    }
+    return { ok, attempted, sent: ok ? attempted : 0 };
+  };
+
+  const maybeQueueForBeacon = (event) => {
+    if (!event || !isBeaconEnabled()) return;
+    if (sampleRate < 1 && random() > sampleRate) return;
+    pendingBeaconEvents.push(event);
+    if (pendingBeaconEvents.length >= 10) {
+      flushManagedBeacon();
+    }
+  };
+
+  const track = (type, payload = {}) => {
+    if (!isEnabled()) return null;
+    const sanitized = sanitizeEventPayload(type, payload, {
+      surface,
+      profile,
+      path: locationRef?.pathname || '/'
+    });
+    if (!sanitized) return null;
+    const event = {
+      v: ANALYTICS_SCHEMA_VERSION,
+      id: `${sessionId}:${sequence + 1}`,
+      ts: clampInt(now(), 0, Number.MAX_SAFE_INTEGER, 0),
+      type,
+      surface,
+      profile,
+      data: sanitized
+    };
+    sequence += 1;
+    ringBuffer.push(event);
+    persist();
+    maybeQueueForBeacon(event);
+    return event;
+  };
+
+  const trackPageView = (payload = {}) => track(
+    ANALYTICS_EVENT_TYPES.VISITOR_PAGE_VIEW,
+    {
+      surface,
+      profile,
+      path: locationRef?.pathname || '/',
+      ...asObject(payload)
+    }
+  );
+
+  const getStatus = () => ({
+    version: ANALYTICS_SCHEMA_VERSION,
+    enabled: isEnabled(),
+    hardDisabled,
+    runtimeDisabled,
+    consentGranted: consentGranted === true,
+    surface,
+    profile,
+    devLocation: isDevLocation(locationRef),
+    managedBeacon: {
+      requested: managedBeaconRequested,
+      enabled: isBeaconEnabled(),
+      endpoint: beaconEndpoint || null,
+      sampleRate,
+      pending: pendingBeaconEvents.length
+    },
+    ringBuffer: {
+      size: ringBuffer.size(),
+      capacity: ringBuffer.capacity
+    }
+  });
+
+  const setConsent = (granted, { persistConsent = true } = {}) => {
+    consentGranted = granted === true;
+    if (persistConsent) {
+      writeStoredConsent(storage, consentGranted);
+    }
+    if (!isEnabled()) {
+      pendingBeaconEvents = [];
+    }
+    return getStatus();
+  };
+
+  const setContext = (next = {}) => {
+    surface = sanitizeSurface(next.surface, surface);
+    profile = sanitizeProfile(next.profile, profile);
+    return getStatus();
+  };
+
+  const configureManagedBeacon = ({
+    enabled,
+    endpoint,
+    sample
+  } = {}) => {
+    if (typeof enabled === 'boolean') {
+      managedBeaconRequested = enabled;
+    }
+    if (endpoint != null) {
+      beaconEndpoint = sanitizeBeaconEndpoint(endpoint);
+    }
+    if (sample != null) {
+      sampleRate = parseSampleRate(sample, sampleRate);
+    }
+    return getStatus();
+  };
+
+  const exportBuffer = () => ({
+    version: ANALYTICS_SCHEMA_VERSION,
+    exportedAt: clampInt(now(), 0, Number.MAX_SAFE_INTEGER, 0),
+    sessionId,
+    surface,
+    profile,
+    events: ringBuffer.values()
+  });
+
+  const importBuffer = (value, { replace = false } = {}) => {
+    let parsed = value;
+    if (typeof value === 'string') {
+      try {
+        parsed = JSON.parse(value);
+      } catch {
+        parsed = null;
+      }
+    }
+    const events = sanitizeEnvelopeEvents(parsed?.events || []);
+    if (replace) {
+      ringBuffer.clear();
+    }
+    for (const event of events) {
+      ringBuffer.push(event);
+    }
+    persist();
+    return {
+      imported: events.length,
+      total: ringBuffer.size()
+    };
+  };
+
+  const clearBuffer = () => {
+    ringBuffer.clear();
+    pendingBeaconEvents = [];
+    persist();
+  };
+
+  const installWindowApi = (targetWindow = windowRef) => {
+    if (!targetWindow) return null;
+    const api = {
+      version: ANALYTICS_SCHEMA_VERSION,
+      getStatus,
+      track,
+      trackPageView,
+      exportBuffer,
+      importBuffer,
+      clearBuffer,
+      setConsent,
+      setContext,
+      configureManagedBeacon,
+      flushManagedBeacon
+    };
+    targetWindow.__LEMMINGS_ANALYTICS__ = api;
+    return api;
+  };
+
+  return {
+    track,
+    trackPageView,
+    getStatus,
+    setConsent,
+    setContext,
+    configureManagedBeacon,
+    exportBuffer,
+    importBuffer,
+    clearBuffer,
+    flushManagedBeacon,
+    installWindowApi
+  };
+};
+
+export {
+  ANALYTICS_SCHEMA_VERSION,
+  DEFAULT_ANALYTICS_BUFFER_CAPACITY,
+  ANALYTICS_EVENT_TYPES,
+  analyticsStorageKeys,
+  createAnalyticsService,
+  sanitizeEventPayload,
+  sanitizeEnvelopeEvents
+};
diff --git a/js/app/boot.js b/js/app/boot.js
index 267549ed..14b46a1d 100644
--- a/js/app/boot.js
+++ b/js/app/boot.js
@@ -6,15 +6,24 @@ import { registerServiceWorker } from './registerServiceWorker.js';
 import { installE2EHarness } from './e2eHarness.js';
 import { ShortcutOverlay } from './shortcutOverlay.js';
 import { bindCanvasFocusBlur } from './canvasFocusBlur.js';
+import { ANALYTICS_EVENT_TYPES, createAnalyticsService } from './analytics.js';
+import {
+  detectEmbedMode,
+  optionalElement,
+  resolveRequiredElements
+} from './domResolver.js';
+import {
+  getRuntimeDependency,
+  setRuntimeContext
+} from '../core/dependencies.js';
+import { DEFAULT_RUNTIME_PROFILE } from '../core/runtimeProfiles.js';
+import { resolveRuntimeRolloutFlags } from '../core/rolloutFlags.js';
 import {
   listSavedLevels,
   loadSavedLevel,
   saveLevel
 } from '../editor/EditorStorage.js';
 
-const $ = globalThis.$ || globalThis.jQuery;
-const jQuery = globalThis.jQuery || $;
-
 const GAME_SHORTCUT_SECTIONS = [
   {
     title: 'General',
@@ -70,63 +79,226 @@ const GAME_SHORTCUT_SECTIONS = [
   }
 ];
 
+const REQUIRED_BOOT_IDS = Object.freeze([
+  'shortcutOverlay',
+  'gameTypeSelect',
+  'levelGroupSelect',
+  'levelIndexSelect',
+  'gameCanvas'
+]);
+
+const getRuntimeWindow = () => getRuntimeDependency('window', null);
+const getRuntimeDocument = () => getRuntimeDependency('document', null);
+const getRuntimeWebMidi = () => getRuntimeDependency('webMidi', null);
+
+const getAmbientRuntimeDependency = (key, globalKey, fallback = null) => {
+  if (typeof globalThis !== 'undefined' &&
+      Object.prototype.hasOwnProperty.call(globalThis, globalKey)) {
+    const value = globalThis[globalKey];
+    return value === undefined ? fallback : value;
+  }
+  return getRuntimeDependency(key, fallback);
+};
+
+const hydrateRuntimeContext = () => {
+  const windowRef = getAmbientRuntimeDependency('window', 'window', null);
+  const documentRef = getAmbientRuntimeDependency('document', 'document', null);
+  const locationRef = getAmbientRuntimeDependency('location', 'location', windowRef?.location || null);
+  const runtimeRolloutFlags = resolveRuntimeRolloutFlags({
+    search: locationRef?.search || '',
+    runtimeFlags: getAmbientRuntimeDependency('rolloutFlags', '__LEMMINGS_ROLLOUT_FLAGS__', null)
+  });
+  setRuntimeContext({
+    window: windowRef,
+    document: documentRef,
+    navigator: getAmbientRuntimeDependency('navigator', 'navigator', windowRef?.navigator || null),
+    location: locationRef,
+    history: getAmbientRuntimeDependency('history', 'history', windowRef?.history || null),
+    localStorage: getAmbientRuntimeDependency('localStorage', 'localStorage', windowRef?.localStorage || null),
+    caches: getAmbientRuntimeDependency('caches', 'caches', null),
+    performance: getAmbientRuntimeDependency('performance', 'performance', (typeof performance !== 'undefined' ? performance : null)),
+    webMidi: getAmbientRuntimeDependency('webMidi', 'WebMidi', null),
+    rolloutFlags: runtimeRolloutFlags,
+    bootNoAutoStart: getAmbientRuntimeDependency('bootNoAutoStart', '__LEMMINGS_BOOT_NO_AUTO_START__', false)
+  });
+  return { windowRef, documentRef };
+};
+
+const appendBootFailureMessage = (documentRef, error, embedMode) => {
+  if (!documentRef) return;
+  const message = error?.message || 'Runtime boot failed.';
+  documentRef.documentElement?.setAttribute?.('data-boot-error', message);
+  if (!embedMode) return;
+  const host = documentRef.querySelector?.('.game_container') || documentRef.body;
+  if (!host || !documentRef.createElement) return;
+  if (documentRef.getElementById?.('bootFailureNotice')) return;
+  const notice = documentRef.createElement('div');
+  notice.id = 'bootFailureNotice';
+  notice.textContent = message;
+  notice.className = 'boot-failure-notice';
+  host.appendChild(notice);
+};
+
 let midiUi = null;
 let midiInputController = null;
 let lemmings;
+let resizeBound = false;
+let cachedGameContainer = null;
+let cachedCanvas = null;
+let analytics = null;
+
+const setLemmingsForTest = (value) => {
+  lemmings = value;
+};
 
-function init() {
+const createBootAnalytics = ({ windowRef, documentRef } = {}) => {
+  analytics = createAnalyticsService({
+    window: windowRef,
+    document: documentRef,
+    navigator: windowRef?.navigator || null,
+    location: windowRef?.location || null,
+    localStorage: getRuntimeDependency('localStorage', windowRef?.localStorage || null),
+    profile: lemmings?.startupProfile || DEFAULT_RUNTIME_PROFILE,
+    surface: 'game',
+    runtimeDisabled: getRuntimeDependency('analyticsDisabled', false) === true,
+    hardDisabled: getRuntimeDependency('analyticsHardDisabled', false) === true,
+    enableManagedBeacon: getRuntimeDependency('analyticsBeaconEnabled', false) === true,
+    managedBeaconEndpoint: getRuntimeDependency('analyticsBeaconEndpoint', null),
+    sampleRate: getRuntimeDependency('analyticsSampleRate', 1)
+  });
+  analytics.installWindowApi(windowRef);
+  return analytics;
+};
+
+function init({ windowRef, documentRef, embedMode }) {
+  if (!windowRef || !documentRef) {
+    throw new Error('Runtime boot requires both window and document references.');
+  }
   midiUi = createMidiUiController({
-    window: globalThis.window,
-    document: globalThis.document,
+    window: windowRef,
+    document: documentRef,
     getLemmings: () => lemmings,
-    getWebMidi: () => globalThis.WebMidi
+    getWebMidi: () => getRuntimeWebMidi()
   });
 
   lemmings = new GameView();
+  lemmings.applyProfileHistoryRetentionPolicy?.();
   lemmings.midiEnabled = midiUi.getStoredEnabled();
   lemmings.includeSavedLevels = true;
   lemmings.autoExitEditorOnSelect = true;
+  analytics?.setContext?.({
+    surface: 'game',
+    profile: lemmings.startupProfile || DEFAULT_RUNTIME_PROFILE
+  });
+  const bootNodes = resolveRequiredElements(documentRef, REQUIRED_BOOT_IDS, {
+    context: 'boot',
+    embedMode: embedMode === true
+  });
+  const shortcutOverlayRoot = bootNodes.shortcutOverlay;
+  const gameTypeSelect = bootNodes.gameTypeSelect;
+  const levelGroupSelect = bootNodes.levelGroupSelect;
+  const levelIndexSelect = bootNodes.levelIndexSelect;
+  const gameCanvas = bootNodes.gameCanvas;
   lemmings.shortcutOverlay = new ShortcutOverlay({
-    root: document.getElementById('shortcutOverlay'),
+    root: shortcutOverlayRoot,
     title: 'Game Shortcuts',
     sections: GAME_SHORTCUT_SECTIONS,
     getBindings: action => lemmings.shortcuts?.getDisplayBindings?.(action) || []
   });
-  installE2EHarness({ view: lemmings });
+  installE2EHarness({ view: lemmings, midiUi });
 
   midiInputController = new MidiInputController(lemmings, {
     getConfig: () => midiUi.getMidiConfig(),
-    onConfigChange: patch => midiUi.setMidiOverrides(patch)
+    onConfigChange: patch => midiUi.applyRuntimePatch(patch)
   });
   midiUi.setMidiInputController(midiInputController);
-  globalThis.onEnabled = () => midiUi?.onEnabled?.();
-  globalThis.onMidiError = (message) => midiUi?.showError?.(message);
+  const midiStatusHandlers = midiUi.getMidiStatusHandlers?.();
+  lemmings.setMidiStatusHandlers?.({
+    onEnabled: () => {
+      analytics?.track?.(ANALYTICS_EVENT_TYPES.GAMEPLAY_MIDI_TOGGLE, { enabled: true });
+      midiStatusHandlers?.onEnabled?.();
+    },
+    onError: (message) => {
+      analytics?.track?.(ANALYTICS_EVENT_TYPES.RUNTIME_BOOT_ERROR, {
+        code: 'midi_error',
+        surface: 'game',
+        profile: lemmings.startupProfile || DEFAULT_RUNTIME_PROFILE,
+        embedMode: embedMode === true
+      });
+      midiStatusHandlers?.onError?.(message);
+    }
+  });
 
-  lemmings.elementSelectGameType = document.getElementById('gameTypeSelect');
-  lemmings.elementSelectLevelGroup = document.getElementById('levelGroupSelect');
-  lemmings.elementSelectLevel = document.getElementById('levelIndexSelect');
-  lemmings.gameCanvas = document.getElementById('gameCanvas');
+  lemmings.elementSelectGameType = gameTypeSelect;
+  lemmings.elementSelectLevelGroup = levelGroupSelect;
+  lemmings.elementSelectLevel = levelIndexSelect;
+  lemmings.gameCanvas = gameCanvas;
+  cachedCanvas = gameCanvas;
+  cachedGameContainer = documentRef.querySelector('.game_container');
   bindCanvasFocusBlur(lemmings.gameCanvas);
   const setupPromise = lemmings.setup();
   if (setupPromise?.then) {
-    setupPromise.then(() => midiUi?.refreshMidiUiFromConfig?.()).catch(() => {});
+    setupPromise.then(async () => {
+      if (lemmings.startupProfile === 'editor') {
+        lemmings.enterEditorMode();
+        await lemmings.loadEditorLevelFromSelection();
+      }
+      midiUi?.refreshMidiUiFromConfig?.();
+    }).catch(() => {});
   }
   // use GameView.strToNum to parse dropdown values
   lemmings.elementSelectGameType.addEventListener('change', (e) => {
-    lemmings.selectGameType(lemmings.strToNum(e.target.value));
+    const value = lemmings.strToNum(e.target.value);
+    lemmings.selectGameType(value);
+    analytics?.track?.(ANALYTICS_EVENT_TYPES.GAMEPLAY_LEVEL_SELECT, {
+      control: 'gameType',
+      value
+    });
   });
   lemmings.elementSelectLevelGroup.addEventListener('change', (e) => {
-    lemmings.selectLevelGroup(lemmings.strToNum(e.target.value));
+    const value = lemmings.strToNum(e.target.value);
+    lemmings.selectLevelGroup(value);
+    analytics?.track?.(ANALYTICS_EVENT_TYPES.GAMEPLAY_LEVEL_SELECT, {
+      control: 'levelGroup',
+      value
+    });
   });
   lemmings.elementSelectLevel.addEventListener('change', (e) => {
-    lemmings.selectLevel(lemmings.strToNum(e.target.value));
+    const value = lemmings.strToNum(e.target.value);
+    lemmings.selectLevel(value);
+    analytics?.track?.(ANALYTICS_EVENT_TYPES.GAMEPLAY_LEVEL_SELECT, {
+      control: 'levelIndex',
+      value
+    });
   });
+  const midiEnabledToggle = optionalElement(documentRef, 'midiEnabledToggle');
+  if (midiEnabledToggle) {
+    midiEnabledToggle.addEventListener('change', (e) => {
+      analytics?.track?.(ANALYTICS_EVENT_TYPES.GAMEPLAY_MIDI_TOGGLE, {
+        enabled: !!e.target.checked
+      });
+    });
+  }
+  const levelPrevButton = optionalElement(documentRef, 'levelPrevButton');
+  const levelNextButton = optionalElement(documentRef, 'levelNextButton');
+  const bindLevelArrow = (element, delta) => {
+    if (!element) return;
+    const move = () => lemmings.moveToLevel(delta);
+    element.addEventListener('click', move);
+    element.addEventListener('keydown', (event) => {
+      if (event.key !== 'Enter' && event.key !== ' ') return;
+      event.preventDefault?.();
+      move();
+    });
+  };
+  bindLevelArrow(levelPrevButton, -1);
+  bindLevelArrow(levelNextButton, 1);
 
-  const savedSelect = document.getElementById('savedLevelSelect');
-  const savedSaveButton = document.getElementById('savedLevelSave');
-  const savedExportButton = document.getElementById('savedLevelExport');
-  const savedImportButton = document.getElementById('savedLevelImport');
-  const savedImportInput = document.getElementById('savedLevelImportInput');
+  const savedSelect = optionalElement(documentRef, 'savedLevelSelect');
+  const savedSaveButton = optionalElement(documentRef, 'savedLevelSave');
+  const savedExportButton = optionalElement(documentRef, 'savedLevelExport');
+  const savedImportButton = optionalElement(documentRef, 'savedLevelImport');
+  const savedImportInput = optionalElement(documentRef, 'savedLevelImportInput');
 
   let currentSavedId = '';
 
@@ -140,12 +312,12 @@ function init() {
     if (!savedSelect) return;
     const entries = listSavedLevels();
     savedSelect.innerHTML = '';
-    const placeholder = document.createElement('option');
+    const placeholder = documentRef.createElement('option');
     placeholder.value = '';
     placeholder.textContent = 'Saved levels';
     savedSelect.appendChild(placeholder);
     for (const entry of entries) {
-      const opt = document.createElement('option');
+      const opt = documentRef.createElement('option');
       opt.value = entry.id;
       opt.textContent = entry.name;
       savedSelect.appendChild(opt);
@@ -170,6 +342,9 @@ function init() {
       if (!text) return;
       lemmings.loadEditorLevelFromText(text);
       currentSavedId = id;
+      analytics?.track?.(ANALYTICS_EVENT_TYPES.GAMEPLAY_SAVED_LEVEL, {
+        action: 'load'
+      });
     });
   }
 
@@ -186,6 +361,9 @@ function init() {
       if (id) {
         currentSavedId = id;
         refreshSavedList(id);
+        analytics?.track?.(ANALYTICS_EVENT_TYPES.GAMEPLAY_SAVED_LEVEL, {
+          action: 'save'
+        });
       }
     });
   }
@@ -198,13 +376,16 @@ function init() {
       const filename = `${sanitizeFileName(title)}.nxlv`;
       const blob = new Blob([text], { type: 'text/plain' });
       const url = URL.createObjectURL(blob);
-      const link = document.createElement('a');
+      const link = documentRef.createElement('a');
       link.href = url;
       link.download = filename;
-      document.body.appendChild(link);
+      documentRef.body.appendChild(link);
       link.click();
-      document.body.removeChild(link);
+      documentRef.body.removeChild(link);
       URL.revokeObjectURL(url);
+      analytics?.track?.(ANALYTICS_EVENT_TYPES.GAMEPLAY_SAVED_LEVEL, {
+        action: 'export'
+      });
     });
   }
 
@@ -223,6 +404,9 @@ function init() {
         lemmings.loadEditorLevelFromText(text);
         currentSavedId = '';
         refreshSavedList('');
+        analytics?.track?.(ANALYTICS_EVENT_TYPES.GAMEPLAY_SAVED_LEVEL, {
+          action: 'import'
+        });
       };
       reader.readAsText(file);
       e.target.value = '';
@@ -231,74 +415,133 @@ function init() {
 }
 
 function setSize() {
+  const windowRef = getRuntimeWindow();
+  const documentRef = getRuntimeDocument();
+  if (!windowRef || !documentRef) return;
   const baseW = 800;
   const baseH = 480;
   const ratio = baseW / baseH;
-  const gameContainer = jQuery('.game_container');
-  const docEl = document.documentElement;
-  const viewport = window.visualViewport;
-  const width = Math.max(1, viewport?.width || docEl.clientWidth || window.innerWidth);
-  const height = Math.max(1, viewport?.height || docEl.clientHeight || window.innerHeight);
+  const gameContainer = cachedGameContainer || documentRef.querySelector('.game_container');
+  if (!cachedGameContainer) {
+    cachedGameContainer = gameContainer;
+  }
+  const docEl = documentRef.documentElement;
+  const viewport = windowRef.visualViewport;
+  const width = Math.max(1, viewport?.width || docEl.clientWidth || windowRef.innerWidth);
+  const height = Math.max(1, viewport?.height || docEl.clientHeight || windowRef.innerHeight);
   const isPortrait = height > width;
   const isTablet = Math.max(width, height) >= 900;
-  document.body.classList.toggle('portrait-small', isPortrait && !isTablet);
+  documentRef.body.classList.toggle('portrait-small', isPortrait && !isTablet);
   let containerWidth, containerHeight;
 
   if (width >= height * ratio) {
     containerWidth = height * ratio;
     containerHeight = height;
-    gameContainer.css('margin-top', '');
-    gameContainer.css('margin-left', (width - containerWidth) / 2);
-    gameContainer.removeClass('small');
+    if (gameContainer) {
+      gameContainer.style.marginTop = '';
+      gameContainer.style.marginLeft = `${(width - containerWidth) / 2}px`;
+      gameContainer.classList.remove('small');
+    }
   } else {
     containerWidth = width;
     containerHeight = width / ratio;
-    gameContainer.css('margin-top', (height - containerHeight) / 2);
-    gameContainer.css('margin-left', '');
-    gameContainer.addClass('small');
+    if (gameContainer) {
+      gameContainer.style.marginTop = `${(height - containerHeight) / 2}px`;
+      gameContainer.style.marginLeft = '';
+      gameContainer.classList.add('small');
+    }
   }
 
   if (containerWidth > width) containerWidth = width;
   if (containerHeight > height) containerHeight = height;
 
-  gameContainer.width(containerWidth);
-  gameContainer.height(containerHeight);
+  if (gameContainer) {
+    gameContainer.style.width = `${containerWidth}px`;
+    gameContainer.style.height = `${containerHeight}px`;
+  }
 
-  const canvas = document.getElementById('gameCanvas');
+  const canvas = lemmings?.gameCanvas || cachedCanvas || optionalElement(documentRef, 'gameCanvas');
+  if (!cachedCanvas && canvas) {
+    cachedCanvas = canvas;
+  }
   if (canvas) {
-    canvas.width = baseW;
-    canvas.height = baseH;
+    if (canvas.width !== baseW) {
+      canvas.width = baseW;
+    }
+    if (canvas.height !== baseH) {
+      canvas.height = baseH;
+    }
     canvas.style.width = containerWidth + 'px';
     canvas.style.height = containerHeight + 'px';
   }
 
-  if (window.lemmings && window.lemmings.stage) {
-    window.lemmings.stage.scheduleUpdateStageSize();
+  if (lemmings?.stage) {
+    lemmings.stage.scheduleUpdateStageSize();
   }
 }
 
 function bindResize() {
-  if (typeof $ === 'function' && $(window)?.on) {
-    $(window).on('resize orientationchange', function() {
-      setSize();
-    });
-  } else {
-    window.addEventListener('resize', setSize);
-    window.addEventListener('orientationchange', setSize);
-  }
+  const windowRef = getRuntimeWindow();
+  if (!windowRef) return;
+  if (resizeBound) return;
+  resizeBound = true;
+  windowRef.addEventListener('resize', setSize);
+  windowRef.addEventListener('orientationchange', setSize);
+  windowRef.visualViewport?.addEventListener?.('resize', setSize);
 }
 
 function start() {
-  init();
-  midiUi?.bindMidiUi();
-  midiUi?.scheduleMidiUiRefresh();
-  registerServiceWorker();
-  setSize();
-  bindResize();
+  const { windowRef, documentRef } = hydrateRuntimeContext();
+  const embedMode = detectEmbedMode({ windowRef, documentRef });
+  createBootAnalytics({ windowRef, documentRef });
+  try {
+    init({ windowRef, documentRef, embedMode });
+    analytics?.trackPageView?.({
+      surface: 'game',
+      profile: lemmings?.startupProfile || DEFAULT_RUNTIME_PROFILE,
+      embedMode: embedMode === true
+    });
+    midiUi?.bindMidiUi();
+    midiUi?.scheduleMidiUiRefresh();
+    registerServiceWorker({
+      profile: lemmings?.startupProfile || DEFAULT_RUNTIME_PROFILE,
+      window: windowRef,
+      document: documentRef,
+      location: windowRef?.location || null
+    });
+    setSize();
+    bindResize();
+  } catch (error) {
+    analytics?.track?.(ANALYTICS_EVENT_TYPES.RUNTIME_BOOT_ERROR, {
+      code: 'boot_error',
+      surface: 'game',
+      profile: lemmings?.startupProfile || DEFAULT_RUNTIME_PROFILE,
+      embedMode: embedMode === true
+    });
+    appendBootFailureMessage(documentRef, error, embedMode);
+    if (!embedMode) {
+      throw error;
+    }
+  }
 }
 
-if (document.readyState === 'loading') {
-  document.addEventListener('DOMContentLoaded', start);
-} else {
-  start();
+{
+  const { documentRef } = hydrateRuntimeContext();
+  const noAutoStart = getRuntimeDependency('bootNoAutoStart', false) === true;
+  if (!noAutoStart && documentRef) {
+    if (documentRef.readyState === 'loading') {
+      documentRef.addEventListener('DOMContentLoaded', start);
+    } else {
+      start();
+    }
+  } else if (!noAutoStart && !documentRef) {
+    throw new Error('Runtime boot requires a document reference.');
+  }
 }
+
+export {
+  bindResize,
+  setLemmingsForTest,
+  setSize,
+  start
+};
diff --git a/js/app/canvasFocusBlur.js b/js/app/canvasFocusBlur.js
index 510a2599..4e9a6df8 100644
--- a/js/app/canvasFocusBlur.js
+++ b/js/app/canvasFocusBlur.js
@@ -1,5 +1,9 @@
-const blurActiveInput = () => {
-  const active = document.activeElement;
+import { getRuntimeDependency } from '../core/dependencies.js';
+
+const boundCanvasHandlers = new WeakMap();
+
+const blurActiveInput = (documentRef, windowRef) => {
+  const active = documentRef?.activeElement;
   if (!active) return;
   const tag = active.tagName;
   if (active.isContentEditable ||
@@ -7,13 +11,13 @@ const blurActiveInput = () => {
       tag === 'SELECT' ||
       tag === 'TEXTAREA') {
     active.blur?.();
-    if (document.body) {
-      document.body.tabIndex = -1;
-      document.body.focus?.({ preventScroll: true });
+    if (documentRef?.body) {
+      documentRef.body.tabIndex = -1;
+      documentRef.body.focus?.({ preventScroll: true });
     }
-    if (document.activeElement === active) {
-      window.setTimeout?.(() => {
-        if (document.activeElement === active) {
+    if (documentRef?.activeElement === active) {
+      windowRef?.setTimeout?.(() => {
+        if (documentRef?.activeElement === active) {
           active.blur?.();
         }
       }, 0);
@@ -21,8 +25,22 @@ const blurActiveInput = () => {
   }
 };
 
-const bindCanvasFocusBlur = (canvas) => {
-  if (!canvas) return;
+/**
+ * Bind canvas interactions that blur active form elements so gameplay input is
+ * not trapped by focused controls. Returns a cleanup function for teardown.
+ */
+const bindCanvasFocusBlur = (canvas, options = {}) => {
+  const deps = options && typeof options === 'object' ? options : {};
+  const documentRef = deps.documentRef || getRuntimeDependency('document', null);
+  const windowRef = deps.windowRef || getRuntimeDependency('window', null);
+  if (!canvas) return () => {};
+  const existingCleanup = boundCanvasHandlers.get(canvas);
+  if (existingCleanup) {
+    return existingCleanup;
+  }
+  if (!documentRef?.addEventListener || !canvas.addEventListener) {
+    return () => {};
+  }
   canvas.dataset.focusBlurBound = 'true';
   const handler = (event) => {
     const target = event?.target;
@@ -33,16 +51,32 @@ const bindCanvasFocusBlur = (canvas) => {
         tag === 'TEXTAREA') {
       return;
     }
-    blurActiveInput();
+    blurActiveInput(documentRef, windowRef);
   };
-  document.addEventListener('pointerdown', handler, { capture: true });
-  document.addEventListener('mousedown', handler, { capture: true });
-  document.addEventListener('touchstart', handler, { capture: true, passive: true });
-  document.addEventListener('click', handler, { capture: true });
+  documentRef.addEventListener('pointerdown', handler, { capture: true });
+  documentRef.addEventListener('mousedown', handler, { capture: true });
+  documentRef.addEventListener('touchstart', handler, { capture: true, passive: true });
+  documentRef.addEventListener('click', handler, { capture: true });
   canvas.addEventListener('pointerdown', handler, { capture: true });
   canvas.addEventListener('mousedown', handler, { capture: true });
   canvas.addEventListener('touchstart', handler, { capture: true, passive: true });
   canvas.addEventListener('click', handler, { capture: true });
+  const cleanup = () => {
+    documentRef.removeEventListener?.('pointerdown', handler, { capture: true });
+    documentRef.removeEventListener?.('mousedown', handler, { capture: true });
+    documentRef.removeEventListener?.('touchstart', handler, { capture: true });
+    documentRef.removeEventListener?.('click', handler, { capture: true });
+    canvas.removeEventListener?.('pointerdown', handler, { capture: true });
+    canvas.removeEventListener?.('mousedown', handler, { capture: true });
+    canvas.removeEventListener?.('touchstart', handler, { capture: true });
+    canvas.removeEventListener?.('click', handler, { capture: true });
+    if (canvas.dataset) {
+      delete canvas.dataset.focusBlurBound;
+    }
+    boundCanvasHandlers.delete(canvas);
+  };
+  boundCanvasHandlers.set(canvas, cleanup);
+  return cleanup;
 };
 
 export { bindCanvasFocusBlur };
diff --git a/js/app/domResolver.js b/js/app/domResolver.js
new file mode 100644
index 00000000..063451b2
--- /dev/null
+++ b/js/app/domResolver.js
@@ -0,0 +1,68 @@
+function optionalElement(doc, id) {
+  if (!doc || typeof doc.getElementById !== 'function') return null;
+  return doc.getElementById(id);
+}
+
+function requireElement(doc, id, options = {}) {
+  const element = optionalElement(doc, id);
+  if (!element) {
+    const context = options.context ? ` (${options.context})` : '';
+    throw new Error(`Missing required DOM element: #${id}${context}`);
+  }
+  return element;
+}
+
+function detectEmbedMode({ windowRef = null, documentRef = null } = {}) {
+  const params = windowRef?.location?.search
+    ? new URLSearchParams(windowRef.location.search)
+    : null;
+  if (params?.has('embed')) return true;
+  if (params?.has('embedded')) return true;
+  if (documentRef?.documentElement?.dataset?.embedMode === 'true') return true;
+  if (documentRef?.body?.dataset?.embedMode === 'true') return true;
+  return false;
+}
+
+function createDomResolutionError({ missingIds = [], embedMode = false, context = 'boot' } = {}) {
+  const ids = Array.isArray(missingIds) ? missingIds.filter(Boolean) : [];
+  const suffix = ids.length ? `: ${ids.map(id => `#${id}`).join(', ')}` : '';
+  const embedHint = embedMode
+    ? ' Embed mode requires explicit container wiring.'
+    : '';
+  const error = new Error(`Missing required DOM elements for ${context}${suffix}.${embedHint}`.trim());
+  error.name = 'DomResolutionError';
+  error.missingIds = ids;
+  error.embedMode = embedMode === true;
+  error.context = context;
+  return error;
+}
+
+function resolveRequiredElements(doc, ids, options = {}) {
+  const missing = [];
+  const resolved = {};
+  const entries = Array.isArray(ids) ? ids : [];
+  for (const id of entries) {
+    const element = optionalElement(doc, id);
+    if (!element) {
+      missing.push(id);
+      continue;
+    }
+    resolved[id] = element;
+  }
+  if (missing.length) {
+    throw createDomResolutionError({
+      missingIds: missing,
+      embedMode: options.embedMode === true,
+      context: options.context || 'boot'
+    });
+  }
+  return resolved;
+}
+
+export {
+  createDomResolutionError,
+  detectEmbedMode,
+  optionalElement,
+  requireElement,
+  resolveRequiredElements
+};
diff --git a/js/app/e2e/E2ECanvasHarness.js b/js/app/e2e/E2ECanvasHarness.js
new file mode 100644
index 00000000..279c8e36
--- /dev/null
+++ b/js/app/e2e/E2ECanvasHarness.js
@@ -0,0 +1,459 @@
+import {
+  BASE64_CHUNK,
+  BinaryReader,
+  DTYPE_MAP,
+  E2E_QUERY_KEY,
+  EditorTools,
+  LevelReader,
+  LevelWriter,
+  createClassicLevelData,
+  createEditorLevelFromClassic,
+  createGadgetEntry,
+  createSteelEntry,
+  createTerrainEntry,
+  ensureEntryUid,
+  ensureLevelEntryUids,
+  findEntryAt,
+  getEntryBounds,
+  getRuntimeDependency,
+  listSavedLevels,
+  loadSavedLevel,
+  removeEntryAt,
+  saveLevel,
+  setEntryProp,
+  validateLevel
+} from './e2eShared.js';
+import {
+  isE2EEnabled,
+  normalizeBufferName,
+  toByteView,
+  encodeBase64,
+  packBuffer,
+  cloneEntry,
+  cloneTerrainGroup,
+  cloneUnknownSection,
+  serializeEditorLevel,
+  serializeSelectionEntry,
+  serializeEditorController,
+  summarizeEditorHistory,
+  getEditorHistoryEntry,
+  serializeIssues,
+  serializeAssets,
+  getActionType,
+  serializeLemming,
+  serializeTrigger,
+  serializeMapObject,
+  isGameReady,
+  getViewState,
+  getGameState
+} from './E2EStateSerialization.js';
+import {
+  getBenchMetrics,
+  toSortedStringList,
+  getRuntimeDiagnostics,
+  getCacheStorageKeys,
+  getEnvironmentDiagnostics,
+  getStageState,
+  getCanvasMetrics
+} from './E2EDiagnostics.js';
+import {
+  getEditorState
+} from './E2EEditorState.js';
+import {
+  getEditorContext,
+  getListForKind,
+  getPrefixForKind,
+  resolveEntryRef,
+  cloneEntryForApply,
+  normalizeBounds,
+  boundsIntersect,
+  applyEditorOps
+} from './E2EEditorApply.js';
+import {
+  pauseGame,
+  resumeGame,
+  stepGame,
+  seekGame,
+  setEditorPlaytest,
+  setSpeed,
+  selectLemmingById,
+  centerViewOnLemming,
+  startReverse,
+  stopReverse,
+  toggleReverse,
+  flushSoundEvents,
+  getHistoryDelta,
+  getHistoryDeltas,
+  startBenchSequence,
+  startBench,
+  stopBench
+} from './E2EGameControls.js';
+const getBuffer = (view, name) => {
+  const normalized = normalizeBufferName(name);
+  const game = view?.game || null;
+  const level = game?.level || null;
+  const manager = game?.getLemmingManager?.() || null;
+  const minimap = manager?.miniMap || null;
+
+  switch (normalized) {
+  case 'ground-mask': {
+    const mask = level?.groundMask?.mask || null;
+    return packBuffer('ground-mask', mask, {
+      width: level?.width ?? null,
+      height: level?.height ?? null,
+      stride: level?.width ?? null,
+      format: 'mask8'
+    });
+  }
+  case 'ground-image': {
+    const image = level?.groundImage || null;
+    return packBuffer('ground-image', image, {
+      width: level?.width ?? null,
+      height: level?.height ?? null,
+      stride: level?.width ? level.width * 4 : null,
+      format: 'rgba8888'
+    });
+  }
+  case 'minimap-terrain':
+    return packBuffer('minimap-terrain', minimap?.terrain || null, {
+      width: minimap?.width ?? null,
+      height: minimap?.height ?? null,
+      stride: minimap?.width ?? null,
+      format: 'u8'
+    });
+  case 'minimap-fog':
+    return packBuffer('minimap-fog', minimap?.fog || null, {
+      width: minimap?.width ?? null,
+      height: minimap?.height ?? null,
+      stride: minimap?.width ?? null,
+      format: 'u8'
+    });
+  case 'minimap-live-dots': {
+    const liveDotsLength = Number.isFinite(minimap?.liveDotsLength)
+      ? Math.max(0, Math.trunc(minimap.liveDotsLength))
+      : (minimap?.liveDots?.length ?? 0);
+    const liveDots = minimap?.liveDots?.subarray?.(0, liveDotsLength) || minimap?.liveDots || null;
+    return packBuffer('minimap-live-dots', liveDots, {
+      pairStride: 2,
+      count: liveDotsLength / 2,
+      format: 'xy'
+    });
+  }
+  case 'minimap-dead-dots': {
+    const count = minimap?.deadCount ?? 0;
+    const data = minimap?.deadDots?.subarray(0, count * 2) || null;
+    return packBuffer('minimap-dead-dots', data, {
+      pairStride: 2,
+      count,
+      format: 'xy'
+    });
+  }
+  case 'minimap-dead-ttls': {
+    const count = minimap?.deadCount ?? 0;
+    const data = minimap?.deadTTLs?.subarray(0, count) || null;
+    return packBuffer('minimap-dead-ttls', data, {
+      count,
+      format: 'u8'
+    });
+  }
+  default:
+    return null;
+  }
+};
+const getEditorLevelText = (view) => view?.getEditorLevelText?.() || '';
+const getStageCanvasRect = (stage) => {
+  const rect = stage?.stageCav?.getBoundingClientRect?.();
+  if (!rect) return null;
+  return {
+    left: rect.left,
+    top: rect.top,
+    width: rect.width,
+    height: rect.height
+  };
+};
+const getStageCanvasScale = (stage, rect = getStageCanvasRect(stage)) => {
+  const canvas = stage?.stageCav || null;
+  const width = Number(canvas?.width);
+  const height = Number(canvas?.height);
+  return {
+    x: rect && Number.isFinite(width) && width > 0 ? rect.width / width : 1,
+    y: rect && Number.isFinite(height) && height > 0 ? rect.height / height : 1
+  };
+};
+const stageCanvasToPageRect = (stage, rect) => {
+  const stageRect = getStageCanvasRect(stage);
+  if (!stageRect || !rect) return null;
+  const scale = getStageCanvasScale(stage, stageRect);
+  return {
+    x: stageRect.left + Number(rect.x) * scale.x,
+    y: stageRect.top + Number(rect.y) * scale.y,
+    width: Number(rect.width) * scale.x,
+    height: Number(rect.height) * scale.y
+  };
+};
+const stageCanvasToPagePoint = (stage, point) => {
+  const stageRect = getStageCanvasRect(stage);
+  if (!stageRect || !point) return null;
+  const scale = getStageCanvasScale(stage, stageRect);
+  return {
+    x: stageRect.left + Number(point.x) * scale.x,
+    y: stageRect.top + Number(point.y) * scale.y
+  };
+};
+const pageToStageCanvasPoint = (stage, point) => {
+  const stageRect = getStageCanvasRect(stage);
+  if (!stageRect || !point) return null;
+  const scale = getStageCanvasScale(stage, stageRect);
+  return {
+    x: (Number(point.x) - stageRect.left) / scale.x,
+    y: (Number(point.y) - stageRect.top) / scale.y
+  };
+};
+const getStageWorldPointFromPage = (view, point = {}) => {
+  const stage = view?.stage;
+  const image = stage?.gameImgProps;
+  const canvasPoint = pageToStageCanvasPoint(stage, point);
+  const x = Number(point?.x);
+  const y = Number(point?.y);
+  if (!image?.viewPoint || !canvasPoint || !Number.isFinite(x) || !Number.isFinite(y)) {
+    return null;
+  }
+  const localX = canvasPoint.x - (image.x ?? 0);
+  const localY = canvasPoint.y - (image.y ?? 0);
+  return {
+    x: image.viewPoint.getSceneX(localX),
+    y: image.viewPoint.getSceneY(localY)
+  };
+};
+const getStagePagePointFromWorld = (view, point = {}) => {
+  const stage = view?.stage;
+  const image = stage?.gameImgProps;
+  const viewRect = stage?.getGameViewRect?.();
+  const x = Number(point?.x);
+  const y = Number(point?.y);
+  const scale = image?.viewPoint?.scale ?? 1;
+  if (!viewRect || !Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(scale)) {
+    return null;
+  }
+  return stageCanvasToPagePoint(stage, {
+    x: (image?.x ?? 0) + (x - viewRect.x) * scale,
+    y: (image?.y ?? 0) + (y - viewRect.y) * scale
+  });
+};
+const centerStageOn = (view, point = {}) => {
+  const stage = view?.stage;
+  const viewRect = stage?.getGameViewRect?.();
+  if (!stage || !viewRect || !stage.gameImgProps) return false;
+  const x = Number(point?.x);
+  const y = Number(point?.y);
+  const scale = Number.isFinite(point?.scale)
+    ? Number(point.scale)
+    : (stage.gameImgProps?.viewPoint?.scale ?? 1);
+  if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(scale)) return false;
+  stage.applyViewport(
+    stage.gameImgProps,
+    x - viewRect.w / 2,
+    y - viewRect.h / 2,
+    scale
+  );
+  stage.redraw?.();
+  view?.render?.();
+  return true;
+};
+const getMinimapPagePoint = (view, options = {}) => {
+  const stage = view?.stage;
+  const gui = stage?.guiImgProps;
+  const display = gui?.display;
+  const miniMap = view?.game?.getLemmingManager?.()?.miniMap || null;
+  if (!gui || !display || !miniMap) return null;
+  const scale = gui.viewPoint?.scale ?? 1;
+  const offsetX = Number.isFinite(options?.offsetX) ? Number(options.offsetX) : 2;
+  const offsetY = Number.isFinite(options?.offsetY) ? Number(options.offsetY) : 2;
+  const bottomInset = Number.isFinite(options?.bottomInset) ? Number(options.bottomInset) : 1;
+  const destX = display.worldDataSize.width - miniMap.width;
+  const destY = display.worldDataSize.height - miniMap.height - bottomInset;
+  return stageCanvasToPagePoint(stage, {
+    x: (gui.x ?? 0) + destX * scale + offsetX,
+    y: (gui.y ?? 0) + destY * scale + offsetY
+  });
+};
+const isFinitePositiveRect = (rect) => (
+  rect
+  && Number.isFinite(rect.x)
+  && Number.isFinite(rect.y)
+  && Number.isFinite(rect.width)
+  && Number.isFinite(rect.height)
+  && rect.width > 0
+  && rect.height > 0
+);
+const normalizePageRect = (rect) => {
+  if (!rect) return null;
+  const x = Number(rect.x ?? rect.left);
+  const y = Number(rect.y ?? rect.top);
+  const width = Number(rect.width);
+  const height = Number(rect.height);
+  const normalized = { x, y, width, height };
+  return isFinitePositiveRect(normalized) ? normalized : null;
+};
+const addRect = (rects, diagnostics, id, rect, missingReason) => {
+  const normalized = normalizePageRect(rect);
+  if (normalized) {
+    rects[id] = normalized;
+    return true;
+  }
+  if (missingReason) diagnostics.missing[id] = missingReason;
+  return false;
+};
+const getCanvasElementRect = () => {
+  const canvas = document.getElementById('gameCanvas') || document.getElementById('editorCanvas');
+  const rect = canvas?.getBoundingClientRect?.();
+  if (!rect) return null;
+  return {
+    x: rect.left,
+    y: rect.top,
+    width: rect.width,
+    height: rect.height
+  };
+};
+const getStagePageRect = (stage) => {
+  const rect = getStageCanvasRect(stage);
+  if (!rect) return null;
+  return {
+    x: rect.left,
+    y: rect.top,
+    width: rect.width,
+    height: rect.height
+  };
+};
+const getStageImagePageRect = (stage, image) => {
+  const width = Number(image?.canvasViewportSize?.width ?? image?.width);
+  const height = Number(image?.canvasViewportSize?.height ?? image?.height);
+  if (!image || !Number.isFinite(width) || !Number.isFinite(height)) {
+    return null;
+  }
+  return stageCanvasToPageRect(stage, {
+    x: Number(image.x) || 0,
+    y: Number(image.y) || 0,
+    width,
+    height
+  });
+};
+const getMinimapPageRect = (view) => {
+  const stage = view?.stage;
+  const gui = stage?.guiImgProps;
+  const display = gui?.display;
+  const miniMap = view?.game?.getLemmingManager?.()?.miniMap || null;
+  if (!gui || !display || !miniMap) return null;
+  const scale = gui.viewPoint?.scale ?? 1;
+  const width = Number(miniMap.width) * scale;
+  const height = Number(miniMap.height) * scale;
+  const destX = display.worldDataSize.width - miniMap.width;
+  const destY = display.worldDataSize.height - miniMap.height;
+  return stageCanvasToPageRect(stage, {
+    x: (gui.x ?? 0) + destX * scale,
+    y: (gui.y ?? 0) + destY * scale,
+    width,
+    height
+  });
+};
+const getWorldPageRect = (view, rect, padding = 0) => {
+  const x = Number(rect?.x);
+  const y = Number(rect?.y);
+  const width = Number(rect?.width);
+  const height = Number(rect?.height);
+  const pad = Number.isFinite(padding) ? Math.max(0, Number(padding)) : 0;
+  if (
+    !Number.isFinite(x) ||
+    !Number.isFinite(y) ||
+    !Number.isFinite(width) ||
+    !Number.isFinite(height) ||
+    width <= 0 ||
+    height <= 0
+  ) {
+    return null;
+  }
+  const start = getStagePagePointFromWorld(view, { x, y });
+  const end = getStagePagePointFromWorld(view, { x: x + width, y: y + height });
+  if (!start || !end) return null;
+  const left = Math.min(start.x, end.x) - pad;
+  const top = Math.min(start.y, end.y) - pad;
+  const right = Math.max(start.x, end.x) + pad;
+  const bottom = Math.max(start.y, end.y) + pad;
+  return {
+    x: left,
+    y: top,
+    width: right - left,
+    height: bottom - top
+  };
+};
+const getEditorSelectionPageRect = (view, editorUi, padding = 0) => {
+  const ctx = getEditorContext(view, editorUi);
+  const bounds = ctx?.controller?.getSelectionBounds?.() || null;
+  if (!bounds) return null;
+  return getWorldPageRect(view, bounds, padding);
+};
+const getCaptureRects = (view, editorUi, options = {}) => {
+  const rects = {};
+  const diagnostics = {
+    route: typeof location !== 'undefined' ? location.pathname : null,
+    mode: editorUi ? 'editor' : (view?.editorMode ? 'editor' : 'game'),
+    missing: {}
+  };
+  const stage = view?.stage || null;
+
+  addRect(rects, diagnostics, 'canvas', getCanvasElementRect(), 'missing #gameCanvas/#editorCanvas');
+  addRect(rects, diagnostics, 'stageCanvas', getStagePageRect(stage), 'missing stage canvas');
+  addRect(rects, diagnostics, 'game', getStageImagePageRect(stage, stage?.gameImgProps), 'missing stage game rect');
+  addRect(rects, diagnostics, 'gui', getStageImagePageRect(stage, stage?.guiImgProps), 'missing stage gui rect');
+  addRect(rects, diagnostics, 'minimap', getMinimapPageRect(view), 'missing minimap');
+
+  const editorCanvas = document.getElementById('editorCanvas')?.getBoundingClientRect?.();
+  addRect(rects, diagnostics, 'editorCanvas', editorCanvas
+    ? {
+      x: editorCanvas.left,
+      y: editorCanvas.top,
+      width: editorCanvas.width,
+      height: editorCanvas.height
+    }
+    : null, 'missing #editorCanvas');
+  addRect(
+    rects,
+    diagnostics,
+    'editorSelection',
+    getEditorSelectionPageRect(view, editorUi, options?.editorSelectionPadding),
+    'missing editor selection'
+  );
+
+  if (options?.worldRect || options?.rect) {
+    const spec = options.worldRect || options;
+    const id = String(spec?.id || options?.id || 'worldRect');
+    const padding = Number.isFinite(spec?.padding)
+      ? Number(spec.padding)
+      : (Number.isFinite(options?.padding) ? Number(options.padding) : 0);
+    addRect(
+      rects,
+      diagnostics,
+      id,
+      getWorldPageRect(view, spec?.rect || spec, padding),
+      'invalid or unavailable world rect'
+    );
+  }
+
+  diagnostics.available = Object.keys(rects).sort();
+  return {
+    version: 1,
+    rects,
+    diagnostics
+  };
+};
+export {
+  getBuffer,
+  getEditorLevelText,
+  getStageCanvasRect,
+  getStageWorldPointFromPage,
+  getStagePagePointFromWorld,
+  centerStageOn,
+  getMinimapPagePoint,
+  getCaptureRects,
+  getWorldPageRect
+};
diff --git a/js/app/e2e/E2EDiagnostics.js b/js/app/e2e/E2EDiagnostics.js
new file mode 100644
index 00000000..339fa04d
--- /dev/null
+++ b/js/app/e2e/E2EDiagnostics.js
@@ -0,0 +1,264 @@
+import {
+  BASE64_CHUNK,
+  BinaryReader,
+  DTYPE_MAP,
+  E2E_QUERY_KEY,
+  EditorTools,
+  LevelReader,
+  LevelWriter,
+  createClassicLevelData,
+  createEditorLevelFromClassic,
+  createGadgetEntry,
+  createSteelEntry,
+  createTerrainEntry,
+  ensureEntryUid,
+  ensureLevelEntryUids,
+  findEntryAt,
+  getEntryBounds,
+  getRuntimeDependency,
+  listSavedLevels,
+  loadSavedLevel,
+  removeEntryAt,
+  saveLevel,
+  setEntryProp,
+  validateLevel
+} from './e2eShared.js';
+import {
+  isE2EEnabled,
+  normalizeBufferName,
+  toByteView,
+  encodeBase64,
+  packBuffer,
+  cloneEntry,
+  cloneTerrainGroup,
+  cloneUnknownSection,
+  serializeEditorLevel,
+  serializeSelectionEntry,
+  serializeEditorController,
+  summarizeEditorHistory,
+  getEditorHistoryEntry,
+  serializeIssues,
+  serializeAssets,
+  getActionType,
+  serializeLemming,
+  serializeTrigger,
+  serializeMapObject,
+  isGameReady,
+  getViewState,
+  getGameState
+} from './E2EStateSerialization.js';
+import {
+  getEditorState
+} from './E2EEditorState.js';
+import {
+  getEditorContext,
+  getListForKind,
+  getPrefixForKind,
+  resolveEntryRef,
+  cloneEntryForApply,
+  normalizeBounds,
+  boundsIntersect,
+  applyEditorOps
+} from './E2EEditorApply.js';
+import {
+  getBuffer,
+  getEditorLevelText,
+  getStageCanvasRect,
+  getStageWorldPointFromPage,
+  getStagePagePointFromWorld,
+  centerStageOn,
+  getMinimapPagePoint
+} from './E2ECanvasHarness.js';
+import {
+  pauseGame,
+  resumeGame,
+  stepGame,
+  seekGame,
+  setEditorPlaytest,
+  setSpeed,
+  selectLemmingById,
+  centerViewOnLemming,
+  startReverse,
+  stopReverse,
+  toggleReverse,
+  flushSoundEvents,
+  getHistoryDelta,
+  getHistoryDeltas,
+  startBenchSequence,
+  startBench,
+  stopBench
+} from './E2EGameControls.js';
+const getBenchMetrics = (view) => {
+  if (!view) return null;
+  const timer = view.game?.getGameTimer?.() || null;
+  const active = !!(view.bench || view.bench2 || view.benchReverse || view.benchSequence);
+  const mode = view.benchReverse
+    ? 'reverse'
+    : view.benchSequence
+      ? 'sequence'
+      : view.bench2
+        ? 'catchup'
+        : view.bench
+          ? 'bench'
+          : null;
+  return {
+    active,
+    mode,
+    steps: view.steps ?? 0,
+    tps: view.tps ?? timer?.tps ?? null,
+    speedFactor: timer?.speedFactor ?? null,
+    benchMaxSpeed: view._benchMaxSpeed ?? null,
+    benchIndex: view._benchIndex ?? null,
+    benchCounts: Array.isArray(view._benchCounts) ? view._benchCounts.slice() : [],
+    benchExtraList: Array.isArray(view._benchExtraList) ? view._benchExtraList.slice() : [],
+    benchExtraIndex: view._benchExtraIndex ?? null,
+    benchStartTime: view._benchStartTime ?? null,
+    benchMeasureExtras: !!view._benchMeasureExtras,
+    benchStartupFrames: timer?.benchStartupFrames ?? 0,
+    benchStableFactor: timer?.benchStableFactor ?? 1
+  };
+};
+const toSortedStringList = (values) => {
+  if (!Array.isArray(values)) return [];
+  return values
+    .map(value => String(value))
+    .sort((a, b) => a.localeCompare(b));
+};
+const getRuntimeDiagnostics = (view) => {
+  const fallback = {
+    profile: view?.startupProfile || 'gameplay',
+    rolloutFlags: view?.rolloutFlags ? { ...view.rolloutFlags } : null,
+    capabilities: view?.runtimeCapabilities ? { ...view.runtimeCapabilities } : null,
+    featureFlags: {
+      performanceAPI: !!view?.performanceAPI,
+      perfMetrics: !!view?.perfMetrics,
+      perfOverlay: !!view?.perfOverlay,
+      debug: !!view?.debug,
+      cheatEnabled: !!view?.cheatEnabled,
+      endless: !!view?.endless,
+      midiEnabled: !!view?.midiEnabled,
+      editorMode: !!view?.editorMode,
+      editorPlaytest: !!view?.editorPlaytest,
+      preserveHistory: !!view?.preserveHistory,
+      includeSavedLevels: !!view?.includeSavedLevels,
+      bench: !!view?.bench,
+      bench2: !!view?.bench2,
+      benchReverse: !!view?.benchReverse,
+      benchSequence: !!view?.benchSequence
+    },
+    caches: {
+      fileProvider: view?.gameFactory?.fileProvider?.getCacheStats?.() || null
+    }
+  };
+  const diagnostics = view?.getRuntimeDiagnostics?.() || fallback;
+  return {
+    profile: diagnostics.profile || fallback.profile,
+    rolloutFlags: diagnostics.rolloutFlags
+      ? { ...diagnostics.rolloutFlags }
+      : (fallback.rolloutFlags ? { ...fallback.rolloutFlags } : null),
+    capabilities: diagnostics.capabilities
+      ? { ...diagnostics.capabilities }
+      : (fallback.capabilities ? { ...fallback.capabilities } : null),
+    featureFlags: {
+      ...fallback.featureFlags,
+      ...(diagnostics.featureFlags || {})
+    },
+    caches: {
+      fileProvider: diagnostics.caches?.fileProvider ?? fallback.caches.fileProvider
+    }
+  };
+};
+const getCacheStorageKeys = async (cacheStorage = getRuntimeDependency('caches', null)) => {
+  if (!cacheStorage?.keys) return [];
+  try {
+    return toSortedStringList(await cacheStorage.keys());
+  } catch {
+    return [];
+  }
+};
+const getEnvironmentDiagnostics = (view, { cacheStorageKeys = null } = {}) => {
+  const runtime = getRuntimeDiagnostics(view);
+  const location = typeof window !== 'undefined' ? window.location : null;
+  const serviceWorker = typeof navigator !== 'undefined' ? navigator.serviceWorker : null;
+  return {
+    version: 1,
+    profile: runtime.profile,
+    rolloutFlags: runtime.rolloutFlags,
+    capabilities: runtime.capabilities,
+    featureFlags: runtime.featureFlags,
+    caches: {
+      ...runtime.caches,
+      cacheStorageKeys: Array.isArray(cacheStorageKeys)
+        ? toSortedStringList(cacheStorageKeys)
+        : null
+    },
+    serviceWorker: {
+      supported: !!serviceWorker,
+      controlled: !!serviceWorker?.controller
+    },
+    location: location
+      ? {
+        protocol: location.protocol || null,
+        hostname: location.hostname || null,
+        pathname: location.pathname || null
+      }
+      : null
+  };
+};
+const getStageState = (stage) => {
+  if (!stage) return null;
+  const viewRect = stage.getGameViewRect?.() || null;
+  return {
+    panEnabled: stage.panEnabled !== false,
+    cursor: { x: stage.cursorX, y: stage.cursorY },
+    viewRect: viewRect ? { ...viewRect } : null,
+    gameScale: stage.gameImgProps?.viewPoint?.scale ?? null,
+    guiScale: stage.guiImgProps?.viewPoint?.scale ?? null,
+    rawScale: stage._rawScale ?? null,
+    gamePosition: {
+      x: stage.gameImgProps?.x ?? null,
+      y: stage.gameImgProps?.y ?? null
+    },
+    guiPosition: {
+      x: stage.guiImgProps?.x ?? null,
+      y: stage.guiImgProps?.y ?? null
+    }
+  };
+};
+const getCanvasMetrics = (view) => {
+  const canvas = document.getElementById('gameCanvas');
+  if (!canvas || typeof canvas.getBoundingClientRect !== 'function') return null;
+  const rect = canvas.getBoundingClientRect();
+  const stage = view?.stage || null;
+  const gameRect = stage?.gameImgProps?.canvasViewportSize
+    ? {
+      x: stage.gameImgProps.x,
+      y: stage.gameImgProps.y,
+      width: stage.gameImgProps.canvasViewportSize.width,
+      height: stage.gameImgProps.canvasViewportSize.height
+    }
+    : null;
+  const guiRect = stage?.guiImgProps?.canvasViewportSize
+    ? {
+      x: stage.guiImgProps.x,
+      y: stage.guiImgProps.y,
+      width: stage.guiImgProps.canvasViewportSize.width,
+      height: stage.guiImgProps.canvasViewportSize.height
+    }
+    : null;
+  return {
+    rect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
+    size: { width: canvas.width, height: canvas.height },
+    gameRect,
+    guiRect
+  };
+};
+export {
+  getBenchMetrics,
+  toSortedStringList,
+  getRuntimeDiagnostics,
+  getCacheStorageKeys,
+  getEnvironmentDiagnostics,
+  getStageState,
+  getCanvasMetrics
+};
diff --git a/js/app/e2e/E2EEditorApply.js b/js/app/e2e/E2EEditorApply.js
new file mode 100644
index 00000000..3dfd0d68
--- /dev/null
+++ b/js/app/e2e/E2EEditorApply.js
@@ -0,0 +1,769 @@
+import {
+  BinaryReader,
+  EditorTools,
+  LevelReader,
+  LevelWriter,
+  createClassicLevelData,
+  createEditorLevelFromClassic,
+  createGadgetEntry,
+  createSteelEntry,
+  createTerrainEntry,
+  ensureLevelEntryUids,
+  findEntryAt,
+  loadSavedLevel,
+  removeEntryAt,
+  saveLevel,
+  setEntryProp,
+  validateLevel
+} from './e2eShared.js';
+import {
+  encodeBase64,
+  getEditorHistoryEntry,
+  serializeIssues
+} from './E2EStateSerialization.js';
+import {
+  boxSelectEntries,
+  boundsIntersect,
+  cloneEntryForApply,
+  getEditorContext,
+  getListForKind,
+  getPrefixForKind,
+  normalizeBounds,
+  resolveEntryRef,
+  resolveSelectionFromRefs
+} from './E2EEditorApplyHelpers.js';
+import {
+  buildApplyError,
+  buildEditorApplyState
+} from './E2EEditorApplyResult.js';
+const applyEditorOps = async (view, editorUi, ops = [], options = {}) => {
+  const ctx = getEditorContext(view, editorUi);
+  if (!ctx) {
+    return {
+      ok: false,
+      error: {
+        code: editorUi ? 'no_editor_session' : 'not_in_editor_mode',
+        message: 'Editor session is not available.'
+      }
+    };
+  }
+
+  ensureLevelEntryUids(ctx.session.level);
+
+  const atomic = options?.atomic === true;
+  const dryRun = options?.dryRun === true;
+  const historyOptions = options?.history || {};
+  const previewOptions = options?.preview || {};
+  const validateOptions = options?.validate || {};
+  const returnState = options?.returnState || 'editor';
+  const historyLabel = historyOptions.label || 'Editor Apply';
+  const previewLabel = previewOptions.label || historyLabel;
+
+  const results = [];
+  const resources = [];
+  let changed = false;
+  let usedHistoryOp = false;
+  const rollbackText = atomic && typeof view?.getEditorLevelText === 'function'
+    ? view.getEditorLevelText()
+    : null;
+
+  const registerResource = (resource) => {
+    if (!resource) return;
+    resources.push(resource);
+  };
+
+  const getLevel = () => ctx.session.level;
+
+  const applySnap = (x, y, snapMode) => {
+    if (!snapMode || snapMode === 'useCurrent') {
+      return ctx.controller._snap ? ctx.controller._snap(x, y) : { x, y };
+    }
+    if (snapMode === 'none') return { x, y };
+    const gridSize = Number(snapMode.gridSize);
+    if (!Number.isFinite(gridSize) || gridSize <= 1) {
+      return { x: Math.round(x), y: Math.round(y) };
+    }
+    return {
+      x: Math.round(x / gridSize) * gridSize,
+      y: Math.round(y / gridSize) * gridSize
+    };
+  };
+
+  const validateAndFix = () => {
+    if (validateOptions.run === false) return null;
+    const issues = validateLevel(getLevel(), ctx.assets, {
+      solverAdvisorySource: view?.game?.level || null
+    });
+    if (validateOptions.autoFix && validateOptions.autoFix !== 'none') {
+      let fixed = false;
+      for (const issue of issues) {
+        if (typeof issue.fix === 'function') {
+          issue.fix();
+          fixed = true;
+        }
+      }
+      if (fixed) {
+        changed = true;
+      }
+    }
+    return serializeIssues(issues);
+  };
+
+  for (const op of ops || []) {
+    const opId = op?.opId ?? null;
+    const type = String(op?.type || '');
+    const args = op?.args || {};
+    let value = null;
+    let ok = true;
+    let errorCode = 'invalid_op';
+    let errorMessage = 'Invalid op';
+    try {
+      switch (type) {
+      case 'editor.ensure': {
+        if (args?.enter && view?.enterEditorMode) {
+          view.enterEditorMode();
+        }
+        value = { inEditor: !!view?.editorMode };
+        break;
+      }
+      case 'level.new': {
+        if (dryRun) break;
+        view?.createBlankEditorLevel?.({ render: false });
+        ctx.session = view?.editorSession || ctx.session;
+        ctx.controller.session = ctx.session;
+        ensureLevelEntryUids(ctx.session.level);
+        if (args?.header && ctx.session.level) {
+          for (const [key, val] of Object.entries(args.header)) {
+            ctx.session.level.setHeader(key, val);
+          }
+        }
+        if (args?.skillset && ctx.session.level?.skillset) {
+          for (const [key, val] of Object.entries(args.skillset)) {
+            ctx.session.level.setSkill(key, val);
+          }
+        }
+        if (args?.resetHistory) {
+          ctx.controller.resetHistory('New');
+        }
+        changed = true;
+        value = { created: true };
+        break;
+      }
+      case 'level.loadText': {
+        if (dryRun) break;
+        const text = String(args?.text || '');
+        const level = view?.loadEditorLevelFromText?.(text, { render: false });
+        if (!level) {
+          ok = false;
+          errorCode = 'invalid_op';
+          errorMessage = 'Failed to load level text.';
+          break;
+        }
+        ctx.session = view?.editorSession || ctx.session;
+        ctx.controller.session = ctx.session;
+        ensureLevelEntryUids(ctx.session.level);
+        if (args?.resetHistory) {
+          ctx.controller.resetHistory(args?.sourceLabel || 'Import');
+        }
+        changed = true;
+        break;
+      }
+      case 'level.loadSaved': {
+        if (dryRun) break;
+        const text = loadSavedLevel(undefined, args?.savedId);
+        if (!text) {
+          ok = false;
+          errorCode = 'invalid_ref';
+          errorMessage = 'Saved level not found.';
+          break;
+        }
+        const level = view?.loadEditorLevelFromText?.(text, { render: false });
+        if (!level) {
+          ok = false;
+          errorCode = 'invalid_op';
+          errorMessage = 'Failed to load saved level.';
+          break;
+        }
+        ctx.session = view?.editorSession || ctx.session;
+        ctx.controller.session = ctx.session;
+        ensureLevelEntryUids(ctx.session.level);
+        if (args?.resetHistory) {
+          ctx.controller.resetHistory('Load Saved');
+        }
+        changed = true;
+        break;
+      }
+      case 'level.save': {
+        const name = String(args?.name || '');
+        const text = view?.getEditorLevelText?.();
+        if (!text) {
+          ok = false;
+          errorCode = 'invalid_op';
+          errorMessage = 'Unable to serialize level.';
+          break;
+        }
+        const savedId = saveLevel(undefined, {
+          id: args?.overwriteId || undefined,
+          name,
+          text
+        });
+        if (!savedId) {
+          ok = false;
+          errorCode = 'internal_error';
+          errorMessage = 'Failed to save level.';
+          break;
+        }
+        value = { savedId, name };
+        break;
+      }
+      case 'level.export': {
+        const format = args?.format === 'classicLvl' ? 'classicLvl' : 'nxlv';
+        if (format === 'nxlv') {
+          const text = view?.getEditorLevelText?.() || '';
+          const filename = String(args?.filename || 'level.nxlv');
+          registerResource({
+            name: filename,
+            mimeType: 'text/plain',
+            encoding: 'text',
+            data: text,
+            meta: { kind: 'export', format: 'nxlv', label: filename }
+          });
+          value = { filename };
+        } else {
+          const classic = createClassicLevelData(getLevel());
+          if (!classic?.levelReader) {
+            ok = false;
+            errorCode = 'internal_error';
+            errorMessage = 'Failed to export classic level.';
+            break;
+          }
+          const writer = new LevelWriter();
+          const payload = {
+            levelProperties: classic.levelReader.levelProperties,
+            screenPositionX: classic.levelReader.screenPositionX,
+            graphicSet1: classic.levelReader.graphicSet1,
+            graphicSet2: classic.levelReader.graphicSet2,
+            isSuperLemming: classic.levelReader.isSuperLemming,
+            objects: classic.levelReader.objects,
+            terrains: classic.levelReader.terrains,
+            steel: classic.levelReader.steel
+          };
+          const bytes = writer.write(payload);
+          const filename = String(args?.filename || 'level.lvl');
+          registerResource({
+            name: filename,
+            mimeType: 'application/octet-stream',
+            encoding: 'base64',
+            data: encodeBase64(bytes),
+            meta: { kind: 'export', format: 'classicLvl', label: filename }
+          });
+          value = { filename };
+        }
+        break;
+      }
+      case 'level.importClassicLvl': {
+        if (dryRun) break;
+        const raw = String(args?.bytesBase64 || '');
+        if (!raw) {
+          ok = false;
+          errorCode = 'invalid_op';
+          errorMessage = 'Missing classic level bytes.';
+          break;
+        }
+        const bytes = Uint8Array.from(atob(raw), c => c.charCodeAt(0));
+        const reader = new BinaryReader(bytes);
+        const levelReader = new LevelReader(reader);
+        const editorLevel = createEditorLevelFromClassic(levelReader);
+        if (!editorLevel) {
+          ok = false;
+          errorCode = 'invalid_op';
+          errorMessage = 'Failed to parse classic level.';
+          break;
+        }
+        ctx.session.level = editorLevel;
+        ensureLevelEntryUids(ctx.session.level);
+        if (args?.resetHistory) {
+          ctx.controller.resetHistory(args?.sourceLabel || 'Import LVL');
+        }
+        changed = true;
+        break;
+      }
+      case 'level.patchHeader': {
+        if (dryRun) break;
+        const level = getLevel();
+        if (!level) break;
+        const set = args?.set || {};
+        for (const [key, val] of Object.entries(set)) {
+          level.setHeader(key, val);
+        }
+        if (Array.isArray(args?.unset)) {
+          for (const key of args.unset) {
+            level.removeHeader(key);
+          }
+        }
+        changed = true;
+        break;
+      }
+      case 'level.patchSkillset': {
+        if (dryRun) break;
+        const level = getLevel();
+        if (!level) break;
+        const set = args?.set || {};
+        for (const [key, val] of Object.entries(set)) {
+          level.setSkill(key, val);
+        }
+        if (Array.isArray(args?.unset)) {
+          for (const key of args.unset) {
+            level.skillset?.delete?.(String(key).trim().toUpperCase());
+          }
+        }
+        changed = true;
+        break;
+      }
+      case 'editor.setTool': {
+        const tool = args?.tool;
+        if (!tool) break;
+        const validTools = new Set(Object.values(EditorTools));
+        if (validTools.has(tool)) {
+          ctx.controller.setTool(tool);
+        }
+        value = { tool: ctx.controller.tool };
+        break;
+      }
+      case 'editor.setBrushSettings': {
+        if (Number.isFinite(args?.gridSize)) ctx.controller.gridSize = Math.max(1, Math.trunc(args.gridSize));
+        if (args?.snapEnabled !== undefined) ctx.controller.setSnapEnabled(!!args.snapEnabled);
+        if (Number.isFinite(args?.brushSize)) ctx.controller.setBrushSize(Math.max(1, Math.trunc(args.brushSize)));
+        if (args?.eraseGadgets !== undefined) ctx.controller.setEraseGadgets(!!args.eraseGadgets);
+        if (Number.isFinite(args?.handleSize)) ctx.controller.handleSize = Math.max(1, Math.trunc(args.handleSize));
+        value = {
+          gridSize: ctx.controller.gridSize,
+          snapEnabled: ctx.controller.snapEnabled,
+          brushSize: ctx.controller.brushSize,
+          eraseGadgets: ctx.controller.eraseGadgets,
+          handleSize: ctx.controller.handleSize
+        };
+        break;
+      }
+      case 'editor.setPaletteSelection': {
+        if (Number.isFinite(args?.selectedTerrainId)) ctx.controller.setSelectedTerrain(args.selectedTerrainId);
+        if (Number.isFinite(args?.selectedGadgetId)) ctx.controller.setSelectedGadget(args.selectedGadgetId);
+        if (Number.isFinite(args?.selectedTriggerId)) ctx.controller.setSelectedTrigger(args.selectedTriggerId);
+        value = {
+          selectedTerrainId: ctx.controller.selectedTerrainId,
+          selectedGadgetId: ctx.controller.selectedGadgetId,
+          selectedTriggerId: ctx.controller.selectedTriggerId
+        };
+        break;
+      }
+      case 'selection.clear': {
+        ctx.controller.clearSelection();
+        value = { cleared: true };
+        break;
+      }
+      case 'selection.set': {
+        const refs = resolveSelectionFromRefs(getLevel(), args?.selection);
+        ctx.controller._setSelection(refs);
+        value = { count: refs.length };
+        break;
+      }
+      case 'selection.hitTest': {
+        const x = Number(args?.x);
+        const y = Number(args?.y);
+        if (!Number.isFinite(x) || !Number.isFinite(y)) {
+          value = { hit: null };
+          break;
+        }
+        const kinds = Array.isArray(args?.kinds) ? args.kinds : ['terrain', 'gadget', 'steel'];
+        const level = getLevel();
+        let hit = null;
+        if (kinds.includes('gadget')) {
+          const gadgetHit = findEntryAt(level?.gadgets, ctx.assets?.gadgetById, x, y);
+          if (gadgetHit) hit = { kind: 'gadget', ...gadgetHit };
+        }
+        if (!hit && kinds.includes('steel')) {
+          const steelHit = findEntryAt(level?.steel, null, x, y);
+          if (steelHit) hit = { kind: 'steel', ...steelHit };
+        }
+        if (!hit && kinds.includes('terrain')) {
+          const terrainHit = findEntryAt(level?.terrains, ctx.assets?.terrainById, x, y);
+          if (terrainHit) hit = { kind: 'terrain', ...terrainHit };
+        }
+        if (hit && hit.entry) {
+          value = { hit: { kind: hit.kind, index: hit.index, uid: hit.entry.uid || null } };
+        } else {
+          value = { hit: null };
+        }
+        break;
+      }
+      case 'selection.boxSelect': {
+        const bounds = args?.bounds;
+        if (!bounds) {
+          value = { count: 0 };
+          break;
+        }
+        const next = boxSelectEntries({
+          level: getLevel(),
+          assets: ctx.assets,
+          bounds,
+          baseSelection: ctx.controller.selection,
+          mode: args?.mode || 'replace'
+        });
+        ctx.controller._setSelection(next);
+        value = { count: ctx.controller.selection.length };
+        break;
+      }
+      case 'entry.add': {
+        if (dryRun) break;
+        const kind = args?.kind;
+        const list = getListForKind(getLevel(), kind);
+        if (!Array.isArray(list)) {
+          ok = false;
+          errorCode = 'invalid_ref';
+          errorMessage = 'Invalid entry kind.';
+          break;
+        }
+        let entry = null;
+        if (kind === 'terrain') {
+          entry = createTerrainEntry({
+            styleName: getLevel()?.getHeader?.('STYLE'),
+            piece: args?.props?.PIECE ?? args?.props?.piece ?? args?.piece,
+            x: args?.props?.X ?? args?.props?.x ?? args?.x,
+            y: args?.props?.Y ?? args?.props?.y ?? args?.y
+          });
+        } else if (kind === 'gadget') {
+          entry = createGadgetEntry({
+            styleName: getLevel()?.getHeader?.('STYLE'),
+            piece: args?.props?.PIECE ?? args?.props?.piece ?? args?.piece,
+            x: args?.props?.X ?? args?.props?.x ?? args?.x,
+            y: args?.props?.Y ?? args?.props?.y ?? args?.y
+          });
+        } else if (kind === 'steel') {
+          entry = createSteelEntry({
+            x: args?.props?.X ?? args?.x,
+            y: args?.props?.Y ?? args?.y,
+            width: args?.props?.WIDTH ?? args?.width,
+            height: args?.props?.HEIGHT ?? args?.height
+          });
+        }
+        if (!entry) {
+          ok = false;
+          errorCode = 'invalid_op';
+          errorMessage = 'Failed to create entry.';
+          break;
+        }
+        const insert = args?.insert;
+        if (insert && Number.isFinite(insert.index)) {
+          const idx = Math.max(0, Math.min(list.length, Math.trunc(insert.index)));
+          list.splice(idx, 0, entry);
+          value = { ref: { kind, index: idx, uid: entry.uid || null } };
+        } else {
+          list.push(entry);
+          value = { ref: { kind, index: list.length - 1, uid: entry.uid || null } };
+        }
+        changed = true;
+        break;
+      }
+      case 'entry.update': {
+        if (dryRun) break;
+        const resolved = resolveEntryRef(getLevel(), args?.ref);
+        if (!resolved) {
+          ok = false;
+          errorCode = 'invalid_ref';
+          errorMessage = 'Entry not found.';
+          break;
+        }
+        const set = args?.set || {};
+        for (const [key, val] of Object.entries(set)) {
+          const removeIfFalse = typeof val === 'boolean';
+          setEntryProp(resolved.entry, key, val, { removeIfFalse });
+        }
+        if (Array.isArray(args?.unset)) {
+          for (const key of args.unset) {
+            setEntryProp(resolved.entry, key, undefined, { removeIfEmpty: true });
+          }
+        }
+        changed = true;
+        break;
+      }
+      case 'entry.remove': {
+        if (dryRun) break;
+        const refs = Array.isArray(args?.refs) ? args.refs : [];
+        const groups = { terrain: [], gadget: [], steel: [] };
+        for (const ref of refs) {
+          const resolved = resolveEntryRef(getLevel(), ref);
+          if (!resolved) continue;
+          groups[resolved.kind]?.push(resolved.index);
+        }
+        for (const [kind, indices] of Object.entries(groups)) {
+          indices.sort((a, b) => b - a);
+          for (const index of indices) {
+            removeEntryAt(getLevel(), kind, index);
+          }
+        }
+        changed = refs.length > 0;
+        break;
+      }
+      case 'entry.duplicate': {
+        if (dryRun) break;
+        const refs = Array.isArray(args?.refs) ? args.refs : [];
+        const dx = Number.isFinite(args?.offset?.dx) ? args.offset.dx : 0;
+        const dy = Number.isFinite(args?.offset?.dy) ? args.offset.dy : 0;
+        const nextRefs = [];
+        for (const ref of refs) {
+          const resolved = resolveEntryRef(getLevel(), ref);
+          if (!resolved) continue;
+          const prefix = getPrefixForKind(resolved.kind);
+          const clone = cloneEntryForApply(resolved.entry, prefix);
+          clone.props.X = (Number.isFinite(clone.props.X) ? clone.props.X : 0) + dx;
+          clone.props.Y = (Number.isFinite(clone.props.Y) ? clone.props.Y : 0) + dy;
+          resolved.list.push(clone);
+          nextRefs.push({ kind: resolved.kind, index: resolved.list.length - 1, uid: clone.uid || null });
+        }
+        if (args?.selectNew) {
+          ctx.controller._setSelection(nextRefs.map(ref => ({ type: ref.kind, index: ref.index })));
+        }
+        value = { refs: nextRefs };
+        changed = nextRefs.length > 0;
+        break;
+      }
+      case 'entry.reorder': {
+        if (dryRun) break;
+        const action = args?.action;
+        const selection = ctx.controller.selection.slice();
+        const groups = { terrain: [], gadget: [], steel: [] };
+        for (const selected of selection) {
+          if (groups[selected.type]) groups[selected.type].push(selected.index);
+        }
+        const reorderList = (list, indices, dir) => {
+          if (!Array.isArray(list) || indices.length === 0) return null;
+          const unique = Array.from(new Set(indices)).filter(idx => idx >= 0 && idx < list.length);
+          if (!unique.length) return null;
+          const selectedSet = new Set(unique);
+          if (dir === 'front' || dir === 'back') {
+            const ordered = unique.slice().sort((a, b) => a - b).map(idx => list[idx]);
+            const remaining = list.filter((_, idx) => !selectedSet.has(idx));
+            list.length = 0;
+            if (dir === 'front') {
+              list.push(...remaining, ...ordered);
+            } else {
+              list.push(...ordered, ...remaining);
+            }
+            const next = new Map();
+            list.forEach((entry, idx) => next.set(entry, idx));
+            return ordered.map(entry => next.get(entry)).filter(idx => idx != null);
+          }
+          if (dir === 'forward') {
+            const sorted = unique.slice().sort((a, b) => b - a);
+            for (const idx of sorted) {
+              if (idx >= list.length - 1) continue;
+              if (selectedSet.has(idx + 1)) continue;
+              const tmp = list[idx + 1];
+              list[idx + 1] = list[idx];
+              list[idx] = tmp;
+              selectedSet.delete(idx);
+              selectedSet.add(idx + 1);
+            }
+            return Array.from(selectedSet);
+          }
+          if (dir === 'backward') {
+            const sorted = unique.slice().sort((a, b) => a - b);
+            for (const idx of sorted) {
+              if (idx <= 0) continue;
+              if (selectedSet.has(idx - 1)) continue;
+              const tmp = list[idx - 1];
+              list[idx - 1] = list[idx];
+              list[idx] = tmp;
+              selectedSet.delete(idx);
+              selectedSet.add(idx - 1);
+            }
+            return Array.from(selectedSet);
+          }
+          return null;
+        };
+        const nextSelection = [];
+        for (const [kind, indices] of Object.entries(groups)) {
+          const list = getListForKind(getLevel(), kind);
+          const nextIndices = reorderList(list, indices, action === 'bringToFront' ? 'front'
+            : action === 'sendToBack' ? 'back'
+              : action === 'moveForward' ? 'forward'
+                : action === 'moveBackward' ? 'backward'
+                  : null);
+          if (!nextIndices) continue;
+          for (const idx of nextIndices) {
+            nextSelection.push({ type: kind, index: idx });
+          }
+        }
+        if (nextSelection.length) {
+          ctx.controller._setSelection(nextSelection);
+        }
+        changed = nextSelection.length > 0;
+        break;
+      }
+      case 'tool.place': {
+        if (dryRun) break;
+        const tool = String(args?.tool || '');
+        const pos = applySnap(Number(args?.x || 0), Number(args?.y || 0), args?.snap);
+        let entry = null;
+        if (tool === EditorTools.TERRAIN) {
+          if (Number.isFinite(args?.pieceId)) ctx.controller.setSelectedTerrain(args.pieceId);
+          entry = ctx.controller._placeTerrainAt(pos.x, pos.y);
+        } else if (tool === EditorTools.GADGET) {
+          if (Number.isFinite(args?.pieceId)) ctx.controller.setSelectedGadget(args.pieceId);
+          entry = ctx.controller._placeGadgetAt(pos.x, pos.y, ctx.controller.selectedGadgetId);
+        } else if (tool === EditorTools.TRIGGER) {
+          if (Number.isFinite(args?.pieceId)) ctx.controller.setSelectedTrigger(args.pieceId);
+          const id = ctx.controller.selectedTriggerId ?? ctx.controller.selectedGadgetId;
+          entry = ctx.controller._placeGadgetAt(pos.x, pos.y, id);
+        } else if (tool === EditorTools.ENTRANCE) {
+          const id = ctx.assets?.entranceId ?? ctx.controller.selectedGadgetId;
+          entry = ctx.controller._placeGadgetAt(pos.x, pos.y, id);
+        } else if (tool === EditorTools.EXIT) {
+          const id = ctx.assets?.exitId ?? ctx.controller.selectedGadgetId;
+          entry = ctx.controller._placeGadgetAt(pos.x, pos.y, id);
+        } else if (tool === EditorTools.STEEL) {
+          const size = Number.isFinite(ctx.controller.gridSize) ? ctx.controller.gridSize : 1;
+          entry = ctx.controller._placeSteelAt(pos.x, pos.y, size, size);
+        }
+        if (entry) {
+          const kind = tool === EditorTools.STEEL ? 'steel'
+            : tool === EditorTools.GADGET || tool === EditorTools.TRIGGER || tool === EditorTools.ENTRANCE || tool === EditorTools.EXIT
+              ? 'gadget'
+              : 'terrain';
+          const list = getListForKind(getLevel(), kind);
+          const index = Array.isArray(list) ? list.indexOf(entry) : -1;
+          if (index >= 0) {
+            ctx.controller._setSelection([{ type: kind, index }]);
+            value = { ref: { kind, index, uid: entry.uid || null } };
+          }
+          changed = true;
+        }
+        break;
+      }
+      case 'tool.stroke':
+      case 'tool.erase': {
+        if (dryRun) break;
+        const tool = type === 'tool.erase' ? EditorTools.ERASER : String(args?.tool || '');
+        const points = Array.isArray(args?.points) ? args.points : [];
+        if (!points.length) break;
+        const prevErase = ctx.controller.eraseGadgets;
+        if (typeof args?.eraseGadgets === 'boolean') {
+          ctx.controller.setEraseGadgets(args.eraseGadgets);
+        }
+        ctx.controller._beginStroke();
+        let last = null;
+        for (const point of points) {
+          const pos = applySnap(Number(point.x || 0), Number(point.y || 0), args?.snap);
+          if (tool === EditorTools.BRUSH) {
+            if (last) ctx.controller._brushLine(last, pos);
+            else ctx.controller._brushAt(pos.x, pos.y);
+          } else if (tool === EditorTools.ERASER) {
+            if (last) ctx.controller._eraseLine(last, pos);
+            else ctx.controller._eraseAt(pos.x, pos.y);
+          }
+          last = pos;
+        }
+        ctx.controller._lastBrushPos = null;
+        ctx.controller.setEraseGadgets(prevErase);
+        changed = true;
+        break;
+      }
+      case 'tool.steelRect': {
+        if (dryRun) break;
+        const rects = Array.isArray(args?.rects) ? args.rects : [];
+        for (const rect of rects) {
+          const bounds = normalizeBounds(rect.x, rect.y, rect.x + rect.width, rect.y + rect.height);
+          ctx.controller._placeSteelAt(bounds.x, bounds.y, bounds.width, bounds.height);
+        }
+        changed = rects.length > 0;
+        break;
+      }
+      case 'history.undo': {
+        usedHistoryOp = true;
+        const count = Number.isFinite(args?.count) ? Math.max(1, Math.trunc(args.count)) : 1;
+        for (let i = 0; i < count; i++) {
+          ctx.controller.undo();
+        }
+        value = { count };
+        break;
+      }
+      case 'history.redo': {
+        usedHistoryOp = true;
+        const count = Number.isFinite(args?.count) ? Math.max(1, Math.trunc(args.count)) : 1;
+        for (let i = 0; i < count; i++) {
+          ctx.controller.redo();
+        }
+        value = { count };
+        break;
+      }
+      case 'history.getEntry': {
+        const entry = getEditorHistoryEntry(ctx.history, Number(args?.index));
+        value = entry || null;
+        break;
+      }
+      case 'validate.run': {
+        value = validateAndFix();
+        break;
+      }
+      default:
+        ok = false;
+        errorCode = 'invalid_op';
+        errorMessage = `Unknown op: ${type}`;
+        break;
+      }
+    } catch (err) {
+      ok = false;
+      errorCode = 'internal_error';
+      errorMessage = err ? String(err) : 'Unknown error';
+    }
+
+    if (ok) {
+      results.push({ opId, type, ok: true, value });
+    } else {
+      results.push({ opId, type, ok: false, error: errorMessage });
+      if (atomic) {
+        if (rollbackText && typeof view?.loadEditorLevelFromText === 'function') {
+          view.loadEditorLevelFromText(rollbackText, { render: false });
+          ctx.session = view?.editorSession || ctx.session;
+          ctx.controller.session = ctx.session;
+          ensureLevelEntryUids(ctx.session.level);
+        }
+        return buildApplyError(errorCode, errorMessage, undefined, results);
+      }
+    }
+  }
+
+  const validation = validateAndFix();
+  if (validation) {
+    results.push({ opId: null, type: 'validate.run', ok: true, value: validation });
+  }
+
+  if (historyOptions.record !== false && changed && !usedHistoryOp) {
+    ctx.controller.history.pushSnapshot(getLevel(), historyLabel);
+  }
+
+  if (previewOptions.refresh !== false && ctx.editorUi?._refreshPreview) {
+    await ctx.editorUi._refreshPreview(previewLabel, {
+      preserveView: previewOptions.preserveViewport !== false
+    });
+  }
+
+  const state = buildEditorApplyState(view, editorUi, returnState);
+
+  return {
+    ok: true,
+    results,
+    resources,
+    state
+  };
+};
+export {
+  getEditorContext,
+  getListForKind,
+  getPrefixForKind,
+  resolveEntryRef,
+  cloneEntryForApply,
+  normalizeBounds,
+  boundsIntersect,
+  applyEditorOps
+};
diff --git a/js/app/e2e/E2EEditorApplyHelpers.js b/js/app/e2e/E2EEditorApplyHelpers.js
new file mode 100644
index 00000000..0c80c92b
--- /dev/null
+++ b/js/app/e2e/E2EEditorApplyHelpers.js
@@ -0,0 +1,136 @@
+import {
+  ensureEntryUid,
+  getEntryBounds
+} from './e2eShared.js';
+
+const getEditorContext = (view, editorUi) => {
+  if (!editorUi) return null;
+  const session = editorUi.session || view?.editorSession || null;
+  const controller = editorUi.controller || null;
+  const history = editorUi.history || null;
+  if (!session || !session.level || !controller || !history) return null;
+  return {
+    session,
+    controller,
+    history,
+    assets: editorUi.assets || null,
+    editorUi
+  };
+};
+
+const getListForKind = (level, kind) => {
+  if (!level) return null;
+  if (kind === 'gadget') return level.gadgets;
+  if (kind === 'steel') return level.steel;
+  if (kind === 'terrain') return level.terrains;
+  return null;
+};
+
+const getPrefixForKind = (kind) => {
+  if (kind === 'gadget') return 'g';
+  if (kind === 'steel') return 's';
+  return 't';
+};
+
+const resolveEntryRef = (level, ref) => {
+  if (!ref || !level) return null;
+  const kind = ref.kind || ref.type;
+  const list = getListForKind(level, kind);
+  if (!Array.isArray(list)) return null;
+  let index = Number.isFinite(ref.index) ? Math.trunc(ref.index) : null;
+  if (!Number.isFinite(index) && ref.uid) {
+    index = list.findIndex(entry => entry?.uid === ref.uid);
+  }
+  if (!Number.isFinite(index) || index < 0 || index >= list.length) return null;
+  return { kind, list, index, entry: list[index] };
+};
+
+const cloneEntryForApply = (entry, prefix) => {
+  const props = entry?.props ? { ...entry.props } : {};
+  const order = Array.isArray(entry?.order) ? entry.order.slice() : Object.keys(props);
+  const unknownLines = Array.isArray(entry?.unknownLines) ? entry.unknownLines.slice() : [];
+  const clone = { props, order, unknownLines };
+  ensureEntryUid(clone, prefix);
+  return clone;
+};
+
+const normalizeBounds = (x1, y1, x2, y2) => {
+  const left = Math.min(x1, x2);
+  const right = Math.max(x1, x2);
+  const top = Math.min(y1, y2);
+  const bottom = Math.max(y1, y2);
+  return {
+    x: left,
+    y: top,
+    width: Math.max(1, right - left),
+    height: Math.max(1, bottom - top)
+  };
+};
+
+const boundsIntersect = (a, b) => {
+  if (!a || !b) return false;
+  return a.x <= b.x + b.width
+    && a.x + a.width >= b.x
+    && a.y <= b.y + b.height
+    && a.y + a.height >= b.y;
+};
+
+const resolveSelectionFromRefs = (level, refs) => {
+  if (!Array.isArray(refs)) return [];
+  const next = [];
+  for (const ref of refs) {
+    const resolved = resolveEntryRef(level, ref);
+    if (!resolved) continue;
+    next.push({ type: resolved.kind, index: resolved.index });
+  }
+  return next;
+};
+
+const boxSelectEntries = ({ level, assets, bounds, baseSelection = [], mode = 'replace' }) => {
+  const hits = [];
+  const addHit = (type, index) => {
+    if (hits.some(entry => entry.type === type && entry.index === index)) return;
+    hits.push({ type, index });
+  };
+  const scan = (entries, metaById, type) => {
+    if (!Array.isArray(entries)) return;
+    for (let i = 0; i < entries.length; i++) {
+      const entry = entries[i];
+      const meta = metaById?.get?.(entry?.props?.PIECE);
+      const entryBounds = getEntryBounds(entry, meta);
+      if (boundsIntersect(bounds, entryBounds)) addHit(type, i);
+    }
+  };
+  scan(level?.terrains, assets?.terrainById, 'terrain');
+  scan(level?.gadgets, assets?.gadgetById, 'gadget');
+  scan(level?.steel, null, 'steel');
+  if (mode === 'replace') {
+    return hits;
+  }
+  const next = baseSelection.slice();
+  for (const hit of hits) {
+    const idx = next.findIndex(entry => entry.type === hit.type && entry.index === hit.index);
+    if (mode === 'add') {
+      if (idx < 0) next.push(hit);
+    } else if (mode === 'toggle') {
+      if (idx >= 0) {
+        next.splice(idx, 1);
+      } else {
+        next.push(hit);
+      }
+    }
+  }
+  return next;
+};
+
+export {
+  boxSelectEntries,
+  boundsIntersect,
+  cloneEntryForApply,
+  getEditorContext,
+  getListForKind,
+  getPrefixForKind,
+  normalizeBounds,
+  resolveEntryRef,
+  resolveSelectionFromRefs
+};
diff --git a/js/app/e2e/E2EEditorApplyResult.js b/js/app/e2e/E2EEditorApplyResult.js
new file mode 100644
index 00000000..76821a18
--- /dev/null
+++ b/js/app/e2e/E2EEditorApplyResult.js
@@ -0,0 +1,47 @@
+import {
+  getBenchMetrics,
+  getEnvironmentDiagnostics,
+  getStageState
+} from './E2EDiagnostics.js';
+import { getEditorState } from './E2EEditorState.js';
+import {
+  getGameState,
+  getViewState,
+  isGameReady
+} from './E2EStateSerialization.js';
+
+const buildEditorApplyState = (view, editorUi, returnState) => {
+  if (returnState === 'editor') {
+    return getEditorState(view, editorUi);
+  }
+  if (returnState !== 'full') {
+    return null;
+  }
+  return {
+    version: 1,
+    mode: editorUi ? 'editor' : (view?.editorMode ? 'editor' : 'game'),
+    ready: isGameReady(view),
+    view: getViewState(view),
+    stage: getStageState(view?.stage),
+    game: getGameState(view),
+    editor: getEditorState(view, editorUi),
+    bench: getBenchMetrics(view),
+    diagnostics: getEnvironmentDiagnostics(view),
+    midi: {
+      enabled: !!view?.midiEnabled,
+      hasRouter: !!view?.midiRouter,
+      outputName: view?.midiOut?.name || null
+    }
+  };
+};
+
+const buildApplyError = (code, message, details, results) => ({
+  ok: false,
+  error: { code, message, details },
+  results
+});
+
+export {
+  buildApplyError,
+  buildEditorApplyState
+};
diff --git a/js/app/e2e/E2EEditorState.js b/js/app/e2e/E2EEditorState.js
new file mode 100644
index 00000000..ccb3645b
--- /dev/null
+++ b/js/app/e2e/E2EEditorState.js
@@ -0,0 +1,156 @@
+import {
+  BASE64_CHUNK,
+  BinaryReader,
+  DTYPE_MAP,
+  E2E_QUERY_KEY,
+  EditorTools,
+  LevelReader,
+  LevelWriter,
+  createClassicLevelData,
+  createEditorLevelFromClassic,
+  createGadgetEntry,
+  createSteelEntry,
+  createTerrainEntry,
+  ensureEntryUid,
+  ensureLevelEntryUids,
+  findEntryAt,
+  getEntryBounds,
+  getRuntimeDependency,
+  listSavedLevels,
+  loadSavedLevel,
+  removeEntryAt,
+  saveLevel,
+  setEntryProp,
+  validateLevel
+} from './e2eShared.js';
+import {
+  isE2EEnabled,
+  normalizeBufferName,
+  toByteView,
+  encodeBase64,
+  packBuffer,
+  cloneEntry,
+  cloneTerrainGroup,
+  cloneUnknownSection,
+  serializeEditorLevel,
+  serializeSelectionEntry,
+  serializeEditorController,
+  summarizeEditorHistory,
+  getEditorHistoryEntry,
+  serializeIssues,
+  serializeAssets,
+  getActionType,
+  serializeLemming,
+  serializeTrigger,
+  serializeMapObject,
+  isGameReady,
+  getViewState,
+  getGameState
+} from './E2EStateSerialization.js';
+import {
+  getBenchMetrics,
+  toSortedStringList,
+  getRuntimeDiagnostics,
+  getCacheStorageKeys,
+  getEnvironmentDiagnostics,
+  getStageState,
+  getCanvasMetrics
+} from './E2EDiagnostics.js';
+import {
+  getEditorContext,
+  getListForKind,
+  getPrefixForKind,
+  resolveEntryRef,
+  cloneEntryForApply,
+  normalizeBounds,
+  boundsIntersect,
+  applyEditorOps
+} from './E2EEditorApply.js';
+import {
+  getBuffer,
+  getEditorLevelText,
+  getStageCanvasRect,
+  getStageWorldPointFromPage,
+  getStagePagePointFromWorld,
+  centerStageOn,
+  getMinimapPagePoint
+} from './E2ECanvasHarness.js';
+import {
+  pauseGame,
+  resumeGame,
+  stepGame,
+  seekGame,
+  setEditorPlaytest,
+  setSpeed,
+  selectLemmingById,
+  centerViewOnLemming,
+  startReverse,
+  stopReverse,
+  toggleReverse,
+  flushSoundEvents,
+  getHistoryDelta,
+  getHistoryDeltas,
+  startBenchSequence,
+  startBench,
+  stopBench
+} from './E2EGameControls.js';
+const getEditorState = (view, editorUi) => {
+  const session = editorUi?.session || view?.editorSession || null;
+  const controller = editorUi?.controller || null;
+  const history = editorUi?.history || null;
+  const level = session?.level || null;
+  const issues = serializeIssues(validateLevel(level, editorUi?.assets || null, {
+    solverAdvisorySource: view?.game?.level || null
+  }));
+  return {
+    mode: !!view?.editorMode,
+    playtest: !!view?.editorPlaytest,
+    session: session
+      ? {
+        title: session.getTitle?.() || null,
+        level: serializeEditorLevel(level)
+      }
+      : null,
+    controller: serializeEditorController(controller),
+    history: summarizeEditorHistory(history),
+    ui: editorUi
+      ? {
+        activeTab: editorUi._activeTab,
+        currentSavedId: editorUi._currentSavedId,
+        playtest: !!editorUi._playtest,
+        previewInFlight: !!editorUi._previewInFlight,
+        previewQueued: !!editorUi._previewQueued,
+        cursorPos: editorUi._cursorPos ? { ...editorUi._cursorPos } : null,
+        pointerDown: !!editorUi._pointerDown,
+        shiftKey: !!editorUi._shiftKey,
+        altKey: !!editorUi._altKey,
+        antsOffset: editorUi._antsOffset ?? 0,
+        selectionCount: editorUi._selection?.length ?? 0,
+        suppressHeader: !!editorUi._suppressHeader,
+        suppressInspector: !!editorUi._suppressInspector,
+        paletteSearch: editorUi.el?.paletteSearch?.value ?? '',
+        solvability: editorUi._lastSolvabilityCheck
+          ? {
+            status: editorUi._lastSolvabilityCheck.status || 'idle',
+            message: editorUi._lastSolvabilityCheck.message || '',
+            warningCount: editorUi._lastSolvabilityCheck.warningCount || 0,
+            warnings: Array.isArray(editorUi._lastSolvabilityCheck.warnings)
+              ? editorUi._lastSolvabilityCheck.warnings.map(warning => ({
+                code: warning.code || null,
+                message: warning.message || '',
+                target: warning.target || null
+              }))
+              : [],
+            budgetUsage: editorUi._lastSolvabilityCheck.budgetUsage || null
+          }
+          : null
+      }
+      : null,
+    assets: serializeAssets(editorUi?.assets || null),
+    validation: issues,
+    savedLevels: listSavedLevels()
+  };
+};
+export {
+  getEditorState
+};
diff --git a/js/app/e2e/E2EGameControls.js b/js/app/e2e/E2EGameControls.js
new file mode 100644
index 00000000..3ce12f2b
--- /dev/null
+++ b/js/app/e2e/E2EGameControls.js
@@ -0,0 +1,252 @@
+import {
+  BASE64_CHUNK,
+  BinaryReader,
+  DTYPE_MAP,
+  E2E_QUERY_KEY,
+  EditorTools,
+  LevelReader,
+  LevelWriter,
+  createClassicLevelData,
+  createEditorLevelFromClassic,
+  createGadgetEntry,
+  createSteelEntry,
+  createTerrainEntry,
+  ensureEntryUid,
+  ensureLevelEntryUids,
+  findEntryAt,
+  getEntryBounds,
+  getRuntimeDependency,
+  listSavedLevels,
+  loadSavedLevel,
+  removeEntryAt,
+  saveLevel,
+  setEntryProp,
+  validateLevel
+} from './e2eShared.js';
+import {
+  isE2EEnabled,
+  normalizeBufferName,
+  toByteView,
+  encodeBase64,
+  packBuffer,
+  cloneEntry,
+  cloneTerrainGroup,
+  cloneUnknownSection,
+  serializeEditorLevel,
+  serializeSelectionEntry,
+  serializeEditorController,
+  summarizeEditorHistory,
+  getEditorHistoryEntry,
+  serializeIssues,
+  serializeAssets,
+  getActionType,
+  serializeLemming,
+  serializeTrigger,
+  serializeMapObject,
+  isGameReady,
+  getViewState,
+  getGameState
+} from './E2EStateSerialization.js';
+import {
+  getBenchMetrics,
+  toSortedStringList,
+  getRuntimeDiagnostics,
+  getCacheStorageKeys,
+  getEnvironmentDiagnostics,
+  getStageState,
+  getCanvasMetrics
+} from './E2EDiagnostics.js';
+import {
+  getEditorState
+} from './E2EEditorState.js';
+import {
+  getEditorContext,
+  getListForKind,
+  getPrefixForKind,
+  resolveEntryRef,
+  cloneEntryForApply,
+  normalizeBounds,
+  boundsIntersect,
+  applyEditorOps
+} from './E2EEditorApply.js';
+import {
+  getBuffer,
+  getEditorLevelText,
+  getStageCanvasRect,
+  getStageWorldPointFromPage,
+  getStagePagePointFromWorld,
+  centerStageOn,
+  getMinimapPagePoint
+} from './E2ECanvasHarness.js';
+const pauseGame = (view) => {
+  const timer = view?.game?.getGameTimer?.();
+  if (!timer) return false;
+  timer.suspend?.();
+  return true;
+};
+const resumeGame = (view) => {
+  const timer = view?.game?.getGameTimer?.();
+  if (!timer) return false;
+  timer.continue?.();
+  return true;
+};
+const stepGame = (view, count = 1) => {
+  const game = view?.game;
+  const timer = game?.getGameTimer?.();
+  if (!game || !timer) return false;
+  if (timer.isRunning?.()) timer.suspend?.();
+  const steps = Math.trunc(count);
+  if (!steps) return true;
+  if (steps > 0) {
+    if (game.timeTravel?.isReversing) game.timeTravel.stopReverse?.();
+    game.history?.truncateAfter?.(timer.tickIndex);
+  }
+  timer.tick(steps);
+  if (game.gameGui) {
+    game.gameGui.gameTimeChanged = true;
+  }
+  game.render?.();
+  return true;
+};
+const seekGame = (view, tickIndex) => {
+  const game = view?.game;
+  const timer = game?.getGameTimer?.();
+  if (!game || !timer) return false;
+  if (timer.isRunning?.()) timer.suspend?.();
+  if (game.timeTravel?.seekToTick) {
+    game.timeTravel.seekToTick(tickIndex);
+    return true;
+  }
+  return false;
+};
+const setEditorPlaytest = (view, editorUi, enabled) => {
+  const desired = !!enabled;
+  if (editorUi && editorUi._playtest !== desired && editorUi._togglePlaytest) {
+    editorUi._togglePlaytest();
+    return true;
+  }
+  if (view?.setEditorPlaytest) {
+    view.setEditorPlaytest(desired);
+    return true;
+  }
+  return false;
+};
+const setSpeed = (view, speedFactor) => {
+  if (!view) return false;
+  const value = Number(speedFactor);
+  if (!Number.isFinite(value) || value <= 0) return false;
+  view.selectSpeedFactor?.(value);
+  return true;
+};
+const selectLemmingById = (view, lemmingId) => {
+  const manager = view?.game?.getLemmingManager?.();
+  const id = Number(lemmingId);
+  if (!manager || !Number.isFinite(id)) return false;
+  const lem = manager.getLemming?.(id);
+  if (!lem || lem.removed || lem.disabled) return false;
+  manager.setSelectedLemming?.(lem);
+  return true;
+};
+const centerViewOnLemming = (view, lemmingId) => {
+  const stage = view?.stage;
+  const manager = view?.game?.getLemmingManager?.();
+  const lem = manager?.getLemming?.(Number(lemmingId));
+  if (!stage || !lem) return false;
+  const rect = stage.getGameViewRect?.();
+  const point = stage.gameImgProps?.viewPoint;
+  if (!rect || !point) return false;
+  point.x = lem.x - rect.w / 2;
+  point.y = lem.y - rect.h / 2;
+  view?.render?.();
+  return true;
+};
+const startReverse = (view) => {
+  const timeTravel = view?.game?.timeTravel;
+  if (!timeTravel?.startReverse) return false;
+  timeTravel.startReverse();
+  return true;
+};
+const stopReverse = (view) => {
+  const timeTravel = view?.game?.timeTravel;
+  if (!timeTravel?.stopReverse) return false;
+  timeTravel.stopReverse();
+  return true;
+};
+const toggleReverse = (view) => {
+  const timeTravel = view?.game?.timeTravel;
+  if (!timeTravel?.toggleReverse) return false;
+  timeTravel.toggleReverse();
+  return true;
+};
+const flushSoundEvents = (view) => {
+  const soundEvents = view?.game?.soundEvents;
+  if (!soundEvents?.flush) return false;
+  soundEvents.flush();
+  return true;
+};
+const getHistoryDelta = (view, tickIndex) => {
+  const history = view?.game?.history;
+  const t = Math.trunc(Number(tickIndex));
+  if (!history?.getDelta || !Number.isFinite(t)) return null;
+  return history.getDelta(t) || null;
+};
+const getHistoryDeltas = (view, fromTick, toTick, maxTicks = 0) => {
+  const history = view?.game?.history;
+  if (!history?.getDelta) return [];
+
+  const start = Math.trunc(Number(fromTick));
+  const end = Math.trunc(Number(toTick));
+  if (!Number.isFinite(start) || !Number.isFinite(end)) return [];
+
+  const step = start <= end ? 1 : -1;
+  const limit = Number.isFinite(maxTicks) && maxTicks > 0 ? Math.trunc(maxTicks) : Infinity;
+
+  const deltas = [];
+  let n = 0;
+  for (let t = start; ; t += step) {
+    if (n >= limit) break;
+    const delta = history.getDelta(t);
+    if (delta) deltas.push(delta);
+    n += 1;
+    if (t === end) break;
+  }
+  return deltas;
+};
+const startBenchSequence = async (view) => {
+  if (!view?.benchSequenceStart) return false;
+  await view.benchSequenceStart();
+  return true;
+};
+const startBench = async (view, entrances = 1) => {
+  if (!view?.benchStart) return false;
+  const count = Math.max(1, Math.trunc(Number(entrances) || 1));
+  await view.benchStart(count);
+  return true;
+};
+const stopBench = (view) => {
+  if (!view) return false;
+  view.bench = false;
+  view.bench2 = false;
+  view.benchReverse = false;
+  view.benchSequence = false;
+  return true;
+};
+export {
+  pauseGame,
+  resumeGame,
+  stepGame,
+  seekGame,
+  setEditorPlaytest,
+  setSpeed,
+  selectLemmingById,
+  centerViewOnLemming,
+  startReverse,
+  stopReverse,
+  toggleReverse,
+  flushSoundEvents,
+  getHistoryDelta,
+  getHistoryDeltas,
+  startBenchSequence,
+  startBench,
+  stopBench
+};
diff --git a/js/app/e2e/E2EStateSerialization.js b/js/app/e2e/E2EStateSerialization.js
new file mode 100644
index 00000000..4e969977
--- /dev/null
+++ b/js/app/e2e/E2EStateSerialization.js
@@ -0,0 +1,597 @@
+import {
+  BASE64_CHUNK,
+  BinaryReader,
+  DTYPE_MAP,
+  E2E_QUERY_KEY,
+  EditorTools,
+  LevelReader,
+  LevelWriter,
+  createClassicLevelData,
+  createEditorLevelFromClassic,
+  createGadgetEntry,
+  createSteelEntry,
+  createTerrainEntry,
+  ensureEntryUid,
+  ensureLevelEntryUids,
+  findEntryAt,
+  getEntryBounds,
+  getRuntimeDependency,
+  listSavedLevels,
+  loadSavedLevel,
+  removeEntryAt,
+  saveLevel,
+  setEntryProp,
+  validateLevel
+} from './e2eShared.js';
+import {
+  getBenchMetrics,
+  toSortedStringList,
+  getRuntimeDiagnostics,
+  getCacheStorageKeys,
+  getEnvironmentDiagnostics,
+  getStageState,
+  getCanvasMetrics
+} from './E2EDiagnostics.js';
+import {
+  getEditorState
+} from './E2EEditorState.js';
+import {
+  getEditorContext,
+  getListForKind,
+  getPrefixForKind,
+  resolveEntryRef,
+  cloneEntryForApply,
+  normalizeBounds,
+  boundsIntersect,
+  applyEditorOps
+} from './E2EEditorApply.js';
+import {
+  getBuffer,
+  getEditorLevelText,
+  getStageCanvasRect,
+  getStageWorldPointFromPage,
+  getStagePagePointFromWorld,
+  centerStageOn,
+  getMinimapPagePoint
+} from './E2ECanvasHarness.js';
+import {
+  pauseGame,
+  resumeGame,
+  stepGame,
+  seekGame,
+  setEditorPlaytest,
+  setSpeed,
+  selectLemmingById,
+  centerViewOnLemming,
+  startReverse,
+  stopReverse,
+  toggleReverse,
+  flushSoundEvents,
+  getHistoryDelta,
+  getHistoryDeltas,
+  startBenchSequence,
+  startBench,
+  stopBench
+} from './E2EGameControls.js';
+const isE2EEnabled = () => {
+  if (typeof window === 'undefined') return false;
+  const params = new URLSearchParams(window.location.search);
+  return params.has(E2E_QUERY_KEY);
+};
+const normalizeBufferName = (name) => {
+  const raw = String(name || '').trim();
+  if (!raw) return '';
+  return raw
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/[\s_]+/g, '-')
+    .toLowerCase();
+};
+const toByteView = (array) => {
+  if (!array) return null;
+  return new Uint8Array(array.buffer, array.byteOffset, array.byteLength);
+};
+const encodeBase64 = (bytes) => {
+  if (!bytes || typeof btoa !== 'function') return null;
+  let binary = '';
+  for (let i = 0; i < bytes.length; i += BASE64_CHUNK) {
+    const chunk = bytes.subarray(i, i + BASE64_CHUNK);
+    binary += String.fromCharCode.apply(null, chunk);
+  }
+  return btoa(binary);
+};
+const packBuffer = (name, array, meta = {}) => {
+  if (!array) return null;
+  const bytes = toByteView(array);
+  if (!bytes) return null;
+  const dtype = DTYPE_MAP.get(array.constructor) || 'u8';
+  const data = encodeBase64(bytes);
+  if (!data) return null;
+  return {
+    name,
+    encoding: 'base64',
+    dtype,
+    byteLength: bytes.byteLength,
+    length: array.length,
+    ...meta,
+    data
+  };
+};
+const cloneEntry = (entry) => {
+  if (!entry) return null;
+  return {
+    uid: entry.uid ?? null,
+    props: entry.props ? { ...entry.props } : {},
+    order: Array.isArray(entry.order) ? entry.order.slice() : [],
+    unknownLines: Array.isArray(entry.unknownLines) ? entry.unknownLines.slice() : []
+  };
+};
+const cloneTerrainGroup = (group) => {
+  if (!group) return null;
+  return {
+    props: group.props ? { ...group.props } : {},
+    order: Array.isArray(group.order) ? group.order.slice() : [],
+    terrains: Array.isArray(group.terrains) ? group.terrains.map(cloneEntry) : [],
+    unknownLines: Array.isArray(group.unknownLines) ? group.unknownLines.slice() : []
+  };
+};
+const cloneUnknownSection = (section) => {
+  if (!section) return null;
+  return {
+    name: section.name ?? '',
+    lines: Array.isArray(section.lines) ? section.lines.slice() : []
+  };
+};
+const serializeEditorLevel = (level) => {
+  if (!level) return null;
+  const skillset = {};
+  if (level.skillset?.forEach) {
+    level.skillset.forEach((value, key) => {
+      skillset[key] = value;
+    });
+  }
+  return {
+    header: { ...(level.header || {}) },
+    headerOrder: Array.isArray(level.headerOrder) ? level.headerOrder.slice() : [],
+    skillset,
+    terrains: Array.isArray(level.terrains) ? level.terrains.map(cloneEntry) : [],
+    gadgets: Array.isArray(level.gadgets) ? level.gadgets.map(cloneEntry) : [],
+    steel: Array.isArray(level.steel) ? level.steel.map(cloneEntry) : [],
+    terrainGroups: Array.isArray(level.terrainGroups)
+      ? level.terrainGroups.map(cloneTerrainGroup)
+      : [],
+    unknownSections: Array.isArray(level.unknownSections)
+      ? level.unknownSections.map(cloneUnknownSection)
+      : [],
+    unknownLines: Array.isArray(level.unknownLines) ? level.unknownLines.slice() : []
+  };
+};
+const serializeSelectionEntry = (selected) => {
+  if (!selected) return null;
+  return {
+    type: selected.type,
+    index: selected.index,
+    uid: selected.entry?.uid ?? null,
+    entry: cloneEntry(selected.entry)
+  };
+};
+const serializeEditorController = (controller) => {
+  if (!controller) return null;
+  const selection = Array.isArray(controller.selection)
+    ? controller.selection.map(item => ({ type: item.type, index: item.index }))
+    : [];
+  const selectedEntries = controller.getSelectedEntries?.() || [];
+  const selectionEntries = selectedEntries.map(serializeSelectionEntry);
+  return {
+    tool: controller.tool,
+    gridSize: controller.gridSize,
+    snapEnabled: controller.snapEnabled !== false,
+    brushSize: controller.brushSize,
+    eraseGadgets: !!controller.eraseGadgets,
+    selectedTerrainId: controller.selectedTerrainId,
+    selectedGadgetId: controller.selectedGadgetId,
+    selectedTriggerId: controller.selectedTriggerId,
+    handleSize: controller.handleSize,
+    selection,
+    selectionEntries,
+    selectionBounds: controller.getSelectionBounds?.() || null,
+    marqueeBounds: controller.getMarqueeBounds?.() || null,
+    drag: controller._drag
+      ? {
+        label: controller._drag.label || null,
+        entries: Array.isArray(controller._drag.entries)
+          ? controller._drag.entries.map(entry => ({ ...entry }))
+          : []
+      }
+      : null,
+    resize: controller._resize ? { ...controller._resize } : null,
+    marquee: controller._marquee ? { ...controller._marquee } : null,
+    steelDraft: controller._steelDraft ? { ...controller._steelDraft } : null,
+    strokeChanged: !!controller._strokeChanged,
+    lastBrushPos: controller._lastBrushPos ? { ...controller._lastBrushPos } : null,
+    pasteOffset: controller._pasteOffset ?? 0,
+    pointerDown: !!controller._pointerDown,
+    pointerButton: controller._pointerButton ?? 0,
+    previewDelay: controller._previewDelay ?? 0,
+    clipboard: controller._clipboard
+      ? {
+        minX: controller._clipboard.minX,
+        minY: controller._clipboard.minY,
+        items: Array.isArray(controller._clipboard.items)
+          ? controller._clipboard.items.map(item => ({
+            type: item.type,
+            offsetX: item.offsetX,
+            offsetY: item.offsetY,
+            entry: cloneEntry(item.entry)
+          }))
+          : []
+      }
+      : null,
+    stampCount: controller._stampSet?.size ?? 0
+  };
+};
+const summarizeEditorHistory = (history) => {
+  if (!history) return null;
+  const entries = history.entries || [];
+  return {
+    cursor: history.cursor,
+    count: entries.length,
+    stats: typeof history.getStats === 'function' ? history.getStats() : null,
+    entries: entries.map(entry => ({
+      label: entry.label || '',
+      time: entry.time || 0,
+      bytes: entry.bytes || 0,
+      textLength: entry.text?.length || 0
+    }))
+  };
+};
+const getEditorHistoryEntry = (history, index) => {
+  if (!history || !Number.isFinite(index)) return null;
+  const entries = history.entries || [];
+  const idx = Math.trunc(index);
+  const entry = entries[idx];
+  if (!entry) return null;
+  return {
+    index: idx,
+    label: entry.label || '',
+    time: entry.time || 0,
+    text: entry.text || ''
+  };
+};
+const serializeIssues = (issues) => {
+  if (!Array.isArray(issues)) return { hasErrors: false, issues: [] };
+  const sanitized = issues.map(issue => ({
+    severity: issue.severity,
+    code: issue.code || null,
+    source: issue.source || null,
+    message: issue.message,
+    fixLabel: issue.fixLabel || null,
+    hasFix: typeof issue.fix === 'function',
+    solverAdvisory: issue.solverAdvisory === true,
+    advisoryCode: issue.advisoryCode || null,
+    blocking: issue.blocking === true,
+    blocksEditing: issue.blocksEditing === true,
+    blocksExport: issue.blocksExport === true
+  }));
+  const hasErrors = sanitized.some(issue => issue.severity === 'error');
+  return { hasErrors, issues: sanitized };
+};
+const serializeAssets = (assets) => {
+  if (!assets) return null;
+  return {
+    styleName: assets.styleName || null,
+    groundSet: assets.groundSet ?? 0,
+    entranceId: assets.entranceId ?? null,
+    exitId: assets.exitId ?? null,
+    terrain: Array.isArray(assets.terrain) ? assets.terrain.map(item => ({ ...item })) : [],
+    gadgets: Array.isArray(assets.gadgets) ? assets.gadgets.map(item => ({ ...item })) : [],
+    triggers: Array.isArray(assets.triggers) ? assets.triggers.map(item => ({ ...item })) : []
+  };
+};
+const getActionType = (manager, action) => {
+  if (!manager || !action) return null;
+  if (manager.actionTypeByAction?.has(action)) {
+    return manager.actionTypeByAction.get(action);
+  }
+  return action.actionType ?? null;
+};
+const serializeLemming = (manager, lem) => {
+  if (!lem) return null;
+  return {
+    id: lem.id,
+    x: lem.x,
+    y: lem.y,
+    lookRight: !!lem.lookRight,
+    frameIndex: lem.frameIndex,
+    state: lem.state ?? null,
+    actionType: getActionType(manager, lem.action),
+    canClimb: !!lem.canClimb,
+    hasParachute: !!lem.hasParachute,
+    removed: !!lem.removed,
+    disabled: !!lem.disabled,
+    countdown: lem.countdown ?? 0,
+    countdownActive: !!lem.countdownAction,
+    hasExploded: !!lem.hasExploded,
+    lastTriggerType: Number.isFinite(lem.lastTriggerType) ? lem.lastTriggerType : null
+  };
+};
+const serializeTrigger = (trigger, observer = false) => {
+  if (!trigger) return null;
+  return {
+    id: trigger.__historyId ?? null,
+    observer: !!observer,
+    type: trigger.type,
+    x1: trigger.x1,
+    y1: trigger.y1,
+    x2: trigger.x2,
+    y2: trigger.y2,
+    disableTicksCount: trigger.disableTicksCount,
+    disabledUntilTick: trigger.disabledUntilTick,
+    soundIndex: trigger.soundIndex,
+    ownerId: trigger.owner?.id ?? null,
+    ownerKind: trigger.owner?.__historyKind ?? trigger.owner?.historyKind ?? null,
+    ownerData: trigger.owner?.__historyData ? { ...trigger.owner.__historyData } : null
+  };
+};
+const serializeMapObject = (obj) => {
+  if (!obj) return null;
+  return {
+    id: obj.obID ?? obj.ob?.id ?? null,
+    x: obj.x,
+    y: obj.y,
+    triggerType: obj.triggerType,
+    animation: obj.animation
+      ? {
+        firstFrameIndex: obj.animation.firstFrameIndex,
+        isFinished: !!obj.animation.isFinished,
+        loop: !!obj.animation.loop,
+        frameCount: obj.animation.frames?.length ?? 0
+      }
+      : null
+  };
+};
+
+const serializeSteelRanges = (ranges) => {
+  if (!ranges || typeof ranges.length !== 'number') return [];
+  const entries = [];
+  for (let i = 0; i + 3 < ranges.length; i += 4) {
+    entries.push({
+      x: ranges[i],
+      y: ranges[i + 1],
+      width: ranges[i + 2],
+      height: ranges[i + 3]
+    });
+  }
+  return entries;
+};
+
+const isGameReady = (view) => {
+  const game = view?.game;
+  const stage = view?.stage;
+  if (!game || !stage || !game.level) return false;
+  const timer = game.getGameTimer?.();
+  if (!timer || typeof timer.tick !== 'function') return false;
+  const viewRect = stage.getGameViewRect?.() || null;
+  if (!viewRect || viewRect.w <= 0 || viewRect.h <= 0) return false;
+  return true;
+};
+const getViewState = (view) => {
+  if (!view) return null;
+  return {
+    gameType: view.gameType,
+    levelGroupIndex: view.levelGroupIndex,
+    levelIndex: view.levelIndex,
+    gameSpeedFactor: view.gameSpeedFactor,
+    scale: view.scale,
+    bench: !!view.bench,
+    bench2: !!view.bench2,
+    benchReverse: !!view.benchReverse,
+    benchSequence: !!view.benchSequence,
+    endless: !!view.endless,
+    extraLemmings: view.extraLemmings,
+    preserveHistory: !!view.preserveHistory,
+    cheatEnabled: !!view.cheatEnabled,
+    debug: !!view.debug,
+    performanceAPI: !!view.performanceAPI,
+    perfMetrics: !!view.perfMetrics,
+    includeSavedLevels: !!view.includeSavedLevels,
+    editorMode: !!view.editorMode,
+    editorPlaytest: !!view.editorPlaytest,
+    midiEnabled: !!view.midiEnabled,
+    configName: view.gameResources?.config?.name ?? null,
+    configPath: view.gameResources?.config?.path ?? null
+  };
+};
+const resolveProcgenController = (source) => {
+  if (!source) return null;
+  if (typeof source.getDebugState === 'function') return source;
+  return source.procgenController || source.procgen?.controller || null;
+};
+const getProcgenState = (source) => {
+  const controller = resolveProcgenController(source);
+  if (!controller || typeof controller.getDebugState !== 'function') return null;
+  return controller.getDebugState();
+};
+const getGameState = (view) => {
+  const game = view?.game;
+  if (!game) return null;
+  const timer = game.getGameTimer?.() || null;
+  const manager = game.getLemmingManager?.() || null;
+  const victory = game.getVictoryCondition?.() || null;
+  const skills = game.getGameSkills?.() || null;
+  const commandManager = game.getCommandManager?.() || null;
+  const history = game.history || null;
+  const timeTravel = game.timeTravel || null;
+  const level = game.level || null;
+  const triggerManager = game.triggerManager || null;
+  const soundEvents = game.soundEvents || null;
+  const bench = getBenchMetrics(view);
+
+  const lemmings = Array.isArray(manager?.lemmings)
+    ? manager.lemmings.map(lem => serializeLemming(manager, lem))
+    : [];
+  const activeCount = manager?.activeLemmings?.length ?? 0;
+  const nukeTargets = Array.isArray(manager?._nukeTargets)
+    ? manager._nukeTargets.map(lem => lem?.id).filter(id => Number.isFinite(id))
+    : [];
+
+  const triggers = [];
+  if (triggerManager?._triggers) {
+    triggers.push(...Array.from(triggerManager._triggers).map(trigger => serializeTrigger(trigger, false)));
+  }
+  if (triggerManager?._observerTriggers) {
+    triggers.push(...Array.from(triggerManager._observerTriggers).map(trigger => serializeTrigger(trigger, true)));
+  }
+  const dynamicCount = triggers.filter(trigger => trigger && trigger.ownerId != null).length;
+
+  const objects = Array.isArray(level?.objects)
+    ? level.objects.map(serializeMapObject)
+    : [];
+  const steel = serializeSteelRanges(level?.steelRanges);
+
+  const minimap = manager?.miniMap
+    ? {
+      width: manager.miniMap.width,
+      height: manager.miniMap.height,
+      scaleX: manager.miniMap.scaleX,
+      scaleY: manager.miniMap.scaleY,
+      liveDotCount: Number.isFinite(manager.miniMap.liveDotsLength)
+        ? manager.miniMap.liveDotsLength / 2
+        : (manager.miniMap.liveDots?.length ? manager.miniMap.liveDots.length / 2 : 0),
+      deadCount: manager.miniMap.deadCount ?? 0,
+      selectedDot: manager.miniMap.selectedDot || null
+    }
+    : null;
+
+  return {
+    ready: isGameReady(view),
+    finalGameState: game.finalGameState ?? null,
+    inputEnabled: game.inputEnabled !== false,
+    state: game.getGameState?.() ?? null,
+    timer: timer
+      ? {
+        tickIndex: timer.tickIndex,
+        speedFactor: timer.speedFactor,
+        frameTime: timer.frameTime,
+        tps: timer.tps,
+        running: timer.isRunning?.() ?? false
+      }
+      : null,
+    history: history?.getHistoryStats?.() ?? null,
+    timeTravel: timeTravel
+      ? {
+        isReversing: !!timeTravel.isReversing,
+        playbackDirection: timeTravel.playbackDirection
+      }
+      : null,
+    victory: victory
+      ? {
+        releaseRate: victory.releaseRate,
+        minReleaseRate: victory.minReleaseRate,
+        leftCount: victory.leftCount,
+        outCount: victory.outCount,
+        survivorCount: victory.survivorCount,
+        isFinalize: !!victory.isFinalize
+      }
+      : null,
+    skills: skills
+      ? {
+        selectedSkill: skills.selectedSkill,
+        cheatMode: !!skills.cheatMode,
+        skills: Array.isArray(skills.skills)
+          ? skills.skills.map((_, idx) =>
+            typeof skills.getSkill === 'function' ? skills.getSkill(idx) : skills.skills[idx]
+          )
+          : []
+      }
+      : null,
+    commandManager: commandManager
+      ? {
+        scheduledCount: Object.keys(commandManager.runCommands || {}).length,
+        loggedCount: Object.keys(commandManager.loggedCommads || {}).length
+      }
+      : null,
+    lemmingManager: manager
+      ? {
+        selectedIndex: manager.selectedIndex,
+        spawnTotal: manager.spawnTotal,
+        releaseTickIndex: manager.releaseTickIndex,
+        mmTickCounter: manager.mmTickCounter,
+        activeCount,
+        totalCount: manager.lemmings?.length ?? 0,
+        nukeTargets
+      }
+      : null,
+    lemmings,
+    level: level
+      ? {
+        name: level.name,
+        width: level.width,
+        height: level.height,
+        screenPositionX: level.screenPositionX,
+        releaseRate: level.releaseRate,
+        releaseCount: level.releaseCount,
+        needCount: level.needCount,
+        timeLimit: level.timeLimit,
+        isSuperLemming: !!level.isSuperLemming,
+        entrances: Array.isArray(level.entrances)
+          ? level.entrances.map((entrance, index) => ({
+            index,
+            x: entrance.x,
+            y: entrance.y,
+            opened: !!entrance._opened
+          }))
+          : [],
+        triggerCount: level.triggers?.length ?? 0,
+        objectCount: level.objects?.length ?? 0
+      }
+      : null,
+    triggers: {
+      totalCount: triggers.length,
+      dynamicCount,
+      entries: triggers
+    },
+    objects: {
+      count: objects.length,
+      entries: objects
+    },
+    steel: {
+      count: steel.length,
+      entries: steel
+    },
+    minimap,
+    bench,
+    soundEvents: soundEvents
+      ? {
+        queuedCount: soundEvents._queue?.length ?? 0,
+        sequence: soundEvents._sequence ?? 0,
+        queueLimit: soundEvents._queueLimit ?? 0
+      }
+      : null
+  };
+};
+export {
+  isE2EEnabled,
+  normalizeBufferName,
+  toByteView,
+  encodeBase64,
+  packBuffer,
+  cloneEntry,
+  cloneTerrainGroup,
+  cloneUnknownSection,
+  serializeEditorLevel,
+  serializeSelectionEntry,
+  serializeEditorController,
+  summarizeEditorHistory,
+  getEditorHistoryEntry,
+  serializeIssues,
+  serializeAssets,
+  getActionType,
+  serializeLemming,
+  serializeTrigger,
+  serializeMapObject,
+  serializeSteelRanges,
+  isGameReady,
+  getViewState,
+  getProcgenState,
+  getGameState
+};
diff --git a/js/app/e2e/e2eShared.js b/js/app/e2e/e2eShared.js
new file mode 100644
index 00000000..8ea75387
--- /dev/null
+++ b/js/app/e2e/e2eShared.js
@@ -0,0 +1,58 @@
+import { listSavedLevels, loadSavedLevel, saveLevel } from '../../editor/EditorStorage.js';
+import {
+  createTerrainEntry,
+  createGadgetEntry,
+  createSteelEntry,
+  ensureEntryUid,
+  ensureLevelEntryUids,
+  setEntryProp,
+  removeEntryAt
+} from '../../editor/EditorEntryFactory.js';
+import { createClassicLevelData } from '../../editor/EditorLevelLoader.js';
+import { createEditorLevelFromClassic } from '../../editor/ClassicLevelConverter.js';
+import { EditorTools } from '../../editor/EditorTools.js';
+import { findEntryAt, getEntryBounds } from '../../editor/EditorHitTest.js';
+import { BinaryReader } from '../../data/BinaryReader.js';
+import { LevelReader } from '../../level/LevelReader.js';
+import { LevelWriter } from '../../level/LevelWriter.js';
+import { validateLevel } from '../../editor/EditorValidator.js';
+import { getRuntimeDependency } from '../../core/dependencies.js';
+const E2E_QUERY_KEY = 'e2e';
+const BASE64_CHUNK = 0x8000;
+const DTYPE_MAP = new Map([
+  [Uint8Array, 'u8'],
+  [Uint8ClampedArray, 'u8c'],
+  [Uint16Array, 'u16'],
+  [Uint32Array, 'u32'],
+  [Int8Array, 'i8'],
+  [Int16Array, 'i16'],
+  [Int32Array, 'i32'],
+  [Float32Array, 'f32'],
+  [Float64Array, 'f64']
+]);
+
+export {
+  BASE64_CHUNK,
+  BinaryReader,
+  DTYPE_MAP,
+  E2E_QUERY_KEY,
+  EditorTools,
+  LevelReader,
+  LevelWriter,
+  createClassicLevelData,
+  createEditorLevelFromClassic,
+  createGadgetEntry,
+  createSteelEntry,
+  createTerrainEntry,
+  ensureEntryUid,
+  ensureLevelEntryUids,
+  findEntryAt,
+  getEntryBounds,
+  getRuntimeDependency,
+  listSavedLevels,
+  loadSavedLevel,
+  removeEntryAt,
+  saveLevel,
+  setEntryProp,
+  validateLevel
+};
diff --git a/js/app/e2eHarness.js b/js/app/e2eHarness.js
index 7e98cd4b..0a6388b7 100644
--- a/js/app/e2eHarness.js
+++ b/js/app/e2eHarness.js
@@ -1,1690 +1,89 @@
-import { listSavedLevels, loadSavedLevel, saveLevel } from '../editor/EditorStorage.js';
 import {
-  createTerrainEntry,
-  createGadgetEntry,
-  createSteelEntry,
-  ensureEntryUid,
-  ensureLevelEntryUids,
-  setEntryProp,
-  removeEntryAt
-} from '../editor/EditorEntryFactory.js';
-import { createClassicLevelData } from '../editor/EditorLevelLoader.js';
-import { createEditorLevelFromClassic } from '../editor/ClassicLevelConverter.js';
-import { EditorTools } from '../editor/EditorTools.js';
-import { findEntryAt, getEntryBounds } from '../editor/EditorHitTest.js';
-import { BinaryReader } from '../data/BinaryReader.js';
-import { LevelReader } from '../level/LevelReader.js';
-import { LevelWriter } from '../level/LevelWriter.js';
-import { validateLevel } from '../editor/EditorValidator.js';
-
-const E2E_QUERY_KEY = 'e2e';
-const BASE64_CHUNK = 0x8000;
-const DTYPE_MAP = new Map([
-  [Uint8Array, 'u8'],
-  [Uint8ClampedArray, 'u8c'],
-  [Uint16Array, 'u16'],
-  [Uint32Array, 'u32'],
-  [Int8Array, 'i8'],
-  [Int16Array, 'i16'],
-  [Int32Array, 'i32'],
-  [Float32Array, 'f32'],
-  [Float64Array, 'f64']
-]);
-
-const isE2EEnabled = () => {
-  if (typeof window === 'undefined') return false;
-  const params = new URLSearchParams(window.location.search);
-  return params.has(E2E_QUERY_KEY);
-};
-
-const normalizeBufferName = (name) => {
-  const raw = String(name || '').trim();
-  if (!raw) return '';
-  return raw
-    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
-    .replace(/[\s_]+/g, '-')
-    .toLowerCase();
-};
-
-const toByteView = (array) => {
-  if (!array) return null;
-  return new Uint8Array(array.buffer, array.byteOffset, array.byteLength);
-};
-
-const encodeBase64 = (bytes) => {
-  if (!bytes || typeof btoa !== 'function') return null;
-  let binary = '';
-  for (let i = 0; i < bytes.length; i += BASE64_CHUNK) {
-    const chunk = bytes.subarray(i, i + BASE64_CHUNK);
-    binary += String.fromCharCode.apply(null, chunk);
-  }
-  return btoa(binary);
-};
-
-const packBuffer = (name, array, meta = {}) => {
-  if (!array) return null;
-  const bytes = toByteView(array);
-  if (!bytes) return null;
-  const dtype = DTYPE_MAP.get(array.constructor) || 'u8';
-  const data = encodeBase64(bytes);
-  if (!data) return null;
-  return {
-    name,
-    encoding: 'base64',
-    dtype,
-    byteLength: bytes.byteLength,
-    length: array.length,
-    ...meta,
-    data
-  };
-};
-
-const cloneEntry = (entry) => {
-  if (!entry) return null;
-  return {
-    uid: entry.uid ?? null,
-    props: entry.props ? { ...entry.props } : {},
-    order: Array.isArray(entry.order) ? entry.order.slice() : [],
-    unknownLines: Array.isArray(entry.unknownLines) ? entry.unknownLines.slice() : []
-  };
-};
-
-const cloneTerrainGroup = (group) => {
-  if (!group) return null;
-  return {
-    props: group.props ? { ...group.props } : {},
-    order: Array.isArray(group.order) ? group.order.slice() : [],
-    terrains: Array.isArray(group.terrains) ? group.terrains.map(cloneEntry) : [],
-    unknownLines: Array.isArray(group.unknownLines) ? group.unknownLines.slice() : []
-  };
-};
-
-const cloneUnknownSection = (section) => {
-  if (!section) return null;
-  return {
-    name: section.name ?? '',
-    lines: Array.isArray(section.lines) ? section.lines.slice() : []
-  };
-};
-
-const serializeEditorLevel = (level) => {
-  if (!level) return null;
-  const skillset = {};
-  if (level.skillset?.forEach) {
-    level.skillset.forEach((value, key) => {
-      skillset[key] = value;
-    });
-  }
-  return {
-    header: { ...(level.header || {}) },
-    headerOrder: Array.isArray(level.headerOrder) ? level.headerOrder.slice() : [],
-    skillset,
-    terrains: Array.isArray(level.terrains) ? level.terrains.map(cloneEntry) : [],
-    gadgets: Array.isArray(level.gadgets) ? level.gadgets.map(cloneEntry) : [],
-    steel: Array.isArray(level.steel) ? level.steel.map(cloneEntry) : [],
-    terrainGroups: Array.isArray(level.terrainGroups)
-      ? level.terrainGroups.map(cloneTerrainGroup)
-      : [],
-    unknownSections: Array.isArray(level.unknownSections)
-      ? level.unknownSections.map(cloneUnknownSection)
-      : [],
-    unknownLines: Array.isArray(level.unknownLines) ? level.unknownLines.slice() : []
-  };
-};
-
-const serializeSelectionEntry = (selected) => {
-  if (!selected) return null;
-  return {
-    type: selected.type,
-    index: selected.index,
-    uid: selected.entry?.uid ?? null,
-    entry: cloneEntry(selected.entry)
-  };
-};
-
-const serializeEditorController = (controller) => {
-  if (!controller) return null;
-  const selection = Array.isArray(controller.selection)
-    ? controller.selection.map(item => ({ type: item.type, index: item.index }))
-    : [];
-  const selectedEntries = controller.getSelectedEntries?.() || [];
-  const selectionEntries = selectedEntries.map(serializeSelectionEntry);
-  return {
-    tool: controller.tool,
-    gridSize: controller.gridSize,
-    snapEnabled: controller.snapEnabled !== false,
-    brushSize: controller.brushSize,
-    eraseGadgets: !!controller.eraseGadgets,
-    selectedTerrainId: controller.selectedTerrainId,
-    selectedGadgetId: controller.selectedGadgetId,
-    selectedTriggerId: controller.selectedTriggerId,
-    handleSize: controller.handleSize,
-    selection,
-    selectionEntries,
-    selectionBounds: controller.getSelectionBounds?.() || null,
-    marqueeBounds: controller.getMarqueeBounds?.() || null,
-    drag: controller._drag
-      ? {
-        label: controller._drag.label || null,
-        entries: Array.isArray(controller._drag.entries)
-          ? controller._drag.entries.map(entry => ({ ...entry }))
-          : []
-      }
-      : null,
-    resize: controller._resize ? { ...controller._resize } : null,
-    marquee: controller._marquee ? { ...controller._marquee } : null,
-    steelDraft: controller._steelDraft ? { ...controller._steelDraft } : null,
-    strokeChanged: !!controller._strokeChanged,
-    lastBrushPos: controller._lastBrushPos ? { ...controller._lastBrushPos } : null,
-    pasteOffset: controller._pasteOffset ?? 0,
-    pointerDown: !!controller._pointerDown,
-    pointerButton: controller._pointerButton ?? 0,
-    previewDelay: controller._previewDelay ?? 0,
-    clipboard: controller._clipboard
-      ? {
-        minX: controller._clipboard.minX,
-        minY: controller._clipboard.minY,
-        items: Array.isArray(controller._clipboard.items)
-          ? controller._clipboard.items.map(item => ({
-            type: item.type,
-            offsetX: item.offsetX,
-            offsetY: item.offsetY,
-            entry: cloneEntry(item.entry)
-          }))
-          : []
-      }
-      : null,
-    stampCount: controller._stampSet?.size ?? 0
-  };
-};
-
-const summarizeEditorHistory = (history) => {
-  if (!history) return null;
-  const entries = history.entries || [];
-  return {
-    cursor: history.cursor,
-    count: entries.length,
-    entries: entries.map(entry => ({
-      label: entry.label || '',
-      time: entry.time || 0,
-      textLength: entry.text?.length || 0
-    }))
-  };
-};
-
-const getEditorHistoryEntry = (history, index) => {
-  if (!history || !Number.isFinite(index)) return null;
-  const entries = history.entries || [];
-  const idx = Math.trunc(index);
-  const entry = entries[idx];
-  if (!entry) return null;
-  return {
-    index: idx,
-    label: entry.label || '',
-    time: entry.time || 0,
-    text: entry.text || ''
-  };
-};
-
-const serializeIssues = (issues) => {
-  if (!Array.isArray(issues)) return { hasErrors: false, issues: [] };
-  const sanitized = issues.map(issue => ({
-    severity: issue.severity,
-    message: issue.message,
-    fixLabel: issue.fixLabel || null,
-    hasFix: typeof issue.fix === 'function'
-  }));
-  const hasErrors = sanitized.some(issue => issue.severity === 'error');
-  return { hasErrors, issues: sanitized };
-};
-
-const serializeAssets = (assets) => {
-  if (!assets) return null;
-  return {
-    styleName: assets.styleName || null,
-    groundSet: assets.groundSet ?? 0,
-    entranceId: assets.entranceId ?? null,
-    exitId: assets.exitId ?? null,
-    terrain: Array.isArray(assets.terrain) ? assets.terrain.map(item => ({ ...item })) : [],
-    gadgets: Array.isArray(assets.gadgets) ? assets.gadgets.map(item => ({ ...item })) : [],
-    triggers: Array.isArray(assets.triggers) ? assets.triggers.map(item => ({ ...item })) : []
-  };
-};
-
-const getActionType = (manager, action) => {
-  if (!manager || !action) return null;
-  if (manager.actionTypeByAction?.has(action)) {
-    return manager.actionTypeByAction.get(action);
-  }
-  return action.actionType ?? null;
-};
-
-const serializeLemming = (manager, lem) => {
-  if (!lem) return null;
-  return {
-    id: lem.id,
-    x: lem.x,
-    y: lem.y,
-    lookRight: !!lem.lookRight,
-    frameIndex: lem.frameIndex,
-    state: lem.state ?? null,
-    actionType: getActionType(manager, lem.action),
-    canClimb: !!lem.canClimb,
-    hasParachute: !!lem.hasParachute,
-    removed: !!lem.removed,
-    disabled: !!lem.disabled,
-    countdown: lem.countdown ?? 0,
-    countdownActive: !!lem.countdownAction,
-    hasExploded: !!lem.hasExploded,
-    lastTriggerType: Number.isFinite(lem.lastTriggerType) ? lem.lastTriggerType : null
-  };
-};
-
-const serializeTrigger = (trigger) => {
-  if (!trigger) return null;
-  return {
-    id: trigger.__historyId ?? null,
-    type: trigger.type,
-    x1: trigger.x1,
-    y1: trigger.y1,
-    x2: trigger.x2,
-    y2: trigger.y2,
-    disableTicksCount: trigger.disableTicksCount,
-    disabledUntilTick: trigger.disabledUntilTick,
-    soundIndex: trigger.soundIndex,
-    ownerId: trigger.owner?.id ?? null
-  };
-};
-
-const serializeMapObject = (obj) => {
-  if (!obj) return null;
-  return {
-    id: obj.obID ?? obj.ob?.id ?? null,
-    x: obj.x,
-    y: obj.y,
-    triggerType: obj.triggerType,
-    animation: obj.animation
-      ? {
-        firstFrameIndex: obj.animation.firstFrameIndex,
-        isFinished: !!obj.animation.isFinished,
-        loop: !!obj.animation.loop,
-        frameCount: obj.animation.frames?.length ?? 0
-      }
-      : null
-  };
-};
-
-const isGameReady = (view) => {
-  const game = view?.game;
-  const stage = view?.stage;
-  if (!game || !stage || !game.level) return false;
-  const timer = game.getGameTimer?.();
-  if (!timer || typeof timer.tick !== 'function') return false;
-  const viewRect = stage.getGameViewRect?.() || null;
-  if (!viewRect || viewRect.w <= 0 || viewRect.h <= 0) return false;
-  return true;
-};
-
-const getViewState = (view) => {
-  if (!view) return null;
-  return {
-    gameType: view.gameType,
-    levelGroupIndex: view.levelGroupIndex,
-    levelIndex: view.levelIndex,
-    gameSpeedFactor: view.gameSpeedFactor,
-    scale: view.scale,
-    bench: !!view.bench,
-    bench2: !!view.bench2,
-    benchReverse: !!view.benchReverse,
-    benchSequence: !!view.benchSequence,
-    endless: !!view.endless,
-    extraLemmings: view.extraLemmings,
-    preserveHistory: !!view.preserveHistory,
-    cheatEnabled: !!view.cheatEnabled,
-    debug: !!view.debug,
-    performanceAPI: !!view.performanceAPI,
-    perfMetrics: !!view.perfMetrics,
-    includeSavedLevels: !!view.includeSavedLevels,
-    editorMode: !!view.editorMode,
-    editorPlaytest: !!view.editorPlaytest,
-    midiEnabled: !!view.midiEnabled,
-    configName: view.gameResources?.config?.name ?? null,
-    configPath: view.gameResources?.config?.path ?? null
-  };
-};
-
-const getBenchMetrics = (view) => {
-  if (!view) return null;
-  const timer = view.game?.getGameTimer?.() || null;
-  const active = !!(view.bench || view.bench2 || view.benchReverse || view.benchSequence);
-  const mode = view.benchReverse
-    ? 'reverse'
-    : view.benchSequence
-      ? 'sequence'
-      : view.bench2
-        ? 'catchup'
-        : view.bench
-          ? 'bench'
-          : null;
-  return {
-    active,
-    mode,
-    steps: view.steps ?? 0,
-    tps: view.tps ?? timer?.tps ?? null,
-    speedFactor: timer?.speedFactor ?? null,
-    benchMaxSpeed: view._benchMaxSpeed ?? null,
-    benchIndex: view._benchIndex ?? null,
-    benchCounts: Array.isArray(view._benchCounts) ? view._benchCounts.slice() : [],
-    benchExtraList: Array.isArray(view._benchExtraList) ? view._benchExtraList.slice() : [],
-    benchExtraIndex: view._benchExtraIndex ?? null,
-    benchStartTime: view._benchStartTime ?? null,
-    benchMeasureExtras: !!view._benchMeasureExtras,
-    benchStartupFrames: timer?.benchStartupFrames ?? 0,
-    benchStableFactor: timer?.benchStableFactor ?? 1
-  };
-};
-
-const getStageState = (stage) => {
-  if (!stage) return null;
-  const viewRect = stage.getGameViewRect?.() || null;
-  return {
-    panEnabled: stage.panEnabled !== false,
-    cursor: { x: stage.cursorX, y: stage.cursorY },
-    viewRect: viewRect ? { ...viewRect } : null,
-    gameScale: stage.gameImgProps?.viewPoint?.scale ?? null,
-    guiScale: stage.guiImgProps?.viewPoint?.scale ?? null,
-    rawScale: stage._rawScale ?? null,
-    gamePosition: {
-      x: stage.gameImgProps?.x ?? null,
-      y: stage.gameImgProps?.y ?? null
-    },
-    guiPosition: {
-      x: stage.guiImgProps?.x ?? null,
-      y: stage.guiImgProps?.y ?? null
-    }
-  };
-};
-
-const getGameState = (view) => {
-  const game = view?.game;
-  if (!game) return null;
-  const timer = game.getGameTimer?.() || null;
-  const manager = game.getLemmingManager?.() || null;
-  const victory = game.getVictoryCondition?.() || null;
-  const skills = game.getGameSkills?.() || null;
-  const commandManager = game.getCommandManager?.() || null;
-  const history = game.history || null;
-  const timeTravel = game.timeTravel || null;
-  const level = game.level || null;
-  const triggerManager = game.triggerManager || null;
-  const soundEvents = game.soundEvents || null;
-  const bench = getBenchMetrics(view);
-
-  const lemmings = Array.isArray(manager?.lemmings)
-    ? manager.lemmings.map(lem => serializeLemming(manager, lem))
-    : [];
-  const activeCount = manager?.activeLemmings?.length ?? 0;
-  const nukeTargets = Array.isArray(manager?._nukeTargets)
-    ? manager._nukeTargets.map(lem => lem?.id).filter(id => Number.isFinite(id))
-    : [];
-
-  const triggers = triggerManager?._triggers
-    ? Array.from(triggerManager._triggers).map(serializeTrigger)
-    : [];
-  const dynamicCount = triggers.filter(trigger => trigger && trigger.ownerId != null).length;
-
-  const objects = Array.isArray(level?.objects)
-    ? level.objects.map(serializeMapObject)
-    : [];
-
-  const minimap = manager?.miniMap
-    ? {
-      width: manager.miniMap.width,
-      height: manager.miniMap.height,
-      scaleX: manager.miniMap.scaleX,
-      scaleY: manager.miniMap.scaleY,
-      liveDotCount: manager.miniMap.liveDots?.length
-        ? manager.miniMap.liveDots.length / 2
-        : 0,
-      deadCount: manager.miniMap.deadCount ?? 0,
-      selectedDot: manager.miniMap.selectedDot || null
-    }
-    : null;
-
-  return {
-    ready: isGameReady(view),
-    finalGameState: game.finalGameState ?? null,
-    state: game.getGameState?.() ?? null,
-    timer: timer
-      ? {
-        tickIndex: timer.tickIndex,
-        speedFactor: timer.speedFactor,
-        frameTime: timer.frameTime,
-        tps: timer.tps,
-        running: timer.isRunning?.() ?? false
-      }
-      : null,
-    history: history?.getHistoryStats?.() ?? null,
-    timeTravel: timeTravel
-      ? {
-        isReversing: !!timeTravel.isReversing,
-        playbackDirection: timeTravel.playbackDirection
-      }
-      : null,
-    victory: victory
-      ? {
-        releaseRate: victory.releaseRate,
-        minReleaseRate: victory.minReleaseRate,
-        leftCount: victory.leftCount,
-        outCount: victory.outCount,
-        survivorCount: victory.survivorCount,
-        isFinalize: !!victory.isFinalize
-      }
-      : null,
-    skills: skills
-      ? {
-        selectedSkill: skills.selectedSkill,
-        cheatMode: !!skills.cheatMode,
-        skills: Array.isArray(skills.skills)
-          ? skills.skills.map((_, idx) =>
-            typeof skills.getSkill === 'function' ? skills.getSkill(idx) : skills.skills[idx]
-          )
-          : []
-      }
-      : null,
-    commandManager: commandManager
-      ? {
-        scheduledCount: Object.keys(commandManager.runCommands || {}).length,
-        loggedCount: Object.keys(commandManager.loggedCommads || {}).length
-      }
-      : null,
-    lemmingManager: manager
-      ? {
-        selectedIndex: manager.selectedIndex,
-        spawnTotal: manager.spawnTotal,
-        releaseTickIndex: manager.releaseTickIndex,
-        mmTickCounter: manager.mmTickCounter,
-        activeCount,
-        totalCount: manager.lemmings?.length ?? 0,
-        nukeTargets
-      }
-      : null,
-    lemmings,
-    level: level
-      ? {
-        name: level.name,
-        width: level.width,
-        height: level.height,
-        screenPositionX: level.screenPositionX,
-        releaseRate: level.releaseRate,
-        releaseCount: level.releaseCount,
-        needCount: level.needCount,
-        timeLimit: level.timeLimit,
-        isSuperLemming: !!level.isSuperLemming,
-        entrances: Array.isArray(level.entrances)
-          ? level.entrances.map((entrance, index) => ({
-            index,
-            x: entrance.x,
-            y: entrance.y,
-            opened: !!entrance._opened
-          }))
-          : [],
-        triggerCount: level.triggers?.length ?? 0,
-        objectCount: level.objects?.length ?? 0
-      }
-      : null,
-    triggers: {
-      totalCount: triggers.length,
-      dynamicCount,
-      entries: triggers
-    },
-    objects: {
-      count: objects.length,
-      entries: objects
-    },
-    minimap,
-    bench,
-    soundEvents: soundEvents
-      ? {
-        queuedCount: soundEvents._queue?.length ?? 0,
-        sequence: soundEvents._sequence ?? 0,
-        queueLimit: soundEvents._queueLimit ?? 0
-      }
-      : null
-  };
-};
-
-const getEditorState = (view, editorUi) => {
-  const session = editorUi?.session || view?.editorSession || null;
-  const controller = editorUi?.controller || null;
-  const history = editorUi?.history || null;
-  const level = session?.level || null;
-  const issues = serializeIssues(validateLevel(level, editorUi?.assets || null));
-  return {
-    mode: !!view?.editorMode,
-    playtest: !!view?.editorPlaytest,
-    session: session
-      ? {
-        title: session.getTitle?.() || null,
-        level: serializeEditorLevel(level)
-      }
-      : null,
-    controller: serializeEditorController(controller),
-    history: summarizeEditorHistory(history),
-    ui: editorUi
-      ? {
-        activeTab: editorUi._activeTab,
-        currentSavedId: editorUi._currentSavedId,
-        playtest: !!editorUi._playtest,
-        previewInFlight: !!editorUi._previewInFlight,
-        previewQueued: !!editorUi._previewQueued,
-        cursorPos: editorUi._cursorPos ? { ...editorUi._cursorPos } : null,
-        pointerDown: !!editorUi._pointerDown,
-        shiftKey: !!editorUi._shiftKey,
-        altKey: !!editorUi._altKey,
-        antsOffset: editorUi._antsOffset ?? 0,
-        selectionCount: editorUi._selection?.length ?? 0,
-        suppressHeader: !!editorUi._suppressHeader,
-        suppressInspector: !!editorUi._suppressInspector,
-        paletteSearch: editorUi.el?.paletteSearch?.value ?? ''
-      }
-      : null,
-    assets: serializeAssets(editorUi?.assets || null),
-    validation: issues,
-    savedLevels: listSavedLevels()
-  };
-};
-
-const getEditorContext = (view, editorUi) => {
-  if (!editorUi) return null;
-  const session = editorUi.session || view?.editorSession || null;
-  const controller = editorUi.controller || null;
-  const history = editorUi.history || null;
-  if (!session || !session.level || !controller || !history) return null;
-  return {
-    session,
-    controller,
-    history,
-    assets: editorUi.assets || null,
-    editorUi
-  };
-};
-
-const getListForKind = (level, kind) => {
-  if (!level) return null;
-  if (kind === 'gadget') return level.gadgets;
-  if (kind === 'steel') return level.steel;
-  if (kind === 'terrain') return level.terrains;
-  return null;
-};
-
-const getPrefixForKind = (kind) => {
-  if (kind === 'gadget') return 'g';
-  if (kind === 'steel') return 's';
-  return 't';
-};
-
-const resolveEntryRef = (level, ref) => {
-  if (!ref || !level) return null;
-  const kind = ref.kind || ref.type;
-  const list = getListForKind(level, kind);
-  if (!Array.isArray(list)) return null;
-  let index = Number.isFinite(ref.index) ? Math.trunc(ref.index) : null;
-  if (!Number.isFinite(index) && ref.uid) {
-    index = list.findIndex(entry => entry?.uid === ref.uid);
-  }
-  if (!Number.isFinite(index) || index < 0 || index >= list.length) return null;
-  return { kind, list, index, entry: list[index] };
-};
-
-const cloneEntryForApply = (entry, prefix) => {
-  const props = entry?.props ? { ...entry.props } : {};
-  const order = Array.isArray(entry?.order) ? entry.order.slice() : Object.keys(props);
-  const unknownLines = Array.isArray(entry?.unknownLines) ? entry.unknownLines.slice() : [];
-  const clone = { props, order, unknownLines };
-  ensureEntryUid(clone, prefix);
-  return clone;
-};
-
-const normalizeBounds = (x1, y1, x2, y2) => {
-  const left = Math.min(x1, x2);
-  const right = Math.max(x1, x2);
-  const top = Math.min(y1, y2);
-  const bottom = Math.max(y1, y2);
-  return {
-    x: left,
-    y: top,
-    width: Math.max(1, right - left),
-    height: Math.max(1, bottom - top)
-  };
-};
-
-const boundsIntersect = (a, b) => {
-  if (!a || !b) return false;
-  return a.x <= b.x + b.width
-    && a.x + a.width >= b.x
-    && a.y <= b.y + b.height
-    && a.y + a.height >= b.y;
-};
-
-const applyEditorOps = async (view, editorUi, ops = [], options = {}) => {
-  const ctx = getEditorContext(view, editorUi);
-  if (!ctx) {
-    return {
-      ok: false,
-      error: {
-        code: editorUi ? 'no_editor_session' : 'not_in_editor_mode',
-        message: 'Editor session is not available.'
-      }
-    };
-  }
-
-  ensureLevelEntryUids(ctx.session.level);
-
-  const atomic = options?.atomic === true;
-  const dryRun = options?.dryRun === true;
-  const historyOptions = options?.history || {};
-  const previewOptions = options?.preview || {};
-  const validateOptions = options?.validate || {};
-  const returnState = options?.returnState || 'editor';
-  const historyLabel = historyOptions.label || 'Editor Apply';
-  const previewLabel = previewOptions.label || historyLabel;
-
-  const results = [];
-  const resources = [];
-  let changed = false;
-  let usedHistoryOp = false;
-  const rollbackText = atomic && typeof view?.getEditorLevelText === 'function'
-    ? view.getEditorLevelText()
-    : null;
-
-  const registerResource = (resource) => {
-    if (!resource) return;
-    resources.push(resource);
-  };
-
-  const applyError = (code, message, details) => ({
-    ok: false,
-    error: { code, message, details },
-    results
-  });
-
-  const getLevel = () => ctx.session.level;
-
-  const resolveSelectionFromRefs = (refs) => {
-    if (!Array.isArray(refs)) return [];
-    const next = [];
-    for (const ref of refs) {
-      const resolved = resolveEntryRef(getLevel(), ref);
-      if (!resolved) continue;
-      next.push({ type: resolved.kind, index: resolved.index });
-    }
-    return next;
-  };
-
-  const applySnap = (x, y, snapMode) => {
-    if (!snapMode || snapMode === 'useCurrent') {
-      return ctx.controller._snap ? ctx.controller._snap(x, y) : { x, y };
-    }
-    if (snapMode === 'none') return { x, y };
-    const gridSize = Number(snapMode.gridSize);
-    if (!Number.isFinite(gridSize) || gridSize <= 1) {
-      return { x: Math.round(x), y: Math.round(y) };
-    }
-    return {
-      x: Math.round(x / gridSize) * gridSize,
-      y: Math.round(y / gridSize) * gridSize
-    };
-  };
-
-  const validateAndFix = () => {
-    if (validateOptions.run === false) return null;
-    const issues = validateLevel(getLevel(), ctx.assets);
-    if (validateOptions.autoFix && validateOptions.autoFix !== 'none') {
-      let fixed = false;
-      for (const issue of issues) {
-        if (typeof issue.fix === 'function') {
-          issue.fix();
-          fixed = true;
-        }
-      }
-      if (fixed) {
-        changed = true;
-      }
-    }
-    return serializeIssues(issues);
-  };
-
-  for (const op of ops || []) {
-    const opId = op?.opId ?? null;
-    const type = String(op?.type || '');
-    const args = op?.args || {};
-    let value = null;
-    let ok = true;
-    let errorCode = 'invalid_op';
-    let errorMessage = 'Invalid op';
-    try {
-      switch (type) {
-      case 'editor.ensure': {
-        if (args?.enter && view?.enterEditorMode) {
-          view.enterEditorMode();
-        }
-        value = { inEditor: !!view?.editorMode };
-        break;
-      }
-      case 'level.new': {
-        if (dryRun) break;
-        view?.createBlankEditorLevel?.({ render: false });
-        ctx.session = view?.editorSession || ctx.session;
-        ctx.controller.session = ctx.session;
-        ensureLevelEntryUids(ctx.session.level);
-        if (args?.header && ctx.session.level) {
-          for (const [key, val] of Object.entries(args.header)) {
-            ctx.session.level.setHeader(key, val);
-          }
-        }
-        if (args?.skillset && ctx.session.level?.skillset) {
-          for (const [key, val] of Object.entries(args.skillset)) {
-            ctx.session.level.setSkill(key, val);
-          }
-        }
-        if (args?.resetHistory) {
-          ctx.controller.resetHistory('New');
-        }
-        changed = true;
-        value = { created: true };
-        break;
-      }
-      case 'level.loadText': {
-        if (dryRun) break;
-        const text = String(args?.text || '');
-        const level = view?.loadEditorLevelFromText?.(text, { render: false });
-        if (!level) {
-          ok = false;
-          errorCode = 'invalid_op';
-          errorMessage = 'Failed to load level text.';
-          break;
-        }
-        ctx.session = view?.editorSession || ctx.session;
-        ctx.controller.session = ctx.session;
-        ensureLevelEntryUids(ctx.session.level);
-        if (args?.resetHistory) {
-          ctx.controller.resetHistory(args?.sourceLabel || 'Import');
-        }
-        changed = true;
-        break;
-      }
-      case 'level.loadSaved': {
-        if (dryRun) break;
-        const text = loadSavedLevel(undefined, args?.savedId);
-        if (!text) {
-          ok = false;
-          errorCode = 'invalid_ref';
-          errorMessage = 'Saved level not found.';
-          break;
-        }
-        const level = view?.loadEditorLevelFromText?.(text, { render: false });
-        if (!level) {
-          ok = false;
-          errorCode = 'invalid_op';
-          errorMessage = 'Failed to load saved level.';
-          break;
-        }
-        ctx.session = view?.editorSession || ctx.session;
-        ctx.controller.session = ctx.session;
-        ensureLevelEntryUids(ctx.session.level);
-        if (args?.resetHistory) {
-          ctx.controller.resetHistory('Load Saved');
-        }
-        changed = true;
-        break;
-      }
-      case 'level.save': {
-        const name = String(args?.name || '');
-        const text = view?.getEditorLevelText?.();
-        if (!text) {
-          ok = false;
-          errorCode = 'invalid_op';
-          errorMessage = 'Unable to serialize level.';
-          break;
-        }
-        const savedId = saveLevel(undefined, {
-          id: args?.overwriteId || undefined,
-          name,
-          text
-        });
-        if (!savedId) {
-          ok = false;
-          errorCode = 'internal_error';
-          errorMessage = 'Failed to save level.';
-          break;
-        }
-        value = { savedId, name };
-        break;
-      }
-      case 'level.export': {
-        const format = args?.format === 'classicLvl' ? 'classicLvl' : 'nxlv';
-        if (format === 'nxlv') {
-          const text = view?.getEditorLevelText?.() || '';
-          const filename = String(args?.filename || 'level.nxlv');
-          registerResource({
-            name: filename,
-            mimeType: 'text/plain',
-            encoding: 'text',
-            data: text,
-            meta: { kind: 'export', format: 'nxlv', label: filename }
-          });
-          value = { filename };
-        } else {
-          const classic = createClassicLevelData(getLevel());
-          if (!classic?.levelReader) {
-            ok = false;
-            errorCode = 'internal_error';
-            errorMessage = 'Failed to export classic level.';
-            break;
-          }
-          const writer = new LevelWriter();
-          const payload = {
-            levelProperties: classic.levelReader.levelProperties,
-            screenPositionX: classic.levelReader.screenPositionX,
-            graphicSet1: classic.levelReader.graphicSet1,
-            graphicSet2: classic.levelReader.graphicSet2,
-            isSuperLemming: classic.levelReader.isSuperLemming,
-            objects: classic.levelReader.objects,
-            terrains: classic.levelReader.terrains,
-            steel: classic.levelReader.steel
-          };
-          const bytes = writer.write(payload);
-          const filename = String(args?.filename || 'level.lvl');
-          registerResource({
-            name: filename,
-            mimeType: 'application/octet-stream',
-            encoding: 'base64',
-            data: encodeBase64(bytes),
-            meta: { kind: 'export', format: 'classicLvl', label: filename }
-          });
-          value = { filename };
-        }
-        break;
-      }
-      case 'level.importClassicLvl': {
-        if (dryRun) break;
-        const raw = String(args?.bytesBase64 || '');
-        if (!raw) {
-          ok = false;
-          errorCode = 'invalid_op';
-          errorMessage = 'Missing classic level bytes.';
-          break;
-        }
-        const bytes = Uint8Array.from(atob(raw), c => c.charCodeAt(0));
-        const reader = new BinaryReader(bytes);
-        const levelReader = new LevelReader(reader);
-        const editorLevel = createEditorLevelFromClassic(levelReader);
-        if (!editorLevel) {
-          ok = false;
-          errorCode = 'invalid_op';
-          errorMessage = 'Failed to parse classic level.';
-          break;
-        }
-        ctx.session.level = editorLevel;
-        ensureLevelEntryUids(ctx.session.level);
-        if (args?.resetHistory) {
-          ctx.controller.resetHistory(args?.sourceLabel || 'Import LVL');
-        }
-        changed = true;
-        break;
-      }
-      case 'level.patchHeader': {
-        if (dryRun) break;
-        const level = getLevel();
-        if (!level) break;
-        const set = args?.set || {};
-        for (const [key, val] of Object.entries(set)) {
-          level.setHeader(key, val);
-        }
-        if (Array.isArray(args?.unset)) {
-          for (const key of args.unset) {
-            level.removeHeader(key);
-          }
-        }
-        changed = true;
-        break;
-      }
-      case 'level.patchSkillset': {
-        if (dryRun) break;
-        const level = getLevel();
-        if (!level) break;
-        const set = args?.set || {};
-        for (const [key, val] of Object.entries(set)) {
-          level.setSkill(key, val);
-        }
-        if (Array.isArray(args?.unset)) {
-          for (const key of args.unset) {
-            level.skillset?.delete?.(String(key).trim().toUpperCase());
-          }
-        }
-        changed = true;
-        break;
-      }
-      case 'editor.setTool': {
-        const tool = args?.tool;
-        if (!tool) break;
-        const validTools = new Set(Object.values(EditorTools));
-        if (validTools.has(tool)) {
-          ctx.controller.setTool(tool);
-        }
-        value = { tool: ctx.controller.tool };
-        break;
-      }
-      case 'editor.setBrushSettings': {
-        if (Number.isFinite(args?.gridSize)) ctx.controller.gridSize = Math.max(1, Math.trunc(args.gridSize));
-        if (args?.snapEnabled !== undefined) ctx.controller.setSnapEnabled(!!args.snapEnabled);
-        if (Number.isFinite(args?.brushSize)) ctx.controller.setBrushSize(Math.max(1, Math.trunc(args.brushSize)));
-        if (args?.eraseGadgets !== undefined) ctx.controller.setEraseGadgets(!!args.eraseGadgets);
-        if (Number.isFinite(args?.handleSize)) ctx.controller.handleSize = Math.max(1, Math.trunc(args.handleSize));
-        value = {
-          gridSize: ctx.controller.gridSize,
-          snapEnabled: ctx.controller.snapEnabled,
-          brushSize: ctx.controller.brushSize,
-          eraseGadgets: ctx.controller.eraseGadgets,
-          handleSize: ctx.controller.handleSize
-        };
-        break;
-      }
-      case 'editor.setPaletteSelection': {
-        if (Number.isFinite(args?.selectedTerrainId)) ctx.controller.setSelectedTerrain(args.selectedTerrainId);
-        if (Number.isFinite(args?.selectedGadgetId)) ctx.controller.setSelectedGadget(args.selectedGadgetId);
-        if (Number.isFinite(args?.selectedTriggerId)) ctx.controller.setSelectedTrigger(args.selectedTriggerId);
-        value = {
-          selectedTerrainId: ctx.controller.selectedTerrainId,
-          selectedGadgetId: ctx.controller.selectedGadgetId,
-          selectedTriggerId: ctx.controller.selectedTriggerId
-        };
-        break;
-      }
-      case 'selection.clear': {
-        ctx.controller.clearSelection();
-        value = { cleared: true };
-        break;
-      }
-      case 'selection.set': {
-        const refs = resolveSelectionFromRefs(args?.selection);
-        ctx.controller._setSelection(refs);
-        value = { count: refs.length };
-        break;
-      }
-      case 'selection.hitTest': {
-        const x = Number(args?.x);
-        const y = Number(args?.y);
-        if (!Number.isFinite(x) || !Number.isFinite(y)) {
-          value = { hit: null };
-          break;
-        }
-        const kinds = Array.isArray(args?.kinds) ? args.kinds : ['terrain', 'gadget', 'steel'];
-        const level = getLevel();
-        let hit = null;
-        if (kinds.includes('gadget')) {
-          const gadgetHit = findEntryAt(level?.gadgets, ctx.assets?.gadgetById, x, y);
-          if (gadgetHit) hit = { kind: 'gadget', ...gadgetHit };
-        }
-        if (!hit && kinds.includes('steel')) {
-          const steelHit = findEntryAt(level?.steel, null, x, y);
-          if (steelHit) hit = { kind: 'steel', ...steelHit };
-        }
-        if (!hit && kinds.includes('terrain')) {
-          const terrainHit = findEntryAt(level?.terrains, ctx.assets?.terrainById, x, y);
-          if (terrainHit) hit = { kind: 'terrain', ...terrainHit };
-        }
-        if (hit && hit.entry) {
-          value = { hit: { kind: hit.kind, index: hit.index, uid: hit.entry.uid || null } };
-        } else {
-          value = { hit: null };
-        }
-        break;
-      }
-      case 'selection.boxSelect': {
-        const bounds = args?.bounds;
-        if (!bounds) {
-          value = { count: 0 };
-          break;
-        }
-        const mode = args?.mode || 'replace';
-        const hits = [];
-        const addHit = (type, index) => {
-          if (hits.some(entry => entry.type === type && entry.index === index)) return;
-          hits.push({ type, index });
-        };
-        const scan = (entries, metaById, type) => {
-          if (!Array.isArray(entries)) return;
-          for (let i = 0; i < entries.length; i++) {
-            const entry = entries[i];
-            const meta = metaById?.get?.(entry?.props?.PIECE);
-            const entryBounds = getEntryBounds(entry, meta);
-            if (boundsIntersect(bounds, entryBounds)) addHit(type, i);
-          }
-        };
-        const level = getLevel();
-        scan(level?.terrains, ctx.assets?.terrainById, 'terrain');
-        scan(level?.gadgets, ctx.assets?.gadgetById, 'gadget');
-        scan(level?.steel, null, 'steel');
-        let next = [];
-        if (mode === 'replace') {
-          next = hits;
-        } else if (mode === 'add') {
-          next = ctx.controller.selection.slice();
-          for (const hit of hits) {
-            if (!next.some(entry => entry.type === hit.type && entry.index === hit.index)) {
-              next.push(hit);
-            }
-          }
-        } else if (mode === 'toggle') {
-          next = ctx.controller.selection.slice();
-          for (const hit of hits) {
-            const idx = next.findIndex(entry => entry.type === hit.type && entry.index === hit.index);
-            if (idx >= 0) {
-              next.splice(idx, 1);
-            } else {
-              next.push(hit);
-            }
-          }
-        }
-        ctx.controller._setSelection(next);
-        value = { count: ctx.controller.selection.length };
-        break;
-      }
-      case 'entry.add': {
-        if (dryRun) break;
-        const kind = args?.kind;
-        const list = getListForKind(getLevel(), kind);
-        if (!Array.isArray(list)) {
-          ok = false;
-          errorCode = 'invalid_ref';
-          errorMessage = 'Invalid entry kind.';
-          break;
-        }
-        let entry = null;
-        if (kind === 'terrain') {
-          entry = createTerrainEntry({
-            styleName: getLevel()?.getHeader?.('STYLE'),
-            piece: args?.props?.PIECE ?? args?.props?.piece ?? args?.piece,
-            x: args?.props?.X ?? args?.props?.x ?? args?.x,
-            y: args?.props?.Y ?? args?.props?.y ?? args?.y
-          });
-        } else if (kind === 'gadget') {
-          entry = createGadgetEntry({
-            styleName: getLevel()?.getHeader?.('STYLE'),
-            piece: args?.props?.PIECE ?? args?.props?.piece ?? args?.piece,
-            x: args?.props?.X ?? args?.props?.x ?? args?.x,
-            y: args?.props?.Y ?? args?.props?.y ?? args?.y
-          });
-        } else if (kind === 'steel') {
-          entry = createSteelEntry({
-            x: args?.props?.X ?? args?.x,
-            y: args?.props?.Y ?? args?.y,
-            width: args?.props?.WIDTH ?? args?.width,
-            height: args?.props?.HEIGHT ?? args?.height
-          });
-        }
-        if (!entry) {
-          ok = false;
-          errorCode = 'invalid_op';
-          errorMessage = 'Failed to create entry.';
-          break;
-        }
-        const insert = args?.insert;
-        if (insert && Number.isFinite(insert.index)) {
-          const idx = Math.max(0, Math.min(list.length, Math.trunc(insert.index)));
-          list.splice(idx, 0, entry);
-          value = { ref: { kind, index: idx, uid: entry.uid || null } };
-        } else {
-          list.push(entry);
-          value = { ref: { kind, index: list.length - 1, uid: entry.uid || null } };
-        }
-        changed = true;
-        break;
-      }
-      case 'entry.update': {
-        if (dryRun) break;
-        const resolved = resolveEntryRef(getLevel(), args?.ref);
-        if (!resolved) {
-          ok = false;
-          errorCode = 'invalid_ref';
-          errorMessage = 'Entry not found.';
-          break;
-        }
-        const set = args?.set || {};
-        for (const [key, val] of Object.entries(set)) {
-          const removeIfFalse = typeof val === 'boolean';
-          setEntryProp(resolved.entry, key, val, { removeIfFalse });
-        }
-        if (Array.isArray(args?.unset)) {
-          for (const key of args.unset) {
-            setEntryProp(resolved.entry, key, undefined, { removeIfEmpty: true });
-          }
-        }
-        changed = true;
-        break;
-      }
-      case 'entry.remove': {
-        if (dryRun) break;
-        const refs = Array.isArray(args?.refs) ? args.refs : [];
-        const groups = { terrain: [], gadget: [], steel: [] };
-        for (const ref of refs) {
-          const resolved = resolveEntryRef(getLevel(), ref);
-          if (!resolved) continue;
-          groups[resolved.kind]?.push(resolved.index);
-        }
-        for (const [kind, indices] of Object.entries(groups)) {
-          indices.sort((a, b) => b - a);
-          for (const index of indices) {
-            removeEntryAt(getLevel(), kind, index);
-          }
-        }
-        changed = refs.length > 0;
-        break;
-      }
-      case 'entry.duplicate': {
-        if (dryRun) break;
-        const refs = Array.isArray(args?.refs) ? args.refs : [];
-        const dx = Number.isFinite(args?.offset?.dx) ? args.offset.dx : 0;
-        const dy = Number.isFinite(args?.offset?.dy) ? args.offset.dy : 0;
-        const nextRefs = [];
-        for (const ref of refs) {
-          const resolved = resolveEntryRef(getLevel(), ref);
-          if (!resolved) continue;
-          const prefix = getPrefixForKind(resolved.kind);
-          const clone = cloneEntryForApply(resolved.entry, prefix);
-          clone.props.X = (Number.isFinite(clone.props.X) ? clone.props.X : 0) + dx;
-          clone.props.Y = (Number.isFinite(clone.props.Y) ? clone.props.Y : 0) + dy;
-          resolved.list.push(clone);
-          nextRefs.push({ kind: resolved.kind, index: resolved.list.length - 1, uid: clone.uid || null });
-        }
-        if (args?.selectNew) {
-          ctx.controller._setSelection(nextRefs.map(ref => ({ type: ref.kind, index: ref.index })));
-        }
-        value = { refs: nextRefs };
-        changed = nextRefs.length > 0;
-        break;
-      }
-      case 'entry.reorder': {
-        if (dryRun) break;
-        const action = args?.action;
-        const selection = ctx.controller.selection.slice();
-        const groups = { terrain: [], gadget: [], steel: [] };
-        for (const selected of selection) {
-          if (groups[selected.type]) groups[selected.type].push(selected.index);
-        }
-        const reorderList = (list, indices, dir) => {
-          if (!Array.isArray(list) || indices.length === 0) return null;
-          const unique = Array.from(new Set(indices)).filter(idx => idx >= 0 && idx < list.length);
-          if (!unique.length) return null;
-          const selectedSet = new Set(unique);
-          if (dir === 'front' || dir === 'back') {
-            const ordered = unique.slice().sort((a, b) => a - b).map(idx => list[idx]);
-            const remaining = list.filter((_, idx) => !selectedSet.has(idx));
-            list.length = 0;
-            if (dir === 'front') {
-              list.push(...remaining, ...ordered);
-            } else {
-              list.push(...ordered, ...remaining);
-            }
-            const next = new Map();
-            list.forEach((entry, idx) => next.set(entry, idx));
-            return ordered.map(entry => next.get(entry)).filter(idx => idx != null);
-          }
-          if (dir === 'forward') {
-            const sorted = unique.slice().sort((a, b) => b - a);
-            for (const idx of sorted) {
-              if (idx >= list.length - 1) continue;
-              if (selectedSet.has(idx + 1)) continue;
-              const tmp = list[idx + 1];
-              list[idx + 1] = list[idx];
-              list[idx] = tmp;
-              selectedSet.delete(idx);
-              selectedSet.add(idx + 1);
-            }
-            return Array.from(selectedSet);
-          }
-          if (dir === 'backward') {
-            const sorted = unique.slice().sort((a, b) => a - b);
-            for (const idx of sorted) {
-              if (idx <= 0) continue;
-              if (selectedSet.has(idx - 1)) continue;
-              const tmp = list[idx - 1];
-              list[idx - 1] = list[idx];
-              list[idx] = tmp;
-              selectedSet.delete(idx);
-              selectedSet.add(idx - 1);
-            }
-            return Array.from(selectedSet);
-          }
-          return null;
-        };
-        const nextSelection = [];
-        for (const [kind, indices] of Object.entries(groups)) {
-          const list = getListForKind(getLevel(), kind);
-          const nextIndices = reorderList(list, indices, action === 'bringToFront' ? 'front'
-            : action === 'sendToBack' ? 'back'
-              : action === 'moveForward' ? 'forward'
-                : action === 'moveBackward' ? 'backward'
-                  : null);
-          if (!nextIndices) continue;
-          for (const idx of nextIndices) {
-            nextSelection.push({ type: kind, index: idx });
-          }
-        }
-        if (nextSelection.length) {
-          ctx.controller._setSelection(nextSelection);
-        }
-        changed = nextSelection.length > 0;
-        break;
-      }
-      case 'tool.place': {
-        if (dryRun) break;
-        const tool = String(args?.tool || '');
-        const pos = applySnap(Number(args?.x || 0), Number(args?.y || 0), args?.snap);
-        let entry = null;
-        if (tool === EditorTools.TERRAIN) {
-          if (Number.isFinite(args?.pieceId)) ctx.controller.setSelectedTerrain(args.pieceId);
-          entry = ctx.controller._placeTerrainAt(pos.x, pos.y);
-        } else if (tool === EditorTools.GADGET) {
-          if (Number.isFinite(args?.pieceId)) ctx.controller.setSelectedGadget(args.pieceId);
-          entry = ctx.controller._placeGadgetAt(pos.x, pos.y, ctx.controller.selectedGadgetId);
-        } else if (tool === EditorTools.TRIGGER) {
-          if (Number.isFinite(args?.pieceId)) ctx.controller.setSelectedTrigger(args.pieceId);
-          const id = ctx.controller.selectedTriggerId ?? ctx.controller.selectedGadgetId;
-          entry = ctx.controller._placeGadgetAt(pos.x, pos.y, id);
-        } else if (tool === EditorTools.ENTRANCE) {
-          const id = ctx.assets?.entranceId ?? ctx.controller.selectedGadgetId;
-          entry = ctx.controller._placeGadgetAt(pos.x, pos.y, id);
-        } else if (tool === EditorTools.EXIT) {
-          const id = ctx.assets?.exitId ?? ctx.controller.selectedGadgetId;
-          entry = ctx.controller._placeGadgetAt(pos.x, pos.y, id);
-        } else if (tool === EditorTools.STEEL) {
-          const size = Number.isFinite(ctx.controller.gridSize) ? ctx.controller.gridSize : 1;
-          entry = ctx.controller._placeSteelAt(pos.x, pos.y, size, size);
-        }
-        if (entry) {
-          const kind = tool === EditorTools.STEEL ? 'steel'
-            : tool === EditorTools.GADGET || tool === EditorTools.TRIGGER || tool === EditorTools.ENTRANCE || tool === EditorTools.EXIT
-              ? 'gadget'
-              : 'terrain';
-          const list = getListForKind(getLevel(), kind);
-          const index = Array.isArray(list) ? list.indexOf(entry) : -1;
-          if (index >= 0) {
-            ctx.controller._setSelection([{ type: kind, index }]);
-            value = { ref: { kind, index, uid: entry.uid || null } };
-          }
-          changed = true;
-        }
-        break;
-      }
-      case 'tool.stroke':
-      case 'tool.erase': {
-        if (dryRun) break;
-        const tool = type === 'tool.erase' ? EditorTools.ERASER : String(args?.tool || '');
-        const points = Array.isArray(args?.points) ? args.points : [];
-        if (!points.length) break;
-        const prevErase = ctx.controller.eraseGadgets;
-        if (typeof args?.eraseGadgets === 'boolean') {
-          ctx.controller.setEraseGadgets(args.eraseGadgets);
-        }
-        ctx.controller._beginStroke();
-        let last = null;
-        for (const point of points) {
-          const pos = applySnap(Number(point.x || 0), Number(point.y || 0), args?.snap);
-          if (tool === EditorTools.BRUSH) {
-            if (last) ctx.controller._brushLine(last, pos);
-            else ctx.controller._brushAt(pos.x, pos.y);
-          } else if (tool === EditorTools.ERASER) {
-            if (last) ctx.controller._eraseLine(last, pos);
-            else ctx.controller._eraseAt(pos.x, pos.y);
-          }
-          last = pos;
-        }
-        ctx.controller._lastBrushPos = null;
-        ctx.controller.setEraseGadgets(prevErase);
-        changed = true;
-        break;
-      }
-      case 'tool.steelRect': {
-        if (dryRun) break;
-        const rects = Array.isArray(args?.rects) ? args.rects : [];
-        for (const rect of rects) {
-          const bounds = normalizeBounds(rect.x, rect.y, rect.x + rect.width, rect.y + rect.height);
-          ctx.controller._placeSteelAt(bounds.x, bounds.y, bounds.width, bounds.height);
-        }
-        changed = rects.length > 0;
-        break;
-      }
-      case 'history.undo': {
-        usedHistoryOp = true;
-        const count = Number.isFinite(args?.count) ? Math.max(1, Math.trunc(args.count)) : 1;
-        for (let i = 0; i < count; i++) {
-          ctx.controller.undo();
-        }
-        value = { count };
-        break;
-      }
-      case 'history.redo': {
-        usedHistoryOp = true;
-        const count = Number.isFinite(args?.count) ? Math.max(1, Math.trunc(args.count)) : 1;
-        for (let i = 0; i < count; i++) {
-          ctx.controller.redo();
-        }
-        value = { count };
-        break;
-      }
-      case 'history.getEntry': {
-        const entry = getEditorHistoryEntry(ctx.history, Number(args?.index));
-        value = entry || null;
-        break;
-      }
-      case 'validate.run': {
-        value = validateAndFix();
-        break;
-      }
-      default:
-        ok = false;
-        errorCode = 'invalid_op';
-        errorMessage = `Unknown op: ${type}`;
-        break;
-      }
-    } catch (err) {
-      ok = false;
-      errorCode = 'internal_error';
-      errorMessage = err ? String(err) : 'Unknown error';
-    }
-
-    if (ok) {
-      results.push({ opId, type, ok: true, value });
-    } else {
-      results.push({ opId, type, ok: false, error: errorMessage });
-      if (atomic) {
-        if (rollbackText && typeof view?.loadEditorLevelFromText === 'function') {
-          view.loadEditorLevelFromText(rollbackText, { render: false });
-          ctx.session = view?.editorSession || ctx.session;
-          ctx.controller.session = ctx.session;
-          ensureLevelEntryUids(ctx.session.level);
-        }
-        return applyError(errorCode, errorMessage);
-      }
-    }
-  }
-
-  const validation = validateAndFix();
-  if (validation) {
-    results.push({ opId: null, type: 'validate.run', ok: true, value: validation });
-  }
-
-  if (historyOptions.record !== false && changed && !usedHistoryOp) {
-    ctx.controller.history.pushSnapshot(getLevel(), historyLabel);
-  }
-
-  if (previewOptions.refresh !== false && ctx.editorUi?._refreshPreview) {
-    await ctx.editorUi._refreshPreview(previewLabel, {
-      preserveView: previewOptions.preserveViewport !== false
-    });
-  }
-
-  let state = null;
-  if (returnState === 'editor') {
-    state = getEditorState(view, editorUi);
-  } else if (returnState === 'full') {
-    state = {
-      version: 1,
-      mode: editorUi ? 'editor' : (view?.editorMode ? 'editor' : 'game'),
-      ready: isGameReady(view),
-      view: getViewState(view),
-      stage: getStageState(view?.stage),
-      game: getGameState(view),
-      editor: getEditorState(view, editorUi),
-      bench: getBenchMetrics(view),
-      midi: {
-        enabled: !!view?.midiEnabled,
-        hasRouter: !!view?.midiRouter,
-        outputName: view?.midiOut?.name || null
-      }
-    };
-  }
-
-  return {
-    ok: true,
-    results,
-    resources,
-    state
-  };
-};
-
-const getBuffer = (view, name) => {
-  const normalized = normalizeBufferName(name);
-  const game = view?.game || null;
-  const level = game?.level || null;
-  const manager = game?.getLemmingManager?.() || null;
-  const minimap = manager?.miniMap || null;
-
-  switch (normalized) {
-  case 'ground-mask': {
-    const mask = level?.groundMask?.mask || null;
-    return packBuffer('ground-mask', mask, {
-      width: level?.width ?? null,
-      height: level?.height ?? null,
-      stride: level?.width ?? null,
-      format: 'mask8'
-    });
-  }
-  case 'ground-image': {
-    const image = level?.groundImage || null;
-    return packBuffer('ground-image', image, {
-      width: level?.width ?? null,
-      height: level?.height ?? null,
-      stride: level?.width ? level.width * 4 : null,
-      format: 'rgba8888'
-    });
-  }
-  case 'minimap-terrain':
-    return packBuffer('minimap-terrain', minimap?.terrain || null, {
-      width: minimap?.width ?? null,
-      height: minimap?.height ?? null,
-      stride: minimap?.width ?? null,
-      format: 'u8'
-    });
-  case 'minimap-fog':
-    return packBuffer('minimap-fog', minimap?.fog || null, {
-      width: minimap?.width ?? null,
-      height: minimap?.height ?? null,
-      stride: minimap?.width ?? null,
-      format: 'u8'
-    });
-  case 'minimap-live-dots':
-    return packBuffer('minimap-live-dots', minimap?.liveDots || null, {
-      pairStride: 2,
-      count: minimap?.liveDots?.length ? minimap.liveDots.length / 2 : 0,
-      format: 'xy'
-    });
-  case 'minimap-dead-dots': {
-    const count = minimap?.deadCount ?? 0;
-    const data = minimap?.deadDots?.subarray(0, count * 2) || null;
-    return packBuffer('minimap-dead-dots', data, {
-      pairStride: 2,
-      count,
-      format: 'xy'
-    });
-  }
-  case 'minimap-dead-ttls': {
-    const count = minimap?.deadCount ?? 0;
-    const data = minimap?.deadTTLs?.subarray(0, count) || null;
-    return packBuffer('minimap-dead-ttls', data, {
-      count,
-      format: 'u8'
-    });
-  }
-  default:
-    return null;
-  }
-};
-
-const pauseGame = (view) => {
-  const timer = view?.game?.getGameTimer?.();
-  if (!timer) return false;
-  timer.suspend?.();
-  return true;
-};
-
-const resumeGame = (view) => {
-  const timer = view?.game?.getGameTimer?.();
-  if (!timer) return false;
-  timer.continue?.();
-  return true;
-};
-
-const stepGame = (view, count = 1) => {
-  const game = view?.game;
-  const timer = game?.getGameTimer?.();
-  if (!game || !timer) return false;
-  if (timer.isRunning?.()) timer.suspend?.();
-  const steps = Math.trunc(count);
-  if (!steps) return true;
-  if (steps > 0) {
-    if (game.timeTravel?.isReversing) game.timeTravel.stopReverse?.();
-    game.history?.truncateAfter?.(timer.tickIndex);
-  }
-  timer.tick(steps);
-  if (game.gameGui) {
-    game.gameGui.gameTimeChanged = true;
-  }
-  game.render?.();
-  return true;
-};
-
-const seekGame = (view, tickIndex) => {
-  const game = view?.game;
-  const timer = game?.getGameTimer?.();
-  if (!game || !timer) return false;
-  if (timer.isRunning?.()) timer.suspend?.();
-  if (game.timeTravel?.seekToTick) {
-    game.timeTravel.seekToTick(tickIndex);
-    return true;
-  }
-  return false;
-};
-
-const setEditorPlaytest = (view, editorUi, enabled) => {
-  const desired = !!enabled;
-  if (editorUi && editorUi._playtest !== desired && editorUi._togglePlaytest) {
-    editorUi._togglePlaytest();
-    return true;
-  }
-  if (view?.setEditorPlaytest) {
-    view.setEditorPlaytest(desired);
-    return true;
-  }
-  return false;
-};
-
-const setSpeed = (view, speedFactor) => {
-  if (!view) return false;
-  const value = Number(speedFactor);
-  if (!Number.isFinite(value) || value <= 0) return false;
-  view.selectSpeedFactor?.(value);
-  return true;
-};
-
-const selectLemmingById = (view, lemmingId) => {
-  const manager = view?.game?.getLemmingManager?.();
-  const id = Number(lemmingId);
-  if (!manager || !Number.isFinite(id)) return false;
-  const lem = manager.getLemming?.(id);
-  if (!lem || lem.removed || lem.disabled) return false;
-  manager.setSelectedLemming?.(lem);
-  return true;
-};
-
-const startReverse = (view) => {
-  const timeTravel = view?.game?.timeTravel;
-  if (!timeTravel?.startReverse) return false;
-  timeTravel.startReverse();
-  return true;
-};
-
-const stopReverse = (view) => {
-  const timeTravel = view?.game?.timeTravel;
-  if (!timeTravel?.stopReverse) return false;
-  timeTravel.stopReverse();
-  return true;
-};
-
-const toggleReverse = (view) => {
-  const timeTravel = view?.game?.timeTravel;
-  if (!timeTravel?.toggleReverse) return false;
-  timeTravel.toggleReverse();
-  return true;
-};
-
-const flushSoundEvents = (view) => {
-  const soundEvents = view?.game?.soundEvents;
-  if (!soundEvents?.flush) return false;
-  soundEvents.flush();
-  return true;
-};
-
-const getHistoryDelta = (view, tickIndex) => {
-  const history = view?.game?.history;
-  const t = Math.trunc(Number(tickIndex));
-  if (!history?.getDelta || !Number.isFinite(t)) return null;
-  return history.getDelta(t) || null;
-};
-
-const getHistoryDeltas = (view, fromTick, toTick, maxTicks = 0) => {
-  const history = view?.game?.history;
-  if (!history?.getDelta) return [];
-
-  const start = Math.trunc(Number(fromTick));
-  const end = Math.trunc(Number(toTick));
-  if (!Number.isFinite(start) || !Number.isFinite(end)) return [];
-
-  const step = start <= end ? 1 : -1;
-  const limit = Number.isFinite(maxTicks) && maxTicks > 0 ? Math.trunc(maxTicks) : Infinity;
-
-  const deltas = [];
-  let n = 0;
-  for (let t = start; ; t += step) {
-    if (n >= limit) break;
-    const delta = history.getDelta(t);
-    if (delta) deltas.push(delta);
-    n += 1;
-    if (t === end) break;
-  }
-  return deltas;
-};
-
-const startBenchSequence = async (view) => {
-  if (!view?.benchSequenceStart) return false;
-  await view.benchSequenceStart();
-  return true;
-};
-
-const startBench = async (view, entrances = 1) => {
-  if (!view?.benchStart) return false;
-  const count = Math.max(1, Math.trunc(Number(entrances) || 1));
-  await view.benchStart(count);
-  return true;
-};
-
-const stopBench = (view) => {
-  if (!view) return false;
-  view.bench = false;
-  view.bench2 = false;
-  view.benchReverse = false;
-  view.benchSequence = false;
-  return true;
-};
-
+  getRuntimeDependency
+} from './e2e/e2eShared.js';
+import {
+  isE2EEnabled,
+  normalizeBufferName,
+  toByteView,
+  encodeBase64,
+  packBuffer,
+  cloneEntry,
+  cloneTerrainGroup,
+  cloneUnknownSection,
+  serializeEditorLevel,
+  serializeSelectionEntry,
+  serializeEditorController,
+  summarizeEditorHistory,
+  getEditorHistoryEntry,
+  serializeIssues,
+  serializeAssets,
+  getActionType,
+  serializeLemming,
+  serializeTrigger,
+  serializeMapObject,
+  isGameReady,
+  getViewState,
+  getProcgenState,
+  getGameState
+} from './e2e/E2EStateSerialization.js';
+import {
+  getBenchMetrics,
+  toSortedStringList,
+  getRuntimeDiagnostics,
+  getCacheStorageKeys,
+  getEnvironmentDiagnostics,
+  getStageState,
+  getCanvasMetrics
+} from './e2e/E2EDiagnostics.js';
+import {
+  getEditorState
+} from './e2e/E2EEditorState.js';
+import {
+  getEditorContext,
+  getListForKind,
+  getPrefixForKind,
+  resolveEntryRef,
+  cloneEntryForApply,
+  normalizeBounds,
+  boundsIntersect,
+  applyEditorOps
+} from './e2e/E2EEditorApply.js';
+import {
+  getBuffer,
+  getEditorLevelText,
+  getStageCanvasRect,
+  getStageWorldPointFromPage,
+  getStagePagePointFromWorld,
+  centerStageOn,
+  getMinimapPagePoint,
+  getCaptureRects
+} from './e2e/E2ECanvasHarness.js';
+import {
+  pauseGame,
+  resumeGame,
+  stepGame,
+  seekGame,
+  setEditorPlaytest,
+  setSpeed,
+  selectLemmingById,
+  centerViewOnLemming,
+  startReverse,
+  stopReverse,
+  toggleReverse,
+  flushSoundEvents,
+  getHistoryDelta,
+  getHistoryDeltas,
+  startBenchSequence,
+  startBench,
+  stopBench
+} from './e2e/E2EGameControls.js';
 const createE2EApi = (context) => ({
   version: 1,
   _setContext: (next) => {
     context.view = next?.view || context.view;
     context.editorUi = next?.editorUi || context.editorUi;
+    context.midiUi = next?.midiUi || context.midiUi;
+    context.procgenController = next?.procgenController || context.procgenController || null;
   },
   getState: () => {
     const view = context.view;
@@ -1698,14 +97,26 @@ const createE2EApi = (context) => ({
       game: getGameState(view),
       editor: getEditorState(view, editorUi),
       bench: getBenchMetrics(view),
+      diagnostics: getEnvironmentDiagnostics(view),
+      procgen: getProcgenState(context.procgenController || view),
       midi: {
         enabled: !!view?.midiEnabled,
         hasRouter: !!view?.midiRouter,
-        outputName: view?.midiOut?.name || null
+        outputName: view?.midiOut?.name || null,
+        projectId: context.midiUi?.getProject?.()?.id ?? null,
+        selectedTrackId: context.midiUi?.getProject?.()?.ui?.selectedTrackId ?? null,
+        selectedSourceId: context.midiUi?.getProject?.()?.ui?.selectedSourceId ?? null
       }
     };
   },
+  getCanvasMetrics: () => getCanvasMetrics(context.view),
+  getCaptureRects: (options) => getCaptureRects(context.view, context.editorUi, options),
   getBuffer: (name) => getBuffer(context.view, name),
+  getEditorLevelText: () => getEditorLevelText(context.view),
+  stageWorldFromPage: (point) => getStageWorldPointFromPage(context.view, point),
+  stagePageFromWorld: (point) => getStagePagePointFromWorld(context.view, point),
+  centerStageOn: (point) => centerStageOn(context.view, point),
+  getMinimapPagePoint: (options) => getMinimapPagePoint(context.view, options),
   getEditorHistoryEntry: (index) => getEditorHistoryEntry(context.editorUi?.history || null, index),
   editorApply: (ops, options) => applyEditorOps(context.view, context.editorUi, ops, options),
   pause: () => pauseGame(context.view),
@@ -1722,23 +133,49 @@ const createE2EApi = (context) => ({
   getDeltas: (fromTick, toTick, maxTicks = 0) =>
     getHistoryDeltas(context.view, fromTick, toTick, maxTicks),
   selectLemmingById: (id) => selectLemmingById(context.view, id),
+  centerViewOnLemming: (id) => centerViewOnLemming(context.view, id),
   getBenchMetrics: () => getBenchMetrics(context.view),
+  getDiagnostics: async () => getEnvironmentDiagnostics(
+    context.view,
+    { cacheStorageKeys: await getCacheStorageKeys() }
+  ),
   startBenchSequence: () => startBenchSequence(context.view),
   startBench: (entrances) => startBench(context.view, entrances),
-  stopBench: () => stopBench(context.view)
+  stopBench: () => stopBench(context.view),
+  midiGetProject: () => context.midiUi?.getProject?.() || null,
+  midiGetRuntimeConfig: () => context.midiUi?.getMidiConfig?.() || null,
+  midiDispatchProjectIntent: (intent) => context.midiUi?.dispatchProjectIntent?.(intent) || null,
+  midiResetProject: (templateId) => context.midiUi?.resetProject?.(templateId) || null,
+  midiExportProject: (options) => context.midiUi?.exportProject?.(options) || null,
+  midiImportProject: (payload) => context.midiUi?.importProject?.(payload) || null,
+  midiSaveProjectTemplate: (options) => context.midiUi?.saveProjectTemplate?.(options) || null,
+  midiGetProjectTemplates: () => context.midiUi?.getProjectTemplates?.() || [],
+  midiGetUiMetrics: () => context.midiUi?.getUiMetrics?.() || null,
+  midiStartLearn: () => context.midiUi?.startLearn?.() || false,
+  midiConfirmLearn: () => context.midiUi?.confirmLearn?.() || false,
+  midiCancelLearn: () => context.midiUi?.cancelLearn?.() || false,
+  midiCaptureLearnNote: (note, velocity, channel) => context.midiUi?.captureLearnNote?.(note, velocity, channel) || false,
+  midiStartRecording: () => context.midiUi?.startRecording?.() || false,
+  midiCommitRecording: () => context.midiUi?.commitRecording?.() || false,
+  midiCancelRecording: () => context.midiUi?.cancelRecording?.() || false,
+  midiCaptureRecordMessage: (message) => context.midiUi?.captureRecordMessage?.(message) || false,
+  midiAudition: (request) => context.midiUi?.audition?.(request) || false
 });
-
-const installE2EHarness = ({ view, editorUi } = {}) => {
+const installE2EHarness = ({ view, editorUi, midiUi, procgenController } = {}) => {
   if (!isE2EEnabled()) return null;
-  const root = typeof globalThis !== 'undefined' ? globalThis : window;
+  const root = getRuntimeDependency('window', null) || {};
   if (root.__E2E__ && typeof root.__E2E__._setContext === 'function') {
-    root.__E2E__._setContext({ view, editorUi });
+    root.__E2E__._setContext({ view, editorUi, midiUi, procgenController });
     return root.__E2E__;
   }
-  const context = { view: view || null, editorUi: editorUi || null };
+  const context = {
+    view: view || null,
+    editorUi: editorUi || null,
+    midiUi: midiUi || null,
+    procgenController: procgenController || null
+  };
   const api = createE2EApi(context);
   root.__E2E__ = api;
   return api;
 };
-
 export { installE2EHarness, isE2EEnabled };
diff --git a/js/app/editor-ui/EditorLevelIoUi.js b/js/app/editor-ui/EditorLevelIoUi.js
new file mode 100644
index 00000000..4e6ca7b2
--- /dev/null
+++ b/js/app/editor-ui/EditorLevelIoUi.js
@@ -0,0 +1,373 @@
+import {
+  BinaryReader,
+  EDITOR_SHORTCUT_SECTIONS,
+  EditorAssetCache,
+  EditorController,
+  EditorHistory,
+  EditorKeybindings,
+  EditorPreviewCache,
+  HISTORY_COALESCE_WINDOW_MS,
+  LevelReader,
+  LevelWriter,
+  MAX_BRUSH_SIZE,
+  MAX_HISTORY,
+  MAX_HISTORY_BYTES,
+  PALETTE_PREVIEW_BATCH_SIZE,
+  PALETTE_SEARCH_DEBOUNCE_MS,
+  ShortcutOverlay,
+  createClassicLevelData,
+  createEditorLevelFromClassic,
+  downloadBinaryFile,
+  downloadTextFile,
+  ensureLevelEntryUids,
+  formatRotation,
+  formatValue,
+  getEntryBounds,
+  getRuntimeDependency,
+  getStyle,
+  getStyleNames,
+  listSavedLevels,
+  loadSavedLevel,
+  normalizeRotation,
+  normalizeText,
+  parseNumber,
+  readArrayBufferFile,
+  readTextFile,
+  sanitizeFileName,
+  saveLevel,
+  validateLevel
+} from './EditorUiControllerShared.js';
+import {
+  getClassicExportLossSummary
+} from './editorClassicSubsetContract.js';
+const editorLevelIoUiMethods = {
+  _refreshSavedList(selectedId = this._currentSavedId) {
+    if (!this.el.savedSelect) return;
+    const entries = listSavedLevels();
+    this.el.savedSelect.innerHTML = '';
+    const placeholder = this.document.createElement('option');
+    placeholder.value = '';
+    placeholder.textContent = 'Saved levels';
+    this.el.savedSelect.appendChild(placeholder);
+    for (const entry of entries) {
+      const opt = this.document.createElement('option');
+      opt.value = entry.id;
+      opt.textContent = entry.name;
+      this.el.savedSelect.appendChild(opt);
+    }
+    this.el.savedSelect.value = selectedId || '';
+  },
+
+  _saveCurrentLevel() {
+    if (!this.view?.editorSession?.level) return;
+    const defaultName = this.view.getEditorLevelTitle?.() || 'Untitled';
+    const prompt = this.window?.prompt;
+    if (typeof prompt !== 'function') return;
+    const name = normalizeText(prompt('Save level as', defaultName));
+    if (!name) return;
+    const text = this.view.getEditorLevelText();
+    const id = saveLevel(undefined, {
+      id: this._currentSavedId || undefined,
+      name,
+      text
+    });
+    if (!id) return;
+    this._currentSavedId = id;
+    this._refreshSavedList(id);
+    this._setDirty(false);
+  },
+
+  async _createNewLevel() {
+    if (!this.view) return;
+    const token = this._nextAsyncToken();
+    this._clearTransientIssue?.('import');
+    this._clearSolvabilityCheck?.();
+    this.view.createBlankEditorLevel({ render: false });
+    this.session = this.view.editorSession || this.session;
+    this.controller.session = this.session;
+    ensureLevelEntryUids(this.session?.level);
+    this.controller.resetHistory('New');
+    this._setDirty(false);
+    this._refreshUndoRedo();
+    this._needsDefaultEntrances = true;
+    this._currentSavedId = '';
+    this._refreshSavedList('');
+    await this._reloadAssets(token);
+    if (!this._isAsyncCurrent(token)) return;
+    await this._refreshStyleOptions();
+    this._refreshHeaderFields();
+    this._refreshSelection(null);
+    this._refreshValidation();
+    await this._refreshPreview('New', { preserveView: false, token });
+  },
+
+  _bindSelectionActions() {
+    const bind = (el, handler, label = 'Selection') => {
+      if (!el) return;
+      this._addDomListener(el, 'click', () => {
+        if (handler()) {
+          this._refreshAfterEdit(label);
+        }
+      });
+    };
+    const parsePieceIds = (value) => {
+      const text = normalizeText(value);
+      if (!text) return [];
+      return text
+        .split(/[,\s]+/)
+        .map(token => parseNumber(token))
+        .filter(id => Number.isFinite(id));
+    };
+
+    bind(this.el.selectionBringFront, () => this.controller.bringSelectionToFront(), 'Reorder');
+    bind(this.el.selectionMoveForward, () => this.controller.moveSelectionForward(), 'Reorder');
+    bind(this.el.selectionMoveBackward, () => this.controller.moveSelectionBackward(), 'Reorder');
+    bind(this.el.selectionSendBack, () => this.controller.sendSelectionToBack(), 'Reorder');
+
+    bind(this.el.selectionAlignLeft, () => this.controller.alignSelection('x', 'min'), 'Align');
+    bind(this.el.selectionAlignCenter, () => this.controller.alignSelection('x', 'center'), 'Align');
+    bind(this.el.selectionAlignRight, () => this.controller.alignSelection('x', 'max'), 'Align');
+    bind(this.el.selectionAlignTop, () => this.controller.alignSelection('y', 'min'), 'Align');
+    bind(this.el.selectionAlignMiddle, () => this.controller.alignSelection('y', 'center'), 'Align');
+    bind(this.el.selectionAlignBottom, () => this.controller.alignSelection('y', 'max'), 'Align');
+    bind(this.el.selectionDistributeX, () => this.controller.distributeSelection('x'), 'Distribute');
+    bind(this.el.selectionDistributeY, () => this.controller.distributeSelection('y'), 'Distribute');
+
+    bind(this.el.selectionReplaceApply, () => {
+      const pieceId = parseNumber(this.el.selectionReplacePiece?.value);
+      return this.controller.replaceSelectionPiece(pieceId);
+    }, 'Replace');
+
+    bind(this.el.selectionRandomApply, () => {
+      const pieceIds = parsePieceIds(this.el.selectionRandomPieces?.value);
+      const seed = parseNumber(this.el.selectionRandomSeed?.value);
+      const requireSameSize = !!this.el.selectionRandomSameSize?.checked;
+      return this.controller.randomizeSelectionPieces(pieceIds, {
+        requireSameSize,
+        seed
+      });
+    }, 'Randomize');
+
+    bind(this.el.selectionTransformApply, () => {
+      const scaleX = parseNumber(this.el.selectionScaleX?.value);
+      const scaleY = parseNumber(this.el.selectionScaleY?.value);
+      return this.controller.transformSelectionGroup({
+        scaleX: Number.isFinite(scaleX) ? scaleX : 1,
+        scaleY: Number.isFinite(scaleY) ? scaleY : 1
+      });
+    }, 'Transform');
+  },
+
+  _bindUndoRedo() {
+    if (this.el.undo) {
+      this._addDomListener(this.el.undo, 'click', () => {
+        if (this.controller.undo()) {
+          this._refreshAfterEdit('Undo');
+        }
+      });
+    }
+    if (this.el.redo) {
+      this._addDomListener(this.el.redo, 'click', () => {
+        if (this.controller.redo()) {
+          this._refreshAfterEdit('Redo');
+        }
+      });
+    }
+  },
+
+  _ensureDefaultEntrancesExits() {
+    if (!this._needsDefaultEntrances) return;
+    if (!this.assets) return;
+    const viewRect = this.view?.stage?.getGameViewRect?.() || null;
+    const added = this.controller.ensureDefaultEntrancesExits({
+      entranceId: this.assets?.entranceId,
+      exitId: this.assets?.exitId,
+      viewRect
+    });
+    if (added) {
+      this._refreshSelection(null);
+      this._refreshValidation();
+    }
+    if (this.assets?.entranceId != null || this.assets?.exitId != null) {
+      this._needsDefaultEntrances = false;
+    }
+  },
+
+  _exportCurrentLevel() {
+    this._refreshValidation();
+    if (this._hasErrors) {
+      this.window?.alert?.('Fix validation errors before exporting.');
+      return;
+    }
+    const text = this.view.getEditorLevelText();
+    const title = this.view.getEditorLevelTitle();
+    const filename = `${sanitizeFileName(title)}.nxlv`;
+    downloadTextFile(this.document, text, filename);
+  },
+
+  _exportCurrentLevelClassic() {
+    this._refreshValidation();
+    if (this._hasErrors) {
+      this.window?.alert?.('Fix validation errors before exporting.');
+      return;
+    }
+    if (!this.session?.level) return;
+    const loss = getClassicExportLossSummary(this.session.level);
+    const classic = createClassicLevelData(this.session.level);
+    if (!classic?.levelReader) return;
+    const writer = new LevelWriter();
+    const payload = {
+      levelProperties: classic.levelReader.levelProperties,
+      screenPositionX: classic.levelReader.screenPositionX,
+      graphicSet1: classic.levelReader.graphicSet1,
+      graphicSet2: classic.levelReader.graphicSet2,
+      isSuperLemming: classic.levelReader.isSuperLemming,
+      objects: classic.levelReader.objects,
+      terrains: classic.levelReader.terrains,
+      steel: classic.levelReader.steel
+    };
+    const bytes = writer.write(payload);
+    const title = this.view.getEditorLevelTitle();
+    const filename = `${sanitizeFileName(title)}.lvl`;
+    downloadBinaryFile(this.document, bytes, filename);
+    this._updateStatus(loss.hasLoss ? `Export LVL lossy: ${loss.summary}` : 'Export LVL');
+  },
+
+  _loadLevelFromText(text, options = {}) {
+    if (!this.view) return;
+    const token = Number.isFinite(options.token) ? options.token : this._nextAsyncToken();
+    let level = null;
+    try {
+      level = this.view.loadEditorLevelFromText(text, { render: false });
+    } catch (error) {
+      this._reportImportFailure?.('NXLV', error);
+      return;
+    }
+    if (!level) {
+      this._reportImportFailure?.('NXLV', 'No level data was loaded.');
+      return;
+    }
+    this._clearTransientIssue?.('import');
+    this._clearSolvabilityCheck?.();
+    this.session = this.view.editorSession;
+    this.controller.session = this.session;
+    ensureLevelEntryUids(this.session?.level);
+    this.controller.clearSelection();
+    this._reloadAssets(token).then(async () => {
+      if (!this._isAsyncCurrent(token)) return;
+      this.controller.resetHistory('Import');
+      this._setDirty(false);
+      this._refreshUndoRedo();
+      this._refreshHeaderFields(level);
+      this._refreshSelection(null);
+      this._refreshValidation();
+      if (options.resetSaved) this._refreshSavedList('');
+      await this._refreshPreview('Import', { preserveView: false, token });
+    });
+  },
+
+  _loadLevelFromClassic(levelReader, options = {}) {
+    if (!this.view) return;
+    const token = Number.isFinite(options.token) ? options.token : this._nextAsyncToken();
+    const session = this.view.ensureEditorSession?.() || this.session;
+    let editorLevel = null;
+    try {
+      editorLevel = createEditorLevelFromClassic(levelReader);
+    } catch (error) {
+      this._reportImportFailure?.('LVL', error);
+      return;
+    }
+    if (!editorLevel) {
+      this._reportImportFailure?.('LVL', 'No classic level data was loaded.');
+      return;
+    }
+    this._clearTransientIssue?.('import');
+    this._clearSolvabilityCheck?.();
+    session.level = editorLevel;
+    this.session = session;
+    this.controller.session = this.session;
+    ensureLevelEntryUids(this.session?.level);
+    this.controller.clearSelection();
+    this._reloadAssets(token).then(async () => {
+      if (!this._isAsyncCurrent(token)) return;
+      this.controller.resetHistory('Import LVL');
+      this._setDirty(false);
+      this._refreshUndoRedo();
+      this._refreshHeaderFields(editorLevel);
+      this._refreshSelection(null);
+      this._refreshValidation();
+      if (options.resetSaved) this._refreshSavedList('');
+      await this._refreshPreview('Import LVL', { preserveView: false, token });
+    });
+  },
+
+  async _reloadAssets(token = this._asyncToken) {
+    const config = this.view?.gameResources?.config
+        || await this.view?.gameFactory?.getConfig?.(this.view?.gameType);
+    if (!this._isAsyncCurrent(token)) return null;
+    const styleName = this.session?.level?.getHeader?.('STYLE');
+    const assets = await this.assetCache.loadStyleAssets(
+      styleName,
+      config,
+      this.view?.gameFactory?.fileProvider
+    );
+    if (!this._isAsyncCurrent(token)) return null;
+    this.assets = assets;
+    if (this.previewCache?.invalidateTypeIds) {
+      this.previewCache.invalidateTypeIds(
+        'terrain',
+        this.assets?.terrain?.map(entry => Number(entry?.id))
+      );
+      const gadgetIds = this.assets?.gadgets?.map(entry => Number(entry?.id));
+      this.previewCache.invalidateTypeIds('gadget', gadgetIds);
+      // Remove older trigger-scoped cache keys after hard-cutover to gadget previews.
+      this.previewCache.invalidateTypeIds('trigger', gadgetIds);
+    }
+    this.controller.setAssets(this.assets);
+    this._refreshPalettes();
+    await this._refreshStyleOptions();
+  },
+
+  async _refreshPreview(label, options = {}) {
+    if (!this.view) return;
+    const token = Number.isFinite(options.token) ? options.token : this._asyncToken;
+    if (!this._isAsyncCurrent(token)) return;
+    const preserveView = options.preserveView !== false;
+    if (this._previewInFlight) {
+      this._previewQueued = true;
+      const nextLabel = label || 'Preview';
+      if (this._previewQueuedLabel && this._previewQueuedLabel !== nextLabel) {
+        this._previewQueuedLabel = 'Preview';
+      } else {
+        this._previewQueuedLabel = nextLabel;
+      }
+      const queuedPreserve = this._previewQueuedOptions?.preserveView ?? true;
+      this._previewQueuedOptions = { preserveView: queuedPreserve && preserveView };
+      return;
+    }
+    this._previewInFlight = true;
+    try {
+      await this.view.loadEditorPreviewLevel({
+        suspend: !this._playtest,
+        preserveView
+      });
+      if (!this._isAsyncCurrent(token)) return;
+      this.view.setEditorPlaytest(this._playtest);
+      this._ensureDefaultEntrancesExits();
+      this._drawSelectionOverlay();
+      this._refreshValidation();
+      this._updateStatus(label || 'Preview');
+    } finally {
+      this._previewInFlight = false;
+      if (this._previewQueued) {
+        const nextLabel = this._previewQueuedLabel || 'Queued';
+        const nextOptions = this._previewQueuedOptions || {};
+        this._previewQueued = false;
+        this._previewQueuedLabel = null;
+        this._previewQueuedOptions = null;
+        this._refreshPreview(nextLabel, nextOptions);
+      }
+    }
+  }
+};
+export { editorLevelIoUiMethods };
diff --git a/js/app/editor-ui/EditorPaletteUi.js b/js/app/editor-ui/EditorPaletteUi.js
new file mode 100644
index 00000000..ad3ac2b5
--- /dev/null
+++ b/js/app/editor-ui/EditorPaletteUi.js
@@ -0,0 +1,439 @@
+import {
+  BinaryReader,
+  EDITOR_SHORTCUT_SECTIONS,
+  EditorAssetCache,
+  EditorController,
+  EditorHistory,
+  EditorKeybindings,
+  EditorPreviewCache,
+  HISTORY_COALESCE_WINDOW_MS,
+  LevelReader,
+  LevelWriter,
+  MAX_BRUSH_SIZE,
+  MAX_HISTORY,
+  MAX_HISTORY_BYTES,
+  PALETTE_PREVIEW_BATCH_SIZE,
+  PALETTE_SEARCH_DEBOUNCE_MS,
+  ShortcutOverlay,
+  createClassicLevelData,
+  createEditorLevelFromClassic,
+  downloadBinaryFile,
+  downloadTextFile,
+  ensureLevelEntryUids,
+  formatRotation,
+  formatValue,
+  getEntryBounds,
+  getRuntimeDependency,
+  getStyle,
+  getStyleNames,
+  listSavedLevels,
+  loadSavedLevel,
+  normalizeRotation,
+  normalizeText,
+  parseNumber,
+  readArrayBufferFile,
+  readTextFile,
+  sanitizeFileName,
+  saveLevel,
+  validateLevel
+} from './EditorUiControllerShared.js';
+
+const MAX_RECENT_PALETTE_ENTRIES = 8;
+
+const editorPaletteUiMethods = {
+  _setPaletteTab(tab) {
+    this._activeTab = tab;
+    const tabs = this.el.paletteTabs?.querySelectorAll?.('button') || [];
+    tabs.forEach(button => {
+      const isActive = button.dataset?.tab === tab;
+      button.classList.toggle('active', isActive);
+      button.setAttribute?.('aria-pressed', isActive ? 'true' : 'false');
+    });
+    if (this.el.paletteTerrain) this.el.paletteTerrain.hidden = tab !== 'terrain';
+    if (this.el.paletteGadgets) this.el.paletteGadgets.hidden = tab !== 'gadgets';
+    if (this.el.paletteTriggers) this.el.paletteTriggers.hidden = tab !== 'triggers';
+    this._schedulePalettePreviewHydration();
+  },
+
+  _syncPaletteTabForTool(tool) {
+    if (tool === 'terrain') {
+      this._setPaletteTab('terrain');
+    } else if (tool === 'gadget') {
+      this._setPaletteTab('gadgets');
+    } else if (tool === 'trigger' || tool === 'midi-flag') {
+      this._setPaletteTab('triggers');
+    }
+  },
+
+  _refreshPalettes() {
+    if (!this.assets) return;
+    this._cancelPalettePreviewHydration();
+    this._renderPaletteList(this.el.paletteTerrain, this.assets.terrain, 'terrain');
+    this._renderPaletteList(this.el.paletteGadgets, this.assets.gadgets, 'gadget');
+    this._renderPaletteList(this.el.paletteTriggers, this.assets.triggers, 'trigger');
+    this._pruneRecentPaletteEntries();
+    this._renderRecentPaletteEntries();
+    this._applyPaletteFilter();
+    this._setPaletteTab(this._activeTab);
+    this._refreshPaletteSelection();
+  },
+
+  _getPaletteLabelText(entry) {
+    const size = `${entry?.width || 0}x${entry?.height || 0}`;
+    const triggerFlag = entry?.triggerEffectId ? ` | T${entry.triggerEffectId}` : '';
+    return `#${entry?.id} ${entry?.name || 'Piece'} (${size})${triggerFlag}`;
+  },
+
+  _selectPaletteEntry(entry, type, options = {}) {
+    const id = Number(entry?.id);
+    if (!Number.isFinite(id)) return;
+    if (type === 'terrain') {
+      this.controller.setSelectedTerrain(id);
+    } else if (type === 'trigger') {
+      this.controller.setSelectedTrigger(id);
+      this.controller.setSelectedGadget(id);
+    } else {
+      this.controller.setSelectedGadget(id);
+    }
+    if (options.recordRecent) {
+      this._recordRecentPaletteEntry(entry, type);
+    }
+    this._refreshPaletteSelection();
+  },
+
+  _getPaletteRecord(type, id) {
+    const entries = this._paletteEntries?.[type] || [];
+    return entries.find(record => Number(record.id) === Number(id)) || null;
+  },
+
+  _recordRecentPaletteEntry(entry, type) {
+    const id = Number(entry?.id);
+    if (!Number.isFinite(id)) return;
+    const next = {
+      id,
+      type,
+      label: this._getPaletteLabelText(entry),
+      entry
+    };
+    const existing = this._recentPaletteEntries || [];
+    this._recentPaletteEntries = [
+      next,
+      ...existing.filter(item => !(item.type === type && Number(item.id) === id))
+    ].slice(0, MAX_RECENT_PALETTE_ENTRIES);
+    this._renderRecentPaletteEntries();
+  },
+
+  _pruneRecentPaletteEntries() {
+    const available = new Set();
+    for (const type of ['terrain', 'gadget', 'trigger']) {
+      for (const record of this._paletteEntries?.[type] || []) {
+        available.add(`${type}:${record.id}`);
+      }
+    }
+    this._recentPaletteEntries = (this._recentPaletteEntries || [])
+      .filter(item => available.has(`${item.type}:${item.id}`));
+  },
+
+  _renderRecentPaletteEntries() {
+    const container = this.el.paletteRecent;
+    if (!container) return;
+    container.innerHTML = '';
+    const entries = this._recentPaletteEntries || [];
+    container.hidden = entries.length === 0;
+    for (const item of entries) {
+      const button = this.document.createElement('button');
+      button.type = 'button';
+      button.dataset.type = item.type;
+      button.dataset.id = String(item.id);
+      button.textContent = item.type === 'terrain'
+        ? `T#${item.id}`
+        : item.type === 'trigger'
+          ? `Tr#${item.id}`
+          : `O#${item.id}`;
+      button.title = `Select recent ${item.label}`;
+      button.setAttribute('aria-label', button.title);
+      button.addEventListener('click', () => {
+        const record = this._getPaletteRecord(item.type, item.id);
+        this._selectPaletteEntry(record?.entry || item.entry, item.type, { recordRecent: true });
+      });
+      container.appendChild(button);
+    }
+    this._refreshRecentPaletteSelection();
+  },
+
+  _bindPaletteView() {
+    const syncButtons = () => {
+      const isList = this._paletteViewMode === 'list';
+      if (this.el.paletteViewList) {
+        this.el.paletteViewList.classList.toggle('active', isList);
+        this.el.paletteViewList.setAttribute?.('aria-pressed', isList ? 'true' : 'false');
+      }
+      if (this.el.paletteViewGrid) {
+        this.el.paletteViewGrid.classList.toggle('active', !isList);
+        this.el.paletteViewGrid.setAttribute?.('aria-pressed', isList ? 'false' : 'true');
+      }
+    };
+    const setMode = (mode) => {
+      this._paletteViewMode = mode;
+      syncButtons();
+      this._applyPaletteViewMode();
+    };
+    if (this.el.paletteViewList) {
+      this._addDomListener(this.el.paletteViewList, 'click', () => setMode('list'));
+    }
+    if (this.el.paletteViewGrid) {
+      this._addDomListener(this.el.paletteViewGrid, 'click', () => setMode('grid'));
+    }
+    syncButtons();
+    this._applyPaletteViewMode();
+    this._bindPaletteGridZoom();
+  },
+
+  _bindPaletteGridZoom() {
+    const bind = (container) => {
+      if (!container) return;
+      this._addDomListener(container, 'wheel', (event) => {
+        if (!event.ctrlKey || this._paletteViewMode !== 'grid') return;
+        if (!Number.isFinite(event.deltaY) || event.deltaY === 0) return;
+        event.preventDefault();
+        const direction = event.deltaY > 0 ? 1 : -1;
+        this._setPaletteGridColumns(this._paletteGridColumns + direction);
+      }, { passive: false });
+    };
+    bind(this.el.paletteTerrain);
+    bind(this.el.paletteGadgets);
+    bind(this.el.paletteTriggers);
+  },
+
+  _setPaletteGridColumns(count) {
+    const next = Math.min(6, Math.max(2, Math.round(count)));
+    this._paletteGridColumns = next;
+    this._applyPaletteGridColumns();
+  },
+
+  _applyPaletteGridColumns() {
+    const apply = (container) => {
+      if (!container) return;
+      container.style.setProperty('--palette-grid-columns', String(this._paletteGridColumns));
+    };
+    apply(this.el.paletteTerrain);
+    apply(this.el.paletteGadgets);
+    apply(this.el.paletteTriggers);
+  },
+
+  _applyPaletteViewMode() {
+    const useGrid = this._paletteViewMode === 'grid';
+    const setGrid = (container) => {
+      if (!container) return;
+      container.classList.toggle('grid', useGrid);
+    };
+    setGrid(this.el.paletteTerrain);
+    setGrid(this.el.paletteGadgets);
+    setGrid(this.el.paletteTriggers);
+    this._applyPaletteGridColumns();
+  },
+
+  _getPreviewUrl(entry, type) {
+    if (!this.previewCache || !this.assets) return null;
+    const cacheType = type === 'trigger' ? 'gadget' : type;
+    const image = type === 'terrain'
+      ? this.assets.terrainImages?.[entry.id]
+      : this.assets.gadgetImages?.[entry.id];
+    if (!image) return null;
+    return this.previewCache.getPreviewUrl({
+      type: cacheType,
+      id: entry.id,
+      image
+    });
+  },
+
+  _cancelPalettePreviewHydration() {
+    this._palettePreviewToken += 1;
+    this._palettePreviewQueue = [];
+    this._palettePreviewIndex = 0;
+    if (this._palettePreviewTimer) {
+      clearTimeout(this._palettePreviewTimer);
+      this._palettePreviewTimer = null;
+    }
+  },
+
+  _getActivePaletteTypes() {
+    if (this._activeTab === 'gadgets') return ['gadget'];
+    if (this._activeTab === 'triggers') return ['trigger'];
+    return ['terrain'];
+  },
+
+  _schedulePalettePreviewHydration() {
+    const types = this._getActivePaletteTypes();
+    const queue = [];
+    for (const type of types) {
+      const records = this._paletteEntries[type] || [];
+      for (const record of records) {
+        if (record.button.hidden || record.previewLoaded) continue;
+        queue.push(record);
+      }
+    }
+    this._palettePreviewToken += 1;
+    const token = this._palettePreviewToken;
+    this._palettePreviewQueue = queue;
+    this._palettePreviewIndex = 0;
+    if (this._palettePreviewTimer) {
+      clearTimeout(this._palettePreviewTimer);
+      this._palettePreviewTimer = null;
+    }
+    if (!this._palettePreviewQueue.length) {
+      return;
+    }
+    const pump = () => {
+      if (token !== this._palettePreviewToken) return;
+      let remaining = PALETTE_PREVIEW_BATCH_SIZE;
+      while (remaining > 0 && this._palettePreviewIndex < this._palettePreviewQueue.length) {
+        const record = this._palettePreviewQueue[this._palettePreviewIndex];
+        this._palettePreviewIndex += 1;
+        if (!record || record.button.hidden || record.previewLoaded) {
+          continue;
+        }
+        const previewUrl = this._getPreviewUrl(record.entry, record.type);
+        if (previewUrl) {
+          record.previewImg.src = previewUrl;
+          record.previewWrap.classList.remove('empty');
+        } else {
+          record.previewWrap.classList.add('empty');
+        }
+        record.previewLoaded = true;
+        record.previewWrap.classList.remove('pending');
+        remaining -= 1;
+      }
+      if (this._palettePreviewIndex < this._palettePreviewQueue.length) {
+        this._palettePreviewTimer = setTimeout(pump, 0);
+      } else {
+        this._palettePreviewQueue = [];
+        this._palettePreviewIndex = 0;
+        this._palettePreviewTimer = null;
+      }
+    };
+    this._palettePreviewTimer = setTimeout(pump, 0);
+  },
+
+  _applyPaletteFilter() {
+    const term = normalizeText(this.el.paletteSearch?.value || '').toLowerCase();
+    const filterList = (type) => {
+      const entries = this._paletteEntries[type] || [];
+      for (const record of entries) {
+        record.button.hidden = !!(term && !record.searchKey.includes(term));
+      }
+    };
+    filterList('terrain');
+    filterList('gadget');
+    filterList('trigger');
+    this._schedulePalettePreviewHydration();
+  },
+
+  _refreshPaletteSelection() {
+    const setActive = (type, id) => {
+      const entries = this._paletteEntries[type] || [];
+      for (const record of entries) {
+        const match = Number(record.id) === id;
+        record.button.classList.toggle('active', match);
+      }
+    };
+    setActive('terrain', this.controller.selectedTerrainId);
+    setActive('gadget', this.controller.selectedGadgetId);
+    setActive('trigger', this.controller.selectedTriggerId);
+    this._refreshRecentPaletteSelection();
+  },
+
+  _refreshRecentPaletteSelection() {
+    const buttons = this.el.paletteRecent?.querySelectorAll?.('button') || [];
+    buttons.forEach(button => {
+      const type = button.dataset?.type;
+      const id = Number(button.dataset?.id);
+      const selectedId = type === 'terrain'
+        ? this.controller.selectedTerrainId
+        : type === 'trigger'
+          ? this.controller.selectedTriggerId
+          : this.controller.selectedGadgetId;
+      const isActive = Number.isFinite(id) && Number(selectedId) === id;
+      button.classList.toggle('active', isActive);
+      button.setAttribute?.('aria-pressed', isActive ? 'true' : 'false');
+    });
+  },
+
+  _refreshHeaderFields(level = this.session?.level) {
+    if (!level) return;
+    this._suppressHeader = true;
+    if (this.el.headerTitle) this.el.headerTitle.value = formatValue(level.getHeader('TITLE'));
+    if (this.el.headerStyle) this.el.headerStyle.value = formatValue(level.getHeader('STYLE'));
+    if (this.el.headerWidth) this.el.headerWidth.value = formatValue(level.getHeader('WIDTH'));
+    if (this.el.headerHeight) this.el.headerHeight.value = formatValue(level.getHeader('HEIGHT'));
+    if (this.el.headerLemmings) this.el.headerLemmings.value = formatValue(level.getHeader('LEMMINGS'));
+    if (this.el.headerSaveRequirement) this.el.headerSaveRequirement.value = formatValue(level.getHeader('SAVE_REQUIREMENT'));
+    if (this.el.headerTimeLimit) this.el.headerTimeLimit.value = formatValue(level.getHeader('TIME_LIMIT'));
+    if (this.el.headerSpawnInterval) this.el.headerSpawnInterval.value = formatValue(level.getHeader('MAX_SPAWN_INTERVAL'));
+    if (this.el.headerStartX) this.el.headerStartX.value = formatValue(level.getHeader('START_X'));
+    if (this.el.headerStartY) this.el.headerStartY.value = formatValue(level.getHeader('START_Y'));
+    this._suppressHeader = false;
+  },
+
+  async _resolveAvailableStyles() {
+    const config = this.view?.gameResources?.config
+        || await this.view?.gameFactory?.getConfig?.(this.view?.gameType);
+    const pathKey = config?.path || '';
+    if (this._styleAvailability.has(pathKey)) {
+      return this._styleAvailability.get(pathKey);
+    }
+    const styleNames = getStyleNames();
+    const provider = this.view?.gameFactory?.fileProvider;
+    if (!config || !provider?.loadBinary) {
+      this._styleAvailability.set(pathKey, styleNames);
+      return styleNames;
+    }
+    const available = [];
+    for (const name of styleNames) {
+      const style = getStyle(name);
+      const groundSet = Number.isFinite(style?.groundSet) ? style.groundSet | 0 : null;
+      if (groundSet == null) continue;
+      try {
+        await Promise.all([
+          provider.loadBinary(config.path, `VGAGR${groundSet}.DAT`),
+          provider.loadBinary(config.path, `GROUND${groundSet}O.DAT`)
+        ]);
+        available.push(style.name);
+      } catch (e) {
+        // Skip styles missing assets in this pack.
+      }
+    }
+    const list = available.length ? available : styleNames;
+    this._styleAvailability.set(pathKey, list);
+    return list;
+  },
+
+  async _refreshStyleOptions() {
+    const select = this.el.headerStyle;
+    if (!select) return;
+    const toStyleKey = value => normalizeText(value).toLowerCase();
+    const current = normalizeText(this.session?.level?.getHeader?.('STYLE'));
+    const currentKey = toStyleKey(current);
+    const styles = await this._resolveAvailableStyles();
+    const options = styles.slice();
+    const optionKeyToName = new Map();
+    for (const name of options) {
+      optionKeyToName.set(toStyleKey(name), name);
+    }
+    if (current && !optionKeyToName.has(currentKey)) {
+      options.push(current);
+      optionKeyToName.set(currentKey, current);
+    }
+    select.innerHTML = '';
+    for (const name of options) {
+      const opt = this.document.createElement('option');
+      opt.value = name;
+      opt.textContent = name;
+      select.appendChild(opt);
+    }
+    if (current) {
+      select.value = optionKeyToName.get(currentKey) || current;
+    }
+  }
+};
+export { editorPaletteUiMethods };
diff --git a/js/app/editor-ui/EditorSelectionPanel.js b/js/app/editor-ui/EditorSelectionPanel.js
new file mode 100644
index 00000000..4ac1f195
--- /dev/null
+++ b/js/app/editor-ui/EditorSelectionPanel.js
@@ -0,0 +1,703 @@
+import {
+  BinaryReader,
+  EDITOR_SHORTCUT_SECTIONS,
+  EditorAssetCache,
+  EditorController,
+  EditorHistory,
+  EditorKeybindings,
+  EditorPreviewCache,
+  HISTORY_COALESCE_WINDOW_MS,
+  LevelReader,
+  LevelWriter,
+  MAX_BRUSH_SIZE,
+  MAX_HISTORY,
+  MAX_HISTORY_BYTES,
+  PALETTE_PREVIEW_BATCH_SIZE,
+  PALETTE_SEARCH_DEBOUNCE_MS,
+  ShortcutOverlay,
+  createClassicLevelData,
+  createEditorLevelFromClassic,
+  createValidationReport,
+  downloadBinaryFile,
+  downloadTextFile,
+  ensureLevelEntryUids,
+  formatRotation,
+  formatValue,
+  getEntryBounds,
+  getRuntimeDependency,
+  getStyle,
+  getStyleNames,
+  listSavedLevels,
+  loadSavedLevel,
+  normalizeRotation,
+  normalizeText,
+  parseNumber,
+  readArrayBufferFile,
+  readTextFile,
+  sanitizeFileName,
+  saveLevel,
+  checkEditorSolvabilityAdvisory,
+  validateLevel
+} from './EditorUiControllerShared.js';
+import {
+  buildClassicSubsetIssues,
+  getErrorMessage,
+  isDestructiveQuickFix
+} from './editorClassicSubsetContract.js';
+
+const getMultiSelectionCapabilities = (entries = []) => {
+  const types = new Set(entries.map(entry => entry?.type).filter(Boolean));
+  const type = types.size === 1 ? Array.from(types)[0] : null;
+  const isTerrain = type === 'terrain';
+  const isGadget = type === 'gadget';
+  const isSteel = type === 'steel';
+  return {
+    type,
+    x: !!type,
+    y: !!type,
+    width: isSteel,
+    height: isSteel,
+    rotate: isTerrain || isGadget,
+    skill: isGadget,
+    lemmings: isGadget,
+    pairing: isGadget,
+    midiFlag: isGadget,
+    midiFlagId: isGadget,
+    flipH: isTerrain || isGadget,
+    flipV: isTerrain || isGadget,
+    noOverwrite: isTerrain,
+    erase: isTerrain,
+    oneWay: isTerrain
+  };
+};
+
+const setBatchInputState = (input, enabled) => {
+  if (!input) return;
+  input.value = '';
+  input.disabled = !enabled;
+  input.placeholder = enabled ? 'batch' : '';
+};
+
+const setBatchCheckState = (check, enabled) => {
+  if (!check) return;
+  check.checked = false;
+  check.indeterminate = !!enabled;
+  check.disabled = !enabled;
+};
+
+const hasEditorGadgetPiece = (level, pieceId) => {
+  if (!Number.isFinite(pieceId) || !Array.isArray(level?.gadgets)) return false;
+  return level.gadgets.some(entry => Number(entry?.props?.PIECE) === pieceId);
+};
+
+const createAdvisoryWarningKey = warning => [
+  warning?.code || '',
+  warning?.target || '',
+  warning?.message || ''
+].join('|');
+
+const editorSelectionPanelMethods = {
+  _setSelectionFields(data) {
+    this._suppressInspector = true;
+    if (!data) {
+      this._toggleSelectionActions(false);
+      if (this.el.selType) this.el.selType.textContent = 'None';
+      if (this.el.selName) this.el.selName.textContent = '';
+      const inputs = [
+        this.el.selX,
+        this.el.selY,
+        this.el.selWidth,
+        this.el.selHeight,
+        this.el.selRotate,
+        this.el.selSkill,
+        this.el.selLemmings,
+        this.el.selPairing,
+        this.el.selMidiFlagId
+      ];
+      inputs.forEach(input => {
+        if (input) {
+          input.value = '';
+          input.placeholder = '';
+          input.disabled = true;
+        }
+      });
+      const checks = [
+        this.el.selFlipH,
+        this.el.selFlipV,
+        this.el.selMidiFlag,
+        this.el.selNoOverwrite,
+        this.el.selErase,
+        this.el.selOneWay
+      ];
+      checks.forEach(check => {
+        if (check) {
+          check.checked = false;
+          check.indeterminate = false;
+          check.disabled = true;
+        }
+      });
+      if (this.el.deleteSelection) this.el.deleteSelection.disabled = true;
+      this._suppressInspector = false;
+      return;
+    }
+
+    if (data.multi) {
+      const capabilities = getMultiSelectionCapabilities(data.entries || []);
+      this._toggleSelectionActions(true);
+      if (this.el.selType) this.el.selType.textContent = 'Multiple';
+      if (this.el.selName) {
+        const suffix = capabilities.type ? `${capabilities.type} items` : 'mixed items';
+        this.el.selName.textContent = `${data.count} ${suffix}`;
+      }
+      setBatchInputState(this.el.selX, capabilities.x);
+      setBatchInputState(this.el.selY, capabilities.y);
+      setBatchInputState(this.el.selWidth, capabilities.width);
+      setBatchInputState(this.el.selHeight, capabilities.height);
+      setBatchInputState(this.el.selRotate, capabilities.rotate);
+      setBatchInputState(this.el.selSkill, capabilities.skill);
+      setBatchInputState(this.el.selLemmings, capabilities.lemmings);
+      setBatchInputState(this.el.selPairing, capabilities.pairing);
+      setBatchInputState(this.el.selMidiFlagId, capabilities.midiFlagId);
+      setBatchCheckState(this.el.selFlipH, capabilities.flipH);
+      setBatchCheckState(this.el.selFlipV, capabilities.flipV);
+      setBatchCheckState(this.el.selMidiFlag, capabilities.midiFlag);
+      setBatchCheckState(this.el.selNoOverwrite, capabilities.noOverwrite);
+      setBatchCheckState(this.el.selErase, capabilities.erase);
+      setBatchCheckState(this.el.selOneWay, capabilities.oneWay);
+      if (this.el.deleteSelection) this.el.deleteSelection.disabled = false;
+      this._suppressInspector = false;
+      return;
+    }
+
+    this._toggleSelectionActions(true);
+    if (this.el.selType) this.el.selType.textContent = data.type;
+    if (this.el.selName) this.el.selName.textContent = data.name || '';
+
+    const props = data.props || {};
+    const meta = data.meta || null;
+    const isGadget = data.type === 'gadget';
+    const isSteel = data.type === 'steel';
+    const isTerrain = data.type === 'terrain';
+    const supportsResize = isSteel;
+    const widthValue = props.WIDTH ?? (isSteel ? undefined : meta?.width);
+    const heightValue = props.HEIGHT ?? (isSteel ? undefined : meta?.height);
+
+    if (this.el.selX) {
+      this.el.selX.value = formatValue(props.X);
+      this.el.selX.placeholder = '';
+      this.el.selX.disabled = false;
+    }
+    if (this.el.selY) {
+      this.el.selY.value = formatValue(props.Y);
+      this.el.selY.placeholder = '';
+      this.el.selY.disabled = false;
+    }
+    if (this.el.selWidth) {
+      this.el.selWidth.value = formatValue(widthValue);
+      this.el.selWidth.placeholder = '';
+      this.el.selWidth.disabled = !supportsResize;
+    }
+    if (this.el.selHeight) {
+      this.el.selHeight.value = formatValue(heightValue);
+      this.el.selHeight.placeholder = '';
+      this.el.selHeight.disabled = !supportsResize;
+    }
+    if (this.el.selRotate) {
+      this.el.selRotate.value = formatRotation(props.ROTATE);
+      this.el.selRotate.placeholder = '';
+      this.el.selRotate.disabled = isSteel;
+    }
+    if (this.el.selSkill) {
+      this.el.selSkill.value = formatValue(props.SKILL);
+      this.el.selSkill.placeholder = '';
+      this.el.selSkill.disabled = !isGadget;
+    }
+    if (this.el.selLemmings) {
+      this.el.selLemmings.value = formatValue(props.LEMMINGS);
+      this.el.selLemmings.placeholder = '';
+      this.el.selLemmings.disabled = !isGadget;
+    }
+    if (this.el.selPairing) {
+      this.el.selPairing.value = formatValue(props.PAIRING);
+      this.el.selPairing.placeholder = '';
+      this.el.selPairing.disabled = !isGadget;
+    }
+    if (this.el.selMidiFlag) {
+      const enabled = !!props.MIDI_FLAG;
+      this.el.selMidiFlag.checked = enabled;
+      this.el.selMidiFlag.indeterminate = false;
+      this.el.selMidiFlag.disabled = !isGadget;
+    }
+    if (this.el.selMidiFlagId) {
+      const flagId = props.MIDI_FLAG_ID;
+      this.el.selMidiFlagId.value = formatValue(flagId);
+      this.el.selMidiFlagId.placeholder = '';
+      const enabled = !!props.MIDI_FLAG;
+      this.el.selMidiFlagId.disabled = !isGadget || !enabled;
+    }
+
+    if (this.el.selFlipH) {
+      this.el.selFlipH.checked = !!props.FLIP_HORIZONTAL;
+      this.el.selFlipH.indeterminate = false;
+      this.el.selFlipH.disabled = isSteel;
+    }
+    if (this.el.selFlipV) {
+      this.el.selFlipV.checked = !!props.FLIP_VERTICAL;
+      this.el.selFlipV.indeterminate = false;
+      this.el.selFlipV.disabled = isSteel;
+    }
+    if (this.el.selNoOverwrite) {
+      this.el.selNoOverwrite.checked = !!props.NO_OVERWRITE;
+      this.el.selNoOverwrite.indeterminate = false;
+      this.el.selNoOverwrite.disabled = isGadget || isSteel;
+    }
+    if (this.el.selErase) {
+      this.el.selErase.checked = !!props.ERASE;
+      this.el.selErase.indeterminate = false;
+      this.el.selErase.disabled = isGadget || isSteel;
+    }
+    if (this.el.selOneWay) {
+      this.el.selOneWay.checked = !!props.ONE_WAY;
+      this.el.selOneWay.indeterminate = false;
+      this.el.selOneWay.disabled = !isTerrain;
+    }
+    if (this.el.deleteSelection) this.el.deleteSelection.disabled = false;
+
+    this._suppressInspector = false;
+  },
+
+  _toggleSelectionActions(visible) {
+    if (this.el.selectionActions) {
+      this.el.selectionActions.hidden = !visible;
+    }
+  },
+
+  _commitSelectionPatch(patch) {
+    const updated = this.controller.updateSelectedProps(patch);
+    if (!updated) return;
+    this.controller.history.pushSnapshot(this.session?.level, 'Edit');
+    this._refreshAfterEdit('Edit');
+  },
+
+  async _syncAfterSelection(label) {
+    if (!this.view) return;
+    const token = this._asyncToken;
+    this._currentSavedId = '';
+    this.session = this.view.editorSession || this.session;
+    this.controller.session = this.session;
+    ensureLevelEntryUids(this.session?.level);
+    this._clearSolvabilityCheck();
+    this.controller.clearSelection();
+    await this._reloadAssets(token);
+    if (!this._isAsyncCurrent(token)) return;
+    this.controller.resetHistory(label || 'Load');
+    this._setDirty(false);
+    this._refreshUndoRedo();
+    this._refreshHeaderFields(this.session?.level);
+    this._refreshSelection(null);
+    this._refreshValidation();
+    this._refreshSavedList('');
+    this._drawSelectionOverlay();
+    this._updateStatus(label || 'Load');
+  },
+
+  _refreshAfterEdit(label) {
+    this._clearTransientIssue?.('import');
+    this._clearSolvabilityCheck();
+    this._refreshValidation();
+    this._drawSelectionOverlay();
+    this._updateStatus(label || 'Edit');
+    this._setDirty(true);
+    this._refreshUndoRedo();
+  },
+
+  _setDirty(isDirty) {
+    this._dirty = !!isDirty;
+    if (this.el.dirtyStatus) {
+      this.el.dirtyStatus.textContent = this._dirty ? 'Unsaved' : 'Saved';
+      this.el.dirtyStatus.classList.toggle('is-dirty', this._dirty);
+    }
+    if (this.document) {
+      this.document.title = this._dirty ? `${this._baseTitle} *` : this._baseTitle;
+    }
+  },
+
+  _refreshUndoRedo() {
+    const canUndo = !!this.controller?.history?.canUndo?.();
+    const canRedo = !!this.controller?.history?.canRedo?.();
+    if (this.el.undo) this.el.undo.disabled = !canUndo;
+    if (this.el.redo) this.el.redo.disabled = !canRedo;
+  },
+
+  _refreshValidation() {
+    const level = this.session?.level;
+    const issues = [
+      ...validateLevel(level, this.assets || null, {
+        solverAdvisorySource: this.view?.game?.level || null
+      }),
+      ...buildClassicSubsetIssues(level),
+      ...(this._transientIssues || [])
+    ];
+    this._renderIssues(issues);
+  },
+
+  _buildCurrentValidationReport() {
+    const level = this.session?.level;
+    const issues = [
+      ...validateLevel(level, this.assets || null, {
+        solverAdvisorySource: this.view?.game?.level || null
+      }),
+      ...buildClassicSubsetIssues(level),
+      ...(this._transientIssues || [])
+    ];
+    return createValidationReport(level, this.assets || null, {
+      issues,
+      pack: {
+        title: 'Current editor session',
+        levels: level ? [level] : []
+      },
+      assetsByStyle: this.assets?.styleName
+        ? { [this.assets.styleName]: this.assets }
+        : null
+    });
+  },
+
+  _exportValidationReport() {
+    const report = this._buildCurrentValidationReport();
+    const title = this.view?.getEditorLevelTitle?.() || report.level.title || 'level';
+    const filename = `${sanitizeFileName(title)}.validation.json`;
+    downloadTextFile(this.document, JSON.stringify(report, null, 2), filename, 'application/json');
+    this._updateStatus('Validation report');
+  },
+
+  _clearSolvabilityCheck() {
+    this._lastSolvabilityCheck = null;
+    this._renderSolvabilityStatus();
+  },
+
+  _renderSolvabilityStatus(state = this._lastSolvabilityCheck) {
+    if (!this.el.solvabilityStatus) return;
+    const status = state?.status || 'idle';
+    this.el.solvabilityStatus.dataset.status = status;
+    this.el.solvabilityStatus.dataset.warningCount = String(state?.warningCount ?? 0);
+    this.el.solvabilityStatus.textContent = state?.message || 'Solvability not checked';
+  },
+
+  async _waitForPreviewIdle(token) {
+    const win = this.window;
+    for (let i = 0; i < 120; i += 1) {
+      if (!this._previewInFlight && !this._previewQueued) return true;
+      if (!this._isAsyncCurrent(token)) return false;
+      await new Promise(resolve => (win?.setTimeout || setTimeout)(resolve, 16));
+    }
+    return !this._previewInFlight && !this._previewQueued;
+  },
+
+  async _runSolvabilityCheck() {
+    if (this._solvabilityCheckInFlight) return;
+    this._solvabilityCheckInFlight = true;
+    const token = this._asyncToken;
+    if (this.el.solvabilityCheck) this.el.solvabilityCheck.disabled = true;
+    this._lastSolvabilityCheck = {
+      status: 'running',
+      message: 'Solvability: checking preview...',
+      warningCount: 0,
+      warnings: [],
+      budgetUsage: null
+    };
+    this._renderSolvabilityStatus();
+    try {
+      await this._refreshPreview('Solvability', { preserveView: true, token });
+      await this._waitForPreviewIdle(token);
+      if (!this._isAsyncCurrent(token)) return;
+      const editorLevel = this.session?.level || null;
+      const runtimeSource = this.view?.game?.level || null;
+      const source = runtimeSource || editorLevel;
+      if (!source) {
+        this._lastSolvabilityCheck = {
+          status: 'unavailable',
+          message: 'Solvability: no level source available',
+          warningCount: 0,
+          warnings: [],
+          budgetUsage: null
+        };
+      } else {
+        const options = {
+          assets: this.assets,
+          entranceId: this.assets?.entranceId,
+          exitId: this.assets?.exitId
+        };
+        const primaryAdvisory = checkEditorSolvabilityAdvisory(source, options);
+        const editorAdvisory = editorLevel && runtimeSource && runtimeSource !== editorLevel
+          ? checkEditorSolvabilityAdvisory(editorLevel, options)
+          : null;
+        const editorHasEntrance = hasEditorGadgetPiece(editorLevel, this.assets?.entranceId);
+        const editorHasExit = hasEditorGadgetPiece(editorLevel, this.assets?.exitId);
+        const warningKeys = new Set();
+        const warnings = [];
+        const pushWarning = (warning, origin) => {
+          if (origin === 'runtime' &&
+              warning?.code === 'missing-entrance' &&
+              editorHasEntrance) {
+            return;
+          }
+          if (origin === 'runtime' &&
+              warning?.code === 'missing-exit' &&
+              editorHasExit) {
+            return;
+          }
+          const key = createAdvisoryWarningKey(warning);
+          if (warningKeys.has(key)) return;
+          warningKeys.add(key);
+          warnings.push({
+            code: warning.code || null,
+            message: warning.message || '',
+            target: warning.target || null
+          });
+        };
+        for (const warning of editorAdvisory?.warnings || []) {
+          pushWarning(warning, 'editor');
+        }
+        for (const warning of primaryAdvisory.warnings || []) {
+          pushWarning(warning, runtimeSource ? 'runtime' : 'editor');
+        }
+        this._lastSolvabilityCheck = {
+          status: warnings.length ? 'warnings' : 'ok',
+          message: warnings.length
+            ? `Solvability: ${warnings.length} advisory warning${warnings.length === 1 ? '' : 's'}`
+            : 'Solvability: no obvious route warnings',
+          warningCount: warnings.length,
+          warnings,
+          budgetUsage: primaryAdvisory.budgetUsage || editorAdvisory?.budgetUsage || null
+        };
+      }
+      this._renderSolvabilityStatus();
+      this._refreshValidation();
+      this._updateStatus('Solvability');
+    } finally {
+      this._solvabilityCheckInFlight = false;
+      if (this.el.solvabilityCheck) this.el.solvabilityCheck.disabled = false;
+    }
+  },
+
+  _setTransientIssue(id, issue) {
+    if (!id || !issue?.message) return;
+    if (!Array.isArray(this._transientIssues)) this._transientIssues = [];
+    this._transientIssues = this._transientIssues.filter(entry => entry.id !== id);
+    this._transientIssues.push({
+      id,
+      severity: issue.severity || 'error',
+      message: issue.message
+    });
+  },
+
+  _clearTransientIssue(id) {
+    if (!Array.isArray(this._transientIssues)) return;
+    this._transientIssues = this._transientIssues.filter(entry => entry.id !== id);
+  },
+
+  _reportImportFailure(kind, error) {
+    const message = getErrorMessage(error);
+    this._setTransientIssue('import', {
+      severity: 'error',
+      message: `${kind} import failed: ${message}`
+    });
+    this._refreshValidation();
+    this._updateStatus(`${kind} import failed`);
+  },
+
+  _renderIssues(issues) {
+    this._hasErrors = false;
+    const summary = { error: 0, warning: 0, info: 0 };
+    if (!this.el.issuesList) {
+      this._validationSummary = summary;
+      return;
+    }
+    this.el.issuesList.innerHTML = '';
+    for (const issue of issues) {
+      const severity = issue.severity === 'error'
+        ? 'error'
+        : issue.severity === 'warning'
+          ? 'warning'
+          : 'info';
+      const severityLabel = severity.charAt(0).toUpperCase() + severity.slice(1);
+      if (severity === 'error') this._hasErrors = true;
+      summary[severity] += 1;
+      const item = this.document.createElement('div');
+      item.className = `issue-item ${severity}`;
+      item.setAttribute('role', 'listitem');
+      item.setAttribute('data-severity', severity);
+      item.setAttribute('aria-label', `${severityLabel}: ${issue.message}`);
+      const label = this.document.createElement('span');
+      label.className = 'issue-severity';
+      label.textContent = severityLabel;
+      item.appendChild(label);
+      const message = this.document.createElement('div');
+      message.className = 'issue-message';
+      message.textContent = issue.message;
+      item.appendChild(message);
+      if (issue.fix) {
+        const destructive = isDestructiveQuickFix(issue);
+        if (destructive) {
+          item.classList.add('has-destructive-fix');
+          item.setAttribute('data-fix', 'destructive');
+          const note = this.document.createElement('div');
+          note.className = 'issue-note';
+          note.textContent = 'Destructive quick fix: changes or removes level data.';
+          item.appendChild(note);
+        }
+        const button = this.document.createElement('button');
+        button.className = destructive ? 'issue-action destructive' : 'issue-action';
+        button.type = 'button';
+        button.textContent = issue.fixLabel || 'Fix';
+        button.title = issue.fixLabel
+          ? `${destructive ? 'Destructive quick fix' : 'Apply fix'}: ${issue.fixLabel}`
+          : 'Apply automatic fix.';
+        button.addEventListener('click', () => {
+          issue.fix();
+          this.controller.history.pushSnapshot(this.session?.level, 'Fix');
+          this._refreshAfterEdit('Fix');
+          this._refreshPreview('Fix');
+        });
+        item.appendChild(button);
+      }
+      this.el.issuesList.appendChild(item);
+    }
+    this._validationSummary = summary;
+  },
+
+  _updateStatus(label) {
+    if (this.el.cursorStatus) {
+      if (this._cursorPos) {
+        const cx = Math.round(this._cursorPos.x);
+        const cy = Math.round(this._cursorPos.y);
+        this.el.cursorStatus.textContent = `X:${cx} Y:${cy}`;
+      } else {
+        this.el.cursorStatus.textContent = 'X:— Y:—';
+      }
+    }
+    if (!this.el.status) return;
+    const parts = [];
+    if (label) parts.push(label);
+    parts.push(`Tool: ${this.controller.tool}`);
+    const grid = this.controller.snapEnabled
+      ? `Grid ${this.controller.gridSize}`
+      : 'Grid off';
+    parts.push(grid);
+    parts.push(this._playtest ? 'Playtest' : 'Edit');
+    const summary = this._validationSummary || {};
+    if (summary.error) {
+      parts.push(`${summary.error} error${summary.error === 1 ? '' : 's'}`);
+    }
+    if (summary.warning) {
+      parts.push(`${summary.warning} warning${summary.warning === 1 ? '' : 's'}`);
+    }
+    this.el.status.textContent = parts.join(' • ');
+  },
+
+  _drawSelectionOverlay() {
+    if (!this.view?.game || !this.view.stage) return;
+    this.view.game.render();
+    const stage = this.view.stage;
+    const baseDisplay = stage.getGameDisplay();
+    const overlayDisplay = stage.getGameOverlayDisplay?.() || null;
+    const display = overlayDisplay || baseDisplay;
+    const selectedEntries = this.controller.getSelectedEntries();
+    const marquee = this.controller.getMarqueeBounds();
+    const steelEntries = this.session?.level?.steel;
+    const hasMarquee = !!marquee;
+    const hasSteelOverlay = !!display?.drawStippleRect && Array.isArray(steelEntries) && steelEntries.length > 0;
+    const hasSelectionOverlay = selectedEntries.length > 0;
+    const hasOverlay = hasMarquee || hasSteelOverlay || hasSelectionOverlay;
+    if (overlayDisplay && (hasOverlay || this._selectionOverlayVisible)) {
+      overlayDisplay.clear(0x00000000);
+    }
+    if (marquee) {
+      this._antsOffset = (this._antsOffset + 1) % 12;
+      display.drawMarchingAntRect(
+        marquee.x,
+        marquee.y,
+        marquee.width,
+        marquee.height,
+        3,
+        this._antsOffset,
+        0xFFFFFFFF,
+        0x00000000
+      );
+    }
+    if (display?.drawStippleRect && Array.isArray(steelEntries)) {
+      const gridSize = 16;
+      for (const entry of steelEntries) {
+        const bounds = getEntryBounds(entry, null);
+        display.drawStippleRect(
+          bounds.x,
+          bounds.y,
+          bounds.width,
+          bounds.height,
+          0,
+          180,
+          180
+        );
+        for (let x = bounds.x; x <= bounds.x + bounds.width; x += gridSize) {
+          display.drawStippleRect(x, bounds.y, 0, bounds.height, 0, 255, 255);
+        }
+        for (let y = bounds.y; y <= bounds.y + bounds.height; y += gridSize) {
+          display.drawStippleRect(bounds.x, y, bounds.width, 0, 0, 255, 255);
+        }
+      }
+    }
+    for (const selected of selectedEntries) {
+      const meta = selected.type === 'steel'
+        ? null
+        : selected.type === 'gadget'
+          ? this.assets?.gadgetById?.get?.(selected.entry?.props?.PIECE)
+          : this.assets?.terrainById?.get?.(selected.entry?.props?.PIECE);
+      const bounds = getEntryBounds(selected.entry, meta);
+      display.drawDashedRect(bounds.x, bounds.y, bounds.width, bounds.height, 210, 106, 60, 3);
+    }
+    if (selectedEntries.length === 1 && this.controller.canResizeSelection?.()) {
+      const selected = selectedEntries[0];
+      const meta = selected.type === 'steel'
+        ? null
+        : selected.type === 'gadget'
+          ? this.assets?.gadgetById?.get?.(selected.entry?.props?.PIECE)
+          : this.assets?.terrainById?.get?.(selected.entry?.props?.PIECE);
+      const bounds = getEntryBounds(selected.entry, meta);
+      const handleSize = this.controller.getHandleSize();
+      const half = Math.max(1, Math.floor(handleSize / 2));
+      const midX = bounds.x + Math.round(bounds.width / 2);
+      const midY = bounds.y + Math.round(bounds.height / 2);
+      const handles = [
+        [bounds.x, bounds.y],
+        [midX, bounds.y],
+        [bounds.x + bounds.width, bounds.y],
+        [bounds.x + bounds.width, midY],
+        [bounds.x + bounds.width, bounds.y + bounds.height],
+        [midX, bounds.y + bounds.height],
+        [bounds.x, bounds.y + bounds.height],
+        [bounds.x, midY]
+      ];
+      for (const [hx, hy] of handles) {
+        display.drawRect(hx - half, hy - half, handleSize - 1, handleSize - 1, 255, 255, 255, true);
+      }
+    }
+    if (overlayDisplay) {
+      this._selectionOverlayVisible = hasOverlay;
+      stage.setGameOverlayVisible?.(hasOverlay);
+    } else {
+      this._selectionOverlayVisible = false;
+    }
+    stage.redraw();
+  },
+
+  _togglePlaytest() {
+    this._playtest = !this._playtest;
+    this.view?.setEditorPlaytest?.(this._playtest);
+    if (this.el.playtestToggle) {
+      this.el.playtestToggle.classList.toggle('is-active', this._playtest);
+      this.el.playtestToggle.textContent = this._playtest ? 'Playtest On' : 'Playtest';
+    }
+    this._updateStatus('Playtest');
+  }
+};
+export { editorSelectionPanelMethods };
diff --git a/js/app/editor-ui/EditorUiBindingControls.js b/js/app/editor-ui/EditorUiBindingControls.js
new file mode 100644
index 00000000..17a8f14a
--- /dev/null
+++ b/js/app/editor-ui/EditorUiBindingControls.js
@@ -0,0 +1,327 @@
+import {
+  BinaryReader,
+  LevelReader,
+  MAX_BRUSH_SIZE,
+  loadSavedLevel,
+  normalizeRotation,
+  normalizeText,
+  parseNumber,
+  readArrayBufferFile,
+  readTextFile
+} from './EditorUiControllerShared.js';
+
+const reportImportFailure = (ui, kind, error) => {
+  console.error(`${kind} import failed`, error);
+  if (typeof ui?._reportImportFailure === 'function') {
+    ui._reportImportFailure(kind, error);
+  } else {
+    ui?._updateStatus?.(`${kind} import failed`);
+  }
+};
+
+const editorUiBindingControlMethods = {
+  _bindHeaderFields() {
+    /** @type {Array<[string, string, (value: any) => any]>} */
+    const headerMap = [
+      ['headerTitle', 'TITLE', value => normalizeText(value)],
+      ['headerStyle', 'STYLE', value => normalizeText(value)],
+      ['headerWidth', 'WIDTH', value => parseNumber(value)],
+      ['headerHeight', 'HEIGHT', value => parseNumber(value)],
+      ['headerLemmings', 'LEMMINGS', value => parseNumber(value)],
+      ['headerSaveRequirement', 'SAVE_REQUIREMENT', value => parseNumber(value)],
+      ['headerTimeLimit', 'TIME_LIMIT', value => {
+        const text = normalizeText(value);
+        if (!text) return 'INFINITE';
+        if (text.toUpperCase() === 'INFINITE') return 'INFINITE';
+        return parseNumber(text);
+      }],
+      ['headerSpawnInterval', 'MAX_SPAWN_INTERVAL', value => parseNumber(value)],
+      ['headerStartX', 'START_X', value => parseNumber(value)],
+      ['headerStartY', 'START_Y', value => parseNumber(value)]
+    ];
+
+    for (const [key, headerKey, parser] of headerMap) {
+      const el = this.el[key];
+      if (!el) continue;
+      this._addDomListener(el, 'change', async () => {
+        if (this._suppressHeader) return;
+        const parsed = parser(el.value);
+        this.controller.updateHeader(headerKey, parsed);
+        this.controller.history.pushSnapshot(this.session?.level, 'Header');
+        if (headerKey === 'STYLE') {
+          const token = this._nextAsyncToken();
+          await this._reloadAssets(token);
+          if (!this._isAsyncCurrent(token)) return;
+        }
+        this._refreshAfterEdit('Header');
+      });
+    }
+  },
+
+  _bindSelectionFields() {
+    const bindField = (el, handler) => {
+      if (!el) return;
+      this._addDomListener(el, 'change', () => {
+        if (this._suppressInspector) return;
+        handler();
+      });
+    };
+
+    bindField(this.el.selX, () => this._commitSelectionPatch({ X: parseNumber(this.el.selX.value) }));
+    bindField(this.el.selY, () => this._commitSelectionPatch({ Y: parseNumber(this.el.selY.value) }));
+    bindField(this.el.selWidth, () => this._commitSelectionPatch({ WIDTH: parseNumber(this.el.selWidth.value) }));
+    bindField(this.el.selHeight, () => this._commitSelectionPatch({ HEIGHT: parseNumber(this.el.selHeight.value) }));
+    bindField(this.el.selRotate, () => {
+      const snapped = normalizeRotation(this.el.selRotate.value);
+      this._commitSelectionPatch({ ROTATE: snapped });
+      this.el.selRotate.value = snapped == null ? '' : String(snapped);
+    });
+    bindField(this.el.selSkill, () => this._commitSelectionPatch({ SKILL: normalizeText(this.el.selSkill.value) }));
+    bindField(this.el.selLemmings, () => this._commitSelectionPatch({ LEMMINGS: parseNumber(this.el.selLemmings.value) }));
+    bindField(this.el.selPairing, () => this._commitSelectionPatch({ PAIRING: parseNumber(this.el.selPairing.value) }));
+    bindField(this.el.selMidiFlag, () => {
+      const enabled = !!this.el.selMidiFlag.checked;
+      const flagId = parseNumber(this.el.selMidiFlagId?.value);
+      this._commitSelectionPatch({
+        MIDI_FLAG: enabled,
+        MIDI_FLAG_ID: enabled ? flagId : null
+      });
+    });
+    bindField(this.el.selMidiFlagId, () => this._commitSelectionPatch({ MIDI_FLAG_ID: parseNumber(this.el.selMidiFlagId.value) }));
+
+    bindField(this.el.selFlipH, () => this._commitSelectionPatch({ FLIP_HORIZONTAL: !!this.el.selFlipH.checked }));
+    bindField(this.el.selFlipV, () => this._commitSelectionPatch({ FLIP_VERTICAL: !!this.el.selFlipV.checked }));
+    bindField(this.el.selNoOverwrite, () => this._commitSelectionPatch({ NO_OVERWRITE: !!this.el.selNoOverwrite.checked }));
+    bindField(this.el.selErase, () => this._commitSelectionPatch({ ERASE: !!this.el.selErase.checked }));
+    bindField(this.el.selOneWay, () => this._commitSelectionPatch({ ONE_WAY: !!this.el.selOneWay.checked }));
+
+    if (this.el.deleteSelection) {
+      this._addDomListener(this.el.deleteSelection, 'click', () => {
+        if (this.controller.deleteSelected()) {
+          this._refreshAfterEdit('Delete');
+        }
+      });
+    }
+  },
+
+  _bindBrushControls() {
+    if (this.el.snapToggle) {
+      this._addDomListener(this.el.snapToggle, 'change', () => {
+        this.controller.setSnapEnabled(this.el.snapToggle.checked);
+        this._updateStatus();
+      });
+    }
+    if (this.el.gridSize) {
+      this._addDomListener(this.el.gridSize, 'change', () => {
+        const value = parseNumber(this.el.gridSize.value);
+        this.controller.gridSize = value && value > 0 ? value : 1;
+        this._updateStatus();
+      });
+    }
+    if (this.el.brushSize) {
+      this._addDomListener(this.el.brushSize, 'change', () => {
+        const value = parseNumber(this.el.brushSize.value);
+        const next = Number.isFinite(value) ? Math.min(Math.max(value, 1), MAX_BRUSH_SIZE) : 1;
+        this.controller.setBrushSize(next);
+        this.el.brushSize.value = String(next);
+      });
+    }
+    if (this.el.eraseGadgets) {
+      this._addDomListener(this.el.eraseGadgets, 'change', () => {
+        this.controller.setEraseGadgets(this.el.eraseGadgets.checked);
+      });
+    }
+  },
+
+  _bindSavedControls() {
+    if (this.el.newLevel) {
+      this._addDomListener(this.el.newLevel, 'click', () => {
+        this._createNewLevel();
+      });
+    }
+    if (this.el.savedSelect) {
+      this._addDomListener(this.el.savedSelect, 'change', () => {
+        const id = this.el.savedSelect.value;
+        if (!id) return;
+        const text = loadSavedLevel(undefined, id);
+        if (!text) return;
+        this._currentSavedId = id;
+        this._loadLevelFromText(text, { resetSaved: false });
+      });
+    }
+
+    if (this.el.savedSave) {
+      this._addDomListener(this.el.savedSave, 'click', () => {
+        this._saveCurrentLevel();
+      });
+    }
+
+    if (this.el.savedExport) {
+      this._addDomListener(this.el.savedExport, 'click', () => {
+        this._exportCurrentLevel();
+      });
+    }
+
+    if (this.el.savedExportClassic) {
+      this._addDomListener(this.el.savedExportClassic, 'click', () => {
+        this._exportCurrentLevelClassic();
+      });
+    }
+
+    if (this.el.savedImport && this.el.savedImportInput) {
+      this._addDomListener(this.el.savedImport, 'click', () => {
+        this.el.savedImportInput.click();
+      });
+      this._addDomListener(this.el.savedImportInput, 'change', async (event) => {
+        const file = event.target.files?.[0];
+        if (!file) return;
+        const token = this._nextAsyncToken();
+        try {
+          const text = await readTextFile(file);
+          if (!text) throw new Error('Level file is empty.');
+          if (!this._isAsyncCurrent(token)) return;
+          this._currentSavedId = '';
+          this._loadLevelFromText(text, { resetSaved: true, token });
+        } catch (error) {
+          reportImportFailure(this, 'NXLV', error);
+        } finally {
+          event.target.value = '';
+        }
+      });
+    }
+
+    if (this.el.savedImportClassic && this.el.savedImportClassicInput) {
+      this._addDomListener(this.el.savedImportClassic, 'click', () => {
+        this.el.savedImportClassicInput.click();
+      });
+      this._addDomListener(this.el.savedImportClassicInput, 'change', async (event) => {
+        const file = event.target.files?.[0];
+        if (!file) return;
+        const token = this._nextAsyncToken();
+        try {
+          const buffer = await readArrayBufferFile(file);
+          if (!buffer || buffer.byteLength === 0) throw new Error('Classic level file is empty.');
+          if (!this._isAsyncCurrent(token)) return;
+          const binary = new BinaryReader(buffer, 0, undefined, file.name);
+          const levelReader = new LevelReader(binary);
+          this._currentSavedId = '';
+          this._loadLevelFromClassic(levelReader, { resetSaved: true, token });
+        } catch (error) {
+          reportImportFailure(this, 'LVL', error);
+        } finally {
+          event.target.value = '';
+        }
+      });
+    }
+  },
+
+  _bindLevelSelectors() {
+    if (this.el.gameType) {
+      this._addDomListener(this.el.gameType, 'change', async (event) => {
+        const token = this._nextAsyncToken();
+        const value = this.view?.strToNum?.(event.target.value) ?? event.target.value;
+        await this.view?.selectGameType?.(value);
+        if (!this._isAsyncCurrent(token)) return;
+        await this._syncAfterSelection('Load');
+      });
+    }
+    if (this.el.levelGroup) {
+      this._addDomListener(this.el.levelGroup, 'change', async (event) => {
+        const token = this._nextAsyncToken();
+        const value = this.view?.strToNum?.(event.target.value) ?? event.target.value;
+        await this.view?.selectLevelGroup?.(value);
+        if (!this._isAsyncCurrent(token)) return;
+        await this._syncAfterSelection('Load');
+      });
+    }
+    if (this.el.levelIndex) {
+      this._addDomListener(this.el.levelIndex, 'change', async (event) => {
+        const token = this._nextAsyncToken();
+        const value = this.view?.strToNum?.(event.target.value) ?? event.target.value;
+        await this.view?.selectLevel?.(value);
+        if (!this._isAsyncCurrent(token)) return;
+        await this._syncAfterSelection('Load');
+      });
+    }
+  },
+
+  _bindPlaytest() {
+    if (!this.el.playtestToggle) return;
+    this._addDomListener(this.el.playtestToggle, 'click', () => {
+      this._togglePlaytest();
+    });
+  },
+
+  _bindValidationControls() {
+    if (this.el.solvabilityCheck) {
+      this._addDomListener(this.el.solvabilityCheck, 'click', () => {
+        this._runSolvabilityCheck?.();
+      });
+    }
+    if (this.el.validationReportExport) {
+      this._addDomListener(this.el.validationReportExport, 'click', () => {
+        this._exportValidationReport?.();
+      });
+    }
+  },
+
+  _bindCanvasInput() {
+    const display = this.view?.stage?.getGameDisplay?.();
+    if (!display) return;
+    this._addDisplayListener(display.onMouseDown, pos => {
+      this._clearActiveInputFocus();
+      if (this._playtest) return;
+      this._pointerDown = true;
+      this.controller.handlePointerDown(pos, 0, { shiftKey: this._shiftKey, altKey: this._altKey });
+      this._updateCursor(pos);
+    });
+    this._addDisplayListener(display.onMouseRightDown, pos => {
+      this._clearActiveInputFocus();
+      if (this._playtest) return;
+      this._pointerDown = false;
+      this.controller.handlePointerDown(pos, 2, { shiftKey: this._shiftKey, altKey: this._altKey });
+      this._updateCursor(pos);
+    });
+    this._addDisplayListener(display.onMouseUp, () => {
+      if (this._playtest) return;
+      this._pointerDown = false;
+      this.controller.handlePointerUp();
+      this._refreshAfterEdit('Pointer');
+    });
+    this._addDisplayListener(display.onMouseRightUp, () => {
+      if (this._playtest) return;
+      this.controller.handlePointerUp();
+      this._refreshAfterEdit('Pointer');
+    });
+    this._addDisplayListener(display.onMouseMove, pos => {
+      if (this._playtest) return;
+      this.controller.handlePointerMove(pos, { isDown: this._pointerDown });
+      this._updateCursor(pos);
+    });
+  },
+
+  _clearActiveInputFocus() {
+    const doc = this.document;
+    const active = doc?.activeElement;
+    if (!active) return;
+    const tag = active.tagName;
+    if (active.isContentEditable ||
+          tag === 'INPUT' ||
+          tag === 'SELECT' ||
+          tag === 'TEXTAREA') {
+      active.blur?.();
+      if (doc?.body) {
+        doc.body.tabIndex = -1;
+        doc.body.focus?.({ preventScroll: true });
+      }
+    }
+  },
+
+  _updateCursor(pos) {
+    if (!pos) return;
+    this._cursorPos = { x: pos.x, y: pos.y };
+    this._updateStatus();
+  }
+};
+
+export { editorUiBindingControlMethods };
diff --git a/js/app/editor-ui/EditorUiBindingLifecycle.js b/js/app/editor-ui/EditorUiBindingLifecycle.js
new file mode 100644
index 00000000..f6e8ca28
--- /dev/null
+++ b/js/app/editor-ui/EditorUiBindingLifecycle.js
@@ -0,0 +1,332 @@
+import {
+  EDITOR_SHORTCUT_SECTIONS,
+  EditorKeybindings,
+  ShortcutOverlay,
+  ensureLevelEntryUids
+} from './EditorUiControllerShared.js';
+
+const editorUiBindingLifecycleMethods = {
+  async init() {
+    if (this._disposed) return;
+    if (!this.session?.level) {
+      this.view?.createBlankEditorLevel({ render: false });
+      this.session = this.view?.editorSession || this.session;
+      this.controller.session = this.session;
+      this._needsDefaultEntrances = true;
+    }
+    ensureLevelEntryUids(this.session?.level);
+    const token = this._nextAsyncToken();
+    await this._reloadAssets(token);
+    if (!this._isAsyncCurrent(token)) return;
+    this.controller.resetHistory('Init');
+    this._setDirty(false);
+    this._refreshUndoRedo();
+    this._refreshHeaderFields();
+    this._refreshSelection(null);
+    this._refreshValidation();
+    this._refreshSavedList();
+    this._bindEvents();
+    await this._refreshPreview('Init', { preserveView: false, token });
+  },
+
+  _bindElements() {
+    const get = id => this.document.getElementById(id);
+    this.el = {
+      gameType: get('editorGameTypeSelect'),
+      levelGroup: get('editorLevelGroupSelect'),
+      levelIndex: get('editorLevelIndexSelect'),
+      savedSelect: get('editorSavedSelect'),
+      newLevel: get('editorNewLevel'),
+      savedSave: get('editorSavedSave'),
+      undo: get('editorUndo'),
+      redo: get('editorRedo'),
+      dirtyStatus: get('editorDirtyStatus'),
+      savedExport: get('editorSavedExport'),
+      savedExportClassic: get('editorSavedExportClassic'),
+      savedImport: get('editorSavedImport'),
+      savedImportClassic: get('editorSavedImportClassic'),
+      savedImportInput: get('editorSavedImportInput'),
+      savedImportClassicInput: get('editorSavedImportClassicInput'),
+      playtestToggle: get('editorPlaytestToggle'),
+      solvabilityCheck: get('editorSolvabilityCheck'),
+      validationReportExport: get('editorValidationReportExport'),
+      solvabilityStatus: get('editorSolvabilityStatus'),
+      toolList: get('editorToolList'),
+      snapToggle: get('editorSnapToggle'),
+      gridSize: get('editorGridSize'),
+      brushSize: get('editorBrushSize'),
+      eraseGadgets: get('editorEraseGadgets'),
+      paletteTabs: get('editorPaletteTabs'),
+      paletteSearch: get('editorPaletteSearch'),
+      paletteViewList: get('editorPaletteViewList'),
+      paletteViewGrid: get('editorPaletteViewGrid'),
+      paletteRecent: get('editorPaletteRecent'),
+      paletteTerrain: get('editorPaletteTerrain'),
+      paletteGadgets: get('editorPaletteGadgets'),
+      paletteTriggers: get('editorPaletteTriggers'),
+      cursorStatus: get('editorCursorStatus'),
+      status: get('editorStatus'),
+      selectionStatus: get('editorSelectionStatus'),
+      headerTitle: get('editorHeaderTitle'),
+      headerStyle: get('editorHeaderStyle'),
+      headerWidth: get('editorHeaderWidth'),
+      headerHeight: get('editorHeaderHeight'),
+      headerLemmings: get('editorHeaderLemmings'),
+      headerSaveRequirement: get('editorHeaderSaveRequirement'),
+      headerTimeLimit: get('editorHeaderTimeLimit'),
+      headerSpawnInterval: get('editorHeaderSpawnInterval'),
+      headerStartX: get('editorHeaderStartX'),
+      headerStartY: get('editorHeaderStartY'),
+      selType: get('editorSelType'),
+      selName: get('editorSelName'),
+      selX: get('editorSelX'),
+      selY: get('editorSelY'),
+      selWidth: get('editorSelWidth'),
+      selHeight: get('editorSelHeight'),
+      selRotate: get('editorSelRotate'),
+      selSkill: get('editorSelSkill'),
+      selLemmings: get('editorSelLemmings'),
+      selPairing: get('editorSelPairing'),
+      selMidiFlag: get('editorSelMidiFlag'),
+      selMidiFlagId: get('editorSelMidiFlagId'),
+      selFlipH: get('editorSelFlipH'),
+      selFlipV: get('editorSelFlipV'),
+      selNoOverwrite: get('editorSelNoOverwrite'),
+      selErase: get('editorSelErase'),
+      selOneWay: get('editorSelOneWay'),
+      selectionActions: get('editorSelectionActions'),
+      selectionFlags: get('editorSelectionFlags'),
+      selectionBringFront: get('editorSelectionBringFront'),
+      selectionMoveForward: get('editorSelectionMoveForward'),
+      selectionMoveBackward: get('editorSelectionMoveBackward'),
+      selectionSendBack: get('editorSelectionSendBack'),
+      selectionAlignLeft: get('editorSelectionAlignLeft'),
+      selectionAlignCenter: get('editorSelectionAlignCenter'),
+      selectionAlignRight: get('editorSelectionAlignRight'),
+      selectionAlignTop: get('editorSelectionAlignTop'),
+      selectionAlignMiddle: get('editorSelectionAlignMiddle'),
+      selectionAlignBottom: get('editorSelectionAlignBottom'),
+      selectionDistributeX: get('editorSelectionDistributeX'),
+      selectionDistributeY: get('editorSelectionDistributeY'),
+      selectionReplacePiece: get('editorSelectionReplacePiece'),
+      selectionReplaceApply: get('editorSelectionReplaceApply'),
+      selectionRandomPieces: get('editorSelectionRandomPieces'),
+      selectionRandomSeed: get('editorSelectionRandomSeed'),
+      selectionRandomSameSize: get('editorSelectionRandomSameSize'),
+      selectionRandomApply: get('editorSelectionRandomApply'),
+      selectionScaleX: get('editorSelectionScaleX'),
+      selectionScaleY: get('editorSelectionScaleY'),
+      selectionTransformApply: get('editorSelectionTransformApply'),
+      deleteSelection: get('editorDeleteSelection'),
+      issuesList: get('editorIssuesList'),
+      shortcutOverlay: get('editorShortcutOverlay')
+    };
+  },
+
+  _bindController() {
+    this.controller.setCallbacks({
+      onSelectionChange: selection => {
+        this._refreshSelection(selection);
+        this._drawSelectionOverlay();
+      },
+      onMarqueeChange: () => {
+        this._drawSelectionOverlay();
+      },
+      onLevelChange: level => {
+        this._refreshHeaderFields(level);
+        this._refreshValidation();
+      },
+      onPreviewRequest: label => {
+        this._refreshPreview(label);
+      }
+    });
+  },
+
+  _nextAsyncToken() {
+    this._asyncToken += 1;
+    return this._asyncToken;
+  },
+
+  _isAsyncCurrent(token) {
+    return !this._disposed && token === this._asyncToken;
+  },
+
+  _addDomListener(element, eventName, handler, options) {
+    if (!element?.addEventListener || typeof handler !== 'function') return;
+    element.addEventListener(eventName, handler, options);
+    if (!Array.isArray(this._domListeners)) this._domListeners = [];
+    this._domListeners.push({ element, eventName, handler, options });
+  },
+
+  _addDisplayListener(eventHandler, handler) {
+    if (!eventHandler?.on || typeof handler !== 'function') return;
+    eventHandler.on(handler);
+    if (!Array.isArray(this._displayListeners)) this._displayListeners = [];
+    this._displayListeners.push({ eventHandler, handler });
+  },
+
+  dispose() {
+    if (this._disposed) return;
+    this._disposed = true;
+    this._asyncToken += 1;
+    this._cancelPalettePreviewHydration();
+    if (this._paletteFilterTimer) {
+      clearTimeout(this._paletteFilterTimer);
+      this._paletteFilterTimer = null;
+    }
+    while (this._displayListeners.length) {
+      const { eventHandler, handler } = this._displayListeners.pop();
+      eventHandler?.off?.(handler);
+    }
+    while (this._domListeners.length) {
+      const { element, eventName, handler, options } = this._domListeners.pop();
+      element?.removeEventListener?.(eventName, handler, options);
+    }
+    this.keybindings?.dispose?.();
+    this.keybindings = null;
+    this.controller?.dispose?.();
+    this.previewCache?.dispose?.();
+    this.shortcutOverlay = null;
+    this._eventsBound = false;
+  },
+
+  _bindEvents() {
+    if (this._eventsBound || this._disposed) return;
+    this._eventsBound = true;
+    this._bindToolButtons();
+    this._bindPaletteTabs();
+    this._bindPaletteSearch();
+    this._bindPaletteView();
+    this._bindHeaderFields();
+    this._bindSelectionFields();
+    this._bindSelectionActions();
+    this._bindUndoRedo();
+    this._bindBrushControls();
+    this._bindSavedControls();
+    this._bindLevelSelectors();
+    this._bindValidationControls();
+    this._bindPlaytest();
+    this._bindCanvasInput();
+    this._bindKeybindings();
+    this._bindShortcutOverlay();
+    this._bindModifierKeys();
+  },
+
+  _bindModifierKeys() {
+    const win = this.window;
+    if (!win?.addEventListener) return;
+    const update = (event) => {
+      this._shiftKey = !!event.shiftKey;
+      this._altKey = !!event.altKey;
+    };
+    this._addDomListener(win, 'keydown', update);
+    this._addDomListener(win, 'keyup', update);
+    this._addDomListener(win, 'blur', () => {
+      this._shiftKey = false;
+      this._altKey = false;
+    });
+  },
+
+  _bindKeybindings() {
+    if (!this.view) return;
+    this.keybindings?.dispose?.();
+    this.keybindings = new EditorKeybindings(this.controller, {
+      fileProvider: this.view.gameFactory?.fileProvider,
+      onBindingsLoaded: () => {
+        this._applyTooltips();
+        this._refreshShortcutOverlay();
+      },
+      onToolChange: tool => {
+        this._setToolButton(tool);
+        this._syncPaletteTabForTool(tool);
+        this._updateStatus();
+      },
+      onCopy: () => {
+        if (this.controller.copySelection()) {
+          this._updateStatus('Copy');
+        }
+      },
+      onPaste: () => {
+        if (this.controller.pasteSelection()) {
+          this._refreshAfterEdit('Paste');
+        }
+      },
+      onDuplicate: () => {
+        if (this.controller.duplicateSelection()) {
+          this._refreshAfterEdit('Duplicate');
+        }
+      },
+      onNudge: (dx, dy, step) => {
+        if (this.controller.nudgeSelection(dx, dy, step)) {
+          this._refreshAfterEdit('Nudge');
+        }
+      },
+      onSnap: () => {
+        if (this.controller.snapSelectionToGrid()) {
+          this._refreshAfterEdit('Snap');
+        }
+      },
+      onUndo: () => {
+        if (this.controller.undo()) {
+          this._refreshAfterEdit('Undo');
+        }
+      },
+      onRedo: () => {
+        if (this.controller.redo()) {
+          this._refreshAfterEdit('Redo');
+        }
+      },
+      onDelete: () => {
+        if (this.controller.deleteSelected()) {
+          this._refreshAfterEdit('Delete');
+        }
+      },
+      onBringToFront: () => {
+        if (this.controller.bringSelectionToFront()) {
+          this._refreshAfterEdit('Reorder');
+        }
+      },
+      onSendToBack: () => {
+        if (this.controller.sendSelectionToBack()) {
+          this._refreshAfterEdit('Reorder');
+        }
+      },
+      onMoveForward: () => {
+        if (this.controller.moveSelectionForward()) {
+          this._refreshAfterEdit('Reorder');
+        }
+      },
+      onMoveBackward: () => {
+        if (this.controller.moveSelectionBackward()) {
+          this._refreshAfterEdit('Reorder');
+        }
+      },
+      onPlaytestToggle: () => this._togglePlaytest(),
+      onToggleShortcutOverlay: () => this._toggleShortcutOverlay()
+    });
+    this.keybindings.bind();
+    this._applyTooltips();
+    this._refreshShortcutOverlay();
+  },
+
+  _bindShortcutOverlay() {
+    if (this.shortcutOverlay || !this.el.shortcutOverlay) return;
+    this.shortcutOverlay = new ShortcutOverlay({
+      root: this.el.shortcutOverlay,
+      title: 'Editor Shortcuts',
+      sections: EDITOR_SHORTCUT_SECTIONS,
+      getBindings: action => this.keybindings?.getDisplayBindings(action) || []
+    });
+  },
+
+  _toggleShortcutOverlay() {
+    this.shortcutOverlay?.toggle();
+  },
+
+  _refreshShortcutOverlay() {
+    if (!this.shortcutOverlay) return;
+    this.shortcutOverlay.render();
+  }
+};
+
+export { editorUiBindingLifecycleMethods };
diff --git a/js/app/editor-ui/EditorUiBindingTools.js b/js/app/editor-ui/EditorUiBindingTools.js
new file mode 100644
index 00000000..f41650c2
--- /dev/null
+++ b/js/app/editor-ui/EditorUiBindingTools.js
@@ -0,0 +1,86 @@
+import {
+  PALETTE_SEARCH_DEBOUNCE_MS
+} from './EditorUiControllerShared.js';
+
+const editorUiBindingToolMethods = {
+  _bindToolButtons() {
+    if (!this.el.toolList) return;
+    this._addDomListener(this.el.toolList, 'click', (event) => {
+      const button = event.target?.closest?.('button');
+      const tool = button?.dataset?.tool;
+      if (!tool) return;
+      this.controller.setTool(tool);
+      this._setToolButton(tool);
+      this._syncPaletteTabForTool(tool);
+      this._updateStatus();
+    });
+    this._setToolButton(this.controller.tool);
+    this._syncPaletteTabForTool(this.controller.tool);
+  },
+
+  _bindPaletteTabs() {
+    if (!this.el.paletteTabs) return;
+    this._addDomListener(this.el.paletteTabs, 'click', (event) => {
+      const button = event.target?.closest?.('button');
+      const tab = button?.dataset?.tab;
+      if (!tab) return;
+      this._setPaletteTab(tab);
+    });
+  },
+
+  _bindPaletteSearch() {
+    if (!this.el.paletteSearch) return;
+    this._addDomListener(this.el.paletteSearch, 'input', () => {
+      if (this._paletteFilterTimer) {
+        clearTimeout(this._paletteFilterTimer);
+      }
+      this._paletteFilterTimer = setTimeout(() => {
+        this._paletteFilterTimer = null;
+        this._applyPaletteFilter();
+      }, PALETTE_SEARCH_DEBOUNCE_MS);
+    });
+  },
+
+  _setToolButton(tool) {
+    const buttons = this.el.toolList?.querySelectorAll?.('button') || [];
+    buttons.forEach(button => {
+      const isActive = button.dataset?.tool === tool;
+      button.classList.toggle('active', isActive);
+      button.setAttribute('aria-pressed', isActive ? 'true' : 'false');
+    });
+  },
+
+  _applyTooltips() {
+    if (!this.keybindings || !this.el.toolList) return;
+    const map = {
+      select: 'editorToolSelect',
+      terrain: 'editorToolTerrain',
+      gadget: 'editorToolGadget',
+      trigger: 'editorToolTrigger',
+      'midi-flag': 'editorToolMidiFlag',
+      entrance: 'editorToolEntrance',
+      exit: 'editorToolExit',
+      steel: 'editorToolSteel',
+      brush: 'editorToolBrush',
+      eraser: 'editorToolEraser'
+    };
+    const buttons = this.el.toolList.querySelectorAll('button');
+    buttons.forEach(button => {
+      const tool = button.dataset?.tool;
+      const action = map[tool];
+      if (!action) return;
+      const bindings = this.keybindings.getDisplayBindings(action);
+      const base = button.dataset?.tooltip || button.title || '';
+      if (!bindings.length) {
+        if (base) button.title = base;
+        return;
+      }
+      const suffix = bindings.length === 1
+        ? `Shortcut: ${bindings[0]}`
+        : `Shortcuts: ${bindings.join(', ')}`;
+      button.title = base ? `${base} (${suffix})` : suffix;
+    });
+  }
+};
+
+export { editorUiBindingToolMethods };
diff --git a/js/app/editor-ui/EditorUiBindings.js b/js/app/editor-ui/EditorUiBindings.js
new file mode 100644
index 00000000..891f5e02
--- /dev/null
+++ b/js/app/editor-ui/EditorUiBindings.js
@@ -0,0 +1,11 @@
+import { editorUiBindingControlMethods } from './EditorUiBindingControls.js';
+import { editorUiBindingLifecycleMethods } from './EditorUiBindingLifecycle.js';
+import { editorUiBindingToolMethods } from './EditorUiBindingTools.js';
+
+const editorUiBindingsMethods = {
+  ...editorUiBindingLifecycleMethods,
+  ...editorUiBindingToolMethods,
+  ...editorUiBindingControlMethods
+};
+
+export { editorUiBindingsMethods };
diff --git a/js/app/editor-ui/EditorUiControllerCore.js b/js/app/editor-ui/EditorUiControllerCore.js
new file mode 100644
index 00000000..79afb350
--- /dev/null
+++ b/js/app/editor-ui/EditorUiControllerCore.js
@@ -0,0 +1,222 @@
+import {
+  BinaryReader,
+  EDITOR_SHORTCUT_SECTIONS,
+  EditorAssetCache,
+  EditorController,
+  EditorHistory,
+  EditorKeybindings,
+  EditorPreviewCache,
+  HISTORY_COALESCE_WINDOW_MS,
+  LevelReader,
+  LevelWriter,
+  MAX_BRUSH_SIZE,
+  MAX_HISTORY,
+  MAX_HISTORY_BYTES,
+  PALETTE_PREVIEW_BATCH_SIZE,
+  PALETTE_SEARCH_DEBOUNCE_MS,
+  ShortcutOverlay,
+  createClassicLevelData,
+  createEditorLevelFromClassic,
+  downloadBinaryFile,
+  downloadTextFile,
+  ensureLevelEntryUids,
+  formatRotation,
+  formatValue,
+  getEntryBounds,
+  getRuntimeDependency,
+  getStyle,
+  getStyleNames,
+  listSavedLevels,
+  loadSavedLevel,
+  normalizeRotation,
+  normalizeText,
+  parseNumber,
+  readArrayBufferFile,
+  readTextFile,
+  sanitizeFileName,
+  saveLevel,
+  validateLevel
+} from './EditorUiControllerShared.js';
+import { editorUiBindingsMethods } from './EditorUiBindings.js';
+import { editorPaletteUiMethods } from './EditorPaletteUi.js';
+import { editorSelectionPanelMethods } from './EditorSelectionPanel.js';
+import { editorLevelIoUiMethods } from './EditorLevelIoUi.js';
+class EditorUiController {
+  constructor(options = {}) {
+    this.view = options.view || null;
+    this.document = options.document || getRuntimeDependency('document', null);
+    this.window = options.window || getRuntimeDependency('window', null);
+    this.session = options.session || this.view?.ensureEditorSession?.() || null;
+    this.history = options.history || new EditorHistory({
+      maxEntries: MAX_HISTORY,
+      maxBytes: MAX_HISTORY_BYTES,
+      coalesceWindowMs: HISTORY_COALESCE_WINDOW_MS
+    });
+    this.controller = options.controller || new EditorController({
+      session: this.session,
+      history: this.history
+    });
+    this.assetCache = options.assetCache || new EditorAssetCache();
+    this.previewCache = options.previewCache || new EditorPreviewCache({
+      document: this.document,
+      window: this.window
+    });
+    this.assets = null;
+    this._selection = [];
+    this._activeTab = 'terrain';
+    this._currentSavedId = '';
+    this._playtest = false;
+    this._previewInFlight = false;
+    this._previewQueued = false;
+    this._previewQueuedLabel = null;
+    this._previewQueuedOptions = null;
+    this._cursorPos = null;
+    this._paletteViewMode = 'list';
+    this._paletteGridColumns = 4;
+    this._paletteEntries = {
+      terrain: [],
+      gadget: [],
+      trigger: []
+    };
+    this._recentPaletteEntries = [];
+    this._palettePreviewQueue = [];
+    this._palettePreviewIndex = 0;
+    this._palettePreviewTimer = null;
+    this._palettePreviewToken = 0;
+    this._paletteFilterTimer = null;
+    this._styleAvailability = new Map();
+    this._suppressHeader = false;
+    this._suppressInspector = false;
+    this._pointerDown = false;
+    this._shiftKey = false;
+    this._altKey = false;
+    this._antsOffset = 0;
+    this._selectionOverlayVisible = false;
+    this._needsDefaultEntrances = false;
+    this._eventsBound = false;
+    this._disposed = false;
+    this._asyncToken = 0;
+    this._domListeners = [];
+    this._displayListeners = [];
+    this.shortcutOverlay = null;
+    this._dirty = false;
+    this._baseTitle = this.document?.title || 'Lemmings Editor';
+    this._lastSolvabilityCheck = null;
+    this._solvabilityCheckInFlight = false;
+
+    this._bindElements();
+    this._bindController();
+  }
+
+  _renderPaletteList(container, items, type) {
+    if (!container) return;
+    container.innerHTML = '';
+    const nextEntries = [];
+    for (const entry of items || []) {
+      const width = Number(entry.width || 0);
+      const height = Number(entry.height || 0);
+      if (width <= 0 && height <= 0) {
+        continue;
+      }
+      const button = this.document.createElement('button');
+      button.type = 'button';
+      button.dataset.id = String(entry.id);
+      button.dataset.type = type;
+      const labelText = this._getPaletteLabelText(entry);
+      const label = this.document.createElement('span');
+      label.className = 'palette-label';
+      label.textContent = labelText;
+      button.title = `Select ${labelText}`;
+      const previewWrap = this.document.createElement('span');
+      previewWrap.className = 'palette-preview';
+      previewWrap.classList.add('pending');
+      const previewImg = this.document.createElement('img');
+      previewImg.alt = labelText;
+      previewImg.loading = 'lazy';
+      previewWrap.appendChild(previewImg);
+      button.append(previewWrap, label);
+      button.addEventListener('click', () => {
+        this._selectPaletteEntry(entry, type, { recordRecent: true });
+      });
+      container.appendChild(button);
+      nextEntries.push({
+        id: Number(entry.id),
+        type,
+        entry,
+        searchKey: normalizeText(labelText).toLowerCase(),
+        button,
+        previewWrap,
+        previewImg,
+        previewLoaded: false
+      });
+    }
+    this._paletteEntries[type] = nextEntries;
+  }
+
+  _refreshSelection(selection) {
+    const entries = Array.isArray(selection)
+      ? selection
+      : this.controller.getSelectedEntries();
+    this._selection = entries;
+    if (!entries.length) {
+      this._setSelectionFields(null);
+      this._updateSelectionStatus();
+      return;
+    }
+    if (entries.length > 1) {
+      this._setSelectionFields({ multi: true, count: entries.length, entries });
+      this._updateSelectionStatus();
+      return;
+    }
+    const selected = entries[0];
+    const props = selected.entry?.props || {};
+    const isSteel = selected.type === 'steel';
+    const meta = selected.type === 'gadget'
+      ? this.assets?.gadgetById?.get?.(props.PIECE)
+      : this.assets?.terrainById?.get?.(props.PIECE);
+    const name = isSteel ? 'Steel' : (meta?.name || `#${props.PIECE}`);
+    const pieceId = Number(props.PIECE);
+    if (!isSteel && Number.isFinite(pieceId)) {
+      if (selected.type === 'gadget') {
+        this.controller.setSelectedGadget(pieceId);
+      } else {
+        this.controller.setSelectedTerrain(pieceId);
+      }
+      this._refreshPaletteSelection();
+    }
+    this._setSelectionFields({
+      type: selected.type,
+      name,
+      props,
+      meta
+    });
+    this._updateSelectionStatus();
+  }
+
+  _updateSelectionStatus() {
+    if (!this.el.selectionStatus) return;
+    if (!this._selection || this._selection.length === 0) {
+      this.el.selectionStatus.textContent = 'No selection';
+      return;
+    }
+    if (this._selection.length > 1) {
+      this.el.selectionStatus.textContent = `${this._selection.length} selected`;
+      return;
+    }
+    const selected = this._selection[0];
+    const props = selected.entry?.props || {};
+    const name = selected.type === 'steel'
+      ? 'steel'
+      : (selected.entry?.props?.PIECE ?? 'unknown');
+    this.el.selectionStatus.textContent = `${selected.type} #${name} @ ${props.X ?? 0},${props.Y ?? 0}`;
+  }
+}
+for (const methods of [
+  editorUiBindingsMethods,
+  editorPaletteUiMethods,
+  editorSelectionPanelMethods,
+  editorLevelIoUiMethods
+]) {
+  Object.defineProperties(EditorUiController.prototype, Object.getOwnPropertyDescriptors(methods));
+}
+export { EditorUiController };
diff --git a/js/app/editor-ui/EditorUiControllerShared.js b/js/app/editor-ui/EditorUiControllerShared.js
new file mode 100644
index 00000000..8643223a
--- /dev/null
+++ b/js/app/editor-ui/EditorUiControllerShared.js
@@ -0,0 +1,141 @@
+import { EditorController } from '../../editor/EditorController.js';
+import { EditorHistory } from '../../editor/EditorHistory.js';
+import { EditorAssetCache } from '../../editor/EditorAssetCache.js';
+import { BinaryReader } from '../../data/BinaryReader.js';
+import { LevelReader } from '../../level/LevelReader.js';
+import { LevelWriter } from '../../level/LevelWriter.js';
+import { createEditorLevelFromClassic } from '../../editor/ClassicLevelConverter.js';
+import { createClassicLevelData } from '../../editor/EditorLevelLoader.js';
+import {
+  createValidationReport,
+  validateLevel
+} from '../../editor/EditorValidator.js';
+import { checkEditorSolvabilityAdvisory } from '../../solver/EditorAdvisory.js';
+import { getEntryBounds } from '../../editor/EditorHitTest.js';
+import { ensureLevelEntryUids } from '../../editor/EditorEntryFactory.js';
+import { getStyle, getStyleNames } from '../../editor/StyleRegistry.js';
+import { EditorPreviewCache } from '../editorPreviewCache.js';
+import { EditorKeybindings } from '../../input/EditorKeybindings.js';
+import { ShortcutOverlay } from '../shortcutOverlay.js';
+import { getRuntimeDependency } from '../../core/dependencies.js';
+import {
+  formatRotation,
+  formatValue,
+  normalizeRotation,
+  normalizeText,
+  parseNumber,
+  sanitizeFileName
+} from './editorUiFormat.js';
+import {
+  downloadBinaryFile,
+  downloadTextFile,
+  readArrayBufferFile,
+  readTextFile
+} from './editorUiFiles.js';
+import {
+  listSavedLevels,
+  loadSavedLevel,
+  saveLevel
+} from '../../editor/EditorStorage.js';
+
+const MAX_HISTORY = 200;
+const MAX_HISTORY_BYTES = 16 * 1024 * 1024;
+const HISTORY_COALESCE_WINDOW_MS = 250;
+const MAX_BRUSH_SIZE = 64;
+const PALETTE_PREVIEW_BATCH_SIZE = 24;
+const PALETTE_SEARCH_DEBOUNCE_MS = 30;
+const EDITOR_SHORTCUT_SECTIONS = [
+  {
+    title: 'General',
+    entries: [
+      { action: 'editorToggleShortcutOverlay', label: 'Shortcut overlay' },
+      { action: 'editorTogglePlaytest', label: 'Toggle playtest' }
+    ]
+  },
+  {
+    title: 'Tools',
+    entries: [
+      { action: 'editorToolSelect', label: 'Select' },
+      { action: 'editorToolTerrain', label: 'Terrain' },
+      { action: 'editorToolGadget', label: 'Object' },
+      { action: 'editorToolTrigger', label: 'Trigger' },
+      { action: 'editorToolMidiFlag', label: 'MIDI Flag' },
+      { action: 'editorToolEntrance', label: 'Entrance' },
+      { action: 'editorToolExit', label: 'Exit' },
+      { action: 'editorToolSteel', label: 'Steel' },
+      { action: 'editorToolBrush', label: 'Brush' },
+      { action: 'editorToolEraser', label: 'Eraser' }
+    ]
+  },
+  {
+    title: 'Edit',
+    entries: [
+      { action: 'editorCopy', label: 'Copy' },
+      { action: 'editorPaste', label: 'Paste' },
+      { action: 'editorDuplicate', label: 'Duplicate' },
+      { action: 'editorUndo', label: 'Undo' },
+      { action: 'editorRedo', label: 'Redo' },
+      { action: 'editorDelete', label: 'Delete selection' },
+      { action: 'editorSnapSelection', label: 'Snap to grid' },
+      { action: 'editorBringToFront', label: 'Bring to front' },
+      { action: 'editorMoveForward', label: 'Move forward' },
+      { action: 'editorMoveBackward', label: 'Move backward' },
+      { action: 'editorSendToBack', label: 'Send to back' }
+    ]
+  },
+  {
+    title: 'Nudge',
+    entries: [
+      { action: 'editorNudgeLeft', label: 'Nudge left' },
+      { action: 'editorNudgeRight', label: 'Nudge right' },
+      { action: 'editorNudgeUp', label: 'Nudge up' },
+      { action: 'editorNudgeDown', label: 'Nudge down' },
+      { action: 'editorNudgeLeftFast', label: 'Nudge left (grid)' },
+      { action: 'editorNudgeRightFast', label: 'Nudge right (grid)' },
+      { action: 'editorNudgeUpFast', label: 'Nudge up (grid)' },
+      { action: 'editorNudgeDownFast', label: 'Nudge down (grid)' }
+    ]
+  }
+];
+
+export {
+  BinaryReader,
+  EDITOR_SHORTCUT_SECTIONS,
+  EditorAssetCache,
+  EditorController,
+  EditorHistory,
+  EditorKeybindings,
+  EditorPreviewCache,
+  HISTORY_COALESCE_WINDOW_MS,
+  LevelReader,
+  LevelWriter,
+  MAX_BRUSH_SIZE,
+  MAX_HISTORY,
+  MAX_HISTORY_BYTES,
+  PALETTE_PREVIEW_BATCH_SIZE,
+  PALETTE_SEARCH_DEBOUNCE_MS,
+  ShortcutOverlay,
+  createClassicLevelData,
+  createValidationReport,
+  createEditorLevelFromClassic,
+  downloadBinaryFile,
+  downloadTextFile,
+  ensureLevelEntryUids,
+  formatRotation,
+  formatValue,
+  getEntryBounds,
+  getRuntimeDependency,
+  getStyle,
+  getStyleNames,
+  listSavedLevels,
+  loadSavedLevel,
+  normalizeRotation,
+  normalizeText,
+  parseNumber,
+  readArrayBufferFile,
+  readTextFile,
+  sanitizeFileName,
+  saveLevel,
+  checkEditorSolvabilityAdvisory,
+  validateLevel
+};
diff --git a/js/app/editor-ui/editorClassicSubsetContract.js b/js/app/editor-ui/editorClassicSubsetContract.js
new file mode 100644
index 00000000..bbd489e1
--- /dev/null
+++ b/js/app/editor-ui/editorClassicSubsetContract.js
@@ -0,0 +1,165 @@
+const CLASSIC_SKILL_NAMES = new Set([
+  'CLIMBER',
+  'FLOATER',
+  'BOMBER',
+  'BLOCKER',
+  'BUILDER',
+  'BASHER',
+  'MINER',
+  'DIGGER'
+]);
+
+const countLines = (lines) => {
+  if (!Array.isArray(lines)) return 0;
+  return lines.filter(line => String(line ?? '').trim()).length;
+};
+
+const getEntries = (level, key) => Array.isArray(level?.[key]) ? level[key] : [];
+
+const collectEntryUnknownLineCount = (level) => {
+  let count = 0;
+  for (const key of ['terrains', 'gadgets', 'steel']) {
+    for (const entry of getEntries(level, key)) {
+      count += countLines(entry?.unknownLines);
+    }
+  }
+  for (const group of getEntries(level, 'terrainGroups')) {
+    count += countLines(group?.unknownLines);
+    const terrains = Array.isArray(group?.terrains) ? group.terrains : [];
+    for (const terrain of terrains) {
+      count += countLines(terrain?.unknownLines);
+    }
+  }
+  return count;
+};
+
+const getPreservedUnknownDataSummary = (level) => {
+  const unknownSections = Array.isArray(level?.unknownSections)
+    ? level.unknownSections.length
+    : 0;
+  const unknownSectionLines = Array.isArray(level?.unknownSections)
+    ? level.unknownSections.reduce((total, section) => total + countLines(section?.lines), 0)
+    : 0;
+  const topLevelLines = countLines(level?.unknownLines);
+  const skillsetLines = countLines(level?.skillsetUnknownLines);
+  const entryLines = collectEntryUnknownLineCount(level);
+  const totalLines = unknownSectionLines + topLevelLines + skillsetLines + entryLines;
+  const parts = [];
+  if (unknownSections) parts.push(`${unknownSections} unknown section${unknownSections === 1 ? '' : 's'}`);
+  if (totalLines) parts.push(`${totalLines} preserved line${totalLines === 1 ? '' : 's'}`);
+  return {
+    hasData: unknownSections > 0 || totalLines > 0,
+    summary: parts.join(', ')
+  };
+};
+
+const hasAnyProp = (entry, names) => {
+  const props = entry?.props || null;
+  if (!props) return false;
+  return names.some(name => Object.prototype.hasOwnProperty.call(props, name));
+};
+
+const hasAnyEntryWithProps = (entries, names) => {
+  return Array.isArray(entries) && entries.some(entry => hasAnyProp(entry, names));
+};
+
+const hasNonClassicSkill = (level) => {
+  if (!level?.skillset?.keys) return false;
+  for (const skill of level.skillset.keys()) {
+    if (!CLASSIC_SKILL_NAMES.has(String(skill).toUpperCase())) return true;
+  }
+  return false;
+};
+
+const hasClassicExportUnsupportedProps = (level) => {
+  const terrainUnsupported = ['ROTATE', 'FLIP_HORIZONTAL', 'WIDTH', 'HEIGHT', 'ONE_WAY'];
+  const gadgetUnsupported = [
+    'ROTATE',
+    'FLIP_HORIZONTAL',
+    'WIDTH',
+    'HEIGHT',
+    'SKILL',
+    'LEMMINGS',
+    'PAIRING',
+    'MIDI_FLAG',
+    'MIDI_FLAG_ID',
+    'MIDI_FLAG_COOLDOWN',
+    'ERASE'
+  ];
+  return hasAnyEntryWithProps(getEntries(level, 'terrains'), terrainUnsupported)
+    || hasAnyEntryWithProps(getEntries(level, 'gadgets'), gadgetUnsupported)
+    || getEntries(level, 'terrainGroups').some(group => {
+      const terrains = Array.isArray(group?.terrains) ? group.terrains : [];
+      return hasAnyProp(group, ['STEEL', 'STYLE'])
+        || hasAnyEntryWithProps(terrains, terrainUnsupported);
+    })
+    || hasNonClassicSkill(level);
+};
+
+const getClassicExportLossReasons = (level) => {
+  const reasons = [];
+  const preserved = getPreservedUnknownDataSummary(level);
+  if (preserved.hasData) reasons.push('comments/unknown NXLV data');
+  if (Array.isArray(level?.terrainGroups) && level.terrainGroups.length > 0) {
+    reasons.push('terrain groups');
+  }
+  if (hasAnyEntryWithProps(getEntries(level, 'terrains'), ['ONE_WAY'])) {
+    reasons.push('terrain one-way flags');
+  }
+  if (hasClassicExportUnsupportedProps(level)) {
+    reasons.push('unsupported transforms, resize, or metadata');
+  }
+  return Array.from(new Set(reasons));
+};
+
+const getClassicExportLossSummary = (level) => {
+  const reasons = getClassicExportLossReasons(level);
+  return {
+    hasLoss: reasons.length > 0,
+    reasons,
+    summary: reasons.join(', ')
+  };
+};
+
+const buildClassicSubsetIssues = (level) => {
+  if (!level) return [];
+  const issues = [];
+  const preserved = getPreservedUnknownDataSummary(level);
+  if (preserved.hasData) {
+    issues.push({
+      severity: 'warning',
+      message: `NXLV has preserved comments or unknown data (${preserved.summary}). NXLV export keeps it; classic preview and LVL export ignore it.`
+    });
+  }
+  const classicLoss = getClassicExportLossSummary(level);
+  if (classicLoss.hasLoss) {
+    issues.push({
+      severity: 'warning',
+      message: `Classic LVL export is lossy: ${classicLoss.summary}. Use NXLV export to preserve editor and NeoLemmix data.`
+    });
+  }
+  return issues;
+};
+
+const isDestructiveQuickFix = (issue) => {
+  if (!issue?.fix) return false;
+  if (issue.destructive === true) return true;
+  const text = `${issue.fixLabel || ''} ${issue.message || ''}`.toLowerCase();
+  return /\b(remove|clamp|clear|snap|reset)\b/.test(text)
+    || text.includes('keep first')
+    || text.includes('fix steel');
+};
+
+const getErrorMessage = (error) => {
+  if (!error) return 'Unknown error.';
+  if (typeof error === 'string') return error;
+  const message = error.message || error.name || String(error);
+  return String(message || 'Unknown error.').trim() || 'Unknown error.';
+};
+
+export {
+  buildClassicSubsetIssues,
+  getClassicExportLossSummary,
+  getErrorMessage,
+  isDestructiveQuickFix
+};
diff --git a/js/app/editor-ui/editorUiFormat.js b/js/app/editor-ui/editorUiFormat.js
index 7dd8170e..b6beb27b 100644
--- a/js/app/editor-ui/editorUiFormat.js
+++ b/js/app/editor-ui/editorUiFormat.js
@@ -1,11 +1,24 @@
+import { toFiniteNumber } from '../../core/numberParsing.js';
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
 const normalizeText = (value) => String(value ?? '').trim();
 
+/**
+ * @param {unknown} value
+ * @returns {number|null}
+ */
 const parseNumber = (value) => {
   if (value == null || value === '') return null;
-  const num = Number(value);
-  return Number.isFinite(num) ? num : null;
+  return toFiniteNumber(value, null);
 };
 
+/**
+ * @param {unknown} value
+ * @returns {number|null}
+ */
 const normalizeRotation = (value) => {
   const num = parseNumber(value);
   if (num == null) return null;
@@ -14,6 +27,10 @@ const normalizeRotation = (value) => {
   return ((snapped % 360) + 360) % 360;
 };
 
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
 const formatRotation = (value) => {
   const num = parseNumber(value);
   if (num == null) return '';
@@ -21,8 +38,16 @@ const formatRotation = (value) => {
   return String(normalized);
 };
 
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
 const formatValue = (value) => (value == null ? '' : String(value));
 
+/**
+ * @param {unknown} name
+ * @returns {string}
+ */
 const sanitizeFileName = (name) => String(name || 'level')
   .trim()
   .replace(/[^a-z0-9_-]+/gi, '_')
diff --git a/js/app/editorBoot.js b/js/app/editorBoot.js
index 82d8db41..21b53c63 100644
--- a/js/app/editorBoot.js
+++ b/js/app/editorBoot.js
@@ -4,8 +4,52 @@ import { EditorUiController } from './editorUiController.js';
 import { registerServiceWorker } from './registerServiceWorker.js';
 import { installE2EHarness } from './e2eHarness.js';
 import { bindCanvasFocusBlur } from './canvasFocusBlur.js';
+import { ANALYTICS_EVENT_TYPES, createAnalyticsService } from './analytics.js';
+
+let analytics = null;
+
+const trackEditorAction = (action, enabled = null) => {
+  analytics?.track?.(ANALYTICS_EVENT_TYPES.EDITOR_ACTION, {
+    action,
+    enabled
+  });
+};
+
+const bindEditorAnalytics = (documentRef) => {
+  const bindClick = (id, action, enabled = null) => {
+    const node = documentRef.getElementById(id);
+    if (!node?.addEventListener) return;
+    node.addEventListener('click', () => {
+      trackEditorAction(action, enabled);
+    });
+  };
+  bindClick('editorNewLevel', 'new');
+  bindClick('editorSavedSave', 'save');
+  bindClick('editorSavedExport', 'export');
+  bindClick('editorPlaytestToggle', 'playtest');
+  const importButtons = ['editorSavedImport', 'editorSavedImportClassic'];
+  for (const id of importButtons) {
+    bindClick(id, 'import');
+  }
+};
 
 const init = async () => {
+  analytics = createAnalyticsService({
+    window,
+    document,
+    navigator: window?.navigator || null,
+    location: window?.location || null,
+    localStorage: window?.localStorage || null,
+    profile: 'editor',
+    surface: 'editor'
+  });
+  analytics.installWindowApi(window);
+  analytics.trackPageView({
+    surface: 'editor',
+    profile: 'editor',
+    embedMode: false
+  });
+
   const lemmings = new GameView();
   lemmings.midiEnabled = false;
 
@@ -22,9 +66,18 @@ const init = async () => {
   const ui = new EditorUiController({ view: lemmings, document, window });
   await ui.init();
   installE2EHarness({ view: lemmings, editorUi: ui });
+  bindEditorAnalytics(document);
 };
 
 window.addEventListener('DOMContentLoaded', () => {
-  init();
-  registerServiceWorker();
+  init().catch((error) => {
+    analytics?.track?.(ANALYTICS_EVENT_TYPES.RUNTIME_BOOT_ERROR, {
+      code: 'boot_error',
+      surface: 'editor',
+      profile: 'editor',
+      embedMode: false
+    });
+    throw error;
+  });
+  registerServiceWorker({ profile: 'editor', dev: true });
 });
diff --git a/js/app/editorPreviewCache.js b/js/app/editorPreviewCache.js
index 24c4e7c2..ca0f3ebc 100644
--- a/js/app/editorPreviewCache.js
+++ b/js/app/editorPreviewCache.js
@@ -1,5 +1,8 @@
+import { getRuntimeDependency } from '../core/dependencies.js';
+
 const CACHE_PREFIX = 'lemmings.editor.preview';
 const CACHE_VERSION = 1;
+const DEFAULT_MAX_MEMORY_ENTRIES = 512;
 
 const hashStep = (hash, value) => (((hash ^ value) >>> 0) * 16777619) >>> 0;
 
@@ -35,6 +38,11 @@ const hashFrame = (hash, frame) => {
   return hash;
 };
 
+const resolveVersion = (value) => {
+  const version = value?._previewHashVersion ?? value?.previewVersion ?? value?.version;
+  return Number.isFinite(version) ? version : null;
+};
+
 const pickFrame = (image) => {
   const frames = image?.frames || [];
   const previewIndex = Number.isFinite(image?.preview_image_index)
@@ -43,6 +51,10 @@ const pickFrame = (image) => {
   return frames[previewIndex] || frames[0] || null;
 };
 
+const getPreviewIndex = (image) => {
+  return Number.isFinite(image?.preview_image_index) ? image.preview_image_index : 0;
+};
+
 const buildPreviewDataUrl = (image, palette, document) => {
   if (!image || !palette || !document) return null;
   const width = Math.max(0, image.width || 0);
@@ -74,12 +86,153 @@ const buildPreviewDataUrl = (image, palette, document) => {
   return canvas.toDataURL('image/png');
 };
 
+const keyPrefixForType = (version, type) => `${CACHE_PREFIX}:v${version}:${type}:`;
+
+const getEntryIdFromKey = (key) => {
+  if (typeof key !== 'string') return null;
+  const parts = key.split(':');
+  if (parts.length < 5) return null;
+  return parts[3] || null;
+};
+
 class EditorPreviewCache {
   constructor(options = {}) {
-    this.document = options.document || globalThis.document || null;
-    this.storage = options.storage || globalThis.localStorage || null;
+    this.document = options.document || getRuntimeDependency('document', null);
+    this.storage = options.storage || getRuntimeDependency('localStorage', null);
     this.version = Number.isFinite(options.version) ? options.version : CACHE_VERSION;
+    this.maxMemoryEntries = Number.isFinite(options.maxMemoryEntries) && options.maxMemoryEntries > 0
+      ? Math.floor(options.maxMemoryEntries)
+      : DEFAULT_MAX_MEMORY_ENTRIES;
     this.memory = new Map();
+    this._hashCache = new WeakMap();
+  }
+
+  _remember(key, value) {
+    if (!key || typeof value !== 'string') return;
+    if (this.memory.has(key)) {
+      this.memory.delete(key);
+    }
+    this.memory.set(key, value);
+    while (this.memory.size > this.maxMemoryEntries) {
+      const oldestKey = this.memory.keys().next().value;
+      this.memory.delete(oldestKey);
+    }
+  }
+
+  /**
+   * Invalidates preview cache entries for one palette type while preserving any
+   * IDs included in `validIds`. Called during style reload to avoid stale/bloated
+   * caches when large packs swap palettes repeatedly.
+   */
+  invalidateTypeIds(type, validIds = []) {
+    if (!type) return;
+    const keepIds = new Set((Array.isArray(validIds) ? validIds : [])
+      .filter(id => Number.isFinite(id))
+      .map(id => String(id)));
+    const prefix = keyPrefixForType(this.version, type);
+
+    for (const key of Array.from(this.memory.keys())) {
+      if (!key.startsWith(prefix)) continue;
+      const entryId = getEntryIdFromKey(key);
+      if (entryId != null && keepIds.has(entryId)) continue;
+      this.memory.delete(key);
+    }
+
+    const storage = this.storage;
+    if (!storage || typeof storage.length !== 'number' || typeof storage.key !== 'function') {
+      return;
+    }
+    const staleKeys = [];
+    try {
+      for (let i = 0; i < storage.length; i += 1) {
+        const key = storage.key(i);
+        if (!key || !key.startsWith(prefix)) continue;
+        const entryId = getEntryIdFromKey(key);
+        if (entryId != null && keepIds.has(entryId)) continue;
+        staleKeys.push(key);
+      }
+      for (const key of staleKeys) {
+        storage.removeItem?.(key);
+      }
+    } catch {
+      // ignore storage enumeration errors
+    }
+  }
+
+  _getImageSignature(image, palette, frame) {
+    const previewIndex = getPreviewIndex(image);
+    const width = image?.width || 0;
+    const height = image?.height || 0;
+    const frameVersion = resolveVersion(frame) ?? resolveVersion(image);
+    const paletteVersion = resolveVersion(palette);
+    let paletteHash = null;
+    if (paletteVersion == null) {
+      paletteHash = hashPalette(2166136261, palette).toString(16);
+    }
+
+    const cached = image && this._hashCache.get(image);
+    const frameStable = cached
+      && cached.frame === frame
+      && cached.frameLength === frame.length
+      && cached.frameVersion === frameVersion
+      && cached.width === width
+      && cached.height === height
+      && cached.previewIndex === previewIndex;
+    if (
+      frameStable
+      && cached.palette === palette
+      && cached.paletteVersion === paletteVersion
+      && cached.paletteHash === paletteHash
+    ) {
+      return cached.signature;
+    }
+
+    const frameHash = frameStable
+      ? cached.frameHash
+      : hashFrame(2166136261, frame).toString(16);
+    let hash = 2166136261;
+    hash = hashStep(hash, width);
+    hash = hashStep(hash, height);
+    hash = hashStep(hash, previewIndex);
+    hash = hashStep(hash, frame.length);
+    for (let i = 0; i < frameHash.length; i += 1) {
+      hash = hashStep(hash, frameHash.charCodeAt(i));
+    }
+    const paletteKey = paletteVersion == null ? paletteHash : String(paletteVersion);
+    for (let i = 0; i < paletteKey.length; i += 1) {
+      hash = hashStep(hash, paletteKey.charCodeAt(i));
+    }
+    const signature = hash.toString(16);
+    if (image) {
+      this._hashCache.set(image, {
+        frame,
+        frameLength: frame.length,
+        frameVersion,
+        width,
+        height,
+        previewIndex,
+        palette,
+        paletteVersion,
+        paletteHash,
+        frameHash,
+        signature
+      });
+      image._previewHash = signature;
+    }
+    return signature;
+  }
+
+  getStats() {
+    return {
+      memoryEntries: this.memory.size,
+      maxMemoryEntries: this.maxMemoryEntries,
+      storageAvailable: !!this.storage
+    };
+  }
+
+  dispose() {
+    this.memory.clear();
+    this._hashCache = new WeakMap();
   }
 
   getPreviewUrl({ type, id, image }) {
@@ -88,19 +241,13 @@ class EditorPreviewCache {
     const frame = pickFrame(image);
     if (!frame || !palette) return null;
 
-    let signature = image._previewHash;
-    if (!signature) {
-      let hash = 2166136261;
-      hash = hashStep(hash, image.width || 0);
-      hash = hashStep(hash, image.height || 0);
-      hash = hashPalette(hash, palette);
-      hash = hashFrame(hash, frame);
-      signature = hash.toString(16);
-      image._previewHash = signature;
-    }
-
+    const signature = this._getImageSignature(image, palette, frame);
     const key = `${CACHE_PREFIX}:v${this.version}:${type}:${id}:${signature}`;
-    if (this.memory.has(key)) return this.memory.get(key);
+    if (this.memory.has(key)) {
+      const cachedMemory = this.memory.get(key);
+      this._remember(key, cachedMemory);
+      return cachedMemory;
+    }
 
     let cached = null;
     try {
@@ -110,13 +257,13 @@ class EditorPreviewCache {
     }
 
     if (cached) {
-      this.memory.set(key, cached);
+      this._remember(key, cached);
       return cached;
     }
 
     const url = buildPreviewDataUrl(image, palette, this.document);
     if (url) {
-      this.memory.set(key, url);
+      this._remember(key, url);
       try {
         this.storage?.setItem?.(key, url);
       } catch {
diff --git a/js/app/editorUiController.js b/js/app/editorUiController.js
index a84dcabc..d5a26efd 100644
--- a/js/app/editorUiController.js
+++ b/js/app/editorUiController.js
@@ -1,1629 +1 @@
-import { EditorController } from '../editor/EditorController.js';
-import { EditorHistory } from '../editor/EditorHistory.js';
-import { EditorAssetCache } from '../editor/EditorAssetCache.js';
-import { BinaryReader } from '../data/BinaryReader.js';
-import { LevelReader } from '../level/LevelReader.js';
-import { LevelWriter } from '../level/LevelWriter.js';
-import { createEditorLevelFromClassic } from '../editor/ClassicLevelConverter.js';
-import { createClassicLevelData } from '../editor/EditorLevelLoader.js';
-import { validateLevel } from '../editor/EditorValidator.js';
-import { getEntryBounds } from '../editor/EditorHitTest.js';
-import { ensureLevelEntryUids } from '../editor/EditorEntryFactory.js';
-import { getStyle, getStyleNames } from '../editor/StyleRegistry.js';
-import { EditorPreviewCache } from './editorPreviewCache.js';
-import { EditorKeybindings } from '../input/EditorKeybindings.js';
-import { ShortcutOverlay } from './shortcutOverlay.js';
-import {
-  formatRotation,
-  formatValue,
-  normalizeRotation,
-  normalizeText,
-  parseNumber,
-  sanitizeFileName
-} from './editor-ui/editorUiFormat.js';
-import {
-  downloadBinaryFile,
-  downloadTextFile,
-  readArrayBufferFile,
-  readTextFile
-} from './editor-ui/editorUiFiles.js';
-import {
-  listSavedLevels,
-  loadSavedLevel,
-  saveLevel
-} from '../editor/EditorStorage.js';
-
-const MAX_HISTORY = 200;
-const MAX_BRUSH_SIZE = 64;
-const EDITOR_SHORTCUT_SECTIONS = [
-  {
-    title: 'General',
-    entries: [
-      { action: 'editorToggleShortcutOverlay', label: 'Shortcut overlay' },
-      { action: 'editorTogglePlaytest', label: 'Toggle playtest' }
-    ]
-  },
-  {
-    title: 'Tools',
-    entries: [
-      { action: 'editorToolSelect', label: 'Select' },
-      { action: 'editorToolTerrain', label: 'Terrain' },
-      { action: 'editorToolGadget', label: 'Object' },
-      { action: 'editorToolTrigger', label: 'Trigger' },
-      { action: 'editorToolEntrance', label: 'Entrance' },
-      { action: 'editorToolExit', label: 'Exit' },
-      { action: 'editorToolSteel', label: 'Steel' },
-      { action: 'editorToolBrush', label: 'Brush' },
-      { action: 'editorToolEraser', label: 'Eraser' }
-    ]
-  },
-  {
-    title: 'Edit',
-    entries: [
-      { action: 'editorCopy', label: 'Copy' },
-      { action: 'editorPaste', label: 'Paste' },
-      { action: 'editorDuplicate', label: 'Duplicate' },
-      { action: 'editorUndo', label: 'Undo' },
-      { action: 'editorRedo', label: 'Redo' },
-      { action: 'editorDelete', label: 'Delete selection' },
-      { action: 'editorSnapSelection', label: 'Snap to grid' },
-      { action: 'editorBringToFront', label: 'Bring to front' },
-      { action: 'editorMoveForward', label: 'Move forward' },
-      { action: 'editorMoveBackward', label: 'Move backward' },
-      { action: 'editorSendToBack', label: 'Send to back' }
-    ]
-  },
-  {
-    title: 'Nudge',
-    entries: [
-      { action: 'editorNudgeLeft', label: 'Nudge left' },
-      { action: 'editorNudgeRight', label: 'Nudge right' },
-      { action: 'editorNudgeUp', label: 'Nudge up' },
-      { action: 'editorNudgeDown', label: 'Nudge down' },
-      { action: 'editorNudgeLeftFast', label: 'Nudge left (grid)' },
-      { action: 'editorNudgeRightFast', label: 'Nudge right (grid)' },
-      { action: 'editorNudgeUpFast', label: 'Nudge up (grid)' },
-      { action: 'editorNudgeDownFast', label: 'Nudge down (grid)' }
-    ]
-  }
-];
-
-class EditorUiController {
-  constructor(options = {}) {
-    this.view = options.view || null;
-    this.document = options.document || globalThis.document;
-    this.window = options.window || globalThis.window;
-    this.session = options.session || this.view?.ensureEditorSession?.() || null;
-    this.history = options.history || new EditorHistory({ maxEntries: MAX_HISTORY });
-    this.controller = options.controller || new EditorController({
-      session: this.session,
-      history: this.history
-    });
-    this.assetCache = options.assetCache || new EditorAssetCache();
-    this.previewCache = options.previewCache || new EditorPreviewCache({
-      document: this.document,
-      window: this.window
-    });
-    this.assets = null;
-    this._selection = [];
-    this._activeTab = 'terrain';
-    this._currentSavedId = '';
-    this._playtest = false;
-    this._previewInFlight = false;
-    this._previewQueued = false;
-    this._previewQueuedLabel = null;
-    this._previewQueuedOptions = null;
-    this._cursorPos = null;
-    this._paletteViewMode = 'list';
-    this._paletteGridColumns = 4;
-    this._styleAvailability = new Map();
-    this._suppressHeader = false;
-    this._suppressInspector = false;
-    this._pointerDown = false;
-    this._shiftKey = false;
-    this._altKey = false;
-    this._antsOffset = 0;
-    this._needsDefaultEntrances = false;
-    this.shortcutOverlay = null;
-    this._dirty = false;
-    this._baseTitle = this.document?.title || 'Lemmings Editor';
-
-    this._bindElements();
-    this._bindController();
-  }
-
-  async init() {
-    if (!this.session?.level) {
-      this.view?.createBlankEditorLevel({ render: false });
-      this.session = this.view?.editorSession || this.session;
-      this.controller.session = this.session;
-      this._needsDefaultEntrances = true;
-    }
-    ensureLevelEntryUids(this.session?.level);
-    await this._reloadAssets();
-    this.controller.resetHistory('Init');
-    this._setDirty(false);
-    this._refreshUndoRedo();
-    this._refreshHeaderFields();
-    this._refreshSelection(null);
-    this._refreshValidation();
-    this._refreshSavedList();
-    this._bindEvents();
-    await this._refreshPreview('Init', { preserveView: false });
-  }
-
-  _bindElements() {
-    const get = id => this.document.getElementById(id);
-    this.el = {
-      gameType: get('editorGameTypeSelect'),
-      levelGroup: get('editorLevelGroupSelect'),
-      levelIndex: get('editorLevelIndexSelect'),
-      savedSelect: get('editorSavedSelect'),
-      newLevel: get('editorNewLevel'),
-      savedSave: get('editorSavedSave'),
-      undo: get('editorUndo'),
-      redo: get('editorRedo'),
-      dirtyStatus: get('editorDirtyStatus'),
-      savedExport: get('editorSavedExport'),
-      savedExportClassic: get('editorSavedExportClassic'),
-      savedImport: get('editorSavedImport'),
-      savedImportClassic: get('editorSavedImportClassic'),
-      savedImportInput: get('editorSavedImportInput'),
-      savedImportClassicInput: get('editorSavedImportClassicInput'),
-      playtestToggle: get('editorPlaytestToggle'),
-      toolList: get('editorToolList'),
-      snapToggle: get('editorSnapToggle'),
-      gridSize: get('editorGridSize'),
-      brushSize: get('editorBrushSize'),
-      eraseGadgets: get('editorEraseGadgets'),
-      paletteTabs: get('editorPaletteTabs'),
-      paletteSearch: get('editorPaletteSearch'),
-      paletteViewList: get('editorPaletteViewList'),
-      paletteViewGrid: get('editorPaletteViewGrid'),
-      paletteTerrain: get('editorPaletteTerrain'),
-      paletteGadgets: get('editorPaletteGadgets'),
-      paletteTriggers: get('editorPaletteTriggers'),
-      cursorStatus: get('editorCursorStatus'),
-      status: get('editorStatus'),
-      selectionStatus: get('editorSelectionStatus'),
-      headerTitle: get('editorHeaderTitle'),
-      headerStyle: get('editorHeaderStyle'),
-      headerWidth: get('editorHeaderWidth'),
-      headerHeight: get('editorHeaderHeight'),
-      headerLemmings: get('editorHeaderLemmings'),
-      headerSaveRequirement: get('editorHeaderSaveRequirement'),
-      headerTimeLimit: get('editorHeaderTimeLimit'),
-      headerSpawnInterval: get('editorHeaderSpawnInterval'),
-      headerStartX: get('editorHeaderStartX'),
-      headerStartY: get('editorHeaderStartY'),
-      selType: get('editorSelType'),
-      selName: get('editorSelName'),
-      selX: get('editorSelX'),
-      selY: get('editorSelY'),
-      selWidth: get('editorSelWidth'),
-      selHeight: get('editorSelHeight'),
-      selRotate: get('editorSelRotate'),
-      selSkill: get('editorSelSkill'),
-      selLemmings: get('editorSelLemmings'),
-      selPairing: get('editorSelPairing'),
-      selFlipH: get('editorSelFlipH'),
-      selFlipV: get('editorSelFlipV'),
-      selNoOverwrite: get('editorSelNoOverwrite'),
-      selErase: get('editorSelErase'),
-      selOneWay: get('editorSelOneWay'),
-      selectionActions: get('editorSelectionActions'),
-      selectionFlags: get('editorSelectionFlags'),
-      selectionBringFront: get('editorSelectionBringFront'),
-      selectionMoveForward: get('editorSelectionMoveForward'),
-      selectionMoveBackward: get('editorSelectionMoveBackward'),
-      selectionSendBack: get('editorSelectionSendBack'),
-      deleteSelection: get('editorDeleteSelection'),
-      issuesList: get('editorIssuesList'),
-      shortcutOverlay: get('editorShortcutOverlay')
-    };
-  }
-
-  _bindController() {
-    this.controller.setCallbacks({
-      onSelectionChange: selection => {
-        this._refreshSelection(selection);
-        this._drawSelectionOverlay();
-      },
-      onMarqueeChange: () => {
-        this._drawSelectionOverlay();
-      },
-      onLevelChange: level => {
-        this._refreshHeaderFields(level);
-        this._refreshValidation();
-      },
-      onPreviewRequest: label => {
-        this._refreshPreview(label);
-      }
-    });
-  }
-
-  _bindEvents() {
-    this._bindToolButtons();
-    this._bindPaletteTabs();
-    this._bindPaletteSearch();
-    this._bindPaletteView();
-    this._bindHeaderFields();
-    this._bindSelectionFields();
-    this._bindSelectionActions();
-    this._bindUndoRedo();
-    this._bindBrushControls();
-    this._bindSavedControls();
-    this._bindLevelSelectors();
-    this._bindPlaytest();
-    this._bindCanvasInput();
-    this._bindKeybindings();
-    this._bindShortcutOverlay();
-    this._bindModifierKeys();
-  }
-
-  _bindModifierKeys() {
-    const win = this.window;
-    if (!win?.addEventListener) return;
-    const update = (event) => {
-      this._shiftKey = !!event.shiftKey;
-      this._altKey = !!event.altKey;
-    };
-    win.addEventListener('keydown', update);
-    win.addEventListener('keyup', update);
-    win.addEventListener('blur', () => {
-      this._shiftKey = false;
-      this._altKey = false;
-    });
-  }
-
-  _bindKeybindings() {
-    if (!this.view) return;
-    this.keybindings?.dispose?.();
-    this.keybindings = new EditorKeybindings(this.controller, {
-      fileProvider: this.view.gameFactory?.fileProvider,
-      onBindingsLoaded: () => {
-        this._applyTooltips();
-        this._refreshShortcutOverlay();
-      },
-      onToolChange: tool => {
-        this._setToolButton(tool);
-        this._syncPaletteTabForTool(tool);
-        this._updateStatus();
-      },
-      onCopy: () => {
-        if (this.controller.copySelection()) {
-          this._updateStatus('Copy');
-        }
-      },
-      onPaste: () => {
-        if (this.controller.pasteSelection()) {
-          this._refreshAfterEdit('Paste');
-        }
-      },
-      onDuplicate: () => {
-        if (this.controller.duplicateSelection()) {
-          this._refreshAfterEdit('Duplicate');
-        }
-      },
-      onNudge: (dx, dy, step) => {
-        if (this.controller.nudgeSelection(dx, dy, step)) {
-          this._refreshAfterEdit('Nudge');
-        }
-      },
-      onSnap: () => {
-        if (this.controller.snapSelectionToGrid()) {
-          this._refreshAfterEdit('Snap');
-        }
-      },
-      onUndo: () => {
-        if (this.controller.undo()) {
-          this._refreshAfterEdit('Undo');
-        }
-      },
-      onRedo: () => {
-        if (this.controller.redo()) {
-          this._refreshAfterEdit('Redo');
-        }
-      },
-      onDelete: () => {
-        if (this.controller.deleteSelected()) {
-          this._refreshAfterEdit('Delete');
-        }
-      },
-      onBringToFront: () => {
-        if (this.controller.bringSelectionToFront()) {
-          this._refreshAfterEdit('Reorder');
-        }
-      },
-      onSendToBack: () => {
-        if (this.controller.sendSelectionToBack()) {
-          this._refreshAfterEdit('Reorder');
-        }
-      },
-      onMoveForward: () => {
-        if (this.controller.moveSelectionForward()) {
-          this._refreshAfterEdit('Reorder');
-        }
-      },
-      onMoveBackward: () => {
-        if (this.controller.moveSelectionBackward()) {
-          this._refreshAfterEdit('Reorder');
-        }
-      },
-      onPlaytestToggle: () => this._togglePlaytest(),
-      onToggleShortcutOverlay: () => this._toggleShortcutOverlay()
-    });
-    this.keybindings.bind();
-    this._applyTooltips();
-    this._refreshShortcutOverlay();
-  }
-
-  _bindShortcutOverlay() {
-    if (this.shortcutOverlay || !this.el.shortcutOverlay) return;
-    this.shortcutOverlay = new ShortcutOverlay({
-      root: this.el.shortcutOverlay,
-      title: 'Editor Shortcuts',
-      sections: EDITOR_SHORTCUT_SECTIONS,
-      getBindings: action => this.keybindings?.getDisplayBindings(action) || []
-    });
-  }
-
-  _toggleShortcutOverlay() {
-    this.shortcutOverlay?.toggle();
-  }
-
-  _refreshShortcutOverlay() {
-    if (!this.shortcutOverlay) return;
-    this.shortcutOverlay.render();
-  }
-
-  _bindToolButtons() {
-    if (!this.el.toolList) return;
-    this.el.toolList.addEventListener('click', (event) => {
-      const button = event.target?.closest?.('button');
-      const tool = button?.dataset?.tool;
-      if (!tool) return;
-      this.controller.setTool(tool);
-      this._setToolButton(tool);
-      this._syncPaletteTabForTool(tool);
-      this._updateStatus();
-    });
-    this._setToolButton(this.controller.tool);
-    this._syncPaletteTabForTool(this.controller.tool);
-  }
-
-  _bindPaletteTabs() {
-    if (!this.el.paletteTabs) return;
-    this.el.paletteTabs.addEventListener('click', (event) => {
-      const button = event.target?.closest?.('button');
-      const tab = button?.dataset?.tab;
-      if (!tab) return;
-      this._setPaletteTab(tab);
-    });
-  }
-
-  _bindPaletteSearch() {
-    if (!this.el.paletteSearch) return;
-    this.el.paletteSearch.addEventListener('input', () => {
-      this._applyPaletteFilter();
-    });
-  }
-
-  _bindHeaderFields() {
-    const headerMap = [
-      ['headerTitle', 'TITLE', value => normalizeText(value)],
-      ['headerStyle', 'STYLE', value => normalizeText(value)],
-      ['headerWidth', 'WIDTH', value => parseNumber(value)],
-      ['headerHeight', 'HEIGHT', value => parseNumber(value)],
-      ['headerLemmings', 'LEMMINGS', value => parseNumber(value)],
-      ['headerSaveRequirement', 'SAVE_REQUIREMENT', value => parseNumber(value)],
-      ['headerTimeLimit', 'TIME_LIMIT', value => {
-        const text = normalizeText(value);
-        if (!text) return 'INFINITE';
-        if (text.toUpperCase() === 'INFINITE') return 'INFINITE';
-        return parseNumber(text);
-      }],
-      ['headerSpawnInterval', 'MAX_SPAWN_INTERVAL', value => parseNumber(value)],
-      ['headerStartX', 'START_X', value => parseNumber(value)],
-      ['headerStartY', 'START_Y', value => parseNumber(value)]
-    ];
-
-    for (const [key, headerKey, parser] of headerMap) {
-      const el = this.el[key];
-      if (!el) continue;
-      el.addEventListener('change', async () => {
-        if (this._suppressHeader) return;
-        const parsed = parser(el.value);
-        this.controller.updateHeader(headerKey, parsed);
-        this.controller.history.pushSnapshot(this.session?.level, 'Header');
-        if (headerKey === 'STYLE') {
-          await this._reloadAssets();
-        }
-        this._refreshAfterEdit('Header');
-      });
-    }
-  }
-
-  _bindSelectionFields() {
-    const bindField = (el, handler) => {
-      if (!el) return;
-      el.addEventListener('change', () => {
-        if (this._suppressInspector) return;
-        handler();
-      });
-    };
-
-    bindField(this.el.selX, () => this._commitSelectionPatch({ X: parseNumber(this.el.selX.value) }));
-    bindField(this.el.selY, () => this._commitSelectionPatch({ Y: parseNumber(this.el.selY.value) }));
-    bindField(this.el.selWidth, () => this._commitSelectionPatch({ WIDTH: parseNumber(this.el.selWidth.value) }));
-    bindField(this.el.selHeight, () => this._commitSelectionPatch({ HEIGHT: parseNumber(this.el.selHeight.value) }));
-    bindField(this.el.selRotate, () => {
-      const snapped = normalizeRotation(this.el.selRotate.value);
-      this._commitSelectionPatch({ ROTATE: snapped });
-      this.el.selRotate.value = snapped == null ? '' : String(snapped);
-    });
-    bindField(this.el.selSkill, () => this._commitSelectionPatch({ SKILL: normalizeText(this.el.selSkill.value) }));
-    bindField(this.el.selLemmings, () => this._commitSelectionPatch({ LEMMINGS: parseNumber(this.el.selLemmings.value) }));
-    bindField(this.el.selPairing, () => this._commitSelectionPatch({ PAIRING: parseNumber(this.el.selPairing.value) }));
-
-    bindField(this.el.selFlipH, () => this._commitSelectionPatch({ FLIP_HORIZONTAL: !!this.el.selFlipH.checked }));
-    bindField(this.el.selFlipV, () => this._commitSelectionPatch({ FLIP_VERTICAL: !!this.el.selFlipV.checked }));
-    bindField(this.el.selNoOverwrite, () => this._commitSelectionPatch({ NO_OVERWRITE: !!this.el.selNoOverwrite.checked }));
-    bindField(this.el.selErase, () => this._commitSelectionPatch({ ERASE: !!this.el.selErase.checked }));
-    bindField(this.el.selOneWay, () => this._commitSelectionPatch({ ONE_WAY: !!this.el.selOneWay.checked }));
-
-    if (this.el.deleteSelection) {
-      this.el.deleteSelection.addEventListener('click', () => {
-        if (this.controller.deleteSelected()) {
-          this._refreshAfterEdit('Delete');
-        }
-      });
-    }
-  }
-
-  _bindBrushControls() {
-    if (this.el.snapToggle) {
-      this.el.snapToggle.addEventListener('change', () => {
-        this.controller.setSnapEnabled(this.el.snapToggle.checked);
-        this._updateStatus();
-      });
-    }
-    if (this.el.gridSize) {
-      this.el.gridSize.addEventListener('change', () => {
-        const value = parseNumber(this.el.gridSize.value);
-        this.controller.gridSize = value && value > 0 ? value : 1;
-        this._updateStatus();
-      });
-    }
-    if (this.el.brushSize) {
-      this.el.brushSize.addEventListener('change', () => {
-        const value = parseNumber(this.el.brushSize.value);
-        const next = Number.isFinite(value) ? Math.min(Math.max(value, 1), MAX_BRUSH_SIZE) : 1;
-        this.controller.setBrushSize(next);
-        this.el.brushSize.value = String(next);
-      });
-    }
-    if (this.el.eraseGadgets) {
-      this.el.eraseGadgets.addEventListener('change', () => {
-        this.controller.setEraseGadgets(this.el.eraseGadgets.checked);
-      });
-    }
-  }
-
-  _bindSavedControls() {
-    if (this.el.newLevel) {
-      this.el.newLevel.addEventListener('click', () => {
-        this._createNewLevel();
-      });
-    }
-    if (this.el.savedSelect) {
-      this.el.savedSelect.addEventListener('change', () => {
-        const id = this.el.savedSelect.value;
-        if (!id) return;
-        const text = loadSavedLevel(undefined, id);
-        if (!text) return;
-        this._currentSavedId = id;
-        this._loadLevelFromText(text, { resetSaved: false });
-      });
-    }
-
-    if (this.el.savedSave) {
-      this.el.savedSave.addEventListener('click', () => {
-        this._saveCurrentLevel();
-      });
-    }
-
-    if (this.el.savedExport) {
-      this.el.savedExport.addEventListener('click', () => {
-        this._exportCurrentLevel();
-      });
-    }
-
-    if (this.el.savedExportClassic) {
-      this.el.savedExportClassic.addEventListener('click', () => {
-        this._exportCurrentLevelClassic();
-      });
-    }
-
-    if (this.el.savedImport && this.el.savedImportInput) {
-      this.el.savedImport.addEventListener('click', () => {
-        this.el.savedImportInput.click();
-      });
-      this.el.savedImportInput.addEventListener('change', async (event) => {
-        const file = event.target.files?.[0];
-        if (!file) return;
-        try {
-          const text = await readTextFile(file);
-          if (!text) return;
-          this._currentSavedId = '';
-          this._loadLevelFromText(text, { resetSaved: true });
-        } catch (error) {
-          console.error('Failed to read level file.', error);
-        } finally {
-          event.target.value = '';
-        }
-      });
-    }
-
-    if (this.el.savedImportClassic && this.el.savedImportClassicInput) {
-      this.el.savedImportClassic.addEventListener('click', () => {
-        this.el.savedImportClassicInput.click();
-      });
-      this.el.savedImportClassicInput.addEventListener('change', async (event) => {
-        const file = event.target.files?.[0];
-        if (!file) return;
-        try {
-          const buffer = await readArrayBufferFile(file);
-          if (!buffer) return;
-          const binary = new BinaryReader(buffer, 0, undefined, file.name);
-          const levelReader = new LevelReader(binary);
-          this._currentSavedId = '';
-          this._loadLevelFromClassic(levelReader, { resetSaved: true });
-        } catch (error) {
-          console.error('Failed to read classic level file.', error);
-        } finally {
-          event.target.value = '';
-        }
-      });
-    }
-  }
-
-  _bindLevelSelectors() {
-    if (this.el.gameType) {
-      this.el.gameType.addEventListener('change', async (event) => {
-        const value = this.view?.strToNum?.(event.target.value) ?? event.target.value;
-        await this.view?.selectGameType?.(value);
-        await this._syncAfterSelection('Load');
-      });
-    }
-    if (this.el.levelGroup) {
-      this.el.levelGroup.addEventListener('change', async (event) => {
-        const value = this.view?.strToNum?.(event.target.value) ?? event.target.value;
-        await this.view?.selectLevelGroup?.(value);
-        await this._syncAfterSelection('Load');
-      });
-    }
-    if (this.el.levelIndex) {
-      this.el.levelIndex.addEventListener('change', async (event) => {
-        const value = this.view?.strToNum?.(event.target.value) ?? event.target.value;
-        await this.view?.selectLevel?.(value);
-        await this._syncAfterSelection('Load');
-      });
-    }
-  }
-
-  _bindPlaytest() {
-    if (!this.el.playtestToggle) return;
-    this.el.playtestToggle.addEventListener('click', () => {
-      this._togglePlaytest();
-    });
-  }
-
-  _bindCanvasInput() {
-    const display = this.view?.stage?.getGameDisplay?.();
-    if (!display) return;
-    display.onMouseDown.on(pos => {
-      this._clearActiveInputFocus();
-      if (this._playtest) return;
-      this._pointerDown = true;
-      this.controller.handlePointerDown(pos, 0, { shiftKey: this._shiftKey, altKey: this._altKey });
-      this._updateCursor(pos);
-    });
-    display.onMouseRightDown.on(pos => {
-      this._clearActiveInputFocus();
-      if (this._playtest) return;
-      this._pointerDown = false;
-      this.controller.handlePointerDown(pos, 2, { shiftKey: this._shiftKey, altKey: this._altKey });
-      this._updateCursor(pos);
-    });
-    display.onMouseUp.on(() => {
-      if (this._playtest) return;
-      this._pointerDown = false;
-      this.controller.handlePointerUp();
-      this._refreshAfterEdit('Pointer');
-    });
-    display.onMouseRightUp.on(() => {
-      if (this._playtest) return;
-      this.controller.handlePointerUp();
-      this._refreshAfterEdit('Pointer');
-    });
-    display.onMouseMove.on(pos => {
-      if (this._playtest) return;
-      this.controller.handlePointerMove(pos, { isDown: this._pointerDown });
-      this._updateCursor(pos);
-    });
-  }
-
-  _clearActiveInputFocus() {
-    const doc = this.document;
-    const active = doc?.activeElement;
-    if (!active) return;
-    const tag = active.tagName;
-    if (active.isContentEditable ||
-        tag === 'INPUT' ||
-        tag === 'SELECT' ||
-        tag === 'TEXTAREA') {
-      active.blur?.();
-      if (doc?.body) {
-        doc.body.tabIndex = -1;
-        doc.body.focus?.({ preventScroll: true });
-      }
-    }
-  }
-
-  _updateCursor(pos) {
-    if (!pos) return;
-    this._cursorPos = { x: pos.x, y: pos.y };
-    this._updateStatus();
-  }
-
-  _setToolButton(tool) {
-    const buttons = this.el.toolList?.querySelectorAll?.('button') || [];
-    buttons.forEach(button => {
-      const isActive = button.dataset?.tool === tool;
-      button.classList.toggle('active', isActive);
-      button.setAttribute('aria-pressed', isActive ? 'true' : 'false');
-    });
-  }
-
-  _applyTooltips() {
-    if (!this.keybindings || !this.el.toolList) return;
-    const map = {
-      select: 'editorToolSelect',
-      terrain: 'editorToolTerrain',
-      gadget: 'editorToolGadget',
-      trigger: 'editorToolTrigger',
-      entrance: 'editorToolEntrance',
-      exit: 'editorToolExit',
-      steel: 'editorToolSteel',
-      brush: 'editorToolBrush',
-      eraser: 'editorToolEraser'
-    };
-    const buttons = this.el.toolList.querySelectorAll('button');
-    buttons.forEach(button => {
-      const tool = button.dataset?.tool;
-      const action = map[tool];
-      if (!action) return;
-      const bindings = this.keybindings.getDisplayBindings(action);
-      const base = button.dataset?.tooltip || button.title || '';
-      if (!bindings.length) {
-        if (base) button.title = base;
-        return;
-      }
-      const suffix = bindings.length === 1
-        ? `Shortcut: ${bindings[0]}`
-        : `Shortcuts: ${bindings.join(', ')}`;
-      button.title = base ? `${base} (${suffix})` : suffix;
-    });
-  }
-
-  _setPaletteTab(tab) {
-    this._activeTab = tab;
-    const tabs = this.el.paletteTabs?.querySelectorAll?.('button') || [];
-    tabs.forEach(button => button.classList.toggle('active', button.dataset?.tab === tab));
-    if (this.el.paletteTerrain) this.el.paletteTerrain.hidden = tab !== 'terrain';
-    if (this.el.paletteGadgets) this.el.paletteGadgets.hidden = tab !== 'gadgets';
-    if (this.el.paletteTriggers) this.el.paletteTriggers.hidden = tab !== 'triggers';
-  }
-
-  _syncPaletteTabForTool(tool) {
-    if (tool === 'terrain') {
-      this._setPaletteTab('terrain');
-    } else if (tool === 'gadget') {
-      this._setPaletteTab('gadgets');
-    } else if (tool === 'trigger') {
-      this._setPaletteTab('triggers');
-    }
-  }
-
-  _refreshPalettes() {
-    if (!this.assets) return;
-    this._renderPaletteList(this.el.paletteTerrain, this.assets.terrain, 'terrain');
-    this._renderPaletteList(this.el.paletteGadgets, this.assets.gadgets, 'gadget');
-    this._renderPaletteList(this.el.paletteTriggers, this.assets.triggers, 'trigger');
-    this._applyPaletteFilter();
-    this._setPaletteTab(this._activeTab);
-    this._refreshPaletteSelection();
-  }
-
-  _bindPaletteView() {
-    const setMode = (mode) => {
-      this._paletteViewMode = mode;
-      const isList = mode === 'list';
-      if (this.el.paletteViewList) {
-        this.el.paletteViewList.classList.toggle('active', isList);
-      }
-      if (this.el.paletteViewGrid) {
-        this.el.paletteViewGrid.classList.toggle('active', !isList);
-      }
-      this._applyPaletteViewMode();
-    };
-    if (this.el.paletteViewList) {
-      this.el.paletteViewList.addEventListener('click', () => setMode('list'));
-    }
-    if (this.el.paletteViewGrid) {
-      this.el.paletteViewGrid.addEventListener('click', () => setMode('grid'));
-    }
-    this._applyPaletteViewMode();
-    this._bindPaletteGridZoom();
-  }
-
-  _bindPaletteGridZoom() {
-    const bind = (container) => {
-      if (!container) return;
-      container.addEventListener('wheel', (event) => {
-        if (!event.ctrlKey || this._paletteViewMode !== 'grid') return;
-        event.preventDefault();
-        const direction = event.deltaY > 0 ? 1 : -1;
-        this._setPaletteGridColumns(this._paletteGridColumns + direction);
-      }, { passive: false });
-    };
-    bind(this.el.paletteTerrain);
-    bind(this.el.paletteGadgets);
-    bind(this.el.paletteTriggers);
-  }
-
-  _setPaletteGridColumns(count) {
-    const next = Math.min(6, Math.max(2, Math.round(count)));
-    this._paletteGridColumns = next;
-    this._applyPaletteGridColumns();
-  }
-
-  _applyPaletteGridColumns() {
-    const apply = (container) => {
-      if (!container) return;
-      container.style.setProperty('--palette-grid-columns', String(this._paletteGridColumns));
-    };
-    apply(this.el.paletteTerrain);
-    apply(this.el.paletteGadgets);
-    apply(this.el.paletteTriggers);
-  }
-
-  _applyPaletteViewMode() {
-    const useGrid = this._paletteViewMode === 'grid';
-    const setGrid = (container) => {
-      if (!container) return;
-      container.classList.toggle('grid', useGrid);
-    };
-    setGrid(this.el.paletteTerrain);
-    setGrid(this.el.paletteGadgets);
-    setGrid(this.el.paletteTriggers);
-    this._applyPaletteGridColumns();
-  }
-
-  _getPreviewUrl(entry, type) {
-    if (!this.previewCache || !this.assets) return null;
-    const image = type === 'terrain'
-      ? this.assets.terrainImages?.[entry.id]
-      : this.assets.gadgetImages?.[entry.id];
-    if (!image) return null;
-    return this.previewCache.getPreviewUrl({
-      type,
-      id: entry.id,
-      image
-    });
-  }
-
-  _renderPaletteList(container, items, type) {
-    if (!container) return;
-    container.innerHTML = '';
-    for (const entry of items || []) {
-      const width = Number(entry.width || 0);
-      const height = Number(entry.height || 0);
-      if (width <= 0 && height <= 0) {
-        continue;
-      }
-      const button = this.document.createElement('button');
-      button.type = 'button';
-      button.dataset.id = String(entry.id);
-      button.dataset.type = type;
-      const size = `${entry.width || 0}x${entry.height || 0}`;
-      const triggerFlag = entry.triggerEffectId ? ` | T${entry.triggerEffectId}` : '';
-      const labelText = `#${entry.id} ${entry.name} (${size})${triggerFlag}`;
-      const label = this.document.createElement('span');
-      label.className = 'palette-label';
-      label.textContent = labelText;
-      button.title = `Select ${labelText}`;
-      const previewWrap = this.document.createElement('span');
-      previewWrap.className = 'palette-preview';
-      const previewImg = this.document.createElement('img');
-      previewImg.alt = labelText;
-      previewImg.loading = 'lazy';
-      previewWrap.appendChild(previewImg);
-      button.append(previewWrap, label);
-      button.addEventListener('click', () => {
-        const id = Number(entry.id);
-        if (type === 'terrain') {
-          this.controller.setSelectedTerrain(id);
-        } else if (type === 'trigger') {
-          this.controller.setSelectedTrigger(id);
-          this.controller.setSelectedGadget(id);
-        } else {
-          this.controller.setSelectedGadget(id);
-        }
-        this._refreshPaletteSelection();
-      });
-      const previewUrl = this._getPreviewUrl(entry, type);
-      if (previewUrl) {
-        previewImg.src = previewUrl;
-      } else {
-        previewWrap.classList.add('empty');
-      }
-      container.appendChild(button);
-    }
-  }
-
-  _applyPaletteFilter() {
-    const term = normalizeText(this.el.paletteSearch?.value || '').toLowerCase();
-    const filterList = (container) => {
-      if (!container) return;
-      const items = container.querySelectorAll('button');
-      items.forEach(button => {
-        if (!term) {
-          button.hidden = false;
-          return;
-        }
-        const text = button.textContent?.toLowerCase() || '';
-        button.hidden = !text.includes(term);
-      });
-    };
-    filterList(this.el.paletteTerrain);
-    filterList(this.el.paletteGadgets);
-    filterList(this.el.paletteTriggers);
-  }
-
-  _refreshPaletteSelection() {
-    const setActive = (container, id) => {
-      if (!container) return;
-      const buttons = container.querySelectorAll('button');
-      buttons.forEach(button => {
-        const match = Number(button.dataset.id) === id;
-        button.classList.toggle('active', match);
-      });
-    };
-    setActive(this.el.paletteTerrain, this.controller.selectedTerrainId);
-    setActive(this.el.paletteGadgets, this.controller.selectedGadgetId);
-    setActive(this.el.paletteTriggers, this.controller.selectedTriggerId);
-  }
-
-  _refreshHeaderFields(level = this.session?.level) {
-    if (!level) return;
-    this._suppressHeader = true;
-    if (this.el.headerTitle) this.el.headerTitle.value = formatValue(level.getHeader('TITLE'));
-    if (this.el.headerStyle) this.el.headerStyle.value = formatValue(level.getHeader('STYLE'));
-    if (this.el.headerWidth) this.el.headerWidth.value = formatValue(level.getHeader('WIDTH'));
-    if (this.el.headerHeight) this.el.headerHeight.value = formatValue(level.getHeader('HEIGHT'));
-    if (this.el.headerLemmings) this.el.headerLemmings.value = formatValue(level.getHeader('LEMMINGS'));
-    if (this.el.headerSaveRequirement) this.el.headerSaveRequirement.value = formatValue(level.getHeader('SAVE_REQUIREMENT'));
-    if (this.el.headerTimeLimit) this.el.headerTimeLimit.value = formatValue(level.getHeader('TIME_LIMIT'));
-    if (this.el.headerSpawnInterval) this.el.headerSpawnInterval.value = formatValue(level.getHeader('MAX_SPAWN_INTERVAL'));
-    if (this.el.headerStartX) this.el.headerStartX.value = formatValue(level.getHeader('START_X'));
-    if (this.el.headerStartY) this.el.headerStartY.value = formatValue(level.getHeader('START_Y'));
-    this._suppressHeader = false;
-  }
-
-  async _resolveAvailableStyles() {
-    const config = this.view?.gameResources?.config
-      || await this.view?.gameFactory?.getConfig?.(this.view?.gameType);
-    const pathKey = config?.path || '';
-    if (this._styleAvailability.has(pathKey)) {
-      return this._styleAvailability.get(pathKey);
-    }
-    const styleNames = getStyleNames();
-    const provider = this.view?.gameFactory?.fileProvider;
-    if (!config || !provider?.loadBinary) {
-      this._styleAvailability.set(pathKey, styleNames);
-      return styleNames;
-    }
-    const available = [];
-    for (const name of styleNames) {
-      const style = getStyle(name);
-      const groundSet = Number.isFinite(style?.groundSet) ? style.groundSet | 0 : null;
-      if (groundSet == null) continue;
-      try {
-        await Promise.all([
-          provider.loadBinary(config.path, `VGAGR${groundSet}.DAT`),
-          provider.loadBinary(config.path, `GROUND${groundSet}O.DAT`)
-        ]);
-        available.push(style.name);
-      } catch (e) {
-        // Skip styles missing assets in this pack.
-      }
-    }
-    const list = available.length ? available : styleNames;
-    this._styleAvailability.set(pathKey, list);
-    return list;
-  }
-
-  async _refreshStyleOptions() {
-    const select = this.el.headerStyle;
-    if (!select) return;
-    const current = normalizeText(this.session?.level?.getHeader?.('STYLE'));
-    const styles = await this._resolveAvailableStyles();
-    const normalized = styles.map(name => normalizeText(name));
-    const hasCurrent = current && normalized.includes(current);
-    const options = current && !hasCurrent
-      ? styles.concat([current])
-      : styles.slice();
-    select.innerHTML = '';
-    for (const name of options) {
-      const opt = this.document.createElement('option');
-      opt.value = name;
-      opt.textContent = name;
-      select.appendChild(opt);
-    }
-    if (current) {
-      select.value = current;
-    }
-  }
-
-  _refreshSelection(selection) {
-    const entries = Array.isArray(selection)
-      ? selection
-      : this.controller.getSelectedEntries();
-    this._selection = entries;
-    if (!entries.length) {
-      this._setSelectionFields(null);
-      this._updateSelectionStatus();
-      return;
-    }
-    if (entries.length > 1) {
-      this._setSelectionFields({ multi: true, count: entries.length });
-      this._updateSelectionStatus();
-      return;
-    }
-    const selected = entries[0];
-    const props = selected.entry?.props || {};
-    const isSteel = selected.type === 'steel';
-    const meta = selected.type === 'gadget'
-      ? this.assets?.gadgetById?.get?.(props.PIECE)
-      : this.assets?.terrainById?.get?.(props.PIECE);
-    const name = isSteel ? 'Steel' : (meta?.name || `#${props.PIECE}`);
-    const pieceId = Number(props.PIECE);
-    if (!isSteel && Number.isFinite(pieceId)) {
-      if (selected.type === 'gadget') {
-        this.controller.setSelectedGadget(pieceId);
-      } else {
-        this.controller.setSelectedTerrain(pieceId);
-      }
-      this._refreshPaletteSelection();
-    }
-    this._setSelectionFields({
-      type: selected.type,
-      name,
-      props,
-      meta
-    });
-    this._updateSelectionStatus();
-  }
-
-  _setSelectionFields(data) {
-    this._suppressInspector = true;
-    if (!data) {
-      this._toggleSelectionActions(false);
-      if (this.el.selType) this.el.selType.textContent = 'None';
-      if (this.el.selName) this.el.selName.textContent = '';
-      const inputs = [
-        this.el.selX,
-        this.el.selY,
-        this.el.selWidth,
-        this.el.selHeight,
-        this.el.selRotate,
-        this.el.selSkill,
-        this.el.selLemmings,
-        this.el.selPairing
-      ];
-      inputs.forEach(input => {
-        if (input) {
-          input.value = '';
-          input.disabled = true;
-        }
-      });
-      const checks = [
-        this.el.selFlipH,
-        this.el.selFlipV,
-        this.el.selNoOverwrite,
-        this.el.selErase,
-        this.el.selOneWay
-      ];
-      checks.forEach(check => {
-        if (check) {
-          check.checked = false;
-          check.disabled = true;
-        }
-      });
-      if (this.el.deleteSelection) this.el.deleteSelection.disabled = true;
-      this._suppressInspector = false;
-      return;
-    }
-
-    if (data.multi) {
-      this._toggleSelectionActions(true);
-      if (this.el.selType) this.el.selType.textContent = 'Multiple';
-      if (this.el.selName) this.el.selName.textContent = `${data.count} items`;
-      const inputs = [
-        this.el.selX,
-        this.el.selY,
-        this.el.selWidth,
-        this.el.selHeight,
-        this.el.selRotate,
-        this.el.selSkill,
-        this.el.selLemmings,
-        this.el.selPairing
-      ];
-      inputs.forEach(input => {
-        if (input) {
-          input.value = '';
-          input.disabled = true;
-        }
-      });
-      const checks = [
-        this.el.selFlipH,
-        this.el.selFlipV,
-        this.el.selNoOverwrite,
-        this.el.selErase,
-        this.el.selOneWay
-      ];
-      checks.forEach(check => {
-        if (check) {
-          check.checked = false;
-          check.disabled = true;
-        }
-      });
-      if (this.el.deleteSelection) this.el.deleteSelection.disabled = false;
-      this._suppressInspector = false;
-      return;
-    }
-
-    this._toggleSelectionActions(true);
-    if (this.el.selType) this.el.selType.textContent = data.type;
-    if (this.el.selName) this.el.selName.textContent = data.name || '';
-
-    const props = data.props || {};
-    const meta = data.meta || null;
-    const isGadget = data.type === 'gadget';
-    const isSteel = data.type === 'steel';
-    const supportsResize = isSteel;
-    const widthValue = props.WIDTH ?? (isSteel ? undefined : meta?.width);
-    const heightValue = props.HEIGHT ?? (isSteel ? undefined : meta?.height);
-
-    if (this.el.selX) {
-      this.el.selX.value = formatValue(props.X);
-      this.el.selX.disabled = false;
-    }
-    if (this.el.selY) {
-      this.el.selY.value = formatValue(props.Y);
-      this.el.selY.disabled = false;
-    }
-    if (this.el.selWidth) {
-      this.el.selWidth.value = formatValue(widthValue);
-      this.el.selWidth.disabled = !supportsResize;
-    }
-    if (this.el.selHeight) {
-      this.el.selHeight.value = formatValue(heightValue);
-      this.el.selHeight.disabled = !supportsResize;
-    }
-    if (this.el.selRotate) {
-      this.el.selRotate.value = formatRotation(props.ROTATE);
-      this.el.selRotate.disabled = isSteel;
-    }
-    if (this.el.selSkill) {
-      this.el.selSkill.value = formatValue(props.SKILL);
-      this.el.selSkill.disabled = !isGadget;
-    }
-    if (this.el.selLemmings) {
-      this.el.selLemmings.value = formatValue(props.LEMMINGS);
-      this.el.selLemmings.disabled = !isGadget;
-    }
-    if (this.el.selPairing) {
-      this.el.selPairing.value = formatValue(props.PAIRING);
-      this.el.selPairing.disabled = !isGadget;
-    }
-
-    if (this.el.selFlipH) {
-      this.el.selFlipH.checked = !!props.FLIP_HORIZONTAL;
-      this.el.selFlipH.disabled = isSteel;
-    }
-    if (this.el.selFlipV) {
-      this.el.selFlipV.checked = !!props.FLIP_VERTICAL;
-      this.el.selFlipV.disabled = isSteel;
-    }
-    if (this.el.selNoOverwrite) {
-      this.el.selNoOverwrite.checked = !!props.NO_OVERWRITE;
-      this.el.selNoOverwrite.disabled = isGadget || isSteel;
-    }
-    if (this.el.selErase) {
-      this.el.selErase.checked = !!props.ERASE;
-      this.el.selErase.disabled = isGadget || isSteel;
-    }
-    if (this.el.selOneWay) {
-      this.el.selOneWay.checked = !!props.ONE_WAY;
-      this.el.selOneWay.disabled = true;
-    }
-    if (this.el.deleteSelection) this.el.deleteSelection.disabled = false;
-
-    this._suppressInspector = false;
-  }
-
-  _toggleSelectionActions(visible) {
-    if (this.el.selectionActions) {
-      this.el.selectionActions.hidden = !visible;
-    }
-  }
-
-  _commitSelectionPatch(patch) {
-    const updated = this.controller.updateSelectedProps(patch);
-    if (!updated) return;
-    this.controller.history.pushSnapshot(this.session?.level, 'Edit');
-    this._refreshAfterEdit('Edit');
-  }
-
-  _refreshSavedList(selectedId = this._currentSavedId) {
-    if (!this.el.savedSelect) return;
-    const entries = listSavedLevels();
-    this.el.savedSelect.innerHTML = '';
-    const placeholder = this.document.createElement('option');
-    placeholder.value = '';
-    placeholder.textContent = 'Saved levels';
-    this.el.savedSelect.appendChild(placeholder);
-    for (const entry of entries) {
-      const opt = this.document.createElement('option');
-      opt.value = entry.id;
-      opt.textContent = entry.name;
-      this.el.savedSelect.appendChild(opt);
-    }
-    this.el.savedSelect.value = selectedId || '';
-  }
-
-  _saveCurrentLevel() {
-    if (!this.view?.editorSession?.level) return;
-    const defaultName = this.view.getEditorLevelTitle?.() || 'Untitled';
-    const prompt = this.window?.prompt;
-    if (typeof prompt !== 'function') return;
-    const name = normalizeText(prompt('Save level as', defaultName));
-    if (!name) return;
-    const text = this.view.getEditorLevelText();
-    const id = saveLevel(undefined, {
-      id: this._currentSavedId || undefined,
-      name,
-      text
-    });
-    if (!id) return;
-    this._currentSavedId = id;
-    this._refreshSavedList(id);
-    this._setDirty(false);
-  }
-
-  async _createNewLevel() {
-    if (!this.view) return;
-    this.view.createBlankEditorLevel({ render: false });
-    this.session = this.view.editorSession || this.session;
-    this.controller.session = this.session;
-    ensureLevelEntryUids(this.session?.level);
-    this.controller.resetHistory('New');
-    this._setDirty(false);
-    this._refreshUndoRedo();
-    this._needsDefaultEntrances = true;
-    this._currentSavedId = '';
-    this._refreshSavedList('');
-    await this._reloadAssets();
-    await this._refreshStyleOptions();
-    this._refreshHeaderFields();
-    this._refreshSelection(null);
-    this._refreshValidation();
-    await this._refreshPreview('New', { preserveView: false });
-  }
-
-  _bindSelectionActions() {
-    const bind = (el, handler) => {
-      if (!el) return;
-      el.addEventListener('click', () => {
-        if (handler()) {
-          this._refreshAfterEdit('Reorder');
-        }
-      });
-    };
-    bind(this.el.selectionBringFront, () => this.controller.bringSelectionToFront());
-    bind(this.el.selectionMoveForward, () => this.controller.moveSelectionForward());
-    bind(this.el.selectionMoveBackward, () => this.controller.moveSelectionBackward());
-    bind(this.el.selectionSendBack, () => this.controller.sendSelectionToBack());
-  }
-
-  _bindUndoRedo() {
-    if (this.el.undo) {
-      this.el.undo.addEventListener('click', () => {
-        if (this.controller.undo()) {
-          this._refreshAfterEdit('Undo');
-        }
-      });
-    }
-    if (this.el.redo) {
-      this.el.redo.addEventListener('click', () => {
-        if (this.controller.redo()) {
-          this._refreshAfterEdit('Redo');
-        }
-      });
-    }
-  }
-
-  _ensureDefaultEntrancesExits() {
-    if (!this._needsDefaultEntrances) return;
-    if (!this.assets) return;
-    const viewRect = this.view?.stage?.getGameViewRect?.() || null;
-    const added = this.controller.ensureDefaultEntrancesExits({
-      entranceId: this.assets?.entranceId,
-      exitId: this.assets?.exitId,
-      viewRect
-    });
-    if (added) {
-      this._refreshSelection(null);
-      this._refreshValidation();
-    }
-    if (this.assets?.entranceId != null || this.assets?.exitId != null) {
-      this._needsDefaultEntrances = false;
-    }
-  }
-
-  _exportCurrentLevel() {
-    this._refreshValidation();
-    if (this._hasErrors) {
-      this.window?.alert?.('Fix validation errors before exporting.');
-      return;
-    }
-    const text = this.view.getEditorLevelText();
-    const title = this.view.getEditorLevelTitle();
-    const filename = `${sanitizeFileName(title)}.nxlv`;
-    downloadTextFile(this.document, text, filename);
-  }
-
-  _exportCurrentLevelClassic() {
-    this._refreshValidation();
-    if (this._hasErrors) {
-      this.window?.alert?.('Fix validation errors before exporting.');
-      return;
-    }
-    if (!this.session?.level) return;
-    const classic = createClassicLevelData(this.session.level);
-    if (!classic?.levelReader) return;
-    const writer = new LevelWriter();
-    const payload = {
-      levelProperties: classic.levelReader.levelProperties,
-      screenPositionX: classic.levelReader.screenPositionX,
-      graphicSet1: classic.levelReader.graphicSet1,
-      graphicSet2: classic.levelReader.graphicSet2,
-      isSuperLemming: classic.levelReader.isSuperLemming,
-      objects: classic.levelReader.objects,
-      terrains: classic.levelReader.terrains,
-      steel: classic.levelReader.steel
-    };
-    const bytes = writer.write(payload);
-    const title = this.view.getEditorLevelTitle();
-    const filename = `${sanitizeFileName(title)}.lvl`;
-    downloadBinaryFile(this.document, bytes, filename);
-  }
-
-  async _syncAfterSelection(label) {
-    if (!this.view) return;
-    this._currentSavedId = '';
-    this.session = this.view.editorSession || this.session;
-    this.controller.session = this.session;
-    ensureLevelEntryUids(this.session?.level);
-    this.controller.clearSelection();
-    await this._reloadAssets();
-    this.controller.resetHistory(label || 'Load');
-    this._setDirty(false);
-    this._refreshUndoRedo();
-    this._refreshHeaderFields(this.session?.level);
-    this._refreshSelection(null);
-    this._refreshValidation();
-    this._refreshSavedList('');
-    this._drawSelectionOverlay();
-    this._updateStatus(label || 'Load');
-  }
-
-  _loadLevelFromText(text, options = {}) {
-    if (!this.view) return;
-    const level = this.view.loadEditorLevelFromText(text, { render: false });
-    if (!level) return;
-    this.session = this.view.editorSession;
-    this.controller.session = this.session;
-    ensureLevelEntryUids(this.session?.level);
-    this.controller.clearSelection();
-    this._reloadAssets().then(async () => {
-      this.controller.resetHistory('Import');
-      this._setDirty(false);
-      this._refreshUndoRedo();
-      this._refreshHeaderFields(level);
-      this._refreshSelection(null);
-      this._refreshValidation();
-      if (options.resetSaved) this._refreshSavedList('');
-      await this._refreshPreview('Import', { preserveView: false });
-    });
-  }
-
-  _loadLevelFromClassic(levelReader, options = {}) {
-    if (!this.view) return;
-    const session = this.view.ensureEditorSession?.() || this.session;
-    const editorLevel = createEditorLevelFromClassic(levelReader);
-    if (!editorLevel) return;
-    session.level = editorLevel;
-    this.session = session;
-    this.controller.session = this.session;
-    ensureLevelEntryUids(this.session?.level);
-    this.controller.clearSelection();
-    this._reloadAssets().then(async () => {
-      this.controller.resetHistory('Import LVL');
-      this._setDirty(false);
-      this._refreshUndoRedo();
-      this._refreshHeaderFields(editorLevel);
-      this._refreshSelection(null);
-      this._refreshValidation();
-      if (options.resetSaved) this._refreshSavedList('');
-      await this._refreshPreview('Import LVL', { preserveView: false });
-    });
-  }
-
-  async _reloadAssets() {
-    const config = this.view?.gameResources?.config
-      || await this.view?.gameFactory?.getConfig?.(this.view?.gameType);
-    const styleName = this.session?.level?.getHeader?.('STYLE');
-    this.assets = await this.assetCache.loadStyleAssets(
-      styleName,
-      config,
-      this.view?.gameFactory?.fileProvider
-    );
-    this.controller.setAssets(this.assets);
-    this._refreshPalettes();
-    await this._refreshStyleOptions();
-  }
-
-  async _refreshPreview(label, options = {}) {
-    if (!this.view) return;
-    const preserveView = options.preserveView !== false;
-    if (this._previewInFlight) {
-      this._previewQueued = true;
-      const nextLabel = label || 'Preview';
-      if (this._previewQueuedLabel && this._previewQueuedLabel !== nextLabel) {
-        this._previewQueuedLabel = 'Preview';
-      } else {
-        this._previewQueuedLabel = nextLabel;
-      }
-      const queuedPreserve = this._previewQueuedOptions?.preserveView ?? true;
-      this._previewQueuedOptions = { preserveView: queuedPreserve && preserveView };
-      return;
-    }
-    this._previewInFlight = true;
-    try {
-      await this.view.loadEditorPreviewLevel({
-        suspend: !this._playtest,
-        preserveView
-      });
-      this.view.setEditorPlaytest(this._playtest);
-      this._ensureDefaultEntrancesExits();
-      this._drawSelectionOverlay();
-      this._updateStatus(label || 'Preview');
-    } finally {
-      this._previewInFlight = false;
-      if (this._previewQueued) {
-        const nextLabel = this._previewQueuedLabel || 'Queued';
-        const nextOptions = this._previewQueuedOptions || {};
-        this._previewQueued = false;
-        this._previewQueuedLabel = null;
-        this._previewQueuedOptions = null;
-        this._refreshPreview(nextLabel, nextOptions);
-      }
-    }
-  }
-
-  _refreshAfterEdit(label) {
-    this._refreshValidation();
-    this._drawSelectionOverlay();
-    this._updateStatus(label || 'Edit');
-    this._setDirty(true);
-    this._refreshUndoRedo();
-  }
-
-  _setDirty(isDirty) {
-    this._dirty = !!isDirty;
-    if (this.el.dirtyStatus) {
-      this.el.dirtyStatus.textContent = this._dirty ? 'Unsaved' : 'Saved';
-      this.el.dirtyStatus.classList.toggle('is-dirty', this._dirty);
-    }
-    if (this.document) {
-      this.document.title = this._dirty ? `${this._baseTitle} *` : this._baseTitle;
-    }
-  }
-
-  _refreshUndoRedo() {
-    const canUndo = !!this.controller?.history?.canUndo?.();
-    const canRedo = !!this.controller?.history?.canRedo?.();
-    if (this.el.undo) this.el.undo.disabled = !canUndo;
-    if (this.el.redo) this.el.redo.disabled = !canRedo;
-  }
-
-  _refreshValidation() {
-    const issues = validateLevel(this.session?.level, this.assets || null);
-    this._renderIssues(issues);
-  }
-
-  _renderIssues(issues) {
-    this._hasErrors = false;
-    if (!this.el.issuesList) return;
-    this.el.issuesList.innerHTML = '';
-    for (const issue of issues) {
-      if (issue.severity === 'error') this._hasErrors = true;
-      const item = this.document.createElement('div');
-      item.className = `issue-item ${issue.severity}`;
-      const message = this.document.createElement('div');
-      message.textContent = issue.message;
-      item.appendChild(message);
-      if (issue.fix) {
-        const button = this.document.createElement('button');
-        button.type = 'button';
-        button.textContent = issue.fixLabel || 'Fix';
-        button.title = issue.fixLabel
-          ? `Apply fix: ${issue.fixLabel}`
-          : 'Apply automatic fix.';
-        button.addEventListener('click', () => {
-          issue.fix();
-          this.controller.history.pushSnapshot(this.session?.level, 'Fix');
-          this._refreshAfterEdit('Fix');
-          this._refreshPreview('Fix');
-        });
-        item.appendChild(button);
-      }
-      this.el.issuesList.appendChild(item);
-    }
-  }
-
-  _updateStatus(label) {
-    if (this.el.cursorStatus) {
-      if (this._cursorPos) {
-        const cx = Math.round(this._cursorPos.x);
-        const cy = Math.round(this._cursorPos.y);
-        this.el.cursorStatus.textContent = `X:${cx} Y:${cy}`;
-      } else {
-        this.el.cursorStatus.textContent = 'X:— Y:—';
-      }
-    }
-    if (!this.el.status) return;
-    const parts = [];
-    if (label) parts.push(label);
-    parts.push(`Tool: ${this.controller.tool}`);
-    const grid = this.controller.snapEnabled
-      ? `Grid ${this.controller.gridSize}`
-      : 'Grid off';
-    parts.push(grid);
-    parts.push(this._playtest ? 'Playtest' : 'Edit');
-    this.el.status.textContent = parts.join(' • ');
-  }
-
-  _updateSelectionStatus() {
-    if (!this.el.selectionStatus) return;
-    if (!this._selection || this._selection.length === 0) {
-      this.el.selectionStatus.textContent = 'No selection';
-      return;
-    }
-    if (this._selection.length > 1) {
-      this.el.selectionStatus.textContent = `${this._selection.length} selected`;
-      return;
-    }
-    const selected = this._selection[0];
-    const props = selected.entry?.props || {};
-    const name = selected.type === 'steel'
-      ? 'steel'
-      : (selected.entry?.props?.PIECE ?? 'unknown');
-    this.el.selectionStatus.textContent = `${selected.type} #${name} @ ${props.X ?? 0},${props.Y ?? 0}`;
-  }
-
-  _drawSelectionOverlay() {
-    if (!this.view?.game || !this.view.stage) return;
-    this.view.game.render();
-    const display = this.view.stage.getGameDisplay();
-    const selectedEntries = this.controller.getSelectedEntries();
-    const marquee = this.controller.getMarqueeBounds();
-    const steelEntries = this.session?.level?.steel;
-    if (marquee) {
-      this._antsOffset = (this._antsOffset + 1) % 12;
-      display.drawMarchingAntRect(
-        marquee.x,
-        marquee.y,
-        marquee.width,
-        marquee.height,
-        3,
-        this._antsOffset,
-        0xFFFFFFFF,
-        0x00000000
-      );
-    }
-    if (display?.drawStippleRect && Array.isArray(steelEntries)) {
-      const gridSize = 16;
-      for (const entry of steelEntries) {
-        const bounds = getEntryBounds(entry, null);
-        display.drawStippleRect(
-          bounds.x,
-          bounds.y,
-          bounds.width,
-          bounds.height,
-          0,
-          180,
-          180
-        );
-        for (let x = bounds.x; x <= bounds.x + bounds.width; x += gridSize) {
-          display.drawStippleRect(x, bounds.y, 0, bounds.height, 0, 255, 255);
-        }
-        for (let y = bounds.y; y <= bounds.y + bounds.height; y += gridSize) {
-          display.drawStippleRect(bounds.x, y, bounds.width, 0, 0, 255, 255);
-        }
-      }
-    }
-    for (const selected of selectedEntries) {
-      const meta = selected.type === 'steel'
-        ? null
-        : selected.type === 'gadget'
-          ? this.assets?.gadgetById?.get?.(selected.entry?.props?.PIECE)
-          : this.assets?.terrainById?.get?.(selected.entry?.props?.PIECE);
-      const bounds = getEntryBounds(selected.entry, meta);
-      display.drawDashedRect(bounds.x, bounds.y, bounds.width, bounds.height, 210, 106, 60, 3);
-    }
-    if (selectedEntries.length === 1 && this.controller.canResizeSelection?.()) {
-      const selected = selectedEntries[0];
-      const meta = selected.type === 'steel'
-        ? null
-        : selected.type === 'gadget'
-          ? this.assets?.gadgetById?.get?.(selected.entry?.props?.PIECE)
-          : this.assets?.terrainById?.get?.(selected.entry?.props?.PIECE);
-      const bounds = getEntryBounds(selected.entry, meta);
-      const handleSize = this.controller.getHandleSize();
-      const half = Math.max(1, Math.floor(handleSize / 2));
-      const midX = bounds.x + Math.round(bounds.width / 2);
-      const midY = bounds.y + Math.round(bounds.height / 2);
-      const handles = [
-        [bounds.x, bounds.y],
-        [midX, bounds.y],
-        [bounds.x + bounds.width, bounds.y],
-        [bounds.x + bounds.width, midY],
-        [bounds.x + bounds.width, bounds.y + bounds.height],
-        [midX, bounds.y + bounds.height],
-        [bounds.x, bounds.y + bounds.height],
-        [bounds.x, midY]
-      ];
-      for (const [hx, hy] of handles) {
-        display.drawRect(hx - half, hy - half, handleSize - 1, handleSize - 1, 255, 255, 255, true);
-      }
-    }
-    this.view.stage.redraw();
-  }
-
-  _togglePlaytest() {
-    this._playtest = !this._playtest;
-    this.view?.setEditorPlaytest?.(this._playtest);
-    if (this.el.playtestToggle) {
-      this.el.playtestToggle.classList.toggle('is-active', this._playtest);
-      this.el.playtestToggle.textContent = this._playtest ? 'Playtest On' : 'Playtest';
-    }
-    this._updateStatus('Playtest');
-  }
-}
-
-export { EditorUiController };
+export { EditorUiController } from './editor-ui/EditorUiControllerCore.js';
diff --git a/js/app/midi-ui/midiUiDevices.js b/js/app/midi-ui/midiUiDevices.js
new file mode 100644
index 00000000..089c8fdd
--- /dev/null
+++ b/js/app/midi-ui/midiUiDevices.js
@@ -0,0 +1,44 @@
+const toDeviceList = (devices) => {
+  if (!devices) return [];
+  if (Array.isArray(devices)) return devices;
+  if (typeof devices.values === 'function') return Array.from(devices.values());
+  if (typeof devices[Symbol.iterator] === 'function') return Array.from(devices);
+  return [];
+};
+
+const resolveMidiId = (devices, ...preferredIds) => {
+  const list = toDeviceList(devices);
+  if (!list.length) return null;
+  for (const id of preferredIds) {
+    if (!id) continue;
+    if (list.some(device => device?.id === id)) return id;
+  }
+  return list[0]?.id || null;
+};
+
+const populateMidiSelect = (document, select, devices, emptyLabel) => {
+  const list = toDeviceList(devices);
+  if (!select) return;
+  select.innerHTML = '';
+  if (!list.length) {
+    const opt = document.createElement('option');
+    opt.textContent = emptyLabel;
+    opt.value = '';
+    select.appendChild(opt);
+    select.disabled = true;
+    return;
+  }
+  select.disabled = false;
+  for (const device of list) {
+    const opt = document.createElement('option');
+    opt.textContent = device.name;
+    opt.value = device.id;
+    select.appendChild(opt);
+  }
+};
+
+export {
+  populateMidiSelect,
+  resolveMidiId,
+  toDeviceList
+};
diff --git a/js/app/midi-ui/midiUiDomain.js b/js/app/midi-ui/midiUiDomain.js
index a2af2304..5595e05d 100644
--- a/js/app/midi-ui/midiUiDomain.js
+++ b/js/app/midi-ui/midiUiDomain.js
@@ -1,6 +1,7 @@
 import { SoundEffectIds } from '../../game/SoundEvents.js';
 import { SkillTypes } from '../../game/SkillTypes.js';
 import { TriggerTypes } from '../../level/TriggerTypes.js';
+import { fromMidiFlagTriggerType, toMidiFlagTriggerType } from '../../midi/MidiFlagTriggers.js';
 
 const NOTE_NAMES = ['C', 'C#', 'D', 'D#', 'E', 'F', 'F#', 'G', 'G#', 'A', 'A#', 'B'];
 const CHORD_OPTIONS = [
@@ -13,6 +14,21 @@ const CHORD_OPTIONS = [
   'sus4',
   'octave'
 ];
+const ARP_PATTERN_VERSION = 1;
+const ARP_PATTERN_STEP_OPTIONS = [
+  { value: 'up', label: '↑' },
+  { value: 'down', label: '↓' },
+  { value: 'hold', label: '•' }
+];
+const ARP_PATTERN_PRESETS = [
+  { value: 'up', label: 'Up', steps: ['up'] },
+  { value: 'down', label: 'Down', steps: ['down'] },
+  { value: 'updown', label: 'Up/down', steps: ['up', 'up', 'down', 'down'] },
+  { value: 'custom', label: 'Custom', steps: ['up', 'hold', 'down', 'hold'] }
+];
+const ARP_PATTERN_MAX_STEPS = 16;
+const ARP_PATTERN_MIN_STEPS = 1;
+const ARP_PATTERN_DEFAULT_STEPS = 8;
 const POSITION_AXIS_OPERATORS = [
   { value: 'add', label: '+' },
   { value: 'sub', label: '-' },
@@ -95,6 +111,102 @@ const EXCLUDED_TRIGGER_NAMES = new Set(['UNKNOWN_2', 'UNKNOWN_3']);
 const TRIGGER_NAME_BY_VALUE = new Map(
   Object.entries(TriggerTypes).map(([name, value]) => [value, name])
 );
+const ARP_PATTERN_PRESET_VALUES = new Set(ARP_PATTERN_PRESETS.map(entry => entry.value));
+const ARP_PATTERN_STEP_VALUES = new Set(ARP_PATTERN_STEP_OPTIONS.map(entry => entry.value));
+
+const isPlainObject = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+
+const clampArpPatternLength = (value, fallback = ARP_PATTERN_DEFAULT_STEPS) => {
+  const next = Number.isFinite(value) ? Math.trunc(value) : fallback;
+  return Math.max(ARP_PATTERN_MIN_STEPS, Math.min(ARP_PATTERN_MAX_STEPS, next));
+};
+
+const normalizeArpPatternStep = (value) => {
+  if (typeof value !== 'string') return 'hold';
+  const next = value.trim().toLowerCase();
+  if (!ARP_PATTERN_STEP_VALUES.has(next)) return 'hold';
+  return next;
+};
+
+const resolveArpPatternPreset = (value, fallback = 'up') => {
+  const next = typeof value === 'string' ? value.trim().toLowerCase() : '';
+  if (ARP_PATTERN_PRESET_VALUES.has(next)) return next;
+  return ARP_PATTERN_PRESET_VALUES.has(fallback) ? fallback : 'up';
+};
+
+const createArpPatternFromPreset = (preset, length = ARP_PATTERN_DEFAULT_STEPS) => {
+  const resolvedPreset = resolveArpPatternPreset(preset);
+  const resolvedLength = clampArpPatternLength(length);
+  const presetEntry = ARP_PATTERN_PRESETS.find(entry => entry.value === resolvedPreset)
+    || ARP_PATTERN_PRESETS[0];
+  const source = Array.isArray(presetEntry.steps) && presetEntry.steps.length
+    ? presetEntry.steps
+    : ['up'];
+  const steps = [];
+  for (let i = 0; i < resolvedLength; i += 1) {
+    const value = source[i % source.length];
+    steps.push(normalizeArpPatternStep(value));
+  }
+  return {
+    version: ARP_PATTERN_VERSION,
+    preset: resolvedPreset,
+    steps
+  };
+};
+
+const sanitizeArpPattern = (pattern, fallbackPreset = 'up') => {
+  const source = isPlainObject(pattern) ? pattern : null;
+  const requestedPreset = resolveArpPatternPreset(source?.preset ?? fallbackPreset, fallbackPreset);
+  const requestedLength = clampArpPatternLength(
+    Array.isArray(source?.steps) ? source.steps.length : ARP_PATTERN_DEFAULT_STEPS
+  );
+  const basePattern = createArpPatternFromPreset(requestedPreset, requestedLength);
+  if (!Array.isArray(source?.steps) || !source.steps.length) {
+    return basePattern;
+  }
+  const mappedSteps = source.steps
+    .slice(0, ARP_PATTERN_MAX_STEPS)
+    .map(normalizeArpPatternStep);
+  const normalizedSteps = mappedSteps.length
+    ? mappedSteps
+    : basePattern.steps;
+  const presetSteps = createArpPatternFromPreset(requestedPreset, normalizedSteps.length).steps;
+  const matchesPreset = normalizedSteps.length === presetSteps.length &&
+    normalizedSteps.every((step, idx) => step === presetSteps[idx]);
+  return {
+    version: ARP_PATTERN_VERSION,
+    preset: matchesPreset ? requestedPreset : 'custom',
+    steps: normalizedSteps
+  };
+};
+
+const deriveArpModeFromPattern = (pattern, fallback = 'up') => {
+  const normalized = sanitizeArpPattern(pattern, fallback);
+  if (normalized.preset === 'up' || normalized.preset === 'down' || normalized.preset === 'updown') {
+    return normalized.preset;
+  }
+  const steps = normalized.steps || [];
+  if (!steps.length) return resolveArpPatternPreset(fallback);
+  if (steps.every(step => step === 'down')) return 'down';
+  if (steps.every(step => step === 'up')) return 'up';
+  return resolveArpPatternPreset(fallback);
+};
+
+const migrateArpConfig = (arp) => {
+  if (!isPlainObject(arp)) return null;
+  const next = { ...arp };
+  const mode = resolveArpPatternPreset(next.mode, 'up');
+  const pattern = sanitizeArpPattern(next.pattern, mode);
+  next.mode = deriveArpModeFromPattern(pattern, mode);
+  next.pattern = pattern;
+  if (Number.isFinite(next.length)) {
+    next.length = Math.max(1, Math.min(16, Math.trunc(next.length)));
+  }
+  if (next.independent !== true) {
+    delete next.independent;
+  }
+  return next;
+};
 
 const resolveSkillAvailability = (level, skills) => {
   const available = new Set();
@@ -139,9 +251,60 @@ const collectTriggerTypes = (level) => {
   if (levelHasSteel(level)) {
     types.add(TriggerTypes.STEEL);
   }
+  const midiFlags = Array.isArray(level.midiFlags) ? level.midiFlags : [];
+  for (const flag of midiFlags) {
+    const triggerType = Number.isFinite(flag?.triggerType)
+      ? Math.trunc(flag.triggerType)
+      : toMidiFlagTriggerType(flag?.id);
+    if (Number.isFinite(triggerType)) {
+      types.add(triggerType);
+    }
+  }
   return types;
 };
 
+const buildTriggerLabel = (triggerType) => {
+  if (TRIGGER_NAME_BY_VALUE.has(triggerType)) {
+    return TRIGGER_NAME_BY_VALUE.get(triggerType);
+  }
+  const midiFlagId = fromMidiFlagTriggerType(triggerType);
+  if (midiFlagId != null) {
+    return `MIDI_FLAG_${midiFlagId}`;
+  }
+  return `TRIGGER_${triggerType}`;
+};
+
+const listTriggerEntries = (config = null, availableTriggerTypes = null, level = null) => {
+  const values = new Set();
+  const addValue = (value) => {
+    if (!Number.isFinite(value) || value <= 0) return;
+    const triggerValue = Math.trunc(value);
+    if (availableTriggerTypes && !availableTriggerTypes.has(triggerValue)) return;
+    values.add(triggerValue);
+  };
+  for (const [name, value] of Object.entries(TriggerTypes)) {
+    if (!Number.isFinite(value) || value <= 0 || EXCLUDED_TRIGGER_NAMES.has(name)) continue;
+    addValue(value);
+  }
+  const overrideIds = Object.keys(config?.triggers || {})
+    .map(key => Number(key))
+    .filter(value => Number.isFinite(value));
+  overrideIds.forEach(addValue);
+  if (availableTriggerTypes) {
+    for (const value of availableTriggerTypes) {
+      addValue(value);
+    }
+  }
+  const midiFlags = Array.isArray(level?.midiFlags) ? level.midiFlags : [];
+  for (const flag of midiFlags) {
+    addValue(flag?.triggerType);
+    addValue(toMidiFlagTriggerType(flag?.id));
+  }
+  return Array.from(values)
+    .sort((a, b) => a - b)
+    .map(value => ({ value, name: buildTriggerLabel(value) }));
+};
+
 const collectTrapSfxIds = (level) => {
   const ids = new Set();
   if (!level) return ids;
@@ -231,58 +394,30 @@ const resolvePositionMappings = (config) => {
   if (Array.isArray(position.mappings)) {
     return position.mappings.map(entry => normalizePositionMapping({ ...entry }));
   }
-  const velocityRange = config?.velocityRange || {};
-  const timbreRange = position.timbreRange || {};
-  const mappings = [];
-  if (position.xToNote) {
-    const xRange = position.xNoteRange || {};
-    mappings.push({
-      axis: 'x',
-      axisX: true,
-      axisY: false,
-      axisOp: 'add',
-      target: 'note',
-      min: xRange.min ?? 0,
-      max: xRange.max ?? 0,
-      enabled: true
-    });
-  }
-  if (position.yToVelocity) {
-    mappings.push({
-      axis: 'y',
-      axisX: false,
-      axisY: true,
-      axisOp: 'add',
-      target: 'velocity',
-      min: velocityRange.max ?? 127,
-      max: velocityRange.min ?? 1,
-      enabled: true
-    });
-  }
-  if (position.yToTimbre) {
-    mappings.push({
-      axis: 'y',
-      axisX: false,
-      axisY: true,
-      axisOp: 'add',
-      target: 'timbre',
-      min: timbreRange.max ?? 127,
-      max: timbreRange.min ?? 0,
-      enabled: true
-    });
-  }
-  return mappings;
+  // Hard-cutover behavior: only explicit mapping entries are surfaced to UI.
+  return [];
 };
 
 export {
   NOTE_NAMES,
   CHORD_OPTIONS,
+  ARP_PATTERN_VERSION,
+  ARP_PATTERN_STEP_OPTIONS,
+  ARP_PATTERN_PRESETS,
+  ARP_PATTERN_DEFAULT_STEPS,
+  resolveArpPatternPreset,
+  createArpPatternFromPreset,
+  sanitizeArpPattern,
+  deriveArpModeFromPattern,
+  migrateArpConfig,
   POSITION_AXIS_OPERATORS,
   POSITION_TARGETS,
   REPEAT_TARGETS,
   REPEAT_WINDOW_OPTIONS,
   EXCLUDED_TRIGGER_NAMES,
   TRIGGER_NAME_BY_VALUE,
+  buildTriggerLabel,
+  listTriggerEntries,
   TRAP_SFX_IDS,
   EXCLUDED_SFX_IDS,
   SFX_NAME_BY_ID,
diff --git a/js/app/midi-ui/midiUiStorage.js b/js/app/midi-ui/midiUiStorage.js
deleted file mode 100644
index ba5dcbf8..00000000
--- a/js/app/midi-ui/midiUiStorage.js
+++ /dev/null
@@ -1,63 +0,0 @@
-const midiStorageKeys = {
-  inputId: 'lemmings.midi.inputId',
-  outputId: 'lemmings.midi.outputId',
-  viewPan: 'lemmings.midi.viewPan',
-  enabled: 'lemmings.midi.enabled',
-  inputChannel: 'lemmings.midi.inputChannel',
-  adsrTarget: 'lemmings.midi.adsrTarget',
-  overrides: 'lemmings.midi.overrides',
-  schemaHash: 'lemmings.midi.schemaHash',
-  panelCollapsed: 'lemmings.midi.panelCollapsed',
-  tabLeft: 'lemmings.midi.tabLeft',
-  tabRight: 'lemmings.midi.tabRight',
-  sectionStates: 'lemmings.midi.sectionStates'
-};
-
-const readStoredMidiId = (storage, key) => {
-  try {
-    return storage?.getItem(key) ?? null;
-  } catch (e) {
-    return null;
-  }
-};
-
-const storeMidiId = (storage, key, value) => {
-  try {
-    if (value) {
-      storage?.setItem(key, value);
-    } else {
-      storage?.removeItem(key);
-    }
-  } catch (e) {
-    // Ignore storage failures (private mode, blocked access, etc.).
-  }
-};
-
-const readStoredJson = (storage, key) => {
-  try {
-    const raw = storage?.getItem(key);
-    return raw ? JSON.parse(raw) : null;
-  } catch (e) {
-    return null;
-  }
-};
-
-const storeJson = (storage, key, value) => {
-  try {
-    if (value == null) {
-      storage?.removeItem(key);
-    } else {
-      storage?.setItem(key, JSON.stringify(value));
-    }
-  } catch (e) {
-    // ignore
-  }
-};
-
-export {
-  midiStorageKeys,
-  readStoredMidiId,
-  storeMidiId,
-  readStoredJson,
-  storeJson
-};
diff --git a/js/app/midiUiController.js b/js/app/midiUiController.js
index 73bac32f..f8e99c17 100644
--- a/js/app/midiUiController.js
+++ b/js/app/midiUiController.js
@@ -1,1388 +1,1078 @@
-import { MidiMapping, ScaleLibrary } from '../midi/MidiMapping.js';
-import { TriggerTypes } from '../level/TriggerTypes.js';
+import { getAppContext, getRuntimeDependency } from '../core/dependencies.js';
 import {
-  CHORD_OPTIONS,
-  EXCLUDED_TRIGGER_NAMES,
-  EXCLUDED_SFX_IDS,
-  NOTE_NAMES,
-  POSITION_AXIS_OPERATORS,
-  POSITION_TARGETS,
-  REPEAT_TARGETS,
-  REPEAT_WINDOW_OPTIONS,
-  SFX_NAME_BY_ID,
-  TRAP_SFX_IDS,
-  TRIGGER_NAME_BY_VALUE,
+  AUTOMATION_AXES,
+  AUTOMATION_TARGETS,
+  ARP_MODES,
+  createDefaultMidiStep,
+  createEmptyDirectMapping,
+  createMidiProjectExportPayload,
+  createMidiProjectFromMidiConfig,
+  detectMidiProjectConflicts,
+  importMidiProjectPayload,
+  projectToMidiConfig,
+  reduceMidiProject,
+  sanitizeMidiProject
+} from '../midi/project/MidiProject.js';
+import {
+  PROJECT_STORAGE_KEY,
+  TEMPLATE_STORAGE_KEY,
+  cleanupLegacyMidiProjectStorage,
+  readStoredMidiProject,
+  readStoredMidiProjectTemplates,
+  resetMidiProjectStorage,
+  saveMidiProject,
+  saveMidiProjectTemplate
+} from '../midi/project/MidiProjectStorage.js';
+import {
+  downloadTextFile as downloadTextFileDefault,
+  readTextFile as readTextFileDefault
+} from './editor-ui/editorUiFiles.js';
+import {
+  populateMidiSelect,
+  resolveMidiId,
+  toDeviceList
+} from './midi-ui/midiUiDevices.js';
+import {
+  ARP_PATTERN_PRESETS,
   collectTriggerTypes,
-  resolveAvailableSfxIds,
-  resolvePositionMappings
+  buildTriggerLabel,
+  createArpPatternFromPreset,
+  deriveArpModeFromPattern,
+  POSITION_AXIS_OPERATORS,
+  resolveAvailableSfxIds
 } from './midi-ui/midiUiDomain.js';
+import { isMidiFlagTriggerType, toMidiFlagTriggerType } from '../midi/MidiFlagTriggers.js';
 import {
-  midiStorageKeys,
-  readStoredMidiId,
-  readStoredJson,
-  storeJson,
-  storeMidiId
-} from './midi-ui/midiUiStorage.js';
-
-const mergeDeep = (target, source) => {
-  if (!source || typeof source !== 'object') return target;
-  const out = { ...(target || {}) };
-  for (const [key, value] of Object.entries(source)) {
-    if (value && typeof value === 'object' && !Array.isArray(value)) {
-      out[key] = mergeDeep(out[key], value);
-    } else {
-      out[key] = value;
-    }
-  }
-  return out;
+  buildChordNotes,
+  clampNoteToRange,
+  DEFAULT_SCALES,
+  resolveScale
+} from '../midi/midi-mapping/MidiMappingDomain.js';
+import { cloneSafeObject, isPlainObject } from '../util/safeObject.js';
+
+const SOURCE_KIND_LABELS = Object.freeze({
+  sfx: 'SFX',
+  trigger: 'Trigger',
+  midiFlag: 'MIDI flag',
+  system: 'System',
+  procgen: 'Procgen'
+});
+
+const CHORD_TYPES = Object.freeze([
+  'triad',
+  'seventh',
+  'sixth',
+  'ninth',
+  'power',
+  'sus2',
+  'sus4',
+  'octave'
+]);
+
+const KEY_ROOT_LABELS = Object.freeze(['C', 'C#', 'D', 'D#', 'E', 'F', 'F#', 'G', 'G#', 'A', 'A#', 'B']);
+const SCALE_LABELS = Object.freeze({
+  major: 'Major',
+  minor: 'Minor',
+  dorian: 'Dorian',
+  mixolydian: 'Mixolydian',
+  pentatonic: 'Pentatonic',
+  chromatic: 'Chromatic',
+  'chromatic-minor': 'Chromatic minor'
+});
+
+const AUTOMATION_TARGET_LABELS = Object.freeze({
+  note: 'Note',
+  velocity: 'Velocity',
+  pan: 'Pan',
+  duration: 'Duration',
+  timbre: 'Timbre',
+  attack: 'Attack',
+  decay: 'Decay',
+  sustain: 'Sustain',
+  release: 'Release'
+});
+
+const STEP_FIELD_COUNT = 32;
+const STEP_GRID_COLUMNS = 4;
+const STEP_GRID_TABLET_MAX_WIDTH = 900;
+const STEP_GRID_PHONE_MAX_WIDTH = 520;
+const STEP_GRID_FIELD_CLASSES = Object.freeze([
+  'midi-step-note',
+  'midi-step-velocity',
+  'midi-step-duration',
+  'midi-step-probability',
+  'midi-step-hold',
+  'midi-step-tie',
+  'midi-step-rest'
+]);
+
+const clamp = (value, min, max) => Math.max(min, Math.min(max, value));
+
+const toNumberOrNull = (value) => {
+  if (value === '' || value == null) return null;
+  const number = Number(value);
+  return Number.isFinite(number) ? number : null;
+};
+
+const formatSourceKey = (source) => `${source.kind}:${source.sourceKey}`;
+const domIdSafe = (value, fallback = 'item') => {
+  const text = String(value || fallback).replace(/[^a-zA-Z0-9_-]+/g, '-');
+  return text || fallback;
+};
+const listOptionId = (kind, id) => `midi-${kind}-option-${domIdSafe(id)}`;
+const normalizeStepGridColumns = (value) => {
+  const columns = Math.round(Number(value));
+  return Number.isFinite(columns)
+    ? Math.max(1, Math.min(STEP_GRID_COLUMNS, columns))
+    : STEP_GRID_COLUMNS;
+};
+const filenameSafe = (value, fallback) => {
+  const text = String(value || fallback || 'midi-project')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return text || fallback || 'midi-project';
+};
+
+const isActionableConflict = (issue) => issue?.severity !== 'info';
+
+const setText = (element, value) => {
+  if (element) element.textContent = value;
 };
 
-const isPlainObject = (value) => value && typeof value === 'object' && !Array.isArray(value);
+const setInputValue = (element, value) => {
+  if (!element) return;
+  const next = value == null ? '' : String(value);
+  if (element.value !== next) element.value = next;
+};
+
+const setChecked = (element, value) => {
+  if (element) element.checked = !!value;
+};
+
+const removeChildren = (element) => {
+  if (!element) return;
+  while (element.firstChild) {
+    element.removeChild(element.firstChild);
+  }
+};
 
-const formatNumber = (value, digits = 2) => {
-  if (!Number.isFinite(value)) return '--';
-  const fixed = value.toFixed(digits);
-  if (!fixed.includes('.')) return fixed;
-  return fixed.replace(/\.?0+$/, '');
+const appendOption = (document, select, value, label) => {
+  const option = document.createElement('option');
+  option.value = value == null ? '' : String(value);
+  option.textContent = label;
+  select.appendChild(option);
 };
 
-const formatDebugBytes = (bytes) => {
-  if (!Array.isArray(bytes) || !bytes.length) return '--';
-  return bytes
-    .map(value => Number(value).toString(16).padStart(2, '0'))
-    .join(' ');
+const scalePresetDegrees = (name) => (
+  Array.isArray(DEFAULT_SCALES[name]) ? [...DEFAULT_SCALES[name]] : null
+);
+
+const configureListbox = (list, activeOptionId) => {
+  if (!list) return;
+  list.tabIndex = 0;
+  list.setAttribute('aria-orientation', 'vertical');
+  list.setAttribute('aria-activedescendant', activeOptionId || '');
 };
 
-const formatDebugOutput = (payload) => {
-  if (!payload) return '--';
-  if (Array.isArray(payload)) return formatDebugBytes(payload);
-  if (typeof payload === 'object') {
-    const note = Number.isFinite(payload.note) ? payload.note : '?';
-    const velocity = Number.isFinite(payload.velocity) ? payload.velocity : '?';
-    const channel = Number.isFinite(payload.channel) ? payload.channel : '?';
-    return `note ${note} vel ${velocity} ch ${channel}`;
+const handleListboxNavigation = (event, items, getId, currentId, selectId) => {
+  if (!event || !Array.isArray(items) || !items.length) return false;
+  const key = event.key;
+  if (!['ArrowDown', 'ArrowRight', 'ArrowUp', 'ArrowLeft', 'Home', 'End'].includes(key)) return false;
+  const currentIndex = items.findIndex(item => getId(item) === currentId);
+  let nextIndex = currentIndex;
+  if (key === 'Home') {
+    nextIndex = 0;
+  } else if (key === 'End') {
+    nextIndex = items.length - 1;
+  } else if (key === 'ArrowDown' || key === 'ArrowRight') {
+    nextIndex = currentIndex < 0 ? 0 : Math.min(currentIndex + 1, items.length - 1);
+  } else if (key === 'ArrowUp' || key === 'ArrowLeft') {
+    nextIndex = currentIndex < 0 ? items.length - 1 : Math.max(currentIndex - 1, 0);
   }
-  return String(payload);
+  event.preventDefault?.();
+  const nextId = getId(items[nextIndex]);
+  if (nextId && nextId !== currentId) selectId(nextId);
+  return true;
+};
+
+const stepGridFieldClass = (target) => STEP_GRID_FIELD_CLASSES.find(className => target?.classList?.contains?.(className)) || null;
+
+const sourceChangeSnapshot = (source = {}) => ({
+  enabled: !!source.enabled,
+  trackId: source.trackId || '',
+  mode: source.mode === 'clip' ? 'clip' : 'direct',
+  mapping: source.mode === 'clip' ? null : source.mapping || null,
+  clipId: source.mode === 'clip' ? source.clipId || null : null
+});
+
+const focusStepGridField = (grid, fieldClass, stepIndex) => {
+  const fields = Array.from(grid?.querySelectorAll?.(`.${fieldClass}`) || []);
+  const field = fields.find(item => Number(item.dataset?.stepIndex) === stepIndex);
+  field?.focus?.();
 };
 
+const handleStepGridNavigation = (event, grid, stepCount, columnCount = STEP_GRID_COLUMNS) => {
+  if (!event || stepCount <= 0) return false;
+  const fieldClass = stepGridFieldClass(event.target);
+  if (!fieldClass) return false;
+  const currentIndex = Number(event.target?.dataset?.stepIndex);
+  if (!Number.isInteger(currentIndex)) return false;
+  const key = event.key;
+  if (!['ArrowRight', 'ArrowLeft', 'ArrowDown', 'ArrowUp', 'Home', 'End'].includes(key)) return false;
+  const columns = normalizeStepGridColumns(columnCount);
+  let nextIndex = currentIndex;
+  if (key === 'Home') {
+    nextIndex = 0;
+  } else if (key === 'End') {
+    nextIndex = stepCount - 1;
+  } else if (key === 'ArrowRight') {
+    nextIndex = Math.min(currentIndex + 1, stepCount - 1);
+  } else if (key === 'ArrowLeft') {
+    nextIndex = Math.max(currentIndex - 1, 0);
+  } else if (key === 'ArrowDown') {
+    nextIndex = Math.min(currentIndex + columns, stepCount - 1);
+  } else if (key === 'ArrowUp') {
+    nextIndex = Math.max(currentIndex - columns, 0);
+  }
+  event.preventDefault?.();
+  if (nextIndex !== currentIndex) focusStepGridField(grid, fieldClass, nextIndex);
+  return true;
+};
 
-export const createMidiUiController = ({
-  window = globalThis.window,
-  document = globalThis.document,
-  getLemmings = () => globalThis.lemmings,
-  getWebMidi = () => globalThis.WebMidi,
-  getMidiConfig = null
+const createMidiUiController = ({
+  window = getRuntimeDependency('window', null),
+  document = getRuntimeDependency('document', null),
+  getLemmings = () => getAppContext(),
+  getWebMidi = () => getRuntimeDependency('webMidi', null),
+  getMidiConfig = null,
+  downloadTextFile = downloadTextFileDefault,
+  readTextFile = readTextFileDefault
 } = {}) => {
-  const storage = window?.localStorage;
+  const storage = window?.localStorage || getRuntimeDependency('localStorage', null);
+  const domListeners = [];
+  const outputLog = [];
+  let project = null;
+  let projectNeedsFactory = false;
+  let bound = false;
   let activeMidiInput = null;
-  let midiUiBound = false;
-  let midiViewPanEnabled = false;
   let midiInputController = null;
-  let midiOverrides = readStoredJson(storage, midiStorageKeys.overrides) || {};
-  let envControlsBound = false;
-  let lastUiSignature = null;
-  let noteCapture = null;
-  let lastEnableError = null;
   let deviceRefreshTimer = null;
   let deviceListenersBound = false;
   let deviceListener = null;
-  if (!isPlainObject(midiOverrides)) {
-    midiOverrides = {};
-  }
-  if (typeof globalThis !== 'undefined') {
-    globalThis.lemmingsMidiOverrides = midiOverrides;
-  }
-
-  const resolveMidiId = (devices, ...preferredIds) => {
-    if (!devices || !devices.length) return null;
-    for (const preferredId of preferredIds) {
-      if (preferredId && devices.some(device => device.id === preferredId)) {
-        return preferredId;
-      }
-    }
-    return devices[0].id;
+  let refreshTimer = null;
+  let lastStatus = 'Project loading';
+  let factorySourceIndex = null;
+  const uiMetrics = {
+    renderCount: 0,
+    queuedRenderCount: 0,
+    lastRenderAt: 0,
+    lastRenderDurationMs: 0
+  };
+  const learnState = {
+    active: false,
+    pending: null,
+    sourceId: null,
+    trackId: null,
+    conflicts: []
+  };
+  const recordState = {
+    active: false,
+    clipId: null,
+    trackId: null,
+    notes: [],
+    activeNotes: new Map()
+  };
+  const sourceFilters = {
+    search: '',
+    kind: 'all',
+    assignment: 'all'
   };
 
-  const populateMidiSelect = (select, devices, emptyLabel) => {
-    if (!select) return;
-    select.innerHTML = '';
-    if (!devices || !devices.length) {
-      const opt = document.createElement('option');
-      opt.textContent = emptyLabel;
-      opt.value = '';
-      select.appendChild(opt);
-      select.disabled = true;
-      return;
-    }
-    select.disabled = false;
-    for (const device of devices.values()) {
-      const opt = document.createElement('option');
-      opt.textContent = device.name;
-      opt.value = device.id;
-      select.appendChild(opt);
-    }
+  const getFactoryConfig = () => {
+    if (typeof getMidiConfig === 'function') return getMidiConfig();
+    const lemmings = getLemmings();
+    return lemmings?.getMidiBaseConfig?.() || null;
   };
 
-  const getErrorDisplay = () => document.getElementById('errorDisplay');
+  const captureFactoryProject = (factoryConfig = getFactoryConfig() || {}) => {
+    const factoryProject = createMidiProjectFromMidiConfig(factoryConfig || {});
+    factorySourceIndex = new Map(factoryProject.sources.map(source => [formatSourceKey(source), source]));
+    return factoryProject;
+  };
 
-  const clearErrorDisplay = () => {
-    const errorDisplay = getErrorDisplay();
-    if (errorDisplay) errorDisplay.innerHTML = '';
+  const getFactorySourceIndex = () => {
+    if (!factorySourceIndex) captureFactoryProject();
+    return factorySourceIndex;
   };
 
-  const appendError = (message) => {
-    const errorDisplay = getErrorDisplay();
-    if (!errorDisplay || !message) return;
-    errorDisplay.innerHTML += `${message}<br />`;
+  const defaultRuntimeSourceSnapshot = (source, currentProject = ensureProject()) => sourceChangeSnapshot({
+    enabled: true,
+    trackId: currentProject.tracks[0]?.id || 'track-1',
+    mode: 'direct',
+    mapping: createEmptyDirectMapping(),
+    clipId: null
+  });
+
+  const isSourceChangedFromFactory = (source, factorySources = getFactorySourceIndex(), currentProject = ensureProject()) => {
+    const factorySource = factorySources.get(formatSourceKey(source));
+    const baseline = factorySource
+      ? sourceChangeSnapshot(factorySource)
+      : defaultRuntimeSourceSnapshot(source, currentProject);
+    return JSON.stringify(sourceChangeSnapshot(source)) !== JSON.stringify(baseline);
   };
 
-  const renderErrorDisplay = ({ inputs, outputs } = {}) => {
-    clearErrorDisplay();
-    if (lastEnableError) {
-      appendError(lastEnableError);
-    }
-    if (Array.isArray(inputs) && inputs.length < 1) {
-      appendError('No input device detected.');
-    }
-    if (Array.isArray(outputs) && outputs.length < 1) {
-      appendError('No output device detected.');
+  const sourceBaselinePatch = (source, currentProject = ensureProject(), factorySources = getFactorySourceIndex()) => {
+    const factorySource = factorySources.get(formatSourceKey(source));
+    if (factorySource) {
+      return {
+        label: factorySource.label,
+        enabled: factorySource.enabled,
+        trackId: factorySource.trackId,
+        mode: factorySource.mode,
+        mapping: cloneSafeObject(factorySource.mapping) || createEmptyDirectMapping(),
+        clipId: factorySource.clipId
+      };
     }
+    return {
+      label: source.label,
+      enabled: true,
+      trackId: currentProject.tracks[0]?.id || 'track-1',
+      mode: 'direct',
+      mapping: createEmptyDirectMapping(),
+      clipId: null
+    };
   };
 
-  const showError = (message) => {
-    lastEnableError = message ? String(message) : null;
-    const webMidi = getWebMidi();
-    renderErrorDisplay({
-      inputs: webMidi?.inputs || [],
-      outputs: webMidi?.outputs || []
-    });
+  const getProjectConfig = () => projectToMidiConfig(ensureProject(), getFactoryConfig() || {});
+
+  const getConflictReport = () => detectMidiProjectConflicts(ensureProject(), {
+    availableOutputIds: toDeviceList(getWebMidi()?.outputs)
+      .map(output => output?.id)
+      .filter(Boolean),
+    requireOutput: false
+  });
+
+  const getSourceConflicts = (report, sourceId, { includeInfo = false } = {}) => (
+    (report.bySourceId?.[sourceId] || []).filter(issue => includeInfo || isActionableConflict(issue))
+  );
+
+  const readOrCreateProject = () => {
+    cleanupLegacyMidiProjectStorage(storage);
+    const factory = getFactoryConfig();
+    const factoryProject = factory ? captureFactoryProject(factory) : null;
+    const stored = readStoredMidiProject(storage);
+    if (stored) {
+      projectNeedsFactory = false;
+      return stored;
+    }
+    if (factoryProject) {
+      projectNeedsFactory = false;
+      return saveMidiProject(storage, factoryProject);
+    }
+    projectNeedsFactory = true;
+    return createMidiProjectFromMidiConfig({ enabled: false, sfx: {}, triggers: {} });
   };
 
-  const setActiveMidiInput = (inputId) => {
-    activeMidiInput = null;
-    if (!inputId || !getWebMidi()?.enabled || !midiInputController) {
-      midiInputController?.detach?.();
-      return;
+  const ensureProject = () => {
+    if (!project) {
+      project = readOrCreateProject();
     }
-    const input = getWebMidi().getInputById(inputId);
-    if (!input) return;
-    midiInputController.attach(input);
-    activeMidiInput = input;
+    if (projectNeedsFactory) {
+      const factory = getFactoryConfig();
+      if (factory) {
+        project = saveMidiProject(storage, captureFactoryProject(factory));
+        projectNeedsFactory = false;
+      }
+    }
+    return project;
   };
 
-  const setActiveMidiOutput = (outputId) => {
-    if (!getWebMidi()?.enabled) return;
-    const output = outputId ? getWebMidi().getOutputById(outputId) : null;
+  const getRuntimeLevel = () => {
     const lemmings = getLemmings();
-    if (lemmings?.midiRouter?.scheduler?.allNotesOff) {
-      lemmings.midiRouter.scheduler.allNotesOff();
-      lemmings.midiRouter.scheduler.clearQueue?.();
-    }
-    if (lemmings) {
-      lemmings.midiOut = output || null;
-    }
+    return lemmings?.game?.level || lemmings?.level || null;
   };
 
-  const setMidiOverrides = (patch) => {
-    midiOverrides = mergeDeep(midiOverrides || {}, patch);
-    storeJson(storage, midiStorageKeys.overrides, midiOverrides);
-    if (typeof globalThis !== 'undefined') {
-      globalThis.lemmingsMidiOverrides = midiOverrides;
-    }
+  const getRuntimeSkills = () => {
     const lemmings = getLemmings();
-    if (lemmings?.applyMidiOverrides) {
-      lemmings.applyMidiOverrides(midiOverrides);
-    }
+    return (
+      lemmings?.game?.getGameSkills?.() ||
+      lemmings?.getGameSkills?.() ||
+      lemmings?.game?.skills ||
+      lemmings?.skills ||
+      null
+    );
   };
 
-  const setNoteCapture = (handler) => {
-    noteCapture = handler;
-    if (midiInputController?.setNoteCapture) {
-      midiInputController.setNoteCapture(handler);
-    }
+  const getAvailableSourceKeys = (currentProject = ensureProject()) => {
+    const keys = new Set();
+    const level = getRuntimeLevel();
+    const skills = getRuntimeSkills();
+    const add = (kind, sourceKey) => keys.add(`${kind}:${String(sourceKey)}`);
+    const sfxConfig = { sfx: {} };
+    for (const source of currentProject.sources) {
+      if (source.kind === 'sfx') sfxConfig.sfx[source.sourceKey] = { name: source.label };
+    }
+    for (const id of resolveAvailableSfxIds(sfxConfig, level, skills)) {
+      add('sfx', id);
+    }
+    for (const triggerType of collectTriggerTypes(level)) {
+      if (!isMidiFlagTriggerType(triggerType)) add('trigger', triggerType);
+    }
+    const flags = Array.isArray(level?.midiFlags) ? level.midiFlags : [];
+    for (const flag of flags) {
+      const triggerType = Number.isFinite(flag?.triggerType)
+        ? Math.trunc(flag.triggerType)
+        : toMidiFlagTriggerType(flag?.id);
+      if (Number.isFinite(triggerType)) add('midiFlag', triggerType);
+    }
+    return keys;
   };
 
-  const clearNoteCapture = () => {
-    setNoteCapture(null);
+  const syncRuntimeSources = () => {
+    const current = ensureProject();
+    const level = getRuntimeLevel();
+    if (!level) return current;
+    const byKey = new Set(current.sources.map(formatSourceKey));
+    const nextSources = current.sources.slice();
+    const triggerTypes = collectTriggerTypes(level);
+    for (const triggerType of triggerTypes) {
+      const key = String(triggerType);
+      const kind = 'trigger';
+      const sourceKey = `${kind}:${key}`;
+      if (byKey.has(sourceKey)) continue;
+      byKey.add(sourceKey);
+      nextSources.push({
+        id: `${kind}-${key}`,
+        kind,
+        sourceKey: key,
+        label: buildTriggerLabel(triggerType),
+        enabled: true,
+        trackId: current.tracks[0]?.id || 'track-1',
+        mode: 'direct',
+        mapping: createEmptyDirectMapping(),
+        clipId: null
+      });
+    }
+    const flags = Array.isArray(level.midiFlags) ? level.midiFlags : [];
+    for (const flag of flags) {
+      const triggerType = Number.isFinite(flag?.triggerType)
+        ? Math.trunc(flag.triggerType)
+        : toMidiFlagTriggerType(flag?.id);
+      if (!Number.isFinite(triggerType)) continue;
+      const key = String(triggerType);
+      const kind = 'midiFlag';
+      const sourceKey = `${kind}:${key}`;
+      if (byKey.has(sourceKey)) continue;
+      byKey.add(sourceKey);
+      const idLabel = Number.isFinite(flag?.id) ? `MIDI_FLAG_${flag.id}` : buildTriggerLabel(triggerType);
+      nextSources.push({
+        id: `${kind}-${key}`,
+        kind,
+        sourceKey: key,
+        label: idLabel,
+        enabled: true,
+        trackId: current.tracks[0]?.id || 'track-1',
+        mode: 'direct',
+        mapping: createEmptyDirectMapping(),
+        clipId: null
+      });
+    }
+    if (nextSources.length === current.sources.length) return current;
+    project = saveMidiProject(storage, sanitizeMidiProject({ ...current, sources: nextSources }));
+    return project;
   };
 
-  const applyViewPanSetting = (enabled) => {
-    midiViewPanEnabled = !!enabled;
-    if (typeof globalThis !== 'undefined') {
-      globalThis.lemmingsMidiViewPan = midiViewPanEnabled;
+  const applyProjectToRuntime = () => {
+    const lemmings = getLemmings();
+    if (!lemmings) return;
+    const config = getProjectConfig();
+    if (typeof lemmings.setMidiProjectConfig === 'function') {
+      lemmings.setMidiProjectConfig(config);
     }
-    setMidiOverrides({ position: { viewPan: midiViewPanEnabled } });
+    lemmings.midiEnabled = !!project?.enabled;
   };
 
-  const getConfig = () => {
-    if (typeof getMidiConfig === 'function') return getMidiConfig();
-    const lemmings = getLemmings();
-    return lemmings?.getMidiConfig?.() || lemmings?.getMidiBaseConfig?.() || null;
+  const queueRender = () => {
+    if (refreshTimer != null || typeof window?.setTimeout !== 'function') return;
+    uiMetrics.queuedRenderCount += 1;
+    refreshTimer = window.setTimeout(() => {
+      refreshTimer = null;
+      render();
+    }, 0);
   };
 
-  const getEffectiveConfig = () => {
-    const base = getConfig() || {};
-    return mergeDeep(base, midiOverrides || {});
+  const nowMs = () => {
+    const value = window?.performance?.now?.();
+    return Number.isFinite(value) ? value : Date.now();
   };
 
-  const getSchemaHash = () => getLemmings()?.getMidiSchemaHash?.() || null;
+  const getUiMetrics = () => cloneSafeObject(uiMetrics);
 
-  const clearMidiStorage = () => {
-    storeMidiId(storage, midiStorageKeys.inputId, null);
-    storeMidiId(storage, midiStorageKeys.outputId, null);
-    storeMidiId(storage, midiStorageKeys.viewPan, null);
-    storeMidiId(storage, midiStorageKeys.enabled, null);
-    storeMidiId(storage, midiStorageKeys.inputChannel, null);
-    storeMidiId(storage, midiStorageKeys.adsrTarget, null);
-    storeMidiId(storage, midiStorageKeys.panelCollapsed, null);
-    storeMidiId(storage, midiStorageKeys.tabLeft, null);
-    storeMidiId(storage, midiStorageKeys.tabRight, null);
-    storeJson(storage, midiStorageKeys.sectionStates, null);
-    storeJson(storage, midiStorageKeys.overrides, null);
+  const commitProject = (nextProject, { persist = true, apply = true, renderUi = true } = {}) => {
+    project = sanitizeMidiProject(nextProject);
+    if (persist) project = saveMidiProject(storage, project);
+    if (apply && !renderUi) applyProjectToRuntime();
+    if (renderUi) render();
+    return project;
   };
 
-  const resetMidiDefaults = (persistHash = true) => {
-    const expectedHash = getSchemaHash();
-    clearMidiStorage();
-    midiOverrides = {};
-    if (typeof globalThis !== 'undefined') {
-      globalThis.lemmingsMidiOverrides = midiOverrides;
-    }
-    if (expectedHash && persistHash) {
-      storeMidiId(storage, midiStorageKeys.schemaHash, expectedHash);
-    } else if (!persistHash) {
-      storeMidiId(storage, midiStorageKeys.schemaHash, null);
-    }
-    const lemmings = getLemmings();
-    if (lemmings?.applyMidiOverrides) {
-      lemmings.applyMidiOverrides({});
-    }
+  const dispatchProjectIntent = (intent) => {
+    const current = ensureProject();
+    const factory = getFactoryConfig() || {};
+    const next = intent?.type === 'project.reset'
+      ? captureFactoryProject(factory)
+      : reduceMidiProject(current, intent);
+    return commitProject(next);
   };
 
-  const ensureSchemaHash = () => {
-    const expectedHash = getSchemaHash();
-    if (!expectedHash) return false;
-    const storedHash = readStoredMidiId(storage, midiStorageKeys.schemaHash);
-    if (storedHash && storedHash === expectedHash) return false;
-    resetMidiDefaults(true);
-    return true;
+  const getProjectTemplates = () => readStoredMidiProjectTemplates(storage);
+
+  const selectedTemplateId = () => (
+    document?.getElementById('midiTemplateSelect')?.value ||
+    ensureProject().templateId ||
+    'midi-mapping'
+  );
+
+  const selectedTemplateLabel = (templateId) => {
+    const id = templateId || selectedTemplateId();
+    if (!id || id === 'midi-mapping') return 'Factory';
+    return getProjectTemplates().find(template => template.id === id)?.name || 'Factory';
   };
 
-  const tabStorageKeys = {
-    'midi-left': midiStorageKeys.tabLeft,
-    'midi-right': midiStorageKeys.tabRight
+  const resetProject = (templateId = null) => {
+    const factory = getFactoryConfig() || {};
+    const nextTemplateId = templateId || selectedTemplateId();
+    const nextTemplateLabel = selectedTemplateLabel(nextTemplateId);
+    captureFactoryProject(factory);
+    project = resetMidiProjectStorage(storage, factory, nextTemplateId);
+    projectNeedsFactory = false;
+    applyProjectToRuntime();
+    render();
+    const message = `Reset project from ${nextTemplateLabel}`;
+    setStatus(message);
+    logOutput(message);
+    return project;
   };
 
-  const readSectionStates = () => {
-    const stored = readStoredJson(storage, midiStorageKeys.sectionStates);
-    return isPlainObject(stored) ? stored : {};
+  const setProject = (nextProject) => commitProject(nextProject);
+
+  const saveProjectTemplate = (options = {}) => {
+    const template = saveMidiProjectTemplate(storage, ensureProject(), options);
+    renderTransport();
+    const message = `Saved template ${template.name}`;
+    setStatus(message);
+    logOutput(message);
+    return template;
   };
 
-  const storeSectionStates = (state) => {
-    storeJson(storage, midiStorageKeys.sectionStates, state);
+  const exportProject = (options = {}) => {
+    const current = ensureProject();
+    const payload = createMidiProjectExportPayload(current, options);
+    const name = payload.template?.name || payload.project?.name || current.name;
+    const suffix = options.asTemplate ? 'template' : 'project';
+    const filename = `${filenameSafe(name, `midi-${suffix}`)}.lemmings-midi-${suffix}.json`;
+    if (options.download !== false) {
+      downloadTextFile(
+        document,
+        `${JSON.stringify(payload, null, 2)}\n`,
+        filename,
+        'application/json'
+      );
+      const message = `Exported ${options.asTemplate ? 'template' : 'project'}`;
+      setStatus(message);
+      logOutput(message);
+    }
+    return payload;
   };
 
-  const applySectionStates = ({ useStored = true } = {}) => {
-    const states = useStored ? readSectionStates() : {};
-    const sections = Array.from(document?.querySelectorAll?.('details[data-section-key]') || []);
-    sections.forEach(section => {
-      const key = section.dataset.sectionKey;
-      if (!section.dataset.defaultOpen) {
-        section.dataset.defaultOpen = section.hasAttribute('open') ? 'true' : 'false';
-      }
-      if (useStored && typeof states[key] === 'boolean') {
-        section.open = states[key];
-      } else if (!useStored) {
-        section.open = section.dataset.defaultOpen === 'true';
-      }
-    });
+  const importProject = (payload) => {
+    const imported = importMidiProjectPayload(payload);
+    projectNeedsFactory = false;
+    const next = commitProject(imported);
+    setStatus(`Imported ${next.name}`);
+    logOutput(`Imported ${next.name}`);
+    return next;
   };
 
-  const bindSectionPersistence = () => {
-    const sections = Array.from(document?.querySelectorAll?.('details[data-section-key]') || []);
-    if (!sections.length) return;
-    const states = readSectionStates();
-    sections.forEach(section => {
-      const key = section.dataset.sectionKey;
-      if (!section.dataset.defaultOpen) {
-        section.dataset.defaultOpen = section.hasAttribute('open') ? 'true' : 'false';
-      }
-      if (typeof states[key] === 'boolean') {
-        section.open = states[key];
-      }
-      section.addEventListener('toggle', () => {
-        if (!key) return;
-        const next = readSectionStates();
-        next[key] = section.open;
-        storeSectionStates(next);
-      });
-    });
+  const importProjectFile = async (file) => {
+    if (!file) return null;
+    try {
+      return importProject(await readTextFile(file));
+    } catch (e) {
+      const message = e?.message || 'MIDI project import failed.';
+      showError(message);
+      setStatus('Import failed');
+      logOutput(`Import failed: ${message}`);
+      return null;
+    }
   };
 
-  const setActiveTab = (group, targetId, { persist = false } = {}) => {
-    if (!group) return;
-    const buttons = Array.from(document?.querySelectorAll?.(`.tab-button[data-tab-group="${group}"]`) || []);
-    const panels = Array.from(document?.querySelectorAll?.(`.tab-panel[data-tab-group="${group}"]`) || []);
-    if (!buttons.length || !panels.length) return;
-    const target = targetId || buttons.find(button => button.classList.contains('active'))?.dataset.tabTarget;
-    const finalTarget = target || buttons[0]?.dataset.tabTarget;
-    buttons.forEach(button => button.classList.remove('active'));
-    panels.forEach(panel => panel.classList.remove('active'));
-    const activeButton = buttons.find(button => button.dataset.tabTarget === finalTarget) || buttons[0];
-    const activePanel = panels.find(panel => panel.id === finalTarget) || panels[0];
-    if (activeButton) activeButton.classList.add('active');
-    if (activePanel) activePanel.classList.add('active');
-    const storageKey = tabStorageKeys[group];
-    if (persist && storageKey && activePanel?.id) {
-      storeMidiId(storage, storageKey, activePanel.id);
-    }
-  };
-
-  const applyTabState = ({ useStored = true } = {}) => {
-    const groups = new Set();
-    const buttons = Array.from(document?.querySelectorAll?.('.tab-button[data-tab-group]') || []);
-    buttons.forEach(button => {
-      if (button.dataset.tabGroup) groups.add(button.dataset.tabGroup);
-    });
-    groups.forEach(group => {
-      const storageKey = tabStorageKeys[group];
-      const stored = useStored && storageKey ? readStoredMidiId(storage, storageKey) : null;
-      setActiveTab(group, stored, { persist: false });
-    });
+  const logOutput = (message) => {
+    const text = String(message || '').trim();
+    if (!text) return;
+    outputLog.unshift(`${new Date().toLocaleTimeString()} ${text}`);
+    outputLog.splice(8);
+    renderOutputStatus();
   };
 
-  const bindTabs = () => {
-    const buttons = Array.from(document?.querySelectorAll?.('.tab-button[data-tab-group]') || []);
-    buttons.forEach(button => {
-      button.addEventListener('click', () => {
-        const group = button.dataset.tabGroup;
-        const target = button.dataset.tabTarget;
-        setActiveTab(group, target, { persist: true });
-      });
-    });
-    applyTabState({ useStored: true });
+  const setStatus = (message) => {
+    lastStatus = message;
+    setText(document?.getElementById('midiProjectStatus'), message);
   };
 
-  const resetUiState = () => {
-    storeMidiId(storage, midiStorageKeys.tabLeft, null);
-    storeMidiId(storage, midiStorageKeys.tabRight, null);
-    storeJson(storage, midiStorageKeys.sectionStates, null);
-    applyTabState({ useStored: false });
-    applySectionStates({ useStored: false });
+  const showError = (message) => {
+    setText(document?.getElementById('errorDisplay'), message || '');
   };
 
-  const buildUiSignature = () => {
-    const lemmings = getLemmings();
-    const game = lemmings?.game ?? null;
-    const level = game?.level ?? lemmings?.level ?? null;
-    const skills = game?.getGameSkills?.() ?? null;
-    const skillCounts = skills?.skills ?? level?.skills ?? [];
-    const skillKey = Array.isArray(skillCounts) ? skillCounts.join(',') : '';
-    return [
-      lemmings?.gameType ?? 'none',
-      lemmings?.levelGroupIndex ?? 'none',
-      lemmings?.levelIndex ?? 'none',
-      level?.triggers?.length ?? -1,
-      level?.steelRanges?.length ?? -1,
-      level?.arrowRanges?.length ?? -1,
-      skills?.cheatMode ? 'cheat' : 'no-cheat',
-      skillKey
-    ].join('|');
-  };
-
-  const buildScaleOptions = (select, current) => {
-    if (!select) return;
-    select.innerHTML = '';
-    const names = Object.keys(ScaleLibrary);
-    for (const name of names) {
-      const opt = document.createElement('option');
-      opt.value = name;
-      opt.textContent = name;
-      select.appendChild(opt);
-    }
-    if (current && names.includes(current)) {
-      select.value = current;
+  const renderChannelOptions = (select, value, { includeOmni = false } = {}) => {
+    if (!select || select.dataset.channelsBound === 'true') return;
+    removeChildren(select);
+    if (includeOmni) appendOption(document, select, 'omni', 'Omni');
+    for (let channel = 1; channel <= 16; channel += 1) {
+      appendOption(document, select, channel, String(channel));
     }
+    select.dataset.channelsBound = 'true';
+    select.value = String(value ?? (includeOmni ? 'omni' : 1));
   };
 
-  const buildKeyOptions = (select, current) => {
+  const renderScaleRootOptions = (select, selectedRoot) => {
     if (!select) return;
-    select.innerHTML = '';
-    NOTE_NAMES.forEach((name, idx) => {
-      const opt = document.createElement('option');
-      opt.value = idx.toString();
-      opt.textContent = name;
-      select.appendChild(opt);
-    });
-    if (Number.isFinite(current)) {
-      select.value = String(current);
+    removeChildren(select);
+    for (let root = 0; root < KEY_ROOT_LABELS.length; root += 1) {
+      appendOption(document, select, root, KEY_ROOT_LABELS[root]);
     }
+    select.value = String(selectedRoot ?? 0);
   };
 
-  const buildChannelOptions = (select, current) => {
+  const renderScaleNameOptions = (select, selectedName) => {
     if (!select) return;
-    select.innerHTML = '';
-    const omni = document.createElement('option');
-    omni.value = 'omni';
-    omni.textContent = 'Omni';
-    select.appendChild(omni);
-    for (let ch = 1; ch <= 16; ch++) {
-      const opt = document.createElement('option');
-      opt.value = String(ch);
-      opt.textContent = String(ch);
-      select.appendChild(opt);
-    }
-    if (current) {
-      select.value = String(current);
-    } else {
-      select.value = 'omni';
+    removeChildren(select);
+    for (const name of Object.keys(DEFAULT_SCALES)) {
+      appendOption(document, select, name, SCALE_LABELS[name] || name);
+    }
+    if (selectedName && !DEFAULT_SCALES[selectedName]) {
+      appendOption(document, select, selectedName, selectedName);
     }
+    select.value = selectedName || 'chromatic-minor';
   };
 
-  const buildRepeatTargetOptions = (select, current) => {
-    if (!select) return;
-    select.innerHTML = '';
-    REPEAT_TARGETS.forEach(target => {
-      const opt = document.createElement('option');
-      opt.value = target.value;
-      opt.textContent = target.label;
-      select.appendChild(opt);
-    });
-    if (current) {
-      select.value = String(current);
-    }
+  const selectedTrack = () => {
+    const current = ensureProject();
+    return current.tracks.find(track => track.id === current.ui.selectedTrackId) || current.tracks[0] || null;
   };
 
-  const buildRepeatWindowOptions = (select, current) => {
-    if (!select) return;
-    select.innerHTML = '';
-    REPEAT_WINDOW_OPTIONS.forEach(option => {
-      const opt = document.createElement('option');
-      opt.value = String(option.value);
-      opt.textContent = option.label;
-      select.appendChild(opt);
-    });
-    if (current != null) {
-      const value = String(current);
-      const hasOption = Array.from(select.options || []).some(opt => opt.value === value);
-      if (!hasOption) {
-        const custom = document.createElement('option');
-        custom.value = value;
-        custom.textContent = value;
-        select.appendChild(custom);
-      }
-      select.value = value;
-    }
+  const selectedSource = () => {
+    const current = ensureProject();
+    return current.sources.find(source => source.id === current.ui.selectedSourceId) || current.sources[0] || null;
   };
 
-  const createRow = (labelText, input) => {
-    const label = document.createElement('label');
-    label.className = 'panel-row';
-    const span = document.createElement('span');
-    span.textContent = labelText;
-    label.appendChild(span);
-    label.appendChild(input);
-    return label;
+  const selectedClip = () => {
+    const current = ensureProject();
+    return current.clips.find(clip => clip.id === current.ui.selectedClipId) || current.clips[0] || null;
   };
 
-  const bindRangeInput = (input) => {
-    if (!input) return;
-    const updateTitle = () => {
-      input.title = input.value;
-    };
-    const updateLabels = () => {
-      const parent = input.parentElement || input.parentNode || input.parent;
-      const children = parent?.children || [];
-      const labels = Array.from(children).filter(child => child.classList?.contains('range-label'));
-      if (labels.length > 0) {
-        const minValue = Number(input.min);
-        labels[0].textContent = Number.isFinite(minValue) ? formatNumber(minValue, 2) : '';
-      }
-      if (labels.length > 1) {
-        const maxValue = Number(input.max);
-        labels[labels.length - 1].textContent = Number.isFinite(maxValue) ? formatNumber(maxValue, 2) : '';
-      }
-    };
-    updateTitle();
-    updateLabels();
-    if (input.dataset.rangeBound === 'true') return;
-    input.addEventListener('input', updateTitle);
-    input.addEventListener('change', updateTitle);
-    input.dataset.rangeBound = 'true';
-  };
-
-  const buildMappingEditor = ({ id, name, entry, targetKey, allowIndependentArp = false }) => {
-    const details = document.createElement('details');
-    details.className = 'panel-section';
-    const summary = document.createElement('summary');
-    summary.className = 'panel-title panel-title-row';
-    const summaryTitle = document.createElement('span');
-    summaryTitle.className = 'panel-title-text';
-    summaryTitle.textContent = name || `Event ${id}`;
-    const enabledToggle = document.createElement('input');
-    enabledToggle.type = 'checkbox';
-    const enabledLabel = document.createElement('label');
-    enabledLabel.className = 'panel-title-toggle';
-    const enabledText = document.createElement('span');
-    enabledText.textContent = 'Enabled';
-    enabledLabel.appendChild(enabledText);
-    enabledLabel.appendChild(enabledToggle);
-    summary.appendChild(summaryTitle);
-    summary.appendChild(enabledLabel);
-    details.appendChild(summary);
-
-    summary.addEventListener('click', (event) => {
-      if (enabledLabel.contains(event.target)) return;
-      event.preventDefault();
-      details.open = !details.open;
-    });
+  const selectedLearnSource = () => {
+    const source = selectedSource();
+    return source?.mode === 'clip' ? null : source;
+  };
 
-    const modeSelect = document.createElement('select');
-    ['note', 'degree', 'chord'].forEach(mode => {
-      const opt = document.createElement('option');
-      opt.value = mode;
-      opt.textContent = mode;
-      modeSelect.appendChild(opt);
-    });
-    const noteKeySelect = document.createElement('select');
-    const notePlaceholder = document.createElement('option');
-    notePlaceholder.value = '';
-    notePlaceholder.textContent = '--';
-    noteKeySelect.appendChild(notePlaceholder);
-    NOTE_NAMES.forEach((name, idx) => {
-      const opt = document.createElement('option');
-      opt.value = String(idx);
-      opt.textContent = name;
-      noteKeySelect.appendChild(opt);
-    });
+  const clearLearnCapture = () => {
+    midiInputController?.setNoteCapture?.(null);
+  };
 
-    const noteOctaveInput = document.createElement('input');
-    noteOctaveInput.type = 'number';
-    noteOctaveInput.min = '0';
-    noteOctaveInput.max = '9';
-
-    const degreeInput = document.createElement('input');
-    degreeInput.type = 'number';
-    degreeInput.min = '0';
-    degreeInput.max = '12';
-
-    const octaveInput = document.createElement('input');
-    octaveInput.type = 'number';
-    octaveInput.min = '0';
-    octaveInput.max = '9';
-
-    const chordSelect = document.createElement('select');
-    CHORD_OPTIONS.forEach(chord => {
-      const opt = document.createElement('option');
-      opt.value = chord;
-      opt.textContent = chord;
-      chordSelect.appendChild(opt);
+  const previewLearnProject = (capture) => {
+    const current = ensureProject();
+    const source = current.sources.find(entry => entry.id === learnState.sourceId) || selectedLearnSource();
+    const track = current.tracks.find(entry => entry.id === learnState.trackId) ||
+      current.tracks.find(entry => entry.id === source?.trackId) ||
+      selectedTrack();
+    if (!source || !track || !capture) return current;
+    let preview = reduceMidiProject(current, {
+      type: 'source.mapping.update',
+      sourceId: source.id,
+      patch: {
+        note: capture.note,
+        velocity: capture.velocity,
+        degree: null,
+        notes: null,
+        chord: null
+      }
     });
+    if (track.arm) {
+      preview = reduceMidiProject(preview, {
+        type: 'track.update',
+        trackId: track.id,
+        patch: { channel: capture.channel }
+      });
+    }
+    return preview;
+  };
 
-    const arpToggle = document.createElement('input');
-    arpToggle.type = 'checkbox';
-    const arpMode = document.createElement('select');
-    ['up', 'down', 'updown'].forEach(mode => {
-      const opt = document.createElement('option');
-      opt.value = mode;
-      opt.textContent = mode;
-      arpMode.appendChild(opt);
-    });
-    const arpLength = document.createElement('input');
-    arpLength.type = 'number';
-    arpLength.min = '1';
-    arpLength.max = '8';
-
-    const arpIndependentToggle = document.createElement('input');
-    arpIndependentToggle.type = 'checkbox';
-
-    const priorityInput = document.createElement('input');
-    priorityInput.type = 'number';
-    priorityInput.min = '1';
-    priorityInput.max = '4';
-
-    const initialMode = entry?.chord
-      ? 'chord'
-      : (entry?.degree != null ? 'degree' : 'note');
-    modeSelect.value = initialMode;
-    const noteValue = Number.isFinite(entry?.note) ? entry.note : null;
-    if (noteValue != null) {
-      noteKeySelect.value = String(noteValue % 12);
-      noteOctaveInput.value = String(Math.floor(noteValue / 12));
-    } else {
-      noteKeySelect.value = '';
-      noteOctaveInput.value = '';
-    }
-    degreeInput.value = entry?.degree ?? '';
-    octaveInput.value = entry?.octave ?? '';
-    chordSelect.value = entry?.chord?.type || 'triad';
-    arpToggle.checked = !!entry?.arp?.enabled;
-    arpMode.value = entry?.arp?.mode || 'up';
-    arpLength.value = entry?.arp?.length ?? 3;
-    arpIndependentToggle.checked = !!entry?.arp?.independent;
-    priorityInput.value = entry?.priority ?? '';
-    enabledToggle.checked = !entry?.disabled;
-
-    const updateModeAvailability = () => {
-      const mode = modeSelect.value;
-      const noteEnabled = mode === 'note';
-      const degreeEnabled = mode === 'degree' || mode === 'chord';
-      noteKeySelect.disabled = !noteEnabled;
-      noteOctaveInput.disabled = !noteEnabled;
-      degreeInput.disabled = !degreeEnabled;
-      octaveInput.disabled = !degreeEnabled;
-      chordSelect.disabled = mode !== 'chord';
-    };
-    updateModeAvailability();
-
-    const updateEntry = () => {
-      const next = { ...(entry || {}) };
-      if (name) next.name = name;
-      next.note = null;
-      next.degree = null;
-      next.octave = null;
-      next.chord = null;
-      next.arp = null;
-      next.priority = null;
-      next.disabled = false;
-      const mode = modeSelect.value;
-      if (mode === 'note' && noteKeySelect.value !== '' && noteOctaveInput.value !== '') {
-        const key = Number(noteKeySelect.value);
-        const octave = Number(noteOctaveInput.value);
-        if (Number.isFinite(key) && Number.isFinite(octave)) {
-          next.note = Math.max(0, Math.min(127, key + octave * 12));
-        }
-      }
-      if (mode === 'degree' || mode === 'chord') {
-        if (degreeInput.value !== '') next.degree = Number(degreeInput.value);
-        if (octaveInput.value !== '') next.octave = Number(octaveInput.value);
-      }
-      if (mode === 'chord') {
-        next.chord = { type: chordSelect.value || 'triad' };
-      }
-      if (arpToggle.checked) {
-        next.arp = { enabled: true, mode: arpMode.value, length: Number(arpLength.value) || 3 };
-        if (allowIndependentArp && arpIndependentToggle.checked) {
-          next.arp.independent = true;
-        }
-      }
-      if (priorityInput.value !== '') next.priority = Number(priorityInput.value);
-      if (!enabledToggle.checked) next.disabled = true;
-      const patch = { [targetKey]: { [String(id)]: next } };
-      setMidiOverrides(patch);
-    };
+  const renderLearnPanel = () => {
+    const panel = document?.getElementById('midiLearnPanel');
+    if (!panel) return;
+    const status = document?.getElementById('midiLearnStatus');
+    const confirm = document?.getElementById('midiLearnConfirmButton');
+    const cancel = document?.getElementById('midiLearnCancelButton');
+    const learn = document?.getElementById('midiLearnButton');
+    const source = selectedLearnSource();
+    panel.classList.toggle('is-active', learnState.active || !!learnState.pending);
+    if (learn) learn.disabled = !source;
+    if (confirm) confirm.disabled = !learnState.pending;
+    if (cancel) cancel.disabled = !learnState.active && !learnState.pending;
+    if (!status) return;
+    if (!source) {
+      status.textContent = 'Learn needs a direct source.';
+      return;
+    }
+    if (learnState.pending) {
+      const conflictText = learnState.conflicts.length
+        ? ` ${learnState.conflicts.length} warning${learnState.conflicts.length === 1 ? '' : 's'}.`
+        : ' No conflicts.';
+      status.textContent = `Pending note ${learnState.pending.note}, velocity ${learnState.pending.velocity}, channel ${learnState.pending.channel}.${conflictText}`;
+      return;
+    }
+    status.textContent = learnState.active
+      ? `Listening for ${source.label}.`
+      : 'Learn waits for the next note-on.';
+  };
 
-    const resolveScaleForNote = () => {
-      const config = getConfig();
-      const scale = config?.scale || {};
-      const root = Number.isFinite(scale.root) ? scale.root : 0;
-      const degrees = Array.isArray(scale.degrees) && scale.degrees.length
-        ? scale.degrees
-        : (ScaleLibrary[scale.name] || ScaleLibrary['chromatic-minor'] || NOTE_NAMES.map((_, idx) => idx));
-      return { root, degrees };
+  const handleLearnNote = (note, velocity, channel) => {
+    if (!learnState.active) return false;
+    const capture = {
+      note: clamp(Math.round(note), 0, 127),
+      velocity: clamp(Math.round(velocity), 1, 127),
+      channel: clamp(Math.round(channel), 1, 16)
     };
+    learnState.pending = capture;
+    const preview = previewLearnProject(capture);
+    const report = detectMidiProjectConflicts(preview);
+    learnState.conflicts = learnState.sourceId
+      ? (report.bySourceId?.[learnState.sourceId] || []).filter(isActionableConflict)
+      : [];
+    clearLearnCapture();
+    setStatus('Learn note captured');
+    renderLearnPanel();
+    return true;
+  };
 
-    const noteToScaleDegree = (note) => {
-      const { root, degrees } = resolveScaleForNote();
-      const relative = ((note - root) % 12 + 12) % 12;
-      let degreeIndex = degrees.indexOf(relative);
-      if (degreeIndex < 0) {
-        let best = 0;
-        let bestDist = 99;
-        degrees.forEach((deg, idx) => {
-          const dist = Math.min(Math.abs(deg - relative), 12 - Math.abs(deg - relative));
-          if (dist < bestDist) {
-            bestDist = dist;
-            best = idx;
-          }
-        });
-        degreeIndex = best;
-      }
-      const degreeOffset = degrees[degreeIndex] ?? 0;
-      const octave = Math.max(0, Math.floor((note - root - degreeOffset) / 12));
-      return { degree: degreeIndex, octave };
-    };
+  const startLearn = () => {
+    const source = selectedLearnSource();
+    const track = selectedTrack();
+    if (!source || !track) {
+      setStatus('Learn unavailable');
+      renderLearnPanel();
+      return false;
+    }
+    if (hasRecordCapture()) cancelRecording();
+    learnState.active = true;
+    learnState.pending = null;
+    learnState.sourceId = source.id;
+    learnState.trackId = track.id;
+    learnState.conflicts = [];
+    midiInputController?.setNoteCapture?.(handleLearnNote);
+    setStatus('Learning next note');
+    renderLearnPanel();
+    return true;
+  };
 
-    const applyLearnedNote = (note) => {
-      if (!Number.isFinite(note)) return;
-      if (modeSelect.value === 'note') {
-        noteKeySelect.value = String(note % 12);
-        noteOctaveInput.value = String(Math.floor(note / 12));
-      } else {
-        const resolved = noteToScaleDegree(note);
-        degreeInput.value = String(resolved.degree);
-        octaveInput.value = String(resolved.octave);
-      }
-      updateEntry();
-    };
+  const cancelLearn = () => {
+    learnState.active = false;
+    learnState.pending = null;
+    learnState.sourceId = null;
+    learnState.trackId = null;
+    learnState.conflicts = [];
+    clearLearnCapture();
+    setStatus('Learn canceled');
+    renderLearnPanel();
+    return true;
+  };
 
-    const bindNoteCapture = (row, input) => {
-      if (!row || !input) return;
-      const arm = () => {
-        if (input.disabled) return;
-        setNoteCapture((captureNote) => {
-          applyLearnedNote(captureNote);
-          clearNoteCapture();
-          return true;
-        });
-      };
-      const label = typeof row.querySelector === 'function'
-        ? row.querySelector('span')
-        : (row.children ? row.children[0] : null);
-      if (label) {
-        label.addEventListener('click', (event) => {
-          event.preventDefault();
-          event.stopPropagation();
-          if (typeof input.focus === 'function') input.focus();
-          arm();
-        });
-      }
-      input.addEventListener('focus', arm);
-      input.addEventListener('blur', clearNoteCapture);
-    };
+  const hasLearnCapture = () => learnState.active || !!learnState.pending;
 
-    modeSelect.addEventListener('change', () => {
-      updateModeAvailability();
-      updateEntry();
-    });
-    [noteKeySelect, noteOctaveInput, degreeInput, octaveInput, chordSelect, arpToggle, arpMode, arpLength, arpIndependentToggle, priorityInput, enabledToggle]
-      .forEach(el => el.addEventListener('change', updateEntry));
-
-    const modeRow = createRow('Mode', modeSelect);
-    const keyRow = createRow('Key', noteKeySelect);
-    const octaveRow = createRow('Octave', noteOctaveInput);
-    const degreeRow = createRow('Degree', degreeInput);
-    const scaleOctaveRow = createRow('Scale octave', octaveInput);
-    details.appendChild(modeRow);
-    details.appendChild(keyRow);
-    details.appendChild(octaveRow);
-    details.appendChild(degreeRow);
-    details.appendChild(scaleOctaveRow);
-    details.appendChild(createRow('Chord', chordSelect));
-    details.appendChild(createRow('Arp', arpToggle));
-    details.appendChild(createRow('Arp mode', arpMode));
-    details.appendChild(createRow('Arp length', arpLength));
-    if (allowIndependentArp) {
-      details.appendChild(createRow('Independent arp', arpIndependentToggle));
-    }
-    details.appendChild(createRow('Priority', priorityInput));
-    enabledLabel.addEventListener('click', (event) => event.stopPropagation());
-    enabledToggle.addEventListener('click', (event) => event.stopPropagation());
-    bindNoteCapture(keyRow, noteKeySelect);
-    bindNoteCapture(octaveRow, noteOctaveInput);
-    bindNoteCapture(degreeRow, degreeInput);
-    bindNoteCapture(scaleOctaveRow, octaveInput);
-    return details;
-  };
-
-  const resolvePositionDefaults = (entry, config) => {
-    const position = config?.position || {};
-    const velocityRange = config?.velocityRange || {};
-    const durationRange = config?.durationTicks || {};
-    const target = entry?.target || 'velocity';
-    switch (target) {
-    case 'note':
-      return {
-        min: position.xNoteRange?.min ?? 0,
-        max: position.xNoteRange?.max ?? 0
-      };
-    case 'velocity':
-      return {
-        min: velocityRange.min ?? 1,
-        max: velocityRange.max ?? 127
-      };
-    case 'timbre':
-      return {
-        min: position.timbreRange?.min ?? 0,
-        max: position.timbreRange?.max ?? 127
-      };
-    case 'pan':
-      return {
-        min: position.panRange?.min ?? -127,
-        max: position.panRange?.max ?? 127
-      };
-    case 'duration':
-      return {
-        min: durationRange.min ?? 1,
-        max: durationRange.max ?? 24
-      };
-    case 'pitchBend':
-      return { min: -1, max: 1 };
-    case 'attack':
-    case 'decay':
-    case 'release':
-      return { min: 0, max: 2 };
-    case 'sustain':
-      return { min: 0.25, max: 2 };
-    default:
-      return { min: null, max: null };
-    }
-  };
-
-  const buildPositionMappingList = (container, mappings, config) => {
-    if (!container) return;
-    container.innerHTML = '';
-    (mappings || []).forEach((entry, index) => {
-      const axisXToggle = document.createElement('input');
-      axisXToggle.type = 'checkbox';
-      const axisYToggle = document.createElement('input');
-      axisYToggle.type = 'checkbox';
-      const axisOpSelect = document.createElement('select');
-      POSITION_AXIS_OPERATORS.forEach(operator => {
-        const opt = document.createElement('option');
-        opt.value = operator.value;
-        opt.textContent = operator.label;
-        axisOpSelect.appendChild(opt);
-      });
-      const axis = entry?.axis || 'x';
-      let axisX = typeof entry?.axisX === 'boolean' ? entry.axisX : null;
-      let axisY = typeof entry?.axisY === 'boolean' ? entry.axisY : null;
-      if (axisX == null && axisY == null) {
-        if (axis === 'xy') {
-          axisX = true;
-          axisY = true;
-        } else if (axis === 'y') {
-          axisX = false;
-          axisY = true;
-        } else {
-          axisX = true;
-          axisY = false;
-        }
-      }
-      if (!axisX && !axisY) {
-        axisX = true;
+  const confirmLearn = () => {
+    if (!learnState.pending || !learnState.sourceId) {
+      renderLearnPanel();
+      return false;
+    }
+    const current = ensureProject();
+    const source = current.sources.find(entry => entry.id === learnState.sourceId);
+    const track = current.tracks.find(entry => entry.id === learnState.trackId) ||
+      current.tracks.find(entry => entry.id === source?.trackId);
+    if (!source || source.mode === 'clip') {
+      cancelLearn();
+      return false;
+    }
+    let next = reduceMidiProject(current, {
+      type: 'source.mapping.update',
+      sourceId: source.id,
+      patch: {
+        note: learnState.pending.note,
+        velocity: learnState.pending.velocity,
+        degree: null,
+        notes: null,
+        chord: null
       }
-      axisXToggle.checked = !!axisX;
-      axisYToggle.checked = !!axisY;
-      axisOpSelect.value = entry?.axisOp || 'add';
-
-      const axisControl = document.createElement('div');
-      axisControl.className = 'axis-toggle';
-      const axisXLabel = document.createElement('label');
-      axisXLabel.className = 'axis-checkbox';
-      axisXLabel.appendChild(axisXToggle);
-      const axisXText = document.createElement('span');
-      axisXText.textContent = 'X';
-      axisXLabel.appendChild(axisXText);
-      const axisYLabel = document.createElement('label');
-      axisYLabel.className = 'axis-checkbox';
-      axisYLabel.appendChild(axisYToggle);
-      const axisYText = document.createElement('span');
-      axisYText.textContent = 'Y';
-      axisYLabel.appendChild(axisYText);
-      axisControl.appendChild(axisXLabel);
-      axisControl.appendChild(axisOpSelect);
-      axisControl.appendChild(axisYLabel);
-
-      const targetSelect = document.createElement('select');
-      POSITION_TARGETS.forEach(target => {
-        const opt = document.createElement('option');
-        opt.value = target.value;
-        opt.textContent = target.label;
-        targetSelect.appendChild(opt);
+    });
+    if (track?.arm) {
+      next = reduceMidiProject(next, {
+        type: 'track.update',
+        trackId: track.id,
+        patch: { channel: learnState.pending.channel }
       });
-      targetSelect.value = entry?.target || 'velocity';
-
-      const minInput = document.createElement('input');
-      minInput.type = 'number';
-      minInput.step = '0.1';
-      minInput.className = 'input-mini input-align-right';
-      if (Number.isFinite(entry?.min)) {
-        minInput.value = String(entry.min);
-      }
-
-      const maxInput = document.createElement('input');
-      maxInput.type = 'number';
-      maxInput.step = '0.1';
-      maxInput.className = 'input-mini input-align-right';
-      if (Number.isFinite(entry?.max)) {
-        maxInput.value = String(entry.max);
-      }
+    }
+    const label = source.label;
+    learnState.active = false;
+    learnState.pending = null;
+    learnState.sourceId = null;
+    learnState.trackId = null;
+    learnState.conflicts = [];
+    clearLearnCapture();
+    commitProject(next);
+    const message = `Learned ${label}`;
+    setStatus(message);
+    logOutput(message);
+    return true;
+  };
 
-      const enabledToggle = document.createElement('input');
-      enabledToggle.type = 'checkbox';
-      enabledToggle.checked = entry?.enabled !== false;
+  const clearRecordCapture = () => {
+    midiInputController?.setMessageCapture?.(null);
+  };
 
-      const removeButton = document.createElement('button');
-      removeButton.type = 'button';
-      removeButton.textContent = 'Remove';
-      removeButton.className = 'button-danger button-compact';
+  const resetRecordState = () => {
+    recordState.active = false;
+    recordState.clipId = null;
+    recordState.trackId = null;
+    recordState.notes = [];
+    recordState.activeNotes.clear();
+  };
 
-      const updateAxisUi = () => {
-        if (!axisXToggle.checked && !axisYToggle.checked) {
-          axisXToggle.checked = true;
-        }
-        const showOp = axisXToggle.checked && axisYToggle.checked;
-        axisOpSelect.hidden = !showOp;
-        axisOpSelect.disabled = !showOp;
-      };
-      updateAxisUi();
+  const renderRecordPanel = () => {
+    const panel = document?.getElementById('midiRecordPanel');
+    if (!panel) return;
+    const status = document?.getElementById('midiRecordStatus');
+    const start = document?.getElementById('midiRecordButton');
+    const commit = document?.getElementById('midiRecordCommitButton');
+    const cancel = document?.getElementById('midiRecordCancelButton');
+    const clip = selectedClip();
+    panel.classList.toggle('is-active', recordState.active || recordState.notes.length > 0);
+    if (start) start.disabled = !clip || recordState.active;
+    if (commit) commit.disabled = !recordState.notes.length && !recordState.activeNotes.size;
+    if (cancel) cancel.disabled = !recordState.active && !recordState.notes.length;
+    if (!status) return;
+    if (!clip) {
+      status.textContent = 'Create a clip before recording.';
+      return;
+    }
+    if (recordState.active) {
+      status.textContent = `Recording into ${clip.name}: ${recordState.notes.length} notes captured.`;
+      return;
+    }
+    status.textContent = recordState.notes.length
+      ? `${recordState.notes.length} notes ready to commit.`
+      : 'Record writes captured notes into clip steps.';
+  };
 
-      const updateRangePlaceholders = (target) => {
-        const rangeDefaults = resolvePositionDefaults({ target }, config);
-        minInput.placeholder = Number.isFinite(rangeDefaults.min) ? String(rangeDefaults.min) : '';
-        maxInput.placeholder = Number.isFinite(rangeDefaults.max) ? String(rangeDefaults.max) : '';
-      };
-      updateRangePlaceholders(targetSelect.value);
-
-      const updateEntry = () => {
-        const next = (mappings || []).map((item, idx) => {
-          if (idx !== index) return { ...item };
-          const minValue = minInput.value === '' ? null : Number(minInput.value);
-          const maxValue = maxInput.value === '' ? null : Number(maxInput.value);
-          const axisX = axisXToggle.checked;
-          const axisY = axisYToggle.checked;
-          const nextEntry = {
-            ...item,
-            axis: axisX && axisY ? 'xy' : (axisX ? 'x' : 'y'),
-            axisX,
-            axisY,
-            axisOp: axisOpSelect.value || 'add',
-            target: targetSelect.value,
-            enabled: !!enabledToggle.checked
-          };
-          if (Number.isFinite(minValue)) nextEntry.min = minValue;
-          else delete nextEntry.min;
-          if (Number.isFinite(maxValue)) nextEntry.max = maxValue;
-          else delete nextEntry.max;
-          return nextEntry;
-        });
-        setMidiOverrides({ position: { mappings: next } });
-      };
+  const noteKey = (event) => `${event.channel}:${event.note}`;
 
-      const removeEntry = () => {
-        const next = (mappings || []).filter((_, idx) => idx !== index);
-        setMidiOverrides({ position: { mappings: next } });
-        window?.setTimeout?.(() => {
-          try {
-            refreshMidiUiFromConfig();
-          } catch (e) {
-            console.error('MIDI UI refresh failed', e);
-          }
-        }, 0);
-      };
+  const durationMsToTicks = (durationMs) => {
+    const current = ensureProject();
+    const fallback = current.global.durationTicks.default ?? 6;
+    if (!Number.isFinite(durationMs) || durationMs <= 0) return fallback;
+    return clamp(Math.round(durationMs / 120), current.global.durationTicks.min, current.global.durationTicks.max);
+  };
 
-      [axisOpSelect, minInput, maxInput, enabledToggle]
-        .forEach(el => el.addEventListener('change', updateEntry));
-      const updateAxisAndEntry = () => {
-        updateAxisUi();
-        updateEntry();
-      };
-      [axisXToggle, axisYToggle].forEach(el => el.addEventListener('change', updateAxisAndEntry));
-      targetSelect.addEventListener('change', () => {
-        updateRangePlaceholders(targetSelect.value);
-        updateEntry();
-      });
-      removeButton.addEventListener('click', removeEntry);
-
-      const block = document.createElement('div');
-      block.className = 'panel-section';
-      const titleRow = document.createElement('div');
-      titleRow.className = 'panel-title panel-title-row';
-      const title = document.createElement('span');
-      title.textContent = `Mapping ${index + 1}`;
-      const enabledLabel = document.createElement('label');
-      enabledLabel.className = 'panel-title-toggle';
-      const enabledText = document.createElement('span');
-      enabledText.textContent = 'Enabled';
-      enabledLabel.appendChild(enabledText);
-      enabledLabel.appendChild(enabledToggle);
-      titleRow.appendChild(title);
-      titleRow.appendChild(enabledLabel);
-      block.appendChild(titleRow);
-      block.appendChild(createRow('Axis', axisControl));
-      block.appendChild(createRow('Target', targetSelect));
-      const rangeRow = document.createElement('label');
-      rangeRow.className = 'panel-row';
-      const rangeLabel = document.createElement('span');
-      rangeLabel.textContent = 'Min / Max';
-      const rangeInputs = document.createElement('div');
-      rangeInputs.className = 'input-pair';
-      rangeInputs.appendChild(minInput);
-      rangeInputs.appendChild(maxInput);
-      rangeRow.appendChild(rangeLabel);
-      rangeRow.appendChild(rangeInputs);
-      block.appendChild(rangeRow);
-      block.appendChild(removeButton);
-      container.appendChild(block);
+  const finishRecordNote = (event, fallbackTime = null) => {
+    const key = noteKey(event);
+    const started = recordState.activeNotes.get(key);
+    if (!started) return;
+    recordState.activeNotes.delete(key);
+    const endTime = Number.isFinite(event.timestamp) ? event.timestamp : fallbackTime;
+    recordState.notes.push({
+      note: clamp(Math.round(started.note), 0, 127),
+      velocity: clamp(Math.round(started.velocity), 1, 127),
+      channel: clamp(Math.round(started.channel), 1, 16),
+      durationTicks: durationMsToTicks((endTime ?? started.timestamp) - started.timestamp)
     });
   };
 
-  const buildDefaultPositionMapping = (config) => {
-    const position = config?.position || {};
-    const xRange = position.xNoteRange || {};
-    return {
-      axis: 'x',
-      axisX: true,
-      axisY: false,
-      axisOp: 'add',
-      target: 'note',
-      min: xRange.min ?? 0,
-      max: xRange.max ?? 0,
-      enabled: true
+  const handleRecordMessage = (event) => {
+    if (!recordState.active) return false;
+    const type = event?.type;
+    const note = Number(event?.note);
+    const velocity = Number(event?.velocity ?? 0);
+    if ((type !== 0x90 && type !== 0x80) || !Number.isFinite(note)) return false;
+    const timestamp = Number.isFinite(event.timestamp) ? event.timestamp : Date.now();
+    const normalized = {
+      note: clamp(Math.round(note), 0, 127),
+      velocity: clamp(Math.round(velocity), 0, 127),
+      channel: clamp(Math.round(event.channel), 1, 16),
+      timestamp
     };
+    if (type === 0x90 && normalized.velocity > 0) {
+      finishRecordNote(normalized, timestamp);
+      recordState.activeNotes.set(noteKey(normalized), normalized);
+    } else {
+      finishRecordNote(normalized, timestamp);
+    }
+    renderRecordPanel();
+    return true;
   };
 
-  const buildEventList = (config, availableSfxIds = null) => {
-    const container = document.getElementById('midiEventList');
-    if (!container) return;
-    container.innerHTML = '';
-    const sfx = config?.sfx || {};
-    let ids = Object.keys(sfx).sort((a, b) => Number(a) - Number(b));
-    if (!ids.length) {
-      ids = Array.from(SFX_NAME_BY_ID.keys()).sort((a, b) => a - b).map(String);
-    }
-    ids.forEach(id => {
-      const numericId = Number(id);
-      if (EXCLUDED_SFX_IDS.has(numericId)) return;
-      if (availableSfxIds && availableSfxIds.size && !availableSfxIds.has(numericId)) return;
-      const entry = sfx[id] || {};
-      const fallbackName = SFX_NAME_BY_ID.get(numericId);
-      const name = entry?.name
-        ? `${entry.name} (#${id})`
-        : (fallbackName ? `${fallbackName} (#${id})` : `SFX ${id}`);
-      container.appendChild(buildMappingEditor({
-        id,
-        name,
-        entry,
-        targetKey: 'sfx',
-        allowIndependentArp: TRAP_SFX_IDS.has(numericId)
-      }));
-    });
+  const startRecording = () => {
+    const clip = selectedClip();
+    if (!clip) {
+      renderRecordPanel();
+      return false;
+    }
+    cancelLearn();
+    resetRecordState();
+    recordState.active = true;
+    recordState.clipId = clip.id;
+    recordState.trackId = selectedTrack()?.id ?? null;
+    midiInputController?.setMessageCapture?.(handleRecordMessage);
+    setStatus('Recording MIDI clip');
+    renderRecordPanel();
+    return true;
   };
 
-  const buildTriggerList = (config, availableTriggerTypes = null) => {
-    const container = document.getElementById('midiTriggerList');
-    if (!container) return;
-    container.innerHTML = '';
-    const triggerConfig = config?.triggers || {};
-    const entries = Object.entries(TriggerTypes)
-      .filter(([name, value]) => Number.isFinite(value) && value > 0 && !EXCLUDED_TRIGGER_NAMES.has(name))
-      .sort((a, b) => a[1] - b[1]);
-    for (const [name, value] of entries) {
-      if (availableTriggerTypes && !availableTriggerTypes.has(value)) continue;
-      const entry = triggerConfig[String(value)] || {};
-      container.appendChild(buildMappingEditor({
-        id: value,
-        name: `${name} (#${value})`,
-        entry,
-        targetKey: 'triggers',
-        allowIndependentArp: true
-      }));
-    }
+  const cancelRecording = () => {
+    clearRecordCapture();
+    resetRecordState();
+    setStatus('Recording canceled');
+    renderRecordPanel();
+    return true;
   };
 
-  const buildAdsrTargetOptions = (select, config, availableSfxIds, availableTriggerTypes) => {
-    if (!select) return;
-    select.innerHTML = '';
-    const globalOpt = document.createElement('option');
-    globalOpt.value = 'global';
-    globalOpt.textContent = 'Global envelope';
-    select.appendChild(globalOpt);
-
-    const sfx = config?.sfx || {};
-    const ids = Object.keys(sfx).sort((a, b) => Number(a) - Number(b));
-    for (const id of ids) {
-      const numericId = Number(id);
-      if (EXCLUDED_SFX_IDS.has(numericId)) continue;
-      if (availableSfxIds && availableSfxIds.size && !availableSfxIds.has(numericId)) continue;
-      const entry = sfx[id];
-      const name = entry?.name ? `${entry.name} (#${id})` : `SFX ${id}`;
-      const opt = document.createElement('option');
-      opt.value = `sfx:${id}`;
-      opt.textContent = name;
-      select.appendChild(opt);
-    }
-
-    const entries = Object.entries(TriggerTypes)
-      .filter(([name, value]) => Number.isFinite(value) && value > 0 && !EXCLUDED_TRIGGER_NAMES.has(name))
-      .sort((a, b) => a[1] - b[1]);
-    for (const [, value] of entries) {
-      if (availableTriggerTypes && !availableTriggerTypes.has(value)) continue;
-      const name = TRIGGER_NAME_BY_VALUE.get(value) || `Trigger ${value}`;
-      const opt = document.createElement('option');
-      opt.value = `trigger:${value}`;
-      opt.textContent = `${name} (#${value})`;
-      select.appendChild(opt);
-    }
-  };
-
-  const resolveEnvelopeTarget = (value) => {
-    if (!value || value === 'global') return { scope: 'global', id: null };
-    if (value.startsWith('sfx:')) return { scope: 'sfx', id: value.slice(4) };
-    if (value.startsWith('trigger:')) return { scope: 'trigger', id: value.slice(8) };
-    return { scope: 'global', id: null };
-  };
-
-  const resolveEnvelopeConfig = (config, targetValue) => {
-    const target = resolveEnvelopeTarget(targetValue);
-    const base = config?.envelope || {};
-    if (target.scope === 'sfx' && target.id && config?.sfx?.[target.id]?.envelope) {
-      return { ...base, ...config.sfx[target.id].envelope };
-    }
-    if (target.scope === 'trigger' && target.id && config?.triggers?.[target.id]?.envelope) {
-      return { ...base, ...config.triggers[target.id].envelope };
-    }
-    return { ...base };
-  };
-
-  const bindEnvelopeControls = () => {
-    if (envControlsBound) return;
-    const envAttack = document.getElementById('midiEnvAttack');
-    const envDecay = document.getElementById('midiEnvDecay');
-    const envSustain = document.getElementById('midiEnvSustain');
-    const envRelease = document.getElementById('midiEnvRelease');
-    const envTarget = document.getElementById('midiEnvTarget');
-    if (!envAttack && !envDecay && !envSustain && !envRelease && !envTarget) {
-      return;
+  const hasRecordCapture = () => recordState.active || recordState.notes.length > 0 || recordState.activeNotes.size > 0;
+
+  const cancelActiveCapture = () => {
+    if (hasLearnCapture()) return cancelLearn();
+    if (hasRecordCapture()) return cancelRecording();
+    return false;
+  };
+
+  const commitRecording = () => {
+    const now = Date.now();
+    for (const started of recordState.activeNotes.values()) {
+      finishRecordNote({ ...started, timestamp: now }, now);
+    }
+    recordState.activeNotes.clear();
+    clearRecordCapture();
+    const current = ensureProject();
+    const clipId = recordState.clipId || current.ui.selectedClipId;
+    const clip = current.clips.find(entry => entry.id === clipId);
+    if (!clip || !recordState.notes.length) {
+      resetRecordState();
+      renderRecordPanel();
+      return false;
     }
-    [envAttack, envDecay, envSustain, envRelease].forEach(bindRangeInput);
-    const envUpdate = () => {
-      if (!envAttack || !envDecay || !envSustain || !envRelease) return;
-      const envelope = {
-        attack: Number(envAttack.value) || 0,
-        decay: Number(envDecay.value) || 0,
-        sustain: Number(envSustain.value) || 0,
-        release: Number(envRelease.value) || 0
-      };
-      const target = resolveEnvelopeTarget(envTarget?.value || 'global');
-      if (target.scope === 'sfx' && target.id) {
-        setMidiOverrides({ sfx: { [target.id]: { envelope } } });
-        return;
-      }
-      if (target.scope === 'trigger' && target.id) {
-        setMidiOverrides({ triggers: { [target.id]: { envelope } } });
-        return;
-      }
-      setMidiOverrides({ envelope });
-    };
-    if (envAttack) envAttack.addEventListener('change', envUpdate);
-    if (envDecay) envDecay.addEventListener('change', envUpdate);
-    if (envSustain) envSustain.addEventListener('change', envUpdate);
-    if (envRelease) envRelease.addEventListener('change', envUpdate);
-    if (envTarget) {
-      envTarget.addEventListener('change', (event) => {
-        const value = event.target.value || 'global';
-        storeMidiId(storage, midiStorageKeys.adsrTarget, value);
-        const config = getConfig();
-        const env = resolveEnvelopeConfig(config, value);
-        if (envAttack && Number.isFinite(env.attack)) envAttack.value = String(env.attack);
-        if (envDecay && Number.isFinite(env.decay)) envDecay.value = String(env.decay);
-        if (envSustain && Number.isFinite(env.sustain)) envSustain.value = String(env.sustain);
-        if (envRelease && Number.isFinite(env.release)) envRelease.value = String(env.release);
+    let next = current;
+    recordState.notes.slice(0, clip.lengthSteps).forEach((note, index) => {
+      next = reduceMidiProject(next, {
+        type: 'clip.step.update',
+        clipId: clip.id,
+        stepIndex: index,
+        patch: {
+          note: note.note,
+          velocity: note.velocity,
+          durationTicks: note.durationTicks,
+          probability: 1,
+          hold: false,
+          tie: false
+        }
       });
-    }
-    envControlsBound = true;
-  };
-
-  const refreshMidiUiFromConfig = () => {
-    const config = getEffectiveConfig();
-    if (!config) return false;
-    bindEnvelopeControls();
-    const keySelect = document.getElementById('midiKeySelect');
-    const scaleSelect = document.getElementById('midiScaleSelect');
-    const positionList = document.getElementById('midiPositionList');
-    const intensity = document.getElementById('midiIntensity');
-    const accent = document.getElementById('midiAccent');
-    const repeatEnabled = document.getElementById('midiRepeatEnabled');
-    const repeatSection = document.getElementById('midiRepeatSection');
-    const repeatCount = document.getElementById('midiRepeatCount');
-    const repeatSpacing = document.getElementById('midiRepeatSpacing');
-    const repeatTarget = document.getElementById('midiRepeatTarget');
-    const repeatAmount = document.getElementById('midiRepeatAmount');
-    const envAttack = document.getElementById('midiEnvAttack');
-    const envDecay = document.getElementById('midiEnvDecay');
-    const envSustain = document.getElementById('midiEnvSustain');
-    const envRelease = document.getElementById('midiEnvRelease');
-    const envTarget = document.getElementById('midiEnvTarget');
-    const viewPanToggle = document.getElementById('midiViewPanToggle');
-    const inputChannel = document.getElementById('midiInputChannel');
-    const bpmBase = document.getElementById('midiBpmBase');
-    const bpmValue = Number.isFinite(config.timing?.bpmBase) ? config.timing.bpmBase : 120;
-    if (bpmBase) bpmBase.value = String(bpmValue);
-    if (scaleSelect) buildScaleOptions(scaleSelect, config.scale?.name || 'chromatic-minor');
-    if (keySelect) {
-      const root = Number.isFinite(config.scale?.root) ? config.scale.root : 0;
-      buildKeyOptions(keySelect, root);
-    }
-    if (intensity) {
-      const defaultVelocity = Number.isFinite(config.velocityRange?.default)
-        ? config.velocityRange.default
-        : 80;
-      if (Number.isFinite(config.velocityRange?.min)) {
-        intensity.min = String(config.velocityRange.min);
-      }
-      if (Number.isFinite(config.velocityRange?.max)) {
-        intensity.max = String(config.velocityRange.max);
-      }
-      intensity.value = String(defaultVelocity);
-      bindRangeInput(intensity);
-    }
-    if (accent) {
-      const defaultAccent = Number.isFinite(config.density?.velocityBoost)
-        ? config.density.velocityBoost
-        : 0.4;
-      accent.value = String(defaultAccent);
-      bindRangeInput(accent);
-    }
-    const repeatCfg = config.repeat || {};
-    if (repeatEnabled) {
-      repeatEnabled.checked = repeatCfg.enabled === true;
-    }
-    if (repeatCount) {
-      const maxRepeats = Number.isFinite(repeatCfg.maxRepeats) ? repeatCfg.maxRepeats : 0;
-      repeatCount.value = String(maxRepeats);
-    }
-    if (repeatSpacing) {
-      const windowBeats = Number.isFinite(repeatCfg.windowBeats)
-        ? repeatCfg.windowBeats
-        : (Number.isFinite(repeatCfg.spacingTicks) ? repeatCfg.spacingTicks : 1);
-      buildRepeatWindowOptions(repeatSpacing, windowBeats);
-    }
-    if (repeatTarget) {
-      const target = repeatCfg.target
-        || (repeatCfg.durationBoost ? 'duration' : 'velocity');
-      buildRepeatTargetOptions(repeatTarget, target);
-    }
-    if (repeatAmount) {
-      const amount = Number.isFinite(repeatCfg.amount)
-        ? repeatCfg.amount
-        : (repeatCfg.durationBoost ?? repeatCfg.velocityBoost ?? 0);
-      repeatAmount.value = String(amount);
-      bindRangeInput(repeatAmount);
-    }
-    if (positionList) {
-      const mappings = resolvePositionMappings(config);
-      buildPositionMappingList(positionList, mappings, config);
-    }
-    const storedViewPan = readStoredMidiId(storage, midiStorageKeys.viewPan);
-    if (viewPanToggle) {
-      if (storedViewPan != null) {
-        viewPanToggle.checked = storedViewPan === 'true';
-      } else if (typeof config.position?.viewPan === 'boolean') {
-        viewPanToggle.checked = config.position.viewPan;
-      }
-    }
-    const storedChannel = readStoredMidiId(storage, midiStorageKeys.inputChannel);
-    if (inputChannel) {
-      const channel = storedChannel ?? config.input?.channel ?? 'omni';
-      const value = channel === 'omni' ? null : channel;
-      buildChannelOptions(inputChannel, value);
-    }
-    const { level, skills } = (() => {
-      const lemmings = getLemmings();
-      const game = lemmings?.game ?? null;
-      return {
-        level: game?.level ?? lemmings?.level ?? null,
-        skills: game?.getGameSkills?.() ?? null
-      };
-    })();
-    const availableSfxIds = resolveAvailableSfxIds(config, level, skills);
-    const sfxFilter = availableSfxIds && availableSfxIds.size ? availableSfxIds : null;
-    const availableTriggerTypes = level ? collectTriggerTypes(level) : null;
-    buildEventList(config, sfxFilter);
-    buildTriggerList(config, availableTriggerTypes);
-    if (envTarget) {
-      buildAdsrTargetOptions(envTarget, config, sfxFilter, availableTriggerTypes);
-      const storedTarget = readStoredMidiId(storage, midiStorageKeys.adsrTarget);
-      const options = Array.from(envTarget.options || envTarget.children || []);
-      const matches = storedTarget &&
-        options.some(opt => opt.value === storedTarget);
-      envTarget.value = matches ? storedTarget : 'global';
-    }
-    const env = resolveEnvelopeConfig(config, envTarget?.value || 'global');
-    if (envAttack) envAttack.value = String(Number.isFinite(env.attack) ? env.attack : 1);
-    if (envDecay) envDecay.value = String(Number.isFinite(env.decay) ? env.decay : 0);
-    if (envSustain) envSustain.value = String(Number.isFinite(env.sustain) ? env.sustain : 1);
-    if (envRelease) envRelease.value = String(Number.isFinite(env.release) ? env.release : 1);
-    bindRangeInput(envAttack);
-    bindRangeInput(envDecay);
-    bindRangeInput(envSustain);
-    bindRangeInput(envRelease);
+    });
+    const noteCount = Math.min(recordState.notes.length, clip.lengthSteps);
+    resetRecordState();
+    commitProject(next);
+    const message = `Recorded ${noteCount} ${noteCount === 1 ? 'note' : 'notes'} into ${clip.name}`;
+    setStatus(message);
+    logOutput(message);
     return true;
   };
 
-  const scheduleMidiUiRefresh = () => {
-    let attempts = 0;
-    const attempt = () => {
-      let refreshed = false;
-      try {
-        ensureSchemaHash();
-        refreshed = refreshMidiUiFromConfig();
-      } catch (e) {
-        console.error('MIDI UI refresh failed', e);
-      }
-      if (!refreshed) {
-        attempts += 1;
-        if (attempts < 120) {
-          window?.setTimeout?.(attempt, 250);
-        }
-      }
-    };
-    window?.setTimeout?.(attempt, 0);
+  const setActiveMidiInput = (inputId) => {
+    const webMidi = getWebMidi();
+    if (!inputId || !webMidi?.enabled) {
+      midiInputController?.detach?.();
+      activeMidiInput = null;
+      return;
+    }
+    const input = webMidi.getInputById?.(inputId) || toDeviceList(webMidi.inputs).find(device => device?.id === inputId);
+    if (!input) {
+      midiInputController?.detach?.();
+      activeMidiInput = null;
+      return;
+    }
+    if (activeMidiInput === input) return;
+    if (activeMidiInput) midiInputController?.detach?.();
+    midiInputController?.attach?.(input);
+    activeMidiInput = input;
   };
 
-  const refreshDeviceLists = ({ preserveSelection = true } = {}) => {
-    const inputSelect = document.getElementById('midiInSelect');
-    const outputSelect = document.getElementById('midiOutSelect');
-    const viewPanToggle = document.getElementById('midiViewPanToggle');
+  const setActiveMidiOutput = (outputId) => {
     const webMidi = getWebMidi();
-    const inputs = webMidi?.inputs || [];
-    const outputs = webMidi?.outputs || [];
-    renderErrorDisplay({ inputs, outputs });
-    populateMidiSelect(inputSelect, inputs, 'No input devices');
-
-    populateMidiSelect(outputSelect, outputs, 'No output devices');
-
-    const storedInputId = readStoredMidiId(storage, midiStorageKeys.inputId);
-    const storedOutputId = readStoredMidiId(storage, midiStorageKeys.outputId);
-    const currentInputId = preserveSelection ? (activeMidiInput?.id || inputSelect?.value) : null;
-    const currentOutputId = preserveSelection
-      ? (getLemmings()?.midiOut?.id || outputSelect?.value)
+    const lemmings = getLemmings();
+    const output = outputId && webMidi?.enabled
+      ? (webMidi.getOutputById?.(outputId) || toDeviceList(webMidi.outputs).find(device => device?.id === outputId) || null)
       : null;
-    const resolvedInputId = resolveMidiId(inputs, currentInputId, storedInputId);
-    const resolvedOutputId = resolveMidiId(outputs, currentOutputId, storedOutputId);
-    const shouldResetUi = (storedInputId && resolvedInputId && storedInputId !== resolvedInputId) ||
-      (storedOutputId && resolvedOutputId && storedOutputId !== resolvedOutputId);
-
-    if (resolvedInputId && inputSelect) {
-      inputSelect.value = resolvedInputId;
-      storeMidiId(storage, midiStorageKeys.inputId, resolvedInputId);
-      setActiveMidiInput(resolvedInputId);
-    } else {
-      setActiveMidiInput(null);
-    }
+    if (lemmings?.midiOut === output) return;
+    clearMidiOutputState();
+    if (lemmings) lemmings.midiOut = output;
+  };
 
-    if (resolvedOutputId && outputSelect) {
-      outputSelect.value = resolvedOutputId;
-      storeMidiId(storage, midiStorageKeys.outputId, resolvedOutputId);
-      setActiveMidiOutput(resolvedOutputId);
-    } else {
-      setActiveMidiOutput(null);
-    }
+  const setAvailableMidiOutputs = (outputs) => {
+    const router = getLemmings()?.midiRouter;
+    if (router?.setOutputs) router.setOutputs(outputs);
+    else router?.scheduler?.setOutputs?.(outputs);
+  };
 
-    if (shouldResetUi) {
-      resetUiState();
-    }
+  const clearMidiOutputState = () => {
+    const scheduler = getLemmings()?.midiRouter?.scheduler;
+    scheduler?.allNotesOff?.();
+    scheduler?.clearQueue?.();
+  };
 
-    const storedViewPan = readStoredMidiId(storage, midiStorageKeys.viewPan);
-    if (storedViewPan != null) {
-      const resolvedViewPan = storedViewPan === 'true';
-      if (viewPanToggle) {
-        viewPanToggle.checked = resolvedViewPan;
-      }
-      applyViewPanSetting(resolvedViewPan);
-    }
-    refreshMidiUiFromConfig();
+  const refreshDeviceLists = ({ preserveSelection = true } = {}) => {
+    const current = ensureProject();
+    const webMidi = getWebMidi();
+    const inputs = toDeviceList(webMidi?.inputs);
+    const outputs = toDeviceList(webMidi?.outputs);
+    const inputSelect = document?.getElementById('midiInSelect');
+    const outputSelect = document?.getElementById('midiOutSelect');
+    setAvailableMidiOutputs(outputs);
+    populateMidiSelect(document, inputSelect, inputs, 'No input devices');
+    populateMidiSelect(document, outputSelect, outputs, 'No output devices');
+    const currentInput = preserveSelection ? (current.devices.inputId || activeMidiInput?.id || inputSelect?.value) : null;
+    const currentOutput = preserveSelection ? (current.devices.outputId || getLemmings()?.midiOut?.id || outputSelect?.value) : null;
+    const inputId = resolveMidiId(inputs, currentInput);
+    const outputId = resolveMidiId(outputs, currentOutput);
+    if (inputSelect) inputSelect.value = inputId || '';
+    if (outputSelect) outputSelect.value = outputId || '';
+    if (inputId !== current.devices.inputId || outputId !== current.devices.outputId) {
+      project = saveMidiProject(storage, reduceMidiProject(current, {
+        type: 'devices.set',
+        devices: { inputId, outputId }
+      }));
+      applyProjectToRuntime();
+    }
+    setActiveMidiInput(inputId);
+    setActiveMidiOutput(outputId);
+    renderTrackOutputOptions(document?.getElementById('midiTrackOutputSelect'), selectedTrack()?.outputId);
+    const missing = [];
+    if (!inputs.length) missing.push('No input device');
+    if (!outputs.length) missing.push('No output device');
+    showError(missing.join('. '));
   };
 
   const scheduleDeviceRefresh = () => {
-    if (deviceRefreshTimer) return;
-    deviceRefreshTimer = window?.setTimeout?.(() => {
+    if (deviceRefreshTimer != null || typeof window?.setTimeout !== 'function') return;
+    deviceRefreshTimer = window.setTimeout(() => {
       deviceRefreshTimer = null;
-      if (getWebMidi()?.enabled) {
-        refreshDeviceLists({ preserveSelection: true });
-      }
+      if (getWebMidi()?.enabled) refreshDeviceLists({ preserveSelection: true });
     }, 100);
   };
 
@@ -1407,337 +1097,1694 @@ export const createMidiUiController = ({
   };
 
   const onEnabled = () => {
-    lastEnableError = null;
-    refreshDeviceLists({ preserveSelection: true });
     bindDeviceListeners();
+    refreshDeviceLists({ preserveSelection: true });
   };
 
-  const toggleMidiUiEnabled = (enabled) => {
-    const inputs = [
-      'midiBpmBase',
-      'midiInSelect',
-      'midiOutSelect',
-      'midiInputChannel',
-      'midiResetButton',
-      'midiViewPanToggle',
-      'midiPositionAdd',
-      'midiIntensity',
-      'midiAccent',
-      'midiRepeatEnabled',
-      'midiRepeatCount',
-      'midiRepeatSpacing',
-      'midiRepeatTarget',
-      'midiRepeatAmount'
-    ];
-    for (const id of inputs) {
-      const el = document.getElementById(id);
-      if (el) el.disabled = !enabled;
-    }
-    const root = document?.body;
-    if (root?.classList) root.classList.toggle('midi-disabled', !enabled);
+  const panic = () => {
+    const scheduler = getLemmings()?.midiRouter?.scheduler;
+    scheduler?.allNotesOff?.();
+    scheduler?.clearQueue?.();
+    logOutput('Panic sent');
+    return true;
   };
 
-  const bindMidiUi = () => {
-    if (midiUiBound) return;
-    const enabledToggle = document.getElementById('midiEnabledToggle');
-    const inputSelect = document.getElementById('midiInSelect');
-    const outputSelect = document.getElementById('midiOutSelect');
-    const viewPanToggle = document.getElementById('midiViewPanToggle');
-    const inputChannel = document.getElementById('midiInputChannel');
-    const resetButton = document.getElementById('midiResetButton');
-    const defaultsButton = document.getElementById('midiDefaultsButton');
-    const panelToggle = document.getElementById('midiPanelToggle');
-    const leftPanel = document.getElementById('controlLeft');
-    const bpmBase = document.getElementById('midiBpmBase');
-    const bpmCurrent = document.getElementById('midiBpmCurrent');
-    const debugInput = document.getElementById('midiDebugInput');
-    const debugOutput = document.getElementById('midiDebugOutput');
-    const keySelect = document.getElementById('midiKeySelect');
-    const scaleSelect = document.getElementById('midiScaleSelect');
-    const positionAdd = document.getElementById('midiPositionAdd');
-    const intensity = document.getElementById('midiIntensity');
-    const accent = document.getElementById('midiAccent');
-    const repeatEnabled = document.getElementById('midiRepeatEnabled');
-    const repeatSection = document.getElementById('midiRepeatSection');
-    const repeatCount = document.getElementById('midiRepeatCount');
-    const repeatSpacing = document.getElementById('midiRepeatSpacing');
-    const repeatTarget = document.getElementById('midiRepeatTarget');
-    const repeatAmount = document.getElementById('midiRepeatAmount');
-
-    ensureSchemaHash();
-
-    const storedEnabled = readStoredMidiId(storage, midiStorageKeys.enabled);
-    const configEnabled = getConfig()?.enabled;
-    const midiEnabled = storedEnabled != null
-      ? storedEnabled !== 'false'
-      : (typeof configEnabled === 'boolean' ? configEnabled : false);
-    if (enabledToggle) enabledToggle.checked = midiEnabled;
-    toggleMidiUiEnabled(midiEnabled);
-    const storedChannel = readStoredMidiId(storage, midiStorageKeys.inputChannel);
-    if (inputChannel) {
-      const channel = storedChannel ?? getConfig()?.input?.channel ?? 'omni';
-      const value = channel === 'omni' ? null : channel;
-      buildChannelOptions(inputChannel, value);
-    }
-    if (storedChannel && storedChannel !== 'omni' &&
-        (!midiOverrides?.input?.channel || midiOverrides.input.channel === 'omni')) {
-      setMidiOverrides({ input: { channel: Number(storedChannel) } });
-    }
-
-    if (leftPanel) {
-      const collapsed = readStoredMidiId(storage, midiStorageKeys.panelCollapsed) === 'true';
-      if (collapsed) leftPanel.classList.add('collapsed');
-    }
-    if (panelToggle && leftPanel) {
-      panelToggle.addEventListener('click', () => {
-        leftPanel.classList.toggle('collapsed');
-        const isCollapsed = leftPanel.classList.contains('collapsed');
-        storeMidiId(storage, midiStorageKeys.panelCollapsed, isCollapsed ? 'true' : null);
-        window?.setTimeout?.(() => {
-          if (typeof window?.dispatchEvent === 'function') {
-            const evt = typeof Event === 'function' ? new Event('resize') : { type: 'resize' };
-            window.dispatchEvent(evt);
-          }
-        }, 0);
-      });
+  const resolveAuditionMapping = (request = {}) => {
+    const current = ensureProject();
+    const source = request.sourceId
+      ? current.sources.find(entry => entry.id === request.sourceId)
+      : selectedSource();
+    const track = request.trackId
+      ? current.tracks.find(entry => entry.id === request.trackId)
+      : current.tracks.find(entry => entry.id === source?.trackId) || selectedTrack();
+    const clip = request.clipId
+      ? current.clips.find(entry => entry.id === request.clipId)
+      : current.clips.find(entry => entry.id === source?.clipId) || selectedClip();
+    if (source?.mode === 'clip' || request.clipId) {
+      return { source, track, mapping: clipToMapping(clip), clip };
+    }
+    const mapping = isPlainObject(request.mapping)
+      ? sanitizeMidiProject({ ...current, sources: [{ ...source, mapping: request.mapping }] }).sources[0]?.mapping
+      : source?.mapping;
+    return { source, track, mapping, clip: null };
+  };
+
+  const clipToMapping = (clip) => {
+    const current = ensureProject();
+    const steps = Array.isArray(clip?.steps)
+      ? clip.steps
+        .filter(step => Number.isFinite(step?.note) && (step.probability ?? 1) > 0 && !step.tie)
+        .sort((a, b) => (a.index ?? 0) - (b.index ?? 0))
+      : [];
+    const first = steps[0] || null;
+    if (!first) return null;
+    const notes = steps.map(step => clamp(Math.round(step.note), 0, 127));
+    return {
+      note: notes[0],
+      notes: notes.length > 1 ? notes : null,
+      velocity: first.velocity ?? current.global.velocityRange.default ?? 80,
+      durationTicks: first.durationTicks ?? current.global.durationTicks.default ?? 6,
+      arp: clip?.type === 'arp' && notes.length > 1
+        ? { enabled: true, mode: 'up', length: notes.length }
+        : null
+    };
+  };
+
+  const resolveAuditionNote = (mapping) => {
+    if (Number.isFinite(mapping?.note)) return clamp(Math.round(mapping.note), 0, 127);
+    if (Array.isArray(mapping?.notes) && Number.isFinite(mapping.notes[0])) {
+      return clamp(Math.round(mapping.notes[0]), 0, 127);
+    }
+    if (Number.isFinite(mapping?.degree)) {
+      const current = ensureProject();
+      const scale = current.global.scale;
+      const degrees = Array.isArray(scale.degrees) && scale.degrees.length ? scale.degrees : [0];
+      const degree = Math.max(0, Math.round(mapping.degree));
+      const octave = Number.isFinite(mapping.octave) ? Math.round(mapping.octave) : 4;
+      const octaveOffset = Math.floor(degree / degrees.length);
+      const degreeOffset = degrees[degree % degrees.length] || 0;
+      return clamp(scale.root + degreeOffset + ((octave + octaveOffset) * 12), 0, 127);
+    }
+    return 60;
+  };
+
+  const resolveAuditionNotes = (mapping) => {
+    if (Array.isArray(mapping?.notes) && mapping.notes.length) {
+      return mapping.notes.map(note => clamp(Math.round(note), 0, 127));
+    }
+    if (mapping?.chord && (Number.isFinite(mapping.degree) || !Number.isFinite(mapping.note))) {
+      const current = ensureProject();
+      const scale = resolveScale(current.global.scale);
+      const degree = Number.isFinite(mapping.degree) ? Math.max(0, Math.round(mapping.degree)) : 0;
+      const octave = Number.isFinite(mapping.octave) ? Math.round(mapping.octave) : 4;
+      const type = CHORD_TYPES.includes(mapping.chord?.type) ? mapping.chord.type : 'triad';
+      const inversion = Number.isFinite(mapping.chord?.inversion) ? Math.max(0, Math.round(mapping.chord.inversion)) : 0;
+      return buildChordNotes(degree, scale, octave, type, inversion)
+        .map(note => clampNoteToRange(note, current.global.noteRange));
+    }
+    return [resolveAuditionNote(mapping)];
+  };
+
+  const audition = (request = {}) => {
+    const { source, track, mapping, clip } = resolveAuditionMapping(request);
+    if (!track || !mapping) {
+      logOutput('Audition skipped: no source');
+      return false;
     }
+    const scheduler = getLemmings()?.midiRouter?.scheduler;
+    if (!scheduler?.sendNote) {
+      logOutput('Audition skipped: no router');
+      return false;
+    }
+    const hasAudibleSolo = ensureProject().tracks.some(item => item.solo && !item.mute);
+    if (track.mute) {
+      logOutput(`Audition skipped: ${track.name} muted`);
+      return false;
+    }
+    if (hasAudibleSolo && !track.solo) {
+      logOutput(`Audition skipped: ${track.name} hidden by solo`);
+      return false;
+    }
+    const notes = resolveAuditionNotes(mapping);
+    const current = ensureProject();
+    const rawVelocity = mapping.velocity ?? current.global.velocityRange.default ?? 80;
+    const velocity = clamp(Math.round(rawVelocity * (track.velocityScale ?? 1)), 1, 127);
+    const durationTicks = mapping.durationTicks ?? current.global.durationTicks.default ?? 6;
+    let sent = false;
+    for (const note of notes) {
+      sent = scheduler.sendNote({
+        note,
+        velocity,
+        durationTicks,
+        channel: track.channel,
+        pan: mapping.pan ?? null,
+        timbre: mapping.timbre ?? null,
+        pitchBend: mapping.pitchBend ?? null,
+        trackId: track.id,
+        voiceBudget: track.voiceBudget,
+        outputId: track.outputId ?? null,
+        timeMs: Date.now()
+      }, {
+        sfxId: source?.kind === 'sfx' ? Number(source.sourceKey) || 0 : 0,
+        triggerType: source && source.kind !== 'sfx' ? Number(source.sourceKey) || null : null,
+        eventType: clip ? 'clip-audition' : 'audition',
+        priority: track.priority,
+        sourceId: source?.id ?? null,
+        trackId: track.id,
+        voiceBudget: track.voiceBudget,
+        outputId: track.outputId ?? null,
+        clipId: clip?.id ?? null
+      }) || sent;
+    }
+    const label = clip?.name || source?.label || 'clip';
+    logOutput(sent ? `Audition ${label} -> ${track.name} ch ${track.channel} notes ${notes.join(',')}` : 'Audition skipped: no output');
+    return !!sent;
+  };
 
-    if (enabledToggle) {
-      enabledToggle.addEventListener('change', async (event) => {
-        const enabled = !!event.target.checked;
-        storeMidiId(storage, midiStorageKeys.enabled, enabled ? 'true' : 'false');
-        toggleMidiUiEnabled(enabled);
-        const lemmings = getLemmings();
-        if (lemmings?.setMidiEnabled) {
-          await lemmings.setMidiEnabled(enabled);
-        }
-        if (!enabled) {
-          unbindDeviceListeners();
-          lastEnableError = null;
-          clearErrorDisplay();
-          setActiveMidiInput(null);
-          setActiveMidiOutput(null);
-        } else if (getWebMidi()?.enabled) {
-          onEnabled();
+  const patchGlobal = (patch) => {
+    const current = ensureProject();
+    commitProject({
+      ...current,
+      global: sanitizeMidiProject({ ...current, global: { ...current.global, ...patch } }).global
+    });
+  };
+
+  const applyRuntimePatch = (patch) => {
+    if (!isPlainObject(patch)) return ensureProject();
+    let current = ensureProject();
+    if (patch.timing) {
+      current = reduceMidiProject(current, {
+        type: 'transport.set',
+        transport: {
+          bpmBase: patch.timing.bpmBase ?? current.transport.bpmBase,
+          timeSignature: patch.timing.timeSignature ?? current.transport.timeSignature,
+          quantize: patch.timing.quantize ?? current.transport.quantize,
+          swing: patch.timing.swing ?? current.transport.swing
         }
       });
     }
-
-    if (inputSelect) {
-      inputSelect.addEventListener('change', (event) => {
-        const selectedId = event.target.value || null;
-        storeMidiId(storage, midiStorageKeys.inputId, selectedId);
-        setActiveMidiInput(selectedId);
-        resetUiState();
+    if (patch.input) {
+      current = reduceMidiProject(current, {
+        type: 'devices.set',
+        devices: { inputChannel: patch.input.channel ?? current.devices.inputChannel }
       });
     }
-    if (outputSelect) {
-      outputSelect.addEventListener('change', (event) => {
-        const selectedId = event.target.value || null;
-        storeMidiId(storage, midiStorageKeys.outputId, selectedId);
-        setActiveMidiOutput(selectedId);
-        resetUiState();
+    project = current;
+    if (patch.scale || patch.noteRange || patch.velocityRange || patch.durationTicks || patch.density || patch.envelope || patch.position || patch.mpe || patch.limits || patch.reverse) {
+      const nextScaleDegrees = patch.scale?.name && !Array.isArray(patch.scale.degrees)
+        ? scalePresetDegrees(patch.scale.name)
+        : null;
+      patchGlobal({
+        ...(patch.scale ? {
+          scale: {
+            ...current.global.scale,
+            ...patch.scale,
+            ...(nextScaleDegrees ? { degrees: nextScaleDegrees } : {})
+          }
+        } : {}),
+        ...(patch.noteRange ? { noteRange: { ...current.global.noteRange, ...patch.noteRange } } : {}),
+        ...(patch.velocityRange ? { velocityRange: { ...current.global.velocityRange, ...patch.velocityRange } } : {}),
+        ...(patch.durationTicks ? { durationTicks: { ...current.global.durationTicks, ...patch.durationTicks } } : {}),
+        ...(patch.density ? { density: { ...current.global.density, ...patch.density } } : {}),
+        ...(patch.envelope ? { envelope: { ...current.global.envelope, ...patch.envelope } } : {}),
+        ...(patch.position ? { position: { ...current.global.position, ...patch.position } } : {}),
+        ...(patch.mpe ? { mpe: { ...current.global.mpe, ...patch.mpe } } : {}),
+        ...(patch.limits ? { limits: { ...current.global.limits, ...patch.limits } } : {}),
+        ...(patch.reverse ? { reverse: { ...current.global.reverse, ...patch.reverse } } : {})
       });
+      current = ensureProject();
+    }
+    const updateGroup = (group, kind) => {
+      if (!isPlainObject(group)) return;
+      for (const [sourceKey, mappingPatch] of Object.entries(group)) {
+        const source = current.sources.find(item =>
+          item.sourceKey === String(sourceKey) &&
+          (kind === 'sfx' ? item.kind === 'sfx' : (item.kind === 'trigger' || item.kind === 'midiFlag'))
+        );
+        if (!source) continue;
+        current = reduceMidiProject(current, {
+          type: 'source.mapping.update',
+          sourceId: source.id,
+          patch: mappingPatch
+        });
+      }
+    };
+    updateGroup(patch.sfx, 'sfx');
+    updateGroup(patch.triggers, 'trigger');
+    return commitProject(current);
+  };
+
+  const filteredSources = (report = getConflictReport()) => {
+    const current = ensureProject();
+    const search = sourceFilters.search.trim().toLowerCase();
+    const factorySources = sourceFilters.assignment === 'changed' ? getFactorySourceIndex() : null;
+    const availableSourceKeys = sourceFilters.assignment === 'available' ? getAvailableSourceKeys(current) : null;
+    return current.sources.filter(source => {
+      const conflicts = getSourceConflicts(report, source.id);
+      if (sourceFilters.kind !== 'all' && source.kind !== sourceFilters.kind) return false;
+      if (sourceFilters.assignment === 'changed' && !isSourceChangedFromFactory(source, factorySources, current)) return false;
+      if (sourceFilters.assignment === 'available' && !availableSourceKeys.has(formatSourceKey(source))) return false;
+      if (sourceFilters.assignment === 'assigned' && !source.trackId) return false;
+      if (sourceFilters.assignment === 'unassigned' && source.trackId) return false;
+      if (sourceFilters.assignment === 'enabled' && !source.enabled) return false;
+      if (sourceFilters.assignment === 'disabled' && source.enabled) return false;
+      if (sourceFilters.assignment === 'conflicts' && !conflicts.length) return false;
+      if (sourceFilters.assignment === 'clean' && conflicts.length) return false;
+      if (!search) return true;
+      return `${source.label} ${source.kind} ${source.sourceKey}`.toLowerCase().includes(search);
+    });
+  };
+
+  const renderSourceList = () => {
+    const current = ensureProject();
+    const list = document?.getElementById('midiSourceList');
+    if (!list) return;
+    removeChildren(list);
+    const report = getConflictReport();
+    const sources = filteredSources(report);
+    const factorySources = getFactorySourceIndex();
+    const activeSource = sources.find(source => source.id === current.ui.selectedSourceId) || sources[0] || null;
+    const activeOptionId = activeSource ? listOptionId('source', activeSource.id) : '';
+    configureListbox(list, activeOptionId);
+    const sourceCount = document.getElementById('midiSourceCount');
+    setText(sourceCount, String(sources.length));
+    sourceCount?.setAttribute?.('aria-label', `${sources.length} source${sources.length === 1 ? '' : 's'} shown`);
+    for (const source of sources) {
+      const track = current.tracks.find(item => item.id === source.trackId);
+      const conflicts = getSourceConflicts(report, source.id);
+      const changed = isSourceChangedFromFactory(source, factorySources, current);
+      const selected = current.ui.selectedSourceId === source.id;
+      const active = activeSource?.id === source.id;
+      const row = document.createElement('button');
+      row.type = 'button';
+      row.id = listOptionId('source', source.id);
+      row.className = 'midi-source-row';
+      row.classList.toggle('is-selected', selected);
+      row.classList.toggle('is-disabled', !source.enabled);
+      row.classList.toggle('is-changed', changed);
+      row.classList.toggle('has-conflict', conflicts.length > 0);
+      row.dataset.sourceId = source.id;
+      row.tabIndex = active ? 0 : -1;
+      row.setAttribute('role', 'option');
+      row.setAttribute('aria-selected', selected ? 'true' : 'false');
+      const conflictLabel = conflicts.length
+        ? `, ${conflicts.length} conflict${conflicts.length === 1 ? '' : 's'}: ${conflicts[0].message}${conflicts.length > 1 ? `, ${conflicts.length - 1} more` : ''}`
+        : '';
+      row.setAttribute('aria-label', `${source.label}, ${SOURCE_KIND_LABELS[source.kind] || source.kind}, ${track?.name || 'Unassigned'}${changed ? ', changed' : ''}${conflictLabel}`);
+      const label = document.createElement('span');
+      label.className = 'midi-source-row__label';
+      label.textContent = source.label;
+      const pill = document.createElement('span');
+      pill.className = 'midi-pill';
+      pill.textContent = SOURCE_KIND_LABELS[source.kind] || source.kind;
+      const meta = document.createElement('span');
+      meta.className = 'midi-source-row__meta';
+      meta.textContent = `${source.sourceKey} -> ${track?.name || 'Unassigned'}`;
+      row.append(label, pill);
+      if (changed) {
+        const changedPill = document.createElement('span');
+        changedPill.className = 'midi-pill midi-pill--changed';
+        changedPill.textContent = 'Changed';
+        row.appendChild(changedPill);
+      }
+      if (conflicts.length) {
+        const badge = document.createElement('span');
+        badge.className = 'midi-conflict-badge';
+        badge.dataset.conflictCount = String(conflicts.length);
+        badge.title = conflicts.map(issue => issue.message).join('\n');
+        badge.setAttribute('aria-hidden', 'true');
+        badge.textContent = String(conflicts.length);
+        row.appendChild(badge);
+      }
+      row.appendChild(meta);
+      row.addEventListener('click', () => dispatchProjectIntent({ type: 'source.select', sourceId: source.id }));
+      list.appendChild(row);
+    }
+    if (!sources.length) {
+      const empty = document.createElement('div');
+      empty.className = 'midi-selection-summary';
+      empty.setAttribute('role', 'option');
+      empty.setAttribute('aria-disabled', 'true');
+      empty.setAttribute('aria-selected', 'false');
+      empty.textContent = 'No sources match the filters';
+      list.appendChild(empty);
     }
-    if (viewPanToggle) {
-      viewPanToggle.addEventListener('change', (event) => {
-        const enabled = !!event.target.checked;
-        storeMidiId(storage, midiStorageKeys.viewPan, enabled ? 'true' : null);
-        applyViewPanSetting(enabled);
-      });
+  };
+
+  const renderTrackList = () => {
+    const current = ensureProject();
+    const list = document?.getElementById('midiTrackList');
+    if (!list) return;
+    removeChildren(list);
+    const activeTrack = current.tracks.find(track => track.id === current.ui.selectedTrackId) || current.tracks[0] || null;
+    const activeOptionId = activeTrack ? listOptionId('track', activeTrack.id) : '';
+    configureListbox(list, activeOptionId);
+    const removeButton = document?.getElementById('midiTrackRemove');
+    if (removeButton) removeButton.disabled = !activeTrack || current.tracks.length <= 1;
+    for (const track of current.tracks) {
+      const selected = current.ui.selectedTrackId === track.id;
+      const active = activeTrack?.id === track.id;
+      const outputLabel = trackOutputLabel(track);
+      const row = document.createElement('button');
+      row.type = 'button';
+      row.id = listOptionId('track', track.id);
+      row.className = 'midi-track-row';
+      row.classList.toggle('is-selected', selected);
+      row.dataset.trackId = track.id;
+      row.tabIndex = active ? 0 : -1;
+      row.setAttribute('role', 'option');
+      row.setAttribute('aria-selected', selected ? 'true' : 'false');
+      row.setAttribute('aria-label', `${track.name}, channel ${track.channel}, ${track.instrumentLabel}, ${outputLabel}${track.mute ? ', muted' : ''}${track.solo ? ', solo' : ''}`);
+      const label = document.createElement('span');
+      label.className = 'midi-track-row__label';
+      label.textContent = track.name;
+      const meta = document.createElement('span');
+      meta.className = 'midi-track-row__meta';
+      meta.textContent = `ch ${track.channel} | ${track.instrumentLabel} | ${outputLabel}${track.mute ? ' | muted' : ''}${track.solo ? ' | solo' : ''}`;
+      row.append(label, meta);
+      row.addEventListener('click', () => dispatchProjectIntent({ type: 'track.select', trackId: track.id }));
+      list.appendChild(row);
     }
-    if (inputChannel) {
-      inputChannel.addEventListener('change', (event) => {
-        const raw = event.target.value;
-        const storedValue = raw && raw !== 'omni' ? raw : null;
-        storeMidiId(storage, midiStorageKeys.inputChannel, storedValue);
-        setMidiOverrides({ input: { channel: storedValue ? Number(storedValue) : 'omni' } });
-      });
+  };
+
+  const renderClipList = () => {
+    const current = ensureProject();
+    const list = document?.getElementById('midiClipList');
+    if (!list) return;
+    removeChildren(list);
+    const activeClip = current.clips.find(clip => clip.id === current.ui.selectedClipId) || current.clips[0] || null;
+    const activeOptionId = activeClip ? listOptionId('clip', activeClip.id) : '';
+    configureListbox(list, activeOptionId);
+    const duplicateButton = document?.getElementById('midiClipDuplicateButton');
+    const removeButton = document?.getElementById('midiClipRemoveButton');
+    if (duplicateButton) duplicateButton.disabled = !activeClip;
+    if (removeButton) removeButton.disabled = !activeClip;
+    for (const clip of current.clips) {
+      const selected = current.ui.selectedClipId === clip.id;
+      const active = activeClip?.id === clip.id;
+      const row = document.createElement('button');
+      row.type = 'button';
+      row.id = listOptionId('clip', clip.id);
+      row.className = 'midi-clip-row';
+      row.classList.toggle('is-selected', selected);
+      row.dataset.clipId = clip.id;
+      row.tabIndex = active ? 0 : -1;
+      row.setAttribute('role', 'option');
+      row.setAttribute('aria-selected', selected ? 'true' : 'false');
+      row.setAttribute('aria-label', `${clip.name}, ${clip.type}, ${clip.lengthSteps} steps`);
+      const label = document.createElement('span');
+      label.className = 'midi-clip-row__label';
+      label.textContent = clip.name;
+      const meta = document.createElement('span');
+      meta.className = 'midi-clip-row__meta';
+      meta.textContent = `${clip.type} | ${clip.lengthSteps} steps`;
+      row.append(label, meta);
+      row.addEventListener('click', () => dispatchProjectIntent({ type: 'clip.select', clipId: clip.id }));
+      list.appendChild(row);
+    }
+    if (!current.clips.length) {
+      const empty = document.createElement('div');
+      empty.className = 'midi-selection-summary';
+      empty.setAttribute('role', 'option');
+      empty.setAttribute('aria-disabled', 'true');
+      empty.setAttribute('aria-selected', 'false');
+      empty.textContent = 'No clips yet';
+      list.appendChild(empty);
     }
-    if (resetButton) {
-      resetButton.addEventListener('click', () => {
-        const lemmings = getLemmings();
-        lemmings?.midiRouter?.scheduler?.allNotesOff?.();
-        lemmings?.midiRouter?.scheduler?.clearQueue?.();
-      });
+  };
+
+  const renderTrackOptions = (select, selectedId) => {
+    if (!select) return;
+    removeChildren(select);
+    for (const track of ensureProject().tracks) {
+      appendOption(document, select, track.id, `${track.name} (ch ${track.channel})`);
     }
-    if (defaultsButton) {
-      defaultsButton.addEventListener('click', () => {
-        resetMidiDefaults(true);
-        resetUiState();
-        refreshMidiUiFromConfig();
-      });
+    select.value = selectedId || ensureProject().tracks[0]?.id || '';
+  };
+
+  const renderTrackOutputOptions = (select, selectedOutputId) => {
+    if (!select) return;
+    removeChildren(select);
+    appendOption(document, select, '', 'Project output');
+    const outputs = toDeviceList(getWebMidi()?.outputs);
+    const outputIds = new Set();
+    for (const output of outputs) {
+      if (!output?.id) continue;
+      outputIds.add(output.id);
+      appendOption(document, select, output.id, output.name || output.id);
+    }
+    if (selectedOutputId && !outputIds.has(selectedOutputId)) {
+      appendOption(document, select, selectedOutputId, `Unavailable: ${selectedOutputId}`);
+    }
+    select.value = selectedOutputId || '';
+  };
+
+  const trackOutputLabel = (track) => {
+    if (!track?.outputId) return 'Project output';
+    const output = toDeviceList(getWebMidi()?.outputs)
+      .find(device => device?.id === track.outputId);
+    return output?.name || `Unavailable: ${track.outputId}`;
+  };
+
+  const renderClipOptions = (select, selectedId) => {
+    if (!select) return;
+    removeChildren(select);
+    const clips = ensureProject().clips;
+    if (!clips.length) {
+      appendOption(document, select, '', 'No clips');
+      select.disabled = true;
+      return;
     }
-    if (bpmBase) {
-      const updateBpmBase = (event) => {
-        const bpm = Number(event.target.value) || 120;
-        setMidiOverrides({ timing: { bpmBase: bpm } });
-        updateBpm();
-      };
-      bpmBase.addEventListener('change', updateBpmBase);
-      bpmBase.addEventListener('input', updateBpmBase);
+    select.disabled = false;
+    for (const clip of clips) {
+      appendOption(document, select, clip.id, `${clip.name} (${clip.lengthSteps})`);
     }
-    if (keySelect) {
-      keySelect.addEventListener('change', (event) => {
-        const value = Number(event.target.value);
-        setMidiOverrides({ scale: { root: value } });
-      });
+    select.value = selectedId || selectedClip()?.id || clips[0]?.id || '';
+  };
+
+  const resolveStepGridColumnCount = () => {
+    if (window?.matchMedia?.(`(max-width: ${STEP_GRID_PHONE_MAX_WIDTH}px)`)?.matches) return 1;
+    if (window?.matchMedia?.(`(max-width: ${STEP_GRID_TABLET_MAX_WIDTH}px)`)?.matches) return 2;
+    const width = Number(window?.innerWidth);
+    if (Number.isFinite(width) && width > 0) {
+      if (width <= STEP_GRID_PHONE_MAX_WIDTH) return 1;
+      if (width <= STEP_GRID_TABLET_MAX_WIDTH) return 2;
     }
-    if (scaleSelect) {
-      scaleSelect.addEventListener('change', (event) => {
-        const value = event.target.value;
-        setMidiOverrides({ scale: { name: value } });
-      });
+    return STEP_GRID_COLUMNS;
+  };
+
+  const renderStepPatternGrid = (clip) => {
+    const grid = document?.getElementById('midiStepPatternGrid');
+    if (!grid) return;
+    const columnCount = resolveStepGridColumnCount();
+    const active = document?.activeElement;
+    const activeClass = typeof active?.className === 'string'
+      ? active.className.split(/\s+/).find(name => name.startsWith('midi-step-'))
+      : '';
+    const activeStepIndex = active?.dataset?.stepIndex;
+    const restoreStepFocus = grid.contains?.(active) && activeClass && activeStepIndex != null;
+    removeChildren(grid);
+    if (!clip) {
+      grid.setAttribute('aria-rowcount', '0');
+      grid.setAttribute('aria-colcount', String(columnCount));
+      const empty = document.createElement('div');
+      empty.className = 'midi-selection-summary';
+      empty.setAttribute('role', 'note');
+      empty.textContent = 'Create a clip to edit steps';
+      grid.appendChild(empty);
+      return;
     }
-    if (positionAdd) {
-      positionAdd.addEventListener('click', () => {
-        const config = getConfig();
-        if (!config) return;
-        const mappings = resolvePositionMappings(config);
-        mappings.push(buildDefaultPositionMapping(config));
-        setMidiOverrides({ position: { mappings } });
-        window?.setTimeout?.(() => {
-          try {
-            refreshMidiUiFromConfig();
-          } catch (e) {
-            console.error('MIDI UI refresh failed', e);
-          }
-        }, 0);
-      });
+    const count = Math.min(clip.lengthSteps || 0, STEP_FIELD_COUNT);
+    grid.setAttribute('aria-rowcount', String(Math.ceil(count / columnCount)));
+    grid.setAttribute('aria-colcount', String(columnCount));
+    for (let index = 0; index < count; index += 1) {
+      const step = clip.steps[index] || createDefaultMidiStep(index, { note: null });
+      const stepLabel = `Step ${index + 1}`;
+      const cell = document.createElement('div');
+      cell.className = 'midi-step-cell';
+      cell.dataset.stepIndex = String(index);
+      cell.setAttribute('role', 'gridcell');
+      cell.setAttribute('aria-rowindex', String(Math.floor(index / columnCount) + 1));
+      cell.setAttribute('aria-colindex', String((index % columnCount) + 1));
+      cell.setAttribute('aria-label', stepLabel);
+      const label = document.createElement('div');
+      label.className = 'midi-step-cell__index';
+      label.textContent = stepLabel;
+      const noteLabel = document.createElement('label');
+      noteLabel.textContent = 'Note';
+      const note = document.createElement('input');
+      note.className = 'midi-step-note';
+      note.dataset.stepIndex = String(index);
+      note.type = 'number';
+      note.min = '0';
+      note.max = '127';
+      note.step = '1';
+      note.value = step.note == null ? '' : String(step.note);
+      note.setAttribute('aria-label', `${stepLabel} note`);
+      note.addEventListener('change', event => updateSelectedClipStep(index, { note: toNumberOrNull(event.target.value) }));
+      noteLabel.appendChild(note);
+      const velocityLabel = document.createElement('label');
+      velocityLabel.textContent = 'Vel';
+      const velocity = document.createElement('input');
+      velocity.className = 'midi-step-velocity';
+      velocity.dataset.stepIndex = String(index);
+      velocity.type = 'number';
+      velocity.min = '1';
+      velocity.max = '127';
+      velocity.step = '1';
+      velocity.value = step.velocity == null ? '' : String(step.velocity);
+      velocity.setAttribute('aria-label', `${stepLabel} velocity`);
+      velocity.addEventListener('change', event => updateSelectedClipStep(index, { velocity: toNumberOrNull(event.target.value) }));
+      velocityLabel.appendChild(velocity);
+      const durationLabel = document.createElement('label');
+      durationLabel.textContent = 'Dur';
+      const duration = document.createElement('input');
+      duration.className = 'midi-step-duration';
+      duration.dataset.stepIndex = String(index);
+      duration.type = 'number';
+      duration.min = '1';
+      duration.max = '960';
+      duration.step = '1';
+      duration.value = step.durationTicks == null ? '' : String(step.durationTicks);
+      duration.setAttribute('aria-label', `${stepLabel} duration`);
+      duration.addEventListener('change', event => updateSelectedClipStep(index, { durationTicks: toNumberOrNull(event.target.value) }));
+      durationLabel.appendChild(duration);
+      const probabilityLabel = document.createElement('label');
+      probabilityLabel.textContent = 'Prob';
+      const probability = document.createElement('input');
+      probability.className = 'midi-step-probability';
+      probability.dataset.stepIndex = String(index);
+      probability.type = 'number';
+      probability.min = '0';
+      probability.max = '1';
+      probability.step = '0.05';
+      probability.value = step.probability == null ? '1' : String(step.probability);
+      probability.setAttribute('aria-label', `${stepLabel} probability`);
+      probability.addEventListener('change', event => updateSelectedClipStep(index, { probability: toNumberOrNull(event.target.value) ?? 1 }));
+      probabilityLabel.appendChild(probability);
+      const holdLabel = document.createElement('label');
+      holdLabel.textContent = 'Hold';
+      const hold = document.createElement('input');
+      hold.className = 'midi-step-hold';
+      hold.dataset.stepIndex = String(index);
+      hold.type = 'checkbox';
+      hold.checked = !!step.hold;
+      hold.setAttribute('aria-label', `${stepLabel} hold`);
+      hold.addEventListener('change', event => updateSelectedClipStep(index, { hold: !!event.target.checked }));
+      holdLabel.appendChild(hold);
+      const tieLabel = document.createElement('label');
+      tieLabel.textContent = 'Tie';
+      const tie = document.createElement('input');
+      tie.className = 'midi-step-tie';
+      tie.dataset.stepIndex = String(index);
+      tie.type = 'checkbox';
+      tie.checked = !!step.tie;
+      tie.setAttribute('aria-label', `${stepLabel} tie`);
+      tie.addEventListener('change', event => updateSelectedClipStep(index, { tie: !!event.target.checked }));
+      tieLabel.appendChild(tie);
+      const rest = document.createElement('button');
+      rest.className = 'midi-step-rest';
+      rest.dataset.stepIndex = String(index);
+      rest.type = 'button';
+      rest.textContent = 'Rest';
+      rest.setAttribute('aria-label', `${stepLabel} rest`);
+      rest.addEventListener('click', () => updateSelectedClipStep(index, {
+        note: null,
+        velocity: null,
+        durationTicks: null,
+        probability: 1,
+        hold: false,
+        tie: false
+      }));
+      cell.append(label, noteLabel, velocityLabel, durationLabel, probabilityLabel, holdLabel, tieLabel, rest);
+      grid.appendChild(cell);
     }
-    if (intensity) {
-      intensity.addEventListener('change', (event) => {
-        const value = Number(event.target.value) || 0;
-        setMidiOverrides({ velocityRange: { default: value } });
-      });
+    if (restoreStepFocus) {
+      grid.querySelector?.(`.${activeClass}[data-step-index="${activeStepIndex}"]`)?.focus?.();
     }
-    if (accent) {
-      accent.addEventListener('change', (event) => {
-        const value = Number(event.target.value) || 0;
-        setMidiOverrides({ density: { velocityBoost: value } });
-      });
+  };
+
+  const renderClipInspector = () => {
+    const clip = selectedClip();
+    const arpMode = document?.getElementById('midiClipArpMode');
+    const arpModeField = document?.getElementById('midiClipArpModeField');
+    const arpPattern = document?.getElementById('midiClipArpPattern');
+    const arpPatternField = document?.getElementById('midiClipArpPatternField');
+    const isArpClip = clip?.type === 'arp';
+    setInputValue(document?.getElementById('midiClipName'), clip?.name);
+    setInputValue(document?.getElementById('midiClipType'), clip?.type);
+    setInputValue(arpMode, clip?.arp?.mode || 'up');
+    setInputValue(arpPattern, clip?.arp?.pattern?.preset || clip?.arp?.mode || 'up');
+    const active = document?.activeElement;
+    const activeInArpControls = !isArpClip && [arpModeField, arpPatternField]
+      .some(field => field && (field === active || field.contains?.(active)));
+    if (arpMode) arpMode.disabled = !isArpClip;
+    if (arpPattern) arpPattern.disabled = !isArpClip;
+    if (arpModeField) arpModeField.style.display = isArpClip ? '' : 'none';
+    if (arpPatternField) arpPatternField.style.display = isArpClip ? '' : 'none';
+    if (activeInArpControls) document?.getElementById('midiClipType')?.focus?.();
+    setInputValue(document?.getElementById('midiClipLengthSteps'), clip?.lengthSteps);
+    renderRecordPanel();
+    renderStepPatternGrid(clip);
+  };
+
+  const renderAutomationList = () => {
+    const current = ensureProject();
+    const list = document?.getElementById('midiAutomationList');
+    if (!list) return;
+    removeChildren(list);
+    for (const lane of current.automation) {
+      const row = document.createElement('div');
+      row.className = 'midi-automation-row';
+      row.dataset.automationId = lane.id;
+      row.setAttribute('role', 'group');
+      row.setAttribute('aria-label', `Modulation lane ${lane.name}`);
+
+      const enabledLabel = document.createElement('label');
+      enabledLabel.className = 'midi-field midi-field--toggle';
+      const enabled = document.createElement('input');
+      enabled.type = 'checkbox';
+      enabled.checked = !!lane.enabled;
+      enabled.setAttribute('aria-label', `Enable modulation lane ${lane.name}`);
+      enabled.addEventListener('change', event => dispatchProjectIntent({
+        type: 'automation.update',
+        automationId: lane.id,
+        patch: { enabled: !!event.target.checked }
+      }));
+      const enabledText = document.createElement('span');
+      enabledText.textContent = 'On';
+      enabledLabel.append(enabledText, enabled);
+
+      const targetLabel = document.createElement('label');
+      targetLabel.className = 'midi-field midi-field--compact';
+      const targetText = document.createElement('span');
+      targetText.textContent = 'Target';
+      const target = document.createElement('select');
+      for (const value of AUTOMATION_TARGETS) {
+        appendOption(document, target, value, AUTOMATION_TARGET_LABELS[value] || value);
+      }
+      target.value = lane.target;
+      target.setAttribute('aria-label', `${lane.name} target`);
+      target.addEventListener('change', event => dispatchProjectIntent({
+        type: 'automation.update',
+        automationId: lane.id,
+        patch: { target: event.target.value }
+      }));
+      targetLabel.append(targetText, target);
+
+      const axisLabel = document.createElement('label');
+      axisLabel.className = 'midi-field midi-field--compact';
+      const axisText = document.createElement('span');
+      axisText.textContent = 'Axis';
+      const axis = document.createElement('select');
+      for (const value of AUTOMATION_AXES) {
+        appendOption(document, axis, value, value.toUpperCase());
+      }
+      axis.value = lane.axis;
+      axis.setAttribute('aria-label', `${lane.name} axis`);
+      axis.addEventListener('change', event => dispatchProjectIntent({
+        type: 'automation.update',
+        automationId: lane.id,
+        patch: { axis: event.target.value }
+      }));
+      axisLabel.append(axisText, axis);
+
+      const opLabel = document.createElement('label');
+      opLabel.className = 'midi-field midi-field--compact';
+      const opText = document.createElement('span');
+      opText.textContent = 'Op';
+      const op = document.createElement('select');
+      op.className = 'midi-automation-axis-op';
+      for (const entry of POSITION_AXIS_OPERATORS) {
+        appendOption(document, op, entry.value, entry.label);
+      }
+      op.value = lane.axisOp || 'add';
+      op.setAttribute('aria-label', `${lane.name} operator`);
+      op.addEventListener('change', event => dispatchProjectIntent({
+        type: 'automation.update',
+        automationId: lane.id,
+        patch: { axisOp: event.target.value }
+      }));
+      opLabel.append(opText, op);
+
+      const minLabel = document.createElement('label');
+      minLabel.className = 'midi-field midi-field--compact';
+      const minText = document.createElement('span');
+      minText.textContent = 'Min';
+      const min = document.createElement('input');
+      min.type = 'number';
+      min.step = '0.05';
+      min.value = String(lane.min);
+      min.setAttribute('aria-label', `${lane.name} minimum`);
+      min.addEventListener('change', event => dispatchProjectIntent({
+        type: 'automation.update',
+        automationId: lane.id,
+        patch: { min: Number(event.target.value) }
+      }));
+      minLabel.append(minText, min);
+
+      const maxLabel = document.createElement('label');
+      maxLabel.className = 'midi-field midi-field--compact';
+      const maxText = document.createElement('span');
+      maxText.textContent = 'Max';
+      const max = document.createElement('input');
+      max.type = 'number';
+      max.step = '0.05';
+      max.value = String(lane.max);
+      max.setAttribute('aria-label', `${lane.name} maximum`);
+      max.addEventListener('change', event => dispatchProjectIntent({
+        type: 'automation.update',
+        automationId: lane.id,
+        patch: { max: Number(event.target.value) }
+      }));
+      maxLabel.append(maxText, max);
+
+      const point = lane.points[0] || { beat: 0, value: lane.min };
+      const pointBeatLabel = document.createElement('label');
+      pointBeatLabel.className = 'midi-field midi-field--compact';
+      const pointBeatText = document.createElement('span');
+      pointBeatText.textContent = 'Beat';
+      const pointBeat = document.createElement('input');
+      pointBeat.className = 'midi-automation-point-beat';
+      pointBeat.type = 'number';
+      pointBeat.min = '0';
+      pointBeat.step = '0.25';
+      pointBeat.value = String(point.beat);
+      pointBeat.setAttribute('aria-label', `${lane.name} point beat`);
+      pointBeat.addEventListener('change', event => dispatchProjectIntent({
+        type: 'automation.point.update',
+        automationId: lane.id,
+        pointIndex: 0,
+        patch: { beat: Number(event.target.value) }
+      }));
+      pointBeatLabel.append(pointBeatText, pointBeat);
+
+      const pointValueLabel = document.createElement('label');
+      pointValueLabel.className = 'midi-field midi-field--compact';
+      const pointValueText = document.createElement('span');
+      pointValueText.textContent = 'Value';
+      const pointValue = document.createElement('input');
+      pointValue.className = 'midi-automation-point-value';
+      pointValue.type = 'number';
+      pointValue.step = '0.05';
+      pointValue.value = String(point.value);
+      pointValue.setAttribute('aria-label', `${lane.name} point value`);
+      pointValue.addEventListener('change', event => dispatchProjectIntent({
+        type: 'automation.point.update',
+        automationId: lane.id,
+        pointIndex: 0,
+        patch: { value: Number(event.target.value) }
+      }));
+      pointValueLabel.append(pointValueText, pointValue);
+
+      const remove = document.createElement('button');
+      remove.type = 'button';
+      remove.className = 'midi-automation-remove';
+      remove.textContent = 'Remove';
+      remove.setAttribute('aria-label', `Remove modulation lane ${lane.name}`);
+      remove.addEventListener('click', () => dispatchProjectIntent({
+        type: 'automation.remove',
+        automationId: lane.id
+      }));
+
+      row.append(enabledLabel, targetLabel, axisLabel, opLabel, minLabel, maxLabel, pointBeatLabel, pointValueLabel, remove);
+      list.appendChild(row);
     }
-    if (repeatEnabled) {
-      repeatEnabled.addEventListener('click', (event) => event.stopPropagation());
-      repeatEnabled.addEventListener('change', (event) => {
-        const enabled = !!event.target.checked;
-        setMidiOverrides({ repeat: { enabled } });
-        if (enabled && repeatSection && !repeatSection.open) {
-          repeatSection.open = true;
-          const key = repeatSection.dataset.sectionKey || 'repeat';
-          const states = readSectionStates();
-          states[key] = true;
-          storeSectionStates(states);
-        }
-      });
+    if (!current.automation.length) {
+      const empty = document.createElement('div');
+      empty.className = 'midi-selection-summary';
+      empty.textContent = 'No modulation lanes';
+      list.appendChild(empty);
     }
-    if (repeatCount) {
-      repeatCount.addEventListener('change', (event) => {
-        const value = Number(event.target.value) || 0;
-        setMidiOverrides({ repeat: { maxRepeats: value } });
-      });
+  };
+
+  const renderModulation = () => {
+    const current = ensureProject();
+    setInputValue(document?.getElementById('midiGlobalIntensity'), current.global.velocityRange.default);
+    setInputValue(document?.getElementById('midiGlobalVelocityMin'), current.global.velocityRange.min);
+    setInputValue(document?.getElementById('midiGlobalVelocityMax'), current.global.velocityRange.max);
+    setInputValue(document?.getElementById('midiGlobalNoteMin'), current.global.noteRange.min);
+    setInputValue(document?.getElementById('midiGlobalNoteMax'), current.global.noteRange.max);
+    setInputValue(document?.getElementById('midiGlobalAccent'), current.global.density.velocityBoost);
+    setInputValue(document?.getElementById('midiGlobalDensityWindow'), current.global.density.windowTicks);
+    setInputValue(document?.getElementById('midiGlobalDurationScale'), current.global.density.durationScale);
+    setChecked(document?.getElementById('midiGlobalViewPan'), current.global.position.viewPan);
+    setInputValue(document?.getElementById('midiGlobalPanMin'), current.global.position.panRange.min);
+    setInputValue(document?.getElementById('midiGlobalPanMax'), current.global.position.panRange.max);
+    setInputValue(document?.getElementById('midiGlobalPanDeadZone'), current.global.position.panDeadZonePct);
+    setInputValue(document?.getElementById('midiGlobalTimbreMin'), current.global.position.timbreRange.min);
+    setInputValue(document?.getElementById('midiGlobalTimbreMax'), current.global.position.timbreRange.max);
+    setInputValue(document?.getElementById('midiGlobalXNoteMin'), current.global.position.xNoteRange.min);
+    setInputValue(document?.getElementById('midiGlobalXNoteMax'), current.global.position.xNoteRange.max);
+    setInputValue(document?.getElementById('midiGlobalMaxActiveNotes'), current.global.limits.maxActiveNotes);
+    setInputValue(document?.getElementById('midiGlobalMaxEventsPerTick'), current.global.limits.maxEventsPerTick);
+    setInputValue(document?.getElementById('midiGlobalDurationDefault'), current.global.durationTicks.default);
+    setInputValue(document?.getElementById('midiGlobalDurationMin'), current.global.durationTicks.min);
+    setInputValue(document?.getElementById('midiGlobalDurationMax'), current.global.durationTicks.max);
+    setInputValue(document?.getElementById('midiGlobalEnvAttack'), current.global.envelope.attack);
+    setInputValue(document?.getElementById('midiGlobalEnvDecay'), current.global.envelope.decay);
+    setInputValue(document?.getElementById('midiGlobalEnvSustain'), current.global.envelope.sustain);
+    setInputValue(document?.getElementById('midiGlobalEnvRelease'), current.global.envelope.release);
+    renderAutomationList();
+  };
+
+  const renderConflictSummary = (report, source, track, clip) => {
+    const element = document?.getElementById('midiConflictSummary');
+    if (!element) return;
+    removeChildren(element);
+    element.textContent = '';
+    const issuesById = new Map();
+    const collect = (issues = []) => {
+      for (const issue of issues) issuesById.set(issue.id, issue);
+    };
+    if (source?.id) collect(getSourceConflicts(report, source.id, { includeInfo: true }));
+    if (track?.id) collect((report.byTrackId?.[track.id] || []).filter(isActionableConflict));
+    if (clip?.id) collect((report.byClipId?.[clip.id] || []).filter(isActionableConflict));
+    const issues = [...issuesById.values()];
+    element.className = `midi-conflict-summary ${issues.some(isActionableConflict) ? 'has-conflict' : 'is-clean'}`;
+    if (!issues.length) {
+      element.textContent = 'No conflicts for the selected source.';
+      return;
     }
-    if (repeatSpacing) {
-      repeatSpacing.addEventListener('change', (event) => {
-        const value = Number(event.target.value) || 1;
-        setMidiOverrides({ repeat: { windowBeats: value } });
-      });
+    for (const issue of issues.slice(0, 5)) {
+      const row = document.createElement('div');
+      row.className = 'midi-conflict-summary__item';
+      row.dataset.severity = issue.severity;
+      row.textContent = issue.message;
+      element.appendChild(row);
     }
-    if (repeatTarget) {
-      repeatTarget.addEventListener('change', (event) => {
-        const value = event.target.value || 'velocity';
-        setMidiOverrides({ repeat: { target: value } });
-      });
+    if (issues.length > 5) {
+      const more = document.createElement('div');
+      more.className = 'midi-conflict-summary__item';
+      more.dataset.severity = 'info';
+      more.textContent = `${issues.length - 5} more conflicts`;
+      element.appendChild(more);
     }
-    if (repeatAmount) {
-      repeatAmount.addEventListener('change', (event) => {
-        const value = Number(event.target.value) || 0;
-        setMidiOverrides({ repeat: { amount: value } });
-      });
+  };
+
+  const renderInspector = () => {
+    const current = ensureProject();
+    const track = selectedTrack();
+    const source = selectedSource();
+    const clip = selectedClip();
+    const report = getConflictReport();
+    setInputValue(document?.getElementById('midiTrackName'), track?.name);
+    setInputValue(document?.getElementById('midiTrackInstrument'), track?.instrumentLabel);
+    renderTrackOutputOptions(document?.getElementById('midiTrackOutputSelect'), track?.outputId);
+    setInputValue(document?.getElementById('midiTrackChannel'), track?.channel);
+    setInputValue(document?.getElementById('midiTrackPriority'), track?.priority);
+    setInputValue(document?.getElementById('midiTrackVoiceBudget'), track?.voiceBudget);
+    setInputValue(document?.getElementById('midiTrackVelocityScale'), track?.velocityScale);
+    setChecked(document?.getElementById('midiTrackMute'), track?.mute);
+    setChecked(document?.getElementById('midiTrackSolo'), track?.solo);
+    setChecked(document?.getElementById('midiTrackArm'), track?.arm);
+
+    const revertButton = document?.getElementById('midiSourceRevertButton');
+    if (revertButton) {
+      revertButton.disabled = !source || !isSourceChangedFromFactory(source, getFactorySourceIndex(), current);
+    }
+    setChecked(document?.getElementById('midiSourceEnabled'), source?.enabled);
+    renderTrackOptions(document?.getElementById('midiSourceTrackSelect'), source?.trackId);
+    renderTrackOptions(document?.getElementById('midiAssignTrackSelect'), track?.id);
+    renderClipOptions(document?.getElementById('midiSourceClipSelect'), source?.clipId || clip?.id);
+    const assignClipButton = document?.getElementById('midiAssignClipButton');
+    if (assignClipButton) assignClipButton.disabled = !source || !current.clips.length;
+    setInputValue(document?.getElementById('midiSourceModeSelect'), source?.mode || 'direct');
+    const sourceClip = source?.mode === 'clip'
+      ? current.clips.find(item => item.id === source.clipId) || null
+      : null;
+    renderConflictSummary(report, source, track, sourceClip);
+    renderLearnPanel();
+    const mapping = source?.mapping || createEmptyDirectMapping();
+    const directDisabled = source?.mode === 'clip';
+    for (const id of [
+      'midiMappingNote',
+      'midiMappingDegree',
+      'midiMappingOctave',
+      'midiMappingVelocity',
+      'midiMappingDuration',
+      'midiMappingChord',
+      'midiMappingChordInversion',
+      'midiMappingArp',
+      'midiMappingPan',
+      'midiMappingTimbre',
+      'midiMappingPitchBend',
+      'midiEnvelopeOverrideToggle'
+    ]) {
+      const element = document?.getElementById(id);
+      if (element) element.disabled = directDisabled;
+    }
+    const chordInversion = document?.getElementById('midiMappingChordInversion');
+    if (chordInversion) chordInversion.disabled = directDisabled || !mapping.chord;
+    const envelopeEnabled = !!mapping.envelope && !directDisabled;
+    setChecked(document?.getElementById('midiEnvelopeOverrideToggle'), !!mapping.envelope);
+    for (const id of ['midiEnvAttack', 'midiEnvDecay', 'midiEnvSustain', 'midiEnvRelease']) {
+      const element = document?.getElementById(id);
+      if (element) element.disabled = !envelopeEnabled;
+    }
+    setInputValue(document?.getElementById('midiMappingNote'), mapping.note);
+    setInputValue(document?.getElementById('midiMappingDegree'), mapping.degree);
+    setInputValue(document?.getElementById('midiMappingOctave'), mapping.octave);
+    setInputValue(document?.getElementById('midiMappingVelocity'), mapping.velocity);
+    setInputValue(document?.getElementById('midiMappingDuration'), mapping.durationTicks);
+    setInputValue(document?.getElementById('midiMappingChord'), mapping.chord?.type || '');
+    setInputValue(document?.getElementById('midiMappingChordInversion'), mapping.chord?.inversion ?? 0);
+    setInputValue(document?.getElementById('midiMappingArp'), mapping.arp?.enabled === false ? '' : mapping.arp?.mode || '');
+    setInputValue(document?.getElementById('midiMappingPan'), mapping.pan);
+    setInputValue(document?.getElementById('midiMappingTimbre'), mapping.timbre);
+    setInputValue(document?.getElementById('midiMappingPitchBend'), mapping.pitchBend);
+    setInputValue(document?.getElementById('midiEnvAttack'), mapping.envelope?.attack);
+    setInputValue(document?.getElementById('midiEnvDecay'), mapping.envelope?.decay);
+    setInputValue(document?.getElementById('midiEnvSustain'), mapping.envelope?.sustain);
+    setInputValue(document?.getElementById('midiEnvRelease'), mapping.envelope?.release);
+
+    const routeTrack = source
+      ? current.tracks.find(item => item.id === source.trackId)
+      : null;
+    const routeLabel = routeTrack
+      ? `${routeTrack.name} (ch ${routeTrack.channel}, ${trackOutputLabel(routeTrack)})`
+      : 'no track';
+    const summary = source
+      ? `${source.label} routes to ${routeLabel} in ${source.mode} mode${source.clipId ? ` using ${current.clips.find(item => item.id === source.clipId)?.name || source.clipId}` : ''}.`
+      : 'No source selected';
+    setText(document?.getElementById('midiSelectedSourceSummary'), summary);
+  };
+
+  const renderTemplateOptions = () => {
+    const select = document?.getElementById('midiTemplateSelect');
+    if (!select) return;
+    const current = ensureProject();
+    const selected = current.templateId || 'midi-mapping';
+    removeChildren(select);
+    appendOption(document, select, 'midi-mapping', 'Factory');
+    for (const template of getProjectTemplates()) {
+      appendOption(document, select, template.id, template.name);
+    }
+    select.value = Array.from(select.children).some(option => option.value === selected)
+      ? selected
+      : 'midi-mapping';
+  };
+
+  const renderTransport = () => {
+    const current = ensureProject();
+    const enabledToggle = document?.getElementById('midiEnabledToggle');
+    setChecked(enabledToggle, current.enabled);
+    renderChannelOptions(document?.getElementById('midiInputChannel'), current.devices.inputChannel, { includeOmni: true });
+    setInputValue(document?.getElementById('midiInputChannel'), current.devices.inputChannel);
+    setInputValue(document?.getElementById('midiBpmBase'), current.transport.bpmBase);
+    setInputValue(document?.getElementById('midiTimeSignatureBeats'), current.transport.timeSignature?.beats ?? 4);
+    setInputValue(document?.getElementById('midiTimeSignatureUnit'), current.transport.timeSignature?.unit ?? 4);
+    renderScaleRootOptions(document?.getElementById('midiScaleRoot'), current.global.scale.root);
+    renderScaleNameOptions(document?.getElementById('midiScaleName'), current.global.scale.name);
+    setInputValue(document?.getElementById('midiQuantize'), current.transport.quantize);
+    setInputValue(document?.getElementById('midiSwing'), current.transport.swing);
+    setChecked(document?.getElementById('midiReversePanicToggle'), current.global.reverse.allNotesOffOnToggle);
+    renderTemplateOptions();
+    document?.body?.classList?.toggle('midi-disabled', !current.enabled);
+    setStatus(current.enabled ? 'MIDI enabled' : 'MIDI disabled');
+  };
+
+  const renderOutputStatus = () => {
+    const router = getLemmings()?.midiRouter;
+    const report = router?.getRateReport?.();
+    const snapshot = report?.snapshot || router?.getRateSnapshot?.();
+    const queued = Math.max(0, Math.round(Number(snapshot?.next?.count) || 0));
+    const pressure = report?.reason
+      ? `Scheduler: ${report.reason}`
+      : (queued ? `Scheduler: queued ${queued}` : 'Scheduler: idle');
+    setText(document?.getElementById('midiSchedulerPressure'), pressure);
+    setText(document?.getElementById('midiOutputLog'), outputLog[0] || 'No output yet');
+  };
+
+  const render = () => {
+    const startedAt = nowMs();
+    try {
+      syncRuntimeSources();
+      applyProjectToRuntime();
+      renderTransport();
+      renderSourceList();
+      renderTrackList();
+      renderClipList();
+      renderInspector();
+      renderModulation();
+      renderClipInspector();
+      renderOutputStatus();
+      if (getWebMidi()?.enabled) refreshDeviceLists({ preserveSelection: true });
+    } finally {
+      uiMetrics.renderCount += 1;
+      uiMetrics.lastRenderAt = Date.now();
+      uiMetrics.lastRenderDurationMs = Math.max(0, nowMs() - startedAt);
     }
-    bindEnvelopeControls();
+  };
 
-    bindTabs();
-    bindSectionPersistence();
+  const addDomListener = (element, eventName, handler) => {
+    if (!element?.addEventListener || typeof handler !== 'function') return;
+    element.addEventListener(eventName, handler);
+    domListeners.push({ element, eventName, handler });
+  };
 
-    const updateBpm = () => {
-      if (!bpmCurrent) return;
-      const config = getEffectiveConfig() || {};
-      const timing = config.timing || {};
-      const base = Number.isFinite(timing.bpmBase) ? timing.bpmBase : 120;
-      const timeSignature = timing.timeSignature || {};
-      const beats = Number.isFinite(timeSignature.beats) ? timeSignature.beats : 4;
-      const unit = Number.isFinite(timeSignature.unit) && timeSignature.unit > 0 ? timeSignature.unit : 4;
-      const lemmings = getLemmings();
-      const timer = lemmings?.game?.getGameTimer?.();
-      const speed = timer?.speedFactor ?? lemmings?.gameSpeedFactor ?? 1;
-      const tps = timer?.tps ?? (timer?.frameTime ? 1000 / timer.frameTime : 1000 / 60);
-      const currentBpm = base * speed;
-      const ticksPerQuarter = currentBpm > 0 ? (tps * 60 / currentBpm) : 0;
-      const unitScale = 4 / unit;
-      const ticksPerBeat = ticksPerQuarter * unitScale;
-      const ticksPerMeasure = ticksPerBeat * beats;
-      bpmCurrent.textContent = `${formatNumber(speed, 2)}x ${formatNumber(base, 0)} = ${formatNumber(currentBpm, 0)} BPM | ${formatNumber(tps, 1)} tps | ${formatNumber(ticksPerBeat, 1)} t/beat | ${formatNumber(ticksPerMeasure, 1)} t/measure`;
-      const uiSignature = buildUiSignature();
-      if (uiSignature !== lastUiSignature) {
-        lastUiSignature = uiSignature;
-        try {
-          refreshMidiUiFromConfig();
-        } catch (e) {
-          console.error('MIDI UI refresh failed', e);
+  const bindById = (id, eventName, handler) => addDomListener(document?.getElementById(id), eventName, handler);
+
+  const updateGlobal = (patch) => {
+    dispatchProjectIntent({ type: 'global.update', patch });
+  };
+
+  const updateSelectedTrack = (patch) => {
+    const track = selectedTrack();
+    if (!track) return;
+    dispatchProjectIntent({ type: 'track.update', trackId: track.id, patch });
+  };
+
+  const removeSelectedTrack = () => {
+    const current = ensureProject();
+    const track = selectedTrack();
+    if (!track || current.tracks.length <= 1) return false;
+    if (learnState.trackId === track.id && hasLearnCapture()) {
+      learnState.active = false;
+      learnState.pending = null;
+      learnState.sourceId = null;
+      learnState.trackId = null;
+      learnState.conflicts = [];
+      clearLearnCapture();
+    }
+    if (recordState.trackId === track.id && hasRecordCapture()) {
+      clearRecordCapture();
+      resetRecordState();
+    }
+    dispatchProjectIntent({ type: 'track.remove', trackId: track.id });
+    const message = `Removed track ${track.name}`;
+    setStatus(message);
+    logOutput(message);
+    return true;
+  };
+
+  const updateSelectedSource = (patch) => {
+    const source = selectedSource();
+    if (!source) return;
+    dispatchProjectIntent({ type: 'source.update', sourceId: source.id, patch });
+  };
+
+  const updateSelectedMapping = (patch) => {
+    const source = selectedSource();
+    if (!source) return;
+    dispatchProjectIntent({ type: 'source.mapping.update', sourceId: source.id, patch });
+  };
+
+  const revertSelectedSource = () => {
+    const current = ensureProject();
+    const source = selectedSource();
+    if (!source) return;
+    dispatchProjectIntent({
+      type: 'source.update',
+      sourceId: source.id,
+      patch: sourceBaselinePatch(source, current)
+    });
+    const message = `Reverted ${source.label}`;
+    setStatus(message);
+    logOutput(message);
+  };
+
+  const updateSelectedClip = (patch) => {
+    const clip = selectedClip();
+    if (!clip) return;
+    dispatchProjectIntent({ type: 'clip.update', clipId: clip.id, patch });
+  };
+
+  const duplicateSelectedClip = () => {
+    const clip = selectedClip();
+    if (!clip) return false;
+    const next = dispatchProjectIntent({ type: 'clip.duplicate', clipId: clip.id });
+    const duplicate = next.clips.find(item => item.id === next.ui.selectedClipId);
+    const message = `Duplicated clip ${duplicate?.name || clip.name}`;
+    setStatus(message);
+    logOutput(message);
+    return true;
+  };
+
+  const removeSelectedClip = () => {
+    const clip = selectedClip();
+    if (!clip) return false;
+    if (recordState.clipId === clip.id && hasRecordCapture()) {
+      clearRecordCapture();
+      resetRecordState();
+    }
+    dispatchProjectIntent({ type: 'clip.remove', clipId: clip.id });
+    const message = `Removed clip ${clip.name}`;
+    setStatus(message);
+    logOutput(message);
+    return true;
+  };
+
+  const updateSelectedClipStep = (stepIndex, patch) => {
+    const clip = selectedClip();
+    if (!clip) return;
+    dispatchProjectIntent({ type: 'clip.step.update', clipId: clip.id, stepIndex, patch });
+  };
+
+  const updateEnvelope = () => {
+    const attack = toNumberOrNull(document?.getElementById('midiEnvAttack')?.value);
+    const decay = toNumberOrNull(document?.getElementById('midiEnvDecay')?.value);
+    const sustain = toNumberOrNull(document?.getElementById('midiEnvSustain')?.value);
+    const release = toNumberOrNull(document?.getElementById('midiEnvRelease')?.value);
+    const values = [attack, decay, sustain, release];
+    updateSelectedMapping({
+      envelope: values.every(value => value == null)
+        ? null
+        : {
+          attack: attack ?? 0,
+          decay: decay ?? 0,
+          sustain: sustain ?? 1,
+          release: release ?? 0
         }
+    });
+  };
+
+  const bindMidiUi = () => {
+    if (bound) return;
+    ensureProject();
+    cleanupLegacyMidiProjectStorage(storage);
+    bindById('midiEnabledToggle', 'change', async event => {
+      const enabled = !!event.target.checked;
+      dispatchProjectIntent({ type: 'enabled.set', enabled });
+      const lemmings = getLemmings();
+      if (lemmings?.setMidiEnabled) await lemmings.setMidiEnabled(enabled);
+      if (enabled && getWebMidi()?.enabled) onEnabled();
+      if (!enabled) {
+        unbindDeviceListeners();
+        setActiveMidiInput(null);
+        showError('');
       }
+      render();
+    });
+    bindById('midiInSelect', 'change', event => {
+      const inputId = event.target.value || null;
+      dispatchProjectIntent({ type: 'devices.set', devices: { inputId } });
+      setActiveMidiInput(inputId);
+    });
+    bindById('midiOutSelect', 'change', event => {
+      const outputId = event.target.value || null;
+      dispatchProjectIntent({ type: 'devices.set', devices: { outputId } });
+      setActiveMidiOutput(outputId);
+    });
+    bindById('midiInputChannel', 'change', event => {
+      dispatchProjectIntent({ type: 'devices.set', devices: { inputChannel: event.target.value || 'omni' } });
+    });
+    bindById('midiBpmBase', 'change', event => {
+      dispatchProjectIntent({ type: 'transport.set', transport: { bpmBase: Number(event.target.value) || 120 } });
+    });
+    bindById('midiQuantize', 'change', event => {
+      dispatchProjectIntent({ type: 'transport.set', transport: { quantize: event.target.value || '1/16' } });
+    });
+    bindById('midiSwing', 'change', event => {
+      dispatchProjectIntent({ type: 'transport.set', transport: { swing: Number(event.target.value) || 0 } });
+    });
+    const updateTimeSignature = () => {
+      const current = ensureProject();
+      const beats = Number(document?.getElementById('midiTimeSignatureBeats')?.value) ||
+        current.transport.timeSignature?.beats ||
+        4;
+      const unit = Number(document?.getElementById('midiTimeSignatureUnit')?.value) ||
+        current.transport.timeSignature?.unit ||
+        4;
+      dispatchProjectIntent({
+        type: 'transport.set',
+        transport: { timeSignature: { beats, unit } }
+      });
     };
-    updateBpm();
-    window?.setInterval?.(updateBpm, 500);
-
-    const updateDebug = () => {
-      if (debugInput) {
-        debugInput.textContent = `Input: ${formatDebugBytes(window?.lastMidiInputMessage)}`;
+    bindById('midiTimeSignatureBeats', 'change', updateTimeSignature);
+    bindById('midiTimeSignatureUnit', 'change', updateTimeSignature);
+    const updateScale = (patch) => {
+      const current = ensureProject();
+      updateGlobal({ scale: { ...current.global.scale, ...patch } });
+    };
+    bindById('midiScaleRoot', 'change', event => {
+      updateScale({ root: toNumberOrNull(event.target.value) ?? 0 });
+    });
+    bindById('midiScaleName', 'change', event => {
+      const name = event.target.value || 'chromatic-minor';
+      updateScale({
+        name,
+        degrees: scalePresetDegrees(name) || ensureProject().global.scale.degrees
+      });
+    });
+    bindById('midiProjectResetButton', 'click', () => resetProject());
+    bindById('midiPanicButton', 'click', () => panic());
+    bindById('midiReversePanicToggle', 'change', event => {
+      const current = ensureProject();
+      updateGlobal({ reverse: { ...current.global.reverse, allNotesOffOnToggle: !!event.target.checked } });
+    });
+    bindById('midiTemplateSelect', 'change', () => setStatus('Template ready'));
+    bindById('midiTemplateSelect', 'keydown', event => {
+      if (event.key !== 'Enter' || !(event.ctrlKey || event.metaKey) || event.altKey || event.shiftKey) return;
+      event.preventDefault?.();
+      event.stopPropagation?.();
+      resetProject();
+    });
+    bindById('midiTemplateSaveButton', 'click', () => saveProjectTemplate());
+    bindById('midiProjectExportButton', 'click', () => exportProject());
+    bindById('midiProjectImportButton', 'click', () => document?.getElementById('midiProjectImportInput')?.click?.());
+    bindById('midiProjectImportInput', 'change', async event => {
+      const file = event.target?.files?.[0] || null;
+      await importProjectFile(file);
+      if (event.target) event.target.value = '';
+    });
+    bindById('midiSourceSearch', 'input', event => {
+      sourceFilters.search = event.target.value || '';
+      renderSourceList();
+    });
+    bindById('midiSourceKindFilter', 'change', event => {
+      sourceFilters.kind = event.target.value || 'all';
+      renderSourceList();
+    });
+    bindById('midiSourceAssignFilter', 'change', event => {
+      sourceFilters.assignment = event.target.value || 'all';
+      renderSourceList();
+    });
+    bindById('midiSourceList', 'keydown', event => {
+      const sources = filteredSources();
+      const selectedSourceId = ensureProject().ui.selectedSourceId;
+      const currentSourceId = sources.some(source => source.id === selectedSourceId)
+        ? selectedSourceId
+        : sources[0]?.id ?? selectedSourceId;
+      handleListboxNavigation(
+        event,
+        sources,
+        source => source.id,
+        currentSourceId,
+        sourceId => dispatchProjectIntent({ type: 'source.select', sourceId })
+      );
+    });
+    bindById('midiTrackList', 'keydown', event => {
+      handleListboxNavigation(
+        event,
+        ensureProject().tracks,
+        track => track.id,
+        ensureProject().ui.selectedTrackId,
+        trackId => dispatchProjectIntent({ type: 'track.select', trackId })
+      );
+    });
+    bindById('midiClipList', 'keydown', event => {
+      const clips = ensureProject().clips;
+      const selectedClipId = ensureProject().ui.selectedClipId;
+      const currentClipId = clips.some(clip => clip.id === selectedClipId)
+        ? selectedClipId
+        : clips[0]?.id ?? selectedClipId;
+      handleListboxNavigation(
+        event,
+        clips,
+        clip => clip.id,
+        currentClipId,
+        clipId => dispatchProjectIntent({ type: 'clip.select', clipId })
+      );
+    });
+    bindById('midiStepPatternGrid', 'keydown', event => {
+      const clip = selectedClip();
+      const stepCount = Math.min(clip?.lengthSteps || 0, STEP_FIELD_COUNT);
+      handleStepGridNavigation(event, document?.getElementById('midiStepPatternGrid'), stepCount, resolveStepGridColumnCount());
+    });
+    bindById('midiTrackAdd', 'click', () => dispatchProjectIntent({ type: 'track.add', track: {} }));
+    bindById('midiTrackRemove', 'click', () => removeSelectedTrack());
+    bindById('midiClipAddButton', 'click', () => dispatchProjectIntent({ type: 'clip.add', clip: {} }));
+    bindById('midiClipDuplicateButton', 'click', () => duplicateSelectedClip());
+    bindById('midiClipRemoveButton', 'click', () => removeSelectedClip());
+    bindById('midiAssignSourceButton', 'click', () => {
+      const source = selectedSource();
+      const trackId = document?.getElementById('midiAssignTrackSelect')?.value;
+      if (source && trackId) dispatchProjectIntent({ type: 'source.assignTrack', sourceId: source.id, trackId });
+    });
+    bindById('midiAssignClipButton', 'click', () => {
+      const source = selectedSource();
+      const clipId = document?.getElementById('midiSourceClipSelect')?.value || selectedClip()?.id || null;
+      if (source && clipId) dispatchProjectIntent({ type: 'source.clip.assign', sourceId: source.id, clipId });
+    });
+    bindById('midiAuditionButton', 'click', () => audition());
+    bindById('midiClipAuditionButton', 'click', () => audition({ clipId: selectedClip()?.id, trackId: selectedTrack()?.id }));
+    bindById('midiLearnButton', 'click', () => startLearn());
+    bindById('midiLearnConfirmButton', 'click', () => confirmLearn());
+    bindById('midiLearnCancelButton', 'click', () => cancelLearn());
+    bindById('midiTrackName', 'change', event => updateSelectedTrack({ name: event.target.value }));
+    bindById('midiTrackInstrument', 'change', event => updateSelectedTrack({ instrumentLabel: event.target.value }));
+    bindById('midiTrackOutputSelect', 'change', event => {
+      clearMidiOutputState();
+      updateSelectedTrack({ outputId: event.target.value || null });
+    });
+    bindById('midiTrackChannel', 'change', event => updateSelectedTrack({ channel: Number(event.target.value) || 1 }));
+    bindById('midiTrackPriority', 'change', event => updateSelectedTrack({ priority: Number(event.target.value) || 0 }));
+    bindById('midiTrackVoiceBudget', 'change', event => updateSelectedTrack({ voiceBudget: Number(event.target.value) || 1 }));
+    bindById('midiTrackVelocityScale', 'change', event => updateSelectedTrack({ velocityScale: Number(event.target.value) }));
+    bindById('midiTrackMute', 'change', event => updateSelectedTrack({ mute: !!event.target.checked }));
+    bindById('midiTrackSolo', 'change', event => updateSelectedTrack({ solo: !!event.target.checked }));
+    bindById('midiTrackArm', 'change', event => updateSelectedTrack({ arm: !!event.target.checked }));
+    bindById('midiSourceRevertButton', 'click', () => revertSelectedSource());
+    bindById('midiSourceEnabled', 'change', event => updateSelectedSource({ enabled: !!event.target.checked }));
+    bindById('midiSourceTrackSelect', 'change', event => {
+      const source = selectedSource();
+      if (source) dispatchProjectIntent({ type: 'source.assignTrack', sourceId: source.id, trackId: event.target.value });
+    });
+    bindById('midiSourceModeSelect', 'change', event => {
+      const source = selectedSource();
+      if (!source) return;
+      const mode = event.target.value === 'clip' ? 'clip' : 'direct';
+      const clipId = mode === 'clip' ? selectedClip()?.id || null : null;
+      if (mode === 'clip' && !clipId) {
+        setStatus('Create a clip before using clip mode');
+        renderInspector();
+        return;
       }
-      if (debugOutput) {
-        debugOutput.textContent = `Output: ${formatDebugOutput(window?.lastMidiOutputMessage)}`;
+      dispatchProjectIntent({ type: 'source.mode.set', sourceId: source.id, mode, clipId });
+    });
+    bindById('midiSourceClipSelect', 'change', event => {
+      const source = selectedSource();
+      if (source && event.target.value) dispatchProjectIntent({ type: 'source.clip.assign', sourceId: source.id, clipId: event.target.value });
+    });
+    bindById('midiMappingNote', 'change', event => {
+      const note = toNumberOrNull(event.target.value);
+      updateSelectedMapping({ note, degree: note == null ? selectedSource()?.mapping?.degree ?? null : null, chord: note == null ? selectedSource()?.mapping?.chord ?? null : null });
+    });
+    bindById('midiMappingDegree', 'change', event => {
+      const degree = toNumberOrNull(event.target.value);
+      updateSelectedMapping({ degree, note: degree == null ? selectedSource()?.mapping?.note ?? null : null });
+    });
+    bindById('midiMappingOctave', 'change', event => updateSelectedMapping({ octave: Number(event.target.value) || 4 }));
+    bindById('midiMappingVelocity', 'change', event => updateSelectedMapping({ velocity: toNumberOrNull(event.target.value) }));
+    bindById('midiMappingDuration', 'change', event => updateSelectedMapping({ durationTicks: toNumberOrNull(event.target.value) }));
+    bindById('midiMappingPan', 'change', event => updateSelectedMapping({ pan: toNumberOrNull(event.target.value) }));
+    bindById('midiMappingTimbre', 'change', event => updateSelectedMapping({ timbre: toNumberOrNull(event.target.value) }));
+    bindById('midiMappingPitchBend', 'change', event => updateSelectedMapping({ pitchBend: toNumberOrNull(event.target.value) }));
+    bindById('midiMappingChord', 'change', event => {
+      const type = event.target.value;
+      const inversion = selectedSource()?.mapping?.chord?.inversion ?? 0;
+      updateSelectedMapping({
+        chord: CHORD_TYPES.includes(type) ? { type, inversion } : null,
+        note: type ? null : selectedSource()?.mapping?.note ?? null,
+        degree: type ? selectedSource()?.mapping?.degree ?? 0 : selectedSource()?.mapping?.degree ?? null
+      });
+    });
+    bindById('midiMappingChordInversion', 'change', event => {
+      const chord = selectedSource()?.mapping?.chord;
+      if (!chord) return;
+      updateSelectedMapping({
+        chord: {
+          ...chord,
+          inversion: Math.max(0, Math.round(Number(event.target.value) || 0))
+        }
+      });
+    });
+    bindById('midiMappingArp', 'change', event => {
+      const mode = ARP_MODES.includes(event.target.value) ? event.target.value : '';
+      updateSelectedMapping({
+        arp: mode
+          ? { ...(selectedSource()?.mapping?.arp || {}), enabled: true, mode }
+          : null
+      });
+    });
+    bindById('midiEnvelopeOverrideToggle', 'change', event => {
+      updateSelectedMapping({
+        envelope: event.target.checked
+          ? { attack: 1, decay: 0, sustain: 1, release: 1 }
+          : null
+      });
+    });
+    for (const id of ['midiEnvAttack', 'midiEnvDecay', 'midiEnvSustain', 'midiEnvRelease']) {
+      bindById(id, 'change', updateEnvelope);
+    }
+    const readGlobalNumber = (value, fallback) => toNumberOrNull(value) ?? fallback;
+    const updateGlobalVelocityRange = (patch) => {
+      const current = ensureProject();
+      updateGlobal({ velocityRange: { ...current.global.velocityRange, ...patch } });
+    };
+    const updateGlobalNoteRange = (patch) => {
+      const current = ensureProject();
+      updateGlobal({ noteRange: { ...current.global.noteRange, ...patch } });
+    };
+    bindById('midiGlobalIntensity', 'change', event => {
+      const current = ensureProject();
+      updateGlobalVelocityRange({ default: readGlobalNumber(event.target.value, current.global.velocityRange.default) });
+    });
+    bindById('midiGlobalVelocityMin', 'change', event => {
+      const current = ensureProject();
+      updateGlobalVelocityRange({ min: readGlobalNumber(event.target.value, current.global.velocityRange.min) });
+    });
+    bindById('midiGlobalVelocityMax', 'change', event => {
+      const current = ensureProject();
+      updateGlobalVelocityRange({ max: readGlobalNumber(event.target.value, current.global.velocityRange.max) });
+    });
+    bindById('midiGlobalNoteMin', 'change', event => {
+      const current = ensureProject();
+      updateGlobalNoteRange({ min: readGlobalNumber(event.target.value, current.global.noteRange.min) });
+    });
+    bindById('midiGlobalNoteMax', 'change', event => {
+      const current = ensureProject();
+      updateGlobalNoteRange({ max: readGlobalNumber(event.target.value, current.global.noteRange.max) });
+    });
+    const updateGlobalDensity = (patch) => {
+      const current = ensureProject();
+      updateGlobal({ density: { ...current.global.density, ...patch } });
+    };
+    bindById('midiGlobalAccent', 'change', event => {
+      updateGlobalDensity({ velocityBoost: Number(event.target.value) || 0 });
+    });
+    bindById('midiGlobalDensityWindow', 'change', event => {
+      updateGlobalDensity({ windowTicks: Number(event.target.value) || 0 });
+    });
+    bindById('midiGlobalDurationScale', 'change', event => {
+      updateGlobalDensity({ durationScale: Number(event.target.value) || 0 });
+    });
+    const updateGlobalLimits = (patch) => {
+      const current = ensureProject();
+      updateGlobal({ limits: { ...current.global.limits, ...patch } });
+    };
+    bindById('midiGlobalMaxActiveNotes', 'change', event => {
+      updateGlobalLimits({ maxActiveNotes: Number(event.target.value) || 1 });
+    });
+    bindById('midiGlobalMaxEventsPerTick', 'change', event => {
+      updateGlobalLimits({ maxEventsPerTick: Number(event.target.value) || 1 });
+    });
+    const updateGlobalPosition = (patch) => {
+      const current = ensureProject();
+      updateGlobal({ position: { ...current.global.position, ...patch } });
+    };
+    bindById('midiGlobalViewPan', 'change', event => {
+      updateGlobalPosition({ viewPan: !!event.target.checked });
+    });
+    bindById('midiGlobalPanMin', 'change', event => {
+      const current = ensureProject();
+      updateGlobalPosition({
+        panRange: {
+          ...current.global.position.panRange,
+          min: readGlobalNumber(event.target.value, current.global.position.panRange.min)
+        }
+      });
+    });
+    bindById('midiGlobalPanMax', 'change', event => {
+      const current = ensureProject();
+      updateGlobalPosition({
+        panRange: {
+          ...current.global.position.panRange,
+          max: readGlobalNumber(event.target.value, current.global.position.panRange.max)
+        }
+      });
+    });
+    bindById('midiGlobalPanDeadZone', 'change', event => {
+      const current = ensureProject();
+      updateGlobalPosition({
+        panDeadZonePct: readGlobalNumber(event.target.value, current.global.position.panDeadZonePct)
+      });
+    });
+    bindById('midiGlobalTimbreMin', 'change', event => {
+      const current = ensureProject();
+      updateGlobalPosition({
+        timbreRange: {
+          ...current.global.position.timbreRange,
+          min: readGlobalNumber(event.target.value, current.global.position.timbreRange.min)
+        }
+      });
+    });
+    bindById('midiGlobalTimbreMax', 'change', event => {
+      const current = ensureProject();
+      updateGlobalPosition({
+        timbreRange: {
+          ...current.global.position.timbreRange,
+          max: readGlobalNumber(event.target.value, current.global.position.timbreRange.max)
+        }
+      });
+    });
+    bindById('midiGlobalXNoteMin', 'change', event => {
+      const current = ensureProject();
+      updateGlobalPosition({
+        xNoteRange: {
+          ...current.global.position.xNoteRange,
+          min: readGlobalNumber(event.target.value, current.global.position.xNoteRange.min)
+        }
+      });
+    });
+    bindById('midiGlobalXNoteMax', 'change', event => {
+      const current = ensureProject();
+      updateGlobalPosition({
+        xNoteRange: {
+          ...current.global.position.xNoteRange,
+          max: readGlobalNumber(event.target.value, current.global.position.xNoteRange.max)
+        }
+      });
+    });
+    const updateGlobalDurationTicks = () => {
+      const current = ensureProject();
+      const readDurationValue = (id, fallback) => toNumberOrNull(document?.getElementById(id)?.value) ?? fallback;
+      updateGlobal({
+        durationTicks: {
+          default: readDurationValue('midiGlobalDurationDefault', current.global.durationTicks.default),
+          min: readDurationValue('midiGlobalDurationMin', current.global.durationTicks.min),
+          max: readDurationValue('midiGlobalDurationMax', current.global.durationTicks.max)
+        }
+      });
+    };
+    for (const id of ['midiGlobalDurationDefault', 'midiGlobalDurationMin', 'midiGlobalDurationMax']) {
+      bindById(id, 'change', updateGlobalDurationTicks);
+    }
+    const updateGlobalEnvelope = () => {
+      const current = ensureProject();
+      const readEnvelopeValue = (id, fallback) => toNumberOrNull(document?.getElementById(id)?.value) ?? fallback;
+      updateGlobal({
+        envelope: {
+          attack: readEnvelopeValue('midiGlobalEnvAttack', current.global.envelope.attack),
+          decay: readEnvelopeValue('midiGlobalEnvDecay', current.global.envelope.decay),
+          sustain: readEnvelopeValue('midiGlobalEnvSustain', current.global.envelope.sustain),
+          release: readEnvelopeValue('midiGlobalEnvRelease', current.global.envelope.release)
+        }
+      });
+    };
+    for (const id of ['midiGlobalEnvAttack', 'midiGlobalEnvDecay', 'midiGlobalEnvSustain', 'midiGlobalEnvRelease']) {
+      bindById(id, 'change', updateGlobalEnvelope);
+    }
+    bindById('midiAutomationAddButton', 'click', () => {
+      const current = ensureProject();
+      const targets = ['note', 'velocity', 'pan', 'duration'];
+      const target = targets.find(item => !current.automation.some(lane => lane.target === item)) || 'velocity';
+      dispatchProjectIntent({ type: 'automation.add', automation: { target, axis: target === 'velocity' ? 'y' : 'x' } });
+    });
+    bindById('midiClipName', 'change', event => updateSelectedClip({ name: event.target.value }));
+    bindById('midiClipType', 'change', event => updateSelectedClip({ type: event.target.value }));
+    bindById('midiClipArpMode', 'change', event => {
+      const mode = ARP_MODES.includes(event.target.value) ? event.target.value : 'up';
+      const clip = selectedClip();
+      const patternLength = Array.isArray(clip?.arp?.pattern?.steps) ? clip.arp.pattern.steps.length : undefined;
+      const pattern = createArpPatternFromPreset(mode, patternLength);
+      updateSelectedClip({ arp: { ...(clip?.arp || {}), mode, pattern } });
+    });
+    bindById('midiClipArpPattern', 'change', event => {
+      const clip = selectedClip();
+      const preset = ARP_PATTERN_PRESETS.some(entry => entry.value === event.target.value)
+        ? event.target.value
+        : 'up';
+      const patternLength = Array.isArray(clip?.arp?.pattern?.steps) ? clip.arp.pattern.steps.length : undefined;
+      const pattern = createArpPatternFromPreset(preset, patternLength);
+      const mode = deriveArpModeFromPattern(pattern, clip?.arp?.mode || 'up');
+      updateSelectedClip({ arp: { ...(clip?.arp || {}), mode, pattern } });
+    });
+    bindById('midiClipLengthSteps', 'change', event => updateSelectedClip({ lengthSteps: Number(event.target.value) || 16 }));
+    bindById('midiRecordButton', 'click', () => startRecording());
+    bindById('midiRecordCommitButton', 'click', () => commitRecording());
+    bindById('midiRecordCancelButton', 'click', () => cancelRecording());
+    bindById('midiSequencerWorkspace', 'keydown', event => {
+      if (event.key === 'Escape' && cancelActiveCapture()) {
+        event.preventDefault?.();
+        event.stopPropagation?.();
+        return;
       }
+      if (!(event.ctrlKey || event.metaKey) || event.altKey || event.shiftKey) return;
+      const key = String(event.key || '').toLowerCase();
+      const importInput = () => document?.getElementById('midiProjectImportInput')?.click?.();
+      const shortcutActions = {
+        s: saveProjectTemplate,
+        e: exportProject,
+        i: importInput
+      };
+      const action = shortcutActions[key];
+      if (!action) return;
+      event.preventDefault?.();
+      event.stopPropagation?.();
+      action();
+    });
+    setMidiUiHook();
+    render();
+    bound = true;
+  };
+
+  const disposeDomListeners = () => {
+    while (domListeners.length) {
+      const { element, eventName, handler } = domListeners.pop();
+      element.removeEventListener?.(eventName, handler);
+    }
+  };
+
+  const clearMidiUiHook = () => {
+    if (!window || !Object.prototype.hasOwnProperty.call(window, '__LEMMINGS_MIDI_UI__')) return;
+    try {
+      delete window.__LEMMINGS_MIDI_UI__;
+    } catch (e) {
+      window.__LEMMINGS_MIDI_UI__ = undefined;
+    }
+  };
+
+  const setMidiUiHook = () => {
+    if (!window) return;
+    window.__LEMMINGS_MIDI_UI__ = {
+      getProject: () => cloneSafeObject(ensureProject()),
+      dispatchProjectIntent,
+      setProject,
+      resetProject,
+      exportProject,
+      importProject,
+      importProjectFile,
+      saveProjectTemplate,
+      getProjectTemplates,
+      getUiMetrics,
+      startLearn,
+      confirmLearn,
+      cancelLearn,
+      captureLearnNote: handleLearnNote,
+      startRecording,
+      commitRecording,
+      cancelRecording,
+      captureRecordMessage: handleRecordMessage,
+      audition,
+      panic
     };
-    updateDebug();
-    window?.setInterval?.(updateDebug, 250);
+  };
 
-    midiUiBound = true;
+  const dispose = () => {
+    if (refreshTimer != null && typeof window?.clearTimeout === 'function') {
+      window.clearTimeout(refreshTimer);
+    }
+    if (deviceRefreshTimer != null && typeof window?.clearTimeout === 'function') {
+      window.clearTimeout(deviceRefreshTimer);
+    }
+    refreshTimer = null;
+    deviceRefreshTimer = null;
+    unbindDeviceListeners();
+    disposeDomListeners();
+    clearMidiUiHook();
+    clearLearnCapture();
+    clearRecordCapture();
+    midiInputController?.detach?.();
+    activeMidiInput = null;
+    bound = false;
   };
 
   return {
     bindMidiUi,
-    scheduleMidiUiRefresh,
+    scheduleMidiUiRefresh: queueRender,
+    refreshMidiUiFromConfig: render,
     onEnabled,
     showError,
-    refreshMidiUiFromConfig,
-    setMidiOverrides,
-    setMidiInputController(controller) {
-      midiInputController = controller;
-      if (midiInputController?.setNoteCapture) {
-        midiInputController.setNoteCapture(noteCapture);
-      }
+    getMidiStatusHandlers() {
+      return { onEnabled, onError: showError };
     },
-    getMidiOverrides() {
-      return midiOverrides;
-    },
-    getMidiConfig: getConfig,
+    getProject: () => cloneSafeObject(ensureProject()),
+    dispatchProjectIntent,
+    setProject,
+    resetProject,
+    exportProject,
+    importProject,
+    importProjectFile,
+    saveProjectTemplate,
+    getProjectTemplates,
+    getUiMetrics,
+    startLearn,
+    confirmLearn,
+    cancelLearn,
+    captureLearnNote: handleLearnNote,
+    startRecording,
+    commitRecording,
+    cancelRecording,
+    captureRecordMessage: handleRecordMessage,
+    audition,
+    panic,
+    applyRuntimePatch,
+    getMidiConfig: getProjectConfig,
     getStoredEnabled() {
-      const stored = readStoredMidiId(storage, midiStorageKeys.enabled);
-      if (stored != null) return stored !== 'false';
-      const configEnabled = getConfig()?.enabled;
-      if (typeof configEnabled === 'boolean') return configEnabled;
-      return false;
+      cleanupLegacyMidiProjectStorage(storage);
+      const stored = readStoredMidiProject(storage);
+      if (stored) return !!stored.enabled;
+      const factory = getFactoryConfig();
+      return !!factory?.enabled;
     },
-    getStorageKeys() {
-      return { ...midiStorageKeys };
-    },
-    __test__: {
-      applySectionStates,
-      buildPositionMappingList,
-      resetMidiDefaults
+    setMidiInputController(controller) {
+      if (midiInputController && midiInputController !== controller) {
+        midiInputController.detach?.();
+      }
+      midiInputController = controller;
+      if (activeMidiInput) midiInputController?.attach?.(activeMidiInput);
+      if (learnState.active) midiInputController?.setNoteCapture?.(handleLearnNote);
+      if (recordState.active) midiInputController?.setMessageCapture?.(handleRecordMessage);
     },
     setActiveMidiInput,
-    setActiveMidiOutput
+    setActiveMidiOutput,
+    dispose,
+    getStorageKeys() {
+      return { project: PROJECT_STORAGE_KEY, templates: TEMPLATE_STORAGE_KEY };
+    }
   };
 };
+
+export { createMidiUiController };
diff --git a/js/app/procgen/ProcgenAiDirector.js b/js/app/procgen/ProcgenAiDirector.js
new file mode 100644
index 00000000..09d1f920
--- /dev/null
+++ b/js/app/procgen/ProcgenAiDirector.js
@@ -0,0 +1,495 @@
+import {
+  SkillTypes
+} from './ProcgenControllerShared.js';
+const procgenAiDirectorMethods = {
+  _initAiDirector() {
+    this._aiDecisionInterval = Math.max(1, Math.floor(this.aiDecisionInterval));
+    this._aiBudgetMax = {
+      builder: 14,
+      floater: 10,
+      bash: 8,
+      mine: 5,
+      dig: 6,
+      blocker: 6
+    };
+    this._aiBudget = {
+      builder: 10,
+      floater: 8,
+      bash: 6,
+      mine: 4,
+      dig: 5,
+      blocker: 5
+    };
+    this._aiBudgetRegen = {
+      builder: 2.2,
+      floater: 1.4,
+      bash: 1.1,
+      mine: 0.7,
+      dig: 0.9,
+      blocker: 0.8
+    };
+  },
+
+  _updateAiBudget(deltaSeconds) {
+    if (!this._aiBudget || !this._aiBudgetMax || !this._aiBudgetRegen) return;
+    const delta = Math.max(0, deltaSeconds);
+    for (const key of Object.keys(this._aiBudget)) {
+      const next = this._aiBudget[key] + this._aiBudgetRegen[key] * delta;
+      this._aiBudget[key] = Math.min(this._aiBudgetMax[key], next);
+    }
+  },
+
+  _updateAiDirector() {
+    const timer = this.game?.getGameTimer?.();
+    const tick = timer?.getGameTicks?.() ?? timer?.tickIndex ?? 0;
+    if (!Number.isFinite(tick)) return;
+    if (tick - this._aiLastDecisionTick < this._aiDecisionInterval) return;
+    this._aiLastDecisionTick = tick;
+    this._beginScanCacheWindow(tick);
+
+    this._applyEdgeBlockers(tick);
+    this._applyBunchingAssist(tick);
+
+    const lemming = this._getFrontierLemming();
+    if (!lemming) return;
+    if (this._shouldSkipAiFor(lemming, tick)) return;
+    const scan = this._scanAhead(lemming);
+    const action = this._decideAssist(lemming, scan, tick);
+    if (action) {
+      this._aiLastDecision = { tick, action, scan };
+    } else if (this._aiLastDecision && this._aiLastDecision.tick !== tick) {
+      this._aiLastDecision = { tick, action: null, scan };
+    }
+    this._updateDebugOverlay();
+  },
+
+  _beginScanCacheWindow(tick) {
+    const ground = this.level?.groundMask || null;
+    if (this._scanCache &&
+          this._scanCacheTick === tick &&
+          this._scanCacheGround === ground) {
+      return this._scanCache;
+    }
+    this._scanCacheTick = Number.isFinite(tick) ? tick : -Infinity;
+    this._scanCacheGround = ground;
+    this._scanCache = {
+      drop: new Map(),
+      wall: new Map(),
+      gap: new Map(),
+      hazard: new Map()
+    };
+    return this._scanCache;
+  },
+
+  _applyEdgeBlockers(tick) {
+    const manager = this.game?.getLemmingManager?.();
+    const lems = manager?.lemmings || [];
+    if (!lems.length) return;
+    const ground = this.level?.groundMask;
+    if (!ground) return;
+    for (const lem of lems) {
+      if (!lem || lem.removed || lem.disabled || lem.lookRight) continue;
+      if (!this._isAssignableAction(lem)) continue;
+      if (this._shouldSkipAiFor(lem, tick)) continue;
+      const x = Number.isFinite(lem.x) ? Math.floor(lem.x) : null;
+      const y = Number.isFinite(lem.y) ? Math.floor(lem.y) : null;
+      if (!Number.isFinite(x) || !Number.isFinite(y)) continue;
+      const nearLeftEdge = x <= 2;
+      const drop = this._getDropAt(ground, x - 1, y, this.maxDrop);
+      if ((nearLeftEdge || drop > 0) && this._canSpend('blocker')) {
+        if (manager.doLemmingAction(lem, SkillTypes.BLOCKER)) {
+          this._noteAiAction(lem, tick, 32, {
+            action: 'blocker',
+            reason: 'left-edge',
+            skillType: SkillTypes.BLOCKER,
+            spent: true,
+            targetX: x
+          });
+          return;
+        }
+        this._refundBudget('blocker');
+      }
+    }
+  },
+
+  _applyBunchingAssist(tick) {
+    const manager = this.game?.getLemmingManager?.();
+    const lems = manager?.lemmings || [];
+    if (!lems.length) return;
+    const levelHeight = this.level?.height ?? 0;
+    for (const lem of lems) {
+      if (!lem || lem.removed || lem.disabled) continue;
+      if (!this._isAssignableAction(lem)) continue;
+      if (this._shouldSkipAiFor(lem, tick)) continue;
+      const key = lem.id;
+      const prev = this._aiStallState.get(key) || {
+        lastX: lem.x,
+        lastDir: lem.lookRight,
+        stallTicks: 0,
+        flipCount: 0
+      };
+      const deltaX = Math.abs((lem.x ?? 0) - (prev.lastX ?? 0));
+      const sameDir = prev.lastDir === lem.lookRight;
+      let stallTicks = prev.stallTicks;
+      let flipCount = prev.flipCount;
+      if (deltaX < 0.5) {
+        stallTicks += 1;
+      } else {
+        stallTicks = Math.max(0, stallTicks - 1);
+      }
+      if (!sameDir && deltaX < 6) {
+        flipCount += 1;
+      } else if (deltaX > 2) {
+        flipCount = Math.max(0, flipCount - 1);
+      }
+
+      const stuck = stallTicks >= 18 || flipCount >= 3;
+      if (stuck) {
+        const highEnough = levelHeight > 0 && (lem.y ?? 0) < levelHeight * 0.6;
+        const attempts = [];
+        attempts.push({ skill: SkillTypes.BASHER, key: 'bash', cooldown: 32 });
+        attempts.push({ skill: SkillTypes.BUILDER, key: 'builder', cooldown: 36 });
+        if (highEnough) {
+          attempts.push({ skill: SkillTypes.DIGGER, key: 'dig', cooldown: 36 });
+          attempts.push({ skill: SkillTypes.MINER, key: 'mine', cooldown: 36 });
+        }
+        for (const option of attempts) {
+          if (!this._canSpend(option.key)) continue;
+          if (manager.doLemmingAction(lem, option.skill)) {
+            this._noteAiAction(lem, tick, option.cooldown, {
+              action: option.key,
+              reason: 'bunching',
+              skillType: option.skill,
+              spent: true
+            });
+            stallTicks = 0;
+            flipCount = 0;
+            break;
+          }
+          this._refundBudget(option.key);
+        }
+      }
+
+      this._aiStallState.set(key, {
+        lastX: lem.x,
+        lastDir: lem.lookRight,
+        stallTicks,
+        flipCount
+      });
+    }
+  },
+
+  _scanAhead(lemming) {
+    const ground = this.level?.groundMask;
+    if (!ground) return null;
+    const x0 = Math.floor(lemming.x);
+    const y0 = Math.floor(lemming.y);
+    const scanAhead = Math.max(6, Math.floor(this.aiScanAhead));
+    const levelHeight = this.level?.height ?? 0;
+    const maxDrop = Math.min(this.maxDrop, levelHeight);
+    const dir = lemming.lookRight ? 1 : -1;
+    let gap = null;
+    let wall = null;
+    for (let dx = 1; dx <= scanAhead; dx++) {
+      const testX = x0 + dx * dir;
+      const drop = this._getDropAt(ground, testX, y0, maxDrop);
+      if (drop > 0 && !gap) {
+        const gapWidth = this._measureGapWidth(ground, testX, y0, scanAhead, dir);
+        gap = { dx, drop, width: gapWidth };
+      }
+      const wallHeight = this._getWallHeight(ground, testX, y0, this.aiWallHeight, dir);
+      if (wallHeight > 0 && !wall) {
+        wall = { dx, height: wallHeight };
+      }
+      if (gap && wall) break;
+    }
+    const hazard = this._findHazardAhead(x0, y0, scanAhead, dir);
+    return { gap, wall, hazard, direction: dir };
+  },
+
+  _getDropAt(ground, x, y, maxDrop) {
+    const cache = this._scanCacheGround === ground ? this._scanCache?.drop : null;
+    const cacheKey = cache ? `${x}|${y}|${maxDrop}` : null;
+    if (cache && cache.has(cacheKey)) {
+      return cache.get(cacheKey);
+    }
+    const height = this.level?.height ?? 0;
+    const top = y + 1;
+    if (top < 0 || top >= height) {
+      if (cache) cache.set(cacheKey, 0);
+      return 0;
+    }
+    const available = Math.max(1, Math.min(maxDrop + 2, height - top));
+    const depth = ground.getColumnGapDepth(x, top, available);
+    const drop = depth <= 1 ? 0 : depth - 1;
+    if (cache) cache.set(cacheKey, drop);
+    return drop;
+  },
+
+  _measureGapWidth(ground, startX, y, scanAhead, dir) {
+    const cache = this._scanCacheGround === ground ? this._scanCache?.gap : null;
+    const cacheKey = cache ? `${startX}|${y}|${scanAhead}|${dir}|${this.maxDrop}` : null;
+    if (cache && cache.has(cacheKey)) {
+      return cache.get(cacheKey);
+    }
+    let width = 0;
+    for (let dx = 0; dx <= scanAhead; dx++) {
+      const drop = this._getDropAt(ground, startX + dx * dir, y, this.maxDrop);
+      if (drop <= 0) break;
+      width += 1;
+      if (width >= scanAhead) break;
+    }
+    if (cache) cache.set(cacheKey, width);
+    return width;
+  },
+
+  _getWallHeight(ground, x, y, maxHeight, dir) {
+    const height = Math.max(1, Math.floor(maxHeight));
+    const cache = this._scanCacheGround === ground ? this._scanCache?.wall : null;
+    const cacheKey = cache ? `${x}|${y}|${height}` : null;
+    if (cache && cache.has(cacheKey)) {
+      return cache.get(cacheKey);
+    }
+    const wall = typeof ground.getColumnWallHeight === 'function'
+      ? ground.getColumnWallHeight(x, y, height)
+      : (() => {
+        let result = 0;
+        for (let dy = 1; dy <= height; dy++) {
+          if (ground.hasGroundAt(x, y - dy)) result = dy;
+        }
+        return result;
+      })();
+    if (cache) cache.set(cacheKey, wall);
+    return wall;
+  },
+
+  _findHazardAhead(x, y, scanAhead, dir) {
+    const triggerList = this.level?.triggers;
+    const sourceSize = triggerList?.length ?? 0;
+    const timer = this.game?.getGameTimer?.();
+    const tick = timer?.getGameTicks?.() ?? timer?.tickIndex ?? 0;
+    const dueRefresh = tick - this._hazardIndexLastRefreshTick >= this.aiHazardIndexRefreshTicks;
+    if (triggerList !== this._hazardTriggerSource ||
+          sourceSize !== this._hazardTriggerSourceSize ||
+          dueRefresh) {
+      this._rebuildHazardIndex(tick);
+    }
+    const hazards = this._hazardTriggers;
+    if (!hazards.length) return null;
+    const hazardCache = this._scanCache?.hazard || null;
+    const hazardCacheKey = hazardCache
+      ? `${x}|${y}|${scanAhead}|${dir}|${this._hazardIndexLastRefreshTick}`
+      : null;
+    if (hazardCache && hazardCache.has(hazardCacheKey)) {
+      return hazardCache.get(hazardCacheKey);
+    }
+    const maxDx = Math.max(1, Math.floor(scanAhead));
+    const minX = dir >= 0 ? x + 1 : x - maxDx;
+    const maxX = dir >= 0 ? x + maxDx : x - 1;
+    let best = null;
+    for (let i = 0; i < hazards.length; i += 1) {
+      const trigger = hazards[i];
+      if (trigger.x1 > maxX) break;
+      if (trigger.x2 <= minX) continue;
+      if (y < trigger.y1 || y >= trigger.y2) continue;
+      const rightEdge = trigger.x2 - 1;
+      const dx = dir >= 0
+        ? (trigger.x1 <= x + 1 ? 1 : trigger.x1 - x)
+        : (rightEdge >= x - 1 ? 1 : x - rightEdge);
+      if (dx < 1 || dx > maxDx) continue;
+      if (!best || dx < best.dx) {
+        best = { dx, type: trigger.type };
+        if (dx === 1) break;
+      }
+    }
+    if (hazardCache) {
+      hazardCache.set(hazardCacheKey, best);
+    }
+    return best;
+  },
+
+  _decideAssist(lemming, scan, tick) {
+    if (!scan) return null;
+    const manager = this.game?.getLemmingManager?.();
+    if (!manager) return null;
+    if (!this._isAssignableAction(lemming)) return null;
+    const skillOrder = [];
+    let noopReason = 'traversable';
+    if (scan.direction === -1 && scan.gap && scan.gap.dx <= 2) {
+      skillOrder.push({
+        skill: SkillTypes.BLOCKER,
+        key: 'blocker',
+        cooldown: 40,
+        reason: 'wrong-way-gap'
+      });
+    }
+    if (scan.hazard && scan.hazard.dx <= this.aiHazardDistance) {
+      skillOrder.push({
+        skill: SkillTypes.BLOCKER,
+        key: 'blocker',
+        reason: 'hazard'
+      });
+    }
+    if (scan.gap && scan.gap.width >= 2 && scan.gap.width <= 8) {
+      skillOrder.push({
+        skill: SkillTypes.BUILDER,
+        key: 'builder',
+        cooldown: 48,
+        reason: 'small-gap',
+        targetX: lemming.x + scan.gap.dx * scan.direction
+      });
+    } else if (scan.gap && scan.gap.drop >= this.aiFloaterDrop) {
+      skillOrder.push({
+        skill: SkillTypes.FLOATER,
+        key: 'floater',
+        reason: 'unsafe-drop',
+        targetX: lemming.x + scan.gap.dx * scan.direction
+      });
+    } else if (scan.gap && scan.gap.drop > 0) {
+      noopReason = 'safe-drop';
+    }
+    const smallBarrierHeight = Math.max(2, Math.floor(this.maxStepUp) + 1);
+    if (scan.wall && scan.wall.height >= smallBarrierHeight) {
+      const barrierReason = scan.wall.height <= this.aiWallHeight + 4
+        ? 'small-barrier'
+        : 'large-barrier';
+      skillOrder.push({
+        skill: SkillTypes.BASHER,
+        key: 'bash',
+        reason: barrierReason,
+        targetX: lemming.x + scan.wall.dx * scan.direction
+      });
+      skillOrder.push({
+        skill: SkillTypes.DIGGER,
+        key: 'dig',
+        reason: barrierReason,
+        targetX: lemming.x + scan.wall.dx * scan.direction
+      });
+      if (scan.wall.height >= this.aiWallHeight + 4 || this._rand() < 0.15) {
+        skillOrder.push({
+          skill: SkillTypes.MINER,
+          key: 'mine',
+          reason: barrierReason,
+          targetX: lemming.x + scan.wall.dx * scan.direction
+        });
+      }
+    }
+    if (!skillOrder.length) {
+      this._recordAssistDecision({
+        tick,
+        type: 'noop',
+        reason: noopReason,
+        lemming,
+        scan,
+        success: true
+      });
+      return null;
+    }
+    for (const option of skillOrder) {
+      if (!this._canSpend(option.key)) continue;
+      const certificate = this._verifyAssistChallenge?.(option, lemming, scan, tick) || null;
+      const certificateMeta = certificate ? {
+        certificateId: certificate.certificate?.id ?? null,
+        challengeType: certificate.certificate?.challengeType ?? null,
+        certificateDecision: certificate.fallback?.decision ?? null,
+        certificateResultType: certificate.fallback?.resultType ?? null
+      } : {};
+      if (manager.doLemmingAction(lemming, option.skill)) {
+        this._noteAiAction(lemming, tick, option.cooldown, {
+          action: option.key,
+          reason: option.reason,
+          skillType: option.skill,
+          spent: true,
+          scan,
+          targetX: option.targetX,
+          ...certificateMeta
+        });
+        return option.key;
+      }
+      this._refundBudget(option.key);
+      this._recordAssistDecision({
+        tick,
+        type: 'failed',
+        action: option.key,
+        reason: option.reason,
+        skillType: option.skill,
+        lemming,
+        scan,
+        success: false,
+        targetX: option.targetX,
+        ...certificateMeta
+      });
+    }
+    return null;
+  },
+
+  _shouldSkipAiFor(lemming, tick) {
+    if (!lemming || !Number.isFinite(tick)) return true;
+    const last = this._aiLemmingCooldown.get(lemming.id);
+    if (Number.isFinite(last) && tick < last) return true;
+    return false;
+  },
+
+  _noteAiAction(lemming, tick, extraCooldown = 0, assist = null) {
+    const cooldown = Math.max(this.aiActionCooldown, extraCooldown || 0);
+    this._aiLemmingCooldown.set(lemming.id, tick + cooldown);
+    if (assist) {
+      this._recordAssistDecision({
+        tick,
+        type: 'skill',
+        lemming,
+        ...assist
+      });
+    }
+  },
+
+  _canSpend(key) {
+    if (!this._aiBudget || !this._aiBudgetMax) return false;
+    if (!Object.prototype.hasOwnProperty.call(this._aiBudget, key)) return false;
+    if (this._aiBudget[key] < 1) return false;
+    this._aiBudget[key] -= 1;
+    return true;
+  },
+
+  _refundBudget(key) {
+    if (!this._aiBudget || !this._aiBudgetMax) return;
+    if (!Object.prototype.hasOwnProperty.call(this._aiBudget, key)) return;
+    this._aiBudget[key] = Math.min(this._aiBudgetMax[key], this._aiBudget[key] + 1);
+  },
+
+  _maybeTriggerBomber() {
+    if (this._bombCheckElapsed < 30) return;
+    if (this._rand() < this._bombChance) {
+      const manager = this.game?.getLemmingManager?.();
+      const lems = manager?.activeLemmings || manager?.lemmings || [];
+      let best = null;
+      let bestX = -Infinity;
+      for (const lem of lems) {
+        if (!lem || lem.removed || lem.disabled) continue;
+        if (lem.x > bestX) {
+          bestX = lem.x;
+          best = lem;
+        }
+      }
+      if (best && manager?.doLemmingAction?.(best, SkillTypes.BOMBER)) {
+        this._bombCheckElapsed = 0;
+        this._bombChance = 0.01;
+        return;
+      }
+    }
+    if (this._bombCheckElapsed >= 10) {
+      this._bombCheckElapsed = 0;
+      this._bombChance = Math.min(1, this._bombChance * 2);
+    }
+  },
+
+  _maybeTriggerNuke() {
+    if (this._nukeElapsed < 60) return;
+    if (this._rand() < 0.001) {
+      const manager = this.game?.getLemmingManager?.();
+      manager?.doNukeAllLemmings?.();
+    }
+    this._nukeElapsed = 0;
+  }
+};
+export { procgenAiDirectorMethods };
diff --git a/js/app/procgen/ProcgenControllerCore.js b/js/app/procgen/ProcgenControllerCore.js
new file mode 100644
index 00000000..115cc538
--- /dev/null
+++ b/js/app/procgen/ProcgenControllerCore.js
@@ -0,0 +1,187 @@
+import {
+  HAZARD_TRIGGER_TYPES,
+  Lemming,
+  SkillTypes,
+  SoundEventTypes,
+  TriggerTypes
+} from './ProcgenControllerShared.js';
+import { procgenLifecycleMethods } from './ProcgenLifecycle.js';
+import { procgenAiDirectorMethods } from './ProcgenAiDirector.js';
+import { procgenTerrainDirectorMethods } from './ProcgenTerrainDirector.js';
+import { procgenTerrainPlanningMethods } from './ProcgenTerrainPlanning.js';
+class ProcgenController {
+  constructor({ view, game, level, assets, stamper, options = {} }) {
+    this.view = view || null;
+    this.game = game || null;
+    this.level = level || null;
+    this.window = options.window || globalThis?.window;
+    this.assets = assets || null;
+    this.stamper = stamper || null;
+    this._rng = typeof options.rng === 'function' ? options.rng : Math.random;
+    this._rngSeed = Number.isFinite(options.rngSeed) ? (Math.trunc(options.rngSeed) >>> 0) : null;
+    this._selectedTheme = options.selectedTheme || assets?.styleName || assets?.selectedTheme || null;
+    this._themeContract = options.themeContract || null;
+    this._tickHandler = null;
+    this._running = false;
+    this._cameraX = 0;
+    this._groundEndX = 0;
+    this._groundTopY = 0;
+    this._segmentColorIndex = 0;
+    this._colorTransition = {
+      from: 1,
+      to: 1,
+      remaining: 0,
+      total: 0,
+      current: 1,
+      step: 0
+    };
+    this._sustainBaseY = 0;
+    this._sustainRemaining = 0;
+    this._builderCursorId = 0;
+    this._seenFalls = new Map();
+    this._soundHandler = null;
+    this._builderBurst = null;
+    this._cameraTargetX = null;
+    this._lastSecond = null;
+    this._bombCheckElapsed = 0;
+    this._bombChance = 0.0001;
+    this._nukeElapsed = 0;
+    this._terrainPlan = { mode: 'flat', remaining: 0 };
+    this._pendingDrop = false;
+    this._gaps = [];
+    this._gapScanStart = 0;
+    this._gapCooldown = 0;
+    this._structurePlan = null;
+    this._aiLastDecisionTick = 0;
+    this._aiDecisionInterval = 3;
+    this._aiBudget = null;
+    this._aiBudgetMax = null;
+    this._aiBudgetRegen = null;
+    this._aiLastDecision = null;
+    this._aiDebug = null;
+    this._aiLemmingCooldown = new Map();
+    this._aiStallState = new Map();
+    this._hazardTriggers = [];
+    this._hazardTriggerSource = null;
+    this._hazardTriggerSourceSize = -1;
+    this._hazardIndexLastRefreshTick = -Infinity;
+    this._scanCacheTick = -Infinity;
+    this._scanCacheGround = null;
+    this._scanCache = null;
+    this._trackerPruneElapsed = 0;
+    this._leftFallCounter = 0;
+    this._splatStreak = 0;
+    this._splatTarget = this._randInt(3, 10);
+    this._pendingMidairBuilder = null;
+    this._recentDecor = [];
+    this._recentAssists = [];
+    this._recentChunks = [];
+    this._recentCertificates = [];
+    this._recentPieces = [];
+    this._recentChunkSerial = 0;
+    this._recentCertificateSerial = 0;
+    this._recentPieceSerial = 0;
+    this._lastNoopAssist = null;
+    this._frontierState = null;
+    this._frontierCacheTick = -Infinity;
+    this._frontierLemmingState = new Map();
+    this._lookaheadState = null;
+    this._lookAheadDistance = 0;
+    this._lookAheadThreshold = 0;
+
+    this.groundHeight = Number.isFinite(options.groundHeight) ? options.groundHeight : 4;
+    this.groundColorIndex = Number.isFinite(options.groundColorIndex) ? options.groundColorIndex : 1;
+    this.initialGroundWidth = Number.isFinite(options.initialGroundWidth) ? options.initialGroundWidth : 120;
+    this.segmentMinWidth = Number.isFinite(options.segmentMinWidth) ? options.segmentMinWidth : 24;
+    this.segmentMaxWidth = Number.isFinite(options.segmentMaxWidth) ? options.segmentMaxWidth : 72;
+    this.extendThreshold = Number.isFinite(options.extendThreshold) ? options.extendThreshold : 16;
+    const explicitLookAhead = Number.isFinite(options.lookAhead)
+      ? Math.max(24, Math.floor(options.lookAhead))
+      : null;
+    this.lookAheadMin = Number.isFinite(options.lookAheadMin)
+      ? Math.max(24, Math.floor(options.lookAheadMin))
+      : (explicitLookAhead ?? 140);
+    this.lookAheadMax = Number.isFinite(options.lookAheadMax)
+      ? Math.max(this.lookAheadMin, Math.floor(options.lookAheadMax))
+      : Math.max(this.lookAheadMin, explicitLookAhead ?? 220);
+    this.lookAhead = this.lookAheadMax;
+    this.lookAheadSpeedTicks = Number.isFinite(options.lookAheadSpeedTicks)
+      ? Math.max(0, Math.floor(options.lookAheadSpeedTicks))
+      : 48;
+    this.recentChunkLimit = Number.isFinite(options.recentChunkLimit)
+      ? Math.max(1, Math.floor(options.recentChunkLimit))
+      : 32;
+    this.recentCertificateLimit = Number.isFinite(options.recentCertificateLimit)
+      ? Math.max(1, Math.floor(options.recentCertificateLimit))
+      : 32;
+    this.recentPieceLimit = Number.isFinite(options.recentPieceLimit)
+      ? Math.max(1, Math.floor(options.recentPieceLimit))
+      : 96;
+    this.procgenCertificateVerification = options.procgenCertificateVerification !== false;
+    this.procgenCertificateVerifier = typeof options.procgenCertificateVerifier === 'function'
+      ? options.procgenCertificateVerifier
+      : null;
+    this.procgenCertificateOptions = options.procgenCertificateOptions &&
+      typeof options.procgenCertificateOptions === 'object' &&
+      !Array.isArray(options.procgenCertificateOptions)
+      ? options.procgenCertificateOptions
+      : {};
+    this.generatedTrackingPruneDistance = Number.isFinite(options.generatedTrackingPruneDistance)
+      ? Math.max(0, Math.floor(options.generatedTrackingPruneDistance))
+      : 512;
+    this.followLerp = Number.isFinite(options.followLerp) ? options.followLerp : 0.12;
+    this.maxStepUp = Number.isFinite(options.maxStepUp) ? options.maxStepUp : 3;
+    this.maxDrop = Number.isFinite(options.maxDrop) ? options.maxDrop : (Lemming.LEM_MAX_FALLING - 1);
+    this.gapChance = Number.isFinite(options.gapChance) ? options.gapChance : 0.08;
+    this.gapMinWidth = Number.isFinite(options.gapMinWidth) ? options.gapMinWidth : 3;
+    this.gapMaxWidth = Number.isFinite(options.gapMaxWidth) ? options.gapMaxWidth : 9;
+    this.gapTriggerDistance = Number.isFinite(options.gapTriggerDistance) ? options.gapTriggerDistance : 10;
+    this.decorChance = Number.isFinite(options.decorChance) ? options.decorChance : 0.06;
+    this.aiDecisionInterval = Number.isFinite(options.aiDecisionInterval) ? options.aiDecisionInterval : 3;
+    this.aiScanAhead = Number.isFinite(options.aiScanAhead) ? options.aiScanAhead : 24;
+    this.aiWallHeight = Number.isFinite(options.aiWallHeight) ? options.aiWallHeight : 10;
+    this.aiHazardDistance = Number.isFinite(options.aiHazardDistance) ? options.aiHazardDistance : 18;
+    this.aiFloaterDrop = Number.isFinite(options.aiFloaterDrop) ? options.aiFloaterDrop : (Lemming.LEM_MAX_FALLING - 2);
+    this.aiDebugOverlay = options.aiDebugOverlay === true;
+    this.aiActionCooldown = Number.isFinite(options.aiActionCooldown) ? options.aiActionCooldown : 5;
+    this.aiNoopDebugIntervalTicks = Number.isFinite(options.aiNoopDebugIntervalTicks)
+      ? Math.max(1, Math.floor(options.aiNoopDebugIntervalTicks))
+      : 30;
+    this.aiHazardIndexRefreshTicks = Number.isFinite(options.aiHazardIndexRefreshTicks)
+      ? Math.max(1, Math.floor(options.aiHazardIndexRefreshTicks))
+      : 64;
+    this.aiTrackerPruneIntervalSeconds = Number.isFinite(options.aiTrackerPruneIntervalSeconds)
+      ? Math.max(1, Math.floor(options.aiTrackerPruneIntervalSeconds))
+      : 10;
+    this.fallEventMemoryTicks = Number.isFinite(options.fallEventMemoryTicks)
+      ? Math.max(30, Math.floor(options.fallEventMemoryTicks))
+      : 360;
+    this.frontierStuckTicks = Number.isFinite(options.frontierStuckTicks)
+      ? Math.max(1, Math.floor(options.frontierStuckTicks))
+      : 90;
+    this.frontierTurnaroundLimit = Number.isFinite(options.frontierTurnaroundLimit)
+      ? Math.max(1, Math.floor(options.frontierTurnaroundLimit))
+      : 6;
+    this.frontierTurnaroundPenalty = Number.isFinite(options.frontierTurnaroundPenalty)
+      ? Math.max(0, Math.floor(options.frontierTurnaroundPenalty))
+      : 12;
+    this.frontierMaxTrackedLemmings = Number.isFinite(options.frontierMaxTrackedLemmings)
+      ? Math.max(1, Math.floor(options.frontierMaxTrackedLemmings))
+      : 128;
+    this.gapTrackingLimit = Number.isFinite(options.gapTrackingLimit)
+      ? Math.max(1, Math.floor(options.gapTrackingLimit))
+      : 256;
+    this.entranceX = Number.isFinite(options.entranceX) ? options.entranceX : null;
+    this.entranceY = Number.isFinite(options.entranceY) ? options.entranceY : null;
+    this.entranceClearance = Number.isFinite(options.entranceClearance) ? options.entranceClearance : 24;
+  }
+}
+for (const methods of [
+  procgenLifecycleMethods,
+  procgenAiDirectorMethods,
+  procgenTerrainDirectorMethods,
+  procgenTerrainPlanningMethods
+]) {
+  Object.defineProperties(ProcgenController.prototype, Object.getOwnPropertyDescriptors(methods));
+}
+export { ProcgenController };
diff --git a/js/app/procgen/ProcgenControllerShared.js b/js/app/procgen/ProcgenControllerShared.js
new file mode 100644
index 00000000..b5404db8
--- /dev/null
+++ b/js/app/procgen/ProcgenControllerShared.js
@@ -0,0 +1,19 @@
+import { Lemming } from '../../lemmings/Lemming.js';
+import { SkillTypes } from '../../game/SkillTypes.js';
+import { SoundEventTypes } from '../../game/SoundEvents.js';
+import { TriggerTypes } from '../../level/TriggerTypes.js';
+
+const HAZARD_TRIGGER_TYPES = new Set([
+  TriggerTypes.TRAP,
+  TriggerTypes.DROWN,
+  TriggerTypes.KILL,
+  TriggerTypes.FRYING
+]);
+
+export {
+  HAZARD_TRIGGER_TYPES,
+  Lemming,
+  SkillTypes,
+  SoundEventTypes,
+  TriggerTypes
+};
diff --git a/js/app/procgen/ProcgenLifecycle.js b/js/app/procgen/ProcgenLifecycle.js
new file mode 100644
index 00000000..f0dbe3ae
--- /dev/null
+++ b/js/app/procgen/ProcgenLifecycle.js
@@ -0,0 +1,404 @@
+import {
+  SkillTypes,
+  SoundEventTypes
+} from './ProcgenControllerShared.js';
+const procgenLifecycleMethods = {
+  start() {
+    if (this._running) return;
+    if (!this.game || !this.level) return;
+    this._running = true;
+    this._initGround();
+    this._initAiDirector();
+    this._rebuildHazardIndex(0);
+    if (this.aiDebugOverlay) {
+      this._initDebugOverlay();
+    }
+    const stage = this.view?.stage || null;
+    if (stage?.gameImgProps?.viewPoint) {
+      this._cameraX = stage.gameImgProps.viewPoint.x || 0;
+    }
+    this._bindTimer();
+    this._bindSoundEvents();
+  },
+
+  stop() {
+    if (!this._running) return;
+    this._running = false;
+    this._unbindTimer();
+    this._unbindSoundEvents();
+    this._destroyDebugOverlay();
+    this._builderBurst = null;
+    this._pendingMidairBuilder = null;
+    this._seenFalls.clear();
+    this._aiLemmingCooldown.clear();
+    this._aiStallState.clear();
+    this._frontierLemmingState.clear();
+    this._gaps.length = 0;
+    this._gapScanStart = 0;
+    this._scanCache = null;
+    this._scanCacheGround = null;
+    this._scanCacheTick = -Infinity;
+    this._lastNoopAssist = null;
+    this._recentAssists.length = 0;
+    this._recentChunks.length = 0;
+    this._recentPieces.length = 0;
+    this._recentDecor.length = 0;
+  },
+
+  _bindTimer() {
+    const timer = this.game?.getGameTimer?.();
+    if (!timer?.onGameTick?.on) return;
+    this._tickHandler = () => this._onTick();
+    timer.onGameTick.on(this._tickHandler);
+  },
+
+  _unbindTimer() {
+    const timer = this.game?.getGameTimer?.();
+    if (!timer?.onGameTick?.off || !this._tickHandler) return;
+    timer.onGameTick.off(this._tickHandler);
+    this._tickHandler = null;
+  },
+
+  _bindSoundEvents() {
+    if (this._soundHandler) return;
+    const bus = this.game?.soundEvents;
+    if (!bus?.onEvent?.on) return;
+    this._soundHandler = event => {
+      if (event?.type !== SoundEventTypes.LEMMING_FELL_OFF &&
+            event?.type !== SoundEventTypes.LEMMING_SPLAT) {
+        return;
+      }
+      const lemmingId = event?.lemmingId;
+      const timer = this.game?.getGameTimer?.();
+      const tick = timer?.getGameTicks?.() ?? timer?.tickIndex ?? 0;
+      if (Number.isFinite(lemmingId)) {
+        const seenAtTick = this._seenFalls.get(lemmingId);
+        if (Number.isFinite(seenAtTick) && tick - seenAtTick <= this.fallEventMemoryTicks) {
+          return;
+        }
+        this._seenFalls.set(lemmingId, tick);
+      }
+      if (event?.type === SoundEventTypes.LEMMING_SPLAT) {
+        this._splatStreak += 1;
+        if (this._splatStreak >= this._splatTarget && !this._pendingMidairBuilder) {
+          this._pendingMidairBuilder = {
+            delay: this._randInt(4, 12),
+            dueTick: null,
+            targetId: null
+          };
+          this._splatStreak = 0;
+          this._splatTarget = this._randInt(3, 10);
+        }
+      } else {
+        this._splatStreak = 0;
+      }
+      const originX = Number.isFinite(event?.x) ? event.x : null;
+      const manager = this.game?.getLemmingManager?.();
+      const lem = Number.isFinite(lemmingId) ? manager?.getLemming?.(lemmingId) : null;
+      const fellLeft = lem ? !lem.lookRight : false;
+      if (fellLeft) {
+        this._leftFallCounter += 1;
+        const isBuilder = this._leftFallCounter % 20 === 0;
+        this._scheduleEdgeResponse(originX, isBuilder ? 'builder-left' : 'blocker');
+      } else {
+        this._scheduleBuilderBurst(originX);
+      }
+    };
+    bus.onEvent.on(this._soundHandler);
+  },
+
+  _unbindSoundEvents() {
+    const bus = this.game?.soundEvents;
+    if (bus?.onEvent?.off && this._soundHandler) {
+      bus.onEvent.off(this._soundHandler);
+    }
+    this._soundHandler = null;
+  },
+
+  _initGround() {
+    const entrance = this.level?.entrances?.[0] || null;
+    const entranceX = Number.isFinite(entrance?.x) ? entrance.x : 0;
+    const startX = Math.max(0, entranceX - Math.floor(this.initialGroundWidth / 4));
+    this._groundTopY = Math.max(0, (this.level?.height ?? 0) - this.groundHeight);
+    this._segmentColorIndex = this.groundColorIndex;
+    this._colorTransition = {
+      from: this._segmentColorIndex,
+      to: this._segmentColorIndex,
+      remaining: 0,
+      total: 0,
+      current: this._segmentColorIndex,
+      step: 0
+    };
+    this._sustainBaseY = this._groundTopY;
+    this._sustainRemaining = 0;
+    this._paintGround(startX, this.initialGroundWidth, this._groundTopY, this._segmentColorIndex);
+    this._groundEndX = Math.max(this._groundEndX, startX + this.initialGroundWidth);
+    this._recordGeneratedChunk?.({
+      type: 'initial-ground',
+      x: startX,
+      y: this._groundTopY,
+      width: this.initialGroundWidth,
+      height: this.groundHeight,
+      endX: startX + this.initialGroundWidth
+    });
+  },
+
+  _onTick() {
+    if (!this._running) return;
+    this._updateTimers();
+    const frontier = this._getFrontierLemming();
+    const frontierX = Number.isFinite(frontier?.x) ? frontier.x : null;
+    const guideX = Number.isFinite(frontierX) ? frontierX : this._getRightmostX();
+    if (!Number.isFinite(guideX)) return;
+    this._ensureGround(guideX);
+    this._processBuilderBurst();
+    this._processGapBridges();
+    this._processMidairBuilder();
+    this._updateAiDirector();
+    this._updateCamera(Number.isFinite(frontierX) ? frontierX : guideX);
+  },
+
+  _updateTimers() {
+    const timer = this.game?.getGameTimer?.();
+    const tick = timer?.getGameTicks?.() ?? timer?.tickIndex ?? null;
+    if (!Number.isFinite(tick)) return;
+    const seconds = Math.floor(tick / 17.5);
+    if (this._lastSecond == null) {
+      this._lastSecond = seconds;
+      return;
+    }
+    if (seconds <= this._lastSecond) return;
+    const delta = seconds - this._lastSecond;
+    this._lastSecond = seconds;
+    this._bombCheckElapsed += delta;
+    this._nukeElapsed += delta;
+    this._trackerPruneElapsed += delta;
+    this._updateAiBudget(delta);
+    this._maybeTriggerBomber();
+    this._maybeTriggerNuke();
+    if (this._trackerPruneElapsed >= this.aiTrackerPruneIntervalSeconds) {
+      this._trackerPruneElapsed = 0;
+      this._pruneTrackingState(tick);
+    }
+  },
+
+  _updateCamera(rightmostX) {
+    const stage = this.view?.stage;
+    const stageImage = stage?.gameImgProps;
+    if (!stage || !stageImage) return;
+    const scale = stageImage.viewPoint.scale || 1;
+    if (!Number.isFinite(scale) || scale <= 0) return;
+    const viewW = stageImage.canvasViewportSize.width / scale;
+    if (!Number.isFinite(viewW) || viewW <= 0) return;
+    const targetX = rightmostX - viewW / 2;
+    if (!Number.isFinite(this._cameraX)) {
+      this._cameraX = targetX;
+    }
+    this._cameraTargetX = targetX;
+    const frameMs = this.game?.getGameTimer?.().frameTime ?? 16;
+    const alpha = Math.min(1, Math.max(0.01, frameMs / 500));
+    this._cameraX += (this._cameraTargetX - this._cameraX) * alpha;
+    stage.applyViewport(stageImage, this._cameraX, 0, stageImage.viewPoint.scale);
+  },
+
+  _getSelectedTheme() {
+    return this._selectedTheme ||
+      this._themeContract?.selectedTheme ||
+      this.assets?.styleName ||
+      this.level?.styleName ||
+      null;
+  },
+
+  _trimRecentList(list, maxLength) {
+    if (!Array.isArray(list) || list.length <= maxLength) return;
+    list.splice(0, list.length - maxLength);
+  },
+
+  _pruneGeneratedTracking(referenceX = null) {
+    const anchorX = Number.isFinite(referenceX) ? referenceX : this._getRightmostX();
+    if (!Number.isFinite(anchorX)) return;
+    const cutoff = anchorX - this.generatedTrackingPruneDistance;
+    const keepRecent = entry => {
+      const endX = Number(entry?.endX ?? ((entry?.x ?? entry?.startX) + entry?.width));
+      return !Number.isFinite(endX) || endX >= cutoff;
+    };
+    if (Array.isArray(this._recentChunks)) {
+      for (let i = this._recentChunks.length - 1; i >= 0; i -= 1) {
+        if (keepRecent(this._recentChunks[i])) continue;
+        this._recentChunks.splice(i, 1);
+      }
+      this._trimRecentList(this._recentChunks, this.recentChunkLimit);
+    }
+    if (Array.isArray(this._recentPieces)) {
+      for (let i = this._recentPieces.length - 1; i >= 0; i -= 1) {
+        if (keepRecent(this._recentPieces[i])) continue;
+        this._recentPieces.splice(i, 1);
+      }
+      this._trimRecentList(this._recentPieces, this.recentPieceLimit);
+    }
+  },
+
+  _trackGeneratedChunk(chunk) {
+    if (!chunk) return;
+    const startX = Number(chunk.startX ?? chunk.x);
+    const endX = Number(chunk.endX ?? (startX + Number(chunk.width)));
+    if (!Number.isFinite(startX) || !Number.isFinite(endX)) return;
+    this._recentChunkSerial += 1;
+    this._recentChunks.push({
+      serial: this._recentChunkSerial,
+      type: chunk.type || 'terrain',
+      theme: this._getSelectedTheme(),
+      startX,
+      endX,
+      width: Math.max(0, endX - startX),
+      y: Number.isFinite(chunk.y) ? chunk.y : null,
+      topY: Number.isFinite(chunk.topY) ? chunk.topY : null,
+      colorIndex: Number.isFinite(chunk.colorIndex) ? chunk.colorIndex : null,
+      originalType: chunk.originalType || null,
+      certificateDecision: chunk.certificateDecision || null,
+      certificateResultType: chunk.certificateResultType || null
+    });
+    this._trimRecentList(this._recentChunks, this.recentChunkLimit);
+  },
+
+  _recordGeneratedChunk(chunk) {
+    this._trackGeneratedChunk(chunk);
+  },
+
+  _trackGeneratedPiece(piece, destX, destY, role = 'ground', rect = null) {
+    if (!piece?.bounds) return;
+    if (!Number.isFinite(destX) || !Number.isFinite(destY)) return;
+    const x = Number.isFinite(rect?.x) ? rect.x : destX + piece.bounds.minX;
+    const y = Number.isFinite(rect?.y) ? rect.y : destY + piece.bounds.minY;
+    const width = Number.isFinite(rect?.width) ? rect.width : piece.bounds.width;
+    const height = Number.isFinite(rect?.height) ? rect.height : piece.bounds.height;
+    this._recentPieceSerial += 1;
+    this._recentPieces.push({
+      serial: this._recentPieceSerial,
+      role,
+      theme: piece.styleName || piece.theme || this._getSelectedTheme(),
+      pieceId: piece.id ?? null,
+      x,
+      y,
+      endX: x + width,
+      width,
+      height,
+      bounds: {
+        minX: piece.bounds.minX,
+        minY: piece.bounds.minY,
+        maxX: piece.bounds.maxX,
+        maxY: piece.bounds.maxY,
+        width: piece.bounds.width,
+        height: piece.bounds.height
+      }
+    });
+    this._trimRecentList(this._recentPieces, this.recentPieceLimit);
+  },
+
+  _summarizeScan(scan) {
+    if (!scan) return null;
+    return {
+      direction: scan.direction ?? null,
+      gap: scan.gap ? {
+        dx: scan.gap.dx,
+        width: scan.gap.width,
+        drop: scan.gap.drop
+      } : null,
+      wall: scan.wall ? {
+        dx: scan.wall.dx,
+        height: scan.wall.height
+      } : null,
+      hazard: scan.hazard ? {
+        dx: scan.hazard.dx,
+        type: scan.hazard.type
+      } : null
+    };
+  },
+
+  _getSkillName(skillType) {
+    for (const [name, value] of Object.entries(SkillTypes)) {
+      if (value === skillType) return name.toLowerCase();
+    }
+    return null;
+  },
+
+  _recordAssistDecision(entry = {}) {
+    const timer = this.game?.getGameTimer?.();
+    const fallbackTick = timer?.getGameTicks?.() ?? timer?.tickIndex ?? 0;
+    const tick = Number.isFinite(entry.tick) ? entry.tick : fallbackTick;
+    const lemming = entry.lemming || null;
+    const type = entry.type || (entry.skillType != null ? 'skill' : 'noop');
+    const reason = entry.reason || type;
+    if (type === 'noop') {
+      const bucketX = Number.isFinite(lemming?.x) ? Math.floor(lemming.x / 32) : null;
+      const key = `${lemming?.id ?? 'none'}:${bucketX}:${reason}`;
+      if (
+        this._lastNoopAssist &&
+        this._lastNoopAssist.key === key &&
+        tick - this._lastNoopAssist.tick < this.aiNoopDebugIntervalTicks
+      ) {
+        return;
+      }
+      this._lastNoopAssist = { key, tick };
+    }
+    const skillType = entry.skillType ?? entry.skill ?? null;
+    this._recentAssists.push({
+      tick,
+      type,
+      reason,
+      action: entry.action || entry.key || null,
+      skillType,
+      skillName: entry.skillName || this._getSkillName(skillType),
+      spent: entry.spent === true,
+      success: entry.success !== false,
+      targetX: Number.isFinite(entry.targetX) ? entry.targetX : null,
+      certificateId: entry.certificateId ?? null,
+      challengeType: entry.challengeType ?? null,
+      certificateDecision: entry.certificateDecision ?? null,
+      certificateResultType: entry.certificateResultType ?? null,
+      lemming: lemming ? {
+        id: lemming.id ?? null,
+        x: Number.isFinite(lemming.x) ? lemming.x : null,
+        y: Number.isFinite(lemming.y) ? lemming.y : null,
+        lookRight: !!lemming.lookRight,
+        action: this._getLemmingActionName(lemming) || null
+      } : null,
+      scan: this._summarizeScan(entry.scan)
+    });
+    this._trimRecentList(this._recentAssists, 32);
+  },
+
+  _initDebugOverlay() {
+    if (!this.window?.document || this._aiDebug) return;
+    const doc = this.window.document;
+    const panel = doc.createElement('div');
+    panel.className = 'procgen-debug';
+    panel.textContent = 'AI: ready';
+    doc.body.appendChild(panel);
+    this._aiDebug = panel;
+  },
+
+  _destroyDebugOverlay() {
+    if (!this._aiDebug) return;
+    this._aiDebug.remove();
+    this._aiDebug = null;
+  },
+
+  _updateDebugOverlay() {
+    if (!this._aiDebug) return;
+    const decision = this._aiLastDecision;
+    if (!decision) return;
+    const action = decision.action || 'none';
+    const scan = decision.scan || {};
+    const gap = scan.gap ? `gap dx=${scan.gap.dx} w=${scan.gap.width} drop=${scan.gap.drop}` : 'gap none';
+    const wall = scan.wall ? `wall dx=${scan.wall.dx} h=${scan.wall.height}` : 'wall none';
+    const hazard = scan.hazard ? `hazard dx=${scan.hazard.dx} type=${scan.hazard.type}` : 'hazard none';
+    const budget = this._aiBudget
+      ? Object.entries(this._aiBudget)
+        .map(([key, value]) => `${key}:${value.toFixed(1)}`)
+        .join(' ')
+      : '';
+    this._aiDebug.textContent = `AI ${action} | ${gap} | ${wall} | ${hazard} | ${budget}`;
+  }
+};
+export { procgenLifecycleMethods };
diff --git a/js/app/procgen/ProcgenTerrainDirector.js b/js/app/procgen/ProcgenTerrainDirector.js
new file mode 100644
index 00000000..e7cb0e83
--- /dev/null
+++ b/js/app/procgen/ProcgenTerrainDirector.js
@@ -0,0 +1,851 @@
+import {
+  SkillTypes
+} from './ProcgenControllerShared.js';
+import {
+  PROCGEN_CHALLENGE_TYPES,
+  PROCGEN_FALLBACK_DECISIONS,
+  createProcgenChallengeCertificate,
+  decideProcgenFallback,
+  verifyProcgenChallengeCertificateSync
+} from '../../solver/ProcgenCertificates.js';
+const procgenTerrainDirectorMethods = {
+  getGroundExtentX() {
+    return Math.max(1, Math.floor(this._groundEndX || 0));
+  },
+
+  _getRightmostX() {
+    const frontier = this._getFrontierSummary?.();
+    if (Number.isFinite(frontier?.x)) return frontier.x;
+    if (Number.isFinite(frontier?.rightmostX)) return frontier.rightmostX;
+    const entrance = this.level?.entrances?.[0] || null;
+    return Number.isFinite(entrance?.x) ? entrance.x : null;
+  },
+
+  _scheduleBuilderBurst(originX) {
+    const timer = this.game?.getGameTimer?.();
+    const tick = timer?.getGameTicks?.() ?? timer?.tickIndex ?? 0;
+    this._builderBurst = {
+      remaining: this._randInt(1, 5),
+      nextDelay: this._randInt(10, 20),
+      dueTick: 0,
+      originX: Number.isFinite(originX) ? originX : null,
+      edgeX: Number.isFinite(originX) ? originX : null,
+      edgeAction: null,
+      used: new Set()
+    };
+    this._builderBurst.dueTick = tick + this._builderBurst.nextDelay;
+  },
+
+  _scheduleEdgeResponse(edgeX, edgeAction) {
+    const timer = this.game?.getGameTimer?.();
+    const tick = timer?.getGameTicks?.() ?? timer?.tickIndex ?? 0;
+    this._builderBurst = {
+      remaining: 1,
+      nextDelay: this._randInt(6, 14),
+      dueTick: tick + this._randInt(6, 14),
+      originX: Number.isFinite(edgeX) ? edgeX : null,
+      edgeX: Number.isFinite(edgeX) ? edgeX : null,
+      edgeAction: edgeAction || 'blocker',
+      used: new Set()
+    };
+  },
+
+  _processBuilderBurst() {
+    const burst = this._builderBurst;
+    if (!burst || burst.remaining <= 0) return;
+    const timer = this.game?.getGameTimer?.();
+    const tick = timer?.getGameTicks?.() ?? timer?.tickIndex ?? 0;
+    if (burst.dueTick > tick) return;
+    if (burst.edgeAction) {
+      const handled = this._applyEdgeResponse(burst, tick);
+      burst.remaining -= handled ? 1 : 0;
+      if (burst.remaining <= 0) {
+        this._builderBurst = null;
+      } else {
+        burst.dueTick = tick + burst.nextDelay;
+      }
+      return;
+    }
+    const applied = this._applyBuilderToNextLemming(burst);
+    if (applied) {
+      burst.remaining -= 1;
+      if (burst.remaining <= 0) {
+        this._builderBurst = null;
+        return;
+      }
+      burst.nextDelay = Math.round(burst.nextDelay * 2) + this._randInt(1, 5);
+    }
+    burst.dueTick = tick + burst.nextDelay;
+  },
+
+  _applyEdgeResponse(burst, tick) {
+    const manager = this.game?.getLemmingManager?.();
+    const lems = manager?.lemmings || [];
+    if (!lems.length || !Number.isFinite(burst.edgeX)) return false;
+    const edgeX = burst.edgeX + (burst.edgeAction === 'blocker' ? 2 : 0);
+    let best = null;
+    let bestDist = Infinity;
+    for (const lem of lems) {
+      if (!lem || lem.removed || lem.disabled) continue;
+      if (!this._isAssignableAction(lem)) continue;
+      if (burst.edgeAction === 'builder-left' && lem.lookRight) continue;
+      if (burst.edgeAction === 'blocker' && lem.lookRight) continue;
+      const dist = Math.abs((lem.x ?? 0) - edgeX);
+      if (dist < bestDist) {
+        bestDist = dist;
+        best = lem;
+      }
+    }
+    if (!best) return false;
+    const skill = burst.edgeAction === 'builder-left' ? SkillTypes.BUILDER : SkillTypes.BLOCKER;
+    const key = burst.edgeAction === 'builder-left' ? 'builder' : 'blocker';
+    if (!this._canSpend(key)) return false;
+    if (manager.doLemmingAction(best, skill)) {
+      this._noteAiAction(best, tick, burst.edgeAction === 'builder-left' ? 48 : 32, {
+        action: key,
+        reason: burst.edgeAction,
+        skillType: skill,
+        spent: true,
+        targetX: burst.edgeX
+      });
+      return true;
+    }
+    this._refundBudget(key);
+    return false;
+  },
+
+  _processGapBridges() {
+    if (!this._gaps.length) return;
+    const manager = this.game?.getLemmingManager?.();
+    const lems = manager?.lemmings || [];
+    let leadX = null;
+    if (lems.length) {
+      const frontier = this._getFrontierLemming();
+      leadX = Number.isFinite(frontier?.x) ? frontier.x : null;
+      this._advanceGapScanCursor(leadX);
+      const maxTriggerX = Number.isFinite(leadX) ? leadX + this.gapTriggerDistance : Infinity;
+      for (let i = this._gapScanStart; i < this._gaps.length; i += 1) {
+        const gap = this._gaps[i];
+        if (!gap || gap.assigned) continue;
+        if (!Number.isFinite(gap.x) || !Number.isFinite(gap.width)) continue;
+        if (gap.x > maxTriggerX) break;
+        const triggerX = gap.x - this.gapTriggerDistance;
+        if (Number.isFinite(leadX) && leadX < triggerX) continue;
+        let best = null;
+        let bestDist = Infinity;
+        for (const lem of lems) {
+          if (!lem || lem.removed || lem.disabled || !lem.lookRight) continue;
+          if (!this._isAssignableAction(lem)) continue;
+          const dist = Math.abs((lem.x ?? 0) - gap.x);
+          if (dist < bestDist) {
+            bestDist = dist;
+            best = lem;
+          }
+        }
+        if (!best) continue;
+        if (Number.isFinite(leadX) && best.x < leadX - 8) continue;
+        if (manager.doLemmingAction(best, SkillTypes.BUILDER)) {
+          const timer = this.game?.getGameTimer?.();
+          const tick = timer?.getGameTicks?.() ?? timer?.tickIndex ?? 0;
+          this._noteAiAction(best, tick, 48, {
+            action: 'builder',
+            reason: 'small-gap',
+            skillType: SkillTypes.BUILDER,
+            spent: true,
+            targetX: gap.x
+          });
+          gap.assigned = true;
+        }
+      }
+    }
+    this._pruneGapQueue(leadX);
+  },
+
+  _processMidairBuilder() {
+    const pending = this._pendingMidairBuilder;
+    if (!pending) return;
+    const manager = this.game?.getLemmingManager?.();
+    const lems = manager?.lemmings || [];
+    if (!lems.length) return;
+    const timer = this.game?.getGameTimer?.();
+    const tick = timer?.getGameTicks?.() ?? timer?.tickIndex ?? 0;
+    const ground = this.level?.groundMask;
+    const levelHeight = this.level?.height ?? 0;
+    const maxDrop = Math.min(this.maxDrop, levelHeight);
+    let target = null;
+
+    if (Number.isFinite(pending.targetId)) {
+      target = manager?.getLemming?.(pending.targetId) || null;
+      const actionName = target?.action?.getActionName?.() || '';
+      if (!target || target.removed || target.disabled || actionName !== 'falling') {
+        pending.targetId = null;
+        pending.dueTick = null;
+        target = null;
+      }
+    }
+
+    if (!target) {
+      for (const lem of lems) {
+        if (!lem || lem.removed || lem.disabled) continue;
+        const actionName = lem.action?.getActionName?.() || '';
+        if (actionName !== 'falling') continue;
+        pending.targetId = lem.id;
+        pending.dueTick = tick + pending.delay;
+        target = lem;
+        break;
+      }
+    }
+
+    if (!target || !Number.isFinite(pending.dueTick)) return;
+    if (tick < pending.dueTick) return;
+    if (!this._canSpend('builder')) return;
+
+    const drop = ground && Number.isFinite(target.x) && Number.isFinite(target.y)
+      ? this._getDropAt(ground, Math.floor(target.x), Math.floor(target.y), maxDrop)
+      : null;
+    if (drop != null && drop <= 1) {
+      this._refundBudget('builder');
+      return;
+    }
+
+    if (manager.doLemmingAction(target, SkillTypes.BUILDER)) {
+      this._noteAiAction(target, tick, 48, {
+        action: 'builder',
+        reason: 'midair-safe-drop',
+        skillType: SkillTypes.BUILDER,
+        spent: true
+      });
+      this._pendingMidairBuilder = null;
+      return;
+    }
+    this._refundBudget('builder');
+  },
+
+  _applyBuilderToNextLemming(burst) {
+    const manager = this.game?.getLemmingManager?.();
+    const lems = manager?.lemmings || [];
+    if (!lems.length) return false;
+    if (Number.isFinite(burst?.edgeX)) {
+      let best = null;
+      let bestDist = Infinity;
+      for (const lem of lems) {
+        if (!lem || lem.removed || lem.disabled || !lem.lookRight) continue;
+        if (!this._isAssignableAction(lem)) continue;
+        if (burst.used?.has?.(lem.id)) continue;
+        if (lem.x > burst.edgeX + 8) continue;
+        const dist = Math.abs((lem.x ?? 0) - burst.edgeX);
+        if (dist < bestDist) {
+          bestDist = dist;
+          best = lem;
+        }
+      }
+      if (best && manager.doLemmingAction(best, SkillTypes.BUILDER)) {
+        const tick = this.game?.getGameTimer?.().tickIndex ?? 0;
+        this._noteAiAction(best, tick, 48, {
+          action: 'builder',
+          reason: 'edge-burst',
+          skillType: SkillTypes.BUILDER,
+          spent: true,
+          targetX: burst.edgeX
+        });
+        burst.used?.add?.(best.id);
+        return true;
+      }
+    }
+    if (Number.isFinite(burst?.originX)) {
+      let best = null;
+      let bestDist = Infinity;
+      for (const lem of lems) {
+        if (!lem || lem.removed || lem.disabled || !lem.lookRight) continue;
+        if (!this._isAssignableAction(lem)) continue;
+        if (burst.used?.has?.(lem.id)) continue;
+        const dist = Math.abs((lem.x ?? 0) - burst.originX);
+        if (dist < bestDist) {
+          bestDist = dist;
+          best = lem;
+        }
+      }
+      if (best && manager.doLemmingAction(best, SkillTypes.BUILDER)) {
+        const tick = this.game?.getGameTimer?.().tickIndex ?? 0;
+        this._noteAiAction(best, tick, 48, {
+          action: 'builder',
+          reason: 'fall-recovery',
+          skillType: SkillTypes.BUILDER,
+          spent: true,
+          targetX: burst.originX
+        });
+        burst.used?.add?.(best.id);
+        return true;
+      }
+      return false;
+    }
+    const start = Math.max(0, this._builderCursorId);
+    for (let i = 0; i < lems.length; i++) {
+      const idx = (start + i) % lems.length;
+      const lem = lems[idx];
+      if (!lem || lem.removed || lem.disabled) continue;
+      if (!this._isAssignableAction(lem)) continue;
+      this._builderCursorId = idx + 1;
+      if (manager.doLemmingAction(lem, SkillTypes.BUILDER)) {
+        const tick = this.game?.getGameTimer?.().tickIndex ?? 0;
+        this._noteAiAction(lem, tick, 48, {
+          action: 'builder',
+          reason: 'builder-burst',
+          skillType: SkillTypes.BUILDER,
+          spent: true
+        });
+        return true;
+      }
+    }
+    return false;
+  },
+
+  _fillProcgenChallengeGround(mask, width, height, x0, x1, y0, groundHeight) {
+    const startX = Math.max(0, Math.floor(x0));
+    const endX = Math.min(width, Math.ceil(x1));
+    const startY = Math.max(0, Math.floor(y0));
+    const endY = Math.min(height, Math.ceil(y0 + groundHeight));
+    for (let y = startY; y < endY; y += 1) {
+      const row = y * width;
+      for (let x = startX; x < endX; x += 1) {
+        mask[row + x] = 1;
+      }
+    }
+  },
+
+  _createGapChallengeFixture(gapStart, gapWidth) {
+    const width = Math.max(72, Math.floor(gapWidth) + 64);
+    const height = 48;
+    const footY = 24;
+    const supportY = footY + 1;
+    const leftEnd = 24;
+    const rightStart = leftEnd + Math.max(0, Math.floor(gapWidth));
+    const groundMask = new Uint8Array(width * height);
+    this._fillProcgenChallengeGround(groundMask, width, height, 0, leftEnd, supportY, this.groundHeight);
+    this._fillProcgenChallengeGround(groundMask, width, height, rightStart, width, supportY, this.groundHeight);
+    return {
+      kind: 'procgen-local-challenge',
+      id: `procgen-gap-${Math.floor(gapStart)}-${Math.floor(gapWidth)}`,
+      width,
+      height,
+      groundMask,
+      steelMask: new Uint8Array(width * height),
+      entrances: [{ x: 8, y: footY }],
+      exits: [{ x: Math.min(width - 8, rightStart + 24), y: footY }],
+      lemmings: [{ id: 0, x: 8, y: footY, lookRight: true, action: 'walking' }],
+      skills: { builder: 1 },
+      challenge: {
+        type: 'builder-gap',
+        sourceStartX: Math.floor(gapStart),
+        sourceWidth: Math.floor(gapWidth)
+      }
+    };
+  },
+
+  _createGapChallengeCertificate(gapStart, gapWidth) {
+    const localGapStart = 24;
+    const localGapEnd = localGapStart + Math.max(0, Math.floor(gapWidth));
+    return createProcgenChallengeCertificate({
+      id: `procgen-gap-${this._recentCertificateSerial + 1}-${Math.floor(gapStart)}`,
+      challengeType: PROCGEN_CHALLENGE_TYPES.BRIDGE_GAP,
+      expectedSkill: 'builder',
+      assignmentWindow: { start: 20, end: 80 },
+      expectedLandingSegment: {
+        x0: localGapEnd,
+        y0: 24,
+        x1: localGapEnd + 16,
+        y1: 24
+      },
+      expectedExitSegment: {
+        x0: localGapEnd + 16,
+        y0: 24,
+        x1: localGapEnd + 32,
+        y1: 24
+      },
+      minimalSkillCount: 1
+    });
+  },
+
+  _getAssistChallengeType(option) {
+    if (!option) return null;
+    if (option.key === 'builder' && option.reason === 'small-gap') {
+      return PROCGEN_CHALLENGE_TYPES.BRIDGE_GAP;
+    }
+    if (option.key === 'floater' && option.reason === 'unsafe-drop') {
+      return PROCGEN_CHALLENGE_TYPES.FALL_SURVIVAL;
+    }
+    if (option.key === 'bash') return PROCGEN_CHALLENGE_TYPES.BASH_BARRIER;
+    if (option.key === 'dig') return PROCGEN_CHALLENGE_TYPES.DIG_BARRIER;
+    if (option.key === 'mine') return PROCGEN_CHALLENGE_TYPES.MINE_SLOPE;
+    return null;
+  },
+
+  _getAssistChallengeSkillName(option) {
+    if (!option) return null;
+    if (option.key === 'bash') return 'basher';
+    if (option.key === 'dig') return 'digger';
+    if (option.key === 'mine') return 'miner';
+    if (option.key === 'builder') return 'builder';
+    if (option.key === 'floater') return 'floater';
+    return option.key || null;
+  },
+
+  _createAssistChallengeCertificate(option, lemming, scan, tick) {
+    const challengeType = this._getAssistChallengeType(option);
+    if (!challengeType) return null;
+    const localTargetX = challengeType === PROCGEN_CHALLENGE_TYPES.BRIDGE_GAP
+      ? 48
+      : 62;
+    return createProcgenChallengeCertificate({
+      id: `procgen-assist-${this._recentCertificateSerial + 1}-${challengeType}`,
+      challengeType,
+      expectedSkill: this._getAssistChallengeSkillName(option),
+      assignmentWindow: {
+        start: Math.max(0, Math.floor((tick ?? 0) - 8)),
+        end: Math.max(0, Math.floor((tick ?? 0) + 16))
+      },
+      expectedLandingSegment: {
+        x0: localTargetX,
+        y0: 57,
+        x1: localTargetX + 18,
+        y1: 57
+      },
+      expectedExitSegment: {
+        x0: 104,
+        y0: 57,
+        x1: 120,
+        y1: 57
+      },
+      minimalSkillCount: 1,
+      source: {
+        reason: option.reason,
+        lemmingId: lemming?.id ?? null,
+        scan
+      }
+    });
+  },
+
+  _createBarrierChallengeFixture(option, scan) {
+    const width = 140;
+    const height = 72;
+    const footY = 57;
+    const supportY = footY + 1;
+    const barrierHeight = Math.max(4, Math.min(24, Math.floor(scan?.wall?.height ?? 10)));
+    const groundMask = new Uint8Array(width * height);
+    const steelMask = new Uint8Array(width * height);
+    this._fillProcgenChallengeGround(groundMask, width, height, 0, width, supportY, this.groundHeight);
+    this._fillProcgenChallengeGround(
+      groundMask,
+      width,
+      height,
+      62,
+      70,
+      footY - barrierHeight + 1,
+      barrierHeight
+    );
+    const skillName = this._getAssistChallengeSkillName(option);
+    return {
+      kind: 'procgen-local-challenge',
+      id: `procgen-${option?.key || 'barrier'}-barrier`,
+      width,
+      height,
+      groundMask,
+      steelMask,
+      entrances: [{ x: 12, y: footY }],
+      exits: [{ x: 120, y: footY }],
+      lemmings: [{ id: 0, x: 20, y: footY, lookRight: true, action: 'walking' }],
+      skills: skillName ? { [skillName]: 1 } : {},
+      challenge: {
+        type: option?.key === 'dig'
+          ? 'dig-barrier'
+          : option?.key === 'mine'
+            ? 'mine-barrier'
+            : 'bash-barrier',
+        sourceHeight: barrierHeight
+      }
+    };
+  },
+
+  _createFallChallengeFixture(scan, tick) {
+    const width = 120;
+    const height = 140;
+    const footY = 23;
+    const supportY = footY + 1;
+    const safeFall = Math.max(1, Math.floor(this.maxDrop || 60));
+    const fallDistance = Math.max(
+      safeFall + 8,
+      Math.floor(scan?.gap?.drop ?? this.aiFloaterDrop ?? safeFall) + 8,
+      72
+    );
+    const landingFootY = Math.min(height - this.groundHeight - 2, footY + fallDistance);
+    const groundMask = new Uint8Array(width * height);
+    this._fillProcgenChallengeGround(groundMask, width, height, 0, 32, supportY, this.groundHeight);
+    this._fillProcgenChallengeGround(
+      groundMask,
+      width,
+      height,
+      48,
+      width,
+      landingFootY + 1,
+      this.groundHeight
+    );
+    return {
+      kind: 'procgen-local-challenge',
+      id: 'procgen-floater-fall',
+      width,
+      height,
+      groundMask,
+      steelMask: new Uint8Array(width * height),
+      entrances: [{ x: 10, y: footY }],
+      exits: [{ x: 104, y: landingFootY }],
+      lemmings: [{ id: 0, x: 12, y: footY, lookRight: true, action: 'walking' }],
+      skills: { floater: 1 },
+      challenge: {
+        type: 'floater-fall'
+      },
+      fall: {
+        x: 34,
+        fromY: footY,
+        toY: landingFootY,
+        safeFallDistance: safeFall,
+        assignmentTick: Math.max(0, Math.floor(tick ?? 0))
+      }
+    };
+  },
+
+  _createAssistChallengeFixture(option, lemming, scan, tick) {
+    const challengeType = this._getAssistChallengeType(option);
+    if (!challengeType) return null;
+    if (challengeType === PROCGEN_CHALLENGE_TYPES.BRIDGE_GAP) {
+      return this._createGapChallengeFixture(
+        Number.isFinite(option?.targetX) ? option.targetX : lemming?.x ?? 0,
+        scan?.gap?.width ?? 4,
+        lemming?.y
+      );
+    }
+    if (challengeType === PROCGEN_CHALLENGE_TYPES.FALL_SURVIVAL) {
+      return this._createFallChallengeFixture(scan, tick);
+    }
+    return this._createBarrierChallengeFixture(option, scan);
+  },
+
+  _normalizeVerifierOutput(output, certificate) {
+    if (output?.verificationResult) return output;
+    return createProcgenChallengeCertificate({
+      ...certificate,
+      verificationResult: output
+    });
+  },
+
+  _verifyGeneratedGap(gapStart, gapWidth, surfaceY) {
+    const certificate = this._createGapChallengeCertificate(gapStart, gapWidth);
+    const chunk = this._createGapChallengeFixture(gapStart, gapWidth, surfaceY);
+    let verified = null;
+    let fallback = {
+      decision: PROCGEN_FALLBACK_DECISIONS.ACCEPT,
+      resultType: 'skipped',
+      reasonCodes: [],
+      summary: 'Procgen certificate verification is disabled'
+    };
+    if (this.procgenCertificateVerification) {
+      const options = {
+        ...this.procgenCertificateOptions,
+        controller: this
+      };
+      const raw = this.procgenCertificateVerifier
+        ? this.procgenCertificateVerifier(certificate, chunk, options)
+        : verifyProcgenChallengeCertificateSync(certificate, chunk, options);
+      verified = this._normalizeVerifierOutput(raw, certificate);
+      fallback = decideProcgenFallback(verified.verificationResult);
+    } else {
+      verified = certificate;
+    }
+    this._trackProcgenCertificate(verified, fallback, {
+      startX: gapStart,
+      endX: gapStart + gapWidth,
+      width: gapWidth,
+      surfaceY
+    });
+    return {
+      certificate: verified,
+      fallback,
+      accepted: fallback.decision === PROCGEN_FALLBACK_DECISIONS.ACCEPT
+    };
+  },
+
+  _verifyAssistChallenge(option, lemming, scan, tick) {
+    const certificate = this._createAssistChallengeCertificate(option, lemming, scan, tick);
+    const chunk = certificate
+      ? this._createAssistChallengeFixture(option, lemming, scan, tick)
+      : null;
+    if (!certificate || !chunk) return null;
+    let verified = null;
+    let fallback = {
+      decision: PROCGEN_FALLBACK_DECISIONS.ACCEPT,
+      resultType: 'skipped',
+      reasonCodes: [],
+      summary: 'Procgen certificate verification is disabled'
+    };
+    if (this.procgenCertificateVerification) {
+      const options = {
+        ...this.procgenCertificateOptions,
+        controller: this
+      };
+      const raw = this.procgenCertificateVerifier
+        ? this.procgenCertificateVerifier(certificate, chunk, options)
+        : verifyProcgenChallengeCertificateSync(certificate, chunk, options);
+      verified = this._normalizeVerifierOutput(raw, certificate);
+      fallback = decideProcgenFallback(verified.verificationResult);
+    } else {
+      verified = certificate;
+    }
+    this._trackProcgenCertificate(verified, fallback, {
+      source: 'assist',
+      reason: option?.reason || null,
+      lemmingId: lemming?.id ?? null,
+      startX: option?.targetX ?? lemming?.x,
+      endX: option?.targetX,
+      width: scan?.gap?.width ?? scan?.wall?.height ?? null,
+      surfaceY: lemming?.y
+    });
+    return {
+      certificate: verified,
+      fallback,
+      accepted: fallback.decision === PROCGEN_FALLBACK_DECISIONS.ACCEPT
+    };
+  },
+
+  _trackProcgenCertificate(verified, fallback, meta = {}) {
+    this._recentCertificateSerial += 1;
+    this._recentCertificates.push({
+      serial: this._recentCertificateSerial,
+      source: meta.source || 'terrain',
+      reason: meta.reason || null,
+      lemmingId: meta.lemmingId ?? null,
+      id: verified?.id ?? null,
+      challengeType: verified?.challengeType ?? PROCGEN_CHALLENGE_TYPES.UNKNOWN,
+      expectedSkill: verified?.expectedSkill ?? null,
+      resultType: fallback?.resultType ?? verified?.verificationResult?.resultType ?? null,
+      decision: fallback?.decision ?? PROCGEN_FALLBACK_DECISIONS.ACCEPT,
+      reasonCodes: Array.isArray(fallback?.reasonCodes) ? fallback.reasonCodes.slice() : [],
+      summary: fallback?.summary ?? verified?.verificationResult?.summary ?? null,
+      startX: Number.isFinite(meta.startX) ? Math.floor(meta.startX) : null,
+      endX: Number.isFinite(meta.endX) ? Math.floor(meta.endX) : null,
+      width: Number.isFinite(meta.width) ? Math.floor(meta.width) : null,
+      surfaceY: Number.isFinite(meta.surfaceY) ? Math.floor(meta.surfaceY) : null
+    });
+    const limit = Math.max(1, Math.floor(this.recentCertificateLimit ?? 32));
+    if (this._recentCertificates.length > limit) {
+      this._recentCertificates.splice(0, this._recentCertificates.length - limit);
+    }
+  },
+
+  _fallbackTerrainWidth(segmentWidth, gapWidth, fallback) {
+    if (fallback?.decision === PROCGEN_FALLBACK_DECISIONS.EXTEND) {
+      return Math.max(segmentWidth, gapWidth + this._pickSegmentWidth());
+    }
+    return Math.max(segmentWidth, gapWidth);
+  },
+
+  _ensureGround(rightmostX) {
+    const levelWidth = this.level?.width ?? 0;
+    if (!Number.isFinite(levelWidth) || levelWidth <= 0) return;
+    const frontierX = Number.isFinite(rightmostX) ? rightmostX : this._getRightmostX();
+    if (!Number.isFinite(frontierX)) return;
+    while (this._needsGroundForFrontier(frontierX)) {
+      if (this._groundEndX >= levelWidth) break;
+      const segmentWidth = this._pickSegmentWidth();
+      if (this._shouldInsertGap()) {
+        const gapWidth = this._pickGapWidth();
+        const gapStart = this._groundEndX;
+        const verification = this._verifyGeneratedGap(gapStart, gapWidth, this._groundTopY);
+        if (!verification.accepted) {
+          const fallback = verification.fallback;
+          if (fallback.decision === PROCGEN_FALLBACK_DECISIONS.SIMPLIFY) {
+            const simplifiedWidth = Math.max(2, Math.min(gapWidth, 8));
+            if (simplifiedWidth < gapWidth) {
+              this._gaps.push({
+                x: gapStart,
+                width: simplifiedWidth,
+                y: this._groundTopY,
+                assigned: false,
+                certificateDecision: fallback.decision,
+                certificateResultType: fallback.resultType
+              });
+              const simplifiedEnd = Math.min(levelWidth, this._groundEndX + simplifiedWidth);
+              this._trackGeneratedChunk({
+                type: 'gap',
+                startX: gapStart,
+                endX: simplifiedEnd,
+                y: this._groundTopY,
+                certificateDecision: fallback.decision,
+                certificateResultType: fallback.resultType
+              });
+              this._groundEndX = simplifiedEnd;
+              this._refreshLookaheadTarget();
+              this._gapCooldown = this._randInt(16, 40);
+              continue;
+            }
+          }
+          const fallbackWidth = this._fallbackTerrainWidth(segmentWidth, gapWidth, fallback);
+          const nextTop = this._pickNextTopY();
+          const colorIndex = this._getNextColorIndex();
+          const fallbackStart = this._groundEndX;
+          this._paintGround(fallbackStart, fallbackWidth, nextTop, colorIndex);
+          this._groundTopY = nextTop;
+          this._groundEndX = Math.min(levelWidth, this._groundEndX + fallbackWidth);
+          this._trackGeneratedChunk({
+            type: 'solver-fallback',
+            originalType: 'gap',
+            startX: fallbackStart,
+            endX: this._groundEndX,
+            topY: nextTop,
+            colorIndex,
+            certificateDecision: fallback.decision,
+            certificateResultType: fallback.resultType
+          });
+          this._refreshLookaheadTarget();
+          this._gapCooldown = this._randInt(12, 28);
+          continue;
+        }
+        this._gaps.push({
+          x: gapStart,
+          width: gapWidth,
+          y: this._groundTopY,
+          assigned: false,
+          certificateDecision: verification.fallback.decision,
+          certificateResultType: verification.fallback.resultType
+        });
+        const gapEnd = Math.min(levelWidth, this._groundEndX + gapWidth);
+        this._trackGeneratedChunk({
+          type: 'gap',
+          startX: gapStart,
+          endX: gapEnd,
+          y: this._groundTopY,
+          certificateDecision: verification.fallback.decision,
+          certificateResultType: verification.fallback.resultType
+        });
+        this._groundEndX = gapEnd;
+        this._refreshLookaheadTarget();
+        this._gapCooldown = this._randInt(16, 40);
+        continue;
+      }
+      const nextTop = this._pickNextTopY();
+      const colorIndex = this._getNextColorIndex();
+      const segmentStart = this._groundEndX;
+      this._paintGround(segmentStart, segmentWidth, nextTop, colorIndex);
+      this._groundTopY = nextTop;
+      this._groundEndX = Math.min(levelWidth, this._groundEndX + segmentWidth);
+      this._trackGeneratedChunk({
+        type: 'terrain',
+        startX: segmentStart,
+        endX: this._groundEndX,
+        topY: nextTop,
+        colorIndex
+      });
+      this._refreshLookaheadTarget();
+    }
+    this._pruneGeneratedTracking(frontierX);
+  },
+
+  _paintGround(startX, width, topY, colorIndex) {
+    if (this.assets && this.stamper) {
+      this._paintGroundPieces(startX, width, topY, colorIndex);
+      return;
+    }
+    this._paintGroundPixels(startX, width, topY, colorIndex);
+  },
+
+  _paintGroundPixels(startX, width, topY, colorIndex) {
+    if (!this.level) return;
+    const levelWidth = this.level.width;
+    const levelHeight = this.level.height;
+    const x0 = Math.max(0, startX);
+    const x1 = Math.min(levelWidth, startX + width);
+    const top = Number.isFinite(topY) ? topY : levelHeight - this.groundHeight;
+    const y0 = Math.max(0, Math.min(levelHeight - this.groundHeight, top));
+    const y1 = Math.min(levelHeight, y0 + this.groundHeight);
+    const paletteIndex = Number.isFinite(colorIndex)
+      ? colorIndex
+      : this.groundColorIndex;
+    if (typeof this.level.setGroundRect === 'function') {
+      this.level.setGroundRect(x0, y0, x1 - x0, y1 - y0, paletteIndex, {
+        recordHistory: false,
+        invalidateMiniMap: true
+      });
+      return;
+    }
+    for (let y = y0; y < y1; y += 1) {
+      for (let x = x0; x < x1; x += 1) {
+        this.level.setGroundAt(x, y, paletteIndex);
+      }
+    }
+  },
+
+  _paintGroundPieces(startX, width, topY, colorIndex) {
+    if (!this.level || !this.assets || !this.stamper) return;
+    const levelWidth = this.level.width;
+    const maxX = Math.min(levelWidth, startX + width);
+    const floorY = (Number.isFinite(topY) ? topY : 0) + this.groundHeight - 1;
+    let cursor = Math.max(0, startX);
+    const decorBias = Number.isFinite(colorIndex) ? (colorIndex % 4) : 0;
+    const structure = this._getStructurePlan();
+    let repeatPiece = null;
+    while (cursor < maxX) {
+      const remaining = maxX - cursor;
+      let surfaceY = this._nextSurfaceY(structure, floorY);
+      const minHeight = structure?.type === 'pillar'
+        ? Math.max(this.groundHeight * 3, 8)
+        : this.groundHeight;
+      const minWidth = structure?.type === 'shelf'
+        ? Math.max(6, this.segmentMinWidth)
+        : 1;
+      const repeatWidth = repeatPiece?.width ?? repeatPiece?.bounds?.width ?? 0;
+      const piece = repeatPiece && remaining >= repeatWidth
+        ? repeatPiece
+        : this.assets.pickGroundPiece(remaining, minHeight, minWidth);
+      if (!piece?.bounds?.width) break;
+      if (!repeatPiece || this._rand() < 0.25) {
+        repeatPiece = piece;
+      }
+      const stamped = structure?.type === 'pillar'
+        ? this._stampVerticalRun(cursor, surfaceY, piece)
+        : this._stampHorizontalRun(cursor, surfaceY, piece, maxX, decorBias);
+      cursor += stamped;
+      if (cursor >= maxX) break;
+    }
+  },
+
+  _stampHorizontalRun(cursorX, surfaceY, piece, maxX, decorBias) {
+    const pieceWidth = Math.max(1, piece.width || piece.bounds.width);
+    const repeats = Math.max(1, Math.floor((maxX - cursorX) / pieceWidth));
+    let stamped = 0;
+    for (let i = 0; i < repeats; i++) {
+      const destX = cursorX + stamped - piece.bounds.minX;
+      const destY = this._clampSurfaceForEntrance(surfaceY, piece, cursorX + stamped) - piece.bounds.maxY;
+      const rect = this.stamper.stamp(piece, destX, destY);
+      this._trackGeneratedPiece(piece, destX, destY, 'ground', rect);
+      if (this._rand() < (this.decorChance + decorBias * 0.01)) {
+        this._placeDecoration(destX, destY, piece);
+      }
+      stamped += pieceWidth;
+    }
+    return stamped || pieceWidth;
+  },
+
+  _stampVerticalRun(cursorX, surfaceY, piece) {
+    const pieceWidth = Math.max(1, piece.width || piece.bounds.width);
+    const pieceHeight = Math.max(1, piece.height || piece.bounds.height);
+    const repeats = Math.max(2, Math.ceil(this.groundHeight / pieceHeight));
+    let topY = surfaceY;
+    for (let i = 0; i < repeats; i++) {
+      const destX = cursorX - piece.bounds.minX;
+      const destY = topY - piece.bounds.maxY;
+      const rect = this.stamper.stamp(piece, destX, destY);
+      this._trackGeneratedPiece(piece, destX, destY, 'support', rect);
+      topY -= pieceHeight;
+    }
+    return pieceWidth;
+  }
+};
+export { procgenTerrainDirectorMethods };
diff --git a/js/app/procgen/ProcgenTerrainPlanning.js b/js/app/procgen/ProcgenTerrainPlanning.js
new file mode 100644
index 00000000..7baa5d67
--- /dev/null
+++ b/js/app/procgen/ProcgenTerrainPlanning.js
@@ -0,0 +1,790 @@
+import {
+  HAZARD_TRIGGER_TYPES,
+  Lemming
+} from './ProcgenControllerShared.js';
+
+const DEAD_FRONTIER_ACTIONS = new Set([
+  'drowning',
+  'exiting',
+  'exploding',
+  'frying',
+  'oh-no',
+  'splatter'
+]);
+const STATIONARY_FRONTIER_ACTIONS = new Set(['blocking', 'countdown']);
+const AIRBORNE_FRONTIER_ACTIONS = new Set(['falling', 'floating', 'jump']);
+const ASSIGNABLE_ACTIONS = new Set(['', 'walk', 'walking']);
+
+const procgenTerrainPlanningMethods = {
+  _getProcgenTick() {
+    const timer = this.game?.getGameTimer?.();
+    return timer?.getGameTicks?.() ?? timer?.tickIndex ?? 0;
+  },
+
+  _getProcgenLemmings() {
+    const manager = this.game?.getLemmingManager?.();
+    if (Array.isArray(manager?.activeLemmings)) return manager.activeLemmings;
+    if (Array.isArray(manager?.lemmings)) return manager.lemmings;
+    return [];
+  },
+
+  _getLemmingActionName(lem) {
+    return lem?.action?.getActionName?.() || '';
+  },
+
+  _isAssignableAction(lem) {
+    return ASSIGNABLE_ACTIONS.has(this._getLemmingActionName(lem));
+  },
+
+  _isLiveFrontierLemming(lem) {
+    if (!lem || lem.removed || lem.disabled) return false;
+    if (lem.isRemoved?.() === true || lem.isDisabled?.() === true) return false;
+    return Number.isFinite(lem.x) && Number.isFinite(lem.y);
+  },
+
+  _trackFrontierLemming(lem, tick) {
+    if (!Number.isFinite(lem?.id)) return null;
+    if (!this._frontierLemmingState) this._frontierLemmingState = new Map();
+    const previous = this._frontierLemmingState.get(lem.id) || null;
+    const previousTick = Number.isFinite(previous?.lastSeenTick) ? previous.lastSeenTick : tick - 1;
+    const sameTick = previous && previousTick === tick;
+    const tickDelta = sameTick ? 0 : Math.max(1, tick - previousTick);
+    const velocityDivisor = Math.max(1, tick - previousTick);
+    const previousX = Number.isFinite(previous?.x) ? previous.x : lem.x;
+    const previousY = Number.isFinite(previous?.y) ? previous.y : lem.y;
+    const dx = lem.x - previousX;
+    const dy = lem.y - previousY;
+    const moved = Math.abs(dx) + Math.abs(dy);
+    const bestX = Math.max(Number.isFinite(previous?.bestX) ? previous.bestX : lem.x, lem.x);
+    const madeRightwardProgress = !previous || lem.x > bestX - 0.5;
+    let stallTicks = Number.isFinite(previous?.stallTicks) ? previous.stallTicks : 0;
+    if (sameTick) {
+      stallTicks = Number.isFinite(previous?.stallTicks) ? previous.stallTicks : 0;
+    } else if (moved < 0.5) {
+      stallTicks += tickDelta;
+    } else {
+      stallTicks = Math.max(0, stallTicks - tickDelta);
+    }
+    let flipCount = Number.isFinite(previous?.flipCount) ? previous.flipCount : 0;
+    if (previous && previous.lookRight !== lem.lookRight && Math.abs(dx) < 8) {
+      flipCount += 1;
+    } else if (!sameTick && moved > 2) {
+      flipCount = Math.max(0, flipCount - 1);
+    }
+    const state = {
+      id: lem.id,
+      x: lem.x,
+      y: lem.y,
+      lookRight: !!lem.lookRight,
+      actionName: this._getLemmingActionName(lem),
+      lastSeenTick: tick,
+      lastProgressTick: madeRightwardProgress
+        ? tick
+        : (Number.isFinite(previous?.lastProgressTick) ? previous.lastProgressTick : tick),
+      bestX,
+      stallTicks,
+      flipCount,
+      velocityX: dx / velocityDivisor,
+      velocityY: dy / velocityDivisor
+    };
+    this._frontierLemmingState.set(lem.id, state);
+    return state;
+  },
+
+  _evaluateFrontierViability(lem, tracker) {
+    if (!this._isLiveFrontierLemming(lem)) {
+      return { viable: false, reason: 'inactive', penalty: Infinity };
+    }
+    const actionName = this._getLemmingActionName(lem);
+    if (DEAD_FRONTIER_ACTIONS.has(actionName)) {
+      return { viable: false, reason: 'dead-action', penalty: Infinity };
+    }
+    if (STATIONARY_FRONTIER_ACTIONS.has(actionName)) {
+      return { viable: false, reason: 'stationary-action', penalty: Infinity };
+    }
+    const levelWidth = this.level?.width ?? Infinity;
+    const levelHeight = this.level?.height ?? Infinity;
+    if (lem.x < 0 || lem.x >= levelWidth || lem.y < Lemming.LEM_MIN_Y || lem.y >= levelHeight + 6) {
+      return { viable: false, reason: 'out-of-level', penalty: Infinity };
+    }
+    if (actionName === 'falling' && !lem.hasParachute) {
+      const fallDistance = Number.isFinite(lem.state) ? lem.state : 0;
+      const maxSafeFall = Math.min(this.maxDrop, Lemming.LEM_MAX_FALLING);
+      if (fallDistance > maxSafeFall) {
+        return { viable: false, reason: 'falling-lethal', penalty: Infinity };
+      }
+    }
+    const airborne = AIRBORNE_FRONTIER_ACTIONS.has(actionName);
+    if (!airborne && tracker) {
+      if (tracker.stallTicks >= this.frontierStuckTicks) {
+        return { viable: false, reason: 'stuck', penalty: Infinity };
+      }
+      if (tracker.flipCount >= this.frontierTurnaroundLimit) {
+        return { viable: false, reason: 'turnaround-stuck', penalty: Infinity };
+      }
+    }
+    let penalty = 0;
+    let reason = actionName || 'live';
+    if (!lem.lookRight) {
+      penalty += this.frontierTurnaroundPenalty;
+      reason = `${reason}:turnaround`;
+    }
+    if (actionName === 'falling' && !lem.hasParachute) {
+      penalty += 4;
+    }
+    return { viable: true, reason, actionName, penalty };
+  },
+
+  _getFrontierFallbackX() {
+    const entrance = this.level?.entrances?.[0] || null;
+    if (Number.isFinite(entrance?.x)) return entrance.x;
+    if (Number.isFinite(this.entranceX)) return this.entranceX;
+    return null;
+  },
+
+  _selectFrontierState({ force = false, requireRight = false } = {}) {
+    const tick = this._getProcgenTick();
+    if (!force && !requireRight && this._frontierState && this._frontierCacheTick === tick) {
+      if (!this._frontierState.lemming || this._isLiveFrontierLemming(this._frontierState.lemming)) {
+        return this._frontierState;
+      }
+    }
+    const lems = this._getProcgenLemmings();
+    const activeIds = new Set();
+    let best = null;
+    let bestTracker = null;
+    let bestViability = null;
+    let bestScore = -Infinity;
+    let liveCount = 0;
+    let viableCount = 0;
+    let rightMovingCount = 0;
+    let rightmostX = null;
+    for (const lem of lems) {
+      if (!this._isLiveFrontierLemming(lem)) continue;
+      liveCount += 1;
+      if (Number.isFinite(lem.id)) activeIds.add(lem.id);
+      const tracker = this._trackFrontierLemming(lem, tick);
+      const viability = this._evaluateFrontierViability(lem, tracker);
+      if (!viability.viable) continue;
+      viableCount += 1;
+      if (lem.lookRight) rightMovingCount += 1;
+      if (rightmostX == null || lem.x > rightmostX) rightmostX = lem.x;
+      if (requireRight && !lem.lookRight) continue;
+      const score = lem.x - viability.penalty;
+      if (score > bestScore || (score === bestScore && (!best || lem.x > best.x))) {
+        best = lem;
+        bestTracker = tracker;
+        bestViability = viability;
+        bestScore = score;
+      }
+    }
+    const fallbackX = best ? best.x : this._getFrontierFallbackX();
+    const state = {
+      tick,
+      lemming: best,
+      id: best?.id ?? null,
+      x: Number.isFinite(fallbackX) ? fallbackX : null,
+      y: Number.isFinite(best?.y) ? best.y : null,
+      lookRight: best ? !!best.lookRight : null,
+      actionName: bestViability?.actionName ?? null,
+      reason: bestViability?.reason ?? (liveCount ? 'no-viable-lemming' : 'no-live-lemming'),
+      velocityX: bestTracker?.velocityX ?? 0,
+      velocityY: bestTracker?.velocityY ?? 0,
+      liveCount,
+      viableCount,
+      rightMovingCount,
+      rightmostX
+    };
+    this._pruneFrontierTrackingState(activeIds, tick);
+    if (!requireRight) {
+      this._frontierState = state;
+      this._frontierCacheTick = tick;
+      this._frontier = state;
+      this._getLookaheadState(state);
+    }
+    return state;
+  },
+
+  _getFrontierState(options = {}) {
+    return this._selectFrontierState(options || {});
+  },
+
+  _getFrontierLemming({ requireRight = false } = {}) {
+    return this._selectFrontierState({ requireRight }).lemming;
+  },
+
+  _getFollowLemming() {
+    return this._getFrontierLemming();
+  },
+
+  _isViableFrontierLemming(lem, { requireRight = false } = {}) {
+    if (requireRight && !lem?.lookRight) return false;
+    const tick = this._getProcgenTick();
+    const tracker = this._trackFrontierLemming(lem, tick);
+    return this._evaluateFrontierViability(lem, tracker).viable;
+  },
+
+  _getFrontierSummary() {
+    const state = this._getFrontierState({ force: true });
+    return {
+      id: state.id,
+      x: state.lemming ? state.x : null,
+      y: state.y,
+      lookRight: state.lookRight,
+      action: state.actionName,
+      reason: state.reason,
+      tick: state.tick,
+      velocityX: state.velocityX,
+      liveCount: state.liveCount,
+      viableCount: state.viableCount,
+      rightMovingCount: state.rightMovingCount,
+      rightmostX: state.rightmostX
+    };
+  },
+
+  _getLookaheadState(frontierOrX = null) {
+    const frontierX = Number.isFinite(frontierOrX)
+      ? frontierOrX
+      : (Number.isFinite(frontierOrX?.x) ? frontierOrX.x : this._frontierState?.x);
+    const velocityX = Math.max(0, Number.isFinite(frontierOrX?.velocityX)
+      ? frontierOrX.velocityX
+      : (this._frontierState?.velocityX ?? 0));
+    const min = Math.max(1, Math.floor(this.lookAheadMin ?? this.lookAhead ?? 1));
+    const max = Math.max(min, Math.floor(this.lookAheadMax ?? this.lookAhead ?? min));
+    const speedBonus = Math.ceil(velocityX * (this.lookAheadSpeedTicks ?? 0));
+    const range = Math.max(0, max - min);
+    const previousVariation = this._lookaheadState?.variation;
+    const variation = Number.isFinite(previousVariation)
+      ? Math.max(0, Math.min(range, Math.floor(previousVariation)))
+      : this._randInt(0, range);
+    const distance = Math.max(min, Math.min(max, min + speedBonus + variation));
+    const generatedEndX = Number.isFinite(this._groundEndX) ? this._groundEndX : null;
+    const groundAhead = Number.isFinite(frontierX) && Number.isFinite(generatedEndX)
+      ? generatedEndX - frontierX
+      : null;
+    const threshold = Math.max(0, Math.floor(this.extendThreshold || 0));
+    const state = {
+      distance,
+      min,
+      max,
+      threshold,
+      groundAhead,
+      distanceToGeneratedEnd: groundAhead,
+      generatedEndX,
+      variation,
+      due: Number.isFinite(groundAhead) ? groundAhead <= distance + threshold : false
+    };
+    this.lookAhead = distance;
+    this._lookAheadDistance = distance;
+    this._lookAheadThreshold = threshold;
+    this._lookaheadState = state;
+    return state;
+  },
+
+  _getLookaheadTarget() {
+    return this._getLookaheadState(this._frontierState).distance;
+  },
+
+  _refreshLookaheadTarget() {
+    if (this._lookaheadState) {
+      this._lookaheadState = { ...this._lookaheadState, variation: Number.NaN };
+    }
+    return this._getLookaheadState(this._frontierState).distance;
+  },
+
+  _needsGroundForFrontier(frontierX) {
+    if (!Number.isFinite(frontierX)) return false;
+    return this._getLookaheadState(frontierX).due;
+  },
+
+  getDebugState() {
+    const frontier = this._getFrontierSummary();
+    const lookahead = this._getLookaheadState(this._frontierState);
+    return {
+      version: 1,
+      selectedTheme: this._getSelectedTheme?.() ?? this.assets?.styleName ?? null,
+      seed: this._rngSeed ?? null,
+      generatedEndX: Number.isFinite(this._groundEndX) ? Math.max(0, Math.floor(this._groundEndX)) : 0,
+      frontier,
+      lookahead: {
+        distance: lookahead.distance,
+        min: lookahead.min,
+        max: lookahead.max,
+        threshold: lookahead.threshold,
+        extendThreshold: lookahead.threshold,
+        groundAhead: lookahead.groundAhead,
+        distanceToGeneratedEnd: lookahead.distanceToGeneratedEnd,
+        variation: lookahead.variation,
+        due: lookahead.due,
+        levelWidth: this.level?.width ?? null
+      },
+      recentChunks: (this._recentChunks || []).map(chunk => ({ ...chunk })),
+      recentCertificates: (this._recentCertificates || []).map(entry => ({ ...entry })),
+      recentPieces: (this._recentPieces || []).map(piece => ({
+        ...piece,
+        bounds: piece.bounds ? { ...piece.bounds } : null
+      })),
+      recentAssists: (this._recentAssists || []).map(assist => ({
+        ...assist,
+        lemming: assist.lemming ? { ...assist.lemming } : null,
+        scan: assist.scan ? {
+          direction: assist.scan.direction,
+          gap: assist.scan.gap ? { ...assist.scan.gap } : null,
+          wall: assist.scan.wall ? { ...assist.scan.wall } : null,
+          hazard: assist.scan.hazard ? { ...assist.scan.hazard } : null
+        } : null
+      })),
+      trackingSizes: this._getTrackingSizes()
+    };
+  },
+
+  _getTrackingSizes() {
+    const scanCacheSizes = {};
+    for (const [key, value] of Object.entries(this._scanCache || {})) {
+      scanCacheSizes[key] = value?.size ?? 0;
+    }
+    return {
+      gaps: this._gaps?.length ?? 0,
+      gapScanStart: this._gapScanStart ?? 0,
+      seenFalls: this._seenFalls?.size ?? 0,
+      aiCooldowns: this._aiLemmingCooldown?.size ?? 0,
+      aiStalls: this._aiStallState?.size ?? 0,
+      frontier: this._frontierLemmingState?.size ?? 0,
+      hazardTriggers: this._hazardTriggers?.length ?? 0,
+      recentChunks: this._recentChunks?.length ?? 0,
+      recentCertificates: this._recentCertificates?.length ?? 0,
+      recentPieces: this._recentPieces?.length ?? 0,
+      recentAssists: this._recentAssists?.length ?? 0,
+      recentDecor: this._recentDecor?.length ?? 0,
+      scanCache: scanCacheSizes
+    };
+  },
+
+  _getStructurePlan() {
+    if (!this._structurePlan || this._structurePlan.remaining <= 0) {
+      this._structurePlan = this._seedStructurePlan();
+    }
+    return this._structurePlan;
+  },
+
+  _seedStructurePlan() {
+    const roll = this._rand();
+    let type = 'flat';
+    if (roll < 0.25) type = 'steps-up';
+    else if (roll < 0.5) type = 'steps-down';
+    else if (roll < 0.65) type = 'shelf';
+    else if (roll < 0.8) type = 'pillar';
+    else type = 'staircase';
+    const length = type === 'staircase'
+      ? this._randInt(4, 10)
+      : this._randInt(2, 6);
+    return {
+      type,
+      remaining: length,
+      step: this._randInt(1, Math.max(2, this.maxStepUp)),
+      surface: null,
+      direction: this._rand() < 0.5 ? -1 : 1,
+      turnAt: Math.max(1, Math.floor(length / 2))
+    };
+  },
+
+  _nextSurfaceY(plan, baseSurfaceY) {
+    if (!plan) return baseSurfaceY;
+    const levelHeight = this.level?.height ?? 0;
+    const maxSurface = Math.max(0, levelHeight - 1);
+    if (!Number.isFinite(plan.surface)) {
+      plan.surface = baseSurfaceY;
+    }
+    let surface = plan.surface;
+    if (plan.type === 'steps-up') {
+      surface -= plan.step;
+    } else if (plan.type === 'steps-down') {
+      surface += plan.step;
+    } else if (plan.type === 'shelf') {
+      surface += this._randInt(-2, 2);
+    } else if (plan.type === 'pillar') {
+      surface += this._randInt(-1, 1);
+    } else if (plan.type === 'staircase') {
+      surface += plan.step * plan.direction;
+      if (plan.remaining <= plan.turnAt) {
+        plan.direction = -plan.direction;
+      }
+    }
+    plan.remaining -= 1;
+    if (plan.remaining <= 0) {
+      this._structurePlan = null;
+    }
+    plan.surface = surface;
+    return Math.max(0, Math.min(maxSurface, surface));
+  },
+
+  _clampSurfaceForEntrance(surfaceY, piece, cursorX) {
+    if (!Number.isFinite(this.entranceY) || !Number.isFinite(this.entranceX)) {
+      return surfaceY;
+    }
+    if (!piece?.bounds) return surfaceY;
+    const span = Math.max(80, piece.bounds.width * 2);
+    if (Math.abs(cursorX - this.entranceX) > span) return surfaceY;
+    const clearance = Math.max(12, this.entranceClearance);
+    const minSurface = this.entranceY + clearance;
+    return Math.max(surfaceY, minSurface);
+  },
+
+  _placeDecoration(baseX, baseY, basePiece) {
+    if (!this.assets || !this.stamper) return;
+    const decor = this.assets.pickDecorPiece(32);
+    if (!decor?.bounds) return;
+    const offsetX = basePiece?.bounds?.minX ?? 0;
+    const destX = baseX + offsetX + this._randInt(-4, 6);
+    const raise = this._randInt(6, 22);
+    const destY = baseY - decor.bounds.height - raise;
+    if (this._overlapsRecentDecor(destX, destY, decor)) return;
+    const rect = this.stamper.stamp(decor, destX, destY);
+    this._trackGeneratedPiece(decor, destX, destY, 'decor', rect);
+    this._trackDecorPlacement(destX, destY, decor);
+  },
+
+  _overlapsRecentDecor(destX, destY, decor) {
+    const rect = {
+      x: destX + decor.bounds.minX,
+      y: destY + decor.bounds.minY,
+      w: decor.bounds.width,
+      h: decor.bounds.height
+    };
+    for (const other of this._recentDecor) {
+      if (!other) continue;
+      const xOverlap = Math.min(rect.x + rect.w, other.x + other.w) - Math.max(rect.x, other.x);
+      const yOverlap = Math.min(rect.y + rect.h, other.y + other.h) - Math.max(rect.y, other.y);
+      if (xOverlap > 2 && yOverlap > 2) {
+        return true;
+      }
+      const centerDx = Math.abs((rect.x + rect.w / 2) - (other.x + other.w / 2));
+      const centerDy = Math.abs((rect.y + rect.h / 2) - (other.y + other.h / 2));
+      if (centerDx < 24 && centerDy < 36) {
+        return true;
+      }
+    }
+    return false;
+  },
+
+  _trackDecorPlacement(destX, destY, decor) {
+    this._recentDecor.push({
+      x: destX + decor.bounds.minX,
+      y: destY + decor.bounds.minY,
+      w: decor.bounds.width,
+      h: decor.bounds.height
+    });
+    if (this._recentDecor.length > 40) {
+      this._recentDecor.splice(0, this._recentDecor.length - 40);
+    }
+  },
+
+  _advanceGapScanCursor(referenceX = null) {
+    const anchorX = Number.isFinite(referenceX)
+      ? referenceX
+      : (Number.isFinite(this._cameraX) ? this._cameraX : this._getRightmostX());
+    if (!Number.isFinite(anchorX)) return;
+    const cutoff = anchorX - 200;
+    while (this._gapScanStart < this._gaps.length) {
+      const gap = this._gaps[this._gapScanStart];
+      if (!gap || !Number.isFinite(gap.x) || !Number.isFinite(gap.width)) {
+        this._gapScanStart += 1;
+        continue;
+      }
+      if ((gap.x + gap.width) <= cutoff) {
+        this._gapScanStart += 1;
+        continue;
+      }
+      break;
+    }
+  },
+
+  _pruneGapQueue(referenceX = null) {
+    this._advanceGapScanCursor(referenceX);
+    if (this._gapScanStart <= 0) {
+      this._capGapQueue();
+      return;
+    }
+    if (this._gapScanStart < 256 && this._gapScanStart < (this._gaps.length >> 1)) {
+      this._capGapQueue();
+      return;
+    }
+    this._gaps.splice(0, this._gapScanStart);
+    this._gapScanStart = 0;
+    this._capGapQueue();
+  },
+
+  _capGapQueue() {
+    const limit = Math.max(1, Math.floor(this.gapTrackingLimit ?? 256));
+    if (!Array.isArray(this._gaps) || this._gaps.length <= limit) return;
+    const removeCount = this._gaps.length - limit;
+    this._gaps.splice(0, removeCount);
+    this._gapScanStart = Math.max(0, this._gapScanStart - removeCount);
+  },
+
+  _collectActiveLemmingIds() {
+    const lems = this._getProcgenLemmings();
+    const ids = new Set();
+    for (let i = 0; i < lems.length; i += 1) {
+      const lem = lems[i];
+      if (!lem || lem.removed || lem.disabled) continue;
+      if (!Number.isFinite(lem.id)) continue;
+      ids.add(lem.id);
+    }
+    return ids;
+  },
+
+  _pruneTrackingState(tick) {
+    const activeIds = this._collectActiveLemmingIds();
+    for (const [id, untilTick] of this._aiLemmingCooldown) {
+      if (activeIds.has(id) && (!Number.isFinite(tick) || untilTick >= tick - 120)) continue;
+      this._aiLemmingCooldown.delete(id);
+    }
+    for (const id of this._aiStallState.keys()) {
+      if (activeIds.has(id)) continue;
+      this._aiStallState.delete(id);
+    }
+    const minSeenTick = Number.isFinite(tick) ? tick - this.fallEventMemoryTicks : -Infinity;
+    for (const [id, seenTick] of this._seenFalls) {
+      if (activeIds.has(id)) continue;
+      if (Number.isFinite(seenTick) && seenTick >= minSeenTick) continue;
+      this._seenFalls.delete(id);
+    }
+    this._pruneFrontierTrackingState(activeIds, tick);
+    const maxTracked = Math.max(activeIds.size, Math.floor(this.frontierMaxTrackedLemmings ?? 128));
+    this._pruneMapToLimit(this._aiLemmingCooldown, maxTracked, activeIds, value => value);
+    this._pruneMapToLimit(this._aiStallState, maxTracked, activeIds, value => value?.lastSeenTick ?? 0);
+    this._pruneMapToLimit(this._seenFalls, maxTracked, activeIds, value => value);
+    this._pruneGapQueue();
+    this._pruneGeneratedTracking();
+  },
+
+  _pruneFrontierTrackingState(activeIds = new Set(), tick = null) {
+    if (!this._frontierLemmingState) return;
+    const staleBefore = Number.isFinite(tick)
+      ? tick - Math.max(this.fallEventMemoryTicks, this.frontierStuckTicks * 2)
+      : -Infinity;
+    for (const [id, state] of this._frontierLemmingState) {
+      if (activeIds.has(id)) continue;
+      if (Number.isFinite(state?.lastSeenTick) && state.lastSeenTick >= staleBefore) continue;
+      this._frontierLemmingState.delete(id);
+    }
+    const maxTracked = Math.max(activeIds.size, Math.floor(this.frontierMaxTrackedLemmings ?? 128));
+    this._pruneMapToLimit(this._frontierLemmingState, maxTracked, activeIds, value => value?.lastSeenTick ?? 0);
+  },
+
+  _pruneMapToLimit(map, limit, activeIds = new Set(), getSortValue = value => value) {
+    if (!map || typeof map.size !== 'number') return;
+    const maxSize = Math.max(0, Math.floor(limit));
+    if (map.size <= maxSize) return;
+    if (maxSize === 0) {
+      map.clear();
+      return;
+    }
+    const entries = [];
+    for (const [key, value] of map) {
+      entries.push({
+        key,
+        active: activeIds.has(key),
+        sort: Number(getSortValue(value)) || 0
+      });
+    }
+    entries.sort((a, b) => {
+      if (a.active !== b.active) return a.active ? 1 : -1;
+      return a.sort - b.sort;
+    });
+    for (const entry of entries) {
+      if (map.size <= maxSize) break;
+      if (entry.active && map.size <= activeIds.size) break;
+      map.delete(entry.key);
+    }
+  },
+
+  _rebuildHazardIndex(tick = null) {
+    const triggers = this.level?.triggers;
+    this._hazardTriggerSource = triggers || null;
+    this._hazardTriggers = [];
+    this._hazardTriggerSourceSize = Array.isArray(triggers) ? triggers.length : 0;
+    this._hazardIndexLastRefreshTick = Number.isFinite(tick) ? tick : 0;
+    if (!Array.isArray(triggers) || triggers.length === 0) return;
+    for (const trigger of triggers) {
+      if (!trigger || !HAZARD_TRIGGER_TYPES.has(trigger.type)) continue;
+      const x1 = Math.min(trigger.x1, trigger.x2);
+      const x2 = Math.max(trigger.x1, trigger.x2);
+      const y1 = Math.min(trigger.y1, trigger.y2);
+      const y2 = Math.max(trigger.y1, trigger.y2);
+      this._hazardTriggers.push({
+        x1,
+        x2,
+        y1,
+        y2,
+        type: trigger.type
+      });
+    }
+    this._hazardTriggers.sort((a, b) => a.x1 - b.x1);
+  },
+
+  _pickSegmentWidth() {
+    const min = Math.max(2, Math.floor(this.segmentMinWidth));
+    const max = Math.max(min, Math.floor(this.segmentMaxWidth));
+    return min + Math.floor(this._rand() * (max - min + 1));
+  },
+
+  _pickGapWidth() {
+    const min = Math.max(2, Math.floor(this.gapMinWidth));
+    const max = Math.max(min, Math.floor(this.gapMaxWidth));
+    return min + Math.floor(this._rand() * (max - min + 1));
+  },
+
+  _shouldInsertGap() {
+    if (this._gapCooldown > 0) {
+      this._gapCooldown -= 1;
+      return false;
+    }
+    if (this._rand() > this.gapChance) return false;
+    return true;
+  },
+
+  _pickNextTopY() {
+    const levelHeight = this.level?.height ?? 0;
+    const maxTop = Math.max(0, levelHeight - this.groundHeight);
+    if (this._sustainRemaining <= 0) {
+      this._seedSustainLevel(maxTop);
+    }
+    const delta = this._nextElevationDelta();
+    let next = this._groundTopY + delta;
+    const offset = this._groundTopY - this._sustainBaseY;
+    if (offset !== 0) {
+      const biasStep = Math.min(3, Math.ceil(Math.abs(offset) / 8));
+      next += offset > 0 ? -biasStep : biasStep;
+    }
+    this._sustainRemaining -= 1;
+    return Math.max(0, Math.min(maxTop, next));
+  },
+
+  _nextElevationDelta() {
+    if (!this._terrainPlan || this._terrainPlan.remaining <= 0) {
+      this._seedTerrainPlan();
+    }
+    const mode = this._terrainPlan.mode;
+    const up = Math.max(1, Math.floor(this.maxStepUp));
+    const down = Math.max(1, Math.floor(this.maxDrop));
+    let delta = 0;
+    if (mode === 'climb') {
+      delta = -this._randInt(1, up);
+    } else if (mode === 'drop-small') {
+      delta = this._randInt(1, Math.min(4, down));
+    } else if (mode === 'drop-medium') {
+      delta = this._randInt(Math.min(5, down), Math.min(14, down));
+    } else if (mode === 'drop-big') {
+      const minBig = Math.max(6, Math.floor(down * 0.7));
+      delta = this._randInt(minBig, down);
+    } else {
+      delta = this._randInt(-1, 1);
+    }
+    this._terrainPlan.remaining -= 1;
+    return delta;
+  },
+
+  _seedTerrainPlan() {
+    const prev = this._terrainPlan?.mode || 'flat';
+    let mode = 'flat';
+    if (prev === 'climb') {
+      mode = 'flat';
+      this._pendingDrop = true;
+    } else if (prev === 'flat') {
+      if (this._pendingDrop) {
+        const roll = this._rand();
+        if (roll < 0.5) mode = 'drop-small';
+        else if (roll < 0.85) mode = 'drop-medium';
+        else mode = 'drop-big';
+        this._pendingDrop = false;
+      } else {
+        const roll = this._rand();
+        if (roll < 0.5) mode = 'climb';
+        else if (roll < 0.75) mode = 'drop-small';
+        else if (roll < 0.92) mode = 'drop-medium';
+        else mode = 'drop-big';
+      }
+    } else {
+      mode = 'flat';
+    }
+    const lengths = {
+      climb: this._randInt(4, 10),
+      flat: this._randInt(8, 18),
+      'drop-small': this._randInt(3, 8),
+      'drop-medium': this._randInt(2, 4),
+      'drop-big': 1
+    };
+    this._terrainPlan = {
+      mode,
+      remaining: lengths[mode] || 3
+    };
+  },
+
+  _rand() {
+    const value = this._rng?.();
+    if (!Number.isFinite(value)) return 0;
+    if (value <= 0) return 0;
+    if (value >= 1) return 0.9999999999999999;
+    return value;
+  },
+
+  _randInt(min, max) {
+    const lo = Math.min(min, max);
+    const hi = Math.max(min, max);
+    return lo + Math.floor(this._rand() * (hi - lo + 1));
+  },
+
+  _getNextColorIndex() {
+    const maxIndex = 15;
+    const base = Number.isFinite(this.groundColorIndex) && this.groundColorIndex > 0
+      ? this.groundColorIndex
+      : 1;
+    if (!Number.isFinite(this._segmentColorIndex) || this._segmentColorIndex <= 0) {
+      this._segmentColorIndex = base;
+    }
+    if (!this._colorTransition || this._colorTransition.remaining <= 0) {
+      const target = this._randInt(1, maxIndex);
+      const to = target === this._segmentColorIndex ? ((target % maxIndex) + 1) : target;
+      const total = this._randInt(10, 300);
+      const step = total > 0 ? (to - this._segmentColorIndex) / total : 0;
+      this._colorTransition = {
+        from: this._segmentColorIndex,
+        to,
+        total,
+        remaining: total,
+        current: this._segmentColorIndex,
+        step
+      };
+    }
+    const transition = this._colorTransition;
+    transition.current += transition.step;
+    transition.remaining -= 1;
+    const progress = transition.total > 0
+      ? (transition.total - transition.remaining) / transition.total
+      : 1;
+    let next = transition.from;
+    if (transition.from !== transition.to) {
+      const chance = Math.min(1, Math.max(0, progress));
+      next = this._rand() < chance ? transition.to : transition.from;
+    }
+    if (transition.remaining <= 0) {
+      next = transition.to;
+      transition.current = transition.to;
+    }
+    next = Math.min(maxIndex, Math.max(1, next));
+    this._segmentColorIndex = next;
+    return next;
+  },
+
+  _seedSustainLevel(maxTop) {
+    const upRange = Math.max(8, Math.floor(this.maxStepUp * 8));
+    const downRange = Math.max(12, Math.floor(this.maxDrop * 0.35));
+    const delta = this._randInt(-upRange, downRange);
+    const nextBase = Math.max(0, Math.min(maxTop, this._groundTopY + delta));
+    this._sustainBaseY = nextBase;
+    this._sustainRemaining = this._randInt(20, 200);
+  }
+};
+export { procgenTerrainPlanningMethods };
diff --git a/js/app/procgenAssetManager.js b/js/app/procgenAssetManager.js
index 1683dda6..9d7c2239 100644
--- a/js/app/procgenAssetManager.js
+++ b/js/app/procgenAssetManager.js
@@ -51,6 +51,7 @@ const getTerrainStats = (image) => {
 class ProcgenAssetManager {
   constructor({ styleName, config, fileProvider, random } = {}) {
     this.styleName = styleName || 'dirt';
+    this.groundSet = null;
     this.config = config || null;
     this.fileProvider = fileProvider || null;
     this.random = typeof random === 'function' ? random : Math.random;
@@ -62,6 +63,7 @@ class ProcgenAssetManager {
     this.decorPieces = [];
     this.gadgetDecor = [];
     this.gadgetHazards = [];
+    this._pickCache = new WeakMap();
   }
 
   async load() {
@@ -71,6 +73,8 @@ class ProcgenAssetManager {
       this.fileProvider
     );
     this.assets = assets;
+    this.styleName = assets?.styleName || this.styleName;
+    this.groundSet = Number.isFinite(assets?.groundSet) ? assets.groundSet | 0 : null;
     this._buildTerrainCatalog(assets);
     this._buildGadgetCatalog(assets);
     return this;
@@ -79,12 +83,17 @@ class ProcgenAssetManager {
   _buildTerrainCatalog(assets) {
     const images = assets?.terrainImages || [];
     const entries = [];
+    const styleName = assets?.styleName || this.styleName;
+    const groundSet = Number.isFinite(assets?.groundSet) ? assets.groundSet | 0 : null;
     for (let id = 0; id < images.length; id++) {
       const image = images[id];
       const stats = getTerrainStats(image);
       if (!stats) continue;
       entries.push({
         id,
+        styleName,
+        theme: styleName,
+        groundSet,
         image,
         frame: stats.frame,
         width: stats.width,
@@ -109,6 +118,7 @@ class ProcgenAssetManager {
       if (piece.isSteel) return false;
       return piece.solidRatio > 0 && piece.solidRatio < 0.2;
     });
+    this._pickCache = new WeakMap();
   }
 
   _buildGadgetCatalog(assets) {
@@ -127,21 +137,33 @@ class ProcgenAssetManager {
 
   _pickFromList(list, maxWidth, minHeight = 1, minWidth = 1) {
     if (!Array.isArray(list) || list.length === 0) return null;
-    let candidates = list;
-    if (Number.isFinite(maxWidth)) {
-      candidates = candidates.filter(piece => piece.bounds.width <= maxWidth);
+    let listCache = this._pickCache.get(list);
+    if (!listCache) {
+      listCache = new Map();
+      this._pickCache.set(list, listCache);
     }
-    if (Number.isFinite(minHeight)) {
-      candidates = candidates.filter(piece => piece.bounds.height >= minHeight);
-    }
-    if (Number.isFinite(minWidth)) {
-      candidates = candidates.filter(piece => piece.bounds.width >= minWidth);
+    const key = `${Number.isFinite(maxWidth) ? maxWidth : 'inf'}:${Number.isFinite(minHeight) ? minHeight : 'inf'}:${Number.isFinite(minWidth) ? minWidth : 'inf'}`;
+    let candidates = listCache.get(key);
+    if (!candidates) {
+      candidates = [];
+      for (let i = 0; i < list.length; i += 1) {
+        const piece = list[i];
+        const bounds = piece?.bounds;
+        if (!bounds) continue;
+        if (Number.isFinite(maxWidth) && bounds.width > maxWidth) continue;
+        if (Number.isFinite(minHeight) && bounds.height < minHeight) continue;
+        if (Number.isFinite(minWidth) && bounds.width < minWidth) continue;
+        candidates.push(piece);
+      }
+      if (listCache.size > 128) listCache.clear();
+      listCache.set(key, candidates);
     }
-    if (candidates.length === 0) {
-      candidates = list;
+    if (candidates.length) {
+      const idx = Math.floor(this.random() * candidates.length);
+      return candidates[idx];
     }
-    const idx = Math.floor(this.random() * candidates.length);
-    return candidates[idx];
+    const idx = Math.floor(this.random() * list.length);
+    return list[idx];
   }
 
   pickGroundPiece(maxWidth, minHeight, minWidth) {
@@ -151,6 +173,19 @@ class ProcgenAssetManager {
   pickDecorPiece(maxWidth) {
     return this._pickFromList(this.decorPieces, maxWidth);
   }
+
+  getThemeSummary() {
+    return {
+      selectedTheme: this.styleName,
+      styleName: this.styleName,
+      groundSet: this.groundSet,
+      terrainPieceCount: this.terrainPieces.length,
+      groundPieceCount: this.groundPieces.length,
+      decorPieceCount: this.decorPieces.length,
+      decorGadgetCount: this.gadgetDecor.length,
+      hazardGadgetCount: this.gadgetHazards.length
+    };
+  }
 }
 
 export { ProcgenAssetManager };
diff --git a/js/app/procgenBoot.js b/js/app/procgenBoot.js
index 2adbb7a0..d76028af 100644
--- a/js/app/procgenBoot.js
+++ b/js/app/procgenBoot.js
@@ -12,6 +12,12 @@ import { registerServiceWorker } from './registerServiceWorker.js';
 import { DEFAULT_LEVEL_HEIGHT } from '../level/ClassicLevelConstants.js';
 import { bindCanvasFocusBlur } from './canvasFocusBlur.js';
 import { ProcgenStageAdapter } from './procgenStageAdapter.js';
+import { ANALYTICS_EVENT_TYPES, createAnalyticsService } from './analytics.js';
+import {
+  normalizeSeed,
+  deriveSeed,
+  createSeededRandom
+} from '../core/seededRandom.js';
 
 const PROCGEN_GAME_TYPE = GameTypes.OHNO;
 const PROCGEN_LEVEL_WIDTH = 65535;
@@ -22,6 +28,8 @@ const PROCGEN_GROUND_HEIGHT = 4;
 const PROCGEN_ENTRANCE_OFFSET = 80;
 const PROCGEN_INITIAL_GROUND_WIDTH = 280;
 const PROCGEN_ENTRANCE_CLEARANCE = 28;
+const PROCGEN_SEED_PARAM = 'seed';
+const PROCGEN_SEED_STORAGE_KEY = 'procgen.seed';
 const PROCGEN_GROUND_SETS_BY_PATH = {
   lemmings: [0, 1, 2, 3, 4],
   lemmings_ohNo: [0, 1, 2, 3],
@@ -41,12 +49,73 @@ const PROCGEN_SKILLS = {
   DIGGER: 9999
 };
 
-const shuffle = (list) => {
-  for (let i = list.length - 1; i > 0; i--) {
-    const j = Math.floor(Math.random() * (i + 1));
-    [list[i], list[j]] = [list[j], list[i]];
+let activeProcgenRuntime = null;
+let analytics = null;
+let procgenBootListeners = [];
+
+const runFocusBlurCleanup = (runtime) => {
+  const cleanup = runtime?.focusBlurCleanup;
+  if (typeof cleanup === 'function') {
+    cleanup();
+  }
+  if (runtime) {
+    runtime.focusBlurCleanup = null;
+  }
+};
+
+/**
+ * Ensure repeat procgen init/start cycles do not leak timers/listeners.
+ * Cleanup order matters: controller first (detaches timer/event hooks), then
+ * stage adapter/view/game teardown.
+ */
+const disposeProcgenRuntime = () => {
+  const runtime = activeProcgenRuntime;
+  if (!runtime) return;
+  activeProcgenRuntime = null;
+  runFocusBlurCleanup(runtime);
+  runtime.controller?.stop?.();
+  if (runtime.view && runtime.view.procgenController === runtime.controller) {
+    runtime.view.procgenController = null;
   }
-  return list;
+  if (typeof window !== 'undefined' && window.procgenDebugState) {
+    window.procgenDebugState = null;
+  }
+  runtime.stageAdapter?.dispose?.();
+  runtime.game?.stop?.();
+  runtime.view?.dispose?.();
+};
+
+const addProcgenBootListener = (target, eventName, handler, options) => {
+  if (!target?.addEventListener || typeof handler !== 'function') return;
+  target.addEventListener(eventName, handler, options);
+  procgenBootListeners.push({ target, eventName, handler, options });
+};
+
+const disposeProcgenBootListeners = () => {
+  while (procgenBootListeners.length) {
+    const { target, eventName, handler, options } = procgenBootListeners.pop();
+    target?.removeEventListener?.(eventName, handler, options);
+  }
+};
+
+const installProcgenBootListeners = () => {
+  disposeProcgenBootListeners();
+  const boot = () => {
+    resizeCanvas();
+    init();
+  };
+  addProcgenBootListener(window, 'resize', resizeCanvas);
+  addProcgenBootListener(window, 'beforeunload', disposeProcgenRuntime);
+
+  if (document.readyState === 'loading') {
+    addProcgenBootListener(document, 'DOMContentLoaded', boot, { once: true });
+  } else {
+    boot();
+  }
+};
+
+const setActiveProcgenRuntimeForTest = (runtime) => {
+  activeProcgenRuntime = runtime || null;
 };
 
 const getProcgenGroundSets = (config) => {
@@ -55,38 +124,38 @@ const getProcgenGroundSets = (config) => {
   return Array.isArray(sets) && sets.length ? sets : null;
 };
 
-const pickProcgenStyle = async (fileProvider, config) => {
+const getCompatibleProcgenStyleNames = (config) => {
   const names = getStyleNames();
-  if (!names.length) return 'fire';
   const allowedGroundSets = getProcgenGroundSets(config);
-  let last = null;
-  try {
-    last = window.localStorage?.getItem('procgen.style') || null;
-  } catch (err) {
-    last = null;
-  }
-  const normalizedLast = last ? last.toLowerCase() : null;
-  const candidates = normalizedLast
-    ? names.filter(name => name.toLowerCase() !== normalizedLast)
-    : names.slice();
-  const filtered = allowedGroundSets
-    ? candidates.filter(name => {
-      const style = getStyle(name);
-      return Number.isFinite(style?.groundSet)
-        && allowedGroundSets.includes(style.groundSet | 0);
-    })
-    : candidates.slice();
-  const shuffled = shuffle(filtered);
-  if (normalizedLast && !shuffled.some(name => name.toLowerCase() === normalizedLast)) {
-    const lastStyle = getStyle(last);
-    const lastGroundSet = Number.isFinite(lastStyle?.groundSet) ? lastStyle.groundSet | 0 : null;
-    const allowLast = !allowedGroundSets
-      || (lastGroundSet != null && allowedGroundSets.includes(lastGroundSet));
-    if (allowLast) {
-      shuffled.push(last);
-    }
-  }
-  const list = shuffled.length ? shuffled : names.slice();
+  if (!allowedGroundSets) return names;
+  return names.filter(name => {
+    const style = getStyle(name);
+    return Number.isFinite(style?.groundSet)
+      && allowedGroundSets.includes(style.groundSet | 0);
+  });
+};
+
+const rotateFromRandomIndex = (list, rng = Math.random) => {
+  if (!Array.isArray(list) || list.length === 0) return [];
+  const start = Math.floor(rng() * list.length) % list.length;
+  return list.slice(start).concat(list.slice(0, start));
+};
+
+const buildProcgenThemeContract = (styleName, config = null) => {
+  const style = getStyle(styleName);
+  return {
+    selectedTheme: style?.name || styleName || null,
+    styleName: style?.name || styleName || null,
+    groundSet: Number.isFinite(style?.groundSet) ? style.groundSet | 0 : null,
+    packPath: config?.path || null
+  };
+};
+
+const pickProcgenStyle = async (fileProvider, config, rng = Math.random) => {
+  const names = getStyleNames();
+  if (!names.length) return 'fire';
+  const compatible = getCompatibleProcgenStyleNames(config);
+  const list = rotateFromRandomIndex(compatible.length ? compatible : names, rng);
   let choice = names[0];
   if (fileProvider && config) {
     for (const candidate of list) {
@@ -105,7 +174,7 @@ const pickProcgenStyle = async (fileProvider, config) => {
       }
     }
   } else {
-    choice = list[Math.floor(Math.random() * list.length)] || names[0];
+    choice = list[Math.floor(rng() * list.length)] || names[0];
   }
   try {
     window.localStorage?.setItem('procgen.style', choice);
@@ -115,6 +184,53 @@ const pickProcgenStyle = async (fileProvider, config) => {
   return choice;
 };
 
+const resolveProcgenSeed = (params) => {
+  const requestedSeed = params?.get?.(PROCGEN_SEED_PARAM);
+  if (requestedSeed != null && requestedSeed !== '') {
+    return normalizeSeed(requestedSeed);
+  }
+  let storedSeed = null;
+  try {
+    storedSeed = window.localStorage?.getItem(PROCGEN_SEED_STORAGE_KEY) || null;
+  } catch {
+    storedSeed = null;
+  }
+  if (storedSeed != null && storedSeed !== '') {
+    return normalizeSeed(storedSeed);
+  }
+  return normalizeSeed(Date.now());
+};
+
+const readFiniteQueryOption = (params, name) => {
+  if (!params?.has?.(name)) return null;
+  const value = Number(params.get(name));
+  return Number.isFinite(value) ? value : null;
+};
+
+const readBooleanQueryOption = (params, name) => {
+  if (!params?.has?.(name)) return null;
+  const value = String(params.get(name) ?? '').trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on', ''].includes(value)) return true;
+  if (['0', 'false', 'no', 'off'].includes(value)) return false;
+  return null;
+};
+
+const buildProcgenControllerOptions = (params, baseOptions = {}) => {
+  const options = { ...baseOptions };
+  for (const name of [
+    'gapChance',
+    'gapMinWidth',
+    'gapMaxWidth',
+    'recentCertificateLimit'
+  ]) {
+    const value = readFiniteQueryOption(params, name);
+    if (value != null) options[name] = value;
+  }
+  const verify = readBooleanQueryOption(params, 'procgenCertificateVerification');
+  if (verify != null) options.procgenCertificateVerification = verify;
+  return options;
+};
+
 const buildProcgenEditorLevel = (styleName) => {
   const level = new EditorLevel();
   level.setHeader('TITLE', 'Procgen');
@@ -138,115 +254,212 @@ const buildProcgenEditorLevel = (styleName) => {
 };
 
 const init = async () => {
+  disposeProcgenRuntime();
+  analytics = createAnalyticsService({
+    window,
+    document,
+    navigator: window?.navigator || null,
+    location: window?.location || null,
+    localStorage: window?.localStorage || null,
+    profile: 'perf',
+    surface: 'procgen'
+  });
+  analytics.installWindowApi(window);
+  analytics.trackPageView({
+    surface: 'procgen',
+    profile: 'perf',
+    embedMode: false
+  });
+  const runtime = {
+    view: null,
+    game: null,
+    controller: null,
+    stageAdapter: null,
+    focusBlurCleanup: null
+  };
   const canvas = document.getElementById('gameCanvas');
   if (!canvas) return;
-  const params = new URLSearchParams(window.location.search);
-  const aiDebugOverlay = params.has('aiDebug');
-  const view = new GameView();
-  view.gameType = PROCGEN_GAME_TYPE;
-  view.levelGroupIndex = 0;
-  view.levelIndex = 0;
-  view.midiEnabled = false;
-  view.includeSavedLevels = false;
-  view.endless = true;
-  view.gameCanvas = canvas;
-  view.gameSpeedFactor = 3;
-  if (view.stage) {
-    view.stage.setGuiEnabled(false);
-    view.stage.setCursorSprite(null);
-    view.stage.hudMargin = 0;
-  }
-
-  const config = await view.gameFactory.getConfig(PROCGEN_GAME_TYPE);
-  const resources = await view.gameFactory.getGameResources(PROCGEN_GAME_TYPE);
-  view.gameResources = resources;
-
-  const styleName = await pickProcgenStyle(
-    view.gameFactory.fileProvider,
-    config
-  );
-  const { level: editorLevel, entranceX, entranceY } = buildProcgenEditorLevel(styleName);
-  const level = await loadEditorLevel(
-    editorLevel,
-    config,
-    view.gameFactory.fileProvider,
-    {
-      styleName,
-      levelGroupIndex: 0,
-      levelIndex: 0
+  activeProcgenRuntime = runtime;
+  try {
+    const params = new URLSearchParams(window.location.search);
+    const procgenSeed = resolveProcgenSeed(params);
+    const styleRng = createSeededRandom(deriveSeed(procgenSeed, 'style'));
+    const terrainRng = createSeededRandom(deriveSeed(procgenSeed, 'terrain'));
+    window.procgenSeed = procgenSeed;
+    try {
+      window.localStorage?.setItem(PROCGEN_SEED_STORAGE_KEY, String(procgenSeed));
+    } catch {
+      // ignore storage failures
     }
-  );
-  if (!level) return;
-
-  const game = await view.gameFactory.getGame(PROCGEN_GAME_TYPE, resources);
-  await game.loadCustomLevel(level, { levelGroupIndex: 0, levelIndex: 0 });
-  game.setGameDisplay(view.stage.getGameDisplay());
-  view.game = game;
-  view.applyLevelViewport(level);
-  view.stage.updateStageSize();
-  game.start();
-  game.getGameTimer().speedFactor = view.gameSpeedFactor;
-  bindCanvasFocusBlur(canvas);
-
-  const assetManager = new ProcgenAssetManager({
-    styleName,
-    config,
-    fileProvider: view.gameFactory.fileProvider
-  });
-  await assetManager.load();
-  const stamper = new ProcgenTerrainStamper(level);
-
-  const controller = new ProcgenController({
-    view,
-    game,
-    level,
-    assets: assetManager,
-    stamper,
-    options: {
-      groundHeight: PROCGEN_GROUND_HEIGHT,
-      initialGroundWidth: PROCGEN_INITIAL_GROUND_WIDTH,
-      entranceX,
-      entranceY,
-      entranceClearance: PROCGEN_ENTRANCE_CLEARANCE,
-      aiDebugOverlay
+    const aiDebugOverlay = params.has('aiDebug');
+    const view = new GameView();
+    runtime.view = view;
+    view.gameType = PROCGEN_GAME_TYPE;
+    view.levelGroupIndex = 0;
+    view.levelIndex = 0;
+    view.midiEnabled = false;
+    view.includeSavedLevels = false;
+    view.endless = true;
+    view.gameCanvas = canvas;
+    view.gameSpeedFactor = 3;
+    if (view.stage) {
+      view.stage.setGuiEnabled(false);
+      view.stage.setCursorSprite(null);
+      view.stage.hudMargin = 0;
     }
-  });
-  controller.start();
 
-  const stageAdapter = new ProcgenStageAdapter({
-    view,
-    controller,
-    canvas
-  });
-  stageAdapter.install();
+    const config = await view.gameFactory.getConfig(PROCGEN_GAME_TYPE);
+    const resources = await view.gameFactory.getGameResources(PROCGEN_GAME_TYPE);
+    view.gameResources = resources;
 
-  installE2EHarness({ view });
-  registerServiceWorker();
+    const styleName = await pickProcgenStyle(
+      view.gameFactory.fileProvider,
+      config,
+      styleRng
+    );
+    const themeContract = buildProcgenThemeContract(styleName, config);
+    window.procgenSelectedTheme = themeContract.selectedTheme;
+    window.procgenThemeContract = themeContract;
+    const { level: editorLevel, entranceX, entranceY } = buildProcgenEditorLevel(styleName);
+    const level = await loadEditorLevel(
+      editorLevel,
+      config,
+      view.gameFactory.fileProvider,
+      {
+        styleName,
+        levelGroupIndex: 0,
+        levelIndex: 0
+      }
+    );
+    if (!level) {
+      runtime.view?.dispose?.();
+      return;
+    }
+
+    const game = await view.gameFactory.getGame(PROCGEN_GAME_TYPE, resources);
+    runtime.game = game;
+    await game.loadCustomLevel(level, { levelGroupIndex: 0, levelIndex: 0 });
+    game.setGameDisplay(view.stage.getGameDisplay());
+    view.game = game;
+    view.applyLevelViewport(level);
+    view.stage.updateStageSize();
+    game.start();
+    game.getGameTimer().speedFactor = view.gameSpeedFactor;
+    runtime.focusBlurCleanup = bindCanvasFocusBlur(canvas);
+
+    const assetManager = new ProcgenAssetManager({
+      styleName,
+      config,
+      fileProvider: view.gameFactory.fileProvider,
+      random: terrainRng
+    });
+    await assetManager.load();
+    const stamper = new ProcgenTerrainStamper(level);
+
+    const controller = new ProcgenController({
+      view,
+      game,
+      level,
+      assets: assetManager,
+      stamper,
+      options: buildProcgenControllerOptions(params, {
+        groundHeight: PROCGEN_GROUND_HEIGHT,
+        initialGroundWidth: PROCGEN_INITIAL_GROUND_WIDTH,
+        entranceX,
+        entranceY,
+        entranceClearance: PROCGEN_ENTRANCE_CLEARANCE,
+        aiDebugOverlay,
+        rng: terrainRng,
+        rngSeed: procgenSeed,
+        selectedTheme: themeContract.selectedTheme,
+        themeContract
+      })
+    });
+    controller.start();
+    runtime.controller = controller;
+    view.procgenController = controller;
+    window.procgenDebugState = () => controller.getDebugState();
+
+    const stageAdapter = new ProcgenStageAdapter({
+      view,
+      controller,
+      canvas
+    });
+    stageAdapter.install();
+    runtime.stageAdapter = stageAdapter;
+    stageAdapter.updateStageSize();
+
+    installE2EHarness({ view, procgenController: controller });
+    registerServiceWorker({ profile: 'perf' });
+  } catch (err) {
+    analytics?.track?.(ANALYTICS_EVENT_TYPES.RUNTIME_BOOT_ERROR, {
+      code: 'resource_error',
+      surface: 'procgen',
+      profile: 'perf',
+      embedMode: false
+    });
+    if (activeProcgenRuntime === runtime) {
+      activeProcgenRuntime = null;
+    }
+    runtime?.controller?.stop?.();
+    if (runtime?.view && runtime.view.procgenController === runtime?.controller) {
+      runtime.view.procgenController = null;
+    }
+    runtime?.stageAdapter?.dispose?.();
+    runtime?.game?.stop?.();
+    runtime?.view?.dispose?.();
+    runFocusBlurCleanup(runtime);
+    throw err;
+  }
 };
 
-const resizeCanvas = () => {
+const resizeCanvas = (runtime = activeProcgenRuntime) => {
   const canvas = document.getElementById('gameCanvas');
   if (!canvas) return;
-  const dpr = window.devicePixelRatio || 1;
-  const width = Math.max(1, window.innerWidth);
-  const height = Math.max(1, window.innerHeight);
+  const dprValue = Number(window?.devicePixelRatio);
+  const dpr = Number.isFinite(dprValue) && dprValue > 0 ? dprValue : 1;
+  const widthValue = Number(window?.innerWidth);
+  const heightValue = Number(window?.innerHeight);
+  const fallbackWidth = Number(canvas?.clientWidth);
+  const fallbackHeight = Number(canvas?.clientHeight);
+  const width = Number.isFinite(widthValue) && widthValue > 0
+    ? widthValue
+    : (Number.isFinite(fallbackWidth) && fallbackWidth > 0 ? fallbackWidth : 1);
+  const height = Number.isFinite(heightValue) && heightValue > 0
+    ? heightValue
+    : (Number.isFinite(fallbackHeight) && fallbackHeight > 0 ? fallbackHeight : 1);
   canvas.width = Math.floor(width * dpr);
   canvas.height = Math.floor(height * dpr);
   canvas.style.width = `${width}px`;
   canvas.style.height = `${height}px`;
-  if (window.lemmings?.stage) {
-    window.lemmings.stage.updateStageSize();
+  if (runtime?.stageAdapter?.updateStageSize) {
+    runtime.stageAdapter.updateStageSize();
+  } else {
+    runtime?.view?.stage?.updateStageSize?.();
   }
 };
 
-window.addEventListener('resize', resizeCanvas);
+const shouldAutoBoot = () => (
+  typeof window !== 'undefined' &&
+  globalThis?.__LEMMINGS_PROCGEN_NO_AUTO_BOOT__ !== true
+);
 
-if (document.readyState === 'loading') {
-  document.addEventListener('DOMContentLoaded', () => {
-    resizeCanvas();
-    init();
-  });
-} else {
-  resizeCanvas();
-  init();
+if (shouldAutoBoot()) {
+  installProcgenBootListeners();
 }
+
+export {
+  getProcgenGroundSets,
+  getCompatibleProcgenStyleNames,
+  buildProcgenThemeContract,
+  pickProcgenStyle,
+  resolveProcgenSeed,
+  buildProcgenControllerOptions,
+  buildProcgenEditorLevel,
+  init,
+  resizeCanvas,
+  disposeProcgenRuntime,
+  installProcgenBootListeners,
+  disposeProcgenBootListeners,
+  setActiveProcgenRuntimeForTest
+};
diff --git a/js/app/procgenController.js b/js/app/procgenController.js
index 396950c5..8dc3eb88 100644
--- a/js/app/procgenController.js
+++ b/js/app/procgenController.js
@@ -1,1272 +1 @@
-import { Lemming } from '../lemmings/Lemming.js';
-import { SkillTypes } from '../game/SkillTypes.js';
-import { SoundEventTypes } from '../game/SoundEvents.js';
-import { TriggerTypes } from '../level/TriggerTypes.js';
-
-class ProcgenController {
-  constructor({ view, game, level, assets, stamper, options = {} }) {
-    this.view = view || null;
-    this.game = game || null;
-    this.level = level || null;
-    this.window = options.window || globalThis?.window;
-    this.assets = assets || null;
-    this.stamper = stamper || null;
-    this._tickHandler = null;
-    this._running = false;
-    this._cameraX = 0;
-    this._groundEndX = 0;
-    this._groundTopY = 0;
-    this._segmentColorIndex = 0;
-    this._colorTransition = {
-      from: 1,
-      to: 1,
-      remaining: 0,
-      total: 0,
-      current: 1,
-      step: 0
-    };
-    this._sustainBaseY = 0;
-    this._sustainRemaining = 0;
-    this._builderCursorId = 0;
-    this._seenFalls = new Set();
-    this._soundHandler = null;
-    this._builderBurst = null;
-    this._cameraTargetX = null;
-    this._lastSecond = null;
-    this._bombCheckElapsed = 0;
-    this._bombChance = 0.0001;
-    this._nukeElapsed = 0;
-    this._terrainPlan = { mode: 'flat', remaining: 0 };
-    this._pendingDrop = false;
-    this._gaps = [];
-    this._gapCooldown = 0;
-    this._structurePlan = null;
-    this._aiLastDecisionTick = 0;
-    this._aiDecisionInterval = 3;
-    this._aiBudget = null;
-    this._aiBudgetMax = null;
-    this._aiBudgetRegen = null;
-    this._aiLastDecision = null;
-    this._aiDebug = null;
-    this._aiLemmingCooldown = new Map();
-    this._aiStallState = new Map();
-    this._leftFallCounter = 0;
-    this._splatStreak = 0;
-    this._splatTarget = this._randInt(3, 10);
-    this._pendingMidairBuilder = null;
-    this._recentDecor = [];
-
-    this.groundHeight = Number.isFinite(options.groundHeight) ? options.groundHeight : 4;
-    this.groundColorIndex = Number.isFinite(options.groundColorIndex) ? options.groundColorIndex : 1;
-    this.initialGroundWidth = Number.isFinite(options.initialGroundWidth) ? options.initialGroundWidth : 120;
-    this.segmentMinWidth = Number.isFinite(options.segmentMinWidth) ? options.segmentMinWidth : 2;
-    this.segmentMaxWidth = Number.isFinite(options.segmentMaxWidth) ? options.segmentMaxWidth : 6;
-    this.extendThreshold = Number.isFinite(options.extendThreshold) ? options.extendThreshold : 4;
-    this.lookAhead = Number.isFinite(options.lookAhead) ? options.lookAhead : 20;
-    this.followLerp = Number.isFinite(options.followLerp) ? options.followLerp : 0.12;
-    this.maxStepUp = Number.isFinite(options.maxStepUp) ? options.maxStepUp : 3;
-    this.maxDrop = Number.isFinite(options.maxDrop) ? options.maxDrop : (Lemming.LEM_MAX_FALLING - 1);
-    this.gapChance = Number.isFinite(options.gapChance) ? options.gapChance : 0.08;
-    this.gapMinWidth = Number.isFinite(options.gapMinWidth) ? options.gapMinWidth : 3;
-    this.gapMaxWidth = Number.isFinite(options.gapMaxWidth) ? options.gapMaxWidth : 9;
-    this.gapTriggerDistance = Number.isFinite(options.gapTriggerDistance) ? options.gapTriggerDistance : 10;
-    this.decorChance = Number.isFinite(options.decorChance) ? options.decorChance : 0.12;
-    this.aiDecisionInterval = Number.isFinite(options.aiDecisionInterval) ? options.aiDecisionInterval : 3;
-    this.aiScanAhead = Number.isFinite(options.aiScanAhead) ? options.aiScanAhead : 24;
-    this.aiWallHeight = Number.isFinite(options.aiWallHeight) ? options.aiWallHeight : 10;
-    this.aiHazardDistance = Number.isFinite(options.aiHazardDistance) ? options.aiHazardDistance : 18;
-    this.aiFloaterDrop = Number.isFinite(options.aiFloaterDrop) ? options.aiFloaterDrop : (Lemming.LEM_MAX_FALLING - 2);
-    this.aiDebugOverlay = options.aiDebugOverlay === true;
-    this.aiActionCooldown = Number.isFinite(options.aiActionCooldown) ? options.aiActionCooldown : 5;
-    this.entranceX = Number.isFinite(options.entranceX) ? options.entranceX : null;
-    this.entranceY = Number.isFinite(options.entranceY) ? options.entranceY : null;
-    this.entranceClearance = Number.isFinite(options.entranceClearance) ? options.entranceClearance : 24;
-  }
-
-  start() {
-    if (this._running) return;
-    if (!this.game || !this.level) return;
-    this._running = true;
-    this._initGround();
-    this._initAiDirector();
-    if (this.aiDebugOverlay) {
-      this._initDebugOverlay();
-    }
-    const stage = this.view?.stage || null;
-    if (stage?.gameImgProps?.viewPoint) {
-      this._cameraX = stage.gameImgProps.viewPoint.x || 0;
-    }
-    this._bindTimer();
-    this._bindSoundEvents();
-  }
-
-  stop() {
-    if (!this._running) return;
-    this._running = false;
-    this._unbindTimer();
-    this._unbindSoundEvents();
-  }
-
-  _bindTimer() {
-    const timer = this.game?.getGameTimer?.();
-    if (!timer?.onGameTick?.on) return;
-    this._tickHandler = () => this._onTick();
-    timer.onGameTick.on(this._tickHandler);
-  }
-
-  _unbindTimer() {
-    const timer = this.game?.getGameTimer?.();
-    if (!timer?.onGameTick?.off || !this._tickHandler) return;
-    timer.onGameTick.off(this._tickHandler);
-    this._tickHandler = null;
-  }
-
-  _bindSoundEvents() {
-    if (this._soundHandler) return;
-    const bus = this.game?.soundEvents;
-    if (!bus?.onEvent?.on) return;
-    this._soundHandler = event => {
-      if (event?.type !== SoundEventTypes.LEMMING_FELL_OFF &&
-          event?.type !== SoundEventTypes.LEMMING_SPLAT) {
-        return;
-      }
-      const lemmingId = event?.lemmingId;
-      if (this._seenFalls.has(lemmingId)) return;
-      this._seenFalls.add(lemmingId);
-      if (event?.type === SoundEventTypes.LEMMING_SPLAT) {
-        this._splatStreak += 1;
-        if (this._splatStreak >= this._splatTarget && !this._pendingMidairBuilder) {
-          this._pendingMidairBuilder = {
-            delay: this._randInt(4, 12),
-            dueTick: null,
-            targetId: null
-          };
-          this._splatStreak = 0;
-          this._splatTarget = this._randInt(3, 10);
-        }
-      } else {
-        this._splatStreak = 0;
-      }
-      const originX = Number.isFinite(event?.x) ? event.x : null;
-      const manager = this.game?.getLemmingManager?.();
-      const lem = Number.isFinite(lemmingId) ? manager?.getLemming?.(lemmingId) : null;
-      const fellLeft = lem ? !lem.lookRight : false;
-      if (fellLeft) {
-        this._leftFallCounter += 1;
-        const isBuilder = this._leftFallCounter % 20 === 0;
-        this._scheduleEdgeResponse(originX, isBuilder ? 'builder-left' : 'blocker');
-      } else {
-        this._scheduleBuilderBurst(originX);
-      }
-    };
-    bus.onEvent.on(this._soundHandler);
-  }
-
-  _unbindSoundEvents() {
-    const bus = this.game?.soundEvents;
-    if (bus?.onEvent?.off && this._soundHandler) {
-      bus.onEvent.off(this._soundHandler);
-    }
-    this._soundHandler = null;
-  }
-
-  _initGround() {
-    const entrance = this.level?.entrances?.[0] || null;
-    const entranceX = Number.isFinite(entrance?.x) ? entrance.x : 0;
-    const startX = Math.max(0, entranceX - Math.floor(this.initialGroundWidth / 4));
-    this._groundTopY = Math.max(0, (this.level?.height ?? 0) - this.groundHeight);
-    this._segmentColorIndex = this.groundColorIndex;
-    this._colorTransition = {
-      from: this._segmentColorIndex,
-      to: this._segmentColorIndex,
-      remaining: 0,
-      total: 0,
-      current: this._segmentColorIndex,
-      step: 0
-    };
-    this._sustainBaseY = this._groundTopY;
-    this._sustainRemaining = 0;
-    this._paintGround(startX, this.initialGroundWidth, this._groundTopY, this._segmentColorIndex);
-    this._groundEndX = Math.max(this._groundEndX, startX + this.initialGroundWidth);
-  }
-
-  _onTick() {
-    if (!this._running) return;
-    this._updateTimers();
-    const follow = this._getFollowLemming();
-    const followX = Number.isFinite(follow?.x) ? follow.x : null;
-    const guideX = Number.isFinite(followX) ? followX : this._getRightmostX();
-    if (!Number.isFinite(guideX)) return;
-    this._ensureGround(guideX);
-    this._processBuilderBurst();
-    this._processGapBridges();
-    this._processMidairBuilder();
-    this._updateAiDirector();
-    this._updateCamera(Number.isFinite(followX) ? followX : guideX);
-  }
-
-  _updateTimers() {
-    const timer = this.game?.getGameTimer?.();
-    const tick = timer?.getGameTicks?.() ?? timer?.tickIndex ?? null;
-    if (!Number.isFinite(tick)) return;
-    const seconds = Math.floor(tick / 17.5);
-    if (this._lastSecond == null) {
-      this._lastSecond = seconds;
-      return;
-    }
-    if (seconds <= this._lastSecond) return;
-    const delta = seconds - this._lastSecond;
-    this._lastSecond = seconds;
-    this._bombCheckElapsed += delta;
-    this._nukeElapsed += delta;
-    this._updateAiBudget(delta);
-    this._maybeTriggerBomber();
-    this._maybeTriggerNuke();
-  }
-
-  _initAiDirector() {
-    this._aiDecisionInterval = Math.max(1, Math.floor(this.aiDecisionInterval));
-    this._aiBudgetMax = {
-      builder: 14,
-      floater: 10,
-      bash: 8,
-      mine: 5,
-      dig: 6,
-      blocker: 6
-    };
-    this._aiBudget = {
-      builder: 10,
-      floater: 8,
-      bash: 6,
-      mine: 4,
-      dig: 5,
-      blocker: 5
-    };
-    this._aiBudgetRegen = {
-      builder: 2.2,
-      floater: 1.4,
-      bash: 1.1,
-      mine: 0.7,
-      dig: 0.9,
-      blocker: 0.8
-    };
-  }
-
-  _updateAiBudget(deltaSeconds) {
-    if (!this._aiBudget || !this._aiBudgetMax || !this._aiBudgetRegen) return;
-    const delta = Math.max(0, deltaSeconds);
-    for (const key of Object.keys(this._aiBudget)) {
-      const next = this._aiBudget[key] + this._aiBudgetRegen[key] * delta;
-      this._aiBudget[key] = Math.min(this._aiBudgetMax[key], next);
-    }
-  }
-
-  _updateAiDirector() {
-    const timer = this.game?.getGameTimer?.();
-    const tick = timer?.getGameTicks?.() ?? timer?.tickIndex ?? 0;
-    if (!Number.isFinite(tick)) return;
-    if (tick - this._aiLastDecisionTick < this._aiDecisionInterval) return;
-    this._aiLastDecisionTick = tick;
-
-    this._applyEdgeBlockers(tick);
-    this._applyBunchingAssist(tick);
-
-    const lemming = this._getFollowLemming();
-    if (!lemming) return;
-    if (this._shouldSkipAiFor(lemming, tick)) return;
-    const scan = this._scanAhead(lemming);
-    const action = this._decideAssist(lemming, scan, tick);
-    if (action) {
-      this._aiLastDecision = { tick, action, scan };
-    } else if (this._aiLastDecision && this._aiLastDecision.tick !== tick) {
-      this._aiLastDecision = { tick, action: null, scan };
-    }
-    this._updateDebugOverlay();
-  }
-
-  _applyEdgeBlockers(tick) {
-    const manager = this.game?.getLemmingManager?.();
-    const lems = manager?.lemmings || [];
-    if (!lems.length) return;
-    const ground = this.level?.groundMask;
-    if (!ground) return;
-    for (const lem of lems) {
-      if (!lem || lem.removed || lem.disabled || lem.lookRight) continue;
-      const actionName = lem.action?.getActionName?.() || '';
-      if (actionName && actionName !== 'walking') continue;
-      if (this._shouldSkipAiFor(lem, tick)) continue;
-      const x = Number.isFinite(lem.x) ? Math.floor(lem.x) : null;
-      const y = Number.isFinite(lem.y) ? Math.floor(lem.y) : null;
-      if (!Number.isFinite(x) || !Number.isFinite(y)) continue;
-      const nearLeftEdge = x <= 2;
-      const drop = this._getDropAt(ground, x - 1, y, this.maxDrop);
-      if ((nearLeftEdge || drop > 0) && this._canSpend('blocker')) {
-        if (manager.doLemmingAction(lem, SkillTypes.BLOCKER)) {
-          this._noteAiAction(lem, tick, 32);
-          return;
-        }
-        this._refundBudget('blocker');
-      }
-    }
-  }
-
-  _applyBunchingAssist(tick) {
-    const manager = this.game?.getLemmingManager?.();
-    const lems = manager?.lemmings || [];
-    if (!lems.length) return;
-    const levelHeight = this.level?.height ?? 0;
-    for (const lem of lems) {
-      if (!lem || lem.removed || lem.disabled) continue;
-      const actionName = lem.action?.getActionName?.() || '';
-      if (actionName && actionName !== 'walking') continue;
-      if (this._shouldSkipAiFor(lem, tick)) continue;
-      const key = lem.id;
-      const prev = this._aiStallState.get(key) || {
-        lastX: lem.x,
-        lastDir: lem.lookRight,
-        stallTicks: 0,
-        flipCount: 0
-      };
-      const deltaX = Math.abs((lem.x ?? 0) - (prev.lastX ?? 0));
-      const sameDir = prev.lastDir === lem.lookRight;
-      let stallTicks = prev.stallTicks;
-      let flipCount = prev.flipCount;
-      if (deltaX < 0.5) {
-        stallTicks += 1;
-      } else {
-        stallTicks = Math.max(0, stallTicks - 1);
-      }
-      if (!sameDir && deltaX < 6) {
-        flipCount += 1;
-      } else if (deltaX > 2) {
-        flipCount = Math.max(0, flipCount - 1);
-      }
-
-      const stuck = stallTicks >= 18 || flipCount >= 3;
-      if (stuck) {
-        const highEnough = levelHeight > 0 && (lem.y ?? 0) < levelHeight * 0.6;
-        const attempts = [];
-        attempts.push({ skill: SkillTypes.BASHER, key: 'bash', cooldown: 32 });
-        attempts.push({ skill: SkillTypes.BUILDER, key: 'builder', cooldown: 36 });
-        if (highEnough) {
-          attempts.push({ skill: SkillTypes.DIGGER, key: 'dig', cooldown: 36 });
-          attempts.push({ skill: SkillTypes.MINER, key: 'mine', cooldown: 36 });
-        }
-        for (const option of attempts) {
-          if (!this._canSpend(option.key)) continue;
-          if (manager.doLemmingAction(lem, option.skill)) {
-            this._noteAiAction(lem, tick, option.cooldown);
-            stallTicks = 0;
-            flipCount = 0;
-            break;
-          }
-          this._refundBudget(option.key);
-        }
-      }
-
-      this._aiStallState.set(key, {
-        lastX: lem.x,
-        lastDir: lem.lookRight,
-        stallTicks,
-        flipCount
-      });
-    }
-  }
-
-  _scanAhead(lemming) {
-    const ground = this.level?.groundMask;
-    if (!ground) return null;
-    const x0 = Math.floor(lemming.x);
-    const y0 = Math.floor(lemming.y);
-    const scanAhead = Math.max(6, Math.floor(this.aiScanAhead));
-    const levelHeight = this.level?.height ?? 0;
-    const maxDrop = Math.min(this.maxDrop, levelHeight);
-    const dir = lemming.lookRight ? 1 : -1;
-    let gap = null;
-    let wall = null;
-    for (let dx = 1; dx <= scanAhead; dx++) {
-      const testX = x0 + dx * dir;
-      const drop = this._getDropAt(ground, testX, y0, maxDrop);
-      if (drop > 0 && !gap) {
-        const gapWidth = this._measureGapWidth(ground, testX, y0, scanAhead, dir);
-        gap = { dx, drop, width: gapWidth };
-      }
-      const wallHeight = this._getWallHeight(ground, testX, y0, this.aiWallHeight, dir);
-      if (wallHeight > 0 && !wall) {
-        wall = { dx, height: wallHeight };
-      }
-      if (gap && wall) break;
-    }
-    const hazard = this._findHazardAhead(x0, y0, scanAhead, dir);
-    return { gap, wall, hazard, direction: dir };
-  }
-
-  _getDropAt(ground, x, y, maxDrop) {
-    const height = this.level?.height ?? 0;
-    const top = y + 1;
-    if (top < 0 || top >= height) return 0;
-    const available = Math.max(1, Math.min(maxDrop + 2, height - top));
-    const depth = ground.getColumnGapDepth(x, top, available);
-    if (depth <= 1) return 0;
-    return depth - 1;
-  }
-
-  _measureGapWidth(ground, startX, y, scanAhead, dir) {
-    let width = 0;
-    for (let dx = 0; dx <= scanAhead; dx++) {
-      const drop = this._getDropAt(ground, startX + dx * dir, y, this.maxDrop);
-      if (drop <= 0) break;
-      width += 1;
-      if (width >= scanAhead) break;
-    }
-    return width;
-  }
-
-  _getWallHeight(ground, x, y, maxHeight, dir) {
-    const height = Math.max(1, Math.floor(maxHeight));
-    let wall = 0;
-    for (let dy = 1; dy <= height; dy++) {
-      if (ground.hasGroundAt(x, y - dy)) wall = dy;
-    }
-    return wall;
-  }
-
-  _findHazardAhead(x, y, scanAhead, dir) {
-    const triggers = this.level?.triggers;
-    if (!Array.isArray(triggers) || triggers.length === 0) return null;
-    const hazardSet = new Set([
-      TriggerTypes.TRAP,
-      TriggerTypes.DROWN,
-      TriggerTypes.KILL,
-      TriggerTypes.FRYING
-    ]);
-    const maxDx = Math.max(1, Math.floor(scanAhead));
-    for (let dx = 1; dx <= maxDx; dx++) {
-      const px = x + dx * dir;
-      for (const trigger of triggers) {
-        if (!trigger || !hazardSet.has(trigger.type)) continue;
-        if (px >= trigger.x1 && px <= trigger.x2 && y >= trigger.y1 && y <= trigger.y2) {
-          return { dx, type: trigger.type };
-        }
-      }
-    }
-    return null;
-  }
-
-  _decideAssist(lemming, scan, tick) {
-    if (!scan) return null;
-    const manager = this.game?.getLemmingManager?.();
-    if (!manager) return null;
-    const actionName = lemming.action?.getActionName?.() || '';
-    if (actionName && actionName !== 'walking') return null;
-    const skillOrder = [];
-    if (scan.direction === -1 && scan.gap && scan.gap.dx <= 2) {
-      skillOrder.push({ skill: SkillTypes.BLOCKER, key: 'blocker', cooldown: 40 });
-    }
-    if (scan.hazard && scan.hazard.dx <= this.aiHazardDistance) {
-      skillOrder.push({ skill: SkillTypes.BLOCKER, key: 'blocker' });
-    }
-    if (scan.gap && scan.gap.width >= 2 && scan.gap.width <= 8) {
-      skillOrder.push({ skill: SkillTypes.BUILDER, key: 'builder', cooldown: 48 });
-    }
-    if (scan.gap && scan.gap.drop >= this.aiFloaterDrop) {
-      skillOrder.push({ skill: SkillTypes.FLOATER, key: 'floater' });
-    }
-    if (scan.wall && scan.wall.height >= 6) {
-      skillOrder.push({ skill: SkillTypes.BASHER, key: 'bash' });
-      skillOrder.push({ skill: SkillTypes.DIGGER, key: 'dig' });
-      if (scan.wall.height >= this.aiWallHeight + 4 || Math.random() < 0.15) {
-        skillOrder.push({ skill: SkillTypes.MINER, key: 'mine' });
-      }
-    }
-    if (!skillOrder.length) return null;
-    for (const option of skillOrder) {
-      if (!this._canSpend(option.key)) continue;
-      if (manager.doLemmingAction(lemming, option.skill)) {
-        this._noteAiAction(lemming, tick, option.cooldown);
-        return option.key;
-      }
-      this._refundBudget(option.key);
-    }
-    return null;
-  }
-
-  _shouldSkipAiFor(lemming, tick) {
-    if (!lemming || !Number.isFinite(tick)) return true;
-    const last = this._aiLemmingCooldown.get(lemming.id);
-    if (Number.isFinite(last) && tick < last) return true;
-    return false;
-  }
-
-  _noteAiAction(lemming, tick, extraCooldown = 0) {
-    const cooldown = Math.max(this.aiActionCooldown, extraCooldown || 0);
-    this._aiLemmingCooldown.set(lemming.id, tick + cooldown);
-  }
-
-  _canSpend(key) {
-    if (!this._aiBudget || !this._aiBudgetMax) return false;
-    if (!Object.prototype.hasOwnProperty.call(this._aiBudget, key)) return false;
-    if (this._aiBudget[key] < 1) return false;
-    this._aiBudget[key] -= 1;
-    return true;
-  }
-
-  _refundBudget(key) {
-    if (!this._aiBudget || !this._aiBudgetMax) return;
-    if (!Object.prototype.hasOwnProperty.call(this._aiBudget, key)) return;
-    this._aiBudget[key] = Math.min(this._aiBudgetMax[key], this._aiBudget[key] + 1);
-  }
-
-  _maybeTriggerBomber() {
-    if (this._bombCheckElapsed < 30) return;
-    if (Math.random() < this._bombChance) {
-      const manager = this.game?.getLemmingManager?.();
-      const lems = manager?.activeLemmings || manager?.lemmings || [];
-      let best = null;
-      let bestX = -Infinity;
-      for (const lem of lems) {
-        if (!lem || lem.removed || lem.disabled) continue;
-        if (lem.x > bestX) {
-          bestX = lem.x;
-          best = lem;
-        }
-      }
-      if (best && manager?.doLemmingAction?.(best, SkillTypes.BOMBER)) {
-        this._bombCheckElapsed = 0;
-        this._bombChance = 0.01;
-        return;
-      }
-    }
-    if (this._bombCheckElapsed >= 10) {
-      this._bombCheckElapsed = 0;
-      this._bombChance = Math.min(1, this._bombChance * 2);
-    }
-  }
-
-  _maybeTriggerNuke() {
-    if (this._nukeElapsed < 60) return;
-    if (Math.random() < 0.001) {
-      const manager = this.game?.getLemmingManager?.();
-      manager?.doNukeAllLemmings?.();
-    }
-    this._nukeElapsed = 0;
-  }
-
-  _getFollowLemming() {
-    const manager = this.game?.getLemmingManager?.();
-    const first = manager?.getLemming?.(0);
-    if (first && Number.isFinite(first.x) && first.lookRight) return first;
-    const lems = manager?.activeLemmings || manager?.lemmings || [];
-    for (const lem of lems) {
-      if (!lem || lem.removed || lem.disabled || !lem.lookRight) continue;
-      return lem;
-    }
-    return null;
-  }
-
-  getGroundExtentX() {
-    return Math.max(1, Math.floor(this._groundEndX || 0));
-  }
-
-  _getRightmostX() {
-    const manager = this.game?.getLemmingManager?.();
-    const lems = manager?.activeLemmings || manager?.lemmings || [];
-    let max = null;
-    for (const lem of lems) {
-      if (!lem || lem.removed || lem.disabled || !lem.lookRight) continue;
-      if (max == null || lem.x > max) max = lem.x;
-    }
-    if (max == null) {
-      const entrance = this.level?.entrances?.[0] || null;
-      return Number.isFinite(entrance?.x) ? entrance.x : null;
-    }
-    return max;
-  }
-
-  _scheduleBuilderBurst(originX) {
-    const timer = this.game?.getGameTimer?.();
-    const tick = timer?.getGameTicks?.() ?? timer?.tickIndex ?? 0;
-    this._builderBurst = {
-      remaining: this._randInt(1, 5),
-      nextDelay: this._randInt(10, 20),
-      dueTick: 0,
-      originX: Number.isFinite(originX) ? originX : null,
-      edgeX: Number.isFinite(originX) ? originX : null,
-      edgeAction: null,
-      used: new Set()
-    };
-    this._builderBurst.dueTick = tick + this._builderBurst.nextDelay;
-  }
-
-  _scheduleEdgeResponse(edgeX, edgeAction) {
-    const timer = this.game?.getGameTimer?.();
-    const tick = timer?.getGameTicks?.() ?? timer?.tickIndex ?? 0;
-    this._builderBurst = {
-      remaining: 1,
-      nextDelay: this._randInt(6, 14),
-      dueTick: tick + this._randInt(6, 14),
-      originX: Number.isFinite(edgeX) ? edgeX : null,
-      edgeX: Number.isFinite(edgeX) ? edgeX : null,
-      edgeAction: edgeAction || 'blocker',
-      used: new Set()
-    };
-  }
-
-  _processBuilderBurst() {
-    const burst = this._builderBurst;
-    if (!burst || burst.remaining <= 0) return;
-    const timer = this.game?.getGameTimer?.();
-    const tick = timer?.getGameTicks?.() ?? timer?.tickIndex ?? 0;
-    if (burst.dueTick > tick) return;
-    if (burst.edgeAction) {
-      const handled = this._applyEdgeResponse(burst, tick);
-      burst.remaining -= handled ? 1 : 0;
-      if (burst.remaining <= 0) {
-        this._builderBurst = null;
-      } else {
-        burst.dueTick = tick + burst.nextDelay;
-      }
-      return;
-    }
-    const applied = this._applyBuilderToNextLemming(burst);
-    if (applied) {
-      burst.remaining -= 1;
-      if (burst.remaining <= 0) {
-        this._builderBurst = null;
-        return;
-      }
-      burst.nextDelay = Math.round(burst.nextDelay * 2) + this._randInt(1, 5);
-    }
-    burst.dueTick = tick + burst.nextDelay;
-  }
-
-  _applyEdgeResponse(burst, tick) {
-    const manager = this.game?.getLemmingManager?.();
-    const lems = manager?.lemmings || [];
-    if (!lems.length || !Number.isFinite(burst.edgeX)) return false;
-    const edgeX = burst.edgeX + (burst.edgeAction === 'blocker' ? 2 : 0);
-    let best = null;
-    let bestDist = Infinity;
-    for (const lem of lems) {
-      if (!lem || lem.removed || lem.disabled) continue;
-      const actionName = lem.action?.getActionName?.() || '';
-      if (actionName && actionName !== 'walking') continue;
-      if (burst.edgeAction === 'builder-left' && lem.lookRight) continue;
-      if (burst.edgeAction === 'blocker' && lem.lookRight) continue;
-      const dist = Math.abs((lem.x ?? 0) - edgeX);
-      if (dist < bestDist) {
-        bestDist = dist;
-        best = lem;
-      }
-    }
-    if (!best) return false;
-    const skill = burst.edgeAction === 'builder-left' ? SkillTypes.BUILDER : SkillTypes.BLOCKER;
-    const key = burst.edgeAction === 'builder-left' ? 'builder' : 'blocker';
-    if (!this._canSpend(key)) return false;
-    if (manager.doLemmingAction(best, skill)) {
-      this._noteAiAction(best, tick, burst.edgeAction === 'builder-left' ? 48 : 32);
-      return true;
-    }
-    this._refundBudget(key);
-    return false;
-  }
-
-  _processGapBridges() {
-    if (!this._gaps.length) return;
-    const manager = this.game?.getLemmingManager?.();
-    const lems = manager?.lemmings || [];
-    if (!lems.length) return;
-    const follow = this._getFollowLemming();
-    const leadId = follow?.id ?? null;
-    const leadX = Number.isFinite(follow?.x) ? follow.x : null;
-    for (const gap of this._gaps) {
-      if (!gap || gap.assigned) continue;
-      if (!Number.isFinite(gap.x) || !Number.isFinite(gap.width)) continue;
-      const triggerX = gap.x - this.gapTriggerDistance;
-      if (Number.isFinite(leadX) && leadX < triggerX) continue;
-      let best = null;
-      let bestDist = Infinity;
-      for (const lem of lems) {
-        if (!lem || lem.removed || lem.disabled || !lem.lookRight) continue;
-        const actionName = lem.action?.getActionName?.() || '';
-        if (actionName && actionName !== 'walking') continue;
-        const dist = Math.abs((lem.x ?? 0) - gap.x);
-        if (dist < bestDist) {
-          bestDist = dist;
-          best = lem;
-        }
-      }
-      if (!best) continue;
-      if (leadId != null && best.id !== leadId && Number.isFinite(leadX)) {
-        if (best.x < leadX - 8) continue;
-      }
-      if (manager.doLemmingAction(best, SkillTypes.BUILDER)) {
-        const timer = this.game?.getGameTimer?.();
-        const tick = timer?.getGameTicks?.() ?? timer?.tickIndex ?? 0;
-        this._noteAiAction(best, tick, 48);
-        gap.assigned = true;
-      }
-    }
-    const cutoff = Number.isFinite(this._cameraX) ? this._cameraX - 200 : null;
-    this._gaps = this._gaps.filter(gap => {
-      if (!gap) return false;
-      if (!gap.assigned) return true;
-      if (cutoff == null) return false;
-      return gap.x + gap.width > cutoff;
-    });
-  }
-
-  _processMidairBuilder() {
-    const pending = this._pendingMidairBuilder;
-    if (!pending) return;
-    const manager = this.game?.getLemmingManager?.();
-    const lems = manager?.lemmings || [];
-    if (!lems.length) return;
-    const timer = this.game?.getGameTimer?.();
-    const tick = timer?.getGameTicks?.() ?? timer?.tickIndex ?? 0;
-    const ground = this.level?.groundMask;
-    const levelHeight = this.level?.height ?? 0;
-    const maxDrop = Math.min(this.maxDrop, levelHeight);
-    let target = null;
-
-    if (Number.isFinite(pending.targetId)) {
-      target = manager?.getLemming?.(pending.targetId) || null;
-      const actionName = target?.action?.getActionName?.() || '';
-      if (!target || target.removed || target.disabled || actionName !== 'falling') {
-        pending.targetId = null;
-        pending.dueTick = null;
-        target = null;
-      }
-    }
-
-    if (!target) {
-      for (const lem of lems) {
-        if (!lem || lem.removed || lem.disabled) continue;
-        const actionName = lem.action?.getActionName?.() || '';
-        if (actionName !== 'falling') continue;
-        pending.targetId = lem.id;
-        pending.dueTick = tick + pending.delay;
-        target = lem;
-        break;
-      }
-    }
-
-    if (!target || !Number.isFinite(pending.dueTick)) return;
-    if (tick < pending.dueTick) return;
-    if (!this._canSpend('builder')) return;
-
-    const drop = ground && Number.isFinite(target.x) && Number.isFinite(target.y)
-      ? this._getDropAt(ground, Math.floor(target.x), Math.floor(target.y), maxDrop)
-      : null;
-    if (drop != null && drop <= 1) {
-      this._refundBudget('builder');
-      return;
-    }
-
-    if (manager.doLemmingAction(target, SkillTypes.BUILDER)) {
-      this._noteAiAction(target, tick, 48);
-      this._pendingMidairBuilder = null;
-      return;
-    }
-    this._refundBudget('builder');
-  }
-
-  _applyBuilderToNextLemming(burst) {
-    const manager = this.game?.getLemmingManager?.();
-    const lems = manager?.lemmings || [];
-    if (!lems.length) return false;
-    if (Number.isFinite(burst?.edgeX)) {
-      let best = null;
-      let bestDist = Infinity;
-      for (const lem of lems) {
-        if (!lem || lem.removed || lem.disabled || !lem.lookRight) continue;
-        const actionName = lem.action?.getActionName?.() || '';
-        if (actionName && actionName !== 'walking') continue;
-        if (burst.used?.has?.(lem.id)) continue;
-        if (lem.x > burst.edgeX + 8) continue;
-        const dist = Math.abs((lem.x ?? 0) - burst.edgeX);
-        if (dist < bestDist) {
-          bestDist = dist;
-          best = lem;
-        }
-      }
-      if (best && manager.doLemmingAction(best, SkillTypes.BUILDER)) {
-        const tick = this.game?.getGameTimer?.().tickIndex ?? 0;
-        this._noteAiAction(best, tick, 48);
-        burst.used?.add?.(best.id);
-        return true;
-      }
-    }
-    if (Number.isFinite(burst?.originX)) {
-      let best = null;
-      let bestDist = Infinity;
-      for (const lem of lems) {
-        if (!lem || lem.removed || lem.disabled || !lem.lookRight) continue;
-        const actionName = lem.action?.getActionName?.() || '';
-        if (actionName && actionName !== 'walking') continue;
-        if (burst.used?.has?.(lem.id)) continue;
-        const dist = Math.abs((lem.x ?? 0) - burst.originX);
-        if (dist < bestDist) {
-          bestDist = dist;
-          best = lem;
-        }
-      }
-      if (best && manager.doLemmingAction(best, SkillTypes.BUILDER)) {
-        const tick = this.game?.getGameTimer?.().tickIndex ?? 0;
-        this._noteAiAction(best, tick, 48);
-        burst.used?.add?.(best.id);
-        return true;
-      }
-      return false;
-    }
-    const start = Math.max(0, this._builderCursorId);
-    for (let i = 0; i < lems.length; i++) {
-      const idx = (start + i) % lems.length;
-      const lem = lems[idx];
-      if (!lem || lem.removed || lem.disabled) continue;
-      const actionName = lem.action?.getActionName?.() || '';
-      if (actionName && actionName !== 'walking') continue;
-      this._builderCursorId = idx + 1;
-      if (manager.doLemmingAction(lem, SkillTypes.BUILDER)) {
-        const tick = this.game?.getGameTimer?.().tickIndex ?? 0;
-        this._noteAiAction(lem, tick, 48);
-        return true;
-      }
-    }
-    return false;
-  }
-
-  _ensureGround(rightmostX) {
-    const levelWidth = this.level?.width ?? 0;
-    if (!Number.isFinite(levelWidth) || levelWidth <= 0) return;
-    while (rightmostX + this.lookAhead >= this._groundEndX - this.extendThreshold) {
-      if (this._groundEndX >= levelWidth) break;
-      const segmentWidth = this._pickSegmentWidth();
-      if (this._shouldInsertGap()) {
-        const gapWidth = this._pickGapWidth();
-        const gapStart = this._groundEndX;
-        this._gaps.push({
-          x: gapStart,
-          width: gapWidth,
-          y: this._groundTopY,
-          assigned: false
-        });
-        this._groundEndX = Math.min(levelWidth, this._groundEndX + gapWidth);
-        this._gapCooldown = this._randInt(16, 40);
-        continue;
-      }
-      const nextTop = this._pickNextTopY();
-      const colorIndex = this._getNextColorIndex();
-      this._paintGround(this._groundEndX, segmentWidth, nextTop, colorIndex);
-      this._groundTopY = nextTop;
-      this._groundEndX = Math.min(levelWidth, this._groundEndX + segmentWidth);
-    }
-  }
-
-  _paintGround(startX, width, topY, colorIndex) {
-    if (this.assets && this.stamper) {
-      this._paintGroundPieces(startX, width, topY, colorIndex);
-      return;
-    }
-    this._paintGroundPixels(startX, width, topY, colorIndex);
-  }
-
-  _paintGroundPixels(startX, width, topY, colorIndex) {
-    if (!this.level) return;
-    const levelWidth = this.level.width;
-    const levelHeight = this.level.height;
-    const x0 = Math.max(0, startX);
-    const x1 = Math.min(levelWidth, startX + width);
-    const top = Number.isFinite(topY) ? topY : levelHeight - this.groundHeight;
-    const y0 = Math.max(0, Math.min(levelHeight - this.groundHeight, top));
-    const y1 = Math.min(levelHeight, y0 + this.groundHeight);
-    const paletteIndex = Number.isFinite(colorIndex)
-      ? colorIndex
-      : this.groundColorIndex;
-    for (let y = y0; y < y1; y++) {
-      for (let x = x0; x < x1; x++) {
-        this.level.setGroundAt(x, y, paletteIndex);
-      }
-    }
-  }
-
-  _paintGroundPieces(startX, width, topY, colorIndex) {
-    if (!this.level || !this.assets || !this.stamper) return;
-    const levelWidth = this.level.width;
-    const maxX = Math.min(levelWidth, startX + width);
-    const floorY = (Number.isFinite(topY) ? topY : 0) + this.groundHeight - 1;
-    let cursor = Math.max(0, startX);
-    const decorBias = Number.isFinite(colorIndex) ? (colorIndex % 4) : 0;
-    const structure = this._getStructurePlan();
-    let repeatPiece = null;
-    while (cursor < maxX) {
-      const remaining = maxX - cursor;
-      let surfaceY = this._nextSurfaceY(structure, floorY);
-      const minHeight = structure?.type === 'pillar'
-        ? Math.max(this.groundHeight * 3, 8)
-        : this.groundHeight;
-      const minWidth = structure?.type === 'shelf'
-        ? Math.max(6, this.segmentMinWidth)
-        : 1;
-      const repeatWidth = repeatPiece?.width ?? repeatPiece?.bounds?.width ?? 0;
-      const piece = repeatPiece && remaining >= repeatWidth
-        ? repeatPiece
-        : this.assets.pickGroundPiece(remaining, minHeight, minWidth);
-      if (!piece?.bounds?.width) break;
-      if (!repeatPiece || Math.random() < 0.25) {
-        repeatPiece = piece;
-      }
-      const stamped = structure?.type === 'pillar'
-        ? this._stampVerticalRun(cursor, surfaceY, piece)
-        : this._stampHorizontalRun(cursor, surfaceY, piece, maxX, decorBias);
-      cursor += stamped;
-      if (cursor >= maxX) break;
-    }
-  }
-
-  _stampHorizontalRun(cursorX, surfaceY, piece, maxX, decorBias) {
-    const pieceWidth = Math.max(1, piece.width || piece.bounds.width);
-    const repeats = Math.max(1, Math.floor((maxX - cursorX) / pieceWidth));
-    let stamped = 0;
-    for (let i = 0; i < repeats; i++) {
-      const destX = cursorX + stamped - piece.bounds.minX;
-      const destY = this._clampSurfaceForEntrance(surfaceY, piece, cursorX + stamped) - piece.bounds.maxY;
-      this.stamper.stamp(piece, destX, destY);
-      if (Math.random() < (this.decorChance + decorBias * 0.01)) {
-        this._placeDecoration(destX, destY, piece);
-      }
-      stamped += pieceWidth;
-    }
-    return stamped || pieceWidth;
-  }
-
-  _stampVerticalRun(cursorX, surfaceY, piece) {
-    const pieceWidth = Math.max(1, piece.width || piece.bounds.width);
-    const pieceHeight = Math.max(1, piece.height || piece.bounds.height);
-    const repeats = Math.max(2, Math.ceil(this.groundHeight / pieceHeight));
-    let topY = surfaceY;
-    for (let i = 0; i < repeats; i++) {
-      const destX = cursorX - piece.bounds.minX;
-      const destY = topY - piece.bounds.maxY;
-      this.stamper.stamp(piece, destX, destY);
-      topY -= pieceHeight;
-    }
-    return pieceWidth;
-  }
-
-  _getStructurePlan() {
-    if (!this._structurePlan || this._structurePlan.remaining <= 0) {
-      this._structurePlan = this._seedStructurePlan();
-    }
-    return this._structurePlan;
-  }
-
-  _seedStructurePlan() {
-    const roll = Math.random();
-    let type = 'flat';
-    if (roll < 0.25) type = 'steps-up';
-    else if (roll < 0.5) type = 'steps-down';
-    else if (roll < 0.65) type = 'shelf';
-    else if (roll < 0.8) type = 'pillar';
-    else type = 'staircase';
-    const length = type === 'staircase'
-      ? this._randInt(4, 10)
-      : this._randInt(2, 6);
-    return {
-      type,
-      remaining: length,
-      step: this._randInt(1, Math.max(2, this.maxStepUp)),
-      surface: null,
-      direction: Math.random() < 0.5 ? -1 : 1,
-      turnAt: Math.max(1, Math.floor(length / 2))
-    };
-  }
-
-  _nextSurfaceY(plan, baseSurfaceY) {
-    if (!plan) return baseSurfaceY;
-    const levelHeight = this.level?.height ?? 0;
-    const maxSurface = Math.max(0, levelHeight - 1);
-    if (!Number.isFinite(plan.surface)) {
-      plan.surface = baseSurfaceY;
-    }
-    let surface = plan.surface;
-    if (plan.type === 'steps-up') {
-      surface -= plan.step;
-    } else if (plan.type === 'steps-down') {
-      surface += plan.step;
-    } else if (plan.type === 'shelf') {
-      surface += this._randInt(-2, 2);
-    } else if (plan.type === 'pillar') {
-      surface += this._randInt(-1, 1);
-    } else if (plan.type === 'staircase') {
-      surface += plan.step * plan.direction;
-      if (plan.remaining <= plan.turnAt) {
-        plan.direction = -plan.direction;
-      }
-    }
-    plan.remaining -= 1;
-    if (plan.remaining <= 0) {
-      this._structurePlan = null;
-    }
-    plan.surface = surface;
-    return Math.max(0, Math.min(maxSurface, surface));
-  }
-
-  _clampSurfaceForEntrance(surfaceY, piece, cursorX) {
-    if (!Number.isFinite(this.entranceY) || !Number.isFinite(this.entranceX)) {
-      return surfaceY;
-    }
-    if (!piece?.bounds) return surfaceY;
-    const span = Math.max(80, piece.bounds.width * 2);
-    if (Math.abs(cursorX - this.entranceX) > span) return surfaceY;
-    const clearance = Math.max(12, this.entranceClearance);
-    const minSurface = this.entranceY + clearance;
-    return Math.max(surfaceY, minSurface);
-  }
-
-  _placeDecoration(baseX, baseY, basePiece) {
-    if (!this.assets || !this.stamper) return;
-    const decor = this.assets.pickDecorPiece(32);
-    if (!decor?.bounds) return;
-    const offsetX = basePiece?.bounds?.minX ?? 0;
-    const destX = baseX + offsetX + this._randInt(-4, 6);
-    const raise = this._randInt(6, 22);
-    const destY = baseY - decor.bounds.height - raise;
-    if (this._overlapsRecentDecor(destX, destY, decor)) return;
-    this.stamper.stamp(decor, destX, destY);
-    this._trackDecorPlacement(destX, destY, decor);
-  }
-
-  _overlapsRecentDecor(destX, destY, decor) {
-    const rect = {
-      x: destX + decor.bounds.minX,
-      y: destY + decor.bounds.minY,
-      w: decor.bounds.width,
-      h: decor.bounds.height
-    };
-    for (const other of this._recentDecor) {
-      if (!other) continue;
-      const xOverlap = Math.min(rect.x + rect.w, other.x + other.w) - Math.max(rect.x, other.x);
-      const yOverlap = Math.min(rect.y + rect.h, other.y + other.h) - Math.max(rect.y, other.y);
-      if (xOverlap > 2 && yOverlap > 2) {
-        return true;
-      }
-    }
-    return false;
-  }
-
-  _trackDecorPlacement(destX, destY, decor) {
-    this._recentDecor.push({
-      x: destX + decor.bounds.minX,
-      y: destY + decor.bounds.minY,
-      w: decor.bounds.width,
-      h: decor.bounds.height
-    });
-    if (this._recentDecor.length > 40) {
-      this._recentDecor.splice(0, this._recentDecor.length - 40);
-    }
-  }
-
-  _pickSegmentWidth() {
-    const min = Math.max(2, Math.floor(this.segmentMinWidth));
-    const max = Math.max(min, Math.floor(this.segmentMaxWidth));
-    return min + Math.floor(Math.random() * (max - min + 1));
-  }
-
-  _pickGapWidth() {
-    const min = Math.max(2, Math.floor(this.gapMinWidth));
-    const max = Math.max(min, Math.floor(this.gapMaxWidth));
-    return min + Math.floor(Math.random() * (max - min + 1));
-  }
-
-  _shouldInsertGap() {
-    if (this._gapCooldown > 0) {
-      this._gapCooldown -= 1;
-      return false;
-    }
-    if (Math.random() > this.gapChance) return false;
-    return true;
-  }
-
-  _pickNextTopY() {
-    const levelHeight = this.level?.height ?? 0;
-    const maxTop = Math.max(0, levelHeight - this.groundHeight);
-    if (this._sustainRemaining <= 0) {
-      this._seedSustainLevel(maxTop);
-    }
-    const delta = this._nextElevationDelta();
-    let next = this._groundTopY + delta;
-    const offset = this._groundTopY - this._sustainBaseY;
-    if (offset !== 0) {
-      const biasStep = Math.min(3, Math.ceil(Math.abs(offset) / 8));
-      next += offset > 0 ? -biasStep : biasStep;
-    }
-    this._sustainRemaining -= 1;
-    return Math.max(0, Math.min(maxTop, next));
-  }
-
-  _nextElevationDelta() {
-    if (!this._terrainPlan || this._terrainPlan.remaining <= 0) {
-      this._seedTerrainPlan();
-    }
-    const mode = this._terrainPlan.mode;
-    const up = Math.max(1, Math.floor(this.maxStepUp));
-    const down = Math.max(1, Math.floor(this.maxDrop));
-    let delta = 0;
-    if (mode === 'climb') {
-      delta = -this._randInt(1, up);
-    } else if (mode === 'drop-small') {
-      delta = this._randInt(1, Math.min(4, down));
-    } else if (mode === 'drop-medium') {
-      delta = this._randInt(Math.min(5, down), Math.min(14, down));
-    } else if (mode === 'drop-big') {
-      const minBig = Math.max(6, Math.floor(down * 0.7));
-      delta = this._randInt(minBig, down);
-    } else {
-      delta = this._randInt(-1, 1);
-    }
-    this._terrainPlan.remaining -= 1;
-    return delta;
-  }
-
-  _seedTerrainPlan() {
-    const prev = this._terrainPlan?.mode || 'flat';
-    let mode = 'flat';
-    if (prev === 'climb') {
-      mode = 'flat';
-      this._pendingDrop = true;
-    } else if (prev === 'flat') {
-      if (this._pendingDrop) {
-        const roll = Math.random();
-        if (roll < 0.5) mode = 'drop-small';
-        else if (roll < 0.85) mode = 'drop-medium';
-        else mode = 'drop-big';
-        this._pendingDrop = false;
-      } else {
-        const roll = Math.random();
-        if (roll < 0.5) mode = 'climb';
-        else if (roll < 0.75) mode = 'drop-small';
-        else if (roll < 0.92) mode = 'drop-medium';
-        else mode = 'drop-big';
-      }
-    } else {
-      mode = 'flat';
-    }
-    const lengths = {
-      climb: this._randInt(4, 10),
-      flat: this._randInt(8, 18),
-      'drop-small': this._randInt(3, 8),
-      'drop-medium': this._randInt(2, 4),
-      'drop-big': 1
-    };
-    this._terrainPlan = {
-      mode,
-      remaining: lengths[mode] || 3
-    };
-  }
-
-  _randInt(min, max) {
-    const lo = Math.min(min, max);
-    const hi = Math.max(min, max);
-    return lo + Math.floor(Math.random() * (hi - lo + 1));
-  }
-
-  _getNextColorIndex() {
-    const maxIndex = 15;
-    const base = Number.isFinite(this.groundColorIndex) && this.groundColorIndex > 0
-      ? this.groundColorIndex
-      : 1;
-    if (!Number.isFinite(this._segmentColorIndex) || this._segmentColorIndex <= 0) {
-      this._segmentColorIndex = base;
-    }
-    if (!this._colorTransition || this._colorTransition.remaining <= 0) {
-      const target = this._randInt(1, maxIndex);
-      const to = target === this._segmentColorIndex ? ((target % maxIndex) + 1) : target;
-      const total = this._randInt(10, 300);
-      const step = total > 0 ? (to - this._segmentColorIndex) / total : 0;
-      this._colorTransition = {
-        from: this._segmentColorIndex,
-        to,
-        total,
-        remaining: total,
-        current: this._segmentColorIndex,
-        step
-      };
-    }
-    const transition = this._colorTransition;
-    transition.current += transition.step;
-    transition.remaining -= 1;
-    const progress = transition.total > 0
-      ? (transition.total - transition.remaining) / transition.total
-      : 1;
-    let next = transition.from;
-    if (transition.from !== transition.to) {
-      const chance = Math.min(1, Math.max(0, progress));
-      next = Math.random() < chance ? transition.to : transition.from;
-    }
-    if (transition.remaining <= 0) {
-      next = transition.to;
-      transition.current = transition.to;
-    }
-    next = Math.min(maxIndex, Math.max(1, next));
-    this._segmentColorIndex = next;
-    return next;
-  }
-
-  _seedSustainLevel(maxTop) {
-    const upRange = Math.max(8, Math.floor(this.maxStepUp * 8));
-    const downRange = Math.max(12, Math.floor(this.maxDrop * 0.35));
-    const delta = this._randInt(-upRange, downRange);
-    const nextBase = Math.max(0, Math.min(maxTop, this._groundTopY + delta));
-    this._sustainBaseY = nextBase;
-    this._sustainRemaining = this._randInt(20, 200);
-  }
-
-  _updateCamera(rightmostX) {
-    const stage = this.view?.stage;
-    const stageImage = stage?.gameImgProps;
-    if (!stage || !stageImage) return;
-    const scale = stageImage.viewPoint.scale || 1;
-    if (!Number.isFinite(scale) || scale <= 0) return;
-    const viewW = stageImage.canvasViewportSize.width / scale;
-    if (!Number.isFinite(viewW) || viewW <= 0) return;
-    const targetX = rightmostX - viewW / 2;
-    if (!Number.isFinite(this._cameraX)) {
-      this._cameraX = targetX;
-    }
-    this._cameraTargetX = targetX;
-    const frameMs = this.game?.getGameTimer?.().frameTime ?? 16;
-    const alpha = Math.min(1, Math.max(0.01, frameMs / 500));
-    this._cameraX += (this._cameraTargetX - this._cameraX) * alpha;
-    stage.applyViewport(stageImage, this._cameraX, 0, stageImage.viewPoint.scale);
-  }
-
-  _initDebugOverlay() {
-    if (!this.window?.document || this._aiDebug) return;
-    const doc = this.window.document;
-    const panel = doc.createElement('div');
-    panel.className = 'procgen-debug';
-    panel.textContent = 'AI: ready';
-    doc.body.appendChild(panel);
-    this._aiDebug = panel;
-  }
-
-  _updateDebugOverlay() {
-    if (!this._aiDebug) return;
-    const decision = this._aiLastDecision;
-    if (!decision) return;
-    const action = decision.action || 'none';
-    const scan = decision.scan || {};
-    const gap = scan.gap ? `gap dx=${scan.gap.dx} w=${scan.gap.width} drop=${scan.gap.drop}` : 'gap none';
-    const wall = scan.wall ? `wall dx=${scan.wall.dx} h=${scan.wall.height}` : 'wall none';
-    const hazard = scan.hazard ? `hazard dx=${scan.hazard.dx} type=${scan.hazard.type}` : 'hazard none';
-    const budget = this._aiBudget
-      ? Object.entries(this._aiBudget)
-        .map(([key, value]) => `${key}:${value.toFixed(1)}`)
-        .join(' ')
-      : '';
-    this._aiDebug.textContent = `AI ${action} | ${gap} | ${wall} | ${hazard} | ${budget}`;
-  }
-}
-
-export { ProcgenController };
+export { ProcgenController } from './procgen/ProcgenControllerCore.js';
diff --git a/js/app/procgenStageAdapter.js b/js/app/procgenStageAdapter.js
index 40f3caca..000b5742 100644
--- a/js/app/procgenStageAdapter.js
+++ b/js/app/procgenStageAdapter.js
@@ -1,29 +1,51 @@
 import { DisplayImage } from '../render/DisplayImage.js';
 
 class ProcgenStageAdapter {
-  constructor({ view, controller, canvas }) {
+  constructor({ view, controller, canvas, windowRef }) {
     this.view = view || null;
     this.controller = controller || null;
     this.canvas = canvas || null;
+    this.window = windowRef || controller?.window || globalThis?.window || null;
     this.stage = view?.stage || null;
+    this._wheelHandler = null;
     this._resizeHandler = null;
     this._snapOverridden = false;
+    this._snapScaleOriginal = null;
+    this._installed = false;
     this.maxScale = 6;
     this.zoomStep = 1.1;
   }
 
   install() {
-    if (!this.stage) return;
+    if (this._installed || !this.stage) return;
     this._ensureGuiBuffer();
     this._overrideScaleClamp();
     this._bindZoom();
     this._bindResize();
+    this._installed = true;
+  }
+
+  /** Release all bound listeners and restore stage behavior. */
+  dispose() {
+    this._unbindZoom();
+    this._unbindResize();
+    this._restoreScaleClamp();
+    this._installed = false;
+  }
+
+  updateStageSize() {
+    if (!this.stage) return;
+    this._ensureGuiBuffer();
+    this.stage.updateStageSize?.();
   }
 
   _bindZoom() {
-    if (!this.canvas) return;
-    this.canvas.addEventListener('wheel', event => {
+    if (!this.canvas || this._wheelHandler) return;
+    this._wheelHandler = event => {
       event.preventDefault();
+      if (!Number.isFinite(event?.deltaY) || event.deltaY === 0) {
+        return;
+      }
       const stage = this.stage;
       const stageImage = stage?.gameImgProps;
       if (!stage || !stageImage) return;
@@ -33,14 +55,28 @@ class ProcgenStageAdapter {
       if (next === current) return;
       stage.applyViewport(stageImage, stageImage.viewPoint.x || 0, stageImage.viewPoint.y || 0, next);
       stage.redraw();
-    }, { passive: false });
+    };
+    this.canvas.addEventListener('wheel', this._wheelHandler, { passive: false });
+  }
+
+  _unbindZoom() {
+    if (!this.canvas || !this._wheelHandler) return;
+    this.canvas.removeEventListener('wheel', this._wheelHandler);
+    this._wheelHandler = null;
   }
 
   _bindResize() {
+    if (this._resizeHandler || !this.window?.addEventListener) return;
     this._resizeHandler = () => {
-      this._ensureGuiBuffer();
+      this.updateStageSize();
     };
-    window.addEventListener('resize', this._resizeHandler);
+    this.window.addEventListener('resize', this._resizeHandler);
+  }
+
+  _unbindResize() {
+    if (!this._resizeHandler || !this.window?.removeEventListener) return;
+    this.window.removeEventListener('resize', this._resizeHandler);
+    this._resizeHandler = null;
   }
 
   _clampScale(scale) {
@@ -66,6 +102,7 @@ class ProcgenStageAdapter {
   _overrideScaleClamp() {
     if (this._snapOverridden || !this.stage) return;
     this._snapOverridden = true;
+    this._snapScaleOriginal = this.stage.snapScale;
     this.stage.snapScale = (rawScale) => {
       const display = this.stage?.gameImgProps?.display;
       const { width: dispW, height: dispH } = display?.worldDataSize || {};
@@ -81,6 +118,13 @@ class ProcgenStageAdapter {
     };
   }
 
+  _restoreScaleClamp() {
+    if (!this._snapOverridden || !this.stage) return;
+    this.stage.snapScale = this._snapScaleOriginal;
+    this._snapScaleOriginal = null;
+    this._snapOverridden = false;
+  }
+
   _getWorldWidth() {
     const level = this.view?.game?.level || this.controller?.level;
     const extent = this.controller?.getGroundExtentX?.();
@@ -91,7 +135,11 @@ class ProcgenStageAdapter {
   _ensureGuiBuffer() {
     if (!this.stage) return;
     const guiProps = this.stage.guiImgProps;
+    if (!guiProps || typeof guiProps !== 'object') return;
     if (guiProps?.display) return;
+    if (typeof guiProps?.viewPoint?.setX !== 'function' || typeof guiProps?.viewPoint?.setY !== 'function') {
+      return;
+    }
     const display = new DisplayImage(this.stage);
     display.initSize(1, 1);
     guiProps.display = display;
diff --git a/js/app/procgenTerrainStamper.js b/js/app/procgenTerrainStamper.js
index ff9f6f50..3dd3df95 100644
--- a/js/app/procgenTerrainStamper.js
+++ b/js/app/procgenTerrainStamper.js
@@ -18,52 +18,119 @@ const getPaletteLookup = (palette) => {
 class ProcgenTerrainStamper {
   constructor(level) {
     this.level = level || null;
+    this._dest32 = null;
+    this._destBuffer = null;
+    this._mask = null;
+    this._levelWidth = 0;
+    this._levelHeight = 0;
   }
 
   stamp(piece, x, y, drawProperties = {}) {
     const level = this.level;
-    if (!level || !piece?.image || !piece?.frame) return;
+    if (!level || !piece?.image || !piece?.frame) return null;
     const img = piece.image;
     const width = img.width | 0;
     const height = img.height | 0;
-    if (width <= 0 || height <= 0) return;
+    if (width <= 0 || height <= 0) return null;
 
-    const dest32 = new Uint32Array(level.groundImage.buffer);
-    const mask = level.groundMask.mask;
-    const levelW = level.width | 0;
-    const levelH = level.height | 0;
+    this._ensureLevelViews(level);
+    const dest32 = this._dest32;
+    const mask = this._mask;
+    const levelW = this._levelWidth;
+    const levelH = this._levelHeight;
+    if (!dest32 || !mask || levelW <= 0 || levelH <= 0) return null;
 
     const palLookup = getPaletteLookup(img.palette);
-    if (!palLookup) return;
+    if (!palLookup) return null;
+
+    const xOffset = x | 0;
+    const yOffset = y | 0;
+    const srcX0 = Math.max(0, -xOffset);
+    const srcY0 = Math.max(0, -yOffset);
+    const srcX1 = Math.min(width, levelW - xOffset);
+    const srcY1 = Math.min(height, levelH - yOffset);
+    if (srcX0 >= srcX1 || srcY0 >= srcY1) return null;
 
     const isUpsideDown = !!drawProperties.isUpsideDown;
     const noOverwrite = !!drawProperties.noOverwrite;
     const onlyOverwrite = !!drawProperties.onlyOverwrite;
     const isErase = !!drawProperties.isErase;
+    const black = ColorPalette.black;
+    let minX = levelW;
+    let minY = levelH;
+    let maxX = -1;
+    let maxY = -1;
 
-    for (let dy = 0; dy < height; dy++) {
+    for (let dy = srcY0; dy < srcY1; dy++) {
       const srcY = isUpsideDown ? (height - 1 - dy) : dy;
-      const outY = y + dy;
-      if (outY < 0 || outY >= levelH) continue;
+      const outY = yOffset + dy;
       const srcRow = srcY * width;
       const destRow = outY * levelW;
-      for (let dx = 0; dx < width; dx++) {
-        const outX = x + dx;
-        if (outX < 0 || outX >= levelW) continue;
+      for (let dx = srcX0; dx < srcX1; dx++) {
+        const outX = xOffset + dx;
         const ci = piece.frame[srcRow + dx];
         if (ci & 0x80) continue;
         const idx = destRow + outX;
         if (isErase) {
+          if (mask[idx] === 0 && dest32[idx] === black) continue;
           mask[idx] = 0;
-          dest32[idx] = ColorPalette.black;
+          dest32[idx] = black;
+          if (outX < minX) minX = outX;
+          if (outY < minY) minY = outY;
+          if (outX > maxX) maxX = outX;
+          if (outY > maxY) maxY = outY;
           continue;
         }
         if (noOverwrite && mask[idx]) continue;
         if (onlyOverwrite && !mask[idx]) continue;
+        const next = palLookup[ci];
+        if (mask[idx] === 1 && dest32[idx] === next) continue;
         mask[idx] = 1;
-        dest32[idx] = palLookup[ci];
+        dest32[idx] = next;
+        if (outX < minX) minX = outX;
+        if (outY < minY) minY = outY;
+        if (outX > maxX) maxX = outX;
+        if (outY > maxY) maxY = outY;
       }
     }
+    if (maxX >= minX && maxY >= minY) {
+      const rect = {
+        x: minX,
+        y: minY,
+        width: (maxX - minX) + 1,
+        height: (maxY - minY) + 1
+      };
+      level.applyGroundBulkChange?.(rect.x, rect.y, rect.width, rect.height, {
+        invalidateMiniMap: true
+      });
+      return rect;
+    }
+    return null;
+  }
+
+  /**
+   * Cache typed-array views for the current level buffer so repeated stamps
+   * avoid recreating `Uint32Array` wrappers in hot terrain generation paths.
+   */
+  _ensureLevelViews(level) {
+    const image = level?.groundImage;
+    const mask = level?.groundMask?.mask;
+    const buffer = image?.buffer ?? null;
+    if (!buffer || !mask) {
+      this._dest32 = null;
+      this._destBuffer = null;
+      this._mask = null;
+      this._levelWidth = 0;
+      this._levelHeight = 0;
+      return;
+    }
+    if (this._destBuffer !== buffer || !this._dest32) {
+      this._destBuffer = buffer;
+      this._dest32 = new Uint32Array(buffer);
+    }
+    this._mask = mask;
+    this._levelWidth = level.width | 0;
+    this._levelHeight = level.height | 0;
   }
 }
 
diff --git a/js/app/registerServiceWorker.js b/js/app/registerServiceWorker.js
index d7472e72..0c10941b 100644
--- a/js/app/registerServiceWorker.js
+++ b/js/app/registerServiceWorker.js
@@ -1,57 +1,221 @@
-const registerServiceWorker = () => {
-  if (typeof navigator === 'undefined' || !('serviceWorker' in navigator)) return;
-  const hadController = !!navigator.serviceWorker.controller;
-  const onLoad = async () => {
+import { appendRevisionParam, resolveRuntimeRevision } from '../core/cacheBust.js';
+import { getRuntimeDependency } from '../core/dependencies.js';
+import { DEFAULT_RUNTIME_PROFILE, normalizeRuntimeProfile } from '../core/runtimeProfiles.js';
+
+const DISABLED_PROFILES = new Set(['dev', 'editor', 'perf', 'e2e']);
+const DISABLED_CACHE_PREFIXES = Object.freeze(['lemmings-core-', 'lemmings-runtime-']);
+let activeServiceWorkerRuntime = null;
+
+const isTruthyQueryValue = (value) => {
+  if (value == null || value === '') return true;
+  const normalized = String(value).trim().toLowerCase();
+  return normalized !== '0' && normalized !== 'false' && normalized !== 'off' && normalized !== 'no';
+};
+
+const hasTruthyQueryKey = (location, key) => {
+  if (!location || typeof URLSearchParams === 'undefined') return false;
+  const params = new URLSearchParams(location.search || '');
+  if (!params.has(key)) return false;
+  return isTruthyQueryValue(params.get(key));
+};
+
+const isDevLocation = (location) => {
+  if (!location) return false;
+  if (location.protocol === 'file:') return true;
+  const host = String(location.hostname || '').toLowerCase();
+  return host === 'localhost' || host === '127.0.0.1' || host === '::1' || host === '0.0.0.0';
+};
+
+const shouldBypassServiceWorker = ({
+  profile = DEFAULT_RUNTIME_PROFILE,
+  e2e = false,
+  dev = false,
+  enableServiceWorker = false,
+  disableServiceWorker = false,
+  location = getRuntimeDependency('location', null)
+} = {}) => {
+  const rawProfile = String(profile || '').trim().toLowerCase();
+  const normalizedProfile = normalizeRuntimeProfile(rawProfile);
+  const explicitlyEnabled = enableServiceWorker === true
+    || hasTruthyQueryKey(location, 'sw')
+    || hasTruthyQueryKey(location, 'serviceWorker');
+  if (disableServiceWorker === true || hasTruthyQueryKey(location, 'noSw')) return true;
+  if (e2e === true || hasTruthyQueryKey(location, 'e2e')) return true;
+  if (DISABLED_PROFILES.has(rawProfile) || DISABLED_PROFILES.has(normalizedProfile)) return true;
+  if (dev === true || hasTruthyQueryKey(location, 'dev')) return !explicitlyEnabled;
+  if (isDevLocation(location)) return !explicitlyEnabled;
+  return false;
+};
+
+const disableActiveServiceWorker = async (
+  serviceWorker = null,
+  cacheStorage = getRuntimeDependency('caches', null)
+) => {
+  if (serviceWorker) {
+    const registrations = [];
     try {
-      const registration = await navigator.serviceWorker.register(
-        'service-worker.js',
-        { updateViaCache: 'none' }
+      const list = await serviceWorker.getRegistrations?.();
+      if (Array.isArray(list)) registrations.push(...list);
+    } catch {
+      /* ignored */
+    }
+    if (!registrations.length) {
+      try {
+        const single = await serviceWorker.getRegistration?.();
+        if (single) registrations.push(single);
+      } catch {
+        /* ignored */
+      }
+    }
+    for (let i = 0; i < registrations.length; i += 1) {
+      try {
+        await registrations[i]?.unregister?.();
+      } catch {
+        /* ignored */
+      }
+    }
+  }
+
+  if (cacheStorage?.keys && cacheStorage?.delete) {
+    try {
+      const cacheKeys = await cacheStorage.keys();
+      for (let i = 0; i < cacheKeys.length; i += 1) {
+        const key = cacheKeys[i];
+        if (!DISABLED_CACHE_PREFIXES.some(prefix => String(key).startsWith(prefix))) {
+          continue;
+        }
+        try {
+          await cacheStorage.delete(key);
+        } catch {
+          /* ignored */
+        }
+      }
+    } catch {
+      /* ignored */
+    }
+  }
+};
+
+const registerServiceWorker = (options = {}) => {
+  activeServiceWorkerRuntime?.dispose?.();
+  activeServiceWorkerRuntime = null;
+  const nav = options.navigator ?? getRuntimeDependency('navigator', null);
+  const windowRef = options.window ?? getRuntimeDependency('window', null);
+  const documentRef = options.document ?? getRuntimeDependency('document', null);
+  const location = options.location ?? windowRef?.location ?? getRuntimeDependency('location', null);
+  let disposed = false;
+  const cleanup = [];
+  let updateIntervalId = null;
+  const addCleanup = (fn) => {
+    if (typeof fn === 'function') cleanup.push(fn);
+  };
+  const addListener = (target, eventName, handler, listenerOptions) => {
+    if (!target?.addEventListener || typeof handler !== 'function') return;
+    target.addEventListener(eventName, handler, listenerOptions);
+    addCleanup(() => target.removeEventListener?.(eventName, handler, listenerOptions));
+  };
+  const runtime = {
+    dispose() {
+      disposed = true;
+      if (updateIntervalId != null) {
+        windowRef?.clearInterval?.(updateIntervalId);
+        updateIntervalId = null;
+      }
+      while (cleanup.length) {
+        try {
+          cleanup.pop()?.();
+        } catch {
+          /* ignored */
+        }
+      }
+      if (activeServiceWorkerRuntime === runtime) {
+        activeServiceWorkerRuntime = null;
+      }
+    }
+  };
+  if (!nav || !('serviceWorker' in nav)) return runtime;
+  const serviceWorker = nav.serviceWorker;
+  activeServiceWorkerRuntime = runtime;
+
+  const onLoad = async () => {
+    if (disposed) return;
+    if (shouldBypassServiceWorker({ ...options, location })) {
+      await disableActiveServiceWorker(
+        serviceWorker,
+        options.cacheStorage ?? getRuntimeDependency('caches', null)
       );
+      return;
+    }
+
+    const hadController = !!serviceWorker.controller;
+    try {
+      const revision = resolveRuntimeRevision({
+        revision: options.revision,
+        location,
+        document: documentRef
+      });
+      const workerUrl = appendRevisionParam('service-worker.js', revision);
+      const registration = await serviceWorker.register(workerUrl, { updateViaCache: 'none' });
       let refreshing = false;
-      const requestUpdate = () => registration.update().catch(() => {});
+      const requestUpdate = () => registration.update?.().catch(() => {});
       const activateWaiting = () => {
         if (registration.waiting) {
           registration.waiting.postMessage({ type: 'SKIP_WAITING' });
         }
       };
       const scheduleUpdate = () => {
+        if (disposed) return;
         requestUpdate();
         activateWaiting();
       };
-      registration.addEventListener('updatefound', () => {
+      const onUpdateFound = () => {
         const installing = registration.installing;
         if (!installing) return;
-        installing.addEventListener('statechange', () => {
-          if (installing.state === 'installed' && navigator.serviceWorker.controller) {
+        const onStateChange = () => {
+          if (installing.state === 'installed' && serviceWorker.controller) {
             activateWaiting();
           }
-        });
-      });
-      navigator.serviceWorker.addEventListener('controllerchange', () => {
+        };
+        addListener(installing, 'statechange', onStateChange);
+      };
+      addListener(registration, 'updatefound', onUpdateFound);
+      const onControllerChange = () => {
         if (!hadController || refreshing) return;
         refreshing = true;
-        window.location.reload();
-      });
+        windowRef?.location?.reload?.();
+      };
+      addListener(serviceWorker, 'controllerchange', onControllerChange);
       scheduleUpdate();
-      window.setInterval(scheduleUpdate, 5 * 60 * 1000);
-      document.addEventListener('visibilitychange', () => {
-        if (document.visibilityState === 'visible') {
+      if (typeof windowRef?.setInterval === 'function') {
+        updateIntervalId = windowRef.setInterval(scheduleUpdate, 5 * 60 * 1000);
+      }
+      const onVisibilityChange = () => {
+        if (documentRef.visibilityState === 'visible') {
           scheduleUpdate();
         }
-      });
-      window.addEventListener('focus', scheduleUpdate);
-      window.addEventListener('online', scheduleUpdate);
+      };
+      addListener(documentRef, 'visibilitychange', onVisibilityChange);
+      addListener(windowRef, 'focus', scheduleUpdate);
+      addListener(windowRef, 'online', scheduleUpdate);
     } catch {
       // Ignore service worker registration failures.
     }
   };
-  if (typeof window !== 'undefined') {
-    if (document.readyState === 'complete') {
+
+  if (windowRef && documentRef) {
+    if (documentRef.readyState === 'complete') {
       onLoad();
     } else {
-      window.addEventListener('load', onLoad, { once: true });
+      addListener(windowRef, 'load', onLoad, { once: true });
     }
+    return runtime;
   }
+  onLoad();
+  return runtime;
 };
 
-export { registerServiceWorker };
+export {
+  disableActiveServiceWorker,
+  registerServiceWorker,
+  shouldBypassServiceWorker
+};
diff --git a/js/app/shortcutOverlay.js b/js/app/shortcutOverlay.js
index 8f31bbb0..e7f419f9 100644
--- a/js/app/shortcutOverlay.js
+++ b/js/app/shortcutOverlay.js
@@ -7,6 +7,7 @@ class ShortcutOverlay {
     this._doc = this.root?.ownerDocument || document;
     this._content = null;
     this._close = null;
+    this._previousFocus = null;
     this._bind();
     this.render();
   }
@@ -18,6 +19,11 @@ class ShortcutOverlay {
     this.root.addEventListener('click', (event) => {
       if (event.target === this.root) this.hide();
     });
+    this.root.addEventListener('keydown', (event) => {
+      if (event.key !== 'Escape') return;
+      event.preventDefault();
+      this.hide();
+    });
     this._close?.addEventListener('click', () => this.hide());
   }
 
@@ -75,15 +81,24 @@ class ShortcutOverlay {
 
   show() {
     if (!this.root) return;
+    const wasVisible = this.root.classList.contains('is-visible');
+    if (!wasVisible) {
+      this._previousFocus = this._doc?.activeElement || null;
+    }
     this.render();
     this.root.classList.add('is-visible');
     this.root.setAttribute('aria-hidden', 'false');
+    this._focusInitialControl();
   }
 
   hide() {
     if (!this.root) return;
+    const wasVisible = this.root.classList.contains('is-visible');
     this.root.classList.remove('is-visible');
     this.root.setAttribute('aria-hidden', 'true');
+    if (wasVisible) {
+      this._restorePreviousFocus();
+    }
   }
 
   toggle(force = null) {
@@ -92,6 +107,28 @@ class ShortcutOverlay {
     if (next) this.show();
     else this.hide();
   }
+
+  _focusInitialControl() {
+    const target = this._close || this.root.querySelector('button, [href], input, select, textarea, [tabindex]');
+    if (typeof target?.focus !== 'function') return;
+    try {
+      target.focus({ preventScroll: true });
+    } catch (error) {
+      target.focus();
+    }
+  }
+
+  _restorePreviousFocus() {
+    const target = this._previousFocus;
+    this._previousFocus = null;
+    if (!target || typeof target.focus !== 'function') return;
+    if (target.isConnected === false) return;
+    try {
+      target.focus({ preventScroll: true });
+    } catch (error) {
+      target.focus();
+    }
+  }
 }
 
 export { ShortcutOverlay };
diff --git a/js/commands/CommandLemmingsAction.js b/js/commands/CommandLemmingsAction.js
index a157b401..92fff67f 100644
--- a/js/commands/CommandLemmingsAction.js
+++ b/js/commands/CommandLemmingsAction.js
@@ -1,4 +1,4 @@
-import { SoundEventTypes, SoundEffectIds, getSoundBus } from '../game/SoundEvents.js';
+import { SoundEventTypes, SoundEffectIds } from '../game/SoundEvents.js';
 
 class CommandLemmingsAction {
   constructor(lemmingId) {
@@ -22,7 +22,7 @@ class CommandLemmingsAction {
     }
     const ok = gameSkills.reuseSkill(selectedSkill);
     if (ok) {
-      const soundBus = getSoundBus();
+      const soundBus = game.soundEvents ?? game.runtime?.soundEvents ?? null;
       soundBus?.emitSfx?.(
         SoundEventTypes.SKILL_ASSIGN,
         SoundEffectIds.SKILL_ASSIGN,
diff --git a/js/commands/CommandManager.js b/js/commands/CommandManager.js
index 0a0cf432..455d1fbd 100644
--- a/js/commands/CommandManager.js
+++ b/js/commands/CommandManager.js
@@ -109,8 +109,6 @@ class CommandManager extends BaseLogger {
       this.gameTimer.onBeforeGameTick.off(this._tickListener);
       this._tickListener = null;
     }
-    if (this.gameTimer && this.gameTimer.onBeforeGameTick && this.gameTimer.onBeforeGameTick.dispose)
-      this.gameTimer.onBeforeGameTick.dispose();
     this.game = null;
     this.gameTimer = null;
     this.log = null;
diff --git a/js/commands/CommandSelectSkill.js b/js/commands/CommandSelectSkill.js
index 20cce501..b25ac80c 100644
--- a/js/commands/CommandSelectSkill.js
+++ b/js/commands/CommandSelectSkill.js
@@ -1,5 +1,5 @@
 import { BaseLogger } from '../util/LogHandler.js';
-import { SoundEventTypes, SoundEffectIds, getSoundBus } from '../game/SoundEvents.js';
+import { SoundEventTypes, SoundEffectIds } from '../game/SoundEvents.js';
 import { SkillTypes } from '../game/SkillTypes.js';
 
 class CommandSelectSkill extends BaseLogger {
@@ -15,7 +15,7 @@ class CommandSelectSkill extends BaseLogger {
     const lemmingManager = game.getLemmingManager?.();
     const changed = gameSkills.setSelectedSkill(this.skill);
     if (changed) {
-      const soundBus = getSoundBus();
+      const soundBus = game.soundEvents ?? game.runtime?.soundEvents ?? null;
       soundBus?.emitSfx?.(
         SoundEventTypes.SKILL_SELECT,
         SoundEffectIds.SKILL_SELECT,
@@ -27,7 +27,7 @@ class CommandSelectSkill extends BaseLogger {
       if (lem && gameSkills.canReuseSkill(this.skill) &&
           lemmingManager.doLemmingAction?.(lem, this.skill)) {
         if (gameSkills.reuseSkill(this.skill)) {
-          const soundBus = getSoundBus();
+          const soundBus = game.soundEvents ?? game.runtime?.soundEvents ?? null;
           soundBus?.emitSfx?.(
             SoundEventTypes.SKILL_ASSIGN,
             SoundEffectIds.SKILL_ASSIGN,
diff --git a/js/core/cacheBust.js b/js/core/cacheBust.js
new file mode 100644
index 00000000..93425cc2
--- /dev/null
+++ b/js/core/cacheBust.js
@@ -0,0 +1,68 @@
+const CACHE_BUST_PARAM = 'rev';
+const ALT_CACHE_BUST_PARAMS = Object.freeze(['cacheBust', 'cb']);
+const CACHE_BUST_PATTERN = /[^a-zA-Z0-9._-]/g;
+const MAX_CACHE_BUST_LENGTH = 64;
+
+const sanitizeCacheBust = (value) => {
+  if (value == null) return null;
+  const trimmed = String(value).trim();
+  if (!trimmed) return null;
+  const normalized = trimmed.replace(CACHE_BUST_PATTERN, '').slice(0, MAX_CACHE_BUST_LENGTH);
+  return normalized || null;
+};
+
+const readCacheBustFromSearch = (search = '') => {
+  if (typeof URLSearchParams === 'undefined') return null;
+  const params = new URLSearchParams(search || '');
+  const direct = sanitizeCacheBust(params.get(CACHE_BUST_PARAM));
+  if (direct) return direct;
+  for (let i = 0; i < ALT_CACHE_BUST_PARAMS.length; i += 1) {
+    const value = sanitizeCacheBust(params.get(ALT_CACHE_BUST_PARAMS[i]));
+    if (value) return value;
+  }
+  return null;
+};
+
+const resolveRuntimeRevision = ({
+  revision = null,
+  location = globalThis.location,
+  document = globalThis.document,
+  globalValue = globalThis.__LEMMINGS_RUNTIME_REVISION__
+} = {}) => {
+  const explicit = sanitizeCacheBust(revision);
+  if (explicit) return explicit;
+  const query = readCacheBustFromSearch(location?.search || '');
+  if (query) return query;
+  const globalRevision = sanitizeCacheBust(globalValue);
+  if (globalRevision) return globalRevision;
+  const metaRevision = sanitizeCacheBust(
+    document?.querySelector?.('meta[name="lemmings-revision"]')?.getAttribute?.('content')
+  );
+  if (metaRevision) return metaRevision;
+  return null;
+};
+
+const appendRevisionParam = (url, revision, paramName = CACHE_BUST_PARAM) => {
+  if (typeof url !== 'string' || !url) return url;
+  const token = sanitizeCacheBust(revision);
+  if (!token) return url;
+  const param = sanitizeCacheBust(paramName) || CACHE_BUST_PARAM;
+  const hashIndex = url.indexOf('#');
+  const hash = hashIndex >= 0 ? url.slice(hashIndex) : '';
+  const base = hashIndex >= 0 ? url.slice(0, hashIndex) : url;
+  const encoded = encodeURIComponent(token);
+  const directPattern = new RegExp(`([?&])${param}=([^&#]*)`);
+  if (directPattern.test(base)) {
+    return `${base.replace(directPattern, `$1${param}=${encoded}`)}${hash}`;
+  }
+  const delimiter = base.includes('?') ? '&' : '?';
+  return `${base}${delimiter}${param}=${encoded}${hash}`;
+};
+
+export {
+  CACHE_BUST_PARAM,
+  appendRevisionParam,
+  readCacheBustFromSearch,
+  resolveRuntimeRevision,
+  sanitizeCacheBust
+};
diff --git a/js/core/capabilityMatrix.js b/js/core/capabilityMatrix.js
new file mode 100644
index 00000000..65e4fd9a
--- /dev/null
+++ b/js/core/capabilityMatrix.js
@@ -0,0 +1,149 @@
+/**
+ * @typedef {object} CapabilityMatrix
+ * @property {{supported: boolean, enabled: boolean, fallbackPath: string}} webMidi
+ * @property {{supported: boolean, ctorSupported: boolean, transferControlSupported: boolean, fallbackPath: string}} offscreenCanvas
+ * @property {{supported: boolean, fallbackPath: string}} imageBitmap
+ * @property {{supported: boolean, fallbackPath: string}} worker
+ * @property {{presentPathSupported: boolean, workerOffscreenSupported: boolean, deterministicFallback: string}} renderPaths
+ */
+
+/** @type {CapabilityMatrix} */
+const DEFAULT_CAPABILITY_MATRIX = Object.freeze({
+  webMidi: Object.freeze({
+    supported: false,
+    enabled: false,
+    fallbackPath: 'audio_only'
+  }),
+  offscreenCanvas: Object.freeze({
+    supported: false,
+    ctorSupported: false,
+    transferControlSupported: false,
+    fallbackPath: 'canvas2d_main_thread'
+  }),
+  imageBitmap: Object.freeze({
+    supported: false,
+    fallbackPath: 'drawimage_main_thread'
+  }),
+  worker: Object.freeze({
+    supported: false,
+    fallbackPath: 'main_thread'
+  }),
+  renderPaths: Object.freeze({
+    presentPathSupported: false,
+    workerOffscreenSupported: false,
+    deterministicFallback: 'canvas2d_main_thread'
+  })
+});
+
+const hasFunction = (value) => typeof value === 'function';
+
+/**
+ * @returns {CapabilityMatrix}
+ */
+const detectRuntimeCapabilities = ({
+  windowRef = (typeof window !== 'undefined' ? window : null),
+  navigatorRef = windowRef?.navigator || (typeof navigator !== 'undefined' ? navigator : null),
+  webMidi = windowRef?.WebMidi || null
+} = {}) => {
+  const requestMidiAccessSupported = hasFunction(navigatorRef?.requestMIDIAccess);
+  const webMidiSupported = requestMidiAccessSupported
+    || !!(webMidi && (hasFunction(webMidi.enable) || webMidi.enabled === true));
+  const webMidiEnabled = !!webMidi?.enabled;
+
+  const offscreenCtorSupported = hasFunction(windowRef?.OffscreenCanvas);
+  const transferControlSupported = hasFunction(windowRef?.HTMLCanvasElement?.prototype?.transferControlToOffscreen);
+  const offscreenSupported = offscreenCtorSupported || transferControlSupported;
+  const canvas2dSupported = hasFunction(windowRef?.document?.createElement)
+    || (typeof document !== 'undefined' && hasFunction(document?.createElement));
+
+  const imageBitmapSupported = hasFunction(windowRef?.createImageBitmap)
+    || (typeof createImageBitmap === 'function');
+  const workerSupported = hasFunction(windowRef?.Worker);
+
+  const presentPathSupported = canvas2dSupported || (offscreenSupported && imageBitmapSupported);
+  const workerOffscreenSupported = offscreenSupported && imageBitmapSupported && workerSupported;
+
+  const renderFallback = workerOffscreenSupported
+    ? 'worker_offscreen'
+    : presentPathSupported
+      ? 'drawimage_present'
+      : 'canvas2d_main_thread';
+
+  return {
+    webMidi: {
+      supported: webMidiSupported,
+      enabled: webMidiEnabled,
+      fallbackPath: webMidiSupported ? 'webmidi' : 'audio_only'
+    },
+    offscreenCanvas: {
+      supported: offscreenSupported,
+      ctorSupported: offscreenCtorSupported,
+      transferControlSupported,
+      fallbackPath: offscreenSupported ? 'offscreen_canvas' : 'canvas2d_main_thread'
+    },
+    imageBitmap: {
+      supported: imageBitmapSupported,
+      fallbackPath: imageBitmapSupported ? 'imagebitmap' : 'drawimage_main_thread'
+    },
+    worker: {
+      supported: workerSupported,
+      fallbackPath: workerSupported ? 'worker' : 'main_thread'
+    },
+    renderPaths: {
+      presentPathSupported,
+      workerOffscreenSupported,
+      deterministicFallback: renderFallback
+    }
+  };
+};
+
+/**
+ * @param {{offscreenPresent?: boolean, workerOffscreen?: boolean}} [requestedFlags]
+ * @param {CapabilityMatrix} [capabilities]
+ */
+const resolveRenderExperimentState = (requestedFlags = {}, capabilities = DEFAULT_CAPABILITY_MATRIX) => {
+  const requestedOffscreen = !!requestedFlags.offscreenPresent;
+  const requestedWorker = !!requestedFlags.workerOffscreen;
+  const cap = capabilities || DEFAULT_CAPABILITY_MATRIX;
+  const presentPathSupported = !!cap.renderPaths?.presentPathSupported;
+  const workerOffscreenSupported = !!cap.renderPaths?.workerOffscreenSupported;
+
+  const offscreenActive = requestedOffscreen && presentPathSupported;
+  const workerActive = requestedWorker && offscreenActive && workerOffscreenSupported;
+
+  let rollbackReason = null;
+  if (requestedOffscreen && !offscreenActive) {
+    rollbackReason = presentPathSupported
+      ? 'present_path_unavailable'
+      : (cap.offscreenCanvas?.supported
+        ? 'imagebitmap_unavailable'
+        : 'offscreen_canvas_unavailable');
+  } else if (requestedWorker && !workerActive) {
+    if (!cap.offscreenCanvas?.supported) {
+      rollbackReason = 'offscreen_canvas_unavailable';
+    } else if (!cap.imageBitmap?.supported) {
+      rollbackReason = 'imagebitmap_unavailable';
+    } else if (!cap.worker?.supported) {
+      rollbackReason = 'worker_unavailable';
+    } else {
+      rollbackReason = 'worker_offscreen_unavailable';
+    }
+  }
+
+  return {
+    presentPathRequested: requestedOffscreen,
+    presentPathActive: offscreenActive,
+    offscreenPresentRequested: requestedOffscreen,
+    offscreenPresentActive: offscreenActive,
+    workerOffscreenRequested: requestedWorker,
+    workerOffscreenActive: workerActive,
+    rollbackReason,
+    capabilityFallback: cap.renderPaths?.deterministicFallback || 'canvas2d_main_thread'
+  };
+};
+
+export {
+  DEFAULT_CAPABILITY_MATRIX,
+  detectRuntimeCapabilities,
+  resolveRenderExperimentState
+};
diff --git a/js/core/dependencies.js b/js/core/dependencies.js
index d595b446..c457adb5 100644
--- a/js/core/dependencies.js
+++ b/js/core/dependencies.js
@@ -1,4 +1,34 @@
 const overrides = new Map();
+let appContext = null;
+let runtimeContext = null;
+
+const RUNTIME_GLOBAL_KEY_ALIASES = Object.freeze({
+  bootNoAutoStart: '__LEMMINGS_BOOT_NO_AUTO_START__',
+  webMidi: 'WebMidi',
+  localStorage: 'localStorage',
+  history: 'history',
+  window: 'window',
+  document: 'document',
+  navigator: 'navigator',
+  location: 'location',
+  caches: 'caches',
+  performance: 'performance',
+  analyticsDisabled: '__LEMMINGS_ANALYTICS_DISABLED__',
+  analyticsHardDisabled: '__LEMMINGS_ANALYTICS_HARD_DISABLED__',
+  analyticsBeaconEnabled: '__LEMMINGS_ANALYTICS_BEACON_ENABLED__',
+  analyticsBeaconEndpoint: '__LEMMINGS_ANALYTICS_BEACON_ENDPOINT__',
+  analyticsSampleRate: '__LEMMINGS_ANALYTICS_SAMPLE_RATE__',
+  rolloutFlags: '__LEMMINGS_ROLLOUT_FLAGS__'
+});
+
+const readGlobalValue = (key) => {
+  if (!key || typeof globalThis === 'undefined') return undefined;
+  const globalKey = RUNTIME_GLOBAL_KEY_ALIASES[key] || key;
+  if (!Object.prototype.hasOwnProperty.call(globalThis, globalKey)) {
+    return undefined;
+  }
+  return globalThis[globalKey];
+};
 
 function setDependency(key, value) {
   if (!key) return;
@@ -19,9 +49,60 @@ function resetDependencies() {
   overrides.clear();
 }
 
+function setAppContext(app) {
+  appContext = app || null;
+}
+
+function getAppContext() {
+  return appContext;
+}
+
+function clearAppContext(expectedApp = null) {
+  if (!expectedApp || expectedApp === appContext) {
+    appContext = null;
+  }
+}
+
+function setRuntimeContext(context = {}) {
+  const next = context && typeof context === 'object' ? context : {};
+  runtimeContext = {
+    ...(runtimeContext || {}),
+    ...next
+  };
+  return { ...runtimeContext };
+}
+
+function clearRuntimeContext() {
+  runtimeContext = null;
+}
+
+function getRuntimeContext() {
+  return runtimeContext ? { ...runtimeContext } : null;
+}
+
+function getRuntimeDependency(key, fallback = null) {
+  if (!key) return fallback;
+  if (runtimeContext && Object.prototype.hasOwnProperty.call(runtimeContext, key)) {
+    const value = runtimeContext[key];
+    return value === undefined ? fallback : value;
+  }
+  const globalValue = readGlobalValue(key);
+  if (globalValue !== undefined) {
+    return globalValue;
+  }
+  return fallback;
+}
+
 export {
   setDependency,
   getDependency,
   clearDependency,
-  resetDependencies
+  resetDependencies,
+  setAppContext,
+  getAppContext,
+  clearAppContext,
+  setRuntimeContext,
+  clearRuntimeContext,
+  getRuntimeContext,
+  getRuntimeDependency
 };
diff --git a/js/core/numberParsing.js b/js/core/numberParsing.js
new file mode 100644
index 00000000..e860d9db
--- /dev/null
+++ b/js/core/numberParsing.js
@@ -0,0 +1,58 @@
+/**
+ * Safely coerce unknown values to numbers without throwing for Symbols.
+ *
+ * @param {unknown} value
+ * @returns {number}
+ */
+const coerceNumber = (value) => {
+  if (typeof value === 'number') return value;
+  try {
+    return Number(value);
+  } catch {
+    return Number.NaN;
+  }
+};
+
+/**
+ * @param {unknown} value
+ * @param {number|null} [fallback]
+ * @returns {number|null}
+ */
+const toFiniteNumber = (value, fallback = null) => {
+  const num = coerceNumber(value);
+  return Number.isFinite(num) ? num : fallback;
+};
+
+const parseInt10 = (value, fallback = null) => {
+  if (value == null) return fallback;
+  const parsed = Number.parseInt(String(value).trim(), 10);
+  return Number.isFinite(parsed) ? parsed : fallback;
+};
+
+const clampNumber = (value, min = -Infinity, max = Infinity) => Math.min(Math.max(value, min), max);
+
+/**
+ * Parse numeric query/input values where bounds are defined in the unscaled
+ * domain and scaling happens only after validation passes.
+ */
+const parseBoundedNumber = (value, {
+  fallback = null,
+  min = -Infinity,
+  max = Infinity,
+  multiplier = 1,
+  integer = false
+} = {}) => {
+  const parsed = toFiniteNumber(value, null);
+  if (parsed == null) return fallback;
+  if (parsed < min || parsed > max) return fallback;
+  const scaled = parsed * multiplier;
+  if (!Number.isFinite(scaled)) return fallback;
+  return integer ? Math.trunc(scaled) : scaled;
+};
+
+export {
+  clampNumber,
+  parseBoundedNumber,
+  parseInt10,
+  toFiniteNumber
+};
diff --git a/js/core/rolloutFlags.js b/js/core/rolloutFlags.js
new file mode 100644
index 00000000..b27b2171
--- /dev/null
+++ b/js/core/rolloutFlags.js
@@ -0,0 +1,125 @@
+/**
+ * @typedef {object} RuntimeRolloutFlags
+ * @property {boolean} historyCodec
+ * @property {boolean} renderPresentPath
+ */
+
+/** @type {Readonly<RuntimeRolloutFlags>} */
+const DEFAULT_RUNTIME_ROLLOUT_FLAGS = Object.freeze({
+  historyCodec: true,
+  renderPresentPath: true
+});
+
+const ROLLOUT_QUERY_KEYS = Object.freeze({
+  historyCodec: Object.freeze({
+    rollout: ['rolloutHistoryCodec'],
+    rollback: ['rollbackHistoryCodec']
+  }),
+  renderPresentPath: Object.freeze({
+    rollout: ['rolloutRenderPresent'],
+    rollback: ['rollbackRenderPresent']
+  })
+});
+
+const BOOL_TRUE = new Set(['', '1', 'true', 'yes', 'on', 'enabled', 'enable']);
+const BOOL_FALSE = new Set(['0', 'false', 'no', 'off', 'disabled', 'disable']);
+
+/**
+ * @param {unknown} value
+ * @returns {boolean | null}
+ */
+const parseBoolish = (value) => {
+  if (value == null) return null;
+  const normalized = String(value).trim().toLowerCase();
+  if (BOOL_TRUE.has(normalized)) return true;
+  if (BOOL_FALSE.has(normalized)) return false;
+  return null;
+};
+
+/**
+ * @param {URLSearchParams | null} query
+ * @param {string[]} [names]
+ * @returns {string | null}
+ */
+const readQueryValue = (query, names = []) => {
+  if (!query) return null;
+  for (const name of names) {
+    if (!query.has(name)) continue;
+    return query.get(name);
+  }
+  return null;
+};
+
+const toRuntimeRolloutObject = (value) => (
+  value && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : {}
+);
+
+const coerceRolloutFlag = (value, fallback) => {
+  if (typeof value === 'boolean') return value;
+  const parsed = parseBoolish(value);
+  return parsed == null ? fallback : parsed;
+};
+
+/**
+ * Resolves rollout flags from defaults, runtime overrides, and query toggles.
+ * Query rollback values always take precedence over rollout values.
+ *
+ * @param {{
+ *   query?: URLSearchParams | null,
+ *   search?: string,
+ *   runtimeFlags?: Partial<RuntimeRolloutFlags> | null,
+ *   defaults?: Partial<RuntimeRolloutFlags> | null
+ * }} [options]
+ * @returns {RuntimeRolloutFlags}
+ */
+const resolveRuntimeRolloutFlags = ({
+  query = null,
+  search = '',
+  runtimeFlags = null,
+  defaults = DEFAULT_RUNTIME_ROLLOUT_FLAGS
+} = {}) => {
+  const activeQuery = query || (
+    typeof URLSearchParams === 'function'
+      ? new URLSearchParams(search || '')
+      : null
+  );
+  const runtime = toRuntimeRolloutObject(runtimeFlags);
+  const resolved = {
+    ...DEFAULT_RUNTIME_ROLLOUT_FLAGS,
+    ...toRuntimeRolloutObject(defaults)
+  };
+
+  for (const key of Object.keys(DEFAULT_RUNTIME_ROLLOUT_FLAGS)) {
+    resolved[key] = coerceRolloutFlag(runtime[key], resolved[key]);
+  }
+
+  const rollbackAll = parseBoolish(readQueryValue(activeQuery, ['rollbackAll']));
+  if (rollbackAll === true) {
+    for (const key of Object.keys(resolved)) {
+      resolved[key] = false;
+    }
+    return resolved;
+  }
+
+  for (const [flagKey, keyConfig] of Object.entries(ROLLOUT_QUERY_KEYS)) {
+    const rollbackValue = parseBoolish(readQueryValue(activeQuery, keyConfig.rollback));
+    if (rollbackValue === true) {
+      resolved[flagKey] = false;
+      continue;
+    }
+    const rolloutValue = parseBoolish(readQueryValue(activeQuery, keyConfig.rollout));
+    if (rolloutValue != null) {
+      resolved[flagKey] = rolloutValue;
+    }
+  }
+
+  return resolved;
+};
+
+export {
+  DEFAULT_RUNTIME_ROLLOUT_FLAGS,
+  ROLLOUT_QUERY_KEYS,
+  resolveRuntimeRolloutFlags
+};
diff --git a/js/core/runtimeProfiles.js b/js/core/runtimeProfiles.js
new file mode 100644
index 00000000..a4e79732
--- /dev/null
+++ b/js/core/runtimeProfiles.js
@@ -0,0 +1,194 @@
+const DEFAULT_RUNTIME_PROFILE = 'classic';
+
+const RUNTIME_PROFILE_ALIASES = Object.freeze({
+  gameplay: 'classic'
+});
+
+const RUNTIME_PROFILE_PRESETS = Object.freeze({
+  classic: Object.freeze({
+    id: 'classic',
+    historyRetention: Object.freeze({
+      enableHistoryCap: true,
+      historyCapTicks: 20000,
+      historyWarnTicks: 15000
+    }),
+    instrumentation: Object.freeze({
+      performanceAPI: false,
+      perfMetrics: false,
+      perfOverlay: false
+    }),
+    rendering: Object.freeze({
+      offscreenPresentExperiment: false,
+      workerOffscreenExperiment: false
+    }),
+    logging: Object.freeze({
+      debug: false
+    })
+  }),
+  midi: Object.freeze({
+    id: 'midi',
+    historyRetention: Object.freeze({
+      enableHistoryCap: true,
+      historyCapTicks: 22000,
+      historyWarnTicks: 16500
+    }),
+    instrumentation: Object.freeze({
+      performanceAPI: false,
+      perfMetrics: false,
+      perfOverlay: false
+    }),
+    rendering: Object.freeze({
+      offscreenPresentExperiment: false,
+      workerOffscreenExperiment: false
+    }),
+    logging: Object.freeze({
+      debug: false
+    })
+  }),
+  editor: Object.freeze({
+    id: 'editor',
+    historyRetention: Object.freeze({
+      enableHistoryCap: true,
+      historyCapTicks: 16000,
+      historyWarnTicks: 12000
+    }),
+    instrumentation: Object.freeze({
+      performanceAPI: false,
+      perfMetrics: false,
+      perfOverlay: false
+    }),
+    rendering: Object.freeze({
+      offscreenPresentExperiment: false,
+      workerOffscreenExperiment: false
+    }),
+    logging: Object.freeze({
+      debug: false
+    })
+  }),
+  e2e: Object.freeze({
+    id: 'e2e',
+    historyRetention: Object.freeze({
+      enableHistoryCap: true,
+      historyCapTicks: 12000,
+      historyWarnTicks: 9000
+    }),
+    instrumentation: Object.freeze({
+      performanceAPI: false,
+      perfMetrics: false,
+      perfOverlay: false
+    }),
+    rendering: Object.freeze({
+      offscreenPresentExperiment: false,
+      workerOffscreenExperiment: false
+    }),
+    logging: Object.freeze({
+      debug: false
+    })
+  }),
+  perf: Object.freeze({
+    id: 'perf',
+    historyRetention: Object.freeze({
+      enableHistoryCap: true,
+      historyCapTicks: 12000,
+      historyWarnTicks: 9000
+    }),
+    instrumentation: Object.freeze({
+      performanceAPI: true,
+      perfMetrics: true,
+      perfOverlay: true
+    }),
+    rendering: Object.freeze({
+      offscreenPresentExperiment: false,
+      workerOffscreenExperiment: false
+    }),
+    logging: Object.freeze({
+      debug: false
+    })
+  })
+});
+
+const SPECIAL_HISTORY_RETENTION_POLICIES = Object.freeze({
+  endless: Object.freeze({
+    enableHistoryCap: true,
+    historyCapTicks: 24000,
+    historyWarnTicks: 18000
+  }),
+  bench: Object.freeze({
+    enableHistoryCap: true,
+    historyCapTicks: 12000,
+    historyWarnTicks: 9000
+  })
+});
+
+/**
+ * @param {unknown} profile
+ * @returns {string}
+ */
+const normalizeRuntimeProfile = (profile) => {
+  const raw = String(profile || '').trim().toLowerCase();
+  const normalized = RUNTIME_PROFILE_ALIASES[raw] || raw;
+  if (RUNTIME_PROFILE_PRESETS[normalized]) return normalized;
+  return DEFAULT_RUNTIME_PROFILE;
+};
+
+/**
+ * @param {unknown} profile
+ * @returns {Readonly<{
+ *   id: string,
+ *   historyRetention: {
+ *     enableHistoryCap: boolean,
+ *     historyCapTicks: number,
+ *     historyWarnTicks: number
+ *   },
+ *   instrumentation: {
+ *     performanceAPI: boolean,
+ *     perfMetrics: boolean,
+ *     perfOverlay: boolean
+ *   },
+ *   rendering: {
+ *     offscreenPresentExperiment: boolean,
+ *     workerOffscreenExperiment: boolean
+ *   },
+ *   logging: {
+ *     debug: boolean
+ *   }
+ * }>}
+ */
+const getRuntimeProfilePreset = (profile) => {
+  const normalized = normalizeRuntimeProfile(profile);
+  return RUNTIME_PROFILE_PRESETS[normalized] || RUNTIME_PROFILE_PRESETS[DEFAULT_RUNTIME_PROFILE];
+};
+
+/** @returns {string[]} */
+const getRuntimeProfileIds = () => Object.keys(RUNTIME_PROFILE_PRESETS);
+
+/**
+ * @param {unknown} profile
+ * @returns {{enableHistoryCap?: boolean, historyCapTicks?: number, historyWarnTicks?: number}}
+ */
+const getProfileHistoryRetention = (profile) => {
+  const preset = getRuntimeProfilePreset(profile);
+  return { ...(preset.historyRetention || {}) };
+};
+
+/**
+ * @param {string} name
+ * @returns {{enableHistoryCap: boolean, historyCapTicks: number, historyWarnTicks: number} | null}
+ */
+const getSpecialHistoryRetention = (name) => {
+  const policy = SPECIAL_HISTORY_RETENTION_POLICIES[name];
+  if (!policy) return null;
+  return { ...policy };
+};
+
+export {
+  DEFAULT_RUNTIME_PROFILE,
+  RUNTIME_PROFILE_ALIASES,
+  RUNTIME_PROFILE_PRESETS,
+  SPECIAL_HISTORY_RETENTION_POLICIES,
+  getProfileHistoryRetention,
+  getRuntimeProfileIds,
+  getRuntimeProfilePreset,
+  getSpecialHistoryRetention,
+  normalizeRuntimeProfile
+};
diff --git a/js/core/seededRandom.js b/js/core/seededRandom.js
new file mode 100644
index 00000000..b47a57dc
--- /dev/null
+++ b/js/core/seededRandom.js
@@ -0,0 +1,53 @@
+const FNV_OFFSET_BASIS_32 = 0x811c9dc5;
+const FNV_PRIME_32 = 0x01000193;
+
+const hashString32 = (value, seed = FNV_OFFSET_BASIS_32) => {
+  let hash = seed >>> 0;
+  for (let i = 0; i < value.length; i += 1) {
+    hash ^= value.charCodeAt(i);
+    hash = Math.imul(hash, FNV_PRIME_32) >>> 0;
+  }
+  return hash >>> 0;
+};
+
+const normalizeSeed = (seedLike, fallback = FNV_OFFSET_BASIS_32) => {
+  if (Number.isFinite(seedLike)) {
+    return (Math.trunc(seedLike) >>> 0);
+  }
+  if (typeof seedLike === 'string') {
+    const trimmed = seedLike.trim();
+    if (!trimmed) return fallback >>> 0;
+    if (/^0x[0-9a-f]+$/i.test(trimmed)) {
+      return (Number.parseInt(trimmed, 16) >>> 0);
+    }
+    if (/^[+-]?\d+$/.test(trimmed)) {
+      return (Number.parseInt(trimmed, 10) >>> 0);
+    }
+    return hashString32(trimmed);
+  }
+  return fallback >>> 0;
+};
+
+const deriveSeed = (seedLike, scope) => {
+  const base = normalizeSeed(seedLike);
+  if (!scope) return base;
+  return hashString32(String(scope), base);
+};
+
+const createSeededRandom = (seedLike) => {
+  let state = normalizeSeed(seedLike, 0x6d2b79f5);
+  return () => {
+    state = (state + 0x6d2b79f5) >>> 0;
+    let mixed = state;
+    mixed = Math.imul(mixed ^ (mixed >>> 15), mixed | 1);
+    mixed ^= mixed + Math.imul(mixed ^ (mixed >>> 7), mixed | 61);
+    return ((mixed ^ (mixed >>> 14)) >>> 0) / 4294967296;
+  };
+};
+
+export {
+  hashString32,
+  normalizeSeed,
+  deriveSeed,
+  createSeededRandom
+};
diff --git a/js/data/BinaryReader.js b/js/data/BinaryReader.js
index 573a6624..a684160e 100644
--- a/js/data/BinaryReader.js
+++ b/js/data/BinaryReader.js
@@ -1,8 +1,12 @@
 import { BaseLogger } from '../util/LogHandler.js';
 
 /**
- * Reads binary data with flexible offset, length, and endian options.
- * Used for game/resource file decoding.
+ * Reads binary data through a logical window over a backing byte array.
+ * Explicit offsets are logical offsets relative to this reader's window.
+ *
+ * Legacy method names are preserved for compatibility:
+ * - readInt/readWord read big-endian values.
+ * - readIntBE/readWordBE read little-endian values despite the BE suffix.
  * @class
  */
 class BinaryReader extends BaseLogger {
@@ -61,6 +65,7 @@ class BinaryReader extends BaseLogger {
     this.#pos = this.#hiddenOffset;
 
     let dataLength = 0;
+    let baseHiddenOffset = 0;
     if (dataArray == null) {
       this.#data = new Uint8Array(0);
       dataLength = 0;
@@ -68,6 +73,7 @@ class BinaryReader extends BaseLogger {
     } else if (dataArray instanceof BinaryReader) {
       this.#data = dataArray.data;
       dataLength = dataArray.length;
+      baseHiddenOffset = dataArray.hiddenOffset;
       this.log.log('BinaryReader from BinaryReader; size: ' + dataLength);
     } else if (dataArray instanceof Uint8Array) {
       this.#data = dataArray;
@@ -114,8 +120,8 @@ class BinaryReader extends BaseLogger {
     }
 
     if (length == null) length = dataLength - offset;
-    this.#hiddenOffset = offset;
-    this.#length = length;
+    this.#hiddenOffset = baseHiddenOffset + offset;
+    this.#length = Math.max(0, Math.min(length, dataLength - offset));
     this.#pos = this.#hiddenOffset;
     this.ready = Promise.resolve(this.#data);
   }
@@ -140,100 +146,136 @@ class BinaryReader extends BaseLogger {
     return this.#pos;
   }
 
+  #resolveReadOffset(offset) {
+    if (offset === undefined || offset === null) return this.#pos;
+    return this.#hiddenOffset + Math.trunc(Number(offset));
+  }
+
+  #windowEnd() {
+    return Math.min(this.#data.length, this.#hiddenOffset + this.#length);
+  }
+
+  #canRead(pos, byteCount, label) {
+    if (!Number.isFinite(pos) || !Number.isFinite(byteCount) || byteCount < 0) {
+      this.log.log(`${label}: invalid offset for ${this.filename}`);
+      return false;
+    }
+    if (pos < this.#hiddenOffset || pos + byteCount > this.#windowEnd()) {
+      this.log.log(
+        `${label}: read out of data: ${this.filename} - window: ${this.#hiddenOffset}+${this.#length} @ ${pos}`
+      );
+      return false;
+    }
+    return true;
+  }
+
   /**
-   * Reads one byte at the current position (or absolute offset if given).
+   * Reads one byte at the current position or logical offset.
    * Advances position after read.
-   * @param {number} [offset] - Absolute (not logical) offset in data. If provided, sets the position.
+   * @param {number} [offset] - Logical offset. If provided, sets the position.
    * @returns {number} Byte value (0–255), or 0 if out-of-bounds.
    */
   readByte(offset) {
-    if (offset !== undefined && offset !== null) {
-      this.#pos = (offset + this.#hiddenOffset);
-    }
-    if (this.#pos < 0 || this.#pos >= this.#data.length) {
-      this.log.log(`read out of data: ${this.filename} - size: ${this.#data.length} @ ${this.#pos}`);
+    this.#pos = this.#resolveReadOffset(offset);
+    if (!this.#canRead(this.#pos, 1, 'readByte')) {
       return 0;
     }
     return this.#data[this.#pos++];
   }
 
   /**
-   * Reads a little-endian integer (4 bytes by default).
+   * Legacy alias for readIntBigEndian().
    * @param {number} [length=4] - Number of bytes to read (1–4).
-   * @param {number} [offset] - Absolute offset in data. If omitted, uses current position.
+   * @param {number} [offset] - Logical offset. If omitted, uses current position.
    * @returns {number} Parsed integer.
    */
   readInt(length = 4, offset) {
-    if (offset == null) offset = this.#pos;
-    if (length === 4) {
-      // Fast path for 4 bytes, little-endian
-      const v = (this.#data[offset] << 24) |
-                (this.#data[offset + 1] << 16) |
-                (this.#data[offset + 2] << 8) |
-                (this.#data[offset + 3]);
-      this.#pos = offset + 4;
-      return v;
-    }
-    let v = 0;
-    for (let i = length; i > 0; i--) {
-      v = (v << 8) | this.#data[offset++];
-    }
-    this.#pos = offset;
-    return v;
+    return this.readIntBigEndian(length, offset);
   }
 
   /**
-   * Reads a big-endian 4-byte integer.
-   * @param {number} [offset] - Absolute offset in data.
+   * Legacy alias for readIntLittleEndian(4, offset).
+   * @param {number} [offset] - Logical offset.
    * @returns {number} Parsed integer.
    */
   readIntBE(offset) {
-    if (offset == null) offset = this.#pos;
-    const v = (this.#data[offset]) |
-              (this.#data[offset + 1] << 8) |
-              (this.#data[offset + 2] << 16) |
-              (this.#data[offset + 3] << 24);
-    this.#pos = offset + 4;
-    return v;
+    return this.readIntLittleEndian(4, offset);
   }
 
   /**
-   * Reads a big-endian 2-byte word.
-   * @param {number} [offset] - Absolute offset in data.
+   * Legacy alias for readWordBigEndian().
+   * @param {number} [offset] - Logical offset.
    * @returns {number} Parsed word (0–65535).
    */
   readWord(offset) {
-    if (offset == null) offset = this.#pos;
-    const v = (this.#data[offset] << 8) | (this.#data[offset + 1]);
-    this.#pos = offset + 2;
-    return v;
+    return this.readWordBigEndian(offset);
   }
 
   /**
-   * Reads a little-endian 2-byte word.
-   * @param {number} [offset] - Absolute offset in data.
+   * Legacy alias for readWordLittleEndian().
+   * @param {number} [offset] - Logical offset.
    * @returns {number} Parsed word (0–65535).
    */
   readWordBE(offset) {
-    if (offset == null) offset = this.#pos;
-    const v = (this.#data[offset]) | (this.#data[offset + 1] << 8);
-    this.#pos = offset + 2;
+    return this.readWordLittleEndian(offset);
+  }
+
+  readIntBigEndian(length = 4, offset) {
+    const byteCount = Math.trunc(Number(length));
+    const pos = this.#resolveReadOffset(offset);
+    if (byteCount < 1 || byteCount > 4 || !this.#canRead(pos, byteCount, 'readIntBigEndian')) {
+      return 0;
+    }
+    let v = 0;
+    for (let i = 0; i < byteCount; i += 1) {
+      v = (v << 8) | this.#data[pos + i];
+    }
+    this.#pos = pos + byteCount;
+    return v;
+  }
+
+  readIntLittleEndian(length = 4, offset) {
+    const byteCount = Math.trunc(Number(length));
+    const pos = this.#resolveReadOffset(offset);
+    if (byteCount < 1 || byteCount > 4 || !this.#canRead(pos, byteCount, 'readIntLittleEndian')) {
+      return 0;
+    }
+    let v = 0;
+    for (let i = byteCount - 1; i >= 0; i -= 1) {
+      v = (v << 8) | this.#data[pos + i];
+    }
+    this.#pos = pos + byteCount;
+    return v;
+  }
+
+  readWordBigEndian(offset) {
+    const pos = this.#resolveReadOffset(offset);
+    if (!this.#canRead(pos, 2, 'readWordBigEndian')) return 0;
+    const v = (this.#data[pos] << 8) | this.#data[pos + 1];
+    this.#pos = pos + 2;
+    return v;
+  }
+
+  readWordLittleEndian(offset) {
+    const pos = this.#resolveReadOffset(offset);
+    if (!this.#canRead(pos, 2, 'readWordLittleEndian')) return 0;
+    const v = this.#data[pos] | (this.#data[pos + 1] << 8);
+    this.#pos = pos + 2;
     return v;
   }
 
   /**
    * Reads a string of the given length from the current position.
    * @param {number} length - Number of bytes/chars to read.
-   * @param {number} [offset] - If provided, sets position before reading.
+   * @param {number} [offset] - Logical offset. If provided, sets position before reading.
    * @returns {string} The decoded string (ASCII).
    */
   readString(length, offset) {
-    if (offset !== undefined && offset !== null) {
-      this.#pos = offset + this.#hiddenOffset;
-    }
+    this.#pos = this.#resolveReadOffset(offset);
     let chars = [];
+    const end = this.#windowEnd();
     for (let i = 0; i < length; i++) {
-      if (this.#pos >= this.#data.length) break;
+      if (this.#pos < this.#hiddenOffset || this.#pos >= end) break;
       chars.push(String.fromCharCode(this.#data[this.#pos++]));
     }
     return chars.join('');
diff --git a/js/data/FileContainer.js b/js/data/FileContainer.js
index aeb2cac5..805a0420 100644
--- a/js/data/FileContainer.js
+++ b/js/data/FileContainer.js
@@ -1,4 +1,4 @@
-import { BaseLogger, withPerformance } from '../util/LogHandler.js';
+import { BaseLogger } from '../util/LogHandler.js';
 import { BinaryReader } from './BinaryReader.js';
 import { UnpackFilePart } from './UnpackFilePart.js';
 
@@ -50,45 +50,45 @@ class FileContainer extends BaseLogger {
    * @param {BinaryReader} fileReader - Input file reader.
    */
   read(fileReader) {
-    withPerformance(
-      'FileContainer.read',
-      {
-        track: 'FileContainer',
-        trackGroup: 'IO',
-        color: 'secondary-dark',
-        tooltipText: `read ${fileReader.filename}`
-      },
-      () => {
-        this.#parts.length = 0; // Reset
-        let pos = 0;
-        const HEADER_SIZE = 10;
+    const endMeasure = this.startMeasure('FileContainer.read', {
+      track: 'FileContainer',
+      trackGroup: 'IO',
+      color: 'secondary-dark',
+      tooltipText: `read ${fileReader.filename}`
+    });
+    try {
+      this.#parts.length = 0; // Reset
+      let pos = 0;
+      const HEADER_SIZE = 10;
 
-        while (pos + HEADER_SIZE < fileReader.length) {
-          fileReader.setOffset(pos);
+      while (pos + HEADER_SIZE < fileReader.length) {
+        fileReader.setOffset(pos);
 
-          // New part instance
-          let part = new UnpackFilePart(fileReader);
-          part.offset = pos + HEADER_SIZE;
-          // Header parsing
-          part.initialBufferLen = fileReader.readByte();
-          part.checksum = fileReader.readByte();
-          part.unknown1 = fileReader.readWord();
-          part.decompressedSize = fileReader.readWord();
-          part.unknown0 = fileReader.readWord();
-          let size = fileReader.readWord();
-          part.compressedSize = size - HEADER_SIZE;
-          part.index = this.#parts.length;
+        // New part instance
+        let part = new UnpackFilePart(fileReader);
+        part.offset = pos + HEADER_SIZE;
+        // Header parsing
+        part.initialBufferLen = fileReader.readByte();
+        part.checksum = fileReader.readByte();
+        part.unknown1 = fileReader.readWord();
+        part.decompressedSize = fileReader.readWord();
+        part.unknown0 = fileReader.readWord();
+        let size = fileReader.readWord();
+        part.compressedSize = size - HEADER_SIZE;
+        part.index = this.#parts.length;
 
-          // Sanity checks
-          if (part.offset < 0 || size > 0xFFFFFF || size < HEADER_SIZE) {
-            this.log.log(`out of sync ${fileReader.filename}`);
-            break;
-          }
-          this.#parts.push(part);
-          pos += size;
+        // Sanity checks
+        if (part.offset < 0 || size > 0xFFFFFF || size < HEADER_SIZE) {
+          this.log.log(`out of sync ${fileReader.filename}`);
+          break;
         }
-        this.log.debug(`${fileReader.filename} has ${this.#parts.length} file-parts.`);
-      })();
+        this.#parts.push(part);
+        pos += size;
+      }
+      this.log.debug(`${fileReader.filename} has ${this.#parts.length} file-parts.`);
+    } finally {
+      endMeasure();
+    }
   }
 
   /** @returns {UnpackFilePart[]} Array of all file parts (read-only view). */
diff --git a/js/data/FileProvider.js b/js/data/FileProvider.js
index 5221028b..ac3e2e0d 100644
--- a/js/data/FileProvider.js
+++ b/js/data/FileProvider.js
@@ -1,624 +1 @@
-import { BaseLogger } from '../util/LogHandler.js';
-import { BinaryReader } from './BinaryReader.js';
-import { getDependency } from '../core/dependencies.js';
-import '../util/LogHandler.js';
-
-const LOCAL_STORAGE_PREFIX = 'lem-cache:';
-const LOCAL_STORAGE_MAX_BYTES = 4 * 1024 * 1024;
-const IDB_NAME = 'lemmings-cache';
-const IDB_VERSION = 1;
-const IDB_STORE_ENTRIES = 'entries';
-const IDB_STORE_PAYLOADS = 'payloads';
-const IDB_STORE_META = 'meta';
-const IDB_MAX_BYTES = 50 * 1024 * 1024;
-
-/**
- * FileProvider with transparent in‑memory caching.
- */
-class FileProvider extends BaseLogger {
-  constructor(rootPath) {
-    super();
-    this.rootPath = rootPath;
-
-    /**
-     * Cache mapping full URL → Promise<BinaryReader> or Promise<string>.
-     * Store the Promise itself so concurrent callers share one in‑flight XHR.
-     * @type {Map<string, Promise<any>>}
-     */
-    this._cache = new Map();
-    this._idbPromise = null;
-    this._idbDisabled = false;
-    this._cacheStats = { localStorageBytes: 0, indexedDbBytes: 0 };
-  }
-
-  /** Empty the cache (debug helper). */
-  clearCache() {
-    this._cache.clear();
-  }
-
-  /** Return cache size telemetry for debug/UI. */
-  getCacheStats() {
-    return {
-      memoryEntries: this._cache.size,
-      localStorageBytes: this._cacheStats.localStorageBytes,
-      indexedDbBytes: this._cacheStats.indexedDbBytes
-    };
-  }
-
-  /**
-   * Load binary data from URL( rootPath + path + filename ).
-   * Returns a Promise that resolves to BinaryReader.
-   * @param {string} path    sub‑directory below rootPath (leading slash optional)
-   * @param {?string} filename  optional file name; when omitted `path` is treated as full relative URL
-   * @param {{forceReload?: boolean}} [opts]
-   */
-  loadBinary(path, filename = null, opts = {}) {
-    const url = this._buildUrl(path, filename);
-    if (!opts.forceReload && this._cache.has(url)) {
-      return this._cache.get(url);
-    }
-
-    let promise;
-    if (!opts.forceReload) {
-      if (this._canUseIndexedDb()) {
-        promise = this._loadFromIndexedDb(url, 'binary', path)
-          .then((cached) => {
-            if (cached) return cached.value;
-            const fallback = this._loadFromLocalStorage(url, 'binary', path);
-            if (fallback) return fallback.value;
-            this.log.debug('loading: ' + url);
-            return this._fetchBinary(url, path);
-          })
-          .catch(() => {
-            const fallback = this._loadFromLocalStorage(url, 'binary', path);
-            if (fallback) return fallback.value;
-            this.log.debug('loading: ' + url);
-            return this._fetchBinary(url, path);
-          });
-      } else {
-        const cached = this._loadFromLocalStorage(url, 'binary', path);
-        if (cached) {
-          promise = Promise.resolve(cached.value);
-        }
-      }
-    }
-
-    if (!promise) {
-      this.log.debug('loading: ' + url);
-      promise = this._fetchBinary(url, path);
-    }
-
-    const guarded = promise.catch((err) => {
-      if (!opts.forceReload) this._cache.delete(url);
-      throw err;
-    });
-
-    if (!opts.forceReload) {
-      this._cache.set(url, guarded);
-    }
-    return guarded;
-  }
-
-  /**
-   * Load text file as string; cached with the same rules as binary.
-   */
-  loadString(url, opts = {}) {
-    if (!opts.forceReload && this._cache.has(url)) {
-      return this._cache.get(url);
-    }
-
-    let promise;
-    if (!opts.forceReload) {
-      if (this._canUseIndexedDb()) {
-        promise = this._loadFromIndexedDb(url, 'text')
-          .then((cached) => {
-            if (cached) return cached.value;
-            const fallback = this._loadFromLocalStorage(url, 'text');
-            if (fallback) return fallback.value;
-            return this._fetchText(url);
-          })
-          .catch(() => {
-            const fallback = this._loadFromLocalStorage(url, 'text');
-            if (fallback) return fallback.value;
-            return this._fetchText(url);
-          });
-      } else {
-        const cached = this._loadFromLocalStorage(url, 'text');
-        if (cached) {
-          promise = Promise.resolve(cached.value);
-        }
-      }
-    }
-
-    if (!promise) {
-      // this.log.debug('loading text: ' + url);
-      promise = this._fetchText(url);
-    }
-
-    const guarded = promise.catch((err) => {
-      if (!opts.forceReload) this._cache.delete(url);
-      throw err;
-    });
-
-    if (!opts.forceReload) {
-      this._cache.set(url, guarded);
-    }
-    return guarded;
-  }
-
-  _buildUrl(path, filename) {
-    return (
-      this.rootPath +
-      path +
-      (filename == null ? '' : '/' + filename)
-    );
-  }
-
-  _filenameFromUrl(url) {
-    if (!url) return '';
-    url = url.split('#')[0].split('?')[0];
-    return url.substring(url.lastIndexOf('/') + 1);
-  }
-
-  _localStorageKey(url) {
-    return LOCAL_STORAGE_PREFIX + url;
-  }
-
-  _canUseIndexedDb() {
-    return !this._idbDisabled && typeof indexedDB !== 'undefined';
-  }
-
-  _idbRequest(request) {
-    return new Promise((resolve, reject) => {
-      request.onsuccess = () => resolve(request.result);
-      request.onerror = () => reject(request.error);
-    });
-  }
-
-  _openIndexedDb() {
-    if (!this._canUseIndexedDb()) return Promise.resolve(null);
-    if (this._idbPromise) return this._idbPromise;
-    this._idbPromise = new Promise((resolve) => {
-      const request = indexedDB.open(IDB_NAME, IDB_VERSION);
-      request.onupgradeneeded = () => {
-        const db = request.result;
-        if (!db.objectStoreNames.contains(IDB_STORE_ENTRIES)) {
-          const store = db.createObjectStore(IDB_STORE_ENTRIES, { keyPath: 'url' });
-          store.createIndex('lastAccess', 'lastAccess', { unique: false });
-        }
-        if (!db.objectStoreNames.contains(IDB_STORE_PAYLOADS)) {
-          db.createObjectStore(IDB_STORE_PAYLOADS, { keyPath: 'url' });
-        }
-        if (!db.objectStoreNames.contains(IDB_STORE_META)) {
-          db.createObjectStore(IDB_STORE_META, { keyPath: 'key' });
-        }
-      };
-      request.onsuccess = () => {
-        const db = request.result;
-        db.onversionchange = () => db.close();
-        resolve(db);
-      };
-      request.onerror = () => {
-        this._idbDisabled = true;
-        resolve(null);
-      };
-    });
-    return this._idbPromise;
-  }
-
-  async _loadFromIndexedDb(url, type, path = '') {
-    const db = await this._openIndexedDb();
-    if (!db) return null;
-    try {
-      const tx = db.transaction([IDB_STORE_ENTRIES, IDB_STORE_PAYLOADS], 'readonly');
-      const entries = tx.objectStore(IDB_STORE_ENTRIES);
-      const payloads = tx.objectStore(IDB_STORE_PAYLOADS);
-      const entry = await this._idbRequest(entries.get(url));
-      if (!entry || entry.type !== type) return null;
-      const payload = await this._idbRequest(payloads.get(url));
-      if (!payload || payload.data == null) return null;
-      this._verifyCache(url, entry);
-      this._touchIndexedDbEntry(url, entry);
-      let value;
-      if (type === 'binary') {
-        const Reader = getDependency('BinaryReader', BinaryReader);
-        value = new Reader(payload.data, 0, null, this._filenameFromUrl(url), path);
-      } else {
-        value = payload.data;
-      }
-      return { value, entry };
-    } catch (e) {
-      return null;
-    }
-  }
-
-  async _touchIndexedDbEntry(url, entry) {
-    const db = await this._openIndexedDb();
-    if (!db) return;
-    try {
-      const tx = db.transaction(IDB_STORE_ENTRIES, 'readwrite');
-      const store = tx.objectStore(IDB_STORE_ENTRIES);
-      store.put({ ...entry, lastAccess: Date.now() });
-    } catch (e) {
-      // ignore
-    }
-  }
-
-  async _storeInCache(url, entry) {
-    const stored = await this._storeInIndexedDb(url, entry);
-    if (!stored) {
-      this._storeInLocalStorage(url, entry);
-    }
-  }
-
-  async _storeInIndexedDb(url, entry) {
-    const db = await this._openIndexedDb();
-    if (!db) return false;
-    try {
-      const now = Date.now();
-      const size = this._estimateEntrySize(entry);
-      const tx = db.transaction([IDB_STORE_ENTRIES, IDB_STORE_PAYLOADS, IDB_STORE_META], 'readwrite');
-      const entries = tx.objectStore(IDB_STORE_ENTRIES);
-      const payloads = tx.objectStore(IDB_STORE_PAYLOADS);
-      const metaStore = tx.objectStore(IDB_STORE_META);
-      const existing = await this._idbRequest(entries.get(url));
-      const prevSize = existing?.size || 0;
-      entries.put({
-        url,
-        type: entry.type,
-        etag: entry.etag || null,
-        lastModified: entry.lastModified || null,
-        hash: entry.hash || null,
-        size,
-        lastAccess: now
-      });
-      payloads.put({ url, data: entry.data });
-      const meta = await this._idbRequest(metaStore.get('totalBytes'));
-      const total = Math.max(0, (meta?.value || 0) - prevSize + size);
-      metaStore.put({ key: 'totalBytes', value: total });
-      this._cacheStats.indexedDbBytes = total;
-      tx.oncomplete = () => {
-        if (total > IDB_MAX_BYTES) {
-          this._pruneIndexedDb(total);
-        }
-      };
-      return true;
-    } catch (e) {
-      return false;
-    }
-  }
-
-  async _pruneIndexedDb(totalBytes) {
-    const db = await this._openIndexedDb();
-    if (!db) return;
-    let remaining = totalBytes;
-    if (remaining <= IDB_MAX_BYTES) return;
-    try {
-      const tx = db.transaction([IDB_STORE_ENTRIES, IDB_STORE_PAYLOADS, IDB_STORE_META], 'readwrite');
-      const entries = tx.objectStore(IDB_STORE_ENTRIES);
-      const payloads = tx.objectStore(IDB_STORE_PAYLOADS);
-      const metaStore = tx.objectStore(IDB_STORE_META);
-      const index = entries.index('lastAccess');
-      const cursorRequest = index.openCursor();
-      cursorRequest.onsuccess = () => {
-        const cursor = cursorRequest.result;
-        if (!cursor || remaining <= IDB_MAX_BYTES) {
-          metaStore.put({ key: 'totalBytes', value: Math.max(0, remaining) });
-          this._cacheStats.indexedDbBytes = Math.max(0, remaining);
-          return;
-        }
-        const entry = cursor.value;
-        const size = entry?.size || 0;
-        entries.delete(entry.url);
-        payloads.delete(entry.url);
-        remaining = Math.max(0, remaining - size);
-        cursor.continue();
-      };
-    } catch (e) {
-      // ignore
-    }
-  }
-
-  _estimateEntrySize(entry) {
-    if (!entry) return 0;
-    if (entry.type === 'binary') {
-      if (entry.data instanceof ArrayBuffer) return entry.data.byteLength;
-      if (ArrayBuffer.isView(entry.data)) return entry.data.byteLength;
-    }
-    if (typeof entry.data === 'string') {
-      return this._estimateTextSize(entry.data);
-    }
-    return 0;
-  }
-
-  _estimateTextSize(text) {
-    if (typeof TextEncoder !== 'undefined') {
-      return new TextEncoder().encode(text).length;
-    }
-    return text.length || 0;
-  }
-
-  _getLocalStorageEntries() {
-    if (typeof localStorage === 'undefined') return [];
-    const entries = [];
-    if (typeof localStorage.length === 'number' && typeof localStorage.key === 'function') {
-      for (let i = 0; i < localStorage.length; i++) {
-        const key = localStorage.key(i);
-        if (!key || !key.startsWith(LOCAL_STORAGE_PREFIX)) continue;
-        const value = localStorage.getItem(key);
-        entries.push({ key, value });
-      }
-      return entries;
-    }
-    if (localStorage.store && typeof localStorage.store.forEach === 'function') {
-      localStorage.store.forEach((value, key) => {
-        if (!String(key).startsWith(LOCAL_STORAGE_PREFIX)) return;
-        entries.push({ key, value });
-      });
-    }
-    return entries;
-  }
-
-  _getLocalStorageUsage() {
-    return this._getLocalStorageEntries()
-      .reduce((total, entry) => total + (entry.value ? String(entry.value).length : 0), 0);
-  }
-
-  _updateLocalStorageStats() {
-    this._cacheStats.localStorageBytes = this._getLocalStorageUsage();
-  }
-
-  _serializeLocalStorageEntry(entry) {
-    const next = { ...entry, lastAccess: entry.lastAccess || Date.now() };
-    let json = JSON.stringify({ ...next, size: 0 });
-    next.size = json.length;
-    json = JSON.stringify(next);
-    next.size = json.length;
-    return { entry: next, json };
-  }
-
-  _setLocalStorageItem(key, json) {
-    try {
-      localStorage.setItem(key, json);
-      return true;
-    } catch (e) {
-      return false;
-    }
-  }
-
-  _evictLocalStorage(requiredBytes = 0) {
-    const entries = this._getLocalStorageEntries();
-    if (!entries.length) return;
-    let total = 0;
-    const parsed = [];
-    for (const entry of entries) {
-      const raw = entry.value;
-      total += raw ? String(raw).length : 0;
-      let parsedEntry = null;
-      try {
-        parsedEntry = raw ? JSON.parse(raw) : null;
-      } catch (e) {
-        parsedEntry = null;
-      }
-      parsed.push({
-        key: entry.key,
-        lastAccess: parsedEntry?.lastAccess || 0,
-        size: parsedEntry?.size || (raw ? String(raw).length : 0)
-      });
-    }
-    const target = Math.max(0, LOCAL_STORAGE_MAX_BYTES - requiredBytes);
-    if (total <= target) {
-      this._cacheStats.localStorageBytes = total;
-      return;
-    }
-    parsed.sort((a, b) => a.lastAccess - b.lastAccess);
-    for (const entry of parsed) {
-      if (total <= target) break;
-      localStorage.removeItem(entry.key);
-      total = Math.max(0, total - entry.size);
-    }
-    this._cacheStats.localStorageBytes = total;
-  }
-
-  _touchLocalStorageEntry(url, entry) {
-    if (!entry) return;
-    entry.lastAccess = Date.now();
-    const key = this._localStorageKey(url);
-    const serialized = this._serializeLocalStorageEntry(entry);
-    if (this._setLocalStorageItem(key, serialized.json)) {
-      this._cacheStats.localStorageBytes = Math.max(
-        this._cacheStats.localStorageBytes,
-        this._getLocalStorageUsage()
-      );
-    }
-  }
-
-  _loadFromLocalStorage(url, type, path = '') {
-    try {
-      if (typeof localStorage === 'undefined') return null;
-      const item = localStorage.getItem(this._localStorageKey(url));
-      if (!item) return null;
-      const entry = JSON.parse(item);
-      if (entry.type !== type) return null;
-
-      // kick off async validation of cache
-      this._verifyCache(url, entry);
-
-      let value;
-      if (type === 'binary') {
-        const buf = this._base64ToArrayBuffer(entry.data);
-        const Reader = getDependency('BinaryReader', BinaryReader);
-        value = new Reader(buf, 0, null, this._filenameFromUrl(url), path);
-      } else {
-        value = entry.data;
-      }
-      this._touchLocalStorageEntry(url, entry);
-      return { value, entry };
-    } catch (e) {
-      return null;
-    }
-  }
-
-  async _verifyCache(url, entry) {
-    const head = await this._fetchHead(url);
-    if (!head) return;
-    if (entry.etag && head.etag && entry.etag === head.etag) return;
-    if (entry.lastModified && head.lastModified && entry.lastModified === head.lastModified) return;
-    try {
-      if (entry.type === 'binary') {
-        await this._fetchBinary(url, '');
-      } else {
-        await this._fetchText(url);
-      }
-    } catch (e) {
-      console.log('cache update error', e);
-    }
-  }
-
-  async _fetchBinary(url, path) {
-    const response = await new Promise((resolve, reject) => {
-      const xhr = new XMLHttpRequest();
-      xhr.onload = () => {
-        if (xhr.status >= 200 && xhr.status < 300) {
-          const headers = {
-            etag: typeof xhr.getResponseHeader === 'function' ? xhr.getResponseHeader('ETag') : null,
-            lastModified: typeof xhr.getResponseHeader === 'function' ? xhr.getResponseHeader('Last-Modified') : null,
-          };
-          resolve({ buffer: xhr.response, headers });
-        } else {
-          const err = new Error('error load file: ' + url);
-          this.log.log(err.message);
-          reject(err);
-        }
-      };
-      xhr.onerror = () => {
-        const err = new Error('error load file: ' + url);
-        this.log.log(err.message);
-        reject(err);
-      };
-      xhr.open('GET', url);
-      xhr.responseType = 'arraybuffer';
-      xhr.send();
-    });
-
-    const buf = response.buffer;
-    const Reader = getDependency('BinaryReader', BinaryReader);
-    const reader = new Reader(buf, 0, null, this._filenameFromUrl(url), path);
-    const hash = await this._hashBuffer(buf);
-    await this._storeInCache(url, { type: 'binary', data: buf, hash, ...response.headers });
-    return reader;
-  }
-
-  async _fetchText(url) {
-    const response = await new Promise((resolve, reject) => {
-      const xhr = new XMLHttpRequest();
-      xhr.onload = () => {
-        if (xhr.status >= 200 && xhr.status < 300) {
-          const headers = {
-            etag: typeof xhr.getResponseHeader === 'function' ? xhr.getResponseHeader('ETag') : null,
-            lastModified: typeof xhr.getResponseHeader === 'function' ? xhr.getResponseHeader('Last-Modified') : null,
-          };
-          resolve({ text: xhr.response, headers });
-        } else {
-          const err = new Error('error load file: ' + url);
-          this.log.log(err.message);
-          reject(err);
-        }
-      };
-      xhr.onerror = () => {
-        const err = new Error('error load file: ' + url);
-        this.log.log(err.message);
-        reject(err);
-      };
-      xhr.open('GET', url);
-      xhr.responseType = 'text';
-      xhr.send();
-    });
-
-    const text = response.text;
-    const hash = await this._hashString(text);
-    await this._storeInCache(url, { type: 'text', data: text, hash, ...response.headers });
-    return text;
-  }
-
-  async _fetchHead(url) {
-    if (typeof fetch !== 'function') return null;
-    try {
-      const resp = await fetch(url, { method: 'HEAD' });
-      return { etag: resp.headers.get('ETag'), lastModified: resp.headers.get('Last-Modified') };
-    } catch (e) {
-      return null;
-    }
-  }
-
-  _storeInLocalStorage(url, entry) {
-    if (typeof localStorage === 'undefined') return false;
-    try {
-      const stored = { ...entry };
-      if (stored.type === 'binary' && stored.data instanceof ArrayBuffer) {
-        stored.data = this._arrayBufferToBase64(stored.data);
-      }
-      stored.lastAccess = Date.now();
-      const serialized = this._serializeLocalStorageEntry(stored);
-      const key = this._localStorageKey(url);
-      if (!this._setLocalStorageItem(key, serialized.json)) {
-        this._evictLocalStorage(serialized.entry.size);
-        if (!this._setLocalStorageItem(key, serialized.json)) {
-          return false;
-        }
-      }
-      this._updateLocalStorageStats();
-      return true;
-    } catch (e) {
-      console.log('cache write error', e);
-      return false;
-    }
-  }
-
-  async _hashBuffer(buffer) {
-    if (typeof globalThis.crypto !== 'undefined' && globalThis.crypto.subtle) {
-      const hashBuf = await globalThis.crypto.subtle.digest('SHA-256', buffer);
-      return Array.from(new Uint8Array(hashBuf))
-        .map(b => b.toString(16).padStart(2, '0'))
-        .join('');
-    }
-
-    try {
-      if (this._forceCryptoError) throw new Error('forced');
-      const { createHash } = await import('node:crypto');
-      const hash = createHash('sha256');
-      hash.update(Buffer.from(buffer));
-      return hash.digest('hex');
-    } catch (e) {
-      throw new Error('crypto API not available');
-    }
-  }
-
-  async _hashString(str) {
-    const enc = new TextEncoder();
-    return this._hashBuffer(enc.encode(str));
-  }
-
-  _arrayBufferToBase64(buffer) {
-    const bytes = new Uint8Array(buffer);
-    const chunkSize = 0x8000;
-    const chunks = [];
-    for (let i = 0; i < bytes.byteLength; i += chunkSize) {
-      const chunk = bytes.subarray(i, i + chunkSize);
-      chunks.push(String.fromCharCode(...chunk));
-    }
-    return btoa(chunks.join(''));
-  }
-
-  _base64ToArrayBuffer(base64) {
-    const binary = atob(base64);
-    const len = binary.length;
-    const bytes = new Uint8Array(len);
-    for (let i = 0; i < len; i++) {
-      bytes[i] = binary.charCodeAt(i);
-    }
-    return bytes.buffer;
-  }
-}
-
-export { FileProvider };
+export { FileProvider } from './file-provider/FileProviderCore.js';
diff --git a/js/data/UnpackFilePart.js b/js/data/UnpackFilePart.js
index 46b3022f..fa0b9de1 100644
--- a/js/data/UnpackFilePart.js
+++ b/js/data/UnpackFilePart.js
@@ -1,4 +1,4 @@
-import { BaseLogger, withPerformance } from '../util/LogHandler.js';
+import { BaseLogger } from '../util/LogHandler.js';
 import { BinaryReader } from './BinaryReader.js';
 import { BitReader } from './BitReader.js';
 import { BitWriter } from './BitWriter.js';
@@ -99,61 +99,61 @@ class UnpackFilePart extends BaseLogger {
    * @returns {BinaryReader}
    */
   #doUnpacking(fileReader) {
-    return withPerformance(
-      'doUnpacking',
-      {
-        track: 'UnpackFilePart',
-        trackGroup: 'IO',
-        color: 'tertiary-light',
-        tooltipText: `doUnpacking ${fileReader.filename}`
-      },
-      () => {
-        const bitReader = new BitReader(
-          fileReader,
-          this.#offset,
-          this.#compressedSize,
-          this.#initialBufferLen
-        );
-        const outBuffer = new BitWriter(bitReader, this.#decompressedSize);
-
-        while (!outBuffer.eof() && !bitReader.eof()) {
-          if (bitReader.read(1) === 0) {
-            switch (bitReader.read(1)) {
-            case 0:
-              outBuffer.copyRawData(bitReader.read(3) + 1);
-              break;
-            case 1:
-              outBuffer.copyReferencedData(2, 8);
-              break;
-            }
-          } else {
-            switch (bitReader.read(2)) {
-            case 0:
-              outBuffer.copyReferencedData(3, 9);
-              break;
-            case 1:
-              outBuffer.copyReferencedData(4, 10);
-              break;
-            case 2:
-              outBuffer.copyReferencedData(bitReader.read(8) + 1, 12);
-              break;
-            case 3:
-              outBuffer.copyRawData(bitReader.read(8) + 9);
-              break;
-            }
+    const endMeasure = this.startMeasure('doUnpacking', {
+      track: 'UnpackFilePart',
+      trackGroup: 'IO',
+      color: 'tertiary-light',
+      tooltipText: `doUnpacking ${fileReader.filename}`
+    });
+    try {
+      const bitReader = new BitReader(
+        fileReader,
+        this.#offset,
+        this.#compressedSize,
+        this.#initialBufferLen
+      );
+      const outBuffer = new BitWriter(bitReader, this.#decompressedSize);
+
+      while (!outBuffer.eof() && !bitReader.eof()) {
+        if (bitReader.read(1) === 0) {
+          switch (bitReader.read(1)) {
+          case 0:
+            outBuffer.copyRawData(bitReader.read(3) + 1);
+            break;
+          case 1:
+            outBuffer.copyReferencedData(2, 8);
+            break;
           }
-        }
-
-        if (this.#checksum === 0) {
-          this.log.debug(`doUnpacking(${fileReader.filename}) skipping checksum`);
-        } else if (this.#checksum === bitReader.getCurrentChecksum()) {
-          this.log.debug(`doUnpacking(${fileReader.filename}) done!`);
         } else {
-          this.log.log(`doUnpacking(${fileReader.filename}): Checksum mismatch!`);
+          switch (bitReader.read(2)) {
+          case 0:
+            outBuffer.copyReferencedData(3, 9);
+            break;
+          case 1:
+            outBuffer.copyReferencedData(4, 10);
+            break;
+          case 2:
+            outBuffer.copyReferencedData(bitReader.read(8) + 1, 12);
+            break;
+          case 3:
+            outBuffer.copyRawData(bitReader.read(8) + 9);
+            break;
+          }
         }
-        // Create a BinaryReader over the decompressed buffer
-        return outBuffer.getFileReader(`${fileReader.filename}[${this.#index}]`);
-      }).call(this);
+      }
+
+      if (this.#checksum === 0) {
+        this.log.debug(`doUnpacking(${fileReader.filename}) skipping checksum`);
+      } else if (this.#checksum === bitReader.getCurrentChecksum()) {
+        this.log.debug(`doUnpacking(${fileReader.filename}) done!`);
+      } else {
+        this.log.log(`doUnpacking(${fileReader.filename}): Checksum mismatch!`);
+      }
+      // Create a BinaryReader over the decompressed buffer
+      return outBuffer.getFileReader(`${fileReader.filename}[${this.#index}]`);
+    } finally {
+      endMeasure();
+    }
   }
 }
 
diff --git a/js/data/file-provider/FileProviderCache.js b/js/data/file-provider/FileProviderCache.js
new file mode 100644
index 00000000..9842d0ab
--- /dev/null
+++ b/js/data/file-provider/FileProviderCache.js
@@ -0,0 +1,97 @@
+import {
+  BaseLogger,
+  BinaryReader,
+  IDB_MAX_BYTES,
+  IDB_NAME,
+  IDB_STORE_ENTRIES,
+  IDB_STORE_META,
+  IDB_STORE_PAYLOADS,
+  IDB_VERSION,
+  LOCAL_STORAGE_MAX_BYTES,
+  LOCAL_STORAGE_PREFIX,
+  appendRevisionParam,
+  getDependency,
+  getRuntimeDependency,
+  sanitizeCacheBust
+} from './FileProviderShared.js';
+const fileProviderCacheMethods = {
+  clearCache() {
+    this._cache.clear();
+  },
+
+  async close() {
+    const db = this._idb || await this._idbPromise?.catch?.(() => null);
+    db?.close?.();
+    this._idb = null;
+    this._idbPromise = null;
+  },
+
+  dispose() {
+    this._cache.clear();
+    this._validationPromises.clear();
+    this.close();
+  },
+
+  getCacheStats() {
+    return {
+      memoryEntries: this._cache.size,
+      localStorageBytes: this._cacheStats.localStorageBytes,
+      indexedDbBytes: this._cacheStats.indexedDbBytes
+    };
+  },
+
+  async _storeInCache(url, entry) {
+    const stored = await this._storeInIndexedDb(url, entry);
+    if (!stored) {
+      this._storeInLocalStorage(url, entry);
+    }
+  },
+
+  _estimateEntrySize(entry) {
+    if (!entry) return 0;
+    if (entry.type === 'binary') {
+      if (entry.data instanceof ArrayBuffer) return entry.data.byteLength;
+      if (ArrayBuffer.isView(entry.data)) return entry.data.byteLength;
+    }
+    if (typeof entry.data === 'string') {
+      return this._estimateTextSize(entry.data);
+    }
+    return 0;
+  },
+
+  _estimateTextSize(text) {
+    if (typeof TextEncoder !== 'undefined') {
+      return new TextEncoder().encode(text).length;
+    }
+    return text.length || 0;
+  },
+
+  _scheduleCacheValidation(url, entry) {
+    if (!url || !entry || this._validationPromises.has(url)) return;
+    const promise = this._verifyCache(url, entry)
+      .catch(() => {})
+      .finally(() => {
+        if (this._validationPromises.get(url) === promise) {
+          this._validationPromises.delete(url);
+        }
+      });
+    this._validationPromises.set(url, promise);
+  },
+
+  async _verifyCache(url, entry) {
+    const head = await this._fetchHead(url);
+    if (!head) return;
+    if (entry.etag && head.etag && entry.etag === head.etag) return;
+    if (entry.lastModified && head.lastModified && entry.lastModified === head.lastModified) return;
+    try {
+      if (entry.type === 'binary') {
+        await this._fetchBinary(url, '');
+      } else {
+        await this._fetchText(url);
+      }
+    } catch (e) {
+      this.log.log('cache update error', e);
+    }
+  }
+};
+export { fileProviderCacheMethods };
\ No newline at end of file
diff --git a/js/data/file-provider/FileProviderCore.js b/js/data/file-provider/FileProviderCore.js
new file mode 100644
index 00000000..fae021a8
--- /dev/null
+++ b/js/data/file-provider/FileProviderCore.js
@@ -0,0 +1,75 @@
+import {
+  BaseLogger,
+  BinaryReader,
+  IDB_MAX_BYTES,
+  IDB_NAME,
+  IDB_STORE_ENTRIES,
+  IDB_STORE_META,
+  IDB_STORE_PAYLOADS,
+  IDB_VERSION,
+  LOCAL_STORAGE_MAX_BYTES,
+  LOCAL_STORAGE_PREFIX,
+  appendRevisionParam,
+  getDependency,
+  getRuntimeDependency,
+  sanitizeCacheBust
+} from './FileProviderShared.js';
+import { fileProviderCacheMethods } from './FileProviderCache.js';
+import { fileProviderStorageMethods } from './FileProviderStorage.js';
+import { fileProviderFetchMethods } from './FileProviderFetch.js';
+import { fileProviderHashMethods } from './FileProviderHash.js';
+class FileProvider extends BaseLogger {
+  constructor(rootPath, options = {}) {
+    super();
+    this.rootPath = rootPath;
+    this._cacheBustRevision = sanitizeCacheBust(
+      options.cacheBustRevision ?? options.cacheBust ?? null
+    );
+
+    /**
+       * Cache mapping full URL → Promise<BinaryReader> or Promise<string>.
+       * Store the Promise itself so concurrent callers share one in‑flight XHR.
+       * @type {Map<string, Promise<any>>}
+       */
+    this._cache = new Map();
+    this._idbPromise = null;
+    this._idb = null;
+    this._idbDisabled = false;
+    this._validationPromises = new Map();
+    this._cacheStats = { localStorageBytes: 0, indexedDbBytes: 0 };
+    this._storage = Object.hasOwn(options, 'localStorage')
+      ? options.localStorage
+      : undefined;
+    this._indexedDB = Object.hasOwn(options, 'indexedDB')
+      ? options.indexedDB
+      : (typeof globalThis !== 'undefined' ? globalThis.indexedDB : null);
+    this._crypto = Object.hasOwn(options, 'crypto')
+      ? options.crypto
+      : null;
+    this._hasFetchOverride = Object.hasOwn(options, 'fetch');
+    this._fetch = this._hasFetchOverride ? options.fetch : null;
+    this._hasXhrOverride = Object.hasOwn(options, 'XMLHttpRequest') ||
+        Object.hasOwn(options, 'createXMLHttpRequest');
+    this._XMLHttpRequest = Object.hasOwn(options, 'XMLHttpRequest')
+      ? options.XMLHttpRequest
+      : null;
+    this._createXMLHttpRequest = typeof options.createXMLHttpRequest === 'function'
+      ? options.createXMLHttpRequest
+      : null;
+  }
+
+  _filenameFromUrl(url) {
+    if (!url) return '';
+    url = url.split('#')[0].split('?')[0];
+    return url.substring(url.lastIndexOf('/') + 1);
+  }
+}
+for (const methods of [
+  fileProviderCacheMethods,
+  fileProviderStorageMethods,
+  fileProviderFetchMethods,
+  fileProviderHashMethods
+]) {
+  Object.defineProperties(FileProvider.prototype, Object.getOwnPropertyDescriptors(methods));
+}
+export { FileProvider };
\ No newline at end of file
diff --git a/js/data/file-provider/FileProviderFetch.js b/js/data/file-provider/FileProviderFetch.js
new file mode 100644
index 00000000..918721c0
--- /dev/null
+++ b/js/data/file-provider/FileProviderFetch.js
@@ -0,0 +1,214 @@
+import {
+  BaseLogger,
+  BinaryReader,
+  IDB_MAX_BYTES,
+  IDB_NAME,
+  IDB_STORE_ENTRIES,
+  IDB_STORE_META,
+  IDB_STORE_PAYLOADS,
+  IDB_VERSION,
+  LOCAL_STORAGE_MAX_BYTES,
+  LOCAL_STORAGE_PREFIX,
+  appendRevisionParam,
+  getDependency,
+  getRuntimeDependency,
+  sanitizeCacheBust
+} from './FileProviderShared.js';
+const fileProviderFetchMethods = {
+  loadBinary(path, filename = null, opts = {}) {
+    const url = this._buildUrl(path, filename);
+    if (!opts.forceReload && this._cache.has(url)) {
+      return this._cache.get(url);
+    }
+
+    let promise;
+    if (!opts.forceReload) {
+      if (this._canUseIndexedDb()) {
+        promise = this._loadFromIndexedDb(url, 'binary', path)
+          .then((cached) => {
+            if (cached) return cached.value;
+            const fallback = this._loadFromLocalStorage(url, 'binary', path);
+            if (fallback) return fallback.value;
+            this.log.debug('loading: ' + url);
+            return this._fetchBinary(url, path);
+          })
+          .catch(() => {
+            const fallback = this._loadFromLocalStorage(url, 'binary', path);
+            if (fallback) return fallback.value;
+            this.log.debug('loading: ' + url);
+            return this._fetchBinary(url, path);
+          });
+      } else {
+        const cached = this._loadFromLocalStorage(url, 'binary', path);
+        if (cached) {
+          promise = Promise.resolve(cached.value);
+        }
+      }
+    }
+
+    if (!promise) {
+      this.log.debug('loading: ' + url);
+      promise = this._fetchBinary(url, path);
+    }
+
+    const guarded = promise.catch((err) => {
+      if (!opts.forceReload) this._cache.delete(url);
+      throw err;
+    });
+
+    if (!opts.forceReload) {
+      this._cache.set(url, guarded);
+    }
+    return guarded;
+  },
+
+  loadString(url, opts = {}) {
+    const resolvedUrl = this._appendCacheBust(url);
+    if (!opts.forceReload && this._cache.has(resolvedUrl)) {
+      return this._cache.get(resolvedUrl);
+    }
+
+    let promise;
+    if (!opts.forceReload) {
+      if (this._canUseIndexedDb()) {
+        promise = this._loadFromIndexedDb(resolvedUrl, 'text')
+          .then((cached) => {
+            if (cached) return cached.value;
+            const fallback = this._loadFromLocalStorage(resolvedUrl, 'text');
+            if (fallback) return fallback.value;
+            return this._fetchText(resolvedUrl);
+          })
+          .catch(() => {
+            const fallback = this._loadFromLocalStorage(resolvedUrl, 'text');
+            if (fallback) return fallback.value;
+            return this._fetchText(resolvedUrl);
+          });
+      } else {
+        const cached = this._loadFromLocalStorage(resolvedUrl, 'text');
+        if (cached) {
+          promise = Promise.resolve(cached.value);
+        }
+      }
+    }
+
+    if (!promise) {
+      // this.log.debug('loading text: ' + url);
+      promise = this._fetchText(resolvedUrl);
+    }
+
+    const guarded = promise.catch((err) => {
+      if (!opts.forceReload) this._cache.delete(resolvedUrl);
+      throw err;
+    });
+
+    if (!opts.forceReload) {
+      this._cache.set(resolvedUrl, guarded);
+    }
+    return guarded;
+  },
+
+  _createXhr() {
+    if (this._createXMLHttpRequest) {
+      return this._createXMLHttpRequest();
+    }
+    const XhrCtor = this._hasXhrOverride
+      ? this._XMLHttpRequest
+      : (typeof XMLHttpRequest !== 'undefined' ? XMLHttpRequest : null);
+    if (typeof XhrCtor !== 'function') {
+      throw new Error('XMLHttpRequest API not available');
+    }
+    return new XhrCtor();
+  },
+
+  async _fetchBinary(url, path) {
+    const response = await new Promise((resolve, reject) => {
+      const xhr = this._createXhr();
+      xhr.onload = () => {
+        if (xhr.status >= 200 && xhr.status < 300) {
+          const headers = {
+            etag: typeof xhr.getResponseHeader === 'function' ? xhr.getResponseHeader('ETag') : null,
+            lastModified: typeof xhr.getResponseHeader === 'function' ? xhr.getResponseHeader('Last-Modified') : null,
+          };
+          resolve({ buffer: xhr.response, headers });
+        } else {
+          const err = new Error('error load file: ' + url);
+          this.log.log(err.message);
+          reject(err);
+        }
+      };
+      xhr.onerror = () => {
+        const err = new Error('error load file: ' + url);
+        this.log.log(err.message);
+        reject(err);
+      };
+      xhr.open('GET', url);
+      xhr.responseType = 'arraybuffer';
+      xhr.send();
+    });
+
+    const buf = response.buffer;
+    const Reader = getDependency('BinaryReader', BinaryReader);
+    const reader = new Reader(buf, 0, null, this._filenameFromUrl(url), path);
+    let hash = null;
+    try {
+      hash = await this._tryHashBuffer(buf);
+    } catch (e) {
+      hash = null;
+    }
+    await this._storeInCache(url, { type: 'binary', data: buf, hash, ...response.headers })
+      .catch(() => {});
+    return reader;
+  },
+
+  async _fetchText(url) {
+    const response = await new Promise((resolve, reject) => {
+      const xhr = this._createXhr();
+      xhr.onload = () => {
+        if (xhr.status >= 200 && xhr.status < 300) {
+          const headers = {
+            etag: typeof xhr.getResponseHeader === 'function' ? xhr.getResponseHeader('ETag') : null,
+            lastModified: typeof xhr.getResponseHeader === 'function' ? xhr.getResponseHeader('Last-Modified') : null,
+          };
+          resolve({ text: xhr.response, headers });
+        } else {
+          const err = new Error('error load file: ' + url);
+          this.log.log(err.message);
+          reject(err);
+        }
+      };
+      xhr.onerror = () => {
+        const err = new Error('error load file: ' + url);
+        this.log.log(err.message);
+        reject(err);
+      };
+      xhr.open('GET', url);
+      xhr.responseType = 'text';
+      xhr.send();
+    });
+
+    const text = response.text;
+    let hash = null;
+    try {
+      hash = await this._tryHashString(text);
+    } catch (e) {
+      hash = null;
+    }
+    await this._storeInCache(url, { type: 'text', data: text, hash, ...response.headers })
+      .catch(() => {});
+    return text;
+  },
+
+  async _fetchHead(url) {
+    const fetchRef = this._hasFetchOverride
+      ? this._fetch
+      : (typeof fetch === 'function' ? fetch : null);
+    if (typeof fetchRef !== 'function') return null;
+    try {
+      const resp = await fetchRef(url, { method: 'HEAD' });
+      return { etag: resp.headers.get('ETag'), lastModified: resp.headers.get('Last-Modified') };
+    } catch (e) {
+      return null;
+    }
+  }
+};
+export { fileProviderFetchMethods };
\ No newline at end of file
diff --git a/js/data/file-provider/FileProviderHash.js b/js/data/file-provider/FileProviderHash.js
new file mode 100644
index 00000000..a875179a
--- /dev/null
+++ b/js/data/file-provider/FileProviderHash.js
@@ -0,0 +1,76 @@
+import {
+  BaseLogger,
+  BinaryReader,
+  IDB_MAX_BYTES,
+  IDB_NAME,
+  IDB_STORE_ENTRIES,
+  IDB_STORE_META,
+  IDB_STORE_PAYLOADS,
+  IDB_VERSION,
+  LOCAL_STORAGE_MAX_BYTES,
+  LOCAL_STORAGE_PREFIX,
+  appendRevisionParam,
+  getDependency,
+  getRuntimeDependency,
+  sanitizeCacheBust
+} from './FileProviderShared.js';
+const fileProviderHashMethods = {
+  async _tryHashBuffer(buffer) {
+    const cryptoRef = this._crypto || (typeof globalThis !== 'undefined' ? globalThis.crypto : null);
+    if (cryptoRef?.subtle) {
+      try {
+        const hashBuf = await cryptoRef.subtle.digest('SHA-256', buffer);
+        return Array.from(new Uint8Array(hashBuf))
+          .map(b => b.toString(16).padStart(2, '0'))
+          .join('');
+      } catch (e) {
+        return null;
+      }
+    }
+    return null;
+  },
+
+  async _tryHashString(str) {
+    if (typeof TextEncoder === 'undefined') return null;
+    const enc = new TextEncoder();
+    return this._tryHashBuffer(enc.encode(str));
+  },
+
+  async _hashBuffer(buffer) {
+    const hash = await this._tryHashBuffer(buffer);
+    if (hash != null) {
+      return hash;
+    }
+    throw new Error('crypto API not available');
+  },
+
+  async _hashString(str) {
+    if (typeof TextEncoder !== 'undefined') {
+      const enc = new TextEncoder();
+      return this._hashBuffer(enc.encode(str));
+    }
+    throw new Error('crypto API not available');
+  },
+
+  _arrayBufferToBase64(buffer) {
+    const bytes = new Uint8Array(buffer);
+    const chunkSize = 0x8000;
+    const chunks = [];
+    for (let i = 0; i < bytes.byteLength; i += chunkSize) {
+      const chunk = bytes.subarray(i, i + chunkSize);
+      chunks.push(String.fromCharCode(...chunk));
+    }
+    return btoa(chunks.join(''));
+  },
+
+  _base64ToArrayBuffer(base64) {
+    const binary = atob(base64);
+    const len = binary.length;
+    const bytes = new Uint8Array(len);
+    for (let i = 0; i < len; i++) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes.buffer;
+  }
+};
+export { fileProviderHashMethods };
\ No newline at end of file
diff --git a/js/data/file-provider/FileProviderShared.js b/js/data/file-provider/FileProviderShared.js
new file mode 100644
index 00000000..aa936950
--- /dev/null
+++ b/js/data/file-provider/FileProviderShared.js
@@ -0,0 +1,31 @@
+import { BaseLogger } from '../../util/LogHandler.js';
+import { BinaryReader } from '../BinaryReader.js';
+import { getDependency, getRuntimeDependency } from '../../core/dependencies.js';
+import { appendRevisionParam, sanitizeCacheBust } from '../../core/cacheBust.js';
+import '../../util/LogHandler.js';
+
+const LOCAL_STORAGE_PREFIX = 'lem-cache:';
+const LOCAL_STORAGE_MAX_BYTES = 4 * 1024 * 1024;
+const IDB_NAME = 'lemmings-cache';
+const IDB_VERSION = 1;
+const IDB_STORE_ENTRIES = 'entries';
+const IDB_STORE_PAYLOADS = 'payloads';
+const IDB_STORE_META = 'meta';
+const IDB_MAX_BYTES = 50 * 1024 * 1024;
+
+export {
+  BaseLogger,
+  BinaryReader,
+  IDB_MAX_BYTES,
+  IDB_NAME,
+  IDB_STORE_ENTRIES,
+  IDB_STORE_META,
+  IDB_STORE_PAYLOADS,
+  IDB_VERSION,
+  LOCAL_STORAGE_MAX_BYTES,
+  LOCAL_STORAGE_PREFIX,
+  appendRevisionParam,
+  getDependency,
+  getRuntimeDependency,
+  sanitizeCacheBust
+};
diff --git a/js/data/file-provider/FileProviderStorage.js b/js/data/file-provider/FileProviderStorage.js
new file mode 100644
index 00000000..7204061d
--- /dev/null
+++ b/js/data/file-provider/FileProviderStorage.js
@@ -0,0 +1,364 @@
+import {
+  BaseLogger,
+  BinaryReader,
+  IDB_MAX_BYTES,
+  IDB_NAME,
+  IDB_STORE_ENTRIES,
+  IDB_STORE_META,
+  IDB_STORE_PAYLOADS,
+  IDB_VERSION,
+  LOCAL_STORAGE_MAX_BYTES,
+  LOCAL_STORAGE_PREFIX,
+  appendRevisionParam,
+  getDependency,
+  getRuntimeDependency,
+  sanitizeCacheBust
+} from './FileProviderShared.js';
+const fileProviderStorageMethods = {
+  _buildUrl(path, filename) {
+    const raw = (
+      this.rootPath +
+        path +
+        (filename == null ? '' : '/' + filename)
+    );
+    return this._appendCacheBust(raw);
+  },
+
+  _appendCacheBust(url) {
+    return appendRevisionParam(url, this._cacheBustRevision);
+  },
+
+  _localStorageKey(url) {
+    return LOCAL_STORAGE_PREFIX + url;
+  },
+
+  _canUseIndexedDb() {
+    return !this._idbDisabled && !!this._indexedDB?.open;
+  },
+
+  _getLocalStorage() {
+    return this._storage === undefined
+      ? getRuntimeDependency('localStorage', null)
+      : this._storage;
+  },
+
+  _idbRequest(request) {
+    return new Promise((resolve, reject) => {
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error);
+    });
+  },
+
+  _idbTransactionDone(tx) {
+    if (!tx || !('oncomplete' in tx || 'onabort' in tx || 'onerror' in tx)) {
+      return Promise.resolve(true);
+    }
+    return new Promise((resolve, reject) => {
+      tx.oncomplete = () => resolve(true);
+      tx.onabort = () => reject(tx.error || new Error('indexedDB transaction aborted'));
+      tx.onerror = () => reject(tx.error || new Error('indexedDB transaction failed'));
+    });
+  },
+
+  _openIndexedDb() {
+    if (!this._canUseIndexedDb()) return Promise.resolve(null);
+    if (this._idb) return Promise.resolve(this._idb);
+    if (this._idbPromise) return this._idbPromise;
+    this._idbPromise = new Promise((resolve) => {
+      const request = this._indexedDB.open(IDB_NAME, IDB_VERSION);
+      request.onupgradeneeded = () => {
+        const db = request.result;
+        if (!db.objectStoreNames.contains(IDB_STORE_ENTRIES)) {
+          const store = db.createObjectStore(IDB_STORE_ENTRIES, { keyPath: 'url' });
+          store.createIndex('lastAccess', 'lastAccess', { unique: false });
+        }
+        if (!db.objectStoreNames.contains(IDB_STORE_PAYLOADS)) {
+          db.createObjectStore(IDB_STORE_PAYLOADS, { keyPath: 'url' });
+        }
+        if (!db.objectStoreNames.contains(IDB_STORE_META)) {
+          db.createObjectStore(IDB_STORE_META, { keyPath: 'key' });
+        }
+      };
+      request.onsuccess = () => {
+        const db = request.result;
+        this._idb = db;
+        db.onversionchange = () => {
+          db.close();
+          if (this._idb === db) this._idb = null;
+          this._idbPromise = null;
+        };
+        resolve(db);
+      };
+      request.onerror = () => {
+        this._idbDisabled = true;
+        this._idbPromise = null;
+        resolve(null);
+      };
+    });
+    return this._idbPromise;
+  },
+
+  async _loadFromIndexedDb(url, type, path = '') {
+    const db = await this._openIndexedDb();
+    if (!db) return null;
+    try {
+      const tx = db.transaction([IDB_STORE_ENTRIES, IDB_STORE_PAYLOADS], 'readonly');
+      const entries = tx.objectStore(IDB_STORE_ENTRIES);
+      const payloads = tx.objectStore(IDB_STORE_PAYLOADS);
+      const entry = await this._idbRequest(entries.get(url));
+      if (!entry || entry.type !== type) return null;
+      const payload = await this._idbRequest(payloads.get(url));
+      if (!payload || payload.data == null) return null;
+      this._scheduleCacheValidation(url, entry);
+      this._touchIndexedDbEntry(url, entry);
+      let value;
+      if (type === 'binary') {
+        const Reader = getDependency('BinaryReader', BinaryReader);
+        value = new Reader(payload.data, 0, null, this._filenameFromUrl(url), path);
+      } else {
+        value = payload.data;
+      }
+      return { value, entry };
+    } catch (e) {
+      return null;
+    }
+  },
+
+  async _touchIndexedDbEntry(url, entry) {
+    const db = await this._openIndexedDb();
+    if (!db) return;
+    try {
+      const tx = db.transaction(IDB_STORE_ENTRIES, 'readwrite');
+      const done = this._idbTransactionDone(tx).catch(() => false);
+      const store = tx.objectStore(IDB_STORE_ENTRIES);
+      store.put({ ...entry, lastAccess: Date.now() });
+      await done;
+    } catch (e) {
+      // ignore
+    }
+  },
+
+  async _storeInIndexedDb(url, entry) {
+    const db = await this._openIndexedDb();
+    if (!db) return false;
+    try {
+      const now = Date.now();
+      const size = this._estimateEntrySize(entry);
+      const tx = db.transaction([IDB_STORE_ENTRIES, IDB_STORE_PAYLOADS, IDB_STORE_META], 'readwrite');
+      let transactionError = null;
+      const done = this._idbTransactionDone(tx).catch((err) => {
+        transactionError = err;
+        return false;
+      });
+      const entries = tx.objectStore(IDB_STORE_ENTRIES);
+      const payloads = tx.objectStore(IDB_STORE_PAYLOADS);
+      const metaStore = tx.objectStore(IDB_STORE_META);
+      const existing = await this._idbRequest(entries.get(url));
+      const prevSize = existing?.size || 0;
+      entries.put({
+        url,
+        type: entry.type,
+        etag: entry.etag || null,
+        lastModified: entry.lastModified || null,
+        hash: entry.hash || null,
+        size,
+        lastAccess: now
+      });
+      payloads.put({ url, data: entry.data });
+      const meta = await this._idbRequest(metaStore.get('totalBytes'));
+      const total = Math.max(0, (meta?.value || 0) - prevSize + size);
+      metaStore.put({ key: 'totalBytes', value: total });
+      const committed = await done;
+      if (!committed) {
+        throw transactionError || new Error('indexedDB transaction failed');
+      }
+      this._cacheStats.indexedDbBytes = total;
+      if (total > IDB_MAX_BYTES) {
+        this._pruneIndexedDb(total);
+      }
+      return true;
+    } catch (e) {
+      return false;
+    }
+  },
+
+  async _pruneIndexedDb(totalBytes) {
+    const db = await this._openIndexedDb();
+    if (!db) return;
+    let remaining = totalBytes;
+    if (remaining <= IDB_MAX_BYTES) return;
+    try {
+      const tx = db.transaction([IDB_STORE_ENTRIES, IDB_STORE_PAYLOADS, IDB_STORE_META], 'readwrite');
+      const entries = tx.objectStore(IDB_STORE_ENTRIES);
+      const payloads = tx.objectStore(IDB_STORE_PAYLOADS);
+      const metaStore = tx.objectStore(IDB_STORE_META);
+      const index = entries.index('lastAccess');
+      const cursorRequest = index.openCursor();
+      cursorRequest.onsuccess = () => {
+        const cursor = cursorRequest.result;
+        if (!cursor || remaining <= IDB_MAX_BYTES) {
+          metaStore.put({ key: 'totalBytes', value: Math.max(0, remaining) });
+          this._cacheStats.indexedDbBytes = Math.max(0, remaining);
+          return;
+        }
+        const entry = cursor.value;
+        const size = entry?.size || 0;
+        entries.delete(entry.url);
+        payloads.delete(entry.url);
+        remaining = Math.max(0, remaining - size);
+        cursor.continue();
+      };
+    } catch (e) {
+      // ignore
+    }
+  },
+
+  _getLocalStorageEntries() {
+    const storage = this._getLocalStorage();
+    if (!storage) return [];
+    const entries = [];
+    if (typeof storage.length === 'number' && typeof storage.key === 'function') {
+      for (let i = 0; i < storage.length; i++) {
+        const key = storage.key(i);
+        if (!key || !key.startsWith(LOCAL_STORAGE_PREFIX)) continue;
+        const value = storage.getItem(key);
+        entries.push({ key, value });
+      }
+      return entries;
+    }
+    if (storage.store && typeof storage.store.forEach === 'function') {
+      storage.store.forEach((value, key) => {
+        if (!String(key).startsWith(LOCAL_STORAGE_PREFIX)) return;
+        entries.push({ key, value });
+      });
+    }
+    return entries;
+  },
+
+  _getLocalStorageUsage() {
+    return this._getLocalStorageEntries()
+      .reduce((total, entry) => total + (entry.value ? String(entry.value).length : 0), 0);
+  },
+
+  _updateLocalStorageStats() {
+    this._cacheStats.localStorageBytes = this._getLocalStorageUsage();
+  },
+
+  _serializeLocalStorageEntry(entry) {
+    const next = { ...entry, lastAccess: entry.lastAccess || Date.now() };
+    let json = JSON.stringify({ ...next, size: 0 });
+    next.size = json.length;
+    json = JSON.stringify(next);
+    next.size = json.length;
+    return { entry: next, json };
+  },
+
+  _setLocalStorageItem(key, json) {
+    try {
+      const storage = this._getLocalStorage();
+      if (!storage?.setItem) return false;
+      storage.setItem(key, json);
+      return true;
+    } catch (e) {
+      return false;
+    }
+  },
+
+  _evictLocalStorage(requiredBytes = 0) {
+    const entries = this._getLocalStorageEntries();
+    if (!entries.length) return;
+    let total = 0;
+    const parsed = [];
+    for (const entry of entries) {
+      const raw = entry.value;
+      total += raw ? String(raw).length : 0;
+      let parsedEntry = null;
+      try {
+        parsedEntry = raw ? JSON.parse(raw) : null;
+      } catch (e) {
+        parsedEntry = null;
+      }
+      parsed.push({
+        key: entry.key,
+        lastAccess: parsedEntry?.lastAccess || 0,
+        size: parsedEntry?.size || (raw ? String(raw).length : 0)
+      });
+    }
+    const target = Math.max(0, LOCAL_STORAGE_MAX_BYTES - requiredBytes);
+    if (total <= target) {
+      this._cacheStats.localStorageBytes = total;
+      return;
+    }
+    parsed.sort((a, b) => a.lastAccess - b.lastAccess);
+    for (const entry of parsed) {
+      if (total <= target) break;
+      this._getLocalStorage()?.removeItem?.(entry.key);
+      total = Math.max(0, total - entry.size);
+    }
+    this._cacheStats.localStorageBytes = total;
+  },
+
+  _touchLocalStorageEntry(url, entry) {
+    if (!entry) return;
+    entry.lastAccess = Date.now();
+    const key = this._localStorageKey(url);
+    const serialized = this._serializeLocalStorageEntry(entry);
+    if (this._setLocalStorageItem(key, serialized.json)) {
+      this._cacheStats.localStorageBytes = Math.max(
+        this._cacheStats.localStorageBytes,
+        this._getLocalStorageUsage()
+      );
+    }
+  },
+
+  _loadFromLocalStorage(url, type, path = '') {
+    try {
+      const storage = this._getLocalStorage();
+      if (!storage) return null;
+      const item = storage.getItem(this._localStorageKey(url));
+      if (!item) return null;
+      const entry = JSON.parse(item);
+      if (entry.type !== type) return null;
+
+      this._scheduleCacheValidation(url, entry);
+
+      let value;
+      if (type === 'binary') {
+        const buf = this._base64ToArrayBuffer(entry.data);
+        const Reader = getDependency('BinaryReader', BinaryReader);
+        value = new Reader(buf, 0, null, this._filenameFromUrl(url), path);
+      } else {
+        value = entry.data;
+      }
+      this._touchLocalStorageEntry(url, entry);
+      return { value, entry };
+    } catch (e) {
+      return null;
+    }
+  },
+
+  _storeInLocalStorage(url, entry) {
+    if (!this._getLocalStorage()) return false;
+    try {
+      const stored = { ...entry };
+      if (stored.type === 'binary' && stored.data instanceof ArrayBuffer) {
+        stored.data = this._arrayBufferToBase64(stored.data);
+      }
+      stored.lastAccess = Date.now();
+      const serialized = this._serializeLocalStorageEntry(stored);
+      const key = this._localStorageKey(url);
+      if (!this._setLocalStorageItem(key, serialized.json)) {
+        this._evictLocalStorage(serialized.entry.size);
+        if (!this._setLocalStorageItem(key, serialized.json)) {
+          return false;
+        }
+      }
+      this._updateLocalStorageStats();
+      return true;
+    } catch (e) {
+      this.log.log('cache write error', e);
+      return false;
+    }
+  }
+};
+export { fileProviderStorageMethods };
\ No newline at end of file
diff --git a/js/editor/EditorController.js b/js/editor/EditorController.js
index 2179816c..c9098c1c 100644
--- a/js/editor/EditorController.js
+++ b/js/editor/EditorController.js
@@ -1,1148 +1,4 @@
-import { EditorTools } from './EditorTools.js';
-import { EditorHistory } from './EditorHistory.js';
-import {
-  createTerrainEntry,
-  createGadgetEntry,
-  createSteelEntry,
-  ensureEntryUid,
-  setEntryProp,
-  removeEntryAt
-} from './EditorEntryFactory.js';
-import { findEntryAt, getEntryBounds } from './EditorHitTest.js';
-
-const DEFAULT_GRID = 4;
-const MAX_ENTRANCES = 4;
-const MAX_EXITS = 4;
-const DEFAULT_HANDLE_SIZE = 2;
-const MAX_BRUSH_SIZE = 64;
-
-const snapValue = (value, gridSize) => {
-  if (!Number.isFinite(gridSize) || gridSize <= 1) return Math.round(value);
-  return Math.round(value / gridSize) * gridSize;
-};
-
-const clampSize = (value) => Math.max(1, Math.round(value));
-const clampBrushSize = (value) => Math.min(MAX_BRUSH_SIZE, clampSize(value));
-
-const cloneEntry = (entry, options = {}) => {
-  const props = entry?.props ? { ...entry.props } : {};
-  const order = Array.isArray(entry?.order) ? entry.order.slice() : Object.keys(props);
-  const unknownLines = Array.isArray(entry?.unknownLines) ? entry.unknownLines.slice() : [];
-  const clone = { props, order, unknownLines };
-  if (options.preserveUid && entry?.uid) {
-    clone.uid = entry.uid;
-  } else if (options.assignUid !== false) {
-    ensureEntryUid(clone, options.prefix || 'e');
-  }
-  return clone;
-};
-
-const coerceEntryNumber = (value, fallback = 0) => {
-  return Number.isFinite(value) ? value : fallback;
-};
-
-const normalizeBounds = (x1, y1, x2, y2) => {
-  const left = Math.min(x1, x2);
-  const right = Math.max(x1, x2);
-  const top = Math.min(y1, y2);
-  const bottom = Math.max(y1, y2);
-  return {
-    x: left,
-    y: top,
-    width: Math.max(1, right - left),
-    height: Math.max(1, bottom - top)
-  };
-};
-
-const boundsIntersect = (a, b) => {
-  if (!a || !b) return false;
-  return a.x <= b.x + b.width
-    && a.x + a.width >= b.x
-    && a.y <= b.y + b.height
-    && a.y + a.height >= b.y;
-};
-
-class EditorController {
-  constructor(options = {}) {
-    this.session = options.session || null;
-    this.history = options.history || new EditorHistory();
-    this.tool = options.tool || EditorTools.SELECT;
-    this.gridSize = Number.isFinite(options.gridSize) ? options.gridSize : DEFAULT_GRID;
-    this.snapEnabled = options.snapEnabled !== false;
-    this.brushSize = 1;
-    this.setBrushSize(Number.isFinite(options.brushSize) ? options.brushSize : 1);
-    this.eraseGadgets = !!options.eraseGadgets;
-    this.assets = options.assets || null;
-    this.selectedTerrainId = 0;
-    this.selectedGadgetId = 0;
-    this.selectedTriggerId = null;
-    this.selection = [];
-    this._drag = null;
-    this._resize = null;
-    this._marquee = null;
-    this._steelDraft = null;
-    this._strokeChanged = false;
-    this._stampSet = new Set();
-    this._lastBrushPos = null;
-    this._clipboard = null;
-    this._pasteOffset = 0;
-    this._previewTimer = null;
-    this._pointerDown = false;
-    this._pointerButton = 0;
-    this._previewDelay = Number.isFinite(options.previewDelay) ? options.previewDelay : 60;
-    this.handleSize = Number.isFinite(options.handleSize) ? options.handleSize : DEFAULT_HANDLE_SIZE;
-    this._callbacks = {
-      onSelectionChange: null,
-      onLevelChange: null,
-      onPreviewRequest: null,
-      onMarqueeChange: null
-    };
-  }
-
-  setCallbacks(callbacks = {}) {
-    this._callbacks = { ...this._callbacks, ...callbacks };
-  }
-
-  setAssets(assets) {
-    this.assets = assets || null;
-    const hasId = (list, id) => Array.isArray(list) && list.some(entry => entry?.id === id);
-    if (assets?.terrain?.length && !hasId(assets.terrain, this.selectedTerrainId)) {
-      this.selectedTerrainId = assets.terrain[0].id;
-    }
-    if (assets?.gadgets?.length && !hasId(assets.gadgets, this.selectedGadgetId)) {
-      this.selectedGadgetId = assets.gadgets[0].id;
-    }
-    if (assets?.triggers?.length && !hasId(assets.triggers, this.selectedTriggerId)) {
-      this.selectedTriggerId = assets.triggers[0].id;
-    }
-  }
-
-  resetHistory(label = 'Init') {
-    this.history.clear();
-    this.history.pushSnapshot(this.session?.level, label);
-  }
-
-  setTool(tool) {
-    if (!tool) return;
-    this.tool = tool;
-  }
-
-  setSnapEnabled(enabled) {
-    this.snapEnabled = !!enabled;
-  }
-
-  setBrushSize(size) {
-    const value = Number.isFinite(size) ? size : 1;
-    this.brushSize = clampBrushSize(value);
-  }
-
-  setEraseGadgets(enabled) {
-    this.eraseGadgets = !!enabled;
-  }
-
-  setSelectedTerrain(id) {
-    if (Number.isFinite(id)) this.selectedTerrainId = id;
-  }
-
-  setSelectedGadget(id) {
-    if (Number.isFinite(id)) this.selectedGadgetId = id;
-  }
-
-  setSelectedTrigger(id) {
-    if (Number.isFinite(id)) this.selectedTriggerId = id;
-  }
-
-  _getListForType(type) {
-    if (!this.session?.level) return null;
-    if (type === 'gadget') return this.session.level.gadgets;
-    if (type === 'steel') return this.session.level.steel;
-    return this.session.level.terrains;
-  }
-
-  getSelectedEntries() {
-    if (!this.session?.level || !Array.isArray(this.selection)) return [];
-    const results = [];
-    for (const selected of this.selection) {
-      const list = this._getListForType(selected.type);
-      const entry = Array.isArray(list) ? list[selected.index] : null;
-      if (!entry) continue;
-      results.push({ ...selected, entry });
-    }
-    return results;
-  }
-
-  getSelectedEntry() {
-    const entries = this.getSelectedEntries();
-    if (entries.length !== 1) return null;
-    return entries[0];
-  }
-
-  getSelectionBounds() {
-    const selected = this.getSelectedEntry();
-    if (!selected) return null;
-    if (selected.type === 'steel') {
-      return getEntryBounds(selected.entry, null);
-    }
-    const meta = selected.type === 'gadget'
-      ? this.assets?.gadgetById?.get?.(selected.entry?.props?.PIECE)
-      : this.assets?.terrainById?.get?.(selected.entry?.props?.PIECE);
-    return getEntryBounds(selected.entry, meta);
-  }
-
-  getMarqueeBounds() {
-    if (!this._marquee) return null;
-    return normalizeBounds(
-      this._marquee.startX,
-      this._marquee.startY,
-      this._marquee.x,
-      this._marquee.y
-    );
-  }
-
-  getHandleSize() {
-    return this.handleSize;
-  }
-
-  canResizeSelection() {
-    if (!Array.isArray(this.selection) || this.selection.length !== 1) return false;
-    return this.selection[0].type === 'steel';
-  }
-
-  clearSelection() {
-    this.selection = [];
-    this._callbacks.onSelectionChange?.(this.getSelectedEntries());
-  }
-
-  _setSelection(list) {
-    this.selection = Array.isArray(list) ? list.map(entry => ({
-      type: entry.type,
-      index: entry.index
-    })) : [];
-    this._callbacks.onSelectionChange?.(this.getSelectedEntries());
-  }
-
-  _isSelected(type, index) {
-    return this.selection.some(entry => entry.type === type && entry.index === index);
-  }
-
-  _toggleSelection(hit) {
-    if (!hit) return;
-    if (this._isSelected(hit.type, hit.index)) {
-      this.selection = this.selection.filter(entry => !(entry.type === hit.type && entry.index === hit.index));
-    } else {
-      this.selection = [...this.selection, { type: hit.type, index: hit.index }];
-    }
-    this._callbacks.onSelectionChange?.(this.getSelectedEntries());
-  }
-
-  updateHeader(key, value) {
-    if (!this.session?.level) return;
-    this.session.level.setHeader(key, value);
-    this._callbacks.onLevelChange?.(this.session.level);
-    this._requestPreview('Header');
-  }
-
-  updateSelectedProps(patch = {}) {
-    const entries = this.getSelectedEntries();
-    if (entries.length === 0) return false;
-    for (const selected of entries) {
-      for (const [key, value] of Object.entries(patch)) {
-        const removeIfFalse = typeof value === 'boolean';
-        setEntryProp(selected.entry, key, value, { removeIfFalse });
-      }
-    }
-    this._callbacks.onSelectionChange?.(this.getSelectedEntries());
-    this._requestPreview('Edit');
-    return true;
-  }
-
-  copySelection() {
-    const entries = this.getSelectedEntries();
-    if (entries.length === 0) return false;
-    let minX = Infinity;
-    let minY = Infinity;
-    const items = [];
-    for (const selected of entries) {
-      const props = selected.entry?.props || {};
-      const x = coerceEntryNumber(props.X, 0);
-      const y = coerceEntryNumber(props.Y, 0);
-      minX = Math.min(minX, x);
-      minY = Math.min(minY, y);
-      items.push({
-        type: selected.type,
-        entry: cloneEntry(selected.entry, { assignUid: false }),
-        offsetX: x,
-        offsetY: y
-      });
-    }
-    for (const item of items) {
-      item.offsetX -= minX;
-      item.offsetY -= minY;
-    }
-    this._clipboard = { items, minX, minY };
-    this._pasteOffset = 0;
-    return true;
-  }
-
-  _getPasteStep() {
-    if (this.snapEnabled && Number.isFinite(this.gridSize) && this.gridSize > 0) {
-      return this.gridSize;
-    }
-    return 1;
-  }
-
-  _cloneSelection(entries, offsetX, offsetY) {
-    const next = [];
-    for (const selected of entries) {
-      const list = this._getListForType(selected.type);
-      if (!Array.isArray(list)) continue;
-      const prefix = selected.type === 'gadget' ? 'g' : selected.type === 'steel' ? 's' : 't';
-      const clone = cloneEntry(selected.entry, { prefix });
-      clone.props.X = coerceEntryNumber(clone.props.X, 0) + offsetX;
-      clone.props.Y = coerceEntryNumber(clone.props.Y, 0) + offsetY;
-      list.push(clone);
-      next.push({ type: selected.type, index: list.length - 1 });
-    }
-    if (!next.length) return null;
-    this._setSelection(next);
-    this._markChanged();
-    return next;
-  }
-
-  pasteSelection() {
-    if (!this.session?.level || !this._clipboard?.items?.length) return false;
-    const step = this._getPasteStep();
-    this._pasteOffset += step;
-    const baseX = coerceEntryNumber(this._clipboard.minX, 0) + this._pasteOffset;
-    const baseY = coerceEntryNumber(this._clipboard.minY, 0) + this._pasteOffset;
-    const entries = this._clipboard.items.map(item => ({
-      type: item.type,
-      entry: item.entry,
-      offsetX: item.offsetX,
-      offsetY: item.offsetY
-    }));
-    const selected = [];
-    for (const item of entries) {
-      const list = this._getListForType(item.type);
-      if (!Array.isArray(list)) continue;
-      const prefix = item.type === 'gadget' ? 'g' : item.type === 'steel' ? 's' : 't';
-      const clone = cloneEntry(item.entry, { prefix });
-      clone.props.X = baseX + item.offsetX;
-      clone.props.Y = baseY + item.offsetY;
-      list.push(clone);
-      selected.push({ type: item.type, index: list.length - 1 });
-    }
-    if (!selected.length) return false;
-    this._setSelection(selected);
-    this._commitHistory('Paste');
-    this._requestPreview('Paste');
-    return true;
-  }
-
-  duplicateSelection() {
-    const copied = this.copySelection();
-    if (!copied) return false;
-    const pasted = this.pasteSelection();
-    if (pasted) {
-      this._requestPreview('Duplicate');
-    }
-    return pasted;
-  }
-
-  nudgeSelection(dx, dy, step = 1) {
-    const entries = this.getSelectedEntries();
-    if (entries.length === 0) return false;
-    const moveX = coerceEntryNumber(dx, 0) * step;
-    const moveY = coerceEntryNumber(dy, 0) * step;
-    for (const selected of entries) {
-      const props = selected.entry?.props;
-      if (!props) continue;
-      props.X = coerceEntryNumber(props.X, 0) + moveX;
-      props.Y = coerceEntryNumber(props.Y, 0) + moveY;
-    }
-    this._callbacks.onSelectionChange?.(this.getSelectedEntries());
-    this._commitHistory('Nudge');
-    this._requestPreview('Nudge');
-    return true;
-  }
-
-  snapSelectionToGrid() {
-    const entries = this.getSelectedEntries();
-    if (entries.length === 0) return false;
-    const grid = Number.isFinite(this.gridSize) && this.gridSize > 0 ? this.gridSize : 1;
-    for (const selected of entries) {
-      const props = selected.entry?.props;
-      if (!props) continue;
-      props.X = snapValue(coerceEntryNumber(props.X, 0), grid);
-      props.Y = snapValue(coerceEntryNumber(props.Y, 0), grid);
-    }
-    this._callbacks.onSelectionChange?.(this.getSelectedEntries());
-    this._commitHistory('Snap');
-    this._requestPreview('Snap');
-    return true;
-  }
-
-  deleteSelected() {
-    if (!this.session?.level || this.selection.length === 0) return false;
-    const terrainIndices = [];
-    const gadgetIndices = [];
-    const steelIndices = [];
-    for (const selected of this.selection) {
-      if (selected.type === 'gadget') gadgetIndices.push(selected.index);
-      else if (selected.type === 'steel') steelIndices.push(selected.index);
-      else terrainIndices.push(selected.index);
-    }
-    terrainIndices.sort((a, b) => b - a);
-    gadgetIndices.sort((a, b) => b - a);
-    steelIndices.sort((a, b) => b - a);
-    for (const index of terrainIndices) {
-      removeEntryAt(this.session.level, 'terrain', index);
-    }
-    for (const index of gadgetIndices) {
-      removeEntryAt(this.session.level, 'gadget', index);
-    }
-    for (const index of steelIndices) {
-      removeEntryAt(this.session.level, 'steel', index);
-    }
-    this.selection = [];
-    this._callbacks.onSelectionChange?.(this.getSelectedEntries());
-    this._commitHistory('Delete');
-    this._requestPreview('Delete');
-    return true;
-  }
-
-  _reorderSelection(mode) {
-    if (!this.session?.level || this.selection.length === 0) return false;
-    const groups = {
-      terrain: [],
-      gadget: [],
-      steel: []
-    };
-    for (const selected of this.selection) {
-      if (groups[selected.type]) groups[selected.type].push(selected.index);
-    }
-    const reorderList = (list, indices, dir) => {
-      if (!Array.isArray(list) || indices.length === 0) return null;
-      const unique = Array.from(new Set(indices)).filter(idx => idx >= 0 && idx < list.length);
-      if (!unique.length) return null;
-      const selectedSet = new Set(unique);
-      if (dir === 'front' || dir === 'back') {
-        const ordered = unique.slice().sort((a, b) => a - b).map(idx => list[idx]);
-        const remaining = list.filter((_, idx) => !selectedSet.has(idx));
-        list.length = 0;
-        if (dir === 'front') {
-          list.push(...remaining, ...ordered);
-        } else {
-          list.push(...ordered, ...remaining);
-        }
-        const next = new Map();
-        list.forEach((entry, idx) => next.set(entry, idx));
-        return ordered.map(entry => next.get(entry)).filter(idx => idx != null);
-      }
-      if (dir === 'forward') {
-        const sorted = unique.slice().sort((a, b) => b - a);
-        for (const idx of sorted) {
-          if (idx >= list.length - 1) continue;
-          if (selectedSet.has(idx + 1)) continue;
-          const tmp = list[idx + 1];
-          list[idx + 1] = list[idx];
-          list[idx] = tmp;
-          selectedSet.delete(idx);
-          selectedSet.add(idx + 1);
-        }
-        return Array.from(selectedSet);
-      }
-      if (dir === 'backward') {
-        const sorted = unique.slice().sort((a, b) => a - b);
-        for (const idx of sorted) {
-          if (idx <= 0) continue;
-          if (selectedSet.has(idx - 1)) continue;
-          const tmp = list[idx - 1];
-          list[idx - 1] = list[idx];
-          list[idx] = tmp;
-          selectedSet.delete(idx);
-          selectedSet.add(idx - 1);
-        }
-        return Array.from(selectedSet);
-      }
-      return null;
-    };
-
-    const nextSelection = [];
-    for (const [type, indices] of Object.entries(groups)) {
-      const list = this._getListForType(type);
-      const nextIndices = reorderList(list, indices, mode);
-      if (!nextIndices) continue;
-      for (const idx of nextIndices) {
-        nextSelection.push({ type, index: idx });
-      }
-    }
-    if (!nextSelection.length) return false;
-    this._setSelection(nextSelection);
-    this._commitHistory('Reorder');
-    this._requestPreview('Reorder');
-    return true;
-  }
-
-  bringSelectionToFront() {
-    return this._reorderSelection('front');
-  }
-
-  sendSelectionToBack() {
-    return this._reorderSelection('back');
-  }
-
-  moveSelectionForward() {
-    return this._reorderSelection('forward');
-  }
-
-  moveSelectionBackward() {
-    return this._reorderSelection('backward');
-  }
-
-  undo() {
-    const level = this.history.undo();
-    if (!level || !this.session) return null;
-    this.session.level = level;
-    this.clearSelection();
-    this._callbacks.onLevelChange?.(level);
-    this._requestPreview('Undo');
-    return level;
-  }
-
-  redo() {
-    const level = this.history.redo();
-    if (!level || !this.session) return null;
-    this.session.level = level;
-    this.clearSelection();
-    this._callbacks.onLevelChange?.(level);
-    this._requestPreview('Redo');
-    return level;
-  }
-
-  _snap(x, y) {
-    if (!this.snapEnabled) return { x: Math.round(x), y: Math.round(y) };
-    return { x: snapValue(x, this.gridSize), y: snapValue(y, this.gridSize) };
-  }
-
-  _findSelectionAt(x, y) {
-    const level = this.session?.level;
-    if (!level) return null;
-    const gadgetHit = findEntryAt(level.gadgets, this.assets?.gadgetById, x, y);
-    if (gadgetHit) return { type: 'gadget', ...gadgetHit };
-    const steelHit = findEntryAt(level.steel, null, x, y);
-    if (steelHit) return { type: 'steel', ...steelHit };
-    const terrainHit = findEntryAt(level.terrains, this.assets?.terrainById, x, y);
-    if (terrainHit) return { type: 'terrain', ...terrainHit };
-    return null;
-  }
-
-  _selectHit(hit, options = {}) {
-    if (!hit) {
-      if (!options.preserve) this.clearSelection();
-      return null;
-    }
-    if (options.toggle) {
-      this._toggleSelection(hit);
-      return hit;
-    }
-    if (options.additive) {
-      if (!this._isSelected(hit.type, hit.index)) {
-        this.selection = [...this.selection, { type: hit.type, index: hit.index }];
-        this._callbacks.onSelectionChange?.(this.getSelectedEntries());
-      }
-      return hit;
-    }
-    this._setSelection([hit]);
-    return hit;
-  }
-
-  _buildHandlePoints(bounds) {
-    const midX = bounds.x + Math.round(bounds.width / 2);
-    const midY = bounds.y + Math.round(bounds.height / 2);
-    return [
-      { id: 'nw', x: bounds.x, y: bounds.y },
-      { id: 'n', x: midX, y: bounds.y },
-      { id: 'ne', x: bounds.x + bounds.width, y: bounds.y },
-      { id: 'e', x: bounds.x + bounds.width, y: midY },
-      { id: 'se', x: bounds.x + bounds.width, y: bounds.y + bounds.height },
-      { id: 's', x: midX, y: bounds.y + bounds.height },
-      { id: 'sw', x: bounds.x, y: bounds.y + bounds.height },
-      { id: 'w', x: bounds.x, y: midY }
-    ];
-  }
-
-  _getResizeHandleAt(x, y) {
-    if (!this.canResizeSelection()) return null;
-    const bounds = this.getSelectionBounds();
-    if (!bounds) return null;
-    const half = Math.max(1, Math.floor(this.handleSize / 2));
-    for (const handle of this._buildHandlePoints(bounds)) {
-      if (x >= handle.x - half && x <= handle.x + half
-          && y >= handle.y - half && y <= handle.y + half) {
-        return handle.id;
-      }
-    }
-    return null;
-  }
-
-  _beginMarquee(x, y, additive) {
-    this._marquee = { startX: x, startY: y, x, y, additive: !!additive };
-    this._callbacks.onMarqueeChange?.(this.getMarqueeBounds());
-  }
-
-  _updateMarquee(x, y) {
-    if (!this._marquee) return;
-    this._marquee.x = x;
-    this._marquee.y = y;
-    this._callbacks.onMarqueeChange?.(this.getMarqueeBounds());
-  }
-
-  _clearMarquee() {
-    if (!this._marquee) return;
-    this._marquee = null;
-    this._callbacks.onMarqueeChange?.(null);
-  }
-
-  _applyMarqueeSelection() {
-    if (!this._marquee || !this.session?.level) return;
-    const bounds = this.getMarqueeBounds();
-    const next = this._marquee.additive ? [...this.selection] : [];
-    const addSelection = (type, index) => {
-      if (next.some(entry => entry.type === type && entry.index === index)) return;
-      next.push({ type, index });
-    };
-    const scan = (entries, metaById, type) => {
-      if (!Array.isArray(entries)) return;
-      for (let i = 0; i < entries.length; i++) {
-        const entry = entries[i];
-        const meta = metaById?.get?.(entry?.props?.PIECE);
-        const entryBounds = getEntryBounds(entry, meta);
-        if (boundsIntersect(bounds, entryBounds)) addSelection(type, i);
-      }
-    };
-    scan(this.session.level.terrains, this.assets?.terrainById, 'terrain');
-    scan(this.session.level.gadgets, this.assets?.gadgetById, 'gadget');
-    scan(this.session.level.steel, null, 'steel');
-    this._setSelection(next);
-  }
-
-  _beginStroke() {
-    this._strokeChanged = false;
-    this._stampSet.clear();
-    this._lastBrushPos = null;
-  }
-
-  _removeGadgetsById(pieceId) {
-    if (!this.session?.level || !Number.isFinite(pieceId)) return;
-    const list = this.session.level.gadgets;
-    if (!Array.isArray(list)) return;
-    for (let i = list.length - 1; i >= 0; i--) {
-      const entry = list[i];
-      if (entry?.props?.PIECE === pieceId) {
-        list.splice(i, 1);
-        this._markChanged();
-      }
-    }
-  }
-
-  _hasGadgetId(pieceId) {
-    if (!this.session?.level || !Number.isFinite(pieceId)) return false;
-    const list = this.session.level.gadgets;
-    if (!Array.isArray(list)) return false;
-    return list.some(entry => entry?.props?.PIECE === pieceId);
-  }
-
-  _trimGadgetsById(pieceId, maxCount) {
-    if (!this.session?.level || !Number.isFinite(pieceId)) return;
-    const list = this.session.level.gadgets;
-    if (!Array.isArray(list)) return;
-    const indices = [];
-    for (let i = 0; i < list.length; i++) {
-      if (list[i]?.props?.PIECE === pieceId) indices.push(i);
-    }
-    const excess = indices.length - maxCount;
-    if (excess <= 0) return;
-    for (let i = 0; i < excess; i++) {
-      removeEntryAt(this.session.level, 'gadget', indices[i] - i);
-      this._markChanged();
-    }
-  }
-
-  _markChanged() {
-    this._strokeChanged = true;
-  }
-
-  _getTerrainMeta(id) {
-    const byId = this.assets?.terrainById?.get?.(id);
-    if (byId) return byId;
-    return this.assets?.terrain?.find?.(entry => entry?.id === id) || null;
-  }
-
-  _getGadgetMeta(id) {
-    const byId = this.assets?.gadgetById?.get?.(id);
-    if (byId) return byId;
-    return this.assets?.gadgets?.find?.(entry => entry?.id === id) || null;
-  }
-
-  _centerPlacement(x, y, meta) {
-    const width = Number(meta?.width || 0);
-    const height = Number(meta?.height || 0);
-    const offsetX = width > 0 ? Math.floor(width / 2) : 0;
-    const offsetY = height > 0 ? Math.floor(height / 2) : 0;
-    return {
-      x: x - offsetX,
-      y: y - offsetY
-    };
-  }
-
-  _commitHistory(label) {
-    this.history.pushSnapshot(this.session?.level, label);
-  }
-
-  _requestPreview(label) {
-    if (this._previewTimer) return;
-    const callback = this._callbacks.onPreviewRequest;
-    if (!callback) return;
-    this._previewTimer = setTimeout(() => {
-      this._previewTimer = null;
-      callback(label || 'Update');
-    }, this._previewDelay);
-  }
-
-  _placeTerrainAt(x, y) {
-    if (!this.session?.level) return null;
-    const meta = this._getTerrainMeta(this.selectedTerrainId);
-    const pos = this._centerPlacement(x, y, meta);
-    const entry = createTerrainEntry({
-      styleName: this.session.level.getHeader('STYLE'),
-      piece: this.selectedTerrainId,
-      x: pos.x,
-      y: pos.y
-    });
-    this.session.level.terrains.push(entry);
-    this._markChanged();
-    return entry;
-  }
-
-  _placeGadgetAt(x, y, pieceId) {
-    if (!this.session?.level) return null;
-    const meta = this._getGadgetMeta(pieceId);
-    const pos = this._centerPlacement(x, y, meta);
-    const entry = createGadgetEntry({
-      styleName: this.session.level.getHeader('STYLE'),
-      piece: pieceId,
-      x: pos.x,
-      y: pos.y
-    });
-    this.session.level.gadgets.push(entry);
-    this._markChanged();
-    return entry;
-  }
-
-  ensureDefaultEntrancesExits(options = {}) {
-    if (!this.session?.level) return false;
-    const entranceId = Number.isFinite(options.entranceId)
-      ? options.entranceId
-      : this.assets?.entranceId;
-    const exitId = Number.isFinite(options.exitId)
-      ? options.exitId
-      : this.assets?.exitId;
-    const viewRect = options.viewRect || null;
-    const headerWidth = coerceEntryNumber(this.session.level.getHeader?.('WIDTH'), 0);
-    const headerHeight = coerceEntryNumber(this.session.level.getHeader?.('HEIGHT'), 0);
-    const levelWidth = Number.isFinite(headerWidth) && headerWidth > 0 ? headerWidth : 0;
-    const levelHeight = Number.isFinite(headerHeight) && headerHeight > 0 ? headerHeight : 0;
-    const hasEntrance = Number.isFinite(entranceId) && this._hasGadgetId(entranceId);
-    const hasExit = Number.isFinite(exitId) && this._hasGadgetId(exitId);
-    if (hasEntrance && hasExit) return false;
-
-    const clamp = (value, min, max) => Math.min(Math.max(value, min), max);
-    const baseX = viewRect ? viewRect.x : 0;
-    const baseY = viewRect ? viewRect.y : 0;
-    const viewW = viewRect ? viewRect.w : Math.min(levelWidth, 320);
-    const viewH = viewRect ? viewRect.h : Math.min(levelHeight, 160);
-    const targetY = clamp(baseY + viewH - 32, 0, Math.max(0, levelHeight - 1));
-
-    if (!hasEntrance && Number.isFinite(entranceId)) {
-      const meta = this._getGadgetMeta(entranceId);
-      const offset = Math.max(8, Math.floor((meta?.width || 16) / 2));
-      const x = clamp(baseX + offset, 0, Math.max(0, levelWidth - 1));
-      this._placeGadgetAt(x, targetY, entranceId);
-    }
-    if (!hasExit && Number.isFinite(exitId)) {
-      const meta = this._getGadgetMeta(exitId);
-      const offset = Math.max(8, Math.floor((meta?.width || 16) / 2));
-      const x = clamp(baseX + viewW - offset, 0, Math.max(0, levelWidth - 1));
-      this._placeGadgetAt(x, targetY, exitId);
-    }
-
-    this._commitHistory('Defaults');
-    this._requestPreview('Defaults');
-    return true;
-  }
-
-  _placeSteelAt(x, y, width, height) {
-    if (!this.session?.level) return null;
-    if (!Array.isArray(this.session.level.steel)) {
-      this.session.level.steel = [];
-    }
-    const entry = createSteelEntry({ x, y, width, height });
-    this.session.level.steel.push(entry);
-    this._markChanged();
-    return entry;
-  }
-
-  _beginSteelDraft(x, y) {
-    const size = Number.isFinite(this.gridSize) && this.gridSize > 0 ? this.gridSize : 1;
-    const entry = this._placeSteelAt(x, y, size, size);
-    if (!entry) return;
-    const list = this.session.level.steel;
-    const index = list.length - 1;
-    this._setSelection([{ type: 'steel', index }]);
-    this._steelDraft = { index, startX: x, startY: y };
-    this._requestPreview('Steel');
-  }
-
-  _updateSteelDraft(x, y) {
-    if (!this._steelDraft || !this.session?.level) return;
-    const list = this.session.level.steel;
-    const entry = Array.isArray(list) ? list[this._steelDraft.index] : null;
-    if (!entry) return;
-    const bounds = normalizeBounds(this._steelDraft.startX, this._steelDraft.startY, x, y);
-    setEntryProp(entry, 'X', bounds.x, { removeIfEmpty: false });
-    setEntryProp(entry, 'Y', bounds.y, { removeIfEmpty: false });
-    setEntryProp(entry, 'WIDTH', clampSize(bounds.width), { removeIfEmpty: false });
-    setEntryProp(entry, 'HEIGHT', clampSize(bounds.height), { removeIfEmpty: false });
-    this._markChanged();
-    this._callbacks.onSelectionChange?.(this.getSelectedEntries());
-    this._requestPreview('Steel');
-  }
-
-  _eraseAt(x, y) {
-    if (!this.session?.level) return;
-    const level = this.session.level;
-    const terrainHit = findEntryAt(level.terrains, this.assets?.terrainById, x, y);
-    if (terrainHit) {
-      removeEntryAt(level, 'terrain', terrainHit.index);
-      this._markChanged();
-    }
-    if (this.eraseGadgets) {
-      const gadgetHit = findEntryAt(level.gadgets, this.assets?.gadgetById, x, y);
-      if (gadgetHit) {
-        removeEntryAt(level, 'gadget', gadgetHit.index);
-        this._markChanged();
-      }
-    }
-  }
-
-  _getBrushStep() {
-    if (this.snapEnabled && Number.isFinite(this.gridSize) && this.gridSize > 0) {
-      return this.gridSize;
-    }
-    return 1;
-  }
-
-  _brushLine(start, end) {
-    if (!start || !end) return;
-    const step = Math.max(1, this._getBrushStep());
-    const dx = end.x - start.x;
-    const dy = end.y - start.y;
-    const distance = Math.hypot(dx, dy);
-    const segments = Math.max(1, Math.floor(distance / step));
-    for (let i = 0; i <= segments; i++) {
-      const t = i / segments;
-      const px = Math.round(start.x + dx * t);
-      const py = Math.round(start.y + dy * t);
-      this._brushAt(px, py);
-    }
-  }
-
-  _eraseLine(start, end) {
-    if (!start || !end) return;
-    const step = Math.max(1, this._getBrushStep());
-    const dx = end.x - start.x;
-    const dy = end.y - start.y;
-    const distance = Math.hypot(dx, dy);
-    const segments = Math.max(1, Math.floor(distance / step));
-    for (let i = 0; i <= segments; i++) {
-      const t = i / segments;
-      const px = Math.round(start.x + dx * t);
-      const py = Math.round(start.y + dy * t);
-      this._eraseAt(px, py);
-    }
-  }
-
-  _brushAt(x, y) {
-    const size = Math.max(1, this.brushSize);
-    const key = `${x},${y},${size}`;
-    if (this._stampSet.has(key)) return;
-    this._stampSet.add(key);
-    const half = Math.floor(size / 2);
-    const step = this._getBrushStep();
-    for (let by = -half; by <= half; by++) {
-      for (let bx = -half; bx <= half; bx++) {
-        const px = x + bx * step;
-        const py = y + by * step;
-        this._placeTerrainAt(px, py);
-      }
-    }
-  }
-
-  handlePointerDown(pos, button = 0, options = {}) {
-    if (!this.session?.level) return;
-    const { x, y } = this._snap(pos.x, pos.y);
-    const shiftKey = options.shiftKey === true;
-    const altKey = options.altKey === true;
-    this._pointerDown = button === 0;
-    this._pointerButton = button;
-    if (button === 2) {
-      this.clearSelection();
-      this._clearMarquee();
-      return;
-    }
-
-    this._beginStroke();
-
-    switch (this.tool) {
-    case EditorTools.SELECT: {
-      const resizeHandle = !shiftKey ? this._getResizeHandleAt(x, y) : null;
-      if (resizeHandle) {
-        const selected = this.getSelectedEntry();
-        const bounds = this.getSelectionBounds();
-        if (selected && bounds) {
-          this._resize = {
-            handle: resizeHandle,
-            type: selected.type,
-            index: selected.index,
-            bounds
-          };
-          return;
-        }
-      }
-      const hit = this._findSelectionAt(x, y);
-      if (!hit) {
-        if (!shiftKey) this.clearSelection();
-        this._beginMarquee(x, y, shiftKey);
-        return;
-      }
-      if (shiftKey) {
-        this._selectHit(hit, { toggle: true });
-        return;
-      }
-      if (!this._isSelected(hit.type, hit.index)) {
-        this._selectHit(hit);
-      }
-      if (altKey) {
-        this._cloneSelection(this.getSelectedEntries(), 0, 0);
-      }
-      const selectedEntries = this.getSelectedEntries();
-      this._drag = {
-        entries: selectedEntries.map(entry => ({
-          type: entry.type,
-          index: entry.index,
-          offsetX: x - (entry.entry?.props?.X || 0),
-          offsetY: y - (entry.entry?.props?.Y || 0)
-        })),
-        label: altKey ? 'Duplicate' : 'Move'
-      };
-      break;
-    }
-    case EditorTools.TERRAIN:
-      this._placeTerrainAt(x, y);
-      this._commitHistory('Terrain');
-      this._requestPreview('Terrain');
-      break;
-    case EditorTools.GADGET:
-      this._placeGadgetAt(x, y, this.selectedGadgetId);
-      this._commitHistory('Gadget');
-      this._requestPreview('Gadget');
-      break;
-    case EditorTools.TRIGGER:
-      this._placeGadgetAt(x, y, this.selectedTriggerId ?? this.selectedGadgetId);
-      this._commitHistory('Trigger');
-      this._requestPreview('Trigger');
-      break;
-    case EditorTools.ENTRANCE: {
-      const entranceId = this.assets?.entranceId ?? 1;
-      this._trimGadgetsById(entranceId, MAX_ENTRANCES - 1);
-      this._placeGadgetAt(x, y, entranceId);
-      this._commitHistory('Entrance');
-      this._requestPreview('Entrance');
-      break;
-    }
-    case EditorTools.EXIT: {
-      const exitId = this.assets?.exitId ?? this.selectedGadgetId;
-      if (Number.isFinite(exitId)) {
-        this._trimGadgetsById(exitId, MAX_EXITS - 1);
-      }
-      this._placeGadgetAt(x, y, exitId);
-      this._commitHistory('Exit');
-      this._requestPreview('Exit');
-      break;
-    }
-    case EditorTools.STEEL:
-      this._beginSteelDraft(x, y);
-      break;
-    case EditorTools.BRUSH:
-      this._brushAt(x, y);
-      this._lastBrushPos = { x, y };
-      this._requestPreview('Brush');
-      break;
-    case EditorTools.ERASER:
-      this._eraseAt(x, y);
-      this._lastBrushPos = { x, y };
-      this._requestPreview('Erase');
-      break;
-    default:
-      break;
-    }
-  }
-
-  handlePointerMove(pos, options = {}) {
-    if (!this.session?.level) return;
-    const { x, y } = this._snap(pos.x, pos.y);
-    const isDown = typeof options.isDown === 'boolean'
-      ? options.isDown
-      : this._pointerDown;
-
-    if (this._steelDraft && this.tool === EditorTools.STEEL) {
-      this._updateSteelDraft(x, y);
-      return;
-    }
-
-    if (this._resize && this.tool === EditorTools.SELECT) {
-      const selected = this.getSelectedEntry();
-      if (!selected) return;
-      const bounds = this._resize.bounds;
-      let left = bounds.x;
-      let right = bounds.x + bounds.width;
-      let top = bounds.y;
-      let bottom = bounds.y + bounds.height;
-      const snapCoord = (value) => (
-        this.snapEnabled ? snapValue(value, this.gridSize) : Math.round(value)
-      );
-      const handle = this._resize.handle;
-      if (handle.includes('w')) left = snapCoord(x);
-      if (handle.includes('e')) right = snapCoord(x);
-      if (handle.includes('n')) top = snapCoord(y);
-      if (handle.includes('s')) bottom = snapCoord(y);
-      if (right <= left) {
-        if (handle.includes('w')) left = right - 1;
-        else right = left + 1;
-      }
-      if (bottom <= top) {
-        if (handle.includes('n')) top = bottom - 1;
-        else bottom = top + 1;
-      }
-      const width = clampSize(right - left);
-      const height = clampSize(bottom - top);
-      const entry = selected.entry;
-      setEntryProp(entry, 'X', left, { removeIfEmpty: false });
-      setEntryProp(entry, 'Y', top, { removeIfEmpty: false });
-      setEntryProp(entry, 'WIDTH', width, { removeIfEmpty: false });
-      setEntryProp(entry, 'HEIGHT', height, { removeIfEmpty: false });
-      this._markChanged();
-      this._callbacks.onSelectionChange?.(this.getSelectedEntries());
-      this._requestPreview('Resize');
-      return;
-    }
-
-    if (this._drag && this.tool === EditorTools.SELECT) {
-      for (const dragEntry of this._drag.entries || []) {
-        const list = this._getListForType(dragEntry.type);
-        const entry = list?.[dragEntry.index];
-        if (entry) {
-          entry.props.X = x - dragEntry.offsetX;
-          entry.props.Y = y - dragEntry.offsetY;
-          this._markChanged();
-        }
-      }
-      if (this._drag.entries?.length) {
-        this._callbacks.onSelectionChange?.(this.getSelectedEntries());
-        this._requestPreview('Move');
-      }
-      return;
-    }
-
-    if (isDown && this._marquee && this.tool === EditorTools.SELECT) {
-      this._updateMarquee(x, y);
-      return;
-    }
-
-    if (isDown && this.tool === EditorTools.BRUSH) {
-      if (this._lastBrushPos) {
-        this._brushLine(this._lastBrushPos, { x, y });
-      } else {
-        this._brushAt(x, y);
-      }
-      this._lastBrushPos = { x, y };
-      this._requestPreview('Brush');
-    }
-
-    if (isDown && this.tool === EditorTools.ERASER) {
-      if (this._lastBrushPos) {
-        this._eraseLine(this._lastBrushPos, { x, y });
-      } else {
-        this._eraseAt(x, y);
-      }
-      this._lastBrushPos = { x, y };
-      this._requestPreview('Erase');
-    }
-  }
-
-  handlePointerUp() {
-    this._pointerDown = false;
-    this._pointerButton = 0;
-    if (!this.session?.level) return;
-    this._lastBrushPos = null;
-    if (this._steelDraft) {
-      this._steelDraft = null;
-      if (this._strokeChanged) {
-        this._commitHistory('Steel');
-      }
-      this._strokeChanged = false;
-      return;
-    }
-    if (this._resize) {
-      this._resize = null;
-      if (this._strokeChanged) {
-        this._commitHistory('Resize');
-      }
-      this._strokeChanged = false;
-      return;
-    }
-    if (this._drag) {
-      const label = this._drag.label || 'Move';
-      this._drag = null;
-      if (this._strokeChanged) {
-        this._commitHistory(label);
-      }
-      this._strokeChanged = false;
-      return;
-    }
-    if (this._marquee) {
-      this._applyMarqueeSelection();
-      this._clearMarquee();
-      return;
-    }
-
-    if (this.tool === EditorTools.BRUSH && this._strokeChanged) {
-      this._commitHistory('Brush');
-    }
-    if (this.tool === EditorTools.ERASER && this._strokeChanged) {
-      this._commitHistory('Erase');
-    }
-    this._strokeChanged = false;
-  }
-}
-
-export { EditorController };
-
-const __test__ = {
-  cloneEntry,
-  normalizeBounds,
-  boundsIntersect
-};
-
-export { __test__ };
+export { EditorController } from './editor-controller/EditorControllerCore.js';
+export {
+  __test__
+} from './editor-controller/EditorControllerShared.js';
diff --git a/js/editor/EditorHistory.js b/js/editor/EditorHistory.js
index 15380492..c65045ce 100644
--- a/js/editor/EditorHistory.js
+++ b/js/editor/EditorHistory.js
@@ -5,15 +5,27 @@ import { EditorLevel } from './EditorLevel.js';
 class EditorHistory {
   constructor(options = {}) {
     this.maxEntries = Number.isFinite(options.maxEntries) ? options.maxEntries : 100;
+    this.maxBytes = Number.isFinite(options.maxBytes) && options.maxBytes > 0
+      ? Math.floor(options.maxBytes)
+      : Infinity;
+    this.coalesceWindowMs = Number.isFinite(options.coalesceWindowMs) && options.coalesceWindowMs > 0
+      ? Math.floor(options.coalesceWindowMs)
+      : 0;
     this.parser = options.parser || new NxlvParser();
     this.writer = options.writer || new NxlvWriter();
     this._entries = [];
     this._cursor = -1;
+    this._totalBytes = 0;
+    this._transactionDepth = 0;
+    this._transactionPending = null;
   }
 
   clear() {
     this._entries = [];
     this._cursor = -1;
+    this._totalBytes = 0;
+    this._transactionDepth = 0;
+    this._transactionPending = null;
   }
 
   get entries() {
@@ -24,6 +36,21 @@ class EditorHistory {
     return this._cursor;
   }
 
+  getStats() {
+    const pendingText = this._transactionPending?.changed
+      ? this._transactionPending.text
+      : null;
+    return {
+      entries: this._entries.length,
+      cursor: this._cursor,
+      bytes: this._totalBytes,
+      maxEntries: this.maxEntries,
+      maxBytes: this.maxBytes,
+      transactionDepth: this._transactionDepth,
+      pendingBytes: typeof pendingText === 'string' ? this._estimateBytes(pendingText) : 0
+    };
+  }
+
   canUndo() {
     return this._cursor > 0;
   }
@@ -36,24 +63,139 @@ class EditorHistory {
     return this.writer.write(level || new EditorLevel());
   }
 
-  pushSnapshot(level, label = '') {
-    const text = this._serialize(level);
+  _estimateBytes(text) {
+    return typeof text === 'string' ? text.length * 2 : 0;
+  }
+
+  _removeEntries(start, deleteCount) {
+    if (deleteCount <= 0) return [];
+    const removed = this._entries.splice(start, deleteCount);
+    for (const entry of removed) {
+      this._totalBytes -= entry?.bytes || 0;
+    }
+    this._totalBytes = Math.max(0, this._totalBytes);
+    return removed;
+  }
+
+  _truncateRedoEntries() {
+    if (this._cursor >= this._entries.length - 1) return;
+    this._removeEntries(this._cursor + 1, this._entries.length - this._cursor - 1);
+  }
+
+  _trimToLimits() {
+    while (
+      this._entries.length > 1
+      && (
+        this._entries.length > this.maxEntries
+        || this._totalBytes > this.maxBytes
+      )
+    ) {
+      this._removeEntries(0, 1);
+      this._cursor -= 1;
+    }
+    if (this._entries.length === 0) {
+      this._cursor = -1;
+    } else {
+      this._cursor = Math.min(Math.max(this._cursor, 0), this._entries.length - 1);
+    }
+  }
+
+  _canCoalesce(label, time) {
+    if (!this.coalesceWindowMs || this._cursor < 0) return false;
+    const prev = this._entries[this._cursor];
+    if (!prev || prev.label !== label) return false;
+    return Math.abs(time - prev.time) <= this.coalesceWindowMs;
+  }
+
+  _pushSerialized(text, label = '', time = Date.now()) {
     const prev = this._entries[this._cursor]?.text;
     if (prev === text) return false;
-    if (this._cursor < this._entries.length - 1) {
-      this._entries = this._entries.slice(0, this._cursor + 1);
-    }
-    this._entries.push({ text, label, time: Date.now() });
-    if (this._entries.length > this.maxEntries) {
-      const overflow = this._entries.length - this.maxEntries;
-      this._entries.splice(0, overflow);
-      this._cursor = this._entries.length - 1;
+    this._truncateRedoEntries();
+    const bytes = this._estimateBytes(text);
+    if (this._canCoalesce(label, time)) {
+      const entry = this._entries[this._cursor];
+      this._totalBytes += bytes - (entry.bytes || 0);
+      entry.text = text;
+      entry.label = label;
+      entry.time = time;
+      entry.bytes = bytes;
     } else {
+      this._entries.push({ text, label, time, bytes });
+      this._totalBytes += bytes;
       this._cursor = this._entries.length - 1;
     }
+    this._trimToLimits();
     return true;
   }
 
+  beginTransaction(label = 'Batch') {
+    this._transactionDepth += 1;
+    if (this._transactionDepth === 1) {
+      this._transactionPending = {
+        text: null,
+        label: label || 'Batch',
+        time: Date.now(),
+        changed: false
+      };
+    } else if (label) {
+      this._transactionPending.label = label;
+    }
+  }
+
+  endTransaction(label = '') {
+    if (this._transactionDepth <= 0) return false;
+    if (label && this._transactionPending) {
+      this._transactionPending.label = label;
+    }
+    this._transactionDepth -= 1;
+    if (this._transactionDepth > 0) return false;
+    const pending = this._transactionPending;
+    this._transactionPending = null;
+    if (!pending?.changed || typeof pending.text !== 'string') return false;
+    return this._pushSerialized(
+      pending.text,
+      pending.label || label || 'Batch',
+      pending.time
+    );
+  }
+
+  cancelTransaction() {
+    if (this._transactionDepth <= 0 && !this._transactionPending) return false;
+    this._transactionDepth = 0;
+    this._transactionPending = null;
+    return true;
+  }
+
+  /**
+   * Queue snapshots as a single undo unit until `endTransaction` is called.
+   * Nested transactions are supported and only commit at the outer boundary.
+   */
+  pushSnapshot(level, label = '') {
+    const text = this._serialize(level);
+    if (this._transactionDepth > 0) {
+      if (!this._transactionPending) {
+        this._transactionPending = {
+          text: null,
+          label: label || 'Batch',
+          time: Date.now(),
+          changed: false
+        };
+      }
+      const baseText = this._transactionPending.changed
+        ? this._transactionPending.text
+        : this._entries[this._cursor]?.text;
+      if (baseText === text) return false;
+      this._transactionPending.text = text;
+      this._transactionPending.time = Date.now();
+      this._transactionPending.changed = true;
+      if (label) {
+        this._transactionPending.label = label;
+      }
+      return true;
+    }
+    return this._pushSerialized(text, label, Date.now());
+  }
+
   _applySnapshot(index) {
     if (index < 0 || index >= this._entries.length) return null;
     this._cursor = index;
diff --git a/js/editor/EditorLevelLoader.js b/js/editor/EditorLevelLoader.js
index 202d7348..7ed1afa3 100644
--- a/js/editor/EditorLevelLoader.js
+++ b/js/editor/EditorLevelLoader.js
@@ -6,7 +6,15 @@ import { GroundRenderer } from '../render/GroundRenderer.js';
 import { SolidLayer } from '../render/SolidLayer.js';
 import { DrawProperties } from '../render/DrawProperties.js';
 import { SkillTypes } from '../game/SkillTypes.js';
-import { DEFAULT_LEVEL_WIDTH, DEFAULT_LEVEL_HEIGHT } from '../level/ClassicLevelConstants.js';
+import {
+  DEFAULT_LEVEL_WIDTH,
+  DEFAULT_LEVEL_HEIGHT,
+  LEVEL_OBJECT_COUNT,
+  LEVEL_TERRAIN_COUNT,
+  LEVEL_STEEL_COUNT,
+  LEVEL_NAME_LENGTH
+} from '../level/ClassicLevelConstants.js';
+import { MIDI_FLAG_TRIGGER_MAX, clampMidiFlagId, toMidiFlagTriggerType } from '../midi/MidiFlagTriggers.js';
 import {
   getDefaultStyle,
   getStyle,
@@ -16,6 +24,7 @@ import {
 
 const DEFAULT_RELEASE_RATE = 50;
 const MAX_TIME_LIMIT_SECONDS = 99 * 60 + 99;
+const DEFAULT_MIDI_FLAG_COOLDOWN = 8;
 
 const coerceNumber = (value, fallback) => {
   return Number.isFinite(value) ? value : fallback;
@@ -23,7 +32,7 @@ const coerceNumber = (value, fallback) => {
 
 const normalizeBoolean = (value) => {
   if (value === true || value === 1) return true;
-  if (value === false || value === 0 || value == null) return false;
+  if (value === false || value === 0 || value === null || value === undefined) return false;
   if (typeof value === 'string') {
     const normalized = value.trim().toLowerCase();
     if (normalized === 'true' || normalized === '1') return true;
@@ -93,6 +102,166 @@ const createSteelRanges = (entries) => {
     .filter(Boolean);
 };
 
+const createExportWarning = (code, message, details = {}) => {
+  return {
+    severity: 'warning',
+    code,
+    exportFormat: 'classicLvl',
+    destructive: true,
+    message,
+    ...details
+  };
+};
+
+const capClassicList = (entries, max, codeTarget, label, warnings) => {
+  const list = Array.isArray(entries) ? entries : [];
+  if (list.length <= max) return list;
+  warnings.push(createExportWarning(
+    `classic_${codeTarget}_count`,
+    `Classic .lvl export stores ${max} ${label}; ${list.length - max} will be omitted.`,
+    {
+      target: codeTarget,
+      count: list.length,
+      max
+    }
+  ));
+  return list.slice(0, max);
+};
+
+const collectUnsupportedClassicProps = (entries, allowedProps) => {
+  const keys = new Set();
+  if (!Array.isArray(entries)) return [];
+  for (const entry of entries) {
+    const props = entry?.props;
+    if (!props) continue;
+    for (const key of Object.keys(props)) {
+      if (!allowedProps.has(key)) keys.add(key);
+    }
+  }
+  return Array.from(keys).sort();
+};
+
+const countPreservedNxlvMetadata = (editorLevel) => {
+  if (!editorLevel) return 0;
+  let count = 0;
+  if (Array.isArray(editorLevel.unknownLines)) count += editorLevel.unknownLines.length;
+  if (Array.isArray(editorLevel.unknownSections)) count += editorLevel.unknownSections.length;
+  if (Array.isArray(editorLevel.skillsetUnknownLines)) count += editorLevel.skillsetUnknownLines.length;
+  const addEntryUnknownLines = (entries) => {
+    if (!Array.isArray(entries)) return;
+    for (const entry of entries) {
+      if (Array.isArray(entry?.unknownLines)) count += entry.unknownLines.length;
+    }
+  };
+  addEntryUnknownLines(editorLevel.terrains);
+  addEntryUnknownLines(editorLevel.gadgets);
+  addEntryUnknownLines(editorLevel.steel);
+  if (Array.isArray(editorLevel.terrainGroups)) {
+    for (const group of editorLevel.terrainGroups) {
+      if (Array.isArray(group?.unknownLines)) count += group.unknownLines.length;
+      addEntryUnknownLines(group?.terrains);
+    }
+  }
+  return count;
+};
+
+const TERRAIN_CLASSIC_PROPS = new Set([
+  'STYLE',
+  'PIECE',
+  'X',
+  'Y',
+  'FLIP_VERTICAL',
+  'NO_OVERWRITE',
+  'ERASE'
+]);
+
+const GADGET_CLASSIC_PROPS = new Set([
+  'STYLE',
+  'PIECE',
+  'X',
+  'Y',
+  'FLIP_VERTICAL',
+  'NO_OVERWRITE'
+]);
+
+const STEEL_CLASSIC_PROPS = new Set([
+  'X',
+  'Y',
+  'WIDTH',
+  'HEIGHT'
+]);
+
+/**
+ * Convert editor gadget props tagged with MIDI flag metadata into runtime
+ * trigger descriptors consumed by GameView.
+ */
+const extractMidiFlags = (entries, styleName, objectImages) => {
+  if (!Array.isArray(entries) || !Array.isArray(objectImages)) return [];
+  const flags = [];
+  const usedIds = new Set();
+  for (const entry of entries) {
+    const props = entry?.props || {};
+    if (!normalizeBoolean(props.MIDI_FLAG)) continue;
+    const explicitId = clampMidiFlagId(Number(props.MIDI_FLAG_ID));
+    if (explicitId) usedIds.add(explicitId);
+  }
+  let autoId = 1;
+  const nextAutoId = () => {
+    while (autoId <= MIDI_FLAG_TRIGGER_MAX && usedIds.has(autoId)) {
+      autoId += 1;
+    }
+    if (autoId > MIDI_FLAG_TRIGGER_MAX) return null;
+    const id = autoId;
+    usedIds.add(id);
+    autoId += 1;
+    return id;
+  };
+
+  for (const entry of entries) {
+    const props = entry?.props || {};
+    const enabled = normalizeBoolean(props.MIDI_FLAG);
+    if (!enabled) continue;
+    const explicitId = clampMidiFlagId(Number(props.MIDI_FLAG_ID));
+    const flagId = explicitId || nextAutoId();
+    if (!flagId) continue;
+    usedIds.add(flagId);
+    const triggerType = toMidiFlagTriggerType(flagId);
+    if (!triggerType) continue;
+    const pieceId = resolvePieceId(resolveGadgetId, styleName, props.PIECE);
+    const objectInfo = objectImages[pieceId] || null;
+    const hasTriggerArea = objectInfo &&
+      Number.isFinite(objectInfo.trigger_width) &&
+      Number.isFinite(objectInfo.trigger_height) &&
+      objectInfo.trigger_width > 0 &&
+      objectInfo.trigger_height > 0;
+    const x = coerceNumber(props.X, 0);
+    const y = coerceNumber(props.Y, 0);
+    const x1 = x + (hasTriggerArea ? coerceNumber(objectInfo.trigger_left, 0) : 0);
+    const y1 = y + (hasTriggerArea ? coerceNumber(objectInfo.trigger_top, 0) : 0);
+    const width = hasTriggerArea
+      ? objectInfo.trigger_width
+      : Math.max(1, objectInfo?.width || 8);
+    const height = hasTriggerArea
+      ? objectInfo.trigger_height
+      : Math.max(1, objectInfo?.height || 8);
+    const cooldownRaw = Number(props.MIDI_FLAG_COOLDOWN);
+    const cooldownTicks = Number.isFinite(cooldownRaw)
+      ? Math.max(0, Math.trunc(cooldownRaw))
+      : DEFAULT_MIDI_FLAG_COOLDOWN;
+    flags.push({
+      id: flagId,
+      triggerType,
+      pieceId,
+      x1,
+      y1,
+      x2: x1 + Math.max(1, width),
+      y2: y1 + Math.max(1, height),
+      cooldownTicks
+    });
+  }
+  return flags;
+};
+
 const buildSkills = (skillset) => {
   const skills = new Array(Object.keys(SkillTypes).length).fill(0);
   if (!skillset) return skills;
@@ -106,19 +275,96 @@ const buildSkills = (skillset) => {
 
 const createClassicLevelData = (editorLevel, options = {}) => {
   if (!editorLevel) return null;
+  const warnings = [];
   const styleName = resolveStyleName(editorLevel, options);
   const groundSet = resolveGroundSet(styleName);
   const width = coerceNumber(editorLevel.getHeader('WIDTH'), DEFAULT_LEVEL_WIDTH);
   const height = coerceNumber(editorLevel.getHeader('HEIGHT'), DEFAULT_LEVEL_HEIGHT);
-  const title = editorLevel.getHeader('TITLE') || 'Untitled';
+  const rawTitle = String(editorLevel.getHeader('TITLE') || 'Untitled');
+  const title = rawTitle.length > LEVEL_NAME_LENGTH
+    ? rawTitle.slice(0, LEVEL_NAME_LENGTH)
+    : rawTitle;
   const releaseCount = coerceNumber(editorLevel.getHeader('LEMMINGS'), 0);
   const needCount = coerceNumber(editorLevel.getHeader('SAVE_REQUIREMENT'), 0);
   const releaseRate = coerceNumber(editorLevel.getHeader('MAX_SPAWN_INTERVAL'), DEFAULT_RELEASE_RATE);
   const timeLimit = resolveTimeLimit(editorLevel.getHeader('TIME_LIMIT'));
   const startX = coerceNumber(editorLevel.getHeader('START_X'), 0);
+  const terrainUnsupported = collectUnsupportedClassicProps(editorLevel.terrains, TERRAIN_CLASSIC_PROPS);
+  const gadgetUnsupported = collectUnsupportedClassicProps(editorLevel.gadgets, GADGET_CLASSIC_PROPS);
+  const steelUnsupported = collectUnsupportedClassicProps(editorLevel.steel, STEEL_CLASSIC_PROPS);
+  const preservedMetadataCount = countPreservedNxlvMetadata(editorLevel);
+
+  if (rawTitle.length > LEVEL_NAME_LENGTH) {
+    warnings.push(createExportWarning(
+      'classic_title_length',
+      `Classic .lvl export stores ${LEVEL_NAME_LENGTH} title characters; ${rawTitle.length - LEVEL_NAME_LENGTH} will be omitted.`,
+      {
+        target: 'header.TITLE',
+        count: rawTitle.length,
+        max: LEVEL_NAME_LENGTH
+      }
+    ));
+  }
+
+  if (Array.isArray(editorLevel.terrainGroups) && editorLevel.terrainGroups.length) {
+    warnings.push(createExportWarning(
+      'classic_terrain_groups',
+      'Terrain groups are not exported to classic .lvl.',
+      {
+        target: 'terrainGroups',
+        count: editorLevel.terrainGroups.length,
+        max: 0
+      }
+    ));
+  }
+
+  if (preservedMetadataCount) {
+    warnings.push(createExportWarning(
+      'classic_preserved_nxlv_metadata',
+      'Comments and unknown NXLV sections are preserved for NXLV but are not exported to classic .lvl.',
+      {
+        target: 'nxlvMetadata',
+        count: preservedMetadataCount,
+        max: 0
+      }
+    ));
+  }
+
+  if (terrainUnsupported.length) {
+    warnings.push(createExportWarning(
+      'classic_unsupported_terrain_props',
+      `Terrain entries include properties classic .lvl cannot export (${terrainUnsupported.join(', ')}).`,
+      {
+        target: 'terrains',
+        props: terrainUnsupported
+      }
+    ));
+  }
+
+  if (gadgetUnsupported.length) {
+    warnings.push(createExportWarning(
+      'classic_unsupported_gadget_props',
+      `Gadget entries include properties classic .lvl cannot export (${gadgetUnsupported.join(', ')}).`,
+      {
+        target: 'gadgets',
+        props: gadgetUnsupported
+      }
+    ));
+  }
+
+  if (steelUnsupported.length) {
+    warnings.push(createExportWarning(
+      'classic_unsupported_steel_props',
+      `Steel entries include properties classic .lvl cannot export (${steelUnsupported.join(', ')}).`,
+      {
+        target: 'steel',
+        props: steelUnsupported
+      }
+    ));
+  }
 
   const levelProperties = {
-    levelName: String(title),
+    levelName: title,
     releaseRate,
     releaseCount,
     needCount,
@@ -126,11 +372,30 @@ const createClassicLevelData = (editorLevel, options = {}) => {
     skills: buildSkills(editorLevel.skillset)
   };
 
-  const terrains = createLevelElements(editorLevel.terrains, styleName, resolveTerrainId);
-  const objects = createLevelElements(editorLevel.gadgets, styleName, resolveGadgetId);
-  const steelRanges = Array.isArray(options.steelRanges)
+  const terrains = capClassicList(
+    createLevelElements(editorLevel.terrains, styleName, resolveTerrainId),
+    LEVEL_TERRAIN_COUNT,
+    'terrains',
+    'terrain pieces',
+    warnings
+  );
+  const objects = capClassicList(
+    createLevelElements(editorLevel.gadgets, styleName, resolveGadgetId),
+    LEVEL_OBJECT_COUNT,
+    'gadgets',
+    'gadgets',
+    warnings
+  );
+  const rawSteelRanges = Array.isArray(options.steelRanges)
     ? options.steelRanges
     : createSteelRanges(editorLevel.steel);
+  const steelRanges = capClassicList(
+    rawSteelRanges,
+    LEVEL_STEEL_COUNT,
+    'steel',
+    'steel rectangles',
+    warnings
+  );
 
   return {
     levelReader: {
@@ -146,13 +411,18 @@ const createClassicLevelData = (editorLevel, options = {}) => {
       steel: steelRanges
     },
     styleName,
-    groundSet
+    groundSet,
+    warnings,
+    metadata: {
+      format: 'classicLvl',
+      lossy: warnings.length > 0
+    }
   };
 };
 
 const loadEditorLevel = async (editorLevel, config, fileProvider, options = {}) => {
   if (!editorLevel || !config || !fileProvider) return null;
-  const { levelReader, groundSet } = createClassicLevelData(editorLevel, {
+  const { levelReader, groundSet, styleName } = createClassicLevelData(editorLevel, {
     styleName: options.styleName,
     steelRanges: options.steelRanges
   });
@@ -201,8 +471,10 @@ const loadEditorLevel = async (editorLevel, config, fileProvider, options = {})
 
   level.setGroundImage(renderer.img.getData());
   level.setGroundMaskLayer(new SolidLayerCtor(level.width, level.height, renderer.img.mask));
-  level.setMapObjects(levelReader.objects, groundReader.getObjectImages());
+  const objectImages = groundReader.getObjectImages();
+  level.setMapObjects(levelReader.objects, objectImages);
   level.setPalettes(groundReader.colorPalette, groundReader.groundPalette);
+  level.midiFlags = extractMidiFlags(editorLevel.gadgets, styleName, objectImages);
 
   if (Array.isArray(levelReader.steel) && levelReader.steel.length) {
     level.setSteelAreas(levelReader.steel);
diff --git a/js/editor/EditorStorage.js b/js/editor/EditorStorage.js
index 762691b8..31d5bd28 100644
--- a/js/editor/EditorStorage.js
+++ b/js/editor/EditorStorage.js
@@ -1,11 +1,14 @@
+import { getRuntimeDependency } from '../core/dependencies.js';
+
 const STORAGE_KEYS = Object.freeze({
   index: 'lemmings.editor.levels',
   levelPrefix: 'lemmings.editor.level.'
 });
+const EDITOR_STORAGE_VERSION = 2;
 
 let idCounter = 0;
 
-const getDefaultStorage = () => globalThis.localStorage || null;
+const getDefaultStorage = () => getRuntimeDependency('localStorage', null);
 
 const safeGetItem = (storage, key) => {
   try {
@@ -39,12 +42,20 @@ const normalizeName = (name) => {
 };
 
 const parseIndex = (raw) => {
-  if (!raw) return [];
+  if (!raw) return { entries: [], shouldMigrate: false };
   try {
     const parsed = JSON.parse(raw);
-    return Array.isArray(parsed) ? parsed : [];
+    if (Array.isArray(parsed)) {
+      return { entries: parsed, shouldMigrate: true };
+    }
+    if (parsed && typeof parsed === 'object' && Array.isArray(parsed.entries)) {
+      const parsedVersion = Number(parsed.version);
+      const shouldMigrate = !Number.isFinite(parsedVersion) || parsedVersion !== EDITOR_STORAGE_VERSION;
+      return { entries: parsed.entries, shouldMigrate };
+    }
+    return { entries: [], shouldMigrate: false };
   } catch (e) {
-    return [];
+    return { entries: [], shouldMigrate: false };
   }
 };
 
@@ -57,7 +68,10 @@ const sanitizeIndex = (entries) => entries
   }));
 
 const writeIndex = (storage, entries) => {
-  const payload = JSON.stringify(entries);
+  const payload = JSON.stringify({
+    version: EDITOR_STORAGE_VERSION,
+    entries
+  });
   safeSetItem(storage, STORAGE_KEYS.index, payload);
 };
 
@@ -76,7 +90,11 @@ const compareSavedLevels = (a, b) => {
 
 const listSavedLevels = (storage = getDefaultStorage()) => {
   const raw = safeGetItem(storage, STORAGE_KEYS.index);
-  const entries = sanitizeIndex(parseIndex(raw));
+  const parsed = parseIndex(raw);
+  const entries = sanitizeIndex(parsed.entries);
+  if (parsed.shouldMigrate && storage) {
+    writeIndex(storage, entries);
+  }
   entries.sort(compareSavedLevels);
   return entries;
 };
@@ -93,7 +111,8 @@ const saveLevel = (storage = getDefaultStorage(), payload = {}) => {
   const id = payload.id || createLevelId(payload.now || (() => now));
   const name = normalizeName(payload.name);
   const text = typeof payload.text === 'string' ? payload.text : '';
-  const index = sanitizeIndex(parseIndex(safeGetItem(storage, STORAGE_KEYS.index)));
+  const parsed = parseIndex(safeGetItem(storage, STORAGE_KEYS.index));
+  const index = sanitizeIndex(parsed.entries);
   const existing = index.find(entry => entry.id === id);
   if (existing) {
     existing.name = name;
@@ -109,7 +128,8 @@ const saveLevel = (storage = getDefaultStorage(), payload = {}) => {
 const deleteLevel = (storage = getDefaultStorage(), id) => {
   if (!storage || !id) return false;
   safeRemoveItem(storage, STORAGE_KEYS.levelPrefix + id);
-  const index = sanitizeIndex(parseIndex(safeGetItem(storage, STORAGE_KEYS.index)));
+  const parsed = parseIndex(safeGetItem(storage, STORAGE_KEYS.index));
+  const index = sanitizeIndex(parsed.entries);
   const next = index.filter(entry => entry.id !== id);
   writeIndex(storage, next);
   return true;
diff --git a/js/editor/EditorTools.js b/js/editor/EditorTools.js
index 1e06e0fc..a6a71948 100644
--- a/js/editor/EditorTools.js
+++ b/js/editor/EditorTools.js
@@ -3,6 +3,7 @@ const EditorTools = Object.freeze({
   TERRAIN: 'terrain',
   GADGET: 'gadget',
   TRIGGER: 'trigger',
+  MIDI_FLAG: 'midi-flag',
   ENTRANCE: 'entrance',
   EXIT: 'exit',
   STEEL: 'steel',
@@ -15,6 +16,7 @@ const EDITOR_TOOL_ORDER = Object.freeze([
   EditorTools.TERRAIN,
   EditorTools.GADGET,
   EditorTools.TRIGGER,
+  EditorTools.MIDI_FLAG,
   EditorTools.ENTRANCE,
   EditorTools.EXIT,
   EditorTools.STEEL,
diff --git a/js/editor/EditorValidator.js b/js/editor/EditorValidator.js
index ebc5925e..7f64c7f0 100644
--- a/js/editor/EditorValidator.js
+++ b/js/editor/EditorValidator.js
@@ -1,4 +1,15 @@
-import { DEFAULT_LEVEL_WIDTH, DEFAULT_LEVEL_HEIGHT } from '../level/ClassicLevelConstants.js';
+import {
+  DEFAULT_LEVEL_WIDTH,
+  DEFAULT_LEVEL_HEIGHT,
+  LEVEL_OBJECT_COUNT,
+  LEVEL_TERRAIN_COUNT,
+  LEVEL_STEEL_COUNT,
+  LEVEL_NAME_LENGTH
+} from '../level/ClassicLevelConstants.js';
+import {
+  EDITOR_ADVISORY_WARNING_CODES,
+  checkEditorSolvabilityAdvisory
+} from '../solver/EditorAdvisory.js';
 import { createGadgetEntry, removeEntryAt } from './EditorEntryFactory.js';
 
 const clamp = (value, min, max) => Math.min(Math.max(value, min), max);
@@ -9,6 +20,10 @@ const coerceNumber = (value, fallback = 0) => {
 
 const isFiniteNumber = (value) => Number.isFinite(value);
 const ROTATION_STEPS = new Set([0, 90, 180, 270]);
+const VALIDATOR_HANDLED_ADVISORY_CODES = new Set([
+  EDITOR_ADVISORY_WARNING_CODES.MISSING_ENTRANCE,
+  EDITOR_ADVISORY_WARNING_CODES.MISSING_EXIT
+]);
 const MAX_ENTRANCES = 4;
 const MAX_EXITS = 4;
 const MAX_LEVEL_WIDTH = DEFAULT_LEVEL_WIDTH;
@@ -33,8 +48,12 @@ const findPieceIndices = (entries, pieceId) => {
   return matches;
 };
 
-const createIssue = (severity, message, fixLabel = null, fix = null) => {
-  return { severity, message, fixLabel, fix };
+const createIssue = (severity, message, fixLabel = null, fix = null, details = null) => {
+  const issue = { severity, message, fixLabel, fix };
+  if (details && typeof details === 'object') {
+    Object.assign(issue, details);
+  }
+  return issue;
 };
 
 const normalizeRotation = (value) => {
@@ -44,6 +63,256 @@ const normalizeRotation = (value) => {
   return ((snapped % 360) + 360) % 360;
 };
 
+const createDestructiveIssue = (code, message, fixLabel = null, fix = null, details = {}) => {
+  return createIssue('warning', message, fixLabel, fix, {
+    code,
+    exportFormat: 'classicLvl',
+    destructive: true,
+    ...details
+  });
+};
+
+const normalizeSolverAdvisoryConfig = (options) => {
+  if (options?.solverAdvisory === false) return null;
+  return options?.solverAdvisory && typeof options.solverAdvisory === 'object'
+    ? options.solverAdvisory
+    : {};
+};
+
+const toSolverAdvisoryIssueCode = (code) => {
+  const normalized = String(code || 'unknown')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '');
+  return `solver_advisory_${normalized || 'unknown'}`;
+};
+
+const appendSolverAdvisoryIssues = (issues, level, assets, options) => {
+  const config = normalizeSolverAdvisoryConfig(options);
+  if (!config) return;
+  const { source = null, ...advisoryOptions } = config;
+  const advisorySource = source || options?.solverAdvisorySource || options?.runtimeLevel || level;
+  if (!advisorySource) return;
+  const advisory = checkEditorSolvabilityAdvisory(advisorySource, {
+    assets,
+    entranceId: assets?.entranceId,
+    exitId: assets?.exitId,
+    ...advisoryOptions
+  });
+  for (const warning of advisory.warnings || []) {
+    if (VALIDATOR_HANDLED_ADVISORY_CODES.has(warning.code)) continue;
+    issues.push(createIssue(
+      'warning',
+      `Solver advisory: ${warning.message}`,
+      null,
+      null,
+      {
+        code: toSolverAdvisoryIssueCode(warning.code),
+        source: 'solver-advisory',
+        solverAdvisory: true,
+        advisoryCode: warning.code,
+        target: warning.target ?? null,
+        blocking: false,
+        blocksEditing: advisory.blocksEditing === true,
+        blocksExport: advisory.blocksExport === true,
+        budgetUsage: advisory.budgetUsage || null
+      }
+    ));
+  }
+};
+
+const truncateEntries = (level, key, max) => {
+  const entries = Array.isArray(level?.[key]) ? level[key] : [];
+  entries.length = Math.min(entries.length, max);
+};
+
+const getUnsupportedPropKeys = (entry, allowedKeys) => {
+  const props = entry?.props;
+  if (!props) return [];
+  return Object.keys(props).filter(key => !allowedKeys.has(key));
+};
+
+const hasUnsupportedProps = (entry, allowedKeys) => {
+  return getUnsupportedPropKeys(entry, allowedKeys).length > 0;
+};
+
+const stripUnsupportedProps = (entry, allowedKeys) => {
+  if (!entry?.props) return;
+  for (const key of Object.keys(entry.props)) {
+    if (!allowedKeys.has(key)) {
+      delete entry.props[key];
+    }
+  }
+};
+
+const countPreservedNxlvMetadata = (level) => {
+  if (!level) return 0;
+  let count = 0;
+  if (Array.isArray(level.unknownLines)) count += level.unknownLines.length;
+  if (Array.isArray(level.unknownSections)) count += level.unknownSections.length;
+  if (Array.isArray(level.skillsetUnknownLines)) count += level.skillsetUnknownLines.length;
+  const addEntryUnknownLines = (entries) => {
+    if (!Array.isArray(entries)) return;
+    for (const entry of entries) {
+      if (Array.isArray(entry?.unknownLines)) count += entry.unknownLines.length;
+    }
+  };
+  addEntryUnknownLines(level.terrains);
+  addEntryUnknownLines(level.gadgets);
+  addEntryUnknownLines(level.steel);
+  if (Array.isArray(level.terrainGroups)) {
+    for (const group of level.terrainGroups) {
+      if (Array.isArray(group?.unknownLines)) count += group.unknownLines.length;
+      addEntryUnknownLines(group?.terrains);
+    }
+  }
+  return count;
+};
+
+const normalizeIssueForReport = (issue, index, source = 'level-validation') => {
+  const severity = issue?.severity === 'error'
+    ? 'error'
+    : issue?.severity === 'warning'
+      ? 'warning'
+      : 'info';
+  const destructive = issue?.destructive === true || issue?.exportFormat === 'classicLvl';
+  return {
+    index,
+    source,
+    severity,
+    code: issue?.code || null,
+    target: issue?.target || null,
+    message: String(issue?.message || ''),
+    blocker: severity === 'error' || issue?.blocking === true || issue?.blocksExport === true,
+    blocksEditing: issue?.blocksEditing === true,
+    blocksExport: severity === 'error' || issue?.blocksExport === true,
+    destructive,
+    exportFormat: issue?.exportFormat || null,
+    hasFix: typeof issue?.fix === 'function',
+    fixLabel: issue?.fixLabel || null,
+    metadata: {
+      count: Number.isFinite(issue?.count) ? issue.count : null,
+      max: Number.isFinite(issue?.max) ? issue.max : null,
+      props: Array.isArray(issue?.props) ? [...issue.props] : null,
+      advisoryCode: issue?.advisoryCode || null
+    }
+  };
+};
+
+const summarizeReportIssues = (issues) => ({
+  total: issues.length,
+  errors: issues.filter(issue => issue.severity === 'error').length,
+  warnings: issues.filter(issue => issue.severity === 'warning').length,
+  infos: issues.filter(issue => issue.severity === 'info').length,
+  blockers: issues.filter(issue => issue.blocker).length,
+  destructive: issues.filter(issue => issue.destructive).length,
+  unsupportedPreservedData: issues.filter(issue => issue.exportFormat === 'classicLvl').length
+});
+
+const levelIdentity = (level, index = 0) => ({
+  index,
+  id: level?.getHeader?.('ID') ?? level?.id ?? null,
+  title: String(level?.getHeader?.('TITLE') ?? level?.title ?? `Level ${index + 1}`),
+  style: String(level?.getHeader?.('STYLE') ?? level?.style ?? ''),
+  width: getHeaderNumber(level, 'WIDTH', DEFAULT_LEVEL_WIDTH),
+  height: getHeaderNumber(level, 'HEIGHT', DEFAULT_LEVEL_HEIGHT)
+});
+
+const validatePackConsistency = (pack = {}, assetsByStyle = null) => {
+  const levels = Array.isArray(pack?.levels)
+    ? pack.levels
+    : (Array.isArray(pack) ? pack : []);
+  const issues = [];
+  if (!levels.length) {
+    issues.push({
+      severity: 'error',
+      code: 'pack_missing_levels',
+      target: 'pack.levels',
+      message: 'Pack has no levels.',
+      blocking: true
+    });
+    return issues.map((issue, index) => normalizeIssueForReport(issue, index, 'pack-validation'));
+  }
+
+  const titleSeen = new Map();
+  const idSeen = new Map();
+  levels.forEach((level, index) => {
+    const identity = levelIdentity(level, index);
+    const titleKey = identity.title.trim().toLowerCase();
+    const idKey = identity.id == null ? '' : String(identity.id).trim().toLowerCase();
+    if (!identity.style) {
+      issues.push({
+        severity: 'warning',
+        code: 'pack_missing_style',
+        target: `levels[${index}].STYLE`,
+        message: `Level ${index + 1} has no style.`,
+        blocking: false
+      });
+    } else if (assetsByStyle && !assetsByStyle[identity.style]) {
+      issues.push({
+        severity: 'warning',
+        code: 'pack_missing_style_assets',
+        target: `levels[${index}].STYLE`,
+        message: `Level ${index + 1} references missing style assets: ${identity.style}.`,
+        blocking: false
+      });
+    }
+    if (titleKey) {
+      if (titleSeen.has(titleKey)) {
+        issues.push({
+          severity: 'warning',
+          code: 'pack_duplicate_title',
+          target: `levels[${index}].TITLE`,
+          message: `Duplicate level title: ${identity.title}.`,
+          blocking: false
+        });
+      } else {
+        titleSeen.set(titleKey, index);
+      }
+    }
+    if (idKey) {
+      if (idSeen.has(idKey)) {
+        issues.push({
+          severity: 'warning',
+          code: 'pack_duplicate_id',
+          target: `levels[${index}].ID`,
+          message: `Duplicate level id: ${identity.id}.`,
+          blocking: false
+        });
+      } else {
+        idSeen.set(idKey, index);
+      }
+    }
+  });
+
+  return issues.map((issue, index) => normalizeIssueForReport(issue, index, 'pack-validation'));
+};
+
+const createValidationReport = (level, assets = null, options = {}) => {
+  const rawIssues = Array.isArray(options.issues)
+    ? options.issues
+    : validateLevel(level, assets, options.validationOptions || options);
+  const levelIssues = rawIssues.map((issue, index) => normalizeIssueForReport(issue, index));
+  const packIssues = options.pack
+    ? validatePackConsistency(options.pack, options.assetsByStyle || null)
+    : [];
+  const issues = [...levelIssues, ...packIssues];
+  return {
+    kind: 'editor-validation-report',
+    schemaVersion: 1,
+    level: levelIdentity(level),
+    pack: options.pack
+      ? {
+        title: String(options.pack.title || options.pack.name || ''),
+        levelCount: Array.isArray(options.pack.levels) ? options.pack.levels.length : 0
+      }
+      : null,
+    summary: summarizeReportIssues(issues),
+    issues
+  };
+};
+
 const validateLevel = (level, assets = null, options = {}) => {
   if (!level) return [];
   const issues = [];
@@ -65,12 +334,49 @@ const validateLevel = (level, assets = null, options = {}) => {
     issues.push(createIssue('warning', 'Title is empty.', 'Set title', () => {
       level.setHeader('TITLE', 'Untitled');
     }));
+  } else if (String(title).length > LEVEL_NAME_LENGTH) {
+    const titleText = String(title);
+    issues.push(createDestructiveIssue(
+      'classic_title_length',
+      `Classic .lvl export stores ${LEVEL_NAME_LENGTH} title characters; the remaining ${titleText.length - LEVEL_NAME_LENGTH} will be omitted.`,
+      'Truncate title',
+      () => {
+        level.setHeader('TITLE', titleText.slice(0, LEVEL_NAME_LENGTH));
+      },
+      {
+        target: 'header.TITLE',
+        count: titleText.length,
+        max: LEVEL_NAME_LENGTH
+      }
+    ));
   }
 
   if (Array.isArray(level.terrainGroups) && level.terrainGroups.length > 0) {
-    issues.push(createIssue(
-      'warning',
-      'Terrain groups are not supported in editor preview/runtime.'
+    issues.push(createDestructiveIssue(
+      'classic_terrain_groups',
+      'Terrain groups are not exported to classic .lvl; ungroup terrain before classic export.',
+      null,
+      null,
+      {
+        target: 'terrainGroups',
+        count: level.terrainGroups.length,
+        max: 0
+      }
+    ));
+  }
+
+  const preservedMetadataCount = countPreservedNxlvMetadata(level);
+  if (preservedMetadataCount) {
+    issues.push(createDestructiveIssue(
+      'classic_preserved_nxlv_metadata',
+      'Comments and unknown NXLV sections are preserved for NXLV but are not exported to classic .lvl.',
+      null,
+      null,
+      {
+        target: 'nxlvMetadata',
+        count: preservedMetadataCount,
+        max: 0
+      }
     ));
   }
 
@@ -216,6 +522,55 @@ const validateLevel = (level, assets = null, options = {}) => {
   const exitId = assets?.exitId ?? null;
   const gadgets = Array.isArray(level.gadgets) ? level.gadgets : [];
   const steelEntries = Array.isArray(level.steel) ? level.steel : [];
+  const directTerrains = Array.isArray(level.terrains) ? level.terrains : [];
+
+  if (gadgets.length > LEVEL_OBJECT_COUNT) {
+    issues.push(createDestructiveIssue(
+      'classic_object_count',
+      `Classic .lvl export stores ${LEVEL_OBJECT_COUNT} gadgets; the remaining ${gadgets.length - LEVEL_OBJECT_COUNT} will be omitted.`,
+      'Keep first gadgets',
+      () => {
+        truncateEntries(level, 'gadgets', LEVEL_OBJECT_COUNT);
+      },
+      {
+        target: 'gadgets',
+        count: gadgets.length,
+        max: LEVEL_OBJECT_COUNT
+      }
+    ));
+  }
+
+  if (directTerrains.length > LEVEL_TERRAIN_COUNT) {
+    issues.push(createDestructiveIssue(
+      'classic_terrain_count',
+      `Classic .lvl export stores ${LEVEL_TERRAIN_COUNT} terrain pieces; the remaining ${directTerrains.length - LEVEL_TERRAIN_COUNT} will be omitted.`,
+      'Keep first terrain',
+      () => {
+        truncateEntries(level, 'terrains', LEVEL_TERRAIN_COUNT);
+      },
+      {
+        target: 'terrains',
+        count: directTerrains.length,
+        max: LEVEL_TERRAIN_COUNT
+      }
+    ));
+  }
+
+  if (steelEntries.length > LEVEL_STEEL_COUNT) {
+    issues.push(createDestructiveIssue(
+      'classic_steel_count',
+      `Classic .lvl export stores ${LEVEL_STEEL_COUNT} steel rectangles; the remaining ${steelEntries.length - LEVEL_STEEL_COUNT} will be omitted.`,
+      'Keep first steel',
+      () => {
+        truncateEntries(level, 'steel', LEVEL_STEEL_COUNT);
+      },
+      {
+        target: 'steel',
+        count: steelEntries.length,
+        max: LEVEL_STEEL_COUNT
+      }
+    ));
+  }
 
   if (Number.isFinite(entranceId)) {
     const entrances = findPieceIndices(gadgets, entranceId);
@@ -334,15 +689,36 @@ const validateLevel = (level, assets = null, options = {}) => {
   }
 
   const terrainEntries = [
-    ...(Array.isArray(level.terrains) ? level.terrains : []),
+    ...directTerrains,
     ...(Array.isArray(level.terrainGroups)
       ? level.terrainGroups.flatMap(group => Array.isArray(group?.terrains) ? group.terrains : [])
       : [])
   ];
   const gadgetEntries = Array.isArray(level.gadgets) ? level.gadgets : [];
   const gadgetOnlyProps = ['SKILL', 'LEMMINGS', 'PAIRING'];
-  const terrainUnsupportedProps = ['ROTATE', 'FLIP_HORIZONTAL', 'ONE_WAY', 'WIDTH', 'HEIGHT'];
-  const gadgetUnsupportedProps = ['ROTATE', 'FLIP_HORIZONTAL', 'WIDTH', 'HEIGHT'];
+  const terrainClassicProps = new Set([
+    'STYLE',
+    'PIECE',
+    'X',
+    'Y',
+    'FLIP_VERTICAL',
+    'NO_OVERWRITE',
+    'ERASE'
+  ]);
+  const gadgetClassicProps = new Set([
+    'STYLE',
+    'PIECE',
+    'X',
+    'Y',
+    'FLIP_VERTICAL',
+    'NO_OVERWRITE'
+  ]);
+  const steelClassicProps = new Set([
+    'X',
+    'Y',
+    'WIDTH',
+    'HEIGHT'
+  ]);
 
   const hasAnyProps = (entry, keys) => {
     const props = entry?.props;
@@ -373,26 +749,62 @@ const validateLevel = (level, assets = null, options = {}) => {
     ));
   }
 
-  const terrainWithUnsupported = terrainEntries.filter(entry => hasAnyProps(entry, terrainUnsupportedProps));
+  const terrainWithUnsupported = terrainEntries.filter(entry => hasUnsupportedProps(entry, terrainClassicProps));
   if (terrainWithUnsupported.length) {
-    issues.push(createIssue(
-      'warning',
-      'Terrain entries include unsupported classic properties (rotate/flip H/resize/one-way).',
+    const propKeys = Array.from(new Set(terrainWithUnsupported.flatMap(entry => {
+      return getUnsupportedPropKeys(entry, terrainClassicProps);
+    }))).sort();
+    issues.push(createDestructiveIssue(
+      'classic_unsupported_terrain_props',
+      `Terrain entries include properties classic .lvl cannot export (${propKeys.join(', ')}).`,
       'Remove unsupported terrain props',
       () => {
-        for (const entry of terrainWithUnsupported) stripProps(entry, terrainUnsupportedProps);
+        for (const entry of terrainWithUnsupported) stripUnsupportedProps(entry, terrainClassicProps);
+      },
+      {
+        target: 'terrains',
+        count: terrainWithUnsupported.length,
+        props: propKeys
       }
     ));
   }
 
-  const gadgetWithUnsupported = gadgetEntries.filter(entry => hasAnyProps(entry, gadgetUnsupportedProps));
+  const gadgetWithUnsupported = gadgetEntries.filter(entry => hasUnsupportedProps(entry, gadgetClassicProps));
   if (gadgetWithUnsupported.length) {
-    issues.push(createIssue(
-      'warning',
-      'Gadget entries include unsupported classic properties (rotate/flip H/resize).',
+    const propKeys = Array.from(new Set(gadgetWithUnsupported.flatMap(entry => {
+      return getUnsupportedPropKeys(entry, gadgetClassicProps);
+    }))).sort();
+    issues.push(createDestructiveIssue(
+      'classic_unsupported_gadget_props',
+      `Gadget entries include properties classic .lvl cannot export (${propKeys.join(', ')}).`,
       'Remove unsupported gadget props',
       () => {
-        for (const entry of gadgetWithUnsupported) stripProps(entry, gadgetUnsupportedProps);
+        for (const entry of gadgetWithUnsupported) stripUnsupportedProps(entry, gadgetClassicProps);
+      },
+      {
+        target: 'gadgets',
+        count: gadgetWithUnsupported.length,
+        props: propKeys
+      }
+    ));
+  }
+
+  const steelWithUnsupported = steelEntries.filter(entry => hasUnsupportedProps(entry, steelClassicProps));
+  if (steelWithUnsupported.length) {
+    const propKeys = Array.from(new Set(steelWithUnsupported.flatMap(entry => {
+      return getUnsupportedPropKeys(entry, steelClassicProps);
+    }))).sort();
+    issues.push(createDestructiveIssue(
+      'classic_unsupported_steel_props',
+      `Steel entries include properties classic .lvl cannot export (${propKeys.join(', ')}).`,
+      'Remove unsupported steel props',
+      () => {
+        for (const entry of steelWithUnsupported) stripUnsupportedProps(entry, steelClassicProps);
+      },
+      {
+        target: 'steel',
+        count: steelWithUnsupported.length,
+        props: propKeys
       }
     ));
   }
@@ -432,13 +844,20 @@ const validateLevel = (level, assets = null, options = {}) => {
       'Snap rotations',
       () => {
         for (const { entry, snapped } of snapRotations) {
-          if (entry?.props) entry.props.ROTATE = snapped;
+          if (entry?.props && Object.prototype.hasOwnProperty.call(entry.props, 'ROTATE')) {
+            entry.props.ROTATE = snapped;
+          }
         }
       }
     ));
   }
 
+  appendSolverAdvisoryIssues(issues, level, assets, options);
   return issues;
 };
 
-export { validateLevel };
+export {
+  createValidationReport,
+  validateLevel,
+  validatePackConsistency
+};
diff --git a/js/editor/NxlvParser.js b/js/editor/NxlvParser.js
index 3905d3b5..a6414cb7 100644
--- a/js/editor/NxlvParser.js
+++ b/js/editor/NxlvParser.js
@@ -25,7 +25,9 @@ const ENTRY_NUMERIC_KEYS = new Set([
   'HEIGHT',
   'PAIRING',
   'SKILL',
-  'LEMMINGS'
+  'LEMMINGS',
+  'MIDI_FLAG_ID',
+  'MIDI_FLAG_COOLDOWN'
 ]);
 
 const ENTRY_BOOLEAN_KEYS = new Set([
@@ -34,7 +36,8 @@ const ENTRY_BOOLEAN_KEYS = new Set([
   'NO_OVERWRITE',
   'ERASE',
   'ONE_WAY',
-  'STEEL'
+  'STEEL',
+  'MIDI_FLAG'
 ]);
 
 function parseNumberValue(value) {
diff --git a/js/editor/editor-controller/EditorControllerClipboard.js b/js/editor/editor-controller/EditorControllerClipboard.js
new file mode 100644
index 00000000..82ea2eac
--- /dev/null
+++ b/js/editor/editor-controller/EditorControllerClipboard.js
@@ -0,0 +1,538 @@
+import {
+  DEFAULT_GRID,
+  DEFAULT_HANDLE_SIZE,
+  EditorHistory,
+  EditorTools,
+  MAX_BRUSH_SIZE,
+  MAX_ENTRANCES,
+  MAX_EXITS,
+  MAX_MIDI_FLAG_ID,
+  MIDI_FLAG_TRIGGER_MAX,
+  __test__,
+  boundsIntersect,
+  clampBrushSize,
+  clampMidiFlagId,
+  clampSize,
+  cloneEntry,
+  coerceEntryNumber,
+  createGadgetEntry,
+  createSteelEntry,
+  createTerrainEntry,
+  ensureEntryUid,
+  findEntryAt,
+  getEntryBounds,
+  isMidiFlagEnabled,
+  normalizeBounds,
+  removeEntryAt,
+  selectionKey,
+  setEntryProp,
+  snapValue
+} from './EditorControllerShared.js';
+const editorControllerClipboardMethods = {
+  copySelection() {
+    const entries = this.getSelectedEntries();
+    if (entries.length === 0) return false;
+    let minX = Infinity;
+    let minY = Infinity;
+    const items = [];
+    for (const selected of entries) {
+      const props = selected.entry?.props || {};
+      const x = coerceEntryNumber(props.X, 0);
+      const y = coerceEntryNumber(props.Y, 0);
+      minX = Math.min(minX, x);
+      minY = Math.min(minY, y);
+      items.push({
+        type: selected.type,
+        entry: cloneEntry(selected.entry, { assignUid: false }),
+        offsetX: x,
+        offsetY: y
+      });
+    }
+    for (const item of items) {
+      item.offsetX -= minX;
+      item.offsetY -= minY;
+    }
+    this._clipboard = { items, minX, minY };
+    this._pasteOffset = 0;
+    return true;
+  },
+
+  _getPasteStep() {
+    if (this.snapEnabled && Number.isFinite(this.gridSize) && this.gridSize > 0) {
+      return this.gridSize;
+    }
+    return 1;
+  },
+
+  _cloneSelection(entries, offsetX, offsetY) {
+    const next = [];
+    for (const selected of entries) {
+      const list = this._getListForType(selected.type);
+      if (!Array.isArray(list)) continue;
+      const prefix = selected.type === 'gadget' ? 'g' : selected.type === 'steel' ? 's' : 't';
+      const clone = cloneEntry(selected.entry, { prefix });
+      clone.props.X = coerceEntryNumber(clone.props.X, 0) + offsetX;
+      clone.props.Y = coerceEntryNumber(clone.props.Y, 0) + offsetY;
+      list.push(clone);
+      next.push({ type: selected.type, index: list.length - 1 });
+    }
+    if (!next.length) return null;
+    this._setSelection(next);
+    this._markChanged();
+    return next;
+  },
+
+  pasteSelection(options = {}) {
+    if (!this.session?.level || !this._clipboard?.items?.length) return false;
+    const historyLabel = typeof options.historyLabel === 'string'
+      ? options.historyLabel
+      : 'Paste';
+    const previewLabel = typeof options.previewLabel === 'string'
+      ? options.previewLabel
+      : 'Paste';
+    const commitHistory = options.commitHistory !== false;
+    const requestPreview = options.requestPreview !== false;
+    const step = this._getPasteStep();
+    this._pasteOffset += step;
+    const baseX = coerceEntryNumber(this._clipboard.minX, 0) + this._pasteOffset;
+    const baseY = coerceEntryNumber(this._clipboard.minY, 0) + this._pasteOffset;
+    const entries = this._clipboard.items.map(item => ({
+      type: item.type,
+      entry: item.entry,
+      offsetX: item.offsetX,
+      offsetY: item.offsetY
+    }));
+    const selected = [];
+    for (const item of entries) {
+      const list = this._getListForType(item.type);
+      if (!Array.isArray(list)) continue;
+      const prefix = item.type === 'gadget' ? 'g' : item.type === 'steel' ? 's' : 't';
+      const clone = cloneEntry(item.entry, { prefix });
+      clone.props.X = baseX + item.offsetX;
+      clone.props.Y = baseY + item.offsetY;
+      list.push(clone);
+      selected.push({ type: item.type, index: list.length - 1 });
+    }
+    if (!selected.length) return false;
+    this._setSelection(selected);
+    if (commitHistory) {
+      this._commitHistory(historyLabel);
+    }
+    if (requestPreview) {
+      this._requestPreview(previewLabel);
+    }
+    return true;
+  },
+
+  duplicateSelection() {
+    const copied = this.copySelection();
+    if (!copied) return false;
+    const pasted = this.runHistoryTransaction('Duplicate', () => this.pasteSelection({
+      historyLabel: 'Duplicate',
+      previewLabel: 'Duplicate',
+      commitHistory: true,
+      requestPreview: false
+    }));
+    if (pasted) {
+      this._requestPreview('Duplicate');
+    }
+    return pasted;
+  },
+
+  nudgeSelection(dx, dy, step = 1) {
+    const entries = this.getSelectedEntries();
+    if (entries.length === 0) return false;
+    const moveX = coerceEntryNumber(dx, 0) * step;
+    const moveY = coerceEntryNumber(dy, 0) * step;
+    for (const selected of entries) {
+      const props = selected.entry?.props;
+      if (!props) continue;
+      props.X = coerceEntryNumber(props.X, 0) + moveX;
+      props.Y = coerceEntryNumber(props.Y, 0) + moveY;
+    }
+    this._callbacks.onSelectionChange?.(this.getSelectedEntries());
+    this._commitHistory('Nudge');
+    this._requestPreview('Nudge');
+    return true;
+  },
+
+  snapSelectionToGrid() {
+    const entries = this.getSelectedEntries();
+    if (entries.length === 0) return false;
+    const grid = Number.isFinite(this.gridSize) && this.gridSize > 0 ? this.gridSize : 1;
+    for (const selected of entries) {
+      const props = selected.entry?.props;
+      if (!props) continue;
+      props.X = snapValue(coerceEntryNumber(props.X, 0), grid);
+      props.Y = snapValue(coerceEntryNumber(props.Y, 0), grid);
+    }
+    this._callbacks.onSelectionChange?.(this.getSelectedEntries());
+    this._commitHistory('Snap');
+    this._requestPreview('Snap');
+    return true;
+  },
+
+  _getEntryMetaForType(type, entry) {
+    if (type === 'gadget') {
+      return this.assets?.gadgetById?.get?.(entry?.props?.PIECE) || null;
+    }
+    if (type === 'terrain') {
+      return this.assets?.terrainById?.get?.(entry?.props?.PIECE) || null;
+    }
+    return null;
+  },
+
+  _getPieceMetaByType(type) {
+    if (type === 'gadget') {
+      return this.assets?.gadgetById || null;
+    }
+    if (type === 'terrain') {
+      return this.assets?.terrainById || null;
+    }
+    return null;
+  },
+
+  _getSelectionBoundsEntries(entries = null) {
+    const selectedEntries = Array.isArray(entries) ? entries : this.getSelectedEntries();
+    if (!selectedEntries.length) return null;
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    const resolved = [];
+    for (const selected of selectedEntries) {
+      const meta = this._getEntryMetaForType(selected.type, selected.entry);
+      const bounds = getEntryBounds(selected.entry, meta);
+      if (!bounds) continue;
+      minX = Math.min(minX, bounds.x);
+      minY = Math.min(minY, bounds.y);
+      maxX = Math.max(maxX, bounds.x + bounds.width);
+      maxY = Math.max(maxY, bounds.y + bounds.height);
+      resolved.push({ ...selected, bounds });
+    }
+    if (!resolved.length) return null;
+    return {
+      minX,
+      minY,
+      maxX,
+      maxY,
+      width: maxX - minX,
+      height: maxY - minY,
+      entries: resolved
+    };
+  },
+
+  alignSelection(axis = 'x', anchor = 'min') {
+    return this.runHistoryTransaction('Align', () => {
+      const group = this._getSelectionBoundsEntries();
+      if (!group || group.entries.length < 2) return false;
+      const isX = axis === 'x';
+      const groupMin = isX ? group.minX : group.minY;
+      const groupMax = isX ? group.maxX : group.maxY;
+      const groupCenter = (groupMin + groupMax) / 2;
+      for (const selected of group.entries) {
+        const props = selected.entry?.props;
+        if (!props) continue;
+        const bounds = selected.bounds;
+        const size = isX ? bounds.width : bounds.height;
+        const offset = isX
+          ? coerceEntryNumber(props.X, 0) - bounds.x
+          : coerceEntryNumber(props.Y, 0) - bounds.y;
+        let nextStart = groupMin;
+        if (anchor === 'max' || anchor === 'end') {
+          nextStart = groupMax - size;
+        } else if (anchor === 'center' || anchor === 'mid') {
+          nextStart = groupCenter - (size / 2);
+        }
+        if (isX) props.X = Math.round(nextStart + offset);
+        else props.Y = Math.round(nextStart + offset);
+      }
+      this._callbacks.onSelectionChange?.(this.getSelectedEntries());
+      this._commitHistory('Align');
+      this._requestPreview('Align');
+      return true;
+    });
+  },
+
+  distributeSelection(axis = 'x') {
+    return this.runHistoryTransaction('Distribute', () => {
+      const group = this._getSelectionBoundsEntries();
+      if (!group || group.entries.length < 3) return false;
+      const isX = axis === 'x';
+      const sorted = group.entries.slice().sort((a, b) => {
+        const av = isX ? a.bounds.x : a.bounds.y;
+        const bv = isX ? b.bounds.x : b.bounds.y;
+        return av - bv;
+      });
+      const first = sorted[0];
+      const last = sorted[sorted.length - 1];
+      const firstStart = isX ? first.bounds.x : first.bounds.y;
+      const lastStart = isX ? last.bounds.x : last.bounds.y;
+      const spacing = (lastStart - firstStart) / (sorted.length - 1);
+      for (let i = 1; i < sorted.length - 1; i++) {
+        const selected = sorted[i];
+        const props = selected.entry?.props;
+        if (!props) continue;
+        const bounds = selected.bounds;
+        const offset = isX
+          ? coerceEntryNumber(props.X, 0) - bounds.x
+          : coerceEntryNumber(props.Y, 0) - bounds.y;
+        const nextStart = firstStart + (spacing * i);
+        if (isX) props.X = Math.round(nextStart + offset);
+        else props.Y = Math.round(nextStart + offset);
+      }
+      this._callbacks.onSelectionChange?.(this.getSelectedEntries());
+      this._commitHistory('Distribute');
+      this._requestPreview('Distribute');
+      return true;
+    });
+  },
+
+  replaceSelectionPiece(pieceId, type = null) {
+    return this.runHistoryTransaction('Replace', () => {
+      const nextPieceId = Number(pieceId);
+      if (!Number.isFinite(nextPieceId)) return false;
+      const entries = this.getSelectedEntries();
+      if (!entries.length) return false;
+      let changed = false;
+      for (const selected of entries) {
+        if (type && selected.type !== type) continue;
+        if (selected.type === 'steel') continue;
+        if (!selected.entry?.props) continue;
+        if (selected.entry.props.PIECE !== nextPieceId) {
+          selected.entry.props.PIECE = nextPieceId;
+          changed = true;
+        }
+      }
+      if (!changed) return false;
+      this._callbacks.onSelectionChange?.(this.getSelectedEntries());
+      this._commitHistory('Replace');
+      this._requestPreview('Replace');
+      return true;
+    });
+  },
+
+  randomizeSelectionPieces(pieceIds = [], options = {}) {
+    return this.runHistoryTransaction('Randomize', () => {
+      const entries = this.getSelectedEntries();
+      if (!entries.length) return false;
+      const {
+        type = null,
+        requireSameSize = false,
+        seed = null
+      } = options;
+      const candidates = Array.from(new Set(
+        (Array.isArray(pieceIds) ? pieceIds : [])
+          .map(value => Number(value))
+          .filter(value => Number.isFinite(value))
+      ));
+      if (!candidates.length) return false;
+
+      let random = Math.random;
+      if (Number.isFinite(seed)) {
+        let state = (Math.floor(seed) >>> 0) || 1;
+        random = () => {
+          state = (state * 1664525 + 1013904223) >>> 0;
+          return state / 4294967296;
+        };
+      }
+      const pickPiece = (available) => {
+        if (!available.length) return null;
+        const index = Math.min(available.length - 1, Math.floor(random() * available.length));
+        return available[index];
+      };
+      let changed = false;
+      for (const selected of entries) {
+        if (type && selected.type !== type) continue;
+        if (selected.type === 'steel') continue;
+        const props = selected.entry?.props;
+        if (!props) continue;
+        const metaById = this._getPieceMetaByType(selected.type);
+        let available = candidates;
+        if (requireSameSize && metaById?.get) {
+          const sourceMeta = metaById.get(props.PIECE);
+          if (sourceMeta) {
+            available = candidates.filter(id => {
+              const candidateMeta = metaById.get(id);
+              return candidateMeta
+                  && candidateMeta.width === sourceMeta.width
+                  && candidateMeta.height === sourceMeta.height;
+            });
+            if (!available.length) {
+              continue;
+            }
+          }
+        }
+        const nextPiece = pickPiece(available);
+        if (!Number.isFinite(nextPiece)) continue;
+        if (props.PIECE !== nextPiece) {
+          props.PIECE = nextPiece;
+          changed = true;
+        }
+      }
+      if (!changed) return false;
+      this._callbacks.onSelectionChange?.(this.getSelectedEntries());
+      this._commitHistory('Randomize');
+      this._requestPreview('Randomize');
+      return true;
+    });
+  },
+
+  transformSelectionGroup({ scaleX = 1, scaleY = 1 } = {}) {
+    return this.runHistoryTransaction('Transform', () => {
+      const group = this._getSelectionBoundsEntries();
+      if (!group || group.entries.length < 1) return false;
+      const sx = Number.isFinite(scaleX) ? scaleX : 1;
+      const sy = Number.isFinite(scaleY) ? scaleY : 1;
+      if (sx === 1 && sy === 1) return false;
+      const cx = group.minX + (group.width / 2);
+      const cy = group.minY + (group.height / 2);
+      for (const selected of group.entries) {
+        const props = selected.entry?.props;
+        if (!props) continue;
+        const bounds = selected.bounds;
+        const nx = cx + ((bounds.x - cx) * sx);
+        const ny = cy + ((bounds.y - cy) * sy);
+        const dx = nx - bounds.x;
+        const dy = ny - bounds.y;
+        props.X = Math.round(coerceEntryNumber(props.X, 0) + dx);
+        props.Y = Math.round(coerceEntryNumber(props.Y, 0) + dy);
+        if (Object.prototype.hasOwnProperty.call(props, 'WIDTH')) {
+          props.WIDTH = clampSize(coerceEntryNumber(Number(props.WIDTH), 1) * Math.max(0.01, sx));
+        }
+        if (Object.prototype.hasOwnProperty.call(props, 'HEIGHT')) {
+          props.HEIGHT = clampSize(coerceEntryNumber(Number(props.HEIGHT), 1) * Math.max(0.01, sy));
+        }
+      }
+      this._callbacks.onSelectionChange?.(this.getSelectedEntries());
+      this._commitHistory('Transform');
+      this._requestPreview('Transform');
+      return true;
+    });
+  },
+
+  deleteSelected() {
+    return this.runHistoryTransaction('Delete', () => {
+      if (!this.session?.level || this.selection.length === 0) return false;
+      const terrainIndices = [];
+      const gadgetIndices = [];
+      const steelIndices = [];
+      for (const selected of this.selection) {
+        if (selected.type === 'gadget') gadgetIndices.push(selected.index);
+        else if (selected.type === 'steel') steelIndices.push(selected.index);
+        else terrainIndices.push(selected.index);
+      }
+      terrainIndices.sort((a, b) => b - a);
+      gadgetIndices.sort((a, b) => b - a);
+      steelIndices.sort((a, b) => b - a);
+      for (const index of terrainIndices) {
+        removeEntryAt(this.session.level, 'terrain', index);
+      }
+      for (const index of gadgetIndices) {
+        removeEntryAt(this.session.level, 'gadget', index);
+      }
+      for (const index of steelIndices) {
+        removeEntryAt(this.session.level, 'steel', index);
+      }
+      this._invalidateEntryIndexCache();
+      this.selection = [];
+      this._callbacks.onSelectionChange?.(this.getSelectedEntries());
+      this._commitHistory('Delete');
+      this._requestPreview('Delete');
+      return true;
+    });
+  },
+
+  _reorderSelection(mode) {
+    return this.runHistoryTransaction('Reorder', () => {
+      if (!this.session?.level || this.selection.length === 0) return false;
+      const groups = {
+        terrain: [],
+        gadget: [],
+        steel: []
+      };
+      for (const selected of this.selection) {
+        if (groups[selected.type]) groups[selected.type].push(selected.index);
+      }
+      const reorderList = (list, indices, dir) => {
+        if (!Array.isArray(list) || indices.length === 0) return null;
+        const unique = Array.from(new Set(indices)).filter(idx => idx >= 0 && idx < list.length);
+        if (!unique.length) return null;
+        const selectedSet = new Set(unique);
+        if (dir === 'front' || dir === 'back') {
+          const ordered = unique.slice().sort((a, b) => a - b).map(idx => list[idx]);
+          const remaining = list.filter((_, idx) => !selectedSet.has(idx));
+          list.length = 0;
+          if (dir === 'front') {
+            list.push(...remaining, ...ordered);
+          } else {
+            list.push(...ordered, ...remaining);
+          }
+          const next = new Map();
+          list.forEach((entry, idx) => next.set(entry, idx));
+          return ordered.map(entry => next.get(entry)).filter(idx => idx != null);
+        }
+        if (dir === 'forward') {
+          const sorted = unique.slice().sort((a, b) => b - a);
+          for (const idx of sorted) {
+            if (idx >= list.length - 1) continue;
+            if (selectedSet.has(idx + 1)) continue;
+            const tmp = list[idx + 1];
+            list[idx + 1] = list[idx];
+            list[idx] = tmp;
+            selectedSet.delete(idx);
+            selectedSet.add(idx + 1);
+          }
+          return Array.from(selectedSet);
+        }
+        if (dir === 'backward') {
+          const sorted = unique.slice().sort((a, b) => a - b);
+          for (const idx of sorted) {
+            if (idx <= 0) continue;
+            if (selectedSet.has(idx - 1)) continue;
+            const tmp = list[idx - 1];
+            list[idx - 1] = list[idx];
+            list[idx] = tmp;
+            selectedSet.delete(idx);
+            selectedSet.add(idx - 1);
+          }
+          return Array.from(selectedSet);
+        }
+        return null;
+      };
+
+      const nextSelection = [];
+      for (const [type, indices] of Object.entries(groups)) {
+        const list = this._getListForType(type);
+        const nextIndices = reorderList(list, indices, mode);
+        if (!nextIndices) continue;
+        for (const idx of nextIndices) {
+          nextSelection.push({ type, index: idx });
+        }
+      }
+      if (!nextSelection.length) return false;
+      this._invalidateEntryIndexCache();
+      this._setSelection(nextSelection);
+      this._commitHistory('Reorder');
+      this._requestPreview('Reorder');
+      return true;
+    });
+  },
+
+  bringSelectionToFront() {
+    return this._reorderSelection('front');
+  },
+
+  sendSelectionToBack() {
+    return this._reorderSelection('back');
+  },
+
+  moveSelectionForward() {
+    return this._reorderSelection('forward');
+  },
+
+  moveSelectionBackward() {
+    return this._reorderSelection('backward');
+  }
+};
+export { editorControllerClipboardMethods };
\ No newline at end of file
diff --git a/js/editor/editor-controller/EditorControllerCore.js b/js/editor/editor-controller/EditorControllerCore.js
new file mode 100644
index 00000000..1191ac85
--- /dev/null
+++ b/js/editor/editor-controller/EditorControllerCore.js
@@ -0,0 +1,93 @@
+import {
+  DEFAULT_GRID,
+  DEFAULT_HANDLE_SIZE,
+  EditorHistory,
+  EditorTools,
+  MAX_BRUSH_SIZE,
+  MAX_ENTRANCES,
+  MAX_EXITS,
+  MAX_MIDI_FLAG_ID,
+  MIDI_FLAG_TRIGGER_MAX,
+  __test__,
+  boundsIntersect,
+  clampBrushSize,
+  clampMidiFlagId,
+  clampSize,
+  cloneEntry,
+  coerceEntryNumber,
+  createGadgetEntry,
+  createSteelEntry,
+  createTerrainEntry,
+  ensureEntryUid,
+  findEntryAt,
+  getEntryBounds,
+  isMidiFlagEnabled,
+  normalizeBounds,
+  removeEntryAt,
+  selectionKey,
+  setEntryProp,
+  snapValue
+} from './EditorControllerShared.js';
+import { editorControllerSelectionMethods } from './EditorControllerSelection.js';
+import { editorControllerClipboardMethods } from './EditorControllerClipboard.js';
+import { editorControllerPointerMethods } from './EditorControllerPointer.js';
+class EditorController {
+  constructor(options = {}) {
+    this.session = options.session || null;
+    this.history = options.history || new EditorHistory();
+    this.tool = options.tool || EditorTools.SELECT;
+    this.gridSize = Number.isFinite(options.gridSize) ? options.gridSize : DEFAULT_GRID;
+    this.snapEnabled = options.snapEnabled !== false;
+    this.brushSize = 1;
+    this.setBrushSize(Number.isFinite(options.brushSize) ? options.brushSize : 1);
+    this.eraseGadgets = !!options.eraseGadgets;
+    this.assets = options.assets || null;
+    this.selectedTerrainId = 0;
+    this.selectedGadgetId = 0;
+    this.selectedTriggerId = null;
+    this._selection = [];
+    this._selectionSet = new Set();
+    this._entryIndexCache = {
+      terrain: { list: null, size: -1, map: new Map() },
+      gadget: { list: null, size: -1, map: new Map() },
+      steel: { list: null, size: -1, map: new Map() }
+    };
+    Object.defineProperty(this, 'selection', {
+      configurable: true,
+      enumerable: true,
+      get: () => this._selection,
+      set: (value) => {
+        this._setSelectionState(value);
+      }
+    });
+    this.selection = [];
+    this._drag = null;
+    this._resize = null;
+    this._marquee = null;
+    this._steelDraft = null;
+    this._strokeChanged = false;
+    this._stampSet = new Set();
+    this._lastBrushPos = null;
+    this._clipboard = null;
+    this._pasteOffset = 0;
+    this._previewTimer = null;
+    this._pointerDown = false;
+    this._pointerButton = 0;
+    this._previewDelay = Number.isFinite(options.previewDelay) ? options.previewDelay : 60;
+    this.handleSize = Number.isFinite(options.handleSize) ? options.handleSize : DEFAULT_HANDLE_SIZE;
+    this._callbacks = {
+      onSelectionChange: null,
+      onLevelChange: null,
+      onPreviewRequest: null,
+      onMarqueeChange: null
+    };
+  }
+}
+for (const methods of [
+  editorControllerSelectionMethods,
+  editorControllerClipboardMethods,
+  editorControllerPointerMethods
+]) {
+  Object.defineProperties(EditorController.prototype, Object.getOwnPropertyDescriptors(methods));
+}
+export { EditorController };
\ No newline at end of file
diff --git a/js/editor/editor-controller/EditorControllerPointer.js b/js/editor/editor-controller/EditorControllerPointer.js
new file mode 100644
index 00000000..7207a635
--- /dev/null
+++ b/js/editor/editor-controller/EditorControllerPointer.js
@@ -0,0 +1,11 @@
+import { editorControllerPointerInputMethods } from './EditorControllerPointerInput.js';
+import { editorControllerPointerSelectionMethods } from './EditorControllerPointerSelection.js';
+import { editorControllerPointerToolMethods } from './EditorControllerPointerTools.js';
+
+const editorControllerPointerMethods = {
+  ...editorControllerPointerSelectionMethods,
+  ...editorControllerPointerToolMethods,
+  ...editorControllerPointerInputMethods
+};
+
+export { editorControllerPointerMethods };
diff --git a/js/editor/editor-controller/EditorControllerPointerInput.js b/js/editor/editor-controller/EditorControllerPointerInput.js
new file mode 100644
index 00000000..95e3c8db
--- /dev/null
+++ b/js/editor/editor-controller/EditorControllerPointerInput.js
@@ -0,0 +1,264 @@
+import {
+  EditorTools,
+  MAX_ENTRANCES,
+  MAX_EXITS,
+  clampSize,
+  setEntryProp,
+  snapValue
+} from './EditorControllerShared.js';
+
+const editorControllerPointerInputMethods = {
+  handlePointerDown(pos, button = 0, options = {}) {
+    if (!this.session?.level) return;
+    const { x, y } = this._snap(pos.x, pos.y);
+    const shiftKey = options.shiftKey === true;
+    const altKey = options.altKey === true;
+    this._pointerDown = button === 0;
+    this._pointerButton = button;
+    if (button === 2) {
+      this.clearSelection();
+      this._clearMarquee();
+      return;
+    }
+
+    this._beginStroke();
+
+    switch (this.tool) {
+    case EditorTools.SELECT: {
+      const resizeHandle = !shiftKey ? this._getResizeHandleAt(x, y) : null;
+      if (resizeHandle) {
+        const selected = this.getSelectedEntry();
+        const bounds = this.getSelectionBounds();
+        if (selected && bounds) {
+          this._resize = {
+            handle: resizeHandle,
+            type: selected.type,
+            index: selected.index,
+            bounds
+          };
+          return;
+        }
+      }
+      const hit = this._findSelectionAt(x, y);
+      if (!hit) {
+        if (!shiftKey) this.clearSelection();
+        this._beginMarquee(x, y, shiftKey);
+        return;
+      }
+      if (shiftKey) {
+        this._selectHit(hit, { toggle: true });
+        return;
+      }
+      if (!this._isSelected(hit.type, hit.index)) {
+        this._selectHit(hit);
+      }
+      if (altKey) {
+        this._cloneSelection(this.getSelectedEntries(), 0, 0);
+      }
+      const selectedEntries = this.getSelectedEntries();
+      this._drag = {
+        entries: selectedEntries.map(entry => ({
+          type: entry.type,
+          index: entry.index,
+          offsetX: x - (entry.entry?.props?.X || 0),
+          offsetY: y - (entry.entry?.props?.Y || 0)
+        })),
+        label: altKey ? 'Duplicate' : 'Move'
+      };
+      break;
+    }
+    case EditorTools.TERRAIN:
+      this._placeTerrainAt(x, y);
+      this._commitHistory('Terrain');
+      this._requestPreview('Terrain');
+      break;
+    case EditorTools.GADGET:
+      this._placeGadgetAt(x, y, this.selectedGadgetId);
+      this._commitHistory('Gadget');
+      this._requestPreview('Gadget');
+      break;
+    case EditorTools.TRIGGER:
+      this._placeGadgetAt(x, y, this.selectedTriggerId ?? this.selectedGadgetId);
+      this._commitHistory('Trigger');
+      this._requestPreview('Trigger');
+      break;
+    case EditorTools.MIDI_FLAG:
+      this._placeMidiFlagAt(x, y);
+      this._commitHistory('MIDI Flag');
+      this._requestPreview('MIDI Flag');
+      break;
+    case EditorTools.ENTRANCE: {
+      const entranceId = this.assets?.entranceId ?? 1;
+      this._trimGadgetsById(entranceId, MAX_ENTRANCES - 1);
+      this._placeGadgetAt(x, y, entranceId);
+      this._commitHistory('Entrance');
+      this._requestPreview('Entrance');
+      break;
+    }
+    case EditorTools.EXIT: {
+      const exitId = this.assets?.exitId ?? this.selectedGadgetId;
+      if (Number.isFinite(exitId)) {
+        this._trimGadgetsById(exitId, MAX_EXITS - 1);
+      }
+      this._placeGadgetAt(x, y, exitId);
+      this._commitHistory('Exit');
+      this._requestPreview('Exit');
+      break;
+    }
+    case EditorTools.STEEL:
+      this._beginSteelDraft(x, y);
+      break;
+    case EditorTools.BRUSH:
+      this._brushAt(x, y);
+      this._lastBrushPos = { x, y };
+      this._requestPreview('Brush');
+      break;
+    case EditorTools.ERASER:
+      this._eraseAt(x, y);
+      this._lastBrushPos = { x, y };
+      this._requestPreview('Erase');
+      break;
+    default:
+      break;
+    }
+  },
+
+  handlePointerMove(pos, options = {}) {
+    if (!this.session?.level) return;
+    const { x, y } = this._snap(pos.x, pos.y);
+    const isDown = typeof options.isDown === 'boolean'
+      ? options.isDown
+      : this._pointerDown;
+
+    if (this._steelDraft && this.tool === EditorTools.STEEL) {
+      this._updateSteelDraft(x, y);
+      return;
+    }
+
+    if (this._resize && this.tool === EditorTools.SELECT) {
+      const selected = this.getSelectedEntry();
+      if (!selected) return;
+      const bounds = this._resize.bounds;
+      let left = bounds.x;
+      let right = bounds.x + bounds.width;
+      let top = bounds.y;
+      let bottom = bounds.y + bounds.height;
+      const snapCoord = (value) => (
+        this.snapEnabled ? snapValue(value, this.gridSize) : Math.round(value)
+      );
+      const handle = this._resize.handle;
+      if (handle.includes('w')) left = snapCoord(x);
+      if (handle.includes('e')) right = snapCoord(x);
+      if (handle.includes('n')) top = snapCoord(y);
+      if (handle.includes('s')) bottom = snapCoord(y);
+      if (right <= left) {
+        if (handle.includes('w')) left = right - 1;
+        else right = left + 1;
+      }
+      if (bottom <= top) {
+        if (handle.includes('n')) top = bottom - 1;
+        else bottom = top + 1;
+      }
+      const width = clampSize(right - left);
+      const height = clampSize(bottom - top);
+      const entry = selected.entry;
+      setEntryProp(entry, 'X', left, { removeIfEmpty: false });
+      setEntryProp(entry, 'Y', top, { removeIfEmpty: false });
+      setEntryProp(entry, 'WIDTH', width, { removeIfEmpty: false });
+      setEntryProp(entry, 'HEIGHT', height, { removeIfEmpty: false });
+      this._markChanged();
+      this._callbacks.onSelectionChange?.(this.getSelectedEntries());
+      this._requestPreview('Resize');
+      return;
+    }
+
+    if (this._drag && this.tool === EditorTools.SELECT) {
+      for (const dragEntry of this._drag.entries || []) {
+        const list = this._getListForType(dragEntry.type);
+        const entry = list?.[dragEntry.index];
+        if (entry) {
+          entry.props.X = x - dragEntry.offsetX;
+          entry.props.Y = y - dragEntry.offsetY;
+          this._markChanged();
+        }
+      }
+      if (this._drag.entries?.length) {
+        this._callbacks.onSelectionChange?.(this.getSelectedEntries());
+        this._requestPreview('Move');
+      }
+      return;
+    }
+
+    if (isDown && this._marquee && this.tool === EditorTools.SELECT) {
+      this._updateMarquee(x, y);
+      return;
+    }
+
+    if (isDown && this.tool === EditorTools.BRUSH) {
+      if (this._lastBrushPos) {
+        this._brushLine(this._lastBrushPos, { x, y });
+      } else {
+        this._brushAt(x, y);
+      }
+      this._lastBrushPos = { x, y };
+      this._requestPreview('Brush');
+    }
+
+    if (isDown && this.tool === EditorTools.ERASER) {
+      if (this._lastBrushPos) {
+        this._eraseLine(this._lastBrushPos, { x, y });
+      } else {
+        this._eraseAt(x, y);
+      }
+      this._lastBrushPos = { x, y };
+      this._requestPreview('Erase');
+    }
+  },
+
+  handlePointerUp() {
+    this._pointerDown = false;
+    this._pointerButton = 0;
+    if (!this.session?.level) return;
+    this._lastBrushPos = null;
+    if (this._steelDraft) {
+      this._steelDraft = null;
+      if (this._strokeChanged) {
+        this._commitHistory('Steel');
+      }
+      this._strokeChanged = false;
+      return;
+    }
+    if (this._resize) {
+      this._resize = null;
+      if (this._strokeChanged) {
+        this._commitHistory('Resize');
+      }
+      this._strokeChanged = false;
+      return;
+    }
+    if (this._drag) {
+      const label = this._drag.label || 'Move';
+      this._drag = null;
+      if (this._strokeChanged) {
+        this._commitHistory(label);
+      }
+      this._strokeChanged = false;
+      return;
+    }
+    if (this._marquee) {
+      this._applyMarqueeSelection();
+      this._clearMarquee();
+      return;
+    }
+
+    if (this.tool === EditorTools.BRUSH && this._strokeChanged) {
+      this._commitHistory('Brush');
+    }
+    if (this.tool === EditorTools.ERASER && this._strokeChanged) {
+      this._commitHistory('Erase');
+    }
+    this._strokeChanged = false;
+  }
+};
+
+export { editorControllerPointerInputMethods };
diff --git a/js/editor/editor-controller/EditorControllerPointerSelection.js b/js/editor/editor-controller/EditorControllerPointerSelection.js
new file mode 100644
index 00000000..6ab8dc58
--- /dev/null
+++ b/js/editor/editor-controller/EditorControllerPointerSelection.js
@@ -0,0 +1,143 @@
+import {
+  boundsIntersect,
+  findEntryAt,
+  getEntryBounds,
+  snapValue
+} from './EditorControllerShared.js';
+
+const editorControllerPointerSelectionMethods = {
+  undo() {
+    const level = this.history.undo();
+    if (!level || !this.session) return null;
+    this.session.level = level;
+    this._invalidateEntryIndexCache();
+    this.clearSelection();
+    this._callbacks.onLevelChange?.(level);
+    this._requestPreview('Undo');
+    return level;
+  },
+
+  redo() {
+    const level = this.history.redo();
+    if (!level || !this.session) return null;
+    this.session.level = level;
+    this._invalidateEntryIndexCache();
+    this.clearSelection();
+    this._callbacks.onLevelChange?.(level);
+    this._requestPreview('Redo');
+    return level;
+  },
+
+  _snap(x, y) {
+    if (!this.snapEnabled) return { x: Math.round(x), y: Math.round(y) };
+    return { x: snapValue(x, this.gridSize), y: snapValue(y, this.gridSize) };
+  },
+
+  _findSelectionAt(x, y) {
+    const level = this.session?.level;
+    if (!level) return null;
+    const gadgetHit = findEntryAt(level.gadgets, this.assets?.gadgetById, x, y);
+    if (gadgetHit) return { type: 'gadget', ...gadgetHit };
+    const steelHit = findEntryAt(level.steel, null, x, y);
+    if (steelHit) return { type: 'steel', ...steelHit };
+    const terrainHit = findEntryAt(level.terrains, this.assets?.terrainById, x, y);
+    if (terrainHit) return { type: 'terrain', ...terrainHit };
+    return null;
+  },
+
+  _selectHit(hit, options = {}) {
+    if (!hit) {
+      if (!options.preserve) this.clearSelection();
+      return null;
+    }
+    if (options.toggle) {
+      this._toggleSelection(hit);
+      return hit;
+    }
+    if (options.additive) {
+      if (!this._isSelected(hit.type, hit.index)) {
+        this.selection = [...this.selection, {
+          type: hit.type,
+          index: hit.index,
+          uid: hit?.entry?.uid || null
+        }];
+        this._callbacks.onSelectionChange?.(this.getSelectedEntries());
+      }
+      return hit;
+    }
+    this._setSelection([hit]);
+    return hit;
+  },
+
+  _buildHandlePoints(bounds) {
+    const midX = bounds.x + Math.round(bounds.width / 2);
+    const midY = bounds.y + Math.round(bounds.height / 2);
+    return [
+      { id: 'nw', x: bounds.x, y: bounds.y },
+      { id: 'n', x: midX, y: bounds.y },
+      { id: 'ne', x: bounds.x + bounds.width, y: bounds.y },
+      { id: 'e', x: bounds.x + bounds.width, y: midY },
+      { id: 'se', x: bounds.x + bounds.width, y: bounds.y + bounds.height },
+      { id: 's', x: midX, y: bounds.y + bounds.height },
+      { id: 'sw', x: bounds.x, y: bounds.y + bounds.height },
+      { id: 'w', x: bounds.x, y: midY }
+    ];
+  },
+
+  _getResizeHandleAt(x, y) {
+    if (!this.canResizeSelection()) return null;
+    const bounds = this.getSelectionBounds();
+    if (!bounds) return null;
+    const half = Math.max(1, Math.floor(this.handleSize / 2));
+    for (const handle of this._buildHandlePoints(bounds)) {
+      if (x >= handle.x - half && x <= handle.x + half
+            && y >= handle.y - half && y <= handle.y + half) {
+        return handle.id;
+      }
+    }
+    return null;
+  },
+
+  _beginMarquee(x, y, additive) {
+    this._marquee = { startX: x, startY: y, x, y, additive: !!additive };
+    this._callbacks.onMarqueeChange?.(this.getMarqueeBounds());
+  },
+
+  _updateMarquee(x, y) {
+    if (!this._marquee) return;
+    this._marquee.x = x;
+    this._marquee.y = y;
+    this._callbacks.onMarqueeChange?.(this.getMarqueeBounds());
+  },
+
+  _clearMarquee() {
+    if (!this._marquee) return;
+    this._marquee = null;
+    this._callbacks.onMarqueeChange?.(null);
+  },
+
+  _applyMarqueeSelection() {
+    if (!this._marquee || !this.session?.level) return;
+    const bounds = this.getMarqueeBounds();
+    const next = this._marquee.additive ? [...this.selection] : [];
+    const addSelection = (type, index, uid = null) => {
+      if (next.some(entry => entry.type === type && entry.index === index)) return;
+      next.push({ type, index, uid });
+    };
+    const scan = (entries, metaById, type) => {
+      if (!Array.isArray(entries)) return;
+      for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        const meta = metaById?.get?.(entry?.props?.PIECE);
+        const entryBounds = getEntryBounds(entry, meta);
+        if (boundsIntersect(bounds, entryBounds)) addSelection(type, i, entry?.uid || null);
+      }
+    };
+    scan(this.session.level.terrains, this.assets?.terrainById, 'terrain');
+    scan(this.session.level.gadgets, this.assets?.gadgetById, 'gadget');
+    scan(this.session.level.steel, null, 'steel');
+    this._setSelection(next);
+  }
+};
+
+export { editorControllerPointerSelectionMethods };
diff --git a/js/editor/editor-controller/EditorControllerPointerTools.js b/js/editor/editor-controller/EditorControllerPointerTools.js
new file mode 100644
index 00000000..6c5919d2
--- /dev/null
+++ b/js/editor/editor-controller/EditorControllerPointerTools.js
@@ -0,0 +1,367 @@
+import {
+  MAX_ENTRANCES,
+  MAX_EXITS,
+  MAX_MIDI_FLAG_ID,
+  clampMidiFlagId,
+  clampSize,
+  coerceEntryNumber,
+  createGadgetEntry,
+  createSteelEntry,
+  createTerrainEntry,
+  findEntryAt,
+  isMidiFlagEnabled,
+  normalizeBounds,
+  removeEntryAt,
+  setEntryProp
+} from './EditorControllerShared.js';
+
+const editorControllerPointerToolMethods = {
+  _beginStroke() {
+    this._strokeChanged = false;
+    this._stampSet.clear();
+    this._lastBrushPos = null;
+  },
+
+  _removeGadgetsById(pieceId) {
+    if (!this.session?.level || !Number.isFinite(pieceId)) return;
+    const list = this.session.level.gadgets;
+    if (!Array.isArray(list)) return;
+    for (let i = list.length - 1; i >= 0; i--) {
+      const entry = list[i];
+      if (entry?.props?.PIECE === pieceId) {
+        list.splice(i, 1);
+        this._markChanged();
+      }
+    }
+  },
+
+  _hasGadgetId(pieceId) {
+    if (!this.session?.level || !Number.isFinite(pieceId)) return false;
+    const list = this.session.level.gadgets;
+    if (!Array.isArray(list)) return false;
+    return list.some(entry => entry?.props?.PIECE === pieceId);
+  },
+
+  _trimGadgetsById(pieceId, maxCount) {
+    if (!this.session?.level || !Number.isFinite(pieceId)) return;
+    const list = this.session.level.gadgets;
+    if (!Array.isArray(list)) return;
+    const indices = [];
+    for (let i = 0; i < list.length; i++) {
+      if (list[i]?.props?.PIECE === pieceId) indices.push(i);
+    }
+    const excess = indices.length - maxCount;
+    if (excess <= 0) return;
+    for (let i = 0; i < excess; i++) {
+      removeEntryAt(this.session.level, 'gadget', indices[i] - i);
+      this._markChanged();
+    }
+  },
+
+  _markChanged() {
+    this._strokeChanged = true;
+    this._invalidateEntryIndexCache();
+  },
+
+  _getTerrainMeta(id) {
+    const byId = this.assets?.terrainById?.get?.(id);
+    if (byId) return byId;
+    return this.assets?.terrain?.find?.(entry => entry?.id === id) || null;
+  },
+
+  _getGadgetMeta(id) {
+    const byId = this.assets?.gadgetById?.get?.(id);
+    if (byId) return byId;
+    return this.assets?.gadgets?.find?.(entry => entry?.id === id) || null;
+  },
+
+  _centerPlacement(x, y, meta) {
+    const width = Number(meta?.width || 0);
+    const height = Number(meta?.height || 0);
+    const offsetX = width > 0 ? Math.floor(width / 2) : 0;
+    const offsetY = height > 0 ? Math.floor(height / 2) : 0;
+    return {
+      x: x - offsetX,
+      y: y - offsetY
+    };
+  },
+
+  _commitHistory(label) {
+    this.history.pushSnapshot(this.session?.level, label);
+  },
+
+  beginHistoryTransaction(label = 'Batch') {
+    this.history?.beginTransaction?.(label);
+  },
+
+  endHistoryTransaction(label = '') {
+    return this.history?.endTransaction?.(label) || false;
+  },
+
+  runHistoryTransaction(label, callback) {
+    if (typeof callback !== 'function') return false;
+    const history = this.history;
+    const supportsTransactions = !!(
+      history
+        && typeof history.beginTransaction === 'function'
+        && typeof history.endTransaction === 'function'
+    );
+    if (!supportsTransactions) {
+      return callback();
+    }
+    history.beginTransaction(label);
+    try {
+      const result = callback();
+      history.endTransaction(label);
+      return result;
+    } catch (error) {
+      if (typeof history.cancelTransaction === 'function') {
+        history.cancelTransaction();
+      } else {
+        history.endTransaction(label);
+      }
+      throw error;
+    }
+  },
+
+  dispose() {
+    if (this._previewTimer) {
+      clearTimeout(this._previewTimer);
+      this._previewTimer = null;
+    }
+    this._callbacks = {
+      onSelectionChange: null,
+      onLevelChange: null,
+      onPreviewRequest: null,
+      onMarqueeChange: null
+    };
+    this._drag = null;
+    this._resize = null;
+    this._marquee = null;
+    this._steelDraft = null;
+    this._pointerDown = false;
+    this._stampSet.clear();
+  },
+
+  _requestPreview(label) {
+    if (this._previewTimer) return;
+    const callback = this._callbacks.onPreviewRequest;
+    if (!callback) return;
+    const nextLabel = label || 'Update';
+    this._previewTimer = setTimeout(() => {
+      this._previewTimer = null;
+      this._callbacks.onPreviewRequest?.(nextLabel);
+    }, this._previewDelay);
+  },
+
+  _placeTerrainAt(x, y) {
+    if (!this.session?.level) return null;
+    const meta = this._getTerrainMeta(this.selectedTerrainId);
+    const pos = this._centerPlacement(x, y, meta);
+    const entry = createTerrainEntry({
+      styleName: this.session.level.getHeader('STYLE'),
+      piece: this.selectedTerrainId,
+      x: pos.x,
+      y: pos.y
+    });
+    this.session.level.terrains.push(entry);
+    this._markChanged();
+    return entry;
+  },
+
+  _placeGadgetAt(x, y, pieceId) {
+    if (!this.session?.level) return null;
+    const meta = this._getGadgetMeta(pieceId);
+    const pos = this._centerPlacement(x, y, meta);
+    const entry = createGadgetEntry({
+      styleName: this.session.level.getHeader('STYLE'),
+      piece: pieceId,
+      x: pos.x,
+      y: pos.y
+    });
+    this.session.level.gadgets.push(entry);
+    this._markChanged();
+    return entry;
+  },
+
+  _nextMidiFlagId() {
+    const list = this.session?.level?.gadgets;
+    if (!Array.isArray(list) || !list.length) return 1;
+    const used = new Set();
+    for (const entry of list) {
+      if (!isMidiFlagEnabled(entry?.props?.MIDI_FLAG)) continue;
+      const id = clampMidiFlagId(Number(entry?.props?.MIDI_FLAG_ID));
+      if (id !== null) used.add(id);
+    }
+    for (let id = 1; id <= MAX_MIDI_FLAG_ID; id += 1) {
+      if (!used.has(id)) return id;
+    }
+    return MAX_MIDI_FLAG_ID;
+  },
+
+  _placeMidiFlagAt(x, y) {
+    if (!this.session?.level) return null;
+    const pieceId = Number.isFinite(this.selectedTriggerId)
+      ? this.selectedTriggerId
+      : this.selectedGadgetId;
+    if (!Number.isFinite(pieceId)) return null;
+    const entry = this._placeGadgetAt(x, y, pieceId);
+    if (!entry?.props) return null;
+    setEntryProp(entry, 'MIDI_FLAG', true, { removeIfFalse: true });
+    if (clampMidiFlagId(Number(entry.props.MIDI_FLAG_ID)) === null) {
+      setEntryProp(entry, 'MIDI_FLAG_ID', this._nextMidiFlagId(), { removeIfEmpty: false });
+    }
+    return entry;
+  },
+
+  ensureDefaultEntrancesExits(options = {}) {
+    if (!this.session?.level) return false;
+    const entranceId = Number.isFinite(options.entranceId)
+      ? options.entranceId
+      : this.assets?.entranceId;
+    const exitId = Number.isFinite(options.exitId)
+      ? options.exitId
+      : this.assets?.exitId;
+    const viewRect = options.viewRect || null;
+    const headerWidth = coerceEntryNumber(this.session.level.getHeader?.('WIDTH'), 0);
+    const headerHeight = coerceEntryNumber(this.session.level.getHeader?.('HEIGHT'), 0);
+    const levelWidth = Number.isFinite(headerWidth) && headerWidth > 0 ? headerWidth : 0;
+    const levelHeight = Number.isFinite(headerHeight) && headerHeight > 0 ? headerHeight : 0;
+    const hasEntrance = Number.isFinite(entranceId) && this._hasGadgetId(entranceId);
+    const hasExit = Number.isFinite(exitId) && this._hasGadgetId(exitId);
+    if (hasEntrance && hasExit) return false;
+
+    const clamp = (value, min, max) => Math.min(Math.max(value, min), max);
+    const baseX = viewRect ? viewRect.x : 0;
+    const baseY = viewRect ? viewRect.y : 0;
+    const viewW = viewRect ? viewRect.w : Math.min(levelWidth, 320);
+    const viewH = viewRect ? viewRect.h : Math.min(levelHeight, 160);
+    const targetY = clamp(baseY + viewH - 32, 0, Math.max(0, levelHeight - 1));
+
+    if (!hasEntrance && Number.isFinite(entranceId)) {
+      const meta = this._getGadgetMeta(entranceId);
+      const offset = Math.max(8, Math.floor((meta?.width || 16) / 2));
+      const x = clamp(baseX + offset, 0, Math.max(0, levelWidth - 1));
+      this._placeGadgetAt(x, targetY, entranceId);
+    }
+    if (!hasExit && Number.isFinite(exitId)) {
+      const meta = this._getGadgetMeta(exitId);
+      const offset = Math.max(8, Math.floor((meta?.width || 16) / 2));
+      const x = clamp(baseX + viewW - offset, 0, Math.max(0, levelWidth - 1));
+      this._placeGadgetAt(x, targetY, exitId);
+    }
+
+    this._commitHistory('Defaults');
+    this._requestPreview('Defaults');
+    return true;
+  },
+
+  _placeSteelAt(x, y, width, height) {
+    if (!this.session?.level) return null;
+    if (!Array.isArray(this.session.level.steel)) {
+      this.session.level.steel = [];
+    }
+    const entry = createSteelEntry({ x, y, width, height });
+    this.session.level.steel.push(entry);
+    this._markChanged();
+    return entry;
+  },
+
+  _beginSteelDraft(x, y) {
+    const size = Number.isFinite(this.gridSize) && this.gridSize > 0 ? this.gridSize : 1;
+    const entry = this._placeSteelAt(x, y, size, size);
+    if (!entry) return;
+    const list = this.session.level.steel;
+    const index = list.length - 1;
+    this._setSelection([{ type: 'steel', index }]);
+    this._steelDraft = { index, startX: x, startY: y };
+    this._requestPreview('Steel');
+  },
+
+  _updateSteelDraft(x, y) {
+    if (!this._steelDraft || !this.session?.level) return;
+    const list = this.session.level.steel;
+    const entry = Array.isArray(list) ? list[this._steelDraft.index] : null;
+    if (!entry) return;
+    const bounds = normalizeBounds(this._steelDraft.startX, this._steelDraft.startY, x, y);
+    setEntryProp(entry, 'X', bounds.x, { removeIfEmpty: false });
+    setEntryProp(entry, 'Y', bounds.y, { removeIfEmpty: false });
+    setEntryProp(entry, 'WIDTH', clampSize(bounds.width), { removeIfEmpty: false });
+    setEntryProp(entry, 'HEIGHT', clampSize(bounds.height), { removeIfEmpty: false });
+    this._markChanged();
+    this._callbacks.onSelectionChange?.(this.getSelectedEntries());
+    this._requestPreview('Steel');
+  },
+
+  _eraseAt(x, y) {
+    if (!this.session?.level) return;
+    const level = this.session.level;
+    const terrainHit = findEntryAt(level.terrains, this.assets?.terrainById, x, y);
+    if (terrainHit) {
+      removeEntryAt(level, 'terrain', terrainHit.index);
+      this._markChanged();
+    }
+    if (this.eraseGadgets) {
+      const gadgetHit = findEntryAt(level.gadgets, this.assets?.gadgetById, x, y);
+      if (gadgetHit) {
+        removeEntryAt(level, 'gadget', gadgetHit.index);
+        this._markChanged();
+      }
+    }
+  },
+
+  _getBrushStep() {
+    if (this.snapEnabled && Number.isFinite(this.gridSize) && this.gridSize > 0) {
+      return this.gridSize;
+    }
+    return 1;
+  },
+
+  _brushLine(start, end) {
+    if (!start || !end) return;
+    const step = Math.max(1, this._getBrushStep());
+    const dx = end.x - start.x;
+    const dy = end.y - start.y;
+    const distance = Math.hypot(dx, dy);
+    const segments = Math.max(1, Math.floor(distance / step));
+    for (let i = 0; i <= segments; i++) {
+      const t = i / segments;
+      const px = Math.round(start.x + dx * t);
+      const py = Math.round(start.y + dy * t);
+      this._brushAt(px, py);
+    }
+  },
+
+  _eraseLine(start, end) {
+    if (!start || !end) return;
+    const step = Math.max(1, this._getBrushStep());
+    const dx = end.x - start.x;
+    const dy = end.y - start.y;
+    const distance = Math.hypot(dx, dy);
+    const segments = Math.max(1, Math.floor(distance / step));
+    for (let i = 0; i <= segments; i++) {
+      const t = i / segments;
+      const px = Math.round(start.x + dx * t);
+      const py = Math.round(start.y + dy * t);
+      this._eraseAt(px, py);
+    }
+  },
+
+  _brushAt(x, y) {
+    const size = Math.max(1, this.brushSize);
+    const key = `${x},${y},${size}`;
+    if (this._stampSet.has(key)) return;
+    this._stampSet.add(key);
+    const half = Math.floor(size / 2);
+    const step = this._getBrushStep();
+    for (let by = -half; by <= half; by++) {
+      for (let bx = -half; bx <= half; bx++) {
+        const px = x + bx * step;
+        const py = y + by * step;
+        this._placeTerrainAt(px, py);
+      }
+    }
+  }
+};
+
+export { editorControllerPointerToolMethods };
diff --git a/js/editor/editor-controller/EditorControllerSelection.js b/js/editor/editor-controller/EditorControllerSelection.js
new file mode 100644
index 00000000..39c0cfa4
--- /dev/null
+++ b/js/editor/editor-controller/EditorControllerSelection.js
@@ -0,0 +1,278 @@
+import {
+  DEFAULT_GRID,
+  DEFAULT_HANDLE_SIZE,
+  EditorHistory,
+  EditorTools,
+  MAX_BRUSH_SIZE,
+  MAX_ENTRANCES,
+  MAX_EXITS,
+  MAX_MIDI_FLAG_ID,
+  MIDI_FLAG_TRIGGER_MAX,
+  __test__,
+  boundsIntersect,
+  clampBrushSize,
+  clampMidiFlagId,
+  clampSize,
+  cloneEntry,
+  coerceEntryNumber,
+  createGadgetEntry,
+  createSteelEntry,
+  createTerrainEntry,
+  ensureEntryUid,
+  findEntryAt,
+  getEntryBounds,
+  isMidiFlagEnabled,
+  normalizeBounds,
+  removeEntryAt,
+  selectionKey,
+  setEntryProp,
+  snapValue
+} from './EditorControllerShared.js';
+const editorControllerSelectionMethods = {
+  setCallbacks(callbacks = {}) {
+    this._callbacks = { ...this._callbacks, ...callbacks };
+  },
+
+  setAssets(assets) {
+    this.assets = assets || null;
+    const hasId = (list, id) => Array.isArray(list) && list.some(entry => entry?.id === id);
+    if (assets?.terrain?.length && !hasId(assets.terrain, this.selectedTerrainId)) {
+      this.selectedTerrainId = assets.terrain[0].id;
+    }
+    if (assets?.gadgets?.length && !hasId(assets.gadgets, this.selectedGadgetId)) {
+      this.selectedGadgetId = assets.gadgets[0].id;
+    }
+    if (assets?.triggers?.length && !hasId(assets.triggers, this.selectedTriggerId)) {
+      this.selectedTriggerId = assets.triggers[0].id;
+    }
+  },
+
+  resetHistory(label = 'Init') {
+    this.history.clear();
+    this.history.pushSnapshot(this.session?.level, label);
+  },
+
+  setTool(tool) {
+    if (!tool) return;
+    this.tool = tool;
+  },
+
+  setSnapEnabled(enabled) {
+    this.snapEnabled = !!enabled;
+  },
+
+  setBrushSize(size) {
+    const value = Number.isFinite(size) ? size : 1;
+    this.brushSize = clampBrushSize(value);
+  },
+
+  setEraseGadgets(enabled) {
+    this.eraseGadgets = !!enabled;
+  },
+
+  setSelectedTerrain(id) {
+    if (Number.isFinite(id)) this.selectedTerrainId = id;
+  },
+
+  setSelectedGadget(id) {
+    if (Number.isFinite(id)) this.selectedGadgetId = id;
+  },
+
+  setSelectedTrigger(id) {
+    if (Number.isFinite(id)) this.selectedTriggerId = id;
+  },
+
+  _getListForType(type) {
+    if (!this.session?.level) return null;
+    if (type === 'gadget') return this.session.level.gadgets;
+    if (type === 'steel') return this.session.level.steel;
+    return this.session.level.terrains;
+  },
+
+  _setSelectionState(list) {
+    const normalized = Array.isArray(list) ? list.map((entry) => ({
+      type: entry?.type,
+      index: entry?.index,
+      uid: entry?.uid || null
+    })) : [];
+    this._selection = normalized;
+    this._selectionSet.clear();
+    for (const entry of normalized) {
+      if (!entry || !entry.type || !Number.isFinite(entry.index)) continue;
+      this._selectionSet.add(selectionKey(entry.type, entry.index));
+    }
+  },
+
+  _invalidateEntryIndexCache(type = null) {
+    if (type) {
+      const cache = this._entryIndexCache[type];
+      if (!cache) return;
+      cache.list = null;
+      cache.size = -1;
+      cache.map.clear();
+      return;
+    }
+    for (const cache of Object.values(this._entryIndexCache)) {
+      cache.list = null;
+      cache.size = -1;
+      cache.map.clear();
+    }
+  },
+
+  _getEntryIndexByUid(type, uid, list) {
+    if (!uid || !Array.isArray(list)) return -1;
+    const cache = this._entryIndexCache[type];
+    if (!cache) return -1;
+    if (cache.list !== list || cache.size !== list.length) {
+      cache.list = list;
+      cache.size = list.length;
+      cache.map = new Map();
+      for (let index = 0; index < list.length; index += 1) {
+        const entryUid = list[index]?.uid;
+        if (entryUid) {
+          cache.map.set(entryUid, index);
+        }
+      }
+    }
+    return cache.map.get(uid) ?? -1;
+  },
+
+  _resolveSelectionEntry(selected) {
+    const list = this._getListForType(selected?.type);
+    if (!Array.isArray(list)) return null;
+    const currentIndex = Number.isFinite(selected?.index) ? selected.index : -1;
+    const currentEntry = currentIndex >= 0 ? list[currentIndex] : null;
+    if (currentEntry && (!selected.uid || selected.uid === currentEntry.uid)) {
+      if (!selected.uid && currentEntry.uid) {
+        selected.uid = currentEntry.uid;
+      }
+      return { index: currentIndex, entry: currentEntry };
+    }
+    if (selected?.uid) {
+      const nextIndex = this._getEntryIndexByUid(selected.type, selected.uid, list);
+      if (nextIndex >= 0) {
+        const nextEntry = list[nextIndex];
+        if (nextEntry) {
+          if (currentIndex !== nextIndex && Number.isFinite(currentIndex)) {
+            this._selectionSet.delete(selectionKey(selected.type, currentIndex));
+            this._selectionSet.add(selectionKey(selected.type, nextIndex));
+          }
+          selected.index = nextIndex;
+          return { index: nextIndex, entry: nextEntry };
+        }
+      }
+    }
+    if (currentEntry?.uid) {
+      selected.uid = currentEntry.uid;
+      return { index: currentIndex, entry: currentEntry };
+    }
+    return null;
+  },
+
+  getSelectedEntries() {
+    if (!this.session?.level || !Array.isArray(this.selection)) return [];
+    const results = [];
+    for (const selected of this.selection) {
+      const resolved = this._resolveSelectionEntry(selected);
+      if (!resolved?.entry) continue;
+      results.push({
+        type: selected.type,
+        index: resolved.index,
+        uid: selected.uid || resolved.entry.uid || null,
+        entry: resolved.entry
+      });
+    }
+    return results;
+  },
+
+  getSelectedEntry() {
+    const entries = this.getSelectedEntries();
+    if (entries.length !== 1) return null;
+    return entries[0];
+  },
+
+  getSelectionBounds() {
+    const selected = this.getSelectedEntry();
+    if (!selected) return null;
+    if (selected.type === 'steel') {
+      return getEntryBounds(selected.entry, null);
+    }
+    const meta = selected.type === 'gadget'
+      ? this.assets?.gadgetById?.get?.(selected.entry?.props?.PIECE)
+      : this.assets?.terrainById?.get?.(selected.entry?.props?.PIECE);
+    return getEntryBounds(selected.entry, meta);
+  },
+
+  getMarqueeBounds() {
+    if (!this._marquee) return null;
+    return normalizeBounds(
+      this._marquee.startX,
+      this._marquee.startY,
+      this._marquee.x,
+      this._marquee.y
+    );
+  },
+
+  getHandleSize() {
+    return this.handleSize;
+  },
+
+  canResizeSelection() {
+    if (!Array.isArray(this.selection) || this.selection.length !== 1) return false;
+    return this.selection[0].type === 'steel';
+  },
+
+  clearSelection() {
+    this.selection = [];
+    this._callbacks.onSelectionChange?.(this.getSelectedEntries());
+  },
+
+  _setSelection(list) {
+    this.selection = Array.isArray(list) ? list.map(entry => ({
+      type: entry.type,
+      index: entry.index,
+      uid: entry?.uid || entry?.entry?.uid || this._getListForType(entry.type)?.[entry.index]?.uid || null
+    })) : [];
+    this._callbacks.onSelectionChange?.(this.getSelectedEntries());
+  },
+
+  _isSelected(type, index) {
+    return this._selectionSet.has(selectionKey(type, index));
+  },
+
+  _toggleSelection(hit) {
+    if (!hit) return;
+    if (this._isSelected(hit.type, hit.index)) {
+      this.selection = this.selection.filter(entry => !(entry.type === hit.type && entry.index === hit.index));
+    } else {
+      this.selection = [...this.selection, {
+        type: hit.type,
+        index: hit.index,
+        uid: hit?.entry?.uid || null
+      }];
+    }
+    this._callbacks.onSelectionChange?.(this.getSelectedEntries());
+  },
+
+  updateHeader(key, value) {
+    if (!this.session?.level) return;
+    this.session.level.setHeader(key, value);
+    this._callbacks.onLevelChange?.(this.session.level);
+    this._requestPreview('Header');
+  },
+
+  updateSelectedProps(patch = {}) {
+    const entries = this.getSelectedEntries();
+    if (entries.length === 0) return false;
+    for (const selected of entries) {
+      for (const [key, value] of Object.entries(patch)) {
+        const removeIfFalse = typeof value === 'boolean';
+        setEntryProp(selected.entry, key, value, { removeIfFalse });
+      }
+    }
+    this._callbacks.onSelectionChange?.(this.getSelectedEntries());
+    this._requestPreview('Edit');
+    return true;
+  }
+};
+export { editorControllerSelectionMethods };
\ No newline at end of file
diff --git a/js/editor/editor-controller/EditorControllerShared.js b/js/editor/editor-controller/EditorControllerShared.js
new file mode 100644
index 00000000..c506a038
--- /dev/null
+++ b/js/editor/editor-controller/EditorControllerShared.js
@@ -0,0 +1,97 @@
+import { EditorTools } from '../EditorTools.js';
+import { EditorHistory } from '../EditorHistory.js';
+import {
+  createTerrainEntry,
+  createGadgetEntry,
+  createSteelEntry,
+  ensureEntryUid,
+  setEntryProp,
+  removeEntryAt
+} from '../EditorEntryFactory.js';
+import { findEntryAt, getEntryBounds } from '../EditorHitTest.js';
+import { MIDI_FLAG_TRIGGER_MAX, clampMidiFlagId } from '../../midi/MidiFlagTriggers.js';
+
+const DEFAULT_GRID = 4;
+const MAX_ENTRANCES = 4;
+const MAX_EXITS = 4;
+const DEFAULT_HANDLE_SIZE = 2;
+const MAX_BRUSH_SIZE = 64;
+const MAX_MIDI_FLAG_ID = MIDI_FLAG_TRIGGER_MAX;
+const snapValue = (value, gridSize) => {
+  if (!Number.isFinite(gridSize) || gridSize <= 1) return Math.round(value);
+  return Math.round(value / gridSize) * gridSize;
+};
+const clampSize = (value) => Math.max(1, Math.round(value));
+const clampBrushSize = (value) => Math.min(MAX_BRUSH_SIZE, clampSize(value));
+const selectionKey = (type, index) => `${type}:${index}`;
+const isMidiFlagEnabled = (value) => value === true || value === 1 || value === '1';
+const cloneEntry = (entry, options = {}) => {
+  const props = entry?.props ? { ...entry.props } : {};
+  const order = Array.isArray(entry?.order) ? entry.order.slice() : Object.keys(props);
+  const unknownLines = Array.isArray(entry?.unknownLines) ? entry.unknownLines.slice() : [];
+  const clone = { props, order, unknownLines };
+  if (options.preserveUid && entry?.uid) {
+    clone.uid = entry.uid;
+  } else if (options.assignUid !== false) {
+    ensureEntryUid(clone, options.prefix || 'e');
+  }
+  return clone;
+};
+const coerceEntryNumber = (value, fallback = 0) => {
+  return Number.isFinite(value) ? value : fallback;
+};
+const normalizeBounds = (x1, y1, x2, y2) => {
+  const left = Math.min(x1, x2);
+  const right = Math.max(x1, x2);
+  const top = Math.min(y1, y2);
+  const bottom = Math.max(y1, y2);
+  return {
+    x: left,
+    y: top,
+    width: Math.max(1, right - left),
+    height: Math.max(1, bottom - top)
+  };
+};
+const boundsIntersect = (a, b) => {
+  if (!a || !b) return false;
+  return a.x <= b.x + b.width
+    && a.x + a.width >= b.x
+    && a.y <= b.y + b.height
+    && a.y + a.height >= b.y;
+};
+const __test__ = {
+  cloneEntry,
+  normalizeBounds,
+  boundsIntersect
+};
+
+export {
+  DEFAULT_GRID,
+  DEFAULT_HANDLE_SIZE,
+  EditorHistory,
+  EditorTools,
+  MAX_BRUSH_SIZE,
+  MAX_ENTRANCES,
+  MAX_EXITS,
+  MAX_MIDI_FLAG_ID,
+  MIDI_FLAG_TRIGGER_MAX,
+  __test__,
+  boundsIntersect,
+  clampBrushSize,
+  clampMidiFlagId,
+  clampSize,
+  cloneEntry,
+  coerceEntryNumber,
+  createGadgetEntry,
+  createSteelEntry,
+  createTerrainEntry,
+  ensureEntryUid,
+  findEntryAt,
+  getEntryBounds,
+  isMidiFlagEnabled,
+  normalizeBounds,
+  removeEntryAt,
+  selectionKey,
+  setEntryProp,
+  snapValue
+};
diff --git a/js/game/Game.js b/js/game/Game.js
index 0a3dd6bc..c37de644 100644
--- a/js/game/Game.js
+++ b/js/game/Game.js
@@ -15,7 +15,35 @@ import { ObjectManager } from '../level/ObjectManager.js';
 import { ParticleTable } from '../render/ParticleTable.js';
 import { SoundEventBus, SoundEventTypes, SoundEffectIds } from './SoundEvents.js';
 import { TriggerManager } from '../level/TriggerManager.js';
-import { getDependency } from '../core/dependencies.js';
+import { getAppContext, getDependency } from '../core/dependencies.js';
+import { createGameRuntime } from './GameRuntime.js';
+import {
+  canMeasurePerformance,
+  recordPerformanceMeasure
+} from '../util/performanceInstrumentation.js';
+
+const RUN_LOGIC_MEASURE_DETAIL = Object.freeze({
+  track: 'Game',
+  trackGroup: 'Game State',
+  color: 'secondary',
+  tooltipText: 'runGameLogic'
+});
+
+const GAME_OVER_MEASURE_DETAIL = Object.freeze({
+  track: 'Game',
+  trackGroup: 'Game State',
+  color: 'tertiary',
+  tooltipText: 'checkForGameOver'
+});
+
+const RENDER_MEASURE_DETAIL = Object.freeze({
+  track: 'Game',
+  trackGroup: 'Render',
+  color: 'primary-dark',
+  tooltipText: 'render'
+});
+
+const getApp = () => getAppContext();
 
 class Game extends BaseLogger {
   constructor (gameResources) {
@@ -39,6 +67,7 @@ class Game extends BaseLogger {
     this.soundEvents          = null;
     this.history              = null;
     this.timeTravel           = null;
+    this.runtime              = null;
     this.inputEnabled         = true;
 
     this.onGameEnd      = new EventHandler();
@@ -84,6 +113,7 @@ class Game extends BaseLogger {
     this.soundEvents     = null;
     this.history         = null;
     this.timeTravel      = null;
+    this.runtime         = null;
 
     this.finalGameState  = GameStateTypes.UNKNOWN;
   }
@@ -95,10 +125,13 @@ class Game extends BaseLogger {
       color: 'primary',
       tooltipText: `loadLevel ${levelGroupIndex}:${levelIndex}`
     });
-    const level = await this.gameResources.getLevel(levelGroupIndex, levelIndex);
-    await this._initLevel(level, { levelGroupIndex, levelIndex });
-    endMeasure();
-    return this; // keeps legacy promise signature intact
+    try {
+      const level = await this.gameResources.getLevel(levelGroupIndex, levelIndex);
+      await this._initLevel(level, { levelGroupIndex, levelIndex });
+      return this;
+    } finally {
+      endMeasure();
+    }
   }
 
   async loadCustomLevel(level, options = {}) {
@@ -131,6 +164,8 @@ class Game extends BaseLogger {
     const TimeTravel = getDependency('TimeTravelController', TimeTravelController);
     this.timeTravel = new TimeTravel(this, this.history);
     this.gameTimer?.setTimeTravelController?.(this.timeTravel);
+    this.runtime = createGameRuntime(this, getApp());
+    level.setRuntime?.(this.runtime);
 
     const CommandMgr = getDependency('CommandManager', CommandManager);
     const Skills = getDependency('GameSkills', GameSkills);
@@ -139,7 +174,7 @@ class Game extends BaseLogger {
     this.commandManager       = new CommandMgr(this, this.gameTimer);
     this.skills               = new Skills(level);
     this.gameVictoryCondition = new Victory(level);
-    this.triggerManager       = new Triggers(this.gameTimer);
+    this.triggerManager       = new Triggers(this.gameTimer, level.width, level.height, 16, this.runtime);
     this.triggerManager.addRange(level.triggers);
 
     const [masks, lemSprite] = await Promise.all([
@@ -157,6 +192,7 @@ class Game extends BaseLogger {
       this.gameVictoryCondition,
       masks,
       particleTable,
+      this.runtime
     );
 
     const skillPanelSprites = await this.gameResources.getSkillPanelSprite(level.colorPalette);
@@ -231,26 +267,33 @@ class Game extends BaseLogger {
   }
 
   runGameLogic () {
-    const endMeasure = this.startMeasure('Game runGameLogic', {
-      track: 'Game',
-      trackGroup: 'Game State',
-      color: 'secondary',
-      tooltipText: 'runGameLogic'
-    });
-    if (!this.level) {
-      this.log.log('level not loaded!');
-      endMeasure();
-      return;
+    const app = getApp();
+    const perfEnabled = !!app &&
+      (app.performanceAPI === true || app.perfMetrics === true) &&
+      canMeasurePerformance();
+    const perfStart = perfEnabled ? performance.now() : 0;
+    try {
+      if (!this.level) {
+        this.log.log('level not loaded!');
+        return;
+      }
+      this.lemmingManager.tick();
+    } finally {
+      if (perfEnabled) {
+        recordPerformanceMeasure('Game runGameLogic', {
+          start: perfStart,
+          detail: { devtools: RUN_LOGIC_MEASURE_DETAIL }
+        });
+      }
     }
-    this.lemmingManager.tick();
-    endMeasure();
   }
 
   getGameState () {
-    if (typeof lemmings !== 'undefined' && (lemmings.bench || lemmings.bench2 || lemmings.benchReverse)) {
+    const app = getApp();
+    if (app?.bench || app?.bench2 || app?.benchReverse) {
       return GameStateTypes.RUNNING;
     }
-    if (typeof lemmings !== 'undefined' && lemmings.endless) {
+    if (app?.endless) {
       return GameStateTypes.RUNNING;
     }
     if (this.finalGameState !== GameStateTypes.UNKNOWN) {
@@ -267,7 +310,7 @@ class Game extends BaseLogger {
       return won ? GameStateTypes.SUCCEEDED
         : GameStateTypes.FAILED_LESS_LEMMINGS;
     }
-    if (!lemmings?.endless && this.gameTimer?.getGameLeftTime() <= 0) {
+    if (!app?.endless && this.gameTimer?.getGameLeftTime() <= 0) {
       return won ? GameStateTypes.SUCCEEDED
         : GameStateTypes.FAILED_OUT_OF_TIME;
     }
@@ -275,50 +318,67 @@ class Game extends BaseLogger {
   }
 
   checkForGameOver () {
-    const endMeasure = this.startMeasure('Game checkForGameOver', {
-      track: 'Game',
-      trackGroup: 'Game State',
-      color: 'tertiary',
-      tooltipText: 'checkForGameOver'
-    });
-    if (typeof lemmings !== 'undefined' && (lemmings.bench || lemmings.bench2 || lemmings.benchReverse)) {
-      endMeasure();
-      return;
-    }
-    if (this.finalGameState !== GameStateTypes.UNKNOWN) {
-      endMeasure();
-      return;
-    }
-
-    const state = this.getGameState();
-    if (state !== GameStateTypes.RUNNING &&
-        state !== GameStateTypes.UNKNOWN) {
-      this.gameVictoryCondition.doFinalize();
-      this.finalGameState = state;
-      const Result = getDependency('GameResult', GameResult);
-      this.onGameEnd?.trigger(new Result(this));
+    const app = getApp();
+    const perfEnabled = !!app &&
+      (app.performanceAPI === true || app.perfMetrics === true) &&
+      canMeasurePerformance();
+    const perfStart = perfEnabled ? performance.now() : 0;
+    try {
+      if (app?.bench || app?.bench2 || app?.benchReverse) {
+        return;
+      }
+      if (this.finalGameState !== GameStateTypes.UNKNOWN) {
+        return;
+      }
+
+      const state = this.getGameState();
+      if (state !== GameStateTypes.RUNNING &&
+          state !== GameStateTypes.UNKNOWN) {
+        this.gameVictoryCondition.doFinalize();
+        this.finalGameState = state;
+        const Result = getDependency('GameResult', GameResult);
+        this.onGameEnd?.trigger(new Result(this));
+      }
+    } finally {
+      if (perfEnabled) {
+        recordPerformanceMeasure('Game checkForGameOver', {
+          start: perfStart,
+          detail: { devtools: GAME_OVER_MEASURE_DETAIL }
+        });
+      }
     }
-    endMeasure();
   }
 
   render () {
-    const endMeasure = this.startMeasure('Game render', {
-      track: 'Game',
-      trackGroup: 'Render',
-      color: 'primary-dark',
-      tooltipText: 'render'
-    });
-    if (this.gameDisplay) {
-      this.gameDisplay.render();
-      if (this.showDebug) this.gameDisplay.renderDebug();
-    }
-    if (this.guiDisplay) {
-      this.gameGui.render();
-      this.guiDisplay.redraw();
-    } else if (this.display) {
-      this.display.redraw();
+    const app = getApp();
+    const perfEnabled = !!app &&
+      (app.performanceAPI === true || app.perfMetrics === true) &&
+      canMeasurePerformance();
+    const perfStart = perfEnabled ? performance.now() : 0;
+    try {
+      if (this.gameDisplay) {
+        this.gameDisplay.render();
+        if (this.showDebug) this.gameDisplay.renderDebug();
+        this.display?.commitFrameForBackgroundRestore?.();
+      }
+      if (this.guiDisplay) {
+        const guiDirty = this.gameGui.render();
+        if (guiDirty) {
+          this.guiDisplay.redraw();
+        } else if (this.display?.hasPendingDirty?.()) {
+          this.display.redraw();
+        }
+      } else if (this.display) {
+        this.display.redraw();
+      }
+    } finally {
+      if (perfEnabled) {
+        recordPerformanceMeasure('Game render', {
+          start: perfStart,
+          detail: { devtools: RENDER_MEASURE_DETAIL }
+        });
+      }
     }
-    endMeasure();
   }
 }
 export { Game };
diff --git a/js/game/GameDisplay.js b/js/game/GameDisplay.js
index d7858e29..79bc404c 100644
--- a/js/game/GameDisplay.js
+++ b/js/game/GameDisplay.js
@@ -4,8 +4,32 @@ import { ActionBlockerSystem } from '../actions/ActionBlockerSystem.js';
 import { ActionDiggSystem } from '../actions/ActionDiggSystem.js';
 import { ActionMineSystem } from '../actions/ActionMineSystem.js';
 import { SkillTypes } from './SkillTypes.js';
-import { getDependency } from '../core/dependencies.js';
-import { withPerformance } from '../util/LogHandler.js';
+import { LemmingStateType } from '../lemmings/LemmingStateType.js';
+import { getAppContext, getDependency } from '../core/dependencies.js';
+import {
+  canMeasurePerformance,
+  recordPerformanceMeasure
+} from '../util/performanceInstrumentation.js';
+
+const RENDER_MEASURE_DETAIL = Object.freeze({
+  devtools: Object.freeze({
+    track: 'GameDisplay',
+    trackGroup: 'Render',
+    color: 'primary',
+    tooltipText: 'render'
+  })
+});
+
+const RENDER_DEBUG_MEASURE_DETAIL = Object.freeze({
+  devtools: Object.freeze({
+    track: 'GameDisplay',
+    trackGroup: 'Render',
+    color: 'secondary',
+    tooltipText: 'renderDebug'
+  })
+});
+
+const LEMMING_HIGHLIGHT_SIZE = Object.freeze({ width: 10, height: 13 });
 
 class GameDisplay {
   constructor(game, level, lemmingManager, objectManager, triggerManager) {
@@ -25,6 +49,7 @@ class GameDisplay {
     this._dashOffset = 0;
     this.hoverIndex = -1;
     this.hoverLemming = null;
+    this._overlayHadContent = false;
     this._redundantActions = {
       [SkillTypes.BASHER]: getDependency('ActionBashSystem', ActionBashSystem),
       [SkillTypes.BLOCKER]: getDependency('ActionBlockerSystem', ActionBlockerSystem),
@@ -32,6 +57,16 @@ class GameDisplay {
       [SkillTypes.MINER]: getDependency('ActionMineSystem', ActionMineSystem)
     };
   }
+  _detachGuiListeners() {
+    if (this.display && this._mouseHandler) {
+      this.display.onMouseDown?.off?.(this._mouseHandler);
+      this._mouseHandler = null;
+    }
+    if (this.display && this._mouseMoveHandler) {
+      this.display.onMouseMove?.off?.(this._mouseMoveHandler);
+      this._mouseMoveHandler = null;
+    }
+  }
   _scheduleHoverUpdate() {
     if (this._hoverRafId) return;
     const raf = (typeof window !== 'undefined' && window.requestAnimationFrame)
@@ -53,7 +88,15 @@ class GameDisplay {
     if (!cand) {
       cand = this.lemmingManager.getNearestLemming(x, y);
     }
-    if (cand?.action?.getActionName?.() === 'exploding') cand = null;
+    const exploding =
+      !!cand && (
+        cand.state === LemmingStateType.EXPLODING ||
+        cand.action === this.lemmingManager?.actions?.[LemmingStateType.EXPLODING] ||
+        cand?.action?.getActionName?.() === 'exploding'
+      );
+    if (exploding) {
+      cand = null;
+    }
     if (prev !== cand && this.game?.gameGui) {
       this.hoverLemming = cand;
       this.game.gameGui.backgroundChanged = true;
@@ -63,7 +106,12 @@ class GameDisplay {
     }
   }
   setGuiDisplay(display) {
-    this.display = display;
+    if (display === this.display && this._mouseHandler && this._mouseMoveHandler) return;
+    this._detachGuiListeners();
+    this.display = display || null;
+    if (!this.display?.onMouseDown?.on || !this.display?.onMouseMove?.on) {
+      return;
+    }
     this._mouseHandler = (e) => {
       if (this.game?.inputEnabled === false) return;
       const lem = this.lemmingManager.getNearestLemming(e.x, e.y);
@@ -83,61 +131,95 @@ class GameDisplay {
     this.display.onMouseMove.on(this._mouseMoveHandler);
   }
   render() {
-    return withPerformance(
-      'GameDisplay render',
-      {
-        track: 'GameDisplay',
-        trackGroup: 'Render',
-        color: 'primary',
-        tooltipText: 'render'
-      },
-      () => {
-        if (this.display == null)
-          return;
-        this.level.render(this.display);
-        this.objectManager.render(this.display);
-        this.lemmingManager.render(this.display);
-        if (!this.game.showDebug) {
-          const sel = this.lemmingManager.getSelectedLemming();
-          if (sel && !sel.removed) this.#drawSelection(sel);
-
-          if (this.hoverLemming && !this.hoverLemming.removed) {
-            this.#drawHover(this.hoverLemming);
-          }
+    const app = getAppContext();
+    const perfEnabled = !!app &&
+      (app.performanceAPI === true || app.perfMetrics === true) &&
+      canMeasurePerformance();
+    const perfStart = perfEnabled ? performance.now() : 0;
+    try {
+      if (this.display === null)
+        return;
+      this.level.render(this.display);
+      this.objectManager.render(this.display);
+      this.lemmingManager.render(this.display);
+      let hasOverlay = false;
+      let selected = null;
+      let hover = null;
+      if (!this.game.showDebug) {
+        selected = this.lemmingManager.getSelectedLemming();
+        hover = this.hoverLemming;
+        hasOverlay = !!((selected && !selected.removed) || (hover && !hover.removed));
+      }
+      const needsOverlayLayer = hasOverlay || this._overlayHadContent;
+      const overlayDisplay = needsOverlayLayer ? this._getGameOverlayDisplay() : null;
+      const targetDisplay = overlayDisplay || this.display;
+      if (overlayDisplay && needsOverlayLayer) {
+        overlayDisplay.clear(0x00000000);
+      }
+      if (!this.game.showDebug) {
+        if (selected && !selected.removed) {
+          this.#drawSelection(selected, targetDisplay);
+        }
+        if (hover && !hover.removed) {
+          this.#drawHover(hover, targetDisplay);
         }
       }
-    ).call(this);
+      if (overlayDisplay) {
+        this._overlayHadContent = hasOverlay;
+        this.display?.stage?.setGameOverlayVisible?.(hasOverlay);
+      }
+    } finally {
+      if (perfEnabled) {
+        recordPerformanceMeasure('GameDisplay render', {
+          start: perfStart,
+          detail: RENDER_MEASURE_DETAIL
+        });
+      }
+    }
   }
   renderDebug() {
-    return withPerformance(
-      'GameDisplay renderDebug',
-      {
-        track: 'GameDisplay',
-        trackGroup: 'Render',
-        color: 'secondary',
-        tooltipText: 'renderDebug'
-      },
-      () => {
-        if (this.display == null)
-          return;
-        this.level.renderDebug(this.display);
-        this.lemmingManager.renderDebug(this.display);
-        this.triggerManager.renderDebug(this.display);
-        if (this.hoverLemming) {
-          const x = this.hoverLemming.x - 5;
-          const y = this.hoverLemming.y - 11;
-          this.display.drawDashedRect(x, y, 10, 13, 3, this._dashOffset);
-          this._dashOffset = (this._dashOffset + 1) % 6;
-        }
+    const app = getAppContext();
+    const perfEnabled = !!app &&
+      (app.performanceAPI === true || app.perfMetrics === true) &&
+      canMeasurePerformance();
+    const perfStart = perfEnabled ? performance.now() : 0;
+    try {
+      if (this.display === null)
+        return;
+      this.level.renderDebug(this.display);
+      this.lemmingManager.renderDebug(this.display);
+      this.triggerManager.renderDebug(this.display);
+      const hasOverlay = !!this.hoverLemming;
+      const needsOverlayLayer = hasOverlay || this._overlayHadContent;
+      const overlayDisplay = needsOverlayLayer ? this._getGameOverlayDisplay() : null;
+      const targetDisplay = overlayDisplay || this.display;
+      if (overlayDisplay && needsOverlayLayer) {
+        overlayDisplay.clear(0x00000000);
+      }
+      if (this.hoverLemming) {
+        const x = this.hoverLemming.x - 5;
+        const y = this.hoverLemming.y - 11;
+        targetDisplay.drawDashedRect(x, y, 10, 13, 3, this._dashOffset);
+        this._dashOffset = (this._dashOffset + 1) % 6;
+      }
+      if (overlayDisplay) {
+        this._overlayHadContent = hasOverlay;
+        this.display?.stage?.setGameOverlayVisible?.(hasOverlay);
       }
-    ).call(this);
+    } finally {
+      if (perfEnabled) {
+        recordPerformanceMeasure('GameDisplay renderDebug', {
+          start: perfStart,
+          detail: RENDER_DEBUG_MEASURE_DETAIL
+        });
+      }
+    }
   }
-
   #drawCorner(x, y, r, g, b) {
     this.display.drawRect(x, y, 2, 2, r, g, b, true);
   }
 
-  #drawSelection(lem) {
+  #drawSelection(lem, target = this.display) {
     const x = lem.x - 5;
     const y = lem.y - 11; // sits a bit higher
 
@@ -151,10 +233,10 @@ class GameDisplay {
       }
     }
 
-    this.display.drawCornerRect(
+    target.drawCornerRect(
       x,
       y,
-      { width: 10, height: 13 },
+      LEMMING_HIGHLIGHT_SIZE,
       color & 0xff,
       (color >> 8) & 0xff,
       (color >> 16) & 0xff,
@@ -162,12 +244,19 @@ class GameDisplay {
     );
   }
 
-  #drawHover(lem) {
+  #drawHover(lem, target = this.display) {
     const x = lem.x - 5;
     const y = lem.y - 11; // sits a bit higher
     const color = 0x5e5e5e; // slightly lighter grey
 
-    this.display.drawCornerRect(x, y, { width: 10, height: 13 }, color & 0xff, (color >> 8) & 0xff, (color >> 16) & 0xff);
+    target.drawCornerRect(
+      x,
+      y,
+      LEMMING_HIGHLIGHT_SIZE,
+      color & 0xff,
+      (color >> 8) & 0xff,
+      (color >> 16) & 0xff
+    );
   }
 
   static __test__ = {
@@ -176,19 +265,17 @@ class GameDisplay {
     }
   };
 
+  _getGameOverlayDisplay() {
+    return this.display?.stage?.getGameOverlayDisplay?.() || null;
+  }
+
   dispose() {
-    if (this.display && this._mouseHandler) {
-      this.display.onMouseDown.off(this._mouseHandler);
-      this._mouseHandler = null;
-    }
-    if (this.display && this._mouseMoveHandler) {
-      this.display.onMouseMove.off(this._mouseMoveHandler);
-      this._mouseMoveHandler = null;
-    }
+    this._detachGuiListeners();
     if (this._hoverRafId && typeof window !== 'undefined' && window.cancelAnimationFrame) {
       window.cancelAnimationFrame(this._hoverRafId);
       this._hoverRafId = 0;
     }
+    this.display?.stage?.setGameOverlayVisible?.(false);
     this.display = null;
     this.game = null;
     this.level = null;
@@ -197,6 +284,7 @@ class GameDisplay {
     this.triggerManager = null;
     this.hoverIndex = -1;
     this.hoverLemming = null;
+    this._overlayHadContent = false;
   }
 }
 
diff --git a/js/game/GameFactory.js b/js/game/GameFactory.js
index 8fbea974..c7046701 100644
--- a/js/game/GameFactory.js
+++ b/js/game/GameFactory.js
@@ -2,29 +2,58 @@ import { ConfigReader } from '../data/ConfigReader.js';
 import { FileProvider } from '../data/FileProvider.js';
 import { Game } from './Game.js';
 import { GameResources } from './GameResources.js';
-import { getDependency } from '../core/dependencies.js';
+import { getDependency, getAppContext, getRuntimeDependency } from '../core/dependencies.js';
+import { resolveRuntimeRevision } from '../core/cacheBust.js';
+import { getRuntimeProfilePreset } from '../core/runtimeProfiles.js';
+
+const getApp = () => {
+  const app = getAppContext();
+  if (app) return app;
+  return null;
+};
+
+const getPerformanceApi = () => getRuntimeDependency(
+  'performance',
+  (typeof performance !== 'undefined' ? performance : null)
+);
+
+const resolvePerfInstrumentation = (app) => {
+  const preset = getRuntimeProfilePreset(app?.startupProfile);
+  const instrumentation = preset.instrumentation || {};
+  const usePerformanceApi = (app?.performanceAPI ?? instrumentation.performanceAPI) === true;
+  const usePerfMetrics = (app?.perfMetrics ?? instrumentation.perfMetrics) === true;
+  const perfApi = getPerformanceApi();
+  const enabled = (usePerformanceApi || usePerfMetrics) &&
+    typeof perfApi?.measure === 'function' &&
+    typeof perfApi?.now === 'function';
+  return {
+    enabled: !!enabled,
+    perfApi
+  };
+};
 
 class GameFactory {
-  constructor(rootPath) {
+  constructor(rootPath, options = {}) {
     this.rootPath = rootPath;
+    this.runtimeRevision = resolveRuntimeRevision(options);
     const Provider = getDependency('FileProvider', FileProvider);
-    this.fileProvider = new Provider(rootPath);
+    this.fileProvider = new Provider(rootPath, {
+      cacheBustRevision: this.runtimeRevision
+    });
     let configFileReader = this.fileProvider.loadString('config.json');
     const Reader = getDependency('ConfigReader', ConfigReader);
     this.configReader = new Reader(configFileReader);
   }
   /** return a game object to control/run the game */
   async getGame(gameType, gameResources = null) {
-    const perfEnabled = typeof lemmings !== 'undefined' &&
-      (lemmings.performanceAPI === true || lemmings.perfMetrics === true) &&
-      typeof performance !== 'undefined' &&
-      typeof performance.measure === 'function' &&
-      typeof performance.now === 'function';
-    const perfStart = perfEnabled ? performance.now() : 0;
+    const app = getApp();
+    const perfInstrumentation = resolvePerfInstrumentation(app);
+    const perfEnabled = perfInstrumentation.enabled;
+    const perfStart = perfEnabled ? perfInstrumentation.perfApi.now() : 0;
     const finish = () => {
       if (!perfEnabled) return;
       try {
-        performance.measure('GameFactory getGame', {
+        perfInstrumentation.perfApi.measure('GameFactory getGame', {
           start: perfStart,
           detail: { devtools: { track: 'GameFactory', trackGroup: 'Load', color: 'primary', tooltipText: 'getGame' } }
         });
@@ -50,16 +79,14 @@ class GameFactory {
   }
   /** return a Game Resources that gives access to images, maps, sounds  */
   async getGameResources(gameType) {
-    const perfEnabled = typeof lemmings !== 'undefined' &&
-      (lemmings.performanceAPI === true || lemmings.perfMetrics === true) &&
-      typeof performance !== 'undefined' &&
-      typeof performance.measure === 'function' &&
-      typeof performance.now === 'function';
-    const perfStart = perfEnabled ? performance.now() : 0;
+    const app = getApp();
+    const perfInstrumentation = resolvePerfInstrumentation(app);
+    const perfEnabled = perfInstrumentation.enabled;
+    const perfStart = perfEnabled ? perfInstrumentation.perfApi.now() : 0;
     const finish = () => {
       if (!perfEnabled) return;
       try {
-        performance.measure('GameFactory getGameResources', {
+        perfInstrumentation.perfApi.measure('GameFactory getGameResources', {
           start: perfStart,
           detail: { devtools: { track: 'GameFactory', trackGroup: 'Load', color: 'secondary', tooltipText: 'getGameResources' } }
         });
@@ -69,7 +96,7 @@ class GameFactory {
     };
     try {
       const config = await this.configReader.getConfig(gameType);
-      if (config == null) {
+      if (config === null || config === undefined) {
         throw new Error('Game config not found');
       }
       const Resources = getDependency('GameResources', GameResources);
diff --git a/js/game/GameGui.js b/js/game/GameGui.js
index 08c00382..bd9b14c0 100644
--- a/js/game/GameGui.js
+++ b/js/game/GameGui.js
@@ -1,886 +1,4 @@
-import { CommandNuke } from '../commands/CommandNuke.js';
-import { CommandReleaseRateIncrease } from '../commands/CommandReleaseRateIncrease.js';
-import { CommandReleaseRateDecrease } from '../commands/CommandReleaseRateDecrease.js';
-import { CommandSelectSkill } from '../commands/CommandSelectSkill.js';
-import { EventHandler } from '../util/EventHandler.js';
-import { MiniMap } from '../render/MiniMap.js';
-import { SkillTypes } from './SkillTypes.js';
-import { getDependency } from '../core/dependencies.js';
-
-const getApp = () => {
-  if (typeof globalThis !== 'undefined' && globalThis.lemmings) return globalThis.lemmings;
-  if (typeof lemmings !== 'undefined') return lemmings;
-  return null;
-};
-
-/**
- * GameGui – unchanged public API, now updates itself
- * even while the simulation is paused.
- */
-class GameGui {
-  constructor(game, skillPanelSprites, skills, gameTimer, gameVictoryCondition) {
-    /* external handles */
-    this.game                 = game;
-    this.skillPanelSprites    = skillPanelSprites;
-    this.skills               = skills;
-    this.gameTimer            = gameTimer;
-    this.gameVictoryCondition = gameVictoryCondition;
-
-    /* change-tracking flags (original names) */
-    this.gameTimeChanged       = true;
-    this.skillsCountChanged    = true;
-    this.skillSelectionChanged = true;
-    this.backgroundChanged     = true;
-    this.releaseRateChanged    = true;
-
-    this.nukePrepared          = false;
-    this.lastGameSpeed      = 0;
-
-    /* sprite caches */
-    this._panelSprite    = skillPanelSprites.getPanelSprite();
-    this._numLeftCache   = new Array(10);
-    this._numRightCache  = new Array(10);
-    this._numEmptySprite = skillPanelSprites.getNumberSpriteEmpty();
-    this._letterCache    = new Map();
-
-    /* runtime state */
-    this.display          = null;
-    this.miniMap          = null;
-    this.deltaReleaseRate = 0;
-
-    /* marching ants selection animation settings */
-    this.selectionDashLen   = 4;   // length of dash segments (1px longer)
-    this.selectionAnimDelay = 60;  // frames between offset increments (slower)
-    this.selectionAnimStep  = 1;   // pixels per animation step
-    this._selectionOffset   = 0;
-    this._selectionCounter  = 0;
-
-    /* hover state */
-    this._hoverPanelIdx   = -1;
-    this._hoverSpeedUp    = false;
-    this._hoverSpeedDown  = false;
-
-    /* release rate lock state */
-    this._rrLockMin = false;
-    this._rrLockMax = false;
-
-    this._guiBound = this._guiLoop.bind(this);
-    this._guiRafId = 0;
-
-    this.smoothScroller = new SmoothScroller();
-
-    this._nukeAfterCountdown = 0;
-
-    this._onEachGameSecond = () => {
-      const app = getApp();
-      this._applyReleaseRateAuto();
-      if (app?.nukeAfter > 0) {
-        this._nukeAfterCountdown++;
-        if (this._nukeAfterCountdown == app.nukeAfter) {
-          this.game.queueCommand(new CommandNuke());
-          this.nukePrepared = false;
-        }
-      }
-      if ((Math.floor(this.gameTimer.getGameTime()) % 2) == 0) {
-        this.backgroundChanged = true;
-      }
-      this.gameTimeChanged = true;
-
-      if (this._guiRafId == 0) {
-        this._guiRafId = window.requestAnimationFrame(this._guiBound);
-      }
-    };
-    gameTimer.eachGameSecond.on(this._onEachGameSecond);
-
-    this._onSkillCountChanged = () => {
-      this.backgroundChanged = true;
-    };
-    skills.onCountChanged.on(this._onSkillCountChanged);
-
-    this._onSkillSelectionChanged = () => {
-      this.backgroundChanged = true;
-      this._selectionOffset  = 0;
-    };
-    skills.onSelectionChanged.on(this._onSkillSelectionChanged);
-  }
-
-  setMiniMap(miniMap) {
-    this.miniMap = miniMap;
-    this.game?.lemmingManager?.setMiniMap?.(miniMap);
-  }
-
-  _applyReleaseRateAuto() {
-    if (!this.deltaReleaseRate) return;
-    if (this.gameTimer.isRunning()) {
-      const min = this.gameVictoryCondition.getMinReleaseRate?.() ?? 0;
-      const max = this.gameVictoryCondition.getMaxReleaseRate?.() ?? 99;
-      const cur = this.gameVictoryCondition.getCurrentReleaseRate();
-      let   neu = cur + this.deltaReleaseRate;
-      if (neu < min) neu = min;
-      if (neu > max) neu = max;
-      this.gameVictoryCondition.setCurrentReleaseRate?.(neu) ??
-                (this.gameVictoryCondition.releaseRate = neu);
-      this.releaseRateChanged = true;
-    }
-    if (this.deltaReleaseRate > 0)
-      this.game.queueCommand(new CommandReleaseRateIncrease(this.deltaReleaseRate));
-    else
-      this.game.queueCommand(new CommandReleaseRateDecrease(-this.deltaReleaseRate));
-  }
-
-  handleSkillMouseDown(e) {
-    const panelIndex = Math.trunc(e.x / 16);
-    if (panelIndex !== 11) {
-      this.nukePrepared = false;
-      this.backgroundChanged = true;
-      this.gameTimeChanged = true;
-    }
-
-    if (panelIndex === 0 || panelIndex === 1) {
-      const step = panelIndex === 0 ? -3 : +3;
-      const min = this.gameVictoryCondition.getMinReleaseRate?.() ?? 0;
-      const max = this.gameVictoryCondition.getMaxReleaseRate?.() ?? 99;
-      const cur = this.gameVictoryCondition.getCurrentReleaseRate();
-      if ((step < 0 && cur <= min) || (step > 0 && cur >= max)) {
-        if (this.skills.clearSelectedSkill()) {
-          this.skillSelectionChanged = true;
-        }
-        return;
-      }
-      if (this.gameTimer.isRunning()) {
-        let neu = cur + step;
-        if (neu < min) neu = min;
-        if (neu > max) neu = max;
-        this.lastGameSpeed = neu;
-        this.gameVictoryCondition.setCurrentReleaseRate?.(neu) ??
-                    (this.gameVictoryCondition.releaseRate = neu);
-      }
-      this.deltaReleaseRate = step;
-      this._applyReleaseRateAuto();
-      this.gameTimeChanged = true;
-      return;
-    }
-    if (panelIndex === 10) {
-      if (e.y >= 32) { // if it is the bottom of the pause button
-        const pauseX = e.x - 159; // the leftmost position
-        const pauseIndex = Math.trunc(pauseX / 9);
-        const speedFac = this.gameTimer.speedFactor;
-        const app = getApp();
-        const debugOrBench = (this.game.showDebug || app?.bench === true || app?.bench2 === true || app?.benchReverse === true);
-        const syncSpeed = () => {
-          if (app) app.gameSpeedFactor = this.gameTimer.speedFactor;
-        };
-        if (pauseIndex === 0) {
-          if (speedFac > 10) {
-            this.gameTimer.speedFactor -= 10;
-            this.drawSpeedChange(false);
-            syncSpeed();
-            return;
-          }
-          if (speedFac > 1) {
-            this.gameTimer.speedFactor--;
-            this.drawSpeedChange(false); 
-            syncSpeed();
-            return;
-          }
-          if (debugOrBench || speedFac == 1 || speedFac > 0.1 && speedFac < 1) {
-            this.gameTimer.speedFactor = Math.trunc((this.gameTimer.speedFactor-0.1)*100)/100;
-            this.drawSpeedChange(false);
-            syncSpeed();
-            return;
-          }
-        }
-        if (pauseIndex === 1) {
-          if (speedFac < 1) {
-            this.gameTimer.speedFactor = Math.trunc((this.gameTimer.speedFactor+0.1)*100)/100;
-            this.drawSpeedChange(true);
-            syncSpeed();
-            return;
-          }
-          if (speedFac >= 10 && speedFac < 120) {
-            this.gameTimer.speedFactor += 10;
-            this.drawSpeedChange(true);
-            syncSpeed();
-            return;
-          }
-          if (speedFac < 10) {
-            this.gameTimer.speedFactor++;
-            this.drawSpeedChange(true);
-            syncSpeed();
-            return;
-          }
-        }
-      } else {
-        this.gameTimer.toggle();
-      }
-      this.skillSelectionChanged = true;
-      this.gameTimeChanged = true;
-      return;
-    }
-    if (panelIndex === 11) {
-      if (this.nukePrepared) {
-        this.game.queueCommand(new CommandNuke());
-        this.nukePrepared = false;
-        this.gameTimeChanged = true;
-      } else {
-        this.nukePrepared = true;
-        this.gameTimeChanged = true;
-      }
-      if (this.skills.clearSelectedSkill()) {
-        this.skillSelectionChanged = true;
-      }
-      this.skillSelectionChanged = true;
-      return;
-    }
-    const newSkill = this.getSkillByPanelIndex(panelIndex);
-    if (newSkill === SkillTypes.UNKNOWN) return;
-    if (this.skills.getSkill(newSkill) <= 0) {
-      if (this.skills.clearSelectedSkill()) this.skillSelectionChanged = true;
-      return;
-    }
-    this.skills.setSelectedSkill(newSkill);
-    this.game.queueCommand(new CommandSelectSkill(newSkill));
-  }
-
-  handleSkillMouseRightDown(e) {
-    const panelIndex = Math.trunc(e.x / 16);
-
-    this.nukePrepared = false; // always cancel nuke confirmation on right click
-    this.gameTimeChanged = true;
-
-    if (panelIndex === 0) {
-      const min = this.gameVictoryCondition.getMinReleaseRate?.() ?? 0;
-      this.gameVictoryCondition.setCurrentReleaseRate?.(min) ??
-        (this.gameVictoryCondition.releaseRate = min);
-      this.deltaReleaseRate = -min;
-      this._applyReleaseRateAuto();
-      return;
-    }
-
-    if (panelIndex === 1) {
-      const max = this.gameVictoryCondition.getMaxReleaseRate?.() ?? 99;
-      this.gameVictoryCondition.setCurrentReleaseRate?.(max) ??
-        (this.gameVictoryCondition.releaseRate = max);
-      this.deltaReleaseRate = max;
-      this._applyReleaseRateAuto();
-      return;
-    }
-
-    if (panelIndex === 10) { // reset game speed if you right click pause
-      if (this.gameTimer.speedFactor !== 1) {
-        this.gameTimer.speedFactor = 1;
-        this.drawSpeedChange(false, true);
-        const app = getApp();
-        if (app) app.gameSpeedFactor = this.gameTimer.speedFactor;
-      }
-      return;
-    }
-
-    if (panelIndex === 11) { // enable debug mode if you right click nuke
-      this.game.showDebug = !this.game.showDebug;
-      return;
-    }
-  }
-
-  handleSkillDoubleClick(e) {
-    if (Math.trunc(e.x / 16) === 11)
-      this.game.queueCommand(new CommandNuke());
-  }
-
-  handleMouseMove(e) {
-    const rawIdx = e.y > 15 ? Math.trunc(e.x / 16) : -1;
-    let idx = rawIdx;
-
-    if (!this.gameTimer.isRunning() && rawIdx !== 11) {
-      idx = -1;
-    }
-
-    if (rawIdx === 0 || rawIdx === 1) {
-      const rrMin = this.gameVictoryCondition.getMinReleaseRate?.() ?? 0;
-      const rrMax = this.gameVictoryCondition.getMaxReleaseRate?.() ?? 99;
-      const rrCur = this.gameVictoryCondition.getCurrentReleaseRate?.() ?? 0;
-      if ((rawIdx === 0 && rrCur <= rrMin) || (rawIdx === 1 && rrCur >= rrMax)) {
-        idx = -1;
-      }
-    } else if (rawIdx >= 2 && rawIdx <= 9) {
-      const skill = this.getSkillByPanelIndex(rawIdx);
-      if (this.skills.getSkill(skill) <= 0) idx = -1;
-    }
-
-    const wasIdx = this._hoverPanelIdx;
-    if (idx !== wasIdx) {
-      this._hoverPanelIdx = idx;
-      this.backgroundChanged = true;
-      this.gameTimeChanged = true;
-    }
-
-    let up = false, down = false;
-    if (rawIdx === 10 && e.y >= 32) {
-      const pauseIndex = Math.trunc((e.x - 159) / 9);
-      const speedFac = this.gameTimer.speedFactor;
-      if (pauseIndex === 1 && speedFac < 120) up = true;
-      if (pauseIndex === 0 && speedFac > 0.1) down = true;
-    }
-    if (up !== this._hoverSpeedUp || down !== this._hoverSpeedDown) {
-      this._hoverSpeedUp = up;
-      this._hoverSpeedDown = down;
-      this.gameSpeedChanged = true;
-      this.gameTimeChanged = true;
-    }
-  }
-
-  setGuiDisplay(display) {
-    if (this.display && this._displayListeners) {
-      for (const [event, handler] of this._displayListeners) {
-        this.display[event].off(handler);
-      }
-    }
-    this.display = display;
-    if (!this.miniMap) {
-      const MiniMapCtor = getDependency('MiniMap', MiniMap);
-      this.setMiniMap(new MiniMapCtor(this.game.gameDisplay, this.game.level, display));
-    }
-
-    this._displayListeners = [
-      ['onMouseDown', e => { this.deltaReleaseRate = 0; if (e.y > 15) this.handleSkillMouseDown(e); }],
-      ['onMouseUp', () => { this.deltaReleaseRate = 0; }],
-      ['onMouseRightDown', e => { if (e.y > 15) this.handleSkillMouseRightDown(e); }],
-      ['onMouseRightUp', () => { }],
-      ['onDoubleClick', e => { if (e.y > 15) this.handleSkillDoubleClick(e); }],
-      ['onMouseMove', e => { this.handleMouseMove(e); }],
-    ];
-    for (const [event, handler] of this._displayListeners) {
-      display[event].on(handler);
-    }
-
-    // Initialize the HUD size immediately so Stage can center it
-    display.initSize(this._panelSprite.width, this._panelSprite.height);
-    display.setBackground(this._panelSprite.getData());
-    display.stage.updateStageSize();
-
-    this.gameTimeChanged = this.skillsCountChanged = this.skillSelectionChanged = this.backgroundChanged = this.releaseRateChanged = true;
-    this._guiRafId = window.requestAnimationFrame(this._guiBound);
-  }
-
-  _guiLoop(now) {
-    if (!this.display) {
-      return;
-    }
-    const ss = this.smoothScroller;
-    if (ss) {
-      ss.update();
-    }
-
-    window.cancelAnimationFrame(this._guiRafId);
-    this.render();
-    this.display.redraw();
-    this._guiRafId = window.requestAnimationFrame(this._guiBound);
-  }
-
-  dispose() {
-    if (this._guiRafId) {
-      window.cancelAnimationFrame(this._guiRafId);
-      this._guiRafId = 0;
-    }
-    if (this.gameTimer?.eachGameSecond && this._onEachGameSecond) {
-      this.gameTimer.eachGameSecond.off(this._onEachGameSecond);
-      this._onEachGameSecond = null;
-    }
-    if (this.skills?.onCountChanged && this._onSkillCountChanged) {
-      this.skills.onCountChanged.off(this._onSkillCountChanged);
-      this._onSkillCountChanged = null;
-    }
-    if (this.skills?.onSelectionChanged && this._onSkillSelectionChanged) {
-      this.skills.onSelectionChanged.off(this._onSkillSelectionChanged);
-      this._onSkillSelectionChanged = null;
-    }
-    if (this.display && this._displayListeners) {
-      for (const [event, handler] of this._displayListeners) {
-        this.display[event].off(handler);
-      }
-    }
-    this._letterCache = null;
-    this._numRightCache = null;
-    this._numLeftCache = null;
-    this._panelSprite = null;
-    this._numEmptySprite = null;
-    if (this.miniMap?.dispose) this.miniMap.dispose();
-    this.miniMap = null;
-    this.smoothScroller = null;
-
-  }
-
-  render() {
-    const perfEnabled = typeof lemmings !== 'undefined' &&
-      (lemmings.performanceAPI === true || lemmings.perfMetrics === true) &&
-      typeof performance !== 'undefined' &&
-      typeof performance.measure === 'function' &&
-      typeof performance.now === 'function';
-    const perfStart = perfEnabled ? performance.now() : 0;
-    if (!this.display) {
-      if (perfEnabled) {
-        try {
-          performance.measure('GameGui render', {
-            start: perfStart,
-            detail: { devtools: { track: 'GameGui', trackGroup: 'Render', color: 'secondary', tooltipText: 'render' } }
-          });
-        } catch {
-          /* ignored */
-        }
-      }
-      return;
-    }
-    const d = this.display;
-    const app = getApp();
-    const bench = app?.bench === true || app?.bench2 === true || app?.benchReverse === true || app?.benchSequence === true;
-    if (bench) this.gameTimeChanged = true;
-
-    if (this.backgroundChanged) {
-      this.backgroundChanged = false;
-      d.initSize(this._panelSprite.width, this._panelSprite.height);
-      d.setBackground(this._panelSprite.getData());
-
-      this.gameTimeChanged = this.skillsCountChanged = this.skillSelectionChanged = this.releaseRateChanged = this.gameSpeedChanged = true;
-    }
-
-    if (this.gameTimeChanged) {
-      this.gameTimeChanged = false;
-
-      if (!bench) {
-        let text = '';
-        if (this._hoverPanelIdx >= 0) {
-          text = this._getPanelName(this._hoverPanelIdx);
-          if (this._hoverPanelIdx === 10) {
-            if (this._hoverSpeedUp) text = 'Increase';
-            else if (this._hoverSpeedDown) text = 'Decrease';
-          }
-        } else if (this.game?.gameDisplay?.hoverLemming?.action) {
-          text = this.game.gameDisplay.hoverLemming.action.getActionName?.() || '';
-        } else if (this.nukePrepared) {
-          text = 'Nuke';
-        } else if (!this.gameTimer.isRunning()) {
-          text = 'Pause';
-        } else {
-          const sel = this.skills.getSelectedSkill();
-          if (sel !== SkillTypes.UNKNOWN) {
-            const key = Object.keys(SkillTypes)[sel];
-            if (key) {
-              text = key.charAt(0) + key.slice(1).toLowerCase();
-            }
-          }
-        }
-        const statusText = this._composeStatusText(this._formatTickIndicator(), text);
-        if (statusText) {
-          this.drawGreenString(d, statusText, 0, 0);
-        }
-        const timeText = app?.endless ? '4-20' : this.gameTimer.getGameLeftTimeString();
-        this.drawGreenString(d, 'Time ' + timeText + '-00', 248, 0);
-        const totalCount = this.game?.getLemmingManager?.()?.spawnTotal ??
-          this.gameVictoryCondition.getReleaseCount();
-        if (totalCount >= 0) {
-          this.drawGreenString(d, 'Out ' + totalCount + '  ', 112, 0);
-        }
-        this.drawGreenString(d, 'In'  + this._pad(this.gameVictoryCondition.getSurvivorPercentage(), 3) + '%', 186, 0);
-      } else {
-        const activeCount = this.game.getLemmingManager?.()?.getLemmings?.()?.length ?? 0;
-        const stats = [
-          'T' + (app?.steps ?? 0),
-          'TPS ' + Math.round(app?.tps ?? 0),
-          'ACTIVE ' + activeCount,
-          'SPAWNED ' + (this.game.getLemmingManager?.().spawnTotal ?? 0)
-        ];
-        let x = 0;
-        for (let i = 0; i < stats.length; i++) {
-          const s = stats[i];
-          this.drawGreenString(d, s, x, 0);
-          x += (s.length+1) * 8;
-        }
-      }
-    }
-
-    if (this.gameSpeedChanged) {
-      this.gameSpeedChanged = false;
-      const speedFac = this.gameTimer.speedFactor;
-
-      d.drawRect(160, 32, 16, 10, 0, 0, 0, true); // draw bottom black rect on pause button
-
-      if (speedFac != 120) {
-        const greenS  = this._getGreenLetter('f');
-        d.drawFrameResized(greenS, 173, 34, 3, 4);
-      }
-
-      if (speedFac != 0.1) {
-        const greenP  = this._getGreenLetter('-');
-        d.drawFrameResized(greenP, 161, 33, 3, 6);
-      }
-
-      const tens  = Math.floor(speedFac / 10);
-      const ones  = speedFac % 10;
-      const left  = this._getRightDigit(tens);
-      const right = this._getRightDigit(ones);
-      let rightX = 164;
-      if (left && tens > 0) {
-        rightX = 164;
-        d.drawFrameResized(left, rightX-4, 33, 8, 6);
-      }
-      if (right) {
-        d.drawFrameResized(right, rightX, 33, 8, 6);
-      }
-      if (speedFac < 1) {
-        let sn = Math.trunc((speedFac)*10);
-        const small = this._getRightDigit(sn);
-        d.setPixel(167, 38, 255, 255, 255);
-        d.drawFrameResized(small, 164, 33, 8, 6);
-        d.drawHorizontalLine(169, 33, 175, 0, 0, 0);
-      }
-
-      if (this._hoverSpeedUp) {
-        d.drawHorizontalLine(172, 32, 175, 0, 166, 0);
-        d.drawHorizontalLine(172, 38, 175, 0, 166, 0);
-      } else if (this._hoverSpeedDown) {
-        d.drawHorizontalLine(161, 32, 164, 0, 166, 0);
-        d.drawHorizontalLine(161, 38, 164, 0, 166, 0);
-      }
-    }
-
-
-    if (this.skillsCountChanged) {
-      this.skillsCountChanged = false;
-      for (let s = 1; s < Object.keys(SkillTypes).length; ++s) {
-        const panel = this.getPanelIndexBySkill(s);
-        const count = this.skills.getSkill(s);
-        this.drawPanelNumber(d, count, panel);
-      }
-    }
-    for (let s = 1; s < Object.keys(SkillTypes).length; ++s) {
-      if (this.skills.getSkill(s) <= 0) {
-        const panel = this.getPanelIndexBySkill(s);
-        d.drawStippleRect(panel * 16, 16, 16, 23, 160, 160, 160);
-      }
-    }
-    if (this.skillSelectionChanged) {
-      this.skillSelectionChanged = false;
-    }
-
-    if (!this.gameTimer.isRunning()) {
-      this.drawPaused(d);
-    }
-    if (this.nukePrepared) {
-      this.drawNukeConfirm(d);
-      this.drawNukeHover(d);
-    }
-
-    if (this._hoverPanelIdx >= 0) {
-      if (this._hoverPanelIdx === 11) {
-        if (!this.nukePrepared) this.drawSkillHover(d, this._hoverPanelIdx, 255, 128, 0);
-      } else {
-        this.drawSkillHover(d, this._hoverPanelIdx);
-      }
-    }
-
-    // update marching ants animation
-    if (++this._selectionCounter >= this.selectionAnimDelay) {
-      this._selectionCounter = 0;
-      this._selectionOffset += this.selectionAnimStep;
-    }
-
-    this.drawSelection(d, this.getPanelIndexBySkill(this.skills.getSelectedSkill()));
-    if (this.releaseRateChanged) {
-      this.releaseRateChanged = false;
-      this.drawPanelNumber(d, this.gameVictoryCondition.getMinReleaseRate(),     0);
-      this.drawPanelNumber(d, this.gameVictoryCondition.getCurrentReleaseRate(), 1);
-    }
-
-    const rrMin = this.gameVictoryCondition.getMinReleaseRate?.() ?? 0;
-    const rrMax = this.gameVictoryCondition.getMaxReleaseRate?.() ?? 99;
-    const rrCur = this.gameVictoryCondition.getCurrentReleaseRate?.() ?? 0;
-
-    const lockMin = rrCur <= rrMin;
-    const lockMax = rrCur >= rrMax;
-
-    if (lockMin) this._drawLockEdge(d, 0);
-    if (lockMax) this._drawLockEdge(d, 1);
-
-    if (this._rrLockMin && !lockMin) this.backgroundChanged = true;
-    if (this._rrLockMax && !lockMax) this.backgroundChanged = true;
-
-    this._rrLockMin = lockMin;
-    this._rrLockMax = lockMax;
-
-    if (this.miniMap) {
-      const viewX = this.game.level.screenPositionX;
-      const viewW = d.worldDataSize.width;
-
-      this.miniMap.render(viewX, viewW);
-    }
-    if (perfEnabled) {
-      try {
-        performance.measure('GameGui render', {
-          start: perfStart,
-          detail: { devtools: { track: 'GameGui', trackGroup: 'Render', color: 'secondary', tooltipText: 'render' } }
-        });
-      } catch {
-        /* ignored */
-      }
-    }
-  }
-
-  _formatTickIndicator() {
-    const tick = Math.max(0, this.gameTimer?.tickIndex ?? 0);
-    const dir = this.game?.timeTravel?.isReversing ? '<' : '>';
-    return `T${tick}${dir}`;
-  }
-
-  _composeStatusText(primary, secondary) {
-    const left = primary || '';
-    const right = secondary || '';
-    if (!left && !right) return '';
-    const combined = right ? `${left} ${right}` : left;
-    const maxChars = 14;
-    return combined.length > maxChars ? combined.slice(0, maxChars) : combined;
-  }
-
-  _pad(v, len) { const s = String(v); return s.length >= len ? s : ' '.repeat(len - s.length) + s; }
-  _getLeftDigit(d)  { if (d <= 0) return null;
-    if (!this._numLeftCache[d])  this._numLeftCache[d]  = this.skillPanelSprites.getNumberSpriteLeft(d);
-    return this._numLeftCache[d]; }
-  _getRightDigit(d) { if (!this._numRightCache[d])
-    this._numRightCache[d] = this.skillPanelSprites.getNumberSpriteRight(d);
-  return this._numRightCache[d]; 
-  }
-  _getGreenLetter(ch) {
-    const cachedGreenLet  = this._letterCache.get(ch);
-    if (!cachedGreenLet) { 
-      const newGreenLet = this.skillPanelSprites.getLetterSprite(ch); 
-      this._letterCache.set(ch, newGreenLet); 
-      return newGreenLet;
-    } else {
-      return cachedGreenLet;
-    }
-  }
-
-  drawSelection(d, panelIdx) {
-    if (panelIdx < 0) return;
-    d.drawMarchingAntRect(
-      16 * panelIdx,
-      16,
-      16,
-      23,
-      this.selectionDashLen,
-      this._selectionOffset
-    );
-  }
-
-  drawPaused(d) {
-    d.drawMarchingAntRect(
-      16 * 10,
-      16,
-      16,
-      23,
-      this.selectionDashLen,
-      this._selectionOffset
-    );
-  }
-
-  drawSkillHover(d, panelIdx, r = 255, g = 255, b = 0) {
-    if (panelIdx < 0) return;
-    d.drawRect(16 * panelIdx, 16, 16, 23, r, g, b);
-  }
-
-  _getPanelName(idx) {
-    switch (idx) {
-    case 0:  return 'Decrease';
-    case 1:  return 'Increase';
-    case 10: return 'Pause';
-    case 11: return 'Nuke';
-    default:
-      const skill = this.getSkillByPanelIndex(idx);
-      if (skill !== SkillTypes.UNKNOWN) {
-        const key = Object.keys(SkillTypes)[skill];
-        if (key) return key.charAt(0) + key.slice(1).toLowerCase();
-      }
-      return '';
-    }
-  }
-
-  _drawLockEdge(d, panelIdx) {
-    const x = 16 * panelIdx + 2;
-    const y = 18;
-    const w = 11; // narrower than full panel
-    const h = 18; // shorter than full panel
-    d.drawStippleRect(x, y, w, 0, 160, 160, 160);       // top
-    d.drawStippleRect(x, y + h, w, 0, 160, 160, 160);    // bottom
-    d.drawStippleRect(x, y, 0, h, 160, 160, 160);        // left
-    d.drawStippleRect(x + w, y, 0, h, 160, 160, 160);    // right
-  }
-
-  drawSpeedChange(upDown, reset = false) {
-    if (!reset) {
-      if (upDown) {
-        this.display.drawHorizontalLine(172, 32, 175, 0, 166, 0);
-        this.display.drawHorizontalLine(172, 38, 175, 0, 166, 0);
-      } else {
-        this.display.drawHorizontalLine(161, 32, 164, 0, 166, 0);
-        this.display.drawHorizontalLine(161, 38, 164, 0, 166, 0);
-      }
-    } else {
-      this.display.drawHorizontalLine(161, 32, 175, 111, 0, 0);
-      this.display.drawHorizontalLine(161, 38, 175, 111, 0, 0);
-    }
-
-    if (this._hoverSpeedUp) {
-      this.display.drawHorizontalLine(172, 32, 175, 0, 166, 0);
-      this.display.drawHorizontalLine(172, 38, 175, 0, 166, 0);
-    } else if (this._hoverSpeedDown) {
-      this.display.drawHorizontalLine(161, 32, 164, 0, 166, 0);
-      this.display.drawHorizontalLine(161, 38, 164, 0, 166, 0);
-    }
-
-    this.gameSpeedChanged = true;
-  }
-
-  drawNukeConfirm(d) {
-    d.drawRect(16 * 11, 16, 16, 23, 255, 0, 0);
-  }
-
-  drawNukeHover(d) {
-    d.drawMarchingAntRect(
-      16 * 11,
-      16,
-      16,
-      23,
-      this.selectionDashLen,
-      this._selectionOffset * 2,
-      0xFF0080FF,
-      0xFF00FFFF
-    );
-  }
-
-  drawPanelNumber(d, num, panelIdx) { 
-    this.drawNumber(d, num, 4 + 16 * panelIdx, 17); 
-  }
-
-  drawNumber(d, num, x, y, small = false) {
-    if (num <= 0) { 
-      d.drawFrame(this._numEmptySprite, x, y); return; 
-    }
-    const tens  = Math.floor(num / 10);
-    const ones  = num % 10;
-    const left  = this._getLeftDigit(tens);
-    const right = this._getRightDigit(ones);
-    if (left) { 
-      d.drawFrameCovered(left,  x, y, 0, 0, 0);
-    }
-    d.drawFrame(right, x, y);
-  }
-
-  drawGreenString(d, text, x, y) {
-    for (let i = 0; i < text.length; ++i) {
-      const ch = text[i];
-      let img  = this._letterCache.get(ch);
-      if (!img) { 
-        img = this.skillPanelSprites.getLetterSprite(ch); 
-        this._letterCache.set(ch, img); 
-      }
-      if (img) {
-        d.drawFrameCovered(img, x, y, 0, 0, 0);
-      }
-      x += 8;
-    }
-  }
-
-  getSkillByPanelIndex(idx) {
-    switch (Math.trunc(idx)) {
-    case 2:  return SkillTypes.CLIMBER;
-    case 3:  return SkillTypes.FLOATER;
-    case 4:  return SkillTypes.BOMBER;
-    case 5:  return SkillTypes.BLOCKER;
-    case 6:  return SkillTypes.BUILDER;
-    case 7:  return SkillTypes.BASHER;
-    case 8:  return SkillTypes.MINER;
-    case 9:  return SkillTypes.DIGGER;
-    default: return SkillTypes.UNKNOWN;
-    }
-  }
-
-  getPanelIndexBySkill(skill) {
-    switch (skill) {
-    case SkillTypes.CLIMBER: return 2;
-    case SkillTypes.FLOATER: return 3;
-    case SkillTypes.BOMBER:  return 4;
-    case SkillTypes.BLOCKER: return 5;
-    case SkillTypes.BUILDER: return 6;
-    case SkillTypes.BASHER:  return 7;
-    case SkillTypes.MINER:   return 8;
-    case SkillTypes.DIGGER:  return 9;
-    default: return -1;
-    }
-  }
-}
-
-class SmoothScroller {
-  static minZoom = 0.25;
-  static maxZoom = 8;
-
-  constructor() {
-    this.velocity = 0;     // pixels/frame (or units/frame)
-    this.friction = 0.99;
-    this.minVelocity = 0.7;       //0.0175;
-    this._lastVelocity = 0;
-
-    this.onHasVelocity = new EventHandler();
-  }
-
-  hasVelocity() {
-    if (this.velocity < this.minVelocity || this.velocity == 0) {
-      return false;
-    }
-    return true;
-  }
-
-  // call this whenever a wheel event fires:
-  addImpulse(delta) {
-    if (delta == 0) {
-      console.log('error: trying to add 0 impulse');
-      return;
-    }
-    if (delta > 50) {
-      delta = 50;
-    }
-    if (delta < -50) {
-      delta = -50;
-    }
-
-    if (this.velocity + delta > 500) {
-      this.velocity = 500;
-      return;
-    }
-
-    if (this.velocity + delta < -500) {
-      this.velocity = -500;
-      return;
-    }
-
-    this.velocity += delta; 
-  }
-
-  update() {
-    // decay the velocity:
-    this.velocity = this.velocity * this.friction;
-
-
-    // stop if below threshold:
-    if (Math.abs(this.velocity) < this.minVelocity) {
-      this.velocity = 0;
-      if (this._lastVelocity != 0) {
-        this._lastVelocity = 0;
-        this.onHasVelocity.trigger(this.velocity);
-      }
-      return;
-    }
-    this._lastVelocity = this.velocity;
-    this.onHasVelocity.trigger(this.velocity);
-  }
-}
-
-export { GameGui, SmoothScroller };
+export { GameGui } from './game-gui/GameGuiCore.js';
+export {
+  SmoothScroller
+} from './game-gui/GameGuiShared.js';
diff --git a/js/game/GameResources.js b/js/game/GameResources.js
index dfc9fee6..d6ae1eee 100644
--- a/js/game/GameResources.js
+++ b/js/game/GameResources.js
@@ -20,7 +20,7 @@ class GameResources extends BaseLogger {
   }
   /** return the main.dat file container */
   getMainDat() {
-    if (this.mainDat != null) {
+    if (this.mainDat !== null) {
       return this.mainDat;
     }
     this.mainDat = this._loadMainDat();
diff --git a/js/game/GameRuntime.js b/js/game/GameRuntime.js
new file mode 100644
index 00000000..7b0911a2
--- /dev/null
+++ b/js/game/GameRuntime.js
@@ -0,0 +1,32 @@
+const createGameRuntime = (game, performanceContext = null) => ({
+  get history() {
+    return game?.history ?? null;
+  },
+  get soundEvents() {
+    return game?.soundEvents ?? null;
+  },
+  get miniMap() {
+    return game?.lemmingManager?.miniMap ?? null;
+  },
+  get performanceContext() {
+    return performanceContext ?? null;
+  },
+  get isReplayApplying() {
+    return !!game?.timeTravel?.isReversing;
+  }
+});
+
+const getRuntimeHistory = (runtime) => runtime?.history ?? null;
+const getRuntimeSoundEvents = (runtime) => runtime?.soundEvents ?? null;
+const getRuntimeMiniMap = (runtime) => runtime?.miniMap ?? null;
+const getRuntimePerformanceContext = (runtime) => runtime?.performanceContext ?? null;
+const isRuntimeReplayApplying = (runtime) => runtime?.isReplayApplying === true;
+
+export {
+  createGameRuntime,
+  getRuntimeHistory,
+  getRuntimeSoundEvents,
+  getRuntimeMiniMap,
+  getRuntimePerformanceContext,
+  isRuntimeReplayApplying
+};
diff --git a/js/game/GameSkills.js b/js/game/GameSkills.js
index 6182d16d..2ea95b06 100644
--- a/js/game/GameSkills.js
+++ b/js/game/GameSkills.js
@@ -1,6 +1,13 @@
 import { EventHandler } from '../util/EventHandler.js';
 import { SkillTypes } from './SkillTypes.js';
 
+const MIN_SKILL_TYPE = SkillTypes.UNKNOWN;
+const MAX_SKILL_TYPE = SkillTypes.DIGGER;
+
+const isValidSkillType = (type) => (
+  Number.isInteger(type) && type >= MIN_SKILL_TYPE && type <= MAX_SKILL_TYPE
+);
+
 class GameSkills {
   constructor(level) {
     this.selectedSkill = SkillTypes.CLIMBER;
@@ -37,7 +44,7 @@ class GameSkills {
     return true;
   }
   getSkill(type) {
-    if (!SkillTypes[Object.keys(SkillTypes)[type]])
+    if (!isValidSkillType(type))
       return 0;
     const val = this.skills[type];
     if (val === Infinity) return 99;
@@ -47,10 +54,10 @@ class GameSkills {
     return this.selectedSkill;
   }
   setSelectedSkill(skill) {
-    if (this.selectedSkill == skill) {
+    if (this.selectedSkill === skill) {
       return false;
     }
-    if (!SkillTypes[Object.keys(SkillTypes)[skill]]) {
+    if (!isValidSkillType(skill)) {
       return false;
     }
     this.selectedSkill = skill;
diff --git a/js/game/GameTimer.js b/js/game/GameTimer.js
index d41c86a5..e7d5d20c 100644
--- a/js/game/GameTimer.js
+++ b/js/game/GameTimer.js
@@ -1,13 +1,24 @@
 import { COUNTER_LIMIT } from '../core/constants.js';
+import { getAppContext } from '../core/dependencies.js';
 import { EventHandler } from '../util/EventHandler.js';
-import { withPerformance } from '../util/LogHandler.js';
+import {
+  canMeasurePerformance,
+  recordPerformanceMeasure
+} from '../util/performanceInstrumentation.js';
 
 const getApp = () => {
-  if (typeof globalThis !== 'undefined' && globalThis.lemmings) return globalThis.lemmings;
-  if (typeof lemmings !== 'undefined') return lemmings;
+  const app = getAppContext();
+  if (app) return app;
   return null;
 };
 
+const TIMER_LOOP_DEVTOOLS = Object.freeze({
+  track: 'GameTimer',
+  trackGroup: 'Game Loop',
+  color: 'primary',
+  tooltipText: 'loop'
+});
+
 class GameTimer {
   #speedFactor;
   #frameTime;
@@ -23,14 +34,20 @@ class GameTimer {
   #catchupBaseSpeed;
   #visHandler;
   #timeTravel;
+  #windowRef;
+  #documentRef;
+  #performanceRef;
   benchStartupFrames = 0;
   benchStableFactor = 1;
 
-  constructor(level) {
+  constructor(level, runtime = {}) {
     this.TIME_PER_FRAME_MS = 60;
+    this.#windowRef = runtime.window ?? (typeof window !== 'undefined' ? window : null);
+    this.#documentRef = runtime.document ?? (typeof document !== 'undefined' ? document : null);
+    this.#performanceRef = runtime.performance ?? (typeof performance !== 'undefined' ? performance : null);
     this.#speedFactor = 1;
     this.#frameTime = this.TIME_PER_FRAME_MS;
-    this.#rafId = 0;
+    this.#rafId = null;
     this.#running = false;
     this.#lastTime = 0;
     this.#lastGameSecond = 0;
@@ -49,7 +66,9 @@ class GameTimer {
       const app = getApp();
       const skip = app?.bench || app?.bench2 || app?.benchReverse || app?.benchSequence;
       if (skip) return;
-      const hidden = document.visibilityState === 'hidden' || !document.hasFocus();
+      const documentRef = this.#documentRef;
+      const hidden = documentRef?.visibilityState === 'hidden' ||
+        (typeof documentRef?.hasFocus === 'function' && !documentRef.hasFocus());
       if (hidden) {
         if (this.isRunning()) {
           this.#autoPaused = true;
@@ -60,9 +79,9 @@ class GameTimer {
         this.continue();
       }
     };
-    document.addEventListener('visibilitychange', this.#visHandler, false);
-    window.addEventListener('blur',  this.#visHandler, false);
-    window.addEventListener('focus', this.#visHandler, false);
+    this.#documentRef?.addEventListener?.('visibilitychange', this.#visHandler, false);
+    this.#windowRef?.addEventListener?.('blur',  this.#visHandler, false);
+    this.#windowRef?.addEventListener?.('focus', this.#visHandler, false);
     this.#updateFrameTime();
     this.benchStartupFrames = 0;
     this.benchStableFactor = 1;
@@ -82,7 +101,37 @@ class GameTimer {
       console.warn('tickIndex wrapped, resetting to 0');
       this.#tickIndex = 0;
     } else {
-      this.#tickIndex = v;
+      this.#tickIndex = Math.max(0, Math.trunc(Number(v) || 0));
+    }
+    this.#lastGameSecond = this.#getWholeGameSecond();
+  }
+  #incrementTickIndex() {
+    const next = this.#tickIndex + 1;
+    if (next >= COUNTER_LIMIT) {
+      console.warn('tickIndex wrapped, resetting to 0');
+      this.#tickIndex = 0;
+      this.#lastGameSecond = 0;
+      return;
+    }
+    this.#tickIndex = next;
+  }
+
+  #now() {
+    return this.#performanceRef?.now?.() ?? Date.now();
+  }
+
+  #getWholeGameSecond() {
+    return Math.floor(this.#tickIndex * (this.TIME_PER_FRAME_MS / 1000));
+  }
+
+  #emitGameSecondIfChanged() {
+    if (!this.eachGameSecond) return;
+    const current = this.#getWholeGameSecond();
+    if (current === this.#lastGameSecond) return;
+    const step = current > this.#lastGameSecond ? 1 : -1;
+    while (this.#lastGameSecond !== current) {
+      this.#lastGameSecond += step;
+      this.eachGameSecond.trigger(this.#lastGameSecond);
     }
   }
 
@@ -111,16 +160,31 @@ class GameTimer {
   }
 
   continue() {
-    if (this.isRunning()) return;
-    this.#lastTime = performance.now();
+    if (this.isRunning()) return true;
+    this.#lastTime = this.#now();
     this.#running = true;
-    this.#rafId = window.requestAnimationFrame(this.#loopBound);
+    if (!this.#scheduleFrame()) {
+      this.#running = false;
+      this.#rafId = null;
+      return false;
+    }
+    return true;
+  }
+
+  #scheduleFrame() {
+    if (typeof this.#windowRef?.requestAnimationFrame !== 'function') {
+      return false;
+    }
+    const rafId = this.#windowRef.requestAnimationFrame(this.#loopBound);
+    if (rafId == null) return false;
+    this.#rafId = rafId;
+    return true;
   }
 
   suspend() {
-    if (this.#rafId) {
-      window.cancelAnimationFrame(this.#rafId);
-      this.#rafId = 0;
+    if (this.#rafId != null) {
+      this.#windowRef?.cancelAnimationFrame?.(this.#rafId);
+      this.#rafId = null;
     }
     this.#running = false;
   }
@@ -138,71 +202,85 @@ class GameTimer {
       this.#timeTravel.stepBackward(count);
       return;
     }
+    const beforeTick = this.onBeforeGameTick;
+    const onTick = this.onGameTick;
     for (let i = 0; i < count; i++) {
       if (dir >= 0) {
-        if (this.onBeforeGameTick) this.onBeforeGameTick.trigger(this.tickIndex);
-        ++this.tickIndex;
-        if (this.onGameTick) this.onGameTick.trigger();
-      } else if (this.tickIndex > 0) {
-        --this.tickIndex;
-        if (this.onBeforeGameTick) this.onBeforeGameTick.trigger(this.tickIndex);
-        if (this.onGameTick) this.onGameTick.trigger();
+        if (beforeTick) beforeTick.trigger(this.#tickIndex);
+        this.#incrementTickIndex();
+        this.#emitGameSecondIfChanged();
+        if (onTick) onTick.trigger();
+      } else if (this.#tickIndex > 0) {
+        this.#tickIndex -= 1;
+        if (beforeTick) beforeTick.trigger(this.#tickIndex);
+        this.#emitGameSecondIfChanged();
+        if (onTick) onTick.trigger();
       }
     }
   }
 
   #loop(now) {
     if (!this.isRunning()) return;
-    return withPerformance(
-      'GameTimer loop',
-      {
-        track: 'GameTimer',
-        trackGroup: 'Game Loop',
-        color: 'primary',
-        tooltipText: 'loop'
-      },
-      () => {
-        window.cancelAnimationFrame(this.#rafId);
-        this.#rafId = 0;
-        const app = getApp();
-        if (app) app.tps = this.tps;
-        const gameSeconds = Math.floor(this.#lastTime / this.TIME_PER_FRAME_MS);
-        if (gameSeconds > this.#lastGameSecond) {
-          if (this.eachGameSecond) {
-            this.#lastGameSecond = gameSeconds;
-            this.eachGameSecond.trigger();
-          }
+    const app = getApp();
+    const bench = app?.bench === true;
+    const bench2 = app?.bench2 === true;
+    const benchReverse = app?.benchReverse === true;
+    const benchSequence = app?.benchSequence === true;
+    const inBenchMode = bench || bench2 || benchReverse || benchSequence;
+    const perfEnabled = !!app &&
+      !inBenchMode &&
+      (app.performanceAPI === true || app.perfMetrics === true) &&
+      canMeasurePerformance(this.#performanceRef);
+    const perfStart = perfEnabled ? this.#now() : 0;
+
+    try {
+      if (this.#rafId != null) {
+        this.#windowRef?.cancelAnimationFrame?.(this.#rafId);
+      }
+      this.#rafId = null;
+      const frameTime = this.#frameTime;
+      if (app) app.tps = 1000 / frameTime;
+      let delta = now - this.#lastTime;
+      if (delta >= frameTime) {
+        const steps = Math.floor(delta / frameTime);
+        if (bench || benchReverse || benchSequence) {
+          this.#benchSpeedAdjust(steps, app);
+        }
+        if (bench2) {
+          if (steps > 1) this.#catchupSpeedAdjust(steps, app);
+          else this.#restoreSpeed();
         }
-        const frameTime = this.#frameTime;
-        let delta = now - this.#lastTime;
-        if (delta >= frameTime) {
-          const steps = Math.floor(delta / frameTime);
-          if (app?.bench === true || app?.benchReverse === true || app?.benchSequence === true) {
-            this.#benchSpeedAdjust(steps);
-          }
-          if (app?.bench2 === true) {
-            if (steps > 1) this.#catchupSpeedAdjust(steps);
-            else this.#restoreSpeed();
-          }
-          delta -= steps * frameTime;
-          this.#lastTime = now - delta;
-          for (let i = 0; i < steps; ++i) {
-            if (this.onBeforeGameTick) this.onBeforeGameTick.trigger(this.tickIndex);
-            ++this.tickIndex;
-            if (this.onGameTick) this.onGameTick.trigger();
-          }
+        delta -= steps * frameTime;
+        this.#lastTime = now - delta;
+        const beforeTick = this.onBeforeGameTick;
+        const onTick = this.onGameTick;
+        for (let i = 0; i < steps; ++i) {
+          if (beforeTick) beforeTick.trigger(this.#tickIndex);
+          this.#incrementTickIndex();
+          this.#emitGameSecondIfChanged();
+          if (onTick) onTick.trigger();
         }
-        this.#rafId = window.requestAnimationFrame(this.#loopBound);
       }
-    ).call(this);
+      if (!this.#scheduleFrame()) {
+        this.#running = false;
+        this.#rafId = null;
+      }
+    } finally {
+      if (perfEnabled) {
+        recordPerformanceMeasure('GameTimer loop', {
+          start: perfStart,
+          detail: { devtools: TIMER_LOOP_DEVTOOLS }
+        }, { performanceRef: this.#performanceRef });
+      }
+    }
   }
 
-  #benchSpeedAdjust(steps) {
+  #benchSpeedAdjust(steps, appRef = null) {
     // dynamically adjust speed based on how far we fall behind
     // slowThreshold and recoverThreshold scale with the current speedFactor.
     // Below speedFactor 6 the values grow too large; use speedFactor * 1.5 so
     // lower speeds still trigger slowdown after at least 10 queued frames.
-    const app = getApp();
+    const app = appRef || getApp();
     if (!app) return;
     app.steps = steps;
     const oldSpeed = this.#speedFactor;
@@ -223,12 +301,9 @@ class GameTimer {
 
     if (this.benchStartupFrames <= 0) {
       if (steps > 100) {
-        this.suspend();
         this.#stableTicks = 0;
-        this.#speedFactor = 0.1;
-        window.setTimeout(() => {
-          if (!this.isRunning()) this.continue();
-        }, 500);
+        const severeDrop = Math.min(this.#speedFactor * 0.5, this.#speedFactor - 1);
+        this.#speedFactor = Math.max(0.2, severeDrop);
       } else if (steps > slowThreshold) {
         this.#stableTicks = 0;
         const sf = this.#speedFactor;
@@ -257,6 +332,7 @@ class GameTimer {
         ? `rgba(0,255,0,${intensity})`
         : `rgba(255,0,0,${intensity})`;
       const dashLen = Math.max(2, Math.min(steps, 20));
+      const inBenchMode = app.bench || app.bench2 || app.benchReverse || app.benchSequence;
       const stage = app?.stage;
       if (stage?.startOverlayFade) {
         let rect = null;
@@ -265,18 +341,21 @@ class GameTimer {
           const scale = gui.viewPoint.scale;
           rect = { x: gui.x + 160 * scale, y: gui.y + 32 * scale, width: 16 * scale, height: 10 * scale };
         }
-        stage.startOverlayFade(color, rect, dashLen);
+        stage.startOverlayFade(color, rect, inBenchMode ? 0 : dashLen);
       }
     }
   }
 
-  #catchupSpeedAdjust(steps) {
+  #catchupSpeedAdjust(steps, appRef = null) {
     const newFactor = Math.max(0.1, 1 / steps);
+    const app = appRef || getApp();
     if (!this.#catchupSlow) {
       this.#catchupBaseSpeed = this.#speedFactor;
     }
     if (newFactor < this.#speedFactor) {
-      console.log(`catchup: ${steps} steps, speed ${newFactor}`);
+      if (app?.logBenchCatchup === true) {
+        console.log(`catchup: ${steps} steps, speed ${newFactor}`);
+      }
       this.#speedFactor = newFactor;
       this.#updateFrameTime();
       this.#catchupSlow = true;
@@ -286,15 +365,18 @@ class GameTimer {
   #restoreSpeed() {
     if (this.#catchupSlow) {
       this.#catchupSlow = false;
-      this.speedFactor = this.#catchupBaseSpeed;
+      if (this.#speedFactor !== this.#catchupBaseSpeed) {
+        this.#speedFactor = this.#catchupBaseSpeed;
+        this.#updateFrameTime();
+      }
     }
   }
 
   stop() {
     this.suspend();
-    document.removeEventListener('visibilitychange', this.#visHandler, false);
-    window.removeEventListener('blur', this.#visHandler, false);
-    window.removeEventListener('focus', this.#visHandler, false);
+    this.#documentRef?.removeEventListener?.('visibilitychange', this.#visHandler, false);
+    this.#windowRef?.removeEventListener?.('blur', this.#visHandler, false);
+    this.#windowRef?.removeEventListener?.('focus', this.#visHandler, false);
 
     // Dispose all event handlers to prevent leaks across level reloads
     if (this.onBeforeGameTick && this.onBeforeGameTick.dispose)
@@ -327,8 +409,8 @@ class GameTimer {
     const app = getApp();
     if (app?.endless === true) {
       return 42069 * (this.TIME_PER_FRAME_MS / 1000);
-    }  
-    return t * (this.TIME_PER_FRAME_MS / 1000); 
+    }
+    return t * (this.TIME_PER_FRAME_MS / 1000);
   }
   secondsToTicks(s) { return s * (1000 / this.TIME_PER_FRAME_MS); }
 }
diff --git a/js/game/GameVictoryCondition.js b/js/game/GameVictoryCondition.js
index 4833d0f3..70bd4b7b 100644
--- a/js/game/GameVictoryCondition.js
+++ b/js/game/GameVictoryCondition.js
@@ -1,6 +1,8 @@
+import { getAppContext } from '../core/dependencies.js';
+
 const getApp = () => {
-  if (typeof globalThis !== 'undefined' && globalThis.lemmings) return globalThis.lemmings;
-  if (typeof lemmings !== 'undefined') return lemmings;
+  const app = getAppContext();
+  if (app) return app;
   return null;
 };
 
@@ -27,7 +29,7 @@ class GameVictoryCondition {
     }
     let oldReleaseRate = this.releaseRate;
     let newReleaseRate = this.boundToRange(this.minReleaseRate, this.releaseRate + count, GameVictoryCondition.maxReleaseRate);
-    if (newReleaseRate == oldReleaseRate) {
+    if (newReleaseRate === oldReleaseRate) {
       return false;
     }
     this.releaseRate = newReleaseRate;
diff --git a/js/game/GameView.js b/js/game/GameView.js
index ff97c6e1..ba41ca2c 100644
--- a/js/game/GameView.js
+++ b/js/game/GameView.js
@@ -1,1480 +1 @@
-import { createCrosshairFrame } from '../input/CrosshairCursor.js';
-import { GameFactory } from './GameFactory.js';
-import { GameStateTypes } from './GameStateTypes.js';
-import { GameTypes } from './GameTypes.js';
-import { KeyboardShortcuts } from '../input/KeyboardShortcuts.js';
-import { Lemming } from '../lemmings/Lemming.js';
-import { BaseLogger } from '../util/LogHandler.js';
-import { MidiEventRouter } from '../midi/MidiEventRouter.js';
-import { MidiMapping } from '../midi/MidiMapping.js';
-import { Stage } from '../render/Stage.js';
-import { TriggerTypes } from '../level/TriggerTypes.js';
-import { FileContainer } from '../data/FileContainer.js';
-import { LevelIndexResolve } from '../level/LevelIndexResolve.js';
-import { LevelReader } from '../level/LevelReader.js';
-import { EditorSession } from '../editor/EditorSession.js';
-import { createEditorLevelFromClassic } from '../editor/ClassicLevelConverter.js';
-import { loadEditorLevel } from '../editor/EditorLevelLoader.js';
-import { listSavedLevels, loadSavedLevel } from '../editor/EditorStorage.js';
-import { getDependency } from '../core/dependencies.js';
-
-const getGameTypes = () => getDependency('GameTypes', GameTypes);
-const getGameStateTypes = () => getDependency('GameStateTypes', GameStateTypes);
-const getTriggerTypes = () => getDependency('TriggerTypes', TriggerTypes);
-const getLemmingCtor = () => getDependency('Lemming', Lemming);
-
-const cloneConfig = (config) => JSON.parse(JSON.stringify(config || {}));
-
-const hashString = (input) => {
-  let hash = 2166136261;
-  const str = String(input ?? '');
-  for (let i = 0; i < str.length; i++) {
-    hash ^= str.charCodeAt(i);
-    hash = Math.imul(hash, 16777619);
-  }
-  return (hash >>> 0).toString(16);
-};
-
-class GameView extends BaseLogger {
-  constructor() {
-    super();
-    globalThis.lemmings = this;
-    this.gameType = null;
-    this.levelIndex = 0;
-    this.levelGroupIndex = 0;
-    this.gameResources = null;
-    this.game = null;
-    const Factory = getDependency('GameFactory', GameFactory);
-    this.gameFactory = new Factory('./');
-    this.stage = null;
-    this.gameSpeedFactor = 1;
-    this.bench = false; // just keep spawning lems
-    this.bench2 = false;
-    this.benchReverse = false;
-    this.benchSequence = false;
-    this._benchMeasureExtras = false;
-    this.endless = false; // time doesn't run out, game doesn't end
-    this.nukeAfter = 0; // nuke after x seconds
-    this.scale = 0; // zoom 
-    this.laggedOut = 0;
-    this.extraLemmings = 0;
-    this.perfMetrics = false;
-    this.performanceAPI = false;
-    this.steps = 0;
-    this._benchMonitor = null;
-    this._benchSpeedTrack = null;
-    this._benchMaxSpeed = 0;
-    this._benchCounts = [];
-    this._benchIndex = 0;
-    this._benchExtraList = null;
-    this._benchExtraIndex = 0;
-    this._benchStartTime = 0;
-    this._benchBaseEntrances = null;
-    this._benchEntrancePool = null;
-    this.preserveHistory = false;
-    this.cheatEnabled = false;
-    this.applyQuery();
-    this.elementGameState = null;
-    this.autoMoveTimer = null;
-    this.resumeTimer = null;
-    this.elementSelectGameType = null;
-    this.elementSelectLevelGroup = null;
-    this.elementSelectLevel = null;
-    this.configs = null;
-    const Shortcuts = getDependency('KeyboardShortcuts', KeyboardShortcuts);
-    this.shortcuts = new Shortcuts(this);
-    this.midiRouter = null;
-    this._midiOut = null;
-    this._midiMapping = null;
-    this._midiBaseConfig = null;
-    this._midiSchemaHash = null;
-    this.midiEnabled = false;
-
-    this.includeSavedLevels = false;
-    this.autoExitEditorOnSelect = false;
-    this.editorMode = false;
-    this.editorSession = null;
-    this.editorPlaytest = false;
-    this._editorWasRunning = false;
-    this._editorInputWasEnabled = true;
-    this._editorPanWasEnabled = true;
-
-    const gameTypes = getGameTypes();
-    this.log.log('selected level: ' + gameTypes.toString(this.gameType) + ' : ' + this.levelIndex + ' / ' + this.levelGroupIndex);
-  }
-
-  set gameCanvas(el) {
-    if (this.stage && this.stage.dispose) {
-      window.removeEventListener('resize', this._stageResize);
-      window.removeEventListener('orientationchange', this._stageResize);
-      this.stage.dispose();
-    }
-    const StageCtor = getDependency('Stage', Stage);
-    this.stage = new StageCtor(el);
-    this._stageResize = () => this.stage.scheduleUpdateStageSize();
-    window.addEventListener('resize', this._stageResize);
-    window.addEventListener('orientationchange', this._stageResize);
-    this._stageResize();
-  }
-
-  /** start or continue the game */
-  async start(replayString) {
-    if (!this.gameFactory) return;
-    if (this.game != null) {
-      this.continue();
-      return;
-    }
-    try {
-      const game = await this.gameFactory.getGame(this.gameType, this.gameResources);
-      await game.loadLevel(this.levelGroupIndex, this.levelIndex);
-      if (replayString != null) {
-        game.getCommandManager().loadReplay(replayString);
-      }
-      game.setGameDisplay(this.stage.getGameDisplay());
-      game.setGuiDisplay(this.stage.getGuiDisplay());
-      if (this.stage && game.level) {
-        this.applyLevelViewport(game.level);
-      }
-      game.getGameTimer().speedFactor = this.gameSpeedFactor;
-      if (this.preserveHistory || replayString != null) {
-        game.history?.setPreserveFutureHistory?.(true);
-      }
-      // Display a custom crosshair cursor sized relative to a lemming
-      this.stage.setCursorSprite(createCrosshairFrame(24));
-      if (this.midiEnabled) {
-        await this.initMidiRouting();
-        this.midiRouter?.attach(game.soundEvents, { game, stage: this.stage });
-      }
-      game.start();
-      const gameStateTypes = getGameStateTypes();
-      this.changeHtmlText(this.elementGameState, gameStateTypes.toString(gameStateTypes.RUNNING));
-      game.onGameEnd.on(state => this.onGameEnd(state));
-      this.game = game;
-      if (this.cheatEnabled) this.game.cheat();
-      if (this.debug) this.game.showDebug = true;
-    } catch (e) {
-      this.log.log('Error starting game:', e);
-    }
-  }
-
-  onGameEnd(gameResult) {
-    const gameStateTypes = getGameStateTypes();
-    this.changeHtmlText(this.elementGameState, gameStateTypes.toString(gameResult.state));
-    this.stage.startFadeOut();
-    console.dir(gameResult);
-    this.autoMoveTimer = window.setTimeout(() => {
-      const gameStateTypes = getGameStateTypes();
-      if (gameResult.state == gameStateTypes.SUCCEEDED) {
-        /// move to next level
-        this.moveToLevel(1);
-      } else {
-        /// redo this level
-        this.moveToLevel(0);
-      }
-      this.autoMoveTimer = null;
-    }, 2500);
-  }
-
-  async loadReplay(replayString) {
-    await this.start(replayString);
-  }
-
-  cheat() {
-    if (this.game == null) {
-      return;
-    }
-    this.game.cheat();
-  }
-
-  suspend() {
-    if (this.game == null) {
-      return;
-    }
-    this.game.getGameTimer().suspend();
-  }
-
-  suspendWithColor(color) {
-    if (this.game == null) {
-      return;
-    }
-    this.game.getGameTimer().suspend();
-    if (this.stage?.startOverlayFade) {
-      let rect = null;
-      if (this.bench || this.bench2 || this.benchReverse) {
-        const gui = this.stage.guiImgProps;
-        const scale = gui.viewPoint.scale;
-        rect = {
-          x: gui.x + 160 * scale,
-          y: gui.y + 32 * scale,
-          width: 16 * scale,
-          height: 10 * scale
-        };
-      }
-      this.stage.startOverlayFade(color, rect);
-    }
-    if (this.resumeTimer) {
-      window.clearTimeout(this.resumeTimer);
-      this.resumeTimer = null;
-    }
-    this.resumeTimer = window.setTimeout(() => {
-      if (this.game) this.game.getGameTimer().continue();
-      this.resumeTimer = null;
-    }, 2000);
-  }
-
-  continue () {
-    if (this.game == null) {
-      return;
-    }
-    this.game.getGameTimer().continue();
-  }
-
-  nextFrame() {
-    if (this.game == null) {
-      return;
-    }
-    const timer = this.game.getGameTimer();
-    if (!timer) return;
-    if (this.game.timeTravel?.isReversing) {
-      this.game.timeTravel.stopReverse();
-    }
-    this.game.history?.truncateAfter?.(timer.tickIndex);
-    timer.tick(1);
-    if (this.game.gameGui) {
-      this.game.gameGui.gameTimeChanged = true;
-    }
-    this.game.render();
-  }
-
-  prevFrame() {
-    if (this.game == null) {
-      return;
-    }
-    const timeTravel = this.game.timeTravel;
-    if (timeTravel?.stepBackward) {
-      timeTravel.stepBackward(1);
-      return;
-    }
-    this.game.getGameTimer().tick(-1);
-    this.game.render();
-  }
-
-  selectSpeedFactor(newSpeed) {
-    if (this.game == null) {
-      return;
-    }
-    this.gameSpeedFactor = newSpeed;
-    this.game.getGameTimer().speedFactor = newSpeed;
-  }
-
-  playMusic(moveInterval) {
-
-  }
-
-  stopMusic() {
-
-  }
-
-  stopSound() {
-
-  }
-
-  playSound(moveInterval) {
-
-  }
-
-  get midiOut() { return this._midiOut; }
-  set midiOut(output) {
-    this._midiOut = output;
-    this.midiRouter?.setOutput?.(output);
-  }
-
-  _getWebMidi() {
-    if (typeof globalThis !== 'undefined') return globalThis.WebMidi;
-    return null;
-  }
-
-  _formatMidiEnableError(err) {
-    const rawMessage = err?.message ? String(err.message) : String(err || '');
-    const isSecure = typeof window !== 'undefined'
-      ? (window.isSecureContext || window.location?.protocol === 'https:' || window.location?.hostname === 'localhost')
-      : true;
-    if (!isSecure) {
-      return 'WebMIDI requires HTTPS or localhost.';
-    }
-    if (err?.name === 'NotAllowedError' || /permission/i.test(rawMessage)) {
-      return 'WebMIDI permission denied. Check browser permissions.';
-    }
-    if (err?.name === 'SecurityError' || /secure context/i.test(rawMessage)) {
-      return 'WebMIDI requires HTTPS or localhost.';
-    }
-    if (err?.name === 'NotSupportedError') {
-      return 'WebMIDI is not supported in this browser.';
-    }
-    if (!rawMessage) {
-      return 'WebMIDI enable failed.';
-    }
-    return `WebMIDI enable failed: ${rawMessage}`;
-  }
-
-  async _ensureWebMidiEnabled() {
-    const webMidi = this._getWebMidi();
-    if (!webMidi) {
-      if (typeof globalThis.onMidiError === 'function') {
-        globalThis.onMidiError('WebMIDI is not supported in this browser.');
-      }
-      return null;
-    }
-    if (webMidi.enabled) return webMidi;
-    try {
-      await webMidi.enable();
-      if (typeof globalThis.onEnabled === 'function') {
-        globalThis.onEnabled();
-      }
-      return webMidi;
-    } catch (e) {
-      this.log.log('WebMidi enable failed', e);
-      if (typeof globalThis.onMidiError === 'function') {
-        globalThis.onMidiError(this._formatMidiEnableError(e));
-      }
-      return null;
-    }
-  }
-
-  async _loadMidiMapping() {
-    if (!this.gameFactory?.fileProvider) return new MidiMapping();
-    try {
-      const text = await this.gameFactory.fileProvider.loadString('midi-mapping.json');
-      const mapping = MidiMapping.fromJson(text);
-      this._midiSchemaHash = hashString(text);
-      this._midiBaseConfig = cloneConfig(mapping.config);
-      return mapping;
-    } catch (e) {
-      this.log.log('Unable to load midi-mapping.json, using defaults', e);
-      const mapping = new MidiMapping();
-      this._midiSchemaHash = hashString(JSON.stringify(mapping.config));
-      this._midiBaseConfig = cloneConfig(mapping.config);
-      return mapping;
-    }
-  }
-
-  async initMidiRouting() {
-    if (!this.midiEnabled) {
-      this.midiRouter?.detach?.();
-      this.midiRouter?.scheduler?.allNotesOff?.();
-      return null;
-    }
-    if (!this.midiRouter) {
-      await this._ensureWebMidiEnabled();
-      this._midiMapping = this._midiMapping || await this._loadMidiMapping();
-      if (typeof globalThis !== 'undefined' && globalThis.lemmingsMidiOverrides) {
-        this.applyMidiOverrides(globalThis.lemmingsMidiOverrides);
-      }
-      const viewPan = typeof globalThis !== 'undefined' ? globalThis.lemmingsMidiViewPan : null;
-      if (typeof viewPan === 'boolean') {
-        const position = this._midiMapping.config.position || {};
-        this._midiMapping.config.position = { ...position, viewPan };
-      }
-      const Router = getDependency('MidiEventRouter', MidiEventRouter);
-      this.midiRouter = new Router(this._midiMapping);
-    }
-    if (!this._midiOut) {
-      const webMidi = this._getWebMidi();
-      if (webMidi?.enabled && webMidi.outputs?.length) {
-        this._midiOut = webMidi.outputs[0];
-      }
-    }
-    if (this._midiOut) this.midiRouter.setOutput(this._midiOut);
-    return this.midiRouter;
-  }
-
-  async setMidiEnabled(enabled) {
-    this.midiEnabled = !!enabled;
-    if (!this.midiEnabled) {
-      this.midiRouter?.detach?.();
-      this.midiRouter?.scheduler?.allNotesOff?.();
-      return;
-    }
-    await this.initMidiRouting();
-    if (this.game?.soundEvents) {
-      this.midiRouter?.attach(this.game.soundEvents, { game: this.game, stage: this.stage });
-    }
-  }
-
-  applyMidiOverrides(overrides) {
-    if (!this._midiBaseConfig) return;
-    const merged = typeof MidiMapping?.mergeConfigs === 'function'
-      ? MidiMapping.mergeConfigs(this._midiBaseConfig, overrides || {})
-      : { ...this._midiBaseConfig, ...(overrides || {}) };
-    this._midiMapping = new MidiMapping(merged);
-    if (this.midiRouter) this.midiRouter.setMapping(this._midiMapping);
-  }
-
-  getMidiConfig() {
-    return this._midiMapping?.config ?? null;
-  }
-
-  getMidiBaseConfig() {
-    return this._midiBaseConfig;
-  }
-
-  getMidiSchemaHash() {
-    return this._midiSchemaHash;
-  }
-
-  enableDebug() {
-    if (this.game == null) {
-      return;
-    }
-    this.game.setDebugMode(true);
-  }
-
-  /** add/subtract one to the current levelIndex */
-  async moveToLevel(moveInterval = 0) {
-    if (this.inMoveToLevel) return;
-    this.inMoveToLevel = true;
-    const oldGameType = this.gameType;
-    try {
-      const gameTypes = getGameTypes();
-      let gameType = this.gameType;
-      let levelGroupIndex = this.levelGroupIndex;
-      let levelIndex = (this.levelIndex + moveInterval) | 0;
-      let config = await this.gameFactory.getConfig(gameType);
-
-      const savedEntries = this._getSavedLevelEntries();
-      const getBaseGroupCount = cfg => cfg?.level?.order?.length ?? 0;
-      const getGroupLength = (cfg, groupIndex) => {
-        const baseGroupCount = getBaseGroupCount(cfg);
-        return this._getGroupLength(cfg, groupIndex, baseGroupCount, savedEntries);
-      };
-      const getGroupCount = (cfg) => {
-        const baseGroupCount = getBaseGroupCount(cfg);
-        return this._getGroupCount(baseGroupCount, savedEntries);
-      };
-      const isValidGameType = (type) =>
-        type > 0 && type < gameTypes.length;
-
-      if (moveInterval < 0) {
-        while (levelIndex < 0) {
-          if (levelGroupIndex > 0) {
-            levelGroupIndex--;
-            levelIndex += getGroupLength(config, levelGroupIndex);
-            continue;
-          }
-          if (gameType > 1) {
-            gameType--;
-            config = await this.gameFactory.getConfig(gameType);
-            levelGroupIndex = Math.max(0, getGroupCount(config) - 1);
-            levelIndex += getGroupLength(config, levelGroupIndex);
-            continue;
-          }
-          levelIndex = 0;
-          break;
-        }
-      } else if (moveInterval > 0) {
-        while (true) {
-          const groupLength = getGroupLength(config, levelGroupIndex);
-          if (groupLength <= 0) {
-            if (levelGroupIndex + 1 < getGroupCount(config)) {
-              levelGroupIndex++;
-              continue;
-            }
-            gameType++;
-            if (!isValidGameType(gameType)) {
-              gameType = 1;
-            }
-            config = await this.gameFactory.getConfig(gameType);
-            levelGroupIndex = 0;
-            continue;
-          }
-          if (levelIndex < groupLength) break;
-          levelIndex -= groupLength;
-          if (levelGroupIndex + 1 < getGroupCount(config)) {
-            levelGroupIndex++;
-            continue;
-          }
-          gameType++;
-          if (!isValidGameType(gameType)) {
-            gameType = 1;
-          }
-          config = await this.gameFactory.getConfig(gameType);
-          levelGroupIndex = 0;
-        }
-      }
-
-      if (!isValidGameType(gameType)) {
-        gameType = 1;
-        levelGroupIndex = 0;
-        levelIndex = 0;
-      }
-
-      this.gameType = gameType;
-      this.levelGroupIndex = levelGroupIndex;
-      this.levelIndex = levelIndex;
-
-      if (oldGameType !== this.gameType) {
-        this.gameResources = await this.gameFactory.getGameResources(this.gameType);
-      }
-      if (this.autoExitEditorOnSelect && this.editorMode) {
-        this.exitEditorMode();
-      }
-      if (this.editorMode) {
-        await this.loadEditorLevelFromSelection();
-      } else {
-        await this.loadLevel();
-      }
-    } finally {
-      this.inMoveToLevel = false;
-    }
-  }
-  /** helper to parse a numeric query value */
-  parseNumber(query, names, def, min, max, multiplier = 1) {
-    for (const name of names) {
-      const raw = query.get(name);
-      if (raw !== null) {
-        const val = parseFloat(raw);
-        if (!isNaN(val) && val >= min && val <= max) {
-          return val * multiplier;
-        }
-      }
-    }
-    return def;
-  }
-
-  /** helper to parse a boolean query value */
-  parseBool(query, names, def = false) {
-    for (const name of names) {
-      if (query.has(name)) {
-        return query.get(name) === 'true';
-      }
-    }
-    return def;
-  }
-
-  /** convert a string to a number or return 0 if NaN */
-  /** read parameters from the current URL */
-  applyQuery() {
-    this.gameType = 1;
-    const query = typeof window === 'undefined'
-      ? new URLSearchParams('')
-      : new URLSearchParams(window.location.search);
-    this.gameType = this.parseNumber(query, ['version', 'v'], 1, 1, 6);
-    this.levelGroupIndex = this.parseNumber(query, ['difficulty', 'd'], 1, 1, 6) - 1;
-    this.levelIndex = this.parseNumber(query, ['level', 'l'], 1, 1, 100) - 1;
-    this.gameSpeedFactor = this.parseNumber(query, ['speed', 's'], 1, 0, 100);
-    // values above normal correspond to discrete steps
-    if (this.gameSpeedFactor > 1) {
-      this.gameSpeedFactor = Math.round(this.gameSpeedFactor);
-    }
-    this.cheatEnabled = this.parseBool(query, ['cheat', 'c']);
-    this.debug = this.parseBool(query, ['debug', 'dbg']);
-    this.bench = this.parseBool(query, ['bench', 'b']);
-    this.bench2 = this.parseBool(query, ['bench2', 'b2']);
-    this.benchReverse = this.parseBool(query, ['benchReverse', 'bR']);
-    this.benchSequence = this.parseBool(query, ['benchSequence', 'bs']);        
-    this.preserveHistory = this.parseBool(query, ['preserveHistory', 'ph']);
-    if (this.bench || this.bench2 || this.benchSequence) {
-      this.benchReverse = false;
-    }
-    this.endless = this.parseBool(query, ['endless', 'e']);
-    this.nukeAfter = this.parseNumber(query, ['nukeAfter', 'na'], 0, 1, 60, 10);
-    this.extraLemmings = this.parseNumber(query, ['extra', 'ex'], 0, 1, 1000);
-    this.scale = this.parseNumber(query, ['scale', 'sc'], 0, 0.0125, 8);
-    this.laggedOut = 0;
-        
-    this.shortcut = false;
-    if (query.get('shortcut') || query.get('_')) {
-      this.shortcut = (query.get('shortcut') || query.get('_')) === 'true';
-    }
-    this.performanceAPI = this.parseBool(query, ['performanceAPI', 'pa']);
-    this.perfMetrics = this.performanceAPI;
-  }
-  updateQuery() {
-    const params = typeof window === 'undefined'
-      ? new URLSearchParams('')
-      : new URLSearchParams(window.location.search);
-    const setParam = (longName, shortName, value, def, always) => {
-      params.delete(longName);
-      params.delete(shortName);
-      if (always || (value !== undefined && value !== def)) {
-        params.set(this.shortcut ? shortName : longName, value);
-      }
-    };
-
-    // main game state should always remain visible
-    setParam('version', 'v', this.gameType, undefined, true);
-    setParam('difficulty', 'd', this.levelGroupIndex + 1, undefined, true);
-    setParam('level', 'l', this.levelIndex + 1, undefined, true);
-    setParam('speed', 's', this.gameSpeedFactor, undefined, true);
-    setParam('cheat', 'c', this.cheatEnabled, undefined, true);
-
-    // optional flags only appear when non-default
-    setParam('debug', 'dbg', this.debug, false);
-    setParam('bench', 'b', this.bench, false);
-    setParam('bench2', 'b2', this.bench2, false);
-    setParam('benchReverse', 'bR', this.benchReverse, false);
-    setParam('benchSequence', 'bs', this.benchSequence, false);
-    setParam('preserveHistory', 'ph', this.preserveHistory, false);
-    setParam('endless', 'e', this.endless, false);
-    setParam('nukeAfter', 'na', this.nukeAfter ? this.nukeAfter / 10 : undefined);
-    setParam('extra', 'ex', this.extraLemmings, 0);
-    setParam('scale', 'sc', this.scale, 0);
-    setParam('performanceAPI', 'pa', this.performanceAPI, false);
-
-    if (this.shortcut) {
-      params.set('_', true);
-    } else {
-      params.delete('_');
-    }
-
-    this.setHistoryState(params);
-  }
-  setHistoryState(params) {
-    const query = params instanceof URLSearchParams ? params : new URLSearchParams(params);
-    history.replaceState(null, null, '?' + query.toString());
-  }
-  /** change the the text of a html element */
-  changeHtmlText(htmlElement, value) {
-    if (htmlElement == null) {
-      return;
-    }
-    htmlElement.innerText = value;
-  }
-  /** prefix items with an increasing index */
-  prefixNumbers(list) {
-    return list.map((item, idx) => `${idx + 1} - ${item}`);
-  }
-
-  /** convert select values to integers */
-  strToNum(str) {
-    const n = parseInt(str, 10);
-    return Number.isNaN(n) ? 0 : n;
-  }
-  /** remove items of a <select> */
-  clearHtmlList(htmlList) {
-    while (htmlList.options.length) {
-      htmlList.remove(0);
-    }
-  }
-
-  _getSavedLevelEntries() {
-    if (!this.includeSavedLevels) return [];
-    return listSavedLevels();
-  }
-
-  _getSavedGroupIndex(baseGroupCount, savedEntries = []) {
-    if (!this.includeSavedLevels || !savedEntries.length) return -1;
-    return baseGroupCount;
-  }
-
-  _isSavedGroupIndex(groupIndex, baseGroupCount, savedEntries = []) {
-    return groupIndex === this._getSavedGroupIndex(baseGroupCount, savedEntries);
-  }
-
-  _getGroupCount(baseGroupCount, savedEntries = []) {
-    const savedIndex = this._getSavedGroupIndex(baseGroupCount, savedEntries);
-    return savedIndex >= 0 ? baseGroupCount + 1 : baseGroupCount;
-  }
-
-  _getGroupNames(savedEntries = []) {
-    const baseGroups = this.gameResources?.getLevelGroups?.() ?? [];
-    if (!this.includeSavedLevels || !savedEntries.length) return baseGroups;
-    return [...baseGroups, 'Saved Levels'];
-  }
-
-  _getGroupLength(config, groupIndex, baseGroupCount, savedEntries = []) {
-    if (this._isSavedGroupIndex(groupIndex, baseGroupCount, savedEntries)) {
-      return savedEntries.length;
-    }
-    return config?.level?.getGroupLength?.(groupIndex) ?? 0;
-  }
-
-  _normalizeSelection(config, savedEntries = []) {
-    const baseGroupCount = config?.level?.order?.length ??
-      this.gameResources?.getLevelGroups?.().length ?? 0;
-    const groupCount = this._getGroupCount(baseGroupCount, savedEntries);
-    if (groupCount <= 0) {
-      this.levelGroupIndex = 0;
-      this.levelIndex = 0;
-      return;
-    }
-    let groupIndex = Math.min(Math.max(this.levelGroupIndex, 0), groupCount - 1);
-    let levelIndex = Math.max(this.levelIndex, 0);
-    let groupLength = this._getGroupLength(
-      config,
-      groupIndex,
-      baseGroupCount,
-      savedEntries
-    );
-    if (groupLength <= 0) {
-      let found = false;
-      for (let i = 0; i < groupCount; i++) {
-        const length = this._getGroupLength(config, i, baseGroupCount, savedEntries);
-        if (length > 0) {
-          groupIndex = i;
-          levelIndex = 0;
-          found = true;
-          break;
-        }
-      }
-      if (!found) {
-        groupIndex = 0;
-        levelIndex = 0;
-      }
-    } else if (levelIndex >= groupLength) {
-      levelIndex = 0;
-    }
-    this.levelGroupIndex = groupIndex;
-    this.levelIndex = levelIndex;
-  }
-
-  async _syncLevelGroupSelect(savedEntries = []) {
-    if (!this.elementSelectLevelGroup || !this.gameResources) return;
-    const config = await this.gameFactory.getConfig(this.gameType);
-    const groups = this._getGroupNames(savedEntries);
-    this.arrayToSelect(this.elementSelectLevelGroup, this.prefixNumbers(groups));
-    this._normalizeSelection(config, savedEntries);
-    this.elementSelectLevelGroup.selectedIndex = this.levelGroupIndex;
-  }
-
-  getEntranceFocusX(level, stageImage) {
-    if (!level || !stageImage) return 0;
-    const entrance = level.entrances?.[0];
-    if (!entrance) return 0;
-    const scale = stageImage.viewPoint.scale || 1;
-    const viewW = stageImage.canvasViewportSize.width / scale;
-    if (!isFinite(viewW) || viewW <= 0) return 0;
-    const centerX = entrance.x + 24;
-    return Math.round(centerX - viewW / 2);
-  }
-
-  applyLevelViewport(level) {
-    if (!this.stage || !level) return;
-    const stageImage = this.stage.gameImgProps;
-    const rawX = Number.isFinite(level.screenPositionX) ? level.screenPositionX : 0;
-    const targetX = Number.isFinite(rawX) ? rawX : this.getEntranceFocusX(level, stageImage);
-    this.stage.applyViewport(
-      stageImage,
-      targetX,
-      0,
-      stageImage.viewPoint.scale
-    );
-    this.stage.redraw();
-  }
-  /** add array elements to a <select> */
-  arrayToSelect(htmlList, list) {
-    if (htmlList == null) {
-      return;
-    }
-    this.clearHtmlList(htmlList);
-    for (let i = 0; i < list.length; i++) {
-      const opt = list[i];
-      const el = document.createElement('option');
-      el.textContent = opt;
-      el.value = i.toString();
-      htmlList.appendChild(el);
-    }
-  }
-  /** fill the level select with the names for the current group */
-  async populateLevelSelect() {
-    if (!this.elementSelectLevel || !this.gameResources) return;
-    const config = await this.gameFactory.getConfig(this.gameType);
-    const savedEntries = this._getSavedLevelEntries();
-    const baseGroupCount = this.gameResources.getLevelGroups().length;
-    if (this._isSavedGroupIndex(this.levelGroupIndex, baseGroupCount, savedEntries)) {
-      const list = savedEntries.map((entry, index) => `${index + 1}: ${entry.name}`);
-      this.arrayToSelect(this.elementSelectLevel, list);
-      if (list.length) {
-        this.levelIndex = Math.min(this.levelIndex, list.length - 1);
-      } else {
-        this.levelIndex = 0;
-      }
-      this.elementSelectLevel.selectedIndex = this.levelIndex;
-      return;
-    }
-    const groupLength = this._getGroupLength(
-      config,
-      this.levelGroupIndex,
-      baseGroupCount,
-      savedEntries
-    );
-    const list = [];
-    for (let i = 0; i < groupLength; i++) {
-      try {
-        const lvl = await this.gameResources.getLevel(this.levelGroupIndex, i);
-        if (lvl) {
-          list.push((i + 1) + ': ' + lvl.name);
-          continue;
-        }
-      } catch (e) {
-        // keep slot alignment even if a level fails to load
-      }
-      list.push((i + 1) + ': [missing]');
-    }
-    this.arrayToSelect(this.elementSelectLevel, list);
-    if (list.length) {
-      this.levelIndex = Math.min(this.levelIndex, list.length - 1);
-    } else {
-      this.levelIndex = 0;
-    }
-    this.elementSelectLevel.selectedIndex = this.levelIndex;
-  }
-  /** switch the selected level group */
-  async selectLevelGroup(newLevelGroupIndex) {
-    if (!this.gameResources) return;
-    const savedEntries = this._getSavedLevelEntries();
-    const baseGroupCount = this.gameResources.getLevelGroups().length;
-    const max = Math.max(0, this._getGroupCount(baseGroupCount, savedEntries) - 1);
-    if (newLevelGroupIndex < 0) newLevelGroupIndex = 0;
-    else if (newLevelGroupIndex > max) newLevelGroupIndex = max;
-    this.levelGroupIndex = newLevelGroupIndex;
-    this.levelIndex = 0;
-    await this.populateLevelSelect();
-    if (this.autoExitEditorOnSelect && this.editorMode) {
-      this.exitEditorMode();
-    }
-    if (this.editorMode) {
-      await this.loadEditorLevelFromSelection();
-      return;
-    }
-    this.loadLevel();
-  }
-  /** switch the selected game type */
-  async selectGameType(newGameType) {
-    // dropdown values correspond to config array indices
-    if (this.configs && this.configs[newGameType]) {
-      newGameType = this.configs[newGameType].gametype;
-    }
-    this.gameType = newGameType;
-    this.levelGroupIndex = 0;
-    this.levelIndex = 0;
-    const newGameResources = await this.gameFactory.getGameResources(this.gameType);
-    this.gameResources = newGameResources;
-    const savedEntries = this._getSavedLevelEntries();
-    await this._syncLevelGroupSelect(savedEntries);
-    await this.populateLevelSelect();
-    if (this.autoExitEditorOnSelect && this.editorMode) {
-      this.exitEditorMode();
-    }
-    if (this.editorMode) {
-      await this.loadEditorLevelFromSelection();
-      return;
-    }
-    this.loadLevel();
-  }
-  /** select a specific level */
-  async selectLevel(newLevelIndex) {
-    this.levelIndex = newLevelIndex;
-    if (this.autoExitEditorOnSelect && this.editorMode) {
-      this.exitEditorMode();
-    }
-    if (this.editorMode) {
-      await this.loadEditorLevelFromSelection();
-      return;
-    }
-    this.loadLevel();
-  }
-  /** select a game type */
-  async setup() {
-    this.applyQuery();
-    if (!this._midiMapping) {
-      this._midiMapping = await this._loadMidiMapping();
-      if (typeof globalThis !== 'undefined' && globalThis.lemmingsMidiOverrides) {
-        this.applyMidiOverrides(globalThis.lemmingsMidiOverrides);
-      }
-    }
-    this.configs = await this.gameFactory.configReader.configs;
-    this.arrayToSelect(this.elementSelectGameType, this.configs.map(c => c.name));
-    const typeIndex = this.configs.findIndex(c => c.gametype === this.gameType);
-    if (typeIndex >= 0 && this.elementSelectGameType)
-      this.elementSelectGameType.selectedIndex = typeIndex;
-    const newGameResources = await this.gameFactory.getGameResources(this.gameType);
-    this.gameResources = newGameResources;
-    const savedEntries = this._getSavedLevelEntries();
-    await this._syncLevelGroupSelect(savedEntries);
-    const populatePromise = this.populateLevelSelect();
-    await this.loadLevel();
-    await populatePromise;
-    if (this.benchSequence) {
-      await this.benchSequenceStart();
-    }
-  }
-
-  async setupEditor() {
-    this.applyQuery();
-    this.configs = await this.gameFactory.configReader.configs;
-    this.arrayToSelect(this.elementSelectGameType, this.configs.map(c => c.name));
-    const typeIndex = this.configs.findIndex(c => c.gametype === this.gameType);
-    if (typeIndex >= 0 && this.elementSelectGameType)
-      this.elementSelectGameType.selectedIndex = typeIndex;
-    const newGameResources = await this.gameFactory.getGameResources(this.gameType);
-    this.gameResources = newGameResources;
-    const savedEntries = this._getSavedLevelEntries();
-    await this._syncLevelGroupSelect(savedEntries);
-    await this.populateLevelSelect();
-  }
-  /** load a level and render it to the display */
-  async loadLevel() {
-    if (this.autoMoveTimer !== null) {
-      window.clearTimeout(this.autoMoveTimer);
-      this.autoMoveTimer = null;
-    }
-    if (!this.gameResources) return;
-    const savedEntries = this._getSavedLevelEntries();
-    const baseGroupCount = this.gameResources.getLevelGroups().length;
-    if (this._isSavedGroupIndex(this.levelGroupIndex, baseGroupCount, savedEntries)) {
-      return this.loadSavedLevelFromSelection(savedEntries);
-    }
-    if (this.game) {
-      this.midiRouter?.detach?.();
-      this.game.stop();
-      this.game = null;
-    }
-    const gameStateTypes = getGameStateTypes();
-    this.changeHtmlText(this.elementGameState, gameStateTypes[gameStateTypes.UNKNOWN]);
-    const level = await this.gameResources.getLevel(this.levelGroupIndex, this.levelIndex);
-    if (!level) return;
-    if (this.elementSelectGameType && this.configs) {
-      const idx = this.configs.findIndex(c => c.gametype === this.gameType);
-      if (idx >= 0) this.elementSelectGameType.selectedIndex = idx;
-    }
-    if (this.elementSelectLevelGroup) this.elementSelectLevelGroup.selectedIndex = this.levelGroupIndex;
-    if (this.elementSelectLevel) this.elementSelectLevel.selectedIndex = this.levelIndex;
-    if (this.stage) {
-      const gameDisplay = this.stage.getGameDisplay();
-      gameDisplay.clear();
-      this.stage.resetFade();
-      level.render(gameDisplay);
-      this.stage.updateStageSize();
-      this.applyLevelViewport(level);
-    }
-    this.updateQuery();
-    this.log.debug(level);
-    return this.start();
-  }
-
-  async benchStart(entrances) {
-    this.bench = true;
-    this._benchMeasureExtras = false;
-    await this.loadLevel();
-    const level = this.game.level;
-    if (this.stage) {
-      this.applyLevelViewport(level);
-    }
-    const cfg = this.configs?.find(c => c.gametype === this.gameType);
-    const pack = cfg?.name || this.gameType;
-    const savedEntries = this._getSavedLevelEntries();
-    const group = this._getGroupNames(savedEntries)[this.levelGroupIndex];
-    const lvlName = level.name ? level.name.trim() : '';
-    console.log(`starting bench series for ${lvlName} in ${group} in ${pack}, adding ${entrances} entrances with ${this.extraLemmings} extra lemmings`);
-
-    if (!this._benchBaseEntrances) {
-      this._benchBaseEntrances = level.entrances.slice();
-    }
-    level.entrances.length = 0;
-    const baseEntrances = this._benchBaseEntrances;
-    const groundMask = level.getGroundMaskLayer();
-    const triggerTypes = getTriggerTypes();
-    const badTriggers = new Set([
-      triggerTypes.DROWN,
-      triggerTypes.FRYING,
-      triggerTypes.KILL,
-      triggerTypes.TRAP,
-    ]);
-
-    const increments = [100, 50, 25, 12, 6];
-    const SEGMENT_DURATION = 60;
-    const ENTRANCE_HEIGHT = 28;
-    const SPAWN_OFFSET_Y = 14;
-    const SAFE_ENTRANCE_DROP = getLemmingCtor().LEM_MAX_FALLING - SPAWN_OFFSET_Y;
-
-    const clearHeight = (x, y) => {
-      if (y < 0 || y + ENTRANCE_HEIGHT > level.height) return false;
-      for (let i = 0; i < ENTRANCE_HEIGHT; i++) {
-        if (groundMask.hasGroundAt(x, y + i)) return false;
-      }
-      return true;
-    };
-
-    const findOpenSegment = x => {
-      let best = null;
-      let y = 0;
-      while (y < level.height) {
-        while (y < level.height && groundMask.hasGroundAt(x, y)) y++;
-        const start = y;
-        while (y < level.height && !groundMask.hasGroundAt(x, y)) y++;
-        const end = y;
-        if (end >= level.height) break;
-        const h = end - start;
-        if (h >= ENTRANCE_HEIGHT + 15 && (!best || h > best.height)) {
-          best = { top: start, bottom: end, height: h };
-        }
-        y++; // skip ground
-      }
-      return best;
-    };
-
-    const trySpawn = spawnX => {
-      if (spawnX < 0 || spawnX >= level.width) return false;
-      const seg = findOpenSegment(spawnX);
-      if (!seg) return false;
-      const drop = Math.min(seg.height - ENTRANCE_HEIGHT, SAFE_ENTRANCE_DROP);
-      if (drop < 15) return false;
-      const entY = seg.bottom - ENTRANCE_HEIGHT - drop;
-      if (!clearHeight(spawnX, entY)) return false;
-
-      for (const tr of level.triggers) {
-        if (!badTriggers.has(tr.type)) continue;
-        if (spawnX < tr.x1 || spawnX > tr.x2) continue;
-        // disallow if entrance intersects or is above a deadly trigger
-        if (entY + ENTRANCE_HEIGHT > tr.y1 && entY < tr.y2) return false;
-        if (entY + ENTRANCE_HEIGHT <= tr.y1 && seg.bottom >= tr.y1) return false;
-      }
-
-      const entX = spawnX - 24;
-      if (entX < 0 || entX >= level.width || entY < 0 || entY >= level.height) return false;
-
-      for (const ent of level.entrances) {
-        if (ent.x === entX && ent.y === entY) return false;
-      }
-
-      level.entrances.push({ x: entX, y: entY });
-      return true;
-    };
-
-    if (!this._benchEntrancePool) {
-      level.entrances = baseEntrances.slice();
-      const target = Math.max(...this._benchCounts);
-      for (const step of increments) {
-        let offset = 0;
-        while (level.entrances.length < target && offset <= level.width) {
-          for (const base of baseEntrances) {
-            if (level.entrances.length >= target) break;
-            const center = base.x + 24;
-            if (offset === 0) {
-              trySpawn(center);
-              continue;
-            }
-            trySpawn(center + offset);
-            if (level.entrances.length >= target) break;
-            trySpawn(center - offset);
-          }
-          offset += step;
-        }
-        if (level.entrances.length >= target) break;
-      }
-      this._benchEntrancePool = level.entrances.slice();
-    } else {
-      level.entrances = this._benchEntrancePool.slice();
-    }
-    if (entrances > level.entrances.length) {
-      entrances = level.entrances.length;
-    }
-    level.entrances.length = entrances;
-    if (this.game.getLemmingManager) {
-      const lm = this.game.getLemmingManager();
-      if (lm) lm.spawnCount = entrances;
-    }
-    const timer = this.game.getGameTimer();
-    timer.speedFactor = 6;
-    timer.benchStartupFrames = 120;
-    timer.benchStableFactor = 8;
-    this._benchStartTime = timer.getGameTime();
-    if (this.benchSequence) {
-      if (this._benchMonitor) timer.eachGameSecond.off(this._benchMonitor);
-      if (this._benchSpeedTrack) timer.eachGameSecond.off(this._benchSpeedTrack);
-      this._benchMaxSpeed = timer.speedFactor;
-      this._benchSpeedTrack = () => {
-        if (timer.speedFactor > this._benchMaxSpeed) this._benchMaxSpeed = timer.speedFactor;
-      };
-      timer.eachGameSecond.on(this._benchSpeedTrack);
-      this._benchMonitor = async () => {
-        if (timer.speedFactor < 1 ||
-              timer.getGameTime() - this._benchStartTime >= SEGMENT_DURATION) {
-          timer.eachGameSecond.off(this._benchMonitor);
-          timer.eachGameSecond.off(this._benchSpeedTrack);
-          timer.suspend();
-          const count = this.game.getLemmingManager().getLemmings().length;
-          const tps = (this._benchMaxSpeed * (1000 / timer.TIME_PER_FRAME_MS)).toFixed(1);
-          console.log(`series finished for ${entrances} entrances - ${count} lemmings - ${this._benchMaxSpeed.toFixed(1)} highest speed achieved (${tps} ticks per second)`);
-          this._benchIndex++;
-          if (this._benchIndex >= this._benchCounts.length) {
-            this._benchIndex = 0;
-            if (this._benchExtraList && ++this._benchExtraIndex < this._benchExtraList.length) {
-              this.extraLemmings = this._benchExtraList[this._benchExtraIndex];
-              lemmings.extraLemmings = this.extraLemmings;
-            } else if (this._benchExtraList) {
-              return;
-            }
-          }
-          await this.benchStart(this._benchCounts[this._benchIndex]);
-        }
-      };
-      timer.eachGameSecond.on(this._benchMonitor);
-    }
-  }
-
-  async benchMeasureExtras() {
-    this.bench = true;
-    this._benchMeasureExtras = true;
-    await this.loadLevel();
-    const lm = this.game.getLemmingManager();
-    if (lm) lm.spawnCount = this.game.level.entrances.length;
-    const vc = this.game.getVictoryCondition();
-    if (vc) vc.releaseRate = vc.getMinReleaseRate();
-    const timer = this.game.getGameTimer();
-    timer.speedFactor = 10;
-    timer.benchStartupFrames = 120;
-    timer.benchStableFactor = 2;
-    let extras = 0;
-    let prev = lm.spawnTotal;
-    let spawned = 0;
-    return new Promise(resolve => {
-      const monitor = () => {
-        const delta = lm.spawnTotal - prev;
-        prev = lm.spawnTotal;
-        spawned += delta / (extras + 1);
-        while (spawned >= 10) {
-          spawned -= 1;
-          extras += 1;
-          this.extraLemmings = extras;
-          lemmings.extraLemmings = extras;
-        }
-        if (timer.speedFactor < 1 || timer.getGameTime() >= 120) {
-          timer.eachGameSecond.off(monitor);
-          timer.suspend();
-          this._benchMeasureExtras = false;
-          console.log(`extra lemmings threshold reached at ${extras}`);
-          resolve(extras);
-        }
-      };
-      timer.eachGameSecond.on(monitor);
-    });
-  }
-
-  async benchSequenceStart() {
-    this._benchCounts = [50, 25, 10, 1];
-    this._benchIndex = 0;
-    const extras = await this.benchMeasureExtras();
-    this._benchExtraList = [extras, Math.floor(extras / 2), 0];
-    this._benchExtraIndex = 0;
-    this._benchBaseEntrances = null;
-    this._benchEntrancePool = null;
-    this.extraLemmings = this._benchExtraList[0];
-    lemmings.extraLemmings = this.extraLemmings;
-    await this.benchStart(this._benchCounts[0]);
-  }
-
-  ensureEditorSession() {
-    if (!this.editorSession) {
-      this.editorSession = new EditorSession();
-    }
-    return this.editorSession;
-  }
-
-  enterEditorMode() {
-    if (this.editorMode) return;
-    this.editorMode = true;
-    this.editorPlaytest = false;
-    const timer = this.game?.getGameTimer?.();
-    this._editorWasRunning = !!timer?.isRunning?.();
-    timer?.suspend?.();
-    if (this.stage) {
-      this._editorPanWasEnabled = this.stage.panEnabled !== false;
-      this.stage.panEnabled = false;
-    }
-    if (this.game) {
-      this._editorInputWasEnabled = this.game.inputEnabled !== false;
-      this.game.inputEnabled = false;
-    }
-    if (!this.editorSession) {
-      this.editorSession = new EditorSession();
-      this.editorSession.createBlank();
-    }
-  }
-
-  exitEditorMode() {
-    if (!this.editorMode) return;
-    this.editorMode = false;
-    this.editorPlaytest = false;
-    const timer = this.game?.getGameTimer?.();
-    if (this._editorWasRunning) {
-      timer?.continue?.();
-    }
-    this._editorWasRunning = false;
-    if (this.stage) {
-      this.stage.panEnabled = this._editorPanWasEnabled !== false;
-    }
-    if (this.game) {
-      this.game.inputEnabled = this._editorInputWasEnabled !== false;
-    }
-  }
-
-  toggleEditorMode() {
-    if (this.editorMode) {
-      this.exitEditorMode();
-    } else {
-      this.enterEditorMode();
-    }
-  }
-
-  setEditorPlaytest(enabled) {
-    this.editorPlaytest = !!enabled;
-    if (!this.editorMode) return;
-    const timer = this.game?.getGameTimer?.();
-    if (this.editorPlaytest) {
-      timer?.continue?.();
-    } else {
-      timer?.suspend?.();
-    }
-    if (this.game) {
-      this.game.inputEnabled = this.editorPlaytest;
-    }
-    if (this.stage) {
-      this.stage.panEnabled = this.editorPlaytest;
-    }
-  }
-
-  createBlankEditorLevel(options = {}) {
-    this.enterEditorMode();
-    const level = this.editorSession.createBlank(options);
-    if (options.render !== false) {
-      this.loadEditorPreviewLevel({ suspend: true });
-    }
-    return level;
-  }
-
-  loadEditorLevelFromText(text, options = {}) {
-    this.enterEditorMode();
-    const level = this.editorSession.loadFromText(text);
-    if (options.render !== false) {
-      this.loadEditorPreviewLevel({ suspend: true });
-    }
-    return level;
-  }
-
-  getEditorLevelText() {
-    const session = this.ensureEditorSession();
-    return session.toText();
-  }
-
-  getEditorLevelTitle() {
-    const session = this.ensureEditorSession();
-    return session.getTitle();
-  }
-
-  async _startWithLevel(level) {
-    if (!this.gameFactory) return;
-    if (this.game != null) {
-      this.continue();
-      return;
-    }
-    const baseResources = this.gameResources;
-    if (!baseResources) return;
-    const editorResources = Object.create(baseResources);
-    editorResources.getLevel = async () => level;
-    try {
-      const game = await this.gameFactory.getGame(this.gameType, editorResources);
-      await game.loadLevel(this.levelGroupIndex, this.levelIndex);
-      game.setGameDisplay(this.stage.getGameDisplay());
-      game.setGuiDisplay(this.stage.getGuiDisplay());
-      if (this.stage && game.level) {
-        const preserveViewport = this._preserveEditorViewport === true;
-        if (!preserveViewport) {
-          this.applyLevelViewport(game.level);
-        }
-        this._preserveEditorViewport = false;
-      }
-      game.getGameTimer().speedFactor = this.gameSpeedFactor;
-      this.stage.setCursorSprite(createCrosshairFrame(24));
-      if (this.midiEnabled) {
-        await this.initMidiRouting();
-        this.midiRouter?.attach(game.soundEvents, { game, stage: this.stage });
-      }
-      game.start();
-      const gameStateTypes = getGameStateTypes();
-      this.changeHtmlText(this.elementGameState, gameStateTypes.toString(gameStateTypes.RUNNING));
-      game.onGameEnd.on(state => this.onGameEnd(state));
-      this.game = game;
-      if (this.cheatEnabled) this.game.cheat();
-      if (this.debug) this.game.showDebug = true;
-    } catch (e) {
-      this.log.log('Error starting custom level:', e);
-    }
-  }
-
-  async loadEditorPreviewLevel(options = {}) {
-    if (this.autoMoveTimer !== null) {
-      window.clearTimeout(this.autoMoveTimer);
-      this.autoMoveTimer = null;
-    }
-    if (!this.editorSession?.level || !this.gameFactory) return null;
-    const config = this.gameResources?.config || await this.gameFactory.getConfig(this.gameType);
-    if (!config) return null;
-    if (this.game) {
-      this.midiRouter?.detach?.();
-      this.game.stop();
-      this.game = null;
-    }
-    const gameStateTypes = getGameStateTypes();
-    this.changeHtmlText(this.elementGameState, gameStateTypes[gameStateTypes.UNKNOWN]);
-    const level = await loadEditorLevel(
-      this.editorSession.level,
-      config,
-      this.gameFactory.fileProvider,
-      {
-        levelGroupIndex: this.levelGroupIndex,
-        levelIndex: this.levelIndex
-      }
-    );
-    if (!level) return null;
-    if (this.elementSelectGameType && this.configs) {
-      const idx = this.configs.findIndex(c => c.gametype === this.gameType);
-      if (idx >= 0) this.elementSelectGameType.selectedIndex = idx;
-    }
-    if (this.elementSelectLevelGroup) this.elementSelectLevelGroup.selectedIndex = this.levelGroupIndex;
-    if (this.elementSelectLevel) this.elementSelectLevel.selectedIndex = this.levelIndex;
-    const preserveView = options.preserveView === true;
-    const prevViewport = preserveView && this.stage
-      ? {
-        x: this.stage.gameImgProps.viewPoint.x,
-        y: this.stage.gameImgProps.viewPoint.y,
-        scale: this.stage.gameImgProps.viewPoint.scale
-      }
-      : null;
-    this._preserveEditorViewport = !!prevViewport;
-
-    if (this.stage) {
-      const gameDisplay = this.stage.getGameDisplay();
-      gameDisplay.clear();
-      this.stage.resetFade();
-      level.render(gameDisplay);
-      this.stage.updateStageSize();
-      if (prevViewport) {
-        this.stage.applyViewport(
-          this.stage.gameImgProps,
-          prevViewport.x,
-          prevViewport.y,
-          prevViewport.scale
-        );
-        this.stage.redraw();
-      } else {
-        this.applyLevelViewport(level);
-      }
-    }
-    this.updateQuery();
-    this.log.debug(level);
-    await this._startWithLevel(level);
-    if (prevViewport && this.stage) {
-      this.stage.applyViewport(
-        this.stage.gameImgProps,
-        prevViewport.x,
-        prevViewport.y,
-        prevViewport.scale
-      );
-      this.stage.redraw();
-    }
-    this._preserveEditorViewport = false;
-    if (this.editorMode && this.game) {
-      this.game.inputEnabled = this.editorPlaytest;
-    } else if (this.game) {
-      this.game.inputEnabled = true;
-    }
-    if (this.editorMode && this.stage) {
-      this.stage.panEnabled = this.editorPlaytest;
-    } else if (this.stage) {
-      this.stage.panEnabled = true;
-    }
-    const timer = this.game?.getGameTimer?.();
-    if (options.suspend !== false && !this.editorPlaytest) {
-      timer?.suspend?.();
-    } else if (this.editorPlaytest) {
-      timer?.continue?.();
-    }
-    return level;
-  }
-
-  async loadSavedLevelFromSelection(savedEntries = null) {
-    if (!this.gameResources || !this.gameFactory) return null;
-    const entries = savedEntries ?? this._getSavedLevelEntries();
-    if (!entries.length) return null;
-    if (this.levelIndex < 0) this.levelIndex = 0;
-    if (this.levelIndex >= entries.length) {
-      this.levelIndex = entries.length - 1;
-    }
-    const entry = entries[this.levelIndex];
-    if (!entry) return null;
-    const text = loadSavedLevel(undefined, entry.id);
-    if (!text) return null;
-    if (this.autoExitEditorOnSelect && this.editorMode) {
-      this.exitEditorMode();
-    }
-    const session = this.ensureEditorSession();
-    session.loadFromText(text);
-    return this.loadEditorPreviewLevel({ suspend: false });
-  }
-
-  async refreshSavedLevels() {
-    if (!this.includeSavedLevels || !this.gameResources) return;
-    const savedEntries = this._getSavedLevelEntries();
-    await this._syncLevelGroupSelect(savedEntries);
-    await this.populateLevelSelect();
-    const baseGroupCount = this.gameResources.getLevelGroups().length;
-    if (!this.editorMode &&
-        this._isSavedGroupIndex(this.levelGroupIndex, baseGroupCount, savedEntries)) {
-      await this.loadSavedLevelFromSelection(savedEntries);
-    }
-  }
-  async _loadClassicLevelReader(gameType, levelGroupIndex, levelIndex) {
-    const provider = this.gameFactory?.fileProvider;
-    if (!provider) return null;
-    const config = await this.gameFactory.getConfig(gameType);
-    if (!config) return null;
-    const resolver = new LevelIndexResolve(config);
-    const levelInfo = resolver.resolve(levelGroupIndex, levelIndex);
-    if (!levelInfo) return null;
-    const paddedFileId = ('0000' + levelInfo.fileId).slice(-3);
-    const levelDat = await provider.loadBinary(
-      config.path,
-      config.level.filePrefix + paddedFileId + '.DAT'
-    );
-    const levelsContainer = new FileContainer(levelDat);
-    return new LevelReader(levelsContainer.getPart(levelInfo.partIndex));
-  }
-
-  async loadEditorLevelFromSelection(options = {}) {
-    this.enterEditorMode();
-    const reader = await this._loadClassicLevelReader(
-      this.gameType,
-      this.levelGroupIndex,
-      this.levelIndex
-    );
-    if (!reader) return null;
-    const editorLevel = createEditorLevelFromClassic(reader, options);
-    this.editorSession.level = editorLevel;
-    if (options.render !== false) {
-      await this.loadEditorPreviewLevel({ suspend: true });
-    }
-    return editorLevel;
-  }
-
-  /** cleanup keyboard and stage handlers */
-  dispose() {
-    if (this.shortcuts) {
-      this.shortcuts.dispose();
-      this.shortcuts = null;
-    }
-    if (this.midiRouter) {
-      this.midiRouter.dispose();
-      this.midiRouter = null;
-    }
-    if (this.stage && this.stage.dispose) {
-      window.removeEventListener('resize', this._stageResize);
-      window.removeEventListener('orientationchange', this._stageResize);
-      this.stage.dispose();
-      this.stage = null;
-    }
-  }
-}
-
-export { GameView };
+export { GameView } from './game-view/GameViewCore.js';
diff --git a/js/game/HistoryStore.js b/js/game/HistoryStore.js
index 19dbf04d..fe516d71 100644
--- a/js/game/HistoryStore.js
+++ b/js/game/HistoryStore.js
@@ -1,1596 +1,2 @@
-import { SkillTypes } from './SkillTypes.js';
-import { Trigger } from '../level/Trigger.js';
-
-const DEFAULT_OPTIONS = Object.freeze({
-  keyframeInterval: 120,
-  preserveFutureHistory: false,
-  enableHistoryCap: false,
-  historyCapTicks: 0,
-  historyWarnTicks: 0,
-  deltaPoolLimit: 64
-});
-
-const createLemmingState = (size) => ({
-  capacity: size,
-  present: new Uint8Array(size),
-  x: new Int32Array(size),
-  y: new Int32Array(size),
-  lookRight: new Uint8Array(size),
-  frameIndex: new Int32Array(size),
-  state: new Int32Array(size),
-  canClimb: new Uint8Array(size),
-  hasParachute: new Uint8Array(size),
-  removed: new Uint8Array(size),
-  disabled: new Uint8Array(size),
-  countdown: new Int32Array(size),
-  hasExploded: new Uint8Array(size),
-  lastTriggerType: new Int32Array(size),
-  actionType: new Int32Array(size),
-  countdownActive: new Uint8Array(size)
-});
-
-const cloneLemmingState = (state, length) => {
-  const size = length ?? state.capacity;
-  const copy = createLemmingState(size);
-  copy.present.set(state.present.subarray(0, size));
-  copy.x.set(state.x.subarray(0, size));
-  copy.y.set(state.y.subarray(0, size));
-  copy.lookRight.set(state.lookRight.subarray(0, size));
-  copy.frameIndex.set(state.frameIndex.subarray(0, size));
-  copy.state.set(state.state.subarray(0, size));
-  copy.canClimb.set(state.canClimb.subarray(0, size));
-  copy.hasParachute.set(state.hasParachute.subarray(0, size));
-  copy.removed.set(state.removed.subarray(0, size));
-  copy.disabled.set(state.disabled.subarray(0, size));
-  copy.countdown.set(state.countdown.subarray(0, size));
-  copy.hasExploded.set(state.hasExploded.subarray(0, size));
-  copy.lastTriggerType.set(state.lastTriggerType.subarray(0, size));
-  copy.actionType.set(state.actionType.subarray(0, size));
-  copy.countdownActive.set(state.countdownActive.subarray(0, size));
-  return copy;
-};
-
-const ensureLemmingCapacity = (state, size) => {
-  if (state.capacity >= size) return state;
-  const next = Math.max(size, state.capacity * 2, 1);
-  const grown = createLemmingState(next);
-  grown.present.set(state.present);
-  grown.x.set(state.x);
-  grown.y.set(state.y);
-  grown.lookRight.set(state.lookRight);
-  grown.frameIndex.set(state.frameIndex);
-  grown.state.set(state.state);
-  grown.canClimb.set(state.canClimb);
-  grown.hasParachute.set(state.hasParachute);
-  grown.removed.set(state.removed);
-  grown.disabled.set(state.disabled);
-  grown.countdown.set(state.countdown);
-  grown.hasExploded.set(state.hasExploded);
-  grown.lastTriggerType.set(state.lastTriggerType);
-  grown.actionType.set(state.actionType);
-  grown.countdownActive.set(state.countdownActive);
-  return grown;
-};
-
-const snapshotLemming = (lem, actionType, countdownActive) => ({
-  id: lem.id,
-  x: lem.x,
-  y: lem.y,
-  lookRight: lem.lookRight ? 1 : 0,
-  frameIndex: lem.frameIndex,
-  state: lem.state ?? 0,
-  canClimb: lem.canClimb ? 1 : 0,
-  hasParachute: lem.hasParachute ? 1 : 0,
-  removed: lem.removed ? 1 : 0,
-  disabled: lem.disabled ? 1 : 0,
-  countdown: lem.countdown ?? 0,
-  hasExploded: lem.hasExploded ? 1 : 0,
-  lastTriggerType: Number.isFinite(lem.lastTriggerType) ? lem.lastTriggerType : -1,
-  actionType: Number.isFinite(actionType) ? actionType : -1,
-  countdownActive: countdownActive ? 1 : 0
-});
-
-const applyLemmingSnapshot = (lem, snapshot, action, countdownAction) => {
-  lem.id = snapshot.id;
-  lem.x = snapshot.x;
-  lem.y = snapshot.y;
-  lem.lookRight = !!snapshot.lookRight;
-  lem.frameIndex = snapshot.frameIndex;
-  lem.state = snapshot.state;
-  lem.canClimb = !!snapshot.canClimb;
-  lem.hasParachute = !!snapshot.hasParachute;
-  lem.removed = !!snapshot.removed;
-  lem.disabled = !!snapshot.disabled;
-  lem.countdown = snapshot.countdown;
-  lem.hasExploded = !!snapshot.hasExploded;
-  lem.lastTriggerType = snapshot.lastTriggerType >= 0 ? snapshot.lastTriggerType : null;
-  lem.action = action || null;
-  lem.countdownAction = snapshot.countdownActive ? countdownAction : null;
-};
-
-const createDelta = (tick) => ({
-  tick,
-  lemChanges: { ids: [], fields: [], prev: [], next: [] },
-  lemAdded: [],
-  lemRemoved: [],
-  lemmingManagerChanges: null,
-  groundChanges: {
-    indices: [],
-    spans: null,
-    prevMask: [],
-    prevR: [],
-    prevG: [],
-    prevB: [],
-    nextMask: [],
-    nextR: [],
-    nextG: [],
-    nextB: []
-  },
-  entranceChanges: { indices: [], prev: [], next: [] },
-  triggerCooldownChanges: { ids: [], prev: [], next: [] },
-  triggerAdd: [],
-  triggerRemove: [],
-  objectAnimChanges: { ids: [], prevFirst: [], prevFinished: [], nextFirst: [], nextFinished: [] },
-  victoryChanges: null,
-  skillsChanges: null,
-  timerChanges: null,
-  gameChanges: null,
-  soundEvents: [],
-  minimapDeaths: []
-});
-
-class HistoryStore {
-  constructor(options = {}) {
-    this.options = { ...DEFAULT_OPTIONS, ...options };
-    this.keyframes = [];
-    this.keyframeTicks = [];
-    this.deltas = [];
-    this.minDeltaTick = null;
-    this.maxDeltaTick = null;
-    this.minKeyframeTick = null;
-    this.maxKeyframeTick = null;
-    this.deltaCount = 0;
-    this.keyframeCount = 0;
-    this._deltaPool = [];
-    this._historyWarned = false;
-    this._recording = false;
-    this._currentTick = null;
-    this._currentDelta = null;
-    this._lemmingState = createLemmingState(0);
-    this._lemmingManagerState = null;
-    this._entranceOpened = new Uint8Array(0);
-    this._skillsState = null;
-    this._victoryState = null;
-    this._timerState = null;
-    this._gameState = null;
-    this._nextTriggerId = 1;
-    this._triggerIds = new Map();
-    this._triggerById = new Map();
-    this._nextObjectId = 1;
-    this._objectIds = new Map();
-    this._objectById = new Map();
-    this.game = null;
-    this.timer = null;
-    this._beforeTick = null;
-    this._afterTick = null;
-    this._groundDirty = true;
-    this._lastKeyframe = null;
-  }
-
-  setPreserveFutureHistory(enabled) {
-    this.options.preserveFutureHistory = !!enabled;
-  }
-
-  getDelta(tickIndex) {
-    if (!Number.isFinite(tickIndex)) return null;
-    return this.deltas[Math.trunc(tickIndex)] || null;
-  }
-
-  getKeyframe(tickIndex) {
-    if (!Number.isFinite(tickIndex)) return null;
-    return this.keyframes[Math.trunc(tickIndex)] || null;
-  }
-
-  getHistoryStats() {
-    const min = this.minDeltaTick;
-    const max = this.maxDeltaTick;
-    const span = (min == null || max == null) ? 0 : (max - min + 1);
-    return {
-      minTick: min,
-      maxTick: max,
-      deltaCount: this.deltaCount,
-      keyframeCount: this.keyframeCount,
-      spanTicks: span
-    };
-  }
-
-  _allocDelta(tickIndex) {
-    const tick = Math.trunc(tickIndex);
-    const delta = this._deltaPool.pop();
-    if (!delta) return createDelta(tick);
-    this._resetDelta(delta, tick);
-    return delta;
-  }
-
-  _resetDelta(delta, tickIndex) {
-    delta.tick = Math.trunc(tickIndex);
-    delta.lemChanges.ids.length = 0;
-    delta.lemChanges.fields.length = 0;
-    delta.lemChanges.prev.length = 0;
-    delta.lemChanges.next.length = 0;
-    delta.lemAdded.length = 0;
-    delta.lemRemoved.length = 0;
-    delta.lemmingManagerChanges = null;
-    delta.groundChanges.indices.length = 0;
-    delta.groundChanges.spans = null;
-    delta.groundChanges.prevMask.length = 0;
-    delta.groundChanges.prevR.length = 0;
-    delta.groundChanges.prevG.length = 0;
-    delta.groundChanges.prevB.length = 0;
-    delta.groundChanges.nextMask.length = 0;
-    delta.groundChanges.nextR.length = 0;
-    delta.groundChanges.nextG.length = 0;
-    delta.groundChanges.nextB.length = 0;
-    delta.entranceChanges.indices.length = 0;
-    delta.entranceChanges.prev.length = 0;
-    delta.entranceChanges.next.length = 0;
-    delta.triggerCooldownChanges.ids.length = 0;
-    delta.triggerCooldownChanges.prev.length = 0;
-    delta.triggerCooldownChanges.next.length = 0;
-    delta.triggerAdd.length = 0;
-    delta.triggerRemove.length = 0;
-    delta.objectAnimChanges.ids.length = 0;
-    delta.objectAnimChanges.prevFirst.length = 0;
-    delta.objectAnimChanges.prevFinished.length = 0;
-    delta.objectAnimChanges.nextFirst.length = 0;
-    delta.objectAnimChanges.nextFinished.length = 0;
-    delta.victoryChanges = null;
-    delta.skillsChanges = null;
-    delta.timerChanges = null;
-    delta.gameChanges = null;
-    delta.soundEvents.length = 0;
-    delta.minimapDeaths.length = 0;
-  }
-
-  _releaseDelta(delta) {
-    if (!delta) return;
-    const limit = this.options.deltaPoolLimit ?? DEFAULT_OPTIONS.deltaPoolLimit;
-    if (this._deltaPool.length >= limit) return;
-    this._resetDelta(delta, 0);
-    this._deltaPool.push(delta);
-  }
-
-  attach(game, { captureBaseline = true } = {}) {
-    if (!game) return;
-    this.game = game;
-    this.timer = game.getGameTimer?.() || null;
-    this._bindTimer();
-    if (captureBaseline) {
-      this.start();
-    }
-  }
-
-  detach() {
-    if (this.timer?.onBeforeGameTick && this._beforeTick) {
-      this.timer.onBeforeGameTick.off(this._beforeTick);
-    }
-    if (this.timer?.onGameTick && this._afterTick) {
-      this.timer.onGameTick.off(this._afterTick);
-    }
-    this._beforeTick = null;
-    this._afterTick = null;
-    this._recording = false;
-    this.game = null;
-    this.timer = null;
-  }
-
-  start() {
-    if (!this.game) return;
-    this.captureBaseline(this.game);
-    this._recording = true;
-    const tickIndex = this.timer?.tickIndex ?? 0;
-    if (!this.keyframes[tickIndex]) {
-      this._setKeyframe(tickIndex, this._captureKeyframe(this.game, tickIndex));
-    }
-  }
-
-  pause() {
-    this._recording = false;
-    this._currentDelta = null;
-    this._currentTick = null;
-  }
-
-  resume() {
-    if (!this.game) return;
-    this.captureBaseline(this.game);
-    this._groundDirty = true;
-    this._recording = true;
-  }
-
-  getKeyframeAtOrBefore(tickIndex) {
-    if (!Number.isFinite(tickIndex)) return null;
-    const ticks = this.keyframeTicks;
-    if (!ticks.length) return null;
-    const target = Math.max(0, Math.trunc(tickIndex));
-    if (target < ticks[0]) return null;
-    let lo = 0;
-    let hi = ticks.length - 1;
-    while (lo <= hi) {
-      const mid = (lo + hi) >> 1;
-      if (ticks[mid] <= target) {
-        lo = mid + 1;
-      } else {
-        hi = mid - 1;
-      }
-    }
-    const tick = ticks[Math.max(0, hi)];
-    return this.keyframes[tick] || null;
-  }
-
-  truncateAfter(tickIndex) {
-    if (!Number.isFinite(tickIndex)) return;
-    if (this.options.preserveFutureHistory) return;
-    const cutoff = Math.max(0, Math.trunc(tickIndex));
-    this._truncateDeltasAfter(cutoff);
-    this._truncateKeyframesAfter(cutoff);
-  }
-
-  _setDelta(tickIndex, delta) {
-    const tick = Math.trunc(tickIndex);
-    if (!this.deltas[tick]) {
-      this.deltaCount += 1;
-    }
-    this.deltas[tick] = delta;
-    if (this.minDeltaTick == null || tick < this.minDeltaTick) {
-      this.minDeltaTick = tick;
-    }
-    if (this.maxDeltaTick == null || tick > this.maxDeltaTick) {
-      this.maxDeltaTick = tick;
-    }
-  }
-
-  _setKeyframe(tickIndex, keyframe) {
-    const tick = Math.trunc(tickIndex);
-    if (!this.keyframes[tick]) {
-      this.keyframeCount += 1;
-      this._insertKeyframeTick(tick);
-    }
-    this.keyframes[tick] = keyframe;
-    this._lastKeyframe = keyframe;
-    if (this.minKeyframeTick == null || tick < this.minKeyframeTick) {
-      this.minKeyframeTick = tick;
-    }
-    if (this.maxKeyframeTick == null || tick > this.maxKeyframeTick) {
-      this.maxKeyframeTick = tick;
-    }
-  }
-
-  _insertKeyframeTick(tickIndex) {
-    const tick = Math.trunc(tickIndex);
-    const list = this.keyframeTicks;
-    const last = list[list.length - 1];
-    if (last == null || tick > last) {
-      list.push(tick);
-      return;
-    }
-    if (tick === last) return;
-    let lo = 0;
-    let hi = list.length - 1;
-    while (lo <= hi) {
-      const mid = (lo + hi) >> 1;
-      if (list[mid] < tick) {
-        lo = mid + 1;
-      } else {
-        hi = mid - 1;
-      }
-    }
-    if (list[lo] !== tick) list.splice(lo, 0, tick);
-  }
-
-  _truncateDeltasAfter(cutoff) {
-    if (this.maxDeltaTick == null) return;
-    for (let tick = this.maxDeltaTick; tick > cutoff; tick -= 1) {
-      const delta = this.deltas[tick];
-      if (!delta) continue;
-      this.deltas[tick] = undefined;
-      this.deltaCount -= 1;
-      this._releaseDelta(delta);
-    }
-    let nextMax = Math.min(this.maxDeltaTick, cutoff);
-    while (nextMax >= this.minDeltaTick && !this.deltas[nextMax]) {
-      nextMax -= 1;
-    }
-    if (nextMax < this.minDeltaTick) {
-      this.minDeltaTick = null;
-      this.maxDeltaTick = null;
-      this.deltaCount = 0;
-      return;
-    }
-    this.maxDeltaTick = nextMax;
-  }
-
-  _truncateKeyframesAfter(cutoff) {
-    if (this.maxKeyframeTick == null) return;
-    for (let tick = this.maxKeyframeTick; tick > cutoff; tick -= 1) {
-      if (!this.keyframes[tick]) continue;
-      this.keyframes[tick] = undefined;
-      this.keyframeCount -= 1;
-    }
-    while (this.keyframeTicks.length &&
-        this.keyframeTicks[this.keyframeTicks.length - 1] > cutoff) {
-      this.keyframeTicks.pop();
-    }
-    if (!this.keyframeTicks.length) {
-      this.minKeyframeTick = null;
-      this.maxKeyframeTick = null;
-      this._lastKeyframe = null;
-      return;
-    }
-    this.minKeyframeTick = this.keyframeTicks[0];
-    this.maxKeyframeTick = this.keyframeTicks[this.keyframeTicks.length - 1];
-    this._lastKeyframe = this.keyframes[this.maxKeyframeTick] || null;
-  }
-
-  _truncateBefore(cutoff) {
-    if (this.minDeltaTick == null || this.maxDeltaTick == null) return;
-    const start = Math.max(0, Math.trunc(cutoff));
-    for (let tick = this.minDeltaTick; tick < start; tick += 1) {
-      const delta = this.deltas[tick];
-      if (!delta) continue;
-      this.deltas[tick] = undefined;
-      this.deltaCount -= 1;
-      this._releaseDelta(delta);
-    }
-    let nextMin = Math.max(this.minDeltaTick, start);
-    while (nextMin <= this.maxDeltaTick && !this.deltas[nextMin]) {
-      nextMin += 1;
-    }
-    if (nextMin > this.maxDeltaTick) {
-      this.minDeltaTick = null;
-      this.maxDeltaTick = null;
-      this.deltaCount = 0;
-    } else {
-      this.minDeltaTick = nextMin;
-    }
-
-    if (!this.keyframeTicks.length) return;
-    while (this.keyframeTicks.length && this.keyframeTicks[0] < start) {
-      const tick = this.keyframeTicks.shift();
-      if (this.keyframes[tick]) {
-        this.keyframes[tick] = undefined;
-        this.keyframeCount -= 1;
-      }
-    }
-    if (!this.keyframeTicks.length) {
-      this.minKeyframeTick = null;
-      this.maxKeyframeTick = null;
-      this._lastKeyframe = null;
-      return;
-    }
-    this.minKeyframeTick = this.keyframeTicks[0];
-    this.maxKeyframeTick = this.keyframeTicks[this.keyframeTicks.length - 1];
-    this._lastKeyframe = this.keyframes[this.maxKeyframeTick] || null;
-  }
-
-  _compressGroundChanges(changes) {
-    const indices = changes?.indices;
-    if (!indices || indices.length < 2) return;
-    const starts = [];
-    const lengths = [];
-    let runStart = indices[0];
-    let runLength = 1;
-    for (let i = 1; i < indices.length; i++) {
-      const idx = indices[i];
-      if (idx === indices[i - 1] + 1) {
-        runLength += 1;
-      } else {
-        starts.push(runStart);
-        lengths.push(runLength);
-        runStart = idx;
-        runLength = 1;
-      }
-    }
-    starts.push(runStart);
-    lengths.push(runLength);
-    changes.spans = { starts, lengths };
-    indices.length = 0;
-  }
-
-  _maybeWarnHistory() {
-    const warn = this.options.historyWarnTicks;
-    if (!warn || warn <= 0 || this._historyWarned) return;
-    if (this.minDeltaTick == null || this.maxDeltaTick == null) return;
-    const span = this.maxDeltaTick - this.minDeltaTick + 1;
-    if (span < warn) return;
-    this._historyWarned = true;
-    console.warn(`HistoryStore: ${span} ticks retained (warn threshold ${warn}).`);
-  }
-
-  _enforceHistoryCap() {
-    if (!this.options.enableHistoryCap) return;
-    const cap = this.options.historyCapTicks ?? 0;
-    if (!Number.isFinite(cap) || cap <= 0) return;
-    if (this.minDeltaTick == null || this.maxDeltaTick == null) return;
-    const span = this.maxDeltaTick - this.minDeltaTick + 1;
-    if (span <= cap) return;
-    let cutoff = this.maxDeltaTick - cap + 1;
-    const frame = this.getKeyframeAtOrBefore(cutoff);
-    if (frame?.tickIndex != null) {
-      cutoff = Math.min(cutoff, frame.tickIndex);
-    }
-    if (cutoff <= this.minDeltaTick) return;
-    this._truncateBefore(cutoff);
-  }
-
-  _bindTimer() {
-    if (!this.timer) return;
-    this._beforeTick = (tick) => this.beginTick(tick);
-    this._afterTick = () => this.endTick();
-    this.timer.onBeforeGameTick?.on(this._beforeTick);
-    this.timer.onGameTick?.on(this._afterTick);
-  }
-
-  beginTick(tick) {
-    if (!this._recording) return;
-    this._currentTick = tick;
-    this._currentDelta = this._allocDelta(tick);
-  }
-
-  endTick() {
-    if (!this._recording || !this.game || !this._currentDelta) return;
-    const tick = this._currentTick;
-    const tickIndex = this.timer?.tickIndex ?? (tick + 1);
-    this._diffState(this.game, this._currentDelta);
-    this._compressGroundChanges(this._currentDelta.groundChanges);
-    this._setDelta(tick, this._currentDelta);
-    if ((tickIndex % this.options.keyframeInterval) === 0) {
-      this._setKeyframe(tickIndex, this._captureKeyframe(this.game, tickIndex));
-    }
-    this._maybeWarnHistory();
-    this._enforceHistoryCap();
-    this._currentDelta = null;
-  }
-
-  captureBaseline(game) {
-    if (!game) return;
-    this._captureScalarState(game);
-    const manager = game.getLemmingManager?.();
-    this._captureLemmingState(manager);
-    this._lemmingManagerState = this._readLemmingManager(manager);
-    this._captureEntrances(game.level);
-  }
-
-  recordSoundEvent(event) {
-    if (!this._currentDelta) return;
-    this._currentDelta.soundEvents.push(event);
-  }
-
-  recordGroundChange(index, prevMask, prevR, prevG, prevB, nextMask, nextR, nextG, nextB) {
-    if (!this._currentDelta) return;
-    this._groundDirty = true;
-    const changes = this._currentDelta.groundChanges;
-    changes.indices.push(index);
-    changes.prevMask.push(prevMask);
-    changes.prevR.push(prevR);
-    changes.prevG.push(prevG);
-    changes.prevB.push(prevB);
-    changes.nextMask.push(nextMask);
-    changes.nextR.push(nextR);
-    changes.nextG.push(nextG);
-    changes.nextB.push(nextB);
-  }
-
-  recordEntranceChange(index, prev, next) {
-    if (!this._currentDelta) return;
-    const changes = this._currentDelta.entranceChanges;
-    changes.indices.push(index);
-    changes.prev.push(prev ? 1 : 0);
-    changes.next.push(next ? 1 : 0);
-  }
-
-  recordTriggerCooldown(trigger, prev, next) {
-    if (!this._currentDelta) return;
-    const id = this._ensureTriggerId(trigger);
-    const changes = this._currentDelta.triggerCooldownChanges;
-    changes.ids.push(id);
-    changes.prev.push(prev);
-    changes.next.push(next);
-  }
-
-  recordTriggerAdd(trigger, snapshot) {
-    if (!this._currentDelta) return;
-    const id = this._ensureTriggerId(trigger);
-    this._currentDelta.triggerAdd.push({ id, ...snapshot });
-  }
-
-  recordTriggerRemove(trigger, snapshot) {
-    if (!this._currentDelta) return;
-    const id = this._ensureTriggerId(trigger);
-    this._currentDelta.triggerRemove.push({ id, ...snapshot });
-  }
-
-  recordObjectAnimation(obj, prev, next) {
-    if (!this._currentDelta) return;
-    const id = this._ensureObjectId(obj);
-    const changes = this._currentDelta.objectAnimChanges;
-    changes.ids.push(id);
-    changes.prevFirst.push(prev.firstFrameIndex);
-    changes.prevFinished.push(prev.isFinished ? 1 : 0);
-    changes.nextFirst.push(next.firstFrameIndex);
-    changes.nextFinished.push(next.isFinished ? 1 : 0);
-  }
-
-  recordMinimapDeath(entry) {
-    if (!this._currentDelta) return;
-    this._currentDelta.minimapDeaths.push(entry);
-  }
-
-  _ensureTriggerId(trigger) {
-    if (!trigger) return 0;
-    if (trigger.__historyId) return trigger.__historyId;
-    const id = this._nextTriggerId++;
-    trigger.__historyId = id;
-    this._triggerIds.set(trigger, id);
-    this._triggerById.set(id, trigger);
-    return id;
-  }
-
-  _ensureObjectId(obj) {
-    if (!obj) return 0;
-    if (obj.__historyId) return obj.__historyId;
-    const id = this._nextObjectId++;
-    obj.__historyId = id;
-    this._objectIds.set(obj, id);
-    this._objectById.set(id, obj);
-    return id;
-  }
-
-  _captureKeyframe(game, tickIndex) {
-    const lemmingManager = game.getLemmingManager?.();
-    const lemmings = lemmingManager?.lemmings || [];
-    const lemmingState = cloneLemmingState(this._lemmingState, lemmings.length || 0);
-    const lemmingManagerState = this._readLemmingManager(lemmingManager);
-    const entrances = game.level?.entrances || [];
-    const entranceOpened = new Uint8Array(entrances.length);
-    for (let i = 0; i < entrances.length; i++) {
-      entranceOpened[i] = entrances[i]?._opened ? 1 : 0;
-    }
-    const triggerState = this._readTriggerState(game);
-    const objectState = this._readObjectState(game.level);
-    const minimapState = this._readMinimapState(lemmingManager?.miniMap);
-    const victory = this._readVictory(game.getVictoryCondition?.());
-    const skills = this._readSkills(game.getGameSkills?.());
-    const timer = this._readTimer(game.getGameTimer?.());
-    const gameState = this._readGameState(game);
-    const level = game.level || null;
-    let groundMask = null;
-    let groundImage = null;
-    if (level?.groundMask?.mask && level?.groundImage) {
-      if (!this._groundDirty &&
-          this._lastKeyframe?.groundMask &&
-          this._lastKeyframe?.groundImage) {
-        groundMask = this._lastKeyframe.groundMask;
-        groundImage = this._lastKeyframe.groundImage;
-      } else {
-        groundMask = new Uint8Array(level.groundMask.mask);
-        groundImage = new Uint8ClampedArray(level.groundImage);
-      }
-    }
-    this._groundDirty = false;
-    return {
-      tickIndex,
-      lemmingState,
-      lemmingManagerState,
-      entranceOpened,
-      triggerState,
-      objectState,
-      minimapState,
-      victory,
-      skills,
-      timer,
-      gameState,
-      groundMask,
-      groundImage
-    };
-  }
-
-  _diffState(game, delta) {
-    const manager = game.getLemmingManager?.();
-    this._diffLemmings(manager, delta);
-    this._diffLemmingManager(manager, delta);
-    this._diffEntrances(game.level, delta);
-    this._diffScalarState(game, delta);
-  }
-
-  _captureLemmingState(manager) {
-    if (!manager) return;
-    const lems = manager.lemmings || [];
-    this._lemmingState = ensureLemmingCapacity(this._lemmingState, lems.length);
-    for (let i = 0; i < lems.length; i++) {
-      const lem = lems[i];
-      if (!lem) {
-        this._lemmingState.present[i] = 0;
-        continue;
-      }
-      const actionType = this._getActionType(manager, lem.action);
-      const countdownActive = !!lem.countdownAction;
-      this._writeLemmingState(this._lemmingState, i, lem, actionType, countdownActive);
-    }
-  }
-
-  _diffLemmings(manager, delta) {
-    if (!manager) return;
-    const lems = manager.lemmings || [];
-    this._lemmingState = ensureLemmingCapacity(this._lemmingState, lems.length);
-    const prev = this._lemmingState;
-    for (let i = 0; i < lems.length; i++) {
-      const lem = lems[i];
-      if (!lem) {
-        if (prev.present[i]) {
-          const snap = {
-            id: i,
-            x: prev.x[i],
-            y: prev.y[i],
-            lookRight: prev.lookRight[i],
-            frameIndex: prev.frameIndex[i],
-            state: prev.state[i],
-            canClimb: prev.canClimb[i],
-            hasParachute: prev.hasParachute[i],
-            removed: prev.removed[i],
-            disabled: prev.disabled[i],
-            countdown: prev.countdown[i],
-            hasExploded: prev.hasExploded[i],
-            lastTriggerType: prev.lastTriggerType[i],
-            actionType: prev.actionType[i],
-            countdownActive: prev.countdownActive[i]
-          };
-          delta.lemRemoved.push(snap);
-          prev.present[i] = 0;
-        }
-        continue;
-      }
-
-      const actionType = this._getActionType(manager, lem.action);
-      const countdownActive = !!lem.countdownAction;
-      if (!prev.present[i]) {
-        delta.lemAdded.push(snapshotLemming(lem, actionType, countdownActive));
-        this._writeLemmingState(prev, i, lem, actionType, countdownActive);
-        continue;
-      }
-
-      this._diffLemmingField(delta, i, 0, prev.x[i], lem.x, prev.x);
-      this._diffLemmingField(delta, i, 1, prev.y[i], lem.y, prev.y);
-      this._diffLemmingField(delta, i, 2, prev.lookRight[i], lem.lookRight ? 1 : 0, prev.lookRight);
-      this._diffLemmingField(delta, i, 3, prev.frameIndex[i], lem.frameIndex, prev.frameIndex);
-      this._diffLemmingField(delta, i, 4, prev.state[i], lem.state ?? 0, prev.state);
-      this._diffLemmingField(delta, i, 5, prev.canClimb[i], lem.canClimb ? 1 : 0, prev.canClimb);
-      this._diffLemmingField(delta, i, 6, prev.hasParachute[i], lem.hasParachute ? 1 : 0, prev.hasParachute);
-      this._diffLemmingField(delta, i, 7, prev.removed[i], lem.removed ? 1 : 0, prev.removed);
-      this._diffLemmingField(delta, i, 8, prev.disabled[i], lem.disabled ? 1 : 0, prev.disabled);
-      this._diffLemmingField(delta, i, 9, prev.countdown[i], lem.countdown ?? 0, prev.countdown);
-      this._diffLemmingField(delta, i, 10, prev.hasExploded[i], lem.hasExploded ? 1 : 0, prev.hasExploded);
-      this._diffLemmingField(delta, i, 11, prev.lastTriggerType[i], Number.isFinite(lem.lastTriggerType) ? lem.lastTriggerType : -1, prev.lastTriggerType);
-      this._diffLemmingField(delta, i, 12, prev.actionType[i], actionType, prev.actionType);
-      this._diffLemmingField(delta, i, 13, prev.countdownActive[i], countdownActive ? 1 : 0, prev.countdownActive);
-      prev.present[i] = 1;
-    }
-
-    for (let i = lems.length; i < prev.present.length; i++) {
-      if (prev.present[i]) {
-        const snap = {
-          id: i,
-          x: prev.x[i],
-          y: prev.y[i],
-          lookRight: prev.lookRight[i],
-          frameIndex: prev.frameIndex[i],
-          state: prev.state[i],
-          canClimb: prev.canClimb[i],
-          hasParachute: prev.hasParachute[i],
-          removed: prev.removed[i],
-          disabled: prev.disabled[i],
-          countdown: prev.countdown[i],
-          hasExploded: prev.hasExploded[i],
-          lastTriggerType: prev.lastTriggerType[i],
-          actionType: prev.actionType[i],
-          countdownActive: prev.countdownActive[i]
-        };
-        delta.lemRemoved.push(snap);
-        prev.present[i] = 0;
-      }
-    }
-  }
-
-  _diffLemmingManager(manager, delta) {
-    const next = this._readLemmingManager(manager);
-    if (this._lemmingManagerState && next && !this._lemmingManagerEqual(this._lemmingManagerState, next)) {
-      delta.lemmingManagerChanges = { prev: this._lemmingManagerState, next };
-    }
-    this._lemmingManagerState = next;
-  }
-
-  _readLemmingManager(manager) {
-    if (!manager) return null;
-    const targets = Array.isArray(manager._nukeTargets)
-      ? manager._nukeTargets.map(lem => (lem?.id ?? null))
-      : null;
-    return {
-      selectedIndex: manager.selectedIndex,
-      spawnTotal: manager.spawnTotal,
-      releaseTickIndex: manager.releaseTickIndex,
-      mmTickCounter: manager.mmTickCounter,
-      nextNukingLemmingsIndex: manager.nextNukingLemmingsIndex,
-      nukeTargets: targets
-    };
-  }
-
-  _lemmingManagerEqual(a, b) {
-    if (!a || !b) return false;
-    if (a.selectedIndex !== b.selectedIndex) return false;
-    if (a.spawnTotal !== b.spawnTotal) return false;
-    if (a.releaseTickIndex !== b.releaseTickIndex) return false;
-    if (a.mmTickCounter !== b.mmTickCounter) return false;
-    if (a.nextNukingLemmingsIndex !== b.nextNukingLemmingsIndex) return false;
-    const aa = a.nukeTargets || [];
-    const bb = b.nukeTargets || [];
-    if (aa.length !== bb.length) return false;
-    for (let i = 0; i < aa.length; i++) {
-      if (aa[i] !== bb[i]) return false;
-    }
-    return true;
-  }
-
-  _diffLemmingField(delta, id, field, prevValue, nextValue, store) {
-    if (prevValue === nextValue) return;
-    delta.lemChanges.ids.push(id);
-    delta.lemChanges.fields.push(field);
-    delta.lemChanges.prev.push(prevValue);
-    delta.lemChanges.next.push(nextValue);
-    store[id] = nextValue;
-  }
-
-  _writeLemmingState(state, index, lem, actionType, countdownActive) {
-    state.present[index] = 1;
-    state.x[index] = lem.x;
-    state.y[index] = lem.y;
-    state.lookRight[index] = lem.lookRight ? 1 : 0;
-    state.frameIndex[index] = lem.frameIndex;
-    state.state[index] = lem.state ?? 0;
-    state.canClimb[index] = lem.canClimb ? 1 : 0;
-    state.hasParachute[index] = lem.hasParachute ? 1 : 0;
-    state.removed[index] = lem.removed ? 1 : 0;
-    state.disabled[index] = lem.disabled ? 1 : 0;
-    state.countdown[index] = lem.countdown ?? 0;
-    state.hasExploded[index] = lem.hasExploded ? 1 : 0;
-    state.lastTriggerType[index] = Number.isFinite(lem.lastTriggerType) ? lem.lastTriggerType : -1;
-    state.actionType[index] = Number.isFinite(actionType) ? actionType : -1;
-    state.countdownActive[index] = countdownActive ? 1 : 0;
-  }
-
-  _getActionType(manager, action) {
-    if (!action || !manager) return -1;
-    if (manager.actionTypeByAction?.has(action)) {
-      return manager.actionTypeByAction.get(action);
-    }
-    const actions = manager.actions || [];
-    for (let i = 0; i < actions.length; i++) {
-      if (actions[i] === action) return i;
-    }
-    return -1;
-  }
-
-  _captureEntrances(level) {
-    const entrances = level?.entrances || [];
-    this._entranceOpened = new Uint8Array(entrances.length);
-    for (let i = 0; i < entrances.length; i++) {
-      this._entranceOpened[i] = entrances[i]?._opened ? 1 : 0;
-    }
-  }
-
-  _diffEntrances(level, delta) {
-    const entrances = level?.entrances || [];
-    if (this._entranceOpened.length !== entrances.length) {
-      this._captureEntrances(level);
-      return;
-    }
-    for (let i = 0; i < entrances.length; i++) {
-      const opened = entrances[i]?._opened ? 1 : 0;
-      if (this._entranceOpened[i] !== opened) {
-        delta.entranceChanges.indices.push(i);
-        delta.entranceChanges.prev.push(this._entranceOpened[i]);
-        delta.entranceChanges.next.push(opened);
-        this._entranceOpened[i] = opened;
-      }
-    }
-  }
-
-  _captureScalarState(game) {
-    this._skillsState = this._readSkills(game.getGameSkills?.());
-    this._victoryState = this._readVictory(game.getVictoryCondition?.());
-    this._timerState = this._readTimer(game.getGameTimer?.());
-    this._gameState = this._readGameState(game);
-  }
-
-  _diffScalarState(game, delta) {
-    const nextSkills = this._readSkills(game.getGameSkills?.());
-    if (this._skillsState && nextSkills && !this._skillsEqual(this._skillsState, nextSkills)) {
-      delta.skillsChanges = { prev: this._skillsState, next: nextSkills };
-    }
-    this._skillsState = nextSkills;
-
-    const nextVictory = this._readVictory(game.getVictoryCondition?.());
-    if (this._victoryState && nextVictory && !this._victoryEqual(this._victoryState, nextVictory)) {
-      delta.victoryChanges = { prev: this._victoryState, next: nextVictory };
-    }
-    this._victoryState = nextVictory;
-
-    const nextTimer = this._readTimer(game.getGameTimer?.());
-    if (this._timerState && nextTimer && !this._timerEqual(this._timerState, nextTimer)) {
-      delta.timerChanges = { prev: this._timerState, next: nextTimer };
-    }
-    this._timerState = nextTimer;
-
-    const nextGame = this._readGameState(game);
-    if (this._gameState && nextGame && !this._gameStateEqual(this._gameState, nextGame)) {
-      delta.gameChanges = { prev: this._gameState, next: nextGame };
-    }
-    this._gameState = nextGame;
-  }
-
-  _readSkills(skills) {
-    if (!skills) return null;
-    const values = Array.isArray(skills.skills) ? skills.skills.slice() : [];
-    return {
-      selectedSkill: skills.selectedSkill,
-      cheatMode: !!skills.cheatMode,
-      skills: values
-    };
-  }
-
-  _skillsEqual(a, b) {
-    if (!a || !b) return false;
-    if (a.selectedSkill !== b.selectedSkill) return false;
-    if (!!a.cheatMode !== !!b.cheatMode) return false;
-    const aa = a.skills || [];
-    const bb = b.skills || [];
-    if (aa.length !== bb.length) return false;
-    for (let i = 0; i < aa.length; i++) {
-      if (aa[i] !== bb[i]) return false;
-    }
-    return true;
-  }
-
-  _readVictory(victory) {
-    if (!victory) return null;
-    return {
-      releaseRate: victory.releaseRate,
-      minReleaseRate: victory.minReleaseRate,
-      leftCount: victory.leftCount,
-      outCount: victory.outCount,
-      survivorCount: victory.survivorCount,
-      isFinalize: !!victory.isFinalize
-    };
-  }
-
-  _victoryEqual(a, b) {
-    if (!a || !b) return false;
-    return a.releaseRate === b.releaseRate
-      && a.minReleaseRate === b.minReleaseRate
-      && a.leftCount === b.leftCount
-      && a.outCount === b.outCount
-      && a.survivorCount === b.survivorCount
-      && !!a.isFinalize === !!b.isFinalize;
-  }
-
-  _readTimer(timer) {
-    if (!timer) return null;
-    return {
-      speedFactor: timer.speedFactor,
-      frameTime: timer.frameTime,
-      tickIndex: timer.tickIndex
-    };
-  }
-
-  _timerEqual(a, b) {
-    if (!a || !b) return false;
-    return a.speedFactor === b.speedFactor
-      && a.frameTime === b.frameTime
-      && a.tickIndex === b.tickIndex;
-  }
-
-  _readGameState(game) {
-    if (!game) return null;
-    return { finalGameState: game.finalGameState };
-  }
-
-  _gameStateEqual(a, b) {
-    if (!a || !b) return false;
-    return a.finalGameState === b.finalGameState;
-  }
-
-  applyKeyframe(game, keyframe) {
-    if (!game || !keyframe) return;
-    const manager = game.getLemmingManager?.();
-    if (manager && keyframe.lemmingState) {
-      const state = keyframe.lemmingState;
-      const lems = manager.lemmings || [];
-      if (lems.length !== state.present.length) {
-        manager.lemmings = new Array(state.present.length);
-      }
-      const countdownAction = manager.skillActions?.[SkillTypes.BOMBER] ?? null;
-      for (let i = 0; i < state.present.length; i++) {
-        if (!state.present[i]) {
-          manager.lemmings[i] = null;
-          continue;
-        }
-        let lem = manager.lemmings[i];
-        if (!lem) {
-          const ctor = manager._lemmingCtor || globalThis.lemmings?.Lemming || null;
-          lem = ctor ? new ctor(state.x[i], state.y[i], i) : { id: i };
-          manager.lemmings[i] = lem;
-        }
-        const action = state.actionType[i] >= 0 ? manager.actions?.[state.actionType[i]] : null;
-        const snap = {
-          id: i,
-          x: state.x[i],
-          y: state.y[i],
-          lookRight: state.lookRight[i],
-          frameIndex: state.frameIndex[i],
-          state: state.state[i],
-          canClimb: state.canClimb[i],
-          hasParachute: state.hasParachute[i],
-          removed: state.removed[i],
-          disabled: state.disabled[i],
-          countdown: state.countdown[i],
-          hasExploded: state.hasExploded[i],
-          lastTriggerType: state.lastTriggerType[i],
-          actionType: state.actionType[i],
-          countdownActive: state.countdownActive[i]
-        };
-        applyLemmingSnapshot(lem, snap, action, countdownAction);
-      }
-      manager.activeLemmings = manager.lemmings.filter(lem => lem && !lem.removed);
-      for (let i = 0; i < manager.activeLemmings.length; i++) {
-        manager.activeLemmings[i]._activeIndex = i;
-      }
-      manager._activeDirty = false;
-    }
-
-    if (manager && keyframe.lemmingManagerState) {
-      const state = keyframe.lemmingManagerState;
-      manager.selectedIndex = state.selectedIndex ?? -1;
-      manager.spawnTotal = state.spawnTotal ?? 0;
-      manager.releaseTickIndex = state.releaseTickIndex ?? 0;
-      manager.mmTickCounter = state.mmTickCounter ?? 0;
-      manager.nextNukingLemmingsIndex = state.nextNukingLemmingsIndex ?? -1;
-      if (Array.isArray(state.nukeTargets)) {
-        manager._nukeTargets = state.nukeTargets
-          .map(id => (Number.isFinite(id) ? manager.lemmings[id] : null))
-          .filter(Boolean);
-      } else {
-        manager._nukeTargets = null;
-      }
-    }
-
-    if (game.level && keyframe.entranceOpened) {
-      const entrances = game.level.entrances || [];
-      for (let i = 0; i < entrances.length; i++) {
-        entrances[i]._opened = !!keyframe.entranceOpened[i];
-      }
-    }
-
-    if (game.triggerManager && keyframe.triggerState) {
-      this._applyTriggerState(game, keyframe.triggerState);
-    }
-
-    if (game.level && keyframe.objectState) {
-      this._applyObjectState(game.level, keyframe.objectState);
-    }
-
-    if (manager?.miniMap && keyframe.minimapState) {
-      const miniMap = manager.miniMap;
-      miniMap.deadDots = new Uint8Array(keyframe.minimapState.deadDots || []);
-      miniMap.deadTTLs = new Uint8Array(keyframe.minimapState.deadTTLs || []);
-      miniMap.deadCount = keyframe.minimapState.deadCount ?? 0;
-    }
-
-    if (game.level?.groundMask && keyframe.groundMask) {
-      game.level.groundMask.mask = new Uint8Array(keyframe.groundMask);
-    }
-    if (game.level && keyframe.groundImage) {
-      game.level.groundImage = new Uint8ClampedArray(keyframe.groundImage);
-    }
-
-    if (keyframe.victory) {
-      const victory = game.getVictoryCondition?.();
-      if (victory) {
-        victory.releaseRate = keyframe.victory.releaseRate;
-        victory.minReleaseRate = keyframe.victory.minReleaseRate;
-        victory.leftCount = keyframe.victory.leftCount;
-        victory.outCount = keyframe.victory.outCount;
-        victory.survivorCount = keyframe.victory.survivorCount;
-        victory.isFinalize = !!keyframe.victory.isFinalize;
-      }
-    }
-
-    if (keyframe.skills) {
-      const skills = game.getGameSkills?.();
-      if (skills) {
-        skills.selectedSkill = keyframe.skills.selectedSkill;
-        skills.cheatMode = !!keyframe.skills.cheatMode;
-        skills.skills = keyframe.skills.skills.slice();
-      }
-    }
-
-    if (keyframe.timer) {
-      const timer = game.getGameTimer?.();
-      if (timer) {
-        const ignoreSpeed = !!game?.timeTravel?.isReversing &&
-          !!game?.timeTravel?.ignoreSpeedOnReverse;
-        if (!ignoreSpeed) {
-          timer.speedFactor = keyframe.timer.speedFactor;
-        }
-        timer.tickIndex = keyframe.timer.tickIndex;
-      }
-    }
-
-    if (keyframe.gameState) {
-      game.finalGameState = keyframe.gameState.finalGameState;
-    }
-
-    this.captureBaseline(game);
-  }
-
-  applyDeltaForward(game, delta) {
-    this._applyDelta(game, delta, true);
-  }
-
-  applyDeltaBackward(game, delta) {
-    this._applyDelta(game, delta, false);
-  }
-
-  _applyDelta(game, delta, useNext) {
-    if (!game || !delta) return;
-    const manager = game.getLemmingManager?.();
-    if (manager) {
-      if (useNext) {
-        this._applyLemmingAdds(manager, delta.lemAdded);
-      } else {
-        this._applyLemmingAdds(manager, delta.lemRemoved);
-      }
-      this._applyLemmingChanges(manager, delta.lemChanges, useNext);
-      if (useNext) {
-        this._applyLemmingRemovals(manager, delta.lemRemoved);
-      } else {
-        this._applyLemmingRemovals(manager, delta.lemAdded);
-      }
-      this._applyLemmingManagerState(manager, delta.lemmingManagerChanges, useNext);
-      this._rebuildActiveLemmings(manager);
-      this._applyMinimapDeaths(manager, delta.minimapDeaths, useNext);
-    }
-
-    this._applyEntranceChanges(game.level, delta.entranceChanges, useNext);
-    this._applyGroundChanges(game.level, delta.groundChanges, useNext);
-    this._applyTriggerChanges(game, delta, useNext);
-    this._applyObjectChanges(game.level, delta.objectAnimChanges, useNext);
-    this._applyScalarChanges(game, delta, useNext);
-  }
-
-  _applyLemmingAdds(manager, list) {
-    if (!manager || !Array.isArray(list) || !list.length) return;
-    const countdownAction = manager.skillActions?.[SkillTypes.BOMBER] ?? null;
-    if (!Array.isArray(manager.lemmings)) manager.lemmings = [];
-    for (const snap of list) {
-      if (snap == null || !Number.isFinite(snap.id)) continue;
-      let lem = manager.lemmings[snap.id];
-      if (!lem) {
-        const ctor = manager._lemmingCtor || globalThis.lemmings?.Lemming || null;
-        lem = ctor ? new ctor(snap.x, snap.y, snap.id) : { id: snap.id };
-        manager.lemmings[snap.id] = lem;
-      }
-      const action = snap.actionType >= 0 ? manager.actions?.[snap.actionType] : null;
-      applyLemmingSnapshot(lem, snap, action, countdownAction);
-    }
-  }
-
-  _applyLemmingRemovals(manager, list) {
-    if (!manager || !Array.isArray(list) || !list.length) return;
-    for (const snap of list) {
-      if (snap == null || !Number.isFinite(snap.id)) continue;
-      manager.lemmings[snap.id] = null;
-    }
-  }
-
-  _applyLemmingChanges(manager, changes, useNext) {
-    if (!manager || !changes?.ids?.length) return;
-    const countdownAction = manager.skillActions?.[SkillTypes.BOMBER] ?? null;
-    for (let i = 0; i < changes.ids.length; i++) {
-      const id = changes.ids[i];
-      const field = changes.fields[i];
-      const value = useNext ? changes.next[i] : changes.prev[i];
-      const lem = manager.lemmings?.[id];
-      if (!lem) continue;
-      switch (field) {
-      case 0: lem.x = value; break;
-      case 1: lem.y = value; break;
-      case 2: lem.lookRight = !!value; break;
-      case 3: lem.frameIndex = value; break;
-      case 4: lem.state = value; break;
-      case 5: lem.canClimb = !!value; break;
-      case 6: lem.hasParachute = !!value; break;
-      case 7: lem.removed = !!value; break;
-      case 8: lem.disabled = !!value; break;
-      case 9: lem.countdown = value; break;
-      case 10: lem.hasExploded = !!value; break;
-      case 11: lem.lastTriggerType = value >= 0 ? value : null; break;
-      case 12: lem.action = value >= 0 ? manager.actions?.[value] : null; break;
-      case 13: lem.countdownAction = value ? countdownAction : null; break;
-      default: break;
-      }
-    }
-  }
-
-  _applyLemmingManagerState(manager, changes, useNext) {
-    if (!manager || !changes) return;
-    const state = useNext ? changes.next : changes.prev;
-    if (!state) return;
-    manager.selectedIndex = state.selectedIndex ?? -1;
-    manager.spawnTotal = state.spawnTotal ?? 0;
-    manager.releaseTickIndex = state.releaseTickIndex ?? 0;
-    manager.mmTickCounter = state.mmTickCounter ?? 0;
-    manager.nextNukingLemmingsIndex = state.nextNukingLemmingsIndex ?? -1;
-    if (Array.isArray(state.nukeTargets)) {
-      manager._nukeTargets = state.nukeTargets
-        .map(id => (Number.isFinite(id) ? manager.lemmings[id] : null))
-        .filter(Boolean);
-    } else {
-      manager._nukeTargets = null;
-    }
-  }
-
-  _rebuildActiveLemmings(manager) {
-    if (!manager) return;
-    manager.activeLemmings = manager.lemmings.filter(lem => lem && !lem.removed);
-    for (let i = 0; i < manager.activeLemmings.length; i++) {
-      manager.activeLemmings[i]._activeIndex = i;
-    }
-    manager._activeDirty = false;
-  }
-
-  _applyEntranceChanges(level, changes, useNext) {
-    if (!level || !changes?.indices?.length) return;
-    for (let i = 0; i < changes.indices.length; i++) {
-      const idx = changes.indices[i];
-      const val = useNext ? changes.next[i] : changes.prev[i];
-      if (level.entrances?.[idx]) {
-        level.entrances[idx]._opened = !!val;
-      }
-    }
-  }
-
-  _applyGroundChanges(level, changes, useNext) {
-    if (!level || !changes) return;
-    const mask = level.groundMask?.mask;
-    const img = level.groundImage;
-    if (!mask || !img) return;
-    const spans = changes.spans;
-    if (spans?.starts?.length) {
-      let valueIndex = 0;
-      const starts = spans.starts;
-      const lengths = spans.lengths;
-      for (let i = 0; i < starts.length; i++) {
-        const start = starts[i];
-        const length = lengths[i];
-        for (let j = 0; j < length; j++) {
-          const index = start + j;
-          const maskValue = useNext ? changes.nextMask[valueIndex] : changes.prevMask[valueIndex];
-          const r = useNext ? changes.nextR[valueIndex] : changes.prevR[valueIndex];
-          const g = useNext ? changes.nextG[valueIndex] : changes.prevG[valueIndex];
-          const b = useNext ? changes.nextB[valueIndex] : changes.prevB[valueIndex];
-          mask[index] = maskValue;
-          const imgIdx = index * 4;
-          img[imgIdx] = r;
-          img[imgIdx + 1] = g;
-          img[imgIdx + 2] = b;
-          valueIndex += 1;
-        }
-      }
-      return;
-    }
-    if (!changes.indices?.length) return;
-    for (let i = 0; i < changes.indices.length; i++) {
-      const index = changes.indices[i];
-      const maskValue = useNext ? changes.nextMask[i] : changes.prevMask[i];
-      const r = useNext ? changes.nextR[i] : changes.prevR[i];
-      const g = useNext ? changes.nextG[i] : changes.prevG[i];
-      const b = useNext ? changes.nextB[i] : changes.prevB[i];
-      mask[index] = maskValue;
-      const imgIdx = index * 4;
-      img[imgIdx] = r;
-      img[imgIdx + 1] = g;
-      img[imgIdx + 2] = b;
-    }
-  }
-
-  _applyTriggerChanges(game, delta, useNext) {
-    const triggerManager = game?.triggerManager;
-    if (!triggerManager || !delta) return;
-    const adds = useNext ? delta.triggerAdd : delta.triggerRemove;
-    const removes = useNext ? delta.triggerRemove : delta.triggerAdd;
-    for (const snap of removes || []) {
-      const trig = this._findTriggerById(triggerManager, snap.id);
-      if (trig && trig.owner) {
-        triggerManager.removeByOwner(trig.owner);
-      }
-    }
-    for (const snap of adds || []) {
-      const owner = Number.isFinite(snap.ownerId)
-        ? game.getLemmingManager?.()?.getLemming?.(snap.ownerId)
-        : null;
-      const trig = new Trigger(
-        snap.type,
-        snap.x1,
-        snap.y1,
-        snap.x2,
-        snap.y2,
-        snap.disableTicksCount,
-        snap.soundIndex,
-        owner
-      );
-      trig.disabledUntilTick = snap.disabledUntilTick ?? 0;
-      trig.__historyId = snap.id;
-      triggerManager.add(trig);
-      this._triggerById.set(snap.id, trig);
-    }
-    if (delta.triggerCooldownChanges?.ids?.length) {
-      for (let i = 0; i < delta.triggerCooldownChanges.ids.length; i++) {
-        const id = delta.triggerCooldownChanges.ids[i];
-        const trig = this._findTriggerById(triggerManager, id);
-        if (!trig) continue;
-        const value = useNext
-          ? delta.triggerCooldownChanges.next[i]
-          : delta.triggerCooldownChanges.prev[i];
-        trig.disabledUntilTick = value;
-      }
-    }
-  }
-
-  _findTriggerById(triggerManager, id) {
-    if (!triggerManager || !id) return null;
-    if (this._triggerById.has(id)) return this._triggerById.get(id);
-    for (const trig of triggerManager._triggers || []) {
-      if (trig?.__historyId === id) {
-        this._triggerById.set(id, trig);
-        return trig;
-      }
-    }
-    return null;
-  }
-
-  _applyObjectChanges(level, changes, useNext) {
-    if (!level || !changes?.ids?.length) return;
-    for (let i = 0; i < changes.ids.length; i++) {
-      const id = changes.ids[i];
-      let obj = this._objectById.get(id);
-      if (!obj) {
-        const objects = level.objects || [];
-        for (const entry of objects) {
-          if (!entry?.animation) continue;
-          const entryId = this._ensureObjectId(entry);
-          if (entryId === id) {
-            obj = entry;
-            break;
-          }
-        }
-      }
-      if (!obj?.animation) continue;
-      const first = useNext ? changes.nextFirst[i] : changes.prevFirst[i];
-      const finished = useNext ? changes.nextFinished[i] : changes.prevFinished[i];
-      obj.animation.firstFrameIndex = first;
-      obj.animation.isFinished = !!finished;
-    }
-  }
-
-  _applyScalarChanges(game, delta, useNext) {
-    if (delta.victoryChanges) {
-      const victory = game.getVictoryCondition?.();
-      const state = useNext ? delta.victoryChanges.next : delta.victoryChanges.prev;
-      if (victory && state) {
-        victory.releaseRate = state.releaseRate;
-        victory.minReleaseRate = state.minReleaseRate;
-        victory.leftCount = state.leftCount;
-        victory.outCount = state.outCount;
-        victory.survivorCount = state.survivorCount;
-        victory.isFinalize = !!state.isFinalize;
-      }
-    }
-    if (delta.skillsChanges) {
-      const skills = game.getGameSkills?.();
-      const state = useNext ? delta.skillsChanges.next : delta.skillsChanges.prev;
-      if (skills && state) {
-        skills.selectedSkill = state.selectedSkill;
-        skills.cheatMode = !!state.cheatMode;
-        skills.skills = state.skills.slice();
-      }
-    }
-    if (delta.timerChanges) {
-      const timer = game.getGameTimer?.();
-      const state = useNext ? delta.timerChanges.next : delta.timerChanges.prev;
-      if (timer && state) {
-        const ignoreSpeed = !useNext && !!game?.timeTravel?.ignoreSpeedOnReverse;
-        if (!ignoreSpeed) {
-          timer.speedFactor = state.speedFactor;
-        }
-        timer.tickIndex = state.tickIndex;
-      }
-    }
-    if (delta.gameChanges) {
-      const state = useNext ? delta.gameChanges.next : delta.gameChanges.prev;
-      if (state) game.finalGameState = state.finalGameState;
-    }
-  }
-
-  _applyMinimapDeaths(manager, entries, useNext) {
-    const miniMap = manager?.miniMap;
-    if (!miniMap || !entries?.length) return;
-    if (useNext) {
-      for (const entry of entries) {
-        const idx = entry.prevCount ?? miniMap.deadCount ?? 0;
-        const neededDots = (idx + 1) * 2;
-        if (miniMap.deadDots.length < neededDots) {
-          const next = Math.max(4, miniMap.deadDots.length * 2, neededDots);
-          const coords = new Uint8Array(next);
-          coords.set(miniMap.deadDots);
-          miniMap.deadDots = coords;
-        }
-        if (miniMap.deadTTLs.length < idx + 1) {
-          const next = Math.max(4, miniMap.deadTTLs.length * 2, idx + 1);
-          const ttls = new Uint8Array(next);
-          ttls.set(miniMap.deadTTLs);
-          miniMap.deadTTLs = ttls;
-        }
-        miniMap.deadDots[idx * 2] = entry.x ?? 0;
-        miniMap.deadDots[idx * 2 + 1] = entry.y ?? 0;
-        miniMap.deadTTLs[idx] = entry.ttl ?? 0;
-        miniMap.deadCount = Math.max(miniMap.deadCount ?? 0, idx + 1);
-      }
-      return;
-    }
-    for (let i = entries.length - 1; i >= 0; i--) {
-      const entry = entries[i];
-      const prevCount = entry.prevCount ?? 0;
-      miniMap.deadCount = prevCount;
-    }
-  }
-
-  _readTriggerState(game) {
-    const triggerManager = game?.triggerManager;
-    const level = game?.level;
-    if (!triggerManager || !level) return null;
-    const staticTriggers = [];
-    const dynamicTriggers = [];
-    const levelTriggers = level.triggers || [];
-    const staticSet = new Set(levelTriggers);
-    for (let i = 0; i < levelTriggers.length; i++) {
-      const trig = levelTriggers[i];
-      if (!trig) continue;
-      const id = this._ensureTriggerId(trig);
-      staticTriggers.push({ id, disabledUntilTick: trig.disabledUntilTick });
-    }
-    for (const trig of triggerManager._triggers || []) {
-      if (!trig || staticSet.has(trig)) continue;
-      const ownerId = Number.isFinite(trig.owner?.id) ? trig.owner.id : null;
-      if (ownerId == null) continue;
-      const id = this._ensureTriggerId(trig);
-      dynamicTriggers.push({
-        id,
-        ownerId,
-        type: trig.type,
-        x1: trig.x1,
-        y1: trig.y1,
-        x2: trig.x2,
-        y2: trig.y2,
-        disableTicksCount: trig.disableTicksCount,
-        soundIndex: trig.soundIndex,
-        disabledUntilTick: trig.disabledUntilTick
-      });
-    }
-    return { staticTriggers, dynamicTriggers };
-  }
-
-  _applyTriggerState(game, state) {
-    const triggerManager = game.triggerManager;
-    const level = game.level;
-    if (!triggerManager || !level || !state) return;
-    const levelTriggers = level.triggers || [];
-    for (let i = 0; i < levelTriggers.length; i++) {
-      const trig = levelTriggers[i];
-      const entry = state.staticTriggers?.[i] || null;
-      if (!trig || !entry) continue;
-      trig.disabledUntilTick = entry.disabledUntilTick;
-      this._ensureTriggerId(trig);
-    }
-
-    const dynamic = state.dynamicTriggers || [];
-    if (dynamic.length) {
-      const removeOwners = new Set();
-      for (const trig of triggerManager._triggers || []) {
-        const ownerId = Number.isFinite(trig.owner?.id) ? trig.owner.id : null;
-        if (ownerId != null) removeOwners.add(ownerId);
-      }
-      for (const ownerId of removeOwners) {
-        const owner = game.getLemmingManager?.()?.getLemming?.(ownerId) ?? null;
-        if (owner) triggerManager.removeByOwner(owner);
-      }
-      for (const snap of dynamic) {
-        const owner = game.getLemmingManager?.()?.getLemming?.(snap.ownerId) ?? null;
-        const trig = new Trigger(
-          snap.type,
-          snap.x1,
-          snap.y1,
-          snap.x2,
-          snap.y2,
-          snap.disableTicksCount,
-          snap.soundIndex,
-          owner
-        );
-        trig.disabledUntilTick = snap.disabledUntilTick;
-        trig.__historyId = snap.id;
-        triggerManager.add(trig);
-      }
-    }
-  }
-
-  _readObjectState(level) {
-    const objects = level?.objects || [];
-    const out = [];
-    for (const obj of objects) {
-      if (!obj?.animation) continue;
-      const id = this._ensureObjectId(obj);
-      out.push({
-        id,
-        firstFrameIndex: obj.animation.firstFrameIndex,
-        isFinished: obj.animation.isFinished
-      });
-    }
-    return out;
-  }
-
-  _applyObjectState(level, state) {
-    for (const entry of state || []) {
-      let obj = this._objectById.get(entry.id);
-      if (!obj) {
-        const objects = level?.objects || [];
-        for (const candidate of objects) {
-          if (!candidate?.animation) continue;
-          const candidateId = this._ensureObjectId(candidate);
-          if (candidateId === entry.id) {
-            obj = candidate;
-            break;
-          }
-        }
-      }
-      if (!obj?.animation) continue;
-      obj.animation.firstFrameIndex = entry.firstFrameIndex;
-      obj.animation.isFinished = !!entry.isFinished;
-    }
-  }
-
-  _readMinimapState(miniMap) {
-    if (!miniMap) return null;
-    return {
-      deadDots: new Uint8Array(miniMap.deadDots || []),
-      deadTTLs: new Uint8Array(miniMap.deadTTLs || []),
-      deadCount: miniMap.deadCount ?? 0
-    };
-  }
-}
-
-const __test__ = {
-  createLemmingState,
-  cloneLemmingState,
-  ensureLemmingCapacity,
-  snapshotLemming,
-  applyLemmingSnapshot
-};
-
-export { HistoryStore, __test__ };
+// @ts-check
+export { HistoryStore, __test__ } from './history/HistoryStoreCore.js';
diff --git a/js/game/SoundEvents.js b/js/game/SoundEvents.js
index ecb1739b..231d0016 100644
--- a/js/game/SoundEvents.js
+++ b/js/game/SoundEvents.js
@@ -1,5 +1,18 @@
 import { EventHandler } from '../util/EventHandler.js';
-import { withPerformance } from '../util/LogHandler.js';
+import { getAppContext } from '../core/dependencies.js';
+import {
+  canMeasurePerformance,
+  recordPerformanceMeasure
+} from '../util/performanceInstrumentation.js';
+
+const EMIT_MEASURE_DETAIL = Object.freeze({
+  devtools: Object.freeze({
+    track: 'SoundEvents',
+    trackGroup: 'Game State',
+    color: 'secondary',
+    tooltipText: 'emit'
+  })
+});
 
 const SoundEventTypes = Object.freeze({
   LEVEL_START: 'level-start',
@@ -60,39 +73,56 @@ class SoundEventBus {
   }
 
   emit(event) {
-    return withPerformance(
-      'SoundEventBus emit',
-      {
-        track: 'SoundEvents',
-        trackGroup: 'Game State',
-        color: 'secondary',
-        tooltipText: 'emit'
-      },
-      () => {
-        if (!event) return;
-        const hasListeners = this.onEvent?.handlers?.size > 0;
-        if (!hasListeners &&
-            (this._queueLimit <= 0 || this._queue.length >= this._queueLimit)) {
-          return;
-        }
-        const tick = this.gameTimer?.getGameTicks?.() ?? 0;
-        const frameMs = this.gameTimer?.frameTime ?? this.gameTimer?.TIME_PER_FRAME_MS ?? 60;
-        const payload = {
-          id: ++this._sequence,
-          tick,
-          timeMs: tick * frameMs,
-          frameMs,
-          speedFactor: this.gameTimer?.speedFactor ?? 1,
-          tps: this.gameTimer?.tps ?? null,
-          ...event
-        };
-        if (this._queueLimit > 0 && this._queue.length < this._queueLimit) {
-          this._queue.push(payload);
-        }
-        this.history?.recordSoundEvent?.(payload);
-        if (this.onEvent) this.onEvent.trigger(payload);
+    const app = getAppContext();
+    const perfEnabled = !!app &&
+      (app.performanceAPI === true || app.perfMetrics === true) &&
+      canMeasurePerformance();
+    const perfStart = perfEnabled ? performance.now() : 0;
+    try {
+      if (!event) return;
+      const handlers = this.onEvent?.handlers || null;
+      const hasListeners = !!handlers && handlers.size > 0;
+      const hasHistory = !!this.history?.recordSoundEvent;
+      const queueLimit = this._queueLimit | 0;
+      const queue = this._queue;
+      const queueLen = queue.length;
+      const queueOpen = queueLimit > 0 && queueLen < queueLimit;
+
+      if (!hasListeners && !hasHistory && !queueOpen) {
+        return;
+      }
+
+      const timer = this.gameTimer;
+      const tick = timer?.getGameTicks?.() ?? 0;
+      const frameMs = timer?.frameTime ?? timer?.TIME_PER_FRAME_MS ?? 60;
+      const payload = {
+        id: this._sequence + 1,
+        tick,
+        timeMs: tick * frameMs,
+        frameMs,
+        speedFactor: timer?.speedFactor ?? 1,
+        tps: timer?.tps ?? null
+      };
+      this._sequence += 1;
+
+      for (const key in event) {
+        if (!Object.prototype.hasOwnProperty.call(event, key)) continue;
+        payload[key] = event[key];
+      }
+
+      if (queueOpen) {
+        queue.push(payload);
       }
-    ).call(this);
+      this.history?.recordSoundEvent?.(payload);
+      if (this.onEvent) this.onEvent.trigger(payload);
+    } finally {
+      if (perfEnabled) {
+        recordPerformanceMeasure('SoundEventBus emit', {
+          start: perfStart,
+          detail: EMIT_MEASURE_DETAIL
+        });
+      }
+    }
   }
 
   emitSfx(type, sfxId, data = {}) {
@@ -119,11 +149,9 @@ class SoundEventBus {
 }
 
 const getSoundBus = () => {
-  if (typeof globalThis !== 'undefined' && globalThis.lemmings?.game?.soundEvents) {
-    return globalThis.lemmings.game.soundEvents;
-  }
-  if (typeof lemmings !== 'undefined' && lemmings?.game?.soundEvents) {
-    return lemmings.game.soundEvents;
+  const app = getAppContext();
+  if (app?.game?.soundEvents) {
+    return app.game.soundEvents;
   }
   return null;
 };
diff --git a/js/game/TimeTravelController.js b/js/game/TimeTravelController.js
index 76521b0f..48973aaf 100644
--- a/js/game/TimeTravelController.js
+++ b/js/game/TimeTravelController.js
@@ -1,3 +1,23 @@
+const DEFAULT_HISTORY_RETENTION = Object.freeze({
+  enableHistoryCap: true,
+  historyCapTicks: 20000,
+  historyWarnTicks: 15000
+});
+
+const getNowMs = () => {
+  if (typeof performance !== 'undefined' && typeof performance.now === 'function') {
+    return performance.now();
+  }
+  return Date.now();
+};
+
+const resolveRafApi = () => {
+  if (typeof window === 'undefined') return null;
+  if (typeof window.requestAnimationFrame !== 'function') return null;
+  if (typeof window.cancelAnimationFrame !== 'function') return null;
+  return window;
+};
+
 class TimeTravelController {
   constructor(game, history) {
     this.game = game;
@@ -12,16 +32,48 @@ class TimeTravelController {
     this.ignoreSpeedOnReverse = true;
     this._resumeForward = false;
     this._prevInputEnabled = null;
+    this._rafApi = null;
+    this._historyRetention = this._configureHistoryRetention();
   }
 
   get isReversing() { return this._reverseActive; }
 
+  getHistoryRetention() {
+    return { ...this._historyRetention };
+  }
+
+  _configureHistoryRetention() {
+    return this.setHistoryRetention(DEFAULT_HISTORY_RETENTION);
+  }
+
+  setHistoryRetention(policy = null) {
+    const requested = {
+      ...DEFAULT_HISTORY_RETENTION,
+      ...(policy && typeof policy === 'object' ? policy : {})
+    };
+    if (!this.history?.configureRetention) {
+      this._historyRetention = { ...requested };
+      return this.getHistoryRetention();
+    }
+    this._historyRetention = this.history.configureRetention(requested);
+    return this.getHistoryRetention();
+  }
+
   _resolveTimer() {
     const timer = this.game?.getGameTimer?.();
     if (timer) this.timer = timer;
     return this.timer;
   }
 
+  _getDeltaAt(tickIndex) {
+    if (!this.history) return null;
+    if (typeof this.history.getDelta === 'function') {
+      const delta = this.history.getDelta(tickIndex);
+      if (delta !== undefined && delta !== null) return delta;
+    }
+    return this.history.deltas?.[tickIndex] ?? null;
+  }
+
   stepBackward(count = 1) {
     const timer = this._resolveTimer();
     if (!timer || !this.history || !this.game) return;
@@ -33,12 +85,15 @@ class TimeTravelController {
         break;
       }
       const targetTick = timer.tickIndex - 1;
-      const delta = this.history.getDelta?.(targetTick)
-        ?? this.history.deltas?.[targetTick];
+      const delta = this._getDeltaAt(targetTick);
       if (!delta) {
         this.seekToTick(targetTick);
         break;
       }
+      if (typeof this.history.applyDeltaBackward !== 'function') {
+        this.seekToTick(targetTick);
+        break;
+      }
       this.history.applyDeltaBackward(this.game, delta);
       timer.tickIndex = targetTick;
       this._emitReverseEvents(delta);
@@ -56,13 +111,17 @@ class TimeTravelController {
     const target = Math.max(0, Math.trunc(targetTickIndex));
     const keyframe = this.history.getKeyframeAtOrBefore(target);
     if (!keyframe) return;
+    if (typeof this.history.applyKeyframe !== 'function') return;
     this.history.applyKeyframe(this.game, keyframe);
-    timer.tickIndex = keyframe.tickIndex ?? target;
+    const keyframeTick = Number.isFinite(keyframe.tickIndex)
+      ? Math.max(0, Math.trunc(keyframe.tickIndex))
+      : target;
+    timer.tickIndex = Math.min(target, keyframeTick);
     let cursor = timer.tickIndex;
     while (cursor < target) {
-      const delta = this.history.getDelta?.(cursor)
-        ?? this.history.deltas?.[cursor];
+      const delta = this._getDeltaAt(cursor);
       if (!delta) break;
+      if (typeof this.history.applyDeltaForward !== 'function') break;
       this.history.applyDeltaForward(this.game, delta);
       cursor += 1;
       timer.tickIndex = cursor;
@@ -75,9 +134,11 @@ class TimeTravelController {
 
   startReverse() {
     const timer = this._resolveTimer();
-    if (this._reverseActive || !timer || !this.game) return;
+    const rafApi = resolveRafApi();
+    if (this._reverseActive || !timer || !this.game || !rafApi) return;
     this.playbackDirection = -1;
     this._reverseActive = true;
+    this._rafApi = rafApi;
     this._resumeForward = !!timer.isRunning?.();
     if (this._prevInputEnabled === null) {
       this._prevInputEnabled = this.game.inputEnabled ?? true;
@@ -88,11 +149,14 @@ class TimeTravelController {
     }
     timer.suspend?.();
     this.history?.pause?.();
-    this._lastTime = performance.now();
+    this._lastTime = getNowMs();
     this._reverseCarryMs = 0;
     const loop = (now) => {
       if (!this._reverseActive) return;
-      const frameTime = timer.frameTime || timer.TIME_PER_FRAME_MS || 60;
+      const frameTimeCandidate = timer.frameTime || timer.TIME_PER_FRAME_MS || 60;
+      const frameTime = Number.isFinite(frameTimeCandidate) && frameTimeCandidate > 0
+        ? frameTimeCandidate
+        : 60;
       let delta = (now - this._lastTime) + this._reverseCarryMs;
       if (delta >= frameTime) {
         const rawSteps = Math.floor(delta / frameTime);
@@ -105,19 +169,21 @@ class TimeTravelController {
         this._lastTime = now;
         this.stepBackward(steps);
       }
-      this._reverseRaf = window.requestAnimationFrame(loop);
+      this._reverseRaf = this._rafApi?.requestAnimationFrame?.(loop) ?? 0;
     };
-    this._reverseRaf = window.requestAnimationFrame(loop);
+    this._reverseRaf = this._rafApi.requestAnimationFrame(loop);
   }
 
   stopReverse() {
     if (!this._reverseActive) return;
     const timer = this._resolveTimer();
     this._reverseActive = false;
+    const rafApi = this._rafApi || resolveRafApi();
     if (this._reverseRaf) {
-      window.cancelAnimationFrame(this._reverseRaf);
+      rafApi?.cancelAnimationFrame?.(this._reverseRaf);
       this._reverseRaf = 0;
     }
+    this._rafApi = null;
     this._reverseCarryMs = 0;
     if (this._resumeForward && timer) {
       this.history?.truncateAfter?.(timer.tickIndex);
diff --git a/js/game/game-gui/GameGuiCore.js b/js/game/game-gui/GameGuiCore.js
new file mode 100644
index 00000000..604b0ba6
--- /dev/null
+++ b/js/game/game-gui/GameGuiCore.js
@@ -0,0 +1,121 @@
+import {
+  CommandNuke,
+  CommandReleaseRateDecrease,
+  CommandReleaseRateIncrease,
+  CommandSelectSkill,
+  EventHandler,
+  MiniMap,
+  SKILL_COUNT,
+  SKILL_KEYS,
+  SKILL_LABELS,
+  SkillTypes,
+  SmoothScroller,
+  canMeasurePerformance,
+  formatSkillLabel,
+  getApp,
+  getAppContext,
+  getDependency,
+  recordPerformanceMeasure
+} from './GameGuiShared.js';
+import { gameGuiInputMethods } from './GameGuiInput.js';
+import { gameGuiRenderMethods } from './GameGuiRender.js';
+class GameGui {
+  constructor(game, skillPanelSprites, skills, gameTimer, gameVictoryCondition) {
+    /* external handles */
+    this.game                 = game;
+    this.skillPanelSprites    = skillPanelSprites;
+    this.skills               = skills;
+    this.gameTimer            = gameTimer;
+    this.gameVictoryCondition = gameVictoryCondition;
+
+    /* change-tracking flags (original names) */
+    this.gameTimeChanged       = true;
+    this.skillsCountChanged    = true;
+    this.skillSelectionChanged = true;
+    this.backgroundChanged     = true;
+    this.releaseRateChanged    = true;
+
+    this.nukePrepared          = false;
+    this.lastGameSpeed      = 0;
+
+    /* sprite caches */
+    this._panelSprite    = skillPanelSprites.getPanelSprite();
+    this._numLeftCache   = new Array(10);
+    this._numRightCache  = new Array(10);
+    this._numEmptySprite = skillPanelSprites.getNumberSpriteEmpty();
+    this._letterCache    = new Map();
+
+    /* runtime state */
+    this.display          = null;
+    this.miniMap          = null;
+    this.deltaReleaseRate = 0;
+    this._overlayHadContent = false;
+
+    /* marching ants selection animation settings */
+    this.selectionDashLen   = 4;   // length of dash segments (1px longer)
+    this.selectionAnimDelay = 60;  // frames between offset increments (slower)
+    this.selectionAnimStep  = 1;   // pixels per animation step
+    this.selectionAnimIdleMultiplier = 2;
+    this._selectionOffset   = 0;
+    this._selectionCounter  = 0;
+    this._lastAntPanel = Number.NaN;
+    this._lastAntPaused = null;
+    this._lastAntNukePrepared = null;
+    this._lastAntHoverPanel = Number.NaN;
+    this._lastAntOffset = Number.NaN;
+
+    /* hover state */
+    this._hoverPanelIdx   = -1;
+    this._hoverSpeedUp    = false;
+    this._hoverSpeedDown  = false;
+
+    /* release rate lock state */
+    this._rrLockMin = false;
+    this._rrLockMax = false;
+
+    this._guiBound = this._guiLoop.bind(this);
+    this._guiRafId = 0;
+
+    this.smoothScroller = new SmoothScroller();
+
+    this._nukeAfterCountdown = 0;
+
+    this._onEachGameSecond = () => {
+      const app = getApp();
+      this._applyReleaseRateAuto();
+      if (app?.nukeAfter > 0) {
+        this._nukeAfterCountdown++;
+        if (this._nukeAfterCountdown >= app.nukeAfter) {
+          this.game.queueCommand(new CommandNuke());
+          this.nukePrepared = false;
+          this._nukeAfterCountdown = 0;
+        }
+      }
+      if ((Math.floor(this.gameTimer.getGameTime()) % 2) === 0) {
+        this.backgroundChanged = true;
+      }
+      this.gameTimeChanged = true;
+
+      this._requestGuiRender();
+    };
+    gameTimer.eachGameSecond.on(this._onEachGameSecond);
+
+    this._onSkillCountChanged = () => {
+      this.backgroundChanged = true;
+    };
+    skills.onCountChanged.on(this._onSkillCountChanged);
+
+    this._onSkillSelectionChanged = () => {
+      this.backgroundChanged = true;
+      this._selectionOffset  = 0;
+    };
+    skills.onSelectionChanged.on(this._onSkillSelectionChanged);
+  }
+}
+for (const methods of [
+  gameGuiInputMethods,
+  gameGuiRenderMethods
+]) {
+  Object.defineProperties(GameGui.prototype, Object.getOwnPropertyDescriptors(methods));
+}
+export { GameGui };
\ No newline at end of file
diff --git a/js/game/game-gui/GameGuiInput.js b/js/game/game-gui/GameGuiInput.js
new file mode 100644
index 00000000..9d200d09
--- /dev/null
+++ b/js/game/game-gui/GameGuiInput.js
@@ -0,0 +1,393 @@
+import {
+  CommandNuke,
+  CommandReleaseRateDecrease,
+  CommandReleaseRateIncrease,
+  CommandSelectSkill,
+  EventHandler,
+  MiniMap,
+  SKILL_COUNT,
+  SKILL_KEYS,
+  SKILL_LABELS,
+  SkillTypes,
+  SmoothScroller,
+  canMeasurePerformance,
+  formatSkillLabel,
+  getApp,
+  getAppContext,
+  getDependency,
+  recordPerformanceMeasure
+} from './GameGuiShared.js';
+const gameGuiInputMethods = {
+  setMiniMap(miniMap) {
+    this.miniMap = miniMap;
+    this.game?.lemmingManager?.setMiniMap?.(miniMap);
+  },
+
+  _requestGuiRender() {
+    if (!this.display || this._guiRafId) return;
+    if (typeof window === 'undefined' || typeof window.requestAnimationFrame !== 'function') {
+      return;
+    }
+    this._guiRafId = window.requestAnimationFrame(this._guiBound);
+  },
+
+  _invalidateAntState() {
+    this._lastAntPanel = Number.NaN;
+    this._lastAntPaused = null;
+    this._lastAntNukePrepared = null;
+    this._lastAntHoverPanel = Number.NaN;
+    this._lastAntOffset = Number.NaN;
+  },
+
+  _isMechanicEnabled(name, fallback = false) {
+    const value = this.game?.level?.mechanics?.[name];
+    if (typeof value === 'boolean') return value;
+    return fallback;
+  },
+
+  _getSelectionAnimDelay(paused) {
+    const baseDelay = Math.max(1, Math.trunc(this.selectionAnimDelay) || 1);
+    if (!paused) return baseDelay;
+    const isIdle =
+        this._hoverPanelIdx < 0 &&
+        !this._hoverSpeedUp &&
+        !this._hoverSpeedDown &&
+        !this.nukePrepared;
+    if (!isIdle) return baseDelay;
+    const idleMultiplier = Math.max(1, Math.trunc(this.selectionAnimIdleMultiplier) || 1);
+    return baseDelay * idleMultiplier;
+  },
+
+  _applyReleaseRateAuto({ queueWhenClamped = false } = {}) {
+    if (!this.deltaReleaseRate) return;
+    const isRunning = this.gameTimer.isRunning();
+    if (isRunning) {
+      const min = this.gameVictoryCondition.getMinReleaseRate?.() ?? 0;
+      const max = this.gameVictoryCondition.getMaxReleaseRate?.() ?? 99;
+      const cur = this.gameVictoryCondition.getCurrentReleaseRate();
+      let   neu = cur + this.deltaReleaseRate;
+      if (neu < min) neu = min;
+      if (neu > max) neu = max;
+      if (neu === cur) {
+        if (!queueWhenClamped) return;
+      } else {
+        this.gameVictoryCondition.setCurrentReleaseRate?.(neu) ??
+                    (this.gameVictoryCondition.releaseRate = neu);
+        this.releaseRateChanged = true;
+      }
+    }
+    if (!isRunning && !this._isMechanicEnabled('pauseGlitch', true)) {
+      return;
+    }
+    if (this.deltaReleaseRate > 0)
+      this.game.queueCommand(new CommandReleaseRateIncrease(this.deltaReleaseRate));
+    else
+      this.game.queueCommand(new CommandReleaseRateDecrease(-this.deltaReleaseRate));
+  },
+
+  handleSkillMouseDown(e) {
+    const panelIndex = Math.trunc(e.x / 16);
+    if (panelIndex !== 11) {
+      this.nukePrepared = false;
+      this.backgroundChanged = true;
+      this.gameTimeChanged = true;
+    }
+
+    if (panelIndex === 0 || panelIndex === 1) {
+      const step = panelIndex === 0 ? -3 : +3;
+      const min = this.gameVictoryCondition.getMinReleaseRate?.() ?? 0;
+      const max = this.gameVictoryCondition.getMaxReleaseRate?.() ?? 99;
+      const cur = this.gameVictoryCondition.getCurrentReleaseRate();
+      if ((step < 0 && cur <= min) || (step > 0 && cur >= max)) {
+        if (this.skills.clearSelectedSkill()) {
+          this.skillSelectionChanged = true;
+        }
+        return;
+      }
+      if (this.gameTimer.isRunning()) {
+        let neu = cur + step;
+        if (neu < min) neu = min;
+        if (neu > max) neu = max;
+        this.lastGameSpeed = neu;
+        this.gameVictoryCondition.setCurrentReleaseRate?.(neu) ??
+                      (this.gameVictoryCondition.releaseRate = neu);
+        this.releaseRateChanged = true;
+      }
+      this.deltaReleaseRate = step;
+      this._applyReleaseRateAuto();
+      this.gameTimeChanged = true;
+      return;
+    }
+    if (panelIndex === 10) {
+      if (e.y >= 32) { // if it is the bottom of the pause button
+        const pauseX = e.x - 159; // the leftmost position
+        const pauseIndex = Math.trunc(pauseX / 9);
+        const speedFac = this.gameTimer.speedFactor;
+        const app = getApp();
+        const debugOrBench = (this.game.showDebug || app?.bench === true || app?.bench2 === true || app?.benchReverse === true);
+        const syncSpeed = () => {
+          if (app) app.gameSpeedFactor = this.gameTimer.speedFactor;
+        };
+        if (pauseIndex === 0) {
+          if (speedFac > 10) {
+            this.gameTimer.speedFactor -= 10;
+            this.drawSpeedChange(false);
+            syncSpeed();
+            return;
+          }
+          if (speedFac > 1) {
+            this.gameTimer.speedFactor--;
+            this.drawSpeedChange(false);
+            syncSpeed();
+            return;
+          }
+          if (debugOrBench || speedFac === 1 || speedFac > 0.1 && speedFac < 1) {
+            this.gameTimer.speedFactor = Math.trunc((this.gameTimer.speedFactor-0.1)*100)/100;
+            this.drawSpeedChange(false);
+            syncSpeed();
+            return;
+          }
+        }
+        if (pauseIndex === 1) {
+          if (speedFac < 1) {
+            this.gameTimer.speedFactor = Math.trunc((this.gameTimer.speedFactor+0.1)*100)/100;
+            this.drawSpeedChange(true);
+            syncSpeed();
+            return;
+          }
+          if (speedFac >= 10 && speedFac < 120) {
+            this.gameTimer.speedFactor += 10;
+            this.drawSpeedChange(true);
+            syncSpeed();
+            return;
+          }
+          if (speedFac < 10) {
+            this.gameTimer.speedFactor++;
+            this.drawSpeedChange(true);
+            syncSpeed();
+            return;
+          }
+        }
+      } else {
+        this.gameTimer.toggle();
+      }
+      this.skillSelectionChanged = true;
+      this.gameTimeChanged = true;
+      return;
+    }
+    if (panelIndex === 11) {
+      if (this.nukePrepared) {
+        this.game.queueCommand(new CommandNuke());
+        this.nukePrepared = false;
+        this.gameTimeChanged = true;
+      } else {
+        this.nukePrepared = true;
+        this.gameTimeChanged = true;
+      }
+      if (this.skills.clearSelectedSkill()) {
+        this.skillSelectionChanged = true;
+      }
+      this.skillSelectionChanged = true;
+      return;
+    }
+    const newSkill = this.getSkillByPanelIndex(panelIndex);
+    if (newSkill === SkillTypes.UNKNOWN) return;
+    if (this.skills.getSkill(newSkill) <= 0) {
+      if (this.skills.clearSelectedSkill()) this.skillSelectionChanged = true;
+      return;
+    }
+    this.skills.setSelectedSkill(newSkill);
+    this.game.queueCommand(new CommandSelectSkill(newSkill));
+  },
+
+  handleSkillMouseRightDown(e) {
+    const panelIndex = Math.trunc(e.x / 16);
+
+    this.nukePrepared = false; // always cancel nuke confirmation on right click
+    this.gameTimeChanged = true;
+    if (!this._isMechanicEnabled('rightClickGlitch', true)) {
+      return;
+    }
+
+    if (panelIndex === 0) {
+      const min = this.gameVictoryCondition.getMinReleaseRate?.() ?? 0;
+      this.gameVictoryCondition.setCurrentReleaseRate?.(min) ??
+          (this.gameVictoryCondition.releaseRate = min);
+      this.deltaReleaseRate = -min;
+      this.releaseRateChanged = true;
+      this._applyReleaseRateAuto({ queueWhenClamped: true });
+      return;
+    }
+
+    if (panelIndex === 1) {
+      const max = this.gameVictoryCondition.getMaxReleaseRate?.() ?? 99;
+      this.gameVictoryCondition.setCurrentReleaseRate?.(max) ??
+          (this.gameVictoryCondition.releaseRate = max);
+      this.deltaReleaseRate = max;
+      this.releaseRateChanged = true;
+      this._applyReleaseRateAuto({ queueWhenClamped: true });
+      return;
+    }
+
+    if (panelIndex === 10) { // reset game speed if you right click pause
+      if (this.gameTimer.speedFactor !== 1) {
+        this.gameTimer.speedFactor = 1;
+        this.drawSpeedChange(false, true);
+        const app = getApp();
+        if (app) app.gameSpeedFactor = this.gameTimer.speedFactor;
+      }
+      return;
+    }
+
+    if (panelIndex === 11) { // enable debug mode if you right click nuke
+      this.game.showDebug = !this.game.showDebug;
+      return;
+    }
+  },
+
+  handleSkillDoubleClick(e) {
+    if (Math.trunc(e.x / 16) === 11 && this._isMechanicEnabled('nukeGlitch', true))
+      this.game.queueCommand(new CommandNuke());
+  },
+
+  handleMouseMove(e) {
+    const rawIdx = e.y > 15 ? Math.trunc(e.x / 16) : -1;
+    let idx = rawIdx;
+
+    if (!this.gameTimer.isRunning() && rawIdx !== 11) {
+      idx = -1;
+    }
+
+    if (rawIdx === 0 || rawIdx === 1) {
+      const rrMin = this.gameVictoryCondition.getMinReleaseRate?.() ?? 0;
+      const rrMax = this.gameVictoryCondition.getMaxReleaseRate?.() ?? 99;
+      const rrCur = this.gameVictoryCondition.getCurrentReleaseRate?.() ?? 0;
+      if ((rawIdx === 0 && rrCur <= rrMin) || (rawIdx === 1 && rrCur >= rrMax)) {
+        idx = -1;
+      }
+    } else if (rawIdx >= 2 && rawIdx <= 9) {
+      const skill = this.getSkillByPanelIndex(rawIdx);
+      if (this.skills.getSkill(skill) <= 0) idx = -1;
+    }
+
+    const wasIdx = this._hoverPanelIdx;
+    if (idx !== wasIdx) {
+      this._hoverPanelIdx = idx;
+      this.backgroundChanged = true;
+      this.gameTimeChanged = true;
+    }
+
+    let up = false, down = false;
+    if (rawIdx === 10 && e.y >= 32) {
+      const pauseIndex = Math.trunc((e.x - 159) / 9);
+      const speedFac = this.gameTimer.speedFactor;
+      if (pauseIndex === 1 && speedFac < 120) up = true;
+      if (pauseIndex === 0 && speedFac > 0.1) down = true;
+    }
+    if (up !== this._hoverSpeedUp || down !== this._hoverSpeedDown) {
+      this._hoverSpeedUp = up;
+      this._hoverSpeedDown = down;
+      this.gameSpeedChanged = true;
+      this.gameTimeChanged = true;
+    }
+  },
+
+  setGuiDisplay(display) {
+    if (this.display && this._displayListeners) {
+      for (const [event, handler] of this._displayListeners) {
+        this.display[event].off(handler);
+      }
+    }
+    this.display = display;
+    this.display?.stage?.setGuiOverlayVisible?.(false);
+    this._overlayHadContent = false;
+    if (!this.miniMap) {
+      const MiniMapCtor = getDependency('MiniMap', MiniMap);
+      this.setMiniMap(new MiniMapCtor(this.game.gameDisplay, this.game.level, display, this.game.runtime));
+    }
+
+    this._displayListeners = [
+      ['onMouseDown', e => {
+        this.deltaReleaseRate = 0;
+        if (e.y > 15) this.handleSkillMouseDown(e);
+        this._requestGuiRender();
+      }],
+      ['onMouseUp', () => {
+        this.deltaReleaseRate = 0;
+        this._requestGuiRender();
+      }],
+      ['onMouseRightDown', e => {
+        if (e.y > 15) this.handleSkillMouseRightDown(e);
+        this._requestGuiRender();
+      }],
+      ['onMouseRightUp', () => {
+        this.deltaReleaseRate = 0;
+        this._requestGuiRender();
+      }],
+      ['onDoubleClick', e => {
+        if (e.y > 15) this.handleSkillDoubleClick(e);
+        this._requestGuiRender();
+      }],
+      ['onMouseMove', e => {
+        this.handleMouseMove(e);
+        this._requestGuiRender();
+      }],
+    ];
+    for (const [event, handler] of this._displayListeners) {
+      display[event].on(handler);
+    }
+
+    // Initialize the HUD size immediately so Stage can center it
+    display.initSize(this._panelSprite.width, this._panelSprite.height);
+    display.setBackground(this._panelSprite.getData());
+    display.stage.updateStageSize();
+
+    this.gameTimeChanged = this.skillsCountChanged = this.skillSelectionChanged = this.backgroundChanged = this.releaseRateChanged = true;
+    this._requestGuiRender();
+  },
+
+  _guiLoop(now) {
+    this._guiRafId = 0;
+    if (!this.display) return;
+    this.render();
+    this.display.redraw();
+  },
+
+  dispose() {
+    if (this._guiRafId) {
+      if (typeof window !== 'undefined' && typeof window.cancelAnimationFrame === 'function') {
+        window.cancelAnimationFrame(this._guiRafId);
+      }
+      this._guiRafId = 0;
+    }
+    if (this.gameTimer?.eachGameSecond && this._onEachGameSecond) {
+      this.gameTimer.eachGameSecond.off(this._onEachGameSecond);
+      this._onEachGameSecond = null;
+    }
+    if (this.skills?.onCountChanged && this._onSkillCountChanged) {
+      this.skills.onCountChanged.off(this._onSkillCountChanged);
+      this._onSkillCountChanged = null;
+    }
+    if (this.skills?.onSelectionChanged && this._onSkillSelectionChanged) {
+      this.skills.onSelectionChanged.off(this._onSkillSelectionChanged);
+      this._onSkillSelectionChanged = null;
+    }
+    if (this.display && this._displayListeners) {
+      for (const [event, handler] of this._displayListeners) {
+        this.display[event].off(handler);
+      }
+    }
+    this.display?.stage?.setGuiOverlayVisible?.(false);
+    this._letterCache = null;
+    this._numRightCache = null;
+    this._numLeftCache = null;
+    this._panelSprite = null;
+    this._numEmptySprite = null;
+    if (this.miniMap?.dispose) this.miniMap.dispose();
+    this.miniMap = null;
+    this.smoothScroller = null;
+    this._overlayHadContent = false;
+
+  }
+};
+export { gameGuiInputMethods };
\ No newline at end of file
diff --git a/js/game/game-gui/GameGuiRender.js b/js/game/game-gui/GameGuiRender.js
new file mode 100644
index 00000000..9f1de206
--- /dev/null
+++ b/js/game/game-gui/GameGuiRender.js
@@ -0,0 +1,487 @@
+import {
+  CommandNuke,
+  CommandReleaseRateDecrease,
+  CommandReleaseRateIncrease,
+  CommandSelectSkill,
+  EventHandler,
+  MiniMap,
+  SKILL_COUNT,
+  SKILL_KEYS,
+  SKILL_LABELS,
+  SkillTypes,
+  SmoothScroller,
+  canMeasurePerformance,
+  formatSkillLabel,
+  getApp,
+  getAppContext,
+  getDependency,
+  recordPerformanceMeasure
+} from './GameGuiShared.js';
+const gameGuiRenderMethods = {
+  render() {
+    const app = getApp();
+    const perfEnabled = !!app &&
+        (app.performanceAPI === true || app.perfMetrics === true) &&
+        canMeasurePerformance();
+    const perfStart = perfEnabled ? performance.now() : 0;
+    if (!this.display) {
+      if (perfEnabled) {
+        recordPerformanceMeasure('GameGui render', {
+          start: perfStart,
+          detail: { devtools: { track: 'GameGui', trackGroup: 'Render', color: 'secondary', tooltipText: 'render' } }
+        });
+      }
+      return false;
+    }
+    const d = this.display;
+    const overlayDisplay = d.stage?.getGuiOverlayDisplay?.() || null;
+    const bench = app?.bench === true || app?.bench2 === true || app?.benchReverse === true || app?.benchSequence === true;
+    if (bench) this.gameTimeChanged = true;
+
+    if (this.backgroundChanged) {
+      this.backgroundChanged = false;
+      this._invalidateAntState();
+      d.initSize(this._panelSprite.width, this._panelSprite.height);
+      d.setBackground(this._panelSprite.getData());
+      this.miniMap?.invalidateFrame?.();
+
+      this.gameTimeChanged = this.skillsCountChanged = this.skillSelectionChanged = this.releaseRateChanged = this.gameSpeedChanged = true;
+    }
+
+    if (this.gameTimeChanged) {
+      this.gameTimeChanged = false;
+
+      if (!bench) {
+        let text = '';
+        if (this._hoverPanelIdx >= 0) {
+          text = this._getPanelName(this._hoverPanelIdx);
+          if (this._hoverPanelIdx === 10) {
+            if (this._hoverSpeedUp) text = 'Increase';
+            else if (this._hoverSpeedDown) text = 'Decrease';
+          }
+        } else if (this.game?.gameDisplay?.hoverLemming?.action) {
+          text = this.game.gameDisplay.hoverLemming.action.getActionName?.() || '';
+        } else if (this.nukePrepared) {
+          text = 'Nuke';
+        } else if (!this.gameTimer.isRunning()) {
+          text = 'Pause';
+        } else {
+          const sel = this.skills.getSelectedSkill();
+          if (sel !== SkillTypes.UNKNOWN) {
+            text = SKILL_LABELS[sel] || '';
+          }
+        }
+        const statusText = this._composeStatusText(this._formatTickIndicator(), text);
+        if (statusText) {
+          this.drawGreenString(d, statusText, 0, 0);
+        }
+        const timeText = app?.endless ? '4-20' : this.gameTimer.getGameLeftTimeString();
+        this.drawGreenString(d, 'Time ' + timeText + '-00', 248, 0);
+        const totalCount = this.game?.getLemmingManager?.()?.spawnTotal ??
+            this.gameVictoryCondition.getReleaseCount?.();
+        if (totalCount >= 0) {
+          this.drawGreenString(d, 'Out ' + totalCount + '  ', 112, 0);
+        }
+        const survivorPct = this.gameVictoryCondition.getSurvivorPercentage?.();
+        if (Number.isFinite(survivorPct)) {
+          this.drawGreenString(d, 'In' + this._pad(survivorPct, 3) + '%', 186, 0);
+        }
+      } else {
+        const activeCount = this.game.getLemmingManager?.()?.getLemmings?.()?.length ?? 0;
+        const stats = [
+          'T' + (app?.steps ?? 0),
+          'TPS ' + Math.round(app?.tps ?? 0),
+          'ACTIVE ' + activeCount,
+          'SPAWNED ' + (this.game.getLemmingManager?.().spawnTotal ?? 0)
+        ];
+        let x = 0;
+        for (let i = 0; i < stats.length; i++) {
+          const s = stats[i];
+          this.drawGreenString(d, s, x, 0);
+          x += (s.length+1) * 8;
+        }
+      }
+    }
+
+    if (this.gameSpeedChanged) {
+      this.gameSpeedChanged = false;
+      const speedFac = this.gameTimer.speedFactor;
+
+      d.drawRect(160, 32, 16, 10, 0, 0, 0, true); // draw bottom black rect on pause button
+
+      if (speedFac !== 120) {
+        const greenS  = this._getGreenLetter('f');
+        d.drawFrameResized(greenS, 173, 34, 3, 4);
+      }
+
+      if (speedFac !== 0.1) {
+        const greenP  = this._getGreenLetter('-');
+        d.drawFrameResized(greenP, 161, 33, 3, 6);
+      }
+
+      const tens  = Math.floor(speedFac / 10);
+      const ones  = speedFac % 10;
+      const left  = this._getLeftDigit(tens);
+      const right = this._getRightDigit(ones);
+      let rightX = 164;
+      if (left && tens > 0) {
+        rightX = 164;
+        d.drawFrameResized(left, rightX-4, 33, 8, 6);
+      }
+      if (right) {
+        d.drawFrameResized(right, rightX, 33, 8, 6);
+      }
+      if (speedFac < 1) {
+        let sn = Math.trunc((speedFac)*10);
+        const small = this._getRightDigit(sn);
+        d.setPixel(167, 38, 255, 255, 255);
+        d.drawFrameResized(small, 164, 33, 8, 6);
+        d.drawHorizontalLine(169, 33, 175, 0, 0, 0);
+      }
+
+      if (this._hoverSpeedUp) {
+        d.drawHorizontalLine(172, 32, 175, 0, 166, 0);
+        d.drawHorizontalLine(172, 38, 175, 0, 166, 0);
+      } else if (this._hoverSpeedDown) {
+        d.drawHorizontalLine(161, 32, 164, 0, 166, 0);
+        d.drawHorizontalLine(161, 38, 164, 0, 166, 0);
+      }
+    }
+
+
+    if (this.skillsCountChanged) {
+      this.skillsCountChanged = false;
+      for (let s = 1; s < SKILL_COUNT; ++s) {
+        const panel = this.getPanelIndexBySkill(s);
+        const count = this.skills.getSkill(s);
+        this.drawPanelNumber(d, count, panel);
+      }
+      for (let s = 1; s < SKILL_COUNT; ++s) {
+        if (this.skills.getSkill(s) <= 0) {
+          const panel = this.getPanelIndexBySkill(s);
+          d.drawStippleRect(panel * 16, 16, 16, 23, 160, 160, 160);
+        }
+      }
+    }
+    if (this.skillSelectionChanged) {
+      this.skillSelectionChanged = false;
+    }
+
+    const paused = !this.gameTimer.isRunning();
+    const selectedPanel = this.getPanelIndexBySkill(this.skills.getSelectedSkill());
+    const antDelay = this._getSelectionAnimDelay(paused);
+    if (++this._selectionCounter >= antDelay) {
+      this._selectionCounter = 0;
+      this._selectionOffset += this.selectionAnimStep;
+    }
+    const antStateChanged =
+        this._lastAntPanel !== selectedPanel ||
+        this._lastAntPaused !== paused ||
+        this._lastAntNukePrepared !== this.nukePrepared ||
+        this._lastAntHoverPanel !== this._hoverPanelIdx ||
+        this._lastAntOffset !== this._selectionOffset;
+    const drawOverlayDecorations = (target) => {
+      let drawn = false;
+      if (this.nukePrepared) {
+        this.drawNukeConfirm(target);
+        drawn = true;
+      }
+      if (this._hoverPanelIdx >= 0) {
+        if (this._hoverPanelIdx === 11) {
+          if (!this.nukePrepared) this.drawSkillHover(target, this._hoverPanelIdx, 255, 128, 0);
+        } else {
+          this.drawSkillHover(target, this._hoverPanelIdx);
+        }
+        drawn = true;
+      }
+      if (paused) {
+        this.drawPaused(target);
+        drawn = true;
+      }
+      if (this.nukePrepared) {
+        this.drawNukeHover(target);
+        drawn = true;
+      }
+      if (selectedPanel >= 0) {
+        this.drawSelection(target, selectedPanel);
+        drawn = true;
+      }
+      return drawn;
+    };
+
+    if (overlayDisplay) {
+      if (antStateChanged) {
+        overlayDisplay.clear(0x00000000);
+        this._overlayHadContent = drawOverlayDecorations(overlayDisplay);
+        d.stage?.setGuiOverlayVisible?.(this._overlayHadContent);
+      }
+    } else {
+      if (this.nukePrepared) {
+        this.drawNukeConfirm(d);
+      }
+      if (this._hoverPanelIdx >= 0) {
+        if (this._hoverPanelIdx === 11) {
+          if (!this.nukePrepared) this.drawSkillHover(d, this._hoverPanelIdx, 255, 128, 0);
+        } else {
+          this.drawSkillHover(d, this._hoverPanelIdx);
+        }
+      }
+      if (antStateChanged) {
+        if (paused) {
+          this.drawPaused(d);
+        }
+        if (this.nukePrepared) {
+          this.drawNukeHover(d);
+        }
+        this.drawSelection(d, selectedPanel);
+      }
+      this._overlayHadContent = false;
+    }
+
+    if (antStateChanged) {
+      this._lastAntPanel = selectedPanel;
+      this._lastAntPaused = paused;
+      this._lastAntNukePrepared = this.nukePrepared;
+      this._lastAntHoverPanel = this._hoverPanelIdx;
+      this._lastAntOffset = this._selectionOffset;
+    }
+    if (this.releaseRateChanged) {
+      this.releaseRateChanged = false;
+      this.drawPanelNumber(d, this.gameVictoryCondition.getMinReleaseRate(),     0);
+      this.drawPanelNumber(d, this.gameVictoryCondition.getCurrentReleaseRate(), 1);
+    }
+
+    const rrMin = this.gameVictoryCondition.getMinReleaseRate?.() ?? 0;
+    const rrMax = this.gameVictoryCondition.getMaxReleaseRate?.() ?? 99;
+    const rrCur = this.gameVictoryCondition.getCurrentReleaseRate?.() ?? 0;
+
+    const lockMin = rrCur <= rrMin;
+    const lockMax = rrCur >= rrMax;
+
+    if (lockMin) this._drawLockEdge(d, 0);
+    if (lockMax) this._drawLockEdge(d, 1);
+
+    if (this._rrLockMin && !lockMin) this.backgroundChanged = true;
+    if (this._rrLockMax && !lockMax) this.backgroundChanged = true;
+
+    this._rrLockMin = lockMin;
+    this._rrLockMax = lockMax;
+
+    if (this.miniMap) {
+      const viewX = this.game.level.screenPositionX;
+      const viewW = d.worldDataSize.width;
+
+      this.miniMap.render(viewX, viewW);
+    }
+    if (perfEnabled) {
+      recordPerformanceMeasure('GameGui render', {
+        start: perfStart,
+        detail: { devtools: { track: 'GameGui', trackGroup: 'Render', color: 'secondary', tooltipText: 'render' } }
+      });
+    }
+    return !!(
+      d.hasPendingDirty?.() ||
+        overlayDisplay?.hasPendingDirty?.()
+    );
+  },
+
+  _formatTickIndicator() {
+    const tick = Math.max(0, this.gameTimer?.tickIndex ?? 0);
+    const dir = this.game?.timeTravel?.isReversing ? '<' : '>';
+    return `T${tick}${dir}`;
+  },
+
+  _composeStatusText(primary, secondary) {
+    const left = primary || '';
+    const right = secondary || '';
+    if (!left && !right) return '';
+    const combined = right ? `${left} ${right}` : left;
+    const maxChars = 14;
+    return combined.length > maxChars ? combined.slice(0, maxChars) : combined;
+  },
+
+  _pad(v, len) { const s = String(v); return s.length >= len ? s : ' '.repeat(len - s.length) + s; },
+
+  _getLeftDigit(d)  { if (d <= 0) return null;
+    if (!this._numLeftCache[d])  this._numLeftCache[d]  = this.skillPanelSprites.getNumberSpriteLeft(d);
+    return this._numLeftCache[d]; },
+
+  _getRightDigit(d) { if (!this._numRightCache[d])
+    this._numRightCache[d] = this.skillPanelSprites.getNumberSpriteRight(d);
+  return this._numRightCache[d];
+  },
+
+  _getGreenLetter(ch) {
+    const cachedGreenLet  = this._letterCache.get(ch);
+    if (!cachedGreenLet) {
+      const newGreenLet = this.skillPanelSprites.getLetterSprite(ch);
+      this._letterCache.set(ch, newGreenLet);
+      return newGreenLet;
+    } else {
+      return cachedGreenLet;
+    }
+  },
+
+  drawSelection(d, panelIdx) {
+    if (panelIdx < 0) return;
+    d.drawMarchingAntRect(
+      16 * panelIdx,
+      16,
+      16,
+      23,
+      this.selectionDashLen,
+      this._selectionOffset
+    );
+  },
+
+  drawPaused(d) {
+    d.drawMarchingAntRect(
+      16 * 10,
+      16,
+      16,
+      23,
+      this.selectionDashLen,
+      this._selectionOffset
+    );
+  },
+
+  drawSkillHover(d, panelIdx, r = 255, g = 255, b = 0) {
+    if (panelIdx < 0) return;
+    d.drawRect(16 * panelIdx, 16, 16, 23, r, g, b);
+  },
+
+  _getPanelName(idx) {
+    switch (idx) {
+    case 0:  return 'Decrease';
+    case 1:  return 'Increase';
+    case 10: return 'Pause';
+    case 11: return 'Nuke';
+    default:
+      const skill = this.getSkillByPanelIndex(idx);
+      if (skill !== SkillTypes.UNKNOWN) {
+        return SKILL_LABELS[skill] || '';
+      }
+      return '';
+    }
+  },
+
+  _drawLockEdge(d, panelIdx) {
+    const x = 16 * panelIdx + 2;
+    const y = 18;
+    const w = 11; // narrower than full panel
+    const h = 18; // shorter than full panel
+    d.drawStippleRect(x, y, w, 0, 160, 160, 160);       // top
+    d.drawStippleRect(x, y + h, w, 0, 160, 160, 160);    // bottom
+    d.drawStippleRect(x, y, 0, h, 160, 160, 160);        // left
+    d.drawStippleRect(x + w, y, 0, h, 160, 160, 160);    // right
+  },
+
+  drawSpeedChange(upDown, reset = false) {
+    if (!this.display) {
+      this.gameSpeedChanged = true;
+      return;
+    }
+    if (!reset) {
+      if (upDown) {
+        this.display.drawHorizontalLine(172, 32, 175, 0, 166, 0);
+        this.display.drawHorizontalLine(172, 38, 175, 0, 166, 0);
+      } else {
+        this.display.drawHorizontalLine(161, 32, 164, 0, 166, 0);
+        this.display.drawHorizontalLine(161, 38, 164, 0, 166, 0);
+      }
+    } else {
+      this.display.drawHorizontalLine(161, 32, 175, 111, 0, 0);
+      this.display.drawHorizontalLine(161, 38, 175, 111, 0, 0);
+    }
+
+    if (this._hoverSpeedUp) {
+      this.display.drawHorizontalLine(172, 32, 175, 0, 166, 0);
+      this.display.drawHorizontalLine(172, 38, 175, 0, 166, 0);
+    } else if (this._hoverSpeedDown) {
+      this.display.drawHorizontalLine(161, 32, 164, 0, 166, 0);
+      this.display.drawHorizontalLine(161, 38, 164, 0, 166, 0);
+    }
+
+    this.gameSpeedChanged = true;
+    this._requestGuiRender();
+  },
+
+  drawNukeConfirm(d) {
+    d.drawRect(16 * 11, 16, 16, 23, 255, 0, 0);
+  },
+
+  drawNukeHover(d) {
+    d.drawMarchingAntRect(
+      16 * 11,
+      16,
+      16,
+      23,
+      this.selectionDashLen,
+      this._selectionOffset * 2,
+      0xFF0080FF,
+      0xFF00FFFF
+    );
+  },
+
+  drawPanelNumber(d, num, panelIdx) {
+    this.drawNumber(d, num, 4 + 16 * panelIdx, 17);
+  },
+
+  drawNumber(d, num, x, y, small = false) {
+    if (num <= 0) {
+      d.drawFrame(this._numEmptySprite, x, y); return;
+    }
+    const tens  = Math.floor(num / 10);
+    const ones  = num % 10;
+    const left  = this._getLeftDigit(tens);
+    const right = this._getRightDigit(ones);
+    if (left) {
+      d.drawFrameCovered(left,  x, y, 0, 0, 0);
+    }
+    d.drawFrame(right, x, y);
+  },
+
+  drawGreenString(d, text, x, y) {
+    for (let i = 0; i < text.length; ++i) {
+      const ch = text[i];
+      let img  = this._letterCache.get(ch);
+      if (!img) {
+        img = this.skillPanelSprites.getLetterSprite(ch);
+        this._letterCache.set(ch, img);
+      }
+      if (img) {
+        d.drawFrameCovered(img, x, y, 0, 0, 0);
+      }
+      x += 8;
+    }
+  },
+
+  getSkillByPanelIndex(idx) {
+    switch (Math.trunc(idx)) {
+    case 2:  return SkillTypes.CLIMBER;
+    case 3:  return SkillTypes.FLOATER;
+    case 4:  return SkillTypes.BOMBER;
+    case 5:  return SkillTypes.BLOCKER;
+    case 6:  return SkillTypes.BUILDER;
+    case 7:  return SkillTypes.BASHER;
+    case 8:  return SkillTypes.MINER;
+    case 9:  return SkillTypes.DIGGER;
+    default: return SkillTypes.UNKNOWN;
+    }
+  },
+
+  getPanelIndexBySkill(skill) {
+    switch (skill) {
+    case SkillTypes.CLIMBER: return 2;
+    case SkillTypes.FLOATER: return 3;
+    case SkillTypes.BOMBER:  return 4;
+    case SkillTypes.BLOCKER: return 5;
+    case SkillTypes.BUILDER: return 6;
+    case SkillTypes.BASHER:  return 7;
+    case SkillTypes.MINER:   return 8;
+    case SkillTypes.DIGGER:  return 9;
+    default: return -1;
+    }
+  }
+};
+export { gameGuiRenderMethods };
\ No newline at end of file
diff --git a/js/game/game-gui/GameGuiShared.js b/js/game/game-gui/GameGuiShared.js
new file mode 100644
index 00000000..1cde75be
--- /dev/null
+++ b/js/game/game-gui/GameGuiShared.js
@@ -0,0 +1,108 @@
+import { CommandNuke } from '../../commands/CommandNuke.js';
+import { CommandReleaseRateIncrease } from '../../commands/CommandReleaseRateIncrease.js';
+import { CommandReleaseRateDecrease } from '../../commands/CommandReleaseRateDecrease.js';
+import { CommandSelectSkill } from '../../commands/CommandSelectSkill.js';
+import { EventHandler } from '../../util/EventHandler.js';
+import { MiniMap } from '../../render/MiniMap.js';
+import { SkillTypes } from '../SkillTypes.js';
+import { getDependency, getAppContext } from '../../core/dependencies.js';
+import {
+  canMeasurePerformance,
+  recordPerformanceMeasure
+} from '../../util/performanceInstrumentation.js';
+
+const getApp = () => {
+  const app = getAppContext();
+  if (app) return app;
+  return null;
+};
+const formatSkillLabel = (key) => (
+  key ? (key.charAt(0) + key.slice(1).toLowerCase()) : ''
+);
+const SKILL_KEYS = Object.freeze(Object.keys(SkillTypes));
+const SKILL_COUNT = SKILL_KEYS.length;
+const SKILL_LABELS = Object.freeze(SKILL_KEYS.map(formatSkillLabel));
+class SmoothScroller {
+  static minZoom = 0.25;
+  static maxZoom = 8;
+
+  constructor() {
+    this.velocity = 0;     // pixels/frame (or units/frame)
+    this.friction = 0.99;
+    this.minVelocity = 0.7;       //0.0175;
+    this._lastVelocity = 0;
+
+    this.onHasVelocity = new EventHandler();
+  }
+
+  hasVelocity() {
+    if (this.velocity < this.minVelocity || this.velocity === 0) {
+      return false;
+    }
+    return true;
+  }
+
+  // call this whenever a wheel event fires:
+  addImpulse(delta) {
+    if (delta === 0) {
+      console.log('error: trying to add 0 impulse');
+      return;
+    }
+    if (delta > 50) {
+      delta = 50;
+    }
+    if (delta < -50) {
+      delta = -50;
+    }
+
+    if (this.velocity + delta > 500) {
+      this.velocity = 500;
+      return;
+    }
+
+    if (this.velocity + delta < -500) {
+      this.velocity = -500;
+      return;
+    }
+
+    this.velocity += delta;
+  }
+
+  update() {
+    // decay the velocity:
+    this.velocity = this.velocity * this.friction;
+
+
+    // stop if below threshold:
+    if (Math.abs(this.velocity) < this.minVelocity) {
+      this.velocity = 0;
+      if (this._lastVelocity !== 0) {
+        this._lastVelocity = 0;
+        this.onHasVelocity.trigger(this.velocity);
+      }
+      return;
+    }
+    this._lastVelocity = this.velocity;
+    this.onHasVelocity.trigger(this.velocity);
+  }
+}
+
+export {
+  CommandNuke,
+  CommandReleaseRateDecrease,
+  CommandReleaseRateIncrease,
+  CommandSelectSkill,
+  EventHandler,
+  MiniMap,
+  SKILL_COUNT,
+  SKILL_KEYS,
+  SKILL_LABELS,
+  SkillTypes,
+  SmoothScroller,
+  canMeasurePerformance,
+  formatSkillLabel,
+  getApp,
+  getAppContext,
+  getDependency,
+  recordPerformanceMeasure
+};
diff --git a/js/game/game-view/GameViewCore.js b/js/game/game-view/GameViewCore.js
new file mode 100644
index 00000000..dd0a3695
--- /dev/null
+++ b/js/game/game-view/GameViewCore.js
@@ -0,0 +1,144 @@
+import {
+  BaseLogger,
+  DEFAULT_RUNTIME_PROFILE,
+  DEFAULT_RUNTIME_ROLLOUT_FLAGS,
+  EditorSession,
+  FileContainer,
+  GameFactory,
+  GameStateTypes,
+  GameTypes,
+  KeyboardShortcuts,
+  Lemming,
+  LevelIndexResolve,
+  LevelReader,
+  MIDI_FLAG_REGISTRATION_KEY,
+  MidiEventRouter,
+  MidiMapping,
+  PASSIVE_RESIZE_LISTENER,
+  STARTUP_PROFILES,
+  SoundEffectIds,
+  SoundEventTypes,
+  Stage,
+  Trigger,
+  TriggerTypes,
+  clampMidiFlagId,
+  clearAppContext,
+  cloneConfig,
+  createCrosshairFrame,
+  createEditorLevelFromClassic,
+  detectRuntimeCapabilities,
+  getDependency,
+  getGameStateTypes,
+  getGameTypes,
+  getLemmingCtor,
+  getProfileHistoryRetention,
+  getRuntimeDependency,
+  getRuntimeProfileIds,
+  getRuntimeProfilePreset,
+  getSpecialHistoryRetention,
+  getTriggerTypes,
+  hashString,
+  listSavedLevels,
+  loadEditorLevel,
+  loadSavedLevel,
+  normalizeRuntimeProfile,
+  parseBoundedNumber,
+  parseInt10,
+  resolveRuntimeRolloutFlags,
+  setAppContext,
+  toMidiFlagTriggerType
+} from './GameViewShared.js';
+import { gameViewRuntimeMethods } from './GameViewRuntime.js';
+import { gameViewMidiMethods } from './GameViewMidi.js';
+import { gameViewQueryMethods } from './GameViewQuery.js';
+import { gameViewLevelSelectionMethods } from './GameViewLevelSelection.js';
+import { gameViewDiagnosticsMethods } from './GameViewDiagnostics.js';
+import { gameViewEditorModeMethods } from './GameViewEditorMode.js';
+class GameView extends BaseLogger {
+  constructor() {
+    super();
+    setAppContext(this);
+    this.gameType = null;
+    this.levelIndex = 0;
+    this.levelGroupIndex = 0;
+    this.gameResources = null;
+    this.game = null;
+    const Factory = getDependency('GameFactory', GameFactory);
+    this.gameFactory = new Factory('./');
+    this.stage = null;
+    this.gameSpeedFactor = 1;
+    this.bench = false; // just keep spawning lems
+    this.bench2 = false;
+    this.benchReverse = false;
+    this.benchSequence = false;
+    this._benchMeasureExtras = false;
+    this.endless = false; // time doesn't run out, game doesn't end
+    this.nukeAfter = 0; // nuke after x seconds
+    this.scale = 0; // zoom
+    this.laggedOut = 0;
+    this.extraLemmings = 0;
+    this.perfMetrics = false;
+    this.performanceAPI = false;
+    this.perfOverlay = false;
+    this.offscreenPresentExperiment = false;
+    this.workerOffscreenExperiment = false;
+    this.startupProfile = DEFAULT_RUNTIME_PROFILE;
+    this.rolloutFlags = { ...DEFAULT_RUNTIME_ROLLOUT_FLAGS };
+    this.runtimeCapabilities = detectRuntimeCapabilities();
+    this.steps = 0;
+    this._benchMonitor = null;
+    this._benchSpeedTrack = null;
+    this._benchMaxSpeed = 0;
+    this._benchCounts = [];
+    this._benchIndex = 0;
+    this._benchExtraList = null;
+    this._benchExtraIndex = 0;
+    this._benchStartTime = 0;
+    this._benchBaseEntrances = null;
+    this._benchEntrancePool = null;
+    this._historyRetentionOverride = null;
+    this._historyRetentionPolicy = null;
+    this.preserveHistory = false;
+    this.cheatEnabled = false;
+    this.applyQuery();
+    this.elementGameState = null;
+    this.autoMoveTimer = null;
+    this.resumeTimer = null;
+    this.elementSelectGameType = null;
+    this.elementSelectLevelGroup = null;
+    this.elementSelectLevel = null;
+    this.configs = null;
+    const Shortcuts = getDependency('KeyboardShortcuts', KeyboardShortcuts);
+    this.shortcuts = new Shortcuts(this);
+    this.midiRouter = null;
+    this._midiOut = null;
+    this._midiMapping = null;
+    this._midiBaseConfig = null;
+    this._midiSchemaHash = null;
+    this._midiStatusHandlers = { onEnabled: null, onError: null };
+    this.midiEnabled = false;
+
+    this.includeSavedLevels = false;
+    this.autoExitEditorOnSelect = false;
+    this.editorMode = false;
+    this.editorSession = null;
+    this.editorPlaytest = false;
+    this._editorWasRunning = false;
+    this._editorInputWasEnabled = true;
+    this._editorPanWasEnabled = true;
+
+    const gameTypes = getGameTypes();
+    this.log.log('selected level: ' + gameTypes.toString(this.gameType) + ' : ' + this.levelIndex + ' / ' + this.levelGroupIndex);
+  }
+}
+for (const methods of [
+  gameViewRuntimeMethods,
+  gameViewMidiMethods,
+  gameViewQueryMethods,
+  gameViewLevelSelectionMethods,
+  gameViewDiagnosticsMethods,
+  gameViewEditorModeMethods
+]) {
+  Object.defineProperties(GameView.prototype, Object.getOwnPropertyDescriptors(methods));
+}
+export { GameView };
diff --git a/js/game/game-view/GameViewDiagnostics.js b/js/game/game-view/GameViewDiagnostics.js
new file mode 100644
index 00000000..61ca86be
--- /dev/null
+++ b/js/game/game-view/GameViewDiagnostics.js
@@ -0,0 +1,261 @@
+import {
+  BaseLogger,
+  DEFAULT_RUNTIME_PROFILE,
+  DEFAULT_RUNTIME_ROLLOUT_FLAGS,
+  EditorSession,
+  FileContainer,
+  GameFactory,
+  GameStateTypes,
+  GameTypes,
+  KeyboardShortcuts,
+  Lemming,
+  LevelIndexResolve,
+  LevelReader,
+  MIDI_FLAG_REGISTRATION_KEY,
+  MidiEventRouter,
+  MidiMapping,
+  PASSIVE_RESIZE_LISTENER,
+  STARTUP_PROFILES,
+  SoundEffectIds,
+  SoundEventTypes,
+  Stage,
+  Trigger,
+  TriggerTypes,
+  clampMidiFlagId,
+  clearAppContext,
+  cloneConfig,
+  createCrosshairFrame,
+  createEditorLevelFromClassic,
+  detectRuntimeCapabilities,
+  getDependency,
+  getGameStateTypes,
+  getGameTypes,
+  getLemmingCtor,
+  getProfileHistoryRetention,
+  getRuntimeDependency,
+  getRuntimeProfileIds,
+  getRuntimeProfilePreset,
+  getSpecialHistoryRetention,
+  getTriggerTypes,
+  hashString,
+  listSavedLevels,
+  loadEditorLevel,
+  loadSavedLevel,
+  normalizeRuntimeProfile,
+  parseBoundedNumber,
+  parseInt10,
+  resolveRuntimeRolloutFlags,
+  setAppContext,
+  toMidiFlagTriggerType
+} from './GameViewShared.js';
+const gameViewDiagnosticsMethods = {
+  async benchStart(entrances) {
+    this.bench = true;
+    this._benchMeasureExtras = false;
+    await this.loadLevel();
+    const level = this.game.level;
+    if (this.stage) {
+      this.applyLevelViewport(level);
+    }
+    const cfg = this.configs?.find(c => c.gametype === this.gameType);
+    const pack = cfg?.name || this.gameType;
+    const savedEntries = this._getSavedLevelEntries();
+    const group = this._getGroupNames(savedEntries)[this.levelGroupIndex];
+    const lvlName = level.name ? level.name.trim() : '';
+    console.log(`starting bench series for ${lvlName} in ${group} in ${pack}, adding ${entrances} entrances with ${this.extraLemmings} extra lemmings`);
+
+    if (!this._benchBaseEntrances) {
+      this._benchBaseEntrances = level.entrances.slice();
+    }
+    level.entrances.length = 0;
+    const baseEntrances = this._benchBaseEntrances;
+    const groundMask = level.getGroundMaskLayer();
+    const triggerTypes = getTriggerTypes();
+    const badTriggers = new Set([
+      triggerTypes.DROWN,
+      triggerTypes.FRYING,
+      triggerTypes.KILL,
+      triggerTypes.TRAP,
+    ]);
+
+    const increments = [100, 50, 25, 12, 6];
+    const SEGMENT_DURATION = 60;
+    const ENTRANCE_HEIGHT = 28;
+    const SPAWN_OFFSET_Y = 14;
+    const SAFE_ENTRANCE_DROP = getLemmingCtor().LEM_MAX_FALLING - SPAWN_OFFSET_Y;
+
+    const clearHeight = (x, y) => {
+      if (y < 0 || y + ENTRANCE_HEIGHT > level.height) return false;
+      for (let i = 0; i < ENTRANCE_HEIGHT; i++) {
+        if (groundMask.hasGroundAt(x, y + i)) return false;
+      }
+      return true;
+    };
+
+    const findOpenSegment = x => {
+      let best = null;
+      let y = 0;
+      while (y < level.height) {
+        while (y < level.height && groundMask.hasGroundAt(x, y)) y++;
+        const start = y;
+        while (y < level.height && !groundMask.hasGroundAt(x, y)) y++;
+        const end = y;
+        if (end >= level.height) break;
+        const h = end - start;
+        if (h >= ENTRANCE_HEIGHT + 15 && (!best || h > best.height)) {
+          best = { top: start, bottom: end, height: h };
+        }
+        y++; // skip ground
+      }
+      return best;
+    };
+
+    const trySpawn = spawnX => {
+      if (spawnX < 0 || spawnX >= level.width) return false;
+      const seg = findOpenSegment(spawnX);
+      if (!seg) return false;
+      const drop = Math.min(seg.height - ENTRANCE_HEIGHT, SAFE_ENTRANCE_DROP);
+      if (drop < 15) return false;
+      const entY = seg.bottom - ENTRANCE_HEIGHT - drop;
+      if (!clearHeight(spawnX, entY)) return false;
+
+      for (const tr of level.triggers) {
+        if (!badTriggers.has(tr.type)) continue;
+        if (spawnX < tr.x1 || spawnX >= tr.x2) continue;
+        // disallow if entrance intersects or is above a deadly trigger
+        if (entY + ENTRANCE_HEIGHT > tr.y1 && entY < tr.y2) return false;
+        if (entY + ENTRANCE_HEIGHT <= tr.y1 && seg.bottom >= tr.y1) return false;
+      }
+
+      const entX = spawnX - 24;
+      if (entX < 0 || entX >= level.width || entY < 0 || entY >= level.height) return false;
+
+      for (const ent of level.entrances) {
+        if (ent.x === entX && ent.y === entY) return false;
+      }
+
+      level.entrances.push({ x: entX, y: entY });
+      return true;
+    };
+
+    if (!this._benchEntrancePool) {
+      level.entrances = baseEntrances.slice();
+      const target = Math.max(...this._benchCounts);
+      for (const step of increments) {
+        let offset = 0;
+        while (level.entrances.length < target && offset <= level.width) {
+          for (const base of baseEntrances) {
+            if (level.entrances.length >= target) break;
+            const center = base.x + 24;
+            if (offset === 0) {
+              trySpawn(center);
+              continue;
+            }
+            trySpawn(center + offset);
+            if (level.entrances.length >= target) break;
+            trySpawn(center - offset);
+          }
+          offset += step;
+        }
+        if (level.entrances.length >= target) break;
+      }
+      this._benchEntrancePool = level.entrances.slice();
+    } else {
+      level.entrances = this._benchEntrancePool.slice();
+    }
+    if (entrances > level.entrances.length) {
+      entrances = level.entrances.length;
+    }
+    level.entrances.length = entrances;
+    if (this.game.getLemmingManager) {
+      const lm = this.game.getLemmingManager();
+      if (lm) lm.spawnCount = entrances;
+    }
+    const timer = this.game.getGameTimer();
+    timer.speedFactor = 6;
+    timer.benchStartupFrames = 120;
+    timer.benchStableFactor = 8;
+    this._benchStartTime = timer.getGameTime();
+    if (this.benchSequence) {
+      if (this._benchMonitor) timer.eachGameSecond.off(this._benchMonitor);
+      if (this._benchSpeedTrack) timer.eachGameSecond.off(this._benchSpeedTrack);
+      this._benchMaxSpeed = timer.speedFactor;
+      this._benchSpeedTrack = () => {
+        if (timer.speedFactor > this._benchMaxSpeed) this._benchMaxSpeed = timer.speedFactor;
+      };
+      timer.eachGameSecond.on(this._benchSpeedTrack);
+      this._benchMonitor = async () => {
+        if (timer.speedFactor < 1 ||
+                timer.getGameTime() - this._benchStartTime >= SEGMENT_DURATION) {
+          timer.eachGameSecond.off(this._benchMonitor);
+          timer.eachGameSecond.off(this._benchSpeedTrack);
+          timer.suspend();
+          const count = this.game.getLemmingManager().getLemmings().length;
+          const tps = (this._benchMaxSpeed * (1000 / timer.TIME_PER_FRAME_MS)).toFixed(1);
+          console.log(`series finished for ${entrances} entrances - ${count} lemmings - ${this._benchMaxSpeed.toFixed(1)} highest speed achieved (${tps} ticks per second)`);
+          this._benchIndex++;
+          if (this._benchIndex >= this._benchCounts.length) {
+            this._benchIndex = 0;
+            if (this._benchExtraList && ++this._benchExtraIndex < this._benchExtraList.length) {
+              this.extraLemmings = this._benchExtraList[this._benchExtraIndex];
+            } else if (this._benchExtraList) {
+              return;
+            }
+          }
+          await this.benchStart(this._benchCounts[this._benchIndex]);
+        }
+      };
+      timer.eachGameSecond.on(this._benchMonitor);
+    }
+  },
+
+  async benchMeasureExtras() {
+    this.bench = true;
+    this._benchMeasureExtras = true;
+    await this.loadLevel();
+    const lm = this.game.getLemmingManager();
+    if (lm) lm.spawnCount = this.game.level.entrances.length;
+    const vc = this.game.getVictoryCondition();
+    if (vc) vc.releaseRate = vc.getMinReleaseRate();
+    const timer = this.game.getGameTimer();
+    timer.speedFactor = 10;
+    timer.benchStartupFrames = 120;
+    timer.benchStableFactor = 2;
+    let extras = 0;
+    let prev = lm.spawnTotal;
+    let spawned = 0;
+    return new Promise(resolve => {
+      const monitor = () => {
+        const delta = lm.spawnTotal - prev;
+        prev = lm.spawnTotal;
+        spawned += delta / (extras + 1);
+        while (spawned >= 10) {
+          spawned -= 1;
+          extras += 1;
+          this.extraLemmings = extras;
+        }
+        if (timer.speedFactor < 1 || timer.getGameTime() >= 120) {
+          timer.eachGameSecond.off(monitor);
+          timer.suspend();
+          this._benchMeasureExtras = false;
+          console.log(`extra lemmings threshold reached at ${extras}`);
+          resolve(extras);
+        }
+      };
+      timer.eachGameSecond.on(monitor);
+    });
+  },
+
+  async benchSequenceStart() {
+    this._benchCounts = [50, 25, 10, 1];
+    this._benchIndex = 0;
+    const extras = await this.benchMeasureExtras();
+    this._benchExtraList = [extras, Math.floor(extras / 2), 0];
+    this._benchExtraIndex = 0;
+    this._benchBaseEntrances = null;
+    this._benchEntrancePool = null;
+    this.extraLemmings = this._benchExtraList[0];
+    await this.benchStart(this._benchCounts[0]);
+  }
+};
+export { gameViewDiagnosticsMethods };
\ No newline at end of file
diff --git a/js/game/game-view/GameViewEditorMode.js b/js/game/game-view/GameViewEditorMode.js
new file mode 100644
index 00000000..eea6fdb5
--- /dev/null
+++ b/js/game/game-view/GameViewEditorMode.js
@@ -0,0 +1,302 @@
+import {
+  BaseLogger,
+  DEFAULT_RUNTIME_PROFILE,
+  DEFAULT_RUNTIME_ROLLOUT_FLAGS,
+  EditorSession,
+  FileContainer,
+  GameFactory,
+  GameStateTypes,
+  GameTypes,
+  KeyboardShortcuts,
+  Lemming,
+  LevelIndexResolve,
+  LevelReader,
+  MIDI_FLAG_REGISTRATION_KEY,
+  MidiEventRouter,
+  MidiMapping,
+  PASSIVE_RESIZE_LISTENER,
+  STARTUP_PROFILES,
+  SoundEffectIds,
+  SoundEventTypes,
+  Stage,
+  Trigger,
+  TriggerTypes,
+  clampMidiFlagId,
+  clearAppContext,
+  cloneConfig,
+  createCrosshairFrame,
+  createEditorLevelFromClassic,
+  detectRuntimeCapabilities,
+  getDependency,
+  getGameStateTypes,
+  getGameTypes,
+  getLemmingCtor,
+  getProfileHistoryRetention,
+  getRuntimeDependency,
+  getRuntimeProfileIds,
+  getRuntimeProfilePreset,
+  getSpecialHistoryRetention,
+  getTriggerTypes,
+  hashString,
+  listSavedLevels,
+  loadEditorLevel,
+  loadSavedLevel,
+  normalizeRuntimeProfile,
+  parseBoundedNumber,
+  parseInt10,
+  resolveRuntimeRolloutFlags,
+  setAppContext,
+  toMidiFlagTriggerType
+} from './GameViewShared.js';
+const gameViewEditorModeMethods = {
+  async setupEditor() {
+    this.applyQuery();
+    this.configs = await this.gameFactory.configReader.configs;
+    this.arrayToSelect(this.elementSelectGameType, this.configs.map(c => c.name));
+    const typeIndex = this.configs.findIndex(c => c.gametype === this.gameType);
+    if (typeIndex >= 0 && this.elementSelectGameType)
+      this.elementSelectGameType.selectedIndex = typeIndex;
+    const newGameResources = await this.gameFactory.getGameResources(this.gameType);
+    this.gameResources = newGameResources;
+    const savedEntries = this._getSavedLevelEntries();
+    await this._syncLevelGroupSelect(savedEntries);
+    await this.populateLevelSelect();
+  },
+
+  ensureEditorSession() {
+    if (!this.editorSession) {
+      this.editorSession = new EditorSession();
+    }
+    return this.editorSession;
+  },
+
+  enterEditorMode() {
+    if (this.editorMode) return;
+    this.editorMode = true;
+    this.editorPlaytest = false;
+    const timer = this.game?.getGameTimer?.();
+    this._editorWasRunning = !!timer?.isRunning?.();
+    timer?.suspend?.();
+    if (this.stage) {
+      this._editorPanWasEnabled = this.stage.panEnabled !== false;
+      this.stage.panEnabled = false;
+    }
+    if (this.game) {
+      this._editorInputWasEnabled = this.game.inputEnabled !== false;
+      this.game.inputEnabled = false;
+    }
+    if (!this.editorSession) {
+      this.editorSession = new EditorSession();
+      this.editorSession.createBlank();
+    }
+  },
+
+  exitEditorMode() {
+    if (!this.editorMode) return;
+    this.editorMode = false;
+    this.editorPlaytest = false;
+    const timer = this.game?.getGameTimer?.();
+    if (this._editorWasRunning) {
+      timer?.continue?.();
+    }
+    this._editorWasRunning = false;
+    if (this.stage) {
+      this.stage.panEnabled = this._editorPanWasEnabled !== false;
+    }
+    if (this.game) {
+      this.game.inputEnabled = this._editorInputWasEnabled !== false;
+    }
+  },
+
+  toggleEditorMode() {
+    if (this.editorMode) {
+      this.exitEditorMode();
+    } else {
+      this.enterEditorMode();
+    }
+  },
+
+  setEditorPlaytest(enabled) {
+    this.editorPlaytest = !!enabled;
+    if (!this.editorMode) return;
+    const timer = this.game?.getGameTimer?.();
+    if (this.editorPlaytest) {
+      timer?.continue?.();
+    } else {
+      timer?.suspend?.();
+    }
+    if (this.game) {
+      this.game.inputEnabled = this.editorPlaytest;
+    }
+    if (this.stage) {
+      this.stage.panEnabled = this.editorPlaytest;
+    }
+  },
+
+  createBlankEditorLevel(options = {}) {
+    this.enterEditorMode();
+    const level = this.editorSession.createBlank(options);
+    if (options.render !== false) {
+      this.loadEditorPreviewLevel({ suspend: true });
+    }
+    return level;
+  },
+
+  loadEditorLevelFromText(text, options = {}) {
+    this.enterEditorMode();
+    const level = this.editorSession.loadFromText(text);
+    if (options.render !== false) {
+      this.loadEditorPreviewLevel({ suspend: true });
+    }
+    return level;
+  },
+
+  getEditorLevelText() {
+    const session = this.ensureEditorSession();
+    return session.toText();
+  },
+
+  getEditorLevelTitle() {
+    const session = this.ensureEditorSession();
+    return session.getTitle();
+  },
+
+  async loadEditorPreviewLevel(options = {}) {
+    if (this.autoMoveTimer !== null) {
+      const clearTimeoutFn = globalThis.window?.clearTimeout || globalThis.clearTimeout;
+      if (typeof clearTimeoutFn === 'function') {
+        clearTimeoutFn(this.autoMoveTimer);
+      }
+      this.autoMoveTimer = null;
+    }
+    if (!this.editorSession?.level || !this.gameFactory) return null;
+    const config = this.gameResources?.config || await this.gameFactory.getConfig(this.gameType);
+    if (!config) return null;
+    if (this.game) {
+      this.midiRouter?.detach?.();
+      this.game.stop();
+      this.game = null;
+    }
+    const gameStateTypes = getGameStateTypes();
+    this.changeHtmlText(this.elementGameState, gameStateTypes[gameStateTypes.UNKNOWN]);
+    const level = await loadEditorLevel(
+      this.editorSession.level,
+      config,
+      this.gameFactory.fileProvider,
+      {
+        levelGroupIndex: this.levelGroupIndex,
+        levelIndex: this.levelIndex
+      }
+    );
+    if (!level) return null;
+    if (this.elementSelectGameType && this.configs) {
+      const idx = this.configs.findIndex(c => c.gametype === this.gameType);
+      if (idx >= 0) this.elementSelectGameType.selectedIndex = idx;
+    }
+    if (this.elementSelectLevelGroup) this.elementSelectLevelGroup.selectedIndex = this.levelGroupIndex;
+    if (this.elementSelectLevel) this.elementSelectLevel.selectedIndex = this.levelIndex;
+    const preserveView = options.preserveView === true;
+    const prevViewport = preserveView && this.stage
+      ? {
+        x: this.stage.gameImgProps.viewPoint.x,
+        y: this.stage.gameImgProps.viewPoint.y,
+        scale: this.stage.gameImgProps.viewPoint.scale
+      }
+      : null;
+    this._preserveEditorViewport = !!prevViewport;
+
+    if (this.stage) {
+      const gameDisplay = this.stage.getGameDisplay();
+      gameDisplay.clear();
+      this.stage.resetFade();
+      level.render(gameDisplay);
+      this.stage.updateStageSize();
+      if (prevViewport) {
+        this.stage.applyViewport(
+          this.stage.gameImgProps,
+          prevViewport.x,
+          prevViewport.y,
+          prevViewport.scale
+        );
+        this.stage.redraw();
+      } else {
+        this.applyLevelViewport(level);
+      }
+    }
+    this.updateQuery();
+    this.log.debug(level);
+    await this._startWithLevel(level);
+    if (prevViewport && this.stage) {
+      this.stage.applyViewport(
+        this.stage.gameImgProps,
+        prevViewport.x,
+        prevViewport.y,
+        prevViewport.scale
+      );
+      this.stage.redraw();
+    }
+    this._preserveEditorViewport = false;
+    if (this.editorMode && this.game) {
+      this.game.inputEnabled = this.editorPlaytest;
+    } else if (this.game) {
+      this.game.inputEnabled = true;
+    }
+    if (this.editorMode && this.stage) {
+      this.stage.panEnabled = this.editorPlaytest;
+    } else if (this.stage) {
+      this.stage.panEnabled = true;
+    }
+    const timer = this.game?.getGameTimer?.();
+    if (options.suspend !== false && !this.editorPlaytest) {
+      timer?.suspend?.();
+    } else if (this.editorPlaytest) {
+      timer?.continue?.();
+    }
+    return level;
+  },
+
+  async loadEditorLevelFromSelection(options = {}) {
+    this.enterEditorMode();
+    const reader = await this._loadClassicLevelReader(
+      this.gameType,
+      this.levelGroupIndex,
+      this.levelIndex
+    );
+    if (!reader) return null;
+    const editorLevel = createEditorLevelFromClassic(reader, options);
+    this.editorSession.level = editorLevel;
+    if (options.render !== false) {
+      await this.loadEditorPreviewLevel({ suspend: true });
+    }
+    return editorLevel;
+  },
+
+  dispose() {
+    const appWindow = globalThis.window;
+    // Fall back to the global timer helpers so disposal works in headless tests.
+    if (this.autoMoveTimer != null) {
+      (appWindow?.clearTimeout || globalThis.clearTimeout)?.(this.autoMoveTimer);
+      this.autoMoveTimer = null;
+    }
+    if (this.resumeTimer != null) {
+      (appWindow?.clearTimeout || globalThis.clearTimeout)?.(this.resumeTimer);
+      this.resumeTimer = null;
+    }
+    clearAppContext(this);
+    if (this.shortcuts) {
+      this.shortcuts.dispose();
+      this.shortcuts = null;
+    }
+    if (this.midiRouter) {
+      this.midiRouter.dispose();
+      this.midiRouter = null;
+    }
+    if (this.stage && this.stage.dispose) {
+      appWindow?.removeEventListener?.('resize', this._stageResize, PASSIVE_RESIZE_LISTENER);
+      appWindow?.removeEventListener?.('orientationchange', this._stageResize, PASSIVE_RESIZE_LISTENER);
+      this.stage.dispose();
+      this.stage = null;
+    }
+  }
+};
+export { gameViewEditorModeMethods };
\ No newline at end of file
diff --git a/js/game/game-view/GameViewLevelSelection.js b/js/game/game-view/GameViewLevelSelection.js
new file mode 100644
index 00000000..d7bfcc81
--- /dev/null
+++ b/js/game/game-view/GameViewLevelSelection.js
@@ -0,0 +1,564 @@
+import {
+  BaseLogger,
+  DEFAULT_RUNTIME_PROFILE,
+  DEFAULT_RUNTIME_ROLLOUT_FLAGS,
+  EditorSession,
+  FileContainer,
+  GameFactory,
+  GameStateTypes,
+  GameTypes,
+  KeyboardShortcuts,
+  Lemming,
+  LevelIndexResolve,
+  LevelReader,
+  MIDI_FLAG_REGISTRATION_KEY,
+  MidiEventRouter,
+  MidiMapping,
+  PASSIVE_RESIZE_LISTENER,
+  STARTUP_PROFILES,
+  SoundEffectIds,
+  SoundEventTypes,
+  Stage,
+  Trigger,
+  TriggerTypes,
+  clampMidiFlagId,
+  clearAppContext,
+  cloneConfig,
+  createCrosshairFrame,
+  createEditorLevelFromClassic,
+  detectRuntimeCapabilities,
+  getDependency,
+  getGameStateTypes,
+  getGameTypes,
+  getLemmingCtor,
+  getProfileHistoryRetention,
+  getRuntimeDependency,
+  getRuntimeProfileIds,
+  getRuntimeProfilePreset,
+  getSpecialHistoryRetention,
+  getTriggerTypes,
+  hashString,
+  listSavedLevels,
+  loadEditorLevel,
+  loadSavedLevel,
+  normalizeRuntimeProfile,
+  parseBoundedNumber,
+  parseInt10,
+  resolveRuntimeRolloutFlags,
+  setAppContext,
+  toMidiFlagTriggerType
+} from './GameViewShared.js';
+const gameViewLevelSelectionMethods = {
+  async moveToLevel(moveInterval = 0) {
+    if (this.inMoveToLevel) return;
+    this.inMoveToLevel = true;
+    const oldGameType = this.gameType;
+    try {
+      const gameTypes = getGameTypes();
+      let gameType = this.gameType;
+      let levelGroupIndex = this.levelGroupIndex;
+      let levelIndex = (this.levelIndex + moveInterval) | 0;
+      let config = await this.gameFactory.getConfig(gameType);
+
+      const savedEntries = this._getSavedLevelEntries();
+      const getBaseGroupCount = cfg => cfg?.level?.order?.length ?? 0;
+      const getGroupLength = (cfg, groupIndex) => {
+        const baseGroupCount = getBaseGroupCount(cfg);
+        return this._getGroupLength(cfg, groupIndex, baseGroupCount, savedEntries);
+      };
+      const getGroupCount = (cfg) => {
+        const baseGroupCount = getBaseGroupCount(cfg);
+        return this._getGroupCount(baseGroupCount, savedEntries);
+      };
+      const isValidGameType = (type) =>
+        type > 0 && type < gameTypes.length;
+
+      if (moveInterval < 0) {
+        let rewindAttempts = 0;
+        const rewindLimit = Math.max(1, gameTypes.length * 4);
+        while (levelIndex < 0) {
+          rewindAttempts += 1;
+          if (rewindAttempts > rewindLimit) {
+            levelIndex = 0;
+            break;
+          }
+          if (levelGroupIndex > 0) {
+            levelGroupIndex--;
+            levelIndex += getGroupLength(config, levelGroupIndex);
+            continue;
+          }
+          if (gameType > 1) {
+            gameType--;
+            config = await this.gameFactory.getConfig(gameType);
+            levelGroupIndex = Math.max(0, getGroupCount(config) - 1);
+            levelIndex += getGroupLength(config, levelGroupIndex);
+            continue;
+          }
+          const lastType = gameTypes.length - 1;
+          if (isValidGameType(lastType) && lastType !== gameType) {
+            gameType = lastType;
+            config = await this.gameFactory.getConfig(gameType);
+            levelGroupIndex = Math.max(0, getGroupCount(config) - 1);
+            levelIndex += getGroupLength(config, levelGroupIndex);
+            continue;
+          }
+          levelIndex = 0;
+          break;
+        }
+      } else if (moveInterval > 0) {
+        while (true) {
+          const groupLength = getGroupLength(config, levelGroupIndex);
+          if (groupLength <= 0) {
+            if (levelGroupIndex + 1 < getGroupCount(config)) {
+              levelGroupIndex++;
+              continue;
+            }
+            gameType++;
+            if (!isValidGameType(gameType)) {
+              gameType = 1;
+            }
+            config = await this.gameFactory.getConfig(gameType);
+            levelGroupIndex = 0;
+            continue;
+          }
+          if (levelIndex < groupLength) break;
+          levelIndex -= groupLength;
+          if (levelGroupIndex + 1 < getGroupCount(config)) {
+            levelGroupIndex++;
+            continue;
+          }
+          gameType++;
+          if (!isValidGameType(gameType)) {
+            gameType = 1;
+          }
+          config = await this.gameFactory.getConfig(gameType);
+          levelGroupIndex = 0;
+        }
+      }
+
+      if (!isValidGameType(gameType)) {
+        gameType = 1;
+        levelGroupIndex = 0;
+        levelIndex = 0;
+      }
+
+      this.gameType = gameType;
+      this.levelGroupIndex = levelGroupIndex;
+      this.levelIndex = levelIndex;
+
+      if (oldGameType !== this.gameType) {
+        this.gameResources = await this.gameFactory.getGameResources(this.gameType);
+      }
+      if (this.autoExitEditorOnSelect && this.editorMode) {
+        this.exitEditorMode();
+      }
+      if (this.editorMode) {
+        await this.loadEditorLevelFromSelection();
+      } else {
+        await this.loadLevel();
+      }
+    } finally {
+      this.inMoveToLevel = false;
+    }
+  },
+
+  changeHtmlText(htmlElement, value) {
+    if (htmlElement == null) {
+      return;
+    }
+    htmlElement.innerText = value;
+  },
+
+  prefixNumbers(list) {
+    return list.map((item, idx) => `${idx + 1} - ${item}`);
+  },
+
+  strToNum(str) {
+    return parseInt10(str, 0);
+  },
+
+  clearHtmlList(htmlList) {
+    while (htmlList.options.length) {
+      htmlList.remove(0);
+    }
+  },
+
+  _getSavedLevelEntries() {
+    if (!this.includeSavedLevels) return [];
+    return listSavedLevels();
+  },
+
+  _getSavedGroupIndex(baseGroupCount, savedEntries = []) {
+    if (!this.includeSavedLevels || !savedEntries.length) return -1;
+    return baseGroupCount;
+  },
+
+  _isSavedGroupIndex(groupIndex, baseGroupCount, savedEntries = []) {
+    return groupIndex === this._getSavedGroupIndex(baseGroupCount, savedEntries);
+  },
+
+  _getGroupCount(baseGroupCount, savedEntries = []) {
+    const savedIndex = this._getSavedGroupIndex(baseGroupCount, savedEntries);
+    return savedIndex >= 0 ? baseGroupCount + 1 : baseGroupCount;
+  },
+
+  _getGroupNames(savedEntries = []) {
+    const baseGroups = this.gameResources?.getLevelGroups?.() ?? [];
+    if (!this.includeSavedLevels || !savedEntries.length) return baseGroups;
+    return [...baseGroups, 'Saved Levels'];
+  },
+
+  _getGroupLength(config, groupIndex, baseGroupCount, savedEntries = []) {
+    if (this._isSavedGroupIndex(groupIndex, baseGroupCount, savedEntries)) {
+      return savedEntries.length;
+    }
+    return config?.level?.getGroupLength?.(groupIndex) ?? 0;
+  },
+
+  _normalizeSelection(config, savedEntries = []) {
+    const baseGroupCount = config?.level?.order?.length ??
+        this.gameResources?.getLevelGroups?.().length ?? 0;
+    const groupCount = this._getGroupCount(baseGroupCount, savedEntries);
+    if (groupCount <= 0) {
+      this.levelGroupIndex = 0;
+      this.levelIndex = 0;
+      return;
+    }
+    let groupIndex = Math.min(Math.max(this.levelGroupIndex, 0), groupCount - 1);
+    let levelIndex = Math.max(this.levelIndex, 0);
+    let groupLength = this._getGroupLength(
+      config,
+      groupIndex,
+      baseGroupCount,
+      savedEntries
+    );
+    if (groupLength <= 0) {
+      let found = false;
+      for (let i = 0; i < groupCount; i++) {
+        const length = this._getGroupLength(config, i, baseGroupCount, savedEntries);
+        if (length > 0) {
+          groupIndex = i;
+          levelIndex = 0;
+          found = true;
+          break;
+        }
+      }
+      if (!found) {
+        groupIndex = 0;
+        levelIndex = 0;
+      }
+    } else if (levelIndex >= groupLength) {
+      levelIndex = 0;
+    }
+    this.levelGroupIndex = groupIndex;
+    this.levelIndex = levelIndex;
+  },
+
+  async _syncLevelGroupSelect(savedEntries = []) {
+    if (!this.elementSelectLevelGroup || !this.gameResources) return;
+    const config = await this.gameFactory.getConfig(this.gameType);
+    const groups = this._getGroupNames(savedEntries);
+    this.arrayToSelect(this.elementSelectLevelGroup, this.prefixNumbers(groups));
+    this._normalizeSelection(config, savedEntries);
+    this.elementSelectLevelGroup.selectedIndex = this.levelGroupIndex;
+  },
+
+  getEntranceFocusX(level, stageImage) {
+    if (!level || !stageImage) return 0;
+    const entrance = level.entrances?.[0];
+    if (!entrance) return 0;
+    const scale = stageImage.viewPoint.scale || 1;
+    const viewW = stageImage.canvasViewportSize.width / scale;
+    if (!isFinite(viewW) || viewW <= 0) return 0;
+    const centerX = entrance.x + 24;
+    return Math.round(centerX - viewW / 2);
+  },
+
+  applyLevelViewport(level) {
+    if (!this.stage || !level) return;
+    const stageImage = this.stage.gameImgProps;
+    const hasSavedX = Number.isFinite(level.screenPositionX);
+    const targetX = hasSavedX
+      ? level.screenPositionX
+      : this.getEntranceFocusX(level, stageImage);
+    this.stage.applyViewport(
+      stageImage,
+      targetX,
+      0,
+      stageImage.viewPoint.scale
+    );
+    this.stage.redraw();
+  },
+
+  arrayToSelect(htmlList, list) {
+    if (htmlList == null) {
+      return;
+    }
+    this.clearHtmlList(htmlList);
+    for (let i = 0; i < list.length; i++) {
+      const opt = list[i];
+      const el = document.createElement('option');
+      el.textContent = opt;
+      el.value = i.toString();
+      htmlList.appendChild(el);
+    }
+  },
+
+  async populateLevelSelect() {
+    if (!this.elementSelectLevel || !this.gameResources) return;
+    const config = await this.gameFactory.getConfig(this.gameType);
+    const savedEntries = this._getSavedLevelEntries();
+    const baseGroupCount = this.gameResources.getLevelGroups().length;
+    if (this._isSavedGroupIndex(this.levelGroupIndex, baseGroupCount, savedEntries)) {
+      const list = savedEntries.map((entry, index) => `${index + 1}: ${entry.name}`);
+      this.arrayToSelect(this.elementSelectLevel, list);
+      if (list.length) {
+        this.levelIndex = Math.min(this.levelIndex, list.length - 1);
+      } else {
+        this.levelIndex = 0;
+      }
+      this.elementSelectLevel.selectedIndex = this.levelIndex;
+      return;
+    }
+    const groupLength = this._getGroupLength(
+      config,
+      this.levelGroupIndex,
+      baseGroupCount,
+      savedEntries
+    );
+    const list = [];
+    for (let i = 0; i < groupLength; i++) {
+      try {
+        const lvl = await this.gameResources.getLevel(this.levelGroupIndex, i);
+        if (lvl) {
+          list.push((i + 1) + ': ' + lvl.name);
+          continue;
+        }
+      } catch (e) {
+        // keep slot alignment even if a level fails to load
+      }
+      list.push((i + 1) + ': [missing]');
+    }
+    this.arrayToSelect(this.elementSelectLevel, list);
+    if (list.length) {
+      this.levelIndex = Math.min(this.levelIndex, list.length - 1);
+    } else {
+      this.levelIndex = 0;
+    }
+    this.elementSelectLevel.selectedIndex = this.levelIndex;
+  },
+
+  async selectLevelGroup(newLevelGroupIndex) {
+    if (!this.gameResources) return;
+    const savedEntries = this._getSavedLevelEntries();
+    const baseGroupCount = this.gameResources.getLevelGroups().length;
+    const max = Math.max(0, this._getGroupCount(baseGroupCount, savedEntries) - 1);
+    if (newLevelGroupIndex < 0) newLevelGroupIndex = 0;
+    else if (newLevelGroupIndex > max) newLevelGroupIndex = max;
+    this.levelGroupIndex = newLevelGroupIndex;
+    this.levelIndex = 0;
+    await this.populateLevelSelect();
+    if (this.autoExitEditorOnSelect && this.editorMode) {
+      this.exitEditorMode();
+    }
+    if (this.editorMode) {
+      await this.loadEditorLevelFromSelection();
+      return;
+    }
+    this.loadLevel();
+  },
+
+  async selectGameType(newGameType) {
+    // dropdown values correspond to config array indices
+    if (this.configs && this.configs[newGameType]) {
+      newGameType = this.configs[newGameType].gametype;
+    }
+    this.gameType = newGameType;
+    this.levelGroupIndex = 0;
+    this.levelIndex = 0;
+    const newGameResources = await this.gameFactory.getGameResources(this.gameType);
+    this.gameResources = newGameResources;
+    const savedEntries = this._getSavedLevelEntries();
+    await this._syncLevelGroupSelect(savedEntries);
+    await this.populateLevelSelect();
+    if (this.autoExitEditorOnSelect && this.editorMode) {
+      this.exitEditorMode();
+    }
+    if (this.editorMode) {
+      await this.loadEditorLevelFromSelection();
+      return;
+    }
+    this.loadLevel();
+  },
+
+  async selectLevel(newLevelIndex) {
+    this.levelIndex = newLevelIndex;
+    if (this.autoExitEditorOnSelect && this.editorMode) {
+      this.exitEditorMode();
+    }
+    if (this.editorMode) {
+      await this.loadEditorLevelFromSelection();
+      return;
+    }
+    this.loadLevel();
+  },
+
+  async setup() {
+    this.applyQuery();
+    if (!this._midiMapping) {
+      this._midiMapping = await this._loadMidiMapping();
+    }
+    if (this._midiProjectConfig) {
+      this.setMidiProjectConfig(this._midiProjectConfig);
+    }
+    this.configs = await this.gameFactory.configReader.configs;
+    this.arrayToSelect(this.elementSelectGameType, this.configs.map(c => c.name));
+    const typeIndex = this.configs.findIndex(c => c.gametype === this.gameType);
+    if (typeIndex >= 0 && this.elementSelectGameType)
+      this.elementSelectGameType.selectedIndex = typeIndex;
+    const newGameResources = await this.gameFactory.getGameResources(this.gameType);
+    this.gameResources = newGameResources;
+    const savedEntries = this._getSavedLevelEntries();
+    await this._syncLevelGroupSelect(savedEntries);
+    const populatePromise = this.populateLevelSelect();
+    await this.loadLevel();
+    await populatePromise;
+    if (this.benchSequence) {
+      await this.benchSequenceStart();
+    }
+  },
+
+  async loadLevel() {
+    if (this.autoMoveTimer !== null) {
+      const clearTimeoutFn = globalThis.window?.clearTimeout || globalThis.clearTimeout;
+      if (typeof clearTimeoutFn === 'function') {
+        clearTimeoutFn(this.autoMoveTimer);
+      }
+      this.autoMoveTimer = null;
+    }
+    if (!this.gameResources) return;
+    const savedEntries = this._getSavedLevelEntries();
+    const baseGroupCount = this.gameResources.getLevelGroups().length;
+    if (this._isSavedGroupIndex(this.levelGroupIndex, baseGroupCount, savedEntries)) {
+      return this.loadSavedLevelFromSelection(savedEntries);
+    }
+    if (this.game) {
+      this.midiRouter?.detach?.();
+      this.game.stop();
+      this.game = null;
+    }
+    const gameStateTypes = getGameStateTypes();
+    this.changeHtmlText(this.elementGameState, gameStateTypes[gameStateTypes.UNKNOWN]);
+    const level = await this.gameResources.getLevel(this.levelGroupIndex, this.levelIndex);
+    if (!level) return;
+    if (this.elementSelectGameType && this.configs) {
+      const idx = this.configs.findIndex(c => c.gametype === this.gameType);
+      if (idx >= 0) this.elementSelectGameType.selectedIndex = idx;
+    }
+    if (this.elementSelectLevelGroup) this.elementSelectLevelGroup.selectedIndex = this.levelGroupIndex;
+    if (this.elementSelectLevel) this.elementSelectLevel.selectedIndex = this.levelIndex;
+    if (this.stage) {
+      const gameDisplay = this.stage.getGameDisplay();
+      gameDisplay.clear();
+      this.stage.resetFade();
+      level.render(gameDisplay);
+      this.stage.updateStageSize();
+      this.applyLevelViewport(level);
+    }
+    this.updateQuery();
+    this.log.debug(level);
+    return this.start();
+  },
+
+  async _startWithLevel(level) {
+    if (!this.gameFactory) return;
+    if (this.game != null) {
+      this.continue();
+      return;
+    }
+    const baseResources = this.gameResources;
+    if (!baseResources) return;
+    const editorResources = Object.create(baseResources);
+    editorResources.getLevel = async () => level;
+    try {
+      const game = await this.gameFactory.getGame(this.gameType, editorResources);
+      await game.loadLevel(this.levelGroupIndex, this.levelIndex);
+      game.setGameDisplay(this.stage.getGameDisplay());
+      game.setGuiDisplay(this.stage.getGuiDisplay());
+      if (this.stage && game.level) {
+        const preserveViewport = this._preserveEditorViewport === true;
+        if (!preserveViewport) {
+          this.applyLevelViewport(game.level);
+        }
+        this._preserveEditorViewport = false;
+      }
+      game.getGameTimer().speedFactor = this.gameSpeedFactor;
+      this._registerMidiFlagTriggers(game);
+      game.history?.captureReplayBaseline?.(game);
+      this.stage.setCursorSprite(createCrosshairFrame(24));
+      if (this.midiEnabled) {
+        await this.initMidiRouting();
+        this.midiRouter?.attach(game.soundEvents, { game, stage: this.stage });
+      }
+      game.start();
+      const gameStateTypes = getGameStateTypes();
+      this.changeHtmlText(this.elementGameState, gameStateTypes.toString(gameStateTypes.RUNNING));
+      game.onGameEnd.on(state => this.onGameEnd(state));
+      this.game = game;
+      if (this.cheatEnabled) this.game.cheat();
+      if (this.debug) this.game.showDebug = true;
+    } catch (e) {
+      this.log.log('Error starting custom level:', e);
+    }
+  },
+
+  async loadSavedLevelFromSelection(savedEntries = null) {
+    if (!this.gameResources || !this.gameFactory) return null;
+    const entries = savedEntries ?? this._getSavedLevelEntries();
+    if (!entries.length) return null;
+    if (this.levelIndex < 0) this.levelIndex = 0;
+    if (this.levelIndex >= entries.length) {
+      this.levelIndex = entries.length - 1;
+    }
+    const entry = entries[this.levelIndex];
+    if (!entry) return null;
+    const text = loadSavedLevel(undefined, entry.id);
+    if (!text) return null;
+    if (this.autoExitEditorOnSelect && this.editorMode) {
+      this.exitEditorMode();
+    }
+    const session = this.ensureEditorSession();
+    session.loadFromText(text);
+    return this.loadEditorPreviewLevel({ suspend: false });
+  },
+
+  async refreshSavedLevels() {
+    if (!this.includeSavedLevels || !this.gameResources) return;
+    const savedEntries = this._getSavedLevelEntries();
+    await this._syncLevelGroupSelect(savedEntries);
+    await this.populateLevelSelect();
+    const baseGroupCount = this.gameResources.getLevelGroups().length;
+    if (!this.editorMode &&
+          this._isSavedGroupIndex(this.levelGroupIndex, baseGroupCount, savedEntries)) {
+      await this.loadSavedLevelFromSelection(savedEntries);
+    }
+  },
+
+  async _loadClassicLevelReader(gameType, levelGroupIndex, levelIndex) {
+    const provider = this.gameFactory?.fileProvider;
+    if (!provider) return null;
+    const config = await this.gameFactory.getConfig(gameType);
+    if (!config) return null;
+    const resolver = new LevelIndexResolve(config);
+    const levelInfo = resolver.resolve(levelGroupIndex, levelIndex);
+    if (!levelInfo) return null;
+    const paddedFileId = ('0000' + levelInfo.fileId).slice(-3);
+    const levelDat = await provider.loadBinary(
+      config.path,
+      config.level.filePrefix + paddedFileId + '.DAT'
+    );
+    const levelsContainer = new FileContainer(levelDat);
+    return new LevelReader(levelsContainer.getPart(levelInfo.partIndex));
+  }
+};
+export { gameViewLevelSelectionMethods };
diff --git a/js/game/game-view/GameViewMidi.js b/js/game/game-view/GameViewMidi.js
new file mode 100644
index 00000000..e9db611d
--- /dev/null
+++ b/js/game/game-view/GameViewMidi.js
@@ -0,0 +1,256 @@
+import {
+  BaseLogger,
+  DEFAULT_RUNTIME_PROFILE,
+  DEFAULT_RUNTIME_ROLLOUT_FLAGS,
+  EditorSession,
+  FileContainer,
+  GameFactory,
+  GameStateTypes,
+  GameTypes,
+  KeyboardShortcuts,
+  Lemming,
+  LevelIndexResolve,
+  LevelReader,
+  MIDI_FLAG_REGISTRATION_KEY,
+  MidiEventRouter,
+  MidiMapping,
+  PASSIVE_RESIZE_LISTENER,
+  STARTUP_PROFILES,
+  SoundEffectIds,
+  SoundEventTypes,
+  Stage,
+  Trigger,
+  TriggerTypes,
+  clampMidiFlagId,
+  clearAppContext,
+  cloneConfig,
+  createCrosshairFrame,
+  createEditorLevelFromClassic,
+  detectRuntimeCapabilities,
+  getDependency,
+  getGameStateTypes,
+  getGameTypes,
+  getLemmingCtor,
+  getProfileHistoryRetention,
+  getRuntimeDependency,
+  getRuntimeProfileIds,
+  getRuntimeProfilePreset,
+  getSpecialHistoryRetention,
+  getTriggerTypes,
+  hashString,
+  listSavedLevels,
+  loadEditorLevel,
+  loadSavedLevel,
+  normalizeRuntimeProfile,
+  parseBoundedNumber,
+  parseInt10,
+  resolveRuntimeRolloutFlags,
+  setAppContext,
+  toMidiFlagTriggerType
+} from './GameViewShared.js';
+const gameViewMidiMethods = {
+  get midiOut() { return this._midiOut; },
+
+  set midiOut(output) {
+    this._midiOut = output;
+    this.midiRouter?.setOutput?.(output);
+  },
+
+  setMidiStatusHandlers({ onEnabled = null, onError = null } = {}) {
+    this._midiStatusHandlers = {
+      onEnabled: typeof onEnabled === 'function' ? onEnabled : null,
+      onError: typeof onError === 'function' ? onError : null
+    };
+  },
+
+  _getWebMidi() {
+    return getRuntimeDependency('webMidi', null);
+  },
+
+  _formatMidiEnableError(err) {
+    const rawMessage = err?.message ? String(err.message) : String(err || '');
+    const runtimeWindow = getRuntimeDependency('window', null);
+    const isSecure = runtimeWindow
+      ? (runtimeWindow.isSecureContext || runtimeWindow.location?.protocol === 'https:' || runtimeWindow.location?.hostname === 'localhost')
+      : true;
+    if (!isSecure) {
+      return 'WebMIDI requires HTTPS or localhost.';
+    }
+    if (err?.name === 'NotAllowedError' || /permission/i.test(rawMessage)) {
+      return 'WebMIDI permission denied. Check browser permissions.';
+    }
+    if (err?.name === 'SecurityError' || /secure context/i.test(rawMessage)) {
+      return 'WebMIDI requires HTTPS or localhost.';
+    }
+    if (err?.name === 'NotSupportedError') {
+      return 'WebMIDI is not supported in this browser.';
+    }
+    if (!rawMessage) {
+      return 'WebMIDI enable failed.';
+    }
+    return `WebMIDI enable failed: ${rawMessage}`;
+  },
+
+  async _ensureWebMidiEnabled() {
+    const webMidi = this._getWebMidi();
+    if (!webMidi) {
+      this._midiStatusHandlers?.onError?.('WebMIDI is not supported in this browser.');
+      return null;
+    }
+    if (webMidi.enabled) return webMidi;
+    try {
+      await webMidi.enable();
+      this._midiStatusHandlers?.onEnabled?.();
+      return webMidi;
+    } catch (e) {
+      this.log.log('WebMidi enable failed', e);
+      this._midiStatusHandlers?.onError?.(this._formatMidiEnableError(e));
+      return null;
+    }
+  },
+
+  async _loadMidiMapping() {
+    if (!this.gameFactory?.fileProvider) return new MidiMapping();
+    try {
+      const text = await this.gameFactory.fileProvider.loadString('midi-mapping.json');
+      const mapping = MidiMapping.fromJson(text);
+      this._midiSchemaHash = hashString(text);
+      this._midiBaseConfig = cloneConfig(mapping.config);
+      return mapping;
+    } catch (e) {
+      this.log.log('Unable to load midi-mapping.json, using defaults', e);
+      const mapping = new MidiMapping();
+      this._midiSchemaHash = hashString(JSON.stringify(mapping.config));
+      this._midiBaseConfig = cloneConfig(mapping.config);
+      return mapping;
+    }
+  },
+
+  async initMidiRouting() {
+    if (!this.midiEnabled) {
+      this.midiRouter?.detach?.();
+      this.midiRouter?.scheduler?.allNotesOff?.();
+      return null;
+    }
+    if (!this.midiRouter) {
+      await this._ensureWebMidiEnabled();
+      this._midiMapping = this._midiMapping || await this._loadMidiMapping();
+      if (this._midiProjectConfig) {
+        this.setMidiProjectConfig(this._midiProjectConfig);
+      }
+      const Router = getDependency('MidiEventRouter', MidiEventRouter);
+      this.midiRouter = new Router(this._midiMapping);
+    }
+    const webMidi = this._getWebMidi();
+    if (webMidi?.enabled) {
+      this.midiRouter?.setOutputs?.(webMidi.outputs || []);
+    }
+    if (!this._midiOut) {
+      if (webMidi?.enabled && webMidi.outputs?.length) {
+        this._midiOut = webMidi.outputs[0];
+      }
+    }
+    if (this._midiOut) this.midiRouter.setOutput(this._midiOut);
+    return this.midiRouter;
+  },
+
+  async setMidiEnabled(enabled) {
+    this.midiEnabled = !!enabled;
+    if (!this.midiEnabled) {
+      this.midiRouter?.detach?.();
+      this.midiRouter?.scheduler?.allNotesOff?.();
+      return;
+    }
+    await this.initMidiRouting();
+    if (this.game?.soundEvents) {
+      this.midiRouter?.attach(this.game.soundEvents, { game: this.game, stage: this.stage });
+    }
+  },
+
+  setMidiProjectConfig(config) {
+    this._midiProjectConfig = cloneConfig(config || {});
+    this._midiMapping = new MidiMapping(this._midiProjectConfig);
+    if (this.midiRouter) this.midiRouter.setMapping(this._midiMapping);
+  },
+
+  getMidiConfig() {
+    return this._midiMapping?.config ?? null;
+  },
+
+  getMidiBaseConfig() {
+    return this._midiBaseConfig;
+  },
+
+  getMidiSchemaHash() {
+    return this._midiSchemaHash;
+  },
+
+  _registerMidiFlagTriggers(game) {
+    if (!game?.triggerManager || !game?.soundEvents) return;
+    if (game[MIDI_FLAG_REGISTRATION_KEY]) return;
+    game[MIDI_FLAG_REGISTRATION_KEY] = true;
+    const flags = Array.isArray(game?.level?.midiFlags) ? game.level.midiFlags : [];
+    if (!flags.length) return;
+    for (let i = 0; i < flags.length; i += 1) {
+      const flag = flags[i] || {};
+      const midiFlagId = clampMidiFlagId(Number(flag.id));
+      const triggerType = Number.isFinite(flag.triggerType)
+        ? flag.triggerType
+        : toMidiFlagTriggerType(midiFlagId);
+      if (!Number.isFinite(triggerType)) continue;
+      const x1 = Number(flag.x1);
+      const y1 = Number(flag.y1);
+      const x2 = Number(flag.x2);
+      const y2 = Number(flag.y2);
+      if (!Number.isFinite(x1) || !Number.isFinite(y1) || !Number.isFinite(x2) || !Number.isFinite(y2)) {
+        continue;
+      }
+      const cooldownTicks = Number.isFinite(flag.cooldownTicks)
+        ? Math.max(0, Math.trunc(flag.cooldownTicks))
+        : 0;
+      const owner = {
+        id: `midi_flag_${midiFlagId ?? i}_${i}`,
+        __historyKind: 'midi_flag',
+        __historyData: {
+          midiFlagId,
+          triggerType,
+          pieceId: flag.pieceId ?? null
+        },
+        onTrigger: (_tick, lemming, trigger, x, y) => {
+          game.soundEvents.emit({
+            type: SoundEventTypes.TRAP_TRIGGER,
+            sfxId: SoundEffectIds.NONE,
+            triggerType,
+            midiFlagId,
+            pieceId: flag.pieceId ?? null,
+            x,
+            y,
+            lemmingId: lemming?.id ?? null,
+            triggerBounds: {
+              x1: trigger?.x1 ?? x1,
+              y1: trigger?.y1 ?? y1,
+              x2: trigger?.x2 ?? x2,
+              y2: trigger?.y2 ?? y2
+            }
+          });
+        }
+      };
+      const trigger = new Trigger(
+        TriggerTypes.NO_TRIGGER,
+        x1,
+        y1,
+        x2,
+        y2,
+        cooldownTicks,
+        -1,
+        owner
+      );
+      if (typeof game.triggerManager.addObserver === 'function') {
+        game.triggerManager.addObserver(trigger);
+      } else {
+        game.triggerManager.add(trigger);
+      }
+    }
+  }
+};
+export { gameViewMidiMethods };
diff --git a/js/game/game-view/GameViewQuery.js b/js/game/game-view/GameViewQuery.js
new file mode 100644
index 00000000..ae64c7ca
--- /dev/null
+++ b/js/game/game-view/GameViewQuery.js
@@ -0,0 +1,358 @@
+import {
+  BaseLogger,
+  DEFAULT_RUNTIME_PROFILE,
+  DEFAULT_RUNTIME_ROLLOUT_FLAGS,
+  EditorSession,
+  FileContainer,
+  GameFactory,
+  GameStateTypes,
+  GameTypes,
+  KeyboardShortcuts,
+  Lemming,
+  LevelIndexResolve,
+  LevelReader,
+  MIDI_FLAG_REGISTRATION_KEY,
+  MidiEventRouter,
+  MidiMapping,
+  PASSIVE_RESIZE_LISTENER,
+  STARTUP_PROFILES,
+  SoundEffectIds,
+  SoundEventTypes,
+  Stage,
+  Trigger,
+  TriggerTypes,
+  clampMidiFlagId,
+  clearAppContext,
+  cloneConfig,
+  createCrosshairFrame,
+  createEditorLevelFromClassic,
+  detectRuntimeCapabilities,
+  getDependency,
+  getGameStateTypes,
+  getGameTypes,
+  getLemmingCtor,
+  getProfileHistoryRetention,
+  getRuntimeDependency,
+  getRuntimeProfileIds,
+  getRuntimeProfilePreset,
+  getSpecialHistoryRetention,
+  getTriggerTypes,
+  hashString,
+  listSavedLevels,
+  loadEditorLevel,
+  loadSavedLevel,
+  normalizeRuntimeProfile,
+  parseBoundedNumber,
+  parseInt10,
+  resolveRuntimeRolloutFlags,
+  setAppContext,
+  toMidiFlagTriggerType
+} from './GameViewShared.js';
+const gameViewQueryMethods = {
+  enableDebug() {
+    if (this.game == null) {
+      return;
+    }
+    this.game.setDebugMode(true);
+  },
+
+  parseNumber(query, names, def, min, max, multiplier = 1) {
+    for (const name of names) {
+      const raw = query.get(name);
+      if (raw !== null) {
+        const parsed = parseBoundedNumber(raw, {
+          fallback: null,
+          min,
+          max,
+          multiplier
+        });
+        if (parsed != null) return parsed;
+      }
+    }
+    return def;
+  },
+
+  parseBool(query, names, def = false) {
+    for (const name of names) {
+      if (query.has(name)) {
+        const raw = query.get(name);
+        if (raw == null || raw === '') return true;
+        const normalized = String(raw).trim().toLowerCase();
+        if (['1', 'true', 'yes', 'on'].includes(normalized)) return true;
+        if (['0', 'false', 'no', 'off'].includes(normalized)) return false;
+        return def;
+      }
+    }
+    return def;
+  },
+
+  parseProfileBool(query, names, fallback = false) {
+    for (const name of names) {
+      if (query.has(name)) {
+        return this.parseBool(query, names, fallback);
+      }
+    }
+    return fallback;
+  },
+
+  applyQuery() {
+    this.gameType = 1;
+    const windowRef = getRuntimeDependency('window', null);
+    const query = windowRef?.location?.search
+      ? new URLSearchParams(windowRef.location.search)
+      : new URLSearchParams('');
+    this.rolloutFlags = resolveRuntimeRolloutFlags({
+      query,
+      runtimeFlags: getRuntimeDependency('rolloutFlags', null)
+    });
+    this.runtimeCapabilities = detectRuntimeCapabilities({
+      windowRef,
+      navigatorRef: getRuntimeDependency('navigator', windowRef?.navigator || null),
+      webMidi: getRuntimeDependency('webMidi', windowRef?.WebMidi || null)
+    });
+    this.gameType = this.parseNumber(query, ['version', 'v'], 1, 1, 6);
+    this.levelGroupIndex = this.parseNumber(query, ['difficulty', 'd'], 1, 1, 6) - 1;
+    this.levelIndex = this.parseNumber(query, ['level', 'l'], 1, 1, 100) - 1;
+    this.gameSpeedFactor = this.parseNumber(query, ['speed', 's'], 1, 0, 100);
+    // values above normal correspond to discrete steps
+    if (this.gameSpeedFactor > 1) {
+      this.gameSpeedFactor = Math.round(this.gameSpeedFactor);
+    }
+    this.cheatEnabled = this.parseBool(query, ['cheat', 'c']);
+    this.debug = this.parseBool(query, ['debug', 'dbg']);
+    this.bench = this.parseBool(query, ['bench', 'b']);
+    this.bench2 = this.parseBool(query, ['bench2', 'b2']);
+    this.benchReverse = this.parseBool(query, ['benchReverse', 'bR']);
+    this.benchSequence = this.parseBool(query, ['benchSequence', 'bs']);
+    this.preserveHistory = this.parseBool(query, ['preserveHistory', 'ph']);
+    if (this.bench || this.bench2 || this.benchSequence) {
+      this.benchReverse = false;
+    }
+    this.endless = this.parseBool(query, ['endless', 'e']);
+    this.nukeAfter = this.parseNumber(query, ['nukeAfter', 'na'], 0, 1, 60, 10);
+    this.extraLemmings = this.parseNumber(query, ['extra', 'ex'], 0, 1, 1000);
+    this.scale = this.parseNumber(query, ['scale', 'sc'], 0, 0.0125, 8);
+    this.laggedOut = 0;
+
+    this.shortcut = false;
+    if (query.get('shortcut') || query.get('_')) {
+      this.shortcut = (query.get('shortcut') || query.get('_')) === 'true';
+    }
+    const profileRaw = query.get('profile') || query.get('pr') || DEFAULT_RUNTIME_PROFILE;
+    this.startupProfile = normalizeRuntimeProfile(profileRaw);
+    if (!STARTUP_PROFILES.has(this.startupProfile)) {
+      this.startupProfile = DEFAULT_RUNTIME_PROFILE;
+    }
+    const profilePreset = getRuntimeProfilePreset(this.startupProfile);
+    const instrumentation = profilePreset.instrumentation || {};
+    const rendering = profilePreset.rendering || {};
+    this.performanceAPI = this.parseProfileBool(
+      query,
+      ['performanceAPI', 'pa'],
+      instrumentation.performanceAPI === true
+    );
+    this.perfMetrics = this.parseProfileBool(
+      query,
+      ['perfMetrics', 'pm'],
+      instrumentation.perfMetrics === true || this.performanceAPI
+    );
+    this.perfOverlay = this.parseProfileBool(
+      query,
+      ['perfOverlay', 'po'],
+      instrumentation.perfOverlay === true
+    );
+    const renderRolloutEnabled = this.rolloutFlags?.renderPresentPath !== false;
+    this.offscreenPresentExperiment = renderRolloutEnabled && this.parseProfileBool(
+      query,
+      ['offscreenPresent'],
+      rendering.offscreenPresentExperiment === true
+    );
+    this.workerOffscreenExperiment = renderRolloutEnabled && this.parseProfileBool(
+      query,
+      ['workerOffscreen'],
+      rendering.workerOffscreenExperiment === true
+    );
+    this.stage?.setRenderExperimentFlags?.({
+      offscreenPresent: this.offscreenPresentExperiment,
+      workerOffscreen: this.workerOffscreenExperiment
+    });
+  },
+
+  updateQuery() {
+    const windowRef = getRuntimeDependency('window', null);
+    const params = windowRef?.location?.search
+      ? new URLSearchParams(windowRef.location.search)
+      : new URLSearchParams('');
+    const setParam = (longName, shortName, value, def, always) => {
+      params.delete(longName);
+      if (shortName) params.delete(shortName);
+      if (always || (value !== undefined && value !== def)) {
+        params.set(this.shortcut && shortName ? shortName : longName, value);
+      }
+    };
+
+    // main game state should always remain visible
+    setParam('version', 'v', this.gameType, undefined, true);
+    setParam('difficulty', 'd', this.levelGroupIndex + 1, undefined, true);
+    setParam('level', 'l', this.levelIndex + 1, undefined, true);
+    setParam('speed', 's', this.gameSpeedFactor, undefined, true);
+    setParam('cheat', 'c', this.cheatEnabled, undefined, true);
+
+    // optional flags only appear when non-default
+    setParam('debug', 'dbg', this.debug, false);
+    setParam('bench', 'b', this.bench, false);
+    setParam('bench2', 'b2', this.bench2, false);
+    setParam('benchReverse', 'bR', this.benchReverse, false);
+    setParam('benchSequence', 'bs', this.benchSequence, false);
+    setParam('preserveHistory', 'ph', this.preserveHistory, false);
+    setParam('endless', 'e', this.endless, false);
+    setParam('nukeAfter', 'na', this.nukeAfter ? this.nukeAfter / 10 : undefined);
+    setParam('extra', 'ex', this.extraLemmings, 0);
+    setParam('scale', 'sc', this.scale, 0);
+    setParam('performanceAPI', 'pa', this.performanceAPI, false);
+    setParam('perfMetrics', 'pm', this.perfMetrics, this.performanceAPI);
+    setParam('perfOverlay', 'po', this.perfOverlay, false);
+    setParam('offscreenPresent', null, this.offscreenPresentExperiment, false);
+    setParam('workerOffscreen', null, this.workerOffscreenExperiment, false);
+    setParam('profile', 'pr', this.startupProfile, DEFAULT_RUNTIME_PROFILE);
+
+    if (this.shortcut) {
+      params.set('_', true);
+    } else {
+      params.delete('_');
+    }
+
+    this.setHistoryState(params);
+  },
+
+  getPerfOverlayData() {
+    const timer = this.game?.getGameTimer?.() || null;
+    const lines = [];
+    if (timer) {
+      lines.push(`tick ${timer.tickIndex ?? 0} speed ${Number(timer.speedFactor || 0).toFixed(2)}`);
+      lines.push(`tps ${Number(timer.tps || 0).toFixed(1)} frame ${Number(timer.frameTime || 0).toFixed(2)}ms`);
+    }
+    if (this.bench || this.bench2 || this.benchReverse || this.benchSequence) {
+      lines.push(`bench steps ${this.steps | 0} lag ${this.laggedOut | 0}`);
+    }
+    if (this.game?.timeTravel?.isReversing) {
+      lines.push('reverse playback active');
+    }
+    return { lines };
+  },
+
+  resolveHistoryRetentionPolicy() {
+    if (this._historyRetentionOverride) {
+      return { ...this._historyRetentionOverride };
+    }
+    let profilePolicy = getProfileHistoryRetention(this.startupProfile);
+    if (this.endless) {
+      profilePolicy = getSpecialHistoryRetention('endless') || profilePolicy;
+    }
+    if (this.bench || this.bench2 || this.benchReverse || this.benchSequence) {
+      profilePolicy = getSpecialHistoryRetention('bench') || profilePolicy;
+    }
+    if (this.rolloutFlags?.historyCodec === false) {
+      profilePolicy = {
+        ...profilePolicy,
+        coldBlockAgeTicks: 0,
+        enableColdBlockCompression: false,
+        enableColdBlockDedupe: false
+      };
+    }
+    return { ...profilePolicy };
+  },
+
+  setHistoryRetentionPolicy(policy) {
+    if (!policy || typeof policy !== 'object') {
+      this._historyRetentionOverride = null;
+      return null;
+    }
+    this._historyRetentionOverride = { ...policy };
+    return { ...this._historyRetentionOverride };
+  },
+
+  applyProfileHistoryRetentionPolicy() {
+    const policy = this.resolveHistoryRetentionPolicy();
+    this._historyRetentionPolicy = { ...policy };
+    return { ...policy };
+  },
+
+  _applyHistoryRetentionPolicy(game, replayString = null) {
+    const basePolicy = this.resolveHistoryRetentionPolicy();
+    const preserveFutureHistory = !!(this.preserveHistory || replayString != null);
+    const requested = {
+      ...basePolicy,
+      preserveFutureHistory
+    };
+    let applied = requested;
+    if (game?.timeTravel?.setHistoryRetention) {
+      applied = game.timeTravel.setHistoryRetention(requested) || requested;
+    } else if (game?.history?.configureRetention) {
+      applied = game.history.configureRetention(requested) || requested;
+    }
+    this._historyRetentionPolicy = { ...applied };
+    return { ...this._historyRetentionPolicy };
+  },
+
+  getRuntimeDiagnostics() {
+    const windowRef = getRuntimeDependency('window', null);
+    const capabilities = detectRuntimeCapabilities({
+      windowRef,
+      navigatorRef: getRuntimeDependency('navigator', windowRef?.navigator || null),
+      webMidi: getRuntimeDependency('webMidi', windowRef?.WebMidi || null)
+    });
+    this.runtimeCapabilities = capabilities;
+    const fileProviderStats = this.gameFactory?.fileProvider?.getCacheStats?.() || null;
+    const sanitizedFileProviderStats = fileProviderStats
+      ? {
+        memoryEntries: fileProviderStats.memoryEntries ?? 0,
+        localStorageBytes: fileProviderStats.localStorageBytes ?? 0,
+        indexedDbBytes: fileProviderStats.indexedDbBytes ?? 0
+      }
+      : null;
+    return {
+      profile: this.startupProfile || DEFAULT_RUNTIME_PROFILE,
+      rolloutFlags: {
+        ...DEFAULT_RUNTIME_ROLLOUT_FLAGS,
+        ...(this.rolloutFlags || {})
+      },
+      capabilities,
+      history: {
+        retention: this._historyRetentionPolicy
+          ? { ...this._historyRetentionPolicy }
+          : this.resolveHistoryRetentionPolicy()
+      },
+      featureFlags: {
+        performanceAPI: !!this.performanceAPI,
+        perfMetrics: !!this.perfMetrics,
+        perfOverlay: !!this.perfOverlay,
+        offscreenPresentExperiment: !!this.offscreenPresentExperiment,
+        workerOffscreenExperiment: !!this.workerOffscreenExperiment,
+        debug: !!this.debug,
+        cheatEnabled: !!this.cheatEnabled,
+        endless: !!this.endless,
+        midiEnabled: !!this.midiEnabled,
+        editorMode: !!this.editorMode,
+        editorPlaytest: !!this.editorPlaytest,
+        preserveHistory: !!this.preserveHistory,
+        includeSavedLevels: !!this.includeSavedLevels,
+        bench: !!this.bench,
+        bench2: !!this.bench2,
+        benchReverse: !!this.benchReverse,
+        benchSequence: !!this.benchSequence
+      },
+      caches: {
+        fileProvider: sanitizedFileProviderStats
+      },
+      renderExperiments: this.stage?.getRenderExperimentStatus?.() || null
+    };
+  },
+
+  setHistoryState(params) {
+    const query = params instanceof URLSearchParams ? params : new URLSearchParams(params);
+    const historyRef = getRuntimeDependency('history', null);
+    historyRef?.replaceState?.(null, null, '?' + query.toString());
+  }
+};
+export { gameViewQueryMethods };
diff --git a/js/game/game-view/GameViewRuntime.js b/js/game/game-view/GameViewRuntime.js
new file mode 100644
index 00000000..586b1fad
--- /dev/null
+++ b/js/game/game-view/GameViewRuntime.js
@@ -0,0 +1,255 @@
+import {
+  BaseLogger,
+  DEFAULT_RUNTIME_PROFILE,
+  DEFAULT_RUNTIME_ROLLOUT_FLAGS,
+  EditorSession,
+  FileContainer,
+  GameFactory,
+  GameStateTypes,
+  GameTypes,
+  KeyboardShortcuts,
+  Lemming,
+  LevelIndexResolve,
+  LevelReader,
+  MIDI_FLAG_REGISTRATION_KEY,
+  MidiEventRouter,
+  MidiMapping,
+  PASSIVE_RESIZE_LISTENER,
+  STARTUP_PROFILES,
+  SoundEffectIds,
+  SoundEventTypes,
+  Stage,
+  Trigger,
+  TriggerTypes,
+  clampMidiFlagId,
+  clearAppContext,
+  cloneConfig,
+  createCrosshairFrame,
+  createEditorLevelFromClassic,
+  detectRuntimeCapabilities,
+  getDependency,
+  getGameStateTypes,
+  getGameTypes,
+  getLemmingCtor,
+  getProfileHistoryRetention,
+  getRuntimeDependency,
+  getRuntimeProfileIds,
+  getRuntimeProfilePreset,
+  getSpecialHistoryRetention,
+  getTriggerTypes,
+  hashString,
+  listSavedLevels,
+  loadEditorLevel,
+  loadSavedLevel,
+  normalizeRuntimeProfile,
+  parseBoundedNumber,
+  parseInt10,
+  resolveRuntimeRolloutFlags,
+  setAppContext,
+  toMidiFlagTriggerType
+} from './GameViewShared.js';
+const gameViewRuntimeMethods = {
+  set gameCanvas(el) {
+    const appWindow = globalThis.window;
+    if (this.stage && this.stage.dispose) {
+      appWindow?.removeEventListener?.('resize', this._stageResize, PASSIVE_RESIZE_LISTENER);
+      appWindow?.removeEventListener?.('orientationchange', this._stageResize, PASSIVE_RESIZE_LISTENER);
+      this.stage.dispose();
+    }
+    const StageCtor = getDependency('Stage', Stage);
+    this.stage = new StageCtor(el, {
+      getScale: () => this.scale
+    });
+    this.stage.setPerfOverlay?.(this.perfOverlay, () => this.getPerfOverlayData());
+    this.stage.setRenderExperimentFlags?.({
+      offscreenPresent: this.offscreenPresentExperiment,
+      workerOffscreen: this.workerOffscreenExperiment
+    });
+    this._stageResize = () => this.stage.scheduleUpdateStageSize();
+    appWindow?.addEventListener?.('resize', this._stageResize, PASSIVE_RESIZE_LISTENER);
+    appWindow?.addEventListener?.('orientationchange', this._stageResize, PASSIVE_RESIZE_LISTENER);
+    this._stageResize();
+  },
+
+  async start(replayString) {
+    if (!this.gameFactory) return;
+    if (this.game != null) {
+      this.continue();
+      return;
+    }
+    try {
+      const game = await this.gameFactory.getGame(this.gameType, this.gameResources);
+      await game.loadLevel(this.levelGroupIndex, this.levelIndex);
+      if (replayString != null) {
+        game.getCommandManager().loadReplay(replayString);
+      }
+      game.setGameDisplay(this.stage.getGameDisplay());
+      game.setGuiDisplay(this.stage.getGuiDisplay());
+      if (this.stage && game.level) {
+        this.applyLevelViewport(game.level);
+      }
+      game.getGameTimer().speedFactor = this.gameSpeedFactor;
+      this._applyHistoryRetentionPolicy(game, replayString);
+      if (this.preserveHistory || replayString != null) {
+        game.history?.setPreserveFutureHistory?.(true);
+      }
+      this._registerMidiFlagTriggers(game);
+      game.history?.captureReplayBaseline?.(game);
+      // Display a custom crosshair cursor sized relative to a lemming
+      this.stage.setCursorSprite(createCrosshairFrame(24));
+      if (this.midiEnabled) {
+        await this.initMidiRouting();
+        this.midiRouter?.attach(game.soundEvents, { game, stage: this.stage });
+      }
+      game.start();
+      const gameStateTypes = getGameStateTypes();
+      this.changeHtmlText(this.elementGameState, gameStateTypes.toString(gameStateTypes.RUNNING));
+      game.onGameEnd.on(state => this.onGameEnd(state));
+      this.game = game;
+      if (this.cheatEnabled) this.game.cheat();
+      if (this.debug) this.game.showDebug = true;
+    } catch (e) {
+      this.log.log('Error starting game:', e);
+    }
+  },
+
+  onGameEnd(gameResult) {
+    const gameStateTypes = getGameStateTypes();
+    this.changeHtmlText(this.elementGameState, gameStateTypes.toString(gameResult.state));
+    this.stage.startFadeOut();
+    console.dir(gameResult);
+    const appWindow = globalThis.window;
+    const setTimeoutFn = appWindow?.setTimeout || globalThis.setTimeout;
+    if (typeof setTimeoutFn !== 'function') {
+      return;
+    }
+    this.autoMoveTimer = setTimeoutFn(() => {
+      const gameStateTypes = getGameStateTypes();
+      if (gameResult.state === gameStateTypes.SUCCEEDED) {
+        /// move to next level
+        this.moveToLevel(1);
+      } else {
+        /// redo this level
+        this.moveToLevel(0);
+      }
+      this.autoMoveTimer = null;
+    }, 2500);
+  },
+
+  async loadReplay(replayString) {
+    await this.start(replayString);
+  },
+
+  cheat() {
+    if (this.game == null) {
+      return;
+    }
+    this.game.cheat();
+  },
+
+  suspend() {
+    if (this.game == null) {
+      return;
+    }
+    this.game.getGameTimer().suspend();
+  },
+
+  suspendWithColor(color) {
+    if (this.game == null) {
+      return;
+    }
+    const appWindow = globalThis.window;
+    const clearTimeoutFn = appWindow?.clearTimeout || globalThis.clearTimeout;
+    const setTimeoutFn = appWindow?.setTimeout || globalThis.setTimeout;
+    this.game.getGameTimer().suspend();
+    if (this.stage?.startOverlayFade) {
+      let rect = null;
+      if (this.bench || this.bench2 || this.benchReverse) {
+        const gui = this.stage.guiImgProps;
+        const scale = gui.viewPoint.scale;
+        rect = {
+          x: gui.x + 160 * scale,
+          y: gui.y + 32 * scale,
+          width: 16 * scale,
+          height: 10 * scale
+        };
+      }
+      this.stage.startOverlayFade(color, rect);
+    }
+    if (this.resumeTimer) {
+      if (typeof clearTimeoutFn === 'function') {
+        clearTimeoutFn(this.resumeTimer);
+      }
+      this.resumeTimer = null;
+    }
+    if (typeof setTimeoutFn !== 'function') {
+      return;
+    }
+    this.resumeTimer = setTimeoutFn(() => {
+      if (this.game) this.game.getGameTimer().continue();
+      this.resumeTimer = null;
+    }, 2000);
+  },
+
+  continue () {
+    if (this.game == null) {
+      return;
+    }
+    this.game.getGameTimer().continue();
+  },
+
+  nextFrame() {
+    if (this.game == null) {
+      return;
+    }
+    const timer = this.game.getGameTimer();
+    if (!timer) return;
+    if (this.game.timeTravel?.isReversing) {
+      this.game.timeTravel.stopReverse();
+    }
+    this.game.history?.truncateAfter?.(timer.tickIndex);
+    timer.tick(1);
+    if (this.game.gameGui) {
+      this.game.gameGui.gameTimeChanged = true;
+    }
+    this.game.render();
+  },
+
+  prevFrame() {
+    if (this.game == null) {
+      return;
+    }
+    const timeTravel = this.game.timeTravel;
+    if (timeTravel?.stepBackward) {
+      timeTravel.stepBackward(1);
+      return;
+    }
+    this.game.getGameTimer().tick(-1);
+    this.game.render();
+  },
+
+  selectSpeedFactor(newSpeed) {
+    if (this.game == null) {
+      return;
+    }
+    this.gameSpeedFactor = newSpeed;
+    this.game.getGameTimer().speedFactor = newSpeed;
+  },
+
+  playMusic(moveInterval) {
+
+  },
+
+  stopMusic() {
+
+  },
+
+  stopSound() {
+
+  },
+
+  playSound(moveInterval) {
+
+  }
+};
+export { gameViewRuntimeMethods };
\ No newline at end of file
diff --git a/js/game/game-view/GameViewShared.js b/js/game/game-view/GameViewShared.js
new file mode 100644
index 00000000..3c4efc8f
--- /dev/null
+++ b/js/game/game-view/GameViewShared.js
@@ -0,0 +1,110 @@
+import { createCrosshairFrame } from '../../input/CrosshairCursor.js';
+import { GameFactory } from '../GameFactory.js';
+import { GameStateTypes } from '../GameStateTypes.js';
+import { GameTypes } from '../GameTypes.js';
+import { KeyboardShortcuts } from '../../input/KeyboardShortcuts.js';
+import { Lemming } from '../../lemmings/Lemming.js';
+import { BaseLogger } from '../../util/LogHandler.js';
+import { MidiEventRouter } from '../../midi/MidiEventRouter.js';
+import { MidiMapping } from '../../midi/MidiMapping.js';
+import { Stage } from '../../render/Stage.js';
+import { Trigger } from '../../level/Trigger.js';
+import { TriggerTypes } from '../../level/TriggerTypes.js';
+import { SoundEffectIds, SoundEventTypes } from '../SoundEvents.js';
+import { FileContainer } from '../../data/FileContainer.js';
+import { LevelIndexResolve } from '../../level/LevelIndexResolve.js';
+import { LevelReader } from '../../level/LevelReader.js';
+import { EditorSession } from '../../editor/EditorSession.js';
+import { createEditorLevelFromClassic } from '../../editor/ClassicLevelConverter.js';
+import { loadEditorLevel } from '../../editor/EditorLevelLoader.js';
+import { listSavedLevels, loadSavedLevel } from '../../editor/EditorStorage.js';
+import {
+  getDependency,
+  setAppContext,
+  clearAppContext,
+  getRuntimeDependency
+} from '../../core/dependencies.js';
+import { clampMidiFlagId, toMidiFlagTriggerType } from '../../midi/MidiFlagTriggers.js';
+import { parseBoundedNumber, parseInt10 } from '../../core/numberParsing.js';
+import {
+  DEFAULT_RUNTIME_PROFILE,
+  getProfileHistoryRetention,
+  getRuntimeProfileIds,
+  getRuntimeProfilePreset,
+  getSpecialHistoryRetention,
+  normalizeRuntimeProfile
+} from '../../core/runtimeProfiles.js';
+import { detectRuntimeCapabilities } from '../../core/capabilityMatrix.js';
+import {
+  DEFAULT_RUNTIME_ROLLOUT_FLAGS,
+  resolveRuntimeRolloutFlags
+} from '../../core/rolloutFlags.js';
+
+const getGameTypes = () => getDependency('GameTypes', GameTypes);
+const getGameStateTypes = () => getDependency('GameStateTypes', GameStateTypes);
+const getTriggerTypes = () => getDependency('TriggerTypes', TriggerTypes);
+const getLemmingCtor = () => getDependency('Lemming', Lemming);
+const STARTUP_PROFILES = new Set(getRuntimeProfileIds());
+const MIDI_FLAG_REGISTRATION_KEY = Symbol('midi-flag-registration');
+const PASSIVE_RESIZE_LISTENER = Object.freeze({ passive: true });
+const cloneConfig = (config) => JSON.parse(JSON.stringify(config || {}));
+const hashString = (input) => {
+  let hash = 2166136261;
+  const str = String(input ?? '');
+  for (let i = 0; i < str.length; i++) {
+    hash ^= str.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16);
+};
+
+export {
+  BaseLogger,
+  DEFAULT_RUNTIME_PROFILE,
+  DEFAULT_RUNTIME_ROLLOUT_FLAGS,
+  EditorSession,
+  FileContainer,
+  GameFactory,
+  GameStateTypes,
+  GameTypes,
+  KeyboardShortcuts,
+  Lemming,
+  LevelIndexResolve,
+  LevelReader,
+  MIDI_FLAG_REGISTRATION_KEY,
+  MidiEventRouter,
+  MidiMapping,
+  PASSIVE_RESIZE_LISTENER,
+  STARTUP_PROFILES,
+  SoundEffectIds,
+  SoundEventTypes,
+  Stage,
+  Trigger,
+  TriggerTypes,
+  clampMidiFlagId,
+  clearAppContext,
+  cloneConfig,
+  createCrosshairFrame,
+  createEditorLevelFromClassic,
+  detectRuntimeCapabilities,
+  getDependency,
+  getGameStateTypes,
+  getGameTypes,
+  getLemmingCtor,
+  getProfileHistoryRetention,
+  getRuntimeDependency,
+  getRuntimeProfileIds,
+  getRuntimeProfilePreset,
+  getSpecialHistoryRetention,
+  getTriggerTypes,
+  hashString,
+  listSavedLevels,
+  loadEditorLevel,
+  loadSavedLevel,
+  normalizeRuntimeProfile,
+  parseBoundedNumber,
+  parseInt10,
+  resolveRuntimeRolloutFlags,
+  setAppContext,
+  toMidiFlagTriggerType
+};
diff --git a/js/game/history/HistoryBinaryCodec.js b/js/game/history/HistoryBinaryCodec.js
new file mode 100644
index 00000000..c6d0b844
--- /dev/null
+++ b/js/game/history/HistoryBinaryCodec.js
@@ -0,0 +1,293 @@
+// @ts-check
+import { decodeText, encodeText, toI32 } from './HistoryShared.js';
+
+class BinaryWriter {
+  constructor(initialCapacity = 256) {
+    const size = Math.max(32, initialCapacity | 0);
+    this._bytes = new Uint8Array(size);
+    this.length = 0;
+    this._scratch = new Uint8Array(8);
+    this._scratchView = new DataView(this._scratch.buffer);
+  }
+
+  _ensure(extraBytes) {
+    const needed = this.length + extraBytes;
+    if (needed <= this._bytes.length) return;
+    let nextSize = this._bytes.length;
+    while (nextSize < needed) nextSize *= 2;
+    const next = new Uint8Array(nextSize);
+    next.set(this._bytes.subarray(0, this.length));
+    this._bytes = next;
+  }
+
+  writeU8(value) {
+    this._ensure(1);
+    this._bytes[this.length] = value & 0xff;
+    this.length += 1;
+  }
+
+  writeU32(value) {
+    const v = Number.isFinite(value) ? (Math.trunc(value) >>> 0) : 0;
+    this._ensure(4);
+    this._bytes[this.length] = v & 0xff;
+    this._bytes[this.length + 1] = (v >>> 8) & 0xff;
+    this._bytes[this.length + 2] = (v >>> 16) & 0xff;
+    this._bytes[this.length + 3] = (v >>> 24) & 0xff;
+    this.length += 4;
+  }
+
+  writeI32(value) {
+    this.writeU32((toI32(value) >> 0) >>> 0);
+  }
+
+  writeF64(value) {
+    this._scratchView.setFloat64(0, Number.isFinite(value) ? value : 0, true);
+    this.writeRaw(this._scratch);
+  }
+
+  writeVarUint(value) {
+    let next = Number.isFinite(value) ? Math.max(0, Math.trunc(value)) : 0;
+    while (next >= 0x80) {
+      this.writeU8((next & 0x7f) | 0x80);
+      next = Math.floor(next / 128);
+    }
+    this.writeU8(next);
+  }
+
+  writeRaw(bytes) {
+    if (!bytes || !bytes.length) return;
+    this._ensure(bytes.length);
+    this._bytes.set(bytes, this.length);
+    this.length += bytes.length;
+  }
+
+  writeBytes(bytes) {
+    const src = bytes instanceof Uint8Array ? bytes : Uint8Array.from(bytes || []);
+    this.writeVarUint(src.length);
+    this.writeRaw(src);
+  }
+
+  toUint8Array() {
+    return this._bytes.slice(0, this.length);
+  }
+}
+
+class BinaryReader {
+  constructor(bytes) {
+    this._bytes = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes || 0);
+    this._view = new DataView(this._bytes.buffer, this._bytes.byteOffset, this._bytes.byteLength);
+    this.offset = 0;
+  }
+
+  _require(length) {
+    if ((this.offset + length) > this._bytes.length) {
+      throw new Error('HistoryStore cold-block decode overflow.');
+    }
+  }
+
+  readU8() {
+    this._require(1);
+    const value = this._bytes[this.offset];
+    this.offset += 1;
+    return value;
+  }
+
+  readU32() {
+    this._require(4);
+    const value = this._view.getUint32(this.offset, true);
+    this.offset += 4;
+    return value;
+  }
+
+  readI32() {
+    this._require(4);
+    const value = this._view.getInt32(this.offset, true);
+    this.offset += 4;
+    return value;
+  }
+
+  readF64() {
+    this._require(8);
+    const value = this._view.getFloat64(this.offset, true);
+    this.offset += 8;
+    return value;
+  }
+
+  readVarUint() {
+    let value = 0;
+    let shift = 0;
+    while (true) {
+      const byte = this.readU8();
+      value += (byte & 0x7f) * Math.pow(2, shift);
+      if ((byte & 0x80) === 0) break;
+      shift += 7;
+      if (shift > 49) {
+        throw new Error('HistoryStore cold-block varuint too large.');
+      }
+    }
+    return value;
+  }
+
+  readRaw(length) {
+    const size = Number.isFinite(length) ? Math.max(0, Math.trunc(length)) : 0;
+    this._require(size);
+    const value = this._bytes.subarray(this.offset, this.offset + size);
+    this.offset += size;
+    return value;
+  }
+
+  readBytes() {
+    const length = this.readVarUint();
+    return this.readRaw(length);
+  }
+
+  eof() {
+    return this.offset >= this._bytes.length;
+  }
+}
+
+const VALUE_TAG_NULL = 0;
+const VALUE_TAG_FALSE = 1;
+const VALUE_TAG_TRUE = 2;
+const VALUE_TAG_NUMBER = 3;
+const VALUE_TAG_STRING = 4;
+const VALUE_TAG_ARRAY = 5;
+const VALUE_TAG_OBJECT = 6;
+const VALUE_TAG_UNDEFINED = 7;
+
+const writeTaggedValue = (writer, value) => {
+  if (value === null) {
+    writer.writeU8(VALUE_TAG_NULL);
+    return;
+  }
+  if (value === undefined) {
+    writer.writeU8(VALUE_TAG_UNDEFINED);
+    return;
+  }
+  if (value === false) {
+    writer.writeU8(VALUE_TAG_FALSE);
+    return;
+  }
+  if (value === true) {
+    writer.writeU8(VALUE_TAG_TRUE);
+    return;
+  }
+  if (typeof value === 'number') {
+    writer.writeU8(VALUE_TAG_NUMBER);
+    writer.writeF64(value);
+    return;
+  }
+  if (typeof value === 'string') {
+    writer.writeU8(VALUE_TAG_STRING);
+    writer.writeBytes(encodeText(value));
+    return;
+  }
+  if (Array.isArray(value)) {
+    writer.writeU8(VALUE_TAG_ARRAY);
+    writer.writeVarUint(value.length);
+    for (let i = 0; i < value.length; i += 1) {
+      writeTaggedValue(writer, value[i]);
+    }
+    return;
+  }
+  writer.writeU8(VALUE_TAG_OBJECT);
+  const keys = Object.keys(value).filter(key => value[key] !== undefined).sort();
+  writer.writeVarUint(keys.length);
+  for (let i = 0; i < keys.length; i += 1) {
+    const key = keys[i];
+    writer.writeBytes(encodeText(key));
+    writeTaggedValue(writer, value[key]);
+  }
+};
+
+const readTaggedValue = (reader) => {
+  const tag = reader.readU8();
+  switch (tag) {
+  case VALUE_TAG_NULL:
+    return null;
+  case VALUE_TAG_FALSE:
+    return false;
+  case VALUE_TAG_TRUE:
+    return true;
+  case VALUE_TAG_NUMBER:
+    return reader.readF64();
+  case VALUE_TAG_STRING:
+    return decodeText(reader.readBytes());
+  case VALUE_TAG_ARRAY: {
+    const length = reader.readVarUint();
+    const out = new Array(length);
+    for (let i = 0; i < length; i += 1) {
+      out[i] = readTaggedValue(reader);
+    }
+    return out;
+  }
+  case VALUE_TAG_OBJECT: {
+    const length = reader.readVarUint();
+    const out = {};
+    for (let i = 0; i < length; i += 1) {
+      const key = decodeText(reader.readBytes());
+      out[key] = readTaggedValue(reader);
+    }
+    return out;
+  }
+  case VALUE_TAG_UNDEFINED:
+    return undefined;
+  default:
+    throw new Error(`HistoryStore cold-block tag ${tag} is unsupported.`);
+  }
+};
+
+const bytesEqual = (a, b) => {
+  if (!a || !b || a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i += 1) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+};
+
+const fnv1aHashBytes = (bytes) => {
+  let hash = 2166136261;
+  for (let i = 0; i < bytes.length; i += 1) {
+    hash ^= bytes[i];
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, '0');
+};
+
+const rleEncodeBytes = (bytes) => {
+  if (!bytes || bytes.length <= 2) return bytes;
+  const out = [];
+  for (let i = 0; i < bytes.length;) {
+    const value = bytes[i];
+    let run = 1;
+    while ((i + run) < bytes.length && bytes[i + run] === value && run < 255) {
+      run += 1;
+    }
+    out.push(run, value);
+    i += run;
+  }
+  return Uint8Array.from(out);
+};
+
+const rleDecodeBytes = (bytes) => {
+  const out = [];
+  for (let i = 0; i < bytes.length; i += 2) {
+    const run = bytes[i];
+    const value = bytes[i + 1];
+    for (let j = 0; j < run; j += 1) {
+      out.push(value);
+    }
+  }
+  return Uint8Array.from(out);
+};
+
+export {
+  BinaryWriter,
+  BinaryReader,
+  writeTaggedValue,
+  readTaggedValue,
+  bytesEqual,
+  fnv1aHashBytes,
+  rleEncodeBytes,
+  rleDecodeBytes
+};
diff --git a/js/game/history/HistoryDeltaCodec.js b/js/game/history/HistoryDeltaCodec.js
new file mode 100644
index 00000000..c23397eb
--- /dev/null
+++ b/js/game/history/HistoryDeltaCodec.js
@@ -0,0 +1,293 @@
+// @ts-check
+import {
+  DELTA_FLAG_ENTRANCE,
+  DELTA_FLAG_GROUND,
+  DELTA_FLAG_LEMMING_ADDS,
+  DELTA_FLAG_LEMMING_CHANGES,
+  DELTA_FLAG_LEMMING_MANAGER,
+  DELTA_FLAG_LEMMING_REMOVALS,
+  DELTA_FLAG_MINIMAP_DEATHS,
+  DELTA_FLAG_OBJECTS,
+  DELTA_FLAG_SCALARS,
+  DELTA_FLAG_SOUND_EVENTS,
+  DELTA_FLAG_TRIGGERS,
+  toBoolByte,
+  toI32,
+  toU8
+} from './HistoryShared.js';
+
+
+const computeDeltaFlags = (delta) => {
+  if (!delta || typeof delta !== 'object') return 0;
+  let flags = 0;
+  if (delta.lemAdded?.length) flags |= DELTA_FLAG_LEMMING_ADDS;
+  if (delta.lemChanges?.ids?.length) flags |= DELTA_FLAG_LEMMING_CHANGES;
+  if (delta.lemRemoved?.length) flags |= DELTA_FLAG_LEMMING_REMOVALS;
+  if (delta.lemmingManagerChanges) flags |= DELTA_FLAG_LEMMING_MANAGER;
+  if (delta.groundChanges?.indices?.length || delta.groundChanges?.spans) flags |= DELTA_FLAG_GROUND;
+  if (delta.entranceChanges?.indices?.length) flags |= DELTA_FLAG_ENTRANCE;
+  if (
+    delta.triggerCooldownChanges?.ids?.length ||
+    delta.triggerAdd?.length ||
+    delta.triggerRemove?.length
+  ) {
+    flags |= DELTA_FLAG_TRIGGERS;
+  }
+  if (delta.objectAnimChanges?.ids?.length) flags |= DELTA_FLAG_OBJECTS;
+  if (delta.victoryChanges || delta.skillsChanges || delta.timerChanges || delta.gameChanges) {
+    flags |= DELTA_FLAG_SCALARS;
+  }
+  if (delta.soundEvents?.length) flags |= DELTA_FLAG_SOUND_EVENTS;
+  if (delta.minimapDeaths?.length) flags |= DELTA_FLAG_MINIMAP_DEATHS;
+  return flags;
+};
+
+/**
+ * Canonical delta-section bitmap normalizer.
+ * Deltas are expected to carry `flags`; this fills it once for any ad-hoc test
+ * or tooling input that omitted the bitmap.
+ */
+const ensureDeltaFlags = (delta) => {
+  if (!delta || typeof delta !== 'object') return 0;
+  if (Number.isFinite(delta.flags)) return delta.flags | 0;
+  const flags = computeDeltaFlags(delta);
+  delta.flags = flags;
+  return flags;
+};
+
+const isNoOpDelta = (delta) => {
+  return ensureDeltaFlags(delta) === 0;
+};
+
+
+const createDelta = (tick) => ({
+  tick,
+  flags: 0,
+  lemChanges: { ids: [], fields: [], prev: [], next: [] },
+  lemAdded: [],
+  lemRemoved: [],
+  lemmingManagerChanges: null,
+  groundChanges: {
+    indices: [],
+    spans: null,
+    prevMask: [],
+    prevR: [],
+    prevG: [],
+    prevB: [],
+    nextMask: [],
+    nextR: [],
+    nextG: [],
+    nextB: []
+  },
+  entranceChanges: { indices: [], prev: [], next: [] },
+  triggerCooldownChanges: { ids: [], prev: [], next: [] },
+  triggerAdd: [],
+  triggerRemove: [],
+  objectAnimChanges: { ids: [], prevFirst: [], prevFinished: [], nextFirst: [], nextFinished: [] },
+  victoryChanges: null,
+  skillsChanges: null,
+  timerChanges: null,
+  gameChanges: null,
+  soundEvents: [],
+  minimapDeaths: []
+});
+
+const createPackedLemmingMutation = (count) => ({
+  count,
+  id: new Int32Array(count),
+  x: new Int32Array(count),
+  y: new Int32Array(count),
+  lookRight: new Uint8Array(count),
+  frameIndex: new Int32Array(count),
+  state: new Int32Array(count),
+  canClimb: new Uint8Array(count),
+  hasParachute: new Uint8Array(count),
+  removed: new Uint8Array(count),
+  disabled: new Uint8Array(count),
+  countdown: new Int32Array(count),
+  hasExploded: new Uint8Array(count),
+  lastTriggerType: new Int32Array(count),
+  actionType: new Int32Array(count),
+  countdownActive: new Uint8Array(count)
+});
+
+const packLemmingMutationList = (list) => {
+  const count = Array.isArray(list) ? list.length : 0;
+  const packed = createPackedLemmingMutation(count);
+  for (let i = 0; i < count; i += 1) {
+    const snap = list[i] || {};
+    packed.id[i] = toI32(snap.id);
+    packed.x[i] = toI32(snap.x);
+    packed.y[i] = toI32(snap.y);
+    packed.lookRight[i] = toBoolByte(snap.lookRight);
+    packed.frameIndex[i] = toI32(snap.frameIndex);
+    packed.state[i] = toI32(snap.state);
+    packed.canClimb[i] = toBoolByte(snap.canClimb);
+    packed.hasParachute[i] = toBoolByte(snap.hasParachute);
+    packed.removed[i] = toBoolByte(snap.removed);
+    packed.disabled[i] = toBoolByte(snap.disabled);
+    packed.countdown[i] = toI32(snap.countdown);
+    packed.hasExploded[i] = toBoolByte(snap.hasExploded);
+    packed.lastTriggerType[i] = toI32(snap.lastTriggerType, -1);
+    packed.actionType[i] = toI32(snap.actionType, -1);
+    packed.countdownActive[i] = toBoolByte(snap.countdownActive);
+  }
+  return packed;
+};
+
+const unpackLemmingMutationList = (packed) => {
+  const count = packed?.count || 0;
+  const out = new Array(count);
+  for (let i = 0; i < count; i += 1) {
+    out[i] = {
+      id: packed.id[i],
+      x: packed.x[i],
+      y: packed.y[i],
+      lookRight: packed.lookRight[i],
+      frameIndex: packed.frameIndex[i],
+      state: packed.state[i],
+      canClimb: packed.canClimb[i],
+      hasParachute: packed.hasParachute[i],
+      removed: packed.removed[i],
+      disabled: packed.disabled[i],
+      countdown: packed.countdown[i],
+      hasExploded: packed.hasExploded[i],
+      lastTriggerType: packed.lastTriggerType[i],
+      actionType: packed.actionType[i],
+      countdownActive: packed.countdownActive[i]
+    };
+  }
+  return out;
+};
+
+const writePackedLemmingMutation = (writer, packed) => {
+  const count = packed?.count || 0;
+  writer.writeVarUint(count);
+  for (let i = 0; i < count; i += 1) writer.writeI32(packed.id[i]);
+  for (let i = 0; i < count; i += 1) writer.writeI32(packed.x[i]);
+  for (let i = 0; i < count; i += 1) writer.writeI32(packed.y[i]);
+  for (let i = 0; i < count; i += 1) writer.writeU8(packed.lookRight[i]);
+  for (let i = 0; i < count; i += 1) writer.writeI32(packed.frameIndex[i]);
+  for (let i = 0; i < count; i += 1) writer.writeI32(packed.state[i]);
+  for (let i = 0; i < count; i += 1) writer.writeU8(packed.canClimb[i]);
+  for (let i = 0; i < count; i += 1) writer.writeU8(packed.hasParachute[i]);
+  for (let i = 0; i < count; i += 1) writer.writeU8(packed.removed[i]);
+  for (let i = 0; i < count; i += 1) writer.writeU8(packed.disabled[i]);
+  for (let i = 0; i < count; i += 1) writer.writeI32(packed.countdown[i]);
+  for (let i = 0; i < count; i += 1) writer.writeU8(packed.hasExploded[i]);
+  for (let i = 0; i < count; i += 1) writer.writeI32(packed.lastTriggerType[i]);
+  for (let i = 0; i < count; i += 1) writer.writeI32(packed.actionType[i]);
+  for (let i = 0; i < count; i += 1) writer.writeU8(packed.countdownActive[i]);
+};
+
+const readPackedLemmingMutation = (reader) => {
+  const count = reader.readVarUint();
+  const packed = createPackedLemmingMutation(count);
+  for (let i = 0; i < count; i += 1) packed.id[i] = reader.readI32();
+  for (let i = 0; i < count; i += 1) packed.x[i] = reader.readI32();
+  for (let i = 0; i < count; i += 1) packed.y[i] = reader.readI32();
+  for (let i = 0; i < count; i += 1) packed.lookRight[i] = reader.readU8();
+  for (let i = 0; i < count; i += 1) packed.frameIndex[i] = reader.readI32();
+  for (let i = 0; i < count; i += 1) packed.state[i] = reader.readI32();
+  for (let i = 0; i < count; i += 1) packed.canClimb[i] = reader.readU8();
+  for (let i = 0; i < count; i += 1) packed.hasParachute[i] = reader.readU8();
+  for (let i = 0; i < count; i += 1) packed.removed[i] = reader.readU8();
+  for (let i = 0; i < count; i += 1) packed.disabled[i] = reader.readU8();
+  for (let i = 0; i < count; i += 1) packed.countdown[i] = reader.readI32();
+  for (let i = 0; i < count; i += 1) packed.hasExploded[i] = reader.readU8();
+  for (let i = 0; i < count; i += 1) packed.lastTriggerType[i] = reader.readI32();
+  for (let i = 0; i < count; i += 1) packed.actionType[i] = reader.readI32();
+  for (let i = 0; i < count; i += 1) packed.countdownActive[i] = reader.readU8();
+  return packed;
+};
+
+const createPackedLemmingChanges = (count) => ({
+  count,
+  ids: new Int32Array(count),
+  fields: new Uint8Array(count),
+  prev: new Int32Array(count),
+  next: new Int32Array(count)
+});
+
+const packLemmingChanges = (changes) => {
+  const count = Array.isArray(changes?.ids) ? changes.ids.length : 0;
+  const packed = createPackedLemmingChanges(count);
+  for (let i = 0; i < count; i += 1) {
+    packed.ids[i] = toI32(changes.ids[i]);
+    packed.fields[i] = toU8(changes.fields?.[i]);
+    packed.prev[i] = toI32(changes.prev?.[i]);
+    packed.next[i] = toI32(changes.next?.[i]);
+  }
+  return packed;
+};
+
+const unpackLemmingChanges = (packed) => {
+  const count = packed?.count || 0;
+  const changes = {
+    ids: new Array(count),
+    fields: new Array(count),
+    prev: new Array(count),
+    next: new Array(count)
+  };
+  for (let i = 0; i < count; i += 1) {
+    changes.ids[i] = packed.ids[i];
+    changes.fields[i] = packed.fields[i];
+    changes.prev[i] = packed.prev[i];
+    changes.next[i] = packed.next[i];
+  }
+  return changes;
+};
+
+const writePackedLemmingChanges = (writer, packed) => {
+  const count = packed?.count || 0;
+  writer.writeVarUint(count);
+  for (let i = 0; i < count; i += 1) writer.writeI32(packed.ids[i]);
+  for (let i = 0; i < count; i += 1) writer.writeU8(packed.fields[i]);
+  for (let i = 0; i < count; i += 1) writer.writeI32(packed.prev[i]);
+  for (let i = 0; i < count; i += 1) writer.writeI32(packed.next[i]);
+};
+
+const readPackedLemmingChanges = (reader) => {
+  const count = reader.readVarUint();
+  const packed = createPackedLemmingChanges(count);
+  for (let i = 0; i < count; i += 1) packed.ids[i] = reader.readI32();
+  for (let i = 0; i < count; i += 1) packed.fields[i] = reader.readU8();
+  for (let i = 0; i < count; i += 1) packed.prev[i] = reader.readI32();
+  for (let i = 0; i < count; i += 1) packed.next[i] = reader.readI32();
+  return packed;
+};
+
+const packTimerStateForStorage = (state, tick) => {
+  if (!state) return null;
+  const out = { ...state };
+  if (Number.isFinite(out.tickIndex) && Number.isFinite(tick)) {
+    out.tickIndex = Math.trunc(out.tickIndex) - Math.trunc(tick);
+  }
+  return out;
+};
+
+const unpackTimerStateFromStorage = (state, tick) => {
+  if (!state) return null;
+  const out = { ...state };
+  if (Number.isFinite(out.tickIndex) && Number.isFinite(tick)) {
+    out.tickIndex = Math.trunc(out.tickIndex) + Math.trunc(tick);
+  }
+  return out;
+};
+
+export {
+  computeDeltaFlags,
+  ensureDeltaFlags,
+  isNoOpDelta,
+  createDelta,
+  packLemmingMutationList,
+  unpackLemmingMutationList,
+  writePackedLemmingMutation,
+  readPackedLemmingMutation,
+  packLemmingChanges,
+  unpackLemmingChanges,
+  writePackedLemmingChanges,
+  readPackedLemmingChanges,
+  packTimerStateForStorage,
+  unpackTimerStateFromStorage
+};
diff --git a/js/game/history/HistoryLemmingState.js b/js/game/history/HistoryLemmingState.js
new file mode 100644
index 00000000..74ff55ef
--- /dev/null
+++ b/js/game/history/HistoryLemmingState.js
@@ -0,0 +1,106 @@
+// @ts-check
+const createLemmingState = (size) => ({
+  capacity: size,
+  present: new Uint8Array(size),
+  x: new Int32Array(size),
+  y: new Int32Array(size),
+  lookRight: new Uint8Array(size),
+  frameIndex: new Int32Array(size),
+  state: new Int32Array(size),
+  canClimb: new Uint8Array(size),
+  hasParachute: new Uint8Array(size),
+  removed: new Uint8Array(size),
+  disabled: new Uint8Array(size),
+  countdown: new Int32Array(size),
+  hasExploded: new Uint8Array(size),
+  lastTriggerType: new Int32Array(size),
+  actionType: new Int32Array(size),
+  countdownActive: new Uint8Array(size)
+});
+
+const cloneLemmingState = (state, length) => {
+  const size = length ?? state.capacity;
+  const copy = createLemmingState(size);
+  copy.present.set(state.present.subarray(0, size));
+  copy.x.set(state.x.subarray(0, size));
+  copy.y.set(state.y.subarray(0, size));
+  copy.lookRight.set(state.lookRight.subarray(0, size));
+  copy.frameIndex.set(state.frameIndex.subarray(0, size));
+  copy.state.set(state.state.subarray(0, size));
+  copy.canClimb.set(state.canClimb.subarray(0, size));
+  copy.hasParachute.set(state.hasParachute.subarray(0, size));
+  copy.removed.set(state.removed.subarray(0, size));
+  copy.disabled.set(state.disabled.subarray(0, size));
+  copy.countdown.set(state.countdown.subarray(0, size));
+  copy.hasExploded.set(state.hasExploded.subarray(0, size));
+  copy.lastTriggerType.set(state.lastTriggerType.subarray(0, size));
+  copy.actionType.set(state.actionType.subarray(0, size));
+  copy.countdownActive.set(state.countdownActive.subarray(0, size));
+  return copy;
+};
+
+const ensureLemmingCapacity = (state, size) => {
+  if (state.capacity >= size) return state;
+  const next = Math.max(size, state.capacity * 2, 1);
+  const grown = createLemmingState(next);
+  grown.present.set(state.present);
+  grown.x.set(state.x);
+  grown.y.set(state.y);
+  grown.lookRight.set(state.lookRight);
+  grown.frameIndex.set(state.frameIndex);
+  grown.state.set(state.state);
+  grown.canClimb.set(state.canClimb);
+  grown.hasParachute.set(state.hasParachute);
+  grown.removed.set(state.removed);
+  grown.disabled.set(state.disabled);
+  grown.countdown.set(state.countdown);
+  grown.hasExploded.set(state.hasExploded);
+  grown.lastTriggerType.set(state.lastTriggerType);
+  grown.actionType.set(state.actionType);
+  grown.countdownActive.set(state.countdownActive);
+  return grown;
+};
+
+const snapshotLemming = (lem, actionType, countdownActive) => ({
+  id: lem.id,
+  x: lem.x,
+  y: lem.y,
+  lookRight: lem.lookRight ? 1 : 0,
+  frameIndex: lem.frameIndex,
+  state: lem.state ?? 0,
+  canClimb: lem.canClimb ? 1 : 0,
+  hasParachute: lem.hasParachute ? 1 : 0,
+  removed: lem.removed ? 1 : 0,
+  disabled: lem.disabled ? 1 : 0,
+  countdown: lem.countdown ?? 0,
+  hasExploded: lem.hasExploded ? 1 : 0,
+  lastTriggerType: Number.isFinite(lem.lastTriggerType) ? lem.lastTriggerType : -1,
+  actionType: Number.isFinite(actionType) ? actionType : -1,
+  countdownActive: countdownActive ? 1 : 0
+});
+
+const applyLemmingSnapshot = (lem, snapshot, action, countdownAction) => {
+  lem.id = snapshot.id;
+  lem.x = snapshot.x;
+  lem.y = snapshot.y;
+  lem.lookRight = !!snapshot.lookRight;
+  lem.frameIndex = snapshot.frameIndex;
+  lem.state = snapshot.state;
+  lem.canClimb = !!snapshot.canClimb;
+  lem.hasParachute = !!snapshot.hasParachute;
+  lem.removed = !!snapshot.removed;
+  lem.disabled = !!snapshot.disabled;
+  lem.countdown = snapshot.countdown;
+  lem.hasExploded = !!snapshot.hasExploded;
+  lem.lastTriggerType = snapshot.lastTriggerType >= 0 ? snapshot.lastTriggerType : null;
+  lem.action = action || null;
+  lem.countdownAction = snapshot.countdownActive ? countdownAction : null;
+};
+
+export {
+  createLemmingState,
+  cloneLemmingState,
+  ensureLemmingCapacity,
+  snapshotLemming,
+  applyLemmingSnapshot
+};
diff --git a/js/game/history/HistoryShared.js b/js/game/history/HistoryShared.js
new file mode 100644
index 00000000..f717200b
--- /dev/null
+++ b/js/game/history/HistoryShared.js
@@ -0,0 +1,139 @@
+// @ts-check
+const DEFAULT_OPTIONS = Object.freeze({
+  keyframeInterval: 120,
+  preserveFutureHistory: false,
+  enableHistoryCap: true,
+  historyCapTicks: 20000,
+  historyWarnTicks: 15000,
+  deltaPoolLimit: 64,
+  deltaBlockSizeTicks: 256,
+  coldBlockAgeTicks: 2048,
+  coldCompactionIntervalTicks: 1,
+  coldCompactionMaxBlocksPerSweep: 4,
+  enableColdBlockCompression: true,
+  enableColdBlockDedupe: true
+});
+
+const COLD_DELTA_SENTINEL = 1;
+const DELTA_FLAG_LEMMING_ADDS = 1 << 0;
+const DELTA_FLAG_LEMMING_CHANGES = 1 << 1;
+const DELTA_FLAG_LEMMING_REMOVALS = 1 << 2;
+const DELTA_FLAG_LEMMING_MANAGER = 1 << 3;
+const DELTA_FLAG_GROUND = 1 << 4;
+const DELTA_FLAG_ENTRANCE = 1 << 5;
+const DELTA_FLAG_TRIGGERS = 1 << 6;
+const DELTA_FLAG_OBJECTS = 1 << 7;
+const DELTA_FLAG_SCALARS = 1 << 8;
+const DELTA_FLAG_SOUND_EVENTS = 1 << 9;
+const DELTA_FLAG_MINIMAP_DEATHS = 1 << 10;
+const DELTA_FLAG_LEMMING_MUTATIONS =
+  DELTA_FLAG_LEMMING_ADDS |
+  DELTA_FLAG_LEMMING_CHANGES |
+  DELTA_FLAG_LEMMING_REMOVALS;
+
+const COLD_BLOCK_MAGIC = 0x42534c48; // 'HLSB'
+const COLD_BLOCK_VERSION = 1;
+const DELTA_CODEC_VERSION = 1;
+const NULL_INT32 = -2147483648;
+const textEncoder = typeof TextEncoder !== 'undefined' ? new TextEncoder() : null;
+const textDecoder = typeof TextDecoder !== 'undefined' ? new TextDecoder() : null;
+
+const toNonNegativeInt = (value, fallback) => {
+  if (!Number.isFinite(value)) return fallback;
+  const next = Math.trunc(value);
+  return next >= 0 ? next : fallback;
+};
+
+const encodeText = (value) => {
+  if (textEncoder) return textEncoder.encode(value);
+  const bytes = [];
+  for (let i = 0; i < value.length; i += 1) {
+    bytes.push(value.charCodeAt(i) & 0xff);
+  }
+  return Uint8Array.from(bytes);
+};
+
+const decodeText = (bytes) => {
+  if (textDecoder) return textDecoder.decode(bytes);
+  let out = '';
+  for (let i = 0; i < bytes.length; i += 1) {
+    out += String.fromCharCode(bytes[i]);
+  }
+  return out;
+};
+
+const toI32 = (value, fallback = 0) => {
+  if (!Number.isFinite(value)) return fallback;
+  return Math.trunc(value);
+};
+
+const toU8 = (value, fallback = 0) => {
+  if (!Number.isFinite(value)) return fallback;
+  const int = Math.trunc(value);
+  if (int <= 0) return 0;
+  if (int >= 255) return 255;
+  return int;
+};
+
+const toBoolByte = (value) => (value ? 1 : 0);
+
+const normalizeOptions = (options = {}) => {
+  const keyframeInterval = Math.max(1, toNonNegativeInt(options.keyframeInterval, DEFAULT_OPTIONS.keyframeInterval));
+  const deltaPoolLimit = toNonNegativeInt(options.deltaPoolLimit, DEFAULT_OPTIONS.deltaPoolLimit);
+  const historyCapTicks = toNonNegativeInt(options.historyCapTicks, DEFAULT_OPTIONS.historyCapTicks);
+  const deltaBlockSizeTicks = Math.max(1, toNonNegativeInt(options.deltaBlockSizeTicks, DEFAULT_OPTIONS.deltaBlockSizeTicks));
+  const coldBlockAgeTicks = Math.max(0, toNonNegativeInt(options.coldBlockAgeTicks, DEFAULT_OPTIONS.coldBlockAgeTicks));
+  const coldCompactionIntervalTicks = Math.max(1, toNonNegativeInt(
+    options.coldCompactionIntervalTicks,
+    DEFAULT_OPTIONS.coldCompactionIntervalTicks
+  ));
+  const coldCompactionMaxBlocksPerSweep = Math.max(1, toNonNegativeInt(
+    options.coldCompactionMaxBlocksPerSweep,
+    DEFAULT_OPTIONS.coldCompactionMaxBlocksPerSweep
+  ));
+  let historyWarnTicks = toNonNegativeInt(options.historyWarnTicks, DEFAULT_OPTIONS.historyWarnTicks);
+  if (historyCapTicks > 0 && historyWarnTicks > historyCapTicks) {
+    historyWarnTicks = historyCapTicks;
+  }
+  return {
+    keyframeInterval,
+    preserveFutureHistory: !!options.preserveFutureHistory,
+    enableHistoryCap: options.enableHistoryCap !== false,
+    historyCapTicks,
+    historyWarnTicks,
+    deltaPoolLimit,
+    deltaBlockSizeTicks,
+    coldBlockAgeTicks,
+    coldCompactionIntervalTicks,
+    coldCompactionMaxBlocksPerSweep,
+    enableColdBlockCompression: options.enableColdBlockCompression !== false,
+    enableColdBlockDedupe: options.enableColdBlockDedupe !== false
+  };
+};
+
+export {
+  DEFAULT_OPTIONS,
+  COLD_DELTA_SENTINEL,
+  DELTA_FLAG_LEMMING_ADDS,
+  DELTA_FLAG_LEMMING_CHANGES,
+  DELTA_FLAG_LEMMING_REMOVALS,
+  DELTA_FLAG_LEMMING_MANAGER,
+  DELTA_FLAG_GROUND,
+  DELTA_FLAG_ENTRANCE,
+  DELTA_FLAG_TRIGGERS,
+  DELTA_FLAG_OBJECTS,
+  DELTA_FLAG_SCALARS,
+  DELTA_FLAG_SOUND_EVENTS,
+  DELTA_FLAG_MINIMAP_DEATHS,
+  DELTA_FLAG_LEMMING_MUTATIONS,
+  COLD_BLOCK_MAGIC,
+  COLD_BLOCK_VERSION,
+  DELTA_CODEC_VERSION,
+  NULL_INT32,
+  encodeText,
+  decodeText,
+  toI32,
+  toU8,
+  toBoolByte,
+  normalizeOptions
+};
diff --git a/js/game/history/HistoryStoreApplyDeltaMethods.js b/js/game/history/HistoryStoreApplyDeltaMethods.js
new file mode 100644
index 00000000..e990e72d
--- /dev/null
+++ b/js/game/history/HistoryStoreApplyDeltaMethods.js
@@ -0,0 +1,477 @@
+// @ts-check
+import { SkillTypes } from '../SkillTypes.js';
+import { Trigger } from '../../level/Trigger.js';
+import {
+  COLD_BLOCK_MAGIC,
+  COLD_BLOCK_VERSION,
+  COLD_DELTA_SENTINEL,
+  DEFAULT_OPTIONS,
+  DELTA_CODEC_VERSION,
+  DELTA_FLAG_ENTRANCE,
+  DELTA_FLAG_GROUND,
+  DELTA_FLAG_LEMMING_ADDS,
+  DELTA_FLAG_LEMMING_CHANGES,
+  DELTA_FLAG_LEMMING_MANAGER,
+  DELTA_FLAG_LEMMING_MUTATIONS,
+  DELTA_FLAG_LEMMING_REMOVALS,
+  DELTA_FLAG_MINIMAP_DEATHS,
+  DELTA_FLAG_OBJECTS,
+  DELTA_FLAG_SCALARS,
+  DELTA_FLAG_SOUND_EVENTS,
+  DELTA_FLAG_TRIGGERS,
+  NULL_INT32,
+  normalizeOptions,
+  toI32
+} from './HistoryShared.js';
+import {
+  BinaryReader,
+  BinaryWriter,
+  bytesEqual,
+  fnv1aHashBytes,
+  readTaggedValue,
+  rleDecodeBytes,
+  rleEncodeBytes,
+  writeTaggedValue
+} from './HistoryBinaryCodec.js';
+import {
+  applyLemmingSnapshot,
+  cloneLemmingState,
+  createLemmingState,
+  ensureLemmingCapacity,
+  snapshotLemming
+} from './HistoryLemmingState.js';
+import {
+  computeDeltaFlags,
+  createDelta,
+  ensureDeltaFlags,
+  isNoOpDelta,
+  packLemmingChanges,
+  packLemmingMutationList,
+  packTimerStateForStorage,
+  readPackedLemmingChanges,
+  readPackedLemmingMutation,
+  unpackLemmingChanges,
+  unpackLemmingMutationList,
+  unpackTimerStateFromStorage,
+  writePackedLemmingChanges,
+  writePackedLemmingMutation
+} from './HistoryDeltaCodec.js';
+import {
+  MIDI_FLAG_OWNER_KIND,
+  clonePlainObject,
+  createMidiFlagTriggerOwner
+} from './HistoryTriggerOwners.js';
+
+const historyStoreApplyDeltaMethods = {
+  applyDeltaForward(game, delta) {
+    this._applyDelta(game, delta, true);
+  },
+
+  applyDeltaBackward(game, delta) {
+    this._applyDelta(game, delta, false);
+  },
+
+  _applyDelta(game, delta, useNext) {
+    if (!game || !delta) return;
+    const flags = this._getDeltaFlags(delta);
+    const manager = game.getLemmingManager?.();
+    if (manager) {
+      if (useNext) {
+        if (flags & DELTA_FLAG_LEMMING_ADDS) {
+          this._applyLemmingAdds(manager, delta.lemAdded);
+        }
+      } else {
+        if (flags & DELTA_FLAG_LEMMING_REMOVALS) {
+          this._applyLemmingAdds(manager, delta.lemRemoved);
+        }
+      }
+      if (flags & DELTA_FLAG_LEMMING_CHANGES) {
+        this._applyLemmingChanges(manager, delta.lemChanges, useNext);
+      }
+      if (useNext) {
+        if (flags & DELTA_FLAG_LEMMING_REMOVALS) {
+          this._applyLemmingRemovals(manager, delta.lemRemoved);
+        }
+      } else {
+        if (flags & DELTA_FLAG_LEMMING_ADDS) {
+          this._applyLemmingRemovals(manager, delta.lemAdded);
+        }
+      }
+      if (flags & DELTA_FLAG_LEMMING_MANAGER) {
+        this._applyLemmingManagerState(manager, delta.lemmingManagerChanges, useNext);
+      }
+      if (flags & DELTA_FLAG_LEMMING_MUTATIONS) {
+        this._rebuildActiveLemmings(manager);
+      }
+      if (flags & (DELTA_FLAG_LEMMING_MUTATIONS | DELTA_FLAG_LEMMING_MANAGER)) {
+        this._refreshMiniMapDots(manager);
+      }
+      if (flags & DELTA_FLAG_MINIMAP_DEATHS) {
+        this._applyMinimapDeaths(manager, delta.minimapDeaths, useNext);
+      }
+    }
+
+    if (flags & DELTA_FLAG_ENTRANCE) {
+      this._applyEntranceChanges(game.level, delta.entranceChanges, useNext);
+    }
+    if (flags & DELTA_FLAG_GROUND) {
+      this._applyGroundChanges(game.level, delta.groundChanges, useNext);
+    }
+    if (flags & DELTA_FLAG_TRIGGERS) {
+      this._applyTriggerChanges(game, delta, useNext);
+    }
+    if (flags & DELTA_FLAG_OBJECTS) {
+      this._applyObjectChanges(game.level, delta.objectAnimChanges, useNext);
+    }
+    if (flags & DELTA_FLAG_SCALARS) {
+      this._applyScalarChanges(game, delta, useNext);
+    } else {
+      this._applyDerivedTimerTick(game, delta, useNext);
+    }
+  },
+
+  _applyDerivedTimerTick(game, delta, useNext) {
+    if (!Number.isFinite(delta?.tick)) return;
+    const timer = game?.getGameTimer?.();
+    if (!timer) return;
+    timer.tickIndex = Math.max(0, Math.trunc(delta.tick) + (useNext ? 1 : 0));
+  },
+
+  _getDeltaFlags(delta) {
+    return ensureDeltaFlags(delta);
+  },
+
+  _createReplayLemming(manager, x, y, id) {
+    if (!manager) return null;
+    if (typeof manager._acquireLemming === 'function') {
+      const lem = manager._acquireLemming(x, y, id);
+      if (lem && typeof lem === 'object') return lem;
+    } else if (typeof manager._lemmingCtor === 'function') {
+      return new manager._lemmingCtor(x, y, id);
+    }
+    throw new Error('HistoryStore replay apply requires manager._acquireLemming() or manager._lemmingCtor.');
+  },
+
+  _applyLemmingAdds(manager, list) {
+    if (!manager || !Array.isArray(list) || !list.length) return;
+    const countdownAction = manager.skillActions?.[SkillTypes.BOMBER] ?? null;
+    if (!Array.isArray(manager.lemmings)) manager.lemmings = [];
+    for (const snap of list) {
+      if (snap == null || !Number.isFinite(snap.id)) continue;
+      let lem = manager.lemmings[snap.id];
+      if (!lem) {
+        lem = this._createReplayLemming(manager, snap.x, snap.y, snap.id);
+        manager.lemmings[snap.id] = lem;
+      }
+      const action = snap.actionType >= 0 ? manager.actions?.[snap.actionType] : null;
+      applyLemmingSnapshot(lem, snap, action, countdownAction);
+    }
+  },
+
+  _applyLemmingRemovals(manager, list) {
+    if (!manager || !Array.isArray(list) || !list.length) return;
+    for (const snap of list) {
+      if (snap == null || !Number.isFinite(snap.id)) continue;
+      manager.lemmings[snap.id] = null;
+    }
+  },
+
+  _applyLemmingChanges(manager, changes, useNext) {
+    if (!manager || !changes?.ids?.length) return;
+    const countdownAction = manager.skillActions?.[SkillTypes.BOMBER] ?? null;
+    for (let i = 0; i < changes.ids.length; i++) {
+      const id = changes.ids[i];
+      const field = changes.fields[i];
+      const value = useNext ? changes.next[i] : changes.prev[i];
+      const lem = manager.lemmings?.[id];
+      if (!lem) continue;
+      switch (field) {
+      case 0: lem.x = value; break;
+      case 1: lem.y = value; break;
+      case 2: lem.lookRight = !!value; break;
+      case 3: lem.frameIndex = value; break;
+      case 4: lem.state = value; break;
+      case 5: lem.canClimb = !!value; break;
+      case 6: lem.hasParachute = !!value; break;
+      case 7: lem.removed = !!value; break;
+      case 8: lem.disabled = !!value; break;
+      case 9: lem.countdown = value; break;
+      case 10: lem.hasExploded = !!value; break;
+      case 11: lem.lastTriggerType = value >= 0 ? value : null; break;
+      case 12: lem.action = value >= 0 ? manager.actions?.[value] : null; break;
+      case 13: lem.countdownAction = value ? countdownAction : null; break;
+      default: break;
+      }
+    }
+  },
+
+  _applyLemmingManagerState(manager, changes, useNext) {
+    if (!manager || !changes) return;
+    const state = useNext ? changes.next : changes.prev;
+    if (!state) return;
+    manager.selectedIndex = state.selectedIndex ?? -1;
+    manager.spawnTotal = state.spawnTotal ?? 0;
+    manager.releaseTickIndex = state.releaseTickIndex ?? 0;
+    manager.mmTickCounter = state.mmTickCounter ?? 0;
+    manager.nextNukingLemmingsIndex = state.nextNukingLemmingsIndex ?? -1;
+    manager._nukeTargets = this._resolveNukeTargets(manager, state.nukeTargets);
+  },
+
+  _resolveNukeTargets(manager, ids) {
+    if (!manager || !Array.isArray(ids)) return null;
+    const lems = manager.lemmings || [];
+    const resolved = [];
+    for (let i = 0; i < ids.length; i += 1) {
+      const id = ids[i];
+      if (!Number.isFinite(id)) continue;
+      const lem = lems[id];
+      if (lem) resolved.push(lem);
+    }
+    return resolved;
+  },
+
+  _rebuildActiveLemmings(manager) {
+    if (!manager) return;
+    const lems = manager.lemmings || [];
+    const active = Array.isArray(manager.activeLemmings) ? manager.activeLemmings : [];
+    active.length = 0;
+    for (let i = 0; i < lems.length; i += 1) {
+      const lem = lems[i];
+      if (!lem || lem.removed) continue;
+      lem._activeIndex = active.length;
+      active.push(lem);
+    }
+    manager.activeLemmings = active;
+    manager._activeDirty = false;
+  },
+
+  _refreshMiniMapDots(manager) {
+    if (!manager?.miniMap) return;
+    if (typeof manager.refreshMiniMapDots === 'function') {
+      manager.refreshMiniMapDots();
+      return;
+    }
+    manager.miniMap.setLiveDots?.(new Uint8Array(0), 0);
+    manager.miniMap.setSelectedDot?.(null);
+  },
+
+  _applyEntranceChanges(level, changes, useNext) {
+    if (!level || !changes?.indices?.length) return;
+    for (let i = 0; i < changes.indices.length; i++) {
+      const idx = changes.indices[i];
+      const val = useNext ? changes.next[i] : changes.prev[i];
+      if (level.entrances?.[idx]) {
+        level.entrances[idx]._opened = !!val;
+      }
+    }
+  },
+
+  _applyGroundChanges(level, changes, useNext) {
+    if (!level || !changes) return;
+    const mask = level.groundMask?.mask;
+    const img = level.groundImage;
+    if (!mask || !img) return;
+    const maskValues = useNext ? changes.nextMask : changes.prevMask;
+    const redValues = useNext ? changes.nextR : changes.prevR;
+    const greenValues = useNext ? changes.nextG : changes.prevG;
+    const blueValues = useNext ? changes.nextB : changes.prevB;
+    if (!maskValues || !redValues || !greenValues || !blueValues) return;
+    const spans = changes.spans;
+    if (spans?.starts?.length) {
+      const starts = spans.starts;
+      const lengths = spans.lengths;
+      let valueIndex = 0;
+      for (let i = 0; i < starts.length; i += 1) {
+        let index = starts[i];
+        let imgIndex = index << 2;
+        const valueEnd = valueIndex + lengths[i];
+        for (; valueIndex < valueEnd; valueIndex += 1, index += 1, imgIndex += 4) {
+          mask[index] = maskValues[valueIndex];
+          img[imgIndex] = redValues[valueIndex];
+          img[imgIndex + 1] = greenValues[valueIndex];
+          img[imgIndex + 2] = blueValues[valueIndex];
+        }
+      }
+      return;
+    }
+    const indices = changes.indices;
+    if (!indices?.length) return;
+    for (let i = 0; i < indices.length; i += 1) {
+      const index = indices[i];
+      const imgIndex = index << 2;
+      mask[index] = maskValues[i];
+      img[imgIndex] = redValues[i];
+      img[imgIndex + 1] = greenValues[i];
+      img[imgIndex + 2] = blueValues[i];
+    }
+  },
+
+  _applyTriggerChanges(game, delta, useNext) {
+    const triggerManager = game?.triggerManager;
+    if (!triggerManager || !delta) return;
+    const adds = useNext ? delta.triggerAdd : delta.triggerRemove;
+    const removes = useNext ? delta.triggerRemove : delta.triggerAdd;
+    for (let i = 0; i < (removes?.length || 0); i += 1) {
+      const snap = removes[i];
+      const trig = this._findTriggerById(triggerManager, snap.id);
+      if (this._isReplayManagedDynamicTrigger(trig)) {
+        this._removeTriggerInstance(triggerManager, trig);
+      }
+    }
+    for (let i = 0; i < (adds?.length || 0); i += 1) {
+      const snap = adds[i];
+      const owner = this._resolveTriggerOwner(game, snap);
+      const trig = new Trigger(
+        snap.type,
+        snap.x1,
+        snap.y1,
+        snap.x2,
+        snap.y2,
+        snap.disableTicksCount,
+        snap.soundIndex,
+        owner
+      );
+      trig.disabledUntilTick = snap.disabledUntilTick ?? 0;
+      trig.__historyId = snap.id;
+      if (snap.observer === true && typeof triggerManager.addObserver === 'function') {
+        triggerManager.addObserver(trig);
+      } else {
+        triggerManager.add(trig);
+      }
+      this._triggerById.set(snap.id, trig);
+    }
+    if (delta.triggerCooldownChanges?.ids?.length) {
+      for (let i = 0; i < delta.triggerCooldownChanges.ids.length; i++) {
+        const id = delta.triggerCooldownChanges.ids[i];
+        const trig = this._findTriggerById(triggerManager, id);
+        if (!trig) continue;
+        const value = useNext
+          ? delta.triggerCooldownChanges.next[i]
+          : delta.triggerCooldownChanges.prev[i];
+        trig.disabledUntilTick = value;
+      }
+    }
+  },
+
+  _findTriggerById(triggerManager, id) {
+    if (!triggerManager || !id) return null;
+    if (this._triggerById.has(id)) return this._triggerById.get(id);
+    let found = null;
+    const triggerSets = [triggerManager._triggers, triggerManager._observerTriggers];
+    for (const triggerSet of triggerSets) {
+      for (const trig of triggerSet || []) {
+        const trigId = trig?.__historyId;
+        if (!trigId) continue;
+        this._triggerById.set(trigId, trig);
+        if (trigId === id) {
+          found = trig;
+        }
+      }
+    }
+    return found;
+  },
+
+  _applyObjectChanges(level, changes, useNext) {
+    if (!level || !changes?.ids?.length) return;
+    for (let i = 0; i < changes.ids.length; i++) {
+      const id = changes.ids[i];
+      let obj = this._objectById.get(id);
+      if (!obj) {
+        const objects = level.objects || [];
+        for (const entry of objects) {
+          if (!entry?.animation) continue;
+          const entryId = this._ensureObjectId(entry);
+          if (entryId === id) {
+            obj = entry;
+            break;
+          }
+        }
+      }
+      if (!obj?.animation) continue;
+      const first = useNext ? changes.nextFirst[i] : changes.prevFirst[i];
+      const finished = useNext ? changes.nextFinished[i] : changes.prevFinished[i];
+      obj.animation.firstFrameIndex = first;
+      obj.animation.isFinished = !!finished;
+    }
+  },
+
+  _applyScalarChanges(game, delta, useNext) {
+    const derivedTick = Number.isFinite(delta?.tick)
+      ? Math.max(0, Math.trunc(delta.tick) + (useNext ? 1 : 0))
+      : null;
+    if (delta.victoryChanges) {
+      const victory = game.getVictoryCondition?.();
+      const state = useNext ? delta.victoryChanges.next : delta.victoryChanges.prev;
+      if (victory && state) {
+        victory.releaseRate = state.releaseRate;
+        victory.minReleaseRate = state.minReleaseRate;
+        victory.leftCount = state.leftCount;
+        victory.outCount = state.outCount;
+        victory.survivorCount = state.survivorCount;
+        victory.isFinalize = !!state.isFinalize;
+      }
+    }
+    if (delta.skillsChanges) {
+      const skills = game.getGameSkills?.();
+      const state = useNext ? delta.skillsChanges.next : delta.skillsChanges.prev;
+      if (skills && state) {
+        skills.selectedSkill = state.selectedSkill;
+        skills.cheatMode = !!state.cheatMode;
+        skills.skills = state.skills.slice();
+      }
+    }
+    if (delta.timerChanges) {
+      const timer = game.getGameTimer?.();
+      const state = useNext ? delta.timerChanges.next : delta.timerChanges.prev;
+      if (timer && state) {
+        const ignoreSpeed = !useNext && !!game?.timeTravel?.ignoreSpeedOnReverse;
+        if (!ignoreSpeed) {
+          timer.speedFactor = state.speedFactor;
+        }
+        timer.tickIndex = Number.isFinite(state.tickIndex) ? state.tickIndex : derivedTick;
+      }
+    } else if (derivedTick != null) {
+      const timer = game.getGameTimer?.();
+      if (timer) timer.tickIndex = derivedTick;
+    }
+    if (delta.gameChanges) {
+      const state = useNext ? delta.gameChanges.next : delta.gameChanges.prev;
+      if (state) game.finalGameState = state.finalGameState;
+    }
+  },
+
+  _applyMinimapDeaths(manager, entries, useNext) {
+    const miniMap = manager?.miniMap;
+    if (!miniMap || !entries?.length) return;
+    if (useNext) {
+      for (const entry of entries) {
+        const idx = entry.prevCount ?? miniMap.deadCount ?? 0;
+        const neededDots = (idx + 1) * 2;
+        if (miniMap.deadDots.length < neededDots) {
+          const next = Math.max(4, miniMap.deadDots.length * 2, neededDots);
+          const coords = new Uint8Array(next);
+          coords.set(miniMap.deadDots);
+          miniMap.deadDots = coords;
+        }
+        if (miniMap.deadTTLs.length < idx + 1) {
+          const next = Math.max(4, miniMap.deadTTLs.length * 2, idx + 1);
+          const ttls = new Uint8Array(next);
+          ttls.set(miniMap.deadTTLs);
+          miniMap.deadTTLs = ttls;
+        }
+        miniMap.deadDots[idx * 2] = entry.x ?? 0;
+        miniMap.deadDots[idx * 2 + 1] = entry.y ?? 0;
+        miniMap.deadTTLs[idx] = entry.ttl ?? 0;
+        miniMap.deadCount = Math.max(miniMap.deadCount ?? 0, idx + 1);
+      }
+      return;
+    }
+    for (let i = entries.length - 1; i >= 0; i--) {
+      const entry = entries[i];
+      const prevCount = entry.prevCount ?? 0;
+      miniMap.deadCount = prevCount;
+    }
+  },
+};
+
+export { historyStoreApplyDeltaMethods };
diff --git a/js/game/history/HistoryStoreApplyStateMethods.js b/js/game/history/HistoryStoreApplyStateMethods.js
new file mode 100644
index 00000000..4f42cd48
--- /dev/null
+++ b/js/game/history/HistoryStoreApplyStateMethods.js
@@ -0,0 +1,334 @@
+// @ts-check
+import { SkillTypes } from '../SkillTypes.js';
+import { Trigger } from '../../level/Trigger.js';
+import {
+  COLD_BLOCK_MAGIC,
+  COLD_BLOCK_VERSION,
+  COLD_DELTA_SENTINEL,
+  DEFAULT_OPTIONS,
+  DELTA_CODEC_VERSION,
+  DELTA_FLAG_ENTRANCE,
+  DELTA_FLAG_GROUND,
+  DELTA_FLAG_LEMMING_ADDS,
+  DELTA_FLAG_LEMMING_CHANGES,
+  DELTA_FLAG_LEMMING_MANAGER,
+  DELTA_FLAG_LEMMING_MUTATIONS,
+  DELTA_FLAG_LEMMING_REMOVALS,
+  DELTA_FLAG_MINIMAP_DEATHS,
+  DELTA_FLAG_OBJECTS,
+  DELTA_FLAG_SCALARS,
+  DELTA_FLAG_SOUND_EVENTS,
+  DELTA_FLAG_TRIGGERS,
+  NULL_INT32,
+  normalizeOptions,
+  toI32
+} from './HistoryShared.js';
+import {
+  BinaryReader,
+  BinaryWriter,
+  bytesEqual,
+  fnv1aHashBytes,
+  readTaggedValue,
+  rleDecodeBytes,
+  rleEncodeBytes,
+  writeTaggedValue
+} from './HistoryBinaryCodec.js';
+import {
+  applyLemmingSnapshot,
+  cloneLemmingState,
+  createLemmingState,
+  ensureLemmingCapacity,
+  snapshotLemming
+} from './HistoryLemmingState.js';
+import {
+  computeDeltaFlags,
+  createDelta,
+  ensureDeltaFlags,
+  isNoOpDelta,
+  packLemmingChanges,
+  packLemmingMutationList,
+  packTimerStateForStorage,
+  readPackedLemmingChanges,
+  readPackedLemmingMutation,
+  unpackLemmingChanges,
+  unpackLemmingMutationList,
+  unpackTimerStateFromStorage,
+  writePackedLemmingChanges,
+  writePackedLemmingMutation
+} from './HistoryDeltaCodec.js';
+import {
+  MIDI_FLAG_OWNER_KIND,
+  clonePlainObject,
+  createMidiFlagTriggerOwner
+} from './HistoryTriggerOwners.js';
+
+const historyStoreApplyStateMethods = {
+  applyKeyframe(game, keyframe) {
+    if (!game || !keyframe) return;
+    const manager = game.getLemmingManager?.();
+    if (manager && keyframe.lemmingState) {
+      const state = keyframe.lemmingState;
+      const lems = manager.lemmings || [];
+      if (lems.length !== state.present.length) {
+        manager.lemmings = new Array(state.present.length);
+      }
+      const countdownAction = manager.skillActions?.[SkillTypes.BOMBER] ?? null;
+      for (let i = 0; i < state.present.length; i++) {
+        if (!state.present[i]) {
+          manager.lemmings[i] = null;
+          continue;
+        }
+        let lem = manager.lemmings[i];
+        if (!lem) {
+          lem = this._createReplayLemming(manager, state.x[i], state.y[i], i);
+          manager.lemmings[i] = lem;
+        }
+        const action = state.actionType[i] >= 0 ? manager.actions?.[state.actionType[i]] : null;
+        const snap = {
+          id: i,
+          x: state.x[i],
+          y: state.y[i],
+          lookRight: state.lookRight[i],
+          frameIndex: state.frameIndex[i],
+          state: state.state[i],
+          canClimb: state.canClimb[i],
+          hasParachute: state.hasParachute[i],
+          removed: state.removed[i],
+          disabled: state.disabled[i],
+          countdown: state.countdown[i],
+          hasExploded: state.hasExploded[i],
+          lastTriggerType: state.lastTriggerType[i],
+          actionType: state.actionType[i],
+          countdownActive: state.countdownActive[i]
+        };
+        applyLemmingSnapshot(lem, snap, action, countdownAction);
+      }
+      this._rebuildActiveLemmings(manager);
+    }
+
+    if (manager && keyframe.lemmingManagerState) {
+      const state = keyframe.lemmingManagerState;
+      manager.selectedIndex = state.selectedIndex ?? -1;
+      manager.spawnTotal = state.spawnTotal ?? 0;
+      manager.releaseTickIndex = state.releaseTickIndex ?? 0;
+      manager.mmTickCounter = state.mmTickCounter ?? 0;
+      manager.nextNukingLemmingsIndex = state.nextNukingLemmingsIndex ?? -1;
+      manager._nukeTargets = this._resolveNukeTargets(manager, state.nukeTargets);
+    }
+
+    if (game.level && keyframe.entranceOpened) {
+      const entrances = game.level.entrances || [];
+      for (let i = 0; i < entrances.length; i++) {
+        entrances[i]._opened = !!keyframe.entranceOpened[i];
+      }
+    }
+
+    if (game.triggerManager && keyframe.triggerState) {
+      this._applyTriggerState(game, keyframe.triggerState);
+    }
+
+    if (game.level && keyframe.objectState) {
+      this._applyObjectState(game.level, keyframe.objectState);
+    }
+
+    if (manager?.miniMap && keyframe.minimapState) {
+      const miniMap = manager.miniMap;
+      miniMap.deadDots = new Uint8Array(keyframe.minimapState.deadDots || []);
+      miniMap.deadTTLs = new Uint8Array(keyframe.minimapState.deadTTLs || []);
+      miniMap.deadCount = keyframe.minimapState.deadCount ?? 0;
+    }
+    this._refreshMiniMapDots(manager);
+
+    if (game.level?.groundMask && keyframe.groundMask) {
+      game.level.groundMask.mask = new Uint8Array(keyframe.groundMask);
+    }
+    if (game.level && keyframe.groundImage) {
+      game.level.groundImage = new Uint8ClampedArray(keyframe.groundImage);
+    }
+
+    if (keyframe.victory) {
+      const victory = game.getVictoryCondition?.();
+      if (victory) {
+        victory.releaseRate = keyframe.victory.releaseRate;
+        victory.minReleaseRate = keyframe.victory.minReleaseRate;
+        victory.leftCount = keyframe.victory.leftCount;
+        victory.outCount = keyframe.victory.outCount;
+        victory.survivorCount = keyframe.victory.survivorCount;
+        victory.isFinalize = !!keyframe.victory.isFinalize;
+      }
+    }
+
+    if (keyframe.skills) {
+      const skills = game.getGameSkills?.();
+      if (skills) {
+        skills.selectedSkill = keyframe.skills.selectedSkill;
+        skills.cheatMode = !!keyframe.skills.cheatMode;
+        skills.skills = keyframe.skills.skills.slice();
+      }
+    }
+
+    if (keyframe.timer) {
+      const timer = game.getGameTimer?.();
+      if (timer) {
+        const ignoreSpeed = !!game?.timeTravel?.isReversing &&
+            !!game?.timeTravel?.ignoreSpeedOnReverse;
+        if (!ignoreSpeed) {
+          timer.speedFactor = keyframe.timer.speedFactor;
+        }
+        timer.tickIndex = keyframe.timer.tickIndex;
+      }
+    }
+
+    if (keyframe.gameState) {
+      game.finalGameState = keyframe.gameState.finalGameState;
+    }
+
+    this.captureBaseline(game);
+  },
+
+  _readTriggerState(game) {
+    const triggerManager = game?.triggerManager;
+    const level = game?.level;
+    if (!triggerManager || !level) return null;
+    const staticTriggers = [];
+    const dynamicTriggers = [];
+    const levelTriggers = level.triggers || [];
+    const staticSet = this._scratchStaticTriggers;
+    staticSet.clear();
+    for (let i = 0; i < levelTriggers.length; i += 1) {
+      staticSet.add(levelTriggers[i]);
+    }
+    for (let i = 0; i < levelTriggers.length; i++) {
+      const trig = levelTriggers[i];
+      if (!trig) continue;
+      const id = this._ensureTriggerId(trig);
+      staticTriggers.push({ id, disabledUntilTick: trig.disabledUntilTick });
+    }
+    const readDynamicTrigger = (trig, observer = false) => {
+      if (!trig || staticSet.has(trig)) return;
+      const ownerSnapshot = this._readTriggerOwnerSnapshot(trig);
+      if (ownerSnapshot.ownerKind == null) return;
+      const id = this._ensureTriggerId(trig);
+      dynamicTriggers.push({
+        id,
+        ...ownerSnapshot,
+        type: trig.type,
+        x1: trig.x1,
+        y1: trig.y1,
+        x2: trig.x2,
+        y2: trig.y2,
+        disableTicksCount: trig.disableTicksCount,
+        soundIndex: trig.soundIndex,
+        disabledUntilTick: trig.disabledUntilTick,
+        observer
+      });
+    };
+    for (const trig of triggerManager._triggers || []) {
+      readDynamicTrigger(trig, false);
+    }
+    for (const trig of triggerManager._observerTriggers || []) {
+      readDynamicTrigger(trig, true);
+    }
+    staticSet.clear();
+    return { staticTriggers, dynamicTriggers };
+  },
+
+  _applyTriggerState(game, state) {
+    const triggerManager = game.triggerManager;
+    const level = game.level;
+    if (!triggerManager || !level || !state) return;
+    const levelTriggers = level.triggers || [];
+    for (let i = 0; i < levelTriggers.length; i++) {
+      const trig = levelTriggers[i];
+      const entry = state.staticTriggers?.[i] || null;
+      if (!trig || !entry) continue;
+      trig.disabledUntilTick = entry.disabledUntilTick;
+      this._ensureTriggerId(trig);
+    }
+
+    const dynamic = state.dynamicTriggers || [];
+    const staticSet = this._scratchStaticTriggers;
+    staticSet.clear();
+    for (let i = 0; i < levelTriggers.length; i += 1) {
+      if (levelTriggers[i]) staticSet.add(levelTriggers[i]);
+    }
+    const removeList = [];
+    for (const triggerSet of [triggerManager._triggers, triggerManager._observerTriggers]) {
+      for (const trig of triggerSet || []) {
+        if (!trig || staticSet.has(trig)) continue;
+        if (this._isReplayManagedDynamicTrigger(trig)) removeList.push(trig);
+      }
+    }
+    staticSet.clear();
+    for (const trig of removeList) {
+      this._removeTriggerInstance(triggerManager, trig);
+    }
+    for (const snap of dynamic) {
+      const owner = this._resolveTriggerOwner(game, snap);
+      const trig = new Trigger(
+        snap.type,
+        snap.x1,
+        snap.y1,
+        snap.x2,
+        snap.y2,
+        snap.disableTicksCount,
+        snap.soundIndex,
+        owner
+      );
+      trig.disabledUntilTick = snap.disabledUntilTick;
+      trig.__historyId = snap.id;
+      if (snap.observer === true && typeof triggerManager.addObserver === 'function') {
+        triggerManager.addObserver(trig);
+      } else {
+        triggerManager.add(trig);
+      }
+      this._triggerById.set(snap.id, trig);
+    }
+  },
+
+  _readObjectState(level) {
+    const objects = level?.objects || [];
+    const out = [];
+    for (const obj of objects) {
+      if (!obj?.animation) continue;
+      const id = this._ensureObjectId(obj);
+      out.push({
+        id,
+        firstFrameIndex: obj.animation.firstFrameIndex,
+        isFinished: obj.animation.isFinished
+      });
+    }
+    return out;
+  },
+
+  _applyObjectState(level, state) {
+    for (const entry of state || []) {
+      let obj = this._objectById.get(entry.id);
+      if (!obj) {
+        const objects = level?.objects || [];
+        for (const candidate of objects) {
+          if (!candidate?.animation) continue;
+          const candidateId = this._ensureObjectId(candidate);
+          if (candidateId === entry.id) {
+            obj = candidate;
+            break;
+          }
+        }
+      }
+      if (!obj?.animation) continue;
+      obj.animation.firstFrameIndex = entry.firstFrameIndex;
+      obj.animation.isFinished = !!entry.isFinished;
+    }
+  },
+
+  _readMinimapState(miniMap) {
+    if (!miniMap) return null;
+    return {
+      deadDots: new Uint8Array(miniMap.deadDots || []),
+      deadTTLs: new Uint8Array(miniMap.deadTTLs || []),
+      deadCount: miniMap.deadCount ?? 0
+    };
+  },
+};
+
+export { historyStoreApplyStateMethods };
diff --git a/js/game/history/HistoryStoreColdBlockCodecMethods.js b/js/game/history/HistoryStoreColdBlockCodecMethods.js
new file mode 100644
index 00000000..f74bd9eb
--- /dev/null
+++ b/js/game/history/HistoryStoreColdBlockCodecMethods.js
@@ -0,0 +1,316 @@
+// @ts-check
+import { SkillTypes } from '../SkillTypes.js';
+import { Trigger } from '../../level/Trigger.js';
+import {
+  COLD_BLOCK_MAGIC,
+  COLD_BLOCK_VERSION,
+  COLD_DELTA_SENTINEL,
+  DEFAULT_OPTIONS,
+  DELTA_CODEC_VERSION,
+  DELTA_FLAG_ENTRANCE,
+  DELTA_FLAG_GROUND,
+  DELTA_FLAG_LEMMING_ADDS,
+  DELTA_FLAG_LEMMING_CHANGES,
+  DELTA_FLAG_LEMMING_MANAGER,
+  DELTA_FLAG_LEMMING_MUTATIONS,
+  DELTA_FLAG_LEMMING_REMOVALS,
+  DELTA_FLAG_MINIMAP_DEATHS,
+  DELTA_FLAG_OBJECTS,
+  DELTA_FLAG_SCALARS,
+  DELTA_FLAG_SOUND_EVENTS,
+  DELTA_FLAG_TRIGGERS,
+  NULL_INT32,
+  normalizeOptions,
+  toI32
+} from './HistoryShared.js';
+import {
+  BinaryReader,
+  BinaryWriter,
+  bytesEqual,
+  fnv1aHashBytes,
+  readTaggedValue,
+  rleDecodeBytes,
+  rleEncodeBytes,
+  writeTaggedValue
+} from './HistoryBinaryCodec.js';
+import {
+  applyLemmingSnapshot,
+  cloneLemmingState,
+  createLemmingState,
+  ensureLemmingCapacity,
+  snapshotLemming
+} from './HistoryLemmingState.js';
+import {
+  computeDeltaFlags,
+  createDelta,
+  ensureDeltaFlags,
+  isNoOpDelta,
+  packLemmingChanges,
+  packLemmingMutationList,
+  packTimerStateForStorage,
+  readPackedLemmingChanges,
+  readPackedLemmingMutation,
+  unpackLemmingChanges,
+  unpackLemmingMutationList,
+  unpackTimerStateFromStorage,
+  writePackedLemmingChanges,
+  writePackedLemmingMutation
+} from './HistoryDeltaCodec.js';
+import {
+  MIDI_FLAG_OWNER_KIND,
+  clonePlainObject,
+  createMidiFlagTriggerOwner
+} from './HistoryTriggerOwners.js';
+
+const historyStoreColdBlockCodecMethods = {
+  _buildColdBlockPayload(block) {
+    const noOpStarts = [];
+    const noOpLengths = [];
+    const deltaOffsets = [];
+    const deltaBytes = [];
+    let runStart = -1;
+    let runLen = 0;
+    for (let tick = block.startTick; tick <= block.endTick; tick += 1) {
+      const entry = this.deltas[tick];
+      if (!entry || entry === COLD_DELTA_SENTINEL) {
+        if (runLen > 0) {
+          noOpStarts.push(runStart);
+          noOpLengths.push(runLen);
+          runStart = -1;
+          runLen = 0;
+        }
+        continue;
+      }
+      const offset = tick - block.startTick;
+      if (isNoOpDelta(entry)) {
+        if (runLen === 0) {
+          runStart = offset;
+          runLen = 1;
+        } else if (offset === (runStart + runLen)) {
+          runLen += 1;
+        } else {
+          noOpStarts.push(runStart);
+          noOpLengths.push(runLen);
+          runStart = offset;
+          runLen = 1;
+        }
+      } else {
+        if (runLen > 0) {
+          noOpStarts.push(runStart);
+          noOpLengths.push(runLen);
+          runStart = -1;
+          runLen = 0;
+        }
+        const packed = this._packDeltaForStorage(entry);
+        deltaOffsets.push(offset);
+        deltaBytes.push(packed);
+      }
+    }
+    if (runLen > 0) {
+      noOpStarts.push(runStart);
+      noOpLengths.push(runLen);
+    }
+    return {
+      noOpStarts: Uint32Array.from(noOpStarts),
+      noOpLengths: Uint32Array.from(noOpLengths),
+      deltaOffsets: Uint32Array.from(deltaOffsets),
+      deltaBytes
+    };
+  },
+
+  _encodeColdBlockPayload(payload) {
+    const writer = new BinaryWriter();
+    writer.writeU32(COLD_BLOCK_MAGIC);
+    writer.writeU8(COLD_BLOCK_VERSION);
+    const noOpCount = payload?.noOpStarts?.length || 0;
+    writer.writeVarUint(noOpCount);
+    for (let i = 0; i < noOpCount; i += 1) {
+      writer.writeVarUint(payload.noOpStarts[i]);
+      writer.writeVarUint(payload.noOpLengths[i]);
+    }
+    const deltaCount = payload?.deltaOffsets?.length || 0;
+    writer.writeVarUint(deltaCount);
+    for (let i = 0; i < deltaCount; i += 1) {
+      writer.writeVarUint(payload.deltaOffsets[i]);
+    }
+    for (let i = 0; i < deltaCount; i += 1) {
+      const bytes = payload.deltaBytes?.[i] || new Uint8Array(0);
+      writer.writeVarUint(bytes.length);
+    }
+    for (let i = 0; i < deltaCount; i += 1) {
+      writer.writeRaw(payload.deltaBytes?.[i] || new Uint8Array(0));
+    }
+    return writer.toUint8Array();
+  },
+
+  _decodeColdBlockPayload(bytes) {
+    const reader = new BinaryReader(bytes);
+    const magic = reader.readU32();
+    if (magic !== COLD_BLOCK_MAGIC) {
+      throw new Error('HistoryStore cold-block magic mismatch.');
+    }
+    const version = reader.readU8();
+    if (version !== COLD_BLOCK_VERSION) {
+      throw new Error(`HistoryStore cold-block version ${version} is unsupported.`);
+    }
+
+    const noOpCount = reader.readVarUint();
+    const noOpRanges = new Array(noOpCount);
+    for (let i = 0; i < noOpCount; i += 1) {
+      noOpRanges[i] = [reader.readVarUint(), reader.readVarUint()];
+    }
+
+    const deltaCount = reader.readVarUint();
+    const offsets = new Array(deltaCount);
+    const lengths = new Array(deltaCount);
+    for (let i = 0; i < deltaCount; i += 1) offsets[i] = reader.readVarUint();
+    for (let i = 0; i < deltaCount; i += 1) lengths[i] = reader.readVarUint();
+    const deltaEntries = new Array(deltaCount);
+    for (let i = 0; i < deltaCount; i += 1) {
+      deltaEntries[i] = [offsets[i], reader.readRaw(lengths[i])];
+    }
+    if (!reader.eof()) {
+      throw new Error('HistoryStore cold-block payload has trailing bytes.');
+    }
+    return { noOpRanges, deltaEntries };
+  },
+
+  _decodeColdBlock(block) {
+    if (!block?.cold || !block.encodedBytes) return null;
+    if (block.decoded) return block.decoded;
+    const bytes = block.encoding === 'rle'
+      ? rleDecodeBytes(block.encodedBytes)
+      : block.encodedBytes;
+    const payload = this._decodeColdBlockPayload(bytes);
+    const deltaMap = new Map();
+    for (const [offset, deltaBytes] of payload.deltaEntries || []) {
+      const tick = block.startTick + offset;
+      deltaMap.set(offset, this._unpackDeltaFromStorage(deltaBytes, tick));
+    }
+    block.decoded = {
+      noOpRanges: payload.noOpRanges || [],
+      deltaMap,
+      noOpCache: new Map()
+    };
+    return block.decoded;
+  },
+
+  _packDeltaForStorage(delta) {
+    const writer = new BinaryWriter();
+    const flags = computeDeltaFlags(delta);
+    const tick = toI32(delta?.tick);
+    writer.writeU8(DELTA_CODEC_VERSION);
+    writer.writeU32(flags);
+    if (flags & DELTA_FLAG_LEMMING_CHANGES) {
+      writePackedLemmingChanges(writer, packLemmingChanges(delta.lemChanges));
+    }
+    if (flags & DELTA_FLAG_LEMMING_ADDS) {
+      writePackedLemmingMutation(writer, packLemmingMutationList(delta.lemAdded));
+    }
+    if (flags & DELTA_FLAG_LEMMING_REMOVALS) {
+      writePackedLemmingMutation(writer, packLemmingMutationList(delta.lemRemoved));
+    }
+    if (flags & DELTA_FLAG_LEMMING_MANAGER) {
+      writeTaggedValue(writer, delta.lemmingManagerChanges || null);
+    }
+    if (flags & DELTA_FLAG_GROUND) {
+      writeTaggedValue(writer, delta.groundChanges || null);
+    }
+    if (flags & DELTA_FLAG_ENTRANCE) {
+      writeTaggedValue(writer, delta.entranceChanges || null);
+    }
+    if (flags & DELTA_FLAG_TRIGGERS) {
+      writeTaggedValue(writer, {
+        triggerCooldownChanges: delta.triggerCooldownChanges || null,
+        triggerAdd: delta.triggerAdd || [],
+        triggerRemove: delta.triggerRemove || []
+      });
+    }
+    if (flags & DELTA_FLAG_OBJECTS) {
+      writeTaggedValue(writer, delta.objectAnimChanges || null);
+    }
+    if (flags & DELTA_FLAG_SCALARS) {
+      writeTaggedValue(writer, {
+        victoryChanges: delta.victoryChanges || null,
+        skillsChanges: delta.skillsChanges || null,
+        timerChanges: delta.timerChanges
+          ? {
+            prev: packTimerStateForStorage(delta.timerChanges.prev, tick),
+            next: packTimerStateForStorage(delta.timerChanges.next, tick)
+          }
+          : null,
+        gameChanges: delta.gameChanges || null
+      });
+    }
+    if (flags & DELTA_FLAG_SOUND_EVENTS) {
+      writeTaggedValue(writer, delta.soundEvents || []);
+    }
+    if (flags & DELTA_FLAG_MINIMAP_DEATHS) {
+      writeTaggedValue(writer, delta.minimapDeaths || []);
+    }
+    return writer.toUint8Array();
+  },
+
+  _unpackDeltaFromStorage(packed, tick) {
+    const reader = new BinaryReader(packed);
+    const version = reader.readU8();
+    if (version !== DELTA_CODEC_VERSION) {
+      throw new Error(`HistoryStore delta codec version ${version} is unsupported.`);
+    }
+    const flags = reader.readU32() | 0;
+    const delta = createDelta(tick);
+    delta.flags = flags;
+
+    if (flags & DELTA_FLAG_LEMMING_CHANGES) {
+      delta.lemChanges = unpackLemmingChanges(readPackedLemmingChanges(reader));
+    }
+    if (flags & DELTA_FLAG_LEMMING_ADDS) {
+      delta.lemAdded = unpackLemmingMutationList(readPackedLemmingMutation(reader));
+    }
+    if (flags & DELTA_FLAG_LEMMING_REMOVALS) {
+      delta.lemRemoved = unpackLemmingMutationList(readPackedLemmingMutation(reader));
+    }
+    if (flags & DELTA_FLAG_LEMMING_MANAGER) {
+      delta.lemmingManagerChanges = readTaggedValue(reader);
+    }
+    if (flags & DELTA_FLAG_GROUND) {
+      delta.groundChanges = readTaggedValue(reader) || delta.groundChanges;
+    }
+    if (flags & DELTA_FLAG_ENTRANCE) {
+      delta.entranceChanges = readTaggedValue(reader) || delta.entranceChanges;
+    }
+    if (flags & DELTA_FLAG_TRIGGERS) {
+      const triggerPayload = readTaggedValue(reader) || {};
+      delta.triggerCooldownChanges = triggerPayload.triggerCooldownChanges || delta.triggerCooldownChanges;
+      delta.triggerAdd = triggerPayload.triggerAdd || delta.triggerAdd;
+      delta.triggerRemove = triggerPayload.triggerRemove || delta.triggerRemove;
+    }
+    if (flags & DELTA_FLAG_OBJECTS) {
+      delta.objectAnimChanges = readTaggedValue(reader) || delta.objectAnimChanges;
+    }
+    if (flags & DELTA_FLAG_SCALARS) {
+      const scalarPayload = readTaggedValue(reader) || {};
+      delta.victoryChanges = scalarPayload.victoryChanges || null;
+      delta.skillsChanges = scalarPayload.skillsChanges || null;
+      delta.timerChanges = scalarPayload.timerChanges
+        ? {
+          prev: unpackTimerStateFromStorage(scalarPayload.timerChanges.prev, tick),
+          next: unpackTimerStateFromStorage(scalarPayload.timerChanges.next, tick)
+        }
+        : null;
+      delta.gameChanges = scalarPayload.gameChanges || null;
+    }
+    if (flags & DELTA_FLAG_SOUND_EVENTS) {
+      delta.soundEvents = readTaggedValue(reader) || [];
+    }
+    if (flags & DELTA_FLAG_MINIMAP_DEATHS) {
+      delta.minimapDeaths = readTaggedValue(reader) || [];
+    }
+    if (!reader.eof()) {
+      throw new Error('HistoryStore delta payload has trailing bytes.');
+    }
+    return delta;
+  },
+};
+
+export { historyStoreColdBlockCodecMethods };
diff --git a/js/game/history/HistoryStoreColdBlockStorageMethods.js b/js/game/history/HistoryStoreColdBlockStorageMethods.js
new file mode 100644
index 00000000..90c4b17a
--- /dev/null
+++ b/js/game/history/HistoryStoreColdBlockStorageMethods.js
@@ -0,0 +1,271 @@
+// @ts-check
+import { SkillTypes } from '../SkillTypes.js';
+import { Trigger } from '../../level/Trigger.js';
+import {
+  COLD_BLOCK_MAGIC,
+  COLD_BLOCK_VERSION,
+  COLD_DELTA_SENTINEL,
+  DEFAULT_OPTIONS,
+  DELTA_CODEC_VERSION,
+  DELTA_FLAG_ENTRANCE,
+  DELTA_FLAG_GROUND,
+  DELTA_FLAG_LEMMING_ADDS,
+  DELTA_FLAG_LEMMING_CHANGES,
+  DELTA_FLAG_LEMMING_MANAGER,
+  DELTA_FLAG_LEMMING_MUTATIONS,
+  DELTA_FLAG_LEMMING_REMOVALS,
+  DELTA_FLAG_MINIMAP_DEATHS,
+  DELTA_FLAG_OBJECTS,
+  DELTA_FLAG_SCALARS,
+  DELTA_FLAG_SOUND_EVENTS,
+  DELTA_FLAG_TRIGGERS,
+  NULL_INT32,
+  normalizeOptions,
+  toI32
+} from './HistoryShared.js';
+import {
+  BinaryReader,
+  BinaryWriter,
+  bytesEqual,
+  fnv1aHashBytes,
+  readTaggedValue,
+  rleDecodeBytes,
+  rleEncodeBytes,
+  writeTaggedValue
+} from './HistoryBinaryCodec.js';
+import {
+  applyLemmingSnapshot,
+  cloneLemmingState,
+  createLemmingState,
+  ensureLemmingCapacity,
+  snapshotLemming
+} from './HistoryLemmingState.js';
+import {
+  computeDeltaFlags,
+  createDelta,
+  ensureDeltaFlags,
+  isNoOpDelta,
+  packLemmingChanges,
+  packLemmingMutationList,
+  packTimerStateForStorage,
+  readPackedLemmingChanges,
+  readPackedLemmingMutation,
+  unpackLemmingChanges,
+  unpackLemmingMutationList,
+  unpackTimerStateFromStorage,
+  writePackedLemmingChanges,
+  writePackedLemmingMutation
+} from './HistoryDeltaCodec.js';
+import {
+  MIDI_FLAG_OWNER_KIND,
+  clonePlainObject,
+  createMidiFlagTriggerOwner
+} from './HistoryTriggerOwners.js';
+
+const historyStoreColdBlockStorageMethods = {
+  _deltaBlockStart(tickIndex) {
+    const size = this.options.deltaBlockSizeTicks || DEFAULT_OPTIONS.deltaBlockSizeTicks;
+    return Math.floor(Math.trunc(tickIndex) / size) * size;
+  },
+
+  _deltaBlockEnd(startTick) {
+    const size = this.options.deltaBlockSizeTicks || DEFAULT_OPTIONS.deltaBlockSizeTicks;
+    return startTick + size - 1;
+  },
+
+  _ensureDeltaBlock(tickIndex) {
+    const start = this._deltaBlockStart(tickIndex);
+    let block = this._deltaBlocks.get(start);
+    if (!block) {
+      block = {
+        startTick: start,
+        endTick: this._deltaBlockEnd(start),
+        cold: false,
+        encoding: null,
+        encodedBytes: null,
+        encodedStoreKey: null,
+        decoded: null
+      };
+      this._deltaBlocks.set(start, block);
+    }
+    return block;
+  },
+
+  _retainColdBytes(storeKey, bytes) {
+    let bucket = this._coldBlockStore.get(storeKey);
+    if (!bucket) {
+      bucket = [];
+      this._coldBlockStore.set(storeKey, bucket);
+    }
+    for (const entry of bucket) {
+      if (bytesEqual(entry.bytes, bytes)) {
+        entry.refs += 1;
+        return entry.bytes;
+      }
+    }
+    bucket.push({ bytes, refs: 1 });
+    this._coldBlockBytes += bytes.length;
+    return bytes;
+  },
+
+  _releaseColdBytes(storeKey, bytes) {
+    if (!storeKey || !bytes) return;
+    const bucket = this._coldBlockStore.get(storeKey);
+    if (!bucket) return;
+    for (let i = 0; i < bucket.length; i += 1) {
+      const entry = bucket[i];
+      if (entry.bytes !== bytes) continue;
+      entry.refs -= 1;
+      if (entry.refs <= 0) {
+        this._coldBlockBytes -= entry.bytes.length;
+        bucket.splice(i, 1);
+      }
+      break;
+    }
+    if (!bucket.length) {
+      this._coldBlockStore.delete(storeKey);
+    }
+  },
+
+  _buildNoOpDelta(tickIndex) {
+    return createDelta(Math.trunc(tickIndex));
+  },
+
+  _resolveColdDelta(tickIndex) {
+    const tick = Math.trunc(tickIndex);
+    const block = this._deltaBlocks.get(this._deltaBlockStart(tick));
+    if (!block || !block.cold) return null;
+    const decoded = this._decodeColdBlock(block);
+    if (!decoded) return null;
+    const offset = tick - block.startTick;
+    if (decoded.deltaMap.has(offset)) {
+      return decoded.deltaMap.get(offset);
+    }
+    for (const [start, len] of decoded.noOpRanges) {
+      if (offset >= start && offset < (start + len)) {
+        if (!decoded.noOpCache.has(offset)) {
+          decoded.noOpCache.set(offset, this._buildNoOpDelta(tick));
+        }
+        return decoded.noOpCache.get(offset);
+      }
+    }
+    return null;
+  },
+
+  _compactDeltaBlock(block) {
+    if (!block || block.cold) return false;
+    const payload = this._buildColdBlockPayload(block);
+    if (!payload.deltaOffsets.length && !payload.noOpStarts.length) return false;
+    const rawBytes = this._encodeColdBlockPayload(payload);
+    const compressed = this.options.enableColdBlockCompression ? rleEncodeBytes(rawBytes) : rawBytes;
+    const useCompressed = compressed.length < rawBytes.length;
+    const encodedBytes = useCompressed ? compressed : rawBytes;
+    const encoding = useCompressed ? 'rle' : 'raw';
+    const hash = fnv1aHashBytes(encodedBytes);
+    const storeKey = `${encoding}:${hash}:${encodedBytes.length}`;
+    const sharedBytes = this.options.enableColdBlockDedupe
+      ? this._retainColdBytes(storeKey, encodedBytes)
+      : encodedBytes;
+    if (!this.options.enableColdBlockDedupe) {
+      this._coldBlockBytes += encodedBytes.length;
+    }
+    block.cold = true;
+    block.encoding = encoding;
+    block.encodedBytes = sharedBytes;
+    block.encodedStoreKey = storeKey;
+    block.decoded = null;
+    this._coldBlockCount += 1;
+
+    for (let tick = block.startTick; tick <= block.endTick; tick += 1) {
+      const entry = this.deltas[tick];
+      if (!entry || entry === COLD_DELTA_SENTINEL) continue;
+      this._releaseDelta(entry);
+      this.deltas[tick] = COLD_DELTA_SENTINEL;
+    }
+    return true;
+  },
+
+  _thawDeltaBlock(blockStart) {
+    const block = this._deltaBlocks.get(blockStart);
+    if (!block || !block.cold) return;
+    for (let tick = block.startTick; tick <= block.endTick; tick += 1) {
+      if (this.deltas[tick] !== COLD_DELTA_SENTINEL) continue;
+      const delta = this._resolveColdDelta(tick);
+      this.deltas[tick] = delta || undefined;
+      if (!delta) {
+        this.deltaCount = Math.max(0, this.deltaCount - 1);
+      }
+    }
+    if (this.options.enableColdBlockDedupe) {
+      this._releaseColdBytes(block.encodedStoreKey, block.encodedBytes);
+    } else if (block.encodedBytes) {
+      this._coldBlockBytes -= block.encodedBytes.length;
+    }
+    block.cold = false;
+    block.encoding = null;
+    block.encodedBytes = null;
+    block.encodedStoreKey = null;
+    block.decoded = null;
+    this._coldBlockCount = Math.max(0, this._coldBlockCount - 1);
+  },
+
+  _cleanupDeltaBlock(blockStart) {
+    const block = this._deltaBlocks.get(blockStart);
+    if (!block) return;
+    let hasEntries = false;
+    for (let tick = block.startTick; tick <= block.endTick; tick += 1) {
+      if (this.deltas[tick]) {
+        hasEntries = true;
+        break;
+      }
+    }
+    if (hasEntries) return;
+    if (block.cold) {
+      if (this.options.enableColdBlockDedupe) {
+        this._releaseColdBytes(block.encodedStoreKey, block.encodedBytes);
+      } else if (block.encodedBytes) {
+        this._coldBlockBytes -= block.encodedBytes.length;
+      }
+      this._coldBlockCount = Math.max(0, this._coldBlockCount - 1);
+    }
+    this._deltaBlocks.delete(blockStart);
+  },
+
+  _maybeCompactDeltaBlocks() {
+    const age = this.options.coldBlockAgeTicks ?? 0;
+    if (age <= 0 || this.maxDeltaTick == null || this.minDeltaTick == null) return;
+    const interval = this.options.coldCompactionIntervalTicks || DEFAULT_OPTIONS.coldCompactionIntervalTicks;
+    if (interval > 1 && (this.maxDeltaTick % interval) !== 0) return;
+    const cutoff = this.maxDeltaTick - age;
+    const firstStart = this._deltaBlockStart(this.minDeltaTick);
+    const lastStart = this._deltaBlockStart(cutoff);
+    if (lastStart < firstStart) return;
+
+    if (!Number.isFinite(this._coldCompactionCursor)
+          || this._coldCompactionCursor < firstStart
+          || this._coldCompactionCursor > lastStart) {
+      this._coldCompactionCursor = firstStart;
+    }
+
+    const budget = this.options.coldCompactionMaxBlocksPerSweep
+        || DEFAULT_OPTIONS.coldCompactionMaxBlocksPerSweep;
+    const stride = this.options.deltaBlockSizeTicks || DEFAULT_OPTIONS.deltaBlockSizeTicks;
+    let cursor = this._coldCompactionCursor;
+    let remaining = budget;
+    while (remaining > 0) {
+      const block = this._deltaBlocks.get(cursor);
+      if (block && !block.cold && block.endTick <= cutoff) {
+        this._compactDeltaBlock(block);
+      }
+      remaining -= 1;
+      cursor += stride;
+      if (cursor > lastStart) {
+        cursor = firstStart;
+      }
+      if (cursor === this._coldCompactionCursor) break;
+    }
+    this._coldCompactionCursor = cursor;
+  },
+};
+
+export { historyStoreColdBlockStorageMethods };
diff --git a/js/game/history/HistoryStoreCore.js b/js/game/history/HistoryStoreCore.js
new file mode 100644
index 00000000..68ab0684
--- /dev/null
+++ b/js/game/history/HistoryStoreCore.js
@@ -0,0 +1,91 @@
+// @ts-check
+import {
+  DEFAULT_OPTIONS,
+  normalizeOptions
+} from './HistoryShared.js';
+import {
+  applyLemmingSnapshot,
+  cloneLemmingState,
+  createLemmingState,
+  ensureLemmingCapacity,
+  snapshotLemming
+} from './HistoryLemmingState.js';
+import { isNoOpDelta } from './HistoryDeltaCodec.js';
+import { historyStoreStatsMethods } from './HistoryStoreStatsMethods.js';
+import { historyStoreColdBlockStorageMethods } from './HistoryStoreColdBlockStorageMethods.js';
+import { historyStoreColdBlockCodecMethods } from './HistoryStoreColdBlockCodecMethods.js';
+import { historyStoreLifecycleMethods } from './HistoryStoreLifecycleMethods.js';
+import { historyStoreRecordingMethods } from './HistoryStoreRecordingMethods.js';
+import { historyStoreDiffMethods } from './HistoryStoreDiffMethods.js';
+import { historyStoreApplyStateMethods } from './HistoryStoreApplyStateMethods.js';
+import { historyStoreApplyDeltaMethods } from './HistoryStoreApplyDeltaMethods.js';
+
+class HistoryStore {
+  constructor(options = {}) {
+    this.options = normalizeOptions({ ...DEFAULT_OPTIONS, ...options });
+    this.keyframes = [];
+    this.keyframeTicks = [];
+    this.deltas = [];
+    this.minDeltaTick = null;
+    this.maxDeltaTick = null;
+    this.minKeyframeTick = null;
+    this.maxKeyframeTick = null;
+    this.deltaCount = 0;
+    this.keyframeCount = 0;
+    this._deltaPool = [];
+    this._deltaBlocks = new Map();
+    this._coldBlockStore = new Map();
+    this._coldBlockCount = 0;
+    this._coldBlockBytes = 0;
+    this._coldCompactionCursor = null;
+    this._historyWarned = false;
+    this._recording = false;
+    this._currentTick = null;
+    this._currentDelta = null;
+    this._lemmingState = createLemmingState(0);
+    this._lemmingManagerState = null;
+    this._entranceOpened = new Uint8Array(0);
+    this._skillsState = null;
+    this._victoryState = null;
+    this._timerState = null;
+    this._gameState = null;
+    this._nextTriggerId = 1;
+    this._triggerIds = new Map();
+    this._triggerById = new Map();
+    this._nextObjectId = 1;
+    this._objectIds = new Map();
+    this._objectById = new Map();
+    this.game = null;
+    this.timer = null;
+    this._beforeTick = null;
+    this._afterTick = null;
+    this._groundDirty = true;
+    this._lastKeyframe = null;
+    this._scratchTouchedBlocks = new Set();
+    this._scratchStaticTriggers = new Set();
+    this._scratchRemoveOwners = new Set();
+  }
+}
+
+Object.assign(
+  HistoryStore.prototype,
+  historyStoreStatsMethods,
+  historyStoreColdBlockStorageMethods,
+  historyStoreColdBlockCodecMethods,
+  historyStoreLifecycleMethods,
+  historyStoreRecordingMethods,
+  historyStoreDiffMethods,
+  historyStoreApplyStateMethods,
+  historyStoreApplyDeltaMethods
+);
+
+const __test__ = {
+  createLemmingState,
+  cloneLemmingState,
+  ensureLemmingCapacity,
+  snapshotLemming,
+  applyLemmingSnapshot,
+  isNoOpDelta
+};
+
+export { HistoryStore, __test__ };
diff --git a/js/game/history/HistoryStoreDiffMethods.js b/js/game/history/HistoryStoreDiffMethods.js
new file mode 100644
index 00000000..03f74599
--- /dev/null
+++ b/js/game/history/HistoryStoreDiffMethods.js
@@ -0,0 +1,483 @@
+// @ts-check
+import { SkillTypes } from '../SkillTypes.js';
+import { Trigger } from '../../level/Trigger.js';
+import {
+  COLD_BLOCK_MAGIC,
+  COLD_BLOCK_VERSION,
+  COLD_DELTA_SENTINEL,
+  DEFAULT_OPTIONS,
+  DELTA_CODEC_VERSION,
+  DELTA_FLAG_ENTRANCE,
+  DELTA_FLAG_GROUND,
+  DELTA_FLAG_LEMMING_ADDS,
+  DELTA_FLAG_LEMMING_CHANGES,
+  DELTA_FLAG_LEMMING_MANAGER,
+  DELTA_FLAG_LEMMING_MUTATIONS,
+  DELTA_FLAG_LEMMING_REMOVALS,
+  DELTA_FLAG_MINIMAP_DEATHS,
+  DELTA_FLAG_OBJECTS,
+  DELTA_FLAG_SCALARS,
+  DELTA_FLAG_SOUND_EVENTS,
+  DELTA_FLAG_TRIGGERS,
+  NULL_INT32,
+  normalizeOptions,
+  toI32
+} from './HistoryShared.js';
+import {
+  BinaryReader,
+  BinaryWriter,
+  bytesEqual,
+  fnv1aHashBytes,
+  readTaggedValue,
+  rleDecodeBytes,
+  rleEncodeBytes,
+  writeTaggedValue
+} from './HistoryBinaryCodec.js';
+import {
+  applyLemmingSnapshot,
+  cloneLemmingState,
+  createLemmingState,
+  ensureLemmingCapacity,
+  snapshotLemming
+} from './HistoryLemmingState.js';
+import {
+  computeDeltaFlags,
+  createDelta,
+  ensureDeltaFlags,
+  isNoOpDelta,
+  packLemmingChanges,
+  packLemmingMutationList,
+  packTimerStateForStorage,
+  readPackedLemmingChanges,
+  readPackedLemmingMutation,
+  unpackLemmingChanges,
+  unpackLemmingMutationList,
+  unpackTimerStateFromStorage,
+  writePackedLemmingChanges,
+  writePackedLemmingMutation
+} from './HistoryDeltaCodec.js';
+import {
+  MIDI_FLAG_OWNER_KIND,
+  clonePlainObject,
+  createMidiFlagTriggerOwner
+} from './HistoryTriggerOwners.js';
+
+const historyStoreDiffMethods = {
+  _captureKeyframe(game, tickIndex) {
+    const lemmingManager = game.getLemmingManager?.();
+    const lemmings = lemmingManager?.lemmings || [];
+    const lemmingState = cloneLemmingState(this._lemmingState, lemmings.length || 0);
+    const lemmingManagerState = this._readLemmingManager(lemmingManager);
+    const entrances = game.level?.entrances || [];
+    const entranceOpened = new Uint8Array(entrances.length);
+    for (let i = 0; i < entrances.length; i++) {
+      entranceOpened[i] = entrances[i]?._opened ? 1 : 0;
+    }
+    const triggerState = this._readTriggerState(game);
+    const objectState = this._readObjectState(game.level);
+    const minimapState = this._readMinimapState(lemmingManager?.miniMap);
+    const victory = this._readVictory(game.getVictoryCondition?.());
+    const skills = this._readSkills(game.getGameSkills?.());
+    const timer = this._readTimer(game.getGameTimer?.(), { includeTickIndex: true });
+    const gameState = this._readGameState(game);
+    const level = game.level || null;
+    let groundMask = null;
+    let groundImage = null;
+    if (level?.groundMask?.mask && level?.groundImage) {
+      if (!this._groundDirty &&
+            this._lastKeyframe?.groundMask &&
+            this._lastKeyframe?.groundImage) {
+        groundMask = this._lastKeyframe.groundMask;
+        groundImage = this._lastKeyframe.groundImage;
+      } else {
+        groundMask = new Uint8Array(level.groundMask.mask);
+        groundImage = new Uint8ClampedArray(level.groundImage);
+      }
+    }
+    this._groundDirty = false;
+    return {
+      tickIndex,
+      lemmingState,
+      lemmingManagerState,
+      entranceOpened,
+      triggerState,
+      objectState,
+      minimapState,
+      victory,
+      skills,
+      timer,
+      gameState,
+      groundMask,
+      groundImage
+    };
+  },
+
+  _diffState(game, delta) {
+    const manager = game.getLemmingManager?.();
+    this._diffLemmings(manager, delta);
+    this._diffLemmingManager(manager, delta);
+    this._diffEntrances(game.level, delta);
+    this._diffScalarState(game, delta);
+  },
+
+  _captureLemmingState(manager) {
+    if (!manager) return;
+    const lems = manager.lemmings || [];
+    this._lemmingState = ensureLemmingCapacity(this._lemmingState, lems.length);
+    for (let i = 0; i < lems.length; i++) {
+      const lem = lems[i];
+      if (!lem) {
+        this._lemmingState.present[i] = 0;
+        continue;
+      }
+      const actionType = this._getActionType(manager, lem.action);
+      const countdownActive = !!lem.countdownAction;
+      this._writeLemmingState(this._lemmingState, i, lem, actionType, countdownActive);
+    }
+  },
+
+  _diffLemmings(manager, delta) {
+    if (!manager) return;
+    const lems = manager.lemmings || [];
+    this._lemmingState = ensureLemmingCapacity(this._lemmingState, lems.length);
+    const prev = this._lemmingState;
+    for (let i = 0; i < lems.length; i++) {
+      const lem = lems[i];
+      if (!lem) {
+        if (prev.present[i]) {
+          const snap = {
+            id: i,
+            x: prev.x[i],
+            y: prev.y[i],
+            lookRight: prev.lookRight[i],
+            frameIndex: prev.frameIndex[i],
+            state: prev.state[i],
+            canClimb: prev.canClimb[i],
+            hasParachute: prev.hasParachute[i],
+            removed: prev.removed[i],
+            disabled: prev.disabled[i],
+            countdown: prev.countdown[i],
+            hasExploded: prev.hasExploded[i],
+            lastTriggerType: prev.lastTriggerType[i],
+            actionType: prev.actionType[i],
+            countdownActive: prev.countdownActive[i]
+          };
+          delta.lemRemoved.push(snap);
+          prev.present[i] = 0;
+        }
+        continue;
+      }
+
+      const actionType = this._getActionType(manager, lem.action);
+      const countdownActive = !!lem.countdownAction;
+      const lookRight = lem.lookRight ? 1 : 0;
+      const state = lem.state ?? 0;
+      const canClimb = lem.canClimb ? 1 : 0;
+      const hasParachute = lem.hasParachute ? 1 : 0;
+      const removed = lem.removed ? 1 : 0;
+      const disabled = lem.disabled ? 1 : 0;
+      const countdown = lem.countdown ?? 0;
+      const hasExploded = lem.hasExploded ? 1 : 0;
+      const lastTriggerType = Number.isFinite(lem.lastTriggerType) ? lem.lastTriggerType : -1;
+      const countdownActiveValue = countdownActive ? 1 : 0;
+      if (!prev.present[i]) {
+        delta.lemAdded.push(snapshotLemming(lem, actionType, countdownActive));
+        this._writeLemmingState(prev, i, lem, actionType, countdownActive);
+        continue;
+      }
+
+      if (
+        prev.x[i] === lem.x &&
+          prev.y[i] === lem.y &&
+          prev.lookRight[i] === lookRight &&
+          prev.frameIndex[i] === lem.frameIndex &&
+          prev.state[i] === state &&
+          prev.canClimb[i] === canClimb &&
+          prev.hasParachute[i] === hasParachute &&
+          prev.removed[i] === removed &&
+          prev.disabled[i] === disabled &&
+          prev.countdown[i] === countdown &&
+          prev.hasExploded[i] === hasExploded &&
+          prev.lastTriggerType[i] === lastTriggerType &&
+          prev.actionType[i] === actionType &&
+          prev.countdownActive[i] === countdownActiveValue
+      ) {
+        prev.present[i] = 1;
+        continue;
+      }
+
+      this._diffLemmingField(delta, i, 0, prev.x[i], lem.x, prev.x);
+      this._diffLemmingField(delta, i, 1, prev.y[i], lem.y, prev.y);
+      this._diffLemmingField(delta, i, 2, prev.lookRight[i], lookRight, prev.lookRight);
+      this._diffLemmingField(delta, i, 3, prev.frameIndex[i], lem.frameIndex, prev.frameIndex);
+      this._diffLemmingField(delta, i, 4, prev.state[i], state, prev.state);
+      this._diffLemmingField(delta, i, 5, prev.canClimb[i], canClimb, prev.canClimb);
+      this._diffLemmingField(delta, i, 6, prev.hasParachute[i], hasParachute, prev.hasParachute);
+      this._diffLemmingField(delta, i, 7, prev.removed[i], removed, prev.removed);
+      this._diffLemmingField(delta, i, 8, prev.disabled[i], disabled, prev.disabled);
+      this._diffLemmingField(delta, i, 9, prev.countdown[i], countdown, prev.countdown);
+      this._diffLemmingField(delta, i, 10, prev.hasExploded[i], hasExploded, prev.hasExploded);
+      this._diffLemmingField(delta, i, 11, prev.lastTriggerType[i], lastTriggerType, prev.lastTriggerType);
+      this._diffLemmingField(delta, i, 12, prev.actionType[i], actionType, prev.actionType);
+      this._diffLemmingField(delta, i, 13, prev.countdownActive[i], countdownActiveValue, prev.countdownActive);
+      prev.present[i] = 1;
+    }
+
+    for (let i = lems.length; i < prev.present.length; i++) {
+      if (prev.present[i]) {
+        const snap = {
+          id: i,
+          x: prev.x[i],
+          y: prev.y[i],
+          lookRight: prev.lookRight[i],
+          frameIndex: prev.frameIndex[i],
+          state: prev.state[i],
+          canClimb: prev.canClimb[i],
+          hasParachute: prev.hasParachute[i],
+          removed: prev.removed[i],
+          disabled: prev.disabled[i],
+          countdown: prev.countdown[i],
+          hasExploded: prev.hasExploded[i],
+          lastTriggerType: prev.lastTriggerType[i],
+          actionType: prev.actionType[i],
+          countdownActive: prev.countdownActive[i]
+        };
+        delta.lemRemoved.push(snap);
+        prev.present[i] = 0;
+      }
+    }
+  },
+
+  _diffLemmingManager(manager, delta) {
+    const next = this._readLemmingManager(manager);
+    if (this._lemmingManagerState && next && !this._lemmingManagerEqual(this._lemmingManagerState, next)) {
+      delta.lemmingManagerChanges = { prev: this._lemmingManagerState, next };
+    }
+    this._lemmingManagerState = next;
+  },
+
+  _readLemmingManager(manager) {
+    if (!manager) return null;
+    const sourceTargets = manager._nukeTargets;
+    let targets = null;
+    if (Array.isArray(sourceTargets)) {
+      targets = new Array(sourceTargets.length);
+      for (let i = 0; i < sourceTargets.length; i += 1) {
+        targets[i] = sourceTargets[i]?.id ?? null;
+      }
+    }
+    return {
+      selectedIndex: manager.selectedIndex,
+      spawnTotal: manager.spawnTotal,
+      releaseTickIndex: manager.releaseTickIndex,
+      mmTickCounter: manager.mmTickCounter,
+      nextNukingLemmingsIndex: manager.nextNukingLemmingsIndex,
+      nukeTargets: targets
+    };
+  },
+
+  _lemmingManagerEqual(a, b) {
+    if (!a || !b) return false;
+    if (a.selectedIndex !== b.selectedIndex) return false;
+    if (a.spawnTotal !== b.spawnTotal) return false;
+    if (a.releaseTickIndex !== b.releaseTickIndex) return false;
+    if (a.mmTickCounter !== b.mmTickCounter) return false;
+    if (a.nextNukingLemmingsIndex !== b.nextNukingLemmingsIndex) return false;
+    const aa = a.nukeTargets || [];
+    const bb = b.nukeTargets || [];
+    if (aa.length !== bb.length) return false;
+    for (let i = 0; i < aa.length; i++) {
+      if (aa[i] !== bb[i]) return false;
+    }
+    return true;
+  },
+
+  _diffLemmingField(delta, id, field, prevValue, nextValue, store) {
+    if (prevValue === nextValue) return;
+    delta.lemChanges.ids.push(id);
+    delta.lemChanges.fields.push(field);
+    delta.lemChanges.prev.push(prevValue);
+    delta.lemChanges.next.push(nextValue);
+    store[id] = nextValue;
+  },
+
+  _writeLemmingState(state, index, lem, actionType, countdownActive) {
+    state.present[index] = 1;
+    state.x[index] = lem.x;
+    state.y[index] = lem.y;
+    state.lookRight[index] = lem.lookRight ? 1 : 0;
+    state.frameIndex[index] = lem.frameIndex;
+    state.state[index] = lem.state ?? 0;
+    state.canClimb[index] = lem.canClimb ? 1 : 0;
+    state.hasParachute[index] = lem.hasParachute ? 1 : 0;
+    state.removed[index] = lem.removed ? 1 : 0;
+    state.disabled[index] = lem.disabled ? 1 : 0;
+    state.countdown[index] = lem.countdown ?? 0;
+    state.hasExploded[index] = lem.hasExploded ? 1 : 0;
+    state.lastTriggerType[index] = Number.isFinite(lem.lastTriggerType) ? lem.lastTriggerType : -1;
+    state.actionType[index] = Number.isFinite(actionType) ? actionType : -1;
+    state.countdownActive[index] = countdownActive ? 1 : 0;
+  },
+
+  _getActionType(manager, action) {
+    if (!action || !manager) return -1;
+    if (manager.actionTypeByAction?.has(action)) {
+      return manager.actionTypeByAction.get(action);
+    }
+    const actions = manager.actions || [];
+    for (let i = 0; i < actions.length; i++) {
+      if (actions[i] === action) return i;
+    }
+    return -1;
+  },
+
+  _captureEntrances(level) {
+    const entrances = level?.entrances || [];
+    this._entranceOpened = new Uint8Array(entrances.length);
+    for (let i = 0; i < entrances.length; i++) {
+      this._entranceOpened[i] = entrances[i]?._opened ? 1 : 0;
+    }
+  },
+
+  _diffEntrances(level, delta) {
+    const entrances = level?.entrances || [];
+    if (this._entranceOpened.length !== entrances.length) {
+      this._captureEntrances(level);
+      return;
+    }
+    for (let i = 0; i < entrances.length; i++) {
+      const opened = entrances[i]?._opened ? 1 : 0;
+      if (this._entranceOpened[i] !== opened) {
+        delta.entranceChanges.indices.push(i);
+        delta.entranceChanges.prev.push(this._entranceOpened[i]);
+        delta.entranceChanges.next.push(opened);
+        this._entranceOpened[i] = opened;
+      }
+    }
+  },
+
+  _captureScalarState(game) {
+    this._skillsState = this._readSkills(game.getGameSkills?.(), this._skillsState);
+    this._victoryState = this._readVictory(game.getVictoryCondition?.());
+    this._timerState = this._readTimer(game.getGameTimer?.());
+    this._gameState = this._readGameState(game);
+  },
+
+  _diffScalarState(game, delta) {
+    const nextSkills = this._readSkills(game.getGameSkills?.(), this._skillsState);
+    if (this._skillsState && nextSkills && this._skillsState !== nextSkills) {
+      delta.skillsChanges = { prev: this._skillsState, next: nextSkills };
+    }
+    this._skillsState = nextSkills;
+
+    const nextVictory = this._readVictory(game.getVictoryCondition?.());
+    if (this._victoryState && nextVictory && !this._victoryEqual(this._victoryState, nextVictory)) {
+      delta.victoryChanges = { prev: this._victoryState, next: nextVictory };
+    }
+    this._victoryState = nextVictory;
+
+    const nextTimer = this._readTimer(game.getGameTimer?.());
+    if (this._timerState && nextTimer && !this._timerEqual(this._timerState, nextTimer)) {
+      delta.timerChanges = { prev: this._timerState, next: nextTimer };
+    }
+    this._timerState = nextTimer;
+
+    const nextGame = this._readGameState(game);
+    if (this._gameState && nextGame && !this._gameStateEqual(this._gameState, nextGame)) {
+      delta.gameChanges = { prev: this._gameState, next: nextGame };
+    }
+    this._gameState = nextGame;
+  },
+
+  _readSkills(skills, previous = null) {
+    if (!skills) return null;
+    const source = Array.isArray(skills.skills) ? skills.skills : [];
+    if (
+      previous &&
+        previous.selectedSkill === skills.selectedSkill &&
+        !!previous.cheatMode === !!skills.cheatMode
+    ) {
+      const prevValues = previous.skills || [];
+      if (prevValues.length === source.length) {
+        let same = true;
+        for (let i = 0; i < source.length; i += 1) {
+          if (prevValues[i] !== source[i]) {
+            same = false;
+            break;
+          }
+        }
+        if (same) return previous;
+      }
+    }
+    return {
+      selectedSkill: skills.selectedSkill,
+      cheatMode: !!skills.cheatMode,
+      skills: source.slice()
+    };
+  },
+
+  _skillsEqual(a, b) {
+    if (!a || !b) return false;
+    if (a.selectedSkill !== b.selectedSkill) return false;
+    if (!!a.cheatMode !== !!b.cheatMode) return false;
+    const aa = a.skills || [];
+    const bb = b.skills || [];
+    if (aa.length !== bb.length) return false;
+    for (let i = 0; i < aa.length; i++) {
+      if (aa[i] !== bb[i]) return false;
+    }
+    return true;
+  },
+
+  _readVictory(victory) {
+    if (!victory) return null;
+    return {
+      releaseRate: victory.releaseRate,
+      minReleaseRate: victory.minReleaseRate,
+      leftCount: victory.leftCount,
+      outCount: victory.outCount,
+      survivorCount: victory.survivorCount,
+      isFinalize: !!victory.isFinalize
+    };
+  },
+
+  _victoryEqual(a, b) {
+    if (!a || !b) return false;
+    return a.releaseRate === b.releaseRate
+        && a.minReleaseRate === b.minReleaseRate
+        && a.leftCount === b.leftCount
+        && a.outCount === b.outCount
+        && a.survivorCount === b.survivorCount
+        && !!a.isFinalize === !!b.isFinalize;
+  },
+
+  _readTimer(timer, { includeTickIndex = false } = {}) {
+    if (!timer) return null;
+    const state = {
+      speedFactor: timer.speedFactor,
+      frameTime: timer.frameTime
+    };
+    if (includeTickIndex) {
+      state.tickIndex = timer.tickIndex;
+    }
+    return state;
+  },
+
+  _timerEqual(a, b) {
+    if (!a || !b) return false;
+    return a.speedFactor === b.speedFactor
+        && a.frameTime === b.frameTime;
+  },
+
+  _readGameState(game) {
+    if (!game) return null;
+    return { finalGameState: game.finalGameState };
+  },
+
+  _gameStateEqual(a, b) {
+    if (!a || !b) return false;
+    return a.finalGameState === b.finalGameState;
+  },
+};
+
+export { historyStoreDiffMethods };
diff --git a/js/game/history/HistoryStoreLifecycleMethods.js b/js/game/history/HistoryStoreLifecycleMethods.js
new file mode 100644
index 00000000..d3995e4e
--- /dev/null
+++ b/js/game/history/HistoryStoreLifecycleMethods.js
@@ -0,0 +1,431 @@
+// @ts-check
+import { SkillTypes } from '../SkillTypes.js';
+import { Trigger } from '../../level/Trigger.js';
+import {
+  COLD_BLOCK_MAGIC,
+  COLD_BLOCK_VERSION,
+  COLD_DELTA_SENTINEL,
+  DEFAULT_OPTIONS,
+  DELTA_CODEC_VERSION,
+  DELTA_FLAG_ENTRANCE,
+  DELTA_FLAG_GROUND,
+  DELTA_FLAG_LEMMING_ADDS,
+  DELTA_FLAG_LEMMING_CHANGES,
+  DELTA_FLAG_LEMMING_MANAGER,
+  DELTA_FLAG_LEMMING_MUTATIONS,
+  DELTA_FLAG_LEMMING_REMOVALS,
+  DELTA_FLAG_MINIMAP_DEATHS,
+  DELTA_FLAG_OBJECTS,
+  DELTA_FLAG_SCALARS,
+  DELTA_FLAG_SOUND_EVENTS,
+  DELTA_FLAG_TRIGGERS,
+  NULL_INT32,
+  normalizeOptions,
+  toI32
+} from './HistoryShared.js';
+import {
+  BinaryReader,
+  BinaryWriter,
+  bytesEqual,
+  fnv1aHashBytes,
+  readTaggedValue,
+  rleDecodeBytes,
+  rleEncodeBytes,
+  writeTaggedValue
+} from './HistoryBinaryCodec.js';
+import {
+  applyLemmingSnapshot,
+  cloneLemmingState,
+  createLemmingState,
+  ensureLemmingCapacity,
+  snapshotLemming
+} from './HistoryLemmingState.js';
+import {
+  computeDeltaFlags,
+  createDelta,
+  ensureDeltaFlags,
+  isNoOpDelta,
+  packLemmingChanges,
+  packLemmingMutationList,
+  packTimerStateForStorage,
+  readPackedLemmingChanges,
+  readPackedLemmingMutation,
+  unpackLemmingChanges,
+  unpackLemmingMutationList,
+  unpackTimerStateFromStorage,
+  writePackedLemmingChanges,
+  writePackedLemmingMutation
+} from './HistoryDeltaCodec.js';
+import {
+  MIDI_FLAG_OWNER_KIND,
+  clonePlainObject,
+  createMidiFlagTriggerOwner
+} from './HistoryTriggerOwners.js';
+
+const historyStoreLifecycleMethods = {
+  _allocDelta(tickIndex) {
+    const tick = Math.trunc(tickIndex);
+    const delta = this._deltaPool.pop();
+    if (!delta) return createDelta(tick);
+    this._resetDelta(delta, tick);
+    return delta;
+  },
+
+  _resetDelta(delta, tickIndex) {
+    delta.tick = Math.trunc(tickIndex);
+    delta.flags = 0;
+    delta.lemChanges.ids.length = 0;
+    delta.lemChanges.fields.length = 0;
+    delta.lemChanges.prev.length = 0;
+    delta.lemChanges.next.length = 0;
+    delta.lemAdded.length = 0;
+    delta.lemRemoved.length = 0;
+    delta.lemmingManagerChanges = null;
+    delta.groundChanges.indices.length = 0;
+    delta.groundChanges.spans = null;
+    delta.groundChanges.prevMask.length = 0;
+    delta.groundChanges.prevR.length = 0;
+    delta.groundChanges.prevG.length = 0;
+    delta.groundChanges.prevB.length = 0;
+    delta.groundChanges.nextMask.length = 0;
+    delta.groundChanges.nextR.length = 0;
+    delta.groundChanges.nextG.length = 0;
+    delta.groundChanges.nextB.length = 0;
+    delta.entranceChanges.indices.length = 0;
+    delta.entranceChanges.prev.length = 0;
+    delta.entranceChanges.next.length = 0;
+    delta.triggerCooldownChanges.ids.length = 0;
+    delta.triggerCooldownChanges.prev.length = 0;
+    delta.triggerCooldownChanges.next.length = 0;
+    delta.triggerAdd.length = 0;
+    delta.triggerRemove.length = 0;
+    delta.objectAnimChanges.ids.length = 0;
+    delta.objectAnimChanges.prevFirst.length = 0;
+    delta.objectAnimChanges.prevFinished.length = 0;
+    delta.objectAnimChanges.nextFirst.length = 0;
+    delta.objectAnimChanges.nextFinished.length = 0;
+    delta.victoryChanges = null;
+    delta.skillsChanges = null;
+    delta.timerChanges = null;
+    delta.gameChanges = null;
+    delta.soundEvents.length = 0;
+    delta.minimapDeaths.length = 0;
+  },
+
+  _releaseDelta(delta) {
+    if (!delta || delta === COLD_DELTA_SENTINEL || typeof delta !== 'object') return;
+    const limit = this.options.deltaPoolLimit ?? DEFAULT_OPTIONS.deltaPoolLimit;
+    if (this._deltaPool.length >= limit) return;
+    this._resetDelta(delta, 0);
+    this._deltaPool.push(delta);
+  },
+
+  attach(game, { captureBaseline = true } = {}) {
+    if (!game) return;
+    this.game = game;
+    this.timer = game.getGameTimer?.() || null;
+    this._bindTimer();
+    if (captureBaseline) {
+      this.start();
+    }
+  },
+
+  detach() {
+    if (this.timer?.onBeforeGameTick && this._beforeTick) {
+      this.timer.onBeforeGameTick.off(this._beforeTick);
+    }
+    if (this.timer?.onGameTick && this._afterTick) {
+      this.timer.onGameTick.off(this._afterTick);
+    }
+    this._beforeTick = null;
+    this._afterTick = null;
+    this._recording = false;
+    this.game = null;
+    this.timer = null;
+  },
+
+  start() {
+    if (!this.game) return;
+    this.captureBaseline(this.game);
+    this._recording = true;
+    const tickIndex = this.timer?.tickIndex ?? 0;
+    if (!this.keyframes[tickIndex]) {
+      this._setKeyframe(tickIndex, this._captureKeyframe(this.game, tickIndex));
+    }
+  },
+
+  captureReplayBaseline(game = this.game) {
+    if (!game) return;
+    this.captureBaseline(game);
+    const tickIndex = game.getGameTimer?.()?.tickIndex ?? this.timer?.tickIndex ?? 0;
+    this._setKeyframe(tickIndex, this._captureKeyframe(game, tickIndex));
+  },
+
+  pause() {
+    this._recording = false;
+    this._currentDelta = null;
+    this._currentTick = null;
+  },
+
+  resume() {
+    if (!this.game) return;
+    this.captureBaseline(this.game);
+    this._groundDirty = true;
+    this._recording = true;
+  },
+
+  getKeyframeAtOrBefore(tickIndex) {
+    if (!Number.isFinite(tickIndex)) return null;
+    const ticks = this.keyframeTicks;
+    if (!ticks.length) return null;
+    const target = Math.max(0, Math.trunc(tickIndex));
+    if (target < ticks[0]) return null;
+    let lo = 0;
+    let hi = ticks.length - 1;
+    while (lo <= hi) {
+      const mid = (lo + hi) >> 1;
+      if (ticks[mid] <= target) {
+        lo = mid + 1;
+      } else {
+        hi = mid - 1;
+      }
+    }
+    const tick = ticks[Math.max(0, hi)];
+    return this.keyframes[tick] || null;
+  },
+
+  truncateAfter(tickIndex) {
+    if (!Number.isFinite(tickIndex)) return;
+    if (this.options.preserveFutureHistory) return;
+    const cutoff = Math.max(0, Math.trunc(tickIndex));
+    this._truncateDeltasAfter(cutoff);
+    this._truncateKeyframesAfter(cutoff);
+  },
+
+  _setDelta(tickIndex, delta) {
+    const tick = Math.trunc(tickIndex);
+    const block = this._ensureDeltaBlock(tick);
+    if (block.cold) {
+      this._thawDeltaBlock(block.startTick);
+    }
+    const prev = this.deltas[tick];
+    if (!prev) {
+      this.deltaCount += 1;
+    } else if (prev !== COLD_DELTA_SENTINEL) {
+      this._releaseDelta(prev);
+    }
+    this.deltas[tick] = delta;
+    if (this.minDeltaTick == null || tick < this.minDeltaTick) {
+      this.minDeltaTick = tick;
+    }
+    if (this.maxDeltaTick == null || tick > this.maxDeltaTick) {
+      this.maxDeltaTick = tick;
+    }
+  },
+
+  _setKeyframe(tickIndex, keyframe) {
+    const tick = Math.trunc(tickIndex);
+    if (!this.keyframes[tick]) {
+      this.keyframeCount += 1;
+      this._insertKeyframeTick(tick);
+    }
+    this.keyframes[tick] = keyframe;
+    this._lastKeyframe = keyframe;
+    if (this.minKeyframeTick == null || tick < this.minKeyframeTick) {
+      this.minKeyframeTick = tick;
+    }
+    if (this.maxKeyframeTick == null || tick > this.maxKeyframeTick) {
+      this.maxKeyframeTick = tick;
+    }
+  },
+
+  _insertKeyframeTick(tickIndex) {
+    const tick = Math.trunc(tickIndex);
+    const list = this.keyframeTicks;
+    const last = list[list.length - 1];
+    if (last == null || tick > last) {
+      list.push(tick);
+      return;
+    }
+    if (tick === last) return;
+    let lo = 0;
+    let hi = list.length - 1;
+    while (lo <= hi) {
+      const mid = (lo + hi) >> 1;
+      if (list[mid] < tick) {
+        lo = mid + 1;
+      } else {
+        hi = mid - 1;
+      }
+    }
+    if (list[lo] !== tick) list.splice(lo, 0, tick);
+  },
+
+  _truncateDeltasAfter(cutoff) {
+    if (this.maxDeltaTick == null) return;
+    const touchedBlocks = this._scratchTouchedBlocks;
+    touchedBlocks.clear();
+    for (let tick = this.maxDeltaTick; tick > cutoff; tick -= 1) {
+      const delta = this.deltas[tick];
+      if (!delta) continue;
+      const blockStart = this._deltaBlockStart(tick);
+      touchedBlocks.add(blockStart);
+      if (delta === COLD_DELTA_SENTINEL) {
+        this._thawDeltaBlock(blockStart);
+      }
+      const current = this.deltas[tick];
+      this.deltas[tick] = undefined;
+      this.deltaCount -= 1;
+      this._releaseDelta(current);
+    }
+    for (const blockStart of touchedBlocks) {
+      this._cleanupDeltaBlock(blockStart);
+    }
+    touchedBlocks.clear();
+    let nextMax = Math.min(this.maxDeltaTick, cutoff);
+    while (nextMax >= this.minDeltaTick && !this.deltas[nextMax]) {
+      nextMax -= 1;
+    }
+    if (nextMax < this.minDeltaTick) {
+      this.minDeltaTick = null;
+      this.maxDeltaTick = null;
+      this.deltaCount = 0;
+      return;
+    }
+    this.maxDeltaTick = nextMax;
+  },
+
+  _truncateKeyframesAfter(cutoff) {
+    if (this.maxKeyframeTick == null) return;
+    for (let tick = this.maxKeyframeTick; tick > cutoff; tick -= 1) {
+      if (!this.keyframes[tick]) continue;
+      this.keyframes[tick] = undefined;
+      this.keyframeCount -= 1;
+    }
+    while (this.keyframeTicks.length &&
+          this.keyframeTicks[this.keyframeTicks.length - 1] > cutoff) {
+      this.keyframeTicks.pop();
+    }
+    if (!this.keyframeTicks.length) {
+      this.minKeyframeTick = null;
+      this.maxKeyframeTick = null;
+      this._lastKeyframe = null;
+      return;
+    }
+    this.minKeyframeTick = this.keyframeTicks[0];
+    this.maxKeyframeTick = this.keyframeTicks[this.keyframeTicks.length - 1];
+    this._lastKeyframe = this.keyframes[this.maxKeyframeTick] || null;
+  },
+
+  _truncateBefore(cutoff) {
+    if (this.minDeltaTick == null || this.maxDeltaTick == null) return;
+    const start = Math.max(0, Math.trunc(cutoff));
+    const touchedBlocks = this._scratchTouchedBlocks;
+    touchedBlocks.clear();
+    for (let tick = this.minDeltaTick; tick < start; tick += 1) {
+      const delta = this.deltas[tick];
+      if (!delta) continue;
+      const blockStart = this._deltaBlockStart(tick);
+      touchedBlocks.add(blockStart);
+      if (delta === COLD_DELTA_SENTINEL) {
+        this._thawDeltaBlock(blockStart);
+      }
+      const current = this.deltas[tick];
+      this.deltas[tick] = undefined;
+      this.deltaCount -= 1;
+      this._releaseDelta(current);
+    }
+    for (const blockStart of touchedBlocks) {
+      this._cleanupDeltaBlock(blockStart);
+    }
+    touchedBlocks.clear();
+    let nextMin = Math.max(this.minDeltaTick, start);
+    while (nextMin <= this.maxDeltaTick && !this.deltas[nextMin]) {
+      nextMin += 1;
+    }
+    if (nextMin > this.maxDeltaTick) {
+      this.minDeltaTick = null;
+      this.maxDeltaTick = null;
+      this.deltaCount = 0;
+    } else {
+      this.minDeltaTick = nextMin;
+    }
+
+    if (!this.keyframeTicks.length) return;
+    const keyframeTicks = this.keyframeTicks;
+    let removeCount = 0;
+    const total = keyframeTicks.length;
+    while (removeCount < total && keyframeTicks[removeCount] < start) {
+      const tick = keyframeTicks[removeCount];
+      if (this.keyframes[tick]) {
+        this.keyframes[tick] = undefined;
+        this.keyframeCount -= 1;
+      }
+      removeCount += 1;
+    }
+    if (removeCount > 0) {
+      keyframeTicks.splice(0, removeCount);
+    }
+    if (!keyframeTicks.length) {
+      this.minKeyframeTick = null;
+      this.maxKeyframeTick = null;
+      this._lastKeyframe = null;
+      return;
+    }
+    this.minKeyframeTick = keyframeTicks[0];
+    this.maxKeyframeTick = keyframeTicks[keyframeTicks.length - 1];
+    this._lastKeyframe = this.keyframes[this.maxKeyframeTick] || null;
+  },
+
+  _compressGroundChanges(changes) {
+    const indices = changes?.indices;
+    if (!indices || indices.length < 2) return;
+    const starts = [];
+    const lengths = [];
+    let runStart = indices[0];
+    let runLength = 1;
+    for (let i = 1; i < indices.length; i++) {
+      const idx = indices[i];
+      if (idx === indices[i - 1] + 1) {
+        runLength += 1;
+      } else {
+        starts.push(runStart);
+        lengths.push(runLength);
+        runStart = idx;
+        runLength = 1;
+      }
+    }
+    starts.push(runStart);
+    lengths.push(runLength);
+    changes.spans = { starts, lengths };
+    indices.length = 0;
+  },
+
+  _maybeWarnHistory() {
+    const warn = this.options.historyWarnTicks;
+    if (!warn || warn <= 0 || this._historyWarned) return;
+    if (this.minDeltaTick == null || this.maxDeltaTick == null) return;
+    const span = this.maxDeltaTick - this.minDeltaTick + 1;
+    if (span < warn) return;
+    this._historyWarned = true;
+    console.warn(`HistoryStore: ${span} ticks retained (warn threshold ${warn}).`);
+  },
+
+  _enforceHistoryCap() {
+    if (!this.options.enableHistoryCap) return;
+    const cap = this.options.historyCapTicks ?? 0;
+    if (!Number.isFinite(cap) || cap <= 0) return;
+    if (this.minDeltaTick == null || this.maxDeltaTick == null) return;
+    const span = this.maxDeltaTick - this.minDeltaTick + 1;
+    if (span <= cap) return;
+    let cutoff = this.maxDeltaTick - cap + 1;
+    const frame = this.getKeyframeAtOrBefore(cutoff);
+    if (frame?.tickIndex != null) {
+      cutoff = Math.min(cutoff, frame.tickIndex);
+    }
+    if (cutoff <= this.minDeltaTick) return;
+    this._truncateBefore(cutoff);
+  },
+};
+
+export { historyStoreLifecycleMethods };
diff --git a/js/game/history/HistoryStoreRecordingMethods.js b/js/game/history/HistoryStoreRecordingMethods.js
new file mode 100644
index 00000000..9ed905f9
--- /dev/null
+++ b/js/game/history/HistoryStoreRecordingMethods.js
@@ -0,0 +1,264 @@
+// @ts-check
+import { SkillTypes } from '../SkillTypes.js';
+import { Trigger } from '../../level/Trigger.js';
+import {
+  COLD_BLOCK_MAGIC,
+  COLD_BLOCK_VERSION,
+  COLD_DELTA_SENTINEL,
+  DEFAULT_OPTIONS,
+  DELTA_CODEC_VERSION,
+  DELTA_FLAG_ENTRANCE,
+  DELTA_FLAG_GROUND,
+  DELTA_FLAG_LEMMING_ADDS,
+  DELTA_FLAG_LEMMING_CHANGES,
+  DELTA_FLAG_LEMMING_MANAGER,
+  DELTA_FLAG_LEMMING_MUTATIONS,
+  DELTA_FLAG_LEMMING_REMOVALS,
+  DELTA_FLAG_MINIMAP_DEATHS,
+  DELTA_FLAG_OBJECTS,
+  DELTA_FLAG_SCALARS,
+  DELTA_FLAG_SOUND_EVENTS,
+  DELTA_FLAG_TRIGGERS,
+  NULL_INT32,
+  normalizeOptions,
+  toI32
+} from './HistoryShared.js';
+import {
+  BinaryReader,
+  BinaryWriter,
+  bytesEqual,
+  fnv1aHashBytes,
+  readTaggedValue,
+  rleDecodeBytes,
+  rleEncodeBytes,
+  writeTaggedValue
+} from './HistoryBinaryCodec.js';
+import {
+  applyLemmingSnapshot,
+  cloneLemmingState,
+  createLemmingState,
+  ensureLemmingCapacity,
+  snapshotLemming
+} from './HistoryLemmingState.js';
+import {
+  computeDeltaFlags,
+  createDelta,
+  ensureDeltaFlags,
+  isNoOpDelta,
+  packLemmingChanges,
+  packLemmingMutationList,
+  packTimerStateForStorage,
+  readPackedLemmingChanges,
+  readPackedLemmingMutation,
+  unpackLemmingChanges,
+  unpackLemmingMutationList,
+  unpackTimerStateFromStorage,
+  writePackedLemmingChanges,
+  writePackedLemmingMutation
+} from './HistoryDeltaCodec.js';
+import {
+  MIDI_FLAG_OWNER_KIND,
+  clonePlainObject,
+  createMidiFlagTriggerOwner
+} from './HistoryTriggerOwners.js';
+
+const historyStoreRecordingMethods = {
+  _bindTimer() {
+    if (!this.timer) return;
+    this._beforeTick = (tick) => this.beginTick(tick);
+    this._afterTick = () => this.endTick();
+    this.timer.onBeforeGameTick?.on(this._beforeTick);
+    this.timer.onGameTick?.on(this._afterTick);
+  },
+
+  beginTick(tick) {
+    if (!this._recording) return;
+    this._currentTick = tick;
+    this._currentDelta = this._allocDelta(tick);
+  },
+
+  endTick() {
+    if (!this._recording || !this.game || !this._currentDelta) return;
+    const tick = this._currentTick;
+    const tickIndex = this.timer?.tickIndex ?? (tick + 1);
+    this._diffState(this.game, this._currentDelta);
+    this._compressGroundChanges(this._currentDelta.groundChanges);
+    this._currentDelta.flags = computeDeltaFlags(this._currentDelta);
+    this._setDelta(tick, this._currentDelta);
+    if ((tickIndex % this.options.keyframeInterval) === 0) {
+      this._setKeyframe(tickIndex, this._captureKeyframe(this.game, tickIndex));
+    }
+    this._maybeWarnHistory();
+    this._enforceHistoryCap();
+    this._maybeCompactDeltaBlocks();
+    this._currentDelta = null;
+  },
+
+  captureBaseline(game) {
+    if (!game) return;
+    this._captureScalarState(game);
+    const manager = game.getLemmingManager?.();
+    this._captureLemmingState(manager);
+    this._lemmingManagerState = this._readLemmingManager(manager);
+    this._captureEntrances(game.level);
+  },
+
+  recordSoundEvent(event) {
+    if (!this._currentDelta) return;
+    this._currentDelta.soundEvents.push(event);
+  },
+
+  recordGroundChange(index, prevMask, prevR, prevG, prevB, nextMask, nextR, nextG, nextB) {
+    if (!this._currentDelta) return;
+    this._groundDirty = true;
+    const changes = this._currentDelta.groundChanges;
+    changes.indices.push(index);
+    changes.prevMask.push(prevMask);
+    changes.prevR.push(prevR);
+    changes.prevG.push(prevG);
+    changes.prevB.push(prevB);
+    changes.nextMask.push(nextMask);
+    changes.nextR.push(nextR);
+    changes.nextG.push(nextG);
+    changes.nextB.push(nextB);
+  },
+
+  recordEntranceChange(index, prev, next) {
+    if (!this._currentDelta) return;
+    const changes = this._currentDelta.entranceChanges;
+    changes.indices.push(index);
+    changes.prev.push(prev ? 1 : 0);
+    changes.next.push(next ? 1 : 0);
+  },
+
+  recordTriggerCooldown(trigger, prev, next) {
+    if (!this._currentDelta) return;
+    const id = this._ensureTriggerId(trigger);
+    const changes = this._currentDelta.triggerCooldownChanges;
+    changes.ids.push(id);
+    changes.prev.push(prev);
+    changes.next.push(next);
+  },
+
+  recordTriggerAdd(trigger, snapshot) {
+    if (!this._currentDelta) return;
+    const id = this._ensureTriggerId(trigger);
+    this._currentDelta.triggerAdd.push({
+      id,
+      ...snapshot,
+      ...this._readTriggerOwnerSnapshot(trigger)
+    });
+  },
+
+  recordTriggerRemove(trigger, snapshot) {
+    if (!this._currentDelta) return;
+    const id = this._ensureTriggerId(trigger);
+    this._currentDelta.triggerRemove.push({
+      id,
+      ...snapshot,
+      ...this._readTriggerOwnerSnapshot(trigger)
+    });
+  },
+
+  _readTriggerOwnerSnapshot(trigger) {
+    const owner = trigger?.owner ?? null;
+    if (!owner) {
+      return { ownerKind: null, ownerId: null, ownerRef: null, ownerData: null };
+    }
+    if (Number.isFinite(owner.id)) {
+      return {
+        ownerKind: 'lemming',
+        ownerId: owner.id,
+        ownerRef: { id: owner.id },
+        ownerData: null
+      };
+    }
+    const ownerKind = owner.__historyKind || owner.historyKind || null;
+    if (ownerKind) {
+      const ownerData = typeof owner.getHistoryData === 'function'
+        ? owner.getHistoryData(trigger)
+        : (clonePlainObject(owner.__historyData) || clonePlainObject(owner.historyData));
+      return {
+        ownerKind,
+        ownerId: owner.id ?? null,
+        ownerRef: owner.id != null ? { id: owner.id } : null,
+        ownerData
+      };
+    }
+    return { ownerKind: null, ownerId: owner.id ?? null, ownerRef: null, ownerData: null };
+  },
+
+  _resolveTriggerOwner(game, snap) {
+    const ownerKind = snap?.ownerKind || (Number.isFinite(snap?.ownerId) ? 'lemming' : null);
+    if (ownerKind === 'lemming') {
+      const id = Number.isFinite(snap?.ownerRef?.id) ? snap.ownerRef.id : snap?.ownerId;
+      return Number.isFinite(id)
+        ? game.getLemmingManager?.()?.getLemming?.(id) ?? null
+        : null;
+    }
+    if (ownerKind === MIDI_FLAG_OWNER_KIND) {
+      return createMidiFlagTriggerOwner(game, snap);
+    }
+    if (ownerKind) {
+      return { id: snap?.ownerId ?? snap?.ownerRef?.id ?? null };
+    }
+    return null;
+  },
+
+  _isReplayManagedDynamicTrigger(trigger) {
+    if (!trigger) return false;
+    const ownerSnapshot = this._readTriggerOwnerSnapshot(trigger);
+    return ownerSnapshot.ownerKind != null;
+  },
+
+  _removeTriggerInstance(triggerManager, trigger) {
+    if (!triggerManager || !trigger) return;
+    if (typeof triggerManager.remove === 'function') {
+      triggerManager.remove(trigger);
+      return;
+    }
+    if (trigger.owner && typeof triggerManager.removeByOwner === 'function') {
+      triggerManager.removeByOwner(trigger.owner);
+      return;
+    }
+    triggerManager._triggers?.delete?.(trigger);
+  },
+
+  recordObjectAnimation(obj, prev, next) {
+    if (!this._currentDelta) return;
+    const id = this._ensureObjectId(obj);
+    const changes = this._currentDelta.objectAnimChanges;
+    changes.ids.push(id);
+    changes.prevFirst.push(prev.firstFrameIndex);
+    changes.prevFinished.push(prev.isFinished ? 1 : 0);
+    changes.nextFirst.push(next.firstFrameIndex);
+    changes.nextFinished.push(next.isFinished ? 1 : 0);
+  },
+
+  recordMinimapDeath(entry) {
+    if (!this._currentDelta) return;
+    this._currentDelta.minimapDeaths.push(entry);
+  },
+
+  _ensureTriggerId(trigger) {
+    if (!trigger) return 0;
+    if (trigger.__historyId) return trigger.__historyId;
+    const id = this._nextTriggerId++;
+    trigger.__historyId = id;
+    this._triggerIds.set(trigger, id);
+    this._triggerById.set(id, trigger);
+    return id;
+  },
+
+  _ensureObjectId(obj) {
+    if (!obj) return 0;
+    if (obj.__historyId) return obj.__historyId;
+    const id = this._nextObjectId++;
+    obj.__historyId = id;
+    this._objectIds.set(obj, id);
+    this._objectById.set(id, obj);
+    return id;
+  },
+};
+
+export { historyStoreRecordingMethods };
diff --git a/js/game/history/HistoryStoreStatsMethods.js b/js/game/history/HistoryStoreStatsMethods.js
new file mode 100644
index 00000000..b118b3f9
--- /dev/null
+++ b/js/game/history/HistoryStoreStatsMethods.js
@@ -0,0 +1,157 @@
+// @ts-check
+import { SkillTypes } from '../SkillTypes.js';
+import { Trigger } from '../../level/Trigger.js';
+import {
+  COLD_BLOCK_MAGIC,
+  COLD_BLOCK_VERSION,
+  COLD_DELTA_SENTINEL,
+  DEFAULT_OPTIONS,
+  DELTA_CODEC_VERSION,
+  DELTA_FLAG_ENTRANCE,
+  DELTA_FLAG_GROUND,
+  DELTA_FLAG_LEMMING_ADDS,
+  DELTA_FLAG_LEMMING_CHANGES,
+  DELTA_FLAG_LEMMING_MANAGER,
+  DELTA_FLAG_LEMMING_MUTATIONS,
+  DELTA_FLAG_LEMMING_REMOVALS,
+  DELTA_FLAG_MINIMAP_DEATHS,
+  DELTA_FLAG_OBJECTS,
+  DELTA_FLAG_SCALARS,
+  DELTA_FLAG_SOUND_EVENTS,
+  DELTA_FLAG_TRIGGERS,
+  NULL_INT32,
+  normalizeOptions,
+  toI32
+} from './HistoryShared.js';
+import {
+  BinaryReader,
+  BinaryWriter,
+  bytesEqual,
+  fnv1aHashBytes,
+  readTaggedValue,
+  rleDecodeBytes,
+  rleEncodeBytes,
+  writeTaggedValue
+} from './HistoryBinaryCodec.js';
+import {
+  applyLemmingSnapshot,
+  cloneLemmingState,
+  createLemmingState,
+  ensureLemmingCapacity,
+  snapshotLemming
+} from './HistoryLemmingState.js';
+import {
+  computeDeltaFlags,
+  createDelta,
+  ensureDeltaFlags,
+  isNoOpDelta,
+  packLemmingChanges,
+  packLemmingMutationList,
+  packTimerStateForStorage,
+  readPackedLemmingChanges,
+  readPackedLemmingMutation,
+  unpackLemmingChanges,
+  unpackLemmingMutationList,
+  unpackTimerStateFromStorage,
+  writePackedLemmingChanges,
+  writePackedLemmingMutation
+} from './HistoryDeltaCodec.js';
+import {
+  MIDI_FLAG_OWNER_KIND,
+  clonePlainObject,
+  createMidiFlagTriggerOwner
+} from './HistoryTriggerOwners.js';
+
+const historyStoreStatsMethods = {
+  setPreserveFutureHistory(enabled) {
+    this.options.preserveFutureHistory = !!enabled;
+  },
+
+  configureRetention(policy = {}) {
+    this.options = normalizeOptions({ ...this.options, ...policy });
+    this._coldCompactionCursor = null;
+    this._historyWarned = false;
+    return this.getRetentionPolicy();
+  },
+
+  getRetentionPolicy() {
+    return {
+      preserveFutureHistory: !!this.options.preserveFutureHistory,
+      enableHistoryCap: !!this.options.enableHistoryCap,
+      historyCapTicks: this.options.historyCapTicks ?? 0,
+      historyWarnTicks: this.options.historyWarnTicks ?? 0
+    };
+  },
+
+  getDelta(tickIndex) {
+    if (!Number.isFinite(tickIndex)) return null;
+    const tick = Math.trunc(tickIndex);
+    const entry = this.deltas[tick];
+    if (!entry) return null;
+    if (entry === COLD_DELTA_SENTINEL) {
+      return this._resolveColdDelta(tick);
+    }
+    return entry;
+  },
+
+  getKeyframe(tickIndex) {
+    if (!Number.isFinite(tickIndex)) return null;
+    return this.keyframes[Math.trunc(tickIndex)] || null;
+  },
+
+  getHistoryStats() {
+    const min = this.minDeltaTick;
+    const max = this.maxDeltaTick;
+    const span = (min == null || max == null) ? 0 : (max - min + 1);
+    return {
+      minTick: min,
+      maxTick: max,
+      deltaCount: this.deltaCount,
+      keyframeCount: this.keyframeCount,
+      spanTicks: span,
+      coldBlockCount: this._coldBlockCount,
+      coldBlockBytes: this._coldBlockBytes,
+      retention: this.getRetentionPolicy()
+    };
+  },
+
+  computeReplayHash(fromTick = null, toTick = null) {
+    if (this.minDeltaTick == null || this.maxDeltaTick == null) return null;
+    const start = Number.isFinite(fromTick) ? Math.max(this.minDeltaTick, Math.trunc(fromTick)) : this.minDeltaTick;
+    const end = Number.isFinite(toTick) ? Math.min(this.maxDeltaTick, Math.trunc(toTick)) : this.maxDeltaTick;
+    if (start > end) return null;
+    let hash = 2166136261;
+    const pushByte = (value) => {
+      hash ^= value & 0xff;
+      hash = Math.imul(hash, 16777619);
+    };
+    const pushAscii = (value) => {
+      const text = String(value);
+      for (let i = 0; i < text.length; i += 1) {
+        pushByte(text.charCodeAt(i));
+      }
+      pushByte(124); // '|'
+    };
+    for (let tick = start; tick <= end; tick += 1) {
+      const delta = this.getDelta(tick);
+      if (!delta) continue;
+      pushAscii(tick);
+      pushAscii(isNoOpDelta(delta) ? 1 : 0);
+      pushAscii(delta.lemChanges?.ids?.length || 0);
+      pushAscii(delta.lemAdded?.length || 0);
+      pushAscii(delta.lemRemoved?.length || 0);
+      pushAscii(delta.groundChanges?.indices?.length || 0);
+      pushAscii(delta.entranceChanges?.indices?.length || 0);
+      pushAscii(delta.triggerCooldownChanges?.ids?.length || 0);
+      pushAscii(delta.triggerAdd?.length || 0);
+      pushAscii(delta.triggerRemove?.length || 0);
+      pushAscii(delta.objectAnimChanges?.ids?.length || 0);
+      pushAscii(delta.soundEvents?.length || 0);
+      pushAscii(delta.minimapDeaths?.length || 0);
+      pushByte(10); // '\n'
+    }
+    return (hash >>> 0).toString(16).padStart(8, '0');
+  },
+};
+
+export { historyStoreStatsMethods };
diff --git a/js/game/history/HistoryTriggerOwners.js b/js/game/history/HistoryTriggerOwners.js
new file mode 100644
index 00000000..084d2de8
--- /dev/null
+++ b/js/game/history/HistoryTriggerOwners.js
@@ -0,0 +1,41 @@
+// @ts-check
+import { SoundEventTypes, SoundEffectIds } from '../SoundEvents.js';
+
+const MIDI_FLAG_OWNER_KIND = 'midi_flag';
+
+const clonePlainObject = (value) => {
+  if (!value || typeof value !== 'object') return null;
+  return { ...value };
+};
+
+const createMidiFlagTriggerOwner = (game, snap = {}) => {
+  const data = clonePlainObject(snap.ownerData) || {};
+  const midiFlagId = data.midiFlagId ?? null;
+  const triggerType = data.triggerType ?? snap.triggerType ?? null;
+  const pieceId = data.pieceId ?? null;
+  return {
+    id: snap.ownerId ?? data.ownerId ?? `midi_flag_${midiFlagId ?? 'unknown'}`,
+    __historyKind: MIDI_FLAG_OWNER_KIND,
+    __historyData: { midiFlagId, triggerType, pieceId },
+    onTrigger: (_tick, lemming, trigger, x, y) => {
+      game?.soundEvents?.emit?.({
+        type: SoundEventTypes.TRAP_TRIGGER,
+        sfxId: SoundEffectIds.NONE,
+        triggerType,
+        midiFlagId,
+        pieceId,
+        x,
+        y,
+        lemmingId: lemming?.id ?? null,
+        triggerBounds: {
+          x1: trigger?.x1 ?? snap.x1,
+          y1: trigger?.y1 ?? snap.y1,
+          x2: trigger?.x2 ?? snap.x2,
+          y2: trigger?.y2 ?? snap.y2
+        }
+      });
+    }
+  };
+};
+
+export { MIDI_FLAG_OWNER_KIND, clonePlainObject, createMidiFlagTriggerOwner };
diff --git a/js/input/EditorKeybindings.js b/js/input/EditorKeybindings.js
index 3f632bb0..c3accf67 100644
--- a/js/input/EditorKeybindings.js
+++ b/js/input/EditorKeybindings.js
@@ -1,7 +1,34 @@
 import { KeybindingRegistry, parseKeybindingConfig } from './KeybindingRegistry.js';
 import { formatBindingSpec } from './KeybindingFormatter.js';
+import { GamepadInputController } from './GamepadInputController.js';
 import { EditorTools } from '../editor/EditorTools.js';
+import { getRuntimeDependency } from '../core/dependencies.js';
 
+/**
+ * Keyboard and gamepad shortcut bridge for editor actions.
+ *
+ * @param {object} controller
+ * @param {{
+ *   fileProvider?: {loadString?: (path: string) => Promise<string>} | null,
+ *   onToolChange?: (tool: number) => void,
+ *   onCopy?: () => void,
+ *   onPaste?: () => void,
+ *   onDuplicate?: () => void,
+ *   onNudge?: (dx: number, dy: number, distance: number) => void,
+ *   onSnap?: () => void,
+ *   onUndo?: () => void,
+ *   onRedo?: () => void,
+ *   onDelete?: () => void,
+ *   onBringToFront?: () => void,
+ *   onSendToBack?: () => void,
+ *   onMoveForward?: () => void,
+ *   onMoveBackward?: () => void,
+ *   onPlaytestToggle?: () => void,
+ *   onToggleShortcutOverlay?: () => void,
+ *   onPreview?: () => void,
+ *   onBindingsLoaded?: () => void
+ * }} [options]
+ */
 class EditorKeybindings {
   constructor(controller, options = {}) {
     this.controller = controller;
@@ -22,18 +49,38 @@ class EditorKeybindings {
     this._onToggleShortcutOverlay = options.onToggleShortcutOverlay || null;
     this._onPreview = options.onPreview || null;
     this._onBindingsLoaded = options.onBindingsLoaded || null;
+    this.window = options.window || getRuntimeDependency('window', null);
+    this.performance = options.performance || getRuntimeDependency('performance', null);
+    this.requestAnimationFrame = options.requestAnimationFrame ||
+      this.window?.requestAnimationFrame?.bind?.(this.window) ||
+      null;
+    this.cancelAnimationFrame = options.cancelAnimationFrame ||
+      this.window?.cancelAnimationFrame?.bind?.(this.window) ||
+      null;
     this._down = this._onKeyDown.bind(this);
     this.keybindings = new KeybindingRegistry();
     this._actions = this._createActionHandlers();
+    this.gamepad = new GamepadInputController({
+      mode: 'editor',
+      fileProvider: options.fileProvider || null,
+      window: this.window,
+      navigator: options.navigator ?? this.window?.navigator ?? getRuntimeDependency('navigator', null),
+      storage: options.storage ?? this.window?.localStorage ?? getRuntimeDependency('localStorage', null),
+      onAction: (action, type) => {
+        this._handleAction(action, type);
+      }
+    });
     this._loadKeybindings(options.fileProvider || null);
   }
 
   bind() {
-    window.addEventListener('keydown', this._down);
+    this.window?.addEventListener?.('keydown', this._down);
   }
 
   dispose() {
-    window.removeEventListener('keydown', this._down);
+    this.window?.removeEventListener?.('keydown', this._down);
+    this.gamepad?.dispose?.();
+    this.gamepad = null;
   }
 
   _loadKeybindings(fileProvider) {
@@ -67,12 +114,21 @@ class EditorKeybindings {
     return specs.map(spec => formatBindingSpec(spec)).filter(Boolean);
   }
 
+  getGamepadDisplayBindings(action) {
+    return this.gamepad?.getDisplayBindings(action) || [];
+  }
+
+  setGamepadBindings(config, options) {
+    this.gamepad?.setConfig?.(config, options);
+  }
+
   _createActionHandlers() {
     return {
       editorToolSelect: { down: () => this._setTool(EditorTools.SELECT) },
       editorToolTerrain: { down: () => this._setTool(EditorTools.TERRAIN) },
       editorToolGadget: { down: () => this._setTool(EditorTools.GADGET) },
       editorToolTrigger: { down: () => this._setTool(EditorTools.TRIGGER) },
+      editorToolMidiFlag: { down: () => this._setTool(EditorTools.MIDI_FLAG) },
       editorToolEntrance: { down: () => this._setTool(EditorTools.ENTRANCE) },
       editorToolExit: { down: () => this._setTool(EditorTools.EXIT) },
       editorToolSteel: { down: () => this._setTool(EditorTools.STEEL) },
@@ -144,10 +200,11 @@ class EditorKeybindings {
     };
   }
 
-  _handleAction(action) {
+  _handleAction(action, type = 'down') {
     const handler = this._actions[action];
-    if (!handler?.down) return false;
-    handler.down();
+    const fn = type === 'up' ? handler?.up : handler?.down;
+    if (!fn) return false;
+    fn();
     this._onPreview?.();
     return true;
   }
diff --git a/js/input/GamepadInputController.js b/js/input/GamepadInputController.js
new file mode 100644
index 00000000..40fd79b6
--- /dev/null
+++ b/js/input/GamepadInputController.js
@@ -0,0 +1,11 @@
+export { GamepadInputController } from './gamepad/GamepadInputControllerCore.js';
+export {
+  DEFAULT_GAMEPAD_BINDINGS,
+  GamepadBindingRegistry,
+  formatGamepadBindingSpec,
+  mergeGamepadConfigLayers,
+  mergeGamepadConfig,
+  parseBindingSpec,
+  compactGamepadOverrideConfig,
+  parseGamepadBindingConfig
+} from './gamepad/GamepadInputControllerShared.js';
diff --git a/js/input/KeyboardShortcuts.js b/js/input/KeyboardShortcuts.js
index 8c2dc3e2..2e95dbfb 100644
--- a/js/input/KeyboardShortcuts.js
+++ b/js/input/KeyboardShortcuts.js
@@ -1,484 +1 @@
-import { CommandLemmingsAction } from '../commands/CommandLemmingsAction.js';
-import { CommandNuke } from '../commands/CommandNuke.js';
-import { CommandReleaseRateDecrease } from '../commands/CommandReleaseRateDecrease.js';
-import { CommandReleaseRateIncrease } from '../commands/CommandReleaseRateIncrease.js';
-import { CommandSelectSkill } from '../commands/CommandSelectSkill.js';
-import { GameVictoryCondition } from '../game/GameVictoryCondition.js';
-import { LemmingStateType } from '../lemmings/LemmingStateType.js';
-import { SkillTypes } from '../game/SkillTypes.js';
-import { KeybindingRegistry, parseKeybindingConfig } from './KeybindingRegistry.js';
-import { formatBindingSpec } from './KeybindingFormatter.js';
-
-class KeyboardShortcuts {
-  constructor(view) {
-    this.view = view;
-    this._down = this._onKeyDown.bind(this);
-    this._up = this._onKeyUp.bind(this);
-    window.addEventListener('keydown', this._down);
-    window.addEventListener('keyup', this._up);
-    this.mod = { shift:false };
-    this.pan = { left:false,right:false,up:false,down:false,vx:0,vy:0,changed:false };
-    this.zoom = { dir:0,v:0,reset:null };
-    this.keybindings = new KeybindingRegistry();
-    this._actions = this._createActionHandlers();
-    this._raf = null;
-    this._last = 0;
-    this._loadKeybindings();
-  }
-
-  dispose() {
-    if (this._raf) {
-      window.cancelAnimationFrame(this._raf);
-      this._raf = null;
-    }
-    window.removeEventListener('keydown', this._down);
-    window.removeEventListener('keyup', this._up);
-  }
-
-  _startLoop() {
-    if (!this._raf) {
-      this._last = performance.now();
-      this._raf = requestAnimationFrame((t) => this._step(t));
-    }
-  }
-
-  _step(t) {
-    const stage = this.view.stage;
-    let again = false;
-    const dt = Math.min(60, t - this._last) / 16.666;
-    this._last = t;
-    if (stage) {
-      const img = stage.gameImgProps;
-      const vp = img.viewPoint;
-      const scale = vp.scale;
-      // hold shift to pan much further per frame
-      const shiftMul = this.mod.shift ? 2 : 1;
-
-      // ----- panning -----
-      // tweak distance per frame; previous values felt too large
-      const baseX = 18 * scale;
-      const baseY = 9 * scale;
-      // smoother acceleration with immediate jump when direction changes
-      const accel = 0.18 / scale * dt;
-      const targetVX = (this.pan.right - this.pan.left) * baseX * shiftMul;
-      const targetVY = (this.pan.down - this.pan.up)   * baseY * shiftMul;
-      if (this.pan.changed) {
-        this.pan.vx = targetVX;
-        this.pan.vy = targetVY;
-        this.pan.changed = false;
-      } else {
-        this.pan.vx += (targetVX - this.pan.vx) * accel;
-        this.pan.vy += (targetVY - this.pan.vy) * accel;
-      }
-      // extend easing so velocity decays more gradually
-      this.pan.vx *= 0.85;
-      this.pan.vy *= 0.85;
-      const dx = this.pan.vx;
-      const dy = this.pan.vy;
-      if (Math.abs(dx) > 0.05 || Math.abs(dy) > 0.05) {
-        const nx = vp.x + dx / vp.scale;
-        const ny = vp.y + dy / vp.scale;
-        stage.applyViewport(img, nx, ny, stage._rawScale);
-        stage.redraw();
-        again = true;
-      } else {
-        this.pan.vx = this.pan.vy = 0;
-      }
-
-      // ----- zooming -----
-      // anchor zooming around the current screen centre without
-      // drifting the viewpoint. Using updateViewPoint() directly was
-      // causing the camera to slide left as the scale changed.
-      const { width: vpW, height: vpH } = img.canvasViewportSize;
-      const cx = vpW / 2;
-      const cy = vpH / 2;
-      const centerX = vp.x + cx / vp.scale;
-      const centerY = vp.y + cy / vp.scale;
-      let targetZ = 0;
-      if (this.zoom.reset !== null) {
-        targetZ = (this.zoom.reset - vp.scale) * 0.2;
-      } else {
-        // smaller default zoom step; shift increases it only modestly
-        const baseZ = 20 * (this.mod.shift ? 1.5 : 1);
-        targetZ = this.zoom.dir * baseZ;
-      }
-      // gentler acceleration for zooming
-      this.zoom.v += (targetZ - this.zoom.v) * 0.07 * dt;
-      this.zoom.v *= 0.9;
-      const dz = this.zoom.v;
-      if (Math.abs(dz) > 0.001) {
-        stage._rawScale = stage.limitValue(0.25, stage._rawScale * (1 + dz / 1500), 8);
-        const newScale = stage.snapScale(stage._rawScale);
-        const nx = centerX - cx / newScale;
-        const ny = centerY - cy / newScale;
-        stage.applyViewport(img, nx, ny, stage._rawScale);
-        stage.redraw();
-        again = true;
-      } else if (this.zoom.reset !== null) {
-        stage.applyViewport(img, vp.x, vp.y, this.zoom.reset);
-        this.zoom.reset = null;
-        stage.redraw();
-        this.zoom.v = 0;
-      } else {
-        this.zoom.v = 0;
-      }
-    }
-    if (again) {
-      this._raf = requestAnimationFrame((tt) => this._step(tt));
-    } else {
-      this._raf = null;
-    }
-  }
-
-  _cycleSkill(dir = 1) {
-    if (this._isGameplayBlocked()) return;
-    const game = this.view.game;
-    if (!game) return;
-    const skills = game.getGameSkills();
-    let next = skills.getSelectedSkill() + dir;
-    if (next > SkillTypes.DIGGER) next = SkillTypes.CLIMBER;
-    if (next < SkillTypes.CLIMBER) next = SkillTypes.DIGGER;
-    game.queueCommand(new CommandSelectSkill(next, false));
-    game.gameGui.skillSelectionChanged = true;
-  }
-
-  _instantNuke() {
-    if (this._isGameplayBlocked()) return;
-    const mgr = this.view.game?.getLemmingManager?.();
-    const lems = mgr?.getLemmings?.() ?? mgr?.lemmings;
-    if (!lems) return;
-    for (const lem of lems) {
-      if (lem.removed) continue;
-      if (lem.hasExploded) continue;
-      if (lem.countdownAction) continue;
-      if (lem.action === mgr.actions?.[LemmingStateType.EXPLODING]) continue;
-      if (lem.action === mgr.actions?.[LemmingStateType.OHNO]) continue;
-      mgr.setLemmingState(lem, LemmingStateType.EXPLODING);
-    }
-  }
-
-  _changeSpeed(dir, isShift) {
-    const game = this.view.game;
-    if (!game) return;
-    const timer = game.getGameTimer();
-    const gui = game.gameGui;
-    // Shift should noticeably speed things up
-    const steps = isShift ? 5 : 1;
-    for (let i=0;i<steps;i++) {
-      if (dir > 0) {
-        if (timer.speedFactor < 1) {
-          timer.speedFactor = Math.round((timer.speedFactor + 0.1) * 100) / 100;
-          gui.drawSpeedChange(true);
-        } else if (timer.speedFactor < 120) {
-          timer.speedFactor += 1;
-          gui.drawSpeedChange(true);
-        }
-      } else {
-        if (timer.speedFactor > 1) {
-          timer.speedFactor -= 1;
-          gui.drawSpeedChange(false);
-        } else if (timer.speedFactor > 0.1) {
-          timer.speedFactor = Math.round((timer.speedFactor - 0.1) * 100) / 100;
-          gui.drawSpeedChange(false);
-        }
-      }
-    }
-    this.view.gameSpeedFactor = timer.speedFactor;
-  }
-
-  _isGameplayBlocked() {
-    return !!this.view?.game?.timeTravel?.isReversing;
-  }
-
-  _shouldIgnoreKey(e, actions = []) {
-    const target = e?.target;
-    if (!target) return false;
-    if (target.isContentEditable) return true;
-    const tag = String(target.tagName || '').toUpperCase();
-    if (tag === 'SELECT') {
-      if (actions.includes('toggleReverse') ||
-          actions.includes('stepBackward') ||
-          actions.includes('stepForward')) {
-        return false;
-      }
-      return true;
-    }
-    return tag === 'INPUT' || tag === 'TEXTAREA';
-  }
-
-  _loadKeybindings() {
-    const provider = this.view?.gameFactory?.fileProvider;
-    if (!provider?.loadString) return;
-    provider.loadString('keybindings.json')
-      .then((text) => {
-        const parsed = parseKeybindingConfig(text);
-        if (!parsed) return;
-        this.keybindings.setConfig(parsed);
-      })
-      .catch(() => {});
-  }
-
-  getDisplayBindings(action) {
-    const specs = this.keybindings.getBindingsForAction(action);
-    return specs.map(spec => formatBindingSpec(spec)).filter(Boolean);
-  }
-
-  _createActionHandlers() {
-    return {
-      releaseRateDown: { down: () => {
-        if (this._isGameplayBlocked()) return;
-        const game = this.view.game;
-        if (!game) return;
-        game.queueCommand(new CommandReleaseRateDecrease(1));
-        game.gameGui.releaseRateChanged = true;
-      }},
-      releaseRateDownMax: { down: () => {
-        if (this._isGameplayBlocked()) return;
-        const game = this.view.game;
-        if (!game) return;
-        const vc = game.getVictoryCondition();
-        const diff = vc.getCurrentReleaseRate() - vc.getMinReleaseRate();
-        if (diff > 0) game.queueCommand(new CommandReleaseRateDecrease(diff));
-        game.gameGui.releaseRateChanged = true;
-      }},
-      releaseRateUp: { down: () => {
-        if (this._isGameplayBlocked()) return;
-        const game = this.view.game;
-        if (!game) return;
-        game.queueCommand(new CommandReleaseRateIncrease(1));
-        game.gameGui.releaseRateChanged = true;
-      }},
-      releaseRateUpMax: { down: () => {
-        if (this._isGameplayBlocked()) return;
-        const game = this.view.game;
-        if (!game) return;
-        const vc = game.getVictoryCondition();
-        const max = vc.getMaxReleaseRate?.() ?? GameVictoryCondition.maxReleaseRate;
-        const diff = max - vc.getCurrentReleaseRate();
-        if (diff > 0) game.queueCommand(new CommandReleaseRateIncrease(diff));
-        game.gameGui.releaseRateChanged = true;
-      }},
-      selectSkillClimber: { down: () => this._selectSkill(SkillTypes.CLIMBER) },
-      selectSkillFloater: { down: () => this._selectSkill(SkillTypes.FLOATER) },
-      selectSkillBomber: { down: () => this._selectSkill(SkillTypes.BOMBER) },
-      selectSkillBlocker: { down: () => this._selectSkill(SkillTypes.BLOCKER) },
-      selectSkillBuilder: { down: () => this._selectSkill(SkillTypes.BUILDER) },
-      selectSkillBasher: { down: () => this._selectSkill(SkillTypes.BASHER) },
-      selectSkillMiner: { down: () => this._selectSkill(SkillTypes.MINER) },
-      selectSkillDigger: { down: () => this._selectSkill(SkillTypes.DIGGER) },
-      togglePause: { down: () => {
-        const game = this.view.game;
-        if (!game) return;
-        if (game.timeTravel?.isReversing) {
-          game.timeTravel.stopReverse();
-          game.gameGui.skillSelectionChanged = true;
-          return;
-        }
-        game.getGameTimer().toggle();
-        game.gameGui.skillSelectionChanged = true;
-      }},
-      stepForward: { down: () => {
-        const timer = this.view.game?.getGameTimer?.();
-        if (!timer || timer.isRunning()) return;
-        this.view.nextFrame();
-      }},
-      stepBackward: { down: () => {
-        const timer = this.view.game?.getGameTimer?.();
-        if (!timer || timer.isRunning()) return;
-        this.view.prevFrame();
-      }},
-      toggleReverse: { down: () => {
-        const game = this.view.game;
-        if (!game?.timeTravel) return;
-        const midiConfig = this.view?.getMidiConfig?.()
-          ?? this.view?.midiRouter?.mapping?.config;
-        if (midiConfig?.reverse?.allNotesOffOnToggle) {
-          const scheduler = this.view?.midiRouter?.scheduler;
-          scheduler?.allNotesOff?.();
-          scheduler?.clearQueue?.();
-        }
-        game.timeTravel.toggleReverse();
-        if (game.gameGui) game.gameGui.gameTimeChanged = true;
-      }},
-      nuke: { down: () => {
-        if (this._isGameplayBlocked()) return;
-        const game = this.view.game;
-        if (!game) return;
-        game.queueCommand(new CommandNuke());
-      }},
-      nukeInstant: { down: () => this._instantNuke() },
-      restartLevel: { down: () => this.view.moveToLevel(0) },
-      panLeft: {
-        down: () => {
-          if (this.pan.vx > 0) this.pan.vx = 0;
-          this.pan.left = true;
-          this.pan.changed = true;
-          this._startLoop();
-        },
-        up: () => {
-          this.pan.left = false;
-          this.pan.changed = true;
-          this._startLoop();
-        }
-      },
-      panRight: {
-        down: () => {
-          if (this.pan.vx < 0) this.pan.vx = 0;
-          this.pan.right = true;
-          this.pan.changed = true;
-          this._startLoop();
-        },
-        up: () => {
-          this.pan.right = false;
-          this.pan.changed = true;
-          this._startLoop();
-        }
-      },
-      panUp: {
-        down: () => {
-          if (this.pan.vy > 0) this.pan.vy = 0;
-          this.pan.up = true;
-          this.pan.changed = true;
-          this._startLoop();
-        },
-        up: () => {
-          this.pan.up = false;
-          this.pan.changed = true;
-          this._startLoop();
-        }
-      },
-      panDown: {
-        down: () => {
-          if (this.pan.vy < 0) this.pan.vy = 0;
-          this.pan.down = true;
-          this.pan.changed = true;
-          this._startLoop();
-        },
-        up: () => {
-          this.pan.down = false;
-          this.pan.changed = true;
-          this._startLoop();
-        }
-      },
-      panBoost: {
-        preventDefault: false,
-        down: () => {
-          this.mod.shift = true;
-          this._startLoop();
-        },
-        up: () => {
-          this.mod.shift = false;
-          this._startLoop();
-        }
-      },
-      zoomIn: {
-        down: () => {
-          this.zoom.dir = 1;
-          this._startLoop();
-        },
-        up: () => {
-          if (this.zoom.dir > 0) this.zoom.dir = 0;
-          this._startLoop();
-        }
-      },
-      zoomOut: {
-        down: () => {
-          this.zoom.dir = -1;
-          this._startLoop();
-        },
-        up: () => {
-          if (this.zoom.dir < 0) this.zoom.dir = 0;
-          this._startLoop();
-        }
-      },
-      zoomReset: { down: () => {
-        this.zoom.reset = 2;
-        this._startLoop();
-      }},
-      cycleSkillNext: { down: () => this._cycleSkill(1) },
-      cycleSkillPrev: { down: () => this._cycleSkill(-1) },
-      applySkillToSelected: { down: () => {
-        if (this._isGameplayBlocked()) return;
-        const mgr = this.view.game?.getLemmingManager?.();
-        const lem = mgr?.getSelectedLemming?.();
-        if (!lem || !this.view.game) return;
-        this.view.game.queueCommand(new CommandLemmingsAction(lem.id));
-      }},
-      toggleDebug: { down: () => {
-        const game = this.view.game;
-        if (!game) return;
-        game.showDebug = !game.showDebug;
-      }},
-      speedDown: { down: () => this._changeSpeed(-1, false) },
-      speedDownFast: { down: () => this._changeSpeed(-1, true) },
-      speedUp: { down: () => this._changeSpeed(1, false) },
-      speedUpFast: { down: () => this._changeSpeed(1, true) },
-      levelPrev: { down: () => this.view.moveToLevel(-1) },
-      levelNext: { down: () => this.view.moveToLevel(1) },
-      levelGroupPrev: { down: () => {
-        if (this.view.levelGroupIndex > 0) {
-          this.view.selectLevelGroup(this.view.levelGroupIndex - 1);
-        } else if (this.view.gameType > 1) {
-          this.view.selectGameType(this.view.gameType - 1);
-        }
-      }},
-      levelGroupNext: { down: () => {
-        const totalGroups = this.view.elementSelectLevelGroup?.options.length ||
-          this.view.gameResources?.getLevelGroups().length || 0;
-        if (this.view.levelGroupIndex + 1 < totalGroups) {
-          this.view.selectLevelGroup(this.view.levelGroupIndex + 1);
-        } else {
-          this.view.selectGameType(this.view.gameType + 1);
-        }
-      }},
-      editorToggle: { down: () => {
-        if (typeof this.view.toggleEditorMode === 'function') {
-          this.view.toggleEditorMode();
-        }
-      }},
-      toggleShortcutOverlay: { down: () => {
-        this.view?.shortcutOverlay?.toggle?.();
-      }}
-    };
-  }
-
-  _selectSkill(skillType) {
-    if (this._isGameplayBlocked()) return;
-    const game = this.view.game;
-    if (!game) return;
-    game.queueCommand(new CommandSelectSkill(skillType));
-    game.gameGui.skillSelectionChanged = true;
-  }
-
-  _handleAction(action, type, event) {
-    const handler = this._actions[action];
-    if (!handler) return false;
-    const fn = type === 'up' ? handler.up : handler.down;
-    if (!fn) return false;
-    fn(event);
-    return handler.preventDefault !== false;
-  }
-
-  _onKeyDown(e) {
-    const actions = this.keybindings.getActionsForEvent(e);
-    if (!actions.length) return;
-    if (this._shouldIgnoreKey(e, actions)) return;
-    let handled = false;
-    for (const action of actions) {
-      if (this._handleAction(action, 'down', e)) handled = true;
-    }
-    if (handled) e.preventDefault();
-  }
-
-  _onKeyUp(e) {
-    const actions = this.keybindings.getActionsForEvent(e);
-    if (!actions.length) return;
-    let handled = false;
-    for (const action of actions) {
-      if (this._handleAction(action, 'up', e)) handled = true;
-    }
-    if (handled) e.preventDefault();
-  }
-}
-
-export { KeyboardShortcuts };
+export { KeyboardShortcuts } from './keyboard-shortcuts/KeyboardShortcutsCore.js';
diff --git a/js/input/UserInputManager.js b/js/input/UserInputManager.js
index ff27c0d2..f2a12926 100644
--- a/js/input/UserInputManager.js
+++ b/js/input/UserInputManager.js
@@ -1,5 +1,9 @@
 import { EventHandler } from '../util/EventHandler.js';
 import { Position2D } from '../util/Position2D.js';
+import { getAppContext } from '../core/dependencies.js';
+
+const PASSIVE_LISTENER = Object.freeze({ passive: true });
+const ACTIVE_LISTENER = Object.freeze({ passive: false });
 
 class MouseMoveEventArguements extends Position2D {
   constructor(x = 0, y = 0, deltaX = 0, deltaY = 0, button = false) {
@@ -25,7 +29,7 @@ class ZoomEventArgs extends Position2D {
 }
 
 class UserInputManager {
-  constructor(listenElement) {
+  constructor(listenElement, options = {}) {
     this.mouseDownX = 0;
     this.mouseDownY = 0;
     this.lastMouseX = 0;
@@ -41,6 +45,7 @@ class UserInputManager {
     this.onZoom = new EventHandler();
     this.listenElement = listenElement;
     this._listeners = [];
+    this._passiveMouseMove = options.passiveMouseMove !== false;
     this.twoTouch = false;
     this.lastTouchDistance = 0;
 
@@ -52,9 +57,6 @@ class UserInputManager {
     this._addListener('mousemove', (e) => {
       let relativePos = this.getRelativePosition(this.listenElement, e.clientX, e.clientY);
       this.handleMouseMove(relativePos);
-      e.stopPropagation();
-      e.preventDefault();
-      return false;
     });
     this._addListener('touchmove', (e) => {
       if (e.touches.length > 2) {
@@ -150,6 +152,11 @@ class UserInputManager {
       this.handleMouseUp(relativePos);
       return false;
     });
+    this._addListener('contextmenu', (e) => {
+      e.stopPropagation();
+      e.preventDefault();
+      return false;
+    });
     this._addListener('mouseleave', (e) => {
       e.stopPropagation();
       e.preventDefault();
@@ -177,6 +184,8 @@ class UserInputManager {
       }
       let relativePos = this.getRelativePosition(this.listenElement, e.changedTouches[0].clientX, e.changedTouches[0].clientY);
       this.handleMouseUp(relativePos);
+      e.stopPropagation();
+      e.preventDefault();
       return false;
     });
     this._addListener('touchleave', (e) => {
@@ -212,13 +221,28 @@ class UserInputManager {
   }
 
   _addListener(type, handler, options = null) {
-    const useOptions = options || (type.startsWith('touch') || type === 'wheel'
-      ? { passive: false }
-      : undefined);
+    let useOptions = options;
+    if (useOptions == null) {
+      useOptions = this._defaultListenerOptions(type);
+    }
     this.listenElement.addEventListener(type, handler, useOptions);
     this._listeners.push([type, handler, useOptions]);
   }
 
+  /**
+   * Listener options are explicit so the browser can keep high-frequency move
+   * handlers on the fast path while still allowing touch/wheel default-prevent.
+   */
+  _defaultListenerOptions(type) {
+    if (type === 'mousemove' || type === 'mouseleave') {
+      return this._passiveMouseMove ? PASSIVE_LISTENER : undefined;
+    }
+    if (type.startsWith('touch') || type === 'wheel') {
+      return ACTIVE_LISTENER;
+    }
+    return undefined;
+  }
+
   dispose() {
     for (const [type, handler, options] of this._listeners) {
       this.listenElement.removeEventListener(type, handler, options);
@@ -236,11 +260,22 @@ class UserInputManager {
   }
 
   getRelativePosition(element, clientX, clientY) {
-    const rect = element.getBoundingClientRect();
-    const scaleX = element.width / rect.width;
-    const scaleY = element.height / rect.height;
-    const x = (clientX - rect.left) * scaleX;
-    const y = (clientY - rect.top) * scaleY;
+    const rect = element?.getBoundingClientRect?.() || {
+      left: 0,
+      top: 0,
+      width: 0,
+      height: 0
+    };
+    const rectWidth = Number.isFinite(rect.width) ? rect.width : 0;
+    const rectHeight = Number.isFinite(rect.height) ? rect.height : 0;
+    const canvasWidth = Number.isFinite(element?.width) ? element.width : rectWidth;
+    const canvasHeight = Number.isFinite(element?.height) ? element.height : rectHeight;
+    const scaleX = rectWidth > 0 ? ((canvasWidth > 0 ? canvasWidth : rectWidth) / rectWidth) : 1;
+    const scaleY = rectHeight > 0 ? ((canvasHeight > 0 ? canvasHeight : rectHeight) / rectHeight) : 1;
+    const left = Number.isFinite(rect.left) ? rect.left : 0;
+    const top = Number.isFinite(rect.top) ? rect.top : 0;
+    const x = (clientX - left) * scaleX;
+    const y = (clientY - top) * scaleY;
     return new Position2D(x, y);
   }
   handleMouseMove(position) {
@@ -304,25 +339,8 @@ class UserInputManager {
     this.lastMouseX = position.x;
     this.lastMouseY = position.y;
 
-
-    const stage = globalThis?.lemmings?.stage;
     const evt = new ZoomEventArgs(position.x, position.y, deltaY);
-
-    if (stage && stage.getStageImageAt) {
-      this.onZoom.trigger(evt);
-
-      const stageImage = stage.getStageImageAt(position.x, position.y);
-      if (
-        stageImage &&
-        stageImage.display &&
-        stageImage.display.worldDataSize.width === 1600
-      ) {
-        stage.updateViewPoint(stageImage, position.x, position.y, deltaY);
-        return;
-      }
-    } else {
-      this.onZoom.trigger(evt);
-    }
+    this.onZoom.trigger(evt);
   }
 }
 
diff --git a/js/input/gamepad/GamepadConfig.js b/js/input/gamepad/GamepadConfig.js
new file mode 100644
index 00000000..d7389089
--- /dev/null
+++ b/js/input/gamepad/GamepadConfig.js
@@ -0,0 +1,85 @@
+import {
+  DEFAULT_AXIS_DEAD_ZONE,
+  DEFAULT_BUTTON_THRESHOLD,
+  DEFAULT_GAMEPAD_BINDINGS,
+  DEFAULT_STORAGE_KEY,
+  GAMEPAD_BUTTON_LABELS,
+  GamepadBindingRegistry,
+  NO_GAMEPAD_POLL_INTERVAL_MS,
+  bindingEntriesEqual,
+  clampUnit,
+  cloneGamepadConfig,
+  compactGamepadOverrideConfig,
+  formatGamepadBindingSpec,
+  mergeGamepadConfig,
+  mergeGamepadConfigLayers,
+  normalizeBindingList,
+  normalizeBindingsMap,
+  normalizeModeName,
+  parseBindingSpec,
+  parseGamepadBindingConfig,
+  parseNumberValue
+} from './GamepadInputControllerShared.js';
+const gamepadConfigMethods = {
+  _loadPersistedConfig() {
+    try {
+      const stored = this.storage?.getItem?.(this.storageKey);
+      const parsed = parseGamepadBindingConfig(stored);
+      if (parsed) {
+        this._layers.persisted = compactGamepadOverrideConfig(parsed);
+        this._persistConfig();
+        this._applyConfigLayers();
+      }
+    } catch {
+      /* ignored */
+    }
+  },
+
+  _persistConfig() {
+    try {
+      this.storage?.setItem?.(this.storageKey, JSON.stringify(this._layers.persisted || {
+        version: this.registry.config.version,
+        bindings: {}
+      }));
+    } catch {
+      /* ignored */
+    }
+  },
+
+  _loadFileConfig() {
+    if (!this.fileProvider?.loadString) return;
+    this.fileProvider.loadString('gamepadbindings.json')
+      .then((text) => {
+        const parsed = parseGamepadBindingConfig(text);
+        if (!parsed) return;
+        this._layers.file = cloneGamepadConfig(parsed);
+        if (this._layers.persisted) {
+          this._layers.persisted = compactGamepadOverrideConfig(
+            this._layers.persisted,
+            mergeGamepadConfigLayers(this._layers.file)
+          );
+          this._persistConfig();
+        }
+        this._applyConfigLayers();
+      })
+      .catch(() => {});
+  },
+
+  _applyConfigLayers() {
+    this.registry.setConfig(mergeGamepadConfigLayers(
+      this._layers.file,
+      this._layers.persisted,
+      this._layers.session
+    ));
+    this._releaseAllActions();
+    this._bindingActive.clear();
+  },
+
+  getDisplayBindings(action) {
+    return this.registry
+      .getBindingsForAction(this.mode, action)
+      .map(spec => formatGamepadBindingSpec(spec))
+      .filter(Boolean);
+  }
+};
+export { gamepadConfigMethods };
\ No newline at end of file
diff --git a/js/input/gamepad/GamepadInputControllerCore.js b/js/input/gamepad/GamepadInputControllerCore.js
new file mode 100644
index 00000000..59a503ce
--- /dev/null
+++ b/js/input/gamepad/GamepadInputControllerCore.js
@@ -0,0 +1,107 @@
+import {
+  DEFAULT_AXIS_DEAD_ZONE,
+  DEFAULT_BUTTON_THRESHOLD,
+  DEFAULT_GAMEPAD_BINDINGS,
+  DEFAULT_STORAGE_KEY,
+  GAMEPAD_BUTTON_LABELS,
+  GamepadBindingRegistry,
+  NO_GAMEPAD_POLL_INTERVAL_MS,
+  bindingEntriesEqual,
+  clampUnit,
+  cloneGamepadConfig,
+  compactGamepadOverrideConfig,
+  formatGamepadBindingSpec,
+  mergeGamepadConfig,
+  mergeGamepadConfigLayers,
+  normalizeBindingList,
+  normalizeBindingsMap,
+  normalizeModeName,
+  parseBindingSpec,
+  parseGamepadBindingConfig,
+  parseNumberValue
+} from './GamepadInputControllerShared.js';
+import { gamepadConfigMethods } from './GamepadConfig.js';
+import { gamepadPollingMethods } from './GamepadPolling.js';
+class GamepadInputController {
+  constructor(options = {}) {
+    this.mode = normalizeModeName(options.mode || 'gameplay') || 'gameplay';
+    this.onAction = typeof options.onAction === 'function' ? options.onAction : null;
+    this.window = options.window ?? globalThis.window;
+    this.navigator = options.navigator ?? globalThis.navigator;
+    this.storage = options.storage ?? globalThis.localStorage;
+    this.fileProvider = options.fileProvider || null;
+    this.storageKey = options.storageKey || DEFAULT_STORAGE_KEY;
+    this.registry = new GamepadBindingRegistry();
+    this._layers = {
+      file: null,
+      persisted: null,
+      session: null
+    };
+    this._bindingActive = new Map();
+    this._actionActiveCounts = new Map();
+    this._raf = 0;
+    this._running = false;
+    this._tick = this._tick.bind(this);
+    this._lastNoGamepadPollMs = -Infinity;
+    this._hasConnectedGamepad = false;
+    this._onGamepadConnected = () => {
+      this._hasConnectedGamepad = true;
+      this._lastNoGamepadPollMs = -Infinity;
+    };
+    this._onGamepadDisconnected = () => {
+      this._hasConnectedGamepad = this._detectConnectedGamepad() !== null;
+      if (!this._hasConnectedGamepad) {
+        this._releaseAllActions();
+        this._bindingActive.clear();
+      }
+    };
+    this.window?.addEventListener?.('gamepadconnected', this._onGamepadConnected);
+    this.window?.addEventListener?.('gamepaddisconnected', this._onGamepadDisconnected);
+    this._loadPersistedConfig();
+    this._loadFileConfig();
+    this._hasConnectedGamepad = this._detectConnectedGamepad() !== null;
+    this._start();
+  }
+
+  setConfig(config, { persist = true, layer = null } = {}) {
+    const layerName = layer || (persist ? 'persisted' : 'session');
+    if (!Object.hasOwn(this._layers, layerName)) {
+      throw new Error(`unknown gamepad config layer: ${layerName}`);
+    }
+    this._layers[layerName] = layerName === 'persisted'
+      ? compactGamepadOverrideConfig(config, mergeGamepadConfigLayers(this._layers.file))
+      : cloneGamepadConfig(config);
+    this._applyConfigLayers();
+    if (persist) {
+      this._persistConfig();
+    }
+  }
+
+  _poll() {
+    const bindings = this.registry.getCompiledBindings(this.mode);
+    if (!bindings.length) {
+      this._releaseAllActions();
+      this._bindingActive.clear();
+      return;
+    }
+    const gamepad = this._getPrimaryGamepad();
+    if (!gamepad) {
+      this._hasConnectedGamepad = false;
+      this._releaseAllActions();
+      this._bindingActive.clear();
+      return;
+    }
+    this._hasConnectedGamepad = true;
+    for (const binding of bindings) {
+      const nextActive = this._isBindingActive(binding.spec, gamepad);
+      this._setBindingState(binding.id, binding.action, nextActive);
+    }
+  }
+}
+for (const methods of [
+  gamepadConfigMethods,
+  gamepadPollingMethods
+]) {
+  Object.defineProperties(GamepadInputController.prototype, Object.getOwnPropertyDescriptors(methods));
+}
+export { GamepadInputController };
\ No newline at end of file
diff --git a/js/input/gamepad/GamepadInputControllerShared.js b/js/input/gamepad/GamepadInputControllerShared.js
new file mode 100644
index 00000000..791a3519
--- /dev/null
+++ b/js/input/gamepad/GamepadInputControllerShared.js
@@ -0,0 +1,301 @@
+
+const DEFAULT_GAMEPAD_BINDINGS = Object.freeze({
+  version: 1,
+  bindings: Object.freeze({
+    gameplay: Object.freeze({
+      togglePause: ['button:9'],
+      stepBackward: ['button:2'],
+      stepForward: ['button:3'],
+      toggleReverse: ['button:10'],
+      nuke: ['button:8'],
+      restartLevel: ['button:11'],
+      cycleSkillPrev: ['button:4'],
+      cycleSkillNext: ['button:5'],
+      applySkillToSelected: ['button:0'],
+      levelPrev: ['button:6'],
+      levelNext: ['button:7'],
+      toggleShortcutOverlay: ['button:16'],
+      panLeft: ['button:14', 'axis:0:-:0.35'],
+      panRight: ['button:15', 'axis:0:+:0.35'],
+      panUp: ['button:12', 'axis:1:-:0.35'],
+      panDown: ['button:13', 'axis:1:+:0.35'],
+      zoomIn: ['axis:3:-:0.35'],
+      zoomOut: ['axis:3:+:0.35'],
+      zoomReset: ['button:1']
+    }),
+    editor: Object.freeze({
+      editorToolSelect: ['button:10'],
+      editorToolTerrain: ['button:0'],
+      editorToolGadget: ['button:1'],
+      editorToolTrigger: ['button:2'],
+      editorToolMidiFlag: ['button:3'],
+      editorToolBrush: ['button:4'],
+      editorToolEraser: ['button:5'],
+      editorUndo: ['button:6'],
+      editorRedo: ['button:7'],
+      editorDelete: ['button:8'],
+      editorTogglePlaytest: ['button:9'],
+      editorToggleShortcutOverlay: ['button:16'],
+      editorNudgeLeft: ['button:14', 'axis:0:-:0.35'],
+      editorNudgeRight: ['button:15', 'axis:0:+:0.35'],
+      editorNudgeUp: ['button:12', 'axis:1:-:0.35'],
+      editorNudgeDown: ['button:13', 'axis:1:+:0.35']
+    })
+  })
+});
+const DEFAULT_STORAGE_KEY = 'lem-gamepad-bindings-v1';
+const DEFAULT_BUTTON_THRESHOLD = 0.5;
+const DEFAULT_AXIS_DEAD_ZONE = 0.35;
+const NO_GAMEPAD_POLL_INTERVAL_MS = 1000;
+const GAMEPAD_BUTTON_LABELS = Object.freeze({
+  0: 'A / Cross',
+  1: 'B / Circle',
+  2: 'X / Square',
+  3: 'Y / Triangle',
+  4: 'L1',
+  5: 'R1',
+  6: 'L2',
+  7: 'R2',
+  8: 'Select / View',
+  9: 'Start / Menu',
+  10: 'L3',
+  11: 'R3',
+  12: 'DPad Up',
+  13: 'DPad Down',
+  14: 'DPad Left',
+  15: 'DPad Right',
+  16: 'Home / Guide'
+});
+const normalizeBindingsMap = (input) => {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return {};
+  return input;
+};
+const normalizeBindingList = (entry) => {
+  if (Array.isArray(entry)) return entry;
+  if (typeof entry === 'string') return [entry];
+  return [];
+};
+const normalizeModeName = (value) => String(value || '').trim().toLowerCase();
+const parseNumberValue = (raw, fallback = null) => {
+  const num = Number(raw);
+  return Number.isFinite(num) ? num : fallback;
+};
+const clampUnit = (value, fallback) => {
+  const num = parseNumberValue(value, fallback);
+  if (!Number.isFinite(num)) return fallback;
+  return Math.min(Math.max(num, 0), 1);
+};
+const parseBindingSpec = (raw) => {
+  if (typeof raw !== 'string') return null;
+  const parts = raw.split(':').map(part => part.trim()).filter(Boolean);
+  if (!parts.length) return null;
+  const type = parts[0].toLowerCase();
+  if (type === 'button') {
+    const index = parseNumberValue(parts[1], null);
+    if (!Number.isFinite(index) || index < 0) return null;
+    const threshold = clampUnit(parts[2], DEFAULT_BUTTON_THRESHOLD);
+    return {
+      kind: 'button',
+      index: Math.trunc(index),
+      threshold
+    };
+  }
+  if (type === 'axis') {
+    const index = parseNumberValue(parts[1], null);
+    if (!Number.isFinite(index) || index < 0) return null;
+    const dirRaw = String(parts[2] || '').toLowerCase();
+    const direction = dirRaw === '+' || dirRaw === 'pos' || dirRaw === 'positive'
+      ? 1
+      : dirRaw === '-' || dirRaw === 'neg' || dirRaw === 'negative'
+        ? -1
+        : 0;
+    if (!direction) return null;
+    const deadZone = clampUnit(parts[3], DEFAULT_AXIS_DEAD_ZONE);
+    return {
+      kind: 'axis',
+      index: Math.trunc(index),
+      direction,
+      deadZone
+    };
+  }
+  return null;
+};
+const formatGamepadBindingSpec = (spec) => {
+  if (!spec) return '';
+  if (spec.kind === 'button') {
+    const label = GAMEPAD_BUTTON_LABELS[spec.index] || `Button ${spec.index}`;
+    return label;
+  }
+  if (spec.kind === 'axis') {
+    const dir = spec.direction < 0 ? '-' : '+';
+    return `Axis ${spec.index} ${dir}`;
+  }
+  return '';
+};
+const parseGamepadBindingConfig = (text) => {
+  if (typeof text !== 'string') return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+};
+const cloneGamepadConfig = (config) => {
+  if (!config || typeof config !== 'object') return null;
+  const clone = {
+    version: Number.isFinite(config.version) ? Math.trunc(config.version) : undefined,
+    bindings: {}
+  };
+  const modes = normalizeBindingsMap(config.bindings);
+  let hasBindings = false;
+  for (const modeName of ['gameplay', 'editor']) {
+    const modeBindings = normalizeBindingsMap(modes[modeName]);
+    const nextMode = {};
+    for (const [action, entry] of Object.entries(modeBindings)) {
+      if (Array.isArray(entry)) {
+        nextMode[action] = entry.slice();
+      } else if (typeof entry === 'string') {
+        nextMode[action] = entry;
+      } else {
+        nextMode[action] = entry;
+      }
+    }
+    if (Object.keys(nextMode).length) {
+      clone.bindings[modeName] = nextMode;
+      hasBindings = true;
+    }
+  }
+  if (!hasBindings) delete clone.bindings;
+  if (clone.version == null) delete clone.version;
+  return clone;
+};
+const bindingEntriesEqual = (left, right) => {
+  const leftList = normalizeBindingList(left);
+  const rightList = normalizeBindingList(right);
+  if (leftList.length !== rightList.length) return false;
+  for (let i = 0; i < leftList.length; i += 1) {
+    if (leftList[i] !== rightList[i]) return false;
+  }
+  return true;
+};
+const mergeGamepadConfig = (base, overrides = null) => {
+  const merged = {
+    version: base.version,
+    bindings: {
+      gameplay: { ...normalizeBindingsMap(base.bindings?.gameplay) },
+      editor: { ...normalizeBindingsMap(base.bindings?.editor) }
+    }
+  };
+  if (!overrides || typeof overrides !== 'object') return merged;
+  if (Number.isFinite(overrides.version)) {
+    merged.version = Math.trunc(overrides.version);
+  }
+  const overrideModes = normalizeBindingsMap(overrides.bindings);
+  for (const modeName of ['gameplay', 'editor']) {
+    const modeOverrides = normalizeBindingsMap(overrideModes[modeName]);
+    for (const [action, bindings] of Object.entries(modeOverrides)) {
+      merged.bindings[modeName][action] = bindings;
+    }
+  }
+  return merged;
+};
+const mergeGamepadConfigLayers = (...layers) => {
+  let merged = mergeGamepadConfig(DEFAULT_GAMEPAD_BINDINGS);
+  for (const layer of layers) {
+    if (!layer || typeof layer !== 'object') continue;
+    merged = mergeGamepadConfig(merged, layer);
+  }
+  return merged;
+};
+const compactGamepadOverrideConfig = (config, baseConfig = DEFAULT_GAMEPAD_BINDINGS) => {
+  const clone = cloneGamepadConfig(config);
+  if (!clone?.bindings) return clone;
+  const base = mergeGamepadConfig(DEFAULT_GAMEPAD_BINDINGS, baseConfig || null);
+  for (const modeName of ['gameplay', 'editor']) {
+    const modeBindings = normalizeBindingsMap(clone.bindings?.[modeName]);
+    const baseModeBindings = normalizeBindingsMap(base.bindings?.[modeName]);
+    for (const [action, bindings] of Object.entries(modeBindings)) {
+      if (bindingEntriesEqual(bindings, baseModeBindings[action])) {
+        delete modeBindings[action];
+      }
+    }
+    if (!Object.keys(modeBindings).length) {
+      delete clone.bindings[modeName];
+    }
+  }
+  if (!Object.keys(clone.bindings || {}).length) {
+    delete clone.bindings;
+  }
+  return clone;
+};
+class GamepadBindingRegistry {
+  constructor(config = DEFAULT_GAMEPAD_BINDINGS) {
+    this._compiledByMode = new Map();
+    this._specsByModeAction = new Map();
+    this.setConfig(config);
+  }
+
+  setConfig(config) {
+    this.config = mergeGamepadConfig(DEFAULT_GAMEPAD_BINDINGS, config);
+    this._compiledByMode.clear();
+    this._specsByModeAction.clear();
+
+    for (const modeName of ['gameplay', 'editor']) {
+      const modeBindings = normalizeBindingsMap(this.config.bindings?.[modeName]);
+      const compiled = [];
+      const byAction = new Map();
+      for (const [action, entry] of Object.entries(modeBindings)) {
+        const rawSpecs = normalizeBindingList(entry);
+        if (!rawSpecs.length) continue;
+        const parsedSpecs = [];
+        for (const rawSpec of rawSpecs) {
+          const spec = parseBindingSpec(rawSpec);
+          if (!spec) continue;
+          parsedSpecs.push(spec);
+          compiled.push({
+            id: `${action}:${spec.kind}:${spec.index}:${spec.direction ?? 0}:${spec.deadZone ?? spec.threshold ?? 0}`,
+            action,
+            spec
+          });
+        }
+        if (parsedSpecs.length) {
+          byAction.set(action, parsedSpecs);
+        }
+      }
+      this._compiledByMode.set(modeName, compiled);
+      this._specsByModeAction.set(modeName, byAction);
+    }
+  }
+
+  getCompiledBindings(mode) {
+    return this._compiledByMode.get(normalizeModeName(mode)) || [];
+  }
+
+  getBindingsForAction(mode, action) {
+    const map = this._specsByModeAction.get(normalizeModeName(mode));
+    return map?.get(action) || [];
+  }
+}
+
+export {
+  DEFAULT_AXIS_DEAD_ZONE,
+  DEFAULT_BUTTON_THRESHOLD,
+  DEFAULT_GAMEPAD_BINDINGS,
+  DEFAULT_STORAGE_KEY,
+  GAMEPAD_BUTTON_LABELS,
+  GamepadBindingRegistry,
+  NO_GAMEPAD_POLL_INTERVAL_MS,
+  bindingEntriesEqual,
+  clampUnit,
+  cloneGamepadConfig,
+  compactGamepadOverrideConfig,
+  formatGamepadBindingSpec,
+  mergeGamepadConfig,
+  mergeGamepadConfigLayers,
+  normalizeBindingList,
+  normalizeBindingsMap,
+  normalizeModeName,
+  parseBindingSpec,
+  parseGamepadBindingConfig,
+  parseNumberValue
+};
diff --git a/js/input/gamepad/GamepadPolling.js b/js/input/gamepad/GamepadPolling.js
new file mode 100644
index 00000000..00cb82d0
--- /dev/null
+++ b/js/input/gamepad/GamepadPolling.js
@@ -0,0 +1,123 @@
+import {
+  DEFAULT_AXIS_DEAD_ZONE,
+  DEFAULT_BUTTON_THRESHOLD,
+  DEFAULT_GAMEPAD_BINDINGS,
+  DEFAULT_STORAGE_KEY,
+  GAMEPAD_BUTTON_LABELS,
+  GamepadBindingRegistry,
+  NO_GAMEPAD_POLL_INTERVAL_MS,
+  bindingEntriesEqual,
+  clampUnit,
+  cloneGamepadConfig,
+  compactGamepadOverrideConfig,
+  formatGamepadBindingSpec,
+  mergeGamepadConfig,
+  mergeGamepadConfigLayers,
+  normalizeBindingList,
+  normalizeBindingsMap,
+  normalizeModeName,
+  parseBindingSpec,
+  parseGamepadBindingConfig,
+  parseNumberValue
+} from './GamepadInputControllerShared.js';
+const gamepadPollingMethods = {
+  _start() {
+    if (this._running) return;
+    if (typeof this.window?.requestAnimationFrame !== 'function') return;
+    if (typeof this.navigator?.getGamepads !== 'function') return;
+    this._running = true;
+    this._raf = this.window.requestAnimationFrame(this._tick);
+  },
+
+  _tick() {
+    this._raf = 0;
+    if (!this._running) return;
+    const now = typeof performance !== 'undefined' && typeof performance.now === 'function'
+      ? performance.now()
+      : Date.now();
+    if (this._hasConnectedGamepad || (now - this._lastNoGamepadPollMs) >= NO_GAMEPAD_POLL_INTERVAL_MS) {
+      this._lastNoGamepadPollMs = now;
+      this._poll();
+    }
+    this._raf = this.window.requestAnimationFrame(this._tick);
+  },
+
+  _detectConnectedGamepad() {
+    const rawPads = this.navigator?.getGamepads?.();
+    if (!rawPads) return null;
+    for (let i = 0; i < rawPads.length; i += 1) {
+      const pad = rawPads[i];
+      if (pad && pad.connected !== false) return pad;
+    }
+    return null;
+  },
+
+  _getPrimaryGamepad() {
+    return this._detectConnectedGamepad();
+  },
+
+  _isBindingActive(spec, gamepad) {
+    if (spec.kind === 'button') {
+      const button = gamepad?.buttons?.[spec.index];
+      if (!button) return false;
+      const pressed = button.pressed === true;
+      const value = Number.isFinite(button.value) ? button.value : (pressed ? 1 : 0);
+      return pressed || value >= (spec.threshold ?? DEFAULT_BUTTON_THRESHOLD);
+    }
+    if (spec.kind === 'axis') {
+      const value = Number(gamepad?.axes?.[spec.index] ?? 0);
+      if (!Number.isFinite(value)) return false;
+      const deadZone = spec.deadZone ?? DEFAULT_AXIS_DEAD_ZONE;
+      if (spec.direction < 0) {
+        return value <= -deadZone;
+      }
+      return value >= deadZone;
+    }
+    return false;
+  },
+
+  _setBindingState(bindingId, action, active) {
+    const prev = this._bindingActive.get(bindingId) === true;
+    if (prev === active) return;
+    this._bindingActive.set(bindingId, active);
+
+    const prevCount = this._actionActiveCounts.get(action) || 0;
+    if (active) {
+      const nextCount = prevCount + 1;
+      this._actionActiveCounts.set(action, nextCount);
+      if (prevCount === 0) {
+        this.onAction?.(action, 'down');
+      }
+      return;
+    }
+
+    const nextCount = Math.max(0, prevCount - 1);
+    if (nextCount === 0) {
+      this._actionActiveCounts.delete(action);
+      this.onAction?.(action, 'up');
+    } else {
+      this._actionActiveCounts.set(action, nextCount);
+    }
+  },
+
+  _releaseAllActions() {
+    if (!this._actionActiveCounts.size) return;
+    for (const action of this._actionActiveCounts.keys()) {
+      this.onAction?.(action, 'up');
+    }
+    this._actionActiveCounts.clear();
+  },
+
+  dispose() {
+    this._running = false;
+    if (this._raf) {
+      this.window?.cancelAnimationFrame?.(this._raf);
+      this._raf = 0;
+    }
+    this.window?.removeEventListener?.('gamepadconnected', this._onGamepadConnected);
+    this.window?.removeEventListener?.('gamepaddisconnected', this._onGamepadDisconnected);
+    this._releaseAllActions();
+    this._bindingActive.clear();
+  }
+};
+export { gamepadPollingMethods };
\ No newline at end of file
diff --git a/js/input/keyboard-shortcuts/KeyboardShortcutActions.js b/js/input/keyboard-shortcuts/KeyboardShortcutActions.js
new file mode 100644
index 00000000..4dd67b33
--- /dev/null
+++ b/js/input/keyboard-shortcuts/KeyboardShortcutActions.js
@@ -0,0 +1,274 @@
+import {
+  CommandLemmingsAction,
+  CommandNuke,
+  CommandReleaseRateDecrease,
+  CommandReleaseRateIncrease,
+  CommandSelectSkill,
+  GameVictoryCondition,
+  GamepadInputController,
+  KeybindingRegistry,
+  LemmingStateType,
+  SkillTypes,
+  formatBindingSpec,
+  getRuntimeDependency,
+  parseKeybindingConfig
+} from './KeyboardShortcutsShared.js';
+const keyboardShortcutActionsMethods = {
+  _createActionHandlers() {
+    return {
+      releaseRateDown: { down: () => {
+        if (this._isGameplayBlocked()) return;
+        const game = this.view.game;
+        if (!game) return;
+        game.queueCommand(new CommandReleaseRateDecrease(1));
+        game.gameGui.releaseRateChanged = true;
+      }},
+      releaseRateDownMax: { down: () => {
+        if (this._isGameplayBlocked()) return;
+        const game = this.view.game;
+        if (!game) return;
+        const vc = game.getVictoryCondition();
+        const diff = vc.getCurrentReleaseRate() - vc.getMinReleaseRate();
+        if (diff > 0) game.queueCommand(new CommandReleaseRateDecrease(diff));
+        game.gameGui.releaseRateChanged = true;
+      }},
+      releaseRateUp: { down: () => {
+        if (this._isGameplayBlocked()) return;
+        const game = this.view.game;
+        if (!game) return;
+        game.queueCommand(new CommandReleaseRateIncrease(1));
+        game.gameGui.releaseRateChanged = true;
+      }},
+      releaseRateUpMax: { down: () => {
+        if (this._isGameplayBlocked()) return;
+        const game = this.view.game;
+        if (!game) return;
+        const vc = game.getVictoryCondition();
+        const max = vc.getMaxReleaseRate?.() ?? GameVictoryCondition.maxReleaseRate;
+        const diff = max - vc.getCurrentReleaseRate();
+        if (diff > 0) game.queueCommand(new CommandReleaseRateIncrease(diff));
+        game.gameGui.releaseRateChanged = true;
+      }},
+      selectSkillClimber: { down: () => this._selectSkill(SkillTypes.CLIMBER) },
+      selectSkillFloater: { down: () => this._selectSkill(SkillTypes.FLOATER) },
+      selectSkillBomber: { down: () => this._selectSkill(SkillTypes.BOMBER) },
+      selectSkillBlocker: { down: () => this._selectSkill(SkillTypes.BLOCKER) },
+      selectSkillBuilder: { down: () => this._selectSkill(SkillTypes.BUILDER) },
+      selectSkillBasher: { down: () => this._selectSkill(SkillTypes.BASHER) },
+      selectSkillMiner: { down: () => this._selectSkill(SkillTypes.MINER) },
+      selectSkillDigger: { down: () => this._selectSkill(SkillTypes.DIGGER) },
+      togglePause: { down: () => {
+        const game = this.view.game;
+        if (!game) return;
+        if (game.timeTravel?.isReversing) {
+          game.timeTravel.stopReverse();
+          game.gameGui.skillSelectionChanged = true;
+          return;
+        }
+        game.getGameTimer().toggle();
+        game.gameGui.skillSelectionChanged = true;
+      }},
+      stepForward: { down: () => {
+        const timer = this.view.game?.getGameTimer?.();
+        if (!timer || timer.isRunning()) return;
+        this.view.nextFrame();
+      }},
+      stepBackward: { down: () => {
+        const timer = this.view.game?.getGameTimer?.();
+        if (!timer || timer.isRunning()) return;
+        this.view.prevFrame();
+      }},
+      toggleReverse: { down: () => {
+        const game = this.view.game;
+        if (!game?.timeTravel) return;
+        const midiConfig = this.view?.getMidiConfig?.()
+            ?? this.view?.midiRouter?.mapping?.config;
+        if (midiConfig?.reverse?.allNotesOffOnToggle) {
+          const scheduler = this.view?.midiRouter?.scheduler;
+          scheduler?.allNotesOff?.();
+          scheduler?.clearQueue?.();
+        }
+        game.timeTravel.toggleReverse();
+        if (game.gameGui) game.gameGui.gameTimeChanged = true;
+      }},
+      nuke: { down: () => {
+        if (this._isGameplayBlocked()) return;
+        const game = this.view.game;
+        if (!game) return;
+        game.queueCommand(new CommandNuke());
+      }},
+      nukeInstant: { down: () => this._instantNuke() },
+      restartLevel: { down: () => this.view.moveToLevel(0) },
+      panLeft: {
+        down: () => {
+          if (this.pan.vx > 0) this.pan.vx = 0;
+          this.pan.left = true;
+          this.pan.changed = true;
+          this._startLoop();
+        },
+        up: () => {
+          this.pan.left = false;
+          this.pan.changed = true;
+          this._startLoop();
+        }
+      },
+      panRight: {
+        down: () => {
+          if (this.pan.vx < 0) this.pan.vx = 0;
+          this.pan.right = true;
+          this.pan.changed = true;
+          this._startLoop();
+        },
+        up: () => {
+          this.pan.right = false;
+          this.pan.changed = true;
+          this._startLoop();
+        }
+      },
+      panUp: {
+        down: () => {
+          if (this.pan.vy > 0) this.pan.vy = 0;
+          this.pan.up = true;
+          this.pan.changed = true;
+          this._startLoop();
+        },
+        up: () => {
+          this.pan.up = false;
+          this.pan.changed = true;
+          this._startLoop();
+        }
+      },
+      panDown: {
+        down: () => {
+          if (this.pan.vy < 0) this.pan.vy = 0;
+          this.pan.down = true;
+          this.pan.changed = true;
+          this._startLoop();
+        },
+        up: () => {
+          this.pan.down = false;
+          this.pan.changed = true;
+          this._startLoop();
+        }
+      },
+      panBoost: {
+        preventDefault: false,
+        down: () => {
+          this.mod.shift = true;
+          this._startLoop();
+        },
+        up: () => {
+          this.mod.shift = false;
+          this._startLoop();
+        }
+      },
+      zoomIn: {
+        down: () => {
+          this.zoom.dir = 1;
+          this._startLoop();
+        },
+        up: () => {
+          if (this.zoom.dir > 0) this.zoom.dir = 0;
+          this._startLoop();
+        }
+      },
+      zoomOut: {
+        down: () => {
+          this.zoom.dir = -1;
+          this._startLoop();
+        },
+        up: () => {
+          if (this.zoom.dir < 0) this.zoom.dir = 0;
+          this._startLoop();
+        }
+      },
+      zoomReset: { down: () => {
+        this.zoom.reset = 2;
+        this._startLoop();
+      }},
+      cycleSkillNext: { down: () => this._cycleSkill(1) },
+      cycleSkillPrev: { down: () => this._cycleSkill(-1) },
+      applySkillToSelected: { down: () => {
+        if (this._isGameplayBlocked()) return;
+        const mgr = this.view.game?.getLemmingManager?.();
+        const lem = mgr?.getSelectedLemming?.();
+        if (!lem || !this.view.game) return;
+        this.view.game.queueCommand(new CommandLemmingsAction(lem.id));
+      }},
+      toggleDebug: { down: () => {
+        const game = this.view.game;
+        if (!game) return;
+        game.showDebug = !game.showDebug;
+      }},
+      speedDown: { down: () => this._changeSpeed(-1, false) },
+      speedDownFast: { down: () => this._changeSpeed(-1, true) },
+      speedUp: { down: () => this._changeSpeed(1, false) },
+      speedUpFast: { down: () => this._changeSpeed(1, true) },
+      levelPrev: { down: () => this.view.moveToLevel(-1) },
+      levelNext: { down: () => this.view.moveToLevel(1) },
+      levelGroupPrev: { down: () => {
+        if (this.view.levelGroupIndex > 0) {
+          this.view.selectLevelGroup(this.view.levelGroupIndex - 1);
+        } else if (this.view.gameType > 1) {
+          this.view.selectGameType(this.view.gameType - 1);
+        }
+      }},
+      levelGroupNext: { down: () => {
+        const totalGroups = this.view.elementSelectLevelGroup?.options.length ||
+            this.view.gameResources?.getLevelGroups().length || 0;
+        if (this.view.levelGroupIndex + 1 < totalGroups) {
+          this.view.selectLevelGroup(this.view.levelGroupIndex + 1);
+        } else {
+          this.view.selectGameType(this.view.gameType + 1);
+        }
+      }},
+      editorToggle: { down: () => {
+        if (typeof this.view.toggleEditorMode === 'function') {
+          this.view.toggleEditorMode();
+        }
+      }},
+      toggleShortcutOverlay: { down: () => {
+        this.view?.shortcutOverlay?.toggle?.();
+      }}
+    };
+  },
+
+  _selectSkill(skillType) {
+    if (this._isGameplayBlocked()) return;
+    const game = this.view.game;
+    if (!game) return;
+    game.queueCommand(new CommandSelectSkill(skillType));
+    game.gameGui.skillSelectionChanged = true;
+  },
+
+  _handleAction(action, type, event) {
+    const handler = this._actions[action];
+    if (!handler) return false;
+    const fn = type === 'up' ? handler.up : handler.down;
+    if (!fn) return false;
+    fn(event);
+    return handler.preventDefault !== false;
+  },
+
+  _onKeyDown(e) {
+    const actions = this.keybindings.getActionsForEvent(e);
+    if (!actions.length) return;
+    if (this._shouldIgnoreKey(e, actions)) return;
+    let handled = false;
+    for (const action of actions) {
+      if (this._handleAction(action, 'down', e)) handled = true;
+    }
+    if (handled) e.preventDefault();
+  },
+
+  _onKeyUp(e) {
+    const actions = this.keybindings.getActionsForEvent(e);
+    if (!actions.length) return;
+    let handled = false;
+    for (const action of actions) {
+      if (this._handleAction(action, 'up', e)) handled = true;
+    }
+    if (handled) e.preventDefault();
+  }
+};
+export { keyboardShortcutActionsMethods };
\ No newline at end of file
diff --git a/js/input/keyboard-shortcuts/KeyboardShortcutRuntime.js b/js/input/keyboard-shortcuts/KeyboardShortcutRuntime.js
new file mode 100644
index 00000000..d0d0ddb0
--- /dev/null
+++ b/js/input/keyboard-shortcuts/KeyboardShortcutRuntime.js
@@ -0,0 +1,232 @@
+import {
+  CommandLemmingsAction,
+  CommandNuke,
+  CommandReleaseRateDecrease,
+  CommandReleaseRateIncrease,
+  CommandSelectSkill,
+  GameVictoryCondition,
+  GamepadInputController,
+  KeybindingRegistry,
+  LemmingStateType,
+  SkillTypes,
+  formatBindingSpec,
+  getRuntimeDependency,
+  parseKeybindingConfig
+} from './KeyboardShortcutsShared.js';
+const keyboardShortcutRuntimeMethods = {
+  dispose() {
+    if (this._raf) {
+      this.cancelAnimationFrame?.(this._raf);
+      this._raf = null;
+    }
+    this.gamepad?.dispose?.();
+    this.gamepad = null;
+    this.window?.removeEventListener?.('keydown', this._down);
+    this.window?.removeEventListener?.('keyup', this._up);
+  },
+
+  _startLoop() {
+    if (!this._raf && typeof this.requestAnimationFrame === 'function') {
+      this._last = this.performance?.now?.() ?? Date.now();
+      this._raf = this.requestAnimationFrame((t) => this._step(t));
+    }
+  },
+
+  _step(t) {
+    const stage = this.view.stage;
+    let again = false;
+    const dt = Math.min(60, t - this._last) / 16.666;
+    this._last = t;
+    if (stage) {
+      const img = stage.gameImgProps;
+      const vp = img.viewPoint;
+      const scale = vp.scale;
+      // hold shift to pan much further per frame
+      const shiftMul = this.mod.shift ? 2 : 1;
+
+      // ----- panning -----
+      // tweak distance per frame; previous values felt too large
+      const baseX = 18 * scale;
+      const baseY = 9 * scale;
+      // smoother acceleration with immediate jump when direction changes
+      const accel = 0.18 / scale * dt;
+      const targetVX = (this.pan.right - this.pan.left) * baseX * shiftMul;
+      const targetVY = (this.pan.down - this.pan.up)   * baseY * shiftMul;
+      if (this.pan.changed) {
+        this.pan.vx = targetVX;
+        this.pan.vy = targetVY;
+        this.pan.changed = false;
+      } else {
+        this.pan.vx += (targetVX - this.pan.vx) * accel;
+        this.pan.vy += (targetVY - this.pan.vy) * accel;
+      }
+      // extend easing so velocity decays more gradually
+      this.pan.vx *= 0.85;
+      this.pan.vy *= 0.85;
+      const dx = this.pan.vx;
+      const dy = this.pan.vy;
+      if (Math.abs(dx) > 0.05 || Math.abs(dy) > 0.05) {
+        const nx = vp.x + dx / vp.scale;
+        const ny = vp.y + dy / vp.scale;
+        stage.applyViewport(img, nx, ny, stage._rawScale);
+        stage.redraw();
+        again = true;
+      } else {
+        this.pan.vx = this.pan.vy = 0;
+      }
+
+      // ----- zooming -----
+      // anchor zooming around the current screen centre without
+      // drifting the viewpoint. Using updateViewPoint() directly was
+      // causing the camera to slide left as the scale changed.
+      const { width: vpW, height: vpH } = img.canvasViewportSize;
+      const cx = vpW / 2;
+      const cy = vpH / 2;
+      const centerX = vp.x + cx / vp.scale;
+      const centerY = vp.y + cy / vp.scale;
+      let targetZ = 0;
+      if (this.zoom.reset !== null) {
+        targetZ = (this.zoom.reset - vp.scale) * 0.2;
+      } else {
+        // smaller default zoom step; shift increases it only modestly
+        const baseZ = 20 * (this.mod.shift ? 1.5 : 1);
+        targetZ = this.zoom.dir * baseZ;
+      }
+      // gentler acceleration for zooming
+      this.zoom.v += (targetZ - this.zoom.v) * 0.07 * dt;
+      this.zoom.v *= 0.9;
+      const dz = this.zoom.v;
+      if (Math.abs(dz) > 0.001) {
+        stage._rawScale = stage.limitValue(0.25, stage._rawScale * (1 + dz / 1500), 8);
+        const newScale = stage.snapScale(stage._rawScale);
+        const nx = centerX - cx / newScale;
+        const ny = centerY - cy / newScale;
+        stage.applyViewport(img, nx, ny, stage._rawScale);
+        stage.redraw();
+        again = true;
+      } else if (this.zoom.reset !== null) {
+        stage.applyViewport(img, vp.x, vp.y, this.zoom.reset);
+        this.zoom.reset = null;
+        stage.redraw();
+        this.zoom.v = 0;
+      } else if (this.zoom.dir !== 0) {
+        again = true;
+      } else {
+        this.zoom.v = 0;
+      }
+    }
+    if (again) {
+      if (typeof this.requestAnimationFrame === 'function') {
+        this._raf = this.requestAnimationFrame((tt) => this._step(tt));
+      } else {
+        this._raf = null;
+      }
+    } else {
+      this._raf = null;
+    }
+  },
+
+  _cycleSkill(dir = 1) {
+    if (this._isGameplayBlocked()) return;
+    const game = this.view.game;
+    if (!game) return;
+    const skills = game.getGameSkills();
+    let next = skills.getSelectedSkill() + dir;
+    if (next > SkillTypes.DIGGER) next = SkillTypes.CLIMBER;
+    if (next < SkillTypes.CLIMBER) next = SkillTypes.DIGGER;
+    game.queueCommand(new CommandSelectSkill(next, false));
+    game.gameGui.skillSelectionChanged = true;
+  },
+
+  _instantNuke() {
+    if (this._isGameplayBlocked()) return;
+    const mgr = this.view.game?.getLemmingManager?.();
+    const lems = mgr?.getLemmings?.() ?? mgr?.lemmings;
+    if (!lems) return;
+    for (const lem of lems) {
+      if (lem.removed) continue;
+      if (lem.hasExploded) continue;
+      if (lem.countdownAction) continue;
+      if (lem.action === mgr.actions?.[LemmingStateType.EXPLODING]) continue;
+      if (lem.action === mgr.actions?.[LemmingStateType.OHNO]) continue;
+      mgr.setLemmingState(lem, LemmingStateType.EXPLODING);
+    }
+  },
+
+  _changeSpeed(dir, isShift) {
+    const game = this.view.game;
+    if (!game) return;
+    const timer = game.getGameTimer?.();
+    const gui = game.gameGui;
+    // Some lightweight test and embed flows do not wire a timer/gui yet.
+    if (!timer) return;
+    // Shift should noticeably speed things up
+    const steps = isShift ? 5 : 1;
+    for (let i=0;i<steps;i++) {
+      if (dir > 0) {
+        if (timer.speedFactor < 1) {
+          timer.speedFactor = Math.round((timer.speedFactor + 0.1) * 100) / 100;
+          gui?.drawSpeedChange?.(true);
+        } else if (timer.speedFactor < 120) {
+          timer.speedFactor += 1;
+          gui?.drawSpeedChange?.(true);
+        }
+      } else {
+        if (timer.speedFactor > 1) {
+          timer.speedFactor -= 1;
+          gui?.drawSpeedChange?.(false);
+        } else if (timer.speedFactor > 0.1) {
+          timer.speedFactor = Math.round((timer.speedFactor - 0.1) * 100) / 100;
+          gui?.drawSpeedChange?.(false);
+        }
+      }
+    }
+    this.view.gameSpeedFactor = timer.speedFactor;
+  },
+
+  _isGameplayBlocked() {
+    return !!this.view?.game?.timeTravel?.isReversing;
+  },
+
+  _shouldIgnoreKey(e, actions = []) {
+    const target = e?.target;
+    if (!target) return false;
+    if (target.isContentEditable) return true;
+    const tag = String(target.tagName || '').toUpperCase();
+    if (tag === 'SELECT') {
+      if (actions.includes('toggleReverse') ||
+            actions.includes('stepBackward') ||
+            actions.includes('stepForward')) {
+        return false;
+      }
+      return true;
+    }
+    return tag === 'INPUT' || tag === 'TEXTAREA';
+  },
+
+  _loadKeybindings() {
+    const provider = this.view?.gameFactory?.fileProvider;
+    if (!provider?.loadString) return;
+    provider.loadString('keybindings.json')
+      .then((text) => {
+        const parsed = parseKeybindingConfig(text);
+        if (!parsed) return;
+        this.keybindings.setConfig(parsed);
+      })
+      .catch(() => {});
+  },
+
+  getDisplayBindings(action) {
+    const specs = this.keybindings.getBindingsForAction(action);
+    return specs.map(spec => formatBindingSpec(spec)).filter(Boolean);
+  },
+
+  getGamepadDisplayBindings(action) {
+    return this.gamepad?.getDisplayBindings(action) || [];
+  },
+
+  setGamepadBindings(config, options) {
+    this.gamepad?.setConfig?.(config, options);
+  }
+};
+export { keyboardShortcutRuntimeMethods };
\ No newline at end of file
diff --git a/js/input/keyboard-shortcuts/KeyboardShortcutsCore.js b/js/input/keyboard-shortcuts/KeyboardShortcutsCore.js
new file mode 100644
index 00000000..3169c889
--- /dev/null
+++ b/js/input/keyboard-shortcuts/KeyboardShortcutsCore.js
@@ -0,0 +1,61 @@
+import {
+  CommandLemmingsAction,
+  CommandNuke,
+  CommandReleaseRateDecrease,
+  CommandReleaseRateIncrease,
+  CommandSelectSkill,
+  GameVictoryCondition,
+  GamepadInputController,
+  KeybindingRegistry,
+  LemmingStateType,
+  SkillTypes,
+  formatBindingSpec,
+  getRuntimeDependency,
+  parseKeybindingConfig
+} from './KeyboardShortcutsShared.js';
+import { keyboardShortcutRuntimeMethods } from './KeyboardShortcutRuntime.js';
+import { keyboardShortcutActionsMethods } from './KeyboardShortcutActions.js';
+class KeyboardShortcuts {
+  constructor(view, options = {}) {
+    this.view = view;
+    this._down = this._onKeyDown.bind(this);
+    this._up = this._onKeyUp.bind(this);
+    this.window = options.window ?? view?.runtime?.window ?? getRuntimeDependency('window', null);
+    this.performance = options.performance ?? view?.runtime?.performance ?? getRuntimeDependency('performance', null);
+    this.requestAnimationFrame = options.requestAnimationFrame ??
+        view?.runtime?.requestAnimationFrame ??
+        this.window?.requestAnimationFrame?.bind?.(this.window) ??
+        null;
+    this.cancelAnimationFrame = options.cancelAnimationFrame ??
+        view?.runtime?.cancelAnimationFrame ??
+        this.window?.cancelAnimationFrame?.bind?.(this.window) ??
+        null;
+    this.window?.addEventListener?.('keydown', this._down);
+    this.window?.addEventListener?.('keyup', this._up);
+    this.mod = { shift:false };
+    this.pan = { left:false,right:false,up:false,down:false,vx:0,vy:0,changed:false };
+    this.zoom = { dir:0,v:0,reset:null };
+    this.keybindings = new KeybindingRegistry();
+    this._actions = this._createActionHandlers();
+    this.gamepad = new GamepadInputController({
+      mode: 'gameplay',
+      fileProvider: this.view?.gameFactory?.fileProvider || null,
+      window: this.window,
+      navigator: options.navigator ?? view?.runtime?.navigator ?? this.window?.navigator ?? getRuntimeDependency('navigator', null),
+      storage: options.storage ?? view?.runtime?.localStorage ?? this.window?.localStorage ?? getRuntimeDependency('localStorage', null),
+      onAction: (action, type) => {
+        this._handleAction(action, type, null);
+      }
+    });
+    this._raf = null;
+    this._last = 0;
+    this._loadKeybindings();
+  }
+}
+for (const methods of [
+  keyboardShortcutRuntimeMethods,
+  keyboardShortcutActionsMethods
+]) {
+  Object.defineProperties(KeyboardShortcuts.prototype, Object.getOwnPropertyDescriptors(methods));
+}
+export { KeyboardShortcuts };
\ No newline at end of file
diff --git a/js/input/keyboard-shortcuts/KeyboardShortcutsShared.js b/js/input/keyboard-shortcuts/KeyboardShortcutsShared.js
new file mode 100644
index 00000000..1b027510
--- /dev/null
+++ b/js/input/keyboard-shortcuts/KeyboardShortcutsShared.js
@@ -0,0 +1,29 @@
+import { CommandLemmingsAction } from '../../commands/CommandLemmingsAction.js';
+import { CommandNuke } from '../../commands/CommandNuke.js';
+import { CommandReleaseRateDecrease } from '../../commands/CommandReleaseRateDecrease.js';
+import { CommandReleaseRateIncrease } from '../../commands/CommandReleaseRateIncrease.js';
+import { CommandSelectSkill } from '../../commands/CommandSelectSkill.js';
+import { GameVictoryCondition } from '../../game/GameVictoryCondition.js';
+import { LemmingStateType } from '../../lemmings/LemmingStateType.js';
+import { SkillTypes } from '../../game/SkillTypes.js';
+import { GamepadInputController } from '../GamepadInputController.js';
+import { KeybindingRegistry, parseKeybindingConfig } from '../KeybindingRegistry.js';
+import { formatBindingSpec } from '../KeybindingFormatter.js';
+import { getRuntimeDependency } from '../../core/dependencies.js';
+
+
+export {
+  CommandLemmingsAction,
+  CommandNuke,
+  CommandReleaseRateDecrease,
+  CommandReleaseRateIncrease,
+  CommandSelectSkill,
+  GameVictoryCondition,
+  GamepadInputController,
+  KeybindingRegistry,
+  LemmingStateType,
+  SkillTypes,
+  formatBindingSpec,
+  getRuntimeDependency,
+  parseKeybindingConfig
+};
diff --git a/js/lemmings/Lemming.js b/js/lemmings/Lemming.js
index 81954a9a..ff07d196 100644
--- a/js/lemmings/Lemming.js
+++ b/js/lemmings/Lemming.js
@@ -1,10 +1,27 @@
 import { LemmingStateType } from './LemmingStateType.js';
 import { BaseLogger } from '../util/LogHandler.js';
-import { SoundEventTypes, SoundEffectIds, getSoundBus } from '../game/SoundEvents.js';
+import { SoundEventTypes, SoundEffectIds } from '../game/SoundEvents.js';
+import { getRuntimeMiniMap, getRuntimeSoundEvents } from '../game/GameRuntime.js';
+
+const addMiniMapDeath = (runtime, x, y) => {
+  getRuntimeMiniMap(runtime)?.addDeath(x, y);
+};
 
 class Lemming extends BaseLogger {
-  constructor(x = 0, y = 0, id) {
+  constructor(x = 0, y = 0, id, runtime = null) {
     super();
+    this.runtime = runtime;
+    this.reset(x, y, id);
+  }
+
+  setRuntime(runtime = null) {
+    this.runtime = runtime;
+  }
+
+  /**
+   * Reinitialize this instance so managers can reuse pooled objects.
+   */
+  reset(x = 0, y = 0, id) {
     this.lookRight = true;
     this.frameIndex = 0;
     this.canClimb = false;
@@ -15,6 +32,9 @@ class Lemming extends BaseLogger {
     this.state = 0;
     this.hasExploded = false;
     this.disabled = false;
+    this.lastTriggerType = null;
+    this.countdownAction = null;
+    this._activeIndex = -1;
     this.x = x;
     this.y = y;
     this.id = id;
@@ -56,7 +76,7 @@ class Lemming extends BaseLogger {
 
   render(gameDisplay) {
     if (!this.action) return;
-    if (this.countdownAction != null) {
+    if (this.countdownAction !== null && this.countdownAction !== undefined) {
       this.countdownAction.draw(gameDisplay, this);
     }
     this.action.draw(gameDisplay, this);
@@ -75,28 +95,24 @@ class Lemming extends BaseLogger {
       if (lemY >= level.height) {
         newY = level.height - 6;
       }
-      const soundBus = getSoundBus();
+      const soundBus = getRuntimeSoundEvents(this.runtime);
       soundBus?.emitSfx?.(
         SoundEventTypes.LEMMING_FELL_OFF,
         SoundEffectIds.FELL_OFF,
         { lemmingId: this.id, x: lemX, y: newY }
       );
-      if (lemmings?.game?.lemmingManager?.miniMap) {
-        lemmings.game.lemmingManager.miniMap.addDeath(lemX, newY);
-      }
+      addMiniMapDeath(this.runtime, lemX, newY);
       return LemmingStateType.OUT_OF_LEVEL;
     }
     // run main action
     if (!this.action) {
-      if (lemmings?.game?.lemmingManager?.miniMap) {
-        lemmings.game.lemmingManager.miniMap.addDeath(lemX, this.y);
-      }
+      addMiniMapDeath(this.runtime, lemX, this.y);
       return LemmingStateType.OUT_OF_LEVEL;
     }
     // run secondary action
     if (this.countdownAction) {
       let newAction = this.countdownAction.process(level, this);
-      if (newAction != LemmingStateType.NO_STATE_TYPE) {
+      if (newAction !== LemmingStateType.NO_STATE_TYPE) {
         return newAction;
       }
     }
@@ -122,7 +138,7 @@ class Lemming extends BaseLogger {
   }
 
   isDisabled() { return this.disabled; }
-  isRemoved() { return (this.action == null); }
+  isRemoved() { return this.action === null; }
 }
 
 Lemming.LEM_MIN_Y = -5;
diff --git a/js/lemmings/LemmingManager.js b/js/lemmings/LemmingManager.js
index 2d416dc3..ad6cdb7c 100644
--- a/js/lemmings/LemmingManager.js
+++ b/js/lemmings/LemmingManager.js
@@ -1,687 +1 @@
-import { COUNTER_LIMIT } from '../core/constants.js';
-import { SoundEventTypes, SoundEffectIds, getSoundBus } from '../game/SoundEvents.js';
-import { ActionBashSystem } from '../actions/ActionBashSystem.js';
-import { ActionBlockerSystem } from '../actions/ActionBlockerSystem.js';
-import { ActionBuildSystem } from '../actions/ActionBuildSystem.js';
-import { ActionClimbSystem } from '../actions/ActionClimbSystem.js';
-import { ActionCountdownSystem } from '../actions/ActionCountdownSystem.js';
-import { ActionDiggSystem } from '../actions/ActionDiggSystem.js';
-import { ActionDrowningSystem } from '../actions/ActionDrowningSystem.js';
-import { ActionExitingSystem } from '../actions/ActionExitingSystem.js';
-import { ActionExplodingSystem } from '../actions/ActionExplodingSystem.js';
-import { ActionFallSystem } from '../actions/ActionFallSystem.js';
-import { ActionFloatingSystem } from '../actions/ActionFloatingSystem.js';
-import { ActionFryingSystem } from '../actions/ActionFryingSystem.js';
-import { ActionHoistSystem } from '../actions/ActionHoistSystem.js';
-import { ActionJumpSystem } from '../actions/ActionJumpSystem.js';
-import { ActionMineSystem } from '../actions/ActionMineSystem.js';
-import { ActionOhNoSystem } from '../actions/ActionOhNoSystem.js';
-import { ActionShrugSystem } from '../actions/ActionShrugSystem.js';
-import { ActionSplatterSystem } from '../actions/ActionSplatterSystem.js';
-import { ActionWalkSystem } from '../actions/ActionWalkSystem.js';
-import { Lemming } from './Lemming.js';
-import { LemmingStateType } from './LemmingStateType.js';
-import { BaseLogger, LogHandler, withPerformance } from '../util/LogHandler.js';
-import { SkillTypes } from '../game/SkillTypes.js';
-import { TriggerTypes } from '../level/TriggerTypes.js';
-import { getDependency } from '../core/dependencies.js';
-
-class LemmingManager extends BaseLogger {
-  #mmTickCounter = 0;
-  #releaseTickIndex = 0;
-  constructor(level, lemmingsSprite, triggerManager, gameVictoryCondition, masks, particleTable) {
-    super();
-    withPerformance(
-      'LemmingManager constructor',
-      {
-        track: 'LemmingManager',
-        trackGroup: 'Game State',
-        color: 'primary',
-        tooltipText: 'LemmingManager constructor'
-      },
-      () => {
-        if (!lemmings.bench && !lemmings.bench2 && !lemmings.benchReverse && (lemmings.extraLemmings | 0) === 0) {
-          this.lemmings = new Array(gameVictoryCondition.getReleaseCount());
-          this.lemmings.length = 0;
-        } else {
-          this.lemmings = [];
-        }
-        this.activeLemmings = [];
-        this._activeDirty = false;
-        this.minimapDots = new Uint8Array(0);
-        this.spawnTotal = 0;
-        this.selectedIndex = -1;
-        const maxDots = (gameVictoryCondition.getReleaseCount() +
-          (lemmings.extraLemmings | 0)) * 2;
-        this._minimapDotBuffer = new Uint8Array(maxDots);
-        this.minimapDots = this._minimapDotBuffer.subarray(0, 0);
-        this._mmVisited = new Uint8Array(65536);
-        if (!LemmingManager.log) {
-          LemmingManager.log = this.log;
-        }
-        this.level = level;
-        this.triggerManager = triggerManager;
-        this.gameVictoryCondition = gameVictoryCondition;
-        this.actions = [];
-        this.skillActions = [];
-        this.logging = LemmingManager.log;
-        this.miniMap = null;
-        this.nextNukingLemmingsIndex = -1;
-        this._nukeTargets = null;
-
-        const WalkSystem = getDependency('ActionWalkSystem', ActionWalkSystem);
-        const FallSystem = getDependency('ActionFallSystem', ActionFallSystem);
-        const JumpSystem = getDependency('ActionJumpSystem', ActionJumpSystem);
-        const DiggSystem = getDependency('ActionDiggSystem', ActionDiggSystem);
-        const ExitSystem = getDependency('ActionExitingSystem', ActionExitingSystem);
-        const FloatSystem = getDependency('ActionFloatingSystem', ActionFloatingSystem);
-        const BlockSystem = getDependency('ActionBlockerSystem', ActionBlockerSystem);
-        const MineSystem = getDependency('ActionMineSystem', ActionMineSystem);
-        const ClimbSystem = getDependency('ActionClimbSystem', ActionClimbSystem);
-        const HoistSystem = getDependency('ActionHoistSystem', ActionHoistSystem);
-        const BashSystem = getDependency('ActionBashSystem', ActionBashSystem);
-        const BuildSystem = getDependency('ActionBuildSystem', ActionBuildSystem);
-        const ShrugSystem = getDependency('ActionShrugSystem', ActionShrugSystem);
-        const ExplodeSystem = getDependency('ActionExplodingSystem', ActionExplodingSystem);
-        const OhNoSystem = getDependency('ActionOhNoSystem', ActionOhNoSystem);
-        const SplatterSystem = getDependency('ActionSplatterSystem', ActionSplatterSystem);
-        const DrownSystem = getDependency('ActionDrowningSystem', ActionDrowningSystem);
-        const FrySystem = getDependency('ActionFryingSystem', ActionFryingSystem);
-        const CountdownSystem = getDependency('ActionCountdownSystem', ActionCountdownSystem);
-
-        this.actions[LemmingStateType.WALKING]    = new WalkSystem(lemmingsSprite);
-        this.actions[LemmingStateType.FALLING]    = new FallSystem(lemmingsSprite);
-        this.actions[LemmingStateType.JUMPING]    = new JumpSystem(lemmingsSprite);
-        this.actions[LemmingStateType.DIGGING]    = new DiggSystem(lemmingsSprite);
-        this.actions[LemmingStateType.EXITING]    = new ExitSystem(lemmingsSprite, gameVictoryCondition);
-        this.actions[LemmingStateType.FLOATING]   = new FloatSystem(lemmingsSprite);
-        this.actions[LemmingStateType.BLOCKING]   = new BlockSystem(lemmingsSprite, triggerManager);
-        this.actions[LemmingStateType.MINING]     = new MineSystem(lemmingsSprite, masks);
-        this.actions[LemmingStateType.CLIMBING]   = new ClimbSystem(lemmingsSprite);
-        this.actions[LemmingStateType.HOISTING]   = new HoistSystem(lemmingsSprite);
-        this.actions[LemmingStateType.BASHING]    = new BashSystem(lemmingsSprite, masks);
-        this.actions[LemmingStateType.BUILDING]   = new BuildSystem(lemmingsSprite);
-        this.actions[LemmingStateType.SHRUG]      = new ShrugSystem(lemmingsSprite);
-        this.actions[LemmingStateType.EXPLODING]  = new ExplodeSystem(lemmingsSprite, masks, triggerManager, particleTable);
-        this.actions[LemmingStateType.OHNO]       = new OhNoSystem(lemmingsSprite);
-        this.actions[LemmingStateType.SPLATTING]  = new SplatterSystem(lemmingsSprite);
-        this.actions[LemmingStateType.DROWNING]   = new DrownSystem(lemmingsSprite);
-        this.actions[LemmingStateType.FRYING]     = new FrySystem(lemmingsSprite);
-
-        this.skillActions[SkillTypes.DIGGER]  = this.actions[LemmingStateType.DIGGING];
-        this.skillActions[SkillTypes.FLOATER] = this.actions[LemmingStateType.FLOATING];
-        this.skillActions[SkillTypes.BLOCKER] = this.actions[LemmingStateType.BLOCKING];
-        this.skillActions[SkillTypes.MINER]   = this.actions[LemmingStateType.MINING];
-        this.skillActions[SkillTypes.CLIMBER] = this.actions[LemmingStateType.CLIMBING];
-        this.skillActions[SkillTypes.BASHER]  = this.actions[LemmingStateType.BASHING];
-        this.skillActions[SkillTypes.BUILDER] = this.actions[LemmingStateType.BUILDING];
-        this.skillActions[SkillTypes.BOMBER]  = new CountdownSystem(masks);
-        this.countdownAction = this.skillActions[SkillTypes.BOMBER];
-
-        this.actionTypeByAction = new Map();
-        for (let i = 0; i < this.actions.length; i++) {
-          const action = this.actions[i];
-          if (action) this.actionTypeByAction.set(action, i);
-        }
-
-        this._actionTypes = {
-          blocker: BlockSystem,
-          basher: BashSystem,
-          builder: BuildSystem,
-          climber: ClimbSystem,
-          digger: DiggSystem,
-          floater: FloatSystem,
-          miner: MineSystem
-        };
-        this._lemmingCtor = getDependency('Lemming', Lemming);
-
-        this.releaseTickIndex = this.gameVictoryCondition.getCurrentReleaseRate() - 30;
-      })();
-  }
-
-  get mmTickCounter() { return this.#mmTickCounter; }
-  set mmTickCounter(v) {
-    if (v >= COUNTER_LIMIT) {
-      console.warn('mmTickCounter wrapped, resetting to 0');
-      this.#mmTickCounter = 0;
-    } else {
-      this.#mmTickCounter = v;
-    }
-  }
-
-  get releaseTickIndex() { return this.#releaseTickIndex; }
-  set releaseTickIndex(v) {
-    if (v >= COUNTER_LIMIT) {
-      console.warn('releaseTickIndex wrapped, resetting to 0');
-      this.#releaseTickIndex = 0;
-    } else {
-      this.#releaseTickIndex = v;
-    }
-  }
-
-  setMiniMap(miniMap) {
-    this.miniMap = miniMap;
-  }
-
-  _addActiveLemming(lem) {
-    lem._activeIndex = this.activeLemmings.length;
-    this.activeLemmings.push(lem);
-  }
-
-  _compactActiveLemmings() {
-    const lems = this.activeLemmings;
-    let write = 0;
-    for (let i = 0; i < lems.length; i++) {
-      const lem = lems[i];
-      if (lem.removed) continue;
-      lem._activeIndex = write;
-      lems[write++] = lem;
-    }
-    lems.length = write;
-    this._activeDirty = false;
-  }
-
-  processNewAction(lem, newAction) {
-    if (newAction == LemmingStateType.NO_STATE_TYPE) return false;
-    this.setLemmingState(lem, newAction);
-    return true;
-  }
-
-  tick() {
-    const tickNum = this.mmTickCounter;
-    withPerformance(
-      'tick',
-      {
-        track: 'LemmingManager',
-        trackGroup: 'Game State',
-        color: 'tertiary-dark',
-        tooltipText: `tick ${tickNum}`
-      },
-      () => {
-        this.addNewLemmings();
-        const lems = this.activeLemmings;
-        const count = lems.length;
-        if (this.isNuking()) {
-          this._nukeNextLemming();
-        }
-        for (const lem of lems) {
-          if (lem.removed && lem.action !== this.actions[LemmingStateType.EXPLODING]) continue;
-          const newAction = lem.process(this.level);
-          this.processNewAction(lem, newAction);
-          const triggerAction = this.runTrigger(lem);
-          this.processNewAction(lem, triggerAction);
-        }
-        const sel = this.getSelectedLemming();
-        if (!sel || sel.removed || sel.disabled) this.selectedIndex = -1;
-        if (lemmings.bench || lemmings.bench2 || lemmings.benchReverse) {
-          lemmings.laggedOut = count;
-        }
-        if (this.miniMap && ((++this.mmTickCounter % 10) === 0)) {
-          const lemsCount = lems.length;
-          if (this._minimapDotBuffer.length < lemsCount * 2) {
-            this._minimapDotBuffer = new Uint8Array(lemsCount * 2);
-          }
-          const dots = this._minimapDotBuffer;
-          const visited = this._mmVisited;
-          visited.fill(0);
-          const scaleX = this.miniMap.scaleX;
-          const scaleY = this.miniMap.scaleY;
-          let idx = 0;
-          let selDot = null;
-          for (const lem of lems) {
-            if (lem.removed || lem.disabled) continue;
-            const x = (lem.x * scaleX) | 0;
-            const y = (lem.y * scaleY) | 0;
-            if (lem.id === this.selectedIndex) selDot = [x, y];
-            const key = (y << 8) | x;
-            if (visited[key]) continue;
-            visited[key] = 1;
-            dots[idx++] = x;
-            dots[idx++] = y;
-          }
-          this.minimapDots = dots.subarray(0, idx);
-          this.miniMap.setLiveDots(this.minimapDots);
-          this.miniMap.setSelectedDot(selDot);
-        }
-        if (this._activeDirty) {
-          this._compactActiveLemmings();
-        }
-      })();
-  }
-
-  addLemming(x, y) {
-    withPerformance(
-      'addLemming',
-      {
-        track: 'LemmingManager',
-        trackGroup: 'Game State',
-        color: 'primary-light',
-        tooltipText: `addLemming ${x},${y}`
-      },
-      () => {
-        const startingLemLength = this.lemmings.length;
-        const LemmingCtor = this._lemmingCtor || Lemming;
-        const lem = new LemmingCtor(x, y, startingLemLength);
-        if (lemmings.bench || lemmings.bench2 || lemmings.benchReverse) {
-          lem.lookRight = Math.random() < 0.5;
-        }
-        this.setLemmingState(lem, LemmingStateType.FALLING);
-        this.lemmings.push(lem);
-        this._addActiveLemming(lem);
-        this.spawnTotal += 1;
-
-        const extraCount = lemmings.extraLemmings | 0;
-        if (extraCount > 0) {
-          const action = this.actions[LemmingStateType.FALLING];
-          const extras = new Array(extraCount);
-          for (let i = 0; i < extraCount; i++) {
-            const extra = new LemmingCtor(
-              x,
-              y,
-              startingLemLength + 1 + i
-            );
-            if (lemmings.bench || lemmings.bench2 || lemmings.benchReverse) {
-              extra.lookRight = Math.random() < 0.5;
-            }
-            extra.setAction(action);
-            extras[i] = extra;
-            this._addActiveLemming(extra);
-          }
-          Array.prototype.push.apply(this.lemmings, extras);
-          this.spawnTotal += extraCount;
-        }
-      })();
-  }
-
-  addNewLemmings() {
-    const endless = lemmings?.endless === true;
-    if (lemmings.bench == true || lemmings.bench2 == true || lemmings.benchReverse == true) { // if bench is enabled just keep spawning lems by skipping gameVictoryCondition check
-            
-    } else {
-      if (!endless && this.gameVictoryCondition.getLeftCount() <= 0) return;
-    }
-    if (++this.releaseTickIndex >= (104 - this.gameVictoryCondition.getCurrentReleaseRate())) {
-      this.releaseTickIndex = 0;
-      const entrances = this.level.entrances;
-      for (let i = 0, l = entrances.length; i < l; i++) {
-        const entrance = entrances[i];
-        const spawnX = entrance.x + 24;
-        const spawnY = entrance.y + 14;
-        if (!entrance._opened) {
-          entrance._opened = true;
-          const soundBus = getSoundBus();
-          soundBus?.emitSfx?.(
-            SoundEventTypes.ENTRANCE_OPEN,
-            SoundEffectIds.ENTRANCE_OPEN,
-            {
-              entranceIndex: i,
-              x: spawnX,
-              y: spawnY
-            }
-          );
-        }
-        this.addLemming(spawnX, spawnY);
-        this.gameVictoryCondition.releaseOne();
-      }
-    }
-  }
-
-  runTrigger(lem) {
-    if (lem.isRemoved() || lem.isDisabled()) {
-      // this.lemmings.splice(this.lemmings.indexOf(lem), 1);
-      return LemmingStateType.NO_STATE_TYPE;
-    }
-    const triggerType = this.triggerManager.trigger(lem.x, lem.y, lem);
-    switch (triggerType) {
-    case TriggerTypes.NO_TRIGGER:
-      return LemmingStateType.NO_STATE_TYPE;
-    case TriggerTypes.DROWN:
-      lem.lastTriggerType = triggerType;
-      return LemmingStateType.DROWNING;
-    case TriggerTypes.EXIT_LEVEL:
-      lem.lastTriggerType = triggerType;
-      return LemmingStateType.EXITING;
-    case TriggerTypes.KILL:
-      lem.lastTriggerType = triggerType;
-      return LemmingStateType.SPLATTING;
-    case TriggerTypes.FRYING:
-      lem.lastTriggerType = triggerType;
-      return LemmingStateType.FRYING;
-    case TriggerTypes.TRAP:
-      lem.lastTriggerType = triggerType;
-      return LemmingStateType.SPLATTING;
-    case TriggerTypes.BLOCKER_LEFT:
-      if (lem.lookRight) lem.lookRight = false;
-      return LemmingStateType.NO_STATE_TYPE;
-    case TriggerTypes.BLOCKER_RIGHT:
-      if (!lem.lookRight) lem.lookRight = true;
-      return LemmingStateType.NO_STATE_TYPE;
-    default:
-      this.logging.log('unknown trigger type: ' + triggerType);
-      return LemmingStateType.NO_STATE_TYPE;
-    }
-  }
-
-  render(gameDisplay) {
-    withPerformance(
-      'render',
-      {
-        track: 'LemmingManager',
-        trackGroup: 'Render',
-        color: 'tertiary-dark',
-        tooltipText: 'render'
-      },
-      () => {
-        const stage = gameDisplay?.stage;
-        const view = stage?.getGameViewRect?.();
-        let minX = -Infinity;
-        let maxX = Infinity;
-        let minY = -Infinity;
-        let maxY = Infinity;
-        if (view) {
-          const pad = 16;
-          minX = view.x - pad;
-          maxX = view.x + view.w + pad;
-          minY = view.y - pad;
-          maxY = view.y + view.h + pad;
-        }
-        for (const lem of this.activeLemmings) {
-          if (lem.removed) continue;
-          if (lem.x < minX || lem.x > maxX || lem.y < minY || lem.y > maxY) continue;
-          lem.render(gameDisplay);
-        }
-      })();
-  }
-
-  renderDebug(gameDisplay) {
-    const stage = gameDisplay?.stage;
-    const view = stage?.getGameViewRect?.();
-    let minX = -Infinity;
-    let maxX = Infinity;
-    let minY = -Infinity;
-    let maxY = Infinity;
-    if (view) {
-      const pad = 16;
-      minX = view.x - pad;
-      maxX = view.x + view.w + pad;
-      minY = view.y - pad;
-      maxY = view.y + view.h + pad;
-    }
-    for (const lem of this.activeLemmings) {
-      if (lem.removed) continue;
-      if (lem.x < minX || lem.x > maxX || lem.y < minY || lem.y > maxY) continue;
-      lem.renderDebug(gameDisplay);
-    }
-  }
-
-  getLemming(id) {
-    return this.lemmings[id] ?? null;
-  }
-
-  getSelectedLemming() {
-    const lem = this.getLemming(this.selectedIndex);
-    if (!lem || lem.removed || lem.disabled) return null;
-    return lem;
-  }
-
-  setSelectedLemming(lem) {
-    this.selectedIndex = lem?.id ?? -1;
-  }
-
-  getLemmings() {
-    return this.activeLemmings;
-  }
-
-  getLemmingAt(x, y, radius = 6) {
-    return this.getNearestLemming(x, y);
-  }
-
-  getNearestLemming(x, y) {
-    let best = null;
-    let bestDist = Infinity;
-    for (const lem of this.activeLemmings) {
-      if (lem.removed) continue;
-      const dist = lem.getClickDistance(x, y);
-      if (dist >= 0 && dist < bestDist) {
-        bestDist = dist;
-        best = lem;
-      }
-    }
-    return best;
-  }
-
-  getLemmingsInMask(mask, x, y) {
-    const out = [];
-    const lems = this.activeLemmings;
-    const left = x + mask.offsetX;
-    const right = left + mask.width;
-    const top = y + mask.offsetY;
-    const bottom = top + mask.height;
-    for (const val of lems) {
-      if (val.removed) continue;
-      const lx = val.x;
-      const ly = val.y;
-      if (lx > left && lx < right && ly > top && ly < bottom) out.push(val);
-    }
-    return out;
-  }
-
-  setLemmingState(lem, stateType) {
-    withPerformance(
-      'setLemmingState',
-      {
-        track: 'LemmingManager',
-        trackGroup: 'Game State',
-        color: 'secondary-light',
-        tooltipText: `setLemmingState ${lem.id}`
-      },
-      () => {
-        if (lem.countdown > 0) {
-          const lethal =
-                stateType === LemmingStateType.DROWNING   ||
-                stateType === LemmingStateType.SPLATTING  ||
-                stateType === LemmingStateType.FRYING;
-          if (lethal) {
-            lem.countdown = 0;
-            lem.countdownAction = null;
-          }
-        }
-        if (stateType == LemmingStateType.OUT_OF_LEVEL) {
-          withPerformance(
-            'removeOne',
-            {
-              track: 'LemmingManager',
-              trackGroup: 'Game State',
-              color: 'secondary-dark',
-              tooltipText: `removeOne ${lem.id}`
-            },
-            () => {
-              this.removeOne(lem);
-            }
-          )();
-          return;
-        }
-        const actionSystem = this.actions[stateType];
-        if (!actionSystem) {
-          this.removeOne(lem);
-          this.logging.log(lem.id + ' Action: Error not an action: ' + LemmingStateType[stateType]);
-          return;
-        } else {
-          if (this.activeLemmings.length <= 50 && (lemmings?.gameSpeedFactor ?? 1) <= 1) {
-            this.logging.debug(lem.id + ' Action: ' + actionSystem.getActionName());
-          }
-        }
-        if (stateType === LemmingStateType.EXPLODING) {
-          lem.hasExploded = true;
-        }
-        lem.setAction(actionSystem);
-      })();
-  }
-
-  doLemmingAction(lem, skillType) {
-    return withPerformance(
-      'doLemmingAction',
-      {
-        track: 'LemmingManager',
-        trackGroup: 'Game State',
-        color: 'secondary-dark',
-        tooltipText: `doLemmingAction ${skillType}`
-      },
-      () => {
-        if (!lem) {
-          return false;
-        }
-        const actionSystem = this.skillActions[skillType];
-        if (!actionSystem) {
-          this.logging.log(lem.id + ' Unknown Action: ' + skillType);
-          return false;
-        }
-        const canApplyWhileFalling = {
-          [SkillTypes.FLOATER]: this._actionTypes?.floater,
-          [SkillTypes.CLIMBER]: this._actionTypes?.climber,
-          [SkillTypes.BOMBER]: this.skillActions[SkillTypes.BOMBER],
-          [SkillTypes.BUILDER]: this._actionTypes?.builder
-        };
-        if (lem.action == this.actions[LemmingStateType.FALLING]) {
-          if (!canApplyWhileFalling[skillType]) {
-            return false;
-          }
-        }
-        const redundant = {
-          [SkillTypes.BASHER]: this._actionTypes?.basher,
-          [SkillTypes.BLOCKER]: this._actionTypes?.blocker,
-          [SkillTypes.DIGGER]: this._actionTypes?.digger,
-          [SkillTypes.MINER]: this._actionTypes?.miner
-        };
-        const alreadyDoingIt =
-            redundant[skillType] && (lem.action instanceof redundant[skillType]);
-        if (alreadyDoingIt) {
-          return false;
-        }
-        const wasBlocking = this._actionTypes?.blocker
-          ? (lem.action instanceof this._actionTypes.blocker)
-          : false;
-        const ok = actionSystem.triggerLemAction(lem);
-        if (ok && wasBlocking) {
-          const keepWall =
-                skillType === SkillTypes.BOMBER ||
-                skillType === SkillTypes.CLIMBER ||
-                skillType === SkillTypes.FLOATER;
-          if (!keepWall) {
-            this.triggerManager.removeByOwner(lem);
-          }
-        }
-        const result = ok;
-        return result;
-      }).call(this);
-  }
-
-  isNuking() { return this.nextNukingLemmingsIndex >= 0; }
-  doNukeAllLemmings() {
-    const targets = this.activeLemmings.filter(lem => lem && !lem.removed && !lem.disabled);
-    this._nukeTargets = targets;
-    this.nextNukingLemmingsIndex = targets.length ? 0 : -1;
-  }
-
-  _nukeNextLemming() {
-    const lems = this._nukeTargets || [];
-    const count = lems.length;
-    if (count <= 0) return;
-    if (this.nextNukingLemmingsIndex >= count) {
-      this.nextNukingLemmingsIndex = -1;
-      this._nukeTargets = null;
-      return;
-    }
-    let attempts = 0;
-    while (attempts < count && this.nextNukingLemmingsIndex >= 0) {
-      const idx = this.nextNukingLemmingsIndex;
-      if (idx >= count) {
-        this.nextNukingLemmingsIndex = -1;
-        this._nukeTargets = null;
-        return;
-      }
-      const lem = lems[idx];
-      let applied = false;
-      if (lem && !lem.removed && !lem.disabled) {
-        applied = this.doLemmingAction(lem, SkillTypes.BOMBER);
-      }
-      if (idx + 1 >= count) {
-        this.nextNukingLemmingsIndex = -1;
-        this._nukeTargets = null;
-      } else {
-        this.nextNukingLemmingsIndex = idx + 1;
-      }
-      if (applied) break;
-      attempts++;
-    }
-  }
-
-  removeOne(lem) {
-    if (this.miniMap &&
-            lem.action !== this.actions[LemmingStateType.EXITING]) {
-      this.miniMap.addDeath(lem.x, lem.y);
-    }
-    const lemId = lem.id;
-    lem.remove();
-    if (lemId !== null && lemId !== undefined) this.lemmings[lemId] = null;
-    this._activeDirty = true;
-    this.gameVictoryCondition.removeOne();
-  }
-
-  cycleSelection(dir = 1) {
-    const lems = this.activeLemmings;
-    if (!lems?.length) return null;
-    const total = lems.length;
-    const current = this.getSelectedLemming();
-    let idx = current?._activeIndex ?? 0;
-    for (let i = 0; i < total; i++) {
-      idx = (idx + dir + total) % total;
-      const lem = lems[idx];
-      if (!lem.removed && !lem.disabled) {
-        this.setSelectedLemming(lem);
-        return lem;
-      }
-    }
-    this.selectedIndex = -1;
-    return null;
-  }
-
-  dispose() {
-    const start = performance.now();
-    if (this.lemmings) this.lemmings.length = 0;
-    if (this.activeLemmings) this.activeLemmings.length = 0;
-    if (this.minimapDots) this.minimapDots = new Uint8Array(0);
-    this._minimapDotBuffer = null;
-    this._mmVisited = null;
-    this.level = null;
-    this.triggerManager = null;
-    this.gameVictoryCondition = null;
-    this.skillActions.length = 0;
-    this.#releaseTickIndex = null;
-    const Handler = getDependency('LogHandler', LogHandler);
-    this.logging = new Handler('LemmingManager');
-    this.miniMap = null;
-    this.#mmTickCounter = null;
-    this.nextNukingLemmingsIndex = null;
-    this._nukeTargets = null;
-    this.selectedIndex = null;
-    if (typeof lemmings !== 'undefined' &&
-            (lemmings.performanceAPI === true || lemmings.perfMetrics === true) &&
-            typeof performance !== 'undefined' &&
-            typeof performance.measure === 'function') {
-      performance.measure('LemmingManager Dispose', {
-        start,
-        detail: {
-          devtools: {
-            track: 'LemmingManager',
-            trackGroup: 'Game State',
-            color: 'error',
-            tooltipText: 'LemmingManager Dispose'
-          }
-        }
-      });
-    }
-  }
-}
-
-export { LemmingManager };
+export { LemmingManager } from './lemming-manager/LemmingManagerCore.js';
diff --git a/js/lemmings/lemming-manager/LemmingManagerCore.js b/js/lemmings/lemming-manager/LemmingManagerCore.js
new file mode 100644
index 00000000..1f0d7097
--- /dev/null
+++ b/js/lemmings/lemming-manager/LemmingManagerCore.js
@@ -0,0 +1,262 @@
+import {
+  ActionBashSystem,
+  ActionBlockerSystem,
+  ActionBuildSystem,
+  ActionClimbSystem,
+  ActionCountdownSystem,
+  ActionDiggSystem,
+  ActionDrowningSystem,
+  ActionExitingSystem,
+  ActionExplodingSystem,
+  ActionFallSystem,
+  ActionFloatingSystem,
+  ActionFryingSystem,
+  ActionHoistSystem,
+  ActionJumpSystem,
+  ActionMineSystem,
+  ActionOhNoSystem,
+  ActionShrugSystem,
+  ActionSplatterSystem,
+  ActionWalkSystem,
+  BaseLogger,
+  COUNTER_LIMIT,
+  Lemming,
+  LemmingStateType,
+  LogHandler,
+  RENDER_MEASURE_DETAIL,
+  SkillTypes,
+  SoundEffectIds,
+  SoundEventTypes,
+  TICK_MEASURE_DETAIL,
+  TriggerTypes,
+  canMeasurePerformance,
+  getApp,
+  getAppContext,
+  getDependency,
+  getRuntimeSoundEvents,
+  isBenchMode,
+  recordPerformanceMeasure
+} from './LemmingManagerShared.js';
+import { lemmingManagerSpawningMethods } from './LemmingManagerSpawning.js';
+import { lemmingManagerInteractionMethods } from './LemmingManagerInteraction.js';
+class LemmingManager extends BaseLogger {
+  #mmTickCounter = 0;
+
+  #releaseTickIndex = 0;
+
+  constructor(level, lemmingsSprite, triggerManager, gameVictoryCondition, masks, particleTable, runtime = null) {
+    super();
+    const endMeasure = this.startMeasure('LemmingManager constructor', {
+      track: 'LemmingManager',
+      trackGroup: 'Game State',
+      color: 'primary',
+      tooltipText: 'LemmingManager constructor'
+    });
+    const app = getApp();
+    try {
+      if (!isBenchMode(app) && (app?.extraLemmings | 0) === 0) {
+        this.lemmings = new Array(gameVictoryCondition.getReleaseCount());
+        this.lemmings.length = 0;
+      } else {
+        this.lemmings = [];
+      }
+      this.activeLemmings = [];
+      this._activeDirty = false;
+      this.minimapDots = new Uint8Array(0);
+      this.spawnTotal = 0;
+      this.selectedIndex = -1;
+      const maxDots = (gameVictoryCondition.getReleaseCount() +
+            (app?.extraLemmings | 0)) * 2;
+      this._minimapDotBuffer = new Uint8Array(maxDots);
+      this.minimapDots = this._minimapDotBuffer.subarray(0, 0);
+      this._mmVisited = new Uint16Array(65536);
+      this._mmVisitStamp = 1;
+      this._selectedMiniMapDot = [0, 0];
+      if (!LemmingManager.log) {
+        LemmingManager.log = this.log;
+      }
+      this.level = level;
+      this.runtime = runtime;
+      this.triggerManager = triggerManager;
+      this.gameVictoryCondition = gameVictoryCondition;
+      this.actions = [];
+      this.skillActions = [];
+      this.logging = LemmingManager.log;
+      this.miniMap = null;
+      this.nextNukingLemmingsIndex = -1;
+      this._nukeTargets = null;
+      this._nukeScratch = [];
+      this._nearestCellShift = 4;
+      this._nearestGrid = new Map();
+      this._nearestGridPool = [];
+      this._nearestGridDirty = true;
+      this._lemmingPool = [];
+      const releaseCount = Math.max(1, gameVictoryCondition.getReleaseCount() || 0);
+      this._maxLemmingPoolSize = Math.max(64, releaseCount * 4);
+
+      const WalkSystem = getDependency('ActionWalkSystem', ActionWalkSystem);
+      const FallSystem = getDependency('ActionFallSystem', ActionFallSystem);
+      const JumpSystem = getDependency('ActionJumpSystem', ActionJumpSystem);
+      const DiggSystem = getDependency('ActionDiggSystem', ActionDiggSystem);
+      const ExitSystem = getDependency('ActionExitingSystem', ActionExitingSystem);
+      const FloatSystem = getDependency('ActionFloatingSystem', ActionFloatingSystem);
+      const BlockSystem = getDependency('ActionBlockerSystem', ActionBlockerSystem);
+      const MineSystem = getDependency('ActionMineSystem', ActionMineSystem);
+      const ClimbSystem = getDependency('ActionClimbSystem', ActionClimbSystem);
+      const HoistSystem = getDependency('ActionHoistSystem', ActionHoistSystem);
+      const BashSystem = getDependency('ActionBashSystem', ActionBashSystem);
+      const BuildSystem = getDependency('ActionBuildSystem', ActionBuildSystem);
+      const ShrugSystem = getDependency('ActionShrugSystem', ActionShrugSystem);
+      const ExplodeSystem = getDependency('ActionExplodingSystem', ActionExplodingSystem);
+      const OhNoSystem = getDependency('ActionOhNoSystem', ActionOhNoSystem);
+      const SplatterSystem = getDependency('ActionSplatterSystem', ActionSplatterSystem);
+      const DrownSystem = getDependency('ActionDrowningSystem', ActionDrowningSystem);
+      const FrySystem = getDependency('ActionFryingSystem', ActionFryingSystem);
+      const CountdownSystem = getDependency('ActionCountdownSystem', ActionCountdownSystem);
+
+      this.actions[LemmingStateType.WALKING]    = new WalkSystem(lemmingsSprite);
+      this.actions[LemmingStateType.FALLING]    = new FallSystem(lemmingsSprite);
+      this.actions[LemmingStateType.JUMPING]    = new JumpSystem(lemmingsSprite);
+      this.actions[LemmingStateType.DIGGING]    = new DiggSystem(lemmingsSprite);
+      this.actions[LemmingStateType.EXITING]    = new ExitSystem(lemmingsSprite, gameVictoryCondition);
+      this.actions[LemmingStateType.FLOATING]   = new FloatSystem(lemmingsSprite);
+      this.actions[LemmingStateType.BLOCKING]   = new BlockSystem(lemmingsSprite, triggerManager);
+      this.actions[LemmingStateType.MINING]     = new MineSystem(lemmingsSprite, masks);
+      this.actions[LemmingStateType.CLIMBING]   = new ClimbSystem(lemmingsSprite);
+      this.actions[LemmingStateType.HOISTING]   = new HoistSystem(lemmingsSprite);
+      this.actions[LemmingStateType.BASHING]    = new BashSystem(lemmingsSprite, masks);
+      this.actions[LemmingStateType.BUILDING]   = new BuildSystem(lemmingsSprite);
+      this.actions[LemmingStateType.SHRUG]      = new ShrugSystem(lemmingsSprite);
+      this.actions[LemmingStateType.EXPLODING]  = new ExplodeSystem(lemmingsSprite, masks, triggerManager, particleTable);
+      this.actions[LemmingStateType.OHNO]       = new OhNoSystem(lemmingsSprite);
+      this.actions[LemmingStateType.SPLATTING]  = new SplatterSystem(lemmingsSprite);
+      this.actions[LemmingStateType.DROWNING]   = new DrownSystem(lemmingsSprite);
+      this.actions[LemmingStateType.FRYING]     = new FrySystem(lemmingsSprite);
+
+      this.skillActions[SkillTypes.DIGGER]  = this.actions[LemmingStateType.DIGGING];
+      this.skillActions[SkillTypes.FLOATER] = this.actions[LemmingStateType.FLOATING];
+      this.skillActions[SkillTypes.BLOCKER] = this.actions[LemmingStateType.BLOCKING];
+      this.skillActions[SkillTypes.MINER]   = this.actions[LemmingStateType.MINING];
+      this.skillActions[SkillTypes.CLIMBER] = this.actions[LemmingStateType.CLIMBING];
+      this.skillActions[SkillTypes.BASHER]  = this.actions[LemmingStateType.BASHING];
+      this.skillActions[SkillTypes.BUILDER] = this.actions[LemmingStateType.BUILDING];
+      this.skillActions[SkillTypes.BOMBER]  = new CountdownSystem(masks);
+      this.countdownAction = this.skillActions[SkillTypes.BOMBER];
+      for (const action of this.actions) {
+        action?.setRuntime?.(runtime);
+      }
+      this.countdownAction?.setRuntime?.(runtime);
+
+      this.actionTypeByAction = new Map();
+      for (let i = 0; i < this.actions.length; i++) {
+        const action = this.actions[i];
+        if (action) this.actionTypeByAction.set(action, i);
+      }
+
+      this._actionTypes = {
+        blocker: BlockSystem,
+        basher: BashSystem,
+        builder: BuildSystem,
+        climber: ClimbSystem,
+        digger: DiggSystem,
+        floater: FloatSystem,
+        miner: MineSystem
+      };
+      const maxSkillType = SkillTypes.DIGGER;
+      this._canApplyWhileFalling = new Uint8Array(maxSkillType + 1);
+      this._canApplyWhileFalling[SkillTypes.FLOATER] = 1;
+      this._canApplyWhileFalling[SkillTypes.CLIMBER] = 1;
+      this._canApplyWhileFalling[SkillTypes.BOMBER] = 1;
+      this._canApplyWhileFalling[SkillTypes.BUILDER] = 1;
+      this._redundantActionBySkill = new Array(maxSkillType + 1);
+      this._redundantActionBySkill[SkillTypes.BASHER] = this._actionTypes.basher;
+      this._redundantActionBySkill[SkillTypes.BLOCKER] = this._actionTypes.blocker;
+      this._redundantActionBySkill[SkillTypes.DIGGER] = this._actionTypes.digger;
+      this._redundantActionBySkill[SkillTypes.MINER] = this._actionTypes.miner;
+      this._keepBlockerWallBySkill = new Uint8Array(maxSkillType + 1);
+      this._keepBlockerWallBySkill[SkillTypes.BOMBER] = 1;
+      this._keepBlockerWallBySkill[SkillTypes.CLIMBER] = 1;
+      this._keepBlockerWallBySkill[SkillTypes.FLOATER] = 1;
+      this._lemmingCtor = getDependency('Lemming', Lemming);
+
+      this.releaseTickIndex = this.gameVictoryCondition.getCurrentReleaseRate() - 30;
+    } finally {
+      endMeasure();
+    }
+  }
+
+  get mmTickCounter() { return this.#mmTickCounter; }
+
+  set mmTickCounter(v) {
+    if (v >= COUNTER_LIMIT) {
+      console.warn('mmTickCounter wrapped, resetting to 0');
+      this.#mmTickCounter = 0;
+    } else {
+      this.#mmTickCounter = v;
+    }
+  }
+
+  get releaseTickIndex() { return this.#releaseTickIndex; }
+
+  set releaseTickIndex(v) {
+    if (v >= COUNTER_LIMIT) {
+      console.warn('releaseTickIndex wrapped, resetting to 0');
+      this.#releaseTickIndex = 0;
+    } else {
+      this.#releaseTickIndex = v;
+    }
+  }
+
+  dispose() {
+    const app = getApp();
+    const perfEnabled = !!app &&
+        (app.performanceAPI === true || app.perfMetrics === true) &&
+        canMeasurePerformance();
+    const start = perfEnabled ? performance.now() : 0;
+    if (this.lemmings) this.lemmings.length = 0;
+    if (this.activeLemmings) this.activeLemmings.length = 0;
+    if (this.minimapDots) this.minimapDots = new Uint8Array(0);
+    this._minimapDotBuffer = null;
+    this._mmVisited = null;
+    this._mmVisitStamp = null;
+    this.level = null;
+    this.runtime = null;
+    this.triggerManager = null;
+    this.gameVictoryCondition = null;
+    this.skillActions.length = 0;
+    this.#releaseTickIndex = null;
+    const Handler = getDependency('LogHandler', LogHandler);
+    this.logging = new Handler('LemmingManager');
+    this.miniMap = null;
+    this.#mmTickCounter = null;
+    this.nextNukingLemmingsIndex = null;
+    this._nukeTargets = null;
+    this._nukeScratch = null;
+    this._nearestGrid = null;
+    this._nearestGridPool = null;
+    if (this._lemmingPool) this._lemmingPool.length = 0;
+    this._lemmingPool = null;
+    this._maxLemmingPoolSize = null;
+    this.selectedIndex = null;
+    if (perfEnabled) {
+      recordPerformanceMeasure('LemmingManager Dispose', {
+        start,
+        detail: {
+          devtools: {
+            track: 'LemmingManager',
+            trackGroup: 'Game State',
+            color: 'error',
+            tooltipText: 'LemmingManager Dispose'
+          }
+        }
+      });
+    }
+  }
+}
+for (const methods of [
+  lemmingManagerSpawningMethods,
+  lemmingManagerInteractionMethods
+]) {
+  Object.defineProperties(LemmingManager.prototype, Object.getOwnPropertyDescriptors(methods));
+}
+export { LemmingManager };
\ No newline at end of file
diff --git a/js/lemmings/lemming-manager/LemmingManagerInteraction.js b/js/lemmings/lemming-manager/LemmingManagerInteraction.js
new file mode 100644
index 00000000..5349a815
--- /dev/null
+++ b/js/lemmings/lemming-manager/LemmingManagerInteraction.js
@@ -0,0 +1,357 @@
+import {
+  ActionBashSystem,
+  ActionBlockerSystem,
+  ActionBuildSystem,
+  ActionClimbSystem,
+  ActionCountdownSystem,
+  ActionDiggSystem,
+  ActionDrowningSystem,
+  ActionExitingSystem,
+  ActionExplodingSystem,
+  ActionFallSystem,
+  ActionFloatingSystem,
+  ActionFryingSystem,
+  ActionHoistSystem,
+  ActionJumpSystem,
+  ActionMineSystem,
+  ActionOhNoSystem,
+  ActionShrugSystem,
+  ActionSplatterSystem,
+  ActionWalkSystem,
+  BaseLogger,
+  COUNTER_LIMIT,
+  Lemming,
+  LemmingStateType,
+  LogHandler,
+  RENDER_MEASURE_DETAIL,
+  SkillTypes,
+  SoundEffectIds,
+  SoundEventTypes,
+  TICK_MEASURE_DETAIL,
+  TriggerTypes,
+  canMeasurePerformance,
+  getApp,
+  getAppContext,
+  getDependency,
+  getRuntimeSoundEvents,
+  isBenchMode,
+  recordPerformanceMeasure
+} from './LemmingManagerShared.js';
+const lemmingManagerInteractionMethods = {
+  runTrigger(lem, tickOverride = null) {
+    if (lem.isRemoved() || lem.isDisabled()) {
+      // this.lemmings.splice(this.lemmings.indexOf(lem), 1);
+      return LemmingStateType.NO_STATE_TYPE;
+    }
+    const triggerType = this.triggerManager.trigger(lem.x, lem.y, lem, tickOverride);
+    switch (triggerType) {
+    case TriggerTypes.NO_TRIGGER:
+    case TriggerTypes.DISABLED:
+      return LemmingStateType.NO_STATE_TYPE;
+    case TriggerTypes.DROWN:
+      lem.lastTriggerType = triggerType;
+      return LemmingStateType.DROWNING;
+    case TriggerTypes.EXIT_LEVEL:
+      lem.lastTriggerType = triggerType;
+      return LemmingStateType.EXITING;
+    case TriggerTypes.KILL:
+      lem.lastTriggerType = triggerType;
+      return LemmingStateType.SPLATTING;
+    case TriggerTypes.FRYING:
+      lem.lastTriggerType = triggerType;
+      return LemmingStateType.FRYING;
+    case TriggerTypes.UNKNOWN_2:
+    case TriggerTypes.UNKNOWN_3:
+    case TriggerTypes.TRAP:
+      lem.lastTriggerType = triggerType;
+      return LemmingStateType.SPLATTING;
+    case TriggerTypes.BLOCKER_LEFT:
+      if (lem.lookRight) lem.lookRight = false;
+      return LemmingStateType.NO_STATE_TYPE;
+    case TriggerTypes.BLOCKER_RIGHT:
+      if (!lem.lookRight) lem.lookRight = true;
+      return LemmingStateType.NO_STATE_TYPE;
+    default:
+      this.logging.log('unknown trigger type: ' + triggerType);
+      return LemmingStateType.NO_STATE_TYPE;
+    }
+  },
+
+  render(gameDisplay) {
+    const app = getApp();
+    const perfEnabled = !!app &&
+        (app.performanceAPI === true || app.perfMetrics === true) &&
+        canMeasurePerformance();
+    const perfStart = perfEnabled ? performance.now() : 0;
+    try {
+      const stage = gameDisplay?.stage;
+      const view = stage?.getGameViewRect?.();
+      let minX = -Infinity;
+      let maxX = Infinity;
+      let minY = -Infinity;
+      let maxY = Infinity;
+      if (view) {
+        const pad = 16;
+        minX = view.x - pad;
+        maxX = view.x + view.w + pad;
+        minY = view.y - pad;
+        maxY = view.y + view.h + pad;
+      }
+      const lems = this.activeLemmings;
+      for (let i = 0; i < lems.length; i += 1) {
+        const lem = lems[i];
+        if (lem.removed) continue;
+        if (lem.x < minX || lem.x > maxX || lem.y < minY || lem.y > maxY) continue;
+        lem.render(gameDisplay);
+      }
+    } finally {
+      if (perfEnabled) {
+        recordPerformanceMeasure('render', {
+          start: perfStart,
+          detail: RENDER_MEASURE_DETAIL
+        });
+      }
+    }
+  },
+
+  renderDebug(gameDisplay) {
+    const stage = gameDisplay?.stage;
+    const view = stage?.getGameViewRect?.();
+    let minX = -Infinity;
+    let maxX = Infinity;
+    let minY = -Infinity;
+    let maxY = Infinity;
+    if (view) {
+      const pad = 16;
+      minX = view.x - pad;
+      maxX = view.x + view.w + pad;
+      minY = view.y - pad;
+      maxY = view.y + view.h + pad;
+    }
+    const lems = this.activeLemmings;
+    for (let i = 0; i < lems.length; i += 1) {
+      const lem = lems[i];
+      if (lem.removed) continue;
+      if (lem.x < minX || lem.x > maxX || lem.y < minY || lem.y > maxY) continue;
+      lem.renderDebug(gameDisplay);
+    }
+  },
+
+  getLemming(id) {
+    return this.lemmings[id] ?? null;
+  },
+
+  getSelectedLemming() {
+    const lem = this.getLemming(this.selectedIndex);
+    if (!lem || lem.removed || lem.disabled) return null;
+    return lem;
+  },
+
+  setSelectedLemming(lem) {
+    this.selectedIndex = lem?.id ?? -1;
+  },
+
+  getLemmings() {
+    return this.activeLemmings;
+  },
+
+  getLemmingAt(x, y, radius = 6) {
+    return this.getNearestLemming(x, y);
+  },
+
+  getNearestLemming(x, y) {
+    this._rebuildNearestGrid();
+    const shift = this._nearestCellShift;
+    const cx = x >> shift;
+    const cy = y >> shift;
+
+    let best = null;
+    let bestDist = Infinity;
+    for (let dy = -1; dy <= 1; dy += 1) {
+      for (let dx = -1; dx <= 1; dx += 1) {
+        const key = this._nearestCellKey(cx + dx, cy + dy);
+        const bucket = this._nearestGrid.get(key);
+        if (!bucket?.length) continue;
+        ({ best, bestDist } = this._findNearestInBucket(bucket, x, y, best, bestDist));
+      }
+    }
+    if (best) return best;
+
+    const lems = this.activeLemmings;
+    for (let i = 0; i < lems.length; i += 1) {
+      const lem = lems[i];
+      if (!lem || lem.removed) continue;
+      const dist = lem.getClickDistance(x, y);
+      if (dist >= 0 && dist < bestDist) {
+        bestDist = dist;
+        best = lem;
+      }
+    }
+    return best;
+  },
+
+  getLemmingsInMask(mask, x, y) {
+    const out = [];
+    const lems = this.activeLemmings;
+    const left = x + mask.offsetX;
+    const right = left + mask.width;
+    const top = y + mask.offsetY;
+    const bottom = top + mask.height;
+    for (let i = 0; i < lems.length; i += 1) {
+      const val = lems[i];
+      if (val.removed) continue;
+      const lx = val.x;
+      const ly = val.y;
+      if (lx > left && lx < right && ly > top && ly < bottom) out.push(val);
+    }
+    return out;
+  },
+
+  setLemmingState(lem, stateType) {
+    if (lem.countdown > 0) {
+      const lethal =
+              stateType === LemmingStateType.DROWNING   ||
+              stateType === LemmingStateType.SPLATTING  ||
+              stateType === LemmingStateType.FRYING;
+      if (lethal) {
+        lem.countdown = 0;
+        lem.countdownAction = null;
+      }
+    }
+    if (stateType === LemmingStateType.OUT_OF_LEVEL) {
+      this.removeOne(lem);
+      return;
+    }
+    const actionSystem = this.actions[stateType];
+    if (!actionSystem) {
+      this.removeOne(lem);
+      this.logging.log(lem.id + ' Action: Error not an action: ' + LemmingStateType[stateType]);
+      return;
+    } else {
+      const app = getApp();
+      if (this.activeLemmings.length <= 50 && (app?.gameSpeedFactor ?? 1) <= 1) {
+        this.logging.debug(lem.id + ' Action: ' + actionSystem.getActionName());
+      }
+    }
+    if (stateType === LemmingStateType.EXPLODING) {
+      lem.hasExploded = true;
+    }
+    lem.setAction(actionSystem);
+  },
+
+  doLemmingAction(lem, skillType) {
+    if (!lem) {
+      return false;
+    }
+    const actionSystem = this.skillActions[skillType];
+    if (!actionSystem) {
+      this.logging.log(lem.id + ' Unknown Action: ' + skillType);
+      return false;
+    }
+    if (lem.action === this.actions[LemmingStateType.FALLING]) {
+      if (!this._canApplyWhileFalling?.[skillType]) {
+        return false;
+      }
+    }
+    const redundant = this._redundantActionBySkill?.[skillType] ?? null;
+    const alreadyDoingIt =
+          redundant && (lem.action instanceof redundant);
+    if (alreadyDoingIt) {
+      return false;
+    }
+    const wasBlocking = this._actionTypes?.blocker
+      ? (lem.action instanceof this._actionTypes.blocker)
+      : false;
+    const ok = actionSystem.triggerLemAction(lem);
+    if (ok && wasBlocking) {
+      if (!this._keepBlockerWallBySkill?.[skillType]) {
+        this.triggerManager.removeByOwner(lem);
+      }
+    }
+    return ok;
+  },
+
+  isNuking() { return this.nextNukingLemmingsIndex >= 0; },
+
+  doNukeAllLemmings() {
+    const scratch = this._nukeScratch;
+    let count = 0;
+    const lems = this.activeLemmings;
+    for (let i = 0; i < lems.length; i += 1) {
+      const lem = lems[i];
+      if (!lem || lem.removed || lem.disabled) continue;
+      scratch[count] = lem;
+      count += 1;
+    }
+    scratch.length = count;
+    this._nukeTargets = scratch;
+    this.nextNukingLemmingsIndex = count ? 0 : -1;
+  },
+
+  _nukeNextLemming() {
+    const lems = this._nukeTargets || [];
+    const count = lems.length;
+    if (count <= 0) return;
+    if (this.nextNukingLemmingsIndex >= count) {
+      this.nextNukingLemmingsIndex = -1;
+      this._nukeTargets = null;
+      return;
+    }
+    let attempts = 0;
+    while (attempts < count && this.nextNukingLemmingsIndex >= 0) {
+      const idx = this.nextNukingLemmingsIndex;
+      if (idx >= count) {
+        this.nextNukingLemmingsIndex = -1;
+        this._nukeTargets = null;
+        return;
+      }
+      const lem = lems[idx];
+      let applied = false;
+      if (lem && !lem.removed && !lem.disabled) {
+        applied = this.doLemmingAction(lem, SkillTypes.BOMBER);
+      }
+      if (idx + 1 >= count) {
+        this.nextNukingLemmingsIndex = -1;
+        this._nukeTargets = null;
+      } else {
+        this.nextNukingLemmingsIndex = idx + 1;
+      }
+      if (applied) break;
+      attempts++;
+    }
+  },
+
+  removeOne(lem) {
+    if (!lem || lem.removed) return;
+    if (this.miniMap &&
+              lem.action !== this.actions[LemmingStateType.EXITING]) {
+      this.miniMap.addDeath(lem.x, lem.y);
+    }
+    const lemId = lem.id;
+    lem.remove();
+    this._releaseLemming(lem);
+    if (lemId !== null && lemId !== undefined) this.lemmings[lemId] = null;
+    this._activeDirty = true;
+    this._nearestGridDirty = true;
+    this.gameVictoryCondition.removeOne();
+  },
+
+  cycleSelection(dir = 1) {
+    const lems = this.activeLemmings;
+    if (!lems?.length) return null;
+    const total = lems.length;
+    const current = this.getSelectedLemming();
+    let idx = current?._activeIndex ?? 0;
+    for (let i = 0; i < total; i++) {
+      idx = (idx + dir + total) % total;
+      const lem = lems[idx];
+      if (!lem.removed && !lem.disabled) {
+        this.setSelectedLemming(lem);
+        return lem;
+      }
+    }
+    this.selectedIndex = -1;
+    return null;
+  }
+};
+export { lemmingManagerInteractionMethods };
\ No newline at end of file
diff --git a/js/lemmings/lemming-manager/LemmingManagerShared.js b/js/lemmings/lemming-manager/LemmingManagerShared.js
new file mode 100644
index 00000000..a85054d7
--- /dev/null
+++ b/js/lemmings/lemming-manager/LemmingManagerShared.js
@@ -0,0 +1,91 @@
+import { COUNTER_LIMIT } from '../../core/constants.js';
+import { SoundEventTypes, SoundEffectIds } from '../../game/SoundEvents.js';
+import { ActionBashSystem } from '../../actions/ActionBashSystem.js';
+import { ActionBlockerSystem } from '../../actions/ActionBlockerSystem.js';
+import { ActionBuildSystem } from '../../actions/ActionBuildSystem.js';
+import { ActionClimbSystem } from '../../actions/ActionClimbSystem.js';
+import { ActionCountdownSystem } from '../../actions/ActionCountdownSystem.js';
+import { ActionDiggSystem } from '../../actions/ActionDiggSystem.js';
+import { ActionDrowningSystem } from '../../actions/ActionDrowningSystem.js';
+import { ActionExitingSystem } from '../../actions/ActionExitingSystem.js';
+import { ActionExplodingSystem } from '../../actions/ActionExplodingSystem.js';
+import { ActionFallSystem } from '../../actions/ActionFallSystem.js';
+import { ActionFloatingSystem } from '../../actions/ActionFloatingSystem.js';
+import { ActionFryingSystem } from '../../actions/ActionFryingSystem.js';
+import { ActionHoistSystem } from '../../actions/ActionHoistSystem.js';
+import { ActionJumpSystem } from '../../actions/ActionJumpSystem.js';
+import { ActionMineSystem } from '../../actions/ActionMineSystem.js';
+import { ActionOhNoSystem } from '../../actions/ActionOhNoSystem.js';
+import { ActionShrugSystem } from '../../actions/ActionShrugSystem.js';
+import { ActionSplatterSystem } from '../../actions/ActionSplatterSystem.js';
+import { ActionWalkSystem } from '../../actions/ActionWalkSystem.js';
+import { Lemming } from '../Lemming.js';
+import { LemmingStateType } from '../LemmingStateType.js';
+import { BaseLogger, LogHandler } from '../../util/LogHandler.js';
+import { SkillTypes } from '../../game/SkillTypes.js';
+import { TriggerTypes } from '../../level/TriggerTypes.js';
+import { getAppContext, getDependency } from '../../core/dependencies.js';
+import { getRuntimeSoundEvents } from '../../game/GameRuntime.js';
+import {
+  canMeasurePerformance,
+  recordPerformanceMeasure
+} from '../../util/performanceInstrumentation.js';
+
+const TICK_MEASURE_DETAIL = Object.freeze({
+  devtools: Object.freeze({
+    track: 'LemmingManager',
+    trackGroup: 'Game State',
+    color: 'tertiary-dark',
+    tooltipText: 'tick'
+  })
+});
+const RENDER_MEASURE_DETAIL = Object.freeze({
+  devtools: Object.freeze({
+    track: 'LemmingManager',
+    trackGroup: 'Render',
+    color: 'tertiary-dark',
+    tooltipText: 'render'
+  })
+});
+const getApp = () => getAppContext();
+const isBenchMode = (app) => app?.bench || app?.bench2 || app?.benchReverse;
+
+export {
+  ActionBashSystem,
+  ActionBlockerSystem,
+  ActionBuildSystem,
+  ActionClimbSystem,
+  ActionCountdownSystem,
+  ActionDiggSystem,
+  ActionDrowningSystem,
+  ActionExitingSystem,
+  ActionExplodingSystem,
+  ActionFallSystem,
+  ActionFloatingSystem,
+  ActionFryingSystem,
+  ActionHoistSystem,
+  ActionJumpSystem,
+  ActionMineSystem,
+  ActionOhNoSystem,
+  ActionShrugSystem,
+  ActionSplatterSystem,
+  ActionWalkSystem,
+  BaseLogger,
+  COUNTER_LIMIT,
+  Lemming,
+  LemmingStateType,
+  LogHandler,
+  RENDER_MEASURE_DETAIL,
+  SkillTypes,
+  SoundEffectIds,
+  SoundEventTypes,
+  TICK_MEASURE_DETAIL,
+  TriggerTypes,
+  canMeasurePerformance,
+  getApp,
+  getAppContext,
+  getDependency,
+  getRuntimeSoundEvents,
+  isBenchMode,
+  recordPerformanceMeasure
+};
diff --git a/js/lemmings/lemming-manager/LemmingManagerSpawning.js b/js/lemmings/lemming-manager/LemmingManagerSpawning.js
new file mode 100644
index 00000000..65a47eb3
--- /dev/null
+++ b/js/lemmings/lemming-manager/LemmingManagerSpawning.js
@@ -0,0 +1,297 @@
+import {
+  ActionBashSystem,
+  ActionBlockerSystem,
+  ActionBuildSystem,
+  ActionClimbSystem,
+  ActionCountdownSystem,
+  ActionDiggSystem,
+  ActionDrowningSystem,
+  ActionExitingSystem,
+  ActionExplodingSystem,
+  ActionFallSystem,
+  ActionFloatingSystem,
+  ActionFryingSystem,
+  ActionHoistSystem,
+  ActionJumpSystem,
+  ActionMineSystem,
+  ActionOhNoSystem,
+  ActionShrugSystem,
+  ActionSplatterSystem,
+  ActionWalkSystem,
+  BaseLogger,
+  COUNTER_LIMIT,
+  Lemming,
+  LemmingStateType,
+  LogHandler,
+  RENDER_MEASURE_DETAIL,
+  SkillTypes,
+  SoundEffectIds,
+  SoundEventTypes,
+  TICK_MEASURE_DETAIL,
+  TriggerTypes,
+  canMeasurePerformance,
+  getApp,
+  getAppContext,
+  getDependency,
+  getRuntimeSoundEvents,
+  isBenchMode,
+  recordPerformanceMeasure
+} from './LemmingManagerShared.js';
+const lemmingManagerSpawningMethods = {
+  setMiniMap(miniMap) {
+    this.miniMap = miniMap;
+  },
+
+  refreshMiniMapDots() {
+    if (!this.miniMap) return false;
+    const lems = this.activeLemmings;
+    const lemsCount = lems.length;
+    if (this._minimapDotBuffer.length < lemsCount * 2) {
+      this._minimapDotBuffer = new Uint8Array(lemsCount * 2);
+    }
+    const dots = this._minimapDotBuffer;
+    const visited = this._mmVisited;
+    let visitStamp = (this._mmVisitStamp + 1) & 0xffff;
+    if (visitStamp === 0) {
+      visited.fill(0);
+      visitStamp = 1;
+    }
+    this._mmVisitStamp = visitStamp;
+    const scaleX = this.miniMap.scaleX;
+    const scaleY = this.miniMap.scaleY;
+    let idx = 0;
+    let hasSelectedDot = false;
+    for (let i = 0; i < lems.length; i += 1) {
+      const lem = lems[i];
+      if (lem.removed || lem.disabled) continue;
+      const x = (lem.x * scaleX) | 0;
+      const y = (lem.y * scaleY) | 0;
+      if (lem.id === this.selectedIndex) {
+        this._selectedMiniMapDot[0] = x;
+        this._selectedMiniMapDot[1] = y;
+        hasSelectedDot = true;
+      }
+      const key = (y << 8) | x;
+      if (visited[key] === visitStamp) continue;
+      visited[key] = visitStamp;
+      dots[idx++] = x;
+      dots[idx++] = y;
+    }
+    this.minimapDots = dots;
+    this.miniMap.setLiveDots(this.minimapDots, idx);
+    this.miniMap.setSelectedDot(hasSelectedDot ? this._selectedMiniMapDot : null);
+    return true;
+  },
+
+  _addActiveLemming(lem) {
+    lem._activeIndex = this.activeLemmings.length;
+    this.activeLemmings.push(lem);
+    this._nearestGridDirty = true;
+  },
+
+  _compactActiveLemmings() {
+    const lems = this.activeLemmings;
+    let write = 0;
+    for (let i = 0; i < lems.length; i++) {
+      const lem = lems[i];
+      if (lem.removed) continue;
+      lem._activeIndex = write;
+      lems[write++] = lem;
+    }
+    lems.length = write;
+    this._activeDirty = false;
+    this._nearestGridDirty = true;
+  },
+
+  _nearestCellKey(cx, cy) {
+    return ((cy & 0xffff) << 16) | (cx & 0xffff);
+  },
+
+  _rebuildNearestGrid() {
+    if (!this._nearestGridDirty) return;
+    const grid = this._nearestGrid;
+    const pool = this._nearestGridPool;
+    for (const list of grid.values()) {
+      list.length = 0;
+      pool.push(list);
+    }
+    grid.clear();
+    const shift = this._nearestCellShift;
+    const lems = this.activeLemmings;
+    for (let i = 0; i < lems.length; i += 1) {
+      const lem = lems[i];
+      if (!lem || lem.removed || lem.disabled) continue;
+      const cx = lem.x >> shift;
+      const cy = lem.y >> shift;
+      const key = this._nearestCellKey(cx, cy);
+      let bucket = grid.get(key);
+      if (!bucket) {
+        bucket = pool.pop() || [];
+        grid.set(key, bucket);
+      }
+      bucket.push(lem);
+    }
+    this._nearestGridDirty = false;
+  },
+
+  _findNearestInBucket(bucket, x, y, best, bestDist) {
+    for (let i = 0; i < bucket.length; i += 1) {
+      const lem = bucket[i];
+      if (!lem || lem.removed) continue;
+      const dist = lem.getClickDistance(x, y);
+      if (dist >= 0 && dist < bestDist) {
+        bestDist = dist;
+        best = lem;
+      }
+    }
+    return { best, bestDist };
+  },
+
+  _acquireLemming(x, y, id) {
+    const pool = this._lemmingPool;
+    const lem = pool.length ? pool.pop() : null;
+    if (lem && typeof lem.reset === 'function') {
+      lem.reset(x, y, id);
+      lem.setRuntime?.(this.runtime);
+      return lem;
+    }
+    const LemmingCtor = this._lemmingCtor;
+    if (typeof LemmingCtor !== 'function') {
+      throw new Error('LemmingManager requires an explicit lemming constructor.');
+    }
+    return new LemmingCtor(x, y, id, this.runtime);
+  },
+
+  _releaseLemming(lem) {
+    if (!lem || !this._lemmingPool) return;
+    if (this._lemmingPool.length >= this._maxLemmingPoolSize) return;
+    this._lemmingPool.push(lem);
+  },
+
+  processNewAction(lem, newAction) {
+    if (newAction === LemmingStateType.NO_STATE_TYPE) return false;
+    this.setLemmingState(lem, newAction);
+    return true;
+  },
+
+  _processLemmingStep(lem, tick) {
+    const newAction = lem.process(this.level);
+    this.processNewAction(lem, newAction);
+    const triggerAction = this.runTrigger(lem, tick);
+    this.processNewAction(lem, triggerAction);
+  },
+
+  tick() {
+    const app = getApp();
+    const perfEnabled = !!app &&
+        (app.performanceAPI === true || app.perfMetrics === true) &&
+        canMeasurePerformance();
+    const perfStart = perfEnabled ? performance.now() : 0;
+    try {
+      this.addNewLemmings();
+      const lems = this.activeLemmings;
+      const count = lems.length;
+      const tick = this.triggerManager?.gameTimer?.getGameTicks?.() ?? null;
+      const stepsPerTick = this.level?.isSuperLemming ? 2 : 1;
+      if (this.isNuking()) {
+        this._nukeNextLemming();
+      }
+      for (let i = 0; i < lems.length; i += 1) {
+        const lem = lems[i];
+        for (let step = 0; step < stepsPerTick; step += 1) {
+          if (lem.removed && lem.action !== this.actions[LemmingStateType.EXPLODING]) break;
+          this._processLemmingStep(lem, tick);
+        }
+      }
+      const sel = this.getSelectedLemming();
+      if (!sel || sel.removed || sel.disabled) this.selectedIndex = -1;
+      if (isBenchMode(app)) {
+        app.laggedOut = count;
+      }
+      if (this.miniMap && ((++this.mmTickCounter % 10) === 0)) {
+        this.refreshMiniMapDots();
+      }
+      if (this._activeDirty) {
+        this._compactActiveLemmings();
+      }
+      this._nearestGridDirty = true;
+    } finally {
+      if (perfEnabled) {
+        recordPerformanceMeasure('tick', {
+          start: perfStart,
+          detail: TICK_MEASURE_DETAIL
+        });
+      }
+    }
+  },
+
+  addLemming(x, y) {
+    const app = getApp();
+    const startingLemLength = this.lemmings.length;
+    const lem = this._acquireLemming(x, y, startingLemLength);
+    if (isBenchMode(app)) {
+      lem.lookRight = Math.random() < 0.5;
+    }
+    this.setLemmingState(lem, LemmingStateType.FALLING);
+    this.lemmings.push(lem);
+    this._addActiveLemming(lem);
+    this.spawnTotal += 1;
+
+    const extraCount = app?.extraLemmings | 0;
+    if (extraCount > 0) {
+      const action = this.actions[LemmingStateType.FALLING];
+      const extras = new Array(extraCount);
+      for (let i = 0; i < extraCount; i++) {
+        const extra = this._acquireLemming(
+          x,
+          y,
+          startingLemLength + 1 + i
+        );
+        if (isBenchMode(app)) {
+          extra.lookRight = Math.random() < 0.5;
+        }
+        extra.setAction(action);
+        extras[i] = extra;
+        this._addActiveLemming(extra);
+      }
+      Array.prototype.push.apply(this.lemmings, extras);
+      this.spawnTotal += extraCount;
+    }
+    this._nearestGridDirty = true;
+  },
+
+  addNewLemmings() {
+    const app = getApp();
+    const endless = app?.endless === true;
+    if (app?.bench === true || app?.bench2 === true || app?.benchReverse === true) { // if bench is enabled just keep spawning lems by skipping gameVictoryCondition check
+
+    } else {
+      if (!endless && this.gameVictoryCondition.getLeftCount() <= 0) return;
+    }
+    if (++this.releaseTickIndex >= (104 - this.gameVictoryCondition.getCurrentReleaseRate())) {
+      this.releaseTickIndex = 0;
+      const entrances = this.level.entrances;
+      for (let i = 0, l = entrances.length; i < l; i++) {
+        const entrance = entrances[i];
+        const spawnX = entrance.x + 24;
+        const spawnY = entrance.y + 14;
+        if (!entrance._opened) {
+          entrance._opened = true;
+          const soundBus = getRuntimeSoundEvents(this.runtime);
+          soundBus?.emitSfx?.(
+            SoundEventTypes.ENTRANCE_OPEN,
+            SoundEffectIds.ENTRANCE_OPEN,
+            {
+              entranceIndex: i,
+              x: spawnX,
+              y: spawnY
+            }
+          );
+        }
+        this.addLemming(spawnX, spawnY);
+        this.gameVictoryCondition.releaseOne();
+      }
+    }
+  }
+};
+export { lemmingManagerSpawningMethods };
diff --git a/js/level/GroundReader.js b/js/level/GroundReader.js
index 0c78cd78..fe0456de 100644
--- a/js/level/GroundReader.js
+++ b/js/level/GroundReader.js
@@ -3,19 +3,37 @@ import { ColorPalette } from '../render/ColorPalette.js';
 import { ObjectImageInfo } from './ObjectImageInfo.js';
 import { PaletteImage } from '../render/PaletteImage.js';
 import { TerrainImageInfo } from '../render/TerrainImageInfo.js';
+import { DEFAULT_STEEL_SPRITES } from '../steelSpritesData.js';
+import { getRuntimeDependency } from '../core/dependencies.js';
 let steelSprites = null;
 
+const cloneSteelSprites = (source) => {
+  const clone = {};
+  for (const [folder, files] of Object.entries(source || {})) {
+    clone[folder] = {};
+    for (const [filename, ids] of Object.entries(files || {})) {
+      clone[folder][filename] = Array.isArray(ids) ? ids.slice() : [];
+    }
+  }
+  return clone;
+};
+
 async function loadSteelSprites() {
   if (!steelSprites) {
     const url = new URL('../steelSprites.json', import.meta.url);
     try {
-      const res = await fetch(url);
+      const fetchRef = getRuntimeDependency(
+        'fetch',
+        typeof fetch === 'function' ? fetch : null
+      );
+      if (typeof fetchRef !== 'function') {
+        throw new Error('fetch API not available');
+      }
+      const res = await fetchRef(url);
       steelSprites = await res.json();
     } catch (e) {
       if (url.protocol === 'file:') {
-        const { readFile } = await import('node:fs/promises');
-        const txt = await readFile(url, 'utf8');
-        steelSprites = JSON.parse(txt);
+        steelSprites = cloneSteelSprites(DEFAULT_STEEL_SPRITES);
       } else {
         throw e;
       }
@@ -42,11 +60,6 @@ class GroundReader extends BaseLogger {
    */
   constructor (groundFile, vgaTerrain, vgaObject) {
     super();
-    if (groundFile.length !== 1056) {
-      this.log.log(`groundFile ${groundFile.filename} has wrong size: ${groundFile.length}`);
-      return;
-    }
-
     // ---------------------------------------------------------------------
     //  Pre‑allocate fixed‑length arrays so their shape never changes, which
     //  keeps them in V8 "fast elements" mode for O(1) access.
@@ -56,6 +69,13 @@ class GroundReader extends BaseLogger {
 
     this.groundPalette = new ColorPalette();
     this.colorPalette  = new ColorPalette();
+    this.valid = false;
+
+    if (groundFile.length !== 1056) {
+      this.log.log(`groundFile ${groundFile.filename} has wrong size: ${groundFile.length}`);
+      return;
+    }
+    this.valid = true;
 
     // Palette offset is the last block in the file – compute once.
     const paletteOffset = BYTE_SIZE_OF_OBJECTS + BYTE_SIZE_OF_TERRAIN;
@@ -98,7 +118,7 @@ class GroundReader extends BaseLogger {
           let widest  = 0;
           let tallest = 0;
 
-          // scan each row once from the right 
+          // scan each row once from the right
           for (let y = img.height - 1; y >= 0; --y) {
             const rowBase = y * img.width;
             let rowHasPixel = false;
@@ -134,7 +154,6 @@ class GroundReader extends BaseLogger {
   _readObjectImages (fr, offset, palette) {
     fr.setOffset(offset);
 
-    //console.log("obj count: " + OBJECT_COUNT)
     for (let i = 0; i < OBJECT_COUNT; ++i) {
       const img      = new ObjectImageInfo();
       const flags    = fr.readWordBE();
@@ -192,9 +211,7 @@ class GroundReader extends BaseLogger {
       const filename = fr.filename;
       const foldername = fr.foldername;
       if (foldername === '[unknown]') {
-        console.log(
-          'folder name for ' + filename + ' is unknown, unable to use magic numbers to make perfect steel'
-        );
+        this.log.log('folder name for ' + filename + ' is unknown, unable to use magic numbers to make perfect steel');
       } else {
         const sprites = steelSprites ?? {};
         const gameData = sprites[foldername];
diff --git a/js/level/Level.js b/js/level/Level.js
index fe2379e9..4b9c083e 100644
--- a/js/level/Level.js
+++ b/js/level/Level.js
@@ -1,424 +1 @@
-import { BaseLogger, withPerformance } from '../util/LogHandler.js';
-import { Animation } from '../render/Animation.js';
-import { ColorPalette } from '../render/ColorPalette.js';
-import { Frame } from '../render/Frame.js';
-import { MapObject } from './MapObject.js';
-import { Range } from '../util/Range.js';
-import { SkillTypes } from '../game/SkillTypes.js';
-import { SolidLayer } from '../render/SolidLayer.js';
-import { Trigger } from './Trigger.js';
-
-// Palette remapping for the fire shooter trap. 
-const FIRE_INDICES = Object.freeze([3, 4, 5, 6, 10, 11, 12, 13, 14]);
-const ICE_COLORS   = Object.freeze([
-  ColorPalette.colorFromRGB(92, 224, 255),
-  ColorPalette.colorFromRGB(96, 255, 255),
-  ColorPalette.colorFromRGB(72, 192, 255),
-  ColorPalette.colorFromRGB(64, 160, 255),
-  ColorPalette.colorFromRGB(4, 48, 136),
-  ColorPalette.colorFromRGB(0, 64, 152),
-  ColorPalette.colorFromRGB(2, 32, 120),
-  ColorPalette.colorFromRGB(0, 64, 152),
-  ColorPalette.colorFromRGB(64, 160, 255)
-]);
-
-class Level extends BaseLogger {
-  constructor(width, height) {
-    super();
-    this.width = width | 0;
-    this.height = height | 0;
-    this.groundMask = new SolidLayer(this.width, this.height);
-    this.groundImages = null;
-    this.steelRanges = new Int32Array(0);
-    this.steelMask = new SolidLayer(this.width, this.height);
-
-    this.objects = [];
-    this.entrances = [];
-    this.triggers = [];
-    this.arrowRanges = new Int32Array(0);
-    this.arrowTriggers = [];
-
-    this.name = '';
-    this.releaseRate = 0;
-    this.releaseCount = 0;
-    this.needCount = 0;
-    this.timeLimit = 0;
-    this.skills = new Array(Object.keys(SkillTypes).length);
-    this.screenPositionX = 0;
-    this.isSuperLemming = false;
-    /** mechanics customization */
-    this.mechanics = {};
-
-    /** @type {Frame|null} prebuilt debug overlay */
-    this._debugFrame = null;
-  }
-
-  setMapObjects(objects, objectImg) {
-    withPerformance(
-      'setMapObjects',
-      {
-        track: 'Level',
-        trackGroup: 'Game State',
-        color: 'primary-light',
-        tooltipText: 'setMapObjects'
-      },
-      () => {
-        this.objects.length = 0;
-        this.entrances.length = 0;
-        this.triggers.length = 0;
-        let arrowRects = [];
-        for (const ob of objects) {
-          let objectInfo = objectImg[ob.id];
-          if (objectInfo == null) continue;
-
-          // // Ice palette swap for fire shooter traps
-          // if (ob.id === 8 || ob.id === 10) {
-          //   const pal = new ColorPalette();
-          //   for (let i = 0; i < 16; ++i) {
-          //     pal.setColorInt(i, objectInfo.palette.getColor(i));
-          //   }
-          //   for (let i = 0; i < FIRE_INDICES.length; ++i) {
-          //     pal.setColorInt(FIRE_INDICES[i], ICE_COLORS[i]);
-          //   }
-
-          //   const clone = new ObjectImageInfo();
-          //   Object.assign(clone, objectInfo);
-          //   clone.palette = pal;
-          //   objectInfo = clone;
-          // }
-          let tfxID = objectInfo.trigger_effect_id;
-
-          if (tfxID === 6 && (ob.id === 7 || ob.id === 8 || ob.id === 10)) {
-            tfxID = 12;
-          }
-
-          const mapOb = new MapObject(ob, objectInfo, new Animation(), tfxID);
-          this.objects.push(mapOb);
-          if (ob.id === 1) this.entrances.push(ob);
-
-          if (tfxID !== 0) {
-            const x1 = ob.x + objectInfo.trigger_left;
-            const y1 = ob.y + objectInfo.trigger_top;
-            const x2 = x1 + objectInfo.trigger_width;
-            const y2 = y1 + objectInfo.trigger_height;
-            let repeatDelay = 0;
-            if (tfxID != 1) {
-              if (tfxID != 5 && tfxID != 6 && tfxID != 7 && tfxID != 8 && tfxID != 12) {
-                repeatDelay = objectInfo.frameCount;
-              }
-            }
-
-            let trigger = new Trigger(tfxID, x1, y1, x2, y2, repeatDelay, objectInfo.trap_sound_effect_id, mapOb);
-
-            if (mapOb.triggerType == 7 || mapOb.triggerType == 8) {
-              const newRange = new Range();
-              newRange.x = ob.x + objectInfo.trigger_left;
-              newRange.y = ob.y + objectInfo.trigger_top;
-              newRange.width = objectInfo.trigger_width;
-              newRange.height = objectInfo.trigger_height;
-              newRange.direction = mapOb.triggerType == 8 ? 1 : 0;
-              arrowRects.push(newRange);
-              this.arrowTriggers.push(trigger);
-            }
-
-            this.triggers.push(trigger);
-          }
-        }
-        if (arrowRects.length > 0) {
-          this.setArrowAreas(arrowRects);
-        }
-        this._debugFrame = null; // invalidate cached debug overlay
-      })();
-  }
-
-  getGroundMaskLayer() { return this.groundMask; }
-  setGroundMaskLayer(solidLayer) { this.groundMask = solidLayer; }
-
-  isOutOfLevel(y) { return y < 0 || y >= this.height; }
-
-  _clearGroundWithMaskInternal(mask, x, y) {
-    let changed = false;
-    let removed = 0;
-    const history = globalThis?.lemmings?.game?.history ?? null;
-    const gm = this.groundMask;
-    const gmMask = gm.mask;
-    const img = this.groundImage;
-    const w = this.width;
-    const { offsetX, offsetY, width: mw, height: mh } = mask;
-    for (let dy = 0; dy < mh; ++dy) {
-      for (let dx = 0; dx < mw; ++dx) {
-        if (mask.at(dx, dy)) continue; // Only erase where mask is TRANSPARENT  
-        const px = x + offsetX + dx;
-        const py = y + offsetY + dy;
-        if (this.isSteelAt(px, py)) continue;
-        if (px < 0 || px >= this.width || py < 0 || py >= this.height) continue;
-        const maskIdx = py * w + px;
-        const imgIdx = maskIdx * 4;
-        const prevMask = gmMask[maskIdx];
-        const prevR = img[imgIdx];
-        const prevG = img[imgIdx + 1];
-        const prevB = img[imgIdx + 2];
-        if (prevMask || prevR || prevG || prevB) {
-          history?.recordGroundChange?.(
-            maskIdx,
-            prevMask,
-            prevR,
-            prevG,
-            prevB,
-            0,
-            0,
-            0,
-            0
-          );
-        }
-        if (prevMask) {
-          changed = true;
-          gmMask[maskIdx] = 0;
-        }
-        if (prevR || prevG || prevB) {
-          removed += 1;
-        }
-        img[imgIdx] = img[imgIdx + 1] = img[imgIdx + 2] = 0;
-      }
-    }
-    return { changed, removed };
-  }
-
-  clearGroundWithMask(mask, x, y) {
-    return this._clearGroundWithMaskInternal(mask, x, y).changed;
-  }
-
-  clearGroundWithMaskCount(mask, x, y) {
-    return this._clearGroundWithMaskInternal(mask, x, y).removed;
-  }
-
-  setGroundAt(x, y, paletteIndex) {
-    const maskIdx = y * this.width + x;
-    const idx = (y * this.width + x) * 4;
-    const gp = this.groundImage;
-    const history = globalThis?.lemmings?.game?.history ?? null;
-    if (history?.recordGroundChange) {
-      const prevMask = this.groundMask.mask[maskIdx];
-      const prevR = gp[idx];
-      const prevG = gp[idx + 1];
-      const prevB = gp[idx + 2];
-      const nextR = this.colorPalette.getR(paletteIndex);
-      const nextG = this.colorPalette.getG(paletteIndex);
-      const nextB = this.colorPalette.getB(paletteIndex);
-      history.recordGroundChange(
-        maskIdx,
-        prevMask,
-        prevR,
-        prevG,
-        prevB,
-        1,
-        nextR,
-        nextG,
-        nextB
-      );
-    }
-    this.groundMask.setGroundAt(x, y);
-    gp[idx]     = this.colorPalette.getR(paletteIndex);
-    gp[idx + 1] = this.colorPalette.getG(paletteIndex);
-    gp[idx + 2] = this.colorPalette.getB(paletteIndex);
-    globalThis?.lemmings?.game?.lemmingManager?.miniMap?.onGroundChanged(x, y, false);
-  }
-
-  hasGroundAt(x, y) { return this.groundMask.hasGroundAt(x, y); }
-
-  clearGroundAt(x, y) {
-    if (this.isSteelAt(x, y)) return;
-    const idx = (y * this.width + x) * 4;
-    const gp  = this.groundImage;
-    const history = globalThis?.lemmings?.game?.history ?? null;
-    if (history?.recordGroundChange) {
-      const maskIdx = y * this.width + x;
-      const prevMask = this.groundMask.mask[maskIdx];
-      const prevR = gp[idx];
-      const prevG = gp[idx + 1];
-      const prevB = gp[idx + 2];
-      history.recordGroundChange(
-        maskIdx,
-        prevMask,
-        prevR,
-        prevG,
-        prevB,
-        0,
-        0,
-        0,
-        0
-      );
-    }
-    this.groundMask.clearGroundAt(x, y);
-    gp[idx] = gp[idx + 1] = gp[idx + 2] = 0;
-    globalThis?.lemmings?.game?.lemmingManager?.miniMap?.onGroundChanged(x, y, true);
-  }
-
-  setArrowAreas(ranges = []) {
-    const buf = new Int32Array(ranges.length * 5);
-    for (let i = 0, o = 0; i < ranges.length; ++i, o += 5) {
-      const r = ranges[i];
-      buf[o]   = r.x;
-      buf[o+1] = r.y;
-      buf[o+2] = r.width;
-      buf[o+3] = r.height;
-      buf[o+4] = r.direction;
-    }
-    this.arrowRanges = buf;
-    this._debugFrame = null; // invalidate cached debug overlay
-  }
-
-  isArrowAt(x, y, direction) {
-    const a = this.arrowRanges;
-    for (let i = 0, len = a.length; i < len; i += 5) {
-      if (x >= a[i] && x < a[i] + a[i+2] && y >= a[i+1] && y < a[i+1] + a[i+3] && direction != a[i+4]) {
-        return true;
-      }
-    }
-    return false;
-  }
-
-  isArrowGround(x, y, direction) { return this.isArrowAt(x, y, direction) && this.hasGroundAt(x, y); }
-
-  hasArrowUnderMask(mask, ox, oy, direction) {
-    const { offsetX:mx, offsetY:my, width:w, height:h } = mask;
-    for (let dy = 0; dy < h; ++dy) {
-      for (let dx = 0; dx < w; ++dx) {
-        if (!mask.at(dx, dy) && this.isArrowGround(ox + mx + dx, oy + my + dy, direction)) {
-          return true;
-        }
-      }
-    }
-    return false;
-  }
-
-  newSetSteelAreas(levelReader, terrainImages) {
-    withPerformance(
-      'newSetSteelAreas',
-      {
-        track: 'Level',
-        trackGroup: 'Game State',
-        color: 'secondary-light',
-        tooltipText: 'newSetSteelAreas'
-      },
-      () => {
-        if (!this.steelMask || this.steelMask.width !== this.width || this.steelMask.height !== this.height) {
-          this.steelMask = new SolidLayer(this.width, this.height);
-        } else {
-          // Clear all
-          this.steelMask.mask.fill(0);
-        }
-        const { levelWidth, levelHeight, terrains } = levelReader;
-        let newSteelRanges = [];
-        if (this.steelRanges.length == 0) return;
-        for (let i = 0, len = terrains.length; i < len; ++i) {
-          const tObj = terrains[i];
-          const terImg = terrainImages[tObj.id];
-          if (terImg.isSteel == true) {
-            const newRange = new Range();
-            newRange.x = tObj.x;
-            newRange.y = tObj.y;
-            newRange.width = terImg.steelWidth;
-            newRange.height = terImg.steelHeight;
-            for (let dy = tObj.y; dy < tObj.y+terImg.height; dy++) {
-              for (let dx = tObj.x; dx < tObj.x+terImg.width; dx++) {
-                if (this.isSteelAt(dx,dy, true)) {
-                  newSteelRanges.push(newRange);
-                  this.steelMask.setMaskAt(dx, dy);
-                }
-              }
-            }
-          }
-        }
-        if (newSteelRanges.length > 0) {
-          this.steelRanges = new Int32Array(0);
-          this.setSteelAreas(newSteelRanges);
-        }
-      })();
-  }
-
-  setSteelAreas(ranges = []) {
-    const buf = new Int32Array(ranges.length * 4);
-    for (let i = 0, o = 0; i < ranges.length; ++i, o += 4) {
-      const r = ranges[i];
-      buf[o]   = r.x;
-      buf[o+1] = r.y;
-      buf[o+2] = r.width;
-      buf[o+3] = r.height;
-    }
-    this.steelRanges = buf;
-    this._debugFrame = null; // invalidate cached debug overlay
-  }
-
-  isSteelAt(x, y, loading = false) {
-    if (loading == false) {
-      return this.steelMask.hasMaskAt(x,y);
-    }
-    const s = this.steelRanges;
-    for (let i = 0, len = s.length; i < len; i += 4) {
-      if (x >= s[i] && x < s[i] + s[i+2] && y >= s[i+1] && y < s[i+1] + s[i+3]) {
-        return true;
-      }
-    }
-    return false;
-  }
-
-  isSteelGround(x, y, loading = false) {
-    if (loading == false) {
-      return this.steelMask.hasMaskAt(x,y);
-    }
-    if (this.hasGroundAt(x, y)) {
-      return this.isSteelAt(x, y);
-    }
-  }
-
-  hasSteelUnderMask(mask, ox, oy) {
-    const { offsetX:mx, offsetY:my, width:w, height:h } = mask;
-    for (let dy = 0; dy < h; ++dy) {
-      for (let dx = 0; dx < w; ++dx) {
-        if (!mask.at(dx, dy) && this.isSteelGround(ox + mx + dx, oy + my + dy)) {
-          return true;
-        }
-      }
-    }
-    return false;
-  }
-
-  setGroundImage(img) { this.groundImage = new Uint8ClampedArray(img); }
-  setPalettes(colorPalette, groundPalette) {
-    this.colorPalette = colorPalette;
-    this.groundPalette = groundPalette;
-  }
-
-  render(gameDisplay) {
-    gameDisplay.initSize(this.width, this.height);
-    gameDisplay.setBackground(this.groundImage, this.groundMask);
-  }
-
-  renderDebug(gameDisplay) {
-    if (!this._debugFrame) this.#buildDebugFrame();
-    gameDisplay.drawFrame(this._debugFrame, 0, 0);
-  }
-
-  #buildDebugFrame() {
-    const frame = new Frame(this.width, this.height);
-    const steelColor  = ColorPalette.colorFromRGB(0, 255, 255);
-    const arrowRColor = ColorPalette.colorFromRGB(128, 255, 0);
-    const arrowLColor = ColorPalette.colorFromRGB(255, 128, 0);
-
-    const s = this.steelRanges;
-    for (let i = 0, len = s.length; i < len; i += 4) {
-      frame.drawRect(s[i], s[i+1], s[i+2], s[i+3], steelColor);
-    }
-
-    const a = this.arrowRanges;
-    for (let i = 0, len = a.length; i < len; i += 5) {
-      const col = a[i+4] ? arrowRColor : arrowLColor;
-      frame.drawRect(a[i], a[i+1], a[i+2], a[i+3], col);
-    }
-
-    this._debugFrame = frame;
-  }
-}
-
-export { Level };
+export { Level } from './level/LevelCore.js';
diff --git a/js/level/LevelLoader.js b/js/level/LevelLoader.js
index d3583cf3..10e57968 100644
--- a/js/level/LevelLoader.js
+++ b/js/level/LevelLoader.js
@@ -8,6 +8,17 @@ import { OddTableReader } from '../data/OddTableReader.js';
 import { SolidLayer } from '../render/SolidLayer.js';
 import { VGASpecReader } from '../data/VGASpecReader.js';
 
+const PACK_RESOURCE_FALLBACKS = Object.freeze({
+  xmas92: Object.freeze(['xmas91'])
+});
+
+const isMissingResourceError = (error) => {
+  if (!error) return false;
+  if (error.code === 'ENOENT') return true;
+  const message = String(error.message || '');
+  return message.includes('ENOENT');
+};
+
 const mergeLevelProperties = (baseProperties, oddProperties) => {
   if (!oddProperties) return baseProperties;
 
@@ -57,6 +68,47 @@ class LevelLoader {
     this.fileProvider = fileProvider;
     this.config = config;
     this.levelIndexResolve = new LevelIndexResolve(config);
+    this.resourceFallbackPaths = this.#buildResourceFallbackPaths();
+  }
+
+  #buildResourceFallbackPaths() {
+    const defaults = PACK_RESOURCE_FALLBACKS[this.config?.path] || [];
+    const configured = Array.isArray(this.config?.resourceFallbackPaths)
+      ? this.config.resourceFallbackPaths
+      : [];
+    const merged = [this.config?.path, ...configured, ...defaults];
+    const unique = [];
+    for (let i = 0; i < merged.length; i += 1) {
+      const entry = merged[i];
+      if (typeof entry !== 'string' || entry.length === 0) continue;
+      if (unique.includes(entry)) continue;
+      unique.push(entry);
+    }
+    return unique;
+  }
+
+  /**
+   * Load a pack resource from the active pack first, then configured fallback
+   * packs. This keeps runtime level logic unchanged while supporting packs
+   * that intentionally reuse shared terrain/object files.
+   */
+  async #loadBinaryWithFallback(filename) {
+    let lastMissing = null;
+    const roots = this.resourceFallbackPaths;
+    for (let i = 0; i < roots.length; i += 1) {
+      const root = roots[i];
+      try {
+        return await this.fileProvider.loadBinary(root, filename);
+      } catch (error) {
+        if (isMissingResourceError(error)) {
+          lastMissing = error;
+          continue;
+        }
+        throw error;
+      }
+    }
+    if (lastMissing) throw lastMissing;
+    throw new Error(`Unable to load resource: ${filename}`);
   }
 
   async getLevel (levelMode, levelIndex) {
@@ -69,7 +121,7 @@ class LevelLoader {
     if (levelInfo == null) return null;
 
     const useOddTable   = levelInfo.useOddTable && this.config.level.useOddTable;
-    const paddedFileId  = ('0000' + levelInfo.fileId).slice(-3);   
+    const paddedFileId  = ('0000' + levelInfo.fileId).slice(-3);
 
     const baseLevel     = this.fileProvider.loadBinary(
       this.config.path,
@@ -119,11 +171,11 @@ class LevelLoader {
     // 3 · Fetch graphics set(s) in parallel                                   //
     // ----------------------------------------------------------------------- //
     await loadSteelSprites();
-    const vgagrFile    = this.fileProvider.loadBinary(
-      this.config.path, `VGAGR${levelReader.graphicSet1}.DAT`);
-    const groundFile   = this.fileProvider.loadBinary(
-      this.config.path, `GROUND${levelReader.graphicSet1}O.DAT`);
-    const vgaspecFile  = (levelReader.graphicSet2 !== 0) ? this.fileProvider.loadBinary(this.config.path, `VGASPEC${levelReader.graphicSet2 - 1}.DAT`) : null;
+    const vgagrFile    = this.#loadBinaryWithFallback(`VGAGR${levelReader.graphicSet1}.DAT`);
+    const groundFile   = this.#loadBinaryWithFallback(`GROUND${levelReader.graphicSet1}O.DAT`);
+    const vgaspecFile  = (levelReader.graphicSet2 !== 0)
+      ? this.#loadBinaryWithFallback(`VGASPEC${levelReader.graphicSet2 - 1}.DAT`)
+      : null;
 
     const [vgagrBuf, groundBuf, vgaspecBuf] =
       await Promise.all([vgagrFile, groundFile, vgaspecFile]);
@@ -157,9 +209,9 @@ class LevelLoader {
     level.setPalettes(groundReader.colorPalette, groundReader.groundPalette);
 
     level.setSteelAreas(levelReader.steel);
-    level.newSetSteelAreas(levelReader, groundReader.getTerrainImages()); 
+    level.newSetSteelAreas(levelReader, groundReader.getTerrainImages());
 
-    return level;  
+    return level;
   }
 }
 
diff --git a/js/level/LevelReader.js b/js/level/LevelReader.js
index e283d43a..b86ae6fe 100644
--- a/js/level/LevelReader.js
+++ b/js/level/LevelReader.js
@@ -80,17 +80,19 @@ class LevelReader extends BaseLogger {
     fr.setOffset(LEVEL_OBJECT_OFFSET);
     for (let i = 0; i < LEVEL_OBJECT_COUNT; i++) {
       const newOb = new LevelElement();
-      newOb.x = fr.readWord() - OBJECT_X_OFFSET;
-      newOb.y = fr.readWord();
-      newOb.id = fr.readWord();
+      const rawX = fr.readWord();
+      const rawY = fr.readWord();
+      const rawId = fr.readWord();
       const flags = fr.readWord();
+      if (rawX === 0 && rawY === 0 && rawId === 0 && flags === 0)
+        continue;
+      newOb.x = rawX - OBJECT_X_OFFSET;
+      newOb.y = rawY;
+      newOb.id = rawId;
       const isUpsideDown = ((flags & 0x0080) > 0);
       const noOverwrite = ((flags & 0x8000) > 0);
       const onlyOverwrite = ((flags & 0x4000) > 0);
       newOb.drawProperties = new DrawProperties(isUpsideDown, noOverwrite, onlyOverwrite, false);
-      /// ignore empty items/objects
-      if (flags == 0)
-        continue;
       this.objects.push(newOb);
     }
   }
diff --git a/js/level/MapObject.js b/js/level/MapObject.js
index 1deb10d0..3fd502d2 100644
--- a/js/level/MapObject.js
+++ b/js/level/MapObject.js
@@ -1,28 +1,71 @@
 import { Animation } from '../render/Animation.js';
 import { Frame } from '../render/Frame.js';
-import { SoundEventTypes, SoundEffectIds, getSoundBus } from '../game/SoundEvents.js';
+import { SoundEventTypes, SoundEffectIds } from '../game/SoundEvents.js';
 import { TriggerTypes } from './TriggerTypes.js';
+import { getRuntimeHistory, getRuntimeSoundEvents } from '../game/GameRuntime.js';
 
 class MapObject {
   /** WeakMap<objectImg, Frame[]> – shared across all MapObject instances. */
   static _frameCache = new WeakMap();
-  constructor (ob, objectImg, animation = new Animation(), triggerType = TriggerTypes.NO_TRIGGER) {
+  constructor (ob, objectImg, animation = new Animation(), triggerType = TriggerTypes.NO_TRIGGER, runtime = null) {
     this.ob              = ob;
     this.obID            = ob.id;
     this.x               = ob.x;
     this.y               = ob.y;
     this.drawProperties  = ob.drawProperties;
     this.triggerType     = triggerType;
+    this.runtime         = runtime;
 
     let frames = MapObject._frameCache.get(objectImg);
     if (!frames) {
       frames = new Array(objectImg.frames.length);
+      // Keep sourceScale consistent with GroundRenderer so hi-res object frames
+      // can be sampled down into classic world-space sprite sizes once at load time.
+      const srcScaleX = Math.max(1, (objectImg.sourceScaleX | 0) || 1);
+      const srcScaleY = Math.max(1, (objectImg.sourceScaleY | 0) || 1);
       for (let i = 0, len = frames.length; i < len; ++i) {
-        const f = new Frame(objectImg.width, objectImg.height);
+        const src = objectImg.frames[i];
+        if (src instanceof Frame && srcScaleX === 1 && srcScaleY === 1) {
+          frames[i] = src;
+          continue;
+        }
+
+        const srcWidth = (src instanceof Frame ? src.width : objectImg.width) | 0;
+        const srcHeight = (src instanceof Frame ? src.height : objectImg.height) | 0;
+        const outWidth = Math.max(1, Math.floor(srcWidth / srcScaleX));
+        const outHeight = Math.max(1, Math.floor(srcHeight / srcScaleY));
+        const f = new Frame(outWidth, outHeight);
         f.clear();
-        // Draw once (palette → RGBA). This cost is now paid ONE time per sprite
-        f.drawPaletteImage(objectImg.frames[i], objectImg.width, objectImg.height,
-          objectImg.palette, 0, 0);
+
+        const sample = (x, y) => (y * srcWidth) + x;
+        if (src instanceof Frame) {
+          const srcBuf = src.getBuffer();
+          const srcMask = src.getMask();
+          for (let y = 0; y < outHeight; y += 1) {
+            const srcY = y * srcScaleY;
+            for (let x = 0; x < outWidth; x += 1) {
+              const idx = sample(x * srcScaleX, srcY);
+              if (!srcMask[idx]) continue;
+              f.setPixel(x, y, srcBuf[idx]);
+            }
+          }
+        } else {
+          const pal = objectImg.palette;
+          if (!pal) {
+            frames[i] = f;
+            continue;
+          }
+          const palLookup = pal._rgbaCache ||= Uint32Array.from({ length: 128 }, (_, j) => pal.getColor(j));
+          for (let y = 0; y < outHeight; y += 1) {
+            const srcY = y * srcScaleY;
+            for (let x = 0; x < outWidth; x += 1) {
+              const idx = sample(x * srcScaleX, srcY);
+              const ci = src[idx];
+              if (ci & 0x80) continue;
+              f.setPixel(x, y, palLookup[ci]);
+            }
+          }
+        }
         frames[i] = f;
       }
       MapObject._frameCache.set(objectImg, frames);
@@ -33,13 +76,22 @@ class MapObject {
     this.animation.firstFrameIndex = objectImg.firstFrameIndex;
     this.animation.objectImg       = objectImg;
     this.animation.frames          = frames;
+    const firstFrame = frames[0];
+    if (Number.isFinite(firstFrame?.width) && Number.isFinite(firstFrame?.height)) {
+      this._frameWidth = firstFrame.width;
+      this._frameHeight = firstFrame.height;
+    }
+  }
+
+  setRuntime(runtime = null) {
+    this.runtime = runtime;
   }
 
   /** Called when a lemming collides with this object's trigger zone. */
   onTrigger (globalTick, lemming = null, trigger = null, x = null, y = null) {
     // 1. restart visual cue
     if (this.animation && !this.animation.loop) {
-      const history = globalThis?.lemmings?.game?.history ?? null;
+      const history = getRuntimeHistory(this.runtime);
       if (history?.recordObjectAnimation) {
         const prev = {
           firstFrameIndex: this.animation.firstFrameIndex,
@@ -70,7 +122,7 @@ class MapObject {
     }
 
     if (eventType && Number.isFinite(sfxId) && sfxId > 0) {
-      const soundBus = getSoundBus();
+      const soundBus = getRuntimeSoundEvents(this.runtime);
       soundBus?.emitSfx?.(
         eventType,
         sfxId,
diff --git a/js/level/ObjectManager.js b/js/level/ObjectManager.js
index 9c7e8088..dda62dbe 100644
--- a/js/level/ObjectManager.js
+++ b/js/level/ObjectManager.js
@@ -1,36 +1,195 @@
-import { withPerformance } from '../util/LogHandler.js';
+import { getAppContext } from '../core/dependencies.js';
+import {
+  canMeasurePerformance,
+  recordPerformanceMeasure
+} from '../util/performanceInstrumentation.js';
+
+const RENDER_MEASURE_DETAIL = Object.freeze({
+  devtools: Object.freeze({
+    track: 'ObjectManager',
+    trackGroup: 'Render',
+    color: 'secondary',
+    tooltipText: 'render'
+  })
+});
 
 class ObjectManager {
   constructor(gameTimer) {
     this.gameTimer = gameTimer;
     this.objects = [];
+    this._bucketWidth = 128;
+    this._xBuckets = new Map();
+    this._bucketScratch = [];
+    this._unknownWidthObjects = [];
+    this._renderStamp = 0;
+  }
+
+  _bucketIndexForX(x) {
+    return Math.floor(x / this._bucketWidth);
+  }
+
+  _frameSizeFromObject(obj) {
+    const width = Number.isFinite(obj?._frameWidth) ? obj._frameWidth : NaN;
+    const height = Number.isFinite(obj?._frameHeight) ? obj._frameHeight : NaN;
+    if (Number.isFinite(width) && Number.isFinite(height)) {
+      return { width, height };
+    }
+    const frame = obj?.animation?.frames?.[0] || null;
+    if (Number.isFinite(frame?.width) && Number.isFinite(frame?.height)) {
+      obj._frameWidth = frame.width;
+      obj._frameHeight = frame.height;
+      return { width: frame.width, height: frame.height };
+    }
+    return null;
+  }
+
+  _addObjectToBucket(obj) {
+    if (!Number.isFinite(obj?.x)) return;
+    const size = this._frameSizeFromObject(obj);
+    if (!size || !Number.isFinite(size.width) || size.width <= 0) {
+      this._unknownWidthObjects.push(obj);
+      obj.__objectManagerBuckets = null;
+      return;
+    }
+    const startBucket = this._bucketIndexForX(obj.x);
+    const endBucket = this._bucketIndexForX(obj.x + Math.max(0, size.width - 1));
+    const buckets = [];
+    for (let bucket = startBucket; bucket <= endBucket; bucket += 1) {
+      let list = this._xBuckets.get(bucket);
+      if (!list) {
+        list = [];
+        this._xBuckets.set(bucket, list);
+      }
+      list.push(obj);
+      buckets.push(bucket);
+    }
+    obj.__objectManagerBuckets = buckets;
+  }
+
+  _moveUnknownObjectToBuckets(obj, index) {
+    const size = this._frameSizeFromObject(obj);
+    if (!size || !Number.isFinite(size.width) || size.width <= 0) return false;
+    const last = this._unknownWidthObjects.length - 1;
+    if (index !== last) this._unknownWidthObjects[index] = this._unknownWidthObjects[last];
+    this._unknownWidthObjects.length = last;
+    this._addObjectToBucket(obj);
+    return true;
   }
+
+  _pushBucketObject(source, obj, stamp) {
+    if (obj.__objectManagerRenderStamp === stamp) return;
+    obj.__objectManagerRenderStamp = stamp;
+    source.push(obj);
+  }
+
   /** render all Objects to the GameDisplay */
   render(gameDisplay) {
-    return withPerformance(
-      'ObjectManager render',
-      {
-        track: 'ObjectManager',
-        trackGroup: 'Render',
-        color: 'secondary',
-        tooltipText: 'render'
-      },
-      () => {
-        let objs = this.objects;
-        let tick = this.gameTimer.getGameTicks();
-        for (let i = 0; i < objs.length; i++) {
-          let obj = objs[i];
-          gameDisplay.drawFrameFlags(obj.animation.getFrame(tick + 1), obj.x, obj.y, obj.drawProperties);
+    const app = getAppContext();
+    const perfEnabled = !!app &&
+      (app.performanceAPI === true || app.perfMetrics === true) &&
+      canMeasurePerformance();
+    const perfStart = perfEnabled ? performance.now() : 0;
+    try {
+      const objs = this.objects;
+      const tick = this.gameTimer.getGameTicks();
+      const view = gameDisplay?.stage?.getGameViewRect?.();
+      let minX = -Infinity;
+      let minY = -Infinity;
+      let maxX = Infinity;
+      let maxY = Infinity;
+      if (view) {
+        const pad = 32;
+        minX = view.x - pad;
+        minY = view.y - pad;
+        maxX = view.x + view.w + pad;
+        maxY = view.y + view.h + pad;
+      }
+      let source = objs;
+      if (view) {
+        const bucketPad = this._bucketWidth;
+        const startBucket = this._bucketIndexForX(minX - bucketPad);
+        const endBucket = this._bucketIndexForX(maxX + bucketPad);
+        source = this._bucketScratch;
+        source.length = 0;
+        this._renderStamp = (this._renderStamp + 1) || 1;
+        const stamp = this._renderStamp;
+        for (let bucket = startBucket; bucket <= endBucket; bucket += 1) {
+          const list = this._xBuckets.get(bucket);
+          if (!list?.length) continue;
+          for (let i = 0; i < list.length; i += 1) {
+            this._pushBucketObject(source, list[i], stamp);
+          }
+        }
+        for (let i = 0; i < this._unknownWidthObjects.length;) {
+          const obj = this._unknownWidthObjects[i];
+          if (this._moveUnknownObjectToBuckets(obj, i)) {
+            const fw = obj._frameWidth;
+            if ((obj.x + fw) >= minX && obj.x <= maxX) {
+              this._pushBucketObject(source, obj, stamp);
+            }
+            continue;
+          }
+          this._pushBucketObject(source, obj, stamp);
+          i += 1;
         }
       }
-    ).call(this);
+      for (let i = 0; i < source.length; i++) {
+        const obj = source[i];
+        const animation = obj?.animation;
+        if (!animation?.getFrame) continue;
+        let fw = Number.isFinite(obj._frameWidth) ? obj._frameWidth : NaN;
+        let fh = Number.isFinite(obj._frameHeight) ? obj._frameHeight : NaN;
+        if (view && Number.isFinite(fw) && Number.isFinite(fh)) {
+          if ((obj.x + fw) < minX || obj.x > maxX || (obj.y + fh) < minY || obj.y > maxY) {
+            continue;
+          }
+        }
+        const frame = animation.getFrame(tick + 1);
+        if (!frame) continue;
+        if (!Number.isFinite(fw) || !Number.isFinite(fh)) {
+          fw = frame.width ?? 0;
+          fh = frame.height ?? 0;
+          obj._frameWidth = fw;
+          obj._frameHeight = fh;
+          if (view && obj.__objectManagerBuckets == null) {
+            const unknownIndex = this._unknownWidthObjects.indexOf(obj);
+            if (unknownIndex >= 0) {
+              this._moveUnknownObjectToBuckets(obj, unknownIndex);
+            }
+          }
+        }
+        if (view) {
+          if ((obj.x + fw) < minX || obj.x > maxX || (obj.y + fh) < minY || obj.y > maxY) {
+            continue;
+          }
+        }
+        gameDisplay.drawFrameFlags(frame, obj.x, obj.y, obj.drawProperties);
+      }
+    } finally {
+      if (perfEnabled) {
+        recordPerformanceMeasure('ObjectManager render', {
+          start: perfStart,
+          detail: RENDER_MEASURE_DETAIL
+        });
+      }
+    }
   }
   /** add map objects to manager */
   addRange(mapObjects) {
     for (let i = 0; i < mapObjects.length; i++) {
-      this.objects.push(mapObjects[i]);
+      const obj = mapObjects[i];
+      this.objects.push(obj);
+      this._addObjectToBucket(obj);
     }
   }
+
+  dispose() {
+    this.objects.length = 0;
+    this._xBuckets.clear();
+    this._bucketScratch.length = 0;
+    this._unknownWidthObjects.length = 0;
+    this.gameTimer = null;
+  }
 }
 
 export { ObjectManager };
diff --git a/js/level/Trigger.js b/js/level/Trigger.js
index 89279ad4..e2fd00f3 100644
--- a/js/level/Trigger.js
+++ b/js/level/Trigger.js
@@ -1,13 +1,28 @@
+// @ts-check
 import { COUNTER_LIMIT } from '../core/constants.js';
 import { TriggerTypes } from './TriggerTypes.js';
+import { getRuntimeHistory } from '../game/GameRuntime.js';
 
 class Trigger {
   #disabledUntilTick;
+  /**
+   * @param {number} [type]
+   * @param {number} [x1]
+   * @param {number} [y1]
+ * @param {number} [x2] exclusive right edge
+ * @param {number} [y2] exclusive bottom edge
+   * @param {number} [disableTicksCount]
+   * @param {number} [soundIndex]
+   * @param {any} [owner]
+   */
   constructor(type = TriggerTypes.NO_TRIGGER, x1 = 0, y1 = 0, x2 = 0, y2 = 0, disableTicksCount = 0, soundIndex = -1, owner = null) {
     this.#disabledUntilTick = 0;
+    /** @type {number|undefined} */
+    this.__historyId = undefined;
     this.owner = owner;
-    this.type = type;
+    this.type = Number(type);
     this.soundIndex = soundIndex;
+    this.runtime = null;
     this.x1 = Math.min(x1, x2);
     this.y1 = Math.min(y1, y2);
     this.x2 = Math.max(x1, x2);
@@ -26,11 +41,11 @@ class Trigger {
   }
   trigger(x, y, tick, lemming = null) {
     if (this.disabledUntilTick <= tick) {
-      if ((x >= this.x1) && (y >= this.y1) && (x <= this.x2) && (y <= this.y2)) {
+      if ((x >= this.x1) && (y >= this.y1) && (x < this.x2) && (y < this.y2)) {
         const prev = this.disabledUntilTick;
         const next = tick + this.disableTicksCount;
         if (prev !== next) {
-          const history = globalThis?.lemmings?.game?.history ?? null;
+          const history = getRuntimeHistory(this.runtime);
           history?.recordTriggerCooldown?.(this, prev, next);
         }
         this.disabledUntilTick = next;
@@ -45,11 +60,18 @@ class Trigger {
     return TriggerTypes.NO_TRIGGER;
   }
   draw(gameDisplay) {
-
-    if (this.type == 7 || this.type == 8) {
+    if (this.type === TriggerTypes.ONEWAY_LEFT || this.type === TriggerTypes.ONEWAY_RIGHT) {
       return; // don't render arrow triggers to debug display, that is handled in level
     }
-    gameDisplay.drawRect(this.x1, this.y1, this.x2 - this.x1, this.y2 - this.y1, 255, 0, 0);
+    gameDisplay.drawRect(
+      this.x1,
+      this.y1,
+      Math.max(0, this.x2 - this.x1 - 1),
+      Math.max(0, this.y2 - this.y1 - 1),
+      255,
+      0,
+      0
+    );
   }
 }
 
diff --git a/js/level/TriggerManager.js b/js/level/TriggerManager.js
index 84eaffe5..a8e423b8 100644
--- a/js/level/TriggerManager.js
+++ b/js/level/TriggerManager.js
@@ -1,138 +1,178 @@
 import { ColorPalette } from '../render/ColorPalette.js';
 import { Frame } from '../render/Frame.js';
 import { TriggerTypes } from './TriggerTypes.js';
-import { withPerformance } from '../util/LogHandler.js';
-
-/*  TriggerManager
- *  ───────────────
- *  Public API:
- *      constructor(gameTimer, [levelW, levelH, cellSize])
- *      add(trigger)
- *      addRange(triggerArray)
- *      removeByOwner(owner)
- *      trigger(x, y)           → TriggerTypes enum
- *      renderDebug(gameDisplay)
- *
- *  • Grid cell size defaults to 16 px (power-of-two → shift 4)
- *  • Grid columns/rows are computed from levelW / levelH on construction
- *  • All indices are clamped, so out-of-bounds writes are impossible
- */
+import { getAppContext } from '../core/dependencies.js';
+import {
+  getRuntimeHistory,
+  getRuntimePerformanceContext
+} from '../game/GameRuntime.js';
+import {
+  canMeasurePerformance,
+  recordPerformanceMeasure
+} from '../util/performanceInstrumentation.js';
+
+const TRIGGER_MEASURE_DETAIL = Object.freeze({
+  devtools: Object.freeze({
+    track: 'TriggerManager',
+    trackGroup: 'Game State',
+    color: 'secondary-light',
+    tooltipText: 'trigger'
+  })
+});
 
 class TriggerManager {
-  /**
-   * @param {GameTimer} gameTimer
-   * @param {number}  [levelW=1600]   – level width in pixels (inclusive)
-   * @param {number}  [levelH=160]    – level height in pixels (inclusive)
-   * @param {number}  [cellSize=16]   – grid cell size, must be power of two
-   */
-  constructor (gameTimer, levelW = 1600, levelH = 160, cellSize = 16) {
-    /* store basics */
+  constructor(gameTimer, levelW = 1600, levelH = 160, cellSize = 16, runtime = null) {
     this.gameTimer = gameTimer;
+    this.runtime = runtime;
     this._cellSize = cellSize;
-    this._shift    = Math.log2(cellSize) | 0;   // integer shift
-    this._levelW   = levelW;
-    this._levelH   = levelH;
-
-    /* derive grid */
-    this._cols   = (levelW  >> this._shift) + 1;   // e.g. 1600 → 101
-    this._rows   = (levelH  >> this._shift) + 1;   // e.g.  160 → 11
-    const slots  = this._cols * this._rows;
+    this._shift = Math.log2(cellSize) | 0;
+    this._levelW = Math.max(1, Math.trunc(Number(levelW) || 1600));
+    this._levelH = Math.max(1, Math.trunc(Number(levelH) || 160));
 
-    this._grid   = Array.from({length: slots}, () => new Set());
+    this._cols = Math.max(1, Math.ceil(this._levelW / cellSize));
+    this._rows = Math.max(1, Math.ceil(this._levelH / cellSize));
+    const slots = this._cols * this._rows;
 
+    this._grid = Array.from({ length: slots }, () => []);
+    this._observerGrid = Array.from({ length: slots }, () => []);
     this._triggers = new Set();
+    this._observerTriggers = new Set();
+    this._ownerTriggers = new Map();
+    this._ownerObserverTriggers = new Map();
 
-    /* debug bookkeeping */
     this._lastCheckTick = new Uint32Array(slots);
-    this._lastHitTick   = new Uint32Array(slots);
+    this._lastHitTick = new Uint32Array(slots);
 
-    /* handy bounds */
-    this._maxX = levelW;
-    this._maxY = levelH;
-
-    /** @type {Frame|null} prebuilt debug overlay */
+    this._maxX = this._levelW - 1;
+    this._maxY = this._levelH - 1;
     this._debugFrame = null;
   }
 
-  /* ───────────────────────── public API ───────────────────────── */
+  setRuntime(runtime = null) {
+    this.runtime = runtime;
+    for (const trigger of this._triggers || []) {
+      trigger.runtime = runtime;
+    }
+    for (const trigger of this._observerTriggers || []) {
+      trigger.runtime = runtime;
+    }
+  }
 
-  /** Register a single trigger */
-  add (trigger) {
-    if (this._triggers.has(trigger)) return;
+  add(trigger) {
+    if (!trigger || this._triggers.has(trigger)) return;
+    trigger.runtime = this.runtime;
     this._triggers.add(trigger);
+    this.#addOwnerRecord(trigger, this._ownerTriggers);
     this.#insert(trigger);
     this._debugFrame = null;
-    const history = globalThis?.lemmings?.game?.history ?? null;
-    if (history?.recordTriggerAdd) {
-      history.recordTriggerAdd(trigger, {
-        type: trigger.type,
-        x1: trigger.x1,
-        y1: trigger.y1,
-        x2: trigger.x2,
-        y2: trigger.y2,
-        disableTicksCount: trigger.disableTicksCount,
-        soundIndex: trigger.soundIndex,
-        ownerId: trigger.owner?.id ?? null
-      });
-    }
-  }
-
-  /** Bulk-add (used by Level on load) */
-  addRange (arr) {
+    this.#recordTriggerAdd(trigger, false);
+  }
+
+  addObserver(trigger) {
+    if (!trigger || this._observerTriggers.has(trigger)) return;
+    trigger.runtime = this.runtime;
+    this._observerTriggers.add(trigger);
+    this.#addOwnerRecord(trigger, this._ownerObserverTriggers);
+    this.#insert(trigger, {
+      grid: this._observerGrid,
+      indicesProp: '__observerBucketIndices',
+      positionsProp: '__observerBucketCellPositions'
+    });
+    this.#recordTriggerAdd(trigger, true);
+  }
+
+  addRange(arr) {
     for (let i = 0; i < arr.length; ++i) this.add(arr[i]);
     if (arr.length) this._debugFrame = null;
   }
 
-  /** Remove every trigger that belongs to `owner` */
-  removeByOwner (owner) {
+  remove(trigger) {
+    if (this._triggers?.has(trigger)) {
+      this.#remove(trigger);
+      return;
+    }
+    if (this._observerTriggers?.has(trigger)) {
+      this.#removeObserver(trigger);
+    }
+  }
+
+  removeByOwner(owner) {
     if (!this._triggers) return;
-    for (const tr of this._triggers) {
-      if (tr.owner === owner) this.#remove(tr);
+    const list = this._ownerTriggers.get(owner);
+    if (list?.length) {
+      const owned = list.slice();
+      for (let i = 0; i < owned.length; i += 1) {
+        this.#remove(owned[i]);
+      }
+      return;
+    }
+    for (const trigger of this._triggers) {
+      if (trigger.owner === owner) {
+        this.#remove(trigger);
+      }
     }
     this._debugFrame = null;
   }
 
-  /**
-   * Query at pixel (x,y).  Returns a value from TriggerTypes
-   */
-  trigger (x, y, lemming = null) {
-    return withPerformance(
-      'TriggerManager trigger',
-      {
-        track: 'TriggerManager',
-        trackGroup: 'Game State',
-        color: 'secondary-light',
-        tooltipText: 'trigger'
-      },
-      () => {
-        if (x < 0 || y < 0 || x > this._maxX || y > this._maxY) {
-          return TriggerTypes.NO_TRIGGER;
-        }
+  removeObserverByOwner(owner) {
+    if (!this._observerTriggers) return;
+    const list = this._ownerObserverTriggers.get(owner);
+    if (list?.length) {
+      const owned = list.slice();
+      for (let i = 0; i < owned.length; i += 1) {
+        this.#removeObserver(owned[i]);
+      }
+      return;
+    }
+    for (const trigger of this._observerTriggers) {
+      if (trigger.owner === owner) {
+        this.#removeObserver(trigger);
+      }
+    }
+  }
 
-        const bucket =
-          ( (y >> this._shift) * this._cols ) +
-          (  x >> this._shift);
+  trigger(x, y, lemming = null, tickOverride = null) {
+    const app = getRuntimePerformanceContext(this.runtime) || getAppContext();
+    const perfEnabled = !!app &&
+      (app.performanceAPI === true || app.perfMetrics === true) &&
+      canMeasurePerformance();
+    const perfStart = perfEnabled ? performance.now() : 0;
+    try {
+      if (x < 0 || y < 0 || x > this._maxX || y > this._maxY) {
+        return TriggerTypes.NO_TRIGGER;
+      }
 
-        const cell = this._grid[bucket];
-        const tick = this.gameTimer.getGameTicks();
+      const bucket = ((y >> this._shift) * this._cols) + (x >> this._shift);
+      const cell = this._grid[bucket];
+      const tick = Number.isFinite(tickOverride)
+        ? Math.trunc(tickOverride)
+        : this.gameTimer.getGameTicks();
 
-        this._lastCheckTick[bucket] = tick;
+      this._lastCheckTick[bucket] = tick;
 
-        for (const trig of cell) {
-          const val = trig.trigger(x, y, tick, lemming);
-          if (val !== TriggerTypes.NO_TRIGGER) {
-            this._lastHitTick[bucket] = tick;
-            return val;
-          }
+      for (let i = 0; i < cell.length; i += 1) {
+        const trig = cell[i];
+        const val = trig.trigger(x, y, tick, lemming);
+        if (val !== TriggerTypes.NO_TRIGGER) {
+          this._lastHitTick[bucket] = tick;
+          this.#runObservers(bucket, x, y, lemming, tick);
+          return val;
         }
-        return TriggerTypes.NO_TRIGGER;
       }
-    ).call(this);
+      this.#runObservers(bucket, x, y, lemming, tick);
+      return TriggerTypes.NO_TRIGGER;
+    } finally {
+      if (perfEnabled) {
+        recordPerformanceMeasure('TriggerManager trigger', {
+          start: perfStart,
+          detail: TRIGGER_MEASURE_DETAIL
+        });
+      }
+    }
   }
 
-  /** Draw rectangles in debug overlay */
-  renderDebug (g) {
-    const cs   = this._cellSize;
+  renderDebug(g) {
+    const cs = this._cellSize;
     const tick = this.gameTimer.getGameTicks();
     for (let r = 0; r < this._rows; ++r) {
       const base = r * this._cols;
@@ -142,7 +182,7 @@ class TriggerManager {
           g.drawRect(c * cs, r * cs, cs - 1, cs - 1, 255, 0, 0);
         } else if (this._lastCheckTick[idx] === tick) {
           g.drawRect(c * cs, r * cs, cs - 1, cs - 1, 255, 255, 255);
-        } else if (this._grid[idx].size === 0) {
+        } else if (this._grid[idx].length === 0) {
           g.drawRect(c * cs, r * cs, cs - 1, cs - 1, 128, 128, 128);
         } else {
           g.drawRect(c * cs, r * cs, cs - 1, cs - 1, 0, 0, 255);
@@ -153,74 +193,199 @@ class TriggerManager {
     g.drawFrame(this._debugFrame, 0, 0);
   }
 
-  /* ────────────────────── internal helpers ────────────────────── */
-
   #buildDebugFrame() {
     const frame = new Frame(this._levelW, this._levelH);
     const color = ColorPalette.colorFromRGB(255, 0, 0);
     for (const tr of this._triggers) {
-      if (tr.type === 7 || tr.type === 8) continue; // arrows handled elsewhere
-      frame.drawRect(tr.x1, tr.y1, tr.x2 - tr.x1, tr.y2 - tr.y1, color);
+      if (tr.type === 7 || tr.type === 8) continue;
+      frame.drawRect(
+        tr.x1,
+        tr.y1,
+        Math.max(0, tr.x2 - tr.x1 - 1),
+        Math.max(0, tr.y2 - tr.y1 - 1),
+        color
+      );
     }
     this._debugFrame = frame;
   }
 
-  #insert (trigger) {
-    /* normalise & clamp bounds */
-    let x0 = Math.max(0, Math.min(this._maxX, Math.min(trigger.x1, trigger.x2)));
-    let x1 = Math.max(0, Math.min(this._maxX, Math.max(trigger.x1, trigger.x2)));
-    let y0 = Math.max(0, Math.min(this._maxY, Math.min(trigger.y1, trigger.y2)));
-    let y1 = Math.max(0, Math.min(this._maxY, Math.max(trigger.y1, trigger.y2)));
+  #addOwnerRecord(trigger, ownerMap) {
+    const owner = trigger.owner ?? null;
+    if (!owner) return;
+    let list = ownerMap.get(owner);
+    if (!list) {
+      list = [];
+      ownerMap.set(owner, list);
+    }
+    list.push(trigger);
+  }
+
+  #removeOwnerRecord(trigger, ownerMap) {
+    const owner = trigger.owner ?? null;
+    if (!owner) return;
+    const ownerList = ownerMap.get(owner);
+    if (!ownerList?.length) return;
+    for (let i = ownerList.length - 1; i >= 0; i -= 1) {
+      if (ownerList[i] !== trigger) continue;
+      const last = ownerList.length - 1;
+      if (i !== last) ownerList[i] = ownerList[last];
+      ownerList.length = last;
+      break;
+    }
+    if (ownerList.length === 0) {
+      ownerMap.delete(owner);
+    }
+  }
+
+  #triggerSnapshot(trigger, observer) {
+    return {
+      type: trigger.type,
+      x1: trigger.x1,
+      y1: trigger.y1,
+      x2: trigger.x2,
+      y2: trigger.y2,
+      disableTicksCount: trigger.disableTicksCount,
+      soundIndex: trigger.soundIndex,
+      ownerId: trigger.owner?.id ?? null,
+      observer
+    };
+  }
+
+  #recordTriggerAdd(trigger, observer) {
+    const history = getRuntimeHistory(this.runtime);
+    history?.recordTriggerAdd?.(trigger, this.#triggerSnapshot(trigger, observer));
+  }
+
+  #recordTriggerRemove(trigger, observer) {
+    const history = getRuntimeHistory(this.runtime);
+    history?.recordTriggerRemove?.(trigger, this.#triggerSnapshot(trigger, observer));
+  }
+
+  #insert(trigger, {
+    grid = this._grid,
+    indicesProp = '__bucketIndices',
+    positionsProp = '__bucketCellPositions'
+  } = {}) {
+    const x0 = Math.max(0, Math.min(this._levelW, Math.min(trigger.x1, trigger.x2)));
+    const x1 = Math.max(0, Math.min(this._levelW, Math.max(trigger.x1, trigger.x2)));
+    const y0 = Math.max(0, Math.min(this._levelH, Math.min(trigger.y1, trigger.y2)));
+    const y1 = Math.max(0, Math.min(this._levelH, Math.max(trigger.y1, trigger.y2)));
+    if (x1 <= x0 || y1 <= y0) {
+      trigger[indicesProp] = [];
+      trigger[positionsProp] = [];
+      return;
+    }
 
     const c0 = x0 >> this._shift;
-    const c1 = x1 >> this._shift;
+    const c1 = (x1 - 1) >> this._shift;
     const r0 = y0 >> this._shift;
-    const r1 = y1 >> this._shift;
+    const r1 = (y1 - 1) >> this._shift;
 
-    const buckets = new Set();
+    const bucketCount = (r1 - r0 + 1) * (c1 - c0 + 1);
+    const buckets = new Array(bucketCount);
+    const bucketPositions = new Array(bucketCount);
+    let bucketIndex = 0;
     for (let r = r0; r <= r1; ++r) {
       const base = r * this._cols;
       for (let c = c0; c <= c1; ++c) {
         const idx = base + c;
-        this._grid[idx].add(trigger);
-        buckets.add(idx);
+        const cell = grid[idx];
+        const insertPos = cell.length;
+        cell.push(trigger);
+        buckets[bucketIndex++] = idx;
+        bucketPositions[bucketIndex - 1] = insertPos;
       }
     }
-    trigger.__bucketIndices = buckets;   // fast removal
+    trigger[indicesProp] = buckets;
+    trigger[positionsProp] = bucketPositions;
   }
 
-  #remove (trigger) {
-    this._triggers.delete(trigger);
-    const buckets = trigger.__bucketIndices;
+  #removeFromGrid(trigger, {
+    grid = this._grid,
+    indicesProp = '__bucketIndices',
+    positionsProp = '__bucketCellPositions'
+  } = {}) {
+    const buckets = trigger[indicesProp];
+    const bucketPositions = trigger[positionsProp];
     if (buckets) {
-      for (const idx of buckets) {
-        const arr = this._grid[idx];
+      for (let i = 0; i < buckets.length; i += 1) {
+        const idx = buckets[i];
+        const cell = grid[idx];
+        if (!cell?.length) continue;
+
+        let pos = Number.isFinite(bucketPositions?.[i]) ? bucketPositions[i] : -1;
+        const last = cell.length - 1;
+        if (pos < 0 || pos > last || cell[pos] !== trigger) {
+          pos = -1;
+          for (let j = last; j >= 0; j -= 1) {
+            if (cell[j] === trigger) {
+              pos = j;
+              break;
+            }
+          }
+          if (pos < 0) continue;
+        }
 
-        arr.delete(trigger);
+        if (pos !== last) {
+          const swapped = cell[last];
+          cell[pos] = swapped;
+          const swappedBuckets = swapped?.[indicesProp];
+          const swappedPositions = swapped?.[positionsProp];
+          if (swappedBuckets && swappedPositions) {
+            for (let j = 0; j < swappedBuckets.length; j += 1) {
+              if (swappedBuckets[j] !== idx) continue;
+              if (swappedPositions[j] !== last) continue;
+              swappedPositions[j] = pos;
+              break;
+            }
+          }
+        }
+        cell.length = last;
       }
     }
-    const history = globalThis?.lemmings?.game?.history ?? null;
-    if (history?.recordTriggerRemove) {
-      history.recordTriggerRemove(trigger, {
-        type: trigger.type,
-        x1: trigger.x1,
-        y1: trigger.y1,
-        x2: trigger.x2,
-        y2: trigger.y2,
-        disableTicksCount: trigger.disableTicksCount,
-        soundIndex: trigger.soundIndex,
-        ownerId: trigger.owner?.id ?? null
-      });
-    }
-    delete trigger.__bucketIndices;
+    delete trigger[indicesProp];
+    delete trigger[positionsProp];
+  }
+
+  #remove(trigger) {
+    this._triggers.delete(trigger);
+    this.#removeFromGrid(trigger);
+    this.#removeOwnerRecord(trigger, this._ownerTriggers);
+    this.#recordTriggerRemove(trigger, false);
+    trigger.runtime = null;
     this._debugFrame = null;
   }
 
+  #removeObserver(trigger) {
+    this._observerTriggers.delete(trigger);
+    this.#removeFromGrid(trigger, {
+      grid: this._observerGrid,
+      indicesProp: '__observerBucketIndices',
+      positionsProp: '__observerBucketCellPositions'
+    });
+    this.#removeOwnerRecord(trigger, this._ownerObserverTriggers);
+    this.#recordTriggerRemove(trigger, true);
+    trigger.runtime = null;
+  }
+
+  #runObservers(bucket, x, y, lemming, tick) {
+    const cell = this._observerGrid?.[bucket];
+    if (!cell?.length) return;
+    for (let i = 0; i < cell.length; i += 1) {
+      cell[i].trigger(x, y, tick, lemming);
+    }
+  }
+
   dispose() {
     this.gameTimer = null;
-    this._grid   = null;
+    this._grid = null;
+    this._observerGrid = null;
     this._triggers = null;
+    this._observerTriggers = null;
+    this._ownerTriggers = null;
+    this._ownerObserverTriggers = null;
     this._debugFrame = null;
+    this.runtime = null;
   }
 }
 
diff --git a/js/level/level/LevelArrowSteel.js b/js/level/level/LevelArrowSteel.js
new file mode 100644
index 00000000..96155883
--- /dev/null
+++ b/js/level/level/LevelArrowSteel.js
@@ -0,0 +1,199 @@
+import {
+  Animation,
+  BaseLogger,
+  ColorPalette,
+  FIRE_INDICES,
+  Frame,
+  ICE_COLORS,
+  MapObject,
+  Range,
+  SET_MAP_OBJECTS_MEASURE_DETAIL,
+  SET_STEEL_MEASURE_DETAIL,
+  SkillTypes,
+  SolidLayer,
+  Trigger,
+  canMeasurePerformance,
+  getAppContext,
+  getMaskTransparentSpans,
+  getRuntimeApp,
+  getRuntimeHistory,
+  getRuntimeMiniMap,
+  getRuntimePerformanceContext,
+  recordPerformanceMeasure
+} from './LevelShared.js';
+const levelArrowSteelMethods = {
+  setArrowAreas(ranges = []) {
+    const buf = new Int32Array(ranges.length * 5);
+    for (let i = 0, o = 0; i < ranges.length; ++i, o += 5) {
+      const r = ranges[i];
+      buf[o]   = r.x;
+      buf[o+1] = r.y;
+      buf[o+2] = r.width;
+      buf[o+3] = r.height;
+      buf[o+4] = r.direction;
+    }
+    this.arrowRanges = buf;
+    this._debugFrame = null; // invalidate cached debug overlay
+  },
+
+  isArrowAt(x, y, direction) {
+    const a = this.arrowRanges;
+    for (let i = 0, len = a.length; i < len; i += 5) {
+      if (x >= a[i] && x < a[i] + a[i+2] && y >= a[i+1] && y < a[i+1] + a[i+3] && direction != a[i+4]) {
+        return true;
+      }
+    }
+    return false;
+  },
+
+  isArrowGround(x, y, direction) { return this.isArrowAt(x, y, direction) && this.hasGroundAt(x, y); },
+
+  hasArrowUnderMask(mask, ox, oy, direction) {
+    const { offsetX:mx, offsetY:my, width:w, height:h } = mask;
+    const spans = getMaskTransparentSpans(mask);
+    if (spans?.rows?.length) {
+      const rows = spans.rows;
+      const starts = spans.starts;
+      const lengths = spans.lengths;
+      for (let i = 0; i < rows.length; i += 1) {
+        const dy = rows[i];
+        const y = oy + my + dy;
+        const start = starts[i];
+        const end = start + lengths[i];
+        for (let dx = start; dx < end; dx += 1) {
+          if (this.isArrowGround(ox + mx + dx, y, direction)) {
+            return true;
+          }
+        }
+      }
+      return false;
+    }
+    for (let dy = 0; dy < h; ++dy) {
+      for (let dx = 0; dx < w; ++dx) {
+        if (!mask.at(dx, dy) && this.isArrowGround(ox + mx + dx, oy + my + dy, direction)) {
+          return true;
+        }
+      }
+    }
+    return false;
+  },
+
+  newSetSteelAreas(levelReader, terrainImages) {
+    const app = getRuntimeApp(this.runtime);
+    const perfEnabled = !!app &&
+        (app.performanceAPI === true || app.perfMetrics === true) &&
+        canMeasurePerformance();
+    const perfStart = perfEnabled ? performance.now() : 0;
+    try {
+      if (!this.steelMask || this.steelMask.width !== this.width || this.steelMask.height !== this.height) {
+        this.steelMask = new SolidLayer(this.width, this.height);
+      } else {
+        // Clear all
+        this.steelMask.mask.fill(0);
+      }
+      const { terrains } = levelReader;
+      let newSteelRanges = [];
+      if (this.steelRanges.length == 0) return;
+      for (let i = 0, len = terrains.length; i < len; ++i) {
+        const tObj = terrains[i];
+        const terImg = terrainImages[tObj.id];
+        if (terImg.isSteel == true) {
+          const newRange = new Range();
+          newRange.x = tObj.x;
+          newRange.y = tObj.y;
+          newRange.width = terImg.steelWidth;
+          newRange.height = terImg.steelHeight;
+          let hasSteelPixels = false;
+          for (let dy = tObj.y; dy < tObj.y+terImg.height; dy++) {
+            for (let dx = tObj.x; dx < tObj.x+terImg.width; dx++) {
+              if (this.isSteelAt(dx,dy, true)) {
+                if (!hasSteelPixels) {
+                  newSteelRanges.push(newRange);
+                  hasSteelPixels = true;
+                }
+                this.steelMask.setMaskAt(dx, dy);
+              }
+            }
+          }
+        }
+      }
+      if (newSteelRanges.length > 0) {
+        this.steelRanges = new Int32Array(0);
+        this.setSteelAreas(newSteelRanges);
+      }
+    } finally {
+      if (perfEnabled) {
+        recordPerformanceMeasure('newSetSteelAreas', {
+          start: perfStart,
+          detail: SET_STEEL_MEASURE_DETAIL
+        });
+      }
+    }
+  },
+
+  setSteelAreas(ranges = []) {
+    const buf = new Int32Array(ranges.length * 4);
+    for (let i = 0, o = 0; i < ranges.length; ++i, o += 4) {
+      const r = ranges[i];
+      buf[o]   = r.x;
+      buf[o+1] = r.y;
+      buf[o+2] = r.width;
+      buf[o+3] = r.height;
+    }
+    this.steelRanges = buf;
+    this._debugFrame = null; // invalidate cached debug overlay
+  },
+
+  isSteelAt(x, y, loading = false) {
+    if (loading == false) {
+      return this.steelMask.hasMaskAt(x,y);
+    }
+    const s = this.steelRanges;
+    for (let i = 0, len = s.length; i < len; i += 4) {
+      if (x >= s[i] && x < s[i] + s[i+2] && y >= s[i+1] && y < s[i+1] + s[i+3]) {
+        return true;
+      }
+    }
+    return false;
+  },
+
+  isSteelGround(x, y, loading = false) {
+    if (loading == false) {
+      return this.steelMask.hasMaskAt(x,y);
+    }
+    if (this.hasGroundAt(x, y)) {
+      return this.isSteelAt(x, y);
+    }
+  },
+
+  hasSteelUnderMask(mask, ox, oy) {
+    const { offsetX:mx, offsetY:my, width:w, height:h } = mask;
+    const spans = getMaskTransparentSpans(mask);
+    if (spans?.rows?.length) {
+      const rows = spans.rows;
+      const starts = spans.starts;
+      const lengths = spans.lengths;
+      for (let i = 0; i < rows.length; i += 1) {
+        const dy = rows[i];
+        const y = oy + my + dy;
+        const start = starts[i];
+        const end = start + lengths[i];
+        for (let dx = start; dx < end; dx += 1) {
+          if (this.isSteelGround(ox + mx + dx, y)) {
+            return true;
+          }
+        }
+      }
+      return false;
+    }
+    for (let dy = 0; dy < h; ++dy) {
+      for (let dx = 0; dx < w; ++dx) {
+        if (!mask.at(dx, dy) && this.isSteelGround(ox + mx + dx, oy + my + dy)) {
+          return true;
+        }
+      }
+    }
+    return false;
+  }
+};
+export { levelArrowSteelMethods };
\ No newline at end of file
diff --git a/js/level/level/LevelCore.js b/js/level/level/LevelCore.js
new file mode 100644
index 00000000..4acf29f9
--- /dev/null
+++ b/js/level/level/LevelCore.js
@@ -0,0 +1,97 @@
+import {
+  Animation,
+  BaseLogger,
+  ColorPalette,
+  FIRE_INDICES,
+  Frame,
+  ICE_COLORS,
+  MapObject,
+  Range,
+  SET_MAP_OBJECTS_MEASURE_DETAIL,
+  SET_STEEL_MEASURE_DETAIL,
+  SkillTypes,
+  SolidLayer,
+  Trigger,
+  canMeasurePerformance,
+  getAppContext,
+  getMaskTransparentSpans,
+  getRuntimeApp,
+  getRuntimeHistory,
+  getRuntimeMiniMap,
+  getRuntimePerformanceContext,
+  recordPerformanceMeasure
+} from './LevelShared.js';
+import { levelGroundMutationMethods } from './LevelGroundMutation.js';
+import { levelArrowSteelMethods } from './LevelArrowSteel.js';
+import { levelRenderMethods } from './LevelRender.js';
+class Level extends BaseLogger {
+  constructor(width, height) {
+    super();
+    this.width = width | 0;
+    this.height = height | 0;
+    this.groundMask = new SolidLayer(this.width, this.height);
+    this.groundImages = null;
+    this.steelRanges = new Int32Array(0);
+    this.steelMask = new SolidLayer(this.width, this.height);
+
+    this.objects = [];
+    this.entrances = [];
+    this.triggers = [];
+    this.arrowRanges = new Int32Array(0);
+    this.arrowTriggers = [];
+
+    this.name = '';
+    this.releaseRate = 0;
+    this.releaseCount = 0;
+    this.needCount = 0;
+    this.timeLimit = 0;
+    this.skills = new Array(Object.keys(SkillTypes).length);
+    this.screenPositionX = 0;
+    this.isSuperLemming = false;
+    /** mechanics customization */
+    this.mechanics = {};
+
+    /** @type {Frame|null} prebuilt debug overlay */
+    this._debugFrame = null;
+    this._groundTileSize = 64;
+    this._groundTileColumns = Math.max(1, Math.ceil(this.width / this._groundTileSize));
+    this._groundTileRows = Math.max(1, Math.ceil(this.height / this._groundTileSize));
+    this._groundDirtyTiles = new Set();
+    this._groundDirtyFull = true;
+    this._groundDirtyRects = [];
+    this.runtime = null;
+  }
+
+  renderDebug(gameDisplay) {
+    if (!this._debugFrame) this.#buildDebugFrame();
+    gameDisplay.drawFrame(this._debugFrame, 0, 0);
+  }
+
+  #buildDebugFrame() {
+    const frame = new Frame(this.width, this.height);
+    const steelColor  = ColorPalette.colorFromRGB(0, 255, 255);
+    const arrowRColor = ColorPalette.colorFromRGB(128, 255, 0);
+    const arrowLColor = ColorPalette.colorFromRGB(255, 128, 0);
+
+    const s = this.steelRanges;
+    for (let i = 0, len = s.length; i < len; i += 4) {
+      frame.drawRect(s[i], s[i+1], s[i+2], s[i+3], steelColor);
+    }
+
+    const a = this.arrowRanges;
+    for (let i = 0, len = a.length; i < len; i += 5) {
+      const col = a[i+4] ? arrowRColor : arrowLColor;
+      frame.drawRect(a[i], a[i+1], a[i+2], a[i+3], col);
+    }
+
+    this._debugFrame = frame;
+  }
+}
+for (const methods of [
+  levelGroundMutationMethods,
+  levelArrowSteelMethods,
+  levelRenderMethods
+]) {
+  Object.defineProperties(Level.prototype, Object.getOwnPropertyDescriptors(methods));
+}
+export { Level };
\ No newline at end of file
diff --git a/js/level/level/LevelGroundMutation.js b/js/level/level/LevelGroundMutation.js
new file mode 100644
index 00000000..a3f88b17
--- /dev/null
+++ b/js/level/level/LevelGroundMutation.js
@@ -0,0 +1,512 @@
+import {
+  Animation,
+  BaseLogger,
+  ColorPalette,
+  FIRE_INDICES,
+  Frame,
+  ICE_COLORS,
+  MapObject,
+  Range,
+  SET_MAP_OBJECTS_MEASURE_DETAIL,
+  SET_STEEL_MEASURE_DETAIL,
+  SkillTypes,
+  SolidLayer,
+  Trigger,
+  canMeasurePerformance,
+  getAppContext,
+  getMaskTransparentSpans,
+  getRuntimeApp,
+  getRuntimeHistory,
+  getRuntimeMiniMap,
+  getRuntimePerformanceContext,
+  recordPerformanceMeasure
+} from './LevelShared.js';
+const levelGroundMutationMethods = {
+  setRuntime(runtime = null) {
+    this.runtime = runtime;
+    for (const obj of this.objects || []) {
+      obj?.setRuntime?.(runtime);
+    }
+    for (const trigger of this.triggers || []) {
+      trigger.runtime = runtime;
+    }
+    for (const trigger of this.arrowTriggers || []) {
+      trigger.runtime = runtime;
+    }
+  },
+
+  setMapObjects(objects, objectImg) {
+    const app = getRuntimeApp(this.runtime);
+    const perfEnabled = !!app &&
+        (app.performanceAPI === true || app.perfMetrics === true) &&
+        canMeasurePerformance();
+    const perfStart = perfEnabled ? performance.now() : 0;
+    try {
+      this.objects.length = 0;
+      this.entrances.length = 0;
+      this.triggers.length = 0;
+      this.arrowTriggers.length = 0;
+      let arrowRects = [];
+      for (const ob of objects) {
+        let objectInfo = objectImg[ob.id];
+        if (objectInfo == null) continue;
+
+        // // Ice palette swap for fire shooter traps
+        // if (ob.id === 8 || ob.id === 10) {
+        //   const pal = new ColorPalette();
+        //   for (let i = 0; i < 16; ++i) {
+        //     pal.setColorInt(i, objectInfo.palette.getColor(i));
+        //   }
+        //   for (let i = 0; i < FIRE_INDICES.length; ++i) {
+        //     pal.setColorInt(FIRE_INDICES[i], ICE_COLORS[i]);
+        //   }
+
+        //   const clone = new ObjectImageInfo();
+        //   Object.assign(clone, objectInfo);
+        //   clone.palette = pal;
+        //   objectInfo = clone;
+        // }
+        let tfxID = objectInfo.trigger_effect_id;
+
+        if (tfxID === 6 && (ob.id === 7 || ob.id === 8 || ob.id === 10)) {
+          tfxID = 12;
+        }
+
+        const mapOb = new MapObject(ob, objectInfo, new Animation(), tfxID, this.runtime);
+        this.objects.push(mapOb);
+        if (ob.id === 1) this.entrances.push(ob);
+
+        if (tfxID !== 0) {
+          const x1 = ob.x + objectInfo.trigger_left;
+          const y1 = ob.y + objectInfo.trigger_top;
+          const x2 = x1 + objectInfo.trigger_width;
+          const y2 = y1 + objectInfo.trigger_height;
+          let repeatDelay = 0;
+          if (tfxID != 1) {
+            if (tfxID != 5 && tfxID != 6 && tfxID != 7 && tfxID != 8 && tfxID != 12) {
+              repeatDelay = objectInfo.frameCount;
+            }
+          }
+
+          let trigger = new Trigger(tfxID, x1, y1, x2, y2, repeatDelay, objectInfo.trap_sound_effect_id, mapOb);
+          trigger.runtime = this.runtime;
+
+          if (mapOb.triggerType == 7 || mapOb.triggerType == 8) {
+            const newRange = new Range();
+            newRange.x = ob.x + objectInfo.trigger_left;
+            newRange.y = ob.y + objectInfo.trigger_top;
+            newRange.width = objectInfo.trigger_width;
+            newRange.height = objectInfo.trigger_height;
+            newRange.direction = mapOb.triggerType == 8 ? 1 : 0;
+            arrowRects.push(newRange);
+            this.arrowTriggers.push(trigger);
+          }
+
+          this.triggers.push(trigger);
+        }
+      }
+      if (arrowRects.length > 0) {
+        this.setArrowAreas(arrowRects);
+      } else {
+        this.arrowRanges = new Int32Array(0);
+      }
+      this._debugFrame = null; // invalidate cached debug overlay
+    } finally {
+      if (perfEnabled) {
+        recordPerformanceMeasure('setMapObjects', {
+          start: perfStart,
+          detail: SET_MAP_OBJECTS_MEASURE_DETAIL
+        });
+      }
+    }
+  },
+
+  getGroundMaskLayer() { return this.groundMask; },
+
+  setGroundMaskLayer(solidLayer) { this.groundMask = solidLayer; },
+
+  _markGroundDirtyAll() {
+    this._groundDirtyFull = true;
+    this._groundDirtyTiles.clear();
+    this._groundDirtyRects.length = 0;
+  },
+
+  _markGroundDirtyTilesForRect(x1, y1, x2, y2) {
+    if (this._groundDirtyFull) return;
+    const tileSize = this._groundTileSize;
+    const cols = this._groundTileColumns;
+    const rows = this._groundTileRows;
+    if (!tileSize || !cols || !rows) return;
+    const tx1 = Math.max(0, Math.floor(x1 / tileSize));
+    const ty1 = Math.max(0, Math.floor(y1 / tileSize));
+    const tx2 = Math.min(cols - 1, Math.floor((x2 - 1) / tileSize));
+    const ty2 = Math.min(rows - 1, Math.floor((y2 - 1) / tileSize));
+    for (let ty = ty1; ty <= ty2; ty += 1) {
+      const row = ty * cols;
+      for (let tx = tx1; tx <= tx2; tx += 1) {
+        this._groundDirtyTiles.add(row + tx);
+      }
+    }
+    const tileCount = cols * rows;
+    if (this._groundDirtyTiles.size >= tileCount || this._groundDirtyTiles.size > 1024) {
+      this._markGroundDirtyAll();
+    }
+  },
+
+  _consumeGroundDirtyTileRects() {
+    if (this._groundDirtyFull || !this._groundDirtyTiles.size) return [];
+    const rects = [];
+    const tileSize = this._groundTileSize;
+    const cols = this._groundTileColumns;
+    for (const index of this._groundDirtyTiles) {
+      const tx = index % cols;
+      const ty = Math.floor(index / cols);
+      const x = tx * tileSize;
+      const y = ty * tileSize;
+      rects.push({
+        x,
+        y,
+        width: Math.min(tileSize, this.width - x),
+        height: Math.min(tileSize, this.height - y)
+      });
+    }
+    this._groundDirtyTiles.clear();
+    return rects;
+  },
+
+  _markGroundDirtyRect(x, y, width, height) {
+    if (!Number.isFinite(width) || !Number.isFinite(height)) {
+      this._markGroundDirtyAll();
+      return;
+    }
+    if (width <= 0 || height <= 0) return;
+    if (this._groundDirtyFull) return;
+    const x1 = Math.max(0, Math.floor(x));
+    const y1 = Math.max(0, Math.floor(y));
+    const x2 = Math.min(this.width, Math.ceil(x + width));
+    const y2 = Math.min(this.height, Math.ceil(y + height));
+    if (x2 <= x1 || y2 <= y1) return;
+    this._markGroundDirtyTilesForRect(x1, y1, x2, y2);
+    this._groundDirtyRects.push({
+      x: x1,
+      y: y1,
+      width: x2 - x1,
+      height: y2 - y1
+    });
+    if (this._groundDirtyRects.length > 128) {
+      this._markGroundDirtyAll();
+    }
+  },
+
+  isOutOfLevel(y) { return y < 0 || y >= this.height; },
+
+  _clearGroundWithMaskInternal(mask, x, y, opts = null) {
+    let changed = false;
+    let removed = 0;
+    let minX = this.width;
+    let minY = this.height;
+    let maxX = -1;
+    let maxY = -1;
+    const revealSteel = opts?.revealSteel === true;
+    const history = getRuntimeHistory(this.runtime);
+    const gm = this.groundMask;
+    const gmMask = gm.mask;
+    const img = this.groundImage;
+    const w = this.width;
+    const { offsetX, offsetY, width: mw, height: mh } = mask;
+    const spans = getMaskTransparentSpans(mask);
+    const clearPixel = (dx, dy) => {
+      const px = x + offsetX + dx;
+      const py = y + offsetY + dy;
+      if (px < 0 || px >= this.width || py < 0 || py >= this.height) return;
+      const isSteel = this.isSteelAt(px, py);
+      if (isSteel && !revealSteel) return;
+      const maskIdx = py * w + px;
+      const imgIdx = maskIdx * 4;
+      const prevMask = gmMask[maskIdx];
+      const prevR = img[imgIdx];
+      const prevG = img[imgIdx + 1];
+      const prevB = img[imgIdx + 2];
+      const nextMask = isSteel ? prevMask : 0;
+      if (prevMask || prevR || prevG || prevB) {
+        history?.recordGroundChange?.(
+          maskIdx,
+          prevMask,
+          prevR,
+          prevG,
+          prevB,
+          nextMask,
+          0,
+          0,
+          0
+        );
+      }
+      const pixelChanged = (prevMask && !isSteel) || !!(prevR || prevG || prevB);
+      if (prevMask && !isSteel) {
+        changed = true;
+        gmMask[maskIdx] = 0;
+      }
+      if (prevR || prevG || prevB) {
+        removed += 1;
+        changed = true;
+      }
+      if (pixelChanged) {
+        if (px < minX) minX = px;
+        if (py < minY) minY = py;
+        if (px > maxX) maxX = px;
+        if (py > maxY) maxY = py;
+      }
+      img[imgIdx] = img[imgIdx + 1] = img[imgIdx + 2] = 0;
+    };
+    if (spans?.rows?.length) {
+      const rows = spans.rows;
+      const starts = spans.starts;
+      const lengths = spans.lengths;
+      for (let i = 0; i < rows.length; i += 1) {
+        const dy = rows[i];
+        const py = y + offsetY + dy;
+        if (py < 0 || py >= this.height) continue;
+        const startDx = starts[i];
+        const endDx = startDx + lengths[i];
+        const clippedStart = Math.max(startDx, -x - offsetX);
+        const clippedEnd = Math.min(endDx, this.width - x - offsetX);
+        for (let dx = clippedStart; dx < clippedEnd; dx += 1) {
+          const px = x + offsetX + dx;
+          const isSteel = this.isSteelAt(px, py);
+          if (isSteel && !revealSteel) continue;
+          const maskIdx = py * w + px;
+          const imgIdx = maskIdx * 4;
+          const prevMask = gmMask[maskIdx];
+          const prevR = img[imgIdx];
+          const prevG = img[imgIdx + 1];
+          const prevB = img[imgIdx + 2];
+          const nextMask = isSteel ? prevMask : 0;
+          if (prevMask || prevR || prevG || prevB) {
+            history?.recordGroundChange?.(
+              maskIdx,
+              prevMask,
+              prevR,
+              prevG,
+              prevB,
+              nextMask,
+              0,
+              0,
+              0
+            );
+          }
+          const pixelChanged = (prevMask && !isSteel) || !!(prevR || prevG || prevB);
+          if (prevMask && !isSteel) {
+            changed = true;
+            gmMask[maskIdx] = 0;
+          }
+          if (prevR || prevG || prevB) {
+            removed += 1;
+            changed = true;
+          }
+          if (pixelChanged) {
+            if (px < minX) minX = px;
+            if (py < minY) minY = py;
+            if (px > maxX) maxX = px;
+            if (py > maxY) maxY = py;
+          }
+          img[imgIdx] = img[imgIdx + 1] = img[imgIdx + 2] = 0;
+        }
+      }
+    } else {
+      for (let dy = 0; dy < mh; ++dy) {
+        for (let dx = 0; dx < mw; ++dx) {
+          if (mask.at(dx, dy)) continue; // Only erase where mask is TRANSPARENT
+          clearPixel(dx, dy);
+        }
+      }
+    }
+    if (changed && maxX >= minX && maxY >= minY) {
+      const width = (maxX - minX) + 1;
+      const height = (maxY - minY) + 1;
+      this._markGroundDirtyRect(minX, minY, width, height);
+      getRuntimeMiniMap(this.runtime)?.invalidateRegion?.(minX, minY, width, height);
+    }
+    return { changed, removed };
+  },
+
+  clearGroundWithMask(mask, x, y, opts = null) {
+    return this._clearGroundWithMaskInternal(mask, x, y, opts).changed;
+  },
+
+  clearGroundWithMaskCount(mask, x, y, opts = null) {
+    return this._clearGroundWithMaskInternal(mask, x, y, opts).removed;
+  },
+
+  applyGroundBulkChange(x, y, width, height, { invalidateMiniMap = true } = {}) {
+    this._markGroundDirtyRect(x, y, width, height);
+    if (invalidateMiniMap) {
+      getRuntimeMiniMap(this.runtime)?.invalidateRegion?.(x, y, width, height);
+    }
+  },
+
+  setGroundRect(x, y, width, height, paletteIndex, {
+    recordHistory = false,
+    invalidateMiniMap = true
+  } = {}) {
+    const x0 = Math.max(0, Math.floor(x));
+    const y0 = Math.max(0, Math.floor(y));
+    const x1 = Math.min(this.width, Math.ceil(x + width));
+    const y1 = Math.min(this.height, Math.ceil(y + height));
+    if (x1 <= x0 || y1 <= y0) return 0;
+    const mask = this.groundMask?.mask;
+    const gp = this.groundImage;
+    if (!mask || !gp) return 0;
+    const history = recordHistory ? getRuntimeHistory(this.runtime) : null;
+    const nextR = this.colorPalette.getR(paletteIndex);
+    const nextG = this.colorPalette.getG(paletteIndex);
+    const nextB = this.colorPalette.getB(paletteIndex);
+    let changed = 0;
+    for (let yy = y0; yy < y1; yy += 1) {
+      const row = yy * this.width;
+      for (let xx = x0; xx < x1; xx += 1) {
+        const maskIdx = row + xx;
+        const imgIdx = maskIdx * 4;
+        const prevMask = mask[maskIdx];
+        const prevR = gp[imgIdx];
+        const prevG = gp[imgIdx + 1];
+        const prevB = gp[imgIdx + 2];
+        if (prevMask === 1 && prevR === nextR && prevG === nextG && prevB === nextB) continue;
+        if (history?.recordGroundChange) {
+          history.recordGroundChange(
+            maskIdx,
+            prevMask,
+            prevR,
+            prevG,
+            prevB,
+            1,
+            nextR,
+            nextG,
+            nextB
+          );
+        }
+        mask[maskIdx] = 1;
+        gp[imgIdx] = nextR;
+        gp[imgIdx + 1] = nextG;
+        gp[imgIdx + 2] = nextB;
+        changed += 1;
+      }
+    }
+    if (changed > 0) {
+      this.applyGroundBulkChange(x0, y0, x1 - x0, y1 - y0, { invalidateMiniMap });
+    }
+    return changed;
+  },
+
+  setGroundAt(x, y, paletteIndex) {
+    const maskIdx = y * this.width + x;
+    const idx = (y * this.width + x) * 4;
+    const gp = this.groundImage;
+    const history = getRuntimeHistory(this.runtime);
+    if (history?.recordGroundChange) {
+      const prevMask = this.groundMask.mask[maskIdx];
+      const prevR = gp[idx];
+      const prevG = gp[idx + 1];
+      const prevB = gp[idx + 2];
+      const nextR = this.colorPalette.getR(paletteIndex);
+      const nextG = this.colorPalette.getG(paletteIndex);
+      const nextB = this.colorPalette.getB(paletteIndex);
+      history.recordGroundChange(
+        maskIdx,
+        prevMask,
+        prevR,
+        prevG,
+        prevB,
+        1,
+        nextR,
+        nextG,
+        nextB
+      );
+    }
+    this.groundMask.setGroundAt(x, y);
+    gp[idx]     = this.colorPalette.getR(paletteIndex);
+    gp[idx + 1] = this.colorPalette.getG(paletteIndex);
+    gp[idx + 2] = this.colorPalette.getB(paletteIndex);
+    this._markGroundDirtyRect(x, y, 1, 1);
+    getRuntimeMiniMap(this.runtime)?.onGroundChanged(x, y, false);
+  },
+
+  hasGroundAt(x, y) { return this.groundMask.hasGroundAt(x, y); },
+
+  clearGroundAt(x, y) {
+    if (this.isSteelAt(x, y)) return;
+    const idx = (y * this.width + x) * 4;
+    const gp  = this.groundImage;
+    const history = getRuntimeHistory(this.runtime);
+    if (history?.recordGroundChange) {
+      const maskIdx = y * this.width + x;
+      const prevMask = this.groundMask.mask[maskIdx];
+      const prevR = gp[idx];
+      const prevG = gp[idx + 1];
+      const prevB = gp[idx + 2];
+      history.recordGroundChange(
+        maskIdx,
+        prevMask,
+        prevR,
+        prevG,
+        prevB,
+        0,
+        0,
+        0,
+        0
+      );
+    }
+    this.groundMask.clearGroundAt(x, y);
+    gp[idx] = gp[idx + 1] = gp[idx + 2] = 0;
+    this._markGroundDirtyRect(x, y, 1, 1);
+    getRuntimeMiniMap(this.runtime)?.onGroundChanged(x, y, true);
+  },
+
+  clearGroundRow(x, y, width) {
+    if (!Number.isFinite(y) || y < 0 || y >= this.height) return 0;
+    const x0 = Math.max(0, Math.floor(x));
+    const x1 = Math.min(this.width, Math.ceil(x + width));
+    if (x1 <= x0) return 0;
+    const mask = this.groundMask?.mask;
+    const gp = this.groundImage;
+    if (!mask || !gp) return 0;
+    const yy = Math.trunc(y);
+    const row = yy * this.width;
+    const history = getRuntimeHistory(this.runtime);
+    let changed = 0;
+    let minX = this.width;
+    let maxX = -1;
+    for (let xx = x0; xx < x1; xx += 1) {
+      if (!mask[row + xx]) continue;
+      if (this.isSteelAt(xx, yy)) continue;
+      const maskIdx = row + xx;
+      const imgIdx = maskIdx * 4;
+      const prevMask = mask[maskIdx];
+      const prevR = gp[imgIdx];
+      const prevG = gp[imgIdx + 1];
+      const prevB = gp[imgIdx + 2];
+      history?.recordGroundChange?.(
+        maskIdx,
+        prevMask,
+        prevR,
+        prevG,
+        prevB,
+        0,
+        0,
+        0,
+        0
+      );
+      mask[maskIdx] = 0;
+      gp[imgIdx] = gp[imgIdx + 1] = gp[imgIdx + 2] = 0;
+      changed += 1;
+      if (xx < minX) minX = xx;
+      if (xx > maxX) maxX = xx;
+    }
+    if (changed > 0) {
+      const dirtyWidth = (maxX - minX) + 1;
+      this._markGroundDirtyRect(minX, yy, dirtyWidth, 1);
+      getRuntimeMiniMap(this.runtime)?.invalidateRegion?.(minX, yy, dirtyWidth, 1);
+    }
+    return changed;
+  }
+};
+export { levelGroundMutationMethods };
\ No newline at end of file
diff --git a/js/level/level/LevelRender.js b/js/level/level/LevelRender.js
new file mode 100644
index 00000000..8a1e434f
--- /dev/null
+++ b/js/level/level/LevelRender.js
@@ -0,0 +1,67 @@
+import {
+  Animation,
+  BaseLogger,
+  ColorPalette,
+  FIRE_INDICES,
+  Frame,
+  ICE_COLORS,
+  MapObject,
+  Range,
+  SET_MAP_OBJECTS_MEASURE_DETAIL,
+  SET_STEEL_MEASURE_DETAIL,
+  SkillTypes,
+  SolidLayer,
+  Trigger,
+  canMeasurePerformance,
+  getAppContext,
+  getMaskTransparentSpans,
+  getRuntimeApp,
+  getRuntimeHistory,
+  getRuntimeMiniMap,
+  getRuntimePerformanceContext,
+  recordPerformanceMeasure
+} from './LevelShared.js';
+const levelRenderMethods = {
+  setGroundImage(img) {
+    this.groundImage = new Uint8ClampedArray(img);
+    this._groundTileColumns = Math.max(1, Math.ceil(this.width / this._groundTileSize));
+    this._groundTileRows = Math.max(1, Math.ceil(this.height / this._groundTileSize));
+    this._markGroundDirtyAll();
+  },
+
+  setPalettes(colorPalette, groundPalette) {
+    this.colorPalette = colorPalette;
+    this.groundPalette = groundPalette;
+  },
+
+  render(gameDisplay) {
+    gameDisplay.initSize(this.width, this.height);
+    if (typeof gameDisplay.restoreBackground === 'function' &&
+          typeof gameDisplay.syncBackground === 'function') {
+      gameDisplay.setDirtyTileSize?.(this._groundTileSize);
+      gameDisplay.restoreBackground();
+      if (this._groundDirtyFull || !gameDisplay.hasBackground?.()) {
+        gameDisplay.syncBackground(this.groundImage, this.groundMask, null, this._groundTileSize);
+        gameDisplay.groundMask = this.groundMask;
+        this._groundDirtyFull = false;
+        this._groundDirtyTiles.clear();
+        this._groundDirtyRects.length = 0;
+        return;
+      }
+      if (this._groundDirtyTiles.size || this._groundDirtyRects.length) {
+        let dirtyRects = this._consumeGroundDirtyTileRects();
+        if (!dirtyRects.length && this._groundDirtyRects.length) {
+          dirtyRects = this._groundDirtyRects.slice();
+        }
+        gameDisplay.syncBackground(this.groundImage, this.groundMask, dirtyRects, this._groundTileSize);
+        gameDisplay.groundMask = this.groundMask;
+        this._groundDirtyRects.length = 0;
+        return;
+      }
+      gameDisplay.groundMask = this.groundMask;
+      return;
+    }
+    gameDisplay.setBackground(this.groundImage, this.groundMask);
+  }
+};
+export { levelRenderMethods };
\ No newline at end of file
diff --git a/js/level/level/LevelShared.js b/js/level/level/LevelShared.js
new file mode 100644
index 00000000..5f77407e
--- /dev/null
+++ b/js/level/level/LevelShared.js
@@ -0,0 +1,82 @@
+import { BaseLogger } from '../../util/LogHandler.js';
+import { Animation } from '../../render/Animation.js';
+import { ColorPalette } from '../../render/ColorPalette.js';
+import { Frame } from '../../render/Frame.js';
+import { MapObject } from '../MapObject.js';
+import { Range } from '../../util/Range.js';
+import { SkillTypes } from '../../game/SkillTypes.js';
+import { SolidLayer } from '../../render/SolidLayer.js';
+import { Trigger } from '../Trigger.js';
+import { getAppContext } from '../../core/dependencies.js';
+import {
+  getRuntimeHistory,
+  getRuntimeMiniMap,
+  getRuntimePerformanceContext
+} from '../../game/GameRuntime.js';
+import {
+  canMeasurePerformance,
+  recordPerformanceMeasure
+} from '../../util/performanceInstrumentation.js';
+
+const FIRE_INDICES = Object.freeze([3, 4, 5, 6, 10, 11, 12, 13, 14]);
+const ICE_COLORS   = Object.freeze([
+  ColorPalette.colorFromRGB(92, 224, 255),
+  ColorPalette.colorFromRGB(96, 255, 255),
+  ColorPalette.colorFromRGB(72, 192, 255),
+  ColorPalette.colorFromRGB(64, 160, 255),
+  ColorPalette.colorFromRGB(4, 48, 136),
+  ColorPalette.colorFromRGB(0, 64, 152),
+  ColorPalette.colorFromRGB(2, 32, 120),
+  ColorPalette.colorFromRGB(0, 64, 152),
+  ColorPalette.colorFromRGB(64, 160, 255)
+]);
+const SET_MAP_OBJECTS_MEASURE_DETAIL = Object.freeze({
+  devtools: Object.freeze({
+    track: 'Level',
+    trackGroup: 'Game State',
+    color: 'primary-light',
+    tooltipText: 'setMapObjects'
+  })
+});
+const SET_STEEL_MEASURE_DETAIL = Object.freeze({
+  devtools: Object.freeze({
+    track: 'Level',
+    trackGroup: 'Game State',
+    color: 'secondary-light',
+    tooltipText: 'newSetSteelAreas'
+  })
+});
+const getRuntimeApp = (runtime = null) => getRuntimePerformanceContext(runtime) || getAppContext();
+const getMaskTransparentSpans = (mask) => {
+  if (!mask) return null;
+  if (typeof mask.getTransparentSpans === 'function') {
+    return mask.getTransparentSpans();
+  }
+  const spans = mask.transparentSpans || null;
+  if (spans?.rows && spans?.starts && spans?.lengths) return spans;
+  return null;
+};
+
+export {
+  Animation,
+  BaseLogger,
+  ColorPalette,
+  FIRE_INDICES,
+  Frame,
+  ICE_COLORS,
+  MapObject,
+  Range,
+  SET_MAP_OBJECTS_MEASURE_DETAIL,
+  SET_STEEL_MEASURE_DETAIL,
+  SkillTypes,
+  SolidLayer,
+  Trigger,
+  canMeasurePerformance,
+  getAppContext,
+  getMaskTransparentSpans,
+  getRuntimeApp,
+  getRuntimeHistory,
+  getRuntimeMiniMap,
+  getRuntimePerformanceContext,
+  recordPerformanceMeasure
+};
diff --git a/js/level/packMechanics.js b/js/level/packMechanics.js
index 8f48462f..c7d28840 100644
--- a/js/level/packMechanics.js
+++ b/js/level/packMechanics.js
@@ -5,27 +5,45 @@
 export const packMechanics = {
   lemmings: {
     classicBuilder: true,
-    bomberAssist: false
+    bomberAssist: false,
+    pauseGlitch: true,
+    nukeGlitch: true,
+    rightClickGlitch: true
   },
   lemmings_ohNo: {
     classicBuilder: true,
-    bomberAssist: false
+    bomberAssist: false,
+    pauseGlitch: true,
+    nukeGlitch: true,
+    rightClickGlitch: true
   },
   xmas91: {
     classicBuilder: true,
-    bomberAssist: false
+    bomberAssist: false,
+    pauseGlitch: true,
+    nukeGlitch: true,
+    rightClickGlitch: true
   },
   xmas92: {
     classicBuilder: true,
-    bomberAssist: false
+    bomberAssist: false,
+    pauseGlitch: true,
+    nukeGlitch: true,
+    rightClickGlitch: true
   },
   holiday93: {
     classicBuilder: false,
-    bomberAssist: true
+    bomberAssist: true,
+    pauseGlitch: false,
+    nukeGlitch: false,
+    rightClickGlitch: false
   },
   holiday94: {
     classicBuilder: false,
-    bomberAssist: true
+    bomberAssist: true,
+    pauseGlitch: false,
+    nukeGlitch: false,
+    rightClickGlitch: false
   }
 };
 export default packMechanics;
diff --git a/js/midi/MidiEventRouter.js b/js/midi/MidiEventRouter.js
index 274280b2..f11ad253 100644
--- a/js/midi/MidiEventRouter.js
+++ b/js/midi/MidiEventRouter.js
@@ -1,506 +1 @@
-import { MidiMapping } from './MidiMapping.js';
-import { MidiScheduler } from './MidiScheduler.js';
-
-const MAX_EVENTS_PER_TICK = 32;
-const MAX_MIDI_MESSAGES_PER_SECOND = 1000;
-
-class MidiEventRouter {
-  constructor(mapping = null) {
-    this.mapping = mapping instanceof MidiMapping ? mapping : new MidiMapping(mapping || {});
-    this.scheduler = new MidiScheduler(this.mapping.config);
-    this.soundBus = null;
-    this.context = {};
-    this._lastTickBySfx = new Map();
-    this._tickCounter = { tick: null, count: 0 };
-    this._clockBaseMs = null;
-    this._clockFrameMs = null;
-    this._clockSpeedFactor = null;
-    this._lastAcceptedBySfx = new Map();
-    this._arpStateBySfx = new Map();
-    this._repeatHistoryByKey = new Map();
-    this._lastRateReport = null;
-    this._boundOnEvent = this._onEvent.bind(this);
-  }
-
-  setMapping(mapping) {
-    this.mapping = mapping instanceof MidiMapping ? mapping : new MidiMapping(mapping || {});
-    this.scheduler.setConfig(this.mapping.config);
-  }
-
-  setOutput(output) {
-    this.scheduler.setOutput(output);
-  }
-
-  attach(soundBus, context = {}) {
-    if (this.soundBus?.onEvent) {
-      this.soundBus.onEvent.off(this._boundOnEvent);
-    }
-    this.soundBus = soundBus;
-    this.context = context || {};
-    this.soundBus?.onEvent?.on(this._boundOnEvent);
-  }
-
-  detach() {
-    if (this.soundBus?.onEvent) {
-      this.soundBus.onEvent.off(this._boundOnEvent);
-    }
-    this.soundBus = null;
-  }
-
-  _tickMsFromEvent(event) {
-    if (event?.tps) return 1000 / event.tps;
-    if (event?.frameMs) return event.frameMs;
-    const timer = this.context?.game?.getGameTimer?.();
-    return timer?.frameTime ?? 60;
-  }
-
-  _densityForEvent(event) {
-    const windowTicks = this.mapping.config?.density?.windowTicks ?? 0;
-    if (!windowTicks || event?.tick == null || event?.sfxId == null) return 0;
-    const last = this._lastTickBySfx.get(event.sfxId);
-    if (last == null) return 0;
-    const delta = event.tick - last;
-    if (delta <= 0) return 1;
-    if (delta >= windowTicks) return 0;
-    return (windowTicks - delta) / windowTicks;
-  }
-
-  _nowMs() {
-    return typeof performance !== 'undefined' ? performance.now() : Date.now();
-  }
-
-  _resolveScheduleBase(eventTimeMs, frameMs, speedFactor) {
-    if (!Number.isFinite(eventTimeMs)) return null;
-    const frameChanged = Number.isFinite(frameMs) &&
-      this._clockFrameMs != null &&
-      Math.abs(frameMs - this._clockFrameMs) > 0.001;
-    const speedChanged = Number.isFinite(speedFactor) &&
-      this._clockSpeedFactor != null &&
-      speedFactor !== this._clockSpeedFactor;
-    if (frameChanged || speedChanged) {
-      this._clockBaseMs = null;
-      this._lastAcceptedBySfx.clear();
-      this._arpStateBySfx.clear();
-      this._repeatHistoryByKey.clear();
-      this.scheduler?.allNotesOff?.();
-      this.scheduler?.clearQueue?.();
-    }
-    if (this._clockBaseMs == null) {
-      this._clockBaseMs = this._nowMs() - eventTimeMs;
-    }
-    if (Number.isFinite(frameMs)) this._clockFrameMs = frameMs;
-    if (Number.isFinite(speedFactor)) this._clockSpeedFactor = speedFactor;
-    return this._clockBaseMs;
-  }
-
-  _getEventPriority(event, sfx) {
-    if (Number.isFinite(sfx?.priority)) return sfx.priority;
-    const priorityList = this.mapping.config?.limits?.prioritySfx || [];
-    if (priorityList.includes(event?.sfxId)) return 2;
-    return 1;
-  }
-
-  _getBpm() {
-    const base = this.mapping.config?.timing?.bpmBase ?? 120;
-    const speed = this.context?.game?.getGameTimer?.()?.speedFactor ?? 1;
-    return Math.max(20, base * speed);
-  }
-
-  _resolveArpKey(event, sfx) {
-    if (event?.triggerType != null && sfx?.arp?.independent) {
-      const objectId = Number.isFinite(event.objectId) ? event.objectId : null;
-      if (objectId != null) {
-        return `trigger:${event.triggerType}:${event.sfxId}:object:${objectId}`;
-      }
-      const lemmingId = Number.isFinite(event.lemmingId) ? event.lemmingId : null;
-      if (lemmingId != null) {
-        return `trigger:${event.triggerType}:${event.sfxId}:lemming:${lemmingId}`;
-      }
-      const x = Number.isFinite(event.x) ? Math.round(event.x) : 'x';
-      const y = Number.isFinite(event.y) ? Math.round(event.y) : 'y';
-      return `trigger:${event.triggerType}:${event.sfxId}:${x}:${y}`;
-    }
-    return `sfx:${event?.sfxId ?? 'unknown'}`;
-  }
-
-  _getRepeatFactor(key, timeMs, repeatCfg, bpm) {
-    if (repeatCfg?.enabled === false) return 0;
-    const maxRepeats = Math.max(0, repeatCfg.maxRepeats ?? 0);
-    const windowBeats = repeatCfg.windowBeats ?? repeatCfg.spacingTicks ?? 0;
-    if (maxRepeats <= 0 || !Number.isFinite(timeMs) || windowBeats <= 0 || bpm <= 0) {
-      return 0;
-    }
-    const windowMs = (60000 / bpm) * windowBeats;
-    const history = this._repeatHistoryByKey.get(key) || [];
-    const cutoff = timeMs - windowMs;
-    const nextHistory = history.filter(entry => entry >= cutoff);
-    nextHistory.push(timeMs);
-    this._repeatHistoryByKey.set(key, nextHistory);
-    const repeatCount = Math.max(0, nextHistory.length - 1);
-    return Math.min(repeatCount / maxRepeats, 1);
-  }
-
-  _applyRepeatTarget(spec, activeNotes, repeatCfg, repeatFactor) {
-    if (!spec || repeatFactor <= 0) return { spec, activeNotes };
-    const hasAmount = Number.isFinite(repeatCfg.amount);
-    if (!hasAmount) return { spec, activeNotes };
-    const amount = repeatCfg.amount;
-    if (!amount) return { spec, activeNotes };
-    const delta = amount * repeatFactor;
-    const noteRange = this.mapping.config?.noteRange || { min: 0, max: 127 };
-    const positionCfg = this.mapping.config?.position || {};
-    const clampNote = value => Math.max(noteRange.min ?? 0, Math.min(noteRange.max ?? 127, value));
-    const clampValue = (value, min, max) => Math.max(min, Math.min(max, value));
-    const target = repeatCfg.target || 'velocity';
-    const updated = { ...spec };
-    let notes = activeNotes;
-
-    switch (target) {
-    case 'velocity':
-    case 'accent': {
-      const velocity = updated.velocity ?? 64;
-      updated.velocity = clampValue(Math.round(velocity * (1 + delta)), 1, 127);
-      return { spec: updated, activeNotes: notes };
-    }
-    case 'duration': {
-      const duration = updated.durationTicks ?? 1;
-      updated.durationTicks = Math.max(1, Math.round(duration * (1 + delta)));
-      return { spec: updated, activeNotes: notes };
-    }
-    case 'note': {
-      const noteDelta = Math.round(delta * 12);
-      notes = notes.map(note => clampNote(note + noteDelta));
-      updated.note = notes[0];
-      updated.notes = notes;
-      return { spec: updated, activeNotes: notes };
-    }
-    case 'timbre': {
-      if (!Number.isFinite(updated.timbre)) return { spec: updated, activeNotes: notes };
-      const tMin = positionCfg.timbreRange?.min ?? 0;
-      const tMax = positionCfg.timbreRange?.max ?? 127;
-      const range = tMax - tMin;
-      updated.timbre = clampValue(updated.timbre + delta * range, tMin, tMax);
-      return { spec: updated, activeNotes: notes };
-    }
-    case 'pan': {
-      if (!Number.isFinite(updated.pan)) return { spec: updated, activeNotes: notes };
-      const pMin = positionCfg.panRange?.min ?? -127;
-      const pMax = positionCfg.panRange?.max ?? 127;
-      const range = pMax - pMin;
-      updated.pan = clampValue(updated.pan + delta * range, pMin, pMax);
-      return { spec: updated, activeNotes: notes };
-    }
-    case 'pitchBend': {
-      if (!Number.isFinite(updated.pitchBend)) return { spec: updated, activeNotes: notes };
-      updated.pitchBend = clampValue(updated.pitchBend + delta, -1, 1);
-      return { spec: updated, activeNotes: notes };
-    }
-    case 'attack':
-    case 'decay': {
-      const velocity = updated.velocity ?? 64;
-      updated.velocity = clampValue(Math.round(velocity * (1 + delta)), 1, 127);
-      return { spec: updated, activeNotes: notes };
-    }
-    case 'sustain': {
-      const duration = updated.durationTicks ?? 1;
-      updated.durationTicks = Math.max(1, Math.round(duration * (1 + delta)));
-      return { spec: updated, activeNotes: notes };
-    }
-    case 'release': {
-      const releaseVelocity = updated.releaseVelocity ?? updated.velocity ?? 64;
-      updated.releaseVelocity = clampValue(Math.round(releaseVelocity * (1 + delta)), 1, 127);
-      return { spec: updated, activeNotes: notes };
-    }
-    default:
-      return { spec: updated, activeNotes: notes };
-    }
-  }
-
-  _planEntries(spec, sendTimeMs, noteCount = 1) {
-    const durationMs = Number.isFinite(spec.durationTicks) ? Math.max(0, spec.durationTicks * this.scheduler.tickMs) : 0;
-    const offTimeMs = sendTimeMs + durationMs;
-    const offMessages = durationMs > 0 ? (1 + (this.mapping.config?.mpe?.enabled ? 1 : 0)) : 0;
-    const estimate = this.scheduler.estimateMessages(spec);
-    const onMessages = Math.max(estimate.messages - offMessages, 0);
-    const onBytes = onMessages * 3;
-    const offBytes = offMessages * 3;
-    return {
-      on: { timeMs: sendTimeMs, count: onMessages * noteCount, bytes: onBytes * noteCount },
-      off: { timeMs: offTimeMs, count: offMessages * noteCount, bytes: offBytes * noteCount }
-    };
-  }
-
-  _shouldSend(meta, spec, plan, now) {
-    const limits = this.mapping.config?.limits || {};
-    const maxPerSecond = Math.min(Math.max(limits.maxEventsPerSecond ?? MAX_MIDI_MESSAGES_PER_SECOND, 1), MAX_MIDI_MESSAGES_PER_SECOND);
-    const hardMaxPerSecond = Math.min(
-      Math.max(limits.hardMaxEventsPerSecond ?? maxPerSecond, 1),
-      MAX_MIDI_MESSAGES_PER_SECOND
-    );
-    const snapshot = this.scheduler.getRateSnapshot(now);
-    const maxBytes = limits.maxBytesPerSecond ?? snapshot.maxBytesPerSecond;
-    const windowEnd = now + 1000;
-    let nextCount = snapshot.next.count;
-    let nextBytes = snapshot.next.bytes;
-    if (plan.on.timeMs >= now && plan.on.timeMs < windowEnd) {
-      nextCount += plan.on.count;
-      nextBytes += plan.on.bytes;
-    }
-    if (plan.off.timeMs >= now && plan.off.timeMs < windowEnd) {
-      nextCount += plan.off.count;
-      nextBytes += plan.off.bytes;
-    }
-    if (nextCount <= maxPerSecond && nextBytes <= maxBytes) {
-      return true;
-    }
-    if (nextBytes > maxBytes) {
-      this._lastRateReport = {
-        timeMs: now,
-        reason: 'byte-limit',
-        snapshot: this.scheduler.getUsageShare('next', now)
-      };
-      return false;
-    }
-    if (nextCount > hardMaxPerSecond) {
-      this._lastRateReport = {
-        timeMs: now,
-        reason: 'count-limit',
-        snapshot: this.scheduler.getUsageShare('next', now)
-      };
-      return false;
-    }
-    const plannedCount = nextCount - snapshot.next.count;
-    const plannedBytes = nextBytes - snapshot.next.bytes;
-    const priority = meta.priority ?? 1;
-    const bySfx = snapshot.next.bySfx;
-    let higherCount = 0;
-    let higherBytes = 0;
-    let sameGroupCount = 0;
-    let sameGroupBytes = 0;
-    const samePriority = [];
-    for (const [sfxId, entry] of bySfx.entries()) {
-      const entryPriority = entry.priority ?? 1;
-      if (entryPriority > priority) {
-        higherCount += entry.count;
-        higherBytes += entry.bytes;
-      } else if (entryPriority === priority) {
-        samePriority.push({ sfxId, count: entry.count, bytes: entry.bytes, priority: entryPriority });
-        sameGroupCount += entry.count;
-        sameGroupBytes += entry.bytes;
-      }
-    }
-    const available = Math.max(0, maxPerSecond - higherCount);
-    const availableBytes = Math.max(0, maxBytes - higherBytes);
-    if (available <= 0) {
-      this._lastRateReport = {
-        timeMs: now,
-        reason: 'priority-saturated',
-        snapshot: this.scheduler.getUsageShare('next', now)
-      };
-      return false;
-    }
-    if (availableBytes <= 0) {
-      this._lastRateReport = {
-        timeMs: now,
-        reason: 'byte-limit',
-        snapshot: this.scheduler.getUsageShare('next', now)
-      };
-      return false;
-    }
-
-    const shareReport = this.scheduler.getUsageShare('next', now);
-    const sameGroup = shareReport.filter(entry => entry.priority === priority);
-    const current = sameGroup.find(entry => entry.sfxId === meta.sfxId);
-    const groupSize = sameGroup.length + (current ? 0 : 1);
-    const evenShare = 1 / groupSize;
-    const shareRatio = (current?.percentCount ?? evenShare) / evenShare;
-    const projectedGroupCount = sameGroupCount + plannedCount;
-    const projectedGroupBytes = sameGroupBytes + plannedBytes;
-    const overCount = projectedGroupCount > available
-      ? projectedGroupCount / Math.max(available, 1)
-      : 1;
-    const overBytes = projectedGroupBytes > availableBytes
-      ? projectedGroupBytes / Math.max(availableBytes, 1)
-      : 1;
-    const overageFactor = Math.max(1, overCount, overBytes);
-    const budgetCount = available / Math.max(groupSize, 1);
-    const budgetBytes = availableBytes / Math.max(groupSize, 1);
-    const projectedCount = (current?.count ?? 0) + plannedCount;
-    const projectedBytes = (current?.bytes ?? 0) + plannedBytes;
-    const overBudget = (budgetCount > 0 && projectedCount > budgetCount) ||
-      (budgetBytes > 0 && projectedBytes > budgetBytes);
-    const bpm = this._getBpm();
-    const beatMs = 60000 / bpm;
-    const spacingMs = beatMs * Math.max(1, shareRatio, overageFactor) / Math.max(priority, 1);
-    const lastAccepted = this._lastAcceptedBySfx.get(meta.sfxId) ?? -Infinity;
-    const okSpacing = (spec.timeMs ?? now) - lastAccepted >= spacingMs;
-    const limitReason = overBudget ? 'share-throttle' : 'count-limit';
-    this._lastRateReport = {
-      timeMs: now,
-      reason: okSpacing ? limitReason : 'spacing',
-      snapshot: shareReport
-    };
-    if (!okSpacing || overBudget) return false;
-    return true;
-  }
-
-  getRateReport() {
-    return this._lastRateReport;
-  }
-
-  getRateSnapshot() {
-    return this.scheduler.getRateSnapshot();
-  }
-
-  getUsageShare(window = 'past') {
-    return this.scheduler.getUsageShare(window);
-  }
-
-  _onEvent(event) {
-    const perfEnabled = typeof lemmings !== 'undefined' &&
-      (lemmings.performanceAPI === true || lemmings.perfMetrics === true) &&
-      typeof performance !== 'undefined' &&
-      typeof performance.measure === 'function' &&
-      typeof performance.now === 'function';
-    const perfStart = perfEnabled ? performance.now() : 0;
-    try {
-      if (!event || event.sfxId == null) return;
-      if (!this.mapping.config?.enabled) return;
-      if (!this.scheduler.output) return;
-      const now = this._nowMs();
-      const tick = event.tick;
-      if (tick != null && this._tickCounter.tick !== tick) {
-        this._tickCounter.tick = tick;
-        this._tickCounter.count = 0;
-      }
-      const limits = this.mapping.config?.limits || {};
-      const maxPerTick = Math.min(Math.max(limits.maxEventsPerTick ?? MAX_EVENTS_PER_TICK, 1), MAX_EVENTS_PER_TICK);
-      const tickMs = this._tickMsFromEvent(event);
-      this.scheduler.setTickMs(tickMs);
-      const density = this._densityForEvent(event);
-      const viewRect = this.context?.stage?.getGameViewRect?.() || null;
-      const context = {
-        levelWidth: this.context?.game?.level?.width ?? this.context?.level?.width ?? null,
-        levelHeight: this.context?.game?.level?.height ?? this.context?.level?.height ?? null,
-        viewRect
-      };
-      const baseSfx = this.mapping.getSfxConfig(event.sfxId) || {};
-      const triggerCfg = event?.triggerType != null
-        ? this.mapping.config?.triggers?.[String(event.triggerType)] || null
-        : null;
-      const sfx = triggerCfg ? { ...baseSfx, ...triggerCfg } : baseSfx;
-      const spec = this.mapping.mapEvent(event, context, density, sfx);
-      if (!spec) return;
-      spec.reverse = !!event.reverse;
-      if (tick != null && this._tickCounter.count >= maxPerTick) return;
-      if (tick != null) {
-        this._tickCounter.count += 1;
-      }
-      if (event.tick != null) {
-        this._lastTickBySfx.set(event.sfxId, event.tick);
-      }
-      const priority = this._getEventPriority(event, sfx);
-      const meta = { sfxId: event.sfxId, eventType: event.type, priority, triggerType: event.triggerType ?? null };
-      const scheduleAhead = this.mapping.config?.timing?.scheduleAheadMs ?? 0;
-      const base = this._resolveScheduleBase(event.timeMs, event.frameMs, event.speedFactor);
-      const rawTime = Number.isFinite(event.timeMs) && base != null ? base + event.timeMs : now;
-      const sendTimeMs = Math.max(rawTime, now + scheduleAhead);
-      const noteList = Array.isArray(spec.notes) && spec.notes.length ? spec.notes : [spec.note];
-
-      const arp = spec.arp;
-      let activeNotes = noteList.slice();
-      if (arp?.enabled && noteList.length) {
-        const sorted = noteList.slice().sort((a, b) => a - b);
-        const length = Math.max(1, Math.min(arp.length ?? sorted.length, sorted.length));
-        const seq = sorted.slice(0, length);
-        const seqKey = seq.join(',');
-        const arpKey = this._resolveArpKey(event, sfx);
-        const state = this._arpStateBySfx.get(arpKey) || {
-          index: 0,
-          dir: 1,
-          mode: arp.mode,
-          length,
-          seqKey
-        };
-        if (state.mode !== arp.mode || state.length !== length || state.seqKey !== seqKey) {
-          state.index = 0;
-          state.dir = 1;
-        }
-        state.mode = arp.mode;
-        state.length = length;
-        state.seqKey = seqKey;
-        let idx = state.index;
-        if (idx >= seq.length || idx < 0) idx = 0;
-        if (seq.length <= 1) {
-          activeNotes = [seq[0]];
-          state.index = 0;
-          state.dir = 1;
-        } else if (arp.mode === 'down') {
-          const reversed = seq.slice().reverse();
-          activeNotes = [reversed[idx]];
-          state.index = idx + 1;
-        } else if (arp.mode === 'updown') {
-          activeNotes = [seq[idx]];
-          if (idx + state.dir >= seq.length || idx + state.dir < 0) {
-            state.dir *= -1;
-          }
-          state.index = idx + state.dir;
-        } else {
-          activeNotes = [seq[idx]];
-          state.index = idx + 1;
-        }
-        this._arpStateBySfx.set(arpKey, state);
-      }
-
-      const repeatCfg = { ...(this.mapping.config?.repeat || {}), ...(sfx.repeat || {}) };
-      const bpm = this._getBpm();
-      const repeatKey = event?.triggerType != null
-        ? `trigger:${event.triggerType}:${event.sfxId}`
-        : `sfx:${event.sfxId}`;
-      const repeatFactor = this._getRepeatFactor(repeatKey, sendTimeMs, repeatCfg, bpm);
-      const hasAmount = Number.isFinite(repeatCfg.amount);
-      const velocityBoost = hasAmount ? 0 : (repeatCfg.velocityBoost ?? 0);
-      const durationBoost = hasAmount ? 0 : (repeatCfg.durationBoost ?? 0);
-      const velocityScale = 1 + velocityBoost * repeatFactor;
-      const durationScale = 1 + durationBoost * repeatFactor;
-      let specWithTime = {
-        ...spec,
-        timeMs: sendTimeMs,
-        velocity: Math.max(1, Math.min(127, Math.round((spec.velocity ?? 64) * velocityScale))),
-        durationTicks: Math.max(1, Math.round((spec.durationTicks ?? 1) * durationScale))
-      };
-      if (hasAmount && repeatFactor > 0) {
-        const adjusted = this._applyRepeatTarget(specWithTime, activeNotes, repeatCfg, repeatFactor);
-        specWithTime = adjusted.spec;
-        activeNotes = adjusted.activeNotes;
-      }
-      const plan = this._planEntries(specWithTime, sendTimeMs, activeNotes.length);
-      if (!this._shouldSend(meta, specWithTime, plan, now)) {
-        return;
-      }
-      for (const note of activeNotes) {
-        const adjusted = { ...specWithTime, note };
-        this.scheduler.sendNote(adjusted, meta);
-      }
-      this._lastAcceptedBySfx.set(event.sfxId, sendTimeMs);
-    } finally {
-      if (perfEnabled) {
-        try {
-          performance.measure('MidiEventRouter onEvent', {
-            start: perfStart,
-            detail: { devtools: { track: 'MidiEventRouter', trackGroup: 'MIDI', color: 'primary', tooltipText: 'onEvent' } }
-          });
-        } catch {
-          /* ignored */
-        }
-      }
-    }
-  }
-
-  dispose() {
-    this.detach();
-    this.scheduler.dispose();
-  }
-}
-
-export { MidiEventRouter };
+export { MidiEventRouter } from './router/MidiEventRouterCore.js';
diff --git a/js/midi/MidiFlagTriggers.js b/js/midi/MidiFlagTriggers.js
new file mode 100644
index 00000000..335dc0c2
--- /dev/null
+++ b/js/midi/MidiFlagTriggers.js
@@ -0,0 +1,49 @@
+const MIDI_FLAG_TRIGGER_BASE = 1000;
+const MIDI_FLAG_TRIGGER_MAX = 9999;
+
+/**
+ * Parse and clamp a MIDI flag id to the supported trigger id space.
+ * Returns null when the input cannot map to a valid positive flag id.
+ */
+const clampMidiFlagId = (value) => {
+  if (!Number.isFinite(value)) return null;
+  const id = Math.trunc(value);
+  if (id < 1) return null;
+  if (id > MIDI_FLAG_TRIGGER_MAX) return MIDI_FLAG_TRIGGER_MAX;
+  return id;
+};
+
+/**
+ * Convert a MIDI flag id into a trigger type used by MIDI mapping lookups.
+ */
+const toMidiFlagTriggerType = (flagId) => {
+  const id = clampMidiFlagId(flagId);
+  if (!id) return null;
+  return MIDI_FLAG_TRIGGER_BASE + id;
+};
+
+/**
+ * Convert a trigger type back to its MIDI flag id when it is in the MIDI
+ * flag trigger range.
+ */
+const fromMidiFlagTriggerType = (triggerType) => {
+  if (!Number.isFinite(triggerType)) return null;
+  const value = Math.trunc(triggerType);
+  const maxTriggerType = MIDI_FLAG_TRIGGER_BASE + MIDI_FLAG_TRIGGER_MAX;
+  if (value <= MIDI_FLAG_TRIGGER_BASE || value > maxTriggerType) return null;
+  return value - MIDI_FLAG_TRIGGER_BASE;
+};
+
+/**
+ * Check whether a trigger type belongs to the MIDI flag trigger namespace.
+ */
+const isMidiFlagTriggerType = (triggerType) => fromMidiFlagTriggerType(triggerType) !== null;
+
+export {
+  MIDI_FLAG_TRIGGER_BASE,
+  MIDI_FLAG_TRIGGER_MAX,
+  clampMidiFlagId,
+  toMidiFlagTriggerType,
+  fromMidiFlagTriggerType,
+  isMidiFlagTriggerType
+};
diff --git a/js/midi/MidiMapping.js b/js/midi/MidiMapping.js
index 7908a294..39e5d601 100644
--- a/js/midi/MidiMapping.js
+++ b/js/midi/MidiMapping.js
@@ -1,350 +1,22 @@
-const DEFAULT_SCALES = Object.freeze({
-  major: [0, 2, 4, 5, 7, 9, 11],
-  minor: [0, 2, 3, 5, 7, 8, 10],
-  dorian: [0, 2, 3, 5, 7, 9, 10],
-  mixolydian: [0, 2, 4, 5, 7, 9, 10],
-  pentatonic: [0, 2, 4, 7, 9],
-  chromatic: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11],
-  'chromatic-minor': [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
-});
-
-const DEFAULT_CONFIG = Object.freeze({
-  enabled: true,
-  mpe: {
-    enabled: true,
-    masterChannel: 1,
-    memberChannels: [2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16],
-    pitchBendRange: { semitones: 24, cents: 0 },
-    timbreCc: 74
-  },
-  scale: {
-    name: 'chromatic-minor',
-    root: 0,
-    degrees: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
-  },
-  timing: {
-    bpmBase: 120,
-    scheduleAheadMs: 0,
-    timeSignature: { beats: 4, unit: 4 }
-  },
-  reverse: {
-    allNotesOffOnToggle: false
-  },
-  noteDefaults: {
-    octave: 4,
-    degree: 0,
-    chord: 'triad'
-  },
-  noteRange: { min: 36, max: 84 },
-  velocityRange: { min: 20, max: 110, default: 80 },
-  durationTicks: { default: 6, min: 2, max: 24 },
-  envelope: {
-    attack: 1,
-    decay: 0,
-    sustain: 1,
-    release: 1
-  },
-  limits: {
-    windowMs: 1000,
-    maxEventsPerTick: 32,
-    hardMaxEventsPerTick: 128,
-    maxEventsPerSecond: 900,
-    hardMaxEventsPerSecond: 1000,
-    maxBytesPerSecond: 3906,
-    overloadCooldownMs: 500,
-    maxActiveNotes: 32,
-    prioritySfx: [2, 3, 16]
-  },
-  density: { windowTicks: 24, velocityBoost: 0.4, durationScale: 0.5 },
-  repeat: {
-    maxRepeats: 0,
-    windowBeats: 4,
-    spacingTicks: 2,
-    target: 'velocity',
-    amount: 0.15,
-    velocityBoost: 0,
-    durationBoost: 0
-  },
-  position: {
-    xToNote: false,
-    xNoteRange: { min: -12, max: 12 },
-    yToVelocity: true,
-    yToTimbre: true,
-    timbreRange: { min: 20, max: 110 },
-    viewPan: false,
-    panRange: { min: -127, max: 127 },
-    panDeadZonePct: 0.02,
-    panOnscreenWeight: 0.8,
-    panOffscreenWeight: 0.2,
-    panOffscreenRange: 1
-  },
-  input: {
-    enabled: true,
-    channel: 'omni',
-    transport: {
-      start: 'restart',
-      stop: 'pause',
-      continue: 'resume'
-    },
-    notes: {
-      skillBase: 60,
-      skillOrder: [
-        'CLIMBER',
-        'FLOATER',
-        'BOMBER',
-        'BLOCKER',
-        'BUILDER',
-        'BASHER',
-        'MINER',
-        'DIGGER'
-      ],
-      actions: {
-        pause: 36,
-        resume: 38,
-        restart: 40,
-        speedDown: 41,
-        speedUp: 43,
-        speedReset: 45,
-        toggleMidi: 47,
-        toggleViewPan: 49
-      }
-    },
-    cc: {
-      speed: { cc: 1, min: 0.1, max: 8 },
-      bpmBase: { cc: 74, min: 60, max: 200 },
-      intensity: { cc: 7, min: 10, max: 127 },
-      accent: { cc: 11, min: 0, max: 1 },
-      keyRoot: { cc: 16, min: 0, max: 11, round: true, target: 'scale.root' },
-      scaleName: {
-        cc: 17,
-        target: 'scale.name',
-        values: ['chromatic-minor', 'major', 'minor', 'dorian', 'mixolydian', 'pentatonic', 'chromatic']
-      },
-      xToNote: { cc: 18, toggle: true, target: 'position.xToNote' },
-      yToVelocity: { cc: 19, toggle: true, target: 'position.yToVelocity' },
-      yToTimbre: { cc: 20, toggle: true, target: 'position.yToTimbre' },
-      viewPan: { cc: 21, toggle: true, target: 'position.viewPan' },
-      repeatCount: { cc: 22, min: 0, max: 32, round: true, target: 'repeat.maxRepeats' },
-      repeatSpacing: { cc: 23, min: 1, max: 8, round: true, target: 'repeat.windowBeats' },
-      envAttack: { cc: 24, min: 0, max: 2, target: 'envelope.attack' },
-      envDecay: { cc: 25, min: 0, max: 2, target: 'envelope.decay' },
-      envSustain: { cc: 26, min: 0, max: 1, target: 'envelope.sustain' },
-      envRelease: { cc: 27, min: 0, max: 2, target: 'envelope.release' },
-      chordType: {
-        cc: 28,
-        target: 'noteDefaults.chord',
-        values: ['triad', 'seventh', 'sixth', 'ninth', 'power', 'sus2', 'sus4', 'octave']
-      },
-      chordOctave: { cc: 29, min: 1, max: 8, round: true, target: 'noteDefaults.octave' },
-      chordDegree: { cc: 30, min: 0, max: 6, round: true, target: 'noteDefaults.degree' },
-      duration: { cc: 31, min: 1, max: 24, round: true, target: 'durationTicks.default' },
-      timeSignatureBeats: { cc: 80, min: 1, max: 12, round: true, target: 'timing.timeSignature.beats' },
-      timeSignatureUnit: { cc: 81, values: [1, 2, 4, 8, 16], target: 'timing.timeSignature.unit' }
-    }
-  },
-  triggers: {},
-  sfx: {}
-});
-
-const isPlainObject = (val) => val && typeof val === 'object' && !Array.isArray(val);
-
-const mergeConfig = (base, override) => {
-  if (!override) return { ...base };
-  const out = { ...base };
-  for (const [key, val] of Object.entries(override)) {
-    if (isPlainObject(val) && isPlainObject(base[key])) {
-      out[key] = mergeConfig(base[key], val);
-    } else {
-      out[key] = val;
-    }
-  }
-  return out;
-};
-
-const clamp = (value, min, max) => Math.max(min, Math.min(max, value));
-const lerp = (a, b, t) => a + (b - a) * t;
-
-const resolvePositionMappings = (positionCfg, velocityRange) => {
-  if (Array.isArray(positionCfg?.mappings)) return positionCfg.mappings;
-  const mappings = [];
-  if (positionCfg?.xToNote) {
-    const xRange = positionCfg.xNoteRange || {};
-    mappings.push({
-      axis: 'x',
-      target: 'note',
-      min: xRange.min ?? 0,
-      max: xRange.max ?? 0,
-      enabled: true
-    });
-  }
-  if (positionCfg?.yToVelocity) {
-    const velMin = velocityRange?.min ?? 1;
-    const velMax = velocityRange?.max ?? 127;
-    mappings.push({
-      axis: 'y',
-      target: 'velocity',
-      min: velMax,
-      max: velMin,
-      enabled: true
-    });
-  }
-  if (positionCfg?.yToTimbre) {
-    const tMin = positionCfg.timbreRange?.min ?? 0;
-    const tMax = positionCfg.timbreRange?.max ?? 127;
-    mappings.push({
-      axis: 'y',
-      target: 'timbre',
-      min: tMax,
-      max: tMin,
-      enabled: true
-    });
-  }
-  return mappings;
-};
-
-const resolveAxisValues = (event, context) => {
-  const xNorm = context.levelWidth && event?.x != null
-    ? clamp(event.x / context.levelWidth, 0, 1)
-    : null;
-  const yNorm = context.levelHeight && event?.y != null
-    ? clamp(event.y / context.levelHeight, 0, 1)
-    : null;
-  const xyNorm = (xNorm != null && yNorm != null)
-    ? clamp((xNorm + yNorm) / 2, 0, 1)
-    : null;
-  return { x: xNorm, y: yNorm, xy: xyNorm };
-};
-
-const resolveAxisValue = (entry, axisValues) => {
-  const axisX = typeof entry?.axisX === 'boolean' ? entry.axisX : null;
-  const axisY = typeof entry?.axisY === 'boolean' ? entry.axisY : null;
-  if (axisX != null || axisY != null) {
-    if (axisX && axisY) {
-      const xVal = axisValues.x;
-      const yVal = axisValues.y;
-      if (xVal == null || yVal == null) return null;
-      const op = entry?.axisOp || 'add';
-      switch (op) {
-      case 'sub':
-        return clamp((xVal - yVal + 1) / 2, 0, 1);
-      case 'mul':
-        return clamp(xVal * yVal, 0, 1);
-      case 'div':
-        if (yVal === 0) return 1;
-        return clamp(xVal / yVal, 0, 1);
-      case 'add':
-      default:
-        return clamp((xVal + yVal) / 2, 0, 1);
-      }
-    }
-    if (axisX) return axisValues.x;
-    if (axisY) return axisValues.y;
-    return null;
-  }
-  const axis = entry?.axis || 'x';
-  if (axis === 'xy') {
-    const xVal = axisValues.x;
-    const yVal = axisValues.y;
-    if (xVal == null || yVal == null) return axisValues.xy;
-    const op = entry?.axisOp || 'add';
-    switch (op) {
-    case 'sub':
-      return clamp((xVal - yVal + 1) / 2, 0, 1);
-    case 'mul':
-      return clamp(xVal * yVal, 0, 1);
-    case 'div':
-      if (yVal === 0) return 1;
-      return clamp(xVal / yVal, 0, 1);
-    case 'add':
-    default:
-      return clamp((xVal + yVal) / 2, 0, 1);
-    }
-  }
-  return axisValues[axis] ?? null;
-};
-
-const resolveScale = (scale) => {
-  const name = scale?.name || DEFAULT_CONFIG.scale.name;
-  if (Array.isArray(scale?.degrees) && scale.degrees.length) {
-    return { name, root: scale?.root ?? 0, degrees: scale.degrees };
-  }
-  if (DEFAULT_SCALES[name]) {
-    return { name, root: scale?.root ?? 0, degrees: DEFAULT_SCALES[name] };
-  }
-  return {
-    name: DEFAULT_CONFIG.scale.name,
-    root: DEFAULT_CONFIG.scale.root,
-    degrees: DEFAULT_CONFIG.scale.degrees
-  };
-};
-
-const CHORD_TYPES = Object.freeze({
-  triad: [0, 2, 4],
-  seventh: [0, 2, 4, 6],
-  sixth: [0, 2, 4, 5],
-  ninth: [0, 2, 4, 6, 8],
-  power: [0, 4],
-  sus2: [0, 1, 4],
-  sus4: [0, 3, 4],
-  octave: [0, 7]
-});
-
-const quantizeToScale = (note, scale) => {
-  const degrees = scale?.degrees ?? DEFAULT_CONFIG.scale.degrees;
-  const root = scale?.root ?? 0;
-  if (!degrees.length) return Math.round(note);
-  const rounded = Math.round(note);
-  const pitchClass = ((rounded - root) % 12 + 12) % 12;
-  if (degrees.includes(pitchClass)) return rounded;
-  for (let step = 1; step <= 6; step++) {
-    const up = (pitchClass + step) % 12;
-    const down = (pitchClass - step + 12) % 12;
-    if (degrees.includes(up)) return rounded + step;
-    if (degrees.includes(down)) return rounded - step;
-  }
-  return rounded;
-};
-
-const noteFromFrequency = (frequency) => 69 + 12 * Math.log2(frequency / 440);
-
-const noteToFrequency = (note) => 440 * Math.pow(2, (note - 69) / 12);
-
-const clampNoteToRange = (note, range) => {
-  let out = Math.round(note);
-  if (!range) return clamp(out, 0, 127);
-  const min = range.min ?? 0;
-  const max = range.max ?? 127;
-  while (out < min) out += 12;
-  while (out > max) out -= 12;
-  return clamp(out, 0, 127);
-};
-
-const buildScaleNote = (degree, scale, octave) => {
-  const degrees = scale.degrees || DEFAULT_CONFIG.scale.degrees;
-  const root = scale.root ?? 0;
-  const index = Math.max(0, degree | 0);
-  const octaveOffset = Math.floor(index / degrees.length);
-  const step = degrees[index % degrees.length];
-  return root + step + (octave + octaveOffset) * 12;
-};
-
-const buildChordNotes = (baseDegree, scale, octave, chordType, inversion = 0) => {
-  const degrees = scale.degrees || DEFAULT_CONFIG.scale.degrees;
-  const offsets = CHORD_TYPES[chordType] || CHORD_TYPES.triad;
-  const rawNotes = offsets.map(offset => {
-    const idx = (baseDegree | 0) + offset;
-    const oct = octave + Math.floor(idx / degrees.length);
-    return buildScaleNote(idx % degrees.length, scale, oct);
-  });
-  const inverted = rawNotes.slice();
-  let inv = inversion | 0;
-  while (inv > 0 && inverted.length > 1) {
-    const note = inverted.shift();
-    inverted.push(note + 12);
-    inv -= 1;
-  }
-  return inverted;
-};
+import { cloneSafeObject, isPlainObject } from '../util/safeObject.js';
+import {
+  CHORD_TYPES,
+  DEFAULT_CONFIG,
+  DEFAULT_SCALES,
+  buildChordNotes,
+  buildScaleNote,
+  clamp,
+  clampNoteToRange,
+  lerp,
+  mergeConfig,
+  noteFromFrequency,
+  noteToFrequency,
+  quantizeToScale,
+  resolveAxisValue,
+  resolveAxisValues,
+  resolvePositionMappings,
+  resolveScale
+} from './midi-mapping/MidiMappingDomain.js';
 
 class MidiMapping {
   constructor(config = {}) {
@@ -370,6 +42,27 @@ class MidiMapping {
     return this.config.sfx?.[String(sfxId)] ?? null;
   }
 
+  /**
+   * Resolve a gameplay event into a MIDI-ready note payload.
+   * @param {object} event - Source event (position, sfx id, trigger metadata).
+   * @param {object} [context={}] - Runtime context (view rect, level dimensions, etc.).
+   * @param {number} [density=0] - Normalized density scalar used by density mappings.
+   * @param {object|null} [overrideSfx=null] - Optional per-event SFX mapping override.
+   * @returns {{
+   *   note:number,
+   *   notes:number[]|null,
+   *   velocity:number,
+   *   durationTicks:number,
+   *   releaseVelocity:number|null,
+   *   timbre:number|null,
+   *   pan:number|null,
+   *   pitchBend:number,
+   *   frequencyHz:number,
+   *   channel:number|null,
+   *   voiceBudget:number|null,
+   *   arp:object|null
+   * }|null}
+   */
   mapEvent(event, context = {}, density = 0, overrideSfx = null) {
     const cfg = this.config;
     if (!cfg.enabled || !event) return null;
@@ -383,7 +76,7 @@ class MidiMapping {
     const positionCfg = cfg.position || DEFAULT_CONFIG.position;
     const scale = resolveScale(cfg.scale);
     const noteDefaults = cfg.noteDefaults || DEFAULT_CONFIG.noteDefaults;
-    const positionMappings = resolvePositionMappings(positionCfg, velocityRange);
+    const positionMappings = resolvePositionMappings(positionCfg);
     const axisValues = resolveAxisValues(event, context);
     const envelopeOverrides = {};
     let noteOffset = null;
@@ -462,7 +155,10 @@ class MidiMapping {
     if (Number.isFinite(sfx.frequencyHz) && sfx.frequencyHz > 0) {
       const floatNote = noteFromFrequency(sfx.frequencyHz);
       const baseNote = Math.round(floatNote);
-      const bendRange = cfg.mpe?.pitchBendRange?.semitones ?? 2;
+      const configuredBendRange = cfg.mpe?.pitchBendRange?.semitones;
+      const bendRange = Number.isFinite(configuredBendRange) && configuredBendRange > 0
+        ? configuredBendRange
+        : 2;
       const offset = floatNote - baseNote;
       pitchBend = clamp(offset / bendRange, -1, 1);
       note = baseNote;
@@ -605,6 +301,9 @@ class MidiMapping {
       pitchBend,
       frequencyHz,
       channel: sfx.channel ?? null,
+      voiceBudget: sfx.voiceBudget ?? null,
+      outputId: sfx.outputId ?? null,
+      trackId: sfx.trackId ?? null,
       arp: sfx.arp ?? null
     };
   }
diff --git a/js/midi/MidiScheduler.js b/js/midi/MidiScheduler.js
index 9d72562f..8ef66219 100644
--- a/js/midi/MidiScheduler.js
+++ b/js/midi/MidiScheduler.js
@@ -1,471 +1 @@
-const clamp = (value, min, max) => Math.max(min, Math.min(max, value));
-const MIDI_BITS_PER_SECOND = 31250;
-const MIDI_BYTES_PER_SECOND = MIDI_BITS_PER_SECOND / 8;
-const MIDI_MESSAGE_BYTES = 3;
-
-class MidiScheduler {
-  constructor(config = {}) {
-    this.output = null;
-    this.tickMs = 60;
-    this._activeByChannel = new Map();
-    this._activeNotes = new Map();
-    this._maxActiveNotes = 32;
-    this._memberChannels = [];
-    this._noteOffs = [];
-    this._noteOffTimerId = 0;
-    this._noteOffSeq = 0;
-    this._rateWindowMs = 1000;
-    this._rateSent = [];
-    this._ratePlanned = [];
-    this._maxMessagesPerSecond = 1000;
-    this._maxBytesPerSecond = MIDI_BYTES_PER_SECOND;
-    this._lastRateErrorMs = 0;
-    this.setConfig(config);
-  }
-
-  setConfig(config) {
-    this.config = config || {};
-    const maxActive = this.config.limits?.maxActiveNotes ?? 32;
-    this._maxActiveNotes = clamp(maxActive, 1, 32);
-    const maxMessages = this.config.limits?.maxEventsPerSecond ?? 1000;
-    const maxBytes = this.config.limits?.maxBytesPerSecond ?? MIDI_BYTES_PER_SECOND;
-    this._maxMessagesPerSecond = clamp(maxMessages, 1, 1000);
-    this._maxBytesPerSecond = Math.max(1, maxBytes);
-    this._memberChannels = this.config.mpe?.memberChannels?.slice() || [];
-    if (this.output) this._initMpe();
-  }
-
-  setOutput(output) {
-    this.output = output;
-    this._initMpe();
-  }
-
-  setTickMs(tickMs) {
-    if (Number.isFinite(tickMs) && tickMs > 0) {
-      this.tickMs = tickMs;
-    }
-  }
-
-  _nowMs() {
-    return typeof performance !== 'undefined' ? performance.now() : Date.now();
-  }
-
-  _initMpe() {
-    if (!this.output) return;
-    const mpe = this.config.mpe;
-    if (!mpe?.enabled) return;
-    const bend = mpe.pitchBendRange || { semitones: 2, cents: 0 };
-    const master = mpe.masterChannel || 1;
-    const members = mpe.memberChannels || [];
-    const channels = [master, ...members];
-    for (const ch of channels) {
-      const channel = this.output.channels?.[ch];
-      if (!channel) continue;
-      channel.sendPitchBendRange(bend.semitones, bend.cents);
-      channel.sendPitchBend(0);
-    }
-    this._memberChannels = members.slice();
-  }
-
-  _stopActiveChannel(channelNumber) {
-    const active = this._activeByChannel.get(channelNumber);
-    if (!active || !this.output) return;
-    const channel = this.output.channels?.[channelNumber];
-    if (channel) {
-      channel.sendNoteOff(active.note);
-      channel.sendPitchBend(0);
-    }
-    this._activeByChannel.delete(channelNumber);
-    if (active.token != null) {
-      this._activeNotes.delete(active.token);
-      this._removeScheduledNoteOff(active.token);
-    }
-  }
-
-  _removeScheduledNoteOff(token) {
-    if (token == null || !this._noteOffs.length) return;
-    for (let i = this._noteOffs.length - 1; i >= 0; i--) {
-      if (this._noteOffs[i].token === token) {
-        this._noteOffs.splice(i, 1);
-      }
-    }
-    this._armNoteOffTimer();
-  }
-
-  _stealOldestNote() {
-    if (!this._activeNotes.size || !this.output) return;
-    let oldestToken = null;
-    let oldestTime = Infinity;
-    for (const [token, info] of this._activeNotes.entries()) {
-      if (info.startedAt < oldestTime) {
-        oldestTime = info.startedAt;
-        oldestToken = token;
-      }
-    }
-    if (oldestToken == null) return;
-    const info = this._activeNotes.get(oldestToken);
-    if (!info) return;
-    const channel = this.output.channels?.[info.channel];
-    if (channel) {
-      channel.sendNoteOff(info.note);
-      if (info.mpe) channel.sendPitchBend(0);
-    }
-    this._activeNotes.delete(oldestToken);
-    if (info.mpe) {
-      this._activeByChannel.delete(info.channel);
-    }
-    this._removeScheduledNoteOff(oldestToken);
-  }
-
-  _allocateChannel() {
-    const mpe = this.config.mpe;
-    if (!mpe?.enabled) {
-      return this.config.defaultChannel || 1;
-    }
-    for (const ch of this._memberChannels) {
-      if (!this._activeByChannel.has(ch)) {
-        return ch;
-      }
-    }
-    let oldest = null;
-    let oldestTime = Infinity;
-    for (const [ch, info] of this._activeByChannel.entries()) {
-      if (info.startedAt < oldestTime) {
-        oldestTime = info.startedAt;
-        oldest = ch;
-      }
-    }
-    if (oldest != null) {
-      this._stopActiveChannel(oldest);
-      return oldest;
-    }
-    return mpe.masterChannel || 1;
-  }
-
-  _pruneRateEntries(now) {
-    const cutoff = now - this._rateWindowMs;
-    if (this._rateSent.length) {
-      this._rateSent = this._rateSent.filter(entry => entry.timeMs >= cutoff);
-    }
-    if (this._ratePlanned.length) {
-      const remaining = [];
-      for (const entry of this._ratePlanned) {
-        if (entry.timeMs <= now) {
-          this._rateSent.push(entry);
-        } else {
-          remaining.push(entry);
-        }
-      }
-      this._ratePlanned = remaining;
-    }
-  }
-
-  _sumRate(entries, startMs, endMs) {
-    let count = 0;
-    let bytes = 0;
-    const bySfx = new Map();
-    for (const entry of entries) {
-      if (entry.timeMs < startMs || entry.timeMs >= endMs) continue;
-      count += entry.count;
-      bytes += entry.bytes;
-      const key = entry.sfxId ?? 'unknown';
-      const curr = bySfx.get(key) || { count: 0, bytes: 0, priority: entry.priority ?? 1 };
-      curr.count += entry.count;
-      curr.bytes += entry.bytes;
-      if (entry.priority != null) curr.priority = entry.priority;
-      bySfx.set(key, curr);
-    }
-    return { count, bytes, bySfx };
-  }
-
-  getRateSnapshot(now = this._nowMs()) {
-    this._pruneRateEntries(now);
-    const past = this._sumRate(this._rateSent, now - this._rateWindowMs, now);
-    const next = this._sumRate(this._ratePlanned, now, now + this._rateWindowMs);
-    return {
-      now,
-      past,
-      next,
-      maxMessagesPerSecond: this._maxMessagesPerSecond,
-      maxBytesPerSecond: this._maxBytesPerSecond
-    };
-  }
-
-  getUsageShare(window = 'past', now = this._nowMs()) {
-    const snapshot = this.getRateSnapshot(now);
-    const data = window === 'next' ? snapshot.next : snapshot.past;
-    const total = data.count || 0;
-    const totalBytes = data.bytes || 0;
-    const shares = [];
-    for (const [sfxId, entry] of data.bySfx.entries()) {
-      shares.push({
-        sfxId,
-        count: entry.count,
-        bytes: entry.bytes,
-        priority: entry.priority ?? 1,
-        percentCount: total ? entry.count / total : 0,
-        percentBytes: totalBytes ? entry.bytes / totalBytes : 0
-      });
-    }
-    shares.sort((a, b) => b.count - a.count);
-    return shares;
-  }
-
-  estimateMessages(spec) {
-    if (!spec || !Number.isFinite(spec.note)) return { messages: 0, bytes: 0 };
-    let messages = 1;
-    if (this.config.mpe?.enabled) {
-      messages += 1;
-    } else if (spec.pitchBend != null && Number.isFinite(spec.pitchBend) && spec.pitchBend !== 0) {
-      messages += 1;
-    }
-    if (spec.timbre != null && Number.isFinite(spec.timbre)) messages += 1;
-    if (spec.pan != null && Number.isFinite(spec.pan)) messages += 1;
-    if (spec.durationTicks && spec.durationTicks > 0) {
-      messages += 1;
-      if (this.config.mpe?.enabled) messages += 1;
-    }
-    return { messages, bytes: messages * MIDI_MESSAGE_BYTES };
-  }
-
-  _recordPlanned(entry) {
-    const now = this._nowMs();
-    this._pruneRateEntries(now);
-    if (entry.timeMs <= now) {
-      this._rateSent.push(entry);
-    } else {
-      this._ratePlanned.push(entry);
-    }
-  }
-
-  _checkByteRate(now = this._nowMs()) {
-    const snapshot = this.getRateSnapshot(now);
-    if (snapshot.past.bytes > this._maxBytesPerSecond || snapshot.next.bytes > this._maxBytesPerSecond) {
-      if (now - this._lastRateErrorMs > 1000) {
-        this._lastRateErrorMs = now;
-        console.error(`MIDI throughput exceeded ${this._maxBytesPerSecond.toFixed(0)} bytes/sec`);
-      }
-    }
-  }
-
-  sendNote(spec, meta = {}) {
-    const perfEnabled = typeof lemmings !== 'undefined' &&
-      (lemmings.performanceAPI === true || lemmings.perfMetrics === true) &&
-      typeof performance !== 'undefined' &&
-      typeof performance.measure === 'function' &&
-      typeof performance.now === 'function';
-    const perfStart = perfEnabled ? performance.now() : 0;
-    try {
-      if (!this.output || !spec || !Number.isFinite(spec.note)) return false;
-      const channelNumber = this.config.mpe?.enabled
-        ? this._allocateChannel()
-        : (spec.channel ?? this.config.defaultChannel ?? 1);
-      const channel = this.output.channels?.[channelNumber];
-      if (!channel) return false;
-
-      const sendTimeMs = Number.isFinite(spec.timeMs) ? spec.timeMs : this._nowMs();
-      const durationMs = Number.isFinite(spec.durationTicks)
-        ? Math.max(0, spec.durationTicks * this.tickMs)
-        : 0;
-      const offTimeMs = sendTimeMs + durationMs;
-      const baseVelocity = clamp(spec.velocity ?? 64, 1, 127);
-      const baseRelease = clamp(spec.releaseVelocity ?? baseVelocity, 1, 127);
-      const reverse = !!spec.reverse;
-      const attackVelocity = reverse ? baseRelease : baseVelocity;
-      const releaseVelocity = reverse ? baseVelocity : baseRelease;
-      const timbreCc = this.config.mpe?.timbreCc ?? 74;
-
-      if (this.config.mpe?.enabled) {
-        if (Number.isFinite(spec.pitchBend) && spec.pitchBend !== 0) {
-          channel.sendPitchBend(clamp(spec.pitchBend, -1, 1), { time: sendTimeMs });
-        } else {
-          channel.sendPitchBend(0, { time: sendTimeMs });
-        }
-        if (spec.timbre != null && Number.isFinite(spec.timbre)) {
-          channel.sendControlChange(timbreCc, clamp(spec.timbre, 0, 127), { time: sendTimeMs });
-        }
-      }
-      if (spec.pan != null && Number.isFinite(spec.pan)) {
-        const panRange = this.config.position?.panRange;
-        const signedPan = (panRange?.min ?? 0) < 0;
-        let panValue = spec.pan;
-        if (signedPan) {
-          panValue = Math.round((clamp(panValue, -127, 127) + 127) / 2);
-        }
-        channel.sendControlChange(10, clamp(panValue, 0, 127), { time: sendTimeMs });
-      }
-
-      const startedAt = sendTimeMs;
-      const token = ++this._noteOffSeq;
-      if (this._activeNotes.size >= this._maxActiveNotes) {
-        this._stealOldestNote();
-      }
-
-      channel.sendNoteOn(spec.note, { rawAttack: attackVelocity, time: sendTimeMs });
-      if (typeof window !== 'undefined') {
-        window.lastMidiOutputMessage = {
-          type: 'noteOn',
-          note: spec.note,
-          velocity: attackVelocity,
-          channel: channelNumber,
-          timeMs: sendTimeMs
-        };
-      }
-
-      this._activeNotes.set(token, {
-        channel: channelNumber,
-        note: spec.note,
-        startedAt,
-        token,
-        mpe: !!this.config.mpe?.enabled
-      });
-      if (this.config.mpe?.enabled) {
-        this._activeByChannel.set(channelNumber, {
-          note: spec.note,
-          startedAt,
-          token
-        });
-      }
-      if (durationMs > 0) {
-        channel.sendNoteOff(spec.note, { rawRelease: releaseVelocity, time: offTimeMs });
-        if (this.config.mpe?.enabled) {
-          channel.sendPitchBend(0, { time: offTimeMs });
-        }
-        this._scheduleNoteOff({
-          timeMs: offTimeMs,
-          channel: channelNumber,
-          note: spec.note,
-          token,
-          mpe: !!this.config.mpe?.enabled
-        });
-      }
-      const { messages, bytes } = this.estimateMessages(spec);
-      if (messages > 0) {
-        this._recordPlanned({
-          timeMs: sendTimeMs,
-          count: messages - (durationMs > 0 ? 1 + (this.config.mpe?.enabled ? 1 : 0) : 0),
-          bytes: (messages - (durationMs > 0 ? 1 + (this.config.mpe?.enabled ? 1 : 0) : 0)) * MIDI_MESSAGE_BYTES,
-          sfxId: meta.sfxId ?? null,
-          priority: meta.priority ?? 1
-        });
-        if (durationMs > 0) {
-          const offMessages = 1 + (this.config.mpe?.enabled ? 1 : 0);
-          this._recordPlanned({
-            timeMs: offTimeMs,
-            count: offMessages,
-            bytes: offMessages * MIDI_MESSAGE_BYTES,
-            sfxId: meta.sfxId ?? null,
-            priority: meta.priority ?? 1
-          });
-        }
-      }
-      this._checkByteRate(sendTimeMs);
-      return true;
-    } finally {
-      if (perfEnabled) {
-        try {
-          performance.measure('MidiScheduler sendNote', {
-            start: perfStart,
-            detail: { devtools: { track: 'MidiScheduler', trackGroup: 'MIDI', color: 'secondary', tooltipText: 'sendNote' } }
-          });
-        } catch {
-          /* ignored */
-        }
-      }
-    }
-  }
-
-  _scheduleNoteOff(entry) {
-    const list = this._noteOffs;
-    list.push(entry);
-    let i = list.length - 1;
-    while (i > 0 && list[i - 1].timeMs > entry.timeMs) {
-      list[i] = list[i - 1];
-      i--;
-    }
-    list[i] = entry;
-    if (i === 0) this._armNoteOffTimer();
-  }
-
-  _armNoteOffTimer() {
-    if (this._noteOffTimerId) {
-      clearTimeout(this._noteOffTimerId);
-      this._noteOffTimerId = 0;
-    }
-    if (!this._noteOffs.length) return;
-    const now = typeof performance !== 'undefined' ? performance.now() : Date.now();
-    const delay = Math.max(0, this._noteOffs[0].timeMs - now);
-    this._noteOffTimerId = setTimeout(() => this._processNoteOffs(), delay);
-  }
-
-  _processNoteOffs() {
-    this._noteOffTimerId = 0;
-    if (!this.output || !this._noteOffs.length) return;
-    const now = typeof performance !== 'undefined' ? performance.now() : Date.now();
-    let idx = 0;
-    while (idx < this._noteOffs.length && this._noteOffs[idx].timeMs <= now + 1) {
-      const entry = this._noteOffs[idx];
-      const active = this._activeNotes.get(entry.token);
-      if (active && entry.mpe) {
-        this._activeByChannel.delete(entry.channel);
-      }
-      if (active) this._activeNotes.delete(entry.token);
-      idx++;
-    }
-    if (idx > 0) {
-      this._noteOffs.splice(0, idx);
-    }
-    this._armNoteOffTimer();
-  }
-
-  allNotesOff() {
-    if (!this.output) return;
-    const mpe = this.config.mpe;
-    const channels = mpe?.enabled
-      ? [mpe.masterChannel || 1, ...(mpe.memberChannels || [])]
-      : [this.config.defaultChannel || 1];
-    for (const ch of channels) {
-      const channel = this.output.channels?.[ch];
-      if (!channel) continue;
-      channel.sendAllNotesOff?.();
-      channel.sendPitchBend?.(0);
-    }
-    this._noteOffs.length = 0;
-    if (this._noteOffTimerId) {
-      clearTimeout(this._noteOffTimerId);
-      this._noteOffTimerId = 0;
-    }
-    this._activeByChannel.clear();
-    this._activeNotes.clear();
-    this._noteOffs.length = 0;
-    this._rateSent.length = 0;
-    this._ratePlanned.length = 0;
-  }
-
-  clearQueue() {
-    this._noteOffs.length = 0;
-    if (this._noteOffTimerId) {
-      clearTimeout(this._noteOffTimerId);
-      this._noteOffTimerId = 0;
-    }
-    this._ratePlanned.length = 0;
-  }
-
-  dispose() {
-    for (const [ch] of this._activeByChannel.entries()) {
-      this._stopActiveChannel(ch);
-    }
-    this._activeByChannel.clear();
-    this._activeNotes.clear();
-    this._noteOffs.length = 0;
-    this._rateSent.length = 0;
-    this._ratePlanned.length = 0;
-    if (this._noteOffTimerId) {
-      clearTimeout(this._noteOffTimerId);
-      this._noteOffTimerId = 0;
-    }
-    this.output = null;
-  }
-}
-
-export { MidiScheduler };
+export { MidiScheduler } from './scheduler/MidiSchedulerCore.js';
diff --git a/js/midi/input/MidiInputController.js b/js/midi/input/MidiInputController.js
index 6d97c95b..15360bd3 100644
--- a/js/midi/input/MidiInputController.js
+++ b/js/midi/input/MidiInputController.js
@@ -3,11 +3,27 @@ import { SkillTypes } from '../../game/SkillTypes.js';
 
 const clamp = (value, min, max) => Math.max(min, Math.min(max, value));
 
+const normalizeInputChannel = (channel) => {
+  if (typeof channel === 'number' && Number.isFinite(channel)) {
+    return clamp(channel | 0, 1, 16);
+  }
+  const normalized = String(channel ?? 'omni').trim().toLowerCase();
+  if (!normalized || normalized === 'omni') return 'omni';
+  const numeric = Number(normalized);
+  if (Number.isFinite(numeric)) {
+    return clamp(Math.trunc(numeric), 1, 16);
+  }
+  return normalized;
+};
+
 const scaleValue = (value, min, max) => {
   const t = clamp(value / 127, 0, 1);
   return min + (max - min) * t;
 };
 
+/**
+ * Translate live MIDI input events into gameplay and MIDI-config intents.
+ */
 class MidiInputController {
   constructor(view, { getConfig, onConfigChange } = {}) {
     this.view = view;
@@ -16,18 +32,119 @@ class MidiInputController {
     this.input = null;
     this.channel = 'omni';
     this._noteCapture = null;
+    this._messageCapture = null;
+    this._lastInputChannel = undefined;
+    this._lastCcConfigRef = undefined;
+    this._lastNotesConfigRef = undefined;
+    this._ccMappings = new Map();
+    this._noteActions = new Map();
+    this._noteSkills = new Map();
     this._handler = this._onMessage.bind(this);
   }
 
   setConfig(config) {
-    const channel = config?.input?.channel ?? 'omni';
-    if (typeof channel === 'number') {
-      this.channel = clamp(channel | 0, 1, 16);
-    } else {
-      this.channel = String(channel || 'omni').toLowerCase();
+    this._lastInputChannel = config?.input?.channel;
+    this._lastCcConfigRef = config?.input?.cc;
+    this._lastNotesConfigRef = config?.input?.notes;
+    this.channel = normalizeInputChannel(this._lastInputChannel);
+    this._buildCcMappingIndex(this._lastCcConfigRef);
+    this._buildNoteMappingIndex(this._lastNotesConfigRef);
+  }
+
+  /**
+   * Index configured CC mappings by controller number to avoid per-message scans.
+   * @param {object|null|undefined} ccConfig
+   */
+  _buildCcMappingIndex(ccConfig) {
+    this._ccMappings.clear();
+    if (!ccConfig || typeof ccConfig !== 'object') return;
+    for (const [key, mapping] of Object.entries(ccConfig)) {
+      const cc = Number.isFinite(mapping?.cc) ? Math.trunc(mapping.cc) : null;
+      if (cc == null) continue;
+      const list = this._ccMappings.get(cc) || [];
+      list.push({ key, mapping });
+      this._ccMappings.set(cc, list);
+    }
+  }
+
+  _buildNoteMappingIndex(notesCfg) {
+    this._noteActions.clear();
+    this._noteSkills.clear();
+    if (!notesCfg || typeof notesCfg !== 'object') return;
+    const skillBase = Number.isFinite(notesCfg.skillBase) ? Math.trunc(notesCfg.skillBase) : 60;
+    const skillOrder = Array.isArray(notesCfg.skillOrder) ? notesCfg.skillOrder : [];
+    for (let i = 0; i < skillOrder.length; i += 1) {
+      const key = skillOrder[i];
+      const skill = SkillTypes[key];
+      if (skill != null) {
+        this._noteSkills.set(skillBase + i, skill);
+      }
+    }
+    const actions = notesCfg.actions || {};
+    if (!actions || typeof actions !== 'object') return;
+    for (const [action, mapped] of Object.entries(actions)) {
+      if (!Number.isFinite(mapped)) continue;
+      this._noteActions.set(Math.trunc(mapped), action);
     }
   }
 
+  /**
+   * Resolve cached CC mappings and self-heal stale entries when config objects
+   * are mutated in place.
+   * @param {number} ccNumber
+   * @param {object|null|undefined} ccConfig
+   * @returns {Array<{key:string,mapping:object}>}
+   */
+  _resolveCcEntries(ccNumber, ccConfig) {
+    if (!ccConfig || typeof ccConfig !== 'object') return [];
+    let entries = this._ccMappings.get(ccNumber) || [];
+    let hasStale = false;
+    let validEntries = [];
+    if (entries.length) {
+      validEntries = entries.filter(({ key, mapping }) => {
+        const currentMapping = ccConfig[key];
+        const sameReference = currentMapping === mapping;
+        const sameControllerNumber = Number.isFinite(currentMapping?.cc) &&
+          Math.trunc(currentMapping.cc) === ccNumber;
+        const valid = sameReference && sameControllerNumber;
+        if (!valid) hasStale = true;
+        return valid;
+      });
+    }
+    if (hasStale) {
+      this._buildCcMappingIndex(ccConfig);
+      validEntries = this._ccMappings.get(ccNumber) || [];
+    }
+    if (validEntries.length) return validEntries;
+    const scanned = [];
+    for (const [key, mapping] of Object.entries(ccConfig)) {
+      if (!Number.isFinite(mapping?.cc) || Math.trunc(mapping.cc) !== ccNumber) continue;
+      scanned.push({ key, mapping });
+    }
+    if (scanned.length) {
+      this._ccMappings.set(ccNumber, scanned);
+    }
+    return scanned;
+  }
+
+  /**
+   * Track only config fields that affect input dispatch hot paths.
+   * @param {object|null|undefined} config
+   */
+  _syncConfig(config) {
+    const nextInputChannel = config?.input?.channel;
+    const nextCcConfig = config?.input?.cc;
+    const nextNotesConfig = config?.input?.notes;
+    if (
+      nextInputChannel === this._lastInputChannel &&
+      nextCcConfig === this._lastCcConfigRef &&
+      nextNotesConfig === this._lastNotesConfigRef
+    ) {
+      return;
+    }
+    this.setConfig(config);
+  }
+
   attach(input) {
     if (this.input && this._handler) {
       this.input.removeListener('midimessage', this._handler);
@@ -49,6 +166,10 @@ class MidiInputController {
     this._noteCapture = typeof handler === 'function' ? handler : null;
   }
 
+  setMessageCapture(handler) {
+    this._messageCapture = typeof handler === 'function' ? handler : null;
+  }
+
   _matchesChannel(channel) {
     if (this.channel === 'omni') return true;
     return channel === this.channel;
@@ -57,10 +178,6 @@ class MidiInputController {
   _applyConfigPatch(patch) {
     if (this.onConfigChange) {
       this.onConfigChange(patch);
-      return;
-    }
-    if (this.view?.applyMidiOverrides) {
-      this.view.applyMidiOverrides(patch);
     }
   }
 
@@ -119,23 +236,21 @@ class MidiInputController {
       if (handled) return;
     }
     const notesCfg = config?.input?.notes || {};
-    const skillBase = notesCfg.skillBase ?? 60;
-    const skillOrder = notesCfg.skillOrder || [];
-    const skillIdx = note - skillBase;
-    if (skillIdx >= 0 && skillIdx < skillOrder.length) {
-      const key = skillOrder[skillIdx];
-      const skill = SkillTypes[key];
-      if (skill != null && this.view?.game?.queueCommand) {
+    if (notesCfg !== this._lastNotesConfigRef) {
+      this._lastNotesConfigRef = notesCfg;
+      this._buildNoteMappingIndex(notesCfg);
+    }
+    const skill = this._noteSkills.get(note);
+    if (skill != null) {
+      if (this.view?.game?.queueCommand) {
         this.view.game.queueCommand(new CommandSelectSkill(skill));
         if (this.view.game.gameGui) this.view.game.gameGui.skillSelectionChanged = true;
       }
       return;
     }
 
-    const actions = notesCfg.actions || {};
-    const match = Object.entries(actions).find(([, mapped]) => mapped === note);
-    if (!match) return;
-    const action = match[0];
+    const action = this._noteActions.get(note);
+    if (!action) return;
     if (action === 'pause') this._pauseGame();
     if (action === 'resume') this._resumeGame();
     if (action === 'restart') this._restartLevel();
@@ -152,10 +267,15 @@ class MidiInputController {
   }
 
   _handleControlChange(cc, value, config) {
-    const ccCfg = config?.input?.cc || {};
-    const entries = Object.entries(ccCfg);
-    for (const [key, mapping] of entries) {
-      if ((mapping?.cc ?? -1) !== cc) continue;
+    const ccNumber = Math.trunc(cc);
+    const nextCcConfig = config?.input?.cc;
+    if (nextCcConfig && nextCcConfig !== this._lastCcConfigRef) {
+      this._lastCcConfigRef = nextCcConfig;
+      this._buildCcMappingIndex(nextCcConfig);
+    }
+    const entries = this._resolveCcEntries(ccNumber, nextCcConfig);
+    if (!entries || !entries.length) return;
+    for (const { key, mapping } of entries) {
       if (key === 'speed') {
         const min = mapping.min ?? 0.1;
         const max = mapping.max ?? 8;
@@ -197,7 +317,7 @@ class MidiInputController {
 
   _onMessage(event) {
     const config = this.getConfig?.() || {};
-    this.setConfig(config);
+    this._syncConfig(config);
     const data = event?.data;
     if (!data || data.length === 0) return;
     if (typeof window !== 'undefined') {
@@ -213,6 +333,20 @@ class MidiInputController {
     const type = status & 0xF0;
     const channel = (status & 0x0F) + 1;
     if (!this._matchesChannel(channel)) return;
+    if (this._messageCapture) {
+      const handled = this._messageCapture({
+        data: Array.from(data),
+        status,
+        type,
+        channel,
+        note: data[1],
+        velocity: data[2] ?? 0,
+        cc: data[1],
+        value: data[2] ?? 0,
+        timestamp: event?.timestamp ?? event?.timeStamp ?? event?.receivedTime ?? Date.now()
+      });
+      if (handled) return;
+    }
     if (type === 0x90 || type === 0x80) {
       const note = data[1];
       const velocity = data[2] ?? 0;
diff --git a/js/midi/midi-mapping/MidiMappingDomain.js b/js/midi/midi-mapping/MidiMappingDomain.js
new file mode 100644
index 00000000..a8ff153e
--- /dev/null
+++ b/js/midi/midi-mapping/MidiMappingDomain.js
@@ -0,0 +1,342 @@
+import { cloneSafeObject, createNullObject, isPlainObject, safeObjectEntries } from '../../util/safeObject.js';
+
+const DEFAULT_SCALES = Object.freeze({
+  major: [0, 2, 4, 5, 7, 9, 11],
+  minor: [0, 2, 3, 5, 7, 8, 10],
+  dorian: [0, 2, 3, 5, 7, 9, 10],
+  mixolydian: [0, 2, 4, 5, 7, 9, 10],
+  pentatonic: [0, 2, 4, 7, 9],
+  chromatic: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11],
+  'chromatic-minor': [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
+});
+
+const DEFAULT_CONFIG = Object.freeze({
+  enabled: true,
+  mpe: {
+    enabled: true,
+    masterChannel: 1,
+    memberChannels: [2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16],
+    pitchBendRange: { semitones: 24, cents: 0 },
+    timbreCc: 74
+  },
+  scale: {
+    name: 'chromatic-minor',
+    root: 0,
+    degrees: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
+  },
+  timing: {
+    bpmBase: 120,
+    scheduleAheadMs: 0,
+    timeSignature: { beats: 4, unit: 4 },
+    quantize: '1/16',
+    swing: 0
+  },
+  reverse: {
+    allNotesOffOnToggle: false
+  },
+  noteDefaults: {
+    octave: 4,
+    degree: 0,
+    chord: 'triad'
+  },
+  noteRange: { min: 36, max: 84 },
+  velocityRange: { min: 20, max: 110, default: 80 },
+  durationTicks: { default: 6, min: 2, max: 24 },
+  envelope: {
+    attack: 1,
+    decay: 0,
+    sustain: 1,
+    release: 1
+  },
+  limits: {
+    windowMs: 1000,
+    maxEventsPerTick: 32,
+    hardMaxEventsPerTick: 128,
+    maxEventsPerSecond: 900,
+    hardMaxEventsPerSecond: 1000,
+    maxBytesPerSecond: 3906,
+    overloadCooldownMs: 500,
+    maxActiveNotes: 32,
+    prioritySfx: [2, 3, 16]
+  },
+  density: { windowTicks: 24, velocityBoost: 0.4, durationScale: 0.5 },
+  repeat: {
+    maxRepeats: 0,
+    windowBeats: 4,
+    spacingTicks: 2,
+    target: 'velocity',
+    amount: 0.15,
+    velocityBoost: 0,
+    durationBoost: 0
+  },
+  position: {
+    xNoteRange: { min: -12, max: 12 },
+    timbreRange: { min: 20, max: 110 },
+    mappings: [
+      { axis: 'y', target: 'velocity', min: 110, max: 20, enabled: true },
+      { axis: 'y', target: 'timbre', min: 110, max: 20, enabled: true }
+    ],
+    viewPan: false,
+    panRange: { min: -127, max: 127 },
+    panDeadZonePct: 0.02,
+    panOnscreenWeight: 0.8,
+    panOffscreenWeight: 0.2,
+    panOffscreenRange: 1
+  },
+  input: {
+    enabled: true,
+    channel: 'omni',
+    transport: {
+      start: 'restart',
+      stop: 'pause',
+      continue: 'resume'
+    },
+    notes: {
+      skillBase: 60,
+      skillOrder: [
+        'CLIMBER',
+        'FLOATER',
+        'BOMBER',
+        'BLOCKER',
+        'BUILDER',
+        'BASHER',
+        'MINER',
+        'DIGGER'
+      ],
+      actions: {
+        pause: 36,
+        resume: 38,
+        restart: 40,
+        speedDown: 41,
+        speedUp: 43,
+        speedReset: 45,
+        toggleMidi: 47,
+        toggleViewPan: 49
+      }
+    },
+    cc: {
+      speed: { cc: 1, min: 0.1, max: 8 },
+      bpmBase: { cc: 74, min: 60, max: 200 },
+      intensity: { cc: 7, min: 10, max: 127 },
+      accent: { cc: 11, min: 0, max: 1 },
+      keyRoot: { cc: 16, min: 0, max: 11, round: true, target: 'scale.root' },
+      scaleName: {
+        cc: 17,
+        target: 'scale.name',
+        values: ['chromatic-minor', 'major', 'minor', 'dorian', 'mixolydian', 'pentatonic', 'chromatic']
+      },
+      viewPan: { cc: 21, toggle: true, target: 'position.viewPan' },
+      repeatCount: { cc: 22, min: 0, max: 32, round: true, target: 'repeat.maxRepeats' },
+      repeatSpacing: { cc: 23, min: 1, max: 8, round: true, target: 'repeat.windowBeats' },
+      envAttack: { cc: 24, min: 0, max: 2, target: 'envelope.attack' },
+      envDecay: { cc: 25, min: 0, max: 2, target: 'envelope.decay' },
+      envSustain: { cc: 26, min: 0, max: 1, target: 'envelope.sustain' },
+      envRelease: { cc: 27, min: 0, max: 2, target: 'envelope.release' },
+      chordType: {
+        cc: 28,
+        target: 'noteDefaults.chord',
+        values: ['triad', 'seventh', 'sixth', 'ninth', 'power', 'sus2', 'sus4', 'octave']
+      },
+      chordOctave: { cc: 29, min: 1, max: 8, round: true, target: 'noteDefaults.octave' },
+      chordDegree: { cc: 30, min: 0, max: 6, round: true, target: 'noteDefaults.degree' },
+      duration: { cc: 31, min: 1, max: 24, round: true, target: 'durationTicks.default' },
+      timeSignatureBeats: { cc: 80, min: 1, max: 12, round: true, target: 'timing.timeSignature.beats' },
+      timeSignatureUnit: { cc: 81, values: [1, 2, 4, 8, 16], target: 'timing.timeSignature.unit' }
+    }
+  },
+  triggers: {},
+  sfx: {}
+});
+
+const mergeConfig = (base, override) => {
+  const out = createNullObject();
+  for (const [key, val] of safeObjectEntries(base)) {
+    out[key] = val;
+  }
+  if (!override) return out;
+  for (const [key, val] of safeObjectEntries(override)) {
+    if (isPlainObject(val) && isPlainObject(base[key])) {
+      out[key] = mergeConfig(base[key], val);
+    } else {
+      const cloned = cloneSafeObject(val);
+      if (cloned !== undefined) out[key] = cloned;
+    }
+  }
+  return out;
+};
+
+const clamp = (value, min, max) => Math.max(min, Math.min(max, value));
+const lerp = (a, b, t) => a + (b - a) * t;
+
+/**
+ * Hard-cutover behavior: only explicit `position.mappings` entries are used.
+ * Legacy position toggle flags are intentionally ignored.
+ */
+const resolvePositionMappings = (positionCfg) => {
+  if (Array.isArray(positionCfg?.mappings)) return positionCfg.mappings;
+  return [];
+};
+
+const resolveAxisValues = (event, context) => {
+  const xNorm = context.levelWidth && event?.x != null
+    ? clamp(event.x / context.levelWidth, 0, 1)
+    : null;
+  const yNorm = context.levelHeight && event?.y != null
+    ? clamp(event.y / context.levelHeight, 0, 1)
+    : null;
+  const xyNorm = (xNorm != null && yNorm != null)
+    ? clamp((xNorm + yNorm) / 2, 0, 1)
+    : null;
+  return { x: xNorm, y: yNorm, xy: xyNorm };
+};
+
+const resolveAxisValue = (entry, axisValues) => {
+  const axisX = typeof entry?.axisX === 'boolean' ? entry.axisX : null;
+  const axisY = typeof entry?.axisY === 'boolean' ? entry.axisY : null;
+  if (axisX != null || axisY != null) {
+    if (axisX && axisY) {
+      const xVal = axisValues.x;
+      const yVal = axisValues.y;
+      if (xVal == null || yVal == null) return null;
+      const op = entry?.axisOp || 'add';
+      switch (op) {
+      case 'sub':
+        return clamp((xVal - yVal + 1) / 2, 0, 1);
+      case 'mul':
+        return clamp(xVal * yVal, 0, 1);
+      case 'div':
+        if (yVal === 0) return 1;
+        return clamp(xVal / yVal, 0, 1);
+      case 'add':
+      default:
+        return clamp((xVal + yVal) / 2, 0, 1);
+      }
+    }
+    if (axisX) return axisValues.x;
+    if (axisY) return axisValues.y;
+    return null;
+  }
+  const axis = entry?.axis || 'x';
+  if (axis === 'xy') {
+    const xVal = axisValues.x;
+    const yVal = axisValues.y;
+    if (xVal == null || yVal == null) return axisValues.xy;
+    const op = entry?.axisOp || 'add';
+    switch (op) {
+    case 'sub':
+      return clamp((xVal - yVal + 1) / 2, 0, 1);
+    case 'mul':
+      return clamp(xVal * yVal, 0, 1);
+    case 'div':
+      if (yVal === 0) return 1;
+      return clamp(xVal / yVal, 0, 1);
+    case 'add':
+    default:
+      return clamp((xVal + yVal) / 2, 0, 1);
+    }
+  }
+  return axisValues[axis] ?? null;
+};
+
+const resolveScale = (scale) => {
+  const name = scale?.name || DEFAULT_CONFIG.scale.name;
+  if (Array.isArray(scale?.degrees) && scale.degrees.length) {
+    return { name, root: scale?.root ?? 0, degrees: scale.degrees };
+  }
+  if (DEFAULT_SCALES[name]) {
+    return { name, root: scale?.root ?? 0, degrees: DEFAULT_SCALES[name] };
+  }
+  return {
+    name: DEFAULT_CONFIG.scale.name,
+    root: DEFAULT_CONFIG.scale.root,
+    degrees: DEFAULT_CONFIG.scale.degrees
+  };
+};
+
+const CHORD_TYPES = Object.freeze({
+  triad: [0, 2, 4],
+  seventh: [0, 2, 4, 6],
+  sixth: [0, 2, 4, 5],
+  ninth: [0, 2, 4, 6, 8],
+  power: [0, 4],
+  sus2: [0, 1, 4],
+  sus4: [0, 3, 4],
+  octave: [0, 7]
+});
+
+const quantizeToScale = (note, scale) => {
+  const degrees = scale?.degrees ?? DEFAULT_CONFIG.scale.degrees;
+  const root = scale?.root ?? 0;
+  if (!degrees.length) return Math.round(note);
+  const rounded = Math.round(note);
+  const pitchClass = ((rounded - root) % 12 + 12) % 12;
+  if (degrees.includes(pitchClass)) return rounded;
+  for (let step = 1; step <= 6; step++) {
+    const up = (pitchClass + step) % 12;
+    const down = (pitchClass - step + 12) % 12;
+    if (degrees.includes(up)) return rounded + step;
+    if (degrees.includes(down)) return rounded - step;
+  }
+  return rounded;
+};
+
+const noteFromFrequency = (frequency) => 69 + 12 * Math.log2(frequency / 440);
+
+const noteToFrequency = (note) => 440 * Math.pow(2, (note - 69) / 12);
+
+const clampNoteToRange = (note, range) => {
+  let out = Math.round(note);
+  if (!range) return clamp(out, 0, 127);
+  const min = range.min ?? 0;
+  const max = range.max ?? 127;
+  while (out < min) out += 12;
+  while (out > max) out -= 12;
+  return clamp(out, 0, 127);
+};
+
+const buildScaleNote = (degree, scale, octave) => {
+  const degrees = scale.degrees || DEFAULT_CONFIG.scale.degrees;
+  const root = scale.root ?? 0;
+  const index = Math.max(0, degree | 0);
+  const octaveOffset = Math.floor(index / degrees.length);
+  const step = degrees[index % degrees.length];
+  return root + step + (octave + octaveOffset) * 12;
+};
+
+const buildChordNotes = (baseDegree, scale, octave, chordType, inversion = 0) => {
+  const degrees = scale.degrees || DEFAULT_CONFIG.scale.degrees;
+  const offsets = CHORD_TYPES[chordType] || CHORD_TYPES.triad;
+  const rawNotes = offsets.map(offset => {
+    const idx = (baseDegree | 0) + offset;
+    const oct = octave + Math.floor(idx / degrees.length);
+    return buildScaleNote(idx % degrees.length, scale, oct);
+  });
+  const inverted = rawNotes.slice();
+  let inv = inversion | 0;
+  while (inv > 0 && inverted.length > 1) {
+    const note = inverted.shift();
+    inverted.push(note + 12);
+    inv -= 1;
+  }
+  return inverted;
+};
+
+
+export {
+  CHORD_TYPES,
+  DEFAULT_CONFIG,
+  DEFAULT_SCALES,
+  buildChordNotes,
+  buildScaleNote,
+  clamp,
+  clampNoteToRange,
+  lerp,
+  mergeConfig,
+  noteFromFrequency,
+  noteToFrequency,
+  quantizeToScale,
+  resolveAxisValue,
+  resolveAxisValues,
+  resolvePositionMappings,
+  resolveScale
+};
diff --git a/js/midi/project/MidiProject.js b/js/midi/project/MidiProject.js
new file mode 100644
index 00000000..995c8ed2
--- /dev/null
+++ b/js/midi/project/MidiProject.js
@@ -0,0 +1,1513 @@
+import { DEFAULT_CONFIG, mergeConfig } from '../midi-mapping/MidiMappingDomain.js';
+import { cloneSafeObject, isPlainObject, safeObjectEntries } from '../../util/safeObject.js';
+
+const MIDI_PROJECT_VERSION = 1;
+const DEFAULT_TRACK_ID = 'track-1';
+const DEFAULT_TEMPLATE_ID = 'midi-mapping';
+const MIDI_PROJECT_EXPORT_KIND = 'lemmings.midi.project';
+const MIDI_TEMPLATE_EXPORT_KIND = 'lemmings.midi.template';
+const MIN_DURATION_TICKS = 1;
+const MAX_DURATION_TICKS = 960;
+
+const DIRECT_MAPPING_KEYS = Object.freeze([
+  'note',
+  'degree',
+  'octave',
+  'notes',
+  'chord',
+  'velocity',
+  'durationTicks',
+  'pan',
+  'timbre',
+  'pitchBend',
+  'envelope',
+  'arp'
+]);
+
+const SOURCE_KINDS = Object.freeze(['sfx', 'trigger', 'midiFlag', 'system', 'procgen']);
+const CLIP_TYPES = Object.freeze(['stepPattern', 'chord', 'arp']);
+const ARP_MODES = Object.freeze(['up', 'down', 'updown']);
+const AUTOMATION_SCOPES = Object.freeze(['global', 'track']);
+const AUTOMATION_AXES = Object.freeze(['x', 'y', 'xy']);
+const AUTOMATION_AXIS_OPS = Object.freeze(['add', 'sub', 'mul', 'div']);
+const AUTOMATION_TARGETS = Object.freeze([
+  'note',
+  'velocity',
+  'pan',
+  'duration',
+  'timbre',
+  'attack',
+  'decay',
+  'sustain',
+  'release'
+]);
+const AUTOMATION_TARGET_DEFAULTS = Object.freeze({
+  note: { min: -12, max: 12 },
+  velocity: { min: 110, max: 20 },
+  pan: { min: -127, max: 127 },
+  duration: { min: 2, max: 24 },
+  timbre: { min: 110, max: 20 },
+  attack: { min: 0, max: 2 },
+  decay: { min: 0, max: 2 },
+  sustain: { min: 0, max: 2 },
+  release: { min: 0, max: 2 }
+});
+
+const clamp = (value, min, max) => Math.max(min, Math.min(max, value));
+
+const toFiniteNumber = (value, fallback) => {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : fallback;
+};
+
+const toInteger = (value, fallback) => Math.round(toFiniteNumber(value, fallback));
+
+const sanitizeId = (value, fallback) => {
+  const text = typeof value === 'string' ? value.trim() : '';
+  return text || fallback;
+};
+
+const uniqueId = (base, used) => {
+  let candidate = base;
+  let index = 2;
+  while (used.has(candidate)) {
+    candidate = `${base}-${index}`;
+    index += 1;
+  }
+  used.add(candidate);
+  return candidate;
+};
+
+const uniqueName = (base, used) => {
+  let candidate = base;
+  let index = 2;
+  while (used.has(candidate)) {
+    candidate = `${base} ${index}`;
+    index += 1;
+  }
+  used.add(candidate);
+  return candidate;
+};
+
+const cloneObject = (value, fallback = {}) => {
+  const cloned = cloneSafeObject(value);
+  return isPlainObject(cloned) ? cloned : fallback;
+};
+
+const cloneArray = (value) => {
+  const cloned = cloneSafeObject(value);
+  return Array.isArray(cloned) ? cloned : [];
+};
+
+const sanitizeBoolean = (value, fallback = false) => (
+  typeof value === 'boolean' ? value : fallback
+);
+
+const sanitizeChannel = (value, fallback = 1) => clamp(toInteger(value, fallback), 1, 16);
+
+const sanitizeInputChannel = (value) => {
+  if (value === 'omni') return 'omni';
+  if (value == null || value === '') return 'omni';
+  return sanitizeChannel(value, 1);
+};
+
+const sanitizeNote = (value, fallback = 60) => clamp(toInteger(value, fallback), 0, 127);
+
+const sanitizeVelocity = (value, fallback = 80) => clamp(toInteger(value, fallback), 1, 127);
+
+const sanitizeDurationTicks = (value, fallback = 6) => (
+  clamp(toInteger(value, fallback), MIN_DURATION_TICKS, MAX_DURATION_TICKS)
+);
+
+const sanitizeDensity = (density = {}, fallback = DEFAULT_CONFIG.density) => ({
+  windowTicks: clamp(toInteger(density?.windowTicks, fallback.windowTicks ?? 24), 0, 960),
+  velocityBoost: clamp(toFiniteNumber(density?.velocityBoost, fallback.velocityBoost ?? 0), 0, 4),
+  durationScale: clamp(toFiniteNumber(density?.durationScale, fallback.durationScale ?? 0), 0, 1)
+});
+
+const sanitizePositionConfig = (position = {}, fallback = DEFAULT_CONFIG.position) => ({
+  xNoteRange: sanitizeRange(position?.xNoteRange, fallback.xNoteRange ?? { min: -12, max: 12 }, -48, 48),
+  timbreRange: sanitizeRange(position?.timbreRange, fallback.timbreRange ?? { min: 0, max: 127 }, 0, 127),
+  viewPan: sanitizeBoolean(position?.viewPan, fallback.viewPan ?? false),
+  panRange: sanitizeRange(position?.panRange, fallback.panRange ?? { min: -127, max: 127 }, -127, 127),
+  panDeadZonePct: clamp(toFiniteNumber(position?.panDeadZonePct, fallback.panDeadZonePct ?? 0.02), 0, 0.5),
+  panOnscreenWeight: clamp(toFiniteNumber(position?.panOnscreenWeight, fallback.panOnscreenWeight ?? 0.8), 0, 1),
+  panOffscreenWeight: clamp(toFiniteNumber(position?.panOffscreenWeight, fallback.panOffscreenWeight ?? 0.2), 0, 1),
+  panOffscreenRange: clamp(toFiniteNumber(position?.panOffscreenRange, fallback.panOffscreenRange ?? 1), 0, 4)
+});
+
+const createEmptyDirectMapping = () => ({
+  note: null,
+  degree: null,
+  octave: 4,
+  notes: null,
+  chord: null,
+  velocity: null,
+  durationTicks: null,
+  pan: null,
+  timbre: null,
+  pitchBend: null,
+  envelope: null,
+  arp: null
+});
+
+const createDefaultMidiStep = (index = 0, overrides = {}) => ({
+  index,
+  note: overrides.note ?? (index === 0 ? 60 : null),
+  velocity: overrides.velocity ?? null,
+  durationTicks: overrides.durationTicks ?? null,
+  tie: overrides.tie ?? false,
+  hold: overrides.hold ?? false,
+  probability: overrides.probability ?? 1
+});
+
+const sanitizeArpPayload = (arp) => {
+  if (!isPlainObject(arp)) return null;
+  const clean = cloneObject(arp);
+  return {
+    ...clean,
+    mode: ARP_MODES.includes(clean.mode) ? clean.mode : 'up',
+    pattern: isPlainObject(clean.pattern) ? cloneObject(clean.pattern) : null
+  };
+};
+
+const createDefaultMidiClip = (overrides = {}) => {
+  const lengthSteps = clamp(toInteger(overrides.lengthSteps, 16), 1, 256);
+  const steps = Array.isArray(overrides.steps) && overrides.steps.length
+    ? overrides.steps
+    : Array.from({ length: lengthSteps }, (_, index) => createDefaultMidiStep(index));
+  return {
+    id: overrides.id || 'clip-1',
+    name: overrides.name || 'Clip 1',
+    type: CLIP_TYPES.includes(overrides.type) ? overrides.type : 'stepPattern',
+    lengthSteps,
+    steps,
+    arp: sanitizeArpPayload(overrides.arp)
+  };
+};
+
+const automationDefaultsForTarget = (target) => AUTOMATION_TARGET_DEFAULTS[target] || AUTOMATION_TARGET_DEFAULTS.velocity;
+
+const createDefaultMidiAutomation = (overrides = {}) => {
+  const target = AUTOMATION_TARGETS.includes(overrides.target) ? overrides.target : 'velocity';
+  const defaults = automationDefaultsForTarget(target);
+  const axis = AUTOMATION_AXES.includes(overrides.axis) ? overrides.axis : 'y';
+  return {
+    id: overrides.id || `automation-${target}`,
+    name: overrides.name || `${target} by ${axis.toUpperCase()}`,
+    enabled: overrides.enabled ?? true,
+    scope: AUTOMATION_SCOPES.includes(overrides.scope) ? overrides.scope : 'global',
+    trackId: overrides.trackId ?? null,
+    target,
+    axis,
+    axisOp: AUTOMATION_AXIS_OPS.includes(overrides.axisOp) ? overrides.axisOp : 'add',
+    min: overrides.min ?? defaults.min,
+    max: overrides.max ?? defaults.max,
+    points: Array.isArray(overrides.points) ? overrides.points : []
+  };
+};
+
+const createMidiAutomationFromPositionMapping = (mapping = {}, index = 0) => {
+  const target = AUTOMATION_TARGETS.includes(mapping?.target) ? mapping.target : 'velocity';
+  const axis = AUTOMATION_AXES.includes(mapping?.axis) ? mapping.axis : 'y';
+  const defaults = automationDefaultsForTarget(target);
+  return createDefaultMidiAutomation({
+    id: `position-${target}-${index + 1}`,
+    name: `${target} by ${axis.toUpperCase()}`,
+    enabled: mapping?.enabled !== false,
+    scope: 'global',
+    target,
+    axis,
+    axisOp: mapping?.axisOp,
+    min: mapping?.min ?? defaults.min,
+    max: mapping?.max ?? defaults.max
+  });
+};
+
+const cloneDirectMapping = (mapping = {}) => {
+  const out = createEmptyDirectMapping();
+  if (!isPlainObject(mapping)) return out;
+  for (const key of DIRECT_MAPPING_KEYS) {
+    const cloned = cloneSafeObject(mapping[key]);
+    if (cloned !== undefined) out[key] = cloned;
+  }
+  return out;
+};
+
+const sanitizeEnvelope = (envelope) => {
+  if (!isPlainObject(envelope)) return null;
+  return {
+    attack: clamp(toFiniteNumber(envelope.attack, 0), 0, 2),
+    decay: clamp(toFiniteNumber(envelope.decay, 0), 0, 2),
+    sustain: clamp(toFiniteNumber(envelope.sustain, 1), 0, 2),
+    release: clamp(toFiniteNumber(envelope.release, 0), 0, 2)
+  };
+};
+
+const sanitizeEnvelopeDefaults = (envelope = {}, fallback = DEFAULT_CONFIG.envelope) => ({
+  attack: clamp(toFiniteNumber(envelope?.attack, fallback.attack ?? 1), 0, 2),
+  decay: clamp(toFiniteNumber(envelope?.decay, fallback.decay ?? 0), 0, 2),
+  sustain: clamp(toFiniteNumber(envelope?.sustain, fallback.sustain ?? 1), 0, 2),
+  release: clamp(toFiniteNumber(envelope?.release, fallback.release ?? 1), 0, 2)
+});
+
+const sanitizeDirectMapping = (mapping = {}) => {
+  const out = cloneDirectMapping(mapping);
+  out.note = out.note == null ? null : sanitizeNote(out.note);
+  out.degree = out.degree == null ? null : Math.max(0, toInteger(out.degree, 0));
+  out.octave = clamp(toInteger(out.octave, 4), 0, 10);
+  if (Array.isArray(out.notes)) {
+    const notes = out.notes.map(note => sanitizeNote(note)).filter(Number.isFinite);
+    out.notes = notes.length ? notes : null;
+  } else {
+    out.notes = null;
+  }
+  out.chord = isPlainObject(out.chord)
+    ? {
+      type: sanitizeId(out.chord.type, 'triad'),
+      inversion: Math.max(0, toInteger(out.chord.inversion, 0))
+    }
+    : null;
+  out.velocity = out.velocity == null ? null : sanitizeVelocity(out.velocity);
+  out.durationTicks = out.durationTicks == null ? null : sanitizeDurationTicks(out.durationTicks);
+  out.pan = out.pan == null ? null : clamp(toInteger(out.pan, 0), -127, 127);
+  out.timbre = out.timbre == null ? null : clamp(toInteger(out.timbre, 0), 0, 127);
+  out.pitchBend = out.pitchBend == null ? null : clamp(toFiniteNumber(out.pitchBend, 0), -1, 1);
+  out.envelope = sanitizeEnvelope(out.envelope);
+  out.arp = sanitizeArpPayload(out.arp);
+  return out;
+};
+
+const sanitizeRange = (range, fallback, minLimit, maxLimit) => {
+  const min = clamp(toInteger(range?.min, fallback.min), minLimit, maxLimit);
+  const max = clamp(toInteger(range?.max, fallback.max), minLimit, maxLimit);
+  return { min: Math.min(min, max), max: Math.max(min, max) };
+};
+
+const sanitizeVelocityRange = (range, fallback = DEFAULT_CONFIG.velocityRange) => {
+  const base = sanitizeRange(range, fallback, 1, 127);
+  const defaultVelocity = sanitizeVelocity(range?.default, fallback.default ?? base.max);
+  return { ...base, default: clamp(defaultVelocity, base.min, base.max) };
+};
+
+const sanitizeDurationRange = (range, fallback = DEFAULT_CONFIG.durationTicks) => {
+  const base = sanitizeRange(range, {
+    min: fallback.min ?? MIN_DURATION_TICKS,
+    max: fallback.max ?? MAX_DURATION_TICKS
+  }, MIN_DURATION_TICKS, MAX_DURATION_TICKS);
+  const defaultDuration = sanitizeDurationTicks(range?.default, fallback.default ?? base.min);
+  return { ...base, default: clamp(defaultDuration, base.min, base.max) };
+};
+
+const sanitizeScale = (scale, fallback = DEFAULT_CONFIG.scale) => ({
+  name: sanitizeId(scale?.name, fallback.name || 'chromatic-minor'),
+  root: clamp(toInteger(scale?.root, fallback.root ?? 0), 0, 11),
+  degrees: Array.isArray(scale?.degrees)
+    ? scale.degrees
+      .map(degree => clamp(toInteger(degree, 0), 0, 11))
+      .filter((degree, index, list) => list.indexOf(degree) === index)
+    : cloneSafeObject(fallback.degrees)
+});
+
+const sanitizeTransport = (transport = {}) => {
+  const fallback = DEFAULT_CONFIG.timing;
+  const signature = transport.timeSignature || fallback.timeSignature;
+  return {
+    bpmBase: clamp(toInteger(transport.bpmBase, fallback.bpmBase ?? 120), 20, 320),
+    timeSignature: {
+      beats: clamp(toInteger(signature?.beats, fallback.timeSignature?.beats ?? 4), 1, 16),
+      unit: [1, 2, 4, 8, 16].includes(toInteger(signature?.unit, fallback.timeSignature?.unit ?? 4))
+        ? toInteger(signature?.unit, fallback.timeSignature?.unit ?? 4)
+        : 4
+    },
+    quantize: sanitizeId(transport.quantize, '1/16'),
+    swing: clamp(toFiniteNumber(transport.swing, 0), 0, 1)
+  };
+};
+
+const buildGlobalFromConfig = (config = {}) => {
+  const merged = mergeConfig(DEFAULT_CONFIG, config || {});
+  return {
+    scale: sanitizeScale(merged.scale),
+    noteRange: sanitizeRange(merged.noteRange, DEFAULT_CONFIG.noteRange, 0, 127),
+    velocityRange: sanitizeVelocityRange(merged.velocityRange),
+    durationTicks: sanitizeDurationRange(merged.durationTicks),
+    density: sanitizeDensity(merged.density),
+    envelope: sanitizeEnvelopeDefaults(merged.envelope),
+    position: sanitizePositionConfig(merged.position),
+    mpe: cloneObject(merged.mpe),
+    limits: cloneObject(merged.limits),
+    reverse: cloneObject(merged.reverse)
+  };
+};
+
+const sanitizeGlobal = (global = {}) => {
+  const defaults = buildGlobalFromConfig(DEFAULT_CONFIG);
+  return {
+    scale: sanitizeScale(global.scale, defaults.scale),
+    noteRange: sanitizeRange(global.noteRange, defaults.noteRange, 0, 127),
+    velocityRange: sanitizeVelocityRange(global.velocityRange, defaults.velocityRange),
+    durationTicks: sanitizeDurationRange(global.durationTicks, defaults.durationTicks),
+    density: sanitizeDensity(global.density, defaults.density),
+    envelope: sanitizeEnvelopeDefaults(global.envelope, defaults.envelope),
+    position: sanitizePositionConfig(global.position, defaults.position),
+    mpe: cloneObject(global.mpe, defaults.mpe),
+    limits: cloneObject(global.limits, defaults.limits),
+    reverse: cloneObject(global.reverse, defaults.reverse)
+  };
+};
+
+const createDefaultMidiTrack = (overrides = {}) => ({
+  id: overrides.id || DEFAULT_TRACK_ID,
+  name: overrides.name || 'Track 1',
+  outputId: overrides.outputId ?? null,
+  channel: overrides.channel ?? 1,
+  instrumentLabel: overrides.instrumentLabel || 'General MIDI',
+  mute: overrides.mute ?? overrides.muted ?? false,
+  solo: overrides.solo ?? false,
+  arm: overrides.arm ?? false,
+  velocityScale: overrides.velocityScale ?? 1,
+  priority: overrides.priority ?? 1,
+  voiceBudget: overrides.voiceBudget ?? 32
+});
+
+const sanitizeTrack = (track, fallbackIndex, usedIds) => {
+  const fallback = createDefaultMidiTrack({
+    id: `track-${fallbackIndex + 1}`,
+    name: `Track ${fallbackIndex + 1}`
+  });
+  const baseId = sanitizeId(track?.id, fallback.id);
+  return {
+    id: uniqueId(baseId, usedIds),
+    name: sanitizeId(track?.name, fallback.name),
+    outputId: track?.outputId == null ? null : String(track.outputId),
+    channel: sanitizeChannel(track?.channel, fallback.channel),
+    instrumentLabel: sanitizeId(track?.instrumentLabel, fallback.instrumentLabel),
+    mute: sanitizeBoolean(track?.mute ?? track?.muted, false),
+    solo: sanitizeBoolean(track?.solo, false),
+    arm: sanitizeBoolean(track?.arm, false),
+    velocityScale: clamp(toFiniteNumber(track?.velocityScale, 1), 0, 4),
+    priority: Math.max(0, toInteger(track?.priority, 1)),
+    voiceBudget: clamp(toInteger(track?.voiceBudget, 32), 1, 32)
+  };
+};
+
+const normalizeKind = (value) => {
+  const kind = String(value || 'sfx');
+  return SOURCE_KINDS.includes(kind) ? kind : 'sfx';
+};
+
+const createMidiSourceFromMapping = (kind, sourceKey, mapping = {}, trackId = DEFAULT_TRACK_ID) => {
+  const resolvedKind = normalizeKind(kind);
+  return {
+    id: `${resolvedKind}-${sourceKey}`,
+    kind: resolvedKind,
+    sourceKey: String(sourceKey),
+    label: sanitizeId(mapping?.name, String(sourceKey)),
+    enabled: mapping?.disabled !== true,
+    trackId,
+    mode: 'direct',
+    mapping: sanitizeDirectMapping(mapping),
+    clipId: null
+  };
+};
+
+const sanitizeSource = (source, fallbackIndex, trackIds, clipIds, usedIds) => {
+  const kind = normalizeKind(source?.kind ?? source?.type);
+  const sourceKey = sanitizeId(source?.sourceKey ?? source?.key, String(fallbackIndex + 1));
+  const fallbackId = `${kind}-${sourceKey}`;
+  const fallbackTrackId = trackIds.has(source?.trackId) ? source.trackId : [...trackIds][0];
+  const mode = source?.mode === 'clip' ? 'clip' : 'direct';
+  const clipId = source?.clipId != null && clipIds.has(source.clipId) ? source.clipId : null;
+  return {
+    id: uniqueId(sanitizeId(source?.id, fallbackId), usedIds),
+    kind,
+    sourceKey,
+    label: sanitizeId(source?.label ?? source?.name, sourceKey),
+    enabled: sanitizeBoolean(source?.enabled, true),
+    trackId: fallbackTrackId,
+    mode,
+    mapping: mode === 'direct' ? sanitizeDirectMapping(source?.mapping) : null,
+    clipId: mode === 'clip' ? clipId : null
+  };
+};
+
+const sanitizeStep = (step, fallbackIndex) => {
+  if (!isPlainObject(step)) {
+    return createDefaultMidiStep(fallbackIndex, { note: null });
+  }
+  return {
+    ...cloneObject(step),
+    index: Math.max(0, toInteger(step.index, fallbackIndex)),
+    note: step.note == null ? null : sanitizeNote(step.note),
+    velocity: step.velocity == null ? null : sanitizeVelocity(step.velocity),
+    durationTicks: step.durationTicks == null ? null : sanitizeDurationTicks(step.durationTicks),
+    tie: sanitizeBoolean(step.tie, false),
+    hold: sanitizeBoolean(step.hold, false),
+    probability: clamp(toFiniteNumber(step.probability, 1), 0, 1)
+  };
+};
+
+const sanitizeClip = (clip, fallbackIndex, usedIds) => {
+  if (!isPlainObject(clip)) return null;
+  const type = CLIP_TYPES.includes(clip.type) ? clip.type : 'stepPattern';
+  const lengthSteps = clamp(toInteger(clip.lengthSteps, 16), 1, 256);
+  const steps = cloneArray(clip.steps)
+    .slice(0, lengthSteps)
+    .map((step, index) => sanitizeStep(step, index));
+  while (steps.length < lengthSteps) {
+    steps.push(createDefaultMidiStep(steps.length, { note: null }));
+  }
+  return {
+    id: uniqueId(sanitizeId(clip.id, `clip-${fallbackIndex + 1}`), usedIds),
+    name: sanitizeId(clip.name, `Clip ${fallbackIndex + 1}`),
+    type,
+    lengthSteps,
+    steps,
+    arp: sanitizeArpPayload(clip.arp)
+  };
+};
+
+const sanitizeAutomationPoint = (point, fallbackIndex, fallbackValue) => {
+  if (!isPlainObject(point)) {
+    return { beat: fallbackIndex, value: fallbackValue };
+  }
+  return {
+    beat: Math.max(0, toFiniteNumber(point.beat, fallbackIndex)),
+    value: toFiniteNumber(point.value, fallbackValue)
+  };
+};
+
+const sanitizeAutomation = (automation, fallbackIndex, usedIds, trackIds) => {
+  if (!isPlainObject(automation)) return null;
+  const target = AUTOMATION_TARGETS.includes(automation.target) ? automation.target : 'velocity';
+  const defaults = automationDefaultsForTarget(target);
+  const min = toFiniteNumber(automation.min, defaults.min);
+  const max = toFiniteNumber(automation.max, defaults.max);
+  const scope = AUTOMATION_SCOPES.includes(automation.scope) ? automation.scope : 'global';
+  const trackId = scope === 'track' && trackIds.has(automation.trackId) ? automation.trackId : null;
+  const points = cloneArray(automation.points)
+    .map((point, index) => sanitizeAutomationPoint(point, index, min))
+    .sort((a, b) => a.beat - b.beat);
+  return {
+    id: uniqueId(sanitizeId(automation.id, `automation-${fallbackIndex + 1}`), usedIds),
+    name: sanitizeId(automation.name, `${target} modulation`),
+    enabled: sanitizeBoolean(automation.enabled, true),
+    scope,
+    trackId,
+    target,
+    axis: AUTOMATION_AXES.includes(automation.axis) ? automation.axis : 'y',
+    axisOp: AUTOMATION_AXIS_OPS.includes(automation.axisOp) ? automation.axisOp : 'add',
+    min,
+    max,
+    points
+  };
+};
+
+const buildProjectBase = (overrides = {}) => {
+  const now = Number.isFinite(overrides.createdAt) ? overrides.createdAt : Date.now();
+  return {
+    version: MIDI_PROJECT_VERSION,
+    id: sanitizeId(overrides.id, 'midi-project'),
+    name: sanitizeId(overrides.name, 'MIDI Project'),
+    templateId: overrides.templateId ?? null,
+    createdAt: now,
+    updatedAt: Number.isFinite(overrides.updatedAt) ? overrides.updatedAt : now,
+    enabled: sanitizeBoolean(overrides.enabled, false),
+    devices: {
+      inputId: overrides.devices?.inputId ?? null,
+      outputId: overrides.devices?.outputId ?? null,
+      inputChannel: sanitizeInputChannel(overrides.devices?.inputChannel)
+    },
+    transport: sanitizeTransport(overrides.transport),
+    global: sanitizeGlobal(overrides.global),
+    tracks: Array.isArray(overrides.tracks) && overrides.tracks.length
+      ? overrides.tracks
+      : [createDefaultMidiTrack()],
+    sources: Array.isArray(overrides.sources) ? overrides.sources : [],
+    clips: Array.isArray(overrides.clips) ? overrides.clips : [],
+    automation: Array.isArray(overrides.automation) ? cloneArray(overrides.automation) : [],
+    ui: {
+      selectedTrackId: overrides.ui?.selectedTrackId ?? DEFAULT_TRACK_ID,
+      selectedSourceId: overrides.ui?.selectedSourceId ?? null,
+      selectedClipId: overrides.ui?.selectedClipId ?? null,
+      activeRegion: sanitizeId(overrides.ui?.activeRegion, 'setup')
+    }
+  };
+};
+
+const createMidiProject = (overrides = {}) => sanitizeMidiProject(buildProjectBase(overrides));
+
+const createMidiProjectFromMidiConfig = (config = {}, options = {}) => {
+  const merged = mergeConfig(DEFAULT_CONFIG, config || {});
+  const sources = [];
+  for (const [key, mapping] of safeObjectEntries(merged.sfx)) {
+    sources.push(createMidiSourceFromMapping('sfx', key, mapping));
+  }
+  for (const [key, mapping] of safeObjectEntries(merged.triggers)) {
+    sources.push(createMidiSourceFromMapping('trigger', key, mapping));
+  }
+  const automation = Array.isArray(merged.position?.mappings)
+    ? merged.position.mappings.map((mapping, index) => createMidiAutomationFromPositionMapping(mapping, index))
+    : [];
+  return sanitizeMidiProject(buildProjectBase({
+    id: options.id || 'factory-midi-project',
+    name: options.name || 'Factory MIDI Project',
+    templateId: options.templateId || DEFAULT_TEMPLATE_ID,
+    createdAt: options.createdAt,
+    updatedAt: options.updatedAt,
+    enabled: sanitizeBoolean(merged.enabled, false),
+    devices: {
+      inputId: null,
+      outputId: null,
+      inputChannel: sanitizeInputChannel(merged.input?.channel)
+    },
+    transport: {
+      bpmBase: merged.timing?.bpmBase,
+      timeSignature: merged.timing?.timeSignature,
+      quantize: '1/16',
+      swing: 0
+    },
+    global: buildGlobalFromConfig(merged),
+    tracks: [createDefaultMidiTrack()],
+    sources,
+    clips: [],
+    automation,
+    ui: {
+      selectedTrackId: DEFAULT_TRACK_ID,
+      selectedSourceId: sources[0]?.id ?? null,
+      selectedClipId: null,
+      activeRegion: 'setup'
+    }
+  }));
+};
+
+function sanitizeMidiProject(project = {}) {
+  const source = {
+    ...buildProjectBase(project),
+    ...cloneObject(project)
+  };
+  const trackIdSet = new Set();
+  const tracks = cloneArray(source.tracks)
+    .map((track, index) => sanitizeTrack(track, index, trackIdSet));
+  if (!tracks.length) tracks.push(createDefaultMidiTrack());
+
+  const trackIds = new Set(tracks.map(track => track.id));
+  const clipIdSet = new Set();
+  const clips = cloneArray(source.clips)
+    .map((clip, index) => sanitizeClip(clip, index, clipIdSet))
+    .filter(Boolean);
+  const clipIds = new Set(clips.map(clip => clip.id));
+
+  const sourceIdSet = new Set();
+  const sources = cloneArray(source.sources)
+    .map((entry, index) => sanitizeSource(entry, index, trackIds, clipIds, sourceIdSet));
+  const sourceIds = new Set(sources.map(entry => entry.id));
+  const automationIdSet = new Set();
+  const automation = cloneArray(source.automation)
+    .map((entry, index) => sanitizeAutomation(entry, index, automationIdSet, trackIds))
+    .filter(Boolean);
+
+  const selectedTrackId = trackIds.has(source.ui?.selectedTrackId)
+    ? source.ui.selectedTrackId
+    : tracks[0].id;
+  const selectedSourceId = sourceIds.has(source.ui?.selectedSourceId)
+    ? source.ui.selectedSourceId
+    : sources[0]?.id ?? null;
+  const selectedClipId = clipIds.has(source.ui?.selectedClipId)
+    ? source.ui.selectedClipId
+    : null;
+
+  return {
+    version: MIDI_PROJECT_VERSION,
+    id: sanitizeId(source.id, 'midi-project'),
+    name: sanitizeId(source.name, 'MIDI Project'),
+    templateId: source.templateId == null ? null : String(source.templateId),
+    createdAt: Number.isFinite(source.createdAt) ? source.createdAt : Date.now(),
+    updatedAt: Number.isFinite(source.updatedAt) ? source.updatedAt : Date.now(),
+    enabled: sanitizeBoolean(source.enabled, false),
+    devices: {
+      inputId: source.devices?.inputId == null ? null : String(source.devices.inputId),
+      outputId: source.devices?.outputId == null ? null : String(source.devices.outputId),
+      inputChannel: sanitizeInputChannel(source.devices?.inputChannel)
+    },
+    transport: sanitizeTransport(source.transport),
+    global: sanitizeGlobal(source.global),
+    tracks,
+    sources,
+    clips,
+    automation,
+    ui: {
+      ...cloneObject(source.ui),
+      selectedTrackId,
+      selectedSourceId,
+      selectedClipId,
+      activeRegion: sanitizeId(source.ui?.activeRegion, 'setup')
+    }
+  };
+}
+
+const parseMidiProjectPayload = (payload) => {
+  if (typeof payload !== 'string') return cloneSafeObject(payload);
+  try {
+    return JSON.parse(payload);
+  } catch (e) {
+    throw new Error('MIDI project import is not valid JSON.');
+  }
+};
+
+const createMidiProjectTemplate = (project = {}, options = {}) => {
+  const clean = sanitizeMidiProject(project);
+  const now = Number.isFinite(options.now) ? options.now : Date.now();
+  const id = sanitizeId(
+    options.id,
+    clean.templateId && clean.templateId !== DEFAULT_TEMPLATE_ID
+      ? clean.templateId
+      : `user-template-${now}`
+  );
+  const name = sanitizeId(options.name, `${clean.name} Template`);
+  const templateProject = sanitizeMidiProject({
+    ...clean,
+    name,
+    templateId: id,
+    enabled: false,
+    devices: {
+      inputId: null,
+      outputId: null,
+      inputChannel: clean.devices.inputChannel
+    },
+    ui: {
+      ...clean.ui,
+      activeRegion: 'setup'
+    }
+  });
+  return {
+    version: MIDI_PROJECT_VERSION,
+    id,
+    name,
+    createdAt: Number.isFinite(options.createdAt) ? options.createdAt : now,
+    updatedAt: Number.isFinite(options.updatedAt) ? options.updatedAt : now,
+    project: templateProject
+  };
+};
+
+const createMidiProjectExportPayload = (project = {}, options = {}) => {
+  const exportedAt = Number.isFinite(options.exportedAt) ? options.exportedAt : Date.now();
+  if (options.asTemplate) {
+    return {
+      kind: MIDI_TEMPLATE_EXPORT_KIND,
+      version: MIDI_PROJECT_VERSION,
+      exportedAt,
+      template: createMidiProjectTemplate(project, options)
+    };
+  }
+  return {
+    kind: MIDI_PROJECT_EXPORT_KIND,
+    version: MIDI_PROJECT_VERSION,
+    exportedAt,
+    project: sanitizeMidiProject(project)
+  };
+};
+
+const stringifyMidiProjectExport = (project = {}, options = {}) => (
+  `${JSON.stringify(createMidiProjectExportPayload(project, options), null, 2)}\n`
+);
+
+const importMidiProjectPayload = (payload) => {
+  const parsed = parseMidiProjectPayload(payload);
+  if (!isPlainObject(parsed)) {
+    throw new Error('MIDI project import did not contain a project.');
+  }
+  let projectPayload = null;
+  let templateId = null;
+  if (parsed.kind === MIDI_TEMPLATE_EXPORT_KIND) {
+    projectPayload = parsed.template?.project ?? parsed.project;
+    templateId = parsed.template?.id ?? parsed.templateId ?? projectPayload?.templateId ?? null;
+  } else if (parsed.kind === MIDI_PROJECT_EXPORT_KIND) {
+    projectPayload = parsed.project;
+  } else if (isPlainObject(parsed.project)) {
+    projectPayload = parsed.project;
+    templateId = parsed.templateId ?? parsed.project.templateId ?? null;
+  } else {
+    projectPayload = parsed;
+  }
+  if (!isPlainObject(projectPayload)) {
+    throw new Error('MIDI project import did not contain a project.');
+  }
+  return sanitizeMidiProject({
+    ...projectPayload,
+    templateId: templateId ?? projectPayload.templateId ?? null
+  });
+};
+
+const touchProject = (project) => ({
+  ...project,
+  updatedAt: Date.now()
+});
+
+const updateById = (items, id, patch) => items.map(item => (
+  item.id === id ? { ...item, ...cloneObject(patch) } : item
+));
+
+const updatePatch = (patch) => {
+  const clean = cloneObject(patch);
+  delete clean.id;
+  return clean;
+};
+
+const updateSourceMapping = (items, id, patch) => items.map(item => (
+  item.id === id ? { ...item, mapping: { ...createEmptyDirectMapping(), ...item.mapping, ...cloneObject(patch) } } : item
+));
+
+const addTrack = (project, track = {}) => {
+  const existing = new Set(project.tracks.map(item => item.id));
+  const id = uniqueId(sanitizeId(track.id, `track-${project.tracks.length + 1}`), existing);
+  return {
+    ...project,
+    tracks: [...project.tracks, { ...createDefaultMidiTrack({ id, name: `Track ${project.tracks.length + 1}` }), ...cloneObject(track), id }],
+    ui: { ...project.ui, selectedTrackId: id, activeRegion: 'tracks' }
+  };
+};
+
+const removeTrack = (project, trackId) => {
+  const index = project.tracks.findIndex(track => track.id === trackId);
+  if (index < 0 || project.tracks.length <= 1) return project;
+  const tracks = project.tracks.filter(track => track.id !== trackId);
+  const fallbackTrackId = tracks[index]?.id ?? tracks[index - 1]?.id ?? tracks[0].id;
+  const selectedTrackId = project.ui.selectedTrackId === trackId || !tracks.some(track => track.id === project.ui.selectedTrackId)
+    ? fallbackTrackId
+    : project.ui.selectedTrackId;
+  return {
+    ...project,
+    tracks,
+    sources: project.sources.map(source => (
+      source.trackId === trackId ? { ...source, trackId: fallbackTrackId } : source
+    )),
+    automation: project.automation.filter(lane => !(lane.scope === 'track' && lane.trackId === trackId)),
+    ui: { ...project.ui, selectedTrackId, activeRegion: 'tracks' }
+  };
+};
+
+const addClip = (project, clip = {}) => {
+  const existing = new Set(project.clips.map(item => item.id));
+  const id = uniqueId(sanitizeId(clip.id, `clip-${project.clips.length + 1}`), existing);
+  const name = sanitizeId(clip.name, `Clip ${project.clips.length + 1}`);
+  return {
+    ...project,
+    clips: [...project.clips, createDefaultMidiClip({ ...cloneObject(clip), id, name })],
+    ui: { ...project.ui, selectedClipId: id, activeRegion: 'clips' }
+  };
+};
+
+const duplicateClip = (project, clipId, options = {}) => {
+  const clip = project.clips.find(item => item.id === clipId);
+  if (!clip) return project;
+  const id = uniqueId(
+    sanitizeId(options.id, `${clip.id}-copy`),
+    new Set(project.clips.map(item => item.id))
+  );
+  const name = uniqueName(
+    sanitizeId(options.name, `${clip.name} Copy`),
+    new Set(project.clips.map(item => item.name))
+  );
+  return {
+    ...project,
+    clips: [...project.clips, createDefaultMidiClip({ ...cloneObject(clip), id, name })],
+    ui: { ...project.ui, selectedClipId: id, activeRegion: 'clips' }
+  };
+};
+
+const removeClip = (project, clipId) => {
+  const index = project.clips.findIndex(clip => clip.id === clipId);
+  if (index < 0) return project;
+  const clips = project.clips.filter(clip => clip.id !== clipId);
+  const selectedClipId = project.ui.selectedClipId === clipId || !clips.some(clip => clip.id === project.ui.selectedClipId)
+    ? clips[index]?.id ?? clips[index - 1]?.id ?? null
+    : project.ui.selectedClipId;
+  return {
+    ...project,
+    clips,
+    sources: project.sources.map(source => (
+      source.mode === 'clip' && source.clipId === clipId
+        ? {
+          ...source,
+          mode: 'direct',
+          clipId: null,
+          mapping: createEmptyDirectMapping()
+        }
+        : source
+    )),
+    ui: { ...project.ui, selectedClipId, activeRegion: 'clips' }
+  };
+};
+
+const addAutomation = (project, automation = {}) => {
+  const existing = new Set(project.automation.map(item => item.id));
+  const target = AUTOMATION_TARGETS.includes(automation.target) ? automation.target : 'velocity';
+  const id = uniqueId(sanitizeId(automation.id, `automation-${project.automation.length + 1}`), existing);
+  return {
+    ...project,
+    automation: [...project.automation, createDefaultMidiAutomation({ ...cloneObject(automation), id, target })],
+    ui: { ...project.ui, activeRegion: 'automation' }
+  };
+};
+
+const removeById = (items, id) => items.filter(item => item.id !== id);
+
+const updateClipStep = (clips, clipId, stepIndex, patch) => clips.map(clip => {
+  if (clip.id !== clipId) return clip;
+  const index = clamp(toInteger(stepIndex, 0), 0, Math.max(clip.lengthSteps - 1, 0));
+  const steps = clip.steps.slice();
+  while (steps.length < clip.lengthSteps) {
+    steps.push(createDefaultMidiStep(steps.length, { note: null }));
+  }
+  steps[index] = {
+    ...createDefaultMidiStep(index, { note: null }),
+    ...steps[index],
+    ...cloneObject(patch),
+    index
+  };
+  return { ...clip, steps };
+});
+
+const updateAutomationPoint = (automation, automationId, pointIndex, patch) => automation.map(lane => {
+  if (lane.id !== automationId) return lane;
+  const index = Math.max(0, toInteger(pointIndex, 0));
+  const points = lane.points.slice();
+  while (points.length <= index) {
+    points.push({ beat: points.length, value: lane.min });
+  }
+  points[index] = { ...points[index], ...cloneObject(patch) };
+  return { ...lane, points };
+});
+
+const updateAutomationLane = (automation, automationId, patch, tracks) => {
+  const trackIds = new Set(tracks.map(track => track.id));
+  return automation.map(lane => {
+    if (lane.id !== automationId) return lane;
+    const cleanPatch = updatePatch(patch);
+    if (cleanPatch.trackId != null) {
+      const trackId = String(cleanPatch.trackId);
+      if (trackIds.has(trackId)) {
+        cleanPatch.trackId = trackId;
+      } else {
+        delete cleanPatch.trackId;
+      }
+    }
+    if (cleanPatch.scope === 'global') cleanPatch.trackId = null;
+    return { ...lane, ...cleanPatch };
+  });
+};
+
+function reduceMidiProject(project, intent = {}) {
+  const current = sanitizeMidiProject(project);
+  let next = current;
+  switch (intent?.type) {
+  case 'project.set':
+    return sanitizeMidiProject(intent.project);
+  case 'project.reset':
+    return createMidiProjectFromMidiConfig(intent.factoryConfig);
+  case 'enabled.set':
+    next = { ...current, enabled: Boolean(intent.enabled) };
+    break;
+  case 'devices.set':
+    next = { ...current, devices: { ...current.devices, ...cloneObject(intent.devices) } };
+    break;
+  case 'transport.set':
+    next = { ...current, transport: { ...current.transport, ...cloneObject(intent.transport) } };
+    break;
+  case 'global.update':
+    next = { ...current, global: { ...current.global, ...cloneObject(intent.patch ?? intent.global) } };
+    break;
+  case 'track.add':
+    next = addTrack(current, intent.track);
+    break;
+  case 'track.update':
+    next = { ...current, tracks: updateById(current.tracks, intent.trackId, updatePatch(intent.patch)) };
+    break;
+  case 'track.remove':
+    next = removeTrack(current, intent.trackId ?? current.ui.selectedTrackId);
+    break;
+  case 'track.select':
+    next = { ...current, ui: { ...current.ui, selectedTrackId: intent.trackId, activeRegion: 'tracks' } };
+    break;
+  case 'source.select':
+    next = { ...current, ui: { ...current.ui, selectedSourceId: intent.sourceId, activeRegion: 'sources' } };
+    break;
+  case 'source.update':
+    next = { ...current, sources: updateById(current.sources, intent.sourceId, updatePatch(intent.patch)) };
+    break;
+  case 'source.assignTrack': {
+    const trackId = intent.trackId == null ? null : String(intent.trackId);
+    next = current.tracks.some(track => track.id === trackId)
+      ? { ...current, sources: updateById(current.sources, intent.sourceId, { trackId }) }
+      : current;
+    break;
+  }
+  case 'source.mode.set': {
+    const requestedClipId = intent.clipId ?? current.ui.selectedClipId;
+    const validClipId = current.clips.some(clip => clip.id === requestedClipId)
+      ? requestedClipId
+      : null;
+    next = { ...current, sources: current.sources.map(source => {
+      if (source.id !== intent.sourceId) return source;
+      if (intent.mode === 'clip' && validClipId) {
+        return {
+          ...source,
+          mode: 'clip',
+          clipId: validClipId,
+          mapping: null
+        };
+      }
+      return {
+        ...source,
+        mode: 'direct',
+        clipId: null,
+        mapping: source.mapping || createEmptyDirectMapping()
+      };
+    }) };
+    break;
+  }
+  case 'source.clip.assign':
+    next = { ...current, sources: updateById(current.sources, intent.sourceId, {
+      mode: 'clip',
+      clipId: intent.clipId
+    }) };
+    break;
+  case 'source.mapping.update':
+    next = { ...current, sources: updateSourceMapping(current.sources, intent.sourceId, intent.patch) };
+    break;
+  case 'clip.add':
+    next = addClip(current, intent.clip);
+    break;
+  case 'clip.duplicate':
+    next = duplicateClip(current, intent.clipId ?? current.ui.selectedClipId, intent.clip);
+    break;
+  case 'clip.update':
+    next = { ...current, clips: updateById(current.clips, intent.clipId, updatePatch(intent.patch)) };
+    break;
+  case 'clip.remove':
+    next = removeClip(current, intent.clipId);
+    break;
+  case 'clip.step.update':
+    next = { ...current, clips: updateClipStep(current.clips, intent.clipId, intent.stepIndex, intent.patch) };
+    break;
+  case 'clip.select':
+    next = { ...current, ui: { ...current.ui, selectedClipId: intent.clipId, activeRegion: 'clips' } };
+    break;
+  case 'automation.add':
+    next = addAutomation(current, intent.automation);
+    break;
+  case 'automation.update':
+    next = { ...current, automation: updateAutomationLane(current.automation, intent.automationId, intent.patch, current.tracks) };
+    break;
+  case 'automation.point.update':
+    next = { ...current, automation: updateAutomationPoint(current.automation, intent.automationId, intent.pointIndex, intent.patch) };
+    break;
+  case 'automation.remove':
+    next = { ...current, automation: removeById(current.automation, intent.automationId) };
+    break;
+  case 'ui.set':
+    next = { ...current, ui: { ...current.ui, ...cloneObject(intent.ui) } };
+    break;
+  default:
+    return current;
+  }
+  return sanitizeMidiProject(touchProject(next));
+}
+
+const isTrackAudible = (track, hasSolo) => {
+  if (!track || track.mute) return false;
+  if (hasSolo && !track.solo) return false;
+  return true;
+};
+
+const buildRuntimeMapping = (source, track, hiddenByTrack, globalVelocityDefault) => {
+  const mapping = sanitizeDirectMapping(source.mapping);
+  const out = {};
+  for (const key of DIRECT_MAPPING_KEYS) {
+    const value = mapping[key];
+    if (value != null) out[key] = cloneSafeObject(value);
+  }
+  out.name = source.label;
+  out.channel = track.channel;
+  out.priority = track.priority;
+  out.voiceBudget = track.voiceBudget;
+  out.trackId = track.id;
+  out.outputId = track.outputId;
+  if (track.velocityScale !== 1) {
+    const velocity = Number.isFinite(out.velocity) ? out.velocity : globalVelocityDefault;
+    out.velocity = sanitizeVelocity(Math.round(velocity * track.velocityScale));
+  }
+  if (!source.enabled || hiddenByTrack) out.disabled = true;
+  return out;
+};
+
+const activeClipSteps = (clip) => (
+  Array.isArray(clip?.steps)
+    ? clip.steps
+      .filter(step => Number.isFinite(step?.note) && (step.probability ?? 1) > 0 && !step.tie)
+      .sort((a, b) => (a.index ?? 0) - (b.index ?? 0))
+    : []
+);
+
+const automationToPositionMappings = (automation = []) => automation
+  .filter(lane => lane.enabled && lane.scope === 'global')
+  .map(lane => {
+    const mapping = {
+      axis: lane.axis,
+      axisOp: lane.axisOp,
+      target: lane.target,
+      min: lane.min,
+      max: lane.max,
+      enabled: true
+    };
+    if (lane.points.length) mapping.points = lane.points.map(point => cloneObject(point));
+    return mapping;
+  });
+
+const runtimeBucketForSource = (source) => {
+  const kind = normalizeKind(source?.kind);
+  if (kind === 'sfx') return 'sfx';
+  if (kind === 'trigger' || kind === 'midiFlag') return 'triggers';
+  return null;
+};
+
+const isValidChannelValue = (value) => {
+  const number = Number(value);
+  return Number.isFinite(number) && Math.round(number) === number && number >= 1 && number <= 16;
+};
+
+const isValidInputChannelValue = (value) => (
+  value === 'omni' || value == null || value === '' || isValidChannelValue(value)
+);
+
+const issueId = (issue, index) => [
+  issue.code,
+  issue.sourceId || issue.trackId || issue.clipId || issue.runtimeKey || 'project',
+  index
+].join(':');
+
+const buildConflictReport = (issues) => {
+  const summary = { errors: 0, warnings: 0, infos: 0 };
+  const bySourceId = {};
+  const byTrackId = {};
+  const byClipId = {};
+  const addIndexedIssue = (index, issue) => ({
+    severity: issue.severity || 'warning',
+    id: issue.id || issueId(issue, index),
+    ...issue
+  });
+  const indexed = issues.map((issue, index) => addIndexedIssue(index, issue));
+  for (const issue of indexed) {
+    if (issue.severity === 'error') summary.errors += 1;
+    else if (issue.severity === 'info') summary.infos += 1;
+    else summary.warnings += 1;
+    if (issue.sourceId) {
+      if (!bySourceId[issue.sourceId]) bySourceId[issue.sourceId] = [];
+      bySourceId[issue.sourceId].push(issue);
+    }
+    if (issue.trackId) {
+      if (!byTrackId[issue.trackId]) byTrackId[issue.trackId] = [];
+      byTrackId[issue.trackId].push(issue);
+    }
+    if (issue.clipId) {
+      if (!byClipId[issue.clipId]) byClipId[issue.clipId] = [];
+      byClipId[issue.clipId].push(issue);
+    }
+  }
+  return {
+    ok: summary.errors === 0,
+    issues: indexed,
+    items: indexed,
+    summary,
+    bySourceId,
+    byTrackId,
+    byClipId
+  };
+};
+
+const mappingHasExplicitNote = (mapping = {}) => (
+  Number.isFinite(mapping.note) ||
+  Number.isFinite(mapping.degree) ||
+  (Array.isArray(mapping.notes) && mapping.notes.some(Number.isFinite)) ||
+  mapping.chord != null ||
+  mapping.arp != null
+);
+
+const collectMappingNotes = (mapping = {}) => {
+  if (Array.isArray(mapping.notes) && mapping.notes.length) {
+    return mapping.notes.filter(Number.isFinite);
+  }
+  return Number.isFinite(mapping.note) ? [mapping.note] : [];
+};
+
+const collectClipNotes = (clip) => activeClipSteps(clip).map(step => step.note).filter(Number.isFinite);
+
+const noteRangeIssues = ({ notes, range, source, clip, path }) => {
+  const issues = [];
+  const outOfRange = notes.filter(note => note < range.min || note > range.max);
+  if (outOfRange.length) {
+    issues.push({
+      severity: 'warning',
+      code: 'note_out_of_range',
+      sourceId: source?.id ?? null,
+      trackId: source?.trackId ?? null,
+      clipId: clip?.id ?? null,
+      path,
+      message: `Notes ${outOfRange.join(', ')} are outside the project note range ${range.min}-${range.max}.`
+    });
+  }
+  if (notes.length > 1) {
+    const clamped = notes.map(note => clamp(note, range.min, range.max));
+    const uniqueOriginal = new Set(notes).size;
+    const uniqueClamped = new Set(clamped).size;
+    if (uniqueClamped < uniqueOriginal) {
+      issues.push({
+        severity: 'warning',
+        code: 'note_range_collapse',
+        sourceId: source?.id ?? null,
+        trackId: source?.trackId ?? null,
+        clipId: clip?.id ?? null,
+        path,
+        message: `Project note range ${range.min}-${range.max} collapses multiple notes to the same output.`
+      });
+    }
+  }
+  return issues;
+};
+
+function detectMidiProjectConflicts(project = {}, options = {}) {
+  const clean = sanitizeMidiProject(project);
+  const raw = isPlainObject(project) ? project : {};
+  const rawTracks = cloneArray(raw.tracks);
+  const rawSources = cloneArray(raw.sources);
+  const rawClips = cloneArray(raw.clips);
+  const rawAutomation = cloneArray(raw.automation);
+  const issues = [];
+  const tracksById = new Map(clean.tracks.map(track => [track.id, track]));
+  const clipsById = new Map(clean.clips.map(clip => [clip.id, clip]));
+  const trackIds = new Set(clean.tracks.map(track => track.id));
+  const rawClipIds = new Set(rawClips
+    .map(clip => (clip?.id == null ? null : String(clip.id)))
+    .filter(Boolean));
+  const availableOutputIds = Array.isArray(options.availableOutputIds)
+    ? new Set(options.availableOutputIds.map(id => String(id)))
+    : null;
+
+  if (!isValidInputChannelValue(raw.devices?.inputChannel)) {
+    issues.push({
+      severity: 'warning',
+      code: 'invalid_input_channel',
+      path: ['devices', 'inputChannel'],
+      message: `Input channel ${raw.devices?.inputChannel} will be clamped to ${clean.devices.inputChannel}.`
+    });
+  }
+  if (options.requireOutput === true && clean.enabled && !clean.devices.outputId) {
+    issues.push({
+      severity: 'warning',
+      code: 'missing_project_output',
+      path: ['devices', 'outputId'],
+      message: 'MIDI is enabled but no project output is selected.'
+    });
+  }
+  if (availableOutputIds && clean.devices.outputId && !availableOutputIds.has(clean.devices.outputId)) {
+    issues.push({
+      severity: 'error',
+      code: 'invalid_project_output',
+      path: ['devices', 'outputId'],
+      message: `Project output ${clean.devices.outputId} is not available.`
+    });
+  }
+
+  clean.tracks.forEach((track, index) => {
+    const rawTrack = rawTracks[index];
+    if (isPlainObject(rawTrack) && rawTrack.channel != null && !isValidChannelValue(rawTrack.channel)) {
+      issues.push({
+        severity: 'warning',
+        code: 'invalid_track_channel',
+        trackId: track.id,
+        path: ['tracks', index, 'channel'],
+        message: `Track ${track.name} channel ${rawTrack.channel} will be clamped to ${track.channel}.`
+      });
+    }
+    if (track.outputId && availableOutputIds && !availableOutputIds.has(track.outputId)) {
+      issues.push({
+        severity: 'warning',
+        code: 'invalid_track_output',
+        trackId: track.id,
+        path: ['tracks', index, 'outputId'],
+        message: `Track output ${track.outputId} is not available.`
+      });
+    }
+  });
+
+  rawAutomation.forEach((automation, index) => {
+    if (!isPlainObject(automation) || automation.scope !== 'track' || automation.trackId == null) return;
+    const rawTrackId = String(automation.trackId);
+    if (trackIds.has(rawTrackId)) return;
+    const cleanLane = clean.automation[index] || null;
+    issues.push({
+      severity: 'warning',
+      code: 'missing_automation_track',
+      automationId: cleanLane?.id ?? sanitizeId(automation.id, `automation-${index + 1}`),
+      trackId: rawTrackId,
+      path: ['automation', index, 'trackId'],
+      message: `${cleanLane?.name || 'Automation lane'} references missing track ${rawTrackId}.`
+    });
+  });
+
+  const runtimeSources = new Map();
+  const hasSolo = clean.tracks.some(track => track.solo && !track.mute);
+  const noteRange = clean.global.noteRange;
+
+  clean.sources.forEach((source, index) => {
+    const rawSource = rawSources[index];
+    const rawTrackId = rawSource?.trackId == null ? null : String(rawSource.trackId);
+    const track = tracksById.get(source.trackId);
+    const bucket = runtimeBucketForSource(source);
+    if (bucket) {
+      const runtimeKey = `${bucket}:${source.sourceKey}`;
+      if (!runtimeSources.has(runtimeKey)) runtimeSources.set(runtimeKey, []);
+      runtimeSources.get(runtimeKey).push({ source, index });
+    }
+    if (rawTrackId && !trackIds.has(rawTrackId)) {
+      issues.push({
+        severity: 'error',
+        code: 'missing_track',
+        sourceId: source.id,
+        trackId: rawTrackId,
+        path: ['sources', index, 'trackId'],
+        message: `${source.label} references missing track ${rawTrackId}.`
+      });
+    }
+    if (!source.enabled) {
+      issues.push({
+        severity: 'info',
+        code: 'disabled_source',
+        sourceId: source.id,
+        trackId: source.trackId,
+        path: ['sources', index, 'enabled'],
+        message: `${source.label} is disabled.`
+      });
+    }
+    if (source.enabled && track?.mute) {
+      issues.push({
+        severity: 'warning',
+        code: 'track_muted',
+        sourceId: source.id,
+        trackId: track.id,
+        path: ['tracks', clean.tracks.indexOf(track), 'mute'],
+        message: `${source.label} is routed to muted track ${track.name}.`
+      });
+    } else if (source.enabled && hasSolo && track && !track.solo) {
+      issues.push({
+        severity: 'warning',
+        code: 'track_solo_hidden',
+        sourceId: source.id,
+        trackId: track.id,
+        path: ['tracks', clean.tracks.indexOf(track), 'solo'],
+        message: `${source.label} is hidden while another track is soloed.`
+      });
+    }
+
+    if (source.mode === 'clip') {
+      const clip = clipsById.get(source.clipId);
+      const rawClipId = rawSource?.clipId == null ? null : String(rawSource.clipId);
+      if (!source.clipId || !clip) {
+        issues.push({
+          severity: 'error',
+          code: 'missing_clip',
+          sourceId: source.id,
+          trackId: source.trackId,
+          clipId: rawClipId || source.clipId || null,
+          path: ['sources', index, 'clipId'],
+          message: `${source.label} is in clip mode without an assigned clip.`
+        });
+      } else if (rawClipId && rawClipIds.size && !rawClipIds.has(rawClipId)) {
+        issues.push({
+          severity: 'error',
+          code: 'missing_clip',
+          sourceId: source.id,
+          trackId: source.trackId,
+          clipId: rawClipId,
+          path: ['sources', index, 'clipId'],
+          message: `${source.label} references missing clip ${rawClipId}.`
+        });
+      } else {
+        const notes = collectClipNotes(clip);
+        if (!notes.length) {
+          issues.push({
+            severity: 'warning',
+            code: 'silent_clip',
+            sourceId: source.id,
+            trackId: source.trackId,
+            clipId: clip.id,
+            path: ['clips', clean.clips.indexOf(clip), 'steps'],
+            message: `${source.label} uses clip ${clip.name}, but it has no playable steps.`
+          });
+        }
+        issues.push(...noteRangeIssues({
+          notes,
+          range: noteRange,
+          source,
+          clip,
+          path: ['clips', clean.clips.indexOf(clip), 'steps']
+        }));
+      }
+    } else {
+      const mapping = source.mapping || createEmptyDirectMapping();
+      if (!mappingHasExplicitNote(mapping)) {
+        issues.push({
+          severity: 'warning',
+          code: 'implicit_default_mapping',
+          sourceId: source.id,
+          trackId: source.trackId,
+          path: ['sources', index, 'mapping'],
+          message: `${source.label} has no explicit note, degree, chord, or arp mapping.`
+        });
+      }
+      issues.push(...noteRangeIssues({
+        notes: collectMappingNotes(mapping),
+        range: noteRange,
+        source,
+        clip: null,
+        path: ['sources', index, 'mapping']
+      }));
+    }
+  });
+
+  for (const [runtimeKey, entries] of runtimeSources) {
+    if (entries.length <= 1) continue;
+    for (const { source, index } of entries) {
+      issues.push({
+        severity: 'error',
+        code: 'duplicate_source_key',
+        sourceId: source.id,
+        trackId: source.trackId,
+        runtimeKey,
+        path: ['sources', index, 'sourceKey'],
+        message: `Duplicate runtime key ${runtimeKey} will overwrite another source.`
+      });
+    }
+  }
+
+  return buildConflictReport(issues);
+}
+
+const buildRuntimeClipMapping = (source, track, clip, hiddenByTrack, globalVelocityDefault, globalDurationDefault) => {
+  const steps = activeClipSteps(clip);
+  const first = steps[0] || null;
+  const notes = steps.map(step => sanitizeNote(step.note));
+  const out = {
+    name: source.label,
+    channel: track.channel,
+    priority: track.priority,
+    voiceBudget: track.voiceBudget,
+    trackId: track.id,
+    outputId: track.outputId,
+    clipId: clip?.id ?? source.clipId,
+    clipType: clip?.type || 'stepPattern',
+    note: notes[0] ?? null,
+    velocity: first?.velocity ?? globalVelocityDefault,
+    durationTicks: first?.durationTicks ?? globalDurationDefault
+  };
+  if (notes.length > 1) out.notes = notes;
+  if (clip?.type === 'arp' && notes.length) {
+    out.arp = {
+      enabled: true,
+      mode: clip.arp?.mode || 'up',
+      length: notes.length,
+      pattern: isPlainObject(clip.arp?.pattern) ? cloneObject(clip.arp.pattern) : null
+    };
+  }
+  if (track.velocityScale !== 1) {
+    const velocity = Number.isFinite(out.velocity) ? out.velocity : globalVelocityDefault;
+    out.velocity = sanitizeVelocity(Math.round(velocity * track.velocityScale));
+  }
+  if (!source.enabled || hiddenByTrack || !notes.length) out.disabled = true;
+  return out;
+};
+
+function projectToMidiConfig(project, factoryConfig = {}) {
+  const clean = sanitizeMidiProject(project);
+  const base = mergeConfig(DEFAULT_CONFIG, factoryConfig || {});
+  const positionMappings = automationToPositionMappings(clean.automation);
+  const config = mergeConfig(base, {
+    enabled: clean.enabled,
+    timing: {
+      bpmBase: clean.transport.bpmBase,
+      timeSignature: clean.transport.timeSignature,
+      quantize: clean.transport.quantize,
+      swing: clean.transport.swing,
+      scheduleAheadMs: base.timing?.scheduleAheadMs ?? 0
+    },
+    scale: clean.global.scale,
+    noteRange: clean.global.noteRange,
+    velocityRange: clean.global.velocityRange,
+    durationTicks: clean.global.durationTicks,
+    density: clean.global.density,
+    envelope: clean.global.envelope,
+    position: {
+      ...clean.global.position,
+      mappings: positionMappings
+    },
+    mpe: clean.global.mpe,
+    limits: clean.global.limits,
+    reverse: clean.global.reverse,
+    input: {
+      ...(base.input || {}),
+      channel: clean.devices.inputChannel,
+      enabled: clean.enabled
+    }
+  });
+  config.sfx = {};
+  config.triggers = {};
+
+  const tracksById = new Map(clean.tracks.map(track => [track.id, track]));
+  const clipsById = new Map(clean.clips.map(clip => [clip.id, clip]));
+  const hasSolo = clean.tracks.some(track => track.solo && !track.mute);
+  const defaultVelocity = clean.global.velocityRange.default ?? DEFAULT_CONFIG.velocityRange.default;
+  const defaultDuration = clean.global.durationTicks.default ?? DEFAULT_CONFIG.durationTicks.default;
+  for (const source of clean.sources) {
+    const track = tracksById.get(source.trackId) || clean.tracks[0];
+    const hiddenByTrack = !isTrackAudible(track, hasSolo);
+    const mapping = source.mode === 'clip'
+      ? buildRuntimeClipMapping(source, track, clipsById.get(source.clipId), hiddenByTrack, defaultVelocity, defaultDuration)
+      : buildRuntimeMapping(source, track, hiddenByTrack, defaultVelocity);
+    if (source.kind === 'trigger' || source.kind === 'midiFlag') {
+      config.triggers[source.sourceKey] = mapping;
+    } else if (source.kind === 'sfx') {
+      config.sfx[source.sourceKey] = mapping;
+    }
+  }
+  return config;
+}
+
+export {
+  AUTOMATION_AXES,
+  AUTOMATION_TARGETS,
+  ARP_MODES,
+  DIRECT_MAPPING_KEYS,
+  MAX_DURATION_TICKS,
+  MIDI_PROJECT_EXPORT_KIND,
+  MIDI_PROJECT_VERSION,
+  MIDI_TEMPLATE_EXPORT_KIND,
+  MIN_DURATION_TICKS,
+  createDefaultMidiAutomation,
+  createDefaultMidiClip,
+  createDefaultMidiStep,
+  createDefaultMidiTrack,
+  createEmptyDirectMapping,
+  createMidiProjectExportPayload,
+  createMidiProjectTemplate,
+  detectMidiProjectConflicts,
+  createMidiProject,
+  createMidiProjectFromMidiConfig,
+  createMidiSourceFromMapping,
+  importMidiProjectPayload,
+  projectToMidiConfig,
+  reduceMidiProject,
+  sanitizeMidiProject,
+  stringifyMidiProjectExport
+};
diff --git a/js/midi/project/MidiProjectStorage.js b/js/midi/project/MidiProjectStorage.js
new file mode 100644
index 00000000..16b01752
--- /dev/null
+++ b/js/midi/project/MidiProjectStorage.js
@@ -0,0 +1,154 @@
+import {
+  createMidiProjectTemplate,
+  createMidiProjectFromMidiConfig,
+  sanitizeMidiProject
+} from './MidiProject.js';
+
+const PROJECT_STORAGE_KEY = 'lemmings.midi.project.v1';
+const TEMPLATE_STORAGE_KEY = 'lemmings.midi.templates.v1';
+const FACTORY_TEMPLATE_ID = 'midi-mapping';
+
+const LEGACY_MIDI_STORAGE_KEYS = Object.freeze([
+  'lemmings.midi.intent',
+  'lemmings.midi.overrides',
+  'lemmings.midi.inputId',
+  'lemmings.midi.outputId',
+  'lemmings.midi.enabled',
+  'lemmings.midi.inputChannel',
+  'lemmings.midi.viewPan',
+  'lemmings.midi.adsrTarget',
+  'lemmings.midi.tabLeft',
+  'lemmings.midi.tabRight',
+  'lemmings.midi.sectionStates',
+  'lemmings.midi.schemaHash',
+  'lemmings.midi.storageVersion',
+  'lemmings.midi.panelCollapsed',
+  'lemmings.midi.ui.audition'
+]);
+
+const safeGetItem = (storage, key) => {
+  try {
+    return storage?.getItem?.(key) ?? null;
+  } catch (e) {
+    return null;
+  }
+};
+
+const safeSetItem = (storage, key, value) => {
+  try {
+    storage?.setItem?.(key, value);
+  } catch (e) {
+    // Storage is optional; callers still get a sanitized in-memory project.
+  }
+};
+
+const safeRemoveItem = (storage, key) => {
+  try {
+    storage?.removeItem?.(key);
+  } catch (e) {
+    // Storage cleanup is best-effort for private browsing and test doubles.
+  }
+};
+
+const cleanupLegacyMidiProjectStorage = (storage) => {
+  for (const key of LEGACY_MIDI_STORAGE_KEYS) {
+    safeRemoveItem(storage, key);
+  }
+};
+
+const saveMidiProject = (storage, project) => {
+  const clean = sanitizeMidiProject(project);
+  safeSetItem(storage, PROJECT_STORAGE_KEY, JSON.stringify(clean));
+  return clean;
+};
+
+const readStoredMidiProject = (storage) => {
+  const raw = safeGetItem(storage, PROJECT_STORAGE_KEY);
+  if (!raw) return null;
+  try {
+    return sanitizeMidiProject(JSON.parse(raw));
+  } catch (e) {
+    return null;
+  }
+};
+
+const readStoredMidiProjectTemplates = (storage) => {
+  const raw = safeGetItem(storage, TEMPLATE_STORAGE_KEY);
+  if (!raw) return [];
+  try {
+    const parsed = JSON.parse(raw);
+    const entries = Array.isArray(parsed) ? parsed : parsed.templates;
+    if (!Array.isArray(entries)) return [];
+    return entries
+      .map(template => createMidiProjectTemplate(template?.project, template))
+      .filter(template => template.id);
+  } catch (e) {
+    return [];
+  }
+};
+
+const saveStoredMidiProjectTemplates = (storage, templates) => {
+  const clean = Array.isArray(templates)
+    ? templates.map(template => createMidiProjectTemplate(template?.project, template))
+    : [];
+  safeSetItem(storage, TEMPLATE_STORAGE_KEY, JSON.stringify({ version: 1, templates: clean }));
+  return clean;
+};
+
+const saveMidiProjectTemplate = (storage, project, options = {}) => {
+  const template = createMidiProjectTemplate(project, options);
+  const templates = readStoredMidiProjectTemplates(storage)
+    .filter(entry => entry.id !== template.id);
+  templates.push(template);
+  saveStoredMidiProjectTemplates(storage, templates);
+  return template;
+};
+
+const resolveStoredMidiProjectTemplate = (storage, templateId) => (
+  readStoredMidiProjectTemplates(storage)
+    .find(template => template.id === templateId) || null
+);
+
+const loadMidiProject = (storage, factoryConfig = {}) => {
+  cleanupLegacyMidiProjectStorage(storage);
+  return readStoredMidiProject(storage) || createMidiProjectFromMidiConfig(factoryConfig);
+};
+
+const resetMidiProjectStorage = (storage, factoryConfig = {}, templateId = FACTORY_TEMPLATE_ID) => {
+  cleanupLegacyMidiProjectStorage(storage);
+  const template = templateId && templateId !== FACTORY_TEMPLATE_ID
+    ? resolveStoredMidiProjectTemplate(storage, templateId)
+    : null;
+  const project = template
+    ? sanitizeMidiProject({
+      ...template.project,
+      id: template.project.id,
+      name: template.name,
+      templateId: template.id,
+      createdAt: Date.now(),
+      updatedAt: Date.now()
+    })
+    : createMidiProjectFromMidiConfig(factoryConfig);
+  return saveMidiProject(storage, project);
+};
+
+const clearMidiProjectStorage = (storage) => {
+  cleanupLegacyMidiProjectStorage(storage);
+  safeRemoveItem(storage, PROJECT_STORAGE_KEY);
+};
+
+export {
+  LEGACY_MIDI_STORAGE_KEYS,
+  PROJECT_STORAGE_KEY,
+  TEMPLATE_STORAGE_KEY,
+  cleanupLegacyMidiProjectStorage,
+  clearMidiProjectStorage,
+  loadMidiProject,
+  readStoredMidiProject,
+  readStoredMidiProjectTemplates,
+  resetMidiProjectStorage,
+  resolveStoredMidiProjectTemplate,
+  saveMidiProject,
+  saveMidiProjectTemplate,
+  saveStoredMidiProjectTemplates
+};
diff --git a/js/midi/router/MidiEventRouterCore.js b/js/midi/router/MidiEventRouterCore.js
new file mode 100644
index 00000000..b7a1232b
--- /dev/null
+++ b/js/midi/router/MidiEventRouterCore.js
@@ -0,0 +1,36 @@
+import { MidiMapping } from '../MidiMapping.js';
+import { MidiScheduler } from '../MidiScheduler.js';
+import { midiEventRouterLifecycleMethods } from './MidiEventRouterLifecycleMethods.js';
+import { midiEventRouterPlanningMethods } from './MidiEventRouterPlanningMethods.js';
+import { midiEventRouterEventMethods } from './MidiEventRouterEventMethods.js';
+
+class MidiEventRouter {
+  constructor(mapping = null) {
+    this.mapping = mapping instanceof MidiMapping ? mapping : new MidiMapping(mapping || {});
+    this.scheduler = new MidiScheduler(this.mapping.config);
+    this.soundBus = null;
+    this.context = {};
+    this._lastTickBySfx = new Map();
+    this._tickCounter = { tick: null, count: 0 };
+    this._clockBaseMs = null;
+    this._clockFrameMs = null;
+    this._clockSpeedFactor = null;
+    this._lastAcceptedBySfx = new Map();
+    this._arpStateBySfx = new Map();
+    this._repeatHistoryByKey = new Map();
+    this._singleNoteBuffer = [0];
+    this._arpNotesScratch = [];
+    this._arpPatternScratch = [];
+    this._lastRateReport = null;
+    this._boundOnEvent = this._onEvent.bind(this);
+  }
+}
+
+Object.assign(
+  MidiEventRouter.prototype,
+  midiEventRouterLifecycleMethods,
+  midiEventRouterPlanningMethods,
+  midiEventRouterEventMethods
+);
+
+export { MidiEventRouter };
diff --git a/js/midi/router/MidiEventRouterEventMethods.js b/js/midi/router/MidiEventRouterEventMethods.js
new file mode 100644
index 00000000..d935c0e0
--- /dev/null
+++ b/js/midi/router/MidiEventRouterEventMethods.js
@@ -0,0 +1,232 @@
+import { MidiMapping } from '../MidiMapping.js';
+import { MidiScheduler } from '../MidiScheduler.js';
+import { isMidiFlagTriggerType } from '../MidiFlagTriggers.js';
+import { getAppContext } from '../../core/dependencies.js';
+import {
+  canMeasurePerformance,
+  recordPerformanceMeasure
+} from '../../util/performanceInstrumentation.js';
+import {
+  MAX_ARP_STATE_ENTRIES,
+  MAX_EVENTS_PER_TICK,
+  MAX_MIDI_MESSAGES_PER_SECOND,
+  MAX_REPEAT_HISTORY_KEYS
+} from './MidiEventRouterShared.js';
+
+const midiEventRouterEventMethods = {
+  _onEvent(event) {
+    const app = this.context?.app || getAppContext();
+    const perfEnabled = !!app &&
+        (app.performanceAPI === true || app.perfMetrics === true) &&
+        canMeasurePerformance();
+    const perfStart = perfEnabled ? performance.now() : 0;
+    try {
+      if (!event || event.sfxId == null) return;
+      if (!this.mapping.config?.enabled) return;
+      if (typeof this.scheduler.hasAnyOutput === 'function') {
+        if (!this.scheduler.hasAnyOutput()) return;
+      } else if (!this.scheduler.output) {
+        return;
+      }
+      const now = this._nowMs();
+      const tick = event.tick;
+      if (tick != null && this._tickCounter.tick !== tick) {
+        this._tickCounter.tick = tick;
+        this._tickCounter.count = 0;
+      }
+      const limits = this.mapping.config?.limits || {};
+      const maxPerTick = Math.min(Math.max(limits.maxEventsPerTick ?? MAX_EVENTS_PER_TICK, 1), MAX_EVENTS_PER_TICK);
+      const tickMs = this._tickMsFromEvent(event);
+      this.scheduler.setTickMs(tickMs);
+      const density = this._densityForEvent(event);
+      const viewRect = this.context?.stage?.getGameViewRect?.() || null;
+      const context = {
+        levelWidth: this.context?.game?.level?.width ?? this.context?.level?.width ?? null,
+        levelHeight: this.context?.game?.level?.height ?? this.context?.level?.height ?? null,
+        viewRect
+      };
+      const baseSfx = this.mapping.getSfxConfig(event.sfxId) || {};
+      const triggerCfg = event?.triggerType != null
+        ? this.mapping.config?.triggers?.[String(event.triggerType)] || null
+        : null;
+      if (isMidiFlagTriggerType(event?.triggerType) && !triggerCfg) {
+        return;
+      }
+      const sfx = triggerCfg ? { ...baseSfx, ...triggerCfg } : baseSfx;
+      const spec = this.mapping.mapEvent(event, context, density, sfx);
+      if (!spec) return;
+      if (typeof this.scheduler.hasOutput === 'function' && !this.scheduler.hasOutput(spec.outputId ?? null)) {
+        return;
+      }
+      spec.reverse = !!event.reverse;
+      if (tick != null && this._tickCounter.count >= maxPerTick) return;
+      if (tick != null) {
+        this._tickCounter.count += 1;
+      }
+      if (event.tick != null) {
+        this._lastTickBySfx.set(event.sfxId, event.tick);
+      }
+      const priority = this._getEventPriority(event, sfx);
+      const meta = {
+        sfxId: event.sfxId,
+        eventType: event.type,
+        priority,
+        triggerType: event.triggerType ?? null,
+        trackId: spec.trackId ?? null,
+        voiceBudget: spec.voiceBudget ?? null,
+        outputId: spec.outputId ?? null
+      };
+      const scheduleAhead = this.mapping.config?.timing?.scheduleAheadMs ?? 0;
+      const base = this._resolveScheduleBase(event.timeMs, event.frameMs, event.speedFactor);
+      const rawTime = Number.isFinite(event.timeMs) && base != null ? base + event.timeMs : now;
+      const sendTimeMs = Math.max(rawTime, now + scheduleAhead);
+      let noteList;
+      if (Array.isArray(spec.notes) && spec.notes.length) {
+        noteList = spec.notes;
+      } else {
+        this._singleNoteBuffer[0] = spec.note;
+        noteList = this._singleNoteBuffer;
+      }
+
+      const arp = spec.arp;
+      let activeNotes = noteList;
+      if (arp?.enabled && noteList.length) {
+        const sorted = this._arpNotesScratch;
+        sorted.length = 0;
+        for (let i = 0; i < noteList.length; i += 1) {
+          sorted.push(noteList[i]);
+        }
+        sorted.sort((a, b) => a - b);
+        const length = Math.max(1, Math.min(arp.length ?? sorted.length, sorted.length));
+        let seqKey = '';
+        for (let i = 0; i < length; i += 1) {
+          seqKey += i === 0 ? String(sorted[i]) : `,${sorted[i]}`;
+        }
+        const patternSteps = this._arpPatternScratch;
+        patternSteps.length = 0;
+        if (Array.isArray(arp?.pattern?.steps)) {
+          for (const rawStep of arp.pattern.steps) {
+            const step = String(rawStep || '').trim().toLowerCase();
+            if (step === 'up' || step === 'down' || step === 'hold') {
+              patternSteps.push(step);
+            }
+          }
+        }
+        const useCustomPattern = arp?.pattern?.preset === 'custom' && patternSteps.length > 0;
+        const patternKey = useCustomPattern ? patternSteps.join(',') : '';
+        const arpKey = this._resolveArpKey(event, sfx);
+        const state = this._arpStateBySfx.get(arpKey) || {
+          index: 0,
+          dir: 1,
+          mode: arp.mode,
+          length,
+          seqKey,
+          patternKey,
+          patternIndex: 0
+        };
+        if (
+          state.mode !== arp.mode ||
+            state.length !== length ||
+            state.seqKey !== seqKey ||
+            state.patternKey !== patternKey
+        ) {
+          state.index = 0;
+          state.dir = 1;
+          state.patternIndex = 0;
+        }
+        state.mode = arp.mode;
+        state.length = length;
+        state.seqKey = seqKey;
+        state.patternKey = patternKey;
+        let idx = state.index;
+        if (idx >= length || idx < 0) idx = 0;
+        if (length <= 1) {
+          this._singleNoteBuffer[0] = sorted[0];
+          activeNotes = this._singleNoteBuffer;
+          state.index = 0;
+          state.dir = 1;
+          state.patternIndex = 0;
+        } else if (useCustomPattern) {
+          this._singleNoteBuffer[0] = sorted[idx];
+          activeNotes = this._singleNoteBuffer;
+          const step = patternSteps[state.patternIndex % patternSteps.length] || 'hold';
+          let nextIdx = idx;
+          if (step === 'up') {
+            nextIdx = idx + 1;
+          } else if (step === 'down') {
+            nextIdx = idx - 1;
+          }
+          if (nextIdx >= length) {
+            nextIdx = 0;
+          } else if (nextIdx < 0) {
+            nextIdx = length - 1;
+          }
+          state.index = nextIdx;
+          state.patternIndex = (state.patternIndex + 1) % patternSteps.length;
+        } else if (arp.mode === 'down') {
+          this._singleNoteBuffer[0] = sorted[length - 1 - idx];
+          activeNotes = this._singleNoteBuffer;
+          state.index = idx + 1;
+        } else if (arp.mode === 'updown') {
+          this._singleNoteBuffer[0] = sorted[idx];
+          activeNotes = this._singleNoteBuffer;
+          if (idx + state.dir >= length || idx + state.dir < 0) {
+            state.dir *= -1;
+          }
+          state.index = idx + state.dir;
+        } else {
+          this._singleNoteBuffer[0] = sorted[idx];
+          activeNotes = this._singleNoteBuffer;
+          state.index = idx + 1;
+        }
+        this._storeArpState(arpKey, state);
+      }
+
+      const repeatCfg = { ...(this.mapping.config?.repeat || {}), ...(sfx.repeat || {}) };
+      const bpm = this._getBpm();
+      const repeatKey = event?.triggerType != null
+        ? `trigger:${event.triggerType}:${event.sfxId}`
+        : `sfx:${event.sfxId}`;
+      const repeatFactor = this._getRepeatFactor(repeatKey, sendTimeMs, repeatCfg, bpm);
+      const hasAmount = Number.isFinite(repeatCfg.amount);
+      const velocityBoost = hasAmount ? 0 : (repeatCfg.velocityBoost ?? 0);
+      const durationBoost = hasAmount ? 0 : (repeatCfg.durationBoost ?? 0);
+      const velocityScale = 1 + velocityBoost * repeatFactor;
+      const durationScale = 1 + durationBoost * repeatFactor;
+      let specWithTime = {
+        ...spec,
+        timeMs: sendTimeMs,
+        velocity: Math.max(1, Math.min(127, Math.round((spec.velocity ?? 64) * velocityScale))),
+        durationTicks: Math.max(1, Math.round((spec.durationTicks ?? 1) * durationScale))
+      };
+      if (hasAmount && repeatFactor > 0) {
+        const adjusted = this._applyRepeatTarget(specWithTime, activeNotes, repeatCfg, repeatFactor);
+        specWithTime = adjusted.spec;
+        activeNotes = adjusted.activeNotes;
+      }
+      const plan = this._planEntries(specWithTime, sendTimeMs, activeNotes.length);
+      if (!this._shouldSend(meta, specWithTime, plan, now)) {
+        return;
+      }
+      for (const note of activeNotes) {
+        specWithTime.note = note;
+        this.scheduler.sendNote(specWithTime, meta);
+      }
+      this._lastAcceptedBySfx.set(event.sfxId, sendTimeMs);
+    } finally {
+      if (perfEnabled) {
+        recordPerformanceMeasure('MidiEventRouter onEvent', {
+          start: perfStart,
+          detail: { devtools: { track: 'MidiEventRouter', trackGroup: 'MIDI', color: 'primary', tooltipText: 'onEvent' } }
+        });
+      }
+    }
+  },
+
+  dispose() {
+    this.detach();
+    this.scheduler.dispose();
+  },
+};
+
+export { midiEventRouterEventMethods };
diff --git a/js/midi/router/MidiEventRouterLifecycleMethods.js b/js/midi/router/MidiEventRouterLifecycleMethods.js
new file mode 100644
index 00000000..94f34ec8
--- /dev/null
+++ b/js/midi/router/MidiEventRouterLifecycleMethods.js
@@ -0,0 +1,152 @@
+import { MidiMapping } from '../MidiMapping.js';
+import { MidiScheduler } from '../MidiScheduler.js';
+import { isMidiFlagTriggerType } from '../MidiFlagTriggers.js';
+import { getAppContext } from '../../core/dependencies.js';
+import {
+  canMeasurePerformance,
+  recordPerformanceMeasure
+} from '../../util/performanceInstrumentation.js';
+import {
+  MAX_ARP_STATE_ENTRIES,
+  MAX_EVENTS_PER_TICK,
+  MAX_MIDI_MESSAGES_PER_SECOND,
+  MAX_REPEAT_HISTORY_KEYS
+} from './MidiEventRouterShared.js';
+
+const midiEventRouterLifecycleMethods = {
+  setMapping(mapping) {
+    this.mapping = mapping instanceof MidiMapping ? mapping : new MidiMapping(mapping || {});
+    this.scheduler.setConfig(this.mapping.config);
+  },
+
+  setOutput(output) {
+    this.scheduler.setOutput(output);
+  },
+
+  setOutputs(outputs) {
+    this.scheduler.setOutputs?.(outputs);
+  },
+
+  attach(soundBus, context = {}) {
+    if (this.soundBus?.onEvent) {
+      this.soundBus.onEvent.off(this._boundOnEvent);
+    }
+    this.soundBus = soundBus;
+    this.context = context || {};
+    this.soundBus?.onEvent?.on(this._boundOnEvent);
+  },
+
+  detach() {
+    if (this.soundBus?.onEvent) {
+      this.soundBus.onEvent.off(this._boundOnEvent);
+    }
+    this.soundBus = null;
+  },
+
+  _tickMsFromEvent(event) {
+    if (Number.isFinite(event?.tps) && event.tps > 0) return 1000 / event.tps;
+    if (Number.isFinite(event?.frameMs) && event.frameMs > 0) return event.frameMs;
+    const timer = this.context?.game?.getGameTimer?.();
+    if (Number.isFinite(timer?.frameTime) && timer.frameTime > 0) {
+      return timer.frameTime;
+    }
+    return 60;
+  },
+
+  _densityForEvent(event) {
+    const windowTicks = this.mapping.config?.density?.windowTicks ?? 0;
+    if (!windowTicks || event?.tick == null || event?.sfxId == null) return 0;
+    const last = this._lastTickBySfx.get(event.sfxId);
+    if (last == null) return 0;
+    const delta = event.tick - last;
+    if (delta <= 0) return 1;
+    if (delta >= windowTicks) return 0;
+    return (windowTicks - delta) / windowTicks;
+  },
+
+  _nowMs() {
+    return typeof performance !== 'undefined' ? performance.now() : Date.now();
+  },
+
+  _resolveScheduleBase(eventTimeMs, frameMs, speedFactor) {
+    if (!Number.isFinite(eventTimeMs)) return null;
+    const frameChanged = Number.isFinite(frameMs) &&
+        this._clockFrameMs != null &&
+        Math.abs(frameMs - this._clockFrameMs) > 0.001;
+    const speedChanged = Number.isFinite(speedFactor) &&
+        this._clockSpeedFactor != null &&
+        speedFactor !== this._clockSpeedFactor;
+    if (frameChanged || speedChanged) {
+      this._clockBaseMs = null;
+      this._lastAcceptedBySfx.clear();
+      this._arpStateBySfx.clear();
+      this._repeatHistoryByKey.clear();
+      this.scheduler?.allNotesOff?.();
+      this.scheduler?.clearQueue?.();
+    }
+    if (this._clockBaseMs == null) {
+      this._clockBaseMs = this._nowMs() - eventTimeMs;
+    }
+    if (Number.isFinite(frameMs)) this._clockFrameMs = frameMs;
+    if (Number.isFinite(speedFactor)) this._clockSpeedFactor = speedFactor;
+    return this._clockBaseMs;
+  },
+
+  _getEventPriority(event, sfx) {
+    if (Number.isFinite(sfx?.priority)) return sfx.priority;
+    const priorityList = this.mapping.config?.limits?.prioritySfx || [];
+    if (priorityList.includes(event?.sfxId)) return 2;
+    return 1;
+  },
+
+  _getBpm() {
+    const base = this.mapping.config?.timing?.bpmBase ?? 120;
+    const speed = this.context?.game?.getGameTimer?.()?.speedFactor ?? 1;
+    return Math.max(20, base * speed);
+  },
+
+  _resolveArpKey(event, sfx) {
+    if (event?.triggerType != null && sfx?.arp?.independent) {
+      const objectId = Number.isFinite(event.objectId) ? event.objectId : null;
+      if (objectId != null) {
+        return `trigger:${event.triggerType}:${event.sfxId}:object:${objectId}`;
+      }
+      const lemmingId = Number.isFinite(event.lemmingId) ? event.lemmingId : null;
+      if (lemmingId != null) {
+        return `trigger:${event.triggerType}:${event.sfxId}:lemming:${lemmingId}`;
+      }
+      const x = Number.isFinite(event.x) ? Math.round(event.x) : 'x';
+      const y = Number.isFinite(event.y) ? Math.round(event.y) : 'y';
+      return `trigger:${event.triggerType}:${event.sfxId}:${x}:${y}`;
+    }
+    return `sfx:${event?.sfxId ?? 'unknown'}`;
+  },
+
+  _storeArpState(key, state) {
+    if (!key) return;
+    if (this._arpStateBySfx.has(key)) {
+      this._arpStateBySfx.delete(key);
+    }
+    this._arpStateBySfx.set(key, state);
+    while (this._arpStateBySfx.size > MAX_ARP_STATE_ENTRIES) {
+      const oldestKey = this._arpStateBySfx.keys().next().value;
+      if (oldestKey == null) break;
+      this._arpStateBySfx.delete(oldestKey);
+    }
+  },
+
+  _storeRepeatHistory(key, history) {
+    if (!key) return;
+    if (this._repeatHistoryByKey.has(key)) {
+      this._repeatHistoryByKey.delete(key);
+    }
+    this._repeatHistoryByKey.set(key, history);
+    while (this._repeatHistoryByKey.size > MAX_REPEAT_HISTORY_KEYS) {
+      const oldestKey = this._repeatHistoryByKey.keys().next().value;
+      if (oldestKey == null) break;
+      this._repeatHistoryByKey.delete(oldestKey);
+    }
+  },
+};
+
+export { midiEventRouterLifecycleMethods };
diff --git a/js/midi/router/MidiEventRouterPlanningMethods.js b/js/midi/router/MidiEventRouterPlanningMethods.js
new file mode 100644
index 00000000..1110fa41
--- /dev/null
+++ b/js/midi/router/MidiEventRouterPlanningMethods.js
@@ -0,0 +1,337 @@
+import { MidiMapping } from '../MidiMapping.js';
+import { MidiScheduler } from '../MidiScheduler.js';
+import { isMidiFlagTriggerType } from '../MidiFlagTriggers.js';
+import { getAppContext } from '../../core/dependencies.js';
+import {
+  canMeasurePerformance,
+  recordPerformanceMeasure
+} from '../../util/performanceInstrumentation.js';
+import {
+  MAX_ARP_STATE_ENTRIES,
+  MAX_EVENTS_PER_TICK,
+  MAX_MIDI_MESSAGES_PER_SECOND,
+  MAX_REPEAT_HISTORY_KEYS
+} from './MidiEventRouterShared.js';
+
+const midiEventRouterPlanningMethods = {
+  _getRepeatFactor(key, timeMs, repeatCfg, bpm) {
+    if (repeatCfg?.enabled === false) return 0;
+    const maxRepeats = Math.max(0, repeatCfg.maxRepeats ?? 0);
+    const windowBeats = repeatCfg.windowBeats ?? repeatCfg.spacingTicks ?? 0;
+    if (maxRepeats <= 0 || !Number.isFinite(timeMs) || windowBeats <= 0 || bpm <= 0) {
+      return 0;
+    }
+    const windowMs = (60000 / bpm) * windowBeats;
+    const history = this._repeatHistoryByKey.get(key) || [];
+    const cutoff = timeMs - windowMs;
+    const nextHistory = history.filter(entry => entry >= cutoff);
+    nextHistory.push(timeMs);
+    const maxEntries = Math.max(1, maxRepeats + 1);
+    if (nextHistory.length > maxEntries) {
+      nextHistory.splice(0, nextHistory.length - maxEntries);
+    }
+    this._storeRepeatHistory(key, nextHistory);
+    const repeatCount = Math.max(0, nextHistory.length - 1);
+    return Math.min(repeatCount / maxRepeats, 1);
+  },
+
+  _applyRepeatTarget(spec, activeNotes, repeatCfg, repeatFactor) {
+    if (!spec || repeatFactor <= 0) return { spec, activeNotes };
+    const hasAmount = Number.isFinite(repeatCfg.amount);
+    if (!hasAmount) return { spec, activeNotes };
+    const amount = repeatCfg.amount;
+    if (!amount) return { spec, activeNotes };
+    const delta = amount * repeatFactor;
+    const noteRange = this.mapping.config?.noteRange || { min: 0, max: 127 };
+    const positionCfg = this.mapping.config?.position || {};
+    const clampNote = value => Math.max(noteRange.min ?? 0, Math.min(noteRange.max ?? 127, value));
+    const clampValue = (value, min, max) => Math.max(min, Math.min(max, value));
+    const target = repeatCfg.target || 'velocity';
+    const updated = { ...spec };
+    let notes = activeNotes;
+
+    switch (target) {
+    case 'velocity':
+    case 'accent': {
+      const velocity = updated.velocity ?? 64;
+      updated.velocity = clampValue(Math.round(velocity * (1 + delta)), 1, 127);
+      return { spec: updated, activeNotes: notes };
+    }
+    case 'duration': {
+      const duration = updated.durationTicks ?? 1;
+      updated.durationTicks = Math.max(1, Math.round(duration * (1 + delta)));
+      return { spec: updated, activeNotes: notes };
+    }
+    case 'note': {
+      const noteDelta = Math.round(delta * 12);
+      notes = notes.map(note => clampNote(note + noteDelta));
+      updated.note = notes[0];
+      updated.notes = notes;
+      return { spec: updated, activeNotes: notes };
+    }
+    case 'timbre': {
+      if (!Number.isFinite(updated.timbre)) return { spec: updated, activeNotes: notes };
+      const tMin = positionCfg.timbreRange?.min ?? 0;
+      const tMax = positionCfg.timbreRange?.max ?? 127;
+      const range = tMax - tMin;
+      updated.timbre = clampValue(updated.timbre + delta * range, tMin, tMax);
+      return { spec: updated, activeNotes: notes };
+    }
+    case 'pan': {
+      if (!Number.isFinite(updated.pan)) return { spec: updated, activeNotes: notes };
+      const pMin = positionCfg.panRange?.min ?? -127;
+      const pMax = positionCfg.panRange?.max ?? 127;
+      const range = pMax - pMin;
+      updated.pan = clampValue(updated.pan + delta * range, pMin, pMax);
+      return { spec: updated, activeNotes: notes };
+    }
+    case 'pitchBend': {
+      if (!Number.isFinite(updated.pitchBend)) return { spec: updated, activeNotes: notes };
+      updated.pitchBend = clampValue(updated.pitchBend + delta, -1, 1);
+      return { spec: updated, activeNotes: notes };
+    }
+    case 'attack':
+    case 'decay': {
+      const velocity = updated.velocity ?? 64;
+      updated.velocity = clampValue(Math.round(velocity * (1 + delta)), 1, 127);
+      return { spec: updated, activeNotes: notes };
+    }
+    case 'sustain': {
+      const duration = updated.durationTicks ?? 1;
+      updated.durationTicks = Math.max(1, Math.round(duration * (1 + delta)));
+      return { spec: updated, activeNotes: notes };
+    }
+    case 'release': {
+      const releaseVelocity = updated.releaseVelocity ?? updated.velocity ?? 64;
+      updated.releaseVelocity = clampValue(Math.round(releaseVelocity * (1 + delta)), 1, 127);
+      return { spec: updated, activeNotes: notes };
+    }
+    default:
+      return { spec: updated, activeNotes: notes };
+    }
+  },
+
+  _planEntries(spec, sendTimeMs, noteCount = 1) {
+    const durationMs = Number.isFinite(spec.durationTicks) ? Math.max(0, spec.durationTicks * this.scheduler.tickMs) : 0;
+    const offTimeMs = sendTimeMs + durationMs;
+    const offMessages = durationMs > 0 ? (1 + (this.mapping.config?.mpe?.enabled ? 1 : 0)) : 0;
+    const estimate = this.scheduler.estimateMessages(spec);
+    const onMessages = Math.max(estimate.messages - offMessages, 0);
+    const onBytes = onMessages * 3;
+    const offBytes = offMessages * 3;
+    return {
+      on: { timeMs: sendTimeMs, count: onMessages * noteCount, bytes: onBytes * noteCount },
+      off: { timeMs: offTimeMs, count: offMessages * noteCount, bytes: offBytes * noteCount }
+    };
+  },
+
+  _shouldSend(meta, spec, plan, now) {
+    const limits = this.mapping.config?.limits || {};
+    const maxPerSecond = Math.min(Math.max(limits.maxEventsPerSecond ?? MAX_MIDI_MESSAGES_PER_SECOND, 1), MAX_MIDI_MESSAGES_PER_SECOND);
+    const hardMaxPerSecond = Math.min(
+      Math.max(limits.hardMaxEventsPerSecond ?? maxPerSecond, 1),
+      MAX_MIDI_MESSAGES_PER_SECOND
+    );
+    const snapshotForMax = typeof this.scheduler.evaluateAndReserve === 'function'
+      ? null
+      : this.scheduler.getRateSnapshot(now);
+    const maxBytes = limits.maxBytesPerSecond ??
+        this.scheduler._maxBytesPerSecond ??
+        snapshotForMax?.maxBytesPerSecond ??
+        3906;
+    const evaluation = typeof this.scheduler.evaluateAndReserve === 'function'
+      ? this.scheduler.evaluateAndReserve(plan, meta, now, {
+        softMaxMessagesPerSecond: maxPerSecond,
+        maxMessagesPerSecond: hardMaxPerSecond,
+        maxBytesPerSecond: maxBytes,
+        reserve: false
+      })
+      : (() => {
+        const budget = this.scheduler.getPlanBudget(plan, now);
+        const check = this.scheduler.canSchedule(plan, now, {
+          maxMessagesPerSecond: hardMaxPerSecond,
+          maxBytesPerSecond: maxBytes
+        });
+        return {
+          ...check,
+          softOk: budget.combined.count <= maxPerSecond && budget.combined.bytes <= maxBytes,
+          snapshot: budget.snapshot,
+          proposed: budget.proposed,
+          combined: budget.combined
+        };
+      })();
+    const reservePlan = () => typeof this.scheduler.reserveEvaluation === 'function'
+      ? this.scheduler.reserveEvaluation(evaluation, plan, meta, now)
+      : this.scheduler.reserve(plan, meta, now, {
+        maxMessagesPerSecond: hardMaxPerSecond,
+        maxBytesPerSecond: maxBytes
+      });
+    const snapshot = evaluation.snapshot;
+    let shareReport = null;
+    const combinedBySfx = () => {
+      const bySfx = new Map();
+      const addEntries = (entries) => {
+        for (const [sfxId, entry] of entries.entries()) {
+          const curr = bySfx.get(sfxId) || { count: 0, bytes: 0, priority: entry.priority ?? 1 };
+          curr.count += entry.count;
+          curr.bytes += entry.bytes;
+          if (entry.priority != null) curr.priority = entry.priority;
+          bySfx.set(sfxId, curr);
+        }
+      };
+      addEntries(snapshot.past.bySfx);
+      addEntries(snapshot.next.bySfx);
+      return bySfx;
+    };
+    const getShareReport = () => {
+      if (!shareReport) {
+        const bySfx = combinedBySfx();
+        const total = snapshot.past.count + snapshot.next.count;
+        const totalBytes = snapshot.past.bytes + snapshot.next.bytes;
+        shareReport = [];
+        for (const [sfxId, entry] of bySfx.entries()) {
+          shareReport.push({
+            sfxId,
+            count: entry.count,
+            bytes: entry.bytes,
+            priority: entry.priority ?? 1,
+            percentCount: total ? entry.count / total : 0,
+            percentBytes: totalBytes ? entry.bytes / totalBytes : 0
+          });
+        }
+        shareReport.sort((a, b) => b.count - a.count);
+      }
+      return shareReport;
+    };
+    const nextCount = evaluation.combined.count;
+    const nextBytes = evaluation.combined.bytes;
+    if (evaluation.softOk) {
+      const reservation = reservePlan();
+      if (!reservation.ok) {
+        this._lastRateReport = {
+          timeMs: now,
+          reason: reservation.reason,
+          snapshot: getShareReport()
+        };
+        return false;
+      }
+      meta.rateReserved = true;
+      meta.reservationId = reservation.reservationId;
+      return true;
+    }
+    if (nextBytes > maxBytes) {
+      this._lastRateReport = {
+        timeMs: now,
+        reason: 'byte-limit',
+        snapshot: getShareReport()
+      };
+      return false;
+    }
+    if (!evaluation.ok || nextCount > hardMaxPerSecond) {
+      this._lastRateReport = {
+        timeMs: now,
+        reason: evaluation.reason || 'count-limit',
+        snapshot: getShareReport()
+      };
+      return false;
+    }
+    const plannedCount = evaluation.proposed.count;
+    const plannedBytes = evaluation.proposed.bytes;
+    const priority = meta.priority ?? 1;
+    const bySfx = combinedBySfx();
+    let higherCount = 0;
+    let higherBytes = 0;
+    let sameGroupCount = 0;
+    let sameGroupBytes = 0;
+    const samePriority = [];
+    for (const [sfxId, entry] of bySfx.entries()) {
+      const entryPriority = entry.priority ?? 1;
+      if (entryPriority > priority) {
+        higherCount += entry.count;
+        higherBytes += entry.bytes;
+      } else if (entryPriority === priority) {
+        samePriority.push({ sfxId, count: entry.count, bytes: entry.bytes, priority: entryPriority });
+        sameGroupCount += entry.count;
+        sameGroupBytes += entry.bytes;
+      }
+    }
+    const available = Math.max(0, maxPerSecond - higherCount);
+    const availableBytes = Math.max(0, maxBytes - higherBytes);
+    if (available <= 0) {
+      this._lastRateReport = {
+        timeMs: now,
+        reason: 'priority-saturated',
+        snapshot: getShareReport()
+      };
+      return false;
+    }
+    if (availableBytes <= 0) {
+      this._lastRateReport = {
+        timeMs: now,
+        reason: 'byte-limit',
+        snapshot: getShareReport()
+      };
+      return false;
+    }
+
+    shareReport = getShareReport();
+    const sameGroup = shareReport.filter(entry => entry.priority === priority);
+    const current = sameGroup.find(entry => entry.sfxId === meta.sfxId);
+    const groupSize = sameGroup.length + (current ? 0 : 1);
+    const evenShare = 1 / groupSize;
+    const shareRatio = (current?.percentCount ?? evenShare) / evenShare;
+    const projectedGroupCount = sameGroupCount + plannedCount;
+    const projectedGroupBytes = sameGroupBytes + plannedBytes;
+    const overCount = projectedGroupCount > available
+      ? projectedGroupCount / Math.max(available, 1)
+      : 1;
+    const overBytes = projectedGroupBytes > availableBytes
+      ? projectedGroupBytes / Math.max(availableBytes, 1)
+      : 1;
+    const overageFactor = Math.max(1, overCount, overBytes);
+    const budgetCount = available / Math.max(groupSize, 1);
+    const budgetBytes = availableBytes / Math.max(groupSize, 1);
+    const projectedCount = (current?.count ?? 0) + plannedCount;
+    const projectedBytes = (current?.bytes ?? 0) + plannedBytes;
+    const overBudget = (budgetCount > 0 && projectedCount > budgetCount) ||
+        (budgetBytes > 0 && projectedBytes > budgetBytes);
+    const bpm = this._getBpm();
+    const beatMs = 60000 / bpm;
+    const spacingMs = beatMs * Math.max(1, shareRatio, overageFactor) / Math.max(priority, 1);
+    const lastAccepted = this._lastAcceptedBySfx.get(meta.sfxId) ?? -Infinity;
+    const okSpacing = (spec.timeMs ?? now) - lastAccepted >= spacingMs;
+    const limitReason = overBudget ? 'share-throttle' : 'count-limit';
+    this._lastRateReport = {
+      timeMs: now,
+      reason: okSpacing ? limitReason : 'spacing',
+      snapshot: shareReport
+    };
+    if (!okSpacing || overBudget) return false;
+    const reservation = reservePlan();
+    if (!reservation.ok) {
+      this._lastRateReport = {
+        timeMs: now,
+        reason: reservation.reason,
+        snapshot: getShareReport()
+      };
+      return false;
+    }
+    meta.rateReserved = true;
+    meta.reservationId = reservation.reservationId;
+    return true;
+  },
+
+  getRateReport() {
+    return this._lastRateReport;
+  },
+
+  getRateSnapshot() {
+    return this.scheduler.getRateSnapshot();
+  },
+
+  getUsageShare(window = 'past') {
+    return this.scheduler.getUsageShare(window);
+  },
+};
+
+export { midiEventRouterPlanningMethods };
diff --git a/js/midi/router/MidiEventRouterShared.js b/js/midi/router/MidiEventRouterShared.js
new file mode 100644
index 00000000..7b29a28f
--- /dev/null
+++ b/js/midi/router/MidiEventRouterShared.js
@@ -0,0 +1,11 @@
+const MAX_EVENTS_PER_TICK = 32;
+const MAX_MIDI_MESSAGES_PER_SECOND = 1000;
+const MAX_ARP_STATE_ENTRIES = 256;
+const MAX_REPEAT_HISTORY_KEYS = 512;
+
+export {
+  MAX_ARP_STATE_ENTRIES,
+  MAX_EVENTS_PER_TICK,
+  MAX_MIDI_MESSAGES_PER_SECOND,
+  MAX_REPEAT_HISTORY_KEYS
+};
diff --git a/js/midi/scheduler/MidiSchedulerChannelMethods.js b/js/midi/scheduler/MidiSchedulerChannelMethods.js
new file mode 100644
index 00000000..0555449a
--- /dev/null
+++ b/js/midi/scheduler/MidiSchedulerChannelMethods.js
@@ -0,0 +1,282 @@
+import { getAppContext } from '../../core/dependencies.js';
+import {
+  canMeasurePerformance,
+  recordPerformanceMeasure
+} from '../../util/performanceInstrumentation.js';
+import {
+  MAX_RATE_ENTRIES,
+  MIDI_BYTES_PER_SECOND,
+  MIDI_MESSAGE_BYTES,
+  clamp,
+  normalizeChannelNumber,
+  toFiniteNumber,
+  toPositiveInt
+} from './MidiSchedulerShared.js';
+
+const normalizeOutputId = (outputId) => (
+  outputId == null || outputId === '' ? null : String(outputId)
+);
+
+const normalizeTrackId = (trackId) => (
+  trackId == null || trackId === '' ? null : String(trackId)
+);
+
+const toOutputList = (outputs) => {
+  if (!outputs) return [];
+  if (Array.isArray(outputs)) return outputs;
+  if (typeof outputs.values === 'function') return Array.from(outputs.values());
+  return [];
+};
+
+const midiSchedulerChannelMethods = {
+  setConfig(config) {
+    this.config = config || {};
+    const maxActive = toPositiveInt(this.config.limits?.maxActiveNotes, 32);
+    this._maxActiveNotes = clamp(maxActive, 1, 32);
+    const maxMessages = toPositiveInt(this.config.limits?.maxEventsPerSecond, 1000);
+    const maxBytes = toPositiveInt(this.config.limits?.maxBytesPerSecond, MIDI_BYTES_PER_SECOND);
+    this._maxMessagesPerSecond = clamp(maxMessages, 1, 1000);
+    this._maxBytesPerSecond = maxBytes;
+    const members = Array.isArray(this.config.mpe?.memberChannels) ? this.config.mpe.memberChannels : [];
+    this._memberChannels = members
+      .map((channel) => normalizeChannelNumber(channel))
+      .filter((channel, index, list) => list.indexOf(channel) === index);
+    if (this.hasAnyOutput()) this._initMpe();
+  },
+
+  setOutput(output) {
+    this.output = output || null;
+    if (this.output) this._registerOutput(this.output);
+    this._initMpe(this.output);
+  },
+
+  setOutputs(outputs) {
+    this._outputsById.clear();
+    for (const output of toOutputList(outputs)) {
+      this._registerOutput(output);
+    }
+    if (this.output) this._registerOutput(this.output);
+    this._initMpe();
+  },
+
+  hasAnyOutput() {
+    return !!this.output || this._outputsById.size > 0;
+  },
+
+  hasOutput(outputId = null) {
+    return !!this._resolveOutput(outputId);
+  },
+
+  _registerOutput(output) {
+    const id = normalizeOutputId(output?.id);
+    if (id && output) this._outputsById.set(id, output);
+  },
+
+  _resolveOutputId(outputId = null) {
+    return normalizeOutputId(outputId);
+  },
+
+  _resolveOutput(outputId = null) {
+    const id = this._resolveOutputId(outputId);
+    if (id) {
+      return this._outputsById.get(id) ||
+        (normalizeOutputId(this.output?.id) === id ? this.output : null);
+    }
+    return this.output;
+  },
+
+  _listOutputs() {
+    const outputs = [];
+    const seenIds = new Set();
+    const seenOutputs = new Set();
+    const addOutput = (output) => {
+      if (!output || seenOutputs.has(output)) return;
+      const id = normalizeOutputId(output.id);
+      if (id && seenIds.has(id)) return;
+      outputs.push(output);
+      seenOutputs.add(output);
+      if (id) seenIds.add(id);
+    };
+    addOutput(this.output);
+    for (const output of this._outputsById.values()) {
+      addOutput(output);
+    }
+    return outputs;
+  },
+
+  _activeChannelKey(channelNumber, outputId = null) {
+    const id = this._resolveOutputId(outputId);
+    return id ? `${id}:${channelNumber}` : channelNumber;
+  },
+
+  _normalizeTrackId(trackId = null) {
+    return normalizeTrackId(trackId);
+  },
+
+  setTickMs(tickMs) {
+    if (Number.isFinite(tickMs) && tickMs > 0) {
+      this.tickMs = tickMs;
+    }
+  },
+
+  _nowMs() {
+    return typeof performance !== 'undefined' ? performance.now() : Date.now();
+  },
+
+  _initMpe(output = undefined) {
+    const outputs = output === undefined
+      ? this._listOutputs()
+      : (output ? [output] : []);
+    if (!outputs.length) return;
+    const mpe = this.config.mpe;
+    if (!mpe?.enabled) return;
+    const bend = mpe.pitchBendRange || { semitones: 2, cents: 0 };
+    const master = normalizeChannelNumber(mpe.masterChannel, 1);
+    const members = Array.isArray(mpe.memberChannels)
+      ? mpe.memberChannels.map((channel) => normalizeChannelNumber(channel))
+      : [];
+    const uniqueMembers = members
+      .filter((channel, index, list) => channel !== master && list.indexOf(channel) === index);
+    const channels = [master, ...uniqueMembers];
+    for (const targetOutput of outputs) {
+      for (const ch of channels) {
+        const channel = targetOutput.channels?.[ch];
+        if (!channel) continue;
+        channel.sendPitchBendRange(bend.semitones, bend.cents);
+        channel.sendPitchBend(0);
+      }
+    }
+    this._memberChannels = uniqueMembers.slice();
+  },
+
+  _stopActiveChannel(channelNumber, outputId = null) {
+    const activeKey = this._activeChannelKey(channelNumber, outputId);
+    const active = this._activeByChannel.get(activeKey);
+    const resolvedOutputId = active?.outputId ?? outputId;
+    const output = this._resolveOutput(resolvedOutputId);
+    if (!active || !output) return;
+    const channel = output.channels?.[channelNumber];
+    if (channel) {
+      channel.sendNoteOff(active.note);
+      channel.sendPitchBend(0);
+    }
+    this._activeByChannel.delete(activeKey);
+    if (active.token != null) {
+      this._activeNotes.delete(active.token);
+      this._removeScheduledNoteOff(active.token);
+    }
+  },
+
+  _removeScheduledNoteOff(token) {
+    if (token == null || !this._noteOffs.length) return;
+    for (let i = this._noteOffs.length - 1; i >= 0; i--) {
+      if (this._noteOffs[i].token === token) {
+        this._noteOffs.splice(i, 1);
+      }
+    }
+    this._armNoteOffTimer();
+  },
+
+  _findOldestActiveNote(matches = null) {
+    if (!this._activeNotes?.size || typeof this._activeNotes.entries !== 'function') return null;
+    let oldestToken = null;
+    let oldestTime = Infinity;
+    for (const [token, info] of this._activeNotes.entries()) {
+      if (!info || (matches && !matches(info, token))) continue;
+      if (info.startedAt < oldestTime) {
+        oldestTime = info.startedAt;
+        oldestToken = token;
+      }
+    }
+    return oldestToken;
+  },
+
+  _countActiveNotesForTrack(trackId) {
+    const normalized = normalizeTrackId(trackId);
+    if (!normalized || !this._activeNotes?.size || typeof this._activeNotes.entries !== 'function') return 0;
+    let count = 0;
+    for (const [, info] of this._activeNotes.entries()) {
+      if (normalizeTrackId(info?.trackId) === normalized) count += 1;
+    }
+    return count;
+  },
+
+  _stealOldestNoteForTrack(trackId) {
+    const normalized = normalizeTrackId(trackId);
+    if (!normalized) return;
+    const oldestToken = this._findOldestActiveNote(
+      info => normalizeTrackId(info?.trackId) === normalized
+    );
+    this._stopActiveNoteToken(oldestToken);
+  },
+
+  _stealOldestNote() {
+    const oldestToken = this._findOldestActiveNote();
+    this._stopActiveNoteToken(oldestToken);
+  },
+
+  _stopActiveNoteToken(oldestToken) {
+    if (oldestToken == null || !this.hasAnyOutput()) return;
+    if (typeof this._activeNotes?.get !== 'function') return;
+    const info = this._activeNotes.get(oldestToken);
+    if (!info) return;
+    const output = this._resolveOutput(info.outputId);
+    if (!output) return;
+    const channel = output.channels?.[info.channel];
+    let sentMessages = 0;
+    if (channel) {
+      channel.sendNoteOff(info.note);
+      sentMessages += 1;
+      if (info.mpe) {
+        channel.sendPitchBend(0);
+        sentMessages += 1;
+      }
+    }
+    if (typeof this._activeNotes.delete === 'function') {
+      this._activeNotes.delete(oldestToken);
+    }
+    if (info.mpe) {
+      this._activeByChannel.delete(this._activeChannelKey(info.channel, info.outputId));
+    }
+    this._removeScheduledNoteOff(oldestToken);
+    this._removePlannedRateEntries(oldestToken, 'off');
+    if (sentMessages > 0) {
+      this._recordSent({
+        timeMs: this._nowMs(),
+        count: sentMessages,
+        bytes: sentMessages * MIDI_MESSAGE_BYTES,
+        token: oldestToken,
+        phase: 'off'
+      });
+    }
+  },
+
+  _allocateChannel(outputId = null) {
+    const mpe = this.config.mpe;
+    if (!mpe?.enabled) {
+      return normalizeChannelNumber(this.config.defaultChannel, 1);
+    }
+    const normalizedOutputId = this._resolveOutputId(outputId);
+    for (const ch of this._memberChannels) {
+      if (!this._activeByChannel.has(this._activeChannelKey(ch, normalizedOutputId))) {
+        return ch;
+      }
+    }
+    let oldest = null;
+    let oldestTime = Infinity;
+    for (const [ch, info] of this._activeByChannel.entries()) {
+      if (this._resolveOutputId(info?.outputId) !== normalizedOutputId) continue;
+      if (info.startedAt < oldestTime) {
+        oldestTime = info.startedAt;
+        oldest = info.channel ?? ch;
+      }
+    }
+    if (oldest != null) {
+      this._stopActiveChannel(oldest, normalizedOutputId);
+      return oldest;
+    }
+    return normalizeChannelNumber(mpe.masterChannel, 1);
+  },
+};
+
+export { midiSchedulerChannelMethods };
diff --git a/js/midi/scheduler/MidiSchedulerCore.js b/js/midi/scheduler/MidiSchedulerCore.js
new file mode 100644
index 00000000..5b2ff24f
--- /dev/null
+++ b/js/midi/scheduler/MidiSchedulerCore.js
@@ -0,0 +1,36 @@
+import { MIDI_BYTES_PER_SECOND } from './MidiSchedulerShared.js';
+import { midiSchedulerChannelMethods } from './MidiSchedulerChannelMethods.js';
+import { midiSchedulerRateMethods } from './MidiSchedulerRateMethods.js';
+import { midiSchedulerSendMethods } from './MidiSchedulerSendMethods.js';
+
+class MidiScheduler {
+  constructor(config = {}) {
+    this.output = null;
+    this._outputsById = new Map();
+    this.tickMs = 60;
+    this._activeByChannel = new Map();
+    this._activeNotes = new Map();
+    this._maxActiveNotes = 32;
+    this._memberChannels = [];
+    this._noteOffs = [];
+    this._noteOffTimerId = 0;
+    this._noteOffSeq = 0;
+    this._rateWindowMs = 1000;
+    this._rateSent = [];
+    this._ratePlanned = [];
+    this._reservationSeq = 0;
+    this._maxMessagesPerSecond = 1000;
+    this._maxBytesPerSecond = MIDI_BYTES_PER_SECOND;
+    this._lastRateErrorMs = 0;
+    this.setConfig(config);
+  }
+}
+
+Object.assign(
+  MidiScheduler.prototype,
+  midiSchedulerChannelMethods,
+  midiSchedulerRateMethods,
+  midiSchedulerSendMethods
+);
+
+export { MidiScheduler };
diff --git a/js/midi/scheduler/MidiSchedulerRateMethods.js b/js/midi/scheduler/MidiSchedulerRateMethods.js
new file mode 100644
index 00000000..c5e33dc6
--- /dev/null
+++ b/js/midi/scheduler/MidiSchedulerRateMethods.js
@@ -0,0 +1,315 @@
+import { getAppContext } from '../../core/dependencies.js';
+import {
+  canMeasurePerformance,
+  recordPerformanceMeasure
+} from '../../util/performanceInstrumentation.js';
+import {
+  MAX_RATE_ENTRIES,
+  MIDI_BYTES_PER_SECOND,
+  MIDI_MESSAGE_BYTES,
+  clamp,
+  normalizeChannelNumber,
+  toFiniteNumber,
+  toPositiveInt
+} from './MidiSchedulerShared.js';
+
+const midiSchedulerRateMethods = {
+  _pruneRateEntries(now) {
+    const cutoff = now - this._rateWindowMs;
+    if (this._rateSent.length) {
+      let write = 0;
+      for (let read = 0; read < this._rateSent.length; read += 1) {
+        const entry = this._rateSent[read];
+        if (entry.timeMs < cutoff) continue;
+        this._rateSent[write] = entry;
+        write += 1;
+      }
+      this._rateSent.length = write;
+    }
+    if (this._ratePlanned.length) {
+      let write = 0;
+      for (let read = 0; read < this._ratePlanned.length; read += 1) {
+        const entry = this._ratePlanned[read];
+        if (entry.timeMs < now) {
+          this._rateSent.push(entry);
+        } else {
+          this._ratePlanned[write] = entry;
+          write += 1;
+        }
+      }
+      this._ratePlanned.length = write;
+    }
+    this._trimRateEntries();
+  },
+
+  _trimRateEntries() {
+    if (this._rateSent.length > MAX_RATE_ENTRIES) {
+      this._rateSent.splice(0, this._rateSent.length - MAX_RATE_ENTRIES);
+    }
+    if (this._ratePlanned.length > MAX_RATE_ENTRIES) {
+      this._ratePlanned.splice(0, this._ratePlanned.length - MAX_RATE_ENTRIES);
+    }
+  },
+
+  _sumRate(entries, startMs, endMs) {
+    let count = 0;
+    let bytes = 0;
+    const bySfx = new Map();
+    const byTrack = new Map();
+    const byOutput = new Map();
+    const addShare = (map, key, entry) => {
+      const curr = map.get(key) || { count: 0, bytes: 0, priority: entry.priority ?? 1 };
+      curr.count += entry.count;
+      curr.bytes += entry.bytes;
+      if (entry.priority != null) curr.priority = entry.priority;
+      if (entry.voiceBudget != null) curr.voiceBudget = entry.voiceBudget;
+      map.set(key, curr);
+    };
+    for (const entry of entries) {
+      if (entry.timeMs < startMs || entry.timeMs >= endMs) continue;
+      count += entry.count;
+      bytes += entry.bytes;
+      addShare(bySfx, entry.sfxId ?? 'unknown', entry);
+      addShare(byTrack, entry.trackId ?? 'project', entry);
+      addShare(byOutput, entry.outputId ?? 'project', entry);
+    }
+    return { count, bytes, bySfx, byTrack, byOutput };
+  },
+
+  _planEntries(plan) {
+    if (!plan || typeof plan !== 'object') return [];
+    if (Array.isArray(plan.entries)) return plan.entries;
+    const entries = [];
+    if (plan.on) entries.push({ ...plan.on, phase: 'on' });
+    if (plan.off) entries.push({ ...plan.off, phase: 'off' });
+    return entries;
+  },
+
+  _sumPlan(plan, now) {
+    let count = 0;
+    let bytes = 0;
+    const startMs = now - this._rateWindowMs;
+    const endMs = now + this._rateWindowMs;
+    for (const entry of this._planEntries(plan)) {
+      if (!Number.isFinite(entry?.timeMs)) continue;
+      if (entry.timeMs < startMs || entry.timeMs >= endMs) continue;
+      const entryCount = Math.trunc(toFiniteNumber(entry.count, 0));
+      if (entryCount <= 0) continue;
+      const entryBytes = Math.trunc(toFiniteNumber(entry.bytes, entryCount * MIDI_MESSAGE_BYTES));
+      if (entryBytes <= 0) continue;
+      count += entryCount;
+      bytes += entryBytes;
+    }
+    return { count, bytes };
+  },
+
+  getPlanBudget(plan, now = this._nowMs()) {
+    const snapshot = this.getRateSnapshot(now);
+    const proposed = this._sumPlan(plan, now);
+    return {
+      snapshot,
+      proposed,
+      combined: {
+        count: snapshot.past.count + snapshot.next.count + proposed.count,
+        bytes: snapshot.past.bytes + snapshot.next.bytes + proposed.bytes
+      }
+    };
+  },
+
+  canSchedule(plan, now = this._nowMs(), options = {}) {
+    return this.evaluateAndReserve(plan, {}, now, {
+      ...options,
+      reserve: false
+    });
+  },
+
+  evaluateAndReserve(plan, meta = {}, now = this._nowMs(), options = {}) {
+    const maxMessages = Math.min(
+      Math.max(options.maxMessagesPerSecond ?? this._maxMessagesPerSecond, 1),
+      1000
+    );
+    const softMaxMessages = Math.min(
+      Math.max(options.softMaxMessagesPerSecond ?? maxMessages, 1),
+      maxMessages
+    );
+    const maxBytes = Math.max(1, options.maxBytesPerSecond ?? this._maxBytesPerSecond);
+    this._pruneRateEntries(now);
+    const snapshot = {
+      now,
+      past: this._sumRate(this._rateSent, now - this._rateWindowMs, now),
+      next: this._sumRate(this._ratePlanned, now, now + this._rateWindowMs),
+      maxMessagesPerSecond: this._maxMessagesPerSecond,
+      maxBytesPerSecond: this._maxBytesPerSecond
+    };
+    const proposed = this._sumPlan(plan, now);
+    const combined = {
+      count: snapshot.past.count + snapshot.next.count + proposed.count,
+      bytes: snapshot.past.bytes + snapshot.next.bytes + proposed.bytes
+    };
+    const overMessages = combined.count > maxMessages;
+    const overBytes = combined.bytes > maxBytes;
+    const softOverMessages = combined.count > softMaxMessages;
+    const result = {
+      ok: !overMessages && !overBytes,
+      softOk: !softOverMessages && !overBytes,
+      reason: overBytes ? 'byte-limit' : (overMessages ? 'count-limit' : null),
+      maxMessagesPerSecond: maxMessages,
+      softMaxMessagesPerSecond: softMaxMessages,
+      maxBytesPerSecond: maxBytes,
+      snapshot,
+      proposed,
+      combined
+    };
+    if (!result.ok || options.reserve === false) return result;
+    return this.reserveEvaluation(result, plan, meta, now);
+  },
+
+  reserveEvaluation(evaluation, plan, meta = {}, now = this._nowMs()) {
+    if (!evaluation?.ok) return evaluation || { ok: false, reason: 'count-limit' };
+    if (evaluation.reservationId) return evaluation;
+    const reservationId = ++this._reservationSeq;
+    this._pruneRateEntries(now);
+    for (const entry of this._planEntries(plan)) {
+      const count = Math.trunc(toFiniteNumber(entry.count, 0));
+      if (count <= 0) continue;
+      const bytes = Math.trunc(toFiniteNumber(entry.bytes, count * MIDI_MESSAGE_BYTES));
+      if (bytes <= 0) continue;
+      this._recordPlanned({
+        timeMs: entry.timeMs,
+        count,
+        bytes,
+        phase: entry.phase ?? null,
+        reservationId,
+        sfxId: meta.sfxId ?? null,
+        priority: meta.priority ?? 1,
+        triggerType: meta.triggerType ?? null,
+        trackId: meta.trackId ?? null,
+        outputId: meta.outputId ?? null,
+        voiceBudget: meta.voiceBudget ?? null
+      }, now);
+    }
+    return {
+      ...evaluation,
+      ok: true,
+      reservationId
+    };
+  },
+
+  reserve(plan, meta = {}, now = this._nowMs(), options = {}) {
+    return this.evaluateAndReserve(plan, meta, now, {
+      ...options,
+      reserve: true
+    });
+  },
+
+  getRateSnapshot(now = this._nowMs()) {
+    this._pruneRateEntries(now);
+    const past = this._sumRate(this._rateSent, now - this._rateWindowMs, now);
+    const next = this._sumRate(this._ratePlanned, now, now + this._rateWindowMs);
+    return {
+      now,
+      past,
+      next,
+      maxMessagesPerSecond: this._maxMessagesPerSecond,
+      maxBytesPerSecond: this._maxBytesPerSecond
+    };
+  },
+
+  getUsageShare(window = 'past', now = this._nowMs()) {
+    const snapshot = this.getRateSnapshot(now);
+    const data = window === 'next' ? snapshot.next : snapshot.past;
+    const total = data.count || 0;
+    const totalBytes = data.bytes || 0;
+    const shares = [];
+    for (const [sfxId, entry] of data.bySfx.entries()) {
+      shares.push({
+        sfxId,
+        count: entry.count,
+        bytes: entry.bytes,
+        priority: entry.priority ?? 1,
+        percentCount: total ? entry.count / total : 0,
+        percentBytes: totalBytes ? entry.bytes / totalBytes : 0
+      });
+    }
+    shares.sort((a, b) => b.count - a.count);
+    return shares;
+  },
+
+  estimateMessages(spec) {
+    if (!spec || !Number.isFinite(spec.note)) return { messages: 0, bytes: 0 };
+    let messages = 1;
+    if (this.config.mpe?.enabled) {
+      messages += 1;
+    } else if (spec.pitchBend != null && Number.isFinite(spec.pitchBend) && spec.pitchBend !== 0) {
+      messages += 1;
+    }
+    if (spec.timbre != null && Number.isFinite(spec.timbre)) messages += 1;
+    if (spec.pan != null && Number.isFinite(spec.pan)) messages += 1;
+    if (spec.durationTicks && spec.durationTicks > 0) {
+      messages += 1;
+      if (this.config.mpe?.enabled) messages += 1;
+    }
+    return { messages, bytes: messages * MIDI_MESSAGE_BYTES };
+  },
+
+  _recordPlanned(entry, now = this._nowMs()) {
+    if (!entry || !Number.isFinite(entry.timeMs)) return;
+    const count = Math.trunc(toFiniteNumber(entry.count, 0));
+    if (count <= 0) return;
+    const bytes = Math.trunc(toFiniteNumber(entry.bytes, count * MIDI_MESSAGE_BYTES));
+    if (bytes <= 0) return;
+    const normalized = { ...entry, count, bytes };
+    this._pruneRateEntries(now);
+    if (normalized.timeMs < now) {
+      this._rateSent.push(normalized);
+    } else {
+      this._ratePlanned.push(normalized);
+    }
+    this._trimRateEntries();
+  },
+
+  _recordSent(entry, now = this._nowMs()) {
+    if (!entry || !Number.isFinite(entry.timeMs)) return;
+    const count = Math.trunc(toFiniteNumber(entry.count, 0));
+    if (count <= 0) return;
+    const bytes = Math.trunc(toFiniteNumber(entry.bytes, count * MIDI_MESSAGE_BYTES));
+    if (bytes <= 0) return;
+    this._pruneRateEntries(now);
+    this._rateSent.push({ ...entry, count, bytes });
+    this._trimRateEntries();
+  },
+
+  _removePlannedRateEntries(token, phase = null) {
+    if (token == null || !this._ratePlanned.length) return;
+    let write = 0;
+    for (let read = 0; read < this._ratePlanned.length; read += 1) {
+      const entry = this._ratePlanned[read];
+      const remove = entry?.token === token && (phase == null || entry.phase === phase);
+      if (remove) continue;
+      this._ratePlanned[write] = entry;
+      write += 1;
+    }
+    this._ratePlanned.length = write;
+  },
+
+  _checkByteRate(now = this._nowMs()) {
+    const snapshot = this.getRateSnapshot(now);
+    const pastCount = toFiniteNumber(snapshot.past?.count, 0);
+    const nextCount = toFiniteNumber(snapshot.next?.count, 0);
+    const pastBytes = toFiniteNumber(snapshot.past?.bytes, 0);
+    const nextBytes = toFiniteNumber(snapshot.next?.bytes, 0);
+    const overMessageRate = pastCount > this._maxMessagesPerSecond || nextCount > this._maxMessagesPerSecond;
+    const overByteRate = pastBytes > this._maxBytesPerSecond || nextBytes > this._maxBytesPerSecond;
+    if (overMessageRate || overByteRate) {
+      if (now - this._lastRateErrorMs > 1000) {
+        this._lastRateErrorMs = now;
+        const limits = [];
+        if (overMessageRate) limits.push(`${this._maxMessagesPerSecond.toFixed(0)} messages/sec`);
+        if (overByteRate) limits.push(`${this._maxBytesPerSecond.toFixed(0)} bytes/sec`);
+        console.error(`MIDI throughput exceeded ${limits.join(' and ')}`);
+      }
+    }
+  },
+};
+
+export { midiSchedulerRateMethods };
diff --git a/js/midi/scheduler/MidiSchedulerSendMethods.js b/js/midi/scheduler/MidiSchedulerSendMethods.js
new file mode 100644
index 00000000..34fc7775
--- /dev/null
+++ b/js/midi/scheduler/MidiSchedulerSendMethods.js
@@ -0,0 +1,280 @@
+import { getAppContext } from '../../core/dependencies.js';
+import {
+  canMeasurePerformance,
+  recordPerformanceMeasure
+} from '../../util/performanceInstrumentation.js';
+import {
+  MAX_RATE_ENTRIES,
+  MIDI_BYTES_PER_SECOND,
+  MIDI_MESSAGE_BYTES,
+  clamp,
+  normalizeChannelNumber,
+  toFiniteNumber,
+  toPositiveInt
+} from './MidiSchedulerShared.js';
+
+const midiSchedulerSendMethods = {
+  sendNote(spec, meta = {}) {
+    const app = this.config?.runtime?.app || getAppContext();
+    const perfEnabled = !!app &&
+        (app.performanceAPI === true || app.perfMetrics === true) &&
+        canMeasurePerformance();
+    const perfStart = perfEnabled ? performance.now() : 0;
+    try {
+      if (!spec || !Number.isFinite(spec.note)) return false;
+      const outputId = this._resolveOutputId?.(spec.outputId) ?? null;
+      const output = this._resolveOutput ? this._resolveOutput(outputId) : this.output;
+      if (!output) return false;
+      const channelNumber = this.config.mpe?.enabled
+        ? this._allocateChannel(outputId)
+        : normalizeChannelNumber(spec.channel ?? this.config.defaultChannel, 1);
+      const channel = output.channels?.[channelNumber];
+      if (!channel) return false;
+
+      const sendTimeMs = Number.isFinite(spec.timeMs) ? spec.timeMs : this._nowMs();
+      const durationMs = Number.isFinite(spec.durationTicks)
+        ? Math.max(0, spec.durationTicks * this.tickMs)
+        : 0;
+      const offTimeMs = sendTimeMs + durationMs;
+      const baseVelocity = clamp(spec.velocity ?? 64, 1, 127);
+      const baseRelease = clamp(spec.releaseVelocity ?? baseVelocity, 1, 127);
+      const reverse = !!spec.reverse;
+      const attackVelocity = reverse ? baseRelease : baseVelocity;
+      const releaseVelocity = reverse ? baseVelocity : baseRelease;
+      const timbreCc = this.config.mpe?.timbreCc ?? 74;
+      const trackId = this._normalizeTrackId?.(spec.trackId) ?? null;
+      const voiceBudget = trackId && spec.voiceBudget != null
+        ? clamp(toPositiveInt(spec.voiceBudget, this._maxActiveNotes), 1, this._maxActiveNotes)
+        : null;
+
+      if (this.config.mpe?.enabled) {
+        if (Number.isFinite(spec.pitchBend) && spec.pitchBend !== 0) {
+          channel.sendPitchBend(clamp(spec.pitchBend, -1, 1), { time: sendTimeMs });
+        } else {
+          channel.sendPitchBend(0, { time: sendTimeMs });
+        }
+        if (spec.timbre != null && Number.isFinite(spec.timbre)) {
+          channel.sendControlChange(timbreCc, clamp(spec.timbre, 0, 127), { time: sendTimeMs });
+        }
+      }
+      if (spec.pan != null && Number.isFinite(spec.pan)) {
+        const panRange = this.config.position?.panRange;
+        const signedPan = (panRange?.min ?? 0) < 0;
+        let panValue = spec.pan;
+        if (signedPan) {
+          panValue = Math.round((clamp(panValue, -127, 127) + 127) / 2);
+        }
+        channel.sendControlChange(10, clamp(panValue, 0, 127), { time: sendTimeMs });
+      }
+
+      const startedAt = sendTimeMs;
+      const token = ++this._noteOffSeq;
+      if (
+        trackId &&
+          voiceBudget != null &&
+          this._countActiveNotesForTrack?.(trackId) >= voiceBudget
+      ) {
+        this._stealOldestNoteForTrack(trackId);
+      }
+      if (this._activeNotes.size >= this._maxActiveNotes) {
+        this._stealOldestNote();
+      }
+
+      channel.sendNoteOn(spec.note, { rawAttack: attackVelocity, time: sendTimeMs });
+      if (typeof window !== 'undefined') {
+        window.lastMidiOutputMessage = {
+          type: 'noteOn',
+          note: spec.note,
+          velocity: attackVelocity,
+          channel: channelNumber,
+          outputId,
+          timeMs: sendTimeMs
+        };
+      }
+
+      this._activeNotes.set(token, {
+        channel: channelNumber,
+        note: spec.note,
+        startedAt,
+        token,
+        trackId,
+        voiceBudget,
+        outputId,
+        mpe: !!this.config.mpe?.enabled
+      });
+      if (this.config.mpe?.enabled) {
+        this._activeByChannel.set(this._activeChannelKey(channelNumber, outputId), {
+          channel: channelNumber,
+          note: spec.note,
+          outputId,
+          startedAt,
+          token
+        });
+      }
+      if (durationMs > 0) {
+        channel.sendNoteOff(spec.note, { rawRelease: releaseVelocity, time: offTimeMs });
+        if (this.config.mpe?.enabled) {
+          channel.sendPitchBend(0, { time: offTimeMs });
+        }
+        this._scheduleNoteOff({
+          timeMs: offTimeMs,
+          channel: channelNumber,
+          note: spec.note,
+          outputId,
+          token,
+          mpe: !!this.config.mpe?.enabled
+        });
+      }
+      const { messages, bytes } = this.estimateMessages(spec);
+      if (messages > 0 && meta.rateReserved !== true) {
+        const offMessages = durationMs > 0 ? (1 + (this.config.mpe?.enabled ? 1 : 0)) : 0;
+        const immediateMessages = messages - offMessages;
+        const immediateBytes = bytes - (offMessages * MIDI_MESSAGE_BYTES);
+        this._recordPlanned({
+          timeMs: sendTimeMs,
+          count: immediateMessages,
+          bytes: immediateBytes,
+          token,
+          phase: 'on',
+          sfxId: meta.sfxId ?? null,
+          priority: meta.priority ?? 1,
+          triggerType: meta.triggerType ?? null,
+          trackId,
+          outputId,
+          voiceBudget
+        });
+        if (durationMs > 0) {
+          this._recordPlanned({
+            timeMs: offTimeMs,
+            count: offMessages,
+            bytes: offMessages * MIDI_MESSAGE_BYTES,
+            token,
+            phase: 'off',
+            sfxId: meta.sfxId ?? null,
+            priority: meta.priority ?? 1,
+            triggerType: meta.triggerType ?? null,
+            trackId,
+            outputId,
+            voiceBudget
+          });
+        }
+      }
+      this._checkByteRate(sendTimeMs);
+      return true;
+    } finally {
+      if (perfEnabled) {
+        recordPerformanceMeasure('MidiScheduler sendNote', {
+          start: perfStart,
+          detail: { devtools: { track: 'MidiScheduler', trackGroup: 'MIDI', color: 'secondary', tooltipText: 'sendNote' } }
+        });
+      }
+    }
+  },
+
+  _scheduleNoteOff(entry) {
+    const list = this._noteOffs;
+    list.push(entry);
+    let i = list.length - 1;
+    while (i > 0 && list[i - 1].timeMs > entry.timeMs) {
+      list[i] = list[i - 1];
+      i--;
+    }
+    list[i] = entry;
+    if (i === 0) this._armNoteOffTimer();
+  },
+
+  _armNoteOffTimer() {
+    if (this._noteOffTimerId) {
+      clearTimeout(this._noteOffTimerId);
+      this._noteOffTimerId = 0;
+    }
+    if (!this._noteOffs.length) return;
+    const now = typeof performance !== 'undefined' ? performance.now() : Date.now();
+    const delay = Math.max(0, this._noteOffs[0].timeMs - now);
+    this._noteOffTimerId = setTimeout(() => this._processNoteOffs(), delay);
+  },
+
+  _processNoteOffs() {
+    this._noteOffTimerId = 0;
+    if (!this.hasAnyOutput() || !this._noteOffs.length) return;
+    const now = typeof performance !== 'undefined' ? performance.now() : Date.now();
+    let idx = 0;
+    while (idx < this._noteOffs.length && this._noteOffs[idx].timeMs <= now + 1) {
+      const entry = this._noteOffs[idx];
+      const active = this._activeNotes.get(entry.token);
+      if (active && entry.mpe) {
+        this._activeByChannel.delete(this._activeChannelKey(entry.channel, active.outputId ?? entry.outputId));
+      }
+      if (active) this._activeNotes.delete(entry.token);
+      idx++;
+    }
+    if (idx > 0) {
+      this._noteOffs.splice(0, idx);
+    }
+    this._armNoteOffTimer();
+  },
+
+  allNotesOff() {
+    if (!this.hasAnyOutput()) return;
+    const mpe = this.config.mpe;
+    let channels;
+    if (mpe?.enabled) {
+      const master = normalizeChannelNumber(mpe.masterChannel, 1);
+      const members = (Array.isArray(mpe.memberChannels) ? mpe.memberChannels : [])
+        .map((channel) => normalizeChannelNumber(channel))
+        .filter((channel, index, list) => channel !== master && list.indexOf(channel) === index);
+      channels = [master, ...members];
+    } else {
+      channels = [normalizeChannelNumber(this.config.defaultChannel, 1)];
+    }
+    for (const output of this._listOutputs()) {
+      for (const ch of channels) {
+        const channel = output.channels?.[ch];
+        if (!channel) continue;
+        channel.sendAllNotesOff?.();
+        channel.sendPitchBend?.(0);
+      }
+    }
+    this._noteOffs.length = 0;
+    if (this._noteOffTimerId) {
+      clearTimeout(this._noteOffTimerId);
+      this._noteOffTimerId = 0;
+    }
+    this._activeByChannel.clear();
+    this._activeNotes.clear();
+    this._noteOffs.length = 0;
+    this._rateSent.length = 0;
+    this._ratePlanned.length = 0;
+  },
+
+  clearQueue() {
+    this._noteOffs.length = 0;
+    if (this._noteOffTimerId) {
+      clearTimeout(this._noteOffTimerId);
+      this._noteOffTimerId = 0;
+    }
+    this._activeByChannel.clear();
+    this._activeNotes.clear();
+    this._rateSent.length = 0;
+    this._ratePlanned.length = 0;
+  },
+
+  dispose() {
+    for (const [ch, active] of this._activeByChannel.entries()) {
+      this._stopActiveChannel(active?.channel ?? ch, active?.outputId ?? null);
+    }
+    this._activeByChannel.clear();
+    this._activeNotes.clear();
+    this._noteOffs.length = 0;
+    this._rateSent.length = 0;
+    this._ratePlanned.length = 0;
+    if (this._noteOffTimerId) {
+      clearTimeout(this._noteOffTimerId);
+      this._noteOffTimerId = 0;
+    }
+    this.output = null;
+    this._outputsById.clear();
+  },
+};
+
+export { midiSchedulerSendMethods };
diff --git a/js/midi/scheduler/MidiSchedulerShared.js b/js/midi/scheduler/MidiSchedulerShared.js
new file mode 100644
index 00000000..f182c610
--- /dev/null
+++ b/js/midi/scheduler/MidiSchedulerShared.js
@@ -0,0 +1,27 @@
+const clamp = (value, min, max) => Math.max(min, Math.min(max, value));
+const MIDI_BITS_PER_SECOND = 31250;
+const MIDI_BYTES_PER_SECOND = MIDI_BITS_PER_SECOND / 8;
+const MIDI_MESSAGE_BYTES = 3;
+const MAX_RATE_ENTRIES = 4096;
+const toFiniteNumber = (value, fallback) => {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : fallback;
+};
+const toPositiveInt = (value, fallback) => {
+  const numeric = Math.trunc(toFiniteNumber(value, fallback));
+  return numeric > 0 ? numeric : fallback;
+};
+const normalizeChannelNumber = (value, fallback = 1) => {
+  const numeric = Math.trunc(toFiniteNumber(value, fallback));
+  return clamp(numeric, 1, 16);
+};
+
+export {
+  MIDI_BYTES_PER_SECOND,
+  MIDI_MESSAGE_BYTES,
+  MAX_RATE_ENTRIES,
+  clamp,
+  normalizeChannelNumber,
+  toFiniteNumber,
+  toPositiveInt
+};
diff --git a/js/render/DisplayImage.js b/js/render/DisplayImage.js
index 548cfcf0..48210baa 100644
--- a/js/render/DisplayImage.js
+++ b/js/render/DisplayImage.js
@@ -1,746 +1,9 @@
-/* -------------------- DisplayImage.js -------------------- */
-import { BaseLogger } from '../util/LogHandler.js';
-import { EventHandler } from '../util/EventHandler.js';
-import { scaleImage } from '../xbrz/xbrz.js';
-import { hqxScale, initHqx } from '../vendor/hqx/index.js';
-initHqx();
-
-// a simple but high quality 53-bit hash
-const cyrb53 = (str, seed = 0) => {
-  let h1 = 0xdeadbeef ^ seed, h2 = 0x41c6ce57 ^ seed;
-  for(let i = 0, ch; i < str.length; i++) {
-    ch = str.charCodeAt(i);
-    h1 = Math.imul(h1 ^ ch, 2654435761);
-    h2 = Math.imul(h2 ^ ch, 1597334677);
-  }
-  h1  = Math.imul(h1 ^ (h1 >>> 16), 2246822507);
-  h1 ^= Math.imul(h2 ^ (h2 >>> 13), 3266489909);
-  h2  = Math.imul(h2 ^ (h2 >>> 16), 2246822507);
-  h2 ^= Math.imul(h1 ^ (h1 >>> 13), 3266489909);
-  
-  return 4294967296 * (2097151 & h2) + (h1 >>> 0);
-};
-
-class DisplayImage extends BaseLogger {
-  constructor(stage) {
-    super();
-    this.stage = stage;
-    this.onMouseUp = new EventHandler();
-    this.onMouseDown = new EventHandler();
-    this.onMouseRightDown = new EventHandler();
-    this.onMouseRightUp = new EventHandler();
-    this.onMouseMove = new EventHandler();
-    this.onDoubleClick = new EventHandler();
-    // 32‑bit view reused everywhere; set by initSize()
-    this.buffer32 = null;
-    // this.onMouseDown.on(e => {
-    //     // this.setDebugPixel(e.x, e.y);
-    // });
-    this.imgData = null;
-  }
-
-  /* ---------- image helpers ---------- */
-  getWidth()  { return this.imgData?.width  ?? 0; }
-  getHeight() { return this.imgData?.height ?? 0; }
-
-  /** Size of the ImageData backing this DisplayImage. */
-  get worldDataSize() {
-    return { width: this.getWidth(), height: this.getHeight() };
-  }
-
-  set worldDataSize({ width, height }) {
-    this.initSize(width, height);
-  }
-
-  /** (Re)allocate the backing ImageData + uint32 view. */
-  initSize(width, height) {
-    if (!this.imgData || this.imgData.width !== width || this.imgData.height !== height) {
-      this.imgData  = this.stage.createImage(this, width, height);
-      // Single 32‑bit view that aliases the same buffer – no copying.
-      this.buffer32 = new Uint32Array(this.imgData.data.buffer);
-      this.clear();
-    }
-  }
-
-  /** Fast clear using .fill() on the uint32 view (default: ARGB 0xFF00FF00). */
-  clear(color = 0xFF00FF00) {
-    this.buffer32?.fill(color);
-  }
-
-  /** Bulk background copy – copy 32‑bit words where possible. */
-  setBackground(groundImage, groundMask = null) {
-    if (groundImage instanceof Uint8ClampedArray) {
-      // Uint8 – copy bytes directly.
-      this.imgData.data.set(groundImage);
-    } else if (groundImage instanceof Uint32Array) {
-      // Faster 32‑bit path.
-      this.buffer32.set(groundImage);
-    } else {
-      // Fallback (ArrayLike)
-      this.log.log('error: setBackground fallback');
-      // this.imgData.data.set(groundImage);
-    }
-    this.groundMask = groundMask;
-  }
-    
-  /* ---------- primitive drawing ---------- */
-  /** Draw rectangle outline */
-  drawRect(x, y, width, height, r, g, b, filled = false) {
-    const x2 = x + width;
-    const y2 = y + height;
-    this.drawHorizontalLine(x, y,  x2, r, g, b);
-
-    if (filled) {
-      for (let i = y; i <= y+height; i++) {
-        this.drawHorizontalLine(x, i, x2, r, g, b);
-      }
-    }
-
-    this.drawHorizontalLine(x, y2, x2, r, g, b);
-    this.drawVerticalLine(  x,  y,  y2, r, g, b);
-    this.drawVerticalLine( x2,  y,  y2, r, g, b);
-  }
-
-  /** Vertical 1‑px line (uses uint32 writes) */
-  drawVerticalLine(x, y1, y2, r, g, b) {
-    if (!this.buffer32) return;
-    const { width: w, height: h } = this.imgData;
-    x  = Math.min(Math.max(x,  0), w - 1);
-    y1 = Math.min(Math.max(y1, 0), h - 1);
-    y2 = Math.min(Math.max(y2, 0), h - 1);
-    if (y2 < y1) [y1, y2] = [y2, y1];
-    const color32 = 0xFF000000 | (b & 0xFF) << 16 | (g & 0xFF) << 8 | (r & 0xFF);
-    let idx = y1 * w + x;
-    for (let y = y1; y <= y2; y++, idx += w) this.buffer32[idx] = color32;
-  }
-
-  /** Horizontal 1‑px line (uint32 writes) */
-  drawHorizontalLine(x1, y, x2, r, g, b) {
-    if (!this.buffer32) return;
-    const { width: w, height: h } = this.imgData;
-    y  = Math.min(Math.max(y,  0), h - 1);
-    x1 = Math.min(Math.max(x1, 0), w - 1);
-    x2 = Math.min(Math.max(x2, 0), w - 1);
-    if (x2 < x1) [x1, x2] = [x2, x1];
-    const color32 = 0xFF000000 | (b & 0xFF) << 16 | (g & 0xFF) << 8 | (r & 0xFF);
-    let idx = y * w + x1;
-    for (let x = x1; x <= x2; x++, idx++) this.buffer32[idx] = color32;
-  }
-
-  /**
-     * Draw rectangle outline using a "marching ants" effect.
-     * @param {number} x      Top left x position
-     * @param {number} y      Top left y position
-     * @param {number} width  Rectangle width
-     * @param {number} height Rectangle height
-     * @param {number} dashLen Length of each dash segment (in pixels)
-     * @param {number} offset  Offset of the dash pattern
-     */
-  drawMarchingAntRect(
-    x,
-    y,
-    width,
-    height,
-    dashLen = 3,
-    offset = 0,
-    color1 = 0xFFFFFFFF,
-    color2 = 0xFF000000
-  ) {
-    drawMarchingAntRect(
-      this,
-      x,
-      y,
-      width,
-      height,
-      dashLen,
-      offset,
-      color1,
-      color2
-    );
-  }
-
-  /** Draw rectangle outline with a dashed pattern. */
-  drawDashedRect(
-    x,
-    y,
-    width,
-    height,
-    dashLenOrR = 3,
-    offsetOrG = 0,
-    color1OrB = 0xFFFFFFFF,
-    color2OrDashLen = 0xFF000000
-  ) {
-    const isRgbSignature = arguments.length >= 7 &&
-      Number.isFinite(dashLenOrR) &&
-      Number.isFinite(offsetOrG) &&
-      Number.isFinite(color1OrB) &&
-      dashLenOrR >= 0 && dashLenOrR <= 255 &&
-      offsetOrG >= 0 && offsetOrG <= 255 &&
-      color1OrB >= 0 && color1OrB <= 255;
-
-    if (isRgbSignature) {
-      const r = dashLenOrR;
-      const g = offsetOrG;
-      const b = color1OrB;
-      const dashLen = Number.isFinite(color2OrDashLen) ? color2OrDashLen : 2;
-      const color = 0xFF000000 | (b & 0xFF) << 16 | (g & 0xFF) << 8 | (r & 0xFF);
-      drawDashedRect(
-        this,
-        x,
-        y,
-        width,
-        height,
-        dashLen,
-        0,
-        color,
-        0x00000000
-      );
-      return;
-    }
-
-    drawDashedRect(
-      this,
-      x,
-      y,
-      width,
-      height,
-      dashLenOrR,
-      offsetOrG,
-      color1OrB,
-      color2OrDashLen
-    );
-  }
-
-  /** Draw a stippled rectangle fill (simple checkerboard pattern). */
-  drawStippleRect(x, y, width, height, r = 128, g = 128, b = 128) {
-    if (!this.buffer32) return;
-    const { width: w } = this.imgData;
-    const color32 = 0xFF000000 | (b & 0xFF) << 16 | (g & 0xFF) << 8 | (r & 0xFF);
-    for (let dy = 0; dy <= height; dy++) {
-      let idx = (y + dy) * w + x;
-      for (let dx = 0; dx <= width; dx++, idx++) {
-        if (((dx + dy) & 1) === 0) this.buffer32[idx] = color32;
-      }
-    }
-  }
-
-  /**
-     * Draw L‑shaped corners around a rectangle.
-     * @param {number} x        Top-left x position
-     * @param {number} y        Top-left y position
-     * @param {number|Object} size  Width/height or { width, height }
-     * @param {number} r        Red component
-     * @param {number} g        Green component
-     * @param {number} b        Blue component
-     * @param {number} length   Length of the corner arms
-     * @param {boolean} midLine Draw centered lines on each edge
-     * @param {number} midLen   Length of the centered lines
-     */
-  drawCornerRect(x, y, size, r, g, b, length = 1, midLine = false, midLen = 0) {
-    const w = typeof size === 'object' ? size.width : size;
-    const h = typeof size === 'object' ? size.height : size;
-    const x2 = x + w - 1;
-    const y2 = y + h - 1;
-
-    const len = Math.max(1, length);
-
-    // top-left
-    this.drawHorizontalLine(x, y, Math.min(x + len, x2), r, g, b);
-    this.drawVerticalLine(x, y, Math.min(y + len, y2), r, g, b);
-    // top-right
-    this.drawHorizontalLine(Math.max(x2 - len, x), y, x2, r, g, b);
-    this.drawVerticalLine(x2, y, Math.min(y + len, y2), r, g, b);
-    // bottom-left
-    this.drawHorizontalLine(x, y2, Math.min(x + len, x2), r, g, b);
-    this.drawVerticalLine(x, Math.max(y2 - len, y), y2, r, g, b);
-    // bottom-right
-    this.drawHorizontalLine(Math.max(x2 - len, x), y2, x2, r, g, b);
-    this.drawVerticalLine(x2, Math.max(y2 - len, y), y2, r, g, b);
-
-    if (midLine && midLen > 0) {
-      const hx1 = Math.max(x + Math.floor((w - midLen) / 2), x);
-      const hx2 = Math.min(hx1 + midLen - 1, x2);
-      const hy1 = Math.max(y + Math.floor((h - midLen) / 2), y);
-      const hy2 = Math.min(hy1 + midLen - 1, y2);
-      this.drawHorizontalLine(hx1, y, hx2, r, g, b);
-      this.drawHorizontalLine(hx1, y2, hx2, r, g, b);
-      this.drawVerticalLine(x, hy1, hy2, r, g, b);
-      this.drawVerticalLine(x2, hy1, hy2, r, g, b);
-    }
-  }
-
-  /* ---------- blitting helpers ---------- */
-  /** Write sprite mask (white) */
-  drawMask(mask, posX, posY) {
-    if (!this.buffer32) return;
-    const srcW = mask.width, srcH = mask.height,
-      srcMask = mask.getMask(),
-      destW = this.imgData.width, destH = this.imgData.height,
-      baseX = posX + mask.offsetX, baseY = posY + mask.offsetY,
-      WHITE = 0xFFFFFFFF;
-    for (let srcY = 0; srcY < srcH; srcY++) {
-      const outY = srcY + baseY;
-      if (outY < 0 || outY >= destH) continue;
-      let srcRow = srcY * srcW, destRow = outY * destW + baseX;
-      for (let srcX = 0; srcX < srcW; srcX++, srcRow++, destRow++) {
-        if (!srcMask[srcRow]) continue;
-        const outX = srcX + baseX;
-        if (outX < 0 || outX >= destW) continue; // x‑clip
-        this.buffer32[destRow] = WHITE;
-      }
-    }
-  }
-
-  /**
-     * Generic blitter helper used by drawFrame & drawFrameCovered
-     * Now accepts optional `size: {width, height}` in opts to scale the sprite.
-     * Scaling uses nearest‑neighbour for speed.
-     */
-  _blit(frame, posX, posY, opts) {
-    const { width: srcW, height: srcH } = frame,
-      srcBuf  = frame.getBuffer(),
-      srcMask = frame.getMask(),
-      destW   = this.imgData.width, destH = this.imgData.height,
-      baseX   = posX + frame.offsetX, baseY = posY + frame.offsetY,
-      dest32  = this.buffer32;
-
-    const {
-      nullColor32   = null,
-      checkGround   = false,
-      onlyOverwrite = false,
-      noOverwrite   = false,
-      upsideDown    = false,
-      groundMask    = null,
-      size          = null, // { width, height }
-      scaleMode     = 'nearest'
-    } = opts ?? {};
-
-    // If no scaling requested or size matches source → fall back to original fast path
-    const dstW = size?.width  ?? srcW;
-    const dstH = size?.height ?? srcH;
-    const isScaled = (dstW !== srcW) || (dstH !== srcH);
-
-    if (!isScaled) {
-      const spanCache = frame.getSpanCache?.();
-      if (spanCache && nullColor32 === null) {
-        const { rows, bounds } = spanCache;
-        const minY = bounds ? bounds.minY : 0;
-        const maxY = bounds ? bounds.maxY : -1;
-        for (let sy = 0; sy < srcH; sy++) {
-          const sourceY = upsideDown ? srcH - sy - 1 : sy;
-          if (sourceY < minY || sourceY > maxY) continue;
-          const spans = rows[sourceY];
-          if (!spans) continue;
-          const outY = sy + baseY;
-          if (outY < 0 || outY >= destH) continue;
-          const srcRow = sourceY * srcW;
-          const destRow = outY * destW + baseX;
-          for (let i = 0; i < spans.length; i += 2) {
-            let start = spans[i];
-            let end = spans[i + 1];
-            if (baseX + start < 0) start = -baseX;
-            if (baseX + end > destW) end = destW - baseX;
-            if (end <= start) continue;
-            let srcIdx = srcRow + start;
-            let destIdx = destRow + start;
-            if (!checkGround) {
-              for (let sx = start; sx < end; sx++, srcIdx++, destIdx++) {
-                dest32[destIdx] = srcBuf[srcIdx];
-              }
-            } else {
-              for (let sx = start; sx < end; sx++, srcIdx++, destIdx++) {
-                const outX = baseX + sx;
-                const hasGround = groundMask?.hasGroundAt(outX, outY);
-                if (noOverwrite && hasGround)    continue;
-                if (onlyOverwrite && !hasGround) continue;
-                dest32[destIdx] = srcBuf[srcIdx];
-              }
-            }
-          }
-        }
-        return;
-      }
-
-      for (let sy = 0; sy < srcH; sy++) {
-        const sourceY = upsideDown ? srcH - sy - 1 : sy;
-        const outY = sy + baseY;
-        if (outY < 0 || outY >= destH) continue;
-        let srcRow  = sourceY * srcW;
-        let destRow = outY * destW + baseX;
-        for (let sx = 0; sx < srcW; sx++, srcRow++, destRow++) {
-          if (!srcMask[srcRow]) {
-            if (nullColor32 !== null) dest32[destRow] = nullColor32; // covered variant
-            continue;
-          }
-          const outX = sx + baseX;
-          if (outX < 0 || outX >= destW) continue;
-          if (checkGround) {
-            const hasGround = groundMask?.hasGroundAt(outX, outY);
-            if (noOverwrite && hasGround)    continue;
-            if (onlyOverwrite && !hasGround) continue;
-          }
-          dest32[destRow] = srcBuf[srcRow];
-        }
-      }
-      return;
-    }
-
-    // Scaled path – choose algorithm
-    const scaleOpts = {
-      dest32,
-      destW,
-      destH,
-      baseX,
-      baseY,
-      nullColor32,
-      checkGround,
-      onlyOverwrite,
-      noOverwrite,
-      upsideDown,
-      groundMask
-    };
-
-    if (scaleMode === 'xbrz') {
-      scaleXbrz(frame, dstW, dstH, scaleOpts);
-    } else if (scaleMode === 'hqx') {
-      scaleHqx(frame, dstW, dstH, scaleOpts);
-    } else {
-      scaleNearest(frame, dstW, dstH, scaleOpts);
-    }
-  }
-
-  drawFrame(frame, x, y,) {
-    this._blit(frame, x, y);
-  }
-
-  drawFrameCovered(frame, x, y, r, g, b) {
-    const nullColor32 = 0xFF000000 | (b & 0xFF) << 16 | (g & 0xFF) << 8 | (r & 0xFF);
-    this._blit(frame, x, y, { nullColor32 });
-  }
-
-  drawFrameFlags(frame, x, y, cfg) {
-    this._blit(frame, x, y, {
-      checkGround:   true,
-      onlyOverwrite: cfg.onlyOverwrite,
-      noOverwrite:   cfg.noOverwrite,
-      upsideDown:    cfg.isUpsideDown,
-      groundMask:    this.groundMask
-    });
-  }
-  drawFrameResized(frame, x, y, w, h) {
-    this._blit(frame, x, y, {
-      size: {width: w, height: h}
-    });
-  }
-
-  /* ---------- misc utilities ---------- */
-  setDebugPixel(x, y) { if (this.buffer32) this.buffer32[y * this.imgData.width + x] = 0xFF0000FF; }
-
-  setPixel(x,y,r,g,b) {
-    if (!this.buffer32) return;
-    this.buffer32[y * this.imgData.width + x] = 0xFF000000 | (b&0xFF)<<16 | (g&0xFF)<<8 | (r&0xFF);
-  }
-
-  setScreenPosition(x, y, options) {
-    this.stage.setGameViewPointPosition(x, y, options);
-  }
-  getImageData()         { return this.imgData;  }
-  redraw()               { this.stage.redraw();   }
-
-  dispose() {
-    this.onMouseUp.dispose();
-    this.onMouseDown.dispose();
-    this.onMouseRightDown.dispose();
-    this.onMouseRightUp.dispose();
-    this.onMouseMove.dispose();
-    this.onDoubleClick.dispose();
-    this.buffer32 = null;
-    this.imgData = null;
-    this.stage = null;
-  }
-}
-
-function scaleNearest(
-  frame,
-  dstWidth,
-  dstHeight,
-  opts = {}
-) {
-  const {
-    dest32,
-    destW,
-    destH,
-    baseX,
-    baseY,
-    nullColor32 = null,
-    checkGround = false,
-    onlyOverwrite = false,
-    noOverwrite = false,
-    upsideDown = false,
-    groundMask = null
-  } = opts;
-
-  if (!dest32) return;
-
-  const { width: srcW, height: srcH } = frame;
-  const srcBuf = frame.getBuffer();
-  const srcMask = frame.getMask();
-
-  const scaleX = srcW / dstWidth;
-  const scaleY = srcH / dstHeight;
-
-  for (let dy = 0; dy < dstHeight; dy++) {
-    let srcY = Math.floor(dy * scaleY);
-    if (upsideDown) srcY = srcH - 1 - srcY;
-    const outY = dy + baseY;
-    if (outY < 0 || outY >= destH) continue;
-
-    const srcYBase = srcY * srcW;
-    const destYBase = outY * destW;
-
-    for (let dx = 0; dx < dstWidth; dx++) {
-      const outX = dx + baseX;
-      if (outX < 0 || outX >= destW) continue;
-
-      const srcX = Math.floor(dx * scaleX);
-      const srcIdx = srcYBase + srcX;
-      const destIdx = destYBase + outX;
-
-      if (!srcMask[srcIdx]) {
-        if (nullColor32 !== null) dest32[destIdx] = nullColor32;
-        continue;
-      }
-
-      if (checkGround) {
-        const hasGround = groundMask?.hasGroundAt(outX, outY);
-        if (noOverwrite && hasGround) continue;
-        if (onlyOverwrite && !hasGround) continue;
-      }
-
-      dest32[destIdx] = srcBuf[srcIdx];
-    }
-  }
-}
-
-function scaleXbrz(
-  frame,
-  dstWidth,
-  dstHeight,
-  opts = {}
-) {
-  const {
-    dest32,
-    destW,
-    destH,
-    baseX,
-    baseY,
-    nullColor32 = null,
-    checkGround = false,
-    onlyOverwrite = false,
-    noOverwrite = false,
-    upsideDown = false,
-    groundMask = null
-  } = opts;
-
-  if (!dest32) return;
-
-  const { width: srcW, height: srcH } = frame;
-  const scale = Math.round(dstWidth / srcW);
-  if (scale < 2 || scale > 4 || dstWidth !== srcW * scale || dstHeight !== srcH * scale) {
-    scaleNearest(frame, dstWidth, dstHeight, opts);
-    return;
-  }
-
-  const srcBuf = frame.getBuffer();
-  const srcMask = frame.getMask();
-  const temp = new Uint32Array(srcBuf.length);
-  for (let i = 0; i < srcBuf.length; i++) {
-    temp[i] = srcMask[i] ? srcBuf[i] : 0;
-  }
-
-  const scaled = new Uint32Array(dstWidth * dstHeight);
-  scaleImage(scale, temp, scaled, srcW, srcH, 0, srcH);
-
-  const scaledMask = new Uint8Array(dstWidth * dstHeight);
-  for (let dy = 0; dy < dstHeight; dy++) {
-    const sy = Math.floor(dy / scale);
-    const srcRow = sy * srcW;
-    const dstRow = dy * dstWidth;
-    for (let dx = 0; dx < dstWidth; dx++) {
-      const sx = Math.floor(dx / scale);
-      scaledMask[dstRow + dx] = srcMask[srcRow + sx];
-    }
-  }
-
-  for (let dy = 0; dy < dstHeight; dy++) {
-    const srcY = upsideDown ? dstHeight - 1 - dy : dy;
-    const outY = dy + baseY;
-    if (outY < 0 || outY >= destH) continue;
-
-    let srcRow = srcY * dstWidth;
-    let destRow = outY * destW + baseX;
-
-    for (let dx = 0; dx < dstWidth; dx++, srcRow++, destRow++) {
-      const outX = dx + baseX;
-      if (outX < 0 || outX >= destW) continue;
-
-      if (!scaledMask[srcRow]) {
-        if (nullColor32 !== null) dest32[destRow] = nullColor32;
-        continue;
-      }
-
-      if (checkGround) {
-        const hasGround = groundMask?.hasGroundAt(outX, outY);
-        if (noOverwrite && hasGround) continue;
-        if (onlyOverwrite && !hasGround) continue;
-      }
-
-      dest32[destRow] = scaled[srcRow];
-    }
-  }
-}
-
-function scaleHqx(
-  frame,
-  dstWidth,
-  dstHeight,
-  opts = {}
-) {
-  const {
-    dest32,
-    destW,
-    destH,
-    baseX,
-    baseY,
-    nullColor32 = null,
-    checkGround = false,
-    onlyOverwrite = false,
-    noOverwrite = false,
-    upsideDown = false,
-    groundMask = null
-  } = opts;
-
-  if (!dest32) return;
-
-  const { width: srcW, height: srcH } = frame;
-  const scale = Math.round(dstWidth / srcW);
-  if (scale < 2 || scale > 4 || dstWidth !== srcW * scale || dstHeight !== srcH * scale) {
-    scaleNearest(frame, dstWidth, dstHeight, opts);
-    return;
-  }
-
-  const srcBuf = frame.getBuffer();
-  const srcMask = frame.getMask();
-  const temp = new Uint32Array(srcBuf.length);
-  for (let i = 0; i < srcBuf.length; i++) {
-    temp[i] = srcMask[i] ? srcBuf[i] : 0;
-  }
-
-  const scaled = hqxScale(temp, srcW, srcH, scale);
-
-  const scaledMask = new Uint8Array(dstWidth * dstHeight);
-  for (let dy = 0; dy < dstHeight; dy++) {
-    const sy = Math.floor(dy / scale);
-    const srcRow = sy * srcW;
-    const dstRow = dy * dstWidth;
-    for (let dx = 0; dx < dstWidth; dx++) {
-      const sx = Math.floor(dx / scale);
-      scaledMask[dstRow + dx] = srcMask[srcRow + sx];
-    }
-  }
-
-  for (let dy = 0; dy < dstHeight; dy++) {
-    const srcY = upsideDown ? dstHeight - 1 - dy : dy;
-    const outY = dy + baseY;
-    if (outY < 0 || outY >= destH) continue;
-
-    let srcRow = srcY * dstWidth;
-    let destRow = outY * destW + baseX;
-
-    for (let dx = 0; dx < dstWidth; dx++, srcRow++, destRow++) {
-      const outX = dx + baseX;
-      if (outX < 0 || outX >= destW) continue;
-
-      if (!scaledMask[srcRow]) {
-        if (nullColor32 !== null) dest32[destRow] = nullColor32;
-        continue;
-      }
-
-      if (checkGround) {
-        const hasGround = groundMask?.hasGroundAt(outX, outY);
-        if (noOverwrite && hasGround) continue;
-        if (onlyOverwrite && !hasGround) continue;
-      }
-
-      dest32[destRow] = scaled[srcRow];
-    }
-  }
-}
-
-function drawMarchingAntRect(
-  display,
-  x,
-  y,
-  width,
-  height,
-  dashLen = 3,
-  offset = 0,
-  color1 = 0xFFFFFFFF,
-  color2 = 0xFF000000
-) {
-  if (!display?.buffer32) return;
-  const { width: w } = display.imgData;
-  const pattern = dashLen * 2;
-  let pos = ((offset % pattern) + pattern) % pattern;
-  const set = (px, py) => {
-    const useFirst = Math.floor(pos / dashLen) % 2 === 0;
-    const color = useFirst ? color1 : color2;
-    if ((color >>> 24) !== 0) {
-      display.buffer32[py * w + px] = color;
-    }
-    pos = (pos + 1) % pattern;
-  };
-
-  for (let dx = 0; dx <= width; dx++) set(x + dx, y);
-  for (let dy = 1; dy <= height; dy++) set(x + width, y + dy);
-  for (let dx = 1; dx <= width; dx++) set(x + width - dx, y + height);
-  for (let dy = 1; dy < height; dy++) set(x, y + height - dy);
-}
-
-function drawDashedRect(
-  display,
-  x,
-  y,
-  width,
-  height,
-  dashLen = 3,
-  offset = 0,
-  color1 = 0xFFFFFFFF,
-  color2 = 0xFF000000
-) {
-  drawMarchingAntRect(
-    display,
-    x,
-    y,
-    width,
-    height,
-    dashLen,
-    offset,
-    color1,
-    color2
-  );
-}
-
-const __test__ = {
-  cyrb53
-};
-
+export { DisplayImage } from './display/DisplayImageCore.js';
 export {
-  DisplayImage,
   drawMarchingAntRect,
   drawDashedRect,
   scaleNearest,
   scaleXbrz,
   scaleHqx,
   __test__
-};
+} from './display/DisplayImageShared.js';
diff --git a/js/render/Frame.js b/js/render/Frame.js
index 783e0d91..3ee9fedb 100644
--- a/js/render/Frame.js
+++ b/js/render/Frame.js
@@ -24,6 +24,9 @@ class Frame {
     this._spanCacheEnabled = false;
     this._spanRows = null;
     this._spanBounds = null;
+    this._version = 0;
+    this._spanBatchDepth = 0;
+    this._spanInvalidationPending = false;
 
     this.clear();
   }
@@ -94,15 +97,20 @@ class Frame {
 
   // misc helpers -------------------------------------------------------------
   drawRect (x, y, w, h, color, noOverwrite = false, onlyOverwrite = false) {
-    const x2 = x + w;
-    const y2 = y + h;
-    for (let xx = x; xx <= x2; ++xx) {
-      this.setPixel(xx, y,  color, noOverwrite, onlyOverwrite);
-      this.setPixel(xx, y2, color, noOverwrite, onlyOverwrite);
-    }
-    for (let yy = y + 1; yy < y2; ++yy) {
-      this.setPixel(x,  yy, color, noOverwrite, onlyOverwrite);
-      this.setPixel(x2, yy, color, noOverwrite, onlyOverwrite);
+    this.#beginSpanBatch();
+    try {
+      const x2 = x + w;
+      const y2 = y + h;
+      for (let xx = x; xx <= x2; ++xx) {
+        this.setPixel(xx, y,  color, noOverwrite, onlyOverwrite);
+        this.setPixel(xx, y2, color, noOverwrite, onlyOverwrite);
+      }
+      for (let yy = y + 1; yy < y2; ++yy) {
+        this.setPixel(x,  yy, color, noOverwrite, onlyOverwrite);
+        this.setPixel(x2, yy, color, noOverwrite, onlyOverwrite);
+      }
+    } finally {
+      this.#endSpanBatch();
     }
   }
 
@@ -127,20 +135,30 @@ class Frame {
       pos = (pos + 1) % pattern;
     };
 
-    for (let dx = 0; dx <= width; dx++) set(x + dx, y);
-    for (let dy = 1; dy <= height; dy++) set(x + width, y + dy);
-    for (let dx = 1; dx <= width; dx++) set(x + width - dx, y + height);
-    for (let dy = 1; dy < height; dy++) set(x, y + height - dy);
+    this.#beginSpanBatch();
+    try {
+      for (let dx = 0; dx <= width; dx++) set(x + dx, y);
+      for (let dy = 1; dy <= height; dy++) set(x + width, y + dy);
+      for (let dx = 1; dx <= width; dx++) set(x + width - dx, y + height);
+      for (let dy = 1; dy < height; dy++) set(x, y + height - dy);
+    } finally {
+      this.#endSpanBatch();
+    }
   }
 
   /** Draw a stippled rectangle fill (simple checkerboard pattern). */
   drawStippleRect(x, y, width, height, r = 128, g = 128, b = 128) {
     const color32 = ColorPalette.colorFromRGB(r, g, b);
-    for (let dy = 0; dy <= height; dy++) {
-      for (let dx = 0; dx <= width; dx++) {
-        if (((dx + dy) & 1) !== 0) continue;
-        this.setPixel(x + dx, y + dy, color32);
+    this.#beginSpanBatch();
+    try {
+      for (let dy = 0; dy <= height; dy++) {
+        for (let dx = 0; dx <= width; dx++) {
+          if (((dx + dy) & 1) !== 0) continue;
+          this.setPixel(x + dx, y + dy, color32);
+        }
       }
+    } finally {
+      this.#endSpanBatch();
     }
   }
 
@@ -150,7 +168,7 @@ class Frame {
     if ((noOverwrite && this.mask[idx]) || (onlyOverwrite && !this.mask[idx])) return;
     this.data[idx] = color;
     this.mask[idx] = 1;
-    this.#invalidateSpanCache();
+    this.#markSpanCacheDirty();
   }
 
   clearPixel (x, y) {
@@ -158,10 +176,31 @@ class Frame {
     const idx = (y * this.width + x) >>> 0;
     this.data[idx] = ColorPalette.black;
     this.mask[idx] = 0;
+    this.#markSpanCacheDirty();
+  }
+
+  #beginSpanBatch () {
+    this._spanBatchDepth += 1;
+  }
+
+  #endSpanBatch () {
+    if (this._spanBatchDepth > 0) this._spanBatchDepth -= 1;
+    if (this._spanBatchDepth === 0 && this._spanInvalidationPending) {
+      this._spanInvalidationPending = false;
+      this.#invalidateSpanCache();
+    }
+  }
+
+  #markSpanCacheDirty () {
+    if (this._spanBatchDepth > 0) {
+      this._spanInvalidationPending = true;
+      return;
+    }
     this.#invalidateSpanCache();
   }
 
   #invalidateSpanCache () {
+    this._version += 1;
     if (!this._spanCacheEnabled) return;
     this._spanRows = null;
     this._spanBounds = null;
diff --git a/js/render/GroundRenderer.js b/js/render/GroundRenderer.js
index 03875b33..1ca3e411 100644
--- a/js/render/GroundRenderer.js
+++ b/js/render/GroundRenderer.js
@@ -16,7 +16,11 @@ function getPaletteLookup(palette) {
 }
 
 class GroundRenderer {
-  constructor () {}
+  constructor () {
+    this.tileSize = 64;
+    this.tileColumns = 0;
+    this.tileRows = 0;
+  }
 
   /** VGA‑spec levels reuse the pre‑decoded frame */
   createVgaspecMap (levelReader, vgaRenderer) {
@@ -27,6 +31,8 @@ class GroundRenderer {
   createGroundMap (levelReader, terrainImages) {
     const { levelWidth, levelHeight, terrains } = levelReader;
     this.img = new Frame(levelWidth, levelHeight);
+    this.tileColumns = Math.max(1, Math.ceil(levelWidth / this.tileSize));
+    this.tileRows = Math.max(1, Math.ceil(levelHeight / this.tileSize));
 
     for (let i = 0, len = terrains.length; i < len; ++i) {
       const tObj = terrains[i];
@@ -37,44 +43,68 @@ class GroundRenderer {
   _blit (srcImg, cfg, frameIdx = 0) {
     if (!srcImg) return;
 
-    const pix  = srcImg.frames[frameIdx];
-    const w    = srcImg.width | 0;
-    const h    = srcImg.height | 0;
-    const pal  = srcImg.palette;
-    const palLookup = getPaletteLookup(pal);
+    const pix = srcImg.frames?.[frameIdx];
+    if (!pix) return;
+
+    // Optional sourceScale allows high-resolution asset sources to render in
+    // classic world-space coordinates (for example 2x source pixels -> 1 world pixel).
+    const srcScaleX = Math.max(1, (srcImg.sourceScaleX | 0) || 1);
+    const srcScaleY = Math.max(1, (srcImg.sourceScaleY | 0) || 1);
+    let srcWidth = srcImg.width | 0;
+    let srcHeight = srcImg.height | 0;
+    let readColor = null;
+    let isOpaque = null;
+
+    if (pix instanceof Frame) {
+      srcWidth = pix.width | 0;
+      srcHeight = pix.height | 0;
+      const srcBuf = pix.getBuffer();
+      const srcMask = pix.getMask();
+      readColor = (idx) => srcBuf[idx];
+      isOpaque = (idx) => srcMask[idx] !== 0;
+    } else {
+      const palLookup = getPaletteLookup(srcImg.palette);
+      if (!palLookup) return;
+      readColor = (idx) => palLookup[pix[idx]];
+      isOpaque = (idx) => (pix[idx] & 0x80) === 0;
+    }
+    if (srcWidth <= 0 || srcHeight <= 0) return;
+    const w = Math.max(1, Math.floor(srcWidth / srcScaleX));
+    const h = Math.max(1, Math.floor(srcHeight / srcScaleY));
 
     const destX = cfg.x | 0;
     const destY = cfg.y | 0;
 
     const { isUpsideDown, noOverwrite, isErase, onlyOverwrite } = cfg.drawProperties;
     const img = this.img;
+    const sample = (x, y) => (y * srcWidth) + x;
 
     // Up–down variant chosen once, so the inner loop has zero branches
     if (isUpsideDown) {
       for (let y = 0; y < h; ++y) {
-        const srcRow = (h - 1 - y) * w;
+        const srcY = (h - 1 - y) * srcScaleY;
         const dy = y + destY;
         for (let x = 0; x < w; ++x) {
-          const ci = pix[srcRow + x];
-          if (ci & 0x80) continue;             // transparent
+          const idx = sample(x * srcScaleX, srcY);
+          if (!isOpaque(idx)) continue;
           if (isErase) {
             img.clearPixel(x + destX, dy);
           } else {
-            img.setPixel(x + destX, dy, palLookup[ci], noOverwrite, onlyOverwrite);
+            img.setPixel(x + destX, dy, readColor(idx), noOverwrite, onlyOverwrite);
           }
         }
       }
     } else {
       for (let y = 0; y < h; ++y) {
-        const srcRow = y * w;
+        const srcY = y * srcScaleY;
         const dy = y + destY;
         for (let x = 0; x < w; ++x) {
-          const ci = pix[srcRow + x];
-          if (ci & 0x80) continue;
+          const idx = sample(x * srcScaleX, srcY);
+          if (!isOpaque(idx)) continue;
           if (isErase) {
             img.clearPixel(x + destX, dy);
           } else {
-            img.setPixel(x + destX, dy, palLookup[ci], noOverwrite, onlyOverwrite);
+            img.setPixel(x + destX, dy, readColor(idx), noOverwrite, onlyOverwrite);
           }
         }
       }
diff --git a/js/render/Mask.js b/js/render/Mask.js
index ef74595a..5a19dd90 100644
--- a/js/render/Mask.js
+++ b/js/render/Mask.js
@@ -12,6 +12,9 @@ class Mask {
     this.width = width;
     this.height = height;
     this.data = null;
+    this.transparentSpans = null;
+    this.transparentOffsets = null;
+    this.clearableCount = 0;
     if (fr != null) {
       this.loadFromFile(fr, width, height);
     }
@@ -45,6 +48,60 @@ class Mask {
       bitBufferLen--;
     }
     this.data = pixBuf;
+    this._buildTransparentMetrics();
+  }
+
+  getTransparentSpans() {
+    if (!this.transparentSpans || !this.transparentOffsets) {
+      this._buildTransparentMetrics();
+    }
+    return this.transparentSpans;
+  }
+
+  _buildTransparentMetrics() {
+    const data = this.data;
+    const width = this.width | 0;
+    const height = this.height | 0;
+    if (!data || width <= 0 || height <= 0) {
+      this.transparentSpans = {
+        rows: new Int16Array(0),
+        starts: new Int16Array(0),
+        lengths: new Int16Array(0),
+        offsets: new Int32Array(0)
+      };
+      this.transparentOffsets = this.transparentSpans.offsets;
+      this.clearableCount = 0;
+      return;
+    }
+
+    const rows = [];
+    const starts = [];
+    const lengths = [];
+    const offsets = [];
+    for (let y = 0; y < height; y += 1) {
+      const row = y * width;
+      let x = 0;
+      while (x < width) {
+        while (x < width && data[row + x] === 0) x += 1;
+        if (x >= width) break;
+        const start = x;
+        while (x < width && data[row + x] !== 0) {
+          offsets.push(row + x);
+          x += 1;
+        }
+        rows.push(y);
+        starts.push(start);
+        lengths.push(x - start);
+      }
+    }
+    this.transparentSpans = {
+      rows: Int16Array.from(rows),
+      starts: Int16Array.from(starts),
+      lengths: Int16Array.from(lengths),
+      offsets: Int32Array.from(offsets)
+    };
+    this.transparentOffsets = this.transparentSpans.offsets;
+    this.clearableCount = this.transparentOffsets.length;
   }
 }
 export { Mask };
diff --git a/js/render/MiniMap.js b/js/render/MiniMap.js
index 74749129..d6f5341f 100644
--- a/js/render/MiniMap.js
+++ b/js/render/MiniMap.js
@@ -1,360 +1 @@
-import { Frame } from './Frame.js';
-import { TriggerTypes } from '../level/TriggerTypes.js';
-
-class MiniMap {
-  static palette = null;
-  static DEATH_DOT_TTL = 30;
-  constructor(gameDisplay, level, guiDisplay) {
-    this.gameDisplay = gameDisplay;
-    this.level = level;
-    this.guiDisplay = guiDisplay;
-
-    this.width = 127;
-    this.height = 24;
-    this.size = this.width * this.height;
-    this.scaleX = this.width / level.width;
-    this.scaleY = this.height / level.height;
-
-    this.terrain = new Uint8Array(this.size);
-    this.#buildTerrain();
-
-    // dynamic state
-    this.fog = new Uint8Array(this.size); // 0 = unseen
-    this.fog.fill(1); // disabled
-    // typed array storing [x1,y1,x2,y2,...] scaled to minimap
-    this.liveDots = new Uint8Array(0);
-    this.selectedDot = null;
-    // typed arrays storing [x1,y1,x2,y2,...] and TTL per dot
-    this.deadDots = new Uint8Array(64);
-    this.deadTTLs = new Uint8Array(32);
-    this.deadCount = 0;
-
-    // render target (drawn into the GUI canvas once per frame)
-    this.frame = new Frame(this.width, this.height);
-    //this.renderFrame = new Frame(this.renderWidth, this.renderHeight);
-
-    if (!MiniMap.palette) {
-      MiniMap.palette = new Uint32Array(129);
-      for (let i = 1; i <= 128; ++i) {
-        MiniMap.palette[i] = 0xFF000000 | ((i*2) << 8);
-      }
-    }
-
-    this._displayListeners = null;
-    this._mouseDown = false;
-    this.viewportDashOffset = 0;
-    this._viewportCounter = 0;
-    this.viewportDashDelay = 100;
-    if (this.guiDisplay) this.#hookPointer();
-  }
-
-  #hookPointer() {
-    this._displayListeners = [
-      ['onMouseDown', e => { this.#handleMouseDown(e); }],
-      ['onMouseUp', e => { this.#handleMouseUp(e); }],
-      ['onMouseMove', e => { this.#handleMouseMove(e); }],
-    ];
-    for (const [event, handler] of this._displayListeners) {
-      this.guiDisplay[event].on(handler);
-    }
-  }
-
-  #handleMouseDown(event){
-    if (!this.guiDisplay) return;
-    this._mouseDown = true;
-    const gd = this.guiDisplay;
-    const destX = gd.worldDataSize.width  - this.width;
-    const destY = gd.worldDataSize.height - this.height - 1;
-
-    const mx = event.x - destX;
-    const my = event.y - destY;
-    if (mx < 0 || my < 0 || mx >= this.width || my >= this.height) return;
-        
-    const pct = mx / this.width;
-    const newX = ((this.level.width - gd.worldDataSize.width) * pct) | 0;
-    this.level.screenPositionX = newX;
-    gd.setScreenPosition?.(newX, 0, { preserveScale: true });
-  }
-
-  #handleMouseUp(event){
-    if (!this.guiDisplay) return;
-    this._mouseDown = false;
-    const gd = this.guiDisplay;
-    const destX = gd.worldDataSize.width  - this.width;
-    const destY = gd.worldDataSize.height - this.height - 1;
-
-    const mx = event.x - destX;
-    const my = event.y - destY;
-    if (mx < 0 || my < 0 || mx >= this.width || my >= this.height) return;
-    const pct = mx / this.width;
-    const newX = ((this.level.width - gd.worldDataSize.width) * pct) | 0;
-    this.level.screenPositionX = newX;
-    gd.setScreenPosition?.(newX, 0, { preserveScale: true });
-  }
-
-  #handleMouseMove(event){
-    if (!this.guiDisplay) return;
-    if (!this._mouseDown) return;
-    const gd = this.guiDisplay;
-    const { width: gdW, height: gdH } = gd.worldDataSize;
-
-    const destX = gd.worldDataSize.width  - this.width;
-    const destY = gd.worldDataSize.height - this.height - 1;
-
-    const mx = event.x - destX;
-    const my = event.y - destY;
-    if (mx < 0 || my < 0 || mx >= this.width || my >= this.height) return;
-
-    const pct = mx / this.width;
-    const newX = ((this.level.width - gd.worldDataSize.width) * pct) | 0;
-    this.level.screenPositionX = newX;
-    gd.setScreenPosition?.(newX, 0, { preserveScale: true });
-  }
-
-  /* Build complete terrain snapshot (expensive – call at load/reset only). */
-  #buildTerrain() {
-    this.terrain.fill(0);
-    const gm = this.level.getGroundMaskLayer();
-    for (let mY = 0; mY < this.height; ++mY) {
-      const ly1 = Math.floor(mY / this.scaleY);
-      const ly2 = Math.min(this.level.height, Math.ceil((mY + 1) / this.scaleY));
-      for (let mX = 0; mX < this.width; ++mX) {
-        const lx1 = Math.floor(mX / this.scaleX);
-        const lx2 = Math.min(this.level.width, Math.ceil((mX + 1) / this.scaleX));
-        let count = gm.countMaskInRect(lx1, ly1, lx2 - lx1, ly2 - ly1, 72);
-        if (count > 71) count = 72;
-        this.terrain[mY * this.width + mX] = count;
-      }
-    }
-  }
-
-  /* Fast per‑pixel update called by digging/mining/placing ground.
-         Supply removed=true for clearing ground, false for placing. */
-  onGroundChanged(px, py, removed = true) {
-    const mX = (px * this.scaleX) | 0;
-    const mY = (py * this.scaleY) | 0;
-    const idx = mY * this.width + mX;
-    if (removed) {
-      if (this.terrain[idx] > 0) --this.terrain[idx];
-    } else {
-      if (this.terrain[idx] < 128) ++this.terrain[idx];
-    }
-  }
-
-  /* Region‑based revalidation (e.g. after a large mask dig). */
-  invalidateRegion(x, y, w, h) {
-    const gm = this.level.getGroundMaskLayer();
-    const xEnd = Math.min(this.level.width, x + w);
-    const yEnd = Math.min(this.level.height, y + h);
-
-    // For minimal work, track which minimap rows/cols need recompute
-    const touched = new Int8Array(this.width * this.height);
-
-    for (let py = y; py < yEnd; ++py) {
-      const mY = (py * this.scaleY) | 0;
-      const rowBase = mY * this.width;
-      for (let px = x; px < xEnd; ++px) {
-        const mX = (px * this.scaleX) | 0;
-        touched[rowBase + mX] = 1;
-      }
-    }
-
-    // For every touched cell recalc its counter from scratch.
-    for (let mY = 0; mY < this.height; ++mY) {
-      const rowBase = mY * this.width;
-      for (let mX = 0; mX < this.width; ++mX) {
-        const idx = rowBase + mX;
-        if (!touched[idx]) continue;
-
-        // Back‑map to level bounds for this cell.
-        const lx1 = Math.floor(mX / this.scaleX);
-        const lx2 = Math.min(this.level.width, Math.ceil((mX + 1) / this.scaleX));
-        const ly1 = Math.floor(mY / this.scaleY);
-        const ly2 = Math.min(this.level.height, Math.ceil((mY + 1) / this.scaleY));
-
-        let count = gm.countMaskInRect(lx1, ly1, lx2 - lx1, ly2 - ly1, 72);
-        if (count > 71) count = 72;
-        this.terrain[idx] = count;
-      }
-    }
-  }
-
-  /** reveal terrain that is currently on screen */
-  reveal(viewX, viewW) {
-    const sx1 = Math.floor(viewX * this.scaleX);
-    const sx2 = Math.min(this.width, Math.ceil((viewX + viewW) * this.scaleX));
-    for (let y = 0; y < this.height; ++y) {
-      const row = y * this.width;
-      for (let x = sx1; x < sx2; ++x) this.fog[row + x] = 1;
-    }
-  }
-
-  setLiveDots(arr) {
-    // arr is a Uint8Array of scaled [x1,y1,x2,y2,...]
-    this.liveDots = arr;
-  }
-
-  setSelectedDot(dot) {
-    this.selectedDot = dot;
-  }
-
-  addDeath(x, y) {
-    const sx = Math.max(0, Math.min(this.width - 1, (x * this.scaleX) | 0));
-    const sy = Math.max(0, Math.min(this.height - 1, (y * this.scaleY) | 0));
-    const history = globalThis?.lemmings?.game?.history ?? null;
-    if (history?.recordMinimapDeath) {
-      history.recordMinimapDeath({
-        x: sx,
-        y: sy,
-        ttl: MiniMap.DEATH_DOT_TTL,
-        prevCount: this.deadCount
-      });
-    }
-
-    if (this.deadCount >= this.deadTTLs.length) {
-      const next = Math.max(4, this.deadTTLs.length * 2);
-      const coords = new Uint8Array(next * 2);
-      const ttls = new Uint8Array(next);
-      coords.set(this.deadDots.subarray(0, this.deadCount * 2));
-      ttls.set(this.deadTTLs.subarray(0, this.deadCount));
-      this.deadDots = coords;
-      this.deadTTLs = ttls;
-    }
-
-    const idx = this.deadCount++;
-    this.deadDots[idx * 2] = sx;
-    this.deadDots[idx * 2 + 1] = sy;
-    this.deadTTLs[idx] = MiniMap.DEATH_DOT_TTL;
-  }
-
-  render() {
-    if (!this.guiDisplay) return;
-    const reversing = !!globalThis?.lemmings?.game?.timeTravel?.isReversing;
-
-    if (++this._viewportCounter >= this.viewportDashDelay) {
-      this._viewportCounter = 0;
-      this.viewportDashOffset += 1;
-    }
-
-    const {
-      width: W,
-      height: H,
-      frame,
-      terrain,
-      fog,
-    } = this;
-
-    /* Terrain + fog background */
-    for (let idx = 0; idx < terrain.length; ++idx) {
-      let color = 0xFF000000;
-      if (MiniMap.palette[terrain[idx]]) {
-        color = MiniMap.palette[terrain[idx]];
-      }
-      frame.data[idx] = color;
-      frame.mask[idx] = 1;
-    }
-
-    const viewRect = globalThis.lemmings?.stage?.getGameViewRect?.();
-    if (!viewRect) return;
-    const vpX = (viewRect.x * this.scaleX) | 0;
-    let vpW = (viewRect.w * this.scaleX) | 0;
-    const vpY = (viewRect.y * this.scaleY) | 0;
-    const vpH = (viewRect.h * this.scaleY) | 0;
-    let vpXW = vpX + vpW;
-    // dumb fix to keep right edge of viewport rect visible
-    if (vpXW == this.width) {
-      vpW -= 1;
-    }
-    frame.drawMarchingAntRect(
-      vpX,
-      vpY,
-      vpW,
-      vpH,
-      2,
-      this.viewportDashOffset,
-      0xFF00FF00,
-      0xFF005500
-    );
-
-    /* Entrances / Exits */
-    for (const obj of this.level.objects) {
-      const rx = (obj.x * this.scaleX) | 0;
-      const ry = (obj.y * this.scaleY) | 0;
-      if (obj.ob?.id === 1) frame.setPixel(rx + 2, ry + 2, 0xFF00AA00);
-      if (obj.triggerType === TriggerTypes.EXIT_LEVEL) {
-        frame.setPixel(rx + 2, ry + 2, 0xFFFF00CC);
-        frame.setPixel(rx + 2, ry + 1, 0xFFFF00CC);
-      }
-    }
-
-    /* Live lemmings */
-    for (let i = 0; i < this.liveDots.length; i += 2) {
-      const x = this.liveDots[i];
-      const y = this.liveDots[i + 1];
-      frame.setPixel(x, y, 0xFF00FFFF);
-    }
-    if (this.selectedDot) {
-      frame.setPixel(this.selectedDot[0], this.selectedDot[1], 0xFFFFFFFF);
-    }
-
-    /* Death flashes */
-    if (reversing) {
-      const total = this.deadCount;
-      for (let i = 0; i < total; ++i) {
-        const ttl = this.deadTTLs[i];
-        if (ttl <= 0) continue;
-        if (ttl & 4) {
-          const x = this.deadDots[i * 2];
-          const y = this.deadDots[i * 2 + 1];
-          frame.setPixel(x, y, 0xFF0000FF);
-        }
-      }
-    } else {
-      let write = 0;
-      const total = this.deadCount;
-      for (let i = 0; i < total; ++i) {
-        const ttl = this.deadTTLs[i] - 1;
-        if (ttl <= 0) continue;
-        this.deadTTLs[write] = ttl;
-        const x = this.deadDots[i * 2];
-        const y = this.deadDots[i * 2 + 1];
-        this.deadDots[write * 2] = x;
-        this.deadDots[write * 2 + 1] = y;
-        if (ttl & 4) {
-          frame.setPixel(x, y, 0xFF0000FF);
-        }
-        write++;
-      }
-      this.deadCount = write;
-    }
-
-    /* Blit */
-    const destX = this.guiDisplay.worldDataSize.width  - W;
-    const destY = this.guiDisplay.worldDataSize.height - H;
-    this.guiDisplay.drawFrame(frame, destX, destY);
-  }
-
-  dispose() {
-    if (this.guiDisplay && this._displayListeners) {
-      for (const [event, handler] of this._displayListeners) {
-        this.guiDisplay[event].off(handler);
-      }
-      this._displayListeners = null;
-    }
-    this.gameDisplay = null;
-    this.level = null;
-    this.guiDisplay = null;
-    this.terrain = null;
-    this.fog = null;
-    this.liveDots = null;
-    this.selectedDot = null;
-    this.deadDots = null;
-    this.deadTTLs = null;
-    this.deadCount = 0;
-    this.frame = null;
-  }
-}
-
-export {
-  MiniMap
-};
+export { MiniMap } from './minimap/MiniMapCore.js';
diff --git a/js/render/ParticleTable.js b/js/render/ParticleTable.js
index a166f97b..d5489c6a 100644
--- a/js/render/ParticleTable.js
+++ b/js/render/ParticleTable.js
@@ -57,6 +57,23 @@ class ParticleTable {
     gameDisplay.drawFrame(frame, x, y);
   }
 
+  drawMany(gameDisplay, frameIndex, points) {
+    const frame = this.#frames?.[frameIndex];
+    if (!frame || !gameDisplay || !Array.isArray(points) || points.length < 1) {
+      return 0;
+    }
+    let drawn = 0;
+    for (let i = 0; i < points.length; i += 1) {
+      const point = points[i];
+      const x = point?.x;
+      const y = point?.y;
+      if (!Number.isFinite(x) || !Number.isFinite(y)) continue;
+      gameDisplay.drawFrame(frame, x, y);
+      drawn += 1;
+    }
+    return drawn;
+  }
+
   #buildFrames() {
     const frames = new Array(this.#particleData.length);
     const table = this.#colorIndexTable;
diff --git a/js/render/SolidLayer.js b/js/render/SolidLayer.js
index dc1eecb8..0209d1b7 100644
--- a/js/render/SolidLayer.js
+++ b/js/render/SolidLayer.js
@@ -1,4 +1,4 @@
-import { BaseLogger, withPerformance } from '../util/LogHandler.js';
+import { BaseLogger } from '../util/LogHandler.js';
 
 class SolidLayer extends BaseLogger {
   /**
@@ -111,6 +111,38 @@ class SolidLayer extends BaseLogger {
     return height + 1;
   }
 
+  /**
+     * Return contiguous wall height directly above yBottom.
+     * This is tuned for repeated AI wall checks in procgen.
+     * @param {number} x
+     * @param {number} yBottom
+     * @param {number} height
+     * @returns {number} 0..height
+     */
+  getColumnWallHeight(x, yBottom, height) {
+    const w = this.width;
+    const h = this.height;
+    const limit = Math.floor(height);
+    if (x < 0 || x >= w || !Number.isFinite(limit) || limit <= 0) return 0;
+    const mask = this.mask;
+    let wall = 0;
+    let started = false;
+    for (let dy = 1; dy <= limit; dy++) {
+      const y = yBottom - dy;
+      if (y < 0 || y >= h) {
+        if (started) break;
+        continue;
+      }
+      started = true;
+      if (mask[y * w + x] !== 0) {
+        wall += 1;
+      } else {
+        break;
+      }
+    }
+    return wall;
+  }
+
   /**
      * Count solid pixels in a rectangle without allocating a sublayer.
      * Out-of-bounds areas are treated as empty.
@@ -153,35 +185,25 @@ class SolidLayer extends BaseLogger {
      */
   clearGroundWithMask(mask, x, y, skipTest = null) {
     let changed = false;
-    withPerformance(
-      'clearGroundWithMask',
-      {
-        track: 'SolidLayer',
-        trackGroup: 'Game State',
-        color: 'primary-dark',
-        tooltipText: `clearGroundWithMask ${x},${y}`
-      },
-      () => {
-        const mx = mask.offsetX || 0, my = mask.offsetY || 0;
-        for (let dy = 0; dy < mask.height; ++dy) {
-          const mapY = y + my + dy;
-          if (mapY < 0 || mapY >= this.height) continue;
-          for (let dx = 0; dx < mask.width; ++dx) {
-            const mapX = x + mx + dx;
-            if (mapX < 0 || mapX >= this.width) continue;
-            // Only clear where mask pixel is **not** solid
-            if (!mask.at(dx, dy)) {
-              if (!skipTest || !skipTest(mapX, mapY)) {
-                const idx = mapX + mapY * this.width;
-                if (this.mask[idx]) {
-                  this.mask[idx] = 0;
-                  changed = true;
-                }
-              }
+    const mx = mask.offsetX || 0, my = mask.offsetY || 0;
+    for (let dy = 0; dy < mask.height; ++dy) {
+      const mapY = y + my + dy;
+      if (mapY < 0 || mapY >= this.height) continue;
+      for (let dx = 0; dx < mask.width; ++dx) {
+        const mapX = x + mx + dx;
+        if (mapX < 0 || mapX >= this.width) continue;
+        // Only clear where mask pixel is **not** solid
+        if (!mask.at(dx, dy)) {
+          if (!skipTest || !skipTest(mapX, mapY)) {
+            const idx = mapX + mapY * this.width;
+            if (this.mask[idx]) {
+              this.mask[idx] = 0;
+              changed = true;
             }
           }
         }
-      })();
+      }
+    }
     return changed;
   }
 
@@ -192,22 +214,12 @@ class SolidLayer extends BaseLogger {
      * @param {Function|null} skipTest - Optional (x, y) => true if pixel should not be cleared (e.g. steel check)
      */
   clearGroundWithMasks(masks, positions, skipTest = null) {
-    withPerformance(
-      'clearGroundWithMasks',
-      {
-        track: 'SolidLayer',
-        trackGroup: 'Game State',
-        color: 'primary-light',
-        tooltipText: `clearGroundWithMasks ${masks.length}`
-      },
-      () => {
-        if (!Array.isArray(masks) || masks.length === 0) return;
-        for (let i = 0; i < masks.length; ++i) {
-          const mask = masks[i], pos = positions[i];
-          if (!mask || !pos) continue;
-          this.clearGroundWithMask(mask, pos[0], pos[1], skipTest);
-        }
-      })();
+    if (!Array.isArray(masks) || masks.length === 0) return;
+    for (let i = 0; i < masks.length; ++i) {
+      const mask = masks[i], pos = positions[i];
+      if (!mask || !pos) continue;
+      this.clearGroundWithMask(mask, pos[0], pos[1], skipTest);
+    }
   }
 }
 
diff --git a/js/render/Stage.js b/js/render/Stage.js
index 806a67e8..346c9f5e 100644
--- a/js/render/Stage.js
+++ b/js/render/Stage.js
@@ -1,658 +1 @@
-import { DisplayImage, drawMarchingAntRect } from './DisplayImage.js';
-import { Position2D } from '../util/Position2D.js';
-import { StageImageProperties } from './StageImageProperties.js';
-import { UserInputManager } from '../input/UserInputManager.js';
-import { ViewPoint } from './ViewPoint.js';
-import { getDependency } from '../core/dependencies.js';
-
-function colorStringTo32(str) {
-  const m = /rgba?\((\d+),(\d+),(\d+),(\d*(?:\.\d+)?)\)/.exec(str);
-  if (!m) return 0xffffffff;
-  const r = parseInt(m[1]);
-  const g = parseInt(m[2]);
-  const b = parseInt(m[3]);
-  const a = m[4] === undefined ? 1 : parseFloat(m[4]);
-  return ((Math.round(a * 255) & 0xff) << 24) | (b << 16) | (g << 8) | r;
-}
-
-class Stage {
-  constructor(canvasForOutput) {
-    this.controller = null;
-    this.fadeTimer = 0;
-    this.fadeAlpha = 0;
-    this.overlayColor = 'black';
-    this.overlayAlpha = 0;
-    this.overlayRect = null;
-    this.overlayTimer = 0;
-    this.overlayDashLen = 0;
-    this.overlayDashColor = 0;
-    this.overlayDashOffset = 0;
-    this.panEnabled = true;
-    this._resizeRaf = 0;
-
-    this.cursorCanvas = null;
-    this.cursorX = 0;
-    this.cursorY = 0;
-    this.guiEnabled = true;
-    this.hudMargin = 20;
-
-    this.stageCav = canvasForOutput;
-    this.gameImgProps = new StageImageProperties();
-    this.guiImgProps  = new StageImageProperties();
-
-    // HUD always starts at scale = 4
-    this.guiImgProps.viewPoint = new ViewPoint(0, 0, 4);
-    this._rawScale = this.gameImgProps.viewPoint.scale || 1;
-
-    // Initialize DisplayImage instances
-    this.getGameDisplay();
-    this.getGuiDisplay();
-
-    this.controller = new UserInputManager(canvasForOutput);
-    this.handleOnMouseUp();
-    this.handleOnMouseDown();
-    this.handleOnMouseRightUp();
-    this.handleOnMouseRightDown();
-    this.handleOnMouseMove();
-    this.handleOnDoubleClick();
-    this.handleOnZoom();
-
-    this.updateStageSize();
-    this.clear();
-  }
-
-  setCursorSprite(frame) {
-    if (!frame) {
-      this.cursorCanvas = null;
-      return;
-    }
-    const c = document.createElement('canvas');
-    c.width = frame.width;
-    c.height = frame.height;
-    const ictx = c.getContext('2d', { alpha: true, willReadFrequently: true});
-    ictx.putImageData(
-      new ImageData(frame.getData(), frame.width, frame.height),
-      0,
-      0
-    );
-    this.cursorCanvas = c;
-  }
-
-  setGuiEnabled(enabled) {
-    this.guiEnabled = !!enabled;
-    if (!this.guiEnabled) {
-      this.guiImgProps.display = null;
-    }
-    this.updateStageSize();
-  }
-
-  calcPosition2D(stageImage, e) {
-    const localX = e.x - stageImage.x;
-    const localY = e.y - stageImage.y;
-    const worldX = stageImage.viewPoint.getSceneX(localX);
-    const worldY = stageImage.viewPoint.getSceneY(localY);
-    return new Position2D(worldX, worldY);
-  }
-
-  handleOnDoubleClick() {
-    this.controller.onDoubleClick.on((e) => {
-      const stageImage = this.getStageImageAt(e.x, e.y);
-      if (!stageImage || !stageImage.display) return;
-      const pos = this.calcPosition2D(stageImage, e);
-      stageImage.display.onDoubleClick.trigger(pos);
-    });
-  }
-
-  handleOnMouseDown() {
-    this.controller.onMouseDown.on((e) => {
-      const stageImage = this.getStageImageAt(e.x, e.y);
-      if (!stageImage || !stageImage.display) return;
-      const pos = this.calcPosition2D(stageImage, e);
-      stageImage.display.onMouseDown.trigger(pos);
-    });
-  }
-
-  handleOnMouseUp() {
-    this.controller.onMouseUp.on((e) => {
-      const stageImage = this.getStageImageAt(e.x, e.y);
-      if (!stageImage || !stageImage.display) return;
-      const pos = this.calcPosition2D(stageImage, e);
-      stageImage.display.onMouseUp.trigger(pos);
-    });
-  }
-
-  handleOnMouseRightDown() {
-    this.controller.onMouseRightDown.on((e) => {
-      const stageImage = this.getStageImageAt(e.x, e.y);
-      if (!stageImage || !stageImage.display) return;
-      const pos = this.calcPosition2D(stageImage, e);
-      stageImage.display.onMouseRightDown.trigger(pos);
-    });
-  }
-
-  handleOnMouseRightUp() {
-    this.controller.onMouseRightUp.on((e) => {
-      const stageImage = this.getStageImageAt(e.x, e.y);
-      if (!stageImage || !stageImage.display) return;
-      const pos = this.calcPosition2D(stageImage, e);
-      stageImage.display.onMouseRightUp.trigger(pos);
-    });
-  }
-
-  handleOnMouseMove() {
-    this.controller.onMouseMove.on((e) => {
-      this.cursorX = e.x;
-      this.cursorY = e.y;
-
-      if (e.button) {
-        const stageImage = this.getStageImageAt(e.mouseDownX, e.mouseDownY);
-        if (!stageImage || !stageImage.display) return;
-        if (this.panEnabled && stageImage === this.gameImgProps) {
-          this.updateViewPoint(stageImage, e.deltaX, e.deltaY, 0);
-        }
-        const pos = this.calcPosition2D(stageImage, e);
-        stageImage.display.onMouseMove.trigger(pos);
-      } else {
-        const stageImage = this.getStageImageAt(e.x, e.y);
-        if (!stageImage || !stageImage.display) return;
-        const localX = e.x - stageImage.x;
-        const localY = e.y - stageImage.y;
-        const worldX = stageImage.viewPoint.getSceneX(localX);
-        const worldY = stageImage.viewPoint.getSceneY(localY);
-        stageImage.display.onMouseMove.trigger(
-          new Position2D(worldX, worldY)
-        );
-        
-      }
-    });
-  }
-
-  handleOnZoom() {
-    this.controller.onZoom.on((e) => {
-      const stageImage = this.gameImgProps;
-      if (!stageImage || !stageImage.display) return;
-
-      // Always zoom around the cursor position e.x,e.y
-      this.updateViewPoint(stageImage, e.x, e.y, e.deltaZoom, e.velocity);
-    });
-  }
-
-  /**
-   * updateViewPoint(stageImage, argX, argY, deltaZoom)
-   *
-   * Pan/zoom logic:
-   * • If deltaZoom !== 0: treat argX,argY as cursor pixel coordinates.
-   *   1) Compute relX = screenX − stageImage.x
-   *   2) Compute relY = screenY − stageImage.y
-   *   3) sceneX_pre = viewPoint.getSceneX(relX)
-   *      sceneY_pre = viewPoint.getSceneY(relY)
-   *   4) newScale = oldScale + deltaZoom × zoomSensitivity
-   *   5) Clamp then snap newScale
-   *   6) viewPoint.scale = newScale
-   *   7) viewPoint.x = sceneX_pre − (relX / newScale)
-   *      viewPoint.y = sceneY_pre − (relY / newScale)
-   * • Else: treat argX,argY as drag distances (deltaX,deltaY) in screen pixels
-   *   1) worldDX = deltaX / scale
-   *      worldDY = deltaY / scale
-   *   2) viewPoint.x −= worldDX
-   *      viewPoint.y −= worldDY
-   */
-  updateViewPoint(stageImage, argX, argY, deltaZoom, veloUpdate = false) {
-    if (!stageImage || !stageImage.display) return;
-
-    let targetScale = stageImage.viewPoint.scale || 1;
-    let targetX = stageImage.viewPoint.x;
-    let targetY = stageImage.viewPoint.y;
-
-    if (deltaZoom !== 0) {
-      const screenX_rel = argX - stageImage.x;
-      const screenY_rel = argY - stageImage.y;
-
-      const sceneX_pre = stageImage.viewPoint.getSceneX(screenX_rel);
-      const sceneY_pre = stageImage.viewPoint.getSceneY(screenY_rel);
-
-      const zoomSensitivity = 0.001125;
-      const desiredScale = targetScale + deltaZoom * zoomSensitivity;
-      const snappedScale = this.snapScale(desiredScale);
-      targetScale = snappedScale;
-
-      if (!veloUpdate && snappedScale !== stageImage.viewPoint.scale) {
-        targetX = sceneX_pre - screenX_rel / targetScale;
-        targetY = sceneY_pre - screenY_rel / targetScale;
-      }
-    } else {
-      targetX += argX / targetScale;
-      targetY += argY / targetScale;
-    }
-    const imgData = stageImage.display.getImageData();
-    const guiImgData = this.guiImgProps.display.getImageData();
-    this.applyViewport(stageImage, targetX, targetY, targetScale);
-    this.clear(stageImage);
-    this.clear(this.guiImgProps);
-    this.draw(stageImage, imgData);
-    this.draw(this.guiImgProps, guiImgData);
-  }
-
-  /**
-   * Snap a raw scale so that (displayWidth × scale) and (displayHeight × scale)
-   * are both integers (no sub‐pixel artifact). Based on DisplayImage’s dimensions.
-   */
-  snapScale(rawScale) {
-    const { width: dispW, height: dispH } = this.gameImgProps.display.worldDataSize;
-    if (dispW === 0 || dispH === 0) return rawScale;
-
-    const gcd = (a, b) => (b ? gcd(b, a % b) : a);
-    const g = gcd(dispW, dispH);
-    const step = 1 / g;
-
-    const minScale = 0.25;
-    const maxScale = 8;
-    let clamped = rawScale;
-    if (clamped < minScale) clamped = minScale;
-    if (clamped > maxScale) clamped = maxScale;
-
-    return Math.round(clamped / step) * step;
-  }
-
-  applyViewport(stageImage, targetX, targetY, targetScale) {
-    if (!stageImage || !stageImage.display) return;
-
-    this._rawScale = targetScale;
-    stageImage.viewPoint.scale = this.snapScale(targetScale);
-    stageImage.viewPoint.setX(targetX);
-    stageImage.viewPoint.setY(targetY);
-
-    this.clampViewPoint(stageImage);
-  }
-
-  scheduleUpdateStageSize() {
-    if (this._resizeRaf) return;
-    if (typeof window === 'undefined' || typeof window.requestAnimationFrame !== 'function') {
-      this.updateStageSize();
-      return;
-    }
-    this._resizeRaf = window.requestAnimationFrame(() => {
-      this._resizeRaf = 0;
-      this.updateStageSize();
-    });
-  }
-
-  updateStageSize() {
-    const stageH = this.stageCav.height;
-    const stageW = this.stageCav.width;
-    const guiActive = this.guiEnabled && !!this.guiImgProps.display;
-    // this margin is for the level <select> elements in the html
-    const margin = guiActive ? this.hudMargin : 0;
-
-    // HUD scale adapts to available space
-    const rawHUDH = guiActive ? (this.guiImgProps.display?.worldDataSize.height || 80) : 0;
-    const rawHUDW = guiActive ? (this.guiImgProps.display?.worldDataSize.width || 720) : 0;
-
-    const maxScaleW = guiActive && rawHUDW ? stageW / rawHUDW : 1;
-    const maxScaleH = guiActive && rawHUDH ? (stageH - margin) / rawHUDH : 1;
-    let hudScale = guiActive ? Math.min(4, maxScaleW, maxScaleH) : 1;
-    if (!isFinite(hudScale) || hudScale <= 0) hudScale = 1;
-    this.guiImgProps.viewPoint.scale = hudScale;
-
-    const hudH = guiActive ? rawHUDH * hudScale : 0;
-    const hudW = guiActive ? rawHUDW * hudScale : 0;
-
-    const gameH = Math.max(0, stageH - hudH - margin);
-
-    Object.assign(this.gameImgProps, { x: 0, y: 0 });
-    this.gameImgProps.canvasViewportSize = { width: stageW, height: gameH };
-    Object.assign(this.guiImgProps, {
-      x: guiActive ? (stageW - hudW) / 2 : 0,
-      y: guiActive ? (stageH - hudH - margin) : 0
-    });
-    this.guiImgProps.canvasViewportSize = { width: hudW, height: hudH };
-
-    if (this.gameImgProps.display) {
-      const { width: worldW, height: worldH } = this.gameImgProps.display.worldDataSize;
-
-      const scale = this.gameImgProps.viewPoint.scale || 2;
-      const viewH_world = gameH / scale;
-      const viewW_world = stageW / scale;
-
-      let x = this.gameImgProps.viewPoint.x;
-      let y = this.gameImgProps.viewPoint.y;
-      if (!isFinite(x)) x = 0;
-      if (!isFinite(y)) y = 0;
-
-      if (worldW * scale <= stageW) {
-        x = (worldW - viewW_world) / 2;
-      }
-
-      this.applyViewport(this.gameImgProps, x, y, scale);
-
-      // Redraw at initial position
-      this.clear(this.gameImgProps);
-      const gameImg = this.gameImgProps.display.getImageData();
-      this.draw(this.gameImgProps, gameImg);
-    }
-
-    if (guiActive && this.guiImgProps.display) {
-      const guiImg = this.guiImgProps.display.getImageData();
-      this.draw(this.guiImgProps, guiImg);
-    }
-  }
-  getStageImageAt(x, y) {
-    const { width: gameW, height: gameH } =
-      this.gameImgProps.canvasViewportSize;
-    if (
-      x >= this.gameImgProps.x &&
-      x <  this.gameImgProps.x + gameW &&
-      y >= this.gameImgProps.y &&
-      y <  this.gameImgProps.y + gameH
-    ) {
-      return this.gameImgProps;
-    }
-    const { width: guiW, height: guiH } =
-      this.guiImgProps.canvasViewportSize;
-    if (
-      x >= this.guiImgProps.x &&
-      x <  this.guiImgProps.x + guiW &&
-      y >= this.guiImgProps.y &&
-      y <  this.guiImgProps.y + guiH
-    ) {
-      return this.guiImgProps;
-    }
-    return null;
-  }
-
-  getGameDisplay() {
-    if (this.gameImgProps.display) return this.gameImgProps.display;
-    this.gameImgProps.display = new DisplayImage(this);
-    return this.gameImgProps.display;
-  }
-
-  getGuiDisplay() {
-    if (this.guiImgProps.display) return this.guiImgProps.display;
-    this.guiImgProps.display = new DisplayImage(this);
-    return this.guiImgProps.display;
-  }
-
-  setGameViewPointPosition(x, y, options = {}) {
-    this.clear(this.gameImgProps);
-    const targetY = isFinite(y) ? y : 0;
-    const preserveScale = options.preserveScale === true;
-    if (preserveScale) {
-      const rawScale = Number.isFinite(this._rawScale)
-        ? this._rawScale
-        : (this.gameImgProps.viewPoint.scale || 1);
-      this._rawScale = rawScale;
-      this.applyViewport(this.gameImgProps, x, targetY, rawScale);
-      this.redraw();
-      return;
-    }
-
-    const app = globalThis?.lemmings;
-    if (app?.scale > 0) {
-      this._rawScale = app.scale;
-      this.gameImgProps.viewPoint.scale = this.snapScale(this._rawScale);
-      this.gameImgProps.viewPoint.setX(x);
-      this.gameImgProps.viewPoint.setY(targetY);
-      this.clampViewPoint(this.gameImgProps);
-
-      this.redraw();
-      return;
-    }
-
-    let scale = this.gameImgProps.viewPoint.scale;
-    if (scale === 2) {
-      this._rawScale = scale;
-      this.gameImgProps.viewPoint.scale = this.snapScale(this._rawScale);
-      this.gameImgProps.viewPoint.setX(x);
-      this.gameImgProps.viewPoint.setY(targetY);
-      this.clampViewPoint(this.gameImgProps);
-
-      this.redraw();
-      return;
-    }
-
-    const sceneX = this.gameImgProps.viewPoint.getSceneX(x - this.gameImgProps.x);
-    const sceneY = this.gameImgProps.viewPoint.getSceneY(y - this.gameImgProps.y);
-    this._rawScale = 2;
-    this.gameImgProps.viewPoint.scale = this.snapScale(this._rawScale);
-    this.gameImgProps.viewPoint.setX(
-      sceneX - (x - this.gameImgProps.x) / this.gameImgProps.viewPoint.scale
-    );
-    this.gameImgProps.viewPoint.setY(
-      sceneY - (y - this.gameImgProps.y) / this.gameImgProps.viewPoint.scale
-    );
-    this.clampViewPoint(this.gameImgProps);
-
-    this.redraw();
-  }
-
-  redraw() {
-    this.clear();
-    if (this.gameImgProps.display) {
-      const gameImg = this.gameImgProps.display.getImageData();
-      this.draw(this.gameImgProps, gameImg);
-    }
-    if (this.guiImgProps.display) {
-      const guiImg = this.guiImgProps.display.getImageData();
-      this.draw(this.guiImgProps, guiImg);
-    }
-    this.drawCursor();
-  }
-
-  createImage(displayOwner, width, height) {
-    return displayOwner === this.gameImgProps.display
-      ? this.gameImgProps.createImage(width, height)
-      : this.guiImgProps.createImage(width, height);
-  }
-
-  clear(stageImage) {
-    const ctx = this.stageCav.getContext('2d', { willReadFrequently: true });
-    ctx.fillStyle = '#000900';
-    if (!stageImage) {
-      ctx.fillRect(0, 0, ctx.canvas.width, ctx.canvas.height);
-    } else {
-      ctx.fillRect(stageImage.x, stageImage.y, stageImage.width, stageImage.height);
-    }
-  }
-
-  resetFade() {
-    this.fadeAlpha = 0;
-    this.overlayAlpha = 0;
-    this.overlayRect = null;
-    if (this.fadeTimer) clearInterval(this.fadeTimer);
-    if (this.overlayTimer) clearInterval(this.overlayTimer);
-    this.fadeTimer = this.overlayTimer = 0;
-  }
-
-  startFadeOut() {
-    this.resetFade();
-    this.fadeTimer = setInterval(() => {
-      this.fadeAlpha = Math.min(this.fadeAlpha + 0.02, 1);
-      if (this.fadeAlpha >= 1) {
-        clearInterval(this.fadeTimer);
-        this.fadeTimer = 0;
-      }
-    }, 40);
-  }
-
-  startOverlayFade(color, rect = null, dashLen = 0) {
-    if (this.overlayTimer) clearInterval(this.overlayTimer);
-    this.overlayColor = color;
-    this.overlayRect = rect;
-    this.overlayDashLen = dashLen;
-    this.overlayDashColor = colorStringTo32(color);
-    this.overlayDashOffset = 0;
-    this.overlayAlpha = 1;
-    this.overlayTimer = setInterval(() => {
-      this.overlayAlpha = Math.max(this.overlayAlpha - 0.02, 0);
-      this.overlayDashOffset = (this.overlayDashOffset + 1) % ((this.overlayDashLen || 1) * 2);
-      if (this.overlayAlpha <= 0) {
-        clearInterval(this.overlayTimer);
-        this.overlayTimer = 0;
-        this.overlayRect = null;
-        this.overlayDashLen = 0;
-      }
-    }, 40);
-  }
-
-  resetOverlayFade() {
-    this.overlayAlpha = 0;
-    this.overlayRect = null;
-    this.overlayDashLen = 0;
-    if (this.overlayTimer) clearInterval(this.overlayTimer);
-    this.overlayTimer = 0;
-  }
-
-  dispose() {
-    this.resetFade();
-    if (this._resizeRaf) {
-      window.cancelAnimationFrame(this._resizeRaf);
-      this._resizeRaf = 0;
-    }
-    if (this.gameImgProps.display?.dispose) this.gameImgProps.display.dispose();
-    if (this.guiImgProps.display?.dispose)  this.guiImgProps.display.dispose();
-    if (this.controller?.dispose)            this.controller.dispose();
-    this.controller = null;
-    this.gameImgProps = null;
-    this.guiImgProps  = null;
-    this.stageCav     = null;
-  }
-
-  draw(display, img) {
-    if (!display.ctx) return;
-
-    display.ctx.putImageData(img, 0, 0);
-
-    const ctx = this.stageCav.getContext('2d', { willReadFrequently: true });
-    ctx.imageSmoothingEnabled = false;
-    ctx.globalAlpha = 1;
-
-    let sx = display.viewPoint.x;
-    let sy = display.viewPoint.y;
-    let sw = img.width - sx;
-    let sh = img.height - sy;
-    if (sx < 0) {
-      sw += sx;
-      sx = 0;
-    }
-    if (sy < 0) {
-      sh += sy;
-      sy = 0;
-    }
-    sw = Math.min(sw, img.width - sx);
-    sh = Math.min(sh, img.height - sy);
-
-    const dx = display.x + Math.max(-display.viewPoint.x, 0) * display.viewPoint.scale;
-    const dy = display.y + Math.max(-display.viewPoint.y, 0) * display.viewPoint.scale;
-    let dw = sw * display.viewPoint.scale;
-    let dh = sh * display.viewPoint.scale;
-
-    if (dw > display.width) {
-      sw = display.width / display.viewPoint.scale;
-      dw = display.width;
-    }
-    if (dh > display.height) {
-      sh = display.height / display.viewPoint.scale;
-      dh = display.height;
-    }
-
-    ctx.drawImage(
-      display.cav,
-      sx,
-      sy,
-      sw,
-      sh,
-      dx,
-      dy,
-      Math.trunc(dw),
-      Math.trunc(dh)
-    );
-
-    if (this.fadeAlpha !== 0) {
-      ctx.globalAlpha = this.fadeAlpha;
-      ctx.fillStyle = 'black';
-      ctx.fillRect(display.x, display.y, Math.trunc(dw), Math.trunc(dh));
-      ctx.globalAlpha = 1;
-    }
-
-    if (this.overlayAlpha > 0) {
-      ctx.globalAlpha = this.overlayAlpha;
-      ctx.fillStyle = this.overlayColor;
-      const r = this.overlayRect || {
-        x: display.x,
-        y: display.y,
-        width: Math.trunc(dw),
-        height: Math.trunc(dh),
-      };
-      ctx.fillRect(r.x, r.y, r.width, r.height);
-      ctx.globalAlpha = 1;
-      if (this.overlayDashLen > 0) {
-        const octx = this.stageCav.getContext('2d', { alpha: true, willReadFrequently: true});
-        const img = octx.getImageData(r.x, r.y, r.width + 1, r.height + 1);
-        const disp = { buffer32: new Uint32Array(img.data.buffer), imgData: img };
-        const drawAnts = getDependency('drawMarchingAntRect', drawMarchingAntRect);
-        drawAnts(
-          disp,
-          0,
-          0,
-          r.width,
-          r.height,
-          this.overlayDashLen,
-          this.overlayDashOffset,
-          this.overlayDashColor,
-          0x00000000
-        );
-        octx.putImageData(img, r.x, r.y);
-      }
-    }
-  }
-
-  drawCursor() {
-    if (!this.cursorCanvas) return;
-    const ctx = this.stageCav.getContext('2d', { alpha: true, willReadFrequently: true});
-    const cx = Math.trunc(this.cursorX - this.cursorCanvas.width / 2);
-    const cy = Math.trunc(this.cursorY - this.cursorCanvas.height / 2);
-    ctx.drawImage(this.cursorCanvas, cx, cy);
-  }
-
-  clampViewPoint(stageImage) {
-    if (!stageImage || !stageImage.display) return;
-    const { width: worldW, height: worldH } = stageImage.display.worldDataSize;
-    const scale = stageImage.viewPoint.scale;
-    const { width: vpW, height: vpH } = stageImage.canvasViewportSize;
-    const viewW = vpW / scale;
-    const viewH = vpH / scale;
-
-    const maxY = Math.max(worldH - viewH, 0);
-    stageImage.viewPoint.y = this.limitValue(
-      0,
-      stageImage.viewPoint.y,
-      maxY
-    );
-
-    if (worldW <= viewW) {
-      stageImage.viewPoint.x = (worldW - viewW) / 2;
-    } else {
-      stageImage.viewPoint.x = this.limitValue(
-        0,
-        stageImage.viewPoint.x,
-        worldW - viewW
-      );
-    }
-  }
-
-  getGameViewRect() {
-    return {
-      x: this.gameImgProps.viewPoint.x,
-      y: this.gameImgProps.viewPoint.y,
-      w: this.gameImgProps.canvasViewportSize.width  / this.gameImgProps.viewPoint.scale,
-      h: this.gameImgProps.canvasViewportSize.height / this.gameImgProps.viewPoint.scale
-
-    };
-  }
-
-  limitValue(minLimit, value, maxLimit) {
-    return Math.min(Math.max(minLimit, value), maxLimit);
-  }
-}
-
-export { Stage };
+export { Stage } from './stage/StageCore.js';
diff --git a/js/render/display/DisplayBlit.js b/js/render/display/DisplayBlit.js
new file mode 100644
index 00000000..a14d56d6
--- /dev/null
+++ b/js/render/display/DisplayBlit.js
@@ -0,0 +1,246 @@
+import {
+  BaseLogger,
+  DIRTY_RECT_FULL_LIMIT,
+  DIRTY_RECT_MERGE_PAD,
+  DIRTY_TILE_FULL_LIMIT,
+  EMPTY_DIRTY_RECTS,
+  EventHandler,
+  MAX_MARCHING_ANT_CACHE_ENTRIES,
+  MAX_MARCHING_ANT_FAST_PERIMETER,
+  MAX_MARCHING_ANT_PATTERN_CACHE_ENTRIES,
+  MAX_NEAREST_COORD_CACHE_ENTRIES,
+  MAX_SCALED_VARIANTS_PER_FRAME,
+  __test__,
+  cyrb53,
+  drawDashedRect,
+  drawMarchingAntRect,
+  frameOpaqueCache,
+  getClippedDestinationSpan,
+  getMarchingAntPaintPattern,
+  getMarchingAntPerimeterOffsets,
+  getNearestCoordinateMap,
+  getScaledFrameVariant,
+  hqxScale,
+  initHqx,
+  isFrameFullyOpaque,
+  marchingAntPatternCache,
+  marchingAntPerimeterCache,
+  nearestCoordinateCache,
+  scaleHqx,
+  scaleImage,
+  scaleNearest,
+  scaleXbrz,
+  scaledFrameCache,
+  toUint32Source
+} from './DisplayImageShared.js';
+const displayBlitMethods = {
+  _blit(frame, posX, posY, opts) {
+    const frameOffsetX = Number.isFinite(frame?.offsetX) ? frame.offsetX : 0;
+    const frameOffsetY = Number.isFinite(frame?.offsetY) ? frame.offsetY : 0;
+    const { width: srcW, height: srcH } = frame,
+      srcBuf  = frame.getBuffer(),
+      srcMask = frame.getMask(),
+      destW   = this.imgData.width, destH = this.imgData.height,
+      baseX   = posX + frameOffsetX, baseY = posY + frameOffsetY,
+      dest32  = this.buffer32;
+
+    const {
+      nullColor32   = null,
+      checkGround   = false,
+      onlyOverwrite = false,
+      noOverwrite   = false,
+      upsideDown    = false,
+      groundMask    = null,
+      size          = null, // { width, height }
+      scaleMode     = 'nearest'
+    } = opts ?? {};
+
+    // If no scaling requested or size matches source → fall back to original fast path
+    const dstW = size?.width  ?? srcW;
+    const dstH = size?.height ?? srcH;
+    const isScaled = (dstW !== srcW) || (dstH !== srcH);
+    this.markDirtyRect(baseX, baseY, dstW, dstH);
+
+    if (!isScaled) {
+      const spanCache = frame.getSpanCache?.();
+      if (spanCache && nullColor32 === null) {
+        const { rows, bounds } = spanCache;
+        const minY = bounds ? bounds.minY : 0;
+        const maxY = bounds ? bounds.maxY : -1;
+        for (let sy = 0; sy < srcH; sy++) {
+          const sourceY = upsideDown ? srcH - sy - 1 : sy;
+          if (sourceY < minY || sourceY > maxY) continue;
+          const spans = rows[sourceY];
+          if (!spans) continue;
+          const outY = sy + baseY;
+          if (outY < 0 || outY >= destH) continue;
+          const srcRow = sourceY * srcW;
+          const destRow = outY * destW + baseX;
+          for (let i = 0; i < spans.length; i += 2) {
+            let start = spans[i];
+            let end = spans[i + 1];
+            if (baseX + start < 0) start = -baseX;
+            if (baseX + end > destW) end = destW - baseX;
+            if (end <= start) continue;
+            let srcIdx = srcRow + start;
+            let destIdx = destRow + start;
+            if (!checkGround) {
+              for (let sx = start; sx < end; sx++, srcIdx++, destIdx++) {
+                dest32[destIdx] = srcBuf[srcIdx];
+              }
+            } else {
+              for (let sx = start; sx < end; sx++, srcIdx++, destIdx++) {
+                const outX = baseX + sx;
+                const hasGround = groundMask?.hasGroundAt(outX, outY);
+                if (noOverwrite && hasGround)    continue;
+                if (onlyOverwrite && !hasGround) continue;
+                dest32[destIdx] = srcBuf[srcIdx];
+              }
+            }
+          }
+        }
+        return;
+      }
+
+      const fullyInBounds =
+          !checkGround &&
+          nullColor32 === null &&
+          baseX >= 0 &&
+          baseY >= 0 &&
+          (baseX + srcW) <= destW &&
+          (baseY + srcH) <= destH;
+      if (fullyInBounds) {
+        if (isFrameFullyOpaque(frame)) {
+          for (let sy = 0; sy < srcH; sy += 1) {
+            const sourceY = upsideDown ? srcH - sy - 1 : sy;
+            const srcStart = sourceY * srcW;
+            const destStart = (sy + baseY) * destW + baseX;
+            dest32.set(srcBuf.subarray(srcStart, srcStart + srcW), destStart);
+          }
+          return;
+        }
+        for (let sy = 0; sy < srcH; sy += 1) {
+          const sourceY = upsideDown ? srcH - sy - 1 : sy;
+          let srcRow = sourceY * srcW;
+          let destRow = (sy + baseY) * destW + baseX;
+          for (let sx = 0; sx < srcW; sx += 1, srcRow += 1, destRow += 1) {
+            if (!srcMask[srcRow]) continue;
+            dest32[destRow] = srcBuf[srcRow];
+          }
+        }
+        return;
+      }
+
+      let srcXStart = 0;
+      if (baseX < 0) srcXStart = -baseX;
+      let srcXEnd = srcW;
+      const maxRight = destW - baseX;
+      if (srcXEnd > maxRight) srcXEnd = maxRight;
+      if (srcXEnd <= srcXStart) return;
+
+      for (let sy = 0; sy < srcH; sy++) {
+        const sourceY = upsideDown ? srcH - sy - 1 : sy;
+        const outY = sy + baseY;
+        if (outY < 0 || outY >= destH) continue;
+        let srcRow  = (sourceY * srcW) + srcXStart;
+        let destRow = outY * destW + baseX + srcXStart;
+        for (let sx = srcXStart; sx < srcXEnd; sx++, srcRow++, destRow++) {
+          if (!srcMask[srcRow]) {
+            if (nullColor32 !== null) dest32[destRow] = nullColor32; // covered variant
+            continue;
+          }
+          if (checkGround) {
+            const hasGround = groundMask?.hasGroundAt(baseX + sx, outY);
+            if (noOverwrite && hasGround)    continue;
+            if (onlyOverwrite && !hasGround) continue;
+          }
+          dest32[destRow] = srcBuf[srcRow];
+        }
+      }
+      return;
+    }
+
+    // Scaled path – choose algorithm
+    const scaleOpts = {
+      dest32,
+      destW,
+      destH,
+      baseX,
+      baseY,
+      nullColor32,
+      checkGround,
+      onlyOverwrite,
+      noOverwrite,
+      upsideDown,
+      groundMask
+    };
+
+    if (scaleMode === 'xbrz') {
+      scaleXbrz(frame, dstW, dstH, scaleOpts);
+    } else if (scaleMode === 'hqx') {
+      scaleHqx(frame, dstW, dstH, scaleOpts);
+    } else {
+      scaleNearest(frame, dstW, dstH, scaleOpts);
+    }
+  },
+
+  drawFrame(frame, x, y,) {
+    this._blit(frame, x, y);
+  },
+
+  drawFrameCovered(frame, x, y, r, g, b) {
+    const nullColor32 = 0xFF000000 | (b & 0xFF) << 16 | (g & 0xFF) << 8 | (r & 0xFF);
+    this._blit(frame, x, y, { nullColor32 });
+  },
+
+  drawFrameFlags(frame, x, y, cfg) {
+    this._blit(frame, x, y, {
+      checkGround:   true,
+      onlyOverwrite: cfg.onlyOverwrite,
+      noOverwrite:   cfg.noOverwrite,
+      upsideDown:    cfg.isUpsideDown,
+      groundMask:    this.groundMask
+    });
+  },
+
+  drawFrameResized(frame, x, y, w, h) {
+    this._blit(frame, x, y, {
+      size: {width: w, height: h}
+    });
+  },
+
+  setDebugPixel(x, y) { if (this.buffer32) this.buffer32[y * this.imgData.width + x] = 0xFF0000FF; },
+
+  setPixel(x,y,r,g,b) {
+    if (!this.buffer32) return;
+    this.buffer32[y * this.imgData.width + x] = 0xFF000000 | (b&0xFF)<<16 | (g&0xFF)<<8 | (r&0xFF);
+  },
+
+  setScreenPosition(x, y, options) {
+    this.stage.setGameViewPointPosition(x, y, options);
+  },
+
+  getImageData()         { return this.imgData;  },
+
+  redraw()               { this.stage.redraw();   },
+
+  dispose() {
+    this.onMouseUp.dispose();
+    this.onMouseDown.dispose();
+    this.onMouseRightDown.dispose();
+    this.onMouseRightUp.dispose();
+    this.onMouseMove.dispose();
+    this.onDoubleClick.dispose();
+    this.buffer32 = null;
+    this.background32 = null;
+    this.imgData = null;
+    this.stage = null;
+    this._hasBackground = false;
+    this._restoreFull = false;
+    this._restoreRects.length = 0;
+    this._dirtyRectListPool.length = 0;
+    this._dynamicDirtyFull = false;
+    this._dynamicDirtyRects.length = 0;
+  }
+};
+export { displayBlitMethods };
\ No newline at end of file
diff --git a/js/render/display/DisplayDirtyTracking.js b/js/render/display/DisplayDirtyTracking.js
new file mode 100644
index 00000000..31550592
--- /dev/null
+++ b/js/render/display/DisplayDirtyTracking.js
@@ -0,0 +1,420 @@
+import {
+  BaseLogger,
+  DIRTY_RECT_FULL_LIMIT,
+  DIRTY_RECT_MERGE_PAD,
+  DIRTY_TILE_FULL_LIMIT,
+  EMPTY_DIRTY_RECTS,
+  EventHandler,
+  MAX_MARCHING_ANT_CACHE_ENTRIES,
+  MAX_MARCHING_ANT_FAST_PERIMETER,
+  MAX_MARCHING_ANT_PATTERN_CACHE_ENTRIES,
+  MAX_NEAREST_COORD_CACHE_ENTRIES,
+  MAX_SCALED_VARIANTS_PER_FRAME,
+  __test__,
+  cyrb53,
+  drawDashedRect,
+  drawMarchingAntRect,
+  frameOpaqueCache,
+  getClippedDestinationSpan,
+  getMarchingAntPaintPattern,
+  getMarchingAntPerimeterOffsets,
+  getNearestCoordinateMap,
+  getScaledFrameVariant,
+  hqxScale,
+  initHqx,
+  isFrameFullyOpaque,
+  marchingAntPatternCache,
+  marchingAntPerimeterCache,
+  nearestCoordinateCache,
+  scaleHqx,
+  scaleImage,
+  scaleNearest,
+  scaleXbrz,
+  scaledFrameCache,
+  toUint32Source
+} from './DisplayImageShared.js';
+const displayDirtyTrackingMethods = {
+  getWidth()  { return this.imgData?.width  ?? 0; },
+
+  getHeight() { return this.imgData?.height ?? 0; },
+
+  get worldDataSize() {
+    return { width: this.getWidth(), height: this.getHeight() };
+  },
+
+  set worldDataSize({ width, height }) {
+    this.initSize(width, height);
+  },
+
+  initSize(width, height) {
+    if (!this.imgData || this.imgData.width !== width || this.imgData.height !== height) {
+      this.imgData  = this.stage.createImage(this, width, height);
+      // Single 32‑bit view that aliases the same buffer – no copying.
+      this.buffer32 = new Uint32Array(this.imgData.data.buffer);
+      this.background32 = new Uint32Array(width * height);
+      this._hasBackground = false;
+      this._restoreFull = false;
+      this._restoreRects.length = 0;
+      this._dirtyRectListPool.length = 0;
+      this._dirtyTileListPool.length = 0;
+      this._dirtyTiles.clear();
+      this._dirtyTileColumns = this._dirtyTileSize
+        ? Math.ceil(width / this._dirtyTileSize)
+        : 0;
+      this._dirtyTileRows = this._dirtyTileSize
+        ? Math.ceil(height / this._dirtyTileSize)
+        : 0;
+      this._dirtyTileFull = true;
+      this._dynamicDirtyFull = false;
+      this._dynamicDirtyRects.length = 0;
+      this.clear();
+    }
+  },
+
+  clear(color = 0xFF00FF00) {
+    this.buffer32?.fill(color);
+    this.markDirtyAll();
+  },
+
+  setBackground(groundImage, groundMask = null) {
+    this.syncBackground(groundImage, groundMask, null);
+  },
+
+  hasBackground() {
+    return this._hasBackground === true;
+  },
+
+  setDirtyTileSize(tileSize) {
+    const next = Number.isFinite(tileSize) && tileSize > 0
+      ? Math.max(1, Math.trunc(tileSize))
+      : 0;
+    if (next === this._dirtyTileSize) return;
+    this._dirtyTileSize = next;
+    const width = this.getWidth();
+    const height = this.getHeight();
+    this._dirtyTileColumns = next ? Math.ceil(width / next) : 0;
+    this._dirtyTileRows = next ? Math.ceil(height / next) : 0;
+    this._dirtyTiles.clear();
+    this._dirtyTileListPool.length = 0;
+    this._dirtyTileFull = this._dirtyFull || this._dirtyRects.length > 0;
+  },
+
+  syncBackground(groundImage, groundMask = null, dirtyRects = null, tileSize = undefined) {
+    if (tileSize !== undefined) {
+      this.setDirtyTileSize(tileSize);
+    }
+    const source32 = toUint32Source(groundImage);
+    if (!source32) {
+      this.log.log('error: setBackground fallback');
+      this.groundMask = groundMask;
+      this.markDirtyAll({ captureDynamic: false });
+      return;
+    }
+    if (!this.buffer32) return;
+    if (!this.background32 || this.background32.length !== this.buffer32.length) {
+      this.background32 = new Uint32Array(this.buffer32.length);
+      this._hasBackground = false;
+    }
+    const applyFull = dirtyRects === null || !this._hasBackground;
+    if (applyFull) {
+      this.background32.set(source32);
+      this.buffer32.set(source32);
+      this.groundMask = groundMask;
+      this._hasBackground = true;
+      this._restoreFull = false;
+      this._restoreRects.length = 0;
+      this.markDirtyAll({ captureDynamic: false });
+      return;
+    }
+    if (!Array.isArray(dirtyRects) || dirtyRects.length < 1) {
+      this.groundMask = groundMask;
+      return;
+    }
+    for (let i = 0; i < dirtyRects.length; i += 1) {
+      const rect = this._normalizeRect(
+        dirtyRects[i]?.x,
+        dirtyRects[i]?.y,
+        dirtyRects[i]?.width,
+        dirtyRects[i]?.height
+      );
+      if (!rect) continue;
+      this._copyRect(this.background32, source32, rect);
+      this._copyRect(this.buffer32, this.background32, rect);
+      this.markPresentDirtyRect(rect.x, rect.y, rect.width, rect.height);
+    }
+    this.groundMask = groundMask;
+    this._hasBackground = true;
+  },
+
+  restoreBackground() {
+    if (!this._hasBackground || !this.buffer32 || !this.background32) return;
+    if (this._restoreFull) {
+      this.buffer32.set(this.background32);
+      this._restoreFull = false;
+      this._restoreRects.length = 0;
+      this.markDirtyAll({ captureDynamic: false });
+      return;
+    }
+    if (!this._restoreRects.length) return;
+    for (let i = 0; i < this._restoreRects.length; i += 1) {
+      const rect = this._restoreRects[i];
+      this._copyRect(this.buffer32, this.background32, rect);
+      this.markPresentDirtyRect(rect.x, rect.y, rect.width, rect.height);
+    }
+    this._restoreRects.length = 0;
+  },
+
+  commitFrameForBackgroundRestore() {
+    if (!this._hasBackground) {
+      this._dynamicDirtyFull = false;
+      this._dynamicDirtyRects.length = 0;
+      return;
+    }
+    this._restoreFull = this._dynamicDirtyFull === true;
+    if (this._restoreFull) {
+      this._restoreRects.length = 0;
+    } else {
+      const previousRestoreRects = this._restoreRects;
+      this._restoreRects = this._dynamicDirtyRects;
+      this._dynamicDirtyRects = previousRestoreRects;
+      this._dynamicDirtyRects.length = 0;
+    }
+    this._dynamicDirtyFull = false;
+    if (this._restoreFull) {
+      this._dynamicDirtyRects.length = 0;
+    }
+  },
+
+  _acquireRectList() {
+    if (this._dirtyRectListPool.length > 0) {
+      const rects = this._dirtyRectListPool.pop();
+      rects.length = 0;
+      this._allocationStats.rectListReused += 1;
+      return rects;
+    }
+    this._allocationStats.rectListCreated += 1;
+    return [];
+  },
+
+  _acquireTileList() {
+    if (this._dirtyTileListPool.length > 0) {
+      const tiles = this._dirtyTileListPool.pop();
+      tiles.length = 0;
+      this._allocationStats.tileListReused += 1;
+      return tiles;
+    }
+    this._allocationStats.tileListCreated += 1;
+    return [];
+  },
+
+  _markTileDirtyRect(rect) {
+    if (!rect || !this._dirtyTileSize || this._dirtyTileFull) return;
+    const cols = this._dirtyTileColumns;
+    const rows = this._dirtyTileRows;
+    if (!cols || !rows) return;
+    const tileSize = this._dirtyTileSize;
+    const tx1 = Math.max(0, Math.floor(rect.x / tileSize));
+    const ty1 = Math.max(0, Math.floor(rect.y / tileSize));
+    const tx2 = Math.min(cols - 1, Math.floor((rect.x + rect.width - 1) / tileSize));
+    const ty2 = Math.min(rows - 1, Math.floor((rect.y + rect.height - 1) / tileSize));
+    for (let ty = ty1; ty <= ty2; ty += 1) {
+      const row = ty * cols;
+      for (let tx = tx1; tx <= tx2; tx += 1) {
+        this._dirtyTiles.add(row + tx);
+      }
+    }
+    if (this._dirtyTiles.size >= (cols * rows) || this._dirtyTiles.size > DIRTY_TILE_FULL_LIMIT) {
+      this._dirtyTiles.clear();
+      this._dirtyTileFull = true;
+    }
+  },
+
+  markDirtyAll({ captureDynamic = true } = {}) {
+    this._dirtyFull = true;
+    this._dirtyRects.length = 0;
+    this._dirtyTileFull = true;
+    this._dirtyTiles.clear();
+    if (captureDynamic) {
+      this._dynamicDirtyFull = true;
+      this._dynamicDirtyRects.length = 0;
+    }
+  },
+
+  _normalizeRect(x, y, width, height) {
+    if (!Number.isFinite(width) || !Number.isFinite(height)) {
+      return null;
+    }
+    if (width <= 0 || height <= 0) return null;
+    const w = this.getWidth();
+    const h = this.getHeight();
+    if (!w || !h) return null;
+    const x1 = Math.max(0, Math.floor(x));
+    const y1 = Math.max(0, Math.floor(y));
+    const x2 = Math.min(w, Math.ceil(x + width));
+    const y2 = Math.min(h, Math.ceil(y + height));
+    if (x2 <= x1 || y2 <= y1) return null;
+    return {
+      x: x1,
+      y: y1,
+      width: x2 - x1,
+      height: y2 - y1
+    };
+  },
+
+  _copyRect(dest32, source32, rect) {
+    if (!dest32 || !source32 || !rect) return;
+    const w = this.getWidth();
+    for (let row = 0; row < rect.height; row += 1) {
+      const offset = (rect.y + row) * w + rect.x;
+      const end = offset + rect.width;
+      dest32.set(source32.subarray(offset, end), offset);
+    }
+  },
+
+  _mergeDirtyRect(rect, fullProp, rectsProp) {
+    if (!rect) return;
+    if (this[fullProp]) return;
+    const w = this.getWidth();
+    const h = this.getHeight();
+    let mergedX1 = rect.x;
+    let mergedY1 = rect.y;
+    let mergedX2 = rect.x + rect.width;
+    let mergedY2 = rect.y + rect.height;
+    const rects = this[rectsProp];
+    for (let i = 0; i < rects.length;) {
+      const rect = rects[i];
+      const rectX1 = rect.x;
+      const rectY1 = rect.y;
+      const rectX2 = rect.x + rect.width;
+      const rectY2 = rect.y + rect.height;
+      const overlapsOrTouches =
+          mergedX1 <= (rectX2 + DIRTY_RECT_MERGE_PAD) &&
+          mergedX2 >= (rectX1 - DIRTY_RECT_MERGE_PAD) &&
+          mergedY1 <= (rectY2 + DIRTY_RECT_MERGE_PAD) &&
+          mergedY2 >= (rectY1 - DIRTY_RECT_MERGE_PAD);
+      if (!overlapsOrTouches) {
+        i += 1;
+        continue;
+      }
+      mergedX1 = Math.min(mergedX1, rectX1);
+      mergedY1 = Math.min(mergedY1, rectY1);
+      mergedX2 = Math.max(mergedX2, rectX2);
+      mergedY2 = Math.max(mergedY2, rectY2);
+      const last = rects.length - 1;
+      rects[i] = rects[last];
+      rects.length = last;
+    }
+    if (mergedX1 === 0 && mergedY1 === 0 && mergedX2 === w && mergedY2 === h) {
+      this[fullProp] = true;
+      rects.length = 0;
+      return;
+    }
+    rects.push({
+      x: mergedX1,
+      y: mergedY1,
+      width: mergedX2 - mergedX1,
+      height: mergedY2 - mergedY1
+    });
+    if (rects.length > DIRTY_RECT_FULL_LIMIT) {
+      this[fullProp] = true;
+      rects.length = 0;
+    }
+  },
+
+  markPresentDirtyRect(x, y, width, height) {
+    const rect = this._normalizeRect(x, y, width, height);
+    this._markTileDirtyRect(rect);
+    this._mergeDirtyRect(rect, '_dirtyFull', '_dirtyRects');
+  },
+
+  markDirtyRect(x, y, width, height) {
+    const rect = this._normalizeRect(x, y, width, height);
+    if (!rect) {
+      if (!Number.isFinite(width) || !Number.isFinite(height)) {
+        this.markDirtyAll();
+      }
+      return;
+    }
+    this._markTileDirtyRect(rect);
+    this._mergeDirtyRect(rect, '_dirtyFull', '_dirtyRects');
+    this._mergeDirtyRect(rect, '_dynamicDirtyFull', '_dynamicDirtyRects');
+  },
+
+  consumeDirtyTiles() {
+    if (!this._dirtyTileSize || !this.imgData) return undefined;
+    if (this._dirtyTileFull) {
+      this._dirtyTileFull = false;
+      this._dirtyTiles.clear();
+      return null;
+    }
+    if (!this._dirtyTiles.size) return EMPTY_DIRTY_RECTS;
+    const cols = this._dirtyTileColumns;
+    const tileSize = this._dirtyTileSize;
+    const width = this.getWidth();
+    const height = this.getHeight();
+    const tiles = this._acquireTileList();
+    for (const index of this._dirtyTiles) {
+      const tx = index % cols;
+      const ty = Math.floor(index / cols);
+      const x = tx * tileSize;
+      const y = ty * tileSize;
+      tiles.push({
+        x,
+        y,
+        width: Math.min(tileSize, width - x),
+        height: Math.min(tileSize, height - y)
+      });
+    }
+    this._dirtyTiles.clear();
+    return tiles;
+  },
+
+  releaseConsumedDirtyTiles(tiles) {
+    if (!Array.isArray(tiles) || tiles === EMPTY_DIRTY_RECTS || tiles === this._dirtyRects) {
+      return;
+    }
+    tiles.length = 0;
+    if (this._dirtyTileListPool.length < 4) {
+      this._dirtyTileListPool.push(tiles);
+    }
+  },
+
+  consumeDirtyRects() {
+    if (this._dirtyFull || !this.imgData) {
+      this._dirtyFull = false;
+      this._dirtyRects.length = 0;
+      return null;
+    }
+    if (!this._dirtyRects.length) return EMPTY_DIRTY_RECTS;
+    const rects = this._dirtyRects;
+    this._dirtyRects = this._acquireRectList();
+    return rects;
+  },
+
+  releaseConsumedDirtyRects(rects) {
+    if (!Array.isArray(rects) || rects === EMPTY_DIRTY_RECTS || rects === this._dirtyRects) {
+      return;
+    }
+    rects.length = 0;
+    if (this._dirtyRectListPool.length < 4) {
+      this._dirtyRectListPool.push(rects);
+    }
+  },
+
+  hasPendingDirty() {
+    if (!this.imgData) return false;
+    return this._dirtyFull || this._dirtyRects.length > 0;
+  },
+
+  consumeAllocationStats(reset = false) {
+    const stats = { ...this._allocationStats };
+    if (reset) {
+      this._allocationStats.rectListCreated = 0;
+      this._allocationStats.rectListReused = 0;
+      this._allocationStats.tileListCreated = 0;
+      this._allocationStats.tileListReused = 0;
+    }
+    return stats;
+  }
+};
+export { displayDirtyTrackingMethods };
\ No newline at end of file
diff --git a/js/render/display/DisplayImageCore.js b/js/render/display/DisplayImageCore.js
new file mode 100644
index 00000000..01efaf32
--- /dev/null
+++ b/js/render/display/DisplayImageCore.js
@@ -0,0 +1,85 @@
+import {
+  BaseLogger,
+  DIRTY_RECT_FULL_LIMIT,
+  DIRTY_RECT_MERGE_PAD,
+  DIRTY_TILE_FULL_LIMIT,
+  EMPTY_DIRTY_RECTS,
+  EventHandler,
+  MAX_MARCHING_ANT_CACHE_ENTRIES,
+  MAX_MARCHING_ANT_FAST_PERIMETER,
+  MAX_MARCHING_ANT_PATTERN_CACHE_ENTRIES,
+  MAX_NEAREST_COORD_CACHE_ENTRIES,
+  MAX_SCALED_VARIANTS_PER_FRAME,
+  __test__,
+  cyrb53,
+  drawDashedRect,
+  drawMarchingAntRect,
+  frameOpaqueCache,
+  getClippedDestinationSpan,
+  getMarchingAntPaintPattern,
+  getMarchingAntPerimeterOffsets,
+  getNearestCoordinateMap,
+  getScaledFrameVariant,
+  hqxScale,
+  initHqx,
+  isFrameFullyOpaque,
+  marchingAntPatternCache,
+  marchingAntPerimeterCache,
+  nearestCoordinateCache,
+  scaleHqx,
+  scaleImage,
+  scaleNearest,
+  scaleXbrz,
+  scaledFrameCache,
+  toUint32Source
+} from './DisplayImageShared.js';
+import { displayDirtyTrackingMethods } from './DisplayDirtyTracking.js';
+import { displayPrimitivesMethods } from './DisplayPrimitives.js';
+import { displayBlitMethods } from './DisplayBlit.js';
+class DisplayImage extends BaseLogger {
+  constructor(stage) {
+    super();
+    this.stage = stage;
+    this.onMouseUp = new EventHandler();
+    this.onMouseDown = new EventHandler();
+    this.onMouseRightDown = new EventHandler();
+    this.onMouseRightUp = new EventHandler();
+    this.onMouseMove = new EventHandler();
+    this.onDoubleClick = new EventHandler();
+    // 32‑bit view reused everywhere; set by initSize()
+    this.buffer32 = null;
+    this.background32 = null;
+    this._hasBackground = false;
+    this._dirtyFull = true;
+    this._dirtyRects = [];
+    this._dirtyRectListPool = [];
+    this._dirtyTileSize = 0;
+    this._dirtyTileColumns = 0;
+    this._dirtyTileRows = 0;
+    this._dirtyTileFull = true;
+    this._dirtyTiles = new Set();
+    this._dirtyTileListPool = [];
+    this._allocationStats = {
+      rectListCreated: 0,
+      rectListReused: 0,
+      tileListCreated: 0,
+      tileListReused: 0
+    };
+    this._dynamicDirtyFull = false;
+    this._dynamicDirtyRects = [];
+    this._restoreFull = false;
+    this._restoreRects = [];
+    // this.onMouseDown.on(e => {
+    //     // this.setDebugPixel(e.x, e.y);
+    // });
+    this.imgData = null;
+  }
+}
+for (const methods of [
+  displayDirtyTrackingMethods,
+  displayPrimitivesMethods,
+  displayBlitMethods
+]) {
+  Object.defineProperties(DisplayImage.prototype, Object.getOwnPropertyDescriptors(methods));
+}
+export { DisplayImage };
\ No newline at end of file
diff --git a/js/render/display/DisplayImageShared.js b/js/render/display/DisplayImageShared.js
new file mode 100644
index 00000000..ef9d8e4d
--- /dev/null
+++ b/js/render/display/DisplayImageShared.js
@@ -0,0 +1,573 @@
+import { BaseLogger } from '../../util/LogHandler.js';
+import { EventHandler } from '../../util/EventHandler.js';
+import { scaleImage } from '../../xbrz/xbrz.js';
+import { hqxScale, initHqx } from '../../vendor/hqx/index.js';
+
+initHqx();
+const cyrb53 = (str, seed = 0) => {
+  let h1 = 0xdeadbeef ^ seed, h2 = 0x41c6ce57 ^ seed;
+  for(let i = 0, ch; i < str.length; i++) {
+    ch = str.charCodeAt(i);
+    h1 = Math.imul(h1 ^ ch, 2654435761);
+    h2 = Math.imul(h2 ^ ch, 1597334677);
+  }
+  h1  = Math.imul(h1 ^ (h1 >>> 16), 2246822507);
+  h1 ^= Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+  h2  = Math.imul(h2 ^ (h2 >>> 16), 2246822507);
+  h2 ^= Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+
+  return 4294967296 * (2097151 & h2) + (h1 >>> 0);
+};
+const scaledFrameCache = new WeakMap();
+const frameOpaqueCache = new WeakMap();
+const MAX_SCALED_VARIANTS_PER_FRAME = 8;
+const marchingAntPerimeterCache = new Map();
+const marchingAntPatternCache = new Map();
+const MAX_MARCHING_ANT_CACHE_ENTRIES = 256;
+const MAX_MARCHING_ANT_PATTERN_CACHE_ENTRIES = 1024;
+const MAX_MARCHING_ANT_FAST_PERIMETER = 2048;
+const MAX_NEAREST_COORD_CACHE_ENTRIES = 256;
+const DIRTY_RECT_MERGE_PAD = 1;
+const DIRTY_RECT_FULL_LIMIT = 96;
+const DIRTY_TILE_FULL_LIMIT = 1024;
+const EMPTY_DIRTY_RECTS = Object.freeze([]);
+const nearestCoordinateCache = new Map();
+const toUint32Source = (source) => {
+  if (source instanceof Uint32Array) return source;
+  if (source instanceof Uint8ClampedArray || source instanceof Uint8Array) {
+    return new Uint32Array(source.buffer, source.byteOffset, source.byteLength >>> 2);
+  }
+  return null;
+};
+const getMarchingAntPerimeterOffsets = (stride, width, height) => {
+  const key = `${stride}:${width}:${height}`;
+  const cached = marchingAntPerimeterCache.get(key);
+  if (cached) return cached;
+
+  const total = (width + 1) + height + width + Math.max(0, height - 1);
+  const offsets = new Int32Array(total);
+  let i = 0;
+
+  for (let dx = 0; dx <= width; dx += 1) {
+    offsets[i++] = dx;
+  }
+  for (let dy = 1; dy <= height; dy += 1) {
+    offsets[i++] = (dy * stride) + width;
+  }
+  for (let dx = 1; dx <= width; dx += 1) {
+    offsets[i++] = (height * stride) + width - dx;
+  }
+  for (let dy = 1; dy < height; dy += 1) {
+    offsets[i++] = ((height - dy) * stride);
+  }
+
+  if (marchingAntPerimeterCache.size >= MAX_MARCHING_ANT_CACHE_ENTRIES) {
+    marchingAntPerimeterCache.clear();
+  }
+  marchingAntPerimeterCache.set(key, offsets);
+  return offsets;
+};
+const getMarchingAntPaintPattern = (perimeterLen, dashLen, offset) => {
+  const pattern = dashLen * 2;
+  const phase = ((offset % pattern) + pattern) % pattern;
+  const key = `${perimeterLen}:${dashLen}:${phase}`;
+  const cached = marchingAntPatternCache.get(key);
+  if (cached) return cached;
+
+  const first = [];
+  const second = [];
+  for (let i = 0; i < perimeterLen; i += 1) {
+    const pos = (phase + i) % pattern;
+    if (pos < dashLen) first.push(i);
+    else second.push(i);
+  }
+
+  const result = {
+    first: Int32Array.from(first),
+    second: Int32Array.from(second)
+  };
+
+  if (marchingAntPatternCache.size >= MAX_MARCHING_ANT_PATTERN_CACHE_ENTRIES) {
+    marchingAntPatternCache.clear();
+  }
+  marchingAntPatternCache.set(key, result);
+  return result;
+};
+const isFrameFullyOpaque = (frame) => {
+  if (!frame) return false;
+  const version = Number.isFinite(frame._version) ? frame._version : 0;
+  const cached = frameOpaqueCache.get(frame);
+  if (cached && cached.version === version) {
+    return cached.opaque === true;
+  }
+  const mask = frame.getMask();
+  let opaque = true;
+  for (let i = 0; i < mask.length; i += 1) {
+    if (!mask[i]) {
+      opaque = false;
+      break;
+    }
+  }
+  frameOpaqueCache.set(frame, { version, opaque });
+  return opaque;
+};
+function getScaledFrameVariant(frame, dstWidth, dstHeight, mode) {
+  if (!frame) return null;
+  const srcW = frame.width | 0;
+  const srcH = frame.height | 0;
+  if (!srcW || !srcH || !dstWidth || !dstHeight) return null;
+  const scale = Math.round(dstWidth / srcW);
+  if (scale < 2 || scale > 4 || dstWidth !== srcW * scale || dstHeight !== srcH * scale) {
+    return null;
+  }
+
+  const version = Number.isFinite(frame._version) ? frame._version : 0;
+  const key = `${mode}:${dstWidth}x${dstHeight}:v${version}`;
+  let variants = scaledFrameCache.get(frame);
+  if (!variants) {
+    variants = new Map();
+    scaledFrameCache.set(frame, variants);
+  } else if (variants.has(key)) {
+    const cached = variants.get(key);
+    // True LRU: reads promote the entry so hot scale variants stay resident.
+    variants.delete(key);
+    variants.set(key, cached);
+    return cached;
+  }
+
+  const srcBuf = frame.getBuffer();
+  const srcMask = frame.getMask();
+  const maskLen = srcMask.length;
+  const opaqueSrc = new Uint32Array(maskLen);
+  for (let i = 0; i < maskLen; i++) {
+    opaqueSrc[i] = srcMask[i] ? srcBuf[i] : 0;
+  }
+
+  const scaledMask = new Uint8Array(dstWidth * dstHeight);
+  for (let dy = 0; dy < dstHeight; dy++) {
+    const sy = Math.floor(dy / scale);
+    const srcRow = sy * srcW;
+    const dstRow = dy * dstWidth;
+    for (let dx = 0; dx < dstWidth; dx++) {
+      const sx = Math.floor(dx / scale);
+      scaledMask[dstRow + dx] = srcMask[srcRow + sx];
+    }
+  }
+
+  const scaled = mode === 'hqx'
+    ? hqxScale(opaqueSrc, srcW, srcH, scale)
+    : (() => {
+      const out = new Uint32Array(dstWidth * dstHeight);
+      scaleImage(scale, opaqueSrc, out, srcW, srcH, 0, srcH);
+      return out;
+    })();
+
+  const variant = { scaled, scaledMask };
+  if (!variants.has(key) && variants.size >= MAX_SCALED_VARIANTS_PER_FRAME) {
+    const firstKey = variants.keys().next().value;
+    variants.delete(firstKey);
+  }
+  variants.set(key, variant);
+  return variant;
+}
+function getNearestCoordinateMap(srcLength, dstLength) {
+  if (!Number.isFinite(srcLength) || !Number.isFinite(dstLength)) return null;
+  const src = Math.trunc(srcLength);
+  const dst = Math.trunc(dstLength);
+  if (src < 1 || dst < 1) return null;
+  const key = `${src}:${dst}`;
+  const cached = nearestCoordinateCache.get(key);
+  if (cached) {
+    nearestCoordinateCache.delete(key);
+    nearestCoordinateCache.set(key, cached);
+    return cached;
+  }
+
+  const ratio = src / dst;
+  const map = new Int32Array(dst);
+  for (let i = 0; i < dst; i += 1) {
+    map[i] = Math.floor(i * ratio);
+  }
+
+  if (nearestCoordinateCache.size >= MAX_NEAREST_COORD_CACHE_ENTRIES) {
+    const oldestKey = nearestCoordinateCache.keys().next().value;
+    nearestCoordinateCache.delete(oldestKey);
+  }
+  nearestCoordinateCache.set(key, map);
+  return map;
+}
+function getClippedDestinationSpan(destW, destH, baseX, baseY, width, height) {
+  const x1 = Math.max(0, -baseX);
+  const y1 = Math.max(0, -baseY);
+  const x2 = Math.min(width, destW - baseX);
+  const y2 = Math.min(height, destH - baseY);
+  if (x2 <= x1 || y2 <= y1) return null;
+  return { x1, y1, x2, y2 };
+}
+function scaleNearest(
+  frame,
+  dstWidth,
+  dstHeight,
+  opts = {}
+) {
+  const {
+    dest32,
+    destW,
+    destH,
+    baseX,
+    baseY,
+    nullColor32 = null,
+    checkGround = false,
+    onlyOverwrite = false,
+    noOverwrite = false,
+    upsideDown = false,
+    groundMask = null
+  } = opts;
+
+  if (!dest32) return;
+
+  const { width: srcW, height: srcH } = frame;
+  const srcBuf = frame.getBuffer();
+  const srcMask = frame.getMask();
+  const xMap = getNearestCoordinateMap(srcW, dstWidth);
+  const yMap = getNearestCoordinateMap(srcH, dstHeight);
+  if (!xMap || !yMap) return;
+  const span = getClippedDestinationSpan(destW, destH, baseX, baseY, dstWidth, dstHeight);
+  if (!span) return;
+
+  const { x1, y1, x2, y2 } = span;
+  for (let dy = y1; dy < y2; dy += 1) {
+    const mapY = upsideDown ? (dstHeight - 1 - dy) : dy;
+    const srcRowBase = yMap[mapY] * srcW;
+    const outY = dy + baseY;
+    let destIdx = (outY * destW) + baseX + x1;
+    let outX = baseX + x1;
+
+    for (let dx = x1; dx < x2; dx += 1, destIdx += 1, outX += 1) {
+      const srcIdx = srcRowBase + xMap[dx];
+      if (!srcMask[srcIdx]) {
+        if (nullColor32 !== null) dest32[destIdx] = nullColor32;
+        continue;
+      }
+
+      if (checkGround) {
+        const hasGround = groundMask?.hasGroundAt(outX, outY);
+        if (noOverwrite && hasGround) continue;
+        if (onlyOverwrite && !hasGround) continue;
+      }
+
+      dest32[destIdx] = srcBuf[srcIdx];
+    }
+  }
+}
+function scaleXbrz(
+  frame,
+  dstWidth,
+  dstHeight,
+  opts = {}
+) {
+  const {
+    dest32,
+    destW,
+    destH,
+    baseX,
+    baseY,
+    nullColor32 = null,
+    checkGround = false,
+    onlyOverwrite = false,
+    noOverwrite = false,
+    upsideDown = false,
+    groundMask = null
+  } = opts;
+
+  if (!dest32) return;
+
+  const { width: srcW, height: srcH } = frame;
+  const scale = Math.round(dstWidth / srcW);
+  if (scale < 2 || scale > 4 || dstWidth !== srcW * scale || dstHeight !== srcH * scale) {
+    scaleNearest(frame, dstWidth, dstHeight, opts);
+    return;
+  }
+
+  const variant = getScaledFrameVariant(frame, dstWidth, dstHeight, 'xbrz');
+  if (!variant) {
+    scaleNearest(frame, dstWidth, dstHeight, opts);
+    return;
+  }
+  const { scaled, scaledMask } = variant;
+  const span = getClippedDestinationSpan(destW, destH, baseX, baseY, dstWidth, dstHeight);
+  if (!span) return;
+  const { x1, y1, x2, y2 } = span;
+  for (let dy = y1; dy < y2; dy += 1) {
+    const srcY = upsideDown ? (dstHeight - 1 - dy) : dy;
+    let srcIdx = (srcY * dstWidth) + x1;
+    const outY = dy + baseY;
+    let destIdx = (outY * destW) + baseX + x1;
+    let outX = baseX + x1;
+    for (let dx = x1; dx < x2; dx += 1, srcIdx += 1, destIdx += 1, outX += 1) {
+      if (!scaledMask[srcIdx]) {
+        if (nullColor32 !== null) dest32[destIdx] = nullColor32;
+        continue;
+      }
+
+      if (checkGround) {
+        const hasGround = groundMask?.hasGroundAt(outX, outY);
+        if (noOverwrite && hasGround) continue;
+        if (onlyOverwrite && !hasGround) continue;
+      }
+
+      dest32[destIdx] = scaled[srcIdx];
+    }
+  }
+}
+function scaleHqx(
+  frame,
+  dstWidth,
+  dstHeight,
+  opts = {}
+) {
+  const {
+    dest32,
+    destW,
+    destH,
+    baseX,
+    baseY,
+    nullColor32 = null,
+    checkGround = false,
+    onlyOverwrite = false,
+    noOverwrite = false,
+    upsideDown = false,
+    groundMask = null
+  } = opts;
+
+  if (!dest32) return;
+
+  const { width: srcW, height: srcH } = frame;
+  const scale = Math.round(dstWidth / srcW);
+  if (scale < 2 || scale > 4 || dstWidth !== srcW * scale || dstHeight !== srcH * scale) {
+    scaleNearest(frame, dstWidth, dstHeight, opts);
+    return;
+  }
+
+  const variant = getScaledFrameVariant(frame, dstWidth, dstHeight, 'hqx');
+  if (!variant) {
+    scaleNearest(frame, dstWidth, dstHeight, opts);
+    return;
+  }
+  const { scaled, scaledMask } = variant;
+  const span = getClippedDestinationSpan(destW, destH, baseX, baseY, dstWidth, dstHeight);
+  if (!span) return;
+  const { x1, y1, x2, y2 } = span;
+  for (let dy = y1; dy < y2; dy += 1) {
+    const srcY = upsideDown ? (dstHeight - 1 - dy) : dy;
+    let srcIdx = (srcY * dstWidth) + x1;
+    const outY = dy + baseY;
+    let destIdx = (outY * destW) + baseX + x1;
+    let outX = baseX + x1;
+    for (let dx = x1; dx < x2; dx += 1, srcIdx += 1, destIdx += 1, outX += 1) {
+      if (!scaledMask[srcIdx]) {
+        if (nullColor32 !== null) dest32[destIdx] = nullColor32;
+        continue;
+      }
+
+      if (checkGround) {
+        const hasGround = groundMask?.hasGroundAt(outX, outY);
+        if (noOverwrite && hasGround) continue;
+        if (onlyOverwrite && !hasGround) continue;
+      }
+
+      dest32[destIdx] = scaled[srcIdx];
+    }
+  }
+}
+function drawMarchingAntRect(
+  display,
+  x,
+  y,
+  width,
+  height,
+  dashLen = 3,
+  offset = 0,
+  color1 = 0xFFFFFFFF,
+  color2 = 0xFF000000
+) {
+  if (!display?.buffer32) return;
+  x = Math.trunc(x);
+  y = Math.trunc(y);
+  width = Math.trunc(width);
+  height = Math.trunc(height);
+  if (width < 0 || height < 0) return;
+  if (dashLen <= 0) dashLen = 1;
+  const { width: w, height: h } = display.imgData;
+  if (!w || !h) return;
+  const buffer32 = display.buffer32;
+  const pattern = dashLen * 2;
+  const writeColor1 = (color1 >>> 24) !== 0;
+  const writeColor2 = (color2 >>> 24) !== 0;
+  if (!writeColor1 && !writeColor2) return;
+  const perimeter = (width + 1) + height + width + Math.max(0, height - 1);
+  const x2 = x + width;
+  const y2 = y + height;
+  const fullyInBounds = x >= 0 && y >= 0 && x2 < w && y2 < h;
+
+  if (fullyInBounds && perimeter <= MAX_MARCHING_ANT_FAST_PERIMETER) {
+    const baseIndex = (y * w) + x;
+    const offsets = getMarchingAntPerimeterOffsets(w, width, height);
+    const paintPattern = getMarchingAntPaintPattern(offsets.length, dashLen, offset);
+    if (writeColor1) {
+      const first = paintPattern.first;
+      for (let i = 0; i < first.length; i += 1) {
+        buffer32[baseIndex + offsets[first[i]]] = color1;
+      }
+    }
+    if (writeColor2) {
+      const second = paintPattern.second;
+      for (let i = 0; i < second.length; i += 1) {
+        buffer32[baseIndex + offsets[second[i]]] = color2;
+      }
+    }
+    return;
+  }
+
+  let pos = ((offset % pattern) + pattern) % pattern;
+  const writeAtIndex = (idx) => {
+    if (writeColor1 && writeColor2) {
+      buffer32[idx] = pos < dashLen ? color1 : color2;
+      return;
+    }
+    if (writeColor1) {
+      if (pos < dashLen) buffer32[idx] = color1;
+      return;
+    }
+    if (pos >= dashLen) {
+      buffer32[idx] = color2;
+    }
+  };
+  const advancePattern = () => {
+    pos += 1;
+    if (pos === pattern) pos = 0;
+  };
+
+  if (fullyInBounds) {
+    let idx = y * w + x;
+    for (let dx = 0; dx <= width; dx += 1, idx += 1) {
+      writeAtIndex(idx);
+      advancePattern();
+    }
+    idx = (y + 1) * w + x + width;
+    for (let dy = 1; dy <= height; dy += 1, idx += w) {
+      writeAtIndex(idx);
+      advancePattern();
+    }
+    idx = (y + height) * w + x + width - 1;
+    for (let dx = 1; dx <= width; dx += 1, idx -= 1) {
+      writeAtIndex(idx);
+      advancePattern();
+    }
+    idx = (y + height - 1) * w + x;
+    for (let dy = 1; dy < height; dy += 1, idx -= w) {
+      writeAtIndex(idx);
+      advancePattern();
+    }
+    return;
+  }
+
+  for (let dx = 0; dx <= width; dx += 1) {
+    const xx = x + dx;
+    if (y >= 0 && y < h && xx >= 0 && xx < w) {
+      writeAtIndex((y * w) + xx);
+    }
+    advancePattern();
+  }
+  for (let dy = 1; dy <= height; dy += 1) {
+    const yy = y + dy;
+    if (yy >= 0 && yy < h && x2 >= 0 && x2 < w) {
+      writeAtIndex((yy * w) + x2);
+    }
+    advancePattern();
+  }
+  for (let dx = 1; dx <= width; dx += 1) {
+    const xx = x2 - dx;
+    if (y2 >= 0 && y2 < h && xx >= 0 && xx < w) {
+      writeAtIndex((y2 * w) + xx);
+    }
+    advancePattern();
+  }
+  for (let dy = 1; dy < height; dy += 1) {
+    const yy = y2 - dy;
+    if (yy >= 0 && yy < h && x >= 0 && x < w) {
+      writeAtIndex((yy * w) + x);
+    }
+    advancePattern();
+  }
+}
+function drawDashedRect(
+  display,
+  x,
+  y,
+  width,
+  height,
+  dashLen = 3,
+  offset = 0,
+  color1 = 0xFFFFFFFF,
+  color2 = 0xFF000000
+) {
+  drawMarchingAntRect(
+    display,
+    x,
+    y,
+    width,
+    height,
+    dashLen,
+    offset,
+    color1,
+    color2
+  );
+}
+const __test__ = {
+  cyrb53,
+  getScaledFrameVariant,
+  getNearestCoordinateMap,
+  _scaledFrameCache: scaledFrameCache,
+  _nearestCoordinateCache: nearestCoordinateCache,
+  _marchingAntPerimeterCache: marchingAntPerimeterCache,
+  _marchingAntPatternCache: marchingAntPatternCache,
+  getMarchingAntPerimeterOffsets,
+  getMarchingAntPaintPattern
+};
+
+export {
+  BaseLogger,
+  DIRTY_RECT_FULL_LIMIT,
+  DIRTY_RECT_MERGE_PAD,
+  DIRTY_TILE_FULL_LIMIT,
+  EMPTY_DIRTY_RECTS,
+  EventHandler,
+  MAX_MARCHING_ANT_CACHE_ENTRIES,
+  MAX_MARCHING_ANT_FAST_PERIMETER,
+  MAX_MARCHING_ANT_PATTERN_CACHE_ENTRIES,
+  MAX_NEAREST_COORD_CACHE_ENTRIES,
+  MAX_SCALED_VARIANTS_PER_FRAME,
+  __test__,
+  cyrb53,
+  drawDashedRect,
+  drawMarchingAntRect,
+  frameOpaqueCache,
+  getClippedDestinationSpan,
+  getMarchingAntPaintPattern,
+  getMarchingAntPerimeterOffsets,
+  getNearestCoordinateMap,
+  getScaledFrameVariant,
+  hqxScale,
+  initHqx,
+  isFrameFullyOpaque,
+  marchingAntPatternCache,
+  marchingAntPerimeterCache,
+  nearestCoordinateCache,
+  scaleHqx,
+  scaleImage,
+  scaleNearest,
+  scaleXbrz,
+  scaledFrameCache,
+  toUint32Source
+};
diff --git a/js/render/display/DisplayPrimitives.js b/js/render/display/DisplayPrimitives.js
new file mode 100644
index 00000000..869b0c40
--- /dev/null
+++ b/js/render/display/DisplayPrimitives.js
@@ -0,0 +1,225 @@
+import {
+  BaseLogger,
+  DIRTY_RECT_FULL_LIMIT,
+  DIRTY_RECT_MERGE_PAD,
+  DIRTY_TILE_FULL_LIMIT,
+  EMPTY_DIRTY_RECTS,
+  EventHandler,
+  MAX_MARCHING_ANT_CACHE_ENTRIES,
+  MAX_MARCHING_ANT_FAST_PERIMETER,
+  MAX_MARCHING_ANT_PATTERN_CACHE_ENTRIES,
+  MAX_NEAREST_COORD_CACHE_ENTRIES,
+  MAX_SCALED_VARIANTS_PER_FRAME,
+  __test__,
+  cyrb53,
+  drawDashedRect,
+  drawMarchingAntRect,
+  frameOpaqueCache,
+  getClippedDestinationSpan,
+  getMarchingAntPaintPattern,
+  getMarchingAntPerimeterOffsets,
+  getNearestCoordinateMap,
+  getScaledFrameVariant,
+  hqxScale,
+  initHqx,
+  isFrameFullyOpaque,
+  marchingAntPatternCache,
+  marchingAntPerimeterCache,
+  nearestCoordinateCache,
+  scaleHqx,
+  scaleImage,
+  scaleNearest,
+  scaleXbrz,
+  scaledFrameCache,
+  toUint32Source
+} from './DisplayImageShared.js';
+const displayPrimitivesMethods = {
+  drawRect(x, y, width, height, r, g, b, filled = false) {
+    const x2 = x + width;
+    const y2 = y + height;
+    this.drawHorizontalLine(x, y,  x2, r, g, b);
+
+    if (filled) {
+      for (let i = y; i <= y+height; i++) {
+        this.drawHorizontalLine(x, i, x2, r, g, b);
+      }
+    }
+
+    this.drawHorizontalLine(x, y2, x2, r, g, b);
+    this.drawVerticalLine(  x,  y,  y2, r, g, b);
+    this.drawVerticalLine( x2,  y,  y2, r, g, b);
+  },
+
+  drawVerticalLine(x, y1, y2, r, g, b) {
+    if (!this.buffer32) return;
+    const { width: w, height: h } = this.imgData;
+    x  = Math.min(Math.max(x,  0), w - 1);
+    y1 = Math.min(Math.max(y1, 0), h - 1);
+    y2 = Math.min(Math.max(y2, 0), h - 1);
+    if (y2 < y1) [y1, y2] = [y2, y1];
+    const color32 = 0xFF000000 | (b & 0xFF) << 16 | (g & 0xFF) << 8 | (r & 0xFF);
+    let idx = y1 * w + x;
+    for (let y = y1; y <= y2; y++, idx += w) this.buffer32[idx] = color32;
+    this.markDirtyRect(x, y1, 1, (y2 - y1) + 1);
+  },
+
+  drawHorizontalLine(x1, y, x2, r, g, b) {
+    if (!this.buffer32) return;
+    const { width: w, height: h } = this.imgData;
+    y  = Math.min(Math.max(y,  0), h - 1);
+    x1 = Math.min(Math.max(x1, 0), w - 1);
+    x2 = Math.min(Math.max(x2, 0), w - 1);
+    if (x2 < x1) [x1, x2] = [x2, x1];
+    const color32 = 0xFF000000 | (b & 0xFF) << 16 | (g & 0xFF) << 8 | (r & 0xFF);
+    let idx = y * w + x1;
+    for (let x = x1; x <= x2; x++, idx++) this.buffer32[idx] = color32;
+    this.markDirtyRect(x1, y, (x2 - x1) + 1, 1);
+  },
+
+  drawMarchingAntRect(
+    x,
+    y,
+    width,
+    height,
+    dashLen = 3,
+    offset = 0,
+    color1 = 0xFFFFFFFF,
+    color2 = 0xFF000000
+  ) {
+    drawMarchingAntRect(
+      this,
+      x,
+      y,
+      width,
+      height,
+      dashLen,
+      offset,
+      color1,
+      color2
+    );
+    this.markDirtyRect(x, y, width + 1, height + 1);
+  },
+
+  drawDashedRect(
+    x,
+    y,
+    width,
+    height,
+    dashLenOrR = 3,
+    offsetOrG = 0,
+    color1OrB = 0xFFFFFFFF,
+    color2OrDashLen = 0xFF000000
+  ) {
+    const isRgbSignature = arguments.length >= 7 &&
+        Number.isFinite(dashLenOrR) &&
+        Number.isFinite(offsetOrG) &&
+        Number.isFinite(color1OrB) &&
+        dashLenOrR >= 0 && dashLenOrR <= 255 &&
+        offsetOrG >= 0 && offsetOrG <= 255 &&
+        color1OrB >= 0 && color1OrB <= 255;
+
+    if (isRgbSignature) {
+      const r = dashLenOrR;
+      const g = offsetOrG;
+      const b = color1OrB;
+      const dashLen = Number.isFinite(color2OrDashLen) ? color2OrDashLen : 2;
+      const color = 0xFF000000 | (b & 0xFF) << 16 | (g & 0xFF) << 8 | (r & 0xFF);
+      drawDashedRect(
+        this,
+        x,
+        y,
+        width,
+        height,
+        dashLen,
+        0,
+        color,
+        0x00000000
+      );
+      this.markDirtyRect(x, y, width + 1, height + 1);
+      return;
+    }
+
+    drawDashedRect(
+      this,
+      x,
+      y,
+      width,
+      height,
+      dashLenOrR,
+      offsetOrG,
+      color1OrB,
+      color2OrDashLen
+    );
+    this.markDirtyRect(x, y, width + 1, height + 1);
+  },
+
+  drawStippleRect(x, y, width, height, r = 128, g = 128, b = 128) {
+    if (!this.buffer32) return;
+    const { width: w } = this.imgData;
+    const color32 = 0xFF000000 | (b & 0xFF) << 16 | (g & 0xFF) << 8 | (r & 0xFF);
+    for (let dy = 0; dy <= height; dy++) {
+      let idx = (y + dy) * w + x;
+      for (let dx = 0; dx <= width; dx++, idx++) {
+        if (((dx + dy) & 1) === 0) this.buffer32[idx] = color32;
+      }
+    }
+    this.markDirtyRect(x, y, width + 1, height + 1);
+  },
+
+  drawCornerRect(x, y, size, r, g, b, length = 1, midLine = false, midLen = 0) {
+    const w = typeof size === 'object' ? size.width : size;
+    const h = typeof size === 'object' ? size.height : size;
+    const x2 = x + w - 1;
+    const y2 = y + h - 1;
+
+    const len = Math.max(1, length);
+
+    // top-left
+    this.drawHorizontalLine(x, y, Math.min(x + len, x2), r, g, b);
+    this.drawVerticalLine(x, y, Math.min(y + len, y2), r, g, b);
+    // top-right
+    this.drawHorizontalLine(Math.max(x2 - len, x), y, x2, r, g, b);
+    this.drawVerticalLine(x2, y, Math.min(y + len, y2), r, g, b);
+    // bottom-left
+    this.drawHorizontalLine(x, y2, Math.min(x + len, x2), r, g, b);
+    this.drawVerticalLine(x, Math.max(y2 - len, y), y2, r, g, b);
+    // bottom-right
+    this.drawHorizontalLine(Math.max(x2 - len, x), y2, x2, r, g, b);
+    this.drawVerticalLine(x2, Math.max(y2 - len, y), y2, r, g, b);
+
+    if (midLine && midLen > 0) {
+      const hx1 = Math.max(x + Math.floor((w - midLen) / 2), x);
+      const hx2 = Math.min(hx1 + midLen - 1, x2);
+      const hy1 = Math.max(y + Math.floor((h - midLen) / 2), y);
+      const hy2 = Math.min(hy1 + midLen - 1, y2);
+      this.drawHorizontalLine(hx1, y, hx2, r, g, b);
+      this.drawHorizontalLine(hx1, y2, hx2, r, g, b);
+      this.drawVerticalLine(x, hy1, hy2, r, g, b);
+      this.drawVerticalLine(x2, hy1, hy2, r, g, b);
+    }
+  },
+
+  drawMask(mask, posX, posY) {
+    if (!this.buffer32) return;
+    const maskOffsetX = Number.isFinite(mask?.offsetX) ? mask.offsetX : 0;
+    const maskOffsetY = Number.isFinite(mask?.offsetY) ? mask.offsetY : 0;
+    const srcW = mask.width, srcH = mask.height,
+      srcMask = mask.getMask(),
+      destW = this.imgData.width, destH = this.imgData.height,
+      baseX = posX + maskOffsetX, baseY = posY + maskOffsetY,
+      WHITE = 0xFFFFFFFF;
+    for (let srcY = 0; srcY < srcH; srcY++) {
+      const outY = srcY + baseY;
+      if (outY < 0 || outY >= destH) continue;
+      let srcRow = srcY * srcW, destRow = outY * destW + baseX;
+      for (let srcX = 0; srcX < srcW; srcX++, srcRow++, destRow++) {
+        if (!srcMask[srcRow]) continue;
+        const outX = srcX + baseX;
+        if (outX < 0 || outX >= destW) continue; // x‑clip
+        this.buffer32[destRow] = WHITE;
+      }
+    }
+    this.markDirtyRect(baseX, baseY, srcW, srcH);
+  }
+};
+export { displayPrimitivesMethods };
\ No newline at end of file
diff --git a/js/render/minimap/MiniMapCore.js b/js/render/minimap/MiniMapCore.js
new file mode 100644
index 00000000..fc7ec874
--- /dev/null
+++ b/js/render/minimap/MiniMapCore.js
@@ -0,0 +1,107 @@
+import {
+  Frame,
+  TriggerTypes,
+  clamp,
+  getApp,
+  getAppContext,
+  getRuntimeHistory,
+  getRuntimePerformanceContext,
+  isRuntimeReplayApplying
+} from './MiniMapShared.js';
+import { miniMapInputMethods } from './MiniMapInput.js';
+import { miniMapTerrainMethods } from './MiniMapTerrain.js';
+import { miniMapRenderMethods } from './MiniMapRender.js';
+class MiniMap {
+  static palette = null;
+
+  static DEATH_DOT_TTL = 30;
+
+  constructor(gameDisplay, level, guiDisplay, runtime = null) {
+    this.gameDisplay = gameDisplay;
+    this.level = level;
+    this.guiDisplay = guiDisplay;
+    this.runtime = runtime;
+
+    this.width = 127;
+    this.height = 24;
+    this.size = this.width * this.height;
+    const levelWidth = Number.isFinite(level?.width) && level.width > 0 ? level.width : this.width;
+    const levelHeight = Number.isFinite(level?.height) && level.height > 0 ? level.height : this.height;
+    this.levelWidth = levelWidth;
+    this.levelHeight = levelHeight;
+    this.scaleX = this.width / levelWidth;
+    this.scaleY = this.height / levelHeight;
+
+    this.terrain = new Uint8Array(this.size);
+    this.terrainColors = new Uint32Array(this.size);
+    this._terrainDirtyFlags = new Uint8Array(this.size);
+    this._terrainDirtyIndices = new Uint16Array(this.size);
+    this._terrainDirtyCount = 0;
+    this._terrainDirtyRead = 0;
+    this._terrainDirtyWrite = 0;
+    this.terrainRevalidateBudget = Math.max(64, this.size >> 2);
+    this._objectMarkerIndices = new Uint16Array(0);
+    this._objectMarkerColors = new Uint32Array(0);
+
+    if (!MiniMap.palette) {
+      MiniMap.palette = new Uint32Array(129);
+      for (let i = 1; i <= 128; ++i) {
+        MiniMap.palette[i] = 0xFF000000 | ((i*2) << 8);
+      }
+    }
+    this._buildTerrain();
+    this._buildObjectMarkers();
+
+    // dynamic state
+    this.fog = new Uint8Array(this.size); // 0 = unseen
+    this.fog.fill(1); // disabled
+    // typed array storing [x1,y1,x2,y2,...] scaled to minimap
+    this.liveDots = new Uint8Array(0);
+    this.liveDotsLength = 0;
+    this.selectedDot = null;
+    // typed arrays storing [x1,y1,x2,y2,...] and TTL per dot
+    this.deadDots = new Uint8Array(64);
+    this.deadTTLs = new Uint8Array(32);
+    this.deadCount = 0;
+
+    // render target (drawn into the GUI canvas once per frame)
+    this.frame = new Frame(this.width, this.height);
+    this.frame.mask.fill(1);
+    //this.renderFrame = new Frame(this.renderWidth, this.renderHeight);
+
+    this._displayListeners = null;
+    this._mouseDown = false;
+    this.viewportDashOffset = 0;
+    this._viewportCounter = 0;
+    this.viewportDashDelay = 100;
+    this._frameNeedsCompose = true;
+    this._lastViewRectX = Number.NaN;
+    this._lastViewRectY = Number.NaN;
+    this._lastViewRectW = Number.NaN;
+    this._lastViewRectH = Number.NaN;
+    this._lastViewDashOffset = Number.NaN;
+    this._lastLiveDotsRef = this.liveDots;
+    this._lastLiveDotsLength = 0;
+    this._lastSelectedDotVisible = false;
+    this._lastSelectedDotX = Number.NaN;
+    this._lastSelectedDotY = Number.NaN;
+    this._lastReversing = false;
+    this._lastTerrainRevalidated = 0;
+    this._renderStats = {
+      draws: 0,
+      composes: 0,
+      reuses: 0,
+      lastTerrainCells: 0,
+      lastDeadCount: 0
+    };
+    if (this.guiDisplay) this._hookPointer();
+  }
+}
+for (const methods of [
+  miniMapInputMethods,
+  miniMapTerrainMethods,
+  miniMapRenderMethods
+]) {
+  Object.defineProperties(MiniMap.prototype, Object.getOwnPropertyDescriptors(methods));
+}
+export { MiniMap };
\ No newline at end of file
diff --git a/js/render/minimap/MiniMapInput.js b/js/render/minimap/MiniMapInput.js
new file mode 100644
index 00000000..e113755a
--- /dev/null
+++ b/js/render/minimap/MiniMapInput.js
@@ -0,0 +1,63 @@
+import {
+  Frame,
+  TriggerTypes,
+  clamp,
+  getApp,
+  getAppContext,
+  getRuntimeHistory,
+  getRuntimePerformanceContext,
+  isRuntimeReplayApplying
+} from './MiniMapShared.js';
+const miniMapInputMethods = {
+  _hookPointer() {
+    this._displayListeners = [
+      ['onMouseDown', e => { this._handleMouseDown(e); }],
+      ['onMouseUp', e => { this._handleMouseUp(e); }],
+      ['onMouseMove', e => { this._handleMouseMove(e); }],
+    ];
+    for (const [event, handler] of this._displayListeners) {
+      this.guiDisplay[event].on(handler);
+    }
+  },
+
+  _updateViewportFromPointer(event) {
+    if (!this.guiDisplay || !this.level) return;
+    if (!Number.isFinite(event?.x) || !Number.isFinite(event?.y)) return;
+    const gd = this.guiDisplay;
+    const destX = gd.worldDataSize.width - this.width;
+    const destY = gd.worldDataSize.height - this.height;
+
+    const mx = event.x - destX;
+    const my = event.y - destY;
+    if (mx < 0 || my < 0 || mx >= this.width || my >= this.height) return;
+
+    const pct = this.width <= 1 ? 0 : (mx / (this.width - 1));
+    const stageViewWidth = getApp(this.runtime)?.stage?.getGameViewRect?.()?.w;
+    const viewportWorldWidth = Number.isFinite(stageViewWidth) && stageViewWidth > 0
+      ? stageViewWidth
+      : gd.worldDataSize.width;
+    const maxOffset = Math.max(0, this.levelWidth - viewportWorldWidth);
+    const newX = clamp(Math.trunc(pct * maxOffset), 0, maxOffset);
+    this.level.screenPositionX = newX;
+    gd.setScreenPosition?.(newX, 0, { preserveScale: true });
+  },
+
+  _handleMouseDown(event){
+    if (!this.guiDisplay) return;
+    this._mouseDown = true;
+    this._updateViewportFromPointer(event);
+  },
+
+  _handleMouseUp(event){
+    if (!this.guiDisplay) return;
+    this._mouseDown = false;
+    this._updateViewportFromPointer(event);
+  },
+
+  _handleMouseMove(event){
+    if (!this.guiDisplay) return;
+    if (!this._mouseDown) return;
+    this._updateViewportFromPointer(event);
+  }
+};
+export { miniMapInputMethods };
\ No newline at end of file
diff --git a/js/render/minimap/MiniMapRender.js b/js/render/minimap/MiniMapRender.js
new file mode 100644
index 00000000..05ed3b72
--- /dev/null
+++ b/js/render/minimap/MiniMapRender.js
@@ -0,0 +1,175 @@
+import {
+  Frame,
+  TriggerTypes,
+  clamp,
+  getApp,
+  getAppContext,
+  getRuntimeHistory,
+  getRuntimePerformanceContext,
+  isRuntimeReplayApplying
+} from './MiniMapShared.js';
+const miniMapRenderMethods = {
+  render() {
+    const terrainChanged = this._flushTerrainInvalidation();
+    if (terrainChanged) {
+      this._frameNeedsCompose = true;
+    }
+    if (!this.guiDisplay) return false;
+    const app = getApp(this.runtime);
+    const reversing = isRuntimeReplayApplying(this.runtime);
+    this._renderStats.draws += 1;
+
+    let dashChanged = false;
+    if (++this._viewportCounter >= this.viewportDashDelay) {
+      this._viewportCounter = 0;
+      this.viewportDashOffset += 1;
+      dashChanged = true;
+    }
+
+    const {
+      width: W,
+      height: H,
+      frame,
+    } = this;
+    const frameData = frame.data;
+
+    const viewRect = app?.stage?.getGameViewRect?.();
+    if (!viewRect) return false;
+    const vpX = (viewRect.x * this.scaleX) | 0;
+    let vpW = (viewRect.w * this.scaleX) | 0;
+    const vpY = (viewRect.y * this.scaleY) | 0;
+    const vpH = (viewRect.h * this.scaleY) | 0;
+    const viewChanged =
+        this._lastViewRectX !== vpX ||
+        this._lastViewRectY !== vpY ||
+        this._lastViewRectW !== vpW ||
+        this._lastViewRectH !== vpH ||
+        this._lastViewDashOffset !== this.viewportDashOffset;
+    if (viewChanged || dashChanged) {
+      this._frameNeedsCompose = true;
+      this._lastViewRectX = vpX;
+      this._lastViewRectY = vpY;
+      this._lastViewRectW = vpW;
+      this._lastViewRectH = vpH;
+      this._lastViewDashOffset = this.viewportDashOffset;
+    }
+
+    if (this.liveDots !== this._lastLiveDotsRef || this.liveDotsLength !== this._lastLiveDotsLength) {
+      this._frameNeedsCompose = true;
+      this._lastLiveDotsRef = this.liveDots;
+      this._lastLiveDotsLength = this.liveDotsLength;
+    }
+    const selectedVisible = !!this.selectedDot;
+    const selectedX = selectedVisible ? this.selectedDot[0] : Number.NaN;
+    const selectedY = selectedVisible ? this.selectedDot[1] : Number.NaN;
+    const selectedChanged =
+        this._lastSelectedDotVisible !== selectedVisible ||
+        (selectedVisible && (
+          this._lastSelectedDotX !== selectedX ||
+          this._lastSelectedDotY !== selectedY
+        ));
+    if (selectedChanged) {
+      this._frameNeedsCompose = true;
+      this._lastSelectedDotVisible = selectedVisible;
+      this._lastSelectedDotX = selectedX;
+      this._lastSelectedDotY = selectedY;
+    }
+    if (reversing !== this._lastReversing) {
+      this._frameNeedsCompose = true;
+      this._lastReversing = reversing;
+    }
+    if (!reversing && this._decayDeathDots()) {
+      this._frameNeedsCompose = true;
+    }
+
+    if (this._frameNeedsCompose) {
+      frameData.set(this.terrainColors);
+      this._paintObjectMarkers(frameData);
+
+      let vpXW = vpX + vpW;
+      // dumb fix to keep right edge of viewport rect visible
+      if (vpXW === this.width) {
+        vpW -= 1;
+      }
+      frame.drawMarchingAntRect(
+        vpX,
+        vpY,
+        vpW,
+        vpH,
+        2,
+        this.viewportDashOffset,
+        0xFF00FF00,
+        0xFF005500
+      );
+
+      /* Live lemmings */
+      for (let i = 0; i < this.liveDotsLength; i += 2) {
+        const x = this.liveDots[i];
+        const y = this.liveDots[i + 1];
+        if ((x >>> 0) < W && (y >>> 0) < H) {
+          frameData[(y * W) + x] = 0xFF00FFFF;
+        }
+      }
+      if (this.selectedDot) {
+        const x = this.selectedDot[0];
+        const y = this.selectedDot[1];
+        if ((x >>> 0) < W && (y >>> 0) < H) {
+          frameData[(y * W) + x] = 0xFFFFFFFF;
+        }
+      }
+
+      /* Death flashes */
+      const total = this.deadCount;
+      for (let i = 0; i < total; ++i) {
+        const ttl = this.deadTTLs[i];
+        if (ttl <= 0) continue;
+        if (ttl & 4) {
+          const x = this.deadDots[i * 2];
+          const y = this.deadDots[i * 2 + 1];
+          if ((x >>> 0) < W && (y >>> 0) < H) {
+            frameData[(y * W) + x] = 0xFF0000FF;
+          }
+        }
+      }
+      this._renderStats.composes += 1;
+      this._frameNeedsCompose = false;
+    } else {
+      this._renderStats.reuses += 1;
+      this._renderStats.lastTerrainCells = this._lastTerrainRevalidated;
+      this._renderStats.lastDeadCount = this.deadCount;
+      return false;
+    }
+
+    this._renderStats.lastTerrainCells = this._lastTerrainRevalidated;
+    this._renderStats.lastDeadCount = this.deadCount;
+
+    /* Blit */
+    const destX = this.guiDisplay.worldDataSize.width  - W;
+    const destY = this.guiDisplay.worldDataSize.height - H;
+    this.guiDisplay.drawFrame(frame, destX, destY);
+    return true;
+  },
+
+  dispose() {
+    if (this.guiDisplay && this._displayListeners) {
+      for (const [event, handler] of this._displayListeners) {
+        this.guiDisplay[event].off(handler);
+      }
+      this._displayListeners = null;
+    }
+    this.gameDisplay = null;
+    this.level = null;
+    this.guiDisplay = null;
+    this.terrain = null;
+    this.fog = null;
+    this.liveDots = null;
+    this.liveDotsLength = 0;
+    this.selectedDot = null;
+    this.deadDots = null;
+    this.deadTTLs = null;
+    this.deadCount = 0;
+    this.frame = null;
+    this.runtime = null;
+  }
+};
+export { miniMapRenderMethods };
\ No newline at end of file
diff --git a/js/render/minimap/MiniMapShared.js b/js/render/minimap/MiniMapShared.js
new file mode 100644
index 00000000..319c68b5
--- /dev/null
+++ b/js/render/minimap/MiniMapShared.js
@@ -0,0 +1,22 @@
+import { Frame } from '../Frame.js';
+import { TriggerTypes } from '../../level/TriggerTypes.js';
+import { getAppContext } from '../../core/dependencies.js';
+import {
+  getRuntimeHistory,
+  getRuntimePerformanceContext,
+  isRuntimeReplayApplying
+} from '../../game/GameRuntime.js';
+
+const getApp = (runtime = null) => getRuntimePerformanceContext(runtime) || getAppContext();
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+
+export {
+  Frame,
+  TriggerTypes,
+  clamp,
+  getApp,
+  getAppContext,
+  getRuntimeHistory,
+  getRuntimePerformanceContext,
+  isRuntimeReplayApplying
+};
diff --git a/js/render/minimap/MiniMapTerrain.js b/js/render/minimap/MiniMapTerrain.js
new file mode 100644
index 00000000..4e327199
--- /dev/null
+++ b/js/render/minimap/MiniMapTerrain.js
@@ -0,0 +1,274 @@
+import {
+  Frame,
+  TriggerTypes,
+  clamp,
+  getApp,
+  getAppContext,
+  getRuntimeHistory,
+  getRuntimePerformanceContext,
+  isRuntimeReplayApplying
+} from './MiniMapShared.js';
+const miniMapTerrainMethods = {
+  _buildTerrain() {
+    const gm = this.level.getGroundMaskLayer();
+    const levelWidth = this.levelWidth;
+    const levelHeight = this.levelHeight;
+    for (let mY = 0; mY < this.height; ++mY) {
+      const ly1 = Math.floor(mY / this.scaleY);
+      const ly2 = Math.min(levelHeight, Math.ceil((mY + 1) / this.scaleY));
+      for (let mX = 0; mX < this.width; ++mX) {
+        const lx1 = Math.floor(mX / this.scaleX);
+        const lx2 = Math.min(levelWidth, Math.ceil((mX + 1) / this.scaleX));
+        let count = gm.countMaskInRect(lx1, ly1, lx2 - lx1, ly2 - ly1, 72);
+        if (count > 71) count = 72;
+        this._setTerrainCount(mY * this.width + mX, count);
+      }
+    }
+  },
+
+  _setTerrainCount(idx, count) {
+    const normalized = Math.max(0, Math.min(128, count | 0));
+    this.terrain[idx] = normalized;
+    this.terrainColors[idx] = this.constructor.palette[normalized] || 0xFF000000;
+  },
+
+  _markTerrainCellDirty(idx) {
+    if ((idx >>> 0) >= this.size) return;
+    if (this._terrainDirtyFlags[idx]) return;
+    if (this._terrainDirtyCount >= this.size) {
+      const overwriteIdx = this._terrainDirtyIndices[this._terrainDirtyWrite];
+      if ((overwriteIdx >>> 0) < this.size) {
+        this._terrainDirtyFlags[overwriteIdx] = 0;
+      }
+      if (this._terrainDirtyRead === this._terrainDirtyWrite) {
+        this._terrainDirtyRead = (this._terrainDirtyRead + 1) % this.size;
+      }
+    }
+    this._terrainDirtyFlags[idx] = 1;
+    this._terrainDirtyIndices[this._terrainDirtyWrite] = idx;
+    this._terrainDirtyWrite += 1;
+    if (this._terrainDirtyWrite === this.size) {
+      this._terrainDirtyWrite = 0;
+    }
+    this._terrainDirtyCount = Math.min(this.size, this._terrainDirtyCount + 1);
+  },
+
+  _refreshTerrainCell(idx, groundMaskLayer = null) {
+    const mX = idx % this.width;
+    const mY = (idx / this.width) | 0;
+    const lx1 = Math.floor(mX / this.scaleX);
+    const lx2 = Math.min(this.levelWidth, Math.ceil((mX + 1) / this.scaleX));
+    const ly1 = Math.floor(mY / this.scaleY);
+    const ly2 = Math.min(this.levelHeight, Math.ceil((mY + 1) / this.scaleY));
+    const gm = groundMaskLayer || this.level.getGroundMaskLayer();
+    let count = gm.countMaskInRect(lx1, ly1, lx2 - lx1, ly2 - ly1, 72);
+    if (count > 71) count = 72;
+    this._setTerrainCount(idx, count);
+  },
+
+  _flushTerrainInvalidation() {
+    const dirtyCount = this._terrainDirtyCount;
+    this._lastTerrainRevalidated = 0;
+    if (!dirtyCount) return false;
+    if (dirtyCount >= (this.size >> 1)) {
+      this._buildTerrain();
+      this._terrainDirtyFlags.fill(0);
+      this._terrainDirtyCount = 0;
+      this._terrainDirtyRead = 0;
+      this._terrainDirtyWrite = 0;
+      this._lastTerrainRevalidated = this.size;
+      return true;
+    }
+    let budget = this.terrainRevalidateBudget | 0;
+    if (budget <= 0 || budget > dirtyCount) budget = dirtyCount;
+    const dirty = this._terrainDirtyIndices;
+    const flags = this._terrainDirtyFlags;
+    const groundMaskLayer = this.level.getGroundMaskLayer();
+    let read = this._terrainDirtyRead;
+    for (let i = 0; i < budget; i += 1) {
+      const idx = dirty[read];
+      read += 1;
+      if (read === this.size) read = 0;
+      flags[idx] = 0;
+      this._refreshTerrainCell(idx, groundMaskLayer);
+    }
+    this._terrainDirtyRead = read;
+    this._terrainDirtyCount = dirtyCount - budget;
+    if (!this._terrainDirtyCount) {
+      this._terrainDirtyRead = 0;
+      this._terrainDirtyWrite = 0;
+    }
+    this._lastTerrainRevalidated = budget;
+    return budget > 0;
+  },
+
+  _buildObjectMarkers() {
+    const markerMap = new Map();
+    const objects = this.level?.objects || [];
+    for (let i = 0; i < objects.length; i += 1) {
+      const obj = objects[i];
+      const rx = (obj.x * this.scaleX) | 0;
+      const ry = (obj.y * this.scaleY) | 0;
+      if ((obj.ob?.id === 1)) {
+        const idx = ((ry + 2) * this.width) + (rx + 2);
+        if ((idx >>> 0) < this.size) markerMap.set(idx, 0xFF00AA00);
+      }
+      if (obj.triggerType === TriggerTypes.EXIT_LEVEL) {
+        const idxA = ((ry + 2) * this.width) + (rx + 2);
+        const idxB = ((ry + 1) * this.width) + (rx + 2);
+        if ((idxA >>> 0) < this.size) markerMap.set(idxA, 0xFFFF00CC);
+        if ((idxB >>> 0) < this.size) markerMap.set(idxB, 0xFFFF00CC);
+      }
+    }
+    const count = markerMap.size;
+    if (!count) {
+      this._objectMarkerIndices = new Uint16Array(0);
+      this._objectMarkerColors = new Uint32Array(0);
+      return;
+    }
+    const indices = new Uint16Array(count);
+    const colors = new Uint32Array(count);
+    let index = 0;
+    for (const [markerIdx, markerColor] of markerMap) {
+      indices[index] = markerIdx;
+      colors[index] = markerColor;
+      index += 1;
+    }
+    this._objectMarkerIndices = indices;
+    this._objectMarkerColors = colors;
+  },
+
+  _paintObjectMarkers(frameData) {
+    const indices = this._objectMarkerIndices;
+    const colors = this._objectMarkerColors;
+    for (let i = 0; i < indices.length; i += 1) {
+      frameData[indices[i]] = colors[i];
+    }
+  },
+
+  onGroundChanged(px, py, removed = true) {
+    const mX = (px * this.scaleX) | 0;
+    const mY = (py * this.scaleY) | 0;
+    if (mX < 0 || mX >= this.width || mY < 0 || mY >= this.height) return;
+    const idx = mY * this.width + mX;
+    let next = this.terrain[idx];
+    if (removed) next -= 1;
+    else next += 1;
+    this._setTerrainCount(idx, next);
+    this._markTerrainCellDirty(idx);
+    this._frameNeedsCompose = true;
+  },
+
+  invalidateRegion(x, y, w, h) {
+    if (w <= 0 || h <= 0) return;
+    const xStart = Math.max(0, Math.floor(x));
+    const yStart = Math.max(0, Math.floor(y));
+    const xEnd = Math.min(this.levelWidth, Math.ceil(x + w));
+    const yEnd = Math.min(this.levelHeight, Math.ceil(y + h));
+    if (xEnd <= xStart || yEnd <= yStart) return;
+
+    const mX0 = Math.max(0, Math.floor(xStart * this.scaleX));
+    const mY0 = Math.max(0, Math.floor(yStart * this.scaleY));
+    const mX1 = Math.min(this.width - 1, Math.floor((xEnd - 1) * this.scaleX));
+    const mY1 = Math.min(this.height - 1, Math.floor((yEnd - 1) * this.scaleY));
+
+    for (let mY = mY0; mY <= mY1; mY += 1) {
+      for (let mX = mX0; mX <= mX1; mX += 1) {
+        this._markTerrainCellDirty((mY * this.width) + mX);
+      }
+    }
+    this._frameNeedsCompose = true;
+  },
+
+  reveal(viewX, viewW) {
+    const sx1 = Math.max(0, Math.floor(viewX * this.scaleX));
+    const sx2 = Math.min(this.width, Math.ceil((viewX + viewW) * this.scaleX));
+    if (sx2 <= sx1) return;
+    for (let y = 0; y < this.height; ++y) {
+      const row = y * this.width;
+      for (let x = sx1; x < sx2; ++x) this.fog[row + x] = 1;
+    }
+    this._frameNeedsCompose = true;
+  },
+
+  setLiveDots(arr, activeLength) {
+    // arr is a Uint8Array of scaled [x1,y1,x2,y2,...]
+    this.liveDots = arr;
+    const length = activeLength == null ? arr?.length : activeLength;
+    this.liveDotsLength = Math.max(0, Math.min(arr?.length ?? 0, Math.trunc(length ?? 0)));
+    this._frameNeedsCompose = true;
+  },
+
+  invalidateFrame() {
+    this._frameNeedsCompose = true;
+  },
+
+  setSelectedDot(dot) {
+    this.selectedDot = dot;
+    this._frameNeedsCompose = true;
+  },
+
+  addDeath(x, y) {
+    const sx = Math.max(0, Math.min(this.width - 1, (x * this.scaleX) | 0));
+    const sy = Math.max(0, Math.min(this.height - 1, (y * this.scaleY) | 0));
+    const history = getRuntimeHistory(this.runtime);
+    if (history?.recordMinimapDeath) {
+      history.recordMinimapDeath({
+        x: sx,
+        y: sy,
+        ttl: this.constructor.DEATH_DOT_TTL,
+        prevCount: this.deadCount
+      });
+    }
+
+    if (this.deadCount >= this.deadTTLs.length) {
+      const next = Math.max(4, this.deadTTLs.length * 2);
+      const coords = new Uint8Array(next * 2);
+      const ttls = new Uint8Array(next);
+      coords.set(this.deadDots.subarray(0, this.deadCount * 2));
+      ttls.set(this.deadTTLs.subarray(0, this.deadCount));
+      this.deadDots = coords;
+      this.deadTTLs = ttls;
+    }
+
+    const idx = this.deadCount++;
+    this.deadDots[idx * 2] = sx;
+    this.deadDots[idx * 2 + 1] = sy;
+    this.deadTTLs[idx] = this.constructor.DEATH_DOT_TTL;
+    this._frameNeedsCompose = true;
+  },
+
+  _decayDeathDots() {
+    if (this.deadCount < 1) return false;
+    let write = 0;
+    const total = this.deadCount;
+    let changed = false;
+    for (let i = 0; i < total; ++i) {
+      const ttl = this.deadTTLs[i] - 1;
+      if (ttl <= 0) {
+        changed = true;
+        continue;
+      }
+      if (ttl !== this.deadTTLs[i] || write !== i) {
+        changed = true;
+      }
+      this.deadTTLs[write] = ttl;
+      const x = this.deadDots[i * 2];
+      const y = this.deadDots[i * 2 + 1];
+      this.deadDots[write * 2] = x;
+      this.deadDots[write * 2 + 1] = y;
+      write += 1;
+    }
+    this.deadCount = write;
+    return changed;
+  },
+
+  getRenderDiagnostics() {
+    return {
+      ...this._renderStats,
+      deadCount: this.deadCount,
+      terrainDirtyCount: this._terrainDirtyCount
+    };
+  }
+};
+export { miniMapTerrainMethods };
diff --git a/js/render/stage/StageCompositor.js b/js/render/stage/StageCompositor.js
new file mode 100644
index 00000000..97ed98c1
--- /dev/null
+++ b/js/render/stage/StageCompositor.js
@@ -0,0 +1,311 @@
+import {
+  COLOR_FN_RE,
+  COLOR_RE,
+  DAMAGE_FULL_REDRAW_AREA_RATIO,
+  DAMAGE_FULL_REDRAW_REGION_THRESHOLD,
+  DIRTY_RECT_FULL_BLIT_AREA_RATIO,
+  DIRTY_RECT_FULL_BLIT_THRESHOLD,
+  DIRTY_UNION_BLIT_RATIO,
+  DisplayImage,
+  PERF_SAMPLE_WINDOW,
+  Position2D,
+  StageImageProperties,
+  UserInputManager,
+  ViewPoint,
+  clamp,
+  colorStringTo32,
+  detectRuntimeCapabilities,
+  drawMarchingAntRect,
+  getDependency,
+  percentile,
+  perfNow,
+  resolveRenderExperimentState,
+  summarizeSamples,
+  toAlpha,
+  toChannel,
+  toFiniteNumber
+} from './StageShared.js';
+const stageCompositorMethods = {
+  redraw(forceComposite = false) {
+    const start = perfNow();
+    this._updateFadeState(start);
+    const collectPerfSamples = this._shouldCollectPerfSamples();
+    this._perfTrackingFrame = true;
+    this._perfDrawMs = 0;
+    this._perfClearMs = 0;
+    this._frameDamageStats = {
+      regionCount: 0,
+      dirtyArea: 0,
+      fullArea: 0,
+      uploadCalls: 0,
+      fullBlitCount: 0,
+      tileUpdateCount: 0
+    };
+    const overlayVisible = this._gameOverlayVisible || (this.guiEnabled && this._guiOverlayVisible);
+    if (this.gameOverlayImgProps.display || this.guiOverlayImgProps.display || overlayVisible) {
+      this._syncOverlayLayout();
+      this._syncOverlayDisplaySize(this.gameImgProps, this.gameOverlayImgProps);
+      this._syncOverlayDisplaySize(this.guiImgProps, this.guiOverlayImgProps);
+    }
+    const gameDisplay = this.gameImgProps.display;
+    const guiDisplay = this.guiImgProps.display;
+    const gameOverlayDisplay = this.gameOverlayImgProps.display;
+    const guiOverlayDisplay = this.guiOverlayImgProps.display;
+    const gameSig = gameDisplay ? this._getDrawSignature(this.gameImgProps) : '';
+    const guiSig = guiDisplay ? this._getDrawSignature(this.guiImgProps) : '';
+    const gameOverlaySig = gameOverlayDisplay ? this._getDrawSignature(this.gameOverlayImgProps) : '';
+    const guiOverlaySig = guiOverlayDisplay ? this._getDrawSignature(this.guiOverlayImgProps) : '';
+    const gameDirty = !!gameDisplay &&
+        (gameDisplay.hasPendingDirty?.() || gameSig !== this._lastGameDrawSignature);
+    const guiDirty = !!guiDisplay &&
+        (guiDisplay.hasPendingDirty?.() || guiSig !== this._lastGuiDrawSignature);
+    const gameOverlayDirty = !!gameOverlayDisplay &&
+        (gameOverlayDisplay.hasPendingDirty?.() || gameOverlaySig !== this._lastGameOverlayDrawSignature);
+    const guiOverlayDirty = !!guiOverlayDisplay &&
+        (guiOverlayDisplay.hasPendingDirty?.() || guiOverlaySig !== this._lastGuiOverlayDrawSignature);
+    const overlayDirty = gameOverlayDirty || guiOverlayDirty;
+    const overlayVisibilityChanged = this._overlayVisibilityVersion !== this._lastOverlayVisibilityVersion;
+    const cursorVisibleChanged = this._lastCursorHasSprite !== !!this.cursorCanvas;
+    const cursorStateChanged = this._cursorStateVersion !== this._lastCursorStateVersion || cursorVisibleChanged;
+    const cursorMoved = !!this.cursorCanvas &&
+        (this._lastCursorX !== this.cursorX || this._lastCursorY !== this.cursorY);
+    const requiresFullComposite =
+        forceComposite ||
+        this.fadeAlpha !== 0 ||
+        this.overlayAlpha > 0 ||
+        this.perfOverlayEnabled ||
+        cursorStateChanged ||
+        cursorMoved ||
+        overlayVisibilityChanged ||
+        overlayDirty ||
+        (overlayVisible && (gameDirty || guiDirty));
+
+    if (!requiresFullComposite && !gameDirty && !guiDirty && !overlayDirty) {
+      this._lastCursorX = this.cursorX;
+      this._lastCursorY = this.cursorY;
+      this._lastCursorHasSprite = !!this.cursorCanvas;
+      this._lastCursorStateVersion = this._cursorStateVersion;
+      this._lastOverlayVisibilityVersion = this._overlayVisibilityVersion;
+      this._perfTrackingFrame = false;
+      this._perfFrameCount += 1;
+      this._perfFrameMs = perfNow() - start;
+      if (this._perfFrameMs > this._perfFramePeakMs) {
+        this._perfFramePeakMs = this._perfFrameMs;
+      }
+      if (collectPerfSamples) {
+        const allocGame = this._collectDisplayAllocationStats(this.gameImgProps);
+        const allocGui = this._collectDisplayAllocationStats(this.guiImgProps);
+        const allocGameOverlay = this._collectDisplayAllocationStats(this.gameOverlayImgProps);
+        const allocGuiOverlay = this._collectDisplayAllocationStats(this.guiOverlayImgProps);
+        const allocations = {
+          rectListCreated: allocGame.rectListCreated + allocGui.rectListCreated + allocGameOverlay.rectListCreated + allocGuiOverlay.rectListCreated,
+          rectListReused: allocGame.rectListReused + allocGui.rectListReused + allocGameOverlay.rectListReused + allocGuiOverlay.rectListReused,
+          tileListCreated: allocGame.tileListCreated + allocGui.tileListCreated + allocGameOverlay.tileListCreated + allocGuiOverlay.tileListCreated,
+          tileListReused: allocGame.tileListReused + allocGui.tileListReused + allocGameOverlay.tileListReused + allocGuiOverlay.tileListReused
+        };
+        this._recordFramePerf(this._perfFrameMs, this._perfDrawMs, this._perfClearMs);
+        this._recordDamagePerf({
+          regionCount: 0,
+          dirtyAreaRatio: 0,
+          uploadCalls: 0,
+          fullBlitCount: 0,
+          tileUpdateCount: 0
+        });
+        this._recordAllocationPerf(allocations);
+      }
+      if (this.perfOverlayEnabled) {
+        this.drawPerfOverlay();
+      }
+      this._lastCursorX = this.cursorX;
+      this._lastCursorY = this.cursorY;
+      this._lastCursorHasSprite = !!this.cursorCanvas;
+      this._lastCursorStateVersion = this._cursorStateVersion;
+      return;
+    }
+
+    if (requiresFullComposite) {
+      this.clear();
+      if (gameDisplay) {
+        const gameImg = gameDisplay.getImageData();
+        this.draw(this.gameImgProps, gameImg);
+        this._lastGameDrawSignature = gameSig;
+      }
+      if (guiDisplay) {
+        const guiImg = guiDisplay.getImageData();
+        this.draw(this.guiImgProps, guiImg);
+        this._lastGuiDrawSignature = guiSig;
+      }
+      if (gameOverlayDisplay && (this._gameOverlayVisible || gameOverlayDirty)) {
+        const overlayImg = gameOverlayDisplay.getImageData();
+        this.draw(this.gameOverlayImgProps, overlayImg, { applyStageEffects: false });
+      }
+      if (guiOverlayDisplay && (this._guiOverlayVisible || guiOverlayDirty)) {
+        const overlayImg = guiOverlayDisplay.getImageData();
+        this.draw(this.guiOverlayImgProps, overlayImg, { applyStageEffects: false });
+      }
+    } else {
+      if (gameDisplay && gameDirty) {
+        const gameImg = gameDisplay.getImageData();
+        this.clear(this.gameImgProps);
+        this.draw(this.gameImgProps, gameImg);
+        this._lastGameDrawSignature = gameSig;
+      }
+      if (guiDisplay && guiDirty) {
+        const guiImg = guiDisplay.getImageData();
+        this.clear(this.guiImgProps);
+        this.draw(this.guiImgProps, guiImg);
+        this._lastGuiDrawSignature = guiSig;
+      }
+    }
+    if (this.cursorCanvas) {
+      this.drawCursor();
+    }
+    this._lastGameOverlayDrawSignature = gameOverlaySig;
+    this._lastGuiOverlayDrawSignature = guiOverlaySig;
+    this._perfTrackingFrame = false;
+    this._perfFrameCount += 1;
+    this._perfFrameMs = perfNow() - start;
+    if (this._perfFrameMs > this._perfFramePeakMs) {
+      this._perfFramePeakMs = this._perfFrameMs;
+    }
+    const fullArea = this._frameDamageStats.fullArea || 0;
+    const dirtyAreaRatio = fullArea > 0
+      ? Math.min(1, (this._frameDamageStats.dirtyArea || 0) / fullArea)
+      : 0;
+    if (collectPerfSamples) {
+      const allocGame = this._collectDisplayAllocationStats(this.gameImgProps);
+      const allocGui = this._collectDisplayAllocationStats(this.guiImgProps);
+      const allocGameOverlay = this._collectDisplayAllocationStats(this.gameOverlayImgProps);
+      const allocGuiOverlay = this._collectDisplayAllocationStats(this.guiOverlayImgProps);
+      const allocations = {
+        rectListCreated: allocGame.rectListCreated + allocGui.rectListCreated + allocGameOverlay.rectListCreated + allocGuiOverlay.rectListCreated,
+        rectListReused: allocGame.rectListReused + allocGui.rectListReused + allocGameOverlay.rectListReused + allocGuiOverlay.rectListReused,
+        tileListCreated: allocGame.tileListCreated + allocGui.tileListCreated + allocGameOverlay.tileListCreated + allocGuiOverlay.tileListCreated,
+        tileListReused: allocGame.tileListReused + allocGui.tileListReused + allocGameOverlay.tileListReused + allocGuiOverlay.tileListReused
+      };
+      this._recordFramePerf(this._perfFrameMs, this._perfDrawMs, this._perfClearMs);
+      this._recordDamagePerf({
+        regionCount: this._frameDamageStats.regionCount || 0,
+        dirtyAreaRatio,
+        uploadCalls: this._frameDamageStats.uploadCalls || 0,
+        fullBlitCount: this._frameDamageStats.fullBlitCount || 0,
+        tileUpdateCount: this._frameDamageStats.tileUpdateCount || 0
+      });
+      this._recordAllocationPerf(allocations);
+    }
+    if (this.perfOverlayEnabled) {
+      this.drawPerfOverlay();
+    }
+    this._lastCursorX = this.cursorX;
+    this._lastCursorY = this.cursorY;
+    this._lastCursorHasSprite = !!this.cursorCanvas;
+    this._lastCursorStateVersion = this._cursorStateVersion;
+    this._lastOverlayVisibilityVersion = this._overlayVisibilityVersion;
+  },
+
+  createImage(displayOwner, width, height) {
+    if (displayOwner === this.gameImgProps.display) {
+      return this.gameImgProps.createImage(width, height);
+    }
+    if (displayOwner === this.guiImgProps.display) {
+      return this.guiImgProps.createImage(width, height);
+    }
+    if (displayOwner === this.gameOverlayImgProps.display) {
+      return this.gameOverlayImgProps.createImage(width, height);
+    }
+    if (displayOwner === this.guiOverlayImgProps.display) {
+      return this.guiOverlayImgProps.createImage(width, height);
+    }
+    return this.gameImgProps.createImage(width, height);
+  },
+
+  _computeDirtyUnion(dirtyRegions) {
+    if (!Array.isArray(dirtyRegions) || dirtyRegions.length < 2) return null;
+    let x1 = Infinity;
+    let y1 = Infinity;
+    let x2 = -Infinity;
+    let y2 = -Infinity;
+    for (let i = 0; i < dirtyRegions.length; i += 1) {
+      const rect = dirtyRegions[i];
+      if (!rect) continue;
+      x1 = Math.min(x1, rect.x);
+      y1 = Math.min(y1, rect.y);
+      x2 = Math.max(x2, rect.x + rect.width);
+      y2 = Math.max(y2, rect.y + rect.height);
+    }
+    if (!Number.isFinite(x1) || !Number.isFinite(y1) || !Number.isFinite(x2) || !Number.isFinite(y2)) {
+      return null;
+    }
+    if (x2 <= x1 || y2 <= y1) return null;
+    return {
+      x: x1,
+      y: y1,
+      width: x2 - x1,
+      height: y2 - y1
+    };
+  },
+
+  _shouldUseFullBlit(dirtyRegions, fullArea, cumulative = null) {
+    let dirtyArea = 0;
+    for (let i = 0; i < dirtyRegions.length; i += 1) {
+      const rect = dirtyRegions[i];
+      dirtyArea += rect.width * rect.height;
+    }
+    const localThreshold = fullArea * DIRTY_RECT_FULL_BLIT_AREA_RATIO;
+    let useFull = dirtyRegions.length > DIRTY_RECT_FULL_BLIT_THRESHOLD || dirtyArea >= localThreshold;
+    if (!useFull && cumulative) {
+      const totalRegions = (cumulative.regionCount || 0) + dirtyRegions.length;
+      const totalArea = (cumulative.dirtyArea || 0) + dirtyArea;
+      const totalFullArea = (cumulative.fullArea || 0) + fullArea;
+      if (
+        totalRegions >= DAMAGE_FULL_REDRAW_REGION_THRESHOLD ||
+          totalArea >= (totalFullArea * DAMAGE_FULL_REDRAW_AREA_RATIO)
+      ) {
+        useFull = true;
+      }
+    }
+    return { useFull, dirtyArea };
+  },
+
+  _accumulateFrameDamage(stats) {
+    if (!this._frameDamageStats || !stats) return;
+    this._frameDamageStats.regionCount += stats.regionCount || 0;
+    this._frameDamageStats.dirtyArea += stats.dirtyArea || 0;
+    this._frameDamageStats.fullArea += stats.fullArea || 0;
+    this._frameDamageStats.uploadCalls += stats.uploadCalls || 0;
+    this._frameDamageStats.fullBlitCount += stats.fullBlit ? 1 : 0;
+    this._frameDamageStats.tileUpdateCount += stats.usedTiles ? 1 : 0;
+  },
+
+  _ensureOverlayFallbackSurface(width, height) {
+    const w = Math.max(1, Math.trunc(width));
+    const h = Math.max(1, Math.trunc(height));
+    if (!this._overlayFallbackCanvas) {
+      if (typeof document === 'undefined' || typeof document.createElement !== 'function') {
+        return null;
+      }
+      const canvas = document.createElement('canvas');
+      const ctx = canvas.getContext('2d', { alpha: true, willReadFrequently: true });
+      if (!ctx) return null;
+      this._overlayFallbackCanvas = canvas;
+      this._overlayFallbackCtx = ctx;
+    }
+    if (
+      !this._overlayFallbackImageData ||
+        this._overlayFallbackImageData.width !== w ||
+        this._overlayFallbackImageData.height !== h
+    ) {
+      this._overlayFallbackCanvas.width = w;
+      this._overlayFallbackCanvas.height = h;
+      this._overlayFallbackImageData = this._overlayFallbackCtx.createImageData(w, h);
+      this._overlayFallbackBuffer32 = new Uint32Array(this._overlayFallbackImageData.data.buffer);
+    }
+    return {
+      canvas: this._overlayFallbackCanvas,
+      ctx: this._overlayFallbackCtx,
+      imageData: this._overlayFallbackImageData,
+      buffer32: this._overlayFallbackBuffer32
+    };
+  }
+};
+export { stageCompositorMethods };
\ No newline at end of file
diff --git a/js/render/stage/StageCore.js b/js/render/stage/StageCore.js
new file mode 100644
index 00000000..d0b711ed
--- /dev/null
+++ b/js/render/stage/StageCore.js
@@ -0,0 +1,208 @@
+import {
+  COLOR_FN_RE,
+  COLOR_RE,
+  DAMAGE_FULL_REDRAW_AREA_RATIO,
+  DAMAGE_FULL_REDRAW_REGION_THRESHOLD,
+  DIRTY_RECT_FULL_BLIT_AREA_RATIO,
+  DIRTY_RECT_FULL_BLIT_THRESHOLD,
+  DIRTY_UNION_BLIT_RATIO,
+  DisplayImage,
+  PERF_SAMPLE_WINDOW,
+  Position2D,
+  StageImageProperties,
+  UserInputManager,
+  ViewPoint,
+  clamp,
+  colorStringTo32,
+  detectRuntimeCapabilities,
+  drawMarchingAntRect,
+  getDependency,
+  percentile,
+  perfNow,
+  resolveRenderExperimentState,
+  summarizeSamples,
+  toAlpha,
+  toChannel,
+  toFiniteNumber
+} from './StageShared.js';
+import { stagePerfMethods } from './StagePerf.js';
+import { stageInputMethods } from './StageInput.js';
+import { stageCompositorMethods } from './StageCompositor.js';
+import { stageOverlaysMethods } from './StageOverlays.js';
+class Stage {
+  constructor(canvasForOutput, options = {}) {
+    this.controller = null;
+    this.fadeTimer = 0;
+    this.fadeAlpha = 0;
+    this.overlayColor = 'black';
+    this.overlayAlpha = 0;
+    this.overlayRect = null;
+    this.overlayTimer = 0;
+    this.overlayDashLen = 0;
+    this.overlayDashColor = 0;
+    this.overlayDashOffset = 0;
+    this._fadeClockMs = NaN;
+    this._fadeDashAccumulator = 0;
+    this._fadeOutActive = false;
+    this._overlayFadeActive = false;
+    this.perfOverlayEnabled = false;
+    this.perfOverlayProvider = null;
+    this._perfTrackingFrame = false;
+    this._perfFrameMs = 0;
+    this._perfDrawMs = 0;
+    this._perfClearMs = 0;
+    this._perfFramePeakMs = 0;
+    this._perfFrameCount = 0;
+    this._perfFrameSamples = [];
+    this._perfDrawSamples = [];
+    this._perfClearSamples = [];
+    this._perfDirtyRegionsSamples = [];
+    this._perfDirtyAreaRatioSamples = [];
+    this._perfUploadCallsSamples = [];
+    this._perfAllocationsSamples = [];
+    this._perfLastDamage = {
+      regionCount: 0,
+      dirtyAreaRatio: 0,
+      uploadCalls: 0,
+      fullBlitCount: 0,
+      tileUpdateCount: 0
+    };
+    this._perfLastAllocations = {
+      rectListCreated: 0,
+      rectListReused: 0,
+      tileListCreated: 0,
+      tileListReused: 0
+    };
+    this._frameDamageStats = null;
+    this._renderExperiments = {
+      offscreenPresentRequested: false,
+      offscreenPresentActive: false,
+      workerOffscreenRequested: false,
+      workerOffscreenActive: false,
+      rollbackReason: null
+    };
+    this._lastGameDrawSignature = '';
+    this._lastGuiDrawSignature = '';
+    this._lastGameOverlayDrawSignature = '';
+    this._lastGuiOverlayDrawSignature = '';
+    this._gameOverlayVisible = false;
+    this._guiOverlayVisible = false;
+    this._overlayVisibilityVersion = 0;
+    this._lastOverlayVisibilityVersion = 0;
+    this.panEnabled = true;
+    this._resizeRaf = 0;
+    this._lastStageWidth = NaN;
+    this._lastStageHeight = NaN;
+    this._overlayFallbackCanvas = null;
+    this._overlayFallbackCtx = null;
+    this._overlayFallbackImageData = null;
+    this._overlayFallbackBuffer32 = null;
+    this._overlayFallbackDisplay = { buffer32: null, imgData: null };
+    this._scaleProvider = typeof options.getScale === 'function' ? options.getScale : null;
+
+    this.cursorCanvas = null;
+    this.cursorX = 0;
+    this.cursorY = 0;
+    this._lastCursorX = Number.NaN;
+    this._lastCursorY = Number.NaN;
+    this._lastCursorHasSprite = false;
+    this._cursorStateVersion = 0;
+    this._lastCursorStateVersion = 0;
+    this.guiEnabled = true;
+    this.hudMargin = 20;
+
+    this.stageCav = canvasForOutput;
+    this.stageCtx = canvasForOutput.getContext('2d', { alpha: true, willReadFrequently: true });
+    this.stageCtx.imageSmoothingEnabled = false;
+    this._ctxAlpha = 1;
+    this._ctxFillStyle = '';
+    this._ctxStrokeStyle = '';
+    this.gameImgProps = new StageImageProperties();
+    this.guiImgProps  = new StageImageProperties();
+    this.gameOverlayImgProps = new StageImageProperties();
+    this.guiOverlayImgProps = new StageImageProperties();
+
+    // HUD always starts at scale = 4
+    this.guiImgProps.viewPoint = new ViewPoint(0, 0, 4);
+    this.gameOverlayImgProps.viewPoint = this.gameImgProps.viewPoint;
+    this.guiOverlayImgProps.viewPoint = this.guiImgProps.viewPoint;
+    this._rawScale = this.gameImgProps.viewPoint.scale || 1;
+
+    // Initialize DisplayImage instances
+    this.getGameDisplay();
+    this.getGuiDisplay();
+
+    this.controller = new UserInputManager(canvasForOutput, {
+      passiveMouseMove: true
+    });
+    this.handleOnMouseUp();
+    this.handleOnMouseDown();
+    this.handleOnMouseRightUp();
+    this.handleOnMouseRightDown();
+    this.handleOnMouseMove();
+    this.handleOnDoubleClick();
+    this.handleOnZoom();
+
+    this.updateStageSize();
+    this.clear();
+  }
+
+  clear(stageImage) {
+    const start = this._perfTrackingFrame ? perfNow() : 0;
+    const ctx = this.stageCtx;
+    this._setFillStyle('#000900');
+    if (!stageImage) {
+      ctx.fillRect(0, 0, ctx.canvas.width, ctx.canvas.height);
+    } else {
+      ctx.fillRect(stageImage.x, stageImage.y, stageImage.width, stageImage.height);
+    }
+    if (this._perfTrackingFrame) {
+      this._perfClearMs += perfNow() - start;
+    }
+  }
+
+  drawPerfOverlay() {
+    const ctx = this.stageCtx;
+    const snap = this.getPerfSnapshot();
+    const lines = [
+      `frame ${this._perfFrameMs.toFixed(2)}ms`,
+      `draw ${this._perfDrawMs.toFixed(2)}ms clear ${this._perfClearMs.toFixed(2)}ms`,
+      `peak ${this._perfFramePeakMs.toFixed(2)}ms`,
+      `p95 ${snap.frame.p95.toFixed(2)} p99 ${snap.frame.p99.toFixed(2)} worst ${snap.frame.worst.toFixed(2)}`,
+      `damage r${snap.lastDamage.regionCount} a${(snap.lastDamage.dirtyAreaRatio * 100).toFixed(1)}% u${snap.lastDamage.uploadCalls}`,
+      `alloc rc${snap.lastAllocations.rectListCreated} tc${snap.lastAllocations.tileListCreated}`
+    ];
+    if (this.perfOverlayProvider) {
+      const data = this.perfOverlayProvider() || {};
+      if (Array.isArray(data.lines)) {
+        for (const line of data.lines) {
+          if (line) lines.push(String(line));
+        }
+      }
+    }
+    const x = 8;
+    const y = 8;
+    const lineH = 12;
+    const width = 280;
+    const height = (lines.length * lineH) + 8;
+    this._setGlobalAlpha(0.6);
+    this._setFillStyle('#000');
+    ctx.fillRect(x - 4, y - 4, width, height);
+    this._setGlobalAlpha(1);
+    this._setFillStyle('#8cf');
+    ctx.font = '11px monospace';
+    ctx.textBaseline = 'top';
+    for (let i = 0; i < lines.length; i++) {
+      ctx.fillText(lines[i], x, y + (i * lineH));
+    }
+  }
+}
+for (const methods of [
+  stagePerfMethods,
+  stageInputMethods,
+  stageCompositorMethods,
+  stageOverlaysMethods
+]) {
+  Object.defineProperties(Stage.prototype, Object.getOwnPropertyDescriptors(methods));
+}
+export { Stage };
\ No newline at end of file
diff --git a/js/render/stage/StageInput.js b/js/render/stage/StageInput.js
new file mode 100644
index 00000000..ca56d2e2
--- /dev/null
+++ b/js/render/stage/StageInput.js
@@ -0,0 +1,437 @@
+import {
+  COLOR_FN_RE,
+  COLOR_RE,
+  DAMAGE_FULL_REDRAW_AREA_RATIO,
+  DAMAGE_FULL_REDRAW_REGION_THRESHOLD,
+  DIRTY_RECT_FULL_BLIT_AREA_RATIO,
+  DIRTY_RECT_FULL_BLIT_THRESHOLD,
+  DIRTY_UNION_BLIT_RATIO,
+  DisplayImage,
+  PERF_SAMPLE_WINDOW,
+  Position2D,
+  StageImageProperties,
+  UserInputManager,
+  ViewPoint,
+  clamp,
+  colorStringTo32,
+  detectRuntimeCapabilities,
+  drawMarchingAntRect,
+  getDependency,
+  percentile,
+  perfNow,
+  resolveRenderExperimentState,
+  summarizeSamples,
+  toAlpha,
+  toChannel,
+  toFiniteNumber
+} from './StageShared.js';
+const stageInputMethods = {
+  setCursorSprite(frame) {
+    if (!frame) {
+      this.cursorCanvas = null;
+      // Force redraw even if cursor position is unchanged.
+      this._cursorStateVersion += 1;
+      return;
+    }
+    if (typeof document === 'undefined' || typeof document.createElement !== 'function') {
+      this.cursorCanvas = null;
+      this._cursorStateVersion += 1;
+      return;
+    }
+    const c = document.createElement('canvas');
+    c.width = frame.width;
+    c.height = frame.height;
+    const ictx = c.getContext('2d', { alpha: true, willReadFrequently: true});
+    if (!ictx) {
+      this.cursorCanvas = null;
+      this._cursorStateVersion += 1;
+      return;
+    }
+    ictx.putImageData(
+      new ImageData(frame.getData(), frame.width, frame.height),
+      0,
+      0
+    );
+    this.cursorCanvas = c;
+    // Sprite updates must invalidate the cursor plane for the next redraw.
+    this._cursorStateVersion += 1;
+  },
+
+  setGuiEnabled(enabled) {
+    this.guiEnabled = !!enabled;
+    if (!this.guiEnabled) {
+      this.guiImgProps.display = null;
+      this.guiOverlayImgProps.display = null;
+      this._guiOverlayVisible = false;
+      this._lastGuiOverlayDrawSignature = '';
+    }
+    this.updateStageSize();
+  },
+
+  calcPosition2D(stageImage, e) {
+    const localX = e.x - stageImage.x;
+    const localY = e.y - stageImage.y;
+    const worldX = stageImage.viewPoint.getSceneX(localX);
+    const worldY = stageImage.viewPoint.getSceneY(localY);
+    return new Position2D(worldX, worldY);
+  },
+
+  handleOnDoubleClick() {
+    this.controller.onDoubleClick.on((e) => {
+      const stageImage = this.getStageImageAt(e.x, e.y);
+      if (!stageImage || !stageImage.display) return;
+      const pos = this.calcPosition2D(stageImage, e);
+      stageImage.display.onDoubleClick.trigger(pos);
+    });
+  },
+
+  handleOnMouseDown() {
+    this.controller.onMouseDown.on((e) => {
+      const stageImage = this.getStageImageAt(e.x, e.y);
+      if (!stageImage || !stageImage.display) return;
+      const pos = this.calcPosition2D(stageImage, e);
+      stageImage.display.onMouseDown.trigger(pos);
+    });
+  },
+
+  handleOnMouseUp() {
+    this.controller.onMouseUp.on((e) => {
+      const stageImage = this.getStageImageAt(e.x, e.y);
+      if (!stageImage || !stageImage.display) return;
+      const pos = this.calcPosition2D(stageImage, e);
+      stageImage.display.onMouseUp.trigger(pos);
+    });
+  },
+
+  handleOnMouseRightDown() {
+    this.controller.onMouseRightDown.on((e) => {
+      const stageImage = this.getStageImageAt(e.x, e.y);
+      if (!stageImage || !stageImage.display) return;
+      const pos = this.calcPosition2D(stageImage, e);
+      stageImage.display.onMouseRightDown.trigger(pos);
+    });
+  },
+
+  handleOnMouseRightUp() {
+    this.controller.onMouseRightUp.on((e) => {
+      const stageImage = this.getStageImageAt(e.x, e.y);
+      if (!stageImage || !stageImage.display) return;
+      const pos = this.calcPosition2D(stageImage, e);
+      stageImage.display.onMouseRightUp.trigger(pos);
+    });
+  },
+
+  handleOnMouseMove() {
+    this.controller.onMouseMove.on((e) => {
+      this.cursorX = e.x;
+      this.cursorY = e.y;
+
+      if (e.button) {
+        const stageImage = this.getStageImageAt(e.mouseDownX, e.mouseDownY);
+        if (!stageImage || !stageImage.display) return;
+        if (this.panEnabled && stageImage === this.gameImgProps) {
+          this.updateViewPoint(stageImage, e.deltaX, e.deltaY, 0);
+        }
+        const pos = this.calcPosition2D(stageImage, e);
+        stageImage.display.onMouseMove.trigger(pos);
+      } else {
+        const stageImage = this.getStageImageAt(e.x, e.y);
+        if (!stageImage || !stageImage.display) return;
+        const localX = e.x - stageImage.x;
+        const localY = e.y - stageImage.y;
+        const worldX = stageImage.viewPoint.getSceneX(localX);
+        const worldY = stageImage.viewPoint.getSceneY(localY);
+        stageImage.display.onMouseMove.trigger(
+          new Position2D(worldX, worldY)
+        );
+
+      }
+    });
+  },
+
+  handleOnZoom() {
+    this.controller.onZoom.on((e) => {
+      const stageImage = this.gameImgProps;
+      if (!stageImage || !stageImage.display) return;
+
+      // Always zoom around the cursor position e.x,e.y
+      this.updateViewPoint(stageImage, e.x, e.y, e.deltaZoom, e.velocity);
+    });
+  },
+
+  updateViewPoint(stageImage, argX, argY, deltaZoom, veloUpdate = false) {
+    if (!stageImage || !stageImage.display) return;
+
+    let targetScale = stageImage.viewPoint.scale || 1;
+    let targetX = stageImage.viewPoint.x;
+    let targetY = stageImage.viewPoint.y;
+
+    if (deltaZoom !== 0) {
+      const screenX_rel = argX - stageImage.x;
+      const screenY_rel = argY - stageImage.y;
+
+      const sceneX_pre = stageImage.viewPoint.getSceneX(screenX_rel);
+      const sceneY_pre = stageImage.viewPoint.getSceneY(screenY_rel);
+
+      const zoomSensitivity = 0.001125;
+      const desiredScale = targetScale + deltaZoom * zoomSensitivity;
+      const snappedScale = this.snapScale(desiredScale);
+      targetScale = snappedScale;
+
+      if (!veloUpdate && snappedScale !== stageImage.viewPoint.scale) {
+        targetX = sceneX_pre - screenX_rel / targetScale;
+        targetY = sceneY_pre - screenY_rel / targetScale;
+      }
+    } else {
+      targetX += argX / targetScale;
+      targetY += argY / targetScale;
+    }
+    const imgData = stageImage.display.getImageData();
+    const shouldRedrawGui = !!(
+      this.guiEnabled &&
+        stageImage === this.guiImgProps &&
+        this.guiImgProps.display?.getImageData
+    );
+    const guiImgData = shouldRedrawGui ? this.guiImgProps.display.getImageData() : null;
+    this.applyViewport(stageImage, targetX, targetY, targetScale);
+    this.clear(stageImage);
+    if (shouldRedrawGui) {
+      this.clear(this.guiImgProps);
+    }
+    this.draw(stageImage, imgData);
+    if (shouldRedrawGui) {
+      this.draw(this.guiImgProps, guiImgData);
+    }
+  },
+
+  snapScale(rawScale) {
+    const { width: dispW, height: dispH } = this.gameImgProps.display.worldDataSize;
+    if (dispW === 0 || dispH === 0) return rawScale;
+
+    const gcd = (a, b) => (b ? gcd(b, a % b) : a);
+    const g = gcd(dispW, dispH);
+    const step = 1 / g;
+
+    const minScale = 0.25;
+    const maxScale = 8;
+    let clamped = rawScale;
+    if (clamped < minScale) clamped = minScale;
+    if (clamped > maxScale) clamped = maxScale;
+
+    return Math.round(clamped / step) * step;
+  },
+
+  applyViewport(stageImage, targetX, targetY, targetScale) {
+    if (!stageImage || !stageImage.display) return;
+
+    this._rawScale = targetScale;
+    stageImage.viewPoint.scale = this.snapScale(targetScale);
+    stageImage.viewPoint.setX(targetX);
+    stageImage.viewPoint.setY(targetY);
+
+    this.clampViewPoint(stageImage);
+  },
+
+  scheduleUpdateStageSize() {
+    if (this._resizeRaf) return;
+    if (typeof window === 'undefined' || typeof window.requestAnimationFrame !== 'function') {
+      this.updateStageSize();
+      return;
+    }
+    this._resizeRaf = window.requestAnimationFrame(() => {
+      this._resizeRaf = 0;
+      this.updateStageSize(true);
+    });
+  },
+
+  updateStageSize(fromResize = false) {
+    const stageH = this.stageCav.height;
+    const stageW = this.stageCav.width;
+    if (fromResize && stageW === this._lastStageWidth && stageH === this._lastStageHeight) {
+      const gameDirty = this.gameImgProps.display?.hasPendingDirty?.() === true;
+      const guiDirty = this.guiEnabled && this.guiImgProps.display?.hasPendingDirty?.() === true;
+      if (!gameDirty && !guiDirty) return;
+    }
+    this._lastStageWidth = stageW;
+    this._lastStageHeight = stageH;
+    const guiActive = this.guiEnabled && !!this.guiImgProps.display;
+    // this margin is for the level <select> elements in the html
+    const margin = guiActive ? this.hudMargin : 0;
+
+    // HUD scale adapts to available space
+    const rawHUDH = guiActive ? (this.guiImgProps.display?.worldDataSize.height || 80) : 0;
+    const rawHUDW = guiActive ? (this.guiImgProps.display?.worldDataSize.width || 720) : 0;
+
+    const maxScaleW = guiActive && rawHUDW ? stageW / rawHUDW : 1;
+    const maxScaleH = guiActive && rawHUDH ? (stageH - margin) / rawHUDH : 1;
+    let hudScale = guiActive ? Math.min(4, maxScaleW, maxScaleH) : 1;
+    if (!isFinite(hudScale) || hudScale <= 0) hudScale = 1;
+    this.guiImgProps.viewPoint.scale = hudScale;
+
+    const hudH = guiActive ? rawHUDH * hudScale : 0;
+    const hudW = guiActive ? rawHUDW * hudScale : 0;
+
+    const gameH = Math.max(0, stageH - hudH - margin);
+
+    Object.assign(this.gameImgProps, { x: 0, y: 0 });
+    this.gameImgProps.canvasViewportSize = { width: stageW, height: gameH };
+    Object.assign(this.guiImgProps, {
+      x: guiActive ? (stageW - hudW) / 2 : 0,
+      y: guiActive ? (stageH - hudH - margin) : 0
+    });
+    this.guiImgProps.canvasViewportSize = { width: hudW, height: hudH };
+    this._syncOverlayLayout();
+
+    if (this.gameImgProps.display) {
+      const { width: worldW, height: worldH } = this.gameImgProps.display.worldDataSize;
+
+      const scale = this.gameImgProps.viewPoint.scale || 2;
+      const viewH_world = gameH / scale;
+      const viewW_world = stageW / scale;
+
+      let x = this.gameImgProps.viewPoint.x;
+      let y = this.gameImgProps.viewPoint.y;
+      if (!isFinite(x)) x = 0;
+      if (!isFinite(y)) y = 0;
+
+      if (worldW * scale <= stageW) {
+        x = (worldW - viewW_world) / 2;
+      }
+
+      this.applyViewport(this.gameImgProps, x, y, scale);
+
+      // Redraw at initial position
+      this.clear(this.gameImgProps);
+      const gameImg = this.gameImgProps.display.getImageData();
+      this.draw(this.gameImgProps, gameImg);
+    }
+
+    if (guiActive && this.guiImgProps.display) {
+      const guiImg = this.guiImgProps.display.getImageData();
+      this.draw(this.guiImgProps, guiImg);
+    }
+
+    this._syncOverlayDisplaySize(this.gameImgProps, this.gameOverlayImgProps);
+    this._syncOverlayDisplaySize(this.guiImgProps, this.guiOverlayImgProps);
+  },
+
+  getStageImageAt(x, y) {
+    const { width: gameW, height: gameH } =
+        this.gameImgProps.canvasViewportSize;
+    if (
+      x >= this.gameImgProps.x &&
+        x <  this.gameImgProps.x + gameW &&
+        y >= this.gameImgProps.y &&
+        y <  this.gameImgProps.y + gameH
+    ) {
+      return this.gameImgProps;
+    }
+    const { width: guiW, height: guiH } =
+        this.guiImgProps.canvasViewportSize;
+    if (
+      x >= this.guiImgProps.x &&
+        x <  this.guiImgProps.x + guiW &&
+        y >= this.guiImgProps.y &&
+        y <  this.guiImgProps.y + guiH
+    ) {
+      return this.guiImgProps;
+    }
+    return null;
+  },
+
+  getGameDisplay() {
+    if (this.gameImgProps.display) return this.gameImgProps.display;
+    this.gameImgProps.display = new DisplayImage(this);
+    return this.gameImgProps.display;
+  },
+
+  getGuiDisplay() {
+    if (this.guiImgProps.display) return this.guiImgProps.display;
+    this.guiImgProps.display = new DisplayImage(this);
+    return this.guiImgProps.display;
+  },
+
+  getGameOverlayDisplay() {
+    if (this.gameOverlayImgProps.display) return this.gameOverlayImgProps.display;
+    this.gameOverlayImgProps.display = new DisplayImage(this);
+    this._syncOverlayDisplaySize(this.gameImgProps, this.gameOverlayImgProps);
+    this.gameOverlayImgProps.display.clear(0x00000000);
+    return this.gameOverlayImgProps.display;
+  },
+
+  getGuiOverlayDisplay() {
+    if (this.guiOverlayImgProps.display) return this.guiOverlayImgProps.display;
+    this.guiOverlayImgProps.display = new DisplayImage(this);
+    this._syncOverlayDisplaySize(this.guiImgProps, this.guiOverlayImgProps);
+    this.guiOverlayImgProps.display.clear(0x00000000);
+    return this.guiOverlayImgProps.display;
+  },
+
+  setGameOverlayVisible(visible) {
+    const nextVisible = !!visible;
+    if (this._gameOverlayVisible === nextVisible) return;
+    this._gameOverlayVisible = nextVisible;
+    this._overlayVisibilityVersion += 1;
+  },
+
+  setGuiOverlayVisible(visible) {
+    const nextVisible = !!visible;
+    if (this._guiOverlayVisible === nextVisible) return;
+    this._guiOverlayVisible = nextVisible;
+    this._overlayVisibilityVersion += 1;
+  },
+
+  setGameViewPointPosition(x, y, options = {}) {
+    const targetX = isFinite(x) ? x : 0;
+    const targetY = isFinite(y) ? y : 0;
+    const preserveScale = options.preserveScale === true;
+    if (preserveScale) {
+      const rawScale = Number.isFinite(this._rawScale)
+        ? this._rawScale
+        : (this.gameImgProps.viewPoint.scale || 1);
+      this._rawScale = rawScale;
+      this.applyViewport(this.gameImgProps, targetX, targetY, rawScale);
+      this.redraw(true);
+      return;
+    }
+
+    const requestedScale = this._getRequestedScale();
+    if (requestedScale > 0) {
+      this._rawScale = requestedScale;
+      this.gameImgProps.viewPoint.scale = this.snapScale(this._rawScale);
+      this.gameImgProps.viewPoint.setX(targetX);
+      this.gameImgProps.viewPoint.setY(targetY);
+      this.clampViewPoint(this.gameImgProps);
+
+      this.redraw(true);
+      return;
+    }
+
+    let scale = this.gameImgProps.viewPoint.scale;
+    if (scale === 2) {
+      this._rawScale = scale;
+      this.gameImgProps.viewPoint.scale = this.snapScale(this._rawScale);
+      this.gameImgProps.viewPoint.setX(targetX);
+      this.gameImgProps.viewPoint.setY(targetY);
+      this.clampViewPoint(this.gameImgProps);
+
+      this.redraw(true);
+      return;
+    }
+
+    const sceneX = this.gameImgProps.viewPoint.getSceneX(targetX - this.gameImgProps.x);
+    const sceneY = this.gameImgProps.viewPoint.getSceneY(targetY - this.gameImgProps.y);
+    this._rawScale = 2;
+    this.gameImgProps.viewPoint.scale = this.snapScale(this._rawScale);
+    this.gameImgProps.viewPoint.setX(
+      sceneX - (targetX - this.gameImgProps.x) / this.gameImgProps.viewPoint.scale
+    );
+    this.gameImgProps.viewPoint.setY(
+      sceneY - (targetY - this.gameImgProps.y) / this.gameImgProps.viewPoint.scale
+    );
+    this.clampViewPoint(this.gameImgProps);
+
+    this.redraw(true);
+  }
+};
+export { stageInputMethods };
\ No newline at end of file
diff --git a/js/render/stage/StageOverlays.js b/js/render/stage/StageOverlays.js
new file mode 100644
index 00000000..1c28fb41
--- /dev/null
+++ b/js/render/stage/StageOverlays.js
@@ -0,0 +1,484 @@
+import {
+  COLOR_FN_RE,
+  COLOR_RE,
+  DAMAGE_FULL_REDRAW_AREA_RATIO,
+  DAMAGE_FULL_REDRAW_REGION_THRESHOLD,
+  DIRTY_RECT_FULL_BLIT_AREA_RATIO,
+  DIRTY_RECT_FULL_BLIT_THRESHOLD,
+  DIRTY_UNION_BLIT_RATIO,
+  DisplayImage,
+  PERF_SAMPLE_WINDOW,
+  Position2D,
+  StageImageProperties,
+  UserInputManager,
+  ViewPoint,
+  clamp,
+  colorStringTo32,
+  detectRuntimeCapabilities,
+  drawMarchingAntRect,
+  getDependency,
+  percentile,
+  perfNow,
+  resolveRenderExperimentState,
+  summarizeSamples,
+  toAlpha,
+  toChannel,
+  toFiniteNumber
+} from './StageShared.js';
+const stageOverlaysMethods = {
+  resetFade() {
+    this.fadeAlpha = 0;
+    this.overlayAlpha = 0;
+    this.overlayRect = null;
+    this.fadeTimer = this.overlayTimer = 0;
+    this._fadeOutActive = false;
+    this._overlayFadeActive = false;
+    this._fadeClockMs = NaN;
+    this._fadeDashAccumulator = 0;
+  },
+
+  startFadeOut() {
+    this.fadeAlpha = 0;
+    this.fadeTimer = 1;
+    this._fadeOutActive = true;
+    this._fadeClockMs = perfNow();
+  },
+
+  startOverlayFade(color, rect = null, dashLen = 0) {
+    this.overlayColor = color;
+    this.overlayRect = rect;
+    this.overlayDashLen = dashLen;
+    this.overlayDashColor = colorStringTo32(color);
+    this.overlayDashOffset = 0;
+    this.overlayAlpha = 1;
+    this.overlayTimer = 1;
+    this._overlayFadeActive = true;
+    this._fadeDashAccumulator = 0;
+    if (!this._fadeClockMs) this._fadeClockMs = perfNow();
+  },
+
+  resetOverlayFade() {
+    this.overlayAlpha = 0;
+    this.overlayRect = null;
+    this.overlayDashLen = 0;
+    this.overlayTimer = 0;
+    this._overlayFadeActive = false;
+    this._fadeDashAccumulator = 0;
+    if (!this._fadeOutActive) this._fadeClockMs = NaN;
+  },
+
+  _updateFadeState(nowMs) {
+    if (!this._fadeOutActive && !this._overlayFadeActive) return;
+    const now = Number.isFinite(nowMs) ? nowMs : perfNow();
+    if (!Number.isFinite(this._fadeClockMs)) {
+      this._fadeClockMs = now;
+      return;
+    }
+    const deltaMs = Math.max(0, now - this._fadeClockMs);
+    if (deltaMs <= 0) return;
+    this._fadeClockMs = now;
+
+    const alphaStep = deltaMs * (0.02 / 40);
+    if (this._fadeOutActive) {
+      this.fadeAlpha = Math.min(this.fadeAlpha + alphaStep, 1);
+      if (this.fadeAlpha >= 1) {
+        this._fadeOutActive = false;
+        this.fadeTimer = 0;
+      }
+    }
+
+    if (this._overlayFadeActive) {
+      this.overlayAlpha = Math.max(this.overlayAlpha - alphaStep, 0);
+      const dashLen = this.overlayDashLen || 0;
+      if (dashLen > 0) {
+        this._fadeDashAccumulator += deltaMs * (1 / 40);
+        const steps = Math.trunc(this._fadeDashAccumulator);
+        if (steps > 0) {
+          const pattern = Math.max(1, dashLen * 2);
+          this.overlayDashOffset = (this.overlayDashOffset + steps) % pattern;
+          this._fadeDashAccumulator -= steps;
+        }
+      }
+      if (this.overlayAlpha <= 0) {
+        this.overlayAlpha = 0;
+        this.overlayRect = null;
+        this.overlayDashLen = 0;
+        this.overlayTimer = 0;
+        this._overlayFadeActive = false;
+        this._fadeDashAccumulator = 0;
+      }
+    }
+
+    if (!this._fadeOutActive && !this._overlayFadeActive) {
+      this._fadeClockMs = NaN;
+    }
+  },
+
+  dispose() {
+    this.resetFade();
+    if (this._resizeRaf) {
+      if (typeof window !== 'undefined' && typeof window.cancelAnimationFrame === 'function') {
+        window.cancelAnimationFrame(this._resizeRaf);
+      }
+      this._resizeRaf = 0;
+    }
+    if (this.gameImgProps.display?.dispose) this.gameImgProps.display.dispose();
+    if (this.guiImgProps.display?.dispose)  this.guiImgProps.display.dispose();
+    if (this.gameOverlayImgProps.display?.dispose) this.gameOverlayImgProps.display.dispose();
+    if (this.guiOverlayImgProps.display?.dispose)  this.guiOverlayImgProps.display.dispose();
+    if (this.controller?.dispose)            this.controller.dispose();
+    this.controller = null;
+    this.gameImgProps = null;
+    this.guiImgProps  = null;
+    this.gameOverlayImgProps = null;
+    this.guiOverlayImgProps = null;
+    this.stageCtx = null;
+    this.stageCav     = null;
+    this._overlayFallbackCanvas = null;
+    this._overlayFallbackCtx = null;
+    this._overlayFallbackImageData = null;
+    this._overlayFallbackBuffer32 = null;
+    this._overlayFallbackDisplay = null;
+  },
+
+  draw(display, img, options = {}) {
+    const applyStageEffects = options.applyStageEffects !== false;
+    const start = this._perfTrackingFrame ? perfNow() : 0;
+    if (!display.ctx) return;
+    if (!img || !Number.isFinite(img.width) || !Number.isFinite(img.height) || img.width < 1 || img.height < 1) {
+      return;
+    }
+
+    const displayImage = display.display;
+    const dirtyTiles = displayImage?.consumeDirtyTiles?.();
+    const dirtyRects = displayImage?.consumeDirtyRects?.();
+    const hasTileSupport = dirtyTiles !== undefined;
+    const hasRectUpdates = dirtyRects === null || (Array.isArray(dirtyRects) && dirtyRects.length > 0);
+    const useTileUpdates = hasTileSupport && (
+      dirtyTiles === null ||
+        (Array.isArray(dirtyTiles) && dirtyTiles.length > 0) ||
+        !hasRectUpdates
+    );
+    const dirtyRegions = useTileUpdates ? dirtyTiles : dirtyRects;
+    const damageStats = {
+      regionCount: 0,
+      dirtyArea: 0,
+      fullArea: img.width * img.height,
+      uploadCalls: 0,
+      fullBlit: false,
+      usedTiles: useTileUpdates
+    };
+    try {
+      if (dirtyRegions === null) {
+        display.ctx.putImageData(img, 0, 0);
+        damageStats.regionCount = 1;
+        damageStats.dirtyArea = damageStats.fullArea;
+        damageStats.uploadCalls = 1;
+        damageStats.fullBlit = true;
+      } else if (dirtyRegions.length) {
+        damageStats.regionCount = dirtyRegions.length;
+        const decision = this._shouldUseFullBlit(
+          dirtyRegions,
+          damageStats.fullArea,
+          this._frameDamageStats
+        );
+        let useFullBlit = decision.useFull;
+        damageStats.dirtyArea = decision.dirtyArea;
+        if (useFullBlit) {
+          display.ctx.putImageData(img, 0, 0);
+          damageStats.uploadCalls = 1;
+          damageStats.fullBlit = true;
+          damageStats.dirtyArea = damageStats.fullArea;
+        } else {
+          const union = this._renderExperiments.offscreenPresentActive
+            ? this._computeDirtyUnion(dirtyRegions)
+            : null;
+          const unionArea = union ? (union.width * union.height) : 0;
+          const useUnion = !!union && unionArea <= (damageStats.dirtyArea * DIRTY_UNION_BLIT_RATIO);
+          if (useUnion) {
+            try {
+              display.ctx.putImageData(
+                img,
+                0,
+                0,
+                union.x,
+                union.y,
+                union.width,
+                union.height
+              );
+              damageStats.uploadCalls = 1;
+              damageStats.regionCount = 1;
+              damageStats.dirtyArea = unionArea;
+            } catch {
+              this._renderExperiments.offscreenPresentActive = false;
+              this._renderExperiments.rollbackReason = 'offscreen_present_runtime_error';
+              for (let i = 0; i < dirtyRegions.length; i += 1) {
+                const rect = dirtyRegions[i];
+                display.ctx.putImageData(
+                  img,
+                  0,
+                  0,
+                  rect.x,
+                  rect.y,
+                  rect.width,
+                  rect.height
+                );
+              }
+              damageStats.uploadCalls = dirtyRegions.length;
+            }
+          } else {
+            for (let i = 0; i < dirtyRegions.length; i += 1) {
+              const rect = dirtyRegions[i];
+              display.ctx.putImageData(
+                img,
+                0,
+                0,
+                rect.x,
+                rect.y,
+                rect.width,
+                rect.height
+              );
+            }
+            damageStats.uploadCalls = dirtyRegions.length;
+          }
+        }
+      }
+    } finally {
+      if (useTileUpdates) {
+        displayImage?.releaseConsumedDirtyTiles?.(dirtyTiles);
+      }
+      displayImage?.releaseConsumedDirtyRects?.(dirtyRects);
+      this._accumulateFrameDamage(damageStats);
+    }
+
+    const ctx = this.stageCtx;
+    this._setGlobalAlpha(1);
+
+    let sx = display.viewPoint.x;
+    let sy = display.viewPoint.y;
+    let sw = img.width - sx;
+    let sh = img.height - sy;
+    if (sx < 0) {
+      sw += sx;
+      sx = 0;
+    }
+    if (sy < 0) {
+      sh += sy;
+      sy = 0;
+    }
+    sw = Math.min(sw, img.width - sx);
+    sh = Math.min(sh, img.height - sy);
+
+    const dx = display.x + Math.max(-display.viewPoint.x, 0) * display.viewPoint.scale;
+    const dy = display.y + Math.max(-display.viewPoint.y, 0) * display.viewPoint.scale;
+    let dw = sw * display.viewPoint.scale;
+    let dh = sh * display.viewPoint.scale;
+
+    if (dw > display.width) {
+      sw = display.width / display.viewPoint.scale;
+      dw = display.width;
+    }
+    if (dh > display.height) {
+      sh = display.height / display.viewPoint.scale;
+      dh = display.height;
+    }
+
+    ctx.drawImage(
+      display.cav,
+      sx,
+      sy,
+      sw,
+      sh,
+      dx,
+      dy,
+      Math.trunc(dw),
+      Math.trunc(dh)
+    );
+
+    if (applyStageEffects && this.fadeAlpha !== 0) {
+      this._setGlobalAlpha(this.fadeAlpha);
+      this._setFillStyle('black');
+      ctx.fillRect(display.x, display.y, Math.trunc(dw), Math.trunc(dh));
+      this._setGlobalAlpha(1);
+    }
+
+    if (applyStageEffects && this.overlayAlpha > 0) {
+      this._setGlobalAlpha(this.overlayAlpha);
+      this._setFillStyle(this.overlayColor);
+      const r = this.overlayRect || {
+        x: display.x,
+        y: display.y,
+        width: Math.trunc(dw),
+        height: Math.trunc(dh),
+      };
+      ctx.fillRect(r.x, r.y, r.width, r.height);
+      this._setGlobalAlpha(1);
+      if (this.overlayDashLen > 0) {
+        const octx = this.stageCtx;
+        if (typeof octx.setLineDash === 'function' && typeof octx.strokeRect === 'function') {
+          this._setGlobalAlpha(this.overlayAlpha);
+          this._setStrokeStyle(this.overlayColor);
+          octx.lineWidth = 1;
+          octx.setLineDash([this.overlayDashLen, this.overlayDashLen]);
+          octx.lineDashOffset = -this.overlayDashOffset;
+          octx.strokeRect(r.x + 0.5, r.y + 0.5, Math.max(0, r.width - 1), Math.max(0, r.height - 1));
+          octx.setLineDash([]);
+          octx.lineDashOffset = 0;
+          this._setGlobalAlpha(1);
+        } else {
+          const fallbackSurface = this._ensureOverlayFallbackSurface(r.width + 1, r.height + 1);
+          const drawAnts = getDependency('drawMarchingAntRect', drawMarchingAntRect);
+          if (fallbackSurface) {
+            fallbackSurface.buffer32.fill(0);
+            this._overlayFallbackDisplay.buffer32 = fallbackSurface.buffer32;
+            this._overlayFallbackDisplay.imgData = fallbackSurface.imageData;
+            drawAnts(
+              this._overlayFallbackDisplay,
+              0,
+              0,
+              r.width,
+              r.height,
+              this.overlayDashLen,
+              this.overlayDashOffset,
+              this.overlayDashColor,
+              0x00000000
+            );
+            fallbackSurface.ctx.putImageData(fallbackSurface.imageData, 0, 0);
+            this._setGlobalAlpha(this.overlayAlpha);
+            octx.drawImage(fallbackSurface.canvas, r.x, r.y);
+            this._setGlobalAlpha(1);
+          } else {
+            const img = octx.getImageData(r.x, r.y, r.width + 1, r.height + 1);
+            const disp = { buffer32: new Uint32Array(img.data.buffer), imgData: img };
+            drawAnts(
+              disp,
+              0,
+              0,
+              r.width,
+              r.height,
+              this.overlayDashLen,
+              this.overlayDashOffset,
+              this.overlayDashColor,
+              0x00000000
+            );
+            octx.putImageData(img, r.x, r.y);
+          }
+        }
+      }
+    }
+    if (this._perfTrackingFrame) {
+      this._perfDrawMs += perfNow() - start;
+    }
+  },
+
+  drawCursor() {
+    if (!this.cursorCanvas) return;
+    const ctx = this.stageCtx;
+    const cx = Math.trunc(this.cursorX - this.cursorCanvas.width / 2);
+    const cy = Math.trunc(this.cursorY - this.cursorCanvas.height / 2);
+    ctx.drawImage(this.cursorCanvas, cx, cy);
+  },
+
+  clampViewPoint(stageImage) {
+    if (!stageImage || !stageImage.display) return;
+    const { width: worldW, height: worldH } = stageImage.display.worldDataSize;
+    const scale = stageImage.viewPoint.scale;
+    const { width: vpW, height: vpH } = stageImage.canvasViewportSize;
+    const viewW = vpW / scale;
+    const viewH = vpH / scale;
+
+    const maxY = Math.max(worldH - viewH, 0);
+    stageImage.viewPoint.y = this.limitValue(
+      0,
+      stageImage.viewPoint.y,
+      maxY
+    );
+
+    if (worldW <= viewW) {
+      stageImage.viewPoint.x = (worldW - viewW) / 2;
+    } else {
+      stageImage.viewPoint.x = this.limitValue(
+        0,
+        stageImage.viewPoint.x,
+        worldW - viewW
+      );
+    }
+  },
+
+  getGameViewRect() {
+    return {
+      x: this.gameImgProps.viewPoint.x,
+      y: this.gameImgProps.viewPoint.y,
+      w: this.gameImgProps.canvasViewportSize.width  / this.gameImgProps.viewPoint.scale,
+      h: this.gameImgProps.canvasViewportSize.height / this.gameImgProps.viewPoint.scale
+
+    };
+  },
+
+  limitValue(minLimit, value, maxLimit) {
+    return Math.min(Math.max(minLimit, value), maxLimit);
+  },
+
+  _getDrawSignature(display) {
+    const vp = display.viewPoint;
+    return [
+      display.x,
+      display.y,
+      display.width,
+      display.height,
+      vp?.x ?? 0,
+      vp?.y ?? 0,
+      vp?.scale ?? 1
+    ].join('|');
+  },
+
+  _syncOverlayLayout() {
+    this.gameOverlayImgProps.x = this.gameImgProps.x;
+    this.gameOverlayImgProps.y = this.gameImgProps.y;
+    this.gameOverlayImgProps.canvasViewportSize = {
+      width: this.gameImgProps.width,
+      height: this.gameImgProps.height
+    };
+    this.gameOverlayImgProps.viewPoint = this.gameImgProps.viewPoint;
+    this.guiOverlayImgProps.x = this.guiImgProps.x;
+    this.guiOverlayImgProps.y = this.guiImgProps.y;
+    this.guiOverlayImgProps.canvasViewportSize = {
+      width: this.guiImgProps.width,
+      height: this.guiImgProps.height
+    };
+    this.guiOverlayImgProps.viewPoint = this.guiImgProps.viewPoint;
+  },
+
+  _syncOverlayDisplaySize(baseProps, overlayProps) {
+    const baseDisplay = baseProps?.display;
+    const overlayDisplay = overlayProps?.display;
+    if (!baseDisplay || !overlayDisplay) return;
+    const { width, height } = baseDisplay.worldDataSize;
+    if (!Number.isFinite(width) || !Number.isFinite(height) || width < 1 || height < 1) {
+      return;
+    }
+    const needsResize = overlayDisplay.getWidth() !== width || overlayDisplay.getHeight() !== height;
+    if (!needsResize) return;
+    overlayDisplay.initSize(width, height);
+    overlayDisplay.clear(0x00000000);
+  },
+
+  _setGlobalAlpha(value) {
+    if (this._ctxAlpha === value) return;
+    this.stageCtx.globalAlpha = value;
+    this._ctxAlpha = value;
+  },
+
+  _setFillStyle(value) {
+    if (this._ctxFillStyle === value) return;
+    this.stageCtx.fillStyle = value;
+    this._ctxFillStyle = value;
+  },
+
+  _setStrokeStyle(value) {
+    if (this._ctxStrokeStyle === value) return;
+    this.stageCtx.strokeStyle = value;
+    this._ctxStrokeStyle = value;
+  }
+};
+export { stageOverlaysMethods };
\ No newline at end of file
diff --git a/js/render/stage/StagePerf.js b/js/render/stage/StagePerf.js
new file mode 100644
index 00000000..60b7dfd3
--- /dev/null
+++ b/js/render/stage/StagePerf.js
@@ -0,0 +1,148 @@
+import {
+  COLOR_FN_RE,
+  COLOR_RE,
+  DAMAGE_FULL_REDRAW_AREA_RATIO,
+  DAMAGE_FULL_REDRAW_REGION_THRESHOLD,
+  DIRTY_RECT_FULL_BLIT_AREA_RATIO,
+  DIRTY_RECT_FULL_BLIT_THRESHOLD,
+  DIRTY_UNION_BLIT_RATIO,
+  DisplayImage,
+  PERF_SAMPLE_WINDOW,
+  Position2D,
+  StageImageProperties,
+  UserInputManager,
+  ViewPoint,
+  clamp,
+  colorStringTo32,
+  detectRuntimeCapabilities,
+  drawMarchingAntRect,
+  getDependency,
+  percentile,
+  perfNow,
+  resolveRenderExperimentState,
+  summarizeSamples,
+  toAlpha,
+  toChannel,
+  toFiniteNumber
+} from './StageShared.js';
+const stagePerfMethods = {
+  setPerfOverlay(enabled, provider = null) {
+    this.perfOverlayEnabled = !!enabled;
+    this.perfOverlayProvider = typeof provider === 'function' ? provider : null;
+  },
+
+  setScaleProvider(provider = null) {
+    this._scaleProvider = typeof provider === 'function' ? provider : null;
+  },
+
+  _getRequestedScale() {
+    if (!this._scaleProvider) return 0;
+    try {
+      const value = Number(this._scaleProvider());
+      return Number.isFinite(value) ? value : 0;
+    } catch {
+      return 0;
+    }
+  },
+
+  setRenderExperimentFlags(flags = {}) {
+    const capabilities = detectRuntimeCapabilities();
+    this._renderExperiments = resolveRenderExperimentState(flags, capabilities);
+  },
+
+  getRenderExperimentStatus() {
+    return { ...this._renderExperiments };
+  },
+
+  getPerfSnapshot() {
+    const frameQuantiles = summarizeSamples(this._perfFrameSamples);
+    const drawQuantiles = summarizeSamples(this._perfDrawSamples);
+    const clearQuantiles = summarizeSamples(this._perfClearSamples);
+    const regionQuantiles = summarizeSamples(this._perfDirtyRegionsSamples);
+    const areaQuantiles = summarizeSamples(this._perfDirtyAreaRatioSamples);
+    const uploadQuantiles = summarizeSamples(this._perfUploadCallsSamples);
+    const allocationQuantiles = summarizeSamples(this._perfAllocationsSamples);
+    return {
+      frameMs: this._perfFrameMs,
+      drawMs: this._perfDrawMs,
+      clearMs: this._perfClearMs,
+      peakFrameMs: this._perfFramePeakMs,
+      frameCount: this._perfFrameCount,
+      frame: frameQuantiles,
+      draw: drawQuantiles,
+      clear: clearQuantiles,
+      dirtyRegions: regionQuantiles,
+      dirtyAreaRatio: areaQuantiles,
+      uploadCalls: uploadQuantiles,
+      allocations: allocationQuantiles,
+      lastDamage: { ...this._perfLastDamage },
+      lastAllocations: { ...this._perfLastAllocations },
+      experiments: this.getRenderExperimentStatus()
+    };
+  },
+
+  _pushPerfSample(samples, value) {
+    if (!Number.isFinite(value) || value < 0) return;
+    samples.push(value);
+    if (samples.length > PERF_SAMPLE_WINDOW) {
+      samples.splice(0, samples.length - PERF_SAMPLE_WINDOW);
+    }
+  },
+
+  _collectDisplayAllocationStats(display) {
+    const image = display?.display;
+    if (!image?.consumeAllocationStats) {
+      return {
+        rectListCreated: 0,
+        rectListReused: 0,
+        tileListCreated: 0,
+        tileListReused: 0
+      };
+    }
+    return image.consumeAllocationStats(true);
+  },
+
+  _shouldCollectPerfSamples() {
+    return this.perfOverlayEnabled === true;
+  },
+
+  _recordFramePerf(frameMs, drawMs, clearMs) {
+    this._pushPerfSample(this._perfFrameSamples, frameMs);
+    this._pushPerfSample(this._perfDrawSamples, drawMs);
+    this._pushPerfSample(this._perfClearSamples, clearMs);
+  },
+
+  _recordDamagePerf(stats) {
+    const regionCount = stats?.regionCount || 0;
+    const dirtyAreaRatio = stats?.dirtyAreaRatio || 0;
+    const uploadCalls = stats?.uploadCalls || 0;
+    this._pushPerfSample(this._perfDirtyRegionsSamples, regionCount);
+    this._pushPerfSample(this._perfDirtyAreaRatioSamples, dirtyAreaRatio);
+    this._pushPerfSample(this._perfUploadCallsSamples, uploadCalls);
+    this._perfLastDamage = {
+      regionCount,
+      dirtyAreaRatio,
+      uploadCalls,
+      fullBlitCount: stats?.fullBlitCount || 0,
+      tileUpdateCount: stats?.tileUpdateCount || 0
+    };
+  },
+
+  _recordAllocationPerf(stats) {
+    const rectCreated = stats?.rectListCreated || 0;
+    const rectReused = stats?.rectListReused || 0;
+    const tileCreated = stats?.tileListCreated || 0;
+    const tileReused = stats?.tileListReused || 0;
+    this._pushPerfSample(
+      this._perfAllocationsSamples,
+      rectCreated + rectReused + tileCreated + tileReused
+    );
+    this._perfLastAllocations = {
+      rectListCreated: rectCreated,
+      rectListReused: rectReused,
+      tileListCreated: tileCreated,
+      tileListReused: tileReused
+    };
+  }
+};
+export { stagePerfMethods };
\ No newline at end of file
diff --git a/js/render/stage/StageShared.js b/js/render/stage/StageShared.js
new file mode 100644
index 00000000..cc353357
--- /dev/null
+++ b/js/render/stage/StageShared.js
@@ -0,0 +1,97 @@
+import { DisplayImage, drawMarchingAntRect } from '../DisplayImage.js';
+import { Position2D } from '../../util/Position2D.js';
+import { StageImageProperties } from '../StageImageProperties.js';
+import { UserInputManager } from '../../input/UserInputManager.js';
+import { ViewPoint } from '../ViewPoint.js';
+import { getDependency } from '../../core/dependencies.js';
+import { toFiniteNumber } from '../../core/numberParsing.js';
+import {
+  detectRuntimeCapabilities,
+  resolveRenderExperimentState
+} from '../../core/capabilityMatrix.js';
+
+const COLOR_FN_RE = /^rgba?\(/i;
+const COLOR_RE = /^rgba?\(\s*([-+]?\d*\.?\d+)\s*,\s*([-+]?\d*\.?\d+)\s*,\s*([-+]?\d*\.?\d+)\s*(?:,\s*([-+]?\d*\.?\d+)\s*)?\)$/i;
+function clamp(value, min, max) {
+  return Math.min(Math.max(value, min), max);
+}
+function toChannel(value) {
+  if (!Number.isFinite(value)) return 255;
+  return clamp(Math.round(value), 0, 255);
+}
+function toAlpha(value) {
+  if (!Number.isFinite(value)) return 1;
+  return clamp(value, 0, 1);
+}
+function colorStringTo32(str) {
+  if (typeof str !== 'string') return 0xffffffff;
+  if (!COLOR_FN_RE.test(str)) return 0xffffffff;
+  const m = COLOR_RE.exec(str.trim());
+  if (!m) return 0xffffffff;
+  const r = toChannel(toFiniteNumber(m[1], NaN));
+  const g = toChannel(toFiniteNumber(m[2], NaN));
+  const b = toChannel(toFiniteNumber(m[3], NaN));
+  const a = toAlpha(toFiniteNumber(m[4], 1));
+  return ((Math.round(a * 255) & 0xff) << 24) | ((b & 0xff) << 16) | ((g & 0xff) << 8) | (r & 0xff);
+}
+const perfNow = () => {
+  if (typeof performance !== 'undefined' && typeof performance.now === 'function') {
+    return performance.now();
+  }
+  return Date.now();
+};
+const DIRTY_RECT_FULL_BLIT_THRESHOLD = 24;
+const DIRTY_RECT_FULL_BLIT_AREA_RATIO = 0.4;
+const DAMAGE_FULL_REDRAW_REGION_THRESHOLD = 48;
+const DAMAGE_FULL_REDRAW_AREA_RATIO = 0.55;
+const DIRTY_UNION_BLIT_RATIO = 1.25;
+const PERF_SAMPLE_WINDOW = 240;
+const percentile = (samples, p) => {
+  if (!Array.isArray(samples) || samples.length < 1) return 0;
+  const sorted = samples.slice().sort((a, b) => a - b);
+  const clamped = Math.min(1, Math.max(0, p));
+  const index = Math.max(0, Math.min(sorted.length - 1, Math.ceil((sorted.length - 1) * clamped)));
+  return sorted[index] || 0;
+};
+const summarizeSamples = (samples) => {
+  const clean = Array.isArray(samples)
+    ? samples.filter((value) => Number.isFinite(value) && value >= 0)
+    : [];
+  if (!clean.length) {
+    return { p50: 0, p95: 0, p99: 0, worst: 0 };
+  }
+  return {
+    p50: percentile(clean, 0.5),
+    p95: percentile(clean, 0.95),
+    p99: percentile(clean, 0.99),
+    worst: percentile(clean, 1)
+  };
+};
+
+export {
+  COLOR_FN_RE,
+  COLOR_RE,
+  DAMAGE_FULL_REDRAW_AREA_RATIO,
+  DAMAGE_FULL_REDRAW_REGION_THRESHOLD,
+  DIRTY_RECT_FULL_BLIT_AREA_RATIO,
+  DIRTY_RECT_FULL_BLIT_THRESHOLD,
+  DIRTY_UNION_BLIT_RATIO,
+  DisplayImage,
+  PERF_SAMPLE_WINDOW,
+  Position2D,
+  StageImageProperties,
+  UserInputManager,
+  ViewPoint,
+  clamp,
+  colorStringTo32,
+  detectRuntimeCapabilities,
+  drawMarchingAntRect,
+  getDependency,
+  percentile,
+  perfNow,
+  resolveRenderExperimentState,
+  summarizeSamples,
+  toAlpha,
+  toChannel,
+  toFiniteNumber
+};
diff --git a/js/solver/EditorAdvisory.js b/js/solver/EditorAdvisory.js
new file mode 100644
index 00000000..5ecf7799
--- /dev/null
+++ b/js/solver/EditorAdvisory.js
@@ -0,0 +1,383 @@
+import { SkillTypes } from '../game/SkillTypes.js';
+
+const SKILL_INDEX_BY_NAME = new Map([
+  ['climber', SkillTypes.CLIMBER],
+  ['floater', SkillTypes.FLOATER],
+  ['bomber', SkillTypes.BOMBER],
+  ['blocker', SkillTypes.BLOCKER],
+  ['builder', SkillTypes.BUILDER],
+  ['basher', SkillTypes.BASHER],
+  ['miner', SkillTypes.MINER],
+  ['digger', SkillTypes.DIGGER]
+]);
+
+const EDITOR_ADVISORY_WARNING_CODES = Object.freeze({
+  MISSING_ENTRANCE: 'missing-entrance',
+  MISSING_EXIT: 'missing-exit',
+  UNREACHABLE_GAP: 'unreachable-gap',
+  LETHAL_DROP: 'lethal-drop',
+  INSUFFICIENT_SKILLS: 'insufficient-skills',
+  UNSUPPORTED_MECHANIC: 'unsupported-mechanic',
+  ADVISORY_ERROR: 'advisory-error'
+});
+
+const DEFAULT_EDITOR_ADVISORY_OPTIONS = Object.freeze({
+  maxScanColumns: 512,
+  maxScanDrop: 96,
+  maxSafeFall: 60,
+  maxWalkGap: 2,
+  builderReach: 12,
+  stepTolerance: 6
+});
+
+const isPlainObject = value => value != null && typeof value === 'object' && !Array.isArray(value);
+
+const toFiniteNumber = (value, fallback = 0) => {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : fallback;
+};
+
+const toPositiveInteger = (value, fallback) => {
+  const numeric = Math.floor(Number(value));
+  return Number.isFinite(numeric) && numeric > 0 ? numeric : fallback;
+};
+
+const normalizePoint = value => {
+  if (!isPlainObject(value)) return null;
+  const props = isPlainObject(value.props) ? value.props : {};
+  const x = toFiniteNumber(value.x ?? props.X, Number.NaN);
+  const y = toFiniteNumber(value.y ?? props.Y, Number.NaN);
+  if (!Number.isFinite(x) || !Number.isFinite(y)) return null;
+  return { x: Math.floor(x), y: Math.floor(y) };
+};
+
+const getEntryPieceId = entry => {
+  const props = isPlainObject(entry?.props) ? entry.props : {};
+  return entry?.pieceId ?? entry?.piece ?? props.PIECE ?? null;
+};
+
+const entryTypeMatches = (entry, names) => {
+  const raw = entry?.kind ?? entry?.type ?? entry?.role ?? entry?.name ?? '';
+  const type = String(raw).trim().toLowerCase();
+  return names.some(name => type.includes(name));
+};
+
+const extractPointList = (source, key, options) => {
+  const direct = Array.isArray(source?.[key]) ? source[key].map(normalizePoint).filter(Boolean) : [];
+  if (direct.length) return direct;
+  const gadgets = Array.isArray(source?.gadgets) ? source.gadgets : [];
+  const idKey = key === 'entrances' ? 'entranceId' : 'exitId';
+  const targetId = options[idKey] ?? options.assets?.[idKey] ?? null;
+  const names = key === 'entrances' ? ['entrance', 'hatch'] : ['exit'];
+  return gadgets.filter(entry => {
+    if (targetId != null && getEntryPieceId(entry) === targetId) return true;
+    return entryTypeMatches(entry, names);
+  }).map(normalizePoint).filter(Boolean);
+};
+
+const getHeaderNumber = (source, key, fallback) => {
+  const raw = source?.getHeader?.(key) ?? source?.headers?.[key] ?? source?.[key.toLowerCase()];
+  return toFiniteNumber(raw, fallback);
+};
+
+const extractMaskSource = source => {
+  const layer = source?.groundMask ?? source?.terrainMask ?? source?.mask ?? null;
+  if (layer?.mask && Number.isFinite(layer.width) && Number.isFinite(layer.height)) {
+    return {
+      width: layer.width,
+      height: layer.height,
+      hasGroundAt: (x, y) => typeof layer.hasGroundAt === 'function'
+        ? layer.hasGroundAt(x, y)
+        : layer.mask[x + y * layer.width] !== 0
+    };
+  }
+  if (layer && typeof layer.hasGroundAt === 'function') {
+    return {
+      width: source.width ?? layer.width,
+      height: source.height ?? layer.height,
+      hasGroundAt: (x, y) => layer.hasGroundAt(x, y)
+    };
+  }
+  if (ArrayBuffer.isView(layer) && Number.isFinite(source?.width) && Number.isFinite(source?.height)) {
+    return {
+      width: source.width,
+      height: source.height,
+      hasGroundAt: (x, y) => layer[x + y * source.width] !== 0
+    };
+  }
+  return null;
+};
+
+const normalizeAdvisoryContext = (source, options = {}) => {
+  const mask = extractMaskSource(source);
+  const width = toPositiveInteger(source?.width ?? mask?.width ?? getHeaderNumber(source, 'WIDTH', 0), 0);
+  const height = toPositiveInteger(source?.height ?? mask?.height ?? getHeaderNumber(source, 'HEIGHT', 0), 0);
+  const normalizedOptions = {
+    ...DEFAULT_EDITOR_ADVISORY_OPTIONS,
+    ...options,
+    maxScanColumns: toPositiveInteger(options.maxScanColumns, DEFAULT_EDITOR_ADVISORY_OPTIONS.maxScanColumns),
+    maxScanDrop: toPositiveInteger(options.maxScanDrop, DEFAULT_EDITOR_ADVISORY_OPTIONS.maxScanDrop),
+    maxSafeFall: toPositiveInteger(options.maxSafeFall, DEFAULT_EDITOR_ADVISORY_OPTIONS.maxSafeFall),
+    maxWalkGap: toPositiveInteger(options.maxWalkGap, DEFAULT_EDITOR_ADVISORY_OPTIONS.maxWalkGap),
+    builderReach: toPositiveInteger(options.builderReach, DEFAULT_EDITOR_ADVISORY_OPTIONS.builderReach),
+    stepTolerance: toPositiveInteger(options.stepTolerance, DEFAULT_EDITOR_ADVISORY_OPTIONS.stepTolerance)
+  };
+  return {
+    source,
+    options: normalizedOptions,
+    width,
+    height,
+    mask,
+    entrances: extractPointList(source, 'entrances', options),
+    exits: extractPointList(source, 'exits', options),
+    oneWay: Array.isArray(source?.oneWay) ? source.oneWay : [],
+    hazards: Array.isArray(source?.hazards) ? source.hazards : [],
+    unsupportedMechanics: Array.isArray(source?.unsupportedMechanics) ? source.unsupportedMechanics : [],
+    skills: source?.skills ?? source?.skillset ?? {}
+  };
+};
+
+const createWarning = (code, message, details = {}) => ({
+  severity: 'warning',
+  code,
+  message,
+  blocking: false,
+  ...details
+});
+
+const createAdvisoryResult = (warnings, budgetUsage = {}) => ({
+  status: warnings.length ? 'warnings' : 'ok',
+  canContinue: true,
+  blocksEditing: false,
+  blocksExport: false,
+  warnings,
+  budgetUsage: {
+    scannedColumns: budgetUsage.scannedColumns ?? 0,
+    maxScanColumns: budgetUsage.maxScanColumns ?? DEFAULT_EDITOR_ADVISORY_OPTIONS.maxScanColumns
+  }
+});
+
+const warningExists = (warnings, code) => warnings.some(warning => warning.code === code);
+
+const pushWarningOnce = (warnings, warning) => {
+  if (!warningExists(warnings, warning.code)) warnings.push(warning);
+};
+
+const getSkillCount = (skills, skillName) => {
+  const expected = String(skillName).toLowerCase();
+  if (skills instanceof Map) {
+    for (const [key, value] of skills.entries()) {
+      const normalizedKey = String(key).toLowerCase();
+      if (normalizedKey === expected || normalizedKey === `${expected}s`) {
+        return Math.max(0, Math.floor(toFiniteNumber(value, 0)));
+      }
+    }
+    return 0;
+  }
+  if (Array.isArray(skills) || ArrayBuffer.isView(skills)) {
+    const index = SKILL_INDEX_BY_NAME.get(expected);
+    return index == null ? 0 : Math.max(0, Math.floor(toFiniteNumber(skills[index], 0)));
+  }
+  if (!isPlainObject(skills)) return 0;
+  for (const [key, value] of Object.entries(skills)) {
+    const normalizedKey = String(key).toLowerCase();
+    if (normalizedKey === expected || normalizedKey === `${expected}s`) {
+      return Math.max(0, Math.floor(toFiniteNumber(value, 0)));
+    }
+  }
+  return 0;
+};
+
+const detectUnsupportedMechanics = (context, warnings) => {
+  if (context.oneWay.length) {
+    pushWarningOnce(warnings, createWarning(
+      EDITOR_ADVISORY_WARNING_CODES.UNSUPPORTED_MECHANIC,
+      'One-way terrain constraints are outside the current advisory solver scope.',
+      { target: 'oneWay', count: context.oneWay.length }
+    ));
+  }
+  if (context.unsupportedMechanics.length) {
+    const mechanics = context.unsupportedMechanics.map(item => String(item)).sort();
+    pushWarningOnce(warnings, createWarning(
+      EDITOR_ADVISORY_WARNING_CODES.UNSUPPORTED_MECHANIC,
+      `Unsupported mechanics detected: ${mechanics.join(', ')}.`,
+      { target: 'mechanics', mechanics }
+    ));
+  }
+  const supportedHazards = new Set(['fire', 'fryer', 'hazard', 'trap', 'water']);
+  const unsupportedHazards = context.hazards.filter(hazard => {
+    const kind = String(hazard?.kind ?? hazard?.type ?? '').trim().toLowerCase();
+    return kind && !supportedHazards.has(kind);
+  });
+  if (unsupportedHazards.length) {
+    const kinds = Array.from(new Set(unsupportedHazards.map(hazard => {
+      return String(hazard?.kind ?? hazard?.type).trim().toLowerCase();
+    }))).sort();
+    pushWarningOnce(warnings, createWarning(
+      EDITOR_ADVISORY_WARNING_CODES.UNSUPPORTED_MECHANIC,
+      `Unsupported hazard mechanics detected: ${kinds.join(', ')}.`,
+      { target: 'hazards', mechanics: kinds }
+    ));
+  }
+};
+
+const hasGroundAt = (context, x, y) => {
+  if (!context.mask || x < 0 || y < 0 || x >= context.width || y >= context.height) return false;
+  return context.mask.hasGroundAt(Math.floor(x), Math.floor(y));
+};
+
+const findSupportY = (context, x, nearY) => {
+  const { maxScanDrop, stepTolerance } = context.options;
+  const startY = Math.max(0, Math.floor(nearY - stepTolerance));
+  const endY = Math.min(context.height - 1, Math.floor(nearY + maxScanDrop));
+  for (let y = startY; y <= endY; y += 1) {
+    if (hasGroundAt(context, x, y)) return y;
+  }
+  return null;
+};
+
+const createColumnSampler = (startX, endX, maxScanColumns) => {
+  const direction = startX <= endX ? 1 : -1;
+  const distance = Math.abs(endX - startX) + 1;
+  const step = direction * Math.max(1, Math.ceil(distance / maxScanColumns));
+  const columns = [];
+  for (let x = startX; direction > 0 ? x <= endX : x >= endX; x += step) {
+    columns.push(x);
+  }
+  if (columns[columns.length - 1] !== endX) columns.push(endX);
+  return columns;
+};
+
+const analyzeClosedGap = (context, warnings, gap, landingSupportY) => {
+  const width = Math.abs(gap.endX - gap.startX) + 1;
+  if (width <= context.options.maxWalkGap) return;
+  const requiredBuilders = Math.max(1, Math.ceil((width - context.options.maxWalkGap) / context.options.builderReach));
+  const availableBuilders = getSkillCount(context.skills, 'builder');
+  if (requiredBuilders > availableBuilders) {
+    pushWarningOnce(warnings, createWarning(
+      EDITOR_ADVISORY_WARNING_CODES.UNREACHABLE_GAP,
+      `Obvious gap from x=${gap.startX} to x=${gap.endX} needs about ${requiredBuilders} builder skill(s).`,
+      {
+        target: 'terrain',
+        startX: gap.startX,
+        endX: gap.endX,
+        requiredBuilders
+      }
+    ));
+    pushWarningOnce(warnings, createWarning(
+      EDITOR_ADVISORY_WARNING_CODES.INSUFFICIENT_SKILLS,
+      `Builder budget is ${availableBuilders}, below the estimated ${requiredBuilders} needed for an obvious gap.`,
+      {
+        target: 'skills.builder',
+        available: availableBuilders,
+        required: requiredBuilders
+      }
+    ));
+  }
+  if (gap.previousSupportY != null && landingSupportY != null) {
+    const drop = landingSupportY - gap.previousSupportY;
+    if (drop > context.options.maxSafeFall) {
+      pushWarningOnce(warnings, createWarning(
+        EDITOR_ADVISORY_WARNING_CODES.LETHAL_DROP,
+        `Drop near x=${gap.endX} is about ${drop}px, above the advisory safe limit.`,
+        {
+          target: 'terrain',
+          x: gap.endX,
+          drop,
+          maxSafeFall: context.options.maxSafeFall
+        }
+      ));
+    }
+  }
+};
+
+const analyzeRouteGeometry = (context, warnings) => {
+  if (!context.mask || !context.width || !context.height || !context.entrances.length || !context.exits.length) {
+    return { scannedColumns: 0, maxScanColumns: context.options.maxScanColumns };
+  }
+  const entrance = context.entrances[0];
+  const exit = context.exits[0];
+  const startX = Math.min(Math.max(0, entrance.x), context.width - 1);
+  const endX = Math.min(Math.max(0, exit.x), context.width - 1);
+  const columns = createColumnSampler(startX, endX, context.options.maxScanColumns);
+  let previousSupportY = findSupportY(context, startX, entrance.y + 1);
+  let gap = null;
+  for (const x of columns) {
+    const nearY = previousSupportY ?? entrance.y + 1;
+    const supportY = findSupportY(context, x, nearY);
+    if (supportY == null) {
+      if (!gap) {
+        gap = {
+          startX: x,
+          endX: x,
+          previousSupportY
+        };
+      } else {
+        gap.endX = x;
+      }
+      continue;
+    }
+    if (gap) {
+      analyzeClosedGap(context, warnings, gap, supportY);
+      gap = null;
+    } else if (previousSupportY != null) {
+      const drop = supportY - previousSupportY;
+      if (drop > context.options.maxSafeFall) {
+        pushWarningOnce(warnings, createWarning(
+          EDITOR_ADVISORY_WARNING_CODES.LETHAL_DROP,
+          `Drop near x=${x} is about ${drop}px, above the advisory safe limit.`,
+          {
+            target: 'terrain',
+            x,
+            drop,
+            maxSafeFall: context.options.maxSafeFall
+          }
+        ));
+      }
+    }
+    previousSupportY = supportY;
+  }
+  if (gap) analyzeClosedGap(context, warnings, gap, null);
+  return {
+    scannedColumns: columns.length,
+    maxScanColumns: context.options.maxScanColumns
+  };
+};
+
+const checkEditorSolvabilityAdvisory = (source, options = {}) => {
+  try {
+    const context = normalizeAdvisoryContext(source, options);
+    const warnings = [];
+    if (!context.entrances.length) {
+      warnings.push(createWarning(
+        EDITOR_ADVISORY_WARNING_CODES.MISSING_ENTRANCE,
+        'Missing entrance; solver advisory cannot prove a route.',
+        { target: 'entrances' }
+      ));
+    }
+    if (!context.exits.length) {
+      warnings.push(createWarning(
+        EDITOR_ADVISORY_WARNING_CODES.MISSING_EXIT,
+        'Missing exit; solver advisory cannot prove a route.',
+        { target: 'exits' }
+      ));
+    }
+    detectUnsupportedMechanics(context, warnings);
+    const budgetUsage = analyzeRouteGeometry(context, warnings);
+    return createAdvisoryResult(warnings, budgetUsage);
+  } catch (error) {
+    return createAdvisoryResult([
+      createWarning(
+        EDITOR_ADVISORY_WARNING_CODES.ADVISORY_ERROR,
+        'Solver advisory could not complete, but editing and export remain available.',
+        { detail: error?.message || String(error) }
+      )
+    ]);
+  }
+};
+
+export {
+  DEFAULT_EDITOR_ADVISORY_OPTIONS,
+  EDITOR_ADVISORY_WARNING_CODES,
+  checkEditorSolvabilityAdvisory
+};
diff --git a/js/solver/ProcgenCertificates.js b/js/solver/ProcgenCertificates.js
new file mode 100644
index 00000000..93a79a9d
--- /dev/null
+++ b/js/solver/ProcgenCertificates.js
@@ -0,0 +1,367 @@
+import {
+  SOLVER_EXPLANATION_CODES,
+  SOLVER_RESULT_TYPES,
+  createSolverResult
+} from './SolverTypes.js';
+import { solveTactical } from './TacticalSolver.js';
+
+const PROCGEN_CHALLENGE_TYPES = Object.freeze({
+  WALK: 'walk',
+  BRIDGE_GAP: 'bridge-gap',
+  DIG_BARRIER: 'dig-barrier',
+  BASH_BARRIER: 'bash-barrier',
+  MINE_SLOPE: 'mine-slope',
+  FALL_SURVIVAL: 'fall-survival',
+  EXIT_ROUTE: 'exit-route',
+  UNKNOWN: 'unknown'
+});
+
+const PROCGEN_FALLBACK_DECISIONS = Object.freeze({
+  ACCEPT: 'accept',
+  EXTEND: 'extend',
+  REPLACE: 'replace',
+  SIMPLIFY: 'simplify'
+});
+
+const TACTICAL_SOLVER_METHODS = [
+  'verifyProcgenCertificate',
+  'verifyChallengeCertificate',
+  'solveChallenge',
+  'solveTacticalChallenge',
+  'solve',
+  'run'
+];
+
+const solveProcgenTacticalChunk = (chunk, _certificate, options) => solveTactical(chunk, options);
+
+const isPlainObject = value => value != null && typeof value === 'object' && !Array.isArray(value);
+
+const toNonNegativeInteger = (value, fallback = 0) => {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric) || numeric < 0) return fallback;
+  return Math.floor(numeric);
+};
+
+const normalizeToken = (value, fallback = null) => {
+  if (value == null) return fallback;
+  const token = String(value).trim();
+  return token || fallback;
+};
+
+const normalizeAssignmentWindow = value => {
+  if (value == null) return null;
+  const source = Array.isArray(value)
+    ? { start: value[0], end: value[1] }
+    : isPlainObject(value)
+      ? value
+      : {};
+  const start = toNonNegativeInteger(source.start ?? source.from ?? source.tick, 0);
+  const end = toNonNegativeInteger(source.end ?? source.to ?? source.tick, start);
+  return {
+    start: Math.min(start, end),
+    end: Math.max(start, end)
+  };
+};
+
+const normalizeSegment = value => {
+  if (value == null) return null;
+  const source = Array.isArray(value)
+    ? {
+      x0: value[0],
+      y0: value[1],
+      x1: value[2],
+      y1: value[3]
+    }
+    : isPlainObject(value)
+      ? value
+      : {};
+  const start = isPlainObject(source.start) ? source.start : {};
+  const end = isPlainObject(source.end) ? source.end : {};
+  const x0 = Number(source.x0 ?? source.left ?? source.x ?? start.x);
+  const y0 = Number(source.y0 ?? source.top ?? source.y ?? start.y);
+  const rawX1 = source.x1 ?? source.right ?? end.x;
+  const rawY1 = source.y1 ?? source.bottom ?? end.y;
+  const x1 = Number(rawX1 ?? (Number.isFinite(x0) ? x0 : 0));
+  const y1 = Number(rawY1 ?? (Number.isFinite(y0) ? y0 : 0));
+  if (!Number.isFinite(x0) || !Number.isFinite(y0) || !Number.isFinite(x1) || !Number.isFinite(y1)) {
+    return null;
+  }
+  return {
+    x0: Math.min(Math.floor(x0), Math.floor(x1)),
+    y0: Math.min(Math.floor(y0), Math.floor(y1)),
+    x1: Math.max(Math.floor(x0), Math.floor(x1)),
+    y1: Math.max(Math.floor(y0), Math.floor(y1))
+  };
+};
+
+const normalizeSolverLikeResult = value => {
+  if (!isPlainObject(value)) {
+    return createSolverResult({
+      resultType: SOLVER_RESULT_TYPES.UNKNOWN,
+      summary: 'No tactical solver result was returned',
+      explanations: [SOLVER_EXPLANATION_CODES.STATE_EXPLOSION]
+    });
+  }
+  if (value.resultType) return createSolverResult(value);
+  if (value.solved === true) {
+    return createSolverResult({
+      resultType: SOLVER_RESULT_TYPES.SOLVED,
+      summary: value.summary || 'Procgen certificate verified',
+      actions: value.actions,
+      explanations: value.explanations,
+      budgetUsage: value.budgetUsage,
+      replaySummary: value.replaySummary,
+      captures: value.captures
+    });
+  }
+  if (value.solved === false) {
+    return createSolverResult({
+      resultType: SOLVER_RESULT_TYPES.FAILED,
+      summary: value.summary || 'Procgen certificate was rejected',
+      explanations: value.explanations || [SOLVER_EXPLANATION_CODES.NO_ROUTE_TO_EXIT],
+      budgetUsage: value.budgetUsage,
+      replaySummary: value.replaySummary,
+      captures: value.captures
+    });
+  }
+  return createSolverResult({
+    resultType: SOLVER_RESULT_TYPES.UNKNOWN,
+    summary: value.summary || 'Tactical solver result did not include a result type',
+    explanations: value.explanations || [SOLVER_EXPLANATION_CODES.STATE_EXPLOSION],
+    budgetUsage: value.budgetUsage,
+    replaySummary: value.replaySummary,
+    captures: value.captures
+  });
+};
+
+const createUnavailableSolverResult = () => createSolverResult({
+  resultType: SOLVER_RESULT_TYPES.UNSUPPORTED,
+  summary: 'Tactical solver is not available for procgen certificate verification',
+  explanations: [{
+    code: SOLVER_EXPLANATION_CODES.UNSUPPORTED_MECHANIC,
+    detail: 'No TacticalSolver module or injected tactical solver was available.'
+  }]
+});
+
+const createSolverErrorResult = error => createSolverResult({
+  resultType: SOLVER_RESULT_TYPES.UNKNOWN,
+  summary: 'Tactical solver could not verify the procgen certificate',
+  explanations: [{
+    code: SOLVER_EXPLANATION_CODES.STATE_EXPLOSION,
+    detail: error?.message || String(error)
+  }]
+});
+
+const createAsyncSolverResult = () => createSolverResult({
+  resultType: SOLVER_RESULT_TYPES.UNKNOWN,
+  summary: 'Tactical solver returned an async result for synchronous procgen verification',
+  explanations: [{
+    code: SOLVER_EXPLANATION_CODES.STATE_EXPLOSION,
+    detail: 'Procgen generation requires synchronous local certificate decisions.'
+  }]
+});
+
+const isPromiseLike = value => value != null && typeof value.then === 'function';
+
+const callSolverFunction = (fn, chunk, certificate, options) => {
+  if (fn.length >= 2) return fn(chunk, certificate, options);
+  return fn({ chunk, certificate, options });
+};
+
+const invokeSolverObject = async (solver, chunk, certificate, options) => {
+  for (const methodName of TACTICAL_SOLVER_METHODS) {
+    if (typeof solver?.[methodName] === 'function') {
+      return callSolverFunction(solver[methodName].bind(solver), chunk, certificate, options);
+    }
+  }
+  return null;
+};
+
+const invokeTacticalSolver = async (solver, chunk, certificate, options) => {
+  if (typeof solver === 'function') {
+    const source = Function.prototype.toString.call(solver);
+    if (/^class\s/.test(source)) {
+      return invokeSolverObject(new solver(chunk, options), chunk, certificate, options);
+    }
+    return callSolverFunction(solver, chunk, certificate, options);
+  }
+  return invokeSolverObject(solver, chunk, certificate, options);
+};
+
+const invokeSolverObjectSync = (solver, chunk, certificate, options) => {
+  for (const methodName of TACTICAL_SOLVER_METHODS) {
+    if (typeof solver?.[methodName] === 'function') {
+      return callSolverFunction(solver[methodName].bind(solver), chunk, certificate, options);
+    }
+  }
+  return null;
+};
+
+const invokeTacticalSolverSync = (solver, chunk, certificate, options) => {
+  if (typeof solver === 'function') {
+    const source = Function.prototype.toString.call(solver);
+    if (/^class\s/.test(source)) {
+      return invokeSolverObjectSync(new solver(chunk, options), chunk, certificate, options);
+    }
+    return callSolverFunction(solver, chunk, certificate, options);
+  }
+  return invokeSolverObjectSync(solver, chunk, certificate, options);
+};
+
+const resolveTacticalSolver = async options => {
+  if (Object.prototype.hasOwnProperty.call(options, 'tacticalSolver')) {
+    return { solver: options.tacticalSolver };
+  }
+  if (Object.prototype.hasOwnProperty.call(options, 'TacticalSolver')) {
+    return { solver: options.TacticalSolver };
+  }
+  try {
+    return { solver: solveProcgenTacticalChunk };
+  } catch (error) {
+    if (error?.code === 'ERR_MODULE_NOT_FOUND') return { solver: null };
+    return { solver: null, error };
+  }
+};
+
+const resolveTacticalSolverSync = options => {
+  if (Object.prototype.hasOwnProperty.call(options, 'tacticalSolver')) {
+    return { solver: options.tacticalSolver };
+  }
+  if (Object.prototype.hasOwnProperty.call(options, 'TacticalSolver')) {
+    return { solver: options.TacticalSolver };
+  }
+  return { solver: solveProcgenTacticalChunk };
+};
+
+const createProcgenChallengeCertificate = (input = {}) => {
+  const source = isPlainObject(input) ? input : {};
+  const expectedSegment = isPlainObject(source.expectedSegment) ? source.expectedSegment : {};
+  const roughAssignmentWindow = normalizeAssignmentWindow(
+    source.roughAssignmentWindow ??
+      source.assignmentWindow ??
+      source.expectedAssignmentWindow ??
+      source.window
+  );
+  return {
+    id: normalizeToken(source.id, null),
+    challengeType: normalizeToken(
+      source.challengeType ?? source.type,
+      PROCGEN_CHALLENGE_TYPES.UNKNOWN
+    ),
+    expectedSkill: normalizeToken(source.expectedSkill ?? source.skill, null),
+    roughAssignmentWindow,
+    assignmentWindow: roughAssignmentWindow,
+    expectedLandingSegment: normalizeSegment(
+      source.expectedLandingSegment ?? source.landingSegment ?? expectedSegment.landing
+    ),
+    expectedExitSegment: normalizeSegment(
+      source.expectedExitSegment ?? source.exitSegment ?? expectedSegment.exit
+    ),
+    minimalSkillCount: toNonNegativeInteger(
+      source.minimalSkillCount ?? source.minimumSkillCount ?? source.skillCount,
+      0
+    ),
+    verificationResult: source.verificationResult
+      ? normalizeSolverLikeResult(source.verificationResult)
+      : null
+  };
+};
+
+const verifyProcgenChallengeCertificate = async (certificate, chunk, options = {}) => {
+  const normalized = createProcgenChallengeCertificate(certificate);
+  const resolved = await resolveTacticalSolver(options);
+  let verificationResult;
+  if (resolved.error) {
+    verificationResult = createSolverErrorResult(resolved.error);
+  } else if (!resolved.solver) {
+    verificationResult = createUnavailableSolverResult();
+  } else {
+    try {
+      const rawResult = await invokeTacticalSolver(resolved.solver, chunk, normalized, options);
+      verificationResult = normalizeSolverLikeResult(rawResult);
+    } catch (error) {
+      verificationResult = createSolverErrorResult(error);
+    }
+  }
+  return {
+    ...normalized,
+    verificationResult
+  };
+};
+
+const verifyProcgenChallengeCertificateSync = (certificate, chunk, options = {}) => {
+  const normalized = createProcgenChallengeCertificate(certificate);
+  const resolved = resolveTacticalSolverSync(options);
+  let verificationResult;
+  if (resolved.error) {
+    verificationResult = createSolverErrorResult(resolved.error);
+  } else if (!resolved.solver) {
+    verificationResult = createUnavailableSolverResult();
+  } else {
+    try {
+      const rawResult = invokeTacticalSolverSync(resolved.solver, chunk, normalized, options);
+      verificationResult = isPromiseLike(rawResult)
+        ? createAsyncSolverResult()
+        : normalizeSolverLikeResult(rawResult);
+    } catch (error) {
+      verificationResult = createSolverErrorResult(error);
+    }
+  }
+  return {
+    ...normalized,
+    verificationResult
+  };
+};
+
+const getExplanationCodes = result => {
+  const explanations = Array.isArray(result?.explanations) ? result.explanations : [];
+  return new Set(explanations.map(explanation => {
+    if (typeof explanation === 'string') return explanation;
+    return explanation?.code;
+  }).filter(Boolean));
+};
+
+const decideProcgenFallback = result => {
+  const normalized = normalizeSolverLikeResult(result);
+  const codes = getExplanationCodes(normalized);
+  let decision = PROCGEN_FALLBACK_DECISIONS.SIMPLIFY;
+  if (normalized.resultType === SOLVER_RESULT_TYPES.SOLVED) {
+    decision = PROCGEN_FALLBACK_DECISIONS.ACCEPT;
+  } else if (normalized.resultType === SOLVER_RESULT_TYPES.UNSUPPORTED) {
+    decision = PROCGEN_FALLBACK_DECISIONS.REPLACE;
+  } else if (
+    codes.has(SOLVER_EXPLANATION_CODES.HAZARD_UNAVOIDABLE) ||
+    codes.has(SOLVER_EXPLANATION_CODES.BARRIER_BLOCKED_BY_STEEL) ||
+    codes.has(SOLVER_EXPLANATION_CODES.UNSUPPORTED_MECHANIC)
+  ) {
+    decision = PROCGEN_FALLBACK_DECISIONS.REPLACE;
+  } else if (
+    codes.has(SOLVER_EXPLANATION_CODES.MISSING_LANDING) ||
+    codes.has(SOLVER_EXPLANATION_CODES.MISSING_EXIT) ||
+    codes.has(SOLVER_EXPLANATION_CODES.NO_ROUTE_TO_EXIT)
+  ) {
+    decision = PROCGEN_FALLBACK_DECISIONS.EXTEND;
+  } else if (
+    codes.has(SOLVER_EXPLANATION_CODES.GAP_EXCEEDS_BUILDER_BUDGET) ||
+    codes.has(SOLVER_EXPLANATION_CODES.TIMING_WINDOW_TOO_NARROW) ||
+    codes.has(SOLVER_EXPLANATION_CODES.BUDGET_EXHAUSTED) ||
+    codes.has(SOLVER_EXPLANATION_CODES.SAVE_COUNT_UNREACHABLE)
+  ) {
+    decision = PROCGEN_FALLBACK_DECISIONS.SIMPLIFY;
+  }
+  return {
+    decision,
+    resultType: normalized.resultType,
+    reasonCodes: Array.from(codes).sort(),
+    summary: normalized.summary
+  };
+};
+
+export {
+  PROCGEN_CHALLENGE_TYPES,
+  PROCGEN_FALLBACK_DECISIONS,
+  createProcgenChallengeCertificate,
+  decideProcgenFallback,
+  verifyProcgenChallengeCertificate,
+  verifyProcgenChallengeCertificateSync
+};
diff --git a/js/solver/ReachabilityGraph.js b/js/solver/ReachabilityGraph.js
new file mode 100644
index 00000000..eae4cda9
--- /dev/null
+++ b/js/solver/ReachabilityGraph.js
@@ -0,0 +1,282 @@
+import { analyzeSolverAffordances } from './SolverAnalysis.js';
+import { analyzeSolverGeometry } from './SolverGeometry.js';
+import { extractSolverState, isSolverState, stableHash } from './SolverState.js';
+
+const edgeDistance = (from, to) => {
+  const ax = from?.x ?? 0;
+  const ay = from?.y ?? 0;
+  const bx = to?.x ?? ax;
+  const by = to?.y ?? ay;
+  return Math.abs(ax - bx) + Math.abs(ay - by);
+};
+
+const sortById = (left, right) => String(left.id).localeCompare(String(right.id));
+
+const addNode = (nodes, node) => {
+  if (!nodes.has(node.id)) nodes.set(node.id, node);
+};
+
+const addEdge = (edges, edge) => {
+  if (!edge.from || !edge.to || edge.from === edge.to) return;
+  const id = edge.id ?? `${edge.from}->${edge.to}:${edge.type}`;
+  if (edges.has(id)) return;
+  edges.set(id, {
+    ...edge,
+    id
+  });
+};
+
+const findSurfaceNode = surfaceId => `surface:${surfaceId}`;
+
+const surfaceCenter = surface => ({
+  x: Math.floor(surface.x + surface.width / 2),
+  y: surface.y
+});
+
+const rectCenter = rect => ({
+  x: Math.floor(rect.x + Math.max(0, rect.width - 1) / 2),
+  y: Math.floor(rect.y + Math.max(0, rect.height - 1) / 2)
+});
+
+const rectRight = rect => rect.x + rect.width - 1;
+const rectBottom = rect => rect.y + rect.height - 1;
+
+const rectsOverlap = (left, right) => (
+  left.x <= rectRight(right) &&
+  rectRight(left) >= right.x &&
+  left.y <= rectBottom(right) &&
+  rectBottom(left) >= right.y
+);
+
+const edgeFromAffordance = affordance => {
+  const requiredSkills = affordance.skillType ? [affordance.skillType] : [];
+  const hazardExposure = affordance.blocked
+    ? affordance.blockers.map(blocker => blocker.type).sort()
+    : [];
+  const mutation = affordance.skillType && affordance.skillType !== 'floater' && affordance.skillType !== 'blocker'
+    ? {
+      kind: affordance.type,
+      skillType: affordance.skillType,
+      affectedBounds: { ...affordance.rect },
+      blockers: affordance.blockers
+    }
+    : null;
+  return {
+    type: affordance.skillType === 'builder'
+      ? 'build'
+      : affordance.skillType === 'floater'
+        ? 'fall'
+        : affordance.skillType === 'blocker'
+          ? 'blocker-turn'
+          : affordance.skillType,
+    requiredSkills,
+    requiredSkillCount: affordance.requiredSkillCount,
+    availableSkillCount: affordance.availableSkillCount,
+    roughTimingWindow: affordance.roughTimingWindow,
+    hazardExposure,
+    blocked: affordance.blocked,
+    blockers: affordance.blockers,
+    uncertainty: affordance.blocked ? 1 : 0,
+    mutation
+  };
+};
+
+const buildEndpointNodes = (nodes, edges, snapshot, geometry, kind, rects, surfaceKey) => {
+  for (const item of rects) {
+    const nodeId = `${kind}:${item.index}`;
+    addNode(nodes, {
+      id: nodeId,
+      type: kind,
+      rect: {
+        x: item.x,
+        y: item.y,
+        width: item.width,
+        height: item.height
+      },
+      point: rectCenter(item)
+    });
+  }
+  const surfaceIds = geometry.routeContinuity?.[surfaceKey] ?? [];
+  for (const item of rects) {
+    for (const surfaceId of surfaceIds) {
+      const surfaceNode = findSurfaceNode(surfaceId);
+      if (kind === 'entrance') {
+        addEdge(edges, {
+          from: `${kind}:${item.index}`,
+          to: surfaceNode,
+          type: 'spawn',
+          requiredSkills: [],
+          requiredSkillCount: 0,
+          hazardExposure: [],
+          blocked: false,
+          uncertainty: 0,
+          distance: 0
+        });
+      } else {
+        addEdge(edges, {
+          from: surfaceNode,
+          to: `${kind}:${item.index}`,
+          type: 'exit',
+          requiredSkills: [],
+          requiredSkillCount: 0,
+          hazardExposure: [],
+          blocked: false,
+          uncertainty: 0,
+          distance: 0
+        });
+      }
+    }
+  }
+};
+
+const addStepEdges = (edges, surfaces, maxStepHeight) => {
+  for (const left of surfaces) {
+    for (const right of surfaces) {
+      if (left.id === right.id) continue;
+      const touching = right.left <= left.right + 1 && right.right >= left.left - 1;
+      if (!touching) continue;
+      const step = Math.abs(left.y - right.y);
+      if (step > maxStepHeight) continue;
+      addEdge(edges, {
+        from: findSurfaceNode(left.id),
+        to: findSurfaceNode(right.id),
+        type: step === 0 ? 'walk' : 'step',
+        requiredSkills: [],
+        requiredSkillCount: 0,
+        hazardExposure: right.hasHazard ? right.hazardKinds : [],
+        blocked: right.hasHazard,
+        uncertainty: 0,
+        distance: edgeDistance(surfaceCenter(left), surfaceCenter(right))
+      });
+    }
+  }
+};
+
+const addFallEdges = (edges, cliffs) => {
+  for (const cliff of cliffs) {
+    if (!cliff.safe || cliff.landing?.surfaceId == null) continue;
+    addEdge(edges, {
+      from: findSurfaceNode(cliff.surfaceId),
+      to: findSurfaceNode(cliff.landing.surfaceId),
+      type: 'fall',
+      requiredSkills: [],
+      requiredSkillCount: 0,
+      hazardExposure: [],
+      blocked: false,
+      uncertainty: 0,
+      fallDistance: cliff.fallDistance,
+      roughTimingWindow: {
+        start: Math.max(0, cliff.x - 4),
+        end: cliff.x + 4
+      },
+      distance: Math.max(0, cliff.fallDistance ?? 0)
+    });
+  }
+};
+
+const addAffordanceEdges = (edges, nodes, affordances) => {
+  for (const affordance of affordances) {
+    const from = findSurfaceNode(affordance.fromSurfaceId);
+    let to = affordance.toSurfaceId == null ? null : findSurfaceNode(affordance.toSurfaceId);
+    if (!to && affordance.skillType !== 'blocker') {
+      to = `mutation:${affordance.id}`;
+      addNode(nodes, {
+        id: to,
+        type: 'mutation-segment',
+        rect: { ...affordance.rect },
+        point: rectCenter(affordance.rect),
+        generatedBy: affordance.id
+      });
+    }
+    if (!to) to = from;
+    addEdge(edges, {
+      from,
+      to,
+      id: `affordance:${affordance.id}`,
+      affordanceId: affordance.id,
+      ...edgeFromAffordance(affordance),
+      distance: Math.max(1, affordance.rect.width + affordance.rect.height)
+    });
+  }
+};
+
+const buildReachabilityGraph = (input, options = {}) => {
+  const snapshot = isSolverState(input) ? input : extractSolverState(input, options);
+  const geometry = options.geometry ?? analyzeSolverGeometry(snapshot, options.geometryOptions ?? options);
+  const analysis = options.analysis ?? analyzeSolverAffordances(snapshot, {
+    ...options,
+    geometry
+  });
+  const nodes = new Map();
+  const edges = new Map();
+
+  for (const surface of geometry.surfaces) {
+    addNode(nodes, {
+      id: findSurfaceNode(surface.id),
+      type: 'surface',
+      surfaceId: surface.id,
+      rect: {
+        x: surface.x,
+        y: surface.y,
+        width: surface.width,
+        height: 1
+      },
+      point: surfaceCenter(surface),
+      hazardKinds: surface.hazardKinds,
+      blocked: surface.hasHazard
+    });
+  }
+
+  buildEndpointNodes(nodes, edges, snapshot, geometry, 'entrance', snapshot.entrances, 'entranceSurfaceIds');
+  buildEndpointNodes(nodes, edges, snapshot, geometry, 'exit', snapshot.exits, 'exitSurfaceIds');
+  addStepEdges(edges, geometry.surfaces, options.maxStepHeight ?? 4);
+  addFallEdges(edges, geometry.cliffs);
+  addAffordanceEdges(edges, nodes, analysis.skillAffordances);
+
+  const graph = {
+    kind: 'solver-reachability-graph',
+    stateHash: snapshot.snapshotHash,
+    terrainHash: snapshot.terrainHash,
+    terrainMutationHash: snapshot.terrainMutationHash,
+    geometryHash: geometry.geometryHash,
+    analysisHash: analysis.analysisHash,
+    nodes: Array.from(nodes.values()).sort(sortById),
+    edges: Array.from(edges.values()).sort(sortById),
+    entranceNodeIds: snapshot.entrances.map(entrance => `entrance:${entrance.index}`),
+    exitNodeIds: snapshot.exits.map(exit => `exit:${exit.index}`)
+  };
+  graph.graphHash = stableHash({
+    stateHash: graph.stateHash,
+    terrainMutationHash: graph.terrainMutationHash,
+    nodes: graph.nodes,
+    edges: graph.edges
+  });
+  return graph;
+};
+
+const invalidateReachabilityGraph = (graph, mutation = {}) => {
+  const bounds = mutation.affectedBounds ?? mutation.rect ?? mutation;
+  const overlaps = rect => rect && bounds?.width != null && rectsOverlap(rect, bounds);
+  const invalidatedNodeIds = graph.nodes
+    .filter(node => overlaps(node.rect))
+    .map(node => node.id)
+    .sort();
+  const invalidatedEdgeIds = graph.edges
+    .filter(edge => invalidatedNodeIds.includes(edge.from) ||
+      invalidatedNodeIds.includes(edge.to) ||
+      overlaps(edge.mutation?.affectedBounds))
+    .map(edge => edge.id)
+    .sort();
+  return {
+    graphHash: graph.graphHash,
+    mutationHash: stableHash(mutation),
+    invalidatedNodeIds,
+    invalidatedEdgeIds,
+    requiresRebuild: invalidatedNodeIds.length > 0 || invalidatedEdgeIds.length > 0
+  };
+};
+
+export {
+  buildReachabilityGraph,
+  invalidateReachabilityGraph
+};
diff --git a/js/solver/RoutePlanner.js b/js/solver/RoutePlanner.js
new file mode 100644
index 00000000..9617ddf1
--- /dev/null
+++ b/js/solver/RoutePlanner.js
@@ -0,0 +1,230 @@
+import {
+  SOLVER_EXPLANATION_CODES,
+  SOLVER_RESULT_TYPES,
+  createSolverResult,
+  normalizeSolverOptions
+} from './SolverTypes.js';
+import { buildReachabilityGraph } from './ReachabilityGraph.js';
+import { analyzeSolverCrowd } from './SolverCrowd.js';
+import { stableHash } from './SolverState.js';
+
+const EDGE_TYPE_ORDER = Object.freeze({
+  spawn: 0,
+  walk: 1,
+  step: 2,
+  fall: 3,
+  build: 4,
+  blocker: 5,
+  'blocker-turn': 5,
+  basher: 6,
+  digger: 7,
+  miner: 8,
+  exit: 9
+});
+
+const DESTRUCTIVE_TYPES = new Set(['basher', 'digger', 'miner']);
+
+const edgeCost = edge => {
+  const skillCost = (edge.requiredSkillCount ?? edge.requiredSkills?.length ?? 0) * 100;
+  const destructiveCost = DESTRUCTIVE_TYPES.has(edge.type) ? 25 : 0;
+  const hazardCost = (edge.hazardExposure?.length ?? 0) * 1000;
+  const blockedCost = edge.blocked ? 10000 : 0;
+  const uncertaintyCost = (edge.uncertainty ?? 0) * 20;
+  const distanceCost = Math.max(0, Math.floor(edge.distance ?? 0));
+  const timingCost = edge.roughTimingWindow
+    ? Math.max(0, Math.floor(edge.roughTimingWindow.end - edge.roughTimingWindow.start))
+    : 0;
+  return skillCost + destructiveCost + hazardCost + blockedCost + uncertaintyCost + distanceCost + timingCost;
+};
+
+const routeScoreBreakdown = edges => ({
+  skillCount: edges.reduce((sum, edge) => sum + (edge.requiredSkillCount ?? edge.requiredSkills?.length ?? 0), 0),
+  destructiveActions: edges.filter(edge => DESTRUCTIVE_TYPES.has(edge.type)).length,
+  hazardExposure: edges.reduce((sum, edge) => sum + (edge.hazardExposure?.length ?? 0), 0),
+  uncertainty: edges.reduce((sum, edge) => sum + (edge.uncertainty ?? 0), 0),
+  timingDifficulty: edges.reduce((sum, edge) => {
+    if (!edge.roughTimingWindow) return sum;
+    return sum + Math.max(0, edge.roughTimingWindow.end - edge.roughTimingWindow.start);
+  }, 0),
+  distance: edges.reduce((sum, edge) => sum + Math.max(0, edge.distance ?? 0), 0),
+  total: edges.reduce((sum, edge) => sum + edgeCost(edge), 0)
+});
+
+const sortEdges = edges => [...edges].sort((left, right) => (
+  edgeCost(left) - edgeCost(right) ||
+  (EDGE_TYPE_ORDER[left.type] ?? 99) - (EDGE_TYPE_ORDER[right.type] ?? 99) ||
+  String(left.id).localeCompare(String(right.id))
+));
+
+const buildAdjacency = graph => {
+  const adjacency = new Map();
+  for (const edge of sortEdges(graph.edges)) {
+    if (!adjacency.has(edge.from)) adjacency.set(edge.from, []);
+    adjacency.get(edge.from).push(edge);
+  }
+  return adjacency;
+};
+
+const hasUsableSkills = (edge, options) => {
+  if (!edge.requiredSkills?.length) return true;
+  const subset = new Set(options.skillSubset);
+  if (subset.size && edge.requiredSkills.some(skill => !subset.has(skill))) return false;
+  if (edge.availableSkillCount != null && edge.requiredSkillCount != null) {
+    return edge.availableSkillCount >= edge.requiredSkillCount;
+  }
+  return true;
+};
+
+const isDestructiveAllowed = (edge, options) => {
+  if (!DESTRUCTIVE_TYPES.has(edge.type)) return true;
+  if (options.allowDestructiveSkills === false) return false;
+  return true;
+};
+
+const createRouteSkeleton = (graph, edges) => {
+  const scoreBreakdown = routeScoreBreakdown(edges);
+  const skeleton = {
+    kind: 'solver-route-skeleton',
+    graphHash: graph.graphHash,
+    nodeIds: edges.length
+      ? [edges[0].from, ...edges.map(edge => edge.to)]
+      : [],
+    edgeIds: edges.map(edge => edge.id),
+    segments: edges.map((edge, index) => ({
+      index,
+      edgeId: edge.id,
+      from: edge.from,
+      to: edge.to,
+      type: edge.type,
+      requiredSkillFamilies: edge.requiredSkills ?? [],
+      requiredSkillCount: edge.requiredSkillCount ?? edge.requiredSkills?.length ?? 0,
+      roughActionWindow: edge.roughTimingWindow ?? null,
+      mutation: edge.mutation ?? null,
+      hazardExposure: edge.hazardExposure ?? [],
+      explanation: edge.blocked ? 'blocked edge retained for failure reporting' : null
+    })),
+    scoreBreakdown
+  };
+  skeleton.routeHash = stableHash(skeleton);
+  return skeleton;
+};
+
+const planSolverRoute = (input, options = {}) => {
+  const normalized = {
+    ...normalizeSolverOptions(options),
+    allowDestructiveSkills: options.allowDestructiveSkills !== false
+  };
+  const graph = options.graph ?? buildReachabilityGraph(input, options);
+  const crowd = options.crowd ?? analyzeSolverCrowd(input, options);
+  if (crowd.targetSaveCount > 0 && crowd.maximumReachableSaveCount < crowd.targetSaveCount) {
+    const result = createSolverResult({
+      resultType: SOLVER_RESULT_TYPES.FAILED,
+      summary: `Save target ${crowd.targetSaveCount} exceeds reachable crowd count ${crowd.maximumReachableSaveCount}`,
+      explanations: [{
+        code: SOLVER_EXPLANATION_CODES.SAVE_COUNT_UNREACHABLE,
+        detail: 'Route planning stopped before timing search because the crowd cannot satisfy the save target.',
+        data: {
+          targetSaveCount: crowd.targetSaveCount,
+          maximumReachableSaveCount: crowd.maximumReachableSaveCount
+        }
+      }],
+      budgetUsage: { nodes: 1 }
+    });
+    result.crowd = crowd;
+    result.graphHash = graph.graphHash;
+    return result;
+  }
+
+  const adjacency = buildAdjacency(graph);
+  const exitSet = new Set(graph.exitNodeIds);
+  const queue = graph.entranceNodeIds.map(nodeId => ({
+    nodeId,
+    edges: [],
+    score: 0
+  }));
+  const bestScoreByNode = new Map(queue.map(item => [item.nodeId, 0]));
+  const stats = {
+    nodes: 0,
+    edgesConsidered: 0,
+    pruned: 0,
+    bestFailureReason: null
+  };
+
+  while (queue.length) {
+    queue.sort((left, right) => left.score - right.score || left.nodeId.localeCompare(right.nodeId));
+    const current = queue.shift();
+    stats.nodes += 1;
+    if (stats.nodes > normalized.maxNodes) {
+      const result = createSolverResult({
+        resultType: SOLVER_RESULT_TYPES.TIMEOUT,
+        summary: 'Route planner exhausted node budget',
+        explanations: [SOLVER_EXPLANATION_CODES.BUDGET_EXHAUSTED],
+        budgetUsage: { nodes: stats.nodes }
+      });
+      result.routeSearchStats = stats;
+      result.graphHash = graph.graphHash;
+      return result;
+    }
+    if (exitSet.has(current.nodeId)) {
+      const routeSkeleton = createRouteSkeleton(graph, current.edges);
+      const result = createSolverResult({
+        resultType: SOLVER_RESULT_TYPES.UNKNOWN,
+        summary: 'Route skeleton selected; exact timing and runtime replay still required',
+        explanations: [],
+        budgetUsage: { nodes: stats.nodes, actions: routeSkeleton.segments.length }
+      });
+      result.routeSkeleton = routeSkeleton;
+      result.routeSearchStats = stats;
+      result.graphHash = graph.graphHash;
+      result.crowd = crowd;
+      return result;
+    }
+
+    for (const edge of adjacency.get(current.nodeId) ?? []) {
+      stats.edgesConsidered += 1;
+      if (edge.blocked) {
+        stats.pruned += 1;
+        stats.bestFailureReason = edge.blockers?.[0]?.type === 'steel'
+          ? SOLVER_EXPLANATION_CODES.BARRIER_BLOCKED_BY_STEEL
+          : SOLVER_EXPLANATION_CODES.HAZARD_UNAVOIDABLE;
+        continue;
+      }
+      if (!hasUsableSkills(edge, normalized) || !isDestructiveAllowed(edge, normalized)) {
+        stats.pruned += 1;
+        stats.bestFailureReason = SOLVER_EXPLANATION_CODES.NO_ROUTE_TO_EXIT;
+        continue;
+      }
+      const score = current.score + edgeCost(edge);
+      const previous = bestScoreByNode.get(edge.to);
+      if (previous != null && previous <= score) {
+        stats.pruned += 1;
+        continue;
+      }
+      bestScoreByNode.set(edge.to, score);
+      queue.push({
+        nodeId: edge.to,
+        edges: [...current.edges, edge],
+        score
+      });
+    }
+  }
+
+  const explanationCode = stats.bestFailureReason ?? SOLVER_EXPLANATION_CODES.NO_ROUTE_TO_EXIT;
+  const result = createSolverResult({
+    resultType: SOLVER_RESULT_TYPES.FAILED,
+    summary: 'No route skeleton reaches the exit within supported graph edges',
+    explanations: [{
+      code: explanationCode,
+      detail: 'Reachability graph search exhausted all deterministic candidates.'
+    }],
+    budgetUsage: { nodes: stats.nodes }
+  });
+  result.routeSearchStats = stats;
+  result.graphHash = graph.graphHash;
+  result.crowd = crowd;
+  return result;
+};
+
+export {
+  planSolverRoute
+};
diff --git a/js/solver/SolverAnalysis.js b/js/solver/SolverAnalysis.js
new file mode 100644
index 00000000..2fb310ee
--- /dev/null
+++ b/js/solver/SolverAnalysis.js
@@ -0,0 +1,277 @@
+import { SOLVER_EXPLANATION_CODES } from './SolverTypes.js';
+import { analyzeSolverGeometry } from './SolverGeometry.js';
+import { extractSolverState, isSolverState, stableHash } from './SolverState.js';
+
+const SUPPORTED_HAZARD_KINDS = new Set([
+  'fall',
+  'frying',
+  'hazard',
+  'kill',
+  'lethal-fall',
+  'trap',
+  'water',
+  'drown'
+]);
+
+const DESTRUCTIVE_SKILLS = Object.freeze(['basher', 'digger', 'miner']);
+
+const rectRight = rect => rect.x + rect.width - 1;
+const rectBottom = rect => rect.y + rect.height - 1;
+
+const rectsOverlap = (left, right) => (
+  left.x <= rectRight(right) &&
+  rectRight(left) >= right.x &&
+  left.y <= rectBottom(right) &&
+  rectBottom(left) >= right.y
+);
+
+const toCount = value => {
+  const next = Number(value);
+  return Number.isFinite(next) ? Math.max(0, Math.floor(next)) : 0;
+};
+
+const getSkillCount = (snapshot, skill) => toCount(snapshot.skills?.counts?.[skill]);
+
+const normalizeHazardKind = kind => {
+  const key = String(kind || 'hazard').trim().toLowerCase();
+  if (key === 'drowning') return 'drown';
+  if (key === 'fire' || key === 'fryer') return 'frying';
+  if (key === 'drop') return 'fall';
+  return key || 'hazard';
+};
+
+const blockedByOneWay = (snapshot, rect, skill, direction = null) => {
+  if (!DESTRUCTIVE_SKILLS.includes(skill)) return [];
+  return snapshot.oneWay.filter(oneWay => {
+    if (!rectsOverlap(rect, oneWay)) return false;
+    if (!direction || oneWay.direction === 'unknown') return true;
+    return oneWay.direction !== direction;
+  });
+};
+
+const steelInRect = (snapshot, rect) => snapshot.steel.constraints
+  .filter(steel => rectsOverlap(rect, steel));
+
+const createExplanation = (code, detail, data = undefined) => ({
+  code,
+  detail,
+  ...(data ? { data } : {})
+});
+
+const createHazardRecords = (snapshot, geometry) => {
+  const records = snapshot.hazards.map((hazard, index) => {
+    const kind = normalizeHazardKind(hazard.kind);
+    return {
+      id: `hazard:${index}`,
+      source: 'snapshot',
+      kind,
+      rect: {
+        x: hazard.x,
+        y: hazard.y,
+        width: hazard.width,
+        height: hazard.height
+      },
+      supported: SUPPORTED_HAZARD_KINDS.has(kind),
+      explanation: SUPPORTED_HAZARD_KINDS.has(kind)
+        ? null
+        : createExplanation(
+          SOLVER_EXPLANATION_CODES.UNSUPPORTED_MECHANIC,
+          `Unsupported hazard mechanic: ${kind}`,
+          { kind }
+        )
+    };
+  });
+  for (const cliff of geometry.cliffs) {
+    if (cliff.safe || cliff.fallDistance == null) continue;
+    records.push({
+      id: `lethal-fall:${cliff.surfaceId}:${cliff.side}`,
+      source: 'geometry',
+      kind: 'lethal-fall',
+      rect: {
+        x: cliff.x,
+        y: cliff.y,
+        width: 1,
+        height: Math.max(1, cliff.fallDistance)
+      },
+      supported: true,
+      explanation: createExplanation(
+        SOLVER_EXPLANATION_CODES.HAZARD_UNAVOIDABLE,
+        `Fall distance ${cliff.fallDistance}px exceeds the configured safe fall bound.`,
+        { fallDistance: cliff.fallDistance }
+      )
+    });
+  }
+  return records.sort((a, b) => (
+    a.rect.y - b.rect.y ||
+    a.rect.x - b.rect.x ||
+    a.kind.localeCompare(b.kind) ||
+    a.id.localeCompare(b.id)
+  ));
+};
+
+const builderAffordances = (snapshot, geometry) => geometry.gaps.map((gap, index) => {
+  const requiredSkillCount = Math.max(1, Math.ceil(gap.width / 12));
+  return {
+    id: `builder:${index}`,
+    type: 'builder-bridge',
+    skillType: 'builder',
+    fromSurfaceId: gap.fromSurfaceId,
+    toSurfaceId: gap.toSurfaceId,
+    rect: {
+      x: gap.x,
+      y: gap.y,
+      width: gap.width,
+      height: 2
+    },
+    requiredSkillCount,
+    availableSkillCount: getSkillCount(snapshot, 'builder'),
+    blocked: false,
+    blockers: [],
+    roughTimingWindow: {
+      start: Math.max(0, gap.x - 12),
+      end: gap.x + Math.max(6, gap.width * 2)
+    }
+  };
+});
+
+const destructiveAffordances = (snapshot, geometry) => {
+  const out = [];
+  for (const barrier of geometry.barriers) {
+    const rect = {
+      x: barrier.x,
+      y: barrier.y,
+      width: barrier.width,
+      height: barrier.height
+    };
+    const direction = barrier.side === 'right' ? 'right' : 'left';
+    for (const skill of DESTRUCTIVE_SKILLS) {
+      const steelBlockers = steelInRect(snapshot, rect);
+      const oneWayBlockers = blockedByOneWay(snapshot, rect, skill, direction);
+      const blockers = [
+        ...steelBlockers.map(steel => ({
+          type: 'steel',
+          rect: { x: steel.x, y: steel.y, width: steel.width, height: steel.height }
+        })),
+        ...oneWayBlockers.map(oneWay => ({
+          type: 'one-way',
+          direction: oneWay.direction,
+          rect: { x: oneWay.x, y: oneWay.y, width: oneWay.width, height: oneWay.height }
+        }))
+      ];
+      out.push({
+        id: `${skill}:${barrier.id}`,
+        type: `${skill}-tunnel`,
+        skillType: skill,
+        fromSurfaceId: barrier.surfaceId,
+        toSurfaceId: null,
+        rect,
+        requiredSkillCount: 1,
+        availableSkillCount: getSkillCount(snapshot, skill),
+        blocked: blockers.length > 0,
+        blockers,
+        explanation: blockers.some(blocker => blocker.type === 'steel')
+          ? createExplanation(SOLVER_EXPLANATION_CODES.BARRIER_BLOCKED_BY_STEEL, 'Destructive path intersects steel.')
+          : blockers.some(blocker => blocker.type === 'one-way')
+            ? createExplanation(SOLVER_EXPLANATION_CODES.ONE_WAY_BLOCKED, 'Destructive path conflicts with one-way terrain.')
+            : null,
+        roughTimingWindow: {
+          start: Math.max(0, barrier.x - 8),
+          end: barrier.x + barrier.width + 12
+        }
+      });
+    }
+  }
+  return out;
+};
+
+const floaterAffordances = (snapshot, geometry) => geometry.cliffs
+  .filter(cliff => !cliff.safe && cliff.landing)
+  .map((cliff, index) => ({
+    id: `floater:${index}`,
+    type: 'floater-fall',
+    skillType: 'floater',
+    fromSurfaceId: cliff.surfaceId,
+    toSurfaceId: cliff.landing.surfaceId,
+    rect: {
+      x: cliff.x,
+      y: cliff.y,
+      width: 1,
+      height: Math.max(1, cliff.fallDistance ?? 1)
+    },
+    requiredSkillCount: 1,
+    availableSkillCount: getSkillCount(snapshot, 'floater'),
+    blocked: false,
+    blockers: [],
+    roughTimingWindow: {
+      start: Math.max(0, cliff.x - 8),
+      end: cliff.x + 8
+    }
+  }));
+
+const blockerAffordances = (snapshot, geometry) => geometry.surfaces.map(surface => ({
+  id: `blocker:${surface.id}`,
+  type: 'blocker-turn',
+  skillType: 'blocker',
+  fromSurfaceId: surface.id,
+  toSurfaceId: surface.id,
+  rect: {
+    x: surface.x,
+    y: surface.y,
+    width: surface.width,
+    height: 1
+  },
+  requiredSkillCount: 1,
+  availableSkillCount: getSkillCount(snapshot, 'blocker'),
+  blocked: false,
+  blockers: [],
+  roughTimingWindow: {
+    start: Math.max(0, surface.x),
+    end: Math.max(0, surface.right)
+  }
+}));
+
+const analyzeSolverAffordances = (input, options = {}) => {
+  const snapshot = isSolverState(input) ? input : extractSolverState(input, options);
+  const geometry = options.geometry ?? analyzeSolverGeometry(snapshot, options.geometryOptions ?? options);
+  const hazards = createHazardRecords(snapshot, geometry);
+  const skillAffordances = [
+    ...builderAffordances(snapshot, geometry),
+    ...destructiveAffordances(snapshot, geometry),
+    ...floaterAffordances(snapshot, geometry),
+    ...blockerAffordances(snapshot, geometry)
+  ].sort((a, b) => (
+    a.rect.y - b.rect.y ||
+    a.rect.x - b.rect.x ||
+    a.skillType.localeCompare(b.skillType) ||
+    a.id.localeCompare(b.id)
+  ));
+  const explanations = hazards
+    .map(hazard => hazard.explanation)
+    .concat(skillAffordances.map(affordance => affordance.explanation))
+    .filter(Boolean);
+  const analysis = {
+    kind: 'solver-analysis',
+    stateHash: snapshot.snapshotHash,
+    geometryHash: geometry.geometryHash,
+    terrainMutationHash: snapshot.terrainMutationHash,
+    hazards,
+    skillAffordances,
+    unsupportedMechanics: hazards
+      .filter(hazard => !hazard.supported)
+      .map(hazard => hazard.kind)
+      .sort(),
+    explanations
+  };
+  analysis.analysisHash = stableHash({
+    stateHash: analysis.stateHash,
+    geometryHash: analysis.geometryHash,
+    terrainMutationHash: analysis.terrainMutationHash,
+    hazards,
+    skillAffordances
+  });
+  return analysis;
+};
+
+export {
+  analyzeSolverAffordances
+};
diff --git a/js/solver/SolverCrowd.js b/js/solver/SolverCrowd.js
new file mode 100644
index 00000000..d6a2c6b9
--- /dev/null
+++ b/js/solver/SolverCrowd.js
@@ -0,0 +1,129 @@
+import {
+  SOLVER_EXPLANATION_CODES,
+  SOLVER_RESULT_TYPES,
+  createSolverResult,
+  normalizeSolverOptions
+} from './SolverTypes.js';
+import { extractSolverState, isSolverState, stableHash } from './SolverState.js';
+
+const actionName = lemming => String(lemming.action ?? lemming.state ?? '').toLowerCase();
+
+const isDead = lemming => (
+  lemming.dead === true ||
+  lemming.removed === true ||
+  ['dead', 'splatted', 'splatting', 'drowning', 'frying', 'out_of_level'].includes(actionName(lemming))
+);
+
+const isSaved = lemming => lemming.saved === true || actionName(lemming).includes('exit');
+
+const isActive = lemming => !isDead(lemming) && !isSaved(lemming) && lemming.disabled !== true;
+
+const roleRecord = (role, lemming, reason) => ({
+  role,
+  lemmingId: lemming?.id ?? null,
+  x: lemming?.x ?? null,
+  y: lemming?.y ?? null,
+  reason
+});
+
+const uniqueRoles = roles => {
+  const seen = new Set();
+  const out = [];
+  for (const role of roles) {
+    const key = `${role.role}:${role.lemmingId}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(role);
+  }
+  return out;
+};
+
+const analyzeSolverCrowd = (input, options = {}) => {
+  const snapshot = isSolverState(input) ? input : extractSolverState(input, options);
+  const normalized = normalizeSolverOptions(options);
+  const lemmings = snapshot.lemmings.map(lemming => ({
+    ...lemming,
+    saved: isSaved(lemming),
+    dead: isDead(lemming),
+    active: isActive(lemming),
+    fallDistance: Number.isFinite(Number(lemming.fallDistance)) ? Math.max(0, Math.floor(lemming.fallDistance)) : 0
+  }));
+  const active = lemmings.filter(lemming => lemming.active)
+    .sort((left, right) => left.x - right.x || left.y - right.y || Number(left.id) - Number(right.id));
+  const savedCount = lemmings.filter(lemming => lemming.saved).length ||
+    snapshot.victory.survivorsCount;
+  const deadCount = lemmings.filter(lemming => lemming.dead).length;
+  const leftCount = snapshot.victory.leftCount;
+  const releaseCount = snapshot.victory.releaseCount || lemmings.length;
+  const targetSaveCount = normalized.targetSaveCount || snapshot.victory.needCount || 1;
+  const maximumReachableSaveCount = savedCount + active.length + leftCount;
+  const frontier = [...active].sort((left, right) => (
+    right.x - left.x ||
+    left.y - right.y ||
+    Number(left.id) - Number(right.id)
+  ))[0] ?? null;
+  const lead = active[0] ?? null;
+  const rescue = active.find(lemming => lemming.fallDistance > 0) ?? null;
+  const blockerAnchor = active.find(lemming => actionName(lemming).includes('block')) ?? lead;
+  const builderCandidate = frontier ?? lead;
+  const roles = uniqueRoles([
+    roleRecord('lead', lead, 'earliest active lemming in deterministic order'),
+    roleRecord('frontier', frontier, 'rightmost active lemming for forward route progress'),
+    roleRecord('builder-candidate', builderCandidate, 'frontier lemming has first chance to bridge or climb route gaps'),
+    roleRecord('blocker-anchor', blockerAnchor, 'candidate for simple crowd turnaround or hold'),
+    roleRecord('crowd-representative', lead, 'stable representative for trailing crowd state'),
+    roleRecord('rescue-candidate', rescue, rescue ? 'active lemming currently carrying fall risk' : 'no immediate rescue target')
+  ]);
+  const crowd = {
+    kind: 'solver-crowd-analysis',
+    stateHash: snapshot.snapshotHash,
+    targetSaveCount,
+    savedCount,
+    deadCount,
+    activeCount: active.length,
+    leftCount,
+    releaseCount,
+    maximumReachableSaveCount,
+    routeSuccessCanSatisfySaveCount: maximumReachableSaveCount >= targetSaveCount,
+    roles,
+    crowdRisk: {
+      saveCountUnreachable: maximumReachableSaveCount < targetSaveCount,
+      activeHazardCount: active.filter(lemming => lemming.fallDistance > 0).length,
+      blockerNeeded: active.length > 1 && snapshot.skills.counts.blocker > 0
+    }
+  };
+  crowd.crowdHash = stableHash(crowd);
+  return crowd;
+};
+
+const validateSaveCountForResult = (result, crowd, options = {}) => {
+  const targetSaveCount = Math.max(0, Math.floor(
+    Number(options.targetSaveCount ?? crowd?.targetSaveCount ?? 1) || 0
+  ));
+  const savedCount = Math.max(0, Math.floor(Number(
+    result?.replaySummary?.savedCount ?? crowd?.savedCount ?? 0
+  ) || 0));
+  if (result?.resultType !== SOLVER_RESULT_TYPES.SOLVED || savedCount >= targetSaveCount) {
+    return result;
+  }
+  const next = createSolverResult({
+    resultType: SOLVER_RESULT_TYPES.FAILED,
+    summary: `Route replay saved ${savedCount} of ${targetSaveCount} required lemming(s)`,
+    actions: result.actions,
+    explanations: [{
+      code: SOLVER_EXPLANATION_CODES.SAVE_COUNT_UNREACHABLE,
+      detail: 'The action script reaches a route goal but fails the required save count.',
+      data: { savedCount, targetSaveCount }
+    }],
+    budgetUsage: result.budgetUsage,
+    replaySummary: result.replaySummary,
+    captures: result.captures
+  });
+  next.crowd = crowd;
+  return next;
+};
+
+export {
+  analyzeSolverCrowd,
+  validateSaveCountForResult
+};
diff --git a/js/solver/SolverFixtures.js b/js/solver/SolverFixtures.js
new file mode 100644
index 00000000..b7e57bc7
--- /dev/null
+++ b/js/solver/SolverFixtures.js
@@ -0,0 +1,111 @@
+const createMask = (width, height) => new Uint8Array(Math.max(0, width * height));
+
+const fillRect = (mask, width, height, rect, value = 1) => {
+  if (!mask || !rect) return;
+  const x0 = Math.max(0, Math.floor(rect.x ?? 0));
+  const y0 = Math.max(0, Math.floor(rect.y ?? 0));
+  const x1 = Math.min(width, Math.ceil(x0 + (rect.width ?? 0)));
+  const y1 = Math.min(height, Math.ceil(y0 + (rect.height ?? 0)));
+  for (let y = y0; y < y1; y += 1) {
+    const row = y * width;
+    for (let x = x0; x < x1; x += 1) {
+      mask[row + x] = value ? 1 : 0;
+    }
+  }
+};
+
+const cloneRects = rects => Array.isArray(rects)
+  ? rects.map(rect => ({ ...rect }))
+  : [];
+
+const createSyntheticSolverFixture = ({
+  id = 'synthetic',
+  width = 160,
+  height = 80,
+  ground = [],
+  steel = [],
+  oneWay = [],
+  hazards = [],
+  entrances = [{ x: 8, y: 48 }],
+  exits = [{ x: width - 16, y: 48 }],
+  lemmings = [{ id: 0, x: 8, y: 48, lookRight: true, action: 'walking' }],
+  skills = {},
+  timer = { tick: 0, timeLimit: 0 },
+  needCount = 1,
+  releaseCount = lemmings.length || 1
+} = {}) => {
+  const safeWidth = Math.max(1, Math.floor(width));
+  const safeHeight = Math.max(1, Math.floor(height));
+  const groundMask = createMask(safeWidth, safeHeight);
+  const steelMask = createMask(safeWidth, safeHeight);
+  for (const rect of ground) fillRect(groundMask, safeWidth, safeHeight, rect, 1);
+  for (const rect of steel) fillRect(steelMask, safeWidth, safeHeight, rect, 1);
+  return {
+    kind: 'synthetic',
+    id,
+    width: safeWidth,
+    height: safeHeight,
+    groundMask,
+    steelMask,
+    oneWay: cloneRects(oneWay),
+    hazards: cloneRects(hazards),
+    entrances: cloneRects(entrances),
+    exits: cloneRects(exits),
+    lemmings: Array.isArray(lemmings) ? lemmings.map(lem => ({ ...lem })) : [],
+    skills: { ...skills },
+    timer: { ...timer },
+    needCount: Math.max(0, Math.floor(needCount)),
+    releaseCount: Math.max(0, Math.floor(releaseCount))
+  };
+};
+
+const createFlatWalkFixture = (overrides = {}) => createSyntheticSolverFixture({
+  id: 'flat-walk',
+  width: 120,
+  height: 64,
+  ground: [{ x: 0, y: 52, width: 120, height: 4 }],
+  entrances: [{ x: 8, y: 51 }],
+  exits: [{ x: 104, y: 51 }],
+  lemmings: [{ id: 0, x: 8, y: 51, lookRight: true, action: 'walking' }],
+  skills: {},
+  ...overrides
+});
+
+const createSmallGapFixture = (overrides = {}) => createSyntheticSolverFixture({
+  id: 'small-gap',
+  width: 140,
+  height: 72,
+  ground: [
+    { x: 0, y: 58, width: 48, height: 4 },
+    { x: 58, y: 58, width: 82, height: 4 }
+  ],
+  entrances: [{ x: 12, y: 57 }],
+  exits: [{ x: 120, y: 57 }],
+  lemmings: [{ id: 0, x: 20, y: 57, lookRight: true, action: 'walking' }],
+  skills: { builder: 2 },
+  ...overrides
+});
+
+const createBarrierFixture = (overrides = {}) => createSyntheticSolverFixture({
+  id: 'small-barrier',
+  width: 140,
+  height: 72,
+  ground: [
+    { x: 0, y: 58, width: 140, height: 4 },
+    { x: 62, y: 48, width: 8, height: 10 }
+  ],
+  entrances: [{ x: 12, y: 57 }],
+  exits: [{ x: 120, y: 57 }],
+  lemmings: [{ id: 0, x: 20, y: 57, lookRight: true, action: 'walking' }],
+  skills: { basher: 1, digger: 1, miner: 1 },
+  ...overrides
+});
+
+export {
+  createBarrierFixture,
+  createFlatWalkFixture,
+  createMask,
+  createSmallGapFixture,
+  createSyntheticSolverFixture,
+  fillRect
+};
diff --git a/js/solver/SolverGeometry.js b/js/solver/SolverGeometry.js
new file mode 100644
index 00000000..2b34db1d
--- /dev/null
+++ b/js/solver/SolverGeometry.js
@@ -0,0 +1,470 @@
+import { extractSolverState, isSolverState, stableHash } from './SolverState.js';
+
+const DEFAULT_GEOMETRY_OPTIONS = Object.freeze({
+  maxSmallGap: 12,
+  maxStepHeight: 4,
+  maxSafeFall: 60,
+  landingSearchDepth: 96,
+  entranceSnapRadius: 24,
+  exitSnapRadius: 24,
+  minSurfaceWidth: 1
+});
+
+const toOptions = options => ({
+  ...DEFAULT_GEOMETRY_OPTIONS,
+  ...options
+});
+
+const maskAt = (mask, width, height, x, y) => {
+  if (x < 0 || x >= width || y < 0 || y >= height) return false;
+  return mask[y * width + x] !== 0;
+};
+
+const isGroundAt = (snapshot, x, y) => (
+  maskAt(snapshot.terrain.mask, snapshot.width, snapshot.height, x, y)
+);
+
+const isSteelAt = (snapshot, x, y) => (
+  maskAt(snapshot.steel.mask, snapshot.width, snapshot.height, x, y)
+);
+
+const rectRight = rect => rect.x + rect.width - 1;
+
+const rectBottom = rect => rect.y + rect.height - 1;
+
+const rectsOverlap = (a, b) => (
+  a.x <= rectRight(b) &&
+  rectRight(a) >= b.x &&
+  a.y <= rectBottom(b) &&
+  rectBottom(a) >= b.y
+);
+
+const surfaceOverlapRect = surface => ({
+  x: surface.x,
+  y: surface.y - 2,
+  width: surface.width,
+  height: 5
+});
+
+const countSteelInRect = (snapshot, rect) => {
+  let count = 0;
+  const x1 = Math.max(0, rect.x);
+  const y1 = Math.max(0, rect.y);
+  const x2 = Math.min(snapshot.width - 1, rectRight(rect));
+  const y2 = Math.min(snapshot.height - 1, rectBottom(rect));
+  for (let y = y1; y <= y2; y += 1) {
+    for (let x = x1; x <= x2; x += 1) {
+      if (isSteelAt(snapshot, x, y)) count += 1;
+    }
+  }
+  return count;
+};
+
+const buildWalkableSurfaces = snapshot => {
+  const surfaces = [];
+  for (let y = 0; y < snapshot.height - 1; y += 1) {
+    let startX = -1;
+    for (let x = 0; x < snapshot.width; x += 1) {
+      const walkable = !isGroundAt(snapshot, x, y) && isGroundAt(snapshot, x, y + 1);
+      if (walkable && startX < 0) {
+        startX = x;
+      } else if (!walkable && startX >= 0) {
+        surfaces.push({
+          x: startX,
+          y,
+          width: x - startX
+        });
+        startX = -1;
+      }
+    }
+    if (startX >= 0) {
+      surfaces.push({
+        x: startX,
+        y,
+        width: snapshot.width - startX
+      });
+    }
+  }
+  return surfaces
+    .filter(surface => surface.width > 0)
+    .sort((a, b) => a.x - b.x || a.y - b.y || b.width - a.width)
+    .map((surface, id) => {
+      const rect = {
+        x: surface.x,
+        y: surface.y + 1,
+        width: surface.width,
+        height: 1
+      };
+      const hazardKinds = snapshot.hazards
+        .filter(hazard => rectsOverlap(surfaceOverlapRect(surface), hazard))
+        .map(hazard => hazard.kind)
+        .sort();
+      const entrances = snapshot.entrances
+        .filter(entrance => rectsOverlap(surfaceOverlapRect(surface), entrance))
+        .map(entrance => entrance.index);
+      const exits = snapshot.exits
+        .filter(exit => rectsOverlap(surfaceOverlapRect(surface), exit))
+        .map(exit => exit.index);
+      const steelCount = countSteelInRect(snapshot, rect);
+      return {
+        id,
+        x: surface.x,
+        y: surface.y,
+        width: surface.width,
+        left: surface.x,
+        right: surface.x + surface.width - 1,
+        steelCount,
+        hasSteel: steelCount > 0,
+        hazardKinds,
+        hasHazard: hazardKinds.length > 0,
+        entrances,
+        exits
+      };
+    });
+};
+
+const findSurfaceAt = (surfaces, x, y, radius) => {
+  let best = null;
+  let bestScore = Infinity;
+  for (const surface of surfaces) {
+    const dx = x < surface.left ? surface.left - x : Math.max(0, x - surface.right);
+    const dy = Math.abs(surface.y - y);
+    if (dx > radius || dy > radius) continue;
+    const score = dx * 4 + dy;
+    if (score < bestScore) {
+      best = surface;
+      bestScore = score;
+    }
+  }
+  return best;
+};
+
+const rectAnchor = rect => ({
+  x: Math.trunc(rect.x + Math.max(0, rect.width - 1) / 2),
+  y: Math.trunc(rect.y + Math.max(0, rect.height - 1))
+});
+
+const findLandingBelow = (snapshot, surfaces, x, startY, options) => {
+  if (x < 0 || x >= snapshot.width) return null;
+  const limit = Math.min(snapshot.height - 2, startY + options.landingSearchDepth);
+  for (let y = Math.max(0, startY); y <= limit; y += 1) {
+    if (!isGroundAt(snapshot, x, y) && isGroundAt(snapshot, x, y + 1)) {
+      const surface = findSurfaceAt(surfaces, x, y, 1);
+      return {
+        x,
+        y,
+        surfaceId: surface?.id ?? null
+      };
+    }
+  }
+  return null;
+};
+
+const buildCliffs = (snapshot, surfaces, options) => {
+  const cliffs = [];
+  for (const surface of surfaces) {
+    const edges = [
+      { side: 'left', x: surface.left - 1 },
+      { side: 'right', x: surface.right + 1 }
+    ];
+    for (const edge of edges) {
+      const outOfLevel = edge.x < 0 || edge.x >= snapshot.width;
+      const landing = outOfLevel
+        ? null
+        : findLandingBelow(snapshot, surfaces, edge.x, surface.y + 1, options);
+      const fallDistance = landing ? landing.y - surface.y : null;
+      cliffs.push({
+        surfaceId: surface.id,
+        side: edge.side,
+        x: edge.x,
+        y: surface.y,
+        outOfLevel,
+        fallDistance,
+        landing,
+        safe: Number.isFinite(fallDistance) && fallDistance <= options.maxSafeFall
+      });
+    }
+  }
+  return cliffs;
+};
+
+const isGapEmpty = (snapshot, leftSurface, rightSurface) => {
+  const startX = leftSurface.right + 1;
+  const endX = rightSurface.left - 1;
+  if (startX > endX) return false;
+  const y = Math.max(leftSurface.y, rightSurface.y);
+  for (let x = startX; x <= endX; x += 1) {
+    if (isGroundAt(snapshot, x, y) || isGroundAt(snapshot, x, y + 1)) return false;
+  }
+  return true;
+};
+
+const buildGaps = (snapshot, surfaces, options) => {
+  const gaps = [];
+  for (let i = 0; i < surfaces.length; i += 1) {
+    for (let j = 0; j < surfaces.length; j += 1) {
+      if (i === j) continue;
+      const left = surfaces[i];
+      const right = surfaces[j];
+      if (right.left <= left.right + 1) continue;
+      const verticalDelta = Math.abs(right.y - left.y);
+      if (verticalDelta > options.maxStepHeight) continue;
+      if (!isGapEmpty(snapshot, left, right)) continue;
+      const width = right.left - left.right - 1;
+      gaps.push({
+        fromSurfaceId: left.id,
+        toSurfaceId: right.id,
+        x: left.right + 1,
+        y: Math.max(left.y, right.y),
+        width,
+        verticalDelta,
+        isSmall: width <= options.maxSmallGap,
+        bridgeable: width <= options.maxSmallGap
+      });
+    }
+  }
+  return gaps.sort((a, b) => a.x - b.x || a.y - b.y || a.width - b.width);
+};
+
+const measureWallHeight = (snapshot, x, y) => {
+  let height = 0;
+  for (let yy = y; yy >= 0; yy -= 1) {
+    if (!isGroundAt(snapshot, x, yy)) break;
+    height += 1;
+  }
+  return height;
+};
+
+const findBarrierFromEdge = (snapshot, surface, side, options) => {
+  const direction = side === 'right' ? 1 : -1;
+  const edgeX = side === 'right' ? surface.right + 1 : surface.left - 1;
+  if (edgeX < 0 || edgeX >= snapshot.width) return null;
+  const height = measureWallHeight(snapshot, edgeX, surface.y);
+  if (height <= options.maxStepHeight) return null;
+  let width = 0;
+  let cursor = edgeX;
+  while (cursor >= 0 && cursor < snapshot.width) {
+    const nextHeight = measureWallHeight(snapshot, cursor, surface.y);
+    if (nextHeight <= options.maxStepHeight) break;
+    width += 1;
+    cursor += direction;
+  }
+  const x = direction > 0 ? edgeX : edgeX - width + 1;
+  const rect = {
+    x,
+    y: surface.y - height + 1,
+    width,
+    height
+  };
+  const steelCount = countSteelInRect(snapshot, rect);
+  return {
+    surfaceId: surface.id,
+    side,
+    x: rect.x,
+    y: rect.y,
+    width: rect.width,
+    height: rect.height,
+    bottomY: surface.y,
+    steelCount,
+    hasSteel: steelCount > 0
+  };
+};
+
+const buildBarriers = (snapshot, surfaces, options) => {
+  const seen = new Set();
+  const barriers = [];
+  for (const surface of surfaces) {
+    for (const side of ['left', 'right']) {
+      const barrier = findBarrierFromEdge(snapshot, surface, side, options);
+      if (!barrier) continue;
+      const key = `${barrier.x}:${barrier.y}:${barrier.width}:${barrier.height}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      barriers.push({ ...barrier, id: barriers.length });
+    }
+  }
+  return barriers.sort((a, b) => a.x - b.x || a.y - b.y || b.height - a.height)
+    .map((barrier, id) => ({ ...barrier, id }));
+};
+
+const buildLandingZones = (surfaces, cliffs) => {
+  const landingsBySurface = new Map();
+  for (const cliff of cliffs) {
+    if (cliff.landing?.surfaceId == null) continue;
+    if (!landingsBySurface.has(cliff.landing.surfaceId)) {
+      landingsBySurface.set(cliff.landing.surfaceId, []);
+    }
+    landingsBySurface.get(cliff.landing.surfaceId).push({
+      fromSurfaceId: cliff.surfaceId,
+      fallDistance: cliff.fallDistance,
+      side: cliff.side
+    });
+  }
+  return surfaces.map(surface => ({
+    surfaceId: surface.id,
+    x: surface.x,
+    y: surface.y,
+    width: surface.width,
+    safe: !surface.hasHazard,
+    incomingFalls: landingsBySurface.get(surface.id) ?? []
+  }));
+};
+
+const addEdge = (edges, from, to, type, data = {}) => {
+  if (from == null || to == null || from === to) return;
+  if (!edges.has(from)) edges.set(from, []);
+  const bucket = edges.get(from);
+  if (bucket.some(edge => edge.to === to && edge.type === type)) return;
+  bucket.push({ from, to, type, ...data });
+};
+
+const buildRouteEdges = (surfaces, gaps, cliffs, options) => {
+  const edges = new Map();
+  for (const gap of gaps) {
+    if (!gap.bridgeable) continue;
+    addEdge(edges, gap.fromSurfaceId, gap.toSurfaceId, 'small-gap', {
+      width: gap.width
+    });
+    addEdge(edges, gap.toSurfaceId, gap.fromSurfaceId, 'small-gap', {
+      width: gap.width
+    });
+  }
+  for (const cliff of cliffs) {
+    if (!cliff.safe || cliff.landing?.surfaceId == null) continue;
+    addEdge(edges, cliff.surfaceId, cliff.landing.surfaceId, 'fall', {
+      fallDistance: cliff.fallDistance
+    });
+  }
+  for (const left of surfaces) {
+    for (const right of surfaces) {
+      if (left.id === right.id) continue;
+      const touching = right.left <= left.right + 1 && right.right >= left.left - 1;
+      if (!touching) continue;
+      const step = Math.abs(right.y - left.y);
+      if (step > options.maxStepHeight) continue;
+      addEdge(edges, left.id, right.id, 'step', { step });
+    }
+  }
+  return edges;
+};
+
+const resolveEndpointSurfaceIds = (rects, surfaces, radius) => rects
+  .map(rect => {
+    const anchor = rectAnchor(rect);
+    return findSurfaceAt(surfaces, anchor.x, anchor.y, radius)?.id ?? null;
+  })
+  .filter(id => id != null);
+
+const traverseRoute = (surfaceIds, exitIds, surfaces, edges) => {
+  const exitSet = new Set(exitIds);
+  const blockedHazards = [];
+  const queue = [];
+  const visited = new Set();
+  for (const id of surfaceIds) {
+    const surface = surfaces[id];
+    if (!surface || surface.hasHazard) {
+      if (surface?.hasHazard) blockedHazards.push(id);
+      continue;
+    }
+    queue.push(id);
+    visited.add(id);
+  }
+  while (queue.length) {
+    const current = queue.shift();
+    if (exitSet.has(current)) {
+      return {
+        continuous: true,
+        reachableSurfaceIds: Array.from(visited).sort((a, b) => a - b),
+        blockedHazardSurfaceIds: blockedHazards
+      };
+    }
+    for (const edge of edges.get(current) ?? []) {
+      const surface = surfaces[edge.to];
+      if (!surface || visited.has(edge.to)) continue;
+      if (surface.hasHazard) {
+        blockedHazards.push(edge.to);
+        continue;
+      }
+      visited.add(edge.to);
+      queue.push(edge.to);
+    }
+  }
+  return {
+    continuous: false,
+    reachableSurfaceIds: Array.from(visited).sort((a, b) => a - b),
+    blockedHazardSurfaceIds: blockedHazards.sort((a, b) => a - b)
+  };
+};
+
+const buildRouteContinuity = (snapshot, surfaces, gaps, cliffs, options) => {
+  const entranceSurfaceIds = resolveEndpointSurfaceIds(
+    snapshot.entrances,
+    surfaces,
+    options.entranceSnapRadius
+  );
+  const exitSurfaceIds = resolveEndpointSurfaceIds(
+    snapshot.exits,
+    surfaces,
+    options.exitSnapRadius
+  );
+  const edges = buildRouteEdges(surfaces, gaps, cliffs, options);
+  const route = traverseRoute(entranceSurfaceIds, exitSurfaceIds, surfaces, edges);
+  return {
+    continuous: route.continuous,
+    entranceSurfaceIds,
+    exitSurfaceIds,
+    reachableSurfaceIds: route.reachableSurfaceIds,
+    blockedHazardSurfaceIds: route.blockedHazardSurfaceIds,
+    edgeCount: Array.from(edges.values()).reduce((sum, bucket) => sum + bucket.length, 0),
+    blocked: !route.continuous,
+    missingEntrance: entranceSurfaceIds.length === 0,
+    missingExit: exitSurfaceIds.length === 0
+  };
+};
+
+const analyzeSolverGeometry = (input, options = {}) => {
+  const normalizedOptions = toOptions(options);
+  const snapshot = isSolverState(input) ? input : extractSolverState(input);
+  const surfaces = buildWalkableSurfaces(snapshot)
+    .filter(surface => surface.width >= normalizedOptions.minSurfaceWidth);
+  const cliffs = buildCliffs(snapshot, surfaces, normalizedOptions);
+  const gaps = buildGaps(snapshot, surfaces, normalizedOptions);
+  const barriers = buildBarriers(snapshot, surfaces, normalizedOptions);
+  const landingZones = buildLandingZones(surfaces, cliffs);
+  const routeContinuity = buildRouteContinuity(
+    snapshot,
+    surfaces,
+    gaps,
+    cliffs,
+    normalizedOptions
+  );
+  const geometry = {
+    kind: 'solver-geometry',
+    stateHash: snapshot.snapshotHash,
+    terrainHash: snapshot.terrainHash,
+    terrainMutationHash: snapshot.terrainMutationHash,
+    width: snapshot.width,
+    height: snapshot.height,
+    surfaces,
+    cliffs,
+    gaps,
+    barriers,
+    landingZones,
+    routeContinuity
+  };
+  geometry.geometryHash = stableHash({
+    stateHash: geometry.stateHash,
+    surfaces,
+    cliffs,
+    gaps,
+    barriers,
+    landingZones,
+    routeContinuity
+  });
+  return geometry;
+};
+
+export {
+  DEFAULT_GEOMETRY_OPTIONS,
+  analyzeSolverGeometry
+};
diff --git a/js/solver/SolverRunner.js b/js/solver/SolverRunner.js
new file mode 100644
index 00000000..a34c801c
--- /dev/null
+++ b/js/solver/SolverRunner.js
@@ -0,0 +1,1125 @@
+import {
+  SOLVER_EXPLANATION_CODES,
+  SOLVER_RESULT_TYPES,
+  createSolverResult,
+  normalizeActionScriptAction,
+  normalizeSolverOptions
+} from './SolverTypes.js';
+import { GameStateTypes } from '../game/GameStateTypes.js';
+import { SkillTypes } from '../game/SkillTypes.js';
+import { extractSolverState, stableHash } from './SolverState.js';
+
+const SYNTHETIC_RUNNER_KIND = 'synthetic';
+
+const SKILL_TYPE_BY_NAME = Object.freeze({
+  climber: SkillTypes.CLIMBER,
+  floater: SkillTypes.FLOATER,
+  bomber: SkillTypes.BOMBER,
+  blocker: SkillTypes.BLOCKER,
+  builder: SkillTypes.BUILDER,
+  basher: SkillTypes.BASHER,
+  miner: SkillTypes.MINER,
+  digger: SkillTypes.DIGGER
+});
+
+const cloneRectList = value => Array.isArray(value)
+  ? value.map(rect => ({ ...rect }))
+  : [];
+
+const toInteger = (value, fallback = 0) => {
+  const next = Number(value);
+  return Number.isFinite(next) ? Math.floor(next) : fallback;
+};
+
+const getSourceKind = source => {
+  if (source?.kind === SYNTHETIC_RUNNER_KIND || source?.fixture?.kind === SYNTHETIC_RUNNER_KIND) {
+    return SYNTHETIC_RUNNER_KIND;
+  }
+  const raw = String(source?.kind ?? source?.type ?? source?.sourceKind ?? '').trim().toLowerCase();
+  if (raw === 'editor' || raw === 'editor-level') return 'editor';
+  if (raw === 'procgen' || raw === 'procgen-chunk') return 'procgen';
+  if (raw === 'builtin' || raw === 'built-in') return 'builtin';
+  return raw || 'unknown';
+};
+
+const createUnsupportedRunnerResult = (sourceKind, detail = 'Solver runner source is not wired yet') => ({
+  sourceKind,
+  runner: null,
+  result: createSolverResult({
+    resultType: SOLVER_RESULT_TYPES.UNSUPPORTED,
+    summary: `${sourceKind} solver runner is not supported yet`,
+    explanations: [{
+      code: SOLVER_EXPLANATION_CODES.UNSUPPORTED_MECHANIC,
+      detail
+    }]
+  })
+});
+
+const cloneMask = (mask, width, height) => {
+  const size = Math.max(0, width * height);
+  if (mask instanceof Uint8Array) return new Uint8Array(mask);
+  if (Array.isArray(mask)) return Uint8Array.from(mask.slice(0, size));
+  return new Uint8Array(size);
+};
+
+const cloneSkills = skills => {
+  const out = {};
+  if (skills == null || typeof skills !== 'object') return out;
+  for (const [key, value] of Object.entries(skills)) {
+    const count = Number(value);
+    out[key] = Number.isFinite(count) ? Math.max(0, Math.floor(count)) : 0;
+  }
+  return out;
+};
+
+const cloneLemming = (lemming, index) => ({
+  id: lemming?.id ?? index,
+  x: toInteger(lemming?.x, 0),
+  y: toInteger(lemming?.y, 0),
+  lookRight: lemming?.lookRight !== false,
+  action: String(lemming?.action || 'walking'),
+  saved: Boolean(lemming?.saved),
+  dead: Boolean(lemming?.dead),
+  fallDistance: Math.max(0, toInteger(lemming?.fallDistance, 0)),
+  lastSkill: lemming?.lastSkill == null ? null : String(lemming.lastSkill)
+});
+
+const hashSummary = value => {
+  const text = JSON.stringify(value);
+  let hash = 2166136261;
+  for (let i = 0; i < text.length; i += 1) {
+    hash ^= text.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, '0');
+};
+
+const withStateHash = summary => ({
+  ...summary,
+  stateHash: summary.stateHash ?? hashSummary(summary)
+});
+
+const hasRunnerAdapterShape = value => (
+  value != null &&
+  typeof value.step === 'function' &&
+  typeof value.applyAction === 'function' &&
+  typeof value.getFinalStateSummary === 'function'
+);
+
+const normalizeSkillTypeForRuntime = skillType => {
+  if (Number.isInteger(skillType)) return skillType;
+  const key = String(skillType || '').trim().toLowerCase();
+  return SKILL_TYPE_BY_NAME[key] ?? SkillTypes.UNKNOWN;
+};
+
+const summaryCount = (summary, key, fallback = 0) => Math.max(0, toInteger(summary?.[key], fallback));
+
+const activeFromSummary = summary => Array.isArray(summary?.lemmings)
+  ? summary.lemmings.filter(lemming => !lemming.saved && !lemming.dead && !lemming.removed && !lemming.disabled)
+  : [];
+
+class SyntheticSolverRunner {
+  constructor(fixture = {}, options = {}) {
+    const width = Math.max(1, toInteger(fixture.width, 1));
+    const height = Math.max(1, toInteger(fixture.height, 1));
+    this.kind = SYNTHETIC_RUNNER_KIND;
+    this.id = String(fixture.id || SYNTHETIC_RUNNER_KIND);
+    this.width = width;
+    this.height = height;
+    this.groundMask = cloneMask(fixture.groundMask, width, height);
+    this.steelMask = cloneMask(fixture.steelMask, width, height);
+    this.oneWay = cloneRectList(fixture.oneWay);
+    this.hazards = cloneRectList(fixture.hazards);
+    this.entrances = cloneRectList(fixture.entrances);
+    this.exits = cloneRectList(fixture.exits);
+    this.skills = cloneSkills(fixture.skills);
+    this.lemmings = Array.isArray(fixture.lemmings)
+      ? fixture.lemmings.map(cloneLemming)
+      : [];
+    this.needCount = Math.max(0, toInteger(fixture.needCount, 1));
+    this.releaseCount = Math.max(0, toInteger(fixture.releaseCount, this.lemmings.length));
+    this.tick = Math.max(0, toInteger(fixture.timer?.tick, 0));
+    this.options = normalizeSolverOptions(options);
+    this.builderLength = Math.max(1, toInteger(options.builderLength, 12));
+    this.maxSurvivableFall = Math.max(1, toInteger(options.maxSurvivableFall, 12));
+  }
+
+  getSavedCount() {
+    return this.lemmings.filter(lemming => lemming.saved).length;
+  }
+
+  getDeadCount() {
+    return this.lemmings.filter(lemming => lemming.dead).length;
+  }
+
+  getActiveLemmings() {
+    return this.lemmings.filter(lemming => !lemming.saved && !lemming.dead);
+  }
+
+  getSkillCount(skillType) {
+    return this.skills[String(skillType || '')] ?? 0;
+  }
+
+  selectLemming(target) {
+    const active = this.getActiveLemmings();
+    if (target == null) return active[0] ?? this.lemmings[0] ?? null;
+    if (typeof target === 'number') return this.lemmings.find(lemming => lemming.id === target) ?? null;
+    if (typeof target === 'string') {
+      if (target === 'first' || target === 'lead') return active[0] ?? null;
+      return this.lemmings.find(lemming => String(lemming.id) === target) ?? null;
+    }
+    if (typeof target === 'object') {
+      if (target.id != null) {
+        return this.lemmings.find(lemming => String(lemming.id) === String(target.id)) ?? null;
+      }
+      if (target.index != null) return this.lemmings[toInteger(target.index, -1)] ?? null;
+    }
+    return active[0] ?? null;
+  }
+
+  isTerminal() {
+    return this.getActiveLemmings().length === 0;
+  }
+
+  step(count = 1) {
+    const safeCount = Math.max(1, toInteger(count, 1));
+    for (let i = 0; i < safeCount; i += 1) {
+      this.#stepOneTick();
+    }
+    return this.getFinalStateSummary();
+  }
+
+  applyAction(action) {
+    const normalized = normalizeActionScriptAction(action);
+    const lemming = this.selectLemming(normalized.target);
+    if (!lemming || lemming.saved || lemming.dead) {
+      return {
+        ok: false,
+        detail: `No active target lemming for ${normalized.skillType || 'action'}`
+      };
+    }
+
+    const skillType = String(normalized.skillType || 'wait').toLowerCase();
+    if (skillType === 'wait' || skillType === 'noop') {
+      lemming.lastSkill = skillType;
+      return { ok: true, lemmingId: lemming.id, skillType };
+    }
+    if (this.getSkillCount(skillType) <= 0) {
+      return {
+        ok: false,
+        detail: `No ${skillType} skill remains`
+      };
+    }
+
+    if (skillType === 'builder') return this.#applyBuilder(lemming, skillType);
+    if (skillType === 'basher') return this.#applyBasher(lemming, skillType);
+    if (skillType === 'digger') return this.#applyDigger(lemming, skillType);
+    if (skillType === 'miner') return this.#applyMiner(lemming, skillType);
+    if (skillType === 'blocker') return this.#applyBlocker(lemming, skillType);
+
+    return {
+      ok: false,
+      detail: `Synthetic runner does not support ${skillType}`
+    };
+  }
+
+  getFinalStateSummary() {
+    const lemmings = this.lemmings.map(lemming => ({
+      id: lemming.id,
+      x: lemming.x,
+      y: lemming.y,
+      lookRight: lemming.lookRight,
+      action: lemming.action,
+      saved: lemming.saved,
+      dead: lemming.dead,
+      fallDistance: lemming.fallDistance,
+      lastSkill: lemming.lastSkill
+    }));
+    const summary = {
+      sourceKind: this.kind,
+      id: this.id,
+      tick: this.tick,
+      width: this.width,
+      height: this.height,
+      savedCount: this.getSavedCount(),
+      deadCount: this.getDeadCount(),
+      activeCount: this.getActiveLemmings().length,
+      needCount: this.needCount,
+      releaseCount: this.releaseCount,
+      skills: { ...this.skills },
+      lemmings
+    };
+    return { ...summary, stateHash: hashSummary(summary) };
+  }
+
+  #stepOneTick() {
+    for (const lemming of this.lemmings) {
+      if (lemming.saved || lemming.dead) continue;
+      this.#maybeExit(lemming);
+      if (lemming.saved) continue;
+      if (this.#isInHazard(lemming.x, lemming.y)) {
+        lemming.dead = true;
+        lemming.action = 'dead';
+        continue;
+      }
+
+      const supported = this.#hasSupport(lemming.x, lemming.y);
+      if (!supported) {
+        this.#fall(lemming);
+        continue;
+      }
+
+      lemming.fallDistance = 0;
+      const dx = lemming.lookRight ? 1 : -1;
+      const nextX = lemming.x + dx;
+      if (this.#isBlocked(nextX, lemming.y)) {
+        lemming.action = 'stopped';
+        continue;
+      }
+      lemming.x = nextX;
+      lemming.action = 'walking';
+      if (!this.#hasSupport(lemming.x, lemming.y)) this.#fall(lemming);
+      this.#maybeExit(lemming);
+    }
+    this.tick += 1;
+  }
+
+  #fall(lemming) {
+    lemming.y += 1;
+    lemming.fallDistance += 1;
+    lemming.action = 'falling';
+    if (lemming.y >= this.height || lemming.fallDistance > this.maxSurvivableFall) {
+      lemming.dead = true;
+      lemming.action = 'dead';
+    }
+  }
+
+  #applyBuilder(lemming, skillType) {
+    this.#consumeSkill(skillType);
+    const dx = lemming.lookRight ? 1 : -1;
+    const y = lemming.y + 1;
+    for (let step = 1; step <= this.builderLength; step += 1) {
+      this.#setGround(lemming.x + (dx * step), y, true);
+    }
+    lemming.action = 'building';
+    lemming.lastSkill = skillType;
+    return { ok: true, lemmingId: lemming.id, skillType };
+  }
+
+  #applyBasher(lemming, skillType) {
+    this.#consumeSkill(skillType);
+    const dx = lemming.lookRight ? 1 : -1;
+    for (let step = 1; step <= 10; step += 1) {
+      const x = lemming.x + (dx * step);
+      for (let y = lemming.y - 8; y <= lemming.y + 1; y += 1) {
+        if (!this.#isSteel(x, y)) this.#setGround(x, y, false);
+      }
+    }
+    lemming.action = 'bashing';
+    lemming.lastSkill = skillType;
+    return { ok: true, lemmingId: lemming.id, skillType };
+  }
+
+  #applyDigger(lemming, skillType) {
+    this.#consumeSkill(skillType);
+    for (let y = lemming.y + 1; y <= lemming.y + 12; y += 1) {
+      for (let x = lemming.x - 2; x <= lemming.x + 2; x += 1) {
+        if (!this.#isSteel(x, y)) this.#setGround(x, y, false);
+      }
+    }
+    lemming.action = 'digging';
+    lemming.lastSkill = skillType;
+    return { ok: true, lemmingId: lemming.id, skillType };
+  }
+
+  #applyMiner(lemming, skillType) {
+    this.#consumeSkill(skillType);
+    const dx = lemming.lookRight ? 1 : -1;
+    for (let step = 1; step <= 12; step += 1) {
+      const x = lemming.x + (dx * step);
+      const y = lemming.y + Math.floor(step / 2);
+      for (let dy = -1; dy <= 2; dy += 1) {
+        if (!this.#isSteel(x, y + dy)) this.#setGround(x, y + dy, false);
+      }
+    }
+    lemming.action = 'mining';
+    lemming.lastSkill = skillType;
+    return { ok: true, lemmingId: lemming.id, skillType };
+  }
+
+  #applyBlocker(lemming, skillType) {
+    this.#consumeSkill(skillType);
+    lemming.lookRight = !lemming.lookRight;
+    lemming.action = 'blocking';
+    lemming.lastSkill = skillType;
+    return { ok: true, lemmingId: lemming.id, skillType };
+  }
+
+  #consumeSkill(skillType) {
+    this.skills[skillType] = Math.max(0, this.getSkillCount(skillType) - 1);
+  }
+
+  #hasSupport(x, y) {
+    return this.#isGround(x, y + 1);
+  }
+
+  #isBlocked(x, y) {
+    return this.#isGround(x, y) || this.#isSteel(x, y);
+  }
+
+  #isGround(x, y) {
+    return this.#maskValue(this.groundMask, x, y) > 0;
+  }
+
+  #isSteel(x, y) {
+    return this.#maskValue(this.steelMask, x, y) > 0;
+  }
+
+  #setGround(x, y, value) {
+    const index = this.#maskIndex(x, y);
+    if (index < 0) return;
+    this.groundMask[index] = value ? 1 : 0;
+  }
+
+  #maskValue(mask, x, y) {
+    const index = this.#maskIndex(x, y);
+    return index < 0 ? 0 : mask[index];
+  }
+
+  #maskIndex(x, y) {
+    const ix = toInteger(x, -1);
+    const iy = toInteger(y, -1);
+    if (ix < 0 || iy < 0 || ix >= this.width || iy >= this.height) return -1;
+    return (iy * this.width) + ix;
+  }
+
+  #maybeExit(lemming) {
+    for (const exit of this.exits) {
+      const exitX = toInteger(exit.x, 0);
+      const exitY = toInteger(exit.y, 0);
+      const radius = Math.max(1, toInteger(exit.radius, 1));
+      if (Math.abs(lemming.x - exitX) <= radius && Math.abs(lemming.y - exitY) <= 2) {
+        lemming.saved = true;
+        lemming.action = 'exiting';
+        return;
+      }
+    }
+  }
+
+  #isInHazard(x, y) {
+    return this.hazards.some(rect => (
+      x >= toInteger(rect.x, 0) &&
+      x < toInteger(rect.x, 0) + Math.max(0, toInteger(rect.width, 0)) &&
+      y >= toInteger(rect.y, 0) &&
+      y < toInteger(rect.y, 0) + Math.max(0, toInteger(rect.height, 0))
+    ));
+  }
+}
+
+class DelegatingRuntimeSolverRunner {
+  constructor(sourceKind, runner, source = {}) {
+    this.kind = sourceKind;
+    this.runner = runner;
+    this.id = String(source.id ?? runner.id ?? sourceKind);
+    this.isRuntimeAuthoritative = source.authoritative !== false &&
+      runner.isRuntimeAuthoritative !== false;
+  }
+
+  get tick() {
+    return toInteger(this.runner.tick ?? this.runner.getFinalStateSummary?.().tick, 0);
+  }
+
+  getSavedCount() {
+    return summaryCount(this.getFinalStateSummary(), 'savedCount', 0);
+  }
+
+  getDeadCount() {
+    return summaryCount(this.getFinalStateSummary(), 'deadCount', 0);
+  }
+
+  getActiveLemmings() {
+    if (typeof this.runner.getActiveLemmings === 'function') return this.runner.getActiveLemmings();
+    return activeFromSummary(this.getFinalStateSummary());
+  }
+
+  getSkillCount(skillType) {
+    if (typeof this.runner.getSkillCount === 'function') return this.runner.getSkillCount(skillType);
+    return summaryCount(this.getFinalStateSummary()?.skills, String(skillType || ''), 0);
+  }
+
+  selectLemming(target) {
+    if (typeof this.runner.selectLemming === 'function') return this.runner.selectLemming(target);
+    return selectLemmingFromList(this.getActiveLemmings(), target);
+  }
+
+  isTerminal() {
+    if (typeof this.runner.isTerminal === 'function') return this.runner.isTerminal();
+    const summary = this.getFinalStateSummary();
+    return summary.activeCount <= 0 && summary.leftCount <= 0;
+  }
+
+  step(count = 1) {
+    return this.runner.step(count);
+  }
+
+  applyAction(action) {
+    return this.runner.applyAction(action);
+  }
+
+  getFinalStateSummary() {
+    return withStateHash({
+      sourceKind: this.kind,
+      id: this.id,
+      ...this.runner.getFinalStateSummary()
+    });
+  }
+}
+
+const selectLemmingFromList = (lemmings, target) => {
+  const active = Array.isArray(lemmings) ? lemmings : [];
+  if (target == null) return active[0] ?? null;
+  if (typeof target === 'number') return active.find(lemming => lemming.id === target) ?? null;
+  if (typeof target === 'string') {
+    if (target === 'first' || target === 'lead' || target === 'frontier') return active[0] ?? null;
+    return active.find(lemming => String(lemming.id) === target) ?? null;
+  }
+  if (typeof target === 'object') {
+    if (target.id != null) {
+      return active.find(lemming => String(lemming.id) === String(target.id)) ?? null;
+    }
+    if (target.index != null) return active[toInteger(target.index, -1)] ?? null;
+    if (target.role === 'frontier') {
+      return [...active].sort((a, b) => b.x - a.x || a.y - b.y || Number(a.id) - Number(b.id))[0] ?? null;
+    }
+    if (target.role === 'crowd' || target.role === 'lead') return active[0] ?? null;
+  }
+  return active[0] ?? null;
+};
+
+class RuntimeGameSolverRunner {
+  constructor(sourceKind, source = {}, options = {}) {
+    this.kind = sourceKind;
+    this.source = source;
+    this.runtime = source.game ?? source.runtime ?? source.adapter ?? source;
+    this.id = String(source.id ?? this.runtime?.id ?? this.runtime?.level?.id ?? sourceKind);
+    this.options = normalizeSolverOptions(options);
+    this.isRuntimeAuthoritative = source.authoritative !== false &&
+      this.runtime?.isRuntimeAuthoritative !== false;
+  }
+
+  get tick() {
+    return toInteger(
+      this.runtime?.tick ??
+        this.runtime?.getTick?.() ??
+        this.getTimer()?.tickIndex ??
+        this.getTimer()?.getGameTicks?.(),
+      0
+    );
+  }
+
+  getTimer() {
+    return this.runtime?.getGameTimer?.() ?? this.runtime?.gameTimer ?? this.source?.timer ?? null;
+  }
+
+  getManager() {
+    return this.runtime?.getLemmingManager?.() ??
+      this.runtime?.lemmingManager ??
+      this.source?.lemmingManager ??
+      null;
+  }
+
+  getSkills() {
+    return this.runtime?.getGameSkills?.() ?? this.runtime?.skills ?? this.source?.skillsRuntime ?? null;
+  }
+
+  getVictory() {
+    return this.runtime?.getVictoryCondition?.() ??
+      this.runtime?.gameVictoryCondition ??
+      this.source?.victory ??
+      null;
+  }
+
+  getActiveLemmings() {
+    const manager = this.getManager();
+    if (typeof manager?.getLemmings === 'function') return manager.getLemmings();
+    if (Array.isArray(manager?.activeLemmings)) return manager.activeLemmings;
+    if (Array.isArray(this.runtime?.lemmings)) return this.runtime.lemmings;
+    return [];
+  }
+
+  getSavedCount() {
+    const victory = this.getVictory();
+    return toInteger(victory?.getSurvivorsCount?.() ?? victory?.survivorCount, 0);
+  }
+
+  getDeadCount() {
+    const summary = this.getFinalStateSummary();
+    return summary.deadCount;
+  }
+
+  getSkillCount(skillType) {
+    const runtimeSkillType = normalizeSkillTypeForRuntime(skillType);
+    const skills = this.getSkills();
+    if (typeof skills?.getSkill === 'function') return toInteger(skills.getSkill(runtimeSkillType), 0);
+    if (typeof skills?.canReuseSkill === 'function') return skills.canReuseSkill(runtimeSkillType) ? 1 : 0;
+    const rawSkills = skills?.skills ?? this.runtime?.level?.skills ?? this.source?.skills ?? {};
+    if (Array.isArray(rawSkills)) return toInteger(rawSkills[runtimeSkillType], 0);
+    return toInteger(rawSkills?.[String(skillType || '').toLowerCase()], 0);
+  }
+
+  selectLemming(target) {
+    const manager = this.getManager();
+    if (target && typeof target === 'object' && target.id != null && typeof manager?.getLemming === 'function') {
+      const byId = manager.getLemming(target.id);
+      if (byId && !byId.removed && !byId.disabled) return byId;
+    }
+    if (typeof target === 'number' && typeof manager?.getLemming === 'function') {
+      const byId = manager.getLemming(target);
+      if (byId && !byId.removed && !byId.disabled) return byId;
+    }
+    return selectLemmingFromList(this.getActiveLemmings(), target);
+  }
+
+  isTerminal() {
+    if (typeof this.runtime?.isTerminal === 'function') return this.runtime.isTerminal();
+    const state = this.runtime?.getGameState?.();
+    if (state != null && state !== GameStateTypes.RUNNING && state !== GameStateTypes.UNKNOWN) return true;
+    const victory = this.getVictory();
+    const left = toInteger(victory?.getLeftCount?.() ?? victory?.leftCount, 0);
+    const out = toInteger(victory?.getOutCount?.() ?? victory?.outCount, this.getActiveLemmings().length);
+    return left <= 0 && out <= 0;
+  }
+
+  step(count = 1) {
+    const safeCount = Math.max(1, toInteger(count, 1));
+    if (typeof this.runtime?.step === 'function' && this.runtime !== this) {
+      return this.runtime.step(safeCount);
+    }
+    const timer = this.getTimer();
+    if (typeof timer?.tick === 'function') {
+      timer.tick(safeCount);
+      return this.getFinalStateSummary();
+    }
+    if (typeof this.runtime?.runGameLogic === 'function') {
+      for (let i = 0; i < safeCount; i += 1) {
+        this.runtime.runGameLogic();
+      }
+      return this.getFinalStateSummary();
+    }
+    return this.getFinalStateSummary();
+  }
+
+  applyAction(action) {
+    const normalized = normalizeActionScriptAction(action);
+    if (typeof this.runtime?.applySolverAction === 'function') {
+      return this.runtime.applySolverAction(normalized);
+    }
+    const lemming = this.selectLemming(normalized.target);
+    if (!lemming) {
+      return {
+        ok: false,
+        detail: `No runtime target lemming for ${normalized.skillType || 'action'}`
+      };
+    }
+    const skillType = normalizeSkillTypeForRuntime(normalized.skillType);
+    const skills = this.getSkills();
+    const manager = this.getManager();
+    if (!manager || !skills || skillType === SkillTypes.UNKNOWN) {
+      return {
+        ok: false,
+        detail: `Runtime cannot apply ${normalized.skillType || 'action'}`
+      };
+    }
+    if (typeof skills.canReuseSkill === 'function' && !skills.canReuseSkill(skillType)) {
+      return {
+        ok: false,
+        detail: `No ${normalized.skillType} skill remains`
+      };
+    }
+    if (!manager.doLemmingAction?.(lemming, skillType)) {
+      return {
+        ok: false,
+        detail: `Runtime rejected ${normalized.skillType} for lemming ${lemming.id}`
+      };
+    }
+    if (typeof skills.reuseSkill === 'function' && !skills.reuseSkill(skillType)) {
+      return {
+        ok: false,
+        detail: `Runtime could not consume ${normalized.skillType}`
+      };
+    }
+    return {
+      ok: true,
+      lemmingId: lemming.id,
+      skillType: normalized.skillType
+    };
+  }
+
+  getFinalStateSummary() {
+    if (typeof this.runtime?.getSolverSummary === 'function') {
+      return withStateHash({
+        sourceKind: this.kind,
+        id: this.id,
+        ...this.runtime.getSolverSummary()
+      });
+    }
+    let snapshot = null;
+    try {
+      snapshot = extractSolverState(this.runtime, {
+        sourceKind: this.kind,
+        id: this.id
+      });
+    } catch {
+      snapshot = null;
+    }
+    const victory = this.getVictory();
+    const active = this.getActiveLemmings();
+    const savedCount = toInteger(victory?.getSurvivorsCount?.() ?? victory?.survivorCount, 0);
+    const releaseCount = toInteger(victory?.getReleaseCount?.() ?? victory?.releaseCount ?? snapshot?.victory.releaseCount, active.length);
+    const leftCount = toInteger(victory?.getLeftCount?.() ?? victory?.leftCount ?? snapshot?.victory.leftCount, 0);
+    const activeCount = toInteger(victory?.getOutCount?.() ?? victory?.outCount, active.length);
+    const lemmings = snapshot?.lemmings ?? active.map((lemming, index) => ({
+      id: lemming?.id ?? index,
+      x: toInteger(lemming?.x, 0),
+      y: toInteger(lemming?.y, 0),
+      lookRight: lemming?.lookRight !== false,
+      action: String(lemming?.action?.getActionName?.() ?? lemming?.action ?? ''),
+      saved: false,
+      dead: !!lemming?.removed,
+      removed: !!lemming?.removed,
+      disabled: !!lemming?.disabled
+    }));
+    const summary = {
+      sourceKind: this.kind,
+      id: this.id,
+      tick: this.tick,
+      width: snapshot?.width ?? this.runtime?.level?.width ?? this.source?.width ?? 0,
+      height: snapshot?.height ?? this.runtime?.level?.height ?? this.source?.height ?? 0,
+      savedCount,
+      deadCount: Math.max(0, releaseCount - leftCount - activeCount - savedCount),
+      activeCount,
+      needCount: toInteger(victory?.getNeedCount?.() ?? victory?.needCount ?? snapshot?.victory.needCount, 1),
+      releaseCount,
+      leftCount,
+      skills: snapshot?.skills?.counts ?? {},
+      lemmings,
+      hashes: snapshot?.hashes ?? null,
+      snapshotHash: snapshot?.snapshotHash ?? null
+    };
+    return withStateHash(summary);
+  }
+}
+
+const createSyntheticRunner = (fixture, options = {}) => {
+  const source = fixture?.fixture?.kind === SYNTHETIC_RUNNER_KIND ? fixture.fixture : fixture;
+  return new SyntheticSolverRunner(source, options);
+};
+
+const createRunnerFromSyntheticFixture = (fixture, options = {}) => ({
+  sourceKind: SYNTHETIC_RUNNER_KIND,
+  runner: createSyntheticRunner(fixture, options),
+  result: null
+});
+
+const createRuntimeSourceRunner = (sourceKind, source, options = {}, missingDetail) => {
+  const facade = source?.runner ?? source?.runtime ?? source?.game ?? source?.adapter ?? null;
+  if (hasRunnerAdapterShape(facade)) {
+    return {
+      sourceKind,
+      runner: new DelegatingRuntimeSolverRunner(sourceKind, facade, source),
+      result: null
+    };
+  }
+  if (facade || source?.getGameTimer || source?.getLemmingManager) {
+    return {
+      sourceKind,
+      runner: new RuntimeGameSolverRunner(sourceKind, source, options),
+      result: null
+    };
+  }
+  return createUnsupportedRunnerResult(sourceKind, missingDetail);
+};
+
+const createEditorLevelRunner = (source, options = {}) => createRuntimeSourceRunner(
+  'editor',
+  source,
+  options,
+  'Editor level sources require an initialized editor playtest runtime or runner adapter'
+);
+
+const createProcgenChunkRunner = (source, options = {}) => createRuntimeSourceRunner(
+  'procgen',
+  source,
+  options,
+  'Procgen chunks require an initialized procgen runtime or runner adapter'
+);
+
+const createBuiltInLevelRunner = (source, options = {}) => createRuntimeSourceRunner(
+  'builtin',
+  source,
+  options,
+  'Built-in level descriptors require an initialized game runtime or runner adapter'
+);
+
+const createRunnerFromSource = (source, options = {}) => {
+  const kind = getSourceKind(source);
+  if (kind === SYNTHETIC_RUNNER_KIND) {
+    return createRunnerFromSyntheticFixture(source?.fixture ?? source, options);
+  }
+  if (kind === 'editor') return createEditorLevelRunner(source, options);
+  if (kind === 'procgen') return createProcgenChunkRunner(source, options);
+  if (kind === 'builtin') return createBuiltInLevelRunner(source, options);
+  return createUnsupportedRunnerResult('unknown', 'Unknown solver runner source');
+};
+
+const isRunnerAdapter = value => hasRunnerAdapterShape(value);
+
+const resolveRunner = (runnerOrSource, options) => {
+  if (isRunnerAdapter(runnerOrSource)) {
+    return { sourceKind: runnerOrSource.kind || 'adapter', runner: runnerOrSource, result: null };
+  }
+  if (runnerOrSource?.result) return runnerOrSource;
+  if (runnerOrSource?.runner && typeof runnerOrSource.sourceKind === 'string') return runnerOrSource;
+  return createRunnerFromSource(runnerOrSource, options);
+};
+
+const getActionBounds = action => {
+  if (action.tick != null) return { start: action.tick, end: action.tick, exact: true };
+  if (action.window) {
+    return {
+      start: Math.min(action.window.start, action.window.end),
+      end: Math.max(action.window.start, action.window.end),
+      exact: false
+    };
+  }
+  return { start: 0, end: 0, exact: true };
+};
+
+const prepareActionQueue = actions => actions
+  .map((action, index) => {
+    const normalized = normalizeActionScriptAction(action);
+    return {
+      action: normalized,
+      index,
+      ...getActionBounds(normalized)
+    };
+  })
+  .sort((left, right) => left.start - right.start || left.index - right.index);
+
+const toConditionCount = (condition, fallback) => Math.max(0, toInteger(
+  condition.count ?? condition.value ?? condition.min,
+  fallback
+));
+
+const conditionDetail = condition => {
+  if (typeof condition === 'string') return condition;
+  return JSON.stringify(condition);
+};
+
+const checkCondition = (condition, runner, action = null) => {
+  const summary = runner.getFinalStateSummary();
+  if (typeof condition === 'string') {
+    if (condition === 'target-active') {
+      const target = runner.selectLemming(action?.target);
+      return {
+        ok: Boolean(target && !target.saved && !target.dead),
+        detail: condition
+      };
+    }
+    if (condition === 'saved') {
+      return { ok: summary.savedCount > 0, detail: condition };
+    }
+    return { ok: false, detail: `Unknown replay condition: ${condition}` };
+  }
+  if (condition == null || typeof condition !== 'object') {
+    return { ok: false, detail: 'Invalid replay condition' };
+  }
+
+  const type = String(condition.type ?? condition.kind ?? condition.code ?? '').trim();
+  const lemming = condition.id == null
+    ? runner.selectLemming(action?.target)
+    : summary.lemmings.find(item => String(item.id) === String(condition.id));
+
+  if (type === 'savedCountAtLeast') {
+    return {
+      ok: summary.savedCount >= toConditionCount(condition, 1),
+      detail: conditionDetail(condition)
+    };
+  }
+  if (type === 'deadCountAtMost') {
+    return {
+      ok: summary.deadCount <= toConditionCount(condition, 0),
+      detail: conditionDetail(condition)
+    };
+  }
+  if (type === 'activeCountAtLeast') {
+    return {
+      ok: summary.activeCount >= toConditionCount(condition, 1),
+      detail: conditionDetail(condition)
+    };
+  }
+  if (type === 'lemmingSaved') {
+    return {
+      ok: Boolean(lemming?.saved),
+      detail: conditionDetail(condition)
+    };
+  }
+  if (type === 'lemmingAlive') {
+    return {
+      ok: Boolean(lemming && !lemming.dead),
+      detail: conditionDetail(condition)
+    };
+  }
+  if (type === 'lemmingXAtLeast') {
+    return {
+      ok: Boolean(lemming && lemming.x >= toInteger(condition.x, 0)),
+      detail: conditionDetail(condition)
+    };
+  }
+  if (type === 'lemmingXAtMost') {
+    return {
+      ok: Boolean(lemming && lemming.x <= toInteger(condition.x, 0)),
+      detail: conditionDetail(condition)
+    };
+  }
+  if (type === 'skillAvailable' || type === 'skillRemainingAtLeast') {
+    const skillType = String(condition.skillType ?? condition.skill ?? '').trim();
+    return {
+      ok: runner.getSkillCount(skillType) >= toConditionCount(condition, 1),
+      detail: conditionDetail(condition)
+    };
+  }
+  if (type === 'tickAtLeast') {
+    return {
+      ok: summary.tick >= toConditionCount(condition, 0),
+      detail: conditionDetail(condition)
+    };
+  }
+  if (type === 'tickAtMost') {
+    return {
+      ok: summary.tick <= toConditionCount(condition, 0),
+      detail: conditionDetail(condition)
+    };
+  }
+  if (type === 'stateHash') {
+    return {
+      ok: summary.stateHash === String(condition.value ?? ''),
+      detail: conditionDetail(condition)
+    };
+  }
+  return { ok: false, detail: `Unknown replay condition: ${conditionDetail(condition)}` };
+};
+
+const firstFailedCondition = (conditions, runner, action = null) => {
+  for (const condition of conditions) {
+    const checked = checkCondition(condition, runner, action);
+    if (!checked.ok) return checked;
+  }
+  return null;
+};
+
+const createReplayResult = ({
+  resultType,
+  summary,
+  actions,
+  explanations = [],
+  budgetUsage,
+  runner,
+  appliedActions
+}) => {
+  const replaySummary = {
+    ...runner.getFinalStateSummary(),
+    appliedActions: appliedActions.map(item => ({ ...item }))
+  };
+  return createSolverResult({
+    resultType,
+    summary,
+    actions,
+    explanations,
+    budgetUsage,
+    replaySummary
+  });
+};
+
+const createReplayFailure = ({
+  summary,
+  detail,
+  actions,
+  budgetUsage,
+  runner,
+  appliedActions,
+  code = SOLVER_EXPLANATION_CODES.REPLAY_DIVERGED
+}) => createReplayResult({
+  resultType: SOLVER_RESULT_TYPES.FAILED,
+  summary,
+  actions,
+  explanations: [{ code, detail }],
+  budgetUsage,
+  runner,
+  appliedActions
+});
+
+const verifyActionReplay = (runnerOrSource, actions = [], options = {}) => {
+  const normalizedOptions = normalizeSolverOptions(options);
+  const created = resolveRunner(runnerOrSource, normalizedOptions);
+  if (created.result) return created.result;
+
+  const runner = created.runner;
+  const actionQueue = prepareActionQueue(actions);
+  const appliedActions = [];
+  const budgetUsage = {
+    ticks: 0,
+    nodes: 0,
+    actions: 0,
+    wallTimeMs: 0
+  };
+  const targetSaveCount = Math.max(0, toInteger(options.targetSaveCount, runner.needCount || 1));
+  let nextActionIndex = 0;
+
+  const timeout = () => createReplayResult({
+    resultType: SOLVER_RESULT_TYPES.TIMEOUT,
+    summary: `Replay budget exhausted at tick ${budgetUsage.ticks}`,
+    actions,
+    explanations: [SOLVER_EXPLANATION_CODES.BUDGET_EXHAUSTED],
+    budgetUsage,
+    runner,
+    appliedActions
+  });
+
+  const checkFinalPostconditions = () => {
+    for (const item of actionQueue) {
+      const failed = firstFailedCondition(item.action.expectedPostconditions, runner, item.action);
+      if (failed) {
+        return createReplayFailure({
+          summary: `Replay diverged after ${budgetUsage.ticks} ticks`,
+          detail: failed.detail,
+          actions,
+          budgetUsage,
+          runner,
+          appliedActions
+        });
+      }
+    }
+    return null;
+  };
+
+  while (true) {
+    while (nextActionIndex < actionQueue.length) {
+      const item = actionQueue[nextActionIndex];
+      if (runner.tick < item.start) break;
+      if (runner.tick > item.end) {
+        return createReplayFailure({
+          summary: `Replay missed action ${item.index} at tick ${runner.tick}`,
+          detail: `Action window ${item.start}-${item.end} expired`,
+          actions,
+          budgetUsage,
+          runner,
+          appliedActions,
+          code: SOLVER_EXPLANATION_CODES.TIMING_WINDOW_TOO_NARROW
+        });
+      }
+
+      const failedPrecondition = firstFailedCondition(
+        item.action.preconditions,
+        runner,
+        item.action
+      );
+      if (failedPrecondition) {
+        if (!item.exact && runner.tick < item.end) break;
+        return createReplayFailure({
+          summary: `Replay precondition failed at tick ${runner.tick}`,
+          detail: failedPrecondition.detail,
+          actions,
+          budgetUsage,
+          runner,
+          appliedActions
+        });
+      }
+
+      budgetUsage.actions += 1;
+      if (budgetUsage.actions > normalizedOptions.maxActions) return timeout();
+      const applied = runner.applyAction(item.action);
+      if (!applied.ok) {
+        return createReplayFailure({
+          summary: `Replay action failed at tick ${runner.tick}`,
+          detail: applied.detail,
+          actions,
+          budgetUsage,
+          runner,
+          appliedActions
+        });
+      }
+      appliedActions.push({
+        index: item.index,
+        tick: runner.tick,
+        skillType: item.action.skillType,
+        target: item.action.target,
+        lemmingId: applied.lemmingId
+      });
+      nextActionIndex += 1;
+    }
+
+    if (runner.getSavedCount() >= targetSaveCount) {
+      const postconditionFailure = checkFinalPostconditions();
+      if (postconditionFailure) return postconditionFailure;
+      if (created.sourceKind !== SYNTHETIC_RUNNER_KIND && runner.isRuntimeAuthoritative === false) {
+        return createReplayResult({
+          resultType: SOLVER_RESULT_TYPES.UNKNOWN,
+          summary: `${created.sourceKind} replay reached the save target without an authoritative runtime adapter`,
+          actions,
+          explanations: [{
+            code: SOLVER_EXPLANATION_CODES.MISSING_RUNTIME_ADAPTER,
+            detail: 'Non-synthetic solved results require authoritative runtime replay.'
+          }],
+          budgetUsage,
+          runner,
+          appliedActions
+        });
+      }
+      return createReplayResult({
+        resultType: SOLVER_RESULT_TYPES.SOLVED,
+        summary: `Replay solved ${runner.kind || 'runner'} ${runner.id || ''} in ${budgetUsage.ticks} ticks`.trim(),
+        actions,
+        budgetUsage,
+        runner,
+        appliedActions
+      });
+    }
+
+    if (runner.isTerminal()) {
+      return createReplayFailure({
+        summary: `Replay failed to save ${targetSaveCount} lemming(s)`,
+        detail: `Saved ${runner.getSavedCount()} of ${targetSaveCount}`,
+        actions,
+        budgetUsage,
+        runner,
+        appliedActions,
+        code: SOLVER_EXPLANATION_CODES.SAVE_COUNT_UNREACHABLE
+      });
+    }
+
+    if (
+      budgetUsage.ticks >= normalizedOptions.maxTicks ||
+      budgetUsage.nodes >= normalizedOptions.maxNodes
+    ) {
+      return timeout();
+    }
+
+    runner.step();
+    budgetUsage.ticks += 1;
+    budgetUsage.nodes += 1;
+  }
+};
+
+export {
+  DelegatingRuntimeSolverRunner,
+  RuntimeGameSolverRunner,
+  SyntheticSolverRunner,
+  createBuiltInLevelRunner,
+  createEditorLevelRunner,
+  createProcgenChunkRunner,
+  createRunnerFromSource,
+  createRunnerFromSyntheticFixture,
+  createSyntheticRunner,
+  verifyActionReplay
+};
diff --git a/js/solver/SolverState.js b/js/solver/SolverState.js
new file mode 100644
index 00000000..6b55c06d
--- /dev/null
+++ b/js/solver/SolverState.js
@@ -0,0 +1,654 @@
+import { SkillTypes } from '../game/SkillTypes.js';
+import { TriggerTypes } from '../level/TriggerTypes.js';
+
+const HASH_OFFSET_A = 0x811c9dc5;
+const HASH_OFFSET_B = 0x9e3779b9;
+const HASH_PRIME = 0x01000193;
+
+const SKILL_NAMES_BY_TYPE = Object.freeze({
+  [SkillTypes.CLIMBER]: 'climber',
+  [SkillTypes.FLOATER]: 'floater',
+  [SkillTypes.BOMBER]: 'bomber',
+  [SkillTypes.BLOCKER]: 'blocker',
+  [SkillTypes.BUILDER]: 'builder',
+  [SkillTypes.BASHER]: 'basher',
+  [SkillTypes.MINER]: 'miner',
+  [SkillTypes.DIGGER]: 'digger'
+});
+
+const HAZARD_TRIGGER_TYPES = new Set([
+  TriggerTypes.UNKNOWN_2,
+  TriggerTypes.UNKNOWN_3,
+  TriggerTypes.TRAP,
+  TriggerTypes.DROWN,
+  TriggerTypes.KILL,
+  TriggerTypes.FRYING
+]);
+
+const TRIGGER_NAMES_BY_TYPE = Object.freeze({
+  [TriggerTypes.EXIT_LEVEL]: 'exit',
+  [TriggerTypes.TRAP]: 'trap',
+  [TriggerTypes.DROWN]: 'drown',
+  [TriggerTypes.KILL]: 'kill',
+  [TriggerTypes.ONEWAY_LEFT]: 'oneway-left',
+  [TriggerTypes.ONEWAY_RIGHT]: 'oneway-right',
+  [TriggerTypes.FRYING]: 'frying'
+});
+
+const isPlainObject = value => (
+  value != null &&
+  typeof value === 'object' &&
+  (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)
+);
+
+const toInteger = (value, fallback = 0) => {
+  const number = Number(value);
+  if (!Number.isFinite(number)) return fallback;
+  return Math.trunc(number);
+};
+
+const toNonNegativeInteger = (value, fallback = 0) => Math.max(0, toInteger(value, fallback));
+
+const hasOwn = (source, key) => Object.prototype.hasOwnProperty.call(source, key);
+
+const hex32 = value => (value >>> 0).toString(16).padStart(8, '0');
+
+const mixHashByte = (state, byte) => {
+  state.a ^= byte & 0xff;
+  state.a = Math.imul(state.a, HASH_PRIME) >>> 0;
+  state.b ^= (byte + state.a) & 0xff;
+  state.b = Math.imul(state.b, HASH_PRIME) >>> 0;
+};
+
+const mixHashString = (state, text) => {
+  const value = String(text);
+  for (let i = 0; i < value.length; i += 1) {
+    const code = value.charCodeAt(i);
+    mixHashByte(state, code & 0xff);
+    mixHashByte(state, (code >>> 8) & 0xff);
+  }
+};
+
+const createHashState = () => ({ a: HASH_OFFSET_A, b: HASH_OFFSET_B });
+
+const finishHashState = state => `${hex32(state.a)}${hex32(state.b)}`;
+
+const stableJsonValue = (value, seen = new Set()) => {
+  if (value == null) return value;
+  if (typeof value === 'number') return Number.isFinite(value) ? value : String(value);
+  if (typeof value === 'string' || typeof value === 'boolean') return value;
+  if (ArrayBuffer.isView(value)) {
+    return Array.from(value);
+  }
+  if (value instanceof ArrayBuffer) {
+    return Array.from(new Uint8Array(value));
+  }
+  if (Array.isArray(value)) {
+    return value.map(item => stableJsonValue(item, seen));
+  }
+  if (typeof value !== 'object') return String(value);
+  if (seen.has(value)) return '[Circular]';
+  seen.add(value);
+  const out = {};
+  const keys = Object.keys(value).sort();
+  for (const key of keys) {
+    const next = value[key];
+    if (typeof next === 'undefined' || typeof next === 'function') continue;
+    out[key] = stableJsonValue(next, seen);
+  }
+  seen.delete(value);
+  return out;
+};
+
+const stableStringify = value => JSON.stringify(stableJsonValue(value));
+
+const stableHash = value => {
+  const state = createHashState();
+  mixHashString(state, stableStringify(value));
+  return finishHashState(state);
+};
+
+const cloneMaskBytes = (value, width, height, sampler = null) => {
+  const length = Math.max(0, width * height);
+  if (value instanceof Uint8Array) {
+    const out = new Uint8Array(length);
+    out.set(value.subarray(0, Math.min(length, value.length)));
+    return out;
+  }
+  if (ArrayBuffer.isView(value)) {
+    const out = new Uint8Array(length);
+    const source = new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+    out.set(source.subarray(0, Math.min(length, source.length)));
+    return out;
+  }
+  if (Array.isArray(value)) {
+    const out = new Uint8Array(length);
+    for (let i = 0; i < Math.min(length, value.length); i += 1) {
+      out[i] = value[i] ? 1 : 0;
+    }
+    return out;
+  }
+  const out = new Uint8Array(length);
+  if (typeof sampler !== 'function') return out;
+  for (let y = 0; y < height; y += 1) {
+    const row = y * width;
+    for (let x = 0; x < width; x += 1) {
+      out[row + x] = sampler(x, y) ? 1 : 0;
+    }
+  }
+  return out;
+};
+
+const readLayerObject = (source, keys) => {
+  for (const key of keys) {
+    const value = source?.[key];
+    if (value) return value;
+  }
+  return null;
+};
+
+const readGroundLayer = source => {
+  if (typeof source?.getGroundMaskLayer === 'function') return source.getGroundMaskLayer();
+  return readLayerObject(source, ['groundMask', 'terrainMask', 'mask']);
+};
+
+const readSteelLayer = source => readLayerObject(source, ['steelMask', 'steelLayer']);
+
+const normalizeMask = (source, width, height, {
+  layer = null,
+  samplerName = null
+} = {}) => {
+  const resolvedLayer = layer || source;
+  const maskValue = resolvedLayer?.mask ?? resolvedLayer;
+  const sampler = samplerName && typeof source?.[samplerName] === 'function'
+    ? (x, y) => source[samplerName](x, y)
+    : null;
+  return cloneMaskBytes(maskValue, width, height, sampler);
+};
+
+const hashMask = (mask, width, height, salt = '') => {
+  const state = createHashState();
+  mixHashString(state, `${salt}:${width}x${height}:`);
+  for (let i = 0; i < mask.length; i += 1) {
+    mixHashByte(state, mask[i] ? 1 : 0);
+  }
+  return finishHashState(state);
+};
+
+const countMask = mask => {
+  let count = 0;
+  for (let i = 0; i < mask.length; i += 1) {
+    if (mask[i]) count += 1;
+  }
+  return count;
+};
+
+const normalizeRectSize = (rect, axis) => {
+  const sizeKey = axis === 'x' ? 'width' : 'height';
+  const altSizeKey = axis === 'x' ? 'w' : 'h';
+  const endKey = axis === 'x' ? 'x2' : 'y2';
+  const startKey = axis === 'x' ? 'x1' : 'y1';
+  const pointKey = axis === 'x' ? 'x' : 'y';
+  const altPointKey = axis === 'x' ? 'left' : 'top';
+  if (rect[sizeKey] != null || rect[altSizeKey] != null) {
+    return toNonNegativeInteger(rect[sizeKey] ?? rect[altSizeKey], 0);
+  }
+  if (Number.isFinite(Number(rect[endKey]))) {
+    return toNonNegativeInteger(Number(rect[endKey]) - Number(rect[startKey] ?? rect[pointKey] ?? 0), 0);
+  }
+  if (rect[pointKey] != null || rect[altPointKey] != null || rect[startKey] != null) return 1;
+  return 0;
+};
+
+const normalizeRect = (rect = {}, index = 0) => ({
+  index: toNonNegativeInteger(rect.index, index),
+  x: toInteger(rect.x ?? rect.left ?? rect.x1, 0),
+  y: toInteger(rect.y ?? rect.top ?? rect.y1, 0),
+  width: normalizeRectSize(rect, 'x'),
+  height: normalizeRectSize(rect, 'y')
+});
+
+const normalizeRectList = (items = []) => {
+  if (!Array.isArray(items)) return [];
+  return items.map((item, index) => normalizeRect(item, index))
+    .sort((a, b) => a.y - b.y || a.x - b.x || a.width - b.width || a.height - b.height);
+};
+
+const normalizeRanges = (ranges, stride, hasDirection = false) => {
+  if (!ranges || typeof ranges.length !== 'number') return [];
+  const out = [];
+  for (let i = 0, index = 0; i + stride - 1 < ranges.length; i += stride, index += 1) {
+    const rect = {
+      index,
+      x: ranges[i],
+      y: ranges[i + 1],
+      width: ranges[i + 2],
+      height: ranges[i + 3]
+    };
+    if (hasDirection) rect.direction = ranges[i + 4];
+    out.push(rect);
+  }
+  return out;
+};
+
+const readMaskComponentRects = (mask, width, height) => {
+  const visited = new Uint8Array(mask.length);
+  const queueX = [];
+  const queueY = [];
+  const rects = [];
+  for (let y = 0; y < height; y += 1) {
+    const row = y * width;
+    for (let x = 0; x < width; x += 1) {
+      const offset = row + x;
+      if (!mask[offset] || visited[offset]) continue;
+      let minX = x;
+      let maxX = x;
+      let minY = y;
+      let maxY = y;
+      visited[offset] = 1;
+      queueX.length = 0;
+      queueY.length = 0;
+      queueX.push(x);
+      queueY.push(y);
+      for (let read = 0; read < queueX.length; read += 1) {
+        const cx = queueX[read];
+        const cy = queueY[read];
+        if (cx < minX) minX = cx;
+        if (cx > maxX) maxX = cx;
+        if (cy < minY) minY = cy;
+        if (cy > maxY) maxY = cy;
+        const neighbors = [
+          [cx - 1, cy],
+          [cx + 1, cy],
+          [cx, cy - 1],
+          [cx, cy + 1]
+        ];
+        for (const [nx, ny] of neighbors) {
+          if (nx < 0 || nx >= width || ny < 0 || ny >= height) continue;
+          const nextOffset = ny * width + nx;
+          if (!mask[nextOffset] || visited[nextOffset]) continue;
+          visited[nextOffset] = 1;
+          queueX.push(nx);
+          queueY.push(ny);
+        }
+      }
+      rects.push({
+        index: rects.length,
+        x: minX,
+        y: minY,
+        width: (maxX - minX) + 1,
+        height: (maxY - minY) + 1
+      });
+    }
+  }
+  return rects;
+};
+
+const normalizeSteelConstraints = (source, steelMask, width, height) => {
+  const explicit = normalizeRectList(source?.steel ?? source?.steelAreas ?? []);
+  const ranges = normalizeRanges(source?.steelRanges, 4, false);
+  const rects = explicit.length ? explicit : ranges;
+  const constraints = rects.length ? rects : readMaskComponentRects(steelMask, width, height);
+  return constraints.map((rect, index) => ({ ...normalizeRect(rect, index), type: 'steel' }));
+};
+
+const normalizeOneWayDirection = value => {
+  if (value === 'left' || value === 'right') return value;
+  const number = Number(value);
+  if (Number.isFinite(number)) return number === 1 ? 'right' : 'left';
+  return 'unknown';
+};
+
+const normalizeOneWayConstraints = source => {
+  const explicit = Array.isArray(source?.oneWay) ? source.oneWay : [];
+  const fromRanges = normalizeRanges(source?.arrowRanges, 5, true);
+  const fromTriggers = Array.isArray(source?.triggers)
+    ? source.triggers
+      .filter(trigger => trigger?.type === TriggerTypes.ONEWAY_LEFT || trigger?.type === TriggerTypes.ONEWAY_RIGHT)
+      .map(trigger => ({
+        x: trigger.x1,
+        y: trigger.y1,
+        width: trigger.x2 - trigger.x1,
+        height: trigger.y2 - trigger.y1,
+        direction: trigger.type === TriggerTypes.ONEWAY_RIGHT ? 'right' : 'left'
+      }))
+    : [];
+  return [...explicit, ...fromRanges, ...fromTriggers]
+    .map((item, index) => ({
+      ...normalizeRect(item, index),
+      direction: normalizeOneWayDirection(item.direction),
+      type: 'one-way'
+    }))
+    .sort((a, b) => a.y - b.y || a.x - b.x || a.direction.localeCompare(b.direction));
+};
+
+const normalizeEntrance = (item, index) => ({
+  ...normalizeRect(item, index),
+  opened: !!item?._opened,
+  type: 'entrance'
+});
+
+const normalizeEntrances = source => normalizeRectList(source?.entrances ?? [])
+  .map((item, index) => normalizeEntrance(item, index));
+
+const triggerToRect = (trigger, index) => ({
+  index,
+  x: toInteger(trigger?.x1, 0),
+  y: toInteger(trigger?.y1, 0),
+  width: toNonNegativeInteger((trigger?.x2 ?? 0) - (trigger?.x1 ?? 0), 0),
+  height: toNonNegativeInteger((trigger?.y2 ?? 0) - (trigger?.y1 ?? 0), 0),
+  triggerType: toInteger(trigger?.type, 0),
+  kind: TRIGGER_NAMES_BY_TYPE[trigger?.type] || `trigger-${trigger?.type ?? 0}`
+});
+
+const normalizeExits = source => {
+  const explicit = Array.isArray(source?.exits)
+    ? source.exits
+      .map((item, index) => ({
+        ...normalizeRect(item, index),
+        type: 'exit',
+        kind: item.kind || item.type || 'exit'
+      }))
+    : [];
+  const triggerExits = Array.isArray(source?.triggers)
+    ? source.triggers
+      .filter(trigger => trigger?.type === TriggerTypes.EXIT_LEVEL)
+      .map((trigger, index) => ({ ...triggerToRect(trigger, index), type: 'exit' }))
+    : [];
+  return [...explicit, ...triggerExits]
+    .sort((a, b) => a.y - b.y || a.x - b.x || a.width - b.width);
+};
+
+const normalizeHazards = source => {
+  const explicit = Array.isArray(source?.hazards)
+    ? source.hazards.map((item, index) => ({
+      ...normalizeRect(item, index),
+      type: 'hazard',
+      kind: item.kind || item.type || 'hazard'
+    }))
+    : [];
+  const triggerHazards = Array.isArray(source?.triggers)
+    ? source.triggers
+      .filter(trigger => HAZARD_TRIGGER_TYPES.has(trigger?.type))
+      .map((trigger, index) => ({ ...triggerToRect(trigger, index), type: 'hazard' }))
+    : [];
+  return [...explicit, ...triggerHazards]
+    .sort((a, b) => a.y - b.y || a.x - b.x || String(a.kind).localeCompare(String(b.kind)));
+};
+
+const normalizeMutationRecord = (item, index, fallbackKind) => ({
+  ...normalizeRect(item, index),
+  kind: String(item?.kind ?? item?.type ?? fallbackKind),
+  skillType: item?.skillType == null ? null : String(item.skillType),
+  direction: item?.direction == null ? null : normalizeOneWayDirection(item.direction),
+  tick: item?.tick == null ? null : toNonNegativeInteger(item.tick, 0),
+  source: item?.source == null ? null : String(item.source)
+});
+
+const normalizeMutationRecords = source => {
+  const groups = [
+    ['terrainMutations', 'mutation'],
+    ['mutations', 'mutation'],
+    ['builderStairs', 'builder-stair'],
+    ['digShafts', 'dig-shaft'],
+    ['bashTunnels', 'bash-tunnel'],
+    ['mineTunnels', 'mine-tunnel']
+  ];
+  const out = [];
+  for (const [key, fallbackKind] of groups) {
+    const records = Array.isArray(source?.[key]) ? source[key] : [];
+    for (const record of records) {
+      out.push(normalizeMutationRecord(record, out.length, fallbackKind));
+    }
+  }
+  return out.sort((a, b) => (
+    a.y - b.y ||
+    a.x - b.x ||
+    a.width - b.width ||
+    String(a.kind).localeCompare(String(b.kind)) ||
+    a.index - b.index
+  ));
+};
+
+const readGameFacade = input => {
+  if (!input) return null;
+  if (input.level || typeof input.getGameTimer === 'function' || typeof input.getLemmingManager === 'function') {
+    return input;
+  }
+  if (input.game) return input.game;
+  return null;
+};
+
+const resolveLevelSource = input => {
+  const game = readGameFacade(input);
+  if (game?.level) return game.level;
+  if (input?.level) return input.level;
+  return input;
+};
+
+const readLemmingCollection = input => {
+  const game = readGameFacade(input);
+  const manager = game?.getLemmingManager?.() ?? game?.lemmingManager ?? input?.lemmingManager;
+  if (typeof manager?.getLemmings === 'function') return manager.getLemmings();
+  if (Array.isArray(manager?.activeLemmings)) return manager.activeLemmings;
+  if (Array.isArray(input?.lemmings)) return input.lemmings;
+  if (Array.isArray(resolveLevelSource(input)?.lemmings)) return resolveLevelSource(input).lemmings;
+  return [];
+};
+
+const normalizeActionName = action => {
+  if (action == null) return null;
+  if (typeof action === 'string' || typeof action === 'number') return action;
+  if (typeof action.getActionName === 'function') return action.getActionName();
+  if (action.constructor?.name) return action.constructor.name;
+  return String(action);
+};
+
+const normalizeLemming = (lemming, index) => ({
+  id: lemming?.id ?? index,
+  x: toInteger(lemming?.x, 0),
+  y: toInteger(lemming?.y, 0),
+  lookRight: lemming?.lookRight !== false,
+  direction: lemming?.lookRight === false ? 'left' : 'right',
+  action: normalizeActionName(lemming?.action),
+  state: normalizeActionName(lemming?.state),
+  removed: !!(lemming?.removed || lemming?.isRemoved?.()),
+  disabled: !!(lemming?.disabled || lemming?.isDisabled?.()),
+  countdown: toNonNegativeInteger(lemming?.countdown, 0),
+  canClimb: !!lemming?.canClimb,
+  hasParachute: !!lemming?.hasParachute
+});
+
+const normalizeLemmings = input => readLemmingCollection(input)
+  .filter(Boolean)
+  .map((lemming, index) => normalizeLemming(lemming, index))
+  .sort((a, b) => Number(a.id) - Number(b.id) || a.y - b.y || a.x - b.x);
+
+const normalizeSkillMap = skills => {
+  const out = {};
+  for (const name of Object.values(SKILL_NAMES_BY_TYPE)) out[name] = 0;
+  if (Array.isArray(skills)) {
+    for (const [typeText, name] of Object.entries(SKILL_NAMES_BY_TYPE)) {
+      out[name] = toNonNegativeInteger(skills[Number(typeText)], 0);
+    }
+    return out;
+  }
+  if (isPlainObject(skills)) {
+    const keys = Object.keys(skills).sort();
+    for (const key of keys) {
+      const normalized = key.toLowerCase();
+      out[normalized] = toNonNegativeInteger(skills[key], 0);
+    }
+  }
+  return out;
+};
+
+const normalizeSkills = input => {
+  const game = readGameFacade(input);
+  const level = resolveLevelSource(input);
+  const gameSkills = game?.getGameSkills?.() ?? game?.skills ?? null;
+  const sourceSkills = gameSkills?.skills ?? level?.skills ?? input?.skills ?? {};
+  const counts = normalizeSkillMap(sourceSkills);
+  return {
+    counts,
+    selectedSkill: gameSkills?.selectedSkill ?? null,
+    selectedSkillName: SKILL_NAMES_BY_TYPE[gameSkills?.selectedSkill] ?? null,
+    cheatMode: !!gameSkills?.cheatMode
+  };
+};
+
+const normalizeTimer = input => {
+  const game = readGameFacade(input);
+  const level = resolveLevelSource(input);
+  const timer = input?.timer ?? game?.getGameTimer?.() ?? game?.gameTimer ?? null;
+  const tick = timer?.tick ?? timer?.tickIndex ?? timer?.getGameTicks?.() ?? input?.tick ?? 0;
+  return {
+    tick: toNonNegativeInteger(tick, 0),
+    seconds: Number.isFinite(Number(timer?.getGameTime?.())) ? Number(timer.getGameTime()) : null,
+    timeLimit: toNonNegativeInteger(timer?.timeLimit ?? level?.timeLimit ?? input?.timeLimit, 0),
+    timeLeft: Number.isFinite(Number(timer?.getGameLeftTime?.())) ? Number(timer.getGameLeftTime()) : null
+  };
+};
+
+const normalizeVictory = input => {
+  const game = readGameFacade(input);
+  const level = resolveLevelSource(input);
+  const victory = input?.victory ?? game?.getVictoryCondition?.() ?? game?.gameVictoryCondition ?? null;
+  const needCount = victory?.getNeedCount?.() ?? victory?.needCount ?? level?.needCount ?? input?.needCount ?? 0;
+  const releaseCount = victory?.getReleaseCount?.() ?? victory?.releaseCount ?? level?.releaseCount ?? input?.releaseCount ?? 0;
+  const survivors = victory?.getSurvivorsCount?.() ?? victory?.survivorCount ?? input?.survivorsCount ?? 0;
+  const left = victory?.getLeftCount?.() ?? victory?.leftCount ?? input?.leftCount ?? releaseCount;
+  const out = victory?.getOutCount?.() ?? victory?.outCount ?? input?.outCount ?? 0;
+  return {
+    needCount: toNonNegativeInteger(needCount, 0),
+    releaseCount: toNonNegativeInteger(releaseCount, 0),
+    survivorsCount: toNonNegativeInteger(survivors, 0),
+    leftCount: toNonNegativeInteger(left, 0),
+    outCount: toNonNegativeInteger(out, 0),
+    gameState: game?.getGameState?.() ?? game?.finalGameState ?? null
+  };
+};
+
+const publicSnapshotForHash = snapshot => ({
+  kind: snapshot.kind,
+  sourceKind: snapshot.sourceKind,
+  id: snapshot.id,
+  width: snapshot.width,
+  height: snapshot.height,
+  terrainHash: snapshot.terrainHash,
+  terrainMutationHash: snapshot.terrainMutationHash,
+  steel: {
+    hash: snapshot.steel.hash,
+    solidCount: snapshot.steel.solidCount,
+    constraints: snapshot.steel.constraints
+  },
+  oneWay: snapshot.oneWay,
+  entrances: snapshot.entrances,
+  exits: snapshot.exits,
+  hazards: snapshot.hazards,
+  lemmings: snapshot.lemmings,
+  terrainMutations: snapshot.terrainMutations,
+  skills: snapshot.skills,
+  timer: snapshot.timer,
+  victory: snapshot.victory
+});
+
+const extractSolverState = (input, options = {}) => {
+  const source = resolveLevelSource(input);
+  if (!source) {
+    throw new Error('extractSolverState requires a synthetic fixture, Level-like object, or Game-like object.');
+  }
+  const width = Math.max(1, toInteger(options.width ?? source.width, 1));
+  const height = Math.max(1, toInteger(options.height ?? source.height, 1));
+  const groundLayer = readGroundLayer(source);
+  const groundMask = normalizeMask(source, width, height, {
+    layer: groundLayer,
+    samplerName: 'hasGroundAt'
+  });
+  const baseGroundLayer = source.baseGroundMask ?? source.originalGroundMask ?? source.terrainMask ?? groundLayer;
+  const baseGroundMask = normalizeMask(source, width, height, {
+    layer: baseGroundLayer,
+    samplerName: 'hasGroundAt'
+  });
+  const steelLayer = readSteelLayer(source);
+  const steelMask = normalizeMask(source, width, height, {
+    layer: steelLayer,
+    samplerName: 'isSteelAt'
+  });
+  const terrainHash = source.terrainHash ?? hashMask(baseGroundMask, width, height, 'terrain');
+  const terrainMutations = normalizeMutationRecords(source);
+  const terrainMutationMaskHash = hashMask(groundMask, width, height, 'terrain-mutation');
+  const terrainMutationHash = source.terrainMutationHash ??
+    source.groundMutationHash ??
+    stableHash({
+      maskHash: terrainMutationMaskHash,
+      mutations: terrainMutations
+    });
+  const steelHash = source.steelHash ?? hashMask(steelMask, width, height, 'steel');
+  const steelConstraints = normalizeSteelConstraints(source, steelMask, width, height);
+  const snapshot = {
+    kind: 'solver-state',
+    sourceKind: options.sourceKind ||
+      input?.sourceKind ||
+      input?.kind ||
+      input?.type ||
+      source.kind ||
+      (readGameFacade(input)?.level ? 'game' : 'level'),
+    id: String(options.id ?? source.id ?? source.name ?? 'level'),
+    width,
+    height,
+    terrainHash,
+    terrainMutationHash,
+    terrain: {
+      width,
+      height,
+      hash: terrainHash,
+      mutationHash: terrainMutationHash,
+      solidCount: countMask(groundMask),
+      mask: groundMask
+    },
+    steel: {
+      hash: steelHash,
+      solidCount: countMask(steelMask),
+      mask: steelMask,
+      constraints: steelConstraints
+    },
+    oneWay: normalizeOneWayConstraints(source),
+    entrances: normalizeEntrances(source),
+    exits: normalizeExits(source),
+    hazards: normalizeHazards(source),
+    terrainMutations,
+    lemmings: normalizeLemmings(input),
+    skills: normalizeSkills(input),
+    timer: normalizeTimer(input),
+    victory: normalizeVictory(input)
+  };
+  snapshot.hashes = {
+    terrain: snapshot.terrainHash,
+    terrainMutation: snapshot.terrainMutationHash,
+    steel: steelHash,
+    oneWay: stableHash(snapshot.oneWay),
+    hazards: stableHash(snapshot.hazards),
+    terrainMutations: stableHash(snapshot.terrainMutations),
+    entrances: stableHash(snapshot.entrances),
+    exits: stableHash(snapshot.exits),
+    lemmings: stableHash(snapshot.lemmings),
+    skills: stableHash(snapshot.skills),
+    timer: stableHash(snapshot.timer),
+    victory: stableHash(snapshot.victory)
+  };
+  snapshot.snapshotHash = stableHash(publicSnapshotForHash(snapshot));
+  snapshot.hashes.snapshot = snapshot.snapshotHash;
+  return snapshot;
+};
+
+const isSolverState = value => value?.kind === 'solver-state' && value?.terrain?.mask;
+
+export {
+  SKILL_NAMES_BY_TYPE,
+  extractSolverState,
+  hashMask,
+  isSolverState,
+  stableHash,
+  stableStringify
+};
diff --git a/js/solver/SolverTypes.js b/js/solver/SolverTypes.js
new file mode 100644
index 00000000..ba505e9e
--- /dev/null
+++ b/js/solver/SolverTypes.js
@@ -0,0 +1,208 @@
+const SOLVER_RESULT_TYPES = Object.freeze({
+  SOLVED: 'solved',
+  FAILED: 'failed',
+  UNKNOWN: 'unknown',
+  TIMEOUT: 'timeout',
+  UNSUPPORTED: 'unsupported'
+});
+
+const SOLVER_MODES = Object.freeze({
+  TACTICAL: 'tactical',
+  ROUTE: 'route',
+  FULL: 'full'
+});
+
+const SOLVER_EXPLANATION_CODES = Object.freeze({
+  BARRIER_BLOCKED_BY_STEEL: 'barrier-blocked-by-steel',
+  BUDGET_EXHAUSTED: 'budget-exhausted',
+  GAP_EXCEEDS_BUILDER_BUDGET: 'gap-exceeds-builder-budget',
+  HAZARD_UNAVOIDABLE: 'hazard-unavoidable',
+  MISSING_ENTRANCE: 'missing-entrance',
+  MISSING_EXIT: 'missing-exit',
+  MISSING_LANDING: 'missing-landing',
+  MISSING_RUNTIME_ADAPTER: 'missing-runtime-adapter',
+  NO_ROUTE_TO_EXIT: 'no-route-to-exit',
+  ONE_WAY_BLOCKED: 'one-way-blocked',
+  REPLAY_DIVERGED: 'replay-diverged',
+  SAVE_COUNT_UNREACHABLE: 'save-count-unreachable',
+  STATE_EXPLOSION: 'state-explosion',
+  ARTIFACT_WRITE_FAILED: 'artifact-write-failed',
+  TIMING_WINDOW_TOO_NARROW: 'timing-window-too-narrow',
+  UNSUPPORTED_MECHANIC: 'unsupported-mechanic'
+});
+
+const DEFAULT_SOLVER_OPTIONS = Object.freeze({
+  seed: 0,
+  mode: SOLVER_MODES.TACTICAL,
+  skillSubset: Object.freeze([]),
+  targetSaveCount: 1,
+  maxTicks: 1200,
+  maxNodes: 500,
+  maxActions: 8,
+  maxWallTimeMs: 250
+});
+
+const isPlainObject = value => value != null && typeof value === 'object' && !Array.isArray(value);
+
+const toNonNegativeInteger = (value, fallback) => {
+  const next = Number(value);
+  if (!Number.isFinite(next) || next < 0) return fallback;
+  return Math.floor(next);
+};
+
+const normalizeSkillSubset = value => {
+  if (value == null) return [];
+  const raw = Array.isArray(value) ? value : [value];
+  const seen = new Set();
+  const out = [];
+  for (const item of raw) {
+    const key = String(item || '').trim();
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    out.push(key);
+  }
+  return out;
+};
+
+const normalizeSolverOptions = (options = {}) => {
+  const source = isPlainObject(options) ? options : {};
+  const mode = Object.values(SOLVER_MODES).includes(source.mode)
+    ? source.mode
+    : DEFAULT_SOLVER_OPTIONS.mode;
+  return {
+    seed: toNonNegativeInteger(source.seed, DEFAULT_SOLVER_OPTIONS.seed),
+    mode,
+    skillSubset: normalizeSkillSubset(source.skillSubset ?? source.skills),
+    targetSaveCount: Math.max(0, toNonNegativeInteger(
+      source.targetSaveCount,
+      DEFAULT_SOLVER_OPTIONS.targetSaveCount
+    )),
+    maxTicks: Math.max(1, toNonNegativeInteger(source.maxTicks, DEFAULT_SOLVER_OPTIONS.maxTicks)),
+    maxNodes: Math.max(1, toNonNegativeInteger(source.maxNodes, DEFAULT_SOLVER_OPTIONS.maxNodes)),
+    maxActions: Math.max(0, toNonNegativeInteger(source.maxActions, DEFAULT_SOLVER_OPTIONS.maxActions)),
+    maxWallTimeMs: Math.max(1, toNonNegativeInteger(
+      source.maxWallTimeMs,
+      DEFAULT_SOLVER_OPTIONS.maxWallTimeMs
+    ))
+  };
+};
+
+const normalizeExplanation = explanation => {
+  if (typeof explanation === 'string') {
+    return { code: explanation, detail: null };
+  }
+  if (!isPlainObject(explanation)) {
+    return { code: SOLVER_EXPLANATION_CODES.STATE_EXPLOSION, detail: null };
+  }
+  return {
+    code: String(explanation.code || SOLVER_EXPLANATION_CODES.STATE_EXPLOSION),
+    detail: explanation.detail == null ? null : String(explanation.detail),
+    data: isPlainObject(explanation.data) ? { ...explanation.data } : undefined
+  };
+};
+
+const normalizeActionScriptAction = action => {
+  const source = isPlainObject(action) ? action : {};
+  const tick = Number.isFinite(source.tick) ? Math.max(0, Math.floor(source.tick)) : null;
+  const window = isPlainObject(source.window)
+    ? {
+      start: Math.max(0, Math.floor(Number(source.window.start) || 0)),
+      end: Math.max(0, Math.floor(Number(source.window.end) || 0))
+    }
+    : null;
+  return {
+    skillType: source.skillType ?? source.skill ?? null,
+    target: source.target ?? source.targetSelector ?? null,
+    tick,
+    window,
+    preconditions: Array.isArray(source.preconditions) ? [...source.preconditions] : [],
+    expectedPostconditions: Array.isArray(source.expectedPostconditions)
+      ? [...source.expectedPostconditions]
+      : [],
+    rationale: source.rationale == null ? null : String(source.rationale)
+  };
+};
+
+const createSolverResult = ({
+  resultType,
+  summary = '',
+  actions = [],
+  explanations = [],
+  budgetUsage = {},
+  replaySummary = null,
+  captures = []
+} = {}) => {
+  const type = Object.values(SOLVER_RESULT_TYPES).includes(resultType)
+    ? resultType
+    : SOLVER_RESULT_TYPES.UNKNOWN;
+  return {
+    resultType: type,
+    summary: String(summary || type),
+    actions: Array.isArray(actions) ? actions.map(normalizeActionScriptAction) : [],
+    explanations: Array.isArray(explanations) ? explanations.map(normalizeExplanation) : [],
+    budgetUsage: {
+      ticks: toNonNegativeInteger(budgetUsage.ticks, 0),
+      nodes: toNonNegativeInteger(budgetUsage.nodes, 0),
+      actions: toNonNegativeInteger(budgetUsage.actions, 0),
+      wallTimeMs: toNonNegativeInteger(budgetUsage.wallTimeMs, 0)
+    },
+    replaySummary,
+    captures: Array.isArray(captures) ? captures.map(item => String(item)) : []
+  };
+};
+
+const createBudgetMeter = (options = {}, now = () => Date.now()) => {
+  const normalized = normalizeSolverOptions(options);
+  const startedAt = now();
+  let nodes = 0;
+  let ticks = 0;
+  let actions = 0;
+  const usage = () => ({
+    ticks,
+    nodes,
+    actions,
+    wallTimeMs: Math.max(0, Math.floor(now() - startedAt))
+  });
+  return {
+    options: normalized,
+    recordNode(count = 1) {
+      nodes += Math.max(0, Math.floor(count));
+      return usage();
+    },
+    recordTick(count = 1) {
+      ticks += Math.max(0, Math.floor(count));
+      return usage();
+    },
+    recordAction(count = 1) {
+      actions += Math.max(0, Math.floor(count));
+      return usage();
+    },
+    usage,
+    isExceeded() {
+      const current = usage();
+      return current.nodes > normalized.maxNodes ||
+        current.ticks > normalized.maxTicks ||
+        current.actions > normalized.maxActions ||
+        current.wallTimeMs > normalized.maxWallTimeMs;
+    },
+    timeoutResult(summary = 'Solver budget was exhausted') {
+      return createSolverResult({
+        resultType: SOLVER_RESULT_TYPES.TIMEOUT,
+        summary,
+        explanations: [SOLVER_EXPLANATION_CODES.BUDGET_EXHAUSTED],
+        budgetUsage: usage()
+      });
+    }
+  };
+};
+
+export {
+  DEFAULT_SOLVER_OPTIONS,
+  SOLVER_EXPLANATION_CODES,
+  SOLVER_MODES,
+  SOLVER_RESULT_TYPES,
+  createBudgetMeter,
+  createSolverResult,
+  normalizeActionScriptAction,
+  normalizeSolverOptions
+};
diff --git a/js/solver/TacticalSolver.js b/js/solver/TacticalSolver.js
new file mode 100644
index 00000000..bfafc1e3
--- /dev/null
+++ b/js/solver/TacticalSolver.js
@@ -0,0 +1,564 @@
+import {
+  SOLVER_EXPLANATION_CODES,
+  SOLVER_RESULT_TYPES,
+  createBudgetMeter,
+  createSolverResult
+} from './SolverTypes.js';
+
+const BUILDER_SPAN_PIXELS = 12;
+const DEFAULT_SAFE_FALL_DISTANCE = 60;
+const MAX_SIMPLE_BARRIER_HEIGHT = 24;
+const WALK_TICKS_PER_PIXEL = 2;
+
+const SUPPORTED_MECHANICS = new Set([
+  'walk',
+  'gap',
+  'builder-gap',
+  'barrier',
+  'bash-barrier',
+  'dig-barrier',
+  'mine-barrier',
+  'floater-fall',
+  'blocker-turnaround'
+]);
+
+const DESTRUCTIVE_SKILLS = Object.freeze(['basher', 'digger', 'miner']);
+
+const isPlainObject = value => value != null && typeof value === 'object' && !Array.isArray(value);
+
+const toFiniteNumber = (value, fallback = 0) => {
+  const next = Number(value);
+  return Number.isFinite(next) ? next : fallback;
+};
+
+const toInteger = (value, fallback = 0) => Math.floor(toFiniteNumber(value, fallback));
+
+const maskData = mask => {
+  if (mask == null) return null;
+  if (mask.mask != null) return mask.mask;
+  return mask;
+};
+
+const maskAt = (mask, width, height, x, y) => {
+  const data = maskData(mask);
+  const px = Math.floor(x);
+  const py = Math.floor(y);
+  if (!data || px < 0 || py < 0 || px >= width || py >= height) return 0;
+  return data[(py * width) + px] ? 1 : 0;
+};
+
+const hasAnyMaskInRect = (mask, width, height, rect) => {
+  if (!rect) return false;
+  const x0 = Math.max(0, Math.floor(rect.x));
+  const y0 = Math.max(0, Math.floor(rect.y));
+  const x1 = Math.min(width, Math.ceil(rect.x + rect.width));
+  const y1 = Math.min(height, Math.ceil(rect.y + rect.height));
+  for (let y = y0; y < y1; y += 1) {
+    for (let x = x0; x < x1; x += 1) {
+      if (maskAt(mask, width, height, x, y)) return true;
+    }
+  }
+  return false;
+};
+
+const firstSupportedPoint = fixture => {
+  if (Array.isArray(fixture.lemmings) && fixture.lemmings.length > 0) {
+    return fixture.lemmings[0];
+  }
+  if (Array.isArray(fixture.entrances) && fixture.entrances.length > 0) {
+    return fixture.entrances[0];
+  }
+  return null;
+};
+
+const firstExit = fixture => Array.isArray(fixture.exits) && fixture.exits.length > 0
+  ? fixture.exits[0]
+  : null;
+
+const normalizeChallengeType = fixture => {
+  const challenge = fixture.challenge ?? fixture.tacticalChallenge ?? null;
+  if (typeof challenge === 'string') return challenge;
+  if (isPlainObject(challenge)) {
+    return challenge.type ?? challenge.mechanic ?? fixture.requiredMechanic ?? null;
+  }
+  return fixture.requiredMechanic ?? fixture.mechanic ?? null;
+};
+
+const challengeData = fixture => {
+  const challenge = fixture.challenge ?? fixture.tacticalChallenge ?? null;
+  return isPlainObject(challenge) ? challenge : {};
+};
+
+const findFallChallenge = fixture => {
+  if (isPlainObject(fixture.fall)) return fixture.fall;
+  const challenge = challengeData(fixture);
+  if (challenge.type === 'floater-fall' || challenge.mechanic === 'floater-fall') {
+    return challenge;
+  }
+  if (!Array.isArray(fixture.hazards)) return null;
+  return fixture.hazards.find(hazard => hazard.type === 'fall' || hazard.type === 'drop') ?? null;
+};
+
+const findBlockerTurnaround = fixture => {
+  if (isPlainObject(fixture.blockerTurnaround)) return fixture.blockerTurnaround;
+  const challenge = challengeData(fixture);
+  if (challenge.type === 'blocker-turnaround' || challenge.mechanic === 'blocker-turnaround') {
+    return challenge;
+  }
+  return null;
+};
+
+const skillCount = (fixture, skill) => {
+  const count = toInteger(fixture.skills?.[skill], 0);
+  return Math.max(0, count);
+};
+
+const directionToExit = (start, exit) => exit.x >= start.x ? 1 : -1;
+
+const targetSelector = (start, role = 'lead') => ({
+  kind: 'lemming',
+  id: start.id ?? 0,
+  role
+});
+
+const tickForX = (fixture, start, x) => {
+  const baseTick = toInteger(fixture.timer?.tick, 0);
+  const distance = Math.abs(toFiniteNumber(x, start.x) - toFiniteNumber(start.x, 0));
+  return baseTick + Math.max(0, Math.floor(distance * WALK_TICKS_PER_PIXEL));
+};
+
+const tickWindow = tick => ({
+  start: Math.max(0, tick - 6),
+  end: tick + 6
+});
+
+const supportYFor = start => toInteger(start.y, 0) + 1;
+
+const hasSupportAt = (fixture, x, footY) => {
+  const y = footY + 1;
+  return maskAt(fixture.groundMask, fixture.width, fixture.height, x, y) === 1;
+};
+
+const barrierHeightAt = (fixture, x, footY) => {
+  let height = 0;
+  for (let y = footY; y >= 0; y -= 1) {
+    if (!maskAt(fixture.groundMask, fixture.width, fixture.height, x, y)) break;
+    height += 1;
+  }
+  return height;
+};
+
+class TacticalSolver {
+  constructor(fixture, options = {}, deps = {}) {
+    this.fixture = fixture ?? {};
+    this.meter = createBudgetMeter(options, deps.now ?? options.now ?? (() => 0));
+    this.options = this.meter.options;
+    this.allowedSkills = new Set(this.options.skillSubset);
+  }
+
+  solve() {
+    const timeout = this.recordNode('Solver budget exhausted while reading tactical fixture');
+    if (timeout) return timeout;
+
+    const unsupported = this.unsupportedMechanicResult();
+    if (unsupported) return unsupported;
+
+    const required = this.validateRouteEndpoints();
+    if (required) return required;
+
+    const fall = findFallChallenge(this.fixture);
+    if (fall) return this.solveFloaterFall(fall);
+
+    const turnaround = findBlockerTurnaround(this.fixture);
+    if (turnaround) return this.solveBlockerTurnaround(turnaround);
+
+    return this.solveLocalRoute();
+  }
+
+  recordNode(summary) {
+    this.meter.recordNode();
+    return this.timeoutIfExceeded(summary);
+  }
+
+  recordAction(summary) {
+    this.meter.recordAction();
+    return this.timeoutIfExceeded(summary);
+  }
+
+  recordTicks(count, summary) {
+    this.meter.recordTick(count);
+    return this.timeoutIfExceeded(summary);
+  }
+
+  timeoutIfExceeded(summary) {
+    if (!this.meter.isExceeded()) return null;
+    return createSolverResult({
+      resultType: SOLVER_RESULT_TYPES.TIMEOUT,
+      summary,
+      explanations: [{
+        code: SOLVER_EXPLANATION_CODES.BUDGET_EXHAUSTED,
+        detail: 'Tactical solver stopped before exceeding configured node, tick, action, or wall-time budget.'
+      }],
+      budgetUsage: this.meter.usage()
+    });
+  }
+
+  unsupportedMechanicResult() {
+    const mechanic = normalizeChallengeType(this.fixture);
+    if (!mechanic || SUPPORTED_MECHANICS.has(mechanic)) return null;
+    return this.result(SOLVER_RESULT_TYPES.UNSUPPORTED, `Unsupported tactical mechanic: ${mechanic}`, [], [{
+      code: SOLVER_EXPLANATION_CODES.UNSUPPORTED_MECHANIC,
+      detail: `The tactical solver does not model ${mechanic}.`,
+      data: { mechanic }
+    }]);
+  }
+
+  validateRouteEndpoints() {
+    const start = firstSupportedPoint(this.fixture);
+    const exit = firstExit(this.fixture);
+    if (!start) {
+      return this.result(SOLVER_RESULT_TYPES.FAILED, 'No entrance or lemming is available for tactical solving', [], [{
+        code: SOLVER_EXPLANATION_CODES.MISSING_ENTRANCE,
+        detail: 'Fixture has no lemming and no entrance.'
+      }]);
+    }
+    if (!exit) {
+      return this.result(SOLVER_RESULT_TYPES.FAILED, 'No exit is available for tactical solving', [], [{
+        code: SOLVER_EXPLANATION_CODES.MISSING_EXIT,
+        detail: 'Fixture has no exit target.'
+      }]);
+    }
+    return null;
+  }
+
+  solveFloaterFall(fall) {
+    const start = firstSupportedPoint(this.fixture);
+    const fromY = toFiniteNumber(fall.fromY ?? fall.y ?? start.y, start.y);
+    const toY = toFiniteNumber(fall.toY ?? fall.landingY ?? fall.y + fall.height, fromY);
+    const fallDistance = Math.max(0, Math.floor(toY - fromY));
+    const safeDistance = Math.max(0, toInteger(fall.safeFallDistance, DEFAULT_SAFE_FALL_DISTANCE));
+    const timeout = this.recordNode('Solver budget exhausted while checking floater fall');
+    if (timeout) return timeout;
+
+    if (fallDistance <= safeDistance) {
+      return this.result(SOLVER_RESULT_TYPES.SOLVED, 'Fall is survivable without a floater', [], []);
+    }
+    if (!this.canUseSkill('floater')) {
+      return this.result(SOLVER_RESULT_TYPES.FAILED, 'Lethal fall requires a floater skill', [], [{
+        code: SOLVER_EXPLANATION_CODES.HAZARD_UNAVOIDABLE,
+        detail: 'The fall exceeds safe distance and no usable floater is available.',
+        data: { fallDistance, safeDistance }
+      }]);
+    }
+
+    const x = toFiniteNumber(fall.x ?? start.x, start.x);
+    const tick = toInteger(fall.assignmentTick, tickForX(this.fixture, start, x));
+    const action = {
+      skillType: 'floater',
+      targetSelector: targetSelector(start),
+      tick,
+      window: tickWindow(tick),
+      preconditions: [
+        `lemming is falling before ${fallDistance}px drop`,
+        'floater skill is available'
+      ],
+      expectedPostconditions: [
+        'lemming opens umbrella',
+        'lemming survives landing'
+      ],
+      rationale: `Assign floater before a ${fallDistance}px drop that exceeds the ${safeDistance}px safe fall distance.`
+    };
+    return this.solvedWithActions('Floater action survives the local fall challenge', [action], fallDistance);
+  }
+
+  solveBlockerTurnaround(turnaround) {
+    const start = firstSupportedPoint(this.fixture);
+    const exit = firstExit(this.fixture);
+    const timeout = this.recordNode('Solver budget exhausted while checking blocker turnaround');
+    if (timeout) return timeout;
+
+    if (!this.canUseSkill('blocker')) {
+      return this.result(SOLVER_RESULT_TYPES.FAILED, 'Turnaround requires a blocker skill', [], [{
+        code: SOLVER_EXPLANATION_CODES.NO_ROUTE_TO_EXIT,
+        detail: 'The local route requires a blocker turnaround and no usable blocker is available.'
+      }]);
+    }
+
+    const x = toFiniteNumber(turnaround.x ?? start.x, start.x);
+    const y = toFiniteNumber(turnaround.y ?? start.y, start.y);
+    const tick = toInteger(turnaround.assignmentTick, tickForX(this.fixture, start, x));
+    const direction = directionToExit(start, exit) > 0 ? 'right' : 'left';
+    const action = {
+      skillType: 'blocker',
+      targetSelector: {
+        ...targetSelector(start, 'turnaround-anchor'),
+        x,
+        y
+      },
+      tick,
+      window: tickWindow(tick),
+      preconditions: [
+        'blocker skill is available',
+        `crowd approaches blocker from the ${direction === 'right' ? 'left' : 'right'}`
+      ],
+      expectedPostconditions: [
+        `crowd turns ${direction}`,
+        'lead route continues toward exit'
+      ],
+      rationale: `Place a blocker at x=${Math.floor(x)} to reverse the crowd toward the exit.`
+    };
+    return this.solvedWithActions('Blocker action turns the local route toward the exit', [action], 12);
+  }
+
+  solveLocalRoute() {
+    const start = firstSupportedPoint(this.fixture);
+    const exit = firstExit(this.fixture);
+    const route = this.scanRoute(start, exit);
+    if (route.result) return route.result;
+
+    const actions = [];
+    for (const gap of route.gaps) {
+      const gapResult = this.actionForGap(start, gap);
+      if (gapResult.result) return gapResult.result;
+      actions.push(...gapResult.actions);
+    }
+    for (const barrier of route.barriers) {
+      const barrierResult = this.actionForBarrier(start, barrier);
+      if (barrierResult.result) return barrierResult.result;
+      actions.push(...barrierResult.actions);
+    }
+
+    if (actions.length === 0) {
+      return this.result(SOLVER_RESULT_TYPES.SOLVED, 'Direct walking route reaches the local exit', [], []);
+    }
+
+    return this.solvedWithActions('Tactical actions connect the local route to the exit', actions, route.ticks);
+  }
+
+  scanRoute(start, exit) {
+    const timeout = this.recordNode('Solver budget exhausted while scanning local route');
+    if (timeout) return { result: timeout };
+
+    const direction = directionToExit(start, exit);
+    const xStart = Math.max(0, Math.min(this.fixture.width - 1, toInteger(start.x, 0)));
+    const xEnd = Math.max(0, Math.min(this.fixture.width - 1, toInteger(exit.x, 0)));
+    const footY = toInteger(start.y, 0);
+    const gaps = [];
+    const barriers = [];
+    let activeGap = null;
+    let activeBarrier = null;
+
+    for (let x = xStart; direction > 0 ? x <= xEnd : x >= xEnd; x += direction) {
+      const supported = hasSupportAt(this.fixture, x, footY);
+      const barrierHeight = supported ? barrierHeightAt(this.fixture, x, footY) : 0;
+
+      if (!supported && activeGap == null) {
+        activeGap = { startX: x, endX: x, y: supportYFor(start) };
+      } else if (!supported) {
+        activeGap.endX = x;
+      } else if (activeGap) {
+        gaps.push(this.finalizeSpan(activeGap, direction));
+        activeGap = null;
+      }
+
+      if (barrierHeight > 0 && activeBarrier == null) {
+        activeBarrier = { startX: x, endX: x, footY, height: barrierHeight };
+      } else if (barrierHeight > 0) {
+        activeBarrier.endX = x;
+        activeBarrier.height = Math.max(activeBarrier.height, barrierHeight);
+      } else if (activeBarrier) {
+        barriers.push(this.finalizeSpan(activeBarrier, direction));
+        activeBarrier = null;
+      }
+    }
+
+    if (activeGap) gaps.push(this.finalizeSpan(activeGap, direction));
+    if (activeBarrier) barriers.push(this.finalizeSpan(activeBarrier, direction));
+
+    if (gaps.length > 0) {
+      const timeoutAfterGap = this.recordNode('Solver budget exhausted while classifying gaps');
+      if (timeoutAfterGap) return { result: timeoutAfterGap };
+    }
+    if (barriers.length > 0) {
+      const timeoutAfterBarrier = this.recordNode('Solver budget exhausted while classifying barriers');
+      if (timeoutAfterBarrier) return { result: timeoutAfterBarrier };
+    }
+
+    return {
+      gaps,
+      barriers,
+      ticks: Math.abs(xEnd - xStart) * WALK_TICKS_PER_PIXEL
+    };
+  }
+
+  finalizeSpan(span, direction) {
+    const minX = Math.min(span.startX, span.endX);
+    const maxX = Math.max(span.startX, span.endX);
+    return {
+      ...span,
+      direction,
+      minX,
+      maxX,
+      width: (maxX - minX) + 1
+    };
+  }
+
+  actionForGap(start, gap) {
+    const builderBudget = this.skillBudget('builder');
+    const neededBuilders = Math.max(1, Math.ceil(gap.width / BUILDER_SPAN_PIXELS));
+    if (builderBudget <= 0) {
+      return {
+        result: this.result(SOLVER_RESULT_TYPES.FAILED, 'No route to exit through unbridged gap', [], [{
+          code: SOLVER_EXPLANATION_CODES.NO_ROUTE_TO_EXIT,
+          detail: 'The route has a gap and no usable builder skill.'
+        }])
+      };
+    }
+    if (neededBuilders > builderBudget) {
+      return {
+        result: this.result(SOLVER_RESULT_TYPES.FAILED, 'Gap exceeds available builder budget', [], [{
+          code: SOLVER_EXPLANATION_CODES.GAP_EXCEEDS_BUILDER_BUDGET,
+          detail: `Gap width ${gap.width}px requires ${neededBuilders} builders but only ${builderBudget} are usable.`,
+          data: { gapWidth: gap.width, neededBuilders, builderBudget }
+        }])
+      };
+    }
+
+    const actions = [];
+    for (let i = 0; i < neededBuilders; i += 1) {
+      const targetX = gap.direction > 0
+        ? gap.minX - 1 + (i * BUILDER_SPAN_PIXELS)
+        : gap.maxX + 1 - (i * BUILDER_SPAN_PIXELS);
+      const tick = tickForX(this.fixture, start, targetX) + (i * 14);
+      const action = {
+        skillType: 'builder',
+        targetSelector: {
+          ...targetSelector(start),
+          x: targetX,
+          y: gap.y
+        },
+        tick,
+        window: tickWindow(tick),
+        preconditions: [
+          'builder skill is available',
+          'lemming is walking at the gap edge'
+        ],
+        expectedPostconditions: [
+          `bridge covers gap x=${gap.minX}..${gap.maxX}`,
+          'lemming reaches the far-side landing'
+        ],
+        rationale: `Bridge ${gap.width}px gap with builder ${i + 1} of ${neededBuilders}.`
+      };
+      const timeout = this.recordAction('Solver budget exhausted while adding builder action');
+      if (timeout) return { result: timeout };
+      actions.push(action);
+    }
+    return { actions };
+  }
+
+  actionForBarrier(start, barrier) {
+    const rect = {
+      x: barrier.minX,
+      y: Math.max(0, barrier.footY - barrier.height + 1),
+      width: barrier.width,
+      height: barrier.height
+    };
+    if (hasAnyMaskInRect(this.fixture.steelMask, this.fixture.width, this.fixture.height, rect)) {
+      return {
+        result: this.result(SOLVER_RESULT_TYPES.FAILED, 'Barrier is blocked by steel', [], [{
+          code: SOLVER_EXPLANATION_CODES.BARRIER_BLOCKED_BY_STEEL,
+          detail: 'The simple destructive tunnel intersects steel terrain.',
+          data: { x: barrier.minX, width: barrier.width, height: barrier.height }
+        }])
+      };
+    }
+    if (barrier.height > MAX_SIMPLE_BARRIER_HEIGHT) {
+      return {
+        result: this.result(SOLVER_RESULT_TYPES.UNKNOWN, 'Barrier exceeds tactical solver bounds', [], [{
+          code: SOLVER_EXPLANATION_CODES.STATE_EXPLOSION,
+          detail: `Barrier height ${barrier.height}px exceeds the ${MAX_SIMPLE_BARRIER_HEIGHT}px simple local bound.`,
+          data: { x: barrier.minX, width: barrier.width, height: barrier.height }
+        }])
+      };
+    }
+
+    const preferred = this.preferredBarrierSkill();
+    if (!preferred) {
+      return {
+        result: this.result(SOLVER_RESULT_TYPES.FAILED, 'No route to exit through simple barrier', [], [{
+          code: SOLVER_EXPLANATION_CODES.NO_ROUTE_TO_EXIT,
+          detail: 'The route has a simple barrier and no usable dig, bash, or mine skill.'
+        }])
+      };
+    }
+
+    const targetX = barrier.direction > 0 ? barrier.minX - 1 : barrier.maxX + 1;
+    const tick = tickForX(this.fixture, start, targetX);
+    const action = {
+      skillType: preferred,
+      targetSelector: {
+        ...targetSelector(start),
+        x: targetX,
+        y: barrier.footY
+      },
+      tick,
+      window: tickWindow(tick),
+      preconditions: [
+        `${preferred} skill is available`,
+        'lemming is walking at the barrier face',
+        'tunnel path does not intersect steel'
+      ],
+      expectedPostconditions: [
+        `${preferred} clears simple barrier x=${barrier.minX}..${barrier.maxX}`,
+        'lemming resumes route toward exit'
+      ],
+      rationale: `Use ${preferred} to clear a ${barrier.width}px wide, ${barrier.height}px high barrier.`
+    };
+    const timeout = this.recordAction('Solver budget exhausted while adding barrier action');
+    if (timeout) return { result: timeout };
+    return { actions: [action] };
+  }
+
+  preferredBarrierSkill() {
+    const requested = normalizeChallengeType(this.fixture);
+    if (requested === 'bash-barrier' && this.canUseSkill('basher')) return 'basher';
+    if (requested === 'dig-barrier' && this.canUseSkill('digger')) return 'digger';
+    if (requested === 'mine-barrier' && this.canUseSkill('miner')) return 'miner';
+    return DESTRUCTIVE_SKILLS.find(skill => this.canUseSkill(skill)) ?? null;
+  }
+
+  skillBudget(skill) {
+    if (this.allowedSkills.size > 0 && !this.allowedSkills.has(skill)) return 0;
+    return skillCount(this.fixture, skill);
+  }
+
+  canUseSkill(skill) {
+    return this.skillBudget(skill) > 0;
+  }
+
+  solvedWithActions(summary, actions, tickEstimate) {
+    const timeout = this.recordTicks(tickEstimate, `Solver budget exhausted after ${summary}`);
+    if (timeout) return timeout;
+    return this.result(SOLVER_RESULT_TYPES.SOLVED, summary, actions, []);
+  }
+
+  result(resultType, summary, actions, explanations) {
+    return createSolverResult({
+      resultType,
+      summary,
+      actions,
+      explanations,
+      budgetUsage: this.meter.usage(),
+      replaySummary: resultType === SOLVER_RESULT_TYPES.SOLVED
+        ? { verifier: 'local-tactical-fixture', verified: true }
+        : null
+    });
+  }
+}
+
+const solveTactical = (fixture, options = {}, deps = {}) => new TacticalSolver(fixture, options, deps).solve();
+
+export {
+  TacticalSolver,
+  solveTactical
+};
diff --git a/js/solver/TerrainMutationPlanner.js b/js/solver/TerrainMutationPlanner.js
new file mode 100644
index 00000000..d95cfa40
--- /dev/null
+++ b/js/solver/TerrainMutationPlanner.js
@@ -0,0 +1,153 @@
+import { analyzeSolverAffordances } from './SolverAnalysis.js';
+import { buildReachabilityGraph, invalidateReachabilityGraph } from './ReachabilityGraph.js';
+import { extractSolverState, hashMask, isSolverState, stableHash } from './SolverState.js';
+
+const MUTATION_SKILLS = new Set(['builder', 'digger', 'basher', 'miner']);
+
+const cloneMask = mask => {
+  if (mask instanceof Uint8Array) return new Uint8Array(mask);
+  if (ArrayBuffer.isView(mask)) return new Uint8Array(mask.buffer.slice(mask.byteOffset, mask.byteOffset + mask.byteLength));
+  if (Array.isArray(mask)) return Uint8Array.from(mask);
+  return new Uint8Array(0);
+};
+
+const clampRect = (snapshot, rect) => {
+  const x = Math.max(0, Math.floor(rect.x));
+  const y = Math.max(0, Math.floor(rect.y));
+  const x2 = Math.min(snapshot.width, Math.ceil(rect.x + rect.width));
+  const y2 = Math.min(snapshot.height, Math.ceil(rect.y + rect.height));
+  return {
+    x,
+    y,
+    width: Math.max(0, x2 - x),
+    height: Math.max(0, y2 - y)
+  };
+};
+
+const forEachRectPixel = (snapshot, rect, fn) => {
+  const clipped = clampRect(snapshot, rect);
+  for (let y = clipped.y; y < clipped.y + clipped.height; y += 1) {
+    const row = y * snapshot.width;
+    for (let x = clipped.x; x < clipped.x + clipped.width; x += 1) {
+      fn(x, y, row + x);
+    }
+  }
+};
+
+const candidateFromAffordance = (snapshot, graph, affordance) => {
+  if (!MUTATION_SKILLS.has(affordance.skillType)) return null;
+  const affectedBounds = { ...affordance.rect };
+  const candidate = {
+    id: `mutation:${affordance.id}`,
+    kind: affordance.type,
+    skillType: affordance.skillType,
+    fromSurfaceId: affordance.fromSurfaceId,
+    toSurfaceId: affordance.toSurfaceId,
+    affectedBounds,
+    requiredSkillCount: affordance.requiredSkillCount,
+    availableSkillCount: affordance.availableSkillCount,
+    roughTimingWindow: affordance.roughTimingWindow,
+    steelBlockers: affordance.blockers.filter(blocker => blocker.type === 'steel'),
+    oneWayBlockers: affordance.blockers.filter(blocker => blocker.type === 'one-way'),
+    expectedGraphInvalidation: invalidateReachabilityGraph(graph, { affectedBounds }),
+    expectedNewSurfaces: affordance.toSurfaceId == null
+      ? [{ generatedBy: affordance.id, bounds: affectedBounds }]
+      : [],
+    acceptedOnlyAfterReplay: snapshot.sourceKind !== 'synthetic'
+  };
+  candidate.blocked = candidate.steelBlockers.length > 0 || candidate.oneWayBlockers.length > 0;
+  candidate.mutationHash = stableHash(candidate);
+  return candidate;
+};
+
+const planTerrainMutations = (input, options = {}) => {
+  const snapshot = isSolverState(input) ? input : extractSolverState(input, options);
+  const graph = options.graph ?? buildReachabilityGraph(snapshot, options);
+  const analysis = options.analysis ?? analyzeSolverAffordances(snapshot, options);
+  const candidates = analysis.skillAffordances
+    .map(affordance => candidateFromAffordance(snapshot, graph, affordance))
+    .filter(Boolean)
+    .sort((left, right) => (
+      Number(left.blocked) - Number(right.blocked) ||
+      left.affectedBounds.y - right.affectedBounds.y ||
+      left.affectedBounds.x - right.affectedBounds.x ||
+      left.skillType.localeCompare(right.skillType) ||
+      left.id.localeCompare(right.id)
+    ));
+  const plan = {
+    kind: 'solver-terrain-mutation-plan',
+    stateHash: snapshot.snapshotHash,
+    terrainMutationHash: snapshot.terrainMutationHash,
+    graphHash: graph.graphHash,
+    candidates
+  };
+  plan.planHash = stableHash(plan);
+  return plan;
+};
+
+const simulateTerrainMutation = (snapshotInput, candidate) => {
+  const snapshot = isSolverState(snapshotInput) ? snapshotInput : extractSolverState(snapshotInput);
+  const groundMask = cloneMask(snapshot.terrain.mask);
+  const baseGroundMask = cloneMask(snapshot.terrain.mask);
+  const steelMask = cloneMask(snapshot.steel.mask);
+  if (!candidate || candidate.blocked) {
+    return {
+      snapshot,
+      applied: false,
+      reason: candidate?.blocked ? 'blocked' : 'missing-candidate'
+    };
+  }
+  if (candidate.skillType === 'builder') {
+    forEachRectPixel(snapshot, candidate.affectedBounds, (_x, _y, index) => {
+      groundMask[index] = 1;
+    });
+  } else {
+    forEachRectPixel(snapshot, candidate.affectedBounds, (_x, _y, index) => {
+      if (steelMask[index]) return;
+      groundMask[index] = 0;
+    });
+  }
+  const nextSource = {
+    kind: snapshot.sourceKind,
+    id: snapshot.id,
+    width: snapshot.width,
+    height: snapshot.height,
+    baseGroundMask,
+    groundMask,
+    steelMask,
+    steel: snapshot.steel.constraints,
+    oneWay: snapshot.oneWay,
+    entrances: snapshot.entrances,
+    exits: snapshot.exits,
+    hazards: snapshot.hazards,
+    lemmings: snapshot.lemmings,
+    skills: snapshot.skills.counts,
+    timer: snapshot.timer,
+    needCount: snapshot.victory.needCount,
+    releaseCount: snapshot.victory.releaseCount,
+    terrainMutations: [
+      ...snapshot.terrainMutations,
+      {
+        kind: candidate.kind,
+        skillType: candidate.skillType,
+        ...candidate.affectedBounds
+      }
+    ]
+  };
+  const nextSnapshot = extractSolverState(nextSource, {
+    sourceKind: snapshot.sourceKind,
+    id: `${snapshot.id}:mutation`
+  });
+  return {
+    snapshot: nextSnapshot,
+    applied: true,
+    previousTerrainMutationHash: snapshot.terrainMutationHash,
+    terrainMutationHash: hashMask(groundMask, snapshot.width, snapshot.height, 'terrain-mutation'),
+    snapshotHash: nextSnapshot.snapshotHash
+  };
+};
+
+export {
+  planTerrainMutations,
+  simulateTerrainMutation
+};
diff --git a/js/solver/TimingSearch.js b/js/solver/TimingSearch.js
new file mode 100644
index 00000000..c351ff86
--- /dev/null
+++ b/js/solver/TimingSearch.js
@@ -0,0 +1,183 @@
+import {
+  SOLVER_EXPLANATION_CODES,
+  SOLVER_RESULT_TYPES,
+  createSolverResult,
+  normalizeSolverOptions
+} from './SolverTypes.js';
+import { planSolverRoute } from './RoutePlanner.js';
+import { validateSaveCountForResult } from './SolverCrowd.js';
+import { stableHash } from './SolverState.js';
+import { verifyActionReplay } from './SolverRunner.js';
+
+const DEFAULT_SKILL_FOR_EDGE = Object.freeze({
+  build: 'builder',
+  basher: 'basher',
+  digger: 'digger',
+  miner: 'miner',
+  fall: 'floater',
+  'blocker-turn': 'blocker'
+});
+
+const windowForSegment = (segment, fallbackTick) => {
+  const raw = segment.roughActionWindow;
+  if (raw) {
+    return {
+      start: Math.max(0, Math.floor(Number(raw.start) || 0)),
+      end: Math.max(0, Math.floor(Number(raw.end) || 0))
+    };
+  }
+  return {
+    start: Math.max(0, fallbackTick - 6),
+    end: fallbackTick + 6
+  };
+};
+
+const actionForSegment = (segment, tickCursor) => {
+  const skillType = segment.requiredSkillFamilies?.[0] ?? DEFAULT_SKILL_FOR_EDGE[segment.type] ?? null;
+  if (!skillType) return null;
+  const window = windowForSegment(segment, tickCursor);
+  return {
+    skillType,
+    target: {
+      kind: 'lemming',
+      role: skillType === 'blocker' ? 'blocker-anchor' : 'frontier'
+    },
+    tick: null,
+    window,
+    preconditions: [
+      { type: 'skillAvailable', skillType, count: 1 },
+      'target-active'
+    ],
+    expectedPostconditions: [
+      { type: 'activeCountAtLeast', count: 1 }
+    ],
+    rationale: `Apply ${skillType} for ${segment.type} segment ${segment.index}.`
+  };
+};
+
+const compactStats = stats => ({
+  nodes: stats.nodes,
+  ticksConsidered: stats.ticksConsidered,
+  actionsConsidered: stats.actionsConsidered,
+  prunedEquivalentStates: stats.prunedEquivalentStates,
+  prunedImpossiblePreconditions: stats.prunedImpossiblePreconditions,
+  prunedDominatedScripts: stats.prunedDominatedScripts,
+  bestFailureReason: stats.bestFailureReason
+});
+
+const buildCandidateScript = routeSkeleton => {
+  const actions = [];
+  let tickCursor = 0;
+  for (const segment of routeSkeleton.segments ?? []) {
+    tickCursor += 12;
+    const action = actionForSegment(segment, tickCursor);
+    if (!action) continue;
+    actions.push(action);
+    tickCursor = Math.max(tickCursor, action.window.end);
+  }
+  return actions;
+};
+
+const searchActionTiming = (runnerOrSource, routeOrInput = null, options = {}) => {
+  const normalized = normalizeSolverOptions(options);
+  const stats = {
+    nodes: 0,
+    ticksConsidered: 0,
+    actionsConsidered: 0,
+    prunedEquivalentStates: 0,
+    prunedImpossiblePreconditions: 0,
+    prunedDominatedScripts: 0,
+    bestFailureReason: null
+  };
+  const routeSkeleton = routeOrInput?.kind === 'solver-route-skeleton'
+    ? routeOrInput
+    : routeOrInput?.routeSkeleton ??
+      planSolverRoute(routeOrInput ?? runnerOrSource, options).routeSkeleton;
+  if (!routeSkeleton) {
+    const result = createSolverResult({
+      resultType: SOLVER_RESULT_TYPES.FAILED,
+      summary: 'Timing search has no route skeleton to schedule',
+      explanations: [SOLVER_EXPLANATION_CODES.NO_ROUTE_TO_EXIT],
+      budgetUsage: { nodes: 1 }
+    });
+    result.timingSearchStats = compactStats({ ...stats, nodes: 1 });
+    return result;
+  }
+
+  const seenStateKeys = new Set();
+  const actions = buildCandidateScript(routeSkeleton);
+  stats.actionsConsidered = actions.length;
+  stats.ticksConsidered = actions.reduce((sum, action) => {
+    return sum + Math.max(1, action.window.end - action.window.start + 1);
+  }, 0);
+  stats.nodes = Math.max(1, actions.length + 1);
+  if (stats.nodes > normalized.maxNodes || actions.length > normalized.maxActions) {
+    const result = createSolverResult({
+      resultType: SOLVER_RESULT_TYPES.TIMEOUT,
+      summary: 'Timing search exhausted deterministic budget',
+      explanations: [SOLVER_EXPLANATION_CODES.BUDGET_EXHAUSTED],
+      budgetUsage: {
+        nodes: stats.nodes,
+        actions: actions.length,
+        ticks: stats.ticksConsidered
+      }
+    });
+    result.timingSearchStats = compactStats(stats);
+    result.routeSkeleton = routeSkeleton;
+    return result;
+  }
+
+  const canonicalKey = stableHash(actions.map(action => ({
+    skillType: action.skillType,
+    target: action.target,
+    window: action.window
+  })));
+  if (seenStateKeys.has(canonicalKey)) {
+    stats.prunedEquivalentStates += 1;
+  }
+  seenStateKeys.add(canonicalKey);
+
+  const narrow = actions.find(action => action.window.end < action.window.start);
+  if (narrow) {
+    stats.prunedImpossiblePreconditions += 1;
+    stats.bestFailureReason = SOLVER_EXPLANATION_CODES.TIMING_WINDOW_TOO_NARROW;
+    const result = createSolverResult({
+      resultType: SOLVER_RESULT_TYPES.FAILED,
+      summary: 'Timing search found an impossible action window',
+      actions,
+      explanations: [SOLVER_EXPLANATION_CODES.TIMING_WINDOW_TOO_NARROW],
+      budgetUsage: {
+        nodes: stats.nodes,
+        actions: actions.length,
+        ticks: stats.ticksConsidered
+      }
+    });
+    result.timingSearchStats = compactStats(stats);
+    result.routeSkeleton = routeSkeleton;
+    return result;
+  }
+
+  const replay = options.verify === false
+    ? createSolverResult({
+      resultType: SOLVER_RESULT_TYPES.UNKNOWN,
+      summary: 'Timing candidate generated; runtime replay was skipped by option',
+      actions,
+      budgetUsage: {
+        nodes: stats.nodes,
+        actions: actions.length,
+        ticks: stats.ticksConsidered
+      }
+    })
+    : verifyActionReplay(runnerOrSource, actions, normalized);
+  const result = options.crowd
+    ? validateSaveCountForResult(replay, options.crowd, normalized)
+    : replay;
+  result.timingSearchStats = compactStats(stats);
+  result.routeSkeleton = routeSkeleton;
+  result.candidateScriptHash = stableHash(actions);
+  return result;
+};
+
+export {
+  searchActionTiming
+};
diff --git a/js/solver/index.js b/js/solver/index.js
new file mode 100644
index 00000000..96881545
--- /dev/null
+++ b/js/solver/index.js
@@ -0,0 +1,14 @@
+export * from './SolverTypes.js';
+export * from './SolverFixtures.js';
+export * from './SolverRunner.js';
+export * from './SolverState.js';
+export * from './SolverGeometry.js';
+export * from './SolverAnalysis.js';
+export * from './ReachabilityGraph.js';
+export * from './RoutePlanner.js';
+export * from './SolverCrowd.js';
+export * from './TerrainMutationPlanner.js';
+export * from './TimingSearch.js';
+export * from './TacticalSolver.js';
+export * from './ProcgenCertificates.js';
+export * from './EditorAdvisory.js';
diff --git a/js/steelSprites.json b/js/steelSprites.json
index 03c890ab..4b3c4518 100644
--- a/js/steelSprites.json
+++ b/js/steelSprites.json
@@ -10,5 +10,21 @@
     "GROUND0O.DAT": [51, 52, 53, 54],
     "GROUND1O.DAT": [56, 57, 58, 59],
     "GROUND2O.DAT": [29, 30, 31, 32]
+  },
+  "xmas91": {
+    "GROUND0O.DAT": [51, 52, 53],
+    "GROUND2O.DAT": [29]
+  },
+  "xmas92": {
+    "GROUND0O.DAT": [51, 52, 53],
+    "GROUND2O.DAT": [29]
+  },
+  "holiday93": {
+    "GROUND1O.DAT": [56, 57, 58, 59],
+    "GROUND2O.DAT": [29]
+  },
+  "holiday94": {
+    "GROUND1O.DAT": [56, 57, 58, 59],
+    "GROUND2O.DAT": [29]
   }
 }
diff --git a/js/steelSpritesData.js b/js/steelSpritesData.js
new file mode 100644
index 00000000..43c7b301
--- /dev/null
+++ b/js/steelSpritesData.js
@@ -0,0 +1,32 @@
+const DEFAULT_STEEL_SPRITES = Object.freeze({
+  lemmings: Object.freeze({
+    'GROUND0O.DAT': Object.freeze([22, 23, 24, 25, 26]),
+    'GROUND1O.DAT': Object.freeze([12, 13, 14, 15, 16, 17]),
+    'GROUND2O.DAT': Object.freeze([5, 57, 58, 59]),
+    'GROUND3O.DAT': Object.freeze([27, 48, 49, 50]),
+    'GROUND4O.DAT': Object.freeze([31, 32, 34])
+  }),
+  lemmings_ohNo: Object.freeze({
+    'GROUND0O.DAT': Object.freeze([51, 52, 53, 54]),
+    'GROUND1O.DAT': Object.freeze([56, 57, 58, 59]),
+    'GROUND2O.DAT': Object.freeze([29, 30, 31, 32])
+  }),
+  xmas91: Object.freeze({
+    'GROUND0O.DAT': Object.freeze([51, 52, 53]),
+    'GROUND2O.DAT': Object.freeze([29])
+  }),
+  xmas92: Object.freeze({
+    'GROUND0O.DAT': Object.freeze([51, 52, 53]),
+    'GROUND2O.DAT': Object.freeze([29])
+  }),
+  holiday93: Object.freeze({
+    'GROUND1O.DAT': Object.freeze([56, 57, 58, 59]),
+    'GROUND2O.DAT': Object.freeze([29])
+  }),
+  holiday94: Object.freeze({
+    'GROUND1O.DAT': Object.freeze([56, 57, 58, 59]),
+    'GROUND2O.DAT': Object.freeze([29])
+  })
+});
+
+export { DEFAULT_STEEL_SPRITES };
diff --git a/js/util/EventHandler.js b/js/util/EventHandler.js
index 69ea74d2..022237a2 100644
--- a/js/util/EventHandler.js
+++ b/js/util/EventHandler.js
@@ -1,29 +1,42 @@
 class EventHandler {
   constructor () {
     this.handlers = new Set();
+    this._snapshot = [];
+    this._snapshotDirty = true;
   }
 
   // Register a callback (idempotent)
   on (handler) {
     if (typeof handler === 'function' && !this.handlers.has(handler)) {
       this.handlers.add(handler);
+      this._snapshotDirty = true;
     }
   }
 
   // Deregister a callback
   off (handler) {
-    this.handlers.delete(handler);
+    if (this.handlers.delete(handler)) {
+      this._snapshotDirty = true;
+    }
   }
 
   // Remove all callbacks
   dispose () {
-    this.handlers.clear();
+    if (this.handlers.size) {
+      this.handlers.clear();
+      this._snapshotDirty = true;
+    }
+    this._snapshot.length = 0;
   }
 
-  // Run every handler with `arg`.  No `.slice()` → no transient allocations
+  // Run a stable snapshot; mutations during dispatch affect the next trigger.
   trigger (arg) {
-    // snapshot length once to tolerate `off` during iteration without skipping
-    for (const handler of this.handlers) {
+    if (this._snapshotDirty) {
+      this._snapshot = Array.from(this.handlers);
+      this._snapshotDirty = false;
+    }
+    const snapshot = this._snapshot;
+    for (const handler of snapshot) {
       handler(arg);
     }
   }
diff --git a/js/util/LogHandler.js b/js/util/LogHandler.js
index d2e0aab6..b337852f 100644
--- a/js/util/LogHandler.js
+++ b/js/util/LogHandler.js
@@ -1,4 +1,7 @@
-import { getDependency } from '../core/dependencies.js';
+import { getDependency, getAppContext } from '../core/dependencies.js';
+import { recordPerformanceMeasure } from './performanceInstrumentation.js';
+
+const NOOP = () => {};
 
 class Logger {
   constructor(moduleName) {
@@ -6,10 +9,10 @@ class Logger {
   }
 
   _enabled() {
-    return typeof lemmings !== 'undefined' &&
-            lemmings &&
-            lemmings.game &&
-            lemmings.game.showDebug === true;
+    const app = getAppContext();
+    return !!app &&
+            !!app.game &&
+            app.game.showDebug === true;
   }
 
   /** log an info message */
@@ -66,32 +69,28 @@ class BaseLogger {
      * @returns {Function}
      */
   startMeasure(name, devtools = {}) {
-    const app = typeof lemmings !== 'undefined' ? lemmings : null;
+    const app = getAppContext();
     const perfEnabled = !!app &&
             (app.performanceAPI === true || app.perfMetrics === true);
     if (!perfEnabled ||
             typeof performance === 'undefined' ||
             typeof performance.now !== 'function' ||
             typeof performance.measure !== 'function') {
-      return () => {};
+      return NOOP;
     }
     const start = performance.now();
     return () => {
-      try {
-        performance.measure(name, {
-          start,
-          detail: { devtools }
-        });
-      } catch {
-        /* ignored */
-      }
+      recordPerformanceMeasure(name, {
+        start,
+        detail: { devtools }
+      });
     };
   }
 }
 
 function withPerformance(name, devtools = {}, fn) {
   return function(...args) {
-    const app = typeof lemmings !== 'undefined' ? lemmings : null;
+    const app = getAppContext();
     const perfEnabled = !!app &&
             (app.performanceAPI === true || app.perfMetrics === true);
     if (!perfEnabled ||
@@ -104,14 +103,10 @@ function withPerformance(name, devtools = {}, fn) {
     try {
       return fn.apply(this, args);
     } finally {
-      try {
-        performance.measure(name, {
-          start,
-          detail: { devtools }
-        });
-      } catch {
-        /* ignored */
-      }
+      recordPerformanceMeasure(name, {
+        start,
+        detail: { devtools }
+      });
     }
   };
 }
diff --git a/js/util/performanceInstrumentation.js b/js/util/performanceInstrumentation.js
new file mode 100644
index 00000000..9ce76d0e
--- /dev/null
+++ b/js/util/performanceInstrumentation.js
@@ -0,0 +1,52 @@
+const DEFAULT_MEASURE_RETENTION = 120;
+const measureCounts = new Map();
+
+const getPerformanceRef = (performanceRef = null) => (
+  performanceRef || (typeof performance !== 'undefined' ? performance : null)
+);
+
+const canMeasurePerformance = (performanceRef = null) => {
+  const perf = getPerformanceRef(performanceRef);
+  return typeof perf?.now === 'function' && typeof perf?.measure === 'function';
+};
+
+const normalizeRetention = (value) => {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) return DEFAULT_MEASURE_RETENTION;
+  return Math.max(0, Math.trunc(numeric));
+};
+
+const recordPerformanceMeasure = (
+  name,
+  measureOptions = {},
+  { performanceRef = null, retention = DEFAULT_MEASURE_RETENTION } = {}
+) => {
+  const perf = getPerformanceRef(performanceRef);
+  if (typeof perf?.measure !== 'function') return false;
+  try {
+    perf.measure(name, measureOptions);
+    const keep = normalizeRetention(retention);
+    if (keep > 0 && typeof perf.clearMeasures === 'function') {
+      const count = (measureCounts.get(name) || 0) + 1;
+      if (count >= keep) {
+        perf.clearMeasures(name);
+        measureCounts.set(name, 0);
+      } else {
+        measureCounts.set(name, count);
+      }
+    }
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const resetPerformanceMeasureCounts = () => {
+  measureCounts.clear();
+};
+
+export {
+  canMeasurePerformance,
+  recordPerformanceMeasure,
+  resetPerformanceMeasureCounts
+};
diff --git a/js/util/safeObject.js b/js/util/safeObject.js
new file mode 100644
index 00000000..99c90d15
--- /dev/null
+++ b/js/util/safeObject.js
@@ -0,0 +1,67 @@
+const UNSAFE_OBJECT_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+const isUnsafeObjectKey = (key) => UNSAFE_OBJECT_KEYS.has(String(key));
+
+const isPlainObject = (value) => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+};
+
+const createNullObject = () => Object.create(null);
+
+const safeObjectEntries = (value) => {
+  if (!isPlainObject(value)) return [];
+  return Object.entries(value).filter(([key]) => !isUnsafeObjectKey(key));
+};
+
+const cloneSafeObject = (value, depth = 0, maxDepth = 12) => {
+  if (depth > maxDepth) return undefined;
+  if (value === null) return null;
+  const type = typeof value;
+  if (type === 'string' || type === 'boolean') return value;
+  if (type === 'number') return Number.isFinite(value) ? value : undefined;
+  if (Array.isArray(value)) {
+    const out = [];
+    for (let i = 0; i < value.length; i += 1) {
+      const next = cloneSafeObject(value[i], depth + 1, maxDepth);
+      if (next !== undefined) out.push(next);
+    }
+    return out;
+  }
+  if (isPlainObject(value)) {
+    const out = createNullObject();
+    for (const [key, entry] of safeObjectEntries(value)) {
+      const next = cloneSafeObject(entry, depth + 1, maxDepth);
+      if (next !== undefined) out[key] = next;
+    }
+    return out;
+  }
+  return undefined;
+};
+
+const mergeDeepSafe = (target, source) => {
+  const out = createNullObject();
+  for (const [key, value] of safeObjectEntries(target)) {
+    out[key] = value;
+  }
+  for (const [key, value] of safeObjectEntries(source)) {
+    if (isPlainObject(value) && isPlainObject(out[key])) {
+      out[key] = mergeDeepSafe(out[key], value);
+    } else {
+      const cloned = cloneSafeObject(value);
+      if (cloned !== undefined) out[key] = cloned;
+    }
+  }
+  return out;
+};
+
+export {
+  UNSAFE_OBJECT_KEYS,
+  isUnsafeObjectKey,
+  isPlainObject,
+  createNullObject,
+  safeObjectEntries,
+  cloneSafeObject,
+  mergeDeepSafe
+};
diff --git a/js/xbrz/xbrz.js b/js/xbrz/xbrz.js
index 7f3b8466..6d059665 100644
--- a/js/xbrz/xbrz.js
+++ b/js/xbrz/xbrz.js
@@ -63,8 +63,8 @@ class OutputMatrix {
   }
 
   ref (i, j) {
-    i = parseInt(i);
-    j = parseInt(j);
+    i = Number.parseInt(i, 10);
+    j = Number.parseInt(j, 10);
     const rot = matrixRotation[this.nr + i * maxScale + j];
     this.out.position(this.outi + rot.J + rot.I * this.outWidth);
     return this.out;
@@ -352,6 +352,17 @@ function scalePixel (scaler, rotDeg, ker3x3, trg, trgi, trgWidth, blendInfo) {
   }
 }
 
+/**
+ * Scale source pixels into the target buffer for a bounded row range.
+ * @param {2|3|4} scaleSize
+ * @param {number[]} src
+ * @param {number[]} trg
+ * @param {number} srcWidth
+ * @param {number} srcHeight
+ * @param {number} yFirst
+ * @param {number} yLast
+ * @returns {void}
+ */
 export function scaleImage (scaleSize, src, trg, srcWidth, srcHeight, yFirst, yLast) {
   yFirst = Math.max(yFirst, 0);
   yLast = Math.min(yLast, srcHeight);
@@ -506,17 +517,3 @@ export function scaleImage (scaleSize, src, trg, srcWidth, srcHeight, yFirst, yL
     }
   }
 }
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/keybindings.json b/keybindings.json
index 5c1e7e6f..7cb9504c 100644
--- a/keybindings.json
+++ b/keybindings.json
@@ -33,7 +33,7 @@
     "applySkillToSelected": ["KeyK"],
     "toggleDebug": ["Backslash"],
     "toggleShortcutOverlay": ["F1", "Shift+Slash"],
-    "speedDown": ["Minus", "NumpadSubtract", "Alt+Equal", "Alt+NumpadAdd"],     
+    "speedDown": ["Minus", "NumpadSubtract", "Alt+Equal", "Alt+NumpadAdd"],
     "speedDownFast": ["Shift+Minus", "Shift+NumpadSubtract", "Alt+Shift+Equal", "Alt+Shift+NumpadAdd"],
     "speedUp": ["Equal", "NumpadAdd"],
     "speedUpFast": ["Shift+Equal", "Shift+NumpadAdd"],
@@ -47,6 +47,7 @@
     "editorToolTerrain": ["KeyT"],
     "editorToolGadget": ["KeyG"],
     "editorToolTrigger": ["KeyR"],
+    "editorToolMidiFlag": ["KeyM"],
     "editorToolEntrance": ["KeyE"],
     "editorToolExit": ["KeyX"],
     "editorToolSteel": ["KeyF"],
diff --git a/mcp/editorObjectTools.js b/mcp/editorObjectTools.js
new file mode 100644
index 00000000..d2e240a8
--- /dev/null
+++ b/mcp/editorObjectTools.js
@@ -0,0 +1,407 @@
+const createEditorObjectToolHandlers = ({
+  schemas,
+  getSession,
+  getState,
+  callE2E,
+  attachEvents,
+  nudgeWatchPolling
+}) => {
+  const {
+    EditorApplySchema,
+    ObjectsDeleteSchema,
+    ObjectsListSchema,
+    ObjectsPlaceSchema,
+    ObjectsUpdateSchema
+  } = schemas;
+
+  const getEditorLevelFromState = (state) => state?.editor?.session?.level ?? null;
+
+  const getEditorRevisionFromState = (state) => {
+    const revision = state?.editor?.history?.cursor;
+    return Number.isFinite(revision) ? Number(revision) : null;
+  };
+
+  const getEditorListByKind = (level, kind) => {
+    if (!level) return null;
+    if (kind === 'terrain') return Array.isArray(level.terrains) ? level.terrains : [];
+    if (kind === 'gadget') return Array.isArray(level.gadgets) ? level.gadgets : [];
+    if (kind === 'steel') return Array.isArray(level.steel) ? level.steel : [];
+    return null;
+  };
+
+  const normalizeEditorBBox = (bbox) => {
+    if (!bbox || !Number.isFinite(bbox.x) || !Number.isFinite(bbox.y)) return null;
+    const width = Number.isFinite(bbox.width) ? bbox.width : bbox.w;
+    const height = Number.isFinite(bbox.height) ? bbox.height : bbox.h;
+    if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) return null;
+    return {
+      x: Number(bbox.x),
+      y: Number(bbox.y),
+      width: Number(width),
+      height: Number(height)
+    };
+  };
+
+  const editorBoundsIntersect = (a, b) => (
+    a.x < b.x + b.width &&
+    a.x + a.width > b.x &&
+    a.y < b.y + b.height &&
+    a.y + a.height > b.y
+  );
+
+  const getEditorObjectBounds = (entry, kind) => {
+    const props = entry?.props || {};
+    const x = Number.isFinite(props.X) ? props.X : (Number.isFinite(props.x) ? props.x : 0);
+    const y = Number.isFinite(props.Y) ? props.Y : (Number.isFinite(props.y) ? props.y : 0);
+    if (kind === 'steel') {
+      const width = Number.isFinite(props.WIDTH) ? props.WIDTH : 1;
+      const height = Number.isFinite(props.HEIGHT) ? props.HEIGHT : 1;
+      return { x, y, width, height };
+    }
+    return { x, y, width: 1, height: 1 };
+  };
+
+  const buildEditorObjectId = (kind, index, entry) => (
+    entry?.uid ? `${kind}:${entry.uid}` : `${kind}:#${index}`
+  );
+
+  const buildEditorObjectRecord = (kind, index, entry, fields = 'compact') => {
+    const props = entry?.props || {};
+    const bounds = getEditorObjectBounds(entry, kind);
+    const record = {
+      id: buildEditorObjectId(kind, index, entry),
+      kind,
+      index,
+      uid: entry?.uid || null,
+      piece: Number.isFinite(props.PIECE) ? props.PIECE : null,
+      x: bounds.x,
+      y: bounds.y,
+      width: bounds.width,
+      height: bounds.height
+    };
+    if (fields === 'full') {
+      record.entry = entry ? JSON.parse(JSON.stringify(entry)) : null;
+    }
+    record._hash = JSON.stringify({
+      uid: record.uid,
+      index: record.index,
+      props,
+      order: Array.isArray(entry?.order) ? entry.order : []
+    });
+    return record;
+  };
+
+  const collectEditorObjectRecords = (level, kind, fields) => {
+    const kinds = kind === 'all' ? ['terrain', 'gadget', 'steel'] : [kind];
+    const records = [];
+    for (const oneKind of kinds) {
+      const list = getEditorListByKind(level, oneKind) || [];
+      for (let index = 0; index < list.length; index += 1) {
+        records.push(buildEditorObjectRecord(oneKind, index, list[index], fields));
+      }
+    }
+    return records;
+  };
+
+  const resolveEditorObjectRef = (level, ref) => {
+    const requestedKind = ref?.kind;
+    const kinds = requestedKind && requestedKind !== 'all'
+      ? [requestedKind]
+      : ['terrain', 'gadget', 'steel'];
+    if (Number.isFinite(ref?.index)) {
+      if (!requestedKind || requestedKind === 'all') return null;
+      const list = getEditorListByKind(level, requestedKind);
+      const index = Math.trunc(ref.index);
+      if (!list || index < 0 || index >= list.length) return null;
+      const entry = list[index];
+      return {
+        kind: requestedKind,
+        index,
+        uid: entry?.uid || null
+      };
+    }
+    if (typeof ref?.uid === 'string' && ref.uid) {
+      for (const kind of kinds) {
+        const list = getEditorListByKind(level, kind);
+        if (!list) continue;
+        const index = list.findIndex((entry) => entry?.uid === ref.uid);
+        if (index >= 0) {
+          return {
+            kind,
+            index,
+            uid: ref.uid
+          };
+        }
+      }
+    }
+    return null;
+  };
+
+  const cacheEditorListSnapshot = (session, queryKey, revision, records) => {
+    if (!session.editorObjectListCache) {
+      session.editorObjectListCache = new Map();
+    }
+    const map = new Map(records.map((record) => [record.id, record._hash]));
+    session.editorObjectListCache.delete(queryKey);
+    session.editorObjectListCache.set(queryKey, { revision, map });
+    while (session.editorObjectListCache.size > 32) {
+      const oldestKey = session.editorObjectListCache.keys().next().value;
+      session.editorObjectListCache.delete(oldestKey);
+    }
+  };
+
+  const buildEditorListDelta = (previous, current, sinceRevision, toRevision) => {
+    if (!previous || previous.revision !== sinceRevision) {
+      return {
+        available: false,
+        reason: 'stale_or_missing_revision',
+        baseRevision: sinceRevision,
+        toRevision
+      };
+    }
+    const added = [];
+    const removed = [];
+    const updated = [];
+    for (const [id, hash] of current.entries()) {
+      if (!previous.map.has(id)) {
+        added.push(id);
+      } else if (previous.map.get(id) !== hash) {
+        updated.push(id);
+      }
+    }
+    for (const id of previous.map.keys()) {
+      if (!current.has(id)) {
+        removed.push(id);
+      }
+    }
+    return {
+      available: true,
+      baseRevision: sinceRevision,
+      toRevision,
+      added,
+      removed,
+      updated
+    };
+  };
+
+  const runEditorApply = async (session, ops, options = {}) => {
+    const result = await callE2E(session, 'editorApply', ops || [], {
+      atomic: options.atomic,
+      dryRun: options.dryRun,
+      history: options.history,
+      preview: options.preview,
+      validate: options.validate,
+      returnState: options.returnState
+    });
+    if (!result.ok) {
+      return attachEvents(session, {
+        ok: false,
+        reason: 'harness_unavailable',
+        error: result.error || null
+      });
+    }
+
+    const payload = result.value || {};
+    if (!payload.ok) {
+      return attachEvents(session, payload);
+    }
+
+    nudgeWatchPolling(session);
+
+    const resources = [];
+    if (Array.isArray(payload.resources)) {
+      for (const resource of payload.resources) {
+        if (!resource) continue;
+        const encoding = resource.encoding || 'text';
+        const data = resource.data || '';
+        const bytes = encoding === 'base64'
+          ? Buffer.from(data, 'base64')
+          : Buffer.from(data, 'utf8');
+        const mimeType = resource.mimeType || 'application/octet-stream';
+        const stored = session.resources.put({
+          sessionId: session.id,
+          bytes,
+          mimeType,
+          meta: resource.meta || { kind: 'resource', name: resource.name || '' }
+        });
+        resources.push({
+          uri: stored?.uri || null,
+          mimeType,
+          name: resource.name || null,
+          sizeBytes: stored?.sizeBytes ?? null,
+          meta: resource.meta || null
+        });
+      }
+    }
+
+    return attachEvents(session, {
+      ok: true,
+      results: Array.isArray(payload.results) ? payload.results : [],
+      state: payload.state ?? null,
+      resources
+    });
+  };
+
+  const editorApplyTool = async (args) => {
+    const parsed = EditorApplySchema.parse(args || {});
+    const session = getSession(parsed.sessionId);
+    return runEditorApply(session, parsed.ops || [], {
+      atomic: parsed.atomic,
+      dryRun: parsed.dryRun,
+      history: parsed.history,
+      preview: parsed.preview,
+      validate: parsed.validate,
+      returnState: parsed.returnState
+    });
+  };
+
+  const listObjectsTool = async (args) => {
+    const parsed = ObjectsListSchema.parse(args || {});
+    const session = getSession(parsed.sessionId);
+    const state = await getState(session);
+    const level = getEditorLevelFromState(state);
+    if (!level) {
+      return attachEvents(session, {
+        ok: false,
+        reason: 'not_in_editor_mode'
+      });
+    }
+
+    const kind = parsed.kind || 'all';
+    const fields = parsed.fields || 'compact';
+    const bbox = normalizeEditorBBox(parsed.bbox);
+    let records = collectEditorObjectRecords(level, kind, fields);
+    if (bbox) {
+      records = records.filter((record) => editorBoundsIntersect(record, bbox));
+    }
+    const totalCount = records.length;
+    const page = Number.isFinite(parsed.page) ? Math.max(0, parsed.page) : 0;
+    const pageSize = Number.isFinite(parsed.pageSize) ? parsed.pageSize : 100;
+    const start = page * pageSize;
+    const pageRecords = records.slice(start, start + pageSize);
+    const revision = getEditorRevisionFromState(state);
+    const queryKey = JSON.stringify({ kind, fields, bbox: bbox || null });
+    const currentSnapshot = new Map(records.map((record) => [record.id, record._hash]));
+    let delta = null;
+    if (Number.isFinite(parsed.sinceRevision)) {
+      const previous = session.editorObjectListCache?.get(queryKey) || null;
+      delta = buildEditorListDelta(
+        previous,
+        currentSnapshot,
+        parsed.sinceRevision,
+        revision
+      );
+    }
+    cacheEditorListSnapshot(session, queryKey, revision, records);
+
+    return attachEvents(session, {
+      ok: true,
+      revision,
+      kind,
+      page,
+      pageSize,
+      totalCount,
+      entries: pageRecords.map((record) => {
+        const { _hash, ...rest } = record;
+        return rest;
+      }),
+      delta
+    });
+  };
+
+  const placeObjectsTool = async (args) => {
+    const parsed = ObjectsPlaceSchema.parse(args || {});
+    const session = getSession(parsed.sessionId);
+    const ops = parsed.objects.map((item, index) => ({
+      opId: `objects.place.${index}`,
+      type: 'entry.add',
+      args: {
+        kind: item.kind,
+        props: item.props,
+        piece: item.piece,
+        x: item.x,
+        y: item.y,
+        width: item.width,
+        height: item.height,
+        insert: Number.isFinite(item.insertIndex) ? { index: item.insertIndex } : undefined
+      }
+    }));
+    return runEditorApply(session, ops, parsed.options || {});
+  };
+
+  const updateObjectsTool = async (args) => {
+    const parsed = ObjectsUpdateSchema.parse(args || {});
+    const session = getSession(parsed.sessionId);
+    const state = await getState(session);
+    const level = getEditorLevelFromState(state);
+    if (!level) {
+      return attachEvents(session, {
+        ok: false,
+        reason: 'not_in_editor_mode'
+      });
+    }
+    const ops = [];
+    for (let index = 0; index < parsed.updates.length; index += 1) {
+      const update = parsed.updates[index];
+      const resolvedRef = resolveEditorObjectRef(level, update.ref);
+      if (!resolvedRef) {
+        return attachEvents(session, {
+          ok: false,
+          reason: 'invalid_ref',
+          index
+        });
+      }
+      ops.push({
+        opId: `objects.update.${index}`,
+        type: 'entry.update',
+        args: {
+          ref: resolvedRef,
+          set: update.set || {},
+          unset: update.unset || []
+        }
+      });
+    }
+    return runEditorApply(session, ops, parsed.options || {});
+  };
+
+  const deleteObjectsTool = async (args) => {
+    const parsed = ObjectsDeleteSchema.parse(args || {});
+    const session = getSession(parsed.sessionId);
+    const state = await getState(session);
+    const level = getEditorLevelFromState(state);
+    if (!level) {
+      return attachEvents(session, {
+        ok: false,
+        reason: 'not_in_editor_mode'
+      });
+    }
+    const refs = [];
+    for (let index = 0; index < parsed.refs.length; index += 1) {
+      const resolvedRef = resolveEditorObjectRef(level, parsed.refs[index]);
+      if (!resolvedRef) {
+        return attachEvents(session, {
+          ok: false,
+          reason: 'invalid_ref',
+          index
+        });
+      }
+      refs.push(resolvedRef);
+    }
+    return runEditorApply(session, [{
+      opId: 'objects.delete',
+      type: 'entry.remove',
+      args: { refs }
+    }], parsed.options || {});
+  };
+
+
+  return {
+    editorApplyTool,
+    listObjectsTool,
+    placeObjectsTool,
+    updateObjectsTool,
+    deleteObjectsTool
+  };
+};
+
+export { createEditorObjectToolHandlers };
diff --git a/mcp/eventEnvelope.js b/mcp/eventEnvelope.js
new file mode 100644
index 00000000..9bf1c511
--- /dev/null
+++ b/mcp/eventEnvelope.js
@@ -0,0 +1,50 @@
+/**
+ * Attach queued event envelope data to an MCP tool payload.
+ * Minimal mode strips agent-originated events to reduce chatter.
+ *
+ * @param {any} session
+ * @param {any} payload
+ * @returns {any}
+ */
+const attachEvents = (session, payload) => {
+  if (!session) return payload;
+  if (!payload || typeof payload !== 'object') return payload;
+  if (!session.events || typeof session.events.drain !== 'function') return payload;
+  const mode = session.eventsMode || 'minimal';
+  if (mode === 'none') return payload;
+
+  const envelope = session.events.drain(undefined, {
+    updateCursor: true,
+    includeHumanSummary: mode !== 'none'
+  });
+  if (!envelope) return payload;
+
+  if (mode === 'minimal') {
+    envelope.events = (envelope.events || [])
+      .filter((event) => event && event.source !== 'agent')
+      .map((event) => ({
+        source: event.source,
+        type: event.type,
+        tickIndex: event.tickIndex ?? null,
+        summary: event.summary ?? null,
+        ...(Array.isArray(event.resourceUris) && event.resourceUris.length
+          ? { resourceUris: event.resourceUris }
+          : {})
+      }));
+    if (!envelope.events.length) {
+      delete envelope.events;
+    }
+    if (!envelope.humanSummary) {
+      delete envelope.humanSummary;
+    }
+  }
+
+  const hasEvents = Array.isArray(envelope.events) && envelope.events.length > 0;
+  const hasSummary = typeof envelope.humanSummary === 'string' && envelope.humanSummary.length > 0;
+  if (!hasEvents && !hasSummary) return payload;
+
+  payload.events = envelope;
+  return payload;
+};
+
+export { attachEvents };
diff --git a/mcp/eventQueue.js b/mcp/eventQueue.js
new file mode 100644
index 00000000..065291fa
--- /dev/null
+++ b/mcp/eventQueue.js
@@ -0,0 +1,332 @@
+import crypto from 'node:crypto';
+
+const nowIso = () => new Date().toISOString();
+const DEFAULT_MAX_EVENTS = 1000;
+const MAX_MAX_EVENTS = 10000;
+const DEFAULT_MAX_HUMAN_SUMMARY_PARTS = 24;
+const MIN_HUMAN_SUMMARY_PARTS = 0;
+const MAX_HUMAN_SUMMARY_PARTS = 2048;
+
+/**
+ * Normalize capacity-like inputs to stable integer bounds.
+ */
+const normalizeCapacity = (value, fallback, min = 0) => {
+  let numeric;
+  try {
+    numeric = Number(value);
+  } catch {
+    numeric = Number.NaN;
+  }
+  const candidate = Number.isFinite(numeric) ? Math.trunc(numeric) : NaN;
+  if (!Number.isFinite(candidate) || candidate < min) return fallback;
+  return candidate;
+};
+
+const makeId = (bytes = 9) => crypto.randomBytes(bytes)
+  .toString('base64')
+  .replace(/\+/g, '-')
+  .replace(/\//g, '_')
+  .replace(/=+$/g, '');
+
+/**
+ * Fallback deep clone used when structuredClone/JSON cloning is unavailable.
+ * Supports circular references via a WeakMap memo table.
+ *
+ * @param {any} value
+ * @param {WeakMap<object, any>} [seen]
+ * @returns {any}
+ */
+const cloneEventValueFallback = (value, seen = new WeakMap()) => {
+  if (value == null || typeof value !== 'object') return value;
+  if (typeof value === 'function') return value;
+  if (seen.has(value)) return seen.get(value);
+
+  if (Buffer.isBuffer(value)) {
+    const copy = Buffer.from(value);
+    seen.set(value, copy);
+    return copy;
+  }
+  if (value instanceof Date) {
+    const copy = new Date(value.getTime());
+    seen.set(value, copy);
+    return copy;
+  }
+  if (value instanceof RegExp) {
+    const copy = new RegExp(value.source, value.flags);
+    seen.set(value, copy);
+    return copy;
+  }
+  if (value instanceof ArrayBuffer) {
+    const copy = value.slice(0);
+    seen.set(value, copy);
+    return copy;
+  }
+  if (value instanceof DataView) {
+    const buffer = value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength);
+    const copy = new DataView(buffer);
+    seen.set(value, copy);
+    return copy;
+  }
+  if (ArrayBuffer.isView(value)) {
+    const copy = new value.constructor(value);
+    seen.set(value, copy);
+    return copy;
+  }
+  if (value instanceof Map) {
+    const copy = new Map();
+    seen.set(value, copy);
+    for (const [entryKey, entryValue] of value.entries()) {
+      copy.set(
+        cloneEventValueFallback(entryKey, seen),
+        cloneEventValueFallback(entryValue, seen)
+      );
+    }
+    return copy;
+  }
+  if (value instanceof Set) {
+    const copy = new Set();
+    seen.set(value, copy);
+    for (const entry of value.values()) {
+      copy.add(cloneEventValueFallback(entry, seen));
+    }
+    return copy;
+  }
+  if (Array.isArray(value)) {
+    const copy = new Array(value.length);
+    seen.set(value, copy);
+    for (let i = 0; i < value.length; i += 1) {
+      copy[i] = cloneEventValueFallback(value[i], seen);
+    }
+    return copy;
+  }
+
+  const copy = {};
+  seen.set(value, copy);
+  for (const key of Object.keys(value)) {
+    copy[key] = cloneEventValueFallback(value[key], seen);
+  }
+  return copy;
+};
+
+/**
+ * Clone event payloads so queue entries stay immutable from caller mutations.
+ *
+ * @param {any} value
+ * @returns {any}
+ */
+const cloneEventValue = (value) => {
+  if (value == null || typeof value !== 'object') return value;
+  if (typeof structuredClone === 'function') {
+    try {
+      return structuredClone(value);
+    } catch {
+      // fall through
+    }
+  }
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    try {
+      return cloneEventValueFallback(value);
+    } catch {
+      return null;
+    }
+  }
+};
+
+class EventQueue {
+  /**
+   * @param {Object} options
+   * @param {number} [options.maxEvents=1000] - Maximum number of events retained in the queue.
+   * @param {number} [options.maxHumanSummaryParts=24] - Max human summary segments retained.
+   * @param {() => string} [options.idFactory=makeId] - Unique id factory for event entries.
+   * @param {() => string} [options.timeFactory=nowIso] - Timestamp factory for event entries.
+   */
+  constructor({
+    maxEvents = DEFAULT_MAX_EVENTS,
+    maxHumanSummaryParts = DEFAULT_MAX_HUMAN_SUMMARY_PARTS,
+    idFactory = makeId,
+    timeFactory = nowIso
+  } = {}) {
+    this.maxEvents = Math.min(
+      MAX_MAX_EVENTS,
+      Math.max(1, normalizeCapacity(maxEvents, DEFAULT_MAX_EVENTS, 1))
+    );
+    this.idFactory = typeof idFactory === 'function' ? idFactory : makeId;
+    this.timeFactory = typeof timeFactory === 'function' ? timeFactory : nowIso;
+    this.events = new Array(this.maxEvents);
+    this.head = 0;
+    this.size = 0;
+    this.seq = 0;
+    this.lastDelivered = 0;
+    // Ring-buffer over summary segments to avoid O(n) shift churn under chatty input.
+    this.humanSummaryParts = [];
+    this.humanSummaryStart = 0;
+    this.maxHumanSummaryParts = Math.min(
+      MAX_HUMAN_SUMMARY_PARTS,
+      normalizeCapacity(
+        maxHumanSummaryParts,
+        DEFAULT_MAX_HUMAN_SUMMARY_PARTS,
+        MIN_HUMAN_SUMMARY_PARTS
+      )
+    );
+  }
+
+  /**
+   * Add a new event to the queue and keep snapshots of mutable payloads.
+   * @param {object} entry
+   * @param {string} entry.source
+   * @param {string} entry.type
+   * @param {string} [entry.summary]
+   * @param {*} [entry.data]
+   * @param {string[]} [entry.resourceUris]
+   * @param {number} [entry.tickIndex]
+   * @returns {object}
+   */
+  add({ source, type, summary, data, resourceUris, tickIndex } = {}) {
+    const eventData = cloneEventValue(data);
+    const eventResourceUris = Array.isArray(resourceUris) ? resourceUris.slice() : undefined;
+    const normalizedSummary = summary == null ? '' : String(summary);
+    const entry = {
+      id: this.idFactory(),
+      source,
+      type,
+      tickIndex: Number.isFinite(tickIndex) ? tickIndex : null,
+      time: this.timeFactory(),
+      summary: normalizedSummary,
+      data: eventData,
+      resourceUris: eventResourceUris
+    };
+    this.seq += 1;
+    entry.seq = this.seq;
+
+    let index;
+    if (this.size < this.maxEvents) {
+      index = (this.head + this.size) % this.maxEvents;
+      this.size += 1;
+    } else {
+      index = this.head;
+      this.head = (this.head + 1) % this.maxEvents;
+    }
+    this.events[index] = entry;
+
+    const summaryCap = Math.min(
+      MAX_HUMAN_SUMMARY_PARTS,
+      normalizeCapacity(
+        this.maxHumanSummaryParts,
+        DEFAULT_MAX_HUMAN_SUMMARY_PARTS,
+        MIN_HUMAN_SUMMARY_PARTS
+      )
+    );
+    this.maxHumanSummaryParts = summaryCap;
+    if (summaryCap <= 0 && this.humanSummaryParts.length) {
+      this.humanSummaryParts.length = 0;
+      this.humanSummaryStart = 0;
+    }
+    if (summaryCap > 0 && this.humanSummaryParts.length > summaryCap) {
+      if (this.humanSummaryStart === 0) {
+        this.humanSummaryParts = this.humanSummaryParts.slice(-summaryCap);
+      } else {
+        const ordered = new Array(this.humanSummaryParts.length);
+        for (let i = 0; i < this.humanSummaryParts.length; i += 1) {
+          ordered[i] = this.humanSummaryParts[
+            (this.humanSummaryStart + i) % this.humanSummaryParts.length
+          ];
+        }
+        this.humanSummaryParts = ordered.slice(-summaryCap);
+      }
+      this.humanSummaryStart = 0;
+    }
+
+    if (source === 'human' && normalizedSummary) {
+      if (summaryCap <= 0) {
+        return entry;
+      }
+      if (this.humanSummaryParts.length < summaryCap) {
+        this.humanSummaryParts.push(normalizedSummary);
+      } else {
+        this.humanSummaryParts[this.humanSummaryStart] = normalizedSummary;
+        this.humanSummaryStart = (this.humanSummaryStart + 1) % summaryCap;
+      }
+    }
+    return entry;
+  }
+
+  /**
+   * Normalize an untrusted client cursor into the queue-owned sequence range.
+   * @param {string|number|undefined} after
+   * @returns {number}
+   */
+  normalizeCursor(after) {
+    const parsedAfter = Number(after);
+    const requested = Number.isFinite(parsedAfter) ? Math.trunc(parsedAfter) : this.lastDelivered;
+    if (this.size <= 0) return this.lastDelivered;
+    const oldest = this.events[this.head];
+    const newest = this.events[(this.head + this.size - 1) % this.maxEvents];
+    if (!oldest || !newest) return this.lastDelivered;
+    if (requested < oldest.seq - 1) return oldest.seq - 1;
+    if (requested > newest.seq) return newest.seq;
+    return requested;
+  }
+
+  /**
+   * Drain queued events newer than `after` into a transport envelope.
+   * @param {string|number|undefined} after
+   * @param {object} [options]
+   * @param {boolean} [options.updateCursor=true] - Whether to advance last delivered cursor.
+   * @param {boolean} [options.includeHumanSummary=true] - Whether to include human summary.
+   * @returns {{cursor:string,events:object[],humanSummary?:string}|null}
+   */
+  drain(after, { updateCursor = true, includeHumanSummary = true } = {}) {
+    if (this.size <= 0) return null;
+    const oldest = this.events[this.head];
+    const newest = this.events[(this.head + this.size - 1) % this.maxEvents];
+    if (!oldest || !newest) return null;
+    const afterSeq = this.normalizeCursor(after);
+    if (afterSeq >= newest.seq) return null;
+
+    const startSeq = Math.max(afterSeq + 1, oldest.seq);
+    const startOffset = Math.max(0, startSeq - oldest.seq);
+    if (startOffset >= this.size) return null;
+
+    const events = [];
+    let cursorSeq = afterSeq;
+    for (let offset = startOffset; offset < this.size; offset += 1) {
+      const event = this.events[(this.head + offset) % this.maxEvents];
+      if (!event) continue;
+      cursorSeq = event.seq;
+      const { seq, ...rest } = event;
+      events.push(rest);
+    }
+    if (!events.length) return null;
+
+    const cursor = String(cursorSeq);
+    if (updateCursor) {
+      this.lastDelivered = Number(cursor);
+    }
+    const payload = {
+      cursor,
+      events
+    };
+    if (includeHumanSummary && this.humanSummaryParts.length) {
+      if (this.humanSummaryStart === 0) {
+        payload.humanSummary = this.humanSummaryParts.join('; ');
+      } else {
+        const ordered = new Array(this.humanSummaryParts.length);
+        for (let i = 0; i < this.humanSummaryParts.length; i += 1) {
+          ordered[i] = this.humanSummaryParts[
+            (this.humanSummaryStart + i) % this.humanSummaryParts.length
+          ];
+        }
+        payload.humanSummary = ordered.join('; ');
+      }
+      if (updateCursor) {
+        this.humanSummaryParts.length = 0;
+        this.humanSummaryStart = 0;
+      }
+    }
+    return payload;
+  }
+}
+
+export { EventQueue };
diff --git a/mcp/gameTools.js b/mcp/gameTools.js
new file mode 100644
index 00000000..a788db45
--- /dev/null
+++ b/mcp/gameTools.js
@@ -0,0 +1,287 @@
+const createGameToolHandlers = ({
+  schemas,
+  getSession,
+  getState,
+  getTickIndex,
+  callE2E,
+  attachEvents,
+  nudgeWatchPolling,
+  ensureGameFocus,
+  pressAction,
+  pressKey,
+  normalizeKeyToken,
+  skillActions,
+  skillIndexByName
+}) => {
+  const {
+    InputActionSchema,
+    InputKeysSchema,
+    LemmingSelectSchema,
+    SkillApplySchema,
+    TimeSchema,
+    TimeStepSchema
+  } = schemas;
+  const SKILL_ACTIONS = skillActions;
+  const SKILL_INDEX_BY_NAME = skillIndexByName;
+
+  const pauseTime = async (args) => {
+    const { sessionId } = TimeSchema.parse(args || {});
+    const session = getSession(sessionId);
+    const result = await callE2E(session, 'pause');
+    if (result.ok && result.value) {
+      nudgeWatchPolling(session);
+    }
+    const tickIndex = await getTickIndex(session);
+    return attachEvents(session, {
+      ok: !!result.ok && !!result.value,
+      tickIndex
+    });
+  };
+
+  const resumeTime = async (args) => {
+    const { sessionId } = TimeSchema.parse(args || {});
+    const session = getSession(sessionId);
+    const result = await callE2E(session, 'resume');
+    if (result.ok && result.value) {
+      nudgeWatchPolling(session);
+    }
+    const tickIndex = await getTickIndex(session);
+    return attachEvents(session, {
+      ok: !!result.ok && !!result.value,
+      tickIndex
+    });
+  };
+
+  const stepTime = async (args) => {
+    const { sessionId, count, ensurePaused } = TimeStepSchema.parse(args || {});
+    const session = getSession(sessionId);
+    if (ensurePaused !== false) {
+      await callE2E(session, 'pause');
+    }
+    const tickIndexBefore = await getTickIndex(session);
+    const result = await callE2E(session, 'step', count);
+    if (result.ok && result.value) {
+      nudgeWatchPolling(session);
+    }
+    const tickIndexAfter = await getTickIndex(session);
+    return attachEvents(session, {
+      ok: !!result.ok && !!result.value,
+      tickIndexBefore,
+      tickIndexAfter
+    });
+  };
+
+
+  const centerViewOnLemming = async (session, lemmingId) => {
+    const result = await callE2E(session, 'centerViewOnLemming', lemmingId);
+    return !!(result.ok && result.value);
+  };
+
+  const selectLemmingTool = async (args) => {
+    const { sessionId, lemmingId, alsoCenterView, confirm } = LemmingSelectSchema.parse(args || {});
+    const session = getSession(sessionId);
+    const result = await callE2E(session, 'selectLemmingById', lemmingId);
+    if (!result.ok || !result.value) {
+      const state = await getState(session);
+      const entry = state?.game?.lemmings?.[lemmingId] || null;
+      let reason = 'harness_unavailable';
+      if (entry) {
+        if (entry.removed) reason = 'removed';
+        else if (entry.disabled) reason = 'disabled';
+        else reason = 'not_found';
+      } else {
+        reason = 'not_found';
+      }
+      return attachEvents(session, {
+        ok: false,
+        lemmingId,
+        reason
+      });
+    }
+
+    if (alsoCenterView) {
+      await centerViewOnLemming(session, lemmingId);
+    }
+    nudgeWatchPolling(session);
+
+    let selectedNow = null;
+    if (confirm !== false) {
+      const state = await getState(session);
+      selectedNow = state?.game?.lemmingManager?.selectedIndex ?? null;
+    }
+
+    return attachEvents(session, {
+      ok: true,
+      lemmingId,
+      selectedNow
+    });
+  };
+
+  const applySkillTool = async (args) => {
+    const { sessionId, skill, lemmingId, ensurePaused, requireAvailable, postStep, verify } =
+      SkillApplySchema.parse(args || {});
+    const session = getSession(sessionId);
+    if (ensurePaused !== false) {
+      await callE2E(session, 'pause');
+    }
+
+    let tickIndexBefore = null;
+    let tickIndexAfter = null;
+    let beforeState = null;
+    if (verify !== false || requireAvailable) {
+      beforeState = await getState(session);
+      tickIndexBefore = beforeState?.game?.timer?.tickIndex ?? null;
+    }
+
+    const action = SKILL_ACTIONS[skill];
+    if (!action) {
+      return attachEvents(session, { ok: false, reason: 'unknown_skill', skill });
+    }
+
+    if (requireAvailable) {
+      const skills = beforeState?.game?.skills || null;
+      const skillIndex = SKILL_INDEX_BY_NAME[skill];
+      const available = !!skills?.cheatMode || (Number.isFinite(skillIndex)
+        && Array.isArray(skills?.skills)
+        && skills.skills[skillIndex] > 0);
+      if (!available) {
+        return attachEvents(session, { ok: false, reason: 'no_skill_remaining', skill });
+      }
+    }
+
+    if (Number.isFinite(lemmingId)) {
+      const selectResult = await callE2E(session, 'selectLemmingById', lemmingId);
+      if (!selectResult.ok || !selectResult.value) {
+        return attachEvents(session, {
+          ok: false,
+          skill,
+          lemmingIdAppliedTo: lemmingId,
+          reason: 'select_failed'
+        });
+      }
+    }
+
+    const selectKey = await pressAction(session, action, 1);
+    if (!selectKey.ok) {
+      return attachEvents(session, { ok: false, reason: 'missing_binding', skill, action });
+    }
+    const applyKey = await pressAction(session, 'applySkillToSelected', 1);
+    if (!applyKey.ok) {
+      return attachEvents(session, { ok: false, reason: 'missing_binding', action: 'applySkillToSelected' });
+    }
+
+    const steps = Number.isFinite(postStep) ? Math.trunc(postStep) : 1;
+    if (steps > 0) {
+      await callE2E(session, 'step', steps);
+    }
+
+    let verification = null;
+    let lemmingIdAppliedTo = lemmingId ?? null;
+    if (verify !== false) {
+      const afterState = await getState(session);
+      tickIndexAfter = afterState?.game?.timer?.tickIndex ?? null;
+      const selectedId = afterState?.game?.lemmingManager?.selectedIndex ?? null;
+      lemmingIdAppliedTo = Number.isFinite(lemmingIdAppliedTo) ? lemmingIdAppliedTo : selectedId;
+      const beforeLem = lemmingIdAppliedTo != null
+        ? beforeState?.game?.lemmings?.[lemmingIdAppliedTo] || null
+        : null;
+      const afterLem = lemmingIdAppliedTo != null
+        ? afterState?.game?.lemmings?.[lemmingIdAppliedTo] || null
+        : null;
+      const changedFields = [];
+      let applied = false;
+      if (beforeLem && afterLem) {
+        if (skill === 'climber' && !beforeLem.canClimb && afterLem.canClimb) {
+          applied = true;
+          changedFields.push('canClimb');
+        } else if (skill === 'floater' && !beforeLem.hasParachute && afterLem.hasParachute) {
+          applied = true;
+          changedFields.push('hasParachute');
+        } else if (skill === 'bomber' && !beforeLem.countdownActive && afterLem.countdownActive) {
+          applied = true;
+          changedFields.push('countdownActive');
+        } else if (beforeLem.actionType !== afterLem.actionType) {
+          applied = true;
+          changedFields.push('actionType');
+        }
+      }
+      verification = {
+        applied,
+        changedFields
+      };
+    }
+
+    nudgeWatchPolling(session);
+    return attachEvents(session, {
+      ok: true,
+      skill,
+      lemmingIdAppliedTo,
+      tickIndexBefore,
+      tickIndexAfter,
+      verification
+    });
+  };
+
+  const inputActionTool = async (args) => {
+    const { sessionId, action, repeat } = InputActionSchema.parse(args || {});
+    const session = getSession(sessionId);
+    const response = await pressAction(session, action, repeat || 1);
+    if (response.ok) {
+      nudgeWatchPolling(session);
+    }
+    return attachEvents(session, response);
+  };
+
+  const inputKeysTool = async (args) => {
+    const { sessionId, keys, repeat, events } = InputKeysSchema.parse(args || {});
+    const session = getSession(sessionId);
+    await ensureGameFocus(session);
+    let injected = 0;
+
+    if (Array.isArray(keys) && keys.length) {
+      const count = repeat || 1;
+      for (let i = 0; i < count; i += 1) {
+        for (const key of keys) {
+          await pressKey(session, key);
+          injected += 1;
+        }
+      }
+    } else if (Array.isArray(events)) {
+      for (const event of events) {
+        const key = normalizeKeyToken(event.key);
+        if (event.type === 'down') {
+          await session.page.keyboard.down(key);
+        } else if (event.type === 'up') {
+          await session.page.keyboard.up(key);
+        } else {
+          await session.page.keyboard.press(key);
+        }
+        injected += 1;
+      }
+    }
+
+    if (injected) {
+      session.events.add({
+        source: 'agent',
+        type: 'input',
+        summary: `keys:${injected}`
+      });
+      nudgeWatchPolling(session);
+    }
+
+    return attachEvents(session, { ok: true, eventsInjected: injected });
+  };
+
+
+  return {
+    pauseTime,
+    resumeTime,
+    stepTime,
+    selectLemmingTool,
+    applySkillTool,
+    inputActionTool,
+    inputKeysTool
+  };
+};
+
+export { createGameToolHandlers };
diff --git a/mcp/lemmingSummary.js b/mcp/lemmingSummary.js
new file mode 100644
index 00000000..97c578a5
--- /dev/null
+++ b/mcp/lemmingSummary.js
@@ -0,0 +1,162 @@
+/**
+ * Convert arbitrary numeric-like values to finite numbers.
+ * Returns null for invalid or non-coercible values.
+ *
+ * @param {unknown} value
+ * @returns {number|null}
+ */
+const toFiniteNumber = (value) => {
+  try {
+    const numeric = Number(value);
+    return Number.isFinite(numeric) ? numeric : null;
+  } catch {
+    return null;
+  }
+};
+
+const withinRect = (lem, rect) => {
+  if (!rect) return true;
+  const x = toFiniteNumber(rect.x);
+  const y = toFiniteNumber(rect.y);
+  const width = toFiniteNumber(rect.w ?? rect.width);
+  const height = toFiniteNumber(rect.h ?? rect.height);
+  if (!Number.isFinite(x) || !Number.isFinite(y)) return true;
+  if (!Number.isFinite(width) || !Number.isFinite(height)) return true;
+  if (width <= 0 || height <= 0) return true;
+  return (
+    lem.x >= x &&
+    lem.x <= x + width &&
+    lem.y >= y &&
+    lem.y <= y + height
+  );
+};
+
+const compareTopCandidatePriority = (left, right) => {
+  const leftCountdown = left?.countdownActive ? 1 : 0;
+  const rightCountdown = right?.countdownActive ? 1 : 0;
+  if (leftCountdown !== rightCountdown) return rightCountdown - leftCountdown;
+  const leftX = Number.isFinite(left?.x) ? left.x : -Infinity;
+  const rightX = Number.isFinite(right?.x) ? right.x : -Infinity;
+  return rightX - leftX;
+};
+
+const insertBoundedTopCandidate = (top, candidate, topK) => {
+  if (!candidate || topK <= 0) return;
+  if (top.length >= topK && compareTopCandidatePriority(candidate, top[top.length - 1]) >= 0) {
+    return;
+  }
+
+  let insertAt = top.length;
+  while (insertAt > 0 && compareTopCandidatePriority(candidate, top[insertAt - 1]) < 0) {
+    insertAt -= 1;
+  }
+  top.splice(insertAt, 0, candidate);
+  if (top.length > topK) {
+    top.pop();
+  }
+};
+
+const cloneLemmingSummaryEntry = (lem) => {
+  if (!lem || typeof lem !== 'object') return lem || null;
+  return { ...lem };
+};
+
+const buildLemmingSummary = (state, options = {}) => {
+  const manager = state?.game?.lemmingManager || null;
+  const tickIndex = state?.game?.timer?.tickIndex ?? null;
+  const lemmings = Array.isArray(state?.game?.lemmings) ? state.game.lemmings : [];
+
+  const includeSelected = options.includeSelected !== false;
+  const activeOnly = options.activeOnly !== false;
+  const viewRect = options.inViewOnly ? state?.stage?.viewRect : null;
+  const rect = options.rectWorld || viewRect || null;
+  const topK = Number.isFinite(options.topK) ? Math.max(0, Math.trunc(options.topK)) : 10;
+  const sortAllCandidates = options.sortAllCandidates === true;
+
+  const histAction = {};
+  const histState = {};
+  let climbers = 0;
+  let floaters = 0;
+  let countingDown = 0;
+  let exploded = 0;
+
+  let totalCount = 0;
+  let activeCount = 0;
+  let removedCount = 0;
+  let disabledCount = 0;
+  let candidates = sortAllCandidates ? [] : null;
+  const top = sortAllCandidates ? null : [];
+
+  for (const lem of lemmings) {
+    if (!lem || !withinRect(lem, rect)) continue;
+    totalCount += 1;
+
+    const isRemoved = !!lem.removed;
+    const isDisabled = !!lem.disabled;
+    if (isRemoved) removedCount += 1;
+    if (isDisabled) disabledCount += 1;
+
+    const isActive = !(isRemoved || isDisabled);
+    if (isActive) activeCount += 1;
+    if (activeOnly && !isActive) continue;
+
+    const action = lem.actionType ?? null;
+    const stateCode = lem.state ?? null;
+    if (action != null) {
+      histAction[action] = (histAction[action] || 0) + 1;
+    }
+    if (stateCode != null) {
+      histState[stateCode] = (histState[stateCode] || 0) + 1;
+    }
+    if (lem.canClimb) climbers += 1;
+    if (lem.hasParachute) floaters += 1;
+    if (lem.countdownActive) countingDown += 1;
+    if (lem.hasExploded) exploded += 1;
+
+    if (sortAllCandidates) {
+      candidates.push(lem);
+    } else {
+      insertBoundedTopCandidate(top, lem, topK);
+    }
+  }
+
+  if (sortAllCandidates) {
+    if (candidates.length > 1) {
+      candidates.sort(compareTopCandidatePriority);
+    }
+    candidates = candidates.slice(0, topK);
+  }
+
+  const selectedIndex = manager?.selectedIndex;
+  const selected = includeSelected && Number.isFinite(selectedIndex) && selectedIndex >= 0
+    ? (lemmings[selectedIndex] || null)
+    : null;
+
+  const resolvedTop = sortAllCandidates ? candidates : top;
+  if (selected && !resolvedTop.some((lem) => lem?.id === selected.id)) {
+    resolvedTop.unshift(selected);
+    if (resolvedTop.length > topK) resolvedTop.pop();
+  }
+
+  const selectedSnapshot = cloneLemmingSummaryEntry(selected);
+  const topSnapshot = resolvedTop.map((lem) => cloneLemmingSummaryEntry(lem));
+
+  return {
+    tickIndex,
+    selectedLemmingId: selected ? selected.id : null,
+    totalCount,
+    activeCount,
+    removedCount,
+    disabledCount,
+    byActionType: histAction,
+    byState: histState,
+    climbers,
+    floaters,
+    countingDown,
+    exploded,
+    selected: selectedSnapshot,
+    top: topSnapshot
+  };
+};
+
+export { buildLemmingSummary };
diff --git a/mcp/protocolMetadata.js b/mcp/protocolMetadata.js
new file mode 100644
index 00000000..b0834e07
--- /dev/null
+++ b/mcp/protocolMetadata.js
@@ -0,0 +1,82 @@
+import crypto from 'node:crypto';
+
+const KEY_ALIASES = new Map([
+  ['Ctrl', 'Control'],
+  ['ControlLeft', 'Control'],
+  ['ControlRight', 'Control'],
+  ['Cmd', 'Meta'],
+  ['Command', 'Meta'],
+  ['MetaLeft', 'Meta'],
+  ['MetaRight', 'Meta'],
+  ['AltLeft', 'Alt'],
+  ['AltRight', 'Alt'],
+  ['Option', 'Alt'],
+  ['ShiftLeft', 'Shift'],
+  ['ShiftRight', 'Shift']
+]);
+
+
+const nowIso = () => new Date().toISOString();
+
+const makeId = (bytes = 9) => crypto.randomBytes(bytes)
+  .toString('base64')
+  .replace(/\+/g, '-')
+  .replace(/\//g, '_')
+  .replace(/=+$/g, '');
+
+const normalizeKeyToken = (token) => {
+  const raw = String(token || '');
+  return KEY_ALIASES.get(raw) || raw;
+};
+
+const normalizeKeyChord = (chord) => String(chord || '')
+  .split('+')
+  .map((part) => normalizeKeyToken(part.trim()))
+  .filter(Boolean)
+  .join('+');
+
+const formatToMime = (format) => {
+  switch (format) {
+  case 'jpeg':
+    return 'image/jpeg';
+  case 'webp':
+    return 'image/webp';
+  default:
+    return 'image/png';
+  }
+};
+
+
+const toToolName = (name) => String(name).replace(/\./g, '_');
+
+const buildToolResponse = (payload) => ({
+  content: [{ type: 'text', text: JSON.stringify(payload) }],
+  structuredContent: payload
+});
+
+const buildProtocolMetadata = ({
+  protocolVersion,
+  schemaFrozenAt,
+  skillNames,
+  lemmingDeltaFields
+}) => ({
+  version: protocolVersion,
+  schemaFrozenAt,
+  acceptedToolNameForms: ['underscore'],
+  unsupportedOptions: {
+    spectatorOpenBrowser: true
+  },
+  skillNames,
+  lemmingDeltaFields
+});
+
+export {
+  buildProtocolMetadata,
+  buildToolResponse,
+  formatToMime,
+  makeId,
+  normalizeKeyChord,
+  normalizeKeyToken,
+  nowIso,
+  toToolName
+};
diff --git a/mcp/resourceStore.js b/mcp/resourceStore.js
new file mode 100644
index 00000000..fd0efacd
--- /dev/null
+++ b/mcp/resourceStore.js
@@ -0,0 +1,278 @@
+import crypto from 'node:crypto';
+
+const nowIso = () => new Date().toISOString();
+const toNumberOrNaN = (value) => {
+  try {
+    return Number(value);
+  } catch {
+    return Number.NaN;
+  }
+};
+const normalizeInteger = (value, fallback, min = 0) => {
+  const numeric = toNumberOrNaN(value);
+  if (!Number.isFinite(numeric)) return fallback;
+  const integer = Math.trunc(numeric);
+  return integer >= min ? integer : fallback;
+};
+/**
+ * Normalize session ids used in resource URIs and map keys.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+const normalizeSessionId = (value) => String(value ?? '').trim();
+
+/**
+ * Fallback deep clone used when structuredClone/JSON cloning is unavailable.
+ * Supports circular references via a WeakMap memo table.
+ *
+ * @param {any} value
+ * @param {WeakMap<object, any>} [seen]
+ * @returns {any}
+ */
+const cloneMetaFallback = (value, seen = new WeakMap()) => {
+  if (value == null || typeof value !== 'object') return value;
+  if (seen.has(value)) return seen.get(value);
+
+  if (Buffer.isBuffer(value)) {
+    const copy = Buffer.from(value);
+    seen.set(value, copy);
+    return copy;
+  }
+  if (value instanceof Date) {
+    const copy = new Date(value.getTime());
+    seen.set(value, copy);
+    return copy;
+  }
+  if (value instanceof RegExp) {
+    const copy = new RegExp(value.source, value.flags);
+    seen.set(value, copy);
+    return copy;
+  }
+  if (value instanceof ArrayBuffer) {
+    const copy = value.slice(0);
+    seen.set(value, copy);
+    return copy;
+  }
+  if (value instanceof DataView) {
+    const buffer = value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength);
+    const copy = new DataView(buffer);
+    seen.set(value, copy);
+    return copy;
+  }
+  if (ArrayBuffer.isView(value)) {
+    const copy = new value.constructor(value);
+    seen.set(value, copy);
+    return copy;
+  }
+  if (value instanceof Map) {
+    const copy = new Map();
+    seen.set(value, copy);
+    for (const [entryKey, entryValue] of value.entries()) {
+      copy.set(
+        cloneMetaFallback(entryKey, seen),
+        cloneMetaFallback(entryValue, seen)
+      );
+    }
+    return copy;
+  }
+  if (value instanceof Set) {
+    const copy = new Set();
+    seen.set(value, copy);
+    for (const entry of value.values()) {
+      copy.add(cloneMetaFallback(entry, seen));
+    }
+    return copy;
+  }
+  if (Array.isArray(value)) {
+    const copy = new Array(value.length);
+    seen.set(value, copy);
+    for (let i = 0; i < value.length; i += 1) {
+      copy[i] = cloneMetaFallback(value[i], seen);
+    }
+    return copy;
+  }
+
+  const copy = {};
+  seen.set(value, copy);
+  for (const key of Object.keys(value)) {
+    copy[key] = cloneMetaFallback(value[key], seen);
+  }
+  return copy;
+};
+
+/**
+ * Clone metadata payloads defensively for storage and retrieval operations.
+ *
+ * @param {unknown} value
+ * @returns {object}
+ */
+const cloneMeta = (value) => {
+  if (value == null || typeof value !== 'object') return {};
+  if (typeof structuredClone === 'function') {
+    try {
+      return structuredClone(value);
+    } catch {
+      // fall through
+    }
+  }
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    try {
+      return cloneMetaFallback(value);
+    } catch {
+      return {};
+    }
+  }
+};
+
+const makeId = (bytes = 9) => crypto.randomBytes(bytes)
+  .toString('base64')
+  .replace(/\+/g, '-')
+  .replace(/\//g, '_')
+  .replace(/=+$/g, '');
+
+const normalizeResourceId = (value) => String(value ?? '')
+  .trim()
+  .replace(/[^A-Za-z0-9_-]/g, '');
+
+class ResourceStore {
+  constructor({
+    maxBytes = 256 * 1024 * 1024,
+    ttlMs = 10 * 60 * 1000,
+    maxItems = 5000,
+    idFactory = makeId,
+    timeFactory = nowIso
+  } = {}) {
+    this.maxBytes = normalizeInteger(maxBytes, 256 * 1024 * 1024, 1);
+    this.defaultTtlMs = normalizeInteger(ttlMs, 10 * 60 * 1000, 0);
+    this.maxItems = normalizeInteger(maxItems, 5000, 1);
+    this.idFactory = typeof idFactory === 'function' ? idFactory : makeId;
+    this.timeFactory = typeof timeFactory === 'function' ? timeFactory : nowIso;
+    this.items = new Map();
+    this.totalBytes = 0;
+  }
+
+  put({ sessionId, bytes, mimeType, meta = {}, ttlMs } = {}) {
+    const normalizedSessionId = normalizeSessionId(sessionId);
+    if (!normalizedSessionId || bytes == null) return null;
+    let buffer;
+    try {
+      // Always clone to avoid storing mutable caller-owned buffers by reference.
+      buffer = Buffer.from(bytes);
+    } catch {
+      return null;
+    }
+    const sizeBytes = buffer.length;
+    if (sizeBytes > this.maxBytes) return null;
+    const normalizedMimeType = typeof mimeType === 'string' && mimeType.trim()
+      ? mimeType.trim()
+      : 'application/octet-stream';
+    const id = this._createResourceId();
+    const uri = `lemmings://sessions/${normalizedSessionId}/resources/${id}`;
+    const ttl = normalizeInteger(ttlMs, this.defaultTtlMs, 0);
+    const expiresAt = ttl > 0 ? Date.now() + ttl : null;
+    const item = {
+      id,
+      uri,
+      sessionId: normalizedSessionId,
+      mimeType: normalizedMimeType,
+      meta: cloneMeta(meta),
+      bytes: buffer,
+      sizeBytes,
+      createdAt: this.timeFactory(),
+      expiresAt
+    };
+    this.items.set(id, item);
+    this.totalBytes += sizeBytes;
+    this._evictIfNeeded();
+    return {
+      uri,
+      sizeBytes,
+      expiresAt: expiresAt ? new Date(expiresAt).toISOString() : null
+    };
+  }
+
+  get(uri) {
+    const match = /^lemmings:\/\/sessions\/([^/]+)\/resources\/([^/]+)$/.exec(String(uri || ''));
+    if (!match) return null;
+    const sessionId = match[1];
+    const id = match[2];
+    const item = this.items.get(id);
+    if (!item) return null;
+    if (item.sessionId !== sessionId) return null;
+    if (item.expiresAt && Date.now() >= item.expiresAt) {
+      this._remove(id);
+      return null;
+    }
+    this.items.delete(id);
+    this.items.set(id, item);
+    return {
+      ...item,
+      meta: cloneMeta(item.meta),
+      bytes: Buffer.from(item.bytes)
+    };
+  }
+
+  list({ limit = 200 } = {}) {
+    const safeLimit = normalizeInteger(limit, 200, 0);
+    if (safeLimit === 0) return [];
+    const out = [];
+    for (const item of this.items.values()) {
+      if (item.expiresAt && Date.now() >= item.expiresAt) {
+        this._remove(item.id);
+        continue;
+      }
+      out.push({
+        uri: item.uri,
+        name: item.meta?.tag || item.meta?.kind || item.id,
+        mimeType: item.mimeType,
+        sizeBytes: item.sizeBytes,
+        createdAt: item.createdAt,
+        expiresAt: item.expiresAt ? new Date(item.expiresAt).toISOString() : null
+      });
+      if (out.length >= safeLimit) break;
+    }
+    return out;
+  }
+
+  clearSession(sessionId) {
+    const normalizedSessionId = normalizeSessionId(sessionId);
+    if (!normalizedSessionId) return;
+    for (const [id, item] of this.items.entries()) {
+      if (item.sessionId === normalizedSessionId) {
+        this._remove(id);
+      }
+    }
+  }
+
+  _remove(id) {
+    const item = this.items.get(id);
+    if (!item) return;
+    this.items.delete(id);
+    this.totalBytes = Math.max(0, this.totalBytes - item.sizeBytes);
+  }
+
+  _evictIfNeeded() {
+    while (this.totalBytes > this.maxBytes || this.items.size > this.maxItems) {
+      const firstKey = this.items.keys().next().value;
+      if (!firstKey) break;
+      this._remove(firstKey);
+    }
+  }
+
+  _createResourceId() {
+    const base = normalizeResourceId(this.idFactory());
+    const seed = base || makeId();
+    let candidate = seed;
+    let suffix = 0;
+    while (this.items.has(candidate)) {
+      suffix += 1;
+      candidate = `${seed}-${suffix}`;
+    }
+    return candidate;
+  }
+}
+
+export { ResourceStore };
diff --git a/mcp/schemas.js b/mcp/schemas.js
new file mode 100644
index 00000000..27876e3a
--- /dev/null
+++ b/mcp/schemas.js
@@ -0,0 +1,517 @@
+import { z } from 'zod';
+
+const SKILL_ACTIONS = {
+  climber: 'selectSkillClimber',
+  floater: 'selectSkillFloater',
+  bomber: 'selectSkillBomber',
+  blocker: 'selectSkillBlocker',
+  builder: 'selectSkillBuilder',
+  basher: 'selectSkillBasher',
+  miner: 'selectSkillMiner',
+  digger: 'selectSkillDigger'
+};
+
+const SKILL_NAMES = Object.freeze([
+  'climber',
+  'floater',
+  'bomber',
+  'blocker',
+  'builder',
+  'basher',
+  'miner',
+  'digger'
+]);
+
+const SKILL_INDEX_BY_NAME = Object.freeze({
+  climber: 1,
+  floater: 2,
+  bomber: 3,
+  blocker: 4,
+  builder: 5,
+  basher: 6,
+  miner: 7,
+  digger: 8
+});
+
+const LEMMING_DELTA_FIELDS = Object.freeze([
+  'x',
+  'y',
+  'lookRight',
+  'frameIndex',
+  'state',
+  'canClimb',
+  'hasParachute',
+  'removed',
+  'disabled',
+  'countdown',
+  'hasExploded',
+  'lastTriggerType',
+  'actionType',
+  'countdownActive'
+]);
+
+const DEFAULT_LEM_DELTA_FIELDS = Object.freeze([4, 5, 6, 7, 8, 9, 10, 11, 12, 13]);
+const MCP_PROTOCOL_VERSION = '2.1.0';
+const MCP_PROTOCOL_SCHEMA_FROZEN_AT = '2026-02-23';
+const MCP_MAX_EVENT_QUEUE_EVENTS = 10000;
+const MCP_MAX_CAPTURE_SEQUENCE_FRAMES = 240;
+
+const KEY_ALIASES = new Map([
+  ['Ctrl', 'Control'],
+  ['ControlLeft', 'Control'],
+  ['ControlRight', 'Control'],
+  ['Cmd', 'Meta'],
+  ['Command', 'Meta'],
+  ['MetaLeft', 'Meta'],
+  ['MetaRight', 'Meta'],
+  ['AltLeft', 'Alt'],
+  ['AltRight', 'Alt'],
+  ['Option', 'Alt'],
+  ['ShiftLeft', 'Shift'],
+  ['ShiftRight', 'Shift']
+]);
+
+const RESOURCE_URI_RE = /^lemmings:\/\/sessions\/([^/]+)\/resources\/([^/]+)$/;
+
+let cachedKeybindings = null;
+let cachedKeybindingsMtimeMs = NaN;
+
+const nowIso = () => new Date().toISOString();
+
+const makeId = (bytes = 9) => crypto.randomBytes(bytes)
+  .toString('base64')
+  .replace(/\+/g, '-')
+  .replace(/\//g, '_')
+  .replace(/=+$/g, '');
+
+const normalizeKeyToken = (token) => {
+  const raw = String(token || '');
+  return KEY_ALIASES.get(raw) || raw;
+};
+
+const normalizeKeyChord = (chord) => String(chord || '')
+  .split('+')
+  .map((part) => normalizeKeyToken(part.trim()))
+  .filter(Boolean)
+  .join('+');
+
+const formatToMime = (format) => {
+  switch (format) {
+  case 'jpeg':
+    return 'image/jpeg';
+  case 'webp':
+    return 'image/webp';
+  default:
+    return 'image/png';
+  }
+};
+
+const RectSchema = z.object({
+  x: z.number(),
+  y: z.number(),
+  width: z.number().positive(),
+  height: z.number().positive()
+});
+
+const SessionCreateSchema = z.object({
+  baseUrl: z.string().optional(),
+  path: z.string().optional(),
+  headless: z.boolean().optional(),
+  viewport: z.object({
+    width: z.number().int().positive(),
+    height: z.number().int().positive(),
+    deviceScaleFactor: z.number().positive().optional()
+  }).optional(),
+  enableSpectator: z.boolean().optional(),
+  spectator: z.object({
+    port: z.number().int().positive().optional(),
+    allowHumanInput: z.boolean().optional(),
+    openBrowser: z.boolean().optional(),
+    frameIntervalMs: z.number().int().positive().optional(),
+    jpegQuality: z.number().int().min(1).max(100).optional(),
+    frameSkipPolicy: z.enum(['latest', 'none']).optional()
+  }).optional(),
+  resources: z.object({
+    maxBytes: z.number().int().positive().optional(),
+    ttlMs: z.number().int().nonnegative().optional(),
+    maxItems: z.number().int().positive().optional()
+  }).optional(),
+  events: z.object({
+    maxEvents: z.number().int().positive().max(MCP_MAX_EVENT_QUEUE_EVENTS).optional(),
+    mode: z.enum(['none', 'minimal', 'full']).optional()
+  }).optional()
+});
+
+const SessionCloseSchema = z.object({
+  sessionId: z.string().min(1)
+});
+
+const TimeSchema = z.object({
+  sessionId: z.string().min(1)
+});
+
+const TimeStepSchema = z.object({
+  sessionId: z.string().min(1),
+  count: z.number().int(),
+  ensurePaused: z.boolean().optional()
+});
+
+const StateGetSchema = z.object({
+  sessionId: z.string().min(1),
+  preset: z.enum(['compact', 'debug']).optional(),
+  include: z.object({
+    view: z.boolean().optional(),
+    stage: z.boolean().optional(),
+    game: z.boolean().optional(),
+    editor: z.boolean().optional(),
+    midi: z.boolean().optional()
+  }).optional(),
+  lemmings: z.object({
+    mode: z.enum(['none', 'summary', 'selected', 'all', 'ids']).optional(),
+    ids: z.array(z.number().int()).optional(),
+    max: z.number().int().positive().optional(),
+    topK: z.number().int().positive().optional(),
+    includeSelected: z.boolean().optional(),
+    activeOnly: z.boolean().optional(),
+    inViewOnly: z.boolean().optional(),
+    rectWorld: z.object({
+      x: z.number(),
+      y: z.number(),
+      width: z.number().positive().optional(),
+      height: z.number().positive().optional(),
+      w: z.number().positive().optional(),
+      h: z.number().positive().optional()
+    }).optional()
+  }).optional(),
+  format: z.object({
+    delivery: z.enum(['inline', 'resource']).optional(),
+    pretty: z.boolean().optional(),
+    includeSizeEstimate: z.boolean().optional()
+  }).optional()
+});
+
+const StateDeltaSchema = z.object({
+  sessionId: z.string().min(1),
+  afterTick: z.number().int().optional(),
+  toTick: z.number().int().optional(),
+  maxTicks: z.number().int().positive().optional(),
+  include: z.object({
+    lemmings: z.boolean().optional(),
+    lemmingManager: z.boolean().optional(),
+    skills: z.boolean().optional(),
+    victory: z.boolean().optional(),
+    timer: z.boolean().optional(),
+    game: z.boolean().optional(),
+    sound: z.boolean().optional(),
+    minimap: z.boolean().optional(),
+    triggers: z.boolean().optional(),
+    objects: z.boolean().optional(),
+    ground: z.boolean().optional(),
+    entrances: z.boolean().optional()
+  }).optional(),
+  lemmings: z.object({
+    fields: z.array(z.number().int().min(0).max(13)).optional(),
+    includePrev: z.boolean().optional(),
+    includeXY: z.enum(['none', 'tracked', 'all']).optional(),
+    trackedIds: z.array(z.number().int()).optional(),
+    maxChanges: z.number().int().positive().optional()
+  }).optional(),
+  format: z.object({
+    delivery: z.enum(['inline', 'resource']).optional(),
+    pretty: z.boolean().optional()
+  }).optional()
+});
+
+const LemmingsSummarySchema = z.object({
+  sessionId: z.string().min(1),
+  filter: z.object({
+    activeOnly: z.boolean().optional(),
+    inViewOnly: z.boolean().optional(),
+    rectWorld: z.object({
+      x: z.number(),
+      y: z.number(),
+      width: z.number().positive().optional(),
+      height: z.number().positive().optional(),
+      w: z.number().positive().optional(),
+      h: z.number().positive().optional()
+    }).optional()
+  }).optional(),
+  topK: z.number().int().positive().optional(),
+  includeSelected: z.boolean().optional()
+});
+
+const LemmingSelectSchema = z.object({
+  sessionId: z.string().min(1),
+  lemmingId: z.number().int(),
+  alsoCenterView: z.boolean().optional(),
+  confirm: z.boolean().optional()
+});
+
+const SkillApplySchema = z.object({
+  sessionId: z.string().min(1),
+  skill: z.enum([
+    'climber',
+    'floater',
+    'bomber',
+    'blocker',
+    'builder',
+    'basher',
+    'miner',
+    'digger'
+  ]),
+  lemmingId: z.number().int().optional(),
+  ensurePaused: z.boolean().optional(),
+  requireAvailable: z.boolean().optional(),
+  postStep: z.number().int().nonnegative().optional(),
+  verify: z.boolean().optional()
+});
+
+const InputActionSchema = z.object({
+  sessionId: z.string().min(1),
+  action: z.string().min(1),
+  repeat: z.number().int().positive().optional()
+});
+
+const InputKeysSchema = z.object({
+  sessionId: z.string().min(1),
+  keys: z.array(z.string().min(1)).optional(),
+  repeat: z.number().int().positive().optional(),
+  events: z.array(z.object({
+    type: z.enum(['down', 'up', 'press']),
+    key: z.string().min(1)
+  })).optional()
+});
+
+const VisionCaptureSchema = z.object({
+  sessionId: z.string().min(1),
+  target: z.enum(['page', 'gameCanvas', 'guiCanvas', 'stageCanvas', 'rect']).optional(),
+  rect: RectSchema.optional(),
+  format: z.enum(['png', 'jpeg', 'webp']).optional(),
+  quality: z.number().int().min(1).max(100).optional(),
+  delivery: z.enum(['resource', 'inline']).optional(),
+  tag: z.string().optional()
+});
+
+const VisionSequenceSchema = z.object({
+  sessionId: z.string().min(1),
+  mode: z.enum(['step', 'sample']),
+  frames: z.number().int().positive().max(MCP_MAX_CAPTURE_SEQUENCE_FRAMES),
+  stepBy: z.number().int().optional(),
+  everyMs: z.number().int().positive().optional(),
+  capture: VisionCaptureSchema.omit({ sessionId: true }),
+  returnManifest: z.boolean().optional()
+});
+
+const WatchCreateSchema = z.object({
+  sessionId: z.string().min(1),
+  watch: z.object({
+    type: z.enum(['everyTicks', 'onChange']),
+    everyTicks: z.number().int().positive().optional(),
+    jsonPointer: z.string().optional()
+  }),
+  actions: z.array(z.object({
+    type: z.enum(['emitSummary', 'capture']),
+    include: z.object({
+      lemmingsSummary: z.boolean().optional(),
+      statePointers: z.array(z.string().min(1)).optional()
+    }).optional(),
+    capture: VisionCaptureSchema.omit({ sessionId: true }).optional(),
+    throttleTicks: z.number().int().positive().optional()
+  })).optional(),
+  enabled: z.boolean().optional()
+});
+
+const WatchCancelSchema = z.object({
+  sessionId: z.string().min(1),
+  watchId: z.string().min(1)
+});
+
+const EditorApplySchema = z.object({
+  sessionId: z.string().min(1),
+  ops: z.array(z.object({
+    opId: z.string().optional(),
+    type: z.string().min(1),
+    args: z.any().optional()
+  })).optional(),
+  atomic: z.boolean().optional(),
+  dryRun: z.boolean().optional(),
+  history: z.object({
+    label: z.string().optional(),
+    record: z.boolean().optional()
+  }).optional(),
+  preview: z.object({
+    refresh: z.boolean().optional(),
+    label: z.string().optional(),
+    preserveViewport: z.boolean().optional()
+  }).optional(),
+  validate: z.object({
+    run: z.boolean().optional(),
+    autoFix: z.enum(['none', 'safe', 'aggressive']).optional()
+  }).optional(),
+  returnState: z.enum(['none', 'editor', 'full']).optional()
+});
+
+const EditorMutationOptionsSchema = z.object({
+  atomic: z.boolean().optional(),
+  dryRun: z.boolean().optional(),
+  history: z.object({
+    label: z.string().optional(),
+    record: z.boolean().optional()
+  }).optional(),
+  preview: z.object({
+    refresh: z.boolean().optional(),
+    label: z.string().optional(),
+    preserveViewport: z.boolean().optional()
+  }).optional(),
+  validate: z.object({
+    run: z.boolean().optional(),
+    autoFix: z.enum(['none', 'safe', 'aggressive']).optional()
+  }).optional(),
+  returnState: z.enum(['none', 'editor', 'full']).optional()
+});
+
+const EditorObjectKindSchema = z.enum(['terrain', 'gadget', 'steel']);
+const EditorObjectKindOrAllSchema = z.enum(['terrain', 'gadget', 'steel', 'all']);
+
+const EditorObjectRefSchema = z.object({
+  kind: EditorObjectKindOrAllSchema.optional(),
+  index: z.number().int().nonnegative().optional(),
+  uid: z.string().min(1).optional()
+}).refine(
+  (value) => Number.isFinite(value.index) || typeof value.uid === 'string',
+  { message: 'Editor object ref requires index or uid.' }
+);
+
+const EditorObjectBBoxSchema = z.object({
+  x: z.number(),
+  y: z.number(),
+  width: z.number().positive().optional(),
+  height: z.number().positive().optional(),
+  w: z.number().positive().optional(),
+  h: z.number().positive().optional()
+});
+
+const ObjectsListSchema = z.object({
+  sessionId: z.string().min(1),
+  kind: EditorObjectKindOrAllSchema.optional(),
+  bbox: EditorObjectBBoxSchema.optional(),
+  page: z.number().int().nonnegative().optional(),
+  pageSize: z.number().int().positive().max(500).optional(),
+  fields: z.enum(['compact', 'full']).optional(),
+  sinceRevision: z.number().int().nonnegative().optional()
+});
+
+const ObjectsPlaceSchema = z.object({
+  sessionId: z.string().min(1),
+  objects: z.array(z.object({
+    kind: EditorObjectKindSchema,
+    props: z.record(z.any()).optional(),
+    piece: z.number().int().optional(),
+    x: z.number().optional(),
+    y: z.number().optional(),
+    width: z.number().positive().optional(),
+    height: z.number().positive().optional(),
+    insertIndex: z.number().int().nonnegative().optional()
+  })).min(1),
+  options: EditorMutationOptionsSchema.optional()
+});
+
+const ObjectsUpdateSchema = z.object({
+  sessionId: z.string().min(1),
+  updates: z.array(z.object({
+    ref: EditorObjectRefSchema,
+    set: z.record(z.any()).optional(),
+    unset: z.array(z.string().min(1)).optional()
+  }).refine((value) => (
+    (value.set && Object.keys(value.set).length > 0) ||
+    (Array.isArray(value.unset) && value.unset.length > 0)
+  ), {
+    message: 'Each update requires set and/or unset fields.'
+  })).min(1),
+  options: EditorMutationOptionsSchema.optional()
+});
+
+const ObjectsDeleteSchema = z.object({
+  sessionId: z.string().min(1),
+  refs: z.array(EditorObjectRefSchema).min(1),
+  options: EditorMutationOptionsSchema.optional()
+});
+
+const EventsPollSchema = z.object({
+  sessionId: z.string().min(1),
+  after: z.string().optional()
+});
+
+const SolverOptionsSchema = z.object({
+  seed: z.number().int().nonnegative().optional(),
+  mode: z.enum(['tactical', 'route', 'full']).optional(),
+  skillSubset: z.array(z.string().min(1)).optional(),
+  targetSaveCount: z.number().int().nonnegative().optional(),
+  maxTicks: z.number().int().positive().optional(),
+  maxNodes: z.number().int().positive().optional(),
+  maxActions: z.number().int().nonnegative().optional(),
+  maxWallTimeMs: z.number().int().positive().optional(),
+  allowDestructiveSkills: z.boolean().optional(),
+  verify: z.boolean().optional()
+}).passthrough();
+
+const SolverSourceSchema = z.any();
+
+const SolverSnapshotSchema = z.object({
+  source: SolverSourceSchema,
+  options: SolverOptionsSchema.optional()
+});
+
+const SolverRouteSchema = z.object({
+  source: SolverSourceSchema,
+  options: SolverOptionsSchema.optional()
+});
+
+const SolverReplaySchema = z.object({
+  source: SolverSourceSchema,
+  actions: z.array(z.any()).optional(),
+  options: SolverOptionsSchema.optional()
+});
+
+
+export {
+  DEFAULT_LEM_DELTA_FIELDS,
+  EditorApplySchema,
+  EditorMutationOptionsSchema,
+  EditorObjectBBoxSchema,
+  EditorObjectKindOrAllSchema,
+  EditorObjectKindSchema,
+  EditorObjectRefSchema,
+  EventsPollSchema,
+  InputActionSchema,
+  InputKeysSchema,
+  LEMMING_DELTA_FIELDS,
+  LemmingsSummarySchema,
+  LemmingSelectSchema,
+  MCP_MAX_CAPTURE_SEQUENCE_FRAMES,
+  MCP_MAX_EVENT_QUEUE_EVENTS,
+  MCP_PROTOCOL_SCHEMA_FROZEN_AT,
+  MCP_PROTOCOL_VERSION,
+  ObjectsDeleteSchema,
+  ObjectsListSchema,
+  ObjectsPlaceSchema,
+  ObjectsUpdateSchema,
+  RectSchema,
+  SKILL_ACTIONS,
+  SKILL_INDEX_BY_NAME,
+  SKILL_NAMES,
+  SessionCloseSchema,
+  SessionCreateSchema,
+  SkillApplySchema,
+  SolverReplaySchema,
+  SolverRouteSchema,
+  SolverSnapshotSchema,
+  StateDeltaSchema,
+  StateGetSchema,
+  TimeSchema,
+  TimeStepSchema,
+  VisionCaptureSchema,
+  VisionSequenceSchema,
+  WatchCancelSchema,
+  WatchCreateSchema
+};
diff --git a/mcp/server.js b/mcp/server.js
index 19a76284..7eda968c 100644
--- a/mcp/server.js
+++ b/mcp/server.js
@@ -6,2283 +6,363 @@ import {
   ListToolsRequestSchema,
   ReadResourceRequestSchema
 } from '@modelcontextprotocol/sdk/types.js';
-import { z } from 'zod';
 import { toJsonSchemaCompat } from '@modelcontextprotocol/sdk/server/zod-json-schema-compat.js';
 import { chromium } from '@playwright/test';
-import crypto from 'node:crypto';
 import fs from 'node:fs/promises';
-import http from 'node:http';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { WebSocketServer } from 'ws';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const ROOT_DIR = path.resolve(__dirname, '..');
-const KEYBINDINGS_PATH = path.join(ROOT_DIR, 'keybindings.json');
-const SPECTATOR_HTML_PATH = path.join(__dirname, 'spectator.html');
-
-const DEFAULT_BASE_URL = process.env.LEMMINGS_MCP_BASE_URL || 'https://localhost:8080';
-const DEFAULT_PATH = process.env.LEMMINGS_MCP_PATH || '/?e2e=1';
-const DEFAULT_VIEWPORT = { width: 1280, height: 720, deviceScaleFactor: 1 };
-
-const SKILL_ACTIONS = {
-  climber: 'selectSkillClimber',
-  floater: 'selectSkillFloater',
-  bomber: 'selectSkillBomber',
-  blocker: 'selectSkillBlocker',
-  builder: 'selectSkillBuilder',
-  basher: 'selectSkillBasher',
-  miner: 'selectSkillMiner',
-  digger: 'selectSkillDigger'
-};
-
-const SKILL_NAMES = Object.freeze([
-  'climber',
-  'floater',
-  'bomber',
-  'blocker',
-  'builder',
-  'basher',
-  'miner',
-  'digger'
-]);
-
-const SKILL_INDEX_BY_NAME = Object.freeze({
-  climber: 1,
-  floater: 2,
-  bomber: 3,
-  blocker: 4,
-  builder: 5,
-  basher: 6,
-  miner: 7,
-  digger: 8
-});
-
-const LEMMING_DELTA_FIELDS = Object.freeze([
-  'x',
-  'y',
-  'lookRight',
-  'frameIndex',
-  'state',
-  'canClimb',
-  'hasParachute',
-  'removed',
-  'disabled',
-  'countdown',
-  'hasExploded',
-  'lastTriggerType',
-  'actionType',
-  'countdownActive'
-]);
-
-const DEFAULT_LEM_DELTA_FIELDS = Object.freeze([4, 5, 6, 7, 8, 9, 10, 11, 12, 13]);
-
-const KEY_ALIASES = new Map([
-  ['Ctrl', 'Control'],
-  ['ControlLeft', 'Control'],
-  ['ControlRight', 'Control'],
-  ['Cmd', 'Meta'],
-  ['Command', 'Meta'],
-  ['MetaLeft', 'Meta'],
-  ['MetaRight', 'Meta'],
-  ['AltLeft', 'Alt'],
-  ['AltRight', 'Alt'],
-  ['Option', 'Alt'],
-  ['ShiftLeft', 'Shift'],
-  ['ShiftRight', 'Shift']
-]);
-
-const RESOURCE_URI_RE = /^lemmings:\/\/sessions\/([^/]+)\/resources\/([^/]+)$/;
-
-const sessions = new Map();
-let cachedKeybindings = null;
-
-const nowIso = () => new Date().toISOString();
-
-const makeId = (bytes = 9) => crypto.randomBytes(bytes)
-  .toString('base64')
-  .replace(/\+/g, '-')
-  .replace(/\//g, '_')
-  .replace(/=+$/g, '');
-
-const normalizeKeyToken = (token) => {
-  const raw = String(token || '');
-  return KEY_ALIASES.get(raw) || raw;
-};
-
-const normalizeKeyChord = (chord) => String(chord || '')
-  .split('+')
-  .map((part) => normalizeKeyToken(part.trim()))
-  .filter(Boolean)
-  .join('+');
-
-const formatToMime = (format) => {
-  switch (format) {
-  case 'jpeg':
-    return 'image/jpeg';
-  case 'webp':
-    return 'image/webp';
-  default:
-    return 'image/png';
-  }
-};
-
-class ResourceStore {
-  constructor({ maxBytes = 256 * 1024 * 1024, ttlMs = 10 * 60 * 1000, maxItems = 5000 } = {}) {
-    this.maxBytes = maxBytes;
-    this.defaultTtlMs = ttlMs;
-    this.maxItems = maxItems;
-    this.items = new Map();
-    this.totalBytes = 0;
-  }
-
-  put({ sessionId, bytes, mimeType, meta = {}, ttlMs } = {}) {
-    if (!bytes) return null;
-    const buffer = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
-    const id = makeId();
-    const uri = `lemmings://sessions/${sessionId}/resources/${id}`;
-    const sizeBytes = buffer.length;
-    const ttl = Number.isFinite(ttlMs) ? ttlMs : this.defaultTtlMs;
-    const expiresAt = ttl > 0 ? Date.now() + ttl : null;
-    const item = {
-      id,
-      uri,
-      sessionId,
-      mimeType,
-      meta,
-      bytes: buffer,
-      sizeBytes,
-      createdAt: nowIso(),
-      expiresAt
-    };
-    this.items.set(id, item);
-    this.totalBytes += sizeBytes;
-    this._evictIfNeeded();
-    return {
-      uri,
-      sizeBytes,
-      expiresAt: expiresAt ? new Date(expiresAt).toISOString() : null
-    };
-  }
-
-  get(uri) {
-    const match = RESOURCE_URI_RE.exec(String(uri || ''));
-    if (!match) return null;
-    const id = match[2];
-    const item = this.items.get(id);
-    if (!item) return null;
-    if (item.expiresAt && Date.now() >= item.expiresAt) {
-      this._remove(id);
-      return null;
-    }
-    this.items.delete(id);
-    this.items.set(id, item);
-    return item;
-  }
-
-  list({ limit = 200 } = {}) {
-    const out = [];
-    for (const item of this.items.values()) {
-      if (item.expiresAt && Date.now() >= item.expiresAt) {
-        this._remove(item.id);
-        continue;
-      }
-      out.push({
-        uri: item.uri,
-        name: item.meta?.tag || item.meta?.kind || item.id,
-        mimeType: item.mimeType,
-        sizeBytes: item.sizeBytes,
-        createdAt: item.createdAt,
-        expiresAt: item.expiresAt ? new Date(item.expiresAt).toISOString() : null
-      });
-      if (out.length >= limit) break;
-    }
-    return out;
-  }
-
-  clearSession(sessionId) {
-    if (!sessionId) return;
-    for (const [id, item] of this.items.entries()) {
-      if (item.sessionId === sessionId) {
-        this._remove(id);
-      }
-    }
-  }
-
-  _remove(id) {
-    const item = this.items.get(id);
-    if (!item) return;
-    this.items.delete(id);
-    this.totalBytes = Math.max(0, this.totalBytes - item.sizeBytes);
-  }
-
-  _evictIfNeeded() {
-    while (this.totalBytes > this.maxBytes || this.items.size > this.maxItems) {
-      const firstKey = this.items.keys().next().value;
-      if (!firstKey) break;
-      this._remove(firstKey);
-    }
-  }
-}
-
-class EventQueue {
-  constructor({ maxEvents = 1000 } = {}) {
-    this.maxEvents = maxEvents;
-    this.events = [];
-    this.seq = 0;
-    this.lastDelivered = 0;
-    this.humanSummaryParts = [];
-  }
-
-  add({ source, type, summary, data, resourceUris, tickIndex } = {}) {
-    const entry = {
-      id: makeId(),
-      source,
-      type,
-      tickIndex: Number.isFinite(tickIndex) ? tickIndex : null,
-      time: nowIso(),
-      summary: summary || '',
-      data,
-      resourceUris
-    };
-    this.seq += 1;
-    entry.seq = this.seq;
-    this.events.push(entry);
-    if (source === 'human' && summary) {
-      this.humanSummaryParts.push(summary);
-    }
-    while (this.events.length > this.maxEvents) {
-      this.events.shift();
-    }
-    return entry;
-  }
-
-  drain(after, { updateCursor = true, includeHumanSummary = true } = {}) {
-    const afterSeq = Number.isFinite(Number(after)) ? Number(after) : this.lastDelivered;
-    const events = this.events.filter((event) => event.seq > afterSeq);
-    if (!events.length) return null;
-    const cursor = String(events[events.length - 1].seq);
-    if (updateCursor) {
-      this.lastDelivered = Number(cursor);
-    }
-    const payload = {
-      cursor,
-      events: events.map(({ seq, ...rest }) => rest)
-    };
-    if (includeHumanSummary && this.humanSummaryParts.length) {
-      payload.humanSummary = this.humanSummaryParts.join('; ');
-      this.humanSummaryParts = [];
-    }
-    return payload;
-  }
-}
-
-const RectSchema = z.object({
-  x: z.number(),
-  y: z.number(),
-  width: z.number().positive(),
-  height: z.number().positive()
-});
-
-const SessionCreateSchema = z.object({
-  baseUrl: z.string().optional(),
-  path: z.string().optional(),
-  headless: z.boolean().optional(),
-  viewport: z.object({
-    width: z.number().int().positive(),
-    height: z.number().int().positive(),
-    deviceScaleFactor: z.number().positive().optional()
-  }).optional(),
-  enableSpectator: z.boolean().optional(),
-  spectator: z.object({
-    port: z.number().int().positive().optional(),
-    allowHumanInput: z.boolean().optional(),
-    openBrowser: z.boolean().optional()
-  }).optional(),
-  resources: z.object({
-    maxBytes: z.number().int().positive().optional(),
-    ttlMs: z.number().int().nonnegative().optional(),
-    maxItems: z.number().int().positive().optional()
-  }).optional(),
-  events: z.object({
-    maxEvents: z.number().int().positive().optional(),
-    mode: z.enum(['none', 'minimal', 'full']).optional()
-  }).optional()
-});
-
-const SessionCloseSchema = z.object({
-  sessionId: z.string().min(1)
-});
-
-const TimeSchema = z.object({
-  sessionId: z.string().min(1)
-});
-
-const TimeStepSchema = z.object({
-  sessionId: z.string().min(1),
-  count: z.number().int(),
-  ensurePaused: z.boolean().optional()
-});
-
-const StateGetSchema = z.object({
-  sessionId: z.string().min(1),
-  preset: z.enum(['compact', 'debug']).optional(),
-  include: z.object({
-    view: z.boolean().optional(),
-    stage: z.boolean().optional(),
-    game: z.boolean().optional(),
-    editor: z.boolean().optional(),
-    midi: z.boolean().optional()
-  }).optional(),
-  lemmings: z.object({
-    mode: z.enum(['none', 'summary', 'selected', 'all', 'ids']).optional(),
-    ids: z.array(z.number().int()).optional(),
-    max: z.number().int().positive().optional(),
-    topK: z.number().int().positive().optional(),
-    includeSelected: z.boolean().optional(),
-    activeOnly: z.boolean().optional(),
-    inViewOnly: z.boolean().optional(),
-    rectWorld: z.object({
-      x: z.number(),
-      y: z.number(),
-      width: z.number().positive().optional(),
-      height: z.number().positive().optional(),
-      w: z.number().positive().optional(),
-      h: z.number().positive().optional()
-    }).optional()
-  }).optional(),
-  format: z.object({
-    delivery: z.enum(['inline', 'resource']).optional(),
-    pretty: z.boolean().optional(),
-    includeSizeEstimate: z.boolean().optional()
-  }).optional()
-});
-
-const StateDeltaSchema = z.object({
-  sessionId: z.string().min(1),
-  afterTick: z.number().int().optional(),
-  toTick: z.number().int().optional(),
-  maxTicks: z.number().int().positive().optional(),
-  include: z.object({
-    lemmings: z.boolean().optional(),
-    lemmingManager: z.boolean().optional(),
-    skills: z.boolean().optional(),
-    victory: z.boolean().optional(),
-    timer: z.boolean().optional(),
-    game: z.boolean().optional(),
-    sound: z.boolean().optional(),
-    minimap: z.boolean().optional(),
-    triggers: z.boolean().optional(),
-    objects: z.boolean().optional(),
-    ground: z.boolean().optional(),
-    entrances: z.boolean().optional()
-  }).optional(),
-  lemmings: z.object({
-    fields: z.array(z.number().int().min(0).max(13)).optional(),
-    includePrev: z.boolean().optional(),
-    includeXY: z.enum(['none', 'tracked', 'all']).optional(),
-    trackedIds: z.array(z.number().int()).optional(),
-    maxChanges: z.number().int().positive().optional()
-  }).optional(),
-  format: z.object({
-    delivery: z.enum(['inline', 'resource']).optional(),
-    pretty: z.boolean().optional()
-  }).optional()
-});
-
-const LemmingsSummarySchema = z.object({
-  sessionId: z.string().min(1),
-  filter: z.object({
-    activeOnly: z.boolean().optional(),
-    inViewOnly: z.boolean().optional(),
-    rectWorld: z.object({
-      x: z.number(),
-      y: z.number(),
-      width: z.number().positive().optional(),
-      height: z.number().positive().optional(),
-      w: z.number().positive().optional(),
-      h: z.number().positive().optional()
-    }).optional()
-  }).optional(),
-  topK: z.number().int().positive().optional(),
-  includeSelected: z.boolean().optional()
-});
-
-const LemmingSelectSchema = z.object({
-  sessionId: z.string().min(1),
-  lemmingId: z.number().int(),
-  alsoCenterView: z.boolean().optional(),
-  confirm: z.boolean().optional()
-});
-
-const SkillApplySchema = z.object({
-  sessionId: z.string().min(1),
-  skill: z.enum([
-    'climber',
-    'floater',
-    'bomber',
-    'blocker',
-    'builder',
-    'basher',
-    'miner',
-    'digger'
-  ]),
-  lemmingId: z.number().int().optional(),
-  ensurePaused: z.boolean().optional(),
-  requireAvailable: z.boolean().optional(),
-  postStep: z.number().int().nonnegative().optional(),
-  verify: z.boolean().optional()
-});
-
-const InputActionSchema = z.object({
-  sessionId: z.string().min(1),
-  action: z.string().min(1),
-  repeat: z.number().int().positive().optional()
-});
-
-const InputKeysSchema = z.object({
-  sessionId: z.string().min(1),
-  keys: z.array(z.string().min(1)).optional(),
-  repeat: z.number().int().positive().optional(),
-  events: z.array(z.object({
-    type: z.enum(['down', 'up', 'press']),
-    key: z.string().min(1)
-  })).optional()
-});
-
-const VisionCaptureSchema = z.object({
-  sessionId: z.string().min(1),
-  target: z.enum(['page', 'gameCanvas', 'guiCanvas', 'stageCanvas', 'rect']).optional(),
-  rect: RectSchema.optional(),
-  format: z.enum(['png', 'jpeg', 'webp']).optional(),
-  delivery: z.enum(['resource', 'inline']).optional(),
-  tag: z.string().optional()
-});
-
-const VisionSequenceSchema = z.object({
-  sessionId: z.string().min(1),
-  mode: z.enum(['step', 'sample']),
-  frames: z.number().int().positive(),
-  stepBy: z.number().int().optional(),
-  everyMs: z.number().int().positive().optional(),
-  capture: VisionCaptureSchema.omit({ sessionId: true }),
-  returnManifest: z.boolean().optional()
-});
-
-const WatchCreateSchema = z.object({
-  sessionId: z.string().min(1),
-  watch: z.object({
-    type: z.enum(['everyTicks', 'onChange']),
-    everyTicks: z.number().int().positive().optional(),
-    jsonPointer: z.string().optional()
-  }),
-  actions: z.array(z.object({
-    type: z.enum(['emitSummary', 'capture']),
-    include: z.object({
-      lemmingsSummary: z.boolean().optional(),
-      statePointers: z.array(z.string().min(1)).optional()
-    }).optional(),
-    capture: VisionCaptureSchema.omit({ sessionId: true }).optional(),
-    throttleTicks: z.number().int().positive().optional()
-  })).optional(),
-  enabled: z.boolean().optional()
-});
-
-const WatchCancelSchema = z.object({
-  sessionId: z.string().min(1),
-  watchId: z.string().min(1)
-});
-
-const EditorApplySchema = z.object({
-  sessionId: z.string().min(1),
-  ops: z.array(z.object({
-    opId: z.string().optional(),
-    type: z.string().min(1),
-    args: z.any().optional()
-  })).optional(),
-  atomic: z.boolean().optional(),
-  dryRun: z.boolean().optional(),
-  history: z.object({
-    label: z.string().optional(),
-    record: z.boolean().optional()
-  }).optional(),
-  preview: z.object({
-    refresh: z.boolean().optional(),
-    label: z.string().optional(),
-    preserveViewport: z.boolean().optional()
-  }).optional(),
-  validate: z.object({
-    run: z.boolean().optional(),
-    autoFix: z.enum(['none', 'safe', 'aggressive']).optional()
-  }).optional(),
-  returnState: z.enum(['none', 'editor', 'full']).optional()
-});
-
-const EventsPollSchema = z.object({
-  sessionId: z.string().min(1),
-  after: z.string().optional()
-});
-
-const TOOL_SPECS = [
-  {
-    name: 'session.create',
-    description: 'Launch a Playwright session and load the game with the E2E harness.',
-    schema: SessionCreateSchema
-  },
-  {
-    name: 'session.close',
-    description: 'Close a Playwright session and clear resources/events.',
-    schema: SessionCloseSchema
-  },
-  {
-    name: 'time.pause',
-    description: 'Pause the game timer via the E2E harness.',
-    schema: TimeSchema
-  },
-  {
-    name: 'time.resume',
-    description: 'Resume the game timer via the E2E harness.',
-    schema: TimeSchema
-  },
-  {
-    name: 'time.step',
-    description: 'Step the game timer forward or backward by a number of ticks.',
-    schema: TimeStepSchema
-  },
-  {
-    name: 'state.get',
-    description: 'Fetch a structured state snapshot from the E2E harness.',
-    schema: StateGetSchema
-  },
-  {
-    name: 'state.delta',
-    description: 'Return filtered history deltas between ticks (defaults to changes since the last state.get).',
-    schema: StateDeltaSchema
-  },
-  {
-    name: 'editor.apply',
-    description: 'Apply editor mutations through the E2E harness.',
-    schema: EditorApplySchema
-  },
-  {
-    name: 'lemming.summary',
-    description: 'Return aggregated lemming summary data.',
-    schema: LemmingsSummarySchema
-  },
-  {
-    name: 'lemming.select',
-    description: 'Select a lemming by ID via the E2E harness.',
-    schema: LemmingSelectSchema
-  },
-  {
-    name: 'skill.apply',
-    description: 'Apply a skill to a selected lemming using keybindings.',
-    schema: SkillApplySchema
-  },
-  {
-    name: 'input.action',
-    description: 'Execute a named action from keybindings.json.',
-    schema: InputActionSchema
-  },
-  {
-    name: 'input.keys',
-    description: 'Inject low-level key events.',
-    schema: InputKeysSchema
-  },
-  {
-    name: 'vision.capture',
-    description: 'Capture a screenshot of the page or canvas.',
-    schema: VisionCaptureSchema
-  },
-  {
-    name: 'vision.captureSequence',
-    description: 'Capture multiple frames across time.',
-    schema: VisionSequenceSchema
-  },
-  {
-    name: 'watch.create',
-    description: 'Create a watch that emits events based on ticks or state changes.',
-    schema: WatchCreateSchema
-  },
-  {
-    name: 'watch.cancel',
-    description: 'Cancel a watch.',
-    schema: WatchCancelSchema
-  },
-  {
-    name: 'events.poll',
-    description: 'Poll events since a cursor.',
-    schema: EventsPollSchema
-  }
-];
-
-const TOOL_NAME_ALIASES = new Map();
-
-const toToolName = (name) => String(name).replace(/\./g, '_');
-
-const LEGACY_TOOL_ALIASES = new Map([
-  ['lemmings.session.create', 'session.create'],
-  ['lemmings.session.close', 'session.close'],
-  ['lemmings.time.pause', 'time.pause'],
-  ['lemmings.time.resume', 'time.resume'],
-  ['lemmings.time.step', 'time.step'],
-  ['lemmings.state.get', 'state.get'],
-  ['lemmings.state.delta', 'state.delta'],
-  ['lemmings.editor.apply', 'editor.apply'],
-  ['lemmings.lemmings.summary', 'lemming.summary'],
-  ['lemmings.lemming.select', 'lemming.select'],
-  ['lemmings.skill.apply', 'skill.apply'],
-  ['lemmings.input.action', 'input.action'],
-  ['lemmings.input.keys', 'input.keys'],
-  ['lemmings.vision.capture', 'vision.capture'],
-  ['lemmings.vision.captureSequence', 'vision.captureSequence'],
-  ['lemmings.watch.create', 'watch.create'],
-  ['lemmings.watch.cancel', 'watch.cancel'],
-  ['lemmings.events.poll', 'events.poll']
-]);
-
-const TOOL_DEFS = TOOL_SPECS.map((spec) => {
-  const externalName = toToolName(spec.name);
-  TOOL_NAME_ALIASES.set(externalName, spec.name);
-  TOOL_NAME_ALIASES.set(spec.name, spec.name);
-  return {
-    name: externalName,
-    description: spec.description,
-    inputSchema: toJsonSchemaCompat(spec.schema)
-  };
-});
-
-for (const [legacyName, currentName] of LEGACY_TOOL_ALIASES.entries()) {
-  TOOL_NAME_ALIASES.set(legacyName, currentName);
-  TOOL_NAME_ALIASES.set(toToolName(legacyName), currentName);
-}
-
-const buildToolResponse = (payload) => ({
-  content: [{ type: 'text', text: JSON.stringify(payload) }],
-  structuredContent: payload
-});
-
-const getSession = (sessionId) => {
-  const session = sessions.get(sessionId);
-  if (!session) {
-    throw new Error(`Session not found: ${sessionId}`);
-  }
-  return session;
-};
-
-const loadKeybindings = async () => {
-  if (cachedKeybindings) return cachedKeybindings;
-  const raw = await fs.readFile(KEYBINDINGS_PATH, 'utf8');
-  cachedKeybindings = JSON.parse(raw);
-  return cachedKeybindings;
-};
-
-const ensureBlurred = async (session) => {
-  await session.page.evaluate(() => {
-    const active = document.activeElement;
-    if (active && typeof active.blur === 'function') {
-      active.blur();
-    }
-  });
-};
-
-const callE2E = async (session, method, ...args) => session.page.evaluate(
-  ({ method, args }) => {
-    const api = window.__E2E__;
-    if (!api || typeof api[method] !== 'function') {
-      return { ok: false, error: 'harness_unavailable' };
-    }
-    try {
-      return { ok: true, value: api[method](...args) };
-    } catch (err) {
-      return { ok: false, error: err ? String(err) : 'error' };
-    }
-  },
-  { method, args }
-);
-
-const getState = async (session) => {
-  const result = await callE2E(session, 'getState');
-  return result.ok ? result.value : null;
-};
-
-const getTickIndex = async (session) => {
-  const state = await getState(session);
-  return state?.game?.timer?.tickIndex ?? null;
-};
-
-const attachEvents = (session, payload) => {
-  if (!session) return payload;
-  const mode = session.eventsMode || 'minimal';
-  if (mode === 'none') return payload;
-
-  const envelope = session.events.drain(undefined, {
-    updateCursor: true,
-    includeHumanSummary: mode !== 'none'
-  });
-  if (!envelope) return payload;
-
-  if (mode === 'minimal') {
-    envelope.events = (envelope.events || [])
-      .filter((event) => event && event.source !== 'agent')
-      .map((event) => ({
-        source: event.source,
-        type: event.type,
-        tickIndex: event.tickIndex ?? null,
-        summary: event.summary ?? null,
-        ...(Array.isArray(event.resourceUris) && event.resourceUris.length
-          ? { resourceUris: event.resourceUris }
-          : {})
-      }));
-    if (!envelope.events.length) {
-      delete envelope.events;
-    }
-    if (!envelope.humanSummary) {
-      delete envelope.humanSummary;
-    }
-  }
-
-  const hasEvents = Array.isArray(envelope.events) && envelope.events.length > 0;
-  const hasSummary = typeof envelope.humanSummary === 'string' && envelope.humanSummary.length > 0;
-  if (!hasEvents && !hasSummary) return payload;
-
-  payload.events = envelope;
-  return payload;
-};
-
-const filterStateSnapshot = (snapshot, include) => {
-  const config = {
-    view: false,
-    stage: false,
-    game: true,
-    editor: false,
-    midi: false,
-    ...(include || {})
-  };
-  const output = {
-    version: snapshot.version,
-    mode: snapshot.mode,
-    ready: snapshot.ready
-  };
-
-  if (config.view) output.view = snapshot.view;
-  if (config.stage) output.stage = snapshot.stage;
-  if (config.game) output.game = snapshot.game;
-  if (config.editor) output.editor = snapshot.editor;
-  if (config.midi) output.midi = snapshot.midi;
-
-  return output;
-};
-
-const withinRect = (lem, rect) => {
-  if (!rect) return true;
-  const width = Number.isFinite(rect.w) ? rect.w : rect.width;
-  const height = Number.isFinite(rect.h) ? rect.h : rect.height;
-  if (!Number.isFinite(width) || !Number.isFinite(height)) return true;
-  return (
-    lem.x >= rect.x &&
-    lem.x <= rect.x + width &&
-    lem.y >= rect.y &&
-    lem.y <= rect.y + height
-  );
-};
-
-const buildLemmingSummary = (state, options = {}) => {
-  const manager = state?.game?.lemmingManager || null;
-  const tickIndex = state?.game?.timer?.tickIndex ?? null;
-  const lemmings = Array.isArray(state?.game?.lemmings) ? state.game.lemmings : [];
-
-  const includeSelected = options.includeSelected !== false;
-  const activeOnly = options.activeOnly !== false;
-  const viewRect = options.inViewOnly ? state?.stage?.viewRect : null;
-  const rect = options.rectWorld || viewRect || null;
-
-  const inRect = rect ? lemmings.filter((lem) => lem && withinRect(lem, rect)) : lemmings.filter(Boolean);
-  const activeInRect = inRect.filter((lem) => !(lem.removed || lem.disabled));
-  const removedCount = inRect.reduce((acc, lem) => acc + (lem.removed ? 1 : 0), 0);
-  const disabledCount = inRect.reduce((acc, lem) => acc + (lem.disabled ? 1 : 0), 0);
-  const filtered = activeOnly ? activeInRect : inRect;
-
-  const histAction = {};
-  const histState = {};
-  let climbers = 0;
-  let floaters = 0;
-  let countingDown = 0;
-  let exploded = 0;
-  for (const lem of filtered) {
-    if (!lem) continue;
-    const action = lem.actionType ?? null;
-    const stateCode = lem.state ?? null;
-    if (action != null) {
-      histAction[action] = (histAction[action] || 0) + 1;
-    }
-    if (stateCode != null) {
-      histState[stateCode] = (histState[stateCode] || 0) + 1;
-    }
-    if (lem.canClimb) climbers += 1;
-    if (lem.hasParachute) floaters += 1;
-    if (lem.countdownActive) countingDown += 1;
-    if (lem.hasExploded) exploded += 1;
-  }
-
-  const selectedIndex = manager?.selectedIndex;
-  const selected = includeSelected && Number.isFinite(selectedIndex) && selectedIndex >= 0
-    ? (lemmings[selectedIndex] || null)
-    : null;
-
-  const topK = Number.isFinite(options.topK) ? Math.max(0, Math.trunc(options.topK)) : 10;
-  const candidates = filtered.slice();
-  if (candidates.length > 1) {
-    candidates.sort((a, b) => {
-      const aCountdown = a?.countdownActive ? 1 : 0;
-      const bCountdown = b?.countdownActive ? 1 : 0;
-      if (aCountdown !== bCountdown) return bCountdown - aCountdown;
-      const ax = Number.isFinite(a?.x) ? a.x : -Infinity;
-      const bx = Number.isFinite(b?.x) ? b.x : -Infinity;
-      return bx - ax;
-    });
-  }
-  const top = candidates.slice(0, topK);
-  if (selected && !top.some((lem) => lem?.id === selected.id)) {
-    top.unshift(selected);
-    if (top.length > topK) top.pop();
-  }
-
-  return {
-    tickIndex,
-    selectedLemmingId: selected ? selected.id : null,
-    totalCount: inRect.length,
-    activeCount: activeInRect.length,
-    removedCount,
-    disabledCount,
-    byActionType: histAction,
-    byState: histState,
-    climbers,
-    floaters,
-    countingDown,
-    exploded,
-    selected,
-    top
-  };
-};
-
-const buildSkillInfo = (skills) => {
-  if (!skills) return null;
-  const counts = SKILL_NAMES.map((_, idx) => {
-    const skillIndex = idx + 1;
-    const raw = Array.isArray(skills.skills) ? skills.skills[skillIndex] ?? 0 : 0;
-    return Number.isFinite(raw) ? raw : 99;
-  });
-  const cheatMode = !!skills.cheatMode;
-  let availableMask = 0;
-  counts.forEach((count, idx) => {
-    if (cheatMode || count > 0) {
-      availableMask |= (1 << idx);
-    }
-  });
-  const selectedSkill = Number.isFinite(skills.selectedSkill) ? skills.selectedSkill : null;
-  const selectedSkillName = Number.isFinite(selectedSkill)
-    ? (SKILL_NAMES[selectedSkill - 1] || null)
-    : null;
-  return {
-    selectedSkill,
-    selectedSkillName,
-    cheatMode,
-    counts,
-    availableMask
-  };
-};
-
-const buildLemmingPrunePolicy = (state, skillInfo) => {
-  const lemmings = Array.isArray(state?.game?.lemmings) ? state.game.lemmings : [];
-  const availableMask = skillInfo?.availableMask ?? 0;
-  const hasClimb = lemmings.some((lem) => lem?.canClimb);
-  const hasParachute = lemmings.some((lem) => lem?.hasParachute);
-  const hasCountdown = lemmings.some((lem) => lem?.countdownActive);
-  const hasRemoved = lemmings.some((lem) => lem?.removed);
-  const hasDisabled = lemmings.some((lem) => lem?.disabled);
-  return {
-    includeClimb: (availableMask & (1 << 0)) !== 0 || hasClimb,
-    includeParachute: (availableMask & (1 << 1)) !== 0 || hasParachute,
-    includeCountdown: (availableMask & (1 << 2)) !== 0 || hasCountdown,
-    includeRemoved: hasRemoved,
-    includeDisabled: hasDisabled
-  };
-};
-
-const pruneLemming = (lem, policy) => {
-  if (!lem) return null;
-  const output = {
-    id: lem.id,
-    x: lem.x,
-    y: lem.y,
-    state: lem.state ?? null,
-    actionType: lem.actionType ?? null
-  };
-  if (policy?.includeClimb && lem.canClimb) output.canClimb = true;
-  if (policy?.includeParachute && lem.hasParachute) output.hasParachute = true;
-  if (policy?.includeCountdown) {
-    if (lem.countdownActive) output.countdownActive = true;
-    if (Number.isFinite(lem.countdown) && lem.countdown > 0) output.countdown = lem.countdown;
-  }
-  if (policy?.includeRemoved && lem.removed) output.removed = true;
-  if (policy?.includeDisabled && lem.disabled) output.disabled = true;
-  return output;
-};
-
-const buildLemmingSummaryCompact = (state, policy, options = {}) => {
-  const summary = buildLemmingSummary(state, options);
-  return {
-    ...summary,
-    selected: pruneLemming(summary.selected, policy),
-    top: Array.isArray(summary.top) ? summary.top.map((lem) => pruneLemming(lem, policy)) : []
-  };
-};
-
-const readPointer = (obj, pointer) => {
-  if (!pointer || pointer === '/') return obj;
-  const parts = String(pointer)
-    .split('/')
-    .slice(1)
-    .map((part) => part.replace(/~1/g, '/').replace(/~0/g, '~'));
-  let current = obj;
-  for (const part of parts) {
-    if (current == null) return undefined;
-    current = current[part];
-  }
-  return current;
-};
-
-const ensureGameFocus = async (session) => {
-  await ensureBlurred(session);
-};
-
-const pressKey = async (session, key) => {
-  const normalized = normalizeKeyChord(key);
-  if (!normalized) return;
-  await session.page.keyboard.press(normalized);
-};
-
-const pressAction = async (session, action, repeat = 1) => {
-  const bindings = session.keybindings?.bindings || {};
-  const chordList = bindings[action];
-  if (!Array.isArray(chordList) || chordList.length === 0) {
-    return { ok: false, reason: 'unknown_action' };
-  }
-  await ensureGameFocus(session);
-  for (let i = 0; i < repeat; i += 1) {
-    await pressKey(session, chordList[0]);
-  }
-  session.events.add({
-    source: 'agent',
-    type: 'input',
-    summary: `action:${action} x${repeat}`
-  });
-  return { ok: true, action, repeat };
-};
-
-const resolveCanvasMetrics = async (page) => page.evaluate(() => {
-  const canvas = document.getElementById('gameCanvas');
-  if (!canvas) return null;
-  const rect = canvas.getBoundingClientRect();
-  const stage = globalThis.lemmings?.stage;
-  const gameRect = stage?.gameImgProps?.canvasViewportSize
-    ? {
-      x: stage.gameImgProps.x,
-      y: stage.gameImgProps.y,
-      width: stage.gameImgProps.canvasViewportSize.width,
-      height: stage.gameImgProps.canvasViewportSize.height
-    }
-    : null;
-  const guiRect = stage?.guiImgProps?.canvasViewportSize
-    ? {
-      x: stage.guiImgProps.x,
-      y: stage.guiImgProps.y,
-      width: stage.guiImgProps.canvasViewportSize.width,
-      height: stage.guiImgProps.canvasViewportSize.height
-    }
-    : null;
-  return {
-    rect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
-    size: { width: canvas.width, height: canvas.height },
-    gameRect,
-    guiRect
-  };
-});
-
-const resolveCanvasClip = (metrics, target, rect) => {
-  if (!metrics) return null;
-  const scaleX = metrics.rect.width / metrics.size.width;
-  const scaleY = metrics.rect.height / metrics.size.height;
-
-  let base = null;
-  if (target === 'gameCanvas' && metrics.gameRect) {
-    base = metrics.gameRect;
-  } else if (target === 'guiCanvas' && metrics.guiRect) {
-    base = metrics.guiRect;
-  } else if (target === 'stageCanvas') {
-    base = null;
-  }
-
-  const baseCss = base
-    ? {
-      x: base.x * scaleX,
-      y: base.y * scaleY,
-      width: base.width * scaleX,
-      height: base.height * scaleY
-    }
-    : { x: 0, y: 0, width: metrics.rect.width, height: metrics.rect.height };
-
-  const clip = rect
-    ? {
-      x: baseCss.x + rect.x,
-      y: baseCss.y + rect.y,
-      width: rect.width,
-      height: rect.height
-    }
-    : baseCss;
-
-  return {
-    clip: {
-      x: metrics.rect.x + clip.x,
-      y: metrics.rect.y + clip.y,
-      width: clip.width,
-      height: clip.height
-    },
-    width: clip.width,
-    height: clip.height
-  };
-};
-
-const captureFrame = async (session, options) => {
-  const target = options.target || 'page';
-  const rect = options.rect || null;
-  const format = options.format || 'png';
-  const delivery = options.delivery || 'resource';
-  const tag = options.tag || null;
-  const mimeType = formatToMime(format);
-
-  let clip = null;
-  let width = null;
-  let height = null;
-
-  if (target === 'rect') {
-    if (!rect) return { ok: false, reason: 'rect_required' };
-    clip = rect;
-    width = rect?.width ?? null;
-    height = rect?.height ?? null;
-  } else if (target === 'gameCanvas' || target === 'guiCanvas' || target === 'stageCanvas') {
-    const metrics = await resolveCanvasMetrics(session.page);
-    if (!metrics) return { ok: false, reason: 'canvas_missing' };
-    const resolved = resolveCanvasClip(metrics, target, rect);
-    clip = resolved?.clip || null;
-    width = resolved?.width ?? null;
-    height = resolved?.height ?? null;
-  } else if (rect) {
-    clip = rect;
-    width = rect.width;
-    height = rect.height;
-  } else {
-    const viewport = session.page.viewportSize();
-    width = viewport?.width ?? null;
-    height = viewport?.height ?? null;
-  }
-
-  if (clip && (!Number.isFinite(clip.width) || !Number.isFinite(clip.height) || clip.width <= 0 || clip.height <= 0)) {
-    return { ok: false, reason: 'invalid_clip' };
-  }
-
-  const screenshotOptions = {
-    type: format
-  };
-  if (clip) {
-    screenshotOptions.clip = clip;
-  }
-
-  const bytes = await session.page.screenshot(screenshotOptions);
-  const sizeBytes = bytes.length;
-  const tickIndex = await getTickIndex(session);
-
-  const frame = {
-    id: makeId(),
-    mimeType,
-    width: Math.round(width ?? 0),
-    height: Math.round(height ?? 0),
-    tickIndex: Number.isFinite(tickIndex) ? tickIndex : null,
-    takenAt: nowIso(),
-    target,
-    tag: tag || undefined
-  };
-  if (rect) {
-    frame.clip = rect;
-  }
-
-  if (delivery === 'inline') {
-    frame.dataBase64 = Buffer.from(bytes).toString('base64');
-    return { ok: true, frame };
-  }
-
-  const stored = session.resources.put({
-    sessionId: session.id,
-    bytes,
-    mimeType,
-    meta: { kind: 'capture', target, tag }
-  });
-  frame.resourceUri = stored?.uri;
-  frame.sizeBytes = sizeBytes;
-  if (stored?.expiresAt) {
-    frame.expiresAt = stored.expiresAt;
-  }
-  return { ok: true, frame };
-};
-
-const captureSequence = async (session, args) => {
-  const frames = [];
-  const mode = args.mode;
-  const stepBy = Number.isFinite(args.stepBy) ? args.stepBy : 1;
-  const everyMs = Number.isFinite(args.everyMs) ? args.everyMs : 250;
-  const capture = args.capture || {};
-  const total = Math.max(1, args.frames);
-
-  if (mode === 'step') {
-    await callE2E(session, 'pause');
-  }
-
-  for (let i = 0; i < total; i += 1) {
-    const result = await captureFrame(session, capture);
-    if (result?.frame) frames.push(result.frame);
-    if (i === total - 1) break;
-    if (mode === 'step') {
-      await callE2E(session, 'step', stepBy);
-    } else {
-      await session.page.waitForTimeout(everyMs);
-    }
-  }
-
-  const sequenceId = makeId();
-  let manifestResourceUri = null;
-  if (args.returnManifest !== false) {
-    const manifest = {
-      sequenceId,
-      createdAt: nowIso(),
-      frames
-    };
-    const stored = session.resources.put({
-      sessionId: session.id,
-      bytes: Buffer.from(JSON.stringify(manifest)),
-      mimeType: 'application/json',
-      meta: { kind: 'capture-manifest' }
-    });
-    manifestResourceUri = stored?.uri || null;
-  }
-
-  session.events.add({
-    source: 'agent',
-    type: 'capture',
-    summary: `captureSequence:${sequenceId}`,
-    resourceUris: manifestResourceUri ? [manifestResourceUri] : undefined
-  });
-
-  return {
-    sequenceId,
-    frames,
-    manifestResourceUri
-  };
-};
-
-const startSpectatorServer = async (session, options = {}) => {
-  const html = await fs.readFile(SPECTATOR_HTML_PATH, 'utf8');
-  const port = Number.isFinite(options.port) ? options.port : 0;
-  const allowHumanInput = options.allowHumanInput === true;
-  const frameIntervalMs = 500;
-
-  const server = http.createServer((req, res) => {
-    if (req.url && req.url !== '/' && req.url !== '/index.html') {
-      res.writeHead(404);
-      res.end('Not found');
-      return;
-    }
-    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
-    res.end(html);
-  });
-
-  const wss = new WebSocketServer({ server });
-  const clients = new Set();
-
-  wss.on('connection', (ws) => {
-    clients.add(ws);
-    ws.send(JSON.stringify({ type: 'hello', allowHumanInput }));
-    if (session.spectator?.lastFrame) {
-      ws.send(JSON.stringify(session.spectator.lastFrame));
-    }
-    ws.on('message', async (data) => {
-      if (!allowHumanInput) return;
-      let payload;
-      try {
-        payload = JSON.parse(data.toString());
-      } catch (err) {
-        return;
-      }
-      await handleSpectatorInput(session, payload);
-    });
-    ws.on('close', () => {
-      clients.delete(ws);
-    });
-  });
-
-  await new Promise((resolve) => server.listen(port, '127.0.0.1', resolve));
-  const address = server.address();
-  const actualPort = typeof address === 'object' && address ? address.port : port;
-  const baseUrl = `http://127.0.0.1:${actualPort}`;
-
-  session.spectator = {
-    server,
-    wss,
-    clients,
-    allowHumanInput,
-    url: baseUrl,
-    lastFrame: null,
-    frameTimer: null,
-    isCapturing: false
-  };
-
-  session.spectator.frameTimer = setInterval(async () => {
-    if (session.spectator.isCapturing) return;
-    session.spectator.isCapturing = true;
-    try {
-      const result = await captureFrame(session, { target: 'stageCanvas', format: 'jpeg', delivery: 'inline' });
-      if (result.ok && result.frame?.dataBase64) {
-        const payload = {
-          type: 'frame',
-          mimeType: result.frame.mimeType,
-          dataBase64: result.frame.dataBase64
-        };
-        session.spectator.lastFrame = payload;
-        for (const ws of clients) {
-          if (ws.readyState === 1) {
-            ws.send(JSON.stringify(payload));
-          }
-        }
-      }
-    } catch (err) {
-      session.events.add({
-        source: 'system',
-        type: 'error',
-        summary: 'spectator capture failed',
-        data: { message: err ? String(err) : 'unknown' }
-      });
-    } finally {
-      session.spectator.isCapturing = false;
-    }
-  }, frameIntervalMs);
-
-  return baseUrl;
-};
-
-const handleSpectatorInput = async (session, payload) => {
-  if (!payload || !session.spectator?.allowHumanInput) return;
-  if (payload.type === 'key') {
-    const key = normalizeKeyToken(payload.key);
-    await ensureGameFocus(session);
-    if (payload.action === 'down') {
-      await session.page.keyboard.down(key);
-    } else if (payload.action === 'up') {
-      await session.page.keyboard.up(key);
-    }
-    session.events.add({
-      source: 'human',
-      type: 'input',
-      summary: `key:${payload.action}:${key}`
-    });
-    return;
-  }
-  if (payload.type === 'click') {
-    if (!Number.isFinite(payload.x) || !Number.isFinite(payload.y)) return;
-    const metrics = await resolveCanvasMetrics(session.page);
-    if (!metrics) return;
-    const x = metrics.rect.x + metrics.rect.width * payload.x;
-    const y = metrics.rect.y + metrics.rect.height * payload.y;
-    await session.page.mouse.click(x, y);
-    session.events.add({
-      source: 'human',
-      type: 'input',
-      summary: `click:${payload.x.toFixed(2)},${payload.y.toFixed(2)}`
-    });
-  }
-};
-
-const stopSpectatorServer = (session) => {
-  if (!session.spectator) return;
-  const { server, wss, frameTimer, clients } = session.spectator;
-  if (frameTimer) clearInterval(frameTimer);
-  for (const ws of clients || []) {
-    try {
-      ws.close();
-    } catch (err) {
-      // ignore
-    }
-  }
-  try {
-    wss?.close();
-  } catch (err) {
-    // ignore
-  }
-  try {
-    server?.close();
-  } catch (err) {
-    // ignore
-  }
-  session.spectator = null;
-};
-
-const startWatchLoop = (session) => {
-  if (session.watchTimer) return;
-  session.watchTimer = setInterval(() => pollWatches(session), 250);
-};
-
-const stopWatchLoop = (session) => {
-  if (session.watchTimer) {
-    clearInterval(session.watchTimer);
-  }
-  session.watchTimer = null;
-};
-
-const pollWatches = async (session) => {
-  if (session.watchPolling) return;
-  if (!session.watches.size) return;
-  session.watchPolling = true;
-  try {
-    const state = await getState(session);
-    if (!state) return;
-    const tickIndex = state.game?.timer?.tickIndex ?? null;
-    for (const watch of session.watches.values()) {
-      if (!watch.enabled) continue;
-      let triggered = false;
-      if (watch.type === 'everyTicks') {
-        if (Number.isFinite(tickIndex) && tickIndex - watch.lastTick >= watch.everyTicks) {
-          watch.lastTick = tickIndex;
-          triggered = true;
-        }
-      } else if (watch.type === 'onChange') {
-        const value = readPointer(state, watch.jsonPointer);
-        const serialized = JSON.stringify(value);
-        if (serialized !== watch.lastValue) {
-          watch.lastValue = serialized;
-          triggered = true;
-        }
-      }
-
-      if (!triggered) continue;
-      if (!Array.isArray(watch.actions) || !watch.actions.length) {
-        session.events.add({
-          source: 'system',
-          type: 'watch-trigger',
-          summary: `watch:${watch.id} triggered`,
-          tickIndex
-        });
-        continue;
-      }
-
-      for (const action of watch.actions) {
-        if (action.type === 'emitSummary') {
-          const data = {};
-          if (action.include?.lemmingsSummary) {
-            data.lemmingsSummary = buildLemmingSummary(state, {});
-          }
-          if (Array.isArray(action.include?.statePointers)) {
-            data.statePointers = {};
-            for (const pointer of action.include.statePointers) {
-              data.statePointers[pointer] = readPointer(state, pointer);
-            }
-          }
-          session.events.add({
-            source: 'system',
-            type: 'watch-trigger',
-            summary: `watch:${watch.id} summary`,
-            tickIndex,
-            data
-          });
-        } else if (action.type === 'capture') {
-          const throttle = action.throttleTicks ?? 0;
-          if (Number.isFinite(tickIndex) && throttle > 0 && tickIndex - watch.lastCaptureTick < throttle) {
-            continue;
-          }
-          const captureOptions = action.capture || { target: 'page', delivery: 'resource' };
-          const result = await captureFrame(session, captureOptions);
-          if (result.ok && result.frame?.resourceUri) {
-            watch.lastCaptureTick = Number.isFinite(tickIndex) ? tickIndex : watch.lastCaptureTick;
-            session.events.add({
-              source: 'system',
-              type: 'capture',
-              summary: `watch:${watch.id} capture`,
-              tickIndex,
-              resourceUris: [result.frame.resourceUri]
-            });
-          }
-        }
-      }
-    }
-  } finally {
-    session.watchPolling = false;
-  }
-};
-
-const createSession = async (args) => {
-  const options = SessionCreateSchema.parse(args || {});
-  const baseUrl = options.baseUrl || DEFAULT_BASE_URL;
-  const pathName = options.path || DEFAULT_PATH;
-  const gameUrl = new URL(pathName, baseUrl).toString();
-  const headless = options.headless !== false;
-  const viewport = options.viewport || DEFAULT_VIEWPORT;
-
-  const browser = await chromium.launch({
-    headless,
-    args: ['--allow-insecure-localhost']
-  });
-
-  const context = await browser.newContext({
-    viewport: {
-      width: viewport.width,
-      height: viewport.height
-    },
-    deviceScaleFactor: Number.isFinite(viewport.deviceScaleFactor) ? viewport.deviceScaleFactor : 1,
-    ignoreHTTPSErrors: true
-  });
-
-  const page = await context.newPage();
-  const sessionId = makeId();
-
-  const keybindings = await loadKeybindings();
-  const resources = new ResourceStore(options.resources || {});
-  const events = new EventQueue(options.events || {});
-
-  const session = {
-    id: sessionId,
-    browser,
-    context,
-    page,
-    baseUrl,
-    gameUrl,
-    keybindings,
-    resources,
-    events,
-    eventsMode: options.events?.mode || 'minimal',
-    lastStateTick: null,
-    watches: new Map(),
-    watchTimer: null,
-    watchPolling: false,
-    spectator: null
-  };
-
-  sessions.set(sessionId, session);
-
-  page.on('pageerror', (error) => {
-    session.events.add({
-      source: 'system',
-      type: 'error',
-      summary: 'pageerror',
-      data: { message: error?.message || String(error) }
-    });
-  });
-
-  page.on('console', (msg) => {
-    if (msg.type() === 'error') {
-      session.events.add({
-        source: 'system',
-        type: 'error',
-        summary: 'console error',
-        data: { message: msg.text() }
-      });
-    }
-  });
-
-  try {
-    await page.goto(gameUrl, { waitUntil: 'domcontentloaded' });
-    await page.waitForFunction(
-      () => window.__E2E__?.getState?.().ready === true,
-      null,
-      { timeout: 30000 }
-    );
-
-    if (options.enableSpectator) {
-      await startSpectatorServer(session, options.spectator || {});
-    }
-  } catch (err) {
-    sessions.delete(sessionId);
-    await context.close();
-    await browser.close();
-    throw err;
-  }
-
-  const actions = Object.keys(keybindings?.bindings || {}).sort();
-  const response = {
-    ok: true,
-    sessionId,
-    protocol: {
-      skillNames: SKILL_NAMES,
-      lemmingDeltaFields: LEMMING_DELTA_FIELDS
-    },
-    gameUrl,
-    spectatorUrl: session.spectator?.url || null,
-    keybindings: {
-      version: keybindings?.version || 1,
-      actions
-    },
-    warnings: []
-  };
-
-  if (options.spectator?.openBrowser) {
-    response.warnings.push('spectator openBrowser is not implemented');
-  }
-
-  return attachEvents(session, response);
-};
-
-const closeSession = async (args) => {
-  const { sessionId } = SessionCloseSchema.parse(args || {});
-  const session = getSession(sessionId);
-  stopSpectatorServer(session);
-  stopWatchLoop(session);
-  session.resources.clearSession(sessionId);
-  sessions.delete(sessionId);
-  await session.context.close();
-  await session.browser.close();
-  return { ok: true };
-};
-
-const pauseTime = async (args) => {
-  const { sessionId } = TimeSchema.parse(args || {});
-  const session = getSession(sessionId);
-  const result = await callE2E(session, 'pause');
-  const tickIndex = await getTickIndex(session);
-  return attachEvents(session, {
-    ok: !!result.ok && !!result.value,
-    tickIndex
-  });
-};
-
-const resumeTime = async (args) => {
-  const { sessionId } = TimeSchema.parse(args || {});
-  const session = getSession(sessionId);
-  const result = await callE2E(session, 'resume');
-  const tickIndex = await getTickIndex(session);
-  return attachEvents(session, {
-    ok: !!result.ok && !!result.value,
-    tickIndex
-  });
-};
-
-const stepTime = async (args) => {
-  const { sessionId, count, ensurePaused } = TimeStepSchema.parse(args || {});
-  const session = getSession(sessionId);
-  if (ensurePaused !== false) {
-    await callE2E(session, 'pause');
-  }
-  const tickIndexBefore = await getTickIndex(session);
-  const result = await callE2E(session, 'step', count);
-  const tickIndexAfter = await getTickIndex(session);
-  return attachEvents(session, {
-    ok: !!result.ok && !!result.value,
-    tickIndexBefore,
-    tickIndexAfter
-  });
-};
-
-const getStateTool = async (args) => {
-  const { sessionId, preset, include, lemmings, format } = StateGetSchema.parse(args || {});
-  const session = getSession(sessionId);
-  const raw = await getState(session);
-  if (!raw) {
-    return attachEvents(session, { ok: false, reason: 'harness_unavailable' });
-  }
-
-  const tickIndex = raw?.game?.timer?.tickIndex ?? null;
-  if (Number.isFinite(tickIndex)) {
-    session.lastStateTick = tickIndex;
-  }
-
-  const effectivePreset = preset || 'compact';
-  const includeFlags = {
-    view: false,
-    stage: false,
-    game: true,
-    editor: false,
-    midi: false,
-    ...(include || {})
-  };
-
-  const skillInfo = raw.game ? buildSkillInfo(raw.game.skills) : null;
-  const lemmingPolicy = raw.game ? buildLemmingPrunePolicy(raw, skillInfo) : null;
-
-  let snapshot;
-  if (effectivePreset === 'debug') {
-    snapshot = filterStateSnapshot(raw, includeFlags);
-    if (snapshot.game && skillInfo) {
-      snapshot.game.skillsInfo = skillInfo;
-    }
-  } else {
-    snapshot = {
-      version: raw.version,
-      mode: raw.mode,
-      ready: raw.ready
-    };
-    if (includeFlags.view) snapshot.view = raw.view;
-    if (includeFlags.stage) {
-      snapshot.stage = raw.stage ? { viewRect: raw.stage.viewRect } : raw.stage;
-    }
-    if (includeFlags.game && raw.game) {
-      snapshot.game = {
-        state: raw.game.state ?? null,
-        finalGameState: raw.game.finalGameState ?? null,
-        timer: raw.game.timer ? {
-          tickIndex: raw.game.timer.tickIndex,
-          running: raw.game.timer.running,
-          speedFactor: raw.game.timer.speedFactor
-        } : null,
-        victory: raw.game.victory ? {
-          leftCount: raw.game.victory.leftCount,
-          outCount: raw.game.victory.outCount,
-          survivorCount: raw.game.victory.survivorCount,
-          releaseRate: raw.game.victory.releaseRate,
-          minReleaseRate: raw.game.victory.minReleaseRate,
-          isFinalize: raw.game.victory.isFinalize
-        } : null,
-        level: raw.game.level ? {
-          name: raw.game.level.name,
-          width: raw.game.level.width,
-          height: raw.game.level.height,
-          releaseCount: raw.game.level.releaseCount,
-          needCount: raw.game.level.needCount,
-          timeLimit: raw.game.level.timeLimit,
-          isSuperLemming: raw.game.level.isSuperLemming
-        } : null,
-        skills: skillInfo,
-        lemmingManager: raw.game.lemmingManager ? {
-          selectedIndex: raw.game.lemmingManager.selectedIndex,
-          activeCount: raw.game.lemmingManager.activeCount,
-          totalCount: raw.game.lemmingManager.totalCount,
-          spawnTotal: raw.game.lemmingManager.spawnTotal,
-          releaseTickIndex: raw.game.lemmingManager.releaseTickIndex,
-          nukeTargets: raw.game.lemmingManager.nukeTargets
-        } : null,
-        lemmings: []
-      };
-    }
-  }
-
-  const lemmingOpts = lemmings || {};
-  const mode = lemmingOpts.mode || 'summary';
-
-  if (snapshot.game) {
-    if (mode === 'none') {
-      snapshot.game.lemmings = [];
-    } else if (mode === 'summary') {
-      snapshot.game.lemmings = [];
-      const summary = effectivePreset === 'debug'
-        ? buildLemmingSummary(raw, {
-          activeOnly: lemmingOpts.activeOnly !== false,
-          inViewOnly: !!lemmingOpts.inViewOnly,
-          rectWorld: lemmingOpts.rectWorld,
-          topK: lemmingOpts.topK,
-          includeSelected: lemmingOpts.includeSelected
-        })
-        : buildLemmingSummaryCompact(raw, lemmingPolicy, {
-          activeOnly: lemmingOpts.activeOnly !== false,
-          inViewOnly: !!lemmingOpts.inViewOnly,
-          rectWorld: lemmingOpts.rectWorld,
-          topK: lemmingOpts.topK,
-          includeSelected: lemmingOpts.includeSelected
-        });
-      snapshot.game.lemmingsSummary = summary;
-    } else if (mode === 'selected') {
-      snapshot.game.lemmings = [];
-      const selectedIndex = raw?.game?.lemmingManager?.selectedIndex;
-      const selected = Number.isFinite(selectedIndex) ? raw?.game?.lemmings?.[selectedIndex] : null;
-      snapshot.game.selectedLemmingId = selected ? selected.id : null;
-      snapshot.game.selectedLemming = effectivePreset === 'debug'
-        ? selected
-        : pruneLemming(selected, lemmingPolicy);
-    } else if (mode === 'ids') {
-      const ids = Array.isArray(lemmingOpts.ids) ? lemmingOpts.ids : [];
-      snapshot.game.lemmingsIds = ids;
-      snapshot.game.lemmings = ids.map((id) => {
-        const lem = raw.game?.lemmings?.[id] || null;
-        return effectivePreset === 'debug' ? lem : pruneLemming(lem, lemmingPolicy);
-      });
-    } else {
-      const max = lemmingOpts.max || raw.game?.lemmings?.length || 0;
-      const slice = raw.game?.lemmings?.slice(0, max) || [];
-      snapshot.game.lemmings = effectivePreset === 'debug'
-        ? slice
-        : slice.map((lem) => pruneLemming(lem, lemmingPolicy));
-    }
-  }
-
-  const delivery = format?.delivery || 'inline';
-  if (delivery === 'resource') {
-    const json = JSON.stringify(snapshot, null, format?.pretty ? 2 : 0);
-    const stored = session.resources.put({
-      sessionId: session.id,
-      bytes: Buffer.from(json),
-      mimeType: 'application/json',
-      meta: { kind: 'state' }
-    });
-    return attachEvents(session, {
-      ok: true,
-      tickIndex,
-      preset: effectivePreset,
-      resourceUri: stored?.uri || null,
-      sizeBytes: stored?.sizeBytes ?? null
-    });
-  }
-
-  const response = {
-    ok: true,
-    tickIndex,
-    preset: effectivePreset,
-    snapshot
-  };
-
-  if (format?.includeSizeEstimate) {
-    response.sizeBytesEstimate = Buffer.byteLength(JSON.stringify(snapshot));
-  }
-
-  return attachEvents(session, response);
-};
-
-const getStateDeltaTool = async (args) => {
-  const { sessionId, afterTick, toTick, maxTicks, include, lemmings, format } = StateDeltaSchema.parse(args || {});
-  const session = getSession(sessionId);
-  const currentTick = await getTickIndex(session);
-  if (!Number.isFinite(currentTick)) {
-    return attachEvents(session, { ok: false, reason: 'tick_index_unavailable' });
-  }
-
-  const effectiveAfter = Number.isFinite(afterTick)
-    ? afterTick
-    : (Number.isFinite(session.lastStateTick) ? session.lastStateTick : (currentTick - 1));
-  const effectiveTo = Number.isFinite(toTick) ? toTick : currentTick;
-
-  let startTick = Math.trunc(effectiveAfter + 1);
-  let endTick = Math.trunc(effectiveTo);
-  if (startTick > endTick) {
-    return attachEvents(session, {
-      ok: true,
-      cursor: endTick,
-      afterTick: effectiveAfter,
-      toTick: endTick,
-      deltas: []
-    });
-  }
-
-  const limit = Number.isFinite(maxTicks) ? Math.max(1, Math.trunc(maxTicks)) : 10;
-  if ((endTick - startTick + 1) > limit) {
-    startTick = endTick - limit + 1;
-  }
-
-  const inc = {
-    lemmings: true,
-    lemmingManager: true,
-    skills: true,
-    victory: true,
-    timer: true,
-    game: false,
-    sound: false,
-    minimap: false,
-    triggers: false,
-    objects: false,
-    ground: false,
-    entrances: false,
-    ...(include || {})
-  };
-
-  const lemOpts = {
-    fields: Array.isArray(lemmings?.fields) ? lemmings.fields : DEFAULT_LEM_DELTA_FIELDS,
-    includePrev: lemmings?.includePrev === true,
-    includeXY: lemmings?.includeXY || 'none',
-    trackedIds: Array.isArray(lemmings?.trackedIds) ? lemmings.trackedIds : [],
-    maxChanges: Number.isFinite(lemmings?.maxChanges) ? Math.max(1, Math.trunc(lemmings.maxChanges)) : 250
-  };
-
-  const fieldSet = new Set(lemOpts.fields);
-  const trackedSet = new Set(lemOpts.trackedIds);
-
-  const deltaRes = await callE2E(session, 'getDeltas', startTick, endTick, limit);
-  if (!deltaRes.ok) {
-    return attachEvents(session, { ok: false, reason: 'delta_unavailable', error: deltaRes.error || null });
-  }
-  const deltasRaw = Array.isArray(deltaRes.value) ? deltaRes.value : [];
-
-  const filteredDeltas = [];
-  for (const delta of deltasRaw) {
-    if (!delta || typeof delta !== 'object') continue;
-    const out = { tick: delta.tick };
-
-    if (inc.lemmings) {
-      const lemChanges = delta.lemChanges;
-      if (lemChanges && Array.isArray(lemChanges.ids) && Array.isArray(lemChanges.fields) && Array.isArray(lemChanges.next)) {
-        const ids = [];
-        const fields = [];
-        const next = [];
-        const prev = [];
-
-        for (let i = 0; i < lemChanges.ids.length; i += 1) {
-          if (ids.length >= lemOpts.maxChanges) break;
-          const id = lemChanges.ids[i];
-          const field = lemChanges.fields[i];
-
-          if (!fieldSet.has(field)) continue;
-          if ((field === 0 || field === 1) && lemOpts.includeXY === 'none') continue;
-          if ((field === 0 || field === 1) && lemOpts.includeXY === 'tracked' && !trackedSet.has(id)) continue;
-
-          ids.push(id);
-          fields.push(field);
-          next.push(lemChanges.next[i]);
-          if (lemOpts.includePrev && Array.isArray(lemChanges.prev)) {
-            prev.push(lemChanges.prev[i]);
-          }
-        }
-
-        if (ids.length > 0) {
-          out.lemChanges = {
-            ids,
-            fields,
-            ...(lemOpts.includePrev ? { prev } : {}),
-            next
-          };
-        }
-      }
-
-      if (Array.isArray(delta.lemAdded) && delta.lemAdded.length > 0) {
-        out.lemAddedIds = delta.lemAdded.map((lem) => lem?.id).filter((id) => Number.isFinite(id));
-      }
-      if (Array.isArray(delta.lemRemoved) && delta.lemRemoved.length > 0) {
-        out.lemRemovedIds = delta.lemRemoved.map((lem) => lem?.id).filter((id) => Number.isFinite(id));
-      }
-    }
-
-    if (inc.lemmingManager && delta.lemmingManagerChanges) out.lemmingManagerChanges = delta.lemmingManagerChanges;
-    if (inc.skills && delta.skillsChanges) out.skillsChanges = delta.skillsChanges;
-    if (inc.victory && delta.victoryChanges) out.victoryChanges = delta.victoryChanges;
-    if (inc.timer && delta.timerChanges) out.timerChanges = delta.timerChanges;
-    if (inc.game && delta.gameChanges) out.gameChanges = delta.gameChanges;
-
-    if (inc.sound && Array.isArray(delta.soundEvents) && delta.soundEvents.length > 0) out.soundEvents = delta.soundEvents;
-    if (inc.minimap && Array.isArray(delta.minimapDeaths) && delta.minimapDeaths.length > 0) out.minimapDeaths = delta.minimapDeaths;
-
-    if (inc.triggers) {
-      if (Array.isArray(delta.triggerCooldownChanges) && delta.triggerCooldownChanges.length > 0) {
-        out.triggerCooldownChanges = delta.triggerCooldownChanges;
-      }
-      if (Array.isArray(delta.triggerAdd) && delta.triggerAdd.length > 0) out.triggerAdd = delta.triggerAdd;
-      if (Array.isArray(delta.triggerRemove) && delta.triggerRemove.length > 0) out.triggerRemove = delta.triggerRemove;
-    }
-
-    if (inc.objects && Array.isArray(delta.objectAnimChanges) && delta.objectAnimChanges.length > 0) {
-      out.objectAnimChanges = delta.objectAnimChanges;
-    }
-    if (inc.ground && delta.groundChanges) out.groundChanges = delta.groundChanges;
-    if (inc.entrances && delta.entranceChanges) out.entranceChanges = delta.entranceChanges;
-
-    filteredDeltas.push(out);
-  }
-
-  const response = {
-    ok: true,
-    cursor: endTick,
-    afterTick: effectiveAfter,
-    fromTick: startTick,
-    toTick: endTick,
-    deltas: filteredDeltas
-  };
-
-  const delivery = format?.delivery || 'inline';
-  if (delivery === 'resource') {
-    const json = JSON.stringify(response, null, format?.pretty ? 2 : 0);
-    const stored = session.resources.put({
-      sessionId: session.id,
-      bytes: Buffer.from(json),
-      mimeType: 'application/json',
-      meta: { kind: 'state-delta' }
-    });
-    return attachEvents(session, {
-      ok: true,
-      cursor: endTick,
-      resourceUri: stored?.uri || null,
-      sizeBytes: stored?.sizeBytes ?? null
-    });
-  }
-
-  return attachEvents(session, response);
-};
-
-const editorApplyTool = async (args) => {
-  const parsed = EditorApplySchema.parse(args || {});
-  const session = getSession(parsed.sessionId);
-  const result = await callE2E(session, 'editorApply', parsed.ops || [], {
-    atomic: parsed.atomic,
-    dryRun: parsed.dryRun,
-    history: parsed.history,
-    preview: parsed.preview,
-    validate: parsed.validate,
-    returnState: parsed.returnState
-  });
-  if (!result.ok) {
-    return attachEvents(session, {
-      ok: false,
-      reason: 'harness_unavailable',
-      error: result.error || null
-    });
-  }
-
-  const payload = result.value || {};
-  if (!payload.ok) {
-    return attachEvents(session, payload);
-  }
-
-  const resources = [];
-  if (Array.isArray(payload.resources)) {
-    for (const resource of payload.resources) {
-      if (!resource) continue;
-      const encoding = resource.encoding || 'text';
-      const data = resource.data || '';
-      const bytes = encoding === 'base64'
-        ? Buffer.from(data, 'base64')
-        : Buffer.from(data, 'utf8');
-      const mimeType = resource.mimeType || 'application/octet-stream';
-      const stored = session.resources.put({
-        sessionId: session.id,
-        bytes,
-        mimeType,
-        meta: resource.meta || { kind: 'resource', name: resource.name || '' }
-      });
-      resources.push({
-        uri: stored?.uri || null,
-        mimeType,
-        name: resource.name || null,
-        sizeBytes: stored?.sizeBytes ?? null,
-        meta: resource.meta || null
-      });
-    }
-  }
-
-  return attachEvents(session, {
-    ok: true,
-    results: Array.isArray(payload.results) ? payload.results : [],
-    state: payload.state ?? null,
-    resources
-  });
-};
-
-const getLemmingsSummaryTool = async (args) => {
-  const { sessionId, filter, topK, includeSelected } = LemmingsSummarySchema.parse(args || {});
-  const session = getSession(sessionId);
-  const state = await getState(session);
-  if (!state) {
-    return attachEvents(session, { ok: false, reason: 'harness_unavailable' });
-  }
-  const summary = buildLemmingSummary(state, {
-    activeOnly: filter?.activeOnly !== false,
-    inViewOnly: !!filter?.inViewOnly,
-    rectWorld: filter?.rectWorld,
-    topK,
-    includeSelected
-  });
-  return attachEvents(session, summary);
-};
-
-const centerViewOnLemming = async (session, lemmingId) => session.page.evaluate((id) => {
-  const view = globalThis.lemmings;
-  const stage = view?.stage;
-  const manager = view?.game?.getLemmingManager?.();
-  const lem = manager?.getLemming?.(id);
-  if (!stage || !lem) return false;
-  const rect = stage.getGameViewRect?.();
-  if (!rect) return false;
-  stage.gameImgProps.viewPoint.x = lem.x - rect.w / 2;
-  stage.gameImgProps.viewPoint.y = lem.y - rect.h / 2;
-  view?.render?.();
-  return true;
-}, lemmingId);
-
-const selectLemmingTool = async (args) => {
-  const { sessionId, lemmingId, alsoCenterView, confirm } = LemmingSelectSchema.parse(args || {});
-  const session = getSession(sessionId);
-  const result = await callE2E(session, 'selectLemmingById', lemmingId);
-  if (!result.ok || !result.value) {
-    const state = await getState(session);
-    const entry = state?.game?.lemmings?.[lemmingId] || null;
-    let reason = 'harness_unavailable';
-    if (entry) {
-      if (entry.removed) reason = 'removed';
-      else if (entry.disabled) reason = 'disabled';
-      else reason = 'not_found';
-    } else {
-      reason = 'not_found';
-    }
-    return attachEvents(session, {
-      ok: false,
-      lemmingId,
-      reason
-    });
-  }
-
-  if (alsoCenterView) {
-    await centerViewOnLemming(session, lemmingId);
-  }
+import { ALL_TOOL_SURFACES, buildSurfaceRegistry, parseEnabledSurfaces } from './tools/surfaces.js';
+import { EventQueue } from './eventQueue.js';
+import {
+  WatchPollingController,
+  readPointerValue,
+  createPointerWatchState,
+  updatePointerWatchState
+} from './watchPolling.js';
+import { ResourceStore } from './resourceStore.js';
+import { getSession, normalizeSessionId, sessions } from './sessionStore.js';
+import { attachEvents } from './eventEnvelope.js';
+import { disposeAllSessionRuntimes, disposeSessionRuntime } from './sessionLifecycle.js';
+import { buildLemmingSummary } from './lemmingSummary.js';
+import { createStateToolHandlers } from './stateTools.js';
+import { createSpectatorTools } from './spectatorTools.js';
+import { createShutdownController } from './shutdownController.js';
+import { createEditorObjectToolHandlers } from './editorObjectTools.js';
+import { createVisionToolHandlers } from './visionTools.js';
+import { createGameToolHandlers } from './gameTools.js';
+import { createSessionToolHandlers } from './sessionTools.js';
+import { createWatchToolHandlers } from './watchTools.js';
+import { createSolverToolHandlers } from './solverTools.js';
+import { createServerHelpers } from './serverHelpers.js';
+import {
+  buildProtocolMetadata,
+  buildToolResponse,
+  formatToMime,
+  makeId,
+  normalizeKeyChord,
+  normalizeKeyToken,
+  nowIso,
+  toToolName
+} from './protocolMetadata.js';
+import {
+  buildToolCatalog,
+  resolveToolName
+} from './toolRouting.js';
 
-  let selectedNow = null;
-  if (confirm !== false) {
-    const state = await getState(session);
-    selectedNow = state?.game?.lemmingManager?.selectedIndex ?? null;
-  }
+import {
+  DEFAULT_LEM_DELTA_FIELDS,
+  EditorApplySchema,
+  EventsPollSchema,
+  InputActionSchema,
+  InputKeysSchema,
+  LEMMING_DELTA_FIELDS,
+  LemmingsSummarySchema,
+  LemmingSelectSchema,
+  MCP_MAX_CAPTURE_SEQUENCE_FRAMES,
+  MCP_PROTOCOL_SCHEMA_FROZEN_AT,
+  MCP_PROTOCOL_VERSION,
+  ObjectsDeleteSchema,
+  ObjectsListSchema,
+  ObjectsPlaceSchema,
+  ObjectsUpdateSchema,
+  SKILL_ACTIONS,
+  SKILL_INDEX_BY_NAME,
+  SKILL_NAMES,
+  SessionCloseSchema,
+  SessionCreateSchema,
+  SkillApplySchema,
+  SolverReplaySchema,
+  SolverRouteSchema,
+  SolverSnapshotSchema,
+  StateDeltaSchema,
+  StateGetSchema,
+  TimeSchema,
+  TimeStepSchema,
+  VisionCaptureSchema,
+  VisionSequenceSchema,
+  WatchCancelSchema,
+  WatchCreateSchema
+} from './schemas.js';
 
-  return attachEvents(session, {
-    ok: true,
-    lemmingId,
-    selectedNow
-  });
-};
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT_DIR = path.resolve(__dirname, '..');
+const KEYBINDINGS_PATH = path.join(ROOT_DIR, 'keybindings.json');
+const SPECTATOR_HTML_PATH = path.join(__dirname, 'spectator.html');
 
-const applySkillTool = async (args) => {
-  const { sessionId, skill, lemmingId, ensurePaused, requireAvailable, postStep, verify } =
-    SkillApplySchema.parse(args || {});
-  const session = getSession(sessionId);
-  if (ensurePaused !== false) {
-    await callE2E(session, 'pause');
-  }
+const DEFAULT_BASE_URL = process.env.LEMMINGS_MCP_BASE_URL || 'https://localhost:8080';
+const DEFAULT_PATH = process.env.LEMMINGS_MCP_PATH || '/?e2e=1';
+const DEFAULT_VIEWPORT = { width: 1280, height: 720, deviceScaleFactor: 1 };
+const ENABLED_TOOL_SURFACES = parseEnabledSurfaces(process.env.LEMMINGS_MCP_SURFACES);
 
-  let tickIndexBefore = null;
-  let tickIndexAfter = null;
-  let beforeState = null;
-  if (verify !== false || requireAvailable) {
-    beforeState = await getState(session);
-    tickIndexBefore = beforeState?.game?.timer?.tickIndex ?? null;
-  }
+const RESOURCE_URI_RE = /^lemmings:\/\/sessions\/([^/]+)\/resources\/([^/]+)$/;
 
-  const action = SKILL_ACTIONS[skill];
-  if (!action) {
-    return attachEvents(session, { ok: false, reason: 'unknown_skill', skill });
-  }
 
-  if (requireAvailable) {
-    const skills = beforeState?.game?.skills || null;
-    const skillIndex = SKILL_INDEX_BY_NAME[skill];
-    const available = !!skills?.cheatMode || (Number.isFinite(skillIndex)
-      && Array.isArray(skills?.skills)
-      && skills.skills[skillIndex] > 0);
-    if (!available) {
-      return attachEvents(session, { ok: false, reason: 'no_skill_remaining', skill });
-    }
-  }
+const {
+  loadKeybindings,
+  callE2E,
+  getState,
+  getTickIndex,
+  filterStateSnapshot,
+  buildSkillInfo,
+  buildLemmingPrunePolicy,
+  pruneLemming,
+  buildLemmingSummaryCompact,
+  ensureGameFocus,
+  pressKey,
+  pressAction
+} = createServerHelpers({
+  fs,
+  keybindingsPath: KEYBINDINGS_PATH,
+  normalizeKeyChord,
+  skillNames: SKILL_NAMES,
+  buildLemmingSummary
+});
 
-  if (Number.isFinite(lemmingId)) {
-    const selectResult = await callE2E(session, 'selectLemmingById', lemmingId);
-    if (!selectResult.ok || !selectResult.value) {
-      return attachEvents(session, {
-        ok: false,
-        skill,
-        lemmingIdAppliedTo: lemmingId,
-        reason: 'select_failed'
-      });
-    }
-  }
+const {
+  captureFrame,
+  captureSequence,
+  resolveCanvasMetrics,
+  visionCaptureTool,
+  visionSequenceTool
+} = createVisionToolHandlers({
+  schemas: { VisionCaptureSchema, VisionSequenceSchema },
+  getSession,
+  callE2E,
+  getTickIndex,
+  attachEvents,
+  formatToMime,
+  makeId,
+  nowIso,
+  maxCaptureSequenceFrames: MCP_MAX_CAPTURE_SEQUENCE_FRAMES
+});
 
-  const selectKey = await pressAction(session, action, 1);
-  if (!selectKey.ok) {
-    return attachEvents(session, { ok: false, reason: 'missing_binding', skill, action });
-  }
-  const applyKey = await pressAction(session, 'applySkillToSelected', 1);
-  if (!applyKey.ok) {
-    return attachEvents(session, { ok: false, reason: 'missing_binding', action: 'applySkillToSelected' });
-  }
+const { startSpectatorServer, stopSpectatorServer } = createSpectatorTools({
+  spectatorHtmlPath: SPECTATOR_HTML_PATH,
+  captureFrame,
+  resolveCanvasMetrics,
+  normalizeKeyToken,
+  ensureGameFocus
+});
 
-  const steps = Number.isFinite(postStep) ? Math.trunc(postStep) : 1;
-  if (steps > 0) {
-    await callE2E(session, 'step', steps);
-  }
+const {
+  startWatchLoop,
+  stopWatchLoop,
+  requestWatchPoll,
+  nudgeWatchPolling,
+  pollWatches,
+  watchCreateTool,
+  watchCancelTool,
+  eventsPollTool
+} = createWatchToolHandlers({
+  schemas: { EventsPollSchema, WatchCancelSchema, WatchCreateSchema },
+  getSession,
+  getState,
+  attachEvents,
+  makeId,
+  readPointerValue,
+  createPointerWatchState,
+  updatePointerWatchState,
+  buildLemmingSummary,
+  captureFrame,
+  pressAction,
+  pressKey
+});
 
-  let verification = null;
-  let lemmingIdAppliedTo = lemmingId ?? null;
-  if (verify !== false) {
-    const afterState = await getState(session);
-    tickIndexAfter = afterState?.game?.timer?.tickIndex ?? null;
-    const selectedId = afterState?.game?.lemmingManager?.selectedIndex ?? null;
-    lemmingIdAppliedTo = Number.isFinite(lemmingIdAppliedTo) ? lemmingIdAppliedTo : selectedId;
-    const beforeLem = lemmingIdAppliedTo != null
-      ? beforeState?.game?.lemmings?.[lemmingIdAppliedTo] || null
-      : null;
-    const afterLem = lemmingIdAppliedTo != null
-      ? afterState?.game?.lemmings?.[lemmingIdAppliedTo] || null
-      : null;
-    const changedFields = [];
-    let applied = false;
-    if (beforeLem && afterLem) {
-      if (skill === 'climber' && !beforeLem.canClimb && afterLem.canClimb) {
-        applied = true;
-        changedFields.push('canClimb');
-      } else if (skill === 'floater' && !beforeLem.hasParachute && afterLem.hasParachute) {
-        applied = true;
-        changedFields.push('hasParachute');
-      } else if (skill === 'bomber' && !beforeLem.countdownActive && afterLem.countdownActive) {
-        applied = true;
-        changedFields.push('countdownActive');
-      } else if (beforeLem.actionType !== afterLem.actionType) {
-        applied = true;
-        changedFields.push('actionType');
-      }
-    }
-    verification = {
-      applied,
-      changedFields
-    };
-  }
+const {
+  getStateTool,
+  getStateDeltaTool,
+  getLemmingsSummaryTool
+} = createStateToolHandlers({
+  schemas: {
+    StateGetSchema,
+    StateDeltaSchema,
+    LemmingsSummarySchema
+  },
+  attachEvents,
+  getSession,
+  callE2E,
+  getState,
+  getTickIndex,
+  nudgeWatchPolling,
+  helpers: {
+    filterStateSnapshot,
+    buildSkillInfo,
+    buildLemmingPrunePolicy,
+    buildLemmingSummary,
+    buildLemmingSummaryCompact,
+    pruneLemming
+  },
+  defaultLemDeltaFields: DEFAULT_LEM_DELTA_FIELDS
+});
 
-  return attachEvents(session, {
-    ok: true,
-    skill,
-    lemmingIdAppliedTo,
-    tickIndexBefore,
-    tickIndexAfter,
-    verification
-  });
-};
+const { createSession, closeSession } = createSessionToolHandlers({
+  schemas: { SessionCloseSchema, SessionCreateSchema },
+  chromium,
+  ResourceStore,
+  EventQueue,
+  WatchPollingController,
+  sessions,
+  normalizeSessionId,
+  getSession,
+  disposeSessionRuntime,
+  loadKeybindings,
+  pollWatches,
+  startSpectatorServer,
+  stopSpectatorServer,
+  stopWatchLoop,
+  createProtocolMetadata: () => createProtocolMetadata(),
+  attachEvents,
+  defaults: { DEFAULT_BASE_URL, DEFAULT_PATH, DEFAULT_VIEWPORT },
+  makeId
+});
 
-const inputActionTool = async (args) => {
-  const { sessionId, action, repeat } = InputActionSchema.parse(args || {});
-  const session = getSession(sessionId);
-  return attachEvents(session, await pressAction(session, action, repeat || 1));
-};
+const {
+  pauseTime,
+  resumeTime,
+  stepTime,
+  selectLemmingTool,
+  applySkillTool,
+  inputActionTool,
+  inputKeysTool
+} = createGameToolHandlers({
+  schemas: {
+    InputActionSchema,
+    InputKeysSchema,
+    LemmingSelectSchema,
+    SkillApplySchema,
+    TimeSchema,
+    TimeStepSchema
+  },
+  getSession,
+  getState,
+  getTickIndex,
+  callE2E,
+  attachEvents,
+  nudgeWatchPolling,
+  ensureGameFocus,
+  pressAction,
+  pressKey,
+  normalizeKeyToken,
+  skillActions: SKILL_ACTIONS,
+  skillIndexByName: SKILL_INDEX_BY_NAME
+});
 
-const inputKeysTool = async (args) => {
-  const { sessionId, keys, repeat, events } = InputKeysSchema.parse(args || {});
-  const session = getSession(sessionId);
-  await ensureGameFocus(session);
-  let injected = 0;
+const {
+  editorApplyTool,
+  listObjectsTool,
+  placeObjectsTool,
+  updateObjectsTool,
+  deleteObjectsTool
+} = createEditorObjectToolHandlers({
+  schemas: {
+    EditorApplySchema,
+    ObjectsDeleteSchema,
+    ObjectsListSchema,
+    ObjectsPlaceSchema,
+    ObjectsUpdateSchema
+  },
+  getSession,
+  getState,
+  callE2E,
+  attachEvents,
+  nudgeWatchPolling
+});
 
-  if (Array.isArray(keys) && keys.length) {
-    const count = repeat || 1;
-    for (let i = 0; i < count; i += 1) {
-      for (const key of keys) {
-        await pressKey(session, key);
-        injected += 1;
-      }
-    }
-  } else if (Array.isArray(events)) {
-    for (const event of events) {
-      const key = normalizeKeyToken(event.key);
-      if (event.type === 'down') {
-        await session.page.keyboard.down(key);
-      } else if (event.type === 'up') {
-        await session.page.keyboard.up(key);
-      } else {
-        await session.page.keyboard.press(key);
-      }
-      injected += 1;
-    }
+const {
+  solverSnapshotTool,
+  solverRouteTool,
+  solverReplayTool
+} = createSolverToolHandlers({
+  schemas: {
+    SolverSnapshotSchema,
+    SolverRouteSchema,
+    SolverReplaySchema
   }
+});
 
-  if (injected) {
-    session.events.add({
-      source: 'agent',
-      type: 'input',
-      summary: `keys:${injected}`
-    });
+const TOOL_SCHEMA_REGISTRY = {
+  SessionCreateSchema,
+  SessionCloseSchema,
+  TimeSchema,
+  TimeStepSchema,
+  StateGetSchema,
+  StateDeltaSchema,
+  EditorApplySchema,
+  ObjectsListSchema,
+  ObjectsPlaceSchema,
+  ObjectsUpdateSchema,
+  ObjectsDeleteSchema,
+  LemmingsSummarySchema,
+  LemmingSelectSchema,
+  SkillApplySchema,
+  InputActionSchema,
+  InputKeysSchema,
+  VisionCaptureSchema,
+  VisionSequenceSchema,
+  WatchCreateSchema,
+  WatchCancelSchema,
+  EventsPollSchema,
+  SolverSnapshotSchema,
+  SolverRouteSchema,
+  SolverReplaySchema
+};
+
+const TOOL_HANDLER_REGISTRY = {
+  createSession,
+  closeSession,
+  pauseTime,
+  resumeTime,
+  stepTime,
+  getStateTool,
+  getStateDeltaTool,
+  editorApplyTool,
+  listObjectsTool,
+  placeObjectsTool,
+  updateObjectsTool,
+  deleteObjectsTool,
+  getLemmingsSummaryTool,
+  selectLemmingTool,
+  applySkillTool,
+  inputActionTool,
+  inputKeysTool,
+  visionCaptureTool,
+  visionSequenceTool,
+  watchCreateTool,
+  watchCancelTool,
+  eventsPollTool,
+  solverSnapshotTool,
+  solverRouteTool,
+  solverReplayTool
+};
+
+const ACTIVE_TOOL_SURFACES = ENABLED_TOOL_SURFACES;
+
+const surfaceRegistry = buildSurfaceRegistry(
+  TOOL_SCHEMA_REGISTRY,
+  TOOL_HANDLER_REGISTRY,
+  new Set(ALL_TOOL_SURFACES)
+);
+const { toolDefs: TOOL_DEFS, toolRoutes: TOOL_ROUTES } = buildToolCatalog(
+  surfaceRegistry,
+  {
+    activeSurfaces: ACTIVE_TOOL_SURFACES,
+    toToolName,
+    toJsonSchemaCompat
   }
+);
 
-  return attachEvents(session, { ok: true, eventsInjected: injected });
-};
-
-const visionCaptureTool = async (args) => {
-  const options = VisionCaptureSchema.parse(args || {});
-  const session = getSession(options.sessionId);
-  const result = await captureFrame(session, options);
-  if (!result.ok) {
-    return attachEvents(session, { ok: false, reason: result.reason });
+const resolveTool = (rawName) => {
+  const requestedName = resolveToolName(rawName);
+  const route = TOOL_ROUTES.get(requestedName);
+  if (!route) {
+    throw new Error(`Unknown tool: ${rawName}`);
   }
-  session.events.add({
-    source: 'agent',
-    type: 'capture',
-    summary: 'capture',
-    resourceUris: result.frame?.resourceUri ? [result.frame.resourceUri] : undefined
-  });
-  return attachEvents(session, { frame: result.frame });
-};
-
-const visionSequenceTool = async (args) => {
-  const options = VisionSequenceSchema.parse(args || {});
-  const session = getSession(options.sessionId);
-  const result = await captureSequence(session, options);
-  return attachEvents(session, result);
-};
-
-const watchCreateTool = async (args) => {
-  const { sessionId, watch, actions, enabled } = WatchCreateSchema.parse(args || {});
-  const session = getSession(sessionId);
-  const watchId = makeId();
-  const state = await getState(session);
-  const tickIndex = state?.game?.timer?.tickIndex ?? 0;
-
-  const entry = {
-    id: watchId,
-    type: watch.type,
-    everyTicks: watch.everyTicks || 1,
-    jsonPointer: watch.jsonPointer || '',
-    enabled: enabled !== false,
-    actions: actions || [],
-    lastTick: Number.isFinite(tickIndex) ? tickIndex : 0,
-    lastValue: watch.type === 'onChange' ? JSON.stringify(readPointer(state, watch.jsonPointer)) : null,
-    lastCaptureTick: -Infinity
-  };
-
-  session.watches.set(watchId, entry);
-  startWatchLoop(session);
-
-  return attachEvents(session, {
-    watchId,
-    ok: true
-  });
-};
-
-const watchCancelTool = async (args) => {
-  const { sessionId, watchId } = WatchCancelSchema.parse(args || {});
-  const session = getSession(sessionId);
-  const ok = session.watches.delete(watchId);
-  if (!session.watches.size) {
-    stopWatchLoop(session);
+  if (!ENABLED_TOOL_SURFACES.has(route.surface)) {
+    throw new Error(`Tool disabled by surface policy: ${rawName}`);
   }
-  return attachEvents(session, { ok });
+  return route;
 };
 
-const eventsPollTool = async (args) => {
-  const { sessionId, after } = EventsPollSchema.parse(args || {});
-  const session = getSession(sessionId);
-  const envelope = session.events.drain(after, { updateCursor: true });
-  const cursor = String(Number.isFinite(Number(after)) ? Number(after) : session.events.lastDelivered);
-  return envelope || { cursor, events: [] };
-};
-
-const TOOL_HANDLERS = new Map([
-  ['session.create', createSession],
-  ['session.close', closeSession],
-  ['time.pause', pauseTime],
-  ['time.resume', resumeTime],
-  ['time.step', stepTime],
-  ['state.get', getStateTool],
-  ['state.delta', getStateDeltaTool],
-  ['editor.apply', editorApplyTool],
-  ['lemming.summary', getLemmingsSummaryTool],
-  ['lemming.select', selectLemmingTool],
-  ['skill.apply', applySkillTool],
-  ['input.action', inputActionTool],
-  ['input.keys', inputKeysTool],
-  ['vision.capture', visionCaptureTool],
-  ['vision.captureSequence', visionSequenceTool],
-  ['watch.create', watchCreateTool],
-  ['watch.cancel', watchCancelTool],
-  ['events.poll', eventsPollTool]
-]);
-
 const server = new Server(
   {
     name: 'lemmings-mcp',
@@ -2300,11 +380,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOL_DEFS
 
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const rawName = request.params.name;
-  const toolName = TOOL_NAME_ALIASES.get(rawName) || rawName;
-  const handler = TOOL_HANDLERS.get(toolName);
-  if (!handler) {
-    throw new Error(`Unknown tool: ${rawName}`);
-  }
+  const { handler } = resolveTool(rawName);
   const args = request.params.arguments || {};
   const payload = await handler(args);
   return buildToolResponse(payload);
@@ -2343,24 +419,60 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
   return { contents };
 });
 
-const transport = new StdioServerTransport();
-await server.connect(transport);
+const createProtocolMetadata = () => buildProtocolMetadata({
+  protocolVersion: MCP_PROTOCOL_VERSION,
+  schemaFrozenAt: MCP_PROTOCOL_SCHEMA_FROZEN_AT,
+  skillNames: SKILL_NAMES,
+  lemmingDeltaFields: LEMMING_DELTA_FIELDS
+});
 
-const shutdown = async () => {
-  for (const session of sessions.values()) {
-    stopSpectatorServer(session);
-    stopWatchLoop(session);
-    try {
-      await session.context.close();
-      await session.browser.close();
-    } catch (err) {
-      // ignore
-    }
-  }
-  sessions.clear();
+const createMcpRuntime = async ({
+  transport = new StdioServerTransport(),
+  processRef = process
+} = {}) => {
+  await server.connect(transport);
+
+  const shutdownController = createShutdownController({
+    disposeSessions: async () => {
+      await disposeAllSessionRuntimes(sessions.values(), {
+        stopSpectatorServer,
+        stopWatchLoop
+      });
+      sessions.clear();
+    },
+    closeServer: () => server.close(),
+    closeTransport: () => transport.close()
+  });
+
+  processRef?.on?.('SIGINT', () => {
+    shutdownController.handleSignal('SIGINT');
+  });
+
+  processRef?.on?.('SIGTERM', () => {
+    shutdownController.handleSignal('SIGTERM');
+  });
+
+  return {
+    server,
+    transport,
+    shutdownController
+  };
 };
 
-process.on('SIGINT', async () => {
-  await shutdown();
-  process.exit(0);
-});
+const isMainModule = (() => {
+  try {
+    return path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+})();
+
+if (isMainModule) {
+  await createMcpRuntime();
+}
+
+export {
+  createMcpRuntime,
+  createProtocolMetadata,
+  server
+};
diff --git a/mcp/serverHelpers.js b/mcp/serverHelpers.js
new file mode 100644
index 00000000..a761cfe0
--- /dev/null
+++ b/mcp/serverHelpers.js
@@ -0,0 +1,201 @@
+const createServerHelpers = ({
+  fs,
+  keybindingsPath,
+  normalizeKeyChord,
+  skillNames,
+  buildLemmingSummary
+}) => {
+  let cachedKeybindings = null;
+  let cachedKeybindingsMtimeMs = NaN;
+  const SKILL_NAMES = skillNames;
+  const KEYBINDINGS_PATH = keybindingsPath;
+
+  const loadKeybindings = async () => {
+    const stat = await fs.stat(KEYBINDINGS_PATH);
+    if (cachedKeybindings && cachedKeybindingsMtimeMs === stat.mtimeMs) {
+      return cachedKeybindings;
+    }
+    const raw = await fs.readFile(KEYBINDINGS_PATH, 'utf8');
+    cachedKeybindings = JSON.parse(raw);
+    cachedKeybindingsMtimeMs = stat.mtimeMs;
+    return cachedKeybindings;
+  };
+
+  const ensureBlurred = async (session) => {
+    await session.page.evaluate(() => {
+      const active = document.activeElement;
+      if (active && typeof active.blur === 'function') {
+        active.blur();
+      }
+    });
+  };
+
+  const callE2E = async (session, method, ...args) => session.page.evaluate(
+    ({ method, args }) => {
+      const api = window.__E2E__;
+      if (!api || typeof api[method] !== 'function') {
+        return { ok: false, error: 'harness_unavailable' };
+      }
+      try {
+        return { ok: true, value: api[method](...args) };
+      } catch (err) {
+        return { ok: false, error: err ? String(err) : 'error' };
+      }
+    },
+    { method, args }
+  );
+
+  const getState = async (session) => {
+    const result = await callE2E(session, 'getState');
+    return result.ok ? result.value : null;
+  };
+
+  const getTickIndex = async (session) => {
+    const state = await getState(session);
+    return state?.game?.timer?.tickIndex ?? null;
+  };
+
+  const filterStateSnapshot = (snapshot, include) => {
+    const config = {
+      view: false,
+      stage: false,
+      game: true,
+      editor: false,
+      midi: false,
+      ...(include || {})
+    };
+    const output = {
+      version: snapshot.version,
+      mode: snapshot.mode,
+      ready: snapshot.ready
+    };
+
+    if (config.view) output.view = snapshot.view;
+    if (config.stage) output.stage = snapshot.stage;
+    if (config.game) output.game = snapshot.game;
+    if (config.editor) output.editor = snapshot.editor;
+    if (config.midi) output.midi = snapshot.midi;
+
+    return output;
+  };
+
+  const buildSkillInfo = (skills) => {
+    if (!skills) return null;
+    const counts = SKILL_NAMES.map((_, idx) => {
+      const skillIndex = idx + 1;
+      const raw = Array.isArray(skills.skills) ? skills.skills[skillIndex] ?? 0 : 0;
+      return Number.isFinite(raw) ? raw : 99;
+    });
+    const cheatMode = !!skills.cheatMode;
+    let availableMask = 0;
+    counts.forEach((count, idx) => {
+      if (cheatMode || count > 0) {
+        availableMask |= (1 << idx);
+      }
+    });
+    const selectedSkill = Number.isFinite(skills.selectedSkill) ? skills.selectedSkill : null;
+    const selectedSkillName = Number.isFinite(selectedSkill)
+      ? (SKILL_NAMES[selectedSkill - 1] || null)
+      : null;
+    return {
+      selectedSkill,
+      selectedSkillName,
+      cheatMode,
+      counts,
+      availableMask
+    };
+  };
+
+  const buildLemmingPrunePolicy = (state, skillInfo) => {
+    const lemmings = Array.isArray(state?.game?.lemmings) ? state.game.lemmings : [];
+    const availableMask = skillInfo?.availableMask ?? 0;
+    const hasClimb = lemmings.some((lem) => lem?.canClimb);
+    const hasParachute = lemmings.some((lem) => lem?.hasParachute);
+    const hasCountdown = lemmings.some((lem) => lem?.countdownActive);
+    const hasRemoved = lemmings.some((lem) => lem?.removed);
+    const hasDisabled = lemmings.some((lem) => lem?.disabled);
+    return {
+      includeClimb: (availableMask & (1 << 0)) !== 0 || hasClimb,
+      includeParachute: (availableMask & (1 << 1)) !== 0 || hasParachute,
+      includeCountdown: (availableMask & (1 << 2)) !== 0 || hasCountdown,
+      includeRemoved: hasRemoved,
+      includeDisabled: hasDisabled
+    };
+  };
+
+  const pruneLemming = (lem, policy) => {
+    if (!lem) return null;
+    const output = {
+      id: lem.id,
+      x: lem.x,
+      y: lem.y,
+      state: lem.state ?? null,
+      actionType: lem.actionType ?? null
+    };
+    if (policy?.includeClimb && lem.canClimb) output.canClimb = true;
+    if (policy?.includeParachute && lem.hasParachute) output.hasParachute = true;
+    if (policy?.includeCountdown) {
+      if (lem.countdownActive) output.countdownActive = true;
+      if (Number.isFinite(lem.countdown) && lem.countdown > 0) output.countdown = lem.countdown;
+    }
+    if (policy?.includeRemoved && lem.removed) output.removed = true;
+    if (policy?.includeDisabled && lem.disabled) output.disabled = true;
+    return output;
+  };
+
+  const buildLemmingSummaryCompact = (state, policy, options = {}) => {
+    const summary = buildLemmingSummary(state, options);
+    return {
+      ...summary,
+      selected: pruneLemming(summary.selected, policy),
+      top: Array.isArray(summary.top) ? summary.top.map((lem) => pruneLemming(lem, policy)) : []
+    };
+  };
+
+  const ensureGameFocus = async (session) => {
+    await ensureBlurred(session);
+  };
+
+  const pressKey = async (session, key) => {
+    const normalized = normalizeKeyChord(key);
+    if (!normalized) return;
+    await session.page.keyboard.press(normalized);
+  };
+
+  const pressAction = async (session, action, repeat = 1) => {
+    const bindings = session.keybindings?.bindings || {};
+    const chordList = bindings[action];
+    if (!Array.isArray(chordList) || chordList.length === 0) {
+      return { ok: false, reason: 'unknown_action' };
+    }
+    await ensureGameFocus(session);
+    for (let i = 0; i < repeat; i += 1) {
+      await pressKey(session, chordList[0]);
+    }
+    session.events.add({
+      source: 'agent',
+      type: 'input',
+      summary: `action:${action} x${repeat}`
+    });
+    return { ok: true, action, repeat };
+  };
+
+
+  return {
+    loadKeybindings,
+    ensureBlurred,
+    callE2E,
+    getState,
+    getTickIndex,
+    filterStateSnapshot,
+    buildSkillInfo,
+    buildLemmingPrunePolicy,
+    pruneLemming,
+    buildLemmingSummaryCompact,
+    ensureGameFocus,
+    pressKey,
+    pressAction
+  };
+};
+
+export { createServerHelpers };
diff --git a/mcp/sessionLifecycle.js b/mcp/sessionLifecycle.js
new file mode 100644
index 00000000..b797d340
--- /dev/null
+++ b/mcp/sessionLifecycle.js
@@ -0,0 +1,84 @@
+const noop = () => {};
+
+const closeSafely = async (target, methodName) => {
+  if (!target || typeof target[methodName] !== 'function') return;
+  try {
+    await target[methodName]();
+  } catch (error) {
+    // Ignore close failures during teardown.
+  }
+};
+
+const invokeHookSafely = async (hook, session) => {
+  if (typeof hook !== 'function') return;
+  try {
+    await hook(session);
+  } catch (error) {
+    // Ignore hook failures during teardown.
+  }
+};
+
+const clearSessionResourcesSafely = async (session) => {
+  if (!session?.resources || typeof session.resources.clearSession !== 'function') return;
+  try {
+    await session.resources.clearSession(session.id);
+  } catch (error) {
+    // Ignore resource clear failures during teardown.
+  }
+};
+
+/**
+ * Dispose runtime resources associated with a single MCP session.
+ * Hook failures and close failures are intentionally ignored so teardown can
+ * progress and preserve the original caller error context.
+ *
+ * @param {any} session
+ * @param {{
+ *   stopSpectatorServer?: (session: any) => (void|Promise<void>),
+ *   stopWatchLoop?: (session: any) => (void|Promise<void>)
+ * }} [hooks]
+ * @returns {Promise<void>}
+ */
+const disposeSessionRuntime = async (
+  session,
+  {
+    stopSpectatorServer = noop,
+    stopWatchLoop = noop
+  } = {}
+) => {
+  if (!session) return;
+  await invokeHookSafely(stopSpectatorServer, session);
+  await invokeHookSafely(stopWatchLoop, session);
+  await closeSafely(session.watchController, 'stopAndWait');
+  await clearSessionResourcesSafely(session);
+  await closeSafely(session.context, 'close');
+  await closeSafely(session.browser, 'close');
+};
+
+/**
+ * Dispose runtime resources for all provided sessions.
+ *
+ * @param {Iterable<any>} sessions
+ * @param {{
+ *   stopSpectatorServer?: (session: any) => (void|Promise<void>),
+ *   stopWatchLoop?: (session: any) => (void|Promise<void>)
+ * }} [hooks]
+ * @returns {Promise<void>}
+ */
+const disposeAllSessionRuntimes = async (
+  sessions,
+  {
+    stopSpectatorServer = noop,
+    stopWatchLoop = noop
+  } = {}
+) => {
+  const list = Array.from(sessions || []);
+  const pending = list.map((session) => disposeSessionRuntime(session, {
+    stopSpectatorServer,
+    stopWatchLoop
+  }));
+  if (!pending.length) return;
+  await Promise.allSettled(pending);
+};
+
+export { disposeAllSessionRuntimes, disposeSessionRuntime };
diff --git a/mcp/sessionStore.js b/mcp/sessionStore.js
new file mode 100644
index 00000000..4d7fc25e
--- /dev/null
+++ b/mcp/sessionStore.js
@@ -0,0 +1,33 @@
+/** Live MCP session registry keyed by normalized session id. */
+const sessions = new Map();
+
+/**
+ * Normalize incoming session ids for stable map lookups.
+ *
+ * @param {unknown} sessionId
+ * @returns {string}
+ */
+const normalizeSessionId = (sessionId) => (
+  sessionId == null ? '' : String(sessionId).trim()
+);
+
+/**
+ * Resolve a live MCP session by id.
+ *
+ * @param {string} sessionId
+ * @returns {any}
+ * @throws {Error} When the id is missing or the session does not exist.
+ */
+const getSession = (sessionId) => {
+  const normalizedSessionId = normalizeSessionId(sessionId);
+  if (!normalizedSessionId) {
+    throw new Error('Session id is required');
+  }
+  const session = sessions.get(normalizedSessionId);
+  if (!session) {
+    throw new Error(`Session not found: ${normalizedSessionId}`);
+  }
+  return session;
+};
+
+export { getSession, normalizeSessionId, sessions };
diff --git a/mcp/sessionTools.js b/mcp/sessionTools.js
new file mode 100644
index 00000000..ee393e7d
--- /dev/null
+++ b/mcp/sessionTools.js
@@ -0,0 +1,164 @@
+const createSessionToolHandlers = ({
+  schemas,
+  chromium,
+  ResourceStore,
+  EventQueue,
+  WatchPollingController,
+  sessions,
+  normalizeSessionId,
+  getSession,
+  disposeSessionRuntime,
+  loadKeybindings,
+  pollWatches,
+  startSpectatorServer,
+  stopSpectatorServer,
+  stopWatchLoop,
+  createProtocolMetadata,
+  attachEvents,
+  defaults,
+  makeId
+}) => {
+  const { SessionCloseSchema, SessionCreateSchema } = schemas;
+  const { DEFAULT_BASE_URL, DEFAULT_PATH, DEFAULT_VIEWPORT } = defaults;
+
+  const createSession = async (args) => {
+    const options = SessionCreateSchema.parse(args || {});
+    const baseUrl = options.baseUrl || DEFAULT_BASE_URL;
+    const pathName = options.path || DEFAULT_PATH;
+    const gameUrl = new URL(pathName, baseUrl).toString();
+    const headless = options.headless !== false;
+    const viewport = options.viewport || DEFAULT_VIEWPORT;
+    const sessionId = makeId();
+
+    let browser = null;
+    let context = null;
+    let page = null;
+    let session = null;
+    let keybindings = null;
+    try {
+      browser = await chromium.launch({
+        headless,
+        args: ['--allow-insecure-localhost']
+      });
+
+      context = await browser.newContext({
+        viewport: {
+          width: viewport.width,
+          height: viewport.height
+        },
+        deviceScaleFactor: Number.isFinite(viewport.deviceScaleFactor) ? viewport.deviceScaleFactor : 1,
+        ignoreHTTPSErrors: true
+      });
+
+      page = await context.newPage();
+      keybindings = await loadKeybindings();
+
+      session = {
+        id: sessionId,
+        browser,
+        context,
+        page,
+        baseUrl,
+        gameUrl,
+        keybindings,
+        resources: new ResourceStore(options.resources || {}),
+        events: new EventQueue(options.events || {}),
+        eventsMode: options.events?.mode || 'minimal',
+        lastStateTick: null,
+        editorObjectListCache: new Map(),
+        watches: new Map(),
+        watchController: null,
+        spectator: null
+      };
+
+      session.watchController = new WatchPollingController({
+        hasWatchesFn: () => session.watches.size > 0,
+        pollFn: () => pollWatches(session)
+      });
+
+      sessions.set(sessionId, session);
+
+      page.on('pageerror', (error) => {
+        session.events.add({
+          source: 'system',
+          type: 'error',
+          summary: 'pageerror',
+          data: { message: error?.message || String(error) }
+        });
+      });
+
+      page.on('console', (msg) => {
+        if (msg.type() === 'error') {
+          session.events.add({
+            source: 'system',
+            type: 'error',
+            summary: 'console error',
+            data: { message: msg.text() }
+          });
+        }
+      });
+
+      await page.goto(gameUrl, { waitUntil: 'domcontentloaded' });
+      await page.waitForFunction(
+        () => window.__E2E__?.getState?.().ready === true,
+        null,
+        { timeout: 30000 }
+      );
+
+      if (options.enableSpectator) {
+        await startSpectatorServer(session, options.spectator || {});
+      }
+    } catch (err) {
+      sessions.delete(sessionId);
+      if (session) {
+        await disposeSessionRuntime(session, {
+          stopSpectatorServer,
+          stopWatchLoop
+        });
+      } else {
+        await Promise.allSettled([
+          context?.close?.(),
+          browser?.close?.()
+        ]);
+      }
+      throw err;
+    }
+
+    const actions = Object.keys(keybindings?.bindings || {}).sort();
+    const response = {
+      ok: true,
+      sessionId,
+      protocol: createProtocolMetadata(),
+      gameUrl,
+      spectatorUrl: session.spectator?.url || null,
+      spectatorStream: session.spectator?.streamConfig || null,
+      keybindings: {
+        version: keybindings?.version || 1,
+        actions
+      },
+      warnings: []
+    };
+
+    if (options.spectator?.openBrowser) {
+      response.warnings.push('spectator.openBrowser is unsupported in this server version');
+    }
+
+    return attachEvents(session, response);
+  };
+
+  const closeSession = async (args) => {
+    const { sessionId } = SessionCloseSchema.parse(args || {});
+    const session = getSession(sessionId);
+    await disposeSessionRuntime(session, {
+      stopSpectatorServer,
+      stopWatchLoop
+    });
+    sessions.delete(normalizeSessionId(sessionId));
+    return { ok: true };
+  };
+
+
+  return { createSession, closeSession };
+};
+
+export { createSessionToolHandlers };
diff --git a/mcp/shutdownController.js b/mcp/shutdownController.js
new file mode 100644
index 00000000..60eee87d
--- /dev/null
+++ b/mcp/shutdownController.js
@@ -0,0 +1,73 @@
+const resolveMaybePromise = async (fn) => {
+  if (typeof fn !== 'function') return;
+  return fn();
+};
+
+/**
+ * Build an idempotent shutdown controller for MCP runtime teardown.
+ *
+ * @param {{
+ *   disposeSessions?: (() => (void|Promise<void>)),
+ *   closeServer?: (() => (void|Promise<void>)),
+ *   closeTransport?: (() => (void|Promise<void>)),
+ *   logger?: { error?: (...args: unknown[]) => void }
+ * }} [options]
+ * @returns {{
+ *   shutdown: (reason?: string) => Promise<void>,
+ *   handleSignal: (signal: string) => void
+ * }}
+ */
+const createShutdownController = ({
+  disposeSessions,
+  closeServer,
+  closeTransport,
+  logger = console
+} = {}) => {
+  let shutdownPromise = null;
+
+  const shutdown = async (reason = 'shutdown') => {
+    if (shutdownPromise) {
+      return shutdownPromise;
+    }
+    shutdownPromise = (async () => {
+      const failures = [];
+      const runStep = async (name, fn) => {
+        try {
+          await resolveMaybePromise(fn);
+        } catch (error) {
+          failures.push({ name, error });
+        }
+      };
+      await runStep('disposeSessions', disposeSessions);
+      await runStep('closeServer', closeServer);
+      await runStep('closeTransport', closeTransport);
+      if (failures.length) {
+        const summary = failures.map(({ name }) => name).join(', ');
+        const aggregate = new AggregateError(
+          failures.map(({ error }) => error),
+          `MCP shutdown failed (${reason}): ${summary}`
+        );
+        aggregate.failures = failures;
+        throw aggregate;
+      }
+    })();
+    return shutdownPromise;
+  };
+
+  const handleSignal = (signal) => {
+    void shutdown(signal).catch((error) => {
+      process.exitCode = 1;
+      if (logger && typeof logger.error === 'function') {
+        try {
+          logger.error(`[mcp] graceful shutdown failed on ${signal}`, error);
+        } catch {
+          // Logger failures should not mask shutdown errors.
+        }
+      }
+    });
+  };
+
+  return { shutdown, handleSignal };
+};
+
+export { createShutdownController };
diff --git a/mcp/solverTools.js b/mcp/solverTools.js
new file mode 100644
index 00000000..3e4faf22
--- /dev/null
+++ b/mcp/solverTools.js
@@ -0,0 +1,105 @@
+import { planSolverRoute } from '../js/solver/RoutePlanner.js';
+import { extractSolverState } from '../js/solver/SolverState.js';
+import { verifyActionReplay } from '../js/solver/SolverRunner.js';
+
+const compactRect = rect => ({
+  index: rect.index,
+  x: rect.x,
+  y: rect.y,
+  width: rect.width,
+  height: rect.height,
+  ...(rect.type ? { type: rect.type } : {}),
+  ...(rect.kind ? { kind: rect.kind } : {})
+});
+
+const compactSnapshot = snapshot => ({
+  kind: snapshot.kind,
+  sourceKind: snapshot.sourceKind,
+  id: snapshot.id,
+  width: snapshot.width,
+  height: snapshot.height,
+  terrainHash: snapshot.terrainHash,
+  terrainMutationHash: snapshot.terrainMutationHash,
+  snapshotHash: snapshot.snapshotHash,
+  hashes: snapshot.hashes,
+  counts: {
+    terrainSolid: snapshot.terrain.solidCount,
+    steelSolid: snapshot.steel.solidCount,
+    entrances: snapshot.entrances.length,
+    exits: snapshot.exits.length,
+    hazards: snapshot.hazards.length,
+    lemmings: snapshot.lemmings.length,
+    terrainMutations: snapshot.terrainMutations.length
+  },
+  entrances: snapshot.entrances.map(compactRect),
+  exits: snapshot.exits.map(compactRect),
+  hazards: snapshot.hazards.map(compactRect),
+  lemmings: snapshot.lemmings.map(lemming => ({
+    id: lemming.id,
+    x: lemming.x,
+    y: lemming.y,
+    action: lemming.action,
+    state: lemming.state,
+    removed: lemming.removed,
+    disabled: lemming.disabled
+  })),
+  skills: snapshot.skills,
+  timer: snapshot.timer,
+  victory: snapshot.victory
+});
+
+const compactRoute = result => ({
+  ok: true,
+  resultType: result.resultType,
+  summary: result.summary,
+  explanations: result.explanations,
+  budgetUsage: result.budgetUsage,
+  graphHash: result.graphHash ?? null,
+  routeSearchStats: result.routeSearchStats ?? null,
+  crowd: result.crowd ?? null,
+  routeSkeleton: result.routeSkeleton
+    ? {
+      kind: result.routeSkeleton.kind,
+      graphHash: result.routeSkeleton.graphHash,
+      routeHash: result.routeSkeleton.routeHash,
+      nodeIds: result.routeSkeleton.nodeIds,
+      edgeIds: result.routeSkeleton.edgeIds,
+      segments: result.routeSkeleton.segments,
+      scoreBreakdown: result.routeSkeleton.scoreBreakdown
+    }
+    : null
+});
+
+const createSolverToolHandlers = ({ schemas }) => {
+  const solverSnapshotTool = async (args) => {
+    const parsed = schemas.SolverSnapshotSchema.parse(args || {});
+    const snapshot = extractSolverState(parsed.source, parsed.options || {});
+    return {
+      ok: true,
+      snapshot: compactSnapshot(snapshot)
+    };
+  };
+
+  const solverRouteTool = async (args) => {
+    const parsed = schemas.SolverRouteSchema.parse(args || {});
+    const result = planSolverRoute(parsed.source, parsed.options || {});
+    return compactRoute(result);
+  };
+
+  const solverReplayTool = async (args) => {
+    const parsed = schemas.SolverReplaySchema.parse(args || {});
+    const result = verifyActionReplay(parsed.source, parsed.actions || [], parsed.options || {});
+    return {
+      ok: true,
+      result
+    };
+  };
+
+  return {
+    solverSnapshotTool,
+    solverRouteTool,
+    solverReplayTool
+  };
+};
+
+export { createSolverToolHandlers };
diff --git a/mcp/spectatorBroadcaster.js b/mcp/spectatorBroadcaster.js
new file mode 100644
index 00000000..88caddbc
--- /dev/null
+++ b/mcp/spectatorBroadcaster.js
@@ -0,0 +1,165 @@
+const SPECTATOR_SKIP_POLICIES = Object.freeze({
+  LATEST: 'latest',
+  NONE: 'none'
+});
+
+const DEFAULT_SPECTATOR_STREAM_CONFIG = Object.freeze({
+  frameIntervalMs: 500,
+  jpegQuality: 60,
+  frameSkipPolicy: SPECTATOR_SKIP_POLICIES.LATEST
+});
+
+const clampInt = (value, fallback, min, max) => {
+  let number;
+  try {
+    number = Number(value);
+  } catch {
+    number = Number.NaN;
+  }
+  if (!Number.isFinite(number)) return fallback;
+  return Math.min(max, Math.max(min, Math.trunc(number)));
+};
+
+const normalizeFrameSkipPolicy = (policy) => {
+  const normalized = String(policy ?? '').trim().toLowerCase();
+  if (normalized === SPECTATOR_SKIP_POLICIES.NONE) return SPECTATOR_SKIP_POLICIES.NONE;
+  return SPECTATOR_SKIP_POLICIES.LATEST;
+};
+
+/**
+ * Normalize spectator streaming knobs to bounded safe values.
+ *
+ * @param {{
+ *   frameIntervalMs?: number,
+ *   jpegQuality?: number,
+ *   frameSkipPolicy?: string
+ * }} [config]
+ * @returns {{frameIntervalMs:number,jpegQuality:number,frameSkipPolicy:string}}
+ */
+const normalizeSpectatorStreamConfig = (config = {}) => ({
+  frameIntervalMs: clampInt(config.frameIntervalMs, DEFAULT_SPECTATOR_STREAM_CONFIG.frameIntervalMs, 50, 5000),
+  jpegQuality: clampInt(config.jpegQuality, DEFAULT_SPECTATOR_STREAM_CONFIG.jpegQuality, 1, 100),
+  frameSkipPolicy: normalizeFrameSkipPolicy(config.frameSkipPolicy)
+});
+
+class SpectatorBroadcaster {
+  constructor({ frameSkipPolicy = DEFAULT_SPECTATOR_STREAM_CONFIG.frameSkipPolicy } = {}) {
+    this.frameSkipPolicy = normalizeFrameSkipPolicy(frameSkipPolicy);
+    this.clients = new Set();
+  }
+
+  attach(ws) {
+    if (!ws) return null;
+    for (const existingClient of this.clients) {
+      if (existingClient.ws === ws) {
+        return existingClient;
+      }
+    }
+    const client = {
+      ws,
+      sending: false,
+      queuedFrame: null,
+      sentCount: 0,
+      droppedCount: 0
+    };
+    this.clients.add(client);
+    return client;
+  }
+
+  detach(ws) {
+    let removed = false;
+    for (const client of this.clients) {
+      if (client.ws === ws) {
+        this.clients.delete(client);
+        removed = true;
+      }
+    }
+    return removed;
+  }
+
+  broadcast(payload) {
+    if (payload == null) return;
+    let serialized;
+    try {
+      serialized = typeof payload === 'string' ? payload : JSON.stringify(payload);
+    } catch {
+      return;
+    }
+    for (const client of this.clients) {
+      this._sendFrame(client, serialized);
+    }
+  }
+
+  getSnapshot() {
+    let connectedClients = 0;
+    let droppedFrames = 0;
+    let sentFrames = 0;
+    for (const client of this.clients) {
+      if (client?.ws?.readyState === 1) {
+        connectedClients += 1;
+      }
+      droppedFrames += client.droppedCount;
+      sentFrames += client.sentCount;
+    }
+    return {
+      connectedClients,
+      sentFrames,
+      droppedFrames,
+      frameSkipPolicy: this.frameSkipPolicy
+    };
+  }
+
+  closeAll() {
+    for (const client of this.clients) {
+      try {
+        client.ws?.close();
+      } catch (error) {
+        // Ignore close failures and continue cleanup.
+      }
+      this.clients.delete(client);
+    }
+  }
+
+  _sendFrame(client, serialized) {
+    const ws = client.ws;
+    if (!ws || ws.readyState !== 1) {
+      this.clients.delete(client);
+      return;
+    }
+
+    if (this.frameSkipPolicy === SPECTATOR_SKIP_POLICIES.LATEST && client.sending) {
+      if (client.queuedFrame !== null) {
+        client.droppedCount += 1;
+      }
+      client.queuedFrame = serialized;
+      return;
+    }
+
+    client.sending = true;
+    try {
+      ws.send(serialized, (error) => {
+        client.sending = false;
+        if (error || ws.readyState !== 1) {
+          this.clients.delete(client);
+          return;
+        }
+        client.sentCount += 1;
+        if (this.frameSkipPolicy === SPECTATOR_SKIP_POLICIES.LATEST && client.queuedFrame !== null) {
+          const queued = client.queuedFrame;
+          client.queuedFrame = null;
+          this._sendFrame(client, queued);
+        }
+      });
+    } catch (error) {
+      client.sending = false;
+      this.clients.delete(client);
+    }
+  }
+}
+
+export {
+  DEFAULT_SPECTATOR_STREAM_CONFIG,
+  SPECTATOR_SKIP_POLICIES,
+  SpectatorBroadcaster,
+  normalizeSpectatorStreamConfig
+};
diff --git a/mcp/spectatorTools.js b/mcp/spectatorTools.js
new file mode 100644
index 00000000..3716114f
--- /dev/null
+++ b/mcp/spectatorTools.js
@@ -0,0 +1,253 @@
+import fs from 'node:fs/promises';
+import http from 'node:http';
+import { WebSocketServer } from 'ws';
+import { normalizeSpectatorStreamConfig, SpectatorBroadcaster } from './spectatorBroadcaster.js';
+
+/**
+ * Build spectator lifecycle helpers bound to the MCP runtime dependencies.
+ *
+ * @param {{
+ *   spectatorHtmlPath: string,
+ *   captureFrame: (session: any, options: object) => Promise<any>,
+ *   resolveCanvasMetrics: (session: any) => Promise<any>,
+ *   normalizeKeyToken: (token: string) => string,
+ *   ensureGameFocus: (session: any) => Promise<void>
+ * }} deps
+ * @returns {{
+ *   startSpectatorServer: (session: any, options?: object) => Promise<string>,
+ *   stopSpectatorServer: (session: any) => void
+ * }}
+ */
+const createSpectatorTools = ({
+  spectatorHtmlPath,
+  captureFrame,
+  resolveCanvasMetrics,
+  normalizeKeyToken,
+  ensureGameFocus
+}) => {
+  const toNumberOrNaN = (value) => {
+    try {
+      return Number(value);
+    } catch {
+      return Number.NaN;
+    }
+  };
+
+  const normalizeSpectatorPort = (value) => {
+    const parsed = toNumberOrNaN(value);
+    if (!Number.isFinite(parsed)) return 0;
+    const normalized = Math.trunc(parsed);
+    if (normalized < 0 || normalized > 65535) return 0;
+    return normalized;
+  };
+
+  const handleSpectatorInput = async (session, payload) => {
+    if (!payload || !session.spectator?.allowHumanInput) return;
+    if (payload.type === 'key') {
+      if (!['down', 'up', 'press'].includes(payload.action)) return;
+      const normalizedKey = normalizeKeyToken(payload.key);
+      const key = String(normalizedKey ?? '').trim();
+      if (!key) return;
+      await ensureGameFocus(session);
+      if (payload.action === 'down') {
+        await session.page.keyboard.down(key);
+      } else if (payload.action === 'up') {
+        await session.page.keyboard.up(key);
+      } else {
+        await session.page.keyboard.press(key);
+      }
+      session.events.add({
+        source: 'human',
+        type: 'input',
+        summary: `key:${payload.action}:${key}`
+      });
+      return;
+    }
+    if (payload.type === 'click') {
+      if (!Number.isFinite(payload.x) || !Number.isFinite(payload.y)) return;
+      if (payload.x < 0 || payload.x > 1 || payload.y < 0 || payload.y > 1) return;
+      const metrics = await resolveCanvasMetrics(session);
+      if (!metrics) return;
+      const rectX = Number(metrics?.rect?.x);
+      const rectY = Number(metrics?.rect?.y);
+      const rectWidth = Number(metrics?.rect?.width);
+      const rectHeight = Number(metrics?.rect?.height);
+      if (
+        !Number.isFinite(rectX) ||
+        !Number.isFinite(rectY) ||
+        !Number.isFinite(rectWidth) ||
+        !Number.isFinite(rectHeight) ||
+        rectWidth <= 0 ||
+        rectHeight <= 0
+      ) {
+        return;
+      }
+      const normX = Math.min(1, Math.max(0, payload.x));
+      const normY = Math.min(1, Math.max(0, payload.y));
+      const maxOffsetX = Math.max(0, rectWidth - 1);
+      const maxOffsetY = Math.max(0, rectHeight - 1);
+      const x = rectX + Math.min(maxOffsetX, normX * rectWidth);
+      const y = rectY + Math.min(maxOffsetY, normY * rectHeight);
+      await session.page.mouse.click(x, y);
+      session.events.add({
+        source: 'human',
+        type: 'input',
+        summary: `click:${payload.x.toFixed(2)},${payload.y.toFixed(2)}`
+      });
+    }
+  };
+
+  const startSpectatorServer = async (session, options = {}) => {
+    const html = await fs.readFile(spectatorHtmlPath, 'utf8');
+    const port = normalizeSpectatorPort(options.port);
+    const allowHumanInput = options.allowHumanInput === true;
+    const streamConfig = normalizeSpectatorStreamConfig(options);
+    const broadcaster = new SpectatorBroadcaster({
+      frameSkipPolicy: streamConfig.frameSkipPolicy
+    });
+
+    const server = http.createServer((req, res) => {
+      if (req.url && req.url !== '/' && req.url !== '/index.html') {
+        res.writeHead(404);
+        res.end('Not found');
+        return;
+      }
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+      res.end(html);
+    });
+
+    const wss = new WebSocketServer({ server });
+
+    wss.on('connection', (ws) => {
+      broadcaster.attach(ws);
+      ws.send(JSON.stringify({
+        type: 'hello',
+        allowHumanInput,
+        streamConfig
+      }));
+      if (session.spectator?.lastFrame) {
+        ws.send(JSON.stringify(session.spectator.lastFrame));
+      }
+      ws.on('message', async (data) => {
+        if (!allowHumanInput) return;
+        let payload;
+        try {
+          payload = JSON.parse(data.toString());
+        } catch {
+          return;
+        }
+        try {
+          await handleSpectatorInput(session, payload);
+        } catch (error) {
+          session.events.add({
+            source: 'system',
+            type: 'error',
+            summary: 'spectator input failed',
+            data: { message: error?.message || String(error) }
+          });
+        }
+      });
+      ws.on('close', () => {
+        broadcaster.detach(ws);
+      });
+      ws.on('error', () => {
+        broadcaster.detach(ws);
+      });
+    });
+
+    await new Promise((resolve, reject) => {
+      const onError = (error) => {
+        server.off('listening', onListening);
+        reject(error);
+      };
+      const onListening = () => {
+        server.off('error', onError);
+        resolve();
+      };
+      server.once('error', onError);
+      server.once('listening', onListening);
+      server.listen(port, '127.0.0.1');
+    });
+    const address = server.address();
+    const actualPort = typeof address === 'object' && address ? address.port : port;
+    const baseUrl = `http://127.0.0.1:${actualPort}`;
+
+    session.spectator = {
+      server,
+      wss,
+      broadcaster,
+      allowHumanInput,
+      streamConfig,
+      url: baseUrl,
+      lastFrame: null,
+      frameTimer: null,
+      isCapturing: false
+    };
+
+    session.spectator.frameTimer = setInterval(async () => {
+      const spectator = session.spectator;
+      if (!spectator) return;
+      if (spectator.isCapturing) return;
+      if (spectator.broadcaster.getSnapshot().connectedClients <= 0) return;
+      spectator.isCapturing = true;
+      try {
+        const result = await captureFrame(session, {
+          target: 'stageCanvas',
+          format: 'jpeg',
+          quality: spectator.streamConfig.jpegQuality,
+          delivery: 'inline'
+        });
+        if (session.spectator !== spectator) return;
+        if (result.ok && result.frame?.dataBase64) {
+          const payload = {
+            type: 'frame',
+            mimeType: result.frame.mimeType,
+            dataBase64: result.frame.dataBase64,
+            tickIndex: result.frame.tickIndex ?? null,
+            takenAt: result.frame.takenAt ?? null
+          };
+          spectator.lastFrame = payload;
+          spectator.broadcaster.broadcast(payload);
+        }
+      } catch (err) {
+        session.events.add({
+          source: 'system',
+          type: 'error',
+          summary: 'spectator capture failed',
+          data: { message: err ? String(err) : 'unknown' }
+        });
+      } finally {
+        if (session.spectator === spectator) {
+          spectator.isCapturing = false;
+        }
+      }
+    }, streamConfig.frameIntervalMs);
+
+    return baseUrl;
+  };
+
+  const stopSpectatorServer = (session) => {
+    if (!session.spectator) return;
+    const { server, wss, frameTimer, broadcaster } = session.spectator;
+    if (frameTimer) clearInterval(frameTimer);
+    broadcaster?.closeAll();
+    try {
+      wss?.close();
+    } catch {
+      /* ignore */
+    }
+    try {
+      server?.close();
+    } catch {
+      /* ignore */
+    }
+    session.spectator = null;
+  };
+
+  return {
+    startSpectatorServer,
+    stopSpectatorServer
+  };
+};
+
+export { createSpectatorTools };
diff --git a/mcp/stateTools.js b/mcp/stateTools.js
new file mode 100644
index 00000000..ecb45200
--- /dev/null
+++ b/mcp/stateTools.js
@@ -0,0 +1,467 @@
+/**
+ * Build MCP state-tool handlers using injected schema/runtime dependencies.
+ *
+ * @param {{
+ *   schemas: {
+ *     StateGetSchema: { parse: (args?: object) => any },
+ *     StateDeltaSchema: { parse: (args?: object) => any },
+ *     LemmingsSummarySchema: { parse: (args?: object) => any }
+ *   },
+ *   attachEvents: (session: any, payload: any) => any,
+ *   getSession: (sessionId: string) => any,
+ *   callE2E: (session: any, method: string, ...args: any[]) => Promise<{ok:boolean,value?:any,error?:any}>,
+ *   getState: (session: any) => Promise<any>,
+ *   getTickIndex: (session: any) => Promise<number|null>,
+ *   nudgeWatchPolling: (session: any) => void,
+ *   helpers: {
+ *     filterStateSnapshot: (state: any, include: object) => any,
+ *     buildSkillInfo: (skills: any) => any,
+ *     buildLemmingPrunePolicy: (state: any, skillInfo: any) => any,
+ *     buildLemmingSummary: (state: any, options: object) => any,
+ *     buildLemmingSummaryCompact: (state: any, policy: any, options: object) => any,
+ *     pruneLemming: (lem: any, policy: any) => any
+ *   },
+ *   defaultLemDeltaFields: number[]
+ * }} options
+ * @returns {{
+ *   getStateTool: (args?: object) => Promise<any>,
+ *   getStateDeltaTool: (args?: object) => Promise<any>,
+ *   getLemmingsSummaryTool: (args?: object) => Promise<any>
+ * }}
+ */
+const createStateToolHandlers = ({
+  schemas,
+  attachEvents,
+  getSession,
+  callE2E,
+  getState,
+  getTickIndex,
+  nudgeWatchPolling,
+  helpers,
+  defaultLemDeltaFields
+}) => {
+  const {
+    filterStateSnapshot,
+    buildSkillInfo,
+    buildLemmingPrunePolicy,
+    buildLemmingSummary,
+    buildLemmingSummaryCompact,
+    pruneLemming
+  } = helpers;
+  const MAX_STATE_GET_LEMMINGS = 5000;
+  const MAX_DELTA_TICKS = 2000;
+  const MAX_DELTA_LEM_CHANGES = 5000;
+
+  const toTickInteger = (value, fallback = 0) => {
+    if (!Number.isFinite(value)) return fallback;
+    return Math.trunc(value);
+  };
+
+  const normalizePositiveInt = (value, fallback, max) => {
+    if (!Number.isFinite(value)) return fallback;
+    const normalized = Math.trunc(value);
+    if (normalized < 1) return fallback;
+    return Math.min(max, normalized);
+  };
+
+  const serializePayload = (payload, pretty = false) => {
+    try {
+      return {
+        ok: true,
+        json: JSON.stringify(payload, null, pretty ? 2 : 0)
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        error
+      };
+    }
+  };
+
+  const getStateTool = async (args) => {
+    const { sessionId, preset, include, lemmings, format } = schemas.StateGetSchema.parse(args || {});
+    const session = getSession(sessionId);
+    const raw = await getState(session);
+    if (!raw) {
+      return attachEvents(session, { ok: false, reason: 'harness_unavailable' });
+    }
+
+    const tickIndex = raw?.game?.timer?.tickIndex ?? null;
+    if (Number.isFinite(tickIndex)) {
+      session.lastStateTick = tickIndex;
+    }
+
+    const effectivePreset = preset || 'compact';
+    const includeFlags = {
+      view: false,
+      stage: false,
+      game: true,
+      editor: false,
+      midi: false,
+      ...(include || {})
+    };
+
+    const skillInfo = raw.game ? buildSkillInfo(raw.game.skills) : null;
+    const lemmingPolicy = raw.game ? buildLemmingPrunePolicy(raw, skillInfo) : null;
+
+    let snapshot;
+    if (effectivePreset === 'debug') {
+      snapshot = filterStateSnapshot(raw, includeFlags);
+      if (snapshot.game && skillInfo) {
+        snapshot.game.skillsInfo = skillInfo;
+      }
+    } else {
+      snapshot = {
+        version: raw.version,
+        mode: raw.mode,
+        ready: raw.ready
+      };
+      if (includeFlags.view) snapshot.view = raw.view;
+      if (includeFlags.stage) {
+        snapshot.stage = raw.stage ? { viewRect: raw.stage.viewRect } : raw.stage;
+      }
+      if (includeFlags.game && raw.game) {
+        snapshot.game = {
+          state: raw.game.state ?? null,
+          finalGameState: raw.game.finalGameState ?? null,
+          timer: raw.game.timer ? {
+            tickIndex: raw.game.timer.tickIndex,
+            running: raw.game.timer.running,
+            speedFactor: raw.game.timer.speedFactor
+          } : null,
+          victory: raw.game.victory ? {
+            leftCount: raw.game.victory.leftCount,
+            outCount: raw.game.victory.outCount,
+            survivorCount: raw.game.victory.survivorCount,
+            releaseRate: raw.game.victory.releaseRate,
+            minReleaseRate: raw.game.victory.minReleaseRate,
+            isFinalize: raw.game.victory.isFinalize
+          } : null,
+          level: raw.game.level ? {
+            name: raw.game.level.name,
+            width: raw.game.level.width,
+            height: raw.game.level.height,
+            releaseCount: raw.game.level.releaseCount,
+            needCount: raw.game.level.needCount,
+            timeLimit: raw.game.level.timeLimit,
+            isSuperLemming: raw.game.level.isSuperLemming
+          } : null,
+          skills: skillInfo,
+          lemmingManager: raw.game.lemmingManager ? {
+            selectedIndex: raw.game.lemmingManager.selectedIndex,
+            activeCount: raw.game.lemmingManager.activeCount,
+            totalCount: raw.game.lemmingManager.totalCount,
+            spawnTotal: raw.game.lemmingManager.spawnTotal,
+            releaseTickIndex: raw.game.lemmingManager.releaseTickIndex,
+            nukeTargets: raw.game.lemmingManager.nukeTargets
+          } : null,
+          lemmings: []
+        };
+      }
+    }
+
+    const lemmingOpts = lemmings || {};
+    const mode = lemmingOpts.mode || 'summary';
+
+    if (snapshot.game) {
+      if (mode === 'none') {
+        snapshot.game.lemmings = [];
+      } else if (mode === 'summary') {
+        snapshot.game.lemmings = [];
+        const summary = effectivePreset === 'debug'
+          ? buildLemmingSummary(raw, {
+            activeOnly: lemmingOpts.activeOnly !== false,
+            inViewOnly: !!lemmingOpts.inViewOnly,
+            rectWorld: lemmingOpts.rectWorld,
+            topK: lemmingOpts.topK,
+            includeSelected: lemmingOpts.includeSelected
+          })
+          : buildLemmingSummaryCompact(raw, lemmingPolicy, {
+            activeOnly: lemmingOpts.activeOnly !== false,
+            inViewOnly: !!lemmingOpts.inViewOnly,
+            rectWorld: lemmingOpts.rectWorld,
+            topK: lemmingOpts.topK,
+            includeSelected: lemmingOpts.includeSelected
+          });
+        snapshot.game.lemmingsSummary = summary;
+      } else if (mode === 'selected') {
+        snapshot.game.lemmings = [];
+        const selectedIndex = raw?.game?.lemmingManager?.selectedIndex;
+        const selected = Number.isFinite(selectedIndex) ? raw?.game?.lemmings?.[selectedIndex] : null;
+        snapshot.game.selectedLemmingId = selected ? selected.id : null;
+        snapshot.game.selectedLemming = effectivePreset === 'debug'
+          ? selected
+          : pruneLemming(selected, lemmingPolicy);
+      } else if (mode === 'ids') {
+        const ids = [];
+        if (Array.isArray(lemmingOpts.ids)) {
+          const maxIndex = Array.isArray(raw.game?.lemmings) ? raw.game.lemmings.length - 1 : -1;
+          const seenIds = new Set();
+          for (const candidateId of lemmingOpts.ids) {
+            if (!Number.isFinite(candidateId)) continue;
+            const normalizedId = Math.trunc(candidateId);
+            if (normalizedId < 0 || normalizedId > maxIndex) continue;
+            if (seenIds.has(normalizedId)) continue;
+            seenIds.add(normalizedId);
+            ids.push(normalizedId);
+            if (ids.length >= MAX_STATE_GET_LEMMINGS) break;
+          }
+        }
+        snapshot.game.lemmingsIds = ids;
+        snapshot.game.lemmings = ids.map((id) => {
+          const lem = raw.game?.lemmings?.[id] || null;
+          return effectivePreset === 'debug' ? lem : pruneLemming(lem, lemmingPolicy);
+        });
+      } else {
+        const requestedMax = Number.isFinite(lemmingOpts.max)
+          ? Math.max(1, Math.trunc(lemmingOpts.max))
+          : (raw.game?.lemmings?.length || 0);
+        const max = Math.min(MAX_STATE_GET_LEMMINGS, requestedMax);
+        const slice = raw.game?.lemmings?.slice(0, max) || [];
+        snapshot.game.lemmings = effectivePreset === 'debug'
+          ? slice
+          : slice.map((lem) => pruneLemming(lem, lemmingPolicy));
+      }
+    }
+
+    const delivery = format?.delivery || 'inline';
+    if (delivery === 'resource') {
+      const serialized = serializePayload(snapshot, format?.pretty);
+      if (!serialized.ok) {
+        return attachEvents(session, { ok: false, reason: 'snapshot_serialize_failed' });
+      }
+      const stored = session.resources?.put?.({
+        sessionId: session.id,
+        bytes: Buffer.from(serialized.json),
+        mimeType: 'application/json',
+        meta: { kind: 'state' }
+      });
+      if (!stored?.uri) {
+        return attachEvents(session, { ok: false, reason: 'resource_store_failed' });
+      }
+      return attachEvents(session, {
+        ok: true,
+        tickIndex,
+        preset: effectivePreset,
+        resourceUri: stored?.uri || null,
+        sizeBytes: stored?.sizeBytes ?? null
+      });
+    }
+
+    const response = {
+      ok: true,
+      tickIndex,
+      preset: effectivePreset,
+      snapshot
+    };
+
+    if (format?.includeSizeEstimate) {
+      const serialized = serializePayload(snapshot, false);
+      if (serialized.ok) {
+        response.sizeBytesEstimate = Buffer.byteLength(serialized.json);
+      }
+    }
+
+    return attachEvents(session, response);
+  };
+
+  const getStateDeltaTool = async (args) => {
+    const { sessionId, afterTick, toTick, maxTicks, include, lemmings, format } = schemas.StateDeltaSchema.parse(args || {});
+    const session = getSession(sessionId);
+    const currentTick = await getTickIndex(session);
+    if (!Number.isFinite(currentTick)) {
+      return attachEvents(session, { ok: false, reason: 'tick_index_unavailable' });
+    }
+
+    const effectiveAfter = Number.isFinite(afterTick)
+      ? toTickInteger(afterTick, currentTick - 1)
+      : toTickInteger(session.lastStateTick, currentTick - 1);
+    const requestedTo = Number.isFinite(toTick) ? toTickInteger(toTick, currentTick) : currentTick;
+    const effectiveTo = Math.min(currentTick, requestedTo);
+
+    let startTick = Math.max(0, toTickInteger(effectiveAfter + 1, 0));
+    let endTick = Math.max(0, toTickInteger(effectiveTo, 0));
+    if (startTick > endTick) {
+      const cursor = Math.max(endTick, toTickInteger(effectiveAfter, endTick));
+      return attachEvents(session, {
+        ok: true,
+        cursor,
+        afterTick: effectiveAfter,
+        toTick: endTick,
+        deltas: []
+      });
+    }
+
+    const limit = normalizePositiveInt(maxTicks, 10, MAX_DELTA_TICKS);
+    if ((endTick - startTick + 1) > limit) {
+      startTick = endTick - limit + 1;
+    }
+
+    const inc = {
+      lemmings: true,
+      lemmingManager: true,
+      skills: true,
+      victory: true,
+      timer: true,
+      game: false,
+      sound: false,
+      minimap: false,
+      triggers: false,
+      objects: false,
+      ground: false,
+      entrances: false,
+      ...(include || {})
+    };
+
+    const lemOpts = {
+      fields: Array.isArray(lemmings?.fields) ? lemmings.fields : defaultLemDeltaFields,
+      includePrev: lemmings?.includePrev === true,
+      includeXY: lemmings?.includeXY || 'none',
+      trackedIds: Array.isArray(lemmings?.trackedIds) ? lemmings.trackedIds : [],
+      maxChanges: normalizePositiveInt(lemmings?.maxChanges, 250, MAX_DELTA_LEM_CHANGES)
+    };
+
+    const fieldSet = new Set(lemOpts.fields);
+    const trackedSet = new Set(lemOpts.trackedIds);
+
+    const deltaRes = await callE2E(session, 'getDeltas', startTick, endTick, limit);
+    if (!deltaRes.ok) {
+      return attachEvents(session, { ok: false, reason: 'delta_unavailable', error: deltaRes.error || null });
+    }
+    const deltasRaw = Array.isArray(deltaRes.value) ? deltaRes.value : [];
+
+    const filteredDeltas = [];
+    for (const delta of deltasRaw) {
+      if (!delta || typeof delta !== 'object') continue;
+      const out = { tick: delta.tick };
+
+      if (inc.lemmings) {
+        const lemChanges = delta.lemChanges;
+        if (lemChanges && Array.isArray(lemChanges.ids) && Array.isArray(lemChanges.fields) && Array.isArray(lemChanges.next)) {
+          const ids = [];
+          const fields = [];
+          const next = [];
+          const prev = [];
+          const includePrevValues = lemOpts.includePrev && Array.isArray(lemChanges.prev);
+
+          for (let i = 0; i < lemChanges.ids.length; i += 1) {
+            if (ids.length >= lemOpts.maxChanges) break;
+            const id = lemChanges.ids[i];
+            const field = lemChanges.fields[i];
+
+            if (!fieldSet.has(field)) continue;
+            if ((field === 0 || field === 1) && lemOpts.includeXY === 'none') continue;
+            if ((field === 0 || field === 1) && lemOpts.includeXY === 'tracked' && !trackedSet.has(id)) continue;
+
+            ids.push(id);
+            fields.push(field);
+            next.push(lemChanges.next[i]);
+            if (includePrevValues) {
+              prev.push(lemChanges.prev[i]);
+            }
+          }
+
+          if (ids.length > 0) {
+            out.lemChanges = {
+              ids,
+              fields,
+              ...(includePrevValues ? { prev } : {}),
+              next
+            };
+          }
+        }
+
+        if (Array.isArray(delta.lemAdded) && delta.lemAdded.length > 0) {
+          out.lemAddedIds = delta.lemAdded.map((lem) => lem?.id).filter((id) => Number.isFinite(id));
+        }
+        if (Array.isArray(delta.lemRemoved) && delta.lemRemoved.length > 0) {
+          out.lemRemovedIds = delta.lemRemoved.map((lem) => lem?.id).filter((id) => Number.isFinite(id));
+        }
+      }
+
+      if (inc.lemmingManager && delta.lemmingManagerChanges) out.lemmingManagerChanges = delta.lemmingManagerChanges;
+      if (inc.skills && delta.skillsChanges) out.skillsChanges = delta.skillsChanges;
+      if (inc.victory && delta.victoryChanges) out.victoryChanges = delta.victoryChanges;
+      if (inc.timer && delta.timerChanges) out.timerChanges = delta.timerChanges;
+      if (inc.game && delta.gameChanges) out.gameChanges = delta.gameChanges;
+
+      if (inc.sound && Array.isArray(delta.soundEvents) && delta.soundEvents.length > 0) out.soundEvents = delta.soundEvents;
+      if (inc.minimap && Array.isArray(delta.minimapDeaths) && delta.minimapDeaths.length > 0) out.minimapDeaths = delta.minimapDeaths;
+
+      if (inc.triggers) {
+        if (Array.isArray(delta.triggerCooldownChanges) && delta.triggerCooldownChanges.length > 0) {
+          out.triggerCooldownChanges = delta.triggerCooldownChanges;
+        }
+        if (Array.isArray(delta.triggerAdd) && delta.triggerAdd.length > 0) out.triggerAdd = delta.triggerAdd;
+        if (Array.isArray(delta.triggerRemove) && delta.triggerRemove.length > 0) out.triggerRemove = delta.triggerRemove;
+      }
+
+      if (inc.objects && Array.isArray(delta.objectAnimChanges) && delta.objectAnimChanges.length > 0) {
+        out.objectAnimChanges = delta.objectAnimChanges;
+      }
+      if (inc.ground && delta.groundChanges) out.groundChanges = delta.groundChanges;
+      if (inc.entrances && delta.entranceChanges) out.entranceChanges = delta.entranceChanges;
+
+      filteredDeltas.push(out);
+    }
+
+    const response = {
+      ok: true,
+      cursor: endTick,
+      afterTick: effectiveAfter,
+      fromTick: startTick,
+      toTick: endTick,
+      deltas: filteredDeltas
+    };
+
+    const delivery = format?.delivery || 'inline';
+    if (delivery === 'resource') {
+      const serialized = serializePayload(response, format?.pretty);
+      if (!serialized.ok) {
+        return attachEvents(session, { ok: false, reason: 'delta_serialize_failed' });
+      }
+      const stored = session.resources?.put?.({
+        sessionId: session.id,
+        bytes: Buffer.from(serialized.json),
+        mimeType: 'application/json',
+        meta: { kind: 'state-delta' }
+      });
+      if (!stored?.uri) {
+        return attachEvents(session, { ok: false, reason: 'resource_store_failed' });
+      }
+      return attachEvents(session, {
+        ok: true,
+        cursor: endTick,
+        resourceUri: stored?.uri || null,
+        sizeBytes: stored?.sizeBytes ?? null
+      });
+    }
+
+    return attachEvents(session, response);
+  };
+
+  const getLemmingsSummaryTool = async (args) => {
+    const { sessionId, filter, topK, includeSelected } = schemas.LemmingsSummarySchema.parse(args || {});
+    const session = getSession(sessionId);
+    const state = await getState(session);
+    if (!state) {
+      return attachEvents(session, { ok: false, reason: 'harness_unavailable' });
+    }
+    const summary = buildLemmingSummary(state, {
+      activeOnly: filter?.activeOnly !== false,
+      inViewOnly: !!filter?.inViewOnly,
+      rectWorld: filter?.rectWorld,
+      topK,
+      includeSelected
+    });
+    return attachEvents(session, summary);
+  };
+
+  return {
+    getStateTool,
+    getStateDeltaTool,
+    getLemmingsSummaryTool
+  };
+};
+
+export { createStateToolHandlers };
diff --git a/mcp/toolRouting.js b/mcp/toolRouting.js
new file mode 100644
index 00000000..9f182f97
--- /dev/null
+++ b/mcp/toolRouting.js
@@ -0,0 +1,89 @@
+/**
+ * Normalize a requested MCP tool name. Hard-cut MCP routing accepts only the
+ * canonical underscore tool names exposed by list-tools.
+ *
+ * @param {unknown} rawName
+ * @returns {string}
+ */
+const resolveToolName = (rawName) => rawName == null ? '' : String(rawName).trim();
+
+/**
+ * Build list-tools definitions and call-tool routes from a surface registry.
+ * Routes include all known tools so disabled-surface calls can still return
+ * explicit policy errors instead of unknown-tool errors.
+ *
+ * @param {{
+ *   specs?: Array<{name?: string, description?: string, schema?: unknown}>,
+ *   handlersBySurface?: Map<string, Map<string, (...args: any[]) => any>>,
+ *   toolSurfaceByName?: Map<string, string>
+ * }} surfaceRegistry
+ * @param {{
+ *   activeSurfaces?: Set<string>,
+ *   toToolName?: (name: string) => string,
+ *   toJsonSchemaCompat?: (schema: unknown) => unknown
+ * }} [options]
+ * @throws {Error} When two canonical tool names normalize to the same exposed tool name.
+ * @returns {{
+ *   toolDefs: Array<{name: string, description: string, inputSchema: unknown}>,
+ *   toolRoutes: Map<string, {
+ *     toolName: string,
+ *     canonicalName: string,
+ *     surface: string,
+ *     handler: (...args: any[]) => any
+ *   }>
+ * }}
+ */
+const buildToolCatalog = (
+  surfaceRegistry,
+  {
+    activeSurfaces = null,
+    toToolName = (name) => name,
+    toJsonSchemaCompat = (schema) => schema
+  } = {}
+) => {
+  const toolDefs = [];
+  const toolRoutes = new Map();
+  const specs = Array.isArray(surfaceRegistry?.specs) ? surfaceRegistry.specs : [];
+  const handlersBySurface = surfaceRegistry?.handlersBySurface;
+  const toolSurfaceByName = surfaceRegistry?.toolSurfaceByName;
+  const hasActiveFilter = activeSurfaces instanceof Set;
+
+  for (const spec of specs) {
+    const canonicalName = String(spec?.name || '');
+    if (!canonicalName) continue;
+    const toolName = toToolName(canonicalName);
+    const existing = toolRoutes.get(toolName);
+    if (existing && existing.canonicalName !== canonicalName) {
+      throw new Error(
+        `Tool name collision: \"${existing.canonicalName}\" and \"${canonicalName}\" both map to \"${toolName}\"`
+      );
+    }
+    const surface = toolSurfaceByName?.get(canonicalName);
+    const handler = handlersBySurface?.get(surface)?.get(canonicalName) || null;
+    if (!surface || !handler) continue;
+
+    toolRoutes.set(toolName, {
+      toolName,
+      canonicalName,
+      surface,
+      handler
+    });
+
+    if (hasActiveFilter && !activeSurfaces.has(surface)) continue;
+    toolDefs.push({
+      name: toolName,
+      description: String(spec?.description || ''),
+      inputSchema: toJsonSchemaCompat(spec?.schema)
+    });
+  }
+
+  return {
+    toolDefs,
+    toolRoutes
+  };
+};
+
+export {
+  buildToolCatalog,
+  resolveToolName
+};
diff --git a/mcp/tools/editor.js b/mcp/tools/editor.js
new file mode 100644
index 00000000..6a2837f2
--- /dev/null
+++ b/mcp/tools/editor.js
@@ -0,0 +1,63 @@
+const EDITOR_SURFACE = 'editor';
+const EDITOR_NAMESPACES = Object.freeze(['editor', 'objects']);
+const EDITOR_HANDLER_MAP = Object.freeze([
+  ['editor.apply', 'editorApplyTool'],
+  ['objects.list', 'listObjectsTool'],
+  ['objects.place', 'placeObjectsTool'],
+  ['objects.update', 'updateObjectsTool'],
+  ['objects.delete', 'deleteObjectsTool']
+]);
+
+const buildEditorToolSpecs = (schemas) => [
+  {
+    name: 'editor.apply',
+    description: 'Apply editor mutations through the E2E harness.',
+    schema: schemas.EditorApplySchema
+  },
+  {
+    name: 'objects.list',
+    description: 'List editor objects with optional bbox/paging filters and revision deltas.',
+    schema: schemas.ObjectsListSchema
+  },
+  {
+    name: 'objects.place',
+    description: 'Place one or more editor objects via typed mutation calls.',
+    schema: schemas.ObjectsPlaceSchema
+  },
+  {
+    name: 'objects.update',
+    description: 'Update one or more editor objects via typed mutation calls.',
+    schema: schemas.ObjectsUpdateSchema
+  },
+  {
+    name: 'objects.delete',
+    description: 'Delete one or more editor objects via typed mutation calls.',
+    schema: schemas.ObjectsDeleteSchema
+  }
+];
+
+/**
+ * Build dispatch handlers for editor tools.
+ *
+ * @param {Record<string, any>} handlers
+ * @throws {Error} When a required handler is missing.
+ * @returns {Map<string, (...args: any[]) => any>}
+ */
+const buildEditorToolHandlers = (handlers = {}) => {
+  const routes = [];
+  for (const [toolName, handlerKey] of EDITOR_HANDLER_MAP) {
+    const handler = handlers[handlerKey];
+    if (typeof handler !== 'function') {
+      throw new Error(`Missing editor tool handler: ${handlerKey}`);
+    }
+    routes.push([toolName, handler]);
+  }
+  return new Map(routes);
+};
+
+export {
+  EDITOR_NAMESPACES,
+  EDITOR_SURFACE,
+  buildEditorToolHandlers,
+  buildEditorToolSpecs
+};
diff --git a/mcp/tools/game.js b/mcp/tools/game.js
new file mode 100644
index 00000000..43340366
--- /dev/null
+++ b/mcp/tools/game.js
@@ -0,0 +1,100 @@
+const GAME_SURFACE = 'game';
+const GAME_NAMESPACES = Object.freeze(['session', 'time', 'state', 'lemming', 'skill']);
+
+const GAME_HANDLER_MAP = Object.freeze([
+  ['session.create', 'createSession'],
+  ['session.close', 'closeSession'],
+  ['time.pause', 'pauseTime'],
+  ['time.resume', 'resumeTime'],
+  ['time.step', 'stepTime'],
+  ['state.get', 'getStateTool'],
+  ['state.delta', 'getStateDeltaTool'],
+  ['lemming.summary', 'getLemmingsSummaryTool'],
+  ['lemming.select', 'selectLemmingTool'],
+  ['skill.apply', 'applySkillTool']
+]);
+
+/**
+ * Build typed MCP tool specs for the game surface.
+ *
+ * @param {Record<string, any>} schemas
+ * @returns {Array<{name:string,description:string,schema:any}>}
+ */
+const buildGameToolSpecs = (schemas) => [
+  {
+    name: 'session.create',
+    description: 'Launch a Playwright session and load the game with the E2E harness.',
+    schema: schemas.SessionCreateSchema
+  },
+  {
+    name: 'session.close',
+    description: 'Close a Playwright session and clear resources/events.',
+    schema: schemas.SessionCloseSchema
+  },
+  {
+    name: 'time.pause',
+    description: 'Pause the game timer via the E2E harness.',
+    schema: schemas.TimeSchema
+  },
+  {
+    name: 'time.resume',
+    description: 'Resume the game timer via the E2E harness.',
+    schema: schemas.TimeSchema
+  },
+  {
+    name: 'time.step',
+    description: 'Step the game timer forward or backward by a number of ticks.',
+    schema: schemas.TimeStepSchema
+  },
+  {
+    name: 'state.get',
+    description: 'Fetch a structured state snapshot from the E2E harness.',
+    schema: schemas.StateGetSchema
+  },
+  {
+    name: 'state.delta',
+    description: 'Return filtered history deltas between ticks (defaults to changes since the last state.get).',
+    schema: schemas.StateDeltaSchema
+  },
+  {
+    name: 'lemming.summary',
+    description: 'Return aggregated lemming summary data.',
+    schema: schemas.LemmingsSummarySchema
+  },
+  {
+    name: 'lemming.select',
+    description: 'Select a lemming by ID via the E2E harness.',
+    schema: schemas.LemmingSelectSchema
+  },
+  {
+    name: 'skill.apply',
+    description: 'Apply a skill to a selected lemming using keybindings.',
+    schema: schemas.SkillApplySchema
+  }
+];
+
+/**
+ * Build dispatch handlers for game tools.
+ *
+ * @param {Record<string, any>} handlers
+ * @throws {Error} When a required handler is missing.
+ * @returns {Map<string, (...args: any[]) => any>}
+ */
+const buildGameToolHandlers = (handlers = {}) => {
+  const routes = [];
+  for (const [toolName, handlerKey] of GAME_HANDLER_MAP) {
+    const handler = handlers[handlerKey];
+    if (typeof handler !== 'function') {
+      throw new Error(`Missing game tool handler: ${handlerKey}`);
+    }
+    routes.push([toolName, handler]);
+  }
+  return new Map(routes);
+};
+
+export {
+  GAME_NAMESPACES,
+  GAME_SURFACE,
+  buildGameToolHandlers,
+  buildGameToolSpecs
+};
diff --git a/mcp/tools/interact.js b/mcp/tools/interact.js
new file mode 100644
index 00000000..d06cae5b
--- /dev/null
+++ b/mcp/tools/interact.js
@@ -0,0 +1,82 @@
+const INTERACT_SURFACE = 'interact';
+const INTERACT_NAMESPACES = Object.freeze(['input', 'vision', 'watch', 'events']);
+
+const INTERACT_HANDLER_MAP = Object.freeze([
+  ['input.action', 'inputActionTool'],
+  ['input.keys', 'inputKeysTool'],
+  ['vision.capture', 'visionCaptureTool'],
+  ['vision.captureSequence', 'visionSequenceTool'],
+  ['watch.create', 'watchCreateTool'],
+  ['watch.cancel', 'watchCancelTool'],
+  ['events.poll', 'eventsPollTool']
+]);
+
+/**
+ * Build typed MCP tool specs for the interaction surface.
+ *
+ * @param {Record<string, any>} schemas
+ * @returns {Array<{name:string,description:string,schema:any}>}
+ */
+const buildInteractToolSpecs = (schemas) => [
+  {
+    name: 'input.action',
+    description: 'Execute a named action from keybindings.json.',
+    schema: schemas.InputActionSchema
+  },
+  {
+    name: 'input.keys',
+    description: 'Inject low-level key events.',
+    schema: schemas.InputKeysSchema
+  },
+  {
+    name: 'vision.capture',
+    description: 'Capture a screenshot of the page or canvas.',
+    schema: schemas.VisionCaptureSchema
+  },
+  {
+    name: 'vision.captureSequence',
+    description: 'Capture multiple frames across time.',
+    schema: schemas.VisionSequenceSchema
+  },
+  {
+    name: 'watch.create',
+    description: 'Create a watch that emits events based on ticks or state changes.',
+    schema: schemas.WatchCreateSchema
+  },
+  {
+    name: 'watch.cancel',
+    description: 'Cancel a watch.',
+    schema: schemas.WatchCancelSchema
+  },
+  {
+    name: 'events.poll',
+    description: 'Poll events since a cursor.',
+    schema: schemas.EventsPollSchema
+  }
+];
+
+/**
+ * Build dispatch handlers for interaction tools.
+ *
+ * @param {Record<string, any>} handlers
+ * @throws {Error} When a required handler is missing.
+ * @returns {Map<string, (...args: any[]) => any>}
+ */
+const buildInteractToolHandlers = (handlers = {}) => {
+  const routes = [];
+  for (const [toolName, handlerKey] of INTERACT_HANDLER_MAP) {
+    const handler = handlers[handlerKey];
+    if (typeof handler !== 'function') {
+      throw new Error(`Missing interact tool handler: ${handlerKey}`);
+    }
+    routes.push([toolName, handler]);
+  }
+  return new Map(routes);
+};
+
+export {
+  INTERACT_NAMESPACES,
+  INTERACT_SURFACE,
+  buildInteractToolHandlers,
+  buildInteractToolSpecs
+};
diff --git a/mcp/tools/solver.js b/mcp/tools/solver.js
new file mode 100644
index 00000000..18e4d8f9
--- /dev/null
+++ b/mcp/tools/solver.js
@@ -0,0 +1,45 @@
+const SOLVER_SURFACE = 'solver';
+const SOLVER_NAMESPACES = Object.freeze(['solver']);
+
+const SOLVER_HANDLER_MAP = Object.freeze([
+  ['solver.snapshot', 'solverSnapshotTool'],
+  ['solver.route', 'solverRouteTool'],
+  ['solver.replay', 'solverReplayTool']
+]);
+
+const buildSolverToolSpecs = (schemas) => [
+  {
+    name: 'solver.snapshot',
+    description: 'Extract compact deterministic solver snapshot hashes from a local source descriptor.',
+    schema: schemas.SolverSnapshotSchema
+  },
+  {
+    name: 'solver.route',
+    description: 'Build a bounded reachability route skeleton without claiming runtime solvability.',
+    schema: schemas.SolverRouteSchema
+  },
+  {
+    name: 'solver.replay',
+    description: 'Replay a candidate action script through the solver runtime adapter authority path.',
+    schema: schemas.SolverReplaySchema
+  }
+];
+
+const buildSolverToolHandlers = (handlers = {}) => {
+  const routes = [];
+  for (const [toolName, handlerKey] of SOLVER_HANDLER_MAP) {
+    const handler = handlers[handlerKey];
+    if (typeof handler !== 'function') {
+      throw new Error(`Missing solver tool handler: ${handlerKey}`);
+    }
+    routes.push([toolName, handler]);
+  }
+  return new Map(routes);
+};
+
+export {
+  SOLVER_NAMESPACES,
+  SOLVER_SURFACE,
+  buildSolverToolHandlers,
+  buildSolverToolSpecs
+};
diff --git a/mcp/tools/surfaces.js b/mcp/tools/surfaces.js
new file mode 100644
index 00000000..6be79d7d
--- /dev/null
+++ b/mcp/tools/surfaces.js
@@ -0,0 +1,131 @@
+import {
+  GAME_NAMESPACES,
+  GAME_SURFACE,
+  buildGameToolHandlers,
+  buildGameToolSpecs
+} from './game.js';
+import {
+  EDITOR_NAMESPACES,
+  EDITOR_SURFACE,
+  buildEditorToolHandlers,
+  buildEditorToolSpecs
+} from './editor.js';
+import {
+  INTERACT_NAMESPACES,
+  INTERACT_SURFACE,
+  buildInteractToolHandlers,
+  buildInteractToolSpecs
+} from './interact.js';
+import {
+  SOLVER_NAMESPACES,
+  SOLVER_SURFACE,
+  buildSolverToolHandlers,
+  buildSolverToolSpecs
+} from './solver.js';
+
+const ALL_TOOL_SURFACES = Object.freeze([GAME_SURFACE, EDITOR_SURFACE, INTERACT_SURFACE, SOLVER_SURFACE]);
+const DEFAULT_ENABLED_SURFACES = new Set(ALL_TOOL_SURFACES);
+
+const SURFACE_MODULES = Object.freeze([
+  {
+    surface: GAME_SURFACE,
+    namespaces: GAME_NAMESPACES,
+    buildSpecs: buildGameToolSpecs,
+    buildHandlers: buildGameToolHandlers
+  },
+  {
+    surface: EDITOR_SURFACE,
+    namespaces: EDITOR_NAMESPACES,
+    buildSpecs: buildEditorToolSpecs,
+    buildHandlers: buildEditorToolHandlers
+  },
+  {
+    surface: INTERACT_SURFACE,
+    namespaces: INTERACT_NAMESPACES,
+    buildSpecs: buildInteractToolSpecs,
+    buildHandlers: buildInteractToolHandlers
+  },
+  {
+    surface: SOLVER_SURFACE,
+    namespaces: SOLVER_NAMESPACES,
+    buildSpecs: buildSolverToolSpecs,
+    buildHandlers: buildSolverToolHandlers
+  }
+]);
+
+/**
+ * Parse enabled MCP surfaces from an environment-style CSV string.
+ *
+ * @param {unknown} raw
+ * @returns {Set<string>}
+ */
+const parseEnabledSurfaces = (raw) => {
+  if (!raw || !String(raw).trim()) return new Set(DEFAULT_ENABLED_SURFACES);
+  const parts = String(raw)
+    .split(',')
+    .map((part) => part.trim().toLowerCase())
+    .filter(Boolean);
+  if (!parts.length) return new Set(DEFAULT_ENABLED_SURFACES);
+  const enabled = new Set();
+  for (const part of parts) {
+    if (!ALL_TOOL_SURFACES.includes(part)) {
+      throw new Error(`Unknown MCP surface: ${part}`);
+    }
+    enabled.add(part);
+  }
+  return enabled;
+};
+
+/**
+ * Build tool-spec and handler registries grouped by semantic MCP surface.
+ *
+ * @param {object} schemas
+ * @param {object} handlers
+ * @param {Set<string>} [enabledSurfaces]
+ * @returns {{
+ *   specs: Array<{name: string}>,
+ *   handlersBySurface: Map<string, Map<string, Function>>,
+ *   toolSurfaceByName: Map<string, string>
+ * }}
+ */
+const buildSurfaceRegistry = (schemas, handlers, enabledSurfaces) => {
+  const activeSurfaces = enabledSurfaces instanceof Set
+    ? enabledSurfaces
+    : new Set(DEFAULT_ENABLED_SURFACES);
+  const specsBySurface = new Map();
+  const handlersBySurface = new Map();
+  const toolSurfaceByName = new Map();
+  for (const module of SURFACE_MODULES) {
+    const specs = module.buildSpecs(schemas);
+    const surfaceHandlers = module.buildHandlers(handlers);
+    specsBySurface.set(module.surface, specs);
+    handlersBySurface.set(module.surface, surfaceHandlers);
+    for (const spec of specs) {
+      const namespace = String(spec.name).split('.', 1)[0];
+      if (!module.namespaces.includes(namespace)) {
+        throw new Error(`Tool namespace mismatch for surface "${module.surface}": ${spec.name}`);
+      }
+      toolSurfaceByName.set(spec.name, module.surface);
+    }
+  }
+
+  const specs = [];
+  for (const [surface, list] of specsBySurface.entries()) {
+    if (!activeSurfaces.has(surface)) continue;
+    for (const spec of list) {
+      specs.push(spec);
+    }
+  }
+
+  return {
+    specs,
+    handlersBySurface,
+    toolSurfaceByName
+  };
+};
+
+export {
+  ALL_TOOL_SURFACES,
+  parseEnabledSurfaces,
+  buildSurfaceRegistry
+};
diff --git a/mcp/visionTools.js b/mcp/visionTools.js
new file mode 100644
index 00000000..7eb8f475
--- /dev/null
+++ b/mcp/visionTools.js
@@ -0,0 +1,261 @@
+const createVisionToolHandlers = ({
+  schemas,
+  getSession,
+  callE2E,
+  getTickIndex,
+  attachEvents,
+  formatToMime,
+  makeId,
+  nowIso,
+  maxCaptureSequenceFrames
+}) => {
+  const { VisionCaptureSchema, VisionSequenceSchema } = schemas;
+  const MCP_MAX_CAPTURE_SEQUENCE_FRAMES = maxCaptureSequenceFrames;
+
+  const resolveCanvasMetrics = async (session) => {
+    const result = await callE2E(session, 'getCanvasMetrics');
+    return result.ok ? result.value : null;
+  };
+
+  const resolveCanvasClip = (metrics, target, rect) => {
+    if (!metrics) return null;
+    const scaleX = metrics.rect.width / metrics.size.width;
+    const scaleY = metrics.rect.height / metrics.size.height;
+
+    let base = null;
+    if (target === 'gameCanvas' && metrics.gameRect) {
+      base = metrics.gameRect;
+    } else if (target === 'guiCanvas' && metrics.guiRect) {
+      base = metrics.guiRect;
+    } else if (target === 'stageCanvas') {
+      base = null;
+    }
+
+    const baseCss = base
+      ? {
+        x: base.x * scaleX,
+        y: base.y * scaleY,
+        width: base.width * scaleX,
+        height: base.height * scaleY
+      }
+      : { x: 0, y: 0, width: metrics.rect.width, height: metrics.rect.height };
+
+    const clip = rect
+      ? {
+        x: baseCss.x + rect.x,
+        y: baseCss.y + rect.y,
+        width: rect.width,
+        height: rect.height
+      }
+      : baseCss;
+
+    return {
+      clip: {
+        x: metrics.rect.x + clip.x,
+        y: metrics.rect.y + clip.y,
+        width: clip.width,
+        height: clip.height
+      },
+      width: clip.width,
+      height: clip.height
+    };
+  };
+
+  const captureFrame = async (session, options) => {
+    const target = options.target || 'page';
+    const rect = options.rect || null;
+    const format = options.format || 'png';
+    const quality = Number.isFinite(options.quality)
+      ? Math.max(1, Math.min(100, Math.trunc(options.quality)))
+      : null;
+    const delivery = options.delivery || 'resource';
+    const tag = options.tag || null;
+    const mimeType = formatToMime(format);
+
+    let clip = null;
+    let width = null;
+    let height = null;
+
+    if (target === 'rect') {
+      if (!rect) return { ok: false, reason: 'rect_required' };
+      clip = rect;
+      width = rect?.width ?? null;
+      height = rect?.height ?? null;
+    } else if (target === 'gameCanvas' || target === 'guiCanvas' || target === 'stageCanvas') {
+      const metrics = await resolveCanvasMetrics(session);
+      if (!metrics) return { ok: false, reason: 'canvas_missing' };
+      const resolved = resolveCanvasClip(metrics, target, rect);
+      clip = resolved?.clip || null;
+      width = resolved?.width ?? null;
+      height = resolved?.height ?? null;
+    } else if (rect) {
+      clip = rect;
+      width = rect.width;
+      height = rect.height;
+    } else {
+      const viewport = session.page.viewportSize();
+      width = viewport?.width ?? null;
+      height = viewport?.height ?? null;
+    }
+
+    if (clip && (!Number.isFinite(clip.width) || !Number.isFinite(clip.height) || clip.width <= 0 || clip.height <= 0)) {
+      return { ok: false, reason: 'invalid_clip' };
+    }
+
+    const screenshotOptions = {
+      type: format
+    };
+    if (quality != null && (format === 'jpeg' || format === 'webp')) {
+      screenshotOptions.quality = quality;
+    }
+    if (clip) {
+      screenshotOptions.clip = clip;
+    }
+
+    const bytes = await session.page.screenshot(screenshotOptions);
+    const sizeBytes = bytes.length;
+    const tickIndex = await getTickIndex(session);
+
+    const frame = {
+      id: makeId(),
+      mimeType,
+      width: Math.round(width ?? 0),
+      height: Math.round(height ?? 0),
+      tickIndex: Number.isFinite(tickIndex) ? tickIndex : null,
+      takenAt: nowIso(),
+      target,
+      tag: tag || undefined
+    };
+    if (rect) {
+      frame.clip = rect;
+    }
+
+    if (delivery === 'inline') {
+      frame.dataBase64 = Buffer.from(bytes).toString('base64');
+      return { ok: true, frame };
+    }
+
+    const stored = session.resources.put({
+      sessionId: session.id,
+      bytes,
+      mimeType,
+      meta: { kind: 'capture', target, tag }
+    });
+    if (!stored?.uri) {
+      return { ok: false, reason: 'resource_store_failed' };
+    }
+    frame.resourceUri = stored?.uri;
+    frame.sizeBytes = sizeBytes;
+    if (stored?.expiresAt) {
+      frame.expiresAt = stored.expiresAt;
+    }
+    return { ok: true, frame };
+  };
+
+  const captureSequence = async (session, args) => {
+    const frames = [];
+    const sequenceId = makeId();
+    const mode = args.mode;
+    const stepBy = Number.isFinite(args.stepBy) ? args.stepBy : 1;
+    const everyMs = Number.isFinite(args.everyMs) ? args.everyMs : 250;
+    const capture = args.capture || {};
+    const requestedFrames = Number.isFinite(args.frames) ? Math.trunc(args.frames) : 1;
+    const total = Math.min(MCP_MAX_CAPTURE_SEQUENCE_FRAMES, Math.max(1, requestedFrames));
+
+    if (mode === 'step') {
+      await callE2E(session, 'pause');
+    }
+
+    for (let i = 0; i < total; i += 1) {
+      const result = await captureFrame(session, capture);
+      if (!result?.ok || !result?.frame) {
+        return {
+          ok: false,
+          sequenceId,
+          reason: result?.reason || 'capture_failed',
+          failedAtFrame: i,
+          frames
+        };
+      }
+      frames.push(result.frame);
+      if (i === total - 1) break;
+      if (mode === 'step') {
+        await callE2E(session, 'step', stepBy);
+      } else {
+        await session.page.waitForTimeout(everyMs);
+      }
+    }
+
+    let manifestResourceUri = null;
+    if (args.returnManifest !== false) {
+      const manifest = {
+        sequenceId,
+        createdAt: nowIso(),
+        frames
+      };
+      const stored = session.resources.put({
+        sessionId: session.id,
+        bytes: Buffer.from(JSON.stringify(manifest)),
+        mimeType: 'application/json',
+        meta: { kind: 'capture-manifest' }
+      });
+      if (!stored?.uri) {
+        return {
+          ok: false,
+          sequenceId,
+          reason: 'resource_store_failed',
+          failedAtFrame: total,
+          frames
+        };
+      }
+      manifestResourceUri = stored?.uri || null;
+    }
+
+    session.events.add({
+      source: 'agent',
+      type: 'capture',
+      summary: `captureSequence:${sequenceId}`,
+      resourceUris: manifestResourceUri ? [manifestResourceUri] : undefined
+    });
+
+    return {
+      ok: true,
+      sequenceId,
+      frames,
+      manifestResourceUri
+    };
+  };
+
+  const visionCaptureTool = async (args) => {
+    const options = VisionCaptureSchema.parse(args || {});
+    const session = getSession(options.sessionId);
+    const result = await captureFrame(session, options);
+    if (!result.ok) {
+      return attachEvents(session, { ok: false, reason: result.reason });
+    }
+    session.events.add({
+      source: 'agent',
+      type: 'capture',
+      summary: 'capture',
+      resourceUris: result.frame?.resourceUri ? [result.frame.resourceUri] : undefined
+    });
+    return attachEvents(session, { frame: result.frame });
+  };
+
+  const visionSequenceTool = async (args) => {
+    const options = VisionSequenceSchema.parse(args || {});
+    const session = getSession(options.sessionId);
+    const result = await captureSequence(session, options);
+    return attachEvents(session, result);
+  };
+
+  return {
+    captureFrame,
+    captureSequence,
+    resolveCanvasMetrics,
+    visionCaptureTool,
+    visionSequenceTool
+  };
+};
+
+export { createVisionToolHandlers };
diff --git a/mcp/watchPointers.js b/mcp/watchPointers.js
new file mode 100644
index 00000000..b9dc80ab
--- /dev/null
+++ b/mcp/watchPointers.js
@@ -0,0 +1,291 @@
+const HASH_OFFSET_BASIS = 2166136261;
+const HASH_PRIME = 16777619;
+const NUMBER_HASH_VIEW = new DataView(new ArrayBuffer(8));
+const POINTER_EMPTY_PATH = Object.freeze([]);
+const POINTER_INVALID_PATH = null;
+
+/**
+ * Parse an RFC6901 JSON pointer into path segments.
+ * @param {string|null|undefined} pointer
+ * @returns {string[]|null}
+ */
+const parseJsonPointer = (pointer) => {
+  if (pointer == null || pointer === '') return POINTER_EMPTY_PATH;
+  const source = String(pointer);
+  if (source === '/') return [''];
+  if (!source.startsWith('/')) return POINTER_INVALID_PATH;
+  const decoded = [];
+  for (const part of source.slice(1).split('/')) {
+    if (/~(?:$|[^01])/.test(part)) {
+      return POINTER_INVALID_PATH;
+    }
+    decoded.push(part.replace(/~1/g, '/').replace(/~0/g, '~'));
+  }
+  return decoded;
+};
+
+/**
+ * Resolve a value from an object using pointer segments or a pointer string.
+ * @param {object} obj
+ * @param {string|string[]|null} pointerOrPath
+ * @returns {*}
+ */
+const readPointerValue = (obj, pointerOrPath) => {
+  if (pointerOrPath === POINTER_INVALID_PATH) return undefined;
+  const path = Array.isArray(pointerOrPath) ? pointerOrPath : parseJsonPointer(pointerOrPath);
+  if (path === POINTER_INVALID_PATH) return undefined;
+  let current = obj;
+  for (const part of path) {
+    if (current == null) return undefined;
+    current = current[part];
+  }
+  return current;
+};
+
+const hashByte = (hash, byte) => Math.imul((hash ^ (byte & 0xff)) >>> 0, HASH_PRIME) >>> 0;
+
+const hashUint32 = (hash, value) => {
+  let next = hashByte(hash, value);
+  next = hashByte(next, value >>> 8);
+  next = hashByte(next, value >>> 16);
+  next = hashByte(next, value >>> 24);
+  return next >>> 0;
+};
+
+const hashString = (hash, value) => {
+  let next = hash;
+  for (let i = 0; i < value.length; i += 1) {
+    const code = value.charCodeAt(i);
+    next = hashByte(next, code);
+    next = hashByte(next, code >>> 8);
+  }
+  return next >>> 0;
+};
+
+const hashNumber = (hash, value) => {
+  NUMBER_HASH_VIEW.setFloat64(0, value, true);
+  let next = hash;
+  for (let i = 0; i < 8; i += 1) {
+    next = hashByte(next, NUMBER_HASH_VIEW.getUint8(i));
+  }
+  return next >>> 0;
+};
+
+const hashValue = (value, seen = new WeakSet()) => {
+  const type = typeof value;
+  if (value === null) return hashByte(HASH_OFFSET_BASIS, 1);
+  if (type === 'undefined') return hashByte(HASH_OFFSET_BASIS, 2);
+  if (type === 'boolean') return hashByte(hashByte(HASH_OFFSET_BASIS, 3), value ? 1 : 0);
+  if (type === 'number') return hashNumber(hashByte(HASH_OFFSET_BASIS, 4), value);
+  if (type === 'string') return hashString(hashByte(HASH_OFFSET_BASIS, 5), value);
+  if (type === 'bigint') return hashString(hashByte(HASH_OFFSET_BASIS, 6), value.toString());
+  if (type === 'symbol') return hashString(hashByte(HASH_OFFSET_BASIS, 7), String(value.description ?? ''));
+  if (type === 'function') return hashString(hashByte(HASH_OFFSET_BASIS, 8), value.name || '');
+  if (seen.has(value)) return hashByte(HASH_OFFSET_BASIS, 250);
+  seen.add(value);
+
+  let hash = HASH_OFFSET_BASIS;
+  if (Array.isArray(value)) {
+    hash = hashByte(hash, 9);
+    hash = hashUint32(hash, value.length);
+    for (let i = 0; i < value.length; i += 1) {
+      hash = hashUint32(hash, hashValue(value[i], seen));
+    }
+    seen.delete(value);
+    return hash >>> 0;
+  }
+
+  if (value instanceof Map) {
+    hash = hashByte(hash, 14);
+    const entryHashes = [];
+    for (const [entryKey, entryValue] of value.entries()) {
+      let entryHash = HASH_OFFSET_BASIS;
+      entryHash = hashUint32(entryHash, hashValue(entryKey, seen));
+      entryHash = hashUint32(entryHash, hashValue(entryValue, seen));
+      entryHashes.push(entryHash >>> 0);
+    }
+    entryHashes.sort((left, right) => left - right);
+    hash = hashUint32(hash, entryHashes.length);
+    for (const entryHash of entryHashes) {
+      hash = hashUint32(hash, entryHash);
+    }
+    seen.delete(value);
+    return hash >>> 0;
+  }
+
+  if (value instanceof Set) {
+    hash = hashByte(hash, 15);
+    const itemHashes = [];
+    for (const item of value.values()) {
+      itemHashes.push(hashValue(item, seen));
+    }
+    itemHashes.sort((left, right) => left - right);
+    hash = hashUint32(hash, itemHashes.length);
+    for (const itemHash of itemHashes) {
+      hash = hashUint32(hash, itemHash);
+    }
+    seen.delete(value);
+    return hash >>> 0;
+  }
+
+  if (value instanceof ArrayBuffer) {
+    hash = hashByte(hash, 13);
+    const bytes = new Uint8Array(value);
+    hash = hashUint32(hash, bytes.byteLength);
+    for (const byte of bytes) {
+      hash = hashByte(hash, byte);
+    }
+    seen.delete(value);
+    return hash >>> 0;
+  }
+
+  if (ArrayBuffer.isView(value)) {
+    hash = hashByte(hash, 10);
+    hash = hashUint32(hash, value.byteLength || 0);
+    if (value instanceof DataView) {
+      for (let i = 0; i < value.byteLength; i += 1) {
+        hash = hashByte(hash, value.getUint8(i));
+      }
+    } else {
+      for (const item of value) {
+        if (typeof item === 'bigint') {
+          hash = hashByte(hash, 16);
+          hash = hashString(hash, item.toString());
+        } else {
+          hash = hashByte(hash, 17);
+          hash = hashNumber(hash, Number(item));
+        }
+      }
+    }
+    seen.delete(value);
+    return hash >>> 0;
+  }
+
+  if (value instanceof Date) {
+    hash = hashByte(hash, 11);
+    hash = hashNumber(hash, value.getTime());
+    seen.delete(value);
+    return hash >>> 0;
+  }
+
+  hash = hashByte(hash, 12);
+  const keys = Object.keys(value).sort();
+  hash = hashUint32(hash, keys.length);
+  for (const key of keys) {
+    hash = hashString(hash, key);
+    hash = hashUint32(hash, hashValue(value[key], seen));
+  }
+  seen.delete(value);
+  return hash >>> 0;
+};
+
+const buildPointerFingerprint = (value) => {
+  if (value === null) return { kind: 'null' };
+  const type = typeof value;
+  if (type === 'undefined') return { kind: 'undefined' };
+  if (type === 'boolean') return { kind: 'boolean', value };
+  if (type === 'number') return { kind: 'number', value };
+  if (type === 'string') return { kind: 'string', value };
+  if (type === 'bigint') return { kind: 'bigint', value: value.toString() };
+  if (type === 'symbol') return { kind: 'symbol', value: String(value.description ?? '') };
+  if (type === 'function') return { kind: 'function', value: value.name || '' };
+
+  if (value instanceof Date) {
+    return {
+      kind: 'date',
+      value: value.getTime()
+    };
+  }
+
+  if (value instanceof ArrayBuffer) {
+    return {
+      kind: 'arraybuffer',
+      size: value.byteLength,
+      hash: hashValue(value)
+    };
+  }
+
+  if (ArrayBuffer.isView(value)) {
+    return {
+      kind: 'arraybuffer-view',
+      viewType: value.constructor?.name || 'view',
+      size: value.byteLength || 0,
+      hash: hashValue(value)
+    };
+  }
+
+  if (value instanceof Map) {
+    return {
+      kind: 'map',
+      size: value.size,
+      hash: hashValue(value)
+    };
+  }
+  if (value instanceof Set) {
+    return {
+      kind: 'set',
+      size: value.size,
+      hash: hashValue(value)
+    };
+  }
+
+  const size = Array.isArray(value)
+    ? value.length
+    : Object.keys(value).length;
+  return {
+    kind: Array.isArray(value) ? 'array' : 'object',
+    size,
+    hash: hashValue(value)
+  };
+};
+
+const areFingerprintsEqual = (left, right) => {
+  if (!left || !right) return false;
+  if (left.kind !== right.kind) return false;
+  if (left.kind === 'number') return Object.is(left.value, right.value);
+  if (left.kind === 'boolean' || left.kind === 'string' || left.kind === 'bigint' || left.kind === 'symbol' || left.kind === 'function') {
+    return left.value === right.value;
+  }
+  if (left.kind === 'date') return left.value === right.value;
+  if (left.kind === 'null' || left.kind === 'undefined') return true;
+  if (left.kind === 'arraybuffer-view') {
+    return left.viewType === right.viewType && left.size === right.size && left.hash === right.hash;
+  }
+  return left.size === right.size && left.hash === right.hash;
+};
+
+/**
+ * Create watch state for a JSON pointer against an initial source object.
+ * @param {string} pointer
+ * @param {object} source
+ * @returns {{path:string[]|null,fingerprint:object}}
+ */
+const createPointerWatchState = (pointer, source) => {
+  const path = parseJsonPointer(pointer);
+  return {
+    path,
+    fingerprint: buildPointerFingerprint(readPointerValue(source, path))
+  };
+};
+
+/**
+ * Update a watch state in place and report whether the pointer value changed.
+ * @param {{path:string[]|null,fingerprint:object}} state
+ * @param {object} source
+ * @returns {boolean}
+ */
+const updatePointerWatchState = (state, source) => {
+  const next = buildPointerFingerprint(readPointerValue(source, state.path));
+  if (areFingerprintsEqual(state.fingerprint, next)) {
+    return false;
+  }
+  state.fingerprint = next;
+  return true;
+};
+
+export {
+  parseJsonPointer,
+  readPointerValue,
+  createPointerWatchState,
+  updatePointerWatchState
+};
diff --git a/mcp/watchPolling.js b/mcp/watchPolling.js
new file mode 100644
index 00000000..b7da54d2
--- /dev/null
+++ b/mcp/watchPolling.js
@@ -0,0 +1,273 @@
+const DEFAULT_WATCH_POLLING_CONFIG = Object.freeze({
+  minMs: 0,
+  activeMs: 250,
+  maxMs: 2000,
+  backoffFactor: 1.6,
+  idleThreshold: 3,
+  onDemandMinMs: 100
+});
+
+import {
+  createPointerWatchState,
+  parseJsonPointer,
+  readPointerValue,
+  updatePointerWatchState
+} from './watchPointers.js';
+
+const toFiniteNumber = (value, fallback) => {
+  let number;
+  try {
+    number = Number(value);
+  } catch {
+    number = Number.NaN;
+  }
+  return Number.isFinite(number) ? number : fallback;
+};
+
+const normalizeConfig = (config = {}) => {
+  const minMs = Math.max(0, Math.trunc(toFiniteNumber(config.minMs, DEFAULT_WATCH_POLLING_CONFIG.minMs)));
+  const activeMs = Math.max(minMs, Math.trunc(toFiniteNumber(config.activeMs, DEFAULT_WATCH_POLLING_CONFIG.activeMs)));
+  const maxMs = Math.max(activeMs, Math.trunc(toFiniteNumber(config.maxMs, DEFAULT_WATCH_POLLING_CONFIG.maxMs)));
+  const backoffFactor = Math.max(1, toFiniteNumber(config.backoffFactor, DEFAULT_WATCH_POLLING_CONFIG.backoffFactor));
+  const idleThreshold = Math.max(1, Math.trunc(toFiniteNumber(config.idleThreshold, DEFAULT_WATCH_POLLING_CONFIG.idleThreshold)));
+  const onDemandMinMs = Math.max(0, Math.trunc(toFiniteNumber(config.onDemandMinMs, DEFAULT_WATCH_POLLING_CONFIG.onDemandMinMs)));
+  return {
+    minMs,
+    activeMs,
+    maxMs,
+    backoffFactor,
+    idleThreshold,
+    onDemandMinMs
+  };
+};
+
+const clampDelay = (value, minMs, maxMs) => {
+  if (!Number.isFinite(value)) return minMs;
+  return Math.min(maxMs, Math.max(minMs, Math.trunc(value)));
+};
+
+class WatchPollingController {
+  constructor({
+    hasWatchesFn,
+    pollFn,
+    setTimerFn = setTimeout,
+    clearTimerFn = clearTimeout,
+    nowFn = Date.now,
+    config
+  } = {}) {
+    if (typeof hasWatchesFn !== 'function') {
+      throw new Error('WatchPollingController requires hasWatchesFn');
+    }
+    if (typeof pollFn !== 'function') {
+      throw new Error('WatchPollingController requires pollFn');
+    }
+    this.hasWatchesFn = hasWatchesFn;
+    this.pollFn = pollFn;
+    this.setTimerFn = setTimerFn;
+    this.clearTimerFn = clearTimerFn;
+    this.nowFn = nowFn;
+    this.config = normalizeConfig(config);
+    this.running = false;
+    this.polling = false;
+    this.pendingImmediate = false;
+    this.idlePolls = 0;
+    this.delayMs = this.config.activeMs;
+    this.lastPollAtMs = null;
+    this.timerHandle = null;
+    this.nextRunAtMs = 0;
+    this._idleWaiters = new Set();
+  }
+
+  start() {
+    if (this.running) return;
+    this.running = true;
+    this.idlePolls = 0;
+    this.delayMs = this.config.activeMs;
+    this.pendingImmediate = false;
+    this._schedule(0);
+  }
+
+  stop() {
+    this.running = false;
+    this.pendingImmediate = false;
+    this._clearTimer();
+    this._resolveIdleWaiters();
+  }
+
+  async stopAndWait(timeoutMs = 5000) {
+    this.stop();
+    if (!this.polling) return;
+    await this._waitForIdle(timeoutMs);
+  }
+
+  request({ immediate = false } = {}) {
+    if (!this.running || !this.hasWatchesFn()) return;
+    if (immediate) {
+      this.pendingImmediate = true;
+      if (!this.polling) {
+        this._schedule(0);
+      }
+      return;
+    }
+    if (!this.polling) {
+      this._schedule(Math.min(this.delayMs, this.config.activeMs));
+    }
+  }
+
+  async tickNow() {
+    if (!this.running || !this.hasWatchesFn()) return null;
+    if (this.polling) {
+      this.pendingImmediate = true;
+      return null;
+    }
+    const now = this.nowFn();
+    if (Number.isFinite(this.lastPollAtMs) && (now - this.lastPollAtMs) < this.config.onDemandMinMs) {
+      return null;
+    }
+    return this._runPollCycle();
+  }
+
+  getSnapshot() {
+    return {
+      running: this.running,
+      polling: this.polling,
+      pendingImmediate: this.pendingImmediate,
+      idlePolls: this.idlePolls,
+      delayMs: this.delayMs,
+      lastPollAtMs: this.lastPollAtMs,
+      nextRunAtMs: this.nextRunAtMs
+    };
+  }
+
+  async _onTimer() {
+    this.timerHandle = null;
+    this.nextRunAtMs = 0;
+    try {
+      await this._runPollCycle();
+    } catch (error) {
+      // Ignore timer poll errors and let future polls continue.
+    }
+  }
+
+  async _runPollCycle() {
+    if (!this.running || !this.hasWatchesFn()) return null;
+    if (this.polling) return null;
+    this.polling = true;
+    let outcome = null;
+    let failed = false;
+    try {
+      outcome = await this.pollFn();
+    } catch (error) {
+      failed = true;
+      outcome = null;
+    } finally {
+      this.polling = false;
+      this.lastPollAtMs = this.nowFn();
+      this._resolveIdleWaiters();
+    }
+
+    this._applyOutcome(outcome, failed);
+
+    if (!this.running || !this.hasWatchesFn()) {
+      this._clearTimer();
+      return outcome;
+    }
+    if (this.pendingImmediate) {
+      this.pendingImmediate = false;
+      this._schedule(this.config.minMs);
+      return outcome;
+    }
+    this._schedule(this.delayMs);
+    return outcome;
+  }
+
+  _applyOutcome(outcome, failed) {
+    if (failed) {
+      this.idlePolls += 1;
+      this.delayMs = clampDelay(
+        Math.round(this.delayMs * this.config.backoffFactor),
+        this.config.activeMs,
+        this.config.maxMs
+      );
+      return;
+    }
+
+    const triggeredCount = Math.max(0, Math.trunc(toFiniteNumber(outcome?.triggeredCount, 0)));
+    if (triggeredCount > 0) {
+      this.idlePolls = 0;
+      this.delayMs = this.config.activeMs;
+      return;
+    }
+
+    this.idlePolls += 1;
+    if (this.idlePolls < this.config.idleThreshold) {
+      return;
+    }
+    this.delayMs = clampDelay(
+      Math.round(this.delayMs * this.config.backoffFactor),
+      this.config.activeMs,
+      this.config.maxMs
+    );
+  }
+
+  _schedule(delayMs) {
+    if (!this.running) return;
+    const normalized = clampDelay(delayMs, this.config.minMs, this.config.maxMs);
+    const dueAt = this.nowFn() + normalized;
+    if (this.timerHandle && this.nextRunAtMs > 0 && this.nextRunAtMs <= dueAt) {
+      return;
+    }
+    this._clearTimer();
+    this.nextRunAtMs = dueAt;
+    this.timerHandle = this.setTimerFn(() => {
+      void this._onTimer();
+    }, normalized);
+  }
+
+  _clearTimer() {
+    if (this.timerHandle) {
+      this.clearTimerFn(this.timerHandle);
+    }
+    this.timerHandle = null;
+    this.nextRunAtMs = 0;
+  }
+
+  _waitForIdle(timeoutMs) {
+    if (!this.polling) {
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      const waiter = {
+        resolve,
+        timeoutId: null
+      };
+      if (Number.isFinite(timeoutMs) && timeoutMs >= 0) {
+        waiter.timeoutId = this.setTimerFn(() => {
+          this._idleWaiters.delete(waiter);
+          resolve();
+        }, timeoutMs);
+      }
+      this._idleWaiters.add(waiter);
+    });
+  }
+
+  _resolveIdleWaiters() {
+    if (this.polling || !this._idleWaiters.size) return;
+    for (const waiter of this._idleWaiters) {
+      if (waiter.timeoutId != null) {
+        this.clearTimerFn(waiter.timeoutId);
+      }
+      waiter.resolve();
+    }
+    this._idleWaiters.clear();
+  }
+}
+
+export {
+  DEFAULT_WATCH_POLLING_CONFIG,
+  WatchPollingController,
+  parseJsonPointer,
+  readPointerValue,
+  createPointerWatchState,
+  updatePointerWatchState
+};
diff --git a/mcp/watchTools.js b/mcp/watchTools.js
new file mode 100644
index 00000000..d13e35c4
--- /dev/null
+++ b/mcp/watchTools.js
@@ -0,0 +1,194 @@
+const createWatchToolHandlers = ({
+  schemas,
+  getSession,
+  getState,
+  attachEvents,
+  makeId,
+  readPointerValue,
+  createPointerWatchState,
+  updatePointerWatchState,
+  buildLemmingSummary,
+  captureFrame,
+  pressAction,
+  pressKey
+}) => {
+  const { EventsPollSchema, WatchCancelSchema, WatchCreateSchema } = schemas;
+
+  const startWatchLoop = (session) => {
+    session.watchController?.start();
+  };
+
+  const stopWatchLoop = (session) => {
+    session.watchController?.stop();
+  };
+
+  const requestWatchPoll = (session, { immediate = false } = {}) => {
+    session.watchController?.request({ immediate });
+  };
+
+  const nudgeWatchPolling = (session) => {
+    if (!session?.watches?.size) return;
+    requestWatchPoll(session, { immediate: true });
+  };
+
+  const pollWatches = async (session) => {
+    if (!session.watches.size) return { triggeredCount: 0 };
+    const state = await getState(session);
+    if (!state) return { triggeredCount: 0 };
+    const tickIndex = state.game?.timer?.tickIndex ?? null;
+    let triggeredCount = 0;
+    for (const watch of session.watches.values()) {
+      if (!watch.enabled) continue;
+      let triggered = false;
+      if (watch.type === 'everyTicks') {
+        if (Number.isFinite(tickIndex) && tickIndex - watch.lastTick >= watch.everyTicks) {
+          watch.lastTick = tickIndex;
+          triggered = true;
+        }
+      } else if (watch.type === 'onChange') {
+        const pointerState = watch.pointerState || createPointerWatchState(watch.jsonPointer, state);
+        watch.pointerState = pointerState;
+        triggered = updatePointerWatchState(pointerState, state);
+      }
+
+      if (!triggered) continue;
+      triggeredCount += 1;
+      if (!Array.isArray(watch.actions) || !watch.actions.length) {
+        session.events.add({
+          source: 'system',
+          type: 'watch-trigger',
+          summary: `watch:${watch.id} triggered`,
+          tickIndex
+        });
+        continue;
+      }
+
+      for (const action of watch.actions) {
+        if (action.type === 'emitSummary') {
+          const data = {};
+          if (action.include?.lemmingsSummary) {
+            data.lemmingsSummary = buildLemmingSummary(state, {});
+          }
+          if (Array.isArray(action.include?.statePointers)) {
+            data.statePointers = {};
+            for (const pointer of action.include.statePointers) {
+              data.statePointers[pointer] = readPointerValue(state, pointer);
+            }
+          }
+          session.events.add({
+            source: 'system',
+            type: 'watch-trigger',
+            summary: `watch:${watch.id} summary`,
+            tickIndex,
+            data
+          });
+        } else if (action.type === 'capture') {
+          const throttle = action.throttleTicks ?? 0;
+          if (Number.isFinite(tickIndex) && throttle > 0 && tickIndex - watch.lastCaptureTick < throttle) {
+            continue;
+          }
+          const captureOptions = action.capture || { target: 'page', delivery: 'resource' };
+          const result = await captureFrame(session, captureOptions);
+          if (result.ok && result.frame) {
+            watch.lastCaptureTick = Number.isFinite(tickIndex) ? tickIndex : watch.lastCaptureTick;
+            const event = {
+              source: 'system',
+              type: 'capture',
+              summary: `watch:${watch.id} capture`,
+              tickIndex
+            };
+            if (result.frame.resourceUri) {
+              event.resourceUris = [result.frame.resourceUri];
+            } else {
+              event.data = { frame: result.frame };
+            }
+            session.events.add({
+              ...event
+            });
+          } else {
+            session.events.add({
+              source: 'system',
+              type: 'error',
+              summary: `watch:${watch.id} capture failed`,
+              tickIndex,
+              data: { reason: result?.reason || 'capture_failed' }
+            });
+          }
+        }
+      }
+    }
+    return { triggeredCount };
+  };
+
+
+  const watchCreateTool = async (args) => {
+    const { sessionId, watch, actions, enabled } = WatchCreateSchema.parse(args || {});
+    const session = getSession(sessionId);
+    const watchId = makeId();
+    const state = watch.type === 'onChange' ? await getState(session) : null;
+    const tickIndex = state?.game?.timer?.tickIndex ?? 0;
+    const pointerState = watch.type === 'onChange'
+      ? createPointerWatchState(watch.jsonPointer, state)
+      : null;
+
+    const entry = {
+      id: watchId,
+      type: watch.type,
+      everyTicks: watch.everyTicks || 1,
+      jsonPointer: watch.jsonPointer || '',
+      enabled: enabled !== false,
+      actions: actions || [],
+      lastTick: Number.isFinite(tickIndex) ? tickIndex : 0,
+      pointerState,
+      lastCaptureTick: -Infinity
+    };
+
+    session.watches.set(watchId, entry);
+    startWatchLoop(session);
+    requestWatchPoll(session, { immediate: true });
+
+    return attachEvents(session, {
+      watchId,
+      ok: true
+    });
+  };
+
+  const watchCancelTool = async (args) => {
+    const { sessionId, watchId } = WatchCancelSchema.parse(args || {});
+    const session = getSession(sessionId);
+    const ok = session.watches.delete(watchId);
+    if (!session.watches.size) {
+      stopWatchLoop(session);
+    }
+    return attachEvents(session, { ok });
+  };
+
+  const eventsPollTool = async (args) => {
+    const { sessionId, after } = EventsPollSchema.parse(args || {});
+    const session = getSession(sessionId);
+    if (session.watches.size) {
+      await session.watchController?.tickNow();
+    }
+    const normalizedAfter = session.events.normalizeCursor(after);
+    const envelope = session.events.drain(normalizedAfter, { updateCursor: true });
+    const cursor = String(envelope ? envelope.cursor : normalizedAfter);
+    if (!envelope && session.watches.size) {
+      requestWatchPoll(session, { immediate: true });
+    }
+    return envelope || { cursor, events: [] };
+  };
+
+
+  return {
+    startWatchLoop,
+    stopWatchLoop,
+    requestWatchPoll,
+    nudgeWatchPolling,
+    pollWatches,
+    watchCreateTool,
+    watchCancelTool,
+    eventsPollTool
+  };
+};
+
+export { createWatchToolHandlers };
diff --git a/mcpb/README.md b/mcpb/README.md
index 8070abb7..45fc8078 100644
--- a/mcpb/README.md
+++ b/mcpb/README.md
@@ -11,15 +11,32 @@ From the repo root:
 node scripts/build-mcpb-bundle.js
 ```
 
+To build a surface-only bundle:
+
+```
+node scripts/build-mcpb-bundle.js --surface game
+node scripts/build-mcpb-bundle.js --surface editor
+node scripts/build-mcpb-bundle.js --surface interact
+```
+
 This creates `dist/mcpb/` with:
 
 - `manifest.json`
 - `server.json`
 - `.mcpbignore`
 - `package.json`
-- `mcp/server.js`, `mcp/spectator.html`
+- the full `mcp/` server tree
 - `keybindings.json`
 
+Surface builds create `dist/mcpb-game/`, `dist/mcpb-editor/`, or
+`dist/mcpb-interact/` and use surface-specific templates when available:
+
+- `mcpb/manifest.<surface>.json`
+- `mcpb/package.<surface>.json`
+- `mcpb/server.<surface>.json`
+
+Missing surface templates fall back to the generic template for that file.
+
 ## Install dependencies (no bundled browsers)
 
 ```
@@ -35,4 +52,5 @@ npx @anthropic-ai/mcpb validate
 npx @anthropic-ai/mcpb pack dist/lemmings-mcp.mcpb
 ```
 
-Update `server.json` with the release URL and SHA-256 before publishing.
+Update `server.json` or `server.<surface>.json` with the release URL and
+SHA-256 before publishing.
diff --git a/mcpb/manifest.editor.json b/mcpb/manifest.editor.json
new file mode 100644
index 00000000..d8efc6fa
--- /dev/null
+++ b/mcpb/manifest.editor.json
@@ -0,0 +1,38 @@
+{
+  "manifest_version": "0.3",
+  "name": "lemmings-mcp-editor",
+  "version": "0.0.4",
+  "description": "Lemmings MCP editor mutation tool surface",
+  "author": {
+    "name": "doublemover"
+  },
+  "server": {
+    "type": "node",
+    "entry_point": "mcp/server.js",
+    "mcp_config": {
+      "command": "node",
+      "args": ["${__dirname}/mcp/server.js"],
+      "env": {
+        "LEMMINGS_MCP_BASE_URL": "${user_config.base_url}",
+        "LEMMINGS_MCP_PATH": "${user_config.path}",
+        "LEMMINGS_MCP_SURFACES": "editor"
+      }
+    }
+  },
+  "user_config": {
+    "base_url": {
+      "type": "string",
+      "title": "Base URL",
+      "description": "Base URL for the running game server",
+      "required": false,
+      "default": "https://localhost:8080"
+    },
+    "path": {
+      "type": "string",
+      "title": "Path",
+      "description": "Path to load for MCP sessions",
+      "required": false,
+      "default": "/?e2e=1"
+    }
+  }
+}
diff --git a/mcpb/manifest.game.json b/mcpb/manifest.game.json
new file mode 100644
index 00000000..1b467190
--- /dev/null
+++ b/mcpb/manifest.game.json
@@ -0,0 +1,38 @@
+{
+  "manifest_version": "0.3",
+  "name": "lemmings-mcp-game",
+  "version": "0.0.4",
+  "description": "Lemmings MCP game/session/state tool surface",
+  "author": {
+    "name": "doublemover"
+  },
+  "server": {
+    "type": "node",
+    "entry_point": "mcp/server.js",
+    "mcp_config": {
+      "command": "node",
+      "args": ["${__dirname}/mcp/server.js"],
+      "env": {
+        "LEMMINGS_MCP_BASE_URL": "${user_config.base_url}",
+        "LEMMINGS_MCP_PATH": "${user_config.path}",
+        "LEMMINGS_MCP_SURFACES": "game"
+      }
+    }
+  },
+  "user_config": {
+    "base_url": {
+      "type": "string",
+      "title": "Base URL",
+      "description": "Base URL for the running game server",
+      "required": false,
+      "default": "https://localhost:8080"
+    },
+    "path": {
+      "type": "string",
+      "title": "Path",
+      "description": "Path to load for MCP sessions",
+      "required": false,
+      "default": "/?e2e=1"
+    }
+  }
+}
diff --git a/mcpb/manifest.interact.json b/mcpb/manifest.interact.json
new file mode 100644
index 00000000..a3ac68a3
--- /dev/null
+++ b/mcpb/manifest.interact.json
@@ -0,0 +1,38 @@
+{
+  "manifest_version": "0.3",
+  "name": "lemmings-mcp-interact",
+  "version": "0.0.4",
+  "description": "Lemmings MCP input/vision/watch tool surface",
+  "author": {
+    "name": "doublemover"
+  },
+  "server": {
+    "type": "node",
+    "entry_point": "mcp/server.js",
+    "mcp_config": {
+      "command": "node",
+      "args": ["${__dirname}/mcp/server.js"],
+      "env": {
+        "LEMMINGS_MCP_BASE_URL": "${user_config.base_url}",
+        "LEMMINGS_MCP_PATH": "${user_config.path}",
+        "LEMMINGS_MCP_SURFACES": "interact"
+      }
+    }
+  },
+  "user_config": {
+    "base_url": {
+      "type": "string",
+      "title": "Base URL",
+      "description": "Base URL for the running game server",
+      "required": false,
+      "default": "https://localhost:8080"
+    },
+    "path": {
+      "type": "string",
+      "title": "Path",
+      "description": "Path to load for MCP sessions",
+      "required": false,
+      "default": "/?e2e=1"
+    }
+  }
+}
diff --git a/mcpb/manifest.json b/mcpb/manifest.json
index 83da2aa2..097313e1 100644
--- a/mcpb/manifest.json
+++ b/mcpb/manifest.json
@@ -14,7 +14,8 @@
       "args": ["${__dirname}/mcp/server.js"],
       "env": {
         "LEMMINGS_MCP_BASE_URL": "${user_config.base_url}",
-        "LEMMINGS_MCP_PATH": "${user_config.path}"
+        "LEMMINGS_MCP_PATH": "${user_config.path}",
+        "LEMMINGS_MCP_SURFACES": "${user_config.surfaces}"
       }
     }
   },
@@ -32,6 +33,13 @@
       "description": "Path to load for MCP sessions",
       "required": false,
       "default": "/?e2e=1"
+    },
+    "surfaces": {
+      "type": "string",
+      "title": "Tool Surfaces",
+      "description": "Comma-separated tool surfaces to enable (game,editor,interact)",
+      "required": false,
+      "default": "game,editor,interact"
     }
   }
 }
diff --git a/mcpb/package.editor.json b/mcpb/package.editor.json
new file mode 100644
index 00000000..f6d1f0ec
--- /dev/null
+++ b/mcpb/package.editor.json
@@ -0,0 +1,12 @@
+{
+  "name": "lemmings-mcp-editor",
+  "version": "0.0.4",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@playwright/test": "^1.49.1",
+    "ws": "^8.18.1",
+    "zod": "^3.25.76"
+  }
+}
diff --git a/mcpb/package.game.json b/mcpb/package.game.json
new file mode 100644
index 00000000..0bef140d
--- /dev/null
+++ b/mcpb/package.game.json
@@ -0,0 +1,12 @@
+{
+  "name": "lemmings-mcp-game",
+  "version": "0.0.4",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@playwright/test": "^1.49.1",
+    "ws": "^8.18.1",
+    "zod": "^3.25.76"
+  }
+}
diff --git a/mcpb/package.interact.json b/mcpb/package.interact.json
new file mode 100644
index 00000000..0c03eea6
--- /dev/null
+++ b/mcpb/package.interact.json
@@ -0,0 +1,12 @@
+{
+  "name": "lemmings-mcp-interact",
+  "version": "0.0.4",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@playwright/test": "^1.49.1",
+    "ws": "^8.18.1",
+    "zod": "^3.25.76"
+  }
+}
diff --git a/mcpb/server.editor.json b/mcpb/server.editor.json
new file mode 100644
index 00000000..a46ec73e
--- /dev/null
+++ b/mcpb/server.editor.json
@@ -0,0 +1,25 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.doublemover/lemmings-mcp-editor",
+  "title": "Lemmings MCP Editor",
+  "description": "Editor mutation MCP surface for LemmingsJS-MIDI automation",
+  "version": "0.0.4",
+  "repository": {
+    "url": "https://github.com/doublemover/LemmingsJS-MIDI",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registryType": "mcpb",
+      "identifier": "https://github.com/doublemover/LemmingsJS-MIDI/releases/download/v0.0.4/lemmings-mcp-editor.mcpb",
+      "fileSha256": "PUT_SHA256_OF_MCPB_HERE",
+      "transport": { "type": "stdio" }
+    }
+  ],
+  "_meta": {
+    "io.modelcontextprotocol.registry/publisher-provided": {
+      "tool": "manual",
+      "notes": "Surface bundle: editor. Update identifier/fileSha256 before publishing."
+    }
+  }
+}
diff --git a/mcpb/server.game.json b/mcpb/server.game.json
new file mode 100644
index 00000000..ff9c4c4a
--- /dev/null
+++ b/mcpb/server.game.json
@@ -0,0 +1,25 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.doublemover/lemmings-mcp-game",
+  "title": "Lemmings MCP Game",
+  "description": "Game/session/state MCP surface for LemmingsJS-MIDI automation",
+  "version": "0.0.4",
+  "repository": {
+    "url": "https://github.com/doublemover/LemmingsJS-MIDI",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registryType": "mcpb",
+      "identifier": "https://github.com/doublemover/LemmingsJS-MIDI/releases/download/v0.0.4/lemmings-mcp-game.mcpb",
+      "fileSha256": "PUT_SHA256_OF_MCPB_HERE",
+      "transport": { "type": "stdio" }
+    }
+  ],
+  "_meta": {
+    "io.modelcontextprotocol.registry/publisher-provided": {
+      "tool": "manual",
+      "notes": "Surface bundle: game. Update identifier/fileSha256 before publishing."
+    }
+  }
+}
diff --git a/mcpb/server.interact.json b/mcpb/server.interact.json
new file mode 100644
index 00000000..c44fbdd7
--- /dev/null
+++ b/mcpb/server.interact.json
@@ -0,0 +1,25 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.doublemover/lemmings-mcp-interact",
+  "title": "Lemmings MCP Interact",
+  "description": "Input, vision, watch, and event MCP surface for LemmingsJS-MIDI automation",
+  "version": "0.0.4",
+  "repository": {
+    "url": "https://github.com/doublemover/LemmingsJS-MIDI",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registryType": "mcpb",
+      "identifier": "https://github.com/doublemover/LemmingsJS-MIDI/releases/download/v0.0.4/lemmings-mcp-interact.mcpb",
+      "fileSha256": "PUT_SHA256_OF_MCPB_HERE",
+      "transport": { "type": "stdio" }
+    }
+  ],
+  "_meta": {
+    "io.modelcontextprotocol.registry/publisher-provided": {
+      "tool": "manual",
+      "notes": "Surface bundle: interact. Update identifier/fileSha256 before publishing."
+    }
+  }
+}
diff --git a/package-lock.json b/package-lock.json
index c24018a1..5bb2fcfd 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -14,7 +14,6 @@
         "@modelcontextprotocol/sdk": "^1.0.0",
         "@playwright/test": "^1.49.1",
         "@sinonjs/fake-timers": "^14.0.0",
-        "acorn": "^8.14.1",
         "adm-zip": "^0.5.16",
         "c8": "^10.1.3",
         "chai": "^5.2.0",
@@ -27,6 +26,7 @@
         "node-unrar-js": "^2.0.2",
         "pngjs": "^7.0.0",
         "tar": "^7.4.3",
+        "typescript": "^5.9.3",
         "ws": "^8.18.1",
         "zod": "^3.25.76"
       },
@@ -218,9 +218,9 @@
       }
     },
     "node_modules/@eslint/config-array/node_modules/brace-expansion": {
-      "version": "1.1.12",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz",
-      "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==",
+      "version": "1.1.14",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.14.tgz",
+      "integrity": "sha512-MWPGfDxnyzKU7rNOW9SP/c50vi3xrmrua/+6hfPbCS2ABNWfx24vPidzvC7krjU/RTo235sV776ymlsMtGKj8g==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -229,9 +229,9 @@
       }
     },
     "node_modules/@eslint/config-array/node_modules/minimatch": {
-      "version": "3.1.2",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz",
-      "integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==",
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz",
+      "integrity": "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==",
       "dev": true,
       "license": "ISC",
       "dependencies": {
@@ -289,9 +289,9 @@
       }
     },
     "node_modules/@eslint/eslintrc/node_modules/brace-expansion": {
-      "version": "1.1.12",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz",
-      "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==",
+      "version": "1.1.14",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.14.tgz",
+      "integrity": "sha512-MWPGfDxnyzKU7rNOW9SP/c50vi3xrmrua/+6hfPbCS2ABNWfx24vPidzvC7krjU/RTo235sV776ymlsMtGKj8g==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -313,9 +313,9 @@
       }
     },
     "node_modules/@eslint/eslintrc/node_modules/minimatch": {
-      "version": "3.1.2",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz",
-      "integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==",
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz",
+      "integrity": "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==",
       "dev": true,
       "license": "ISC",
       "dependencies": {
@@ -376,9 +376,9 @@
       }
     },
     "node_modules/@hono/node-server": {
-      "version": "1.19.7",
-      "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-1.19.7.tgz",
-      "integrity": "sha512-vUcD0uauS7EU2caukW8z5lJKtoGMokxNbJtBiwHgpqxEXokaHCBkQUmCHhjFB1VUTWdqj25QoMkMKzgjq+uhrw==",
+      "version": "1.19.14",
+      "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-1.19.14.tgz",
+      "integrity": "sha512-GwtvgtXxnWsucXvbQXkRgqksiH2Qed37H9xHZocE5sA3N8O8O8/8FA3uclQXxXVzc9XBZuEOMK7+r02FmSpHtw==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -549,13 +549,13 @@
       }
     },
     "node_modules/@modelcontextprotocol/sdk": {
-      "version": "1.25.1",
-      "resolved": "https://registry.npmjs.org/@modelcontextprotocol/sdk/-/sdk-1.25.1.tgz",
-      "integrity": "sha512-yO28oVFFC7EBoiKdAn+VqRm+plcfv4v0xp6osG/VsCB0NlPZWi87ajbCZZ8f/RvOFLEu7//rSRmuZZ7lMoe3gQ==",
+      "version": "1.29.0",
+      "resolved": "https://registry.npmjs.org/@modelcontextprotocol/sdk/-/sdk-1.29.0.tgz",
+      "integrity": "sha512-zo37mZA9hJWpULgkRpowewez1y6ML5GsXJPY8FI0tBBCd77HEvza4jDqRKOXgHNn867PVGCyTdzqpz0izu5ZjQ==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@hono/node-server": "^1.19.7",
+        "@hono/node-server": "^1.19.9",
         "ajv": "^8.17.1",
         "ajv-formats": "^3.0.1",
         "content-type": "^1.0.5",
@@ -563,14 +563,15 @@
         "cross-spawn": "^7.0.5",
         "eventsource": "^3.0.2",
         "eventsource-parser": "^3.0.0",
-        "express": "^5.0.1",
-        "express-rate-limit": "^7.5.0",
-        "jose": "^6.1.1",
+        "express": "^5.2.1",
+        "express-rate-limit": "^8.2.1",
+        "hono": "^4.11.4",
+        "jose": "^6.1.3",
         "json-schema-typed": "^8.0.2",
         "pkce-challenge": "^5.0.0",
         "raw-body": "^3.0.0",
         "zod": "^3.25 || ^4.0",
-        "zod-to-json-schema": "^3.25.0"
+        "zod-to-json-schema": "^3.25.1"
       },
       "engines": {
         "node": ">=18"
@@ -589,9 +590,9 @@
       }
     },
     "node_modules/@modelcontextprotocol/sdk/node_modules/ajv": {
-      "version": "8.17.1",
-      "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.17.1.tgz",
-      "integrity": "sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g==",
+      "version": "8.20.0",
+      "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.20.0.tgz",
+      "integrity": "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -803,9 +804,9 @@
       }
     },
     "node_modules/ajv": {
-      "version": "6.12.6",
-      "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.12.6.tgz",
-      "integrity": "sha512-j3fVLgvTo527anyYyJOGTYJbG+vnnQYvE0m5mmkc1TK+nxAppkCLMIL0aZ4dblVCNoGShhm+kzE4ZUykBoMg4g==",
+      "version": "6.15.0",
+      "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.15.0.tgz",
+      "integrity": "sha512-fgFx7Hfoq60ytK2c7DhnF8jIvzYgOMxfugjLOSMHjLIPgenqa7S7oaagATUq99mV6IYvN2tRmC0wnTYX6iPbMw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -838,9 +839,9 @@
       }
     },
     "node_modules/ajv-formats/node_modules/ajv": {
-      "version": "8.17.1",
-      "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.17.1.tgz",
-      "integrity": "sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g==",
+      "version": "8.20.0",
+      "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.20.0.tgz",
+      "integrity": "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -964,9 +965,9 @@
       }
     },
     "node_modules/body-parser": {
-      "version": "2.2.1",
-      "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.2.1.tgz",
-      "integrity": "sha512-nfDwkulwiZYQIGwxdy0RUmowMhKcFVcYXUU7m4QlKYim1rUtg83xm2yjZ40QjDuc291AJjjeSc9b++AWHSgSHw==",
+      "version": "2.2.2",
+      "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.2.2.tgz",
+      "integrity": "sha512-oP5VkATKlNwcgvxi0vM0p/D3n2C3EReYVX+DNYs5TjZFn/oQt2j+4sVJtSMr18pdRr8wjTcBl6LoV+FUwzPmNA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -976,7 +977,7 @@
         "http-errors": "^2.0.0",
         "iconv-lite": "^0.7.0",
         "on-finished": "^2.4.1",
-        "qs": "^6.14.0",
+        "qs": "^6.14.1",
         "raw-body": "^3.0.1",
         "type-is": "^2.0.1"
       },
@@ -989,9 +990,9 @@
       }
     },
     "node_modules/body-parser/node_modules/iconv-lite": {
-      "version": "0.7.1",
-      "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.7.1.tgz",
-      "integrity": "sha512-2Tth85cXwGFHfvRgZWszZSvdo+0Xsqmw8k8ZwxScfcBneNUraK+dxRxRm24nszx80Y0TVio8kKLt5sLE7ZCLlw==",
+      "version": "0.7.2",
+      "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.7.2.tgz",
+      "integrity": "sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -1013,9 +1014,9 @@
       "license": "ISC"
     },
     "node_modules/brace-expansion": {
-      "version": "2.0.2",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.2.tgz",
-      "integrity": "sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ==",
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.1.0.tgz",
+      "integrity": "sha512-TN1kCZAgdgweJhWWpgKYrQaMNHcDULHkWwQIspdtjV4Y5aurRdZpjAqn6yX3FPqTA9ngHCc4hJxMAMgGfve85w==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -1383,9 +1384,9 @@
       "license": "MIT"
     },
     "node_modules/content-disposition": {
-      "version": "1.0.1",
-      "resolved": "https://registry.npmjs.org/content-disposition/-/content-disposition-1.0.1.tgz",
-      "integrity": "sha512-oIXISMynqSqm241k6kcQ5UwttDILMK4BiurCfGEREw6+X9jkkpEe5T9FZaApyLGGOnFuyMWZpdolTXMtvEJ08Q==",
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/content-disposition/-/content-disposition-1.1.0.tgz",
+      "integrity": "sha512-5jRCH9Z/+DRP7rkvY83B+yGIGX96OYdJmzngqnw2SBSxqCFPd0w2km3s5iawpGX8krnwSGmF0FW5Nhr0Hfai3g==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -1474,16 +1475,6 @@
         "node": ">=10"
       }
     },
-    "node_modules/cosmiconfig/node_modules/yaml": {
-      "version": "1.10.2",
-      "resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.2.tgz",
-      "integrity": "sha512-r3vXyErRCYJ7wg28yvBY5VSoAF8ZvlcW9/BwUzEtUsjvX/DKs24dIkuwjtuprwJJHsbyUbLApepYTR1BN4uHrg==",
-      "dev": true,
-      "license": "ISC",
-      "engines": {
-        "node": ">= 6"
-      }
-    },
     "node_modules/cross-env": {
       "version": "7.0.3",
       "resolved": "https://registry.npmjs.org/cross-env/-/cross-env-7.0.3.tgz",
@@ -1790,9 +1781,9 @@
       }
     },
     "node_modules/diff": {
-      "version": "7.0.0",
-      "resolved": "https://registry.npmjs.org/diff/-/diff-7.0.0.tgz",
-      "integrity": "sha512-PJWHUb1RFevKCwaFA9RlG5tCd+FO5iRh9A8HEtkmBH2Li03iJriB6m6JIN4rGz3K3JLawI7/veA1xzRKP6ISBw==",
+      "version": "8.0.3",
+      "resolved": "https://registry.npmjs.org/diff/-/diff-8.0.3.tgz",
+      "integrity": "sha512-qejHi7bcSD4hQAZE0tNAawRK1ZtafHDmMTMkrrIGgSLl7hTnQHmKCeB45xAcbfTqK2zowkM3j3bHt/4b/ARbYQ==",
       "dev": true,
       "license": "BSD-3-Clause",
       "engines": {
@@ -2096,9 +2087,9 @@
       }
     },
     "node_modules/eslint/node_modules/brace-expansion": {
-      "version": "1.1.12",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz",
-      "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==",
+      "version": "1.1.14",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.14.tgz",
+      "integrity": "sha512-MWPGfDxnyzKU7rNOW9SP/c50vi3xrmrua/+6hfPbCS2ABNWfx24vPidzvC7krjU/RTo235sV776ymlsMtGKj8g==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -2107,9 +2098,9 @@
       }
     },
     "node_modules/eslint/node_modules/minimatch": {
-      "version": "3.1.2",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz",
-      "integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==",
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz",
+      "integrity": "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==",
       "dev": true,
       "license": "ISC",
       "dependencies": {
@@ -2302,11 +2293,14 @@
       }
     },
     "node_modules/express-rate-limit": {
-      "version": "7.5.1",
-      "resolved": "https://registry.npmjs.org/express-rate-limit/-/express-rate-limit-7.5.1.tgz",
-      "integrity": "sha512-7iN8iPMDzOMHPUYllBEsQdWVB6fPDMPqwjBaFrgr4Jgr/+okjvzAy+UHlYYL/Vs0OsOrMkwS6PJDkFlJwoxUnw==",
+      "version": "8.5.0",
+      "resolved": "https://registry.npmjs.org/express-rate-limit/-/express-rate-limit-8.5.0.tgz",
+      "integrity": "sha512-XKhFohWaSBdVJNTi5TaHziqnPkv04I9UQV6q1Wy7Ui6GGQZVW12ojDFwqer14EvCXxjvPG0CyWXx7cAXpALB4Q==",
       "dev": true,
       "license": "MIT",
+      "dependencies": {
+        "ip-address": "10.1.0"
+      },
       "engines": {
         "node": ">= 16"
       },
@@ -2461,16 +2455,16 @@
       }
     },
     "node_modules/flatted": {
-      "version": "3.3.3",
-      "resolved": "https://registry.npmjs.org/flatted/-/flatted-3.3.3.tgz",
-      "integrity": "sha512-GX+ysw4PBCz0PzosHDepZGANEuFCMLrnRTiEy9McGjmkCQYwRq4A/X786G/fjM/+OjsWSU1ZrY5qyARZmO/uwg==",
+      "version": "3.4.2",
+      "resolved": "https://registry.npmjs.org/flatted/-/flatted-3.4.2.tgz",
+      "integrity": "sha512-PjDse7RzhcPkIJwy5t7KPWQSZ9cAbzQXcafsetQoD7sOJRQlGikNbx7yZp2OotDnJyrDcbyRq3Ttb18iYOqkxA==",
       "dev": true,
       "license": "ISC"
     },
     "node_modules/follow-redirects": {
-      "version": "1.15.9",
-      "resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.15.9.tgz",
-      "integrity": "sha512-gew4GsXizNgdoRyqmyfMHyAmXsZDk6mHkSxZFCzW9gwlbtOW44CDtYavM+y+72qD/Vq2l550kMF52DT8fOLJqQ==",
+      "version": "1.16.0",
+      "resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.16.0.tgz",
+      "integrity": "sha512-y5rN/uOsadFT/JfYwhxRS5R7Qce+g3zG97+JrtFZlC9klX/W5hD7iiLzScI4nZqUS7DNUdhPgw4xI8W2LuXlUw==",
       "dev": true,
       "funding": [
         {
@@ -2634,13 +2628,13 @@
       }
     },
     "node_modules/glob/node_modules/minimatch": {
-      "version": "9.0.5",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.5.tgz",
-      "integrity": "sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow==",
+      "version": "9.0.9",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.9.tgz",
+      "integrity": "sha512-OBwBN9AL4dqmETlpS2zasx+vTeWclWzkblfZk7KTA5j3jeOONz/tRCnZomUyvNg83wL5Zv9Ss6HMJXAgL8R2Yg==",
       "dev": true,
       "license": "ISC",
       "dependencies": {
-        "brace-expansion": "^2.0.1"
+        "brace-expansion": "^2.0.2"
       },
       "engines": {
         "node": ">=16 || 14 >=14.17"
@@ -2777,12 +2771,11 @@
       }
     },
     "node_modules/hono": {
-      "version": "4.11.3",
-      "resolved": "https://registry.npmjs.org/hono/-/hono-4.11.3.tgz",
-      "integrity": "sha512-PmQi306+M/ct/m5s66Hrg+adPnkD5jiO6IjA7WhWw0gSBSo1EcRegwuI1deZ+wd5pzCGynCcn2DprnE4/yEV4w==",
+      "version": "4.12.17",
+      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.17.tgz",
+      "integrity": "sha512-FbJJNb/XgX7YW0hX/V8w5oYLztKEsRLykCMZWt1WdLtsfjzMvmoqWBA4H4t5norinq8/rh20oiZYr+WSl4UzAQ==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=16.9.0"
       }
@@ -2978,6 +2971,16 @@
       "dev": true,
       "license": "ISC"
     },
+    "node_modules/ip-address": {
+      "version": "10.2.0",
+      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.2.0.tgz",
+      "integrity": "sha512-/+S6j4E9AHvW9SWMSEY9Xfy66O5PWvVEJ08O0y5JGyEKQpojb0K0GKpz/v5HJ/G0vi3D2sjGK78119oXZeE0qA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 12"
+      }
+    },
     "node_modules/ipaddr.js": {
       "version": "1.9.1",
       "resolved": "https://registry.npmjs.org/ipaddr.js/-/ipaddr.js-1.9.1.tgz",
@@ -3054,6 +3057,16 @@
         "node": ">=0.12.0"
       }
     },
+    "node_modules/is-path-inside": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/is-path-inside/-/is-path-inside-3.0.3.tgz",
+      "integrity": "sha512-Fd4gABb+ycGAmKou8eMftCupSir5lRxqf4aD/vd0cD2qc4HL07OjCeuHMr8Ro4CoMaeCKDB0/ECBOVWjTwUvPQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/is-plain-obj": {
       "version": "2.1.0",
       "resolved": "https://registry.npmjs.org/is-plain-obj/-/is-plain-obj-2.1.0.tgz",
@@ -3294,9 +3307,9 @@
       }
     },
     "node_modules/lodash": {
-      "version": "4.17.21",
-      "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz",
-      "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==",
+      "version": "4.18.1",
+      "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.18.1.tgz",
+      "integrity": "sha512-dMInicTPVE8d1e5otfwmmjlxkZoUpiVLwyeTdUsi/Caj/gfzzblBcCE5sRHV/AsjuCmxWrte2TNGSYuCeCq+0Q==",
       "dev": true,
       "license": "MIT"
     },
@@ -3452,13 +3465,13 @@
       }
     },
     "node_modules/minimatch": {
-      "version": "7.4.6",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-7.4.6.tgz",
-      "integrity": "sha512-sBz8G/YjVniEz6lKPNpKxXwazJe4c19fEfV2GDMX6AjFz+MX9uDWIZW8XreVhkFW3fkIdTv/gxWr/Kks5FFAVw==",
+      "version": "7.4.9",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-7.4.9.tgz",
+      "integrity": "sha512-Brg/fp/iAVDOQoHxkuN5bEYhyQlZhxddI78yWsCbeEwTHXQjlNLtiJDUsp1GIptVqMI7/gkJMz4vVAc01mpoBw==",
       "dev": true,
       "license": "ISC",
       "dependencies": {
-        "brace-expansion": "^2.0.1"
+        "brace-expansion": "^2.0.2"
       },
       "engines": {
         "node": ">=10"
@@ -3488,9 +3501,9 @@
       }
     },
     "node_modules/minizlib": {
-      "version": "3.0.2",
-      "resolved": "https://registry.npmjs.org/minizlib/-/minizlib-3.0.2.tgz",
-      "integrity": "sha512-oG62iEk+CYt5Xj2YqI5Xi9xWUeZhDI8jjQmC5oThVH5JGCTgIjr7ciJDzC7MBzYd//WvR1OTmP5Q38Q8ShQtVA==",
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/minizlib/-/minizlib-3.1.0.tgz",
+      "integrity": "sha512-KZxYo1BUkWD2TVFLr0MQoM8vUUigWD3LlD83a/75BqC+4qE0Hb1Vo5v1FgcfaNXvfXzr+5EhQ6ing/CaBijTlw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -3500,26 +3513,10 @@
         "node": ">= 18"
       }
     },
-    "node_modules/mkdirp": {
-      "version": "3.0.1",
-      "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-3.0.1.tgz",
-      "integrity": "sha512-+NsyUUAZDmo6YVHzL/stxSu3t9YS1iljliy3BSDrXJ/dkn1KYdmtZODGGjLcc9XLgVVpH4KshHB8XmZgMhaBXg==",
-      "dev": true,
-      "license": "MIT",
-      "bin": {
-        "mkdirp": "dist/cjs/src/bin.js"
-      },
-      "engines": {
-        "node": ">=10"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/isaacs"
-      }
-    },
     "node_modules/mocha": {
-      "version": "11.5.0",
-      "resolved": "https://registry.npmjs.org/mocha/-/mocha-11.5.0.tgz",
-      "integrity": "sha512-VKDjhy6LMTKm0WgNEdlY77YVsD49LZnPSXJAaPNL9NRYQADxvORsyG1DIQY6v53BKTnlNbEE2MbVCDbnxr4K3w==",
+      "version": "11.7.5",
+      "resolved": "https://registry.npmjs.org/mocha/-/mocha-11.7.5.tgz",
+      "integrity": "sha512-mTT6RgopEYABzXWFx+GcJ+ZQ32kp4fMf0xvpZIIfSq9Z8lC/++MtcCnQ9t5FP2veYEP95FIYSvW+U9fV4xrlig==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -3531,6 +3528,7 @@
         "find-up": "^5.0.0",
         "glob": "^10.4.5",
         "he": "^1.2.0",
+        "is-path-inside": "^3.0.3",
         "js-yaml": "^4.1.0",
         "log-symbols": "^4.1.0",
         "minimatch": "^9.0.5",
@@ -3539,7 +3537,7 @@
         "serialize-javascript": "^6.0.2",
         "strip-json-comments": "^3.1.1",
         "supports-color": "^8.1.1",
-        "workerpool": "^6.5.1",
+        "workerpool": "^9.2.0",
         "yargs": "^17.7.2",
         "yargs-parser": "^21.1.1",
         "yargs-unparser": "^2.0.0"
@@ -3553,13 +3551,13 @@
       }
     },
     "node_modules/mocha/node_modules/minimatch": {
-      "version": "9.0.5",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.5.tgz",
-      "integrity": "sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow==",
+      "version": "9.0.9",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.9.tgz",
+      "integrity": "sha512-OBwBN9AL4dqmETlpS2zasx+vTeWclWzkblfZk7KTA5j3jeOONz/tRCnZomUyvNg83wL5Zv9Ss6HMJXAgL8R2Yg==",
       "dev": true,
       "license": "ISC",
       "dependencies": {
-        "brace-expansion": "^2.0.1"
+        "brace-expansion": "^2.0.2"
       },
       "engines": {
         "node": ">=16 || 14 >=14.17"
@@ -3612,9 +3610,9 @@
       }
     },
     "node_modules/multimatch/node_modules/brace-expansion": {
-      "version": "1.1.12",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz",
-      "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==",
+      "version": "1.1.14",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.14.tgz",
+      "integrity": "sha512-MWPGfDxnyzKU7rNOW9SP/c50vi3xrmrua/+6hfPbCS2ABNWfx24vPidzvC7krjU/RTo235sV776ymlsMtGKj8g==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -3623,9 +3621,9 @@
       }
     },
     "node_modules/multimatch/node_modules/minimatch": {
-      "version": "3.1.2",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz",
-      "integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==",
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz",
+      "integrity": "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==",
       "dev": true,
       "license": "ISC",
       "dependencies": {
@@ -3957,9 +3955,9 @@
       }
     },
     "node_modules/path-to-regexp": {
-      "version": "8.3.0",
-      "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-8.3.0.tgz",
-      "integrity": "sha512-7jdwVIRtsP8MYpdXSwOS0YdD0Du+qOoF/AEPIt88PcCFrZCzx41oxku1jD88hZBwbNUIEfpqvuhjFaMAqMTWnA==",
+      "version": "8.4.2",
+      "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-8.4.2.tgz",
+      "integrity": "sha512-qRcuIdP69NPm4qbACK+aDogI5CBDMi1jKe0ry5rSQJz8JVLsC7jV8XpiJjGRLLol3N+R5ihGYcrPLTno6pAdBA==",
       "dev": true,
       "license": "MIT",
       "funding": {
@@ -3995,9 +3993,9 @@
       "license": "ISC"
     },
     "node_modules/picomatch": {
-      "version": "2.3.1",
-      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz",
-      "integrity": "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==",
+      "version": "2.3.2",
+      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.2.tgz",
+      "integrity": "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -4084,9 +4082,9 @@
       }
     },
     "node_modules/postcss": {
-      "version": "8.5.4",
-      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.4.tgz",
-      "integrity": "sha512-QSa9EBe+uwlGTFmHsPKokv3B/oEMQZxfqW0QqNCyhpa6mB1afzulwn8hihglqAb2pOw+BJgNlmXQ8la2VeHB7w==",
+      "version": "8.5.14",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.14.tgz",
+      "integrity": "sha512-SoSL4+OSEtR99LHFZQiJLkT59C5B1amGO1NzTwj7TT1qCUgUO6hxOvzkOYxD+vMrXBM3XJIKzokoERdqQq/Zmg==",
       "dev": true,
       "funding": [
         {
@@ -4147,9 +4145,9 @@
       }
     },
     "node_modules/qs": {
-      "version": "6.14.1",
-      "resolved": "https://registry.npmjs.org/qs/-/qs-6.14.1.tgz",
-      "integrity": "sha512-4EK3+xJl8Ts67nLYNwqw/dsFVnCf+qR7RgXSK9jEEm9unao3njwMDdmsdvoKBKHzxd7tCYz5e5M+SnMjdtXGQQ==",
+      "version": "6.15.1",
+      "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.1.tgz",
+      "integrity": "sha512-6YHEFRL9mfgcAvql/XhwTvf5jKcOiiupt2FiJxHkiX1z4j7WL8J/jRHYLluORvc1XxB5rV20KoeK00gVJamspg==",
       "dev": true,
       "license": "BSD-3-Clause",
       "dependencies": {
@@ -4162,16 +4160,6 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
-    "node_modules/randombytes": {
-      "version": "2.1.0",
-      "resolved": "https://registry.npmjs.org/randombytes/-/randombytes-2.1.0.tgz",
-      "integrity": "sha512-vYl3iOX+4CKUWuxGi9Ukhie6fsqXqS9FE2Zaic4tNFD2N2QQaXOMFbuKK4QmDHC0JO6B1Zp41J0LpT0oR68amQ==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "safe-buffer": "^5.1.0"
-      }
-    },
     "node_modules/range-parser": {
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/range-parser/-/range-parser-1.2.1.tgz",
@@ -4199,9 +4187,9 @@
       }
     },
     "node_modules/raw-body/node_modules/iconv-lite": {
-      "version": "0.7.1",
-      "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.7.1.tgz",
-      "integrity": "sha512-2Tth85cXwGFHfvRgZWszZSvdo+0Xsqmw8k8ZwxScfcBneNUraK+dxRxRm24nszx80Y0TVio8kKLt5sLE7ZCLlw==",
+      "version": "0.7.2",
+      "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.7.2.tgz",
+      "integrity": "sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -4393,13 +4381,13 @@
       }
     },
     "node_modules/serialize-javascript": {
-      "version": "6.0.2",
-      "resolved": "https://registry.npmjs.org/serialize-javascript/-/serialize-javascript-6.0.2.tgz",
-      "integrity": "sha512-Saa1xPByTTq2gdeFZYLLo+RFE35NHZkAbqZeWNd3BpzppeVisAqpDjcp8dyf6uIvEqJRd46jemmyA4iFIeVk8g==",
+      "version": "7.0.5",
+      "resolved": "https://registry.npmjs.org/serialize-javascript/-/serialize-javascript-7.0.5.tgz",
+      "integrity": "sha512-F4LcB0UqUl1zErq+1nYEEzSHJnIwb3AF2XWB94b+afhrekOUijwooAYqFyRbjYkm2PAKBabx6oYv/xDxNi8IBw==",
       "dev": true,
       "license": "BSD-3-Clause",
-      "dependencies": {
-        "randombytes": "^2.1.0"
+      "engines": {
+        "node": ">=20.0.0"
       }
     },
     "node_modules/serve-static": {
@@ -4712,17 +4700,16 @@
       }
     },
     "node_modules/tar": {
-      "version": "7.4.3",
-      "resolved": "https://registry.npmjs.org/tar/-/tar-7.4.3.tgz",
-      "integrity": "sha512-5S7Va8hKfV7W5U6g3aYxXmlPoZVAwUMy9AOKyF2fVuZa2UD3qZjg578OrLRt8PcNN1PleVaL/5/yYATNL0ICUw==",
+      "version": "7.5.13",
+      "resolved": "https://registry.npmjs.org/tar/-/tar-7.5.13.tgz",
+      "integrity": "sha512-tOG/7GyXpFevhXVh8jOPJrmtRpOTsYqUIkVdVooZYJS/z8WhfQUX8RJILmeuJNinGAMSu1veBr4asSHFt5/hng==",
       "dev": true,
-      "license": "ISC",
+      "license": "BlueOak-1.0.0",
       "dependencies": {
         "@isaacs/fs-minipass": "^4.0.0",
         "chownr": "^3.0.0",
         "minipass": "^7.1.2",
-        "minizlib": "^3.0.1",
-        "mkdirp": "^3.0.1",
+        "minizlib": "^3.1.0",
         "yallist": "^5.0.0"
       },
       "engines": {
@@ -4745,13 +4732,13 @@
       }
     },
     "node_modules/test-exclude/node_modules/minimatch": {
-      "version": "9.0.5",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.5.tgz",
-      "integrity": "sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow==",
+      "version": "9.0.9",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.9.tgz",
+      "integrity": "sha512-OBwBN9AL4dqmETlpS2zasx+vTeWclWzkblfZk7KTA5j3jeOONz/tRCnZomUyvNg83wL5Zv9Ss6HMJXAgL8R2Yg==",
       "dev": true,
       "license": "ISC",
       "dependencies": {
-        "brace-expansion": "^2.0.1"
+        "brace-expansion": "^2.0.2"
       },
       "engines": {
         "node": ">=16 || 14 >=14.17"
@@ -4821,10 +4808,24 @@
         "node": ">= 0.6"
       }
     },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
     "node_modules/undici": {
-      "version": "6.21.3",
-      "resolved": "https://registry.npmjs.org/undici/-/undici-6.21.3.tgz",
-      "integrity": "sha512-gBLkYIlEnSp8pFbT64yFgGE6UIB9tAkhukC23PmMDCe5Nd+cRqKxSjw5y54MK2AZMgZfJWMaNE4nYUHgi1XEOw==",
+      "version": "6.25.0",
+      "resolved": "https://registry.npmjs.org/undici/-/undici-6.25.0.tgz",
+      "integrity": "sha512-ZgpWDC5gmNiuY9CnLVXEH8rl50xhRCuLNA97fAUnKi8RRuV4E6KG31pDTsLVUKnohJE0I3XDrTeEydAXRw47xg==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -4945,9 +4946,9 @@
       }
     },
     "node_modules/workerpool": {
-      "version": "6.5.1",
-      "resolved": "https://registry.npmjs.org/workerpool/-/workerpool-6.5.1.tgz",
-      "integrity": "sha512-Fs4dNYcsdpYSAfVxhnl1L5zTksjvOJxtC5hzMNl+1t9B8hTJTdKDyZ5ju7ztgPy+ft9tBFXoOlDNiOT9WUXZlA==",
+      "version": "9.3.4",
+      "resolved": "https://registry.npmjs.org/workerpool/-/workerpool-9.3.4.tgz",
+      "integrity": "sha512-TmPRQYYSAnnDiEB0P/Ytip7bFGvqnSU6I2BcuSw7Hx+JSg/DsUi5ebYfc8GYaSdpuvOcEs6dXxPurOYpe9QFwg==",
       "dev": true,
       "license": "Apache-2.0"
     },
@@ -5095,6 +5096,16 @@
         "node": ">=18"
       }
     },
+    "node_modules/yaml": {
+      "version": "1.10.3",
+      "resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.3.tgz",
+      "integrity": "sha512-vIYeF1u3CjlhAFekPPAk2h/Kv4T3mAkMox5OymRiJQB0spDP10LHvt+K7G9Ny6NuuMAb25/6n1qyUjAcGNf/AA==",
+      "dev": true,
+      "license": "ISC",
+      "engines": {
+        "node": ">= 6"
+      }
+    },
     "node_modules/yargs": {
       "version": "17.7.2",
       "resolved": "https://registry.npmjs.org/yargs/-/yargs-17.7.2.tgz",
diff --git a/package.json b/package.json
index 4757a2ef..8ac850f5 100644
--- a/package.json
+++ b/package.json
@@ -12,23 +12,46 @@
     "start-https": "http-server --cors=* -S -C certs/localhost.pem -K certs/localhost-key.pem",
     "mcp": "node mcp/server.js",
     "mcpb:build": "node scripts/build-mcpb-bundle.js",
+    "mcpb:build:game": "node scripts/build-mcpb-bundle.js --surface game",
+    "mcpb:build:editor": "node scripts/build-mcpb-bundle.js --surface editor",
+    "mcpb:build:interact": "node scripts/build-mcpb-bundle.js --surface interact",
     "mcpb:validate": "npm run mcpb:build && npx @anthropic-ai/mcpb validate dist/mcpb",
     "check-undefined": "node scripts/check-undefined.js",
+    "typecheck:critical": "tsc -p tsconfig.checkjs.json --pretty false",
     "test": "node scripts/runTests.js",
-    "test-core": "mocha \"test/*game*.test.js\"",
-    "test-bench": "mocha \"test/bench*.test.js\"",
-    "test-workflow": "mocha \"test/*workflow*.test.js\"",
-    "test-tools": "mocha \"test/tools/*.test.js\"",
+    "test:budget": "cross-env LEMMINGS_TEST_ENFORCE_BUDGET=true LEMMINGS_TEST_BUDGET_MS=180000 node scripts/runTests.js",
+    "test-core": "node scripts/runTests.js game",
+    "test-bench": "npm run test-bench-unit",
+    "test-bench-unit": "node scripts/runTests.js bench",
+    "test-bench-smoke": "npm run bench-smoke",
+    "test-workflow": "node scripts/runTests.js workflow",
+    "test-tools": "node scripts/runTests.js tools",
     "test-offline-tools": "node scripts/runTests.js offline-tools",
-    "test-editor": "mocha \"test/editor/*.test.js\"",
+    "test-editor": "node scripts/runTests.js editor",
+    "test:changed": "node scripts/runTests.js --changed",
     "test-e2e": "playwright test",
-    "test-e2e:harness": "playwright test e2e/harness.game.spec.js e2e/harness.editor.spec.js",
+    "test-e2e:harness": "playwright test e2e/harness.game.spec.js e2e/harness.editor-mode.spec.js e2e/harness.editor-saved.spec.js e2e/harness.editor.01-editor-harness-exposes-state-and-history.spec.js e2e/harness.editor.02-editor-pack-switch-refreshes-palettes-and-placem.spec.js e2e/harness.editor.03-editor-eraser-removes-terrain-entries.spec.js e2e/harness.editor.04-editor-entrance-and-exit-tools-enforce-classic-l.spec.js e2e/harness.editor.05-editor-roundtrip-workflow.spec.js e2e/harness.editor.06-editor-playtest-runtime-workflow.spec.js",
     "test-e2e:ui": "playwright test --ui",
     "test-e2e:install": "playwright install chromium",
+    "capture:e2e:midi": "node scripts/e2e-capture-rects.js --config=e2e/capture-targets/midi.js",
+    "capture:e2e:editor": "node scripts/e2e-capture-rects.js --config=e2e/capture-targets/editor.js",
+    "capture:e2e:procgen": "node scripts/e2e-capture-rects.js --config=e2e/capture-targets/procgen.js",
+    "capture:e2e:game-hud": "node scripts/e2e-capture-rects.js --config=e2e/capture-targets/game-hud.js",
     "check-mcp-clients": "node scripts/check-mcp-client-compat.js",
     "test-mcp-smoke": "node scripts/mcp-smoke.js",
     "bench-performance": "node scripts/bench-performance.js",
+    "bench-performance-smoke": "node scripts/bench-performance.js --profile=smoke",
     "bench-history": "node scripts/bench-history-stress.js",
+    "bench-history-smoke": "node scripts/bench-history-stress.js --profile=smoke",
+    "bench-hotpaths": "node scripts/bench-hotpaths.js",
+    "bench-smoke": "node scripts/bench-smoke.js",
+    "bench-long-session": "node scripts/bench-long-session.js",
+    "bench-long-session-smoke": "node scripts/bench-long-session.js --profile=smoke",
+    "bench-long-session-soak": "node scripts/bench-long-session.js --profile=soak --soak",
+    "bench-performance-soak": "node scripts/bench-performance.js --soak --profile=soak",
+    "bench-history-soak": "node scripts/bench-history-stress.js --soak --profile=soak",
+    "bench-procgen-soak": "node scripts/bench-procgen-soak.js",
+    "release-readiness": "node scripts/check-release-readiness.js",
     "coverage": "cross-env C8_FORK=1 c8 mocha --recursive",
     "coverage-editor": "cross-env C8_FORK=1 c8 --include=js/editor/** --check-coverage --lines 100 --statements 100 --functions 100 --branches 100 mocha \"test/editor/*.test.js\"",
     "coverage-report": "npx c8 report --reporter=html",
@@ -42,6 +65,7 @@
     "list-sprites": "node tools/listSprites.js",
     "patch-sprites": "node tools/patchSprites.js",
     "pack-levels": "node tools/packLevels.js",
+    "pack-pipeline": "node tools/packPipeline.js",
     "format": "eslint . --fix",
     "lint": "eslint .",
     "depcheck": "depcheck"
@@ -57,7 +81,6 @@
       "test/**",
       "js/xbrz/**",
       "js/vendor/**",
-      "js/vendor/jquery.js",
       "js/vendor/webmidi.js"
     ]
   },
@@ -77,7 +100,6 @@
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@playwright/test": "^1.49.1",
     "@sinonjs/fake-timers": "^14.0.0",
-    "acorn": "^8.14.1",
     "adm-zip": "^0.5.16",
     "c8": "^10.1.3",
     "chai": "^5.2.0",
@@ -90,10 +112,16 @@
     "node-unrar-js": "^2.0.2",
     "pngjs": "^7.0.0",
     "tar": "^7.4.3",
+    "typescript": "^5.9.3",
     "ws": "^8.18.1",
     "zod": "^3.25.76"
   },
   "dependencies": {
     "js-yaml": "^4.1.0"
+  },
+  "overrides": {
+    "diff": "8.0.3",
+    "ip-address": "10.2.0",
+    "serialize-javascript": "7.0.5"
   }
 }
diff --git a/playwright.config.js b/playwright.config.js
index 4b5ea433..887dde72 100644
--- a/playwright.config.js
+++ b/playwright.config.js
@@ -1,5 +1,29 @@
 import { defineConfig } from '@playwright/test';
 
+const DEFAULT_PLAYWRIGHT_BASE_URL = 'https://localhost:8080';
+
+const resolvePlaywrightBaseUrl = (value = process.env.LEMMINGS_E2E_BASE_URL) => {
+  const candidate = String(value || '').trim() || DEFAULT_PLAYWRIGHT_BASE_URL;
+  let url;
+  try {
+    url = new URL(candidate);
+  } catch {
+    throw new Error(`Invalid LEMMINGS_E2E_BASE_URL: ${candidate}`);
+  }
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    throw new Error(`LEMMINGS_E2E_BASE_URL must use http or https: ${candidate}`);
+  }
+  return url.origin;
+};
+
+const resolvePlaywrightWebServerPort = (baseUrl) => {
+  const url = new URL(baseUrl);
+  if (url.port) return Number(url.port);
+  return url.protocol === 'https:' ? 443 : 80;
+};
+
+const baseURL = resolvePlaywrightBaseUrl();
+
 export default defineConfig({
   testDir: './e2e',
   timeout: 30000,
@@ -8,7 +32,7 @@ export default defineConfig({
   },
   reporter: [['list']],
   use: {
-    baseURL: 'https://localhost:8080',
+    baseURL,
     browserName: 'chromium',
     ignoreHTTPSErrors: true,
     permissions: ['midi'],
@@ -21,7 +45,13 @@ export default defineConfig({
   },
   webServer: {
     command: 'npm run start-https',
-    port: 8080,
+    port: resolvePlaywrightWebServerPort(baseURL),
     reuseExistingServer: !process.env.CI
   }
 });
+
+export {
+  DEFAULT_PLAYWRIGHT_BASE_URL,
+  resolvePlaywrightBaseUrl,
+  resolvePlaywrightWebServerPort
+};
diff --git a/procgen.html b/procgen.html
index 814c8ec4..c97ead44 100644
--- a/procgen.html
+++ b/procgen.html
@@ -3,6 +3,8 @@
 <head>
   <title>Lemmings Procgen</title>
   <meta charset="UTF-8" />
+  <meta name="lemmings-analytics" content="runtime" />
+  <meta name="lemmings-analytics-endpoint" content="" />
   <meta name="viewport" content="width=device-width, height=device-height, initial-scale=1.0, maximum-scale=1.0, user-scalable=0.0, viewport-fit=cover"/>
   <link type="text/css" rel="stylesheet" href="css/procgen.css">
   <script type="module" src="js/app/procgenBoot.js"></script>
diff --git a/scripts/bench-history-stress.js b/scripts/bench-history-stress.js
index c67e2949..21bf9112 100644
--- a/scripts/bench-history-stress.js
+++ b/scripts/bench-history-stress.js
@@ -1,5 +1,21 @@
 import { chromium } from '@playwright/test';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
+const DEFAULT_BASE_URL = 'https://localhost:8080/?e2e=1';
+
+const toNumberOrNaN = (value) => {
+  try {
+    return Number(value);
+  } catch {
+    return Number.NaN;
+  }
+};
+
+/**
+ * @param {string[]} argv
+ * @returns {Map<string, string>}
+ */
 const parseArgs = (argv) => {
   const out = new Map();
   for (const arg of argv) {
@@ -10,19 +26,194 @@ const parseArgs = (argv) => {
   return out;
 };
 
-const args = parseArgs(process.argv.slice(2));
-const baseUrl = args.get('url') || process.env.LEMMINGS_BENCH_URL || 'https://localhost:8080/?e2e=1';
-const durationMs = Number(args.get('duration') || process.env.HISTORY_DURATION_MS || 60000);
-const sampleMs = Number(args.get('sample') || process.env.HISTORY_SAMPLE_MS || 1000);
-const targetSpan = Number(args.get('target') || process.env.HISTORY_TARGET_TICKS || 60000);
-const speeds = (args.get('speeds') || process.env.HISTORY_SPEEDS || '30,60,120')
+/**
+ * @param {unknown} value
+ * @param {number} fallback
+ * @returns {number}
+ */
+const toPositiveNumber = (value, fallback) => {
+  const parsed = toNumberOrNaN(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+};
+
+/**
+ * @param {unknown} value
+ * @param {boolean} fallback
+ * @returns {boolean}
+ */
+const toBoolean = (value, fallback) => {
+  if (value == null) return fallback;
+  const normalized = String(value).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) return true;
+  if (['0', 'false', 'no', 'off'].includes(normalized)) return false;
+  return fallback;
+};
+
+/**
+ * @param {unknown} raw
+ * @returns {number[]}
+ */
+const parseSpeedList = (raw) => String(raw || '')
   .split(',')
-  .map(value => Number(value.trim()))
+  .map(value => toNumberOrNaN(value.trim()))
   .filter(value => Number.isFinite(value) && value > 0);
-const headless = (args.get('headless') || process.env.HISTORY_HEADLESS || 'true') !== 'false';
 
+const withTimeout = async (promise, timeoutMs, label) => {
+  let timeoutId = null;
+  const timeoutPromise = new Promise((_, reject) => {
+    timeoutId = setTimeout(() => {
+      reject(new Error(`${label} timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([promise, timeoutPromise]);
+  } finally {
+    if (timeoutId != null) clearTimeout(timeoutId);
+  }
+};
+
+const closeQuietly = async (target, label) => {
+  if (!target || typeof target.close !== 'function') return;
+  try {
+    await withTimeout(target.close(), 5000, label);
+  } catch {
+    // best-effort shutdown
+  }
+};
+
+const HISTORY_PROFILES = {
+  smoke: {
+    durationMs: 6000,
+    sampleMs: 500,
+    targetSpanTicks: 6000,
+    speeds: '30,60',
+    seekSamples: 4,
+    seekP95MsMax: 200,
+    maxRuntimeMs: 70000
+  },
+  default: {
+    durationMs: 60000,
+    sampleMs: 1000,
+    targetSpanTicks: 60000,
+    speeds: '30,60,120',
+    seekSamples: 12,
+    seekP95MsMax: 400,
+    maxRuntimeMs: 300000
+  },
+  soak: {
+    durationMs: 180000,
+    sampleMs: 1000,
+    targetSpanTicks: 60000,
+    speeds: '30,60,120',
+    seekSamples: 12,
+    seekP95MsMax: 400,
+    maxRuntimeMs: 300000
+  }
+};
+
+/**
+ * @param {{
+ *   argv?: string[],
+ *   env?: Record<string, string | undefined>,
+ *   log?: Pick<typeof console, 'warn'>
+ * }} [options]
+ */
+const createHistoryBenchConfig = (
+  {
+    argv = process.argv.slice(2),
+    env = process.env,
+    log = console
+  } = {}
+) => {
+  const args = parseArgs(argv);
+  const baseUrl = args.get('url') || env.LEMMINGS_BENCH_URL || DEFAULT_BASE_URL;
+  const smokeRequested = args.has('smoke') || env.BENCH_SMOKE === '1';
+  const soakRequested = args.has('soak') || env.BENCH_SOAK === '1';
+  const requestedProfile = (
+    args.get('profile') ||
+    env.HISTORY_PROFILE ||
+    (soakRequested ? 'soak' : smokeRequested ? 'smoke' : 'smoke')
+  ).toLowerCase();
+  const profileExplicit = args.has('profile')
+    || !!env.HISTORY_PROFILE
+    || smokeRequested
+    || soakRequested;
+  const profile = HISTORY_PROFILES[requestedProfile] || HISTORY_PROFILES.smoke;
+  if (!profileExplicit) {
+    log.warn?.('[bench-history-stress] No explicit profile selected; defaulting to smoke. Use --profile=default for longer runs.');
+  }
+
+  const speedInput = args.get('speeds') || env.HISTORY_SPEEDS || profile.speeds;
+  const parsedSpeeds = parseSpeedList(speedInput);
+  const speeds = parsedSpeeds.length ? parsedSpeeds : parseSpeedList(profile.speeds);
+  if (!parsedSpeeds.length) {
+    log.warn?.(`[bench-history-stress] Invalid speed list "${String(speedInput)}"; falling back to profile defaults (${profile.speeds}).`);
+  }
+
+  const durationMs = toPositiveNumber(
+    args.get('duration') || env.HISTORY_DURATION_MS,
+    profile.durationMs
+  );
+  const sampleMs = toPositiveNumber(
+    args.get('sample') || env.HISTORY_SAMPLE_MS,
+    profile.sampleMs
+  );
+
+  return {
+    baseUrl,
+    requestedProfile,
+    durationMs,
+    sampleMs,
+    targetSpan: toPositiveNumber(
+      args.get('target') || env.HISTORY_TARGET_TICKS,
+      profile.targetSpanTicks
+    ),
+    speeds,
+    headless: toBoolean(args.get('headless') || env.HISTORY_HEADLESS, true),
+    opTimeoutMs: toPositiveNumber(args.get('opTimeout') || env.HISTORY_OP_TIMEOUT_MS, 30000),
+    maxRuntimeMs: toPositiveNumber(
+      args.get('maxRuntime') || env.HISTORY_MAX_RUNTIME_MS,
+      profile.maxRuntimeMs ?? ((durationMs * Math.max(speeds.length, 1)) + Math.max(60000, sampleMs * 20))
+    ),
+    seekSamples: Math.max(1, Math.trunc(toPositiveNumber(
+      args.get('seekSamples') || env.HISTORY_SEEK_SAMPLES,
+      profile.seekSamples
+    ))),
+    seekP95MsMax: toPositiveNumber(
+      args.get('seekP95MsMax') || env.HISTORY_SEEK_P95_MS_MAX,
+      profile.seekP95MsMax
+    ),
+    requireReplayParity: toBoolean(
+      args.get('requireReplayParity') || env.HISTORY_REQUIRE_REPLAY_PARITY,
+      true
+    ),
+    requireBoundedRetention: toBoolean(
+      args.get('requireBoundedRetention') || env.HISTORY_REQUIRE_BOUNDED_RETENTION,
+      true
+    ),
+    requireTargetSpan: toBoolean(
+      args.get('requireTargetSpan') || env.HISTORY_REQUIRE_TARGET_SPAN,
+      requestedProfile !== 'smoke'
+    ),
+    requireColdCompaction: toBoolean(
+      args.get('requireColdCompaction') || env.HISTORY_REQUIRE_COLD_COMPACTION,
+      requestedProfile !== 'smoke'
+    )
+  };
+};
+
+/**
+ * @param {string} raw
+ * @returns {string}
+ */
 const buildUrl = (raw) => {
-  const url = new URL(raw);
+  /** @type {URL} */
+  let url;
+  try {
+    url = new URL(raw || DEFAULT_BASE_URL);
+  } catch {
+    url = new URL(DEFAULT_BASE_URL);
+  }
   url.searchParams.set('e2e', '1');
   url.searchParams.set('ph', 'true');
   url.searchParams.set('endless', 'true');
@@ -31,58 +222,322 @@ const buildUrl = (raw) => {
 
 const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
 
-const run = async () => {
-  const browser = await chromium.launch({
+const percentile = (sorted, p) => {
+  if (!sorted.length) return 0;
+  const clamped = Math.min(1, Math.max(0, p));
+  const index = Math.max(0, Math.min(sorted.length - 1, Math.ceil((sorted.length - 1) * clamped)));
+  return sorted[index];
+};
+
+/**
+ * @param {unknown[]} timingsMs
+ * @returns {{count: number, p50Ms: number, p95Ms: number, maxMs: number, samplesMs: number[]}}
+ */
+const summarizeTimings = (timingsMs) => {
+  const clean = (Array.isArray(timingsMs) ? timingsMs : [])
+    .map(value => toNumberOrNaN(value))
+    .filter(value => Number.isFinite(value) && value >= 0)
+    .sort((a, b) => a - b);
+  const max = clean.length ? clean[clean.length - 1] : 0;
+  return {
+    count: clean.length,
+    p50Ms: percentile(clean, 0.5),
+    p95Ms: percentile(clean, 0.95),
+    maxMs: max,
+    samplesMs: clean
+  };
+};
+
+/**
+ * @param {{
+ *   baseUrl: string,
+ *   requestedProfile: string,
+ *   durationMs: number,
+ *   sampleMs: number,
+ *   targetSpan: number,
+ *   speeds: number[],
+ *   headless: boolean,
+ *   opTimeoutMs: number,
+ *   maxRuntimeMs: number,
+ *   seekSamples: number,
+ *   seekP95MsMax: number,
+ *   requireReplayParity: boolean,
+ *   requireBoundedRetention: boolean,
+ *   requireTargetSpan: boolean,
+ *   requireColdCompaction: boolean
+ * }} [config]
+ */
+const run = async (config = createHistoryBenchConfig()) => {
+  const {
+    baseUrl,
+    requestedProfile,
+    durationMs,
+    sampleMs,
+    targetSpan,
+    speeds,
     headless,
-    args: ['--allow-insecure-localhost', '--ignore-certificate-errors']
-  });
-  const context = await browser.newContext({ ignoreHTTPSErrors: true });
-  const page = await context.newPage();
-
-  const results = [];
-  for (const speed of speeds) {
-    await page.goto(buildUrl(baseUrl), { waitUntil: 'domcontentloaded' });
-    await page.waitForFunction(() => window.__E2E__?.getState?.().ready === true);
-    await page.evaluate((value) => window.__E2E__.setSpeed(value), speed);
-    await page.evaluate(() => window.__E2E__.resume());
-
-    const start = Date.now();
-    let spanTicks = 0;
-    let maxSpan = 0;
-    while (Date.now() - start < durationMs) {
-      const history = await page.evaluate(() => window.__E2E__.getState().game.history);
-      spanTicks = history?.spanTicks || 0;
-      if (spanTicks > maxSpan) maxSpan = spanTicks;
-      if (spanTicks >= targetSpan) break;
-      await sleep(sampleMs);
+    opTimeoutMs,
+    maxRuntimeMs,
+    seekSamples,
+    seekP95MsMax,
+    requireReplayParity,
+    requireBoundedRetention,
+    requireTargetSpan,
+    requireColdCompaction
+  } = config;
+  let browser = null;
+  let context = null;
+  let page = null;
+  const runStart = Date.now();
+  const failures = [];
+
+  const assertRuntimeBudget = (phase) => {
+    const elapsed = Date.now() - runStart;
+    if (elapsed > maxRuntimeMs) {
+      throw new Error(`History benchmark exceeded max runtime (${maxRuntimeMs}ms) during ${phase}.`);
+    }
+  };
+
+  try {
+    browser = await withTimeout(chromium.launch({
+      headless,
+      args: ['--allow-insecure-localhost', '--ignore-certificate-errors']
+    }), opTimeoutMs, 'chromium.launch');
+
+    context = await withTimeout(
+      browser.newContext({ ignoreHTTPSErrors: true }),
+      opTimeoutMs,
+      'browser.newContext'
+    );
+    page = await withTimeout(context.newPage(), opTimeoutMs, 'context.newPage');
+    page.setDefaultTimeout(opTimeoutMs);
+
+    const results = [];
+    for (const speed of speeds) {
+      assertRuntimeBudget(`speed=${speed} setup`);
+      await withTimeout(page.goto(buildUrl(baseUrl), { waitUntil: 'domcontentloaded' }), opTimeoutMs, 'page.goto');
+      await withTimeout(
+        page.waitForFunction(() => window.__E2E__?.getState?.().ready === true),
+        opTimeoutMs,
+        'waitForGameReady'
+      );
+      await withTimeout(page.evaluate((value) => window.__E2E__.setSpeed(value), speed), opTimeoutMs, 'setSpeed');
+      await withTimeout(page.evaluate(() => window.__E2E__.resume()), opTimeoutMs, 'e2e.resume');
+
+      const start = Date.now();
+      let spanTicks = 0;
+      let maxSpan = 0;
+      let lastHistory = null;
+      while (Date.now() - start < durationMs) {
+        assertRuntimeBudget(`speed=${speed} sampling`);
+        const history = await withTimeout(
+          page.evaluate(() => window.__E2E__?.getState?.()?.game?.history || null),
+          opTimeoutMs,
+          'readHistoryState'
+        );
+        lastHistory = history || null;
+        spanTicks = history?.spanTicks || 0;
+        if (spanTicks > maxSpan) maxSpan = spanTicks;
+        if (spanTicks >= targetSpan) break;
+        await sleep(sampleMs);
+      }
+
+      if (requireTargetSpan && maxSpan < targetSpan) {
+        failures.push(
+          `speed=${speed} history span ${maxSpan} did not reach target ${targetSpan} within ${durationMs}ms`
+        );
+      }
+
+      await withTimeout(page.evaluate(() => window.__E2E__.pause()), opTimeoutMs, 'e2e.pause');
+      const seekProbe = await withTimeout(
+        page.evaluate(({ samples }) => {
+          const api = window.__E2E__;
+          if (!api?.seek || !api?.getState) return null;
+          const gameState = api?.getState?.()?.game;
+          const historyState = gameState?.history || null;
+          const minTick = Number.isFinite(historyState?.minTick) ? Math.trunc(historyState.minTick) : 0;
+          const maxTick = Number.isFinite(historyState?.maxTick)
+            ? Math.trunc(historyState.maxTick)
+            : Math.trunc(gameState?.timer?.tickIndex || 0);
+          const startTick = Math.max(minTick, Math.min(maxTick, Math.trunc(gameState?.timer?.tickIndex || maxTick)));
+          const seekMs = [];
+          const count = Math.max(1, Math.trunc(samples || 1));
+          const span = Math.max(1, startTick - minTick);
+
+          const computeReplayHash = () => {
+            if (!api?.getDelta || maxTick < minTick) return null;
+            let hash = 2166136261;
+            const pushByte = (value) => {
+              hash ^= value & 0xff;
+              hash = Math.imul(hash, 16777619);
+            };
+            const pushAscii = (value) => {
+              const text = String(value);
+              for (let i = 0; i < text.length; i += 1) {
+                pushByte(text.charCodeAt(i));
+              }
+              pushByte(124);
+            };
+            for (let tick = minTick; tick <= maxTick; tick += 1) {
+              const delta = api.getDelta(tick);
+              if (!delta) continue;
+              const noOp = Number.isFinite(delta.flags)
+                ? ((delta.flags | 0) === 0 ? 1 : 0)
+                : 0;
+              pushAscii(tick);
+              pushAscii(noOp);
+              pushAscii(delta.lemChanges?.ids?.length || 0);
+              pushAscii(delta.lemAdded?.length || 0);
+              pushAscii(delta.lemRemoved?.length || 0);
+              pushAscii(delta.groundChanges?.indices?.length || 0);
+              pushAscii(delta.entranceChanges?.indices?.length || 0);
+              pushAscii(delta.triggerCooldownChanges?.ids?.length || 0);
+              pushAscii(delta.triggerAdd?.length || 0);
+              pushAscii(delta.triggerRemove?.length || 0);
+              pushAscii(delta.objectAnimChanges?.ids?.length || 0);
+              pushAscii(delta.soundEvents?.length || 0);
+              pushAscii(delta.minimapDeaths?.length || 0);
+              pushByte(10);
+            }
+            return (hash >>> 0).toString(16).padStart(8, '0');
+          };
+
+          const hashBefore = computeReplayHash();
+          const deltaAvailable = hashBefore != null;
+          for (let i = 0; i < count; i += 1) {
+            const ratio = (i + 1) / (count + 1);
+            const target = Math.max(minTick, startTick - Math.trunc(span * ratio));
+            const start = performance.now();
+            api.seek(target);
+            seekMs.push(performance.now() - start);
+          }
+          const returnStart = performance.now();
+          api.seek(startTick);
+          seekMs.push(performance.now() - returnStart);
+          const hashAfter = computeReplayHash();
+          return {
+            minTick,
+            maxTick,
+            startTick,
+            seekMs,
+            deltaAvailable,
+            hashBefore,
+            hashAfter,
+            hashMatch: hashBefore === hashAfter
+          };
+        }, { samples: seekSamples }),
+        opTimeoutMs,
+        'seekReplayProbe'
+      );
+      const seekStats = summarizeTimings(seekProbe?.seekMs);
+      if (seekStats.p95Ms > seekP95MsMax) {
+        failures.push(
+          `speed=${speed} seek p95 ${seekStats.p95Ms.toFixed(2)}ms > ${seekP95MsMax.toFixed(2)}ms`
+        );
+      }
+      if (requireReplayParity && seekProbe?.deltaAvailable !== false && seekProbe?.hashMatch === false) {
+        failures.push(
+          `speed=${speed} replay parity mismatch after seeks (${seekProbe.hashBefore} != ${seekProbe.hashAfter})`
+        );
+      }
+      const retention = lastHistory?.retention || null;
+      if (requireBoundedRetention) {
+        const bounded = !!retention?.enableHistoryCap && Number(retention?.historyCapTicks || 0) > 0;
+        if (!bounded) {
+          failures.push(`speed=${speed} expected bounded history retention to be enabled.`);
+        }
+      }
+      if (requireColdCompaction && Number(lastHistory?.coldBlockCount || 0) <= 0) {
+        failures.push(`speed=${speed} expected cold compaction blocks to be produced.`);
+      }
+      const memory = await withTimeout(page.evaluate(() => {
+        if (typeof performance === 'undefined' || !performance.memory) return null;
+        return {
+          usedJSHeapSize: performance.memory.usedJSHeapSize,
+          totalJSHeapSize: performance.memory.totalJSHeapSize,
+          jsHeapSizeLimit: performance.memory.jsHeapSizeLimit
+        };
+      }), opTimeoutMs, 'readMemorySnapshot');
+
+      results.push({
+        speedFactor: speed,
+        durationMs: Date.now() - start,
+        maxSpanTicks: maxSpan,
+        targetSpanTicks: targetSpan,
+        seekProbe: {
+          minTick: seekProbe?.minTick ?? 0,
+          maxTick: seekProbe?.maxTick ?? 0,
+          startTick: seekProbe?.startTick ?? 0,
+          deltaAvailable: seekProbe?.deltaAvailable !== false,
+          hashBefore: seekProbe?.hashBefore ?? null,
+          hashAfter: seekProbe?.hashAfter ?? null,
+          hashMatch: !!seekProbe?.hashMatch,
+          ...seekStats
+        },
+        history: {
+          spanTicks: Number(lastHistory?.spanTicks || 0),
+          coldBlockCount: Number(lastHistory?.coldBlockCount || 0),
+          coldBlockBytes: Number(lastHistory?.coldBlockBytes || 0),
+          retention: retention
+            ? {
+              enableHistoryCap: !!retention.enableHistoryCap,
+              historyCapTicks: Number(retention.historyCapTicks || 0),
+              historyWarnTicks: Number(retention.historyWarnTicks || 0)
+            }
+            : null
+        },
+        memory
+      });
     }
-    await page.evaluate(() => window.__E2E__.pause());
-    const memory = await page.evaluate(() => {
-      if (typeof performance === 'undefined' || !performance.memory) return null;
-      return {
-        usedJSHeapSize: performance.memory.usedJSHeapSize,
-        totalJSHeapSize: performance.memory.totalJSHeapSize,
-        jsHeapSizeLimit: performance.memory.jsHeapSizeLimit
-      };
-    });
-    results.push({
-      speedFactor: speed,
-      durationMs: Date.now() - start,
-      maxSpanTicks: maxSpan,
+
+    console.log(JSON.stringify({
+      profile: requestedProfile,
       targetSpanTicks: targetSpan,
-      memory
-    });
+      sampleMs,
+      seekGate: {
+        seekSamples,
+        seekP95MsMax,
+        requireReplayParity,
+        requireBoundedRetention,
+        requireTargetSpan,
+        requireColdCompaction
+      },
+      results,
+      failures
+    }, null, 2));
+    if (failures.length) {
+      process.exitCode = 1;
+    }
+  } finally {
+    await closeQuietly(page, 'page.close');
+    await closeQuietly(context, 'context.close');
+    await closeQuietly(browser, 'browser.close');
   }
-
-  await browser.close();
-  console.log(JSON.stringify({
-    targetSpanTicks: targetSpan,
-    sampleMs,
-    results
-  }, null, 2));
 };
 
-run().catch((error) => {
-  console.error(error);
-  process.exitCode = 1;
-});
+const isMainModule = (() => {
+  try {
+    return path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+})();
+
+if (isMainModule) {
+  run().catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+  });
+}
+
+export {
+  buildUrl,
+  createHistoryBenchConfig,
+  DEFAULT_BASE_URL,
+  parseArgs,
+  parseSpeedList,
+  run,
+  summarizeTimings,
+  toBoolean,
+  toPositiveNumber
+};
diff --git a/scripts/bench-hotpaths.js b/scripts/bench-hotpaths.js
new file mode 100644
index 00000000..2a1618a3
--- /dev/null
+++ b/scripts/bench-hotpaths.js
@@ -0,0 +1,139 @@
+import {
+  fileURLToPath,
+  parseArgs,
+  path,
+  toPositiveInt
+} from './bench-hotpaths/shared.js';
+import {
+  runDirtyRectBench,
+  runTileCompositionBench,
+  runMarchingAntBench,
+  runGuiOverlayBench,
+  runOverlayPlaneBench,
+  runScaledBlitBench
+} from './bench-hotpaths/renderScenarios.js';
+import {
+  runMidiRouterBench,
+  runMidiSchedulerBench
+} from './bench-hotpaths/midiScenarios.js';
+import {
+  runHistoryScenario,
+  runHistoryReplayBench
+} from './bench-hotpaths/historyScenarios.js';
+import {
+  runTerrainCheckScenario,
+  runTerrainClearScenario,
+  runDigRowScenario,
+  runTerrainMaskBench
+} from './bench-hotpaths/terrainScenarios.js';
+import {
+  runObjectCullingScenario,
+  runObjectCullingBench
+} from './bench-hotpaths/objectScenarios.js';
+import {
+  runMiniMapScenario,
+  runMiniMapIdleBench,
+  runGamepadIdleBench
+} from './bench-hotpaths/idleScenarios.js';
+const buildHotpathSummary = (argv = process.argv.slice(2)) => {
+  const args = parseArgs(argv);
+  const smokeRequested = args.has('smoke') || process.env.BENCH_SMOKE === '1';
+  const repeats = toPositiveInt(args.get('repeats'), smokeRequested ? 4 : 6);
+  const dirtyIterations = toPositiveInt(args.get('dirty-iterations'), smokeRequested ? 1500 : 3000);
+  const dirtyRectsPerIter = toPositiveInt(args.get('dirty-rects'), smokeRequested ? 6 : 8);
+  const tileIterations = toPositiveInt(args.get('tile-iterations'), smokeRequested ? 1200 : 2800);
+  const tilePerIter = toPositiveInt(args.get('tile-per-iter'), smokeRequested ? 6 : 10);
+  const antsIterations = toPositiveInt(args.get('ants-iterations'), smokeRequested ? 3000 : 6000);
+  const guiIterations = toPositiveInt(args.get('gui-iterations'), smokeRequested ? 1000 : 2000);
+  const overlayIterations = toPositiveInt(args.get('overlay-iterations'), smokeRequested ? 700 : 1800);
+  const scaledIterations = toPositiveInt(args.get('scaled-iterations'), smokeRequested ? 1600 : 3800);
+  const midiRouterIterations = toPositiveInt(args.get('midi-router-iterations'), smokeRequested ? 700 : 1600);
+  const midiRouterEvents = toPositiveInt(args.get('midi-router-events'), smokeRequested ? 12 : 24);
+  const midiSchedulerIterations = toPositiveInt(args.get('midi-scheduler-iterations'), smokeRequested ? 700 : 1600);
+  const midiSchedulerNotes = toPositiveInt(args.get('midi-scheduler-notes'), smokeRequested ? 12 : 24);
+  const historyTicks = toPositiveInt(args.get('history-ticks'), smokeRequested ? 80 : 180);
+  const historySeekWindow = toPositiveInt(args.get('history-seek-window'), smokeRequested ? 24 : 60);
+  const terrainIterations = toPositiveInt(args.get('terrain-iterations'), smokeRequested ? 1000 : 2500);
+  const terrainClearIterations = toPositiveInt(args.get('terrain-clear-iterations'), smokeRequested ? 180 : 500);
+  const terrainDigIterations = toPositiveInt(args.get('terrain-dig-iterations'), smokeRequested ? 220 : 700);
+  const objectIterations = toPositiveInt(args.get('object-iterations'), smokeRequested ? 25 : 80);
+  const minimapIterations = toPositiveInt(args.get('minimap-iterations'), smokeRequested ? 900 : 2200);
+  const gamepadIterations = toPositiveInt(args.get('gamepad-iterations'), smokeRequested ? 360 : 1200);
+
+  return {
+    historyReplayDelta: runHistoryReplayBench({
+      ticks: historyTicks,
+      seekWindow: historySeekWindow,
+      repeats
+    }),
+    terrainMasks: runTerrainMaskBench({
+      iterations: terrainIterations,
+      clearIterations: terrainClearIterations,
+      digIterations: terrainDigIterations,
+      repeats
+    }),
+    dirtyRectUpload: runDirtyRectBench({
+      iterations: dirtyIterations,
+      rectsPerIter: dirtyRectsPerIter,
+      repeats
+    }),
+    tileComposition: runTileCompositionBench({
+      iterations: tileIterations,
+      tilesPerIter: tilePerIter,
+      repeats
+    }),
+    marchingAnts: runMarchingAntBench({
+      iterations: antsIterations,
+      repeats
+    }),
+    guiOverlay: runGuiOverlayBench({
+      iterations: guiIterations,
+      repeats
+    }),
+    overlayPlane: runOverlayPlaneBench({
+      iterations: overlayIterations,
+      repeats
+    }),
+    scaledBlit: runScaledBlitBench({
+      iterations: scaledIterations,
+      repeats
+    }),
+    objectCulling: runObjectCullingBench({
+      iterations: objectIterations,
+      repeats
+    }),
+    minimapIdle: runMiniMapIdleBench({
+      iterations: minimapIterations,
+      repeats
+    }),
+    gamepadIdle: runGamepadIdleBench({
+      iterations: gamepadIterations,
+      repeats
+    }),
+    midiRouter: runMidiRouterBench({
+      iterations: midiRouterIterations,
+      eventsPerIter: midiRouterEvents,
+      repeats
+    }),
+    midiScheduler: runMidiSchedulerBench({
+      iterations: midiSchedulerIterations,
+      notesPerIter: midiSchedulerNotes,
+      repeats
+    })
+  };
+};
+const main = (argv = process.argv.slice(2)) => {
+  const summary = buildHotpathSummary(argv);
+  console.log(JSON.stringify(summary, null, 2));
+};
+const isMain = (() => {
+  try {
+    return path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+})();
+if (isMain) {
+  main();
+}
+export { buildHotpathSummary };
\ No newline at end of file
diff --git a/scripts/bench-hotpaths/historyScenarios.js b/scripts/bench-hotpaths/historyScenarios.js
new file mode 100644
index 00000000..fb5311e0
--- /dev/null
+++ b/scripts/bench-hotpaths/historyScenarios.js
@@ -0,0 +1,199 @@
+import {
+  ActionDiggSystem,
+  DisplayImage,
+  EventHandler,
+  Frame,
+  GameGui,
+  GamepadInputController,
+  HistoryStore,
+  Level,
+  Mask,
+  MidiEventRouter,
+  MidiScheduler,
+  MiniMap,
+  ObjectManager,
+  SkillTypes,
+  Stage,
+  estimateBytes,
+  fileURLToPath,
+  makeCanvas,
+  makeContext,
+  makePalette,
+  measureN,
+  nsToMs,
+  parseArgs,
+  path,
+  percentile,
+  setupRenderEnvironment,
+  summarizeSamples,
+  toNumberOrNaN,
+  toPositiveInt,
+  withGlobalStubs
+} from './shared.js';
+const makeHistoryGame = (lemmingCount) => {
+  const walkAction = { name: 'walk' };
+  const lemmings = new Array(lemmingCount);
+  for (let i = 0; i < lemmingCount; i += 1) {
+    lemmings[i] = {
+      id: i,
+      x: 10 + (i % 80),
+      y: 20 + Math.floor(i / 80),
+      lookRight: (i & 1) === 0,
+      frameIndex: i & 7,
+      state: 0,
+      canClimb: false,
+      hasParachute: false,
+      removed: false,
+      disabled: false,
+      countdown: 0,
+      hasExploded: false,
+      lastTriggerType: null,
+      action: walkAction,
+      countdownAction: null
+    };
+  }
+  const manager = {
+    lemmings,
+    activeLemmings: lemmings.slice(),
+    actions: [walkAction],
+    skillActions: [],
+    actionTypeByAction: new Map([[walkAction, 0]]),
+    selectedIndex: -1,
+    spawnTotal: lemmingCount,
+    releaseTickIndex: 0,
+    mmTickCounter: 0,
+    nextNukingLemmingsIndex: -1,
+    _nukeTargets: null,
+    getLemming(id) { return this.lemmings[id] || null; }
+  };
+  const timer = {
+    speedFactor: 1,
+    frameTime: 1000 / 60,
+    tickIndex: 0
+  };
+  const skills = {
+    selectedSkill: SkillTypes.BASHER,
+    cheatMode: false,
+    skills: [0, 20, 20, 20, 20, 20, 20, 20, 20]
+  };
+  const victory = {
+    releaseRate: 50,
+    minReleaseRate: 1,
+    leftCount: lemmingCount,
+    outCount: lemmingCount,
+    survivorCount: 0,
+    isFinalize: false
+  };
+  const level = {
+    entrances: [],
+    triggers: [],
+    objects: [],
+    groundMask: null,
+    groundImage: null
+  };
+  const game = {
+    level,
+    finalGameState: 0,
+    getLemmingManager() { return manager; },
+    getGameTimer() { return timer; },
+    getGameSkills() { return skills; },
+    getVictoryCondition() { return victory; }
+  };
+  return { game, manager, timer, skills, victory };
+};
+const mutateHistoryLemmings = (manager, tick) => {
+  const lems = manager.lemmings;
+  const stride = Math.max(1, Math.floor(lems.length / 32));
+  for (let i = tick % stride; i < lems.length; i += stride) {
+    const lem = lems[i];
+    if (!lem || lem.removed) continue;
+    lem.x += ((tick + i) & 1) ? 1 : -1;
+    lem.frameIndex = (lem.frameIndex + 1) & 15;
+    if (((tick + i) % 17) === 0) {
+      lem.lookRight = !lem.lookRight;
+    }
+  }
+  manager.mmTickCounter += 1;
+};
+const runHistoryScenario = ({ lemmingCount, ticks, seekWindow, repeats }) => {
+  const recordSamples = [];
+  const applySamples = [];
+  let lastMetrics = null;
+  for (let repeat = 0; repeat < repeats + 1; repeat += 1) {
+    const { game, manager, timer, skills } = makeHistoryGame(lemmingCount);
+    const history = new HistoryStore({
+      keyframeInterval: 60,
+      enableHistoryCap: false,
+      enableColdBlockCompression: false,
+      enableColdBlockDedupe: false
+    });
+    history.game = game;
+    history.timer = timer;
+    history._recording = true;
+    history.captureBaseline(game);
+    const startRecord = process.hrtime.bigint();
+    for (let tick = 0; tick < ticks; tick += 1) {
+      history.beginTick(timer.tickIndex);
+      mutateHistoryLemmings(manager, tick);
+      if (tick > 0 && (tick % 90) === 0) {
+        timer.speedFactor = timer.speedFactor === 1 ? 2 : 1;
+        skills.selectedSkill = skills.selectedSkill === SkillTypes.BASHER
+          ? SkillTypes.DIGGER
+          : SkillTypes.BASHER;
+      }
+      timer.tickIndex += 1;
+      history.endTick();
+    }
+    recordSamples.push(nsToMs(process.hrtime.bigint() - startRecord));
+
+    const applyStartTick = Math.max(0, ticks - seekWindow);
+    const startApply = process.hrtime.bigint();
+    for (let tick = ticks - 1; tick >= applyStartTick; tick -= 1) {
+      history.applyDeltaBackward(game, history.getDelta(tick));
+    }
+    for (let tick = applyStartTick; tick < ticks; tick += 1) {
+      history.applyDeltaForward(game, history.getDelta(tick));
+    }
+    applySamples.push(nsToMs(process.hrtime.bigint() - startApply));
+
+    if (repeat === repeats) {
+      let deltaBytes = 0;
+      let nonEmptyDeltas = 0;
+      for (let tick = 0; tick < ticks; tick += 1) {
+        const delta = history.getDelta(tick);
+        if (!delta) continue;
+        nonEmptyDeltas += 1;
+        deltaBytes += history._packDeltaForStorage(delta).length;
+      }
+      let keyframeBytes = 0;
+      for (const keyframe of history.keyframes) {
+        if (keyframe) keyframeBytes += estimateBytes(keyframe);
+      }
+      lastMetrics = {
+        retainedDeltaCount: history.getHistoryStats().deltaCount,
+        nonEmptyDeltas,
+        avgDeltaBytes: Number((deltaBytes / Math.max(1, nonEmptyDeltas)).toFixed(2)),
+        keyframeBytes,
+        replayHash: history.computeReplayHash()
+      };
+    }
+  }
+  const record = summarizeSamples(recordSamples.slice(1), ticks);
+  const apply = summarizeSamples(applySamples.slice(1), seekWindow * 2);
+  return {
+    endTick: record,
+    seekWindowApply: apply,
+    ...lastMetrics
+  };
+};
+const runHistoryReplayBench = ({ ticks, seekWindow, repeats }) => ({
+  lemmings50: runHistoryScenario({ lemmingCount: 50, ticks, seekWindow, repeats }),
+  lemmings200: runHistoryScenario({ lemmingCount: 200, ticks, seekWindow, repeats }),
+  lemmings1000: runHistoryScenario({ lemmingCount: 1000, ticks, seekWindow, repeats })
+});
+export {
+  makeHistoryGame,
+  mutateHistoryLemmings,
+  runHistoryScenario,
+  runHistoryReplayBench
+};
\ No newline at end of file
diff --git a/scripts/bench-hotpaths/idleScenarios.js b/scripts/bench-hotpaths/idleScenarios.js
new file mode 100644
index 00000000..b190b78a
--- /dev/null
+++ b/scripts/bench-hotpaths/idleScenarios.js
@@ -0,0 +1,175 @@
+import {
+  ActionDiggSystem,
+  DisplayImage,
+  EventHandler,
+  Frame,
+  GameGui,
+  GamepadInputController,
+  HistoryStore,
+  Level,
+  Mask,
+  MidiEventRouter,
+  MidiScheduler,
+  MiniMap,
+  ObjectManager,
+  SkillTypes,
+  Stage,
+  estimateBytes,
+  fileURLToPath,
+  makeCanvas,
+  makeContext,
+  makePalette,
+  measureN,
+  nsToMs,
+  parseArgs,
+  path,
+  percentile,
+  setupRenderEnvironment,
+  summarizeSamples,
+  toNumberOrNaN,
+  toPositiveInt,
+  withGlobalStubs
+} from './shared.js';
+const makeMiniMapLevel = () => {
+  const width = 640;
+  const height = 160;
+  const mask = { mask: new Uint8Array(width * height) };
+  mask.mask.fill(1);
+  return {
+    width,
+    height,
+    screenPositionX: 0,
+    objects: [],
+    groundMask: mask,
+    getGroundMaskLayer() {
+      return {
+        countMaskInRect(x, y, w, h) {
+          return ((Math.trunc(x + y + w + h) % 9) + 1);
+        }
+      };
+    }
+  };
+};
+const makeMiniMapGuiDisplay = () => ({
+  worldDataSize: { width: 320, height: 40 },
+  drawCalls: 0,
+  onMouseDown: new EventHandler(),
+  onMouseUp: new EventHandler(),
+  onMouseMove: new EventHandler(),
+  drawFrame() { this.drawCalls += 1; }
+});
+const runMiniMapScenario = ({ iterations, repeats, mode }) => withGlobalStubs(() => {
+  setupRenderEnvironment();
+  const samples = [];
+  let diagnostics = null;
+  let drawCalls = 0;
+  let subarrayFallbacks = 0;
+  for (let repeat = 0; repeat < repeats + 1; repeat += 1) {
+    const level = makeMiniMapLevel();
+    const guiDisplay = makeMiniMapGuiDisplay();
+    const runtime = {
+      performanceContext: {
+        stage: {
+          getGameViewRect() {
+            return { x: level.screenPositionX, y: 0, w: 160, h: 120 };
+          }
+        }
+      }
+    };
+    const miniMap = new MiniMap({}, level, guiDisplay, runtime);
+    const liveDots = new Uint8Array(512);
+    for (let i = 0; i < liveDots.length; i += 2) {
+      liveDots[i] = (i * 3) % miniMap.width;
+      liveDots[i + 1] = (i * 5) % miniMap.height;
+    }
+    const start = process.hrtime.bigint();
+    for (let i = 0; i < iterations; i += 1) {
+      if (mode === 'liveDots') {
+        const active = 160 + ((i % 32) * 2);
+        if (miniMap.setLiveDots.length >= 2) {
+          miniMap.setLiveDots(liveDots, active);
+        } else {
+          subarrayFallbacks += 1;
+          miniMap.setLiveDots(liveDots.subarray(0, active));
+        }
+      } else if (mode === 'deaths') {
+        if ((i % 12) === 0) miniMap.addDeath(i % level.width, (i * 3) % level.height);
+      } else if (mode === 'viewport') {
+        level.screenPositionX = (i * 5) % 400;
+      }
+      miniMap.render();
+    }
+    samples.push(nsToMs(process.hrtime.bigint() - start));
+    diagnostics = miniMap.getRenderDiagnostics();
+    drawCalls = guiDisplay.drawCalls;
+    miniMap.dispose();
+  }
+  const summary = summarizeSamples(samples.slice(1), iterations);
+  summary.drawCalls = drawCalls;
+  summary.composes = diagnostics?.composes ?? 0;
+  summary.reuses = diagnostics?.reuses ?? 0;
+  summary.subarrayFallbacks = subarrayFallbacks;
+  return summary;
+});
+const runMiniMapIdleBench = ({ iterations, repeats }) => ({
+  pausedIdle: runMiniMapScenario({ iterations, repeats, mode: 'idle' }),
+  manyLiveDots: runMiniMapScenario({ iterations, repeats, mode: 'liveDots' }),
+  deathDots: runMiniMapScenario({ iterations, repeats, mode: 'deaths' }),
+  viewportMovement: runMiniMapScenario({ iterations, repeats, mode: 'viewport' })
+});
+const runGamepadIdleBench = ({ iterations, repeats }) => {
+  const samples = [];
+  let polls = 0;
+  for (let repeat = 0; repeat < repeats + 1; repeat += 1) {
+    let now = 0;
+    const rafCallbacks = [];
+    let getGamepadsCalls = 0;
+    const windowStub = {
+      requestAnimationFrame(callback) {
+        rafCallbacks.push(callback);
+        return rafCallbacks.length;
+      },
+      cancelAnimationFrame() {},
+      addEventListener() {},
+      removeEventListener() {}
+    };
+    const navigatorStub = {
+      getGamepads() {
+        getGamepadsCalls += 1;
+        return [];
+      }
+    };
+    const prevPerformance = globalThis.performance;
+    globalThis.performance = {
+      now() { return now; },
+      measure() {}
+    };
+    const start = process.hrtime.bigint();
+    const controller = new GamepadInputController({
+      mode: 'gameplay',
+      window: windowStub,
+      navigator: navigatorStub,
+      storage: null
+    });
+    for (let i = 0; i < iterations; i += 1) {
+      now += 16.67;
+      const cb = rafCallbacks.shift();
+      if (typeof cb === 'function') cb();
+    }
+    controller.dispose();
+    samples.push(nsToMs(process.hrtime.bigint() - start));
+    polls = getGamepadsCalls;
+    globalThis.performance = prevPerformance;
+  }
+  const summary = summarizeSamples(samples.slice(1), iterations);
+  summary.getGamepadsCalls = polls;
+  summary.pollsPerFrame = Number((polls / Math.max(1, iterations)).toFixed(4));
+  return summary;
+};
+export {
+  makeMiniMapLevel,
+  makeMiniMapGuiDisplay,
+  runMiniMapScenario,
+  runMiniMapIdleBench,
+  runGamepadIdleBench
+};
\ No newline at end of file
diff --git a/scripts/bench-hotpaths/midiScenarios.js b/scripts/bench-hotpaths/midiScenarios.js
new file mode 100644
index 00000000..ca6e88ac
--- /dev/null
+++ b/scripts/bench-hotpaths/midiScenarios.js
@@ -0,0 +1,136 @@
+import {
+  ActionDiggSystem,
+  DisplayImage,
+  EventHandler,
+  Frame,
+  GameGui,
+  GamepadInputController,
+  HistoryStore,
+  Level,
+  Mask,
+  MidiEventRouter,
+  MidiScheduler,
+  MiniMap,
+  ObjectManager,
+  SkillTypes,
+  Stage,
+  estimateBytes,
+  fileURLToPath,
+  makeCanvas,
+  makeContext,
+  makePalette,
+  measureN,
+  nsToMs,
+  parseArgs,
+  path,
+  percentile,
+  setupRenderEnvironment,
+  summarizeSamples,
+  toNumberOrNaN,
+  toPositiveInt,
+  withGlobalStubs
+} from './shared.js';
+const makeMidiOutput = (channelCount = 16) => {
+  const channels = {};
+  for (let i = 1; i <= channelCount; i += 1) {
+    channels[i] = {
+      sendNoteOn() {},
+      sendNoteOff() {},
+      sendPitchBend() {},
+      sendPitchBendRange() {},
+      sendControlChange() {},
+      sendAllNotesOff() {}
+    };
+  }
+  return { channels };
+};
+const runMidiRouterBench = ({ iterations, eventsPerIter, repeats }) => withGlobalStubs(() => {
+  setupRenderEnvironment();
+  const router = new MidiEventRouter({
+    enabled: true,
+    noteRange: { min: 36, max: 96 },
+    durationTicks: { min: 0, max: 0, default: 0 },
+    timing: { bpmBase: 120, scheduleAheadMs: 0 },
+    repeat: { enabled: false },
+    limits: {
+      maxPerTick: 128,
+      maxPerSecond: 1000,
+      maxBytesPerSecond: 100000000
+    }
+  });
+  router.context = {
+    game: {
+      getGameTimer() {
+        return { tps: 60, speedFactor: 1 };
+      }
+    }
+  };
+  router.setOutput(makeMidiOutput(16));
+
+  const runOnce = () => {
+    for (let i = 0; i < iterations; i += 1) {
+      const tick = i + 1;
+      for (let eventIndex = 0; eventIndex < eventsPerIter; eventIndex += 1) {
+        router._onEvent({
+          tick,
+          sfxId: 1,
+          x: (eventIndex * 7) % 320,
+          y: (eventIndex * 11) % 200
+        });
+      }
+    }
+  };
+
+  const measured = measureN(repeats + 1, runOnce);
+  router.dispose();
+  const summary = summarizeSamples(measured.samplesMs.slice(1), iterations * Math.max(1, eventsPerIter));
+  const allocation = summarizeSamples(measured.allocationSamples.slice(1), iterations * Math.max(1, eventsPerIter));
+  summary.allocBytesAvg = Math.round(allocation.avgMs);
+  summary.allocBytesP95 = Math.round(allocation.p95Ms);
+  summary.allocBytesWorst = Math.round(allocation.worstMs);
+  return summary;
+});
+const runMidiSchedulerBench = ({ iterations, notesPerIter, repeats }) => withGlobalStubs(() => {
+  setupRenderEnvironment();
+  const scheduler = new MidiScheduler({
+    defaultChannel: 1,
+    limits: {
+      maxActiveNotes: 32,
+      maxEventsPerSecond: 1000,
+      maxBytesPerSecond: 100000000
+    },
+    mpe: { enabled: false }
+  });
+  scheduler.setTickMs(1000 / 60);
+  scheduler.setOutput(makeMidiOutput(16));
+
+  const runOnce = () => {
+    for (let i = 0; i < iterations; i += 1) {
+      for (let noteIndex = 0; noteIndex < notesPerIter; noteIndex += 1) {
+        scheduler.sendNote({
+          note: 48 + ((i + noteIndex) % 24),
+          velocity: 96,
+          durationTicks: 0,
+          channel: 1
+        }, {
+          sfxId: 1,
+          priority: 1
+        });
+      }
+    }
+  };
+
+  const measured = measureN(repeats + 1, runOnce);
+  scheduler.dispose();
+  const summary = summarizeSamples(measured.samplesMs.slice(1), iterations * Math.max(1, notesPerIter));
+  const allocation = summarizeSamples(measured.allocationSamples.slice(1), iterations * Math.max(1, notesPerIter));
+  summary.allocBytesAvg = Math.round(allocation.avgMs);
+  summary.allocBytesP95 = Math.round(allocation.p95Ms);
+  summary.allocBytesWorst = Math.round(allocation.worstMs);
+  return summary;
+});
+export {
+  makeMidiOutput,
+  runMidiRouterBench,
+  runMidiSchedulerBench
+};
\ No newline at end of file
diff --git a/scripts/bench-hotpaths/objectScenarios.js b/scripts/bench-hotpaths/objectScenarios.js
new file mode 100644
index 00000000..e84a0f45
--- /dev/null
+++ b/scripts/bench-hotpaths/objectScenarios.js
@@ -0,0 +1,90 @@
+import {
+  ActionDiggSystem,
+  DisplayImage,
+  EventHandler,
+  Frame,
+  GameGui,
+  GamepadInputController,
+  HistoryStore,
+  Level,
+  Mask,
+  MidiEventRouter,
+  MidiScheduler,
+  MiniMap,
+  ObjectManager,
+  SkillTypes,
+  Stage,
+  estimateBytes,
+  fileURLToPath,
+  makeCanvas,
+  makeContext,
+  makePalette,
+  measureN,
+  nsToMs,
+  parseArgs,
+  path,
+  percentile,
+  setupRenderEnvironment,
+  summarizeSamples,
+  toNumberOrNaN,
+  toPositiveInt,
+  withGlobalStubs
+} from './shared.js';
+const makeObjectFrame = (width = 24, height = 18) => {
+  const frame = new Frame(width, height);
+  frame.fill(20, 160, 80);
+  return frame;
+};
+const runObjectCullingScenario = ({ objectCount, iterations, repeats, fullView = false }) => {
+  const frame = makeObjectFrame();
+  const samples = [];
+  let drawn = 0;
+  let candidates = 0;
+  for (let repeat = 0; repeat < repeats + 1; repeat += 1) {
+    const manager = new ObjectManager({ getGameTicks() { return 1; } });
+    const objects = [];
+    for (let i = 0; i < objectCount; i += 1) {
+      objects.push({
+        x: (i * 37) % 2400,
+        y: (i * 17) % 360,
+        drawProperties: null,
+        animation: {
+          frames: [frame],
+          getFrame() { return frame; }
+        }
+      });
+    }
+    manager.addRange(objects);
+    const gameDisplay = {
+      stage: {
+        getGameViewRect() {
+          return fullView ? null : { x: 320, y: 40, w: 640, h: 240 };
+        }
+      },
+      drawFrameFlags() { drawn += 1; }
+    };
+    const start = process.hrtime.bigint();
+    for (let i = 0; i < iterations; i += 1) {
+      manager.render(gameDisplay);
+      candidates += manager._bucketScratch?.length || manager.objects.length;
+    }
+    samples.push(nsToMs(process.hrtime.bigint() - start));
+    manager.dispose();
+  }
+  const summary = summarizeSamples(samples.slice(1), iterations);
+  summary.objects = objectCount;
+  summary.drawn = drawn;
+  summary.candidatesConsidered = candidates;
+  return summary;
+};
+const runObjectCullingBench = ({ iterations, repeats }) => ({
+  viewport100: runObjectCullingScenario({ objectCount: 100, iterations, repeats }),
+  viewport1000: runObjectCullingScenario({ objectCount: 1000, iterations, repeats }),
+  viewport5000: runObjectCullingScenario({ objectCount: 5000, iterations, repeats }),
+  fullBlit1000: runObjectCullingScenario({ objectCount: 1000, iterations, repeats, fullView: true })
+});
+export {
+  makeObjectFrame,
+  runObjectCullingScenario,
+  runObjectCullingBench
+};
\ No newline at end of file
diff --git a/scripts/bench-hotpaths/renderScenarios.js b/scripts/bench-hotpaths/renderScenarios.js
new file mode 100644
index 00000000..99feab73
--- /dev/null
+++ b/scripts/bench-hotpaths/renderScenarios.js
@@ -0,0 +1,335 @@
+import {
+  ActionDiggSystem,
+  DisplayImage,
+  EventHandler,
+  Frame,
+  GameGui,
+  GamepadInputController,
+  HistoryStore,
+  Level,
+  Mask,
+  MidiEventRouter,
+  MidiScheduler,
+  MiniMap,
+  ObjectManager,
+  SkillTypes,
+  Stage,
+  estimateBytes,
+  fileURLToPath,
+  makeCanvas,
+  makeContext,
+  makePalette,
+  measureN,
+  nsToMs,
+  parseArgs,
+  path,
+  percentile,
+  setupRenderEnvironment,
+  summarizeSamples,
+  toNumberOrNaN,
+  toPositiveInt,
+  withGlobalStubs
+} from './shared.js';
+const runDirtyRectBench = ({ iterations, rectsPerIter, repeats }) => withGlobalStubs(() => {
+  setupRenderEnvironment();
+  const stageCanvas = makeCanvas(640, 360);
+  const stage = new Stage(stageCanvas);
+  stage.setGuiEnabled(false);
+  stage.gameImgProps.display.initSize(640, 320);
+  stage.updateStageSize();
+
+  const display = stage.gameImgProps.display;
+  const img = display.getImageData();
+  const width = display.getWidth();
+  const height = display.getHeight();
+  const runOnce = () => {
+    for (let i = 0; i < iterations; i += 1) {
+      for (let r = 0; r < rectsPerIter; r += 1) {
+        const rw = 4 + ((i + r) % 12);
+        const rh = 3 + ((i + (r * 3)) % 10);
+        const x = (i * 31 + r * 47) % Math.max(1, width - rw);
+        const y = (i * 17 + r * 29) % Math.max(1, height - rh);
+        display.markDirtyRect(x, y, rw, rh);
+      }
+      stage.draw(stage.gameImgProps, img);
+    }
+  };
+
+  const measured = measureN(repeats + 1, runOnce);
+  stage.dispose();
+  const summary = summarizeSamples(measured.samplesMs.slice(1), iterations);
+  const allocation = summarizeSamples(measured.allocationSamples.slice(1), iterations);
+  summary.allocBytesAvg = Math.round(allocation.avgMs);
+  summary.allocBytesP95 = Math.round(allocation.p95Ms);
+  summary.allocBytesWorst = Math.round(allocation.worstMs);
+  return summary;
+});
+const runTileCompositionBench = ({ iterations, tilesPerIter, repeats }) => withGlobalStubs(() => {
+  setupRenderEnvironment();
+  const stageCanvas = makeCanvas(960, 540);
+  const stage = new Stage(stageCanvas);
+  stage.setGuiEnabled(false);
+  stage.gameImgProps.display.initSize(960, 512);
+  stage.updateStageSize();
+
+  const display = stage.gameImgProps.display;
+  display.setDirtyTileSize(32);
+  const img = display.getImageData();
+  const width = display.getWidth();
+  const height = display.getHeight();
+  const tileSize = 32;
+
+  const runOnce = () => {
+    for (let i = 0; i < iterations; i += 1) {
+      for (let t = 0; t < tilesPerIter; t += 1) {
+        const x = ((i * 37) + (t * 59)) % Math.max(1, width - tileSize);
+        const y = ((i * 23) + (t * 43)) % Math.max(1, height - tileSize);
+        display.markPresentDirtyRect(x, y, tileSize, tileSize);
+      }
+      stage.draw(stage.gameImgProps, img);
+    }
+  };
+
+  const measured = measureN(repeats + 1, runOnce);
+  stage.dispose();
+  const summary = summarizeSamples(measured.samplesMs.slice(1), iterations);
+  const allocation = summarizeSamples(measured.allocationSamples.slice(1), iterations);
+  summary.allocBytesAvg = Math.round(allocation.avgMs);
+  summary.allocBytesP95 = Math.round(allocation.p95Ms);
+  summary.allocBytesWorst = Math.round(allocation.worstMs);
+  return summary;
+});
+const runMarchingAntBench = ({ iterations, repeats }) => {
+  const stage = {
+    createImage(_display, width, height) {
+      return { width, height, data: new Uint8ClampedArray(width * height * 4) };
+    },
+    redraw() {},
+    setGameViewPointPosition() {}
+  };
+  const display = new DisplayImage(stage);
+  display.initSize(640, 360);
+  display.clear(0);
+
+  const runOnce = () => {
+    for (let i = 0; i < iterations; i += 1) {
+      const offset = i & 15;
+      display.drawMarchingAntRect(32, 24, 220, 120, 4, offset);
+      display.drawMarchingAntRect(300, 32, 96, 52, 3, offset + 2);
+      display.drawMarchingAntRect(120, 180, 300, 100, 5, offset + 4, 0xFF00FFFF, 0xFF0044AA);
+    }
+  };
+
+  const measured = measureN(repeats + 1, runOnce);
+  const summary = summarizeSamples(measured.samplesMs.slice(1), iterations);
+  const allocation = summarizeSamples(measured.allocationSamples.slice(1), iterations);
+  summary.allocBytesAvg = Math.round(allocation.avgMs);
+  summary.allocBytesP95 = Math.round(allocation.p95Ms);
+  summary.allocBytesWorst = Math.round(allocation.worstMs);
+  return summary;
+};
+const makeGuiDisplay = () => ({
+  worldDataSize: { width: 320, height: 40 },
+  stage: { updateStageSize() {} },
+  onMouseDown: new EventHandler(),
+  onMouseUp: new EventHandler(),
+  onMouseRightDown: new EventHandler(),
+  onMouseRightUp: new EventHandler(),
+  onDoubleClick: new EventHandler(),
+  onMouseMove: new EventHandler(),
+  initSize(width, height) { this.worldDataSize = { width, height }; },
+  setBackground() {},
+  redraw() {},
+  drawRect() {},
+  drawFrame() {},
+  drawFrameCovered() {},
+  drawFrameResized() {},
+  drawStippleRect() {},
+  drawMarchingAntRect() {},
+  drawHorizontalLine() {},
+  setPixel() {}
+});
+const runGuiOverlayBench = ({ iterations, repeats }) => withGlobalStubs(() => {
+  setupRenderEnvironment();
+
+  const skills = {
+    onCountChanged: new EventHandler(),
+    onSelectionChanged: new EventHandler(),
+    getSelectedSkill() { return SkillTypes.BASHER; },
+    getSkill() { return 5; },
+    clearSelectedSkill() { return false; }
+  };
+  const timer = {
+    speedFactor: 1,
+    tickIndex: 99,
+    eachGameSecond: new EventHandler(),
+    isRunning() { return false; },
+    getGameTime() { return 0; },
+    getGameLeftTimeString() { return '1-00'; },
+    getGameLeftTimeSString() { return '1-00'; }
+  };
+  const victory = {
+    releaseRate: 20,
+    getMinReleaseRate() { return 1; },
+    getCurrentReleaseRate() { return this.releaseRate; },
+    getMaxReleaseRate() { return 99; },
+    getReleaseCount() { return 25; },
+    getSurvivorPercentage() { return 75; }
+  };
+  const panelSprite = {
+    width: 320,
+    height: 40,
+    getData() { return new Uint8ClampedArray(320 * 40 * 4); }
+  };
+  const sprites = {
+    getPanelSprite() { return panelSprite; },
+    getNumberSpriteEmpty() { return { id: 'empty' }; },
+    getNumberSpriteLeft(v) { return { id: `L${v}` }; },
+    getNumberSpriteRight(v) { return { id: `R${v}` }; },
+    getLetterSprite(ch) { return { id: `G${ch}` }; }
+  };
+  const game = {
+    queueCommand() {},
+    showDebug: false,
+    level: {
+      width: 100,
+      height: 50,
+      mechanics: {},
+      objects: [],
+      screenPositionX: 0,
+      getGroundMaskLayer() { return { countMaskInRect() { return 0; } }; }
+    },
+    gameDisplay: { hoverLemming: null },
+    lemmingManager: { setMiniMap() {} },
+    getLemmingManager() { return { spawnTotal: 20, getLemmings() { return []; } }; }
+  };
+
+  const gui = new GameGui(game, sprites, skills, timer, victory);
+  gui.display = makeGuiDisplay();
+  gui.backgroundChanged = true;
+  gui.gameTimeChanged = true;
+  gui.skillsCountChanged = true;
+  gui.releaseRateChanged = true;
+
+  const runOnce = () => {
+    for (let i = 0; i < iterations; i += 1) {
+      gui.nukePrepared = (i & 1) === 0;
+      gui._hoverPanelIdx = gui.nukePrepared ? 11 : 10;
+      gui.gameTimeChanged = true;
+      gui.render();
+    }
+  };
+
+  const measured = measureN(repeats + 1, runOnce);
+  gui.dispose();
+  const summary = summarizeSamples(measured.samplesMs.slice(1), iterations);
+  const allocation = summarizeSamples(measured.allocationSamples.slice(1), iterations);
+  summary.allocBytesAvg = Math.round(allocation.avgMs);
+  summary.allocBytesP95 = Math.round(allocation.p95Ms);
+  summary.allocBytesWorst = Math.round(allocation.worstMs);
+  return summary;
+});
+const runOverlayPlaneBench = ({ iterations, repeats }) => withGlobalStubs(() => {
+  setupRenderEnvironment();
+  const stageCanvas = makeCanvas(640, 360);
+  const stage = new Stage(stageCanvas);
+  stage.setGuiEnabled(false);
+  stage.gameImgProps.display.initSize(640, 320);
+  stage.updateStageSize();
+  stage.redraw(true);
+
+  const overlay = stage.getGameOverlayDisplay();
+
+  const runOnce = () => {
+    for (let i = 0; i < iterations; i += 1) {
+      const offset = i & 15;
+      overlay.clear(0x00000000);
+      overlay.drawMarchingAntRect(32, 24, 220, 120, 4, offset);
+      overlay.drawMarchingAntRect(300, 40, 96, 52, 3, offset + 2);
+      stage.setGameOverlayVisible(true);
+      stage.redraw();
+    }
+    overlay.clear(0x00000000);
+    stage.setGameOverlayVisible(false);
+    stage.redraw();
+  };
+
+  const measured = measureN(repeats + 1, runOnce);
+  stage.dispose();
+  const summary = summarizeSamples(measured.samplesMs.slice(1), iterations);
+  const allocation = summarizeSamples(measured.allocationSamples.slice(1), iterations);
+  summary.allocBytesAvg = Math.round(allocation.avgMs);
+  summary.allocBytesP95 = Math.round(allocation.p95Ms);
+  summary.allocBytesWorst = Math.round(allocation.worstMs);
+  return summary;
+});
+const makeScaleFrame = (size = 16) => {
+  const width = Math.max(2, Math.trunc(size));
+  const height = width;
+  const pixels = new Uint32Array(width * height);
+  const mask = new Uint8Array(width * height);
+  for (let y = 0; y < height; y += 1) {
+    const row = y * width;
+    for (let x = 0; x < width; x += 1) {
+      const idx = row + x;
+      const r = (x * 17 + y * 9) & 0xff;
+      const g = (x * 11 + y * 13) & 0xff;
+      const b = (x * 7 + y * 19) & 0xff;
+      pixels[idx] = 0xFF000000 | (b << 16) | (g << 8) | r;
+      mask[idx] = ((x + y) % 5) === 0 ? 0 : 1;
+    }
+  }
+  return {
+    width,
+    height,
+    offsetX: 0,
+    offsetY: 0,
+    getBuffer() { return pixels; },
+    getMask() { return mask; },
+    _version: 1
+  };
+};
+const runScaledBlitBench = ({ iterations, repeats }) => {
+  const stage = {
+    createImage(_display, width, height) {
+      return { width, height, data: new Uint8ClampedArray(width * height * 4) };
+    },
+    redraw() {},
+    setGameViewPointPosition() {}
+  };
+  const display = new DisplayImage(stage);
+  display.initSize(640, 360);
+  display.clear(0);
+  const frame = makeScaleFrame(16);
+  const modes = ['nearest', 'xbrz', 'hqx'];
+
+  const runOnce = () => {
+    for (let i = 0; i < iterations; i += 1) {
+      const mode = modes[i % modes.length];
+      const x = (i * 13) % 560;
+      const y = (i * 7) % 280;
+      display._blit(frame, x, y, {
+        size: { width: 64, height: 64 },
+        scaleMode: mode
+      });
+    }
+  };
+
+  const measured = measureN(repeats + 1, runOnce);
+  const summary = summarizeSamples(measured.samplesMs.slice(1), iterations);
+  const allocation = summarizeSamples(measured.allocationSamples.slice(1), iterations);
+  summary.allocBytesAvg = Math.round(allocation.avgMs);
+  summary.allocBytesP95 = Math.round(allocation.p95Ms);
+  summary.allocBytesWorst = Math.round(allocation.worstMs);
+  return summary;
+};
+export {
+  runDirtyRectBench,
+  runTileCompositionBench,
+  runMarchingAntBench,
+  makeGuiDisplay,
+  runGuiOverlayBench,
+  runOverlayPlaneBench,
+  makeScaleFrame,
+  runScaledBlitBench
+};
\ No newline at end of file
diff --git a/scripts/bench-hotpaths/shared.js b/scripts/bench-hotpaths/shared.js
new file mode 100644
index 00000000..298db0a2
--- /dev/null
+++ b/scripts/bench-hotpaths/shared.js
@@ -0,0 +1,228 @@
+import { DisplayImage } from '../../js/render/DisplayImage.js';
+import { Frame } from '../../js/render/Frame.js';
+import { Stage } from '../../js/render/Stage.js';
+import { GameGui } from '../../js/game/GameGui.js';
+import { HistoryStore } from '../../js/game/HistoryStore.js';
+import { SkillTypes } from '../../js/game/SkillTypes.js';
+import { EventHandler } from '../../js/util/EventHandler.js';
+import { Level } from '../../js/level/Level.js';
+import { ObjectManager } from '../../js/level/ObjectManager.js';
+import { ActionDiggSystem } from '../../js/actions/ActionDiggSystem.js';
+import { Mask } from '../../js/render/Mask.js';
+import { MiniMap } from '../../js/render/MiniMap.js';
+import { GamepadInputController } from '../../js/input/GamepadInputController.js';
+import { MidiEventRouter } from '../../js/midi/MidiEventRouter.js';
+import { MidiScheduler } from '../../js/midi/MidiScheduler.js';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const parseArgs = (argv) => {
+  const out = new Map();
+  for (const arg of argv) {
+    if (!arg.startsWith('--')) continue;
+    const [key, value] = arg.slice(2).split('=', 2);
+    out.set(key, value ?? 'true');
+  }
+  return out;
+};
+const toNumberOrNaN = (value) => {
+  try {
+    return Number(value);
+  } catch {
+    return Number.NaN;
+  }
+};
+const toPositiveInt = (value, fallback) => {
+  const parsed = toNumberOrNaN(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  const rounded = Math.trunc(parsed);
+  return rounded > 0 ? rounded : fallback;
+};
+const nsToMs = (value) => toNumberOrNaN(value) / 1e6;
+const percentile = (sorted, p) => {
+  if (!sorted.length) return 0;
+  const clamped = Math.min(1, Math.max(0, p));
+  const index = Math.max(0, Math.min(sorted.length - 1, Math.ceil((sorted.length - 1) * clamped)));
+  return sorted[index];
+};
+const withGlobalStubs = (fn) => {
+  const prevWindow = globalThis.window;
+  const prevDocument = globalThis.document;
+  const prevPerformance = globalThis.performance;
+  const prevLemmings = globalThis.lemmings;
+  const hadLemmings = Object.prototype.hasOwnProperty.call(globalThis, 'lemmings');
+  try {
+    return fn();
+  } finally {
+    globalThis.window = prevWindow;
+    globalThis.document = prevDocument;
+    globalThis.performance = prevPerformance;
+    if (hadLemmings) {
+      globalThis.lemmings = prevLemmings;
+    } else {
+      delete globalThis.lemmings;
+    }
+  }
+};
+const measureN = (iterations, fn) => {
+  const samples = [];
+  const allocationSamples = [];
+  for (let i = 0; i < iterations; i += 1) {
+    const beforeHeap = typeof process?.memoryUsage === 'function'
+      ? process.memoryUsage().heapUsed
+      : NaN;
+    const start = process.hrtime.bigint();
+    fn();
+    samples.push(nsToMs(process.hrtime.bigint() - start));
+    const afterHeap = typeof process?.memoryUsage === 'function'
+      ? process.memoryUsage().heapUsed
+      : NaN;
+    if (Number.isFinite(beforeHeap) && Number.isFinite(afterHeap)) {
+      allocationSamples.push(Math.max(0, afterHeap - beforeHeap));
+    }
+  }
+  const total = samples.reduce((acc, value) => acc + value, 0);
+  return {
+    samplesMs: samples,
+    avgMs: total / samples.length,
+    allocationSamples
+  };
+};
+const summarizeSamples = (samplesMs, iterations) => {
+  const clean = samplesMs
+    .map((value) => toNumberOrNaN(value))
+    .filter((value) => Number.isFinite(value) && value >= 0)
+    .sort((a, b) => a - b);
+  const avg = clean.reduce((acc, value) => acc + value, 0) / Math.max(1, clean.length);
+  const p50 = percentile(clean, 0.5);
+  const p95 = percentile(clean, 0.95);
+  const p99 = percentile(clean, 0.99);
+  const worst = percentile(clean, 1);
+  return {
+    samplesMs: clean.map((value) => Number(value.toFixed(2))),
+    avgMs: Number(avg.toFixed(2)),
+    p50Ms: Number(p50.toFixed(2)),
+    p95Ms: Number(p95.toFixed(2)),
+    p99Ms: Number(p99.toFixed(2)),
+    worstMs: Number(worst.toFixed(2)),
+    usPerIteration: Number(((avg * 1000) / Math.max(1, iterations)).toFixed(4))
+  };
+};
+const estimateBytes = (value, seen = new Set()) => {
+  if (value == null) return 0;
+  if (typeof value === 'string') return value.length * 2;
+  if (typeof value === 'number' || typeof value === 'boolean') return 8;
+  if (ArrayBuffer.isView(value)) return value.byteLength;
+  if (value instanceof ArrayBuffer) return value.byteLength;
+  if (typeof value !== 'object') return 0;
+  if (seen.has(value)) return 0;
+  seen.add(value);
+  let total = 0;
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i += 1) total += estimateBytes(value[i], seen);
+    return total;
+  }
+  for (const entry of Object.values(value)) total += estimateBytes(entry, seen);
+  return total;
+};
+const makePalette = () => ({
+  getR(index) { return (index * 3) & 0xff; },
+  getG(index) { return (index * 5) & 0xff; },
+  getB(index) { return (index * 7) & 0xff; },
+  getColor(index) {
+    const r = this.getR(index);
+    const g = this.getG(index);
+    const b = this.getB(index);
+    return 0xFF000000 | (b << 16) | (g << 8) | r;
+  }
+});
+const makeContext = (canvas) => ({
+  canvas,
+  imageSmoothingEnabled: false,
+  globalAlpha: 1,
+  fillStyle: '#000',
+  strokeStyle: '#000',
+  lineWidth: 1,
+  lineDashOffset: 0,
+  createImageData(width, height) {
+    return { width, height, data: new Uint8ClampedArray(width * height * 4) };
+  },
+  putImageData() {},
+  getImageData(_x, _y, width, height) {
+    return { width, height, data: new Uint8ClampedArray(width * height * 4) };
+  },
+  fillRect() {},
+  drawImage() {},
+  strokeRect() {},
+  setLineDash() {},
+  fillText() {}
+});
+const makeCanvas = (width, height) => {
+  const canvas = {
+    width,
+    height,
+    style: {},
+    addEventListener() {},
+    removeEventListener() {},
+    getContext() { return this._ctx; }
+  };
+  canvas._ctx = makeContext(canvas);
+  return canvas;
+};
+const setupRenderEnvironment = () => {
+  globalThis.performance = {
+    now: () => Date.now(),
+    measure() {}
+  };
+  globalThis.window = {
+    requestAnimationFrame() { return 1; },
+    cancelAnimationFrame() {},
+    addEventListener() {},
+    removeEventListener() {}
+  };
+  globalThis.document = {
+    createElement() { return makeCanvas(16, 16); }
+  };
+  globalThis.lemmings = {
+    bench: false,
+    bench2: false,
+    benchReverse: false,
+    benchSequence: false,
+    performanceAPI: false,
+    perfMetrics: false,
+    endless: false
+  };
+};
+
+export {
+  ActionDiggSystem,
+  DisplayImage,
+  EventHandler,
+  Frame,
+  GameGui,
+  GamepadInputController,
+  HistoryStore,
+  Level,
+  Mask,
+  MidiEventRouter,
+  MidiScheduler,
+  MiniMap,
+  ObjectManager,
+  SkillTypes,
+  Stage,
+  estimateBytes,
+  fileURLToPath,
+  makeCanvas,
+  makeContext,
+  makePalette,
+  measureN,
+  nsToMs,
+  parseArgs,
+  path,
+  percentile,
+  setupRenderEnvironment,
+  summarizeSamples,
+  toNumberOrNaN,
+  toPositiveInt,
+  withGlobalStubs
+};
diff --git a/scripts/bench-hotpaths/terrainScenarios.js b/scripts/bench-hotpaths/terrainScenarios.js
new file mode 100644
index 00000000..09552270
--- /dev/null
+++ b/scripts/bench-hotpaths/terrainScenarios.js
@@ -0,0 +1,194 @@
+import {
+  ActionDiggSystem,
+  DisplayImage,
+  EventHandler,
+  Frame,
+  GameGui,
+  GamepadInputController,
+  HistoryStore,
+  Level,
+  Mask,
+  MidiEventRouter,
+  MidiScheduler,
+  MiniMap,
+  ObjectManager,
+  SkillTypes,
+  Stage,
+  estimateBytes,
+  fileURLToPath,
+  makeCanvas,
+  makeContext,
+  makePalette,
+  measureN,
+  nsToMs,
+  parseArgs,
+  path,
+  percentile,
+  setupRenderEnvironment,
+  summarizeSamples,
+  toNumberOrNaN,
+  toPositiveInt,
+  withGlobalStubs
+} from './shared.js';
+const makeBenchMask = (width = 16, height = 12, offsetX = -8, offsetY = -6) => {
+  const mask = new Mask(null, width, height, offsetX, offsetY);
+  mask.data = new Int8Array(width * height);
+  for (let y = 0; y < height; y += 1) {
+    for (let x = 0; x < width; x += 1) {
+      mask.data[(y * width) + x] = ((x + y) % 5) === 0 ? 0 : 1;
+    }
+  }
+  return mask;
+};
+const makeTerrainLevel = ({ steel = false, arrows = false, runtimeStats = null } = {}) => {
+  const width = 320;
+  const height = 160;
+  const level = new Level(width, height);
+  level.setPalettes(makePalette(), makePalette());
+  const img = new Uint8ClampedArray(width * height * 4);
+  for (let i = 0; i < width * height; i += 1) {
+    level.groundMask.mask[i] = 1;
+    const o = i * 4;
+    img[o] = 64 + (i & 63);
+    img[o + 1] = 120;
+    img[o + 2] = 32;
+    img[o + 3] = 255;
+  }
+  level.setGroundImage(img);
+  level.groundMask.mask.fill(1);
+  if (steel) {
+    for (let y = 20; y < 140; y += 1) {
+      for (let x = 30; x < 290; x += 1) {
+        if (((x + y) & 3) !== 0) level.steelMask.setMaskAt(x, y);
+      }
+    }
+  }
+  if (arrows) {
+    level.setArrowAreas([{ x: 20, y: 10, width: 280, height: 130, direction: 1 }]);
+  }
+  if (runtimeStats) {
+    level.setRuntime({
+      history: {
+        recordGroundChange() { runtimeStats.historyRecords += 1; }
+      },
+      miniMap: {
+        invalidateRegion() { runtimeStats.minimapInvalidations += 1; },
+        onGroundChanged() { runtimeStats.minimapPixelUpdates += 1; }
+      }
+    });
+  }
+  return level;
+};
+const runTerrainCheckScenario = ({ iterations, repeats, kind }) => {
+  const mask = makeBenchMask();
+  const samples = [];
+  let truthy = 0;
+  for (let repeat = 0; repeat < repeats + 1; repeat += 1) {
+    const level = makeTerrainLevel({
+      steel: kind === 'denseSteel',
+      arrows: kind === 'arrow'
+    });
+    const start = process.hrtime.bigint();
+    let hits = 0;
+    for (let i = 0; i < iterations; i += 1) {
+      const x = 12 + ((i * 13) % 280);
+      const y = 10 + ((i * 7) % 130);
+      if (kind === 'arrow') {
+        if (level.hasArrowUnderMask(mask, x, y, 0)) hits += 1;
+      } else if (level.hasSteelUnderMask(mask, x, y)) {
+        hits += 1;
+      }
+    }
+    samples.push(nsToMs(process.hrtime.bigint() - start));
+    truthy = hits;
+  }
+  const summary = summarizeSamples(samples.slice(1), iterations);
+  summary.truthy = truthy;
+  return summary;
+};
+const runTerrainClearScenario = ({ iterations, repeats, noop = false }) => {
+  const mask = makeBenchMask(18, 14, -9, -7);
+  const samples = [];
+  let metrics = null;
+  for (let repeat = 0; repeat < repeats + 1; repeat += 1) {
+    const runtimeStats = {
+      historyRecords: 0,
+      minimapInvalidations: 0,
+      minimapPixelUpdates: 0
+    };
+    const level = makeTerrainLevel({ runtimeStats });
+    if (noop) {
+      level.clearGroundWithMaskCount(mask, 80, 60);
+    }
+    let removed = 0;
+    const start = process.hrtime.bigint();
+    for (let i = 0; i < iterations; i += 1) {
+      const x = noop ? 80 : 20 + ((i * 19) % 260);
+      const y = noop ? 60 : 12 + ((i * 11) % 130);
+      removed += level.clearGroundWithMaskCount(mask, x, y);
+    }
+    samples.push(nsToMs(process.hrtime.bigint() - start));
+    metrics = {
+      removedPixels: removed,
+      historyRecords: runtimeStats.historyRecords,
+      minimapInvalidations: runtimeStats.minimapInvalidations,
+      minimapPixelUpdates: runtimeStats.minimapPixelUpdates,
+      dirtyRectCount: level._groundDirtyRects?.length ?? 0,
+      dirtyTileCount: level._groundDirtyTiles?.size ?? 0
+    };
+  }
+  return {
+    ...summarizeSamples(samples.slice(1), iterations),
+    ...metrics
+  };
+};
+const runDigRowScenario = ({ iterations, repeats }) => {
+  const samples = [];
+  let metrics = null;
+  for (let repeat = 0; repeat < repeats + 1; repeat += 1) {
+    const runtimeStats = {
+      historyRecords: 0,
+      minimapInvalidations: 0,
+      minimapPixelUpdates: 0
+    };
+    const level = makeTerrainLevel({ runtimeStats });
+    const dig = new ActionDiggSystem({ getAnimation() { return null; } });
+    const lem = { id: 1, x: 40, y: 40 };
+    let removedRows = 0;
+    const start = process.hrtime.bigint();
+    for (let i = 0; i < iterations; i += 1) {
+      lem.x = 10 + ((i * 7) % 280);
+      const y = 8 + ((i * 3) % 140);
+      if (dig.digRow(level, lem, y)) removedRows += 1;
+    }
+    samples.push(nsToMs(process.hrtime.bigint() - start));
+    metrics = {
+      rowsWithRemoval: removedRows,
+      historyRecords: runtimeStats.historyRecords,
+      minimapInvalidations: runtimeStats.minimapInvalidations,
+      minimapPixelUpdates: runtimeStats.minimapPixelUpdates,
+      dirtyRectCount: level._groundDirtyRects?.length ?? 0,
+      dirtyTileCount: level._groundDirtyTiles?.size ?? 0
+    };
+  }
+  return {
+    ...summarizeSamples(samples.slice(1), iterations),
+    ...metrics
+  };
+};
+const runTerrainMaskBench = ({ iterations, clearIterations, digIterations, repeats }) => ({
+  noSteelSteelCheck: runTerrainCheckScenario({ iterations, repeats, kind: 'noSteel' }),
+  denseSteelCheck: runTerrainCheckScenario({ iterations, repeats, kind: 'denseSteel' }),
+  arrowCheck: runTerrainCheckScenario({ iterations, repeats, kind: 'arrow' }),
+  clearGroundWithMaskCount: runTerrainClearScenario({ iterations: clearIterations, repeats }),
+  repeatedNoopClear: runTerrainClearScenario({ iterations: clearIterations, repeats, noop: true }),
+  digRow: runDigRowScenario({ iterations: digIterations, repeats })
+});
+export {
+  makeBenchMask,
+  makeTerrainLevel,
+  runTerrainCheckScenario,
+  runTerrainClearScenario,
+  runDigRowScenario,
+  runTerrainMaskBench
+};
\ No newline at end of file
diff --git a/scripts/bench-long-session.js b/scripts/bench-long-session.js
new file mode 100644
index 00000000..20bbe11a
--- /dev/null
+++ b/scripts/bench-long-session.js
@@ -0,0 +1,541 @@
+import { chromium } from '@playwright/test';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DEFAULT_BASE_URL = 'https://localhost:8080/?e2e=1';
+
+const toNumberOrNaN = (value) => {
+  try {
+    return Number(value);
+  } catch {
+    return Number.NaN;
+  }
+};
+
+/**
+ * @param {string[]} argv
+ * @returns {Map<string, string>}
+ */
+const parseArgs = (argv) => {
+  const out = new Map();
+  for (const arg of argv) {
+    if (!arg.startsWith('--')) continue;
+    const [key, value] = arg.slice(2).split('=', 2);
+    out.set(key, value ?? 'true');
+  }
+  return out;
+};
+
+/**
+ * @param {unknown} value
+ * @param {number} fallback
+ * @returns {number}
+ */
+const toPositiveNumber = (value, fallback) => {
+  const parsed = toNumberOrNaN(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+};
+
+/**
+ * @param {unknown} value
+ * @param {number} fallback
+ * @returns {number}
+ */
+const toNonNegativeNumber = (value, fallback) => {
+  const parsed = toNumberOrNaN(value);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
+};
+
+/**
+ * @param {unknown} value
+ * @param {number} fallback
+ * @returns {number}
+ */
+const toFiniteNumber = (value, fallback) => {
+  const parsed = toNumberOrNaN(value);
+  return Number.isFinite(parsed) ? parsed : fallback;
+};
+
+/**
+ * @param {unknown} value
+ * @param {boolean} fallback
+ * @returns {boolean}
+ */
+const toBoolean = (value, fallback) => {
+  if (value == null) return fallback;
+  const normalized = String(value).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) return true;
+  if (['0', 'false', 'no', 'off'].includes(normalized)) return false;
+  return fallback;
+};
+
+const withTimeout = async (promise, timeoutMs, label) => {
+  let timeoutId = null;
+  const timeoutPromise = new Promise((_, reject) => {
+    timeoutId = setTimeout(() => {
+      reject(new Error(`${label} timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([promise, timeoutPromise]);
+  } finally {
+    if (timeoutId != null) clearTimeout(timeoutId);
+  }
+};
+
+const closeQuietly = async (target, label) => {
+  if (!target || typeof target.close !== 'function') return;
+  try {
+    await withTimeout(target.close(), 5000, label);
+  } catch {
+    // best-effort shutdown
+  }
+};
+
+const PROFILE_PRESETS = Object.freeze({
+  smoke: Object.freeze({
+    durationMs: 15000,
+    sampleMs: 1000,
+    replayChecks: 2,
+    maxHeapGrowthBytes: 128 * 1024 * 1024,
+    maxHeapChurnBytes: 256 * 1024 * 1024,
+    maxSoundQueueRatio: 1.0,
+    maxSoundQueueGrowth: 128,
+    minHistorySpanTicks: 2000,
+    maxTriggerDrift: 0,
+    maxRuntimeMs: 90000
+  }),
+  default: Object.freeze({
+    durationMs: 90000,
+    sampleMs: 1000,
+    replayChecks: 6,
+    maxHeapGrowthBytes: 256 * 1024 * 1024,
+    maxHeapChurnBytes: 768 * 1024 * 1024,
+    maxSoundQueueRatio: 1.0,
+    maxSoundQueueGrowth: 256,
+    minHistorySpanTicks: 8000,
+    maxTriggerDrift: 0,
+    maxRuntimeMs: 300000
+  }),
+  soak: Object.freeze({
+    durationMs: 300000,
+    sampleMs: 1000,
+    replayChecks: 12,
+    maxHeapGrowthBytes: 512 * 1024 * 1024,
+    maxHeapChurnBytes: 1536 * 1024 * 1024,
+    maxSoundQueueRatio: 1.0,
+    maxSoundQueueGrowth: 512,
+    minHistorySpanTicks: 12000,
+    maxTriggerDrift: 0,
+    maxRuntimeMs: 420000
+  })
+});
+
+/**
+ * @param {Partial<{
+ *   elapsedMs: number,
+ *   tickIndex: number,
+ *   historySpanTicks: number,
+ *   coldBlockCount: number,
+ *   soundQueued: number,
+ *   soundQueueLimit: number,
+ *   triggerCount: number,
+ *   heapUsedBytes: number
+ * }>} sample
+ * @returns {{
+ *   elapsedMs: number,
+ *   tickIndex: number,
+ *   historySpanTicks: number,
+ *   coldBlockCount: number,
+ *   soundQueued: number,
+ *   soundQueueLimit: number,
+ *   triggerCount: number,
+ *   heapUsedBytes: number
+ * }}
+ */
+const normalizeLongSessionSample = (sample) => ({
+  elapsedMs: toNonNegativeNumber(sample?.elapsedMs, 0),
+  tickIndex: toFiniteNumber(sample?.tickIndex, 0),
+  historySpanTicks: toNonNegativeNumber(sample?.historySpanTicks, 0),
+  coldBlockCount: toNonNegativeNumber(sample?.coldBlockCount, 0),
+  soundQueued: toNonNegativeNumber(sample?.soundQueued, 0),
+  soundQueueLimit: toNonNegativeNumber(sample?.soundQueueLimit, 0),
+  triggerCount: toNonNegativeNumber(sample?.triggerCount, 0),
+  heapUsedBytes: toNonNegativeNumber(sample?.heapUsedBytes, 0)
+});
+
+/**
+ * @param {{
+ *   samples?: Array<{
+ *     tickIndex?: number,
+ *     heapUsedBytes?: number,
+ *     soundQueued?: number,
+ *     soundQueueLimit?: number,
+ *     historySpanTicks?: number,
+ *     triggerCount?: number
+ *   }>,
+ *   replayChecks?: Array<{hashMatch?: boolean}>,
+ *   thresholds?: {
+ *     maxHeapGrowthBytes?: number,
+ *     maxHeapChurnBytes?: number,
+ *     maxSoundQueueRatio?: number,
+ *     maxSoundQueueGrowth?: number,
+ *     minHistorySpanTicks?: number,
+ *     maxTriggerDrift?: number
+ *   }
+ * }} [options]
+ * @returns {{
+ *   metrics: {
+ *     sampleCount: number,
+ *     replayCheckCount: number,
+ *     tickProgress: number,
+ *     heapGrowthBytes: number,
+ *     heapChurnBytes: number,
+ *     maxSoundQueueRatio: number,
+ *     soundQueueGrowth: number,
+ *     historySpanEnd: number,
+ *     triggerDrift: number,
+ *     replayMismatchCount: number
+ *   },
+ *   failures: string[]
+ * }}
+ */
+const evaluateLongSessionGates = ({
+  samples = [],
+  replayChecks = [],
+  thresholds = PROFILE_PRESETS.smoke
+} = {}) => {
+  const clean = Array.isArray(samples) ? samples.filter(Boolean) : [];
+  const replay = Array.isArray(replayChecks) ? replayChecks.filter(Boolean) : [];
+  const first = clean[0] || null;
+  const last = clean[clean.length - 1] || null;
+  const heapStart = toNumberOrNaN(first?.heapUsedBytes || 0);
+  const heapEnd = toNumberOrNaN(last?.heapUsedBytes || 0);
+  const heapGrowthBytes = (Number.isFinite(heapStart) && Number.isFinite(heapEnd))
+    ? Math.max(0, heapEnd - heapStart)
+    : 0;
+  const heapSeries = clean
+    .map((sample) => toNumberOrNaN(sample.heapUsedBytes || 0))
+    .filter((value) => Number.isFinite(value) && value >= 0);
+  let heapChurnBytes = 0;
+  for (let i = 1; i < heapSeries.length; i += 1) {
+    heapChurnBytes += Math.abs(heapSeries[i] - heapSeries[i - 1]);
+  }
+
+  const queueRatios = clean
+    .map((sample) => {
+      const limit = toNumberOrNaN(sample.soundQueueLimit || 0);
+      const queued = toNumberOrNaN(sample.soundQueued || 0);
+      if (!Number.isFinite(limit) || limit <= 0) return 0;
+      return queued / limit;
+    })
+    .filter((value) => Number.isFinite(value) && value >= 0);
+  const maxSoundQueueRatio = queueRatios.length ? Math.max(...queueRatios) : 0;
+  const queueStart = toNumberOrNaN(first?.soundQueued || 0);
+  const queueEnd = toNumberOrNaN(last?.soundQueued || 0);
+  const soundQueueGrowth = Number.isFinite(queueStart) && Number.isFinite(queueEnd)
+    ? Math.max(0, queueEnd - queueStart)
+    : 0;
+
+  const tickSeries = clean
+    .map((sample) => toNumberOrNaN(sample.tickIndex || 0))
+    .filter((value) => Number.isFinite(value));
+  const tickProgress = tickSeries.length > 1
+    ? tickSeries[tickSeries.length - 1] - tickSeries[0]
+    : 0;
+
+  const triggerStart = toNumberOrNaN(first?.triggerCount || 0);
+  const triggerEnd = toNumberOrNaN(last?.triggerCount || 0);
+  const triggerDrift = Number.isFinite(triggerStart) && Number.isFinite(triggerEnd)
+    ? Math.abs(triggerEnd - triggerStart)
+    : 0;
+
+  const historySpanEnd = toNumberOrNaN(last?.historySpanTicks || 0);
+  const replayMismatchCount = replay.filter(check => check.hashMatch === false).length;
+
+  const failures = [];
+  if (tickProgress <= 0) {
+    failures.push('tick_progress_stalled');
+  }
+  if (heapGrowthBytes > toNumberOrNaN(thresholds.maxHeapGrowthBytes || 0)) {
+    failures.push('heap_growth_exceeded');
+  }
+  if (heapChurnBytes > toNumberOrNaN(thresholds.maxHeapChurnBytes || 0)) {
+    failures.push('heap_churn_exceeded');
+  }
+  if (maxSoundQueueRatio > toNumberOrNaN(thresholds.maxSoundQueueRatio || 1)) {
+    failures.push('sound_queue_ratio_exceeded');
+  }
+  if (soundQueueGrowth > toNumberOrNaN(thresholds.maxSoundQueueGrowth || 0)) {
+    failures.push('sound_queue_growth_exceeded');
+  }
+  if (historySpanEnd < toNumberOrNaN(thresholds.minHistorySpanTicks || 0)) {
+    failures.push('history_span_below_minimum');
+  }
+  if (triggerDrift > toNumberOrNaN(thresholds.maxTriggerDrift || 0)) {
+    failures.push('trigger_count_drift_detected');
+  }
+  if (replayMismatchCount > 0) {
+    failures.push('replay_hash_mismatch');
+  }
+
+  return {
+    metrics: {
+      sampleCount: clean.length,
+      replayCheckCount: replay.length,
+      tickProgress,
+      heapGrowthBytes,
+      heapChurnBytes,
+      maxSoundQueueRatio,
+      soundQueueGrowth,
+      historySpanEnd,
+      triggerDrift,
+      replayMismatchCount
+    },
+    failures
+  };
+};
+
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+
+/**
+ * @param {string} raw
+ * @returns {string}
+ */
+const buildBenchUrl = (raw) => {
+  /** @type {URL} */
+  let url;
+  try {
+    url = new URL(raw || DEFAULT_BASE_URL);
+  } catch {
+    url = new URL(DEFAULT_BASE_URL);
+  }
+  url.searchParams.set('e2e', '1');
+  if (!url.searchParams.has('profile')) {
+    url.searchParams.set('profile', 'perf');
+  }
+  return url.toString();
+};
+
+const isMainModule = (() => {
+  try {
+    return path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+})();
+
+const run = async () => {
+  const args = parseArgs(process.argv.slice(2));
+  const baseUrl = args.get('url') || process.env.LEMMINGS_BENCH_URL || DEFAULT_BASE_URL;
+  const requestedProfile = (
+    args.get('profile')
+    || process.env.LONG_SESSION_PROFILE
+    || (args.has('soak') ? 'soak' : args.has('smoke') ? 'smoke' : 'smoke')
+  ).toLowerCase();
+  const preset = PROFILE_PRESETS[requestedProfile] || PROFILE_PRESETS.smoke;
+  const durationMs = toPositiveNumber(args.get('duration') || process.env.LONG_SESSION_DURATION_MS, preset.durationMs);
+  const sampleMs = toPositiveNumber(args.get('sample') || process.env.LONG_SESSION_SAMPLE_MS, preset.sampleMs);
+  const replayChecksTarget = Math.max(1, Math.trunc(toPositiveNumber(
+    args.get('replayChecks') || process.env.LONG_SESSION_REPLAY_CHECKS,
+    preset.replayChecks
+  )));
+  const opTimeoutMs = toPositiveNumber(args.get('opTimeout') || process.env.LONG_SESSION_OP_TIMEOUT_MS, 30000);
+  const maxRuntimeMs = toPositiveNumber(args.get('maxRuntime') || process.env.LONG_SESSION_MAX_RUNTIME_MS, preset.maxRuntimeMs);
+  const headless = toBoolean(args.get('headless') || process.env.LONG_SESSION_HEADLESS, true);
+
+  const runStart = Date.now();
+  const assertRuntimeBudget = (phase) => {
+    const elapsed = Date.now() - runStart;
+    if (elapsed > maxRuntimeMs) {
+      throw new Error(`Long-session bench exceeded max runtime (${maxRuntimeMs}ms) during ${phase}.`);
+    }
+  };
+
+  let browser = null;
+  let context = null;
+  let page = null;
+  try {
+    browser = await withTimeout(chromium.launch({
+      headless,
+      args: ['--allow-insecure-localhost', '--ignore-certificate-errors']
+    }), opTimeoutMs, 'chromium.launch');
+    context = await withTimeout(
+      browser.newContext({ ignoreHTTPSErrors: true }),
+      opTimeoutMs,
+      'browser.newContext'
+    );
+    page = await withTimeout(context.newPage(), opTimeoutMs, 'context.newPage');
+    page.setDefaultTimeout(opTimeoutMs);
+    await withTimeout(
+      page.goto(buildBenchUrl(baseUrl), { waitUntil: 'domcontentloaded' }),
+      opTimeoutMs,
+      'page.goto'
+    );
+    await withTimeout(
+      page.waitForFunction(() => window.__E2E__?.getState?.().ready === true),
+      opTimeoutMs,
+      'waitForReady'
+    );
+
+    await withTimeout(page.evaluate(() => window.__E2E__.resume()), opTimeoutMs, 'resume');
+    const samples = [];
+    const replayChecks = [];
+    const replayEveryMs = Math.max(sampleMs, Math.trunc(durationMs / replayChecksTarget));
+    let lastReplayAtMs = -Infinity;
+    const start = Date.now();
+
+    while (Date.now() - start < durationMs) {
+      assertRuntimeBudget('sampling');
+      const elapsedMs = Date.now() - start;
+      const rawSample = await withTimeout(page.evaluate((elapsed) => {
+        const state = window.__E2E__?.getState?.() || {};
+        const game = state.game || {};
+        const history = game.history || {};
+        const sound = game.soundEvents || {};
+        const triggers = game.triggers || {};
+        const memory = typeof performance !== 'undefined' ? performance.memory : null;
+        return {
+          elapsedMs: Number(elapsed || 0),
+          tickIndex: Number(game.timer?.tickIndex || 0),
+          historySpanTicks: Number(history.spanTicks || 0),
+          coldBlockCount: Number(history.coldBlockCount || 0),
+          soundQueued: Number(sound.queuedCount || 0),
+          soundQueueLimit: Number(sound.queueLimit || 0),
+          triggerCount: Number(triggers.totalCount || 0),
+          heapUsedBytes: Number(memory?.usedJSHeapSize || 0)
+        };
+      }, elapsedMs), opTimeoutMs, 'sampleState');
+      const sample = normalizeLongSessionSample(rawSample);
+      samples.push(sample);
+
+      if (elapsedMs - lastReplayAtMs >= replayEveryMs) {
+        lastReplayAtMs = elapsedMs;
+        const replayCheck = await withTimeout(page.evaluate(() => {
+          const api = window.__E2E__;
+          const state = api?.getState?.();
+          const history = state?.game?.history;
+          if (!api?.getDelta || !history) {
+            return { hashMatch: true, hashBefore: null, hashAfter: null, checked: false };
+          }
+          const minTick = Number.isFinite(history.minTick) ? Math.trunc(history.minTick) : 0;
+          const maxTick = Number.isFinite(history.maxTick) ? Math.trunc(history.maxTick) : minTick;
+          const current = Number.isFinite(state?.game?.timer?.tickIndex)
+            ? Math.trunc(state.game.timer.tickIndex)
+            : maxTick;
+          const hashFn = () => {
+            let hash = 2166136261;
+            const pushByte = (value) => {
+              hash ^= value & 0xff;
+              hash = Math.imul(hash, 16777619);
+            };
+            const pushAscii = (value) => {
+              const text = String(value);
+              for (let i = 0; i < text.length; i += 1) {
+                pushByte(text.charCodeAt(i));
+              }
+              pushByte(124);
+            };
+            for (let tick = minTick; tick <= maxTick; tick += 1) {
+              const delta = api.getDelta(tick);
+              if (!delta) continue;
+              pushAscii(tick);
+              pushAscii(delta.flags ?? 0);
+              pushAscii(delta.soundEvents?.length || 0);
+              pushAscii(delta.minimapDeaths?.length || 0);
+              pushByte(10);
+            }
+            return (hash >>> 0).toString(16).padStart(8, '0');
+          };
+          const hashBefore = hashFn();
+          const span = Math.max(1, maxTick - minTick);
+          const target = Math.max(minTick, current - Math.max(1, Math.trunc(span * 0.25)));
+          api.seek(target);
+          api.seek(current);
+          const hashAfter = hashFn();
+          return {
+            checked: true,
+            hashBefore,
+            hashAfter,
+            hashMatch: hashBefore === hashAfter
+          };
+        }), opTimeoutMs, 'replayCheck');
+        replayChecks.push(replayCheck);
+      }
+
+      await sleep(sampleMs);
+    }
+
+    await withTimeout(page.evaluate(() => window.__E2E__.pause()), opTimeoutMs, 'pause');
+
+    const thresholds = {
+      ...preset,
+      maxHeapGrowthBytes: toPositiveNumber(
+        args.get('maxHeapGrowthBytes') || process.env.LONG_SESSION_MAX_HEAP_GROWTH_BYTES,
+        preset.maxHeapGrowthBytes
+      ),
+      maxHeapChurnBytes: toPositiveNumber(
+        args.get('maxHeapChurnBytes') || process.env.LONG_SESSION_MAX_HEAP_CHURN_BYTES,
+        preset.maxHeapChurnBytes
+      ),
+      maxSoundQueueRatio: toNonNegativeNumber(
+        args.get('maxSoundQueueRatio') || process.env.LONG_SESSION_MAX_SOUND_QUEUE_RATIO,
+        preset.maxSoundQueueRatio
+      ),
+      maxSoundQueueGrowth: toNonNegativeNumber(
+        args.get('maxSoundQueueGrowth') || process.env.LONG_SESSION_MAX_SOUND_QUEUE_GROWTH,
+        preset.maxSoundQueueGrowth
+      ),
+      minHistorySpanTicks: toPositiveNumber(
+        args.get('minHistorySpanTicks') || process.env.LONG_SESSION_MIN_HISTORY_SPAN_TICKS,
+        preset.minHistorySpanTicks
+      ),
+      maxTriggerDrift: toNonNegativeNumber(
+        args.get('maxTriggerDrift') || process.env.LONG_SESSION_MAX_TRIGGER_DRIFT,
+        preset.maxTriggerDrift
+      )
+    };
+    const evaluation = evaluateLongSessionGates({
+      samples,
+      replayChecks,
+      thresholds
+    });
+    const summary = {
+      profile: requestedProfile,
+      url: buildBenchUrl(baseUrl),
+      durationMs,
+      sampleMs,
+      thresholds,
+      metrics: evaluation.metrics,
+      failures: evaluation.failures,
+      samples,
+      replayChecks
+    };
+    console.log(JSON.stringify(summary, null, 2));
+    if (evaluation.failures.length) {
+      process.exitCode = 1;
+    }
+  } finally {
+    await closeQuietly(page, 'page.close');
+    await closeQuietly(context, 'context.close');
+    await closeQuietly(browser, 'browser.close');
+  }
+};
+
+if (isMainModule) {
+  run().catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+  });
+}
+
+export {
+  buildBenchUrl,
+  DEFAULT_BASE_URL,
+  PROFILE_PRESETS,
+  evaluateLongSessionGates,
+  normalizeLongSessionSample,
+  toBoolean,
+  toNonNegativeNumber,
+  toPositiveNumber
+};
diff --git a/scripts/bench-performance.js b/scripts/bench-performance.js
index 74a9f27a..d68125b1 100644
--- a/scripts/bench-performance.js
+++ b/scripts/bench-performance.js
@@ -1,5 +1,70 @@
 import { chromium } from '@playwright/test';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
+const DEFAULT_BASE_URL = 'https://localhost:8080/?e2e=1';
+const VALID_MODES = new Set(['sequence', 'bench', 'reverse']);
+
+const BENCH_PROFILES = {
+  default: {
+    mode: 'sequence',
+    durationMs: 60000,
+    sampleMs: 1000,
+    entrances: 50,
+    warmupMs: 5000,
+    maxRuntimeMs: 150000,
+    query: { profile: 'perf', performanceAPI: 'true', perfOverlay: 'true' }
+  },
+  stress: {
+    mode: 'bench',
+    durationMs: 90000,
+    sampleMs: 500,
+    entrances: 180,
+    warmupMs: 10000,
+    maxRuntimeMs: 220000,
+    query: { profile: 'perf', performanceAPI: 'true', perfOverlay: 'true', bench2: 'true' }
+  },
+  reverse: {
+    mode: 'reverse',
+    durationMs: 90000,
+    sampleMs: 500,
+    entrances: 160,
+    warmupMs: 10000,
+    maxRuntimeMs: 220000,
+    query: { profile: 'perf', performanceAPI: 'true', perfOverlay: 'true', benchReverse: 'true' }
+  },
+  smoke: {
+    mode: 'bench',
+    durationMs: 6000,
+    sampleMs: 500,
+    entrances: 30,
+    warmupMs: 1500,
+    maxRuntimeMs: 25000,
+    query: { profile: 'perf', performanceAPI: 'true', perfOverlay: 'false' }
+  },
+  soak: {
+    mode: 'bench',
+    durationMs: 180000,
+    sampleMs: 500,
+    entrances: 220,
+    warmupMs: 10000,
+    maxRuntimeMs: 300000,
+    query: { profile: 'perf', performanceAPI: 'true', perfOverlay: 'true', bench2: 'true' }
+  }
+};
+
+const toNumberOrNaN = (value) => {
+  try {
+    return Number(value);
+  } catch {
+    return Number.NaN;
+  }
+};
+
+/**
+ * @param {string[]} argv
+ * @returns {Map<string, string>}
+ */
 const parseArgs = (argv) => {
   const out = new Map();
   for (const arg of argv) {
@@ -10,74 +75,422 @@ const parseArgs = (argv) => {
   return out;
 };
 
-const args = parseArgs(process.argv.slice(2));
-const baseUrl = args.get('url') || process.env.LEMMINGS_BENCH_URL || 'https://localhost:8080/?e2e=1';
-const durationMs = Number(args.get('duration') || process.env.BENCH_DURATION_MS || 60000);
-const sampleMs = Number(args.get('sample') || process.env.BENCH_SAMPLE_MS || 1000);
-const mode = (args.get('mode') || process.env.BENCH_MODE || 'sequence').toLowerCase();
-const entrances = Number(args.get('entrances') || process.env.BENCH_ENTRANCES || 50);
-const headless = (args.get('headless') || process.env.BENCH_HEADLESS || 'true') !== 'false';
+/**
+ * @param {unknown} value
+ * @param {number} fallback
+ * @returns {number}
+ */
+const toPositiveNumber = (value, fallback) => {
+  const parsed = toNumberOrNaN(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+};
 
-const buildUrl = (raw) => {
-  const url = new URL(raw);
+/**
+ * @param {unknown} value
+ * @param {boolean} fallback
+ * @returns {boolean}
+ */
+const toBoolean = (value, fallback) => {
+  if (value == null) return fallback;
+  const normalized = String(value).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) return true;
+  if (['0', 'false', 'no', 'off'].includes(normalized)) return false;
+  return fallback;
+};
+
+const withTimeout = async (promise, timeoutMs, label) => {
+  let timeoutId = null;
+  const timeoutPromise = new Promise((_, reject) => {
+    timeoutId = setTimeout(() => {
+      reject(new Error(`${label} timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([promise, timeoutPromise]);
+  } finally {
+    if (timeoutId != null) clearTimeout(timeoutId);
+  }
+};
+
+const closeQuietly = async (target, label) => {
+  if (!target || typeof target.close !== 'function') return;
+  try {
+    await withTimeout(target.close(), 5000, label);
+  } catch {
+    // best-effort shutdown
+  }
+};
+
+/**
+ * @param {string} raw
+ * @param {Record<string, string>} [query]
+ * @param {string} [fallback]
+ * @returns {string}
+ */
+const buildUrl = (raw, query = {}, fallback = DEFAULT_BASE_URL) => {
+  /** @type {URL} */
+  let url;
+  try {
+    url = new URL(raw || fallback);
+  } catch {
+    url = new URL(fallback);
+  }
   url.searchParams.set('e2e', '1');
+  for (const [key, value] of Object.entries(query || {})) {
+    if (!url.searchParams.has(key)) {
+      url.searchParams.set(key, value);
+    }
+  }
   return url.toString();
 };
 
+/**
+ * @param {{
+ *   argv?: string[],
+ *   env?: Record<string, string | undefined>,
+ *   warn?: (message: string) => void
+ * }} [options]
+ */
+const createPerformanceBenchConfig = (
+  {
+    argv = process.argv.slice(2),
+    env = process.env,
+    warn = console.warn
+  } = {}
+) => {
+  const args = parseArgs(argv);
+  const baseUrl = args.get('url') || env.LEMMINGS_BENCH_URL || DEFAULT_BASE_URL;
+  const smokeRequested = args.has('smoke') || env.BENCH_SMOKE === '1';
+  const soakRequested = args.has('soak') || env.BENCH_SOAK === '1';
+  const requestedProfile = (
+    args.get('profile') ||
+    env.BENCH_PROFILE ||
+    (soakRequested ? 'soak' : smokeRequested ? 'smoke' : 'smoke')
+  ).toLowerCase();
+  const profileExplicit = args.has('profile')
+    || !!env.BENCH_PROFILE
+    || smokeRequested
+    || soakRequested;
+  const profile = BENCH_PROFILES[requestedProfile] || BENCH_PROFILES.smoke;
+  if (!profileExplicit) {
+    warn?.('[bench-performance] No explicit profile selected; defaulting to smoke. Use --profile=default for longer runs.');
+  } else if (!BENCH_PROFILES[requestedProfile]) {
+    warn?.(`[bench-performance] Unknown profile "${requestedProfile}", falling back to smoke.`);
+  }
+  const durationMs = toPositiveNumber(args.get('duration') || env.BENCH_DURATION_MS, profile.durationMs);
+  const sampleMs = toPositiveNumber(args.get('sample') || env.BENCH_SAMPLE_MS, profile.sampleMs);
+  const warmupMs = toPositiveNumber(
+    args.get('warmup') || env.BENCH_WARMUP_MS,
+    profile.warmupMs ?? Math.max(5000, sampleMs * 4)
+  );
+  const modeInput = (args.get('mode') || env.BENCH_MODE || profile.mode).toLowerCase();
+  const mode = VALID_MODES.has(modeInput) ? modeInput : profile.mode;
+  if (mode !== modeInput) {
+    warn?.(`[bench-performance] Unsupported mode "${modeInput}", falling back to profile mode "${profile.mode}".`);
+  }
+
+  return {
+    baseUrl,
+    requestedProfile,
+    durationMs,
+    sampleMs,
+    warmupMs,
+    mode,
+    entrances: toPositiveNumber(args.get('entrances') || env.BENCH_ENTRANCES, profile.entrances),
+    opTimeoutMs: toPositiveNumber(args.get('opTimeout') || env.BENCH_OP_TIMEOUT_MS, 30000),
+    maxRuntimeMs: toPositiveNumber(
+      args.get('maxRuntime') || env.BENCH_MAX_RUNTIME_MS,
+      profile.maxRuntimeMs ?? (warmupMs + durationMs + Math.max(60000, sampleMs * 20))
+    ),
+    headless: toBoolean(args.get('headless') || env.BENCH_HEADLESS, true),
+    profileQuery: profile.query || {}
+  };
+};
+
 const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
 
-const run = async () => {
-  const browser = await chromium.launch({
-    headless,
-    args: ['--allow-insecure-localhost', '--ignore-certificate-errors']
-  });
-  const context = await browser.newContext({ ignoreHTTPSErrors: true });
-  const page = await context.newPage();
-  await page.goto(buildUrl(baseUrl), { waitUntil: 'domcontentloaded' });
-  await page.waitForFunction(() => window.__E2E__?.getState?.().ready === true);
-
-  await page.evaluate(() => window.__E2E__.pause());
-  if (mode === 'sequence' && window.__E2E__.startBenchSequence) {
-    await page.evaluate(() => window.__E2E__.startBenchSequence());
-  } else if (window.__E2E__.startBench) {
-    await page.evaluate((count) => window.__E2E__.startBench(count), entrances);
-  }
-  await page.evaluate(() => window.__E2E__.resume());
-
-  const samples = [];
-  let maxTps = 0;
-  let maxSpeed = 0;
-  const start = Date.now();
-  while (Date.now() - start < durationMs) {
-    const bench = await page.evaluate(() => window.__E2E__.getBenchMetrics?.());
-    const tps = Number(bench?.tps || 0);
-    const speed = Number(bench?.speedFactor || 0);
-    if (tps > maxTps) maxTps = tps;
-    if (speed > maxSpeed) maxSpeed = speed;
-    samples.push({
-      elapsedMs: Date.now() - start,
-      tps,
-      speedFactor: speed,
-      benchMaxSpeed: bench?.benchMaxSpeed ?? null
-    });
-    await sleep(sampleMs);
+const median = (values) => {
+  if (!values.length) return 0;
+  const copy = values.slice().sort((a, b) => a - b);
+  const mid = Math.floor(copy.length / 2);
+  if ((copy.length % 2) === 0) {
+    return (copy[mid - 1] + copy[mid]) / 2;
   }
+  return copy[mid];
+};
 
-  await page.evaluate(() => window.__E2E__.pause());
-  await browser.close();
+/**
+ * @param {unknown[]} samples
+ * @param {string} key
+ */
+const summarize = (samples, key) => {
+  const values = samples
+    .map(sample => toNumberOrNaN(sample?.[key]))
+    .filter(value => Number.isFinite(value))
+    .sort((a, b) => a - b);
+  if (!values.length) return { min: 0, max: 0, p50: 0, p95: 0, avg: 0 };
+  const pick = (ratio) => values[Math.min(values.length - 1, Math.floor((values.length - 1) * ratio))];
+  const sum = values.reduce((acc, value) => acc + value, 0);
+  return {
+    min: values[0],
+    max: values[values.length - 1],
+    p50: pick(0.5),
+    p95: pick(0.95),
+    avg: sum / values.length
+  };
+};
 
-  const summary = {
-    mode,
+/**
+ * @param {{
+ *   baseUrl: string,
+ *   requestedProfile: string,
+ *   durationMs: number,
+ *   sampleMs: number,
+ *   warmupMs: number,
+ *   mode: string,
+ *   entrances: number,
+ *   opTimeoutMs: number,
+ *   maxRuntimeMs: number,
+ *   headless: boolean,
+ *   profileQuery: Record<string, string>
+ * }} [config]
+ */
+const run = async (config = createPerformanceBenchConfig()) => {
+  const {
+    baseUrl,
+    requestedProfile,
     durationMs,
     sampleMs,
-    maxTps,
-    maxSpeed,
-    samples
+    warmupMs,
+    mode,
+    entrances,
+    opTimeoutMs,
+    maxRuntimeMs,
+    headless,
+    profileQuery
+  } = config;
+
+  let browser = null;
+  let context = null;
+  let page = null;
+  const runStart = Date.now();
+
+  const assertRuntimeBudget = (phase) => {
+    const elapsed = Date.now() - runStart;
+    if (elapsed > maxRuntimeMs) {
+      throw new Error(`Benchmark exceeded max runtime (${maxRuntimeMs}ms) during ${phase}.`);
+    }
   };
-  console.log(JSON.stringify(summary, null, 2));
+
+  try {
+    browser = await withTimeout(chromium.launch({
+      headless,
+      args: ['--allow-insecure-localhost', '--ignore-certificate-errors']
+    }), opTimeoutMs, 'chromium.launch');
+
+    context = await withTimeout(
+      browser.newContext({ ignoreHTTPSErrors: true }),
+      opTimeoutMs,
+      'browser.newContext'
+    );
+    page = await withTimeout(context.newPage(), opTimeoutMs, 'context.newPage');
+    page.setDefaultTimeout(opTimeoutMs);
+
+    const benchUrl = buildUrl(baseUrl, profileQuery);
+    await withTimeout(
+      page.goto(benchUrl, { waitUntil: 'domcontentloaded' }),
+      opTimeoutMs,
+      'page.goto'
+    );
+    await withTimeout(
+      page.waitForFunction(() => window.__E2E__?.getState?.().ready === true),
+      opTimeoutMs,
+      'waitForGameReady'
+    );
+
+    await withTimeout(page.evaluate(() => window.__E2E__.pause()), opTimeoutMs, 'e2e.pause');
+    const capabilities = await withTimeout(page.evaluate(() => ({
+      startBenchSequence: typeof window.__E2E__?.startBenchSequence === 'function',
+      startBench: typeof window.__E2E__?.startBench === 'function',
+      startReverse: typeof window.__E2E__?.startReverse === 'function'
+    })), opTimeoutMs, 'readCapabilities');
+
+    let started = false;
+    if (mode === 'sequence') {
+      if (capabilities.startBenchSequence) {
+        await withTimeout(page.evaluate(() => window.__E2E__.startBenchSequence()), opTimeoutMs, 'startBenchSequence');
+        started = true;
+      } else if (capabilities.startBench) {
+        await withTimeout(
+          page.evaluate((count) => window.__E2E__.startBench(count), entrances),
+          opTimeoutMs,
+          'startBench'
+        );
+        started = true;
+      }
+    } else if (mode === 'reverse') {
+      if (capabilities.startBench) {
+        await withTimeout(
+          page.evaluate((count) => window.__E2E__.startBench(count), entrances),
+          opTimeoutMs,
+          'startBench'
+        );
+        started = true;
+      }
+      if (capabilities.startReverse) {
+        await withTimeout(page.evaluate(() => window.__E2E__.startReverse()), opTimeoutMs, 'startReverse');
+        started = true;
+      }
+    } else if (capabilities.startBench) {
+      await withTimeout(
+        page.evaluate((count) => window.__E2E__.startBench(count), entrances),
+        opTimeoutMs,
+        'startBench'
+      );
+      started = true;
+    } else if (capabilities.startBenchSequence) {
+      await withTimeout(page.evaluate(() => window.__E2E__.startBenchSequence()), opTimeoutMs, 'startBenchSequence');
+      started = true;
+    }
+    if (!started) {
+      throw new Error(`Requested bench mode "${mode}" is unsupported by current E2E capabilities.`);
+    }
+    await withTimeout(page.evaluate(() => window.__E2E__.resume()), opTimeoutMs, 'e2e.resume');
+
+    const samples = [];
+    const warmupSamples = [];
+    let maxTps = 0;
+    let maxSpeed = 0;
+    let maxFrameMs = 0;
+    const start = Date.now();
+    const totalWindowMs = warmupMs + durationMs;
+    while (Date.now() - start < totalWindowMs) {
+      assertRuntimeBudget('sampling');
+      const evalStart = Date.now();
+      const bench = await withTimeout(page.evaluate(() => {
+        const metrics = window.__E2E__.getBenchMetrics?.() || {};
+        const state = window.__E2E__.getState?.() || {};
+        const timer = state?.game?.timer || {};
+        return {
+          ...metrics,
+          reverse: !!state?.game?.timeTravel?.isReversing,
+          frameMs: Number(timer.frameTime || 0)
+        };
+      }), opTimeoutMs, 'sampleBenchMetrics');
+
+      const evalMs = Date.now() - evalStart;
+      const tps = Number(bench?.tps || 0);
+      const speed = Number(bench?.speedFactor || 0);
+      const frameMs = Number(bench?.frameMs || 0);
+      if (tps > maxTps) maxTps = tps;
+      if (speed > maxSpeed) maxSpeed = speed;
+      if (frameMs > maxFrameMs) maxFrameMs = frameMs;
+      const elapsedMs = Date.now() - start;
+      const sample = {
+        elapsedMs,
+        tps,
+        speedFactor: speed,
+        frameMs,
+        evalMs,
+        reverse: !!bench?.reverse,
+        benchMaxSpeed: bench?.benchMaxSpeed ?? null
+      };
+      if (elapsedMs < warmupMs) {
+        warmupSamples.push(sample);
+      } else {
+        samples.push({
+          ...sample,
+          elapsedMs: elapsedMs - warmupMs
+        });
+      }
+      await sleep(sampleMs);
+    }
+
+    try {
+      await withTimeout(page.evaluate(() => window.__E2E__.pause()), opTimeoutMs, 'finalPause');
+    } catch (error) {
+      // Some bench modes can saturate the game loop near teardown; keep the
+      // collected metrics and continue shutdown instead of failing the run.
+      console.warn(error?.message || String(error));
+    }
+
+    const frameSeries = samples
+      .map(sample => Number(sample.frameMs || 0))
+      .filter(value => Number.isFinite(value) && value > 0);
+    const medianFrame = median(frameSeries);
+    const frameOutlierThreshold = Math.max(120, medianFrame * 3);
+    const evalOutlierThreshold = Math.max(1000, sampleMs * 2);
+    const flaggedSamples = samples.map(sample => {
+      const frameOutlier = sample.frameMs > frameOutlierThreshold;
+      const evalOutlier = sample.evalMs > evalOutlierThreshold;
+      return {
+        ...sample,
+        outlier: frameOutlier || evalOutlier,
+        outlierReason: frameOutlier
+          ? `frameMs>${frameOutlierThreshold.toFixed(1)}`
+          : evalOutlier ? `evalMs>${evalOutlierThreshold.toFixed(1)}` : null
+      };
+    });
+    const filteredSamples = flaggedSamples.filter(sample => !sample.outlier);
+
+    const summary = {
+      profile: requestedProfile,
+      mode,
+      durationMs,
+      warmupMs,
+      sampleMs,
+      entrances,
+      url: benchUrl,
+      maxTps,
+      maxSpeed,
+      maxFrameMs,
+      frameOutlierThreshold,
+      evalOutlierThreshold,
+      warmupSampleCount: warmupSamples.length,
+      sampleCount: flaggedSamples.length,
+      filteredSampleCount: filteredSamples.length,
+      outlierCount: flaggedSamples.length - filteredSamples.length,
+      tpsStats: summarize(flaggedSamples, 'tps'),
+      speedStats: summarize(flaggedSamples, 'speedFactor'),
+      frameStats: summarize(flaggedSamples, 'frameMs'),
+      evalStats: summarize(flaggedSamples, 'evalMs'),
+      filteredTpsStats: summarize(filteredSamples, 'tps'),
+      filteredSpeedStats: summarize(filteredSamples, 'speedFactor'),
+      filteredFrameStats: summarize(filteredSamples, 'frameMs'),
+      samples: flaggedSamples
+    };
+    console.log(JSON.stringify(summary, null, 2));
+  } finally {
+    await closeQuietly(page, 'page.close');
+    await closeQuietly(context, 'context.close');
+    await closeQuietly(browser, 'browser.close');
+  }
 };
 
-run().catch((error) => {
-  console.error(error);
-  process.exitCode = 1;
-});
+const isMainModule = (() => {
+  try {
+    return path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+})();
+
+if (isMainModule) {
+  run().catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+  });
+}
+
+export {
+  BENCH_PROFILES,
+  DEFAULT_BASE_URL,
+  buildUrl,
+  createPerformanceBenchConfig,
+  parseArgs,
+  run,
+  median,
+  summarize,
+  toBoolean,
+  toPositiveNumber
+};
diff --git a/scripts/bench-procgen-soak.js b/scripts/bench-procgen-soak.js
new file mode 100644
index 00000000..2c9125dc
--- /dev/null
+++ b/scripts/bench-procgen-soak.js
@@ -0,0 +1,324 @@
+import { chromium } from '@playwright/test';
+import { pathToFileURL } from 'node:url';
+
+const DEFAULT_BASE_URL = 'https://localhost:8080/procgen.html?e2e=1';
+
+const toNumberOrNaN = (value) => {
+  try {
+    return Number(value);
+  } catch {
+    return Number.NaN;
+  }
+};
+
+/**
+ * @param {string[]} argv
+ * @returns {Map<string, string>}
+ */
+const parseArgs = (argv) => {
+  const out = new Map();
+  for (const arg of argv) {
+    if (!arg.startsWith('--')) continue;
+    const [key, value] = arg.slice(2).split('=', 2);
+    out.set(key, value ?? 'true');
+  }
+  return out;
+};
+
+/**
+ * @param {unknown} value
+ * @param {number} fallback
+ * @returns {number}
+ */
+const toPositiveNumber = (value, fallback) => {
+  const parsed = toNumberOrNaN(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+};
+
+/**
+ * @param {unknown} value
+ * @param {boolean} fallback
+ * @returns {boolean}
+ */
+const toBoolean = (value, fallback) => {
+  if (value == null) return fallback;
+  const normalized = String(value).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on', 'enabled'].includes(normalized)) return true;
+  if (['0', 'false', 'no', 'off', 'disabled'].includes(normalized)) return false;
+  return fallback;
+};
+
+const withTimeout = async (promise, timeoutMs, label) => {
+  let timeoutId = null;
+  const timeoutPromise = new Promise((_, reject) => {
+    timeoutId = setTimeout(() => {
+      reject(new Error(`${label} timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([promise, timeoutPromise]);
+  } finally {
+    if (timeoutId != null) clearTimeout(timeoutId);
+  }
+};
+
+const closeQuietly = async (target, label) => {
+  if (!target || typeof target.close !== 'function') return;
+  try {
+    await withTimeout(target.close(), 5000, label);
+  } catch {
+    // best effort shutdown
+  }
+};
+
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+
+/**
+ * @param {number[]} values
+ * @returns {{min: number, max: number, p50: number, p95: number, avg: number}}
+ */
+const summarize = (values) => {
+  const nums = values.filter(value => Number.isFinite(value)).sort((a, b) => a - b);
+  if (!nums.length) return { min: 0, max: 0, p50: 0, p95: 0, avg: 0 };
+  const pick = (ratio) => nums[Math.min(nums.length - 1, Math.floor((nums.length - 1) * ratio))];
+  const sum = nums.reduce((acc, value) => acc + value, 0);
+  return {
+    min: nums[0],
+    max: nums[nums.length - 1],
+    p50: pick(0.5),
+    p95: pick(0.95),
+    avg: sum / nums.length
+  };
+};
+
+/**
+ * @param {string} raw
+ * @param {string} [fallback]
+ * @returns {string}
+ */
+const buildUrl = (raw, fallback = DEFAULT_BASE_URL) => {
+  let candidate = null;
+  try {
+    candidate = new URL(raw || fallback);
+  } catch {
+    candidate = new URL(fallback);
+  }
+  candidate.searchParams.set('e2e', '1');
+  return candidate.toString();
+};
+
+/**
+ * @param {{argv?: string[], env?: NodeJS.ProcessEnv}} [options]
+ * @returns {{
+ *   baseUrl: string,
+ *   durationMs: number,
+ *   warmupMs: number,
+ *   sampleMs: number,
+ *   opTimeoutMs: number,
+ *   maxRuntimeMs: number,
+ *   heapLimitMb: number,
+ *   headless: boolean
+ * }}
+ */
+const createProcgenSoakConfig = ({
+  argv = process.argv.slice(2),
+  env = process.env
+} = {}) => {
+  const args = parseArgs(argv);
+  const baseUrl = args.get('url') || env.LEMMINGS_PROCGEN_URL || DEFAULT_BASE_URL;
+  const durationMs = toPositiveNumber(args.get('duration') || env.PROCGEN_SOAK_DURATION_MS, 60000);
+  const warmupMs = toPositiveNumber(args.get('warmup') || env.PROCGEN_SOAK_WARMUP_MS, 5000);
+  const sampleMs = toPositiveNumber(args.get('sample') || env.PROCGEN_SOAK_SAMPLE_MS, 1000);
+  const opTimeoutMs = toPositiveNumber(args.get('opTimeout') || env.PROCGEN_SOAK_OP_TIMEOUT_MS, 30000);
+  const maxRuntimeMs = toPositiveNumber(
+    args.get('maxRuntime') || env.PROCGEN_SOAK_MAX_RUNTIME_MS,
+    warmupMs + durationMs + Math.max(60000, sampleMs * 20)
+  );
+  const heapLimitMb = toPositiveNumber(args.get('heapLimitMb') || env.PROCGEN_SOAK_HEAP_LIMIT_MB, 0);
+  const headless = toBoolean(args.get('headless') || env.PROCGEN_SOAK_HEADLESS, true);
+
+  return {
+    baseUrl,
+    durationMs,
+    warmupMs,
+    sampleMs,
+    opTimeoutMs,
+    maxRuntimeMs,
+    heapLimitMb,
+    headless
+  };
+};
+
+/**
+ * Runs the procgen soak benchmark in a Playwright browser context.
+ *
+ * @param {{
+ *   baseUrl: string,
+ *   durationMs: number,
+ *   warmupMs: number,
+ *   sampleMs: number,
+ *   opTimeoutMs: number,
+ *   maxRuntimeMs: number,
+ *   heapLimitMb: number,
+ *   headless: boolean
+ * }} [config]
+ * @returns {Promise<void>}
+ */
+const run = async (config = createProcgenSoakConfig()) => {
+  let browser = null;
+  let context = null;
+  let page = null;
+  const runStart = Date.now();
+  const samples = [];
+  const {
+    baseUrl,
+    durationMs,
+    warmupMs,
+    sampleMs,
+    opTimeoutMs,
+    maxRuntimeMs,
+    heapLimitMb,
+    headless
+  } = config;
+
+  const assertRuntimeBudget = (phase) => {
+    const elapsed = Date.now() - runStart;
+    if (elapsed > maxRuntimeMs) {
+      throw new Error(`Procgen soak exceeded max runtime (${maxRuntimeMs}ms) during ${phase}.`);
+    }
+  };
+
+  try {
+    browser = await withTimeout(chromium.launch({
+      headless,
+      args: ['--allow-insecure-localhost', '--ignore-certificate-errors']
+    }), opTimeoutMs, 'chromium.launch');
+
+    context = await withTimeout(
+      browser.newContext({ ignoreHTTPSErrors: true }),
+      opTimeoutMs,
+      'browser.newContext'
+    );
+    page = await withTimeout(context.newPage(), opTimeoutMs, 'context.newPage');
+    page.setDefaultTimeout(opTimeoutMs);
+
+    await withTimeout(page.goto(buildUrl(baseUrl), { waitUntil: 'domcontentloaded' }), opTimeoutMs, 'page.goto');
+    await withTimeout(
+      page.waitForFunction(() => window.__E2E__?.getState?.().ready === true),
+      opTimeoutMs,
+      'waitForProcgenReady'
+    );
+
+    await withTimeout(page.evaluate(() => window.__E2E__.resume()), opTimeoutMs, 'e2e.resume');
+
+    const loopStart = Date.now();
+    const totalWindow = warmupMs + durationMs;
+    while (Date.now() - loopStart < totalWindow) {
+      assertRuntimeBudget('sampling');
+      const sample = await withTimeout(page.evaluate(() => {
+        const state = window.__E2E__?.getState?.() || {};
+        const timer = state?.game?.timer || {};
+        const manager = state?.game?.lemmingManager || {};
+        const history = state?.game?.history || {};
+        const perfMem = (typeof performance !== 'undefined' && performance.memory)
+          ? {
+            usedJSHeapSize: performance.memory.usedJSHeapSize,
+            totalJSHeapSize: performance.memory.totalJSHeapSize,
+            jsHeapSizeLimit: performance.memory.jsHeapSizeLimit
+          }
+          : null;
+        return {
+          tick: Number(timer.tickIndex || 0),
+          frameMs: Number(timer.frameTime || 0),
+          speedFactor: Number(timer.speedFactor || 0),
+          activeCount: Number(manager.activeCount || 0),
+          totalCount: Number(manager.totalCount || 0),
+          spawnTotal: Number(manager.spawnTotal || 0),
+          historySpanTicks: Number(history.spanTicks || 0),
+          memory: perfMem
+        };
+      }), opTimeoutMs, 'sampleProcgenState');
+
+      samples.push({
+        elapsedMs: Date.now() - loopStart,
+        ...sample
+      });
+      await sleep(sampleMs);
+    }
+
+    await withTimeout(page.evaluate(() => window.__E2E__.pause()), opTimeoutMs, 'e2e.pause');
+
+    const measured = samples
+      .filter(sample => sample.elapsedMs >= warmupMs)
+      .map(sample => ({ ...sample, elapsedMs: sample.elapsedMs - warmupMs }));
+    const warmupSamples = samples.length - measured.length;
+
+    const first = measured[0] || null;
+    const last = measured[measured.length - 1] || null;
+    const memorySamples = measured
+      .map(sample => sample.memory?.usedJSHeapSize || 0)
+      .filter(value => Number.isFinite(value) && value > 0);
+    const maxHeapBytes = memorySamples.length ? Math.max(...memorySamples) : 0;
+    const maxHeapMb = maxHeapBytes > 0 ? (maxHeapBytes / (1024 * 1024)) : 0;
+
+    const summary = {
+      url: buildUrl(baseUrl),
+      durationMs,
+      warmupMs,
+      sampleMs,
+      sampleCount: measured.length,
+      warmupSamples,
+      growth: {
+        tickDelta: first && last ? Math.max(0, last.tick - first.tick) : 0,
+        spawnDelta: first && last ? Math.max(0, last.spawnTotal - first.spawnTotal) : 0,
+        activeDelta: first && last ? (last.activeCount - first.activeCount) : 0,
+        totalCountDelta: first && last ? (last.totalCount - first.totalCount) : 0,
+        historySpanDelta: first && last ? Math.max(0, last.historySpanTicks - first.historySpanTicks) : 0
+      },
+      frameMsStats: summarize(measured.map(sample => sample.frameMs)),
+      activeCountStats: summarize(measured.map(sample => sample.activeCount)),
+      totalCountStats: summarize(measured.map(sample => sample.totalCount)),
+      maxHeapMb,
+      heapLimitMb,
+      heapLimitExceeded: heapLimitMb > 0 && maxHeapMb > heapLimitMb,
+      samples: measured
+    };
+
+    console.log(JSON.stringify(summary, null, 2));
+
+    if (summary.heapLimitExceeded) {
+      throw new Error(`Heap usage ${maxHeapMb.toFixed(2)}MB exceeded limit ${heapLimitMb}MB`);
+    }
+  } finally {
+    await closeQuietly(page, 'page.close');
+    await closeQuietly(context, 'context.close');
+    await closeQuietly(browser, 'browser.close');
+  }
+};
+
+const isDirectExecution = () => {
+  const entry = process.argv?.[1];
+  if (!entry) return false;
+  try {
+    return import.meta.url === pathToFileURL(entry).href;
+  } catch {
+    return false;
+  }
+};
+
+if (isDirectExecution()) {
+  run().catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+  });
+}
+
+export {
+  buildUrl,
+  createProcgenSoakConfig,
+  parseArgs,
+  run,
+  summarize,
+  toBoolean,
+  toPositiveNumber
+};
diff --git a/scripts/bench-smoke.js b/scripts/bench-smoke.js
new file mode 100644
index 00000000..790a757a
--- /dev/null
+++ b/scripts/bench-smoke.js
@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const parseArgs = (argv) => {
+  const out = new Map();
+  for (const arg of argv) {
+    if (!arg.startsWith('--')) continue;
+    const [key, value] = arg.slice(2).split('=', 2);
+    out.set(key, value ?? 'true');
+  }
+  return out;
+};
+
+const toNumberOrNaN = (value) => {
+  try {
+    return Number(value);
+  } catch {
+    return Number.NaN;
+  }
+};
+
+const toPositiveNumber = (value, fallback) => {
+  const parsed = toNumberOrNaN(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+};
+
+const parseJsonOutput = (stdout, label) => {
+  const text = String(stdout || '').trim();
+  if (!text) {
+    throw new Error(`${label} produced no JSON output.`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    const first = text.indexOf('{');
+    const last = text.lastIndexOf('}');
+    if (first < 0 || last <= first) {
+      throw new Error(`${label} did not produce parsable JSON output.`);
+    }
+    return JSON.parse(text.slice(first, last + 1));
+  }
+};
+
+const runNodeScript = (scriptPath, scriptArgs, timeoutMs, label) => {
+  const started = Date.now();
+  const result = spawnSync(process.execPath, [scriptPath, ...scriptArgs], {
+    encoding: 'utf8',
+    timeout: timeoutMs,
+    maxBuffer: 16 * 1024 * 1024
+  });
+  if (result.error) {
+    throw new Error(`${label} failed: ${result.error.message}`);
+  }
+  if (typeof result.status !== 'number' || result.status !== 0) {
+    throw new Error(`${label} exited with status ${result.status ?? 'null'}.\n${result.stderr || ''}`);
+  }
+  return {
+    durationMs: Date.now() - started,
+    data: parseJsonOutput(result.stdout, label)
+  };
+};
+
+const evaluateSmokeResults = ({ performance, history, hotpaths }, thresholds) => {
+  const failures = [];
+
+  const perfP95Frame = Number(performance?.filteredFrameStats?.p95 ?? performance?.frameStats?.p95 ?? 0);
+  const perfP50Tps = Number(performance?.filteredTpsStats?.p50 ?? performance?.tpsStats?.p50 ?? 0);
+  if (perfP95Frame > thresholds.perfP95FrameMsMax) {
+    failures.push(`perf frame p95 ${perfP95Frame.toFixed(2)}ms > ${thresholds.perfP95FrameMsMax.toFixed(2)}ms`);
+  }
+  if (perfP50Tps < thresholds.perfP50TpsMin) {
+    failures.push(`perf TPS p50 ${perfP50Tps.toFixed(2)} < ${thresholds.perfP50TpsMin.toFixed(2)}`);
+  }
+
+  const historyResults = Array.isArray(history?.results) ? history.results : [];
+  const historyRatio = historyResults.length
+    ? historyResults.reduce((acc, item) => {
+      const target = Number(item?.targetSpanTicks || 0);
+      const span = Number(item?.maxSpanTicks || 0);
+      if (!Number.isFinite(target) || target <= 0) return acc;
+      return Math.max(acc, span / target);
+    }, 0)
+    : 0;
+  if (historyRatio < thresholds.historySpanRatioMin) {
+    failures.push(`history span ratio ${historyRatio.toFixed(3)} < ${thresholds.historySpanRatioMin.toFixed(3)}`);
+  }
+
+  const antsAvgMs = Number(hotpaths?.marchingAnts?.avgMs ?? 0);
+  if (antsAvgMs > thresholds.antsAvgMsMax) {
+    failures.push(`marching ants avg ${antsAvgMs.toFixed(2)}ms > ${thresholds.antsAvgMsMax.toFixed(2)}ms`);
+  }
+  const tileCompositionAvgMs = Number(hotpaths?.tileComposition?.avgMs ?? 0);
+  if (tileCompositionAvgMs > thresholds.tileCompositionAvgMsMax) {
+    failures.push(`tile composition avg ${tileCompositionAvgMs.toFixed(2)}ms > ${thresholds.tileCompositionAvgMsMax.toFixed(2)}ms`);
+  }
+
+  const overlayPlaneAvgMs = Number(hotpaths?.overlayPlane?.avgMs ?? 0);
+  if (overlayPlaneAvgMs > thresholds.overlayPlaneAvgMsMax) {
+    failures.push(`overlay plane avg ${overlayPlaneAvgMs.toFixed(2)}ms > ${thresholds.overlayPlaneAvgMsMax.toFixed(2)}ms`);
+  }
+
+  const scaledBlitAvgMs = Number(hotpaths?.scaledBlit?.avgMs ?? 0);
+  if (scaledBlitAvgMs > thresholds.scaledBlitAvgMsMax) {
+    failures.push(`scaled blit avg ${scaledBlitAvgMs.toFixed(2)}ms > ${thresholds.scaledBlitAvgMsMax.toFixed(2)}ms`);
+  }
+
+  return {
+    ok: failures.length === 0,
+    failures,
+    metrics: {
+      perfP95Frame,
+      perfP50Tps,
+      historyRatio,
+      antsAvgMs,
+      tileCompositionAvgMs,
+      overlayPlaneAvgMs,
+      scaledBlitAvgMs
+    }
+  };
+};
+
+const main = (argv = process.argv.slice(2)) => {
+  const args = parseArgs(argv);
+  const soakRequested = args.has('soak') || process.env.BENCH_SOAK === '1';
+  const timeoutMs = toPositiveNumber(
+    args.get('timeoutMs') || process.env.BENCH_SMOKE_TIMEOUT_MS,
+    soakRequested ? 300000 : 70000
+  );
+  const perfP95FrameMsMax = toPositiveNumber(args.get('perfP95FrameMsMax') || process.env.BENCH_SMOKE_PERF_P95_MAX, 250);
+  const perfP50TpsMin = toPositiveNumber(args.get('perfP50TpsMin') || process.env.BENCH_SMOKE_PERF_TPS_MIN, 15);
+  const historySpanRatioMin = toPositiveNumber(args.get('historySpanRatioMin') || process.env.BENCH_SMOKE_HISTORY_RATIO_MIN, 0.5);
+  const antsAvgMsMax = toPositiveNumber(args.get('antsAvgMsMax') || process.env.BENCH_SMOKE_ANTS_MAX_MS, 250);
+  const tileCompositionAvgMsMax = toPositiveNumber(args.get('tileCompositionAvgMsMax') || process.env.BENCH_SMOKE_TILE_MAX_MS, 250);
+  const overlayPlaneAvgMsMax = toPositiveNumber(args.get('overlayPlaneAvgMsMax') || process.env.BENCH_SMOKE_OVERLAY_MAX_MS, 250);
+  const scaledBlitAvgMsMax = toPositiveNumber(args.get('scaledBlitAvgMsMax') || process.env.BENCH_SMOKE_SCALED_MAX_MS, 250);
+  const baseUrl = args.get('url') || process.env.LEMMINGS_BENCH_URL || 'https://localhost:8080/?e2e=1';
+  const headless = (args.get('headless') || process.env.BENCH_HEADLESS || 'true') !== 'false';
+
+  const commonArgs = [
+    `--url=${baseUrl}`,
+    `--headless=${headless}`
+  ];
+
+  const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+  const perfScript = path.join(root, 'scripts', 'bench-performance.js');
+  const historyScript = path.join(root, 'scripts', 'bench-history-stress.js');
+  const hotpathsScript = path.join(root, 'scripts', 'bench-hotpaths.js');
+
+  const started = Date.now();
+  const perfArgs = soakRequested
+    ? ['--soak', '--profile=soak', '--maxRuntime=300000']
+    : ['--smoke', '--profile=smoke', '--duration=6000', '--warmup=1500', '--sample=500', '--maxRuntime=25000'];
+  const historyArgs = soakRequested
+    ? ['--soak', '--profile=soak', '--maxRuntime=300000']
+    : ['--smoke', '--profile=smoke', '--duration=6000', '--sample=500', '--speeds=30,60', '--maxRuntime=25000'];
+  const performance = runNodeScript(perfScript, [
+    ...perfArgs,
+    ...commonArgs
+  ], timeoutMs, 'bench-performance');
+
+  const history = runNodeScript(historyScript, [
+    ...historyArgs,
+    ...commonArgs
+  ], timeoutMs, 'bench-history-stress');
+
+  const hotpaths = runNodeScript(hotpathsScript, [
+    '--smoke'
+  ], Math.min(timeoutMs, 30000), 'bench-hotpaths');
+
+  const thresholds = {
+    perfP95FrameMsMax,
+    perfP50TpsMin,
+    historySpanRatioMin,
+    antsAvgMsMax,
+    tileCompositionAvgMsMax,
+    overlayPlaneAvgMsMax,
+    scaledBlitAvgMsMax
+  };
+  const gate = evaluateSmokeResults({
+    performance: performance.data,
+    history: history.data,
+    hotpaths: hotpaths.data
+  }, thresholds);
+
+  const summary = {
+    ok: gate.ok,
+    profile: soakRequested ? 'soak' : 'smoke',
+    totalDurationMs: Date.now() - started,
+    thresholds,
+    durationsMs: {
+      benchPerformance: performance.durationMs,
+      benchHistoryStress: history.durationMs,
+      benchHotpaths: hotpaths.durationMs
+    },
+    metrics: gate.metrics,
+    failures: gate.failures
+  };
+
+  console.log(JSON.stringify(summary, null, 2));
+  if (!gate.ok) {
+    process.exitCode = 1;
+  }
+};
+
+const isMain = (() => {
+  try {
+    return path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+})();
+
+if (isMain) {
+  try {
+    main();
+  } catch (error) {
+    console.error(error?.message || String(error));
+    process.exitCode = 1;
+  }
+}
+
+export { evaluateSmokeResults };
diff --git a/scripts/build-mcpb-bundle.js b/scripts/build-mcpb-bundle.js
index 6bc69383..6043c710 100644
--- a/scripts/build-mcpb-bundle.js
+++ b/scripts/build-mcpb-bundle.js
@@ -4,31 +4,122 @@ import { fileURLToPath } from 'node:url';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT_DIR = path.resolve(__dirname, '..');
-const DIST_DIR = path.join(ROOT_DIR, 'dist', 'mcpb');
-
-const COPY_LIST = [
-  { from: 'mcpb/manifest.json', to: 'manifest.json' },
-  { from: 'mcpb/server.json', to: 'server.json' },
-  { from: 'mcpb/.mcpbignore', to: '.mcpbignore' },
-  { from: 'mcpb/package.json', to: 'package.json' },
-  { from: 'keybindings.json', to: 'keybindings.json' },
-  { from: 'mcp/server.js', to: 'mcp/server.js' },
-  { from: 'mcp/spectator.html', to: 'mcp/spectator.html', optional: true }
-];
-
-const ensureDir = async (filePath) => {
+const VALID_SURFACES = new Set(['game', 'editor', 'interact']);
+
+/**
+ * @param {string[]} argv
+ * @returns {{surface: string | null}}
+ */
+const parseArgs = (argv) => {
+  const out = {
+    surface: null
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg.startsWith('--surface=')) {
+      const value = arg.slice('--surface='.length).trim();
+      if (!value) {
+        throw new Error('Missing value for --surface');
+      }
+      out.surface = value.toLowerCase();
+      continue;
+    }
+    if (arg === '--surface') {
+      const value = String(argv[i + 1] || '').trim();
+      if (!value) {
+        throw new Error('Missing value for --surface');
+      }
+      out.surface = value.toLowerCase();
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith('--')) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+  if (out.surface && !VALID_SURFACES.has(out.surface)) {
+    throw new Error(`Invalid surface "${out.surface}". Expected one of: ${Array.from(VALID_SURFACES).join(', ')}.`);
+  }
+  return out;
+};
+
+/**
+ * @param {string|null} surface
+ * @param {string} kind
+ * @param {string} fallbackPath
+ * @returns {{candidate: string|null, fallbackPath: string}}
+ */
+const resolveSurfaceFile = (surface, kind, fallbackPath) => {
+  if (!surface) return { candidate: null, fallbackPath };
+  return {
+    candidate: `mcpb/${kind}.${surface}.json`,
+    fallbackPath
+  };
+};
+
+/**
+ * @param {string|null} surface
+ * @returns {Array<{from: string, to: string, candidate: string|null, optional?: boolean}>}
+ */
+const createCopyList = (surface) => {
+  const manifestPath = resolveSurfaceFile(surface, 'manifest', 'mcpb/manifest.json');
+  const packagePath = resolveSurfaceFile(surface, 'package', 'mcpb/package.json');
+  const serverPath = resolveSurfaceFile(surface, 'server', 'mcpb/server.json');
+  return [
+    {
+      from: manifestPath.fallbackPath,
+      to: 'manifest.json',
+      candidate: manifestPath.candidate
+    },
+    {
+      from: serverPath.fallbackPath,
+      to: 'server.json',
+      candidate: serverPath.candidate
+    },
+    { from: 'mcpb/.mcpbignore', to: '.mcpbignore', candidate: null },
+    {
+      from: packagePath.fallbackPath,
+      to: 'package.json',
+      candidate: packagePath.candidate
+    },
+    { from: 'keybindings.json', to: 'keybindings.json', candidate: null }
+  ];
+};
+
+/**
+ * @param {string} filePath
+ * @param {{mkdir: typeof fs.mkdir}} [fsImpl]
+ */
+const ensureDir = async (filePath, fsImpl = fs) => {
   const dir = path.dirname(filePath);
-  await fs.mkdir(dir, { recursive: true });
+  await fsImpl.mkdir(dir, { recursive: true });
 };
 
-const copyFile = async (entry) => {
-  const source = path.join(ROOT_DIR, entry.from);
-  const destination = path.join(DIST_DIR, entry.to);
+/**
+ * @param {{from: string, to: string, candidate: string|null, optional?: boolean}} entry
+ * @param {{
+ *   distDir: string,
+ *   rootDir?: string,
+ *   fsImpl?: Pick<typeof fs, 'copyFile' | 'mkdir'>
+ * }} context
+ * @returns {Promise<boolean>}
+ */
+const copyFile = async (entry, { distDir, rootDir = ROOT_DIR, fsImpl = fs }) => {
+  const sourcePath = entry.candidate
+    ? path.join(rootDir, entry.candidate)
+    : path.join(rootDir, entry.from);
+  const fallbackPath = path.join(rootDir, entry.from);
+  const destination = path.join(distDir, entry.to);
   try {
-    await ensureDir(destination);
-    await fs.copyFile(source, destination);
+    await ensureDir(destination, fsImpl);
+    await fsImpl.copyFile(sourcePath, destination);
     return true;
   } catch (err) {
+    if (entry.candidate && err && err.code === 'ENOENT') {
+      await ensureDir(destination, fsImpl);
+      await fsImpl.copyFile(fallbackPath, destination);
+      return true;
+    }
     if (entry.optional && err && err.code === 'ENOENT') {
       return false;
     }
@@ -36,16 +127,80 @@ const copyFile = async (entry) => {
   }
 };
 
-const buildBundle = async () => {
-  await fs.rm(DIST_DIR, { recursive: true, force: true });
-  await fs.mkdir(DIST_DIR, { recursive: true });
+/**
+ * @param {string} fromDir
+ * @param {string} toDir
+ * @param {Pick<typeof fs, 'copyFile' | 'mkdir' | 'readdir' | 'stat'>} fsImpl
+ */
+const copyDirectory = async (fromDir, toDir, fsImpl = fs) => {
+  await fsImpl.mkdir(toDir, { recursive: true });
+  const entries = await fsImpl.readdir(fromDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const sourcePath = path.join(fromDir, entry.name);
+    const destinationPath = path.join(toDir, entry.name);
+    if (entry.isDirectory()) {
+      await copyDirectory(sourcePath, destinationPath, fsImpl);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    await ensureDir(destinationPath, fsImpl);
+    await fsImpl.copyFile(sourcePath, destinationPath);
+  }
+};
+
+/**
+ * @param {{
+ *   argv?: string[],
+ *   rootDir?: string,
+ *   fsImpl?: Pick<typeof fs, 'copyFile' | 'mkdir' | 'rm' | 'readdir' | 'stat'>,
+ *   log?: Pick<typeof console, 'log'>
+ * }} [options]
+ * @returns {Promise<{distDir: string, surface: string | null}>}
+ */
+const buildBundle = async (
+  {
+    argv = process.argv.slice(2),
+    rootDir = ROOT_DIR,
+    fsImpl = fs,
+    log = console
+  } = {}
+) => {
+  const options = parseArgs(argv);
+  const distDir = options.surface
+    ? path.join(rootDir, 'dist', `mcpb-${options.surface}`)
+    : path.join(rootDir, 'dist', 'mcpb');
+  const copyList = createCopyList(options.surface);
 
-  for (const entry of COPY_LIST) {
-    await copyFile(entry);
+  await fsImpl.rm(distDir, { recursive: true, force: true });
+  await fsImpl.mkdir(distDir, { recursive: true });
+  for (const entry of copyList) {
+    await copyFile(entry, { distDir, rootDir, fsImpl });
   }
+  await copyDirectory(path.join(rootDir, 'mcp'), path.join(distDir, 'mcp'), fsImpl);
 
-  const relative = path.relative(ROOT_DIR, DIST_DIR);
-  console.log(`MCPB bundle staged at ${relative}`);
+  const relative = path.relative(rootDir, distDir);
+  const suffix = options.surface ? ` (surface: ${options.surface})` : '';
+  log.log(`MCPB bundle staged at ${relative}${suffix}`);
+  return { distDir, surface: options.surface };
 };
 
-await buildBundle();
+const isMainModule = (() => {
+  try {
+    return path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+})();
+
+if (isMainModule) {
+  await buildBundle();
+}
+
+export {
+  VALID_SURFACES,
+  buildBundle,
+  createCopyList,
+  copyDirectory,
+  parseArgs,
+  resolveSurfaceFile
+};
diff --git a/scripts/check-release-readiness.js b/scripts/check-release-readiness.js
new file mode 100644
index 00000000..cb256732
--- /dev/null
+++ b/scripts/check-release-readiness.js
@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DEFAULT_DOC_PATH = path.join('docs', 'release-readiness.md');
+
+const REQUIRED_SECTIONS = Object.freeze([
+  'Compatibility',
+  'Migration',
+  'Performance',
+  'Accessibility',
+  'Runtime Controls'
+]);
+
+const normalizePathSeparators = (value) => String(value || '').replace(/\\/g, '/');
+
+const looksLikeWindowsAbsolutePath = (value) => {
+  const normalized = String(value || '');
+  return /^[A-Za-z]:[\\/]/.test(normalized) || /^\\\\[^\\]/.test(normalized);
+};
+
+const usesWindowsPathSemantics = (...values) => (
+  values.some((value) => looksLikeWindowsAbsolutePath(value))
+);
+
+const resolveDocPath = (cwd, docPath) => {
+  const normalizedCwd = String(cwd || '');
+  const normalizedDocPath = String(docPath || '');
+  if (usesWindowsPathSemantics(normalizedCwd, normalizedDocPath)) {
+    return path.win32.isAbsolute(normalizedDocPath)
+      ? path.win32.normalize(normalizedDocPath)
+      : path.win32.resolve(normalizedCwd, normalizedDocPath);
+  }
+  return path.resolve(normalizedCwd, normalizedDocPath);
+};
+
+const formatDocPathForSummary = (cwd, resolvedDocPath) => {
+  const normalizedCwd = String(cwd || '');
+  const normalizedDocPath = String(resolvedDocPath || '');
+
+  if (usesWindowsPathSemantics(normalizedCwd, normalizedDocPath)) {
+    if (path.win32.isAbsolute(normalizedCwd) && path.win32.isAbsolute(normalizedDocPath)) {
+      const relative = normalizePathSeparators(path.win32.relative(normalizedCwd, normalizedDocPath));
+      if (relative && !relative.startsWith('../') && !path.win32.isAbsolute(relative)) {
+        return relative;
+      }
+    }
+    return normalizePathSeparators(path.win32.normalize(normalizedDocPath));
+  }
+
+  if (path.isAbsolute(normalizedCwd) && path.isAbsolute(normalizedDocPath)) {
+    const relative = normalizePathSeparators(path.relative(normalizedCwd, normalizedDocPath));
+    if (relative && !relative.startsWith('../') && !path.isAbsolute(relative)) {
+      return relative;
+    }
+  }
+
+  return normalizePathSeparators(normalizedDocPath);
+};
+
+/**
+ * @param {string[]} [argv]
+ * @returns {Map<string, string>}
+ */
+const parseArgs = (argv = []) => {
+  const out = new Map();
+  for (const arg of argv) {
+    if (!arg.startsWith('--')) continue;
+    const [key, value] = arg.slice(2).split('=', 2);
+    out.set(key, value ?? 'true');
+  }
+  return out;
+};
+
+/**
+ * @param {string | null | undefined} value
+ * @param {boolean} [fallback]
+ * @returns {boolean}
+ */
+const parseBoolean = (value, fallback = false) => {
+  if (value == null) return fallback;
+  const normalized = String(value).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on', 'enabled'].includes(normalized)) return true;
+  if (['0', 'false', 'no', 'off', 'disabled'].includes(normalized)) return false;
+  return fallback;
+};
+
+const normalizeSectionName = (value) => String(value || '').trim().toLowerCase();
+
+/**
+ * @param {string} markdownText
+ * @returns {Map<string, Array<{checked: boolean, text: string}>>}
+ */
+const parseChecklistBySection = (markdownText) => {
+  const sectionMap = new Map();
+  const lines = String(markdownText || '').split(/\r?\n/);
+  let currentSection = null;
+  for (const line of lines) {
+    const headingMatch = line.match(/^\s*##\s+(.+?)\s*(?:#+\s*)?$/);
+    if (headingMatch) {
+      currentSection = headingMatch[1].trim();
+      if (!sectionMap.has(currentSection)) {
+        sectionMap.set(currentSection, []);
+      }
+      continue;
+    }
+    const itemMatch = line.match(/^\s*-\s*\[( |x|X)\]\s+(.+?)\s*$/);
+    if (!itemMatch || !currentSection) continue;
+    sectionMap.get(currentSection).push({
+      checked: itemMatch[1].toLowerCase() === 'x',
+      text: itemMatch[2]
+    });
+  }
+  return sectionMap;
+};
+
+/**
+ * @param {string} markdownText
+ * @param {{
+ *   requiredSections?: string[],
+ *   requireAllChecked?: boolean
+ * }} [options]
+ * @returns {{
+ *   ok: boolean,
+ *   requiredSections: string[],
+ *   counts: {sectionCount: number, itemCount: number, checkedCount: number, uncheckedCount: number},
+ *   missingSections: string[],
+ *   emptySections: string[],
+ *   uncheckedItems: Array<{section: string, text: string}>
+ * }}
+ */
+const evaluateReleaseReadiness = (
+  markdownText,
+  {
+    requiredSections = REQUIRED_SECTIONS,
+    requireAllChecked = true
+  } = {}
+) => {
+  const sections = parseChecklistBySection(markdownText);
+  const normalizedSectionNameToActual = new Map();
+  for (const sectionName of sections.keys()) {
+    normalizedSectionNameToActual.set(normalizeSectionName(sectionName), sectionName);
+  }
+
+  const missingSections = [];
+  const emptySections = [];
+  const uncheckedItems = [];
+  let checkedCount = 0;
+  let itemCount = 0;
+
+  for (const requiredSection of requiredSections) {
+    const found = normalizedSectionNameToActual.get(normalizeSectionName(requiredSection));
+    if (!found) {
+      missingSections.push(requiredSection);
+      continue;
+    }
+    const items = sections.get(found) || [];
+    if (!items.length) {
+      emptySections.push(requiredSection);
+      continue;
+    }
+    for (const item of items) {
+      itemCount += 1;
+      if (item.checked) {
+        checkedCount += 1;
+      } else if (requireAllChecked) {
+        uncheckedItems.push({ section: requiredSection, text: item.text });
+      }
+    }
+  }
+
+  return {
+    ok: missingSections.length === 0 && emptySections.length === 0 && uncheckedItems.length === 0,
+    requiredSections: requiredSections.slice(),
+    counts: {
+      sectionCount: requiredSections.length,
+      itemCount,
+      checkedCount,
+      uncheckedCount: Math.max(0, itemCount - checkedCount)
+    },
+    missingSections,
+    emptySections,
+    uncheckedItems
+  };
+};
+
+/**
+ * @param {string[]} [argv]
+ * @param {{
+ *   cwd?: string,
+ *   fsImpl?: Pick<typeof fs, 'readFileSync'>,
+ *   log?: Pick<typeof console, 'log' | 'error'>,
+ *   exit?: (code: number) => void
+ * }} [options]
+ */
+const run = (
+  argv = process.argv.slice(2),
+  {
+    cwd = process.cwd(),
+    fsImpl = fs,
+    log = console,
+    exit = process.exit
+  } = {}
+) => {
+  const args = parseArgs(argv);
+  const docPath = args.get('file') || process.env.LEMMINGS_RELEASE_READINESS_PATH || DEFAULT_DOC_PATH;
+  const requireAllChecked = parseBoolean(
+    args.get('strict') || process.env.LEMMINGS_RELEASE_READINESS_STRICT,
+    true
+  );
+  const resolvedDocPath = resolveDocPath(cwd, docPath);
+
+  let text;
+  try {
+    text = fsImpl.readFileSync(resolvedDocPath, 'utf8');
+  } catch (error) {
+    log.error(`Unable to read release-readiness document: ${resolvedDocPath}`);
+    log.error(error?.message || String(error));
+    exit(1);
+    return;
+  }
+
+  const summary = evaluateReleaseReadiness(text, { requireAllChecked });
+  log.log(JSON.stringify({
+    docPath: formatDocPathForSummary(cwd, resolvedDocPath),
+    strict: requireAllChecked,
+    ...summary
+  }, null, 2));
+
+  if (!summary.ok) {
+    exit(1);
+    return;
+  }
+};
+
+const isMain = (() => {
+  try {
+    return path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+})();
+
+if (isMain) {
+  run();
+}
+
+export {
+  DEFAULT_DOC_PATH,
+  REQUIRED_SECTIONS,
+  evaluateReleaseReadiness,
+  formatDocPathForSummary,
+  looksLikeWindowsAbsolutePath,
+  parseChecklistBySection,
+  resolveDocPath,
+  run
+};
diff --git a/scripts/check-undefined.js b/scripts/check-undefined.js
index ea24e09d..d1a65ac8 100644
--- a/scripts/check-undefined.js
+++ b/scripts/check-undefined.js
@@ -1,190 +1,193 @@
 import fs from 'fs';
 import path from 'path';
-import { parse } from 'acorn';
-import { createRequire } from 'module';
+import { Linter } from 'eslint';
 import { processHtmlFile as extractHtmlSnippets } from './processHtmlFile.js';
-const require = createRequire(import.meta.url);
-
-
-const definedFunctions = new Set();
-const definedMethods = new Set();
-const calls = [];
-
-const builtinFunctions = new Set([
-  'require',
-  'setTimeout',
-  'clearTimeout',
-  'setInterval',
-  'clearInterval',
-  'describe',
-  'it',
-  'before',
-  'after',
-  'expect',
-  '$',
-  'jQuery'
-]);
-
-const builtinObjects = new Set([
-  'console',
-  'Math',
-  'JSON',
-  'document',
-  'window',
-  'WebMidi',
-  'jQuery',
-  '$'
-]);
+import { checkUndefinedGlobals } from './lint-globals.js';
 
-const builtinMethods = new Set([
-  'log',
-  'error',
-  'warn',
-  'info',
-  'push',
-  'pop',
-  'forEach',
-  'map',
-  'addEventListener',
-  'removeEventListener',
-  'querySelector',
-  'getElementById',
-  'appendChild',
-  'replace',
-  'split',
-  'join',
-  'indexOf',
-  'slice',
-  'substring',
-  'createElement',
-  'ready',
-  'css',
-  'addClass',
-  'removeClass',
-  'values',
-  'catch',
-  'then'
+const defaultHtmlFiles = Object.freeze([
+  'index.html',
+  'editor.html',
+  'procgen.html'
 ]);
 
-function walk(node, visitor) {
-  if (!node || typeof node.type !== 'string') return;
-  visitor(node);
-  for (const key of Object.keys(node)) {
-    const value = node[key];
-    if (Array.isArray(value)) {
-      for (const c of value) walk(c, visitor);
-    } else if (value && typeof value.type === 'string') {
-      walk(value, visitor);
-    }
+const ignoredPathParts = Object.freeze(new Set([
+  '.git',
+  'node_modules',
+  'coverage',
+  'dist',
+  'test-results'
+]));
+
+const ignoredJsPathParts = Object.freeze(new Set([
+  'js/vendor'
+]));
+
+const jsExtensions = Object.freeze(new Set([
+  '.js',
+  '.mjs',
+  '.cjs'
+]));
+
+const linter = new Linter();
+
+const checkConfig = Object.freeze({
+  languageOptions: {
+    ecmaVersion: 2022,
+    sourceType: 'module',
+    globals: checkUndefinedGlobals
+  },
+  rules: {
+    'no-undef': ['error', { typeof: true }]
   }
-}
-
-function collectFromAst(ast, file, withCalls) {
-  walk(ast, node => {
-    if (node.type === 'FunctionDeclaration' && node.id) {
-      definedFunctions.add(node.id.name);
-    } else if (node.type === 'VariableDeclarator' && node.id.type === 'Identifier' && node.init && (node.init.type === 'FunctionExpression' || node.init.type === 'ArrowFunctionExpression')) {
-      definedFunctions.add(node.id.name);
-    } else if (node.type === 'ClassDeclaration' && node.body && node.body.body) {
-      for (const m of node.body.body) {
-        if ((m.type === 'MethodDefinition' || m.type === 'PropertyDefinition') && m.key.type === 'Identifier') {
-          definedMethods.add(m.key.name);
-        }
-      }
-    } else if (withCalls && node.type === 'CallExpression') {
-      if (node.callee.type === 'Identifier') {
-        calls.push({ type: 'function', name: node.callee.name, file, line: node.loc.start.line });
-      } else if (node.callee.type === 'MemberExpression' && !node.callee.computed && node.callee.property.type === 'Identifier') {
-        let objName = null;
-        if (node.callee.object.type === 'Identifier') objName = node.callee.object.name;
-        else if (node.callee.object.type === 'ThisExpression') objName = 'this';
-        calls.push({ type: 'method', name: node.callee.property.name, object: objName, file, line: node.loc.start.line });
-      }
-    }
-  });
-}
-
-function parseJS(code, file) {
-  try {
-    return parse(code, { ecmaVersion: 'latest', sourceType: 'module', locations: true });
-  } catch {
-    try {
-      return parse(code, { ecmaVersion: 'latest', sourceType: 'script', locations: true });
-    } catch {
-      try {
-        return parse(`function tmp(){${code}\n}`, { ecmaVersion: 'latest', sourceType: 'script', locations: true });
-      } catch {
-        return null;
-      }
-    }
+});
+
+const scriptConfig = Object.freeze({
+  ...checkConfig,
+  languageOptions: Object.freeze({
+    ...checkConfig.languageOptions,
+    sourceType: 'script'
+  })
+});
+
+const isIgnoredPath = (filePath, ignoredParts) => {
+  const normalized = filePath.replace(/\\/g, '/');
+  return Array.from(ignoredParts).some((part) => normalized.includes(`/${part}/`) || normalized.endsWith(`/${part}`));
+};
+
+const discoverRootHtmlFiles = () => {
+  const discovered = new Set();
+  for (const fileName of defaultHtmlFiles) {
+    const resolved = path.resolve(fileName);
+    if (fs.existsSync(resolved)) discovered.add(resolved);
+  }
+
+  const rootEntries = fs.readdirSync(process.cwd(), { withFileTypes: true });
+  for (const entry of rootEntries) {
+    if (!entry.isFile()) continue;
+    if (!entry.name.toLowerCase().endsWith('.html')) continue;
+    discovered.add(path.resolve(entry.name));
   }
-}
-
-function processJSFile(file, withCalls = false) {
-  const code = fs.readFileSync(file, 'utf8');
-  const ast = parseJS(code, file);
-  if (ast) collectFromAst(ast, file, withCalls);
-}
-
-function gatherFiles(dir, exts, results = []) {
-  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-    if (entry.name === 'node_modules' || entry.name === '.git') continue;
-    const full = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      gatherFiles(full, exts, results);
-    } else if (exts.some(ext => entry.name.endsWith(ext))) {
-      if (entry.name === 'jquery.js') continue;
-      results.push(full);
+  return Array.from(discovered);
+};
+
+const normalizeCliFiles = (argv) => {
+  const jsFiles = [];
+  const htmlFiles = [];
+
+  for (const raw of argv) {
+    const file = path.resolve(raw);
+    const ext = path.extname(file).toLowerCase();
+    if (jsExtensions.has(ext)) {
+      jsFiles.push(file);
+    } else if (ext === '.html') {
+      htmlFiles.push(file);
     }
   }
-  return results;
-}
 
+  return { jsFiles, htmlFiles };
+};
+
+const dedupeFiles = (files) => Array.from(new Set(files.map((file) => path.resolve(file))));
+
+const formatMessage = (file, message) => ({
+  file,
+  line: message.line || 1,
+  column: message.column || 1,
+  message: message.message
+});
 
-const extra = process.argv.slice(2);
-let jsFiles = [];
-let htmlFiles = [];
+const lintCode = ({ code, file, config }) => (
+  linter.verify(code, config)
+    .filter((message) => message.severity === 2)
+    .map((message) => formatMessage(file, message))
+);
 
-if (extra.length) {
-  for (const f of extra) {
-    if (f.endsWith('.js')) jsFiles.push(f);
-    else if (f.endsWith('.html')) htmlFiles.push(f);
+const wrapHtmlSnippet = (snippet) => {
+  if (snippet.type === 'handler') {
+    return `function __html_handler__() {\n${snippet.code}\n}`;
   }
-} else {
-  jsFiles = gatherFiles('js', ['.js']);
-  htmlFiles = gatherFiles('.', ['.html']);
-}
-
-
-for (const file of jsFiles) processJSFile(file, extra.length > 0);
-for (const file of htmlFiles) {
-  const snippets = extractHtmlSnippets(file);
-  for (const snippet of snippets) {
-    const ast = parseJS(snippet.code, file);
-    if (ast) collectFromAst(ast, file, true);
+  return snippet.code;
+};
+
+const lintHtmlFile = (htmlFile) => {
+  const extracted = extractHtmlSnippets(htmlFile, { includeExternalScripts: true });
+  const snippets = Array.isArray(extracted) ? extracted : extracted.snippets;
+  const entryScripts = Array.isArray(extracted?.entryScripts) ? extracted.entryScripts : [];
+  const code = (snippets || []).map(wrapHtmlSnippet).join('\n');
+  const errors = code.trim()
+    ? lintCode({ code, file: htmlFile, config: scriptConfig })
+    : [];
+
+  return {
+    errors,
+    entryScripts
+  };
+};
+
+const lintJsFiles = (files) => {
+  const errors = [];
+
+  for (const file of files) {
+    if (!fs.existsSync(file) || !fs.statSync(file).isFile()) continue;
+    if (isIgnoredPath(file, ignoredPathParts) || isIgnoredPath(file, ignoredJsPathParts)) continue;
+
+    const code = fs.readFileSync(file, 'utf8');
+    errors.push(...lintCode({ code, file, config: checkConfig }));
   }
-}
 
-const errors = [];
-for (const call of calls) {
-  if (call.type === 'function') {
-    if (!definedFunctions.has(call.name) && !builtinFunctions.has(call.name)) {
-      errors.push({ file: call.file, line: call.line, name: call.name });
-    }
-  } else if (call.type === 'method') {
-    if (builtinObjects.has(call.object)) continue;
-    if (!definedMethods.has(call.name) && !builtinMethods.has(call.name)) {
-      errors.push({ file: call.file, line: call.line, name: call.name });
+  return errors;
+};
+
+const compareErrors = (a, b) => (
+  a.file.localeCompare(b.file) ||
+  a.line - b.line ||
+  a.column - b.column ||
+  a.message.localeCompare(b.message)
+);
+
+const dedupeErrors = (errors) => {
+  const deduped = [];
+  const seen = new Set();
+  for (const error of errors) {
+    const key = `${error.file}:${error.line}:${error.column}:${error.message}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    deduped.push(error);
+  }
+  return deduped.sort(compareErrors);
+};
+
+const main = (argv = process.argv.slice(2)) => {
+  const explicit = argv.length > 0;
+  const cli = normalizeCliFiles(argv);
+  const htmlFiles = explicit ? cli.htmlFiles : discoverRootHtmlFiles();
+
+  const errors = [];
+  const jsFiles = new Set(cli.jsFiles.map((file) => path.resolve(file)));
+
+  for (const htmlFile of htmlFiles) {
+    if (!fs.existsSync(htmlFile) || !fs.statSync(htmlFile).isFile()) continue;
+    if (isIgnoredPath(htmlFile, ignoredPathParts)) continue;
+
+    const result = lintHtmlFile(htmlFile);
+    errors.push(...result.errors);
+    for (const entryScript of result.entryScripts) {
+      jsFiles.add(path.resolve(entryScript));
     }
   }
-}
 
-if (errors.length) {
-  console.error('Undefined calls found:');
-  for (const err of errors) {
-    console.error(`  ${err.file}:${err.line} - ${err.name} is not defined`);
+  errors.push(...lintJsFiles(dedupeFiles(Array.from(jsFiles))));
+
+  const deduped = dedupeErrors(errors);
+  if (deduped.length) {
+    console.error('Undefined references found:');
+    for (const error of deduped) {
+      console.error(`  ${error.file}:${error.line}:${error.column} - ${error.message}`);
+    }
+    process.exit(1);
   }
-  process.exit(1);
-} else {
+
   console.log('No undefined calls detected.');
-}
+};
+
+main();
diff --git a/scripts/e2e-capture-rects.js b/scripts/e2e-capture-rects.js
new file mode 100644
index 00000000..a1ec7b77
--- /dev/null
+++ b/scripts/e2e-capture-rects.js
@@ -0,0 +1,423 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { chromium } from '@playwright/test';
+import {
+  DEFAULT_CAPTURE_ROOT,
+  captureTargets,
+  makeCaptureTimestamp,
+  runVisualProbes,
+  sanitizeCaptureName
+} from '../e2e/helpers/visualCapture.js';
+import { installExternalAssetStubs } from '../e2e/helpers/externalAssets.js';
+import { installWebMidiStub } from '../e2e/helpers/webmidiStub.js';
+import { resolvePlaywrightBaseUrl } from '../playwright.config.js';
+
+const VIEWPORT_PRESETS = Object.freeze({
+  desktop: {
+    viewport: { width: 1280, height: 900 },
+    deviceScaleFactor: 1
+  },
+  tablet: {
+    viewport: { width: 820, height: 1180 },
+    deviceScaleFactor: 1
+  },
+  mobile: {
+    viewport: { width: 390, height: 844 },
+    deviceScaleFactor: 1
+  }
+});
+
+const npmConfigArgsFromEnv = (env = process.env) => {
+  const args = [];
+  const addValue = (envName, optionName) => {
+    const value = String(env?.[envName] || '').trim();
+    if (value) args.push(`--${optionName}=${value}`);
+  };
+  addValue('npm_config_base_url', 'base-url');
+  addValue('npm_config_out_dir', 'out-dir');
+  addValue('npm_config_viewport', 'viewport');
+  addValue('npm_config_target', 'target');
+  if (/^(1|true|yes)$/i.test(String(env?.npm_config_json || '').trim())) {
+    args.push('--json');
+  }
+  return args;
+};
+
+const parseCliArgs = (argv = process.argv.slice(2), env = process.env) => {
+  const parsed = {
+    config: null,
+    baseUrl: env.LEMMINGS_E2E_BASE_URL || null,
+    outDir: null,
+    viewport: 'desktop',
+    targets: [],
+    json: false,
+    help: false
+  };
+  for (const rawArg of [...npmConfigArgsFromEnv(env), ...argv]) {
+    const arg = String(rawArg || '');
+    if (arg === '--help' || arg === '-h') {
+      parsed.help = true;
+      continue;
+    }
+    if (arg === '--json') {
+      parsed.json = true;
+      continue;
+    }
+    if (arg.startsWith('--config=')) {
+      parsed.config = arg.slice('--config='.length).trim();
+      continue;
+    }
+    if (arg.startsWith('--base-url=')) {
+      parsed.baseUrl = arg.slice('--base-url='.length).trim();
+      continue;
+    }
+    if (arg.startsWith('--out-dir=')) {
+      parsed.outDir = arg.slice('--out-dir='.length).trim();
+      continue;
+    }
+    if (arg.startsWith('--viewport=')) {
+      parsed.viewport = arg.slice('--viewport='.length).trim();
+      continue;
+    }
+    if (arg.startsWith('--target=')) {
+      const value = arg.slice('--target='.length).trim();
+      for (const item of value.split(',')) {
+        const name = item.trim();
+        if (name) parsed.targets.push(name);
+      }
+      continue;
+    }
+    throw new Error(`Unknown option: ${arg}`);
+  }
+  return parsed;
+};
+
+const usage = () => [
+  'Usage: node scripts/e2e-capture-rects.js --config=e2e/capture-targets/midi.js',
+  '',
+  'Options:',
+  '  --base-url=https://localhost:8080',
+  '  --out-dir=temp/e2e-captures/my-run',
+  '  --viewport=desktop|tablet|mobile',
+  '  --target=name[,name...]',
+  '  --json'
+].join('\n');
+
+const loadConfig = async (configPath) => {
+  if (!configPath) throw new Error('Missing required --config option.');
+  const resolvedPath = path.resolve(configPath);
+  const mod = await import(pathToFileURL(resolvedPath).href);
+  const config = mod.default || mod.config || mod;
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    throw new Error(`Capture config must export an object: ${resolvedPath}`);
+  }
+  const hasTargets = Array.isArray(config.targets) && config.targets.length > 0;
+  const hasStates = Array.isArray(config.states)
+    && config.states.some(state => Array.isArray(state?.targets) && state.targets.length > 0);
+  if (!hasTargets && !hasStates) {
+    throw new Error(`Capture config must define a non-empty targets array or capture states: ${resolvedPath}`);
+  }
+  return {
+    path: resolvedPath,
+    config
+  };
+};
+
+const buildCaptureUrl = (baseUrl, config) => {
+  const route = config.route || '/';
+  const url = new URL(route, baseUrl);
+  if (config.e2e !== false) {
+    url.searchParams.set('e2e', '1');
+  }
+  return url.href;
+};
+
+const selectTargets = (targets, selectedNames = []) => {
+  if (!selectedNames.length) return targets;
+  const selected = new Set(selectedNames);
+  const matched = targets.filter(target => selected.has(target.name));
+  const matchedNames = new Set(matched.map(target => target.name));
+  const missing = selectedNames.filter(name => !matchedNames.has(name));
+  if (missing.length) {
+    throw new Error(`Unknown target(s): ${missing.join(', ')}`);
+  }
+  return matched;
+};
+
+const normalizeCaptureStates = (config) => (
+  Array.isArray(config.states)
+    ? config.states
+      .map((state, index) => ({
+        name: sanitizeCaptureName(state?.name || `state-${index + 1}`),
+        setup: state?.setup,
+        targets: Array.isArray(state?.targets) ? state.targets : [],
+        probes: Array.isArray(state?.probes) ? state.probes : []
+      }))
+      .filter(state => state.targets.length > 0)
+    : []
+);
+
+const prefixStateTarget = (stateName, target) => ({
+  ...target,
+  name: `${stateName}-${target.name}`
+});
+
+const prefixStateProbe = (stateName, probe) => {
+  if (typeof probe === 'string') {
+    return { name: `${stateName}-${probe}`, selector: probe };
+  }
+  return {
+    ...probe,
+    name: `${stateName}-${probe?.name || probe?.selector || 'probe'}`
+  };
+};
+
+const targetMatchesSelection = (target, selectedNames, rawName) => {
+  if (!selectedNames.length) return true;
+  return selectedNames.includes(target.name) || selectedNames.includes(rawName);
+};
+
+const runConfiguredCaptures = async (page, config, options) => {
+  const states = normalizeCaptureStates(config);
+  if (!states.length) {
+    const targets = selectTargets(config.targets, options.selectedTargets);
+    const captureResult = await captureTargets(page, targets, options.capture);
+    await resetPageScroll(page);
+    const probeResult = await runVisualProbes(page, config.probes || [], {
+      minTapTargetSize: config.minTapTargetSize
+    });
+    return {
+      outDir: captureResult.outDir,
+      captures: captureResult.captures,
+      probes: probeResult
+    };
+  }
+
+  const selectedTargets = options.selectedTargets || [];
+  const matchedTargets = new Set();
+  const captures = [];
+  const probeResults = [];
+  let outDir = null;
+
+  for (const state of states) {
+    if (typeof state.setup === 'function') {
+      await state.setup(page, {
+        ...options.context,
+        stateName: state.name
+      });
+    }
+    const prefixedTargets = state.targets.map(target => prefixStateTarget(state.name, target));
+    const selectedStateTargets = prefixedTargets.filter((target, index) => {
+      const rawName = state.targets[index]?.name;
+      const matches = targetMatchesSelection(target, selectedTargets, rawName);
+      if (matches) {
+        matchedTargets.add(target.name);
+        if (rawName) matchedTargets.add(rawName);
+      }
+      return matches;
+    });
+    if (selectedStateTargets.length) {
+      const captureResult = await captureTargets(page, selectedStateTargets, options.capture);
+      outDir = captureResult.outDir;
+      captures.push(...captureResult.captures);
+    }
+    await resetPageScroll(page);
+    const probes = state.probes.length
+      ? state.probes.map(probe => prefixStateProbe(state.name, probe))
+      : [];
+    if (probes.length) {
+      probeResults.push(await runVisualProbes(page, probes, {
+        minTapTargetSize: config.minTapTargetSize
+      }));
+    }
+  }
+
+  const missing = selectedTargets.filter(name => !matchedTargets.has(name));
+  if (missing.length) {
+    throw new Error(`Unknown target(s): ${missing.join(', ')}`);
+  }
+
+  const issues = probeResults.flatMap(result => result.issues);
+  return {
+    outDir: outDir || options.capture.outDir,
+    captures,
+    probes: {
+      version: 1,
+      issues,
+      warnings: issues.filter(issue => !issue.required),
+      failures: issues.filter(issue => issue.required)
+    }
+  };
+};
+
+const formatRect = (rect) => {
+  if (!rect) return '(full viewport)';
+  const round = value => Number(value).toFixed(1).replace(/\.0$/, '');
+  return `${round(rect.x)},${round(rect.y)} ${round(rect.width)}x${round(rect.height)}`;
+};
+
+const printHumanSummary = (result) => {
+  console.log(`Config: ${result.configName}`);
+  console.log(`Route: ${result.url}`);
+  console.log(`Viewport: ${result.viewportName} ${result.viewport.width}x${result.viewport.height}`);
+  console.log(`Output: ${result.outDir}`);
+  console.log('Captures:');
+  for (const capture of result.captures) {
+    const warnings = capture.warnings?.length ? ` warnings=${capture.warnings.join('; ')}` : '';
+    console.log(`  - ${capture.name} [${capture.type}] ${formatRect(capture.clip || capture.rect)} -> ${capture.path}${warnings}`);
+  }
+  if (result.probes.issues.length) {
+    console.log('Probe warnings:');
+    const visibleIssues = result.probes.issues.slice(0, 40);
+    for (const issue of visibleIssues) {
+      const prefix = issue.required ? 'required' : 'warning';
+      console.log(`  - ${prefix} ${issue.code} ${issue.selector}: ${issue.message}`);
+    }
+    if (result.probes.issues.length > visibleIssues.length) {
+      console.log(`  - ... ${result.probes.issues.length - visibleIssues.length} more`);
+    }
+  } else {
+    console.log('Probe warnings: none');
+  }
+};
+
+const resetPageScroll = async (page) => {
+  await page.evaluate(() => {
+    window.scrollTo?.(0, 0);
+    if (document?.documentElement) document.documentElement.scrollTop = 0;
+    if (document?.body) document.body.scrollTop = 0;
+  });
+};
+
+const runCaptureCli = async (argv = process.argv.slice(2)) => {
+  const args = parseCliArgs(argv);
+  if (args.help) {
+    return { help: true, text: usage(), exitCode: 0, json: args.json };
+  }
+  const viewportPreset = VIEWPORT_PRESETS[args.viewport];
+  if (!viewportPreset) {
+    throw new Error(`Unknown viewport preset: ${args.viewport}`);
+  }
+  const baseUrl = resolvePlaywrightBaseUrl(args.baseUrl);
+  const loaded = await loadConfig(args.config);
+  const configName = sanitizeCaptureName(
+    loaded.config.name || path.basename(loaded.path, path.extname(loaded.path))
+  );
+  const url = buildCaptureUrl(baseUrl, loaded.config);
+  const outDir = args.outDir
+    ? path.resolve(args.outDir)
+    : path.join(DEFAULT_CAPTURE_ROOT, `${makeCaptureTimestamp()}-${configName}`);
+
+  const browser = await chromium.launch();
+  let context = null;
+  try {
+    context = await browser.newContext({
+      baseURL: baseUrl,
+      viewport: viewportPreset.viewport,
+      deviceScaleFactor: viewportPreset.deviceScaleFactor,
+      ignoreHTTPSErrors: true,
+      permissions: ['midi']
+    });
+    const page = await context.newPage();
+    await installExternalAssetStubs(page);
+    if (loaded.config.webMidiStub) {
+      const webMidiStubOptions = typeof loaded.config.webMidiStub === 'object'
+        ? loaded.config.webMidiStub
+        : {};
+      await installWebMidiStub(page, webMidiStubOptions);
+    }
+    await page.goto(url, { waitUntil: loaded.config.waitUntil || 'domcontentloaded' });
+    if (typeof loaded.config.setup === 'function') {
+      await loaded.config.setup(page, {
+        baseUrl,
+        url,
+        viewportName: args.viewport,
+        viewport: viewportPreset.viewport,
+        config: loaded.config
+      });
+    }
+    const captureRun = await runConfiguredCaptures(page, loaded.config, {
+      selectedTargets: args.targets,
+      capture: {
+        outDir,
+        route: new URL(url).pathname + new URL(url).search,
+        viewport: viewportPreset.viewport
+      },
+      context: {
+        baseUrl,
+        url,
+        viewportName: args.viewport,
+        viewport: viewportPreset.viewport,
+        config: loaded.config
+      }
+    });
+    const result = {
+      ok: captureRun.probes.failures.length === 0,
+      configName,
+      configPath: loaded.path,
+      url,
+      baseUrl,
+      viewportName: args.viewport,
+      viewport: viewportPreset.viewport,
+      outDir: captureRun.outDir,
+      captures: captureRun.captures,
+      probes: captureRun.probes
+    };
+    result.exitCode = result.ok ? 0 : 1;
+    result.json = args.json;
+    return result;
+  } finally {
+    await context?.close?.();
+    await browser.close();
+  }
+};
+
+const main = async () => {
+  let json = process.argv.includes('--json');
+  try {
+    const result = await runCaptureCli();
+    json = result.json;
+    if (json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else if (result.help) {
+      console.log(result.text);
+    } else {
+      printHumanSummary(result);
+    }
+    process.exitCode = result.exitCode;
+  } catch (error) {
+    if (json) {
+      console.log(JSON.stringify({
+        ok: false,
+        error: error?.message || String(error)
+      }, null, 2));
+    } else {
+      console.error(error?.stack || error?.message || String(error));
+    }
+    process.exitCode = 1;
+  }
+};
+
+const isMain = (() => {
+  try {
+    return path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+})();
+
+if (isMain) {
+  main();
+}
+
+export {
+  VIEWPORT_PRESETS,
+  buildCaptureUrl,
+  loadConfig,
+  normalizeCaptureStates,
+  npmConfigArgsFromEnv,
+  parseCliArgs,
+  runCaptureCli,
+  selectTargets
+};
diff --git a/scripts/lint-globals.js b/scripts/lint-globals.js
new file mode 100644
index 00000000..93dcc76d
--- /dev/null
+++ b/scripts/lint-globals.js
@@ -0,0 +1,123 @@
+const readonly = 'readonly';
+
+export const browserGlobals = Object.freeze({
+  AbortController: readonly,
+  Audio: readonly,
+  Blob: readonly,
+  CanvasRenderingContext2D: readonly,
+  CompressionStream: readonly,
+  CustomEvent: readonly,
+  DOMParser: readonly,
+  DecompressionStream: readonly,
+  Event: readonly,
+  File: readonly,
+  FileReader: readonly,
+  FormData: readonly,
+  HTMLCanvasElement: readonly,
+  HTMLElement: readonly,
+  HTMLImageElement: readonly,
+  Image: readonly,
+  ImageBitmap: readonly,
+  ImageData: readonly,
+  IndexedDB: readonly,
+  KeyboardEvent: readonly,
+  MouseEvent: readonly,
+  MutationObserver: readonly,
+  OffscreenCanvas: readonly,
+  Path2D: readonly,
+  PointerEvent: readonly,
+  ResizeObserver: readonly,
+  Request: readonly,
+  TextDecoder: readonly,
+  TextEncoder: readonly,
+  URL: readonly,
+  URLSearchParams: readonly,
+  WebSocket: readonly,
+  WebAssembly: readonly,
+  XMLHttpRequest: readonly,
+  atob: readonly,
+  btoa: readonly,
+  cancelAnimationFrame: readonly,
+  caches: readonly,
+  clearInterval: readonly,
+  clearTimeout: readonly,
+  console: readonly,
+  createImageBitmap: readonly,
+  crypto: readonly,
+  document: readonly,
+  fetch: readonly,
+  globalThis: readonly,
+  history: readonly,
+  indexedDB: readonly,
+  localStorage: readonly,
+  location: readonly,
+  navigator: readonly,
+  performance: readonly,
+  queueMicrotask: readonly,
+  requestAnimationFrame: readonly,
+  self: readonly,
+  sessionStorage: readonly,
+  setInterval: readonly,
+  setTimeout: readonly,
+  structuredClone: readonly,
+  window: readonly
+});
+
+export const nodeGlobals = Object.freeze({
+  Buffer: readonly,
+  __dirname: readonly,
+  __filename: readonly,
+  clearImmediate: readonly,
+  exports: readonly,
+  global: readonly,
+  module: readonly,
+  process: readonly,
+  require: readonly,
+  setImmediate: readonly
+});
+
+export const testGlobals = Object.freeze({
+  after: readonly,
+  afterEach: readonly,
+  before: readonly,
+  beforeEach: readonly,
+  context: readonly,
+  describe: readonly,
+  expect: readonly,
+  it: readonly,
+  suite: readonly,
+  test: readonly
+});
+
+export const thirdPartyBrowserGlobals = Object.freeze({
+  $: readonly,
+  JSZip: readonly,
+  WebMidi: readonly,
+  jQuery: readonly
+});
+
+export const projectRuntimeGlobals = Object.freeze({
+  Lemmings: readonly,
+  ShowDebug: readonly,
+  lemmings: readonly,
+  winH: readonly,
+  winW: readonly,
+  worldH: readonly,
+  worldW: readonly
+});
+
+export const lintGlobals = Object.freeze({
+  ...browserGlobals,
+  ...nodeGlobals
+});
+
+export const testLintGlobals = Object.freeze({
+  ...testGlobals,
+  ...thirdPartyBrowserGlobals,
+  ...projectRuntimeGlobals
+});
+
+export const checkUndefinedGlobals = Object.freeze({
+  ...lintGlobals,
+  ...testLintGlobals
+});
diff --git a/scripts/processHtmlFile.js b/scripts/processHtmlFile.js
index 1a871b2b..95dfff0d 100644
--- a/scripts/processHtmlFile.js
+++ b/scripts/processHtmlFile.js
@@ -4,22 +4,84 @@ import { load } from 'cheerio';
 import { pathToFileURL } from 'url';
 
 /**
- * Parse an HTML file and return JavaScript snippets found in
- * <script> tags or inline event handler attributes.
- * Each snippet includes the code and start/end indices when available.
+ * Parse an HTML file and extract JavaScript snippets from inline `<script>`
+ * tags and inline event-handler attributes (`onclick`, `onchange`, ...).
+ *
+ * Behavior flags:
+ * - `rewritePaths`: rewrites relative `src`/`href` values to `file://` URLs.
+ * - `inline`: inlines relative script/style assets into the HTML output.
+ * - `includeExternalScripts`: adds discovered relative script entrypoints to
+ *   `entryScripts` for follow-up scanning by callers.
+ *
+ * Return shape:
+ * - default: `snippets[]`
+ * - with `includeExternalScripts`: `{ snippets, entryScripts }`
+ * - with `rewritePaths` or `inline`: `{ snippets, html, entryScripts }`
+ *
  * @param {string} filePath
- * @returns {Array<{code:string,loc?:{start?:number,end?:number},type:string,attr?:string}>}
+ * @param {{
+ *   rewritePaths?: boolean,
+ *   inline?: boolean,
+ *   includeExternalScripts?: boolean
+ * }} [options]
+ * @returns {Array<{code:string,loc?:{start?:number,end?:number},type:string,attr?:string}> | {
+ *   snippets: Array<{code:string,loc?:{start?:number,end?:number},type:string,attr?:string}>,
+ *   html?: string,
+ *   entryScripts: string[]
+ * }}
  */
 export function processHtmlFile(filePath, options = {}) {
   const html = fs.readFileSync(filePath, 'utf8');
   const dir = path.dirname(filePath);
-  const { rewritePaths = false, inline = false } = options;
+  const { rewritePaths = false, inline = false, includeExternalScripts = false } = options;
   const $ = load(html, { sourceCodeLocationInfo: true });
   const snippets = [];
+  const entryScripts = [];
+  const entryScriptSet = new Set();
+  const URI_SCHEME_RE = /^[a-z][a-z0-9+.-]*:/i;
+
+  function escapeInlineStyleText(css) {
+    return String(css || '').replace(/<\/style/gi, '<\\/style');
+  }
+
+  function splitAssetReference(value) {
+    const raw = String(value || '').trim();
+    if (!raw) return { pathPart: '', suffix: '' };
+    const markerIndex = raw.search(/[?#]/);
+    if (markerIndex < 0) {
+      return { pathPart: raw, suffix: '' };
+    }
+    return {
+      pathPart: raw.slice(0, markerIndex),
+      suffix: raw.slice(markerIndex)
+    };
+  }
+
+  function isRelative(p) {
+    if (typeof p !== 'string') return false;
+    const { pathPart } = splitAssetReference(p);
+    if (!pathPart) return false;
+    if (pathPart.startsWith('//')) return false;
+    if (URI_SCHEME_RE.test(pathPart)) return false;
+    if (path.isAbsolute(pathPart)) return false;
+    return true;
+  }
 
   $('script').each((i, elem) => {
     const src = $(elem).attr('src');
-    if (src) return; // ignore external scripts for snippet extraction
+    if (src) {
+      if (includeExternalScripts && isRelative(src)) {
+        const { pathPart } = splitAssetReference(src);
+        if (pathPart) {
+          const resolved = path.resolve(dir, pathPart);
+          if (!entryScriptSet.has(resolved)) {
+            entryScriptSet.add(resolved);
+            entryScripts.push(resolved);
+          }
+        }
+      }
+      return;
+    }
 
     const code = $(elem).html() || '';
     const loc = {};
@@ -47,29 +109,30 @@ export function processHtmlFile(filePath, options = {}) {
   });
 
   if (rewritePaths || inline) {
-    function isRelative(p) {
-      return typeof p === 'string' && !/^(?:[a-z]+:)?\/\//i.test(p);
-    }
-
     $('*[src], link[href]').each((i, elem) => {
       const attr = elem.attribs.src ? 'src' : 'href';
       const val = $(elem).attr(attr);
       if (!isRelative(val)) return;
-      const abs = path.resolve(dir, val);
+      const { pathPart, suffix } = splitAssetReference(val);
+      if (!pathPart) return;
+      const abs = path.resolve(dir, pathPart);
       if (inline && elem.name === 'script') {
         const code = fs.readFileSync(abs, 'utf8');
         $(elem).removeAttr('src');
         $(elem).text(code);
       } else if (inline && elem.name === 'link' && $(elem).attr('rel') === 'stylesheet') {
         const css = fs.readFileSync(abs, 'utf8');
-        $(elem).replaceWith(`<style>${css}</style>`);
+        const styleElem = $('<style></style>');
+        styleElem.text(escapeInlineStyleText(css));
+        $(elem).replaceWith(styleElem);
       } else {
-        $(elem).attr(attr, pathToFileURL(abs).href);
+        $(elem).attr(attr, `${pathToFileURL(abs).href}${suffix}`);
       }
     });
   }
 
   const output = $.html();
-  if (rewritePaths || inline) return { snippets, html: output };
+  if (rewritePaths || inline) return { snippets, html: output, entryScripts };
+  if (includeExternalScripts) return { snippets, entryScripts };
   return snippets;
 }
diff --git a/scripts/runTests.js b/scripts/runTests.js
index 87ab5972..838d101c 100644
--- a/scripts/runTests.js
+++ b/scripts/runTests.js
@@ -1,31 +1,565 @@
 #!/usr/bin/env node
+import path from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
 
-const CATEGORY_PATTERNS = {
-  core: ['test/*game*.test.js'],
-  bench: ['test/bench*.test.js'],
+const require = createRequire(import.meta.url);
+const mochaBin = require.resolve('mocha/bin/mocha.js');
+const eslintBin = path.join(
+  path.dirname(require.resolve('eslint/package.json')),
+  'bin',
+  'eslint.js'
+);
+const tscBin = path.join(
+  path.dirname(require.resolve('typescript/package.json')),
+  'bin',
+  'tsc'
+);
+const CHECK_JS_CONFIG = 'tsconfig.checkjs.json';
+const DEFAULT_TEST_RUNTIME_BUDGET_MS = 180000;
+const DEFAULT_BASE_REF_CANDIDATES = Object.freeze([
+  'origin/main',
+  'origin/master',
+  'main',
+  'master'
+]);
+const OFFLINE_TOOL_SOURCE_FILES = Object.freeze(new Set([
+  'tools/archiveDir.js',
+  'tools/cleanExports.js',
+  'tools/packLevels.js',
+  'tools/packPipeline.js'
+]));
+
+const RUNTIME_GUARD_TARGETS = Object.freeze([
+  'js/app/**/*.js',
+  'js/editor/**/*.js',
+  'js/game/**/*.js',
+  'js/lemmings/**/*.js',
+  'js/midi/**/*.js',
+  'js/render/**/*.js',
+  'js/util/**/*.js'
+]);
+
+const CATEGORY_PATTERNS = Object.freeze({
+  core: ['--recursive'],
+  game: ['test/*game*.test.js'],
+  bench: ['test/*bench*.test.js'],
+  release: ['test/release-readiness.test.js'],
   workflow: ['test/*workflow*.test.js'],
   tools: ['test/tools/*.test.js'],
   'offline-tools': ['test/offline-tools/*.test.js'],
-  editor: ['test/editor/*.test.js']
+  editor: [
+    'test/editor/*.test.js',
+    'test/editor-*.test.js',
+    'test/input/editor-*.test.js'
+  ]
+});
+
+const CATEGORY_ORDER = Object.freeze([
+  'core',
+  'game',
+  'editor',
+  'tools',
+  'offline-tools',
+  'bench',
+  'release',
+  'workflow'
+]);
+const CHANGED_FILE_CATEGORY_RULES = Object.freeze([
+  {
+    category: 'release',
+    matches: normalized => (
+      normalized === 'docs/release-readiness.md' ||
+      normalized.startsWith('scripts/check-release-readiness') ||
+      normalized === 'test/release-readiness.test.js'
+    )
+  },
+  {
+    category: 'editor',
+    matches: normalized => (
+      normalized.startsWith('js/editor/') ||
+      normalized.startsWith('js/app/editor') ||
+      normalized.startsWith('js/input/Editor') ||
+      normalized.startsWith('css/editor') ||
+      normalized.startsWith('test/editor/') ||
+      /^test\/editor-.*\.test\.js$/.test(normalized) ||
+      /^test\/input\/editor-.*\.test\.js$/.test(normalized)
+    )
+  },
+  {
+    category: 'offline-tools',
+    matches: normalized => (
+      normalized.startsWith('tools/offline/') ||
+      normalized.startsWith('test/offline-tools/') ||
+      OFFLINE_TOOL_SOURCE_FILES.has(normalized)
+    )
+  },
+  {
+    category: 'tools',
+    matches: normalized => (
+      normalized.startsWith('tools/') ||
+      normalized.startsWith('test/tools/') ||
+      normalized.startsWith('scripts/check-undefined') ||
+      normalized.startsWith('scripts/check-mcp-client-compat')
+    )
+  },
+  {
+    category: 'bench',
+    matches: normalized => (
+      normalized.startsWith('scripts/bench-') ||
+      /^test\/bench.*\.test\.js$/.test(normalized)
+    )
+  },
+  {
+    category: 'workflow',
+    matches: normalized => (
+      normalized.startsWith('.github/workflows/') ||
+      /^test\/.*workflow.*\.test\.js$/.test(normalized)
+    )
+  },
+  {
+    category: 'core',
+    matches: normalized => (
+      normalized.startsWith('docs/') ||
+      normalized.endsWith('.md') ||
+      normalized === 'README' ||
+      normalized === 'README.md' ||
+      normalized.startsWith('js/') ||
+      normalized.startsWith('test/') ||
+      normalized.startsWith('mcp/') ||
+      normalized.startsWith('scripts/') ||
+      normalized.startsWith('css/') ||
+      normalized === 'package.json'
+    )
+  }
+]);
+
+const parseBoolEnv = (value) => {
+  if (value == null) return false;
+  const normalized = String(value).trim().toLowerCase();
+  return normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on';
+};
+
+const toNumberOrNaN = (value) => {
+  try {
+    return Number(value);
+  } catch {
+    return Number.NaN;
+  }
+};
+
+const resolveRuntimeBudgetMs = (value) => {
+  const parsed = toNumberOrNaN(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_TEST_RUNTIME_BUDGET_MS;
+  return Math.trunc(parsed);
 };
 
-const categories = process.argv.slice(2);
+const parseCliArgs = (argv = []) => {
+  const result = {
+    changed: false,
+    baseRef: null,
+    printSelection: false,
+    categories: []
+  };
 
-if (categories.length === 0) {
-  const res = spawnSync('mocha', ['--recursive'], { stdio: 'inherit' });
-  process.exit(res.status);
-}
+  for (const rawArg of argv) {
+    const arg = String(rawArg || '');
+    if (!arg) continue;
+    if (arg === '--changed') {
+      result.changed = true;
+      continue;
+    }
+    if (arg.startsWith('--base=')) {
+      const value = arg.slice('--base='.length).trim();
+      if (!value) {
+        throw new Error('Missing value for --base');
+      }
+      result.baseRef = value;
+      continue;
+    }
+    if (arg === '--print-selection' || arg === '--dry-run') {
+      result.printSelection = true;
+      continue;
+    }
+    if (arg.startsWith('--')) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+    result.categories.push(arg);
+  }
+
+  return result;
+};
+
+const normalizeFilePath = (filePath) => String(filePath || '').replace(/\\/g, '/');
+
+const inferCategoriesFromChangedFiles = (files) => {
+  const categories = new Set();
+  if (!Array.isArray(files) || files.length === 0) {
+    categories.add('core');
+    return Array.from(categories);
+  }
+
+  for (const file of files) {
+    const normalized = normalizeFilePath(file);
+    if (!normalized) continue;
+    for (const rule of CHANGED_FILE_CATEGORY_RULES) {
+      if (!rule.matches(normalized)) continue;
+      categories.add(rule.category);
+      break;
+    }
+  }
+
+  if (categories.size === 0) {
+    categories.add('core');
+  }
+  return Array.from(categories).sort((a, b) => a.localeCompare(b));
+};
+
+const defaultRunGitCommand = (args) => spawnSync('git', args, { encoding: 'utf8' });
 
-const patterns = [];
-for (const cat of categories) {
-  const globs = CATEGORY_PATTERNS[cat];
-  if (!globs) {
-    console.error(`Unknown category: ${cat}`);
-    process.exit(1);
+const readGitFileList = (args, runGitCommand = defaultRunGitCommand) => {
+  const result = runGitCommand(args);
+  if (!result || result.error || result.status !== 0) {
+    return null;
   }
-  patterns.push(...globs);
+  const stdout = String(result.stdout || '');
+  return stdout
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+};
+
+const readGitScalar = (args, runGitCommand = defaultRunGitCommand) => {
+  const result = runGitCommand(args);
+  if (!result || result.error || result.status !== 0) {
+    return null;
+  }
+  const stdout = String(result.stdout || '').trim();
+  return stdout || null;
+};
+
+const gitRefExists = (ref, runGitCommand = defaultRunGitCommand) => {
+  if (!ref) return false;
+  return readGitScalar(['rev-parse', '--verify', '--quiet', ref], runGitCommand) != null;
+};
+
+const resolveBaseRef = ({ baseRef = null, runGitCommand = defaultRunGitCommand } = {}) => {
+  if (baseRef) {
+    return {
+      ref: baseRef,
+      source: 'explicit'
+    };
+  }
+
+  const upstream = readGitScalar(
+    ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}'],
+    runGitCommand
+  );
+  if (upstream) {
+    return {
+      ref: upstream,
+      source: 'upstream'
+    };
+  }
+
+  const remoteHead = readGitScalar(
+    ['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'],
+    runGitCommand
+  );
+  if (remoteHead) {
+    return {
+      ref: remoteHead,
+      source: 'origin-head'
+    };
+  }
+
+  for (const candidate of DEFAULT_BASE_REF_CANDIDATES) {
+    if (!gitRefExists(candidate, runGitCommand)) continue;
+    return {
+      ref: candidate,
+      source: 'fallback'
+    };
+  }
+
+  return null;
+};
+
+const collectChangedFiles = ({ baseRef, runGitCommand = defaultRunGitCommand } = {}) => {
+  if (!baseRef) return null;
+  const files = new Set();
+  const baseSpec = `${baseRef}...HEAD`;
+
+  const compared = readGitFileList(['diff', '--name-only', '--diff-filter=ACMRD', baseSpec], runGitCommand);
+  if (!compared) return null;
+  for (const file of compared) files.add(file);
+
+  const staged = readGitFileList(['diff', '--name-only', '--cached', '--diff-filter=ACMRD'], runGitCommand) || [];
+  for (const file of staged) files.add(file);
+
+  const unstaged = readGitFileList(['diff', '--name-only', '--diff-filter=ACMRD'], runGitCommand) || [];
+  for (const file of unstaged) files.add(file);
+  const untracked = readGitFileList(['ls-files', '--others', '--exclude-standard'], runGitCommand) || [];
+  for (const file of untracked) files.add(file);
+
+  return Array.from(files).sort((a, b) => a.localeCompare(b));
+};
+
+const formatSelectionLines = ({
+  resolvedBase = null,
+  changedFiles = null,
+  categories = [],
+  mochaArgs = []
+} = {}) => {
+  const lines = [];
+  if (resolvedBase) {
+    lines.push(`Resolved base ref: ${resolvedBase.ref} (${resolvedBase.source})`);
+  } else {
+    lines.push('Resolved base ref: none');
+  }
+  if (Array.isArray(changedFiles)) {
+    lines.push(`Changed files (${changedFiles.length}): ${changedFiles.join(', ') || '(none)'}`);
+  } else {
+    lines.push('Changed files: unavailable');
+  }
+  lines.push(`Selected categories: ${categories.join(', ') || '(none)'}`);
+  lines.push(`Mocha args: ${mochaArgs.join(' ') || '(none)'}`);
+  return lines;
+};
+
+const validateCategories = (categories) => {
+  for (const category of categories) {
+    if (!CATEGORY_PATTERNS[category]) {
+      throw new Error(`Unknown category: ${category}`);
+    }
+  }
+};
+
+const buildMochaArgsForCategories = (categories) => {
+  const unique = new Set(categories);
+  validateCategories(unique);
+  if (unique.has('core')) {
+    return ['--recursive'];
+  }
+
+  const args = [];
+  for (const category of CATEGORY_ORDER) {
+    if (!unique.has(category)) continue;
+    args.push(...CATEGORY_PATTERNS[category]);
+  }
+  return args.length ? args : ['--recursive'];
+};
+
+const runMocha = (
+  args,
+  {
+    spawn = spawnSync,
+    log = console,
+    exit = process.exit,
+    enforceBudget = false,
+    budgetMs = DEFAULT_TEST_RUNTIME_BUDGET_MS,
+    preRunElapsedMs = 0
+  } = {}
+) => {
+  const mochaStart = Date.now();
+  const res = spawn(process.execPath, [mochaBin, ...args], { stdio: 'inherit' });
+  const mochaElapsedMs = Math.max(0, Date.now() - mochaStart);
+  const totalElapsedMs = preRunElapsedMs + mochaElapsedMs;
+  if (res.error) {
+    log.error(`Failed to run mocha: ${res.error.message}`);
+    exit(1);
+    return;
+  }
+  if (typeof res.status !== 'number') {
+    log.error('Mocha exited without a status code.');
+    exit(1);
+    return;
+  }
+  if (res.status === 0) {
+    log.log(`Test runtime: ${(totalElapsedMs / 1000).toFixed(2)}s (budget ${(budgetMs / 1000).toFixed(2)}s)`);
+    if (enforceBudget && totalElapsedMs > budgetMs) {
+      log.error(`Test runtime budget exceeded: ${totalElapsedMs}ms > ${budgetMs}ms`);
+      exit(1);
+      return;
+    }
+  }
+  exit(res.status);
+};
+
+const runRuntimeGlobalGuard = (
+  {
+    spawn = spawnSync,
+    log = console,
+    exit = process.exit
+  } = {}
+) => {
+  const args = ['--max-warnings=0', ...RUNTIME_GUARD_TARGETS];
+  const res = spawn(process.execPath, [eslintBin, ...args], { stdio: 'inherit' });
+  if (res.error) {
+    log.error(`Failed to run runtime global guard: ${res.error.message}`);
+    exit(1);
+    return false;
+  }
+  if (typeof res.status !== 'number') {
+    log.error('Runtime global guard exited without a status code.');
+    exit(1);
+    return false;
+  }
+  if (res.status !== 0) {
+    exit(res.status);
+    return false;
+  }
+  return true;
+};
+
+const runCriticalTypecheckGuard = (
+  {
+    spawn = spawnSync,
+    log = console,
+    exit = process.exit
+  } = {}
+) => {
+  const args = ['-p', CHECK_JS_CONFIG, '--pretty', 'false'];
+  const res = spawn(process.execPath, [tscBin, ...args], { stdio: 'inherit' });
+  if (res.error) {
+    log.error(`Failed to run critical typecheck guard: ${res.error.message}`);
+    exit(1);
+    return false;
+  }
+  if (typeof res.status !== 'number') {
+    log.error('Critical typecheck guard exited without a status code.');
+    exit(1);
+    return false;
+  }
+  if (res.status !== 0) {
+    exit(res.status);
+    return false;
+  }
+  return true;
+};
+
+const main = (
+  argv = process.argv.slice(2),
+  {
+    spawn = spawnSync,
+    runGitCommand = defaultRunGitCommand,
+    log = console,
+    exit = process.exit
+  } = {}
+) => {
+  const runStartMs = Date.now();
+  const enforceRuntimeBudget = parseBoolEnv(process.env.LEMMINGS_TEST_ENFORCE_BUDGET);
+  const runtimeBudgetMs = resolveRuntimeBudgetMs(process.env.LEMMINGS_TEST_BUDGET_MS);
+  let parsed;
+  try {
+    parsed = parseCliArgs(argv);
+  } catch (error) {
+    log.error(error.message);
+    exit(1);
+    return;
+  }
+
+  const categories = new Set(parsed.categories);
+  let resolvedBase = null;
+  let changedFiles = null;
+
+  if (parsed.changed) {
+    resolvedBase = resolveBaseRef({
+      baseRef: parsed.baseRef,
+      runGitCommand
+    });
+    if (!resolvedBase) {
+      log.warn('Unable to resolve a safe base ref from git; falling back to full suite.');
+      categories.add('core');
+    } else {
+      changedFiles = collectChangedFiles({
+        baseRef: resolvedBase.ref,
+        runGitCommand
+      });
+    }
+    if (!changedFiles) {
+      if (resolvedBase) {
+        log.warn(`Unable to resolve changed files from git for base ${resolvedBase.ref}; falling back to full suite.`);
+        categories.add('core');
+      }
+    } else {
+      const inferred = inferCategoriesFromChangedFiles(changedFiles);
+      for (const category of inferred) {
+        categories.add(category);
+      }
+      log.log(`Changed-file test selection: ${Array.from(categories).sort().join(', ')}`);
+      log.log(`Changed-file base ref: ${resolvedBase.ref} (${resolvedBase.source})`);
+    }
+  }
+
+  if (categories.size === 0) {
+    categories.add('core');
+  }
+
+  let mochaArgs;
+  try {
+    mochaArgs = buildMochaArgsForCategories(Array.from(categories));
+  } catch (error) {
+    log.error(error.message);
+    exit(1);
+    return;
+  }
+
+  if (parsed.printSelection) {
+    const selectionLines = formatSelectionLines({
+      resolvedBase,
+      changedFiles,
+      categories: Array.from(categories).sort((a, b) => a.localeCompare(b)),
+      mochaArgs
+    });
+    for (const line of selectionLines) {
+      log.log(line);
+    }
+    exit(0);
+    return;
+  }
+
+  if (!runRuntimeGlobalGuard({ spawn, log, exit })) {
+    return;
+  }
+  if (!runCriticalTypecheckGuard({ spawn, log, exit })) {
+    return;
+  }
+  const preMochaElapsedMs = Math.max(0, Date.now() - runStartMs);
+  runMocha(mochaArgs, {
+    spawn,
+    log,
+    exit,
+    enforceBudget: enforceRuntimeBudget,
+    budgetMs: runtimeBudgetMs,
+    preRunElapsedMs: preMochaElapsedMs
+  });
+};
+
+const isMain = (() => {
+  try {
+    return path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch (error) {
+    return false;
+  }
+})();
+
+if (isMain) {
+  main();
 }
 
-const res = spawnSync('mocha', patterns, { stdio: 'inherit' });
-process.exit(res.status);
+export {
+  CATEGORY_PATTERNS,
+  RUNTIME_GUARD_TARGETS,
+  buildMochaArgsForCategories,
+  collectChangedFiles,
+  formatSelectionLines,
+  inferCategoriesFromChangedFiles,
+  main,
+  parseCliArgs,
+  parseBoolEnv,
+  resolveBaseRef,
+  runCriticalTypecheckGuard,
+  resolveRuntimeBudgetMs,
+  runRuntimeGlobalGuard
+};
diff --git a/test/action-drown-explode.test.js b/test/action-drown-explode.test.js
index b4a5d235..124bd515 100644
--- a/test/action-drown-explode.test.js
+++ b/test/action-drown-explode.test.js
@@ -24,7 +24,7 @@ class StubLevel {
   constructor() { this.ground = new Set(); this.clearedMasks = []; }
   key(x, y) { return `${x},${y}`; }
   hasGroundAt(x, y) { return this.ground.has(this.key(x, y)); }
-  clearGroundWithMask(mask, x, y) { this.clearedMasks.push({ mask, x, y }); return true; }
+  clearGroundWithMask(mask, x, y, opts = null) { this.clearedMasks.push({ mask, x, y, opts }); return true; }
 }
 
 class StubTriggerManager {
@@ -72,11 +72,13 @@ describe('ActionDrowningSystem behavior', function() {
   });
 
   it('draw records death once frame >= 15', function() {
+    const miniMap = { deaths: 0, addDeath() { this.deaths++; } };
     const sys = new ActionDrowningSystem(stubSprites);
+    sys.setRuntime({ miniMap });
     const lem = new StubLemming();
     lem.frameIndex = 15;
     sys.draw({ drawFrame() {} }, lem);
-    expect(globalThis.lemmings.game.lemmingManager.miniMap.deaths).to.equal(1);
+    expect(miniMap.deaths).to.equal(1);
   });
 });
 
@@ -91,6 +93,7 @@ describe('ActionExplodingSystem behavior', function() {
     expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
     expect(tm.removed[0]).to.equal(lem);
     expect(level.clearedMasks.length).to.equal(1);
+    expect(level.clearedMasks[0].opts).to.eql({ revealSteel: true });
 
     // at frame 51 -> 52 should exit
     lem.frameIndex = 51;
diff --git a/test/action-systems.01-action-systems-process.test.js b/test/action-systems.01-action-systems-process.test.js
new file mode 100644
index 00000000..6f05ead5
--- /dev/null
+++ b/test/action-systems.01-action-systems-process.test.js
@@ -0,0 +1,437 @@
+import { expect } from 'chai';
+import { Lemmings, setTestAppContext, useGlobalLemmings } from './helpers/lemmings.js';
+import { getAppContext } from '../js/core/dependencies.js';
+import { ActionBashSystem } from '../js/actions/ActionBashSystem.js';
+import { ActionBlockerSystem } from '../js/actions/ActionBlockerSystem.js';
+import { ActionBuildSystem } from '../js/actions/ActionBuildSystem.js';
+import { ActionClimbSystem } from '../js/actions/ActionClimbSystem.js';
+import { ActionCountdownSystem } from '../js/actions/ActionCountdownSystem.js';
+import { ActionDiggSystem } from '../js/actions/ActionDiggSystem.js';
+import { ActionDrowningSystem } from '../js/actions/ActionDrowningSystem.js';
+import { ActionExitingSystem } from '../js/actions/ActionExitingSystem.js';
+import { ActionExplodingSystem } from '../js/actions/ActionExplodingSystem.js';
+import { ActionFallSystem } from '../js/actions/ActionFallSystem.js';
+import { ActionFloatingSystem } from '../js/actions/ActionFloatingSystem.js';
+import { ActionFryingSystem } from '../js/actions/ActionFryingSystem.js';
+import { ActionHoistSystem } from '../js/actions/ActionHoistSystem.js';
+import { ActionJumpSystem } from '../js/actions/ActionJumpSystem.js';
+import { ActionMineSystem } from '../js/actions/ActionMineSystem.js';
+import { ActionOhNoSystem } from '../js/actions/ActionOhNoSystem.js';
+import { ActionShrugSystem } from '../js/actions/ActionShrugSystem.js';
+import { ActionSplatterSystem } from '../js/actions/ActionSplatterSystem.js';
+import { ActionWalkSystem } from '../js/actions/ActionWalkSystem.js';
+import { SoundEventTypes, SoundEffectIds } from '../js/game/SoundEvents.js';
+import '../js/level/Trigger.js';
+import '../js/level/TriggerTypes.js';
+import '../js/lemmings/LemmingStateType.js';
+import '../js/lemmings/SpriteTypes.js';
+import '../js/render/MaskTypes.js';
+import '../js/lemmings/Lemming.js';
+import { runScenarioTable } from './support/scenario-table.js';
+
+const makeMiniMap = () => ({
+  addDeath() {},
+  invalidateRegion() {},
+  onGroundChanged() {}
+});
+
+const makeLemmings = () => ({
+  game: {
+    lemmingManager: { miniMap: makeMiniMap() },
+    showDebug: false
+  }
+});
+
+// minimal global environment
+useGlobalLemmings(makeLemmings);
+globalThis.winW = 800;
+globalThis.winH = 600;
+
+const stubSprites = { getAnimation: () => ({ getFrame() { return {}; } }) };
+
+class StubLemming {
+  constructor(x = 0, y = 0) {
+    this.x = x;
+    this.y = y;
+    this.lookRight = true;
+    this.frameIndex = 0;
+    this.state = 0;
+    this.canClimb = false;
+    this.hasParachute = false;
+    this.disabled = false;
+    this.countdown = 0;
+  }
+  getDirection() { return this.lookRight ? 'right' : 'left'; }
+  disable() { this.disabled = true; }
+  setCountDown(act) { this.countdownAction = act; if (this.countdown > 0) return false; this.countdown = 80; return true; }
+  getCountDownTime() { return 8 - (this.countdown >> 4); }
+}
+
+class StubLevel {
+  constructor() {
+    this.ground = new Set();
+    this.clearedMasks = [];
+    this.setGroundCalls = [];
+    this.clearedPoints = [];
+    this.steelUnder = false;
+    this.arrowUnder = false;
+    this.stepHeight = null;
+    this.gapDepth = null;
+    this.steelGround = () => false;
+    this.arrowAt = () => false;
+  }
+  key(x, y) { return `${x},${y}`; }
+  hasGroundAt(x, y) { return this.ground.has(this.key(x, y)); }
+  getGroundMaskLayer() {
+    const self = this;
+    return {
+      hasGroundAt(x, y) { return self.hasGroundAt(x, y); },
+      getSubLayer(x, y, w, h) {
+        return { width: w, height: h, hasGroundAt(dx, dy) { return self.hasGroundAt(x + dx, y + dy); } };
+      },
+      getColumnStepHeight(x, yTop, height) {
+        if (self.stepHeight !== null && self.stepHeight !== undefined) {
+          return self.stepHeight;
+        }
+        const end = yTop + height - 1;
+        for (let i = 0; i < height; i++) {
+          const y = end - i;
+          if (!self.hasGroundAt(x, y)) return i;
+        }
+        return height;
+      },
+      getColumnGapDepth(x, yTop, height) {
+        if (self.gapDepth !== null && self.gapDepth !== undefined) {
+          return self.gapDepth;
+        }
+        for (let i = 0; i < height; i++) {
+          const y = yTop + i;
+          if (self.hasGroundAt(x, y)) return i + 1;
+        }
+        return height + 1;
+      }
+    };
+  }
+  clearGroundWithMask(mask, x, y) { this.clearedMasks.push({ mask, x, y }); }
+  clearGroundWithMaskCount(mask, x, y) {
+    this.clearGroundWithMask(mask, x, y);
+    return this.clearCount ?? 1;
+  }
+  hasSteelUnderMask() { return this.steelUnder; }
+  hasArrowUnderMask() { return this.arrowUnder; }
+  isArrowAt(x, y, direction) { return this.arrowAt(x, y, direction); }
+  clearGroundAt(x, y) { this.clearedPoints.push(this.key(x, y)); this.ground.delete(this.key(x, y)); }
+  setGroundAt(x, y) { this.setGroundCalls.push(this.key(x, y)); this.ground.add(this.key(x, y)); }
+  isSteelGround(x, y) { return this.steelGround(this.key(x, y)); }
+  isOutOfLevel(y) { return y < 0 || y >= 50; }
+}
+
+class StubTriggerManager {
+  constructor() { this.added = []; this.removed = []; }
+  add(t) { this.added.push(t); }
+  removeByOwner(o) { this.removed.push(o); }
+}
+
+class StubGVC { constructor() { this.count = 0; } addSurvivor() { this.count++; } }
+
+class DummyMask { constructor() { this.offsetX = 0; this.offsetY = 0; this.width = 0; this.height = 0; } at() { return false; } }
+function stubMasks() {
+  return {
+    GetMask() {
+      return { GetMask() { return new DummyMask(); } };
+    }
+  };
+}
+
+function useSoundBus(calls) {
+  const base = getAppContext() ?? {};
+  return setTestAppContext({
+    ...base,
+    game: {
+      ...(base.game ?? {}),
+      soundEvents: {
+        emitSfx(type, sfxId, data) {
+          calls.push({ type, sfxId, data });
+        }
+      }
+    }
+  });
+}
+
+function withoutSoundBus() {
+  const base = getAppContext() ?? {};
+  return setTestAppContext({
+    ...base,
+    game: {
+      ...(base.game ?? {}),
+      soundEvents: null
+    }
+  });
+}
+
+function withoutLemmingManager() {
+  const base = getAppContext() ?? {};
+  return setTestAppContext({
+    ...base,
+    game: {
+      ...(base.game ?? {}),
+      lemmingManager: null
+    }
+  });
+}
+
+function makeRuntime(calls = [], miniMap = makeMiniMap()) {
+  return {
+    soundEvents: {
+      emitSfx(type, sfxId, data) {
+        calls.push({ type, sfxId, data });
+      }
+    },
+    miniMap
+  };
+}
+
+function attachRuntime(sys, calls = [], miniMap = makeMiniMap()) {
+  sys.setRuntime?.(makeRuntime(calls, miniMap));
+  return sys;
+}
+
+// helpers for controlled Action systems
+class TestBashSystem extends ActionBashSystem {
+  constructor(gap, horiz) { super(stubSprites, stubMasks()); this.gap = gap; this.horiz = horiz; }
+  findGapDelta() { return this.gap; }
+  findHorizontalSpace() { return this.horiz; }
+}
+
+class TestMineSystem extends ActionMineSystem {
+  constructor(haveSteel, haveArrow) { super(stubSprites, stubMasks()); this.haveSteel = haveSteel; this.haveArrow = haveArrow; this.cleared = 0; }
+  process(level, lem) { return super.process(level, lem); }
+}
+
+describe('Action Systems process()', function() {
+  it('ActionBashSystem handles masks and gaps', function() {
+    const level = new StubLevel();
+    const lem = new StubLemming();
+    const sys = new TestBashSystem(3, 0);
+    lem.frameIndex = 10; // state 11 after ++
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.FALLING);
+
+    const sys2 = new TestBashSystem(0, 4);
+    lem.frameIndex = 1; // ->2
+    sys2.process(level, lem);
+    expect(level.clearedMasks).to.have.length(1);
+
+    level.steelUnder = true;
+    lem.frameIndex = 2; // ->3
+    expect(sys2.process(level, lem)).to.equal(Lemmings.LemmingStateType.SHRUG);
+    level.steelUnder = false;
+
+    lem.frameIndex = 4; // ->5 horiz space 4
+    expect(sys2.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
+
+    lem.frameIndex = 3; // ->4 horiz space !=4
+    expect(sys2.process(level, lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
+  });
+
+  it('ActionBashSystem moves horizontally after frame 10', function() {
+    const level = new StubLevel();
+    const sys = new TestBashSystem(0, 0);
+
+    const lem1 = new StubLemming();
+    lem1.frameIndex = 9; // ->10
+    const x1 = lem1.x;
+    sys.process(level, lem1);
+    expect(lem1.x).to.equal(x1);
+
+    const lem2 = new StubLemming();
+    lem2.frameIndex = 10; // ->11
+    const x2 = lem2.x;
+    expect(sys.process(level, lem2)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
+    expect(lem2.x).to.equal(x2 + 1);
+
+    const lem3 = new StubLemming();
+    lem3.lookRight = false;
+    lem3.frameIndex = 10; // ->11
+    const x3 = lem3.x;
+    sys.process(level, lem3);
+    expect(lem3.x).to.equal(x3 - 1);
+  });
+
+  it('ActionBashSystem keeps bashing when space remains', function() {
+    const level = new StubLevel();
+    const sys = new TestBashSystem(0, 3); // horizontal space < 4
+    const lem = new StubLemming();
+    lem.frameIndex = 4; // ->5
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
+  });
+
+  it('ActionBlockerSystem adds and removes triggers', function() {
+    const level = new StubLevel();
+    const tm = new StubTriggerManager();
+    const sys = new ActionBlockerSystem(stubSprites, tm);
+    const lem = new StubLemming();
+    lem.state = 0;
+    sys.process(level, lem);
+    expect(tm.added.length).to.equal(2);
+    lem.state = 1;
+    level.ground.delete(level.key(lem.x, lem.y + 1));
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.FALLING);
+    expect(tm.removed[0]).to.equal(lem);
+  });
+
+  it('ActionBlockerSystem keeps triggers until ground is lost', function() {
+    const level = new StubLevel();
+    const tm = new StubTriggerManager();
+    const sys = new ActionBlockerSystem(stubSprites, tm);
+    const lem = new StubLemming();
+    level.ground.add(level.key(lem.x, lem.y + 1));
+    lem.state = 0;
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
+    expect(tm.added.length).to.equal(2);
+    expect(tm.removed.length).to.equal(0);
+    lem.state = 1;
+    level.ground.delete(level.key(lem.x, lem.y + 1));
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.FALLING);
+    expect(tm.removed[0]).to.equal(lem);
+  });
+
+  it('ActionBuildSystem lays bricks and shrugs when done', function() {
+    const level = new StubLevel();
+    const sys = new ActionBuildSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.frameIndex = 8; // ->9 brick
+    sys.process(level, lem);
+    expect(level.setGroundCalls).to.have.length(6);
+
+    lem.frameIndex = 15; // ->0
+    lem.state = 11;
+    sys.process(level, lem);
+    expect(lem.state).to.equal(12);
+
+    lem.frameIndex = 15;
+    lem.state = 12;
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.SHRUG);
+  });
+
+  it('ActionClimbSystem hoists or falls', function() {
+    const level = new StubLevel();
+    const sys = new ActionClimbSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.frameIndex = 2; // ->3, below 4 => check top
+    level.ground.delete(level.key(lem.x, lem.y - 7 - 4));
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.HOISTING);
+
+    lem.frameIndex = 4; // ->5, climbing upward
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
+
+    lem.frameIndex = 6; // ->7 >=4 path
+    level.ground.add(level.key(lem.x - 1, lem.y - 9));
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.FALLING);
+  });
+
+  it('ActionClimbSystem triggers HOISTING at the top', function() {
+    const level = new StubLevel();
+    const sys = new ActionClimbSystem(stubSprites);
+    const lem = new StubLemming();
+    // wall continues for two steps but top is clear
+    level.ground.add(level.key(lem.x, lem.y - 8));
+    level.ground.add(level.key(lem.x, lem.y - 9));
+    lem.frameIndex = 2; // ->3 near the top
+    const result = sys.process(level, lem);
+    expect(result).to.equal(Lemmings.LemmingStateType.HOISTING);
+    expect(lem.y).to.equal(-1);
+  });
+
+  it('ActionClimbSystem falls and flips when side blocked', function() {
+    const level = new StubLevel();
+    const sys = new ActionClimbSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.frameIndex = 4; // ->5 climbing up the wall
+    level.ground.add(level.key(lem.x - 1, lem.y - 9));
+    const result = sys.process(level, lem);
+    expect(result).to.equal(Lemmings.LemmingStateType.FALLING);
+    expect(lem.lookRight).to.equal(false);
+    expect(lem.x).to.equal(-2);
+  });
+
+  it('ActionCountdownSystem counts to explosion', function() {
+    const sys = new ActionCountdownSystem({ GetMask() { return new DummyMask(); } });
+    const lem = new StubLemming();
+    lem.countdown = 2;
+    expect(sys.process(new StubLevel(), lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
+    expect(lem.countdown).to.equal(1);
+    lem.countdown = 1;
+    expect(sys.process(new StubLevel(), lem)).to.equal(Lemmings.LemmingStateType.OHNO);
+  });
+
+  it('ActionDiggSystem digs until out', function() {
+    const sys = new ActionDiggSystem(stubSprites);
+    const level = new StubLevel();
+    const lem = new StubLemming();
+    lem.state = 0;
+    sys.process(level, lem);
+    expect(lem.state).to.equal(1);
+
+    lem.state = 1;
+    lem.frameIndex = 7; // ->8 triggers digRow
+    level.isOutOfLevel = () => false;
+    sys.digRow = () => false;
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.FALLING);
+
+    level.isOutOfLevel = () => true;
+    lem.frameIndex = 15; // ->0 but !0 & 0x07 -> 1? Wait 0? We'll set 0.
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.FALLING);
+  });
+
+  it('ActionDrowningSystem toggles direction and exits', function() {
+    const level = new StubLevel();
+    const sys = new ActionDrowningSystem(stubSprites);
+    const lem = new StubLemming();
+    level.ground.add(level.key(lem.x + 8, lem.y));
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
+    expect(lem.disabled).to.equal(true);
+    lem.frameIndex = 15;
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.OUT_OF_LEVEL);
+  });
+
+  it('ActionExitingSystem awards survivor', function() {
+    const gvc = new StubGVC();
+    const sys = new ActionExitingSystem(stubSprites, gvc);
+    const lem = new StubLemming();
+    lem.frameIndex = 7;
+    expect(sys.process(new StubLevel(), lem)).to.equal(Lemmings.LemmingStateType.OUT_OF_LEVEL);
+    expect(gvc.count).to.equal(1);
+  });
+
+  it('ActionExplodingSystem clears mask and exits', function() {
+    const tm = new StubTriggerManager();
+    const sys = new ActionExplodingSystem(stubSprites, stubMasks(), tm, { draw() {} });
+    const level = new StubLevel();
+    const lem = new StubLemming();
+    lem.frameIndex = 0;
+    sys.process(level, lem); // ->1 no clear
+    lem.frameIndex = 1;
+    sys.process(level, lem); // ->2 clears
+    expect(level.clearedMasks).to.have.length.above(0);
+    lem.frameIndex = 51;
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.OUT_OF_LEVEL);
+  });
+
+  it('ActionFallSystem detects splat and float', function() {
+    const level = new StubLevel();
+    const sys = new ActionFallSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.state = 17;
+    lem.hasParachute = true;
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.FLOATING);
+
+    lem.state = 0;
+    level.ground.add(level.key(lem.x, lem.y));
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
+
+    lem.state = Lemmings.Lemming.LEM_MAX_FALLING + 1;
+    lem.hasParachute = false;
+    level.ground.add(level.key(lem.x, lem.y));
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.SPLATTING);
+  });
+});
diff --git a/test/action-systems.02-action-systems-process.test.js b/test/action-systems.02-action-systems-process.test.js
new file mode 100644
index 00000000..b7536df2
--- /dev/null
+++ b/test/action-systems.02-action-systems-process.test.js
@@ -0,0 +1,437 @@
+import { expect } from 'chai';
+import { Lemmings, setTestAppContext, useGlobalLemmings } from './helpers/lemmings.js';
+import { getAppContext } from '../js/core/dependencies.js';
+import { ActionBashSystem } from '../js/actions/ActionBashSystem.js';
+import { ActionBlockerSystem } from '../js/actions/ActionBlockerSystem.js';
+import { ActionBuildSystem } from '../js/actions/ActionBuildSystem.js';
+import { ActionClimbSystem } from '../js/actions/ActionClimbSystem.js';
+import { ActionCountdownSystem } from '../js/actions/ActionCountdownSystem.js';
+import { ActionDiggSystem } from '../js/actions/ActionDiggSystem.js';
+import { ActionDrowningSystem } from '../js/actions/ActionDrowningSystem.js';
+import { ActionExitingSystem } from '../js/actions/ActionExitingSystem.js';
+import { ActionExplodingSystem } from '../js/actions/ActionExplodingSystem.js';
+import { ActionFallSystem } from '../js/actions/ActionFallSystem.js';
+import { ActionFloatingSystem } from '../js/actions/ActionFloatingSystem.js';
+import { ActionFryingSystem } from '../js/actions/ActionFryingSystem.js';
+import { ActionHoistSystem } from '../js/actions/ActionHoistSystem.js';
+import { ActionJumpSystem } from '../js/actions/ActionJumpSystem.js';
+import { ActionMineSystem } from '../js/actions/ActionMineSystem.js';
+import { ActionOhNoSystem } from '../js/actions/ActionOhNoSystem.js';
+import { ActionShrugSystem } from '../js/actions/ActionShrugSystem.js';
+import { ActionSplatterSystem } from '../js/actions/ActionSplatterSystem.js';
+import { ActionWalkSystem } from '../js/actions/ActionWalkSystem.js';
+import { SoundEventTypes, SoundEffectIds } from '../js/game/SoundEvents.js';
+import '../js/level/Trigger.js';
+import '../js/level/TriggerTypes.js';
+import '../js/lemmings/LemmingStateType.js';
+import '../js/lemmings/SpriteTypes.js';
+import '../js/render/MaskTypes.js';
+import '../js/lemmings/Lemming.js';
+import { runScenarioTable } from './support/scenario-table.js';
+
+const makeMiniMap = () => ({
+  addDeath() {},
+  invalidateRegion() {},
+  onGroundChanged() {}
+});
+
+const makeLemmings = () => ({
+  game: {
+    lemmingManager: { miniMap: makeMiniMap() },
+    showDebug: false
+  }
+});
+
+// minimal global environment
+useGlobalLemmings(makeLemmings);
+globalThis.winW = 800;
+globalThis.winH = 600;
+
+const stubSprites = { getAnimation: () => ({ getFrame() { return {}; } }) };
+
+class StubLemming {
+  constructor(x = 0, y = 0) {
+    this.x = x;
+    this.y = y;
+    this.lookRight = true;
+    this.frameIndex = 0;
+    this.state = 0;
+    this.canClimb = false;
+    this.hasParachute = false;
+    this.disabled = false;
+    this.countdown = 0;
+  }
+  getDirection() { return this.lookRight ? 'right' : 'left'; }
+  disable() { this.disabled = true; }
+  setCountDown(act) { this.countdownAction = act; if (this.countdown > 0) return false; this.countdown = 80; return true; }
+  getCountDownTime() { return 8 - (this.countdown >> 4); }
+}
+
+class StubLevel {
+  constructor() {
+    this.ground = new Set();
+    this.clearedMasks = [];
+    this.setGroundCalls = [];
+    this.clearedPoints = [];
+    this.steelUnder = false;
+    this.arrowUnder = false;
+    this.stepHeight = null;
+    this.gapDepth = null;
+    this.steelGround = () => false;
+    this.arrowAt = () => false;
+  }
+  key(x, y) { return `${x},${y}`; }
+  hasGroundAt(x, y) { return this.ground.has(this.key(x, y)); }
+  getGroundMaskLayer() {
+    const self = this;
+    return {
+      hasGroundAt(x, y) { return self.hasGroundAt(x, y); },
+      getSubLayer(x, y, w, h) {
+        return { width: w, height: h, hasGroundAt(dx, dy) { return self.hasGroundAt(x + dx, y + dy); } };
+      },
+      getColumnStepHeight(x, yTop, height) {
+        if (self.stepHeight !== null && self.stepHeight !== undefined) {
+          return self.stepHeight;
+        }
+        const end = yTop + height - 1;
+        for (let i = 0; i < height; i++) {
+          const y = end - i;
+          if (!self.hasGroundAt(x, y)) return i;
+        }
+        return height;
+      },
+      getColumnGapDepth(x, yTop, height) {
+        if (self.gapDepth !== null && self.gapDepth !== undefined) {
+          return self.gapDepth;
+        }
+        for (let i = 0; i < height; i++) {
+          const y = yTop + i;
+          if (self.hasGroundAt(x, y)) return i + 1;
+        }
+        return height + 1;
+      }
+    };
+  }
+  clearGroundWithMask(mask, x, y) { this.clearedMasks.push({ mask, x, y }); }
+  clearGroundWithMaskCount(mask, x, y) {
+    this.clearGroundWithMask(mask, x, y);
+    return this.clearCount ?? 1;
+  }
+  hasSteelUnderMask() { return this.steelUnder; }
+  hasArrowUnderMask() { return this.arrowUnder; }
+  isArrowAt(x, y, direction) { return this.arrowAt(x, y, direction); }
+  clearGroundAt(x, y) { this.clearedPoints.push(this.key(x, y)); this.ground.delete(this.key(x, y)); }
+  setGroundAt(x, y) { this.setGroundCalls.push(this.key(x, y)); this.ground.add(this.key(x, y)); }
+  isSteelGround(x, y) { return this.steelGround(this.key(x, y)); }
+  isOutOfLevel(y) { return y < 0 || y >= 50; }
+}
+
+class StubTriggerManager {
+  constructor() { this.added = []; this.removed = []; }
+  add(t) { this.added.push(t); }
+  removeByOwner(o) { this.removed.push(o); }
+}
+
+class StubGVC { constructor() { this.count = 0; } addSurvivor() { this.count++; } }
+
+class DummyMask { constructor() { this.offsetX = 0; this.offsetY = 0; this.width = 0; this.height = 0; } at() { return false; } }
+function stubMasks() {
+  return {
+    GetMask() {
+      return { GetMask() { return new DummyMask(); } };
+    }
+  };
+}
+
+function useSoundBus(calls) {
+  const base = getAppContext() ?? {};
+  return setTestAppContext({
+    ...base,
+    game: {
+      ...(base.game ?? {}),
+      soundEvents: {
+        emitSfx(type, sfxId, data) {
+          calls.push({ type, sfxId, data });
+        }
+      }
+    }
+  });
+}
+
+function withoutSoundBus() {
+  const base = getAppContext() ?? {};
+  return setTestAppContext({
+    ...base,
+    game: {
+      ...(base.game ?? {}),
+      soundEvents: null
+    }
+  });
+}
+
+function withoutLemmingManager() {
+  const base = getAppContext() ?? {};
+  return setTestAppContext({
+    ...base,
+    game: {
+      ...(base.game ?? {}),
+      lemmingManager: null
+    }
+  });
+}
+
+function makeRuntime(calls = [], miniMap = makeMiniMap()) {
+  return {
+    soundEvents: {
+      emitSfx(type, sfxId, data) {
+        calls.push({ type, sfxId, data });
+      }
+    },
+    miniMap
+  };
+}
+
+function attachRuntime(sys, calls = [], miniMap = makeMiniMap()) {
+  sys.setRuntime?.(makeRuntime(calls, miniMap));
+  return sys;
+}
+
+// helpers for controlled Action systems
+class TestBashSystem extends ActionBashSystem {
+  constructor(gap, horiz) { super(stubSprites, stubMasks()); this.gap = gap; this.horiz = horiz; }
+  findGapDelta() { return this.gap; }
+  findHorizontalSpace() { return this.horiz; }
+}
+
+class TestMineSystem extends ActionMineSystem {
+  constructor(haveSteel, haveArrow) { super(stubSprites, stubMasks()); this.haveSteel = haveSteel; this.haveArrow = haveArrow; this.cleared = 0; }
+  process(level, lem) { return super.process(level, lem); }
+}
+
+describe('Action Systems process()', function() {
+  it('ActionFloatingSystem lands when hitting ground', function() {
+    const sys = new ActionFloatingSystem(stubSprites);
+    const level = new StubLevel();
+    const lem = new StubLemming();
+    level.ground.add(level.key(lem.x, lem.y));
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
+    expect(lem.y).to.equal(0);
+    level.ground.clear();
+    lem.frameIndex = 15;
+    sys.process(level, lem);
+    expect(lem.frameIndex).to.equal(8);
+  });
+
+  it('ActionFloatingSystem trigger sets hasParachute once', function() {
+    const sys = new ActionFloatingSystem(stubSprites);
+    const lem = new StubLemming();
+    expect(sys.triggerLemAction(lem)).to.equal(true);
+    expect(lem.hasParachute).to.equal(true);
+    expect(sys.triggerLemAction(lem)).to.equal(false);
+    expect(lem.hasParachute).to.equal(true);
+  });
+
+  it('opens umbrella mid fall and walks on landing', function() {
+    const fallSys = new ActionFallSystem(stubSprites);
+    const floatSys = new ActionFloatingSystem(stubSprites);
+    const level = new StubLevel();
+    const lem = new StubLemming();
+    lem.state = 17;
+    fallSys.process(level, lem); // fall one step
+    expect(lem.y).to.equal(3);
+    expect(floatSys.triggerLemAction(lem)).to.equal(true);
+    level.ground.add(level.key(lem.x, 5));
+    expect(fallSys.process(level, lem)).to.equal(Lemmings.LemmingStateType.FLOATING);
+    expect(floatSys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
+    expect(lem.y).to.equal(5);
+  });
+
+  it('ActionFryingSystem burns then exits', function() {
+    const level = new StubLevel();
+    const sys = new ActionFryingSystem(stubSprites);
+    const lem = new StubLemming();
+    sys.process(level, lem);
+    expect(lem.disabled).to.equal(true);
+    lem.frameIndex = 13;
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.OUT_OF_LEVEL);
+  });
+
+  it('ActionHoistSystem moves up then walks', function() {
+    const level = new StubLevel();
+    const sys = new ActionHoistSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.frameIndex = 3;
+    sys.process(level, lem);
+    expect(lem.y).to.equal(-2);
+    lem.frameIndex = 7;
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
+  });
+
+  it('ActionJumpSystem jumps up then walks', function() {
+    const level = new StubLevel();
+    level.ground.add(level.key(1, -1));
+    const sys = new ActionJumpSystem(stubSprites);
+    const lem = new StubLemming();
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
+    lem.y = -5;
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
+  });
+
+  it('ActionMineSystem clears ground and falls', function() {
+    const level = new StubLevel();
+    const sys = new ActionMineSystem(stubSprites, stubMasks());
+    const lem = new StubLemming();
+    lem.frameIndex = 1; // ->2 mask clear
+    sys.process(level, lem);
+    expect(level.clearedMasks.length).to.equal(1);
+    lem.frameIndex = 14; // ->15 moves check ground
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.FALLING);
+    level.ground.delete(level.key(lem.x, lem.y));
+    lem.frameIndex = 15; // ->0 case 15
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
+  });
+
+  it('ActionOhNoSystem counts to explode', function() {
+    const level = new StubLevel();
+    const sys = new ActionOhNoSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.frameIndex = 15;
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.EXPLODING);
+  });
+
+  it('ActionShrugSystem returns to walking', function() {
+    const sys = new ActionShrugSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.frameIndex = 7;
+    expect(sys.process(new StubLevel(), lem)).to.equal(Lemmings.LemmingStateType.WALKING);
+  });
+
+  it('ActionSplatterSystem finishes quickly', function() {
+    const sys = new ActionSplatterSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.frameIndex = 15;
+    expect(sys.process(new StubLevel(), lem)).to.equal(Lemmings.LemmingStateType.OUT_OF_LEVEL);
+  });
+
+  it('ActionWalkSystem handles steps and gaps', function() {
+    const sys = new ActionWalkSystem(stubSprites);
+
+    const level1 = new StubLevel();
+    const lem1 = new StubLemming();
+    lem1.canClimb = true;
+    level1.stepHeight = 8;
+    expect(sys.process(level1, lem1)).to.equal(Lemmings.LemmingStateType.CLIMBING);
+
+    const level2 = new StubLevel();
+    const lem2 = new StubLemming();
+    level2.stepHeight = 5;
+    expect(sys.process(level2, lem2)).to.equal(Lemmings.LemmingStateType.JUMPING);
+
+    const level3 = new StubLevel();
+    const lem3 = new StubLemming();
+    level3.stepHeight = 2;
+    expect(sys.process(level3, lem3)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
+
+    const level4 = new StubLevel();
+    const lem4 = new StubLemming();
+    level4.stepHeight = 0;
+    level4.gapDepth = 4;
+    expect(sys.process(level4, lem4)).to.equal(Lemmings.LemmingStateType.FALLING);
+  });
+
+  runScenarioTable([
+    {
+      name: 'ActionBashSystem stops on arrow under mask',
+      apply(level) {
+        level.arrowUnder = true;
+      }
+    },
+    {
+      name: 'ActionBashSystem stops on steel under mask',
+      apply(level) {
+        level.steelUnder = true;
+      }
+    }
+  ], ({ apply }) => {
+    const level = new StubLevel();
+    apply(level);
+    const sys = new TestBashSystem(0, 0);
+    const lem = new StubLemming();
+    lem.frameIndex = 2; // ->3
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.SHRUG);
+    expect(level.clearedMasks).to.have.length(0);
+  });
+
+  it('ActionBashSystem finishes when no horizontal space found', function() {
+    const level = new StubLevel();
+    const sys = new ActionBashSystem(stubSprites, stubMasks());
+    const lem = new StubLemming();
+    lem.frameIndex = 4; // ->5
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
+  });
+
+  it('ActionBashSystem helper functions inspect ground', function() {
+    const level = new StubLevel();
+    const sys = new ActionBashSystem(stubSprites, stubMasks());
+    const gm = level.getGroundMaskLayer();
+
+    expect(sys.findGapDelta(gm, 0, 0)).to.equal(3);
+    level.ground.add(level.key(0, 2));
+    expect(sys.findGapDelta(gm, 0, 0)).to.equal(2);
+    level.ground.add(level.key(0, 0));
+    level.ground.delete(level.key(0, 2));
+    expect(sys.findGapDelta(gm, 0, 0)).to.equal(0);
+
+    level.ground.clear();
+    expect(sys.findHorizontalSpace(gm, 0, 0, true)).to.equal(4);
+    level.ground.add(level.key(1, 0));
+    expect(sys.findHorizontalSpace(gm, 0, 0, true)).to.equal(1);
+    level.ground.clear();
+    level.ground.add(level.key(-3, 0));
+    expect(sys.findHorizontalSpace(gm, 0, 0, false)).to.equal(3);
+  });
+
+  it('ActionBuildSystem turns around when hitting wall', function() {
+    const level = new StubLevel();
+    const sys = new ActionBuildSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.frameIndex = 15; // ->0
+    level.ground.add(level.key(lem.x + 1, lem.y - 2));
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
+    expect(lem.lookRight).to.equal(false);
+  });
+
+  it('ActionBuildSystem walks when roof blocks path', function() {
+    const level = new StubLevel();
+    const sys = new ActionBuildSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.frameIndex = 15; // ->0
+    level.ground.add(level.key(4, -10));
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
+  });
+
+  it('ActionBuildSystem builds twelve bricks then shrugs', function() {
+    const level = new StubLevel();
+    const sys = new ActionBuildSystem(stubSprites);
+    const lem = new StubLemming();
+
+    for (let i = 0; i < 11; i++) {
+      lem.frameIndex = 8; // ->9 lay brick
+      sys.process(level, lem);
+      lem.frameIndex = 15; // ->0 step up
+      sys.process(level, lem);
+    }
+
+    expect(lem.state).to.equal(11);
+    expect(lem.x).to.equal(22);
+    expect(lem.y).to.equal(-11);
+
+    lem.frameIndex = 8; // ->9 lay final brick
+    sys.process(level, lem);
+    lem.frameIndex = 15; // ->0 last step
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.SHRUG);
+    expect(level.setGroundCalls).to.have.length(72);
+    expect(lem.x).to.equal(24);
+    expect(lem.y).to.equal(-12);
+  });
+});
diff --git a/test/action-systems.03-action-systems-process.test.js b/test/action-systems.03-action-systems-process.test.js
new file mode 100644
index 00000000..83502f0e
--- /dev/null
+++ b/test/action-systems.03-action-systems-process.test.js
@@ -0,0 +1,444 @@
+import { expect } from 'chai';
+import { Lemmings, setTestAppContext, useGlobalLemmings } from './helpers/lemmings.js';
+import { getAppContext } from '../js/core/dependencies.js';
+import { ActionBashSystem } from '../js/actions/ActionBashSystem.js';
+import { ActionBlockerSystem } from '../js/actions/ActionBlockerSystem.js';
+import { ActionBuildSystem } from '../js/actions/ActionBuildSystem.js';
+import { ActionClimbSystem } from '../js/actions/ActionClimbSystem.js';
+import { ActionCountdownSystem } from '../js/actions/ActionCountdownSystem.js';
+import { ActionDiggSystem } from '../js/actions/ActionDiggSystem.js';
+import { ActionDrowningSystem } from '../js/actions/ActionDrowningSystem.js';
+import { ActionExitingSystem } from '../js/actions/ActionExitingSystem.js';
+import { ActionExplodingSystem } from '../js/actions/ActionExplodingSystem.js';
+import { ActionFallSystem } from '../js/actions/ActionFallSystem.js';
+import { ActionFloatingSystem } from '../js/actions/ActionFloatingSystem.js';
+import { ActionFryingSystem } from '../js/actions/ActionFryingSystem.js';
+import { ActionHoistSystem } from '../js/actions/ActionHoistSystem.js';
+import { ActionJumpSystem } from '../js/actions/ActionJumpSystem.js';
+import { ActionMineSystem } from '../js/actions/ActionMineSystem.js';
+import { ActionOhNoSystem } from '../js/actions/ActionOhNoSystem.js';
+import { ActionShrugSystem } from '../js/actions/ActionShrugSystem.js';
+import { ActionSplatterSystem } from '../js/actions/ActionSplatterSystem.js';
+import { ActionWalkSystem } from '../js/actions/ActionWalkSystem.js';
+import { SoundEventTypes, SoundEffectIds } from '../js/game/SoundEvents.js';
+import '../js/level/Trigger.js';
+import '../js/level/TriggerTypes.js';
+import '../js/lemmings/LemmingStateType.js';
+import '../js/lemmings/SpriteTypes.js';
+import '../js/render/MaskTypes.js';
+import '../js/lemmings/Lemming.js';
+import { runScenarioTable } from './support/scenario-table.js';
+
+const makeMiniMap = () => ({
+  addDeath() {},
+  invalidateRegion() {},
+  onGroundChanged() {}
+});
+
+const makeLemmings = () => ({
+  game: {
+    lemmingManager: { miniMap: makeMiniMap() },
+    showDebug: false
+  }
+});
+
+// minimal global environment
+useGlobalLemmings(makeLemmings);
+globalThis.winW = 800;
+globalThis.winH = 600;
+
+const stubSprites = { getAnimation: () => ({ getFrame() { return {}; } }) };
+
+class StubLemming {
+  constructor(x = 0, y = 0) {
+    this.x = x;
+    this.y = y;
+    this.lookRight = true;
+    this.frameIndex = 0;
+    this.state = 0;
+    this.canClimb = false;
+    this.hasParachute = false;
+    this.disabled = false;
+    this.countdown = 0;
+  }
+  getDirection() { return this.lookRight ? 'right' : 'left'; }
+  disable() { this.disabled = true; }
+  setCountDown(act) { this.countdownAction = act; if (this.countdown > 0) return false; this.countdown = 80; return true; }
+  getCountDownTime() { return 8 - (this.countdown >> 4); }
+}
+
+class StubLevel {
+  constructor() {
+    this.ground = new Set();
+    this.clearedMasks = [];
+    this.setGroundCalls = [];
+    this.clearedPoints = [];
+    this.steelUnder = false;
+    this.arrowUnder = false;
+    this.stepHeight = null;
+    this.gapDepth = null;
+    this.steelGround = () => false;
+    this.arrowAt = () => false;
+  }
+  key(x, y) { return `${x},${y}`; }
+  hasGroundAt(x, y) { return this.ground.has(this.key(x, y)); }
+  getGroundMaskLayer() {
+    const self = this;
+    return {
+      hasGroundAt(x, y) { return self.hasGroundAt(x, y); },
+      getSubLayer(x, y, w, h) {
+        return { width: w, height: h, hasGroundAt(dx, dy) { return self.hasGroundAt(x + dx, y + dy); } };
+      },
+      getColumnStepHeight(x, yTop, height) {
+        if (self.stepHeight !== null && self.stepHeight !== undefined) {
+          return self.stepHeight;
+        }
+        const end = yTop + height - 1;
+        for (let i = 0; i < height; i++) {
+          const y = end - i;
+          if (!self.hasGroundAt(x, y)) return i;
+        }
+        return height;
+      },
+      getColumnGapDepth(x, yTop, height) {
+        if (self.gapDepth !== null && self.gapDepth !== undefined) {
+          return self.gapDepth;
+        }
+        for (let i = 0; i < height; i++) {
+          const y = yTop + i;
+          if (self.hasGroundAt(x, y)) return i + 1;
+        }
+        return height + 1;
+      }
+    };
+  }
+  clearGroundWithMask(mask, x, y) { this.clearedMasks.push({ mask, x, y }); }
+  clearGroundWithMaskCount(mask, x, y) {
+    this.clearGroundWithMask(mask, x, y);
+    return this.clearCount ?? 1;
+  }
+  hasSteelUnderMask() { return this.steelUnder; }
+  hasArrowUnderMask() { return this.arrowUnder; }
+  isArrowAt(x, y, direction) { return this.arrowAt(x, y, direction); }
+  clearGroundAt(x, y) { this.clearedPoints.push(this.key(x, y)); this.ground.delete(this.key(x, y)); }
+  setGroundAt(x, y) { this.setGroundCalls.push(this.key(x, y)); this.ground.add(this.key(x, y)); }
+  isSteelGround(x, y) { return this.steelGround(this.key(x, y)); }
+  isOutOfLevel(y) { return y < 0 || y >= 50; }
+}
+
+class StubTriggerManager {
+  constructor() { this.added = []; this.removed = []; }
+  add(t) { this.added.push(t); }
+  removeByOwner(o) { this.removed.push(o); }
+}
+
+class StubGVC { constructor() { this.count = 0; } addSurvivor() { this.count++; } }
+
+class DummyMask { constructor() { this.offsetX = 0; this.offsetY = 0; this.width = 0; this.height = 0; } at() { return false; } }
+function stubMasks() {
+  return {
+    GetMask() {
+      return { GetMask() { return new DummyMask(); } };
+    }
+  };
+}
+
+function useSoundBus(calls) {
+  const base = getAppContext() ?? {};
+  return setTestAppContext({
+    ...base,
+    game: {
+      ...(base.game ?? {}),
+      soundEvents: {
+        emitSfx(type, sfxId, data) {
+          calls.push({ type, sfxId, data });
+        }
+      }
+    }
+  });
+}
+
+function withoutSoundBus() {
+  const base = getAppContext() ?? {};
+  return setTestAppContext({
+    ...base,
+    game: {
+      ...(base.game ?? {}),
+      soundEvents: null
+    }
+  });
+}
+
+function withoutLemmingManager() {
+  const base = getAppContext() ?? {};
+  return setTestAppContext({
+    ...base,
+    game: {
+      ...(base.game ?? {}),
+      lemmingManager: null
+    }
+  });
+}
+
+function makeRuntime(calls = [], miniMap = makeMiniMap()) {
+  return {
+    soundEvents: {
+      emitSfx(type, sfxId, data) {
+        calls.push({ type, sfxId, data });
+      }
+    },
+    miniMap
+  };
+}
+
+function attachRuntime(sys, calls = [], miniMap = makeMiniMap()) {
+  sys.setRuntime?.(makeRuntime(calls, miniMap));
+  return sys;
+}
+
+// helpers for controlled Action systems
+class TestBashSystem extends ActionBashSystem {
+  constructor(gap, horiz) { super(stubSprites, stubMasks()); this.gap = gap; this.horiz = horiz; }
+  findGapDelta() { return this.gap; }
+  findHorizontalSpace() { return this.horiz; }
+}
+
+class TestMineSystem extends ActionMineSystem {
+  constructor(haveSteel, haveArrow) { super(stubSprites, stubMasks()); this.haveSteel = haveSteel; this.haveArrow = haveArrow; this.cleared = 0; }
+  process(level, lem) { return super.process(level, lem); }
+}
+
+describe('Action Systems process()', function() {
+  it('ActionBuildSystem turns around mid-step when ground blocks path', function() {
+    const level = new StubLevel();
+    const sys = new ActionBuildSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.frameIndex = 8; // lay first brick
+    sys.process(level, lem);
+    lem.frameIndex = 15; // stepping forward
+    level.ground.add(level.key(lem.x + 1, lem.y - 2));
+    const res = sys.process(level, lem);
+    expect(res).to.equal(Lemmings.LemmingStateType.WALKING);
+    expect(lem.lookRight).to.equal(false);
+    expect(lem.x).to.equal(1);
+    expect(lem.y).to.equal(-1);
+    expect(lem.state).to.equal(0);
+  });
+
+  it('ActionBuildSystem turns around when ceiling blocks next step', function() {
+    const level = new StubLevel();
+    const sys = new ActionBuildSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.frameIndex = 8; // lay brick
+    sys.process(level, lem);
+    lem.frameIndex = 15; // step forward
+    level.ground.add(level.key(4, -10));
+    const result = sys.process(level, lem);
+    expect(result).to.equal(Lemmings.LemmingStateType.WALKING);
+    expect(lem.lookRight).to.equal(false);
+    expect(lem.x).to.equal(2);
+    expect(lem.y).to.equal(-1);
+    expect(lem.state).to.equal(1);
+  });
+
+  it('ActionBuildSystem lays bricks facing left', function() {
+    const level = new StubLevel();
+    const sys = new ActionBuildSystem(stubSprites);
+    const lem = new StubLemming(10, 0);
+    lem.lookRight = false;
+    lem.frameIndex = 8; // ->9 brick
+    sys.process(level, lem);
+    expect(level.setGroundCalls).to.eql([
+      '6,-1','7,-1','8,-1','9,-1','10,-1','11,-1'
+    ]);
+  });
+
+  it('ActionBuildSystem steps forward without obstacles', function() {
+    const level = new StubLevel();
+    const sys = new ActionBuildSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.frameIndex = 15; // ->0 step
+    const result = sys.process(level, lem);
+    expect(result).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
+    expect(lem.x).to.equal(2);
+    expect(lem.y).to.equal(-1);
+    expect(lem.state).to.equal(1);
+    expect(lem.lookRight).to.equal(true);
+  });
+
+  it('ActionBuildSystem clips brick placement to level bounds', function() {
+    const level = new StubLevel();
+    level.width = 12;
+    level.height = 20;
+    const sys = new ActionBuildSystem(stubSprites);
+    const lem = new StubLemming(10, 5);
+    lem.frameIndex = 8; // ->9 brick
+    sys.process(level, lem);
+    expect(level.setGroundCalls).to.eql(['10,4', '11,4']);
+  });
+
+  it('ActionBuildSystem turns around at horizontal level edges', function() {
+    const level = new StubLevel();
+    level.width = 2;
+    const sys = new ActionBuildSystem(stubSprites);
+    const lem = new StubLemming(1, 0);
+    lem.frameIndex = 15; // ->0 step
+    const result = sys.process(level, lem);
+    expect(result).to.equal(Lemmings.LemmingStateType.WALKING);
+    expect(lem.lookRight).to.equal(false);
+    expect(lem.x).to.equal(1);
+  });
+
+  it('ActionBuildSystem bounces off opposing one-way walls and keeps building', function() {
+    const level = new StubLevel();
+    const sys = new ActionBuildSystem(stubSprites);
+    const lem = new StubLemming(10, 12);
+    lem.frameIndex = 15; // ->0 movement step
+    level.arrowAt = (x, y, direction) => direction === true && x === 11 && y === 10;
+
+    const result = sys.process(level, lem);
+
+    expect(result).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
+    expect(lem.lookRight).to.equal(false);
+    expect(lem.x).to.equal(10);
+    expect(lem.y).to.equal(11);
+    expect(lem.state).to.equal(0);
+  });
+
+  it('ActionClimbSystem continues with ceiling present', function() {
+    const level = new StubLevel();
+    const sys = new ActionClimbSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.frameIndex = 2; // ->3
+    level.ground.add(level.key(lem.x, lem.y - 10));
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
+    expect(lem.y).to.equal(0);
+  });
+
+  it('ActionDiggSystem shrugs on steel', function() {
+    const level = new StubLevel();
+    level.steelGround = () => true;
+    const sys = new ActionDiggSystem(stubSprites);
+    const lem = new StubLemming();
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.SHRUG);
+  });
+
+  it('ActionDiggSystem digs rows while inside level', function() {
+    const level = new StubLevel();
+    const sys = new ActionDiggSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.state = 1;
+    lem.frameIndex = 7; // ->8
+    let calls = 0;
+    sys.digRow = () => { calls++; return true; };
+    level.isOutOfLevel = () => false;
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
+    expect(lem.y).to.equal(1);
+    expect(calls).to.equal(1);
+  });
+
+  it('ActionDiggSystem falls when digging out of level', function() {
+    const level = new StubLevel();
+    const sys = new ActionDiggSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.state = 1;
+    lem.y = 49;
+    lem.frameIndex = 7; // ->8
+    level.isOutOfLevel = y => y >= 50;
+    sys.digRow = () => true;
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.FALLING);
+  });
+
+  it('ActionDiggSystem falls when dig row removes nothing', function() {
+    const level = new StubLevel();
+    const sys = new ActionDiggSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.state = 1;
+    lem.frameIndex = 7; // ->8
+    level.isOutOfLevel = () => false;
+    sys.digRow = () => false;
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.FALLING);
+  });
+
+  it('ActionDiggSystem cycles animation frames', function() {
+    const level = new StubLevel();
+    const sys = new ActionDiggSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.state = 1;
+    level.isOutOfLevel = () => false;
+    let calls = 0;
+    sys.digRow = () => { calls++; return true; };
+    for (let i = 0; i < 16; i++) {
+      sys.process(level, lem);
+    }
+    expect(lem.frameIndex).to.equal(0);
+    expect(lem.y).to.equal(2);
+    expect(calls).to.equal(2);
+  });
+
+  it('ActionDiggSystem shrugs when steel appears below', function() {
+    const level = new StubLevel();
+    const sys = new ActionDiggSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.state = 1;
+    lem.frameIndex = 7; // ->8
+    level.isOutOfLevel = () => false;
+    sys.digRow = () => true;
+    level.steelGround = () => false;
+    sys.process(level, lem); // dig first row
+    level.steelGround = k => k === level.key(lem.x, lem.y);
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.SHRUG);
+  });
+
+  it('digRow returns false when no ground present', function() {
+    const level = new StubLevel();
+    const sys = new ActionDiggSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.x = 10;
+    const res = sys.digRow(level, lem, 0);
+    expect(res).to.equal(false);
+    expect(level.clearedPoints).to.have.length(0);
+  });
+
+  it('digRow clears boundary ground points', function() {
+    const level = new StubLevel();
+    const sys = new ActionDiggSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.x = 10;
+    level.setGroundAt(lem.x - 4, 0);
+    level.setGroundAt(lem.x + 4, 0);
+    const res = sys.digRow(level, lem, 0);
+    expect(res).to.equal(true);
+    expect(level.clearedPoints).to.have.members([
+      level.key(lem.x - 4, 0),
+      level.key(lem.x + 4, 0)
+    ]);
+  });
+
+  it('ActionDrowningSystem moves when no wall', function() {
+    const level = new StubLevel();
+    const sys = new ActionDrowningSystem(stubSprites);
+    const lem = new StubLemming();
+    const x0 = lem.x;
+    sys.process(level, lem);
+    expect(lem.x).to.equal(x0 + 1);
+  });
+
+  it('ActionExitingSystem waits before exit', function() {
+    const gvc = new StubGVC();
+    const sys = new ActionExitingSystem(stubSprites, gvc);
+    const lem = new StubLemming();
+    expect(sys.process(new StubLevel(), lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
+    expect(gvc.count).to.equal(0);
+  });
+
+  it('ActionExplodingSystem clears mask on first frame', function() {
+    const tm = new StubTriggerManager();
+    const level = new StubLevel();
+    const sys = new ActionExplodingSystem(stubSprites, stubMasks(), tm, { draw() {} });
+    const lem = new StubLemming();
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
+    expect(tm.removed[0]).to.equal(lem);
+    expect(level.clearedMasks).to.have.length(1);
+  });
+});
diff --git a/test/action-systems.04-action-systems-process.test.js b/test/action-systems.04-action-systems-process.test.js
new file mode 100644
index 00000000..e03df64a
--- /dev/null
+++ b/test/action-systems.04-action-systems-process.test.js
@@ -0,0 +1,451 @@
+import { expect } from 'chai';
+import { Lemmings, setTestAppContext, useGlobalLemmings } from './helpers/lemmings.js';
+import { getAppContext } from '../js/core/dependencies.js';
+import { ActionBashSystem } from '../js/actions/ActionBashSystem.js';
+import { ActionBlockerSystem } from '../js/actions/ActionBlockerSystem.js';
+import { ActionBuildSystem } from '../js/actions/ActionBuildSystem.js';
+import { ActionClimbSystem } from '../js/actions/ActionClimbSystem.js';
+import { ActionCountdownSystem } from '../js/actions/ActionCountdownSystem.js';
+import { ActionDiggSystem } from '../js/actions/ActionDiggSystem.js';
+import { ActionDrowningSystem } from '../js/actions/ActionDrowningSystem.js';
+import { ActionExitingSystem } from '../js/actions/ActionExitingSystem.js';
+import { ActionExplodingSystem } from '../js/actions/ActionExplodingSystem.js';
+import { ActionFallSystem } from '../js/actions/ActionFallSystem.js';
+import { ActionFloatingSystem } from '../js/actions/ActionFloatingSystem.js';
+import { ActionFryingSystem } from '../js/actions/ActionFryingSystem.js';
+import { ActionHoistSystem } from '../js/actions/ActionHoistSystem.js';
+import { ActionJumpSystem } from '../js/actions/ActionJumpSystem.js';
+import { ActionMineSystem } from '../js/actions/ActionMineSystem.js';
+import { ActionOhNoSystem } from '../js/actions/ActionOhNoSystem.js';
+import { ActionShrugSystem } from '../js/actions/ActionShrugSystem.js';
+import { ActionSplatterSystem } from '../js/actions/ActionSplatterSystem.js';
+import { ActionWalkSystem } from '../js/actions/ActionWalkSystem.js';
+import { SoundEventTypes, SoundEffectIds } from '../js/game/SoundEvents.js';
+import '../js/level/Trigger.js';
+import '../js/level/TriggerTypes.js';
+import '../js/lemmings/LemmingStateType.js';
+import '../js/lemmings/SpriteTypes.js';
+import '../js/render/MaskTypes.js';
+import '../js/lemmings/Lemming.js';
+import { runScenarioTable } from './support/scenario-table.js';
+
+const makeMiniMap = () => ({
+  addDeath() {},
+  invalidateRegion() {},
+  onGroundChanged() {}
+});
+
+const makeLemmings = () => ({
+  game: {
+    lemmingManager: { miniMap: makeMiniMap() },
+    showDebug: false
+  }
+});
+
+// minimal global environment
+useGlobalLemmings(makeLemmings);
+globalThis.winW = 800;
+globalThis.winH = 600;
+
+const stubSprites = { getAnimation: () => ({ getFrame() { return {}; } }) };
+
+class StubLemming {
+  constructor(x = 0, y = 0) {
+    this.x = x;
+    this.y = y;
+    this.lookRight = true;
+    this.frameIndex = 0;
+    this.state = 0;
+    this.canClimb = false;
+    this.hasParachute = false;
+    this.disabled = false;
+    this.countdown = 0;
+  }
+  getDirection() { return this.lookRight ? 'right' : 'left'; }
+  disable() { this.disabled = true; }
+  setCountDown(act) { this.countdownAction = act; if (this.countdown > 0) return false; this.countdown = 80; return true; }
+  getCountDownTime() { return 8 - (this.countdown >> 4); }
+}
+
+class StubLevel {
+  constructor() {
+    this.ground = new Set();
+    this.clearedMasks = [];
+    this.setGroundCalls = [];
+    this.clearedPoints = [];
+    this.steelUnder = false;
+    this.arrowUnder = false;
+    this.stepHeight = null;
+    this.gapDepth = null;
+    this.steelGround = () => false;
+    this.arrowAt = () => false;
+  }
+  key(x, y) { return `${x},${y}`; }
+  hasGroundAt(x, y) { return this.ground.has(this.key(x, y)); }
+  getGroundMaskLayer() {
+    const self = this;
+    return {
+      hasGroundAt(x, y) { return self.hasGroundAt(x, y); },
+      getSubLayer(x, y, w, h) {
+        return { width: w, height: h, hasGroundAt(dx, dy) { return self.hasGroundAt(x + dx, y + dy); } };
+      },
+      getColumnStepHeight(x, yTop, height) {
+        if (self.stepHeight !== null && self.stepHeight !== undefined) {
+          return self.stepHeight;
+        }
+        const end = yTop + height - 1;
+        for (let i = 0; i < height; i++) {
+          const y = end - i;
+          if (!self.hasGroundAt(x, y)) return i;
+        }
+        return height;
+      },
+      getColumnGapDepth(x, yTop, height) {
+        if (self.gapDepth !== null && self.gapDepth !== undefined) {
+          return self.gapDepth;
+        }
+        for (let i = 0; i < height; i++) {
+          const y = yTop + i;
+          if (self.hasGroundAt(x, y)) return i + 1;
+        }
+        return height + 1;
+      }
+    };
+  }
+  clearGroundWithMask(mask, x, y) { this.clearedMasks.push({ mask, x, y }); }
+  clearGroundWithMaskCount(mask, x, y) {
+    this.clearGroundWithMask(mask, x, y);
+    return this.clearCount ?? 1;
+  }
+  hasSteelUnderMask() { return this.steelUnder; }
+  hasArrowUnderMask() { return this.arrowUnder; }
+  isArrowAt(x, y, direction) { return this.arrowAt(x, y, direction); }
+  clearGroundAt(x, y) { this.clearedPoints.push(this.key(x, y)); this.ground.delete(this.key(x, y)); }
+  setGroundAt(x, y) { this.setGroundCalls.push(this.key(x, y)); this.ground.add(this.key(x, y)); }
+  isSteelGround(x, y) { return this.steelGround(this.key(x, y)); }
+  isOutOfLevel(y) { return y < 0 || y >= 50; }
+}
+
+class StubTriggerManager {
+  constructor() { this.added = []; this.removed = []; }
+  add(t) { this.added.push(t); }
+  removeByOwner(o) { this.removed.push(o); }
+}
+
+class StubGVC { constructor() { this.count = 0; } addSurvivor() { this.count++; } }
+
+class DummyMask { constructor() { this.offsetX = 0; this.offsetY = 0; this.width = 0; this.height = 0; } at() { return false; } }
+function stubMasks() {
+  return {
+    GetMask() {
+      return { GetMask() { return new DummyMask(); } };
+    }
+  };
+}
+
+function useSoundBus(calls) {
+  const base = getAppContext() ?? {};
+  return setTestAppContext({
+    ...base,
+    game: {
+      ...(base.game ?? {}),
+      soundEvents: {
+        emitSfx(type, sfxId, data) {
+          calls.push({ type, sfxId, data });
+        }
+      }
+    }
+  });
+}
+
+function withoutSoundBus() {
+  const base = getAppContext() ?? {};
+  return setTestAppContext({
+    ...base,
+    game: {
+      ...(base.game ?? {}),
+      soundEvents: null
+    }
+  });
+}
+
+function withoutLemmingManager() {
+  const base = getAppContext() ?? {};
+  return setTestAppContext({
+    ...base,
+    game: {
+      ...(base.game ?? {}),
+      lemmingManager: null
+    }
+  });
+}
+
+function makeRuntime(calls = [], miniMap = makeMiniMap()) {
+  return {
+    soundEvents: {
+      emitSfx(type, sfxId, data) {
+        calls.push({ type, sfxId, data });
+      }
+    },
+    miniMap
+  };
+}
+
+function attachRuntime(sys, calls = [], miniMap = makeMiniMap()) {
+  sys.setRuntime?.(makeRuntime(calls, miniMap));
+  return sys;
+}
+
+// helpers for controlled Action systems
+class TestBashSystem extends ActionBashSystem {
+  constructor(gap, horiz) { super(stubSprites, stubMasks()); this.gap = gap; this.horiz = horiz; }
+  findGapDelta() { return this.gap; }
+  findHorizontalSpace() { return this.horiz; }
+}
+
+class TestMineSystem extends ActionMineSystem {
+  constructor(haveSteel, haveArrow) { super(stubSprites, stubMasks()); this.haveSteel = haveSteel; this.haveArrow = haveArrow; this.cleared = 0; }
+  process(level, lem) { return super.process(level, lem); }
+}
+
+describe('Action Systems process()', function() {
+  it('ActionFallSystem keeps falling without ground', function() {
+    const level = new StubLevel();
+    const sys = new ActionFallSystem(stubSprites);
+    const lem = new StubLemming();
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
+    expect(lem.y).to.equal(3);
+    expect(lem.state).to.equal(3);
+  });
+
+  it('ActionFallSystem accumulates state over time', function() {
+    const level = new StubLevel();
+    const sys = new ActionFallSystem(stubSprites);
+    const lem = new StubLemming();
+    sys.process(level, lem); // state ->3
+    const result = sys.process(level, lem); // state ->6
+    expect(result).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
+    expect(lem.y).to.equal(6);
+    expect(lem.state).to.equal(6);
+  });
+
+  it('ActionFallSystem floats once fall distance exceeds 16 with parachute', function() {
+    const level = new StubLevel();
+    const sys = new ActionFallSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.hasParachute = true;
+    let state;
+    for (let i = 0; i < 7; i++) {
+      state = sys.process(level, lem);
+    }
+    expect(state).to.equal(Lemmings.LemmingStateType.FLOATING);
+    expect(lem.state).to.be.above(16);
+  });
+
+  it('ActionFallSystem lands with parachute when ground one step below', function() {
+    const level = new StubLevel();
+    const sys = new ActionFallSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.hasParachute = true;
+    level.ground.add(level.key(lem.x, lem.y + 1));
+    const state = sys.process(level, lem);
+    expect(state).to.equal(Lemmings.LemmingStateType.WALKING);
+    expect(lem.y).to.equal(1);
+    expect(lem.state).to.equal(0);
+  });
+
+  it('ActionFallSystem lands with parachute when ground two steps below', function() {
+    const level = new StubLevel();
+    const sys = new ActionFallSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.hasParachute = true;
+    level.ground.add(level.key(lem.x, lem.y + 2));
+    const state = sys.process(level, lem);
+    expect(state).to.equal(Lemmings.LemmingStateType.WALKING);
+    expect(lem.y).to.equal(2);
+    expect(lem.state).to.equal(0);
+  });
+
+  it('ActionFallSystem walks or splats depending on fall distance', function() {
+    const level = new StubLevel();
+    const sys = new ActionFallSystem(stubSprites);
+    const lem = new StubLemming();
+    level.ground.add(level.key(lem.x, lem.y));
+    lem.state = Lemmings.Lemming.LEM_MAX_FALLING;
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
+
+    level.ground.add(level.key(lem.x, lem.y));
+    lem.state = Lemmings.Lemming.LEM_MAX_FALLING + 1;
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.SPLATTING);
+  });
+
+  it('ActionFloatingSystem lands when ground below', function() {
+    const sys = new ActionFloatingSystem(stubSprites);
+    const level = new StubLevel();
+    const lem = new StubLemming();
+    level.ground.add(level.key(lem.x, lem.y + 2));
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
+    expect(lem.y).to.equal(2);
+  });
+
+  it('ActionFryingSystem moves then turns around', function() {
+    const level = new StubLevel();
+    const sys = new ActionFryingSystem(stubSprites);
+    const lem = new StubLemming();
+    const x0 = lem.x;
+    sys.process(level, lem);
+    expect(lem.x).to.equal(x0 + 1);
+    level.ground.add(level.key(lem.x + 8, lem.y));
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
+    expect(lem.lookRight).to.equal(false);
+  });
+
+  it('ActionHoistSystem pauses mid animation', function() {
+    const sys = new ActionHoistSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.frameIndex = 5; // ->6
+    expect(sys.process(new StubLevel(), lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
+    expect(lem.y).to.equal(0);
+  });
+
+  it('ActionJumpSystem lands immediately without ceiling', function() {
+    const level = new StubLevel();
+    const sys = new ActionJumpSystem(stubSprites);
+    const lem = new StubLemming();
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
+  });
+
+  it('ActionJumpSystem ends after reaching max height', function() {
+    const level = new StubLevel();
+    const sys = new ActionJumpSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.state = 2;
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
+  });
+
+  it('ActionJumpSystem climbs two cells then ends', function() {
+    const level = new StubLevel();
+    level.ground.add(level.key(1, -1));
+    level.ground.add(level.key(1, -2));
+    const sys = new ActionJumpSystem(stubSprites);
+    const lem = new StubLemming();
+    const res = sys.process(level, lem);
+    expect(res).to.equal(Lemmings.LemmingStateType.WALKING);
+    expect(lem.y).to.equal(-2);
+    expect(lem.state).to.equal(0);
+  });
+
+  it('ActionJumpSystem ends when no ceiling remains', function() {
+    const level = new StubLevel();
+    level.ground.add(level.key(1, -1));
+    const sys = new ActionJumpSystem(stubSprites);
+    const lem = new StubLemming();
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
+    expect(lem.y).to.equal(-1);
+  });
+
+  it('ActionJumpSystem enforces LEM_MIN_Y', function() {
+    const level = new StubLevel();
+    const sys = new ActionJumpSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.y = -6;
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
+    expect(lem.y).to.equal(Lemmings.Lemming.LEM_MIN_Y);
+  });
+
+  it('ActionJumpSystem resets state after jump', function() {
+    const level = new StubLevel();
+    level.ground.add(level.key(1, -1));
+    const sys = new ActionJumpSystem(stubSprites);
+    const lem = new StubLemming();
+    sys.process(level, lem);
+    expect(lem.state).to.equal(0);
+  });
+
+  it('ActionJumpSystem triggerLemAction refuses to activate', function() {
+    const sys = new ActionJumpSystem(stubSprites);
+    const lem = new StubLemming();
+    expect(sys.triggerLemAction(lem)).to.equal(false);
+  });
+
+  it('ActionJumpSystem draw delegates to base system', function() {
+    const sys = new ActionJumpSystem(stubSprites);
+    const lem = new StubLemming();
+    let called = false;
+    const display = { drawFrame() { called = true; } };
+    sys.draw(display, lem);
+    expect(called).to.equal(true);
+  });
+
+  it('ActionJumpSystem initializes state and keeps jumping', function() {
+    const level = new StubLevel();
+    level.hasGroundAt = () => true;
+    const sys = new ActionJumpSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.state = -1;
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.JUMPING);
+    expect(lem.state).to.equal(1);
+    expect(lem.y).to.equal(-2);
+  });
+
+  it('ActionJumpSystem initializes null state then ends', function() {
+    const level = new StubLevel();
+    level.ground.add(level.key(1, -1));
+    const sys = new ActionJumpSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.state = null;
+    const res = sys.process(level, lem);
+    expect(res).to.equal(Lemmings.LemmingStateType.WALKING);
+    expect(lem.state).to.equal(0);
+    expect(lem.y).to.equal(-1);
+  });
+
+  it('ActionMineSystem shrugs on steel ground', function() {
+    const level = new StubLevel();
+    level.steelUnder = true;
+    const sys = new ActionMineSystem(stubSprites, stubMasks());
+    const lem = new StubLemming();
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.SHRUG);
+  });
+
+  it('ActionMineSystem shrugs when arrow under mask', function() {
+    const level = new StubLevel();
+    const sys = new ActionMineSystem(stubSprites, stubMasks());
+    level.arrowUnder = true;
+    const lem = new StubLemming();
+    lem.frameIndex = 1; // ->2
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.SHRUG);
+    expect(level.clearedMasks).to.have.length(0);
+  });
+
+  it('ActionOhNoSystem falls if unsupported', function() {
+    const level = new StubLevel();
+    const sys = new ActionOhNoSystem(stubSprites);
+    const lem = new StubLemming();
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
+    expect(lem.y).to.equal(1);
+  });
+
+  it('ActionShrugSystem waits before walking', function() {
+    const sys = new ActionShrugSystem(stubSprites);
+    const lem = new StubLemming();
+    expect(sys.process(new StubLevel(), lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
+    expect(lem.frameIndex).to.equal(1);
+  });
+
+  it('ActionSplatterSystem disables then exits', function() {
+    const sys = new ActionSplatterSystem(stubSprites);
+    const lem = new StubLemming();
+    expect(sys.process(new StubLevel(), lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
+    expect(lem.disabled).to.equal(true);
+  });
+
+  it('ActionWalkSystem turns when blocked and cannot climb', function() {
+    const sys = new ActionWalkSystem(stubSprites);
+    const level = new StubLevel();
+    level.stepHeight = 8;
+    const lem = new StubLemming();
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
+    expect(lem.lookRight).to.equal(false);
+  });
+});
diff --git a/test/action-systems.05-action-systems-process.test.js b/test/action-systems.05-action-systems-process.test.js
new file mode 100644
index 00000000..84c65da4
--- /dev/null
+++ b/test/action-systems.05-action-systems-process.test.js
@@ -0,0 +1,263 @@
+import { expect } from 'chai';
+import { Lemmings, setTestAppContext, useGlobalLemmings } from './helpers/lemmings.js';
+import { getAppContext } from '../js/core/dependencies.js';
+import { ActionBashSystem } from '../js/actions/ActionBashSystem.js';
+import { ActionBlockerSystem } from '../js/actions/ActionBlockerSystem.js';
+import { ActionBuildSystem } from '../js/actions/ActionBuildSystem.js';
+import { ActionClimbSystem } from '../js/actions/ActionClimbSystem.js';
+import { ActionCountdownSystem } from '../js/actions/ActionCountdownSystem.js';
+import { ActionDiggSystem } from '../js/actions/ActionDiggSystem.js';
+import { ActionDrowningSystem } from '../js/actions/ActionDrowningSystem.js';
+import { ActionExitingSystem } from '../js/actions/ActionExitingSystem.js';
+import { ActionExplodingSystem } from '../js/actions/ActionExplodingSystem.js';
+import { ActionFallSystem } from '../js/actions/ActionFallSystem.js';
+import { ActionFloatingSystem } from '../js/actions/ActionFloatingSystem.js';
+import { ActionFryingSystem } from '../js/actions/ActionFryingSystem.js';
+import { ActionHoistSystem } from '../js/actions/ActionHoistSystem.js';
+import { ActionJumpSystem } from '../js/actions/ActionJumpSystem.js';
+import { ActionMineSystem } from '../js/actions/ActionMineSystem.js';
+import { ActionOhNoSystem } from '../js/actions/ActionOhNoSystem.js';
+import { ActionShrugSystem } from '../js/actions/ActionShrugSystem.js';
+import { ActionSplatterSystem } from '../js/actions/ActionSplatterSystem.js';
+import { ActionWalkSystem } from '../js/actions/ActionWalkSystem.js';
+import { SoundEventTypes, SoundEffectIds } from '../js/game/SoundEvents.js';
+import '../js/level/Trigger.js';
+import '../js/level/TriggerTypes.js';
+import '../js/lemmings/LemmingStateType.js';
+import '../js/lemmings/SpriteTypes.js';
+import '../js/render/MaskTypes.js';
+import '../js/lemmings/Lemming.js';
+import { runScenarioTable } from './support/scenario-table.js';
+
+const makeMiniMap = () => ({
+  addDeath() {},
+  invalidateRegion() {},
+  onGroundChanged() {}
+});
+
+const makeLemmings = () => ({
+  game: {
+    lemmingManager: { miniMap: makeMiniMap() },
+    showDebug: false
+  }
+});
+
+// minimal global environment
+useGlobalLemmings(makeLemmings);
+globalThis.winW = 800;
+globalThis.winH = 600;
+
+const stubSprites = { getAnimation: () => ({ getFrame() { return {}; } }) };
+
+class StubLemming {
+  constructor(x = 0, y = 0) {
+    this.x = x;
+    this.y = y;
+    this.lookRight = true;
+    this.frameIndex = 0;
+    this.state = 0;
+    this.canClimb = false;
+    this.hasParachute = false;
+    this.disabled = false;
+    this.countdown = 0;
+  }
+  getDirection() { return this.lookRight ? 'right' : 'left'; }
+  disable() { this.disabled = true; }
+  setCountDown(act) { this.countdownAction = act; if (this.countdown > 0) return false; this.countdown = 80; return true; }
+  getCountDownTime() { return 8 - (this.countdown >> 4); }
+}
+
+class StubLevel {
+  constructor() {
+    this.ground = new Set();
+    this.clearedMasks = [];
+    this.setGroundCalls = [];
+    this.clearedPoints = [];
+    this.steelUnder = false;
+    this.arrowUnder = false;
+    this.stepHeight = null;
+    this.gapDepth = null;
+    this.steelGround = () => false;
+    this.arrowAt = () => false;
+  }
+  key(x, y) { return `${x},${y}`; }
+  hasGroundAt(x, y) { return this.ground.has(this.key(x, y)); }
+  getGroundMaskLayer() {
+    const self = this;
+    return {
+      hasGroundAt(x, y) { return self.hasGroundAt(x, y); },
+      getSubLayer(x, y, w, h) {
+        return { width: w, height: h, hasGroundAt(dx, dy) { return self.hasGroundAt(x + dx, y + dy); } };
+      },
+      getColumnStepHeight(x, yTop, height) {
+        if (self.stepHeight !== null && self.stepHeight !== undefined) {
+          return self.stepHeight;
+        }
+        const end = yTop + height - 1;
+        for (let i = 0; i < height; i++) {
+          const y = end - i;
+          if (!self.hasGroundAt(x, y)) return i;
+        }
+        return height;
+      },
+      getColumnGapDepth(x, yTop, height) {
+        if (self.gapDepth !== null && self.gapDepth !== undefined) {
+          return self.gapDepth;
+        }
+        for (let i = 0; i < height; i++) {
+          const y = yTop + i;
+          if (self.hasGroundAt(x, y)) return i + 1;
+        }
+        return height + 1;
+      }
+    };
+  }
+  clearGroundWithMask(mask, x, y) { this.clearedMasks.push({ mask, x, y }); }
+  clearGroundWithMaskCount(mask, x, y) {
+    this.clearGroundWithMask(mask, x, y);
+    return this.clearCount ?? 1;
+  }
+  hasSteelUnderMask() { return this.steelUnder; }
+  hasArrowUnderMask() { return this.arrowUnder; }
+  isArrowAt(x, y, direction) { return this.arrowAt(x, y, direction); }
+  clearGroundAt(x, y) { this.clearedPoints.push(this.key(x, y)); this.ground.delete(this.key(x, y)); }
+  setGroundAt(x, y) { this.setGroundCalls.push(this.key(x, y)); this.ground.add(this.key(x, y)); }
+  isSteelGround(x, y) { return this.steelGround(this.key(x, y)); }
+  isOutOfLevel(y) { return y < 0 || y >= 50; }
+}
+
+class StubTriggerManager {
+  constructor() { this.added = []; this.removed = []; }
+  add(t) { this.added.push(t); }
+  removeByOwner(o) { this.removed.push(o); }
+}
+
+class StubGVC { constructor() { this.count = 0; } addSurvivor() { this.count++; } }
+
+class DummyMask { constructor() { this.offsetX = 0; this.offsetY = 0; this.width = 0; this.height = 0; } at() { return false; } }
+function stubMasks() {
+  return {
+    GetMask() {
+      return { GetMask() { return new DummyMask(); } };
+    }
+  };
+}
+
+function useSoundBus(calls) {
+  const base = getAppContext() ?? {};
+  return setTestAppContext({
+    ...base,
+    game: {
+      ...(base.game ?? {}),
+      soundEvents: {
+        emitSfx(type, sfxId, data) {
+          calls.push({ type, sfxId, data });
+        }
+      }
+    }
+  });
+}
+
+function withoutSoundBus() {
+  const base = getAppContext() ?? {};
+  return setTestAppContext({
+    ...base,
+    game: {
+      ...(base.game ?? {}),
+      soundEvents: null
+    }
+  });
+}
+
+function withoutLemmingManager() {
+  const base = getAppContext() ?? {};
+  return setTestAppContext({
+    ...base,
+    game: {
+      ...(base.game ?? {}),
+      lemmingManager: null
+    }
+  });
+}
+
+function makeRuntime(calls = [], miniMap = makeMiniMap()) {
+  return {
+    soundEvents: {
+      emitSfx(type, sfxId, data) {
+        calls.push({ type, sfxId, data });
+      }
+    },
+    miniMap
+  };
+}
+
+function attachRuntime(sys, calls = [], miniMap = makeMiniMap()) {
+  sys.setRuntime?.(makeRuntime(calls, miniMap));
+  return sys;
+}
+
+// helpers for controlled Action systems
+class TestBashSystem extends ActionBashSystem {
+  constructor(gap, horiz) { super(stubSprites, stubMasks()); this.gap = gap; this.horiz = horiz; }
+  findGapDelta() { return this.gap; }
+  findHorizontalSpace() { return this.horiz; }
+}
+
+class TestMineSystem extends ActionMineSystem {
+  constructor(haveSteel, haveArrow) { super(stubSprites, stubMasks()); this.haveSteel = haveSteel; this.haveArrow = haveArrow; this.cleared = 0; }
+  process(level, lem) { return super.process(level, lem); }
+}
+
+describe('Action Systems process()', function() {
+  it('ActionWalkSystem steps up small ledge', function() {
+    const sys = new ActionWalkSystem(stubSprites);
+    const level = new StubLevel();
+    level.stepHeight = 2;
+    const lem = new StubLemming();
+    sys.process(level, lem);
+    expect(lem.y).to.equal(-1);
+  });
+
+  it('getColumnStepHeight counts ground from bottom', function() {
+    const level = new StubLevel();
+    const mask = level.getGroundMaskLayer();
+    level.ground.add(level.key(0, 3));
+    expect(mask.getColumnStepHeight(0, 0, 4)).to.equal(1);
+    level.ground.add(level.key(0, 0));
+    level.ground.add(level.key(0, 1));
+    level.ground.add(level.key(0, 2));
+    expect(mask.getColumnStepHeight(0, 0, 4)).to.equal(4);
+    level.ground.clear();
+    expect(mask.getColumnStepHeight(0, 0, 4)).to.equal(0);
+  });
+
+  it('getColumnGapDepth counts gap from top', function() {
+    const level = new StubLevel();
+    const mask = level.getGroundMaskLayer();
+    level.ground.add(level.key(0, 2));
+    expect(mask.getColumnGapDepth(0, 0, 3)).to.equal(3);
+    level.ground.clear();
+    expect(mask.getColumnGapDepth(0, 0, 3)).to.equal(4);
+  });
+
+  it('ActionWalkSystem clamps position to LEM_MIN_Y', function() {
+    const sys = new ActionWalkSystem(stubSprites);
+    const level = new StubLevel();
+    level.stepHeight = 2;
+    const lem = new StubLemming();
+    lem.y = Lemmings.Lemming.LEM_MIN_Y;
+    sys.process(level, lem);
+    expect(lem.y).to.equal(Lemmings.Lemming.LEM_MIN_Y);
+  });
+
+  it('ActionWalkSystem walks over shallow gaps', function() {
+    const sys = new ActionWalkSystem(stubSprites);
+    const level = new StubLevel();
+    level.stepHeight = 0;
+    level.gapDepth = 1;
+    const lem = new StubLemming();
+    const res = sys.process(level, lem);
+    expect(res).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
+    expect(lem.y).to.equal(1);
+  });
+});
diff --git a/test/action-systems.06-action-systems-events-and-draws.test.js b/test/action-systems.06-action-systems-events-and-draws.test.js
new file mode 100644
index 00000000..b9dc2af8
--- /dev/null
+++ b/test/action-systems.06-action-systems-events-and-draws.test.js
@@ -0,0 +1,438 @@
+import { expect } from 'chai';
+import { Lemmings, setTestAppContext, useGlobalLemmings } from './helpers/lemmings.js';
+import { getAppContext } from '../js/core/dependencies.js';
+import { ActionBashSystem } from '../js/actions/ActionBashSystem.js';
+import { ActionBlockerSystem } from '../js/actions/ActionBlockerSystem.js';
+import { ActionBuildSystem } from '../js/actions/ActionBuildSystem.js';
+import { ActionClimbSystem } from '../js/actions/ActionClimbSystem.js';
+import { ActionCountdownSystem } from '../js/actions/ActionCountdownSystem.js';
+import { ActionDiggSystem } from '../js/actions/ActionDiggSystem.js';
+import { ActionDrowningSystem } from '../js/actions/ActionDrowningSystem.js';
+import { ActionExitingSystem } from '../js/actions/ActionExitingSystem.js';
+import { ActionExplodingSystem } from '../js/actions/ActionExplodingSystem.js';
+import { ActionFallSystem } from '../js/actions/ActionFallSystem.js';
+import { ActionFloatingSystem } from '../js/actions/ActionFloatingSystem.js';
+import { ActionFryingSystem } from '../js/actions/ActionFryingSystem.js';
+import { ActionHoistSystem } from '../js/actions/ActionHoistSystem.js';
+import { ActionJumpSystem } from '../js/actions/ActionJumpSystem.js';
+import { ActionMineSystem } from '../js/actions/ActionMineSystem.js';
+import { ActionOhNoSystem } from '../js/actions/ActionOhNoSystem.js';
+import { ActionShrugSystem } from '../js/actions/ActionShrugSystem.js';
+import { ActionSplatterSystem } from '../js/actions/ActionSplatterSystem.js';
+import { ActionWalkSystem } from '../js/actions/ActionWalkSystem.js';
+import { SoundEventTypes, SoundEffectIds } from '../js/game/SoundEvents.js';
+import '../js/level/Trigger.js';
+import '../js/level/TriggerTypes.js';
+import '../js/lemmings/LemmingStateType.js';
+import '../js/lemmings/SpriteTypes.js';
+import '../js/render/MaskTypes.js';
+import '../js/lemmings/Lemming.js';
+import { runScenarioTable } from './support/scenario-table.js';
+
+const makeMiniMap = () => ({
+  addDeath() {},
+  invalidateRegion() {},
+  onGroundChanged() {}
+});
+
+const makeLemmings = () => ({
+  game: {
+    lemmingManager: { miniMap: makeMiniMap() },
+    showDebug: false
+  }
+});
+
+// minimal global environment
+useGlobalLemmings(makeLemmings);
+globalThis.winW = 800;
+globalThis.winH = 600;
+
+const stubSprites = { getAnimation: () => ({ getFrame() { return {}; } }) };
+
+class StubLemming {
+  constructor(x = 0, y = 0) {
+    this.x = x;
+    this.y = y;
+    this.lookRight = true;
+    this.frameIndex = 0;
+    this.state = 0;
+    this.canClimb = false;
+    this.hasParachute = false;
+    this.disabled = false;
+    this.countdown = 0;
+  }
+  getDirection() { return this.lookRight ? 'right' : 'left'; }
+  disable() { this.disabled = true; }
+  setCountDown(act) { this.countdownAction = act; if (this.countdown > 0) return false; this.countdown = 80; return true; }
+  getCountDownTime() { return 8 - (this.countdown >> 4); }
+}
+
+class StubLevel {
+  constructor() {
+    this.ground = new Set();
+    this.clearedMasks = [];
+    this.setGroundCalls = [];
+    this.clearedPoints = [];
+    this.steelUnder = false;
+    this.arrowUnder = false;
+    this.stepHeight = null;
+    this.gapDepth = null;
+    this.steelGround = () => false;
+    this.arrowAt = () => false;
+  }
+  key(x, y) { return `${x},${y}`; }
+  hasGroundAt(x, y) { return this.ground.has(this.key(x, y)); }
+  getGroundMaskLayer() {
+    const self = this;
+    return {
+      hasGroundAt(x, y) { return self.hasGroundAt(x, y); },
+      getSubLayer(x, y, w, h) {
+        return { width: w, height: h, hasGroundAt(dx, dy) { return self.hasGroundAt(x + dx, y + dy); } };
+      },
+      getColumnStepHeight(x, yTop, height) {
+        if (self.stepHeight !== null && self.stepHeight !== undefined) {
+          return self.stepHeight;
+        }
+        const end = yTop + height - 1;
+        for (let i = 0; i < height; i++) {
+          const y = end - i;
+          if (!self.hasGroundAt(x, y)) return i;
+        }
+        return height;
+      },
+      getColumnGapDepth(x, yTop, height) {
+        if (self.gapDepth !== null && self.gapDepth !== undefined) {
+          return self.gapDepth;
+        }
+        for (let i = 0; i < height; i++) {
+          const y = yTop + i;
+          if (self.hasGroundAt(x, y)) return i + 1;
+        }
+        return height + 1;
+      }
+    };
+  }
+  clearGroundWithMask(mask, x, y) { this.clearedMasks.push({ mask, x, y }); }
+  clearGroundWithMaskCount(mask, x, y) {
+    this.clearGroundWithMask(mask, x, y);
+    return this.clearCount ?? 1;
+  }
+  hasSteelUnderMask() { return this.steelUnder; }
+  hasArrowUnderMask() { return this.arrowUnder; }
+  isArrowAt(x, y, direction) { return this.arrowAt(x, y, direction); }
+  clearGroundAt(x, y) { this.clearedPoints.push(this.key(x, y)); this.ground.delete(this.key(x, y)); }
+  setGroundAt(x, y) { this.setGroundCalls.push(this.key(x, y)); this.ground.add(this.key(x, y)); }
+  isSteelGround(x, y) { return this.steelGround(this.key(x, y)); }
+  isOutOfLevel(y) { return y < 0 || y >= 50; }
+}
+
+class StubTriggerManager {
+  constructor() { this.added = []; this.removed = []; }
+  add(t) { this.added.push(t); }
+  removeByOwner(o) { this.removed.push(o); }
+}
+
+class StubGVC { constructor() { this.count = 0; } addSurvivor() { this.count++; } }
+
+class DummyMask { constructor() { this.offsetX = 0; this.offsetY = 0; this.width = 0; this.height = 0; } at() { return false; } }
+function stubMasks() {
+  return {
+    GetMask() {
+      return { GetMask() { return new DummyMask(); } };
+    }
+  };
+}
+
+function useSoundBus(calls) {
+  const base = getAppContext() ?? {};
+  return setTestAppContext({
+    ...base,
+    game: {
+      ...(base.game ?? {}),
+      soundEvents: {
+        emitSfx(type, sfxId, data) {
+          calls.push({ type, sfxId, data });
+        }
+      }
+    }
+  });
+}
+
+function withoutSoundBus() {
+  const base = getAppContext() ?? {};
+  return setTestAppContext({
+    ...base,
+    game: {
+      ...(base.game ?? {}),
+      soundEvents: null
+    }
+  });
+}
+
+function withoutLemmingManager() {
+  const base = getAppContext() ?? {};
+  return setTestAppContext({
+    ...base,
+    game: {
+      ...(base.game ?? {}),
+      lemmingManager: null
+    }
+  });
+}
+
+function makeRuntime(calls = [], miniMap = makeMiniMap()) {
+  return {
+    soundEvents: {
+      emitSfx(type, sfxId, data) {
+        calls.push({ type, sfxId, data });
+      }
+    },
+    miniMap
+  };
+}
+
+function attachRuntime(sys, calls = [], miniMap = makeMiniMap()) {
+  sys.setRuntime?.(makeRuntime(calls, miniMap));
+  return sys;
+}
+
+// helpers for controlled Action systems
+class TestBashSystem extends ActionBashSystem {
+  constructor(gap, horiz) { super(stubSprites, stubMasks()); this.gap = gap; this.horiz = horiz; }
+  findGapDelta() { return this.gap; }
+  findHorizontalSpace() { return this.horiz; }
+}
+
+class TestMineSystem extends ActionMineSystem {
+  constructor(haveSteel, haveArrow) { super(stubSprites, stubMasks()); this.haveSteel = haveSteel; this.haveArrow = haveArrow; this.cleared = 0; }
+  process(level, lem) { return super.process(level, lem); }
+}
+
+describe('Action systems events and draws', function() {
+  it('ActionBaseSystem emitters fire for bashing and digging steel', function() {
+    const calls = [];
+    const restore = useSoundBus(calls);
+
+    const bashLevel = new StubLevel();
+    bashLevel.steelUnder = true;
+    const bash = attachRuntime(new ActionBashSystem(stubSprites, stubMasks()), calls);
+    const bashLem = new StubLemming();
+    bashLem.id = 1;
+    bashLem.frameIndex = 2; // -> state 3
+    expect(bash.process(bashLevel, bashLem)).to.equal(Lemmings.LemmingStateType.SHRUG);
+
+    const digLevel = new StubLevel();
+    digLevel.steelGround = () => true;
+    const dig = attachRuntime(new ActionDiggSystem(stubSprites), calls);
+    const digLem = new StubLemming();
+    digLem.id = 2;
+    expect(dig.process(digLevel, digLem)).to.equal(Lemmings.LemmingStateType.SHRUG);
+
+    restore();
+    expect(calls[0].type).to.equal(SoundEventTypes.STEEL_HIT);
+    expect(calls[1].type).to.equal(SoundEventTypes.STEEL_HIT);
+  });
+
+  it('emits terrain events with intensity for dig, bash, and mine', function() {
+    const calls = [];
+    const restore = useSoundBus(calls);
+    const digLevel = new StubLevel();
+    const dig = attachRuntime(new ActionDiggSystem(stubSprites), calls);
+    const digLem = new StubLemming(10, 5);
+    digLem.id = 9;
+    for (let x = digLem.x - 4; x <= digLem.x; x++) {
+      digLevel.ground.add(digLevel.key(x, 3));
+    }
+    dig.digRow(digLevel, digLem, 3);
+
+    const mask = { offsetX: 0, offsetY: 0, width: 3, height: 1, at() { return false; } };
+    const masks = { GetMask() { return { GetMask() { return mask; } }; } };
+
+    const bashLevel = new StubLevel();
+    bashLevel.clearCount = 3;
+    const bash = attachRuntime(new ActionBashSystem(stubSprites, masks), calls);
+    const bashLem = new StubLemming();
+    bashLem.id = 10;
+    bashLem.frameIndex = 2; // -> state 3
+    bash.process(bashLevel, bashLem);
+
+    const mineLevel = new StubLevel();
+    mineLevel.clearCount = 2;
+    const mine = attachRuntime(new ActionMineSystem(stubSprites, masks), calls);
+    const mineLem = new StubLemming();
+    mineLem.id = 11;
+    mine.process(mineLevel, mineLem);
+
+    restore();
+    const digEvent = calls.find(call => call.type === SoundEventTypes.LEMMING_DIG);
+    const bashEvent = calls.find(call => call.type === SoundEventTypes.LEMMING_BASH);
+    const mineEvent = calls.find(call => call.type === SoundEventTypes.LEMMING_MINE);
+    expect(digEvent).to.be.ok;
+    expect(bashEvent).to.be.ok;
+    expect(mineEvent).to.be.ok;
+    expect(digEvent.data.intensity).to.be.greaterThan(1);
+    expect(bashEvent.data.intensity).to.be.greaterThan(1);
+    expect(mineEvent.data.intensity).to.be.greaterThan(1);
+  });
+
+  it('handles missing clear count with null bash masks', function() {
+    const restore = useSoundBus([]);
+    const level = {
+      getGroundMaskLayer() { return { hasGroundAt() { return false; } }; },
+      hasSteelUnderMask() { return false; },
+      hasArrowUnderMask() { return false; },
+      clearGroundWithMask(mask) { this.cleared = mask; }
+    };
+    const nullMasks = {
+      GetMask() { return { GetMask() { return null; } }; }
+    };
+    const sys = new ActionBashSystem(stubSprites, nullMasks);
+    const lem = new StubLemming();
+    lem.frameIndex = 1; // -> state 2
+    sys.process(level, lem);
+    restore();
+    expect(level.cleared).to.equal(null);
+  });
+
+  it('handles missing clear count with null mine masks', function() {
+    const restore = useSoundBus([]);
+    const level = {
+      hasSteelUnderMask() { return false; },
+      hasArrowUnderMask() { return false; },
+      clearGroundWithMask(mask) { this.cleared = mask; }
+    };
+    const nullMasks = {
+      GetMask() { return { GetMask() { return null; } }; }
+    };
+    const sys = new ActionMineSystem(stubSprites, nullMasks);
+    const lem = new StubLemming();
+    lem.frameIndex = 0; // -> state 1
+    sys.process(level, lem);
+    restore();
+    expect(level.cleared).to.equal(null);
+  });
+
+  it('ActionBashSystem exits to walking when solid ends', function() {
+    const level = new StubLevel();
+    const sys = new ActionBashSystem(stubSprites, stubMasks());
+    const lem = new StubLemming();
+    lem.frameIndex = 4; // -> state 5
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
+  });
+
+  it('ActionBuildSystem emits step and warning sounds', function() {
+    const calls = [];
+    const restore = useSoundBus(calls);
+    const level = new StubLevel();
+    const sys = attachRuntime(new ActionBuildSystem(stubSprites), calls);
+    const lem = new StubLemming();
+    lem.id = 3;
+    lem.frameIndex = 8;
+    lem.state = 9;
+
+    sys.process(level, lem);
+    restore();
+
+    expect(calls.map(c => c.type)).to.eql([
+      SoundEventTypes.BUILDER_STEP,
+      SoundEventTypes.BUILDER_WARNING
+    ]);
+    expect(calls.map(c => c.sfxId)).to.eql([
+      SoundEffectIds.BUILDER_STEP,
+      SoundEffectIds.BUILDER_WARNING
+    ]);
+  });
+
+  it('ActionBuildSystem handles frame-zero movement checks', function() {
+    const level = new StubLevel();
+    const sys = new ActionBuildSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.frameIndex = 15; // -> 0
+    level.ground.add(level.key(1, -2));
+
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
+    expect(lem.lookRight).to.equal(false);
+
+    const lem2 = new StubLemming();
+    lem2.frameIndex = 15;
+    level.ground.clear();
+    level.ground.add(level.key(4, -10));
+    expect(sys.process(level, lem2)).to.equal(Lemmings.LemmingStateType.WALKING);
+    expect(lem2.lookRight).to.equal(false);
+  });
+
+  it('ActionCountdownSystem emits ohno when the timer hits zero', function() {
+    const calls = [];
+    const restore = useSoundBus(calls);
+    const sys = attachRuntime(new ActionCountdownSystem(stubMasks()), calls);
+    const lem = new StubLemming();
+    lem.id = 4;
+    lem.countdown = 1;
+    lem.setCountDown = act => { lem.countdownAction = act; return true; };
+
+    expect(sys.process(new StubLevel(), lem)).to.equal(Lemmings.LemmingStateType.OHNO);
+    restore();
+
+    expect(calls[0].type).to.equal(SoundEventTypes.LEMMING_OHNO);
+    expect(calls[0].sfxId).to.equal(SoundEffectIds.OHNO);
+  });
+
+  it('ActionDrowningSystem and ExitingSystem emit sfx on entry', function() {
+    const calls = [];
+    const restore = useSoundBus(calls);
+
+    const drowning = attachRuntime(new ActionDrowningSystem(stubSprites), calls);
+    const drownLem = new StubLemming();
+    drownLem.id = 5;
+    drownLem.lastTriggerType = 'water';
+    drowning.process(new StubLevel(), drownLem);
+
+    const gvc = new StubGVC();
+    const exit = attachRuntime(new ActionExitingSystem(stubSprites, gvc), calls);
+    const exitLem = new StubLemming();
+    exitLem.id = 6;
+    exitLem.lastTriggerType = 'exit';
+    exit.process(new StubLevel(), exitLem);
+
+    restore();
+    expect(calls[0].type).to.equal(SoundEventTypes.LEMMING_DROWN);
+    expect(calls[1].type).to.equal(SoundEventTypes.LEMMING_EXIT);
+  });
+
+  it('ActionDrowningSystem moves when no ground is ahead', function() {
+    const sys = new ActionDrowningSystem(stubSprites);
+    const level = new StubLevel();
+    const lem = new StubLemming();
+    const x0 = lem.x;
+    sys.process(level, lem);
+    expect(lem.x).to.equal(x0 + 1);
+  });
+
+  it('ActionExplodingSystem emits and invalidates minimap', function() {
+    const calls = [];
+    const restore = useSoundBus(calls);
+    const mask = { offsetX: -2, offsetY: -3, width: 4, height: 5 };
+    const masks = { GetMask() { return { GetMask() { return mask; } }; } };
+    const triggerManager = { removed: [], removeByOwner(lem) { this.removed.push(lem); } };
+    const particleTable = { draw() {} };
+    const miniMap = {
+      invalidations: [],
+      deaths: [],
+      invalidateRegion(x, y, w, h) { this.invalidations.push({ x, y, w, h }); },
+      addDeath(x, y) { this.deaths.push({ x, y }); }
+    };
+    const sys = attachRuntime(new ActionExplodingSystem(stubSprites, masks, triggerManager, particleTable), calls, miniMap);
+    const level = { clearGroundWithMask() { return true; } };
+
+    const lem = new StubLemming();
+    lem.id = 7;
+    sys.process(level, lem);
+
+    restore();
+
+    expect(calls[0].type).to.equal(SoundEventTypes.LEMMING_EXPLODE);
+    expect(triggerManager.removed[0]).to.equal(lem);
+    expect(miniMap.invalidations[0]).to.eql({ x: -2, y: -3, w: 4, h: 5 });
+    expect(miniMap.deaths[0]).to.eql({ x: 0, y: 0 });
+  });
+});
diff --git a/test/action-systems.07-action-systems-events-and-draws.test.js b/test/action-systems.07-action-systems-events-and-draws.test.js
new file mode 100644
index 00000000..9a0eb9a4
--- /dev/null
+++ b/test/action-systems.07-action-systems-events-and-draws.test.js
@@ -0,0 +1,330 @@
+import { expect } from 'chai';
+import { Lemmings, setTestAppContext, useGlobalLemmings } from './helpers/lemmings.js';
+import { getAppContext } from '../js/core/dependencies.js';
+import { ActionBashSystem } from '../js/actions/ActionBashSystem.js';
+import { ActionBlockerSystem } from '../js/actions/ActionBlockerSystem.js';
+import { ActionBuildSystem } from '../js/actions/ActionBuildSystem.js';
+import { ActionClimbSystem } from '../js/actions/ActionClimbSystem.js';
+import { ActionCountdownSystem } from '../js/actions/ActionCountdownSystem.js';
+import { ActionDiggSystem } from '../js/actions/ActionDiggSystem.js';
+import { ActionDrowningSystem } from '../js/actions/ActionDrowningSystem.js';
+import { ActionExitingSystem } from '../js/actions/ActionExitingSystem.js';
+import { ActionExplodingSystem } from '../js/actions/ActionExplodingSystem.js';
+import { ActionFallSystem } from '../js/actions/ActionFallSystem.js';
+import { ActionFloatingSystem } from '../js/actions/ActionFloatingSystem.js';
+import { ActionFryingSystem } from '../js/actions/ActionFryingSystem.js';
+import { ActionHoistSystem } from '../js/actions/ActionHoistSystem.js';
+import { ActionJumpSystem } from '../js/actions/ActionJumpSystem.js';
+import { ActionMineSystem } from '../js/actions/ActionMineSystem.js';
+import { ActionOhNoSystem } from '../js/actions/ActionOhNoSystem.js';
+import { ActionShrugSystem } from '../js/actions/ActionShrugSystem.js';
+import { ActionSplatterSystem } from '../js/actions/ActionSplatterSystem.js';
+import { ActionWalkSystem } from '../js/actions/ActionWalkSystem.js';
+import { SoundEventTypes, SoundEffectIds } from '../js/game/SoundEvents.js';
+import '../js/level/Trigger.js';
+import '../js/level/TriggerTypes.js';
+import '../js/lemmings/LemmingStateType.js';
+import '../js/lemmings/SpriteTypes.js';
+import '../js/render/MaskTypes.js';
+import '../js/lemmings/Lemming.js';
+import { runScenarioTable } from './support/scenario-table.js';
+
+const makeMiniMap = () => ({
+  addDeath() {},
+  invalidateRegion() {},
+  onGroundChanged() {}
+});
+
+const makeLemmings = () => ({
+  game: {
+    lemmingManager: { miniMap: makeMiniMap() },
+    showDebug: false
+  }
+});
+
+// minimal global environment
+useGlobalLemmings(makeLemmings);
+globalThis.winW = 800;
+globalThis.winH = 600;
+
+const stubSprites = { getAnimation: () => ({ getFrame() { return {}; } }) };
+
+class StubLemming {
+  constructor(x = 0, y = 0) {
+    this.x = x;
+    this.y = y;
+    this.lookRight = true;
+    this.frameIndex = 0;
+    this.state = 0;
+    this.canClimb = false;
+    this.hasParachute = false;
+    this.disabled = false;
+    this.countdown = 0;
+  }
+  getDirection() { return this.lookRight ? 'right' : 'left'; }
+  disable() { this.disabled = true; }
+  setCountDown(act) { this.countdownAction = act; if (this.countdown > 0) return false; this.countdown = 80; return true; }
+  getCountDownTime() { return 8 - (this.countdown >> 4); }
+}
+
+class StubLevel {
+  constructor() {
+    this.ground = new Set();
+    this.clearedMasks = [];
+    this.setGroundCalls = [];
+    this.clearedPoints = [];
+    this.steelUnder = false;
+    this.arrowUnder = false;
+    this.stepHeight = null;
+    this.gapDepth = null;
+    this.steelGround = () => false;
+    this.arrowAt = () => false;
+  }
+  key(x, y) { return `${x},${y}`; }
+  hasGroundAt(x, y) { return this.ground.has(this.key(x, y)); }
+  getGroundMaskLayer() {
+    const self = this;
+    return {
+      hasGroundAt(x, y) { return self.hasGroundAt(x, y); },
+      getSubLayer(x, y, w, h) {
+        return { width: w, height: h, hasGroundAt(dx, dy) { return self.hasGroundAt(x + dx, y + dy); } };
+      },
+      getColumnStepHeight(x, yTop, height) {
+        if (self.stepHeight !== null && self.stepHeight !== undefined) {
+          return self.stepHeight;
+        }
+        const end = yTop + height - 1;
+        for (let i = 0; i < height; i++) {
+          const y = end - i;
+          if (!self.hasGroundAt(x, y)) return i;
+        }
+        return height;
+      },
+      getColumnGapDepth(x, yTop, height) {
+        if (self.gapDepth !== null && self.gapDepth !== undefined) {
+          return self.gapDepth;
+        }
+        for (let i = 0; i < height; i++) {
+          const y = yTop + i;
+          if (self.hasGroundAt(x, y)) return i + 1;
+        }
+        return height + 1;
+      }
+    };
+  }
+  clearGroundWithMask(mask, x, y) { this.clearedMasks.push({ mask, x, y }); }
+  clearGroundWithMaskCount(mask, x, y) {
+    this.clearGroundWithMask(mask, x, y);
+    return this.clearCount ?? 1;
+  }
+  hasSteelUnderMask() { return this.steelUnder; }
+  hasArrowUnderMask() { return this.arrowUnder; }
+  isArrowAt(x, y, direction) { return this.arrowAt(x, y, direction); }
+  clearGroundAt(x, y) { this.clearedPoints.push(this.key(x, y)); this.ground.delete(this.key(x, y)); }
+  setGroundAt(x, y) { this.setGroundCalls.push(this.key(x, y)); this.ground.add(this.key(x, y)); }
+  isSteelGround(x, y) { return this.steelGround(this.key(x, y)); }
+  isOutOfLevel(y) { return y < 0 || y >= 50; }
+}
+
+class StubTriggerManager {
+  constructor() { this.added = []; this.removed = []; }
+  add(t) { this.added.push(t); }
+  removeByOwner(o) { this.removed.push(o); }
+}
+
+class StubGVC { constructor() { this.count = 0; } addSurvivor() { this.count++; } }
+
+class DummyMask { constructor() { this.offsetX = 0; this.offsetY = 0; this.width = 0; this.height = 0; } at() { return false; } }
+function stubMasks() {
+  return {
+    GetMask() {
+      return { GetMask() { return new DummyMask(); } };
+    }
+  };
+}
+
+function useSoundBus(calls) {
+  const base = getAppContext() ?? {};
+  return setTestAppContext({
+    ...base,
+    game: {
+      ...(base.game ?? {}),
+      soundEvents: {
+        emitSfx(type, sfxId, data) {
+          calls.push({ type, sfxId, data });
+        }
+      }
+    }
+  });
+}
+
+function withoutSoundBus() {
+  const base = getAppContext() ?? {};
+  return setTestAppContext({
+    ...base,
+    game: {
+      ...(base.game ?? {}),
+      soundEvents: null
+    }
+  });
+}
+
+function withoutLemmingManager() {
+  const base = getAppContext() ?? {};
+  return setTestAppContext({
+    ...base,
+    game: {
+      ...(base.game ?? {}),
+      lemmingManager: null
+    }
+  });
+}
+
+function makeRuntime(calls = [], miniMap = makeMiniMap()) {
+  return {
+    soundEvents: {
+      emitSfx(type, sfxId, data) {
+        calls.push({ type, sfxId, data });
+      }
+    },
+    miniMap
+  };
+}
+
+function attachRuntime(sys, calls = [], miniMap = makeMiniMap()) {
+  sys.setRuntime?.(makeRuntime(calls, miniMap));
+  return sys;
+}
+
+// helpers for controlled Action systems
+class TestBashSystem extends ActionBashSystem {
+  constructor(gap, horiz) { super(stubSprites, stubMasks()); this.gap = gap; this.horiz = horiz; }
+  findGapDelta() { return this.gap; }
+  findHorizontalSpace() { return this.horiz; }
+}
+
+class TestMineSystem extends ActionMineSystem {
+  constructor(haveSteel, haveArrow) { super(stubSprites, stubMasks()); this.haveSteel = haveSteel; this.haveArrow = haveArrow; this.cleared = 0; }
+  process(level, lem) { return super.process(level, lem); }
+}
+
+describe('Action systems events and draws', function() {
+  it('ActionFallSystem and FloatingSystem draw frames', function() {
+    const display = { frames: [], drawFrame(frame, x, y) { this.frames.push({ frame, x, y }); } };
+
+    const fall = new ActionFallSystem(stubSprites);
+    const fallLem = new StubLemming();
+    fall.draw(display, fallLem);
+
+    const floatSys = new ActionFloatingSystem(stubSprites);
+    const floatLem = new StubLemming();
+    floatSys.draw(display, floatLem);
+
+    expect(display.frames.length).to.equal(2);
+  });
+
+  it('ActionFryingSystem reports deaths to minimap', function() {
+    const miniMap = { deaths: [], addDeath(x, y) { this.deaths.push({ x, y }); } };
+    const sys = attachRuntime(new ActionFryingSystem(stubSprites), [], miniMap);
+    const level = new StubLevel();
+    const lem = new StubLemming();
+    lem.frameIndex = 12;
+
+    sys.process(level, lem);
+
+    expect(miniMap.deaths[0]).to.eql({ x: 0, y: 0 });
+  });
+
+  it('ActionFryingSystem moves when no ground is ahead', function() {
+    const sys = new ActionFryingSystem(stubSprites);
+    const level = new StubLevel();
+    const lem = new StubLemming();
+    const x0 = lem.x;
+    sys.process(level, lem);
+    expect(lem.x).to.equal(x0 + 1);
+  });
+
+  it('ActionHoistSystem handles invalid frameIndex values', function() {
+    const sys = new ActionHoistSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.frameIndex = NaN;
+    expect(sys.process(new StubLevel(), lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
+  });
+
+  it('ActionMineSystem emits steel hit sound', function() {
+    const calls = [];
+    const restore = useSoundBus(calls);
+    const level = new StubLevel();
+    level.steelUnder = true;
+    const sys = attachRuntime(new ActionMineSystem(stubSprites, stubMasks()), calls);
+    const lem = new StubLemming();
+    lem.id = 8;
+    sys.process(level, lem);
+    restore();
+
+    expect(calls[0].type).to.equal(SoundEventTypes.STEEL_HIT);
+    expect(calls[0].sfxId).to.equal(SoundEffectIds.STEEL_HIT);
+  });
+
+  it('ActionMineSystem keeps mining when ground remains', function() {
+    const level = new StubLevel();
+    const sys = new ActionMineSystem(stubSprites, stubMasks());
+    const lem = new StubLemming();
+    lem.frameIndex = 14; // -> 15
+    level.ground.add(level.key(1, 0));
+    const res = sys.process(level, lem);
+    expect(res).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
+    expect(lem.x).to.equal(1);
+  });
+
+  it('ActionOhNoSystem and SplatterSystem trigger handlers', function() {
+    const calls = [];
+    const restore = useSoundBus(calls);
+
+    const miniMap = { deaths: [], addDeath(x, y) { this.deaths.push({ x, y }); } };
+    const ohNo = attachRuntime(new ActionOhNoSystem(stubSprites), calls, miniMap);
+    const ohNoLem = new StubLemming();
+    ohNoLem.frameIndex = 15;
+    expect(ohNo.triggerLemAction(ohNoLem)).to.equal(false);
+
+    ohNo.draw({ drawFrame() {} }, ohNoLem);
+
+    const splatter = attachRuntime(new ActionSplatterSystem(stubSprites), calls, miniMap);
+    const splatLem = new StubLemming();
+    splatLem.id = 9;
+    splatLem.frameIndex = 15;
+    splatLem.lastTriggerType = null;
+    expect(splatter.triggerLemAction(splatLem)).to.equal(false);
+    splatter.draw({ drawFrame() {} }, splatLem);
+    splatLem.frameIndex = 0;
+    splatter.process(new StubLevel(), splatLem);
+
+    restore();
+
+    expect(miniMap.deaths.length).to.equal(2);
+    expect(calls[0].type).to.equal(SoundEventTypes.LEMMING_SPLAT);
+  });
+
+  it('ActionWalkSystem triggerLemAction returns false', function() {
+    const sys = new ActionWalkSystem(stubSprites);
+    const lem = new StubLemming();
+    expect(sys.triggerLemAction(lem)).to.equal(false);
+  });
+
+  it('ActionWalkSystem advances when the path is clear', function() {
+    const sys = new ActionWalkSystem(stubSprites);
+    const level = new StubLevel();
+    level.stepHeight = 0;
+    level.gapDepth = 1;
+    const lem = new StubLemming();
+    const x0 = lem.x;
+    sys.process(level, lem);
+    expect(lem.x).to.equal(x0 + 1);
+  });
+
+  it('ActionDrowningSystem triggerLemAction returns false', function() {
+    const sys = new ActionDrowningSystem(stubSprites);
+    const lem = new StubLemming();
+    expect(sys.triggerLemAction(lem)).to.equal(false);
+  });
+});
diff --git a/test/action-systems.08-action-systems-branch-coverage.test.js b/test/action-systems.08-action-systems-branch-coverage.test.js
new file mode 100644
index 00000000..fc422523
--- /dev/null
+++ b/test/action-systems.08-action-systems-branch-coverage.test.js
@@ -0,0 +1,431 @@
+import { expect } from 'chai';
+import { Lemmings, setTestAppContext, useGlobalLemmings } from './helpers/lemmings.js';
+import { getAppContext } from '../js/core/dependencies.js';
+import { ActionBashSystem } from '../js/actions/ActionBashSystem.js';
+import { ActionBlockerSystem } from '../js/actions/ActionBlockerSystem.js';
+import { ActionBuildSystem } from '../js/actions/ActionBuildSystem.js';
+import { ActionClimbSystem } from '../js/actions/ActionClimbSystem.js';
+import { ActionCountdownSystem } from '../js/actions/ActionCountdownSystem.js';
+import { ActionDiggSystem } from '../js/actions/ActionDiggSystem.js';
+import { ActionDrowningSystem } from '../js/actions/ActionDrowningSystem.js';
+import { ActionExitingSystem } from '../js/actions/ActionExitingSystem.js';
+import { ActionExplodingSystem } from '../js/actions/ActionExplodingSystem.js';
+import { ActionFallSystem } from '../js/actions/ActionFallSystem.js';
+import { ActionFloatingSystem } from '../js/actions/ActionFloatingSystem.js';
+import { ActionFryingSystem } from '../js/actions/ActionFryingSystem.js';
+import { ActionHoistSystem } from '../js/actions/ActionHoistSystem.js';
+import { ActionJumpSystem } from '../js/actions/ActionJumpSystem.js';
+import { ActionMineSystem } from '../js/actions/ActionMineSystem.js';
+import { ActionOhNoSystem } from '../js/actions/ActionOhNoSystem.js';
+import { ActionShrugSystem } from '../js/actions/ActionShrugSystem.js';
+import { ActionSplatterSystem } from '../js/actions/ActionSplatterSystem.js';
+import { ActionWalkSystem } from '../js/actions/ActionWalkSystem.js';
+import { SoundEventTypes, SoundEffectIds } from '../js/game/SoundEvents.js';
+import '../js/level/Trigger.js';
+import '../js/level/TriggerTypes.js';
+import '../js/lemmings/LemmingStateType.js';
+import '../js/lemmings/SpriteTypes.js';
+import '../js/render/MaskTypes.js';
+import '../js/lemmings/Lemming.js';
+import { runScenarioTable } from './support/scenario-table.js';
+
+const makeMiniMap = () => ({
+  addDeath() {},
+  invalidateRegion() {},
+  onGroundChanged() {}
+});
+
+const makeLemmings = () => ({
+  game: {
+    lemmingManager: { miniMap: makeMiniMap() },
+    showDebug: false
+  }
+});
+
+// minimal global environment
+useGlobalLemmings(makeLemmings);
+globalThis.winW = 800;
+globalThis.winH = 600;
+
+const stubSprites = { getAnimation: () => ({ getFrame() { return {}; } }) };
+
+class StubLemming {
+  constructor(x = 0, y = 0) {
+    this.x = x;
+    this.y = y;
+    this.lookRight = true;
+    this.frameIndex = 0;
+    this.state = 0;
+    this.canClimb = false;
+    this.hasParachute = false;
+    this.disabled = false;
+    this.countdown = 0;
+  }
+  getDirection() { return this.lookRight ? 'right' : 'left'; }
+  disable() { this.disabled = true; }
+  setCountDown(act) { this.countdownAction = act; if (this.countdown > 0) return false; this.countdown = 80; return true; }
+  getCountDownTime() { return 8 - (this.countdown >> 4); }
+}
+
+class StubLevel {
+  constructor() {
+    this.ground = new Set();
+    this.clearedMasks = [];
+    this.setGroundCalls = [];
+    this.clearedPoints = [];
+    this.steelUnder = false;
+    this.arrowUnder = false;
+    this.stepHeight = null;
+    this.gapDepth = null;
+    this.steelGround = () => false;
+    this.arrowAt = () => false;
+  }
+  key(x, y) { return `${x},${y}`; }
+  hasGroundAt(x, y) { return this.ground.has(this.key(x, y)); }
+  getGroundMaskLayer() {
+    const self = this;
+    return {
+      hasGroundAt(x, y) { return self.hasGroundAt(x, y); },
+      getSubLayer(x, y, w, h) {
+        return { width: w, height: h, hasGroundAt(dx, dy) { return self.hasGroundAt(x + dx, y + dy); } };
+      },
+      getColumnStepHeight(x, yTop, height) {
+        if (self.stepHeight !== null && self.stepHeight !== undefined) {
+          return self.stepHeight;
+        }
+        const end = yTop + height - 1;
+        for (let i = 0; i < height; i++) {
+          const y = end - i;
+          if (!self.hasGroundAt(x, y)) return i;
+        }
+        return height;
+      },
+      getColumnGapDepth(x, yTop, height) {
+        if (self.gapDepth !== null && self.gapDepth !== undefined) {
+          return self.gapDepth;
+        }
+        for (let i = 0; i < height; i++) {
+          const y = yTop + i;
+          if (self.hasGroundAt(x, y)) return i + 1;
+        }
+        return height + 1;
+      }
+    };
+  }
+  clearGroundWithMask(mask, x, y) { this.clearedMasks.push({ mask, x, y }); }
+  clearGroundWithMaskCount(mask, x, y) {
+    this.clearGroundWithMask(mask, x, y);
+    return this.clearCount ?? 1;
+  }
+  hasSteelUnderMask() { return this.steelUnder; }
+  hasArrowUnderMask() { return this.arrowUnder; }
+  isArrowAt(x, y, direction) { return this.arrowAt(x, y, direction); }
+  clearGroundAt(x, y) { this.clearedPoints.push(this.key(x, y)); this.ground.delete(this.key(x, y)); }
+  setGroundAt(x, y) { this.setGroundCalls.push(this.key(x, y)); this.ground.add(this.key(x, y)); }
+  isSteelGround(x, y) { return this.steelGround(this.key(x, y)); }
+  isOutOfLevel(y) { return y < 0 || y >= 50; }
+}
+
+class StubTriggerManager {
+  constructor() { this.added = []; this.removed = []; }
+  add(t) { this.added.push(t); }
+  removeByOwner(o) { this.removed.push(o); }
+}
+
+class StubGVC { constructor() { this.count = 0; } addSurvivor() { this.count++; } }
+
+class DummyMask { constructor() { this.offsetX = 0; this.offsetY = 0; this.width = 0; this.height = 0; } at() { return false; } }
+function stubMasks() {
+  return {
+    GetMask() {
+      return { GetMask() { return new DummyMask(); } };
+    }
+  };
+}
+
+function useSoundBus(calls) {
+  const base = getAppContext() ?? {};
+  return setTestAppContext({
+    ...base,
+    game: {
+      ...(base.game ?? {}),
+      soundEvents: {
+        emitSfx(type, sfxId, data) {
+          calls.push({ type, sfxId, data });
+        }
+      }
+    }
+  });
+}
+
+function withoutSoundBus() {
+  const base = getAppContext() ?? {};
+  return setTestAppContext({
+    ...base,
+    game: {
+      ...(base.game ?? {}),
+      soundEvents: null
+    }
+  });
+}
+
+function withoutLemmingManager() {
+  const base = getAppContext() ?? {};
+  return setTestAppContext({
+    ...base,
+    game: {
+      ...(base.game ?? {}),
+      lemmingManager: null
+    }
+  });
+}
+
+function makeRuntime(calls = [], miniMap = makeMiniMap()) {
+  return {
+    soundEvents: {
+      emitSfx(type, sfxId, data) {
+        calls.push({ type, sfxId, data });
+      }
+    },
+    miniMap
+  };
+}
+
+function attachRuntime(sys, calls = [], miniMap = makeMiniMap()) {
+  sys.setRuntime?.(makeRuntime(calls, miniMap));
+  return sys;
+}
+
+// helpers for controlled Action systems
+class TestBashSystem extends ActionBashSystem {
+  constructor(gap, horiz) { super(stubSprites, stubMasks()); this.gap = gap; this.horiz = horiz; }
+  findGapDelta() { return this.gap; }
+  findHorizontalSpace() { return this.horiz; }
+}
+
+class TestMineSystem extends ActionMineSystem {
+  constructor(haveSteel, haveArrow) { super(stubSprites, stubMasks()); this.haveSteel = haveSteel; this.haveArrow = haveArrow; this.cleared = 0; }
+  process(level, lem) { return super.process(level, lem); }
+}
+
+describe('Action systems branch coverage', function() {
+  it('ActionBashSystem handles steel without sound bus', function() {
+    const level = new StubLevel();
+    level.steelUnder = true;
+    const sys = new ActionBashSystem(stubSprites, stubMasks());
+    const lem = new StubLemming();
+    lem.frameIndex = 2;
+    const restore = withoutSoundBus();
+    try {
+      expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.SHRUG);
+    } finally {
+      restore();
+    }
+  });
+
+  it('ActionBashSystem checks left edge when bashing', function() {
+    const level = new StubLevel();
+    const sys = new TestBashSystem(0, 4);
+    const lem = new StubLemming();
+    lem.lookRight = false;
+    lem.frameIndex = 4;
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
+  });
+
+  it('ActionBuildSystem skips missing sound bus', function() {
+    const level = new StubLevel();
+    const sys = new ActionBuildSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.frameIndex = 8;
+    lem.state = 9;
+    const restore = withoutSoundBus();
+    try {
+      expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
+    } finally {
+      restore();
+    }
+  });
+
+  it('ActionBuildSystem moves left when blocked', function() {
+    const level = new StubLevel();
+    const sys = new ActionBuildSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.lookRight = false;
+    lem.frameIndex = 15;
+    level.ground.add(level.key(-1, -2));
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
+    expect(lem.x).to.equal(-1);
+  });
+
+  it('ActionBuildSystem checks roof behind when building backwards', function() {
+    const level = new StubLevel();
+    const sys = new ActionBuildSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.lookRight = false;
+    lem.frameIndex = 15;
+    lem.state = 10;
+    level.ground.add(level.key(-4, -10));
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
+    expect(lem.lookRight).to.equal(true);
+  });
+
+  it('ActionClimbSystem flips from the left wall', function() {
+    const level = new StubLevel();
+    const sys = new ActionClimbSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.lookRight = false;
+    lem.frameIndex = 4;
+    level.ground.add(level.key(lem.x + 1, lem.y - 9));
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.FALLING);
+    expect(lem.lookRight).to.equal(true);
+    expect(lem.x).to.equal(2);
+  });
+
+  it('ActionCountdownSystem handles no sound bus at zero', function() {
+    const sys = new ActionCountdownSystem(stubMasks());
+    const lem = new StubLemming();
+    lem.countdown = 1;
+    lem.setCountDown = act => { lem.countdownAction = act; return true; };
+    const restore = withoutSoundBus();
+    try {
+      expect(sys.process(new StubLevel(), lem)).to.equal(Lemmings.LemmingStateType.OHNO);
+    } finally {
+      restore();
+    }
+  });
+
+  it('ActionDiggSystem shrugs on steel without sound bus', function() {
+    const sys = new ActionDiggSystem(stubSprites);
+    const level = new StubLevel();
+    level.steelGround = () => true;
+    const lem = new StubLemming();
+    const restore = withoutSoundBus();
+    try {
+      expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.SHRUG);
+    } finally {
+      restore();
+    }
+  });
+
+  it('ActionDrowningSystem moves left without sound bus', function() {
+    const sys = new ActionDrowningSystem(stubSprites);
+    const level = new StubLevel();
+    const lem = new StubLemming();
+    lem.lookRight = false;
+    const restore = withoutSoundBus();
+    try {
+      sys.process(level, lem);
+    } finally {
+      restore();
+    }
+    expect(lem.x).to.equal(-1);
+  });
+
+  it('ActionExitingSystem handles missing sound bus on entry', function() {
+    const gvc = new StubGVC();
+    const sys = new ActionExitingSystem(stubSprites, gvc);
+    const lem = new StubLemming();
+    const restore = withoutSoundBus();
+    try {
+      expect(sys.process(new StubLevel(), lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
+    } finally {
+      restore();
+    }
+    expect(gvc.count).to.equal(0);
+  });
+
+  it('ActionExplodingSystem handles missing sound bus and minimap', function() {
+    const triggerManager = { removed: [], removeByOwner(lem) { this.removed.push(lem); } };
+    const sys = new ActionExplodingSystem(stubSprites, stubMasks(), triggerManager, { draw() {} });
+    const level = { clearGroundWithMask() { return false; } };
+    const lem = new StubLemming();
+    const restoreSound = withoutSoundBus();
+    const restoreManager = withoutLemmingManager();
+    try {
+      sys.process(level, lem);
+    } finally {
+      restoreManager();
+      restoreSound();
+    }
+    expect(triggerManager.removed[0]).to.equal(lem);
+  });
+
+  it('ActionFryingSystem ignores missing minimap', function() {
+    const sys = new ActionFryingSystem(stubSprites);
+    const level = new StubLevel();
+    const lem = new StubLemming();
+    lem.frameIndex = 12;
+    const restore = withoutLemmingManager();
+    try {
+      sys.process(level, lem);
+    } finally {
+      restore();
+    }
+    expect(lem.frameIndex).to.equal(13);
+  });
+
+  it('ActionFryingSystem moves left when no ground', function() {
+    const sys = new ActionFryingSystem(stubSprites);
+    const level = new StubLevel();
+    const lem = new StubLemming();
+    lem.lookRight = false;
+    sys.process(level, lem);
+    expect(lem.x).to.equal(-1);
+  });
+
+  it('ActionJumpSystem moves left when jumping', function() {
+    const level = new StubLevel();
+    const sys = new ActionJumpSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.lookRight = false;
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
+    expect(lem.x).to.equal(-1);
+  });
+
+  it('ActionMineSystem shrugs on steel without sound bus', function() {
+    const level = new StubLevel();
+    level.steelUnder = true;
+    const sys = new ActionMineSystem(stubSprites, stubMasks());
+    const lem = new StubLemming();
+    const restore = withoutSoundBus();
+    try {
+      expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.SHRUG);
+    } finally {
+      restore();
+    }
+  });
+
+  it('ActionMineSystem moves left when mining', function() {
+    const level = new StubLevel();
+    const sys = new ActionMineSystem(stubSprites, stubMasks());
+    const lem = new StubLemming();
+    lem.lookRight = false;
+    lem.frameIndex = 14;
+    level.ground.add(level.key(-1, 0));
+    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
+    expect(lem.x).to.equal(-1);
+  });
+
+  it('ActionSplatterSystem skips sound bus when missing', function() {
+    const sys = new ActionSplatterSystem(stubSprites);
+    const lem = new StubLemming();
+    lem.frameIndex = 0;
+    const restore = withoutSoundBus();
+    try {
+      expect(sys.process(new StubLevel(), lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
+    } finally {
+      restore();
+    }
+  });
+
+  it('ActionWalkSystem moves left when walking', function() {
+    const sys = new ActionWalkSystem(stubSprites);
+    const level = new StubLevel();
+    level.stepHeight = 0;
+    level.gapDepth = 1;
+    const lem = new StubLemming();
+    lem.lookRight = false;
+    sys.process(level, lem);
+    expect(lem.x).to.equal(-1);
+  });
+});
diff --git a/test/action-systems.test.js b/test/action-systems.test.js
deleted file mode 100644
index af594b72..00000000
--- a/test/action-systems.test.js
+++ /dev/null
@@ -1,1716 +0,0 @@
-import { expect } from 'chai';
-import { Lemmings, setGlobalLemmings, useGlobalLemmings } from './helpers/lemmings.js';
-import { ActionBashSystem } from '../js/actions/ActionBashSystem.js';
-import { ActionBlockerSystem } from '../js/actions/ActionBlockerSystem.js';
-import { ActionBuildSystem } from '../js/actions/ActionBuildSystem.js';
-import { ActionClimbSystem } from '../js/actions/ActionClimbSystem.js';
-import { ActionCountdownSystem } from '../js/actions/ActionCountdownSystem.js';
-import { ActionDiggSystem } from '../js/actions/ActionDiggSystem.js';
-import { ActionDrowningSystem } from '../js/actions/ActionDrowningSystem.js';
-import { ActionExitingSystem } from '../js/actions/ActionExitingSystem.js';
-import { ActionExplodingSystem } from '../js/actions/ActionExplodingSystem.js';
-import { ActionFallSystem } from '../js/actions/ActionFallSystem.js';
-import { ActionFloatingSystem } from '../js/actions/ActionFloatingSystem.js';
-import { ActionFryingSystem } from '../js/actions/ActionFryingSystem.js';
-import { ActionHoistSystem } from '../js/actions/ActionHoistSystem.js';
-import { ActionJumpSystem } from '../js/actions/ActionJumpSystem.js';
-import { ActionMineSystem } from '../js/actions/ActionMineSystem.js';
-import { ActionOhNoSystem } from '../js/actions/ActionOhNoSystem.js';
-import { ActionShrugSystem } from '../js/actions/ActionShrugSystem.js';
-import { ActionSplatterSystem } from '../js/actions/ActionSplatterSystem.js';
-import { ActionWalkSystem } from '../js/actions/ActionWalkSystem.js';
-import { SoundEventTypes, SoundEffectIds } from '../js/game/SoundEvents.js';
-import '../js/level/Trigger.js';
-import '../js/level/TriggerTypes.js';
-import '../js/lemmings/LemmingStateType.js';
-import '../js/lemmings/SpriteTypes.js';
-import '../js/render/MaskTypes.js';
-import '../js/lemmings/Lemming.js';
-
-const makeMiniMap = () => ({
-  addDeath() {},
-  invalidateRegion() {},
-  onGroundChanged() {}
-});
-
-const makeLemmings = () => ({
-  game: {
-    lemmingManager: { miniMap: makeMiniMap() },
-    showDebug: false
-  }
-});
-
-// minimal global environment
-useGlobalLemmings(makeLemmings);
-globalThis.winW = 800;
-globalThis.winH = 600;
-
-const stubSprites = { getAnimation: () => ({ getFrame() { return {}; } }) };
-
-class StubLemming {
-  constructor(x = 0, y = 0) {
-    this.x = x;
-    this.y = y;
-    this.lookRight = true;
-    this.frameIndex = 0;
-    this.state = 0;
-    this.canClimb = false;
-    this.hasParachute = false;
-    this.disabled = false;
-    this.countdown = 0;
-  }
-  getDirection() { return this.lookRight ? 'right' : 'left'; }
-  disable() { this.disabled = true; }
-  setCountDown(act) { this.countdownAction = act; if (this.countdown > 0) return false; this.countdown = 80; return true; }
-  getCountDownTime() { return 8 - (this.countdown >> 4); }
-}
-
-class StubLevel {
-  constructor() {
-    this.ground = new Set();
-    this.clearedMasks = [];
-    this.setGroundCalls = [];
-    this.clearedPoints = [];
-    this.steelUnder = false;
-    this.arrowUnder = false;
-    this.stepHeight = null;
-    this.gapDepth = null;
-    this.steelGround = () => false;
-  }
-  key(x, y) { return `${x},${y}`; }
-  hasGroundAt(x, y) { return this.ground.has(this.key(x, y)); }
-  getGroundMaskLayer() {
-    const self = this;
-    return {
-      hasGroundAt(x, y) { return self.hasGroundAt(x, y); },
-      getSubLayer(x, y, w, h) {
-        return { width: w, height: h, hasGroundAt(dx, dy) { return self.hasGroundAt(x + dx, y + dy); } };
-      },
-      getColumnStepHeight(x, yTop, height) {
-        if (self.stepHeight !== null && self.stepHeight !== undefined) {
-          return self.stepHeight;
-        }
-        const end = yTop + height - 1;
-        for (let i = 0; i < height; i++) {
-          const y = end - i;
-          if (!self.hasGroundAt(x, y)) return i;
-        }
-        return height;
-      },
-      getColumnGapDepth(x, yTop, height) {
-        if (self.gapDepth !== null && self.gapDepth !== undefined) {
-          return self.gapDepth;
-        }
-        for (let i = 0; i < height; i++) {
-          const y = yTop + i;
-          if (self.hasGroundAt(x, y)) return i + 1;
-        }
-        return height + 1;
-      }
-    };
-  }
-  clearGroundWithMask(mask, x, y) { this.clearedMasks.push({ mask, x, y }); }   
-  clearGroundWithMaskCount(mask, x, y) {
-    this.clearGroundWithMask(mask, x, y);
-    return this.clearCount ?? 1;
-  }
-  hasSteelUnderMask() { return this.steelUnder; }
-  hasArrowUnderMask() { return this.arrowUnder; }
-  clearGroundAt(x, y) { this.clearedPoints.push(this.key(x, y)); this.ground.delete(this.key(x, y)); }
-  setGroundAt(x, y) { this.setGroundCalls.push(this.key(x, y)); this.ground.add(this.key(x, y)); }
-  isSteelGround(x, y) { return this.steelGround(this.key(x, y)); }
-  isOutOfLevel(y) { return y < 0 || y >= 50; }
-}
-
-class StubTriggerManager {
-  constructor() { this.added = []; this.removed = []; }
-  add(t) { this.added.push(t); }
-  removeByOwner(o) { this.removed.push(o); }
-}
-
-class StubGVC { constructor() { this.count = 0; } addSurvivor() { this.count++; } }
-
-class DummyMask { constructor() { this.offsetX = 0; this.offsetY = 0; this.width = 0; this.height = 0; } at() { return false; } }
-function stubMasks() {
-  return {
-    GetMask() {
-      return { GetMask() { return new DummyMask(); } };
-    }
-  };
-}
-
-function useSoundBus(calls) {
-  const base = globalThis.lemmings ?? {};
-  return setGlobalLemmings({
-    ...base,
-    game: {
-      ...(base.game ?? {}),
-      soundEvents: {
-        emitSfx(type, sfxId, data) {
-          calls.push({ type, sfxId, data });
-        }
-      }
-    }
-  });
-}
-
-function withoutSoundBus() {
-  const base = globalThis.lemmings ?? {};
-  return setGlobalLemmings({
-    ...base,
-    game: {
-      ...(base.game ?? {}),
-      soundEvents: null
-    }
-  });
-}
-
-function withoutLemmingManager() {
-  const base = globalThis.lemmings ?? {};
-  return setGlobalLemmings({
-    ...base,
-    game: {
-      ...(base.game ?? {}),
-      lemmingManager: null
-    }
-  });
-}
-
-function ensureMiniMap() {
-  return globalThis.lemmings.game.lemmingManager;
-}
-
-// helpers for controlled Action systems
-class TestBashSystem extends ActionBashSystem {
-  constructor(gap, horiz) { super(stubSprites, stubMasks()); this.gap = gap; this.horiz = horiz; }
-  findGapDelta() { return this.gap; }
-  findHorizontalSpace() { return this.horiz; }
-}
-
-class TestMineSystem extends ActionMineSystem {
-  constructor(haveSteel, haveArrow) { super(stubSprites, stubMasks()); this.haveSteel = haveSteel; this.haveArrow = haveArrow; this.cleared = 0; }
-  process(level, lem) { return super.process(level, lem); }
-}
-
-
-describe('Action Systems process()', function() {
-  it('ActionBashSystem handles masks and gaps', function() {
-    const level = new StubLevel();
-    const lem = new StubLemming();
-    const sys = new TestBashSystem(3, 0);
-    lem.frameIndex = 10; // state 11 after ++
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.FALLING);
-
-    const sys2 = new TestBashSystem(0, 4);
-    lem.frameIndex = 1; // ->2
-    sys2.process(level, lem);
-    expect(level.clearedMasks).to.have.length(1);
-
-    level.steelUnder = true;
-    lem.frameIndex = 2; // ->3
-    expect(sys2.process(level, lem)).to.equal(Lemmings.LemmingStateType.SHRUG);
-    level.steelUnder = false;
-
-    lem.frameIndex = 4; // ->5 horiz space 4
-    expect(sys2.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
-
-    lem.frameIndex = 3; // ->4 horiz space !=4
-    expect(sys2.process(level, lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
-  });
-
-  it('ActionBashSystem moves horizontally after frame 10', function() {
-    const level = new StubLevel();
-    const sys = new TestBashSystem(0, 0);
-
-    const lem1 = new StubLemming();
-    lem1.frameIndex = 9; // ->10
-    const x1 = lem1.x;
-    sys.process(level, lem1);
-    expect(lem1.x).to.equal(x1);
-
-    const lem2 = new StubLemming();
-    lem2.frameIndex = 10; // ->11
-    const x2 = lem2.x;
-    expect(sys.process(level, lem2)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
-    expect(lem2.x).to.equal(x2 + 1);
-
-    const lem3 = new StubLemming();
-    lem3.lookRight = false;
-    lem3.frameIndex = 10; // ->11
-    const x3 = lem3.x;
-    sys.process(level, lem3);
-    expect(lem3.x).to.equal(x3 - 1);
-  });
-
-  it('ActionBashSystem keeps bashing when space remains', function() {
-    const level = new StubLevel();
-    const sys = new TestBashSystem(0, 3); // horizontal space < 4
-    const lem = new StubLemming();
-    lem.frameIndex = 4; // ->5
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
-  });
-
-  it('ActionBlockerSystem adds and removes triggers', function() {
-    const level = new StubLevel();
-    const tm = new StubTriggerManager();
-    const sys = new ActionBlockerSystem(stubSprites, tm);
-    const lem = new StubLemming();
-    lem.state = 0;
-    sys.process(level, lem);
-    expect(tm.added.length).to.equal(2);
-    lem.state = 1;
-    level.ground.delete(level.key(lem.x, lem.y + 1));
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.FALLING);
-    expect(tm.removed[0]).to.equal(lem);
-  });
-
-  it('ActionBlockerSystem keeps triggers until ground is lost', function() {
-    const level = new StubLevel();
-    const tm = new StubTriggerManager();
-    const sys = new ActionBlockerSystem(stubSprites, tm);
-    const lem = new StubLemming();
-    level.ground.add(level.key(lem.x, lem.y + 1));
-    lem.state = 0;
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
-    expect(tm.added.length).to.equal(2);
-    expect(tm.removed.length).to.equal(0);
-    lem.state = 1;
-    level.ground.delete(level.key(lem.x, lem.y + 1));
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.FALLING);
-    expect(tm.removed[0]).to.equal(lem);
-  });
-
-  it('ActionBuildSystem lays bricks and shrugs when done', function() {
-    const level = new StubLevel();
-    const sys = new ActionBuildSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.frameIndex = 8; // ->9 brick
-    sys.process(level, lem);
-    expect(level.setGroundCalls).to.have.length(6);
-
-    lem.frameIndex = 15; // ->0
-    lem.state = 11;
-    sys.process(level, lem);
-    expect(lem.state).to.equal(12);
-
-    lem.frameIndex = 15;
-    lem.state = 12;
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.SHRUG);
-  });
-
-  it('ActionClimbSystem hoists or falls', function() {
-    const level = new StubLevel();
-    const sys = new ActionClimbSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.frameIndex = 2; // ->3, below 4 => check top
-    level.ground.delete(level.key(lem.x, lem.y - 7 - 4));
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.HOISTING);
-
-    lem.frameIndex = 4; // ->5, climbing upward
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
-
-    lem.frameIndex = 6; // ->7 >=4 path
-    level.ground.add(level.key(lem.x - 1, lem.y - 9));
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.FALLING);
-  });
-
-  it('ActionClimbSystem triggers HOISTING at the top', function() {
-    const level = new StubLevel();
-    const sys = new ActionClimbSystem(stubSprites);
-    const lem = new StubLemming();
-    // wall continues for two steps but top is clear
-    level.ground.add(level.key(lem.x, lem.y - 8));
-    level.ground.add(level.key(lem.x, lem.y - 9));
-    lem.frameIndex = 2; // ->3 near the top
-    const result = sys.process(level, lem);
-    expect(result).to.equal(Lemmings.LemmingStateType.HOISTING);
-    expect(lem.y).to.equal(-1);
-  });
-
-  it('ActionClimbSystem falls and flips when side blocked', function() {
-    const level = new StubLevel();
-    const sys = new ActionClimbSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.frameIndex = 4; // ->5 climbing up the wall
-    level.ground.add(level.key(lem.x - 1, lem.y - 9));
-    const result = sys.process(level, lem);
-    expect(result).to.equal(Lemmings.LemmingStateType.FALLING);
-    expect(lem.lookRight).to.equal(false);
-    expect(lem.x).to.equal(-2);
-  });
-
-  it('ActionCountdownSystem counts to explosion', function() {
-    const sys = new ActionCountdownSystem({ GetMask() { return new DummyMask(); } });
-    const lem = new StubLemming();
-    lem.countdown = 2;
-    expect(sys.process(new StubLevel(), lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
-    expect(lem.countdown).to.equal(1);
-    lem.countdown = 1;
-    expect(sys.process(new StubLevel(), lem)).to.equal(Lemmings.LemmingStateType.OHNO);
-  });
-
-  it('ActionDiggSystem digs until out', function() {
-    const sys = new ActionDiggSystem(stubSprites);
-    const level = new StubLevel();
-    const lem = new StubLemming();
-    lem.state = 0;
-    sys.process(level, lem);
-    expect(lem.state).to.equal(1);
-
-    lem.state = 1;
-    lem.frameIndex = 7; // ->8 triggers digRow
-    level.isOutOfLevel = () => false;
-    sys.digRow = () => false;
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.FALLING);
-
-    level.isOutOfLevel = () => true;
-    lem.frameIndex = 15; // ->0 but !0 & 0x07 -> 1? Wait 0? We'll set 0.
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.FALLING);
-  });
-
-  it('ActionDrowningSystem toggles direction and exits', function() {
-    const level = new StubLevel();
-    const sys = new ActionDrowningSystem(stubSprites);
-    const lem = new StubLemming();
-    level.ground.add(level.key(lem.x + 8, lem.y));
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
-    expect(lem.disabled).to.equal(true);
-    lem.frameIndex = 15;
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.OUT_OF_LEVEL);
-  });
-
-  it('ActionExitingSystem awards survivor', function() {
-    const gvc = new StubGVC();
-    const sys = new ActionExitingSystem(stubSprites, gvc);
-    const lem = new StubLemming();
-    lem.frameIndex = 7;
-    expect(sys.process(new StubLevel(), lem)).to.equal(Lemmings.LemmingStateType.OUT_OF_LEVEL);
-    expect(gvc.count).to.equal(1);
-  });
-
-  it('ActionExplodingSystem clears mask and exits', function() {
-    const tm = new StubTriggerManager();
-    const sys = new ActionExplodingSystem(stubSprites, stubMasks(), tm, { draw() {} });
-    const level = new StubLevel();
-    const lem = new StubLemming();
-    lem.frameIndex = 0;
-    sys.process(level, lem); // ->1 no clear
-    lem.frameIndex = 1;
-    sys.process(level, lem); // ->2 clears
-    expect(level.clearedMasks).to.have.length.above(0);
-    lem.frameIndex = 51;
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.OUT_OF_LEVEL);
-  });
-
-  it('ActionFallSystem detects splat and float', function() {
-    const level = new StubLevel();
-    const sys = new ActionFallSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.state = 17;
-    lem.hasParachute = true;
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.FLOATING);
-
-    lem.state = 0;
-    level.ground.add(level.key(lem.x, lem.y));
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
-
-    lem.state = Lemmings.Lemming.LEM_MAX_FALLING + 1;
-    lem.hasParachute = false;
-    level.ground.add(level.key(lem.x, lem.y));
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.SPLATTING);
-  });
-
-  it('ActionFloatingSystem lands when hitting ground', function() {
-    const sys = new ActionFloatingSystem(stubSprites);
-    const level = new StubLevel();
-    const lem = new StubLemming();
-    level.ground.add(level.key(lem.x, lem.y));
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
-    expect(lem.y).to.equal(0);
-    level.ground.clear();
-    lem.frameIndex = 15;
-    sys.process(level, lem);
-    expect(lem.frameIndex).to.equal(8);
-  });
-
-  it('ActionFloatingSystem trigger sets hasParachute once', function() {
-    const sys = new ActionFloatingSystem(stubSprites);
-    const lem = new StubLemming();
-    expect(sys.triggerLemAction(lem)).to.equal(true);
-    expect(lem.hasParachute).to.equal(true);
-    expect(sys.triggerLemAction(lem)).to.equal(false);
-    expect(lem.hasParachute).to.equal(true);
-  });
-
-  it('opens umbrella mid fall and walks on landing', function() {
-    const fallSys = new ActionFallSystem(stubSprites);
-    const floatSys = new ActionFloatingSystem(stubSprites);
-    const level = new StubLevel();
-    const lem = new StubLemming();
-    lem.state = 17;
-    fallSys.process(level, lem); // fall one step
-    expect(lem.y).to.equal(3);
-    expect(floatSys.triggerLemAction(lem)).to.equal(true);
-    level.ground.add(level.key(lem.x, 5));
-    expect(fallSys.process(level, lem)).to.equal(Lemmings.LemmingStateType.FLOATING);
-    expect(floatSys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
-    expect(lem.y).to.equal(5);
-  });
-
-  it('ActionFryingSystem burns then exits', function() {
-    const level = new StubLevel();
-    const sys = new ActionFryingSystem(stubSprites);
-    const lem = new StubLemming();
-    sys.process(level, lem);
-    expect(lem.disabled).to.equal(true);
-    lem.frameIndex = 13;
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.OUT_OF_LEVEL);
-  });
-
-  it('ActionHoistSystem moves up then walks', function() {
-    const level = new StubLevel();
-    const sys = new ActionHoistSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.frameIndex = 3;
-    sys.process(level, lem);
-    expect(lem.y).to.equal(-2);
-    lem.frameIndex = 7;
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
-  });
-
-  it('ActionJumpSystem jumps up then walks', function() {
-    const level = new StubLevel();
-    level.ground.add(level.key(1, -1));
-    const sys = new ActionJumpSystem(stubSprites);
-    const lem = new StubLemming();
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
-    lem.y = -5;
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
-  });
-
-  it('ActionMineSystem clears ground and falls', function() {
-    const level = new StubLevel();
-    const sys = new ActionMineSystem(stubSprites, stubMasks());
-    const lem = new StubLemming();
-    lem.frameIndex = 1; // ->2 mask clear
-    sys.process(level, lem);
-    expect(level.clearedMasks.length).to.equal(1);
-    lem.frameIndex = 14; // ->15 moves check ground
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.FALLING);
-    level.ground.delete(level.key(lem.x, lem.y));
-    lem.frameIndex = 15; // ->0 case 15
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
-  });
-
-  it('ActionOhNoSystem counts to explode', function() {
-    const level = new StubLevel();
-    const sys = new ActionOhNoSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.frameIndex = 15;
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.EXPLODING);
-  });
-
-  it('ActionShrugSystem returns to walking', function() {
-    const sys = new ActionShrugSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.frameIndex = 7;
-    expect(sys.process(new StubLevel(), lem)).to.equal(Lemmings.LemmingStateType.WALKING);
-  });
-
-  it('ActionSplatterSystem finishes quickly', function() {
-    const sys = new ActionSplatterSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.frameIndex = 15;
-    expect(sys.process(new StubLevel(), lem)).to.equal(Lemmings.LemmingStateType.OUT_OF_LEVEL);
-  });
-
-  it('ActionWalkSystem handles steps and gaps', function() {
-    const sys = new ActionWalkSystem(stubSprites);
-
-    const level1 = new StubLevel();
-    const lem1 = new StubLemming();
-    lem1.canClimb = true;
-    level1.stepHeight = 8;
-    expect(sys.process(level1, lem1)).to.equal(Lemmings.LemmingStateType.CLIMBING);
-
-    const level2 = new StubLevel();
-    const lem2 = new StubLemming();
-    level2.stepHeight = 5;
-    expect(sys.process(level2, lem2)).to.equal(Lemmings.LemmingStateType.JUMPING);
-
-    const level3 = new StubLevel();
-    const lem3 = new StubLemming();
-    level3.stepHeight = 2;
-    expect(sys.process(level3, lem3)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
-
-    const level4 = new StubLevel();
-    const lem4 = new StubLemming();
-    level4.stepHeight = 0;
-    level4.gapDepth = 4;
-    expect(sys.process(level4, lem4)).to.equal(Lemmings.LemmingStateType.FALLING);
-  });
-
-  it('ActionBashSystem stops on arrow under mask', function() {
-    const level = new StubLevel();
-    level.arrowUnder = true;
-    const sys = new TestBashSystem(0, 0);
-    const lem = new StubLemming();
-    lem.frameIndex = 2; // ->3
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.SHRUG);
-    expect(level.clearedMasks).to.have.length(0);
-  });
-
-  it('ActionBashSystem stops on steel under mask', function() {
-    const level = new StubLevel();
-    level.steelUnder = true;
-    const sys = new TestBashSystem(0, 0);
-    const lem = new StubLemming();
-    lem.frameIndex = 2; // ->3
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.SHRUG);
-    expect(level.clearedMasks).to.have.length(0);
-  });
-
-  it('ActionBashSystem finishes when no horizontal space found', function() {
-    const level = new StubLevel();
-    const sys = new ActionBashSystem(stubSprites, stubMasks());
-    const lem = new StubLemming();
-    lem.frameIndex = 4; // ->5
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
-  });
-
-  it('ActionBashSystem helper functions inspect ground', function() {
-    const level = new StubLevel();
-    const sys = new ActionBashSystem(stubSprites, stubMasks());
-    const gm = level.getGroundMaskLayer();
-
-    expect(sys.findGapDelta(gm, 0, 0)).to.equal(3);
-    level.ground.add(level.key(0, 2));
-    expect(sys.findGapDelta(gm, 0, 0)).to.equal(2);
-    level.ground.add(level.key(0, 0));
-    level.ground.delete(level.key(0, 2));
-    expect(sys.findGapDelta(gm, 0, 0)).to.equal(0);
-
-    level.ground.clear();
-    expect(sys.findHorizontalSpace(gm, 0, 0, true)).to.equal(4);
-    level.ground.add(level.key(1, 0));
-    expect(sys.findHorizontalSpace(gm, 0, 0, true)).to.equal(1);
-    level.ground.clear();
-    level.ground.add(level.key(-3, 0));
-    expect(sys.findHorizontalSpace(gm, 0, 0, false)).to.equal(3);
-  });
-
-  it('ActionBuildSystem turns around when hitting wall', function() {
-    const level = new StubLevel();
-    const sys = new ActionBuildSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.frameIndex = 15; // ->0
-    level.ground.add(level.key(lem.x + 1, lem.y - 2));
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
-    expect(lem.lookRight).to.equal(false);
-  });
-
-  it('ActionBuildSystem walks when roof blocks path', function() {
-    const level = new StubLevel();
-    const sys = new ActionBuildSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.frameIndex = 15; // ->0
-    level.ground.add(level.key(4, -10));
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
-  });
-
-  it('ActionBuildSystem builds twelve bricks then shrugs', function() {
-    const level = new StubLevel();
-    const sys = new ActionBuildSystem(stubSprites);
-    const lem = new StubLemming();
-
-    for (let i = 0; i < 11; i++) {
-      lem.frameIndex = 8; // ->9 lay brick
-      sys.process(level, lem);
-      lem.frameIndex = 15; // ->0 step up
-      sys.process(level, lem);
-    }
-
-    expect(lem.state).to.equal(11);
-    expect(lem.x).to.equal(22);
-    expect(lem.y).to.equal(-11);
-
-    lem.frameIndex = 8; // ->9 lay final brick
-    sys.process(level, lem);
-    lem.frameIndex = 15; // ->0 last step
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.SHRUG);
-    expect(level.setGroundCalls).to.have.length(72);
-    expect(lem.x).to.equal(24);
-    expect(lem.y).to.equal(-12);
-  });
-
-  it('ActionBuildSystem turns around mid-step when ground blocks path', function() {
-    const level = new StubLevel();
-    const sys = new ActionBuildSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.frameIndex = 8; // lay first brick
-    sys.process(level, lem);
-    lem.frameIndex = 15; // stepping forward
-    level.ground.add(level.key(lem.x + 1, lem.y - 2));
-    const res = sys.process(level, lem);
-    expect(res).to.equal(Lemmings.LemmingStateType.WALKING);
-    expect(lem.lookRight).to.equal(false);
-    expect(lem.x).to.equal(1);
-    expect(lem.y).to.equal(-1);
-    expect(lem.state).to.equal(0);
-  });
-
-  it('ActionBuildSystem turns around when ceiling blocks next step', function() {
-    const level = new StubLevel();
-    const sys = new ActionBuildSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.frameIndex = 8; // lay brick
-    sys.process(level, lem);
-    lem.frameIndex = 15; // step forward
-    level.ground.add(level.key(4, -10));
-    const result = sys.process(level, lem);
-    expect(result).to.equal(Lemmings.LemmingStateType.WALKING);
-    expect(lem.lookRight).to.equal(false);
-    expect(lem.x).to.equal(2);
-    expect(lem.y).to.equal(-1);
-    expect(lem.state).to.equal(1);
-  });
-
-  it('ActionBuildSystem lays bricks facing left', function() {
-    const level = new StubLevel();
-    const sys = new ActionBuildSystem(stubSprites);
-    const lem = new StubLemming(10, 0);
-    lem.lookRight = false;
-    lem.frameIndex = 8; // ->9 brick
-    sys.process(level, lem);
-    expect(level.setGroundCalls).to.eql([
-      '6,-1','7,-1','8,-1','9,-1','10,-1','11,-1'
-    ]);
-  });
-
-  it('ActionBuildSystem steps forward without obstacles', function() {
-    const level = new StubLevel();
-    const sys = new ActionBuildSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.frameIndex = 15; // ->0 step
-    const result = sys.process(level, lem);
-    expect(result).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
-    expect(lem.x).to.equal(2);
-    expect(lem.y).to.equal(-1);
-    expect(lem.state).to.equal(1);
-    expect(lem.lookRight).to.equal(true);
-  });
-
-  it('ActionClimbSystem continues with ceiling present', function() {
-    const level = new StubLevel();
-    const sys = new ActionClimbSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.frameIndex = 2; // ->3
-    level.ground.add(level.key(lem.x, lem.y - 10));
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
-    expect(lem.y).to.equal(0);
-  });
-
-  it('ActionDiggSystem shrugs on steel', function() {
-    const level = new StubLevel();
-    level.steelGround = () => true;
-    const sys = new ActionDiggSystem(stubSprites);
-    const lem = new StubLemming();
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.SHRUG);
-  });
-
-  it('ActionDiggSystem digs rows while inside level', function() {
-    const level = new StubLevel();
-    const sys = new ActionDiggSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.state = 1;
-    lem.frameIndex = 7; // ->8
-    let calls = 0;
-    sys.digRow = () => { calls++; return true; };
-    level.isOutOfLevel = () => false;
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
-    expect(lem.y).to.equal(1);
-    expect(calls).to.equal(1);
-  });
-
-  it('ActionDiggSystem falls when digging out of level', function() {
-    const level = new StubLevel();
-    const sys = new ActionDiggSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.state = 1;
-    lem.y = 49;
-    lem.frameIndex = 7; // ->8
-    level.isOutOfLevel = y => y >= 50;
-    sys.digRow = () => true;
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.FALLING);
-  });
-
-  it('ActionDiggSystem falls when dig row removes nothing', function() {
-    const level = new StubLevel();
-    const sys = new ActionDiggSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.state = 1;
-    lem.frameIndex = 7; // ->8
-    level.isOutOfLevel = () => false;
-    sys.digRow = () => false;
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.FALLING);
-  });
-
-  it('ActionDiggSystem cycles animation frames', function() {
-    const level = new StubLevel();
-    const sys = new ActionDiggSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.state = 1;
-    level.isOutOfLevel = () => false;
-    let calls = 0;
-    sys.digRow = () => { calls++; return true; };
-    for (let i = 0; i < 16; i++) {
-      sys.process(level, lem);
-    }
-    expect(lem.frameIndex).to.equal(0);
-    expect(lem.y).to.equal(2);
-    expect(calls).to.equal(2);
-  });
-
-  it('ActionDiggSystem shrugs when steel appears below', function() {
-    const level = new StubLevel();
-    const sys = new ActionDiggSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.state = 1;
-    lem.frameIndex = 7; // ->8
-    level.isOutOfLevel = () => false;
-    sys.digRow = () => true;
-    level.steelGround = () => false;
-    sys.process(level, lem); // dig first row
-    level.steelGround = k => k === level.key(lem.x, lem.y);
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.SHRUG);
-  });
-
-  it('digRow returns false when no ground present', function() {
-    const level = new StubLevel();
-    const sys = new ActionDiggSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.x = 10;
-    const res = sys.digRow(level, lem, 0);
-    expect(res).to.equal(false);
-    expect(level.clearedPoints).to.have.length(0);
-  });
-
-  it('digRow clears boundary ground points', function() {
-    const level = new StubLevel();
-    const sys = new ActionDiggSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.x = 10;
-    level.setGroundAt(lem.x - 4, 0);
-    level.setGroundAt(lem.x + 4, 0);
-    const res = sys.digRow(level, lem, 0);
-    expect(res).to.equal(true);
-    expect(level.clearedPoints).to.have.members([
-      level.key(lem.x - 4, 0),
-      level.key(lem.x + 4, 0)
-    ]);
-  });
-
-  it('ActionDrowningSystem moves when no wall', function() {
-    const level = new StubLevel();
-    const sys = new ActionDrowningSystem(stubSprites);
-    const lem = new StubLemming();
-    const x0 = lem.x;
-    sys.process(level, lem);
-    expect(lem.x).to.equal(x0 + 1);
-  });
-
-  it('ActionExitingSystem waits before exit', function() {
-    const gvc = new StubGVC();
-    const sys = new ActionExitingSystem(stubSprites, gvc);
-    const lem = new StubLemming();
-    expect(sys.process(new StubLevel(), lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
-    expect(gvc.count).to.equal(0);
-  });
-
-  it('ActionExplodingSystem clears mask on first frame', function() {
-    const tm = new StubTriggerManager();
-    const level = new StubLevel();
-    const sys = new ActionExplodingSystem(stubSprites, stubMasks(), tm, { draw() {} });
-    const lem = new StubLemming();
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
-    expect(tm.removed[0]).to.equal(lem);
-    expect(level.clearedMasks).to.have.length(1);
-  });
-
-  it('ActionFallSystem keeps falling without ground', function() {
-    const level = new StubLevel();
-    const sys = new ActionFallSystem(stubSprites);
-    const lem = new StubLemming();
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
-    expect(lem.y).to.equal(3);
-    expect(lem.state).to.equal(3);
-  });
-
-  it('ActionFallSystem accumulates state over time', function() {
-    const level = new StubLevel();
-    const sys = new ActionFallSystem(stubSprites);
-    const lem = new StubLemming();
-    sys.process(level, lem); // state ->3
-    const result = sys.process(level, lem); // state ->6
-    expect(result).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
-    expect(lem.y).to.equal(6);
-    expect(lem.state).to.equal(6);
-  });
-
-  it('ActionFallSystem floats once fall distance exceeds 16 with parachute', function() {
-    const level = new StubLevel();
-    const sys = new ActionFallSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.hasParachute = true;
-    let state;
-    for (let i = 0; i < 7; i++) {
-      state = sys.process(level, lem);
-    }
-    expect(state).to.equal(Lemmings.LemmingStateType.FLOATING);
-    expect(lem.state).to.be.above(16);
-  });
-
-  it('ActionFallSystem lands with parachute when ground one step below', function() {
-    const level = new StubLevel();
-    const sys = new ActionFallSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.hasParachute = true;
-    level.ground.add(level.key(lem.x, lem.y + 1));
-    const state = sys.process(level, lem);
-    expect(state).to.equal(Lemmings.LemmingStateType.WALKING);
-    expect(lem.y).to.equal(1);
-    expect(lem.state).to.equal(0);
-  });
-
-  it('ActionFallSystem lands with parachute when ground two steps below', function() {
-    const level = new StubLevel();
-    const sys = new ActionFallSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.hasParachute = true;
-    level.ground.add(level.key(lem.x, lem.y + 2));
-    const state = sys.process(level, lem);
-    expect(state).to.equal(Lemmings.LemmingStateType.WALKING);
-    expect(lem.y).to.equal(2);
-    expect(lem.state).to.equal(0);
-  });
-
-  it('ActionFallSystem walks or splats depending on fall distance', function() {
-    const level = new StubLevel();
-    const sys = new ActionFallSystem(stubSprites);
-    const lem = new StubLemming();
-    level.ground.add(level.key(lem.x, lem.y));
-    lem.state = Lemmings.Lemming.LEM_MAX_FALLING;
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
-
-    level.ground.add(level.key(lem.x, lem.y));
-    lem.state = Lemmings.Lemming.LEM_MAX_FALLING + 1;
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.SPLATTING);
-  });
-
-  it('ActionFloatingSystem lands when ground below', function() {
-    const sys = new ActionFloatingSystem(stubSprites);
-    const level = new StubLevel();
-    const lem = new StubLemming();
-    level.ground.add(level.key(lem.x, lem.y + 2));
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
-    expect(lem.y).to.equal(2);
-  });
-
-  it('ActionFryingSystem moves then turns around', function() {
-    const level = new StubLevel();
-    const sys = new ActionFryingSystem(stubSprites);
-    const lem = new StubLemming();
-    const x0 = lem.x;
-    sys.process(level, lem);
-    expect(lem.x).to.equal(x0 + 1);
-    level.ground.add(level.key(lem.x + 8, lem.y));
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
-    expect(lem.lookRight).to.equal(false);
-  });
-
-  it('ActionHoistSystem pauses mid animation', function() {
-    const sys = new ActionHoistSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.frameIndex = 5; // ->6
-    expect(sys.process(new StubLevel(), lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
-    expect(lem.y).to.equal(0);
-  });
-
-  it('ActionJumpSystem lands immediately without ceiling', function() {
-    const level = new StubLevel();
-    const sys = new ActionJumpSystem(stubSprites);
-    const lem = new StubLemming();
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
-  });
-
-  it('ActionJumpSystem ends after reaching max height', function() {
-    const level = new StubLevel();
-    const sys = new ActionJumpSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.state = 2;
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
-  });
-
-  it('ActionJumpSystem climbs two cells then ends', function() {
-    const level = new StubLevel();
-    level.ground.add(level.key(1, -1));
-    level.ground.add(level.key(1, -2));
-    const sys = new ActionJumpSystem(stubSprites);
-    const lem = new StubLemming();
-    const res = sys.process(level, lem);
-    expect(res).to.equal(Lemmings.LemmingStateType.WALKING);
-    expect(lem.y).to.equal(-2);
-    expect(lem.state).to.equal(0);
-  });
-
-  it('ActionJumpSystem ends when no ceiling remains', function() {
-    const level = new StubLevel();
-    level.ground.add(level.key(1, -1));
-    const sys = new ActionJumpSystem(stubSprites);
-    const lem = new StubLemming();
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
-    expect(lem.y).to.equal(-1);
-  });
-
-  it('ActionJumpSystem enforces LEM_MIN_Y', function() {
-    const level = new StubLevel();
-    const sys = new ActionJumpSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.y = -6;
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
-    expect(lem.y).to.equal(Lemmings.Lemming.LEM_MIN_Y);
-  });
-
-  it('ActionJumpSystem resets state after jump', function() {
-    const level = new StubLevel();
-    level.ground.add(level.key(1, -1));
-    const sys = new ActionJumpSystem(stubSprites);
-    const lem = new StubLemming();
-    sys.process(level, lem);
-    expect(lem.state).to.equal(0);
-  });
-
-  it('ActionJumpSystem triggerLemAction refuses to activate', function() {
-    const sys = new ActionJumpSystem(stubSprites);
-    const lem = new StubLemming();
-    expect(sys.triggerLemAction(lem)).to.equal(false);
-  });
-
-  it('ActionJumpSystem draw delegates to base system', function() {
-    const sys = new ActionJumpSystem(stubSprites);
-    const lem = new StubLemming();
-    let called = false;
-    const display = { drawFrame() { called = true; } };
-    sys.draw(display, lem);
-    expect(called).to.equal(true);
-  });
-
-  it('ActionJumpSystem initializes state and keeps jumping', function() {
-    const level = new StubLevel();
-    level.hasGroundAt = () => true;
-    const sys = new ActionJumpSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.state = -1;
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.JUMPING);
-    expect(lem.state).to.equal(1);
-    expect(lem.y).to.equal(-2);
-  });
-
-  it('ActionJumpSystem initializes null state then ends', function() {
-    const level = new StubLevel();
-    level.ground.add(level.key(1, -1));
-    const sys = new ActionJumpSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.state = null;
-    const res = sys.process(level, lem);
-    expect(res).to.equal(Lemmings.LemmingStateType.WALKING);
-    expect(lem.state).to.equal(0);
-    expect(lem.y).to.equal(-1);
-  });
-
-  it('ActionMineSystem shrugs on steel ground', function() {
-    const level = new StubLevel();
-    level.steelUnder = true;
-    const sys = new ActionMineSystem(stubSprites, stubMasks());
-    const lem = new StubLemming();
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.SHRUG);
-  });
-
-  it('ActionMineSystem shrugs when arrow under mask', function() {
-    const level = new StubLevel();
-    const sys = new ActionMineSystem(stubSprites, stubMasks());
-    level.arrowUnder = true;
-    const lem = new StubLemming();
-    lem.frameIndex = 1; // ->2
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.SHRUG);
-    expect(level.clearedMasks).to.have.length(0);
-  });
-
-  it('ActionOhNoSystem falls if unsupported', function() {
-    const level = new StubLevel();
-    const sys = new ActionOhNoSystem(stubSprites);
-    const lem = new StubLemming();
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
-    expect(lem.y).to.equal(1);
-  });
-
-  it('ActionShrugSystem waits before walking', function() {
-    const sys = new ActionShrugSystem(stubSprites);
-    const lem = new StubLemming();
-    expect(sys.process(new StubLevel(), lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
-    expect(lem.frameIndex).to.equal(1);
-  });
-
-  it('ActionSplatterSystem disables then exits', function() {
-    const sys = new ActionSplatterSystem(stubSprites);
-    const lem = new StubLemming();
-    expect(sys.process(new StubLevel(), lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
-    expect(lem.disabled).to.equal(true);
-  });
-
-  it('ActionWalkSystem turns when blocked and cannot climb', function() {
-    const sys = new ActionWalkSystem(stubSprites);
-    const level = new StubLevel();
-    level.stepHeight = 8;
-    const lem = new StubLemming();
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
-    expect(lem.lookRight).to.equal(false);
-  });
-
-  it('ActionWalkSystem steps up small ledge', function() {
-    const sys = new ActionWalkSystem(stubSprites);
-    const level = new StubLevel();
-    level.stepHeight = 2;
-    const lem = new StubLemming();
-    sys.process(level, lem);
-    expect(lem.y).to.equal(-1);
-  });
-
-  it('getColumnStepHeight counts ground from bottom', function() {
-    const level = new StubLevel();
-    const mask = level.getGroundMaskLayer();
-    level.ground.add(level.key(0, 3));
-    expect(mask.getColumnStepHeight(0, 0, 4)).to.equal(1);
-    level.ground.add(level.key(0, 0));
-    level.ground.add(level.key(0, 1));
-    level.ground.add(level.key(0, 2));
-    expect(mask.getColumnStepHeight(0, 0, 4)).to.equal(4);
-    level.ground.clear();
-    expect(mask.getColumnStepHeight(0, 0, 4)).to.equal(0);
-  });
-
-  it('getColumnGapDepth counts gap from top', function() {
-    const level = new StubLevel();
-    const mask = level.getGroundMaskLayer();
-    level.ground.add(level.key(0, 2));
-    expect(mask.getColumnGapDepth(0, 0, 3)).to.equal(3);
-    level.ground.clear();
-    expect(mask.getColumnGapDepth(0, 0, 3)).to.equal(4);
-  });
-
-  it('ActionWalkSystem clamps position to LEM_MIN_Y', function() {
-    const sys = new ActionWalkSystem(stubSprites);
-    const level = new StubLevel();
-    level.stepHeight = 2;
-    const lem = new StubLemming();
-    lem.y = Lemmings.Lemming.LEM_MIN_Y;
-    sys.process(level, lem);
-    expect(lem.y).to.equal(Lemmings.Lemming.LEM_MIN_Y);
-  });
-
-  it('ActionWalkSystem walks over shallow gaps', function() {
-    const sys = new ActionWalkSystem(stubSprites);
-    const level = new StubLevel();
-    level.stepHeight = 0;
-    level.gapDepth = 1;
-    const lem = new StubLemming();
-    const res = sys.process(level, lem);
-    expect(res).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
-    expect(lem.y).to.equal(1);
-  });
-});
-
-describe('Action systems events and draws', function() {
-  it('ActionBaseSystem emitters fire for bashing and digging steel', function() {
-    const calls = [];
-    const restore = useSoundBus(calls);
-
-    const bashLevel = new StubLevel();
-    bashLevel.steelUnder = true;
-    const bash = new ActionBashSystem(stubSprites, stubMasks());
-    const bashLem = new StubLemming();
-    bashLem.id = 1;
-    bashLem.frameIndex = 2; // -> state 3
-    expect(bash.process(bashLevel, bashLem)).to.equal(Lemmings.LemmingStateType.SHRUG);
-
-    const digLevel = new StubLevel();
-    digLevel.steelGround = () => true;
-    const dig = new ActionDiggSystem(stubSprites);
-    const digLem = new StubLemming();
-    digLem.id = 2;
-    expect(dig.process(digLevel, digLem)).to.equal(Lemmings.LemmingStateType.SHRUG);
-
-    restore();
-    expect(calls[0].type).to.equal(SoundEventTypes.STEEL_HIT);
-    expect(calls[1].type).to.equal(SoundEventTypes.STEEL_HIT);
-  });
-
-  it('emits terrain events with intensity for dig, bash, and mine', function() {
-    const calls = [];
-    const restore = useSoundBus(calls);
-    const digLevel = new StubLevel();
-    const dig = new ActionDiggSystem(stubSprites);
-    const digLem = new StubLemming(10, 5);
-    digLem.id = 9;
-    for (let x = digLem.x - 4; x <= digLem.x; x++) {
-      digLevel.ground.add(digLevel.key(x, 3));
-    }
-    dig.digRow(digLevel, digLem, 3);
-
-    const mask = { offsetX: 0, offsetY: 0, width: 3, height: 1, at() { return false; } };
-    const masks = { GetMask() { return { GetMask() { return mask; } }; } };
-
-    const bashLevel = new StubLevel();
-    bashLevel.clearCount = 3;
-    const bash = new ActionBashSystem(stubSprites, masks);
-    const bashLem = new StubLemming();
-    bashLem.id = 10;
-    bashLem.frameIndex = 2; // -> state 3
-    bash.process(bashLevel, bashLem);
-
-    const mineLevel = new StubLevel();
-    mineLevel.clearCount = 2;
-    const mine = new ActionMineSystem(stubSprites, masks);
-    const mineLem = new StubLemming();
-    mineLem.id = 11;
-    mine.process(mineLevel, mineLem);
-
-    restore();
-    const digEvent = calls.find(call => call.type === SoundEventTypes.LEMMING_DIG);
-    const bashEvent = calls.find(call => call.type === SoundEventTypes.LEMMING_BASH);
-    const mineEvent = calls.find(call => call.type === SoundEventTypes.LEMMING_MINE);
-    expect(digEvent).to.be.ok;
-    expect(bashEvent).to.be.ok;
-    expect(mineEvent).to.be.ok;
-    expect(digEvent.data.intensity).to.be.greaterThan(1);
-    expect(bashEvent.data.intensity).to.be.greaterThan(1);
-    expect(mineEvent.data.intensity).to.be.greaterThan(1);
-  });
-
-  it('handles missing clear count with null bash masks', function() {
-    const restore = useSoundBus([]);
-    const level = {
-      getGroundMaskLayer() { return { hasGroundAt() { return false; } }; },
-      hasSteelUnderMask() { return false; },
-      hasArrowUnderMask() { return false; },
-      clearGroundWithMask(mask) { this.cleared = mask; }
-    };
-    const nullMasks = {
-      GetMask() { return { GetMask() { return null; } }; }
-    };
-    const sys = new ActionBashSystem(stubSprites, nullMasks);
-    const lem = new StubLemming();
-    lem.frameIndex = 1; // -> state 2
-    sys.process(level, lem);
-    restore();
-    expect(level.cleared).to.equal(null);
-  });
-
-  it('handles missing clear count with null mine masks', function() {
-    const restore = useSoundBus([]);
-    const level = {
-      hasSteelUnderMask() { return false; },
-      hasArrowUnderMask() { return false; },
-      clearGroundWithMask(mask) { this.cleared = mask; }
-    };
-    const nullMasks = {
-      GetMask() { return { GetMask() { return null; } }; }
-    };
-    const sys = new ActionMineSystem(stubSprites, nullMasks);
-    const lem = new StubLemming();
-    lem.frameIndex = 0; // -> state 1
-    sys.process(level, lem);
-    restore();
-    expect(level.cleared).to.equal(null);
-  });
-
-  it('ActionBashSystem exits to walking when solid ends', function() {
-    const level = new StubLevel();
-    const sys = new ActionBashSystem(stubSprites, stubMasks());
-    const lem = new StubLemming();
-    lem.frameIndex = 4; // -> state 5
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
-  });
-
-  it('ActionBuildSystem emits step and warning sounds', function() {
-    const calls = [];
-    const restore = useSoundBus(calls);
-    const level = new StubLevel();
-    const sys = new ActionBuildSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.id = 3;
-    lem.frameIndex = 8;
-    lem.state = 9;
-
-    sys.process(level, lem);
-    restore();
-
-    expect(calls.map(c => c.type)).to.eql([
-      SoundEventTypes.BUILDER_STEP,
-      SoundEventTypes.BUILDER_WARNING
-    ]);
-    expect(calls.map(c => c.sfxId)).to.eql([
-      SoundEffectIds.BUILDER_STEP,
-      SoundEffectIds.BUILDER_WARNING
-    ]);
-  });
-
-  it('ActionBuildSystem handles frame-zero movement checks', function() {
-    const level = new StubLevel();
-    const sys = new ActionBuildSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.frameIndex = 15; // -> 0
-    level.ground.add(level.key(1, -2));
-
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
-    expect(lem.lookRight).to.equal(false);
-
-    const lem2 = new StubLemming();
-    lem2.frameIndex = 15;
-    level.ground.clear();
-    level.ground.add(level.key(4, -10));
-    expect(sys.process(level, lem2)).to.equal(Lemmings.LemmingStateType.WALKING);
-    expect(lem2.lookRight).to.equal(false);
-  });
-
-  it('ActionCountdownSystem emits ohno when the timer hits zero', function() {
-    const calls = [];
-    const restore = useSoundBus(calls);
-    const sys = new ActionCountdownSystem(stubMasks());
-    const lem = new StubLemming();
-    lem.id = 4;
-    lem.countdown = 1;
-    lem.setCountDown = act => { lem.countdownAction = act; return true; };
-
-    expect(sys.process(new StubLevel(), lem)).to.equal(Lemmings.LemmingStateType.OHNO);
-    restore();
-
-    expect(calls[0].type).to.equal(SoundEventTypes.LEMMING_OHNO);
-    expect(calls[0].sfxId).to.equal(SoundEffectIds.OHNO);
-  });
-
-  it('ActionDrowningSystem and ExitingSystem emit sfx on entry', function() {
-    const calls = [];
-    const restore = useSoundBus(calls);
-
-    const drowning = new ActionDrowningSystem(stubSprites);
-    const drownLem = new StubLemming();
-    drownLem.id = 5;
-    drownLem.lastTriggerType = 'water';
-    drowning.process(new StubLevel(), drownLem);
-
-    const gvc = new StubGVC();
-    const exit = new ActionExitingSystem(stubSprites, gvc);
-    const exitLem = new StubLemming();
-    exitLem.id = 6;
-    exitLem.lastTriggerType = 'exit';
-    exit.process(new StubLevel(), exitLem);
-
-    restore();
-    expect(calls[0].type).to.equal(SoundEventTypes.LEMMING_DROWN);
-    expect(calls[1].type).to.equal(SoundEventTypes.LEMMING_EXIT);
-  });
-
-  it('ActionDrowningSystem moves when no ground is ahead', function() {
-    const sys = new ActionDrowningSystem(stubSprites);
-    const level = new StubLevel();
-    const lem = new StubLemming();
-    const x0 = lem.x;
-    sys.process(level, lem);
-    expect(lem.x).to.equal(x0 + 1);
-  });
-
-  it('ActionExplodingSystem emits and invalidates minimap', function() {
-    const calls = [];
-    const restore = useSoundBus(calls);
-    const mask = { offsetX: -2, offsetY: -3, width: 4, height: 5 };
-    const masks = { GetMask() { return { GetMask() { return mask; } }; } };
-    const triggerManager = { removed: [], removeByOwner(lem) { this.removed.push(lem); } };
-    const particleTable = { draw() {} };
-    const sys = new ActionExplodingSystem(stubSprites, masks, triggerManager, particleTable);
-    const level = { clearGroundWithMask() { return true; } };
-
-    const miniMap = {
-      invalidations: [],
-      deaths: [],
-      invalidateRegion(x, y, w, h) { this.invalidations.push({ x, y, w, h }); },
-      addDeath(x, y) { this.deaths.push({ x, y }); }
-    };
-    const manager = ensureMiniMap();
-    const prevMiniMap = manager.miniMap;
-    manager.miniMap = miniMap;
-
-    const lem = new StubLemming();
-    lem.id = 7;
-    sys.process(level, lem);
-
-    manager.miniMap = prevMiniMap;
-    restore();
-
-    expect(calls[0].type).to.equal(SoundEventTypes.LEMMING_EXPLODE);
-    expect(triggerManager.removed[0]).to.equal(lem);
-    expect(miniMap.invalidations[0]).to.eql({ x: -2, y: -3, w: 4, h: 5 });
-    expect(miniMap.deaths[0]).to.eql({ x: 0, y: 0 });
-  });
-
-  it('ActionFallSystem and FloatingSystem draw frames', function() {
-    const display = { frames: [], drawFrame(frame, x, y) { this.frames.push({ frame, x, y }); } };
-
-    const fall = new ActionFallSystem(stubSprites);
-    const fallLem = new StubLemming();
-    fall.draw(display, fallLem);
-
-    const floatSys = new ActionFloatingSystem(stubSprites);
-    const floatLem = new StubLemming();
-    floatSys.draw(display, floatLem);
-
-    expect(display.frames.length).to.equal(2);
-  });
-
-  it('ActionFryingSystem reports deaths to minimap', function() {
-    const sys = new ActionFryingSystem(stubSprites);
-    const level = new StubLevel();
-    const lem = new StubLemming();
-    lem.frameIndex = 12;
-
-    const miniMap = { deaths: [], addDeath(x, y) { this.deaths.push({ x, y }); } };
-    const manager = ensureMiniMap();
-    const prevMiniMap = manager.miniMap;
-    manager.miniMap = miniMap;
-
-    sys.process(level, lem);
-
-    manager.miniMap = prevMiniMap;
-    expect(miniMap.deaths[0]).to.eql({ x: 0, y: 0 });
-  });
-
-  it('ActionFryingSystem moves when no ground is ahead', function() {
-    const sys = new ActionFryingSystem(stubSprites);
-    const level = new StubLevel();
-    const lem = new StubLemming();
-    const x0 = lem.x;
-    sys.process(level, lem);
-    expect(lem.x).to.equal(x0 + 1);
-  });
-
-  it('ActionHoistSystem handles invalid frameIndex values', function() {
-    const sys = new ActionHoistSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.frameIndex = NaN;
-    expect(sys.process(new StubLevel(), lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
-  });
-
-  it('ActionMineSystem emits steel hit sound', function() {
-    const calls = [];
-    const restore = useSoundBus(calls);
-    const level = new StubLevel();
-    level.steelUnder = true;
-    const sys = new ActionMineSystem(stubSprites, stubMasks());
-    const lem = new StubLemming();
-    lem.id = 8;
-    sys.process(level, lem);
-    restore();
-
-    expect(calls[0].type).to.equal(SoundEventTypes.STEEL_HIT);
-    expect(calls[0].sfxId).to.equal(SoundEffectIds.STEEL_HIT);
-  });
-
-  it('ActionMineSystem keeps mining when ground remains', function() {
-    const level = new StubLevel();
-    const sys = new ActionMineSystem(stubSprites, stubMasks());
-    const lem = new StubLemming();
-    lem.frameIndex = 14; // -> 15
-    level.ground.add(level.key(1, 0));
-    const res = sys.process(level, lem);
-    expect(res).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
-    expect(lem.x).to.equal(1);
-  });
-
-  it('ActionOhNoSystem and SplatterSystem trigger handlers', function() {
-    const calls = [];
-    const restore = useSoundBus(calls);
-
-    const ohNo = new ActionOhNoSystem(stubSprites);
-    const ohNoLem = new StubLemming();
-    ohNoLem.frameIndex = 15;
-    expect(ohNo.triggerLemAction(ohNoLem)).to.equal(false);
-
-    const miniMap = { deaths: [], addDeath(x, y) { this.deaths.push({ x, y }); } };
-    const manager = ensureMiniMap();
-    const prevMiniMap = manager.miniMap;
-    manager.miniMap = miniMap;
-
-    ohNo.draw({ drawFrame() {} }, ohNoLem);
-
-    const splatter = new ActionSplatterSystem(stubSprites);
-    const splatLem = new StubLemming();
-    splatLem.id = 9;
-    splatLem.frameIndex = 15;
-    splatLem.lastTriggerType = null;
-    expect(splatter.triggerLemAction(splatLem)).to.equal(false);
-    splatter.draw({ drawFrame() {} }, splatLem);
-    splatLem.frameIndex = 0;
-    splatter.process(new StubLevel(), splatLem);
-
-    manager.miniMap = prevMiniMap;
-    restore();
-
-    expect(miniMap.deaths.length).to.equal(2);
-    expect(calls[0].type).to.equal(SoundEventTypes.LEMMING_SPLAT);
-  });
-
-  it('ActionWalkSystem triggerLemAction returns false', function() {
-    const sys = new ActionWalkSystem(stubSprites);
-    const lem = new StubLemming();
-    expect(sys.triggerLemAction(lem)).to.equal(false);
-  });
-
-  it('ActionWalkSystem advances when the path is clear', function() {
-    const sys = new ActionWalkSystem(stubSprites);
-    const level = new StubLevel();
-    level.stepHeight = 0;
-    level.gapDepth = 1;
-    const lem = new StubLemming();
-    const x0 = lem.x;
-    sys.process(level, lem);
-    expect(lem.x).to.equal(x0 + 1);
-  });
-
-  it('ActionDrowningSystem triggerLemAction returns false', function() {
-    const sys = new ActionDrowningSystem(stubSprites);
-    const lem = new StubLemming();
-    expect(sys.triggerLemAction(lem)).to.equal(false);
-  });
-});
-
-describe('Action systems branch coverage', function() {
-  it('ActionBashSystem handles steel without sound bus', function() {
-    const level = new StubLevel();
-    level.steelUnder = true;
-    const sys = new ActionBashSystem(stubSprites, stubMasks());
-    const lem = new StubLemming();
-    lem.frameIndex = 2;
-    const restore = withoutSoundBus();
-    try {
-      expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.SHRUG);
-    } finally {
-      restore();
-    }
-  });
-
-  it('ActionBashSystem checks left edge when bashing', function() {
-    const level = new StubLevel();
-    const sys = new TestBashSystem(0, 4);
-    const lem = new StubLemming();
-    lem.lookRight = false;
-    lem.frameIndex = 4;
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
-  });
-
-  it('ActionBuildSystem skips missing sound bus', function() {
-    const level = new StubLevel();
-    const sys = new ActionBuildSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.frameIndex = 8;
-    lem.state = 9;
-    const restore = withoutSoundBus();
-    try {
-      expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
-    } finally {
-      restore();
-    }
-  });
-
-  it('ActionBuildSystem moves left when blocked', function() {
-    const level = new StubLevel();
-    const sys = new ActionBuildSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.lookRight = false;
-    lem.frameIndex = 15;
-    level.ground.add(level.key(-1, -2));
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
-    expect(lem.x).to.equal(-1);
-  });
-
-  it('ActionBuildSystem checks roof behind when building backwards', function() {
-    const level = new StubLevel();
-    const sys = new ActionBuildSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.lookRight = false;
-    lem.frameIndex = 15;
-    lem.state = 10;
-    level.ground.add(level.key(-4, -10));
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
-    expect(lem.lookRight).to.equal(true);
-  });
-
-  it('ActionClimbSystem flips from the left wall', function() {
-    const level = new StubLevel();
-    const sys = new ActionClimbSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.lookRight = false;
-    lem.frameIndex = 4;
-    level.ground.add(level.key(lem.x + 1, lem.y - 9));
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.FALLING);
-    expect(lem.lookRight).to.equal(true);
-    expect(lem.x).to.equal(2);
-  });
-
-  it('ActionCountdownSystem handles no sound bus at zero', function() {
-    const sys = new ActionCountdownSystem(stubMasks());
-    const lem = new StubLemming();
-    lem.countdown = 1;
-    lem.setCountDown = act => { lem.countdownAction = act; return true; };
-    const restore = withoutSoundBus();
-    try {
-      expect(sys.process(new StubLevel(), lem)).to.equal(Lemmings.LemmingStateType.OHNO);
-    } finally {
-      restore();
-    }
-  });
-
-  it('ActionDiggSystem shrugs on steel without sound bus', function() {
-    const sys = new ActionDiggSystem(stubSprites);
-    const level = new StubLevel();
-    level.steelGround = () => true;
-    const lem = new StubLemming();
-    const restore = withoutSoundBus();
-    try {
-      expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.SHRUG);
-    } finally {
-      restore();
-    }
-  });
-
-  it('ActionDrowningSystem moves left without sound bus', function() {
-    const sys = new ActionDrowningSystem(stubSprites);
-    const level = new StubLevel();
-    const lem = new StubLemming();
-    lem.lookRight = false;
-    const restore = withoutSoundBus();
-    try {
-      sys.process(level, lem);
-    } finally {
-      restore();
-    }
-    expect(lem.x).to.equal(-1);
-  });
-
-  it('ActionExitingSystem handles missing sound bus on entry', function() {
-    const gvc = new StubGVC();
-    const sys = new ActionExitingSystem(stubSprites, gvc);
-    const lem = new StubLemming();
-    const restore = withoutSoundBus();
-    try {
-      expect(sys.process(new StubLevel(), lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
-    } finally {
-      restore();
-    }
-    expect(gvc.count).to.equal(0);
-  });
-
-  it('ActionExplodingSystem handles missing sound bus and minimap', function() {
-    const triggerManager = { removed: [], removeByOwner(lem) { this.removed.push(lem); } };
-    const sys = new ActionExplodingSystem(stubSprites, stubMasks(), triggerManager, { draw() {} });
-    const level = { clearGroundWithMask() { return false; } };
-    const lem = new StubLemming();
-    const restoreSound = withoutSoundBus();
-    const restoreManager = withoutLemmingManager();
-    try {
-      sys.process(level, lem);
-    } finally {
-      restoreManager();
-      restoreSound();
-    }
-    expect(triggerManager.removed[0]).to.equal(lem);
-  });
-
-  it('ActionFryingSystem ignores missing minimap', function() {
-    const sys = new ActionFryingSystem(stubSprites);
-    const level = new StubLevel();
-    const lem = new StubLemming();
-    lem.frameIndex = 12;
-    const restore = withoutLemmingManager();
-    try {
-      sys.process(level, lem);
-    } finally {
-      restore();
-    }
-    expect(lem.frameIndex).to.equal(13);
-  });
-
-  it('ActionFryingSystem moves left when no ground', function() {
-    const sys = new ActionFryingSystem(stubSprites);
-    const level = new StubLevel();
-    const lem = new StubLemming();
-    lem.lookRight = false;
-    sys.process(level, lem);
-    expect(lem.x).to.equal(-1);
-  });
-
-  it('ActionJumpSystem moves left when jumping', function() {
-    const level = new StubLevel();
-    const sys = new ActionJumpSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.lookRight = false;
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.WALKING);
-    expect(lem.x).to.equal(-1);
-  });
-
-  it('ActionMineSystem shrugs on steel without sound bus', function() {
-    const level = new StubLevel();
-    level.steelUnder = true;
-    const sys = new ActionMineSystem(stubSprites, stubMasks());
-    const lem = new StubLemming();
-    const restore = withoutSoundBus();
-    try {
-      expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.SHRUG);
-    } finally {
-      restore();
-    }
-  });
-
-  it('ActionMineSystem moves left when mining', function() {
-    const level = new StubLevel();
-    const sys = new ActionMineSystem(stubSprites, stubMasks());
-    const lem = new StubLemming();
-    lem.lookRight = false;
-    lem.frameIndex = 14;
-    level.ground.add(level.key(-1, 0));
-    expect(sys.process(level, lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
-    expect(lem.x).to.equal(-1);
-  });
-
-  it('ActionSplatterSystem skips sound bus when missing', function() {
-    const sys = new ActionSplatterSystem(stubSprites);
-    const lem = new StubLemming();
-    lem.frameIndex = 0;
-    const restore = withoutSoundBus();
-    try {
-      expect(sys.process(new StubLevel(), lem)).to.equal(Lemmings.LemmingStateType.NO_STATE_TYPE);
-    } finally {
-      restore();
-    }
-  });
-
-  it('ActionWalkSystem moves left when walking', function() {
-    const sys = new ActionWalkSystem(stubSprites);
-    const level = new StubLevel();
-    level.stepHeight = 0;
-    level.gapDepth = 1;
-    const lem = new StubLemming();
-    lem.lookRight = false;
-    sys.process(level, lem);
-    expect(lem.x).to.equal(-1);
-  });
-});
diff --git a/test/analytics.test.js b/test/analytics.test.js
new file mode 100644
index 00000000..09723515
--- /dev/null
+++ b/test/analytics.test.js
@@ -0,0 +1,176 @@
+import { expect } from 'chai';
+import {
+  ANALYTICS_EVENT_TYPES,
+  analyticsStorageKeys,
+  createAnalyticsService
+} from '../js/app/analytics.js';
+
+const createStorage = () => {
+  const map = new Map();
+  return {
+    getItem(key) {
+      return map.has(key) ? map.get(key) : null;
+    },
+    setItem(key, value) {
+      map.set(key, String(value));
+    },
+    removeItem(key) {
+      map.delete(key);
+    }
+  };
+};
+
+const createLocation = (search = '') => ({
+  search,
+  pathname: '/index.html',
+  protocol: 'https:',
+  hostname: 'example.com'
+});
+
+describe('analytics service', function () {
+  it('defaults to disabled tracking until consent is granted', function () {
+    const storage = createStorage();
+    const analytics = createAnalyticsService({
+      location: createLocation(''),
+      localStorage: storage,
+      profile: 'classic',
+      surface: 'game',
+      now: () => 100
+    });
+
+    expect(analytics.getStatus().enabled).to.equal(false);
+    expect(analytics.track(ANALYTICS_EVENT_TYPES.VISITOR_PAGE_VIEW, {})).to.equal(null);
+    expect(analytics.exportBuffer().events).to.have.lengthOf(0);
+  });
+
+  it('grants consent from query and records page-view events', function () {
+    const storage = createStorage();
+    const analytics = createAnalyticsService({
+      location: createLocation('?analytics=1'),
+      localStorage: storage,
+      profile: 'classic',
+      surface: 'game',
+      now: () => 1234
+    });
+
+    const event = analytics.trackPageView({ embedMode: true });
+    expect(event?.type).to.equal(ANALYTICS_EVENT_TYPES.VISITOR_PAGE_VIEW);
+    expect(event?.data?.embedMode).to.equal(true);
+    expect(analytics.getStatus().enabled).to.equal(true);
+    expect(storage.getItem(analyticsStorageKeys.consent)).to.equal('granted');
+  });
+
+  it('keeps a fixed-size ring buffer', function () {
+    const analytics = createAnalyticsService({
+      location: createLocation('?analytics=1'),
+      localStorage: createStorage(),
+      profile: 'classic',
+      surface: 'game',
+      maxEvents: 2,
+      now: () => 2000
+    });
+
+    analytics.track(ANALYTICS_EVENT_TYPES.GAMEPLAY_LEVEL_SELECT, {
+      control: 'gameType',
+      value: 1
+    });
+    analytics.track(ANALYTICS_EVENT_TYPES.GAMEPLAY_LEVEL_SELECT, {
+      control: 'levelGroup',
+      value: 2
+    });
+    analytics.track(ANALYTICS_EVENT_TYPES.GAMEPLAY_LEVEL_SELECT, {
+      control: 'levelIndex',
+      value: 3
+    });
+
+    const exported = analytics.exportBuffer();
+    expect(exported.events).to.have.lengthOf(2);
+    expect(exported.events[0].data.control).to.equal('levelGroup');
+    expect(exported.events[1].data.control).to.equal('levelIndex');
+  });
+
+  it('hard-disables tracking even when consent query is provided', function () {
+    const analytics = createAnalyticsService({
+      hardDisabled: true,
+      location: createLocation('?analytics=1'),
+      localStorage: createStorage(),
+      profile: 'classic',
+      surface: 'game'
+    });
+
+    expect(analytics.getStatus().enabled).to.equal(false);
+    expect(analytics.track(ANALYTICS_EVENT_TYPES.GAMEPLAY_MIDI_TOGGLE, { enabled: true })).to.equal(null);
+  });
+
+  it('supports explicit export/import for local-only telemetry workflows', function () {
+    const source = createAnalyticsService({
+      location: createLocation('?analytics=1'),
+      localStorage: createStorage(),
+      profile: 'classic',
+      surface: 'game',
+      now: () => 3000
+    });
+    source.track(ANALYTICS_EVENT_TYPES.GAMEPLAY_SAVED_LEVEL, { action: 'save' });
+    source.track(ANALYTICS_EVENT_TYPES.GAMEPLAY_SAVED_LEVEL, { action: 'export' });
+    const snapshot = source.exportBuffer();
+
+    const target = createAnalyticsService({
+      location: createLocation('?analytics=1'),
+      localStorage: createStorage(),
+      profile: 'classic',
+      surface: 'game',
+      now: () => 4000
+    });
+    target.track(ANALYTICS_EVENT_TYPES.GAMEPLAY_MIDI_TOGGLE, { enabled: true });
+
+    const imported = target.importBuffer(snapshot, { replace: true });
+    const exported = target.exportBuffer();
+    expect(imported.imported).to.equal(2);
+    expect(imported.total).to.equal(2);
+    expect(exported.events.map(event => event.data.action)).to.deep.equal(['save', 'export']);
+  });
+
+  it('keeps managed beacon off by default and sends only when explicitly enabled', function () {
+    const calls = [];
+    const navigatorRef = {
+      sendBeacon(url, body) {
+        calls.push({ url, body });
+        return true;
+      }
+    };
+    const endpoint = 'https://analytics.example.com/collect';
+
+    const defaultOff = createAnalyticsService({
+      location: createLocation('?analytics=1'),
+      navigator: navigatorRef,
+      managedBeaconEndpoint: endpoint,
+      localStorage: createStorage(),
+      profile: 'classic',
+      surface: 'game'
+    });
+    defaultOff.track(ANALYTICS_EVENT_TYPES.GAMEPLAY_MIDI_TOGGLE, { enabled: true });
+    const firstFlush = defaultOff.flushManagedBeacon();
+    expect(defaultOff.getStatus().managedBeacon.enabled).to.equal(false);
+    expect(firstFlush.sent).to.equal(0);
+    expect(calls).to.have.lengthOf(0);
+
+    const enabled = createAnalyticsService({
+      location: createLocation('?analytics=1&analyticsBeacon=1'),
+      navigator: navigatorRef,
+      managedBeaconEndpoint: endpoint,
+      localStorage: createStorage(),
+      profile: 'classic',
+      surface: 'game',
+      now: () => 5000
+    });
+    enabled.track(ANALYTICS_EVENT_TYPES.GAMEPLAY_MIDI_TOGGLE, { enabled: true });
+    const secondFlush = enabled.flushManagedBeacon();
+    expect(enabled.getStatus().managedBeacon.enabled).to.equal(true);
+    expect(secondFlush.sent).to.equal(1);
+    expect(calls).to.have.lengthOf(1);
+    expect(calls[0].url).to.equal(endpoint);
+    const payload = JSON.parse(calls[0].body);
+    expect(payload.events).to.have.lengthOf(1);
+    expect(payload.events[0].type).to.equal(ANALYTICS_EVENT_TYPES.GAMEPLAY_MIDI_TOGGLE);
+  });
+});
diff --git a/test/app-boot.test.js b/test/app-boot.test.js
new file mode 100644
index 00000000..e459c053
--- /dev/null
+++ b/test/app-boot.test.js
@@ -0,0 +1,194 @@
+import { expect } from 'chai';
+import { createCanvasStub } from './support/canvas.js';
+
+const preserveGlobals = (names) => {
+  const snapshot = new Map();
+  for (const name of names) {
+    snapshot.set(name, {
+      had: Object.prototype.hasOwnProperty.call(globalThis, name),
+      value: globalThis[name]
+    });
+  }
+  return () => {
+    for (const [name, entry] of snapshot.entries()) {
+      if (entry.had) {
+        globalThis[name] = entry.value;
+      } else {
+        delete globalThis[name];
+      }
+    }
+  };
+};
+
+describe('app boot helpers', function () {
+  it('applies responsive canvas sizing and native resize binding', async function () {
+    const restore = preserveGlobals(['window', 'document', '__LEMMINGS_BOOT_NO_AUTO_START__']);
+    const classSet = new Set();
+    const containerClasses = new Set();
+    const container = {
+      style: {},
+      classList: {
+        add(name) {
+          containerClasses.add(name);
+        },
+        remove(name) {
+          containerClasses.delete(name);
+        }
+      }
+    };
+    const listeners = [];
+
+    try {
+      const windowStub = {
+        visualViewport: {
+          width: 1600,
+          height: 800,
+          addEventListener(type, handler) {
+            listeners.push({ type, handler });
+          }
+        },
+        innerWidth: 1600,
+        innerHeight: 800,
+        addEventListener(type, handler) {
+          listeners.push({ type, handler });
+        },
+        removeEventListener() {}
+      };
+      const documentStub = {
+        body: {
+          classList: {
+            toggle(name, enabled) {
+              if (enabled) classSet.add(name);
+              else classSet.delete(name);
+            }
+          }
+        },
+        documentElement: {
+          clientWidth: 1600,
+          clientHeight: 800
+        },
+        querySelector(selector) {
+          if (selector === '.game_container') return container;
+          return null;
+        },
+        getElementById() {
+          return null;
+        }
+      };
+
+      globalThis.window = windowStub;
+      globalThis.document = documentStub;
+      globalThis.__LEMMINGS_BOOT_NO_AUTO_START__ = true;
+
+      const boot = await import(`../js/app/boot.js?boot_test=${Date.now()}`);
+      const canvas = createCanvasStub({ width: 0, height: 0 });
+      let stageResizeCalls = 0;
+      boot.setLemmingsForTest({
+        gameCanvas: canvas,
+        stage: {
+          scheduleUpdateStageSize() {
+            stageResizeCalls += 1;
+          }
+        }
+      });
+
+      boot.setSize();
+      boot.bindResize();
+
+      expect(containerClasses.has('small')).to.equal(false);
+      expect(container.style.width).to.equal('1333.3333333333335px');
+      expect(container.style.height).to.equal('800px');
+      expect(canvas.style.width).to.equal('1333.3333333333335px');
+      expect(canvas.style.height).to.equal('800px');
+      expect(stageResizeCalls).to.equal(1);
+      expect(classSet.has('portrait-small')).to.equal(false);
+      expect(listeners.map((entry) => entry.type)).to.deep.equal(['resize', 'orientationchange', 'resize']);
+    } finally {
+      restore();
+    }
+  });
+
+  it('registers resize listeners only once', async function () {
+    const restore = preserveGlobals(['window', 'document', '__LEMMINGS_BOOT_NO_AUTO_START__']);
+    try {
+      const listeners = [];
+      globalThis.window = {
+        visualViewport: {
+          width: 500,
+          height: 700,
+          addEventListener(type, handler) {
+            listeners.push({ type, handler });
+          }
+        },
+        innerWidth: 500,
+        innerHeight: 700,
+        addEventListener(type, handler) {
+          listeners.push({ type, handler });
+        },
+        removeEventListener() {}
+      };
+      globalThis.document = {
+        body: { classList: { toggle() {} } },
+        documentElement: { clientWidth: 500, clientHeight: 700 },
+        querySelector() {
+          return null;
+        },
+        getElementById() {
+          return null;
+        }
+      };
+      globalThis.__LEMMINGS_BOOT_NO_AUTO_START__ = true;
+
+      const boot = await import(`../js/app/boot.js?boot_test_nojq=${Date.now()}`);
+      boot.bindResize();
+      boot.bindResize();
+      expect(listeners.map((entry) => entry.type)).to.deep.equal(['resize', 'orientationchange', 'resize']);
+    } finally {
+      restore();
+    }
+  });
+
+  it('surfaces embed-mode boot failures without throwing', async function () {
+    const restore = preserveGlobals(['window', 'document', '__LEMMINGS_BOOT_NO_AUTO_START__']);
+    try {
+      const appended = [];
+      globalThis.window = {
+        location: { search: '?embed=1' },
+        visualViewport: null,
+        innerWidth: 800,
+        innerHeight: 480,
+        addEventListener() {},
+        removeEventListener() {}
+      };
+      globalThis.document = {
+        readyState: 'complete',
+        body: {
+          appendChild(node) {
+            appended.push(node);
+          },
+          classList: { toggle() {} }
+        },
+        documentElement: {
+          setAttribute() {}
+        },
+        querySelector() {
+          return this.body;
+        },
+        createElement() {
+          return { id: '', textContent: '', className: '' };
+        },
+        getElementById() {
+          return null;
+        }
+      };
+      globalThis.__LEMMINGS_BOOT_NO_AUTO_START__ = true;
+
+      const boot = await import(`../js/app/boot.js?boot_embed=${Date.now()}`);
+      expect(() => boot.start()).to.not.throw();
+      expect(appended).to.have.lengthOf(1);
+      expect(appended[0].id).to.equal('bootFailureNotice');
+    } finally {
+      restore();
+    }
+  });
+});
diff --git a/test/bench-history-stress.test.js b/test/bench-history-stress.test.js
new file mode 100644
index 00000000..8c3408f1
--- /dev/null
+++ b/test/bench-history-stress.test.js
@@ -0,0 +1,117 @@
+import { expect } from 'chai';
+import {
+  buildUrl,
+  createHistoryBenchConfig,
+  DEFAULT_BASE_URL,
+  parseArgs,
+  parseSpeedList,
+  summarizeTimings,
+  toBoolean,
+  toPositiveNumber
+} from '../scripts/bench-history-stress.js';
+
+describe('bench-history-stress helpers', function () {
+  it('parses args and number helpers safely', function () {
+    const args = parseArgs(['--profile=soak', '--smoke']);
+    expect(args.get('profile')).to.equal('soak');
+    expect(args.get('smoke')).to.equal('true');
+    expect(toPositiveNumber('30', 5)).to.equal(30);
+    expect(toPositiveNumber('-1', 5)).to.equal(5);
+    expect(toPositiveNumber(Symbol('duration'), 5)).to.equal(5);
+    expect(toBoolean('off', true)).to.equal(false);
+    expect(toBoolean('unknown', true)).to.equal(true);
+  });
+
+  it('parses speed lists and filters invalid entries', function () {
+    expect(parseSpeedList('30, 60, bad, -2, 0, 120')).to.deep.equal([30, 60, 120]);
+    expect(parseSpeedList('')).to.deep.equal([]);
+  });
+
+  it('falls back to profile speeds when provided speed list is invalid', function () {
+    const warnings = [];
+    const config = createHistoryBenchConfig({
+      argv: ['--speeds=,,', '--headless=no'],
+      env: {},
+      log: {
+        warn(message) {
+          warnings.push(message);
+        }
+      }
+    });
+
+    expect(config.speeds).to.deep.equal([30, 60]);
+    expect(config.headless).to.equal(false);
+    expect(warnings.some((message) => String(message).includes('Invalid speed list'))).to.equal(true);
+  });
+
+  it('normalizes malformed URLs to the default bench URL', function () {
+    const malformed = buildUrl('not-a-valid-url');
+    expect(malformed.startsWith(DEFAULT_BASE_URL)).to.equal(true);
+    const parsed = new URL(malformed);
+    expect(parsed.searchParams.get('e2e')).to.equal('1');
+    expect(parsed.searchParams.get('ph')).to.equal('true');
+    expect(parsed.searchParams.get('endless')).to.equal('true');
+  });
+
+  it('builds stable timing summaries for empty and populated lists', function () {
+    expect(summarizeTimings([])).to.deep.equal({
+      count: 0,
+      p50Ms: 0,
+      p95Ms: 0,
+      maxMs: 0,
+      samplesMs: []
+    });
+    const summary = summarizeTimings([20, 10, 30]);
+    expect(summary.count).to.equal(3);
+    expect(summary.samplesMs).to.deep.equal([10, 20, 30]);
+    expect(summary.p50Ms).to.equal(20);
+    expect(summary.p95Ms).to.equal(30);
+  });
+
+  it('applies environment overrides for profile, speeds, and boolean gates', function () {
+    const config = createHistoryBenchConfig({
+      argv: [],
+      env: {
+        HISTORY_PROFILE: 'default',
+        HISTORY_SPEEDS: '45,90',
+        HISTORY_HEADLESS: 'off',
+        HISTORY_REQUIRE_REPLAY_PARITY: '0',
+        HISTORY_REQUIRE_BOUNDED_RETENTION: 'no',
+        HISTORY_REQUIRE_TARGET_SPAN: 'yes',
+        HISTORY_REQUIRE_COLD_COMPACTION: 'yes'
+      },
+      log: { warn() {} }
+    });
+
+    expect(config.requestedProfile).to.equal('default');
+    expect(config.speeds).to.deep.equal([45, 90]);
+    expect(config.headless).to.equal(false);
+    expect(config.requireReplayParity).to.equal(false);
+    expect(config.requireBoundedRetention).to.equal(false);
+    expect(config.requireTargetSpan).to.equal(true);
+    expect(config.requireColdCompaction).to.equal(true);
+  });
+
+  it('treats target span as a long-profile gate by default', function () {
+    const smoke = createHistoryBenchConfig({
+      argv: ['--profile=smoke'],
+      env: {},
+      log: { warn() {} }
+    });
+    const soak = createHistoryBenchConfig({
+      argv: ['--profile=soak'],
+      env: {},
+      log: { warn() {} }
+    });
+    const strictSmoke = createHistoryBenchConfig({
+      argv: ['--profile=smoke', '--requireTargetSpan=true'],
+      env: {},
+      log: { warn() {} }
+    });
+
+    expect(smoke.targetSpan).to.equal(6000);
+    expect(smoke.requireTargetSpan).to.equal(false);
+    expect(soak.requireTargetSpan).to.equal(true);
+    expect(strictSmoke.requireTargetSpan).to.equal(true);
+  });
+});
diff --git a/test/bench-hotpaths.test.js b/test/bench-hotpaths.test.js
new file mode 100644
index 00000000..cf95e3d8
--- /dev/null
+++ b/test/bench-hotpaths.test.js
@@ -0,0 +1,73 @@
+import { expect } from 'chai';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const parseJsonOutput = (stdout) => {
+  const text = String(stdout || '').trim();
+  const first = text.indexOf('{');
+  const last = text.lastIndexOf('}');
+  if (first < 0 || last <= first) return null;
+  return JSON.parse(text.slice(first, last + 1));
+};
+
+describe('bench-hotpaths script', () => {
+  it('reports midi router and scheduler throughput sections', () => {
+    const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+    const script = path.join(root, 'scripts', 'bench-hotpaths.js');
+    const result = spawnSync(process.execPath, [
+      script,
+      '--repeats=1',
+      '--dirty-iterations=10',
+      '--dirty-rects=1',
+      '--tile-iterations=10',
+      '--tile-per-iter=1',
+      '--ants-iterations=10',
+      '--gui-iterations=5',
+      '--overlay-iterations=5',
+      '--scaled-iterations=10',
+      '--history-ticks=4',
+      '--history-seek-window=2',
+      '--terrain-iterations=10',
+      '--terrain-clear-iterations=2',
+      '--terrain-dig-iterations=2',
+      '--object-iterations=1',
+      '--minimap-iterations=5',
+      '--gamepad-iterations=5',
+      '--midi-router-iterations=10',
+      '--midi-router-events=4',
+      '--midi-scheduler-iterations=10',
+      '--midi-scheduler-notes=4'
+    ], {
+      encoding: 'utf8',
+      maxBuffer: 4 * 1024 * 1024
+    });
+    expect(result.status).to.equal(0);
+    const summary = parseJsonOutput(result.stdout);
+    expect(summary).to.be.an('object');
+    expect(summary).to.have.property('historyReplayDelta');
+    expect(summary).to.have.property('terrainMasks');
+    expect(summary).to.have.property('tileComposition');
+    expect(summary).to.have.property('overlayPlane');
+    expect(summary).to.have.property('scaledBlit');
+    expect(summary).to.have.property('objectCulling');
+    expect(summary).to.have.property('minimapIdle');
+    expect(summary).to.have.property('gamepadIdle');
+    expect(summary).to.have.property('midiRouter');
+    expect(summary).to.have.property('midiScheduler');
+    expect(summary.historyReplayDelta.lemmings50.endTick.avgMs).to.be.a('number');
+    expect(summary.terrainMasks.clearGroundWithMaskCount.historyRecords).to.be.a('number');
+    expect(summary.tileComposition.avgMs).to.be.a('number');
+    expect(summary.tileComposition.p95Ms).to.be.a('number');
+    expect(summary.tileComposition.worstMs).to.be.a('number');
+    expect(summary.overlayPlane.avgMs).to.be.a('number');
+    expect(summary.overlayPlane.p99Ms).to.be.a('number');
+    expect(summary.scaledBlit.avgMs).to.be.a('number');
+    expect(summary.scaledBlit.allocBytesAvg).to.be.a('number');
+    expect(summary.objectCulling.viewport1000.avgMs).to.be.a('number');
+    expect(summary.minimapIdle.pausedIdle.drawCalls).to.be.a('number');
+    expect(summary.gamepadIdle.getGamepadsCalls).to.be.a('number');
+    expect(summary.midiRouter.avgMs).to.be.a('number');
+    expect(summary.midiScheduler.avgMs).to.be.a('number');
+  });
+});
diff --git a/test/bench-long-session.test.js b/test/bench-long-session.test.js
new file mode 100644
index 00000000..fd301593
--- /dev/null
+++ b/test/bench-long-session.test.js
@@ -0,0 +1,223 @@
+import { expect } from 'chai';
+import {
+  buildBenchUrl,
+  DEFAULT_BASE_URL,
+  evaluateLongSessionGates,
+  normalizeLongSessionSample,
+  PROFILE_PRESETS,
+  toBoolean,
+  toNonNegativeNumber,
+  toPositiveNumber
+} from '../scripts/bench-long-session.js';
+
+describe('bench long-session gates', function () {
+  it('passes when replay and runtime metrics stay within thresholds', function () {
+    const thresholds = {
+      ...PROFILE_PRESETS.smoke,
+      maxHeapGrowthBytes: 64,
+      maxHeapChurnBytes: 128,
+      maxSoundQueueRatio: 0.75,
+      maxSoundQueueGrowth: 4,
+      minHistorySpanTicks: 100,
+      maxTriggerDrift: 0
+    };
+
+    const result = evaluateLongSessionGates({
+      samples: [
+        {
+          tickIndex: 100,
+          heapUsedBytes: 1024,
+          soundQueued: 1,
+          soundQueueLimit: 8,
+          historySpanTicks: 120,
+          triggerCount: 7
+        },
+        {
+          tickIndex: 160,
+          heapUsedBytes: 1040,
+          soundQueued: 2,
+          soundQueueLimit: 8,
+          historySpanTicks: 180,
+          triggerCount: 7
+        },
+        {
+          tickIndex: 220,
+          heapUsedBytes: 1060,
+          soundQueued: 3,
+          soundQueueLimit: 8,
+          historySpanTicks: 240,
+          triggerCount: 7
+        }
+      ],
+      replayChecks: [{ checked: true, hashMatch: true }],
+      thresholds
+    });
+
+    expect(result.failures).to.deep.equal([]);
+    expect(result.metrics.heapChurnBytes).to.equal(36);
+    expect(result.metrics.soundQueueGrowth).to.equal(2);
+    expect(result.metrics.tickProgress).to.equal(120);
+  });
+
+  it('fails on churn, queue growth, drift, and replay mismatches', function () {
+    const thresholds = {
+      ...PROFILE_PRESETS.smoke,
+      maxHeapGrowthBytes: 8,
+      maxHeapChurnBytes: 32,
+      maxSoundQueueRatio: 0.5,
+      maxSoundQueueGrowth: 2,
+      minHistorySpanTicks: 500,
+      maxTriggerDrift: 0
+    };
+
+    const result = evaluateLongSessionGates({
+      samples: [
+        {
+          tickIndex: 200,
+          heapUsedBytes: 1000,
+          soundQueued: 1,
+          soundQueueLimit: 4,
+          historySpanTicks: 50,
+          triggerCount: 9
+        },
+        {
+          tickIndex: 200,
+          heapUsedBytes: 1050,
+          soundQueued: 4,
+          soundQueueLimit: 4,
+          historySpanTicks: 100,
+          triggerCount: 10
+        },
+        {
+          tickIndex: 200,
+          heapUsedBytes: 1120,
+          soundQueued: 4,
+          soundQueueLimit: 4,
+          historySpanTicks: 120,
+          triggerCount: 10
+        }
+      ],
+      replayChecks: [{ checked: true, hashMatch: false }],
+      thresholds
+    });
+
+    expect(result.failures).to.include.members([
+      'tick_progress_stalled',
+      'heap_growth_exceeded',
+      'heap_churn_exceeded',
+      'sound_queue_ratio_exceeded',
+      'sound_queue_growth_exceeded',
+      'history_span_below_minimum',
+      'trigger_count_drift_detected',
+      'replay_hash_mismatch'
+    ]);
+  });
+
+  it('normalizes sample payloads to finite numeric defaults', function () {
+    const sample = normalizeLongSessionSample({
+      elapsedMs: '10',
+      tickIndex: '42',
+      historySpanTicks: null,
+      coldBlockCount: undefined,
+      soundQueued: '3',
+      soundQueueLimit: '12',
+      triggerCount: Number.NaN,
+      heapUsedBytes: '2048'
+    });
+    expect(sample).to.deep.equal({
+      elapsedMs: 10,
+      tickIndex: 42,
+      historySpanTicks: 0,
+      coldBlockCount: 0,
+      soundQueued: 3,
+      soundQueueLimit: 12,
+      triggerCount: 0,
+      heapUsedBytes: 2048
+    });
+
+    const symbolSample = normalizeLongSessionSample({
+      elapsedMs: Symbol('elapsed'),
+      tickIndex: Symbol('tick'),
+      historySpanTicks: Symbol('history'),
+      coldBlockCount: Symbol('cold'),
+      soundQueued: Symbol('queued'),
+      soundQueueLimit: Symbol('limit'),
+      triggerCount: Symbol('trigger'),
+      heapUsedBytes: Symbol('heap')
+    });
+    expect(symbolSample).to.deep.equal({
+      elapsedMs: 0,
+      tickIndex: 0,
+      historySpanTicks: 0,
+      coldBlockCount: 0,
+      soundQueued: 0,
+      soundQueueLimit: 0,
+      triggerCount: 0,
+      heapUsedBytes: 0
+    });
+  });
+
+  it('clamps invalid normalized sample values to safe numeric defaults', function () {
+    const sample = normalizeLongSessionSample({
+      elapsedMs: Infinity,
+      tickIndex: Infinity,
+      historySpanTicks: -3,
+      coldBlockCount: Number.NaN,
+      soundQueued: -1,
+      soundQueueLimit: -1,
+      triggerCount: -10,
+      heapUsedBytes: Infinity
+    });
+    expect(sample).to.deep.equal({
+      elapsedMs: 0,
+      tickIndex: 0,
+      historySpanTicks: 0,
+      coldBlockCount: 0,
+      soundQueued: 0,
+      soundQueueLimit: 0,
+      triggerCount: 0,
+      heapUsedBytes: 0
+    });
+  });
+
+  it('parses positive and non-negative threshold helpers safely', function () {
+    expect(toPositiveNumber(undefined, 7)).to.equal(7);
+    expect(toPositiveNumber('-5', 7)).to.equal(7);
+    expect(toPositiveNumber('abc', 7)).to.equal(7);
+    expect(toPositiveNumber('4', 7)).to.equal(4);
+    expect(toPositiveNumber(Symbol('positive'), 7)).to.equal(7);
+
+    expect(toNonNegativeNumber(undefined, 3)).to.equal(3);
+    expect(toNonNegativeNumber(-1, 3)).to.equal(3);
+    expect(toNonNegativeNumber('NaN', 3)).to.equal(3);
+    expect(toNonNegativeNumber(0, 3)).to.equal(0);
+    expect(toNonNegativeNumber('5', 3)).to.equal(5);
+    expect(toNonNegativeNumber(Symbol('non-negative'), 3)).to.equal(3);
+    expect(toBoolean('false', true)).to.equal(false);
+    expect(toBoolean('1', false)).to.equal(true);
+    expect(toBoolean('unknown', false)).to.equal(false);
+  });
+
+  it('handles empty and partial replay samples without throwing', function () {
+    const result = evaluateLongSessionGates({
+      samples: [],
+      replayChecks: [{ checked: true }, { checked: true, hashMatch: false }],
+      thresholds: PROFILE_PRESETS.smoke
+    });
+    expect(result.metrics.sampleCount).to.equal(0);
+    expect(result.metrics.replayMismatchCount).to.equal(1);
+    expect(result.failures).to.include('tick_progress_stalled');
+    expect(result.failures).to.include('replay_hash_mismatch');
+  });
+
+  it('normalizes malformed bench URLs and injects perf profile', function () {
+    const malformed = buildBenchUrl('bad-url');
+    expect(malformed.startsWith(DEFAULT_BASE_URL)).to.equal(true);
+    const parsed = new URL(malformed);
+    expect(parsed.searchParams.get('e2e')).to.equal('1');
+    expect(parsed.searchParams.get('profile')).to.equal('perf');
+
+    const explicit = new URL(buildBenchUrl('https://localhost:8080/?profile=custom'));
+    expect(explicit.searchParams.get('profile')).to.equal('custom');
+  });
+});
diff --git a/test/bench-performance.test.js b/test/bench-performance.test.js
new file mode 100644
index 00000000..b3bc23f2
--- /dev/null
+++ b/test/bench-performance.test.js
@@ -0,0 +1,97 @@
+import { expect } from 'chai';
+import {
+  BENCH_PROFILES,
+  buildUrl,
+  createPerformanceBenchConfig,
+  median,
+  parseArgs,
+  summarize,
+  toBoolean,
+  toPositiveNumber
+} from '../scripts/bench-performance.js';
+
+describe('bench-performance helpers', function () {
+  it('parses args and primitive helpers safely', function () {
+    const args = parseArgs(['--profile=stress', '--smoke', '--headless=false']);
+    expect(args.get('profile')).to.equal('stress');
+    expect(args.get('smoke')).to.equal('true');
+    expect(toPositiveNumber('5', 1)).to.equal(5);
+    expect(toPositiveNumber('-1', 1)).to.equal(1);
+    expect(toBoolean('off', true)).to.equal(false);
+    expect(toBoolean('on', false)).to.equal(true);
+    expect(toBoolean('invalid', false)).to.equal(false);
+    expect(toPositiveNumber(Symbol('duration'), 7)).to.equal(7);
+  });
+
+  it('builds config with smoke defaults, mode fallback, and boolean parsing', function () {
+    const warnings = [];
+    const config = createPerformanceBenchConfig({
+      argv: ['--mode=wat', '--headless=0'],
+      env: {},
+      warn(message) {
+        warnings.push(message);
+      }
+    });
+
+    expect(config.requestedProfile).to.equal('smoke');
+    expect(config.durationMs).to.equal(BENCH_PROFILES.smoke.durationMs);
+    expect(config.mode).to.equal(BENCH_PROFILES.smoke.mode);
+    expect(config.headless).to.equal(false);
+    expect(warnings.some(message => String(message).includes('defaulting to smoke'))).to.equal(true);
+    expect(warnings.some(message => String(message).includes('Unsupported mode'))).to.equal(true);
+  });
+
+  it('falls back to smoke profile when explicit profile is unknown', function () {
+    const warnings = [];
+    const config = createPerformanceBenchConfig({
+      argv: ['--profile=unknown'],
+      env: {},
+      warn(message) {
+        warnings.push(message);
+      }
+    });
+
+    expect(config.requestedProfile).to.equal('unknown');
+    expect(config.durationMs).to.equal(BENCH_PROFILES.smoke.durationMs);
+    expect(warnings.some(message => String(message).includes('Unknown profile'))).to.equal(true);
+  });
+
+  it('normalizes malformed URLs while preserving existing query precedence', function () {
+    const malformed = buildUrl('not-a-valid-url', { profile: 'perf', perfOverlay: 'true' });
+    const malformedUrl = new URL(malformed);
+    expect(malformedUrl.searchParams.get('e2e')).to.equal('1');
+    expect(malformedUrl.searchParams.get('profile')).to.equal('perf');
+
+    const explicit = buildUrl(
+      'https://localhost:8080/?e2e=0&profile=custom',
+      { profile: 'perf', performanceAPI: 'true' }
+    );
+    const explicitUrl = new URL(explicit);
+    expect(explicitUrl.searchParams.get('e2e')).to.equal('1');
+    expect(explicitUrl.searchParams.get('profile')).to.equal('custom');
+    expect(explicitUrl.searchParams.get('performanceAPI')).to.equal('true');
+  });
+
+  it('summarizes numeric key series and ignores non-finite values', function () {
+    const stats = summarize([
+      { tps: 10 },
+      { tps: 20 },
+      { tps: Number.NaN },
+      { tps: 30 }
+    ], 'tps');
+    expect(stats).to.deep.equal({
+      min: 10,
+      max: 30,
+      p50: 20,
+      p95: 20,
+      avg: 20
+    });
+  });
+
+  it('computes medians for odd, even, and empty input arrays', function () {
+    expect(median([])).to.equal(0);
+    expect(median([5])).to.equal(5);
+    expect(median([3, 1, 2])).to.equal(2);
+    expect(median([4, 1, 2, 3])).to.equal(2.5);
+  });
+});
diff --git a/test/bench-procgen-soak.test.js b/test/bench-procgen-soak.test.js
new file mode 100644
index 00000000..30487ddb
--- /dev/null
+++ b/test/bench-procgen-soak.test.js
@@ -0,0 +1,68 @@
+import { expect } from 'chai';
+import {
+  buildUrl,
+  createProcgenSoakConfig,
+  parseArgs,
+  summarize,
+  toBoolean,
+  toPositiveNumber
+} from '../scripts/bench-procgen-soak.js';
+
+describe('bench-procgen-soak helpers', function () {
+  it('parses CLI args and normalizes numeric/boolean values', function () {
+    const args = parseArgs(['--duration=1200', '--headless=false', '--smoke']);
+    expect(args.get('duration')).to.equal('1200');
+    expect(args.get('headless')).to.equal('false');
+    expect(args.get('smoke')).to.equal('true');
+
+    expect(toPositiveNumber('10', 5)).to.equal(10);
+    expect(toPositiveNumber('-1', 5)).to.equal(5);
+    expect(toPositiveNumber(Symbol('duration'), 5)).to.equal(5);
+    expect(toBoolean('off', true)).to.equal(false);
+    expect(toBoolean('enabled', false)).to.equal(true);
+  });
+
+  it('builds soak config from argv/env with safe fallbacks', function () {
+    const config = createProcgenSoakConfig({
+      argv: ['--duration=-5', '--sample=250', '--headless=no'],
+      env: {
+        LEMMINGS_PROCGEN_URL: 'https://example.test/procgen.html',
+        PROCGEN_SOAK_WARMUP_MS: 'not-a-number',
+        PROCGEN_SOAK_OP_TIMEOUT_MS: '0',
+        PROCGEN_SOAK_HEAP_LIMIT_MB: '128'
+      }
+    });
+
+    expect(config.baseUrl).to.equal('https://example.test/procgen.html');
+    expect(config.durationMs).to.equal(60000);
+    expect(config.sampleMs).to.equal(250);
+    expect(config.warmupMs).to.equal(5000);
+    expect(config.opTimeoutMs).to.equal(30000);
+    expect(config.headless).to.equal(false);
+    expect(config.heapLimitMb).to.equal(128);
+    expect(config.maxRuntimeMs).to.be.greaterThan(config.durationMs);
+  });
+
+  it('normalizes procgen URLs and tolerates invalid url inputs', function () {
+    expect(buildUrl('https://example.test/procgen.html?foo=1')).to.equal(
+      'https://example.test/procgen.html?foo=1&e2e=1'
+    );
+    expect(buildUrl('not-a-valid-url')).to.equal('https://localhost:8080/procgen.html?e2e=1');
+  });
+
+  it('summarizes numeric samples deterministically', function () {
+    expect(summarize([])).to.deep.equal({
+      min: 0,
+      max: 0,
+      p50: 0,
+      p95: 0,
+      avg: 0
+    });
+    const stats = summarize([8, 2, Number.NaN, 4, 10]);
+    expect(stats.min).to.equal(2);
+    expect(stats.max).to.equal(10);
+    expect(stats.p50).to.equal(4);
+    expect(stats.p95).to.equal(8);
+    expect(stats.avg).to.equal(6);
+  });
+});
diff --git a/test/bench-smoke.test.js b/test/bench-smoke.test.js
new file mode 100644
index 00000000..cfabdcbd
--- /dev/null
+++ b/test/bench-smoke.test.js
@@ -0,0 +1,56 @@
+import { expect } from 'chai';
+import { evaluateSmokeResults } from '../scripts/bench-smoke.js';
+
+describe('bench smoke gates', function () {
+  const thresholds = {
+    perfP95FrameMsMax: 250,
+    perfP50TpsMin: 15,
+    historySpanRatioMin: 0.5,
+    antsAvgMsMax: 250,
+    tileCompositionAvgMsMax: 250,
+    overlayPlaneAvgMsMax: 250,
+    scaledBlitAvgMsMax: 250
+  };
+
+  it('passes when all smoke metrics are within thresholds', function () {
+    const gate = evaluateSmokeResults({
+      performance: {
+        filteredFrameStats: { p95: 120 },
+        filteredTpsStats: { p50: 45 }
+      },
+      history: {
+        results: [{ maxSpanTicks: 24000, targetSpanTicks: 30000 }]
+      },
+      hotpaths: {
+        marchingAnts: { avgMs: 90 },
+        tileComposition: { avgMs: 90 },
+        overlayPlane: { avgMs: 90 },
+        scaledBlit: { avgMs: 90 }
+      }
+    }, thresholds);
+
+    expect(gate.ok).to.equal(true);
+    expect(gate.failures).to.deep.equal([]);
+  });
+
+  it('fails when any benchmark gate regresses', function () {
+    const gate = evaluateSmokeResults({
+      performance: {
+        filteredFrameStats: { p95: 500 },
+        filteredTpsStats: { p50: 5 }
+      },
+      history: {
+        results: [{ maxSpanTicks: 2000, targetSpanTicks: 30000 }]
+      },
+      hotpaths: {
+        marchingAnts: { avgMs: 1000 },
+        tileComposition: { avgMs: 1000 },
+        overlayPlane: { avgMs: 1000 },
+        scaledBlit: { avgMs: 1000 }
+      }
+    }, thresholds);
+
+    expect(gate.ok).to.equal(false);
+    expect(gate.failures.length).to.be.greaterThanOrEqual(7);
+  });
+});
diff --git a/test/binaryreader.test.js b/test/binaryreader.test.js
index 3689cca5..5b4f4bcc 100644
--- a/test/binaryreader.test.js
+++ b/test/binaryreader.test.js
@@ -47,6 +47,10 @@ describe('BinaryReader', function () {
     assert.strictEqual(reader.readIntBE(0), 0x04030201);
     assert.strictEqual(reader.readWord(4), 0x0506);
     assert.strictEqual(reader.readWordBE(4), 0x0605);
+    assert.strictEqual(reader.readIntBigEndian(4, 0), 0x01020304);
+    assert.strictEqual(reader.readIntLittleEndian(4, 0), 0x04030201);
+    assert.strictEqual(reader.readWordBigEndian(4), 0x0506);
+    assert.strictEqual(reader.readWordLittleEndian(4), 0x0605);
     assert.strictEqual(reader.readString(3, 6), 'ABC');
   });
 
@@ -181,9 +185,21 @@ describe('BinaryReader', function () {
     assert.strictEqual(reader.readByte(), 2);
     assert.strictEqual(reader.getOffset(), 1);
     const str = reader.readString(4);
-    assert.strictEqual(str.length, 2);
+    assert.strictEqual(str.length, 1);
     assert.strictEqual(str.charCodeAt(0), 3);
-    assert.strictEqual(str.charCodeAt(1), 4);
+    assert.strictEqual(reader.readByte(), 0);
+  });
+
+  it('uses logical offsets consistently inside non-zero windows', function () {
+    const reader = new BinaryReader(Uint8Array.from([0, 1, 2, 3, 4, 5]), 1, 4);
+
+    assert.strictEqual(reader.readByte(0), 1);
+    assert.strictEqual(reader.readWord(1), 0x0203);
+    assert.strictEqual(reader.readWordBE(2), 0x0403);
+    assert.strictEqual(reader.readIntBigEndian(4, 0), 0x01020304);
+    assert.strictEqual(reader.readIntLittleEndian(4, 0), 0x04030201);
+    assert.strictEqual(reader.readIntBigEndian(4, 1), 0);
+    assert.strictEqual(reader.readString(8, 0), String.fromCharCode(1, 2, 3, 4));
   });
 
   it('rejects when FileReader emits an error', async function () {
diff --git a/test/build-mcpb-bundle.test.js b/test/build-mcpb-bundle.test.js
new file mode 100644
index 00000000..a6c99e51
--- /dev/null
+++ b/test/build-mcpb-bundle.test.js
@@ -0,0 +1,86 @@
+import { expect } from 'chai';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import {
+  buildBundle,
+  createCopyList,
+  parseArgs,
+  resolveSurfaceFile
+} from '../scripts/build-mcpb-bundle.js';
+
+const withTempDir = async (fn) => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mcpb-bundle-'));
+  try {
+    await fn(dir);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+};
+
+describe('build-mcpb-bundle helpers', function () {
+  it('parses and validates surface arguments', function () {
+    expect(parseArgs(['--surface=EDITOR'])).to.deep.equal({ surface: 'editor' });
+    expect(parseArgs(['--surface', 'game'])).to.deep.equal({ surface: 'game' });
+    expect(() => parseArgs(['--surface'])).to.throw(/Missing value for --surface/);
+    expect(() => parseArgs(['--surface='])).to.throw(/Missing value for --surface/);
+    expect(() => parseArgs(['--unknown=1'])).to.throw(/Unknown option/);
+    expect(() => parseArgs(['--surface=bad'])).to.throw(/Invalid surface/);
+  });
+
+  it('resolves candidate files for surface bundles', function () {
+    expect(resolveSurfaceFile(null, 'manifest', 'mcpb/manifest.json')).to.deep.equal({
+      candidate: null,
+      fallbackPath: 'mcpb/manifest.json'
+    });
+    expect(resolveSurfaceFile('editor', 'manifest', 'mcpb/manifest.json')).to.deep.equal({
+      candidate: 'mcpb/manifest.editor.json',
+      fallbackPath: 'mcpb/manifest.json'
+    });
+    const copyList = createCopyList('editor');
+    expect(copyList[0].candidate).to.equal('mcpb/manifest.editor.json');
+    expect(copyList[3].candidate).to.equal('mcpb/package.editor.json');
+  });
+
+  it('builds surface bundles using candidate files with fallback support', async function () {
+    await withTempDir(async (rootDir) => {
+      fs.mkdirSync(path.join(rootDir, 'mcpb'), { recursive: true });
+      fs.mkdirSync(path.join(rootDir, 'mcp'), { recursive: true });
+      fs.writeFileSync(path.join(rootDir, 'mcpb', 'manifest.json'), '{"name":"fallback-manifest"}');
+      fs.writeFileSync(path.join(rootDir, 'mcpb', 'manifest.editor.json'), '{"name":"editor-manifest"}');
+      fs.writeFileSync(path.join(rootDir, 'mcpb', 'package.json'), '{"name":"fallback-package","type":"module"}');
+      fs.writeFileSync(path.join(rootDir, 'mcpb', 'package.editor.json'), '{"name":"editor-package","type":"module"}');
+      fs.writeFileSync(path.join(rootDir, 'mcpb', 'server.json'), '{"server":true}');
+      fs.writeFileSync(path.join(rootDir, 'mcpb', 'server.editor.json'), '{"server":"editor"}');
+      fs.writeFileSync(path.join(rootDir, 'mcpb', '.mcpbignore'), 'node_modules');
+      fs.writeFileSync(path.join(rootDir, 'keybindings.json'), '{"ok":true}');
+      fs.writeFileSync(path.join(rootDir, 'mcp', 'dep.js'), 'export const value = 42;');
+      fs.writeFileSync(path.join(rootDir, 'mcp', 'server.js'), 'import { value } from "./dep.js"; export const ok = value === 42;');
+
+      await buildBundle({
+        argv: ['--surface=editor'],
+        rootDir,
+        log: { log() {} }
+      });
+
+      const outDir = path.join(rootDir, 'dist', 'mcpb-editor');
+      expect(fs.readFileSync(path.join(outDir, 'manifest.json'), 'utf8')).to.equal('{"name":"editor-manifest"}');
+      expect(fs.readFileSync(path.join(outDir, 'package.json'), 'utf8')).to.equal('{"name":"editor-package","type":"module"}');
+      expect(fs.readFileSync(path.join(outDir, 'server.json'), 'utf8')).to.equal('{"server":"editor"}');
+      expect(fs.existsSync(path.join(outDir, 'mcp', 'dep.js'))).to.equal(true);
+      const builtServer = await import(pathToFileURL(path.join(outDir, 'mcp', 'server.js')).href);
+      expect(builtServer.ok).to.equal(true);
+
+      await buildBundle({
+        argv: ['--surface=interact'],
+        rootDir,
+        log: { log() {} }
+      });
+      const interactOutDir = path.join(rootDir, 'dist', 'mcpb-interact');
+      expect(fs.readFileSync(path.join(interactOutDir, 'manifest.json'), 'utf8')).to.equal('{"name":"fallback-manifest"}');
+      expect(fs.readFileSync(path.join(interactOutDir, 'package.json'), 'utf8')).to.equal('{"name":"fallback-package","type":"module"}');
+      expect(fs.readFileSync(path.join(interactOutDir, 'server.json'), 'utf8')).to.equal('{"server":true}');
+    });
+  });
+});
diff --git a/test/canvas-focus-blur.test.js b/test/canvas-focus-blur.test.js
new file mode 100644
index 00000000..913e7109
--- /dev/null
+++ b/test/canvas-focus-blur.test.js
@@ -0,0 +1,104 @@
+import { expect } from 'chai';
+import { bindCanvasFocusBlur } from '../js/app/canvasFocusBlur.js';
+
+const createListenerHost = () => ({
+  listeners: new Map(),
+  addEventListener(type, handler) {
+    const handlers = this.listeners.get(type) || [];
+    handlers.push(handler);
+    this.listeners.set(type, handlers);
+  },
+  removeEventListener(type, handler) {
+    const handlers = this.listeners.get(type) || [];
+    const next = handlers.filter(entry => entry !== handler);
+    if (next.length) {
+      this.listeners.set(type, next);
+    } else {
+      this.listeners.delete(type);
+    }
+  }
+});
+
+const countHandlers = (host, type) => (host.listeners.get(type) || []).length;
+
+describe('canvasFocusBlur', function () {
+  it('returns a no-op cleanup when canvas is missing', function () {
+    const cleanup = bindCanvasFocusBlur(null);
+    expect(cleanup).to.be.a('function');
+    expect(() => cleanup()).to.not.throw();
+  });
+
+  it('deduplicates repeated binds and supports teardown/rebind', function () {
+    const documentRef = {
+      ...createListenerHost(),
+      activeElement: null,
+      body: { tabIndex: 0, focus() {} }
+    };
+    const canvas = {
+      ...createListenerHost(),
+      dataset: {}
+    };
+    const windowRef = { setTimeout(fn) { fn(); } };
+
+    const cleanupA = bindCanvasFocusBlur(canvas, { documentRef, windowRef });
+    const cleanupB = bindCanvasFocusBlur(canvas, { documentRef, windowRef });
+
+    expect(cleanupA).to.equal(cleanupB);
+    expect(countHandlers(documentRef, 'pointerdown')).to.equal(1);
+    expect(countHandlers(canvas, 'pointerdown')).to.equal(1);
+
+    cleanupA();
+    expect(countHandlers(documentRef, 'pointerdown')).to.equal(0);
+    expect(countHandlers(canvas, 'pointerdown')).to.equal(0);
+
+    const cleanupC = bindCanvasFocusBlur(canvas, { documentRef, windowRef });
+    expect(cleanupC).to.not.equal(cleanupA);
+    expect(countHandlers(documentRef, 'pointerdown')).to.equal(1);
+    cleanupC();
+  });
+
+  it('blurs active form inputs only for non-form interaction targets', function () {
+    let blurred = 0;
+    let bodyFocusCount = 0;
+    let documentRef;
+    const activeInput = {
+      tagName: 'INPUT',
+      isContentEditable: false,
+      blur() {
+        blurred += 1;
+        if (documentRef) {
+          documentRef.activeElement = null;
+        }
+      }
+    };
+    documentRef = {
+      ...createListenerHost(),
+      activeElement: activeInput,
+      body: {
+        tabIndex: 0,
+        focus() {
+          bodyFocusCount += 1;
+        }
+      }
+    };
+    const canvas = {
+      ...createListenerHost(),
+      dataset: {}
+    };
+    const windowRef = { setTimeout(fn) { fn(); } };
+
+    const cleanup = bindCanvasFocusBlur(canvas, { documentRef, windowRef });
+    const handler = documentRef.listeners.get('pointerdown')[0];
+
+    handler({ target: { tagName: 'DIV', isContentEditable: false } });
+    expect(blurred).to.equal(1);
+    expect(bodyFocusCount).to.equal(1);
+
+    blurred = 0;
+    documentRef.activeElement = activeInput;
+    handler({ target: { tagName: 'INPUT', isContentEditable: false } });
+    expect(blurred).to.equal(0);
+
+    cleanup();
+  });
+});
diff --git a/test/capability-matrix.test.js b/test/capability-matrix.test.js
new file mode 100644
index 00000000..349c8976
--- /dev/null
+++ b/test/capability-matrix.test.js
@@ -0,0 +1,108 @@
+import { expect } from 'chai';
+import {
+  detectRuntimeCapabilities,
+  resolveRenderExperimentState
+} from '../js/core/capabilityMatrix.js';
+
+describe('capabilityMatrix', function () {
+  it('returns deterministic fallbacks when optional APIs are unavailable', function () {
+    const capabilities = detectRuntimeCapabilities({
+      windowRef: {},
+      navigatorRef: {},
+      webMidi: null
+    });
+
+    expect(capabilities.webMidi.supported).to.equal(false);
+    expect(capabilities.webMidi.fallbackPath).to.equal('audio_only');
+    expect(capabilities.offscreenCanvas.supported).to.equal(false);
+    expect(capabilities.imageBitmap.supported).to.equal(false);
+    expect(capabilities.renderPaths.presentPathSupported).to.equal(false);
+    expect(capabilities.renderPaths.workerOffscreenSupported).to.equal(false);
+    expect(capabilities.renderPaths.deterministicFallback).to.equal('canvas2d_main_thread');
+  });
+
+  it('detects full capability support for WebMIDI/offscreen/imagebitmap/worker', function () {
+    const windowRef = {
+      OffscreenCanvas: function OffscreenCanvas() {},
+      createImageBitmap() {},
+      Worker: function Worker() {},
+      HTMLCanvasElement: {
+        prototype: {
+          transferControlToOffscreen() {}
+        }
+      }
+    };
+    const navigatorRef = {
+      requestMIDIAccess() {}
+    };
+    const webMidi = {
+      enabled: true,
+      enable() {}
+    };
+
+    const capabilities = detectRuntimeCapabilities({
+      windowRef,
+      navigatorRef,
+      webMidi
+    });
+
+    expect(capabilities.webMidi.supported).to.equal(true);
+    expect(capabilities.webMidi.enabled).to.equal(true);
+    expect(capabilities.offscreenCanvas.supported).to.equal(true);
+    expect(capabilities.imageBitmap.supported).to.equal(true);
+    expect(capabilities.worker.supported).to.equal(true);
+    expect(capabilities.renderPaths.presentPathSupported).to.equal(true);
+    expect(capabilities.renderPaths.workerOffscreenSupported).to.equal(true);
+  });
+
+  it('keeps present-path support when only Canvas2D is available', function () {
+    const capabilities = detectRuntimeCapabilities({
+      windowRef: {
+        document: {
+          createElement() {}
+        }
+      },
+      navigatorRef: {}
+    });
+    expect(capabilities.renderPaths.presentPathSupported).to.equal(true);
+    expect(capabilities.renderPaths.workerOffscreenSupported).to.equal(false);
+    expect(capabilities.renderPaths.deterministicFallback).to.equal('drawimage_present');
+  });
+
+  it('resolves experiment rollback reasons deterministically', function () {
+    const noImageBitmap = {
+      offscreenCanvas: { supported: true },
+      imageBitmap: { supported: false },
+      worker: { supported: true },
+      renderPaths: {
+        presentPathSupported: false,
+        workerOffscreenSupported: false,
+        deterministicFallback: 'canvas2d_main_thread'
+      }
+    };
+    const withImageNoWorker = {
+      offscreenCanvas: { supported: true },
+      imageBitmap: { supported: true },
+      worker: { supported: false },
+      renderPaths: {
+        presentPathSupported: true,
+        workerOffscreenSupported: false,
+        deterministicFallback: 'drawimage_present'
+      }
+    };
+
+    const offscreenState = resolveRenderExperimentState({ offscreenPresent: true }, noImageBitmap);
+    expect(offscreenState.presentPathActive).to.equal(false);
+    expect(offscreenState.offscreenPresentActive).to.equal(false);
+    expect(offscreenState.rollbackReason).to.equal('imagebitmap_unavailable');
+
+    const workerState = resolveRenderExperimentState(
+      { offscreenPresent: true, workerOffscreen: true },
+      withImageNoWorker
+    );
+    expect(workerState.presentPathActive).to.equal(true);
+    expect(workerState.offscreenPresentActive).to.equal(true);
+    expect(workerState.workerOffscreenActive).to.equal(false);
+    expect(workerState.rollbackReason).to.equal('worker_unavailable');
+  });
+});
diff --git a/test/check-undefined.test.js b/test/check-undefined.test.js
index 271b2d6b..35eca77f 100644
--- a/test/check-undefined.test.js
+++ b/test/check-undefined.test.js
@@ -23,34 +23,28 @@ const runCheck = (args = [], options = {}) => {
 };
 
 describe('scripts/check-undefined.js', function () {
-  it('detects undefined function calls', function () {
+  it('detects undefined inline HTML references', function () {
     withTempDir((dir) => {
-      fs.mkdirSync(path.join(dir, 'js'));
       const html = '<html><body><script>missingCall();</script></body></html>';
       fs.writeFileSync(path.join(dir, 'index.html'), html);
       const result = runCheck([], { cwd: dir });
       expect(result.status).to.not.equal(0);
-      expect(result.stderr || result.stdout).to.match(/missingCall|require is not defined/);
+      expect(result.stderr || result.stdout).to.match(/'missingCall' is not defined/);
     });
   });
 
-  it('detects global leaks assigned without var/let', function () {
+  it('detects undefined JS references when JS files are passed explicitly', function () {
     withTempDir((dir) => {
       const file = path.join(dir, 'leak.js');
       fs.writeFileSync(file, 'leakFn = function(){}; leakFn();');
       const result = runCheck(file);
       expect(result.status).to.not.equal(0);
-      expect(result.stderr || result.stdout).to.match(/leakFn is not defined/);
+      expect(result.stderr || result.stdout).to.match(/'leakFn' is not defined/);
     });
   });
 
   it('returns success when all calls are defined', function () {
     withTempDir((dir) => {
-      fs.mkdirSync(path.join(dir, 'js'));
-      fs.writeFileSync(
-        path.join(dir, 'js', 'main.js'),
-        'function foo(){}; foo();\n'
-      );
       const html = '<html><body><script>function bar(){}</script>\n' +
         '<script>bar();</script></body></html>';
       fs.writeFileSync(path.join(dir, 'index.html'), html);
@@ -73,37 +67,41 @@ describe('scripts/check-undefined.js', function () {
     });
   });
 
-  it('handles built-in methods and code fragments', function () {
+  it('follows relative entrypoint scripts from HTML inputs', function () {
     withTempDir((dir) => {
-      const file = path.join(dir, 'frag.js');
-      fs.writeFileSync(file, 'foo.appendChild(); return 5;');
-      const result = runCheck('frag.js', { cwd: dir });
+      fs.writeFileSync(path.join(dir, 'entry.js'), 'missingFromEntry();');
+      fs.writeFileSync(
+        path.join(dir, 'page.html'),
+        '<html><body><script src="./entry.js"></script></body></html>'
+      );
+
+      const result = runCheck(['page.html'], { cwd: dir });
+      expect(result.status).to.not.equal(0);
+      expect(result.stderr || result.stdout).to.match(/'missingFromEntry' is not defined/);
+    });
+  });
+
+  it('allows inline event-handler fragments', function () {
+    withTempDir((dir) => {
+      fs.writeFileSync(
+        path.join(dir, 'page.html'),
+        '<html><body><button onclick="return false;"></button></body></html>'
+      );
+      const result = runCheck('page.html', { cwd: dir });
       expect(result.status).to.equal(0);
       expect(result.stdout).to.match(/No undefined calls/);
     });
   });
 
-  it('skips node_modules, .git, and jquery.js when scanning the tree', function () {
+  it('skips node_modules, .git, and vendor scripts when scanning entrypoints', function () {
     withTempDir((dir) => {
       const jsDir = path.join(dir, 'js');
+      const vendorDir = path.join(jsDir, 'vendor');
       fs.mkdirSync(jsDir);
-      fs.mkdirSync(path.join(jsDir, 'sub'));
+      fs.mkdirSync(vendorDir);
 
-      fs.writeFileSync(path.join(jsDir, 'main.js'), 'function ok(){};');
-      fs.writeFileSync(
-        path.join(jsDir, 'sub', 'helper.js'),
-        [
-          'class Foo {',
-          '  jump() {}',
-          '  bar = () => {};',
-          '}',
-          'const arrow = () => {};',
-          'const named = function named() {};',
-          'const arr = [,];',
-          'with (Math) { }'
-        ].join('\n')
-      );
-      fs.writeFileSync(path.join(jsDir, 'jquery.js'), 'missingFromJquery();');
+      fs.writeFileSync(path.join(vendorDir, 'webmidi.js'), 'missingFromVendor();');
+      fs.writeFileSync(path.join(jsDir, 'main.js'), 'function ok(){} ok();');
 
       fs.mkdirSync(path.join(dir, 'node_modules'));
       fs.mkdirSync(path.join(dir, '.git'));
@@ -117,11 +115,7 @@ describe('scripts/check-undefined.js', function () {
       );
       fs.writeFileSync(
         path.join(dir, 'index.html'),
-        '<html><body><script>ok(); this.jump(); console.log("ok"); setTimeout(function(){},0);</script></body></html>'
-      );
-      fs.writeFileSync(
-        path.join(dir, 'bad.html'),
-        '<html><body><script>const = 1;</script></body></html>'
+        '<html><head><script src="js/vendor/webmidi.js"></script><script src="js/main.js"></script></head><body><script>console.log("ok"); setTimeout(function(){},0);</script></body></html>'
       );
 
       const result = runCheck([], { cwd: dir });
@@ -130,25 +124,46 @@ describe('scripts/check-undefined.js', function () {
     });
   });
 
-  it('returns success when JS cannot be parsed', function () {
+  it('reports parse errors for explicit JS files', function () {
     withTempDir((dir) => {
       const file = path.join(dir, 'bad.js');
       fs.writeFileSync(file, 'const = 1;');
 
       const result = runCheck(file);
-      expect(result.status).to.equal(0);
-      expect(result.stdout).to.match(/No undefined calls/);
+      expect(result.status).to.not.equal(0);
+      expect(result.stderr || result.stdout).to.match(/Parsing error|Unexpected token/);
     });
   });
 
-  it('reports undefined methods on non-builtin objects', function () {
+  it('discovers additional root html entrypoints in default mode', function () {
     withTempDir((dir) => {
-      const file = path.join(dir, 'missing-method.js');
-      fs.writeFileSync(file, 'const obj = {}; obj.missing(); ({}).alsoMissing();');
+      fs.writeFileSync(
+        path.join(dir, 'custom.html'),
+        '<html><body><script>missingCustomEntry();</script></body></html>'
+      );
 
-      const result = runCheck(file, { cwd: dir });
+      const result = runCheck([], { cwd: dir });
       expect(result.status).to.not.equal(0);
-      expect(result.stderr || result.stdout).to.match(/missing|alsoMissing/);
+      expect(result.stderr || result.stdout).to.match(/'missingCustomEntry' is not defined/);
+    });
+  });
+
+  it('treats common Mocha hook globals as built-ins', function () {
+    withTempDir((dir) => {
+      const file = path.join(dir, 'mocha-hooks.js');
+      fs.writeFileSync(file, [
+        'describe("suite", function () {',
+        '  beforeEach(function () {});',
+        '  afterEach(function () {});',
+        '  context("nested", function () {',
+        '    test("ok", function () {});',
+        '  });',
+        '});'
+      ].join('\n'));
+
+      const result = runCheck(file, { cwd: dir });
+      expect(result.status).to.equal(0);
+      expect(result.stdout).to.match(/No undefined calls/);
     });
   });
 });
diff --git a/test/commandmanager.test.js b/test/commandmanager.test.js
index 8c34d1a3..213f4611 100644
--- a/test/commandmanager.test.js
+++ b/test/commandmanager.test.js
@@ -71,7 +71,7 @@ describe('CommandManager', function() {
     expect(cm.serialize()).to.equal('1=x1');
   });
 
-  it('loadReplay schedules commands for future ticks', function() {     
+  it('loadReplay schedules commands for future ticks', function() {
     const timer = new MockTimer();
     const cm = new TestCommandManager(game, timer);
     cm.loadReplay('2=x5&bad&4=x6');
@@ -188,15 +188,12 @@ describe('CommandManager', function() {
     const cm = new TestCommandManager(game, timer);
     const listener = cm._tickListener;
     let offCalled = false;
-    let disposed = false;
     timer.onBeforeGameTick.off = function(fn) {
       if (fn === listener) offCalled = true;
       Lemmings.EventHandler.prototype.off.call(this, fn);
     };
-    timer.onBeforeGameTick.dispose = function() { disposed = true; };
     cm.dispose();
     expect(offCalled).to.equal(true);
-    expect(disposed).to.equal(true);
     expect(cm._tickListener).to.equal(null);
     expect(cm.game).to.equal(null);
     expect(cm.gameTimer).to.equal(null);
@@ -204,4 +201,16 @@ describe('CommandManager', function() {
     expect(cm.runCommands).to.deep.equal({});
     expect(cm.loggedCommads).to.deep.equal({});
   });
+
+  it('dispose does not clear unrelated before-tick listeners', function() {
+    const timer = new MockTimer();
+    let unrelatedCalls = 0;
+    timer.onBeforeGameTick.on(() => { unrelatedCalls += 1; });
+    const cm = new TestCommandManager(game, timer);
+
+    cm.dispose();
+    timer.next();
+
+    expect(unrelatedCalls).to.equal(1);
+  });
 });
diff --git a/test/commands.test.js b/test/commands.test.js
index f41a087e..79025bf6 100644
--- a/test/commands.test.js
+++ b/test/commands.test.js
@@ -15,7 +15,7 @@ const withSoundEvents = (soundEvents, fn) => {
   const prev = game.soundEvents;
   game.soundEvents = soundEvents;
   try {
-    return fn();
+    return fn(soundEvents);
   } finally {
     if (hadProp) {
       game.soundEvents = prev;
@@ -172,8 +172,9 @@ describe('Commands', function() {
     let called = null;
     withSoundEvents({
       emitSfx(type, id, payload) { called = { type, id, payload }; }
-    }, () => {
+    }, (soundEvents) => {
       const game = {
+        soundEvents,
         getLemmingManager() {
           return {
             getLemming() { return { id: 7, x: 1, y: 2 }; },
@@ -198,7 +199,7 @@ describe('Commands', function() {
     const calls = [];
     withSoundEvents({
       emitSfx(type, id, payload) { calls.push({ type, id, payload }); }
-    }, () => {
+    }, (soundEvents) => {
       const lem = { id: 1, x: 2, y: 3 };
       const skills = {
         setSelectedSkill() { return true; },
@@ -210,6 +211,7 @@ describe('Commands', function() {
         doLemmingAction() { return true; }
       };
       const game = {
+        soundEvents,
         getGameSkills() { return skills; },
         getLemmingManager() { return lemMgr; }
       };
diff --git a/test/core.number-parsing.test.js b/test/core.number-parsing.test.js
new file mode 100644
index 00000000..4ae08397
--- /dev/null
+++ b/test/core.number-parsing.test.js
@@ -0,0 +1,57 @@
+import assert from 'assert';
+import {
+  clampNumber,
+  parseBoundedNumber,
+  parseInt10,
+  toFiniteNumber
+} from '../js/core/numberParsing.js';
+
+describe('numberParsing', function () {
+  it('parses explicit base-10 integers', function () {
+    assert.strictEqual(parseInt10('08', 0), 8);
+    assert.strictEqual(parseInt10(' 42 ', 0), 42);
+    assert.strictEqual(parseInt10('nope', 7), 7);
+  });
+
+  it('parses and bounds finite numbers', function () {
+    assert.strictEqual(
+      parseBoundedNumber('2.5', { min: 0, max: 3, multiplier: 2, fallback: -1 }),
+      5
+    );
+    assert.strictEqual(
+      parseBoundedNumber('5', { min: 0, max: 10, integer: true, fallback: -1 }),
+      5
+    );
+    assert.strictEqual(
+      parseBoundedNumber('invalid', { min: 0, max: 10, fallback: -1 }),
+      -1
+    );
+    assert.strictEqual(
+      parseBoundedNumber('20', { min: 1, max: 60, multiplier: 10, fallback: -1 }),
+      200
+    );
+    assert.strictEqual(
+      parseBoundedNumber('0', { min: 1, max: 60, multiplier: 10, fallback: -1 }),
+      -1
+    );
+    assert.strictEqual(
+      parseBoundedNumber('61', { min: 1, max: 60, multiplier: 10, fallback: -1 }),
+      -1
+    );
+  });
+
+  it('normalizes finite conversion and clamping', function () {
+    assert.strictEqual(toFiniteNumber('3.14', null), 3.14);
+    assert.strictEqual(toFiniteNumber('abc', null), null);
+    assert.strictEqual(clampNumber(5, 0, 3), 3);
+  });
+
+  it('returns fallback for non-coercible numeric values', function () {
+    const symbolValue = Symbol('value');
+    assert.strictEqual(toFiniteNumber(symbolValue, 7), 7);
+    assert.strictEqual(
+      parseBoundedNumber(symbolValue, { min: 0, max: 10, fallback: -1 }),
+      -1
+    );
+  });
+});
diff --git a/test/dependencies.test.js b/test/dependencies.test.js
index 36dc78b1..18657ceb 100644
--- a/test/dependencies.test.js
+++ b/test/dependencies.test.js
@@ -3,12 +3,16 @@ import {
   setDependency,
   getDependency,
   clearDependency,
-  resetDependencies
+  resetDependencies,
+  setRuntimeContext,
+  clearRuntimeContext,
+  getRuntimeDependency
 } from '../js/core/dependencies.js';
 
 describe('dependencies', function() {
   afterEach(function() {
     resetDependencies();
+    clearRuntimeContext();
   });
 
   it('returns fallback when no override is set', function() {
@@ -35,4 +39,17 @@ describe('dependencies', function() {
     expect(getDependency('One', null)).to.equal(null);
     expect(getDependency('Two', null)).to.equal(null);
   });
+
+  it('prefers explicit runtime context over globals', function() {
+    const originalWindow = globalThis.window;
+    const globalWindow = { name: 'global' };
+    const runtimeWindow = { name: 'runtime' };
+    globalThis.window = globalWindow;
+    try {
+      setRuntimeContext({ window: runtimeWindow });
+      expect(getRuntimeDependency('window')).to.equal(runtimeWindow);
+    } finally {
+      globalThis.window = originalWindow;
+    }
+  });
 });
diff --git a/test/displayimage-coverage.test.js b/test/displayimage-coverage.test.js
index 17b6b7bb..620d3fae 100644
--- a/test/displayimage-coverage.test.js
+++ b/test/displayimage-coverage.test.js
@@ -91,6 +91,13 @@ describe('DisplayImage coverage', function() {
     words[0] = 0x89ABCDEF;
     display.setBackground(words);
     expect(display.buffer32[0]).to.equal(0x89ABCDEF);
+    expect(display.hasBackground()).to.equal(true);
+
+    display.drawRect(0, 0, 0, 0, 255, 0, 0, true);
+    display.commitFrameForBackgroundRestore();
+    display.buffer32[0] = 0;
+    display.restoreBackground();
+    expect(display.buffer32[0]).to.equal(0x89ABCDEF);
 
     const logs = [];
     display.log.log = (msg) => logs.push(msg);
@@ -135,9 +142,15 @@ describe('DisplayImage coverage', function() {
       offsetX: -1,
       offsetY: 0
     });
+    const maskNoOffsets = makeFrame(2, 2, {
+      mask: Uint8Array.from([1, 1, 1, 1])
+    });
+    delete maskNoOffsets.offsetX;
+    delete maskNoOffsets.offsetY;
     display.drawMask(mask, 1, 1);
     display.drawMask(mask, -10, 1);
     display.drawMask(mask, 1, -10);
+    display.drawMask(maskNoOffsets, 0, 0);
 
     const coldMaskDisplay = new DisplayImage(stage);
     coldMaskDisplay.drawMask(mask, 1, 1);
@@ -150,6 +163,25 @@ describe('DisplayImage coverage', function() {
     expect(__test__.cyrb53('abc', 1)).to.be.a('number');
   });
 
+  it('tracks and consumes dirty tiles when enabled', function() {
+    const stage = makeStage();
+    const display = new DisplayImage(stage);
+    display.initSize(8, 8);
+    display.setDirtyTileSize(4);
+
+    const background = new Uint32Array(8 * 8);
+    display.syncBackground(background, null, null, 4);
+    const fullTiles = display.consumeDirtyTiles();
+    expect(fullTiles).to.equal(null);
+
+    display.syncBackground(background, null, [{ x: 1, y: 1, width: 1, height: 1 }], 4);
+    const dirtyTiles = display.consumeDirtyTiles();
+    expect(Array.isArray(dirtyTiles)).to.equal(true);
+    expect(dirtyTiles).to.have.length(1);
+    expect(dirtyTiles[0]).to.eql({ x: 0, y: 0, width: 4, height: 4 });
+    display.releaseConsumedDirtyTiles(dirtyTiles);
+  });
+
   it('blits with span caches and per-pixel fallbacks', function() {
     const stage = makeStage();
     const display = new DisplayImage(stage);
@@ -170,9 +202,13 @@ describe('DisplayImage coverage', function() {
       offsetX: -1,
       spans
     });
+    const frameNoOffsets = makeFrame(2, 2);
+    delete frameNoOffsets.offsetX;
+    delete frameNoOffsets.offsetY;
 
     display._blit(frame, 0, 0, { checkGround: false });
     display._blit(frameNoBounds, 0, 0, { checkGround: false });
+    display._blit(frameNoOffsets, 1, 1, { checkGround: false });
     display._blit(frame, 0, 0, { checkGround: false, upsideDown: true });
     display._blit(frame, 0, -10, { checkGround: false });
 
diff --git a/test/displayimage-dashed-rect.test.js b/test/displayimage-dashed-rect.test.js
index c843ac0b..9ace9830 100644
--- a/test/displayimage-dashed-rect.test.js
+++ b/test/displayimage-dashed-rect.test.js
@@ -1,6 +1,6 @@
 import { expect } from 'chai';
 import { useGlobalLemmings } from './helpers/lemmings.js';
-import { DisplayImage } from '../js/render/DisplayImage.js';
+import { DisplayImage, __test__ } from '../js/render/DisplayImage.js';
 
 class SimpleImageData {
   constructor(width, height) {
@@ -69,4 +69,36 @@ describe('DisplayImage dashed/marching rectangles', function () {
 
     expect(Array.from(display.buffer32)).to.eql(expected);
   });
+
+  it('clips marching ant rectangles that extend outside the display bounds', function () {
+    const stage = new MockStage();
+    const display = stage.getGameDisplay();
+    display.initSize(4, 3);
+    display.clear(0);
+
+    display.drawMarchingAntRect(-1, -1, 3, 2, 2, 0, 0xFFFFFFFF, 0xFF000000);
+
+    expect(Object.prototype.hasOwnProperty.call(display.buffer32, '-1')).to.equal(false);
+    const changed = Array.from(display.buffer32).some(value => value !== 0);
+    expect(changed).to.equal(true);
+  });
+
+  it('keeps marching-ant caches collision-proof for large dimensions', function () {
+    __test__._marchingAntPerimeterCache.clear();
+    __test__._marchingAntPatternCache.clear();
+
+    const perimeterA = __test__.getMarchingAntPerimeterOffsets(2, 0, 1);
+    const perimeterB = __test__.getMarchingAntPerimeterOffsets(1, 256, 1);
+    expect(perimeterA).to.not.equal(perimeterB);
+    expect(perimeterA.length).to.equal(2);
+    expect(perimeterB.length).to.equal(514);
+    expect(__test__._marchingAntPerimeterCache.size).to.equal(2);
+
+    const patternA = __test__.getMarchingAntPaintPattern(2, 1, 0);
+    const patternB = __test__.getMarchingAntPaintPattern(1, 257, 0);
+    expect(patternA).to.not.equal(patternB);
+    expect(patternA.first.length + patternA.second.length).to.equal(2);
+    expect(patternB.first.length + patternB.second.length).to.equal(1);
+    expect(__test__._marchingAntPatternCache.size).to.equal(2);
+  });
 });
diff --git a/test/displayimage-dirty-rect.test.js b/test/displayimage-dirty-rect.test.js
new file mode 100644
index 00000000..96750302
--- /dev/null
+++ b/test/displayimage-dirty-rect.test.js
@@ -0,0 +1,60 @@
+import { expect } from 'chai';
+import { useGlobalLemmings } from './helpers/lemmings.js';
+import { DisplayImage } from '../js/render/DisplayImage.js';
+
+class SimpleImageData {
+  constructor(width, height) {
+    this.width = width;
+    this.height = height;
+    this.data = new Uint8ClampedArray(width * height * 4);
+  }
+}
+
+class MockStage {
+  createImage(_display, width, height) {
+    return new SimpleImageData(width, height);
+  }
+}
+
+describe('DisplayImage dirty rect tracking', function () {
+  useGlobalLemmings({});
+
+  it('coalesces touching dirty rects into one update region', function () {
+    const display = new DisplayImage(new MockStage());
+    display.initSize(20, 10);
+
+    display.consumeDirtyRects();
+    display.markDirtyRect(1, 1, 2, 2);
+    display.markDirtyRect(3, 1, 2, 2);
+
+    const rects = display.consumeDirtyRects();
+    expect(rects).to.deep.equal([{ x: 1, y: 1, width: 4, height: 2 }]);
+  });
+
+  it('switches to full dirty mode when merged region covers the full surface', function () {
+    const display = new DisplayImage(new MockStage());
+    display.initSize(20, 10);
+
+    display.consumeDirtyRects();
+    display.markDirtyRect(0, 0, 20, 10);
+
+    expect(display.consumeDirtyRects()).to.equal(null);
+  });
+
+  it('reuses consumed dirty-rect list buffers after release', function () {
+    const display = new DisplayImage(new MockStage());
+    display.initSize(20, 10);
+
+    display.consumeDirtyRects();
+    display.markDirtyRect(1, 1, 2, 2);
+    const first = display.consumeDirtyRects();
+    expect(first).to.have.length(1);
+    display.releaseConsumedDirtyRects(first);
+    expect(display._dirtyRectListPool.includes(first)).to.equal(true);
+
+    display.markDirtyRect(3, 3, 2, 2);
+    const second = display.consumeDirtyRects();
+    expect(second).to.deep.equal([{ x: 3, y: 3, width: 2, height: 2 }]);
+    expect(display._dirtyRects).to.equal(first);
+  });
+});
diff --git a/test/displayimage-scale-cache.test.js b/test/displayimage-scale-cache.test.js
new file mode 100644
index 00000000..606b58d4
--- /dev/null
+++ b/test/displayimage-scale-cache.test.js
@@ -0,0 +1,70 @@
+import { expect } from 'chai';
+import { Frame } from '../js/render/Frame.js';
+import { __test__ as displayImageTest } from '../js/render/DisplayImage.js';
+
+describe('DisplayImage scale cache', function () {
+  it('reuses scaled buffers for matching frame/version/size and invalidates on frame edits', function () {
+    const frame = new Frame(2, 2);
+    frame.setPixel(0, 0, 0xff00ffff);
+    frame.setPixel(1, 0, 0xff0000ff);
+    frame.setPixel(0, 1, 0xff00ff00);
+    frame.setPixel(1, 1, 0xffffffff);
+
+    const a = displayImageTest.getScaledFrameVariant(frame, 4, 4, 'xbrz');
+    const b = displayImageTest.getScaledFrameVariant(frame, 4, 4, 'xbrz');
+    expect(a).to.equal(b);
+    expect(a.scaled).to.be.instanceof(Uint32Array);
+    expect(a.scaledMask).to.be.instanceof(Uint8Array);
+    expect(a.scaled.length).to.equal(16);
+    expect(a.scaledMask.length).to.equal(16);
+
+    frame.setPixel(0, 0, 0xff112233);
+    const c = displayImageTest.getScaledFrameVariant(frame, 4, 4, 'xbrz');
+    expect(c).to.not.equal(a);
+  });
+
+  it('returns null for unsupported target dimensions', function () {
+    const frame = new Frame(2, 2);
+    const variant = displayImageTest.getScaledFrameVariant(frame, 5, 5, 'xbrz');
+    expect(variant).to.equal(null);
+  });
+
+  it('evicts by least-recently-used variant access', function () {
+    const frame = new Frame(2, 2);
+    const initial = new Map();
+
+    for (let version = 1; version <= 8; version += 1) {
+      frame._version = version;
+      initial.set(version, displayImageTest.getScaledFrameVariant(frame, 4, 4, 'xbrz'));
+    }
+
+    frame._version = 1;
+    const touched = displayImageTest.getScaledFrameVariant(frame, 4, 4, 'xbrz');
+    expect(touched).to.equal(initial.get(1));
+
+    frame._version = 9;
+    displayImageTest.getScaledFrameVariant(frame, 4, 4, 'xbrz');
+
+    frame._version = 1;
+    const stillCached = displayImageTest.getScaledFrameVariant(frame, 4, 4, 'xbrz');
+    expect(stillCached).to.equal(initial.get(1));
+
+    frame._version = 2;
+    const evicted = displayImageTest.getScaledFrameVariant(frame, 4, 4, 'xbrz');
+    expect(evicted).to.not.equal(initial.get(2));
+  });
+
+  it('reuses nearest-coordinate maps and evicts old cache entries', function () {
+    const first = displayImageTest.getNearestCoordinateMap(2, 4);
+    const second = displayImageTest.getNearestCoordinateMap(2, 4);
+    expect(first).to.equal(second);
+    expect(Array.from(first)).to.eql([0, 0, 1, 1]);
+
+    for (let i = 0; i < 300; i += 1) {
+      displayImageTest.getNearestCoordinateMap(3 + i, 6 + i);
+    }
+    const refreshed = displayImageTest.getNearestCoordinateMap(2, 4);
+    expect(refreshed).to.not.equal(null);
+    expect(displayImageTest._nearestCoordinateCache.size).to.be.at.most(256);
+  });
+});
diff --git a/test/docs-checkpoint-guidance.test.js b/test/docs-checkpoint-guidance.test.js
new file mode 100644
index 00000000..4abe3089
--- /dev/null
+++ b/test/docs-checkpoint-guidance.test.js
@@ -0,0 +1,54 @@
+import { expect } from 'chai';
+import fs from 'node:fs';
+
+const readText = (path) => fs.readFileSync(path, 'utf8');
+
+const extractNpmScripts = (markdown) => {
+  const scripts = new Set();
+  const commandRegex = /`(npm(?: run)? [^`]+?)`/g;
+  for (const match of markdown.matchAll(commandRegex)) {
+    const command = match[1].trim();
+    if (command === 'npm test' || command.startsWith('npm test ')) {
+      scripts.add('test');
+      continue;
+    }
+    const scriptMatch = command.match(/^npm run ([^\s`]+)/);
+    if (scriptMatch) scripts.add(scriptMatch[1]);
+  }
+  return scripts;
+};
+
+describe('milestone checkpoint guidance docs', function() {
+  it('keeps documented npm commands aligned with package scripts', function() {
+    const packageJson = JSON.parse(readText('package.json'));
+    const documentedScripts = new Set([
+      ...extractNpmScripts(readText('docs/TESTING.md')),
+      ...extractNpmScripts(readText('docs/playwright-tests.md'))
+    ]);
+
+    for (const script of documentedScripts) {
+      expect(packageJson.scripts, `missing package script ${script}`).to.have.property(script);
+    }
+  });
+
+  it('documents the disposable milestone capture and closeout contract', function() {
+    const testingDoc = readText('docs/TESTING.md');
+    const playwrightDoc = readText('docs/playwright-tests.md');
+
+    expect(testingDoc).to.contain('## Milestone checkpoint evidence');
+    expect(testingDoc).to.contain('Issues:');
+    expect(testingDoc).to.contain('Skipped checks:');
+    expect(testingDoc).to.contain('Follow-up risks:');
+    expect(playwrightDoc).to.contain('## Milestone Capture Matrix');
+    for (const script of [
+      'capture:e2e:midi',
+      'capture:e2e:editor',
+      'capture:e2e:procgen',
+      'capture:e2e:game-hud'
+    ]) {
+      expect(playwrightDoc).to.contain(`npm run ${script}`);
+    }
+    expect(playwrightDoc).to.contain('temp/e2e-captures/');
+    expect(playwrightDoc).to.contain('do not commit screenshots');
+  });
+});
diff --git a/test/dom-resolver.test.js b/test/dom-resolver.test.js
new file mode 100644
index 00000000..7a67d932
--- /dev/null
+++ b/test/dom-resolver.test.js
@@ -0,0 +1,48 @@
+import { expect } from 'chai';
+import {
+  detectEmbedMode,
+  resolveRequiredElements
+} from '../js/app/domResolver.js';
+
+describe('domResolver', function () {
+  it('detects embed mode from query and dataset flags', function () {
+    const queryMode = detectEmbedMode({
+      windowRef: { location: { search: '?embed=1' } },
+      documentRef: null
+    });
+    expect(queryMode).to.equal(true);
+
+    const datasetMode = detectEmbedMode({
+      windowRef: { location: { search: '' } },
+      documentRef: { body: { dataset: { embedMode: 'true' } } }
+    });
+    expect(datasetMode).to.equal(true);
+
+    const defaultMode = detectEmbedMode({
+      windowRef: { location: { search: '' } },
+      documentRef: { body: { dataset: {} }, documentElement: { dataset: {} } }
+    });
+    expect(defaultMode).to.equal(false);
+  });
+
+  it('throws explicit DomResolutionError for missing required ids', function () {
+    const doc = {
+      getElementById() {
+        return null;
+      }
+    };
+    let thrown = null;
+    try {
+      resolveRequiredElements(doc, ['gameCanvas', 'levelIndexSelect'], {
+        context: 'boot',
+        embedMode: true
+      });
+    } catch (error) {
+      thrown = error;
+    }
+    expect(thrown).to.not.equal(null);
+    expect(thrown.name).to.equal('DomResolutionError');
+    expect(thrown.embedMode).to.equal(true);
+    expect(thrown.missingIds).to.deep.equal(['gameCanvas', 'levelIndexSelect']);
+  });
+});
diff --git a/test/e2e-capture-rects-script.test.js b/test/e2e-capture-rects-script.test.js
new file mode 100644
index 00000000..a9095dc0
--- /dev/null
+++ b/test/e2e-capture-rects-script.test.js
@@ -0,0 +1,47 @@
+import { expect } from 'chai';
+import {
+  npmConfigArgsFromEnv,
+  parseCliArgs
+} from '../scripts/e2e-capture-rects.js';
+
+describe('scripts/e2e-capture-rects', function() {
+  it('accepts npm run forwarded config values for capture filters', function() {
+    const env = {
+      npm_config_base_url: 'https://localhost:9090',
+      npm_config_out_dir: 'temp/e2e-captures/focused',
+      npm_config_viewport: 'tablet',
+      npm_config_target: 'midi-output-status,midi-inspector',
+      npm_config_json: 'true'
+    };
+
+    expect(npmConfigArgsFromEnv(env)).to.deep.equal([
+      '--base-url=https://localhost:9090',
+      '--out-dir=temp/e2e-captures/focused',
+      '--viewport=tablet',
+      '--target=midi-output-status,midi-inspector',
+      '--json'
+    ]);
+
+    const parsed = parseCliArgs([], env);
+    expect(parsed.baseUrl).to.equal('https://localhost:9090');
+    expect(parsed.outDir).to.equal('temp/e2e-captures/focused');
+    expect(parsed.viewport).to.equal('tablet');
+    expect(parsed.targets).to.deep.equal(['midi-output-status', 'midi-inspector']);
+    expect(parsed.json).to.equal(true);
+  });
+
+  it('lets explicit capture CLI options override npm config values', function() {
+    const parsed = parseCliArgs([
+      '--viewport=mobile',
+      '--target=midi-source-browser',
+      '--json'
+    ], {
+      npm_config_viewport: 'tablet',
+      npm_config_target: 'midi-output-status'
+    });
+
+    expect(parsed.viewport).to.equal('mobile');
+    expect(parsed.targets).to.deep.equal(['midi-output-status', 'midi-source-browser']);
+    expect(parsed.json).to.equal(true);
+  });
+});
diff --git a/test/e2e-harness.diagnostics.test.js b/test/e2e-harness.diagnostics.test.js
new file mode 100644
index 00000000..faa81133
--- /dev/null
+++ b/test/e2e-harness.diagnostics.test.js
@@ -0,0 +1,123 @@
+import { expect } from 'chai';
+import { installE2EHarness } from '../js/app/e2eHarness.js';
+
+const preserveGlobal = (name) => {
+  const had = Object.prototype.hasOwnProperty.call(globalThis, name);
+  const value = globalThis[name];
+  return () => {
+    if (had) {
+      Object.defineProperty(globalThis, name, {
+        configurable: true,
+        writable: true,
+        value
+      });
+    } else {
+      delete globalThis[name];
+    }
+  };
+};
+
+describe('e2e harness diagnostics', function () {
+  it('returns deterministic diagnostics from getState/getDiagnostics', async function () {
+    const restoreWindow = preserveGlobal('window');
+    const restoreDocument = preserveGlobal('document');
+    const restoreNavigator = preserveGlobal('navigator');
+    const restoreCaches = preserveGlobal('caches');
+    const restoreE2E = preserveGlobal('__E2E__');
+    try {
+      Object.defineProperty(globalThis, 'window', {
+        configurable: true,
+        writable: true,
+        value: {
+          location: {
+            search: '?e2e=1',
+            protocol: 'https:',
+            hostname: 'example.com',
+            pathname: '/index.html'
+          }
+        }
+      });
+      Object.defineProperty(globalThis, 'document', {
+        configurable: true,
+        writable: true,
+        value: {
+          getElementById() {
+            return null;
+          }
+        }
+      });
+      Object.defineProperty(globalThis, 'navigator', {
+        configurable: true,
+        writable: true,
+        value: {
+          serviceWorker: {
+            controller: { scriptURL: 'sw.js' }
+          }
+        }
+      });
+      Object.defineProperty(globalThis, 'caches', {
+        configurable: true,
+        writable: true,
+        value: {
+          async keys() {
+            return ['z-cache', 'a-cache'];
+          }
+        }
+      });
+
+      const view = {
+        getRuntimeDiagnostics() {
+          return {
+            profile: 'perf',
+            rolloutFlags: {
+              historyCodec: false,
+              renderPresentPath: true
+            },
+            capabilities: {
+              webMidi: { supported: false, enabled: false, fallbackPath: 'audio_only' },
+              renderPaths: {
+                presentPathSupported: false,
+                workerOffscreenSupported: false,
+                deterministicFallback: 'canvas2d_main_thread'
+              }
+            },
+            featureFlags: {
+              debug: true,
+              midiEnabled: true
+            },
+            caches: {
+              fileProvider: {
+                memoryEntries: 3,
+                localStorageBytes: 10,
+                indexedDbBytes: 11
+              }
+            }
+          };
+        }
+      };
+
+      const api = installE2EHarness({ view });
+      const state = api.getState();
+      expect(state.diagnostics).to.not.equal(null);
+      expect(state.diagnostics.profile).to.equal('perf');
+      expect(state.diagnostics.rolloutFlags.historyCodec).to.equal(false);
+      expect(state.diagnostics.capabilities.webMidi.supported).to.equal(false);
+      expect(state.diagnostics.caches.fileProvider.memoryEntries).to.equal(3);
+      expect(state.diagnostics.caches.cacheStorageKeys).to.equal(null);
+      expect(state.diagnostics.serviceWorker.controlled).to.equal(true);
+
+      const diagnostics = await api.getDiagnostics();
+      expect(diagnostics.caches.cacheStorageKeys).to.deep.equal(['a-cache', 'z-cache']);
+      expect(diagnostics.location.hostname).to.equal('example.com');
+      expect(diagnostics.featureFlags.debug).to.equal(true);
+      expect(diagnostics.rolloutFlags.renderPresentPath).to.equal(true);
+      expect(diagnostics.capabilities.renderPaths.deterministicFallback).to.equal('canvas2d_main_thread');
+    } finally {
+      restoreE2E();
+      restoreCaches();
+      restoreNavigator();
+      restoreDocument();
+      restoreWindow();
+    }
+  });
+});
diff --git a/test/editor-ui-format.test.js b/test/editor-ui-format.test.js
new file mode 100644
index 00000000..befc9374
--- /dev/null
+++ b/test/editor-ui-format.test.js
@@ -0,0 +1,35 @@
+import { expect } from 'chai';
+import {
+  formatRotation,
+  formatValue,
+  normalizeRotation,
+  normalizeText,
+  parseNumber,
+  sanitizeFileName
+} from '../js/app/editor-ui/editorUiFormat.js';
+
+describe('editorUiFormat', function () {
+  it('normalizes text and parses nullable numbers', function () {
+    expect(normalizeText('  level  ')).to.equal('level');
+    expect(parseNumber('42')).to.equal(42);
+    expect(parseNumber('')).to.equal(null);
+    expect(parseNumber(null)).to.equal(null);
+    expect(parseNumber('x')).to.equal(null);
+  });
+
+  it('normalizes and formats rotations', function () {
+    expect(normalizeRotation('91')).to.equal(90);
+    expect(normalizeRotation('-10')).to.equal(0);
+    expect(normalizeRotation('181')).to.equal(180);
+    expect(normalizeRotation(null)).to.equal(null);
+    expect(formatRotation('450')).to.equal('90');
+    expect(formatRotation('')).to.equal('');
+  });
+
+  it('formats values and sanitizes file names', function () {
+    expect(formatValue(null)).to.equal('');
+    expect(formatValue(7)).to.equal('7');
+    expect(sanitizeFileName('  Hello World!.nxlv  ')).to.equal('Hello_World_nxlv');
+    expect(sanitizeFileName('___')).to.equal('level');
+  });
+});
diff --git a/test/editor/classic-level-converter.test.js b/test/editor/classic-level-converter.test.js
index e2ea352d..79274635 100644
--- a/test/editor/classic-level-converter.test.js
+++ b/test/editor/classic-level-converter.test.js
@@ -128,6 +128,7 @@ describe('ClassicLevelConverter', () => {
     expect(terrain.props.FLIP_VERTICAL).to.equal(true);
     expect(terrain.props.NO_OVERWRITE).to.equal(true);
     expect(terrain.props.ERASE).to.equal(true);
+    expect(terrain.props).to.not.have.property('ONE_WAY');
     const gadget = level.gadgets[0];
     expect(gadget.props.FLIP_VERTICAL).to.equal(undefined);
   });
diff --git a/test/editor/editor-controller.01-editorcontroller.test.js b/test/editor/editor-controller.01-editorcontroller.test.js
new file mode 100644
index 00000000..c5d70d3f
--- /dev/null
+++ b/test/editor/editor-controller.01-editorcontroller.test.js
@@ -0,0 +1,429 @@
+import { expect } from 'chai';
+import FakeTimers from '@sinonjs/fake-timers';
+import { EditorController, __test__ } from '../../js/editor/EditorController.js';
+import { EditorSession } from '../../js/editor/EditorSession.js';
+import { EditorLevel } from '../../js/editor/EditorLevel.js';
+import { EditorTools } from '../../js/editor/EditorTools.js';
+import { createTerrainEntry, createGadgetEntry, createSteelEntry } from '../../js/editor/EditorEntryFactory.js';
+
+class FakeHistory {
+  constructor() {
+    this.clearCount = 0;
+    this.snapshots = [];
+    this.undoValue = null;
+    this.redoValue = null;
+    this.beginLabels = [];
+    this.endLabels = [];
+    this.cancelCount = 0;
+  }
+
+  clear() {
+    this.clearCount += 1;
+  }
+
+  pushSnapshot(level, label) {
+    this.snapshots.push({ level, label });
+    return true;
+  }
+
+  undo() {
+    return this.undoValue;
+  }
+
+  redo() {
+    return this.redoValue;
+  }
+
+  beginTransaction(label) {
+    this.beginLabels.push(label);
+  }
+
+  endTransaction(label) {
+    this.endLabels.push(label);
+    return true;
+  }
+
+  cancelTransaction() {
+    this.cancelCount += 1;
+    return true;
+  }
+}
+
+const buildSession = () => {
+  const session = new EditorSession();
+  const level = new EditorLevel();
+  level.setHeader('STYLE', 'dirt');
+  level.terrains = [];
+  level.gadgets = [];
+  session.level = level;
+  return session;
+};
+
+const buildAssets = () => {
+  const terrainMeta = { id: 2, name: 'terrain_2', width: 8, height: 8 };
+  const gadgetMeta = { id: 1, name: 'object_1', width: 8, height: 8, triggerEffectId: 0 };
+  const triggerMeta = { id: 3, name: 'object_3', width: 8, height: 8, triggerEffectId: 5 };
+  const exitMeta = { id: 4, name: 'object_4', width: 8, height: 8, triggerEffectId: 0 };
+  return {
+    terrain: [terrainMeta],
+    gadgets: [gadgetMeta],
+    triggers: [triggerMeta],
+    entranceId: 1,
+    exitId: 4,
+    terrainById: new Map([[terrainMeta.id, terrainMeta]]),
+    gadgetById: new Map([
+      [gadgetMeta.id, gadgetMeta],
+      [triggerMeta.id, triggerMeta],
+      [exitMeta.id, exitMeta]
+    ])
+  };
+};
+
+describe('EditorController', () => {
+  it('initializes selections and debounces preview updates', () => {
+    const session = buildSession();
+    const history = new FakeHistory();
+    const controller = new EditorController({ session, history, previewDelay: 5 });
+    controller.setAssets(buildAssets());
+
+    expect(controller.selectedTerrainId).to.equal(2);
+    expect(controller.selectedGadgetId).to.equal(1);
+    expect(controller.selectedTriggerId).to.equal(3);
+
+    const levelEvents = [];
+    const previewEvents = [];
+    const clock = FakeTimers.install({ now: 0, toFake: ['setTimeout', 'clearTimeout', 'Date'] });
+    controller.setCallbacks({
+      onLevelChange: level => levelEvents.push(level),
+      onPreviewRequest: label => previewEvents.push(label)
+    });
+
+    controller.updateHeader('TITLE', 'First');
+    controller.updateHeader('TITLE', 'Second');
+    expect(levelEvents).to.have.length(2);
+    expect(previewEvents).to.deep.equal([]);
+
+    clock.tick(5);
+    expect(previewEvents).to.deep.equal(['Header']);
+    clock.uninstall();
+
+    controller.resetHistory('Init');
+    expect(history.clearCount).to.equal(1);
+    expect(history.snapshots[0].label).to.equal('Init');
+  });
+
+  it('dispatches pending preview requests to the latest callback', () => {
+    const session = buildSession();
+    const history = new FakeHistory();
+    const controller = new EditorController({ session, history, previewDelay: 5 });
+    controller.setAssets(buildAssets());
+
+    const firstPreviewEvents = [];
+    const secondPreviewEvents = [];
+    const clock = FakeTimers.install({ now: 0, toFake: ['setTimeout', 'clearTimeout', 'Date'] });
+
+    controller.setCallbacks({
+      onPreviewRequest: label => firstPreviewEvents.push(label)
+    });
+    controller.updateHeader('TITLE', 'Queued');
+    controller.setCallbacks({
+      onPreviewRequest: label => secondPreviewEvents.push(label)
+    });
+
+    clock.tick(5);
+    expect(firstPreviewEvents).to.deep.equal([]);
+    expect(secondPreviewEvents).to.deep.equal(['Header']);
+    clock.uninstall();
+  });
+
+  it('selects, drags, and clears selections', () => {
+    const session = buildSession();
+    const history = new FakeHistory();
+    const controller = new EditorController({ session, history });
+    controller.setAssets(buildAssets());
+
+    const terrainEntry = createTerrainEntry({ styleName: 'dirt', piece: 2, x: 10, y: 10 });
+    session.level.terrains.push(terrainEntry);
+
+    const selections = [];
+    controller.setCallbacks({ onSelectionChange: selection => selections.push(selection) });
+
+    controller.handlePointerDown({ x: 12, y: 12 }, 0);
+    expect(controller.getSelectedEntries()).to.have.length(1);
+    expect(controller.getSelectedEntries()[0].type).to.equal('terrain');
+
+    controller.handlePointerMove({ x: 20, y: 20 });
+    expect(terrainEntry.props.X).to.equal(18);
+    expect(terrainEntry.props.Y).to.equal(18);
+
+    controller.handlePointerUp();
+    expect(history.snapshots[0].label).to.equal('Move');
+    expect(selections.length).to.be.greaterThan(0);
+
+    const gadgetEntry = createGadgetEntry({ styleName: 'dirt', piece: 1, x: 30, y: 30 });
+    session.level.gadgets.push(gadgetEntry);
+    controller.handlePointerDown({ x: 31, y: 31 }, 0);
+    controller.handlePointerMove({ x: 40, y: 40 });
+    controller.handlePointerUp();
+
+    controller.handlePointerDown({ x: 0, y: 0 }, 2);
+    expect(controller.getSelectedEntries()).to.have.length(0);
+
+    controller.handlePointerDown({ x: 100, y: 100 }, 0);
+    expect(controller.getSelectedEntries()).to.have.length(0);
+
+    controller._selectHit(null);
+    expect(controller.getSelectedEntries()).to.have.length(0);
+  });
+
+  it('places terrain, gadgets, triggers, entrances, and exits', () => {
+    const session = buildSession();
+    const history = new FakeHistory();
+    const controller = new EditorController({ session, history, snapEnabled: false });
+    controller.setAssets(buildAssets());
+    controller.setSnapEnabled(false);
+
+    controller.setSelectedTerrain(2);
+    controller.setSelectedTerrain('bad');
+    controller.setTool(EditorTools.TERRAIN);
+    controller.handlePointerDown({ x: 5.2, y: 6.2 }, 0);
+    expect(session.level.terrains).to.have.length(1);
+    expect(session.level.terrains[0].props.X).to.equal(1);
+    expect(history.snapshots[0].label).to.equal('Terrain');
+
+    controller.setSelectedGadget(1);
+    controller.setSelectedGadget(undefined);
+    controller.setTool(EditorTools.GADGET);
+    controller.handlePointerDown({ x: 10, y: 12 }, 0);
+    expect(session.level.gadgets).to.have.length(1);
+    expect(history.snapshots[1].label).to.equal('Gadget');
+
+    controller.setSelectedTrigger(3);
+    controller.setTool(EditorTools.TRIGGER);
+    controller.handlePointerDown({ x: 14, y: 16 }, 0);
+    expect(session.level.gadgets[1].props.PIECE).to.equal(3);
+
+    controller.setSelectedTrigger('bad');
+    controller.selectedTriggerId = null;
+    controller.setTool(EditorTools.TRIGGER);
+    controller.handlePointerDown({ x: 18, y: 20 }, 0);
+    expect(session.level.gadgets[2].props.PIECE).to.equal(1);
+
+    controller.setSelectedTrigger(3);
+    controller.setTool(EditorTools.MIDI_FLAG);
+    controller.handlePointerDown({ x: 22, y: 24 }, 0);
+    const midiFlagEntry = session.level.gadgets[3];
+    expect(midiFlagEntry.props.PIECE).to.equal(3);
+    expect(midiFlagEntry.props.MIDI_FLAG).to.equal(true);
+    expect(Number.isFinite(midiFlagEntry.props.MIDI_FLAG_ID)).to.equal(true);
+
+    for (let i = 0; i < 4; i++) {
+      session.level.gadgets.push(createGadgetEntry({ styleName: 'dirt', piece: 1, x: 1, y: 1 }));
+    }
+    controller.setTool(EditorTools.ENTRANCE);
+    controller.handlePointerDown({ x: 30, y: 40 }, 0);
+    const entranceCount = session.level.gadgets.filter(entry => entry.props.PIECE === 1).length;
+    expect(entranceCount).to.equal(4);
+
+    for (let i = 0; i < 4; i++) {
+      session.level.gadgets.push(createGadgetEntry({ styleName: 'dirt', piece: 4, x: 2, y: 2 }));
+    }
+    controller.setTool(EditorTools.EXIT);
+    controller.handlePointerDown({ x: 32, y: 44 }, 0);
+    const exitCount = session.level.gadgets.filter(entry => entry.props.PIECE === 4).length;
+    expect(exitCount).to.equal(4);
+
+    controller.setTool('unknown');
+    controller.handlePointerDown({ x: 0, y: 0 }, 0);
+  });
+
+  it('handles brush and eraser strokes', () => {
+    const session = buildSession();
+    const history = new FakeHistory();
+    const controller = new EditorController({ session, history, eraseGadgets: true });
+    controller.setAssets(buildAssets());
+
+    controller.setBrushSize(0);
+    expect(controller.brushSize).to.equal(1);
+    controller.setBrushSize(Number.NaN);
+    expect(controller.brushSize).to.equal(1);
+
+    controller.setTool(EditorTools.BRUSH);
+    controller.setBrushSize(2);
+    controller.handlePointerDown({ x: 5, y: 6 }, 0);
+    const countAfterDown = session.level.terrains.length;
+    controller.handlePointerMove({ x: 5, y: 6 }, { isDown: true });
+    controller.handlePointerMove({ x: 5, y: 6 }, { isDown: false });
+    expect(session.level.terrains).to.have.length(countAfterDown);
+    controller.handlePointerUp();
+    expect(history.snapshots[0].label).to.equal('Brush');
+
+    controller.setTool(EditorTools.ERASER);
+    controller.setEraseGadgets(true);
+    session.level.gadgets.push(createGadgetEntry({ styleName: 'dirt', piece: 1, x: 4, y: 4 }));
+    const terrainCount = session.level.terrains.length;
+    controller.handlePointerDown({ x: 4, y: 4 }, 0);
+    expect(session.level.terrains.length).to.be.lessThan(terrainCount);
+    expect(session.level.gadgets).to.have.length(0);
+    controller.handlePointerMove({ x: 4, y: 4 }, { isDown: true });
+    controller.handlePointerUp();
+    expect(history.snapshots.some(entry => entry.label === 'Erase')).to.equal(true);
+  });
+
+  it('coalesces long brush drags into one committed history snapshot', () => {
+    const session = buildSession();
+    const history = new FakeHistory();
+    const controller = new EditorController({ session, history, snapEnabled: false, gridSize: 1 });
+    controller.setAssets(buildAssets());
+    controller.setTool(EditorTools.BRUSH);
+
+    controller.handlePointerDown({ x: 0, y: 0 }, 0);
+    for (let i = 1; i <= 64; i += 1) {
+      controller.handlePointerMove({ x: i, y: i % 8 }, { isDown: true });
+    }
+    controller.handlePointerUp();
+
+    expect(history.snapshots.filter(entry => entry.label === 'Brush')).to.have.length(1);
+    expect(session.level.terrains.length).to.be.greaterThan(10);
+  });
+
+  it('stamps brush lines', () => {
+    const session = buildSession();
+    const controller = new EditorController({ session, gridSize: 4, snapEnabled: true });
+    controller.setAssets(buildAssets());
+    controller.setTool(EditorTools.BRUSH);
+    controller.setBrushSize(1);
+    controller.handlePointerDown({ x: 0, y: 0 }, 0);
+    controller.handlePointerMove({ x: 8, y: 0 }, { isDown: true });
+    controller.handlePointerUp();
+    expect(session.level.terrains).to.have.length(3);
+  });
+
+  it('stamps brush and eraser moves without a prior stroke', () => {
+    const session = buildSession();
+    const controller = new EditorController({ session, snapEnabled: false });
+    controller.setAssets(buildAssets());
+
+    controller.setTool(EditorTools.BRUSH);
+    const beforeBrush = session.level.terrains.length;
+    controller.handlePointerMove({ x: 6, y: 6 }, { isDown: true });
+    expect(session.level.terrains).to.have.length(beforeBrush + 1);
+    controller.handlePointerUp();
+
+    controller.setTool(EditorTools.ERASER);
+    const beforeErase = session.level.terrains.length;
+    controller.handlePointerMove({ x: 6, y: 6 }, { isDown: true });
+    expect(session.level.terrains.length).to.be.lessThan(beforeErase);
+  });
+
+  it('supports multi-select and marquee selection', () => {
+    const session = buildSession();
+    const history = new FakeHistory();
+    const controller = new EditorController({ session, history, snapEnabled: false });
+    controller.setAssets(buildAssets());
+    controller.setTool(EditorTools.SELECT);
+    const selectionEvents = [];
+    controller.setCallbacks({ onSelectionChange: selection => selectionEvents.push(selection) });
+
+    const entryA = createTerrainEntry({ styleName: 'dirt', piece: 2, x: 10, y: 10 });
+    const entryB = createTerrainEntry({ styleName: 'dirt', piece: 2, x: 30, y: 30 });
+    session.level.terrains.push(entryA, entryB);
+
+    controller.handlePointerDown({ x: 10, y: 10 }, 0);
+    controller.handlePointerUp();
+    controller.handlePointerDown({ x: 30, y: 30 }, 0, { shiftKey: true });
+    expect(controller.getSelectedEntries()).to.have.length(2);
+
+    controller.handlePointerDown({ x: 10, y: 10 }, 0);
+    controller.handlePointerMove({ x: 20, y: 20 });
+    controller.handlePointerUp();
+    expect(entryA.props.X).to.equal(20);
+    expect(entryB.props.X).to.equal(40);
+
+    controller.handlePointerDown({ x: 0, y: 0 }, 0);
+    controller.handlePointerMove({ x: 50, y: 50 }, { isDown: true });
+    controller.handlePointerUp();
+    expect(controller.getSelectedEntries()).to.have.length(2);
+    controller.handlePointerDown({ x: 20, y: 20 }, 0, { shiftKey: true });
+    expect(controller.getSelectedEntries()).to.have.length(1);
+    expect(selectionEvents.length).to.be.greaterThan(0);
+  });
+
+  it('supports steel placement and selection', () => {
+    const session = buildSession();
+    const history = new FakeHistory();
+    session.level.steel = null;
+    const controller = new EditorController({ session, history, snapEnabled: false, gridSize: 1 });
+    controller.setAssets(buildAssets());
+    const selectionEvents = [];
+    controller.setCallbacks({ onSelectionChange: entries => selectionEvents.push(entries) });
+    controller.setTool(EditorTools.STEEL);
+    controller.handlePointerDown({ x: 5, y: 6 }, 0);
+    controller.handlePointerMove({ x: 9, y: 10 });
+    controller.handlePointerUp();
+    expect(session.level.steel).to.have.length(1);
+    expect(selectionEvents.length).to.be.greaterThan(0);
+    expect(history.snapshots.some(entry => entry.label === 'Steel')).to.equal(true);
+
+    const steelHit = controller._findSelectionAt(6, 7);
+    expect(steelHit?.type).to.equal('steel');
+
+    controller.setTool(EditorTools.SELECT);
+    controller.handlePointerDown({ x: 6, y: 7 }, 0);
+    expect(controller.getSelectedEntries()[0].type).to.equal('steel');
+    expect(controller.deleteSelected()).to.equal(true);
+    expect(session.level.steel).to.have.length(0);
+  });
+
+  it('uses a 1px steel size when the grid is invalid', () => {
+    const session = buildSession();
+    session.level.steel = null;
+    const controller = new EditorController({ session, snapEnabled: false, gridSize: 0 });
+    controller.setAssets(buildAssets());
+    controller.setTool(EditorTools.STEEL);
+    controller.handlePointerDown({ x: 1, y: 2 }, 0);
+    controller.handlePointerUp();
+    expect(session.level.steel[0].props.WIDTH).to.equal(1);
+    expect(session.level.steel[0].props.HEIGHT).to.equal(1);
+  });
+
+  it('computes selection bounds for gadgets', () => {
+    const session = buildSession();
+    const controller = new EditorController({ session, snapEnabled: false });
+    controller.setAssets(buildAssets());
+    session.level.gadgets.push(createGadgetEntry({ styleName: 'dirt', piece: 1, x: 12, y: 14 }));
+    controller.selection = [{ type: 'gadget', index: 0 }];
+    const bounds = controller.getSelectionBounds();
+    expect(bounds.x).to.equal(12);
+    expect(bounds.y).to.equal(14);
+    expect(bounds.width).to.equal(8);
+  });
+
+  it('copies, pastes, duplicates, and nudges selections', () => {
+    const session = buildSession();
+    const history = new FakeHistory();
+    const controller = new EditorController({ session, history, gridSize: 4, snapEnabled: true });
+    controller.setAssets(buildAssets());
+
+    const terrainEntry = createTerrainEntry({ styleName: 'dirt', piece: 2, x: 8, y: 8 });
+    session.level.terrains.push(terrainEntry);
+    controller.selection = [{ type: 'terrain', index: 0 }];
+
+    expect(controller.copySelection()).to.equal(true);
+    expect(controller.pasteSelection()).to.equal(true);
+    expect(session.level.terrains).to.have.length(2);
+    expect(session.level.terrains[1].props.X).to.equal(12);
+
+    controller.selection = [{ type: 'terrain', index: 1 }];
+    expect(controller.duplicateSelection()).to.equal(true);
+    expect(session.level.terrains).to.have.length(3);
+    expect(session.level.terrains[2].props.X).to.equal(16);
+
+    controller.selection = [{ type: 'terrain', index: 2 }];
+    expect(controller.nudgeSelection(1, 0, 1)).to.equal(true);
+    expect(session.level.terrains[2].props.X).to.equal(17);
+
+    expect(controller.snapSelectionToGrid()).to.equal(true);
+    expect(session.level.terrains[2].props.X).to.equal(16);
+  });
+});
diff --git a/test/editor/editor-controller.02-editorcontroller.test.js b/test/editor/editor-controller.02-editorcontroller.test.js
new file mode 100644
index 00000000..a23778c0
--- /dev/null
+++ b/test/editor/editor-controller.02-editorcontroller.test.js
@@ -0,0 +1,430 @@
+import { expect } from 'chai';
+import FakeTimers from '@sinonjs/fake-timers';
+import { EditorController, __test__ } from '../../js/editor/EditorController.js';
+import { EditorSession } from '../../js/editor/EditorSession.js';
+import { EditorLevel } from '../../js/editor/EditorLevel.js';
+import { EditorTools } from '../../js/editor/EditorTools.js';
+import { createTerrainEntry, createGadgetEntry, createSteelEntry } from '../../js/editor/EditorEntryFactory.js';
+
+class FakeHistory {
+  constructor() {
+    this.clearCount = 0;
+    this.snapshots = [];
+    this.undoValue = null;
+    this.redoValue = null;
+    this.beginLabels = [];
+    this.endLabels = [];
+    this.cancelCount = 0;
+  }
+
+  clear() {
+    this.clearCount += 1;
+  }
+
+  pushSnapshot(level, label) {
+    this.snapshots.push({ level, label });
+    return true;
+  }
+
+  undo() {
+    return this.undoValue;
+  }
+
+  redo() {
+    return this.redoValue;
+  }
+
+  beginTransaction(label) {
+    this.beginLabels.push(label);
+  }
+
+  endTransaction(label) {
+    this.endLabels.push(label);
+    return true;
+  }
+
+  cancelTransaction() {
+    this.cancelCount += 1;
+    return true;
+  }
+}
+
+const buildSession = () => {
+  const session = new EditorSession();
+  const level = new EditorLevel();
+  level.setHeader('STYLE', 'dirt');
+  level.terrains = [];
+  level.gadgets = [];
+  session.level = level;
+  return session;
+};
+
+const buildAssets = () => {
+  const terrainMeta = { id: 2, name: 'terrain_2', width: 8, height: 8 };
+  const gadgetMeta = { id: 1, name: 'object_1', width: 8, height: 8, triggerEffectId: 0 };
+  const triggerMeta = { id: 3, name: 'object_3', width: 8, height: 8, triggerEffectId: 5 };
+  const exitMeta = { id: 4, name: 'object_4', width: 8, height: 8, triggerEffectId: 0 };
+  return {
+    terrain: [terrainMeta],
+    gadgets: [gadgetMeta],
+    triggers: [triggerMeta],
+    entranceId: 1,
+    exitId: 4,
+    terrainById: new Map([[terrainMeta.id, terrainMeta]]),
+    gadgetById: new Map([
+      [gadgetMeta.id, gadgetMeta],
+      [triggerMeta.id, triggerMeta],
+      [exitMeta.id, exitMeta]
+    ])
+  };
+};
+
+describe('EditorController', () => {
+  it('applies batch selection actions for align, distribute, replace, and randomize', () => {
+    const session = buildSession();
+    const history = new FakeHistory();
+    const controller = new EditorController({ session, history, snapEnabled: false });
+    const assets = buildAssets();
+    assets.terrain.push({ id: 7, name: 'terrain_7', width: 16, height: 16 });
+    assets.terrainById.set(7, assets.terrain[1]);
+    controller.setAssets(assets);
+
+    const t0 = createTerrainEntry({ styleName: 'dirt', piece: 2, x: 0, y: 0 });
+    const t1 = createTerrainEntry({ styleName: 'dirt', piece: 2, x: 20, y: 10 });
+    const t2 = createTerrainEntry({ styleName: 'dirt', piece: 2, x: 40, y: 30 });
+    session.level.terrains.push(t0, t1, t2);
+    controller._setSelection([
+      { type: 'terrain', index: 0 },
+      { type: 'terrain', index: 1 },
+      { type: 'terrain', index: 2 }
+    ]);
+
+    expect(controller.alignSelection('y', 'min')).to.equal(true);
+    expect(t0.props.Y).to.equal(0);
+    expect(t1.props.Y).to.equal(0);
+    expect(t2.props.Y).to.equal(0);
+
+    t1.props.X = 36;
+    expect(controller.distributeSelection('x')).to.equal(true);
+    expect(t1.props.X).to.equal(20);
+
+    expect(controller.replaceSelectionPiece(7, 'terrain')).to.equal(true);
+    expect(t0.props.PIECE).to.equal(7);
+    expect(t1.props.PIECE).to.equal(7);
+    expect(t2.props.PIECE).to.equal(7);
+
+    expect(controller.randomizeSelectionPieces([2, 7], {
+      type: 'terrain',
+      requireSameSize: true,
+      seed: 123
+    })).to.equal(false);
+    expect(t0.props.PIECE).to.equal(7);
+
+    expect(controller.randomizeSelectionPieces([2], {
+      type: 'terrain',
+      requireSameSize: false,
+      seed: 123
+    })).to.equal(true);
+    expect(t0.props.PIECE).to.equal(2);
+    expect(t1.props.PIECE).to.equal(2);
+    expect(t2.props.PIECE).to.equal(2);
+    expect(history.snapshots.some(entry => entry.label === 'Align')).to.equal(true);
+    expect(history.snapshots.some(entry => entry.label === 'Distribute')).to.equal(true);
+    expect(history.snapshots.some(entry => entry.label === 'Replace')).to.equal(true);
+    expect(history.snapshots.some(entry => entry.label === 'Randomize')).to.equal(true);
+  });
+
+  it('wraps batch selection edits in explicit history transactions', () => {
+    const session = buildSession();
+    const history = new FakeHistory();
+    const controller = new EditorController({ session, history, snapEnabled: false });
+    controller.setAssets(buildAssets());
+    const t0 = createTerrainEntry({ styleName: 'dirt', piece: 2, x: 0, y: 0 });
+    const t1 = createTerrainEntry({ styleName: 'dirt', piece: 2, x: 20, y: 10 });
+    session.level.terrains.push(t0, t1);
+    controller._setSelection([
+      { type: 'terrain', index: 0 },
+      { type: 'terrain', index: 1 }
+    ]);
+
+    expect(controller.alignSelection('x', 'min')).to.equal(true);
+    expect(history.beginLabels).to.include('Align');
+    expect(history.endLabels).to.include('Align');
+  });
+
+  it('cancels explicit history transactions when a batch callback throws', () => {
+    const session = buildSession();
+    const history = new FakeHistory();
+    const controller = new EditorController({ session, history });
+
+    expect(() => {
+      controller.runHistoryTransaction('Boom', () => {
+        throw new Error('explode');
+      });
+    }).to.throw('explode');
+    expect(history.cancelCount).to.equal(1);
+  });
+
+  it('scales grouped selections with transformSelectionGroup', () => {
+    const session = buildSession();
+    const history = new FakeHistory();
+    const controller = new EditorController({ session, history, snapEnabled: false });
+    controller.setAssets(buildAssets());
+
+    const steel = createSteelEntry({ x: 10, y: 12, width: 4, height: 8 });
+    session.level.steel = [steel];
+    controller._setSelection([{ type: 'steel', index: 0 }]);
+
+    expect(controller.transformSelectionGroup({ scaleX: 1.5, scaleY: 0.5 })).to.equal(true);
+    expect(steel.props.WIDTH).to.equal(6);
+    expect(steel.props.HEIGHT).to.equal(4);
+    expect(steel.props.X).to.equal(9);
+    expect(steel.props.Y).to.equal(14);
+    expect(history.snapshots.some(entry => entry.label === 'Transform')).to.equal(true);
+  });
+
+  it('coerces non-finite positions when copying', () => {
+    const session = buildSession();
+    const controller = new EditorController({ session, snapEnabled: false });
+    controller.setAssets(buildAssets());
+
+    const terrainEntry = createTerrainEntry({ styleName: 'dirt', piece: 2, x: 4, y: 4 });
+    terrainEntry.props.X = 'bad';
+    terrainEntry.props.Y = Number.NaN;
+    session.level.terrains.push(terrainEntry);
+    controller.selection = [{ type: 'terrain', index: 0 }];
+
+    expect(controller.copySelection()).to.equal(true);
+    expect(controller.pasteSelection()).to.equal(true);
+    expect(session.level.terrains[1].props.X).to.equal(1);
+    expect(session.level.terrains[1].props.Y).to.equal(1);
+  });
+
+  it('copies entries without props using defaults', () => {
+    const session = buildSession();
+    const controller = new EditorController({ session, snapEnabled: false });
+    controller.setAssets(buildAssets());
+    session.level.terrains.push({ props: null });
+    controller.selection = [{ type: 'terrain', index: 0 }];
+
+    expect(controller.copySelection()).to.equal(true);
+    expect(controller.pasteSelection()).to.equal(true);
+    expect(session.level.terrains[1].props.X).to.equal(1);
+  });
+
+  it('pastes steel selections with a steel uid prefix', () => {
+    const session = buildSession();
+    const controller = new EditorController({ session, snapEnabled: false });
+    controller.setAssets(buildAssets());
+    session.level.steel = [createSteelEntry({ x: 4, y: 6, width: 2, height: 2 })];
+    controller.selection = [{ type: 'steel', index: 0 }];
+
+    expect(controller.copySelection()).to.equal(true);
+    expect(controller.pasteSelection()).to.equal(true);
+    expect(session.level.steel).to.have.length(2);
+    expect(session.level.steel[1].uid.startsWith('s_')).to.equal(true);
+  });
+
+  it('pastes gadget selections with a gadget uid prefix', () => {
+    const session = buildSession();
+    const controller = new EditorController({ session, snapEnabled: false });
+    controller.setAssets(buildAssets());
+    session.level.gadgets.push(createGadgetEntry({ styleName: 'dirt', piece: 1, x: 2, y: 2 }));
+    controller.selection = [{ type: 'gadget', index: 0 }];
+
+    expect(controller.copySelection()).to.equal(true);
+    expect(controller.pasteSelection()).to.equal(true);
+    expect(session.level.gadgets).to.have.length(2);
+    expect(session.level.gadgets[1].uid.startsWith('g_')).to.equal(true);
+  });
+
+  it('returns false when snapping without a selection', () => {
+    const session = buildSession();
+    const controller = new EditorController({ session });
+    controller.setAssets(buildAssets());
+    expect(controller.snapSelectionToGrid()).to.equal(false);
+  });
+
+  it('snaps using a 1px grid when the grid size is invalid', () => {
+    const session = buildSession();
+    const controller = new EditorController({ session, gridSize: 0, snapEnabled: true });
+    controller.setAssets(buildAssets());
+    session.level.terrains.push(createTerrainEntry({ styleName: 'dirt', piece: 2, x: 4, y: 4 }));
+    session.level.terrains[0].props.X = 3.6;
+    session.level.terrains[0].props.Y = 4.4;
+    controller.selection = [{ type: 'terrain', index: 0 }];
+    expect(controller.snapSelectionToGrid()).to.equal(true);
+    expect(session.level.terrains[0].props.X).to.equal(4);
+    expect(session.level.terrains[0].props.Y).to.equal(4);
+  });
+
+  it('returns false when nudging without a selection', () => {
+    const session = buildSession();
+    const controller = new EditorController({ session });
+    expect(controller.nudgeSelection(1, 0, 1)).to.equal(false);
+  });
+
+  it('skips missing props when nudging and snapping', () => {
+    const session = buildSession();
+    const controller = new EditorController({ session, snapEnabled: true });
+    controller.setAssets(buildAssets());
+    const selectionEvents = [];
+    controller.setCallbacks({ onSelectionChange: entries => selectionEvents.push(entries) });
+    session.level.terrains.push({ props: null });
+    controller.selection = [{ type: 'terrain', index: 0 }];
+    expect(controller.nudgeSelection(1, 0, 1)).to.equal(true);
+    expect(controller.snapSelectionToGrid()).to.equal(true);
+    expect(selectionEvents.length).to.be.greaterThan(0);
+  });
+
+  it('uses 1px paste steps when snapping is disabled', () => {
+    const session = buildSession();
+    const controller = new EditorController({ session, gridSize: 4, snapEnabled: false });
+    controller.setAssets(buildAssets());
+
+    session.level.terrains.push(createTerrainEntry({ styleName: 'dirt', piece: 2, x: 8, y: 8 }));
+    controller.selection = [{ type: 'terrain', index: 0 }];
+    expect(controller.copySelection()).to.equal(true);
+    expect(controller.pasteSelection()).to.equal(true);
+    expect(session.level.terrains[1].props.X).to.equal(9);
+  });
+
+  it('returns false when clone/paste/duplicate have nothing to act on', () => {
+    const session = buildSession();
+    const controller = new EditorController({ session, snapEnabled: false });
+    controller.setAssets(buildAssets());
+    session.level.gadgets = null;
+
+    const cloneResult = controller._cloneSelection([
+      { type: 'gadget', index: 0, entry: { props: { X: 0, Y: 0 } } }
+    ], 0, 0);
+    expect(cloneResult).to.equal(null);
+
+    controller._clipboard = {
+      items: [{ type: 'gadget', entry: { props: { X: 0, Y: 0 } }, offsetX: 0, offsetY: 0 }],
+      minX: 0,
+      minY: 0
+    };
+    expect(controller.pasteSelection()).to.equal(false);
+    expect(controller.duplicateSelection()).to.equal(false);
+  });
+
+  it('duplicates selection with alt-drag', () => {
+    const session = buildSession();
+    const history = new FakeHistory();
+    const controller = new EditorController({
+      session,
+      history,
+      snapEnabled: false,
+      gridSize: 1,
+      handleSize: 2
+    });
+    controller.setAssets(buildAssets());
+    controller.setTool(EditorTools.SELECT);
+
+    const terrainEntry = createTerrainEntry({ styleName: 'dirt', piece: 2, x: 10, y: 10 });
+    session.level.terrains.push(terrainEntry);
+
+    controller.handlePointerDown({ x: 14, y: 14 }, 0);
+    controller.handlePointerUp();
+
+    controller.handlePointerDown({ x: 14, y: 14 }, 0, { altKey: true });
+    controller.handlePointerMove({ x: 16, y: 16 });
+    controller.handlePointerUp();
+
+    expect(session.level.terrains).to.have.length(2);
+    expect(history.snapshots.some(entry => entry.label === 'Duplicate')).to.equal(true);
+  });
+
+  it('handles additive marquee selection without duplicates', () => {
+    const session = buildSession();
+    const controller = new EditorController({ session, snapEnabled: false });
+    controller.setAssets(buildAssets());
+    controller.setTool(EditorTools.SELECT);
+
+    const entryA = createTerrainEntry({ styleName: 'dirt', piece: 2, x: 10, y: 10 });
+    session.level.terrains.push(entryA);
+
+    controller.handlePointerDown({ x: 10, y: 10 }, 0);
+    controller.handlePointerUp();
+
+    session.level.gadgets = null;
+    controller.handlePointerDown({ x: 0, y: 0 }, 0, { shiftKey: true });
+    controller.handlePointerMove({ x: 20, y: 20 }, { isDown: true });
+    controller.handlePointerUp();
+
+    expect(controller.getSelectedEntries()).to.have.length(1);
+  });
+
+  it('covers marquee intersection branches', () => {
+    const session = buildSession();
+    const controller = new EditorController({ session, snapEnabled: false });
+    controller.setAssets(buildAssets());
+    session.level.terrains.push(createTerrainEntry({ styleName: 'dirt', piece: 2, x: 10, y: 10 }));
+
+    const scenarios = [
+      { x: 20, y: 10, width: 2, height: 2 },
+      { x: 0, y: 10, width: 5, height: 2 },
+      { x: 10, y: 25, width: 8, height: 2 },
+      { x: 10, y: 0, width: 8, height: 5 },
+      { x: 12, y: 12, width: 2, height: 2 }
+    ];
+    const originalGetMarqueeBounds = controller.getMarqueeBounds.bind(controller);
+    for (const bounds of scenarios) {
+      controller._marquee = { startX: 0, startY: 0, x: 1, y: 1, additive: false };
+      controller.getMarqueeBounds = () => bounds;
+      controller._applyMarqueeSelection();
+    }
+    controller.getMarqueeBounds = originalGetMarqueeBounds;
+    controller._marquee = null;
+  });
+
+  it('notifies marquee callbacks', () => {
+    const session = buildSession();
+    const controller = new EditorController({ session });
+    const marqueeEvents = [];
+    controller.setCallbacks({ onMarqueeChange: bounds => marqueeEvents.push(bounds) });
+
+    controller._beginMarquee(0, 0, true);
+    controller._updateMarquee(5, 6);
+    controller._clearMarquee();
+
+    expect(marqueeEvents).to.have.length(3);
+    expect(marqueeEvents[0]).to.have.property('width');
+    expect(marqueeEvents[2]).to.equal(null);
+  });
+
+  it('uses a custom handle size', () => {
+    const session = buildSession();
+    const controller = new EditorController({ session, handleSize: 12 });
+    expect(controller.getHandleSize()).to.equal(12);
+  });
+
+  it('supports additive selection helpers', () => {
+    const session = buildSession();
+    const controller = new EditorController({ session, snapEnabled: false });
+    controller.setAssets(buildAssets());
+    controller.setTool(EditorTools.SELECT);
+    const selectionEvents = [];
+    controller.setCallbacks({ onSelectionChange: selection => selectionEvents.push(selection) });
+
+    const entryA = createTerrainEntry({ styleName: 'dirt', piece: 2, x: 10, y: 10 });
+    const entryB = createTerrainEntry({ styleName: 'dirt', piece: 2, x: 30, y: 30 });
+    session.level.terrains.push(entryA, entryB);
+
+    const firstHit = controller._findSelectionAt(10, 10);
+    const secondHit = controller._findSelectionAt(30, 30);
+    controller._selectHit(firstHit);
+    controller._selectHit(secondHit, { additive: true });
+    expect(controller.getSelectedEntries()).to.have.length(2);
+    expect(controller._isSelected('gadget', 0)).to.equal(false);
+    expect(selectionEvents.length).to.be.greaterThan(0);
+
+    const gadgetEntry = createGadgetEntry({ styleName: 'dirt', piece: 1, x: 5, y: 6 });
+    session.level.gadgets.push(gadgetEntry);
+    controller.selection = [{ type: 'gadget', index: 0 }];
+    const bounds = controller.getSelectionBounds();
+    expect(bounds.width).to.equal(8);
+    expect(bounds.height).to.equal(8);
+  });
+});
diff --git a/test/editor/editor-controller.03-editorcontroller.test.js b/test/editor/editor-controller.03-editorcontroller.test.js
new file mode 100644
index 00000000..d8af2fa1
--- /dev/null
+++ b/test/editor/editor-controller.03-editorcontroller.test.js
@@ -0,0 +1,441 @@
+import { expect } from 'chai';
+import FakeTimers from '@sinonjs/fake-timers';
+import { EditorController, __test__ } from '../../js/editor/EditorController.js';
+import { EditorSession } from '../../js/editor/EditorSession.js';
+import { EditorLevel } from '../../js/editor/EditorLevel.js';
+import { EditorTools } from '../../js/editor/EditorTools.js';
+import { createTerrainEntry, createGadgetEntry, createSteelEntry } from '../../js/editor/EditorEntryFactory.js';
+
+class FakeHistory {
+  constructor() {
+    this.clearCount = 0;
+    this.snapshots = [];
+    this.undoValue = null;
+    this.redoValue = null;
+    this.beginLabels = [];
+    this.endLabels = [];
+    this.cancelCount = 0;
+  }
+
+  clear() {
+    this.clearCount += 1;
+  }
+
+  pushSnapshot(level, label) {
+    this.snapshots.push({ level, label });
+    return true;
+  }
+
+  undo() {
+    return this.undoValue;
+  }
+
+  redo() {
+    return this.redoValue;
+  }
+
+  beginTransaction(label) {
+    this.beginLabels.push(label);
+  }
+
+  endTransaction(label) {
+    this.endLabels.push(label);
+    return true;
+  }
+
+  cancelTransaction() {
+    this.cancelCount += 1;
+    return true;
+  }
+}
+
+const buildSession = () => {
+  const session = new EditorSession();
+  const level = new EditorLevel();
+  level.setHeader('STYLE', 'dirt');
+  level.terrains = [];
+  level.gadgets = [];
+  session.level = level;
+  return session;
+};
+
+const buildAssets = () => {
+  const terrainMeta = { id: 2, name: 'terrain_2', width: 8, height: 8 };
+  const gadgetMeta = { id: 1, name: 'object_1', width: 8, height: 8, triggerEffectId: 0 };
+  const triggerMeta = { id: 3, name: 'object_3', width: 8, height: 8, triggerEffectId: 5 };
+  const exitMeta = { id: 4, name: 'object_4', width: 8, height: 8, triggerEffectId: 0 };
+  return {
+    terrain: [terrainMeta],
+    gadgets: [gadgetMeta],
+    triggers: [triggerMeta],
+    entranceId: 1,
+    exitId: 4,
+    terrainById: new Map([[terrainMeta.id, terrainMeta]]),
+    gadgetById: new Map([
+      [gadgetMeta.id, gadgetMeta],
+      [triggerMeta.id, triggerMeta],
+      [exitMeta.id, exitMeta]
+    ])
+  };
+};
+
+describe('EditorController', () => {
+  it('supports on-canvas resize handles', () => {
+    const session = buildSession();
+    const history = new FakeHistory();
+    const controller = new EditorController({ session, history, snapEnabled: false, gridSize: 1 });
+    controller.setAssets(buildAssets());
+    controller.setTool(EditorTools.SELECT);
+    expect(controller.getHandleSize()).to.equal(2);
+
+    const entry = createSteelEntry({
+      x: 10,
+      y: 10,
+      width: 8,
+      height: 8
+    });
+    session.level.steel.push(entry);
+
+    controller.handlePointerDown({ x: 10, y: 10 }, 0);
+    controller.handlePointerUp();
+
+    const handleX = entry.props.X + entry.props.WIDTH;
+    const handleY = entry.props.Y + entry.props.HEIGHT;
+    controller.handlePointerDown({ x: handleX, y: handleY }, 0);
+    controller.handlePointerMove({ x: handleX + 4, y: handleY + 6 });
+    controller.handlePointerUp();
+
+    expect(entry.props.WIDTH).to.equal(12);
+    expect(entry.props.HEIGHT).to.equal(14);
+    expect(history.snapshots.some(entry => entry.label === 'Resize')).to.equal(true);
+  });
+
+  it('snaps resize handles when snapping is enabled', () => {
+    const session = buildSession();
+    const history = new FakeHistory();
+    const controller = new EditorController({ session, history, gridSize: 4 });
+    controller.setAssets(buildAssets());
+    controller.setTool(EditorTools.SELECT);
+
+    let selectionChanges = 0;
+    controller.setCallbacks({ onSelectionChange: () => selectionChanges++ });
+
+    const entry = createSteelEntry({
+      x: 8,
+      y: 8,
+      width: 8,
+      height: 8
+    });
+    session.level.steel.push(entry);
+
+    controller.handlePointerDown({ x: 8, y: 8 }, 0);
+    controller.handlePointerUp();
+
+    const handleX = entry.props.X + entry.props.WIDTH;
+    const handleY = entry.props.Y + entry.props.HEIGHT;
+    controller.handlePointerDown({ x: handleX, y: handleY }, 0);
+    controller.handlePointerMove({ x: handleX + 3, y: handleY + 3 });
+    controller.handlePointerUp();
+
+    expect(entry.props.WIDTH).to.equal(12);
+    expect(entry.props.HEIGHT).to.equal(12);
+    expect(selectionChanges).to.be.greaterThan(0);
+  });
+
+  it('clamps inverted resize handles', () => {
+    const session = buildSession();
+    const controller = new EditorController({ session, snapEnabled: false, gridSize: 1 });
+    controller.setAssets(buildAssets());
+    controller.setTool(EditorTools.SELECT);
+
+    const entry = createSteelEntry({
+      x: 10,
+      y: 10,
+      width: 8,
+      height: 8
+    });
+    session.level.steel.push(entry);
+
+    controller.handlePointerDown({ x: 10, y: 10 }, 0);
+    controller.handlePointerUp();
+
+    const right = entry.props.X + entry.props.WIDTH;
+    const bottom = entry.props.Y + entry.props.HEIGHT;
+    controller.handlePointerDown({ x: right, y: bottom }, 0);
+    controller.handlePointerMove({ x: entry.props.X - 5, y: entry.props.Y - 5 });
+    controller.handlePointerUp();
+    expect(entry.props.WIDTH).to.be.at.least(1);
+    expect(entry.props.HEIGHT).to.be.at.least(1);
+
+    controller.handlePointerDown({ x: entry.props.X, y: entry.props.Y }, 0);
+    controller.handlePointerMove({ x: entry.props.X + entry.props.WIDTH + 10, y: entry.props.Y + entry.props.HEIGHT + 10 });
+    controller.handlePointerUp();
+    expect(entry.props.WIDTH).to.be.at.least(1);
+    expect(entry.props.HEIGHT).to.be.at.least(1);
+  });
+
+  it('updates selected props, deletes entries, and supports undo/redo', () => {
+    const session = buildSession();
+    const history = new FakeHistory();
+    const controller = new EditorController({ session, history });
+    controller.setAssets(buildAssets());
+    const levelChanges = [];
+    const selectionUpdates = [];
+    controller.setCallbacks({
+      onLevelChange: level => levelChanges.push(level),
+      onSelectionChange: selection => selectionUpdates.push(selection)
+    });
+
+    const terrainEntry = createTerrainEntry({ styleName: 'dirt', piece: 2, x: 0, y: 0 });
+    session.level.terrains.push(terrainEntry);
+    controller.handlePointerDown({ x: 1, y: 1 }, 0);
+
+    const updated = controller.updateSelectedProps({ flip_horizontal: true, erase: false });
+    expect(updated).to.equal(true);
+    expect(terrainEntry.props.FLIP_HORIZONTAL).to.equal(true);
+    expect(terrainEntry.props).to.not.have.property('ERASE');
+
+    expect(controller.deleteSelected()).to.equal(true);
+    expect(session.level.terrains).to.have.length(0);
+    expect(controller.deleteSelected()).to.equal(false);
+    const gadgetEntry = createGadgetEntry({ styleName: 'dirt', piece: 1, x: 10, y: 10 });
+    session.level.gadgets.push(gadgetEntry);
+    controller.selection = [{ type: 'gadget', index: 0 }];
+    expect(controller.deleteSelected()).to.equal(true);
+    expect(session.level.gadgets).to.have.length(0);
+
+    const undoLevel = new EditorLevel();
+    undoLevel.setHeader('TITLE', 'Undo');
+    const redoLevel = new EditorLevel();
+    redoLevel.setHeader('TITLE', 'Redo');
+    history.undoValue = undoLevel;
+    history.redoValue = redoLevel;
+
+    expect(controller.undo()).to.equal(undoLevel);
+    expect(session.level).to.equal(undoLevel);
+    expect(controller.redo()).to.equal(redoLevel);
+    expect(levelChanges).to.deep.equal([undoLevel, redoLevel]);
+
+    history.undoValue = null;
+    history.redoValue = null;
+    expect(controller.undo()).to.equal(null);
+    expect(controller.redo()).to.equal(null);
+
+    controller.selection = [{ type: 'gadget', index: 5 }];
+    expect(controller.getSelectedEntry()).to.equal(null);
+    controller.selection = [];
+    expect(controller.updateSelectedProps({ X: 1 })).to.equal(false);
+    expect(selectionUpdates.length).to.be.greaterThan(0);
+
+    controller.selection = [{ type: 'gadget', index: 0 }];
+    controller.session.level.gadgets = null;
+    expect(controller.getSelectedEntry()).to.equal(null);
+  });
+
+  it('handles missing sessions safely', () => {
+    const history = new FakeHistory();
+    const controller = new EditorController({ session: null, history });
+    expect(controller.deleteSelected()).to.equal(false);
+    controller.handlePointerDown({ x: 1, y: 1 }, 0);
+    controller.handlePointerMove({ x: 1, y: 1 });
+    controller.handlePointerUp();
+    expect(controller._placeTerrainAt(1, 1)).to.equal(null);
+    expect(controller._placeGadgetAt(1, 1, 1)).to.equal(null);
+    controller._eraseAt(1, 1);
+    controller._removeGadgetsById(1);
+    expect(controller._findSelectionAt(0, 0)).to.equal(null);
+    controller.updateHeader('TITLE', 'Missing');
+  });
+
+  it('returns null lists without a session', () => {
+    const controller = new EditorController({ session: null });
+    expect(controller._getListForType('terrain')).to.equal(null);
+  });
+
+  it('uses fallback entrance and exit ids without assets', () => {
+    const session = buildSession();
+    const history = new FakeHistory();
+    const controller = new EditorController({ session, history, snapEnabled: false });
+    controller.setAssets(null);
+    controller.setSelectedGadget(5);
+
+    controller.setTool(EditorTools.ENTRANCE);
+    controller.handlePointerDown({ x: 1, y: 1 }, 0);
+    expect(session.level.gadgets[0].props.PIECE).to.equal(1);
+
+    controller.setTool(EditorTools.EXIT);
+    controller.handlePointerDown({ x: 2, y: 2 }, 0);
+    expect(session.level.gadgets[1].props.PIECE).to.equal(5);
+  });
+
+  it('preserves existing selections when assets change', () => {
+    const session = buildSession();
+    const history = new FakeHistory();
+    const controller = new EditorController({ session, history });
+    controller.selectedTerrainId = 9;
+    controller.selectedGadgetId = 8;
+    controller.selectedTriggerId = 7;
+    controller.setAssets(buildAssets());
+    expect(controller.selectedTerrainId).to.equal(2);
+    expect(controller.selectedGadgetId).to.equal(1);
+    expect(controller.selectedTriggerId).to.equal(3);
+    controller.setAssets(null);
+    expect(controller.assets).to.equal(null);
+  });
+
+  it('rounds positions when the grid size is disabled', () => {
+    const session = buildSession();
+    const history = new FakeHistory();
+    const controller = new EditorController({
+      session,
+      history,
+      gridSize: 0,
+      snapEnabled: true,
+      brushSize: 3
+    });
+    expect(controller.brushSize).to.equal(3);
+    controller.setAssets(buildAssets());
+    controller.setTool(EditorTools.TERRAIN);
+    controller.handlePointerDown({ x: 5.6, y: 5.2 }, 0);
+    expect(session.level.terrains[0].props.X).to.equal(2);
+    expect(session.level.terrains[0].props.Y).to.equal(1);
+  });
+
+  it('covers internal fallbacks', () => {
+    const session = buildSession();
+    const history = new FakeHistory();
+    const controller = new EditorController({ session, history, previewDelay: 5 });
+    const previewEvents = [];
+    const clock = FakeTimers.install({ now: 0, toFake: ['setTimeout', 'clearTimeout', 'Date'] });
+    controller.setCallbacks({ onPreviewRequest: label => previewEvents.push(label) });
+    session.level.terrains.push(createTerrainEntry({ styleName: 'dirt', piece: 2, x: 0, y: 0 }));
+    controller.setSnapEnabled(false);
+    controller.setSnapEnabled(true);
+    controller.resetHistory();
+    controller.setTool(null);
+    controller._requestPreview();
+    clock.tick(5);
+    clock.uninstall();
+    expect(previewEvents).to.deep.equal(['Update']);
+
+    controller._removeGadgetsById(null);
+    controller.session.level.gadgets = null;
+    controller._removeGadgetsById(1);
+    controller._trimGadgetsById(null, 1);
+    controller._trimGadgetsById(1, 1);
+    controller._updateMarquee(1, 1);
+    controller._applyMarqueeSelection();
+    controller._setSelection(null);
+    controller._toggleSelection(null);
+    controller.selection = null;
+    controller.getSelectedEntries();
+    controller.getMarqueeBounds();
+    controller.copySelection();
+    controller.pasteSelection();
+    controller._eraseLine(null, null);
+    controller._brushLine(null, null);
+
+    const originalSession = controller.session;
+    controller.session = null;
+    controller._placeSteelAt(0, 0, 1, 1);
+    controller._beginSteelDraft(0, 0);
+    controller.session = originalSession;
+
+    controller._steelDraft = null;
+    controller._updateSteelDraft(1, 1);
+    controller._steelDraft = { index: 0, startX: 0, startY: 0 };
+    controller.session.level.steel = null;
+    controller._updateSteelDraft(1, 1);
+    controller.session.level.steel = [];
+    controller._updateSteelDraft(1, 1);
+
+    controller._steelDraft = null;
+
+    const originalGetMarqueeBounds = controller.getMarqueeBounds.bind(controller);
+    controller.getMarqueeBounds = () => null;
+    controller._marquee = { startX: 0, startY: 0, x: 5, y: 5, additive: false };
+    controller._applyMarqueeSelection();
+    controller.getMarqueeBounds = originalGetMarqueeBounds;
+    controller._marquee = null;
+
+    controller.selection = [];
+    controller._resize = { handle: 'se', type: 'terrain', index: 0, bounds: { x: 0, y: 0, width: 4, height: 4 } };
+    controller.handlePointerMove({ x: 2, y: 2 });
+    controller._resize = null;
+
+    controller._drag = { entries: null };
+    controller.tool = EditorTools.SELECT;
+    controller.handlePointerMove({ x: 1, y: 1 }, { isDown: true });
+
+    controller._drag = { label: '', entries: [] };
+    controller._strokeChanged = true;
+    controller.handlePointerUp();
+  });
+
+  it('dispose cancels pending preview callbacks', () => {
+    const session = buildSession();
+    const controller = new EditorController({ session, history: new FakeHistory(), previewDelay: 5 });
+    const previewEvents = [];
+    const clock = FakeTimers.install({ now: 0, toFake: ['setTimeout', 'clearTimeout', 'Date'] });
+    controller.setCallbacks({ onPreviewRequest: label => previewEvents.push(label) });
+
+    controller._requestPreview('Dispose');
+    controller.dispose();
+    clock.tick(5);
+    clock.uninstall();
+
+    expect(previewEvents).to.deep.equal([]);
+  });
+
+  it('removes gadgets by id', () => {
+    const session = buildSession();
+    const controller = new EditorController({ session });
+    session.level.gadgets.push(createGadgetEntry({ styleName: 'dirt', piece: 1, x: 4, y: 4 }));
+    controller._removeGadgetsById(1);
+    expect(session.level.gadgets).to.have.length(0);
+  });
+
+  it('creates a default history when none is provided', () => {
+    const session = buildSession();
+    const controller = new EditorController({ session });
+    expect(controller.history).to.exist;
+  });
+
+  it('reorders selected entries across lists', () => {
+    const session = buildSession();
+    const history = new FakeHistory();
+    const controller = new EditorController({ session, history, snapEnabled: false });
+    const t0 = createTerrainEntry({ styleName: 'dirt', piece: 1, x: 0, y: 0 });
+    const t1 = createTerrainEntry({ styleName: 'dirt', piece: 2, x: 0, y: 0 });
+    const g0 = createGadgetEntry({ styleName: 'dirt', piece: 1, x: 0, y: 0 });
+    const g1 = createGadgetEntry({ styleName: 'dirt', piece: 2, x: 0, y: 0 });
+    const s0 = createSteelEntry({ x: 0, y: 0, width: 1, height: 1 });
+    const s1 = createSteelEntry({ x: 2, y: 2, width: 1, height: 1 });
+    session.level.terrains = [t0, t1];
+    session.level.gadgets = [g0, g1];
+    session.level.steel = [s0, s1];
+
+    controller._setSelection([
+      { type: 'terrain', index: 0 },
+      { type: 'gadget', index: 0 },
+      { type: 'steel', index: 0 }
+    ]);
+
+    expect(controller.bringSelectionToFront()).to.equal(true);
+    expect(session.level.terrains[1]).to.equal(t0);
+    expect(session.level.gadgets[1]).to.equal(g0);
+    expect(session.level.steel[1]).to.equal(s0);
+
+    expect(controller.sendSelectionToBack()).to.equal(true);
+    expect(session.level.terrains[0]).to.equal(t0);
+    expect(session.level.gadgets[0]).to.equal(g0);
+    expect(session.level.steel[0]).to.equal(s0);
+
+    controller._setSelection([{ type: 'terrain', index: 0 }]);
+    expect(controller.moveSelectionForward()).to.equal(true);
+    expect(session.level.terrains[1]).to.equal(t0);
+
+    expect(controller.moveSelectionBackward()).to.equal(true);
+    expect(session.level.terrains[0]).to.equal(t0);
+  });
+});
diff --git a/test/editor/editor-controller.04-editorcontroller.test.js b/test/editor/editor-controller.04-editorcontroller.test.js
new file mode 100644
index 00000000..b0f33280
--- /dev/null
+++ b/test/editor/editor-controller.04-editorcontroller.test.js
@@ -0,0 +1,245 @@
+import { expect } from 'chai';
+import FakeTimers from '@sinonjs/fake-timers';
+import { EditorController, __test__ } from '../../js/editor/EditorController.js';
+import { EditorSession } from '../../js/editor/EditorSession.js';
+import { EditorLevel } from '../../js/editor/EditorLevel.js';
+import { EditorTools } from '../../js/editor/EditorTools.js';
+import { createTerrainEntry, createGadgetEntry, createSteelEntry } from '../../js/editor/EditorEntryFactory.js';
+
+class FakeHistory {
+  constructor() {
+    this.clearCount = 0;
+    this.snapshots = [];
+    this.undoValue = null;
+    this.redoValue = null;
+    this.beginLabels = [];
+    this.endLabels = [];
+    this.cancelCount = 0;
+  }
+
+  clear() {
+    this.clearCount += 1;
+  }
+
+  pushSnapshot(level, label) {
+    this.snapshots.push({ level, label });
+    return true;
+  }
+
+  undo() {
+    return this.undoValue;
+  }
+
+  redo() {
+    return this.redoValue;
+  }
+
+  beginTransaction(label) {
+    this.beginLabels.push(label);
+  }
+
+  endTransaction(label) {
+    this.endLabels.push(label);
+    return true;
+  }
+
+  cancelTransaction() {
+    this.cancelCount += 1;
+    return true;
+  }
+}
+
+const buildSession = () => {
+  const session = new EditorSession();
+  const level = new EditorLevel();
+  level.setHeader('STYLE', 'dirt');
+  level.terrains = [];
+  level.gadgets = [];
+  session.level = level;
+  return session;
+};
+
+const buildAssets = () => {
+  const terrainMeta = { id: 2, name: 'terrain_2', width: 8, height: 8 };
+  const gadgetMeta = { id: 1, name: 'object_1', width: 8, height: 8, triggerEffectId: 0 };
+  const triggerMeta = { id: 3, name: 'object_3', width: 8, height: 8, triggerEffectId: 5 };
+  const exitMeta = { id: 4, name: 'object_4', width: 8, height: 8, triggerEffectId: 0 };
+  return {
+    terrain: [terrainMeta],
+    gadgets: [gadgetMeta],
+    triggers: [triggerMeta],
+    entranceId: 1,
+    exitId: 4,
+    terrainById: new Map([[terrainMeta.id, terrainMeta]]),
+    gadgetById: new Map([
+      [gadgetMeta.id, gadgetMeta],
+      [triggerMeta.id, triggerMeta],
+      [exitMeta.id, exitMeta]
+    ])
+  };
+};
+
+describe('EditorController', () => {
+  it('covers reorder edge cases and selection bounds', () => {
+    const session = buildSession();
+    const controller = new EditorController({ session });
+    controller.setAssets(buildAssets());
+    const t0 = createTerrainEntry({ styleName: 'dirt', piece: 1, x: 0, y: 0 });
+    const t1 = createTerrainEntry({ styleName: 'dirt', piece: 2, x: 0, y: 0 });
+    session.level.terrains = [t0, t1];
+
+    controller.selection = [];
+    expect(controller.getSelectionBounds()).to.equal(null);
+    expect(controller._getResizeHandleAt(0, 0)).to.equal(null);
+    expect(controller._reorderSelection('front')).to.equal(false);
+
+    controller.selection = [{ type: 'terrain', index: 0 }];
+    expect(controller._reorderSelection('unknown')).to.equal(false);
+    controller.selection = [{ type: 'terrain', index: 5 }];
+    expect(controller._reorderSelection('front')).to.equal(false);
+
+    controller.selection = [{ type: 'terrain', index: 1 }];
+    controller.moveSelectionForward();
+    controller.selection = [{ type: 'terrain', index: 0 }];
+    expect(controller.getSelectionBounds().width).to.equal(8);
+
+    controller.selection = [
+      { type: 'terrain', index: 0 },
+      { type: 'terrain', index: 1 }
+    ];
+    controller.moveSelectionForward();
+    controller.moveSelectionBackward();
+
+    const steel = createSteelEntry({ x: 10, y: 10, width: 4, height: 4 });
+    session.level.steel = [steel];
+    controller.selection = [{ type: 'steel', index: 0 }];
+    expect(controller.getSelectionBounds().width).to.equal(4);
+    expect(controller._getResizeHandleAt(0, 0)).to.equal(null);
+  });
+
+  it('returns null when resize bounds are missing for steel selections', () => {
+    const controller = new EditorController({ session: null });
+    controller.selection = [{ type: 'steel', index: 0 }];
+    expect(controller._getResizeHandleAt(0, 0)).to.equal(null);
+  });
+
+  it('adds default entrances and exits when missing', () => {
+    const session = buildSession();
+    session.level.setHeader('WIDTH', 320);
+    session.level.setHeader('HEIGHT', 160);
+    const history = new FakeHistory();
+    const controller = new EditorController({ session, history, previewDelay: 5 });
+    controller.setAssets(buildAssets());
+    const previews = [];
+    const clock = FakeTimers.install({ now: 0, toFake: ['setTimeout', 'clearTimeout', 'Date'] });
+    controller.setCallbacks({ onPreviewRequest: label => previews.push(label) });
+
+    const result = controller.ensureDefaultEntrancesExits({ viewRect: { x: 0, y: 0, w: 320, h: 160 } });
+    expect(result).to.equal(true);
+    expect(session.level.gadgets.some(entry => entry.props.PIECE === 1)).to.equal(true);
+    expect(session.level.gadgets.some(entry => entry.props.PIECE === 4)).to.equal(true);
+
+    clock.tick(5);
+    expect(previews).to.eql(['Defaults']);
+    clock.uninstall();
+  });
+
+  it('handles default entrances with custom ids and missing headers', () => {
+    const session = buildSession();
+    session.level.setHeader('WIDTH', 'bad');
+    session.level.setHeader('HEIGHT', 0);
+    const history = new FakeHistory();
+    const controller = new EditorController({ session, history });
+    controller.setAssets(buildAssets());
+    const result = controller.ensureDefaultEntrancesExits({ entranceId: 99, exitId: 100 });
+    expect(result).to.equal(true);
+    const pieces = session.level.gadgets.map(entry => entry.props.PIECE);
+    expect(pieces).to.include(99);
+    expect(pieces).to.include(100);
+  });
+
+  it('falls back to asset arrays and handles missing gadget lists', () => {
+    const session = buildSession();
+    const controller = new EditorController({ session });
+    controller.setAssets({
+      terrain: [{ id: 5, width: 4, height: 5 }],
+      gadgets: [{ id: 6, width: 7, height: 8 }]
+    });
+    expect(controller._getTerrainMeta(5).width).to.equal(4);
+    expect(controller._getGadgetMeta(6).width).to.equal(7);
+    expect(controller._getTerrainMeta(99)).to.equal(null);
+
+    session.level.gadgets = null;
+    expect(controller._hasGadgetId(1)).to.equal(false);
+    expect(controller._hasGadgetId(Number.NaN)).to.equal(false);
+  });
+
+  it('returns false when ensuring defaults without a session', () => {
+    const controller = new EditorController({ session: null });
+    expect(controller.ensureDefaultEntrancesExits()).to.equal(false);
+  });
+
+  it('skips defaults when entrances and exits already exist', () => {
+    const session = buildSession();
+    session.level.setHeader('WIDTH', 320);
+    session.level.setHeader('HEIGHT', 160);
+    const history = new FakeHistory();
+    const controller = new EditorController({ session, history });
+    controller.setAssets(buildAssets());
+    session.level.gadgets.push(
+      createGadgetEntry({ styleName: 'dirt', piece: 1, x: 0, y: 0 }),
+      createGadgetEntry({ styleName: 'dirt', piece: 4, x: 10, y: 0 })
+    );
+    const result = controller.ensureDefaultEntrancesExits();
+    expect(result).to.equal(false);
+  });
+
+  it('clones entries while preserving uids', () => {
+    const entry = createTerrainEntry({ styleName: 'dirt', piece: 1, x: 0, y: 0 });
+    entry.uid = 't_keep';
+    const clone = __test__.cloneEntry(entry, { preserveUid: true });
+    expect(clone.uid).to.equal('t_keep');
+    expect(clone.props).to.deep.equal(entry.props);
+  });
+
+  it('assigns default entry uids when none are provided', () => {
+    const entry = createTerrainEntry({ styleName: 'dirt', piece: 1, x: 2, y: 3 });
+    delete entry.uid;
+    const clone = __test__.cloneEntry(entry);
+    expect(clone.uid.startsWith('e_')).to.equal(true);
+  });
+
+  it('assigns uids and clones gadget/steel entries', () => {
+    const session = buildSession();
+    const controller = new EditorController({ session });
+    controller.setAssets(buildAssets());
+    const gadget = createGadgetEntry({ styleName: 'dirt', piece: 1, x: 0, y: 0 });
+    const steel = createSteelEntry({ x: 1, y: 1, width: 2, height: 2 });
+    session.level.gadgets.push(gadget);
+    session.level.steel = [steel];
+    const cloned = controller._cloneSelection([
+      { type: 'gadget', index: 0, entry: gadget },
+      { type: 'steel', index: 0, entry: steel }
+    ], 1, 1);
+    expect(cloned).to.have.length(2);
+    expect(session.level.gadgets[1].uid.startsWith('g_')).to.equal(true);
+    expect(session.level.steel[1].uid.startsWith('s_')).to.equal(true);
+  });
+
+  it('resolves selected entries by uid after index shifts', () => {
+    const session = buildSession();
+    const controller = new EditorController({ session });
+    const first = createTerrainEntry({ styleName: 'dirt', piece: 2, x: 0, y: 0 });
+    const second = createTerrainEntry({ styleName: 'dirt', piece: 2, x: 8, y: 0 });
+    session.level.terrains.push(first, second);
+    controller.selection = [{ type: 'terrain', index: 0, uid: first.uid }];
+
+    session.level.terrains = [second, first];
+    const selected = controller.getSelectedEntries();
+
+    expect(selected).to.have.length(1);
+    expect(selected[0].entry).to.equal(first);
+    expect(selected[0].index).to.equal(1);
+    expect(controller._isSelected('terrain', 1)).to.equal(true);
+  });
+});
diff --git a/test/editor/editor-controller.test.js b/test/editor/editor-controller.test.js
deleted file mode 100644
index b30a99d5..00000000
--- a/test/editor/editor-controller.test.js
+++ /dev/null
@@ -1,1098 +0,0 @@
-import { expect } from 'chai';
-import FakeTimers from '@sinonjs/fake-timers';
-import { EditorController, __test__ } from '../../js/editor/EditorController.js';
-import { EditorSession } from '../../js/editor/EditorSession.js';
-import { EditorLevel } from '../../js/editor/EditorLevel.js';
-import { EditorTools } from '../../js/editor/EditorTools.js';
-import { createTerrainEntry, createGadgetEntry, createSteelEntry } from '../../js/editor/EditorEntryFactory.js';
-
-class FakeHistory {
-  constructor() {
-    this.clearCount = 0;
-    this.snapshots = [];
-    this.undoValue = null;
-    this.redoValue = null;
-  }
-
-  clear() {
-    this.clearCount += 1;
-  }
-
-  pushSnapshot(level, label) {
-    this.snapshots.push({ level, label });
-    return true;
-  }
-
-  undo() {
-    return this.undoValue;
-  }
-
-  redo() {
-    return this.redoValue;
-  }
-}
-
-const buildSession = () => {
-  const session = new EditorSession();
-  const level = new EditorLevel();
-  level.setHeader('STYLE', 'dirt');
-  level.terrains = [];
-  level.gadgets = [];
-  session.level = level;
-  return session;
-};
-
-const buildAssets = () => {
-  const terrainMeta = { id: 2, name: 'terrain_2', width: 8, height: 8 };
-  const gadgetMeta = { id: 1, name: 'object_1', width: 8, height: 8, triggerEffectId: 0 };
-  const triggerMeta = { id: 3, name: 'object_3', width: 8, height: 8, triggerEffectId: 5 };
-  const exitMeta = { id: 4, name: 'object_4', width: 8, height: 8, triggerEffectId: 0 };
-  return {
-    terrain: [terrainMeta],
-    gadgets: [gadgetMeta],
-    triggers: [triggerMeta],
-    entranceId: 1,
-    exitId: 4,
-    terrainById: new Map([[terrainMeta.id, terrainMeta]]),
-    gadgetById: new Map([
-      [gadgetMeta.id, gadgetMeta],
-      [triggerMeta.id, triggerMeta],
-      [exitMeta.id, exitMeta]
-    ])
-  };
-};
-
-describe('EditorController', () => {
-  it('initializes selections and debounces preview updates', () => {
-    const session = buildSession();
-    const history = new FakeHistory();
-    const controller = new EditorController({ session, history, previewDelay: 5 });
-    controller.setAssets(buildAssets());
-
-    expect(controller.selectedTerrainId).to.equal(2);
-    expect(controller.selectedGadgetId).to.equal(1);
-    expect(controller.selectedTriggerId).to.equal(3);
-
-    const levelEvents = [];
-    const previewEvents = [];
-    const clock = FakeTimers.install({ now: 0, toFake: ['setTimeout', 'clearTimeout', 'Date'] });
-    controller.setCallbacks({
-      onLevelChange: level => levelEvents.push(level),
-      onPreviewRequest: label => previewEvents.push(label)
-    });
-
-    controller.updateHeader('TITLE', 'First');
-    controller.updateHeader('TITLE', 'Second');
-    expect(levelEvents).to.have.length(2);
-    expect(previewEvents).to.deep.equal([]);
-
-    clock.tick(5);
-    expect(previewEvents).to.deep.equal(['Header']);
-    clock.uninstall();
-
-    controller.resetHistory('Init');
-    expect(history.clearCount).to.equal(1);
-    expect(history.snapshots[0].label).to.equal('Init');
-  });
-
-  it('selects, drags, and clears selections', () => {
-    const session = buildSession();
-    const history = new FakeHistory();
-    const controller = new EditorController({ session, history });
-    controller.setAssets(buildAssets());
-
-    const terrainEntry = createTerrainEntry({ styleName: 'dirt', piece: 2, x: 10, y: 10 });
-    session.level.terrains.push(terrainEntry);
-
-    const selections = [];
-    controller.setCallbacks({ onSelectionChange: selection => selections.push(selection) });
-
-    controller.handlePointerDown({ x: 12, y: 12 }, 0);
-    expect(controller.getSelectedEntries()).to.have.length(1);
-    expect(controller.getSelectedEntries()[0].type).to.equal('terrain');
-
-    controller.handlePointerMove({ x: 20, y: 20 });
-    expect(terrainEntry.props.X).to.equal(18);
-    expect(terrainEntry.props.Y).to.equal(18);
-
-    controller.handlePointerUp();
-    expect(history.snapshots[0].label).to.equal('Move');
-    expect(selections.length).to.be.greaterThan(0);
-
-    const gadgetEntry = createGadgetEntry({ styleName: 'dirt', piece: 1, x: 30, y: 30 });
-    session.level.gadgets.push(gadgetEntry);
-    controller.handlePointerDown({ x: 31, y: 31 }, 0);
-    controller.handlePointerMove({ x: 40, y: 40 });
-    controller.handlePointerUp();
-
-    controller.handlePointerDown({ x: 0, y: 0 }, 2);
-    expect(controller.getSelectedEntries()).to.have.length(0);
-
-    controller.handlePointerDown({ x: 100, y: 100 }, 0);
-    expect(controller.getSelectedEntries()).to.have.length(0);
-
-    controller._selectHit(null);
-    expect(controller.getSelectedEntries()).to.have.length(0);
-  });
-
-  it('places terrain, gadgets, triggers, entrances, and exits', () => {
-    const session = buildSession();
-    const history = new FakeHistory();
-    const controller = new EditorController({ session, history, snapEnabled: false });
-    controller.setAssets(buildAssets());
-    controller.setSnapEnabled(false);
-
-    controller.setSelectedTerrain(2);
-    controller.setSelectedTerrain('bad');
-    controller.setTool(EditorTools.TERRAIN);
-    controller.handlePointerDown({ x: 5.2, y: 6.2 }, 0);
-    expect(session.level.terrains).to.have.length(1);
-    expect(session.level.terrains[0].props.X).to.equal(1);
-    expect(history.snapshots[0].label).to.equal('Terrain');
-
-    controller.setSelectedGadget(1);
-    controller.setSelectedGadget(undefined);
-    controller.setTool(EditorTools.GADGET);
-    controller.handlePointerDown({ x: 10, y: 12 }, 0);
-    expect(session.level.gadgets).to.have.length(1);
-    expect(history.snapshots[1].label).to.equal('Gadget');
-
-    controller.setSelectedTrigger(3);
-    controller.setTool(EditorTools.TRIGGER);
-    controller.handlePointerDown({ x: 14, y: 16 }, 0);
-    expect(session.level.gadgets[1].props.PIECE).to.equal(3);
-
-    controller.setSelectedTrigger('bad');
-    controller.selectedTriggerId = null;
-    controller.setTool(EditorTools.TRIGGER);
-    controller.handlePointerDown({ x: 18, y: 20 }, 0);
-    expect(session.level.gadgets[2].props.PIECE).to.equal(1);
-
-    for (let i = 0; i < 4; i++) {
-      session.level.gadgets.push(createGadgetEntry({ styleName: 'dirt', piece: 1, x: 1, y: 1 }));
-    }
-    controller.setTool(EditorTools.ENTRANCE);
-    controller.handlePointerDown({ x: 30, y: 40 }, 0);
-    const entranceCount = session.level.gadgets.filter(entry => entry.props.PIECE === 1).length;
-    expect(entranceCount).to.equal(4);
-
-    for (let i = 0; i < 4; i++) {
-      session.level.gadgets.push(createGadgetEntry({ styleName: 'dirt', piece: 4, x: 2, y: 2 }));
-    }
-    controller.setTool(EditorTools.EXIT);
-    controller.handlePointerDown({ x: 32, y: 44 }, 0);
-    const exitCount = session.level.gadgets.filter(entry => entry.props.PIECE === 4).length;
-    expect(exitCount).to.equal(4);
-
-    controller.setTool('unknown');
-    controller.handlePointerDown({ x: 0, y: 0 }, 0);
-  });
-
-  it('handles brush and eraser strokes', () => {
-    const session = buildSession();
-    const history = new FakeHistory();
-    const controller = new EditorController({ session, history, eraseGadgets: true });
-    controller.setAssets(buildAssets());
-
-    controller.setBrushSize(0);
-    expect(controller.brushSize).to.equal(1);
-    controller.setBrushSize(Number.NaN);
-    expect(controller.brushSize).to.equal(1);
-
-    controller.setTool(EditorTools.BRUSH);
-    controller.setBrushSize(2);
-    controller.handlePointerDown({ x: 5, y: 6 }, 0);
-    const countAfterDown = session.level.terrains.length;
-    controller.handlePointerMove({ x: 5, y: 6 }, { isDown: true });
-    controller.handlePointerMove({ x: 5, y: 6 }, { isDown: false });
-    expect(session.level.terrains).to.have.length(countAfterDown);
-    controller.handlePointerUp();
-    expect(history.snapshots[0].label).to.equal('Brush');
-
-    controller.setTool(EditorTools.ERASER);
-    controller.setEraseGadgets(true);
-    session.level.gadgets.push(createGadgetEntry({ styleName: 'dirt', piece: 1, x: 4, y: 4 }));
-    const terrainCount = session.level.terrains.length;
-    controller.handlePointerDown({ x: 4, y: 4 }, 0);
-    expect(session.level.terrains.length).to.be.lessThan(terrainCount);
-    expect(session.level.gadgets).to.have.length(0);
-    controller.handlePointerMove({ x: 4, y: 4 }, { isDown: true });
-    controller.handlePointerUp();
-    expect(history.snapshots.some(entry => entry.label === 'Erase')).to.equal(true);
-  });
-
-  it('stamps brush lines', () => {
-    const session = buildSession();
-    const controller = new EditorController({ session, gridSize: 4, snapEnabled: true });
-    controller.setAssets(buildAssets());
-    controller.setTool(EditorTools.BRUSH);
-    controller.setBrushSize(1);
-    controller.handlePointerDown({ x: 0, y: 0 }, 0);
-    controller.handlePointerMove({ x: 8, y: 0 }, { isDown: true });
-    controller.handlePointerUp();
-    expect(session.level.terrains).to.have.length(3);
-  });
-
-  it('stamps brush and eraser moves without a prior stroke', () => {
-    const session = buildSession();
-    const controller = new EditorController({ session, snapEnabled: false });
-    controller.setAssets(buildAssets());
-
-    controller.setTool(EditorTools.BRUSH);
-    const beforeBrush = session.level.terrains.length;
-    controller.handlePointerMove({ x: 6, y: 6 }, { isDown: true });
-    expect(session.level.terrains).to.have.length(beforeBrush + 1);
-    controller.handlePointerUp();
-
-    controller.setTool(EditorTools.ERASER);
-    const beforeErase = session.level.terrains.length;
-    controller.handlePointerMove({ x: 6, y: 6 }, { isDown: true });
-    expect(session.level.terrains.length).to.be.lessThan(beforeErase);
-  });
-
-  it('supports multi-select and marquee selection', () => {
-    const session = buildSession();
-    const history = new FakeHistory();
-    const controller = new EditorController({ session, history, snapEnabled: false });
-    controller.setAssets(buildAssets());
-    controller.setTool(EditorTools.SELECT);
-    const selectionEvents = [];
-    controller.setCallbacks({ onSelectionChange: selection => selectionEvents.push(selection) });
-
-    const entryA = createTerrainEntry({ styleName: 'dirt', piece: 2, x: 10, y: 10 });
-    const entryB = createTerrainEntry({ styleName: 'dirt', piece: 2, x: 30, y: 30 });
-    session.level.terrains.push(entryA, entryB);
-
-    controller.handlePointerDown({ x: 10, y: 10 }, 0);
-    controller.handlePointerUp();
-    controller.handlePointerDown({ x: 30, y: 30 }, 0, { shiftKey: true });
-    expect(controller.getSelectedEntries()).to.have.length(2);
-
-    controller.handlePointerDown({ x: 10, y: 10 }, 0);
-    controller.handlePointerMove({ x: 20, y: 20 });
-    controller.handlePointerUp();
-    expect(entryA.props.X).to.equal(20);
-    expect(entryB.props.X).to.equal(40);
-
-    controller.handlePointerDown({ x: 0, y: 0 }, 0);
-    controller.handlePointerMove({ x: 50, y: 50 }, { isDown: true });
-    controller.handlePointerUp();
-    expect(controller.getSelectedEntries()).to.have.length(2);
-    controller.handlePointerDown({ x: 20, y: 20 }, 0, { shiftKey: true });
-    expect(controller.getSelectedEntries()).to.have.length(1);
-    expect(selectionEvents.length).to.be.greaterThan(0);
-  });
-
-  it('supports steel placement and selection', () => {
-    const session = buildSession();
-    const history = new FakeHistory();
-    session.level.steel = null;
-    const controller = new EditorController({ session, history, snapEnabled: false, gridSize: 1 });
-    controller.setAssets(buildAssets());
-    const selectionEvents = [];
-    controller.setCallbacks({ onSelectionChange: entries => selectionEvents.push(entries) });
-    controller.setTool(EditorTools.STEEL);
-    controller.handlePointerDown({ x: 5, y: 6 }, 0);
-    controller.handlePointerMove({ x: 9, y: 10 });
-    controller.handlePointerUp();
-    expect(session.level.steel).to.have.length(1);
-    expect(selectionEvents.length).to.be.greaterThan(0);
-    expect(history.snapshots.some(entry => entry.label === 'Steel')).to.equal(true);
-
-    const steelHit = controller._findSelectionAt(6, 7);
-    expect(steelHit?.type).to.equal('steel');
-
-    controller.setTool(EditorTools.SELECT);
-    controller.handlePointerDown({ x: 6, y: 7 }, 0);
-    expect(controller.getSelectedEntries()[0].type).to.equal('steel');
-    expect(controller.deleteSelected()).to.equal(true);
-    expect(session.level.steel).to.have.length(0);
-  });
-
-  it('uses a 1px steel size when the grid is invalid', () => {
-    const session = buildSession();
-    session.level.steel = null;
-    const controller = new EditorController({ session, snapEnabled: false, gridSize: 0 });
-    controller.setAssets(buildAssets());
-    controller.setTool(EditorTools.STEEL);
-    controller.handlePointerDown({ x: 1, y: 2 }, 0);
-    controller.handlePointerUp();
-    expect(session.level.steel[0].props.WIDTH).to.equal(1);
-    expect(session.level.steel[0].props.HEIGHT).to.equal(1);
-  });
-
-  it('computes selection bounds for gadgets', () => {
-    const session = buildSession();
-    const controller = new EditorController({ session, snapEnabled: false });
-    controller.setAssets(buildAssets());
-    session.level.gadgets.push(createGadgetEntry({ styleName: 'dirt', piece: 1, x: 12, y: 14 }));
-    controller.selection = [{ type: 'gadget', index: 0 }];
-    const bounds = controller.getSelectionBounds();
-    expect(bounds.x).to.equal(12);
-    expect(bounds.y).to.equal(14);
-    expect(bounds.width).to.equal(8);
-  });
-
-  it('copies, pastes, duplicates, and nudges selections', () => {
-    const session = buildSession();
-    const history = new FakeHistory();
-    const controller = new EditorController({ session, history, gridSize: 4, snapEnabled: true });
-    controller.setAssets(buildAssets());
-
-    const terrainEntry = createTerrainEntry({ styleName: 'dirt', piece: 2, x: 8, y: 8 });
-    session.level.terrains.push(terrainEntry);
-    controller.selection = [{ type: 'terrain', index: 0 }];
-
-    expect(controller.copySelection()).to.equal(true);
-    expect(controller.pasteSelection()).to.equal(true);
-    expect(session.level.terrains).to.have.length(2);
-    expect(session.level.terrains[1].props.X).to.equal(12);
-
-    controller.selection = [{ type: 'terrain', index: 1 }];
-    expect(controller.duplicateSelection()).to.equal(true);
-    expect(session.level.terrains).to.have.length(3);
-    expect(session.level.terrains[2].props.X).to.equal(16);
-
-    controller.selection = [{ type: 'terrain', index: 2 }];
-    expect(controller.nudgeSelection(1, 0, 1)).to.equal(true);
-    expect(session.level.terrains[2].props.X).to.equal(17);
-
-    expect(controller.snapSelectionToGrid()).to.equal(true);
-    expect(session.level.terrains[2].props.X).to.equal(16);
-  });
-
-  it('coerces non-finite positions when copying', () => {
-    const session = buildSession();
-    const controller = new EditorController({ session, snapEnabled: false });
-    controller.setAssets(buildAssets());
-
-    const terrainEntry = createTerrainEntry({ styleName: 'dirt', piece: 2, x: 4, y: 4 });
-    terrainEntry.props.X = 'bad';
-    terrainEntry.props.Y = Number.NaN;
-    session.level.terrains.push(terrainEntry);
-    controller.selection = [{ type: 'terrain', index: 0 }];
-
-    expect(controller.copySelection()).to.equal(true);
-    expect(controller.pasteSelection()).to.equal(true);
-    expect(session.level.terrains[1].props.X).to.equal(1);
-    expect(session.level.terrains[1].props.Y).to.equal(1);
-  });
-
-  it('copies entries without props using defaults', () => {
-    const session = buildSession();
-    const controller = new EditorController({ session, snapEnabled: false });
-    controller.setAssets(buildAssets());
-    session.level.terrains.push({ props: null });
-    controller.selection = [{ type: 'terrain', index: 0 }];
-
-    expect(controller.copySelection()).to.equal(true);
-    expect(controller.pasteSelection()).to.equal(true);
-    expect(session.level.terrains[1].props.X).to.equal(1);
-  });
-
-  it('pastes steel selections with a steel uid prefix', () => {
-    const session = buildSession();
-    const controller = new EditorController({ session, snapEnabled: false });
-    controller.setAssets(buildAssets());
-    session.level.steel = [createSteelEntry({ x: 4, y: 6, width: 2, height: 2 })];
-    controller.selection = [{ type: 'steel', index: 0 }];
-
-    expect(controller.copySelection()).to.equal(true);
-    expect(controller.pasteSelection()).to.equal(true);
-    expect(session.level.steel).to.have.length(2);
-    expect(session.level.steel[1].uid.startsWith('s_')).to.equal(true);
-  });
-
-  it('pastes gadget selections with a gadget uid prefix', () => {
-    const session = buildSession();
-    const controller = new EditorController({ session, snapEnabled: false });
-    controller.setAssets(buildAssets());
-    session.level.gadgets.push(createGadgetEntry({ styleName: 'dirt', piece: 1, x: 2, y: 2 }));
-    controller.selection = [{ type: 'gadget', index: 0 }];
-
-    expect(controller.copySelection()).to.equal(true);
-    expect(controller.pasteSelection()).to.equal(true);
-    expect(session.level.gadgets).to.have.length(2);
-    expect(session.level.gadgets[1].uid.startsWith('g_')).to.equal(true);
-  });
-
-  it('returns false when snapping without a selection', () => {
-    const session = buildSession();
-    const controller = new EditorController({ session });
-    controller.setAssets(buildAssets());
-    expect(controller.snapSelectionToGrid()).to.equal(false);
-  });
-
-  it('snaps using a 1px grid when the grid size is invalid', () => {
-    const session = buildSession();
-    const controller = new EditorController({ session, gridSize: 0, snapEnabled: true });
-    controller.setAssets(buildAssets());
-    session.level.terrains.push(createTerrainEntry({ styleName: 'dirt', piece: 2, x: 4, y: 4 }));
-    session.level.terrains[0].props.X = 3.6;
-    session.level.terrains[0].props.Y = 4.4;
-    controller.selection = [{ type: 'terrain', index: 0 }];
-    expect(controller.snapSelectionToGrid()).to.equal(true);
-    expect(session.level.terrains[0].props.X).to.equal(4);
-    expect(session.level.terrains[0].props.Y).to.equal(4);
-  });
-
-  it('returns false when nudging without a selection', () => {
-    const session = buildSession();
-    const controller = new EditorController({ session });
-    expect(controller.nudgeSelection(1, 0, 1)).to.equal(false);
-  });
-
-  it('skips missing props when nudging and snapping', () => {
-    const session = buildSession();
-    const controller = new EditorController({ session, snapEnabled: true });
-    controller.setAssets(buildAssets());
-    const selectionEvents = [];
-    controller.setCallbacks({ onSelectionChange: entries => selectionEvents.push(entries) });
-    session.level.terrains.push({ props: null });
-    controller.selection = [{ type: 'terrain', index: 0 }];
-    expect(controller.nudgeSelection(1, 0, 1)).to.equal(true);
-    expect(controller.snapSelectionToGrid()).to.equal(true);
-    expect(selectionEvents.length).to.be.greaterThan(0);
-  });
-
-  it('uses 1px paste steps when snapping is disabled', () => {
-    const session = buildSession();
-    const controller = new EditorController({ session, gridSize: 4, snapEnabled: false });
-    controller.setAssets(buildAssets());
-
-    session.level.terrains.push(createTerrainEntry({ styleName: 'dirt', piece: 2, x: 8, y: 8 }));
-    controller.selection = [{ type: 'terrain', index: 0 }];
-    expect(controller.copySelection()).to.equal(true);
-    expect(controller.pasteSelection()).to.equal(true);
-    expect(session.level.terrains[1].props.X).to.equal(9);
-  });
-
-  it('returns false when clone/paste/duplicate have nothing to act on', () => {
-    const session = buildSession();
-    const controller = new EditorController({ session, snapEnabled: false });
-    controller.setAssets(buildAssets());
-    session.level.gadgets = null;
-
-    const cloneResult = controller._cloneSelection([
-      { type: 'gadget', index: 0, entry: { props: { X: 0, Y: 0 } } }
-    ], 0, 0);
-    expect(cloneResult).to.equal(null);
-
-    controller._clipboard = {
-      items: [{ type: 'gadget', entry: { props: { X: 0, Y: 0 } }, offsetX: 0, offsetY: 0 }],
-      minX: 0,
-      minY: 0
-    };
-    expect(controller.pasteSelection()).to.equal(false);
-    expect(controller.duplicateSelection()).to.equal(false);
-  });
-
-  it('duplicates selection with alt-drag', () => {
-    const session = buildSession();
-    const history = new FakeHistory();
-    const controller = new EditorController({
-      session,
-      history,
-      snapEnabled: false,
-      gridSize: 1,
-      handleSize: 2
-    });
-    controller.setAssets(buildAssets());
-    controller.setTool(EditorTools.SELECT);
-
-    const terrainEntry = createTerrainEntry({ styleName: 'dirt', piece: 2, x: 10, y: 10 });
-    session.level.terrains.push(terrainEntry);
-
-    controller.handlePointerDown({ x: 14, y: 14 }, 0);
-    controller.handlePointerUp();
-
-    controller.handlePointerDown({ x: 14, y: 14 }, 0, { altKey: true });
-    controller.handlePointerMove({ x: 16, y: 16 });
-    controller.handlePointerUp();
-
-    expect(session.level.terrains).to.have.length(2);
-    expect(history.snapshots.some(entry => entry.label === 'Duplicate')).to.equal(true);
-  });
-
-  it('handles additive marquee selection without duplicates', () => {
-    const session = buildSession();
-    const controller = new EditorController({ session, snapEnabled: false });
-    controller.setAssets(buildAssets());
-    controller.setTool(EditorTools.SELECT);
-
-    const entryA = createTerrainEntry({ styleName: 'dirt', piece: 2, x: 10, y: 10 });
-    session.level.terrains.push(entryA);
-
-    controller.handlePointerDown({ x: 10, y: 10 }, 0);
-    controller.handlePointerUp();
-
-    session.level.gadgets = null;
-    controller.handlePointerDown({ x: 0, y: 0 }, 0, { shiftKey: true });
-    controller.handlePointerMove({ x: 20, y: 20 }, { isDown: true });
-    controller.handlePointerUp();
-
-    expect(controller.getSelectedEntries()).to.have.length(1);
-  });
-
-  it('covers marquee intersection branches', () => {
-    const session = buildSession();
-    const controller = new EditorController({ session, snapEnabled: false });
-    controller.setAssets(buildAssets());
-    session.level.terrains.push(createTerrainEntry({ styleName: 'dirt', piece: 2, x: 10, y: 10 }));
-
-    const scenarios = [
-      { x: 20, y: 10, width: 2, height: 2 },
-      { x: 0, y: 10, width: 5, height: 2 },
-      { x: 10, y: 25, width: 8, height: 2 },
-      { x: 10, y: 0, width: 8, height: 5 },
-      { x: 12, y: 12, width: 2, height: 2 }
-    ];
-    const originalGetMarqueeBounds = controller.getMarqueeBounds.bind(controller);
-    for (const bounds of scenarios) {
-      controller._marquee = { startX: 0, startY: 0, x: 1, y: 1, additive: false };
-      controller.getMarqueeBounds = () => bounds;
-      controller._applyMarqueeSelection();
-    }
-    controller.getMarqueeBounds = originalGetMarqueeBounds;
-    controller._marquee = null;
-  });
-
-  it('notifies marquee callbacks', () => {
-    const session = buildSession();
-    const controller = new EditorController({ session });
-    const marqueeEvents = [];
-    controller.setCallbacks({ onMarqueeChange: bounds => marqueeEvents.push(bounds) });
-
-    controller._beginMarquee(0, 0, true);
-    controller._updateMarquee(5, 6);
-    controller._clearMarquee();
-
-    expect(marqueeEvents).to.have.length(3);
-    expect(marqueeEvents[0]).to.have.property('width');
-    expect(marqueeEvents[2]).to.equal(null);
-  });
-
-  it('uses a custom handle size', () => {
-    const session = buildSession();
-    const controller = new EditorController({ session, handleSize: 12 });
-    expect(controller.getHandleSize()).to.equal(12);
-  });
-
-  it('supports additive selection helpers', () => {
-    const session = buildSession();
-    const controller = new EditorController({ session, snapEnabled: false });
-    controller.setAssets(buildAssets());
-    controller.setTool(EditorTools.SELECT);
-    const selectionEvents = [];
-    controller.setCallbacks({ onSelectionChange: selection => selectionEvents.push(selection) });
-
-    const entryA = createTerrainEntry({ styleName: 'dirt', piece: 2, x: 10, y: 10 });
-    const entryB = createTerrainEntry({ styleName: 'dirt', piece: 2, x: 30, y: 30 });
-    session.level.terrains.push(entryA, entryB);
-
-    const firstHit = controller._findSelectionAt(10, 10);
-    const secondHit = controller._findSelectionAt(30, 30);
-    controller._selectHit(firstHit);
-    controller._selectHit(secondHit, { additive: true });
-    expect(controller.getSelectedEntries()).to.have.length(2);
-    expect(controller._isSelected('gadget', 0)).to.equal(false);
-    expect(selectionEvents.length).to.be.greaterThan(0);
-
-    const gadgetEntry = createGadgetEntry({ styleName: 'dirt', piece: 1, x: 5, y: 6 });
-    session.level.gadgets.push(gadgetEntry);
-    controller.selection = [{ type: 'gadget', index: 0 }];
-    const bounds = controller.getSelectionBounds();
-    expect(bounds.width).to.equal(8);
-    expect(bounds.height).to.equal(8);
-  });
-
-  it('supports on-canvas resize handles', () => {
-    const session = buildSession();
-    const history = new FakeHistory();
-    const controller = new EditorController({ session, history, snapEnabled: false, gridSize: 1 });
-    controller.setAssets(buildAssets());
-    controller.setTool(EditorTools.SELECT);
-    expect(controller.getHandleSize()).to.equal(2);
-
-    const entry = createSteelEntry({
-      x: 10,
-      y: 10,
-      width: 8,
-      height: 8
-    });
-    session.level.steel.push(entry);
-
-    controller.handlePointerDown({ x: 10, y: 10 }, 0);
-    controller.handlePointerUp();
-
-    const handleX = entry.props.X + entry.props.WIDTH;
-    const handleY = entry.props.Y + entry.props.HEIGHT;
-    controller.handlePointerDown({ x: handleX, y: handleY }, 0);
-    controller.handlePointerMove({ x: handleX + 4, y: handleY + 6 });
-    controller.handlePointerUp();
-
-    expect(entry.props.WIDTH).to.equal(12);
-    expect(entry.props.HEIGHT).to.equal(14);
-    expect(history.snapshots.some(entry => entry.label === 'Resize')).to.equal(true);
-  });
-
-  it('snaps resize handles when snapping is enabled', () => {
-    const session = buildSession();
-    const history = new FakeHistory();
-    const controller = new EditorController({ session, history, gridSize: 4 });
-    controller.setAssets(buildAssets());
-    controller.setTool(EditorTools.SELECT);
-
-    let selectionChanges = 0;
-    controller.setCallbacks({ onSelectionChange: () => selectionChanges++ });
-
-    const entry = createSteelEntry({
-      x: 8,
-      y: 8,
-      width: 8,
-      height: 8
-    });
-    session.level.steel.push(entry);
-
-    controller.handlePointerDown({ x: 8, y: 8 }, 0);
-    controller.handlePointerUp();
-
-    const handleX = entry.props.X + entry.props.WIDTH;
-    const handleY = entry.props.Y + entry.props.HEIGHT;
-    controller.handlePointerDown({ x: handleX, y: handleY }, 0);
-    controller.handlePointerMove({ x: handleX + 3, y: handleY + 3 });
-    controller.handlePointerUp();
-
-    expect(entry.props.WIDTH).to.equal(12);
-    expect(entry.props.HEIGHT).to.equal(12);
-    expect(selectionChanges).to.be.greaterThan(0);
-  });
-
-  it('clamps inverted resize handles', () => {
-    const session = buildSession();
-    const controller = new EditorController({ session, snapEnabled: false, gridSize: 1 });
-    controller.setAssets(buildAssets());
-    controller.setTool(EditorTools.SELECT);
-
-    const entry = createSteelEntry({
-      x: 10,
-      y: 10,
-      width: 8,
-      height: 8
-    });
-    session.level.steel.push(entry);
-
-    controller.handlePointerDown({ x: 10, y: 10 }, 0);
-    controller.handlePointerUp();
-
-    const right = entry.props.X + entry.props.WIDTH;
-    const bottom = entry.props.Y + entry.props.HEIGHT;
-    controller.handlePointerDown({ x: right, y: bottom }, 0);
-    controller.handlePointerMove({ x: entry.props.X - 5, y: entry.props.Y - 5 });
-    controller.handlePointerUp();
-    expect(entry.props.WIDTH).to.be.at.least(1);
-    expect(entry.props.HEIGHT).to.be.at.least(1);
-
-    controller.handlePointerDown({ x: entry.props.X, y: entry.props.Y }, 0);
-    controller.handlePointerMove({ x: entry.props.X + entry.props.WIDTH + 10, y: entry.props.Y + entry.props.HEIGHT + 10 });
-    controller.handlePointerUp();
-    expect(entry.props.WIDTH).to.be.at.least(1);
-    expect(entry.props.HEIGHT).to.be.at.least(1);
-  });
-
-  it('updates selected props, deletes entries, and supports undo/redo', () => {
-    const session = buildSession();
-    const history = new FakeHistory();
-    const controller = new EditorController({ session, history });
-    controller.setAssets(buildAssets());
-    const levelChanges = [];
-    const selectionUpdates = [];
-    controller.setCallbacks({
-      onLevelChange: level => levelChanges.push(level),
-      onSelectionChange: selection => selectionUpdates.push(selection)
-    });
-
-    const terrainEntry = createTerrainEntry({ styleName: 'dirt', piece: 2, x: 0, y: 0 });
-    session.level.terrains.push(terrainEntry);
-    controller.handlePointerDown({ x: 1, y: 1 }, 0);
-
-    const updated = controller.updateSelectedProps({ flip_horizontal: true, erase: false });
-    expect(updated).to.equal(true);
-    expect(terrainEntry.props.FLIP_HORIZONTAL).to.equal(true);
-    expect(terrainEntry.props).to.not.have.property('ERASE');
-
-    expect(controller.deleteSelected()).to.equal(true);
-    expect(session.level.terrains).to.have.length(0);
-    expect(controller.deleteSelected()).to.equal(false);
-    const gadgetEntry = createGadgetEntry({ styleName: 'dirt', piece: 1, x: 10, y: 10 });
-    session.level.gadgets.push(gadgetEntry);
-    controller.selection = [{ type: 'gadget', index: 0 }];
-    expect(controller.deleteSelected()).to.equal(true);
-    expect(session.level.gadgets).to.have.length(0);
-
-    const undoLevel = new EditorLevel();
-    undoLevel.setHeader('TITLE', 'Undo');
-    const redoLevel = new EditorLevel();
-    redoLevel.setHeader('TITLE', 'Redo');
-    history.undoValue = undoLevel;
-    history.redoValue = redoLevel;
-
-    expect(controller.undo()).to.equal(undoLevel);
-    expect(session.level).to.equal(undoLevel);
-    expect(controller.redo()).to.equal(redoLevel);
-    expect(levelChanges).to.deep.equal([undoLevel, redoLevel]);
-
-    history.undoValue = null;
-    history.redoValue = null;
-    expect(controller.undo()).to.equal(null);
-    expect(controller.redo()).to.equal(null);
-
-    controller.selection = [{ type: 'gadget', index: 5 }];
-    expect(controller.getSelectedEntry()).to.equal(null);
-    controller.selection = [];
-    expect(controller.updateSelectedProps({ X: 1 })).to.equal(false);
-    expect(selectionUpdates.length).to.be.greaterThan(0);
-
-    controller.selection = [{ type: 'gadget', index: 0 }];
-    controller.session.level.gadgets = null;
-    expect(controller.getSelectedEntry()).to.equal(null);
-  });
-
-  it('handles missing sessions safely', () => {
-    const history = new FakeHistory();
-    const controller = new EditorController({ session: null, history });
-    expect(controller.deleteSelected()).to.equal(false);
-    controller.handlePointerDown({ x: 1, y: 1 }, 0);
-    controller.handlePointerMove({ x: 1, y: 1 });
-    controller.handlePointerUp();
-    expect(controller._placeTerrainAt(1, 1)).to.equal(null);
-    expect(controller._placeGadgetAt(1, 1, 1)).to.equal(null);
-    controller._eraseAt(1, 1);
-    controller._removeGadgetsById(1);
-    expect(controller._findSelectionAt(0, 0)).to.equal(null);
-    controller.updateHeader('TITLE', 'Missing');
-  });
-
-  it('returns null lists without a session', () => {
-    const controller = new EditorController({ session: null });
-    expect(controller._getListForType('terrain')).to.equal(null);
-  });
-
-  it('uses fallback entrance and exit ids without assets', () => {
-    const session = buildSession();
-    const history = new FakeHistory();
-    const controller = new EditorController({ session, history, snapEnabled: false });
-    controller.setAssets(null);
-    controller.setSelectedGadget(5);
-
-    controller.setTool(EditorTools.ENTRANCE);
-    controller.handlePointerDown({ x: 1, y: 1 }, 0);
-    expect(session.level.gadgets[0].props.PIECE).to.equal(1);
-
-    controller.setTool(EditorTools.EXIT);
-    controller.handlePointerDown({ x: 2, y: 2 }, 0);
-    expect(session.level.gadgets[1].props.PIECE).to.equal(5);
-  });
-
-  it('preserves existing selections when assets change', () => {
-    const session = buildSession();
-    const history = new FakeHistory();
-    const controller = new EditorController({ session, history });
-    controller.selectedTerrainId = 9;
-    controller.selectedGadgetId = 8;
-    controller.selectedTriggerId = 7;
-    controller.setAssets(buildAssets());
-    expect(controller.selectedTerrainId).to.equal(2);
-    expect(controller.selectedGadgetId).to.equal(1);
-    expect(controller.selectedTriggerId).to.equal(3);
-    controller.setAssets(null);
-    expect(controller.assets).to.equal(null);
-  });
-
-  it('rounds positions when the grid size is disabled', () => {
-    const session = buildSession();
-    const history = new FakeHistory();
-    const controller = new EditorController({
-      session,
-      history,
-      gridSize: 0,
-      snapEnabled: true,
-      brushSize: 3
-    });
-    expect(controller.brushSize).to.equal(3);
-    controller.setAssets(buildAssets());
-    controller.setTool(EditorTools.TERRAIN);
-    controller.handlePointerDown({ x: 5.6, y: 5.2 }, 0);
-    expect(session.level.terrains[0].props.X).to.equal(2);
-    expect(session.level.terrains[0].props.Y).to.equal(1);
-  });
-
-  it('covers internal fallbacks', () => {
-    const session = buildSession();
-    const history = new FakeHistory();
-    const controller = new EditorController({ session, history, previewDelay: 5 });
-    const previewEvents = [];
-    const clock = FakeTimers.install({ now: 0, toFake: ['setTimeout', 'clearTimeout', 'Date'] });
-    controller.setCallbacks({ onPreviewRequest: label => previewEvents.push(label) });
-    session.level.terrains.push(createTerrainEntry({ styleName: 'dirt', piece: 2, x: 0, y: 0 }));
-    controller.setSnapEnabled(false);
-    controller.setSnapEnabled(true);
-    controller.resetHistory();
-    controller.setTool(null);
-    controller._requestPreview();
-    clock.tick(5);
-    clock.uninstall();
-    expect(previewEvents).to.deep.equal(['Update']);
-
-    controller._removeGadgetsById(null);
-    controller.session.level.gadgets = null;
-    controller._removeGadgetsById(1);
-    controller._trimGadgetsById(null, 1);
-    controller._trimGadgetsById(1, 1);
-    controller._updateMarquee(1, 1);
-    controller._applyMarqueeSelection();
-    controller._setSelection(null);
-    controller._toggleSelection(null);
-    controller.selection = null;
-    controller.getSelectedEntries();
-    controller.getMarqueeBounds();
-    controller.copySelection();
-    controller.pasteSelection();
-    controller._eraseLine(null, null);
-    controller._brushLine(null, null);
-
-    const originalSession = controller.session;
-    controller.session = null;
-    controller._placeSteelAt(0, 0, 1, 1);
-    controller._beginSteelDraft(0, 0);
-    controller.session = originalSession;
-
-    controller._steelDraft = null;
-    controller._updateSteelDraft(1, 1);
-    controller._steelDraft = { index: 0, startX: 0, startY: 0 };
-    controller.session.level.steel = null;
-    controller._updateSteelDraft(1, 1);
-    controller.session.level.steel = [];
-    controller._updateSteelDraft(1, 1);
-
-    controller._steelDraft = null;
-
-    const originalGetMarqueeBounds = controller.getMarqueeBounds.bind(controller);
-    controller.getMarqueeBounds = () => null;
-    controller._marquee = { startX: 0, startY: 0, x: 5, y: 5, additive: false };
-    controller._applyMarqueeSelection();
-    controller.getMarqueeBounds = originalGetMarqueeBounds;
-    controller._marquee = null;
-
-    controller.selection = [];
-    controller._resize = { handle: 'se', type: 'terrain', index: 0, bounds: { x: 0, y: 0, width: 4, height: 4 } };
-    controller.handlePointerMove({ x: 2, y: 2 });
-    controller._resize = null;
-
-    controller._drag = { entries: null };
-    controller.tool = EditorTools.SELECT;
-    controller.handlePointerMove({ x: 1, y: 1 }, { isDown: true });
-
-    controller._drag = { label: '', entries: [] };
-    controller._strokeChanged = true;
-    controller.handlePointerUp();
-  });
-
-  it('removes gadgets by id', () => {
-    const session = buildSession();
-    const controller = new EditorController({ session });
-    session.level.gadgets.push(createGadgetEntry({ styleName: 'dirt', piece: 1, x: 4, y: 4 }));
-    controller._removeGadgetsById(1);
-    expect(session.level.gadgets).to.have.length(0);
-  });
-
-  it('creates a default history when none is provided', () => {
-    const session = buildSession();
-    const controller = new EditorController({ session });
-    expect(controller.history).to.exist;
-  });
-
-  it('reorders selected entries across lists', () => {
-    const session = buildSession();
-    const history = new FakeHistory();
-    const controller = new EditorController({ session, history, snapEnabled: false });
-    const t0 = createTerrainEntry({ styleName: 'dirt', piece: 1, x: 0, y: 0 });
-    const t1 = createTerrainEntry({ styleName: 'dirt', piece: 2, x: 0, y: 0 });
-    const g0 = createGadgetEntry({ styleName: 'dirt', piece: 1, x: 0, y: 0 });
-    const g1 = createGadgetEntry({ styleName: 'dirt', piece: 2, x: 0, y: 0 });
-    const s0 = createSteelEntry({ x: 0, y: 0, width: 1, height: 1 });
-    const s1 = createSteelEntry({ x: 2, y: 2, width: 1, height: 1 });
-    session.level.terrains = [t0, t1];
-    session.level.gadgets = [g0, g1];
-    session.level.steel = [s0, s1];
-
-    controller._setSelection([
-      { type: 'terrain', index: 0 },
-      { type: 'gadget', index: 0 },
-      { type: 'steel', index: 0 }
-    ]);
-
-    expect(controller.bringSelectionToFront()).to.equal(true);
-    expect(session.level.terrains[1]).to.equal(t0);
-    expect(session.level.gadgets[1]).to.equal(g0);
-    expect(session.level.steel[1]).to.equal(s0);
-
-    expect(controller.sendSelectionToBack()).to.equal(true);
-    expect(session.level.terrains[0]).to.equal(t0);
-    expect(session.level.gadgets[0]).to.equal(g0);
-    expect(session.level.steel[0]).to.equal(s0);
-
-    controller._setSelection([{ type: 'terrain', index: 0 }]);
-    expect(controller.moveSelectionForward()).to.equal(true);
-    expect(session.level.terrains[1]).to.equal(t0);
-
-    expect(controller.moveSelectionBackward()).to.equal(true);
-    expect(session.level.terrains[0]).to.equal(t0);
-  });
-
-  it('covers reorder edge cases and selection bounds', () => {
-    const session = buildSession();
-    const controller = new EditorController({ session });
-    controller.setAssets(buildAssets());
-    const t0 = createTerrainEntry({ styleName: 'dirt', piece: 1, x: 0, y: 0 });
-    const t1 = createTerrainEntry({ styleName: 'dirt', piece: 2, x: 0, y: 0 });
-    session.level.terrains = [t0, t1];
-
-    controller.selection = [];
-    expect(controller.getSelectionBounds()).to.equal(null);
-    expect(controller._getResizeHandleAt(0, 0)).to.equal(null);
-    expect(controller._reorderSelection('front')).to.equal(false);
-
-    controller.selection = [{ type: 'terrain', index: 0 }];
-    expect(controller._reorderSelection('unknown')).to.equal(false);
-    controller.selection = [{ type: 'terrain', index: 5 }];
-    expect(controller._reorderSelection('front')).to.equal(false);
-
-    controller.selection = [{ type: 'terrain', index: 1 }];
-    controller.moveSelectionForward();
-    controller.selection = [{ type: 'terrain', index: 0 }];
-    expect(controller.getSelectionBounds().width).to.equal(8);
-
-    controller.selection = [
-      { type: 'terrain', index: 0 },
-      { type: 'terrain', index: 1 }
-    ];
-    controller.moveSelectionForward();
-    controller.moveSelectionBackward();
-
-    const steel = createSteelEntry({ x: 10, y: 10, width: 4, height: 4 });
-    session.level.steel = [steel];
-    controller.selection = [{ type: 'steel', index: 0 }];
-    expect(controller.getSelectionBounds().width).to.equal(4);
-    expect(controller._getResizeHandleAt(0, 0)).to.equal(null);
-  });
-
-  it('returns null when resize bounds are missing for steel selections', () => {
-    const controller = new EditorController({ session: null });
-    controller.selection = [{ type: 'steel', index: 0 }];
-    expect(controller._getResizeHandleAt(0, 0)).to.equal(null);
-  });
-
-  it('adds default entrances and exits when missing', () => {
-    const session = buildSession();
-    session.level.setHeader('WIDTH', 320);
-    session.level.setHeader('HEIGHT', 160);
-    const history = new FakeHistory();
-    const controller = new EditorController({ session, history, previewDelay: 5 });
-    controller.setAssets(buildAssets());
-    const previews = [];
-    const clock = FakeTimers.install({ now: 0, toFake: ['setTimeout', 'clearTimeout', 'Date'] });
-    controller.setCallbacks({ onPreviewRequest: label => previews.push(label) });
-
-    const result = controller.ensureDefaultEntrancesExits({ viewRect: { x: 0, y: 0, w: 320, h: 160 } });
-    expect(result).to.equal(true);
-    expect(session.level.gadgets.some(entry => entry.props.PIECE === 1)).to.equal(true);
-    expect(session.level.gadgets.some(entry => entry.props.PIECE === 4)).to.equal(true);
-
-    clock.tick(5);
-    expect(previews).to.eql(['Defaults']);
-    clock.uninstall();
-  });
-
-  it('handles default entrances with custom ids and missing headers', () => {
-    const session = buildSession();
-    session.level.setHeader('WIDTH', 'bad');
-    session.level.setHeader('HEIGHT', 0);
-    const history = new FakeHistory();
-    const controller = new EditorController({ session, history });
-    controller.setAssets(buildAssets());
-    const result = controller.ensureDefaultEntrancesExits({ entranceId: 99, exitId: 100 });
-    expect(result).to.equal(true);
-    const pieces = session.level.gadgets.map(entry => entry.props.PIECE);
-    expect(pieces).to.include(99);
-    expect(pieces).to.include(100);
-  });
-
-  it('falls back to asset arrays and handles missing gadget lists', () => {
-    const session = buildSession();
-    const controller = new EditorController({ session });
-    controller.setAssets({
-      terrain: [{ id: 5, width: 4, height: 5 }],
-      gadgets: [{ id: 6, width: 7, height: 8 }]
-    });
-    expect(controller._getTerrainMeta(5).width).to.equal(4);
-    expect(controller._getGadgetMeta(6).width).to.equal(7);
-    expect(controller._getTerrainMeta(99)).to.equal(null);
-
-    session.level.gadgets = null;
-    expect(controller._hasGadgetId(1)).to.equal(false);
-    expect(controller._hasGadgetId(Number.NaN)).to.equal(false);
-  });
-
-  it('returns false when ensuring defaults without a session', () => {
-    const controller = new EditorController({ session: null });
-    expect(controller.ensureDefaultEntrancesExits()).to.equal(false);
-  });
-
-  it('skips defaults when entrances and exits already exist', () => {
-    const session = buildSession();
-    session.level.setHeader('WIDTH', 320);
-    session.level.setHeader('HEIGHT', 160);
-    const history = new FakeHistory();
-    const controller = new EditorController({ session, history });
-    controller.setAssets(buildAssets());
-    session.level.gadgets.push(
-      createGadgetEntry({ styleName: 'dirt', piece: 1, x: 0, y: 0 }),
-      createGadgetEntry({ styleName: 'dirt', piece: 4, x: 10, y: 0 })
-    );
-    const result = controller.ensureDefaultEntrancesExits();
-    expect(result).to.equal(false);
-  });
-
-  it('clones entries while preserving uids', () => {
-    const entry = createTerrainEntry({ styleName: 'dirt', piece: 1, x: 0, y: 0 });
-    entry.uid = 't_keep';
-    const clone = __test__.cloneEntry(entry, { preserveUid: true });
-    expect(clone.uid).to.equal('t_keep');
-    expect(clone.props).to.deep.equal(entry.props);
-  });
-
-  it('assigns default entry uids when none are provided', () => {
-    const entry = createTerrainEntry({ styleName: 'dirt', piece: 1, x: 2, y: 3 });
-    delete entry.uid;
-    const clone = __test__.cloneEntry(entry);
-    expect(clone.uid.startsWith('e_')).to.equal(true);
-  });
-
-  it('assigns uids and clones gadget/steel entries', () => {
-    const session = buildSession();
-    const controller = new EditorController({ session });
-    controller.setAssets(buildAssets());
-    const gadget = createGadgetEntry({ styleName: 'dirt', piece: 1, x: 0, y: 0 });
-    const steel = createSteelEntry({ x: 1, y: 1, width: 2, height: 2 });
-    session.level.gadgets.push(gadget);
-    session.level.steel = [steel];
-    const cloned = controller._cloneSelection([
-      { type: 'gadget', index: 0, entry: gadget },
-      { type: 'steel', index: 0, entry: steel }
-    ], 1, 1);
-    expect(cloned).to.have.length(2);
-    expect(session.level.gadgets[1].uid.startsWith('g_')).to.equal(true);
-    expect(session.level.steel[1].uid.startsWith('s_')).to.equal(true);
-  });
-});
diff --git a/test/editor/editor-history.test.js b/test/editor/editor-history.test.js
index 2cd1da51..565fe95c 100644
--- a/test/editor/editor-history.test.js
+++ b/test/editor/editor-history.test.js
@@ -62,4 +62,113 @@ describe('EditorHistory', () => {
     history.clear();
     expect(history.undo()).to.equal(null);
   });
+
+  it('groups transaction snapshots into a single undo step', () => {
+    const history = new EditorHistory();
+    const base = new EditorLevel();
+    base.setHeader('TITLE', 'Base');
+    const mid = new EditorLevel();
+    mid.setHeader('TITLE', 'Mid');
+    const fin = new EditorLevel();
+    fin.setHeader('TITLE', 'Final');
+
+    expect(history.pushSnapshot(base, 'Base')).to.equal(true);
+    history.beginTransaction('Batch');
+    expect(history.pushSnapshot(mid, 'Mid')).to.equal(true);
+    expect(history.pushSnapshot(fin, 'Final')).to.equal(true);
+    expect(history.entries).to.have.length(1);
+    expect(history.endTransaction('Batch Done')).to.equal(true);
+
+    expect(history.entries).to.have.length(2);
+    expect(history.entries[1].label).to.equal('Batch Done');
+    expect(history.undo().getHeader('TITLE')).to.equal('Base');
+  });
+
+  it('supports nested transaction boundaries and cancellation', () => {
+    const history = new EditorHistory();
+    const base = new EditorLevel();
+    base.setHeader('TITLE', 'Base');
+    const branch = new EditorLevel();
+    branch.setHeader('TITLE', 'Branch');
+
+    expect(history.pushSnapshot(base, 'Base')).to.equal(true);
+    history.beginTransaction('Outer');
+    history.beginTransaction('Inner');
+    expect(history.pushSnapshot(branch, 'Inner Change')).to.equal(true);
+    expect(history.endTransaction('Inner Done')).to.equal(false);
+    expect(history.entries).to.have.length(1);
+    expect(history.endTransaction('Outer Done')).to.equal(true);
+    expect(history.entries).to.have.length(2);
+    expect(history.entries[1].label).to.equal('Outer Done');
+
+    history.beginTransaction('Cancel');
+    expect(history.pushSnapshot(base, 'Revert')).to.equal(true);
+    expect(history.cancelTransaction()).to.equal(true);
+    expect(history.entries).to.have.length(2);
+  });
+
+  it('reports byte stats and enforces memory-aware retention', () => {
+    const history = new EditorHistory({
+      maxEntries: 10,
+      maxBytes: 8,
+      writer: { write: level => level.text },
+      parser: { parse: text => ({ text }) }
+    });
+
+    expect(history.pushSnapshot({ text: 'aa' }, 'A')).to.equal(true);
+    expect(history.pushSnapshot({ text: 'bb' }, 'B')).to.equal(true);
+    expect(history.pushSnapshot({ text: 'cc' }, 'C')).to.equal(true);
+
+    expect(history.entries.map(entry => entry.text)).to.deep.equal(['bb', 'cc']);
+    expect(history.cursor).to.equal(1);
+    expect(history.getStats()).to.include({
+      entries: 2,
+      cursor: 1,
+      bytes: 8,
+      maxBytes: 8
+    });
+  });
+
+  it('keeps large sessions bounded by bytes during stress-style snapshot growth', () => {
+    const history = new EditorHistory({
+      maxEntries: 1000,
+      maxBytes: 4096,
+      writer: { write: level => level.text },
+      parser: { parse: text => ({ text }) }
+    });
+
+    for (let i = 0; i < 80; i += 1) {
+      const text = `${String(i).padStart(3, '0')}:${'x'.repeat(256)}`;
+      expect(history.pushSnapshot({ text }, 'Stress')).to.equal(true);
+      expect(history.getStats().bytes).to.be.at.most(4096);
+      expect(history.getStats().entries).to.be.lessThan(1000);
+    }
+
+    expect(history.entries.at(-1).text.startsWith('079:')).to.equal(true);
+    expect(history.getStats().bytes).to.be.at.most(4096);
+  });
+
+  it('coalesces nearby snapshots with the same label when configured', () => {
+    const originalNow = Date.now;
+    let now = 1000;
+    Date.now = () => now;
+    try {
+      const history = new EditorHistory({
+        coalesceWindowMs: 250,
+        writer: { write: level => level.text },
+        parser: { parse: text => ({ text }) }
+      });
+
+      expect(history.pushSnapshot({ text: 'a' }, 'Drag')).to.equal(true);
+      now += 100;
+      expect(history.pushSnapshot({ text: 'b' }, 'Drag')).to.equal(true);
+      expect(history.entries.map(entry => entry.text)).to.deep.equal(['b']);
+
+      now += 500;
+      expect(history.pushSnapshot({ text: 'c' }, 'Drag')).to.equal(true);
+      expect(history.entries.map(entry => entry.text)).to.deep.equal(['b', 'c']);
+    } finally {
+      Date.now = originalNow;
+    }
+  });
 });
diff --git a/test/editor/editor-level-loader.test.js b/test/editor/editor-level-loader.test.js
index 9d6f7451..62f9139d 100644
--- a/test/editor/editor-level-loader.test.js
+++ b/test/editor/editor-level-loader.test.js
@@ -1,7 +1,12 @@
 import { expect } from 'chai';
 import { EditorLevel } from '../../js/editor/EditorLevel.js';
 import { createClassicLevelData, loadEditorLevel } from '../../js/editor/EditorLevelLoader.js';
+import { createEditorLevelFromClassic } from '../../js/editor/ClassicLevelConverter.js';
 import { resetStyleRegistry, registerClassicStyles, registerStyle } from '../../js/editor/StyleRegistry.js';
+import { BinaryReader } from '../../js/data/BinaryReader.js';
+import { LevelReader } from '../../js/level/LevelReader.js';
+import { LevelWriter } from '../../js/level/LevelWriter.js';
+import { toMidiFlagTriggerType } from '../../js/midi/MidiFlagTriggers.js';
 
 const buildEntry = (props) => ({ props, order: Object.keys(props), unknownLines: [] });
 
@@ -199,12 +204,170 @@ describe('EditorLevelLoader', () => {
     expect(reader.terrains[0].id).to.equal(4);
     expect(reader.terrains[0].drawProperties.isUpsideDown).to.equal(true);
     expect(reader.terrains[0].drawProperties.isErase).to.equal(true);
+    expect(reader.terrains[0].drawProperties).to.not.have.property('oneWay');
+    expect(reader.terrains[0].drawProperties).to.not.have.property('isOneWay');
     expect(reader.objects[0].id).to.equal(3);
     expect(reader.objects[0].drawProperties.noOverwrite).to.equal(true);
     expect(reader.steel).to.have.length(1);
     expect(reader.steel[0].width).to.equal(6);
   });
 
+  it('does not lower editor terrain one-way flags into classic terrain data', () => {
+    resetStyleRegistry();
+    registerStyle('preview', {
+      groundSet: 2,
+      terrainPieces: [{ id: 4, name: 'block' }]
+    });
+    const level = buildLevel();
+    level.terrains[0].props.ONE_WAY = true;
+
+    const data = createClassicLevelData(level, { styleName: 'preview' });
+    const terrain = data.levelReader.terrains[0];
+
+    expect(terrain.drawProperties).to.not.have.property('oneWay');
+    expect(terrain.drawProperties).to.not.have.property('isOneWay');
+  });
+
+  it('returns lossy classic export warnings and caps binary lists', () => {
+    resetStyleRegistry();
+    registerStyle('preview', {
+      groundSet: 2,
+      terrainPieces: [{ id: 0, name: 'block' }],
+      gadgetPieces: [{ id: 0, name: 'exit' }]
+    });
+    const level = buildLevel();
+    level.setHeader('TITLE', 'This title is definitely longer than thirty two characters');
+    level.terrainGroups = [{ terrains: [buildEntry({ STYLE: 'preview', PIECE: 'block', X: 1, Y: 2 })] }];
+    level.terrains = Array.from({ length: 401 }, (_, index) => buildEntry({
+      STYLE: 'preview',
+      PIECE: 'block',
+      X: index,
+      Y: 0,
+      ONE_WAY: index === 0 ? true : undefined
+    }));
+    level.gadgets = Array.from({ length: 33 }, (_, index) => buildEntry({
+      STYLE: 'preview',
+      PIECE: 'exit',
+      X: index,
+      Y: 0,
+      MIDI_FLAG: index === 0 ? true : undefined
+    }));
+    level.steel = Array.from({ length: 33 }, (_, index) => buildEntry({
+      X: index,
+      Y: 0,
+      WIDTH: 4,
+      HEIGHT: 4,
+      PIECE: index === 0 ? 1 : undefined
+    }));
+
+    const data = createClassicLevelData(level, { styleName: 'preview' });
+    const codes = data.warnings.map(warning => warning.code);
+
+    expect(data.metadata).to.deep.equal({ format: 'classicLvl', lossy: true });
+    expect(data.levelReader.levelProperties.levelName).to.have.length(32);
+    expect(data.levelReader.terrains).to.have.length(400);
+    expect(data.levelReader.objects).to.have.length(32);
+    expect(data.levelReader.steel).to.have.length(32);
+    expect(codes).to.include.members([
+      'classic_title_length',
+      'classic_terrain_groups',
+      'classic_unsupported_terrain_props',
+      'classic_unsupported_gadget_props',
+      'classic_unsupported_steel_props',
+      'classic_terrains_count',
+      'classic_gadgets_count',
+      'classic_steel_count'
+    ]);
+    expect(data.warnings.find(warning => warning.code === 'classic_unsupported_terrain_props').props)
+      .to.include('ONE_WAY');
+    expect(data.warnings.find(warning => warning.code === 'classic_unsupported_gadget_props').props)
+      .to.include('MIDI_FLAG');
+    expect(data.warnings.every(warning => warning.destructive)).to.equal(true);
+  });
+
+  it('documents lossy classic export/import for unsupported editor metadata', () => {
+    resetStyleRegistry();
+    registerStyle('preview', {
+      groundSet: 2,
+      terrainPieces: [{ id: 4, name: 'block' }],
+      gadgetPieces: [{ id: 3, name: 'plain-object' }]
+    });
+    const level = new EditorLevel();
+    level.setHeader('TITLE', 'This title is definitely longer than thirty two characters');
+    level.setHeader('STYLE', 'preview');
+    level.terrains = [
+      buildEntry({
+        STYLE: 'preview',
+        PIECE: 'block',
+        X: 10,
+        Y: 20,
+        ONE_WAY: true
+      })
+    ];
+    level.gadgets = [
+      buildEntry({
+        STYLE: 'preview',
+        PIECE: 'plain-object',
+        X: 48,
+        Y: 64,
+        MIDI_FLAG: true,
+        MIDI_FLAG_ID: 7
+      })
+    ];
+    level.unknownSections = [{ name: 'NEOLEMMIX_ONLY', lines: ['CUSTOM value'] }];
+
+    const classic = createClassicLevelData(level, { styleName: 'preview' });
+    const bytes = new LevelWriter().write(classic.levelReader);
+    const reader = new LevelReader(new BinaryReader(bytes));
+    const imported = createEditorLevelFromClassic(reader, { styleName: 'preview' });
+
+    expect(classic.metadata.lossy).to.equal(true);
+    expect(classic.warnings.map(warning => warning.code)).to.include.members([
+      'classic_title_length',
+      'classic_preserved_nxlv_metadata',
+      'classic_unsupported_terrain_props',
+      'classic_unsupported_gadget_props'
+    ]);
+    expect(imported.getHeader('TITLE')).to.have.length(32);
+    expect(imported.terrains[0].props).to.not.have.property('ONE_WAY');
+    expect(imported.gadgets[0].props).to.not.have.property('MIDI_FLAG');
+    expect(imported.gadgets[0].props).to.not.have.property('MIDI_FLAG_ID');
+    expect(imported.unknownSections).to.deep.equal([]);
+  });
+
+  it('round-trips classic gadgets without modifier flags through binary export/import', () => {
+    resetStyleRegistry();
+    registerStyle('preview', {
+      groundSet: 2,
+      gadgetPieces: [{ id: 3, name: 'plain-object' }]
+    });
+    const level = new EditorLevel();
+    level.setHeader('TITLE', 'Plain Gadget');
+    level.setHeader('STYLE', 'preview');
+    level.gadgets = [
+      buildEntry({
+        STYLE: 'preview',
+        PIECE: 'plain-object',
+        X: 48,
+        Y: 64
+      })
+    ];
+
+    const classic = createClassicLevelData(level, { styleName: 'preview' });
+    const bytes = new LevelWriter().write(classic.levelReader);
+    const reader = new LevelReader(new BinaryReader(bytes));
+    const imported = createEditorLevelFromClassic(reader, { styleName: 'preview' });
+
+    expect(reader.objects).to.have.length(1);
+    expect(imported.gadgets).to.have.length(1);
+    expect(imported.gadgets[0].props).to.include({
+      STYLE: 'preview',
+      PIECE: 3,
+      X: 48,
+      Y: 64
+    });
+  });
+
   it('falls back to default style values and ignores unknown skills', () => {
     resetStyleRegistry();
     registerStyle('alpha', { groundSet: 5 });
@@ -345,6 +508,99 @@ describe('EditorLevelLoader', () => {
     expect(runtime.newSetSteelAreasArgs).to.equal(null);
   });
 
+  it('extracts midi flag triggers using trigger bounds and strict enabled semantics', async () => {
+    resetStyleRegistry();
+    registerStyle('preview', {
+      groundSet: 3,
+      gadgetPieces: [{ id: 0, name: 'flagobj' }]
+    });
+    const level = new EditorLevel();
+    level.setHeader('STYLE', 'preview');
+    level.gadgets = [
+      buildEntry({
+        STYLE: 'preview',
+        PIECE: 'flagobj',
+        X: 10,
+        Y: 20,
+        MIDI_FLAG: true,
+        MIDI_FLAG_ID: 5,
+        MIDI_FLAG_COOLDOWN: 12
+      }),
+      buildEntry({
+        STYLE: 'preview',
+        PIECE: 'flagobj',
+        X: 30,
+        Y: 40,
+        MIDI_FLAG: true
+      }),
+      buildEntry({
+        STYLE: 'preview',
+        PIECE: 'flagobj',
+        X: 50,
+        Y: 60,
+        MIDI_FLAG: false,
+        MIDI_FLAG_ID: 8
+      })
+    ];
+    const { deps, fileProvider } = createFakeDeps();
+    const GroundReaderWithTriggers = class extends deps.GroundReader {
+      constructor(ground, terrain, objects) {
+        super(ground, terrain, objects);
+        this.objectImages = [{
+          id: 0,
+          width: 16,
+          height: 10,
+          trigger_left: 2,
+          trigger_top: 3,
+          trigger_width: 4,
+          trigger_height: 5
+        }];
+      }
+    };
+    const runtime = await loadEditorLevel(level, { gametype: 1, path: 'game' }, fileProvider, {
+      ...deps,
+      GroundReader: GroundReaderWithTriggers
+    });
+    expect(runtime.midiFlags).to.deep.equal([
+      {
+        id: 5,
+        triggerType: toMidiFlagTriggerType(5),
+        pieceId: 0,
+        x1: 12,
+        y1: 23,
+        x2: 16,
+        y2: 28,
+        cooldownTicks: 12
+      },
+      {
+        id: 1,
+        triggerType: toMidiFlagTriggerType(1),
+        pieceId: 0,
+        x1: 32,
+        y1: 43,
+        x2: 36,
+        y2: 48,
+        cooldownTicks: 8
+      }
+    ]);
+  });
+
+  it('extracts midi flags with fallback dimensions when trigger bounds are unavailable', async () => {
+    resetStyleRegistry();
+    registerStyle('preview', { groundSet: 3 });
+    const level = buildLevel();
+    level.gadgets[0].props.MIDI_FLAG = true;
+    const { deps, fileProvider } = createFakeDeps();
+    const runtime = await loadEditorLevel(level, { gametype: 1, path: 'game' }, fileProvider, deps);
+    expect(runtime.midiFlags).to.have.length(1);
+    expect(runtime.midiFlags[0].id).to.equal(1);
+    expect(runtime.midiFlags[0].x1).to.equal(30);
+    expect(runtime.midiFlags[0].y1).to.equal(40);
+    expect(runtime.midiFlags[0].x2).to.equal(38);
+    expect(runtime.midiFlags[0].y2).to.equal(48);
+    expect(runtime.midiFlags[0].cooldownTicks).to.equal(8);
+  });
+
   it('skips steel processing when no steel ranges are provided', async () => {
     resetStyleRegistry();
     registerStyle('preview', { groundSet: 1 });
diff --git a/test/editor/editor-preview-cache.test.js b/test/editor/editor-preview-cache.test.js
new file mode 100644
index 00000000..9e986858
--- /dev/null
+++ b/test/editor/editor-preview-cache.test.js
@@ -0,0 +1,168 @@
+import { expect } from 'chai';
+import { EditorPreviewCache } from '../../js/app/editorPreviewCache.js';
+
+class FakeStorage {
+  constructor() {
+    this._map = new Map();
+  }
+
+  get length() {
+    return this._map.size;
+  }
+
+  key(index) {
+    return Array.from(this._map.keys())[index] ?? null;
+  }
+
+  getItem(key) {
+    return this._map.has(key) ? this._map.get(key) : null;
+  }
+
+  setItem(key, value) {
+    this._map.set(key, String(value));
+  }
+
+  removeItem(key) {
+    this._map.delete(key);
+  }
+}
+
+const buildPalette = (seed = 0, version = null) => ({
+  ...(version == null ? {} : { version }),
+  getColor(index) {
+    const colors = [
+      0xff101010 + seed,
+      0xff202020 + seed,
+      0xff303030 + seed,
+      0xff404040 + seed
+    ];
+    return colors[index % colors.length] >>> 0;
+  }
+});
+
+const buildImage = (pixels) => ({
+  width: 2,
+  height: 2,
+  frames: [Uint8Array.from(pixels)],
+  palette: buildPalette()
+});
+
+const createCanvasDocument = () => {
+  let renderCount = 0;
+  return {
+    get renderCount() {
+      return renderCount;
+    },
+    createElement(tag) {
+      if (tag !== 'canvas') {
+        throw new Error(`Unexpected element: ${tag}`);
+      }
+      return {
+        width: 0,
+        height: 0,
+        getContext() {
+          return {
+            createImageData(width, height) {
+              return { data: new Uint8ClampedArray(width * height * 4) };
+            },
+            putImageData() {}
+          };
+        },
+        toDataURL() {
+          renderCount += 1;
+          return `data:image/png;base64,preview-${renderCount}`;
+        }
+      };
+    }
+  };
+};
+
+describe('EditorPreviewCache', () => {
+  it('reuses generated previews from memory/storage', () => {
+    const document = createCanvasDocument();
+    const storage = new FakeStorage();
+    const cache = new EditorPreviewCache({ document, storage });
+    const image = buildImage([0, 1, 2, 3]);
+
+    const first = cache.getPreviewUrl({ type: 'terrain', id: 1, image });
+    const second = cache.getPreviewUrl({ type: 'terrain', id: 1, image });
+    expect(first).to.be.a('string');
+    expect(second).to.equal(first);
+    expect(document.renderCount).to.equal(1);
+  });
+
+  it('enforces memory LRU size without losing persisted previews', () => {
+    const document = createCanvasDocument();
+    const storage = new FakeStorage();
+    const cache = new EditorPreviewCache({
+      document,
+      storage,
+      maxMemoryEntries: 1
+    });
+
+    const imageA = buildImage([0, 1, 2, 3]);
+    const imageB = buildImage([1, 2, 3, 0]);
+    const urlA = cache.getPreviewUrl({ type: 'terrain', id: 1, image: imageA });
+    const urlB = cache.getPreviewUrl({ type: 'terrain', id: 2, image: imageB });
+    expect(urlA).to.not.equal(urlB);
+    expect(cache.memory.size).to.equal(1);
+
+    const urlAFromStorage = cache.getPreviewUrl({ type: 'terrain', id: 1, image: imageA });
+    expect(urlAFromStorage).to.equal(urlA);
+    expect(document.renderCount).to.equal(2);
+  });
+
+  it('invalidates stale type/id entries during style reloads', () => {
+    const document = createCanvasDocument();
+    const storage = new FakeStorage();
+    const cache = new EditorPreviewCache({ document, storage });
+    const imageA = buildImage([0, 1, 2, 3]);
+    const imageB = buildImage([1, 2, 3, 0]);
+
+    cache.getPreviewUrl({ type: 'terrain', id: 1, image: imageA });
+    cache.getPreviewUrl({ type: 'terrain', id: 2, image: imageB });
+    expect(document.renderCount).to.equal(2);
+
+    cache.invalidateTypeIds('terrain', [1]);
+    const terrainKeys = [];
+    for (let i = 0; i < storage.length; i += 1) {
+      terrainKeys.push(storage.key(i));
+    }
+    expect(terrainKeys.some(key => key.includes(':terrain:2:'))).to.equal(false);
+
+    cache.getPreviewUrl({ type: 'terrain', id: 2, image: imageB });
+    expect(document.renderCount).to.equal(3);
+  });
+
+  it('keys preview signatures by image and palette identity', () => {
+    const document = createCanvasDocument();
+    const storage = new FakeStorage();
+    const cache = new EditorPreviewCache({ document, storage });
+    const image = buildImage([0, 1, 2, 3]);
+
+    const first = cache.getPreviewUrl({ type: 'terrain', id: 1, image });
+    image.palette = buildPalette(5);
+    const second = cache.getPreviewUrl({ type: 'terrain', id: 1, image });
+    const third = cache.getPreviewUrl({ type: 'terrain', id: 1, image });
+
+    expect(second).to.not.equal(first);
+    expect(third).to.equal(second);
+    expect(document.renderCount).to.equal(2);
+  });
+
+  it('reports cache stats and clears memory state on dispose', () => {
+    const document = createCanvasDocument();
+    const storage = new FakeStorage();
+    const cache = new EditorPreviewCache({ document, storage });
+
+    cache.getPreviewUrl({ type: 'terrain', id: 1, image: buildImage([0, 1, 2, 3]) });
+    expect(cache.getStats()).to.include({
+      memoryEntries: 1,
+      maxMemoryEntries: 512,
+      storageAvailable: true
+    });
+
+    cache.dispose();
+    expect(cache.getStats().memoryEntries).to.equal(0);
+  });
+});
diff --git a/test/editor/editor-storage.test.js b/test/editor/editor-storage.test.js
index cdc70f23..d9561f2c 100644
--- a/test/editor/editor-storage.test.js
+++ b/test/editor/editor-storage.test.js
@@ -63,6 +63,20 @@ describe('EditorStorage', () => {
     expect(list[3].updatedAt).to.equal(0);
   });
 
+  it('migrates legacy array index payloads to versioned envelopes', () => {
+    const storage = new MemoryStorage();
+    storage.setItem(STORAGE_KEYS.index, JSON.stringify([
+      { id: 'a', name: 'Alpha', updatedAt: 2 },
+      { id: 'b', name: 'Beta', updatedAt: 1 }
+    ]));
+    const list = listSavedLevels(storage);
+    expect(list.map((entry) => entry.id)).to.deep.equal(['a', 'b']);
+    const migrated = JSON.parse(storage.getItem(STORAGE_KEYS.index));
+    expect(migrated.version).to.equal(2);
+    expect(migrated.entries).to.be.an('array');
+    expect(migrated.entries).to.have.length(2);
+  });
+
   it('orders names in both directions', () => {
     const storage = new MemoryStorage();
     storage.setItem(STORAGE_KEYS.index, JSON.stringify([
@@ -149,6 +163,9 @@ describe('EditorStorage', () => {
     const list = listSavedLevels(storage);
     expect(list).to.have.length(1);
     expect(list[0].name).to.equal('First');
+    const indexPayload = JSON.parse(storage.getItem(STORAGE_KEYS.index));
+    expect(indexPayload.version).to.equal(2);
+    expect(indexPayload.entries).to.be.an('array');
   });
 
   it('uses Date.now when updatedAt is not finite', () => {
diff --git a/test/editor/editor-tools.test.js b/test/editor/editor-tools.test.js
index ecae36dd..fa502129 100644
--- a/test/editor/editor-tools.test.js
+++ b/test/editor/editor-tools.test.js
@@ -9,6 +9,7 @@ describe('EditorTools', () => {
       EditorTools.TERRAIN,
       EditorTools.GADGET,
       EditorTools.TRIGGER,
+      EditorTools.MIDI_FLAG,
       EditorTools.ENTRANCE,
       EditorTools.EXIT,
       EditorTools.STEEL,
diff --git a/test/editor/editor-ui-controller.lifecycle.test.js b/test/editor/editor-ui-controller.lifecycle.test.js
new file mode 100644
index 00000000..1bfb287f
--- /dev/null
+++ b/test/editor/editor-ui-controller.lifecycle.test.js
@@ -0,0 +1,371 @@
+import { expect } from 'chai';
+import { EditorUiController } from '../../js/app/editorUiController.js';
+import { EditorLevel } from '../../js/editor/EditorLevel.js';
+import { EventHandler } from '../../js/util/EventHandler.js';
+import { TestDocument, TestElement, createTestWindow } from '../helpers/test-dom.js';
+import { registerElement } from '../support/dom-fixtures.js';
+
+if (!TestElement.prototype.removeEventListener) {
+  TestElement.prototype.removeEventListener = function(type, handler) {
+    const handlers = this.listeners.get(type) || [];
+    this.listeners.set(type, handlers.filter(next => next !== handler));
+  };
+}
+
+const flush = async () => {
+  await Promise.resolve();
+  await Promise.resolve();
+};
+
+const createControllerStub = () => ({
+  tool: 'select',
+  history: {
+    pushSnapshot() {},
+    canUndo() { return false; },
+    canRedo() { return false; }
+  },
+  setCallbacks(callbacks) {
+    this.callbacks = callbacks;
+  },
+  setTool(tool) {
+    this.tool = tool;
+  },
+  clearSelection() {},
+  resetHistory() {},
+  setAssets() {},
+  getSelectedEntries() { return []; },
+  getMarqueeBounds() { return null; },
+  dispose() {
+    this.disposed = true;
+  }
+});
+
+const createSelectionPanelElements = (doc) => {
+  const makeInput = () => doc.createElement('input');
+  const makeCheck = () => doc.createElement('input');
+  const makeText = () => doc.createElement('span');
+  return {
+    selType: makeText(),
+    selName: makeText(),
+    selX: makeInput(),
+    selY: makeInput(),
+    selWidth: makeInput(),
+    selHeight: makeInput(),
+    selRotate: makeInput(),
+    selSkill: makeInput(),
+    selLemmings: makeInput(),
+    selPairing: makeInput(),
+    selMidiFlag: makeCheck(),
+    selMidiFlagId: makeInput(),
+    selFlipH: makeCheck(),
+    selFlipV: makeCheck(),
+    selNoOverwrite: makeCheck(),
+    selErase: makeCheck(),
+    selOneWay: makeCheck(),
+    deleteSelection: doc.createElement('button')
+  };
+};
+
+describe('EditorUiController lifecycle', function() {
+  it('binds UI events idempotently and removes tracked listeners on dispose', function() {
+    const doc = new TestDocument();
+    const win = createTestWindow();
+    const toolList = registerElement(doc, 'div', 'editorToolList');
+    const paletteTabs = registerElement(doc, 'div', 'editorPaletteTabs');
+    const search = registerElement(doc, 'input', 'editorPaletteSearch');
+    const controller = createControllerStub();
+    const ui = new EditorUiController({
+      document: doc,
+      window: win,
+      view: null,
+      controller
+    });
+
+    ui._bindEvents();
+    ui._bindEvents();
+
+    expect(toolList.listeners.get('click')).to.have.lengthOf(1);
+    expect(paletteTabs.listeners.get('click')).to.have.lengthOf(1);
+    expect(search.listeners.get('input')).to.have.lengthOf(1);
+
+    ui.dispose();
+
+    expect(toolList.listeners.get('click')).to.have.lengthOf(0);
+    expect(paletteTabs.listeners.get('click')).to.have.lengthOf(0);
+    expect(search.listeners.get('input')).to.have.lengthOf(0);
+    expect(controller.disposed).to.equal(true);
+  });
+
+  it('detaches display handlers on dispose', function() {
+    const doc = new TestDocument();
+    const win = createTestWindow();
+    const display = {
+      onMouseDown: new EventHandler(),
+      onMouseRightDown: new EventHandler(),
+      onMouseUp: new EventHandler(),
+      onMouseRightUp: new EventHandler(),
+      onMouseMove: new EventHandler()
+    };
+    const controller = createControllerStub();
+    const ui = new EditorUiController({
+      document: doc,
+      window: win,
+      view: null,
+      controller
+    });
+    ui.view = {
+      stage: {
+        getGameDisplay() {
+          return display;
+        }
+      }
+    };
+
+    ui._bindCanvasInput();
+    expect(display.onMouseDown.handlers.size).to.equal(1);
+    expect(display.onMouseMove.handlers.size).to.equal(1);
+
+    ui.dispose();
+
+    expect(display.onMouseDown.handlers.size).to.equal(0);
+    expect(display.onMouseMove.handlers.size).to.equal(0);
+  });
+
+  it('renders validation issues as list items', function() {
+    const doc = new TestDocument();
+    const issuesList = registerElement(doc, 'div', 'editorIssuesList');
+    const ui = Object.create(EditorUiController.prototype);
+    ui.document = doc;
+    ui.el = { issuesList };
+
+    ui._renderIssues([{
+      severity: 'error',
+      message: 'Missing entrance.',
+      fixLabel: 'Add entrance',
+      fix: () => {}
+    }]);
+
+    expect(ui._hasErrors).to.equal(true);
+    expect(issuesList.children).to.have.lengthOf(1);
+    const issueItem = issuesList.children.find(child => child.classList.contains('issue-item'));
+    expect(issueItem).to.exist;
+    expect(issueItem.getAttribute('role')).to.equal('listitem');
+    expect(issueItem.getAttribute('data-severity')).to.equal('error');
+    expect(issueItem.getAttribute('aria-label')).to.equal('Error: Missing entrance.');
+
+    const severity = issueItem.children.find(child => child.classList.contains('issue-severity'));
+    expect(severity?.textContent).to.equal('Error');
+
+    const message = issueItem.children.find(child => child.classList.contains('issue-message'));
+    expect(message?.textContent).to.equal('Missing entrance.');
+
+    const action = issueItem.children.find(child => child.classList.contains('issue-action'));
+    expect(action?.tagName).to.equal('BUTTON');
+    expect(action?.textContent).to.equal('Add entrance');
+    expect(action?.title).to.equal('Apply fix: Add entrance');
+  });
+
+  it('marks destructive validation quick fixes', function() {
+    const doc = new TestDocument();
+    const issuesList = registerElement(doc, 'div', 'editorIssuesList');
+    const ui = Object.create(EditorUiController.prototype);
+    ui.document = doc;
+    ui.el = { issuesList };
+
+    ui._renderIssues([{
+      severity: 'warning',
+      message: 'Terrain entries include unsupported classic properties.',
+      fixLabel: 'Remove unsupported terrain props',
+      fix: () => {}
+    }]);
+
+    const issueItem = issuesList.children.find(child => child.classList.contains('issue-item'));
+    expect(issueItem.getAttribute('data-fix')).to.equal('destructive');
+    const note = issueItem.children.find(child => child.classList.contains('issue-note'));
+    expect(note?.textContent).to.contain('Destructive quick fix');
+    const action = issueItem.children.find(child => child.classList.contains('issue-action'));
+    expect(action.classList.contains('destructive')).to.equal(true);
+    expect(action.title).to.equal('Destructive quick fix: Remove unsupported terrain props');
+  });
+
+  it('adds classic-subset warnings for preserved NXLV data and lossy LVL export', function() {
+    const doc = new TestDocument();
+    const issuesList = registerElement(doc, 'div', 'editorIssuesList');
+    const level = new EditorLevel();
+    level.setHeader('TITLE', 'Subset');
+    level.unknownSections.push({ name: 'PRETEXT', lines: ['Line one'] });
+    level.unknownLines.push('# trailing comment');
+    level.terrains.push({
+      props: { PIECE: 2, X: 0, Y: 0, ONE_WAY: true },
+      order: ['PIECE', 'X', 'Y', 'ONE_WAY'],
+      unknownLines: ['# terrain comment']
+    });
+
+    const ui = Object.create(EditorUiController.prototype);
+    ui.document = doc;
+    ui.el = { issuesList };
+    ui.session = { level };
+    ui.assets = null;
+    ui._transientIssues = [];
+
+    ui._refreshValidation();
+
+    const messages = issuesList.children
+      .flatMap(item => item.children)
+      .filter(child => child.classList.contains('issue-message'))
+      .map(child => child.textContent)
+      .join('\n');
+    expect(messages).to.contain('NXLV has preserved comments or unknown data');
+    expect(messages).to.contain('Classic LVL export is lossy');
+    expect(ui._validationSummary.warning).to.be.greaterThan(0);
+  });
+
+  it('reports import failures in validation and status UI', function() {
+    const doc = new TestDocument();
+    const issuesList = registerElement(doc, 'div', 'editorIssuesList');
+    const status = registerElement(doc, 'span', 'editorStatus');
+    const cursorStatus = registerElement(doc, 'span', 'editorCursorStatus');
+    const ui = Object.create(EditorUiController.prototype);
+    ui.document = doc;
+    ui.el = { issuesList, status, cursorStatus };
+    ui.controller = {
+      tool: 'select',
+      snapEnabled: true,
+      gridSize: 4
+    };
+    ui._playtest = false;
+    ui._cursorPos = null;
+    ui._transientIssues = [];
+
+    ui._reportImportFailure('NXLV', new Error('bad section'));
+
+    expect(issuesList.children).to.have.lengthOf(1);
+    const message = issuesList.children[0].children.find(child => child.classList.contains('issue-message'));
+    expect(message.textContent).to.equal('NXLV import failed: bad section');
+    expect(status.textContent).to.contain('NXLV import failed');
+    expect(status.textContent).to.contain('1 error');
+  });
+
+  it('builds exportable validation reports from current UI issues', function() {
+    const level = new EditorLevel();
+    level.setHeader('TITLE', 'Report UI');
+    level.setHeader('STYLE', 'dirt');
+    level.setHeader('LEMMINGS', 1);
+    level.setHeader('SAVE_REQUIREMENT', 2);
+
+    const ui = Object.create(EditorUiController.prototype);
+    ui.session = { level };
+    ui.assets = { entranceId: 1, exitId: 2, styleName: 'dirt' };
+    ui._transientIssues = [{
+      severity: 'warning',
+      message: 'Imported data preserved but not previewed.'
+    }];
+    ui.view = { game: { level: null } };
+
+    const report = ui._buildCurrentValidationReport();
+
+    expect(report.kind).to.equal('editor-validation-report');
+    expect(report.level.title).to.equal('Report UI');
+    expect(report.pack.levelCount).to.equal(1);
+    expect(report.summary.errors).to.be.greaterThan(0);
+    expect(report.issues.some(issue => issue.message === 'Imported data preserved but not previewed.')).to.equal(true);
+  });
+
+  it('enables conservative batch inspector fields for homogeneous multi-selection', function() {
+    const doc = new TestDocument();
+    const ui = Object.create(EditorUiController.prototype);
+    ui.el = createSelectionPanelElements(doc);
+    ui._toggleSelectionActions = visible => {
+      ui.selectionActionsVisible = visible;
+    };
+
+    ui._setSelectionFields({
+      multi: true,
+      count: 2,
+      entries: [{ type: 'terrain' }, { type: 'terrain' }]
+    });
+
+    expect(ui.el.selName.textContent).to.equal('2 terrain items');
+    expect(ui.el.selX.disabled).to.equal(false);
+    expect(ui.el.selX.placeholder).to.equal('batch');
+    expect(ui.el.selWidth.disabled).to.equal(true);
+    expect(ui.el.selOneWay.disabled).to.equal(false);
+    expect(ui.el.selOneWay.indeterminate).to.equal(true);
+    expect(ui.el.selSkill.disabled).to.equal(true);
+
+    ui._setSelectionFields({
+      multi: true,
+      count: 2,
+      entries: [{ type: 'terrain' }, { type: 'gadget' }]
+    });
+
+    expect(ui.el.selName.textContent).to.equal('2 mixed items');
+    expect(ui.el.selX.disabled).to.equal(true);
+    expect(ui.el.selOneWay.disabled).to.equal(true);
+  });
+
+  it('ignores stale async level imports after a newer import starts', async function() {
+    const doc = new TestDocument();
+    const win = createTestWindow();
+    const controller = createControllerStub();
+    const pendingAssets = new Map();
+    const assetCache = {
+      loadStyleAssets(styleName) {
+        return new Promise(resolve => pendingAssets.set(styleName, resolve));
+      }
+    };
+    const makeLevel = (styleName) => ({
+      terrains: [],
+      gadgets: [],
+      steel: [],
+      getHeader(key) {
+        return key === 'STYLE' ? styleName : null;
+      }
+    });
+    const view = {
+      editorSession: { level: makeLevel('initial') },
+      gameResources: { config: {} },
+      loadEditorLevelFromText(text) {
+        const level = makeLevel(text);
+        this.editorSession = { level };
+        return level;
+      },
+      loadEditorPreviewLevel() {
+        return Promise.resolve();
+      },
+      setEditorPlaytest() {}
+    };
+    const ui = new EditorUiController({
+      document: doc,
+      window: win,
+      view,
+      controller,
+      assetCache,
+      previewCache: {
+        invalidateTypeIds() {},
+        dispose() {}
+      }
+    });
+    ui._refreshPalettes = () => {};
+    ui._refreshStyleOptions = async () => {};
+    ui._refreshUndoRedo = () => {};
+    ui._refreshHeaderFields = () => {};
+    ui._refreshSelection = () => {};
+    ui._refreshValidation = () => {};
+    ui._refreshSavedList = () => {};
+    ui._drawSelectionOverlay = () => {};
+    ui._updateStatus = () => {};
+    ui._setDirty = () => {};
+
+    ui._loadLevelFromText('first');
+    ui._loadLevelFromText('second');
+
+    pendingAssets.get('first')({ marker: 'first' });
+    await flush();
+    expect(ui.assets).to.equal(null);
+
+    pendingAssets.get('second')({ marker: 'second' });
+    await flush();
+    expect(ui.assets).to.deep.equal({ marker: 'second' });
+  });
+});
diff --git a/test/editor/editor-ui-controller.palette.test.js b/test/editor/editor-ui-controller.palette.test.js
new file mode 100644
index 00000000..f860b391
--- /dev/null
+++ b/test/editor/editor-ui-controller.palette.test.js
@@ -0,0 +1,425 @@
+import { expect } from 'chai';
+import FakeTimers from '@sinonjs/fake-timers';
+import { EditorUiController } from '../../js/app/editorUiController.js';
+import { TestDocument } from '../helpers/test-dom.js';
+
+const createClassList = () => {
+  const set = new Set();
+  return {
+    add(name) {
+      set.add(name);
+    },
+    remove(name) {
+      set.delete(name);
+    },
+    toggle(name, force) {
+      if (force) set.add(name);
+      else set.delete(name);
+    },
+    contains(name) {
+      return set.has(name);
+    }
+  };
+};
+
+const createRecord = (searchKey, hidden = false, previewLoaded = false) => ({
+  searchKey,
+  entry: { id: 1 },
+  type: 'terrain',
+  button: {
+    hidden,
+    classList: createClassList()
+  },
+  previewWrap: { classList: createClassList() },
+  previewImg: { src: '' },
+  previewLoaded
+});
+
+const createButtonStub = (dataset = {}) => {
+  const attrs = new Map();
+  const listeners = new Map();
+  return {
+    dataset,
+    classList: createClassList(),
+    setAttribute(name, value) {
+      attrs.set(name, String(value));
+    },
+    getAttribute(name) {
+      return attrs.get(name) || null;
+    },
+    addEventListener(type, handler) {
+      listeners.set(type, handler);
+    },
+    dispatch(type, event = {}) {
+      listeners.get(type)?.({ type, target: this, ...event });
+    }
+  };
+};
+
+describe('EditorUiController palette throughput helpers', () => {
+  it('updates palette tab pressed state with the active tab', () => {
+    const ui = Object.create(EditorUiController.prototype);
+    const terrain = createButtonStub({ tab: 'terrain' });
+    const gadgets = createButtonStub({ tab: 'gadgets' });
+    const triggers = createButtonStub({ tab: 'triggers' });
+    ui.el = {
+      paletteTabs: { querySelectorAll: () => [terrain, gadgets, triggers] },
+      paletteTerrain: {},
+      paletteGadgets: {},
+      paletteTriggers: {}
+    };
+    ui._schedulePalettePreviewHydration = () => {};
+
+    ui._setPaletteTab('gadgets');
+
+    expect(terrain.classList.contains('active')).to.equal(false);
+    expect(terrain.getAttribute('aria-pressed')).to.equal('false');
+    expect(gadgets.classList.contains('active')).to.equal(true);
+    expect(gadgets.getAttribute('aria-pressed')).to.equal('true');
+    expect(triggers.getAttribute('aria-pressed')).to.equal('false');
+    expect(ui.el.paletteTerrain.hidden).to.equal(true);
+    expect(ui.el.paletteGadgets.hidden).to.equal(false);
+  });
+
+  it('updates palette view pressed state when switching modes', () => {
+    const ui = Object.create(EditorUiController.prototype);
+    const list = createButtonStub();
+    const grid = createButtonStub();
+    ui.el = {
+      paletteViewList: list,
+      paletteViewGrid: grid,
+      paletteTerrain: null,
+      paletteGadgets: null,
+      paletteTriggers: null
+    };
+    ui._paletteViewMode = 'list';
+    ui._addDomListener = (element, type, handler) => element.addEventListener(type, handler);
+    ui._applyPaletteViewMode = () => {};
+    ui._bindPaletteGridZoom = () => {};
+
+    ui._bindPaletteView();
+    expect(list.classList.contains('active')).to.equal(true);
+    expect(list.getAttribute('aria-pressed')).to.equal('true');
+    expect(grid.getAttribute('aria-pressed')).to.equal('false');
+
+    grid.dispatch('click');
+    expect(list.classList.contains('active')).to.equal(false);
+    expect(list.getAttribute('aria-pressed')).to.equal('false');
+    expect(grid.classList.contains('active')).to.equal(true);
+    expect(grid.getAttribute('aria-pressed')).to.equal('true');
+  });
+
+  it('uses gadget preview keys for trigger entries', () => {
+    const ui = Object.create(EditorUiController.prototype);
+    const calls = [];
+    ui.previewCache = {
+      getPreviewUrl(payload) {
+        calls.push(payload);
+        return 'data:image/png;base64,ok';
+      }
+    };
+    ui.assets = {
+      terrainImages: [],
+      gadgetImages: [{ id: 3, width: 8, height: 8 }]
+    };
+
+    const url = ui._getPreviewUrl({ id: 0 }, 'trigger');
+    expect(url).to.equal('data:image/png;base64,ok');
+    expect(calls).to.have.length(1);
+    expect(calls[0].type).to.equal('gadget');
+  });
+
+  it('filters palette entries using cached normalized search keys', () => {
+    const ui = Object.create(EditorUiController.prototype);
+    let scheduleCount = 0;
+    ui._schedulePalettePreviewHydration = () => {
+      scheduleCount += 1;
+    };
+    ui.el = {
+      paletteSearch: { value: 'trap' }
+    };
+    ui._paletteEntries = {
+      terrain: [createRecord('stone'), createRecord('trap door')],
+      gadget: [createRecord('trap zone')],
+      trigger: [createRecord('exit')]
+    };
+
+    ui._applyPaletteFilter();
+    expect(ui._paletteEntries.terrain[0].button.hidden).to.equal(true);
+    expect(ui._paletteEntries.terrain[1].button.hidden).to.equal(false);
+    expect(ui._paletteEntries.gadget[0].button.hidden).to.equal(false);
+    expect(ui._paletteEntries.trigger[0].button.hidden).to.equal(true);
+    expect(scheduleCount).to.equal(1);
+  });
+
+  it('records recent palette entries with de-dupe and cap', () => {
+    const ui = Object.create(EditorUiController.prototype);
+    let renderCount = 0;
+    ui._recentPaletteEntries = [];
+    ui._renderRecentPaletteEntries = () => {
+      renderCount += 1;
+    };
+
+    for (let i = 0; i < 10; i += 1) {
+      ui._recordRecentPaletteEntry({ id: i, name: `Terrain ${i}`, width: 8, height: 8 }, 'terrain');
+    }
+    ui._recordRecentPaletteEntry({ id: 4, name: 'Terrain 4', width: 8, height: 8 }, 'terrain');
+
+    expect(ui._recentPaletteEntries).to.have.lengthOf(8);
+    expect(ui._recentPaletteEntries[0].id).to.equal(4);
+    expect(ui._recentPaletteEntries.filter(entry => entry.id === 4)).to.have.lengthOf(1);
+    expect(ui._recentPaletteEntries.map(entry => entry.id)).to.deep.equal([4, 9, 8, 7, 6, 5, 3, 2]);
+    expect(renderCount).to.equal(11);
+  });
+
+  it('renders recent palette buttons and reuses selection behavior', () => {
+    const doc = new TestDocument();
+    const recent = doc.createElement('div');
+    const ui = Object.create(EditorUiController.prototype);
+    const selected = { terrain: null, gadget: null, trigger: null };
+    ui.document = doc;
+    ui.el = { paletteRecent: recent };
+    ui.controller = {
+      selectedTerrainId: null,
+      selectedGadgetId: null,
+      selectedTriggerId: null,
+      setSelectedTerrain(id) {
+        selected.terrain = id;
+        this.selectedTerrainId = id;
+      },
+      setSelectedGadget(id) {
+        selected.gadget = id;
+        this.selectedGadgetId = id;
+      },
+      setSelectedTrigger(id) {
+        selected.trigger = id;
+        this.selectedTriggerId = id;
+      }
+    };
+    ui._paletteEntries = {
+      terrain: [{
+        id: 3,
+        entry: { id: 3, name: 'Rock', width: 8, height: 8 },
+        button: { classList: createClassList() }
+      }],
+      gadget: [],
+      trigger: []
+    };
+    ui._recentPaletteEntries = [{
+      id: 3,
+      type: 'terrain',
+      label: '#3 Rock (8x8)',
+      entry: { id: 3, name: 'Rock', width: 8, height: 8 }
+    }];
+
+    ui._renderRecentPaletteEntries();
+    expect(recent.hidden).to.equal(false);
+    expect(recent.children).to.have.lengthOf(1);
+    expect(recent.children[0].dataset.type).to.equal('terrain');
+    expect(recent.children[0].dataset.id).to.equal('3');
+    expect(recent.children[0].getAttribute('aria-label')).to.equal('Select recent #3 Rock (8x8)');
+
+    recent.children[0].dispatchEvent({ type: 'click' });
+    expect(selected.terrain).to.equal(3);
+  });
+
+  it('hydrates previews in visible active-tab batches', () => {
+    const clock = FakeTimers.install({ now: 0, toFake: ['setTimeout', 'clearTimeout', 'Date'] });
+    const ui = Object.create(EditorUiController.prototype);
+    const first = createRecord('a', false, false);
+    const hidden = createRecord('b', true, false);
+    const loaded = createRecord('c', false, true);
+    ui._activeTab = 'terrain';
+    ui._palettePreviewQueue = [];
+    ui._palettePreviewToken = 0;
+    ui._palettePreviewTimer = null;
+    ui._paletteEntries = {
+      terrain: [first, hidden, loaded],
+      gadget: [],
+      trigger: []
+    };
+    let previewCalls = 0;
+    ui._getPreviewUrl = () => {
+      previewCalls += 1;
+      return 'data:image/png;base64,terrain';
+    };
+
+    ui._schedulePalettePreviewHydration();
+    clock.tick(0);
+    clock.uninstall();
+
+    expect(previewCalls).to.equal(1);
+    expect(first.previewLoaded).to.equal(true);
+    expect(first.previewImg.src).to.equal('data:image/png;base64,terrain');
+    expect(hidden.previewLoaded).to.equal(false);
+    expect(loaded.previewLoaded).to.equal(true);
+  });
+
+  it('keeps large palette preview hydration batched across timer turns', () => {
+    const clock = FakeTimers.install({ now: 0, toFake: ['setTimeout', 'clearTimeout', 'Date'] });
+    try {
+      const ui = Object.create(EditorUiController.prototype);
+      const records = Array.from({ length: 60 }, (_, i) => createRecord(`terrain-${i}`, false, false));
+      ui._activeTab = 'terrain';
+      ui._palettePreviewQueue = [];
+      ui._palettePreviewIndex = 0;
+      ui._palettePreviewToken = 0;
+      ui._palettePreviewTimer = null;
+      ui._paletteEntries = {
+        terrain: records,
+        gadget: [],
+        trigger: []
+      };
+      let previewCalls = 0;
+      ui._getPreviewUrl = () => {
+        previewCalls += 1;
+        return 'data:image/png;base64,terrain';
+      };
+
+      ui._schedulePalettePreviewHydration();
+      expect(previewCalls).to.equal(0);
+      clock.tick(0);
+      expect(previewCalls).to.equal(24);
+      expect(ui._palettePreviewTimer).to.not.equal(null);
+      clock.tick(1);
+      expect(previewCalls).to.equal(48);
+      clock.tick(1);
+
+      expect(previewCalls).to.equal(60);
+      expect(records.every(record => record.previewLoaded)).to.equal(true);
+      expect(ui._palettePreviewQueue).to.deep.equal([]);
+      expect(ui._palettePreviewTimer).to.equal(null);
+    } finally {
+      clock.uninstall();
+    }
+  });
+
+  it('cancels stale preview hydration batches when the token changes', () => {
+    const clock = FakeTimers.install({ now: 0, toFake: ['setTimeout', 'clearTimeout', 'Date'] });
+    try {
+      const ui = Object.create(EditorUiController.prototype);
+      const first = createRecord('a', false, false);
+      ui._activeTab = 'terrain';
+      ui._palettePreviewQueue = [];
+      ui._palettePreviewIndex = 0;
+      ui._palettePreviewToken = 0;
+      ui._palettePreviewTimer = null;
+      ui._paletteEntries = {
+        terrain: [first],
+        gadget: [],
+        trigger: []
+      };
+      let previewCalls = 0;
+      ui._getPreviewUrl = () => {
+        previewCalls += 1;
+        return 'data:image/png;base64,terrain';
+      };
+
+      ui._schedulePalettePreviewHydration();
+      ui._palettePreviewToken += 1;
+      clock.tick(0);
+
+      expect(previewCalls).to.equal(0);
+      expect(first.previewLoaded).to.equal(false);
+    } finally {
+      clock.uninstall();
+    }
+  });
+
+  it('skips hydration timers when no pending previews exist', () => {
+    const ui = Object.create(EditorUiController.prototype);
+    ui._activeTab = 'terrain';
+    ui._palettePreviewQueue = [];
+    ui._palettePreviewIndex = 0;
+    ui._palettePreviewToken = 0;
+    ui._palettePreviewTimer = null;
+    ui._paletteEntries = {
+      terrain: [createRecord('a', true, false), createRecord('b', false, true)],
+      gadget: [],
+      trigger: []
+    };
+
+    ui._schedulePalettePreviewHydration();
+
+    expect(ui._palettePreviewTimer).to.equal(null);
+    expect(ui._palettePreviewQueue).to.deep.equal([]);
+    expect(ui._palettePreviewIndex).to.equal(0);
+  });
+
+  it('ignores ctrl-wheel zoom updates when wheel delta is zero', () => {
+    const ui = Object.create(EditorUiController.prototype);
+    const terrainContainer = {
+      handler: null,
+      addEventListener(type, handler) {
+        if (type === 'wheel') {
+          this.handler = handler;
+        }
+      }
+    };
+    ui.el = {
+      paletteTerrain: terrainContainer,
+      paletteGadgets: null,
+      paletteTriggers: null
+    };
+    ui._paletteViewMode = 'grid';
+    ui._paletteGridColumns = 4;
+    const updates = [];
+    ui._setPaletteGridColumns = (value) => {
+      updates.push(value);
+    };
+
+    ui._bindPaletteGridZoom();
+    expect(typeof terrainContainer.handler).to.equal('function');
+
+    let prevented = false;
+    terrainContainer.handler({
+      ctrlKey: true,
+      deltaY: 0,
+      preventDefault() {
+        prevented = true;
+      }
+    });
+
+    expect(prevented).to.equal(false);
+    expect(updates).to.deep.equal([]);
+
+    terrainContainer.handler({
+      ctrlKey: true,
+      deltaY: -1,
+      preventDefault() {}
+    });
+    expect(updates).to.deep.equal([3]);
+  });
+
+  it('refreshes style options using canonical names for case-insensitive current styles', async () => {
+    const ui = Object.create(EditorUiController.prototype);
+    const appended = [];
+    ui.el = {
+      headerStyle: {
+        innerHTML: '',
+        value: '',
+        appendChild(option) {
+          appended.push(option);
+        }
+      }
+    };
+    ui.document = {
+      createElement() {
+        return { value: '', textContent: '' };
+      }
+    };
+    ui.session = {
+      level: {
+        getHeader() {
+          return 'canyon';
+        }
+      }
+    };
+    ui._resolveAvailableStyles = async () => ['Canyon', 'Fire'];
+
+    await ui._refreshStyleOptions();
+
+    expect(appended.map(option => option.value)).to.deep.equal(['Canyon', 'Fire']);
+    expect(ui.el.headerStyle.value).to.equal('Canyon');
+  });
+});
diff --git a/test/editor/editor-validator.test.js b/test/editor/editor-validator.test.js
index 250372e7..2e5b5a54 100644
--- a/test/editor/editor-validator.test.js
+++ b/test/editor/editor-validator.test.js
@@ -1,6 +1,12 @@
 import { expect } from 'chai';
 import { EditorLevel } from '../../js/editor/EditorLevel.js';
-import { validateLevel } from '../../js/editor/EditorValidator.js';
+import {
+  createValidationReport,
+  validateLevel,
+  validatePackConsistency
+} from '../../js/editor/EditorValidator.js';
+import { createSmallGapFixture } from '../../js/solver/SolverFixtures.js';
+import { EDITOR_ADVISORY_WARNING_CODES } from '../../js/solver/EditorAdvisory.js';
 
 const createLevel = () => {
   const level = new EditorLevel();
@@ -19,6 +25,38 @@ const createLevel = () => {
   return level;
 };
 
+const installRuntimeFixture = (level, fixture) => {
+  level.setHeader('TITLE', 'Advisory route');
+  level.setHeader('WIDTH', fixture.width);
+  level.setHeader('HEIGHT', fixture.height);
+  level.setHeader('LEMMINGS', 1);
+  level.setHeader('SAVE_REQUIREMENT', 1);
+  level.gadgets = [
+    { props: { PIECE: 1, X: fixture.entrances[0].x, Y: fixture.entrances[0].y } },
+    { props: { PIECE: 2, X: fixture.exits[0].x, Y: fixture.exits[0].y } }
+  ];
+  level.width = fixture.width;
+  level.height = fixture.height;
+  level.groundMask = {
+    width: fixture.width,
+    height: fixture.height,
+    mask: fixture.groundMask,
+    hasGroundAt(x, y) {
+      const ix = Math.floor(x);
+      const iy = Math.floor(y);
+      if (ix < 0 || iy < 0 || ix >= fixture.width || iy >= fixture.height) return false;
+      return fixture.groundMask[ix + iy * fixture.width] !== 0;
+    }
+  };
+  level.entrances = fixture.entrances.map(entry => ({ ...entry }));
+  level.exits = fixture.exits.map(entry => ({ ...entry }));
+  level.oneWay = fixture.oneWay.map(entry => ({ ...entry }));
+  level.hazards = fixture.hazards.map(entry => ({ ...entry }));
+  for (const [skill, count] of Object.entries(fixture.skills || {})) {
+    level.setSkill(skill, count);
+  }
+};
+
 describe('EditorValidator', () => {
   it('returns empty list for null input', () => {
     expect(validateLevel(null)).to.deep.equal([]);
@@ -276,7 +314,7 @@ describe('EditorValidator', () => {
       props: { X: 0, Y: 0, ROTATE: 45, FLIP_HORIZONTAL: true, WIDTH: 4, HEIGHT: 4 }
     });
     level.steel = [
-      { props: { X: 0, Y: 0, WIDTH: 9999, HEIGHT: 9999, LEMMINGS: 5 } }
+      { props: { X: 0, Y: 0, WIDTH: 9999, HEIGHT: 9999, LEMMINGS: 5, PIECE: 1 } }
     ];
 
     const issues = validateLevel(level, { entranceId: 1, exitId: 2 });
@@ -287,8 +325,9 @@ describe('EditorValidator', () => {
     expect(issues.some(issue => issue.message.includes('Spawn interval is out of range'))).to.equal(true);
     expect(issues.some(issue => issue.message.includes('Time limit exceeds classic max'))).to.equal(true);
     const gadgetPropsIssue = issues.find(issue => issue.message.includes('Gadget-only properties'));
-    const terrainUnsupportedIssue = issues.find(issue => issue.message.includes('Terrain entries include unsupported classic properties'));
-    const gadgetUnsupportedIssue = issues.find(issue => issue.message.includes('Gadget entries include unsupported classic properties'));
+    const terrainUnsupportedIssue = issues.find(issue => issue.code === 'classic_unsupported_terrain_props');
+    const gadgetUnsupportedIssue = issues.find(issue => issue.code === 'classic_unsupported_gadget_props');
+    const steelUnsupportedIssue = issues.find(issue => issue.code === 'classic_unsupported_steel_props');
     const oversizeIssue = issues.find(issue => issue.message.includes('Steel sizes exceed the level bounds'));
     const widthIssue = issues.find(issue => issue.message.includes('Width exceeds classic preview max'));
     const heightIssue = issues.find(issue => issue.message.includes('Height exceeds classic preview max'));
@@ -299,6 +338,11 @@ describe('EditorValidator', () => {
     expect(gadgetPropsIssue).to.exist;
     expect(terrainUnsupportedIssue).to.exist;
     expect(gadgetUnsupportedIssue).to.exist;
+    expect(steelUnsupportedIssue).to.exist;
+    expect(terrainUnsupportedIssue.destructive).to.equal(true);
+    expect(terrainUnsupportedIssue.props).to.include.members(['FLIP_HORIZONTAL', 'HEIGHT', 'ONE_WAY', 'ROTATE', 'SKILL', 'WIDTH']);
+    expect(gadgetUnsupportedIssue.props).to.include.members(['FLIP_HORIZONTAL', 'HEIGHT', 'ROTATE', 'WIDTH']);
+    expect(steelUnsupportedIssue.props).to.include('PIECE');
     expect(oversizeIssue).to.exist;
     expect(widthIssue).to.exist;
     expect(heightIssue).to.exist;
@@ -310,6 +354,7 @@ describe('EditorValidator', () => {
     gadgetPropsIssue.fix();
     terrainUnsupportedIssue.fix();
     gadgetUnsupportedIssue.fix();
+    steelUnsupportedIssue.fix();
     oversizeIssue.fix();
     widthIssue.fix();
     heightIssue.fix();
@@ -319,8 +364,41 @@ describe('EditorValidator', () => {
     timeLimitIssue.fix();
     expect(level.terrains[0].props).to.not.have.property('SKILL');
     expect(level.terrains[0].props).to.not.have.property('ROTATE');
+    expect(level.terrains[0].props).to.not.have.property('ONE_WAY');
     expect(level.gadgets[0].props).to.not.have.property('ROTATE');
     expect(level.steel[0].props).to.not.have.property('LEMMINGS');
+    expect(level.steel[0].props).to.not.have.property('PIECE');
+  });
+
+  it('warns and fixes destructive classic export caps', () => {
+    const level = createLevel();
+    level.setHeader('TITLE', 'This title is definitely longer than thirty two characters');
+    level.gadgets = Array.from({ length: 33 }, (_, index) => ({ props: { PIECE: index, X: index, Y: 0 } }));
+    level.terrains = Array.from({ length: 401 }, (_, index) => ({ props: { PIECE: index, X: index, Y: 0 } }));
+    level.steel = Array.from({ length: 33 }, (_, index) => ({
+      props: { X: index, Y: 0, WIDTH: 4, HEIGHT: 4 }
+    }));
+
+    const issues = validateLevel(level, { entranceId: 1, exitId: 2 });
+    const titleIssue = issues.find(issue => issue.code === 'classic_title_length');
+    const objectIssue = issues.find(issue => issue.code === 'classic_object_count');
+    const terrainIssue = issues.find(issue => issue.code === 'classic_terrain_count');
+    const steelIssue = issues.find(issue => issue.code === 'classic_steel_count');
+
+    expect(titleIssue).to.include({ destructive: true, target: 'header.TITLE', max: 32 });
+    expect(objectIssue).to.include({ destructive: true, target: 'gadgets', max: 32 });
+    expect(terrainIssue).to.include({ destructive: true, target: 'terrains', max: 400 });
+    expect(steelIssue).to.include({ destructive: true, target: 'steel', max: 32 });
+
+    titleIssue.fix();
+    objectIssue.fix();
+    terrainIssue.fix();
+    steelIssue.fix();
+
+    expect(level.getHeader('TITLE')).to.have.length(32);
+    expect(level.gadgets).to.have.length(32);
+    expect(level.terrains).to.have.length(400);
+    expect(level.steel).to.have.length(32);
   });
 
   it('clamps negative time limits and invalid start positions', () => {
@@ -343,4 +421,118 @@ describe('EditorValidator', () => {
     expect(level.getHeader('START_X')).to.equal(0);
     expect(level.getHeader('START_Y')).to.equal(0);
   });
+
+  it('attaches non-blocking solver advisory warnings to validation output', () => {
+    const level = createLevel();
+    const fixture = createSmallGapFixture({
+      skills: {},
+      oneWay: [{ x: 20, y: 58, width: 20, height: 4 }]
+    });
+    installRuntimeFixture(level, fixture);
+
+    const issues = validateLevel(level, { entranceId: 1, exitId: 2 });
+    const advisoryIssues = issues.filter(issue => issue.solverAdvisory);
+    const codes = advisoryIssues.map(issue => issue.code);
+    const gapIssue = advisoryIssues.find(issue => {
+      return issue.advisoryCode === EDITOR_ADVISORY_WARNING_CODES.UNREACHABLE_GAP;
+    });
+
+    expect(codes).to.include('solver_advisory_unreachable_gap');
+    expect(codes).to.include('solver_advisory_insufficient_skills');
+    expect(codes).to.include('solver_advisory_unsupported_mechanic');
+    expect(gapIssue).to.include({
+      severity: 'warning',
+      source: 'solver-advisory',
+      blocking: false,
+      blocksEditing: false,
+      blocksExport: false
+    });
+    expect(gapIssue.fix).to.equal(null);
+    expect(gapIssue.budgetUsage.scannedColumns).to.be.greaterThan(0);
+  });
+
+  it('uses the supplied runtime source for editor solver advisory validation', () => {
+    const level = createLevel();
+    level.setHeader('TITLE', 'Editor source');
+    level.setHeader('WIDTH', 140);
+    level.setHeader('HEIGHT', 72);
+    level.setHeader('LEMMINGS', 1);
+    level.setHeader('SAVE_REQUIREMENT', 1);
+    level.gadgets = [
+      { props: { PIECE: 1, X: 12, Y: 57 } },
+      { props: { PIECE: 2, X: 120, Y: 57 } }
+    ];
+    const runtimeSource = createSmallGapFixture({ skills: {} });
+
+    const issues = validateLevel(level, { entranceId: 1, exitId: 2 }, {
+      solverAdvisorySource: runtimeSource
+    });
+
+    expect(issues.some(issue => issue.code === 'solver_advisory_unreachable_gap')).to.equal(true);
+  });
+
+  it('uses editor skillsets for solver advisory skill budgets', () => {
+    const level = createLevel();
+    const fixture = createSmallGapFixture();
+    installRuntimeFixture(level, fixture);
+
+    const issues = validateLevel(level, { entranceId: 1, exitId: 2 });
+
+    expect(issues.some(issue => issue.code === 'solver_advisory_unreachable_gap')).to.equal(false);
+    expect(issues.some(issue => issue.code === 'solver_advisory_insufficient_skills')).to.equal(false);
+  });
+
+  it('can disable solver advisory validation', () => {
+    const level = createLevel();
+    const fixture = createSmallGapFixture({ skills: {} });
+    installRuntimeFixture(level, fixture);
+
+    const issues = validateLevel(level, { entranceId: 1, exitId: 2 }, {
+      solverAdvisory: false
+    });
+
+    expect(issues.some(issue => issue.solverAdvisory)).to.equal(false);
+  });
+
+  it('exports validation report entries with blocker and destructive metadata', () => {
+    const level = createLevel();
+    level.setHeader('TITLE', 'Report');
+    level.terrainGroups = [{ terrains: [], unknownLines: ['GROUP 1'] }];
+
+    const report = createValidationReport(level, { entranceId: 1, exitId: 2 });
+    const saveIssue = report.issues.find(issue => issue.message === 'Save requirement exceeds lemmings.');
+    const groupIssue = report.issues.find(issue => issue.code === 'classic_terrain_groups');
+
+    expect(report.kind).to.equal('editor-validation-report');
+    expect(report.level.title).to.equal('Report');
+    expect(report.summary.errors).to.be.greaterThan(0);
+    expect(saveIssue.blocker).to.equal(true);
+    expect(saveIssue.blocksExport).to.equal(true);
+    expect(groupIssue.destructive).to.equal(true);
+    expect(groupIssue.exportFormat).to.equal('classicLvl');
+  });
+
+  it('reports pack-level duplicate and missing-style consistency warnings', () => {
+    const first = createLevel();
+    first.setHeader('TITLE', 'Repeat');
+    first.setHeader('ID', 'level-a');
+    first.setHeader('STYLE', 'dirt');
+    const second = createLevel();
+    second.setHeader('TITLE', 'Repeat');
+    second.setHeader('ID', 'level-a');
+    second.setHeader('STYLE', 'missing-style');
+
+    const issues = validatePackConsistency({
+      title: 'Pack',
+      levels: [first, second]
+    }, {
+      dirt: {}
+    });
+    const codes = issues.map(issue => issue.code);
+
+    expect(codes).to.include('pack_duplicate_title');
+    expect(codes).to.include('pack_duplicate_id');
+    expect(codes).to.include('pack_missing_style_assets');
+    expect(issues.every(issue => issue.source === 'pack-validation')).to.equal(true);
+  });
 });
diff --git a/test/editor/nxlv-fuzz.test.js b/test/editor/nxlv-fuzz.test.js
new file mode 100644
index 00000000..b6f6e9c1
--- /dev/null
+++ b/test/editor/nxlv-fuzz.test.js
@@ -0,0 +1,122 @@
+import { expect } from 'chai';
+import { EditorLevel } from '../../js/editor/EditorLevel.js';
+import { NxlvParser } from '../../js/editor/NxlvParser.js';
+import { NxlvWriter } from '../../js/editor/NxlvWriter.js';
+import { createGadgetEntry, createSteelEntry, createTerrainEntry } from '../../js/editor/EditorEntryFactory.js';
+
+const createRng = (seed) => {
+  let state = seed >>> 0;
+  return () => {
+    state = (state * 1664525 + 1013904223) >>> 0;
+    return state / 4294967296;
+  };
+};
+
+const pick = (rng, list) => list[Math.floor(rng() * list.length) % list.length];
+
+const randomWord = (rng, len = 5) => {
+  let out = '';
+  const alphabet = 'abcdefghijklmnopqrstuvwxyz';
+  for (let i = 0; i < len; i += 1) {
+    out += alphabet[Math.floor(rng() * alphabet.length)];
+  }
+  return out;
+};
+
+const randomLevel = (seed) => {
+  const rng = createRng(seed);
+  const level = new EditorLevel();
+  level.setHeader('TITLE', `Fuzz_${seed}`);
+  level.setHeader('STYLE', pick(rng, ['dirt', 'crystal', 'marble']));
+  level.setHeader('WIDTH', 320 + Math.floor(rng() * 640));
+  level.setHeader('HEIGHT', 160 + Math.floor(rng() * 320));
+  level.setHeader('SPAWN_INTERVAL_LOCKED', rng() > 0.5);
+
+  level.unknownLines.push(`# top_${randomWord(rng, 6)}`);
+
+  if (rng() > 0.3) {
+    level.skillset.set('CLIMBER', Math.floor(rng() * 50));
+    level.skillset.set('BOMBER', rng() > 0.5 ? 'INFINITE' : Math.floor(rng() * 20));
+    level.skillsetUnknownLines = [`# skill_${randomWord(rng, 4)}`];
+  }
+
+  const terrainCount = 1 + Math.floor(rng() * 4);
+  for (let i = 0; i < terrainCount; i += 1) {
+    const terrain = createTerrainEntry({
+      styleName: level.getHeader('STYLE'),
+      piece: 1 + Math.floor(rng() * 6),
+      x: Math.floor(rng() * 300),
+      y: Math.floor(rng() * 150),
+      oneWay: rng() > 0.7
+    });
+    if (rng() > 0.5) terrain.unknownLines.push(`# terrain_${randomWord(rng, 4)}`);
+    level.terrains.push(terrain);
+  }
+
+  const gadgetCount = Math.floor(rng() * 3);
+  for (let i = 0; i < gadgetCount; i += 1) {
+    const gadget = createGadgetEntry({
+      styleName: level.getHeader('STYLE'),
+      piece: 1 + Math.floor(rng() * 5),
+      x: Math.floor(rng() * 300),
+      y: Math.floor(rng() * 150),
+      rotate: Math.floor(rng() * 4)
+    });
+    if (rng() > 0.5) gadget.unknownLines.push(`# gadget_${randomWord(rng, 4)}`);
+    level.gadgets.push(gadget);
+  }
+
+  if (rng() > 0.4) {
+    level.steel.push(createSteelEntry({
+      x: Math.floor(rng() * 200),
+      y: Math.floor(rng() * 100),
+      width: 1 + Math.floor(rng() * 10),
+      height: 1 + Math.floor(rng() * 10)
+    }));
+  }
+
+  if (rng() > 0.4) {
+    level.unknownSections.push({
+      name: `UNKNOWN_${randomWord(rng, 3).toUpperCase()}`,
+      lines: [`# comment_${randomWord(rng, 3)}`, `FOO ${randomWord(rng, 4)}`]
+    });
+  }
+
+  return level;
+};
+
+describe('NXLV fuzz and recovery', function () {
+  it('round-trips comments and unknown sections with stable writer output', function () {
+    for (let seed = 1; seed <= 50; seed += 1) {
+      const level = randomLevel(seed);
+      const firstWrite = NxlvWriter.write(level);
+      const parsed = NxlvParser.parse(firstWrite);
+      const secondWrite = NxlvWriter.write(parsed);
+      const thirdWrite = NxlvWriter.write(NxlvParser.parse(secondWrite));
+
+      expect(thirdWrite).to.equal(secondWrite);
+      expect(secondWrite).to.contain('TITLE');
+      expect(parsed.unknownLines.length).to.be.greaterThan(0);
+    }
+  });
+
+  it('recovers from malformed payloads without throwing and rewrites safely', function () {
+    const malformedSamples = [
+      '$END\n$END\nTITLE MissingStart',
+      '$TERRAIN\nX nope\nY nope',
+      '$SKILLSET\nSKILL BUILDER nope\n$END',
+      '$FOO\nBAR baz\n# comment only',
+      '# just comments\n# and blank lines',
+      '$TERRAINGROUP\n$TERRAIN\nX 10\n$END',
+      '$GADGET\nPIECE xzz\nX --\nY ++\n$END'
+    ];
+
+    for (const text of malformedSamples) {
+      const parsed = NxlvParser.parse(text);
+      const rewritten = NxlvWriter.write(parsed);
+      expect(parsed).to.be.an('object');
+      expect(rewritten).to.be.a('string');
+      expect(() => NxlvParser.parse(rewritten)).to.not.throw();
+    }
+  });
+});
diff --git a/test/editor/nxlv-parser.test.js b/test/editor/nxlv-parser.test.js
index 1713d7de..05e0a63b 100644
--- a/test/editor/nxlv-parser.test.js
+++ b/test/editor/nxlv-parser.test.js
@@ -123,6 +123,25 @@ describe('NxlvParser', function () {
     assert.strictEqual(level.terrains[0].props.X, 1);
   });
 
+  it('parses MIDI flag gadget props with semantic types', function () {
+    const text = [
+      '$GADGET',
+      '  STYLE dirt',
+      '  PIECE 3',
+      '  X 50',
+      '  Y 60',
+      '  MIDI_FLAG true',
+      '  MIDI_FLAG_ID 7',
+      '  MIDI_FLAG_COOLDOWN 12',
+      '$END'
+    ].join('\n');
+
+    const level = NxlvParser.parse(text);
+    assert.strictEqual(level.gadgets[0].props.MIDI_FLAG, true);
+    assert.strictEqual(level.gadgets[0].props.MIDI_FLAG_ID, 7);
+    assert.strictEqual(level.gadgets[0].props.MIDI_FLAG_COOLDOWN, 12);
+  });
+
   it('initializes skillset unknown lines when missing', function () {
     const original = Object.getOwnPropertyDescriptor(EditorLevel.prototype, 'skillsetUnknownLines');
     let firstAssignment = true;
diff --git a/test/editor/nxlv-writer.test.js b/test/editor/nxlv-writer.test.js
index a57c1f72..62387fd2 100644
--- a/test/editor/nxlv-writer.test.js
+++ b/test/editor/nxlv-writer.test.js
@@ -64,6 +64,48 @@ describe('NxlvWriter', function () {
     assert.strictEqual(parsed.gadgets[0].props.FLIP_VERTICAL, true);
   });
 
+  it('semantically round-trips comments and unknown sections', function () {
+    const text = [
+      '# top note',
+      'TITLE Preserve Notes',
+      'STYLE dirt',
+      '$SKILLSET',
+      '  # skill note',
+      '  SKILL CLIMBER 1',
+      '  TALISMAN legacy',
+      '$END',
+      '$TERRAIN',
+      '  # terrain note',
+      '  STYLE dirt',
+      '  PIECE terrain_1',
+      '  X 10',
+      '  Y 20',
+      '  CUSTOM_TERRAIN_FIELD keep-me',
+      '$END',
+      '$NEOLEMMIX_ONLY',
+      '  # unknown section note',
+      '  CUSTOM value',
+      '$END',
+      '# trailing note'
+    ].join('\n');
+
+    const parsed = NxlvParser.parse(text);
+    const written = NxlvWriter.write(parsed);
+    const reparsed = NxlvParser.parse(written);
+
+    assert.strictEqual(reparsed.getHeader('TITLE'), 'Preserve Notes');
+    assert.ok(reparsed.unknownLines.includes('# top note'));
+    assert.ok(reparsed.unknownLines.includes('# trailing note'));
+    assert.ok(reparsed.skillsetUnknownLines.some(line => line.includes('# skill note')));
+    assert.ok(reparsed.skillsetUnknownLines.some(line => line.includes('TALISMAN legacy')));
+    assert.ok(reparsed.terrains[0].unknownLines.some(line => line.includes('# terrain note')));
+    assert.strictEqual(reparsed.terrains[0].props.CUSTOM_TERRAIN_FIELD, 'keep-me');
+    assert.strictEqual(reparsed.unknownSections.length, 1);
+    assert.strictEqual(reparsed.unknownSections[0].name, 'NEOLEMMIX_ONLY');
+    assert.ok(reparsed.unknownSections[0].lines.some(line => line.includes('# unknown section note')));
+    assert.ok(reparsed.unknownSections[0].lines.some(line => line.includes('CUSTOM value')));
+  });
+
   it('handles missing skillset unknown lines', function () {
     const level = new EditorLevel();
     level.setHeader('TITLE', 'Skillset');
diff --git a/test/eventhandler.test.js b/test/eventhandler.test.js
index 7d2e3cf3..6c8927d3 100644
--- a/test/eventhandler.test.js
+++ b/test/eventhandler.test.js
@@ -23,4 +23,53 @@ describe('EventHandler', function() {
     ev.trigger(2);
     expect(calls).to.eql(['a2', 'c2']);
   });
+
+  it('uses a stable dispatch snapshot when handlers mutate subscriptions', function() {
+    const ev = new EventHandler();
+    const calls = [];
+    const late = () => calls.push('late');
+    const third = () => calls.push('third');
+    const first = () => {
+      calls.push('first');
+      ev.off(third);
+      ev.on(late);
+    };
+    const second = () => calls.push('second');
+
+    ev.on(first);
+    ev.on(second);
+    ev.on(third);
+    ev.trigger();
+    expect(calls).to.eql(['first', 'second', 'third']);
+
+    calls.length = 0;
+    ev.trigger();
+    expect(calls).to.eql(['first', 'second', 'late']);
+  });
+
+  it('reuses the listener snapshot until subscriptions change', function() {
+    const ev = new EventHandler();
+    let calls = 0;
+    let snapshots = 0;
+    const originalFrom = Array.from;
+    ev.on(() => { calls += 1; });
+
+    try {
+      Array.from = function(...args) {
+        snapshots += 1;
+        return originalFrom.apply(this, args);
+      };
+      ev.trigger();
+      ev.trigger();
+      expect(calls).to.equal(2);
+      expect(snapshots).to.equal(1);
+
+      ev.on(() => { calls += 1; });
+      ev.trigger();
+      expect(calls).to.equal(4);
+      expect(snapshots).to.equal(2);
+    } finally {
+      Array.from = originalFrom;
+    }
+  });
 });
diff --git a/test/fileprovider.01-fileprovider.test.js b/test/fileprovider.01-fileprovider.test.js
new file mode 100644
index 00000000..c06682ca
--- /dev/null
+++ b/test/fileprovider.01-fileprovider.test.js
@@ -0,0 +1,435 @@
+import assert from 'assert';
+import { FileProvider } from '../js/data/FileProvider.js';
+import { Lemmings, setDependency } from './helpers/lemmings.js';
+
+class MockBinaryReader {}
+class MockLogHandler {
+  constructor() {
+    this.logged = [];
+    this.debugged = [];
+  }
+  log(msg) {
+    this.logged.push(msg);
+  }
+  debug(msg) {
+    this.debugged.push(msg);
+  }
+}
+let origBR;
+let origLog;
+let origIndexedDb;
+
+const createIndexedDb = ({ failOpen = false } = {}) => {
+  const stores = new Map();
+  const keyPaths = new Map();
+  const indexes = new Map();
+  const objectStoreNames = {
+    contains(name) {
+      return stores.has(name);
+    }
+  };
+
+  const makeRequest = (result, error = null) => {
+    const request = { result: undefined, error };
+    setTimeout(() => {
+      if (error) {
+        request.onerror?.();
+      } else {
+        request.result = result;
+        request.onsuccess?.();
+      }
+    }, 0);
+    return request;
+  };
+
+  const makeCursorRequest = (map, field) => {
+    const entries = Array.from(map.values())
+      .slice()
+      .sort((a, b) => (a?.[field] ?? 0) - (b?.[field] ?? 0));
+    let idx = 0;
+    const request = {};
+    const cursor = {
+      get value() {
+        return entries[idx];
+      },
+      continue() {
+        idx += 1;
+        trigger();
+      }
+    };
+    const trigger = () => {
+      setTimeout(() => {
+        request.result = idx < entries.length ? cursor : null;
+        request.onsuccess?.();
+      }, 0);
+    };
+    trigger();
+    return request;
+  };
+
+  const ensureStore = (name, keyPath = 'id') => {
+    if (!stores.has(name)) stores.set(name, new Map());
+    if (!keyPaths.has(name)) keyPaths.set(name, keyPath);
+    if (!indexes.has(name)) indexes.set(name, new Map());
+  };
+
+  const createStore = (name) => {
+    ensureStore(name);
+    const map = stores.get(name);
+    const keyPath = keyPaths.get(name);
+    const indexMap = indexes.get(name);
+    return {
+      get(key) {
+        return makeRequest(map.get(key));
+      },
+      put(value) {
+        const key = keyPath ? value?.[keyPath] : value?.key;
+        map.set(key, value);
+        return makeRequest(value);
+      },
+      delete(key) {
+        map.delete(key);
+        return makeRequest(undefined);
+      },
+      createIndex(indexName, field) {
+        indexMap.set(indexName, { field });
+        return {};
+      },
+      index(indexName) {
+        const idx = indexMap.get(indexName);
+        return {
+          openCursor() {
+            return makeCursorRequest(map, idx?.field);
+          }
+        };
+      }
+    };
+  };
+
+  const db = {
+    objectStoreNames,
+    createObjectStore(name, options = {}) {
+      ensureStore(name, options.keyPath);
+      return createStore(name);
+    },
+    transaction(storeNames) {
+      const names = Array.isArray(storeNames) ? storeNames : [storeNames];
+      names.forEach((name) => ensureStore(name));
+      return {
+        objectStore(name) {
+          return createStore(name);
+        }
+      };
+    },
+    close() {}
+  };
+
+  return {
+    open() {
+      const request = {};
+      setTimeout(() => {
+        if (failOpen) {
+          request.error = new Error('indexeddb open failed');
+          request.onerror?.();
+          return;
+        }
+        request.result = db;
+        request.onupgradeneeded?.();
+        request.onsuccess?.();
+      }, 0);
+      return request;
+    },
+    _stores: stores
+  };
+};
+
+describe('FileProvider', function () {
+  const rootPath = '/base/';
+
+  let provider;
+
+  let requests;
+
+  let restore;
+
+  let origFetch;
+
+  const makeUrl = (name) => rootPath + name;
+
+  const cacheKey = (url) => `lem-cache:${url}`;
+
+  const setCacheEntry = (url, entry) => {
+    global.localStorage.setItem(cacheKey(url), JSON.stringify(entry));
+  };
+
+  const setCacheRaw = (url, raw) => {
+    global.localStorage.setItem(cacheKey(url), raw);
+  };
+
+  const setBinaryCache = (url, buffer, hash) => {
+    const entry = {
+      type: 'binary',
+      data: provider._arrayBufferToBase64(buffer),
+      ...(hash ? { hash } : {})
+    };
+    setCacheEntry(url, entry);
+  };
+
+  const setTextCache = (url, data) => {
+    setCacheEntry(url, { type: 'text', data });
+  };
+
+  const setupIndexedDb = ({
+    loadFromIndexedDb = async () => null,
+    loadFromLocalStorage
+  } = {}) => {
+    provider._canUseIndexedDb = () => true;
+    provider._loadFromIndexedDb = loadFromIndexedDb;
+    if (typeof loadFromLocalStorage === 'function') {
+      provider._loadFromLocalStorage = loadFromLocalStorage;
+    }
+  };
+
+  const makeFetchCounter = (impl) => {
+    let calls = 0;
+    const fn = async (...args) => {
+      calls += 1;
+      return impl(...args);
+    };
+    return { fn, get calls() { return calls; } };
+  };
+
+  beforeEach(function () {
+    origBR = Lemmings.BinaryReader;
+    origLog = Lemmings.LogHandler;
+    origIndexedDb = global.indexedDB;
+    setDependency('BinaryReader', MockBinaryReader);
+    setDependency('LogHandler', MockLogHandler);
+    provider = new FileProvider(rootPath);
+    global.localStorage = new (class {
+      constructor() { this.store = new Map(); }
+      getItem(k) { return this.store.has(k) ? this.store.get(k) : null; }
+      setItem(k, v) { this.store.set(k, v); }
+      removeItem(k) { this.store.delete(k); }
+      clear() { this.store.clear(); }
+    })();
+    origFetch = global.fetch;
+    delete global.fetch; // disable HEAD requests
+    requests = [];
+    class FakeXHR {
+      constructor() {
+        this.status = 0;
+        this.response = null;
+        FakeXHR.instances.push(this);
+      }
+      open(method, url) {
+        this.method = method;
+        this.url = url;
+      }
+      send() {}
+      respond(status, body) {
+        this.status = status;
+        this.response = body;
+        if (status >= 200 && status < 300) {
+          if (this.onload) this.onload();
+        } else {
+          if (this.onerror) this.onerror();
+        }
+      }
+    }
+    FakeXHR.instances = [];
+    requests = FakeXHR.instances;
+    global.XMLHttpRequest = FakeXHR;
+    restore = () => {
+      delete global.XMLHttpRequest;
+    };
+  });
+
+  afterEach(function () {
+    restore();
+    delete global.localStorage;
+    if (origIndexedDb === undefined) {
+      delete global.indexedDB;
+    } else {
+      global.indexedDB = origIndexedDb;
+    }
+    if (origFetch) {
+      global.fetch = origFetch;
+    }
+    provider.clearCache();
+    setDependency('BinaryReader', origBR);
+    setDependency('LogHandler', origLog);
+  });
+
+  it('_buildUrl() joins rootPath, path and filename', function () {
+    const url = provider._buildUrl('path', 'file.bin');
+    assert.strictEqual(url, rootPath + 'path' + '/' + 'file.bin');
+    const noFile = provider._buildUrl('path', null);
+    assert.strictEqual(noFile, rootPath + 'path');
+  });
+
+  it('applies cache-bust revision to binary and text urls', function () {
+    provider = new FileProvider(rootPath, { cacheBustRevision: 'phase30a' });
+    const binaryUrl = provider._buildUrl('path', 'file.bin');
+    const textUrl = provider._appendCacheBust(makeUrl('config.json'));
+    assert.strictEqual(binaryUrl, rootPath + 'path/file.bin?rev=phase30a');
+    assert.strictEqual(textUrl, rootPath + 'config.json?rev=phase30a');
+  });
+
+  it('_filenameFromUrl strips query and handles empty', function () {
+    const name = provider._filenameFromUrl('http://x/y/file.bin?x=1#hash');
+    assert.strictEqual(name, 'file.bin');
+    assert.strictEqual(provider._filenameFromUrl(''), '');
+  });
+
+  it('loadBinary caches identical requests', async function () {
+    const p1 = provider.loadBinary('data', 'file.bin');
+    const p2 = provider.loadBinary('data', 'file.bin');
+    assert.strictEqual(p1, p2);
+    assert.strictEqual(requests.length, 1);
+
+    const buffer = new ArrayBuffer(0);
+    requests[0].respond(200, buffer);
+    const result = await p1;
+    assert.ok(result instanceof MockBinaryReader);
+
+    const p3 = provider.loadBinary('data', 'file.bin');
+    assert.strictEqual(p1, p3);
+    assert.strictEqual(requests.length, 1);
+  });
+
+  it('loadString caches identical requests', async function () {
+    const url = makeUrl('text.txt');
+    const p1 = provider.loadString(url);
+    const p2 = provider.loadString(url);
+    assert.strictEqual(p1, p2);
+    assert.strictEqual(requests.length, 1);
+
+    requests[0].respond(200, 'hello');
+    const result = await p1;
+    assert.strictEqual(result, 'hello');
+
+    const p3 = provider.loadString(url);
+    assert.strictEqual(p1, p3);
+    assert.strictEqual(requests.length, 1);
+  });
+
+  it('loadString clears cache on failure', async function () {
+    const url = makeUrl('fail.txt');
+    const promise = provider.loadString(url);
+    assert.strictEqual(provider._cache.size, 1);
+    requests[0].respond(500, 'err');
+    await assert.rejects(promise);
+    assert.strictEqual(provider._cache.has(url), false);
+  });
+
+  it('clearCache() empties the internal cache', async function () {
+    const url = makeUrl('file.txt');
+    const p1 = provider.loadString(url);
+    requests[0].respond(200, 'ok');
+    await p1;
+    assert.strictEqual(provider._cache.size, 1);
+    provider.clearCache();
+    assert.strictEqual(provider._cache.size, 0);
+  });
+
+  it('getCacheStats reports cache counters', function () {
+    provider._cache.set('a', Promise.resolve('x'));
+    provider._cacheStats.localStorageBytes = 12;
+    provider._cacheStats.indexedDbBytes = 34;
+    assert.deepStrictEqual(provider.getCacheStats(), {
+      memoryEntries: 1,
+      localStorageBytes: 12,
+      indexedDbBytes: 34
+    });
+  });
+
+  it('stores data in localStorage and reuses it', async function () {
+    const url = makeUrl('text.txt');
+    const p1 = provider.loadString(url);
+    requests[0].respond(200, 'hello');
+    const result1 = await p1;
+    assert.strictEqual(result1, 'hello');
+    const stored = global.localStorage.getItem(cacheKey(url));
+    assert.ok(stored, 'entry stored');
+
+    // new provider simulating page reload
+    provider = new FileProvider(rootPath);
+    const p2 = provider.loadString(url);
+    assert.strictEqual(requests.length, 1, 'no new XHR');
+    const result2 = await p2;
+    assert.strictEqual(result2, 'hello');
+  });
+
+  it('loadBinary uses cached binary entries from localStorage', async function () {
+    provider = new FileProvider(rootPath);
+    const data = Uint8Array.from([1, 2, 3]).buffer;
+    const url = makeUrl('data/file.bin');
+    setBinaryCache(url, data, 'h');
+
+    const result = await provider.loadBinary('data', 'file.bin');
+    assert.ok(result instanceof MockBinaryReader);
+    assert.strictEqual(requests.length, 0);
+  });
+
+  it('falls back to fetching when cached JSON is invalid', async function () {
+    const url = makeUrl('bad.txt');
+    setCacheRaw(url, '{bad');
+    const promise = provider.loadString(url);
+    requests[0].respond(200, 'ok');
+    const result = await promise;
+    assert.strictEqual(result, 'ok');
+  });
+
+  it('logs an error when binary load fails', async function () {
+    const p = provider.loadBinary('data', 'file.bin');
+    requests[0].respond(404, null);
+    await assert.rejects(p);
+    assert.ok(provider.log.logged.some(m => m.includes('error load file')));
+  });
+
+  it('loadBinary bypasses cache when forceReload is true', async function () {
+    let calls = 0;
+    provider._fetchBinary = async () => {
+      calls++;
+      return new MockBinaryReader();
+    };
+    const url = provider._buildUrl('data', 'file.bin');
+
+    const p1 = provider.loadBinary('data', 'file.bin');
+    assert.strictEqual(calls, 1);
+    await p1;
+
+    const p2 = provider.loadBinary('data', 'file.bin');
+    assert.strictEqual(p2, p1);
+    assert.strictEqual(calls, 1);
+    await p2;
+
+    const p3 = provider.loadBinary('data', 'file.bin', { forceReload: true });
+    assert.notStrictEqual(p3, p1);
+    assert.strictEqual(calls, 2);
+    await p3;
+
+    assert.strictEqual(provider._cache.get(url), p1);
+  });
+
+  it('loadBinary uses indexedDB path when enabled and uncached', async function () {
+    setupIndexedDb();
+    const fetchBinary = makeFetchCounter(async () => new MockBinaryReader());
+    provider._fetchBinary = fetchBinary.fn;
+
+    const result = await provider.loadBinary('data', 'missing.bin');
+    assert.ok(result instanceof MockBinaryReader);
+    assert.strictEqual(fetchBinary.calls, 1);
+  });
+
+  it('loadBinary falls back when indexedDB rejects', async function () {
+    setupIndexedDb({ loadFromIndexedDb: async () => { throw new Error('fail'); } });
+    const fetchBinary = makeFetchCounter(async () => new MockBinaryReader());
+    provider._fetchBinary = fetchBinary.fn;
+
+    const result = await provider.loadBinary('data', 'missing.bin');
+    assert.ok(result instanceof MockBinaryReader);
+    assert.strictEqual(fetchBinary.calls, 1);
+  });
+});
diff --git a/test/fileprovider.02-fileprovider.test.js b/test/fileprovider.02-fileprovider.test.js
new file mode 100644
index 00000000..97f200fd
--- /dev/null
+++ b/test/fileprovider.02-fileprovider.test.js
@@ -0,0 +1,437 @@
+import assert from 'assert';
+import { FileProvider } from '../js/data/FileProvider.js';
+import { Lemmings, setDependency } from './helpers/lemmings.js';
+
+class MockBinaryReader {}
+class MockLogHandler {
+  constructor() {
+    this.logged = [];
+    this.debugged = [];
+  }
+  log(msg) {
+    this.logged.push(msg);
+  }
+  debug(msg) {
+    this.debugged.push(msg);
+  }
+}
+let origBR;
+let origLog;
+let origIndexedDb;
+
+const createIndexedDb = ({ failOpen = false } = {}) => {
+  const stores = new Map();
+  const keyPaths = new Map();
+  const indexes = new Map();
+  const objectStoreNames = {
+    contains(name) {
+      return stores.has(name);
+    }
+  };
+
+  const makeRequest = (result, error = null) => {
+    const request = { result: undefined, error };
+    setTimeout(() => {
+      if (error) {
+        request.onerror?.();
+      } else {
+        request.result = result;
+        request.onsuccess?.();
+      }
+    }, 0);
+    return request;
+  };
+
+  const makeCursorRequest = (map, field) => {
+    const entries = Array.from(map.values())
+      .slice()
+      .sort((a, b) => (a?.[field] ?? 0) - (b?.[field] ?? 0));
+    let idx = 0;
+    const request = {};
+    const cursor = {
+      get value() {
+        return entries[idx];
+      },
+      continue() {
+        idx += 1;
+        trigger();
+      }
+    };
+    const trigger = () => {
+      setTimeout(() => {
+        request.result = idx < entries.length ? cursor : null;
+        request.onsuccess?.();
+      }, 0);
+    };
+    trigger();
+    return request;
+  };
+
+  const ensureStore = (name, keyPath = 'id') => {
+    if (!stores.has(name)) stores.set(name, new Map());
+    if (!keyPaths.has(name)) keyPaths.set(name, keyPath);
+    if (!indexes.has(name)) indexes.set(name, new Map());
+  };
+
+  const createStore = (name) => {
+    ensureStore(name);
+    const map = stores.get(name);
+    const keyPath = keyPaths.get(name);
+    const indexMap = indexes.get(name);
+    return {
+      get(key) {
+        return makeRequest(map.get(key));
+      },
+      put(value) {
+        const key = keyPath ? value?.[keyPath] : value?.key;
+        map.set(key, value);
+        return makeRequest(value);
+      },
+      delete(key) {
+        map.delete(key);
+        return makeRequest(undefined);
+      },
+      createIndex(indexName, field) {
+        indexMap.set(indexName, { field });
+        return {};
+      },
+      index(indexName) {
+        const idx = indexMap.get(indexName);
+        return {
+          openCursor() {
+            return makeCursorRequest(map, idx?.field);
+          }
+        };
+      }
+    };
+  };
+
+  const db = {
+    objectStoreNames,
+    createObjectStore(name, options = {}) {
+      ensureStore(name, options.keyPath);
+      return createStore(name);
+    },
+    transaction(storeNames) {
+      const names = Array.isArray(storeNames) ? storeNames : [storeNames];
+      names.forEach((name) => ensureStore(name));
+      return {
+        objectStore(name) {
+          return createStore(name);
+        }
+      };
+    },
+    close() {}
+  };
+
+  return {
+    open() {
+      const request = {};
+      setTimeout(() => {
+        if (failOpen) {
+          request.error = new Error('indexeddb open failed');
+          request.onerror?.();
+          return;
+        }
+        request.result = db;
+        request.onupgradeneeded?.();
+        request.onsuccess?.();
+      }, 0);
+      return request;
+    },
+    _stores: stores
+  };
+};
+
+describe('FileProvider', function () {
+  const rootPath = '/base/';
+
+  let provider;
+
+  let requests;
+
+  let restore;
+
+  let origFetch;
+
+  const makeUrl = (name) => rootPath + name;
+
+  const cacheKey = (url) => `lem-cache:${url}`;
+
+  const setCacheEntry = (url, entry) => {
+    global.localStorage.setItem(cacheKey(url), JSON.stringify(entry));
+  };
+
+  const setCacheRaw = (url, raw) => {
+    global.localStorage.setItem(cacheKey(url), raw);
+  };
+
+  const setBinaryCache = (url, buffer, hash) => {
+    const entry = {
+      type: 'binary',
+      data: provider._arrayBufferToBase64(buffer),
+      ...(hash ? { hash } : {})
+    };
+    setCacheEntry(url, entry);
+  };
+
+  const setTextCache = (url, data) => {
+    setCacheEntry(url, { type: 'text', data });
+  };
+
+  const setupIndexedDb = ({
+    loadFromIndexedDb = async () => null,
+    loadFromLocalStorage
+  } = {}) => {
+    provider._canUseIndexedDb = () => true;
+    provider._loadFromIndexedDb = loadFromIndexedDb;
+    if (typeof loadFromLocalStorage === 'function') {
+      provider._loadFromLocalStorage = loadFromLocalStorage;
+    }
+  };
+
+  const makeFetchCounter = (impl) => {
+    let calls = 0;
+    const fn = async (...args) => {
+      calls += 1;
+      return impl(...args);
+    };
+    return { fn, get calls() { return calls; } };
+  };
+
+  beforeEach(function () {
+    origBR = Lemmings.BinaryReader;
+    origLog = Lemmings.LogHandler;
+    origIndexedDb = global.indexedDB;
+    setDependency('BinaryReader', MockBinaryReader);
+    setDependency('LogHandler', MockLogHandler);
+    provider = new FileProvider(rootPath);
+    global.localStorage = new (class {
+      constructor() { this.store = new Map(); }
+      getItem(k) { return this.store.has(k) ? this.store.get(k) : null; }
+      setItem(k, v) { this.store.set(k, v); }
+      removeItem(k) { this.store.delete(k); }
+      clear() { this.store.clear(); }
+    })();
+    origFetch = global.fetch;
+    delete global.fetch; // disable HEAD requests
+    requests = [];
+    class FakeXHR {
+      constructor() {
+        this.status = 0;
+        this.response = null;
+        FakeXHR.instances.push(this);
+      }
+      open(method, url) {
+        this.method = method;
+        this.url = url;
+      }
+      send() {}
+      respond(status, body) {
+        this.status = status;
+        this.response = body;
+        if (status >= 200 && status < 300) {
+          if (this.onload) this.onload();
+        } else {
+          if (this.onerror) this.onerror();
+        }
+      }
+    }
+    FakeXHR.instances = [];
+    requests = FakeXHR.instances;
+    global.XMLHttpRequest = FakeXHR;
+    restore = () => {
+      delete global.XMLHttpRequest;
+    };
+  });
+
+  afterEach(function () {
+    restore();
+    delete global.localStorage;
+    if (origIndexedDb === undefined) {
+      delete global.indexedDB;
+    } else {
+      global.indexedDB = origIndexedDb;
+    }
+    if (origFetch) {
+      global.fetch = origFetch;
+    }
+    provider.clearCache();
+    setDependency('BinaryReader', origBR);
+    setDependency('LogHandler', origLog);
+  });
+
+  it('loadBinary uses localStorage fallback after indexedDB error', async function () {
+    setupIndexedDb({
+      loadFromIndexedDb: async () => { throw new Error('fail'); },
+      loadFromLocalStorage: () => ({ value: new MockBinaryReader() })
+    });
+    provider._fetchBinary = async () => { throw new Error('should not fetch'); };
+
+    const result = await provider.loadBinary('data', 'missing.bin');
+    assert.ok(result instanceof MockBinaryReader);
+  });
+
+  it('loadBinary reads localStorage when indexedDB rejects', async function () {
+    setupIndexedDb({ loadFromIndexedDb: async () => { throw new Error('fail'); } });
+    const url = provider._buildUrl('data', 'cached.bin');
+    const buf = Uint8Array.from([1, 2, 3]).buffer;
+    setBinaryCache(url, buf);
+    provider._fetchBinary = async () => { throw new Error('should not fetch'); };
+
+    const result = await provider.loadBinary('data', 'cached.bin');
+    assert.ok(result instanceof MockBinaryReader);
+  });
+
+  it('loadString uses indexedDB path when enabled and uncached', async function () {
+    setupIndexedDb();
+    const fetchText = makeFetchCounter(async () => 'ok');
+    provider._fetchText = fetchText.fn;
+
+    const result = await provider.loadString(makeUrl('missing.txt'));
+    assert.strictEqual(result, 'ok');
+    assert.strictEqual(fetchText.calls, 1);
+  });
+
+  it('loadString falls back when indexedDB rejects', async function () {
+    setupIndexedDb({ loadFromIndexedDb: async () => { throw new Error('fail'); } });
+    const fetchText = makeFetchCounter(async () => 'ok');
+    provider._fetchText = fetchText.fn;
+
+    const result = await provider.loadString(makeUrl('missing.txt'));
+    assert.strictEqual(result, 'ok');
+    assert.strictEqual(fetchText.calls, 1);
+  });
+
+  it('loadString uses cached indexedDB value', async function () {
+    setupIndexedDb({ loadFromIndexedDb: async () => ({ value: 'cached' }) });
+    provider._fetchText = async () => { throw new Error('should not fetch'); };
+    const result = await provider.loadString(makeUrl('cached.txt'));
+    assert.strictEqual(result, 'cached');
+  });
+
+  it('loadString uses localStorage fallback after indexedDB error', async function () {
+    setupIndexedDb({
+      loadFromIndexedDb: async () => { throw new Error('fail'); },
+      loadFromLocalStorage: () => ({ value: 'cached' })
+    });
+    provider._fetchText = async () => { throw new Error('should not fetch'); };
+    const result = await provider.loadString(makeUrl('cached.txt'));
+    assert.strictEqual(result, 'cached');
+  });
+
+  it('loadString uses localStorage after indexedDB rejection', async function () {
+    setupIndexedDb({ loadFromIndexedDb: async () => { throw new Error('fail'); } });
+    const url = makeUrl('cached.txt');
+    setTextCache(url, 'stored');
+    provider._fetchText = async () => { throw new Error('should not fetch'); };
+    const result = await provider.loadString(url);
+    assert.strictEqual(result, 'stored');
+  });
+
+  it('refreshes cached text entries when headers change', async function () {
+    let textFetched = 0;
+    provider._fetchHead = async () => ({ etag: 'new' });
+    provider._fetchText = async () => { textFetched++; };
+    await provider._verifyCache('file.txt', { type: 'text', etag: 'old' });
+    assert.strictEqual(textFetched, 1);
+  });
+
+  it('stores response headers when available for text and binary', async function () {
+    class HeaderXHR {
+      constructor() {
+        this.status = 0;
+        this.response = null;
+        HeaderXHR.instances.push(this);
+      }
+      open(method, url) { this.method = method; this.url = url; }
+      send() {}
+      getResponseHeader(name) {
+        if (name === 'ETag') return 'etag-value';
+        if (name === 'Last-Modified') return 'modified';
+        return null;
+      }
+      respond(status, body) {
+        this.status = status;
+        this.response = body;
+        if (status >= 200 && status < 300) {
+          if (this.onload) this.onload();
+        } else if (this.onerror) {
+          this.onerror();
+        }
+      }
+    }
+    HeaderXHR.instances = [];
+    global.XMLHttpRequest = HeaderXHR;
+
+    const textUrl = makeUrl('headers.txt');
+    const textPromise = provider.loadString(textUrl);
+    HeaderXHR.instances[0].respond(200, 'ok');
+    await textPromise;
+    const textEntry = JSON.parse(global.localStorage.getItem(cacheKey(textUrl)));
+    assert.strictEqual(textEntry.etag, 'etag-value');
+
+    const binPromise = provider.loadBinary('data', 'file.bin');
+    const buffer = new ArrayBuffer(0);
+    HeaderXHR.instances[1].respond(200, buffer);
+    await binPromise;
+    const binUrl = provider._buildUrl('data', 'file.bin');
+    const binEntry = JSON.parse(global.localStorage.getItem(cacheKey(binUrl)));
+    assert.strictEqual(binEntry.lastModified, 'modified');
+  });
+
+  it('requires Web Crypto hashing and reports unavailable runtimes', async function () {
+    const origDescriptor = Object.getOwnPropertyDescriptor(globalThis, 'crypto');
+    try {
+      Object.defineProperty(globalThis, 'crypto', { value: undefined, configurable: true });
+      await assert.rejects(provider._hashBuffer(new Uint8Array([4]).buffer), /crypto API not available/);
+    } finally {
+      if (origDescriptor) {
+        Object.defineProperty(globalThis, 'crypto', origDescriptor);
+      } else {
+        delete globalThis.crypto;
+      }
+    }
+  });
+
+  it('stores response headers for binary entries when available', async function () {
+    const p = provider.loadBinary('data', 'with-headers.bin');
+    const url = provider._buildUrl('data', 'with-headers.bin');
+    requests[0].getResponseHeader = key => (key === 'ETag' ? 'etag' : 'last');
+    requests[0].respond(200, new ArrayBuffer(1));
+    await p;
+    const entry = JSON.parse(global.localStorage.getItem(cacheKey(url)));
+    assert.strictEqual(entry.etag, 'etag');
+    assert.strictEqual(entry.lastModified, 'last');
+  });
+
+  it('stores response headers for text entries when available', async function () {
+    const url = makeUrl('with-headers.txt');
+    const p = provider.loadString(url);
+    requests[0].getResponseHeader = key => (key === 'ETag' ? 'etag' : 'last');
+    requests[0].respond(200, 'ok');
+    await p;
+    const entry = JSON.parse(global.localStorage.getItem(cacheKey(url)));
+    assert.strictEqual(entry.etag, 'etag');
+    assert.strictEqual(entry.lastModified, 'last');
+  });
+
+  it('_verifyCache refreshes stale entries', async function () {
+    let headCalls = 0;
+    let fetchCalls = 0;
+    provider._fetchHead = async () => {
+      headCalls++;
+      return { etag: 'new', lastModified: 'new' };
+    };
+    provider._fetchBinary = async () => {
+      fetchCalls++;
+      return new MockBinaryReader();
+    };
+
+    const entry = { type: 'binary', etag: 'old', lastModified: 'old' };
+    await provider._verifyCache('some/url', entry);
+
+    assert.strictEqual(headCalls, 1);
+    assert.strictEqual(fetchCalls, 1);
+  });
+});
diff --git a/test/fileprovider.03-fileprovider.test.js b/test/fileprovider.03-fileprovider.test.js
new file mode 100644
index 00000000..2b997d1e
--- /dev/null
+++ b/test/fileprovider.03-fileprovider.test.js
@@ -0,0 +1,443 @@
+import assert from 'assert';
+import { FileProvider } from '../js/data/FileProvider.js';
+import { Lemmings, setDependency } from './helpers/lemmings.js';
+
+class MockBinaryReader {}
+class MockLogHandler {
+  constructor() {
+    this.logged = [];
+    this.debugged = [];
+  }
+  log(msg) {
+    this.logged.push(msg);
+  }
+  debug(msg) {
+    this.debugged.push(msg);
+  }
+}
+let origBR;
+let origLog;
+let origIndexedDb;
+
+const createIndexedDb = ({ failOpen = false } = {}) => {
+  const stores = new Map();
+  const keyPaths = new Map();
+  const indexes = new Map();
+  const objectStoreNames = {
+    contains(name) {
+      return stores.has(name);
+    }
+  };
+
+  const makeRequest = (result, error = null) => {
+    const request = { result: undefined, error };
+    setTimeout(() => {
+      if (error) {
+        request.onerror?.();
+      } else {
+        request.result = result;
+        request.onsuccess?.();
+      }
+    }, 0);
+    return request;
+  };
+
+  const makeCursorRequest = (map, field) => {
+    const entries = Array.from(map.values())
+      .slice()
+      .sort((a, b) => (a?.[field] ?? 0) - (b?.[field] ?? 0));
+    let idx = 0;
+    const request = {};
+    const cursor = {
+      get value() {
+        return entries[idx];
+      },
+      continue() {
+        idx += 1;
+        trigger();
+      }
+    };
+    const trigger = () => {
+      setTimeout(() => {
+        request.result = idx < entries.length ? cursor : null;
+        request.onsuccess?.();
+      }, 0);
+    };
+    trigger();
+    return request;
+  };
+
+  const ensureStore = (name, keyPath = 'id') => {
+    if (!stores.has(name)) stores.set(name, new Map());
+    if (!keyPaths.has(name)) keyPaths.set(name, keyPath);
+    if (!indexes.has(name)) indexes.set(name, new Map());
+  };
+
+  const createStore = (name) => {
+    ensureStore(name);
+    const map = stores.get(name);
+    const keyPath = keyPaths.get(name);
+    const indexMap = indexes.get(name);
+    return {
+      get(key) {
+        return makeRequest(map.get(key));
+      },
+      put(value) {
+        const key = keyPath ? value?.[keyPath] : value?.key;
+        map.set(key, value);
+        return makeRequest(value);
+      },
+      delete(key) {
+        map.delete(key);
+        return makeRequest(undefined);
+      },
+      createIndex(indexName, field) {
+        indexMap.set(indexName, { field });
+        return {};
+      },
+      index(indexName) {
+        const idx = indexMap.get(indexName);
+        return {
+          openCursor() {
+            return makeCursorRequest(map, idx?.field);
+          }
+        };
+      }
+    };
+  };
+
+  const db = {
+    objectStoreNames,
+    createObjectStore(name, options = {}) {
+      ensureStore(name, options.keyPath);
+      return createStore(name);
+    },
+    transaction(storeNames) {
+      const names = Array.isArray(storeNames) ? storeNames : [storeNames];
+      names.forEach((name) => ensureStore(name));
+      return {
+        objectStore(name) {
+          return createStore(name);
+        }
+      };
+    },
+    close() {}
+  };
+
+  return {
+    open() {
+      const request = {};
+      setTimeout(() => {
+        if (failOpen) {
+          request.error = new Error('indexeddb open failed');
+          request.onerror?.();
+          return;
+        }
+        request.result = db;
+        request.onupgradeneeded?.();
+        request.onsuccess?.();
+      }, 0);
+      return request;
+    },
+    _stores: stores
+  };
+};
+
+describe('FileProvider', function () {
+  const rootPath = '/base/';
+
+  let provider;
+
+  let requests;
+
+  let restore;
+
+  let origFetch;
+
+  const makeUrl = (name) => rootPath + name;
+
+  const cacheKey = (url) => `lem-cache:${url}`;
+
+  const setCacheEntry = (url, entry) => {
+    global.localStorage.setItem(cacheKey(url), JSON.stringify(entry));
+  };
+
+  const setCacheRaw = (url, raw) => {
+    global.localStorage.setItem(cacheKey(url), raw);
+  };
+
+  const setBinaryCache = (url, buffer, hash) => {
+    const entry = {
+      type: 'binary',
+      data: provider._arrayBufferToBase64(buffer),
+      ...(hash ? { hash } : {})
+    };
+    setCacheEntry(url, entry);
+  };
+
+  const setTextCache = (url, data) => {
+    setCacheEntry(url, { type: 'text', data });
+  };
+
+  const setupIndexedDb = ({
+    loadFromIndexedDb = async () => null,
+    loadFromLocalStorage
+  } = {}) => {
+    provider._canUseIndexedDb = () => true;
+    provider._loadFromIndexedDb = loadFromIndexedDb;
+    if (typeof loadFromLocalStorage === 'function') {
+      provider._loadFromLocalStorage = loadFromLocalStorage;
+    }
+  };
+
+  const makeFetchCounter = (impl) => {
+    let calls = 0;
+    const fn = async (...args) => {
+      calls += 1;
+      return impl(...args);
+    };
+    return { fn, get calls() { return calls; } };
+  };
+
+  beforeEach(function () {
+    origBR = Lemmings.BinaryReader;
+    origLog = Lemmings.LogHandler;
+    origIndexedDb = global.indexedDB;
+    setDependency('BinaryReader', MockBinaryReader);
+    setDependency('LogHandler', MockLogHandler);
+    provider = new FileProvider(rootPath);
+    global.localStorage = new (class {
+      constructor() { this.store = new Map(); }
+      getItem(k) { return this.store.has(k) ? this.store.get(k) : null; }
+      setItem(k, v) { this.store.set(k, v); }
+      removeItem(k) { this.store.delete(k); }
+      clear() { this.store.clear(); }
+    })();
+    origFetch = global.fetch;
+    delete global.fetch; // disable HEAD requests
+    requests = [];
+    class FakeXHR {
+      constructor() {
+        this.status = 0;
+        this.response = null;
+        FakeXHR.instances.push(this);
+      }
+      open(method, url) {
+        this.method = method;
+        this.url = url;
+      }
+      send() {}
+      respond(status, body) {
+        this.status = status;
+        this.response = body;
+        if (status >= 200 && status < 300) {
+          if (this.onload) this.onload();
+        } else {
+          if (this.onerror) this.onerror();
+        }
+      }
+    }
+    FakeXHR.instances = [];
+    requests = FakeXHR.instances;
+    global.XMLHttpRequest = FakeXHR;
+    restore = () => {
+      delete global.XMLHttpRequest;
+    };
+  });
+
+  afterEach(function () {
+    restore();
+    delete global.localStorage;
+    if (origIndexedDb === undefined) {
+      delete global.indexedDB;
+    } else {
+      global.indexedDB = origIndexedDb;
+    }
+    if (origFetch) {
+      global.fetch = origFetch;
+    }
+    provider.clearCache();
+    setDependency('BinaryReader', origBR);
+    setDependency('LogHandler', origLog);
+  });
+
+  it('_verifyCache returns early on matching headers', async function () {
+    let fetchCalls = 0;
+    provider._fetchHead = async () => ({ etag: 'same', lastModified: 'same' });
+    provider._fetchBinary = async () => { fetchCalls++; return new MockBinaryReader(); };
+    await provider._verifyCache('url', { type: 'binary', etag: 'same' });
+    assert.strictEqual(fetchCalls, 0);
+
+    provider._fetchHead = async () => ({ etag: 'other', lastModified: 'match' });
+    await provider._verifyCache('url', { type: 'binary', lastModified: 'match' });
+    assert.strictEqual(fetchCalls, 0);
+  });
+
+  it('_verifyCache swallows update errors', async function () {
+    provider._fetchHead = async () => ({ etag: 'new', lastModified: 'new' });
+    provider._fetchText = async () => { throw new Error('fail'); };
+    await provider._verifyCache('url', { type: 'text', etag: 'old' });
+    assert.ok(provider.log.logged.some(m => m.includes('cache update error')));
+  });
+
+  it('_verifyCache refreshes stale text entries', async function () {
+    let textCalls = 0;
+    provider._fetchHead = async () => ({ etag: 'new', lastModified: 'new' });
+    provider._fetchText = async () => { textCalls++; };
+    await provider._verifyCache('url', { type: 'text', etag: 'old' });
+    assert.strictEqual(textCalls, 1);
+  });
+
+  it('_hashBuffer rejects when web crypto is missing', async function () {
+    provider = new FileProvider(rootPath);
+    const buf = Uint8Array.from([1,2,3]).buffer;
+    const orig = global.crypto;
+    delete global.crypto;
+    await assert.rejects(provider._hashBuffer(buf), /crypto API not available/);
+    global.crypto = orig;
+  });
+
+  it('_tryHashBuffer returns null when web crypto is missing', async function () {
+    provider = new FileProvider(rootPath);
+    const buf = Uint8Array.from([1, 2, 3]).buffer;
+    const orig = global.crypto;
+    delete global.crypto;
+    const hash = await provider._tryHashBuffer(buf);
+    global.crypto = orig;
+    assert.strictEqual(hash, null);
+  });
+
+  it('_hashBuffer uses web crypto when available', async function () {
+    const orig = global.crypto;
+    global.crypto = {
+      subtle: {
+        digest: async () => Uint8Array.from([0, 255]).buffer
+      }
+    };
+    const buf = Uint8Array.from([1, 2]).buffer;
+    const hash = await provider._hashBuffer(buf);
+    global.crypto = orig;
+    assert.strictEqual(hash, '00ff');
+  });
+
+  it('_hashBuffer throws when crypto APIs are unavailable', async function () {
+    const orig = global.crypto;
+    delete global.crypto;
+    provider._forceCryptoError = true;
+    const buf = Uint8Array.from([1, 2]).buffer;
+    await assert.rejects(provider._hashBuffer(buf), /crypto API not available/);
+    provider._forceCryptoError = false;
+    global.crypto = orig;
+  });
+
+  it('base64 conversion roundtrips', function () {
+    provider = new FileProvider(rootPath);
+    const buf = Uint8Array.from([65,66,67]).buffer;
+    const b64 = provider._arrayBufferToBase64(buf);
+    const out = provider._base64ToArrayBuffer(b64);
+    assert.deepStrictEqual(Array.from(new Uint8Array(out)), [65,66,67]);
+  });
+
+  it('_fetchText stores data and headers in localStorage', async function () {
+    provider._tryHashString = async () => 'h';
+    const url = makeUrl('text.txt');
+    const promise = provider._fetchText(url);
+    requests[0].respond(200, 'hi');
+    const result = await promise;
+    assert.strictEqual(result, 'hi');
+    const entry = JSON.parse(global.localStorage.getItem(cacheKey(url)));
+    assert.strictEqual(entry.type, 'text');
+    assert.strictEqual(entry.data, 'hi');
+    assert.strictEqual(entry.hash, 'h');
+  });
+
+  it('_fetchText resolves when hashing and persistent cache writes fail', async function () {
+    provider._tryHashString = async () => { throw new Error('hash failed'); };
+    provider._storeInCache = async () => { throw new Error('cache failed'); };
+    const url = makeUrl('text-no-cache.txt');
+    const promise = provider._fetchText(url);
+    requests[0].respond(200, 'hi');
+    assert.strictEqual(await promise, 'hi');
+  });
+
+  it('_fetchText logs and rejects on failure', async function () {
+    const promise = provider._fetchText(makeUrl('bad.txt'));
+    requests[0].respond(404, 'err');
+    await assert.rejects(promise);
+    assert.ok(provider.log.logged.some(m => m.includes('error load file')));
+  });
+
+  it('_fetchBinary rejects when onload reports error status', async function () {
+    const promise = provider._fetchBinary(rootPath + 'bad.bin', 'data');
+    const xhr = requests[0];
+    xhr.status = 500;
+    xhr.response = new ArrayBuffer(0);
+    xhr.onload();
+    await assert.rejects(promise);
+    assert.ok(provider.log.logged.some(m => m.includes('error load file')));
+  });
+
+  it('_fetchText rejects when onload reports error status', async function () {
+    const promise = provider._fetchText(makeUrl('bad2.txt'));
+    const xhr = requests[0];
+    xhr.status = 500;
+    xhr.response = 'err';
+    xhr.onload();
+    await assert.rejects(promise);
+    assert.ok(provider.log.logged.some(m => m.includes('error load file')));
+  });
+
+  it('_fetchHead handles missing fetch', async function () {
+    delete global.fetch;
+    const result = await provider._fetchHead('url');
+    assert.strictEqual(result, null);
+  });
+
+  it('_fetchHead returns headers and swallows errors', async function () {
+    global.fetch = async () => {
+      return { headers: { get: key => ({ ETag: 'v', 'Last-Modified': 'm' }[key]) } };
+    };
+    const success = await provider._fetchHead('url');
+    assert.deepStrictEqual(success, { etag: 'v', lastModified: 'm' });
+    global.fetch = async () => { throw new Error('fail'); };
+    const failure = await provider._fetchHead('url');
+    assert.strictEqual(failure, null);
+  });
+
+  it('honors injected fetch and XMLHttpRequest dependencies', async function () {
+    const fetchCalls = [];
+    class InjectedXHR {
+      constructor() {
+        this.status = 0;
+        this.response = '';
+        InjectedXHR.instances.push(this);
+      }
+      open(method, url) {
+        this.method = method;
+        this.url = url;
+      }
+      send() {}
+    }
+    InjectedXHR.instances = [];
+    const injectedProvider = new FileProvider(rootPath, {
+      fetch: async (url, options) => {
+        fetchCalls.push([url, options.method]);
+        return { headers: { get: key => ({ ETag: 'etag-injected', 'Last-Modified': 'modified-injected' }[key]) } };
+      },
+      XMLHttpRequest: InjectedXHR
+    });
+    injectedProvider._hashString = async () => 'hash';
+
+    const head = await injectedProvider._fetchHead('injected-url');
+    assert.deepStrictEqual(fetchCalls, [['injected-url', 'HEAD']]);
+    assert.deepStrictEqual(head, { etag: 'etag-injected', lastModified: 'modified-injected' });
+
+    const promise = injectedProvider._fetchText(rootPath + 'injected.txt');
+    const xhr = InjectedXHR.instances[0];
+    xhr.status = 200;
+    xhr.response = 'ok';
+    xhr.getResponseHeader = () => null;
+    xhr.onload();
+    assert.strictEqual(await promise, 'ok');
+  });
+});
diff --git a/test/fileprovider.04-fileprovider.test.js b/test/fileprovider.04-fileprovider.test.js
new file mode 100644
index 00000000..a454f7d7
--- /dev/null
+++ b/test/fileprovider.04-fileprovider.test.js
@@ -0,0 +1,423 @@
+import assert from 'assert';
+import { FileProvider } from '../js/data/FileProvider.js';
+import { Lemmings, setDependency } from './helpers/lemmings.js';
+
+class MockBinaryReader {}
+class MockLogHandler {
+  constructor() {
+    this.logged = [];
+    this.debugged = [];
+  }
+  log(msg) {
+    this.logged.push(msg);
+  }
+  debug(msg) {
+    this.debugged.push(msg);
+  }
+}
+let origBR;
+let origLog;
+let origIndexedDb;
+
+const createIndexedDb = ({ failOpen = false } = {}) => {
+  const stores = new Map();
+  const keyPaths = new Map();
+  const indexes = new Map();
+  const objectStoreNames = {
+    contains(name) {
+      return stores.has(name);
+    }
+  };
+
+  const makeRequest = (result, error = null) => {
+    const request = { result: undefined, error };
+    setTimeout(() => {
+      if (error) {
+        request.onerror?.();
+      } else {
+        request.result = result;
+        request.onsuccess?.();
+      }
+    }, 0);
+    return request;
+  };
+
+  const makeCursorRequest = (map, field) => {
+    const entries = Array.from(map.values())
+      .slice()
+      .sort((a, b) => (a?.[field] ?? 0) - (b?.[field] ?? 0));
+    let idx = 0;
+    const request = {};
+    const cursor = {
+      get value() {
+        return entries[idx];
+      },
+      continue() {
+        idx += 1;
+        trigger();
+      }
+    };
+    const trigger = () => {
+      setTimeout(() => {
+        request.result = idx < entries.length ? cursor : null;
+        request.onsuccess?.();
+      }, 0);
+    };
+    trigger();
+    return request;
+  };
+
+  const ensureStore = (name, keyPath = 'id') => {
+    if (!stores.has(name)) stores.set(name, new Map());
+    if (!keyPaths.has(name)) keyPaths.set(name, keyPath);
+    if (!indexes.has(name)) indexes.set(name, new Map());
+  };
+
+  const createStore = (name) => {
+    ensureStore(name);
+    const map = stores.get(name);
+    const keyPath = keyPaths.get(name);
+    const indexMap = indexes.get(name);
+    return {
+      get(key) {
+        return makeRequest(map.get(key));
+      },
+      put(value) {
+        const key = keyPath ? value?.[keyPath] : value?.key;
+        map.set(key, value);
+        return makeRequest(value);
+      },
+      delete(key) {
+        map.delete(key);
+        return makeRequest(undefined);
+      },
+      createIndex(indexName, field) {
+        indexMap.set(indexName, { field });
+        return {};
+      },
+      index(indexName) {
+        const idx = indexMap.get(indexName);
+        return {
+          openCursor() {
+            return makeCursorRequest(map, idx?.field);
+          }
+        };
+      }
+    };
+  };
+
+  const db = {
+    objectStoreNames,
+    createObjectStore(name, options = {}) {
+      ensureStore(name, options.keyPath);
+      return createStore(name);
+    },
+    transaction(storeNames) {
+      const names = Array.isArray(storeNames) ? storeNames : [storeNames];
+      names.forEach((name) => ensureStore(name));
+      return {
+        objectStore(name) {
+          return createStore(name);
+        }
+      };
+    },
+    close() {}
+  };
+
+  return {
+    open() {
+      const request = {};
+      setTimeout(() => {
+        if (failOpen) {
+          request.error = new Error('indexeddb open failed');
+          request.onerror?.();
+          return;
+        }
+        request.result = db;
+        request.onupgradeneeded?.();
+        request.onsuccess?.();
+      }, 0);
+      return request;
+    },
+    _stores: stores
+  };
+};
+
+describe('FileProvider', function () {
+  const rootPath = '/base/';
+
+  let provider;
+
+  let requests;
+
+  let restore;
+
+  let origFetch;
+
+  const makeUrl = (name) => rootPath + name;
+
+  const cacheKey = (url) => `lem-cache:${url}`;
+
+  const setCacheEntry = (url, entry) => {
+    global.localStorage.setItem(cacheKey(url), JSON.stringify(entry));
+  };
+
+  const setCacheRaw = (url, raw) => {
+    global.localStorage.setItem(cacheKey(url), raw);
+  };
+
+  const setBinaryCache = (url, buffer, hash) => {
+    const entry = {
+      type: 'binary',
+      data: provider._arrayBufferToBase64(buffer),
+      ...(hash ? { hash } : {})
+    };
+    setCacheEntry(url, entry);
+  };
+
+  const setTextCache = (url, data) => {
+    setCacheEntry(url, { type: 'text', data });
+  };
+
+  const setupIndexedDb = ({
+    loadFromIndexedDb = async () => null,
+    loadFromLocalStorage
+  } = {}) => {
+    provider._canUseIndexedDb = () => true;
+    provider._loadFromIndexedDb = loadFromIndexedDb;
+    if (typeof loadFromLocalStorage === 'function') {
+      provider._loadFromLocalStorage = loadFromLocalStorage;
+    }
+  };
+
+  const makeFetchCounter = (impl) => {
+    let calls = 0;
+    const fn = async (...args) => {
+      calls += 1;
+      return impl(...args);
+    };
+    return { fn, get calls() { return calls; } };
+  };
+
+  beforeEach(function () {
+    origBR = Lemmings.BinaryReader;
+    origLog = Lemmings.LogHandler;
+    origIndexedDb = global.indexedDB;
+    setDependency('BinaryReader', MockBinaryReader);
+    setDependency('LogHandler', MockLogHandler);
+    provider = new FileProvider(rootPath);
+    global.localStorage = new (class {
+      constructor() { this.store = new Map(); }
+      getItem(k) { return this.store.has(k) ? this.store.get(k) : null; }
+      setItem(k, v) { this.store.set(k, v); }
+      removeItem(k) { this.store.delete(k); }
+      clear() { this.store.clear(); }
+    })();
+    origFetch = global.fetch;
+    delete global.fetch; // disable HEAD requests
+    requests = [];
+    class FakeXHR {
+      constructor() {
+        this.status = 0;
+        this.response = null;
+        FakeXHR.instances.push(this);
+      }
+      open(method, url) {
+        this.method = method;
+        this.url = url;
+      }
+      send() {}
+      respond(status, body) {
+        this.status = status;
+        this.response = body;
+        if (status >= 200 && status < 300) {
+          if (this.onload) this.onload();
+        } else {
+          if (this.onerror) this.onerror();
+        }
+      }
+    }
+    FakeXHR.instances = [];
+    requests = FakeXHR.instances;
+    global.XMLHttpRequest = FakeXHR;
+    restore = () => {
+      delete global.XMLHttpRequest;
+    };
+  });
+
+  afterEach(function () {
+    restore();
+    delete global.localStorage;
+    if (origIndexedDb === undefined) {
+      delete global.indexedDB;
+    } else {
+      global.indexedDB = origIndexedDb;
+    }
+    if (origFetch) {
+      global.fetch = origFetch;
+    }
+    provider.clearCache();
+    setDependency('BinaryReader', origBR);
+    setDependency('LogHandler', origLog);
+  });
+
+  it('skips indexedDB entries with mismatched types or missing payloads', async function () {
+    const idb = createIndexedDb();
+    global.indexedDB = idb;
+    provider = new FileProvider(rootPath);
+    await provider._openIndexedDb();
+    const entries = idb._stores.get('entries');
+    const payloads = idb._stores.get('payloads');
+    const url = rootPath + 'cached.bin';
+    entries.set(url, { url, type: 'text', size: 1, lastAccess: 1 });
+    payloads.set(url, { url, data: new ArrayBuffer(1) });
+
+    const mismatch = await provider._loadFromIndexedDb(url, 'binary', 'data');
+    assert.strictEqual(mismatch, null);
+
+    entries.set(url, { url, type: 'binary', size: 1, lastAccess: 1 });
+    payloads.delete(url);
+    const missing = await provider._loadFromIndexedDb(url, 'binary', 'data');
+    assert.strictEqual(missing, null);
+  });
+
+  it('loads text payloads from indexedDB', async function () {
+    const idb = createIndexedDb();
+    global.indexedDB = idb;
+    provider = new FileProvider(rootPath);
+    await provider._openIndexedDb();
+    const entries = idb._stores.get('entries');
+    const payloads = idb._stores.get('payloads');
+    const url = makeUrl('cached.txt');
+    entries.set(url, { url, type: 'text', size: 4, lastAccess: 1 });
+    payloads.set(url, { url, data: 'ok' });
+
+    const result = await provider._loadFromIndexedDb(url, 'text');
+    assert.strictEqual(result.value, 'ok');
+  });
+
+  it('estimates entry sizes for buffers, views, and strings', function () {
+    const buf = new ArrayBuffer(4);
+    assert.strictEqual(provider._estimateEntrySize({ type: 'binary', data: buf }), 4);
+    assert.strictEqual(provider._estimateEntrySize({
+      type: 'binary',
+      data: new Uint8Array([1, 2])
+    }), 2);
+    assert.ok(provider._estimateEntrySize({ type: 'text', data: 'abc' }) >= 3);
+    assert.strictEqual(provider._estimateEntrySize(null), 0);
+  });
+
+  it('handles localStorage fallbacks and evictions', function () {
+    delete global.localStorage;
+    assert.deepStrictEqual(provider._getLocalStorageEntries(), []);
+    assert.strictEqual(provider._storeInLocalStorage('url', { type: 'text', data: 'x' }), false);
+
+    const store = new Map([
+      ['lem-cache:' + rootPath + 'a', JSON.stringify({ lastAccess: 1, size: 20 })],
+      ['lem-cache:' + rootPath + 'b', JSON.stringify({ lastAccess: 2, size: 20 })]
+    ]);
+    const removed = [];
+    global.localStorage = {
+      length: store.size,
+      key(i) { return Array.from(store.keys())[i] ?? null; },
+      getItem(key) { return store.get(key) ?? null; },
+      removeItem(key) { removed.push(key); store.delete(key); },
+      setItem(key, value) { store.set(key, value); }
+    };
+    provider._evictLocalStorage(4 * 1024 * 1024);
+    assert.strictEqual(removed.length, 2);
+  });
+
+  it('stops evicting localStorage once under target', function () {
+    const store = new Map([
+      ['lem-cache:' + rootPath + 'a', JSON.stringify({ lastAccess: 1, size: 200 })],
+      ['lem-cache:' + rootPath + 'b', JSON.stringify({ lastAccess: 2, size: 5 })]
+    ]);
+    let removed = 0;
+    global.localStorage = {
+      length: store.size,
+      key(i) { return Array.from(store.keys())[i] ?? null; },
+      getItem(key) { return store.get(key) ?? null; },
+      removeItem(key) { removed += 1; store.delete(key); },
+      setItem(key, value) { store.set(key, value); }
+    };
+    provider._evictLocalStorage(4 * 1024 * 1024 - 1);
+    assert.strictEqual(removed, 1);
+  });
+
+  it('returns null when localStorage entries are wrong type', function () {
+    const url = rootPath + 'wrong.bin';
+    setTextCache(url, 'ok');
+    const result = provider._loadFromLocalStorage(url, 'binary', 'data');
+    assert.strictEqual(result, null);
+  });
+
+  it('honors explicit localStorage injection boundaries', function () {
+    const isolated = new FileProvider(rootPath, { localStorage: null });
+    global.localStorage.setItem(cacheKey(makeUrl('isolated.txt')), 'x');
+    assert.deepStrictEqual(isolated._getLocalStorageEntries(), []);
+    assert.strictEqual(isolated._loadFromLocalStorage(makeUrl('isolated.txt'), 'text'), null);
+  });
+
+  it('uses indexedDB cache when available', async function () {
+    const idb = createIndexedDb();
+    global.indexedDB = idb;
+    provider = new FileProvider(rootPath);
+    const url = provider._buildUrl('data', 'cached.bin');
+    const buffer = new ArrayBuffer(4);
+    await provider._storeInIndexedDb(url, { type: 'binary', data: buffer, hash: 'h' });
+
+    const result = await provider.loadBinary('data', 'cached.bin');
+    assert.ok(result instanceof MockBinaryReader);
+    assert.strictEqual(requests.length, 0);
+  });
+
+  it('disables indexedDB on open errors', async function () {
+    global.indexedDB = createIndexedDb({ failOpen: true });
+    provider = new FileProvider(rootPath);
+    const db = await provider._openIndexedDb();
+    assert.strictEqual(db, null);
+    assert.strictEqual(provider._idbDisabled, true);
+  });
+
+  it('enumerates localStorage entries using key/length', function () {
+    const store = new Map([
+      ['lem-cache:' + rootPath + 'a.txt', 'a'],
+      ['other', 'skip']
+    ]);
+    global.localStorage = {
+      length: store.size,
+      key(i) { return Array.from(store.keys())[i] ?? null; },
+      getItem(key) { return store.get(key) ?? null; },
+      removeItem(key) { store.delete(key); },
+      setItem(key, value) { store.set(key, value); }
+    };
+    const entries = provider._getLocalStorageEntries();
+    assert.strictEqual(entries.length, 1);
+    assert.strictEqual(entries[0].key, 'lem-cache:' + rootPath + 'a.txt');
+  });
+
+  it('prunes indexedDB entries when over the limit', async function () {
+    const idb = createIndexedDb();
+    global.indexedDB = idb;
+    provider = new FileProvider(rootPath);
+    await provider._openIndexedDb();
+    const entries = idb._stores.get('entries');
+    const payloads = idb._stores.get('payloads');
+    const meta = idb._stores.get('meta');
+    const urlA = rootPath + 'a.bin';
+    const urlB = rootPath + 'b.bin';
+    entries.set(urlA, { url: urlA, size: 30 * 1024 * 1024, lastAccess: 1 });
+    entries.set(urlB, { url: urlB, size: 30 * 1024 * 1024, lastAccess: 2 });
+    payloads.set(urlA, { url: urlA, data: new ArrayBuffer(1) });
+    payloads.set(urlB, { url: urlB, data: new ArrayBuffer(1) });
+    meta.set('totalBytes', { key: 'totalBytes', value: 60 * 1024 * 1024 });
+
+    await provider._pruneIndexedDb(60 * 1024 * 1024);
+    await new Promise(resolve => setTimeout(resolve, 10));
+
+    assert.ok(entries.size < 2);
+    const metaEntry = meta.get('totalBytes');
+    assert.ok(metaEntry.value <= 60 * 1024 * 1024);
+  });
+});
diff --git a/test/fileprovider.05-fileprovider.test.js b/test/fileprovider.05-fileprovider.test.js
new file mode 100644
index 00000000..cf86cdc0
--- /dev/null
+++ b/test/fileprovider.05-fileprovider.test.js
@@ -0,0 +1,417 @@
+import assert from 'assert';
+import { FileProvider } from '../js/data/FileProvider.js';
+import { Lemmings, setDependency } from './helpers/lemmings.js';
+
+class MockBinaryReader {}
+class MockLogHandler {
+  constructor() {
+    this.logged = [];
+    this.debugged = [];
+  }
+  log(msg) {
+    this.logged.push(msg);
+  }
+  debug(msg) {
+    this.debugged.push(msg);
+  }
+}
+let origBR;
+let origLog;
+let origIndexedDb;
+
+const createIndexedDb = ({ failOpen = false } = {}) => {
+  const stores = new Map();
+  const keyPaths = new Map();
+  const indexes = new Map();
+  const objectStoreNames = {
+    contains(name) {
+      return stores.has(name);
+    }
+  };
+
+  const makeRequest = (result, error = null) => {
+    const request = { result: undefined, error };
+    setTimeout(() => {
+      if (error) {
+        request.onerror?.();
+      } else {
+        request.result = result;
+        request.onsuccess?.();
+      }
+    }, 0);
+    return request;
+  };
+
+  const makeCursorRequest = (map, field) => {
+    const entries = Array.from(map.values())
+      .slice()
+      .sort((a, b) => (a?.[field] ?? 0) - (b?.[field] ?? 0));
+    let idx = 0;
+    const request = {};
+    const cursor = {
+      get value() {
+        return entries[idx];
+      },
+      continue() {
+        idx += 1;
+        trigger();
+      }
+    };
+    const trigger = () => {
+      setTimeout(() => {
+        request.result = idx < entries.length ? cursor : null;
+        request.onsuccess?.();
+      }, 0);
+    };
+    trigger();
+    return request;
+  };
+
+  const ensureStore = (name, keyPath = 'id') => {
+    if (!stores.has(name)) stores.set(name, new Map());
+    if (!keyPaths.has(name)) keyPaths.set(name, keyPath);
+    if (!indexes.has(name)) indexes.set(name, new Map());
+  };
+
+  const createStore = (name) => {
+    ensureStore(name);
+    const map = stores.get(name);
+    const keyPath = keyPaths.get(name);
+    const indexMap = indexes.get(name);
+    return {
+      get(key) {
+        return makeRequest(map.get(key));
+      },
+      put(value) {
+        const key = keyPath ? value?.[keyPath] : value?.key;
+        map.set(key, value);
+        return makeRequest(value);
+      },
+      delete(key) {
+        map.delete(key);
+        return makeRequest(undefined);
+      },
+      createIndex(indexName, field) {
+        indexMap.set(indexName, { field });
+        return {};
+      },
+      index(indexName) {
+        const idx = indexMap.get(indexName);
+        return {
+          openCursor() {
+            return makeCursorRequest(map, idx?.field);
+          }
+        };
+      }
+    };
+  };
+
+  const db = {
+    objectStoreNames,
+    createObjectStore(name, options = {}) {
+      ensureStore(name, options.keyPath);
+      return createStore(name);
+    },
+    transaction(storeNames) {
+      const names = Array.isArray(storeNames) ? storeNames : [storeNames];
+      names.forEach((name) => ensureStore(name));
+      return {
+        objectStore(name) {
+          return createStore(name);
+        }
+      };
+    },
+    close() {}
+  };
+
+  return {
+    open() {
+      const request = {};
+      setTimeout(() => {
+        if (failOpen) {
+          request.error = new Error('indexeddb open failed');
+          request.onerror?.();
+          return;
+        }
+        request.result = db;
+        request.onupgradeneeded?.();
+        request.onsuccess?.();
+      }, 0);
+      return request;
+    },
+    _stores: stores
+  };
+};
+
+describe('FileProvider', function () {
+  const rootPath = '/base/';
+
+  let provider;
+
+  let requests;
+
+  let restore;
+
+  let origFetch;
+
+  const makeUrl = (name) => rootPath + name;
+
+  const cacheKey = (url) => `lem-cache:${url}`;
+
+  const setCacheEntry = (url, entry) => {
+    global.localStorage.setItem(cacheKey(url), JSON.stringify(entry));
+  };
+
+  const setCacheRaw = (url, raw) => {
+    global.localStorage.setItem(cacheKey(url), raw);
+  };
+
+  const setBinaryCache = (url, buffer, hash) => {
+    const entry = {
+      type: 'binary',
+      data: provider._arrayBufferToBase64(buffer),
+      ...(hash ? { hash } : {})
+    };
+    setCacheEntry(url, entry);
+  };
+
+  const setTextCache = (url, data) => {
+    setCacheEntry(url, { type: 'text', data });
+  };
+
+  const setupIndexedDb = ({
+    loadFromIndexedDb = async () => null,
+    loadFromLocalStorage
+  } = {}) => {
+    provider._canUseIndexedDb = () => true;
+    provider._loadFromIndexedDb = loadFromIndexedDb;
+    if (typeof loadFromLocalStorage === 'function') {
+      provider._loadFromLocalStorage = loadFromLocalStorage;
+    }
+  };
+
+  const makeFetchCounter = (impl) => {
+    let calls = 0;
+    const fn = async (...args) => {
+      calls += 1;
+      return impl(...args);
+    };
+    return { fn, get calls() { return calls; } };
+  };
+
+  beforeEach(function () {
+    origBR = Lemmings.BinaryReader;
+    origLog = Lemmings.LogHandler;
+    origIndexedDb = global.indexedDB;
+    setDependency('BinaryReader', MockBinaryReader);
+    setDependency('LogHandler', MockLogHandler);
+    provider = new FileProvider(rootPath);
+    global.localStorage = new (class {
+      constructor() { this.store = new Map(); }
+      getItem(k) { return this.store.has(k) ? this.store.get(k) : null; }
+      setItem(k, v) { this.store.set(k, v); }
+      removeItem(k) { this.store.delete(k); }
+      clear() { this.store.clear(); }
+    })();
+    origFetch = global.fetch;
+    delete global.fetch; // disable HEAD requests
+    requests = [];
+    class FakeXHR {
+      constructor() {
+        this.status = 0;
+        this.response = null;
+        FakeXHR.instances.push(this);
+      }
+      open(method, url) {
+        this.method = method;
+        this.url = url;
+      }
+      send() {}
+      respond(status, body) {
+        this.status = status;
+        this.response = body;
+        if (status >= 200 && status < 300) {
+          if (this.onload) this.onload();
+        } else {
+          if (this.onerror) this.onerror();
+        }
+      }
+    }
+    FakeXHR.instances = [];
+    requests = FakeXHR.instances;
+    global.XMLHttpRequest = FakeXHR;
+    restore = () => {
+      delete global.XMLHttpRequest;
+    };
+  });
+
+  afterEach(function () {
+    restore();
+    delete global.localStorage;
+    if (origIndexedDb === undefined) {
+      delete global.indexedDB;
+    } else {
+      global.indexedDB = origIndexedDb;
+    }
+    if (origFetch) {
+      global.fetch = origFetch;
+    }
+    provider.clearCache();
+    setDependency('BinaryReader', origBR);
+    setDependency('LogHandler', origLog);
+  });
+
+  it('prunes indexedDB entries with missing size metadata', async function () {
+    const idb = createIndexedDb();
+    global.indexedDB = idb;
+    provider = new FileProvider(rootPath);
+    await provider._openIndexedDb();
+    const entries = idb._stores.get('entries');
+    const payloads = idb._stores.get('payloads');
+    const meta = idb._stores.get('meta');
+    const url = rootPath + 'nosize.bin';
+    entries.set(url, { url, lastAccess: 1 });
+    payloads.set(url, { url, data: new ArrayBuffer(1) });
+    meta.set('totalBytes', { key: 'totalBytes', value: 60 * 1024 * 1024 });
+
+    await provider._pruneIndexedDb(60 * 1024 * 1024);
+    await new Promise(resolve => setTimeout(resolve, 10));
+    assert.ok(entries.size < 1);
+  });
+
+  it('_storeInLocalStorage ignores write errors', function () {
+    global.localStorage.setItem = () => { throw new Error('nope'); };
+    const result = provider._storeInLocalStorage('url', { a: 1 });
+    assert.strictEqual(result, false);
+  });
+
+  it('falls back to localStorage when indexedDB misses', async function () {
+    const idb = createIndexedDb();
+    global.indexedDB = idb;
+    provider = new FileProvider(rootPath);
+
+    const binUrl = provider._buildUrl('data', 'fallback.bin');
+    const buf = Uint8Array.from([1]).buffer;
+    setBinaryCache(binUrl, buf);
+
+    const bin = await provider.loadBinary('data', 'fallback.bin');
+    assert.ok(bin instanceof MockBinaryReader);
+    assert.strictEqual(requests.length, 0);
+
+    const textUrl = makeUrl('fallback.txt');
+    setTextCache(textUrl, 'hello');
+    const text = await provider.loadString(textUrl);
+    assert.strictEqual(text, 'hello');
+  });
+
+  it('handles indexedDB failures in load and touch paths', async function () {
+    provider._openIndexedDb = async () => null;
+    const missing = await provider._loadFromIndexedDb('url', 'text');
+    assert.strictEqual(missing, null);
+    await provider._touchIndexedDbEntry('url', { url: 'url' });
+
+    provider._openIndexedDb = async () => ({ transaction() { throw new Error('fail'); } });
+    const failed = await provider._loadFromIndexedDb('url', 'text');
+    assert.strictEqual(failed, null);
+    await provider._touchIndexedDbEntry('url', { url: 'url' });
+  });
+
+  it('_idbRequest rejects when a request fails', async function () {
+    const request = { error: new Error('fail') };
+    const promise = provider._idbRequest(request);
+    request.onerror();
+    await assert.rejects(promise, /fail/);
+  });
+
+  it('closes indexedDB on version changes', async function () {
+    const closeCalls = [];
+    global.indexedDB = {
+      open() {
+        const request = {};
+        setTimeout(() => {
+          request.result = {
+            objectStoreNames: { contains() { return true; } },
+            close() { closeCalls.push(true); }
+          };
+          request.onsuccess?.();
+        }, 0);
+        return request;
+      }
+    };
+    provider = new FileProvider(rootPath);
+    const db = await provider._openIndexedDb();
+    db.onversionchange();
+    assert.strictEqual(closeCalls.length, 1);
+  });
+
+  it('closes an open indexedDB handle on close()', async function () {
+    let closeCalls = 0;
+    provider._idb = {
+      close() {
+        closeCalls += 1;
+      }
+    };
+    provider._idbPromise = Promise.resolve(provider._idb);
+    await provider.close();
+    assert.strictEqual(closeCalls, 1);
+    assert.strictEqual(provider._idb, null);
+    assert.strictEqual(provider._idbPromise, null);
+  });
+
+  it('updates indexedDB sizes when entries already exist', async function () {
+    const idb = createIndexedDb();
+    global.indexedDB = idb;
+    provider = new FileProvider(rootPath);
+    await provider._openIndexedDb();
+    const entries = idb._stores.get('entries');
+    const meta = idb._stores.get('meta');
+    const url = rootPath + 'cached.bin';
+    entries.set(url, { url, type: 'binary', size: 10, lastAccess: 1 });
+    meta.set('totalBytes', { key: 'totalBytes', value: 10 });
+
+    const stored = await provider._storeInIndexedDb(url, { type: 'binary', data: new ArrayBuffer(2) });
+    assert.strictEqual(stored, true);
+    const updated = meta.get('totalBytes');
+    assert.strictEqual(updated.value, 2);
+  });
+
+  it('returns false when indexedDB storage fails', async function () {
+    provider._openIndexedDb = async () => ({ transaction() { throw new Error('fail'); } });
+    const stored = await provider._storeInIndexedDb('url', { type: 'text', data: 'x' });
+    assert.strictEqual(stored, false);
+  });
+
+  it('falls back to localStorage when an indexedDB transaction aborts', async function () {
+    const request = (result) => {
+      const req = {};
+      setTimeout(() => {
+        req.result = result;
+        req.onsuccess?.();
+      }, 0);
+      return req;
+    };
+    provider._openIndexedDb = async () => ({
+      transaction() {
+        const tx = {
+          error: new Error('abort'),
+          oncomplete: null,
+          onabort: null,
+          onerror: null,
+          objectStore() {
+            return {
+              get() { return request(null); },
+              put() {}
+            };
+          }
+        };
+        setTimeout(() => tx.onabort?.(), 5);
+        return tx;
+      }
+    });
+
+    const url = makeUrl('idb-abort.txt');
+    await provider._storeInCache(url, { type: 'text', data: 'ok' });
+    const entry = JSON.parse(global.localStorage.getItem(cacheKey(url)));
+    assert.strictEqual(entry.data, 'ok');
+  });
+});
diff --git a/test/fileprovider.06-fileprovider.test.js b/test/fileprovider.06-fileprovider.test.js
new file mode 100644
index 00000000..55da7af7
--- /dev/null
+++ b/test/fileprovider.06-fileprovider.test.js
@@ -0,0 +1,426 @@
+import assert from 'assert';
+import { FileProvider } from '../js/data/FileProvider.js';
+import { Lemmings, setDependency } from './helpers/lemmings.js';
+
+class MockBinaryReader {}
+class MockLogHandler {
+  constructor() {
+    this.logged = [];
+    this.debugged = [];
+  }
+  log(msg) {
+    this.logged.push(msg);
+  }
+  debug(msg) {
+    this.debugged.push(msg);
+  }
+}
+let origBR;
+let origLog;
+let origIndexedDb;
+
+const createIndexedDb = ({ failOpen = false } = {}) => {
+  const stores = new Map();
+  const keyPaths = new Map();
+  const indexes = new Map();
+  const objectStoreNames = {
+    contains(name) {
+      return stores.has(name);
+    }
+  };
+
+  const makeRequest = (result, error = null) => {
+    const request = { result: undefined, error };
+    setTimeout(() => {
+      if (error) {
+        request.onerror?.();
+      } else {
+        request.result = result;
+        request.onsuccess?.();
+      }
+    }, 0);
+    return request;
+  };
+
+  const makeCursorRequest = (map, field) => {
+    const entries = Array.from(map.values())
+      .slice()
+      .sort((a, b) => (a?.[field] ?? 0) - (b?.[field] ?? 0));
+    let idx = 0;
+    const request = {};
+    const cursor = {
+      get value() {
+        return entries[idx];
+      },
+      continue() {
+        idx += 1;
+        trigger();
+      }
+    };
+    const trigger = () => {
+      setTimeout(() => {
+        request.result = idx < entries.length ? cursor : null;
+        request.onsuccess?.();
+      }, 0);
+    };
+    trigger();
+    return request;
+  };
+
+  const ensureStore = (name, keyPath = 'id') => {
+    if (!stores.has(name)) stores.set(name, new Map());
+    if (!keyPaths.has(name)) keyPaths.set(name, keyPath);
+    if (!indexes.has(name)) indexes.set(name, new Map());
+  };
+
+  const createStore = (name) => {
+    ensureStore(name);
+    const map = stores.get(name);
+    const keyPath = keyPaths.get(name);
+    const indexMap = indexes.get(name);
+    return {
+      get(key) {
+        return makeRequest(map.get(key));
+      },
+      put(value) {
+        const key = keyPath ? value?.[keyPath] : value?.key;
+        map.set(key, value);
+        return makeRequest(value);
+      },
+      delete(key) {
+        map.delete(key);
+        return makeRequest(undefined);
+      },
+      createIndex(indexName, field) {
+        indexMap.set(indexName, { field });
+        return {};
+      },
+      index(indexName) {
+        const idx = indexMap.get(indexName);
+        return {
+          openCursor() {
+            return makeCursorRequest(map, idx?.field);
+          }
+        };
+      }
+    };
+  };
+
+  const db = {
+    objectStoreNames,
+    createObjectStore(name, options = {}) {
+      ensureStore(name, options.keyPath);
+      return createStore(name);
+    },
+    transaction(storeNames) {
+      const names = Array.isArray(storeNames) ? storeNames : [storeNames];
+      names.forEach((name) => ensureStore(name));
+      return {
+        objectStore(name) {
+          return createStore(name);
+        }
+      };
+    },
+    close() {}
+  };
+
+  return {
+    open() {
+      const request = {};
+      setTimeout(() => {
+        if (failOpen) {
+          request.error = new Error('indexeddb open failed');
+          request.onerror?.();
+          return;
+        }
+        request.result = db;
+        request.onupgradeneeded?.();
+        request.onsuccess?.();
+      }, 0);
+      return request;
+    },
+    _stores: stores
+  };
+};
+
+describe('FileProvider', function () {
+  const rootPath = '/base/';
+
+  let provider;
+
+  let requests;
+
+  let restore;
+
+  let origFetch;
+
+  const makeUrl = (name) => rootPath + name;
+
+  const cacheKey = (url) => `lem-cache:${url}`;
+
+  const setCacheEntry = (url, entry) => {
+    global.localStorage.setItem(cacheKey(url), JSON.stringify(entry));
+  };
+
+  const setCacheRaw = (url, raw) => {
+    global.localStorage.setItem(cacheKey(url), raw);
+  };
+
+  const setBinaryCache = (url, buffer, hash) => {
+    const entry = {
+      type: 'binary',
+      data: provider._arrayBufferToBase64(buffer),
+      ...(hash ? { hash } : {})
+    };
+    setCacheEntry(url, entry);
+  };
+
+  const setTextCache = (url, data) => {
+    setCacheEntry(url, { type: 'text', data });
+  };
+
+  const setupIndexedDb = ({
+    loadFromIndexedDb = async () => null,
+    loadFromLocalStorage
+  } = {}) => {
+    provider._canUseIndexedDb = () => true;
+    provider._loadFromIndexedDb = loadFromIndexedDb;
+    if (typeof loadFromLocalStorage === 'function') {
+      provider._loadFromLocalStorage = loadFromLocalStorage;
+    }
+  };
+
+  const makeFetchCounter = (impl) => {
+    let calls = 0;
+    const fn = async (...args) => {
+      calls += 1;
+      return impl(...args);
+    };
+    return { fn, get calls() { return calls; } };
+  };
+
+  beforeEach(function () {
+    origBR = Lemmings.BinaryReader;
+    origLog = Lemmings.LogHandler;
+    origIndexedDb = global.indexedDB;
+    setDependency('BinaryReader', MockBinaryReader);
+    setDependency('LogHandler', MockLogHandler);
+    provider = new FileProvider(rootPath);
+    global.localStorage = new (class {
+      constructor() { this.store = new Map(); }
+      getItem(k) { return this.store.has(k) ? this.store.get(k) : null; }
+      setItem(k, v) { this.store.set(k, v); }
+      removeItem(k) { this.store.delete(k); }
+      clear() { this.store.clear(); }
+    })();
+    origFetch = global.fetch;
+    delete global.fetch; // disable HEAD requests
+    requests = [];
+    class FakeXHR {
+      constructor() {
+        this.status = 0;
+        this.response = null;
+        FakeXHR.instances.push(this);
+      }
+      open(method, url) {
+        this.method = method;
+        this.url = url;
+      }
+      send() {}
+      respond(status, body) {
+        this.status = status;
+        this.response = body;
+        if (status >= 200 && status < 300) {
+          if (this.onload) this.onload();
+        } else {
+          if (this.onerror) this.onerror();
+        }
+      }
+    }
+    FakeXHR.instances = [];
+    requests = FakeXHR.instances;
+    global.XMLHttpRequest = FakeXHR;
+    restore = () => {
+      delete global.XMLHttpRequest;
+    };
+  });
+
+  afterEach(function () {
+    restore();
+    delete global.localStorage;
+    if (origIndexedDb === undefined) {
+      delete global.indexedDB;
+    } else {
+      global.indexedDB = origIndexedDb;
+    }
+    if (origFetch) {
+      global.fetch = origFetch;
+    }
+    provider.clearCache();
+    setDependency('BinaryReader', origBR);
+    setDependency('LogHandler', origLog);
+  });
+
+  it('reports indexedDB write success only after transaction commit', async function () {
+    const request = (result) => {
+      const req = {};
+      setTimeout(() => {
+        req.result = result;
+        req.onsuccess?.();
+      }, 0);
+      return req;
+    };
+    let completeTransaction = null;
+    provider._openIndexedDb = async () => ({
+      transaction() {
+        const tx = {
+          oncomplete: null,
+          onabort: null,
+          onerror: null,
+          objectStore() {
+            return {
+              get() { return request(null); },
+              put() {}
+            };
+          }
+        };
+        completeTransaction = () => tx.oncomplete?.();
+        return tx;
+      }
+    });
+
+    let settled = false;
+    const promise = provider
+      ._storeInIndexedDb('commit-url', { type: 'text', data: 'ok' })
+      .then((value) => {
+        settled = true;
+        return value;
+      });
+    await new Promise(resolve => setTimeout(resolve, 10));
+    assert.strictEqual(settled, false);
+
+    completeTransaction();
+    assert.strictEqual(await promise, true);
+    assert.ok(provider.getCacheStats().indexedDbBytes > 0);
+  });
+
+  it('triggers indexedDB pruning after oversized writes', async function () {
+    let pruneCalls = 0;
+    provider._estimateEntrySize = () => 60 * 1024 * 1024;
+    let idbCalls = 0;
+    provider._idbRequest = async () => {
+      idbCalls++;
+      if (idbCalls === 1) return null;
+      return { value: 0 };
+    };
+    provider._openIndexedDb = async () => ({
+      transaction() {
+        const tx = {
+          objectStore() {
+            return {
+              get() { return {}; },
+              put() {}
+            };
+          }
+        };
+        setTimeout(() => tx.oncomplete?.(), 0);
+        return tx;
+      }
+    });
+    provider._pruneIndexedDb = () => { pruneCalls++; };
+
+    const stored = await provider._storeInIndexedDb('url', { type: 'text', data: 'x' });
+    assert.strictEqual(stored, true);
+    await new Promise(resolve => setTimeout(resolve, 10));
+    assert.strictEqual(pruneCalls, 1);
+  });
+
+  it('prunes indexedDB only when over the limit', async function () {
+    provider._openIndexedDb = async () => null;
+    await provider._pruneIndexedDb(10);
+
+    const idb = createIndexedDb();
+    global.indexedDB = idb;
+    provider = new FileProvider(rootPath);
+    await provider._openIndexedDb();
+    await provider._pruneIndexedDb(1024);
+  });
+
+  it('swallows pruning errors when indexedDB transactions fail', async function () {
+    provider._openIndexedDb = async () => ({ transaction() { throw new Error('fail'); } });
+    await provider._pruneIndexedDb(60 * 1024 * 1024);
+  });
+
+  it('estimates sizes without TextEncoder and ignores unknown data', function () {
+    const orig = global.TextEncoder;
+    global.TextEncoder = undefined;
+    assert.strictEqual(provider._estimateTextSize('abcd'), 4);
+    assert.strictEqual(provider._estimateTextSize(''), 0);
+    global.TextEncoder = orig;
+
+    assert.strictEqual(provider._estimateEntrySize({ type: 'binary', data: 5 }), 0);
+  });
+
+  it('enumerates localStorage entries using store.forEach', function () {
+    const store = new Map([
+      ['lem-cache:' + rootPath + 'a.txt', 'a'],
+      ['other', 'skip']
+    ]);
+    global.localStorage = { store };
+    const entries = provider._getLocalStorageEntries();
+    assert.strictEqual(entries.length, 1);
+    assert.strictEqual(entries[0].key, 'lem-cache:' + rootPath + 'a.txt');
+  });
+
+  it('evicts localStorage safely with malformed entries', function () {
+    const store = new Map([
+      ['lem-cache:' + rootPath + 'bad', '{bad'],
+      ['lem-cache:' + rootPath + 'empty', null]
+    ]);
+    global.localStorage = {
+      length: store.size,
+      key(i) { return Array.from(store.keys())[i] ?? null; },
+      getItem(key) { return store.get(key) ?? null; },
+      removeItem(key) { store.delete(key); },
+      setItem(key, value) { store.set(key, value); }
+    };
+
+    const usage = provider._getLocalStorageUsage();
+    provider._evictLocalStorage();
+    assert.strictEqual(provider._cacheStats.localStorageBytes, usage);
+  });
+
+  it('handles missing localStorage in touch and load paths', function () {
+    delete global.localStorage;
+    assert.strictEqual(provider._loadFromLocalStorage('url', 'text'), null);
+    provider._touchLocalStorageEntry('url', null);
+  });
+
+  it('logs and returns false when localStorage serialization fails', function () {
+    const original = provider._serializeLocalStorageEntry;
+    provider._serializeLocalStorageEntry = () => { throw new Error('fail'); };
+    const result = provider._storeInLocalStorage('url', { type: 'text', data: 'x' });
+    provider._serializeLocalStorageEntry = original;
+    assert.strictEqual(result, false);
+    assert.ok(provider.log.logged.some(m => m.includes('cache write error')));
+  });
+
+  it('serializes localStorage entries with default access times', function () {
+    const serialized = provider._serializeLocalStorageEntry({ type: 'text', data: 'x' });
+    assert.ok(serialized.entry.lastAccess > 0);
+    assert.ok(serialized.entry.size > 0);
+  });
+
+  it('coalesces cache validation per URL', async function () {
+    let calls = 0;
+    provider._verifyCache = async () => {
+      calls += 1;
+    };
+
+    provider._scheduleCacheValidation('same-url', { type: 'text' });
+    provider._scheduleCacheValidation('same-url', { type: 'text' });
+    assert.strictEqual(calls, 1);
+    await Promise.all(Array.from(provider._validationPromises.values()));
+    assert.strictEqual(provider._validationPromises.size, 0);
+  });
+});
diff --git a/test/fileprovider.test.js b/test/fileprovider.test.js
deleted file mode 100644
index 2480bfb9..00000000
--- a/test/fileprovider.test.js
+++ /dev/null
@@ -1,1094 +0,0 @@
-import assert from 'assert';
-import { FileProvider } from '../js/data/FileProvider.js';
-import { Lemmings, setDependency } from './helpers/lemmings.js';
-
-class MockBinaryReader {}
-class MockLogHandler {
-  constructor() {
-    this.logged = [];
-    this.debugged = [];
-  }
-  log(msg) {
-    this.logged.push(msg);
-  }
-  debug(msg) {
-    this.debugged.push(msg);
-  }
-}
-let origBR;
-let origLog;
-let origIndexedDb;
-
-const createIndexedDb = ({ failOpen = false } = {}) => {
-  const stores = new Map();
-  const keyPaths = new Map();
-  const indexes = new Map();
-  const objectStoreNames = {
-    contains(name) {
-      return stores.has(name);
-    }
-  };
-
-  const makeRequest = (result, error = null) => {
-    const request = { result: undefined, error };
-    setTimeout(() => {
-      if (error) {
-        request.onerror?.();
-      } else {
-        request.result = result;
-        request.onsuccess?.();
-      }
-    }, 0);
-    return request;
-  };
-
-  const makeCursorRequest = (map, field) => {
-    const entries = Array.from(map.values())
-      .slice()
-      .sort((a, b) => (a?.[field] ?? 0) - (b?.[field] ?? 0));
-    let idx = 0;
-    const request = {};
-    const cursor = {
-      get value() {
-        return entries[idx];
-      },
-      continue() {
-        idx += 1;
-        trigger();
-      }
-    };
-    const trigger = () => {
-      setTimeout(() => {
-        request.result = idx < entries.length ? cursor : null;
-        request.onsuccess?.();
-      }, 0);
-    };
-    trigger();
-    return request;
-  };
-
-  const ensureStore = (name, keyPath = 'id') => {
-    if (!stores.has(name)) stores.set(name, new Map());
-    if (!keyPaths.has(name)) keyPaths.set(name, keyPath);
-    if (!indexes.has(name)) indexes.set(name, new Map());
-  };
-
-  const createStore = (name) => {
-    ensureStore(name);
-    const map = stores.get(name);
-    const keyPath = keyPaths.get(name);
-    const indexMap = indexes.get(name);
-    return {
-      get(key) {
-        return makeRequest(map.get(key));
-      },
-      put(value) {
-        const key = keyPath ? value?.[keyPath] : value?.key;
-        map.set(key, value);
-        return makeRequest(value);
-      },
-      delete(key) {
-        map.delete(key);
-        return makeRequest(undefined);
-      },
-      createIndex(indexName, field) {
-        indexMap.set(indexName, { field });
-        return {};
-      },
-      index(indexName) {
-        const idx = indexMap.get(indexName);
-        return {
-          openCursor() {
-            return makeCursorRequest(map, idx?.field);
-          }
-        };
-      }
-    };
-  };
-
-  const db = {
-    objectStoreNames,
-    createObjectStore(name, options = {}) {
-      ensureStore(name, options.keyPath);
-      return createStore(name);
-    },
-    transaction(storeNames) {
-      const names = Array.isArray(storeNames) ? storeNames : [storeNames];
-      names.forEach((name) => ensureStore(name));
-      return {
-        objectStore(name) {
-          return createStore(name);
-        }
-      };
-    },
-    close() {}
-  };
-
-  return {
-    open() {
-      const request = {};
-      setTimeout(() => {
-        if (failOpen) {
-          request.error = new Error('indexeddb open failed');
-          request.onerror?.();
-          return;
-        }
-        request.result = db;
-        request.onupgradeneeded?.();
-        request.onsuccess?.();
-      }, 0);
-      return request;
-    },
-    _stores: stores
-  };
-};
-
-describe('FileProvider', function () {
-  const rootPath = '/base/';
-  let provider;
-  let requests;
-  let restore;
-  let origFetch;
-  const makeUrl = (name) => rootPath + name;
-  const cacheKey = (url) => `lem-cache:${url}`;
-  const setCacheEntry = (url, entry) => {
-    global.localStorage.setItem(cacheKey(url), JSON.stringify(entry));
-  };
-  const setCacheRaw = (url, raw) => {
-    global.localStorage.setItem(cacheKey(url), raw);
-  };
-  const setBinaryCache = (url, buffer, hash) => {
-    const entry = {
-      type: 'binary',
-      data: provider._arrayBufferToBase64(buffer),
-      ...(hash ? { hash } : {})
-    };
-    setCacheEntry(url, entry);
-  };
-  const setTextCache = (url, data) => {
-    setCacheEntry(url, { type: 'text', data });
-  };
-  const setupIndexedDb = ({
-    loadFromIndexedDb = async () => null,
-    loadFromLocalStorage = () => null
-  } = {}) => {
-    provider._canUseIndexedDb = () => true;
-    provider._loadFromIndexedDb = loadFromIndexedDb;
-    provider._loadFromLocalStorage = loadFromLocalStorage;
-  };
-  const makeFetchCounter = (impl) => {
-    let calls = 0;
-    const fn = async (...args) => {
-      calls += 1;
-      return impl(...args);
-    };
-    return { fn, get calls() { return calls; } };
-  };
-
-  beforeEach(function () {
-    origBR = Lemmings.BinaryReader;
-    origLog = Lemmings.LogHandler;
-    origIndexedDb = global.indexedDB;
-    setDependency('BinaryReader', MockBinaryReader);
-    setDependency('LogHandler', MockLogHandler);
-    provider = new FileProvider(rootPath);
-    global.localStorage = new (class {
-      constructor() { this.store = new Map(); }
-      getItem(k) { return this.store.has(k) ? this.store.get(k) : null; }
-      setItem(k, v) { this.store.set(k, v); }
-      removeItem(k) { this.store.delete(k); }
-      clear() { this.store.clear(); }
-    })();
-    origFetch = global.fetch;
-    delete global.fetch; // disable HEAD requests
-    requests = [];
-    class FakeXHR {
-      constructor() {
-        this.status = 0;
-        this.response = null;
-        FakeXHR.instances.push(this);
-      }
-      open(method, url) {
-        this.method = method;
-        this.url = url;
-      }
-      send() {}
-      respond(status, body) {
-        this.status = status;
-        this.response = body;
-        if (status >= 200 && status < 300) {
-          if (this.onload) this.onload();
-        } else {
-          if (this.onerror) this.onerror();
-        }
-      }
-    }
-    FakeXHR.instances = [];
-    requests = FakeXHR.instances;
-    global.XMLHttpRequest = FakeXHR;
-    restore = () => {
-      delete global.XMLHttpRequest;
-    };
-  });
-
-  afterEach(function () {
-    restore();
-    delete global.localStorage;
-    if (origIndexedDb === undefined) {
-      delete global.indexedDB;
-    } else {
-      global.indexedDB = origIndexedDb;
-    }
-    if (origFetch) {
-      global.fetch = origFetch;
-    }
-    provider.clearCache();
-    setDependency('BinaryReader', origBR);
-    setDependency('LogHandler', origLog);
-  });
-
-  it('_buildUrl() joins rootPath, path and filename', function () {
-    const url = provider._buildUrl('path', 'file.bin');
-    assert.strictEqual(url, rootPath + 'path' + '/' + 'file.bin');
-    const noFile = provider._buildUrl('path', null);
-    assert.strictEqual(noFile, rootPath + 'path');
-  });
-
-  it('_filenameFromUrl strips query and handles empty', function () {
-    const name = provider._filenameFromUrl('http://x/y/file.bin?x=1#hash');
-    assert.strictEqual(name, 'file.bin');
-    assert.strictEqual(provider._filenameFromUrl(''), '');
-  });
-
-  it('loadBinary caches identical requests', async function () {
-    const p1 = provider.loadBinary('data', 'file.bin');
-    const p2 = provider.loadBinary('data', 'file.bin');
-    assert.strictEqual(p1, p2);
-    assert.strictEqual(requests.length, 1);
-
-    const buffer = new ArrayBuffer(0);
-    requests[0].respond(200, buffer);
-    const result = await p1;
-    assert.ok(result instanceof MockBinaryReader);
-
-    const p3 = provider.loadBinary('data', 'file.bin');
-    assert.strictEqual(p1, p3);
-    assert.strictEqual(requests.length, 1);
-  });
-
-  it('loadString caches identical requests', async function () {
-    const url = makeUrl('text.txt');
-    const p1 = provider.loadString(url);
-    const p2 = provider.loadString(url);
-    assert.strictEqual(p1, p2);
-    assert.strictEqual(requests.length, 1);
-
-    requests[0].respond(200, 'hello');
-    const result = await p1;
-    assert.strictEqual(result, 'hello');
-
-    const p3 = provider.loadString(url);
-    assert.strictEqual(p1, p3);
-    assert.strictEqual(requests.length, 1);
-  });
-
-  it('loadString clears cache on failure', async function () {
-    const url = makeUrl('fail.txt');
-    const promise = provider.loadString(url);
-    assert.strictEqual(provider._cache.size, 1);
-    requests[0].respond(500, 'err');
-    await assert.rejects(promise);
-    assert.strictEqual(provider._cache.has(url), false);
-  });
-
-  it('clearCache() empties the internal cache', async function () {
-    const url = makeUrl('file.txt');
-    const p1 = provider.loadString(url);
-    requests[0].respond(200, 'ok');
-    await p1;
-    assert.strictEqual(provider._cache.size, 1);
-    provider.clearCache();
-    assert.strictEqual(provider._cache.size, 0);
-  });
-
-  it('getCacheStats reports cache counters', function () {
-    provider._cache.set('a', Promise.resolve('x'));
-    provider._cacheStats.localStorageBytes = 12;
-    provider._cacheStats.indexedDbBytes = 34;
-    assert.deepStrictEqual(provider.getCacheStats(), {
-      memoryEntries: 1,
-      localStorageBytes: 12,
-      indexedDbBytes: 34
-    });
-  });
-
-  it('stores data in localStorage and reuses it', async function () {
-    const url = makeUrl('text.txt');
-    const p1 = provider.loadString(url);
-    requests[0].respond(200, 'hello');
-    const result1 = await p1;
-    assert.strictEqual(result1, 'hello');
-    const stored = global.localStorage.getItem(cacheKey(url));
-    assert.ok(stored, 'entry stored');
-
-    // new provider simulating page reload
-    provider = new FileProvider(rootPath);
-    const p2 = provider.loadString(url);
-    assert.strictEqual(requests.length, 1, 'no new XHR');
-    const result2 = await p2;
-    assert.strictEqual(result2, 'hello');
-  });
-
-  it('loadBinary uses cached binary entries from localStorage', async function () {
-    provider = new FileProvider(rootPath);
-    const data = Uint8Array.from([1, 2, 3]).buffer;
-    const url = makeUrl('data/file.bin');
-    setBinaryCache(url, data, 'h');
-
-    const result = await provider.loadBinary('data', 'file.bin');
-    assert.ok(result instanceof MockBinaryReader);
-    assert.strictEqual(requests.length, 0);
-  });
-
-  it('falls back to fetching when cached JSON is invalid', async function () {
-    const url = makeUrl('bad.txt');
-    setCacheRaw(url, '{bad');
-    const promise = provider.loadString(url);
-    requests[0].respond(200, 'ok');
-    const result = await promise;
-    assert.strictEqual(result, 'ok');
-  });
-
-  it('logs an error when binary load fails', async function () {
-    const p = provider.loadBinary('data', 'file.bin');
-    requests[0].respond(404, null);
-    await assert.rejects(p);
-    assert.ok(provider.log.logged.some(m => m.includes('error load file')));
-  });
-
-  it('loadBinary bypasses cache when forceReload is true', async function () {
-    let calls = 0;
-    provider._fetchBinary = async () => {
-      calls++;
-      return new MockBinaryReader();
-    };
-    const url = provider._buildUrl('data', 'file.bin');
-
-    const p1 = provider.loadBinary('data', 'file.bin');
-    assert.strictEqual(calls, 1);
-    await p1;
-
-    const p2 = provider.loadBinary('data', 'file.bin');
-    assert.strictEqual(p2, p1);
-    assert.strictEqual(calls, 1);
-    await p2;
-
-    const p3 = provider.loadBinary('data', 'file.bin', { forceReload: true });
-    assert.notStrictEqual(p3, p1);
-    assert.strictEqual(calls, 2);
-    await p3;
-
-    assert.strictEqual(provider._cache.get(url), p1);
-  });
-
-  it('loadBinary uses indexedDB path when enabled and uncached', async function () {
-    setupIndexedDb();
-    const fetchBinary = makeFetchCounter(async () => new MockBinaryReader());
-    provider._fetchBinary = fetchBinary.fn;
-
-    const result = await provider.loadBinary('data', 'missing.bin');
-    assert.ok(result instanceof MockBinaryReader);
-    assert.strictEqual(fetchBinary.calls, 1);
-  });
-
-  it('loadBinary falls back when indexedDB rejects', async function () {
-    setupIndexedDb({ loadFromIndexedDb: async () => { throw new Error('fail'); } });
-    const fetchBinary = makeFetchCounter(async () => new MockBinaryReader());
-    provider._fetchBinary = fetchBinary.fn;
-
-    const result = await provider.loadBinary('data', 'missing.bin');
-    assert.ok(result instanceof MockBinaryReader);
-    assert.strictEqual(fetchBinary.calls, 1);
-  });
-
-  it('loadBinary uses localStorage fallback after indexedDB error', async function () {
-    setupIndexedDb({
-      loadFromIndexedDb: async () => { throw new Error('fail'); },
-      loadFromLocalStorage: () => ({ value: new MockBinaryReader() })
-    });
-    provider._fetchBinary = async () => { throw new Error('should not fetch'); };
-
-    const result = await provider.loadBinary('data', 'missing.bin');
-    assert.ok(result instanceof MockBinaryReader);
-  });
-
-  it('loadBinary reads localStorage when indexedDB rejects', async function () {
-    setupIndexedDb({ loadFromIndexedDb: async () => { throw new Error('fail'); } });
-    const url = provider._buildUrl('data', 'cached.bin');
-    const buf = Uint8Array.from([1, 2, 3]).buffer;
-    setBinaryCache(url, buf);
-    provider._fetchBinary = async () => { throw new Error('should not fetch'); };
-
-    const result = await provider.loadBinary('data', 'cached.bin');
-    assert.ok(result instanceof MockBinaryReader);
-  });
-
-  it('loadString uses indexedDB path when enabled and uncached', async function () {
-    setupIndexedDb();
-    const fetchText = makeFetchCounter(async () => 'ok');
-    provider._fetchText = fetchText.fn;
-
-    const result = await provider.loadString(makeUrl('missing.txt'));
-    assert.strictEqual(result, 'ok');
-    assert.strictEqual(fetchText.calls, 1);
-  });
-
-  it('loadString falls back when indexedDB rejects', async function () {
-    setupIndexedDb({ loadFromIndexedDb: async () => { throw new Error('fail'); } });
-    const fetchText = makeFetchCounter(async () => 'ok');
-    provider._fetchText = fetchText.fn;
-
-    const result = await provider.loadString(makeUrl('missing.txt'));
-    assert.strictEqual(result, 'ok');
-    assert.strictEqual(fetchText.calls, 1);
-  });
-
-  it('loadString uses cached indexedDB value', async function () {
-    setupIndexedDb({ loadFromIndexedDb: async () => ({ value: 'cached' }) });
-    provider._fetchText = async () => { throw new Error('should not fetch'); };
-    const result = await provider.loadString(makeUrl('cached.txt'));
-    assert.strictEqual(result, 'cached');
-  });
-
-  it('loadString uses localStorage fallback after indexedDB error', async function () {
-    setupIndexedDb({
-      loadFromIndexedDb: async () => { throw new Error('fail'); },
-      loadFromLocalStorage: () => ({ value: 'cached' })
-    });
-    provider._fetchText = async () => { throw new Error('should not fetch'); };
-    const result = await provider.loadString(makeUrl('cached.txt'));
-    assert.strictEqual(result, 'cached');
-  });
-
-  it('loadString uses localStorage after indexedDB rejection', async function () {
-    setupIndexedDb({ loadFromIndexedDb: async () => { throw new Error('fail'); } });
-    const url = makeUrl('cached.txt');
-    setTextCache(url, 'stored');
-    provider._fetchText = async () => { throw new Error('should not fetch'); };
-    const result = await provider.loadString(url);
-    assert.strictEqual(result, 'stored');
-  });
-
-  it('refreshes cached text entries when headers change', async function () {
-    let textFetched = 0;
-    provider._fetchHead = async () => ({ etag: 'new' });
-    provider._fetchText = async () => { textFetched++; };
-    await provider._verifyCache('file.txt', { type: 'text', etag: 'old' });
-    assert.strictEqual(textFetched, 1);
-  });
-
-  it('stores response headers when available for text and binary', async function () {
-    class HeaderXHR {
-      constructor() {
-        this.status = 0;
-        this.response = null;
-        HeaderXHR.instances.push(this);
-      }
-      open(method, url) { this.method = method; this.url = url; }
-      send() {}
-      getResponseHeader(name) {
-        if (name === 'ETag') return 'etag-value';
-        if (name === 'Last-Modified') return 'modified';
-        return null;
-      }
-      respond(status, body) {
-        this.status = status;
-        this.response = body;
-        if (status >= 200 && status < 300) {
-          if (this.onload) this.onload();
-        } else if (this.onerror) {
-          this.onerror();
-        }
-      }
-    }
-    HeaderXHR.instances = [];
-    global.XMLHttpRequest = HeaderXHR;
-
-    const textUrl = makeUrl('headers.txt');
-    const textPromise = provider.loadString(textUrl);
-    HeaderXHR.instances[0].respond(200, 'ok');
-    await textPromise;
-    const textEntry = JSON.parse(global.localStorage.getItem(cacheKey(textUrl)));
-    assert.strictEqual(textEntry.etag, 'etag-value');
-
-    const binPromise = provider.loadBinary('data', 'file.bin');
-    const buffer = new ArrayBuffer(0);
-    HeaderXHR.instances[1].respond(200, buffer);
-    await binPromise;
-    const binUrl = provider._buildUrl('data', 'file.bin');
-    const binEntry = JSON.parse(global.localStorage.getItem(cacheKey(binUrl)));
-    assert.strictEqual(binEntry.lastModified, 'modified');
-  });
-
-  it('falls back to node crypto hashing and reports failures', async function () {
-    const origDescriptor = Object.getOwnPropertyDescriptor(globalThis, 'crypto');
-    try {
-      Object.defineProperty(globalThis, 'crypto', { value: undefined, configurable: true });
-      const hash = await provider._hashBuffer(new Uint8Array([1, 2, 3]).buffer);
-      assert.match(hash, /^[a-f0-9]{64}$/);
-
-      provider._forceCryptoError = true;
-      await assert.rejects(provider._hashBuffer(new Uint8Array([4]).buffer), /crypto API not available/);
-      provider._forceCryptoError = false;
-    } finally {
-      if (origDescriptor) {
-        Object.defineProperty(globalThis, 'crypto', origDescriptor);
-      } else {
-        delete globalThis.crypto;
-      }
-    }
-  });
-
-  it('stores response headers for binary entries when available', async function () {
-    const p = provider.loadBinary('data', 'with-headers.bin');
-    const url = provider._buildUrl('data', 'with-headers.bin');
-    requests[0].getResponseHeader = key => (key === 'ETag' ? 'etag' : 'last');
-    requests[0].respond(200, new ArrayBuffer(1));
-    await p;
-    const entry = JSON.parse(global.localStorage.getItem(cacheKey(url)));
-    assert.strictEqual(entry.etag, 'etag');
-    assert.strictEqual(entry.lastModified, 'last');
-  });
-
-  it('stores response headers for text entries when available', async function () {
-    const url = makeUrl('with-headers.txt');
-    const p = provider.loadString(url);
-    requests[0].getResponseHeader = key => (key === 'ETag' ? 'etag' : 'last');
-    requests[0].respond(200, 'ok');
-    await p;
-    const entry = JSON.parse(global.localStorage.getItem(cacheKey(url)));
-    assert.strictEqual(entry.etag, 'etag');
-    assert.strictEqual(entry.lastModified, 'last');
-  });
-
-  it('_verifyCache refreshes stale entries', async function () {
-    let headCalls = 0;
-    let fetchCalls = 0;
-    provider._fetchHead = async () => {
-      headCalls++;
-      return { etag: 'new', lastModified: 'new' };
-    };
-    provider._fetchBinary = async () => {
-      fetchCalls++;
-      return new MockBinaryReader();
-    };
-
-    const entry = { type: 'binary', etag: 'old', lastModified: 'old' };
-    await provider._verifyCache('some/url', entry);
-
-    assert.strictEqual(headCalls, 1);
-    assert.strictEqual(fetchCalls, 1);
-  });
-
-  it('_verifyCache returns early on matching headers', async function () {
-    let fetchCalls = 0;
-    provider._fetchHead = async () => ({ etag: 'same', lastModified: 'same' });
-    provider._fetchBinary = async () => { fetchCalls++; return new MockBinaryReader(); };
-    await provider._verifyCache('url', { type: 'binary', etag: 'same' });
-    assert.strictEqual(fetchCalls, 0);
-
-    provider._fetchHead = async () => ({ etag: 'other', lastModified: 'match' });
-    await provider._verifyCache('url', { type: 'binary', lastModified: 'match' });
-    assert.strictEqual(fetchCalls, 0);
-  });
-
-  it('_verifyCache swallows update errors', async function () {
-    provider._fetchHead = async () => ({ etag: 'new', lastModified: 'new' });
-    provider._fetchText = async () => { throw new Error('fail'); };
-    const logs = [];
-    const orig = console.log;
-    console.log = (...args) => logs.push(args);
-    await provider._verifyCache('url', { type: 'text', etag: 'old' });
-    console.log = orig;
-    assert.ok(logs.length > 0);
-  });
-
-  it('_verifyCache refreshes stale text entries', async function () {
-    let textCalls = 0;
-    provider._fetchHead = async () => ({ etag: 'new', lastModified: 'new' });
-    provider._fetchText = async () => { textCalls++; };
-    await provider._verifyCache('url', { type: 'text', etag: 'old' });
-    assert.strictEqual(textCalls, 1);
-  });
-
-  it('_hashBuffer falls back to node crypto when web crypto missing', async function () {
-    provider = new FileProvider(rootPath);
-    const buf = Uint8Array.from([1,2,3]).buffer;
-    const orig = global.crypto;
-    delete global.crypto;
-    const hash = await provider._hashBuffer(buf);
-    global.crypto = orig;
-    const { createHash } = await import('node:crypto');
-    const expected = createHash('sha256').update(Buffer.from(buf)).digest('hex');
-    assert.strictEqual(hash, expected);
-  });
-
-  it('_hashBuffer uses web crypto when available', async function () {
-    const orig = global.crypto;
-    global.crypto = {
-      subtle: {
-        digest: async () => Uint8Array.from([0, 255]).buffer
-      }
-    };
-    const buf = Uint8Array.from([1, 2]).buffer;
-    const hash = await provider._hashBuffer(buf);
-    global.crypto = orig;
-    assert.strictEqual(hash, '00ff');
-  });
-
-  it('_hashBuffer throws when crypto APIs are unavailable', async function () {
-    const orig = global.crypto;
-    delete global.crypto;
-    provider._forceCryptoError = true;
-    const buf = Uint8Array.from([1, 2]).buffer;
-    await assert.rejects(provider._hashBuffer(buf), /crypto API not available/);
-    provider._forceCryptoError = false;
-    global.crypto = orig;
-  });
-
-  it('base64 conversion roundtrips', function () {
-    provider = new FileProvider(rootPath);
-    const buf = Uint8Array.from([65,66,67]).buffer;
-    const b64 = provider._arrayBufferToBase64(buf);
-    const out = provider._base64ToArrayBuffer(b64);
-    assert.deepStrictEqual(Array.from(new Uint8Array(out)), [65,66,67]);
-  });
-
-  it('_fetchText stores data and headers in localStorage', async function () {
-    provider._hashString = async () => 'h';
-    const url = makeUrl('text.txt');
-    const promise = provider._fetchText(url);
-    requests[0].respond(200, 'hi');
-    const result = await promise;
-    assert.strictEqual(result, 'hi');
-    const entry = JSON.parse(global.localStorage.getItem(cacheKey(url)));
-    assert.strictEqual(entry.type, 'text');
-    assert.strictEqual(entry.data, 'hi');
-    assert.strictEqual(entry.hash, 'h');
-  });
-
-  it('_fetchText logs and rejects on failure', async function () {
-    const promise = provider._fetchText(makeUrl('bad.txt'));
-    requests[0].respond(404, 'err');
-    await assert.rejects(promise);
-    assert.ok(provider.log.logged.some(m => m.includes('error load file')));
-  });
-
-  it('_fetchBinary rejects when onload reports error status', async function () {
-    const promise = provider._fetchBinary(rootPath + 'bad.bin', 'data');
-    const xhr = requests[0];
-    xhr.status = 500;
-    xhr.response = new ArrayBuffer(0);
-    xhr.onload();
-    await assert.rejects(promise);
-    assert.ok(provider.log.logged.some(m => m.includes('error load file')));
-  });
-
-  it('_fetchText rejects when onload reports error status', async function () {
-    const promise = provider._fetchText(makeUrl('bad2.txt'));
-    const xhr = requests[0];
-    xhr.status = 500;
-    xhr.response = 'err';
-    xhr.onload();
-    await assert.rejects(promise);
-    assert.ok(provider.log.logged.some(m => m.includes('error load file')));
-  });
-
-  it('_fetchHead handles missing fetch', async function () {
-    delete global.fetch;
-    const result = await provider._fetchHead('url');
-    assert.strictEqual(result, null);
-  });
-
-  it('_fetchHead returns headers and swallows errors', async function () {      
-    global.fetch = async () => {
-      return { headers: { get: key => ({ ETag: 'v', 'Last-Modified': 'm' }[key]) } };
-    };
-    const success = await provider._fetchHead('url');
-    assert.deepStrictEqual(success, { etag: 'v', lastModified: 'm' });
-    global.fetch = async () => { throw new Error('fail'); };
-    const failure = await provider._fetchHead('url');
-    assert.strictEqual(failure, null);
-  });
-
-  it('skips indexedDB entries with mismatched types or missing payloads', async function () {
-    const idb = createIndexedDb();
-    global.indexedDB = idb;
-    provider = new FileProvider(rootPath);
-    await provider._openIndexedDb();
-    const entries = idb._stores.get('entries');
-    const payloads = idb._stores.get('payloads');
-    const url = rootPath + 'cached.bin';
-    entries.set(url, { url, type: 'text', size: 1, lastAccess: 1 });
-    payloads.set(url, { url, data: new ArrayBuffer(1) });
-
-    const mismatch = await provider._loadFromIndexedDb(url, 'binary', 'data');
-    assert.strictEqual(mismatch, null);
-
-    entries.set(url, { url, type: 'binary', size: 1, lastAccess: 1 });
-    payloads.delete(url);
-    const missing = await provider._loadFromIndexedDb(url, 'binary', 'data');
-    assert.strictEqual(missing, null);
-  });
-
-  it('loads text payloads from indexedDB', async function () {
-    const idb = createIndexedDb();
-    global.indexedDB = idb;
-    provider = new FileProvider(rootPath);
-    await provider._openIndexedDb();
-    const entries = idb._stores.get('entries');
-    const payloads = idb._stores.get('payloads');
-    const url = makeUrl('cached.txt');
-    entries.set(url, { url, type: 'text', size: 4, lastAccess: 1 });
-    payloads.set(url, { url, data: 'ok' });
-
-    const result = await provider._loadFromIndexedDb(url, 'text');
-    assert.strictEqual(result.value, 'ok');
-  });
-
-  it('estimates entry sizes for buffers, views, and strings', function () {
-    const buf = new ArrayBuffer(4);
-    assert.strictEqual(provider._estimateEntrySize({ type: 'binary', data: buf }), 4);
-    assert.strictEqual(provider._estimateEntrySize({
-      type: 'binary',
-      data: new Uint8Array([1, 2])
-    }), 2);
-    assert.ok(provider._estimateEntrySize({ type: 'text', data: 'abc' }) >= 3);
-    assert.strictEqual(provider._estimateEntrySize(null), 0);
-  });
-
-  it('handles localStorage fallbacks and evictions', function () {
-    delete global.localStorage;
-    assert.deepStrictEqual(provider._getLocalStorageEntries(), []);
-    assert.strictEqual(provider._storeInLocalStorage('url', { type: 'text', data: 'x' }), false);
-
-    const store = new Map([
-      ['lem-cache:' + rootPath + 'a', JSON.stringify({ lastAccess: 1, size: 20 })],
-      ['lem-cache:' + rootPath + 'b', JSON.stringify({ lastAccess: 2, size: 20 })]
-    ]);
-    const removed = [];
-    global.localStorage = {
-      length: store.size,
-      key(i) { return Array.from(store.keys())[i] ?? null; },
-      getItem(key) { return store.get(key) ?? null; },
-      removeItem(key) { removed.push(key); store.delete(key); },
-      setItem(key, value) { store.set(key, value); }
-    };
-    provider._evictLocalStorage(4 * 1024 * 1024);
-    assert.strictEqual(removed.length, 2);
-  });
-
-  it('stops evicting localStorage once under target', function () {
-    const store = new Map([
-      ['lem-cache:' + rootPath + 'a', JSON.stringify({ lastAccess: 1, size: 200 })],
-      ['lem-cache:' + rootPath + 'b', JSON.stringify({ lastAccess: 2, size: 5 })]
-    ]);
-    let removed = 0;
-    global.localStorage = {
-      length: store.size,
-      key(i) { return Array.from(store.keys())[i] ?? null; },
-      getItem(key) { return store.get(key) ?? null; },
-      removeItem(key) { removed += 1; store.delete(key); },
-      setItem(key, value) { store.set(key, value); }
-    };
-    provider._evictLocalStorage(4 * 1024 * 1024 - 1);
-    assert.strictEqual(removed, 1);
-  });
-
-  it('returns null when localStorage entries are wrong type', function () {
-    const url = rootPath + 'wrong.bin';
-    setTextCache(url, 'ok');
-    const result = provider._loadFromLocalStorage(url, 'binary', 'data');
-    assert.strictEqual(result, null);
-  });
-
-  it('uses indexedDB cache when available', async function () {
-    const idb = createIndexedDb();
-    global.indexedDB = idb;
-    provider = new FileProvider(rootPath);
-    const url = provider._buildUrl('data', 'cached.bin');
-    const buffer = new ArrayBuffer(4);
-    await provider._storeInIndexedDb(url, { type: 'binary', data: buffer, hash: 'h' });
-
-    const result = await provider.loadBinary('data', 'cached.bin');
-    assert.ok(result instanceof MockBinaryReader);
-    assert.strictEqual(requests.length, 0);
-  });
-
-  it('disables indexedDB on open errors', async function () {
-    global.indexedDB = createIndexedDb({ failOpen: true });
-    provider = new FileProvider(rootPath);
-    const db = await provider._openIndexedDb();
-    assert.strictEqual(db, null);
-    assert.strictEqual(provider._idbDisabled, true);
-  });
-
-  it('enumerates localStorage entries using key/length', function () {
-    const store = new Map([
-      ['lem-cache:' + rootPath + 'a.txt', 'a'],
-      ['other', 'skip']
-    ]);
-    global.localStorage = {
-      length: store.size,
-      key(i) { return Array.from(store.keys())[i] ?? null; },
-      getItem(key) { return store.get(key) ?? null; },
-      removeItem(key) { store.delete(key); },
-      setItem(key, value) { store.set(key, value); }
-    };
-    const entries = provider._getLocalStorageEntries();
-    assert.strictEqual(entries.length, 1);
-    assert.strictEqual(entries[0].key, 'lem-cache:' + rootPath + 'a.txt');
-  });
-
-  it('prunes indexedDB entries when over the limit', async function () {
-    const idb = createIndexedDb();
-    global.indexedDB = idb;
-    provider = new FileProvider(rootPath);
-    await provider._openIndexedDb();
-    const entries = idb._stores.get('entries');
-    const payloads = idb._stores.get('payloads');
-    const meta = idb._stores.get('meta');
-    const urlA = rootPath + 'a.bin';
-    const urlB = rootPath + 'b.bin';
-    entries.set(urlA, { url: urlA, size: 30 * 1024 * 1024, lastAccess: 1 });
-    entries.set(urlB, { url: urlB, size: 30 * 1024 * 1024, lastAccess: 2 });
-    payloads.set(urlA, { url: urlA, data: new ArrayBuffer(1) });
-    payloads.set(urlB, { url: urlB, data: new ArrayBuffer(1) });
-    meta.set('totalBytes', { key: 'totalBytes', value: 60 * 1024 * 1024 });
-
-    await provider._pruneIndexedDb(60 * 1024 * 1024);
-    await new Promise(resolve => setTimeout(resolve, 10));
-
-    assert.ok(entries.size < 2);
-    const metaEntry = meta.get('totalBytes');
-    assert.ok(metaEntry.value <= 60 * 1024 * 1024);
-  });
-
-  it('prunes indexedDB entries with missing size metadata', async function () {
-    const idb = createIndexedDb();
-    global.indexedDB = idb;
-    provider = new FileProvider(rootPath);
-    await provider._openIndexedDb();
-    const entries = idb._stores.get('entries');
-    const payloads = idb._stores.get('payloads');
-    const meta = idb._stores.get('meta');
-    const url = rootPath + 'nosize.bin';
-    entries.set(url, { url, lastAccess: 1 });
-    payloads.set(url, { url, data: new ArrayBuffer(1) });
-    meta.set('totalBytes', { key: 'totalBytes', value: 60 * 1024 * 1024 });
-
-    await provider._pruneIndexedDb(60 * 1024 * 1024);
-    await new Promise(resolve => setTimeout(resolve, 10));
-    assert.ok(entries.size < 1);
-  });
-
-  it('_storeInLocalStorage ignores write errors', function () {
-    global.localStorage.setItem = () => { throw new Error('nope'); };
-    const result = provider._storeInLocalStorage('url', { a: 1 });
-    assert.strictEqual(result, false);
-  });
-
-  it('falls back to localStorage when indexedDB misses', async function () {
-    const idb = createIndexedDb();
-    global.indexedDB = idb;
-    provider = new FileProvider(rootPath);
-
-    const binUrl = provider._buildUrl('data', 'fallback.bin');
-    const buf = Uint8Array.from([1]).buffer;
-    setBinaryCache(binUrl, buf);
-
-    const bin = await provider.loadBinary('data', 'fallback.bin');
-    assert.ok(bin instanceof MockBinaryReader);
-    assert.strictEqual(requests.length, 0);
-
-    const textUrl = makeUrl('fallback.txt');
-    setTextCache(textUrl, 'hello');
-    const text = await provider.loadString(textUrl);
-    assert.strictEqual(text, 'hello');
-  });
-
-  it('handles indexedDB failures in load and touch paths', async function () {  
-    provider._openIndexedDb = async () => null;
-    const missing = await provider._loadFromIndexedDb('url', 'text');
-    assert.strictEqual(missing, null);
-    await provider._touchIndexedDbEntry('url', { url: 'url' });
-
-    provider._openIndexedDb = async () => ({ transaction() { throw new Error('fail'); } });
-    const failed = await provider._loadFromIndexedDb('url', 'text');
-    assert.strictEqual(failed, null);
-    await provider._touchIndexedDbEntry('url', { url: 'url' });
-  });
-
-  it('_idbRequest rejects when a request fails', async function () {
-    const request = { error: new Error('fail') };
-    const promise = provider._idbRequest(request);
-    request.onerror();
-    await assert.rejects(promise, /fail/);
-  });
-
-  it('closes indexedDB on version changes', async function () {
-    const closeCalls = [];
-    global.indexedDB = {
-      open() {
-        const request = {};
-        setTimeout(() => {
-          request.result = {
-            objectStoreNames: { contains() { return true; } },
-            close() { closeCalls.push(true); }
-          };
-          request.onsuccess?.();
-        }, 0);
-        return request;
-      }
-    };
-    provider = new FileProvider(rootPath);
-    const db = await provider._openIndexedDb();
-    db.onversionchange();
-    assert.strictEqual(closeCalls.length, 1);
-  });
-
-  it('updates indexedDB sizes when entries already exist', async function () {
-    const idb = createIndexedDb();
-    global.indexedDB = idb;
-    provider = new FileProvider(rootPath);
-    await provider._openIndexedDb();
-    const entries = idb._stores.get('entries');
-    const meta = idb._stores.get('meta');
-    const url = rootPath + 'cached.bin';
-    entries.set(url, { url, type: 'binary', size: 10, lastAccess: 1 });
-    meta.set('totalBytes', { key: 'totalBytes', value: 10 });
-
-    const stored = await provider._storeInIndexedDb(url, { type: 'binary', data: new ArrayBuffer(2) });
-    assert.strictEqual(stored, true);
-    const updated = meta.get('totalBytes');
-    assert.strictEqual(updated.value, 2);
-  });
-
-  it('returns false when indexedDB storage fails', async function () {
-    provider._openIndexedDb = async () => ({ transaction() { throw new Error('fail'); } });
-    const stored = await provider._storeInIndexedDb('url', { type: 'text', data: 'x' });
-    assert.strictEqual(stored, false);
-  });
-
-  it('triggers indexedDB pruning after oversized writes', async function () {
-    let pruneCalls = 0;
-    provider._estimateEntrySize = () => 60 * 1024 * 1024;
-    let idbCalls = 0;
-    provider._idbRequest = async () => {
-      idbCalls++;
-      if (idbCalls === 1) return null;
-      return { value: 0 };
-    };
-    provider._openIndexedDb = async () => ({
-      transaction() {
-        const tx = {
-          objectStore() {
-            return {
-              get() { return {}; },
-              put() {}
-            };
-          }
-        };
-        setTimeout(() => tx.oncomplete?.(), 0);
-        return tx;
-      }
-    });
-    provider._pruneIndexedDb = () => { pruneCalls++; };
-
-    const stored = await provider._storeInIndexedDb('url', { type: 'text', data: 'x' });
-    assert.strictEqual(stored, true);
-    await new Promise(resolve => setTimeout(resolve, 10));
-    assert.strictEqual(pruneCalls, 1);
-  });
-
-  it('prunes indexedDB only when over the limit', async function () {
-    provider._openIndexedDb = async () => null;
-    await provider._pruneIndexedDb(10);
-
-    const idb = createIndexedDb();
-    global.indexedDB = idb;
-    provider = new FileProvider(rootPath);
-    await provider._openIndexedDb();
-    await provider._pruneIndexedDb(1024);
-  });
-
-  it('swallows pruning errors when indexedDB transactions fail', async function () {
-    provider._openIndexedDb = async () => ({ transaction() { throw new Error('fail'); } });
-    await provider._pruneIndexedDb(60 * 1024 * 1024);
-  });
-
-  it('estimates sizes without TextEncoder and ignores unknown data', function () {
-    const orig = global.TextEncoder;
-    global.TextEncoder = undefined;
-    assert.strictEqual(provider._estimateTextSize('abcd'), 4);
-    assert.strictEqual(provider._estimateTextSize(''), 0);
-    global.TextEncoder = orig;
-
-    assert.strictEqual(provider._estimateEntrySize({ type: 'binary', data: 5 }), 0);
-  });
-
-  it('enumerates localStorage entries using store.forEach', function () {
-    const store = new Map([
-      ['lem-cache:' + rootPath + 'a.txt', 'a'],
-      ['other', 'skip']
-    ]);
-    global.localStorage = { store };
-    const entries = provider._getLocalStorageEntries();
-    assert.strictEqual(entries.length, 1);
-    assert.strictEqual(entries[0].key, 'lem-cache:' + rootPath + 'a.txt');
-  });
-
-  it('evicts localStorage safely with malformed entries', function () {
-    const store = new Map([
-      ['lem-cache:' + rootPath + 'bad', '{bad'],
-      ['lem-cache:' + rootPath + 'empty', null]
-    ]);
-    global.localStorage = {
-      length: store.size,
-      key(i) { return Array.from(store.keys())[i] ?? null; },
-      getItem(key) { return store.get(key) ?? null; },
-      removeItem(key) { store.delete(key); },
-      setItem(key, value) { store.set(key, value); }
-    };
-
-    const usage = provider._getLocalStorageUsage();
-    provider._evictLocalStorage();
-    assert.strictEqual(provider._cacheStats.localStorageBytes, usage);
-  });
-
-  it('handles missing localStorage in touch and load paths', function () {
-    delete global.localStorage;
-    assert.strictEqual(provider._loadFromLocalStorage('url', 'text'), null);
-    provider._touchLocalStorageEntry('url', null);
-  });
-
-  it('logs and returns false when localStorage serialization fails', function () {
-    const original = provider._serializeLocalStorageEntry;
-    provider._serializeLocalStorageEntry = () => { throw new Error('fail'); };
-    const logs = [];
-    const origLog = console.log;
-    console.log = (...args) => logs.push(args);
-    const result = provider._storeInLocalStorage('url', { type: 'text', data: 'x' });
-    console.log = origLog;
-    provider._serializeLocalStorageEntry = original;
-    assert.strictEqual(result, false);
-    assert.ok(logs.length > 0);
-  });
-
-  it('serializes localStorage entries with default access times', function () {
-    const serialized = provider._serializeLocalStorageEntry({ type: 'text', data: 'x' });
-    assert.ok(serialized.entry.lastAccess > 0);
-    assert.ok(serialized.entry.size > 0);
-  });
-
-});
diff --git a/test/game-display.test.js b/test/game-display.test.js
index 608f1fcb..46838150 100644
--- a/test/game-display.test.js
+++ b/test/game-display.test.js
@@ -78,6 +78,44 @@ describe('GameDisplay', function() {
     expect(gd.hoverLemming).to.equal(lem);
   });
 
+  it('rebinds mouse listeners when the gui display changes', function() {
+    const lem = makeLemming(4);
+    let queueCount = 0;
+    const { game, lemmingManager, level, objectManager, triggerManager } = makeContext({
+      game: { queueCommand() { queueCount += 1; } },
+      lemmingManager: { getNearestLemming() { return lem; } }
+    });
+    const gd = new GameDisplay(game, level, lemmingManager, objectManager, triggerManager);
+    const firstDisplay = makeDisplay();
+    const secondDisplay = makeDisplay();
+
+    gd.setGuiDisplay(firstDisplay);
+    gd.setGuiDisplay(secondDisplay);
+
+    expect(firstDisplay.onMouseDown.handlers.size).to.equal(0);
+    expect(firstDisplay.onMouseMove.handlers.size).to.equal(0);
+    expect(secondDisplay.onMouseDown.handlers.size).to.equal(1);
+    expect(secondDisplay.onMouseMove.handlers.size).to.equal(1);
+
+    firstDisplay.onMouseDown.trigger({ x: 1, y: 2 });
+    expect(queueCount).to.equal(0);
+    secondDisplay.onMouseDown.trigger({ x: 1, y: 2 });
+    expect(queueCount).to.equal(1);
+  });
+
+  it('detaches listeners when gui display is cleared', function() {
+    const { game, lemmingManager, level, objectManager, triggerManager } = makeContext();
+    const gd = new GameDisplay(game, level, lemmingManager, objectManager, triggerManager);
+    const display = makeDisplay();
+
+    gd.setGuiDisplay(display);
+    gd.setGuiDisplay(null);
+
+    expect(display.onMouseDown.handlers.size).to.equal(0);
+    expect(display.onMouseMove.handlers.size).to.equal(0);
+    expect(gd.display).to.equal(null);
+  });
+
   it('updates hover and flags gui changes', function() {
     const prev = makeLemming(1);
     prev.removed = true;
@@ -144,6 +182,70 @@ describe('GameDisplay', function() {
     expect(calls[0][5]).to.equal(255);
   });
 
+  it('renders selection and hover on the stage overlay plane when available', function() {
+    const baseCalls = [];
+    const overlayCalls = [];
+    const overlayDisplay = {
+      clearCalls: 0,
+      clear() { this.clearCalls += 1; },
+      drawCornerRect(...args) { overlayCalls.push(args); }
+    };
+    const stage = {
+      visible: null,
+      getGameOverlayDisplay() { return overlayDisplay; },
+      setGameOverlayVisible(value) { this.visible = value; }
+    };
+    const display = makeDisplay({
+      stage,
+      drawCornerRect(...args) { baseCalls.push(args); }
+    });
+    const selected = makeLemming(1);
+    const hover = makeLemming(2);
+    const { game, lemmingManager, level, objectManager, triggerManager } = makeContext({
+      lemmingManager: {
+        render() {},
+        getSelectedLemming() { return selected; }
+      }
+    });
+    const gd = new GameDisplay(game, level, lemmingManager, objectManager, triggerManager);
+    gd.display = display;
+    gd.hoverLemming = hover;
+
+    gd.render();
+
+    expect(baseCalls.length).to.equal(0);
+    expect(overlayDisplay.clearCalls).to.equal(1);
+    expect(overlayCalls.length).to.equal(2);
+    expect(stage.visible).to.equal(true);
+  });
+
+  it('keeps overlay display lazy until needed and still clears stale overlay state', function() {
+    const overlayDisplay = { clearCalls: 0, clear() { this.clearCalls += 1; } };
+    const stage = {
+      visible: null,
+      getCalls: 0,
+      getGameOverlayDisplay() {
+        this.getCalls += 1;
+        return overlayDisplay;
+      },
+      setGameOverlayVisible(value) { this.visible = value; }
+    };
+    const display = makeDisplay({ stage });
+    const { game, lemmingManager, level, objectManager, triggerManager } = makeContext();
+    const gd = new GameDisplay(game, level, lemmingManager, objectManager, triggerManager);
+    gd.display = display;
+
+    gd.render();
+    gd.renderDebug();
+    expect(stage.getCalls).to.equal(0);
+
+    gd._overlayHadContent = true;
+    gd.render();
+    expect(stage.getCalls).to.equal(1);
+    expect(overlayDisplay.clearCalls).to.equal(1);
+    expect(stage.visible).to.equal(false);
+  });
+
   it('exposes drawCorner test hook', function() {
     const display = makeDisplay({ drawRect(...args) { this.args = args; } });
     const { game, lemmingManager, level, objectManager, triggerManager } = makeContext();
@@ -171,6 +273,34 @@ describe('GameDisplay', function() {
     expect(gd._dashOffset).to.equal(1);
   });
 
+  it('renders debug hover overlays through the stage overlay plane when available', function() {
+    const overlayDisplay = {
+      clearCalls: 0,
+      clear() { this.clearCalls += 1; },
+      drawDashedRect(...args) { this.args = args; }
+    };
+    const stage = {
+      visible: null,
+      getGameOverlayDisplay() { return overlayDisplay; },
+      setGameOverlayVisible(value) { this.visible = value; }
+    };
+    const display = makeDisplay({ stage });
+    const { game, lemmingManager, level, objectManager, triggerManager } = makeContext({
+      lemmingManager: { renderDebug() {} },
+      level: { renderDebug() {} },
+      triggerManager: { renderDebug() {} }
+    });
+    const gd = new GameDisplay(game, level, lemmingManager, objectManager, triggerManager);
+    gd.display = display;
+    gd.hoverLemming = makeLemming(3);
+
+    gd.renderDebug();
+
+    expect(overlayDisplay.clearCalls).to.equal(1);
+    expect(overlayDisplay.args).to.have.length(6);
+    expect(stage.visible).to.equal(true);
+  });
+
   it('skips input when disabled and uses fallback hover scheduling', function() {
     const display = makeDisplay();
     let queued = 0;
diff --git a/test/game-gui.coverage.01-gamegui-coverage.test.js b/test/game-gui.coverage.01-gamegui-coverage.test.js
new file mode 100644
index 00000000..92873847
--- /dev/null
+++ b/test/game-gui.coverage.01-gamegui-coverage.test.js
@@ -0,0 +1,406 @@
+import { expect } from 'chai';
+import { EventHandler } from '../js/util/EventHandler.js';
+import { GameGui } from '../js/game/GameGui.js';
+import { SkillTypes } from '../js/game/SkillTypes.js';
+import { CommandNuke } from '../js/commands/CommandNuke.js';
+import { CommandSelectSkill } from '../js/commands/CommandSelectSkill.js';
+import { CommandReleaseRateIncrease } from '../js/commands/CommandReleaseRateIncrease.js';
+import { CommandReleaseRateDecrease } from '../js/commands/CommandReleaseRateDecrease.js';
+import {
+  resetDependencies,
+  setDependency,
+  useGlobalLemmings,
+  withGlobalLemmings
+} from './helpers/lemmings.js';
+
+const makeSprites = () => {
+  const panelSprite = {
+    width: 320,
+    height: 40,
+    getData() { return new Uint8ClampedArray(320 * 40 * 4); }
+  };
+  return {
+    getPanelSprite() { return panelSprite; },
+    getNumberSpriteEmpty() { return { id: 'empty' }; },
+    getNumberSpriteLeft(n) { return { id: `L${n}` }; },
+    getNumberSpriteRight(n) { return { id: `R${n}` }; },
+    getLetterSprite(ch) { return { id: `G${ch}` }; }
+  };
+};
+
+const makeDisplay = () => ({
+  worldDataSize: { width: 320, height: 40 },
+  initCalls: [],
+  backgroundCalls: 0,
+  rects: [],
+  frames: [],
+  covered: [],
+  resized: [],
+  stipples: 0,
+  ants: 0,
+  hlines: 0,
+  pixels: 0,
+  redrawCalls: 0,
+  stage: { updateStageSize() { this.updated = true; } },
+  onMouseDown: new EventHandler(),
+  onMouseUp: new EventHandler(),
+  onMouseRightDown: new EventHandler(),
+  onMouseRightUp: new EventHandler(),
+  onDoubleClick: new EventHandler(),
+  onMouseMove: new EventHandler(),
+  initSize(width, height) {
+    this.initCalls.push({ width, height });
+    this.worldDataSize = { width, height };
+  },
+  setBackground() { this.backgroundCalls += 1; },
+  redraw() { this.redrawCalls += 1; },
+  drawRect(...args) { this.rects.push(args); },
+  drawFrame(frame) { this.frames.push(frame); },
+  drawFrameCovered(frame) { this.covered.push(frame); },
+  drawFrameResized(...args) { this.resized.push(args); },
+  drawStippleRect() { this.stipples += 1; },
+  drawMarchingAntRect() { this.ants += 1; },
+  drawHorizontalLine() { this.hlines += 1; },
+  setPixel() { this.pixels += 1; }
+});
+
+const makeGui = (options = {}) => {
+  const skillCounts = { [SkillTypes.CLIMBER]: 2, [SkillTypes.BASHER]: 1 };
+  let selectedSkill = SkillTypes.UNKNOWN;
+  const skills = {
+    onCountChanged: new EventHandler(),
+    onSelectionChanged: new EventHandler(),
+    getSelectedSkill() { return selectedSkill; },
+    setSelectedSkill(skill) { selectedSkill = skill; },
+    clearSelectedSkill() { selectedSkill = SkillTypes.UNKNOWN; return true; },
+    getSkill(skill) { return skillCounts[skill] || 0; }
+  };
+
+  const timer = {
+    speedFactor: options.speedFactor ?? 1,
+    tickIndex: 5,
+    eachGameSecond: new EventHandler(),
+    isRunning() { return options.running ?? true; },
+    getGameTime() { return 0; },
+    getGameLeftTimeString() { return '1-00'; },
+    getGameLeftTimeSString() { return '1-00'; },
+    toggle() { this.toggled = true; }
+  };
+
+  const victory = {
+    releaseRate: 20,
+    getMinReleaseRate() { return 10; },
+    getCurrentReleaseRate() { return this.releaseRate; },
+    getMaxReleaseRate() { return 99; },
+    setCurrentReleaseRate(val) { this.releaseRate = val; },
+    getReleaseCount() { return 5; },
+    getSurvivorPercentage() { return 50; }
+  };
+
+  const game = {
+    commands: [],
+    queueCommand(cmd) { this.commands.push(cmd); },
+    showDebug: false,
+    gameDisplay: { hoverLemming: null },
+    level: {
+      width: 100,
+      height: 50,
+      mechanics: options.mechanics ?? {},
+      objects: [],
+      getGroundMaskLayer() { return { countMaskInRect() { return 0; } }; }
+    },
+    lemmingManager: { setMiniMap() {} },
+    getLemmingManager() { return { spawnTotal: 5, getLemmings() { return []; } }; }
+  };
+
+  return {
+    gui: new GameGui(game, makeSprites(), skills, timer, victory),
+    game,
+    skills,
+    timer,
+    victory
+  };
+};
+
+describe('GameGui coverage', function() {
+  const originalWindow = globalThis.window;
+
+  const originalPerformance = globalThis.performance;
+
+  useGlobalLemmings({});
+
+  beforeEach(function() {
+    globalThis.window = {
+      requestAnimationFrame() { return 1; },
+      cancelAnimationFrame() {}
+    };
+    globalThis.performance = {
+      now() { return 0; },
+      measure() {}
+    };
+  });
+
+  afterEach(function() {
+    resetDependencies();
+    globalThis.window = originalWindow;
+    globalThis.performance = originalPerformance;
+  });
+
+  it('applies release rate changes and queues commands', function() {
+    const { gui, game, victory } = makeGui({ running: true });
+    gui.deltaReleaseRate = 5;
+    gui._applyReleaseRateAuto();
+    expect(victory.releaseRate).to.equal(25);
+    expect(game.commands[0]).to.be.instanceOf(CommandReleaseRateIncrease);
+
+    gui.deltaReleaseRate = -3;
+    gui._applyReleaseRateAuto();
+    expect(game.commands[1]).to.be.instanceOf(CommandReleaseRateDecrease);
+  });
+
+  it('handles skill mouse actions', function() {
+    const { gui, game, skills, timer, victory } = makeGui({ running: true });
+    victory.releaseRate = 10;
+    gui.handleSkillMouseDown({ x: 0, y: 20 });
+    expect(gui.skillSelectionChanged).to.equal(true);
+
+    gui.handleSkillMouseDown({ x: 160, y: 10 });
+    expect(timer.toggled).to.equal(true);
+
+    gui.handleSkillMouseDown({ x: 176, y: 20 });
+    gui.handleSkillMouseDown({ x: 176, y: 20 });
+    const nukeCmd = game.commands.find(cmd => cmd instanceof CommandNuke);
+    expect(nukeCmd).to.not.equal(undefined);
+
+    skills.setSelectedSkill(SkillTypes.UNKNOWN);
+    gui.handleSkillMouseDown({ x: 32, y: 20 });
+    const selectCmd = game.commands.find(cmd => cmd instanceof CommandSelectSkill);
+    expect(selectCmd).to.not.equal(undefined);
+  });
+
+  it('tracks nuke countdown and skill change flags', function() {
+    const { gui, game, skills } = makeGui({ running: true });
+    withGlobalLemmings({ nukeAfter: 1 }, () => {
+      gui.nukePrepared = true;
+
+      gui._onEachGameSecond();
+      const nukeCommands = game.commands.filter(cmd => cmd instanceof CommandNuke);
+      expect(nukeCommands.length).to.equal(1);
+      expect(gui.nukePrepared).to.equal(false);
+
+      gui.nukePrepared = true;
+      gui._onEachGameSecond();
+      const repeatedNukes = game.commands.filter(cmd => cmd instanceof CommandNuke);
+      expect(repeatedNukes.length).to.equal(2);
+      expect(gui.nukePrepared).to.equal(false);
+
+      gui.backgroundChanged = false;
+      gui._selectionOffset = 5;
+      skills.onCountChanged.trigger();
+      skills.onSelectionChanged.trigger();
+      expect(gui.backgroundChanged).to.equal(true);
+      expect(gui._selectionOffset).to.equal(0);
+    });
+  });
+
+  it('fires nuke countdown when threshold drops below accumulated seconds', function() {
+    const { gui, game } = makeGui({ running: true });
+    const app = { nukeAfter: 5 };
+    withGlobalLemmings(app, () => {
+      gui._nukeAfterCountdown = 4;
+      app.nukeAfter = 3;
+      gui._onEachGameSecond();
+      const nukeCommands = game.commands.filter(cmd => cmd instanceof CommandNuke);
+      expect(nukeCommands.length).to.equal(1);
+      expect(gui._nukeAfterCountdown).to.equal(0);
+    });
+  });
+
+  it('adjusts release rate and speed from panel clicks', function() {
+    const { gui, timer, victory, skills } = makeGui({ running: true });
+    const app = { gameSpeedFactor: 1 };
+    withGlobalLemmings(app, () => {
+      gui.drawSpeedChange = () => {};
+
+      victory.releaseRate = 20;
+      gui.releaseRateChanged = false;
+      gui.handleSkillMouseDown({ x: 0, y: 20 });
+      expect(victory.releaseRate).to.equal(14);
+      expect(gui.releaseRateChanged).to.equal(true);
+
+      victory.releaseRate = 20;
+      gui.releaseRateChanged = false;
+      gui.handleSkillMouseDown({ x: 16, y: 20 });
+      expect(victory.releaseRate).to.equal(26);
+      expect(gui.releaseRateChanged).to.equal(true);
+
+      timer.speedFactor = 11;
+      gui.handleSkillMouseDown({ x: 160, y: 32 });
+      expect(timer.speedFactor).to.equal(1);
+      timer.speedFactor = 2;
+      gui.handleSkillMouseDown({ x: 160, y: 32 });
+      expect(timer.speedFactor).to.equal(1);
+      timer.speedFactor = 1;
+      gui.handleSkillMouseDown({ x: 160, y: 32 });
+      expect(timer.speedFactor).to.equal(0.9);
+
+      timer.speedFactor = 0.5;
+      gui.handleSkillMouseDown({ x: 170, y: 32 });
+      expect(timer.speedFactor).to.equal(0.6);
+      timer.speedFactor = 20;
+      gui.handleSkillMouseDown({ x: 170, y: 32 });
+      expect(timer.speedFactor).to.equal(30);
+      timer.speedFactor = 5;
+      gui.handleSkillMouseDown({ x: 170, y: 32 });
+      expect(timer.speedFactor).to.equal(6);
+
+      skills.getSkill = () => 0;
+      gui.handleSkillMouseDown({ x: 32, y: 20 });
+      expect(gui.skillSelectionChanged).to.equal(true);
+
+      gui.handleSkillDoubleClick({ x: 176, y: 20 });
+      const doubleNuke = gui.game.commands.find(cmd => cmd instanceof CommandNuke);
+      expect(doubleNuke).to.not.equal(undefined);
+    });
+  });
+
+  it('does not redraw zero-skill stipples when counts are unchanged', function() {
+    const display = makeDisplay();
+    const { gui } = makeGui({ running: true });
+    gui.setGuiDisplay(display);
+    gui.display = display;
+    gui.backgroundChanged = true;
+    gui.skillsCountChanged = true;
+    gui.gameTimeChanged = false;
+    gui.releaseRateChanged = false;
+    gui.gameSpeedChanged = false;
+    gui.render();
+
+    const stipplesAfterFirstRender = display.stipples;
+    gui.backgroundChanged = false;
+    gui.skillsCountChanged = false;
+    gui.gameTimeChanged = false;
+    gui.releaseRateChanged = false;
+    gui.gameSpeedChanged = false;
+    gui.render();
+
+    expect(display.stipples).to.equal(stipplesAfterFirstRender);
+  });
+
+  it('handles right-click actions and hover state', function() {
+    const { gui, game, timer, victory } = makeGui({ running: true });
+    gui.handleSkillMouseRightDown({ x: 0, y: 20 });
+    expect(game.commands[0]).to.be.instanceOf(CommandReleaseRateDecrease);
+
+    gui.handleSkillMouseRightDown({ x: 16, y: 20 });
+    expect(game.commands[1]).to.be.instanceOf(CommandReleaseRateIncrease);
+
+    timer.speedFactor = 2;
+    gui.drawSpeedChange = () => { gui.speedDrawn = true; };
+    gui.handleSkillMouseRightDown({ x: 160, y: 20 });
+    expect(gui.speedDrawn).to.equal(true);
+
+    gui.handleSkillMouseRightDown({ x: 176, y: 20 });
+    expect(game.showDebug).to.equal(true);
+
+    victory.releaseRate = victory.getMinReleaseRate();
+    gui.handleMouseMove({ x: 0, y: 20 });
+    expect(gui._hoverPanelIdx).to.equal(-1);
+
+    timer.speedFactor = 1;
+    gui.handleMouseMove({ x: 168, y: 40 });
+    expect(gui._hoverSpeedUp || gui._hoverSpeedDown).to.equal(true);
+  });
+
+  it('clears release-rate delta on right mouse up', function() {
+    const display = makeDisplay();
+    const { gui } = makeGui({ running: true });
+    gui.setGuiDisplay(display);
+    gui.deltaReleaseRate = 9;
+
+    display.onMouseRightUp.trigger({});
+    expect(gui.deltaReleaseRate).to.equal(0);
+  });
+
+  it('disables glitch actions when mechanics flags are off', function() {
+    const { gui, game, timer, victory } = makeGui({
+      running: false,
+      mechanics: {
+        rightClickGlitch: false,
+        nukeGlitch: false,
+        pauseGlitch: false
+      }
+    });
+
+    gui.deltaReleaseRate = 3;
+    gui._applyReleaseRateAuto();
+    expect(game.commands.length).to.equal(0);
+
+    timer.speedFactor = 2;
+    gui.drawSpeedChange = () => { gui.speedDrawn = true; };
+    gui.handleSkillMouseRightDown({ x: 0, y: 20 });
+    gui.handleSkillMouseRightDown({ x: 16, y: 20 });
+    gui.handleSkillMouseRightDown({ x: 160, y: 20 });
+    gui.handleSkillMouseRightDown({ x: 176, y: 20 });
+    expect(game.commands.length).to.equal(0);
+    expect(victory.releaseRate).to.equal(20);
+    expect(gui.speedDrawn).to.equal(undefined);
+    expect(game.showDebug).to.equal(false);
+
+    gui.handleSkillDoubleClick({ x: 176, y: 20 });
+    expect(game.commands.length).to.equal(0);
+  });
+
+  it('suppresses hover when paused or skill counts are empty', function() {
+    const { gui, skills, timer } = makeGui({ running: false });
+    timer.isRunning = () => false;
+    gui.handleMouseMove({ x: 32, y: 20 });
+    expect(gui._hoverPanelIdx).to.equal(-1);
+
+    timer.isRunning = () => true;
+    skills.getSkill = () => 0;
+    gui.handleMouseMove({ x: 32, y: 20 });
+    expect(gui._hoverPanelIdx).to.equal(-1);
+  });
+
+  it('covers clamping, fallbacks, and helper branches', function() {
+    const { gui, victory, game } = makeGui({ running: true });
+    victory.getMinReleaseRate = () => 10;
+    victory.getMaxReleaseRate = () => 20;
+    victory.releaseRate = 10;
+    gui.deltaReleaseRate = -5;
+    gui._applyReleaseRateAuto();
+    expect(victory.releaseRate).to.equal(10);
+    expect(game.commands.length).to.equal(0);
+
+    victory.releaseRate = 20;
+    gui.deltaReleaseRate = 5;
+    gui._applyReleaseRateAuto();
+    expect(victory.releaseRate).to.equal(20);
+    expect(game.commands.length).to.equal(0);
+
+    victory.releaseRate = 15;
+    gui.deltaReleaseRate = -5;
+    gui._applyReleaseRateAuto();
+    expect(victory.releaseRate).to.equal(10);
+    expect(game.commands.length).to.equal(1);
+
+    gui.handleSkillMouseDown({ x: 500, y: 20 });
+    gui.handleMouseMove({ x: 0, y: 0 });
+
+    gui.gameVictoryCondition = {};
+    gui.handleMouseMove({ x: 0, y: 20 });
+
+    expect(gui._composeStatusText('', '')).to.equal('');
+    expect(gui._pad(1234, 2)).to.equal('1234');
+    gui.drawSelection(makeDisplay(), -1);
+
+    expect(gui.getSkillByPanelIndex(3)).to.equal(SkillTypes.FLOATER);
+    expect(gui.getSkillByPanelIndex(4)).to.equal(SkillTypes.BOMBER);
+    expect(gui.getSkillByPanelIndex(5)).to.equal(SkillTypes.BLOCKER);
+    expect(gui.getSkillByPanelIndex(6)).to.equal(SkillTypes.BUILDER);
+    expect(gui.getSkillByPanelIndex(7)).to.equal(SkillTypes.BASHER);
+    expect(gui.getSkillByPanelIndex(8)).to.equal(SkillTypes.MINER);
+    expect(gui.getSkillByPanelIndex(9)).to.equal(SkillTypes.DIGGER);
+  });
+});
diff --git a/test/game-gui.coverage.test.js b/test/game-gui.coverage.02-gamegui-coverage.test.js
similarity index 62%
rename from test/game-gui.coverage.test.js
rename to test/game-gui.coverage.02-gamegui-coverage.test.js
index 7234bca1..1213862f 100644
--- a/test/game-gui.coverage.test.js
+++ b/test/game-gui.coverage.02-gamegui-coverage.test.js
@@ -105,6 +105,7 @@ const makeGui = (options = {}) => {
     level: {
       width: 100,
       height: 50,
+      mechanics: options.mechanics ?? {},
       objects: [],
       getGroundMaskLayer() { return { countMaskInRect() { return 0; } }; }
     },
@@ -123,7 +124,9 @@ const makeGui = (options = {}) => {
 
 describe('GameGui coverage', function() {
   const originalWindow = globalThis.window;
+
   const originalPerformance = globalThis.performance;
+
   useGlobalLemmings({});
 
   beforeEach(function() {
@@ -143,171 +146,6 @@ describe('GameGui coverage', function() {
     globalThis.performance = originalPerformance;
   });
 
-  it('applies release rate changes and queues commands', function() {
-    const { gui, game, victory } = makeGui({ running: true });
-    gui.deltaReleaseRate = 5;
-    gui._applyReleaseRateAuto();
-    expect(victory.releaseRate).to.equal(25);
-    expect(game.commands[0]).to.be.instanceOf(CommandReleaseRateIncrease);
-
-    gui.deltaReleaseRate = -3;
-    gui._applyReleaseRateAuto();
-    expect(game.commands[1]).to.be.instanceOf(CommandReleaseRateDecrease);
-  });
-
-  it('handles skill mouse actions', function() {
-    const { gui, game, skills, timer, victory } = makeGui({ running: true });   
-    victory.releaseRate = 10;
-    gui.handleSkillMouseDown({ x: 0, y: 20 });
-    expect(gui.skillSelectionChanged).to.equal(true);
-
-    gui.handleSkillMouseDown({ x: 160, y: 10 });
-    expect(timer.toggled).to.equal(true);
-
-    gui.handleSkillMouseDown({ x: 176, y: 20 });
-    gui.handleSkillMouseDown({ x: 176, y: 20 });
-    const nukeCmd = game.commands.find(cmd => cmd instanceof CommandNuke);
-    expect(nukeCmd).to.not.equal(undefined);
-
-    skills.setSelectedSkill(SkillTypes.UNKNOWN);
-    gui.handleSkillMouseDown({ x: 32, y: 20 });
-    const selectCmd = game.commands.find(cmd => cmd instanceof CommandSelectSkill);
-    expect(selectCmd).to.not.equal(undefined);
-  });
-
-  it('tracks nuke countdown and skill change flags', function() {
-    const { gui, game, skills } = makeGui({ running: true });
-    withGlobalLemmings({ nukeAfter: 1 }, () => {
-      gui.nukePrepared = true;
-
-      gui._onEachGameSecond();
-      const nukeCmd = game.commands.find(cmd => cmd instanceof CommandNuke);
-      expect(nukeCmd).to.not.equal(undefined);
-      expect(gui.nukePrepared).to.equal(false);
-
-      gui.backgroundChanged = false;
-      gui._selectionOffset = 5;
-      skills.onCountChanged.trigger();
-      skills.onSelectionChanged.trigger();
-      expect(gui.backgroundChanged).to.equal(true);
-      expect(gui._selectionOffset).to.equal(0);
-    });
-  });
-
-  it('adjusts release rate and speed from panel clicks', function() {
-    const { gui, timer, victory, skills } = makeGui({ running: true });
-    const app = { gameSpeedFactor: 1 };
-    withGlobalLemmings(app, () => {
-      gui.drawSpeedChange = () => {};
-
-      victory.releaseRate = 20;
-      gui.handleSkillMouseDown({ x: 0, y: 20 });
-      expect(victory.releaseRate).to.equal(14);
-
-      victory.releaseRate = 20;
-      gui.handleSkillMouseDown({ x: 16, y: 20 });
-      expect(victory.releaseRate).to.equal(26);
-
-      timer.speedFactor = 11;
-      gui.handleSkillMouseDown({ x: 160, y: 32 });
-      expect(timer.speedFactor).to.equal(1);
-      timer.speedFactor = 2;
-      gui.handleSkillMouseDown({ x: 160, y: 32 });
-      expect(timer.speedFactor).to.equal(1);
-      timer.speedFactor = 1;
-      gui.handleSkillMouseDown({ x: 160, y: 32 });
-      expect(timer.speedFactor).to.equal(0.9);
-
-      timer.speedFactor = 0.5;
-      gui.handleSkillMouseDown({ x: 170, y: 32 });
-      expect(timer.speedFactor).to.equal(0.6);
-      timer.speedFactor = 20;
-      gui.handleSkillMouseDown({ x: 170, y: 32 });
-      expect(timer.speedFactor).to.equal(30);
-      timer.speedFactor = 5;
-      gui.handleSkillMouseDown({ x: 170, y: 32 });
-      expect(timer.speedFactor).to.equal(6);
-
-      skills.getSkill = () => 0;
-      gui.handleSkillMouseDown({ x: 32, y: 20 });
-      expect(gui.skillSelectionChanged).to.equal(true);
-
-      gui.handleSkillDoubleClick({ x: 176, y: 20 });
-      const doubleNuke = gui.game.commands.find(cmd => cmd instanceof CommandNuke);
-      expect(doubleNuke).to.not.equal(undefined);
-    });
-  });
-
-  it('handles right-click actions and hover state', function() {
-    const { gui, game, timer, victory } = makeGui({ running: true });
-    gui.handleSkillMouseRightDown({ x: 0, y: 20 });
-    expect(game.commands[0]).to.be.instanceOf(CommandReleaseRateDecrease);
-
-    gui.handleSkillMouseRightDown({ x: 16, y: 20 });
-    expect(game.commands[1]).to.be.instanceOf(CommandReleaseRateIncrease);
-
-    timer.speedFactor = 2;
-    gui.drawSpeedChange = () => { gui.speedDrawn = true; };
-    gui.handleSkillMouseRightDown({ x: 160, y: 20 });
-    expect(gui.speedDrawn).to.equal(true);
-
-    gui.handleSkillMouseRightDown({ x: 176, y: 20 });
-    expect(game.showDebug).to.equal(true);
-
-    victory.releaseRate = victory.getMinReleaseRate();
-    gui.handleMouseMove({ x: 0, y: 20 });
-    expect(gui._hoverPanelIdx).to.equal(-1);
-
-    timer.speedFactor = 1;
-    gui.handleMouseMove({ x: 168, y: 40 });
-    expect(gui._hoverSpeedUp || gui._hoverSpeedDown).to.equal(true);
-  });
-
-  it('suppresses hover when paused or skill counts are empty', function() {     
-    const { gui, skills, timer } = makeGui({ running: false });
-    timer.isRunning = () => false;
-    gui.handleMouseMove({ x: 32, y: 20 });
-    expect(gui._hoverPanelIdx).to.equal(-1);
-
-    timer.isRunning = () => true;
-    skills.getSkill = () => 0;
-    gui.handleMouseMove({ x: 32, y: 20 });
-    expect(gui._hoverPanelIdx).to.equal(-1);
-  });
-
-  it('covers clamping, fallbacks, and helper branches', function() {
-    const { gui, victory } = makeGui({ running: true });
-    victory.getMinReleaseRate = () => 10;
-    victory.getMaxReleaseRate = () => 20;
-    victory.releaseRate = 10;
-    gui.deltaReleaseRate = -5;
-    gui._applyReleaseRateAuto();
-    expect(victory.releaseRate).to.equal(10);
-
-    victory.releaseRate = 20;
-    gui.deltaReleaseRate = 5;
-    gui._applyReleaseRateAuto();
-    expect(victory.releaseRate).to.equal(20);
-
-    gui.handleSkillMouseDown({ x: 500, y: 20 });
-    gui.handleMouseMove({ x: 0, y: 0 });
-
-    gui.gameVictoryCondition = {};
-    gui.handleMouseMove({ x: 0, y: 20 });
-
-    expect(gui._composeStatusText('', '')).to.equal('');
-    expect(gui._pad(1234, 2)).to.equal('1234');
-    gui.drawSelection(makeDisplay(), -1);
-
-    expect(gui.getSkillByPanelIndex(3)).to.equal(SkillTypes.FLOATER);
-    expect(gui.getSkillByPanelIndex(4)).to.equal(SkillTypes.BOMBER);
-    expect(gui.getSkillByPanelIndex(5)).to.equal(SkillTypes.BLOCKER);
-    expect(gui.getSkillByPanelIndex(6)).to.equal(SkillTypes.BUILDER);
-    expect(gui.getSkillByPanelIndex(7)).to.equal(SkillTypes.BASHER);
-    expect(gui.getSkillByPanelIndex(8)).to.equal(SkillTypes.MINER);
-    expect(gui.getSkillByPanelIndex(9)).to.equal(SkillTypes.DIGGER);
-  });
-
   it('renders normal and bench HUD states', function() {
     const display = makeDisplay();
     const miniMap = { renderCalls: 0, render() { this.renderCalls += 1; } };
@@ -344,6 +182,52 @@ describe('GameGui coverage', function() {
     });
   });
 
+  it('draws marching-ants overlays on the dedicated GUI overlay plane when available', function() {
+    const display = makeDisplay();
+    const overlayDisplay = makeDisplay();
+    overlayDisplay.clearCalls = 0;
+    overlayDisplay.clear = function() { this.clearCalls += 1; };
+    display.stage.getGuiOverlayDisplay = () => overlayDisplay;
+    display.stage.setGuiOverlayVisible = (value) => { display.stage.overlayVisible = value; };
+
+    const { gui } = makeGui({ running: false, speedFactor: 1 });
+    gui.setGuiDisplay(display);
+    gui.display = display;
+    gui.backgroundChanged = true;
+    gui.gameTimeChanged = true;
+    gui.nukePrepared = true;
+    gui._hoverPanelIdx = 11;
+    gui._selectionCounter = gui.selectionAnimDelay - 1;
+
+    gui.render();
+
+    expect(overlayDisplay.clearCalls).to.equal(1);
+    expect(overlayDisplay.ants).to.be.greaterThan(0);
+    expect(display.ants).to.equal(0);
+    expect(display.stage.overlayVisible).to.equal(true);
+  });
+
+  it('throttles marching-ant offset updates while paused and idle', function() {
+    const display = makeDisplay();
+    const { gui } = makeGui({ running: false });
+    gui.setGuiDisplay(display);
+    gui.display = display;
+    gui.backgroundChanged = true;
+    gui.gameTimeChanged = true;
+    gui.selectionAnimDelay = 2;
+    gui.selectionAnimIdleMultiplier = 2;
+    gui._selectionOffset = 0;
+    gui._selectionCounter = gui.selectionAnimDelay - 1;
+
+    gui.render();
+    expect(gui._selectionOffset).to.equal(0);
+
+    gui._selectionCounter = (gui.selectionAnimDelay * gui.selectionAnimIdleMultiplier) - 1;
+    gui.gameTimeChanged = true;
+    gui.render();
+    expect(gui._selectionOffset).to.equal(1);
+  });
+
   it('renders status text, speed, and lock variations', function() {
     const display = makeDisplay();
     const { gui, game, skills, timer, victory } = makeGui({ running: true, speedFactor: 12 });
@@ -429,7 +313,7 @@ describe('GameGui coverage', function() {
     expect(miniMap.args).to.eql({ x: 3, w: display.worldDataSize.width });
   });
 
-  it('returns early when display is missing with perf enabled', function() {    
+  it('returns early when display is missing with perf enabled', function() {
     const { gui } = makeGui({ running: true });
     let measured = 0;
     const originalPerformance = globalThis.performance;
@@ -529,24 +413,17 @@ describe('GameGui coverage', function() {
     expect(display.rects.length).to.equal(rectCount);
   });
 
-  it('formats status text and panel names', function() {
-    const { gui } = makeGui();
-    const text = gui._composeStatusText('123456789012345', 'OK');
-    expect(text.length).to.equal(14);
-    expect(gui._getPanelName(2)).to.equal('Climber');
-    expect(gui._getPanelName(99)).to.equal('');
-  });
+  it('renders the tens place with left-digit sprites in speed HUD', function() {
+    const display = makeDisplay();
+    const { gui, timer } = makeGui({ speedFactor: 12, running: true });
+    gui.setGuiDisplay(display);
+    gui.display = display;
+    timer.speedFactor = 12;
+    gui.gameSpeedChanged = true;
+
+    gui.render();
 
-  it('reacts to skill count changes and formats tick indicators', function() {
-    const { gui, skills, timer, game } = makeGui();
-    gui.backgroundChanged = false;
-    skills.onCountChanged.trigger();
-    expect(gui.backgroundChanged).to.equal(true);
-
-    timer.tickIndex = -5;
-    game.timeTravel = { isReversing: true };
-    expect(gui._formatTickIndicator()).to.equal('T0<');
-    expect(gui._getPanelName(0)).to.equal('Decrease');
-    expect(gui._getPanelName(11)).to.equal('Nuke');
+    const hasLeftDigit = display.resized.some((args) => args?.[0]?.id === 'L1');
+    expect(hasLeftDigit).to.equal(true);
   });
 });
diff --git a/test/game-gui.coverage.03-gamegui-coverage.test.js b/test/game-gui.coverage.03-gamegui-coverage.test.js
new file mode 100644
index 00000000..0999ed62
--- /dev/null
+++ b/test/game-gui.coverage.03-gamegui-coverage.test.js
@@ -0,0 +1,223 @@
+import { expect } from 'chai';
+import { EventHandler } from '../js/util/EventHandler.js';
+import { GameGui } from '../js/game/GameGui.js';
+import { SkillTypes } from '../js/game/SkillTypes.js';
+import { CommandNuke } from '../js/commands/CommandNuke.js';
+import { CommandSelectSkill } from '../js/commands/CommandSelectSkill.js';
+import { CommandReleaseRateIncrease } from '../js/commands/CommandReleaseRateIncrease.js';
+import { CommandReleaseRateDecrease } from '../js/commands/CommandReleaseRateDecrease.js';
+import {
+  resetDependencies,
+  setDependency,
+  useGlobalLemmings,
+  withGlobalLemmings
+} from './helpers/lemmings.js';
+
+const makeSprites = () => {
+  const panelSprite = {
+    width: 320,
+    height: 40,
+    getData() { return new Uint8ClampedArray(320 * 40 * 4); }
+  };
+  return {
+    getPanelSprite() { return panelSprite; },
+    getNumberSpriteEmpty() { return { id: 'empty' }; },
+    getNumberSpriteLeft(n) { return { id: `L${n}` }; },
+    getNumberSpriteRight(n) { return { id: `R${n}` }; },
+    getLetterSprite(ch) { return { id: `G${ch}` }; }
+  };
+};
+
+const makeDisplay = () => ({
+  worldDataSize: { width: 320, height: 40 },
+  initCalls: [],
+  backgroundCalls: 0,
+  rects: [],
+  frames: [],
+  covered: [],
+  resized: [],
+  stipples: 0,
+  ants: 0,
+  hlines: 0,
+  pixels: 0,
+  redrawCalls: 0,
+  stage: { updateStageSize() { this.updated = true; } },
+  onMouseDown: new EventHandler(),
+  onMouseUp: new EventHandler(),
+  onMouseRightDown: new EventHandler(),
+  onMouseRightUp: new EventHandler(),
+  onDoubleClick: new EventHandler(),
+  onMouseMove: new EventHandler(),
+  initSize(width, height) {
+    this.initCalls.push({ width, height });
+    this.worldDataSize = { width, height };
+  },
+  setBackground() { this.backgroundCalls += 1; },
+  redraw() { this.redrawCalls += 1; },
+  drawRect(...args) { this.rects.push(args); },
+  drawFrame(frame) { this.frames.push(frame); },
+  drawFrameCovered(frame) { this.covered.push(frame); },
+  drawFrameResized(...args) { this.resized.push(args); },
+  drawStippleRect() { this.stipples += 1; },
+  drawMarchingAntRect() { this.ants += 1; },
+  drawHorizontalLine() { this.hlines += 1; },
+  setPixel() { this.pixels += 1; }
+});
+
+const makeGui = (options = {}) => {
+  const skillCounts = { [SkillTypes.CLIMBER]: 2, [SkillTypes.BASHER]: 1 };
+  let selectedSkill = SkillTypes.UNKNOWN;
+  const skills = {
+    onCountChanged: new EventHandler(),
+    onSelectionChanged: new EventHandler(),
+    getSelectedSkill() { return selectedSkill; },
+    setSelectedSkill(skill) { selectedSkill = skill; },
+    clearSelectedSkill() { selectedSkill = SkillTypes.UNKNOWN; return true; },
+    getSkill(skill) { return skillCounts[skill] || 0; }
+  };
+
+  const timer = {
+    speedFactor: options.speedFactor ?? 1,
+    tickIndex: 5,
+    eachGameSecond: new EventHandler(),
+    isRunning() { return options.running ?? true; },
+    getGameTime() { return 0; },
+    getGameLeftTimeString() { return '1-00'; },
+    getGameLeftTimeSString() { return '1-00'; },
+    toggle() { this.toggled = true; }
+  };
+
+  const victory = {
+    releaseRate: 20,
+    getMinReleaseRate() { return 10; },
+    getCurrentReleaseRate() { return this.releaseRate; },
+    getMaxReleaseRate() { return 99; },
+    setCurrentReleaseRate(val) { this.releaseRate = val; },
+    getReleaseCount() { return 5; },
+    getSurvivorPercentage() { return 50; }
+  };
+
+  const game = {
+    commands: [],
+    queueCommand(cmd) { this.commands.push(cmd); },
+    showDebug: false,
+    gameDisplay: { hoverLemming: null },
+    level: {
+      width: 100,
+      height: 50,
+      mechanics: options.mechanics ?? {},
+      objects: [],
+      getGroundMaskLayer() { return { countMaskInRect() { return 0; } }; }
+    },
+    lemmingManager: { setMiniMap() {} },
+    getLemmingManager() { return { spawnTotal: 5, getLemmings() { return []; } }; }
+  };
+
+  return {
+    gui: new GameGui(game, makeSprites(), skills, timer, victory),
+    game,
+    skills,
+    timer,
+    victory
+  };
+};
+
+describe('GameGui coverage', function() {
+  const originalWindow = globalThis.window;
+
+  const originalPerformance = globalThis.performance;
+
+  useGlobalLemmings({});
+
+  beforeEach(function() {
+    globalThis.window = {
+      requestAnimationFrame() { return 1; },
+      cancelAnimationFrame() {}
+    };
+    globalThis.performance = {
+      now() { return 0; },
+      measure() {}
+    };
+  });
+
+  afterEach(function() {
+    resetDependencies();
+    globalThis.window = originalWindow;
+    globalThis.performance = originalPerformance;
+  });
+
+  it('renders status text safely when victory helpers are missing', function() {
+    const display = makeDisplay();
+    const { gui, game } = makeGui({ running: true });
+    gui.setGuiDisplay(display);
+    gui.display = display;
+    gui.gameTimeChanged = true;
+    gui.backgroundChanged = false;
+    game.gameDisplay = { hoverLemming: null };
+    gui.gameVictoryCondition = {
+      getCurrentReleaseRate() { return 10; },
+      getMinReleaseRate() { return 0; },
+      getMaxReleaseRate() { return 99; }
+    };
+
+    expect(() => gui.render()).to.not.throw();
+  });
+
+  it('skips survivor HUD text when survivor percentage is not finite', function() {
+    const display = makeDisplay();
+    const { gui } = makeGui({ running: true });
+    gui.setGuiDisplay(display);
+    gui.display = display;
+    gui.backgroundChanged = false;
+    gui.gameTimeChanged = true;
+    const drawnText = [];
+    gui.drawGreenString = (_display, text) => {
+      drawnText.push(text);
+    };
+    gui.gameVictoryCondition = {
+      getCurrentReleaseRate() { return 10; },
+      getMinReleaseRate() { return 0; },
+      getMaxReleaseRate() { return 99; },
+      getReleaseCount() { return 5; },
+      getSurvivorPercentage() { return Number.NaN; }
+    };
+
+    gui.render();
+    expect(drawnText.some((text) => text.startsWith('In'))).to.equal(false);
+  });
+
+  it('handles speed flash and dispose safely when no display/window is available', function() {
+    const { gui } = makeGui({ running: true });
+    gui.display = null;
+    expect(() => gui.drawSpeedChange(true)).to.not.throw();
+    expect(gui.gameSpeedChanged).to.equal(true);
+
+    const previousWindow = globalThis.window;
+    globalThis.window = undefined;
+    gui._guiRafId = 7;
+    expect(() => gui.dispose()).to.not.throw();
+    expect(gui._guiRafId).to.equal(0);
+    globalThis.window = previousWindow;
+  });
+
+  it('formats status text and panel names', function() {
+    const { gui } = makeGui();
+    const text = gui._composeStatusText('123456789012345', 'OK');
+    expect(text.length).to.equal(14);
+    expect(gui._getPanelName(2)).to.equal('Climber');
+    expect(gui._getPanelName(99)).to.equal('');
+  });
+
+  it('reacts to skill count changes and formats tick indicators', function() {
+    const { gui, skills, timer, game } = makeGui();
+    gui.backgroundChanged = false;
+    skills.onCountChanged.trigger();
+    expect(gui.backgroundChanged).to.equal(true);
+
+    timer.tickIndex = -5;
+    game.timeTravel = { isReversing: true };
+    expect(gui._formatTickIndicator()).to.equal('T0<');
+    expect(gui._getPanelName(0)).to.equal('Decrease');
+    expect(gui._getPanelName(11)).to.equal('Nuke');
+  });
+});
diff --git a/test/game-timer.bench.test.js b/test/game-timer.bench.test.js
new file mode 100644
index 00000000..ba7b3d3b
--- /dev/null
+++ b/test/game-timer.bench.test.js
@@ -0,0 +1,252 @@
+import { expect } from 'chai';
+import { withConsoleStub } from './helpers/console.js';
+import { setGlobalLemmings, withGlobalLemmings, withMissingGlobalLemmings } from './helpers/lemmings.js';
+import { GameTimer } from '../js/game/GameTimer.js';
+import { COUNTER_LIMIT } from '../js/core/constants.js';
+import { getAppContext, setAppContext } from '../js/core/dependencies.js';
+
+describe('GameTimer bench speed control', function() {
+  let originalWindow;
+
+  let originalDocument;
+
+  let originalPerformance;
+
+  let restoreLemmings;
+
+  let now;
+
+  beforeEach(function() {
+    originalWindow = globalThis.window;
+    originalDocument = globalThis.document;
+    originalPerformance = globalThis.performance;
+    now = 0;
+    globalThis.performance = { now: () => now };
+    restoreLemmings = setGlobalLemmings({ endless: false });
+
+    const listeners = new Map();
+    this.listeners = listeners;
+    globalThis.document = {
+      visibilityState: 'visible',
+      hasFocus() { return true; },
+      addEventListener(type, handler) { listeners.set(type, handler); },
+      removeEventListener(type, handler) {
+        if (listeners.get(type) === handler) listeners.delete(type);
+      }
+    };
+    globalThis.window = {
+      requestAnimationFrame(cb) {
+        globalThis.window._raf = cb;
+        return 1;
+      },
+      cancelAnimationFrame() {},
+      addEventListener(type, handler) { listeners.set(type, handler); },
+      removeEventListener(type, handler) {
+        if (listeners.get(type) === handler) listeners.delete(type);
+      },
+      setTimeout(cb) {
+        cb();
+        return 1;
+      }
+    };
+  });
+
+  afterEach(function() {
+    globalThis.window = originalWindow;
+    globalThis.document = originalDocument;
+    globalThis.performance = originalPerformance;
+    restoreLemmings();
+  });
+
+  it('omits bench overlay rects during bench sequences', function() {
+    const overlayCalls = [];
+    withGlobalLemmings({
+      benchSequence: true,
+      stage: {
+        guiImgProps: { x: 0, y: 0, viewPoint: { scale: 1 } },
+        startOverlayFade(color, rect, dashLen) {
+          overlayCalls.push({ color, rect, dashLen });
+        }
+      }
+    }, () => {
+      const timer = new GameTimer({ timeLimit: 1 });
+      timer.continue();
+
+      now = 1200;
+      globalThis.window._raf(now);
+
+      expect(overlayCalls.length).to.equal(1);
+      expect(overlayCalls[0].rect).to.equal(null);
+    });
+  });
+
+  it('reduces slow bench speeds without drawing overlay rects', function() {
+    const overlayCalls = [];
+    withGlobalLemmings({
+      benchSequence: true,
+      stage: {
+        guiImgProps: { x: 0, y: 0, viewPoint: { scale: 1 } },
+        startOverlayFade(color, rect) {
+          overlayCalls.push({ color, rect });
+        }
+      }
+    }, () => {
+      const timer = new GameTimer({ timeLimit: 1 });
+      timer.speedFactor = 0.9;
+      timer.continue();
+
+      now = 1000;
+      globalThis.window._raf(now);
+
+      expect(timer.speedFactor).to.be.closeTo(0.8, 0.0001);
+      expect(overlayCalls.length).to.equal(1);
+      expect(overlayCalls[0].rect).to.equal(null);
+    });
+  });
+
+  it('bails out of bench speed adjustments when app disappears', function() {
+    const app = {
+      get bench() {
+        globalThis.lemmings = null;
+        return true;
+      },
+      stage: {
+        guiImgProps: { x: 0, y: 0, viewPoint: { scale: 1 } },
+        startOverlayFade() {}
+      }
+    };
+    withGlobalLemmings(app, () => {
+      const timer = new GameTimer({ timeLimit: 1 });
+      timer.continue();
+
+      now = 120;
+      globalThis.window._raf(now);
+
+      expect(globalThis.lemmings).to.equal(null);
+    });
+  });
+
+  it('slows down and restores speed in bench2 catchup mode', function() {
+    withGlobalLemmings({ bench2: true }, () => {
+      const timer = new GameTimer({ timeLimit: 1 });
+      timer.continue();
+
+      now = 600;
+      globalThis.window._raf(now);
+      expect(timer.speedFactor).to.be.lessThan(1);
+
+      now = 1200;
+      globalThis.window._raf(now);
+      expect(timer.speedFactor).to.be.closeTo(1, 0.0001);
+    });
+  });
+
+  it('restores speed after a single catchup step', function() {
+    withGlobalLemmings({ bench2: true }, () => {
+      const timer = new GameTimer({ timeLimit: 1 });
+      timer.continue();
+
+      now = 120;
+      globalThis.window._raf(now);
+      expect(timer.speedFactor).to.be.lessThan(1);
+
+      now = 240;
+      globalThis.window._raf(now);
+      expect(timer.speedFactor).to.equal(1);
+    });
+  });
+
+  it('restores catchup speed when steps return to normal', function() {
+    withGlobalLemmings({ bench2: true }, () => {
+      const timer = new GameTimer({ timeLimit: 1 });
+      timer.speedFactor = 2;
+      timer.continue();
+
+      now = 120;
+      globalThis.window._raf(now);
+      expect(timer.speedFactor).to.be.lessThan(2);
+
+      now = 360;
+      globalThis.window._raf(now);
+      expect(timer.speedFactor).to.equal(2);
+    });
+  });
+
+  it('wraps tickIndex and converts time units', function() {
+    const timer = new GameTimer({ timeLimit: 1 });
+    let warning = null;
+    const restoreConsole = withConsoleStub({ warn: msg => { warning = msg; } });
+    timer.tickIndex = COUNTER_LIMIT;
+    restoreConsole();
+
+    expect(timer.tickIndex).to.equal(0);
+    expect(warning).to.match(/tickIndex wrapped/i);
+
+    timer.tickIndex = 120;
+    expect(timer.getGameTime()).to.be.closeTo(7.2, 0.001);
+    expect(timer.secondsToTicks(2)).to.be.closeTo(33.333333333333336, 0.0001);
+
+    withGlobalLemmings({ endless: true }, () => {
+      expect(timer.ticksToSeconds(1)).to.be.closeTo(2524.14, 0.01);
+    });
+  });
+
+  it('stops and disposes handlers', function() {
+    const timer = new GameTimer({ timeLimit: 1 });
+    timer.onGameTick.on(() => {});
+    timer.onBeforeGameTick.on(() => {});
+    timer.eachGameSecond.on(() => {});
+
+    timer.stop();
+    expect(timer.onGameTick).to.equal(null);
+    expect(timer.onBeforeGameTick).to.equal(null);
+    expect(timer.eachGameSecond).to.equal(null);
+    expect(this.listeners.size).to.equal(0);
+  });
+
+  it('toggles running state and emits each-second events', function() {
+    const timer = new GameTimer({ timeLimit: 1 });
+    let seconds = 0;
+    timer.eachGameSecond.on(() => { seconds += 1; });
+
+    timer.toggle();
+    expect(timer.isRunning()).to.equal(true);
+    timer.tick(1);
+    expect(timer.tickIndex).to.equal(0);
+
+    now = timer.TIME_PER_FRAME_MS * 17;
+    globalThis.window._raf(now);
+
+    expect(seconds).to.equal(1);
+    timer.toggle();
+    expect(timer.isRunning()).to.equal(false);
+  });
+
+  it('emits eachGameSecond from simulated ticks during manual stepping', function() {
+    const timer = new GameTimer({ timeLimit: 1 });
+    const seconds = [];
+    timer.eachGameSecond.on(second => { seconds.push(second); });
+
+    timer.tick(16);
+    expect(seconds).to.eql([]);
+    timer.tick(1);
+    expect(seconds).to.eql([1]);
+    timer.tick(17);
+    expect(seconds).to.eql([1, 2]);
+  });
+
+  it('does not speed up eachGameSecond cadence with speedFactor', function() {
+    const timer = new GameTimer({ timeLimit: 1 });
+    const seconds = [];
+    timer.eachGameSecond.on(second => { seconds.push(second); });
+    timer.speedFactor = 4;
+    timer.continue();
+
+    now = timer.frameTime * 17;
+    globalThis.window._raf(now);
+
+    expect(timer.tickIndex).to.equal(17);
+    expect(seconds).to.eql([1]);
+    timer.suspend();
+  });
+});
diff --git a/test/game-timer.core.test.js b/test/game-timer.core.test.js
new file mode 100644
index 00000000..127ac5e5
--- /dev/null
+++ b/test/game-timer.core.test.js
@@ -0,0 +1,258 @@
+import { expect } from 'chai';
+import { withConsoleStub } from './helpers/console.js';
+import { setGlobalLemmings, withGlobalLemmings, withMissingGlobalLemmings } from './helpers/lemmings.js';
+import { GameTimer } from '../js/game/GameTimer.js';
+import { COUNTER_LIMIT } from '../js/core/constants.js';
+import { getAppContext, setAppContext } from '../js/core/dependencies.js';
+
+describe('GameTimer core loop', function() {
+  let originalWindow;
+
+  let originalDocument;
+
+  let originalPerformance;
+
+  let restoreLemmings;
+
+  let now;
+
+  beforeEach(function() {
+    originalWindow = globalThis.window;
+    originalDocument = globalThis.document;
+    originalPerformance = globalThis.performance;
+    now = 0;
+    globalThis.performance = { now: () => now };
+    restoreLemmings = setGlobalLemmings({ endless: false });
+
+    const listeners = new Map();
+    this.listeners = listeners;
+    globalThis.document = {
+      visibilityState: 'visible',
+      hasFocus() { return true; },
+      addEventListener(type, handler) { listeners.set(type, handler); },
+      removeEventListener(type, handler) {
+        if (listeners.get(type) === handler) listeners.delete(type);
+      }
+    };
+    globalThis.window = {
+      requestAnimationFrame(cb) {
+        globalThis.window._raf = cb;
+        return 1;
+      },
+      cancelAnimationFrame() {},
+      addEventListener(type, handler) { listeners.set(type, handler); },
+      removeEventListener(type, handler) {
+        if (listeners.get(type) === handler) listeners.delete(type);
+      },
+      setTimeout(cb) {
+        cb();
+        return 1;
+      }
+    };
+  });
+
+  afterEach(function() {
+    globalThis.window = originalWindow;
+    globalThis.document = originalDocument;
+    globalThis.performance = originalPerformance;
+    restoreLemmings();
+  });
+
+  it('ticks forward and backward and triggers handlers', function() {
+    const timer = new GameTimer({ timeLimit: 1 });
+    const before = [];
+    const ticks = [];
+    timer.onBeforeGameTick.on(v => before.push(v));
+    timer.onGameTick.on(() => ticks.push(timer.tickIndex));
+
+    timer.tick(2);
+    expect(timer.tickIndex).to.equal(2);
+    expect(before).to.eql([0, 1]);
+    expect(ticks.length).to.equal(2);
+
+    timer.tick(-1);
+    expect(timer.tickIndex).to.equal(1);
+    expect(before).to.eql([0, 1, 1]);
+    expect(ticks.length).to.equal(3);
+
+    timer.tick(-5);
+    expect(timer.tickIndex).to.equal(0);
+    expect(before).to.eql([0, 1, 1, 0]);
+    expect(ticks.length).to.equal(4);
+  });
+
+  it('stores the time travel controller', function() {
+    const timer = new GameTimer({ timeLimit: 1 });
+    const controller = { stepBackward() {} };
+    timer.setTimeTravelController(controller);
+    expect(timer.getTimeTravelController()).to.equal(controller);
+  });
+
+  it('delegates backward ticks to the time travel controller', function() {
+    const timer = new GameTimer({ timeLimit: 1 });
+    const calls = [];
+    const controller = { stepBackward(count) { calls.push(count); } };
+    timer.setTimeTravelController(controller);
+    timer.tick(-3);
+    expect(calls).to.eql([3]);
+  });
+
+  it('formats left time and honors endless mode', function() {
+    const timer = new GameTimer({ timeLimit: 1 });
+    expect(timer.getGameLeftTimeString()).to.equal('1-00');
+
+    timer.tickIndex = timer.ticksTimeLimit + 10;
+    expect(timer.getGameLeftTimeString()).to.equal('0-00');
+
+    withGlobalLemmings({ endless: true }, () => {
+      expect(timer.getGameLeftTimeString()).to.equal('4-20');
+    });
+  });
+
+  it('runs the animation loop and advances ticks', function() {
+    const timer = new GameTimer({ timeLimit: 1 });
+    const ticks = [];
+    timer.onGameTick.on(() => ticks.push(timer.tickIndex));
+
+    timer.continue();
+    expect(typeof globalThis.window._raf).to.equal('function');
+
+    now = 120;
+    globalThis.window._raf(120);
+
+    expect(timer.tickIndex).to.equal(2);
+    expect(ticks.length).to.equal(2);
+    timer.suspend();
+  });
+
+  it('restarts when speedFactor changes while running', function() {
+    const timer = new GameTimer({ timeLimit: 1 });
+    let suspendCalls = 0;
+    let continueCalls = 0;
+    const originalSuspend = timer.suspend.bind(timer);
+    const originalContinue = timer.continue.bind(timer);
+    timer.suspend = () => { suspendCalls++; originalSuspend(); };
+    timer.continue = () => { continueCalls++; originalContinue(); };
+
+    timer.continue();
+    timer.speedFactor = 2;
+
+    expect(timer.speedFactor).to.equal(2);
+    expect(timer.frameTime).to.equal(30);
+    expect(timer.tps).to.be.closeTo(1000 / 30, 0.0001);
+    expect(suspendCalls).to.equal(1);
+    expect(continueCalls).to.equal(2);
+
+    timer.speedFactor = 2;
+    timer.speedFactor = -1;
+    expect(timer.speedFactor).to.equal(2);
+  });
+
+  it('auto-pauses and resumes on visibility changes', function() {
+    const timer = new GameTimer({ timeLimit: 1 });
+    const handler = this.listeners.get('visibilitychange');
+    timer.continue();
+
+    globalThis.document.visibilityState = 'hidden';
+    handler();
+    expect(timer.isRunning()).to.equal(false);
+
+    globalThis.document.visibilityState = 'visible';
+    handler();
+    expect(timer.isRunning()).to.equal(true);
+    timer.suspend();
+  });
+
+  it('skips visibility auto-pause during bench runs', function() {
+    withGlobalLemmings({ bench: true }, () => {
+      const timer = new GameTimer({ timeLimit: 1 });
+      const handler = this.listeners.get('visibilitychange');
+      timer.continue();
+
+      globalThis.document.visibilityState = 'hidden';
+      handler();
+      expect(timer.isRunning()).to.equal(true);
+      timer.suspend();
+    });
+  });
+
+  it('adjusts bench speed and triggers overlay feedback', function() {
+    const overlayCalls = [];
+    withGlobalLemmings({
+      bench: true,
+      stage: {
+        guiImgProps: { x: 0, y: 0, viewPoint: { scale: 1 } },
+        startOverlayFade(color, rect, dashLen) {
+          overlayCalls.push({ color, rect, dashLen });
+        }
+      }
+    }, () => {
+      const timer = new GameTimer({ timeLimit: 1 });
+      timer.continue();
+
+      now = 60 * 200;
+      globalThis.window._raf(now);
+
+      expect(globalThis.lemmings.steps).to.equal(200);
+      expect(timer.speedFactor).to.equal(0.2);
+      expect(overlayCalls.length).to.equal(1);
+      expect(overlayCalls[0].color).to.match(/^rgba\(255,0,0/);
+      expect(overlayCalls[0].rect).to.eql({ x: 160, y: 32, width: 16, height: 10 });
+    });
+  });
+
+  it('reduces bench speeds across multiple thresholds', function() {
+    const overlayCalls = [];
+    withGlobalLemmings({
+      bench: true,
+      stage: {
+        guiImgProps: { x: 0, y: 0, viewPoint: { scale: 1 } },
+        startOverlayFade(color, rect, dashLen) {
+          overlayCalls.push({ color, rect, dashLen });
+        }
+      }
+    }, () => {
+      const timer = new GameTimer({ timeLimit: 1 });
+      timer.continue();
+
+      timer.speedFactor = 70;
+      now = 30;
+      globalThis.window._raf(now);
+      expect(timer.speedFactor).to.equal(60);
+
+      timer.speedFactor = 50;
+      now = 60;
+      globalThis.window._raf(now);
+      expect(timer.speedFactor).to.equal(40);
+
+      timer.speedFactor = 20;
+      now = 93;
+      globalThis.window._raf(now);
+      expect(timer.speedFactor).to.equal(11);
+      expect(overlayCalls.some(call => call.rect)).to.equal(true);
+    });
+  });
+
+  it('reduces low bench speeds in smaller ranges', function() {
+    withGlobalLemmings({
+      bench: true,
+      stage: {
+        guiImgProps: { x: 0, y: 0, viewPoint: { scale: 1 } },
+        startOverlayFade() {}
+      }
+    }, () => {
+      const timer = new GameTimer({ timeLimit: 1 });
+      timer.continue();
+
+      timer.speedFactor = 5;
+      now = 144;
+      globalThis.window._raf(now);
+      expect(timer.speedFactor).to.equal(4);
+
+      timer.speedFactor = 0.5;
+      now = 3000;
+      globalThis.window._raf(now);
+      expect(timer.speedFactor).to.equal(0.4);
+    });
+  });
+});
diff --git a/test/game-timer.runtime.test.js b/test/game-timer.runtime.test.js
new file mode 100644
index 00000000..c38b54b4
--- /dev/null
+++ b/test/game-timer.runtime.test.js
@@ -0,0 +1,263 @@
+import { expect } from 'chai';
+import { withConsoleStub } from './helpers/console.js';
+import { setGlobalLemmings, withGlobalLemmings, withMissingGlobalLemmings } from './helpers/lemmings.js';
+import { GameTimer } from '../js/game/GameTimer.js';
+import { COUNTER_LIMIT } from '../js/core/constants.js';
+import { getAppContext, setAppContext } from '../js/core/dependencies.js';
+
+describe('GameTimer runtime integration', function() {
+  let originalWindow;
+
+  let originalDocument;
+
+  let originalPerformance;
+
+  let restoreLemmings;
+
+  let now;
+
+  beforeEach(function() {
+    originalWindow = globalThis.window;
+    originalDocument = globalThis.document;
+    originalPerformance = globalThis.performance;
+    now = 0;
+    globalThis.performance = { now: () => now };
+    restoreLemmings = setGlobalLemmings({ endless: false });
+
+    const listeners = new Map();
+    this.listeners = listeners;
+    globalThis.document = {
+      visibilityState: 'visible',
+      hasFocus() { return true; },
+      addEventListener(type, handler) { listeners.set(type, handler); },
+      removeEventListener(type, handler) {
+        if (listeners.get(type) === handler) listeners.delete(type);
+      }
+    };
+    globalThis.window = {
+      requestAnimationFrame(cb) {
+        globalThis.window._raf = cb;
+        return 1;
+      },
+      cancelAnimationFrame() {},
+      addEventListener(type, handler) { listeners.set(type, handler); },
+      removeEventListener(type, handler) {
+        if (listeners.get(type) === handler) listeners.delete(type);
+      },
+      setTimeout(cb) {
+        cb();
+        return 1;
+      }
+    };
+  });
+
+  afterEach(function() {
+    globalThis.window = originalWindow;
+    globalThis.document = originalDocument;
+    globalThis.performance = originalPerformance;
+    restoreLemmings();
+  });
+
+  it('uses injected runtime dependencies for browser integration', function() {
+    const calls = [];
+    const runtime = {
+      performance: { now: () => 0 },
+      document: {
+        visibilityState: 'visible',
+        hasFocus() { return true; },
+        addEventListener(type, handler) { calls.push(['doc:add', type, handler]); },
+        removeEventListener(type, handler) { calls.push(['doc:remove', type, handler]); }
+      },
+      window: {
+        requestAnimationFrame(handler) {
+          calls.push(['win:raf', handler]);
+          return 9;
+        },
+        cancelAnimationFrame(id) { calls.push(['win:cancel', id]); },
+        addEventListener(type, handler) { calls.push(['win:add', type, handler]); },
+        removeEventListener(type, handler) { calls.push(['win:remove', type, handler]); }
+      }
+    };
+
+    const timer = new GameTimer({ timeLimit: 1 }, runtime);
+    timer.continue();
+    timer.stop();
+
+    expect(calls.map(call => call[0])).to.include.members([
+      'doc:add',
+      'win:add',
+      'win:raf',
+      'win:cancel',
+      'doc:remove',
+      'win:remove'
+    ]);
+  });
+
+  it('returns early when continuing while already running', function() {
+    const timer = new GameTimer({ timeLimit: 1 });
+    const originalRaf = globalThis.window.requestAnimationFrame;
+    let rafCalls = 0;
+    globalThis.window.requestAnimationFrame = cb => {
+      rafCalls += 1;
+      globalThis.window._raf = cb;
+      return rafCalls;
+    };
+    try {
+      timer.continue();
+      timer.continue();
+      expect(rafCalls).to.equal(1);
+    } finally {
+      timer.suspend();
+      globalThis.window.requestAnimationFrame = originalRaf;
+    }
+  });
+
+  it('returns false and remains stopped when no RAF scheduler is available', function() {
+    const timer = new GameTimer({ timeLimit: 1 }, {
+      performance: { now: () => 0 },
+      window: {
+        addEventListener() {},
+        removeEventListener() {},
+        cancelAnimationFrame() {}
+      },
+      document: {
+        addEventListener() {},
+        removeEventListener() {}
+      }
+    });
+
+    expect(timer.continue()).to.equal(false);
+    expect(timer.isRunning()).to.equal(false);
+    timer.stop();
+  });
+
+  it('does not advance when loop runs while suspended', function() {
+    const timer = new GameTimer({ timeLimit: 1 });
+    timer.continue();
+    timer.suspend();
+    const prev = timer.tickIndex;
+    globalThis.window._raf(120);
+    expect(timer.tickIndex).to.equal(prev);
+  });
+
+  it('handles missing global app references', function() {
+    const timer = new GameTimer({ timeLimit: 1 });
+    withGlobalLemmings(null, () => {
+      expect(timer.ticksToSeconds(1)).to.be.closeTo(0.06, 0.0001);
+    });
+    withMissingGlobalLemmings(() => {
+      expect(timer.ticksToSeconds(2)).to.be.closeTo(0.12, 0.0001);
+    });
+  });
+
+  it('skips bench adjust when app context is missing mid-loop', function() {
+    const timer = new GameTimer({ timeLimit: 1 });
+    const prev = Object.getOwnPropertyDescriptor(globalThis, 'lemmings');
+    const prevApp = getAppContext();
+    setAppContext(null);
+    let access = 0;
+    Object.defineProperty(globalThis, 'lemmings', {
+      configurable: true,
+      get() {
+        access += 1;
+        if (access <= 2) return { bench: true };
+        return null;
+      }
+    });
+    try {
+      timer.continue();
+      now = 120;
+      globalThis.window._raf(now);
+      expect(access).to.equal(0);
+    } finally {
+      if (prev) {
+        Object.defineProperty(globalThis, 'lemmings', prev);
+      } else {
+        delete globalThis.lemmings;
+      }
+      setAppContext(prevApp);
+      timer.suspend();
+    }
+  });
+
+  it('slows down gradually during bench startup', function() {
+    const overlayCalls = [];
+    withGlobalLemmings({
+      bench: true,
+      stage: {
+        guiImgProps: { x: 0, y: 0, viewPoint: { scale: 1 } },
+        startOverlayFade(color, rect, dashLen) {
+          overlayCalls.push({ color, rect, dashLen });
+        }
+      }
+    }, () => {
+      const timer = new GameTimer({ timeLimit: 1 });
+      timer.speedFactor = 2;
+      timer.benchStartupFrames = 5;
+      timer.benchStableFactor = 2;
+      timer.continue();
+
+      now = timer.frameTime * 12;
+      globalThis.window._raf(now);
+
+      expect(timer.speedFactor).to.equal(1);
+      expect(overlayCalls[0].color).to.match(/^rgba\(255,0,0/);
+    });
+  });
+
+  it('reduces sub-1.0 bench speeds when overloaded', function() {
+    withGlobalLemmings({ bench: true }, () => {
+      const timer = new GameTimer({ timeLimit: 1 });
+      timer.speedFactor = 0.5;
+      timer.continue();
+
+      now = timer.frameTime * 30;
+      globalThis.window._raf(now);
+
+      expect(timer.speedFactor).to.be.closeTo(0.4, 0.0001);
+    });
+  });
+
+  it('recovers speed after extended stability', function() {
+    const overlayCalls = [];
+    withGlobalLemmings({
+      bench: true,
+      stage: {
+        guiImgProps: { x: 0, y: 0, viewPoint: { scale: 1 } },
+        startOverlayFade(color) {
+          overlayCalls.push(color);
+        }
+      }
+    }, () => {
+      const timer = new GameTimer({ timeLimit: 1 });
+      timer.speedFactor = 8;
+      timer.continue();
+      const frame = timer.frameTime;
+      for (let i = 1; i <= 33; i++) {
+        now = frame * i;
+        globalThis.window._raf(now);
+      }
+      expect(timer.speedFactor).to.equal(9);
+      expect(overlayCalls.some(color => color.startsWith('rgba(0,255,0'))).to.equal(true);
+    });
+  });
+
+  it('nudges very slow bench speeds upward', function() {
+    withGlobalLemmings({ bench: true }, () => {
+      const timer = new GameTimer({ timeLimit: 1 });
+      timer.speedFactor = 0.5;
+      timer.continue();
+      for (let i = 1; i <= 3; i++) {
+        now = timer.frameTime * i;
+        globalThis.window._raf(now);
+      }
+      expect(timer.speedFactor).to.be.closeTo(0.6, 0.0001);
+    });
+  });
+
+  it('exposes game tick count', function() {
+    const timer = new GameTimer({ timeLimit: 1 });
+    timer.tick(3);
+    expect(timer.getGameTicks()).to.equal(3);
+  });
+});
diff --git a/test/game-timer.test.js b/test/game-timer.test.js
deleted file mode 100644
index 6d586bb5..00000000
--- a/test/game-timer.test.js
+++ /dev/null
@@ -1,565 +0,0 @@
-import { expect } from 'chai';
-import { withConsoleStub } from './helpers/console.js';
-import { setGlobalLemmings, withGlobalLemmings, withMissingGlobalLemmings } from './helpers/lemmings.js';
-import { GameTimer } from '../js/game/GameTimer.js';
-import { COUNTER_LIMIT } from '../js/core/constants.js';
-
-describe('GameTimer', function() {
-  let originalWindow;
-  let originalDocument;
-  let originalPerformance;
-  let restoreLemmings;
-  let now;
-
-  beforeEach(function() {
-    originalWindow = globalThis.window;
-    originalDocument = globalThis.document;
-    originalPerformance = globalThis.performance;
-    now = 0;
-    globalThis.performance = { now: () => now };
-    restoreLemmings = setGlobalLemmings({ endless: false });
-
-    const listeners = new Map();
-    this.listeners = listeners;
-    globalThis.document = {
-      visibilityState: 'visible',
-      hasFocus() { return true; },
-      addEventListener(type, handler) { listeners.set(type, handler); },
-      removeEventListener(type, handler) {
-        if (listeners.get(type) === handler) listeners.delete(type);
-      }
-    };
-    globalThis.window = {
-      requestAnimationFrame(cb) {
-        globalThis.window._raf = cb;
-        return 1;
-      },
-      cancelAnimationFrame() {},
-      addEventListener(type, handler) { listeners.set(type, handler); },
-      removeEventListener(type, handler) {
-        if (listeners.get(type) === handler) listeners.delete(type);
-      },
-      setTimeout(cb) {
-        cb();
-        return 1;
-      }
-    };
-  });
-
-  afterEach(function() {
-    globalThis.window = originalWindow;
-    globalThis.document = originalDocument;
-    globalThis.performance = originalPerformance;
-    restoreLemmings();
-  });
-
-  it('ticks forward and backward and triggers handlers', function() {
-    const timer = new GameTimer({ timeLimit: 1 });
-    const before = [];
-    const ticks = [];
-    timer.onBeforeGameTick.on(v => before.push(v));
-    timer.onGameTick.on(() => ticks.push(timer.tickIndex));
-
-    timer.tick(2);
-    expect(timer.tickIndex).to.equal(2);
-    expect(before).to.eql([0, 1]);
-    expect(ticks.length).to.equal(2);
-
-    timer.tick(-1);
-    expect(timer.tickIndex).to.equal(1);
-    expect(before).to.eql([0, 1, 1]);
-    expect(ticks.length).to.equal(3);
-
-    timer.tick(-5);
-    expect(timer.tickIndex).to.equal(0);
-    expect(before).to.eql([0, 1, 1, 0]);
-    expect(ticks.length).to.equal(4);
-  });
-
-  it('stores the time travel controller', function() {
-    const timer = new GameTimer({ timeLimit: 1 });
-    const controller = { stepBackward() {} };
-    timer.setTimeTravelController(controller);
-    expect(timer.getTimeTravelController()).to.equal(controller);
-  });
-
-  it('delegates backward ticks to the time travel controller', function() {
-    const timer = new GameTimer({ timeLimit: 1 });
-    const calls = [];
-    const controller = { stepBackward(count) { calls.push(count); } };
-    timer.setTimeTravelController(controller);
-    timer.tick(-3);
-    expect(calls).to.eql([3]);
-  });
-
-  it('formats left time and honors endless mode', function() {
-    const timer = new GameTimer({ timeLimit: 1 });
-    expect(timer.getGameLeftTimeString()).to.equal('1-00');
-
-    timer.tickIndex = timer.ticksTimeLimit + 10;
-    expect(timer.getGameLeftTimeString()).to.equal('0-00');
-
-    withGlobalLemmings({ endless: true }, () => {
-      expect(timer.getGameLeftTimeString()).to.equal('4-20');
-    });
-  });
-
-  it('runs the animation loop and advances ticks', function() {
-    const timer = new GameTimer({ timeLimit: 1 });
-    const ticks = [];
-    timer.onGameTick.on(() => ticks.push(timer.tickIndex));
-
-    timer.continue();
-    expect(typeof globalThis.window._raf).to.equal('function');
-
-    now = 120;
-    globalThis.window._raf(120);
-
-    expect(timer.tickIndex).to.equal(2);
-    expect(ticks.length).to.equal(2);
-    timer.suspend();
-  });
-
-  it('restarts when speedFactor changes while running', function() {
-    const timer = new GameTimer({ timeLimit: 1 });
-    let suspendCalls = 0;
-    let continueCalls = 0;
-    const originalSuspend = timer.suspend.bind(timer);
-    const originalContinue = timer.continue.bind(timer);
-    timer.suspend = () => { suspendCalls++; originalSuspend(); };
-    timer.continue = () => { continueCalls++; originalContinue(); };
-
-    timer.continue();
-    timer.speedFactor = 2;
-
-    expect(timer.speedFactor).to.equal(2);
-    expect(timer.frameTime).to.equal(30);
-    expect(timer.tps).to.be.closeTo(1000 / 30, 0.0001);
-    expect(suspendCalls).to.equal(1);
-    expect(continueCalls).to.equal(2);
-
-    timer.speedFactor = 2;
-    timer.speedFactor = -1;
-    expect(timer.speedFactor).to.equal(2);
-  });
-
-  it('auto-pauses and resumes on visibility changes', function() {
-    const timer = new GameTimer({ timeLimit: 1 });
-    const handler = this.listeners.get('visibilitychange');
-    timer.continue();
-
-    globalThis.document.visibilityState = 'hidden';
-    handler();
-    expect(timer.isRunning()).to.equal(false);
-
-    globalThis.document.visibilityState = 'visible';
-    handler();
-    expect(timer.isRunning()).to.equal(true);
-    timer.suspend();
-  });
-
-  it('skips visibility auto-pause during bench runs', function() {
-    withGlobalLemmings({ bench: true }, () => {
-      const timer = new GameTimer({ timeLimit: 1 });
-      const handler = this.listeners.get('visibilitychange');
-      timer.continue();
-
-      globalThis.document.visibilityState = 'hidden';
-      handler();
-      expect(timer.isRunning()).to.equal(true);
-      timer.suspend();
-    });
-  });
-
-  it('adjusts bench speed and triggers overlay feedback', function() {
-    const overlayCalls = [];
-    withGlobalLemmings({
-      bench: true,
-      stage: {
-        guiImgProps: { x: 0, y: 0, viewPoint: { scale: 1 } },
-        startOverlayFade(color, rect, dashLen) {
-          overlayCalls.push({ color, rect, dashLen });
-        }
-      }
-    }, () => {
-      const timer = new GameTimer({ timeLimit: 1 });
-      timer.continue();
-
-      now = 60 * 200;
-      globalThis.window._raf(now);
-
-      expect(globalThis.lemmings.steps).to.equal(200);
-      expect(timer.speedFactor).to.equal(0.1);
-      expect(overlayCalls.length).to.equal(1);
-      expect(overlayCalls[0].color).to.match(/^rgba\(255,0,0/);
-      expect(overlayCalls[0].rect).to.eql({ x: 160, y: 32, width: 16, height: 10 });
-    });
-  });
-
-  it('reduces bench speeds across multiple thresholds', function() {
-    const overlayCalls = [];
-    withGlobalLemmings({
-      bench: true,
-      stage: {
-        guiImgProps: { x: 0, y: 0, viewPoint: { scale: 1 } },
-        startOverlayFade(color, rect, dashLen) {
-          overlayCalls.push({ color, rect, dashLen });
-        }
-      }
-    }, () => {
-      const timer = new GameTimer({ timeLimit: 1 });
-      timer.continue();
-
-      timer.speedFactor = 70;
-      now = 30;
-      globalThis.window._raf(now);
-      expect(timer.speedFactor).to.equal(60);
-
-      timer.speedFactor = 50;
-      now = 60;
-      globalThis.window._raf(now);
-      expect(timer.speedFactor).to.equal(40);
-
-      timer.speedFactor = 20;
-      now = 93;
-      globalThis.window._raf(now);
-      expect(timer.speedFactor).to.equal(11);
-      expect(overlayCalls.some(call => call.rect)).to.equal(true);
-    });
-  });
-
-  it('reduces low bench speeds in smaller ranges', function() {
-    withGlobalLemmings({
-      bench: true,
-      stage: {
-        guiImgProps: { x: 0, y: 0, viewPoint: { scale: 1 } },
-        startOverlayFade() {}
-      }
-    }, () => {
-      const timer = new GameTimer({ timeLimit: 1 });
-      timer.continue();
-
-      timer.speedFactor = 5;
-      now = 144;
-      globalThis.window._raf(now);
-      expect(timer.speedFactor).to.equal(4);
-
-      timer.speedFactor = 0.5;
-      now = 3000;
-      globalThis.window._raf(now);
-      expect(timer.speedFactor).to.equal(0.4);
-    });
-  });
-
-  it('omits bench overlay rects during bench sequences', function() {
-    const overlayCalls = [];
-    withGlobalLemmings({
-      benchSequence: true,
-      stage: {
-        guiImgProps: { x: 0, y: 0, viewPoint: { scale: 1 } },
-        startOverlayFade(color, rect, dashLen) {
-          overlayCalls.push({ color, rect, dashLen });
-        }
-      }
-    }, () => {
-      const timer = new GameTimer({ timeLimit: 1 });
-      timer.continue();
-
-      now = 1200;
-      globalThis.window._raf(now);
-
-      expect(overlayCalls.length).to.equal(1);
-      expect(overlayCalls[0].rect).to.equal(null);
-    });
-  });
-
-  it('reduces slow bench speeds without drawing overlay rects', function() {
-    const overlayCalls = [];
-    withGlobalLemmings({
-      benchSequence: true,
-      stage: {
-        guiImgProps: { x: 0, y: 0, viewPoint: { scale: 1 } },
-        startOverlayFade(color, rect) {
-          overlayCalls.push({ color, rect });
-        }
-      }
-    }, () => {
-      const timer = new GameTimer({ timeLimit: 1 });
-      timer.speedFactor = 0.9;
-      timer.continue();
-
-      now = 1000;
-      globalThis.window._raf(now);
-
-      expect(timer.speedFactor).to.be.closeTo(0.8, 0.0001);
-      expect(overlayCalls.length).to.equal(1);
-      expect(overlayCalls[0].rect).to.equal(null);
-    });
-  });
-
-  it('bails out of bench speed adjustments when app disappears', function() {
-    const app = {
-      get bench() {
-        globalThis.lemmings = null;
-        return true;
-      },
-      stage: {
-        guiImgProps: { x: 0, y: 0, viewPoint: { scale: 1 } },
-        startOverlayFade() {}
-      }
-    };
-    withGlobalLemmings(app, () => {
-      const timer = new GameTimer({ timeLimit: 1 });
-      timer.continue();
-
-      now = 120;
-      globalThis.window._raf(now);
-
-      expect(globalThis.lemmings).to.equal(null);
-    });
-  });
-
-  it('slows down and restores speed in bench2 catchup mode', function() {  
-    withGlobalLemmings({ bench2: true }, () => {
-      const timer = new GameTimer({ timeLimit: 1 });
-      timer.continue();
-
-      now = 600;
-      globalThis.window._raf(now);
-      expect(timer.speedFactor).to.be.lessThan(1);
-
-      now = 1200;
-      globalThis.window._raf(now);
-      expect(timer.speedFactor).to.be.closeTo(1, 0.0001);
-    });
-  });
-
-  it('restores speed after a single catchup step', function() {
-    withGlobalLemmings({ bench2: true }, () => {
-      const timer = new GameTimer({ timeLimit: 1 });
-      timer.continue();
-
-      now = 120;
-      globalThis.window._raf(now);
-      expect(timer.speedFactor).to.be.lessThan(1);
-
-      now = 240;
-      globalThis.window._raf(now);
-      expect(timer.speedFactor).to.equal(1);
-    });
-  });
-
-  it('restores catchup speed when steps return to normal', function() {
-    withGlobalLemmings({ bench2: true }, () => {
-      const timer = new GameTimer({ timeLimit: 1 });
-      timer.speedFactor = 2;
-      timer.continue();
-
-      now = 120;
-      globalThis.window._raf(now);
-      expect(timer.speedFactor).to.be.lessThan(2);
-
-      now = 360;
-      globalThis.window._raf(now);
-      expect(timer.speedFactor).to.equal(2);
-    });
-  });
-
-  it('wraps tickIndex and converts time units', function() {
-    const timer = new GameTimer({ timeLimit: 1 });
-    let warning = null;
-    const restoreConsole = withConsoleStub({ warn: msg => { warning = msg; } });
-    timer.tickIndex = COUNTER_LIMIT;
-    restoreConsole();
-
-    expect(timer.tickIndex).to.equal(0);
-    expect(warning).to.match(/tickIndex wrapped/i);
-
-    timer.tickIndex = 120;
-    expect(timer.getGameTime()).to.be.closeTo(7.2, 0.001);
-    expect(timer.secondsToTicks(2)).to.be.closeTo(33.333333333333336, 0.0001);
-
-    withGlobalLemmings({ endless: true }, () => {
-      expect(timer.ticksToSeconds(1)).to.be.closeTo(2524.14, 0.01);
-    });
-  });
-
-  it('stops and disposes handlers', function() {
-    const timer = new GameTimer({ timeLimit: 1 });
-    timer.onGameTick.on(() => {});
-    timer.onBeforeGameTick.on(() => {});
-    timer.eachGameSecond.on(() => {});
-
-    timer.stop();
-    expect(timer.onGameTick).to.equal(null);
-    expect(timer.onBeforeGameTick).to.equal(null);
-    expect(timer.eachGameSecond).to.equal(null);
-    expect(this.listeners.size).to.equal(0);
-  });
-
-  it('toggles running state and emits each-second events', function() {
-    const timer = new GameTimer({ timeLimit: 1 });
-    let seconds = 0;
-    timer.eachGameSecond.on(() => { seconds += 1; });
-
-    timer.toggle();
-    expect(timer.isRunning()).to.equal(true);
-    timer.tick(1);
-    expect(timer.tickIndex).to.equal(0);
-
-    now = 120;
-    globalThis.window._raf(now);
-    now = 180;
-    globalThis.window._raf(now);
-
-    expect(seconds).to.equal(1);
-    timer.toggle();
-    expect(timer.isRunning()).to.equal(false);
-  });
-
-  it('returns early when continuing while already running', function() {
-    const timer = new GameTimer({ timeLimit: 1 });
-    const originalRaf = globalThis.window.requestAnimationFrame;
-    let rafCalls = 0;
-    globalThis.window.requestAnimationFrame = cb => {
-      rafCalls += 1;
-      globalThis.window._raf = cb;
-      return rafCalls;
-    };
-    try {
-      timer.continue();
-      timer.continue();
-      expect(rafCalls).to.equal(1);
-    } finally {
-      timer.suspend();
-      globalThis.window.requestAnimationFrame = originalRaf;
-    }
-  });
-
-  it('does not advance when loop runs while suspended', function() {
-    const timer = new GameTimer({ timeLimit: 1 });
-    timer.continue();
-    timer.suspend();
-    const prev = timer.tickIndex;
-    globalThis.window._raf(120);
-    expect(timer.tickIndex).to.equal(prev);
-  });
-
-  it('handles missing global app references', function() {
-    const timer = new GameTimer({ timeLimit: 1 });
-    withGlobalLemmings(null, () => {
-      expect(timer.ticksToSeconds(1)).to.be.closeTo(0.06, 0.0001);
-    });
-    withMissingGlobalLemmings(() => {
-      expect(timer.ticksToSeconds(2)).to.be.closeTo(0.12, 0.0001);
-    });
-  });
-
-  it('skips bench adjust when app vanishes mid-loop', function() {
-    const timer = new GameTimer({ timeLimit: 1 });
-    const prev = Object.getOwnPropertyDescriptor(globalThis, 'lemmings');
-    let access = 0;
-    Object.defineProperty(globalThis, 'lemmings', {
-      configurable: true,
-      get() {
-        access += 1;
-        if (access <= 2) return { bench: true };
-        return null;
-      }
-    });
-    try {
-      timer.continue();
-      now = 120;
-      globalThis.window._raf(now);
-      expect(access).to.be.greaterThan(1);
-    } finally {
-      if (prev) {
-        Object.defineProperty(globalThis, 'lemmings', prev);
-      } else {
-        delete globalThis.lemmings;
-      }
-      timer.suspend();
-    }
-  });
-
-  it('slows down gradually during bench startup', function() {
-    const overlayCalls = [];
-    withGlobalLemmings({
-      bench: true,
-      stage: {
-        guiImgProps: { x: 0, y: 0, viewPoint: { scale: 1 } },
-        startOverlayFade(color, rect, dashLen) {
-          overlayCalls.push({ color, rect, dashLen });
-        }
-      }
-    }, () => {
-      const timer = new GameTimer({ timeLimit: 1 });
-      timer.speedFactor = 2;
-      timer.benchStartupFrames = 5;
-      timer.benchStableFactor = 2;
-      timer.continue();
-
-      now = timer.frameTime * 12;
-      globalThis.window._raf(now);
-
-      expect(timer.speedFactor).to.equal(1);
-      expect(overlayCalls[0].color).to.match(/^rgba\(255,0,0/);
-    });
-  });
-
-  it('reduces sub-1.0 bench speeds when overloaded', function() {
-    withGlobalLemmings({ bench: true }, () => {
-      const timer = new GameTimer({ timeLimit: 1 });
-      timer.speedFactor = 0.5;
-      timer.continue();
-
-      now = timer.frameTime * 30;
-      globalThis.window._raf(now);
-
-      expect(timer.speedFactor).to.be.closeTo(0.4, 0.0001);
-    });
-  });
-
-  it('recovers speed after extended stability', function() {
-    const overlayCalls = [];
-    withGlobalLemmings({
-      bench: true,
-      stage: {
-        guiImgProps: { x: 0, y: 0, viewPoint: { scale: 1 } },
-        startOverlayFade(color) {
-          overlayCalls.push(color);
-        }
-      }
-    }, () => {
-      const timer = new GameTimer({ timeLimit: 1 });
-      timer.speedFactor = 8;
-      timer.continue();
-      const frame = timer.frameTime;
-      for (let i = 1; i <= 33; i++) {
-        now = frame * i;
-        globalThis.window._raf(now);
-      }
-      expect(timer.speedFactor).to.equal(9);
-      expect(overlayCalls.some(color => color.startsWith('rgba(0,255,0'))).to.equal(true);
-    });
-  });
-
-  it('nudges very slow bench speeds upward', function() {
-    withGlobalLemmings({ bench: true }, () => {
-      const timer = new GameTimer({ timeLimit: 1 });
-      timer.speedFactor = 0.5;
-      timer.continue();
-      for (let i = 1; i <= 3; i++) {
-        now = timer.frameTime * i;
-        globalThis.window._raf(now);
-      }
-      expect(timer.speedFactor).to.be.closeTo(0.6, 0.0001);
-    });
-  });
-
-  it('exposes game tick count', function() {
-    const timer = new GameTimer({ timeLimit: 1 });
-    timer.tick(3);
-    expect(timer.getGameTicks()).to.equal(3);
-  });
-});
diff --git a/test/game.test.js b/test/game.test.js
index b7139cf0..4c749713 100644
--- a/test/game.test.js
+++ b/test/game.test.js
@@ -66,7 +66,13 @@ describe('Game', function() {
     });
 
     setDependency('TriggerManager', class {
-      constructor(timer) { this.timer = timer; this.disposed = false; this.added = null; }
+      constructor(timer, levelW, levelH) {
+        this.timer = timer;
+        this.levelW = levelW;
+        this.levelH = levelH;
+        this.disposed = false;
+        this.added = null;
+      }
       addRange(arr) { this.added = arr; }
       dispose() { this.disposed = true; }
     });
@@ -86,7 +92,7 @@ describe('Game', function() {
     setDependency('GameGui', class {
       constructor() { this.renderCalled = 0; this.setDisplay = null; this.disposed = false; }
       setGuiDisplay(d) { this.setDisplay = d; }
-      render() { this.renderCalled++; }
+      render() { this.renderCalled++; return true; }
       dispose() { this.disposed = true; }
     });
 
@@ -106,7 +112,7 @@ describe('Game', function() {
     Object.entries(originals).forEach(([k,v]) => { Lemmings[k] = v; });
   });
 
-  it('loadLevel initializes managers and returns itself', async function() {
+  it('loadLevel initializes managers', async function() {
     const res = new Lemmings.GameResources();
     const game = new Game(res);
     const ret = await game.loadLevel(0, 1);
@@ -119,6 +125,23 @@ describe('Game', function() {
     expect(game.gameDisplay).to.be.instanceOf(Lemmings.GameDisplay);
   });
 
+  it('passes loaded level dimensions into TriggerManager', async function() {
+    const level = {
+      timeLimit: 5,
+      colorPalette: 0,
+      width: 2048,
+      height: 256,
+      triggers: [],
+      objects: [],
+      screenPositionX: 0
+    };
+    const game = new Game(new Lemmings.GameResources());
+    await game.loadCustomLevel(level);
+
+    expect(game.triggerManager.levelW).to.equal(2048);
+    expect(game.triggerManager.levelH).to.equal(256);
+  });
+
   it('loadCustomLevel returns null without a level', async function() {
     const res = new Lemmings.GameResources();
     const game = new Game(res);
@@ -126,6 +149,27 @@ describe('Game', function() {
     expect(ret).to.equal(null);
   });
 
+  it('loadLevel closes performance measures when loading fails', async function() {
+    const res = new Lemmings.GameResources();
+    const game = new Game(res);
+    let endMeasureCalls = 0;
+    game.startMeasure = () => () => {
+      endMeasureCalls += 1;
+    };
+    res.getLevel = async () => {
+      throw new Error('load failed');
+    };
+    let thrown = null;
+    try {
+      await game.loadLevel(0, 0);
+    } catch (error) {
+      thrown = error;
+    }
+
+    expect(thrown).to.be.instanceOf(Error);
+    expect(endMeasureCalls).to.equal(1);
+  });
+
   it('loadCustomLevel initializes managers and returns itself', async function() {
     const res = new Lemmings.GameResources();
     const game = new Game(res);
@@ -241,19 +285,19 @@ describe('Game', function() {
     expect(game.getGameState()).to.equal(Lemmings.GameStateTypes.FAILED_OUT_OF_TIME);
   });
 
-  it('getGameState returns RUNNING when bench mode is enabled', function() {    
+  it('getGameState returns RUNNING when bench mode is enabled', function() {
     const res = new Lemmings.GameResources();
     const game = new Game(res);
     withGlobalLemmings({ bench: true }, () => {
-      expect(game.getGameState()).to.equal(Lemmings.GameStateTypes.RUNNING);    
+      expect(game.getGameState()).to.equal(Lemmings.GameStateTypes.RUNNING);
     });
   });
 
-  it('getGameState returns RUNNING when benchReverse is enabled', function() {  
+  it('getGameState returns RUNNING when benchReverse is enabled', function() {
     const res = new Lemmings.GameResources();
     const game = new Game(res);
     withGlobalLemmings({ benchReverse: true }, () => {
-      expect(game.getGameState()).to.equal(Lemmings.GameStateTypes.RUNNING);    
+      expect(game.getGameState()).to.equal(Lemmings.GameStateTypes.RUNNING);
     });
   });
 
@@ -341,7 +385,7 @@ describe('Game', function() {
     game.onGameEnd.on(() => { ended++; });
     game.checkForGameOver();
     expect(game.gameVictoryCondition.finalizeCalled).to.equal(1);
-    expect(game.finalGameState).to.equal(Lemmings.GameStateTypes.SUCCEEDED);    
+    expect(game.finalGameState).to.equal(Lemmings.GameStateTypes.SUCCEEDED);
     expect(ended).to.equal(1);
   });
 
@@ -349,11 +393,11 @@ describe('Game', function() {
     const res = new Lemmings.GameResources();
     const game = new Game(res);
     withGlobalLemmings({ endless: true }, () => {
-      expect(game.getGameState()).to.equal(Lemmings.GameStateTypes.RUNNING);    
+      expect(game.getGameState()).to.equal(Lemmings.GameStateTypes.RUNNING);
     });
   });
 
-  it('getGameState returns failed out of time when needed', function() {        
+  it('getGameState returns failed out of time when needed', function() {
     const res = new Lemmings.GameResources();
     const game = new Game(res);
     game.gameTimer = { getGameLeftTime: () => 0 };
diff --git a/test/gamefactory.resources.test.js b/test/gamefactory.resources.test.js
index 1cbddb01..f0038860 100644
--- a/test/gamefactory.resources.test.js
+++ b/test/gamefactory.resources.test.js
@@ -1,6 +1,7 @@
 import { expect } from 'chai';
-import { Lemmings, setDependency, setGlobalLemmings, useGlobalLemmings } from './helpers/lemmings.js';
+import { setGlobalLemmings, useGlobalLemmings } from './helpers/lemmings.js';
 import { GameFactory } from '../js/game/GameFactory.js';
+import { applyDependencyOverrides } from './support/deps.js';
 
 useGlobalLemmings({ game: { showDebug: false } });
 
@@ -17,19 +18,6 @@ const makeConfigReaderStub = (getConfig) => class ConfigReaderStub {
   }
 };
 
-const applyDeps = (overrides) => {
-  const originals = {};
-  for (const [key, value] of Object.entries(overrides)) {
-    originals[key] = Lemmings[key];
-    setDependency(key, value);
-  }
-  return () => {
-    for (const [key, value] of Object.entries(originals)) {
-      setDependency(key, value);
-    }
-  };
-};
-
 const withPerfStub = async (perf, lemmings, fn) => {
   const origPerf = globalThis.performance;
   globalThis.performance = perf;
@@ -43,6 +31,10 @@ const withPerfStub = async (perf, lemmings, fn) => {
 };
 
 describe('GameFactory resource helpers', function () {
+  afterEach(function () {
+    delete globalThis.__LEMMINGS_RUNTIME_REVISION__;
+  });
+
   it('loads config and resources and builds Game', async function () {
     const mockConfig = { path: 'data', level: {} };
     const ConfigReaderStub = makeConfigReaderStub(() => mockConfig);
@@ -53,7 +45,7 @@ describe('GameFactory resource helpers', function () {
     class GameStub {
       constructor(res) { this.res = res; }
     }
-    const restore = applyDeps({
+    const restore = applyDependencyOverrides({
       FileProvider: FileProviderStub,
       ConfigReader: ConfigReaderStub,
       GameResources: GameResourcesStub,
@@ -89,7 +81,7 @@ describe('GameFactory resource helpers', function () {
     class GameStub {
       constructor(res) { this.res = res; }
     }
-    const restore = applyDeps({
+    const restore = applyDependencyOverrides({
       FileProvider: FileProviderStub,
       ConfigReader: ConfigReaderStub,
       GameResources: GameResourcesStub,
@@ -110,7 +102,7 @@ describe('GameFactory resource helpers', function () {
 
   it('rejects when config is missing', async function () {
     const ConfigReaderStub = makeConfigReaderStub(() => null);
-    const restore = applyDeps({
+    const restore = applyDependencyOverrides({
       FileProvider: FileProviderStub,
       ConfigReader: ConfigReaderStub
     });
@@ -134,7 +126,7 @@ describe('GameFactory resource helpers', function () {
     const ConfigReaderStub = makeConfigReaderStub(() => ({ path: 'data', level: {} }));
     class GameResourcesStub {}
     class GameStub {}
-    const restore = applyDeps({
+    const restore = applyDependencyOverrides({
       FileProvider: FileProviderStub,
       ConfigReader: ConfigReaderStub,
       GameResources: GameResourcesStub,
@@ -159,7 +151,7 @@ describe('GameFactory resource helpers', function () {
     const ConfigReaderStub = makeConfigReaderStub(() => ({ path: 'data', level: {} }));
     class GameResourcesStub {}
     class GameStub {}
-    const restore = applyDeps({
+    const restore = applyDependencyOverrides({
       FileProvider: FileProviderStub,
       ConfigReader: ConfigReaderStub,
       GameResources: GameResourcesStub,
@@ -176,4 +168,33 @@ describe('GameFactory resource helpers', function () {
     );
     restore();
   });
+
+  it('passes runtime cache-bust revision to FileProvider', async function () {
+    class CapturingFileProvider {
+      constructor(root, options) {
+        this.root = root;
+        this.options = options || {};
+      }
+      loadString() {
+        return Promise.resolve('[]');
+      }
+    }
+    const restore = applyDependencyOverrides({
+      FileProvider: CapturingFileProvider,
+      ConfigReader: makeConfigReaderStub(() => ({ path: 'data', level: {} }))
+    });
+    const previousLocation = globalThis.location;
+    globalThis.location = { search: '?rev=phase30a' };
+    try {
+      const gf = new GameFactory('root');
+      expect(gf.fileProvider.options.cacheBustRevision).to.equal('phase30a');
+    } finally {
+      if (previousLocation === undefined) {
+        delete globalThis.location;
+      } else {
+        globalThis.location = previousLocation;
+      }
+      restore();
+    }
+  });
 });
diff --git a/test/gamefactory.test.js b/test/gamefactory.test.js
index 79b6328b..1ab3911b 100644
--- a/test/gamefactory.test.js
+++ b/test/gamefactory.test.js
@@ -1,22 +1,10 @@
 import { expect } from 'chai';
-import { Lemmings, setDependency, useGlobalLemmings } from './helpers/lemmings.js';
+import { useGlobalLemmings } from './helpers/lemmings.js';
 import { GameFactory } from '../js/game/GameFactory.js';
+import { applyDependencyOverrides } from './support/deps.js';
 
 useGlobalLemmings({ game: { showDebug: false } });
 
-const applyDeps = (overrides) => {
-  const originals = {};
-  for (const [key, value] of Object.entries(overrides)) {
-    originals[key] = Lemmings[key];
-    setDependency(key, value);
-  }
-  return () => {
-    for (const [key, value] of Object.entries(originals)) {
-      setDependency(key, value);
-    }
-  };
-};
-
 describe('GameFactory.createFromConfig', function () {
   it('builds a Game with GameResources and timer', async function () {
     class FileProviderStub {
@@ -39,12 +27,12 @@ describe('GameFactory.createFromConfig', function () {
       constructor(res) { this.res = res; this.loadArgs = []; this.gameTimer = null; }
       async loadLevel(g, i) {
         this.loadArgs = [g, i];
-        this.gameTimer = new Lemmings.GameTimer({});
+        this.gameTimer = new GameTimerStub({});
         return this;
       }
     }
 
-    const restore = applyDeps({
+    const restore = applyDependencyOverrides({
       FileProvider: FileProviderStub,
       ConfigReader: ConfigReaderStub,
       GameResources: GameResourcesStub,
diff --git a/test/gameview.benchreverse.test.js b/test/gameview.benchreverse.test.js
index 11bf01c9..42982c6f 100644
--- a/test/gameview.benchreverse.test.js
+++ b/test/gameview.benchreverse.test.js
@@ -35,4 +35,15 @@ describe('GameView benchReverse flags', function() {
     expect(view.bench2).to.equal(true);
     expect(view.benchSequence).to.equal(true);
   });
+
+  it('keeps benchReverse enabled under perf profile when no other bench flags are set', function() {
+    globalThis.window = {
+      location: { search: '?profile=perf&benchReverse=true' }
+    };
+    const view = new GameView();
+    expect(view.startupProfile).to.equal('perf');
+    expect(view.benchReverse).to.equal(true);
+    expect(view.performanceAPI).to.equal(true);
+    expect(view.perfOverlay).to.equal(true);
+  });
 });
diff --git a/test/gameview.coverage.01-gameview-coverage.test.js b/test/gameview.coverage.01-gameview-coverage.test.js
new file mode 100644
index 00000000..7c95d6d9
--- /dev/null
+++ b/test/gameview.coverage.01-gameview-coverage.test.js
@@ -0,0 +1,390 @@
+import { readFileSync } from 'node:fs';
+import { expect } from 'chai';
+import { GameView } from '../js/game/GameView.js';
+import { BinaryReader } from '../js/data/BinaryReader.js';
+import { LevelReader } from '../js/level/LevelReader.js';
+import { MidiMapping } from '../js/midi/MidiMapping.js';
+import { toMidiFlagTriggerType } from '../js/midi/MidiFlagTriggers.js';
+import { EventHandler } from '../js/util/EventHandler.js';
+import { setDependency, resetDependencies, useGlobalLemmings } from './helpers/lemmings.js';
+import { useGlobalValueRestore } from './support/globals.js';
+import { runScenarioTable } from './support/scenario-table.js';
+
+describe('GameView coverage', function() {
+  useGlobalValueRestore(['window', 'history', 'WebMidi', 'localStorage', 'document']);
+
+  useGlobalLemmings({});
+
+  beforeEach(function() {
+    setDependency('GameFactory', class { constructor() {} });
+    setDependency('KeyboardShortcuts', class { constructor() {} dispose() {} });
+  });
+
+  afterEach(function() {
+    resetDependencies();
+  });
+
+  const makeSelect = () => ({
+    options: [],
+    selectedIndex: -1,
+    appendChild(el) {
+      this.options.push(el);
+      return el;
+    },
+    remove(idx) {
+      this.options.splice(idx, 1);
+    }
+  });
+
+  const stubDocument = () => {
+    globalThis.document = {
+      createElement() {
+        return { textContent: '', value: '' };
+      }
+    };
+  };
+
+  it('parses query params and updates history state', function() {
+    globalThis.window = {
+      location: { search: '?version=2&difficulty=2&level=3&speed=2.2&cheat=true&debug=true&bench=true&scale=0.5&shortcut=true&profile=perf&offscreenPresent=true&workerOffscreen=true' }
+    };
+    let replaced = null;
+    globalThis.history = {
+      replaceState(_state, _title, url) { replaced = url; }
+    };
+
+    const view = new GameView();
+    expect(view.gameType).to.equal(2);
+    expect(view.levelGroupIndex).to.equal(1);
+    expect(view.levelIndex).to.equal(2);
+    expect(view.gameSpeedFactor).to.equal(2);
+    expect(view.cheatEnabled).to.equal(true);
+    expect(view.benchReverse).to.equal(false);
+    expect(view.startupProfile).to.equal('perf');
+    expect(view.performanceAPI).to.equal(true);
+    expect(view.perfOverlay).to.equal(true);
+    expect(view.offscreenPresentExperiment).to.equal(true);
+    expect(view.workerOffscreenExperiment).to.equal(true);
+
+    view.updateQuery();
+    expect(replaced).to.include('?');
+    expect(replaced).to.include('v=2');
+    expect(replaced).to.include('d=2');
+    expect(replaced).to.include('_=true');
+    expect(replaced).to.include('pr=perf');
+
+    view.setHistoryState('a=1');
+    expect(replaced).to.equal('?a=1');
+  });
+
+  it('parses shorthand and numeric boolean query flags', function() {
+    globalThis.window = {
+      location: { search: '?bench&debug=1&cheat=yes&bench2=0&endless=off' }
+    };
+    const view = new GameView();
+    expect(view.bench).to.equal(true);
+    expect(view.debug).to.equal(true);
+    expect(view.cheatEnabled).to.equal(true);
+    expect(view.bench2).to.equal(false);
+    expect(view.endless).to.equal(false);
+  });
+
+  it('applies query bounds before multipliers for scaled values', function() {
+    globalThis.window = {
+      location: { search: '?nukeAfter=20&extra=0' }
+    };
+    const inRange = new GameView();
+    expect(inRange.nukeAfter).to.equal(200);
+    expect(inRange.extraLemmings).to.equal(0);
+
+    globalThis.window = {
+      location: { search: '?nukeAfter=61' }
+    };
+    const outOfRange = new GameView();
+    expect(outOfRange.nukeAfter).to.equal(0);
+  });
+
+  it('applies rollout rollback toggles for render and history codec paths', function() {
+    globalThis.window = {
+      location: {
+        search: '?profile=perf&offscreenPresent=true&workerOffscreen=true&rollbackRenderPresent=1&rollbackHistoryCodec=1'
+      }
+    };
+    const view = new GameView();
+    expect(view.rolloutFlags.renderPresentPath).to.equal(false);
+    expect(view.rolloutFlags.historyCodec).to.equal(false);
+    expect(view.offscreenPresentExperiment).to.equal(false);
+    expect(view.workerOffscreenExperiment).to.equal(false);
+    const policy = view.resolveHistoryRetentionPolicy();
+    expect(policy.coldBlockAgeTicks).to.equal(0);
+    expect(policy.enableColdBlockCompression).to.equal(false);
+    expect(policy.enableColdBlockDedupe).to.equal(false);
+  });
+
+  it('reports runtime diagnostics with normalized feature flags and cache stats', function() {
+    globalThis.window = {
+      location: { search: '' }
+    };
+    const view = new GameView();
+    view.startupProfile = 'perf';
+    view.debug = true;
+    view.midiEnabled = true;
+    view.bench = true;
+    view.gameFactory = {
+      fileProvider: {
+        getCacheStats() {
+          return { memoryEntries: 2, localStorageBytes: 10, indexedDbBytes: 11 };
+        }
+      }
+    };
+
+    const diagnostics = view.getRuntimeDiagnostics();
+    expect(diagnostics.profile).to.equal('perf');
+    expect(diagnostics.rolloutFlags).to.be.an('object');
+    expect(diagnostics.capabilities).to.be.an('object');
+    expect(diagnostics.featureFlags.debug).to.equal(true);
+    expect(diagnostics.featureFlags.midiEnabled).to.equal(true);
+    expect(diagnostics.featureFlags.bench).to.equal(true);
+    expect(diagnostics.caches.fileProvider).to.deep.equal({
+      memoryEntries: 2,
+      localStorageBytes: 10,
+      indexedDbBytes: 11
+    });
+  });
+
+  runScenarioTable([
+    {
+      name: 'formats MIDI errors for insecure contexts',
+      windowRef: { isSecureContext: false, location: { protocol: 'http:', hostname: 'example.com', search: '' } },
+      input: {},
+      expected: 'WebMIDI requires HTTPS or localhost.'
+    },
+    {
+      name: 'formats MIDI errors for permission denials',
+      windowRef: { isSecureContext: true, location: { protocol: 'https:', hostname: 'example.com', search: '' } },
+      input: { name: 'NotAllowedError', message: 'permission' },
+      expected: 'WebMIDI permission denied. Check browser permissions.'
+    },
+    {
+      name: 'formats MIDI errors for unsupported browser APIs',
+      windowRef: { isSecureContext: true, location: { protocol: 'https:', hostname: 'example.com', search: '' } },
+      input: { name: 'NotSupportedError' },
+      expected: 'WebMIDI is not supported in this browser.'
+    }
+  ], ({ windowRef, input, expected }) => {
+    globalThis.window = windowRef;
+    const view = new GameView();
+    expect(view._formatMidiEnableError(input)).to.equal(expected);
+  });
+
+  it('handles WebMidi enable lifecycle', async function() {
+    globalThis.window = { isSecureContext: true, location: { protocol: 'https:', hostname: 'example.com', search: '' } };
+    const view = new GameView();
+
+    let errorMessage = null;
+    view.setMidiStatusHandlers({ onError: msg => { errorMessage = msg; } });
+    const missing = await view._ensureWebMidiEnabled();
+    expect(missing).to.equal(null);
+    expect(errorMessage).to.include('not supported');
+
+    let enabledCalled = false;
+    let onEnabledCalled = false;
+    globalThis.WebMidi = {
+      enabled: false,
+      enable: async () => { enabledCalled = true; },
+      outputs: []
+    };
+    const view2 = new GameView();
+    view2.setMidiStatusHandlers({ onEnabled: () => { onEnabledCalled = true; } });
+    const enabled = await view2._ensureWebMidiEnabled();
+    expect(enabled).to.equal(globalThis.WebMidi);
+    expect(enabledCalled).to.equal(true);
+    expect(onEnabledCalled).to.equal(true);
+  });
+
+  it('advances and rewinds frames', function() {
+    const view = new GameView();
+    let rendered = 0;
+    let truncated = null;
+    const timer = {
+      tickIndex: 7,
+      tickCalls: [],
+      tick(step) { this.tickCalls.push(step); this.tickIndex += step; }
+    };
+    view.game = {
+      getGameTimer() { return timer; },
+      history: { truncateAfter(idx) { truncated = idx; } },
+      timeTravel: { isReversing: true, stopReverse() { this.stopped = true; } },
+      gameGui: { gameTimeChanged: false },
+      render() { rendered += 1; }
+    };
+
+    view.nextFrame();
+    expect(view.game.timeTravel.stopped).to.equal(true);
+    expect(truncated).to.equal(7);
+    expect(timer.tickCalls[0]).to.equal(1);
+    expect(view.game.gameGui.gameTimeChanged).to.equal(true);
+    expect(rendered).to.equal(1);
+
+    view.game.timeTravel = { stepBackward(step) { this.step = step; } };
+    view.prevFrame();
+    expect(view.game.timeTravel.step).to.equal(1);
+  });
+
+  it('suspends with overlay and resumes', function() {
+    globalThis.window = {
+      location: { search: '' },
+      setTimeout(cb) { cb(); return 1; },
+      clearTimeout() {}
+    };
+    const view = new GameView();
+    const timer = {
+      suspendCalls: 0,
+      continueCalls: 0,
+      suspend() { this.suspendCalls += 1; },
+      continue() { this.continueCalls += 1; }
+    };
+    const overlay = { color: null, rect: null };
+    view.stage = {
+      guiImgProps: { viewPoint: { scale: 2 }, x: 0, y: 0 },
+      startOverlayFade(color, rect) { overlay.color = color; overlay.rect = rect; }
+    };
+    view.game = { getGameTimer() { return timer; } };
+    view.bench = true;
+    view.suspendWithColor('red');
+    expect(timer.suspendCalls).to.equal(1);
+    expect(timer.continueCalls).to.equal(1);
+    expect(overlay.color).to.equal('red');
+    expect(overlay.rect.width).to.equal(32);
+  });
+
+  it('toggles editor playtest state', function() {
+    const view = new GameView();
+    const timer = {
+      running: true,
+      isRunning() { return this.running; },
+      suspendCalls: 0,
+      continueCalls: 0,
+      suspend() { this.suspendCalls += 1; },
+      continue() { this.continueCalls += 1; }
+    };
+    view.stage = { panEnabled: true };
+    view.game = { inputEnabled: true, getGameTimer() { return timer; } };
+
+    view.enterEditorMode();
+    expect(view.editorMode).to.equal(true);
+    expect(view.stage.panEnabled).to.equal(false);
+    expect(view.game.inputEnabled).to.equal(false);
+
+    view.setEditorPlaytest(true);
+    expect(timer.continueCalls).to.equal(1);
+    expect(view.stage.panEnabled).to.equal(true);
+    expect(view.game.inputEnabled).to.equal(true);
+
+    view.setEditorPlaytest(false);
+    expect(timer.suspendCalls).to.equal(2);
+    expect(view.stage.panEnabled).to.equal(false);
+    expect(view.game.inputEnabled).to.equal(false);
+
+    view.exitEditorMode();
+    expect(timer.continueCalls).to.equal(2);
+    expect(view.stage.panEnabled).to.equal(true);
+    expect(view.game.inputEnabled).to.equal(true);
+  });
+
+  it('registers midi flag triggers and emits flag events', function() {
+    const view = new GameView();
+    const added = [];
+    const emitted = [];
+    const game = {
+      level: {
+        midiFlags: [
+          { id: 4, x1: 2, y1: 3, x2: 8, y2: 9, cooldownTicks: 2, pieceId: 7 }
+        ]
+      },
+      triggerManager: {
+        add(trigger) {
+          added.push(trigger);
+        }
+      },
+      soundEvents: {
+        emit(payload) {
+          emitted.push(payload);
+        }
+      }
+    };
+
+    view._registerMidiFlagTriggers(game);
+    view._registerMidiFlagTriggers(game);
+    expect(added).to.have.length(1);
+
+    const trigger = added[0];
+    const triggerType = toMidiFlagTriggerType(4);
+    const result = trigger.trigger(4, 5, 0, { id: 11 });
+    expect(result).to.equal(0);
+    expect(emitted).to.have.length(1);
+    expect(emitted[0].triggerType).to.equal(triggerType);
+    expect(emitted[0].midiFlagId).to.equal(4);
+    expect(emitted[0].lemmingId).to.equal(11);
+  });
+
+  it('loads and renders levels when not using saved entries', async function() {
+    globalThis.window = { location: { search: '?benchSequence=true' } };
+    globalThis.history = { replaceState() {} };
+    const view = new GameView();
+    const level = {
+      screenPositionX: 6,
+      renderCalls: 0,
+      render() { this.renderCalls += 1; }
+    };
+    const gameDisplay = { clearCalls: 0, clear() { this.clearCalls += 1; } };
+    const stage = {
+      resetFadeCalls: 0,
+      updateCalls: 0,
+      applied: null,
+      redrawn: 0,
+      gameImgProps: { viewPoint: { scale: 1 }, canvasViewportSize: { width: 10, height: 10 } },
+      getGameDisplay() { return gameDisplay; },
+      resetFade() { this.resetFadeCalls += 1; },
+      updateStageSize() { this.updateCalls += 1; },
+      applyViewport(...args) { this.applied = args; },
+      redraw() { this.redrawn += 1; }
+    };
+    let started = false;
+    view.start = async () => { started = true; };
+    view.stage = stage;
+    view.gameResources = {
+      getLevelGroups() { return ['Only']; },
+      async getLevel() { return level; }
+    };
+    view.configs = [{ gametype: view.gameType }];
+    view.elementGameState = { innerText: '' };
+    view.elementSelectGameType = { selectedIndex: -1 };
+    view.elementSelectLevelGroup = { selectedIndex: -1 };
+    view.elementSelectLevel = { selectedIndex: -1 };
+
+    await view.loadLevel();
+    expect(gameDisplay.clearCalls).to.equal(1);
+    expect(stage.resetFadeCalls).to.equal(1);
+    expect(level.renderCalls).to.equal(1);
+    expect(stage.updateCalls).to.equal(1);
+    expect(stage.applied).to.not.equal(null);
+    expect(stage.redrawn).to.equal(1);
+    expect(started).to.equal(true);
+  });
+
+  it('routes loadLevel to saved selections', async function() {
+    globalThis.window = { location: { search: '' } };
+    const view = new GameView();
+    view.applyQuery = () => {};
+    view.includeSavedLevels = true;
+    view.gameResources = { getLevelGroups() { return []; } };
+    view._getSavedLevelEntries = () => ([{ id: 'one', name: 'Saved' }]);
+    view._isSavedGroupIndex = () => true;
+    let called = false;
+    view.loadSavedLevelFromSelection = async () => { called = true; return 'saved'; };
+    const result = await view.loadLevel();
+    expect(called).to.equal(true);
+    expect(result).to.equal('saved');
+  });
+});
diff --git a/test/gameview.coverage.02-gameview-coverage.test.js b/test/gameview.coverage.02-gameview-coverage.test.js
new file mode 100644
index 00000000..3ff393bf
--- /dev/null
+++ b/test/gameview.coverage.02-gameview-coverage.test.js
@@ -0,0 +1,436 @@
+import { readFileSync } from 'node:fs';
+import { expect } from 'chai';
+import { GameView } from '../js/game/GameView.js';
+import { BinaryReader } from '../js/data/BinaryReader.js';
+import { LevelReader } from '../js/level/LevelReader.js';
+import { MidiMapping } from '../js/midi/MidiMapping.js';
+import { toMidiFlagTriggerType } from '../js/midi/MidiFlagTriggers.js';
+import { EventHandler } from '../js/util/EventHandler.js';
+import { setDependency, resetDependencies, useGlobalLemmings } from './helpers/lemmings.js';
+import { useGlobalValueRestore } from './support/globals.js';
+import { runScenarioTable } from './support/scenario-table.js';
+
+describe('GameView coverage', function() {
+  useGlobalValueRestore(['window', 'history', 'WebMidi', 'localStorage', 'document']);
+
+  useGlobalLemmings({});
+
+  beforeEach(function() {
+    setDependency('GameFactory', class { constructor() {} });
+    setDependency('KeyboardShortcuts', class { constructor() {} dispose() {} });
+  });
+
+  afterEach(function() {
+    resetDependencies();
+  });
+
+  const makeSelect = () => ({
+    options: [],
+    selectedIndex: -1,
+    appendChild(el) {
+      this.options.push(el);
+      return el;
+    },
+    remove(idx) {
+      this.options.splice(idx, 1);
+    }
+  });
+
+  const stubDocument = () => {
+    globalThis.document = {
+      createElement() {
+        return { textContent: '', value: '' };
+      }
+    };
+  };
+
+  it('starts a game session and applies options', async function() {
+    globalThis.window = { location: { search: '?benchSequence=true' } };
+    globalThis.history = { replaceState() {} };
+    setDependency('GameFactory', class {
+      constructor() {}
+      async getGame() {
+        const timer = { speedFactor: 0 };
+        const history = {
+          setPreserveFutureHistory(val) { this.enabled = val; },
+          configureRetention(policy) {
+            this.retention = { ...policy };
+            return this.retention;
+          }
+        };
+        const game = {
+          level: { name: 'Level', entrances: [{ x: 0, y: 0 }] },
+          history,
+          timeTravel: {
+            setHistoryRetention(policy) {
+              this.retention = { ...policy };
+              return this.retention;
+            }
+          },
+          onGameEnd: new EventHandler(),
+          setGameDisplay(display) { this.gameDisplay = display; },
+          setGuiDisplay(display) { this.guiGuiDisplay = display; },
+          getGameTimer() { return timer; },
+          start() { this.started = true; },
+          loadLevel() {},
+          cheat() { this.cheated = true; }
+        };
+        return game;
+      }
+    });
+    setDependency('KeyboardShortcuts', class { constructor() {} dispose() {} });
+
+    const view = new GameView();
+    view.gameResources = {};
+    view.stage = {
+      getGameDisplay() { return { id: 'game' }; },
+      getGuiDisplay() { return { id: 'gui' }; },
+      setCursorSprite() {},
+    };
+    view.applyLevelViewport = () => { view.viewportApplied = true; };
+    view.elementGameState = { innerText: '' };
+    view.preserveHistory = true;
+    view.cheatEnabled = true;
+    view.debug = true;
+    view.midiEnabled = true;
+    view.initMidiRouting = async () => {
+      view.midiRouter = { attach() { view.attached = true; } };
+      return view.midiRouter;
+    };
+
+    await view.start();
+    expect(view.game.started).to.equal(true);
+    expect(view.game.history.enabled).to.equal(true);
+    expect(view.game.timeTravel.retention).to.deep.include({
+      enableHistoryCap: true,
+      historyCapTicks: 12000,
+      historyWarnTicks: 9000,
+      preserveFutureHistory: true
+    });
+    expect(view.getRuntimeDiagnostics().history.retention.historyCapTicks).to.equal(12000);
+    expect(view.viewportApplied).to.equal(true);
+    expect(view.game.cheated).to.equal(true);
+    expect(view.game.showDebug).to.equal(true);
+    expect(view.attached).to.equal(true);
+  });
+
+  it('handles saved level loading and editor text utilities', async function() {
+    globalThis.window = { location: { search: '' } };
+    const indexPayload = JSON.stringify([
+      { id: 'lvl-1', name: 'Saved Level', updatedAt: 1 }
+    ]);
+    globalThis.localStorage = {
+      getItem(key) {
+        if (key === 'lemmings.editor.levels') return indexPayload;
+        if (key === 'lemmings.editor.level.lvl-1') return 'LEVELDATA';
+        return null;
+      },
+      setItem() {},
+      removeItem() {}
+    };
+
+    const view = new GameView();
+    view.includeSavedLevels = true;
+    view.levelIndex = 0;
+    view.gameResources = {};
+    view.autoExitEditorOnSelect = true;
+    view.editorMode = true;
+    view.exitEditorMode = () => { view.exited = true; };
+    view.loadEditorPreviewLevel = async () => 'preview';
+
+    const result = await view.loadSavedLevelFromSelection();
+    expect(result).to.equal('preview');
+    expect(view.exited).to.equal(true);
+    expect(view.getEditorLevelText()).to.be.a('string');
+    expect(view.getEditorLevelTitle()).to.equal('Untitled');
+  });
+
+  it('initializes MIDI routing with project config', async function() {
+    globalThis.window = { location: { search: '' } };
+    globalThis.WebMidi = { enabled: true, outputs: [{ id: 'out' }] };
+    setDependency('MidiEventRouter', class {
+      constructor(mapping) { this.mapping = mapping; this.scheduler = { allNotesOff() {} }; }
+      setOutput(output) { this.output = output; }
+      setMapping(mapping) { this.mapping = mapping; }
+      detach() { this.detached = true; }
+      dispose() { this.disposed = true; }
+    });
+    const view = new GameView();
+    view.setMidiProjectConfig({ position: { viewPan: true } });
+    view._ensureWebMidiEnabled = async () => ({ enabled: true, outputs: [{ id: 'out' }] });
+    view._loadMidiMapping = async () => {
+      view._midiBaseConfig = { position: {} };
+      return new MidiMapping({ position: {} });
+    };
+    view.midiEnabled = true;
+
+    const router = await view.initMidiRouting();
+    expect(router).to.equal(view.midiRouter);
+    expect(view.midiOut).to.eql({ id: 'out' });
+    expect(view.getMidiConfig().position.viewPan).to.equal(true);
+  });
+
+  it('disables MIDI routing cleanly', async function() {
+    const view = new GameView();
+    let detached = 0;
+    let allNotesOff = 0;
+    view.midiRouter = {
+      detach() { detached += 1; },
+      scheduler: { allNotesOff() { allNotesOff += 1; } }
+    };
+    await view.setMidiEnabled(false);
+    expect(detached).to.equal(1);
+    expect(allNotesOff).to.equal(1);
+  });
+
+  it('covers helpers and selection utilities', async function() {
+    stubDocument();
+    globalThis.window = { location: { search: '' } };
+    const view = new GameView();
+    const select = makeSelect();
+    select.options.push({ value: '1' }, { value: '2' });
+    view.clearHtmlList(select);
+    expect(select.options.length).to.equal(0);
+
+    expect(view.prefixNumbers(['A', 'B'])).to.eql(['1 - A', '2 - B']);
+    expect(view.strToNum('5')).to.equal(5);
+    expect(view.strToNum('nope')).to.equal(0);
+
+    view.arrayToSelect(select, ['X', 'Y']);
+    expect(select.options.length).to.equal(2);
+
+    view.gameResources = { getLevelGroups() { return ['One', 'Two']; } };
+    view.includeSavedLevels = true;
+    const groups = view._getGroupNames([{ id: 'a', name: 'Saved' }]);
+    expect(groups).to.eql(['One', 'Two', 'Saved Levels']);
+
+    const config = {
+      level: {
+        order: [[1], []],
+        getGroupLength(index) {
+          return index === 0 ? 1 : 0;
+        }
+      }
+    };
+    view.levelGroupIndex = 1;
+    view.levelIndex = 4;
+    view._normalizeSelection(config, []);
+    expect(view.levelGroupIndex).to.equal(0);
+    expect(view.levelIndex).to.equal(0);
+
+    const emptyConfig = {
+      level: { order: [[], []], getGroupLength() { return 0; } }
+    };
+    view.levelGroupIndex = 1;
+    view.levelIndex = 2;
+    view._normalizeSelection(emptyConfig, []);
+    expect(view.levelGroupIndex).to.equal(0);
+    expect(view.levelIndex).to.equal(0);
+
+    view.elementSelectLevelGroup = select;
+    view.gameFactory = { async getConfig() { return config; } };
+    await view._syncLevelGroupSelect([]);
+    expect(view.elementSelectLevelGroup.selectedIndex).to.equal(0);
+
+    const stageImage = {
+      viewPoint: { scale: 2 },
+      canvasViewportSize: { width: 100, height: 50 }
+    };
+    const focus = view.getEntranceFocusX({ entrances: [{ x: 10, y: 0 }] }, stageImage);
+    expect(focus).to.equal(9);
+  });
+
+  it('falls back to entrance focus when applying viewport without saved screen position', function() {
+    const view = new GameView();
+    let appliedX = null;
+    let redraws = 0;
+    view.stage = {
+      gameImgProps: {
+        viewPoint: { scale: 2 },
+        canvasViewportSize: { width: 100, height: 50 }
+      },
+      applyViewport(_stageImage, x) {
+        appliedX = x;
+      },
+      redraw() {
+        redraws += 1;
+      }
+    };
+
+    view.applyLevelViewport({
+      screenPositionX: Number.NaN,
+      entrances: [{ x: 10, y: 0 }]
+    });
+
+    expect(appliedX).to.equal(9);
+    expect(redraws).to.equal(1);
+
+    view.applyLevelViewport({
+      screenPositionX: 42,
+      entrances: [{ x: 10, y: 0 }]
+    });
+
+    expect(appliedX).to.equal(42);
+    expect(redraws).to.equal(2);
+  });
+
+  it('populates level selections for saved and missing levels', async function() {
+    stubDocument();
+    const view = new GameView();
+    view.elementSelectLevel = makeSelect();
+    view.gameFactory = {
+      async getConfig() {
+        return { level: { getGroupLength() { return 2; } } };
+      }
+    };
+    view.gameResources = {
+      getLevelGroups() { return ['One']; },
+      async getLevel(_group, index) {
+        if (index === 0) return { name: 'Alpha' };
+        throw new Error('missing');
+      }
+    };
+
+    view.includeSavedLevels = true;
+    view.levelGroupIndex = 1;
+    view._getSavedLevelEntries = () => ([{ id: 's1', name: 'Saved' }]);
+    await view.populateLevelSelect();
+    expect(view.elementSelectLevel.options.length).to.equal(1);
+
+    view.includeSavedLevels = false;
+    view.levelGroupIndex = 0;
+    await view.populateLevelSelect();
+    expect(view.elementSelectLevel.options.length).to.equal(2);
+  });
+
+  it('selects levels, groups, and game types', async function() {
+    const view = new GameView();
+    view.gameResources = { getLevelGroups() { return ['One']; } };
+    view._getSavedLevelEntries = () => [];
+    view.populateLevelSelect = async () => { view.populated = true; };
+    view.loadLevel = () => { view.loaded = true; };
+
+    await view.selectLevelGroup(5);
+    expect(view.levelGroupIndex).to.equal(0);
+    expect(view.loaded).to.equal(true);
+
+    view.editorMode = true;
+    view.autoExitEditorOnSelect = true;
+    view.exitEditorMode = () => { view.exited = true; };
+    view.loadEditorLevelFromSelection = async () => { view.editorLoaded = true; };
+    await view.selectLevelGroup(0);
+    expect(view.exited).to.equal(true);
+    expect(view.editorLoaded).to.equal(true);
+
+    view.editorMode = false;
+    view.configs = [{ gametype: 2, name: 'Pack' }];
+    view.gameFactory = {
+      async getGameResources() { return { getLevelGroups() { return ['One']; } }; },
+      async getConfig() { return { level: { getGroupLength() { return 0; } } }; }
+    };
+    view._syncLevelGroupSelect = async () => { view.synced = true; };
+    view.populateLevelSelect = async () => { view.levelsPopulated = true; };
+    await view.selectGameType(0);
+    expect(view.gameType).to.equal(2);
+    expect(view.synced).to.equal(true);
+    expect(view.levelsPopulated).to.equal(true);
+
+    view.editorMode = true;
+    view.loadEditorLevelFromSelection = async () => { view.editorPicked = true; };
+    await view.selectLevel(3);
+    expect(view.levelIndex).to.equal(3);
+    expect(view.editorPicked).to.equal(true);
+  });
+
+  it('runs setup and setupEditor flows', async function() {
+    stubDocument();
+    globalThis.window = { location: { search: '' } };
+    const view = new GameView();
+    view._loadMidiMapping = async () => new MidiMapping({ position: {} });
+    view.setMidiProjectConfig({ position: { viewPan: true } });
+    view.gameFactory = {
+      configReader: { configs: [{ gametype: 1, name: 'Pack' }] },
+      async getGameResources() {
+        return { getLevelGroups() { return ['One']; } };
+      }
+    };
+    view.elementSelectGameType = makeSelect();
+    view._syncLevelGroupSelect = async () => { view.groupSynced = true; };
+    view.populateLevelSelect = async () => { view.levelsSynced = true; };
+    view.loadLevel = async () => { view.didLoad = true; };
+    view.benchSequenceStart = async () => { view.benchRan = true; };
+
+    await view.setup();
+    expect(view.groupSynced).to.equal(true);
+    expect(view.levelsSynced).to.equal(true);
+    expect(view.didLoad).to.equal(true);
+    await view.benchSequenceStart();
+    expect(view.benchRan).to.equal(true);
+
+    view.benchSequence = false;
+    view.populateLevelSelect = async () => { view.editorLevels = true; };
+    await view.setupEditor();
+    expect(view.editorLevels).to.equal(true);
+  });
+
+  it('covers simple gameplay controls and canvas setup', async function() {
+    const events = [];
+    globalThis.window = {
+      location: { search: '' },
+      addEventListener(type) { events.push(type); },
+      removeEventListener(type) { events.push(`remove:${type}`); }
+    };
+    setDependency('Stage', class {
+      constructor() { this.disposed = false; }
+      scheduleUpdateStageSize() { this.scheduled = true; }
+      dispose() { this.disposed = true; }
+    });
+    const view = new GameView();
+    view.gameCanvas = {};
+    expect(events).to.include('resize');
+    view.gameCanvas = {};
+    expect(events).to.include('remove:resize');
+
+    let speed = 1;
+    const timer = {
+      suspendCalls: 0,
+      continueCalls: 0,
+      suspend() { this.suspendCalls += 1; },
+      continue() { this.continueCalls += 1; },
+      speedFactor: speed
+    };
+    view.game = {
+      getGameTimer() { return timer; },
+      setDebugMode(on) { this.debugOn = on; }
+    };
+
+    view.suspend();
+    view.continue();
+    view.selectSpeedFactor(3);
+    view.enableDebug();
+    view.playMusic();
+    view.stopMusic();
+    view.stopSound();
+    view.playSound();
+
+    expect(timer.suspendCalls).to.equal(1);
+    expect(timer.continueCalls).to.equal(1);
+    expect(timer.speedFactor).to.equal(3);
+    expect(view.game.debugOn).to.equal(true);
+  });
+
+  it('sets game canvas safely when window listeners are unavailable', function() {
+    globalThis.window = { location: { search: '' } };
+    setDependency('Stage', class {
+      scheduleUpdateStageSize() {}
+      dispose() {}
+    });
+    const view = new GameView();
+    globalThis.window = undefined;
+
+    expect(() => {
+      view.gameCanvas = {};
+      view.gameCanvas = {};
+    }).to.not.throw();
+  });
+});
diff --git a/test/gameview.coverage.03-gameview-coverage.test.js b/test/gameview.coverage.03-gameview-coverage.test.js
new file mode 100644
index 00000000..b331c930
--- /dev/null
+++ b/test/gameview.coverage.03-gameview-coverage.test.js
@@ -0,0 +1,433 @@
+import { readFileSync } from 'node:fs';
+import { expect } from 'chai';
+import { GameView } from '../js/game/GameView.js';
+import { BinaryReader } from '../js/data/BinaryReader.js';
+import { LevelReader } from '../js/level/LevelReader.js';
+import { MidiMapping } from '../js/midi/MidiMapping.js';
+import { toMidiFlagTriggerType } from '../js/midi/MidiFlagTriggers.js';
+import { EventHandler } from '../js/util/EventHandler.js';
+import { setDependency, resetDependencies, useGlobalLemmings } from './helpers/lemmings.js';
+import { useGlobalValueRestore } from './support/globals.js';
+import { runScenarioTable } from './support/scenario-table.js';
+
+describe('GameView coverage', function() {
+  useGlobalValueRestore(['window', 'history', 'WebMidi', 'localStorage', 'document']);
+
+  useGlobalLemmings({});
+
+  beforeEach(function() {
+    setDependency('GameFactory', class { constructor() {} });
+    setDependency('KeyboardShortcuts', class { constructor() {} dispose() {} });
+  });
+
+  afterEach(function() {
+    resetDependencies();
+  });
+
+  const makeSelect = () => ({
+    options: [],
+    selectedIndex: -1,
+    appendChild(el) {
+      this.options.push(el);
+      return el;
+    },
+    remove(idx) {
+      this.options.splice(idx, 1);
+    }
+  });
+
+  const stubDocument = () => {
+    globalThis.document = {
+      createElement() {
+        return { textContent: '', value: '' };
+      }
+    };
+  };
+
+  it('handles game end and replay flow', async function() {
+    globalThis.window = {
+      location: { search: '' },
+      setTimeout(cb) { cb(); return 1; },
+      clearTimeout() {}
+    };
+    setDependency('GameStateTypes', {
+      UNKNOWN: 0,
+      SUCCEEDED: 1,
+      toString() { return 'SUCCEEDED'; }
+    });
+    const view = new GameView();
+    view.stage = { startFadeOut() { view.faded = true; } };
+    view.elementGameState = { innerText: '' };
+    view.moveToLevel = (delta) => { view.moved = delta; };
+    view.onGameEnd({ state: 1 });
+    expect(view.faded).to.equal(true);
+    expect(view.moved).to.equal(1);
+
+    view.start = async () => { view.started = true; };
+    await view.loadReplay('abc');
+    expect(view.started).to.equal(true);
+  });
+
+  it('covers MIDI config loading and setters', async function() {
+    setDependency('GameFactory', class {
+      constructor() {
+        this.fileProvider = { loadString: async () => '{}' };
+      }
+    });
+    setDependency('KeyboardShortcuts', class { constructor() {} dispose() {} });
+    const view = new GameView();
+    const mapping = await view._loadMidiMapping();
+    expect(mapping).to.be.instanceOf(MidiMapping);
+    expect(view.getMidiBaseConfig()).to.be.an('object');
+    expect(view.getMidiSchemaHash()).to.be.a('string');
+
+    view.midiRouter = { setOutput(out) { this.output = out; } };
+    view.midiOut = { id: 'dev' };
+    expect(view.midiRouter.output).to.eql({ id: 'dev' });
+  });
+
+  it('toggles editor mode and creates editor levels', function() {
+    globalThis.window = { location: { search: '' } };
+    const view = new GameView();
+    view.stage = { panEnabled: true };
+    view.game = { inputEnabled: true, getGameTimer() { return { isRunning() { return false; } }; } };
+
+    view.toggleEditorMode();
+    expect(view.editorMode).to.equal(true);
+    view.toggleEditorMode();
+    expect(view.editorMode).to.equal(false);
+
+    const blank = view.createBlankEditorLevel({ render: false });
+    expect(blank).to.equal(view.editorSession.level);
+    const fromText = view.loadEditorLevelFromText('LEVEL', { render: false });
+    expect(fromText).to.equal(view.editorSession.level);
+    expect(blank).to.not.equal(fromText);
+  });
+
+  it('starts with custom levels and refreshes saved lists', async function() {
+    const view = new GameView();
+    view.gameResources = {};
+    view.stage = {
+      getGameDisplay() { return {}; },
+      getGuiDisplay() { return {}; },
+      setCursorSprite() {}
+    };
+    view.applyLevelViewport = () => { view.viewportApplied = true; };
+    view.elementGameState = { innerText: '' };
+    view.gameSpeedFactor = 2;
+    view.gameFactory = {
+      async getGame() {
+        return {
+          level: { name: 'Custom' },
+          soundEvents: {},
+          onGameEnd: new EventHandler(),
+          getGameTimer() { return { speedFactor: 0 }; },
+          loadLevel() {},
+          setGameDisplay() {},
+          setGuiDisplay() {},
+          start() { view.customStarted = true; },
+          cheat() { view.customCheat = true; }
+        };
+      }
+    };
+    view.cheatEnabled = true;
+    await view._startWithLevel({ name: 'Custom' });
+    expect(view.customStarted).to.equal(true);
+
+    view.includeSavedLevels = true;
+    view.gameResources.getLevelGroups = () => ['One'];
+    view._getSavedLevelEntries = () => ([{ id: 'a', name: 'Saved' }]);
+    view._syncLevelGroupSelect = async () => { view.synced = true; };
+    view.populateLevelSelect = async () => { view.populated = true; };
+    view._isSavedGroupIndex = () => true;
+    view.loadSavedLevelFromSelection = async () => { view.savedLoaded = true; };
+    await view.refreshSavedLevels();
+    expect(view.savedLoaded).to.equal(true);
+  });
+
+  it('covers editor preview early exits and classic reader checks', async function() {
+    globalThis.window = { location: { search: '' }, clearTimeout() {} };
+    const view = new GameView();
+    view.gameFactory = { async getConfig() { return { gametype: 1, level: { order: [] } }; } };
+    view.gameResources = { config: null };
+    view.editorSession = { level: {} };
+    view.game = { stop() { view.stopped = true; } };
+    view.midiRouter = { detach() { view.detached = true; } };
+    view.elementGameState = { innerText: '' };
+    const preview = await view.loadEditorPreviewLevel();
+    expect(preview).to.equal(null);
+    expect(view.stopped).to.equal(true);
+
+    const none = await view._loadClassicLevelReader(1, 0, 0);
+    expect(none).to.equal(null);
+
+    view.gameFactory = {
+      fileProvider: {},
+      async getConfig() { return null; }
+    };
+    const none2 = await view._loadClassicLevelReader(1, 0, 0);
+    expect(none2).to.equal(null);
+
+    view.gameFactory = {
+      fileProvider: { loadBinary: async () => new Uint8Array(0) },
+      async getConfig() {
+        return { path: '.', level: { order: [[]], filePrefix: 'L' } };
+      }
+    };
+    const none3 = await view._loadClassicLevelReader(1, 5, 5);
+    expect(none3).to.equal(null);
+  });
+
+  it('covers bench routines and sequence setup', async function() {
+    setDependency('TriggerTypes', {
+      DROWN: 1,
+      FRYING: 2,
+      KILL: 3,
+      TRAP: 4
+    });
+    setDependency('Lemming', class { static LEM_MAX_FALLING = 20; });
+    const view = new GameView();
+    view.loadLevel = async () => {};
+    view.configs = [{ gametype: view.gameType, name: 'Pack' }];
+    view._getSavedLevelEntries = () => [];
+
+    const level = {
+      width: 20,
+      height: 20,
+      name: 'Bench',
+      entrances: [{ x: 2, y: 2 }],
+      triggers: [],
+      getGroundMaskLayer() {
+        return {
+          hasGroundAt() { return false; },
+          countMaskInRect() { return 0; }
+        };
+      }
+    };
+    const lm = {
+      spawnCount: 0,
+      spawnTotal: 0,
+      getLemmings() { return []; }
+    };
+    const timer = {
+      speedFactor: 1,
+      benchStartupFrames: 0,
+      benchStableFactor: 0,
+      TIME_PER_FRAME_MS: 60,
+      getGameTime() { return 0; },
+      eachGameSecond: new EventHandler(),
+      suspend() {}
+    };
+    view.game = {
+      level,
+      getLemmingManager() { return lm; },
+      getGameTimer() { return timer; },
+      getVictoryCondition() { return { releaseRate: 1, getMinReleaseRate() { return 1; } }; }
+    };
+    view.stage = { applyLevelViewport() {} };
+    view.applyLevelViewport = () => { view.viewportApplied = true; };
+    view._benchCounts = [1];
+
+    await view.benchStart(1);
+    expect(timer.speedFactor).to.equal(6);
+    expect(timer.benchStartupFrames).to.equal(120);
+
+    const timer2 = {
+      speedFactor: 10,
+      benchStartupFrames: 0,
+      benchStableFactor: 0,
+      getGameTime() { return 120; },
+      eachGameSecond: new EventHandler(),
+      suspend() { view.suspended = true; }
+    };
+    const lm2 = { spawnTotal: 0, spawnCount: 1 };
+    view.game = {
+      level,
+      getLemmingManager() { return lm2; },
+      getVictoryCondition() { return { getMinReleaseRate() { return 1; }, releaseRate: 1 }; },
+      getGameTimer() { return timer2; }
+    };
+    const extrasPromise = view.benchMeasureExtras();
+    await Promise.resolve();
+    timer2.eachGameSecond.trigger();
+    const extras = await extrasPromise;
+    expect(extras).to.equal(0);
+    expect(view.suspended).to.equal(true);
+
+    view.benchMeasureExtras = async () => 2;
+    view.benchStart = async () => { view.sequenceStarted = true; };
+    await view.benchSequenceStart();
+    expect(view.sequenceStarted).to.equal(true);
+  });
+
+  it('short-circuits start and controls when no game is active', async function() {
+    const view = new GameView();
+    view.gameFactory = null;
+    await view.start();
+    view.cheat();
+    view.suspend();
+    view.continue();
+    view.suspendWithColor('red');
+    view.nextFrame();
+    view.prevFrame();
+    view.selectSpeedFactor(3);
+    view.enableDebug();
+  });
+
+  it('continues when start is called with an existing game', async function() {
+    const view = new GameView();
+    let continued = false;
+    view.game = { getGameTimer() { return { continue() { continued = true; } }; } };
+    view.continue = () => { continued = true; };
+    await view.start();
+    expect(continued).to.equal(true);
+  });
+
+  it('handles game end for non-success results', function() {
+    globalThis.window = {
+      location: { search: '' },
+      setTimeout(cb) { cb(); return 1; }
+    };
+    setDependency('GameStateTypes', {
+      UNKNOWN: 0,
+      SUCCEEDED: 1,
+      toString() { return 'FAILED'; }
+    });
+    const view = new GameView();
+    view.stage = { startFadeOut() {} };
+    view.elementGameState = { innerText: '' };
+    view.moveToLevel = delta => { view.moved = delta; };
+    view.onGameEnd({ state: 0 });
+    expect(view.moved).to.equal(0);
+  });
+
+  it('uses global timer fallback when handling game end without window timers', function() {
+    globalThis.window = { location: { search: '' } };
+    const originalSetTimeout = globalThis.setTimeout;
+    try {
+      let timeoutCb = null;
+      globalThis.setTimeout = (cb) => {
+        timeoutCb = cb;
+        return 33;
+      };
+      setDependency('GameStateTypes', {
+        UNKNOWN: 0,
+        SUCCEEDED: 1,
+        toString() { return 'SUCCEEDED'; }
+      });
+      const view = new GameView();
+      view.stage = { startFadeOut() {} };
+      view.elementGameState = { innerText: '' };
+      view.moveToLevel = delta => { view.moved = delta; };
+
+      globalThis.window = undefined;
+      view.onGameEnd({ state: 1 });
+      expect(view.autoMoveTimer).to.equal(33);
+      timeoutCb();
+      expect(view.moved).to.equal(1);
+      expect(view.autoMoveTimer).to.equal(null);
+    } finally {
+      globalThis.setTimeout = originalSetTimeout;
+    }
+  });
+
+  it('formats MIDI errors for security and empty messages', function() {
+    globalThis.window = { isSecureContext: true, location: { protocol: 'https:', hostname: 'example.com', search: '' } };
+    const view = new GameView();
+    expect(view._formatMidiEnableError({ name: 'SecurityError', message: 'secure context' }))
+      .to.equal('WebMIDI requires HTTPS or localhost.');
+    expect(view._formatMidiEnableError(''))
+      .to.equal('WebMIDI enable failed.');
+  });
+
+  it('reports WebMidi enable failures', async function() {
+    globalThis.window = { isSecureContext: true, location: { protocol: 'https:', hostname: 'example.com', search: '' } };
+    let errorMessage = null;
+    globalThis.WebMidi = {
+      enabled: false,
+      enable: async () => { throw new Error('boom'); }
+    };
+    const view = new GameView();
+    view.setMidiStatusHandlers({ onError: msg => { errorMessage = msg; } });
+    const result = await view._ensureWebMidiEnabled();
+    expect(result).to.equal(null);
+    expect(errorMessage).to.contain('WebMIDI enable failed');
+  });
+
+  it('attaches MIDI routing when enabled and game has sound events', async function() {
+    const view = new GameView();
+    view.game = { soundEvents: {}, getGameTimer() { return { continue() {} }; } };
+    view.stage = {};
+    view.midiRouter = { attach() {}, detach() {}, scheduler: { allNotesOff() {} } };
+    view.initMidiRouting = async () => view.midiRouter;
+    await view.setMidiEnabled(true);
+  });
+
+  it('covers helper branches for selection utilities', function() {
+    const view = new GameView();
+    view.includeSavedLevels = true;
+    view.gameResources = { getLevelGroups() { return []; } };
+    expect(view._getGroupLength({}, 0, 0, [{ id: 'a' }])).to.equal(1);
+
+    view.levelGroupIndex = 2;
+    view.levelIndex = 3;
+    view._normalizeSelection({}, []);
+    expect(view.levelGroupIndex).to.equal(0);
+    expect(view.levelIndex).to.equal(0);
+
+    const config = { level: { order: [[1]], getGroupLength() { return 1; } } };
+    view.levelGroupIndex = 0;
+    view.levelIndex = 5;
+    view._normalizeSelection(config, []);
+    expect(view.levelIndex).to.equal(0);
+
+    view.arrayToSelect(null, ['A']);
+    view.changeHtmlText(null, 'hi');
+  });
+
+  it('handles empty saved lists and editor selections', async function() {
+    stubDocument();
+    const view = new GameView();
+    view.elementSelectLevel = makeSelect();
+    view.gameResources = { getLevelGroups() { return ['One']; } };
+    view.gameFactory = { async getConfig() { return { level: { getGroupLength() { return 0; } } }; } };
+    view._getSavedLevelEntries = () => [];
+    view._isSavedGroupIndex = () => true;
+    view.levelGroupIndex = 0;
+    view.levelIndex = 3;
+    await view.populateLevelSelect();
+    expect(view.levelIndex).to.equal(0);
+
+    view.editorMode = true;
+    view.autoExitEditorOnSelect = true;
+    view.exitEditorMode = () => { view.exited = true; };
+    view.loadEditorLevelFromSelection = async () => { view.loadedEditor = true; };
+    view.gameFactory = {
+      async getGameResources() { return { getLevelGroups() { return ['One']; } }; },
+      async getConfig() { return { level: { getGroupLength() { return 0; } } }; }
+    };
+    view.configs = [{ gametype: 1 }];
+    await view.selectGameType(0);
+    expect(view.exited).to.equal(true);
+    expect(view.loadedEditor).to.equal(true);
+  });
+
+  it('updates bench setup when enabled', async function() {
+    stubDocument();
+    const view = new GameView();
+    view.benchSequence = true;
+    view.applyQuery = () => {};
+    view._loadMidiMapping = async () => new MidiMapping({ position: {} });
+    view.gameFactory = {
+      configReader: { configs: [{ gametype: 1, name: 'Pack' }] },
+      async getGameResources() { return { getLevelGroups() { return ['One']; } }; }
+    };
+    view.elementSelectGameType = makeSelect();
+    view._syncLevelGroupSelect = async () => {};
+    view.populateLevelSelect = async () => {};
+    view.loadLevel = async () => {};
+    view.benchSequenceStart = async () => { view.benchRan = true; };
+    await view.setup();
+    expect(view.benchRan).to.equal(true);
+  });
+});
diff --git a/test/gameview.coverage.04-gameview-coverage.test.js b/test/gameview.coverage.04-gameview-coverage.test.js
new file mode 100644
index 00000000..190c74e1
--- /dev/null
+++ b/test/gameview.coverage.04-gameview-coverage.test.js
@@ -0,0 +1,437 @@
+import { readFileSync } from 'node:fs';
+import { expect } from 'chai';
+import { GameView } from '../js/game/GameView.js';
+import { BinaryReader } from '../js/data/BinaryReader.js';
+import { LevelReader } from '../js/level/LevelReader.js';
+import { MidiMapping } from '../js/midi/MidiMapping.js';
+import { toMidiFlagTriggerType } from '../js/midi/MidiFlagTriggers.js';
+import { EventHandler } from '../js/util/EventHandler.js';
+import { setDependency, resetDependencies, useGlobalLemmings } from './helpers/lemmings.js';
+import { useGlobalValueRestore } from './support/globals.js';
+import { runScenarioTable } from './support/scenario-table.js';
+
+describe('GameView coverage', function() {
+  useGlobalValueRestore(['window', 'history', 'WebMidi', 'localStorage', 'document']);
+
+  useGlobalLemmings({});
+
+  beforeEach(function() {
+    setDependency('GameFactory', class { constructor() {} });
+    setDependency('KeyboardShortcuts', class { constructor() {} dispose() {} });
+  });
+
+  afterEach(function() {
+    resetDependencies();
+  });
+
+  const makeSelect = () => ({
+    options: [],
+    selectedIndex: -1,
+    appendChild(el) {
+      this.options.push(el);
+      return el;
+    },
+    remove(idx) {
+      this.options.splice(idx, 1);
+    }
+  });
+
+  const stubDocument = () => {
+    globalThis.document = {
+      createElement() {
+        return { textContent: '', value: '' };
+      }
+    };
+  };
+
+  it('clears pending timers and replaces running games on load', async function() {
+    globalThis.window = { location: { search: '' }, clearTimeout() {} };
+    globalThis.history = { replaceState() {} };
+    const view = new GameView();
+    view.autoMoveTimer = 1;
+    view.gameResources = {
+      getLevelGroups() { return ['One']; },
+      async getLevel() { return { render() {}, screenPositionX: 0 }; }
+    };
+    view.stage = {
+      getGameDisplay() { return { clear() {}, initSize() {}, setBackground() {} }; },
+      resetFade() {},
+      updateStageSize() {},
+      applyViewport() {},
+      redraw() {}
+    };
+    view.applyLevelViewport = () => {};
+    view.game = { stop() { view.stopped = true; } };
+    view.midiRouter = { detach() { view.detached = true; } };
+    view.elementGameState = { innerText: '' };
+    view.configs = [{ gametype: view.gameType }];
+    await view.loadLevel();
+    expect(view.stopped).to.equal(true);
+    expect(view.detached).to.equal(true);
+  });
+
+  it('covers replay start, cheat, and frame helpers when game exists', async function() {
+    globalThis.window = {
+      location: { search: '' },
+      setTimeout(cb) { cb(); return 1; },
+      clearTimeout() {}
+    };
+    const view = new GameView();
+    let replayLoaded = null;
+    const timer = { continue() {}, suspend() {}, tick() {}, speedFactor: 0 };
+    view.gameFactory = {
+      async getGame() {
+        return {
+          level: {},
+          soundEvents: {},
+          onGameEnd: new EventHandler(),
+          getCommandManager() { return { loadReplay(str) { replayLoaded = str; } }; },
+          getGameTimer() { return timer; },
+          history: { truncateAfter() {} },
+          timeTravel: { stepBackward() {} },
+          render() {},
+          setGameDisplay() {},
+          setGuiDisplay() {},
+          loadLevel() {},
+          start() {},
+          cheat() { view.cheated = true; }
+        };
+      }
+    };
+    view.stage = {
+      getGameDisplay() { return {}; },
+      getGuiDisplay() { return {}; },
+      setCursorSprite() {}
+    };
+    view.applyLevelViewport = () => {};
+    await view.start('abc');
+    expect(replayLoaded).to.equal('abc');
+
+    view.cheat();
+    view.suspendWithColor('blue');
+    view.nextFrame();
+    view.prevFrame();
+    view.selectSpeedFactor(2);
+  });
+
+  it('draws overlay and resets timers in suspendWithColor', function() {
+    let timeoutCb = null;
+    let clearedId = null;
+    globalThis.window = {
+      location: { search: '' },
+      clearTimeout(id) { clearedId = id; },
+      setTimeout(cb) { timeoutCb = cb; return 7; }
+    };
+    const view = new GameView();
+    const timer = {
+      suspend() {},
+      continue() { view.continued = true; }
+    };
+    view.game = { getGameTimer() { return timer; } };
+    view.stage = {
+      guiImgProps: { x: 10, y: 20, viewPoint: { scale: 2 } },
+      startOverlayFade(color, rect) { view.overlay = { color, rect }; }
+    };
+    view.resumeTimer = 3;
+    view.bench = true;
+
+    view.suspendWithColor('red');
+    expect(clearedId).to.equal(3);
+    expect(view.resumeTimer).to.equal(7);
+    expect(view.overlay.rect).to.eql({ x: 330, y: 84, width: 32, height: 20 });
+
+    timeoutCb();
+    expect(view.continued).to.equal(true);
+    expect(view.resumeTimer).to.equal(null);
+  });
+
+  it('replaces pending resume timers when suspendWithColor is called repeatedly', function() {
+    const callbacks = new Map();
+    let nextTimerId = 10;
+    const cleared = [];
+    globalThis.window = {
+      location: { search: '' },
+      clearTimeout(id) { cleared.push(id); callbacks.delete(id); },
+      setTimeout(cb) {
+        const id = nextTimerId++;
+        callbacks.set(id, cb);
+        return id;
+      }
+    };
+    const view = new GameView();
+    const timer = {
+      suspendCalls: 0,
+      continueCalls: 0,
+      suspend() { this.suspendCalls += 1; },
+      continue() { this.continueCalls += 1; }
+    };
+    view.game = { getGameTimer() { return timer; } };
+    view.stage = {
+      guiImgProps: { x: 0, y: 0, viewPoint: { scale: 1 } },
+      startOverlayFade() {}
+    };
+
+    view.suspendWithColor('red');
+    const firstTimer = view.resumeTimer;
+    view.suspendWithColor('blue');
+    const secondTimer = view.resumeTimer;
+
+    expect(firstTimer).to.equal(10);
+    expect(secondTimer).to.equal(11);
+    expect(cleared).to.deep.equal([10]);
+    expect(timer.suspendCalls).to.equal(2);
+
+    callbacks.get(firstTimer)?.();
+    expect(timer.continueCalls).to.equal(0);
+
+    callbacks.get(secondTimer)?.();
+    expect(timer.continueCalls).to.equal(1);
+    expect(view.resumeTimer).to.equal(null);
+  });
+
+  it('uses global timer fallbacks in suspendWithColor when window is unavailable', function() {
+    globalThis.window = { location: { search: '' } };
+    const originalSetTimeout = globalThis.setTimeout;
+    const originalClearTimeout = globalThis.clearTimeout;
+    const cleared = [];
+    try {
+      globalThis.setTimeout = () => 19;
+      globalThis.clearTimeout = (id) => { cleared.push(id); };
+
+      const view = new GameView();
+      const timer = {
+        suspend() {},
+        continue() {}
+      };
+      view.game = { getGameTimer() { return timer; } };
+      view.stage = {
+        guiImgProps: { x: 0, y: 0, viewPoint: { scale: 1 } },
+        startOverlayFade() {}
+      };
+      view.resumeTimer = 7;
+      globalThis.window = undefined;
+
+      expect(() => view.suspendWithColor('red')).to.not.throw();
+      expect(cleared).to.deep.equal([7]);
+      expect(view.resumeTimer).to.equal(19);
+    } finally {
+      globalThis.setTimeout = originalSetTimeout;
+      globalThis.clearTimeout = originalClearTimeout;
+    }
+  });
+
+  it('uses global clearTimeout fallbacks in load paths when window is unavailable', async function() {
+    globalThis.window = { location: { search: '' } };
+    const originalClearTimeout = globalThis.clearTimeout;
+    const cleared = [];
+    try {
+      globalThis.clearTimeout = (id) => { cleared.push(id); };
+      const view = new GameView();
+      view.autoMoveTimer = 41;
+      globalThis.window = undefined;
+      await view.loadLevel();
+      expect(view.autoMoveTimer).to.equal(null);
+
+      view.autoMoveTimer = 42;
+      await view.loadEditorPreviewLevel();
+      expect(view.autoMoveTimer).to.equal(null);
+      expect(cleared).to.deep.equal([41, 42]);
+    } finally {
+      globalThis.clearTimeout = originalClearTimeout;
+    }
+  });
+
+  it('covers MIDI mapping fallback and disabled routing', async function() {
+    const view = new GameView();
+    view.gameFactory = {
+      fileProvider: { loadString: async () => { throw new Error('nope'); } }
+    };
+    const mapping = await view._loadMidiMapping();
+    expect(mapping).to.be.instanceOf(MidiMapping);
+
+    view.midiEnabled = false;
+    view.midiRouter = { detach() { view.detached = true; }, scheduler: { allNotesOff() { view.off = true; } } };
+    const result = await view.initMidiRouting();
+    expect(result).to.equal(null);
+    expect(view.detached).to.equal(true);
+    expect(view.off).to.equal(true);
+  });
+
+  it('covers moveToLevel negative wrap and invalid game types', async function() {
+    setDependency('GameTypes', { length: 1, toString() { return 'Pack'; } });
+    const view = new GameView();
+    view.gameFactory = {
+      async getConfig() { return { level: { order: [[]] } }; },
+      async getGameResources() { return {}; }
+    };
+    view.editorMode = true;
+    view.autoExitEditorOnSelect = true;
+    view.exitEditorMode = () => { view.exited = true; };
+    view.loadEditorLevelFromSelection = async () => { view.loadedEditor = true; };
+    view.loadLevel = async () => { view.loaded = true; };
+    await view.moveToLevel(-1);
+    expect(view.levelIndex).to.equal(0);
+    expect(view.exited).to.equal(true);
+    expect(view.loadedEditor).to.equal(true);
+  });
+
+  it('covers selection list empty branches', async function() {
+    const view = new GameView();
+    view.elementSelectLevel = makeSelect();
+    view.gameResources = { getLevelGroups() { return ['One']; } };
+    view._getSavedLevelEntries = () => [];
+    view._isSavedGroupIndex = () => false;
+    view.gameFactory = { async getConfig() { return { level: { getGroupLength() { return 0; } } }; } };
+    view.levelIndex = 5;
+    await view.populateLevelSelect();
+    expect(view.levelIndex).to.equal(0);
+  });
+
+  it('covers selectLevel outside editor mode', async function() {
+    const view = new GameView();
+    view.editorMode = false;
+    view.loadLevel = () => { view.loaded = true; };
+    await view.selectLevel(2);
+    expect(view.loaded).to.equal(true);
+  });
+
+  it('calls preview rendering from editor utilities', function() {
+    const view = new GameView();
+    let previewed = 0;
+    view.loadEditorPreviewLevel = async () => { previewed += 1; };
+    view.createBlankEditorLevel();
+    view.loadEditorLevelFromText('LEVELDATA');
+    expect(previewed).to.equal(2);
+  });
+
+  it('returns early when starting a level with an existing game', async function() {
+    const view = new GameView();
+    let continued = false;
+    view.game = { getGameTimer() { return { continue() { continued = true; } }; } };
+    view.continue = () => { continued = true; };
+    await view._startWithLevel({});
+    expect(continued).to.equal(true);
+  });
+
+  it('swallows errors when starting editor levels', async function() {
+    const view = new GameView();
+    view.gameResources = {};
+    view.gameFactory = { async getGame() { throw new Error('boom'); } };
+    await view._startWithLevel({});
+  });
+
+  it('loads editor previews with preserved view state', async function() {
+    globalThis.window = { location: { search: '' }, clearTimeout() {} };
+    globalThis.history = { replaceState() {} };
+    const view = new GameView();
+    view.autoMoveTimer = 1;
+    view.createBlankEditorLevel({ render: false });
+    view.editorMode = true;
+    view.editorPlaytest = true;
+    view.midiEnabled = true;
+    view.initMidiRouting = async () => { view.midiRouter = { attach() {} }; return view.midiRouter; };
+    const config = {
+      gametype: view.gameType,
+      path: 'lemmings',
+      level: { filePrefix: 'LEVEL', order: [[0]] },
+      mechanics: {}
+    };
+    view.gameResources = { config, getLevelGroups() { return []; } };
+    view.gameFactory = {
+      fileProvider: {
+        async loadBinary(path, filename) {
+          const data = readFileSync(new URL(`../${path}/${filename}`, import.meta.url));
+          return new BinaryReader(data, 0, data.length, filename, path);
+        }
+      },
+      async getGame() {
+        return {
+          level: null,
+          soundEvents: {},
+          onGameEnd: new EventHandler(),
+          loadLevel() {},
+          setGameDisplay() {},
+          setGuiDisplay() {},
+          getGameTimer() { return { speedFactor: 0, suspend() {}, continue() {} }; },
+          start() {},
+          stop() {},
+          cheat() {}
+        };
+      }
+    };
+    view.configs = [{ gametype: view.gameType, name: 'Pack' }];
+    view.elementSelectGameType = { selectedIndex: -1 };
+    view.elementSelectLevelGroup = { selectedIndex: -1 };
+    view.elementSelectLevel = { selectedIndex: -1 };
+    view.stage = {
+      panEnabled: false,
+      gameImgProps: { viewPoint: { x: 1, y: 2, scale: 1 }, canvasViewportSize: { width: 10, height: 10 } },
+      getGameDisplay() { return { clear() {}, initSize() {}, setBackground() {} }; },
+      getGuiDisplay() { return {}; },
+      resetFade() {},
+      updateStageSize() {},
+      applyViewport() {},
+      redraw() {},
+      setCursorSprite() {}
+    };
+    view.updateQuery = () => {};
+    view.applyLevelViewport = () => {};
+    await view.loadEditorPreviewLevel({ preserveView: true, suspend: false });
+  });
+
+  it('enables input and pan when not in editor mode', async function() {
+    globalThis.window = { location: { search: '' }, clearTimeout() {} };
+    globalThis.history = { replaceState() {} };
+    const view = new GameView();
+    view.autoMoveTimer = 1;
+    view.createBlankEditorLevel({ render: false });
+    view.editorMode = false;
+    view.editorPlaytest = false;
+    const config = {
+      gametype: view.gameType,
+      path: 'lemmings',
+      level: { filePrefix: 'LEVEL', order: [[0]] },
+      mechanics: {}
+    };
+    view.gameResources = { config, getLevelGroups() { return []; } };
+    view.gameFactory = {
+      fileProvider: {
+        async loadBinary(path, filename) {
+          const data = readFileSync(new URL(`../${path}/${filename}`, import.meta.url));
+          return new BinaryReader(data, 0, data.length, filename, path);
+        }
+      },
+      async getGame() {
+        return {
+          level: null,
+          soundEvents: {},
+          onGameEnd: new EventHandler(),
+          loadLevel() {},
+          setGameDisplay() {},
+          setGuiDisplay() {},
+          getGameTimer() { return { speedFactor: 0, suspend() {}, continue() {} }; },
+          start() {},
+          stop() {},
+          cheat() {},
+          inputEnabled: false
+        };
+      }
+    };
+    view.stage = {
+      panEnabled: false,
+      gameImgProps: { viewPoint: { x: 1, y: 2, scale: 1 }, canvasViewportSize: { width: 10, height: 10 } },
+      getGameDisplay() { return { clear() {}, initSize() {}, setBackground() {} }; },
+      getGuiDisplay() { return {}; },
+      resetFade() {},
+      updateStageSize() {},
+      applyViewport() {},
+      redraw() {},
+      setCursorSprite() {}
+    };
+    view.updateQuery = () => {};
+    view.applyLevelViewport = () => {};
+    await view.loadEditorPreviewLevel({ preserveView: false, suspend: false });
+    expect(view.game.inputEnabled).to.equal(true);
+    expect(view.stage.panEnabled).to.equal(true);
+  });
+});
diff --git a/test/gameview.coverage.05-gameview-coverage.test.js b/test/gameview.coverage.05-gameview-coverage.test.js
new file mode 100644
index 00000000..544f140c
--- /dev/null
+++ b/test/gameview.coverage.05-gameview-coverage.test.js
@@ -0,0 +1,246 @@
+import { readFileSync } from 'node:fs';
+import { expect } from 'chai';
+import { GameView } from '../js/game/GameView.js';
+import { BinaryReader } from '../js/data/BinaryReader.js';
+import { LevelReader } from '../js/level/LevelReader.js';
+import { MidiMapping } from '../js/midi/MidiMapping.js';
+import { toMidiFlagTriggerType } from '../js/midi/MidiFlagTriggers.js';
+import { EventHandler } from '../js/util/EventHandler.js';
+import { setDependency, resetDependencies, useGlobalLemmings } from './helpers/lemmings.js';
+import { useGlobalValueRestore } from './support/globals.js';
+import { runScenarioTable } from './support/scenario-table.js';
+
+describe('GameView coverage', function() {
+  useGlobalValueRestore(['window', 'history', 'WebMidi', 'localStorage', 'document']);
+
+  useGlobalLemmings({});
+
+  beforeEach(function() {
+    setDependency('GameFactory', class { constructor() {} });
+    setDependency('KeyboardShortcuts', class { constructor() {} dispose() {} });
+  });
+
+  afterEach(function() {
+    resetDependencies();
+  });
+
+  const makeSelect = () => ({
+    options: [],
+    selectedIndex: -1,
+    appendChild(el) {
+      this.options.push(el);
+      return el;
+    },
+    remove(idx) {
+      this.options.splice(idx, 1);
+    }
+  });
+
+  const stubDocument = () => {
+    globalThis.document = {
+      createElement() {
+        return { textContent: '', value: '' };
+      }
+    };
+  };
+
+  it('clamps saved level index when out of range', async function() {
+    globalThis.window = { location: { search: '' } };
+    globalThis.localStorage = {
+      store: new Map(),
+      getItem(key) { return this.store.get(key) ?? null; },
+      setItem(key, value) { this.store.set(key, value); },
+      removeItem(key) { this.store.delete(key); }
+    };
+    globalThis.localStorage.setItem(
+      'lemmings.editor.levels',
+      JSON.stringify([{ id: 'lvl-1', name: 'Saved Level', updatedAt: 1 }])
+    );
+    globalThis.localStorage.setItem(
+      'lemmings.editor.level.lvl-1',
+      'LEVELDATA'
+    );
+
+    const view = new GameView();
+    view.gameResources = {};
+    view.gameFactory = {};
+    view.includeSavedLevels = true;
+    view.levelIndex = 5;
+    view.loadEditorPreviewLevel = async () => 'preview';
+
+    const result = await view.loadSavedLevelFromSelection();
+
+    expect(result).to.equal('preview');
+    expect(view.levelIndex).to.equal(0);
+  });
+
+  it('loads classic levels when data is available', async function() {
+    globalThis.window = { location: { search: '' } };
+    const view = new GameView();
+    const data = readFileSync(new URL('../lemmings/LEVEL000.DAT', import.meta.url));
+    view.gameFactory = {
+      fileProvider: {
+        async loadBinary(path, filename) {
+          return new BinaryReader(data, 0, data.length, filename, path);
+        }
+      },
+      async getConfig() {
+        return {
+          path: 'lemmings',
+          level: {
+            filePrefix: 'LEVEL',
+            order: [[0]]
+          }
+        };
+      }
+    };
+
+    const reader = await view._loadClassicLevelReader(1, 0, 0);
+
+    expect(reader).to.be.instanceOf(LevelReader);
+  });
+
+  it('loads editor preview levels end-to-end', async function() {
+    globalThis.window = {
+      location: { search: '' },
+      clearTimeout() {}
+    };
+    globalThis.history = { replaceState() {} };
+    const view = new GameView();
+    view.createBlankEditorLevel({ render: false });
+    const config = {
+      gametype: view.gameType,
+      path: 'lemmings',
+      level: { filePrefix: 'LEVEL', order: [[0]] },
+      mechanics: {}
+    };
+    view.gameResources = { config, getLevelGroups() { return []; } };
+    view.gameFactory = {
+      fileProvider: {
+        async loadBinary(path, filename) {
+          const data = readFileSync(new URL(`../${path}/${filename}`, import.meta.url));
+          return new BinaryReader(data, 0, data.length, filename, path);
+        }
+      },
+      async getGame() {
+        return {
+          level: null,
+          soundEvents: {},
+          onGameEnd: new EventHandler(),
+          loadLevel() {},
+          setGameDisplay() {},
+          setGuiDisplay() {},
+          getGameTimer() { return { speedFactor: 0, suspend() {}, continue() {} }; },
+          start() {},
+          stop() {},
+          cheat() {}
+        };
+      }
+    };
+    view.stage = {
+      gameImgProps: { viewPoint: { x: 0, y: 0, scale: 1 }, canvasViewportSize: { width: 10, height: 10 } },
+      getGameDisplay() {
+        return {
+          clear() {},
+          initSize() {},
+          setBackground() {}
+        };
+      },
+      getGuiDisplay() { return {}; },
+      resetFade() {},
+      updateStageSize() {},
+      applyViewport() {},
+      redraw() {},
+      setCursorSprite() {}
+    };
+    view.updateQuery = () => {};
+    view.applyLevelViewport = () => {};
+
+    const level = await view.loadEditorPreviewLevel();
+
+    expect(level).to.not.equal(null);
+  });
+
+  it('loads editor levels from classic readers', async function() {
+    globalThis.window = { location: { search: '' } };
+    const view = new GameView();
+    view.game = { getGameTimer() { return { isRunning() { return false; }, suspend() {} }; } };
+    view.stage = { panEnabled: true };
+    view.levelGroupIndex = 0;
+    view.levelIndex = 0;
+    view._loadClassicLevelReader = async () => ({
+      graphicSet1: 0,
+      levelProperties: {
+        levelName: 'Classic',
+        releaseCount: 10,
+        needCount: 5,
+        releaseRate: 50,
+        timeLimit: 3,
+        skills: []
+      },
+      levelWidth: 160,
+      levelHeight: 80,
+      screenPositionX: 12,
+      terrains: [],
+      objects: [],
+      steel: []
+    });
+    let previewed = false;
+    view.loadEditorPreviewLevel = async () => { previewed = true; return 'preview'; };
+
+    const level = await view.loadEditorLevelFromSelection();
+
+    expect(level).to.equal(view.editorSession.level);
+    expect(previewed).to.equal(true);
+    expect(view.editorMode).to.equal(true);
+  });
+
+  it('disposes shortcuts, midi, and stage handlers', function() {
+    const removed = [];
+    const clearedTimeouts = [];
+    globalThis.window = {
+      location: { search: '' },
+      removeEventListener(type) { removed.push(type); },
+      clearTimeout(id) { clearedTimeouts.push(id); }
+    };
+    const view = new GameView();
+    let shortcutsDisposed = false;
+    let midiDisposed = false;
+    let stageDisposed = false;
+    view.shortcuts = { dispose() { shortcutsDisposed = true; } };
+    view.midiRouter = { dispose() { midiDisposed = true; } };
+    view.autoMoveTimer = 41;
+    view.resumeTimer = 42;
+    view._stageResize = () => {};
+    view.stage = { dispose() { stageDisposed = true; } };
+
+    view.dispose();
+
+    expect(shortcutsDisposed).to.equal(true);
+    expect(midiDisposed).to.equal(true);
+    expect(stageDisposed).to.equal(true);
+    expect(clearedTimeouts).to.include.members([41, 42]);
+    expect(removed).to.include('resize');
+    expect(removed).to.include('orientationchange');
+  });
+
+  it('uses global clearTimeout fallback when window is unavailable during dispose', function() {
+    const clearedTimeouts = [];
+    globalThis.window = { location: { search: '' } };
+    const originalClearTimeout = globalThis.clearTimeout;
+    globalThis.clearTimeout = (id) => { clearedTimeouts.push(id); };
+    try {
+      const view = new GameView();
+      view.autoMoveTimer = 51;
+      view.resumeTimer = 52;
+      view.stage = null;
+      globalThis.window = undefined;
+
+      view.dispose();
+
+      expect(clearedTimeouts).to.include.members([51, 52]);
+    } finally {
+      globalThis.clearTimeout = originalClearTimeout;
+    }
+  });
+});
diff --git a/test/gameview.coverage.test.js b/test/gameview.coverage.test.js
deleted file mode 100644
index f3573aca..00000000
--- a/test/gameview.coverage.test.js
+++ /dev/null
@@ -1,1414 +0,0 @@
-import { readFileSync } from 'node:fs';
-import { expect } from 'chai';
-import { GameView } from '../js/game/GameView.js';
-import { BinaryReader } from '../js/data/BinaryReader.js';
-import { LevelReader } from '../js/level/LevelReader.js';
-import { MidiMapping } from '../js/midi/MidiMapping.js';
-import { EventHandler } from '../js/util/EventHandler.js';
-import { setDependency, resetDependencies, useGlobalLemmings } from './helpers/lemmings.js';
-
-describe('GameView coverage', function() {
-  const originalWindow = globalThis.window;
-  const originalHistory = globalThis.history;
-  const originalWebMidi = globalThis.WebMidi;
-  const originalOnMidiError = globalThis.onMidiError;
-  const originalOnEnabled = globalThis.onEnabled;
-  const originalLocalStorage = globalThis.localStorage;
-  const originalDocument = globalThis.document;
-  useGlobalLemmings({});
-
-  beforeEach(function() {
-    setDependency('GameFactory', class { constructor() {} });
-    setDependency('KeyboardShortcuts', class { constructor() {} dispose() {} });
-  });
-
-  afterEach(function() {
-    resetDependencies();
-    globalThis.window = originalWindow;
-    globalThis.history = originalHistory;
-    globalThis.WebMidi = originalWebMidi;
-    globalThis.onMidiError = originalOnMidiError;
-    globalThis.onEnabled = originalOnEnabled;
-    globalThis.localStorage = originalLocalStorage;
-    globalThis.document = originalDocument;
-  });
-
-  const makeSelect = () => ({
-    options: [],
-    selectedIndex: -1,
-    appendChild(el) {
-      this.options.push(el);
-      return el;
-    },
-    remove(idx) {
-      this.options.splice(idx, 1);
-    }
-  });
-
-  const stubDocument = () => {
-    globalThis.document = {
-      createElement() {
-        return { textContent: '', value: '' };
-      }
-    };
-  };
-
-  it('parses query params and updates history state', function() {
-    globalThis.window = {
-      location: { search: '?version=2&difficulty=2&level=3&speed=2.2&cheat=true&debug=true&bench=true&scale=0.5&shortcut=true' }
-    };
-    let replaced = null;
-    globalThis.history = {
-      replaceState(_state, _title, url) { replaced = url; }
-    };
-
-    const view = new GameView();
-    expect(view.gameType).to.equal(2);
-    expect(view.levelGroupIndex).to.equal(1);
-    expect(view.levelIndex).to.equal(2);
-    expect(view.gameSpeedFactor).to.equal(2);
-    expect(view.cheatEnabled).to.equal(true);
-    expect(view.benchReverse).to.equal(false);
-
-    view.updateQuery();
-    expect(replaced).to.include('?');
-    expect(replaced).to.include('v=2');
-    expect(replaced).to.include('d=2');
-    expect(replaced).to.include('_=true');
-
-    view.setHistoryState('a=1');
-    expect(replaced).to.equal('?a=1');
-  });
-
-  it('formats MIDI errors and handles WebMidi enable', async function() {
-    globalThis.window = { isSecureContext: false, location: { protocol: 'http:', hostname: 'example.com', search: '' } };
-    const view = new GameView();
-    expect(view._formatMidiEnableError({})).to.equal('WebMIDI requires HTTPS or localhost.');
-    globalThis.window.isSecureContext = true;
-    globalThis.window.location.protocol = 'https:';
-    expect(view._formatMidiEnableError({ name: 'NotAllowedError', message: 'permission' }))
-      .to.equal('WebMIDI permission denied. Check browser permissions.');
-    expect(view._formatMidiEnableError({ name: 'NotSupportedError' }))
-      .to.equal('WebMIDI is not supported in this browser.');
-
-    let errorMessage = null;
-    globalThis.onMidiError = msg => { errorMessage = msg; };
-    const missing = await view._ensureWebMidiEnabled();
-    expect(missing).to.equal(null);
-    expect(errorMessage).to.include('not supported');
-
-    let enabledCalled = false;
-    let onEnabledCalled = false;
-    globalThis.onEnabled = () => { onEnabledCalled = true; };
-    globalThis.WebMidi = {
-      enabled: false,
-      enable: async () => { enabledCalled = true; },
-      outputs: []
-    };
-    const view2 = new GameView();
-    const enabled = await view2._ensureWebMidiEnabled();
-    expect(enabled).to.equal(globalThis.WebMidi);
-    expect(enabledCalled).to.equal(true);
-    expect(onEnabledCalled).to.equal(true);
-  });
-
-  it('advances and rewinds frames', function() {
-    const view = new GameView();
-    let rendered = 0;
-    let truncated = null;
-    const timer = {
-      tickIndex: 7,
-      tickCalls: [],
-      tick(step) { this.tickCalls.push(step); this.tickIndex += step; }
-    };
-    view.game = {
-      getGameTimer() { return timer; },
-      history: { truncateAfter(idx) { truncated = idx; } },
-      timeTravel: { isReversing: true, stopReverse() { this.stopped = true; } },
-      gameGui: { gameTimeChanged: false },
-      render() { rendered += 1; }
-    };
-
-    view.nextFrame();
-    expect(view.game.timeTravel.stopped).to.equal(true);
-    expect(truncated).to.equal(7);
-    expect(timer.tickCalls[0]).to.equal(1);
-    expect(view.game.gameGui.gameTimeChanged).to.equal(true);
-    expect(rendered).to.equal(1);
-
-    view.game.timeTravel = { stepBackward(step) { this.step = step; } };
-    view.prevFrame();
-    expect(view.game.timeTravel.step).to.equal(1);
-  });
-
-  it('suspends with overlay and resumes', function() {
-    globalThis.window = {
-      location: { search: '' },
-      setTimeout(cb) { cb(); return 1; },
-      clearTimeout() {}
-    };
-    const view = new GameView();
-    const timer = {
-      suspendCalls: 0,
-      continueCalls: 0,
-      suspend() { this.suspendCalls += 1; },
-      continue() { this.continueCalls += 1; }
-    };
-    const overlay = { color: null, rect: null };
-    view.stage = {
-      guiImgProps: { viewPoint: { scale: 2 }, x: 0, y: 0 },
-      startOverlayFade(color, rect) { overlay.color = color; overlay.rect = rect; }
-    };
-    view.game = { getGameTimer() { return timer; } };
-    view.bench = true;
-    view.suspendWithColor('red');
-    expect(timer.suspendCalls).to.equal(1);
-    expect(timer.continueCalls).to.equal(1);
-    expect(overlay.color).to.equal('red');
-    expect(overlay.rect.width).to.equal(32);
-  });
-
-  it('toggles editor playtest state', function() {
-    const view = new GameView();
-    const timer = {
-      running: true,
-      isRunning() { return this.running; },
-      suspendCalls: 0,
-      continueCalls: 0,
-      suspend() { this.suspendCalls += 1; },
-      continue() { this.continueCalls += 1; }
-    };
-    view.stage = { panEnabled: true };
-    view.game = { inputEnabled: true, getGameTimer() { return timer; } };
-
-    view.enterEditorMode();
-    expect(view.editorMode).to.equal(true);
-    expect(view.stage.panEnabled).to.equal(false);
-    expect(view.game.inputEnabled).to.equal(false);
-
-    view.setEditorPlaytest(true);
-    expect(timer.continueCalls).to.equal(1);
-    expect(view.stage.panEnabled).to.equal(true);
-    expect(view.game.inputEnabled).to.equal(true);
-
-    view.setEditorPlaytest(false);
-    expect(timer.suspendCalls).to.equal(2);
-    expect(view.stage.panEnabled).to.equal(false);
-    expect(view.game.inputEnabled).to.equal(false);
-
-    view.exitEditorMode();
-    expect(timer.continueCalls).to.equal(2);
-    expect(view.stage.panEnabled).to.equal(true);
-    expect(view.game.inputEnabled).to.equal(true);
-  });
-
-  it('loads and renders levels when not using saved entries', async function() {
-    globalThis.window = { location: { search: '?benchSequence=true' } };
-    globalThis.history = { replaceState() {} };
-    const view = new GameView();
-    const level = {
-      screenPositionX: 6,
-      renderCalls: 0,
-      render() { this.renderCalls += 1; }
-    };
-    const gameDisplay = { clearCalls: 0, clear() { this.clearCalls += 1; } };
-    const stage = {
-      resetFadeCalls: 0,
-      updateCalls: 0,
-      applied: null,
-      redrawn: 0,
-      gameImgProps: { viewPoint: { scale: 1 }, canvasViewportSize: { width: 10, height: 10 } },
-      getGameDisplay() { return gameDisplay; },
-      resetFade() { this.resetFadeCalls += 1; },
-      updateStageSize() { this.updateCalls += 1; },
-      applyViewport(...args) { this.applied = args; },
-      redraw() { this.redrawn += 1; }
-    };
-    let started = false;
-    view.start = async () => { started = true; };
-    view.stage = stage;
-    view.gameResources = {
-      getLevelGroups() { return ['Only']; },
-      async getLevel() { return level; }
-    };
-    view.configs = [{ gametype: view.gameType }];
-    view.elementGameState = { innerText: '' };
-    view.elementSelectGameType = { selectedIndex: -1 };
-    view.elementSelectLevelGroup = { selectedIndex: -1 };
-    view.elementSelectLevel = { selectedIndex: -1 };
-
-    await view.loadLevel();
-    expect(gameDisplay.clearCalls).to.equal(1);
-    expect(stage.resetFadeCalls).to.equal(1);
-    expect(level.renderCalls).to.equal(1);
-    expect(stage.updateCalls).to.equal(1);
-    expect(stage.applied).to.not.equal(null);
-    expect(stage.redrawn).to.equal(1);
-    expect(started).to.equal(true);
-  });
-
-  it('routes loadLevel to saved selections', async function() {
-    globalThis.window = { location: { search: '' } };
-    const view = new GameView();
-    view.applyQuery = () => {};
-    view.includeSavedLevels = true;
-    view.gameResources = { getLevelGroups() { return []; } };
-    view._getSavedLevelEntries = () => ([{ id: 'one', name: 'Saved' }]);
-    view._isSavedGroupIndex = () => true;
-    let called = false;
-    view.loadSavedLevelFromSelection = async () => { called = true; return 'saved'; };
-    const result = await view.loadLevel();
-    expect(called).to.equal(true);
-    expect(result).to.equal('saved');
-  });
-
-  it('starts a game session and applies options', async function() {
-    globalThis.window = { location: { search: '?benchSequence=true' } };
-    globalThis.history = { replaceState() {} };
-    setDependency('GameFactory', class {
-      constructor() {}
-      async getGame() {
-        const timer = { speedFactor: 0 };
-        const history = { setPreserveFutureHistory(val) { this.enabled = val; } };
-        const game = {
-          level: { name: 'Level', entrances: [{ x: 0, y: 0 }] },
-          history,
-          onGameEnd: new EventHandler(),
-          setGameDisplay(display) { this.gameDisplay = display; },
-          setGuiDisplay(display) { this.guiGuiDisplay = display; },
-          getGameTimer() { return timer; },
-          start() { this.started = true; },
-          loadLevel() {},
-          cheat() { this.cheated = true; }
-        };
-        return game;
-      }
-    });
-    setDependency('KeyboardShortcuts', class { constructor() {} dispose() {} });
-
-    const view = new GameView();
-    view.gameResources = {};
-    view.stage = {
-      getGameDisplay() { return { id: 'game' }; },
-      getGuiDisplay() { return { id: 'gui' }; },
-      setCursorSprite() {},
-    };
-    view.applyLevelViewport = () => { view.viewportApplied = true; };
-    view.elementGameState = { innerText: '' };
-    view.preserveHistory = true;
-    view.cheatEnabled = true;
-    view.debug = true;
-    view.midiEnabled = true;
-    view.initMidiRouting = async () => {
-      view.midiRouter = { attach() { view.attached = true; } };
-      return view.midiRouter;
-    };
-
-    await view.start();
-    expect(view.game.started).to.equal(true);
-    expect(view.game.history.enabled).to.equal(true);
-    expect(view.viewportApplied).to.equal(true);
-    expect(view.game.cheated).to.equal(true);
-    expect(view.game.showDebug).to.equal(true);
-    expect(view.attached).to.equal(true);
-  });
-
-  it('handles saved level loading and editor text utilities', async function() {
-    globalThis.window = { location: { search: '' } };
-    const indexPayload = JSON.stringify([
-      { id: 'lvl-1', name: 'Saved Level', updatedAt: 1 }
-    ]);
-    globalThis.localStorage = {
-      getItem(key) {
-        if (key === 'lemmings.editor.levels') return indexPayload;
-        if (key === 'lemmings.editor.level.lvl-1') return 'LEVELDATA';
-        return null;
-      },
-      setItem() {},
-      removeItem() {}
-    };
-
-    const view = new GameView();
-    view.includeSavedLevels = true;
-    view.levelIndex = 0;
-    view.gameResources = {};
-    view.autoExitEditorOnSelect = true;
-    view.editorMode = true;
-    view.exitEditorMode = () => { view.exited = true; };
-    view.loadEditorPreviewLevel = async () => 'preview';
-
-    const result = await view.loadSavedLevelFromSelection();
-    expect(result).to.equal('preview');
-    expect(view.exited).to.equal(true);
-    expect(view.getEditorLevelText()).to.be.a('string');
-    expect(view.getEditorLevelTitle()).to.equal('Untitled');
-  });
-
-  it('initializes MIDI routing with overrides', async function() {
-    globalThis.window = { location: { search: '' } };
-    globalThis.lemmingsMidiOverrides = { position: { viewPan: false } };
-    globalThis.lemmingsMidiViewPan = true;
-    globalThis.WebMidi = { enabled: true, outputs: [{ id: 'out' }] };
-    setDependency('MidiEventRouter', class {
-      constructor(mapping) { this.mapping = mapping; this.scheduler = { allNotesOff() {} }; }
-      setOutput(output) { this.output = output; }
-      setMapping(mapping) { this.mapping = mapping; }
-      detach() { this.detached = true; }
-      dispose() { this.disposed = true; }
-    });
-    const view = new GameView();
-    view._ensureWebMidiEnabled = async () => ({ enabled: true, outputs: [{ id: 'out' }] });
-    view._loadMidiMapping = async () => {
-      view._midiBaseConfig = { position: {} };
-      return new MidiMapping({ position: {} });
-    };
-    view.midiEnabled = true;
-
-    const router = await view.initMidiRouting();
-    expect(router).to.equal(view.midiRouter);
-    expect(view.midiOut).to.eql({ id: 'out' });
-    expect(view.getMidiConfig().position.viewPan).to.equal(true);
-  });
-
-  it('disables MIDI routing cleanly', async function() {
-    const view = new GameView();
-    let detached = 0;
-    let allNotesOff = 0;
-    view.midiRouter = {
-      detach() { detached += 1; },
-      scheduler: { allNotesOff() { allNotesOff += 1; } }
-    };
-    await view.setMidiEnabled(false);
-    expect(detached).to.equal(1);
-    expect(allNotesOff).to.equal(1);
-  });
-
-  it('covers helpers and selection utilities', async function() {
-    stubDocument();
-    globalThis.window = { location: { search: '' } };
-    const view = new GameView();
-    const select = makeSelect();
-    select.options.push({ value: '1' }, { value: '2' });
-    view.clearHtmlList(select);
-    expect(select.options.length).to.equal(0);
-
-    expect(view.prefixNumbers(['A', 'B'])).to.eql(['1 - A', '2 - B']);
-    expect(view.strToNum('5')).to.equal(5);
-    expect(view.strToNum('nope')).to.equal(0);
-
-    view.arrayToSelect(select, ['X', 'Y']);
-    expect(select.options.length).to.equal(2);
-
-    view.gameResources = { getLevelGroups() { return ['One', 'Two']; } };
-    view.includeSavedLevels = true;
-    const groups = view._getGroupNames([{ id: 'a', name: 'Saved' }]);
-    expect(groups).to.eql(['One', 'Two', 'Saved Levels']);
-
-    const config = {
-      level: {
-        order: [[1], []],
-        getGroupLength(index) {
-          return index === 0 ? 1 : 0;
-        }
-      }
-    };
-    view.levelGroupIndex = 1;
-    view.levelIndex = 4;
-    view._normalizeSelection(config, []);
-    expect(view.levelGroupIndex).to.equal(0);
-    expect(view.levelIndex).to.equal(0);
-
-    const emptyConfig = {
-      level: { order: [[], []], getGroupLength() { return 0; } }
-    };
-    view.levelGroupIndex = 1;
-    view.levelIndex = 2;
-    view._normalizeSelection(emptyConfig, []);
-    expect(view.levelGroupIndex).to.equal(0);
-    expect(view.levelIndex).to.equal(0);
-
-    view.elementSelectLevelGroup = select;
-    view.gameFactory = { async getConfig() { return config; } };
-    await view._syncLevelGroupSelect([]);
-    expect(view.elementSelectLevelGroup.selectedIndex).to.equal(0);
-
-    const stageImage = {
-      viewPoint: { scale: 2 },
-      canvasViewportSize: { width: 100, height: 50 }
-    };
-    const focus = view.getEntranceFocusX({ entrances: [{ x: 10, y: 0 }] }, stageImage);
-    expect(focus).to.equal(9);
-  });
-
-  it('populates level selections for saved and missing levels', async function() {
-    stubDocument();
-    const view = new GameView();
-    view.elementSelectLevel = makeSelect();
-    view.gameFactory = {
-      async getConfig() {
-        return { level: { getGroupLength() { return 2; } } };
-      }
-    };
-    view.gameResources = {
-      getLevelGroups() { return ['One']; },
-      async getLevel(_group, index) {
-        if (index === 0) return { name: 'Alpha' };
-        throw new Error('missing');
-      }
-    };
-
-    view.includeSavedLevels = true;
-    view.levelGroupIndex = 1;
-    view._getSavedLevelEntries = () => ([{ id: 's1', name: 'Saved' }]);
-    await view.populateLevelSelect();
-    expect(view.elementSelectLevel.options.length).to.equal(1);
-
-    view.includeSavedLevels = false;
-    view.levelGroupIndex = 0;
-    await view.populateLevelSelect();
-    expect(view.elementSelectLevel.options.length).to.equal(2);
-  });
-
-  it('selects levels, groups, and game types', async function() {
-    const view = new GameView();
-    view.gameResources = { getLevelGroups() { return ['One']; } };
-    view._getSavedLevelEntries = () => [];
-    view.populateLevelSelect = async () => { view.populated = true; };
-    view.loadLevel = () => { view.loaded = true; };
-
-    await view.selectLevelGroup(5);
-    expect(view.levelGroupIndex).to.equal(0);
-    expect(view.loaded).to.equal(true);
-
-    view.editorMode = true;
-    view.autoExitEditorOnSelect = true;
-    view.exitEditorMode = () => { view.exited = true; };
-    view.loadEditorLevelFromSelection = async () => { view.editorLoaded = true; };
-    await view.selectLevelGroup(0);
-    expect(view.exited).to.equal(true);
-    expect(view.editorLoaded).to.equal(true);
-
-    view.editorMode = false;
-    view.configs = [{ gametype: 2, name: 'Pack' }];
-    view.gameFactory = {
-      async getGameResources() { return { getLevelGroups() { return ['One']; } }; },
-      async getConfig() { return { level: { getGroupLength() { return 0; } } }; }
-    };
-    view._syncLevelGroupSelect = async () => { view.synced = true; };
-    view.populateLevelSelect = async () => { view.levelsPopulated = true; };
-    await view.selectGameType(0);
-    expect(view.gameType).to.equal(2);
-    expect(view.synced).to.equal(true);
-    expect(view.levelsPopulated).to.equal(true);
-
-    view.editorMode = true;
-    view.loadEditorLevelFromSelection = async () => { view.editorPicked = true; };
-    await view.selectLevel(3);
-    expect(view.levelIndex).to.equal(3);
-    expect(view.editorPicked).to.equal(true);
-  });
-
-  it('runs setup and setupEditor flows', async function() {
-    stubDocument();
-    globalThis.window = { location: { search: '' } };
-    const view = new GameView();
-    view._loadMidiMapping = async () => new MidiMapping({ position: {} });
-    globalThis.lemmingsMidiOverrides = { position: { viewPan: true } };
-    view.gameFactory = {
-      configReader: { configs: [{ gametype: 1, name: 'Pack' }] },
-      async getGameResources() {
-        return { getLevelGroups() { return ['One']; } };
-      }
-    };
-    view.elementSelectGameType = makeSelect();
-    view._syncLevelGroupSelect = async () => { view.groupSynced = true; };
-    view.populateLevelSelect = async () => { view.levelsSynced = true; };
-    view.loadLevel = async () => { view.didLoad = true; };
-    view.benchSequenceStart = async () => { view.benchRan = true; };
-
-    await view.setup();
-    expect(view.groupSynced).to.equal(true);
-    expect(view.levelsSynced).to.equal(true);
-    expect(view.didLoad).to.equal(true);
-    await view.benchSequenceStart();
-    expect(view.benchRan).to.equal(true);
-
-    view.benchSequence = false;
-    view.populateLevelSelect = async () => { view.editorLevels = true; };
-    await view.setupEditor();
-    expect(view.editorLevels).to.equal(true);
-  });
-
-  it('covers simple gameplay controls and canvas setup', async function() {
-    const events = [];
-    globalThis.window = {
-      location: { search: '' },
-      addEventListener(type) { events.push(type); },
-      removeEventListener(type) { events.push(`remove:${type}`); }
-    };
-    setDependency('Stage', class {
-      constructor() { this.disposed = false; }
-      scheduleUpdateStageSize() { this.scheduled = true; }
-      dispose() { this.disposed = true; }
-    });
-    const view = new GameView();
-    view.gameCanvas = {};
-    expect(events).to.include('resize');
-    view.gameCanvas = {};
-    expect(events).to.include('remove:resize');
-
-    let speed = 1;
-    const timer = {
-      suspendCalls: 0,
-      continueCalls: 0,
-      suspend() { this.suspendCalls += 1; },
-      continue() { this.continueCalls += 1; },
-      speedFactor: speed
-    };
-    view.game = {
-      getGameTimer() { return timer; },
-      setDebugMode(on) { this.debugOn = on; }
-    };
-
-    view.suspend();
-    view.continue();
-    view.selectSpeedFactor(3);
-    view.enableDebug();
-    view.playMusic();
-    view.stopMusic();
-    view.stopSound();
-    view.playSound();
-
-    expect(timer.suspendCalls).to.equal(1);
-    expect(timer.continueCalls).to.equal(1);
-    expect(timer.speedFactor).to.equal(3);
-    expect(view.game.debugOn).to.equal(true);
-  });
-
-  it('handles game end and replay flow', async function() {
-    globalThis.window = {
-      location: { search: '' },
-      setTimeout(cb) { cb(); return 1; },
-      clearTimeout() {}
-    };
-    setDependency('GameStateTypes', {
-      UNKNOWN: 0,
-      SUCCEEDED: 1,
-      toString() { return 'SUCCEEDED'; }
-    });
-    const view = new GameView();
-    view.stage = { startFadeOut() { view.faded = true; } };
-    view.elementGameState = { innerText: '' };
-    view.moveToLevel = (delta) => { view.moved = delta; };
-    view.onGameEnd({ state: 1 });
-    expect(view.faded).to.equal(true);
-    expect(view.moved).to.equal(1);
-
-    view.start = async () => { view.started = true; };
-    await view.loadReplay('abc');
-    expect(view.started).to.equal(true);
-  });
-
-  it('covers MIDI config loading and setters', async function() {
-    setDependency('GameFactory', class {
-      constructor() {
-        this.fileProvider = { loadString: async () => '{}' };
-      }
-    });
-    setDependency('KeyboardShortcuts', class { constructor() {} dispose() {} });
-    const view = new GameView();
-    const mapping = await view._loadMidiMapping();
-    expect(mapping).to.be.instanceOf(MidiMapping);
-    expect(view.getMidiBaseConfig()).to.be.an('object');
-    expect(view.getMidiSchemaHash()).to.be.a('string');
-
-    view.midiRouter = { setOutput(out) { this.output = out; } };
-    view.midiOut = { id: 'dev' };
-    expect(view.midiRouter.output).to.eql({ id: 'dev' });
-  });
-
-  it('toggles editor mode and creates editor levels', function() {
-    globalThis.window = { location: { search: '' } };
-    const view = new GameView();
-    view.stage = { panEnabled: true };
-    view.game = { inputEnabled: true, getGameTimer() { return { isRunning() { return false; } }; } };
-
-    view.toggleEditorMode();
-    expect(view.editorMode).to.equal(true);
-    view.toggleEditorMode();
-    expect(view.editorMode).to.equal(false);
-
-    const blank = view.createBlankEditorLevel({ render: false });
-    expect(blank).to.equal(view.editorSession.level);
-    const fromText = view.loadEditorLevelFromText('LEVEL', { render: false });
-    expect(fromText).to.equal(view.editorSession.level);
-    expect(blank).to.not.equal(fromText);
-  });
-
-  it('starts with custom levels and refreshes saved lists', async function() {
-    const view = new GameView();
-    view.gameResources = {};
-    view.stage = {
-      getGameDisplay() { return {}; },
-      getGuiDisplay() { return {}; },
-      setCursorSprite() {}
-    };
-    view.applyLevelViewport = () => { view.viewportApplied = true; };
-    view.elementGameState = { innerText: '' };
-    view.gameSpeedFactor = 2;
-    view.gameFactory = {
-      async getGame() {
-        return {
-          level: { name: 'Custom' },
-          soundEvents: {},
-          onGameEnd: new EventHandler(),
-          getGameTimer() { return { speedFactor: 0 }; },
-          loadLevel() {},
-          setGameDisplay() {},
-          setGuiDisplay() {},
-          start() { view.customStarted = true; },
-          cheat() { view.customCheat = true; }
-        };
-      }
-    };
-    view.cheatEnabled = true;
-    await view._startWithLevel({ name: 'Custom' });
-    expect(view.customStarted).to.equal(true);
-
-    view.includeSavedLevels = true;
-    view.gameResources.getLevelGroups = () => ['One'];
-    view._getSavedLevelEntries = () => ([{ id: 'a', name: 'Saved' }]);
-    view._syncLevelGroupSelect = async () => { view.synced = true; };
-    view.populateLevelSelect = async () => { view.populated = true; };
-    view._isSavedGroupIndex = () => true;
-    view.loadSavedLevelFromSelection = async () => { view.savedLoaded = true; };
-    await view.refreshSavedLevels();
-    expect(view.savedLoaded).to.equal(true);
-  });
-
-  it('covers editor preview early exits and classic reader checks', async function() {
-    globalThis.window = { location: { search: '' }, clearTimeout() {} };
-    const view = new GameView();
-    view.gameFactory = { async getConfig() { return { gametype: 1, level: { order: [] } }; } };
-    view.gameResources = { config: null };
-    view.editorSession = { level: {} };
-    view.game = { stop() { view.stopped = true; } };
-    view.midiRouter = { detach() { view.detached = true; } };
-    view.elementGameState = { innerText: '' };
-    const preview = await view.loadEditorPreviewLevel();
-    expect(preview).to.equal(null);
-    expect(view.stopped).to.equal(true);
-
-    const none = await view._loadClassicLevelReader(1, 0, 0);
-    expect(none).to.equal(null);
-
-    view.gameFactory = {
-      fileProvider: {},
-      async getConfig() { return null; }
-    };
-    const none2 = await view._loadClassicLevelReader(1, 0, 0);
-    expect(none2).to.equal(null);
-
-    view.gameFactory = {
-      fileProvider: { loadBinary: async () => new Uint8Array(0) },
-      async getConfig() {
-        return { path: '.', level: { order: [[]], filePrefix: 'L' } };
-      }
-    };
-    const none3 = await view._loadClassicLevelReader(1, 5, 5);
-    expect(none3).to.equal(null);
-  });
-
-  it('covers bench routines and sequence setup', async function() {
-    setDependency('TriggerTypes', {
-      DROWN: 1,
-      FRYING: 2,
-      KILL: 3,
-      TRAP: 4
-    });
-    setDependency('Lemming', class { static LEM_MAX_FALLING = 20; });
-    const view = new GameView();
-    view.loadLevel = async () => {};
-    view.configs = [{ gametype: view.gameType, name: 'Pack' }];
-    view._getSavedLevelEntries = () => [];
-
-    const level = {
-      width: 20,
-      height: 20,
-      name: 'Bench',
-      entrances: [{ x: 2, y: 2 }],
-      triggers: [],
-      getGroundMaskLayer() {
-        return {
-          hasGroundAt() { return false; },
-          countMaskInRect() { return 0; }
-        };
-      }
-    };
-    const lm = {
-      spawnCount: 0,
-      spawnTotal: 0,
-      getLemmings() { return []; }
-    };
-    const timer = {
-      speedFactor: 1,
-      benchStartupFrames: 0,
-      benchStableFactor: 0,
-      TIME_PER_FRAME_MS: 60,
-      getGameTime() { return 0; },
-      eachGameSecond: new EventHandler(),
-      suspend() {}
-    };
-    view.game = {
-      level,
-      getLemmingManager() { return lm; },
-      getGameTimer() { return timer; },
-      getVictoryCondition() { return { releaseRate: 1, getMinReleaseRate() { return 1; } }; }
-    };
-    view.stage = { applyLevelViewport() {} };
-    view.applyLevelViewport = () => { view.viewportApplied = true; };
-    view._benchCounts = [1];
-
-    await view.benchStart(1);
-    expect(timer.speedFactor).to.equal(6);
-    expect(timer.benchStartupFrames).to.equal(120);
-
-    const timer2 = {
-      speedFactor: 10,
-      benchStartupFrames: 0,
-      benchStableFactor: 0,
-      getGameTime() { return 120; },
-      eachGameSecond: new EventHandler(),
-      suspend() { view.suspended = true; }
-    };
-    const lm2 = { spawnTotal: 0, spawnCount: 1 };
-    view.game = {
-      level,
-      getLemmingManager() { return lm2; },
-      getVictoryCondition() { return { getMinReleaseRate() { return 1; }, releaseRate: 1 }; },
-      getGameTimer() { return timer2; }
-    };
-    const extrasPromise = view.benchMeasureExtras();
-    await Promise.resolve();
-    timer2.eachGameSecond.trigger();
-    const extras = await extrasPromise;
-    expect(extras).to.equal(0);
-    expect(view.suspended).to.equal(true);
-
-    view.benchMeasureExtras = async () => 2;
-    view.benchStart = async () => { view.sequenceStarted = true; };
-    await view.benchSequenceStart();
-    expect(view.sequenceStarted).to.equal(true);
-  });
-
-  it('short-circuits start and controls when no game is active', async function() {
-    const view = new GameView();
-    view.gameFactory = null;
-    await view.start();
-    view.cheat();
-    view.suspend();
-    view.continue();
-    view.suspendWithColor('red');
-    view.nextFrame();
-    view.prevFrame();
-    view.selectSpeedFactor(3);
-    view.enableDebug();
-  });
-
-  it('continues when start is called with an existing game', async function() {
-    const view = new GameView();
-    let continued = false;
-    view.game = { getGameTimer() { return { continue() { continued = true; } }; } };
-    view.continue = () => { continued = true; };
-    await view.start();
-    expect(continued).to.equal(true);
-  });
-
-  it('handles game end for non-success results', function() {
-    globalThis.window = {
-      location: { search: '' },
-      setTimeout(cb) { cb(); return 1; }
-    };
-    setDependency('GameStateTypes', {
-      UNKNOWN: 0,
-      SUCCEEDED: 1,
-      toString() { return 'FAILED'; }
-    });
-    const view = new GameView();
-    view.stage = { startFadeOut() {} };
-    view.elementGameState = { innerText: '' };
-    view.moveToLevel = delta => { view.moved = delta; };
-    view.onGameEnd({ state: 0 });
-    expect(view.moved).to.equal(0);
-  });
-
-  it('formats MIDI errors for security and empty messages', function() {
-    globalThis.window = { isSecureContext: true, location: { protocol: 'https:', hostname: 'example.com', search: '' } };
-    const view = new GameView();
-    expect(view._formatMidiEnableError({ name: 'SecurityError', message: 'secure context' }))
-      .to.equal('WebMIDI requires HTTPS or localhost.');
-    expect(view._formatMidiEnableError(''))
-      .to.equal('WebMIDI enable failed.');
-  });
-
-  it('reports WebMidi enable failures', async function() {
-    globalThis.window = { isSecureContext: true, location: { protocol: 'https:', hostname: 'example.com', search: '' } };
-    let errorMessage = null;
-    globalThis.onMidiError = msg => { errorMessage = msg; };
-    globalThis.WebMidi = {
-      enabled: false,
-      enable: async () => { throw new Error('boom'); }
-    };
-    const view = new GameView();
-    const result = await view._ensureWebMidiEnabled();
-    expect(result).to.equal(null);
-    expect(errorMessage).to.contain('WebMIDI enable failed');
-  });
-
-  it('attaches MIDI routing when enabled and game has sound events', async function() {
-    const view = new GameView();
-    view.game = { soundEvents: {}, getGameTimer() { return { continue() {} }; } };
-    view.stage = {};
-    view.midiRouter = { attach() {}, detach() {}, scheduler: { allNotesOff() {} } };
-    view.initMidiRouting = async () => view.midiRouter;
-    await view.setMidiEnabled(true);
-  });
-
-  it('covers helper branches for selection utilities', function() {
-    const view = new GameView();
-    view.includeSavedLevels = true;
-    view.gameResources = { getLevelGroups() { return []; } };
-    expect(view._getGroupLength({}, 0, 0, [{ id: 'a' }])).to.equal(1);
-
-    view.levelGroupIndex = 2;
-    view.levelIndex = 3;
-    view._normalizeSelection({}, []);
-    expect(view.levelGroupIndex).to.equal(0);
-    expect(view.levelIndex).to.equal(0);
-
-    const config = { level: { order: [[1]], getGroupLength() { return 1; } } };
-    view.levelGroupIndex = 0;
-    view.levelIndex = 5;
-    view._normalizeSelection(config, []);
-    expect(view.levelIndex).to.equal(0);
-
-    view.arrayToSelect(null, ['A']);
-    view.changeHtmlText(null, 'hi');
-  });
-
-  it('handles empty saved lists and editor selections', async function() {
-    stubDocument();
-    const view = new GameView();
-    view.elementSelectLevel = makeSelect();
-    view.gameResources = { getLevelGroups() { return ['One']; } };
-    view.gameFactory = { async getConfig() { return { level: { getGroupLength() { return 0; } } }; } };
-    view._getSavedLevelEntries = () => [];
-    view._isSavedGroupIndex = () => true;
-    view.levelGroupIndex = 0;
-    view.levelIndex = 3;
-    await view.populateLevelSelect();
-    expect(view.levelIndex).to.equal(0);
-
-    view.editorMode = true;
-    view.autoExitEditorOnSelect = true;
-    view.exitEditorMode = () => { view.exited = true; };
-    view.loadEditorLevelFromSelection = async () => { view.loadedEditor = true; };
-    view.gameFactory = {
-      async getGameResources() { return { getLevelGroups() { return ['One']; } }; },
-      async getConfig() { return { level: { getGroupLength() { return 0; } } }; }
-    };
-    view.configs = [{ gametype: 1 }];
-    await view.selectGameType(0);
-    expect(view.exited).to.equal(true);
-    expect(view.loadedEditor).to.equal(true);
-  });
-
-  it('updates bench setup when enabled', async function() {
-    stubDocument();
-    const view = new GameView();
-    view.benchSequence = true;
-    view.applyQuery = () => {};
-    view._loadMidiMapping = async () => new MidiMapping({ position: {} });
-    view.gameFactory = {
-      configReader: { configs: [{ gametype: 1, name: 'Pack' }] },
-      async getGameResources() { return { getLevelGroups() { return ['One']; } }; }
-    };
-    view.elementSelectGameType = makeSelect();
-    view._syncLevelGroupSelect = async () => {};
-    view.populateLevelSelect = async () => {};
-    view.loadLevel = async () => {};
-    view.benchSequenceStart = async () => { view.benchRan = true; };
-    await view.setup();
-    expect(view.benchRan).to.equal(true);
-  });
-
-  it('clears pending timers and replaces running games on load', async function() {
-    globalThis.window = { location: { search: '' }, clearTimeout() {} };
-    globalThis.history = { replaceState() {} };
-    const view = new GameView();
-    view.autoMoveTimer = 1;
-    view.gameResources = {
-      getLevelGroups() { return ['One']; },
-      async getLevel() { return { render() {}, screenPositionX: 0 }; }
-    };
-    view.stage = {
-      getGameDisplay() { return { clear() {}, initSize() {}, setBackground() {} }; },
-      resetFade() {},
-      updateStageSize() {},
-      applyViewport() {},
-      redraw() {}
-    };
-    view.applyLevelViewport = () => {};
-    view.game = { stop() { view.stopped = true; } };
-    view.midiRouter = { detach() { view.detached = true; } };
-    view.elementGameState = { innerText: '' };
-    view.configs = [{ gametype: view.gameType }];
-    await view.loadLevel();
-    expect(view.stopped).to.equal(true);
-    expect(view.detached).to.equal(true);
-  });
-
-  it('covers replay start, cheat, and frame helpers when game exists', async function() {
-    globalThis.window = {
-      location: { search: '' },
-      setTimeout(cb) { cb(); return 1; },
-      clearTimeout() {}
-    };
-    const view = new GameView();
-    let replayLoaded = null;
-    const timer = { continue() {}, suspend() {}, tick() {}, speedFactor: 0 };
-    view.gameFactory = {
-      async getGame() {
-        return {
-          level: {},
-          soundEvents: {},
-          onGameEnd: new EventHandler(),
-          getCommandManager() { return { loadReplay(str) { replayLoaded = str; } }; },
-          getGameTimer() { return timer; },
-          history: { truncateAfter() {} },
-          timeTravel: { stepBackward() {} },
-          render() {},
-          setGameDisplay() {},
-          setGuiDisplay() {},
-          loadLevel() {},
-          start() {},
-          cheat() { view.cheated = true; }
-        };
-      }
-    };
-    view.stage = {
-      getGameDisplay() { return {}; },
-      getGuiDisplay() { return {}; },
-      setCursorSprite() {}
-    };
-    view.applyLevelViewport = () => {};
-    await view.start('abc');
-    expect(replayLoaded).to.equal('abc');
-
-    view.cheat();
-    view.suspendWithColor('blue');
-    view.nextFrame();
-    view.prevFrame();
-    view.selectSpeedFactor(2);
-  });
-
-  it('draws overlay and resets timers in suspendWithColor', function() {
-    let timeoutCb = null;
-    let clearedId = null;
-    globalThis.window = {
-      location: { search: '' },
-      clearTimeout(id) { clearedId = id; },
-      setTimeout(cb) { timeoutCb = cb; return 7; }
-    };
-    const view = new GameView();
-    const timer = {
-      suspend() {},
-      continue() { view.continued = true; }
-    };
-    view.game = { getGameTimer() { return timer; } };
-    view.stage = {
-      guiImgProps: { x: 10, y: 20, viewPoint: { scale: 2 } },
-      startOverlayFade(color, rect) { view.overlay = { color, rect }; }
-    };
-    view.resumeTimer = 3;
-    view.bench = true;
-
-    view.suspendWithColor('red');
-    expect(clearedId).to.equal(3);
-    expect(view.resumeTimer).to.equal(7);
-    expect(view.overlay.rect).to.eql({ x: 330, y: 84, width: 32, height: 20 });
-
-    timeoutCb();
-    expect(view.continued).to.equal(true);
-    expect(view.resumeTimer).to.equal(null);
-  });
-
-  it('covers MIDI mapping fallback and disabled routing', async function() {
-    const view = new GameView();
-    view.gameFactory = {
-      fileProvider: { loadString: async () => { throw new Error('nope'); } }
-    };
-    const mapping = await view._loadMidiMapping();
-    expect(mapping).to.be.instanceOf(MidiMapping);
-
-    view.midiEnabled = false;
-    view.midiRouter = { detach() { view.detached = true; }, scheduler: { allNotesOff() { view.off = true; } } };
-    const result = await view.initMidiRouting();
-    expect(result).to.equal(null);
-    expect(view.detached).to.equal(true);
-    expect(view.off).to.equal(true);
-  });
-
-  it('covers moveToLevel negative wrap and invalid game types', async function() {
-    setDependency('GameTypes', { length: 1, toString() { return 'Pack'; } });
-    const view = new GameView();
-    view.gameFactory = {
-      async getConfig() { return { level: { order: [[]] } }; },
-      async getGameResources() { return {}; }
-    };
-    view.editorMode = true;
-    view.autoExitEditorOnSelect = true;
-    view.exitEditorMode = () => { view.exited = true; };
-    view.loadEditorLevelFromSelection = async () => { view.loadedEditor = true; };
-    view.loadLevel = async () => { view.loaded = true; };
-    await view.moveToLevel(-1);
-    expect(view.levelIndex).to.equal(0);
-    expect(view.exited).to.equal(true);
-    expect(view.loadedEditor).to.equal(true);
-  });
-
-  it('covers selection list empty branches', async function() {
-    const view = new GameView();
-    view.elementSelectLevel = makeSelect();
-    view.gameResources = { getLevelGroups() { return ['One']; } };
-    view._getSavedLevelEntries = () => [];
-    view._isSavedGroupIndex = () => false;
-    view.gameFactory = { async getConfig() { return { level: { getGroupLength() { return 0; } } }; } };
-    view.levelIndex = 5;
-    await view.populateLevelSelect();
-    expect(view.levelIndex).to.equal(0);
-  });
-
-  it('covers selectLevel outside editor mode', async function() {
-    const view = new GameView();
-    view.editorMode = false;
-    view.loadLevel = () => { view.loaded = true; };
-    await view.selectLevel(2);
-    expect(view.loaded).to.equal(true);
-  });
-
-  it('calls preview rendering from editor utilities', function() {
-    const view = new GameView();
-    let previewed = 0;
-    view.loadEditorPreviewLevel = async () => { previewed += 1; };
-    view.createBlankEditorLevel();
-    view.loadEditorLevelFromText('LEVELDATA');
-    expect(previewed).to.equal(2);
-  });
-
-  it('returns early when starting a level with an existing game', async function() {
-    const view = new GameView();
-    let continued = false;
-    view.game = { getGameTimer() { return { continue() { continued = true; } }; } };
-    view.continue = () => { continued = true; };
-    await view._startWithLevel({});
-    expect(continued).to.equal(true);
-  });
-
-  it('swallows errors when starting editor levels', async function() {
-    const view = new GameView();
-    view.gameResources = {};
-    view.gameFactory = { async getGame() { throw new Error('boom'); } };
-    await view._startWithLevel({});
-  });
-
-  it('loads editor previews with preserved view state', async function() {
-    globalThis.window = { location: { search: '' }, clearTimeout() {} };
-    globalThis.history = { replaceState() {} };
-    const view = new GameView();
-    view.autoMoveTimer = 1;
-    view.createBlankEditorLevel({ render: false });
-    view.editorMode = true;
-    view.editorPlaytest = true;
-    view.midiEnabled = true;
-    view.initMidiRouting = async () => { view.midiRouter = { attach() {} }; return view.midiRouter; };
-    const config = {
-      gametype: view.gameType,
-      path: 'lemmings',
-      level: { filePrefix: 'LEVEL', order: [[0]] },
-      mechanics: {}
-    };
-    view.gameResources = { config, getLevelGroups() { return []; } };
-    view.gameFactory = {
-      fileProvider: {
-        async loadBinary(path, filename) {
-          const data = readFileSync(new URL(`../${path}/${filename}`, import.meta.url));
-          return new BinaryReader(data, 0, data.length, filename, path);
-        }
-      },
-      async getGame() {
-        return {
-          level: null,
-          soundEvents: {},
-          onGameEnd: new EventHandler(),
-          loadLevel() {},
-          setGameDisplay() {},
-          setGuiDisplay() {},
-          getGameTimer() { return { speedFactor: 0, suspend() {}, continue() {} }; },
-          start() {},
-          stop() {},
-          cheat() {}
-        };
-      }
-    };
-    view.configs = [{ gametype: view.gameType, name: 'Pack' }];
-    view.elementSelectGameType = { selectedIndex: -1 };
-    view.elementSelectLevelGroup = { selectedIndex: -1 };
-    view.elementSelectLevel = { selectedIndex: -1 };
-    view.stage = {
-      panEnabled: false,
-      gameImgProps: { viewPoint: { x: 1, y: 2, scale: 1 }, canvasViewportSize: { width: 10, height: 10 } },
-      getGameDisplay() { return { clear() {}, initSize() {}, setBackground() {} }; },
-      getGuiDisplay() { return {}; },
-      resetFade() {},
-      updateStageSize() {},
-      applyViewport() {},
-      redraw() {},
-      setCursorSprite() {}
-    };
-    view.updateQuery = () => {};
-    view.applyLevelViewport = () => {};
-    await view.loadEditorPreviewLevel({ preserveView: true, suspend: false });
-  });
-
-  it('enables input and pan when not in editor mode', async function() {
-    globalThis.window = { location: { search: '' }, clearTimeout() {} };
-    globalThis.history = { replaceState() {} };
-    const view = new GameView();
-    view.autoMoveTimer = 1;
-    view.createBlankEditorLevel({ render: false });
-    view.editorMode = false;
-    view.editorPlaytest = false;
-    const config = {
-      gametype: view.gameType,
-      path: 'lemmings',
-      level: { filePrefix: 'LEVEL', order: [[0]] },
-      mechanics: {}
-    };
-    view.gameResources = { config, getLevelGroups() { return []; } };
-    view.gameFactory = {
-      fileProvider: {
-        async loadBinary(path, filename) {
-          const data = readFileSync(new URL(`../${path}/${filename}`, import.meta.url));
-          return new BinaryReader(data, 0, data.length, filename, path);
-        }
-      },
-      async getGame() {
-        return {
-          level: null,
-          soundEvents: {},
-          onGameEnd: new EventHandler(),
-          loadLevel() {},
-          setGameDisplay() {},
-          setGuiDisplay() {},
-          getGameTimer() { return { speedFactor: 0, suspend() {}, continue() {} }; },
-          start() {},
-          stop() {},
-          cheat() {},
-          inputEnabled: false
-        };
-      }
-    };
-    view.stage = {
-      panEnabled: false,
-      gameImgProps: { viewPoint: { x: 1, y: 2, scale: 1 }, canvasViewportSize: { width: 10, height: 10 } },
-      getGameDisplay() { return { clear() {}, initSize() {}, setBackground() {} }; },
-      getGuiDisplay() { return {}; },
-      resetFade() {},
-      updateStageSize() {},
-      applyViewport() {},
-      redraw() {},
-      setCursorSprite() {}
-    };
-    view.updateQuery = () => {};
-    view.applyLevelViewport = () => {};
-    await view.loadEditorPreviewLevel({ preserveView: false, suspend: false });
-    expect(view.game.inputEnabled).to.equal(true);
-    expect(view.stage.panEnabled).to.equal(true);
-  });
-
-  it('clamps saved level index when out of range', async function() {
-    globalThis.window = { location: { search: '' } };
-    globalThis.localStorage = {
-      store: new Map(),
-      getItem(key) { return this.store.get(key) ?? null; },
-      setItem(key, value) { this.store.set(key, value); },
-      removeItem(key) { this.store.delete(key); }
-    };
-    globalThis.localStorage.setItem(
-      'lemmings.editor.levels',
-      JSON.stringify([{ id: 'lvl-1', name: 'Saved Level', updatedAt: 1 }])
-    );
-    globalThis.localStorage.setItem(
-      'lemmings.editor.level.lvl-1',
-      'LEVELDATA'
-    );
-
-    const view = new GameView();
-    view.gameResources = {};
-    view.gameFactory = {};
-    view.includeSavedLevels = true;
-    view.levelIndex = 5;
-    view.loadEditorPreviewLevel = async () => 'preview';
-
-    const result = await view.loadSavedLevelFromSelection();
-
-    expect(result).to.equal('preview');
-    expect(view.levelIndex).to.equal(0);
-  });
-
-  it('loads classic levels when data is available', async function() {
-    globalThis.window = { location: { search: '' } };
-    const view = new GameView();
-    const data = readFileSync(new URL('../lemmings/LEVEL000.DAT', import.meta.url));
-    view.gameFactory = {
-      fileProvider: {
-        async loadBinary(path, filename) {
-          return new BinaryReader(data, 0, data.length, filename, path);
-        }
-      },
-      async getConfig() {
-        return {
-          path: 'lemmings',
-          level: {
-            filePrefix: 'LEVEL',
-            order: [[0]]
-          }
-        };
-      }
-    };
-
-    const reader = await view._loadClassicLevelReader(1, 0, 0);
-
-    expect(reader).to.be.instanceOf(LevelReader);
-  });
-
-  it('loads editor preview levels end-to-end', async function() {
-    globalThis.window = {
-      location: { search: '' },
-      clearTimeout() {}
-    };
-    globalThis.history = { replaceState() {} };
-    const view = new GameView();
-    view.createBlankEditorLevel({ render: false });
-    const config = {
-      gametype: view.gameType,
-      path: 'lemmings',
-      level: { filePrefix: 'LEVEL', order: [[0]] },
-      mechanics: {}
-    };
-    view.gameResources = { config, getLevelGroups() { return []; } };
-    view.gameFactory = {
-      fileProvider: {
-        async loadBinary(path, filename) {
-          const data = readFileSync(new URL(`../${path}/${filename}`, import.meta.url));
-          return new BinaryReader(data, 0, data.length, filename, path);
-        }
-      },
-      async getGame() {
-        return {
-          level: null,
-          soundEvents: {},
-          onGameEnd: new EventHandler(),
-          loadLevel() {},
-          setGameDisplay() {},
-          setGuiDisplay() {},
-          getGameTimer() { return { speedFactor: 0, suspend() {}, continue() {} }; },
-          start() {},
-          stop() {},
-          cheat() {}
-        };
-      }
-    };
-    view.stage = {
-      gameImgProps: { viewPoint: { x: 0, y: 0, scale: 1 }, canvasViewportSize: { width: 10, height: 10 } },
-      getGameDisplay() {
-        return {
-          clear() {},
-          initSize() {},
-          setBackground() {}
-        };
-      },
-      getGuiDisplay() { return {}; },
-      resetFade() {},
-      updateStageSize() {},
-      applyViewport() {},
-      redraw() {},
-      setCursorSprite() {}
-    };
-    view.updateQuery = () => {};
-    view.applyLevelViewport = () => {};
-
-    const level = await view.loadEditorPreviewLevel();
-
-    expect(level).to.not.equal(null);
-  });
-
-  it('loads editor levels from classic readers', async function() {
-    globalThis.window = { location: { search: '' } };
-    const view = new GameView();
-    view.game = { getGameTimer() { return { isRunning() { return false; }, suspend() {} }; } };
-    view.stage = { panEnabled: true };
-    view.levelGroupIndex = 0;
-    view.levelIndex = 0;
-    view._loadClassicLevelReader = async () => ({
-      graphicSet1: 0,
-      levelProperties: {
-        levelName: 'Classic',
-        releaseCount: 10,
-        needCount: 5,
-        releaseRate: 50,
-        timeLimit: 3,
-        skills: []
-      },
-      levelWidth: 160,
-      levelHeight: 80,
-      screenPositionX: 12,
-      terrains: [],
-      objects: [],
-      steel: []
-    });
-    let previewed = false;
-    view.loadEditorPreviewLevel = async () => { previewed = true; return 'preview'; };
-
-    const level = await view.loadEditorLevelFromSelection();
-
-    expect(level).to.equal(view.editorSession.level);
-    expect(previewed).to.equal(true);
-    expect(view.editorMode).to.equal(true);
-  });
-
-  it('disposes shortcuts, midi, and stage handlers', function() {
-    const removed = [];
-    globalThis.window = {
-      location: { search: '' },
-      removeEventListener(type) { removed.push(type); }
-    };
-    const view = new GameView();
-    let shortcutsDisposed = false;
-    let midiDisposed = false;
-    let stageDisposed = false;
-    view.shortcuts = { dispose() { shortcutsDisposed = true; } };
-    view.midiRouter = { dispose() { midiDisposed = true; } };
-    view._stageResize = () => {};
-    view.stage = { dispose() { stageDisposed = true; } };
-
-    view.dispose();
-
-    expect(shortcutsDisposed).to.equal(true);
-    expect(midiDisposed).to.equal(true);
-    expect(stageDisposed).to.equal(true);
-    expect(removed).to.include('resize');
-    expect(removed).to.include('orientationchange');
-  });
-});
diff --git a/test/gameview.movetolevel.test.js b/test/gameview.movetolevel.test.js
index 7ee4b1cd..730398e3 100644
--- a/test/gameview.movetolevel.test.js
+++ b/test/gameview.movetolevel.test.js
@@ -106,4 +106,52 @@ describe('GameView moveToLevel', function() {
       expectState(view, testCase.expected);
     });
   }
+
+  it('returns to the previous pack after crossing into the next pack boundary', async function() {
+    const denseConfigs = {
+      1: makeConfig([20, 20, 20, 20]),
+      2: makeConfig([20, 20, 20, 20])
+    };
+    setDependency('GameFactory', class {
+      constructor() {}
+      async getConfig(gameType) {
+        return denseConfigs[gameType] || makeConfig([0]);
+      }
+      async getGameResources(gameType) {
+        return { gameType };
+      }
+    });
+    setDependency('GameTypes', { length: 3 });
+
+    const view = makeView({ gameType: 1, levelGroupIndex: 3, levelIndex: 19 });
+    await view.moveToLevel(1);
+    expectState(view, { gameType: 2, levelGroupIndex: 0, levelIndex: 0 });
+
+    await view.moveToLevel(-1);
+    expectState(view, { gameType: 1, levelGroupIndex: 3, levelIndex: 19 });
+  });
+
+  it('wraps after the last level of pack 2 and still allows moving back to pack 2', async function() {
+    const denseConfigs = {
+      1: makeConfig([20, 20, 20, 20]),
+      2: makeConfig([20, 20, 20, 20])
+    };
+    setDependency('GameFactory', class {
+      constructor() {}
+      async getConfig(gameType) {
+        return denseConfigs[gameType] || makeConfig([0]);
+      }
+      async getGameResources(gameType) {
+        return { gameType };
+      }
+    });
+    setDependency('GameTypes', { length: 3 });
+
+    const view = makeView({ gameType: 2, levelGroupIndex: 3, levelIndex: 19 });
+    await view.moveToLevel(1);
+    expectState(view, { gameType: 1, levelGroupIndex: 0, levelIndex: 0 });
+
+    await view.moveToLevel(-1);
+    expectState(view, { gameType: 2, levelGroupIndex: 3, levelIndex: 19 });
+  });
 });
diff --git a/test/groundreader.test.js b/test/groundreader.test.js
index d893bfa1..f772705a 100644
--- a/test/groundreader.test.js
+++ b/test/groundreader.test.js
@@ -1,6 +1,5 @@
 import { expect } from 'chai';
 import { Lemmings, setDependency, useGlobalLemmings, withShowDebug } from './helpers/lemmings.js';
-import { withConsoleStub } from './helpers/console.js';
 import { BinaryReader } from '../js/data/BinaryReader.js';
 import '../js/data/BitReader.js';
 import '../js/data/BitWriter.js';
@@ -125,17 +124,21 @@ describe('GroundReader', function() {
   });
 
   it('returns early when ground file size is invalid', function() {
+    let gr = null;
     const logs = withMockLogHandler(() => {
       const br = new BinaryReader(new Uint8Array(10), 0, 10, 'bad.dat');
       const vgaT = new BinaryReader(new Uint8Array([0]));
       const vgaO = new BinaryReader(new Uint8Array([0]));
-      const gr = new GroundReader(br, vgaT, vgaO);
+      gr = new GroundReader(br, vgaT, vgaO);
       return gr.log.logged;
     });
     expect(logs.some(m => m.includes('wrong size'))).to.equal(true);
+    expect(gr.valid).to.equal(false);
+    expect(gr.imgTerrain).to.have.lengthOf(64);
+    expect(gr.imgObjects).to.have.lengthOf(16);
   });
 
-  it('loads steel sprites from disk when fetch fails', async function() {
+  it('uses bundled steel sprites when file-url fetch fails', async function() {
     const sprites = await withFetchStub(async () => { throw new Error('fail'); }, async () => {
       Lemmings.resetSteelSprites();
       return Lemmings.loadSteelSprites();
@@ -166,21 +169,21 @@ describe('GroundReader', function() {
   });
 
   it('logs when terrain folder name is unknown', function() {
-    const buf = new Uint8Array(1056);
-    const tOff = 28 * 16;
-    buf[tOff] = 1;
-    buf[tOff + 1] = 1;
-    buf[tOff + 5] = 3;
-    const pal = 960 + 24;
-    for (let i = 0; i < 48; i++) buf[pal + i] = 0;
-    const ground = new BinaryReader(buf, 0, buf.length, 'GROUND0O.DAT');
-    const vgaT = new BinaryReader(new Uint8Array([0, 0, 0, 0]));
-    const vgaO = new BinaryReader(new Uint8Array([0, 0, 0, 0, 0]));
-    const logs = [];
-    const restoreConsole = withConsoleStub({ log: (...args) => logs.push(args) });
-    new GroundReader(ground, vgaT, vgaO);
-    restoreConsole();
-    expect(logs.length).to.be.greaterThan(0);
+    const logs = withMockLogHandler(() => {
+      const buf = new Uint8Array(1056);
+      const tOff = 28 * 16;
+      buf[tOff] = 1;
+      buf[tOff + 1] = 1;
+      buf[tOff + 5] = 3;
+      const pal = 960 + 24;
+      for (let i = 0; i < 48; i++) buf[pal + i] = 0;
+      const ground = new BinaryReader(buf, 0, buf.length, 'GROUND0O.DAT');
+      const vgaT = new BinaryReader(new Uint8Array([0, 0, 0, 0]));
+      const vgaO = new BinaryReader(new Uint8Array([0, 0, 0, 0, 0]));
+      const reader = new GroundReader(ground, vgaT, vgaO);
+      return reader.log.logged;
+    });
+    expect(logs.some(m => m.includes('folder name for GROUND0O.DAT is unknown'))).to.equal(true);
   });
 
   it('logs when object data hits EOF', function() {
diff --git a/test/groundrenderer.test.js b/test/groundrenderer.test.js
index 7cc1affa..ae1ee2bc 100644
--- a/test/groundrenderer.test.js
+++ b/test/groundrenderer.test.js
@@ -4,6 +4,7 @@ import '../js/render/ColorPalette.js';
 import { DrawProperties } from '../js/render/DrawProperties.js';
 import { GroundRenderer } from '../js/render/GroundRenderer.js';
 import { DisplayImage } from '../js/render/DisplayImage.js';
+import { Frame } from '../js/render/Frame.js';
 
 class SimpleImageData {
   constructor(width, height) {
@@ -32,6 +33,10 @@ function makeTerrain(arr, width, height, palette) {
   return { width, height, frames: [Uint8Array.from(arr)], palette };
 }
 
+function makeRgbaTerrain(frame) {
+  return { width: frame.width, height: frame.height, frames: [frame], palette: null };
+}
+
 function color32(r, g, b) {
   return (0xFF000000 | (b & 0xFF) << 16 | (g & 0xFF) << 8 | (r & 0xFF)) >>> 0;
 }
@@ -145,4 +150,64 @@ describe('GroundRenderer small maps', function() {
     const BLACK = color32(0, 0, 0);
     expect(display.buffer32[0]).to.equal(BLACK);
   });
+
+  it('renders RGBA terrain frames with transparency masks', function() {
+    const rgba = new Frame(2, 1);
+    rgba.clear();
+    rgba.setPixel(0, 0, color32(9, 8, 7));
+    const terrainImages = [makeRgbaTerrain(rgba)];
+    const levelReader = {
+      levelWidth: 2,
+      levelHeight: 1,
+      terrains: [{ id: 0, x: 0, y: 0, drawProperties: new DrawProperties(false, false, false, false) }]
+    };
+
+    const gr = new GroundRenderer();
+    gr.createGroundMap(levelReader, terrainImages);
+
+    const stage = new MockStage();
+    const display = stage.getGameDisplay();
+    display.initSize(2, 1);
+    display.setBackground(gr.img.getData());
+
+    const BLACK = color32(0, 0, 0);
+    expect(Array.from(display.buffer32)).to.eql([color32(9, 8, 7), BLACK]);
+  });
+
+  it('downscales indexed terrain using sourceScale factors', function() {
+    const pal = makePalette(color32(2, 4, 6));
+    const src = {
+      width: 4,
+      height: 4,
+      frames: [Uint8Array.from([
+        1, 0x80, 1, 0x80,
+        0x80, 0x80, 0x80, 0x80,
+        1, 0x80, 0x80, 0x80,
+        0x80, 0x80, 0x80, 0x80
+      ])],
+      palette: pal,
+      sourceScaleX: 2,
+      sourceScaleY: 2
+    };
+    const levelReader = {
+      levelWidth: 2,
+      levelHeight: 2,
+      terrains: [{ id: 0, x: 0, y: 0, drawProperties: new DrawProperties(false, false, false, false) }]
+    };
+
+    const gr = new GroundRenderer();
+    gr.createGroundMap(levelReader, [src]);
+
+    const stage = new MockStage();
+    const display = stage.getGameDisplay();
+    display.initSize(2, 2);
+    display.setBackground(gr.img.getData());
+
+    const c = color32(2, 4, 6);
+    const BLACK = color32(0, 0, 0);
+    expect(Array.from(display.buffer32)).to.eql([
+      c, c,
+      c, BLACK
+    ]);
+  });
 });
diff --git a/test/helpers/lemmings.js b/test/helpers/lemmings.js
index b9f2bc72..e78860e6 100644
--- a/test/helpers/lemmings.js
+++ b/test/helpers/lemmings.js
@@ -3,7 +3,9 @@ import {
   getDependency,
   setDependency,
   clearDependency,
-  resetDependencies
+  resetDependencies,
+  getAppContext,
+  setAppContext
 } from '../../js/core/dependencies.js';
 
 const defaults = { ...Exports };
@@ -38,15 +40,25 @@ const Lemmings = new Proxy(defaults, {
 
 export { Lemmings, setDependency, clearDependency, resetDependencies };
 
+const setTestAppContext = (value) => {
+  const prevApp = getAppContext();
+  setAppContext(value || null);
+  return () => {
+    setAppContext(prevApp);
+  };
+};
+
 const setGlobalLemmings = (value) => {
   const prev = globalThis.lemmings;
   globalThis.lemmings = value;
+  const restoreApp = setTestAppContext(value);
   return () => {
     if (prev === undefined) {
       delete globalThis.lemmings;
     } else {
       globalThis.lemmings = prev;
     }
+    restoreApp();
   };
 };
 
@@ -72,13 +84,16 @@ const withGlobalLemmings = (value, fn) => {
 const withMissingGlobalLemmings = (fn) => {
   const hadProp = Object.prototype.hasOwnProperty.call(globalThis, 'lemmings');
   const prev = globalThis.lemmings;
+  const prevApp = getAppContext();
   delete globalThis.lemmings;
+  setAppContext(null);
   const restore = () => {
     if (hadProp) {
       globalThis.lemmings = prev;
     } else {
       delete globalThis.lemmings;
     }
+    setAppContext(prevApp);
   };
   try {
     const result = fn();
@@ -94,9 +109,9 @@ const withMissingGlobalLemmings = (fn) => {
 };
 
 const withShowDebug = (value, fn) => {
-  const game = globalThis.lemmings?.game;
+  const game = getAppContext()?.game;
   if (!game) {
-    throw new Error('globalThis.lemmings.game is required for withShowDebug');
+    throw new Error('app context with .game is required for withShowDebug');
   }
   const hadProp = Object.prototype.hasOwnProperty.call(game, 'showDebug');
   const prev = game.showDebug;
@@ -122,10 +137,28 @@ const withShowDebug = (value, fn) => {
 };
 
 const useGlobalLemmings = (value) => {
+  const cloneValue = (input) => {
+    if (Array.isArray(input)) {
+      return input.map(cloneValue);
+    }
+    if (input && typeof input === 'object') {
+      const proto = Object.getPrototypeOf(input);
+      if (proto === Object.prototype || proto === null) {
+        const copy = {};
+        for (const [key, val] of Object.entries(input)) {
+          copy[key] = cloneValue(val);
+        }
+        return copy;
+      }
+    }
+    return input;
+  };
+
   let restore;
   beforeEach(() => {
     const resolved = typeof value === 'function' ? value() : value;
-    restore = setGlobalLemmings(resolved);
+    const isolated = cloneValue(resolved);
+    restore = setGlobalLemmings(isolated);
   });
   afterEach(() => {
     restore();
@@ -133,6 +166,7 @@ const useGlobalLemmings = (value) => {
 };
 
 export {
+  setTestAppContext,
   setGlobalLemmings,
   withGlobalLemmings,
   withLemmingsGame,
diff --git a/test/helpers/test-dom.js b/test/helpers/test-dom.js
index 4305ef3a..93cdeef4 100644
--- a/test/helpers/test-dom.js
+++ b/test/helpers/test-dom.js
@@ -62,6 +62,7 @@ class TestElement {
     this.max = '';
     this.step = '';
     this._innerHTML = '';
+    this.ownerDocument = null;
   }
 
   set innerHTML(value) {
@@ -75,10 +76,36 @@ class TestElement {
 
   appendChild(child) {
     child.parent = this;
+    if (!child.ownerDocument) child.ownerDocument = this.ownerDocument;
     this.children.push(child);
     return child;
   }
 
+  append(...children) {
+    children.forEach(child => this.appendChild(child));
+  }
+
+  removeChild(child) {
+    const index = this.children.indexOf(child);
+    if (index >= 0) {
+      this.children.splice(index, 1);
+      child.parent = null;
+    }
+    return child;
+  }
+
+  get firstChild() {
+    return this.children[0] || null;
+  }
+
+  setAttribute(name, value) {
+    this.attributes.set(name, String(value));
+  }
+
+  getAttribute(name) {
+    return this.attributes.get(name) || null;
+  }
+
   addEventListener(type, handler) {
     if (!this.listeners.has(type)) this.listeners.set(type, []);
     this.listeners.get(type).push(handler);
@@ -88,6 +115,32 @@ class TestElement {
     const handlers = this.listeners.get(event.type) || [];
     handlers.forEach(handler => handler(event));
   }
+
+  focus() {
+    if (this.ownerDocument) this.ownerDocument.activeElement = this;
+  }
+
+  contains(candidate) {
+    if (candidate === this) return true;
+    return this.children.some(child => (
+      child === candidate ||
+      (typeof child.contains === 'function' && child.contains(candidate))
+    ));
+  }
+
+  querySelectorAll(selector) {
+    if (!selector || selector[0] !== '.') return [];
+    const className = selector.slice(1);
+    const matches = [];
+    const visit = (element) => {
+      for (const child of element.children) {
+        if (child.classList.contains(className)) matches.push(child);
+        visit(child);
+      }
+    };
+    visit(this);
+    return matches;
+  }
 }
 
 class TestDocument {
@@ -95,10 +148,12 @@ class TestDocument {
     this._elementsById = new Map();
     this._all = [];
     this.documentElement = { clientWidth: 800, clientHeight: 600 };
+    this.activeElement = null;
   }
 
   createElement(tagName) {
     const el = new TestElement(tagName);
+    el.ownerDocument = this;
     this._all.push(el);
     return el;
   }
diff --git a/test/history-store.basics.test.js b/test/history-store.basics.test.js
new file mode 100644
index 00000000..4749d725
--- /dev/null
+++ b/test/history-store.basics.test.js
@@ -0,0 +1,435 @@
+import { expect } from 'chai';
+import { withConsoleStub } from './helpers/console.js';
+import { HistoryStore, __test__ } from '../js/game/HistoryStore.js';
+import { SkillTypes } from '../js/game/SkillTypes.js';
+import { Trigger } from '../js/level/Trigger.js';
+import { TriggerTypes } from '../js/level/TriggerTypes.js';
+import { EventHandler } from '../js/util/EventHandler.js';
+import { runScenarioTable } from './support/scenario-table.js';
+import {
+  createHistoryFixture,
+  createStubTimer,
+  recordTick,
+  runHistoryOps,
+  scenario,
+  seedHistory
+} from './support/history-fixtures.js';
+
+describe('HistoryStore basics and scalar replay', function() {
+  it('captures lemming deltas and can replay them', function() {
+    const { history, game, timer, manager } = createHistoryFixture();
+    recordTick(history, timer, 0, () => {
+      manager.lemmings[0].x = 10;
+      manager.lemmings[0].y = 12;
+      manager.selectedIndex = 0;
+    });
+
+    const delta = history.getDelta(0);
+    expect(delta).to.be.ok;
+
+    history.applyDeltaBackward(game, delta);
+    expect(manager.lemmings[0].x).to.equal(5);
+    expect(manager.lemmings[0].y).to.equal(6);
+    expect(manager.selectedIndex).to.equal(-1);
+
+    history.applyDeltaForward(game, delta);
+    expect(manager.lemmings[0].x).to.equal(10);
+    expect(manager.lemmings[0].y).to.equal(12);
+    expect(manager.selectedIndex).to.equal(0);
+  });
+
+  it('keeps replay state equivalent across backward/forward delta cycles', function() {
+    const { history, game, timer, manager, triggerManager } = createHistoryFixture();
+    const owner = manager.lemmings[0];
+    const trigger = new Trigger(TriggerTypes.TRAP, 1, 1, 2, 2, 0, 0, owner);
+    triggerManager.add(trigger);
+
+    scenario(history, timer)
+      .tick(0, {
+        ops: [['recordTriggerCooldown', trigger, 0, 5]],
+        mutate() {
+          owner.x = 12;
+          owner.y = 9;
+          owner.lookRight = false;
+          manager.selectedIndex = owner.id;
+        }
+      })
+      .tick(1, {
+        mutate() {
+          owner.x = 14;
+          owner.y = 11;
+          manager.mmTickCounter = 7;
+        }
+      });
+
+    const delta = history.getDelta(1);
+    const baseline = history._captureKeyframe(game);
+
+    history.applyDeltaBackward(game, delta);
+    history.applyDeltaForward(game, delta);
+
+    const replayed = history._captureKeyframe(game);
+    expect(replayed).to.deep.equal(baseline);
+  });
+
+  it('truncates future history unless preservation is enabled', function() {
+    const history = new HistoryStore({ keyframeInterval: 5 });
+    seedHistory(history, { deltas: [0, 2], keyframes: [0, 2] });
+
+    history.truncateAfter(0);
+    expect(!!history.deltas[2]).to.equal(false);
+    expect(!!history.keyframes[2]).to.equal(false);
+
+    seedHistory(history, { deltas: [2], keyframes: [2] });
+    history.setPreserveFutureHistory(true);
+    history.truncateAfter(0);
+    expect(!!history.deltas[2]).to.equal(true);
+    expect(!!history.keyframes[2]).to.equal(true);
+  });
+
+  it('snapshots lemming boolean flags', function() {
+    const lem = {
+      id: 1,
+      x: 0,
+      y: 0,
+      lookRight: false,
+      frameIndex: 0,
+      state: 0,
+      canClimb: false,
+      hasParachute: true,
+      removed: true,
+      disabled: true,
+      countdown: 0,
+      hasExploded: false,
+      lastTriggerType: 1
+    };
+    const snap = __test__.snapshotLemming(lem, 2, true);
+    expect(snap.hasParachute).to.equal(1);
+    expect(snap.removed).to.equal(1);
+    expect(snap.disabled).to.equal(1);
+    expect(snap.countdownActive).to.equal(1);
+  });
+
+  it('handles keyframe access and resume without a game', function() {
+    const history = new HistoryStore();
+    expect(history.getKeyframe('bad')).to.equal(null);
+    history.resume();
+  });
+
+  it('uses fallback tick indices when timers are missing', function() {
+    const history = new HistoryStore({ keyframeInterval: 1 });
+    history._recording = true;
+    history._currentTick = 0;
+    history._currentDelta = history._allocDelta(0);
+    history.game = {};
+    history.timer = { tickIndex: undefined };
+    history._diffState = () => {};
+    history._compressGroundChanges = () => {};
+    history._setDelta = () => {};
+    history._captureKeyframe = () => ({ tickIndex: 0 });
+    let keyframeTick = null;
+    history._setKeyframe = (tickIndex) => { keyframeTick = tickIndex; };
+    history._maybeWarnHistory = () => {};
+    history._enforceHistoryCap = () => {};
+    history.endTick();
+    expect(keyframeTick).to.equal(1);
+  });
+
+  it('compares skill arrays with missing values', function() {
+    const history = new HistoryStore();
+    const a = { selectedSkill: 1, cheatMode: false };
+    const b = { selectedSkill: 1, cheatMode: false, skills: [1] };
+    expect(history._skillsEqual(a, b)).to.equal(false);
+  });
+
+  it('applies keyframes with lemming list resizing and speed ignores', function() {
+    const history = new HistoryStore();
+    const timer = { speedFactor: 2, tickIndex: 0 };
+    const manager = {
+      lemmings: [],
+      skillActions: [],
+      actions: [],
+      _lemmingCtor: function ReplayCtor(x, y, id) {
+        this.x = x;
+        this.y = y;
+        this.id = id;
+      }
+    };
+    const game = {
+      getLemmingManager: () => manager,
+      getGameTimer: () => timer,
+      timeTravel: { isReversing: true, ignoreSpeedOnReverse: true }
+    };
+    const stateSize = 2;
+    const keyframe = {
+      tickIndex: 1,
+      lemmingState: {
+        present: [true, true],
+        x: [0, 1],
+        y: [0, 1],
+        lookRight: [0, 1],
+        frameIndex: [0, 0],
+        state: [0, 0],
+        canClimb: [0, 0],
+        hasParachute: [0, 0],
+        removed: [0, 0],
+        disabled: [0, 0],
+        countdown: [0, 0],
+        hasExploded: [0, 0],
+        lastTriggerType: [-1, -1],
+        actionType: [-1, -1],
+        countdownActive: [0, 0]
+      },
+      timer: { speedFactor: 5, tickIndex: 1 }
+    };
+    history.applyKeyframe(game, keyframe);
+    expect(manager.lemmings).to.have.length(stateSize);
+    expect(timer.speedFactor).to.equal(2);
+  });
+
+  it('applies timer changes without overwriting reverse speed', function() {
+    const history = new HistoryStore();
+    const timer = { speedFactor: 3, tickIndex: 0 };
+    const game = {
+      getGameTimer: () => timer,
+      timeTravel: { ignoreSpeedOnReverse: true }
+    };
+    const delta = {
+      timerChanges: {
+        prev: { speedFactor: 10, tickIndex: 5 },
+        next: { speedFactor: 2, tickIndex: 2 }
+      }
+    };
+    history._applyScalarChanges(game, delta, false);
+    expect(timer.speedFactor).to.equal(3);
+    expect(timer.tickIndex).to.equal(5);
+  });
+
+  it('applies non-lemming deltas and scalar changes', function() {
+    const {
+      history,
+      game,
+      timer,
+      manager,
+      skills,
+      victory,
+      level
+    } = createHistoryFixture();
+
+    manager.miniMap = {
+      deadDots: new Uint8Array(0),
+      deadTTLs: new Uint8Array(0),
+      deadCount: 0
+    };
+
+    const obj = { animation: { firstFrameIndex: 0, isFinished: false } };
+    level.objects = [obj];
+    level.groundMask.mask[1] = 1;
+    level.groundMask.mask[2] = 1;
+    level.groundImage[4] = 10;
+    level.groundImage[5] = 20;
+    level.groundImage[6] = 30;
+    level.groundImage[8] = 11;
+    level.groundImage[9] = 21;
+    level.groundImage[10] = 31;
+
+    scenario(history, timer).tick(0, {
+      ops: [
+        ['recordGroundChange', 1, 1, 10, 20, 30, 0, 0, 0, 0],
+        ['recordGroundChange', 2, 1, 11, 21, 31, 0, 0, 0, 0],
+        ['recordEntranceChange', 0, false, true],
+        ['recordObjectAnimation', obj, { firstFrameIndex: 0, isFinished: false }, { firstFrameIndex: 5, isFinished: true }],
+        ['recordMinimapDeath', { x: 1, y: 2, ttl: 3, prevCount: 0 }]
+      ],
+      mutate() {
+        skills.selectedSkill = 1;
+        skills.cheatMode = true;
+        skills.skills[0] = 2;
+        victory.releaseRate = 2;
+        victory.leftCount = 0;
+        victory.outCount = 2;
+        victory.survivorCount = 1;
+        victory.isFinalize = true;
+        timer.speedFactor = 2;
+        game.finalGameState = 3;
+      }
+    });
+
+    const delta = history.getDelta(0);
+    history.applyDeltaForward(game, delta);
+
+    expect(level.groundMask.mask[1]).to.equal(0);
+    expect(level.groundMask.mask[2]).to.equal(0);
+    expect(level.groundImage[4]).to.equal(0);
+    expect(level.groundImage[8]).to.equal(0);
+    expect(level.entrances[0]._opened).to.equal(true);
+    expect(obj.animation.firstFrameIndex).to.equal(5);
+    expect(obj.animation.isFinished).to.equal(true);
+    expect(manager.miniMap.deadCount).to.equal(1);
+    expect(manager.miniMap.deadDots[0]).to.equal(1);
+    expect(manager.miniMap.deadDots[1]).to.equal(2);
+    expect(manager.miniMap.deadTTLs[0]).to.equal(3);
+    expect(skills.selectedSkill).to.equal(1);
+    expect(skills.cheatMode).to.equal(true);
+    expect(skills.skills[0]).to.equal(2);
+    expect(victory.releaseRate).to.equal(2);
+    expect(victory.leftCount).to.equal(0);
+    expect(victory.outCount).to.equal(2);
+    expect(victory.survivorCount).to.equal(1);
+    expect(victory.isFinalize).to.equal(true);
+    expect(timer.speedFactor).to.equal(2);
+    expect(timer.tickIndex).to.equal(1);
+    expect(game.finalGameState).to.equal(3);
+
+    history.applyDeltaBackward(game, delta);
+    expect(level.groundMask.mask[1]).to.equal(1);
+    expect(level.groundMask.mask[2]).to.equal(1);
+    expect(level.groundImage[4]).to.equal(10);
+    expect(level.groundImage[5]).to.equal(20);
+    expect(level.groundImage[6]).to.equal(30);
+    expect(level.groundImage[8]).to.equal(11);
+    expect(level.groundImage[9]).to.equal(21);
+    expect(level.groundImage[10]).to.equal(31);
+    expect(level.entrances[0]._opened).to.equal(false);
+    expect(obj.animation.firstFrameIndex).to.equal(0);
+    expect(obj.animation.isFinished).to.equal(false);
+    expect(manager.miniMap.deadCount).to.equal(0);
+    expect(skills.selectedSkill).to.equal(0);
+    expect(skills.cheatMode).to.equal(false);
+    expect(skills.skills[0]).to.equal(1);
+    expect(victory.releaseRate).to.equal(1);
+    expect(victory.leftCount).to.equal(1);
+    expect(victory.outCount).to.equal(0);
+    expect(victory.survivorCount).to.equal(0);
+    expect(victory.isFinalize).to.equal(false);
+    expect(timer.speedFactor).to.equal(1);
+    expect(timer.tickIndex).to.equal(0);
+    expect(game.finalGameState).to.equal(0);
+  });
+
+  it('applies trigger cooldown changes', function() {
+    const { history, game, timer, manager, triggerManager } = createHistoryFixture();
+    const owner = manager.lemmings[0];
+    const trigger = new Trigger(
+      TriggerTypes.TRAP,
+      1,
+      1,
+      2,
+      2,
+      5,
+      7,
+      owner
+    );
+    triggerManager.add(trigger);
+
+    scenario(history, timer).tick(0, {
+      ops: [['recordTriggerCooldown', trigger, 0, 5]]
+    });
+
+    const delta = history.getDelta(0);
+    history.applyDeltaForward(game, delta);
+    expect(trigger.disabledUntilTick).to.equal(5);
+    history.applyDeltaBackward(game, delta);
+    expect(trigger.disabledUntilTick).to.equal(0);
+  });
+
+  it('applies trigger add/remove deltas', function() {
+    const { history, game, timer, manager, triggerManager } = createHistoryFixture();
+    const owner = manager.lemmings[0];
+    const trigger = new Trigger(
+      TriggerTypes.TRAP,
+      2,
+      2,
+      3,
+      3,
+      0,
+      9,
+      owner
+    );
+
+    scenario(history, timer).tick(0, {
+      ops: [[
+        'recordTriggerAdd',
+        trigger,
+        {
+          type: trigger.type,
+          x1: trigger.x1,
+          y1: trigger.y1,
+          x2: trigger.x2,
+          y2: trigger.y2,
+          disableTicksCount: trigger.disableTicksCount,
+          soundIndex: trigger.soundIndex,
+          ownerId: owner.id,
+          disabledUntilTick: 0
+        }
+      ]]
+    });
+
+    const delta = history.getDelta(0);
+    history.applyDeltaForward(game, delta);
+    expect(triggerManager._triggers.size).to.equal(1);
+    const added = Array.from(triggerManager._triggers)[0];
+    expect(added.type).to.equal(trigger.type);
+    expect(added.x1).to.equal(trigger.x1);
+    expect(added.y1).to.equal(trigger.y1);
+    expect(added.x2).to.equal(trigger.x2);
+    expect(added.y2).to.equal(trigger.y2);
+
+    history.applyDeltaBackward(game, delta);
+    expect(triggerManager._triggers.size).to.equal(0);
+  });
+
+  it('handles invalid ticks and keyframe lookups', function() {
+    const history = new HistoryStore();
+    expect(history.getDelta(NaN)).to.equal(null);
+    expect(history.getKeyframeAtOrBefore(NaN)).to.equal(null);
+    expect(history.getKeyframeAtOrBefore(1)).to.equal(null);
+
+    seedHistory(history, { keyframes: [3] });
+    expect(history.getKeyframeAtOrBefore(2)).to.equal(null);
+    expect(history.getKeyframeAtOrBefore(3)).to.be.ok;
+  });
+
+  it('releases deltas while respecting pool limits', function() {
+    const history = new HistoryStore({ deltaPoolLimit: 1 });
+    const delta = history._allocDelta(0);
+    history._releaseDelta(delta);
+    expect(history._deltaPool).to.have.length(1);
+    history._releaseDelta(history._allocDelta(1));
+    expect(history._deltaPool).to.have.length(1);
+    history._releaseDelta(null);
+  });
+
+  it('attaches and detaches timer handlers', function() {
+    const history = new HistoryStore();
+    const calls = { onBefore: 0, onAfter: 0, offBefore: 0, offAfter: 0 };
+    const before = {
+      on(fn) { this.fn = fn; calls.onBefore += 1; },
+      off(fn) { if (fn === this.fn) calls.offBefore += 1; }
+    };
+    const after = {
+      on(fn) { this.fn = fn; calls.onAfter += 1; },
+      off(fn) { if (fn === this.fn) calls.offAfter += 1; }
+    };
+    const timer = {
+      tickIndex: 0,
+      onBeforeGameTick: before,
+      onGameTick: after
+    };
+    const game = {
+      level: { entrances: [] },
+      finalGameState: 0,
+      getGameTimer: () => timer,
+      getLemmingManager: () => ({ lemmings: [] }),
+      getGameSkills: () => null,
+      getVictoryCondition: () => null
+    };
+
+    history.attach(game, { captureBaseline: false });
+    expect(calls.onBefore).to.equal(1);
+    expect(calls.onAfter).to.equal(1);
+    history.detach();
+    expect(calls.offBefore).to.equal(1);
+    expect(calls.offAfter).to.equal(1);
+  });
+});
diff --git a/test/history-store.cold-blocks.test.js b/test/history-store.cold-blocks.test.js
new file mode 100644
index 00000000..d9662428
--- /dev/null
+++ b/test/history-store.cold-blocks.test.js
@@ -0,0 +1,388 @@
+import { expect } from 'chai';
+import { withConsoleStub } from './helpers/console.js';
+import { HistoryStore, __test__ } from '../js/game/HistoryStore.js';
+import { SkillTypes } from '../js/game/SkillTypes.js';
+import { Trigger } from '../js/level/Trigger.js';
+import { TriggerTypes } from '../js/level/TriggerTypes.js';
+import { EventHandler } from '../js/util/EventHandler.js';
+import { runScenarioTable } from './support/scenario-table.js';
+import {
+  createHistoryFixture,
+  createStubTimer,
+  recordTick,
+  runHistoryOps,
+  scenario,
+  seedHistory
+} from './support/history-fixtures.js';
+
+describe('HistoryStore cold blocks', function() {
+  it('binds before tick handlers when timers provide hooks', function() {
+    const timer = {
+      tickIndex: 0,
+      speedFactor: 1,
+      frameTime: 60,
+      onBeforeGameTick: new EventHandler(),
+      onGameTick: new EventHandler()
+    };
+    const manager = { lemmings: [], actions: [], skillActions: [] };
+    const game = {
+      level: { entrances: [] },
+      finalGameState: 0,
+      getLemmingManager: () => manager,
+      getGameTimer: () => timer,
+      getGameSkills: () => null,
+      getVictoryCondition: () => null
+    };
+    const history = new HistoryStore();
+    history.attach(game, { captureBaseline: true });
+    timer.onBeforeGameTick.trigger(3);
+    expect(history._currentTick).to.equal(3);
+  });
+
+  it('applies keyframes without nuke targets arrays', function() {
+    const { history, game, manager } = createHistoryFixture();
+    history.applyKeyframe(game, {
+      lemmingManagerState: { nukeTargets: null }
+    });
+    expect(manager._nukeTargets).to.equal(null);
+  });
+
+  it('applies minimap keyframe defaults', function() {
+    const { history, game, manager } = createHistoryFixture();
+    manager.miniMap = {
+      deadDots: new Uint8Array([1, 2]),
+      deadTTLs: new Uint8Array([3]),
+      deadCount: 1
+    };
+    history.applyKeyframe(game, {
+      minimapState: { deadDots: null, deadTTLs: null, deadCount: undefined }
+    });
+    expect(manager.miniMap.deadDots).to.have.length(0);
+    expect(manager.miniMap.deadTTLs).to.have.length(0);
+    expect(manager.miniMap.deadCount).to.equal(0);
+  });
+
+  it('skips applyKeyframe when inputs are missing', function() {
+    const history = new HistoryStore();
+    history.applyKeyframe(null, { lemmingState: {} });
+    history.applyKeyframe({ getLemmingManager: () => ({}) }, null);
+  });
+
+  it('initializes missing lemming arrays during keyframe apply', function() {
+    const history = new HistoryStore();
+    const manager = {
+      actions: [],
+      skillActions: [],
+      _lemmingCtor: function ReplayCtor(x, y, id) {
+        this.x = x;
+        this.y = y;
+        this.id = id;
+      }
+    };
+    const game = {
+      level: { entrances: [] },
+      finalGameState: 0,
+      getLemmingManager: () => manager,
+      getGameTimer: () => null,
+      getGameSkills: () => null,
+      getVictoryCondition: () => null
+    };
+    const lemmingState = __test__.createLemmingState(1);
+    lemmingState.present[0] = 1;
+    lemmingState.x[0] = 2;
+    lemmingState.y[0] = 3;
+    lemmingState.actionType[0] = -1;
+    history.applyKeyframe(game, { lemmingState });
+    expect(Array.isArray(manager.lemmings)).to.equal(true);
+    expect(manager.lemmings[0]).to.be.ok;
+  });
+
+  it('applies keyframe action and entrance fallbacks', function() {
+    const { history, game, manager, walkAction } = createHistoryFixture();
+    game.level.entrances = undefined;
+    manager.actions = [walkAction];
+
+    const lemmingState = __test__.createLemmingState(1);
+    lemmingState.present[0] = 1;
+    lemmingState.x[0] = 1;
+    lemmingState.y[0] = 2;
+    lemmingState.actionType[0] = -1;
+
+    history.applyKeyframe(game, {
+      lemmingState,
+      lemmingManagerState: { nukeTargets: [NaN] },
+      entranceOpened: new Uint8Array(0)
+    });
+
+    expect(manager.lemmings[0].action).to.equal(null);
+    expect(manager._nukeTargets).to.eql([]);
+  });
+
+  it('constructs lemmings from keyframes without skill actions', function() {
+    const history = new HistoryStore();
+    const ctorCalls = [];
+    const LemCtor = function(x, y, id) {
+      this.id = id;
+      this.x = x;
+      this.y = y;
+      ctorCalls.push([x, y, id]);
+    };
+    const manager = { lemmings: [], actions: [], _lemmingCtor: LemCtor };
+    const game = {
+      level: { entrances: [] },
+      finalGameState: 0,
+      getLemmingManager: () => manager,
+      getGameTimer: () => null,
+      getGameSkills: () => null,
+      getVictoryCondition: () => null
+    };
+    const lemmingState = __test__.createLemmingState(1);
+    lemmingState.present[0] = 1;
+    lemmingState.x[0] = 4;
+    lemmingState.y[0] = 5;
+    lemmingState.actionType[0] = -1;
+    history.applyKeyframe(game, { lemmingState });
+    expect(manager.lemmings[0]).to.be.ok;
+    expect(ctorCalls).to.have.length(1);
+
+    manager._lemmingCtor = null;
+    manager.lemmings = [];
+    lemmingState.x[0] = 7;
+    lemmingState.y[0] = 8;
+    expect(() => history.applyKeyframe(game, { lemmingState })).to.throw(
+      /manager\._acquireLemming\(\) or manager\._lemmingCtor/
+    );
+  });
+
+  it('compacts cold delta blocks and resolves sentinel-backed deltas', function() {
+    const { history, timer } = createHistoryFixture();
+    history.configureRetention({
+      deltaBlockSizeTicks: 4,
+      coldBlockAgeTicks: 1,
+      coldCompactionIntervalTicks: 1,
+      coldCompactionMaxBlocksPerSweep: 64,
+      enableColdBlockCompression: true
+    });
+
+    for (let tick = 0; tick < 10; tick += 1) {
+      recordTick(history, timer, tick, null, tick + 1);
+    }
+
+    const stats = history.getHistoryStats();
+    expect(stats.coldBlockCount).to.be.greaterThan(0);
+    const coldTick = 0;
+    expect(history.deltas[coldTick]).to.equal(1);
+    const delta = history.getDelta(coldTick);
+    expect(delta).to.be.ok;
+    expect(delta.tick).to.equal(coldTick);
+  });
+
+  it('throttles cold compaction work per sweep budget', function() {
+    const history = new HistoryStore({
+      deltaBlockSizeTicks: 1,
+      coldBlockAgeTicks: 1,
+      coldCompactionIntervalTicks: 1,
+      coldCompactionMaxBlocksPerSweep: 1,
+      enableColdBlockCompression: true
+    });
+    seedHistory(history, { deltas: [0, 1, 2, 3, 4, 5] });
+
+    history._maybeCompactDeltaBlocks();
+    expect(history._coldBlockCount).to.equal(1);
+    expect(history.deltas[0]).to.equal(1);
+    expect(history.deltas[5]).to.not.equal(1);
+
+    history._maybeCompactDeltaBlocks();
+    expect(history._coldBlockCount).to.equal(2);
+
+    history._maybeCompactDeltaBlocks();
+    history._maybeCompactDeltaBlocks();
+    history._maybeCompactDeltaBlocks();
+    expect(history._coldBlockCount).to.equal(5);
+    expect(history.deltas[4]).to.equal(1);
+    expect(history.deltas[5]).to.not.equal(1);
+  });
+
+  it('runs compaction sweeps only on configured interval ticks', function() {
+    const history = new HistoryStore({
+      deltaBlockSizeTicks: 1,
+      coldBlockAgeTicks: 1,
+      coldCompactionIntervalTicks: 3,
+      coldCompactionMaxBlocksPerSweep: 64,
+      enableColdBlockCompression: true
+    });
+    seedHistory(history, { deltas: [0, 1, 2, 3, 4] });
+
+    history._maybeCompactDeltaBlocks();
+    expect(history._coldBlockCount).to.equal(0);
+
+    history._setDelta(5, history._allocDelta(5));
+    history._maybeCompactDeltaBlocks();
+    expect(history._coldBlockCount).to.equal(0);
+
+    history._setDelta(6, history._allocDelta(6));
+    history._maybeCompactDeltaBlocks();
+    expect(history._coldBlockCount).to.be.greaterThan(0);
+    expect(history.deltas[0]).to.equal(1);
+  });
+
+  it('deduplicates identical cold block payloads by hash', function() {
+    const { history, timer } = createHistoryFixture();
+    history.configureRetention({
+      deltaBlockSizeTicks: 2,
+      coldBlockAgeTicks: 1,
+      coldCompactionIntervalTicks: 1,
+      coldCompactionMaxBlocksPerSweep: 64,
+      enableColdBlockCompression: true,
+      enableColdBlockDedupe: true
+    });
+
+    for (let tick = 0; tick < 10; tick += 1) {
+      recordTick(history, timer, tick, null, tick + 1);
+    }
+
+    const uniqueBuckets = Array.from(history._coldBlockStore.values());
+    expect(uniqueBuckets.length).to.be.greaterThan(0);
+    const hasSharedRef = uniqueBuckets.some(bucket => bucket.some(entry => entry.refs > 1));
+    expect(hasSharedRef).to.equal(true);
+  });
+
+  it('keeps distinct bytes when hash buckets collide during dedupe', function() {
+    const history = new HistoryStore({ enableColdBlockDedupe: true });
+    const storeKey = 'raw:deadbeef:4';
+    const a = Uint8Array.from([1, 2, 3, 4]);
+    const b = Uint8Array.from([4, 3, 2, 1]);
+    const retainedA = history._retainColdBytes(storeKey, a);
+    const retainedB = history._retainColdBytes(storeKey, b);
+    expect(retainedA).to.equal(a);
+    expect(retainedB).to.equal(b);
+    expect(retainedA).to.not.equal(retainedB);
+    expect(history._coldBlockStore.get(storeKey)).to.have.length(2);
+    expect(history._coldBlockBytes).to.equal(a.length + b.length);
+  });
+
+  it('preserves replay hash across cold-block thaw and decode', function() {
+    const { history, timer, manager } = createHistoryFixture();
+    history.configureRetention({
+      deltaBlockSizeTicks: 3,
+      coldBlockAgeTicks: 1,
+      coldCompactionIntervalTicks: 1,
+      coldCompactionMaxBlocksPerSweep: 64,
+      enableColdBlockCompression: true
+    });
+
+    for (let tick = 0; tick < 9; tick += 1) {
+      recordTick(history, timer, tick, () => {
+        manager.lemmings[0].x = 10 + (tick % 3);
+        manager.lemmings[0].frameIndex = tick % 5;
+      }, tick + 1);
+    }
+
+    const before = history.computeReplayHash();
+    for (const start of history._deltaBlocks.keys()) {
+      history._thawDeltaBlock(start);
+    }
+    const after = history.computeReplayHash();
+    expect(before).to.be.a('string');
+    expect(after).to.equal(before);
+  });
+
+  it('preserves replay hash across long-session cold decode and thaw cycles', function() {
+    const { history, timer, manager, skills, victory, game } = createHistoryFixture();
+    history.configureRetention({
+      deltaBlockSizeTicks: 8,
+      coldBlockAgeTicks: 1,
+      coldCompactionIntervalTicks: 1,
+      coldCompactionMaxBlocksPerSweep: 128,
+      enableColdBlockCompression: true
+    });
+
+    for (let tick = 0; tick < 240; tick += 1) {
+      recordTick(history, timer, tick, () => {
+        manager.lemmings[0].x = 10 + (tick % 17);
+        manager.lemmings[0].y = 20 + (tick % 9);
+        manager.lemmings[0].frameIndex = tick % 8;
+        manager.lemmings[0].lookRight = (tick % 2) === 0;
+        skills.selectedSkill = tick % 2;
+        skills.skills[0] = 1 + (tick % 3);
+        victory.leftCount = Math.max(0, 200 - tick);
+        game.finalGameState = tick % 4;
+      }, tick + 1);
+    }
+
+    const baseline = history.computeReplayHash();
+    expect(baseline).to.be.a('string');
+
+    for (let tick = history.maxDeltaTick; tick >= history.minDeltaTick; tick -= 3) {
+      const delta = history.getDelta(tick);
+      expect(delta).to.be.ok;
+    }
+    const afterDecode = history.computeReplayHash();
+    expect(afterDecode).to.equal(baseline);
+
+    for (const start of Array.from(history._deltaBlocks.keys())) {
+      history._thawDeltaBlock(start);
+    }
+    history._maybeCompactDeltaBlocks();
+    const afterThaw = history.computeReplayHash();
+    expect(afterThaw).to.equal(baseline);
+  });
+
+  it('preserves replay hash during randomized cold block seek/decode cycles', function() {
+    const { history, timer, manager, skills, victory, game } = createHistoryFixture();
+    history.configureRetention({
+      deltaBlockSizeTicks: 6,
+      coldBlockAgeTicks: 1,
+      coldCompactionIntervalTicks: 1,
+      coldCompactionMaxBlocksPerSweep: 64,
+      enableColdBlockCompression: true,
+      enableColdBlockDedupe: true
+    });
+
+    for (let tick = 0; tick < 300; tick += 1) {
+      recordTick(history, timer, tick, () => {
+        if ((tick % 4) === 0) {
+          manager.lemmings[0].x = 16 + (tick % 19);
+          manager.lemmings[0].y = 22 + (tick % 11);
+          manager.lemmings[0].frameIndex = tick % 6;
+          manager.lemmings[0].lookRight = (tick % 2) === 0;
+          skills.selectedSkill = tick % 2;
+          skills.skills[0] = 1 + (tick % 4);
+          victory.leftCount = Math.max(0, 240 - tick);
+          game.finalGameState = tick % 5;
+        }
+      }, tick + 1);
+    }
+
+    const baseline = history.computeReplayHash();
+    expect(baseline).to.be.a('string');
+    let seed = 0x1234abcd;
+    const next = () => {
+      seed = (Math.imul(seed, 1664525) + 1013904223) >>> 0;
+      return seed;
+    };
+    const minTick = history.minDeltaTick;
+    const maxTick = history.maxDeltaTick;
+    for (let i = 0; i < 480; i += 1) {
+      const range = (maxTick - minTick + 1);
+      const tick = minTick + (next() % range);
+      history.getDelta(tick);
+      if ((i % 7) === 0) {
+        history._maybeCompactDeltaBlocks();
+      }
+      if ((i % 11) === 0) {
+        const starts = Array.from(history._deltaBlocks.keys());
+        if (starts.length) {
+          const pick = starts[next() % starts.length];
+          history._thawDeltaBlock(pick);
+        }
+      }
+      if ((i % 40) === 0) {
+        expect(history.computeReplayHash()).to.equal(baseline);
+      }
+    }
+
+    const after = history.computeReplayHash();
+    expect(after).to.equal(baseline);
+  });
+});
diff --git a/test/history-store.diffing.test.js b/test/history-store.diffing.test.js
new file mode 100644
index 00000000..c17b9db6
--- /dev/null
+++ b/test/history-store.diffing.test.js
@@ -0,0 +1,181 @@
+import { expect } from 'chai';
+import { withConsoleStub } from './helpers/console.js';
+import { HistoryStore, __test__ } from '../js/game/HistoryStore.js';
+import { SkillTypes } from '../js/game/SkillTypes.js';
+import { Trigger } from '../js/level/Trigger.js';
+import { TriggerTypes } from '../js/level/TriggerTypes.js';
+import { EventHandler } from '../js/util/EventHandler.js';
+import { runScenarioTable } from './support/scenario-table.js';
+import {
+  createHistoryFixture,
+  createStubTimer,
+  recordTick,
+  runHistoryOps,
+  scenario,
+  seedHistory
+} from './support/history-fixtures.js';
+
+describe('HistoryStore diffing', function() {
+  it('truncates before gaps and clears keyframes', function() {
+    const history = new HistoryStore({ keyframeInterval: 2 });
+    seedHistory(history, { deltas: [0, 2], keyframes: [0, 1] });
+
+    history._truncateBefore(1);
+    expect(history.minDeltaTick).to.equal(2);
+
+    history._truncateBefore(5);
+    expect(history.minDeltaTick).to.equal(null);
+
+    const history2 = new HistoryStore({ keyframeInterval: 2 });
+    seedHistory(history2, { deltas: [0], keyframes: [0, 1] });
+    history2._truncateBefore(2);
+    expect(history2.keyframeTicks).to.have.length(0);
+  });
+
+  it('warns and caps history spans', function() {
+    const history = new HistoryStore({
+      enableHistoryCap: true,
+      historyCapTicks: 2,
+      historyWarnTicks: 2
+    });
+    seedHistory(history, { deltas: [0, 1, 2, 3], keyframes: [1] });
+
+    let warned = 0;
+    const restoreConsole = withConsoleStub({ warn: () => { warned += 1; } });
+    try {
+      history._maybeWarnHistory();
+      history._maybeWarnHistory();
+    } finally {
+      restoreConsole();
+    }
+    expect(warned).to.equal(1);
+
+    history._enforceHistoryCap();
+    expect(history.minDeltaTick).to.equal(1);
+  });
+
+  it('skips history caps when a keyframe is before the minimum tick', function() {
+    const history = new HistoryStore({
+      enableHistoryCap: true,
+      historyCapTicks: 2
+    });
+    seedHistory(history, { deltas: [5, 6, 7], keyframes: [0] });
+
+    history._enforceHistoryCap();
+    expect(history.minDeltaTick).to.equal(5);
+  });
+
+  it('captures keyframes with ground data when dirty', function() {
+    const { history, game } = createHistoryFixture();
+    history._groundDirty = true;
+    game.level.groundMask.mask[0] = 1;
+    game.level.groundImage[0] = 5;
+
+    const frame = history._captureKeyframe(game, 0);
+    expect(frame.groundMask[0]).to.equal(1);
+    expect(frame.groundImage[0]).to.equal(5);
+  });
+
+  it('diffs lemming adds, removals, and changes', function() {
+    const history = new HistoryStore();
+    const walkAction = { name: 'walk' };
+    const manager = {
+      lemmings: [
+        {
+          id: 0,
+          x: 1,
+          y: 2,
+          lookRight: true,
+          frameIndex: 0,
+          state: 1,
+          canClimb: false,
+          hasParachute: false,
+          removed: false,
+          disabled: false,
+          countdown: 0,
+          hasExploded: false,
+          lastTriggerType: null,
+          action: walkAction,
+          countdownAction: null
+        },
+        {
+          id: 1,
+          x: 3,
+          y: 4,
+          lookRight: false,
+          frameIndex: 0,
+          state: 1,
+          canClimb: false,
+          hasParachute: false,
+          removed: false,
+          disabled: false,
+          countdown: 0,
+          hasExploded: false,
+          lastTriggerType: null,
+          action: walkAction,
+          countdownAction: null
+        }
+      ],
+      actions: [walkAction],
+      skillActions: [],
+      actionTypeByAction: new Map()
+    };
+
+    history._captureLemmingState(manager);
+    const delta = history._allocDelta(0);
+
+    manager.lemmings[0] = null;
+    manager.lemmings[1].x = 10;
+    manager.lemmings.push({
+      id: 2,
+      x: 5,
+      y: 6,
+      lookRight: true,
+      frameIndex: 0,
+      state: 1,
+      canClimb: false,
+      hasParachute: false,
+      removed: false,
+      disabled: false,
+      countdown: 0,
+      hasExploded: false,
+      lastTriggerType: 2,
+      action: walkAction,
+      countdownAction: null
+    });
+
+    history._diffLemmings(manager, delta);
+    expect(delta.lemRemoved).to.have.length(1);
+    expect(delta.lemAdded).to.have.length(1);
+    expect(delta.lemChanges.ids).to.include(1);
+  });
+
+  it('removes lemmings beyond the current length', function() {
+    const history = new HistoryStore();
+    const walkAction = { name: 'walk' };
+    const manager = {
+      lemmings: [
+        { id: 0, x: 1, y: 2, lookRight: true, frameIndex: 0, state: 1, canClimb: false, hasParachute: false, removed: false, disabled: false, countdown: 0, hasExploded: false, lastTriggerType: null, action: walkAction, countdownAction: null },
+        { id: 1, x: 3, y: 4, lookRight: false, frameIndex: 0, state: 1, canClimb: false, hasParachute: false, removed: false, disabled: false, countdown: 0, hasExploded: false, lastTriggerType: null, action: walkAction, countdownAction: null },
+        { id: 2, x: 5, y: 6, lookRight: true, frameIndex: 0, state: 1, canClimb: false, hasParachute: false, removed: false, disabled: false, countdown: 0, hasExploded: false, lastTriggerType: null, action: walkAction, countdownAction: null }
+      ],
+      actions: [walkAction],
+      skillActions: [],
+      actionTypeByAction: new Map()
+    };
+
+    history._captureLemmingState(manager);
+    manager.lemmings.length = 1;
+    const delta = history._allocDelta(0);
+    history._diffLemmings(manager, delta);
+    expect(delta.lemRemoved).to.have.length(2);
+  });
+
+  it('skips lemming diffs when values match', function() {
+    const history = new HistoryStore();
+    const delta = history._allocDelta(0);
+    const store = new Int32Array(1);
+    history._diffLemmingField(delta, 0, 0, 1, 1, store);
+    expect(delta.lemChanges.ids).to.have.length(0);
+  });
+});
diff --git a/test/history-store.edge-branches.test.js b/test/history-store.edge-branches.test.js
new file mode 100644
index 00000000..b066545d
--- /dev/null
+++ b/test/history-store.edge-branches.test.js
@@ -0,0 +1,402 @@
+import { expect } from 'chai';
+import { withConsoleStub } from './helpers/console.js';
+import { HistoryStore, __test__ } from '../js/game/HistoryStore.js';
+import { SkillTypes } from '../js/game/SkillTypes.js';
+import { Trigger } from '../js/level/Trigger.js';
+import { TriggerTypes } from '../js/level/TriggerTypes.js';
+import { EventHandler } from '../js/util/EventHandler.js';
+import { runScenarioTable } from './support/scenario-table.js';
+import {
+  createHistoryFixture,
+  createStubTimer,
+  recordTick,
+  runHistoryOps,
+  scenario,
+  seedHistory
+} from './support/history-fixtures.js';
+
+describe('HistoryStore edge branches', function() {
+  it('resets entrance tracking when entrance count changes', function() {
+    const timer = createStubTimer();
+    const manager = {
+      lemmings: [],
+      activeLemmings: [],
+      _activeDirty: false,
+      actions: [],
+      skillActions: [],
+      actionTypeByAction: new Map(),
+      selectedIndex: -1,
+      spawnTotal: 0,
+      releaseTickIndex: 0,
+      mmTickCounter: 0,
+      nextNukingLemmingsIndex: -1,
+      _nukeTargets: null
+    };
+    const level = { entrances: [{ _opened: false }] };
+    const game = {
+      level,
+      finalGameState: 0,
+      getLemmingManager: () => manager,
+      getGameTimer: () => timer,
+      getGameSkills: () => null,
+      getVictoryCondition: () => null
+    };
+    const history = new HistoryStore({ keyframeInterval: 5 });
+    history.attach(game, { captureBaseline: true });
+
+    scenario(history, timer).tick(0, {
+      mutate() {
+        level.entrances.push({ _opened: true });
+      }
+    });
+
+    const delta = history.getDelta(0);
+    expect(delta.entranceChanges.indices).to.have.length(0);
+    expect(history._entranceOpened).to.have.length(2);
+  });
+
+  it('removes triggers by resolving ids from trigger sets', function() {
+    const history = new HistoryStore();
+    const owner = { id: 0 };
+    const trigger = new Trigger(TriggerTypes.TRAP, 1, 1, 2, 2, 0, 0, owner);
+    trigger.__historyId = 7;
+    const triggerManager = {
+      _triggers: new Set([trigger]),
+      add(trig) { this._triggers.add(trig); },
+      removeByOwner(ownerRef) {
+        for (const trig of Array.from(this._triggers)) {
+          if (trig.owner === ownerRef) this._triggers.delete(trig);
+        }
+      }
+    };
+    const game = {
+      triggerManager,
+      getLemmingManager: () => ({ getLemming: () => owner })
+    };
+    const delta = {
+      triggerAdd: [],
+      triggerRemove: [{ id: 7 }]
+    };
+
+    history._applyTriggerChanges(game, delta, true);
+
+    expect(triggerManager._triggers.size).to.equal(0);
+    expect(history._triggerById.get(7)).to.equal(trigger);
+  });
+
+  it('applies object changes by resolving ids from level objects', function() {
+    const history = new HistoryStore();
+    const obj = { animation: { firstFrameIndex: 0, isFinished: false } };
+    const level = { objects: [obj] };
+    const changes = {
+      ids: [1],
+      prevFirst: [0],
+      prevFinished: [0],
+      nextFirst: [5],
+      nextFinished: [1]
+    };
+
+    history._applyObjectChanges(level, changes, true);
+
+    expect(obj.animation.firstFrameIndex).to.equal(5);
+    expect(obj.animation.isFinished).to.equal(true);
+  });
+
+  it('handles non-array skill lists', function() {
+    const history = new HistoryStore();
+    const skills = history._readSkills({ selectedSkill: 1, cheatMode: 1, skills: null });
+    expect(skills.skills).to.eql([]);
+    expect(skills.cheatMode).to.equal(true);
+    expect(history._skillsEqual(skills, { selectedSkill: 1, cheatMode: true, skills: [] })).to.equal(true);
+    expect(history._skillsEqual(skills, { selectedSkill: 2, cheatMode: true, skills: [] })).to.equal(false);
+  });
+
+  it('start no-ops without a game and skips existing keyframes', function() {
+    const history = new HistoryStore();
+    history.start();
+    expect(history._recording).to.equal(false);
+
+    const timer = createStubTimer();
+    const game = {
+      level: { entrances: [] },
+      finalGameState: 0,
+      getLemmingManager: () => ({ lemmings: [] }),
+      getGameTimer: () => timer,
+      getGameSkills: () => null,
+      getVictoryCondition: () => null
+    };
+    const history2 = new HistoryStore({ keyframeInterval: 5 });
+    history2.attach(game, { captureBaseline: true });
+    const count = history2.keyframeCount;
+    history2.timer = null;
+    history2.start();
+    expect(history2.keyframeCount).to.equal(count);
+  });
+
+  it('captures keyframes without ground data and handles null minimaps', function() {
+    const history = new HistoryStore();
+    const game = {
+      level: { entrances: [] },
+      finalGameState: 0,
+      getLemmingManager: () => ({ lemmings: [], miniMap: null }),
+      getGameTimer: () => createStubTimer(),
+      getGameSkills: () => null,
+      getVictoryCondition: () => null
+    };
+
+    const frame = history._captureKeyframe(game, 0);
+
+    expect(frame.groundMask).to.equal(null);
+    expect(frame.groundImage).to.equal(null);
+    expect(history._readMinimapState(null)).to.equal(null);
+  });
+
+  it('records lemming adds and ignores unknown change fields', function() {
+    const { history, timer, manager, walkAction } = createHistoryFixture();
+    const newLem = {
+      id: 1,
+      x: 10,
+      y: 11,
+      lookRight: true,
+      frameIndex: 0,
+      state: 0,
+      canClimb: false,
+      hasParachute: false,
+      removed: false,
+      disabled: false,
+      countdown: 0,
+      hasExploded: false,
+      lastTriggerType: null,
+      action: walkAction,
+      countdownAction: null
+    };
+
+    scenario(history, timer).tick(0, {
+      mutate() {
+        manager.lemmings.push(newLem);
+      }
+    });
+
+    const delta = history.getDelta(0);
+    expect(delta.lemAdded).to.have.length(1);
+
+    history._applyLemmingChanges(manager, {
+      ids: [0],
+      fields: [99],
+      prev: [0],
+      next: [1]
+    }, true);
+    expect(manager.lemmings[0].x).to.equal(5);
+  });
+
+  it('skips delta application and ground changes when data is missing', function() {
+    const history = new HistoryStore();
+    history._applyDelta(null, null, true);
+
+    const level = { groundMask: null, groundImage: null };
+    history._applyGroundChanges(level, {
+      indices: [0],
+      prevMask: [0],
+      prevR: [0],
+      prevG: [0],
+      prevB: [0],
+      nextMask: [1],
+      nextR: [1],
+      nextG: [1],
+      nextB: [1]
+    }, true);
+    expect(level.groundImage).to.equal(null);
+  });
+
+  it('adds lemmings with constructors and skips invalid entries', function() {
+    const history = new HistoryStore();
+    const created = [];
+    function LemCtor(x, y, id) {
+      this.id = id;
+      this.x = x;
+      this.y = y;
+      created.push(this);
+    }
+    const manager = { lemmings: null, actions: [], skillActions: [], _lemmingCtor: LemCtor };
+    const snap = {
+      id: 0,
+      x: 1,
+      y: 2,
+      lookRight: 1,
+      frameIndex: 0,
+      state: 0,
+      canClimb: 0,
+      hasParachute: 0,
+      removed: 0,
+      disabled: 0,
+      countdown: 0,
+      hasExploded: 0,
+      lastTriggerType: -1,
+      actionType: -1,
+      countdownActive: 0
+    };
+
+    history._applyLemmingAdds(manager, [null, { id: NaN }, snap]);
+
+    expect(created).to.have.length(1);
+    expect(manager.lemmings[0]).to.be.instanceOf(LemCtor);
+  });
+
+  it('handles trigger changes with missing owners and cooldown ids', function() {
+    const history = new HistoryStore();
+    const trigger = new Trigger(TriggerTypes.TRAP, 0, 0, 1, 1);
+    trigger.__historyId = 3;
+    trigger.owner = null;
+    const triggerManager = {
+      _triggers: new Set([trigger]),
+      add(trig) { this._triggers.add(trig); },
+      removeByOwner(owner) {
+        for (const entry of Array.from(this._triggers)) {
+          if (entry.owner === owner) this._triggers.delete(entry);
+        }
+      }
+    };
+    const game = { triggerManager, getLemmingManager: () => ({ getLemming: () => null }) };
+    const delta = {
+      triggerAdd: [],
+      triggerRemove: [{ id: 3 }],
+      triggerCooldownChanges: { ids: [9], prev: [0], next: [1] }
+    };
+
+    history._applyTriggerChanges(game, delta, true);
+
+    expect(triggerManager._triggers.size).to.equal(1);
+  });
+
+  it('skips ownerless dynamic triggers and ignores empty dynamic state', function() {
+    const history = new HistoryStore();
+    const ownerless = new Trigger(TriggerTypes.TRAP, 1, 1, 2, 2, 0, 0, null);
+    const staticTrigger = new Trigger(TriggerTypes.FRYING, 2, 2, 3, 3, 0, 0, null);
+    staticTrigger.disabledUntilTick = 2;
+    const level = { triggers: [staticTrigger] };
+    const triggerManager = {
+      _triggers: new Set([staticTrigger, ownerless]),
+      add(trig) { this._triggers.add(trig); },
+      removeByOwner(owner) {
+        for (const entry of Array.from(this._triggers)) {
+          if (entry.owner === owner) this._triggers.delete(entry);
+        }
+      }
+    };
+    const game = {
+      level,
+      triggerManager,
+      getLemmingManager: () => ({ getLemming: () => null })
+    };
+
+    const state = history._readTriggerState(game);
+    expect(state.dynamicTriggers).to.have.length(0);
+    state.staticTriggers[0].disabledUntilTick = 5;
+    state.dynamicTriggers = [];
+
+    history._applyTriggerState(game, state);
+
+    expect(staticTrigger.disabledUntilTick).to.equal(5);
+    expect(triggerManager._triggers.has(ownerless)).to.equal(true);
+  });
+
+  it('skips objects without animations in state helpers', function() {
+    const history = new HistoryStore();
+    const objWithAnim = { animation: { firstFrameIndex: 2, isFinished: false } };
+    const objNoAnim = {};
+    const level = { objects: [objWithAnim, objNoAnim] };
+    const state = history._readObjectState(level);
+    expect(state).to.have.length(1);
+
+    history._applyObjectState(level, [{ id: 999, firstFrameIndex: 9, isFinished: true }]);
+    expect(objWithAnim.animation.firstFrameIndex).to.equal(2);
+  });
+
+  it('applies game state even when other scalars are missing', function() {
+    const history = new HistoryStore();
+    const game = {
+      finalGameState: 0,
+      getGameSkills: () => null,
+      getVictoryCondition: () => null,
+      getGameTimer: () => null
+    };
+    const delta = {
+      skillsChanges: { prev: null, next: { selectedSkill: 1, cheatMode: false, skills: [] } },
+      victoryChanges: { prev: null, next: { releaseRate: 1, minReleaseRate: 1, leftCount: 0, outCount: 0, survivorCount: 0, isFinalize: false } },
+      timerChanges: { prev: null, next: { speedFactor: 1, frameTime: 60, tickIndex: 2 } },
+      gameChanges: { prev: { finalGameState: 0 }, next: { finalGameState: 4 } }
+    };
+
+    history._applyScalarChanges(game, delta, true);
+
+    expect(game.finalGameState).to.equal(4);
+  });
+
+  it('handles early returns and null helpers', function() {
+    const history = new HistoryStore({ deltaPoolLimit: 0 });
+    const delta = history._allocDelta(0);
+    history._releaseDelta(delta);
+    expect(history._deltaPool).to.have.length(0);
+
+    history.attach(null);
+    history._bindTimer();
+    history.beginTick(0);
+    history.endTick();
+    history.captureBaseline(null);
+
+    runHistoryOps(history, [
+      ['recordSoundEvent', { type: 'sfx' }],
+      ['recordGroundChange', 0, 0, 0, 0, 0, 1, 1, 1, 1],
+      ['recordEntranceChange', 0, false, true],
+      ['recordTriggerCooldown', null, 0, 1],
+      ['recordTriggerAdd', null, {}],
+      ['recordTriggerRemove', null, {}],
+      ['recordObjectAnimation', null, { firstFrameIndex: 0, isFinished: false }, { firstFrameIndex: 1, isFinished: true }],
+      ['recordMinimapDeath', { x: 1 }]
+    ]);
+
+    expect(history._ensureTriggerId(null)).to.equal(0);
+    expect(history._ensureObjectId(null)).to.equal(0);
+  });
+
+  it('records delta entries for sound, entrances, and objects', function() {
+    const { history, timer, level } = createHistoryFixture();
+    const obj = { animation: { firstFrameIndex: 0, isFinished: false } };
+    level.objects = [obj];
+
+    scenario(history, timer).tick(0, {
+      ops: [
+        ['recordSoundEvent', { type: 'step' }],
+        ['recordEntranceChange', 0, false, true],
+        ['recordObjectAnimation', obj, { firstFrameIndex: 0, isFinished: false }, { firstFrameIndex: 2, isFinished: true }],
+        ['recordMinimapDeath', { x: 2, y: 3, ttl: 4, prevCount: 0 }]
+      ]
+    });
+
+    const delta = history.getDelta(0);
+    expect(delta.soundEvents).to.have.length(1);
+    expect(delta.entranceChanges.prev[0]).to.equal(0);
+    expect(delta.entranceChanges.next[0]).to.equal(1);
+    expect(delta.objectAnimChanges.prevFinished[0]).to.equal(0);
+    expect(delta.objectAnimChanges.nextFinished[0]).to.equal(1);
+    expect(delta.minimapDeaths).to.have.length(1);
+  });
+
+  it('truncates deltas and keyframes when removing all history', function() {
+    const history = new HistoryStore({ keyframeInterval: 2 });
+    seedHistory(history, { deltas: [0, 2], keyframes: [0, 2] });
+
+    history._truncateDeltasAfter(-1);
+    expect(history.minDeltaTick).to.equal(null);
+    expect(history.maxDeltaTick).to.equal(null);
+
+    seedHistory(history, { keyframes: [1] });
+    history._truncateKeyframesAfter(0);
+    expect(history.keyframeTicks).to.have.length(1);
+    expect(history.keyframeTicks[0]).to.equal(0);
+
+    seedHistory(history, { deltas: [0] });
+    history._truncateBefore(5);
+    expect(history.minDeltaTick).to.equal(null);
+  });
+});
diff --git a/test/history-store.keyframe.test.js b/test/history-store.keyframe.test.js
new file mode 100644
index 00000000..cdf24d10
--- /dev/null
+++ b/test/history-store.keyframe.test.js
@@ -0,0 +1,410 @@
+import { expect } from 'chai';
+import { withConsoleStub } from './helpers/console.js';
+import { HistoryStore, __test__ } from '../js/game/HistoryStore.js';
+import { SkillTypes } from '../js/game/SkillTypes.js';
+import { Trigger } from '../js/level/Trigger.js';
+import { TriggerTypes } from '../js/level/TriggerTypes.js';
+import { EventHandler } from '../js/util/EventHandler.js';
+import { runScenarioTable } from './support/scenario-table.js';
+import {
+  createHistoryFixture,
+  createStubTimer,
+  recordTick,
+  runHistoryOps,
+  scenario,
+  seedHistory
+} from './support/history-fixtures.js';
+
+describe('HistoryStore keyframes', function() {
+  it('applies manager state defaults and rebuilds active list', function() {
+    const history = new HistoryStore();
+    history._applyLemmingManagerState(null, null, true);
+    history._rebuildActiveLemmings(null);
+
+    const lem = { id: 0, removed: false };
+    const manager = { lemmings: [lem] };
+    history._applyLemmingManagerState(manager, {
+      next: {
+        selectedIndex: 2,
+        spawnTotal: 3,
+        releaseTickIndex: 4,
+        mmTickCounter: 5,
+        nextNukingLemmingsIndex: 6,
+        nukeTargets: [0]
+      }
+    }, true);
+    expect(manager._nukeTargets).to.eql([lem]);
+
+    history._applyLemmingManagerState(manager, {
+      next: { nukeTargets: null }
+    }, true);
+    expect(manager.selectedIndex).to.equal(-1);
+    expect(manager.spawnTotal).to.equal(0);
+    expect(manager.releaseTickIndex).to.equal(0);
+    expect(manager.mmTickCounter).to.equal(0);
+    expect(manager.nextNukingLemmingsIndex).to.equal(-1);
+    expect(manager._nukeTargets).to.equal(null);
+
+    history._applyLemmingManagerState(manager, { next: null }, true);
+  });
+
+  it('handles entrance and ground change fallbacks', function() {
+    const history = new HistoryStore();
+    history._applyEntranceChanges(null, null, true);
+    history._applyGroundChanges(null, null, true);
+
+    const level = {
+      entrances: [{ _opened: false }],
+      groundMask: { mask: new Uint8Array(1) },
+      groundImage: new Uint8ClampedArray(4)
+    };
+    const entranceChanges = { indices: [0], prev: [0], next: [1] };
+    history._applyEntranceChanges(level, entranceChanges, true);
+    expect(level.entrances[0]._opened).to.equal(true);
+
+    const groundChanges = {
+      spans: null,
+      indices: [0],
+      prevMask: [0],
+      prevR: [0],
+      prevG: [0],
+      prevB: [0],
+      nextMask: [1],
+      nextR: [1],
+      nextG: [2],
+      nextB: [3]
+    };
+    history._applyGroundChanges(level, groundChanges, false);
+    expect(level.groundMask.mask[0]).to.equal(0);
+  });
+
+  it('applies trigger changes and resolves ids', function() {
+    const history = new HistoryStore();
+    const owner = { id: 1 };
+    const cooldownOwner = { id: 2 };
+    const manager = {
+      lemmings: [owner, cooldownOwner],
+      getLemming: (id) => (id === 1 ? owner : cooldownOwner)
+    };
+    const triggerManager = {
+      _triggers: new Set(),
+      add(trigger) { this._triggers.add(trigger); },
+      removeByOwner(ownerTarget) {
+        for (const trig of Array.from(this._triggers)) {
+          if (trig.owner === ownerTarget) this._triggers.delete(trig);
+        }
+      }
+    };
+    const existing = new Trigger(TriggerTypes.TRAP, 0, 0, 1, 1, 0, 0, owner);
+    existing.__historyId = 2;
+    existing.disabledUntilTick = 5;
+    triggerManager._triggers.add(existing);
+
+    const cooldown = new Trigger(TriggerTypes.TRAP, 2, 2, 3, 3, 0, 0, cooldownOwner);
+    cooldown.__historyId = 3;
+    triggerManager._triggers.add(cooldown);
+
+    const game = { triggerManager, getLemmingManager: () => manager };
+    const delta = {
+      triggerAdd: [{
+        id: 10,
+        type: TriggerTypes.KILL,
+        x1: 1,
+        y1: 1,
+        x2: 2,
+        y2: 2,
+        disableTicksCount: 0,
+        soundIndex: 1,
+        ownerId: null
+      }],
+      triggerRemove: [{ id: 2 }],
+      triggerCooldownChanges: { ids: [3, 99], prev: [0, 0], next: [7, 8] }
+    };
+
+    history._applyTriggerChanges(game, delta, true);
+    expect(triggerManager._triggers.has(existing)).to.equal(false);
+    const added = Array.from(triggerManager._triggers)
+      .find(trig => trig.__historyId === 10);
+    expect(added).to.be.ok;
+    expect(added.disabledUntilTick).to.equal(0);
+    expect(cooldown.disabledUntilTick).to.equal(7);
+
+    const found = history._findTriggerById(triggerManager, 3);
+    expect(found).to.equal(cooldown);
+    expect(history._findTriggerById(triggerManager, 123)).to.equal(null);
+    expect(history._findTriggerById({}, 5)).to.equal(null);
+
+    history._applyTriggerChanges(game, { triggerAdd: [], triggerRemove: null }, true);
+    history._applyTriggerChanges(game, { triggerAdd: null, triggerRemove: [] }, true);
+  });
+
+  it('reads and applies trigger state with missing data', function() {
+    const history = new HistoryStore();
+    const owner = { id: 1 };
+    const midiOwner = {
+      id: 'midi_flag_2_0',
+      __historyKind: 'midi_flag',
+      __historyData: { midiFlagId: 2, triggerType: 9002, pieceId: 22 }
+    };
+    const staticTrigger = new Trigger(TriggerTypes.TRAP, 1, 1, 2, 2, 0, 5, null);
+    const dynamicTrigger = new Trigger(TriggerTypes.KILL, 3, 3, 4, 4, 0, 7, owner);
+    const midiTrigger = new Trigger(TriggerTypes.NO_TRIGGER, 7, 7, 9, 9, 0, -1, midiOwner);
+    const orphanTrigger = new Trigger(TriggerTypes.KILL, 5, 5, 6, 6, 0, 8, { id: NaN });
+    const level = { triggers: [null, staticTrigger] };
+    const triggerManager = {
+      _triggers: new Set([staticTrigger, dynamicTrigger, midiTrigger, orphanTrigger]),
+      add(trigger) { this._triggers.add(trigger); },
+      remove(trigger) { this._triggers.delete(trigger); },
+      removeByOwner(ownerTarget) {
+        for (const trig of Array.from(this._triggers)) {
+          if (trig.owner === ownerTarget) this._triggers.delete(trig);
+        }
+      }
+    };
+    const game = {
+      level,
+      triggerManager,
+      getLemmingManager: () => ({ getLemming: (id) => (id === 1 ? owner : null) })
+    };
+    const state = history._readTriggerState(game);
+    expect(state.staticTriggers).to.have.length(1);
+    expect(state.dynamicTriggers).to.have.length(2);
+    const midiState = state.dynamicTriggers.find(entry => entry.ownerKind === 'midi_flag');
+    expect(midiState.ownerData.midiFlagId).to.equal(2);
+
+    const stateNoTriggers = history._readTriggerState({
+      level: {},
+      triggerManager: { _triggers: new Set() }
+    });
+    expect(stateNoTriggers.staticTriggers).to.have.length(0);
+
+    history._applyTriggerState({ level: null, triggerManager: null }, null);
+
+    const applyGameEmpty = {
+      level: { triggers: [staticTrigger, null] },
+      triggerManager: { _triggers: undefined, add() {}, removeByOwner() {} },
+      getLemmingManager: () => null
+    };
+    history._applyTriggerState(applyGameEmpty, { staticTriggers: state.staticTriggers });
+
+    const applyGameNoList = {
+      level: {},
+      triggerManager: { _triggers: undefined, add() {}, removeByOwner() {} },
+      getLemmingManager: () => null
+    };
+    history._applyTriggerState(applyGameNoList, {
+      dynamicTriggers: [{
+        id: 99,
+        ownerId: null,
+        type: TriggerTypes.TRAP,
+        x1: 0,
+        y1: 0,
+        x2: 1,
+        y2: 1,
+        disableTicksCount: 0,
+        soundIndex: 0,
+        disabledUntilTick: 0
+      }]
+    });
+
+    const missingOwnerTrigger = new Trigger(TriggerTypes.KILL, 2, 2, 3, 3, 0, 0, { id: 2 });
+    const applyManager = {
+      _triggers: new Set([dynamicTrigger, missingOwnerTrigger]),
+      add(trigger) { this._triggers.add(trigger); },
+      remove(trigger) { this._triggers.delete(trigger); },
+      removeByOwner(ownerTarget) {
+        for (const trig of Array.from(this._triggers)) {
+          if (trig.owner === ownerTarget) this._triggers.delete(trig);
+        }
+      }
+    };
+    const applyGame = {
+      level: { triggers: [staticTrigger, null] },
+      triggerManager: applyManager,
+      soundEvents: { events: [], emit(event) { this.events.push(event); } },
+      getLemmingManager: () => ({ getLemming: (id) => (id === 1 ? owner : null) })
+    };
+    const applyState = {
+      staticTriggers: state.staticTriggers,
+      dynamicTriggers: [{
+        id: 10,
+        ownerId: 1,
+        type: TriggerTypes.TRAP,
+        x1: 0,
+        y1: 0,
+        x2: 1,
+        y2: 1,
+        disableTicksCount: 0,
+        soundIndex: 0,
+        disabledUntilTick: 2
+      }, {
+        id: 11,
+        ownerId: 2,
+        type: TriggerTypes.KILL,
+        x1: 1,
+        y1: 1,
+        x2: 2,
+        y2: 2,
+        disableTicksCount: 0,
+        soundIndex: 0,
+        disabledUntilTick: 0
+      }, {
+        id: 12,
+        ownerKind: 'midi_flag',
+        ownerId: 'midi_flag_2_0',
+        ownerData: { midiFlagId: 2, triggerType: 9002, pieceId: 22 },
+        type: TriggerTypes.NO_TRIGGER,
+        x1: 7,
+        y1: 7,
+        x2: 9,
+        y2: 9,
+        disableTicksCount: 0,
+        soundIndex: -1,
+        disabledUntilTick: 0
+      }]
+    };
+    history._applyTriggerState(applyGame, applyState);
+    const restoredMidi = Array.from(applyManager._triggers)
+      .find(trigger => trigger.__historyId === 12);
+    restoredMidi.owner.onTrigger(3, { id: 42 }, restoredMidi, 8, 8);
+    expect(applyGame.soundEvents.events[0]).to.include({
+      type: 'trap-trigger',
+      triggerType: 9002,
+      midiFlagId: 2,
+      pieceId: 22,
+      lemmingId: 42
+    });
+
+    history._applyTriggerState(applyGame, {
+      staticTriggers: state.staticTriggers,
+      dynamicTriggers: []
+    });
+    expect(Array.from(applyManager._triggers)
+      .some(trigger => trigger.owner?.__historyKind === 'midi_flag')).to.equal(false);
+  });
+
+  it('handles object state and changes with missing animations', function() {
+    const history = new HistoryStore();
+    const obj = { animation: { firstFrameIndex: 0, isFinished: false } };
+    const level = { objects: [obj, {}] };
+
+    const state = history._readObjectState(level);
+    expect(state).to.have.length(1);
+
+    const objId = history._ensureObjectId(obj);
+    const changes = {
+      ids: [objId, 999],
+      prevFirst: [0, 0],
+      prevFinished: [0, 0],
+      nextFirst: [2, 1],
+      nextFinished: [1, 1]
+    };
+    history._applyObjectChanges(level, changes, true);
+    expect(obj.animation.firstFrameIndex).to.equal(2);
+
+    obj.animation = null;
+    history._applyObjectChanges(level, {
+      ids: [objId],
+      prevFirst: [0],
+      prevFinished: [0],
+      nextFirst: [1],
+      nextFinished: [1]
+    }, true);
+
+    history._objectById = new Map();
+    history._applyObjectChanges({}, {
+      ids: [objId],
+      prevFirst: [0],
+      prevFinished: [0],
+      nextFirst: [1],
+      nextFinished: [1]
+    }, true);
+
+    history._applyObjectState(level, null);
+
+    history._objectById = new Map();
+    const entries = [{ id: objId, firstFrameIndex: 5, isFinished: true }];
+    obj.animation = { firstFrameIndex: 0, isFinished: false };
+    history._applyObjectState(level, entries);
+    expect(obj.animation.firstFrameIndex).to.equal(5);
+
+    obj.animation = null;
+    history._applyObjectState(level, entries);
+
+    history._applyObjectState(null, [{
+      id: 123,
+      firstFrameIndex: 0,
+      isFinished: false
+    }]);
+  });
+
+  it('applies minimap deaths and reads defaults', function() {
+    const history = new HistoryStore();
+    const manager = {
+      miniMap: {
+        deadDots: new Uint8Array(0),
+        deadTTLs: new Uint8Array(0)
+      }
+    };
+
+    history._applyMinimapDeaths(manager, [{
+      x: undefined,
+      y: undefined,
+      ttl: undefined,
+      prevCount: undefined
+    }], true);
+    expect(manager.miniMap.deadDots[0]).to.equal(0);
+    expect(manager.miniMap.deadTTLs[0]).to.equal(0);
+
+    history._applyMinimapDeaths(manager, [{
+      x: 2,
+      y: 3,
+      ttl: 4,
+      prevCount: 1
+    }], true);
+
+    history._applyMinimapDeaths(manager, [{ prevCount: 1 }, {}], false);
+    expect(manager.miniMap.deadCount).to.equal(1);
+
+    const minimapState = history._readMinimapState({
+      deadDots: null,
+      deadTTLs: null,
+      deadCount: undefined
+    });
+    expect(minimapState.deadDots).to.be.instanceof(Uint8Array);
+    expect(minimapState.deadTTLs).to.be.instanceof(Uint8Array);
+    expect(minimapState.deadCount).to.equal(0);
+  });
+
+  it('captures keyframes without level data', function() {
+    const history = new HistoryStore();
+    const game = {
+      finalGameState: 0,
+      getLemmingManager: () => ({ lemmings: [] }),
+      getGameTimer: () => null,
+      getGameSkills: () => null,
+      getVictoryCondition: () => null
+    };
+    const frame = history._captureKeyframe(game, 0);
+    expect(frame.entranceOpened).to.have.length(0);
+    expect(frame.groundMask).to.equal(null);
+
+    const gameWithLevel = {
+      level: { entrances: [{ _opened: true }, { _opened: false }] },
+      finalGameState: 0,
+      getLemmingManager: () => ({ lemmings: [] }),
+      getGameTimer: () => null,
+      getGameSkills: () => null,
+      getVictoryCondition: () => null
+    };
+    const frameWithLevel = history._captureKeyframe(gameWithLevel, 1);
+    expect(frameWithLevel.entranceOpened[0]).to.equal(1);
+    expect(frameWithLevel.entranceOpened[1]).to.equal(0);
+  });
+
+  it('captures interval keyframes during endTick', function() {
+    const { history, timer } = createHistoryFixture();
+    recordTick(history, timer, 0, null, 5);
+    expect(history.getKeyframe(5)).to.be.ok;
+  });
+});
diff --git a/test/history-store.replay-apply.test.js b/test/history-store.replay-apply.test.js
new file mode 100644
index 00000000..671a62c3
--- /dev/null
+++ b/test/history-store.replay-apply.test.js
@@ -0,0 +1,329 @@
+import { expect } from 'chai';
+import { withConsoleStub } from './helpers/console.js';
+import { HistoryStore, __test__ } from '../js/game/HistoryStore.js';
+import { SkillTypes } from '../js/game/SkillTypes.js';
+import { Trigger } from '../js/level/Trigger.js';
+import { TriggerTypes } from '../js/level/TriggerTypes.js';
+import { EventHandler } from '../js/util/EventHandler.js';
+import { runScenarioTable } from './support/scenario-table.js';
+import {
+  createHistoryFixture,
+  createStubTimer,
+  recordTick,
+  runHistoryOps,
+  scenario,
+  seedHistory
+} from './support/history-fixtures.js';
+
+describe('HistoryStore replay application', function() {
+  it('compares lemming manager state including nuke targets', function() {
+    const history = new HistoryStore();
+    const a = {
+      selectedIndex: 0,
+      spawnTotal: 1,
+      releaseTickIndex: 2,
+      mmTickCounter: 3,
+      nextNukingLemmingsIndex: 4,
+      nukeTargets: [1, 2]
+    };
+    const b = { ...a, nukeTargets: [1, 3] };
+    const c = { ...a, nukeTargets: [1, 2] };
+    expect(history._lemmingManagerEqual(a, b)).to.equal(false);
+    expect(history._lemmingManagerEqual(a, c)).to.equal(true);
+  });
+
+  it('diffs entrance and scalar changes', function() {
+    const history = new HistoryStore();
+    const skills = { selectedSkill: 0, cheatMode: false, skills: [1] };
+    const victory = {
+      releaseRate: 1,
+      minReleaseRate: 1,
+      leftCount: 1,
+      outCount: 0,
+      survivorCount: 0,
+      isFinalize: false
+    };
+    const timer = { speedFactor: 1, frameTime: 60, tickIndex: 0 };
+    const level = { entrances: [{ _opened: false }] };
+    const game = {
+      level,
+      finalGameState: 0,
+      getGameSkills: () => skills,
+      getVictoryCondition: () => victory,
+      getGameTimer: () => timer
+    };
+
+    history._captureScalarState(game);
+    history._captureEntrances(level);
+
+    const noChange = history._allocDelta(0);
+    history._diffScalarState(game, noChange);
+    expect(noChange.skillsChanges).to.equal(null);
+
+    skills.selectedSkill = 1;
+    victory.leftCount = 0;
+    timer.tickIndex = 5;
+    timer.speedFactor = 2;
+    game.finalGameState = 2;
+    level.entrances[0]._opened = true;
+
+    const delta = history._allocDelta(0);
+    history._diffScalarState(game, delta);
+    history._diffEntrances(level, delta);
+
+    expect(delta.skillsChanges).to.be.ok;
+    expect(delta.victoryChanges).to.be.ok;
+    expect(delta.timerChanges).to.be.ok;
+    expect(delta.gameChanges).to.be.ok;
+    expect(delta.entranceChanges.indices).to.have.length(1);
+  });
+
+  it('applies lemming removals, changes, and manager targets', function() {
+    const history = new HistoryStore();
+    const bombAction = { name: 'bomber' };
+    const walkAction = { name: 'walk' };
+    const skillActions = [];
+    skillActions[SkillTypes.BOMBER] = bombAction;
+    const lem = { id: 0, action: null, countdownAction: null };
+    const manager = {
+      lemmings: [lem],
+      actions: [walkAction],
+      skillActions
+    };
+
+    history._applyLemmingRemovals(manager, [null, { id: NaN }, { id: 0 }]);
+    expect(manager.lemmings[0]).to.equal(null);
+
+    manager.lemmings[0] = lem;
+    history._applyLemmingChanges(manager, {
+      ids: [0, 0, 0],
+      fields: [11, 12, 13],
+      prev: [-1, -1, 0],
+      next: [2, 0, 1]
+    }, true);
+    expect(lem.lastTriggerType).to.equal(2);
+    expect(lem.action).to.equal(walkAction);
+    expect(lem.countdownAction).to.equal(bombAction);
+
+    const changes = {
+      prev: {
+        selectedIndex: 0,
+        spawnTotal: 1,
+        releaseTickIndex: 0,
+        mmTickCounter: 0,
+        nextNukingLemmingsIndex: 0,
+        nukeTargets: []
+      },
+      next: {
+        selectedIndex: 2,
+        spawnTotal: 2,
+        releaseTickIndex: 1,
+        mmTickCounter: 1,
+        nextNukingLemmingsIndex: 1,
+        nukeTargets: [0]
+      }
+    };
+    history._applyLemmingManagerState(manager, changes, true);
+    expect(manager._nukeTargets).to.eql([lem]);
+  });
+
+  it('replays timer speed changes without assigning read-only frameTime', function() {
+    const history = new HistoryStore();
+    let speedFactor = 4;
+    const timer = {
+      tickIndex: 6,
+      get speedFactor() { return speedFactor; },
+      set speedFactor(value) { speedFactor = value; },
+      get frameTime() { return 60 / speedFactor; }
+    };
+    const game = {
+      timeTravel: { ignoreSpeedOnReverse: true },
+      getGameTimer: () => timer
+    };
+    const delta = {
+      tick: 4,
+      timerChanges: {
+        prev: { speedFactor: 2, frameTime: 30 },
+        next: { speedFactor: 4, frameTime: 15 }
+      }
+    };
+
+    expect(() => history._applyScalarChanges(game, delta, false)).to.not.throw();
+    expect(timer.tickIndex).to.equal(4);
+    expect(timer.speedFactor).to.equal(4);
+    expect(timer.frameTime).to.equal(15);
+  });
+
+  it('resets entrance tracking when entrance list changes', function() {
+    const history = new HistoryStore();
+    const level = { entrances: [{ _opened: false }] };
+    const delta = history._allocDelta(0);
+    history._captureEntrances(level);
+    level.entrances.push({ _opened: true });
+    history._diffEntrances(level, delta);
+    expect(history._entranceOpened).to.have.length(2);
+  });
+
+  it('captures null lemmings in baseline state', function() {
+    const history = new HistoryStore();
+    const walkAction = { name: 'walk' };
+    const manager = {
+      lemmings: [
+        null,
+        {
+          id: 1,
+          x: 1,
+          y: 2,
+          lookRight: true,
+          frameIndex: 0,
+          state: 0,
+          canClimb: false,
+          hasParachute: false,
+          removed: false,
+          disabled: false,
+          countdown: 0,
+          hasExploded: false,
+          lastTriggerType: null,
+          action: walkAction,
+          countdownAction: null
+        }
+      ],
+      actions: [walkAction],
+      skillActions: [],
+      actionTypeByAction: new Map([[walkAction, 0]])
+    };
+
+    history._captureLemmingState(manager);
+    expect(history._lemmingState.present[0]).to.equal(0);
+    expect(history._lemmingState.present[1]).to.equal(1);
+  });
+
+  it('handles helper defaults and early exits', function() {
+    const history = new HistoryStore();
+    const state = __test__.createLemmingState(1);
+
+    __test__.cloneLemmingState(state, null);
+    __test__.cloneLemmingState(state, 1);
+
+    const delta = history._allocDelta(0);
+    history.options.deltaPoolLimit = null;
+    history._releaseDelta(delta);
+    expect(history._deltaPool).to.have.length(1);
+
+    history.options.deltaPoolLimit = 0;
+    history._releaseDelta(history._allocDelta(1));
+    expect(history._deltaPool).to.have.length(0);
+
+    history._bindTimer();
+    history.attach(null);
+    history.start();
+    history.truncateAfter(NaN);
+    history.beginTick(0);
+    history.captureBaseline(null);
+
+    runHistoryOps(history, [
+      ['recordSoundEvent', {}],
+      ['recordGroundChange', 0, 0, 0, 0, 0, 0, 0, 0, 0],
+      ['recordEntranceChange', 0, false, false],
+      ['recordTriggerCooldown', null, 0, 0],
+      ['recordTriggerAdd', null, {}],
+      ['recordTriggerRemove', null, {}],
+      ['recordObjectAnimation', {}, { firstFrameIndex: 0, isFinished: false }, { firstFrameIndex: 0, isFinished: false }],
+      ['recordMinimapDeath', {}]
+    ]);
+
+    const historyWithTimer = new HistoryStore();
+    const timer = createStubTimer();
+    const game = {
+      level: { entrances: [] },
+      finalGameState: 0,
+      getGameTimer: () => timer,
+      getLemmingManager: () => ({ lemmings: [] }),
+      getGameSkills: () => null,
+      getVictoryCondition: () => null
+    };
+    historyWithTimer.attach(game, { captureBaseline: false });
+    expect(historyWithTimer.timer).to.equal(timer);
+
+    const historyNoTimer = new HistoryStore();
+    const gameNoTimer = {
+      level: { entrances: [] },
+      finalGameState: 0,
+      getLemmingManager: () => ({ lemmings: [] }),
+      getGameSkills: () => null,
+      getVictoryCondition: () => null
+    };
+    historyNoTimer.attach(gameNoTimer, { captureBaseline: false });
+    expect(historyNoTimer.timer).to.equal(null);
+  });
+
+  it('records changes with boolean conversions and ids', function() {
+    const history = new HistoryStore();
+    history._recording = true;
+    history.beginTick(0);
+    const obj = {};
+    const trigger = new Trigger(TriggerTypes.TRAP, 0, 0, 1, 1);
+    runHistoryOps(history, [
+      ['recordEntranceChange', 0, false, true],
+      ['recordEntranceChange', 1, true, false],
+      ['recordObjectAnimation', obj, { firstFrameIndex: 1, isFinished: false }, { firstFrameIndex: 2, isFinished: true }],
+      ['recordObjectAnimation', obj, { firstFrameIndex: 2, isFinished: true }, { firstFrameIndex: 3, isFinished: false }],
+      ['recordTriggerCooldown', trigger, 0, 2],
+      ['recordTriggerAdd', trigger, {
+        type: trigger.type,
+        x1: trigger.x1,
+        y1: trigger.y1,
+        x2: trigger.x2,
+        y2: trigger.y2,
+        disableTicksCount: trigger.disableTicksCount,
+        soundIndex: trigger.soundIndex,
+        ownerId: null
+      }],
+      ['recordTriggerRemove', trigger, {
+        type: trigger.type,
+        x1: trigger.x1,
+        y1: trigger.y1,
+        x2: trigger.x2,
+        y2: trigger.y2,
+        disableTicksCount: trigger.disableTicksCount,
+        soundIndex: trigger.soundIndex,
+        ownerId: null
+      }],
+      ['recordMinimapDeath', { x: 1, y: 2, ttl: 3, prevCount: 0 }]
+    ]);
+
+    const existingTrigger = { __historyId: 9 };
+    expect(history._ensureTriggerId(existingTrigger)).to.equal(9);
+    expect(history._ensureTriggerId(null)).to.equal(0);
+    const newTrigger = {};
+    expect(history._ensureTriggerId(newTrigger)).to.be.greaterThan(0);
+
+    const existingObj = { __historyId: 11 };
+    expect(history._ensureObjectId(existingObj)).to.equal(11);
+    expect(history._ensureObjectId(null)).to.equal(0);
+    const newObj = {};
+    expect(history._ensureObjectId(newObj)).to.be.greaterThan(0);
+  });
+
+  it('covers keyframe search branches', function() {
+    const history = new HistoryStore();
+    history.keyframeTicks = [2, 4];
+    history._insertKeyframeTick(1);
+    history._insertKeyframeTick(3);
+    expect(history.keyframeTicks).to.eql([1, 2, 3, 4]);
+
+    history.keyframes[2] = { tickIndex: 2 };
+    history.keyframes[3] = { tickIndex: 3 };
+    history.keyframes[4] = { tickIndex: 4 };
+    expect(history.getKeyframeAtOrBefore(3).tickIndex).to.equal(3);
+
+    history.keyframeTicks = [5, 10];
+    history.keyframes[5] = { tickIndex: 5 };
+    history.keyframes[10] = { tickIndex: 10 };
+    expect(history.getKeyframeAtOrBefore(6).tickIndex).to.equal(5);
+
+    history.keyframeTicks = [7];
+    history.keyframes[7] = undefined;
+    expect(history.getKeyframeAtOrBefore(7)).to.equal(null);
+  });
+});
diff --git a/test/history-store.replay-edge.test.js b/test/history-store.replay-edge.test.js
new file mode 100644
index 00000000..d0766fd9
--- /dev/null
+++ b/test/history-store.replay-edge.test.js
@@ -0,0 +1,472 @@
+import { expect } from 'chai';
+import { withConsoleStub } from './helpers/console.js';
+import { HistoryStore, __test__ } from '../js/game/HistoryStore.js';
+import { SkillTypes } from '../js/game/SkillTypes.js';
+import { Trigger } from '../js/level/Trigger.js';
+import { TriggerTypes } from '../js/level/TriggerTypes.js';
+import { EventHandler } from '../js/util/EventHandler.js';
+import { runScenarioTable } from './support/scenario-table.js';
+import {
+  createHistoryFixture,
+  createStubTimer,
+  recordTick,
+  runHistoryOps,
+  scenario,
+  seedHistory
+} from './support/history-fixtures.js';
+
+describe('HistoryStore replay edge cases', function() {
+  it('handles truncation edge cases', function() {
+    const empty = new HistoryStore();
+    empty._truncateDeltasAfter(1);
+    empty._truncateKeyframesAfter(1);
+    empty._truncateBefore(1);
+
+    const history = new HistoryStore();
+    seedHistory(history, { deltas: [0, 1] });
+    history._truncateDeltasAfter(1);
+    expect(history.maxDeltaTick).to.equal(1);
+
+    const historyGap = new HistoryStore();
+    seedHistory(historyGap, { deltas: [0, 3] });
+    historyGap._truncateDeltasAfter(1);
+    expect(historyGap.maxDeltaTick).to.equal(0);
+
+    const historyAll = new HistoryStore();
+    seedHistory(historyAll, { deltas: [2] });
+    historyAll._truncateDeltasAfter(1);
+    expect(historyAll.minDeltaTick).to.equal(null);
+
+    const keyframesAll = new HistoryStore();
+    seedHistory(keyframesAll, { keyframes: [2, 3] });
+    keyframesAll._truncateKeyframesAfter(1);
+    expect(keyframesAll.keyframeTicks).to.have.length(0);
+
+    const keyframesMissing = new HistoryStore();
+    keyframesMissing.keyframeTicks = [5];
+    keyframesMissing.keyframes[5] = undefined;
+    keyframesMissing.minKeyframeTick = 5;
+    keyframesMissing.maxKeyframeTick = 5;
+    keyframesMissing._truncateKeyframesAfter(5);
+    expect(keyframesMissing._lastKeyframe).to.equal(null);
+
+    const beforeGap = new HistoryStore();
+    seedHistory(beforeGap, { deltas: [0, 3], keyframes: [0, 3] });
+    beforeGap._truncateBefore(2);
+    expect(beforeGap.minDeltaTick).to.equal(3);
+
+    const beforeAll = new HistoryStore();
+    seedHistory(beforeAll, { deltas: [0], keyframes: [0] });
+    beforeAll._truncateBefore(2);
+    expect(beforeAll.minDeltaTick).to.equal(null);
+    expect(beforeAll.keyframeTicks).to.have.length(0);
+
+    const beforeLast = new HistoryStore();
+    seedHistory(beforeLast, { deltas: [0] });
+    beforeLast.keyframeTicks = [2];
+    beforeLast.keyframes[2] = undefined;
+    beforeLast.minKeyframeTick = 2;
+    beforeLast.maxKeyframeTick = 2;
+    beforeLast._truncateBefore(0);
+    expect(beforeLast._lastKeyframe).to.equal(null);
+
+    const historySpan = new HistoryStore();
+    seedHistory(historySpan, { deltas: [0, 5] });
+    historySpan._truncateDeltasAfter(3);
+    expect(historySpan.maxDeltaTick).to.equal(0);
+
+    const historyClear = new HistoryStore();
+    seedHistory(historyClear, { deltas: [5] });
+    historyClear._truncateDeltasAfter(3);
+    expect(historyClear.minDeltaTick).to.equal(null);
+
+    const beforeSpan = new HistoryStore();
+    seedHistory(beforeSpan, { deltas: [0, 5] });
+    beforeSpan._truncateBefore(2);
+    expect(beforeSpan.minDeltaTick).to.equal(5);
+
+    const beforeClear = new HistoryStore();
+    seedHistory(beforeClear, { deltas: [0] });
+    beforeClear._truncateBefore(2);
+    expect(beforeClear.maxDeltaTick).to.equal(null);
+  });
+
+  it('handles history warning and cap edge cases', function() {
+    const history = new HistoryStore({ historyWarnTicks: 5 });
+    history._maybeWarnHistory();
+    seedHistory(history, { deltas: [0, 1] });
+    history._maybeWarnHistory();
+
+    const capDefault = new HistoryStore({ enableHistoryCap: true });
+    capDefault.options.historyCapTicks = null;
+    capDefault._enforceHistoryCap();
+
+    const capEmpty = new HistoryStore({
+      enableHistoryCap: true,
+      historyCapTicks: 2
+    });
+    capEmpty._enforceHistoryCap();
+
+    const capWithFrame = new HistoryStore({
+      enableHistoryCap: true,
+      historyCapTicks: 2
+    });
+    seedHistory(capWithFrame, { deltas: [0, 1, 2], keyframes: [0] });
+    capWithFrame._enforceHistoryCap();
+    expect(capWithFrame.minDeltaTick).to.equal(0);
+
+    const capNoFrame = new HistoryStore({
+      enableHistoryCap: true,
+      historyCapTicks: 2
+    });
+    seedHistory(capNoFrame, { deltas: [0, 1, 2] });
+    capNoFrame._enforceHistoryCap();
+    expect(capNoFrame.minDeltaTick).to.equal(1);
+  });
+
+  it('diffs lemmings through state transitions', function() {
+    const history = new HistoryStore();
+    history._captureLemmingState(null);
+
+    const walk = { name: 'walk' };
+    const manager = {
+      lemmings: [{
+        id: 0,
+        x: 1,
+        y: 2,
+        lookRight: true,
+        frameIndex: 0,
+        state: 1,
+        canClimb: true,
+        hasParachute: true,
+        removed: false,
+        disabled: false,
+        countdown: 3,
+        hasExploded: false,
+        lastTriggerType: 4,
+        action: walk,
+        countdownAction: null
+      }],
+      actions: [walk],
+      skillActions: [],
+      actionTypeByAction: new Map([[walk, 0]])
+    };
+
+    history._captureLemmingState({
+      lemmings: [null],
+      actions: [walk],
+      skillActions: [],
+      actionTypeByAction: new Map()
+    });
+
+    history._captureLemmingState(manager);
+
+    const delta = history._allocDelta(0);
+    manager.lemmings[0].lookRight = false;
+    manager.lemmings[0].state = null;
+    manager.lemmings[0].canClimb = false;
+    manager.lemmings[0].hasParachute = false;
+    manager.lemmings[0].removed = true;
+    manager.lemmings[0].disabled = true;
+    manager.lemmings[0].countdown = null;
+    manager.lemmings[0].hasExploded = true;
+    manager.lemmings[0].lastTriggerType = NaN;
+    manager.lemmings[0].countdownAction = {};
+    history._diffLemmings(manager, delta);
+
+    const delta2 = history._allocDelta(1);
+    manager.lemmings[0].lookRight = true;
+    manager.lemmings[0].state = 2;
+    manager.lemmings[0].canClimb = true;
+    manager.lemmings[0].hasParachute = true;
+    manager.lemmings[0].removed = false;
+    manager.lemmings[0].disabled = false;
+    manager.lemmings[0].countdown = 4;
+    manager.lemmings[0].hasExploded = false;
+    manager.lemmings[0].lastTriggerType = 2;
+    manager.lemmings[0].countdownAction = null;
+    history._diffLemmings(manager, delta2);
+
+    const delta3 = history._allocDelta(2);
+    manager.lemmings[0] = null;
+    history._diffLemmings(manager, delta3);
+
+    const delta4 = history._allocDelta(3);
+    history._diffLemmings(null, delta4);
+    history._diffLemmings({}, delta4);
+
+    const historyNew = new HistoryStore();
+    const managerNew = {
+      lemmings: [{
+        id: 0,
+        x: 1,
+        y: 1,
+        lookRight: true,
+        frameIndex: 0,
+        state: 0,
+        canClimb: false,
+        hasParachute: false,
+        removed: false,
+        disabled: false,
+        countdown: 0,
+        hasExploded: false,
+        lastTriggerType: null,
+        action: null,
+        countdownAction: null
+      }],
+      actions: [],
+      skillActions: [],
+      actionTypeByAction: new Map()
+    };
+    const deltaNew = historyNew._allocDelta(0);
+    historyNew._diffLemmings(managerNew, deltaNew);
+  });
+
+  it('handles lemming manager comparisons with mismatches', function() {
+    const history = new HistoryStore();
+    expect(history._readLemmingManager(null)).to.equal(null);
+
+    const readManager = {
+      selectedIndex: 1,
+      spawnTotal: 2,
+      releaseTickIndex: 3,
+      mmTickCounter: 4,
+      nextNukingLemmingsIndex: 5,
+      _nukeTargets: [{ id: 7 }, {}]
+    };
+    const readState = history._readLemmingManager(readManager);
+    expect(readState.nukeTargets).to.eql([7, null]);
+
+    const base = {
+      selectedIndex: 1,
+      spawnTotal: 2,
+      releaseTickIndex: 3,
+      mmTickCounter: 4,
+      nextNukingLemmingsIndex: 5,
+      nukeTargets: [1, 2]
+    };
+    expect(history._lemmingManagerEqual(null, null)).to.equal(false);
+    expect(history._lemmingManagerEqual(base, { ...base, selectedIndex: 0 })).to.equal(false);
+    expect(history._lemmingManagerEqual(base, { ...base, spawnTotal: 3 })).to.equal(false);
+    expect(history._lemmingManagerEqual(base, { ...base, releaseTickIndex: 4 })).to.equal(false);
+    expect(history._lemmingManagerEqual(base, { ...base, mmTickCounter: 5 })).to.equal(false);
+    expect(history._lemmingManagerEqual(base, { ...base, nextNukingLemmingsIndex: 6 })).to.equal(false);
+    expect(history._lemmingManagerEqual(base, { ...base, nukeTargets: [1] })).to.equal(false);
+    expect(history._lemmingManagerEqual(base, { ...base, nukeTargets: [1, 3] })).to.equal(false);
+    expect(history._lemmingManagerEqual(base, { ...base })).to.equal(true);
+  });
+
+  it('writes lemming state defaults and resolves action types', function() {
+    const history = new HistoryStore();
+    const state = __test__.createLemmingState(1);
+    const action = { name: 'walk' };
+
+    const lemFalse = {
+      id: 0,
+      x: 0,
+      y: 0,
+      lookRight: false,
+      frameIndex: 0,
+      state: null,
+      canClimb: false,
+      hasParachute: false,
+      removed: false,
+      disabled: false,
+      countdown: null,
+      hasExploded: false,
+      lastTriggerType: NaN
+    };
+    history._writeLemmingState(state, 0, lemFalse, NaN, false);
+
+    const lemTrue = {
+      id: 0,
+      x: 1,
+      y: 2,
+      lookRight: true,
+      frameIndex: 3,
+      state: 4,
+      canClimb: true,
+      hasParachute: true,
+      removed: true,
+      disabled: true,
+      countdown: 5,
+      hasExploded: true,
+      lastTriggerType: 2
+    };
+    history._writeLemmingState(state, 0, lemTrue, 1, true);
+
+    const manager = {
+      actions: [action],
+      actionTypeByAction: new Map([[action, 0]])
+    };
+    expect(history._getActionType(null, action)).to.equal(-1);
+    expect(history._getActionType(manager, null)).to.equal(-1);
+
+    const managerNoMap = { actions: [action], actionTypeByAction: new Map() };
+    expect(history._getActionType(managerNoMap, action)).to.equal(0);
+
+    const managerNoActions = { actionTypeByAction: new Map() };
+    expect(history._getActionType(managerNoActions, action)).to.equal(-1);
+  });
+
+  it('captures and diffs entrances with changes', function() {
+    const history = new HistoryStore();
+    history._captureEntrances(null);
+    history._diffEntrances(null, history._allocDelta(0));
+
+    const level = { entrances: [{ _opened: true }, { _opened: false }, null] };
+    history._captureEntrances(level);
+    const delta = history._allocDelta(1);
+    history._diffEntrances(level, delta);
+
+    level.entrances[0]._opened = false;
+    level.entrances[1]._opened = true;
+    history._diffEntrances(level, delta);
+    expect(delta.entranceChanges.indices).to.have.length(2);
+
+    level.entrances.push({ _opened: true });
+    const delta2 = history._allocDelta(2);
+    history._diffEntrances(level, delta2);
+    expect(history._entranceOpened).to.have.length(4);
+  });
+
+  it('compares scalar state snapshots', function() {
+    const history = new HistoryStore();
+    expect(history._readSkills(null)).to.equal(null);
+    expect(history._readVictory(null)).to.equal(null);
+    expect(history._readTimer(null)).to.equal(null);
+    expect(history._readGameState(null)).to.equal(null);
+
+    const skills = { selectedSkill: 1, cheatMode: true, skills: [1, 2] };
+    const skillsState = history._readSkills(skills);
+    expect(history._skillsEqual(skillsState, { ...skillsState })).to.equal(true);
+    expect(history._skillsEqual(skillsState, { ...skillsState, selectedSkill: 2 })).to.equal(false);
+    expect(history._skillsEqual(skillsState, { ...skillsState, cheatMode: false })).to.equal(false);
+    expect(history._skillsEqual(skillsState, { ...skillsState, skills: [1] })).to.equal(false);
+    expect(history._skillsEqual(skillsState, { ...skillsState, skills: [1, 3] })).to.equal(false);
+    expect(history._skillsEqual(skillsState, { selectedSkill: 1, cheatMode: true })).to.equal(false);
+    expect(history._skillsEqual(null, skillsState)).to.equal(false);
+
+    const victory = {
+      releaseRate: 1,
+      minReleaseRate: 1,
+      leftCount: 1,
+      outCount: 0,
+      survivorCount: 0,
+      isFinalize: false
+    };
+    const victoryState = history._readVictory(victory);
+    expect(history._victoryEqual(victoryState, { ...victoryState })).to.equal(true);
+    expect(history._victoryEqual(victoryState, { ...victoryState, outCount: 1 })).to.equal(false);
+    expect(history._victoryEqual(null, victoryState)).to.equal(false);
+
+    const timer = { speedFactor: 1, frameTime: 60, tickIndex: 0 };
+    const timerState = history._readTimer(timer);
+    expect(history._timerEqual(timerState, { ...timerState })).to.equal(true);
+    expect(history._timerEqual(timerState, { ...timerState, tickIndex: 1 })).to.equal(true);
+    expect(history._timerEqual(null, timerState)).to.equal(false);
+
+    const gameState = history._readGameState({ finalGameState: 1 });
+    expect(history._gameStateEqual(gameState, { finalGameState: 1 })).to.equal(true);
+    expect(history._gameStateEqual(gameState, { finalGameState: 2 })).to.equal(false);
+    expect(history._gameStateEqual(null, gameState)).to.equal(false);
+  });
+
+  it('applies lemming adds and changes across fields', function() {
+    const history = new HistoryStore();
+    history._applyDelta(null, null, true);
+
+    const walkAction = { name: 'walk' };
+    const bombAction = { name: 'bomb' };
+
+    const manager = {
+      lemmings: null,
+      actions: [walkAction],
+      _lemmingCtor: function ReplayCtor(x, y, id) {
+        this.x = x;
+        this.y = y;
+        this.id = id;
+      }
+    };
+
+    const addList = [{
+      id: 0,
+      x: 1,
+      y: 2,
+      lookRight: 1,
+      frameIndex: 0,
+      state: 0,
+      canClimb: 0,
+      hasParachute: 0,
+      removed: 0,
+      disabled: 0,
+      countdown: 0,
+      hasExploded: 0,
+      lastTriggerType: -1,
+      actionType: -1,
+      countdownActive: 0
+    }];
+    history._applyLemmingAdds(manager, addList);
+    expect(Array.isArray(manager.lemmings)).to.equal(true);
+
+    const missingChanges = { ids: [1], fields: [0], prev: [0], next: [1] };
+    history._applyLemmingChanges(manager, missingChanges, true);
+
+    manager.skillActions = [];
+    manager.skillActions[SkillTypes.BOMBER] = bombAction;
+
+    history._applyLemmingAdds(manager, [{
+      id: 1,
+      x: 3,
+      y: 4,
+      lookRight: 1,
+      frameIndex: 0,
+      state: 0,
+      canClimb: 0,
+      hasParachute: 0,
+      removed: 0,
+      disabled: 0,
+      countdown: 0,
+      hasExploded: 0,
+      lastTriggerType: -1,
+      actionType: -1,
+      countdownActive: 1
+    }]);
+
+    const lem = manager.lemmings[0];
+    const fields = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 11, 12, 12, 13, 13, 99];
+    const ids = new Array(fields.length).fill(0);
+    const next = [
+      10, 20, 1, 3, 4, 1, 1, 1, 1, 7, 1,
+      -1, 2,
+      -1, 0,
+      0, 1,
+      0
+    ];
+    const prev = new Array(fields.length).fill(0);
+    const changes = { ids, fields, prev, next };
+    history._applyLemmingChanges(manager, changes, true);
+
+    expect(lem.x).to.equal(10);
+    expect(lem.y).to.equal(20);
+    expect(lem.lookRight).to.equal(true);
+    expect(lem.frameIndex).to.equal(3);
+    expect(lem.state).to.equal(4);
+    expect(lem.canClimb).to.equal(true);
+    expect(lem.hasParachute).to.equal(true);
+    expect(lem.removed).to.equal(true);
+    expect(lem.disabled).to.equal(true);
+    expect(lem.countdown).to.equal(7);
+    expect(lem.hasExploded).to.equal(true);
+    expect(lem.lastTriggerType).to.equal(2);
+    expect(lem.action).to.equal(walkAction);
+    expect(lem.countdownAction).to.equal(bombAction);
+
+    const managerNoSkill = { lemmings: [{ id: 0 }], actions: [walkAction] };
+    history._applyLemmingChanges(
+      managerNoSkill,
+      { ids: [0], fields: [2], prev: [0], next: [1] },
+      true
+    );
+  });
+});
diff --git a/test/history-store.retention.test.js b/test/history-store.retention.test.js
new file mode 100644
index 00000000..7a32d29f
--- /dev/null
+++ b/test/history-store.retention.test.js
@@ -0,0 +1,345 @@
+import { expect } from 'chai';
+import { withConsoleStub } from './helpers/console.js';
+import { HistoryStore, __test__ } from '../js/game/HistoryStore.js';
+import { SkillTypes } from '../js/game/SkillTypes.js';
+import { Trigger } from '../js/level/Trigger.js';
+import { TriggerTypes } from '../js/level/TriggerTypes.js';
+import { EventHandler } from '../js/util/EventHandler.js';
+import { runScenarioTable } from './support/scenario-table.js';
+import {
+  createHistoryFixture,
+  createStubTimer,
+  recordTick,
+  runHistoryOps,
+  scenario,
+  seedHistory
+} from './support/history-fixtures.js';
+
+describe('HistoryStore retention', function() {
+  it('applies keyframes across game subsystems', function() {
+    const history = new HistoryStore();
+    const walkAction = { name: 'walk' };
+    const bomberAction = { name: 'bomber' };
+    const created = [];
+    function LemCtor(x, y, id) {
+      this.id = id;
+      this.x = x;
+      this.y = y;
+      created.push(this);
+    }
+    const skillActions = [];
+    skillActions[SkillTypes.BOMBER] = bomberAction;
+    const manager = {
+      lemmings: [],
+      actions: [walkAction],
+      skillActions,
+      _lemmingCtor: LemCtor,
+      activeLemmings: [],
+      _activeDirty: true,
+      actionTypeByAction: new Map([[walkAction, 0]]),
+      miniMap: { deadDots: new Uint8Array([1, 2]), deadTTLs: new Uint8Array([3]), deadCount: 1 },
+      getLemming: id => manager.lemmings[id] ?? null
+    };
+    const staticTrigger = new Trigger(TriggerTypes.TRAP, 1, 1, 2, 2, 0, 0, null);
+    const existingOwner = { id: 0 };
+    const existingTrigger = new Trigger(TriggerTypes.FRYING, 2, 2, 3, 3, 0, 0, existingOwner);
+    const level = {
+      entrances: [{ _opened: false }],
+      triggers: [staticTrigger],
+      objects: [{ animation: { firstFrameIndex: 0, isFinished: false } }],
+      groundMask: { mask: new Uint8Array(4) },
+      groundImage: new Uint8ClampedArray(16)
+    };
+    const triggerManager = {
+      _triggers: new Set([staticTrigger, existingTrigger]),
+      add(trig) { this._triggers.add(trig); },
+      removeByOwner(owner) {
+        for (const trig of Array.from(this._triggers)) {
+          if (trig.owner === owner) this._triggers.delete(trig);
+        }
+      }
+    };
+    const victory = {
+      releaseRate: 1,
+      minReleaseRate: 1,
+      leftCount: 1,
+      outCount: 0,
+      survivorCount: 0,
+      isFinalize: false
+    };
+    const skills = { selectedSkill: 0, cheatMode: false, skills: [1] };
+    const timer = { speedFactor: 1, tickIndex: 0, frameTime: 60 };
+    const game = {
+      level,
+      triggerManager,
+      finalGameState: 0,
+      getLemmingManager: () => manager,
+      getGameSkills: () => skills,
+      getVictoryCondition: () => victory,
+      getGameTimer: () => timer
+    };
+    const lemmingState = {
+      present: new Uint8Array([1, 0]),
+      x: new Int32Array([10, 0]),
+      y: new Int32Array([20, 0]),
+      lookRight: new Uint8Array([1, 0]),
+      frameIndex: new Int32Array([2, 0]),
+      state: new Int32Array([3, 0]),
+      canClimb: new Uint8Array([1, 0]),
+      hasParachute: new Uint8Array([0, 0]),
+      removed: new Uint8Array([0, 0]),
+      disabled: new Uint8Array([0, 0]),
+      countdown: new Int32Array([5, 0]),
+      hasExploded: new Uint8Array([0, 0]),
+      lastTriggerType: new Int32Array([TriggerTypes.TRAP, -1]),
+      actionType: new Int32Array([0, -1]),
+      countdownActive: new Uint8Array([1, 0])
+    };
+    const keyframe = {
+      tickIndex: 10,
+      lemmingState,
+      lemmingManagerState: {
+        selectedIndex: 1,
+        spawnTotal: 2,
+        releaseTickIndex: 3,
+        mmTickCounter: 4,
+        nextNukingLemmingsIndex: 5,
+        nukeTargets: [0, 99]
+      },
+      entranceOpened: new Uint8Array([1]),
+      triggerState: {
+        staticTriggers: [{ id: 100, disabledUntilTick: 7 }],
+        dynamicTriggers: [{
+          id: 200,
+          ownerId: 0,
+          type: TriggerTypes.KILL,
+          x1: 0,
+          y1: 0,
+          x2: 1,
+          y2: 1,
+          disableTicksCount: 0,
+          soundIndex: 2,
+          disabledUntilTick: 4
+        }]
+      },
+      objectState: [{
+        id: history._ensureObjectId(level.objects[0]),
+        firstFrameIndex: 5,
+        isFinished: true
+      }],
+      minimapState: { deadDots: new Uint8Array([9, 10]), deadTTLs: new Uint8Array([5]), deadCount: 1 },
+      groundMask: new Uint8Array([1, 1, 0, 0]),
+      groundImage: new Uint8ClampedArray(16).fill(2),
+      victory: { releaseRate: 2, minReleaseRate: 1, leftCount: 0, outCount: 1, survivorCount: 1, isFinalize: true },
+      skills: { selectedSkill: 1, cheatMode: true, skills: [9] },
+      timer: { speedFactor: 2, tickIndex: 5 },
+      gameState: { finalGameState: 9 }
+    };
+
+    history.applyKeyframe(game, keyframe);
+
+    expect(created).to.have.length(1);
+    expect(manager.lemmings[0]).to.be.ok;
+    expect(manager.lemmings[1]).to.equal(null);
+    expect(manager.activeLemmings).to.have.length(1);
+    expect(manager.activeLemmings[0].action).to.equal(walkAction);
+    expect(manager.activeLemmings[0].countdownAction).to.equal(bomberAction);
+    expect(manager.selectedIndex).to.equal(1);
+    expect(manager._nukeTargets).to.eql([manager.lemmings[0]]);
+    expect(level.entrances[0]._opened).to.equal(true);
+    expect(level.objects[0].animation.firstFrameIndex).to.equal(5);
+    expect(manager.miniMap.deadDots[0]).to.equal(9);
+    expect(level.groundMask.mask[0]).to.equal(1);
+    expect(victory.releaseRate).to.equal(2);
+    expect(skills.selectedSkill).to.equal(1);
+    expect(timer.speedFactor).to.equal(2);
+    expect(game.finalGameState).to.equal(9);
+  });
+
+  it('applies ground changes without spans and scans triggers by id', function() {
+    const history = new HistoryStore();
+    const level = {
+      groundMask: { mask: new Uint8Array(4) },
+      groundImage: new Uint8ClampedArray(16)
+    };
+    const changes = {
+      spans: null,
+      indices: [2],
+      prevMask: [0],
+      prevR: [0],
+      prevG: [0],
+      prevB: [0],
+      nextMask: [1],
+      nextR: [10],
+      nextG: [20],
+      nextB: [30]
+    };
+
+    history._applyGroundChanges(level, changes, true);
+    expect(level.groundMask.mask[2]).to.equal(1);
+    expect(level.groundImage[8]).to.equal(10);
+
+    const trigger = new Trigger(TriggerTypes.TRAP, 1, 1, 2, 2);
+    trigger.__historyId = 9;
+    const triggerManager = { _triggers: new Set([trigger]) };
+    const found = history._findTriggerById(triggerManager, 9);
+    expect(found).to.equal(trigger);
+  });
+
+  it('returns null from readers with missing inputs', function() {
+    const history = new HistoryStore();
+    expect(history._readSkills(null)).to.equal(null);
+    expect(history._readVictory(null)).to.equal(null);
+    expect(history._readTimer(null)).to.equal(null);
+    expect(history._readGameState(null)).to.equal(null);
+    expect(history._skillsEqual(null, null)).to.equal(false);
+    expect(history._victoryEqual(null, null)).to.equal(false);
+    expect(history._timerEqual(null, null)).to.equal(false);
+    expect(history._gameStateEqual(null, null)).to.equal(false);
+  });
+
+  it('skips ownerless trigger entries when reading state', function() {
+    const history = new HistoryStore();
+    const level = { triggers: [null] };
+    const triggerManager = { _triggers: new Set([new Trigger(TriggerTypes.TRAP, 1, 1, 2, 2)]) };
+    const game = { level, triggerManager };
+    const state = history._readTriggerState(game);
+    expect(state.staticTriggers).to.have.length(0);
+    expect(state.dynamicTriggers).to.have.length(0);
+  });
+
+  it('exposes lemming helpers for snapshots and cloning', function() {
+    const state = __test__.createLemmingState(1);
+    state.present[0] = 1;
+    state.x[0] = 7;
+    state.y[0] = 8;
+    state.lookRight[0] = 1;
+    state.countdownActive[0] = 1;
+
+    const cloneDefault = __test__.cloneLemmingState(state);
+    const cloneShort = __test__.cloneLemmingState(state, 0);
+    expect(cloneDefault.present.length).to.equal(1);
+    expect(cloneShort.present.length).to.equal(0);
+
+    const grown = __test__.ensureLemmingCapacity(state, 2);
+    const same = __test__.ensureLemmingCapacity(grown, 1);
+    expect(grown.present.length).to.be.at.least(2);
+    expect(same).to.equal(grown);
+
+    const lem = {
+      id: 1,
+      x: 2,
+      y: 3,
+      lookRight: false,
+      frameIndex: 4,
+      state: null,
+      canClimb: true,
+      hasParachute: false,
+      removed: false,
+      disabled: true,
+      countdown: null,
+      hasExploded: true,
+      lastTriggerType: NaN
+    };
+    const snap = __test__.snapshotLemming(lem, NaN, false);
+    expect(snap.lastTriggerType).to.equal(-1);
+    expect(snap.actionType).to.equal(-1);
+    expect(snap.countdownActive).to.equal(0);
+
+    const walk = { name: 'walk' };
+    const bomb = { name: 'bomber' };
+    const target = {};
+    __test__.applyLemmingSnapshot(
+      target,
+      { ...snap, lastTriggerType: 3, countdownActive: 1 },
+      walk,
+      bomb
+    );
+    expect(target.lastTriggerType).to.equal(3);
+    expect(target.action).to.equal(walk);
+    expect(target.countdownAction).to.equal(bomb);
+
+    __test__.applyLemmingSnapshot(
+      target,
+      { ...snap, lastTriggerType: -1, countdownActive: 0 },
+      null,
+      bomb
+    );
+    expect(target.lastTriggerType).to.equal(null);
+    expect(target.countdownAction).to.equal(null);
+  });
+
+  it('reports history stats and keyframe lookups', function() {
+    const history = new HistoryStore();
+    expect(history.getKeyframe(NaN)).to.equal(null);
+    expect(history.getHistoryStats().spanTicks).to.equal(0);
+
+    seedHistory(history, { deltas: [0, 2], keyframes: [2] });
+    expect(history.getKeyframe(2)).to.be.ok;
+    expect(history.getKeyframe(4)).to.equal(null);
+
+    const stats = history.getHistoryStats();
+    expect(stats.spanTicks).to.equal(3);
+    expect(stats.deltaCount).to.equal(2);
+
+    seedHistory(history, { keyframes: [5] });
+    const found = history.getKeyframeAtOrBefore(4);
+    expect(found.tickIndex).to.equal(2);
+  });
+
+  it('uses bounded retention defaults and normalizes retention settings', function() {
+    const history = new HistoryStore();
+    expect(history.getRetentionPolicy()).to.eql({
+      preserveFutureHistory: false,
+      enableHistoryCap: true,
+      historyCapTicks: 20000,
+      historyWarnTicks: 15000
+    });
+
+    const normalized = new HistoryStore({
+      enableHistoryCap: true,
+      historyCapTicks: 10,
+      historyWarnTicks: 50
+    });
+    expect(normalized.getRetentionPolicy().historyWarnTicks).to.equal(10);
+
+    const configured = normalized.configureRetention({
+      enableHistoryCap: false,
+      historyCapTicks: 5,
+      historyWarnTicks: 3
+    });
+    expect(configured).to.eql({
+      preserveFutureHistory: false,
+      enableHistoryCap: false,
+      historyCapTicks: 5,
+      historyWarnTicks: 3
+    });
+    expect(normalized.getHistoryStats().retention).to.eql(configured);
+  });
+
+  it('pauses and resumes recording with baseline updates', function() {
+    const { history } = createHistoryFixture();
+    history.beginTick(0);
+    history.pause();
+    expect(history._recording).to.equal(false);
+    expect(history._currentDelta).to.equal(null);
+
+    history.resume();
+    expect(history._recording).to.equal(true);
+    expect(history._groundDirty).to.equal(true);
+  });
+
+  it('truncates deltas and keyframes across gaps', function() {
+    const history = new HistoryStore({ keyframeInterval: 2 });
+    seedHistory(history, { deltas: [0, 2], keyframes: [0, 2] });
+
+    history._truncateDeltasAfter(1);
+    expect(history.maxDeltaTick).to.equal(0);
+    history._truncateDeltasAfter(-1);
+    expect(history.minDeltaTick).to.equal(null);
+
+    history._truncateKeyframesAfter(-1);
+    expect(history.keyframeTicks).to.have.length(0);
+    expect(history.minKeyframeTick).to.equal(null);
+  });
+});
diff --git a/test/history-store.state-apply.test.js b/test/history-store.state-apply.test.js
new file mode 100644
index 00000000..3ebe0b59
--- /dev/null
+++ b/test/history-store.state-apply.test.js
@@ -0,0 +1,478 @@
+import { expect } from 'chai';
+import { withConsoleStub } from './helpers/console.js';
+import { HistoryStore, __test__ } from '../js/game/HistoryStore.js';
+import { SkillTypes } from '../js/game/SkillTypes.js';
+import { Trigger } from '../js/level/Trigger.js';
+import { TriggerTypes } from '../js/level/TriggerTypes.js';
+import { EventHandler } from '../js/util/EventHandler.js';
+import { runScenarioTable } from './support/scenario-table.js';
+import {
+  createHistoryFixture,
+  createStubTimer,
+  recordTick,
+  runHistoryOps,
+  scenario,
+  seedHistory
+} from './support/history-fixtures.js';
+
+describe('HistoryStore state application', function() {
+  it('inserts keyframe ticks in order and skips duplicates', function() {
+    const history = new HistoryStore();
+    history._insertKeyframeTick(2);
+    history._insertKeyframeTick(2);
+    history._insertKeyframeTick(1);
+    expect(history.keyframeTicks).to.eql([1, 2]);
+  });
+
+  it('compresses ground changes into spans', function() {
+    const history = new HistoryStore();
+    const changes = { indices: [5], spans: null };
+    history._compressGroundChanges(changes);
+    expect(changes.spans).to.equal(null);
+
+    changes.indices = [1, 2, 4, 5];
+    history._compressGroundChanges(changes);
+    expect(changes.spans.starts).to.eql([1, 4]);
+    expect(changes.spans.lengths).to.eql([2, 2]);
+    expect(changes.indices).to.have.length(0);
+  });
+
+  it('enforces history caps only when needed', function() {
+    const history = new HistoryStore({
+      enableHistoryCap: true,
+      historyCapTicks: 0
+    });
+    seedHistory(history, { deltas: [0] });
+    history._enforceHistoryCap();
+    expect(history.getDelta(0)).to.be.ok;
+
+    const capped = new HistoryStore({
+      enableHistoryCap: true,
+      historyCapTicks: 3
+    });
+    seedHistory(capped, { deltas: [0, 1, 2] });
+    capped._enforceHistoryCap();
+    expect(capped.getDelta(0)).to.be.ok;
+  });
+
+  it('reuses previous ground snapshots when not dirty', function() {
+    const { history, game } = createHistoryFixture();
+    history._groundDirty = false;
+    history._lastKeyframe = {
+      groundMask: new Uint8Array([9, 9]),
+      groundImage: new Uint8ClampedArray([1, 2, 3, 4])
+    };
+
+    const frame = history._captureKeyframe(game, 0);
+
+    expect(frame.groundMask).to.equal(history._lastKeyframe.groundMask);
+    expect(frame.groundImage).to.equal(history._lastKeyframe.groundImage);
+  });
+
+  it('applies ground changes with spans', function() {
+    const history = new HistoryStore();
+    const level = {
+      groundMask: { mask: new Uint8Array(4) },
+      groundImage: new Uint8ClampedArray(16)
+    };
+    const changes = {
+      spans: { starts: [0], lengths: [2] },
+      indices: [],
+      prevMask: [],
+      prevR: [],
+      prevG: [],
+      prevB: [],
+      nextMask: [1, 1],
+      nextR: [10, 20],
+      nextG: [30, 40],
+      nextB: [50, 60]
+    };
+
+    history._applyGroundChanges(level, changes, true);
+
+    expect(level.groundMask.mask[0]).to.equal(1);
+    expect(level.groundMask.mask[1]).to.equal(1);
+    expect(level.groundImage[0]).to.equal(10);
+    expect(level.groundImage[4]).to.equal(20);
+  });
+
+  it('applies minimap deaths forward and backward', function() {
+    const history = new HistoryStore();
+    const manager = {
+      miniMap: {
+        deadDots: new Uint8Array(0),
+        deadTTLs: new Uint8Array(0),
+        deadCount: 0
+      }
+    };
+    history._applyMinimapDeaths(manager, [{ x: 1, y: 2, ttl: 3, prevCount: 0 }], true);
+    expect(manager.miniMap.deadCount).to.equal(1);
+    history._applyMinimapDeaths(manager, [{ prevCount: 0 }], false);
+    expect(manager.miniMap.deadCount).to.equal(0);
+  });
+
+  it('handles trigger id lookups from cache', function() {
+    const history = new HistoryStore();
+    const trigger = new Trigger(TriggerTypes.TRAP, 1, 1, 2, 2);
+    trigger.__historyId = 5;
+    history._triggerById.set(5, trigger);
+    expect(history._findTriggerById({ _triggers: new Set() }, 5)).to.equal(trigger);
+    expect(history._findTriggerById({ _triggers: new Set() }, 0)).to.equal(null);
+  });
+
+  it('truncates history before a cutoff', function() {
+    const history = new HistoryStore({ keyframeInterval: 2 });
+    seedHistory(history, { deltas: [0, 1, 2], keyframes: [0, 2] });
+
+    history._truncateBefore(2);
+
+    expect(history.getDelta(0)).to.equal(null);
+    expect(history.getDelta(1)).to.equal(null);
+    expect(history.getDelta(2)).to.be.ok;
+    expect(history.minDeltaTick).to.equal(2);
+    expect(history.keyframes[0]).to.equal(undefined);
+    expect(history.keyframes[2]).to.be.ok;
+    expect(history.minKeyframeTick).to.equal(2);
+  });
+
+  it('reads and applies trigger state snapshots', function() {
+    const { history, game, manager, triggerManager, level } = createHistoryFixture();
+    const owner = manager.lemmings[0];
+    const staticTrigger = new Trigger(TriggerTypes.TRAP, 1, 1, 2, 2, 0, 5, null);
+    staticTrigger.disabledUntilTick = 5;
+    const dynamicTrigger = new Trigger(TriggerTypes.FRYING, 3, 3, 4, 4, 0, 7, owner);
+    const extraTrigger = new Trigger(TriggerTypes.KILL, 5, 5, 6, 6, 0, 8, owner);
+    level.triggers = [staticTrigger];
+    triggerManager._triggers.add(staticTrigger);
+    triggerManager._triggers.add(dynamicTrigger);
+    triggerManager._triggers.add(extraTrigger);
+
+    const state = history._readTriggerState(game);
+    expect(state.staticTriggers).to.have.length(1);
+    expect(state.dynamicTriggers).to.have.length(2);
+    expect(state.staticTriggers[0].disabledUntilTick).to.equal(5);
+
+    staticTrigger.disabledUntilTick = 0;
+    state.dynamicTriggers = state.dynamicTriggers.slice(0, 1);
+    history._applyTriggerState(game, state);
+
+    expect(staticTrigger.disabledUntilTick).to.equal(5);
+    const dynamic = Array.from(triggerManager._triggers)
+      .filter(tr => tr.owner === owner);
+    expect(dynamic).to.have.length(1);
+    expect(dynamic[0].type).to.equal(state.dynamicTriggers[0].type);
+  });
+
+  it('captures and restores object animation state', function() {
+    const { history, level } = createHistoryFixture();
+    const objA = { animation: { firstFrameIndex: 1, isFinished: false } };
+    const objB = { animation: { firstFrameIndex: 5, isFinished: true } };
+    level.objects = [objA, objB];
+
+    const state = history._readObjectState(level);
+    objA.animation.firstFrameIndex = 9;
+    objA.animation.isFinished = true;
+    objB.animation.firstFrameIndex = 11;
+    objB.animation.isFinished = false;
+
+    history._applyObjectState(level, state);
+
+    expect(objA.animation.firstFrameIndex).to.equal(1);
+    expect(objA.animation.isFinished).to.equal(false);
+    expect(objB.animation.firstFrameIndex).to.equal(5);
+    expect(objB.animation.isFinished).to.equal(true);
+  });
+
+  it('copies minimap state when reading', function() {
+    const { history } = createHistoryFixture();
+    const miniMap = {
+      deadDots: new Uint8Array([1, 2]),
+      deadTTLs: new Uint8Array([3]),
+      deadCount: 1
+    };
+    const state = history._readMinimapState(miniMap);
+    expect(Array.from(state.deadDots)).to.eql([1, 2]);
+    state.deadDots[0] = 9;
+    expect(miniMap.deadDots[0]).to.equal(1);
+  });
+
+  it('caps history and warns when configured', function() {
+    const history = new HistoryStore({
+      enableHistoryCap: true,
+      historyCapTicks: 2,
+      historyWarnTicks: 2
+    });
+    const warnings = [];
+    const restoreConsole = withConsoleStub({ warn: msg => warnings.push(msg) });
+    try {
+      seedHistory(history, { deltas: [0, 1] });
+      history._maybeWarnHistory();
+      expect(warnings).to.have.length(1);
+      history._maybeWarnHistory();
+      expect(warnings).to.have.length(1);
+
+      seedHistory(history, { deltas: [2] });
+      history._enforceHistoryCap();
+      expect(history.getDelta(0)).to.equal(null);
+      expect(history.getDelta(1)).to.be.ok;
+      expect(history.getDelta(2)).to.be.ok;
+    } finally {
+      restoreConsole();
+    }
+  });
+
+  it('returns action types from map or actions list', function() {
+    const history = new HistoryStore();
+    const actionA = { name: 'action-a' };
+    const actionB = { name: 'action-b' };
+    const manager = {
+      actions: [actionA, actionB],
+      actionTypeByAction: new Map([[actionA, 7]])
+    };
+
+    expect(history._getActionType(manager, actionA)).to.equal(7);
+    expect(history._getActionType(manager, actionB)).to.equal(1);
+    expect(history._getActionType(manager, null)).to.equal(-1);
+    expect(history._getActionType({ actions: [actionA] }, { name: 'missing' })).to.equal(-1);
+  });
+
+  it('removes lemmings when slots clear or the array shrinks', function() {
+    const timer = createStubTimer();
+    const walkAction = { name: 'walk' };
+    const makeLemming = (id) => ({
+      id,
+      x: id,
+      y: id + 1,
+      lookRight: true,
+      frameIndex: 0,
+      state: 0,
+      canClimb: false,
+      hasParachute: false,
+      removed: false,
+      disabled: false,
+      countdown: 0,
+      hasExploded: false,
+      lastTriggerType: null,
+      action: walkAction,
+      countdownAction: null
+    });
+    const lemmingA = makeLemming(0);
+    const lemmingB = makeLemming(1);
+    const manager = {
+      lemmings: [lemmingA, lemmingB],
+      activeLemmings: [lemmingA, lemmingB],
+      _activeDirty: false,
+      actions: [walkAction],
+      skillActions: [],
+      _lemmingCtor: function ReplayCtor(x, y, id) {
+        this.x = x;
+        this.y = y;
+        this.id = id;
+      },
+      actionTypeByAction: new Map([[walkAction, 0]]),
+      selectedIndex: -1,
+      spawnTotal: 2,
+      releaseTickIndex: 0,
+      mmTickCounter: 0,
+      nextNukingLemmingsIndex: -1,
+      _nukeTargets: null
+    };
+    const game = {
+      level: { entrances: [] },
+      finalGameState: 0,
+      getLemmingManager: () => manager,
+      getGameTimer: () => timer,
+      getGameSkills: () => null,
+      getVictoryCondition: () => null
+    };
+    const history = new HistoryStore({ keyframeInterval: 5 });
+    history.attach(game, { captureBaseline: true });
+
+    scenario(history, timer).tick(0, {
+      mutate() {
+        manager.lemmings[0] = null;
+        manager.lemmings.length = 1;
+      }
+    });
+
+    const delta = history.getDelta(0);
+    expect(delta.lemRemoved).to.have.length(2);
+
+    history.applyDeltaBackward(game, delta);
+    expect(manager.lemmings[0]).to.be.ok;
+    expect(manager.lemmings[1]).to.be.ok;
+
+    history.applyDeltaForward(game, delta);
+    expect(manager.lemmings[0]).to.equal(null);
+    expect(manager.lemmings[1]).to.equal(null);
+  });
+
+  it('applies all lemming field changes', function() {
+    const timer = createStubTimer();
+    const walkAction = { name: 'walk' };
+    const bomberAction = { name: 'bomber' };
+    const skillActions = [];
+    skillActions[SkillTypes.BOMBER] = bomberAction;
+    const lemming = {
+      id: 0,
+      x: 5,
+      y: 6,
+      lookRight: true,
+      frameIndex: 0,
+      state: 1,
+      canClimb: false,
+      hasParachute: false,
+      removed: false,
+      disabled: false,
+      countdown: 0,
+      hasExploded: false,
+      lastTriggerType: 4,
+      action: walkAction,
+      countdownAction: null
+    };
+    const manager = {
+      lemmings: [lemming],
+      activeLemmings: [lemming],
+      _activeDirty: false,
+      actions: [walkAction],
+      skillActions,
+      actionTypeByAction: new Map([[walkAction, 0]]),
+      selectedIndex: -1,
+      spawnTotal: 1,
+      releaseTickIndex: 0,
+      mmTickCounter: 0,
+      nextNukingLemmingsIndex: -1,
+      _nukeTargets: null
+    };
+    const game = {
+      level: { entrances: [] },
+      finalGameState: 0,
+      getLemmingManager: () => manager,
+      getGameTimer: () => timer,
+      getGameSkills: () => null,
+      getVictoryCondition: () => null
+    };
+    const history = new HistoryStore({ keyframeInterval: 5 });
+    history.attach(game, { captureBaseline: true });
+
+    scenario(history, timer).tick(0, {
+      mutate() {
+        lemming.x = 11;
+        lemming.y = 22;
+        lemming.lookRight = false;
+        lemming.frameIndex = 3;
+        lemming.state = 2;
+        lemming.canClimb = true;
+        lemming.hasParachute = true;
+        lemming.removed = true;
+        lemming.disabled = true;
+        lemming.countdown = 5;
+        lemming.hasExploded = true;
+        lemming.lastTriggerType = null;
+        lemming.action = null;
+        lemming.countdownAction = bomberAction;
+      }
+    });
+
+    const delta = history.getDelta(0);
+    history.applyDeltaForward(game, delta);
+
+    expect(lemming.x).to.equal(11);
+    expect(lemming.y).to.equal(22);
+    expect(lemming.lookRight).to.equal(false);
+    expect(lemming.frameIndex).to.equal(3);
+    expect(lemming.state).to.equal(2);
+    expect(lemming.canClimb).to.equal(true);
+    expect(lemming.hasParachute).to.equal(true);
+    expect(lemming.removed).to.equal(true);
+    expect(lemming.disabled).to.equal(true);
+    expect(lemming.countdown).to.equal(5);
+    expect(lemming.hasExploded).to.equal(true);
+    expect(lemming.lastTriggerType).to.equal(null);
+    expect(lemming.action).to.equal(null);
+    expect(lemming.countdownAction).to.equal(bomberAction);
+
+    history.applyDeltaBackward(game, delta);
+    expect(lemming.x).to.equal(5);
+    expect(lemming.y).to.equal(6);
+    expect(lemming.lookRight).to.equal(true);
+    expect(lemming.frameIndex).to.equal(0);
+    expect(lemming.state).to.equal(1);
+    expect(lemming.canClimb).to.equal(false);
+    expect(lemming.hasParachute).to.equal(false);
+    expect(lemming.removed).to.equal(false);
+    expect(lemming.disabled).to.equal(false);
+    expect(lemming.countdown).to.equal(0);
+    expect(lemming.hasExploded).to.equal(false);
+    expect(lemming.lastTriggerType).to.equal(4);
+    expect(lemming.action).to.equal(walkAction);
+    expect(lemming.countdownAction).to.equal(null);
+  });
+
+  it('applies lemming manager nuke target changes', function() {
+    const timer = createStubTimer();
+    const walkAction = { name: 'walk' };
+    const makeLemming = (id) => ({
+      id,
+      x: id,
+      y: id + 1,
+      lookRight: true,
+      frameIndex: 0,
+      state: 0,
+      canClimb: false,
+      hasParachute: false,
+      removed: false,
+      disabled: false,
+      countdown: 0,
+      hasExploded: false,
+      lastTriggerType: null,
+      action: walkAction,
+      countdownAction: null
+    });
+    const lemmingA = makeLemming(0);
+    const lemmingB = makeLemming(1);
+    const manager = {
+      lemmings: [lemmingA, lemmingB],
+      activeLemmings: [lemmingA, lemmingB],
+      _activeDirty: false,
+      actions: [walkAction],
+      skillActions: [],
+      actionTypeByAction: new Map([[walkAction, 0]]),
+      selectedIndex: -1,
+      spawnTotal: 2,
+      releaseTickIndex: 0,
+      mmTickCounter: 0,
+      nextNukingLemmingsIndex: -1,
+      _nukeTargets: [lemmingA]
+    };
+    const game = {
+      level: { entrances: [] },
+      finalGameState: 0,
+      getLemmingManager: () => manager,
+      getGameTimer: () => timer,
+      getGameSkills: () => null,
+      getVictoryCondition: () => null
+    };
+    const history = new HistoryStore({ keyframeInterval: 5 });
+    history.attach(game, { captureBaseline: true });
+
+    scenario(history, timer).tick(0, {
+      mutate() {
+        manager.selectedIndex = 1;
+        manager.nextNukingLemmingsIndex = 2;
+        manager._nukeTargets = [lemmingB, null];
+      }
+    });
+
+    const delta = history.getDelta(0);
+    history.applyDeltaForward(game, delta);
+    expect(manager.selectedIndex).to.equal(1);
+    expect(manager.nextNukingLemmingsIndex).to.equal(2);
+    expect(manager._nukeTargets).to.eql([lemmingB]);
+
+    history.applyDeltaBackward(game, delta);
+    expect(manager.selectedIndex).to.equal(-1);
+    expect(manager.nextNukingLemmingsIndex).to.equal(-1);
+    expect(manager._nukeTargets).to.eql([lemmingA]);
+  });
+});
diff --git a/test/history-store.test.js b/test/history-store.test.js
deleted file mode 100644
index 00a58a80..00000000
--- a/test/history-store.test.js
+++ /dev/null
@@ -1,3050 +0,0 @@
-import { expect } from 'chai';
-import { withConsoleStub } from './helpers/console.js';
-import { HistoryStore, __test__ } from '../js/game/HistoryStore.js';
-import { SkillTypes } from '../js/game/SkillTypes.js';
-import { Trigger } from '../js/level/Trigger.js';
-import { TriggerTypes } from '../js/level/TriggerTypes.js';
-import { EventHandler } from '../js/util/EventHandler.js';
-
-const createStubTimer = () => ({
-  tickIndex: 0,
-  speedFactor: 1,
-  frameTime: 60,
-  onBeforeGameTick: { on() {}, off() {} },
-  onGameTick: { on() {}, off() {} }
-});
-
-const createHistoryFixture = () => {
-  const timer = createStubTimer();
-  const walkAction = { name: 'walk' };
-  const bomberAction = { name: 'bomber' };
-  const lemming = {
-    id: 0,
-    x: 5,
-    y: 6,
-    lookRight: true,
-    frameIndex: 0,
-    state: 1,
-    canClimb: false,
-    hasParachute: false,
-    removed: false,
-    disabled: false,
-    countdown: 0,
-    hasExploded: false,
-    lastTriggerType: null,
-    action: walkAction,
-    countdownAction: null
-  };
-  const skillActions = [];
-  skillActions[SkillTypes.BOMBER] = bomberAction;
-  const manager = {
-    lemmings: [lemming],
-    activeLemmings: [lemming],
-    _activeDirty: false,
-    actions: [walkAction],
-    skillActions,
-    actionTypeByAction: new Map([[walkAction, 0]]),
-    selectedIndex: -1,
-    spawnTotal: 1,
-    releaseTickIndex: 0,
-    mmTickCounter: 0,
-    nextNukingLemmingsIndex: -1,
-    _nukeTargets: null,
-    miniMap: null,
-    getLemming: (id) => manager.lemmings[id] ?? null
-  };
-  const skills = { selectedSkill: 0, cheatMode: false, skills: [1] };
-  const victory = {
-    releaseRate: 1,
-    minReleaseRate: 1,
-    leftCount: 1,
-    outCount: 0,
-    survivorCount: 0,
-    isFinalize: false
-  };
-  const level = {
-    entrances: [{ _opened: false }],
-    groundMask: { mask: new Uint8Array(4) },
-    groundImage: new Uint8ClampedArray(16),
-    objects: [],
-    triggers: []
-  };
-  const triggerManager = {
-    _triggers: new Set(),
-    add(trigger) { this._triggers.add(trigger); },
-    removeByOwner(owner) {
-      for (const trig of Array.from(this._triggers)) {
-        if (trig.owner === owner) this._triggers.delete(trig);
-      }
-    }
-  };
-  const game = {
-    level,
-    triggerManager,
-    finalGameState: 0,
-    getLemmingManager: () => manager,
-    getGameTimer: () => timer,
-    getGameSkills: () => skills,
-    getVictoryCondition: () => victory
-  };
-  const history = new HistoryStore({ keyframeInterval: 5 });
-  history.attach(game, { captureBaseline: true });
-  return {
-    history,
-    game,
-    timer,
-    manager,
-    skills,
-    victory,
-    level,
-    triggerManager,
-    lemming,
-    walkAction,
-    bomberAction
-  };
-};
-
-const recordTick = (history, timer, tickIndex, mutate, nextTick = tickIndex + 1) => {
-  history.beginTick(tickIndex);
-  if (mutate) mutate();
-  if (timer) timer.tickIndex = nextTick;
-  history.endTick();
-};
-
-const runHistoryOps = (history, ops) => {
-  for (const [method, ...args] of ops) {
-    history[method](...args);
-  }
-};
-
-const scenario = (history, timer) => {
-  const api = {
-    tick(tickIndex, { ops = null, mutate = null, nextTick } = {}) {
-      recordTick(history, timer, tickIndex, () => {
-        if (ops && ops.length) runHistoryOps(history, ops);
-        if (mutate) mutate();
-      }, nextTick);
-      return api;
-    }
-  };
-  return api;
-};
-
-const seedHistory = (history, { deltas = [], keyframes = [] } = {}) => {
-  for (const tick of deltas) {
-    history._setDelta(tick, history._allocDelta(tick));
-  }
-  for (const tick of keyframes) {
-    history._setKeyframe(tick, { tickIndex: tick });
-  }
-};
-
-describe('HistoryStore', function() {
-  it('captures lemming deltas and can replay them', function() {
-    const { history, game, timer, manager } = createHistoryFixture();
-    recordTick(history, timer, 0, () => {
-      manager.lemmings[0].x = 10;
-      manager.lemmings[0].y = 12;
-      manager.selectedIndex = 0;
-    });
-
-    const delta = history.getDelta(0);
-    expect(delta).to.be.ok;
-
-    history.applyDeltaBackward(game, delta);
-    expect(manager.lemmings[0].x).to.equal(5);
-    expect(manager.lemmings[0].y).to.equal(6);
-    expect(manager.selectedIndex).to.equal(-1);
-
-    history.applyDeltaForward(game, delta);
-    expect(manager.lemmings[0].x).to.equal(10);
-    expect(manager.lemmings[0].y).to.equal(12);
-    expect(manager.selectedIndex).to.equal(0);
-  });
-
-  it('truncates future history unless preservation is enabled', function() {
-    const history = new HistoryStore({ keyframeInterval: 5 });
-    seedHistory(history, { deltas: [0, 2], keyframes: [0, 2] });
-
-    history.truncateAfter(0);
-    expect(!!history.deltas[2]).to.equal(false);
-    expect(!!history.keyframes[2]).to.equal(false);
-
-    seedHistory(history, { deltas: [2], keyframes: [2] });
-    history.setPreserveFutureHistory(true);
-    history.truncateAfter(0);
-    expect(!!history.deltas[2]).to.equal(true);
-    expect(!!history.keyframes[2]).to.equal(true);
-  });
-
-  it('snapshots lemming boolean flags', function() {
-    const lem = {
-      id: 1,
-      x: 0,
-      y: 0,
-      lookRight: false,
-      frameIndex: 0,
-      state: 0,
-      canClimb: false,
-      hasParachute: true,
-      removed: true,
-      disabled: true,
-      countdown: 0,
-      hasExploded: false,
-      lastTriggerType: 1
-    };
-    const snap = __test__.snapshotLemming(lem, 2, true);
-    expect(snap.hasParachute).to.equal(1);
-    expect(snap.removed).to.equal(1);
-    expect(snap.disabled).to.equal(1);
-    expect(snap.countdownActive).to.equal(1);
-  });
-
-  it('handles keyframe access and resume without a game', function() {
-    const history = new HistoryStore();
-    expect(history.getKeyframe('bad')).to.equal(null);
-    history.resume();
-  });
-
-  it('truncates all deltas when cutting after the last tick', function() {
-    const history = new HistoryStore();
-    history.deltas[1] = history._allocDelta(1);
-    history.minDeltaTick = 1;
-    history.maxDeltaTick = 1;
-    history.deltaCount = 1;
-    history._truncateDeltasAfter(0);
-    expect(history.minDeltaTick).to.equal(null);
-    expect(history.maxDeltaTick).to.equal(null);
-  });
-
-  it('truncates deltas before a cutoff and clears ranges', function() {
-    const history = new HistoryStore();
-    history.deltas[0] = history._allocDelta(0);
-    history.deltas[1] = history._allocDelta(1);
-    history.minDeltaTick = 0;
-    history.maxDeltaTick = 1;
-    history.deltaCount = 2;
-    history._truncateBefore(2);
-    expect(history.minDeltaTick).to.equal(null);
-    expect(history.maxDeltaTick).to.equal(null);
-  });
-
-  it('uses fallback tick indices when timers are missing', function() {
-    const history = new HistoryStore({ keyframeInterval: 1 });
-    history._recording = true;
-    history._currentTick = 0;
-    history._currentDelta = history._allocDelta(0);
-    history.game = {};
-    history.timer = { tickIndex: undefined };
-    history._diffState = () => {};
-    history._compressGroundChanges = () => {};
-    history._setDelta = () => {};
-    history._captureKeyframe = () => ({ tickIndex: 0 });
-    let keyframeTick = null;
-    history._setKeyframe = (tickIndex) => { keyframeTick = tickIndex; };
-    history._maybeWarnHistory = () => {};
-    history._enforceHistoryCap = () => {};
-    history.endTick();
-    expect(keyframeTick).to.equal(1);
-  });
-
-  it('compares skill arrays with missing values', function() {
-    const history = new HistoryStore();
-    const a = { selectedSkill: 1, cheatMode: false };
-    const b = { selectedSkill: 1, cheatMode: false, skills: [1] };
-    expect(history._skillsEqual(a, b)).to.equal(false);
-  });
-
-  it('applies keyframes with lemming list resizing and speed ignores', function() {
-    const history = new HistoryStore();
-    const timer = { speedFactor: 2, tickIndex: 0 };
-    const manager = { lemmings: [], skillActions: [], actions: [] };
-    const game = {
-      getLemmingManager: () => manager,
-      getGameTimer: () => timer,
-      timeTravel: { isReversing: true, ignoreSpeedOnReverse: true }
-    };
-    const stateSize = 2;
-    const keyframe = {
-      tickIndex: 1,
-      lemmingState: {
-        present: [true, true],
-        x: [0, 1],
-        y: [0, 1],
-        lookRight: [0, 1],
-        frameIndex: [0, 0],
-        state: [0, 0],
-        canClimb: [0, 0],
-        hasParachute: [0, 0],
-        removed: [0, 0],
-        disabled: [0, 0],
-        countdown: [0, 0],
-        hasExploded: [0, 0],
-        lastTriggerType: [-1, -1],
-        actionType: [-1, -1],
-        countdownActive: [0, 0]
-      },
-      timer: { speedFactor: 5, tickIndex: 1 }
-    };
-    history.applyKeyframe(game, keyframe);
-    expect(manager.lemmings).to.have.length(stateSize);
-    expect(timer.speedFactor).to.equal(2);
-  });
-
-  it('applies timer changes without overwriting reverse speed', function() {
-    const history = new HistoryStore();
-    const timer = { speedFactor: 3, tickIndex: 0 };
-    const game = {
-      getGameTimer: () => timer,
-      timeTravel: { ignoreSpeedOnReverse: true }
-    };
-    const delta = {
-      timerChanges: {
-        prev: { speedFactor: 10, tickIndex: 5 },
-        next: { speedFactor: 2, tickIndex: 2 }
-      }
-    };
-    history._applyScalarChanges(game, delta, false);
-    expect(timer.speedFactor).to.equal(3);
-    expect(timer.tickIndex).to.equal(5);
-  });
-
-  it('applies non-lemming deltas and scalar changes', function() {
-    const {
-      history,
-      game,
-      timer,
-      manager,
-      skills,
-      victory,
-      level
-    } = createHistoryFixture();
-
-    manager.miniMap = {
-      deadDots: new Uint8Array(0),
-      deadTTLs: new Uint8Array(0),
-      deadCount: 0
-    };
-
-    const obj = { animation: { firstFrameIndex: 0, isFinished: false } };
-    level.objects = [obj];
-    level.groundMask.mask[1] = 1;
-    level.groundMask.mask[2] = 1;
-    level.groundImage[4] = 10;
-    level.groundImage[5] = 20;
-    level.groundImage[6] = 30;
-    level.groundImage[8] = 11;
-    level.groundImage[9] = 21;
-    level.groundImage[10] = 31;
-
-    scenario(history, timer).tick(0, {
-      ops: [
-        ['recordGroundChange', 1, 1, 10, 20, 30, 0, 0, 0, 0],
-        ['recordGroundChange', 2, 1, 11, 21, 31, 0, 0, 0, 0],
-        ['recordEntranceChange', 0, false, true],
-        ['recordObjectAnimation', obj, { firstFrameIndex: 0, isFinished: false }, { firstFrameIndex: 5, isFinished: true }],
-        ['recordMinimapDeath', { x: 1, y: 2, ttl: 3, prevCount: 0 }]
-      ],
-      mutate() {
-        skills.selectedSkill = 1;
-        skills.cheatMode = true;
-        skills.skills[0] = 2;
-        victory.releaseRate = 2;
-        victory.leftCount = 0;
-        victory.outCount = 2;
-        victory.survivorCount = 1;
-        victory.isFinalize = true;
-        timer.speedFactor = 2;
-        game.finalGameState = 3;
-      }
-    });
-
-    const delta = history.getDelta(0);
-    history.applyDeltaForward(game, delta);
-
-    expect(level.groundMask.mask[1]).to.equal(0);
-    expect(level.groundMask.mask[2]).to.equal(0);
-    expect(level.groundImage[4]).to.equal(0);
-    expect(level.groundImage[8]).to.equal(0);
-    expect(level.entrances[0]._opened).to.equal(true);
-    expect(obj.animation.firstFrameIndex).to.equal(5);
-    expect(obj.animation.isFinished).to.equal(true);
-    expect(manager.miniMap.deadCount).to.equal(1);
-    expect(manager.miniMap.deadDots[0]).to.equal(1);
-    expect(manager.miniMap.deadDots[1]).to.equal(2);
-    expect(manager.miniMap.deadTTLs[0]).to.equal(3);
-    expect(skills.selectedSkill).to.equal(1);
-    expect(skills.cheatMode).to.equal(true);
-    expect(skills.skills[0]).to.equal(2);
-    expect(victory.releaseRate).to.equal(2);
-    expect(victory.leftCount).to.equal(0);
-    expect(victory.outCount).to.equal(2);
-    expect(victory.survivorCount).to.equal(1);
-    expect(victory.isFinalize).to.equal(true);
-    expect(timer.speedFactor).to.equal(2);
-    expect(timer.tickIndex).to.equal(1);
-    expect(game.finalGameState).to.equal(3);
-
-    history.applyDeltaBackward(game, delta);
-    expect(level.groundMask.mask[1]).to.equal(1);
-    expect(level.groundMask.mask[2]).to.equal(1);
-    expect(level.groundImage[4]).to.equal(10);
-    expect(level.groundImage[5]).to.equal(20);
-    expect(level.groundImage[6]).to.equal(30);
-    expect(level.groundImage[8]).to.equal(11);
-    expect(level.groundImage[9]).to.equal(21);
-    expect(level.groundImage[10]).to.equal(31);
-    expect(level.entrances[0]._opened).to.equal(false);
-    expect(obj.animation.firstFrameIndex).to.equal(0);
-    expect(obj.animation.isFinished).to.equal(false);
-    expect(manager.miniMap.deadCount).to.equal(0);
-    expect(skills.selectedSkill).to.equal(0);
-    expect(skills.cheatMode).to.equal(false);
-    expect(skills.skills[0]).to.equal(1);
-    expect(victory.releaseRate).to.equal(1);
-    expect(victory.leftCount).to.equal(1);
-    expect(victory.outCount).to.equal(0);
-    expect(victory.survivorCount).to.equal(0);
-    expect(victory.isFinalize).to.equal(false);
-    expect(timer.speedFactor).to.equal(1);
-    expect(timer.tickIndex).to.equal(0);
-    expect(game.finalGameState).to.equal(0);
-  });
-
-  it('applies trigger cooldown changes', function() {
-    const { history, game, timer, manager, triggerManager } = createHistoryFixture();
-    const owner = manager.lemmings[0];
-    const trigger = new Trigger(
-      TriggerTypes.TRAP,
-      1,
-      1,
-      2,
-      2,
-      5,
-      7,
-      owner
-    );
-    triggerManager.add(trigger);
-
-    scenario(history, timer).tick(0, {
-      ops: [['recordTriggerCooldown', trigger, 0, 5]]
-    });
-
-    const delta = history.getDelta(0);
-    history.applyDeltaForward(game, delta);
-    expect(trigger.disabledUntilTick).to.equal(5);
-    history.applyDeltaBackward(game, delta);
-    expect(trigger.disabledUntilTick).to.equal(0);
-  });
-
-  it('applies trigger add/remove deltas', function() {
-    const { history, game, timer, manager, triggerManager } = createHistoryFixture();
-    const owner = manager.lemmings[0];
-    const trigger = new Trigger(
-      TriggerTypes.TRAP,
-      2,
-      2,
-      3,
-      3,
-      0,
-      9,
-      owner
-    );
-
-    scenario(history, timer).tick(0, {
-      ops: [[
-        'recordTriggerAdd',
-        trigger,
-        {
-          type: trigger.type,
-          x1: trigger.x1,
-          y1: trigger.y1,
-          x2: trigger.x2,
-          y2: trigger.y2,
-          disableTicksCount: trigger.disableTicksCount,
-          soundIndex: trigger.soundIndex,
-          ownerId: owner.id,
-          disabledUntilTick: 0
-        }
-      ]]
-    });
-
-    const delta = history.getDelta(0);
-    history.applyDeltaForward(game, delta);
-    expect(triggerManager._triggers.size).to.equal(1);
-    const added = Array.from(triggerManager._triggers)[0];
-    expect(added.type).to.equal(trigger.type);
-    expect(added.x1).to.equal(trigger.x1);
-    expect(added.y1).to.equal(trigger.y1);
-    expect(added.x2).to.equal(trigger.x2);
-    expect(added.y2).to.equal(trigger.y2);
-
-    history.applyDeltaBackward(game, delta);
-    expect(triggerManager._triggers.size).to.equal(0);
-  });
-
-  it('handles invalid ticks and keyframe lookups', function() {
-    const history = new HistoryStore();
-    expect(history.getDelta(NaN)).to.equal(null);
-    expect(history.getKeyframeAtOrBefore(NaN)).to.equal(null);
-    expect(history.getKeyframeAtOrBefore(1)).to.equal(null);
-
-    seedHistory(history, { keyframes: [3] });
-    expect(history.getKeyframeAtOrBefore(2)).to.equal(null);
-    expect(history.getKeyframeAtOrBefore(3)).to.be.ok;
-  });
-
-  it('releases deltas while respecting pool limits', function() {
-    const history = new HistoryStore({ deltaPoolLimit: 1 });
-    const delta = history._allocDelta(0);
-    history._releaseDelta(delta);
-    expect(history._deltaPool).to.have.length(1);
-    history._releaseDelta(history._allocDelta(1));
-    expect(history._deltaPool).to.have.length(1);
-    history._releaseDelta(null);
-  });
-
-  it('attaches and detaches timer handlers', function() {
-    const history = new HistoryStore();
-    const calls = { onBefore: 0, onAfter: 0, offBefore: 0, offAfter: 0 };
-    const before = {
-      on(fn) { this.fn = fn; calls.onBefore += 1; },
-      off(fn) { if (fn === this.fn) calls.offBefore += 1; }
-    };
-    const after = {
-      on(fn) { this.fn = fn; calls.onAfter += 1; },
-      off(fn) { if (fn === this.fn) calls.offAfter += 1; }
-    };
-    const timer = {
-      tickIndex: 0,
-      onBeforeGameTick: before,
-      onGameTick: after
-    };
-    const game = {
-      level: { entrances: [] },
-      finalGameState: 0,
-      getGameTimer: () => timer,
-      getLemmingManager: () => ({ lemmings: [] }),
-      getGameSkills: () => null,
-      getVictoryCondition: () => null
-    };
-
-    history.attach(game, { captureBaseline: false });
-    expect(calls.onBefore).to.equal(1);
-    expect(calls.onAfter).to.equal(1);
-    history.detach();
-    expect(calls.offBefore).to.equal(1);
-    expect(calls.offAfter).to.equal(1);
-  });
-
-  it('inserts keyframe ticks in order and skips duplicates', function() {
-    const history = new HistoryStore();
-    history._insertKeyframeTick(2);
-    history._insertKeyframeTick(2);
-    history._insertKeyframeTick(1);
-    expect(history.keyframeTicks).to.eql([1, 2]);
-  });
-
-  it('compresses ground changes into spans', function() {
-    const history = new HistoryStore();
-    const changes = { indices: [5], spans: null };
-    history._compressGroundChanges(changes);
-    expect(changes.spans).to.equal(null);
-
-    changes.indices = [1, 2, 4, 5];
-    history._compressGroundChanges(changes);
-    expect(changes.spans.starts).to.eql([1, 4]);
-    expect(changes.spans.lengths).to.eql([2, 2]);
-    expect(changes.indices).to.have.length(0);
-  });
-
-  it('enforces history caps only when needed', function() {
-    const history = new HistoryStore({
-      enableHistoryCap: true,
-      historyCapTicks: 0
-    });
-    seedHistory(history, { deltas: [0] });
-    history._enforceHistoryCap();
-    expect(history.getDelta(0)).to.be.ok;
-
-    const capped = new HistoryStore({
-      enableHistoryCap: true,
-      historyCapTicks: 3
-    });
-    seedHistory(capped, { deltas: [0, 1, 2] });
-    capped._enforceHistoryCap();
-    expect(capped.getDelta(0)).to.be.ok;
-  });
-
-  it('reuses previous ground snapshots when not dirty', function() {
-    const { history, game } = createHistoryFixture();
-    history._groundDirty = false;
-    history._lastKeyframe = {
-      groundMask: new Uint8Array([9, 9]),
-      groundImage: new Uint8ClampedArray([1, 2, 3, 4])
-    };
-
-    const frame = history._captureKeyframe(game, 0);
-
-    expect(frame.groundMask).to.equal(history._lastKeyframe.groundMask);
-    expect(frame.groundImage).to.equal(history._lastKeyframe.groundImage);
-  });
-
-  it('applies ground changes with spans', function() {
-    const history = new HistoryStore();
-    const level = {
-      groundMask: { mask: new Uint8Array(4) },
-      groundImage: new Uint8ClampedArray(16)
-    };
-    const changes = {
-      spans: { starts: [0], lengths: [2] },
-      indices: [],
-      prevMask: [],
-      prevR: [],
-      prevG: [],
-      prevB: [],
-      nextMask: [1, 1],
-      nextR: [10, 20],
-      nextG: [30, 40],
-      nextB: [50, 60]
-    };
-
-    history._applyGroundChanges(level, changes, true);
-
-    expect(level.groundMask.mask[0]).to.equal(1);
-    expect(level.groundMask.mask[1]).to.equal(1);
-    expect(level.groundImage[0]).to.equal(10);
-    expect(level.groundImage[4]).to.equal(20);
-  });
-
-  it('applies minimap deaths forward and backward', function() {
-    const history = new HistoryStore();
-    const manager = {
-      miniMap: {
-        deadDots: new Uint8Array(0),
-        deadTTLs: new Uint8Array(0),
-        deadCount: 0
-      }
-    };
-    history._applyMinimapDeaths(manager, [{ x: 1, y: 2, ttl: 3, prevCount: 0 }], true);
-    expect(manager.miniMap.deadCount).to.equal(1);
-    history._applyMinimapDeaths(manager, [{ prevCount: 0 }], false);
-    expect(manager.miniMap.deadCount).to.equal(0);
-  });
-
-  it('handles trigger id lookups from cache', function() {
-    const history = new HistoryStore();
-    const trigger = new Trigger(TriggerTypes.TRAP, 1, 1, 2, 2);
-    trigger.__historyId = 5;
-    history._triggerById.set(5, trigger);
-    expect(history._findTriggerById({ _triggers: new Set() }, 5)).to.equal(trigger);
-    expect(history._findTriggerById({ _triggers: new Set() }, 0)).to.equal(null);
-  });
-
-  it('truncates history before a cutoff', function() {
-    const history = new HistoryStore({ keyframeInterval: 2 });
-    seedHistory(history, { deltas: [0, 1, 2], keyframes: [0, 2] });
-
-    history._truncateBefore(2);
-
-    expect(history.getDelta(0)).to.equal(null);
-    expect(history.getDelta(1)).to.equal(null);
-    expect(history.getDelta(2)).to.be.ok;
-    expect(history.minDeltaTick).to.equal(2);
-    expect(history.keyframes[0]).to.equal(undefined);
-    expect(history.keyframes[2]).to.be.ok;
-    expect(history.minKeyframeTick).to.equal(2);
-  });
-
-  it('reads and applies trigger state snapshots', function() {
-    const { history, game, manager, triggerManager, level } = createHistoryFixture();
-    const owner = manager.lemmings[0];
-    const staticTrigger = new Trigger(TriggerTypes.TRAP, 1, 1, 2, 2, 0, 5, null);
-    staticTrigger.disabledUntilTick = 5;
-    const dynamicTrigger = new Trigger(TriggerTypes.FRYING, 3, 3, 4, 4, 0, 7, owner);
-    const extraTrigger = new Trigger(TriggerTypes.KILL, 5, 5, 6, 6, 0, 8, owner);
-    level.triggers = [staticTrigger];
-    triggerManager._triggers.add(staticTrigger);
-    triggerManager._triggers.add(dynamicTrigger);
-    triggerManager._triggers.add(extraTrigger);
-
-    const state = history._readTriggerState(game);
-    expect(state.staticTriggers).to.have.length(1);
-    expect(state.dynamicTriggers).to.have.length(2);
-    expect(state.staticTriggers[0].disabledUntilTick).to.equal(5);
-
-    staticTrigger.disabledUntilTick = 0;
-    state.dynamicTriggers = state.dynamicTriggers.slice(0, 1);
-    history._applyTriggerState(game, state);
-
-    expect(staticTrigger.disabledUntilTick).to.equal(5);
-    const dynamic = Array.from(triggerManager._triggers)
-      .filter(tr => tr.owner === owner);
-    expect(dynamic).to.have.length(1);
-    expect(dynamic[0].type).to.equal(state.dynamicTriggers[0].type);
-  });
-
-  it('captures and restores object animation state', function() {
-    const { history, level } = createHistoryFixture();
-    const objA = { animation: { firstFrameIndex: 1, isFinished: false } };
-    const objB = { animation: { firstFrameIndex: 5, isFinished: true } };
-    level.objects = [objA, objB];
-
-    const state = history._readObjectState(level);
-    objA.animation.firstFrameIndex = 9;
-    objA.animation.isFinished = true;
-    objB.animation.firstFrameIndex = 11;
-    objB.animation.isFinished = false;
-
-    history._applyObjectState(level, state);
-
-    expect(objA.animation.firstFrameIndex).to.equal(1);
-    expect(objA.animation.isFinished).to.equal(false);
-    expect(objB.animation.firstFrameIndex).to.equal(5);
-    expect(objB.animation.isFinished).to.equal(true);
-  });
-
-  it('copies minimap state when reading', function() {
-    const { history } = createHistoryFixture();
-    const miniMap = {
-      deadDots: new Uint8Array([1, 2]),
-      deadTTLs: new Uint8Array([3]),
-      deadCount: 1
-    };
-    const state = history._readMinimapState(miniMap);
-    expect(Array.from(state.deadDots)).to.eql([1, 2]);
-    state.deadDots[0] = 9;
-    expect(miniMap.deadDots[0]).to.equal(1);
-  });
-
-  it('caps history and warns when configured', function() {
-    const history = new HistoryStore({
-      enableHistoryCap: true,
-      historyCapTicks: 2,
-      historyWarnTicks: 2
-    });
-    const warnings = [];
-    const restoreConsole = withConsoleStub({ warn: msg => warnings.push(msg) });
-    try {
-      seedHistory(history, { deltas: [0, 1] });
-      history._maybeWarnHistory();
-      expect(warnings).to.have.length(1);
-      history._maybeWarnHistory();
-      expect(warnings).to.have.length(1);
-
-      seedHistory(history, { deltas: [2] });
-      history._enforceHistoryCap();
-      expect(history.getDelta(0)).to.equal(null);
-      expect(history.getDelta(1)).to.be.ok;
-      expect(history.getDelta(2)).to.be.ok;
-    } finally {
-      restoreConsole();
-    }
-  });
-
-  it('returns action types from map or actions list', function() {
-    const history = new HistoryStore();
-    const actionA = { name: 'action-a' };
-    const actionB = { name: 'action-b' };
-    const manager = {
-      actions: [actionA, actionB],
-      actionTypeByAction: new Map([[actionA, 7]])
-    };
-
-    expect(history._getActionType(manager, actionA)).to.equal(7);
-    expect(history._getActionType(manager, actionB)).to.equal(1);
-    expect(history._getActionType(manager, null)).to.equal(-1);
-    expect(history._getActionType({ actions: [actionA] }, { name: 'missing' })).to.equal(-1);
-  });
-
-  it('removes lemmings when slots clear or the array shrinks', function() {
-    const timer = createStubTimer();
-    const walkAction = { name: 'walk' };
-    const makeLemming = (id) => ({
-      id,
-      x: id,
-      y: id + 1,
-      lookRight: true,
-      frameIndex: 0,
-      state: 0,
-      canClimb: false,
-      hasParachute: false,
-      removed: false,
-      disabled: false,
-      countdown: 0,
-      hasExploded: false,
-      lastTriggerType: null,
-      action: walkAction,
-      countdownAction: null
-    });
-    const lemmingA = makeLemming(0);
-    const lemmingB = makeLemming(1);
-    const manager = {
-      lemmings: [lemmingA, lemmingB],
-      activeLemmings: [lemmingA, lemmingB],
-      _activeDirty: false,
-      actions: [walkAction],
-      skillActions: [],
-      actionTypeByAction: new Map([[walkAction, 0]]),
-      selectedIndex: -1,
-      spawnTotal: 2,
-      releaseTickIndex: 0,
-      mmTickCounter: 0,
-      nextNukingLemmingsIndex: -1,
-      _nukeTargets: null
-    };
-    const game = {
-      level: { entrances: [] },
-      finalGameState: 0,
-      getLemmingManager: () => manager,
-      getGameTimer: () => timer,
-      getGameSkills: () => null,
-      getVictoryCondition: () => null
-    };
-    const history = new HistoryStore({ keyframeInterval: 5 });
-    history.attach(game, { captureBaseline: true });
-
-    scenario(history, timer).tick(0, {
-      mutate() {
-        manager.lemmings[0] = null;
-        manager.lemmings.length = 1;
-      }
-    });
-
-    const delta = history.getDelta(0);
-    expect(delta.lemRemoved).to.have.length(2);
-
-    history.applyDeltaBackward(game, delta);
-    expect(manager.lemmings[0]).to.be.ok;
-    expect(manager.lemmings[1]).to.be.ok;
-
-    history.applyDeltaForward(game, delta);
-    expect(manager.lemmings[0]).to.equal(null);
-    expect(manager.lemmings[1]).to.equal(null);
-  });
-
-  it('applies all lemming field changes', function() {
-    const timer = createStubTimer();
-    const walkAction = { name: 'walk' };
-    const bomberAction = { name: 'bomber' };
-    const skillActions = [];
-    skillActions[SkillTypes.BOMBER] = bomberAction;
-    const lemming = {
-      id: 0,
-      x: 5,
-      y: 6,
-      lookRight: true,
-      frameIndex: 0,
-      state: 1,
-      canClimb: false,
-      hasParachute: false,
-      removed: false,
-      disabled: false,
-      countdown: 0,
-      hasExploded: false,
-      lastTriggerType: 4,
-      action: walkAction,
-      countdownAction: null
-    };
-    const manager = {
-      lemmings: [lemming],
-      activeLemmings: [lemming],
-      _activeDirty: false,
-      actions: [walkAction],
-      skillActions,
-      actionTypeByAction: new Map([[walkAction, 0]]),
-      selectedIndex: -1,
-      spawnTotal: 1,
-      releaseTickIndex: 0,
-      mmTickCounter: 0,
-      nextNukingLemmingsIndex: -1,
-      _nukeTargets: null
-    };
-    const game = {
-      level: { entrances: [] },
-      finalGameState: 0,
-      getLemmingManager: () => manager,
-      getGameTimer: () => timer,
-      getGameSkills: () => null,
-      getVictoryCondition: () => null
-    };
-    const history = new HistoryStore({ keyframeInterval: 5 });
-    history.attach(game, { captureBaseline: true });
-
-    scenario(history, timer).tick(0, {
-      mutate() {
-        lemming.x = 11;
-        lemming.y = 22;
-        lemming.lookRight = false;
-        lemming.frameIndex = 3;
-        lemming.state = 2;
-        lemming.canClimb = true;
-        lemming.hasParachute = true;
-        lemming.removed = true;
-        lemming.disabled = true;
-        lemming.countdown = 5;
-        lemming.hasExploded = true;
-        lemming.lastTriggerType = null;
-        lemming.action = null;
-        lemming.countdownAction = bomberAction;
-      }
-    });
-
-    const delta = history.getDelta(0);
-    history.applyDeltaForward(game, delta);
-
-    expect(lemming.x).to.equal(11);
-    expect(lemming.y).to.equal(22);
-    expect(lemming.lookRight).to.equal(false);
-    expect(lemming.frameIndex).to.equal(3);
-    expect(lemming.state).to.equal(2);
-    expect(lemming.canClimb).to.equal(true);
-    expect(lemming.hasParachute).to.equal(true);
-    expect(lemming.removed).to.equal(true);
-    expect(lemming.disabled).to.equal(true);
-    expect(lemming.countdown).to.equal(5);
-    expect(lemming.hasExploded).to.equal(true);
-    expect(lemming.lastTriggerType).to.equal(null);
-    expect(lemming.action).to.equal(null);
-    expect(lemming.countdownAction).to.equal(bomberAction);
-
-    history.applyDeltaBackward(game, delta);
-    expect(lemming.x).to.equal(5);
-    expect(lemming.y).to.equal(6);
-    expect(lemming.lookRight).to.equal(true);
-    expect(lemming.frameIndex).to.equal(0);
-    expect(lemming.state).to.equal(1);
-    expect(lemming.canClimb).to.equal(false);
-    expect(lemming.hasParachute).to.equal(false);
-    expect(lemming.removed).to.equal(false);
-    expect(lemming.disabled).to.equal(false);
-    expect(lemming.countdown).to.equal(0);
-    expect(lemming.hasExploded).to.equal(false);
-    expect(lemming.lastTriggerType).to.equal(4);
-    expect(lemming.action).to.equal(walkAction);
-    expect(lemming.countdownAction).to.equal(null);
-  });
-
-  it('applies lemming manager nuke target changes', function() {
-    const timer = createStubTimer();
-    const walkAction = { name: 'walk' };
-    const makeLemming = (id) => ({
-      id,
-      x: id,
-      y: id + 1,
-      lookRight: true,
-      frameIndex: 0,
-      state: 0,
-      canClimb: false,
-      hasParachute: false,
-      removed: false,
-      disabled: false,
-      countdown: 0,
-      hasExploded: false,
-      lastTriggerType: null,
-      action: walkAction,
-      countdownAction: null
-    });
-    const lemmingA = makeLemming(0);
-    const lemmingB = makeLemming(1);
-    const manager = {
-      lemmings: [lemmingA, lemmingB],
-      activeLemmings: [lemmingA, lemmingB],
-      _activeDirty: false,
-      actions: [walkAction],
-      skillActions: [],
-      actionTypeByAction: new Map([[walkAction, 0]]),
-      selectedIndex: -1,
-      spawnTotal: 2,
-      releaseTickIndex: 0,
-      mmTickCounter: 0,
-      nextNukingLemmingsIndex: -1,
-      _nukeTargets: [lemmingA]
-    };
-    const game = {
-      level: { entrances: [] },
-      finalGameState: 0,
-      getLemmingManager: () => manager,
-      getGameTimer: () => timer,
-      getGameSkills: () => null,
-      getVictoryCondition: () => null
-    };
-    const history = new HistoryStore({ keyframeInterval: 5 });
-    history.attach(game, { captureBaseline: true });
-
-    scenario(history, timer).tick(0, {
-      mutate() {
-        manager.selectedIndex = 1;
-        manager.nextNukingLemmingsIndex = 2;
-        manager._nukeTargets = [lemmingB, null];
-      }
-    });
-
-    const delta = history.getDelta(0);
-    history.applyDeltaForward(game, delta);
-    expect(manager.selectedIndex).to.equal(1);
-    expect(manager.nextNukingLemmingsIndex).to.equal(2);
-    expect(manager._nukeTargets).to.eql([lemmingB]);
-
-    history.applyDeltaBackward(game, delta);
-    expect(manager.selectedIndex).to.equal(-1);
-    expect(manager.nextNukingLemmingsIndex).to.equal(-1);
-    expect(manager._nukeTargets).to.eql([lemmingA]);
-  });
-
-  it('resets entrance tracking when entrance count changes', function() {
-    const timer = createStubTimer();
-    const manager = {
-      lemmings: [],
-      activeLemmings: [],
-      _activeDirty: false,
-      actions: [],
-      skillActions: [],
-      actionTypeByAction: new Map(),
-      selectedIndex: -1,
-      spawnTotal: 0,
-      releaseTickIndex: 0,
-      mmTickCounter: 0,
-      nextNukingLemmingsIndex: -1,
-      _nukeTargets: null
-    };
-    const level = { entrances: [{ _opened: false }] };
-    const game = {
-      level,
-      finalGameState: 0,
-      getLemmingManager: () => manager,
-      getGameTimer: () => timer,
-      getGameSkills: () => null,
-      getVictoryCondition: () => null
-    };
-    const history = new HistoryStore({ keyframeInterval: 5 });
-    history.attach(game, { captureBaseline: true });
-
-    scenario(history, timer).tick(0, {
-      mutate() {
-        level.entrances.push({ _opened: true });
-      }
-    });
-
-    const delta = history.getDelta(0);
-    expect(delta.entranceChanges.indices).to.have.length(0);
-    expect(history._entranceOpened).to.have.length(2);
-  });
-
-  it('removes triggers by resolving ids from trigger sets', function() {
-    const history = new HistoryStore();
-    const owner = { id: 0 };
-    const trigger = new Trigger(TriggerTypes.TRAP, 1, 1, 2, 2, 0, 0, owner);
-    trigger.__historyId = 7;
-    const triggerManager = {
-      _triggers: new Set([trigger]),
-      add(trig) { this._triggers.add(trig); },
-      removeByOwner(ownerRef) {
-        for (const trig of Array.from(this._triggers)) {
-          if (trig.owner === ownerRef) this._triggers.delete(trig);
-        }
-      }
-    };
-    const game = {
-      triggerManager,
-      getLemmingManager: () => ({ getLemming: () => owner })
-    };
-    const delta = {
-      triggerAdd: [],
-      triggerRemove: [{ id: 7 }]
-    };
-
-    history._applyTriggerChanges(game, delta, true);
-
-    expect(triggerManager._triggers.size).to.equal(0);
-    expect(history._triggerById.get(7)).to.equal(trigger);
-  });
-
-  it('applies object changes by resolving ids from level objects', function() {
-    const history = new HistoryStore();
-    const obj = { animation: { firstFrameIndex: 0, isFinished: false } };
-    const level = { objects: [obj] };
-    const changes = {
-      ids: [1],
-      prevFirst: [0],
-      prevFinished: [0],
-      nextFirst: [5],
-      nextFinished: [1]
-    };
-
-    history._applyObjectChanges(level, changes, true);
-
-    expect(obj.animation.firstFrameIndex).to.equal(5);
-    expect(obj.animation.isFinished).to.equal(true);
-  });
-
-  it('handles non-array skill lists', function() {
-    const history = new HistoryStore();
-    const skills = history._readSkills({ selectedSkill: 1, cheatMode: 1, skills: null });
-    expect(skills.skills).to.eql([]);
-    expect(skills.cheatMode).to.equal(true);
-    expect(history._skillsEqual(skills, { selectedSkill: 1, cheatMode: true, skills: [] })).to.equal(true);
-    expect(history._skillsEqual(skills, { selectedSkill: 2, cheatMode: true, skills: [] })).to.equal(false);
-  });
-
-  it('start no-ops without a game and skips existing keyframes', function() {
-    const history = new HistoryStore();
-    history.start();
-    expect(history._recording).to.equal(false);
-
-    const timer = createStubTimer();
-    const game = {
-      level: { entrances: [] },
-      finalGameState: 0,
-      getLemmingManager: () => ({ lemmings: [] }),
-      getGameTimer: () => timer,
-      getGameSkills: () => null,
-      getVictoryCondition: () => null
-    };
-    const history2 = new HistoryStore({ keyframeInterval: 5 });
-    history2.attach(game, { captureBaseline: true });
-    const count = history2.keyframeCount;
-    history2.timer = null;
-    history2.start();
-    expect(history2.keyframeCount).to.equal(count);
-  });
-
-  it('captures keyframes without ground data and handles null minimaps', function() {
-    const history = new HistoryStore();
-    const game = {
-      level: { entrances: [] },
-      finalGameState: 0,
-      getLemmingManager: () => ({ lemmings: [], miniMap: null }),
-      getGameTimer: () => createStubTimer(),
-      getGameSkills: () => null,
-      getVictoryCondition: () => null
-    };
-
-    const frame = history._captureKeyframe(game, 0);
-
-    expect(frame.groundMask).to.equal(null);
-    expect(frame.groundImage).to.equal(null);
-    expect(history._readMinimapState(null)).to.equal(null);
-  });
-
-  it('records lemming adds and ignores unknown change fields', function() {
-    const { history, timer, manager, walkAction } = createHistoryFixture();
-    const newLem = {
-      id: 1,
-      x: 10,
-      y: 11,
-      lookRight: true,
-      frameIndex: 0,
-      state: 0,
-      canClimb: false,
-      hasParachute: false,
-      removed: false,
-      disabled: false,
-      countdown: 0,
-      hasExploded: false,
-      lastTriggerType: null,
-      action: walkAction,
-      countdownAction: null
-    };
-
-    scenario(history, timer).tick(0, {
-      mutate() {
-        manager.lemmings.push(newLem);
-      }
-    });
-
-    const delta = history.getDelta(0);
-    expect(delta.lemAdded).to.have.length(1);
-
-    history._applyLemmingChanges(manager, {
-      ids: [0],
-      fields: [99],
-      prev: [0],
-      next: [1]
-    }, true);
-    expect(manager.lemmings[0].x).to.equal(5);
-  });
-
-  it('skips delta application and ground changes when data is missing', function() {
-    const history = new HistoryStore();
-    history._applyDelta(null, null, true);
-
-    const level = { groundMask: null, groundImage: null };
-    history._applyGroundChanges(level, {
-      indices: [0],
-      prevMask: [0],
-      prevR: [0],
-      prevG: [0],
-      prevB: [0],
-      nextMask: [1],
-      nextR: [1],
-      nextG: [1],
-      nextB: [1]
-    }, true);
-    expect(level.groundImage).to.equal(null);
-  });
-
-  it('adds lemmings with constructors and skips invalid entries', function() {
-    const history = new HistoryStore();
-    const created = [];
-    function LemCtor(x, y, id) {
-      this.id = id;
-      this.x = x;
-      this.y = y;
-      created.push(this);
-    }
-    const manager = { lemmings: null, actions: [], skillActions: [], _lemmingCtor: LemCtor };
-    const snap = {
-      id: 0,
-      x: 1,
-      y: 2,
-      lookRight: 1,
-      frameIndex: 0,
-      state: 0,
-      canClimb: 0,
-      hasParachute: 0,
-      removed: 0,
-      disabled: 0,
-      countdown: 0,
-      hasExploded: 0,
-      lastTriggerType: -1,
-      actionType: -1,
-      countdownActive: 0
-    };
-
-    history._applyLemmingAdds(manager, [null, { id: NaN }, snap]);
-
-    expect(created).to.have.length(1);
-    expect(manager.lemmings[0]).to.be.instanceOf(LemCtor);
-  });
-
-  it('handles trigger changes with missing owners and cooldown ids', function() {
-    const history = new HistoryStore();
-    const trigger = new Trigger(TriggerTypes.TRAP, 0, 0, 1, 1);
-    trigger.__historyId = 3;
-    trigger.owner = null;
-    const triggerManager = {
-      _triggers: new Set([trigger]),
-      add(trig) { this._triggers.add(trig); },
-      removeByOwner(owner) {
-        for (const entry of Array.from(this._triggers)) {
-          if (entry.owner === owner) this._triggers.delete(entry);
-        }
-      }
-    };
-    const game = { triggerManager, getLemmingManager: () => ({ getLemming: () => null }) };
-    const delta = {
-      triggerAdd: [],
-      triggerRemove: [{ id: 3 }],
-      triggerCooldownChanges: { ids: [9], prev: [0], next: [1] }
-    };
-
-    history._applyTriggerChanges(game, delta, true);
-
-    expect(triggerManager._triggers.size).to.equal(1);
-  });
-
-  it('skips ownerless dynamic triggers and ignores empty dynamic state', function() {
-    const history = new HistoryStore();
-    const ownerless = new Trigger(TriggerTypes.TRAP, 1, 1, 2, 2, 0, 0, null);
-    const staticTrigger = new Trigger(TriggerTypes.FRYING, 2, 2, 3, 3, 0, 0, null);
-    staticTrigger.disabledUntilTick = 2;
-    const level = { triggers: [staticTrigger] };
-    const triggerManager = {
-      _triggers: new Set([staticTrigger, ownerless]),
-      add(trig) { this._triggers.add(trig); },
-      removeByOwner(owner) {
-        for (const entry of Array.from(this._triggers)) {
-          if (entry.owner === owner) this._triggers.delete(entry);
-        }
-      }
-    };
-    const game = {
-      level,
-      triggerManager,
-      getLemmingManager: () => ({ getLemming: () => null })
-    };
-
-    const state = history._readTriggerState(game);
-    expect(state.dynamicTriggers).to.have.length(0);
-    state.staticTriggers[0].disabledUntilTick = 5;
-    state.dynamicTriggers = [];
-
-    history._applyTriggerState(game, state);
-
-    expect(staticTrigger.disabledUntilTick).to.equal(5);
-    expect(triggerManager._triggers.has(ownerless)).to.equal(true);
-  });
-
-  it('skips objects without animations in state helpers', function() {
-    const history = new HistoryStore();
-    const objWithAnim = { animation: { firstFrameIndex: 2, isFinished: false } };
-    const objNoAnim = {};
-    const level = { objects: [objWithAnim, objNoAnim] };
-    const state = history._readObjectState(level);
-    expect(state).to.have.length(1);
-
-    history._applyObjectState(level, [{ id: 999, firstFrameIndex: 9, isFinished: true }]);
-    expect(objWithAnim.animation.firstFrameIndex).to.equal(2);
-  });
-
-  it('applies game state even when other scalars are missing', function() {
-    const history = new HistoryStore();
-    const game = {
-      finalGameState: 0,
-      getGameSkills: () => null,
-      getVictoryCondition: () => null,
-      getGameTimer: () => null
-    };
-    const delta = {
-      skillsChanges: { prev: null, next: { selectedSkill: 1, cheatMode: false, skills: [] } },
-      victoryChanges: { prev: null, next: { releaseRate: 1, minReleaseRate: 1, leftCount: 0, outCount: 0, survivorCount: 0, isFinalize: false } },
-      timerChanges: { prev: null, next: { speedFactor: 1, frameTime: 60, tickIndex: 2 } },
-      gameChanges: { prev: { finalGameState: 0 }, next: { finalGameState: 4 } }
-    };
-
-    history._applyScalarChanges(game, delta, true);
-
-    expect(game.finalGameState).to.equal(4);
-  });
-
-  it('handles early returns and null helpers', function() {
-    const history = new HistoryStore({ deltaPoolLimit: 0 });
-    const delta = history._allocDelta(0);
-    history._releaseDelta(delta);
-    expect(history._deltaPool).to.have.length(0);
-
-    history.attach(null);
-    history._bindTimer();
-    history.beginTick(0);
-    history.endTick();
-    history.captureBaseline(null);
-
-    runHistoryOps(history, [
-      ['recordSoundEvent', { type: 'sfx' }],
-      ['recordGroundChange', 0, 0, 0, 0, 0, 1, 1, 1, 1],
-      ['recordEntranceChange', 0, false, true],
-      ['recordTriggerCooldown', null, 0, 1],
-      ['recordTriggerAdd', null, {}],
-      ['recordTriggerRemove', null, {}],
-      ['recordObjectAnimation', null, { firstFrameIndex: 0, isFinished: false }, { firstFrameIndex: 1, isFinished: true }],
-      ['recordMinimapDeath', { x: 1 }]
-    ]);
-
-    expect(history._ensureTriggerId(null)).to.equal(0);
-    expect(history._ensureObjectId(null)).to.equal(0);
-  });
-
-  it('records delta entries for sound, entrances, and objects', function() {
-    const { history, timer, level } = createHistoryFixture();
-    const obj = { animation: { firstFrameIndex: 0, isFinished: false } };
-    level.objects = [obj];
-
-    scenario(history, timer).tick(0, {
-      ops: [
-        ['recordSoundEvent', { type: 'step' }],
-        ['recordEntranceChange', 0, false, true],
-        ['recordObjectAnimation', obj, { firstFrameIndex: 0, isFinished: false }, { firstFrameIndex: 2, isFinished: true }],
-        ['recordMinimapDeath', { x: 2, y: 3, ttl: 4, prevCount: 0 }]
-      ]
-    });
-
-    const delta = history.getDelta(0);
-    expect(delta.soundEvents).to.have.length(1);
-    expect(delta.entranceChanges.prev[0]).to.equal(0);
-    expect(delta.entranceChanges.next[0]).to.equal(1);
-    expect(delta.objectAnimChanges.prevFinished[0]).to.equal(0);
-    expect(delta.objectAnimChanges.nextFinished[0]).to.equal(1);
-    expect(delta.minimapDeaths).to.have.length(1);
-  });
-
-  it('truncates deltas and keyframes when removing all history', function() {
-    const history = new HistoryStore({ keyframeInterval: 2 });
-    seedHistory(history, { deltas: [0, 2], keyframes: [0, 2] });
-
-    history._truncateDeltasAfter(-1);
-    expect(history.minDeltaTick).to.equal(null);
-    expect(history.maxDeltaTick).to.equal(null);
-
-    seedHistory(history, { keyframes: [1] });
-    history._truncateKeyframesAfter(0);
-    expect(history.keyframeTicks).to.have.length(1);
-    expect(history.keyframeTicks[0]).to.equal(0);
-
-    seedHistory(history, { deltas: [0] });
-    history._truncateBefore(5);
-    expect(history.minDeltaTick).to.equal(null);
-  });
-
-  it('applies keyframes across game subsystems', function() {
-    const history = new HistoryStore();
-    const walkAction = { name: 'walk' };
-    const bomberAction = { name: 'bomber' };
-    const created = [];
-    function LemCtor(x, y, id) {
-      this.id = id;
-      this.x = x;
-      this.y = y;
-      created.push(this);
-    }
-    const skillActions = [];
-    skillActions[SkillTypes.BOMBER] = bomberAction;
-    const manager = {
-      lemmings: [],
-      actions: [walkAction],
-      skillActions,
-      _lemmingCtor: LemCtor,
-      activeLemmings: [],
-      _activeDirty: true,
-      actionTypeByAction: new Map([[walkAction, 0]]),
-      miniMap: { deadDots: new Uint8Array([1, 2]), deadTTLs: new Uint8Array([3]), deadCount: 1 },
-      getLemming: id => manager.lemmings[id] ?? null
-    };
-    const staticTrigger = new Trigger(TriggerTypes.TRAP, 1, 1, 2, 2, 0, 0, null);
-    const existingOwner = { id: 0 };
-    const existingTrigger = new Trigger(TriggerTypes.FRYING, 2, 2, 3, 3, 0, 0, existingOwner);
-    const level = {
-      entrances: [{ _opened: false }],
-      triggers: [staticTrigger],
-      objects: [{ animation: { firstFrameIndex: 0, isFinished: false } }],
-      groundMask: { mask: new Uint8Array(4) },
-      groundImage: new Uint8ClampedArray(16)
-    };
-    const triggerManager = {
-      _triggers: new Set([staticTrigger, existingTrigger]),
-      add(trig) { this._triggers.add(trig); },
-      removeByOwner(owner) {
-        for (const trig of Array.from(this._triggers)) {
-          if (trig.owner === owner) this._triggers.delete(trig);
-        }
-      }
-    };
-    const victory = {
-      releaseRate: 1,
-      minReleaseRate: 1,
-      leftCount: 1,
-      outCount: 0,
-      survivorCount: 0,
-      isFinalize: false
-    };
-    const skills = { selectedSkill: 0, cheatMode: false, skills: [1] };
-    const timer = { speedFactor: 1, tickIndex: 0, frameTime: 60 };
-    const game = {
-      level,
-      triggerManager,
-      finalGameState: 0,
-      getLemmingManager: () => manager,
-      getGameSkills: () => skills,
-      getVictoryCondition: () => victory,
-      getGameTimer: () => timer
-    };
-    const lemmingState = {
-      present: new Uint8Array([1, 0]),
-      x: new Int32Array([10, 0]),
-      y: new Int32Array([20, 0]),
-      lookRight: new Uint8Array([1, 0]),
-      frameIndex: new Int32Array([2, 0]),
-      state: new Int32Array([3, 0]),
-      canClimb: new Uint8Array([1, 0]),
-      hasParachute: new Uint8Array([0, 0]),
-      removed: new Uint8Array([0, 0]),
-      disabled: new Uint8Array([0, 0]),
-      countdown: new Int32Array([5, 0]),
-      hasExploded: new Uint8Array([0, 0]),
-      lastTriggerType: new Int32Array([TriggerTypes.TRAP, -1]),
-      actionType: new Int32Array([0, -1]),
-      countdownActive: new Uint8Array([1, 0])
-    };
-    const keyframe = {
-      tickIndex: 10,
-      lemmingState,
-      lemmingManagerState: {
-        selectedIndex: 1,
-        spawnTotal: 2,
-        releaseTickIndex: 3,
-        mmTickCounter: 4,
-        nextNukingLemmingsIndex: 5,
-        nukeTargets: [0, 99]
-      },
-      entranceOpened: new Uint8Array([1]),
-      triggerState: {
-        staticTriggers: [{ id: 100, disabledUntilTick: 7 }],
-        dynamicTriggers: [{
-          id: 200,
-          ownerId: 0,
-          type: TriggerTypes.KILL,
-          x1: 0,
-          y1: 0,
-          x2: 1,
-          y2: 1,
-          disableTicksCount: 0,
-          soundIndex: 2,
-          disabledUntilTick: 4
-        }]
-      },
-      objectState: [{
-        id: history._ensureObjectId(level.objects[0]),
-        firstFrameIndex: 5,
-        isFinished: true
-      }],
-      minimapState: { deadDots: new Uint8Array([9, 10]), deadTTLs: new Uint8Array([5]), deadCount: 1 },
-      groundMask: new Uint8Array([1, 1, 0, 0]),
-      groundImage: new Uint8ClampedArray(16).fill(2),
-      victory: { releaseRate: 2, minReleaseRate: 1, leftCount: 0, outCount: 1, survivorCount: 1, isFinalize: true },
-      skills: { selectedSkill: 1, cheatMode: true, skills: [9] },
-      timer: { speedFactor: 2, tickIndex: 5 },
-      gameState: { finalGameState: 9 }
-    };
-
-    history.applyKeyframe(game, keyframe);
-
-    expect(created).to.have.length(1);
-    expect(manager.lemmings[0]).to.be.ok;
-    expect(manager.lemmings[1]).to.equal(null);
-    expect(manager.activeLemmings).to.have.length(1);
-    expect(manager.activeLemmings[0].action).to.equal(walkAction);
-    expect(manager.activeLemmings[0].countdownAction).to.equal(bomberAction);
-    expect(manager.selectedIndex).to.equal(1);
-    expect(manager._nukeTargets).to.eql([manager.lemmings[0]]);
-    expect(level.entrances[0]._opened).to.equal(true);
-    expect(level.objects[0].animation.firstFrameIndex).to.equal(5);
-    expect(manager.miniMap.deadDots[0]).to.equal(9);
-    expect(level.groundMask.mask[0]).to.equal(1);
-    expect(victory.releaseRate).to.equal(2);
-    expect(skills.selectedSkill).to.equal(1);
-    expect(timer.speedFactor).to.equal(2);
-    expect(game.finalGameState).to.equal(9);
-  });
-
-  it('applies ground changes without spans and scans triggers by id', function() {
-    const history = new HistoryStore();
-    const level = {
-      groundMask: { mask: new Uint8Array(4) },
-      groundImage: new Uint8ClampedArray(16)
-    };
-    const changes = {
-      spans: null,
-      indices: [2],
-      prevMask: [0],
-      prevR: [0],
-      prevG: [0],
-      prevB: [0],
-      nextMask: [1],
-      nextR: [10],
-      nextG: [20],
-      nextB: [30]
-    };
-
-    history._applyGroundChanges(level, changes, true);
-    expect(level.groundMask.mask[2]).to.equal(1);
-    expect(level.groundImage[8]).to.equal(10);
-
-    const trigger = new Trigger(TriggerTypes.TRAP, 1, 1, 2, 2);
-    trigger.__historyId = 9;
-    const triggerManager = { _triggers: new Set([trigger]) };
-    const found = history._findTriggerById(triggerManager, 9);
-    expect(found).to.equal(trigger);
-  });
-
-  it('returns null from readers with missing inputs', function() {
-    const history = new HistoryStore();
-    expect(history._readSkills(null)).to.equal(null);
-    expect(history._readVictory(null)).to.equal(null);
-    expect(history._readTimer(null)).to.equal(null);
-    expect(history._readGameState(null)).to.equal(null);
-    expect(history._skillsEqual(null, null)).to.equal(false);
-    expect(history._victoryEqual(null, null)).to.equal(false);
-    expect(history._timerEqual(null, null)).to.equal(false);
-    expect(history._gameStateEqual(null, null)).to.equal(false);
-  });
-
-  it('skips ownerless trigger entries when reading state', function() {
-    const history = new HistoryStore();
-    const level = { triggers: [null] };
-    const triggerManager = { _triggers: new Set([new Trigger(TriggerTypes.TRAP, 1, 1, 2, 2)]) };
-    const game = { level, triggerManager };
-    const state = history._readTriggerState(game);
-    expect(state.staticTriggers).to.have.length(0);
-    expect(state.dynamicTriggers).to.have.length(0);
-  });
-
-  it('exposes lemming helpers for snapshots and cloning', function() {
-    const state = __test__.createLemmingState(1);
-    state.present[0] = 1;
-    state.x[0] = 7;
-    state.y[0] = 8;
-    state.lookRight[0] = 1;
-    state.countdownActive[0] = 1;
-
-    const cloneDefault = __test__.cloneLemmingState(state);
-    const cloneShort = __test__.cloneLemmingState(state, 0);
-    expect(cloneDefault.present.length).to.equal(1);
-    expect(cloneShort.present.length).to.equal(0);
-
-    const grown = __test__.ensureLemmingCapacity(state, 2);
-    const same = __test__.ensureLemmingCapacity(grown, 1);
-    expect(grown.present.length).to.be.at.least(2);
-    expect(same).to.equal(grown);
-
-    const lem = {
-      id: 1,
-      x: 2,
-      y: 3,
-      lookRight: false,
-      frameIndex: 4,
-      state: null,
-      canClimb: true,
-      hasParachute: false,
-      removed: false,
-      disabled: true,
-      countdown: null,
-      hasExploded: true,
-      lastTriggerType: NaN
-    };
-    const snap = __test__.snapshotLemming(lem, NaN, false);
-    expect(snap.lastTriggerType).to.equal(-1);
-    expect(snap.actionType).to.equal(-1);
-    expect(snap.countdownActive).to.equal(0);
-
-    const walk = { name: 'walk' };
-    const bomb = { name: 'bomber' };
-    const target = {};
-    __test__.applyLemmingSnapshot(
-      target,
-      { ...snap, lastTriggerType: 3, countdownActive: 1 },
-      walk,
-      bomb
-    );
-    expect(target.lastTriggerType).to.equal(3);
-    expect(target.action).to.equal(walk);
-    expect(target.countdownAction).to.equal(bomb);
-
-    __test__.applyLemmingSnapshot(
-      target,
-      { ...snap, lastTriggerType: -1, countdownActive: 0 },
-      null,
-      bomb
-    );
-    expect(target.lastTriggerType).to.equal(null);
-    expect(target.countdownAction).to.equal(null);
-  });
-
-  it('reports history stats and keyframe lookups', function() {
-    const history = new HistoryStore();
-    expect(history.getKeyframe(NaN)).to.equal(null);
-    expect(history.getHistoryStats().spanTicks).to.equal(0);
-
-    seedHistory(history, { deltas: [0, 2], keyframes: [2] });
-    expect(history.getKeyframe(2)).to.be.ok;
-    expect(history.getKeyframe(4)).to.equal(null);
-
-    const stats = history.getHistoryStats();
-    expect(stats.spanTicks).to.equal(3);
-    expect(stats.deltaCount).to.equal(2);
-
-    seedHistory(history, { keyframes: [5] });
-    const found = history.getKeyframeAtOrBefore(4);
-    expect(found.tickIndex).to.equal(2);
-  });
-
-  it('pauses and resumes recording with baseline updates', function() {
-    const { history } = createHistoryFixture();
-    history.beginTick(0);
-    history.pause();
-    expect(history._recording).to.equal(false);
-    expect(history._currentDelta).to.equal(null);
-
-    history.resume();
-    expect(history._recording).to.equal(true);
-    expect(history._groundDirty).to.equal(true);
-  });
-
-  it('truncates deltas and keyframes across gaps', function() {
-    const history = new HistoryStore({ keyframeInterval: 2 });
-    seedHistory(history, { deltas: [0, 2], keyframes: [0, 2] });
-
-    history._truncateDeltasAfter(1);
-    expect(history.maxDeltaTick).to.equal(0);
-    history._truncateDeltasAfter(-1);
-    expect(history.minDeltaTick).to.equal(null);
-
-    history._truncateKeyframesAfter(-1);
-    expect(history.keyframeTicks).to.have.length(0);
-    expect(history.minKeyframeTick).to.equal(null);
-  });
-
-  it('truncates before gaps and clears keyframes', function() {
-    const history = new HistoryStore({ keyframeInterval: 2 });
-    seedHistory(history, { deltas: [0, 2], keyframes: [0, 1] });
-
-    history._truncateBefore(1);
-    expect(history.minDeltaTick).to.equal(2);
-
-    history._truncateBefore(5);
-    expect(history.minDeltaTick).to.equal(null);
-
-    const history2 = new HistoryStore({ keyframeInterval: 2 });
-    seedHistory(history2, { deltas: [0], keyframes: [0, 1] });
-    history2._truncateBefore(2);
-    expect(history2.keyframeTicks).to.have.length(0);
-  });
-
-  it('warns and caps history spans', function() {
-    const history = new HistoryStore({
-      enableHistoryCap: true,
-      historyCapTicks: 2,
-      historyWarnTicks: 2
-    });
-    seedHistory(history, { deltas: [0, 1, 2, 3], keyframes: [1] });
-
-    let warned = 0;
-    const restoreConsole = withConsoleStub({ warn: () => { warned += 1; } });
-    try {
-      history._maybeWarnHistory();
-      history._maybeWarnHistory();
-    } finally {
-      restoreConsole();
-    }
-    expect(warned).to.equal(1);
-
-    history._enforceHistoryCap();
-    expect(history.minDeltaTick).to.equal(1);
-  });
-
-  it('skips history caps when a keyframe is before the minimum tick', function() {
-    const history = new HistoryStore({
-      enableHistoryCap: true,
-      historyCapTicks: 2
-    });
-    seedHistory(history, { deltas: [5, 6, 7], keyframes: [0] });
-
-    history._enforceHistoryCap();
-    expect(history.minDeltaTick).to.equal(5);
-  });
-
-  it('captures keyframes with ground data when dirty', function() {
-    const { history, game } = createHistoryFixture();
-    history._groundDirty = true;
-    game.level.groundMask.mask[0] = 1;
-    game.level.groundImage[0] = 5;
-
-    const frame = history._captureKeyframe(game, 0);
-    expect(frame.groundMask[0]).to.equal(1);
-    expect(frame.groundImage[0]).to.equal(5);
-  });
-
-  it('diffs lemming adds, removals, and changes', function() {
-    const history = new HistoryStore();
-    const walkAction = { name: 'walk' };
-    const manager = {
-      lemmings: [
-        {
-          id: 0,
-          x: 1,
-          y: 2,
-          lookRight: true,
-          frameIndex: 0,
-          state: 1,
-          canClimb: false,
-          hasParachute: false,
-          removed: false,
-          disabled: false,
-          countdown: 0,
-          hasExploded: false,
-          lastTriggerType: null,
-          action: walkAction,
-          countdownAction: null
-        },
-        {
-          id: 1,
-          x: 3,
-          y: 4,
-          lookRight: false,
-          frameIndex: 0,
-          state: 1,
-          canClimb: false,
-          hasParachute: false,
-          removed: false,
-          disabled: false,
-          countdown: 0,
-          hasExploded: false,
-          lastTriggerType: null,
-          action: walkAction,
-          countdownAction: null
-        }
-      ],
-      actions: [walkAction],
-      skillActions: [],
-      actionTypeByAction: new Map()
-    };
-
-    history._captureLemmingState(manager);
-    const delta = history._allocDelta(0);
-
-    manager.lemmings[0] = null;
-    manager.lemmings[1].x = 10;
-    manager.lemmings.push({
-      id: 2,
-      x: 5,
-      y: 6,
-      lookRight: true,
-      frameIndex: 0,
-      state: 1,
-      canClimb: false,
-      hasParachute: false,
-      removed: false,
-      disabled: false,
-      countdown: 0,
-      hasExploded: false,
-      lastTriggerType: 2,
-      action: walkAction,
-      countdownAction: null
-    });
-
-    history._diffLemmings(manager, delta);
-    expect(delta.lemRemoved).to.have.length(1);
-    expect(delta.lemAdded).to.have.length(1);
-    expect(delta.lemChanges.ids).to.include(1);
-  });
-
-  it('removes lemmings beyond the current length', function() {
-    const history = new HistoryStore();
-    const walkAction = { name: 'walk' };
-    const manager = {
-      lemmings: [
-        { id: 0, x: 1, y: 2, lookRight: true, frameIndex: 0, state: 1, canClimb: false, hasParachute: false, removed: false, disabled: false, countdown: 0, hasExploded: false, lastTriggerType: null, action: walkAction, countdownAction: null },
-        { id: 1, x: 3, y: 4, lookRight: false, frameIndex: 0, state: 1, canClimb: false, hasParachute: false, removed: false, disabled: false, countdown: 0, hasExploded: false, lastTriggerType: null, action: walkAction, countdownAction: null },
-        { id: 2, x: 5, y: 6, lookRight: true, frameIndex: 0, state: 1, canClimb: false, hasParachute: false, removed: false, disabled: false, countdown: 0, hasExploded: false, lastTriggerType: null, action: walkAction, countdownAction: null }
-      ],
-      actions: [walkAction],
-      skillActions: [],
-      actionTypeByAction: new Map()
-    };
-
-    history._captureLemmingState(manager);
-    manager.lemmings.length = 1;
-    const delta = history._allocDelta(0);
-    history._diffLemmings(manager, delta);
-    expect(delta.lemRemoved).to.have.length(2);
-  });
-
-  it('skips lemming diffs when values match', function() {
-    const history = new HistoryStore();
-    const delta = history._allocDelta(0);
-    const store = new Int32Array(1);
-    history._diffLemmingField(delta, 0, 0, 1, 1, store);
-    expect(delta.lemChanges.ids).to.have.length(0);
-  });
-
-  it('compares lemming manager state including nuke targets', function() {
-    const history = new HistoryStore();
-    const a = {
-      selectedIndex: 0,
-      spawnTotal: 1,
-      releaseTickIndex: 2,
-      mmTickCounter: 3,
-      nextNukingLemmingsIndex: 4,
-      nukeTargets: [1, 2]
-    };
-    const b = { ...a, nukeTargets: [1, 3] };
-    const c = { ...a, nukeTargets: [1, 2] };
-    expect(history._lemmingManagerEqual(a, b)).to.equal(false);
-    expect(history._lemmingManagerEqual(a, c)).to.equal(true);
-  });
-
-  it('diffs entrance and scalar changes', function() {
-    const history = new HistoryStore();
-    const skills = { selectedSkill: 0, cheatMode: false, skills: [1] };
-    const victory = {
-      releaseRate: 1,
-      minReleaseRate: 1,
-      leftCount: 1,
-      outCount: 0,
-      survivorCount: 0,
-      isFinalize: false
-    };
-    const timer = { speedFactor: 1, frameTime: 60, tickIndex: 0 };
-    const level = { entrances: [{ _opened: false }] };
-    const game = {
-      level,
-      finalGameState: 0,
-      getGameSkills: () => skills,
-      getVictoryCondition: () => victory,
-      getGameTimer: () => timer
-    };
-
-    history._captureScalarState(game);
-    history._captureEntrances(level);
-
-    const noChange = history._allocDelta(0);
-    history._diffScalarState(game, noChange);
-    expect(noChange.skillsChanges).to.equal(null);
-
-    skills.selectedSkill = 1;
-    victory.leftCount = 0;
-    timer.tickIndex = 5;
-    game.finalGameState = 2;
-    level.entrances[0]._opened = true;
-
-    const delta = history._allocDelta(0);
-    history._diffScalarState(game, delta);
-    history._diffEntrances(level, delta);
-
-    expect(delta.skillsChanges).to.be.ok;
-    expect(delta.victoryChanges).to.be.ok;
-    expect(delta.timerChanges).to.be.ok;
-    expect(delta.gameChanges).to.be.ok;
-    expect(delta.entranceChanges.indices).to.have.length(1);
-  });
-
-  it('applies lemming removals, changes, and manager targets', function() {     
-    const history = new HistoryStore();
-    const bombAction = { name: 'bomber' };
-    const walkAction = { name: 'walk' };
-    const skillActions = [];
-    skillActions[SkillTypes.BOMBER] = bombAction;
-    const lem = { id: 0, action: null, countdownAction: null };
-    const manager = {
-      lemmings: [lem],
-      actions: [walkAction],
-      skillActions
-    };
-
-    history._applyLemmingRemovals(manager, [null, { id: NaN }, { id: 0 }]);
-    expect(manager.lemmings[0]).to.equal(null);
-
-    manager.lemmings[0] = lem;
-    history._applyLemmingChanges(manager, {
-      ids: [0, 0, 0],
-      fields: [11, 12, 13],
-      prev: [-1, -1, 0],
-      next: [2, 0, 1]
-    }, true);
-    expect(lem.lastTriggerType).to.equal(2);
-    expect(lem.action).to.equal(walkAction);
-    expect(lem.countdownAction).to.equal(bombAction);
-
-    const changes = {
-      prev: {
-        selectedIndex: 0,
-        spawnTotal: 1,
-        releaseTickIndex: 0,
-        mmTickCounter: 0,
-        nextNukingLemmingsIndex: 0,
-        nukeTargets: []
-      },
-      next: {
-        selectedIndex: 2,
-        spawnTotal: 2,
-        releaseTickIndex: 1,
-        mmTickCounter: 1,
-        nextNukingLemmingsIndex: 1,
-        nukeTargets: [0]
-      }
-    };
-    history._applyLemmingManagerState(manager, changes, true);
-    expect(manager._nukeTargets).to.eql([lem]);
-  });
-
-  it('resets entrance tracking when entrance list changes', function() {
-    const history = new HistoryStore();
-    const level = { entrances: [{ _opened: false }] };
-    const delta = history._allocDelta(0);
-    history._captureEntrances(level);
-    level.entrances.push({ _opened: true });
-    history._diffEntrances(level, delta);
-    expect(history._entranceOpened).to.have.length(2);
-  });
-
-  it('captures null lemmings in baseline state', function() {
-    const history = new HistoryStore();
-    const walkAction = { name: 'walk' };
-    const manager = {
-      lemmings: [
-        null,
-        {
-          id: 1,
-          x: 1,
-          y: 2,
-          lookRight: true,
-          frameIndex: 0,
-          state: 0,
-          canClimb: false,
-          hasParachute: false,
-          removed: false,
-          disabled: false,
-          countdown: 0,
-          hasExploded: false,
-          lastTriggerType: null,
-          action: walkAction,
-          countdownAction: null
-        }
-      ],
-      actions: [walkAction],
-      skillActions: [],
-      actionTypeByAction: new Map([[walkAction, 0]])
-    };
-
-    history._captureLemmingState(manager);
-    expect(history._lemmingState.present[0]).to.equal(0);
-    expect(history._lemmingState.present[1]).to.equal(1);
-  });
-
-  it('handles helper defaults and early exits', function() {
-    const history = new HistoryStore();
-    const state = __test__.createLemmingState(1);
-
-    __test__.cloneLemmingState(state, null);
-    __test__.cloneLemmingState(state, 1);
-
-    const delta = history._allocDelta(0);
-    history.options.deltaPoolLimit = null;
-    history._releaseDelta(delta);
-    expect(history._deltaPool).to.have.length(1);
-
-    history.options.deltaPoolLimit = 0;
-    history._releaseDelta(history._allocDelta(1));
-    expect(history._deltaPool).to.have.length(0);
-
-    history._bindTimer();
-    history.attach(null);
-    history.start();
-    history.truncateAfter(NaN);
-    history.beginTick(0);
-    history.captureBaseline(null);
-
-    runHistoryOps(history, [
-      ['recordSoundEvent', {}],
-      ['recordGroundChange', 0, 0, 0, 0, 0, 0, 0, 0, 0],
-      ['recordEntranceChange', 0, false, false],
-      ['recordTriggerCooldown', null, 0, 0],
-      ['recordTriggerAdd', null, {}],
-      ['recordTriggerRemove', null, {}],
-      ['recordObjectAnimation', {}, { firstFrameIndex: 0, isFinished: false }, { firstFrameIndex: 0, isFinished: false }],
-      ['recordMinimapDeath', {}]
-    ]);
-
-    const historyWithTimer = new HistoryStore();
-    const timer = createStubTimer();
-    const game = {
-      level: { entrances: [] },
-      finalGameState: 0,
-      getGameTimer: () => timer,
-      getLemmingManager: () => ({ lemmings: [] }),
-      getGameSkills: () => null,
-      getVictoryCondition: () => null
-    };
-    historyWithTimer.attach(game, { captureBaseline: false });
-    expect(historyWithTimer.timer).to.equal(timer);
-
-    const historyNoTimer = new HistoryStore();
-    const gameNoTimer = {
-      level: { entrances: [] },
-      finalGameState: 0,
-      getLemmingManager: () => ({ lemmings: [] }),
-      getGameSkills: () => null,
-      getVictoryCondition: () => null
-    };
-    historyNoTimer.attach(gameNoTimer, { captureBaseline: false });
-    expect(historyNoTimer.timer).to.equal(null);
-  });
-
-  it('records changes with boolean conversions and ids', function() {
-    const history = new HistoryStore();
-    history._recording = true;
-    history.beginTick(0);
-    const obj = {};
-    const trigger = new Trigger(TriggerTypes.TRAP, 0, 0, 1, 1);
-    runHistoryOps(history, [
-      ['recordEntranceChange', 0, false, true],
-      ['recordEntranceChange', 1, true, false],
-      ['recordObjectAnimation', obj, { firstFrameIndex: 1, isFinished: false }, { firstFrameIndex: 2, isFinished: true }],
-      ['recordObjectAnimation', obj, { firstFrameIndex: 2, isFinished: true }, { firstFrameIndex: 3, isFinished: false }],
-      ['recordTriggerCooldown', trigger, 0, 2],
-      ['recordTriggerAdd', trigger, {
-        type: trigger.type,
-        x1: trigger.x1,
-        y1: trigger.y1,
-        x2: trigger.x2,
-        y2: trigger.y2,
-        disableTicksCount: trigger.disableTicksCount,
-        soundIndex: trigger.soundIndex,
-        ownerId: null
-      }],
-      ['recordTriggerRemove', trigger, {
-        type: trigger.type,
-        x1: trigger.x1,
-        y1: trigger.y1,
-        x2: trigger.x2,
-        y2: trigger.y2,
-        disableTicksCount: trigger.disableTicksCount,
-        soundIndex: trigger.soundIndex,
-        ownerId: null
-      }],
-      ['recordMinimapDeath', { x: 1, y: 2, ttl: 3, prevCount: 0 }]
-    ]);
-
-    const existingTrigger = { __historyId: 9 };
-    expect(history._ensureTriggerId(existingTrigger)).to.equal(9);
-    expect(history._ensureTriggerId(null)).to.equal(0);
-    const newTrigger = {};
-    expect(history._ensureTriggerId(newTrigger)).to.be.greaterThan(0);
-
-    const existingObj = { __historyId: 11 };
-    expect(history._ensureObjectId(existingObj)).to.equal(11);
-    expect(history._ensureObjectId(null)).to.equal(0);
-    const newObj = {};
-    expect(history._ensureObjectId(newObj)).to.be.greaterThan(0);
-  });
-
-  it('covers keyframe search branches', function() {
-    const history = new HistoryStore();
-    history.keyframeTicks = [2, 4];
-    history._insertKeyframeTick(1);
-    history._insertKeyframeTick(3);
-    expect(history.keyframeTicks).to.eql([1, 2, 3, 4]);
-
-    history.keyframes[2] = { tickIndex: 2 };
-    history.keyframes[3] = { tickIndex: 3 };
-    history.keyframes[4] = { tickIndex: 4 };
-    expect(history.getKeyframeAtOrBefore(3).tickIndex).to.equal(3);
-
-    history.keyframeTicks = [5, 10];
-    history.keyframes[5] = { tickIndex: 5 };
-    history.keyframes[10] = { tickIndex: 10 };
-    expect(history.getKeyframeAtOrBefore(6).tickIndex).to.equal(5);
-
-    history.keyframeTicks = [7];
-    history.keyframes[7] = undefined;
-    expect(history.getKeyframeAtOrBefore(7)).to.equal(null);
-  });
-
-  it('handles truncation edge cases', function() {
-    const empty = new HistoryStore();
-    empty._truncateDeltasAfter(1);
-    empty._truncateKeyframesAfter(1);
-    empty._truncateBefore(1);
-
-    const history = new HistoryStore();
-    seedHistory(history, { deltas: [0, 1] });
-    history._truncateDeltasAfter(1);
-    expect(history.maxDeltaTick).to.equal(1);
-
-    const historyGap = new HistoryStore();
-    seedHistory(historyGap, { deltas: [0, 3] });
-    historyGap._truncateDeltasAfter(1);
-    expect(historyGap.maxDeltaTick).to.equal(0);
-
-    const historyAll = new HistoryStore();
-    seedHistory(historyAll, { deltas: [2] });
-    historyAll._truncateDeltasAfter(1);
-    expect(historyAll.minDeltaTick).to.equal(null);
-
-    const keyframesAll = new HistoryStore();
-    seedHistory(keyframesAll, { keyframes: [2, 3] });
-    keyframesAll._truncateKeyframesAfter(1);
-    expect(keyframesAll.keyframeTicks).to.have.length(0);
-
-    const keyframesMissing = new HistoryStore();
-    keyframesMissing.keyframeTicks = [5];
-    keyframesMissing.keyframes[5] = undefined;
-    keyframesMissing.minKeyframeTick = 5;
-    keyframesMissing.maxKeyframeTick = 5;
-    keyframesMissing._truncateKeyframesAfter(5);
-    expect(keyframesMissing._lastKeyframe).to.equal(null);
-
-    const beforeGap = new HistoryStore();
-    seedHistory(beforeGap, { deltas: [0, 3], keyframes: [0, 3] });
-    beforeGap._truncateBefore(2);
-    expect(beforeGap.minDeltaTick).to.equal(3);
-
-    const beforeAll = new HistoryStore();
-    seedHistory(beforeAll, { deltas: [0], keyframes: [0] });
-    beforeAll._truncateBefore(2);
-    expect(beforeAll.minDeltaTick).to.equal(null);
-    expect(beforeAll.keyframeTicks).to.have.length(0);
-
-    const beforeLast = new HistoryStore();
-    seedHistory(beforeLast, { deltas: [0] });
-    beforeLast.keyframeTicks = [2];
-    beforeLast.keyframes[2] = undefined;
-    beforeLast.minKeyframeTick = 2;
-    beforeLast.maxKeyframeTick = 2;
-    beforeLast._truncateBefore(0);
-    expect(beforeLast._lastKeyframe).to.equal(null);
-
-    const historySpan = new HistoryStore();
-    seedHistory(historySpan, { deltas: [0, 5] });
-    historySpan._truncateDeltasAfter(3);
-    expect(historySpan.maxDeltaTick).to.equal(0);
-
-    const historyClear = new HistoryStore();
-    seedHistory(historyClear, { deltas: [5] });
-    historyClear._truncateDeltasAfter(3);
-    expect(historyClear.minDeltaTick).to.equal(null);
-
-    const beforeSpan = new HistoryStore();
-    seedHistory(beforeSpan, { deltas: [0, 5] });
-    beforeSpan._truncateBefore(2);
-    expect(beforeSpan.minDeltaTick).to.equal(5);
-
-    const beforeClear = new HistoryStore();
-    seedHistory(beforeClear, { deltas: [0] });
-    beforeClear._truncateBefore(2);
-    expect(beforeClear.maxDeltaTick).to.equal(null);
-  });
-
-  it('handles history warning and cap edge cases', function() {
-    const history = new HistoryStore({ historyWarnTicks: 5 });
-    history._maybeWarnHistory();
-    seedHistory(history, { deltas: [0, 1] });
-    history._maybeWarnHistory();
-
-    const capDefault = new HistoryStore({ enableHistoryCap: true });
-    capDefault.options.historyCapTicks = null;
-    capDefault._enforceHistoryCap();
-
-    const capEmpty = new HistoryStore({
-      enableHistoryCap: true,
-      historyCapTicks: 2
-    });
-    capEmpty._enforceHistoryCap();
-
-    const capWithFrame = new HistoryStore({
-      enableHistoryCap: true,
-      historyCapTicks: 2
-    });
-    seedHistory(capWithFrame, { deltas: [0, 1, 2], keyframes: [0] });
-    capWithFrame._enforceHistoryCap();
-    expect(capWithFrame.minDeltaTick).to.equal(0);
-
-    const capNoFrame = new HistoryStore({
-      enableHistoryCap: true,
-      historyCapTicks: 2
-    });
-    seedHistory(capNoFrame, { deltas: [0, 1, 2] });
-    capNoFrame._enforceHistoryCap();
-    expect(capNoFrame.minDeltaTick).to.equal(1);
-  });
-
-  it('diffs lemmings through state transitions', function() {
-    const history = new HistoryStore();
-    history._captureLemmingState(null);
-
-    const walk = { name: 'walk' };
-    const manager = {
-      lemmings: [{
-        id: 0,
-        x: 1,
-        y: 2,
-        lookRight: true,
-        frameIndex: 0,
-        state: 1,
-        canClimb: true,
-        hasParachute: true,
-        removed: false,
-        disabled: false,
-        countdown: 3,
-        hasExploded: false,
-        lastTriggerType: 4,
-        action: walk,
-        countdownAction: null
-      }],
-      actions: [walk],
-      skillActions: [],
-      actionTypeByAction: new Map([[walk, 0]])
-    };
-
-    history._captureLemmingState({
-      lemmings: [null],
-      actions: [walk],
-      skillActions: [],
-      actionTypeByAction: new Map()
-    });
-
-    history._captureLemmingState(manager);
-
-    const delta = history._allocDelta(0);
-    manager.lemmings[0].lookRight = false;
-    manager.lemmings[0].state = null;
-    manager.lemmings[0].canClimb = false;
-    manager.lemmings[0].hasParachute = false;
-    manager.lemmings[0].removed = true;
-    manager.lemmings[0].disabled = true;
-    manager.lemmings[0].countdown = null;
-    manager.lemmings[0].hasExploded = true;
-    manager.lemmings[0].lastTriggerType = NaN;
-    manager.lemmings[0].countdownAction = {};
-    history._diffLemmings(manager, delta);
-
-    const delta2 = history._allocDelta(1);
-    manager.lemmings[0].lookRight = true;
-    manager.lemmings[0].state = 2;
-    manager.lemmings[0].canClimb = true;
-    manager.lemmings[0].hasParachute = true;
-    manager.lemmings[0].removed = false;
-    manager.lemmings[0].disabled = false;
-    manager.lemmings[0].countdown = 4;
-    manager.lemmings[0].hasExploded = false;
-    manager.lemmings[0].lastTriggerType = 2;
-    manager.lemmings[0].countdownAction = null;
-    history._diffLemmings(manager, delta2);
-
-    const delta3 = history._allocDelta(2);
-    manager.lemmings[0] = null;
-    history._diffLemmings(manager, delta3);
-
-    const delta4 = history._allocDelta(3);
-    history._diffLemmings(null, delta4);
-    history._diffLemmings({}, delta4);
-
-    const historyNew = new HistoryStore();
-    const managerNew = {
-      lemmings: [{
-        id: 0,
-        x: 1,
-        y: 1,
-        lookRight: true,
-        frameIndex: 0,
-        state: 0,
-        canClimb: false,
-        hasParachute: false,
-        removed: false,
-        disabled: false,
-        countdown: 0,
-        hasExploded: false,
-        lastTriggerType: null,
-        action: null,
-        countdownAction: null
-      }],
-      actions: [],
-      skillActions: [],
-      actionTypeByAction: new Map()
-    };
-    const deltaNew = historyNew._allocDelta(0);
-    historyNew._diffLemmings(managerNew, deltaNew);
-  });
-
-  it('handles lemming manager comparisons with mismatches', function() {
-    const history = new HistoryStore();
-    expect(history._readLemmingManager(null)).to.equal(null);
-
-    const readManager = {
-      selectedIndex: 1,
-      spawnTotal: 2,
-      releaseTickIndex: 3,
-      mmTickCounter: 4,
-      nextNukingLemmingsIndex: 5,
-      _nukeTargets: [{ id: 7 }, {}]
-    };
-    const readState = history._readLemmingManager(readManager);
-    expect(readState.nukeTargets).to.eql([7, null]);
-
-    const base = {
-      selectedIndex: 1,
-      spawnTotal: 2,
-      releaseTickIndex: 3,
-      mmTickCounter: 4,
-      nextNukingLemmingsIndex: 5,
-      nukeTargets: [1, 2]
-    };
-    expect(history._lemmingManagerEqual(null, null)).to.equal(false);
-    expect(history._lemmingManagerEqual(base, { ...base, selectedIndex: 0 })).to.equal(false);
-    expect(history._lemmingManagerEqual(base, { ...base, spawnTotal: 3 })).to.equal(false);
-    expect(history._lemmingManagerEqual(base, { ...base, releaseTickIndex: 4 })).to.equal(false);
-    expect(history._lemmingManagerEqual(base, { ...base, mmTickCounter: 5 })).to.equal(false);
-    expect(history._lemmingManagerEqual(base, { ...base, nextNukingLemmingsIndex: 6 })).to.equal(false);
-    expect(history._lemmingManagerEqual(base, { ...base, nukeTargets: [1] })).to.equal(false);
-    expect(history._lemmingManagerEqual(base, { ...base, nukeTargets: [1, 3] })).to.equal(false);
-    expect(history._lemmingManagerEqual(base, { ...base })).to.equal(true);
-  });
-
-  it('writes lemming state defaults and resolves action types', function() {
-    const history = new HistoryStore();
-    const state = __test__.createLemmingState(1);
-    const action = { name: 'walk' };
-
-    const lemFalse = {
-      id: 0,
-      x: 0,
-      y: 0,
-      lookRight: false,
-      frameIndex: 0,
-      state: null,
-      canClimb: false,
-      hasParachute: false,
-      removed: false,
-      disabled: false,
-      countdown: null,
-      hasExploded: false,
-      lastTriggerType: NaN
-    };
-    history._writeLemmingState(state, 0, lemFalse, NaN, false);
-
-    const lemTrue = {
-      id: 0,
-      x: 1,
-      y: 2,
-      lookRight: true,
-      frameIndex: 3,
-      state: 4,
-      canClimb: true,
-      hasParachute: true,
-      removed: true,
-      disabled: true,
-      countdown: 5,
-      hasExploded: true,
-      lastTriggerType: 2
-    };
-    history._writeLemmingState(state, 0, lemTrue, 1, true);
-
-    const manager = {
-      actions: [action],
-      actionTypeByAction: new Map([[action, 0]])
-    };
-    expect(history._getActionType(null, action)).to.equal(-1);
-    expect(history._getActionType(manager, null)).to.equal(-1);
-
-    const managerNoMap = { actions: [action], actionTypeByAction: new Map() };
-    expect(history._getActionType(managerNoMap, action)).to.equal(0);
-
-    const managerNoActions = { actionTypeByAction: new Map() };
-    expect(history._getActionType(managerNoActions, action)).to.equal(-1);
-  });
-
-  it('captures and diffs entrances with changes', function() {
-    const history = new HistoryStore();
-    history._captureEntrances(null);
-    history._diffEntrances(null, history._allocDelta(0));
-
-    const level = { entrances: [{ _opened: true }, { _opened: false }, null] };
-    history._captureEntrances(level);
-    const delta = history._allocDelta(1);
-    history._diffEntrances(level, delta);
-
-    level.entrances[0]._opened = false;
-    level.entrances[1]._opened = true;
-    history._diffEntrances(level, delta);
-    expect(delta.entranceChanges.indices).to.have.length(2);
-
-    level.entrances.push({ _opened: true });
-    const delta2 = history._allocDelta(2);
-    history._diffEntrances(level, delta2);
-    expect(history._entranceOpened).to.have.length(4);
-  });
-
-  it('compares scalar state snapshots', function() {
-    const history = new HistoryStore();
-    expect(history._readSkills(null)).to.equal(null);
-    expect(history._readVictory(null)).to.equal(null);
-    expect(history._readTimer(null)).to.equal(null);
-    expect(history._readGameState(null)).to.equal(null);
-
-    const skills = { selectedSkill: 1, cheatMode: true, skills: [1, 2] };
-    const skillsState = history._readSkills(skills);
-    expect(history._skillsEqual(skillsState, { ...skillsState })).to.equal(true);
-    expect(history._skillsEqual(skillsState, { ...skillsState, selectedSkill: 2 })).to.equal(false);
-    expect(history._skillsEqual(skillsState, { ...skillsState, cheatMode: false })).to.equal(false);
-    expect(history._skillsEqual(skillsState, { ...skillsState, skills: [1] })).to.equal(false);
-    expect(history._skillsEqual(skillsState, { ...skillsState, skills: [1, 3] })).to.equal(false);
-    expect(history._skillsEqual(skillsState, { selectedSkill: 1, cheatMode: true })).to.equal(false);
-    expect(history._skillsEqual(null, skillsState)).to.equal(false);
-
-    const victory = {
-      releaseRate: 1,
-      minReleaseRate: 1,
-      leftCount: 1,
-      outCount: 0,
-      survivorCount: 0,
-      isFinalize: false
-    };
-    const victoryState = history._readVictory(victory);
-    expect(history._victoryEqual(victoryState, { ...victoryState })).to.equal(true);
-    expect(history._victoryEqual(victoryState, { ...victoryState, outCount: 1 })).to.equal(false);
-    expect(history._victoryEqual(null, victoryState)).to.equal(false);
-
-    const timer = { speedFactor: 1, frameTime: 60, tickIndex: 0 };
-    const timerState = history._readTimer(timer);
-    expect(history._timerEqual(timerState, { ...timerState })).to.equal(true);
-    expect(history._timerEqual(timerState, { ...timerState, tickIndex: 1 })).to.equal(false);
-    expect(history._timerEqual(null, timerState)).to.equal(false);
-
-    const gameState = history._readGameState({ finalGameState: 1 });
-    expect(history._gameStateEqual(gameState, { finalGameState: 1 })).to.equal(true);
-    expect(history._gameStateEqual(gameState, { finalGameState: 2 })).to.equal(false);
-    expect(history._gameStateEqual(null, gameState)).to.equal(false);
-  });
-
-  it('applies lemming adds and changes across fields', function() {
-    const history = new HistoryStore();
-    history._applyDelta(null, null, true);
-
-    const walkAction = { name: 'walk' };
-    const bombAction = { name: 'bomb' };
-
-    const manager = {
-      lemmings: null,
-      actions: [walkAction]
-    };
-
-    const addList = [{
-      id: 0,
-      x: 1,
-      y: 2,
-      lookRight: 1,
-      frameIndex: 0,
-      state: 0,
-      canClimb: 0,
-      hasParachute: 0,
-      removed: 0,
-      disabled: 0,
-      countdown: 0,
-      hasExploded: 0,
-      lastTriggerType: -1,
-      actionType: -1,
-      countdownActive: 0
-    }];
-    history._applyLemmingAdds(manager, addList);
-    expect(Array.isArray(manager.lemmings)).to.equal(true);
-
-    const missingChanges = { ids: [1], fields: [0], prev: [0], next: [1] };
-    history._applyLemmingChanges(manager, missingChanges, true);
-
-    manager.skillActions = [];
-    manager.skillActions[SkillTypes.BOMBER] = bombAction;
-
-    history._applyLemmingAdds(manager, [{
-      id: 1,
-      x: 3,
-      y: 4,
-      lookRight: 1,
-      frameIndex: 0,
-      state: 0,
-      canClimb: 0,
-      hasParachute: 0,
-      removed: 0,
-      disabled: 0,
-      countdown: 0,
-      hasExploded: 0,
-      lastTriggerType: -1,
-      actionType: -1,
-      countdownActive: 1
-    }]);
-
-    const lem = manager.lemmings[0];
-    const fields = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 11, 12, 12, 13, 13, 99];
-    const ids = new Array(fields.length).fill(0);
-    const next = [
-      10, 20, 1, 3, 4, 1, 1, 1, 1, 7, 1,
-      -1, 2,
-      -1, 0,
-      0, 1,
-      0
-    ];
-    const prev = new Array(fields.length).fill(0);
-    const changes = { ids, fields, prev, next };
-    history._applyLemmingChanges(manager, changes, true);
-
-    expect(lem.x).to.equal(10);
-    expect(lem.y).to.equal(20);
-    expect(lem.lookRight).to.equal(true);
-    expect(lem.frameIndex).to.equal(3);
-    expect(lem.state).to.equal(4);
-    expect(lem.canClimb).to.equal(true);
-    expect(lem.hasParachute).to.equal(true);
-    expect(lem.removed).to.equal(true);
-    expect(lem.disabled).to.equal(true);
-    expect(lem.countdown).to.equal(7);
-    expect(lem.hasExploded).to.equal(true);
-    expect(lem.lastTriggerType).to.equal(2);
-    expect(lem.action).to.equal(walkAction);
-    expect(lem.countdownAction).to.equal(bombAction);
-
-    const managerNoSkill = { lemmings: [{ id: 0 }], actions: [walkAction] };
-    history._applyLemmingChanges(
-      managerNoSkill,
-      { ids: [0], fields: [2], prev: [0], next: [1] },
-      true
-    );
-  });
-
-  it('applies manager state defaults and rebuilds active list', function() {
-    const history = new HistoryStore();
-    history._applyLemmingManagerState(null, null, true);
-    history._rebuildActiveLemmings(null);
-
-    const lem = { id: 0, removed: false };
-    const manager = { lemmings: [lem] };
-    history._applyLemmingManagerState(manager, {
-      next: {
-        selectedIndex: 2,
-        spawnTotal: 3,
-        releaseTickIndex: 4,
-        mmTickCounter: 5,
-        nextNukingLemmingsIndex: 6,
-        nukeTargets: [0]
-      }
-    }, true);
-    expect(manager._nukeTargets).to.eql([lem]);
-
-    history._applyLemmingManagerState(manager, {
-      next: { nukeTargets: null }
-    }, true);
-    expect(manager.selectedIndex).to.equal(-1);
-    expect(manager.spawnTotal).to.equal(0);
-    expect(manager.releaseTickIndex).to.equal(0);
-    expect(manager.mmTickCounter).to.equal(0);
-    expect(manager.nextNukingLemmingsIndex).to.equal(-1);
-    expect(manager._nukeTargets).to.equal(null);
-
-    history._applyLemmingManagerState(manager, { next: null }, true);
-  });
-
-  it('handles entrance and ground change fallbacks', function() {
-    const history = new HistoryStore();
-    history._applyEntranceChanges(null, null, true);
-    history._applyGroundChanges(null, null, true);
-
-    const level = {
-      entrances: [{ _opened: false }],
-      groundMask: { mask: new Uint8Array(1) },
-      groundImage: new Uint8ClampedArray(4)
-    };
-    const entranceChanges = { indices: [0], prev: [0], next: [1] };
-    history._applyEntranceChanges(level, entranceChanges, true);
-    expect(level.entrances[0]._opened).to.equal(true);
-
-    const groundChanges = {
-      spans: null,
-      indices: [0],
-      prevMask: [0],
-      prevR: [0],
-      prevG: [0],
-      prevB: [0],
-      nextMask: [1],
-      nextR: [1],
-      nextG: [2],
-      nextB: [3]
-    };
-    history._applyGroundChanges(level, groundChanges, false);
-    expect(level.groundMask.mask[0]).to.equal(0);
-  });
-
-  it('applies trigger changes and resolves ids', function() {
-    const history = new HistoryStore();
-    const owner = { id: 1 };
-    const cooldownOwner = { id: 2 };
-    const manager = {
-      lemmings: [owner, cooldownOwner],
-      getLemming: (id) => (id === 1 ? owner : cooldownOwner)
-    };
-    const triggerManager = {
-      _triggers: new Set(),
-      add(trigger) { this._triggers.add(trigger); },
-      removeByOwner(ownerTarget) {
-        for (const trig of Array.from(this._triggers)) {
-          if (trig.owner === ownerTarget) this._triggers.delete(trig);
-        }
-      }
-    };
-    const existing = new Trigger(TriggerTypes.TRAP, 0, 0, 1, 1, 0, 0, owner);
-    existing.__historyId = 2;
-    existing.disabledUntilTick = 5;
-    triggerManager._triggers.add(existing);
-
-    const cooldown = new Trigger(TriggerTypes.TRAP, 2, 2, 3, 3, 0, 0, cooldownOwner);
-    cooldown.__historyId = 3;
-    triggerManager._triggers.add(cooldown);
-
-    const game = { triggerManager, getLemmingManager: () => manager };
-    const delta = {
-      triggerAdd: [{
-        id: 10,
-        type: TriggerTypes.KILL,
-        x1: 1,
-        y1: 1,
-        x2: 2,
-        y2: 2,
-        disableTicksCount: 0,
-        soundIndex: 1,
-        ownerId: null
-      }],
-      triggerRemove: [{ id: 2 }],
-      triggerCooldownChanges: { ids: [3, 99], prev: [0, 0], next: [7, 8] }
-    };
-
-    history._applyTriggerChanges(game, delta, true);
-    expect(triggerManager._triggers.has(existing)).to.equal(false);
-    const added = Array.from(triggerManager._triggers)
-      .find(trig => trig.__historyId === 10);
-    expect(added).to.be.ok;
-    expect(added.disabledUntilTick).to.equal(0);
-    expect(cooldown.disabledUntilTick).to.equal(7);
-
-    const found = history._findTriggerById(triggerManager, 3);
-    expect(found).to.equal(cooldown);
-    expect(history._findTriggerById(triggerManager, 123)).to.equal(null);
-    expect(history._findTriggerById({}, 5)).to.equal(null);
-
-    history._applyTriggerChanges(game, { triggerAdd: [], triggerRemove: null }, true);
-    history._applyTriggerChanges(game, { triggerAdd: null, triggerRemove: [] }, true);
-  });
-
-  it('reads and applies trigger state with missing data', function() {
-    const history = new HistoryStore();
-    const owner = { id: 1 };
-    const staticTrigger = new Trigger(TriggerTypes.TRAP, 1, 1, 2, 2, 0, 5, null);
-    const dynamicTrigger = new Trigger(TriggerTypes.KILL, 3, 3, 4, 4, 0, 7, owner);
-    const orphanTrigger = new Trigger(TriggerTypes.KILL, 5, 5, 6, 6, 0, 8, { id: NaN });
-    const level = { triggers: [null, staticTrigger] };
-    const triggerManager = {
-      _triggers: new Set([staticTrigger, dynamicTrigger, orphanTrigger]),
-      add(trigger) { this._triggers.add(trigger); },
-      removeByOwner(ownerTarget) {
-        for (const trig of Array.from(this._triggers)) {
-          if (trig.owner === ownerTarget) this._triggers.delete(trig);
-        }
-      }
-    };
-    const game = {
-      level,
-      triggerManager,
-      getLemmingManager: () => ({ getLemming: (id) => (id === 1 ? owner : null) })
-    };
-    const state = history._readTriggerState(game);
-    expect(state.staticTriggers).to.have.length(1);
-    expect(state.dynamicTriggers).to.have.length(1);
-
-    const stateNoTriggers = history._readTriggerState({
-      level: {},
-      triggerManager: { _triggers: new Set() }
-    });
-    expect(stateNoTriggers.staticTriggers).to.have.length(0);
-
-    history._applyTriggerState({ level: null, triggerManager: null }, null);
-
-    const applyGameEmpty = {
-      level: { triggers: [staticTrigger, null] },
-      triggerManager: { _triggers: undefined, add() {}, removeByOwner() {} },
-      getLemmingManager: () => null
-    };
-    history._applyTriggerState(applyGameEmpty, { staticTriggers: state.staticTriggers });
-
-    const applyGameNoList = {
-      level: {},
-      triggerManager: { _triggers: undefined, add() {}, removeByOwner() {} },
-      getLemmingManager: () => null
-    };
-    history._applyTriggerState(applyGameNoList, {
-      dynamicTriggers: [{
-        id: 99,
-        ownerId: null,
-        type: TriggerTypes.TRAP,
-        x1: 0,
-        y1: 0,
-        x2: 1,
-        y2: 1,
-        disableTicksCount: 0,
-        soundIndex: 0,
-        disabledUntilTick: 0
-      }]
-    });
-
-    const missingOwnerTrigger = new Trigger(TriggerTypes.KILL, 2, 2, 3, 3, 0, 0, { id: 2 });
-    const applyManager = {
-      _triggers: new Set([dynamicTrigger, missingOwnerTrigger]),
-      add(trigger) { this._triggers.add(trigger); },
-      removeByOwner(ownerTarget) {
-        for (const trig of Array.from(this._triggers)) {
-          if (trig.owner === ownerTarget) this._triggers.delete(trig);
-        }
-      }
-    };
-    const applyGame = {
-      level: { triggers: [staticTrigger, null] },
-      triggerManager: applyManager,
-      getLemmingManager: () => ({ getLemming: (id) => (id === 1 ? owner : null) })
-    };
-    const applyState = {
-      staticTriggers: state.staticTriggers,
-      dynamicTriggers: [{
-        id: 10,
-        ownerId: 1,
-        type: TriggerTypes.TRAP,
-        x1: 0,
-        y1: 0,
-        x2: 1,
-        y2: 1,
-        disableTicksCount: 0,
-        soundIndex: 0,
-        disabledUntilTick: 2
-      }, {
-        id: 11,
-        ownerId: 2,
-        type: TriggerTypes.KILL,
-        x1: 1,
-        y1: 1,
-        x2: 2,
-        y2: 2,
-        disableTicksCount: 0,
-        soundIndex: 0,
-        disabledUntilTick: 0
-      }]
-    };
-    history._applyTriggerState(applyGame, applyState);
-  });
-
-  it('handles object state and changes with missing animations', function() {
-    const history = new HistoryStore();
-    const obj = { animation: { firstFrameIndex: 0, isFinished: false } };
-    const level = { objects: [obj, {}] };
-
-    const state = history._readObjectState(level);
-    expect(state).to.have.length(1);
-
-    const objId = history._ensureObjectId(obj);
-    const changes = {
-      ids: [objId, 999],
-      prevFirst: [0, 0],
-      prevFinished: [0, 0],
-      nextFirst: [2, 1],
-      nextFinished: [1, 1]
-    };
-    history._applyObjectChanges(level, changes, true);
-    expect(obj.animation.firstFrameIndex).to.equal(2);
-
-    obj.animation = null;
-    history._applyObjectChanges(level, {
-      ids: [objId],
-      prevFirst: [0],
-      prevFinished: [0],
-      nextFirst: [1],
-      nextFinished: [1]
-    }, true);
-
-    history._objectById = new Map();
-    history._applyObjectChanges({}, {
-      ids: [objId],
-      prevFirst: [0],
-      prevFinished: [0],
-      nextFirst: [1],
-      nextFinished: [1]
-    }, true);
-
-    history._applyObjectState(level, null);
-
-    history._objectById = new Map();
-    const entries = [{ id: objId, firstFrameIndex: 5, isFinished: true }];
-    obj.animation = { firstFrameIndex: 0, isFinished: false };
-    history._applyObjectState(level, entries);
-    expect(obj.animation.firstFrameIndex).to.equal(5);
-
-    obj.animation = null;
-    history._applyObjectState(level, entries);
-
-    history._applyObjectState(null, [{
-      id: 123,
-      firstFrameIndex: 0,
-      isFinished: false
-    }]);
-  });
-
-  it('applies minimap deaths and reads defaults', function() {
-    const history = new HistoryStore();
-    const manager = {
-      miniMap: {
-        deadDots: new Uint8Array(0),
-        deadTTLs: new Uint8Array(0)
-      }
-    };
-
-    history._applyMinimapDeaths(manager, [{
-      x: undefined,
-      y: undefined,
-      ttl: undefined,
-      prevCount: undefined
-    }], true);
-    expect(manager.miniMap.deadDots[0]).to.equal(0);
-    expect(manager.miniMap.deadTTLs[0]).to.equal(0);
-
-    history._applyMinimapDeaths(manager, [{
-      x: 2,
-      y: 3,
-      ttl: 4,
-      prevCount: 1
-    }], true);
-
-    history._applyMinimapDeaths(manager, [{ prevCount: 1 }, {}], false);
-    expect(manager.miniMap.deadCount).to.equal(1);
-
-    const minimapState = history._readMinimapState({
-      deadDots: null,
-      deadTTLs: null,
-      deadCount: undefined
-    });
-    expect(minimapState.deadDots).to.be.instanceof(Uint8Array);
-    expect(minimapState.deadTTLs).to.be.instanceof(Uint8Array);
-    expect(minimapState.deadCount).to.equal(0);
-  });
-
-  it('captures keyframes without level data', function() {
-    const history = new HistoryStore();
-    const game = {
-      finalGameState: 0,
-      getLemmingManager: () => ({ lemmings: [] }),
-      getGameTimer: () => null,
-      getGameSkills: () => null,
-      getVictoryCondition: () => null
-    };
-    const frame = history._captureKeyframe(game, 0);
-    expect(frame.entranceOpened).to.have.length(0);
-    expect(frame.groundMask).to.equal(null);
-
-    const gameWithLevel = {
-      level: { entrances: [{ _opened: true }, { _opened: false }] },
-      finalGameState: 0,
-      getLemmingManager: () => ({ lemmings: [] }),
-      getGameTimer: () => null,
-      getGameSkills: () => null,
-      getVictoryCondition: () => null
-    };
-    const frameWithLevel = history._captureKeyframe(gameWithLevel, 1);
-    expect(frameWithLevel.entranceOpened[0]).to.equal(1);
-    expect(frameWithLevel.entranceOpened[1]).to.equal(0);
-  });
-
-  it('captures interval keyframes during endTick', function() {
-    const { history, timer } = createHistoryFixture();
-    recordTick(history, timer, 0, null, 5);
-    expect(history.getKeyframe(5)).to.be.ok;
-  });
-
-  it('binds before tick handlers when timers provide hooks', function() {
-    const timer = {
-      tickIndex: 0,
-      speedFactor: 1,
-      frameTime: 60,
-      onBeforeGameTick: new EventHandler(),
-      onGameTick: new EventHandler()
-    };
-    const manager = { lemmings: [], actions: [], skillActions: [] };
-    const game = {
-      level: { entrances: [] },
-      finalGameState: 0,
-      getLemmingManager: () => manager,
-      getGameTimer: () => timer,
-      getGameSkills: () => null,
-      getVictoryCondition: () => null
-    };
-    const history = new HistoryStore();
-    history.attach(game, { captureBaseline: true });
-    timer.onBeforeGameTick.trigger(3);
-    expect(history._currentTick).to.equal(3);
-  });
-
-  it('applies keyframes without nuke targets arrays', function() {
-    const { history, game, manager } = createHistoryFixture();
-    history.applyKeyframe(game, {
-      lemmingManagerState: { nukeTargets: null }
-    });
-    expect(manager._nukeTargets).to.equal(null);
-  });
-
-  it('applies minimap keyframe defaults', function() {
-    const { history, game, manager } = createHistoryFixture();
-    manager.miniMap = {
-      deadDots: new Uint8Array([1, 2]),
-      deadTTLs: new Uint8Array([3]),
-      deadCount: 1
-    };
-    history.applyKeyframe(game, {
-      minimapState: { deadDots: null, deadTTLs: null, deadCount: undefined }
-    });
-    expect(manager.miniMap.deadDots).to.have.length(0);
-    expect(manager.miniMap.deadTTLs).to.have.length(0);
-    expect(manager.miniMap.deadCount).to.equal(0);
-  });
-
-  it('skips applyKeyframe when inputs are missing', function() {
-    const history = new HistoryStore();
-    history.applyKeyframe(null, { lemmingState: {} });
-    history.applyKeyframe({ getLemmingManager: () => ({}) }, null);
-  });
-
-  it('initializes missing lemming arrays during keyframe apply', function() {
-    const history = new HistoryStore();
-    const manager = { actions: [], skillActions: [] };
-    const game = {
-      level: { entrances: [] },
-      finalGameState: 0,
-      getLemmingManager: () => manager,
-      getGameTimer: () => null,
-      getGameSkills: () => null,
-      getVictoryCondition: () => null
-    };
-    const lemmingState = __test__.createLemmingState(1);
-    lemmingState.present[0] = 1;
-    lemmingState.x[0] = 2;
-    lemmingState.y[0] = 3;
-    lemmingState.actionType[0] = -1;
-    history.applyKeyframe(game, { lemmingState });
-    expect(Array.isArray(manager.lemmings)).to.equal(true);
-    expect(manager.lemmings[0]).to.be.ok;
-  });
-
-  it('applies keyframe action and entrance fallbacks', function() {
-    const { history, game, manager, walkAction } = createHistoryFixture();
-    game.level.entrances = undefined;
-    manager.actions = [walkAction];
-
-    const lemmingState = __test__.createLemmingState(1);
-    lemmingState.present[0] = 1;
-    lemmingState.x[0] = 1;
-    lemmingState.y[0] = 2;
-    lemmingState.actionType[0] = -1;
-
-    history.applyKeyframe(game, {
-      lemmingState,
-      lemmingManagerState: { nukeTargets: [NaN] },
-      entranceOpened: new Uint8Array(0)
-    });
-
-    expect(manager.lemmings[0].action).to.equal(null);
-    expect(manager._nukeTargets).to.eql([]);
-  });
-
-  it('constructs lemmings from keyframes without skill actions', function() {
-    const history = new HistoryStore();
-    const ctorCalls = [];
-    const LemCtor = function(x, y, id) {
-      this.id = id;
-      this.x = x;
-      this.y = y;
-      ctorCalls.push([x, y, id]);
-    };
-    const manager = { lemmings: [], actions: [], _lemmingCtor: LemCtor };
-    const game = {
-      level: { entrances: [] },
-      finalGameState: 0,
-      getLemmingManager: () => manager,
-      getGameTimer: () => null,
-      getGameSkills: () => null,
-      getVictoryCondition: () => null
-    };
-    const lemmingState = __test__.createLemmingState(1);
-    lemmingState.present[0] = 1;
-    lemmingState.x[0] = 4;
-    lemmingState.y[0] = 5;
-    lemmingState.actionType[0] = -1;
-    history.applyKeyframe(game, { lemmingState });
-    expect(manager.lemmings[0]).to.be.ok;
-    expect(ctorCalls).to.have.length(1);
-
-    manager._lemmingCtor = null;
-    manager.lemmings = [];
-    lemmingState.x[0] = 7;
-    lemmingState.y[0] = 8;
-    history.applyKeyframe(game, { lemmingState });
-    expect(manager.lemmings[0]).to.be.ok;
-  });
-});
diff --git a/test/input/editor-keybindings.test.js b/test/input/editor-keybindings.test.js
new file mode 100644
index 00000000..189c026f
--- /dev/null
+++ b/test/input/editor-keybindings.test.js
@@ -0,0 +1,156 @@
+import { expect } from 'chai';
+import { EditorKeybindings } from '../../js/input/EditorKeybindings.js';
+import { EditorTools } from '../../js/editor/EditorTools.js';
+
+describe('EditorKeybindings', function () {
+  let originalWindowDescriptor;
+  let originalNavigatorDescriptor;
+
+  beforeEach(function () {
+    originalWindowDescriptor = Object.getOwnPropertyDescriptor(globalThis, 'window');
+    originalNavigatorDescriptor = Object.getOwnPropertyDescriptor(globalThis, 'navigator');
+    const listeners = new Map();
+    Object.defineProperty(globalThis, 'window', {
+      configurable: true,
+      writable: true,
+      value: {
+        addEventListener(type, handler) {
+          listeners.set(type, handler);
+        },
+        removeEventListener(type) {
+          listeners.delete(type);
+        },
+        requestAnimationFrame() {
+          return 1;
+        },
+        cancelAnimationFrame() {},
+        _listeners: listeners
+      }
+    });
+    Object.defineProperty(globalThis, 'navigator', {
+      configurable: true,
+      writable: true,
+      value: {
+        getGamepads() {
+          return [];
+        }
+      }
+    });
+  });
+
+  afterEach(function () {
+    if (originalWindowDescriptor) {
+      Object.defineProperty(globalThis, 'window', originalWindowDescriptor);
+    } else {
+      delete globalThis.window;
+    }
+    if (originalNavigatorDescriptor) {
+      Object.defineProperty(globalThis, 'navigator', originalNavigatorDescriptor);
+    } else {
+      delete globalThis.navigator;
+    }
+  });
+
+  it('binds and disposes key listeners', function () {
+    const keybindings = new EditorKeybindings({ setTool() {} });
+    keybindings.bind();
+    expect(globalThis.window._listeners.has('keydown')).to.equal(true);
+    keybindings.dispose();
+    expect(globalThis.window._listeners.has('keydown')).to.equal(false);
+    expect(keybindings.gamepad).to.equal(null);
+  });
+
+  it('uses injected runtime references for listener binding', function () {
+    const listeners = new Map();
+    const windowRef = {
+      addEventListener(type, handler) {
+        listeners.set(type, handler);
+      },
+      removeEventListener(type, handler) {
+        if (listeners.get(type) === handler) listeners.delete(type);
+      }
+    };
+    const keybindings = new EditorKeybindings(
+      { setTool() {} },
+      {
+        window: windowRef,
+        performance: { now: () => 0 },
+        requestAnimationFrame() { return 1; },
+        cancelAnimationFrame() {},
+        navigator: { getGamepads: () => [] },
+        storage: null
+      }
+    );
+
+    keybindings.bind();
+    expect(listeners.has('keydown')).to.equal(true);
+    keybindings.dispose();
+    expect(listeners.size).to.equal(0);
+  });
+
+  it('ignores key events from editable targets', function () {
+    const keybindings = new EditorKeybindings({ setTool() {} });
+    expect(keybindings._shouldIgnoreKey({ target: { isContentEditable: true } })).to.equal(true);
+    expect(keybindings._shouldIgnoreKey({ target: { tagName: 'input' } })).to.equal(true);
+    expect(keybindings._shouldIgnoreKey({ target: { tagName: 'textarea' } })).to.equal(true);
+    expect(keybindings._shouldIgnoreKey({ target: { tagName: 'div' } })).to.equal(false);
+  });
+
+  it('maps keyboard actions to editor callbacks and prevents defaults', function () {
+    const toolChanges = [];
+    let previews = 0;
+    const keybindings = new EditorKeybindings(
+      {
+        setTool(tool) {
+          toolChanges.push(tool);
+        },
+        gridSize: 8
+      },
+      {
+        onToolChange(tool) {
+          toolChanges.push(`on:${tool}`);
+        },
+        onPreview() {
+          previews += 1;
+        }
+      }
+    );
+
+    let prevented = false;
+    keybindings._onKeyDown({
+      code: 'KeyS',
+      shiftKey: false,
+      ctrlKey: false,
+      altKey: false,
+      metaKey: false,
+      preventDefault() {
+        prevented = true;
+      },
+      target: { tagName: 'canvas' }
+    });
+
+    expect(toolChanges[0]).to.equal(EditorTools.SELECT);
+    expect(toolChanges[1]).to.equal(`on:${EditorTools.SELECT}`);
+    expect(previews).to.equal(1);
+    expect(prevented).to.equal(true);
+  });
+
+  it('returns false for unknown actions and delegates gamepad config updates', function () {
+    const keybindings = new EditorKeybindings({ setTool() {} });
+    expect(keybindings._handleAction('missing.action')).to.equal(false);
+
+    const calls = [];
+    keybindings.gamepad = {
+      setConfig(config, options) {
+        calls.push({ config, options });
+      }
+    };
+    keybindings.setGamepadBindings({ bindings: {} }, { persist: false });
+    expect(calls).to.deep.equal([
+      {
+        config: { bindings: {} },
+        options: { persist: false }
+      }
+    ]);
+  });
+});
diff --git a/test/input/gamepad-input-controller.test.js b/test/input/gamepad-input-controller.test.js
new file mode 100644
index 00000000..1c12b8fb
--- /dev/null
+++ b/test/input/gamepad-input-controller.test.js
@@ -0,0 +1,372 @@
+import { expect } from 'chai';
+import {
+  DEFAULT_GAMEPAD_BINDINGS,
+  GamepadInputController,
+  GamepadBindingRegistry,
+  mergeGamepadConfigLayers
+} from '../../js/input/GamepadInputController.js';
+
+const createButton = (pressed = false, value = null) => ({
+  pressed: !!pressed,
+  value: value == null ? (pressed ? 1 : 0) : value
+});
+
+const createPad = ({
+  buttons = [],
+  axes = [],
+  connected = true
+} = {}) => ({
+  connected,
+  buttons,
+  axes
+});
+
+const createStorage = () => {
+  const store = new Map();
+  return {
+    getItem(key) {
+      return store.has(key) ? store.get(key) : null;
+    },
+    setItem(key, value) {
+      store.set(key, value);
+    },
+    removeItem(key) {
+      store.delete(key);
+    },
+    _store: store
+  };
+};
+
+const flushPromises = () => new Promise(resolve => setTimeout(resolve, 0));
+
+describe('GamepadInputController', function () {
+  it('routes button and axis bindings with held-action semantics', function () {
+    const rafCallbacks = [];
+    const windowStub = {
+      requestAnimationFrame(callback) {
+        rafCallbacks.push(callback);
+        return rafCallbacks.length;
+      },
+      cancelAnimationFrame() {}
+    };
+    const pads = [
+      createPad({
+        buttons: Array.from({ length: 17 }, () => createButton(false)),
+        axes: [0, 0, 0, 0]
+      })
+    ];
+    const navigatorStub = {
+      getGamepads() {
+        return pads;
+      }
+    };
+    const calls = [];
+    const controller = new GamepadInputController({
+      mode: 'gameplay',
+      window: windowStub,
+      navigator: navigatorStub,
+      onAction(action, type) {
+        calls.push(`${action}:${type}`);
+      }
+    });
+
+    const step = () => {
+      const cb = rafCallbacks.shift();
+      expect(cb).to.be.a('function');
+      cb();
+    };
+
+    step();
+    expect(calls).to.deep.equal([]);
+
+    pads[0].buttons[14].pressed = true;
+    pads[0].buttons[14].value = 1;
+    step();
+    expect(calls).to.deep.equal(['panLeft:down']);
+
+    pads[0].axes[0] = -0.9;
+    step();
+    expect(calls).to.deep.equal(['panLeft:down']);
+
+    pads[0].buttons[14].pressed = false;
+    pads[0].buttons[14].value = 0;
+    step();
+    expect(calls).to.deep.equal(['panLeft:down']);
+
+    pads[0].axes[0] = 0;
+    step();
+    expect(calls).to.deep.equal(['panLeft:down', 'panLeft:up']);
+
+    controller.dispose();
+  });
+
+  it('persists remapped configs and reloads persisted bindings', function () {
+    const storage = createStorage();
+    const windowStub = {
+      requestAnimationFrame() { return 1; },
+      cancelAnimationFrame() {}
+    };
+    const navigatorStub = {
+      getGamepads() {
+        return [];
+      }
+    };
+    const controller = new GamepadInputController({
+      mode: 'gameplay',
+      window: windowStub,
+      navigator: navigatorStub,
+      storage
+    });
+
+    controller.setConfig({
+      version: 2,
+      bindings: {
+        gameplay: {
+          togglePause: ['button:0']
+        }
+      }
+    });
+    const persisted = storage.getItem('lem-gamepad-bindings-v1');
+    expect(persisted).to.be.a('string');
+    controller.dispose();
+
+    const restored = new GamepadInputController({
+      mode: 'gameplay',
+      window: windowStub,
+      navigator: navigatorStub,
+      storage
+    });
+    expect(restored.getDisplayBindings('togglePause')).to.deep.equal(['A / Cross']);
+    restored.dispose();
+  });
+
+  it('keeps persisted overrides above async file defaults', async function () {
+    const storage = createStorage();
+    storage.setItem('lem-gamepad-bindings-v1', JSON.stringify({
+      version: 1,
+      bindings: {
+        gameplay: {
+          togglePause: ['button:0']
+        }
+      }
+    }));
+    const windowStub = {
+      requestAnimationFrame() { return 1; },
+      cancelAnimationFrame() {}
+    };
+    const navigatorStub = {
+      getGamepads() {
+        return [];
+      }
+    };
+    const controller = new GamepadInputController({
+      mode: 'gameplay',
+      window: windowStub,
+      navigator: navigatorStub,
+      storage,
+      fileProvider: {
+        loadString() {
+          return Promise.resolve(JSON.stringify({
+            version: 3,
+            bindings: {
+              gameplay: {
+                togglePause: ['button:1'],
+                restartLevel: ['button:3']
+              }
+            }
+          }));
+        }
+      }
+    });
+
+    await flushPromises();
+
+    expect(controller.getDisplayBindings('togglePause')).to.deep.equal(['A / Cross']);
+    expect(controller.getDisplayBindings('restartLevel')).to.deep.equal(['Y / Triangle']);
+    controller.dispose();
+  });
+
+  it('migrates legacy full persisted snapshots into user overrides', async function () {
+    const storage = createStorage();
+    storage.setItem('lem-gamepad-bindings-v1', JSON.stringify({
+      version: 7,
+      bindings: {
+        gameplay: {
+          ...DEFAULT_GAMEPAD_BINDINGS.bindings.gameplay,
+          togglePause: ['button:0']
+        },
+        editor: {
+          ...DEFAULT_GAMEPAD_BINDINGS.bindings.editor
+        }
+      }
+    }));
+    const windowStub = {
+      requestAnimationFrame() { return 1; },
+      cancelAnimationFrame() {}
+    };
+    const navigatorStub = {
+      getGamepads() {
+        return [];
+      }
+    };
+    const controller = new GamepadInputController({
+      mode: 'gameplay',
+      window: windowStub,
+      navigator: navigatorStub,
+      storage,
+      fileProvider: {
+        loadString() {
+          return Promise.resolve(JSON.stringify({
+            version: 4,
+            bindings: {
+              gameplay: {
+                restartLevel: ['button:3']
+              },
+              editor: {
+                editorUndo: ['button:1']
+              }
+            }
+          }));
+        }
+      }
+    });
+
+    await flushPromises();
+
+    expect(controller.getDisplayBindings('togglePause')).to.deep.equal(['A / Cross']);
+    expect(controller.getDisplayBindings('restartLevel')).to.deep.equal(['Y / Triangle']);
+    controller.mode = 'editor';
+    expect(controller.getDisplayBindings('editorUndo')).to.deep.equal(['B / Circle']);
+    const persisted = JSON.parse(storage.getItem('lem-gamepad-bindings-v1'));
+    expect(persisted).to.deep.equal({
+      version: 7,
+      bindings: {
+        gameplay: {
+          togglePause: ['button:0']
+        }
+      }
+    });
+    controller.dispose();
+  });
+
+  it('persists only the user override layer', async function () {
+    const storage = createStorage();
+    const windowStub = {
+      requestAnimationFrame() { return 1; },
+      cancelAnimationFrame() {}
+    };
+    const navigatorStub = {
+      getGamepads() {
+        return [];
+      }
+    };
+    const controller = new GamepadInputController({
+      mode: 'gameplay',
+      window: windowStub,
+      navigator: navigatorStub,
+      storage,
+      fileProvider: {
+        loadString() {
+          return Promise.resolve(JSON.stringify({
+            version: 2,
+            bindings: {
+              gameplay: {
+                restartLevel: ['button:3']
+              }
+            }
+          }));
+        }
+      }
+    });
+
+    await flushPromises();
+    controller.setConfig({
+      version: 5,
+      bindings: {
+        gameplay: {
+          togglePause: ['button:0']
+        }
+      }
+    });
+
+    const persisted = JSON.parse(storage.getItem('lem-gamepad-bindings-v1'));
+    expect(persisted).to.deep.equal({
+      version: 5,
+      bindings: {
+        gameplay: {
+          togglePause: ['button:0']
+        }
+      }
+    });
+    expect(persisted.bindings.gameplay.restartLevel).to.equal(undefined);
+    expect(controller.getDisplayBindings('restartLevel')).to.deep.equal(['Y / Triangle']);
+    controller.dispose();
+  });
+
+  it('applies non-persisted session overrides without writing storage', function () {
+    const storage = createStorage();
+    const windowStub = {
+      requestAnimationFrame() { return 1; },
+      cancelAnimationFrame() {}
+    };
+    const navigatorStub = {
+      getGamepads() {
+        return [];
+      }
+    };
+    const controller = new GamepadInputController({
+      mode: 'gameplay',
+      window: windowStub,
+      navigator: navigatorStub,
+      storage
+    });
+
+    controller.setConfig({
+      bindings: {
+        gameplay: {
+          togglePause: ['button:0']
+        }
+      }
+    }, { persist: false });
+
+    expect(storage.getItem('lem-gamepad-bindings-v1')).to.equal(null);
+    expect(controller.getDisplayBindings('togglePause')).to.deep.equal(['A / Cross']);
+    controller.dispose();
+  });
+});
+
+describe('GamepadBindingRegistry', function () {
+  it('normalizes and exposes specs for gameplay/editor actions', function () {
+    const registry = new GamepadBindingRegistry({
+      version: 1,
+      bindings: {
+        gameplay: {
+          togglePause: ['button:9', 'axis:3:-:0.25']
+        },
+        editor: {
+          editorUndo: ['button:6']
+        }
+      }
+    });
+
+    const gameplay = registry.getBindingsForAction('gameplay', 'togglePause');
+    expect(gameplay).to.have.lengthOf(2);
+    expect(gameplay[0].kind).to.equal('button');
+    expect(gameplay[1].kind).to.equal('axis');
+
+    const compiledEditor = registry.getCompiledBindings('editor');
+    expect(compiledEditor.some(entry => entry.action === 'editorUndo')).to.equal(true);
+  });
+
+  it('merges config layers in default, file, persisted, session order', function () {
+    const merged = mergeGamepadConfigLayers(
+      { bindings: { gameplay: { togglePause: ['button:1'], restartLevel: ['button:2'] } } },
+      { bindings: { gameplay: { togglePause: ['button:3'] } } },
+      { bindings: { gameplay: { togglePause: ['button:4'] } } }
+    );
+
+    expect(merged.bindings.gameplay.togglePause).to.deep.equal(['button:4']);
+    expect(merged.bindings.gameplay.restartLevel).to.deep.equal(['button:2']);
+    expect(merged.bindings.gameplay.panLeft).to.deep.equal(['button:14', 'axis:0:-:0.35']);
+  });
+});
diff --git a/test/input/keyboard-shortcuts-coverage.test.js b/test/input/keyboard-shortcuts-coverage.01-keyboardshortcuts-coverage.test.js
similarity index 78%
rename from test/input/keyboard-shortcuts-coverage.test.js
rename to test/input/keyboard-shortcuts-coverage.01-keyboardshortcuts-coverage.test.js
index e10f9a33..0f62a6e1 100644
--- a/test/input/keyboard-shortcuts-coverage.test.js
+++ b/test/input/keyboard-shortcuts-coverage.01-keyboardshortcuts-coverage.test.js
@@ -409,110 +409,4 @@ describe('KeyboardShortcuts coverage', function() {
 
     shortcuts.dispose();
   });
-
-  it('loads keybindings when available', async function() {
-    const { view } = createFixture();
-    let requested = 0;
-    view.gameFactory = {
-      fileProvider: {
-        loadString() {
-          requested += 1;
-          return Promise.resolve(JSON.stringify({ version: 2, bindings: { toggleDebug: ['KeyZ'] } }));
-        }
-      }
-    };
-    const shortcuts = new KeyboardShortcuts(view);
-    await new Promise(resolve => setTimeout(resolve, 0));
-    expect(requested).to.equal(1);
-    expect(shortcuts.keybindings.config.version).to.equal(2);
-    shortcuts.dispose();
-  });
-
-  it('ignores invalid keybinding config payloads', async function() {
-    const { view } = createFixture();
-    view.gameFactory = {
-      fileProvider: {
-        loadString() {
-          return Promise.resolve('{bad');
-        }
-      }
-    };
-    const shortcuts = new KeyboardShortcuts(view);
-    await new Promise(resolve => setTimeout(resolve, 0));
-    expect(shortcuts.keybindings.config).to.be.ok;
-    shortcuts.dispose();
-  });
-
-  it('steps pan/zoom loop and handles blocked checks', function() {
-    const { view, timeTravel } = createFixture();
-    const shortcuts = new KeyboardShortcuts(view);
-    timeTravel.isReversing = true;
-    expect(shortcuts._isGameplayBlocked()).to.equal(true);
-    timeTravel.isReversing = false;
-    expect(shortcuts._isGameplayBlocked()).to.equal(false);
-
-    shortcuts.pan.right = true;
-    shortcuts.pan.changed = true;
-    shortcuts.zoom.dir = 1;
-    shortcuts._startLoop();
-    globals.rafCallbacks.shift()(16.666);
-
-    shortcuts.zoom.reset = view.stage.gameImgProps.viewPoint.scale;
-    shortcuts.pan.left = false;
-    shortcuts.pan.right = false;
-    shortcuts.pan.vx = 0;
-    shortcuts.pan.vy = 0;
-    shortcuts.zoom.dir = 0;
-    shortcuts._step(33.333);
-
-    view.stage = null;
-    shortcuts._step(50);
-
-    shortcuts.dispose();
-  });
-
-  it('resets zoom and formats display bindings', function() {
-    const globals = setupGlobals();
-    const { view } = createFixture();
-    const shortcuts = new KeyboardShortcuts(view);
-    shortcuts.keybindings.setConfig({
-      version: 1,
-      bindings: { toggleDebug: ['KeyZ'] }
-    });
-    const bindings = shortcuts.getDisplayBindings('toggleDebug');
-    expect(bindings.length).to.equal(1);
-
-    shortcuts.zoom.reset = view.stage.gameImgProps.viewPoint.scale;
-    shortcuts.zoom.v = 0;
-    shortcuts.zoom.dir = 0;
-    shortcuts._step(16.666);
-    expect(shortcuts.zoom.reset).to.equal(null);
-    expect(shortcuts.zoom.v).to.equal(0);
-
-    shortcuts.mod.shift = true;
-    shortcuts.zoom.dir = 1;
-    shortcuts._step(33.333);
-
-    shortcuts.zoom.dir = 0;
-    shortcuts.zoom.reset = null;
-    shortcuts.zoom.v = 0;
-    shortcuts._step(50);
-    shortcuts.dispose();
-    restoreGlobals(globals.originals);
-  });
-
-  it('handles keyup actions and level group fallbacks', function() {
-    const { view } = createFixture();
-    const shortcuts = new KeyboardShortcuts(view);
-    view.elementSelectLevelGroup = null;
-    view.selectLevelGroup = (idx) => { view.selected = idx; };
-    shortcuts._actions.levelGroupNext.down();
-    expect(view.selected).to.equal(1);
-
-    shortcuts.keybindings.getActionsForEvent = () => ['panLeft'];
-    let prevented = false;
-    shortcuts._onKeyUp({ preventDefault() { prevented = true; } });
-    expect(prevented).to.equal(true);
-    shortcuts.dispose();
-  });
 });
diff --git a/test/input/keyboard-shortcuts-coverage.02-keyboardshortcuts-coverage.test.js b/test/input/keyboard-shortcuts-coverage.02-keyboardshortcuts-coverage.test.js
new file mode 100644
index 00000000..f7ae84ea
--- /dev/null
+++ b/test/input/keyboard-shortcuts-coverage.02-keyboardshortcuts-coverage.test.js
@@ -0,0 +1,336 @@
+import { expect } from 'chai';
+import { KeyboardShortcuts } from '../../js/input/KeyboardShortcuts.js';
+import { SkillTypes } from '../../js/game/SkillTypes.js';
+import { LemmingStateType } from '../../js/lemmings/LemmingStateType.js';
+
+const setupGlobals = () => {
+  const originals = {
+    window: globalThis.window,
+    performance: globalThis.performance,
+    requestAnimationFrame: globalThis.requestAnimationFrame,
+    cancelAnimationFrame: globalThis.cancelAnimationFrame
+  };
+  const listeners = new Map();
+  const rafCallbacks = [];
+  let now = 0;
+  globalThis.window = {
+    addEventListener(type, handler) {
+      listeners.set(type, handler);
+    },
+    removeEventListener(type, handler) {
+      if (listeners.get(type) === handler) listeners.delete(type);
+    },
+    requestAnimationFrame(cb) {
+      return globalThis.requestAnimationFrame(cb);
+    },
+    cancelAnimationFrame(id) {
+      return globalThis.cancelAnimationFrame(id);
+    }
+  };
+  globalThis.performance = { now: () => now };
+  globalThis.requestAnimationFrame = (cb) => {
+    rafCallbacks.push(cb);
+    return rafCallbacks.length;
+  };
+  globalThis.cancelAnimationFrame = () => {};
+  return {
+    originals,
+    listeners,
+    rafCallbacks,
+    setNow(value) { now = value; }
+  };
+};
+
+const restoreGlobals = (originals) => {
+  globalThis.window = originals.window;
+  globalThis.performance = originals.performance;
+  globalThis.requestAnimationFrame = originals.requestAnimationFrame;
+  globalThis.cancelAnimationFrame = originals.cancelAnimationFrame;
+};
+
+const createFixture = () => {
+  const queue = [];
+  const gameGui = {
+    releaseRateChanged: false,
+    skillSelectionChanged: false,
+    gameTimeChanged: false,
+    drawSpeedChangeCalls: 0,
+    drawSpeedChange() { this.drawSpeedChangeCalls += 1; }
+  };
+  const timer = {
+    speedFactor: 1,
+    toggleCalls: 0,
+    toggle() { this.toggleCalls += 1; },
+    isRunning() { return false; }
+  };
+  const skills = {
+    selectedSkill: SkillTypes.CLIMBER,
+    getSelectedSkill() { return this.selectedSkill; }
+  };
+  const manager = {
+    lemmings: [],
+    actions: [],
+    getLemmings() { return this.lemmings; },
+    getSelectedLemming() { return { id: 7 }; },
+    setLemmingState(lem, state) {
+      lem.action = state;
+      this.setCalls = (this.setCalls || 0) + 1;
+    }
+  };
+  const vc = {
+    getCurrentReleaseRate: () => 5,
+    getMinReleaseRate: () => 1,
+    getMaxReleaseRate: () => 10
+  };
+  const timeTravel = {
+    isReversing: false,
+    toggleReverseCalls: 0,
+    stopReverseCalls: 0,
+    toggleReverse() { this.toggleReverseCalls += 1; },
+    stopReverse() { this.stopReverseCalls += 1; }
+  };
+  const game = {
+    timeTravel,
+    gameGui,
+    showDebug: false,
+    queueCommand(cmd) { queue.push(cmd); },
+    getGameTimer() { return timer; },
+    getGameSkills() { return skills; },
+    getLemmingManager() { return manager; },
+    getVictoryCondition() { return vc; }
+  };
+  const stage = {
+    gameImgProps: {
+      viewPoint: { x: 0, y: 0, scale: 1 },
+      canvasViewportSize: { width: 100, height: 50 }
+    },
+    _rawScale: 1,
+    redraws: 0,
+    applyViewport(img, x, y, rawScale) {
+      img.viewPoint.x = x;
+      img.viewPoint.y = y;
+      img.viewPoint.scale = this.snapScale(rawScale);
+    },
+    redraw() { this.redraws += 1; },
+    limitValue(min, value, max) {
+      return Math.min(max, Math.max(min, value));
+    },
+    snapScale(value) { return value; }
+  };
+  const view = {
+    game,
+    stage,
+    gameSpeedFactor: 1,
+    levelGroupIndex: 0,
+    gameType: 1,
+    elementSelectLevelGroup: { options: [1, 2, 3] },
+    gameResources: { getLevelGroups: () => [1, 2] },
+    moveToLevelCalls: [],
+    moveToLevel(idx) { this.moveToLevelCalls.push(idx); },
+    selectLevelGroupCalls: [],
+    selectLevelGroup(idx) { this.selectLevelGroupCalls.push(idx); },
+    selectGameTypeCalls: [],
+    selectGameType(idx) { this.selectGameTypeCalls.push(idx); },
+    nextFrameCalls: 0,
+    nextFrame() { this.nextFrameCalls += 1; },
+    prevFrameCalls: 0,
+    prevFrame() { this.prevFrameCalls += 1; },
+    toggleEditorModeCalls: 0,
+    toggleEditorMode() { this.toggleEditorModeCalls += 1; },
+    shortcutOverlay: { toggles: 0, toggle() { this.toggles += 1; } },
+    getMidiConfig() { return { reverse: { allNotesOffOnToggle: true } }; },
+    midiRouter: {
+      scheduler: {
+        allNotesOffCalls: 0,
+        clearQueueCalls: 0,
+        allNotesOff() { this.allNotesOffCalls += 1; },
+        clearQueue() { this.clearQueueCalls += 1; }
+      },
+      mapping: { config: { reverse: { allNotesOffOnToggle: true } } }
+    }
+  };
+
+  manager.actions[LemmingStateType.EXPLODING] = 'explode';
+  manager.actions[LemmingStateType.OHNO] = 'ohno';
+  manager.lemmings = [
+    { removed: true },
+    { removed: false, hasExploded: true },
+    { removed: false, hasExploded: false, countdownAction: {} },
+    { removed: false, hasExploded: false, countdownAction: null, action: 'explode' },
+    { removed: false, hasExploded: false, countdownAction: null, action: 'ohno' },
+    { removed: false, hasExploded: false, countdownAction: null, action: null }
+  ];
+
+  return { view, game, queue, timer, skills, manager, vc, timeTravel, gameGui, stage };
+};
+
+describe('KeyboardShortcuts coverage', function() {
+  let globals;
+
+  beforeEach(function() {
+    globals = setupGlobals();
+  });
+
+  afterEach(function() {
+    restoreGlobals(globals.originals);
+  });
+
+  it('supports speed adjustments when gameGui is unavailable', function() {
+    const { view, timer } = createFixture();
+    view.game.gameGui = null;
+    const shortcuts = new KeyboardShortcuts(view);
+    timer.speedFactor = 1;
+    shortcuts._isGameplayBlocked = () => false;
+    const actions = shortcuts._actions;
+
+    actions.speedUp.down();
+    expect(timer.speedFactor).to.equal(2);
+
+    actions.speedUpFast.down();
+    expect(timer.speedFactor).to.equal(7);
+
+    actions.speedDown.down();
+    expect(timer.speedFactor).to.equal(6);
+
+    actions.speedDownFast.down();
+    expect(timer.speedFactor).to.equal(1);
+    shortcuts.dispose();
+  });
+
+  it('ignores speed changes when game timer is unavailable', function() {
+    const { view } = createFixture();
+    view.game.getGameTimer = () => null;
+    const shortcuts = new KeyboardShortcuts(view);
+    shortcuts._isGameplayBlocked = () => false;
+    const actions = shortcuts._actions;
+
+    const before = view.gameSpeedFactor;
+    expect(() => actions.speedUp.down()).to.not.throw();
+    expect(() => actions.speedDown.down()).to.not.throw();
+    expect(view.gameSpeedFactor).to.equal(before);
+    shortcuts.dispose();
+  });
+
+  it('loads keybindings when available', async function() {
+    const { view } = createFixture();
+    const requested = [];
+    view.gameFactory = {
+      fileProvider: {
+        loadString(name) {
+          requested.push(name);
+          return Promise.resolve(JSON.stringify({ version: 2, bindings: { toggleDebug: ['KeyZ'] } }));
+        }
+      }
+    };
+    const shortcuts = new KeyboardShortcuts(view);
+    await new Promise(resolve => setTimeout(resolve, 0));
+    expect(requested).to.include('keybindings.json');
+    expect(requested).to.include('gamepadbindings.json');
+    expect(shortcuts.keybindings.config.version).to.equal(2);
+    shortcuts.dispose();
+  });
+
+  it('ignores invalid keybinding config payloads', async function() {
+    const { view } = createFixture();
+    view.gameFactory = {
+      fileProvider: {
+        loadString() {
+          return Promise.resolve('{bad');
+        }
+      }
+    };
+    const shortcuts = new KeyboardShortcuts(view);
+    await new Promise(resolve => setTimeout(resolve, 0));
+    expect(shortcuts.keybindings.config).to.be.ok;
+    shortcuts.dispose();
+  });
+
+  it('steps pan/zoom loop and handles blocked checks', function() {
+    const { view, timeTravel } = createFixture();
+    const shortcuts = new KeyboardShortcuts(view);
+    timeTravel.isReversing = true;
+    expect(shortcuts._isGameplayBlocked()).to.equal(true);
+    timeTravel.isReversing = false;
+    expect(shortcuts._isGameplayBlocked()).to.equal(false);
+
+    shortcuts.pan.right = true;
+    shortcuts.pan.changed = true;
+    shortcuts.zoom.dir = 1;
+    shortcuts._startLoop();
+    globals.rafCallbacks.shift()(16.666);
+
+    shortcuts.zoom.reset = view.stage.gameImgProps.viewPoint.scale;
+    shortcuts.pan.left = false;
+    shortcuts.pan.right = false;
+    shortcuts.pan.vx = 0;
+    shortcuts.pan.vy = 0;
+    shortcuts.zoom.dir = 0;
+    shortcuts._step(33.333);
+
+    view.stage = null;
+    shortcuts._step(50);
+
+    shortcuts.dispose();
+  });
+
+  it('keeps zoom input active when the first frame has no elapsed time', function() {
+    const { view } = createFixture();
+    const shortcuts = new KeyboardShortcuts(view);
+    shortcuts.zoom.dir = 1;
+    shortcuts._startLoop();
+
+    const firstFrame = globals.rafCallbacks.shift();
+    firstFrame(0);
+    expect(view.stage.redraws).to.equal(0);
+    expect(globals.rafCallbacks).to.have.lengthOf(1);
+
+    globals.rafCallbacks.shift()(16.666);
+    expect(view.stage.redraws).to.be.greaterThan(0);
+    shortcuts.dispose();
+  });
+
+  it('resets zoom and formats display bindings', function() {
+    const globals = setupGlobals();
+    const { view } = createFixture();
+    const shortcuts = new KeyboardShortcuts(view);
+    shortcuts.keybindings.setConfig({
+      version: 1,
+      bindings: { toggleDebug: ['KeyZ'] }
+    });
+    const bindings = shortcuts.getDisplayBindings('toggleDebug');
+    expect(bindings.length).to.equal(1);
+
+    shortcuts.zoom.reset = view.stage.gameImgProps.viewPoint.scale;
+    shortcuts.zoom.v = 0;
+    shortcuts.zoom.dir = 0;
+    shortcuts._step(16.666);
+    expect(shortcuts.zoom.reset).to.equal(null);
+    expect(shortcuts.zoom.v).to.equal(0);
+
+    shortcuts.mod.shift = true;
+    shortcuts.zoom.dir = 1;
+    shortcuts._step(33.333);
+
+    shortcuts.zoom.dir = 0;
+    shortcuts.zoom.reset = null;
+    shortcuts.zoom.v = 0;
+    shortcuts._step(50);
+    shortcuts.dispose();
+    restoreGlobals(globals.originals);
+  });
+
+  it('handles keyup actions and level group fallbacks', function() {
+    const { view } = createFixture();
+    const shortcuts = new KeyboardShortcuts(view);
+    view.elementSelectLevelGroup = null;
+    view.selectLevelGroup = (idx) => { view.selected = idx; };
+    shortcuts._actions.levelGroupNext.down();
+    expect(view.selected).to.equal(1);
+
+    shortcuts.keybindings.getActionsForEvent = () => ['panLeft'];
+    let prevented = false;
+    shortcuts._onKeyUp({ preventDefault() { prevented = true; } });
+    expect(prevented).to.equal(true);
+    shortcuts.dispose();
+  });
+});
diff --git a/test/input/keyboard-shortcuts.test.js b/test/input/keyboard-shortcuts.test.js
index 2fcc239c..9872c66a 100644
--- a/test/input/keyboard-shortcuts.test.js
+++ b/test/input/keyboard-shortcuts.test.js
@@ -81,4 +81,54 @@ describe('KeyboardShortcuts', function() {
       globalThis.performance = originalPerformance;
     }
   });
+
+  it('uses injected browser references for listeners and animation frames', function() {
+    const listeners = new Map();
+    let rafCallback = null;
+    let canceled = null;
+    const windowRef = {
+      addEventListener(type, handler) {
+        listeners.set(type, handler);
+      },
+      removeEventListener(type, handler) {
+        if (listeners.get(type) === handler) listeners.delete(type);
+      }
+    };
+    const shortcuts = new KeyboardShortcuts({
+      stage: {
+        gameImgProps: {
+          viewPoint: { x: 0, y: 0, scale: 1 },
+          canvasViewportSize: { width: 100, height: 100 }
+        },
+        _rawScale: 1,
+        applyViewport() {},
+        redraw() {},
+        limitValue(min, value, max) {
+          return Math.max(min, Math.min(max, value));
+        },
+        snapScale(value) {
+          return value;
+        }
+      }
+    }, {
+      window: windowRef,
+      performance: { now: () => 0 },
+      requestAnimationFrame(callback) {
+        rafCallback = callback;
+        return 7;
+      },
+      cancelAnimationFrame(id) {
+        canceled = id;
+      },
+      navigator: { getGamepads: () => [] },
+      storage: null
+    });
+
+    expect(listeners.has('keydown')).to.equal(true);
+    shortcuts._actions.panRight.down();
+    expect(rafCallback).to.be.a('function');
+    shortcuts.dispose();
+    expect(canceled).to.equal(7);
+    expect(listeners.size).to.equal(0);
+  });
 });
diff --git a/test/input/user-input-manager.test.js b/test/input/user-input-manager.test.js
index 880c0784..9fe8f28a 100644
--- a/test/input/user-input-manager.test.js
+++ b/test/input/user-input-manager.test.js
@@ -5,22 +5,28 @@ import { Position2D } from '../../js/util/Position2D.js';
 
 const makeElement = () => {
   const listeners = new Map();
+  const optionsByType = new Map();
   return {
     width: 100,
     height: 100,
     style: {},
-    addEventListener(type, handler) {
+    addEventListener(type, handler, options) {
       listeners.set(type, handler);
+      optionsByType.set(type, options);
     },
-    removeEventListener(type, handler) {
+    removeEventListener(type, handler, options) {
       if (listeners.get(type) === handler) {
         listeners.delete(type);
       }
+      if (optionsByType.get(type) === options) {
+        optionsByType.delete(type);
+      }
     },
     getBoundingClientRect() {
       return { left: 0, top: 0, width: 100, height: 100 };
     },
-    _listeners: listeners
+    _listeners: listeners,
+    _listenerOptions: optionsByType
   };
 };
 
@@ -75,6 +81,19 @@ describe('UserInputManager', function() {
     element._listeners.get('wheel')(makeEvent({ clientX: 2, clientY: 3, deltaY: 5 }));
   });
 
+  it('prevents native context menu events on the canvas surface', function () {
+    const element = makeElement();
+    new UserInputManager(element);
+    let prevented = false;
+    let stopped = false;
+    element._listeners.get('contextmenu')({
+      preventDefault() { prevented = true; },
+      stopPropagation() { stopped = true; }
+    });
+    expect(prevented).to.equal(true);
+    expect(stopped).to.equal(true);
+  });
+
   it('handles touch gestures and cleanup', function() {
     const element = makeElement();
     const manager = new UserInputManager(element);
@@ -105,28 +124,87 @@ describe('UserInputManager', function() {
     expect(zoomEvents.length).to.be.greaterThan(0);
   });
 
-  it('handles wheel zoom with and without stage targets', function() {
+  it('handles wheel zoom via onZoom without directly mutating stage view', function() {
     const element = makeElement();
     const manager = new UserInputManager(element);
     const zoomEvents = [];
     manager.onZoom.on((evt) => zoomEvents.push(evt));
 
-    const stageImage = { display: { worldDataSize: { width: 1600 } } };
+    const stageImage = { display: { worldDataSize: { width: 3000 } } };
+    let updateCalls = 0;
     const stage = {
+      gameImgProps: stageImage,
       getStageImageAt() { return stageImage; },
-      updateViewPoint() { stage.updated = true; }
+      updateViewPoint() { updateCalls += 1; }
     };
     withGlobalLemmings({ stage }, () => {
       manager.handleWheel(new Position2D(5, 5), 1);
-      expect(stage.updated).to.equal(true);
+      expect(updateCalls).to.equal(0);
 
       stage.getStageImageAt = () => null;
       manager.handleWheel(new Position2D(5, 5), 1);
       expect(zoomEvents.length).to.equal(2);
+      expect(updateCalls).to.equal(0);
     });
 
     manager.handleWheel(new Position2D(5, 5), 1);
     expect(zoomEvents.length).to.equal(3);
+    expect(updateCalls).to.equal(0);
+  });
+
+  it('configures passive listener options for touch and wheel events', function() {
+    const element = makeElement();
+    new UserInputManager(element);
+    expect(element._listenerOptions.get('touchmove')).to.deep.equal({ passive: false });
+    expect(element._listenerOptions.get('touchstart')).to.deep.equal({ passive: false });
+    expect(element._listenerOptions.get('wheel')).to.deep.equal({ passive: false });
+    expect(element._listenerOptions.get('mousemove')).to.deep.equal({ passive: true });
+    expect(element._listenerOptions.get('mouseleave')).to.deep.equal({ passive: true });
+  });
+
+  it('uses fallback zoom event path when stage omits getStageImageAt', function() {
+    const element = makeElement();
+    const manager = new UserInputManager(element);
+    const zoomEvents = [];
+    manager.onZoom.on((evt) => zoomEvents.push(evt));
+    withGlobalLemmings({ stage: {} }, () => {
+      manager.handleWheel(new Position2D(4, 6), -2);
+    });
+    expect(zoomEvents).to.have.lengthOf(1);
+    expect(zoomEvents[0].deltaZoom).to.equal(-2);
+  });
+
+  it('scales relative positions from canvas space', function() {
+    const element = makeElement();
+    element.width = 200;
+    element.height = 300;
+    element.getBoundingClientRect = () => ({ left: 10, top: 20, width: 100, height: 150 });
+    const manager = new UserInputManager(element);
+
+    const point = manager.getRelativePosition(element, 60, 95);
+    expect(point.x).to.equal(100);
+    expect(point.y).to.equal(150);
+  });
+
+  it('keeps relative position finite when canvas or rect dimensions are zero', function() {
+    const element = makeElement();
+    element.width = 0;
+    element.height = 0;
+    element.getBoundingClientRect = () => ({ left: 10, top: 20, width: 0, height: 0 });
+    const manager = new UserInputManager(element);
+
+    const point = manager.getRelativePosition(element, 60, 95);
+    expect(Number.isFinite(point.x)).to.equal(true);
+    expect(Number.isFinite(point.y)).to.equal(true);
+    expect(point.x).to.equal(50);
+    expect(point.y).to.equal(75);
+  });
+
+  it('uses safe defaults when the element does not expose bounding rect APIs', function() {
+    const manager = new UserInputManager(makeElement());
+    const point = manager.getRelativePosition({}, 12, 34);
+    expect(point.x).to.equal(12);
+    expect(point.y).to.equal(34);
   });
 
   it('disposes listeners safely', function() {
diff --git a/test/lemming.boundary.test.js b/test/lemming.boundary.test.js
index 8242f57b..656b37b0 100644
--- a/test/lemming.boundary.test.js
+++ b/test/lemming.boundary.test.js
@@ -1,13 +1,9 @@
 import { expect } from 'chai';
-import { Lemmings, useGlobalLemmings } from './helpers/lemmings.js';
+import { Lemmings } from './helpers/lemmings.js';
 import '../js/lemmings/LemmingStateType.js';
 import { Lemming } from '../js/lemmings/Lemming.js';
 
 describe('Lemming state boundary checks', function () {
-  useGlobalLemmings({
-    game: { lemmingManager: { miniMap: { calls: [], addDeath(...a) { this.calls.push(a); } } } }
-  });
-
   it('renderDebug sets pixel only with action', function () {
     const lem = new Lemming(4, 8);
     const calls = [];
@@ -23,12 +19,13 @@ describe('Lemming state boundary checks', function () {
 
   it('process clamps bottom death position', function () {
     const level = { width: 20, height: 10 };
-    const lem = new Lemming(3, 27);
+    const miniMap = { calls: [], addDeath(...a) { this.calls.push(a); } };
+    const lem = new Lemming(3, 27, undefined, { miniMap });
     lem.action = { process() { return Lemmings.LemmingStateType.WALKING; } };
 
     const res = lem.process(level);
     expect(res).to.equal(Lemmings.LemmingStateType.OUT_OF_LEVEL);
-    expect(globalThis.lemmings.game.lemmingManager.miniMap.calls[0]).to.deep.equal([3, 4]);
+    expect(miniMap.calls[0]).to.deep.equal([3, 4]);
   });
 
   it('process returns whatever the action provides', function () {
diff --git a/test/lemming.core.test.js b/test/lemming.core.test.js
index 37abcf6e..86bb2116 100644
--- a/test/lemming.core.test.js
+++ b/test/lemming.core.test.js
@@ -1,5 +1,4 @@
 import { expect } from 'chai';
-import { withGlobalLemmings } from './helpers/lemmings.js';
 import { Lemming } from '../js/lemmings/Lemming.js';
 import { LemmingStateType } from '../js/lemmings/LemmingStateType.js';
 import { SoundEventTypes } from '../js/game/SoundEvents.js';
@@ -25,22 +24,19 @@ describe('Lemming core', function() {
 
   it('processes out-of-level and missing action states', function() {
     const events = [];
-    withGlobalLemmings({
-      game: {
-        soundEvents: { emitSfx(type, id, payload) { events.push({ type, id, payload }); } },
-        lemmingManager: { miniMap: { addDeath() { events.push({ type: 'death' }); } } }
-      }
-    }, () => {
-      const lem = new Lemming(-1, 5, 2);
-      const state = lem.process(makeLevel());
-      expect(state).to.equal(LemmingStateType.OUT_OF_LEVEL);
-      expect(events.some(e => e.type === SoundEventTypes.LEMMING_FELL_OFF)).to.equal(true);
+    const runtime = {
+      soundEvents: { emitSfx(type, id, payload) { events.push({ type, id, payload }); } },
+      miniMap: { addDeath() { events.push({ type: 'death' }); } }
+    };
+    const lem = new Lemming(-1, 5, 2, runtime);
+    const state = lem.process(makeLevel());
+    expect(state).to.equal(LemmingStateType.OUT_OF_LEVEL);
+    expect(events.some(e => e.type === SoundEventTypes.LEMMING_FELL_OFF)).to.equal(true);
 
-      const lem2 = new Lemming(1, 1, 3);
-      const state2 = lem2.process(makeLevel());
-      expect(state2).to.equal(LemmingStateType.OUT_OF_LEVEL);
-      expect(events.some(e => e.type === 'death')).to.equal(true);
-    });
+    const lem2 = new Lemming(1, 1, 3, runtime);
+    const state2 = lem2.process(makeLevel());
+    expect(state2).to.equal(LemmingStateType.OUT_OF_LEVEL);
+    expect(events.some(e => e.type === 'death')).to.equal(true);
   });
 
   it('processes countdown actions and main actions', function() {
diff --git a/test/lemmingmanager.coverage.test.js b/test/lemmingmanager.coverage.test.js
index 1a782773..58a82c37 100644
--- a/test/lemmingmanager.coverage.test.js
+++ b/test/lemmingmanager.coverage.test.js
@@ -101,7 +101,7 @@ describe('LemmingManager coverage', function() {
     manager.miniMap = {
       scaleX: 1,
       scaleY: 1,
-      setLiveDots(arr) { this.dots = arr; },
+      setLiveDots(arr, activeLength = arr.length) { this.dots = arr.slice(0, activeLength); },
       setSelectedDot(dot) { this.sel = dot; }
     };
     const makeLem = (id) => ({
@@ -147,7 +147,7 @@ describe('LemmingManager coverage', function() {
     const { manager, gvc } = makeManager();
     let called = 0;
     globalThis.lemmings.endless = true;
-    globalThis.lemmings.game.soundEvents = { emitSfx() { called++; } };
+    manager.runtime = { soundEvents: { emitSfx() { called++; } } };
     manager.releaseTickIndex = 4;
     manager.addNewLemmings();
     expect(manager.lemmings.length).to.equal(1);
@@ -217,6 +217,8 @@ describe('LemmingManager coverage', function() {
       [TriggerTypes.EXIT_LEVEL, LemmingStateType.EXITING],
       [TriggerTypes.KILL, LemmingStateType.SPLATTING],
       [TriggerTypes.FRYING, LemmingStateType.FRYING],
+      [TriggerTypes.UNKNOWN_2, LemmingStateType.SPLATTING],
+      [TriggerTypes.UNKNOWN_3, LemmingStateType.SPLATTING],
       [TriggerTypes.TRAP, LemmingStateType.SPLATTING]
     ];
     for (const [triggerType, expected] of cases) {
@@ -240,11 +242,10 @@ describe('LemmingManager coverage', function() {
     expect(manager.lemmings[0].custom).to.equal(true);
   });
 
-  it('uses the default lemming constructor by default', function() {
+  it('requires an explicit lemming constructor', function() {
     const { manager } = makeManager();
     manager._lemmingCtor = null;
-    manager.addLemming(1, 1);
-    expect(manager.lemmings[0]).to.be.instanceOf(Lemming);
+    expect(() => manager.addLemming(1, 1)).to.throw(/explicit lemming constructor/);
   });
 
   it('ticks with minimap updates and compacts active list', function() {
@@ -299,7 +300,7 @@ describe('LemmingManager coverage', function() {
     manager.miniMap = {
       scaleX: 1,
       scaleY: 1,
-      setLiveDots(arr) { this.dots = arr; },
+      setLiveDots(arr, activeLength = arr.length) { this.dots = arr.slice(0, activeLength); },
       setSelectedDot(dot) { this.sel = dot; }
     };
     manager.mmTickCounter = 9;
diff --git a/test/lemmingmanager.test.js b/test/lemmingmanager.test.js
index 8e305d6f..bddfc833 100644
--- a/test/lemmingmanager.test.js
+++ b/test/lemmingmanager.test.js
@@ -12,7 +12,7 @@ import '../js/LemmingsBootstrap.js';
 const makeMiniMap = (overrides = {}) => ({
   scaleX: 1,
   scaleY: 1,
-  setLiveDots(arr) { this.dots = arr; },
+  setLiveDots(arr, activeLength = arr.length) { this.dots = arr.slice(0, activeLength); },
   setSelectedDot() {},
   ...overrides
 });
@@ -115,6 +115,54 @@ describe('LemmingManager core behavior', function() {
     expect(mm.dots.length).to.equal(2);
   });
 
+  it('refreshes minimap dots down to an empty active set', function() {
+    const { manager } = makeManager({ width: 40, height: 40 });
+    const mm = makeMiniMap();
+    manager.setMiniMap(mm);
+    manager.addLemming(10, 10);
+    manager.refreshMiniMapDots();
+    expect(mm.dots.length).to.equal(2);
+
+    manager.lemmings.length = 0;
+    manager.activeLemmings.length = 0;
+    manager.refreshMiniMapDots();
+    expect(mm.dots.length).to.equal(0);
+  });
+
+  it('processes super lemmings twice per tick', function() {
+    const { manager } = makeManager({
+      width: 40,
+      height: 40,
+      levelInit(level) { level.isSuperLemming = true; }
+    });
+    manager.addLemming(10, 10);
+    const lem = manager.lemmings[0];
+    let processCalls = 0;
+    lem.process = () => {
+      processCalls += 1;
+      return Lemmings.LemmingStateType.NO_STATE_TYPE;
+    };
+
+    manager.tick();
+
+    expect(processCalls).to.equal(2);
+  });
+
+  it('processes non-super lemmings once per tick', function() {
+    const { manager } = makeManager({ width: 40, height: 40 });
+    manager.addLemming(10, 10);
+    const lem = manager.lemmings[0];
+    let processCalls = 0;
+    lem.process = () => {
+      processCalls += 1;
+      return Lemmings.LemmingStateType.NO_STATE_TYPE;
+    };
+
+    manager.tick();
+
+    expect(processCalls).to.equal(1);
+  });
+
   it('spawns and removes lemmings mid-level', function() {
     const { manager, gvc } = makeManager({ width: 50, height: 50, releaseCount: 1 });
 
@@ -162,6 +210,34 @@ describe('LemmingManager core behavior', function() {
     expect(nearest).to.equal(lem3);
   });
 
+  it('reuses pooled lemming instances with reset state', function() {
+    const { manager } = makeManager({ width: 40, height: 40 });
+    manager.addLemming(6, 6);
+    const first = manager.lemmings[0];
+    first.disable();
+    first.hasParachute = true;
+    first.canClimb = true;
+    first.countdown = 9;
+    first.lastTriggerType = TriggerTypes.KILL;
+    first.lookRight = false;
+
+    manager.removeOne(first);
+    manager.addLemming(12, 14);
+    const reused = manager.lemmings[1];
+
+    expect(reused).to.equal(first);
+    expect(reused.id).to.equal(1);
+    expect(reused.x).to.equal(12);
+    expect(reused.y).to.equal(14);
+    expect(reused.removed).to.equal(false);
+    expect(reused.disabled).to.equal(false);
+    expect(reused.countdown).to.equal(0);
+    expect(reused.canClimb).to.equal(false);
+    expect(reused.hasParachute).to.equal(false);
+    expect(reused.lastTriggerType).to.equal(null);
+    expect(reused.lookRight).to.equal(true);
+  });
+
   it('cycleSelection skips removed and disabled lemmings', function() {
     const { manager } = makeManager({ width: 20, height: 20 });
 
@@ -224,7 +300,7 @@ describe('LemmingManager additional', function() {
     const lem = manager.lemmings[0];
     manager.setLemmingState(lem, Lemmings.LemmingStateType.BLOCKING);
     let removed=false; manager.triggerManager.removeByOwner=()=>{removed=true;};
-    const ok = manager.doLemmingAction(lem, Lemmings.SkillTypes.DIGGER);        
+    const ok = manager.doLemmingAction(lem, Lemmings.SkillTypes.DIGGER);
     expect(ok).to.be.true;
     expect(removed).to.be.true;
   });
@@ -251,6 +327,16 @@ describe('LemmingManager triggers and nuking', function() {
     expect(state).to.equal(Lemmings.LemmingStateType.SPLATTING);
     expect(lem.lastTriggerType).to.equal(TriggerTypes.TRAP);
 
+    manager.triggerManager.trigger = () => TriggerTypes.UNKNOWN_2;
+    state = manager.runTrigger(lem);
+    expect(state).to.equal(Lemmings.LemmingStateType.SPLATTING);
+    expect(lem.lastTriggerType).to.equal(TriggerTypes.UNKNOWN_2);
+
+    manager.triggerManager.trigger = () => TriggerTypes.UNKNOWN_3;
+    state = manager.runTrigger(lem);
+    expect(state).to.equal(Lemmings.LemmingStateType.SPLATTING);
+    expect(lem.lastTriggerType).to.equal(TriggerTypes.UNKNOWN_3);
+
     manager.triggerManager.trigger = () => TriggerTypes.EXIT_LEVEL;
     state = manager.runTrigger(lem);
     expect(state).to.equal(Lemmings.LemmingStateType.EXITING);
@@ -288,7 +374,7 @@ describe('LemmingManager triggers and nuking', function() {
     expect(logs[0]).to.match(/unknown trigger type/i);
   });
 
-  it('nuking skips disabled targets and ends when applied', function() {        
+  it('nuking skips disabled targets and ends when applied', function() {
     const { manager } = makeManager();
     manager.addLemming(1, 1);
     manager.addLemming(2, 2);
@@ -322,7 +408,7 @@ describe('LemmingManager triggers and nuking', function() {
     expect(manager._nukeTargets).to.equal(null);
   });
 
-  it('clears nuke targets when index jumps beyond count', function() {     
+  it('clears nuke targets when index jumps beyond count', function() {
     const { manager } = makeManager();
     manager._nukeTargets = [{ id: 1 }];
     let calls = 0;
diff --git a/test/level.extra.test.js b/test/level.extra.test.js
index 268b5bf8..c20746cd 100644
--- a/test/level.extra.test.js
+++ b/test/level.extra.test.js
@@ -185,4 +185,33 @@ describe('Level extra coverage', function() {
       expect(level.hasGroundAt(2, 2)).to.equal(true);
     });
   });
+
+  it('rewrites fire-shooter trap ids to frying across known object ids', function() {
+    const palette = makePalette();
+    const triggerIds = [7, 8, 10];
+
+    for (const objectId of triggerIds) {
+      const level = new Level(4, 4);
+      level.setPalettes(palette, palette);
+      level.setGroundImage(new Uint8ClampedArray(4 * 4 * 4));
+      const objectImg = [];
+      objectImg[objectId] = {
+        width: 1,
+        height: 1,
+        frames: [Uint8Array.from([0])],
+        palette,
+        animationLoop: true,
+        firstFrameIndex: 0,
+        frameCount: 1,
+        trigger_effect_id: 6,
+        trigger_left: 0,
+        trigger_top: 0,
+        trigger_width: 1,
+        trigger_height: 1,
+        trap_sound_effect_id: 1
+      };
+      level.setMapObjects([{ id: objectId, x: 1, y: 1, drawProperties: {} }], objectImg);
+      expect(level.objects[0].triggerType).to.equal(12);
+    }
+  });
 });
diff --git a/test/level.ground.test.js b/test/level.ground.test.js
index 553c91a2..46eb0955 100644
--- a/test/level.ground.test.js
+++ b/test/level.ground.test.js
@@ -6,6 +6,11 @@ import '../js/render/ColorPalette.js';
 // minimal global env for logging
 const miniMapStub = { onGroundChanged() {} };
 
+const setRuntime = (level, runtime) => {
+  level.setRuntime?.(runtime);
+  return level;
+};
+
 describe('Level ground operations', function() {
   let restore;
   beforeEach(function() {
@@ -32,7 +37,7 @@ describe('Level ground operations', function() {
     expect(Array.from(level.groundImage.slice(idx, idx + 3))).to.eql([0, 0, 0]);
   });
 
-  it('clears ground with masks while skipping steel and bounds', function() {   
+  it('clears ground with masks while skipping steel and bounds', function() {
     const level = new Level(3, 3);
     const palette = new Lemmings.ColorPalette();
     palette.setColorRGB(1, 10, 20, 30);
@@ -56,12 +61,67 @@ describe('Level ground operations', function() {
     expect(result.removed).to.be.greaterThan(0);
   });
 
+  it('invalidates minimap bounds when masked clears modify terrain', function() {
+    const invalidateCalls = [];
+    const miniMap = {
+      onGroundChanged() {},
+      invalidateRegion(...args) { invalidateCalls.push(args); }
+    };
+
+    const level = setRuntime(new Level(3, 3), { miniMap });
+    const palette = new Lemmings.ColorPalette();
+    palette.setColorRGB(1, 10, 20, 30);
+    level.setGroundImage(new Uint8ClampedArray(3 * 3 * 4));
+    level.setPalettes(palette, palette);
+    level.setGroundAt(1, 1, 1);
+
+    const mask = {
+      offsetX: 0,
+      offsetY: 0,
+      width: 1,
+      height: 1,
+      at() { return false; }
+    };
+    level.clearGroundWithMask(mask, 1, 1);
+
+    expect(invalidateCalls).to.eql([[1, 1, 1, 1]]);
+  });
+
+  it('reveals steel terrain on demand without clearing the steel mask', function() {
+    const level = new Level(2, 2);
+    const palette = new Lemmings.ColorPalette();
+    palette.setColorRGB(1, 10, 20, 30);
+    level.setGroundImage(new Uint8ClampedArray(2 * 2 * 4));
+    level.setPalettes(palette, palette);
+
+    level.setGroundAt(0, 0, 1);
+    level.steelMask.setMaskAt(0, 0);
+
+    const mask = {
+      offsetX: 0,
+      offsetY: 0,
+      width: 1,
+      height: 1,
+      at() { return false; }
+    };
+
+    const unchanged = level._clearGroundWithMaskInternal(mask, 0, 0);
+    expect(unchanged.changed).to.equal(false);
+    expect(level.hasGroundAt(0, 0)).to.equal(true);
+    expect(Array.from(level.groundImage.slice(0, 3))).to.eql([10, 20, 30]);
+
+    const revealed = level._clearGroundWithMaskInternal(mask, 0, 0, { revealSteel: true });
+    expect(revealed.changed).to.equal(true);
+    expect(level.hasGroundAt(0, 0)).to.equal(true);
+    expect(Array.from(level.groundImage.slice(0, 3))).to.eql([0, 0, 0]);
+  });
+
   it('records ground changes when history is available', function() {
     const calls = [];
-    globalThis.lemmings.game.history = {
+    const history = {
       recordGroundChange(...args) { calls.push(args); }
     };
-    const level = new Level(1, 1);
+    const level = setRuntime(new Level(1, 1), { history });
     const palette = new Lemmings.ColorPalette();
     palette.setColorRGB(1, 10, 20, 30);
     level.setGroundImage(new Uint8ClampedArray(1 * 1 * 4));
@@ -80,4 +140,27 @@ describe('Level ground operations', function() {
 
     expect(calls.length).to.equal(3);
   });
+
+  it('writes rectangular terrain in bulk and invalidates minimap region once', function() {
+    const invalidateCalls = [];
+    const miniMap = {
+      onGroundChanged() {},
+      invalidateRegion(...args) { invalidateCalls.push(args); }
+    };
+    const level = setRuntime(new Level(4, 4), { miniMap });
+    const palette = new Lemmings.ColorPalette();
+    palette.setColorRGB(1, 10, 20, 30);
+    level.setGroundImage(new Uint8ClampedArray(4 * 4 * 4));
+    level.setPalettes(palette, palette);
+
+    const changed = level.setGroundRect(1, 1, 2, 2, 1, {
+      recordHistory: false,
+      invalidateMiniMap: true
+    });
+
+    expect(changed).to.equal(4);
+    expect(level.hasGroundAt(1, 1)).to.equal(true);
+    expect(level.hasGroundAt(2, 2)).to.equal(true);
+    expect(invalidateCalls).to.eql([[1, 1, 2, 2]]);
+  });
 });
diff --git a/test/level.newsetsteelareas.test.js b/test/level.newsetsteelareas.test.js
index 4484322a..b15e31a1 100644
--- a/test/level.newsetsteelareas.test.js
+++ b/test/level.newsetsteelareas.test.js
@@ -28,4 +28,21 @@ describe('Level.newSetSteelAreas', function() {
     expect(Array.from(level.steelRanges)).to.eql([0, 0, 1, 1]);
     expect(level.steelMask.hasMaskAt(0, 0)).to.equal(true);
   });
+
+  it('records each steel terrain range once even when multiple pixels match', function() {
+    const level = new Level(4, 4);
+    const pal = new Lemmings.ColorPalette();
+    level.setGroundImage(new Uint8ClampedArray(4 * 4 * 4));
+    level.setPalettes(pal, pal);
+    level.setSteelAreas([Object.assign(new Range(), { x: 0, y: 0, width: 2, height: 2 })]);
+
+    const levelReader = { levelWidth: 4, levelHeight: 4, terrains: [{ id: 1, x: 0, y: 0 }] };
+    const terrainImages = { 1: { isSteel: true, steelWidth: 2, steelHeight: 2, width: 2, height: 2 } };
+
+    level.newSetSteelAreas(levelReader, terrainImages);
+
+    expect(Array.from(level.steelRanges)).to.eql([0, 0, 2, 2]);
+    expect(level.steelMask.hasMaskAt(0, 0)).to.equal(true);
+    expect(level.steelMask.hasMaskAt(1, 1)).to.equal(true);
+  });
 });
diff --git a/test/level.render.test.js b/test/level.render.test.js
index be153a6f..03816e0c 100644
--- a/test/level.render.test.js
+++ b/test/level.render.test.js
@@ -31,4 +31,39 @@ describe('Level render', function() {
     expect(calls[1][1]).to.equal(level.groundImage);
     expect(calls[1][2]).to.equal(level.groundMask);
   });
+
+  it('syncs cached backgrounds and only pushes terrain deltas', function() {
+    const level = new Level(4, 4);
+    const pal = new Lemmings.ColorPalette();
+    level.setGroundImage(new Uint8ClampedArray(4 * 4 * 4));
+    level.setPalettes(pal, pal);
+
+    const syncCalls = [];
+    let hasBackground = false;
+    const gd = {
+      initSize() {},
+      restoreBackground() {},
+      hasBackground() { return hasBackground; },
+      syncBackground(img, mask, dirtyRects, tileSize) {
+        syncCalls.push([img, mask, dirtyRects, tileSize]);
+        hasBackground = true;
+      }
+    };
+
+    level.render(gd);
+    level.render(gd);
+    level.setGroundAt(1, 1, 7);
+    level.render(gd);
+
+    expect(syncCalls.length).to.equal(2);
+    expect(syncCalls[0][2]).to.equal(null);
+    expect(syncCalls[0][3]).to.equal(64);
+    const deltaRects = syncCalls[1][2];
+    expect(deltaRects === null || Array.isArray(deltaRects)).to.equal(true);
+    if (Array.isArray(deltaRects)) {
+      expect(deltaRects.length).to.equal(1);
+    }
+    expect(syncCalls[1][3]).to.equal(64);
+    expect(gd.groundMask).to.equal(level.groundMask);
+  });
 });
diff --git a/test/levelloader.test.js b/test/levelloader.test.js
index 0cb69498..0d6e4174 100644
--- a/test/levelloader.test.js
+++ b/test/levelloader.test.js
@@ -45,13 +45,24 @@ const expectLevelProperties = (level, props) => {
   expect(level.skills).to.deep.equal(props.skills);
 };
 
+const countMaskPixels = (mask) => {
+  if (!mask || !Array.isArray(mask) && !mask.length) return 0;
+  let count = 0;
+  for (let i = 0; i < mask.length; i += 1) {
+    if (mask[i]) count += 1;
+  }
+  return count;
+};
+
 const makeProvider = (oddLoader) => class Provider {
   loadBinary(path, file) {
     if (file === 'ODDTABLE.DAT' && oddLoader) {
       return oddLoader();
     }
     const data = readFileSync(new URL(`../${path}/${file}`, import.meta.url));
-    return Promise.resolve(new Lemmings.BinaryReader(new Uint8Array(data)));
+    return Promise.resolve(
+      new Lemmings.BinaryReader(new Uint8Array(data), 0, data.length, file, path)
+    );
   }
 };
 
@@ -210,4 +221,68 @@ describe('LevelLoader', function () {
     expect(mergedNoSkills.skills).to.eql([5, 6]);
   });
 
+  it('falls back to seasonal resource packs when local terrain files are missing', async function () {
+    const calls = [];
+    class Provider {
+      loadBinary(path, file) {
+        calls.push(`${path}/${file}`);
+        const data = readFileSync(new URL(`../${path}/${file}`, import.meta.url));
+        return Promise.resolve(
+          new Lemmings.BinaryReader(new Uint8Array(data), 0, data.length, file, path)
+        );
+      }
+    }
+
+    const config = makeConfig({
+      path: 'xmas92',
+      gametype: Lemmings.GameTypes.XMAS92,
+      level: {
+        filePrefix: 'LEVEL',
+        useOddTable: false,
+        order: [[4]]
+      }
+    });
+
+    const loader = new Lemmings.LevelLoader(new Provider(), config);
+    const level = await loader.getLevel(0, 0);
+
+    expect(level).to.be.instanceOf(Lemmings.Level);
+    expect(calls).to.include('xmas92/GROUND0O.DAT');
+    expect(calls).to.include('xmas91/GROUND0O.DAT');
+  });
+
+  it('applies seasonal steel sprite mappings to generate steel masks', async function () {
+    const Provider = makeProvider();
+    const seasonalCases = [
+      {
+        path: 'xmas91',
+        gametype: Lemmings.GameTypes.XMAS91,
+        level: { filePrefix: 'LEVEL', useOddTable: false, order: [[3]] }
+      },
+      {
+        path: 'xmas92',
+        gametype: Lemmings.GameTypes.XMAS92,
+        level: { filePrefix: 'LEVEL', useOddTable: false, order: [[3]] }
+      },
+      {
+        path: 'holiday93',
+        gametype: Lemmings.GameTypes.HOLIDAY93,
+        level: { filePrefix: 'LEVEL', useOddTable: false, order: [[1]] }
+      },
+      {
+        path: 'holiday94',
+        gametype: Lemmings.GameTypes.HOLIDAY94,
+        level: { filePrefix: 'LEVEL', useOddTable: false, order: [[1]] }
+      }
+    ];
+
+    for (let i = 0; i < seasonalCases.length; i += 1) {
+      const config = makeConfig(seasonalCases[i]);
+      const loader = new Lemmings.LevelLoader(new Provider(), config);
+      const level = await loader.getLevel(0, 0);
+      const steelPixels = countMaskPixels(level?.steelMask?.mask);
+      expect(steelPixels, `expected steel mask pixels for ${config.path}`).to.be.greaterThan(0);
+    }
+  });
+
 });
diff --git a/test/listSprites.loadDefaultPack.test.js b/test/listSprites.loadDefaultPack.test.js
index aad9efe2..4ed61f53 100644
--- a/test/listSprites.loadDefaultPack.test.js
+++ b/test/listSprites.loadDefaultPack.test.js
@@ -15,7 +15,7 @@ function patchModule() {
     'const cfgPath = path.join(path.dirname(new URL(import.meta.url).pathname), \'..\', \'config.json\');',
     'cfgPath = cfgPath || path.join(path.dirname(new URL(import.meta.url).pathname), \'..\', \'config.json\');'
   );
-const tmp = path.join(path.dirname(fileURLToPath(origPath)), 'listSprites.patched.js');
+  const tmp = path.join(path.dirname(fileURLToPath(origPath)), 'listSprites.patched.js');
   fs.writeFileSync(tmp, code);
   return tmp;
 }
diff --git a/test/mapobject.test.js b/test/mapobject.test.js
index b017fff2..dc666ae2 100644
--- a/test/mapobject.test.js
+++ b/test/mapobject.test.js
@@ -1,10 +1,10 @@
 import { expect } from 'chai';
-import { setGlobalLemmings, useGlobalLemmings, withGlobalLemmings } from './helpers/lemmings.js';
+import { useGlobalLemmings } from './helpers/lemmings.js';
 import { MapObject } from '../js/level/MapObject.js';
 import { TriggerTypes } from '../js/level/TriggerTypes.js';
 import { Animation } from '../js/render/Animation.js';
 import { ColorPalette } from '../js/render/ColorPalette.js';
-import '../js/render/Frame.js';
+import { Frame } from '../js/render/Frame.js';
 
 /** simple helper to create an object image stub */
 function makeObjectImage(loop = true, palette = null) {
@@ -24,20 +24,13 @@ function makeObjectImage(loop = true, palette = null) {
 }
 
 const withSoundEvents = (events, fn) => {
-  const restore = setGlobalLemmings({
-    game: {
-      soundEvents: {
-        emitSfx(type, id, payload) {
-          events.push({ type, id, payload });
-        }
+  return fn({
+    soundEvents: {
+      emitSfx(type, id, payload) {
+        events.push({ type, id, payload });
       }
     }
   });
-  try {
-    return fn();
-  } finally {
-    restore();
-  }
 };
 
 useGlobalLemmings({ game: { showDebug: false } });
@@ -70,29 +63,26 @@ describe('MapObject', function () {
 
   it('records animation changes when history is available', function () {
     const records = [];
-    withGlobalLemmings({
-      game: {
-        history: {
-          recordObjectAnimation(obj, prev, next) {
-            records.push({ obj, prev, next });
-          }
+    const runtime = {
+      history: {
+        recordObjectAnimation(obj, prev, next) {
+          records.push({ obj, prev, next });
         }
       }
-    }, () => {
-      MapObject._frameCache = new WeakMap();
-      const img = makeObjectImage(false);
-      const anim = new Animation();
-      const mo = new MapObject({ id: 0, x: 0, y: 0, drawProperties: {} }, img, anim);
-      anim.firstFrameIndex = 12;
-      anim.isFinished = true;
-
-      mo.onTrigger(20);
-
-      expect(records).to.have.length(1);
-      expect(records[0].prev.firstFrameIndex).to.equal(12);
-      expect(records[0].next.firstFrameIndex).to.equal(20);
-      expect(records[0].next.isFinished).to.equal(false);
-    });
+    };
+    MapObject._frameCache = new WeakMap();
+    const img = makeObjectImage(false);
+    const anim = new Animation();
+    const mo = new MapObject({ id: 0, x: 0, y: 0, drawProperties: {} }, img, anim, 0, runtime);
+    anim.firstFrameIndex = 12;
+    anim.isFinished = true;
+
+    mo.onTrigger(20);
+
+    expect(records).to.have.length(1);
+    expect(records[0].prev.firstFrameIndex).to.equal(12);
+    expect(records[0].next.firstFrameIndex).to.equal(20);
+    expect(records[0].next.isFinished).to.equal(false);
   });
 
   it('draws frames using the provided palette', function () {
@@ -109,12 +99,54 @@ describe('MapObject', function () {
     expect(Array.from(buf.slice(0, 2))).to.eql([c0, c1]);
   });
 
+  it('reuses predecoded Frame sprites without reconversion', function() {
+    MapObject._frameCache = new WeakMap();
+    const rgba = new Frame(2, 1);
+    rgba.setPixel(0, 0, ColorPalette.colorFromRGB(9, 8, 7));
+    const img = {
+      width: 2,
+      height: 1,
+      frames: [rgba],
+      palette: null,
+      animationLoop: true,
+      firstFrameIndex: 0
+    };
+    const mo = new MapObject({ id: 0, x: 0, y: 0, drawProperties: {} }, img, new Animation());
+    expect(mo.animation.frames[0]).to.equal(rgba);
+  });
+
+  it('downscales predecoded Frame sprites using sourceScale factors', function() {
+    MapObject._frameCache = new WeakMap();
+    const rgba = new Frame(4, 2);
+    rgba.clear();
+    rgba.setPixel(0, 0, ColorPalette.colorFromRGB(1, 2, 3));
+    rgba.setPixel(2, 0, ColorPalette.colorFromRGB(4, 5, 6));
+    const img = {
+      width: 4,
+      height: 2,
+      frames: [rgba],
+      palette: null,
+      sourceScaleX: 2,
+      sourceScaleY: 2,
+      animationLoop: true,
+      firstFrameIndex: 0
+    };
+
+    const mo = new MapObject({ id: 0, x: 0, y: 0, drawProperties: {} }, img, new Animation());
+    const frame = mo.animation.frames[0];
+    expect(frame.width).to.equal(2);
+    expect(frame.height).to.equal(1);
+    const c0 = ColorPalette.colorFromRGB(1, 2, 3) >>> 0;
+    const c1 = ColorPalette.colorFromRGB(4, 5, 6) >>> 0;
+    expect(Array.from(frame.getBuffer().slice(0, 2))).to.eql([c0, c1]);
+  });
+
   it('emits trap and fire sounds on trigger', function () {
     const events = [];
-    withSoundEvents(events, () => {
+    withSoundEvents(events, (runtime) => {
       MapObject._frameCache = new WeakMap();
       const img = makeObjectImage(true);
-      const mo = new MapObject({ id: 5, x: 1, y: 2, drawProperties: {} }, img, new Animation(), 0);
+      const mo = new MapObject({ id: 5, x: 1, y: 2, drawProperties: {} }, img, new Animation(), 0, runtime);
 
       const trap = { type: TriggerTypes.TRAP, soundIndex: 2 };
       mo.onTrigger(0, { id: 1, x: 10, y: 11 }, trap, 9, 8);
@@ -128,10 +160,10 @@ describe('MapObject', function () {
 
   it('falls back to lemming position when trigger coordinates are missing', function () {
     const events = [];
-    withSoundEvents(events, () => {
+    withSoundEvents(events, (runtime) => {
       MapObject._frameCache = new WeakMap();
       const img = makeObjectImage(true);
-      const mo = new MapObject({ id: 9, x: 1, y: 2, drawProperties: {} }, img, new Animation(), 0);
+      const mo = new MapObject({ id: 9, x: 1, y: 2, drawProperties: {} }, img, new Animation(), 0, runtime);
 
       const trap = { type: TriggerTypes.TRAP, soundIndex: 2 };
       const lem = { id: 4, x: 7, y: 8 };
@@ -145,10 +177,10 @@ describe('MapObject', function () {
 
   it('falls back to object position when no trigger or lemming coordinates are provided', function () {
     const events = [];
-    withSoundEvents(events, () => {
+    withSoundEvents(events, (runtime) => {
       MapObject._frameCache = new WeakMap();
       const img = makeObjectImage(true);
-      const mo = new MapObject({ id: 12, x: 3, y: 4, drawProperties: {} }, img, new Animation(), 0);
+      const mo = new MapObject({ id: 12, x: 3, y: 4, drawProperties: {} }, img, new Animation(), 0, runtime);
 
       const trap = { type: TriggerTypes.TRAP, soundIndex: 3 };
       mo.onTrigger(0, null, trap);
@@ -162,10 +194,10 @@ describe('MapObject', function () {
 
   it('skips sound emission when sfxId is not positive', function () {
     const events = [];
-    withSoundEvents(events, () => {
+    withSoundEvents(events, (runtime) => {
       MapObject._frameCache = new WeakMap();
       const img = makeObjectImage(true);
-      const mo = new MapObject({ id: 5, x: 1, y: 2, drawProperties: {} }, img, new Animation(), TriggerTypes.TRAP);
+      const mo = new MapObject({ id: 5, x: 1, y: 2, drawProperties: {} }, img, new Animation(), TriggerTypes.TRAP, runtime);
       mo.onTrigger(0, null, { type: TriggerTypes.TRAP, soundIndex: 0 });
       expect(events.length).to.equal(0);
     });
@@ -173,10 +205,10 @@ describe('MapObject', function () {
 
   it('handles trap triggers without explicit trigger data', function () {
     const events = [];
-    withSoundEvents(events, () => {
+    withSoundEvents(events, (runtime) => {
       MapObject._frameCache = new WeakMap();
       const img = makeObjectImage(true);
-      const mo = new MapObject({ id: 5, x: 1, y: 2, drawProperties: {} }, img, new Animation(), TriggerTypes.TRAP);
+      const mo = new MapObject({ id: 5, x: 1, y: 2, drawProperties: {} }, img, new Animation(), TriggerTypes.TRAP, runtime);
       mo.onTrigger(0);
       expect(events.length).to.equal(0);
     });
@@ -184,10 +216,10 @@ describe('MapObject', function () {
 
   it('emits frying sounds and preserves explicit trigger coordinates', function () {
     const events = [];
-    withSoundEvents(events, () => {
+    withSoundEvents(events, (runtime) => {
       MapObject._frameCache = new WeakMap();
       const img = makeObjectImage(true);
-      const mo = new MapObject({ id: 6, x: 3, y: 4, drawProperties: {} }, img, new Animation(), 0);
+      const mo = new MapObject({ id: 6, x: 3, y: 4, drawProperties: {} }, img, new Animation(), 0, runtime);
       const fry = { type: TriggerTypes.FRYING };
       mo.onTrigger(0, { id: 1, x: 9, y: 8 }, fry, 0, 0);
       expect(events.length).to.equal(1);
diff --git a/test/mcp-event-envelope.test.js b/test/mcp-event-envelope.test.js
new file mode 100644
index 00000000..7babe1d9
--- /dev/null
+++ b/test/mcp-event-envelope.test.js
@@ -0,0 +1,69 @@
+import { expect } from 'chai';
+import { attachEvents } from '../mcp/eventEnvelope.js';
+import { EventQueue } from '../mcp/eventQueue.js';
+
+const createQueue = () => {
+  let id = 0;
+  let time = 0;
+  return new EventQueue({
+    maxEvents: 8,
+    idFactory() {
+      id += 1;
+      return `evt-${id}`;
+    },
+    timeFactory() {
+      time += 1;
+      return `t-${time}`;
+    }
+  });
+};
+
+describe('attachEvents', function () {
+  it('filters out agent events in minimal mode and preserves summaries', function () {
+    const session = {
+      eventsMode: 'minimal',
+      events: createQueue()
+    };
+    session.events.add({ source: 'agent', type: 'input', summary: 'action' });
+    session.events.add({ source: 'human', type: 'input', summary: 'keypress' });
+    const payload = attachEvents(session, { ok: true });
+
+    expect(payload.events.events).to.have.lengthOf(1);
+    expect(payload.events.events[0].source).to.equal('human');
+    expect(payload.events.humanSummary).to.equal('keypress');
+  });
+
+  it('returns payload unchanged when events mode is none', function () {
+    const session = {
+      eventsMode: 'none',
+      events: createQueue()
+    };
+    session.events.add({ source: 'human', type: 'input', summary: 'click' });
+    const payload = { ok: true };
+    const result = attachEvents(session, payload);
+    expect(result).to.equal(payload);
+    expect(result.events).to.equal(undefined);
+  });
+
+  it('returns non-object payloads unchanged', function () {
+    const session = {
+      eventsMode: 'minimal',
+      events: createQueue()
+    };
+    session.events.add({ source: 'human', type: 'input', summary: 'click' });
+    const payload = 'ok';
+    const result = attachEvents(session, payload);
+    expect(result).to.equal(payload);
+  });
+
+  it('returns payload unchanged when session has no drainable event queue', function () {
+    const session = {
+      eventsMode: 'minimal',
+      events: null
+    };
+    const payload = { ok: true };
+    const result = attachEvents(session, payload);
+    expect(result).to.equal(payload);
+    expect(result.events).to.equal(undefined);
+  });
+});
diff --git a/test/mcp-event-queue.test.js b/test/mcp-event-queue.test.js
new file mode 100644
index 00000000..3e1ca6c5
--- /dev/null
+++ b/test/mcp-event-queue.test.js
@@ -0,0 +1,391 @@
+import { expect } from 'chai';
+import { EventQueue } from '../mcp/eventQueue.js';
+
+describe('EventQueue', function () {
+  const createQueue = (maxEvents = 4) => {
+    let id = 0;
+    let time = 0;
+    return new EventQueue({
+      maxEvents,
+      idFactory() {
+        id += 1;
+        return `evt-${id}`;
+      },
+      timeFactory() {
+        time += 1;
+        return `t-${time}`;
+      }
+    });
+  };
+
+  it('drains events after a cursor and advances lastDelivered', function () {
+    const queue = createQueue(8);
+    queue.add({ source: 'agent', type: 'a', summary: 'first' });
+    queue.add({ source: 'agent', type: 'b', summary: 'second' });
+
+    const firstDrain = queue.drain(undefined);
+    expect(firstDrain.cursor).to.equal('2');
+    expect(firstDrain.events).to.have.lengthOf(2);
+    expect(firstDrain.events[0].type).to.equal('a');
+    expect(firstDrain.events[1].type).to.equal('b');
+    expect(queue.lastDelivered).to.equal(2);
+
+    const none = queue.drain(undefined);
+    expect(none).to.equal(null);
+  });
+
+  it('drops oldest entries when capacity is exceeded and drains from available head', function () {
+    const queue = createQueue(3);
+    queue.add({ source: 'agent', type: 'a' }); // seq 1
+    queue.add({ source: 'agent', type: 'b' }); // seq 2
+    queue.add({ source: 'agent', type: 'c' }); // seq 3
+    queue.add({ source: 'agent', type: 'd' }); // seq 4 (drops seq 1)
+    queue.add({ source: 'agent', type: 'e' }); // seq 5 (drops seq 2)
+
+    const drainFromOldCursor = queue.drain('0');
+    expect(drainFromOldCursor.cursor).to.equal('5');
+    expect(drainFromOldCursor.events.map((event) => event.type)).to.deep.equal(['c', 'd', 'e']);
+  });
+
+  it('supports drain without updating the queue cursor', function () {
+    const queue = createQueue(4);
+    queue.add({ source: 'agent', type: 'a' });
+    queue.add({ source: 'agent', type: 'b' });
+
+    const envelope = queue.drain(undefined, { updateCursor: false });
+    expect(envelope.cursor).to.equal('2');
+    expect(queue.lastDelivered).to.equal(0);
+
+    const second = queue.drain(undefined);
+    expect(second.events).to.have.lengthOf(2);
+    expect(queue.lastDelivered).to.equal(2);
+  });
+
+  it('normalizes fractional cursors before draining', function () {
+    const queue = createQueue(4);
+    queue.add({ source: 'agent', type: 'a' });
+    queue.add({ source: 'agent', type: 'b' });
+    queue.add({ source: 'agent', type: 'c' });
+
+    const envelope = queue.drain('1.9');
+    expect(envelope.events.map((event) => event.type)).to.deep.equal(['b', 'c']);
+    expect(envelope.cursor).to.equal('3');
+  });
+
+  it('normalizes stale and oversized cursors into the queue-owned range', function () {
+    const queue = createQueue(3);
+    queue.add({ source: 'agent', type: 'a' }); // seq 1
+    queue.add({ source: 'agent', type: 'b' }); // seq 2
+    queue.add({ source: 'agent', type: 'c' }); // seq 3
+    queue.add({ source: 'agent', type: 'd' }); // seq 4, drops seq 1
+
+    expect(queue.normalizeCursor('-999')).to.equal(1);
+    expect(queue.normalizeCursor('999')).to.equal(4);
+    expect(queue.drain('999')).to.equal(null);
+  });
+
+  it('preserves human summary on peek drains', function () {
+    const queue = createQueue(4);
+    queue.add({ source: 'human', type: 'input', summary: 'first' });
+    queue.add({ source: 'agent', type: 'state', summary: 'sync' });
+
+    const peek = queue.drain(undefined, {
+      updateCursor: false,
+      includeHumanSummary: true
+    });
+    expect(peek.humanSummary).to.equal('first');
+    expect(queue.lastDelivered).to.equal(0);
+    expect(queue.humanSummaryParts.length).to.equal(1);
+
+    const committed = queue.drain(undefined, {
+      updateCursor: true,
+      includeHumanSummary: true
+    });
+    expect(committed.humanSummary).to.equal('first');
+    expect(queue.humanSummaryParts.length).to.equal(0);
+  });
+
+  it('emits and clears human summary only when requested', function () {
+    const queue = createQueue(8);
+    queue.add({ source: 'human', type: 'input', summary: 'click' });
+    queue.add({ source: 'agent', type: 'state', summary: 'agent-update' });
+    queue.add({ source: 'human', type: 'input', summary: 'keypress' });
+
+    const noSummary = queue.drain(undefined, { includeHumanSummary: false });
+    expect(noSummary.humanSummary).to.equal(undefined);
+
+    const stillNone = queue.drain(noSummary.cursor, { includeHumanSummary: true });
+    expect(stillNone).to.equal(null);
+
+    queue.add({ source: 'agent', type: 'state', summary: 'refresh' });
+    const withSummary = queue.drain(noSummary.cursor, { includeHumanSummary: true });
+    expect(withSummary.humanSummary).to.equal('click; keypress');
+
+    queue.add({ source: 'agent', type: 'state', summary: 'next' });
+    const cleared = queue.drain(withSummary.cursor, { includeHumanSummary: true });
+    expect(cleared.humanSummary).to.equal(undefined);
+  });
+
+  it('captures event payload snapshots instead of live object references', function () {
+    const queue = createQueue(4);
+    const data = { nested: { count: 1 } };
+    const resourceUris = ['res://one'];
+
+    queue.add({ source: 'system', type: 'watch-trigger', data, resourceUris });
+    data.nested.count = 99;
+    resourceUris.push('res://two');
+
+    const envelope = queue.drain(undefined);
+    expect(envelope.events[0].data).to.deep.equal({ nested: { count: 1 } });
+    expect(envelope.events[0].resourceUris).to.deep.equal(['res://one']);
+  });
+
+  it('normalizes non-string summaries so falsy values are preserved', function () {
+    const queue = createQueue(4);
+    queue.add({ source: 'human', type: 'input', summary: 0 });
+    queue.add({ source: 'human', type: 'input', summary: false });
+
+    const envelope = queue.drain('0', { includeHumanSummary: true });
+    expect(envelope.events.map((event) => event.summary)).to.deep.equal(['0', 'false']);
+    expect(envelope.humanSummary).to.equal('0; false');
+  });
+
+  it('drops malformed non-array resource uri payloads', function () {
+    const queue = createQueue(4);
+    queue.add({ source: 'system', type: 'watch-trigger', resourceUris: 'res://one' });
+
+    const envelope = queue.drain('0');
+    expect(envelope.events[0].resourceUris).to.equal(undefined);
+  });
+
+  it('falls back to cycle-safe cloning when structuredClone is unavailable', function () {
+    const descriptor = Object.getOwnPropertyDescriptor(globalThis, 'structuredClone');
+    if (descriptor && descriptor.configurable !== true && descriptor.writable !== true) {
+      this.skip();
+      return;
+    }
+
+    const queue = createQueue(4);
+    const data = { nested: { count: 1 } };
+    data.self = data;
+
+    const restoreStructuredClone = () => {
+      if (descriptor) {
+        Object.defineProperty(globalThis, 'structuredClone', descriptor);
+      } else {
+        delete globalThis.structuredClone;
+      }
+    };
+
+    try {
+      Object.defineProperty(globalThis, 'structuredClone', {
+        configurable: true,
+        writable: true,
+        value: undefined
+      });
+      queue.add({ source: 'system', type: 'watch', data });
+    } finally {
+      restoreStructuredClone();
+    }
+
+    data.nested.count = 99;
+    const envelope = queue.drain(undefined);
+    expect(envelope.events[0].data).to.not.equal(data);
+    expect(envelope.events[0].data.nested.count).to.equal(1);
+    expect(envelope.events[0].data.self).to.equal(envelope.events[0].data);
+  });
+
+  it('bounds human summary history to avoid unbounded growth', function () {
+    const queue = createQueue(6);
+    queue.maxHumanSummaryParts = 3;
+    queue.add({ source: 'human', type: 'input', summary: 'first' });
+    queue.add({ source: 'human', type: 'input', summary: 'second' });
+    queue.add({ source: 'human', type: 'input', summary: 'third' });
+    queue.add({ source: 'human', type: 'input', summary: 'fourth' });
+    queue.add({ source: 'human', type: 'input', summary: 'fifth' });
+
+    const envelope = queue.drain('0');
+    expect(envelope.humanSummary).to.equal('third; fourth; fifth');
+    expect(queue.humanSummaryParts.length).to.equal(0);
+  });
+
+  it('normalizes constructor human summary limit and supports explicit option', function () {
+    const queue = new EventQueue({
+      maxEvents: 4,
+      maxHumanSummaryParts: 1,
+      idFactory() { return 'evt'; },
+      timeFactory() { return 'fixed-time'; }
+    });
+
+    expect(queue.maxHumanSummaryParts).to.equal(1);
+    queue.add({ source: 'human', type: 'input', summary: 'first' });
+    queue.add({ source: 'human', type: 'input', summary: 'second' });
+
+    const envelope = queue.drain('0');
+    expect(envelope.events).to.have.lengthOf(2);
+    expect(envelope.humanSummary).to.equal('second');
+    expect(queue.maxHumanSummaryParts).to.equal(1);
+  });
+
+  it('treats non-positive human summary max as disabled', function () {
+    const queue = new EventQueue({
+      maxEvents: 8,
+      maxHumanSummaryParts: 0,
+      idFactory() { return 'evt'; },
+      timeFactory() { return 'fixed-time'; }
+    });
+
+    expect(queue.maxHumanSummaryParts).to.equal(0);
+    queue.add({ source: 'human', type: 'input', summary: 'first' });
+    queue.add({ source: 'human', type: 'input', summary: 'second' });
+    const envelope = queue.drain('0', { includeHumanSummary: true });
+    expect(envelope.humanSummary).to.equal(undefined);
+  });
+
+  it('defaults summary limit when configured value is invalid', function () {
+    const queue = new EventQueue({
+      maxEvents: 4,
+      maxHumanSummaryParts: -10,
+      idFactory() { return 'evt'; },
+      timeFactory() { return 'fixed-time'; }
+    });
+    expect(queue.maxHumanSummaryParts).to.equal(24);
+  });
+
+  it('normalizes invalid maxEvents inputs to a usable default capacity', function () {
+    const queue = new EventQueue({
+      maxEvents: Number.NaN,
+      idFactory() { return 'evt'; },
+      timeFactory() { return 'fixed-time'; }
+    });
+    expect(queue.maxEvents).to.equal(1000);
+
+    queue.add({ source: 'agent', type: 'state' });
+    const envelope = queue.drain('0');
+    expect(envelope.events).to.have.lengthOf(1);
+  });
+
+  it('normalizes bigint capacity inputs without throwing', function () {
+    const queue = new EventQueue({
+      maxEvents: 4n,
+      maxHumanSummaryParts: 2n,
+      idFactory() { return 'evt'; },
+      timeFactory() { return 'fixed-time'; }
+    });
+    expect(queue.maxEvents).to.equal(4);
+    expect(queue.maxHumanSummaryParts).to.equal(2);
+    queue.add({ source: 'human', type: 'input', summary: 'a' });
+    queue.add({ source: 'human', type: 'input', summary: 'b' });
+    queue.add({ source: 'human', type: 'input', summary: 'c' });
+    const envelope = queue.drain('0');
+    expect(envelope.humanSummary).to.equal('b; c');
+  });
+
+  it('normalizes non-coercible capacity inputs without throwing', function () {
+    const queue = new EventQueue({
+      maxEvents: Symbol('events'),
+      maxHumanSummaryParts: Symbol('summary'),
+      idFactory() { return 'evt'; },
+      timeFactory() { return 'fixed-time'; }
+    });
+    expect(queue.maxEvents).to.equal(1000);
+    expect(queue.maxHumanSummaryParts).to.equal(24);
+  });
+
+  it('caps extremely large maxEvents values to a safe upper bound', function () {
+    const queue = new EventQueue({
+      maxEvents: 1e9,
+      idFactory() { return 'evt'; },
+      timeFactory() { return 'fixed-time'; }
+    });
+    expect(queue.maxEvents).to.equal(10000);
+    expect(queue.events.length).to.equal(10000);
+  });
+
+  it('caps oversized human summary limits at runtime', function () {
+    const queue = createQueue(8);
+    queue.maxHumanSummaryParts = 1e9;
+    queue.add({ source: 'human', type: 'input', summary: 'a' });
+    expect(queue.maxHumanSummaryParts).to.equal(2048);
+  });
+
+  it('rebalances buffered human summaries when maxHumanSummaryParts shrinks at runtime', function () {
+    const queue = createQueue(8);
+    queue.maxHumanSummaryParts = 5;
+    queue.add({ source: 'human', type: 'input', summary: 'a' });
+    queue.add({ source: 'human', type: 'input', summary: 'b' });
+    queue.add({ source: 'human', type: 'input', summary: 'c' });
+    queue.add({ source: 'human', type: 'input', summary: 'd' });
+    queue.add({ source: 'human', type: 'input', summary: 'e' });
+
+    queue.maxHumanSummaryParts = 2;
+    queue.add({ source: 'human', type: 'input', summary: 'f' });
+
+    const envelope = queue.drain('0');
+    expect(envelope.humanSummary).to.equal('e; f');
+  });
+
+  it('clears buffered human summaries when summary retention is disabled at runtime', function () {
+    const queue = createQueue(8);
+    queue.maxHumanSummaryParts = 4;
+    queue.add({ source: 'human', type: 'input', summary: 'first' });
+    queue.add({ source: 'human', type: 'input', summary: 'second' });
+    expect(queue.humanSummaryParts.length).to.equal(2);
+
+    queue.maxHumanSummaryParts = 0;
+    queue.add({ source: 'human', type: 'input', summary: 'third' });
+
+    const envelope = queue.drain('0', { includeHumanSummary: true });
+    expect(envelope.humanSummary).to.equal(undefined);
+    expect(queue.humanSummaryParts.length).to.equal(0);
+  });
+
+  it('clears buffered human summaries when retention is disabled before non-human events', function () {
+    const queue = createQueue(8);
+    queue.maxHumanSummaryParts = 4;
+    queue.add({ source: 'human', type: 'input', summary: 'first' });
+    queue.add({ source: 'human', type: 'input', summary: 'second' });
+    expect(queue.humanSummaryParts.length).to.equal(2);
+
+    queue.maxHumanSummaryParts = 0;
+    queue.add({ source: 'agent', type: 'state', summary: 'refresh' });
+
+    const envelope = queue.drain('0', { includeHumanSummary: true });
+    expect(envelope.humanSummary).to.equal(undefined);
+    expect(queue.humanSummaryParts.length).to.equal(0);
+  });
+
+  it('rebalances buffered summaries when retention shrinks before non-human events', function () {
+    const queue = createQueue(8);
+    queue.maxHumanSummaryParts = 5;
+    queue.add({ source: 'human', type: 'input', summary: 'a' });
+    queue.add({ source: 'human', type: 'input', summary: 'b' });
+    queue.add({ source: 'human', type: 'input', summary: 'c' });
+    queue.add({ source: 'human', type: 'input', summary: 'd' });
+    queue.add({ source: 'human', type: 'input', summary: 'e' });
+
+    queue.maxHumanSummaryParts = 2;
+    queue.add({ source: 'agent', type: 'state', summary: 'refresh' });
+
+    const envelope = queue.drain('0', { includeHumanSummary: true });
+    expect(envelope.humanSummary).to.equal('d; e');
+  });
+
+  it('reorders wrapped summaries correctly when shrinking the runtime summary cap', function () {
+    const queue = createQueue(16);
+    queue.maxHumanSummaryParts = 5;
+    queue.add({ source: 'human', type: 'input', summary: 'a' });
+    queue.add({ source: 'human', type: 'input', summary: 'b' });
+    queue.add({ source: 'human', type: 'input', summary: 'c' });
+    queue.add({ source: 'human', type: 'input', summary: 'd' });
+    queue.add({ source: 'human', type: 'input', summary: 'e' });
+    queue.add({ source: 'human', type: 'input', summary: 'f' });
+    expect(queue.humanSummaryStart).to.equal(1);
+
+    queue.maxHumanSummaryParts = 2;
+    queue.add({ source: 'human', type: 'input', summary: 'g' });
+
+    const envelope = queue.drain('0', { includeHumanSummary: true });
+    expect(envelope.humanSummary).to.equal('f; g');
+  });
+});
diff --git a/test/mcp-lemming-summary.test.js b/test/mcp-lemming-summary.test.js
new file mode 100644
index 00000000..353f8a76
--- /dev/null
+++ b/test/mcp-lemming-summary.test.js
@@ -0,0 +1,157 @@
+import { expect } from 'chai';
+import { buildLemmingSummary } from '../mcp/lemmingSummary.js';
+
+describe('buildLemmingSummary', function () {
+  it('computes counts and bounded top-k in a single pass', function () {
+    const state = {
+      stage: {
+        viewRect: { x: 0, y: 0, width: 12, height: 12 }
+      },
+      game: {
+        timer: { tickIndex: 42 },
+        lemmingManager: { selectedIndex: 0 },
+        lemmings: [
+          { id: 0, x: 5, y: 5, actionType: 10, state: 1, canClimb: true },
+          { id: 1, x: 9, y: 4, actionType: 11, state: 2, countdownActive: true },
+          { id: 2, x: 7, y: 6, actionType: 11, state: 2, removed: true, hasExploded: true },
+          { id: 3, x: 20, y: 3, actionType: 12, state: 3, disabled: true },
+          { id: 4, x: 11, y: 7, actionType: 13, state: 4, hasParachute: true }
+        ]
+      }
+    };
+
+    const summary = buildLemmingSummary(state, { inViewOnly: true, topK: 2 });
+    expect(summary.tickIndex).to.equal(42);
+    expect(summary.totalCount).to.equal(4);
+    expect(summary.activeCount).to.equal(3);
+    expect(summary.removedCount).to.equal(1);
+    expect(summary.disabledCount).to.equal(0);
+    expect(summary.byActionType).to.deep.equal({ 10: 1, 11: 1, 13: 1 });
+    expect(summary.byState).to.deep.equal({ 1: 1, 2: 1, 4: 1 });
+    expect(summary.climbers).to.equal(1);
+    expect(summary.floaters).to.equal(1);
+    expect(summary.countingDown).to.equal(1);
+    expect(summary.exploded).to.equal(0);
+    expect(summary.selectedLemmingId).to.equal(0);
+    expect(summary.top.map((lem) => lem.id)).to.deep.equal([0, 1]);
+  });
+
+  it('supports top-k without forced selected inclusion and preserves topK=0 behavior', function () {
+    const state = {
+      game: {
+        timer: { tickIndex: 7 },
+        lemmingManager: { selectedIndex: 0 },
+        lemmings: [
+          { id: 0, x: 2, y: 1 },
+          { id: 1, x: 6, y: 1, countdownActive: true }
+        ]
+      }
+    };
+
+    const withoutSelected = buildLemmingSummary(state, {
+      topK: 1,
+      includeSelected: false
+    });
+    expect(withoutSelected.selected).to.equal(null);
+    expect(withoutSelected.top.map((lem) => lem.id)).to.deep.equal([1]);
+
+    const withZeroTop = buildLemmingSummary(state, { topK: 0 });
+    expect(withZeroTop.top).to.deep.equal([]);
+  });
+
+  it('only fully sorts candidates when explicitly requested', function () {
+    const lemmings = [];
+    for (let i = 0; i < 60; i += 1) {
+      lemmings.push({
+        id: i,
+        x: (i * 17) % 31,
+        y: i % 7,
+        countdownActive: i % 9 === 0
+      });
+    }
+    const state = {
+      game: {
+        lemmingManager: { selectedIndex: -1 },
+        lemmings
+      }
+    };
+
+    const bounded = buildLemmingSummary(state, { topK: 8 });
+    const sorted = buildLemmingSummary(state, { topK: 8, sortAllCandidates: true });
+    expect(bounded.top.map((lem) => lem.id)).to.deep.equal(sorted.top.map((lem) => lem.id));
+  });
+
+  it('returns snapshot copies for selected and top entries', function () {
+    const selected = { id: 1, x: 4, y: 2, countdownActive: true };
+    const other = { id: 2, x: 3, y: 1 };
+    const state = {
+      game: {
+        timer: { tickIndex: 3 },
+        lemmingManager: { selectedIndex: 0 },
+        lemmings: [selected, other]
+      }
+    };
+
+    const summary = buildLemmingSummary(state, { topK: 2 });
+    expect(summary.selected).to.not.equal(selected);
+    expect(summary.top[0]).to.not.equal(selected);
+
+    summary.selected.x = 999;
+    summary.top[0].x = 777;
+    expect(selected.x).to.equal(4);
+  });
+
+  it('ignores malformed rect origins instead of filtering all lemmings', function () {
+    const state = {
+      game: {
+        lemmingManager: { selectedIndex: -1 },
+        lemmings: [
+          { id: 0, x: 1, y: 1 },
+          { id: 1, x: 5, y: 4 }
+        ]
+      }
+    };
+
+    const summary = buildLemmingSummary(state, {
+      rectWorld: { x: 'bad', y: 0, width: 10, height: 10 }
+    });
+    expect(summary.totalCount).to.equal(2);
+    expect(summary.activeCount).to.equal(2);
+  });
+
+  it('ignores non-positive rect dimensions instead of filtering all lemmings', function () {
+    const state = {
+      game: {
+        lemmingManager: { selectedIndex: -1 },
+        lemmings: [
+          { id: 0, x: 1, y: 1 },
+          { id: 1, x: 5, y: 4 }
+        ]
+      }
+    };
+
+    const summary = buildLemmingSummary(state, {
+      rectWorld: { x: 0, y: 0, width: 0, height: 10 }
+    });
+    expect(summary.totalCount).to.equal(2);
+    expect(summary.activeCount).to.equal(2);
+  });
+
+  it('accepts numeric-like rect dimensions and coordinates from string inputs', function () {
+    const state = {
+      game: {
+        lemmingManager: { selectedIndex: -1 },
+        lemmings: [
+          { id: 0, x: 1, y: 1 },
+          { id: 1, x: 50, y: 50 }
+        ]
+      }
+    };
+
+    const summary = buildLemmingSummary(state, {
+      rectWorld: { x: '0', y: '0', width: '10', height: '10' }
+    });
+    expect(summary.totalCount).to.equal(1);
+    expect(summary.top.map((lem) => lem.id)).to.deep.equal([0]);
+  });
+});
diff --git a/test/mcp-resource-store.test.js b/test/mcp-resource-store.test.js
new file mode 100644
index 00000000..07b8516f
--- /dev/null
+++ b/test/mcp-resource-store.test.js
@@ -0,0 +1,340 @@
+import { expect } from 'chai';
+import { ResourceStore } from '../mcp/resourceStore.js';
+
+describe('ResourceStore', function () {
+  const createStore = () => {
+    let id = 0;
+    let time = 0;
+    return new ResourceStore({
+      maxItems: 2,
+      idFactory() {
+        id += 1;
+        return `res-${id}`;
+      },
+      timeFactory() {
+        time += 1;
+        return `t-${time}`;
+      }
+    });
+  };
+
+  it('stores, lists, and retrieves resources by URI', function () {
+    const store = createStore();
+    const first = store.put({
+      sessionId: 's1',
+      bytes: Buffer.from('alpha'),
+      mimeType: 'text/plain'
+    });
+    const second = store.put({
+      sessionId: 's1',
+      bytes: Buffer.from('beta'),
+      mimeType: 'text/plain'
+    });
+
+    const list = store.list();
+    expect(list).to.have.lengthOf(2);
+    expect(list[0].uri).to.equal(first.uri);
+    expect(list[1].uri).to.equal(second.uri);
+
+    const resource = store.get(first.uri);
+    expect(resource.uri).to.equal(first.uri);
+    expect(resource.bytes.toString('utf8')).to.equal('alpha');
+  });
+
+  it('evicts oldest entries when maxItems is exceeded and clears sessions', function () {
+    const store = createStore();
+    const first = store.put({
+      sessionId: 's1',
+      bytes: Buffer.from('one'),
+      mimeType: 'text/plain'
+    });
+    store.put({
+      sessionId: 's2',
+      bytes: Buffer.from('two'),
+      mimeType: 'text/plain'
+    });
+    store.put({
+      sessionId: 's2',
+      bytes: Buffer.from('three'),
+      mimeType: 'text/plain'
+    });
+
+    expect(store.get(first.uri)).to.equal(null);
+
+    store.clearSession('s2');
+    expect(store.list()).to.have.lengthOf(0);
+  });
+
+  it('rejects oversized payloads and enforces URI session matching', function () {
+    let id = 0;
+    const store = new ResourceStore({
+      maxBytes: 4,
+      maxItems: 4,
+      idFactory() {
+        id += 1;
+        return `res-${id}`;
+      }
+    });
+    const rejected = store.put({
+      sessionId: 's1',
+      bytes: Buffer.from('12345'),
+      mimeType: 'text/plain'
+    });
+    expect(rejected).to.equal(null);
+    expect(store.list()).to.have.lengthOf(0);
+
+    const accepted = store.put({
+      sessionId: 's1',
+      bytes: Buffer.from('1234'),
+      mimeType: 'text/plain'
+    });
+    expect(accepted).to.not.equal(null);
+    const mismatchedUri = accepted.uri.replace('/sessions/s1/', '/sessions/s2/');
+    expect(store.get(mismatchedUri)).to.equal(null);
+    expect(store.get(accepted.uri)).to.not.equal(null);
+  });
+
+  it('normalizes list limits and constructor capacities', function () {
+    const store = new ResourceStore({
+      maxBytes: Number.NaN,
+      maxItems: Number.NaN,
+      ttlMs: -1,
+      idFactory() { return 'res'; },
+      timeFactory() { return 't-0'; }
+    });
+    expect(store.maxBytes).to.equal(256 * 1024 * 1024);
+    expect(store.maxItems).to.equal(5000);
+    expect(store.defaultTtlMs).to.equal(10 * 60 * 1000);
+
+    store.put({
+      sessionId: 's1',
+      bytes: Buffer.from('x'),
+      mimeType: 'text/plain'
+    });
+    expect(store.list({ limit: 0 })).to.deep.equal([]);
+    expect(store.list({ limit: Number.NaN })).to.have.lengthOf(1);
+  });
+
+  it('falls back to default capacities when constructor numeric values are non-coercible', function () {
+    const store = new ResourceStore({
+      maxBytes: Symbol('bytes'),
+      maxItems: Symbol('items'),
+      ttlMs: Symbol('ttl'),
+      idFactory() { return 'res'; },
+      timeFactory() { return 't-0'; }
+    });
+    expect(store.maxBytes).to.equal(256 * 1024 * 1024);
+    expect(store.maxItems).to.equal(5000);
+    expect(store.defaultTtlMs).to.equal(10 * 60 * 1000);
+  });
+
+  it('clones caller buffers and rejects invalid byte payloads', function () {
+    const store = createStore();
+    const source = Buffer.from('alpha');
+    const saved = store.put({
+      sessionId: 's1',
+      bytes: source,
+      mimeType: 'text/plain'
+    });
+    source[0] = 'z'.charCodeAt(0);
+    expect(store.get(saved.uri).bytes.toString('utf8')).to.equal('alpha');
+
+    const invalid = store.put({
+      sessionId: 's1',
+      bytes: { nope: true },
+      mimeType: 'text/plain'
+    });
+    expect(invalid).to.equal(null);
+  });
+
+  it('returns defensive copies for stored bytes and meta payloads', function () {
+    const store = createStore();
+    const meta = { tag: 'snapshot', nested: { n: 1 } };
+    const saved = store.put({
+      sessionId: 's1',
+      bytes: Buffer.from('alpha'),
+      mimeType: 'text/plain',
+      meta
+    });
+    meta.tag = 'mutated';
+    meta.nested.n = 99;
+
+    const first = store.get(saved.uri);
+    expect(first.meta.tag).to.equal('snapshot');
+    expect(first.meta.nested.n).to.equal(1);
+    first.bytes[0] = 'z'.charCodeAt(0);
+    first.meta.tag = 'local-change';
+
+    const second = store.get(saved.uri);
+    expect(second.bytes.toString('utf8')).to.equal('alpha');
+    expect(second.meta.tag).to.equal('snapshot');
+  });
+
+  it('falls back to cycle-safe meta cloning when structuredClone is unavailable', function () {
+    const descriptor = Object.getOwnPropertyDescriptor(globalThis, 'structuredClone');
+    if (descriptor && descriptor.configurable !== true && descriptor.writable !== true) {
+      this.skip();
+      return;
+    }
+
+    const store = createStore();
+    const meta = { tag: 'snapshot', nested: { n: 1 } };
+    meta.self = meta;
+
+    const restoreStructuredClone = () => {
+      if (descriptor) {
+        Object.defineProperty(globalThis, 'structuredClone', descriptor);
+      } else {
+        delete globalThis.structuredClone;
+      }
+    };
+
+    let saved = null;
+    try {
+      Object.defineProperty(globalThis, 'structuredClone', {
+        configurable: true,
+        writable: true,
+        value: undefined
+      });
+      saved = store.put({
+        sessionId: 's1',
+        bytes: Buffer.from('alpha'),
+        mimeType: 'text/plain',
+        meta
+      });
+    } finally {
+      restoreStructuredClone();
+    }
+
+    meta.nested.n = 99;
+    const resource = store.get(saved.uri);
+    expect(resource.meta).to.not.equal(meta);
+    expect(resource.meta.tag).to.equal('snapshot');
+    expect(resource.meta.nested.n).to.equal(1);
+    expect(resource.meta.self).to.equal(resource.meta);
+  });
+
+  it('defaults mime type when omitted', function () {
+    const store = createStore();
+    const saved = store.put({
+      sessionId: 's1',
+      bytes: Buffer.from('x')
+    });
+    const item = store.get(saved.uri);
+    expect(item.mimeType).to.equal('application/octet-stream');
+  });
+
+  it('expires resources by ttl and updates byte accounting', function () {
+    const store = new ResourceStore({
+      maxItems: 10,
+      maxBytes: 1024,
+      ttlMs: 5,
+      idFactory() {
+        return 'exp-1';
+      },
+      timeFactory() {
+        return 't-exp';
+      }
+    });
+    const originalDateNow = Date.now;
+    try {
+      Date.now = () => 1000;
+      const saved = store.put({
+        sessionId: 's1',
+        bytes: Buffer.from('abc'),
+        mimeType: 'text/plain'
+      });
+      expect(store.totalBytes).to.equal(3);
+      expect(store.get(saved.uri)).to.not.equal(null);
+      expect(store.list()).to.have.lengthOf(1);
+
+      Date.now = () => 1006;
+      expect(store.get(saved.uri)).to.equal(null);
+      expect(store.list()).to.have.lengthOf(0);
+      expect(store.totalBytes).to.equal(0);
+    } finally {
+      Date.now = originalDateNow;
+    }
+  });
+
+  it('generates unique ids when idFactory collisions occur', function () {
+    let callCount = 0;
+    const store = new ResourceStore({
+      maxItems: 10,
+      maxBytes: 1024,
+      idFactory() {
+        callCount += 1;
+        return 'dup-id';
+      },
+      timeFactory() {
+        return `t-${callCount}`;
+      }
+    });
+
+    const first = store.put({
+      sessionId: 's1',
+      bytes: Buffer.from('abc'),
+      mimeType: 'text/plain'
+    });
+    const second = store.put({
+      sessionId: 's1',
+      bytes: Buffer.from('z'),
+      mimeType: 'text/plain'
+    });
+
+    expect(first.uri).to.not.equal(second.uri);
+    expect(store.list()).to.have.lengthOf(2);
+    expect(store.totalBytes).to.equal(4);
+    expect(store.get(first.uri).bytes.toString('utf8')).to.equal('abc');
+    expect(store.get(second.uri).bytes.toString('utf8')).to.equal('z');
+  });
+
+  it('normalizes unsafe idFactory output before building resource URIs', function () {
+    const store = new ResourceStore({
+      maxItems: 10,
+      maxBytes: 1024,
+      idFactory() {
+        return 'bad/id ?value';
+      },
+      timeFactory() {
+        return 't-1';
+      }
+    });
+
+    const saved = store.put({
+      sessionId: 's1',
+      bytes: Buffer.from('x'),
+      mimeType: 'text/plain'
+    });
+
+    expect(saved.uri).to.match(/^lemmings:\/\/sessions\/s1\/resources\/badidvalue$/);
+    expect(store.get(saved.uri).bytes.toString('utf8')).to.equal('x');
+  });
+
+  it('normalizes session ids and rejects blank values', function () {
+    const store = createStore();
+    const saved = store.put({
+      sessionId: '  s1  ',
+      bytes: Buffer.from('x'),
+      mimeType: 'text/plain'
+    });
+    expect(saved.uri).to.match(/^lemmings:\/\/sessions\/s1\/resources\//);
+    expect(store.get(saved.uri)).to.not.equal(null);
+
+    const rejected = store.put({
+      sessionId: '   ',
+      bytes: Buffer.from('y'),
+      mimeType: 'text/plain'
+    });
+    expect(rejected).to.equal(null);
+
+    store.put({
+      sessionId: 's2',
+      bytes: Buffer.from('z'),
+      mimeType: 'text/plain'
+    });
+    store.clearSession('  s1  ');
+    expect(store.get(saved.uri)).to.equal(null);
+    expect(store.list()).to.have.lengthOf(1);
+  });
+});
diff --git a/test/mcp-server-protocol.test.js b/test/mcp-server-protocol.test.js
new file mode 100644
index 00000000..1880635f
--- /dev/null
+++ b/test/mcp-server-protocol.test.js
@@ -0,0 +1,18 @@
+import { expect } from 'chai';
+import { createProtocolMetadata } from '../mcp/server.js';
+
+describe('mcp server protocol metadata', function () {
+  it('describes the hard-cut protocol surface', function () {
+    const protocol = createProtocolMetadata();
+    expect(Object.keys(protocol).sort()).to.deep.equal([
+      'acceptedToolNameForms',
+      'lemmingDeltaFields',
+      'schemaFrozenAt',
+      'skillNames',
+      'unsupportedOptions',
+      'version'
+    ]);
+    expect(protocol.acceptedToolNameForms).to.deep.equal(['underscore']);
+    expect(protocol.unsupportedOptions.spectatorOpenBrowser).to.equal(true);
+  });
+});
diff --git a/test/mcp-session-lifecycle.test.js b/test/mcp-session-lifecycle.test.js
new file mode 100644
index 00000000..3f53da39
--- /dev/null
+++ b/test/mcp-session-lifecycle.test.js
@@ -0,0 +1,156 @@
+import { expect } from 'chai';
+import { disposeAllSessionRuntimes, disposeSessionRuntime } from '../mcp/sessionLifecycle.js';
+
+const createSession = (id) => {
+  const calls = [];
+  const session = {
+    id,
+    resources: {
+      clearSession(sessionId) {
+        calls.push(`clear:${sessionId}`);
+      }
+    },
+    context: {
+      async close() {
+        calls.push('context.close');
+      }
+    },
+    browser: {
+      async close() {
+        calls.push('browser.close');
+      }
+    }
+  };
+  return { session, calls };
+};
+
+describe('session lifecycle disposal', function () {
+  it('disposes spectator/watch hooks and closes browser resources', async function () {
+    const { session, calls } = createSession('s1');
+    const hookCalls = [];
+    await disposeSessionRuntime(session, {
+      stopSpectatorServer(target) {
+        hookCalls.push(`spectator:${target.id}`);
+      },
+      stopWatchLoop(target) {
+        hookCalls.push(`watch:${target.id}`);
+      }
+    });
+
+    expect(hookCalls).to.deep.equal(['spectator:s1', 'watch:s1']);
+    expect(calls).to.deep.equal(['clear:s1', 'context.close', 'browser.close']);
+  });
+
+  it('continues cleanup when close methods throw', async function () {
+    const { session, calls } = createSession('s2');
+    session.context.close = async () => {
+      calls.push('context.close');
+      throw new Error('context fail');
+    };
+    session.browser.close = async () => {
+      calls.push('browser.close');
+      throw new Error('browser fail');
+    };
+
+    await disposeSessionRuntime(session);
+    expect(calls).to.deep.equal(['clear:s2', 'context.close', 'browser.close']);
+  });
+
+  it('continues cleanup when resource clearing throws', async function () {
+    const { session, calls } = createSession('s2b');
+    session.resources.clearSession = () => {
+      calls.push('clear:s2b');
+      throw new Error('clear fail');
+    };
+
+    await disposeSessionRuntime(session);
+    expect(calls).to.deep.equal(['clear:s2b', 'context.close', 'browser.close']);
+  });
+
+  it('continues cleanup when spectator/watch hooks throw', async function () {
+    const { session, calls } = createSession('s3');
+    await disposeSessionRuntime(session, {
+      stopSpectatorServer() {
+        throw new Error('spectator fail');
+      },
+      stopWatchLoop() {
+        throw new Error('watch fail');
+      }
+    });
+    expect(calls).to.deep.equal(['clear:s3', 'context.close', 'browser.close']);
+  });
+
+  it('disposes all sessions from an iterable', async function () {
+    const first = createSession('a');
+    const second = createSession('b');
+    await disposeAllSessionRuntimes([first.session, second.session]);
+
+    expect(first.calls).to.include.members(['clear:a', 'context.close', 'browser.close']);
+    expect(second.calls).to.include.members(['clear:b', 'context.close', 'browser.close']);
+  });
+
+  it('disposes multiple sessions concurrently', async function () {
+    const first = createSession('p1');
+    const second = createSession('p2');
+    const starts = [];
+    let resolveFirst;
+    let resolveSecond;
+
+    first.session.watchController = {
+      stopAndWait() {
+        starts.push('p1');
+        return new Promise((resolve) => {
+          resolveFirst = resolve;
+        });
+      }
+    };
+    second.session.watchController = {
+      stopAndWait() {
+        starts.push('p2');
+        return new Promise((resolve) => {
+          resolveSecond = resolve;
+        });
+      }
+    };
+
+    const disposing = disposeAllSessionRuntimes([first.session, second.session]);
+    for (let i = 0; i < 8 && starts.length < 2; i += 1) {
+      await Promise.resolve();
+    }
+    expect(starts).to.have.members(['p1', 'p2']);
+
+    resolveFirst();
+    resolveSecond();
+    await disposing;
+    expect(first.calls).to.include('clear:p1');
+    expect(second.calls).to.include('clear:p2');
+  });
+
+  it('waits for watch controller shutdown before clearing resources', async function () {
+    const { session } = createSession('w1');
+    const order = [];
+    session.watchController = {
+      async stopAndWait() {
+        order.push('watch:stop-start');
+        await Promise.resolve();
+        order.push('watch:stop-end');
+      }
+    };
+    session.resources.clearSession = () => {
+      order.push('clear');
+    };
+
+    await disposeSessionRuntime(session, {
+      stopWatchLoop() {
+        order.push('hook:watch');
+      }
+    });
+
+    expect(order).to.deep.equal([
+      'hook:watch',
+      'watch:stop-start',
+      'watch:stop-end',
+      'clear'
+    ]);
+  });
+});
diff --git a/test/mcp-session-store.test.js b/test/mcp-session-store.test.js
new file mode 100644
index 00000000..b15109b6
--- /dev/null
+++ b/test/mcp-session-store.test.js
@@ -0,0 +1,42 @@
+import { expect } from 'chai';
+import { getSession, normalizeSessionId, sessions } from '../mcp/sessionStore.js';
+
+describe('mcp session store', function () {
+  beforeEach(function () {
+    sessions.clear();
+  });
+
+  afterEach(function () {
+    sessions.clear();
+  });
+
+  it('resolves an existing session by id', function () {
+    const session = { id: 'abc123' };
+    sessions.set('abc123', session);
+    expect(getSession('abc123')).to.equal(session);
+  });
+
+  it('normalizes non-string ids before lookup', function () {
+    const session = { id: '7' };
+    sessions.set('7', session);
+    expect(getSession(7)).to.equal(session);
+  });
+
+  it('trims surrounding whitespace from ids before lookup', function () {
+    const session = { id: 'alpha' };
+    sessions.set('alpha', session);
+    expect(getSession('  alpha  ')).to.equal(session);
+  });
+
+  it('throws when id is missing or session does not exist', function () {
+    expect(() => getSession('')).to.throw('Session id is required');
+    expect(() => getSession(null)).to.throw('Session id is required');
+    expect(() => getSession('missing')).to.throw('Session not found: missing');
+  });
+
+  it('normalizes ids with trimming and null handling', function () {
+    expect(normalizeSessionId('  abc  ')).to.equal('abc');
+    expect(normalizeSessionId(7)).to.equal('7');
+    expect(normalizeSessionId(null)).to.equal('');
+  });
+});
diff --git a/test/mcp-shutdown-controller.test.js b/test/mcp-shutdown-controller.test.js
new file mode 100644
index 00000000..03a4d245
--- /dev/null
+++ b/test/mcp-shutdown-controller.test.js
@@ -0,0 +1,83 @@
+import { expect } from 'chai';
+import { createShutdownController } from '../mcp/shutdownController.js';
+
+describe('mcp shutdown controller', function () {
+  it('runs shutdown steps once and in order for repeated calls', async function () {
+    const calls = [];
+    let disposed = 0;
+    let closedServer = 0;
+    let closedTransport = 0;
+    const controller = createShutdownController({
+      disposeSessions: async () => {
+        disposed += 1;
+        calls.push('dispose');
+      },
+      closeServer: async () => {
+        closedServer += 1;
+        calls.push('server');
+      },
+      closeTransport: async () => {
+        closedTransport += 1;
+        calls.push('transport');
+      }
+    });
+
+    await Promise.all([
+      controller.shutdown('SIGINT'),
+      controller.shutdown('SIGTERM'),
+      controller.shutdown('manual')
+    ]);
+
+    expect(disposed).to.equal(1);
+    expect(closedServer).to.equal(1);
+    expect(closedTransport).to.equal(1);
+    expect(calls).to.deep.equal(['dispose', 'server', 'transport']);
+  });
+
+  it('sets process exit code and logs when shutdown fails', async function () {
+    const loggerCalls = [];
+    const originalExitCode = process.exitCode;
+    process.exitCode = 0;
+    const controller = createShutdownController({
+      disposeSessions: async () => {
+        throw new Error('boom');
+      },
+      logger: {
+        error: (...args) => loggerCalls.push(args)
+      }
+    });
+
+    controller.handleSignal('SIGINT');
+    await new Promise((resolve) => {
+      setTimeout(resolve, 0);
+    });
+
+    expect(process.exitCode).to.equal(1);
+    expect(loggerCalls.length).to.equal(1);
+    expect(String(loggerCalls[0][0])).to.include('SIGINT');
+    process.exitCode = originalExitCode;
+  });
+
+  it('still sets exit code when logger.error throws', async function () {
+    const originalExitCode = process.exitCode;
+    process.exitCode = 0;
+    const controller = createShutdownController({
+      disposeSessions: async () => {
+        throw new Error('boom');
+      },
+      logger: {
+        error: () => {
+          throw new Error('logger boom');
+        }
+      }
+    });
+
+    controller.handleSignal('SIGTERM');
+    await new Promise((resolve) => {
+      setTimeout(resolve, 0);
+    });
+
+    expect(process.exitCode).to.equal(1);
+    process.exitCode = originalExitCode;
+  });
+});
diff --git a/test/mcp-solver-tools.test.js b/test/mcp-solver-tools.test.js
new file mode 100644
index 00000000..3f781ad3
--- /dev/null
+++ b/test/mcp-solver-tools.test.js
@@ -0,0 +1,52 @@
+import { expect } from 'chai';
+import {
+  SolverReplaySchema,
+  SolverRouteSchema,
+  SolverSnapshotSchema
+} from '../mcp/schemas.js';
+import { createSolverToolHandlers } from '../mcp/solverTools.js';
+import { createFlatWalkFixture } from '../js/solver/SolverFixtures.js';
+import { SOLVER_RESULT_TYPES } from '../js/solver/SolverTypes.js';
+
+describe('mcp solver tools', function() {
+  const handlers = createSolverToolHandlers({
+    schemas: {
+      SolverSnapshotSchema,
+      SolverRouteSchema,
+      SolverReplaySchema
+    }
+  });
+
+  it('returns compact snapshot hashes without terrain masks', async function() {
+    const payload = await handlers.solverSnapshotTool({
+      source: createFlatWalkFixture()
+    });
+
+    expect(payload.ok).to.equal(true);
+    expect(payload.snapshot).to.include({
+      kind: 'solver-state',
+      id: 'flat-walk'
+    });
+    expect(payload.snapshot.terrain?.mask).to.equal(undefined);
+    expect(payload.snapshot.counts.entrances).to.equal(1);
+  });
+
+  it('routes and replays through compact solver MCP payloads', async function() {
+    const route = await handlers.solverRouteTool({
+      source: createFlatWalkFixture(),
+      options: { maxNodes: 50 }
+    });
+    expect(route.ok).to.equal(true);
+    expect(route.resultType).to.equal(SOLVER_RESULT_TYPES.UNKNOWN);
+    expect(route.routeSkeleton).to.not.equal(null);
+
+    const replay = await handlers.solverReplayTool({
+      source: createFlatWalkFixture(),
+      actions: [],
+      options: { maxTicks: 140, targetSaveCount: 1 }
+    });
+    expect(replay.ok).to.equal(true);
+    expect(replay.result.resultType).to.equal(SOLVER_RESULT_TYPES.SOLVED);
+    expect(replay.result.replaySummary.savedCount).to.equal(1);
+  });
+});
diff --git a/test/mcp-spectator-broadcaster.test.js b/test/mcp-spectator-broadcaster.test.js
new file mode 100644
index 00000000..de126656
--- /dev/null
+++ b/test/mcp-spectator-broadcaster.test.js
@@ -0,0 +1,152 @@
+import { expect } from 'chai';
+import {
+  SpectatorBroadcaster,
+  SPECTATOR_SKIP_POLICIES,
+  normalizeSpectatorStreamConfig
+} from '../mcp/spectatorBroadcaster.js';
+
+class FakeSocket {
+  constructor() {
+    this.readyState = 1;
+    this.sent = [];
+    this.pendingCallbacks = [];
+    this.deferCallbacks = false;
+  }
+
+  send(data, callback) {
+    this.sent.push(data);
+    if (this.deferCallbacks) {
+      this.pendingCallbacks.push(callback);
+      return;
+    }
+    if (typeof callback === 'function') {
+      callback();
+    }
+  }
+
+  flush() {
+    const callbacks = this.pendingCallbacks.slice();
+    this.pendingCallbacks = [];
+    for (const callback of callbacks) {
+      if (typeof callback === 'function') {
+        callback();
+      }
+    }
+  }
+
+  close() {
+    this.readyState = 3;
+  }
+}
+
+describe('SpectatorBroadcaster', function () {
+  it('keeps only the latest pending frame for slow clients in latest mode', function () {
+    const broadcaster = new SpectatorBroadcaster({
+      frameSkipPolicy: SPECTATOR_SKIP_POLICIES.LATEST
+    });
+    const socket = new FakeSocket();
+    socket.deferCallbacks = true;
+    broadcaster.attach(socket);
+
+    broadcaster.broadcast({ frame: 1 });
+    broadcaster.broadcast({ frame: 2 });
+    broadcaster.broadcast({ frame: 3 });
+
+    expect(socket.sent).to.have.lengthOf(1);
+    socket.flush();
+    expect(socket.sent).to.have.lengthOf(2);
+    expect(JSON.parse(socket.sent[0]).frame).to.equal(1);
+    expect(JSON.parse(socket.sent[1]).frame).to.equal(3);
+
+    const snapshot = broadcaster.getSnapshot();
+    expect(snapshot.droppedFrames).to.equal(1);
+  });
+
+  it('sends every frame in none mode', function () {
+    const broadcaster = new SpectatorBroadcaster({
+      frameSkipPolicy: SPECTATOR_SKIP_POLICIES.NONE
+    });
+    const socket = new FakeSocket();
+    socket.deferCallbacks = true;
+    broadcaster.attach(socket);
+
+    broadcaster.broadcast({ frame: 1 });
+    broadcaster.broadcast({ frame: 2 });
+    broadcaster.broadcast({ frame: 3 });
+
+    expect(socket.sent).to.have.lengthOf(3);
+  });
+
+  it('queues and delivers empty-string payloads in latest mode', function () {
+    const broadcaster = new SpectatorBroadcaster({
+      frameSkipPolicy: SPECTATOR_SKIP_POLICIES.LATEST
+    });
+    const socket = new FakeSocket();
+    socket.deferCallbacks = true;
+    broadcaster.attach(socket);
+
+    broadcaster.broadcast('first');
+    broadcaster.broadcast('');
+
+    expect(socket.sent).to.deep.equal(['first']);
+    socket.flush();
+    expect(socket.sent).to.deep.equal(['first', '']);
+  });
+
+  it('deduplicates repeat attachment of the same socket', function () {
+    const broadcaster = new SpectatorBroadcaster({
+      frameSkipPolicy: SPECTATOR_SKIP_POLICIES.NONE
+    });
+    const socket = new FakeSocket();
+    broadcaster.attach(socket);
+    broadcaster.attach(socket);
+
+    broadcaster.broadcast({ frame: 1 });
+    expect(socket.sent).to.have.lengthOf(1);
+    expect(broadcaster.getSnapshot().connectedClients).to.equal(1);
+  });
+
+  it('skips payloads that cannot be serialized to JSON', function () {
+    const broadcaster = new SpectatorBroadcaster();
+    const socket = new FakeSocket();
+    broadcaster.attach(socket);
+
+    expect(() => broadcaster.broadcast({ value: BigInt(1) })).to.not.throw();
+    expect(socket.sent).to.have.lengthOf(0);
+  });
+
+  it('normalizes spectator stream settings to safe bounds', function () {
+    const normalized = normalizeSpectatorStreamConfig({
+      frameIntervalMs: 10,
+      jpegQuality: 999,
+      frameSkipPolicy: 'invalid'
+    });
+    expect(normalized.frameIntervalMs).to.equal(50);
+    expect(normalized.jpegQuality).to.equal(100);
+    expect(normalized.frameSkipPolicy).to.equal(SPECTATOR_SKIP_POLICIES.LATEST);
+  });
+
+  it('accepts case-insensitive skip policy and non-coercible numeric config values', function () {
+    const normalized = normalizeSpectatorStreamConfig({
+      frameIntervalMs: Symbol('interval'),
+      jpegQuality: Symbol('quality'),
+      frameSkipPolicy: ' NONE '
+    });
+    expect(normalized.frameIntervalMs).to.equal(500);
+    expect(normalized.jpegQuality).to.equal(60);
+    expect(normalized.frameSkipPolicy).to.equal(SPECTATOR_SKIP_POLICIES.NONE);
+  });
+
+  it('closes and removes all tracked sockets during cleanup', function () {
+    const broadcaster = new SpectatorBroadcaster();
+    const first = new FakeSocket();
+    const second = new FakeSocket();
+    broadcaster.attach(first);
+    broadcaster.attach(second);
+    broadcaster.closeAll();
+
+    expect(first.readyState).to.equal(3);
+    expect(second.readyState).to.equal(3);
+    expect(broadcaster.getSnapshot().connectedClients).to.equal(0);
+  });
+});
diff --git a/test/mcp-spectator-tools.test.js b/test/mcp-spectator-tools.test.js
new file mode 100644
index 00000000..54bf14d8
--- /dev/null
+++ b/test/mcp-spectator-tools.test.js
@@ -0,0 +1,262 @@
+import { expect } from 'chai';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { WebSocket } from 'ws';
+import { createSpectatorTools } from '../mcp/spectatorTools.js';
+
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+const waitFor = async (predicate, timeoutMs = 2000) => {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (predicate()) return;
+    await delay(20);
+  }
+  throw new Error('Timed out while waiting for condition.');
+};
+
+const connectSocket = async (url) => {
+  const ws = new WebSocket(url);
+  await new Promise((resolve, reject) => {
+    const onOpen = () => {
+      ws.off('error', onError);
+      resolve();
+    };
+    const onError = (error) => {
+      ws.off('open', onOpen);
+      reject(error);
+    };
+    ws.once('open', onOpen);
+    ws.once('error', onError);
+  });
+  return ws;
+};
+
+describe('mcp spectator tools', function () {
+  let tempDir = '';
+  let spectatorHtmlPath = '';
+
+  beforeEach(async function () {
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'lemmings-mcp-spectator-'));
+    spectatorHtmlPath = path.join(tempDir, 'spectator.html');
+    await fs.writeFile(spectatorHtmlPath, '<!doctype html><html><body>spectator</body></html>', 'utf8');
+  });
+
+  afterEach(async function () {
+    if (tempDir) {
+      await fs.rm(tempDir, { recursive: true, force: true });
+    }
+    tempDir = '';
+    spectatorHtmlPath = '';
+  });
+
+  it('streams frames and handles human keyboard/mouse input when enabled', async function () {
+    const capturedEvents = [];
+    const keyCalls = [];
+    const mouseClicks = [];
+    let captureCalls = 0;
+    let focusCalls = 0;
+
+    const { startSpectatorServer, stopSpectatorServer } = createSpectatorTools({
+      spectatorHtmlPath,
+      captureFrame: async () => {
+        captureCalls += 1;
+        return {
+          ok: true,
+          frame: {
+            mimeType: 'image/jpeg',
+            dataBase64: 'ZmFrZQ==',
+            tickIndex: 7,
+            takenAt: 'now'
+          }
+        };
+      },
+      resolveCanvasMetrics: async () => ({ rect: { x: 10, y: 20, width: 200, height: 100 } }),
+      normalizeKeyToken: (token) => token,
+      ensureGameFocus: async () => { focusCalls += 1; }
+    });
+
+    const session = {
+      page: {
+        keyboard: {
+          down: async (key) => { keyCalls.push(['down', key]); },
+          up: async (key) => { keyCalls.push(['up', key]); },
+          press: async (key) => { keyCalls.push(['press', key]); }
+        },
+        mouse: {
+          click: async (x, y) => { mouseClicks.push([x, y]); }
+        }
+      },
+      events: {
+        add: (event) => capturedEvents.push(event)
+      },
+      spectator: null
+    };
+
+    const baseUrl = await startSpectatorServer(session, {
+      port: 0,
+      allowHumanInput: true,
+      frameIntervalMs: 50
+    });
+
+    const ws = await connectSocket(baseUrl.replace('http://', 'ws://'));
+    await waitFor(() => captureCalls > 0);
+    expect(captureCalls).to.be.greaterThan(0);
+
+    ws.send(JSON.stringify({ type: 'key', action: 'press', key: 'A' }));
+    ws.send(JSON.stringify({ type: 'key', action: 'press', key: '   ' }));
+    ws.send(JSON.stringify({ type: 'click', x: 0.5, y: 0.5 }));
+    ws.send(JSON.stringify({ type: 'click', x: 1, y: 1 }));
+    await waitFor(() => keyCalls.length === 1 && mouseClicks.length === 2);
+
+    expect(focusCalls).to.equal(1);
+    expect(keyCalls).to.deep.equal([['press', 'A']]);
+    expect(mouseClicks[0][0]).to.equal(110);
+    expect(mouseClicks[0][1]).to.equal(70);
+    expect(mouseClicks[1][0]).to.equal(209);
+    expect(mouseClicks[1][1]).to.equal(119);
+    expect(capturedEvents.some((event) => event.summary === 'key:press:A')).to.equal(true);
+    expect(capturedEvents.some((event) => event.summary?.startsWith('click:'))).to.equal(true);
+
+    ws.close();
+    await new Promise((resolve) => ws.once('close', resolve));
+    stopSpectatorServer(session);
+    expect(session.spectator).to.equal(null);
+  });
+
+  it('ignores inbound human input when allowHumanInput is disabled', async function () {
+    const keyCalls = [];
+    const mouseClicks = [];
+    const { startSpectatorServer, stopSpectatorServer } = createSpectatorTools({
+      spectatorHtmlPath,
+      captureFrame: async () => ({ ok: false, reason: 'capture_disabled' }),
+      resolveCanvasMetrics: async () => ({ rect: { x: 0, y: 0, width: 100, height: 100 } }),
+      normalizeKeyToken: (token) => token,
+      ensureGameFocus: async () => {}
+    });
+
+    const session = {
+      page: {
+        keyboard: {
+          down: async (key) => { keyCalls.push(['down', key]); },
+          up: async (key) => { keyCalls.push(['up', key]); },
+          press: async (key) => { keyCalls.push(['press', key]); }
+        },
+        mouse: {
+          click: async (x, y) => { mouseClicks.push([x, y]); }
+        }
+      },
+      events: { add() {} },
+      spectator: null
+    };
+
+    const baseUrl = await startSpectatorServer(session, {
+      port: 0,
+      allowHumanInput: false,
+      frameIntervalMs: 50
+    });
+    const ws = await connectSocket(baseUrl.replace('http://', 'ws://'));
+    ws.send(JSON.stringify({ type: 'key', action: 'press', key: 'A' }));
+    ws.send(JSON.stringify({ type: 'click', x: 0.5, y: 0.5 }));
+    await delay(100);
+
+    expect(keyCalls).to.deep.equal([]);
+    expect(mouseClicks).to.deep.equal([]);
+
+    ws.close();
+    await new Promise((resolve) => ws.once('close', resolve));
+    stopSpectatorServer(session);
+  });
+
+  it('normalizes invalid spectator ports to ephemeral listeners', async function () {
+    const { startSpectatorServer, stopSpectatorServer } = createSpectatorTools({
+      spectatorHtmlPath,
+      captureFrame: async () => ({ ok: false, reason: 'capture_disabled' }),
+      resolveCanvasMetrics: async () => ({ rect: { x: 0, y: 0, width: 100, height: 100 } }),
+      normalizeKeyToken: (token) => token,
+      ensureGameFocus: async () => {}
+    });
+
+    const session = {
+      page: {
+        keyboard: {
+          down: async () => {},
+          up: async () => {},
+          press: async () => {}
+        },
+        mouse: {
+          click: async () => {}
+        }
+      },
+      events: { add() {} },
+      spectator: null
+    };
+
+    const firstUrl = await startSpectatorServer(session, {
+      port: -123.8,
+      allowHumanInput: false,
+      frameIntervalMs: 50
+    });
+    expect(firstUrl).to.match(/^http:\/\/127\.0\.0\.1:\d+$/);
+    stopSpectatorServer(session);
+
+    const secondUrl = await startSpectatorServer(session, {
+      port: 70000,
+      allowHumanInput: false,
+      frameIntervalMs: 50
+    });
+    expect(secondUrl).to.match(/^http:\/\/127\.0\.0\.1:\d+$/);
+    stopSpectatorServer(session);
+
+    const thirdUrl = await startSpectatorServer(session, {
+      port: Symbol('port'),
+      allowHumanInput: false,
+      frameIntervalMs: 50
+    });
+    expect(thirdUrl).to.match(/^http:\/\/127\.0\.0\.1:\d+$/);
+    stopSpectatorServer(session);
+  });
+
+  it('clamps click offsets for tiny fractional canvas metrics', async function () {
+    const mouseClicks = [];
+    const { startSpectatorServer, stopSpectatorServer } = createSpectatorTools({
+      spectatorHtmlPath,
+      captureFrame: async () => ({ ok: false, reason: 'capture_disabled' }),
+      resolveCanvasMetrics: async () => ({ rect: { x: 10, y: 20, width: 0.25, height: 0.5 } }),
+      normalizeKeyToken: (token) => token,
+      ensureGameFocus: async () => {}
+    });
+
+    const session = {
+      page: {
+        keyboard: {
+          down: async () => {},
+          up: async () => {},
+          press: async () => {}
+        },
+        mouse: {
+          click: async (x, y) => { mouseClicks.push([x, y]); }
+        }
+      },
+      events: { add() {} },
+      spectator: null
+    };
+
+    const baseUrl = await startSpectatorServer(session, {
+      port: 0,
+      allowHumanInput: true,
+      frameIntervalMs: 50
+    });
+    const ws = await connectSocket(baseUrl.replace('http://', 'ws://'));
+    ws.send(JSON.stringify({ type: 'click', x: 1, y: 1 }));
+    await waitFor(() => mouseClicks.length === 1);
+
+    expect(mouseClicks[0][0]).to.equal(10);
+    expect(mouseClicks[0][1]).to.equal(20);
+
+    ws.close();
+    await new Promise((resolve) => ws.once('close', resolve));
+    stopSpectatorServer(session);
+  });
+});
diff --git a/test/mcp-state-tools.test.js b/test/mcp-state-tools.test.js
new file mode 100644
index 00000000..5168225b
--- /dev/null
+++ b/test/mcp-state-tools.test.js
@@ -0,0 +1,425 @@
+import { expect } from 'chai';
+import { createStateToolHandlers } from '../mcp/stateTools.js';
+
+const createFixture = ({
+  currentTick = 0,
+  deltas = [],
+  state = null,
+  resourcePut = () => null
+} = {}) => {
+  const session = {
+    id: 's1',
+    resources: { put: (...args) => resourcePut(...args) },
+    lastStateTick: null
+  };
+  const captured = [];
+  const handlers = createStateToolHandlers({
+    schemas: {
+      StateGetSchema: {
+        parse(args = {}) {
+          return { sessionId: 's1', ...args };
+        }
+      },
+      StateDeltaSchema: {
+        parse(args = {}) {
+          return { sessionId: 's1', ...args };
+        }
+      },
+      LemmingsSummarySchema: {
+        parse(args = {}) {
+          return { sessionId: 's1', ...args };
+        }
+      }
+    },
+    attachEvents(_session, payload) {
+      return payload;
+    },
+    getSession() {
+      return session;
+    },
+    async callE2E(_session, method, startTick, endTick, limit) {
+      captured.push({ method, startTick, endTick, limit });
+      return { ok: true, value: deltas };
+    },
+    async getState() {
+      return state;
+    },
+    async getTickIndex() {
+      return currentTick;
+    },
+    nudgeWatchPolling() {},
+    helpers: {
+      filterStateSnapshot(state) {
+        return state;
+      },
+      buildSkillInfo() {
+        return null;
+      },
+      buildLemmingPrunePolicy() {
+        return null;
+      },
+      buildLemmingSummary() {
+        return {};
+      },
+      buildLemmingSummaryCompact() {
+        return {};
+      },
+      pruneLemming(lemming) {
+        return lemming;
+      }
+    },
+    defaultLemDeltaFields: [0, 1]
+  });
+
+  return {
+    handlers,
+    session,
+    getCaptured() {
+      return captured;
+    }
+  };
+};
+
+describe('state tools', function () {
+  it('clamps toTick to the current tick before requesting deltas', async function () {
+    const fixture = createFixture({ currentTick: 12, deltas: [] });
+
+    const result = await fixture.handlers.getStateDeltaTool({
+      sessionId: 's1',
+      afterTick: 8,
+      toTick: 99,
+      maxTicks: 50
+    });
+
+    expect(fixture.getCaptured()).to.have.lengthOf(1);
+    expect(fixture.getCaptured()[0]).to.include({
+      method: 'getDeltas',
+      startTick: 9,
+      endTick: 12,
+      limit: 50
+    });
+    expect(result.cursor).to.equal(12);
+    expect(result.toTick).to.equal(12);
+  });
+
+  it('preserves the provided cursor when afterTick is ahead of current tick', async function () {
+    const fixture = createFixture({ currentTick: 10, deltas: [] });
+
+    const result = await fixture.handlers.getStateDeltaTool({
+      sessionId: 's1',
+      afterTick: 20
+    });
+
+    expect(fixture.getCaptured()).to.have.lengthOf(0);
+    expect(result).to.include({
+      ok: true,
+      cursor: 20,
+      afterTick: 20,
+      toTick: 10
+    });
+    expect(result.deltas).to.deep.equal([]);
+  });
+
+  it('normalizes negative ranges to start at tick zero', async function () {
+    const fixture = createFixture({ currentTick: 7, deltas: [] });
+
+    await fixture.handlers.getStateDeltaTool({
+      sessionId: 's1',
+      afterTick: -12,
+      toTick: 2,
+      maxTicks: 20
+    });
+
+    expect(fixture.getCaptured()).to.have.lengthOf(1);
+    expect(fixture.getCaptured()[0]).to.include({
+      method: 'getDeltas',
+      startTick: 0,
+      endTick: 2,
+      limit: 20
+    });
+  });
+
+  it('uses integer session lastStateTick when afterTick is omitted', async function () {
+    const fixture = createFixture({ currentTick: 11, deltas: [] });
+    fixture.session.lastStateTick = 5.9;
+
+    await fixture.handlers.getStateDeltaTool({
+      sessionId: 's1',
+      maxTicks: 20
+    });
+
+    expect(fixture.getCaptured()).to.have.lengthOf(1);
+    expect(fixture.getCaptured()[0].startTick).to.equal(6);
+    expect(fixture.getCaptured()[0].endTick).to.equal(11);
+  });
+
+  it('caps state.get ids mode payload size for large id lists', async function () {
+    const total = 6005;
+    const fixture = createFixture({
+      currentTick: 12,
+      state: {
+        version: 1,
+        mode: 'play',
+        ready: true,
+        game: {
+          timer: { tickIndex: 12, running: true, speedFactor: 1 },
+          lemmingManager: { selectedIndex: 0, activeCount: total, totalCount: total },
+          lemmings: Array.from({ length: total }, (_, id) => ({ id, x: id, y: 0 }))
+        }
+      }
+    });
+
+    const result = await fixture.handlers.getStateTool({
+      sessionId: 's1',
+      lemmings: {
+        mode: 'ids',
+        ids: Array.from({ length: total }, (_, id) => id)
+      }
+    });
+
+    expect(result.ok).to.equal(true);
+    expect(result.snapshot.game.lemmingsIds).to.have.lengthOf(5000);
+    expect(result.snapshot.game.lemmings).to.have.lengthOf(5000);
+  });
+
+  it('filters duplicate and out-of-range ids in state.get ids mode', async function () {
+    const fixture = createFixture({
+      currentTick: 12,
+      state: {
+        version: 1,
+        mode: 'play',
+        ready: true,
+        game: {
+          timer: { tickIndex: 12, running: true, speedFactor: 1 },
+          lemmingManager: { selectedIndex: 0, activeCount: 3, totalCount: 3 },
+          lemmings: [
+            { id: 0, x: 0, y: 0 },
+            { id: 1, x: 1, y: 1 },
+            { id: 2, x: 2, y: 2 }
+          ]
+        }
+      }
+    });
+
+    const result = await fixture.handlers.getStateTool({
+      sessionId: 's1',
+      lemmings: {
+        mode: 'ids',
+        ids: [2, 2, -1, 999, 0]
+      }
+    });
+
+    expect(result.ok).to.equal(true);
+    expect(result.snapshot.game.lemmingsIds).to.deep.equal([2, 0]);
+    expect(result.snapshot.game.lemmings.map((lem) => lem.id)).to.deep.equal([2, 0]);
+  });
+
+  it('caps state.get all mode max to protect snapshot size', async function () {
+    const total = 6005;
+    const fixture = createFixture({
+      currentTick: 12,
+      state: {
+        version: 1,
+        mode: 'play',
+        ready: true,
+        game: {
+          timer: { tickIndex: 12, running: true, speedFactor: 1 },
+          lemmingManager: { selectedIndex: 0, activeCount: total, totalCount: total },
+          lemmings: Array.from({ length: total }, (_, id) => ({ id, x: id, y: 0 }))
+        }
+      }
+    });
+
+    const result = await fixture.handlers.getStateTool({
+      sessionId: 's1',
+      lemmings: {
+        mode: 'all',
+        max: 999999
+      }
+    });
+
+    expect(result.ok).to.equal(true);
+    expect(result.snapshot.game.lemmings).to.have.lengthOf(5000);
+  });
+
+  it('caps maxTicks to avoid oversized delta fetches', async function () {
+    const fixture = createFixture({ currentTick: 10000, deltas: [] });
+
+    await fixture.handlers.getStateDeltaTool({
+      sessionId: 's1',
+      afterTick: 0,
+      toTick: 10000,
+      maxTicks: 999999
+    });
+
+    expect(fixture.getCaptured()).to.have.lengthOf(1);
+    expect(fixture.getCaptured()[0]).to.include({
+      method: 'getDeltas',
+      startTick: 8001,
+      endTick: 10000,
+      limit: 2000
+    });
+  });
+
+  it('caps maxChanges and truncates oversized lemming delta arrays', async function () {
+    const totalChanges = 6005;
+    const fixture = createFixture({
+      currentTick: 12,
+      deltas: [{
+        tick: 12,
+        lemChanges: {
+          ids: Array.from({ length: totalChanges }, (_, index) => index),
+          fields: Array.from({ length: totalChanges }, () => 4),
+          next: Array.from({ length: totalChanges }, (_, index) => index)
+        }
+      }]
+    });
+
+    const result = await fixture.handlers.getStateDeltaTool({
+      sessionId: 's1',
+      afterTick: 11,
+      lemmings: {
+        fields: [4],
+        maxChanges: 999999
+      }
+    });
+
+    expect(result.ok).to.equal(true);
+    expect(result.deltas).to.have.lengthOf(1);
+    expect(result.deltas[0].lemChanges.ids).to.have.lengthOf(5000);
+    expect(result.deltas[0].lemChanges.fields).to.have.lengthOf(5000);
+    expect(result.deltas[0].lemChanges.next).to.have.lengthOf(5000);
+  });
+
+  it('returns resource_store_failed when getState resource delivery cannot persist', async function () {
+    const fixture = createFixture({
+      currentTick: 11,
+      state: {
+        version: 1,
+        mode: 'play',
+        ready: true,
+        game: {
+          timer: { tickIndex: 11, running: true, speedFactor: 1 },
+          lemmingManager: { selectedIndex: 0, activeCount: 0, totalCount: 0 },
+          lemmings: []
+        }
+      },
+      resourcePut: () => null
+    });
+
+    const result = await fixture.handlers.getStateTool({
+      sessionId: 's1',
+      format: { delivery: 'resource' }
+    });
+
+    expect(result).to.deep.equal({
+      ok: false,
+      reason: 'resource_store_failed'
+    });
+  });
+
+  it('returns resource_store_failed when getStateDelta resource delivery cannot persist', async function () {
+    const fixture = createFixture({
+      currentTick: 12,
+      deltas: [],
+      resourcePut: () => null
+    });
+
+    const result = await fixture.handlers.getStateDeltaTool({
+      sessionId: 's1',
+      afterTick: 10,
+      format: { delivery: 'resource' }
+    });
+
+    expect(result).to.deep.equal({
+      ok: false,
+      reason: 'resource_store_failed'
+    });
+  });
+
+  it('returns snapshot_serialize_failed when state snapshots cannot be serialized', async function () {
+    const fixture = createFixture({
+      currentTick: 12,
+      state: {
+        version: 1n,
+        mode: 'play',
+        ready: true,
+        game: {
+          timer: { tickIndex: 12, running: true, speedFactor: 1 },
+          lemmingManager: { selectedIndex: 0, activeCount: 0, totalCount: 0 },
+          lemmings: []
+        }
+      },
+      resourcePut: () => {
+        throw new Error('resourcePut should not be reached for unserializable payloads');
+      }
+    });
+
+    const result = await fixture.handlers.getStateTool({
+      sessionId: 's1',
+      format: { delivery: 'resource' }
+    });
+
+    expect(result).to.deep.equal({
+      ok: false,
+      reason: 'snapshot_serialize_failed'
+    });
+  });
+
+  it('returns delta_serialize_failed when delta payloads cannot be serialized', async function () {
+    const fixture = createFixture({
+      currentTick: 12,
+      deltas: [{
+        tick: 12,
+        lemChanges: {
+          ids: [1],
+          fields: [4],
+          next: [1n]
+        }
+      }],
+      resourcePut: () => {
+        throw new Error('resourcePut should not be reached for unserializable payloads');
+      }
+    });
+
+    const result = await fixture.handlers.getStateDeltaTool({
+      sessionId: 's1',
+      afterTick: 11,
+      lemmings: { fields: [4] },
+      format: { delivery: 'resource' }
+    });
+
+    expect(result).to.deep.equal({
+      ok: false,
+      reason: 'delta_serialize_failed'
+    });
+  });
+
+  it('omits prev arrays when includePrev is requested but source deltas do not provide prev values', async function () {
+    const fixture = createFixture({
+      currentTick: 12,
+      deltas: [{
+        tick: 12,
+        lemChanges: {
+          ids: [1],
+          fields: [4],
+          next: [9]
+        }
+      }]
+    });
+
+    const result = await fixture.handlers.getStateDeltaTool({
+      sessionId: 's1',
+      afterTick: 11,
+      lemmings: { includePrev: true, fields: [4] }
+    });
+
+    expect(result.ok).to.equal(true);
+    expect(result.deltas).to.have.lengthOf(1);
+    expect(result.deltas[0].lemChanges).to.deep.equal({
+      ids: [1],
+      fields: [4],
+      next: [9]
+    });
+  });
+});
diff --git a/test/mcp-tool-routing.test.js b/test/mcp-tool-routing.test.js
new file mode 100644
index 00000000..27cf5833
--- /dev/null
+++ b/test/mcp-tool-routing.test.js
@@ -0,0 +1,78 @@
+import { expect } from 'chai';
+import {
+  buildToolCatalog,
+  resolveToolName
+} from '../mcp/toolRouting.js';
+
+describe('mcp tool routing helpers', function () {
+  it('trims canonical tool names directly', function () {
+    expect(resolveToolName('  editor_apply  ')).to.equal('editor_apply');
+    expect(resolveToolName(0)).to.equal('0');
+    expect(resolveToolName(null)).to.equal('');
+  });
+
+  it('builds route catalog for all tools while filtering list definitions by active surfaces', function () {
+    const gameHandler = () => ({ ok: true });
+    const editorHandler = () => ({ ok: true });
+    const registry = {
+      specs: [
+        { name: 'game.state.get', description: 'game', schema: { type: 'object' } },
+        { name: 'editor.apply', description: 'editor', schema: { type: 'object' } }
+      ],
+      handlersBySurface: new Map([
+        ['game', new Map([['game.state.get', gameHandler]])],
+        ['editor', new Map([['editor.apply', editorHandler]])]
+      ]),
+      toolSurfaceByName: new Map([
+        ['game.state.get', 'game'],
+        ['editor.apply', 'editor']
+      ])
+    };
+
+    const { toolDefs, toolRoutes } = buildToolCatalog(registry, {
+      activeSurfaces: new Set(['game']),
+      toToolName: (name) => name.replace(/\./g, '_'),
+      toJsonSchemaCompat: (schema) => ({ wrapped: schema })
+    });
+
+    expect(toolDefs).to.deep.equal([
+      {
+        name: 'game_state_get',
+        description: 'game',
+        inputSchema: { wrapped: { type: 'object' } }
+      }
+    ]);
+    expect(Array.from(toolRoutes.keys()).sort()).to.deep.equal([
+      'editor_apply',
+      'game_state_get'
+    ]);
+    expect(toolRoutes.get('game_state_get')?.handler).to.equal(gameHandler);
+    expect(toolRoutes.get('editor_apply')?.handler).to.equal(editorHandler);
+    expect(toolRoutes.get('editor_apply')?.surface).to.equal('editor');
+  });
+
+  it('throws when two canonical tool names collide after normalization', function () {
+    const handler = () => ({ ok: true });
+    const registry = {
+      specs: [
+        { name: 'alpha.beta', description: 'first', schema: {} },
+        { name: 'alpha_beta', description: 'second', schema: {} }
+      ],
+      handlersBySurface: new Map([
+        ['game', new Map([
+          ['alpha.beta', handler],
+          ['alpha_beta', handler]
+        ])]
+      ]),
+      toolSurfaceByName: new Map([
+        ['alpha.beta', 'game'],
+        ['alpha_beta', 'game']
+      ])
+    };
+
+    expect(() => buildToolCatalog(registry, {
+      toToolName: (name) => name.replace(/\./g, '_')
+    })).to.throw('Tool name collision');
+  });
+
+});
diff --git a/test/mcp-tool-surfaces.test.js b/test/mcp-tool-surfaces.test.js
new file mode 100644
index 00000000..25d9f087
--- /dev/null
+++ b/test/mcp-tool-surfaces.test.js
@@ -0,0 +1,168 @@
+import { expect } from 'chai';
+import {
+  buildEditorToolHandlers,
+  buildEditorToolSpecs
+} from '../mcp/tools/editor.js';
+import { buildGameToolHandlers } from '../mcp/tools/game.js';
+import { buildInteractToolHandlers } from '../mcp/tools/interact.js';
+import {
+  buildSolverToolHandlers,
+  buildSolverToolSpecs
+} from '../mcp/tools/solver.js';
+import {
+  ALL_TOOL_SURFACES,
+  buildSurfaceRegistry,
+  parseEnabledSurfaces
+} from '../mcp/tools/surfaces.js';
+
+const makeSchemas = () => ({
+  SessionCreateSchema: {},
+  SessionCloseSchema: {},
+  TimeSchema: {},
+  TimeStepSchema: {},
+  StateGetSchema: {},
+  StateDeltaSchema: {},
+  EditorApplySchema: {},
+  ObjectsListSchema: {},
+  ObjectsPlaceSchema: {},
+  ObjectsUpdateSchema: {},
+  ObjectsDeleteSchema: {},
+  LemmingsSummarySchema: {},
+  LemmingSelectSchema: {},
+  SkillApplySchema: {},
+  InputActionSchema: {},
+  InputKeysSchema: {},
+  VisionCaptureSchema: {},
+  VisionSequenceSchema: {},
+  WatchCreateSchema: {},
+  WatchCancelSchema: {},
+  EventsPollSchema: {},
+  SolverSnapshotSchema: {},
+  SolverRouteSchema: {},
+  SolverReplaySchema: {}
+});
+
+const makeHandlers = () => ({
+  createSession: () => {},
+  closeSession: () => {},
+  pauseTime: () => {},
+  resumeTime: () => {},
+  stepTime: () => {},
+  getStateTool: () => {},
+  getStateDeltaTool: () => {},
+  editorApplyTool: () => {},
+  listObjectsTool: () => {},
+  placeObjectsTool: () => {},
+  updateObjectsTool: () => {},
+  deleteObjectsTool: () => {},
+  getLemmingsSummaryTool: () => {},
+  selectLemmingTool: () => {},
+  applySkillTool: () => {},
+  inputActionTool: () => {},
+  inputKeysTool: () => {},
+  visionCaptureTool: () => {},
+  visionSequenceTool: () => {},
+  watchCreateTool: () => {},
+  watchCancelTool: () => {},
+  eventsPollTool: () => {},
+  solverSnapshotTool: () => {},
+  solverRouteTool: () => {},
+  solverReplayTool: () => {}
+});
+
+describe('mcp tool surfaces', function () {
+  it('builds editor specs with typed object verbs and compatibility editor.apply', function () {
+    const names = buildEditorToolSpecs(makeSchemas()).map((spec) => spec.name);
+    expect(names).to.deep.equal([
+      'editor.apply',
+      'objects.list',
+      'objects.place',
+      'objects.update',
+      'objects.delete'
+    ]);
+  });
+
+  it('maps editor handlers for all typed object verbs', function () {
+    const handlers = makeHandlers();
+    const editorHandlers = buildEditorToolHandlers(handlers);
+    expect(editorHandlers.get('editor.apply')).to.equal(handlers.editorApplyTool);
+    expect(editorHandlers.get('objects.list')).to.equal(handlers.listObjectsTool);
+    expect(editorHandlers.get('objects.place')).to.equal(handlers.placeObjectsTool);
+    expect(editorHandlers.get('objects.update')).to.equal(handlers.updateObjectsTool);
+    expect(editorHandlers.get('objects.delete')).to.equal(handlers.deleteObjectsTool);
+  });
+
+  it('throws when required game handlers are missing', function () {
+    expect(() => buildGameToolHandlers({})).to.throw('Missing game tool handler');
+  });
+
+  it('throws when required interact handlers are missing', function () {
+    expect(() => buildInteractToolHandlers({})).to.throw('Missing interact tool handler');
+  });
+
+  it('throws when required editor handlers are missing', function () {
+    expect(() => buildEditorToolHandlers({})).to.throw('Missing editor tool handler');
+  });
+
+  it('builds solver specs and handler routes after local API stabilization', function () {
+    const names = buildSolverToolSpecs(makeSchemas()).map((spec) => spec.name);
+    expect(names).to.deep.equal([
+      'solver.snapshot',
+      'solver.route',
+      'solver.replay'
+    ]);
+
+    const handlers = makeHandlers();
+    const solverHandlers = buildSolverToolHandlers(handlers);
+    expect(solverHandlers.get('solver.snapshot')).to.equal(handlers.solverSnapshotTool);
+    expect(solverHandlers.get('solver.route')).to.equal(handlers.solverRouteTool);
+    expect(solverHandlers.get('solver.replay')).to.equal(handlers.solverReplayTool);
+  });
+
+  it('routes typed editor object verbs to the editor surface', function () {
+    const registry = buildSurfaceRegistry(makeSchemas(), makeHandlers(), new Set(ALL_TOOL_SURFACES));
+    expect(registry.toolSurfaceByName.get('objects.list')).to.equal('editor');
+    expect(registry.toolSurfaceByName.get('objects.place')).to.equal('editor');
+    expect(registry.toolSurfaceByName.get('objects.update')).to.equal('editor');
+    expect(registry.toolSurfaceByName.get('objects.delete')).to.equal('editor');
+  });
+
+  it('supports explicit surface parsing and rejects unknown values', function () {
+    expect(Array.from(parseEnabledSurfaces('game,editor')).sort()).to.deep.equal(['editor', 'game']);
+    expect(() => parseEnabledSurfaces('unknown')).to.throw('Unknown MCP surface');
+  });
+
+  it('enforces semantic-first tool exposure by enabled surfaces', function () {
+    const schemas = makeSchemas();
+    const handlers = makeHandlers();
+
+    const editorOnly = buildSurfaceRegistry(schemas, handlers, new Set(['editor']));
+    const editorToolNames = editorOnly.specs.map((spec) => spec.name);
+    expect(editorToolNames).to.include('objects.list');
+    expect(editorToolNames).to.not.include('input.action');
+
+    const gameOnly = buildSurfaceRegistry(schemas, handlers, new Set(['game']));
+    const gameToolNames = gameOnly.specs.map((spec) => spec.name);
+    expect(gameToolNames).to.include('state.get');
+    expect(gameToolNames).to.not.include('input.keys');
+
+    const interactOnly = buildSurfaceRegistry(schemas, handlers, new Set(['interact']));
+    const interactToolNames = interactOnly.specs.map((spec) => spec.name);
+    expect(interactToolNames).to.include('input.action');
+    expect(interactToolNames).to.not.include('objects.place');
+
+    const solverOnly = buildSurfaceRegistry(schemas, handlers, new Set(['solver']));
+    const solverToolNames = solverOnly.specs.map((spec) => spec.name);
+    expect(solverToolNames).to.include('solver.replay');
+    expect(solverToolNames).to.not.include('state.get');
+  });
+
+  it('defaults to all known surfaces when enabledSurfaces is omitted', function () {
+    const registry = buildSurfaceRegistry(makeSchemas(), makeHandlers());
+    const names = registry.specs.map((spec) => spec.name);
+    expect(names).to.include('state.get');
+    expect(names).to.include('objects.list');
+    expect(names).to.include('input.action');
+    expect(names).to.include('solver.replay');
+  });
+});
diff --git a/test/mcp-watch-polling.test.js b/test/mcp-watch-polling.test.js
new file mode 100644
index 00000000..f3e77295
--- /dev/null
+++ b/test/mcp-watch-polling.test.js
@@ -0,0 +1,436 @@
+import { expect } from 'chai';
+import {
+  WatchPollingController,
+  parseJsonPointer,
+  readPointerValue,
+  createPointerWatchState,
+  updatePointerWatchState
+} from '../mcp/watchPolling.js';
+
+const createFakeClock = () => {
+  let now = 0;
+  let nextId = 1;
+  const timers = new Map();
+
+  const flush = async () => {
+    while (true) {
+      const due = Array.from(timers.entries())
+        .filter(([, timer]) => timer.at <= now)
+        .sort((a, b) => a[1].at - b[1].at);
+      if (!due.length) break;
+      for (const [id, timer] of due) {
+        timers.delete(id);
+        timer.fn();
+        await Promise.resolve();
+        await Promise.resolve();
+      }
+    }
+  };
+
+  return {
+    nowFn: () => now,
+    setTimerFn(fn, delayMs) {
+      const id = nextId++;
+      timers.set(id, { fn, at: now + delayMs });
+      return id;
+    },
+    clearTimerFn(id) {
+      timers.delete(id);
+    },
+    async flush() {
+      await flush();
+    },
+    async advance(ms) {
+      now += ms;
+      await flush();
+    },
+    nextDueIn() {
+      if (!timers.size) return null;
+      const nextAt = Math.min(...Array.from(timers.values()).map((timer) => timer.at));
+      return nextAt - now;
+    }
+  };
+};
+
+describe('WatchPollingController', function () {
+  it('falls back to defaults when config contains non-coercible numeric values', function () {
+    const controller = new WatchPollingController({
+      hasWatchesFn: () => false,
+      pollFn: async () => ({ triggeredCount: 0 }),
+      config: {
+        minMs: Symbol('min'),
+        activeMs: Symbol('active'),
+        maxMs: Symbol('max'),
+        backoffFactor: Symbol('backoff'),
+        idleThreshold: Symbol('idle'),
+        onDemandMinMs: Symbol('demand')
+      }
+    });
+
+    expect(controller.config).to.deep.equal({
+      minMs: 0,
+      activeMs: 250,
+      maxMs: 2000,
+      backoffFactor: 1.6,
+      idleThreshold: 3,
+      onDemandMinMs: 100
+    });
+  });
+
+  it('backs off when idle and resets to active cadence after a trigger', async function () {
+    const clock = createFakeClock();
+    const outcomes = [0, 0, 0, 2];
+    let callCount = 0;
+    const controller = new WatchPollingController({
+      hasWatchesFn: () => true,
+      pollFn: async () => ({ triggeredCount: outcomes[callCount++] || 0 }),
+      setTimerFn: clock.setTimerFn,
+      clearTimerFn: clock.clearTimerFn,
+      nowFn: clock.nowFn,
+      config: {
+        minMs: 0,
+        activeMs: 100,
+        maxMs: 400,
+        backoffFactor: 2,
+        idleThreshold: 2,
+        onDemandMinMs: 0
+      }
+    });
+
+    controller.start();
+    await clock.flush();
+    expect(controller.getSnapshot().delayMs).to.equal(100);
+
+    await clock.advance(100);
+    expect(controller.getSnapshot().delayMs).to.equal(200);
+
+    await clock.advance(200);
+    expect(controller.getSnapshot().delayMs).to.equal(400);
+
+    await clock.advance(400);
+    expect(controller.getSnapshot().delayMs).to.equal(100);
+    controller.stop();
+  });
+
+  it('reschedules long idle polls when immediate work is requested', async function () {
+    const clock = createFakeClock();
+    const controller = new WatchPollingController({
+      hasWatchesFn: () => true,
+      pollFn: async () => ({ triggeredCount: 0 }),
+      setTimerFn: clock.setTimerFn,
+      clearTimerFn: clock.clearTimerFn,
+      nowFn: clock.nowFn,
+      config: {
+        minMs: 0,
+        activeMs: 100,
+        maxMs: 400,
+        backoffFactor: 2,
+        idleThreshold: 1,
+        onDemandMinMs: 0
+      }
+    });
+
+    controller.start();
+    await clock.flush();
+    await clock.advance(200);
+    expect(controller.getSnapshot().delayMs).to.equal(400);
+    expect(clock.nextDueIn()).to.equal(400);
+
+    controller.request({ immediate: true });
+    expect(clock.nextDueIn()).to.equal(0);
+    await clock.flush();
+    controller.stop();
+  });
+
+  it('throttles on-demand tickNow calls by onDemandMinMs', async function () {
+    const clock = createFakeClock();
+    let callCount = 0;
+    const controller = new WatchPollingController({
+      hasWatchesFn: () => true,
+      pollFn: async () => ({ triggeredCount: (callCount += 1) }),
+      setTimerFn: clock.setTimerFn,
+      clearTimerFn: clock.clearTimerFn,
+      nowFn: clock.nowFn,
+      config: {
+        minMs: 0,
+        activeMs: 5000,
+        maxMs: 5000,
+        onDemandMinMs: 1000
+      }
+    });
+
+    controller.start();
+    await clock.flush();
+    expect(callCount).to.equal(1);
+
+    await controller.tickNow();
+    expect(callCount).to.equal(1);
+
+    await clock.advance(1000);
+    await controller.tickNow();
+    expect(callCount).to.equal(2);
+    controller.stop();
+  });
+
+  it('clears scheduled timers when stopped', async function () {
+    const clock = createFakeClock();
+    const controller = new WatchPollingController({
+      hasWatchesFn: () => true,
+      pollFn: async () => ({ triggeredCount: 0 }),
+      setTimerFn: clock.setTimerFn,
+      clearTimerFn: clock.clearTimerFn,
+      nowFn: clock.nowFn,
+      config: {
+        minMs: 0,
+        activeMs: 100,
+        maxMs: 400
+      }
+    });
+
+    controller.start();
+    await clock.flush();
+    expect(clock.nextDueIn()).to.equal(100);
+    controller.stop();
+    expect(clock.nextDueIn()).to.equal(null);
+  });
+
+  it('stopAndWait waits for in-flight polls to settle', async function () {
+    const clock = createFakeClock();
+    let resolvePoll;
+    const controller = new WatchPollingController({
+      hasWatchesFn: () => true,
+      pollFn: () => new Promise((resolve) => {
+        resolvePoll = resolve;
+      }),
+      setTimerFn: clock.setTimerFn,
+      clearTimerFn: clock.clearTimerFn,
+      nowFn: clock.nowFn,
+      config: {
+        minMs: 0,
+        activeMs: 10,
+        maxMs: 10
+      }
+    });
+
+    controller.start();
+    await clock.flush();
+    expect(controller.getSnapshot().polling).to.equal(true);
+
+    const waiting = controller.stopAndWait(1000);
+    resolvePoll({ triggeredCount: 0 });
+    await waiting;
+    expect(controller.getSnapshot().polling).to.equal(false);
+    expect(controller.getSnapshot().running).to.equal(false);
+  });
+
+  it('stopAndWait timeout uses configured timer hooks', async function () {
+    const clock = createFakeClock();
+    let resolvePoll;
+    const controller = new WatchPollingController({
+      hasWatchesFn: () => true,
+      pollFn: () => new Promise((resolve) => {
+        resolvePoll = resolve;
+      }),
+      setTimerFn: clock.setTimerFn,
+      clearTimerFn: clock.clearTimerFn,
+      nowFn: clock.nowFn,
+      config: {
+        minMs: 0,
+        activeMs: 10,
+        maxMs: 10
+      }
+    });
+
+    controller.start();
+    await clock.flush();
+    expect(controller.getSnapshot().polling).to.equal(true);
+
+    let settled = false;
+    const waiting = controller.stopAndWait(50).then(() => {
+      settled = true;
+    });
+
+    await Promise.resolve();
+    expect(settled).to.equal(false);
+    await clock.advance(49);
+    expect(settled).to.equal(false);
+    await clock.advance(1);
+    await waiting;
+    expect(settled).to.equal(true);
+
+    resolvePoll({ triggeredCount: 0 });
+    await Promise.resolve();
+  });
+
+  it('backs off when pollFn throws and recovers after a triggered poll', async function () {
+    const clock = createFakeClock();
+    let attempts = 0;
+    const controller = new WatchPollingController({
+      hasWatchesFn: () => true,
+      pollFn: async () => {
+        attempts += 1;
+        if (attempts === 1) {
+          throw new Error('boom');
+        }
+        return { triggeredCount: 1 };
+      },
+      setTimerFn: clock.setTimerFn,
+      clearTimerFn: clock.clearTimerFn,
+      nowFn: clock.nowFn,
+      config: {
+        minMs: 0,
+        activeMs: 100,
+        maxMs: 400,
+        backoffFactor: 2,
+        idleThreshold: 1,
+        onDemandMinMs: 0
+      }
+    });
+
+    controller.start();
+    await clock.flush();
+    expect(controller.getSnapshot().delayMs).to.equal(200);
+    expect(controller.getSnapshot().idlePolls).to.equal(1);
+
+    await clock.advance(200);
+    expect(controller.getSnapshot().delayMs).to.equal(100);
+    expect(controller.getSnapshot().idlePolls).to.equal(0);
+    controller.stop();
+  });
+});
+
+describe('watch pointer helpers', function () {
+  it('parses and resolves JSON pointers with escaped segments', function () {
+    const state = {
+      game: {
+        skills: {
+          '~foo/bar': 7
+        }
+      }
+    };
+    const path = parseJsonPointer('/game/skills/~0foo~1bar');
+    const slashPath = parseJsonPointer('/');
+    expect(path).to.deep.equal(['game', 'skills', '~foo/bar']);
+    expect(slashPath).to.deep.equal(['']);
+    expect(readPointerValue(state, path)).to.equal(7);
+    expect(readPointerValue(state, '/game/skills/~0foo~1bar')).to.equal(7);
+    expect(readPointerValue({ '': 42 }, '/')).to.equal(42);
+    expect(readPointerValue(state, '')).to.equal(state);
+  });
+
+  it('treats invalid JSON pointers as undefined lookups', function () {
+    const invalidPath = parseJsonPointer('game/timer/tickIndex');
+    expect(invalidPath).to.equal(null);
+    expect(readPointerValue({ game: { timer: { tickIndex: 7 } } }, invalidPath)).to.equal(undefined);
+    expect(parseJsonPointer('/game/~2bad')).to.equal(null);
+    expect(readPointerValue({ game: { '~2bad': 5 } }, '/game/~2bad')).to.equal(undefined);
+
+    const tracker = createPointerWatchState('game/timer/tickIndex', {
+      game: { timer: { tickIndex: 7 } }
+    });
+    expect(tracker.path).to.equal(null);
+    expect(updatePointerWatchState(tracker, {
+      game: { timer: { tickIndex: 8 } }
+    })).to.equal(false);
+  });
+
+  it('tracks primitive pointer changes without stringify comparisons', function () {
+    const tracker = createPointerWatchState('/game/timer/tickIndex', {
+      game: { timer: { tickIndex: 10 } }
+    });
+    expect(updatePointerWatchState(tracker, { game: { timer: { tickIndex: 10 } } })).to.equal(false);
+    expect(updatePointerWatchState(tracker, { game: { timer: { tickIndex: 11 } } })).to.equal(true);
+    expect(updatePointerWatchState(tracker, { game: { timer: { tickIndex: 11 } } })).to.equal(false);
+  });
+
+  it('detects structural object changes while ignoring referential churn', function () {
+    const tracker = createPointerWatchState('/game/skills', {
+      game: {
+        skills: {
+          selected: 1,
+          counts: [5, 4, 3]
+        }
+      }
+    });
+    expect(updatePointerWatchState(tracker, {
+      game: {
+        skills: {
+          selected: 1,
+          counts: [5, 4, 3]
+        }
+      }
+    })).to.equal(false);
+    expect(updatePointerWatchState(tracker, {
+      game: {
+        skills: {
+          selected: 2,
+          counts: [5, 4, 3]
+        }
+      }
+    })).to.equal(true);
+  });
+
+  it('treats object key insertion order as stable for pointer fingerprints', function () {
+    const tracker = createPointerWatchState('/payload', {
+      payload: { a: 1, b: 2 }
+    });
+    expect(updatePointerWatchState(tracker, {
+      payload: { b: 2, a: 1 }
+    })).to.equal(false);
+  });
+
+  it('detects ArrayBuffer payload changes by content', function () {
+    const initial = new Uint8Array([1, 2, 3]).buffer;
+    const tracker = createPointerWatchState('/payload', { payload: initial });
+    const same = new Uint8Array([1, 2, 3]).buffer;
+    const changed = new Uint8Array([1, 2, 4]).buffer;
+    expect(updatePointerWatchState(tracker, { payload: same })).to.equal(false);
+    expect(updatePointerWatchState(tracker, { payload: changed })).to.equal(true);
+  });
+
+  it('detects typed-array view-type changes even when values and sizes match', function () {
+    const tracker = createPointerWatchState('/payload', {
+      payload: new Uint8Array([1, 2])
+    });
+    expect(updatePointerWatchState(tracker, {
+      payload: new Int8Array([1, 2])
+    })).to.equal(true);
+  });
+
+  it('detects bigint typed-array value changes without losing precision', function () {
+    const base = 2n ** 60n;
+    const tracker = createPointerWatchState('/payload', {
+      payload: new BigInt64Array([base])
+    });
+    expect(updatePointerWatchState(tracker, {
+      payload: new BigInt64Array([base])
+    })).to.equal(false);
+    expect(updatePointerWatchState(tracker, {
+      payload: new BigInt64Array([base + 1n])
+    })).to.equal(true);
+  });
+
+  it('tracks Set payload changes while ignoring insertion order', function () {
+    const tracker = createPointerWatchState('/payload', {
+      payload: new Set([1, 2, 3])
+    });
+    expect(updatePointerWatchState(tracker, {
+      payload: new Set([3, 2, 1])
+    })).to.equal(false);
+    expect(updatePointerWatchState(tracker, {
+      payload: new Set([1, 2, 4])
+    })).to.equal(true);
+  });
+
+  it('tracks Map payload changes while ignoring insertion order', function () {
+    const tracker = createPointerWatchState('/payload', {
+      payload: new Map([['a', 1], ['b', 2]])
+    });
+    expect(updatePointerWatchState(tracker, {
+      payload: new Map([['b', 2], ['a', 1]])
+    })).to.equal(false);
+    expect(updatePointerWatchState(tracker, {
+      payload: new Map([['a', 1], ['b', 3]])
+    })).to.equal(true);
+  });
+});
diff --git a/test/midi/midi-event-router.01-midieventrouter.test.js b/test/midi/midi-event-router.01-midieventrouter.test.js
new file mode 100644
index 00000000..45a676da
--- /dev/null
+++ b/test/midi/midi-event-router.01-midieventrouter.test.js
@@ -0,0 +1,450 @@
+import { expect } from 'chai';
+import { withGlobalLemmings } from '../helpers/lemmings.js';
+import { MidiEventRouter } from '../../js/midi/MidiEventRouter.js';
+import { MidiMapping } from '../../js/midi/MidiMapping.js';
+import { EventHandler } from '../../js/util/EventHandler.js';
+import { toMidiFlagTriggerType } from '../../js/midi/MidiFlagTriggers.js';
+
+const defaultSpec = () => ({ note: 60, velocity: 64, durationTicks: 1 });
+
+const sumPlanEntries = (plan, now = 0, windowMs = 1000) => {
+  const entries = Array.isArray(plan?.entries)
+    ? plan.entries
+    : [plan?.on, plan?.off].filter(Boolean);
+  let count = 0;
+  let bytes = 0;
+  for (const entry of entries) {
+    if (!Number.isFinite(entry?.timeMs)) continue;
+    if (entry.timeMs < now - windowMs || entry.timeMs >= now + windowMs) continue;
+    const entryCount = Math.max(0, Math.trunc(entry.count || 0));
+    const entryBytes = Math.max(0, Math.trunc(entry.bytes || entryCount * 3));
+    count += entryCount;
+    bytes += entryBytes;
+  }
+  return { count, bytes };
+};
+
+const planBudgetFromSnapshot = (snapshot, plan, now = 0) => {
+  const proposed = sumPlanEntries(plan, now);
+  return {
+    snapshot,
+    proposed,
+    combined: {
+      count: (snapshot?.past?.count || 0) + (snapshot?.next?.count || 0) + proposed.count,
+      bytes: (snapshot?.past?.bytes || 0) + (snapshot?.next?.bytes || 0) + proposed.bytes
+    }
+  };
+};
+
+const canScheduleFromSnapshot = (snapshot, plan, now = 0, options = {}) => {
+  const maxMessagesPerSecond = Math.max(1, options.maxMessagesPerSecond ?? snapshot?.maxMessagesPerSecond ?? 1000);
+  const maxBytesPerSecond = Math.max(1, options.maxBytesPerSecond ?? snapshot?.maxBytesPerSecond ?? 3906);
+  const budget = planBudgetFromSnapshot(snapshot, plan, now);
+  const overMessages = budget.combined.count > maxMessagesPerSecond;
+  const overBytes = budget.combined.bytes > maxBytesPerSecond;
+  return {
+    ok: !overMessages && !overBytes,
+    reason: overBytes ? 'byte-limit' : (overMessages ? 'count-limit' : null),
+    maxMessagesPerSecond,
+    maxBytesPerSecond,
+    ...budget
+  };
+};
+
+const makeSchedulerStub = (sent) => {
+  const planned = [];
+  const sumWindow = (entries, start, end) => {
+    let count = 0;
+    let bytes = 0;
+    const bySfx = new Map();
+    for (const entry of entries) {
+      if (entry.timeMs < start || entry.timeMs >= end) continue;
+      count += entry.count;
+      bytes += entry.bytes;
+      const curr = bySfx.get(entry.sfxId) || { count: 0, bytes: 0, priority: entry.priority ?? 1 };
+      curr.count += entry.count;
+      curr.bytes += entry.bytes;
+      bySfx.set(entry.sfxId, curr);
+    }
+    return { count, bytes, bySfx };
+  };
+  return {
+    output: {},
+    tickMs: 60,
+    config: {},
+    setTickMs(ms) { this.tickMs = ms; },
+    estimateMessages(spec) {
+      if (!spec || !Number.isFinite(spec.note)) return { messages: 0, bytes: 0 };
+      const mpeEnabled = !!this.config?.mpe?.enabled;
+      let messages = 1;
+      if (mpeEnabled) {
+        messages += 1;
+      } else if (spec.pitchBend != null && Number.isFinite(spec.pitchBend) && spec.pitchBend !== 0) {
+        messages += 1;
+      }
+      if (spec.timbre != null && Number.isFinite(spec.timbre)) messages += 1;
+      if (spec.pan != null && Number.isFinite(spec.pan)) messages += 1;
+      if (spec.durationTicks && spec.durationTicks > 0) {
+        messages += 1;
+        if (mpeEnabled) messages += 1;
+      }
+      return { messages, bytes: 3 * messages };
+    },
+    getRateSnapshot(now = 0) {
+      return {
+        now,
+        past: sumWindow(planned, now - 1000, now),
+        next: sumWindow(planned, now, now + 1000),
+        maxMessagesPerSecond: 1000,
+        maxBytesPerSecond: 3906
+      };
+    },
+    getPlanBudget(plan, now = 0) {
+      return planBudgetFromSnapshot(this.getRateSnapshot(now), plan, now);
+    },
+    canSchedule(plan, now = 0, options = {}) {
+      return canScheduleFromSnapshot(this.getRateSnapshot(now), plan, now, options);
+    },
+    reserve(plan, meta = {}, now = 0, options = {}) {
+      const check = this.canSchedule(plan, now, options);
+      if (!check.ok) return check;
+      const reservationId = planned.length + 1;
+      const entries = Array.isArray(plan?.entries)
+        ? plan.entries
+        : [
+          plan?.on ? { ...plan.on, phase: 'on' } : null,
+          plan?.off ? { ...plan.off, phase: 'off' } : null
+        ].filter(Boolean);
+      for (const entry of entries) {
+        planned.push({
+          timeMs: entry.timeMs,
+          count: Math.max(0, Math.trunc(entry.count || 0)),
+          bytes: Math.max(0, Math.trunc(entry.bytes || 0)),
+          sfxId: meta.sfxId,
+          priority: meta.priority,
+          reservationId,
+          phase: entry.phase ?? null
+        });
+      }
+      return { ...check, ok: true, reservationId };
+    },
+    getUsageShare(window = 'past', now = 0) {
+      const data = window === 'next'
+        ? sumWindow(planned, now, now + 1000)
+        : sumWindow(planned, now - 1000, now);
+      const total = data.count || 0;
+      const totalBytes = data.bytes || 0;
+      const shares = [];
+      for (const [sfxId, entry] of data.bySfx.entries()) {
+        shares.push({
+          sfxId,
+          count: entry.count,
+          bytes: entry.bytes,
+          priority: entry.priority ?? 1,
+          percentCount: total ? entry.count / total : 0,
+          percentBytes: totalBytes ? entry.bytes / totalBytes : 0
+        });
+      }
+      shares.sort((a, b) => b.count - a.count);
+      return shares;
+    },
+    sendNote(spec, meta = {}) {
+      sent.push(spec);
+      if (meta.rateReserved === true) return;
+      const timeMs = spec.timeMs ?? 0;
+      const durationMs = (spec.durationTicks ?? 0) * this.tickMs;
+      planned.push({ timeMs, count: 1, bytes: 3, sfxId: meta.sfxId, priority: meta.priority });
+      if (durationMs > 0) {
+        planned.push({ timeMs: timeMs + durationMs, count: 1, bytes: 3, sfxId: meta.sfxId, priority: meta.priority });
+      }
+    },
+    setConfig(config) { this.config = config || {}; },
+    setOutput() {},
+    dispose() {}
+  };
+};
+
+const makeRateSnapshot = (next = {}, past = {}, maxBytesPerSecond = 1000) => ({
+  next: { count: 0, bytes: 0, bySfx: new Map(), ...next },
+  past: { count: 0, bytes: 0, bySfx: new Map(), ...past },
+  maxBytesPerSecond
+});
+
+const makeRateScheduler = (snapshot, usageShare = []) => ({
+  getRateSnapshot(now = 0) {
+    return typeof snapshot === 'function' ? snapshot(now) : snapshot;
+  },
+  getPlanBudget(plan, now = 0) {
+    return planBudgetFromSnapshot(this.getRateSnapshot(now), plan, now);
+  },
+  canSchedule(plan, now = 0, options = {}) {
+    return canScheduleFromSnapshot(this.getRateSnapshot(now), plan, now, options);
+  },
+  reserve(plan, meta = {}, now = 0, options = {}) {
+    const check = this.canSchedule(plan, now, options);
+    return check.ok ? { ...check, reservationId: 1 } : check;
+  },
+  getUsageShare() { return usageShare; }
+});
+
+const makeRateRouter = (config, snapshot, usageShare = []) => (
+  makeRouter(config, { scheduler: makeRateScheduler(snapshot, usageShare) })
+);
+
+const makePlan = ({ timeMs = 0, on = {}, off = {} } = {}) => ({
+  on: { timeMs, count: 0, bytes: 0, ...on },
+  off: { timeMs, count: 0, bytes: 0, ...off }
+});
+
+const makeRouter = (config = {}, options = {}) => {
+  const sent = options.sent ?? [];
+  const mapping = config instanceof MidiMapping ? config : new MidiMapping(config);
+  const router = new MidiEventRouter(mapping);
+  router.scheduler = options.scheduler ?? makeSchedulerStub(sent);
+  router.scheduler.setConfig?.(mapping.config);
+  if (options.output === false) router.scheduler.output = null;
+  if (options.mapEvent) {
+    router.mapping.mapEvent = options.mapEvent;
+  } else if (options.defaultMapEvent) {
+    router.mapping.mapEvent = () => defaultSpec();
+  }
+  return { router, sent, mapping };
+};
+
+const makeArpRouter = (arp, overrides = {}, notes = [60, 64, 67]) => (
+  makeRouter({ limits: { maxEventsPerSecond: 1000 }, ...overrides }, {
+    mapEvent: () => ({
+      notes,
+      note: notes[0],
+      velocity: 64,
+      durationTicks: 1,
+      arp
+    })
+  })
+);
+
+describe('MidiEventRouter 1', function() {
+  it('computes density and tick duration', function() {
+    const densities = [];
+    const { router, sent } = makeRouter({ density: { windowTicks: 10 } }, {
+      mapEvent: (event, context, density) => {
+        densities.push(density);
+        return defaultSpec();
+      }
+    });
+
+    let now = 0;
+    router._nowMs = () => now;
+    router._onEvent({ sfxId: 1, tick: 1, tps: 50 });
+    router._onEvent({ sfxId: 1, tick: 2, tps: 50 });
+
+    expect(router.scheduler.tickMs).to.equal(20);
+    expect(densities[0]).to.equal(0);
+    expect(densities[1]).to.be.closeTo(0.9, 0.01);
+    expect(sent.length).to.equal(2);
+  });
+
+  it('passes reverse flags to the scheduler', function() {
+    const { router, sent } = makeRouter(new MidiMapping(), { defaultMapEvent: true });
+
+    router._onEvent({ sfxId: 1, tick: 1, reverse: true });
+
+    expect(sent[0].reverse).to.equal(true);
+  });
+
+  it('ignores events when disabled or output is missing', function() {
+    const cases = [
+      {
+        name: 'disabled mapping',
+        config: { enabled: false },
+        output: true,
+        events: [{ sfxId: 1, tick: 1 }]
+      },
+      {
+        name: 'missing output',
+        config: { enabled: true },
+        output: false,
+        events: [{ sfxId: 1, tick: 1 }, {}]
+      }
+    ];
+
+    for (const testCase of cases) {
+      const { router, sent } = makeRouter(testCase.config, {
+        defaultMapEvent: true,
+        output: testCase.output
+      });
+      for (const event of testCase.events) {
+        router._onEvent(event);
+      }
+      expect(sent.length, testCase.name).to.equal(0);
+    }
+  });
+
+  it('requires explicit trigger mapping for midi flag trigger events', function() {
+    const triggerType = toMidiFlagTriggerType(3);
+    const { router, sent } = makeRouter({
+      enabled: true,
+      triggers: {}
+    }, {
+      mapEvent: (event, _context, _density, sfx) => {
+        if (!sfx || Object.keys(sfx).length === 0) return null;
+        return { note: 65, velocity: 80, durationTicks: 2 };
+      }
+    });
+
+    router._onEvent({ sfxId: 0, triggerType, tick: 1, x: 10, y: 10 });
+    expect(sent).to.have.length(0);
+
+    router.mapping.config.triggers[String(triggerType)] = { note: 67, velocity: 100, durationTicks: 2 };
+    router._onEvent({ sfxId: 0, triggerType, tick: 2, x: 12, y: 12 });
+    expect(sent).to.have.length(1);
+    expect(sent[0].note).to.equal(65);
+  });
+
+  it('schedules ahead when event time is behind', function() {
+    const { router, sent } = makeRouter({
+      timing: { scheduleAheadMs: 50 },
+      limits: { maxEventsPerSecond: 1000 }
+    }, { defaultMapEvent: true });
+    router._nowMs = () => 1000;
+    router._resolveScheduleBase = () => 900;
+
+    router._onEvent({ sfxId: 1, tick: 1, timeMs: 0 });
+
+    expect(sent[0].timeMs).to.equal(1050);
+  });
+
+  it('enforces per-tick and per-second limits', function() {
+    const { router, sent } = makeRouter({
+      mpe: { enabled: false },
+      limits: { maxEventsPerTick: 1, maxEventsPerSecond: 2 }
+    }, { defaultMapEvent: true });
+
+    let now = 0;
+    router._nowMs = () => now;
+
+    router._onEvent({ sfxId: 1, tick: 1 });
+    router._onEvent({ sfxId: 1, tick: 1 });
+    expect(sent.length).to.equal(1);
+
+    router._onEvent({ sfxId: 1, tick: 2 });
+    expect(sent.length).to.equal(1);
+
+    now = 1100;
+    router._onEvent({ sfxId: 1, tick: 3 });
+    expect(sent.length).to.equal(2);
+  });
+
+  it('rejects events when higher-priority bytes saturate the window', function() {
+    const bySfx = new Map([[2, { count: 0, bytes: 9, priority: 2 }]]);
+    const snapshot = makeRateSnapshot(
+      { count: 11, bytes: 9, bySfx },
+      { count: 0, bytes: 0 },
+      9
+    );
+    const { router } = makeRateRouter({
+      limits: { maxEventsPerSecond: 10, hardMaxEventsPerSecond: 100, maxBytesPerSecond: 9 }
+    }, snapshot);
+    const plan = makePlan();
+    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, {}, plan, 0);
+    expect(ok).to.equal(false);
+    expect(router.getRateReport().reason).to.equal('byte-limit');
+  });
+
+  it('allows events when spacing and budgets are available', function() {
+    const snapshot = makeRateSnapshot(
+      { count: 9, bytes: 100 },
+      { count: 0, bytes: 0 },
+      1000
+    );
+    const { router } = makeRateRouter({
+      limits: { maxEventsPerSecond: 10, hardMaxEventsPerSecond: 100, maxBytesPerSecond: 1000 }
+    }, snapshot);
+    const plan = makePlan({ on: { count: 1, bytes: 3 } });
+    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, { timeMs: 0 }, plan, 0);
+    expect(ok).to.equal(true);
+  });
+
+  it('rejects events when past plus next plus proposed traffic exceeds the reservation budget', function() {
+    const snapshot = makeRateSnapshot(
+      { count: 1, bytes: 3, bySfx: new Map([[2, { count: 1, bytes: 3, priority: 1 }]]) },
+      { count: 1, bytes: 3, bySfx: new Map([[1, { count: 1, bytes: 3, priority: 1 }]]) }
+    );
+    const { router } = makeRateRouter({
+      limits: { maxEventsPerSecond: 3, hardMaxEventsPerSecond: 3 }
+    }, snapshot);
+    const plan = makePlan({ timeMs: 0, on: { count: 2, bytes: 6 } });
+    const ok = router._shouldSend({ sfxId: 3, priority: 1 }, { timeMs: 0 }, plan, 0);
+    expect(ok).to.equal(false);
+    expect(router.getRateReport().reason).to.equal('count-limit');
+  });
+
+  it('exposes the scheduler rate snapshot', function() {
+    const snapshot = { next: { count: 0, bytes: 0, bySfx: new Map() } };
+    const { router } = makeRouter({}, { scheduler: makeRateScheduler(snapshot) });
+    expect(router.getRateSnapshot()).to.equal(snapshot);
+  });
+
+  it('steps through arpeggio notes across events', function() {
+    const { router, sent } = makeArpRouter({ enabled: true, mode: 'up', length: 3 });
+
+    router._onEvent({ sfxId: 1, tick: 1, tps: 50 });
+    router._onEvent({ sfxId: 1, tick: 2, tps: 50 });
+
+    expect(sent[0].note).to.equal(60);
+    expect(sent[1].note).to.equal(64);
+  });
+
+  it('handles single-note arps without advancing', function() {
+    const { router, sent } = makeArpRouter(
+      { enabled: true, mode: 'up', length: 1 },
+      {},
+      [60]
+    );
+
+    router._onEvent({ sfxId: 1, tick: 1, tps: 50 });
+    router._onEvent({ sfxId: 1, tick: 2, tps: 50 });
+
+    expect(sent.length).to.equal(2);
+    expect(sent[0].note).to.equal(60);
+    expect(sent[1].note).to.equal(60);
+  });
+
+  it('handles downward arps with independent trigger keys', function() {
+    const { router, sent } = makeArpRouter(
+      { enabled: true, mode: 'down', length: 3 },
+      { triggers: { '5': { arp: { independent: true } } } }
+    );
+
+    router._onEvent({ sfxId: 1, tick: 1, tps: 50, triggerType: 5, objectId: 100 });
+    router._onEvent({ sfxId: 1, tick: 2, tps: 50, triggerType: 5, objectId: 100 });
+    router._onEvent({ sfxId: 1, tick: 3, tps: 50, triggerType: 5, objectId: 200 });
+
+    expect(sent[0].note).to.equal(67);
+    expect(sent[1].note).to.equal(64);
+    expect(sent[2].note).to.equal(67);
+  });
+
+  it('bounds independent arp cache growth', function() {
+    const { router } = makeRouter(
+      { limits: { maxEventsPerSecond: 1000 }, triggers: { '5': { arp: { independent: true } } } },
+      {
+        mapEvent: () => ({
+          notes: [60, 64],
+          note: 60,
+          velocity: 64,
+          durationTicks: 1,
+          arp: { enabled: true, mode: 'up', length: 2 }
+        })
+      }
+    );
+
+    for (let i = 0; i < 300; i += 1) {
+      router._onEvent({ sfxId: 1, tick: i + 1, tps: 50, triggerType: 5, objectId: i });
+    }
+
+    expect(router._arpStateBySfx.size).to.be.at.most(256);
+    expect(router._arpStateBySfx.has('trigger:5:1:object:0')).to.equal(false);
+    expect(router._arpStateBySfx.has('trigger:5:1:object:299')).to.equal(true);
+  });
+});
diff --git a/test/midi/midi-event-router.02-midieventrouter.test.js b/test/midi/midi-event-router.02-midieventrouter.test.js
new file mode 100644
index 00000000..20e69cdd
--- /dev/null
+++ b/test/midi/midi-event-router.02-midieventrouter.test.js
@@ -0,0 +1,447 @@
+import { expect } from 'chai';
+import { withGlobalLemmings } from '../helpers/lemmings.js';
+import { MidiEventRouter } from '../../js/midi/MidiEventRouter.js';
+import { MidiMapping } from '../../js/midi/MidiMapping.js';
+import { EventHandler } from '../../js/util/EventHandler.js';
+import { toMidiFlagTriggerType } from '../../js/midi/MidiFlagTriggers.js';
+
+const defaultSpec = () => ({ note: 60, velocity: 64, durationTicks: 1 });
+
+const sumPlanEntries = (plan, now = 0, windowMs = 1000) => {
+  const entries = Array.isArray(plan?.entries)
+    ? plan.entries
+    : [plan?.on, plan?.off].filter(Boolean);
+  let count = 0;
+  let bytes = 0;
+  for (const entry of entries) {
+    if (!Number.isFinite(entry?.timeMs)) continue;
+    if (entry.timeMs < now - windowMs || entry.timeMs >= now + windowMs) continue;
+    const entryCount = Math.max(0, Math.trunc(entry.count || 0));
+    const entryBytes = Math.max(0, Math.trunc(entry.bytes || entryCount * 3));
+    count += entryCount;
+    bytes += entryBytes;
+  }
+  return { count, bytes };
+};
+
+const planBudgetFromSnapshot = (snapshot, plan, now = 0) => {
+  const proposed = sumPlanEntries(plan, now);
+  return {
+    snapshot,
+    proposed,
+    combined: {
+      count: (snapshot?.past?.count || 0) + (snapshot?.next?.count || 0) + proposed.count,
+      bytes: (snapshot?.past?.bytes || 0) + (snapshot?.next?.bytes || 0) + proposed.bytes
+    }
+  };
+};
+
+const canScheduleFromSnapshot = (snapshot, plan, now = 0, options = {}) => {
+  const maxMessagesPerSecond = Math.max(1, options.maxMessagesPerSecond ?? snapshot?.maxMessagesPerSecond ?? 1000);
+  const maxBytesPerSecond = Math.max(1, options.maxBytesPerSecond ?? snapshot?.maxBytesPerSecond ?? 3906);
+  const budget = planBudgetFromSnapshot(snapshot, plan, now);
+  const overMessages = budget.combined.count > maxMessagesPerSecond;
+  const overBytes = budget.combined.bytes > maxBytesPerSecond;
+  return {
+    ok: !overMessages && !overBytes,
+    reason: overBytes ? 'byte-limit' : (overMessages ? 'count-limit' : null),
+    maxMessagesPerSecond,
+    maxBytesPerSecond,
+    ...budget
+  };
+};
+
+const makeSchedulerStub = (sent) => {
+  const planned = [];
+  const sumWindow = (entries, start, end) => {
+    let count = 0;
+    let bytes = 0;
+    const bySfx = new Map();
+    for (const entry of entries) {
+      if (entry.timeMs < start || entry.timeMs >= end) continue;
+      count += entry.count;
+      bytes += entry.bytes;
+      const curr = bySfx.get(entry.sfxId) || { count: 0, bytes: 0, priority: entry.priority ?? 1 };
+      curr.count += entry.count;
+      curr.bytes += entry.bytes;
+      bySfx.set(entry.sfxId, curr);
+    }
+    return { count, bytes, bySfx };
+  };
+  return {
+    output: {},
+    tickMs: 60,
+    config: {},
+    setTickMs(ms) { this.tickMs = ms; },
+    estimateMessages(spec) {
+      if (!spec || !Number.isFinite(spec.note)) return { messages: 0, bytes: 0 };
+      const mpeEnabled = !!this.config?.mpe?.enabled;
+      let messages = 1;
+      if (mpeEnabled) {
+        messages += 1;
+      } else if (spec.pitchBend != null && Number.isFinite(spec.pitchBend) && spec.pitchBend !== 0) {
+        messages += 1;
+      }
+      if (spec.timbre != null && Number.isFinite(spec.timbre)) messages += 1;
+      if (spec.pan != null && Number.isFinite(spec.pan)) messages += 1;
+      if (spec.durationTicks && spec.durationTicks > 0) {
+        messages += 1;
+        if (mpeEnabled) messages += 1;
+      }
+      return { messages, bytes: 3 * messages };
+    },
+    getRateSnapshot(now = 0) {
+      return {
+        now,
+        past: sumWindow(planned, now - 1000, now),
+        next: sumWindow(planned, now, now + 1000),
+        maxMessagesPerSecond: 1000,
+        maxBytesPerSecond: 3906
+      };
+    },
+    getPlanBudget(plan, now = 0) {
+      return planBudgetFromSnapshot(this.getRateSnapshot(now), plan, now);
+    },
+    canSchedule(plan, now = 0, options = {}) {
+      return canScheduleFromSnapshot(this.getRateSnapshot(now), plan, now, options);
+    },
+    reserve(plan, meta = {}, now = 0, options = {}) {
+      const check = this.canSchedule(plan, now, options);
+      if (!check.ok) return check;
+      const reservationId = planned.length + 1;
+      const entries = Array.isArray(plan?.entries)
+        ? plan.entries
+        : [
+          plan?.on ? { ...plan.on, phase: 'on' } : null,
+          plan?.off ? { ...plan.off, phase: 'off' } : null
+        ].filter(Boolean);
+      for (const entry of entries) {
+        planned.push({
+          timeMs: entry.timeMs,
+          count: Math.max(0, Math.trunc(entry.count || 0)),
+          bytes: Math.max(0, Math.trunc(entry.bytes || 0)),
+          sfxId: meta.sfxId,
+          priority: meta.priority,
+          reservationId,
+          phase: entry.phase ?? null
+        });
+      }
+      return { ...check, ok: true, reservationId };
+    },
+    getUsageShare(window = 'past', now = 0) {
+      const data = window === 'next'
+        ? sumWindow(planned, now, now + 1000)
+        : sumWindow(planned, now - 1000, now);
+      const total = data.count || 0;
+      const totalBytes = data.bytes || 0;
+      const shares = [];
+      for (const [sfxId, entry] of data.bySfx.entries()) {
+        shares.push({
+          sfxId,
+          count: entry.count,
+          bytes: entry.bytes,
+          priority: entry.priority ?? 1,
+          percentCount: total ? entry.count / total : 0,
+          percentBytes: totalBytes ? entry.bytes / totalBytes : 0
+        });
+      }
+      shares.sort((a, b) => b.count - a.count);
+      return shares;
+    },
+    sendNote(spec, meta = {}) {
+      sent.push(spec);
+      if (meta.rateReserved === true) return;
+      const timeMs = spec.timeMs ?? 0;
+      const durationMs = (spec.durationTicks ?? 0) * this.tickMs;
+      planned.push({ timeMs, count: 1, bytes: 3, sfxId: meta.sfxId, priority: meta.priority });
+      if (durationMs > 0) {
+        planned.push({ timeMs: timeMs + durationMs, count: 1, bytes: 3, sfxId: meta.sfxId, priority: meta.priority });
+      }
+    },
+    setConfig(config) { this.config = config || {}; },
+    setOutput() {},
+    dispose() {}
+  };
+};
+
+const makeRateSnapshot = (next = {}, past = {}, maxBytesPerSecond = 1000) => ({
+  next: { count: 0, bytes: 0, bySfx: new Map(), ...next },
+  past: { count: 0, bytes: 0, bySfx: new Map(), ...past },
+  maxBytesPerSecond
+});
+
+const makeRateScheduler = (snapshot, usageShare = []) => ({
+  getRateSnapshot(now = 0) {
+    return typeof snapshot === 'function' ? snapshot(now) : snapshot;
+  },
+  getPlanBudget(plan, now = 0) {
+    return planBudgetFromSnapshot(this.getRateSnapshot(now), plan, now);
+  },
+  canSchedule(plan, now = 0, options = {}) {
+    return canScheduleFromSnapshot(this.getRateSnapshot(now), plan, now, options);
+  },
+  reserve(plan, meta = {}, now = 0, options = {}) {
+    const check = this.canSchedule(plan, now, options);
+    return check.ok ? { ...check, reservationId: 1 } : check;
+  },
+  getUsageShare() { return usageShare; }
+});
+
+const makeRateRouter = (config, snapshot, usageShare = []) => (
+  makeRouter(config, { scheduler: makeRateScheduler(snapshot, usageShare) })
+);
+
+const makePlan = ({ timeMs = 0, on = {}, off = {} } = {}) => ({
+  on: { timeMs, count: 0, bytes: 0, ...on },
+  off: { timeMs, count: 0, bytes: 0, ...off }
+});
+
+const makeRouter = (config = {}, options = {}) => {
+  const sent = options.sent ?? [];
+  const mapping = config instanceof MidiMapping ? config : new MidiMapping(config);
+  const router = new MidiEventRouter(mapping);
+  router.scheduler = options.scheduler ?? makeSchedulerStub(sent);
+  router.scheduler.setConfig?.(mapping.config);
+  if (options.output === false) router.scheduler.output = null;
+  if (options.mapEvent) {
+    router.mapping.mapEvent = options.mapEvent;
+  } else if (options.defaultMapEvent) {
+    router.mapping.mapEvent = () => defaultSpec();
+  }
+  return { router, sent, mapping };
+};
+
+const makeArpRouter = (arp, overrides = {}, notes = [60, 64, 67]) => (
+  makeRouter({ limits: { maxEventsPerSecond: 1000 }, ...overrides }, {
+    mapEvent: () => ({
+      notes,
+      note: notes[0],
+      velocity: 64,
+      durationTicks: 1,
+      arp
+    })
+  })
+);
+
+describe('MidiEventRouter 2', function() {
+  it('bounds repeat-history key growth for independent triggers', function() {
+    const { router } = makeRouter(
+      {
+        repeat: { maxRepeats: 2, windowBeats: 8 },
+        limits: { maxEventsPerSecond: 1000 },
+        triggers: { '5': { repeat: { maxRepeats: 2, windowBeats: 8 } } }
+      },
+      { defaultMapEvent: true }
+    );
+    router._nowMs = () => 1000;
+
+    for (let i = 0; i < 700; i += 1) {
+      router._onEvent({ sfxId: 1, tick: i + 1, tps: 60, triggerType: 5, timeMs: i * 10 + 1 + i });
+      router._onEvent({ sfxId: 1, tick: i + 1, tps: 60, triggerType: 5 + i, timeMs: i * 10 + 2 + i });
+    }
+
+    expect(router._repeatHistoryByKey.size).to.be.at.most(512);
+  });
+
+  it('caps repeat-history entry count per key to maxRepeats + 1', function() {
+    const { router } = makeRouter();
+    const cfg = { maxRepeats: 2, windowBeats: 10 };
+    for (let i = 0; i < 20; i += 1) {
+      router._getRepeatFactor('sfx:42', i * 10, cfg, 120);
+    }
+    expect(router._repeatHistoryByKey.get('sfx:42')).to.have.length(3);
+  });
+
+  it('reverses direction for updown arps at bounds', function() {
+    const { router, sent } = makeArpRouter({ enabled: true, mode: 'updown', length: 3 });
+
+    router._onEvent({ sfxId: 1, tick: 1, tps: 50 });
+    router._onEvent({ sfxId: 1, tick: 2, tps: 50 });
+    router._onEvent({ sfxId: 1, tick: 3, tps: 50 });
+    router._onEvent({ sfxId: 1, tick: 4, tps: 50 });
+
+    expect(sent.map(entry => entry.note)).to.eql([60, 64, 67, 64]);
+  });
+
+  it('applies custom arp step patterns when preset is custom', function() {
+    const { router, sent } = makeArpRouter({
+      enabled: true,
+      mode: 'up',
+      length: 3,
+      pattern: { preset: 'custom', steps: ['up', 'hold', 'down'] }
+    });
+
+    router._onEvent({ sfxId: 1, tick: 1, tps: 50 });
+    router._onEvent({ sfxId: 1, tick: 2, tps: 50 });
+    router._onEvent({ sfxId: 1, tick: 3, tps: 50 });
+    router._onEvent({ sfxId: 1, tick: 4, tps: 50 });
+    router._onEvent({ sfxId: 1, tick: 5, tps: 50 });
+
+    expect(sent.map(entry => entry.note)).to.eql([60, 64, 64, 60, 64]);
+  });
+
+  it('resets custom arp step state when the pattern changes', function() {
+    const { router, sent } = makeArpRouter({
+      enabled: true,
+      mode: 'up',
+      length: 3,
+      pattern: { preset: 'custom', steps: ['up'] }
+    });
+
+    router._onEvent({ sfxId: 1, tick: 1, tps: 50 });
+    router._onEvent({ sfxId: 1, tick: 2, tps: 50 });
+    router.mapping.mapEvent = () => ({
+      notes: [60, 64, 67],
+      note: 60,
+      velocity: 64,
+      durationTicks: 1,
+      arp: {
+        enabled: true,
+        mode: 'up',
+        length: 3,
+        pattern: { preset: 'custom', steps: ['down'] }
+      }
+    });
+    router._onEvent({ sfxId: 1, tick: 3, tps: 50 });
+
+    expect(sent.map(entry => entry.note)).to.eql([60, 64, 60]);
+  });
+
+  it('resets arpeggio state when the mode changes', function() {
+    const { router, sent } = makeArpRouter({ enabled: true, mode: 'up', length: 3 });
+
+    router._onEvent({ sfxId: 1, tick: 1, tps: 50 });
+    router.mapping.mapEvent = () => ({
+      notes: [60, 64, 67],
+      note: 60,
+      velocity: 64,
+      durationTicks: 1,
+      arp: { enabled: true, mode: 'down', length: 3 }
+    });
+    router._onEvent({ sfxId: 1, tick: 2, tps: 50 });
+
+    expect(sent.length).to.equal(2);
+  });
+
+  it('resets scheduling when speed changes', function() {
+    const sent = [];
+    const scheduler = makeSchedulerStub(sent);
+    let allOffCalls = 0;
+    scheduler.allNotesOff = () => { allOffCalls += 1; };
+    const { router } = makeRouter({ limits: { maxEventsPerSecond: 1000 } }, {
+      scheduler,
+      mapEvent: () => defaultSpec()
+    });
+    router._nowMs = () => 1000;
+
+    router._onEvent({ sfxId: 1, tick: 1, timeMs: 0, frameMs: 60, speedFactor: 1 });
+    router._onEvent({ sfxId: 1, tick: 2, timeMs: 60, frameMs: 120, speedFactor: 0.5 });
+
+    expect(allOffCalls).to.equal(1);
+  });
+
+  it('scales repeat intensity within a beat window', function() {
+    const { router, sent } = makeRouter({
+      repeat: {
+        maxRepeats: 2,
+        windowBeats: 4,
+        amount: null,
+        velocityBoost: 0.5,
+        durationBoost: 0.5
+      },
+      timing: { bpmBase: 120 },
+      limits: { maxEventsPerSecond: 1000 }
+    }, { mapEvent: () => ({ note: 60, velocity: 40, durationTicks: 2 }) });
+
+    router._nowMs = () => 1000;
+    router._onEvent({ sfxId: 1, tick: 1 });
+    router._onEvent({ sfxId: 1, tick: 2 });
+
+    expect(sent.length).to.equal(2);
+    expect(sent[1].velocity).to.be.greaterThan(sent[0].velocity);
+    expect(sent[1].durationTicks).to.be.greaterThan(sent[0].durationTicks);
+  });
+
+  it('applies repeat targets when amount is configured', function() {
+    const { router, sent } = makeRouter({
+      repeat: {
+        maxRepeats: 4,
+        windowBeats: 1,
+        amount: 1,
+        target: 'note'
+      },
+      timing: { bpmBase: 120 },
+      limits: { maxEventsPerSecond: 1000 }
+    }, { mapEvent: () => ({ note: 60, velocity: 40, durationTicks: 1 }) });
+
+    let now = 0;
+    router._nowMs = () => now;
+    router._onEvent({ sfxId: 1, tick: 1 });
+    now = 100;
+    router._onEvent({ sfxId: 1, tick: 2 });
+
+    expect(sent.length).to.equal(2);
+    expect(sent[1].note).to.be.greaterThan(sent[0].note);
+  });
+
+  it('drops events when byte limits are exceeded', function() {
+    const sent = [];
+    const baseSnapshot = makeRateSnapshot({ count: 1, bytes: 3 }, { count: 0, bytes: 0 }, 3);
+    const usageShare = [{ sfxId: 99, count: 1, bytes: 3, priority: 1, percentCount: 1, percentBytes: 1 }];
+    const scheduler = {
+      ...makeRateScheduler((now = 0) => ({ ...baseSnapshot, now }), usageShare),
+      output: {},
+      tickMs: 60,
+      setTickMs() {},
+      estimateMessages() { return { messages: 1, bytes: 3 }; },
+      sendNote() { sent.push(true); }
+    };
+    const { router } = makeRouter(
+      { limits: { maxEventsPerSecond: 1000, maxBytesPerSecond: 3 } },
+      {
+        scheduler,
+        mapEvent: () => ({ note: 60, velocity: 64, durationTicks: 1 })
+      }
+    );
+
+    router._onEvent({ sfxId: 1, tick: 1, tps: 50 });
+
+    expect(sent.length).to.equal(0);
+    expect(router.getRateReport().reason).to.equal('byte-limit');
+  });
+
+  it('attaches and detaches from sound buses', function() {
+    const { router } = makeRouter();
+    const busA = { onEvent: new EventHandler() };
+    const busB = { onEvent: new EventHandler() };
+    router.attach(busA);
+    expect(busA.onEvent.handlers.size).to.equal(1);
+    router.attach(busB);
+    expect(busA.onEvent.handlers.size).to.equal(0);
+    expect(busB.onEvent.handlers.size).to.equal(1);
+    router.detach();
+    expect(busB.onEvent.handlers.size).to.equal(0);
+  });
+
+  it('accepts plain mapping configs and resets context defaults', function() {
+    let configured = null;
+    const { router } = makeRouter({}, {
+      scheduler: { setConfig(cfg) { configured = cfg; } }
+    });
+    router.setMapping({ timing: { bpmBase: 90 } });
+    expect(router.mapping).to.be.instanceOf(MidiMapping);
+    expect(configured).to.equal(router.mapping.config);
+
+    const bus = { onEvent: new EventHandler() };
+    router.attach(bus, null);
+    expect(router.context).to.eql({});
+    router.detach();
+  });
+
+  it('keeps MidiMapping instances when setting mapping', function() {
+    const mapping = new MidiMapping({ timing: { bpmBase: 100 } });
+    const { router } = makeRouter();
+    router.setMapping(mapping);
+    expect(router.mapping).to.equal(mapping);
+  });
+});
diff --git a/test/midi/midi-event-router.03-midieventrouter.test.js b/test/midi/midi-event-router.03-midieventrouter.test.js
new file mode 100644
index 00000000..8101a22c
--- /dev/null
+++ b/test/midi/midi-event-router.03-midieventrouter.test.js
@@ -0,0 +1,444 @@
+import { expect } from 'chai';
+import { withGlobalLemmings } from '../helpers/lemmings.js';
+import { MidiEventRouter } from '../../js/midi/MidiEventRouter.js';
+import { MidiMapping } from '../../js/midi/MidiMapping.js';
+import { EventHandler } from '../../js/util/EventHandler.js';
+import { toMidiFlagTriggerType } from '../../js/midi/MidiFlagTriggers.js';
+
+const defaultSpec = () => ({ note: 60, velocity: 64, durationTicks: 1 });
+
+const sumPlanEntries = (plan, now = 0, windowMs = 1000) => {
+  const entries = Array.isArray(plan?.entries)
+    ? plan.entries
+    : [plan?.on, plan?.off].filter(Boolean);
+  let count = 0;
+  let bytes = 0;
+  for (const entry of entries) {
+    if (!Number.isFinite(entry?.timeMs)) continue;
+    if (entry.timeMs < now - windowMs || entry.timeMs >= now + windowMs) continue;
+    const entryCount = Math.max(0, Math.trunc(entry.count || 0));
+    const entryBytes = Math.max(0, Math.trunc(entry.bytes || entryCount * 3));
+    count += entryCount;
+    bytes += entryBytes;
+  }
+  return { count, bytes };
+};
+
+const planBudgetFromSnapshot = (snapshot, plan, now = 0) => {
+  const proposed = sumPlanEntries(plan, now);
+  return {
+    snapshot,
+    proposed,
+    combined: {
+      count: (snapshot?.past?.count || 0) + (snapshot?.next?.count || 0) + proposed.count,
+      bytes: (snapshot?.past?.bytes || 0) + (snapshot?.next?.bytes || 0) + proposed.bytes
+    }
+  };
+};
+
+const canScheduleFromSnapshot = (snapshot, plan, now = 0, options = {}) => {
+  const maxMessagesPerSecond = Math.max(1, options.maxMessagesPerSecond ?? snapshot?.maxMessagesPerSecond ?? 1000);
+  const maxBytesPerSecond = Math.max(1, options.maxBytesPerSecond ?? snapshot?.maxBytesPerSecond ?? 3906);
+  const budget = planBudgetFromSnapshot(snapshot, plan, now);
+  const overMessages = budget.combined.count > maxMessagesPerSecond;
+  const overBytes = budget.combined.bytes > maxBytesPerSecond;
+  return {
+    ok: !overMessages && !overBytes,
+    reason: overBytes ? 'byte-limit' : (overMessages ? 'count-limit' : null),
+    maxMessagesPerSecond,
+    maxBytesPerSecond,
+    ...budget
+  };
+};
+
+const makeSchedulerStub = (sent) => {
+  const planned = [];
+  const sumWindow = (entries, start, end) => {
+    let count = 0;
+    let bytes = 0;
+    const bySfx = new Map();
+    for (const entry of entries) {
+      if (entry.timeMs < start || entry.timeMs >= end) continue;
+      count += entry.count;
+      bytes += entry.bytes;
+      const curr = bySfx.get(entry.sfxId) || { count: 0, bytes: 0, priority: entry.priority ?? 1 };
+      curr.count += entry.count;
+      curr.bytes += entry.bytes;
+      bySfx.set(entry.sfxId, curr);
+    }
+    return { count, bytes, bySfx };
+  };
+  return {
+    output: {},
+    tickMs: 60,
+    config: {},
+    setTickMs(ms) { this.tickMs = ms; },
+    estimateMessages(spec) {
+      if (!spec || !Number.isFinite(spec.note)) return { messages: 0, bytes: 0 };
+      const mpeEnabled = !!this.config?.mpe?.enabled;
+      let messages = 1;
+      if (mpeEnabled) {
+        messages += 1;
+      } else if (spec.pitchBend != null && Number.isFinite(spec.pitchBend) && spec.pitchBend !== 0) {
+        messages += 1;
+      }
+      if (spec.timbre != null && Number.isFinite(spec.timbre)) messages += 1;
+      if (spec.pan != null && Number.isFinite(spec.pan)) messages += 1;
+      if (spec.durationTicks && spec.durationTicks > 0) {
+        messages += 1;
+        if (mpeEnabled) messages += 1;
+      }
+      return { messages, bytes: 3 * messages };
+    },
+    getRateSnapshot(now = 0) {
+      return {
+        now,
+        past: sumWindow(planned, now - 1000, now),
+        next: sumWindow(planned, now, now + 1000),
+        maxMessagesPerSecond: 1000,
+        maxBytesPerSecond: 3906
+      };
+    },
+    getPlanBudget(plan, now = 0) {
+      return planBudgetFromSnapshot(this.getRateSnapshot(now), plan, now);
+    },
+    canSchedule(plan, now = 0, options = {}) {
+      return canScheduleFromSnapshot(this.getRateSnapshot(now), plan, now, options);
+    },
+    reserve(plan, meta = {}, now = 0, options = {}) {
+      const check = this.canSchedule(plan, now, options);
+      if (!check.ok) return check;
+      const reservationId = planned.length + 1;
+      const entries = Array.isArray(plan?.entries)
+        ? plan.entries
+        : [
+          plan?.on ? { ...plan.on, phase: 'on' } : null,
+          plan?.off ? { ...plan.off, phase: 'off' } : null
+        ].filter(Boolean);
+      for (const entry of entries) {
+        planned.push({
+          timeMs: entry.timeMs,
+          count: Math.max(0, Math.trunc(entry.count || 0)),
+          bytes: Math.max(0, Math.trunc(entry.bytes || 0)),
+          sfxId: meta.sfxId,
+          priority: meta.priority,
+          reservationId,
+          phase: entry.phase ?? null
+        });
+      }
+      return { ...check, ok: true, reservationId };
+    },
+    getUsageShare(window = 'past', now = 0) {
+      const data = window === 'next'
+        ? sumWindow(planned, now, now + 1000)
+        : sumWindow(planned, now - 1000, now);
+      const total = data.count || 0;
+      const totalBytes = data.bytes || 0;
+      const shares = [];
+      for (const [sfxId, entry] of data.bySfx.entries()) {
+        shares.push({
+          sfxId,
+          count: entry.count,
+          bytes: entry.bytes,
+          priority: entry.priority ?? 1,
+          percentCount: total ? entry.count / total : 0,
+          percentBytes: totalBytes ? entry.bytes / totalBytes : 0
+        });
+      }
+      shares.sort((a, b) => b.count - a.count);
+      return shares;
+    },
+    sendNote(spec, meta = {}) {
+      sent.push(spec);
+      if (meta.rateReserved === true) return;
+      const timeMs = spec.timeMs ?? 0;
+      const durationMs = (spec.durationTicks ?? 0) * this.tickMs;
+      planned.push({ timeMs, count: 1, bytes: 3, sfxId: meta.sfxId, priority: meta.priority });
+      if (durationMs > 0) {
+        planned.push({ timeMs: timeMs + durationMs, count: 1, bytes: 3, sfxId: meta.sfxId, priority: meta.priority });
+      }
+    },
+    setConfig(config) { this.config = config || {}; },
+    setOutput() {},
+    dispose() {}
+  };
+};
+
+const makeRateSnapshot = (next = {}, past = {}, maxBytesPerSecond = 1000) => ({
+  next: { count: 0, bytes: 0, bySfx: new Map(), ...next },
+  past: { count: 0, bytes: 0, bySfx: new Map(), ...past },
+  maxBytesPerSecond
+});
+
+const makeRateScheduler = (snapshot, usageShare = []) => ({
+  getRateSnapshot(now = 0) {
+    return typeof snapshot === 'function' ? snapshot(now) : snapshot;
+  },
+  getPlanBudget(plan, now = 0) {
+    return planBudgetFromSnapshot(this.getRateSnapshot(now), plan, now);
+  },
+  canSchedule(plan, now = 0, options = {}) {
+    return canScheduleFromSnapshot(this.getRateSnapshot(now), plan, now, options);
+  },
+  reserve(plan, meta = {}, now = 0, options = {}) {
+    const check = this.canSchedule(plan, now, options);
+    return check.ok ? { ...check, reservationId: 1 } : check;
+  },
+  getUsageShare() { return usageShare; }
+});
+
+const makeRateRouter = (config, snapshot, usageShare = []) => (
+  makeRouter(config, { scheduler: makeRateScheduler(snapshot, usageShare) })
+);
+
+const makePlan = ({ timeMs = 0, on = {}, off = {} } = {}) => ({
+  on: { timeMs, count: 0, bytes: 0, ...on },
+  off: { timeMs, count: 0, bytes: 0, ...off }
+});
+
+const makeRouter = (config = {}, options = {}) => {
+  const sent = options.sent ?? [];
+  const mapping = config instanceof MidiMapping ? config : new MidiMapping(config);
+  const router = new MidiEventRouter(mapping);
+  router.scheduler = options.scheduler ?? makeSchedulerStub(sent);
+  router.scheduler.setConfig?.(mapping.config);
+  if (options.output === false) router.scheduler.output = null;
+  if (options.mapEvent) {
+    router.mapping.mapEvent = options.mapEvent;
+  } else if (options.defaultMapEvent) {
+    router.mapping.mapEvent = () => defaultSpec();
+  }
+  return { router, sent, mapping };
+};
+
+const makeArpRouter = (arp, overrides = {}, notes = [60, 64, 67]) => (
+  makeRouter({ limits: { maxEventsPerSecond: 1000 }, ...overrides }, {
+    mapEvent: () => ({
+      notes,
+      note: notes[0],
+      velocity: 64,
+      durationTicks: 1,
+      arp
+    })
+  })
+);
+
+describe('MidiEventRouter 3', function() {
+  it('handles repeat factor and repeat targets directly', function() {
+    const { router } = makeRouter({
+      noteRange: { min: 0, max: 127 },
+      position: { timbreRange: { min: 0, max: 100 }, panRange: { min: -50, max: 50 } }
+    });
+    expect(router._getRepeatFactor('x', 10, { enabled: false }, 120)).to.equal(0);
+    expect(router._getRepeatFactor('x', Number.NaN, { maxRepeats: 1, windowBeats: 1 }, 120)).to.equal(0);
+
+    const baseSpec = { note: 60, velocity: 64, durationTicks: 2, timbre: 50, pan: 0, pitchBend: 0.2 };
+    const noteList = [60, 64];
+    const amountCfg = { amount: 1, target: 'timbre' };
+    const timbreResult = router._applyRepeatTarget(baseSpec, noteList, amountCfg, 0.5);
+    expect(timbreResult.spec.timbre).to.not.equal(50);
+
+    const panResult = router._applyRepeatTarget(baseSpec, noteList, { amount: 1, target: 'pan' }, 0.5);
+    expect(panResult.spec.pan).to.not.equal(0);
+
+    const attackResult = router._applyRepeatTarget(baseSpec, noteList, { amount: 1, target: 'attack' }, 0.5);
+    expect(attackResult.spec.velocity).to.not.equal(64);
+
+    const sustainResult = router._applyRepeatTarget(baseSpec, noteList, { amount: 1, target: 'sustain' }, 0.5);
+    expect(sustainResult.spec.durationTicks).to.not.equal(2);
+    const sustainDefault = router._applyRepeatTarget(
+      { ...baseSpec, durationTicks: null },
+      noteList,
+      { amount: 1, target: 'sustain' },
+      0.5
+    );
+    expect(sustainDefault.spec.durationTicks).to.be.at.least(1);
+
+    const noTimbre = router._applyRepeatTarget({ ...baseSpec, timbre: null }, noteList, { amount: 1, target: 'timbre' }, 0.5);
+    expect(noTimbre.spec.timbre).to.equal(null);
+    const noPan = router._applyRepeatTarget({ ...baseSpec, pan: null }, noteList, { amount: 1, target: 'pan' }, 0.5);
+    expect(noPan.spec.pan).to.equal(null);
+  });
+
+  it('reports priority saturation', function() {
+    const bySfx = new Map([[2, { count: 1000, bytes: 10, priority: 2 }]]);
+    const snapshot = makeRateSnapshot({ count: 1000, bytes: 10, bySfx }, {}, 1000);
+    const usageShare = [
+      { sfxId: 2, count: 1000, bytes: 10, priority: 2, percentCount: 1, percentBytes: 1 }
+    ];
+    const { router } = makeRateRouter({
+      timing: { bpmBase: 60 },
+      limits: { maxEventsPerSecond: 10, hardMaxEventsPerSecond: 2000, maxBytesPerSecond: 1000 }
+    }, snapshot, usageShare);
+    const plan = makePlan({ timeMs: 2000 });
+    const saturated = router._shouldSend({ sfxId: 1, priority: 1 }, { timeMs: 0 }, plan, 0);
+    expect(saturated).to.equal(false);
+    expect(router.getRateReport().reason).to.equal('priority-saturated');
+  });
+
+  it('defaults priorities when missing', function() {
+    const snapshot = makeRateSnapshot(
+      { count: 6, bytes: 0, bySfx: new Map([[2, { count: 1, bytes: 0 }]]) },
+      {},
+      1000
+    );
+    const usageShare = [{ sfxId: 2, count: 1, bytes: 0, percentCount: 1, percentBytes: 0 }];
+    const { router } = makeRateRouter({
+      timing: { bpmBase: 60 },
+      limits: { maxEventsPerSecond: 5, hardMaxEventsPerSecond: 10, maxBytesPerSecond: 1000 }
+    }, snapshot, usageShare);
+    const plan = makePlan({ on: { count: 1 }, off: { timeMs: 2000 } });
+    const ok = router._shouldSend({ sfxId: 1 }, {}, plan, 0);
+    expect(ok).to.equal(true);
+  });
+
+  it('reports spacing limits when events arrive too quickly', function() {
+    const snapshot = makeRateSnapshot({ count: 10, bytes: 0 }, {}, 1000);
+    const { router } = makeRateRouter({
+      timing: { bpmBase: 60 },
+      limits: { maxEventsPerSecond: 10, hardMaxEventsPerSecond: 100, maxBytesPerSecond: 1000 }
+    }, snapshot);
+    const plan = makePlan({ on: { count: 1 }, off: { timeMs: 2000 } });
+    router._lastAcceptedBySfx.set(1, 0);
+    const spacing = router._shouldSend({ sfxId: 1, priority: 1 }, {}, plan, 0);
+    expect(spacing).to.equal(false);
+    expect(router.getRateReport().reason).to.equal('spacing');
+  });
+
+  it('accounts for byte-heavy groups in share overage', function() {
+    const bySfx = new Map([
+      [2, { count: 1, bytes: 90, priority: 2 }],
+      [1, { count: 1, bytes: 20, priority: 1 }]
+    ]);
+    const snapshot = makeRateSnapshot({ count: 20, bytes: 0, bySfx }, {}, 100);
+    const usageShare = [{ sfxId: 1, count: 1, bytes: 20, priority: 1, percentCount: 1, percentBytes: 1 }];
+    const { router } = makeRateRouter({
+      timing: { bpmBase: 120 },
+      limits: { maxEventsPerSecond: 10, hardMaxEventsPerSecond: 100, maxBytesPerSecond: 100 }
+    }, snapshot, usageShare);
+    const plan = makePlan({ timeMs: 2000 });
+    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, { timeMs: 1000 }, plan, 0);
+    expect(ok).to.equal(false);
+    expect(router.getRateReport().reason).to.equal('share-throttle');
+  });
+
+  it('resets arp indices when out of range', function() {
+    const { router, sent } = makeArpRouter({ enabled: true, mode: 'up', length: 3 });
+    router._arpStateBySfx.set('sfx:1', { index: 99, dir: 1, mode: 'up', length: 3, seqKey: '60,64,67' });
+    router._onEvent({ sfxId: 1, tick: 1, tps: 50 });
+    expect(sent[0].note).to.equal(60);
+  });
+
+  it('defaults arp length to the note list', function() {
+    const { router, sent } = makeArpRouter(
+      { enabled: true, mode: 'down' },
+      { limits: { maxEventsPerSecond: 10000 } },
+      [60, 64]
+    );
+    router._onEvent({ sfxId: 1, tick: 1, tps: 50 });
+    expect(sent[0].note).to.equal(64);
+  });
+
+  it('builds context from game state and stage when available', function() {
+    const { router, sent } = makeRouter({ limits: { maxEventsPerSecond: 1000 } }, {
+      mapEvent: (event, context) => {
+        expect(context.levelWidth).to.equal(200);
+        expect(context.levelHeight).to.equal(100);
+        expect(context.viewRect.w).to.equal(200);
+        return { note: 60, velocity: 64, durationTicks: 0 };
+      }
+    });
+    router.context = {
+      game: { level: { width: 200, height: 100 } },
+      stage: { getGameViewRect() { return { x: 0, w: 200 }; } }
+    };
+    router._onEvent({ sfxId: 1, tick: 1, tps: 50 });
+    expect(sent.length).to.equal(1);
+  });
+
+  it('resolves arp keys with fallback coordinates', function() {
+    const { router } = makeRouter();
+    const key = router._resolveArpKey(
+      { triggerType: 7, sfxId: 1, x: NaN },
+      { arp: { independent: true } }
+    );
+    expect(key).to.equal('trigger:7:1:x:y');
+  });
+
+  it('emits performance measurements when enabled', function() {
+    const originalPerf = globalThis.performance;
+    let measures = 0;
+    globalThis.performance = { now: () => 0, measure: () => { measures += 1; } };
+    try {
+      withGlobalLemmings({ performanceAPI: true }, () => {
+        const { router } = makeRouter(
+          { limits: { maxEventsPerSecond: 1000 } },
+          { mapEvent: () => ({ note: 60, velocity: 64, durationTicks: 0 }) }
+        );
+        router._onEvent({ sfxId: 1, tick: 1, tps: 50 });
+        expect(measures).to.equal(1);
+      });
+    } finally {
+      globalThis.performance = originalPerf;
+    }
+  });
+
+  it('swallows performance measurement errors', function() {
+    const originalPerf = globalThis.performance;
+    globalThis.performance = { now: () => 0, measure: () => { throw new Error('boom'); } };
+    try {
+      withGlobalLemmings({ performanceAPI: true }, () => {
+        const { router, sent } = makeRouter(
+          { limits: { maxEventsPerSecond: 1000 } },
+          { mapEvent: () => ({ note: 60, velocity: 64, durationTicks: 0 }) }
+        );
+        router._onEvent({ sfxId: 1, tick: 1, tps: 50 });
+        expect(sent.length).to.equal(1);
+      });
+    } finally {
+      globalThis.performance = originalPerf;
+    }
+  });
+
+  it('dispose detaches and disposes scheduler', function() {
+    const { router } = makeRouter();
+    const bus = { onEvent: new EventHandler() };
+    const calls = [];
+    router.scheduler = { dispose() { calls.push('dispose'); } };
+    router.attach(bus);
+    router.dispose();
+    expect(bus.onEvent.handlers.size).to.equal(0);
+    expect(calls).to.eql(['dispose']);
+  });
+
+  it('computes tick duration and density helpers', function() {
+    const { router } = makeRouter({ density: { windowTicks: 4 } });
+    router.context = { game: { getGameTimer() { return { frameTime: 30 }; } } };
+    expect(router._tickMsFromEvent({ tps: 25 })).to.equal(40);
+    expect(router._tickMsFromEvent({ frameMs: 10 })).to.equal(10);
+    expect(router._tickMsFromEvent({})).to.equal(30);
+
+    expect(router._densityForEvent({})).to.equal(0);
+    router._lastTickBySfx.set(1, 5);
+    expect(router._densityForEvent({ sfxId: 1, tick: 5 })).to.equal(1);
+    expect(router._densityForEvent({ sfxId: 1, tick: 9 })).to.equal(0);
+  });
+
+  it('resets schedule base when timing changes', function() {
+    let cleared = 0;
+    const { router } = makeRouter({}, {
+      scheduler: {
+        allNotesOff() { cleared += 1; },
+        clearQueue() { cleared += 1; }
+      }
+    });
+    router._nowMs = () => 1000;
+
+    expect(router._resolveScheduleBase(NaN, 60, 1)).to.equal(null);
+    const base = router._resolveScheduleBase(100, 60, 1);
+    expect(base).to.equal(900);
+
+    router._resolveScheduleBase(120, 30, 1);
+    expect(cleared).to.equal(2);
+  });
+});
diff --git a/test/midi/midi-event-router.04-midieventrouter.test.js b/test/midi/midi-event-router.04-midieventrouter.test.js
new file mode 100644
index 00000000..6605cb62
--- /dev/null
+++ b/test/midi/midi-event-router.04-midieventrouter.test.js
@@ -0,0 +1,455 @@
+import { expect } from 'chai';
+import { withGlobalLemmings } from '../helpers/lemmings.js';
+import { MidiEventRouter } from '../../js/midi/MidiEventRouter.js';
+import { MidiMapping } from '../../js/midi/MidiMapping.js';
+import { EventHandler } from '../../js/util/EventHandler.js';
+import { toMidiFlagTriggerType } from '../../js/midi/MidiFlagTriggers.js';
+
+const defaultSpec = () => ({ note: 60, velocity: 64, durationTicks: 1 });
+
+const sumPlanEntries = (plan, now = 0, windowMs = 1000) => {
+  const entries = Array.isArray(plan?.entries)
+    ? plan.entries
+    : [plan?.on, plan?.off].filter(Boolean);
+  let count = 0;
+  let bytes = 0;
+  for (const entry of entries) {
+    if (!Number.isFinite(entry?.timeMs)) continue;
+    if (entry.timeMs < now - windowMs || entry.timeMs >= now + windowMs) continue;
+    const entryCount = Math.max(0, Math.trunc(entry.count || 0));
+    const entryBytes = Math.max(0, Math.trunc(entry.bytes || entryCount * 3));
+    count += entryCount;
+    bytes += entryBytes;
+  }
+  return { count, bytes };
+};
+
+const planBudgetFromSnapshot = (snapshot, plan, now = 0) => {
+  const proposed = sumPlanEntries(plan, now);
+  return {
+    snapshot,
+    proposed,
+    combined: {
+      count: (snapshot?.past?.count || 0) + (snapshot?.next?.count || 0) + proposed.count,
+      bytes: (snapshot?.past?.bytes || 0) + (snapshot?.next?.bytes || 0) + proposed.bytes
+    }
+  };
+};
+
+const canScheduleFromSnapshot = (snapshot, plan, now = 0, options = {}) => {
+  const maxMessagesPerSecond = Math.max(1, options.maxMessagesPerSecond ?? snapshot?.maxMessagesPerSecond ?? 1000);
+  const maxBytesPerSecond = Math.max(1, options.maxBytesPerSecond ?? snapshot?.maxBytesPerSecond ?? 3906);
+  const budget = planBudgetFromSnapshot(snapshot, plan, now);
+  const overMessages = budget.combined.count > maxMessagesPerSecond;
+  const overBytes = budget.combined.bytes > maxBytesPerSecond;
+  return {
+    ok: !overMessages && !overBytes,
+    reason: overBytes ? 'byte-limit' : (overMessages ? 'count-limit' : null),
+    maxMessagesPerSecond,
+    maxBytesPerSecond,
+    ...budget
+  };
+};
+
+const makeSchedulerStub = (sent) => {
+  const planned = [];
+  const sumWindow = (entries, start, end) => {
+    let count = 0;
+    let bytes = 0;
+    const bySfx = new Map();
+    for (const entry of entries) {
+      if (entry.timeMs < start || entry.timeMs >= end) continue;
+      count += entry.count;
+      bytes += entry.bytes;
+      const curr = bySfx.get(entry.sfxId) || { count: 0, bytes: 0, priority: entry.priority ?? 1 };
+      curr.count += entry.count;
+      curr.bytes += entry.bytes;
+      bySfx.set(entry.sfxId, curr);
+    }
+    return { count, bytes, bySfx };
+  };
+  return {
+    output: {},
+    tickMs: 60,
+    config: {},
+    setTickMs(ms) { this.tickMs = ms; },
+    estimateMessages(spec) {
+      if (!spec || !Number.isFinite(spec.note)) return { messages: 0, bytes: 0 };
+      const mpeEnabled = !!this.config?.mpe?.enabled;
+      let messages = 1;
+      if (mpeEnabled) {
+        messages += 1;
+      } else if (spec.pitchBend != null && Number.isFinite(spec.pitchBend) && spec.pitchBend !== 0) {
+        messages += 1;
+      }
+      if (spec.timbre != null && Number.isFinite(spec.timbre)) messages += 1;
+      if (spec.pan != null && Number.isFinite(spec.pan)) messages += 1;
+      if (spec.durationTicks && spec.durationTicks > 0) {
+        messages += 1;
+        if (mpeEnabled) messages += 1;
+      }
+      return { messages, bytes: 3 * messages };
+    },
+    getRateSnapshot(now = 0) {
+      return {
+        now,
+        past: sumWindow(planned, now - 1000, now),
+        next: sumWindow(planned, now, now + 1000),
+        maxMessagesPerSecond: 1000,
+        maxBytesPerSecond: 3906
+      };
+    },
+    getPlanBudget(plan, now = 0) {
+      return planBudgetFromSnapshot(this.getRateSnapshot(now), plan, now);
+    },
+    canSchedule(plan, now = 0, options = {}) {
+      return canScheduleFromSnapshot(this.getRateSnapshot(now), plan, now, options);
+    },
+    reserve(plan, meta = {}, now = 0, options = {}) {
+      const check = this.canSchedule(plan, now, options);
+      if (!check.ok) return check;
+      const reservationId = planned.length + 1;
+      const entries = Array.isArray(plan?.entries)
+        ? plan.entries
+        : [
+          plan?.on ? { ...plan.on, phase: 'on' } : null,
+          plan?.off ? { ...plan.off, phase: 'off' } : null
+        ].filter(Boolean);
+      for (const entry of entries) {
+        planned.push({
+          timeMs: entry.timeMs,
+          count: Math.max(0, Math.trunc(entry.count || 0)),
+          bytes: Math.max(0, Math.trunc(entry.bytes || 0)),
+          sfxId: meta.sfxId,
+          priority: meta.priority,
+          reservationId,
+          phase: entry.phase ?? null
+        });
+      }
+      return { ...check, ok: true, reservationId };
+    },
+    getUsageShare(window = 'past', now = 0) {
+      const data = window === 'next'
+        ? sumWindow(planned, now, now + 1000)
+        : sumWindow(planned, now - 1000, now);
+      const total = data.count || 0;
+      const totalBytes = data.bytes || 0;
+      const shares = [];
+      for (const [sfxId, entry] of data.bySfx.entries()) {
+        shares.push({
+          sfxId,
+          count: entry.count,
+          bytes: entry.bytes,
+          priority: entry.priority ?? 1,
+          percentCount: total ? entry.count / total : 0,
+          percentBytes: totalBytes ? entry.bytes / totalBytes : 0
+        });
+      }
+      shares.sort((a, b) => b.count - a.count);
+      return shares;
+    },
+    sendNote(spec, meta = {}) {
+      sent.push(spec);
+      if (meta.rateReserved === true) return;
+      const timeMs = spec.timeMs ?? 0;
+      const durationMs = (spec.durationTicks ?? 0) * this.tickMs;
+      planned.push({ timeMs, count: 1, bytes: 3, sfxId: meta.sfxId, priority: meta.priority });
+      if (durationMs > 0) {
+        planned.push({ timeMs: timeMs + durationMs, count: 1, bytes: 3, sfxId: meta.sfxId, priority: meta.priority });
+      }
+    },
+    setConfig(config) { this.config = config || {}; },
+    setOutput() {},
+    dispose() {}
+  };
+};
+
+const makeRateSnapshot = (next = {}, past = {}, maxBytesPerSecond = 1000) => ({
+  next: { count: 0, bytes: 0, bySfx: new Map(), ...next },
+  past: { count: 0, bytes: 0, bySfx: new Map(), ...past },
+  maxBytesPerSecond
+});
+
+const makeRateScheduler = (snapshot, usageShare = []) => ({
+  getRateSnapshot(now = 0) {
+    return typeof snapshot === 'function' ? snapshot(now) : snapshot;
+  },
+  getPlanBudget(plan, now = 0) {
+    return planBudgetFromSnapshot(this.getRateSnapshot(now), plan, now);
+  },
+  canSchedule(plan, now = 0, options = {}) {
+    return canScheduleFromSnapshot(this.getRateSnapshot(now), plan, now, options);
+  },
+  reserve(plan, meta = {}, now = 0, options = {}) {
+    const check = this.canSchedule(plan, now, options);
+    return check.ok ? { ...check, reservationId: 1 } : check;
+  },
+  getUsageShare() { return usageShare; }
+});
+
+const makeRateRouter = (config, snapshot, usageShare = []) => (
+  makeRouter(config, { scheduler: makeRateScheduler(snapshot, usageShare) })
+);
+
+const makePlan = ({ timeMs = 0, on = {}, off = {} } = {}) => ({
+  on: { timeMs, count: 0, bytes: 0, ...on },
+  off: { timeMs, count: 0, bytes: 0, ...off }
+});
+
+const makeRouter = (config = {}, options = {}) => {
+  const sent = options.sent ?? [];
+  const mapping = config instanceof MidiMapping ? config : new MidiMapping(config);
+  const router = new MidiEventRouter(mapping);
+  router.scheduler = options.scheduler ?? makeSchedulerStub(sent);
+  router.scheduler.setConfig?.(mapping.config);
+  if (options.output === false) router.scheduler.output = null;
+  if (options.mapEvent) {
+    router.mapping.mapEvent = options.mapEvent;
+  } else if (options.defaultMapEvent) {
+    router.mapping.mapEvent = () => defaultSpec();
+  }
+  return { router, sent, mapping };
+};
+
+const makeArpRouter = (arp, overrides = {}, notes = [60, 64, 67]) => (
+  makeRouter({ limits: { maxEventsPerSecond: 1000 }, ...overrides }, {
+    mapEvent: () => ({
+      notes,
+      note: notes[0],
+      velocity: 64,
+      durationTicks: 1,
+      arp
+    })
+  })
+);
+
+describe('MidiEventRouter 4', function() {
+  it('computes priorities, bpm, and arp keys', function() {
+    const { router } = makeRouter({
+      limits: { prioritySfx: [5] },
+      timing: { bpmBase: 10 }
+    });
+    router.context = { game: { getGameTimer() { return { speedFactor: 2 }; } } };
+
+    expect(router._getEventPriority({ sfxId: 5 }, {})).to.equal(2);
+    expect(router._getEventPriority({ sfxId: 1 }, { priority: 3 })).to.equal(3);
+    expect(router._getEventPriority({ sfxId: 2 }, {})).to.equal(1);
+    expect(router._getBpm()).to.equal(20);
+
+    const arpCfg = { arp: { independent: true } };
+    expect(router._resolveArpKey({ triggerType: 7, sfxId: 1, objectId: 10 }, arpCfg))
+      .to.equal('trigger:7:1:object:10');
+    expect(router._resolveArpKey({ triggerType: 7, sfxId: 1, lemmingId: 5 }, arpCfg))
+      .to.equal('trigger:7:1:lemming:5');
+    expect(router._resolveArpKey({ triggerType: 7, sfxId: 1, x: 1, y: 2 }, arpCfg))
+      .to.equal('trigger:7:1:1:2');
+    expect(router._resolveArpKey({ sfxId: 2 }, {})).to.equal('sfx:2');
+  });
+
+  it('computes repeat factors and applies multiple targets', function() {
+    const { router } = makeRouter({
+      noteRange: { min: 0, max: 127 },
+      position: { timbreRange: { min: 0, max: 127 }, panRange: { min: -127, max: 127 } }
+    });
+
+    const repeatCfg = { maxRepeats: 2, windowBeats: 1, amount: 0.5, target: 'velocity' };
+    expect(router._getRepeatFactor('sfx:1', 0, repeatCfg, 60)).to.equal(0);
+    expect(router._getRepeatFactor('sfx:1', 500, repeatCfg, 60)).to.equal(0.5);
+
+    const baseSpec = { note: 60, velocity: 64, durationTicks: 4, releaseVelocity: 64 };
+    const notes = [60, 64];
+    const velocity = router._applyRepeatTarget(baseSpec, notes, repeatCfg, 0.5).spec;
+    expect(velocity.velocity).to.be.greaterThan(64);
+
+    const duration = router._applyRepeatTarget(baseSpec, notes, { amount: 0.5, target: 'duration' }, 1).spec;
+    expect(duration.durationTicks).to.be.greaterThan(4);
+
+    const note = router._applyRepeatTarget(baseSpec, notes, { amount: 0.5, target: 'note' }, 1);
+    expect(note.activeNotes[0]).to.be.greaterThan(60);
+
+    const timbre = router._applyRepeatTarget({ ...baseSpec, timbre: 10 }, notes, { amount: 0.5, target: 'timbre' }, 1).spec;
+    expect(timbre.timbre).to.be.greaterThan(10);
+
+    const pan = router._applyRepeatTarget({ ...baseSpec, pan: 0 }, notes, { amount: 0.5, target: 'pan' }, 1).spec;
+    expect(pan.pan).to.not.equal(0);
+
+    const bend = router._applyRepeatTarget({ ...baseSpec, pitchBend: 0.2 }, notes, { amount: 0.5, target: 'pitchBend' }, 1).spec;
+    expect(bend.pitchBend).to.be.greaterThan(0.2);
+
+    const attack = router._applyRepeatTarget(baseSpec, notes, { amount: 0.5, target: 'attack' }, 1).spec;
+    expect(attack.velocity).to.be.greaterThan(64);
+
+    const sustain = router._applyRepeatTarget(baseSpec, notes, { amount: 0.5, target: 'sustain' }, 1).spec;
+    expect(sustain.durationTicks).to.be.greaterThan(4);
+
+    const release = router._applyRepeatTarget(baseSpec, notes, { amount: 0.5, target: 'release' }, 1).spec;
+    expect(release.releaseVelocity).to.be.greaterThan(64);
+
+    const noAmount = router._applyRepeatTarget(baseSpec, notes, { target: 'velocity' }, 1);
+    expect(noAmount.spec.velocity).to.equal(64);
+  });
+
+  it('plans entries with mpe-aware off messages', function() {
+    const { router } = makeRouter({ mpe: { enabled: true } });
+    router.scheduler.tickMs = 10;
+    const plan = router._planEntries({ note: 60, durationTicks: 2 }, 100, 2);
+    expect(plan.on.count).to.equal(4);
+    expect(plan.off.count).to.equal(4);
+    const zero = router._planEntries({ note: 60, durationTicks: 0 }, 100, 1);
+    expect(zero.off.count).to.equal(0);
+  });
+
+  it('drops events when hard count limits are exceeded', function() {
+    const snapshot = makeRateSnapshot({ count: 7, bytes: 0 }, { count: 0, bytes: 0 }, 1000);
+    const { router } = makeRateRouter(
+      { limits: { maxEventsPerSecond: 5, hardMaxEventsPerSecond: 6 } },
+      snapshot
+    );
+    const plan = makePlan();
+    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, {}, plan, 0);
+    expect(ok).to.equal(false);
+    expect(router.getRateReport().reason).to.equal('count-limit');
+  });
+
+  it('drops events when higher priority consumes the budget', function() {
+    const bySfx = new Map([[2, { count: 5, bytes: 0, priority: 2 }]]);
+    const snapshot = makeRateSnapshot({ count: 5, bytes: 0, bySfx }, { count: 0, bytes: 0 }, 1000);
+    const { router } = makeRateRouter(
+      { limits: { maxEventsPerSecond: 5, hardMaxEventsPerSecond: 100, maxBytesPerSecond: 1000 } },
+      snapshot
+    );
+    const plan = makePlan({ on: { count: 1, bytes: 3 } });
+    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, {}, plan, 0);
+    expect(ok).to.equal(false);
+    expect(router.getRateReport().reason).to.equal('priority-saturated');
+  });
+
+  it('drops events when spacing or share budgets are exceeded', function() {
+    const scheduler = makeRateScheduler(
+      makeRateSnapshot({ count: 1, bytes: 0 }, { count: 0, bytes: 0 }, 100)
+    );
+    const { router } = makeRouter({
+      limits: { maxEventsPerSecond: 1, hardMaxEventsPerSecond: 100, maxBytesPerSecond: 100 },
+      timing: { bpmBase: 60 }
+    }, { scheduler });
+    const maxPerSecond = Math.min(
+      Math.max(router.mapping.config?.limits?.maxEventsPerSecond ?? 1000, 1),
+      1000
+    );
+    router._lastAcceptedBySfx.set(1, 0);
+    const spacingPlan = makePlan({ on: { count: maxPerSecond, bytes: 3 } });
+    const spacingOk = router._shouldSend(
+      { sfxId: 1, priority: 1 },
+      { timeMs: 0 },
+      spacingPlan,
+      0
+    );
+    expect(spacingOk).to.equal(false);
+    expect(router.getRateReport().reason).to.equal('spacing');
+
+    const bySfx = new Map([[1, { count: 4, bytes: 0, priority: 1 }]]);
+    router.scheduler.getRateSnapshot = () => (
+      makeRateSnapshot({ count: 4, bytes: 0, bySfx }, { count: 0, bytes: 0 }, 100)
+    );
+    router.scheduler.getUsageShare = () => ([
+      { sfxId: 1, count: 4, bytes: 0, priority: 1, percentCount: 1, percentBytes: 0 }
+    ]);
+    router._lastAcceptedBySfx.delete(1);
+    const sharePlan = makePlan({ timeMs: 2000, on: { count: 1, bytes: 3 } });
+    const shareOk = router._shouldSend(
+      { sfxId: 1, priority: 1 },
+      { timeMs: 2000 },
+      sharePlan,
+      2000
+    );
+    expect(shareOk).to.equal(false);
+    expect(router.getRateReport().reason).to.equal('share-throttle');
+  });
+
+  it('handles rate limits and early exits', function() {
+    const { router, sent } = makeRouter({ enabled: false });
+    router._onEvent({ sfxId: 1, tick: 1 });
+    expect(sent.length).to.equal(0);
+
+    router.setMapping({ enabled: true, limits: { maxEventsPerSecond: 1000 } });
+    router.scheduler.output = null;
+    router._onEvent({ sfxId: 1, tick: 1 });
+    expect(sent.length).to.equal(0);
+
+    router.scheduler.output = {};
+    router.mapping.mapEvent = () => null;
+    router._onEvent({ sfxId: 1, tick: 1 });
+    expect(sent.length).to.equal(0);
+
+    router.mapping.mapEvent = () => ({ note: 1, velocity: 1, durationTicks: 1 });
+    router.setMapping({ enabled: true, limits: { maxEventsPerSecond: 1 } });
+    router._onEvent({ sfxId: 1, tick: 1 });
+    router._onEvent({ sfxId: 1, tick: 2 });
+    expect(sent.length).to.equal(0);
+  });
+
+  it('forwards output updates and handles unknown repeat targets', function() {
+    let seen = null;
+    const { router } = makeRouter({}, { scheduler: { setOutput(output) { seen = output; } } });
+    const output = { channels: {} };
+    router.setOutput(output);
+    expect(seen).to.equal(output);
+
+    const spec = { note: 60, velocity: 64, durationTicks: 2 };
+    const result = router._applyRepeatTarget(
+      spec,
+      [60],
+      { amount: 0.5, target: 'unknown-target' },
+      1
+    );
+    expect(result.spec).to.deep.equal(spec);
+  });
+
+  it('forwards usage share queries to the scheduler', function() {
+    const { router } = makeRouter({}, { scheduler: { getUsageShare: window => [{ window }] } });
+    const share = router.getUsageShare('next');
+    expect(share[0].window).to.equal('next');
+  });
+
+  it('covers tick defaults and density edge cases', function() {
+    const { router, mapping } = makeRouter({ density: { windowTicks: 0 } });
+    router.context = {};
+
+    expect(router._tickMsFromEvent({})).to.equal(60);
+    expect(router._densityForEvent({ sfxId: 1, tick: 1 })).to.equal(0);
+
+    router.mapping.config.density.windowTicks = 5;
+    expect(router._densityForEvent({ sfxId: null, tick: 1 })).to.equal(0);
+    router._lastTickBySfx.set(1, 5);
+    expect(router._densityForEvent({ sfxId: 1, tick: 5 })).to.equal(1);
+    expect(router._densityForEvent({ sfxId: 1, tick: 20 })).to.equal(0);
+  });
+
+  it('falls back to Date.now when performance is missing', function() {
+    const { router } = makeRouter();
+    const originalPerf = globalThis.performance;
+    const originalDateNow = Date.now;
+    Date.now = () => 123;
+    globalThis.performance = undefined;
+    try {
+      expect(router._nowMs()).to.equal(123);
+    } finally {
+      Date.now = originalDateNow;
+      globalThis.performance = originalPerf;
+    }
+  });
+
+  it('reuses schedule base and respects spacing tick repeats', function() {
+    const { router, mapping } = makeRouter({ repeat: { maxRepeats: 2, spacingTicks: 2 } });
+    router._nowMs = () => 1000;
+    const base = router._resolveScheduleBase(100, 60, 1);
+    expect(base).to.equal(900);
+    const again = router._resolveScheduleBase(200, 60, 1);
+    expect(again).to.equal(base);
+
+    const factorA = router._getRepeatFactor('sfx:1', 1000, mapping.config.repeat, 60);
+    const factorB = router._getRepeatFactor('sfx:1', 1100, mapping.config.repeat, 60);
+    expect(factorA).to.equal(0);
+    expect(factorB).to.be.greaterThan(0);
+  });
+});
diff --git a/test/midi/midi-event-router.05-midieventrouter.test.js b/test/midi/midi-event-router.05-midieventrouter.test.js
new file mode 100644
index 00000000..ec3cbf52
--- /dev/null
+++ b/test/midi/midi-event-router.05-midieventrouter.test.js
@@ -0,0 +1,451 @@
+import { expect } from 'chai';
+import { withGlobalLemmings } from '../helpers/lemmings.js';
+import { MidiEventRouter } from '../../js/midi/MidiEventRouter.js';
+import { MidiMapping } from '../../js/midi/MidiMapping.js';
+import { EventHandler } from '../../js/util/EventHandler.js';
+import { toMidiFlagTriggerType } from '../../js/midi/MidiFlagTriggers.js';
+
+const defaultSpec = () => ({ note: 60, velocity: 64, durationTicks: 1 });
+
+const sumPlanEntries = (plan, now = 0, windowMs = 1000) => {
+  const entries = Array.isArray(plan?.entries)
+    ? plan.entries
+    : [plan?.on, plan?.off].filter(Boolean);
+  let count = 0;
+  let bytes = 0;
+  for (const entry of entries) {
+    if (!Number.isFinite(entry?.timeMs)) continue;
+    if (entry.timeMs < now - windowMs || entry.timeMs >= now + windowMs) continue;
+    const entryCount = Math.max(0, Math.trunc(entry.count || 0));
+    const entryBytes = Math.max(0, Math.trunc(entry.bytes || entryCount * 3));
+    count += entryCount;
+    bytes += entryBytes;
+  }
+  return { count, bytes };
+};
+
+const planBudgetFromSnapshot = (snapshot, plan, now = 0) => {
+  const proposed = sumPlanEntries(plan, now);
+  return {
+    snapshot,
+    proposed,
+    combined: {
+      count: (snapshot?.past?.count || 0) + (snapshot?.next?.count || 0) + proposed.count,
+      bytes: (snapshot?.past?.bytes || 0) + (snapshot?.next?.bytes || 0) + proposed.bytes
+    }
+  };
+};
+
+const canScheduleFromSnapshot = (snapshot, plan, now = 0, options = {}) => {
+  const maxMessagesPerSecond = Math.max(1, options.maxMessagesPerSecond ?? snapshot?.maxMessagesPerSecond ?? 1000);
+  const maxBytesPerSecond = Math.max(1, options.maxBytesPerSecond ?? snapshot?.maxBytesPerSecond ?? 3906);
+  const budget = planBudgetFromSnapshot(snapshot, plan, now);
+  const overMessages = budget.combined.count > maxMessagesPerSecond;
+  const overBytes = budget.combined.bytes > maxBytesPerSecond;
+  return {
+    ok: !overMessages && !overBytes,
+    reason: overBytes ? 'byte-limit' : (overMessages ? 'count-limit' : null),
+    maxMessagesPerSecond,
+    maxBytesPerSecond,
+    ...budget
+  };
+};
+
+const makeSchedulerStub = (sent) => {
+  const planned = [];
+  const sumWindow = (entries, start, end) => {
+    let count = 0;
+    let bytes = 0;
+    const bySfx = new Map();
+    for (const entry of entries) {
+      if (entry.timeMs < start || entry.timeMs >= end) continue;
+      count += entry.count;
+      bytes += entry.bytes;
+      const curr = bySfx.get(entry.sfxId) || { count: 0, bytes: 0, priority: entry.priority ?? 1 };
+      curr.count += entry.count;
+      curr.bytes += entry.bytes;
+      bySfx.set(entry.sfxId, curr);
+    }
+    return { count, bytes, bySfx };
+  };
+  return {
+    output: {},
+    tickMs: 60,
+    config: {},
+    setTickMs(ms) { this.tickMs = ms; },
+    estimateMessages(spec) {
+      if (!spec || !Number.isFinite(spec.note)) return { messages: 0, bytes: 0 };
+      const mpeEnabled = !!this.config?.mpe?.enabled;
+      let messages = 1;
+      if (mpeEnabled) {
+        messages += 1;
+      } else if (spec.pitchBend != null && Number.isFinite(spec.pitchBend) && spec.pitchBend !== 0) {
+        messages += 1;
+      }
+      if (spec.timbre != null && Number.isFinite(spec.timbre)) messages += 1;
+      if (spec.pan != null && Number.isFinite(spec.pan)) messages += 1;
+      if (spec.durationTicks && spec.durationTicks > 0) {
+        messages += 1;
+        if (mpeEnabled) messages += 1;
+      }
+      return { messages, bytes: 3 * messages };
+    },
+    getRateSnapshot(now = 0) {
+      return {
+        now,
+        past: sumWindow(planned, now - 1000, now),
+        next: sumWindow(planned, now, now + 1000),
+        maxMessagesPerSecond: 1000,
+        maxBytesPerSecond: 3906
+      };
+    },
+    getPlanBudget(plan, now = 0) {
+      return planBudgetFromSnapshot(this.getRateSnapshot(now), plan, now);
+    },
+    canSchedule(plan, now = 0, options = {}) {
+      return canScheduleFromSnapshot(this.getRateSnapshot(now), plan, now, options);
+    },
+    reserve(plan, meta = {}, now = 0, options = {}) {
+      const check = this.canSchedule(plan, now, options);
+      if (!check.ok) return check;
+      const reservationId = planned.length + 1;
+      const entries = Array.isArray(plan?.entries)
+        ? plan.entries
+        : [
+          plan?.on ? { ...plan.on, phase: 'on' } : null,
+          plan?.off ? { ...plan.off, phase: 'off' } : null
+        ].filter(Boolean);
+      for (const entry of entries) {
+        planned.push({
+          timeMs: entry.timeMs,
+          count: Math.max(0, Math.trunc(entry.count || 0)),
+          bytes: Math.max(0, Math.trunc(entry.bytes || 0)),
+          sfxId: meta.sfxId,
+          priority: meta.priority,
+          reservationId,
+          phase: entry.phase ?? null
+        });
+      }
+      return { ...check, ok: true, reservationId };
+    },
+    getUsageShare(window = 'past', now = 0) {
+      const data = window === 'next'
+        ? sumWindow(planned, now, now + 1000)
+        : sumWindow(planned, now - 1000, now);
+      const total = data.count || 0;
+      const totalBytes = data.bytes || 0;
+      const shares = [];
+      for (const [sfxId, entry] of data.bySfx.entries()) {
+        shares.push({
+          sfxId,
+          count: entry.count,
+          bytes: entry.bytes,
+          priority: entry.priority ?? 1,
+          percentCount: total ? entry.count / total : 0,
+          percentBytes: totalBytes ? entry.bytes / totalBytes : 0
+        });
+      }
+      shares.sort((a, b) => b.count - a.count);
+      return shares;
+    },
+    sendNote(spec, meta = {}) {
+      sent.push(spec);
+      if (meta.rateReserved === true) return;
+      const timeMs = spec.timeMs ?? 0;
+      const durationMs = (spec.durationTicks ?? 0) * this.tickMs;
+      planned.push({ timeMs, count: 1, bytes: 3, sfxId: meta.sfxId, priority: meta.priority });
+      if (durationMs > 0) {
+        planned.push({ timeMs: timeMs + durationMs, count: 1, bytes: 3, sfxId: meta.sfxId, priority: meta.priority });
+      }
+    },
+    setConfig(config) { this.config = config || {}; },
+    setOutput() {},
+    dispose() {}
+  };
+};
+
+const makeRateSnapshot = (next = {}, past = {}, maxBytesPerSecond = 1000) => ({
+  next: { count: 0, bytes: 0, bySfx: new Map(), ...next },
+  past: { count: 0, bytes: 0, bySfx: new Map(), ...past },
+  maxBytesPerSecond
+});
+
+const makeRateScheduler = (snapshot, usageShare = []) => ({
+  getRateSnapshot(now = 0) {
+    return typeof snapshot === 'function' ? snapshot(now) : snapshot;
+  },
+  getPlanBudget(plan, now = 0) {
+    return planBudgetFromSnapshot(this.getRateSnapshot(now), plan, now);
+  },
+  canSchedule(plan, now = 0, options = {}) {
+    return canScheduleFromSnapshot(this.getRateSnapshot(now), plan, now, options);
+  },
+  reserve(plan, meta = {}, now = 0, options = {}) {
+    const check = this.canSchedule(plan, now, options);
+    return check.ok ? { ...check, reservationId: 1 } : check;
+  },
+  getUsageShare() { return usageShare; }
+});
+
+const makeRateRouter = (config, snapshot, usageShare = []) => (
+  makeRouter(config, { scheduler: makeRateScheduler(snapshot, usageShare) })
+);
+
+const makePlan = ({ timeMs = 0, on = {}, off = {} } = {}) => ({
+  on: { timeMs, count: 0, bytes: 0, ...on },
+  off: { timeMs, count: 0, bytes: 0, ...off }
+});
+
+const makeRouter = (config = {}, options = {}) => {
+  const sent = options.sent ?? [];
+  const mapping = config instanceof MidiMapping ? config : new MidiMapping(config);
+  const router = new MidiEventRouter(mapping);
+  router.scheduler = options.scheduler ?? makeSchedulerStub(sent);
+  router.scheduler.setConfig?.(mapping.config);
+  if (options.output === false) router.scheduler.output = null;
+  if (options.mapEvent) {
+    router.mapping.mapEvent = options.mapEvent;
+  } else if (options.defaultMapEvent) {
+    router.mapping.mapEvent = () => defaultSpec();
+  }
+  return { router, sent, mapping };
+};
+
+const makeArpRouter = (arp, overrides = {}, notes = [60, 64, 67]) => (
+  makeRouter({ limits: { maxEventsPerSecond: 1000 }, ...overrides }, {
+    mapEvent: () => ({
+      notes,
+      note: notes[0],
+      velocity: 64,
+      durationTicks: 1,
+      arp
+    })
+  })
+);
+
+describe('MidiEventRouter 5', function() {
+  it('returns repeat targets unchanged for missing numeric fields', function() {
+    const { router } = makeRouter();
+    const base = { note: 60, velocity: 64, durationTicks: 1 };
+    const none = router._applyRepeatTarget(base, [60], { amount: 1, target: 'timbre' }, 1);
+    expect(none.spec.timbre).to.equal(undefined);
+    const pan = router._applyRepeatTarget(base, [60], { amount: 1, target: 'pan' }, 1);
+    expect(pan.spec.pan).to.equal(undefined);
+    const bend = router._applyRepeatTarget(base, [60], { amount: 1, target: 'pitchBend' }, 1);
+    expect(bend.spec.pitchBend).to.equal(undefined);
+  });
+
+  it('drops events when available bytes are exhausted', function() {
+    const bySfx = new Map([[2, { count: 1, bytes: 100, priority: 2 }]]);
+    const snapshot = makeRateSnapshot({ count: 6, bytes: 100, bySfx }, { count: 0, bytes: 0 }, 100);
+    const { router } = makeRateRouter(
+      { limits: { maxEventsPerSecond: 5, hardMaxEventsPerSecond: 10, maxBytesPerSecond: 100 } },
+      snapshot
+    );
+    const plan = makePlan();
+    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, {}, plan, 0);
+    expect(ok).to.equal(false);
+    expect(router.getRateReport().reason).to.equal('byte-limit');
+  });
+
+  it('handles share reports without current entries', function() {
+    const bySfx = new Map([[2, { count: 5, bytes: 0, priority: 1 }]]);
+    const snapshot = makeRateSnapshot({ count: 6, bytes: 0, bySfx }, { count: 0, bytes: 0 }, 100);
+    const usageShare = [{ sfxId: 2, count: 5, bytes: 0, priority: 1, percentCount: 1, percentBytes: 0 }];
+    const { router } = makeRateRouter(
+      { limits: { maxEventsPerSecond: 5, hardMaxEventsPerSecond: 10, maxBytesPerSecond: 100 } },
+      snapshot,
+      usageShare
+    );
+    const plan = makePlan({ on: { count: 1, bytes: 3 }, off: { timeMs: 2000 } });
+    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, { timeMs: 0 }, plan, 0);
+    expect(ok).to.equal(true);
+  });
+
+  it('sends notes when ticks are missing and notes are empty', function() {
+    const { router, sent } = makeRouter(
+      { limits: { maxEventsPerSecond: 1000 } },
+      { mapEvent: () => ({ note: 60, notes: [], velocity: 64, durationTicks: 0 }) }
+    );
+    router._nowMs = () => 10;
+
+    router._onEvent({ sfxId: 1, timeMs: NaN });
+    expect(sent.length).to.equal(1);
+  });
+
+  it('constructs mapping from plain config objects', function() {
+    const router = new MidiEventRouter({ enabled: false });
+    expect(router.mapping).to.be.instanceOf(MidiMapping);
+    const routerWithMapping = new MidiEventRouter(new MidiMapping());
+    expect(routerWithMapping.mapping).to.be.instanceOf(MidiMapping);
+  });
+
+  it('attach removes existing listeners when re-attaching', function() {
+    let offCalls = 0;
+    const busA = { onEvent: { on() {}, off() { offCalls += 1; } } };
+    const busB = { onEvent: { on() {}, off() {} } };
+    const { router } = makeRouter();
+    router.attach(busA);
+    router.attach(busB);
+    expect(offCalls).to.equal(1);
+  });
+
+  it('tickMsFromEvent falls back to defaults without timers', function() {
+    const { router } = makeRouter();
+    router.context = {};
+    expect(router._tickMsFromEvent({})).to.equal(60);
+  });
+
+  it('tickMsFromEvent ignores invalid timing payloads', function() {
+    const { router } = makeRouter();
+    router.context = { game: { getGameTimer() { return { frameTime: 33 }; } } };
+    expect(router._tickMsFromEvent({ tps: 0, frameMs: -10 })).to.equal(33);
+    router.context = { game: { getGameTimer() { return { frameTime: 0 }; } } };
+    expect(router._tickMsFromEvent({ tps: -20, frameMs: Number.NaN })).to.equal(60);
+  });
+
+  it('nowMs uses performance when available', function() {
+    const { router } = makeRouter();
+    const originalPerf = globalThis.performance;
+    globalThis.performance = { now: () => 456 };
+    try {
+      expect(router._nowMs()).to.equal(456);
+    } finally {
+      globalThis.performance = originalPerf;
+    }
+  });
+
+  it('resets schedule base when speed changes without frame changes', function() {
+    let cleared = 0;
+    const { router } = makeRouter({}, {
+      scheduler: {
+        allNotesOff() { cleared += 1; },
+        clearQueue() { cleared += 1; }
+      }
+    });
+    router._nowMs = () => 1000;
+    router._resolveScheduleBase(100, 60, 1);
+    router._resolveScheduleBase(120, 60, 2);
+    expect(cleared).to.equal(2);
+    router._resolveScheduleBase(140, NaN, NaN);
+  });
+
+  it('getBpm returns scaled values above the minimum', function() {
+    const { router } = makeRouter({ timing: { bpmBase: 120 } });
+    router.context = { game: { getGameTimer() { return { speedFactor: 2 }; } } };
+    expect(router._getBpm()).to.equal(240);
+  });
+
+  it('resolveArpKey falls back when independence is disabled', function() {
+    const { router } = makeRouter();
+    expect(router._resolveArpKey({ triggerType: 3, sfxId: 2 }, { arp: { independent: false } }))
+      .to.equal('sfx:2');
+  });
+
+  it('getRepeatFactor returns zero for invalid repeat windows', function() {
+    const { router } = makeRouter();
+    expect(router._getRepeatFactor('sfx:1', 10, { maxRepeats: 0, windowBeats: 1 }, 120)).to.equal(0);
+    expect(router._getRepeatFactor('sfx:1', NaN, { maxRepeats: 2, windowBeats: 1 }, 120)).to.equal(0);
+    expect(router._getRepeatFactor('sfx:1', 10, { maxRepeats: 2, windowBeats: 1 }, 0)).to.equal(0);
+  });
+
+  it('applyRepeatTarget handles accent targets and zero factors', function() {
+    const { router } = makeRouter();
+    const baseSpec = { note: 60, velocity: 64, durationTicks: 2, releaseVelocity: 64 };
+    const unchanged = router._applyRepeatTarget(baseSpec, [60], { amount: 1, target: 'velocity' }, 0);
+    expect(unchanged.spec.velocity).to.equal(64);
+    const accent = router._applyRepeatTarget(baseSpec, [60], { amount: 0.5, target: 'accent' }, 1);
+    expect(accent.spec.velocity).to.be.greaterThan(64);
+  });
+
+  it('planEntries uses default off messages without MPE', function() {
+    const { router } = makeRouter({ mpe: { enabled: false } });
+    router.scheduler.tickMs = 10;
+    const plan = router._planEntries({ note: 60, durationTicks: 1 }, 1000, 1);
+    expect(plan.off.count).to.equal(1);
+  });
+
+  it('shouldSend ignores plans outside the next window', function() {
+    const snapshot = makeRateSnapshot();
+    const { router } = makeRateRouter(
+      { limits: { maxEventsPerSecond: 10, maxBytesPerSecond: 1000 } },
+      snapshot
+    );
+    const plan = makePlan({ on: { count: 1, bytes: 3 }, off: { timeMs: 5000, count: 1, bytes: 3 } });
+    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, {}, plan, 1000);
+    expect(ok).to.equal(true);
+  });
+
+  it('shouldSend accounts for higher and same priority entries', function() {
+    const bySfx = new Map([
+      [1, { count: 2, bytes: 6, priority: 1 }],
+      [2, { count: 2, bytes: 6, priority: 2 }]
+    ]);
+    const snapshot = makeRateSnapshot({ count: 4, bytes: 12, bySfx }, {}, 1000);
+    const { router } = makeRateRouter(
+      { limits: { maxEventsPerSecond: 10, maxBytesPerSecond: 1000 } },
+      snapshot
+    );
+    const plan = makePlan({ timeMs: 1000, on: { count: 1, bytes: 3 }, off: { timeMs: 1000 } });
+    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, { timeMs: 1000 }, plan, 1000);
+    expect(ok).to.equal(true);
+  });
+
+  it('tickMsFromEvent uses frameMs and timer fallbacks', function() {
+    const { router } = makeRouter();
+    expect(router._tickMsFromEvent({ frameMs: 33 })).to.equal(33);
+    router.context = { game: { getGameTimer() { return { frameTime: 42 }; } } };
+    expect(router._tickMsFromEvent({})).to.equal(42);
+  });
+
+  it('density handles zero and window limits', function() {
+    const { router } = makeRouter({ density: { windowTicks: 4 } });
+    router._lastTickBySfx.set(1, 10);
+    expect(router._densityForEvent({ sfxId: 1, tick: 10 })).to.equal(1);
+    expect(router._densityForEvent({ sfxId: 1, tick: 12 })).to.be.closeTo(0.5, 0.01);
+    expect(router._densityForEvent({ sfxId: 1, tick: 20 })).to.equal(0);
+    expect(router._densityForEvent({ sfxId: 2, tick: 1 })).to.equal(0);
+  });
+
+  it('resolveScheduleBase resets on frame or speed changes', function() {
+    const { router } = makeRouter();
+    router.scheduler = {};
+    router._nowMs = () => 1000;
+    expect(router._resolveScheduleBase(NaN, 0, 0)).to.equal(null);
+    router._resolveScheduleBase(100, 60, 1);
+
+    router.scheduler = { allNotesOff() { this.off = true; }, clearQueue() { this.clear = true; } };
+    router._resolveScheduleBase(110, 120, 1);
+    expect(router.scheduler.off).to.equal(true);
+    router._resolveScheduleBase(120, 120, 2);
+    expect(router.scheduler.clear).to.equal(true);
+    router._resolveScheduleBase(140, NaN, NaN);
+  });
+
+  it('getEventPriority uses sfx priority and priority lists', function() {
+    const { router } = makeRouter({ limits: { prioritySfx: [5] } });
+    expect(router._getEventPriority({ sfxId: 1 }, { priority: 3 })).to.equal(3);
+    expect(router._getEventPriority({ sfxId: 5 }, {})).to.equal(2);
+  });
+
+  it('resolveArpKey builds independent trigger keys', function() {
+    const { router } = makeRouter();
+    const sfx = { arp: { independent: true } };
+    expect(router._resolveArpKey({ triggerType: 1, sfxId: 2, objectId: 3 }, sfx))
+      .to.equal('trigger:1:2:object:3');
+    expect(router._resolveArpKey({ triggerType: 1, sfxId: 2, lemmingId: 4 }, sfx))
+      .to.equal('trigger:1:2:lemming:4');
+    expect(router._resolveArpKey({ triggerType: 1, sfxId: 2, x: 3, y: 4 }, sfx))
+      .to.equal('trigger:1:2:3:4');
+  });
+
+  it('getRepeatFactor uses spacingTicks and history', function() {
+    const { router } = makeRouter();
+    const repeatCfg = { maxRepeats: 2, spacingTicks: 1 };
+    const bpm = 120;
+    const first = router._getRepeatFactor('sfx:1', 0, repeatCfg, bpm);
+    const second = router._getRepeatFactor('sfx:1', 100, repeatCfg, bpm);
+    expect(first).to.equal(0);
+    expect(second).to.be.greaterThan(0);
+  });
+});
diff --git a/test/midi/midi-event-router.06-midieventrouter.test.js b/test/midi/midi-event-router.06-midieventrouter.test.js
new file mode 100644
index 00000000..b0b5a4d7
--- /dev/null
+++ b/test/midi/midi-event-router.06-midieventrouter.test.js
@@ -0,0 +1,454 @@
+import { expect } from 'chai';
+import { withGlobalLemmings } from '../helpers/lemmings.js';
+import { MidiEventRouter } from '../../js/midi/MidiEventRouter.js';
+import { MidiMapping } from '../../js/midi/MidiMapping.js';
+import { EventHandler } from '../../js/util/EventHandler.js';
+import { toMidiFlagTriggerType } from '../../js/midi/MidiFlagTriggers.js';
+
+const defaultSpec = () => ({ note: 60, velocity: 64, durationTicks: 1 });
+
+const sumPlanEntries = (plan, now = 0, windowMs = 1000) => {
+  const entries = Array.isArray(plan?.entries)
+    ? plan.entries
+    : [plan?.on, plan?.off].filter(Boolean);
+  let count = 0;
+  let bytes = 0;
+  for (const entry of entries) {
+    if (!Number.isFinite(entry?.timeMs)) continue;
+    if (entry.timeMs < now - windowMs || entry.timeMs >= now + windowMs) continue;
+    const entryCount = Math.max(0, Math.trunc(entry.count || 0));
+    const entryBytes = Math.max(0, Math.trunc(entry.bytes || entryCount * 3));
+    count += entryCount;
+    bytes += entryBytes;
+  }
+  return { count, bytes };
+};
+
+const planBudgetFromSnapshot = (snapshot, plan, now = 0) => {
+  const proposed = sumPlanEntries(plan, now);
+  return {
+    snapshot,
+    proposed,
+    combined: {
+      count: (snapshot?.past?.count || 0) + (snapshot?.next?.count || 0) + proposed.count,
+      bytes: (snapshot?.past?.bytes || 0) + (snapshot?.next?.bytes || 0) + proposed.bytes
+    }
+  };
+};
+
+const canScheduleFromSnapshot = (snapshot, plan, now = 0, options = {}) => {
+  const maxMessagesPerSecond = Math.max(1, options.maxMessagesPerSecond ?? snapshot?.maxMessagesPerSecond ?? 1000);
+  const maxBytesPerSecond = Math.max(1, options.maxBytesPerSecond ?? snapshot?.maxBytesPerSecond ?? 3906);
+  const budget = planBudgetFromSnapshot(snapshot, plan, now);
+  const overMessages = budget.combined.count > maxMessagesPerSecond;
+  const overBytes = budget.combined.bytes > maxBytesPerSecond;
+  return {
+    ok: !overMessages && !overBytes,
+    reason: overBytes ? 'byte-limit' : (overMessages ? 'count-limit' : null),
+    maxMessagesPerSecond,
+    maxBytesPerSecond,
+    ...budget
+  };
+};
+
+const makeSchedulerStub = (sent) => {
+  const planned = [];
+  const sumWindow = (entries, start, end) => {
+    let count = 0;
+    let bytes = 0;
+    const bySfx = new Map();
+    for (const entry of entries) {
+      if (entry.timeMs < start || entry.timeMs >= end) continue;
+      count += entry.count;
+      bytes += entry.bytes;
+      const curr = bySfx.get(entry.sfxId) || { count: 0, bytes: 0, priority: entry.priority ?? 1 };
+      curr.count += entry.count;
+      curr.bytes += entry.bytes;
+      bySfx.set(entry.sfxId, curr);
+    }
+    return { count, bytes, bySfx };
+  };
+  return {
+    output: {},
+    tickMs: 60,
+    config: {},
+    setTickMs(ms) { this.tickMs = ms; },
+    estimateMessages(spec) {
+      if (!spec || !Number.isFinite(spec.note)) return { messages: 0, bytes: 0 };
+      const mpeEnabled = !!this.config?.mpe?.enabled;
+      let messages = 1;
+      if (mpeEnabled) {
+        messages += 1;
+      } else if (spec.pitchBend != null && Number.isFinite(spec.pitchBend) && spec.pitchBend !== 0) {
+        messages += 1;
+      }
+      if (spec.timbre != null && Number.isFinite(spec.timbre)) messages += 1;
+      if (spec.pan != null && Number.isFinite(spec.pan)) messages += 1;
+      if (spec.durationTicks && spec.durationTicks > 0) {
+        messages += 1;
+        if (mpeEnabled) messages += 1;
+      }
+      return { messages, bytes: 3 * messages };
+    },
+    getRateSnapshot(now = 0) {
+      return {
+        now,
+        past: sumWindow(planned, now - 1000, now),
+        next: sumWindow(planned, now, now + 1000),
+        maxMessagesPerSecond: 1000,
+        maxBytesPerSecond: 3906
+      };
+    },
+    getPlanBudget(plan, now = 0) {
+      return planBudgetFromSnapshot(this.getRateSnapshot(now), plan, now);
+    },
+    canSchedule(plan, now = 0, options = {}) {
+      return canScheduleFromSnapshot(this.getRateSnapshot(now), plan, now, options);
+    },
+    reserve(plan, meta = {}, now = 0, options = {}) {
+      const check = this.canSchedule(plan, now, options);
+      if (!check.ok) return check;
+      const reservationId = planned.length + 1;
+      const entries = Array.isArray(plan?.entries)
+        ? plan.entries
+        : [
+          plan?.on ? { ...plan.on, phase: 'on' } : null,
+          plan?.off ? { ...plan.off, phase: 'off' } : null
+        ].filter(Boolean);
+      for (const entry of entries) {
+        planned.push({
+          timeMs: entry.timeMs,
+          count: Math.max(0, Math.trunc(entry.count || 0)),
+          bytes: Math.max(0, Math.trunc(entry.bytes || 0)),
+          sfxId: meta.sfxId,
+          priority: meta.priority,
+          reservationId,
+          phase: entry.phase ?? null
+        });
+      }
+      return { ...check, ok: true, reservationId };
+    },
+    getUsageShare(window = 'past', now = 0) {
+      const data = window === 'next'
+        ? sumWindow(planned, now, now + 1000)
+        : sumWindow(planned, now - 1000, now);
+      const total = data.count || 0;
+      const totalBytes = data.bytes || 0;
+      const shares = [];
+      for (const [sfxId, entry] of data.bySfx.entries()) {
+        shares.push({
+          sfxId,
+          count: entry.count,
+          bytes: entry.bytes,
+          priority: entry.priority ?? 1,
+          percentCount: total ? entry.count / total : 0,
+          percentBytes: totalBytes ? entry.bytes / totalBytes : 0
+        });
+      }
+      shares.sort((a, b) => b.count - a.count);
+      return shares;
+    },
+    sendNote(spec, meta = {}) {
+      sent.push(spec);
+      if (meta.rateReserved === true) return;
+      const timeMs = spec.timeMs ?? 0;
+      const durationMs = (spec.durationTicks ?? 0) * this.tickMs;
+      planned.push({ timeMs, count: 1, bytes: 3, sfxId: meta.sfxId, priority: meta.priority });
+      if (durationMs > 0) {
+        planned.push({ timeMs: timeMs + durationMs, count: 1, bytes: 3, sfxId: meta.sfxId, priority: meta.priority });
+      }
+    },
+    setConfig(config) { this.config = config || {}; },
+    setOutput() {},
+    dispose() {}
+  };
+};
+
+const makeRateSnapshot = (next = {}, past = {}, maxBytesPerSecond = 1000) => ({
+  next: { count: 0, bytes: 0, bySfx: new Map(), ...next },
+  past: { count: 0, bytes: 0, bySfx: new Map(), ...past },
+  maxBytesPerSecond
+});
+
+const makeRateScheduler = (snapshot, usageShare = []) => ({
+  getRateSnapshot(now = 0) {
+    return typeof snapshot === 'function' ? snapshot(now) : snapshot;
+  },
+  getPlanBudget(plan, now = 0) {
+    return planBudgetFromSnapshot(this.getRateSnapshot(now), plan, now);
+  },
+  canSchedule(plan, now = 0, options = {}) {
+    return canScheduleFromSnapshot(this.getRateSnapshot(now), plan, now, options);
+  },
+  reserve(plan, meta = {}, now = 0, options = {}) {
+    const check = this.canSchedule(plan, now, options);
+    return check.ok ? { ...check, reservationId: 1 } : check;
+  },
+  getUsageShare() { return usageShare; }
+});
+
+const makeRateRouter = (config, snapshot, usageShare = []) => (
+  makeRouter(config, { scheduler: makeRateScheduler(snapshot, usageShare) })
+);
+
+const makePlan = ({ timeMs = 0, on = {}, off = {} } = {}) => ({
+  on: { timeMs, count: 0, bytes: 0, ...on },
+  off: { timeMs, count: 0, bytes: 0, ...off }
+});
+
+const makeRouter = (config = {}, options = {}) => {
+  const sent = options.sent ?? [];
+  const mapping = config instanceof MidiMapping ? config : new MidiMapping(config);
+  const router = new MidiEventRouter(mapping);
+  router.scheduler = options.scheduler ?? makeSchedulerStub(sent);
+  router.scheduler.setConfig?.(mapping.config);
+  if (options.output === false) router.scheduler.output = null;
+  if (options.mapEvent) {
+    router.mapping.mapEvent = options.mapEvent;
+  } else if (options.defaultMapEvent) {
+    router.mapping.mapEvent = () => defaultSpec();
+  }
+  return { router, sent, mapping };
+};
+
+const makeArpRouter = (arp, overrides = {}, notes = [60, 64, 67]) => (
+  makeRouter({ limits: { maxEventsPerSecond: 1000 }, ...overrides }, {
+    mapEvent: () => ({
+      notes,
+      note: notes[0],
+      velocity: 64,
+      durationTicks: 1,
+      arp
+    })
+  })
+);
+
+describe('MidiEventRouter 6', function() {
+  it('applyRepeatTarget covers additional targets', function() {
+    const { router } = makeRouter({
+      noteRange: { min: 0, max: 127 },
+      position: { timbreRange: { min: 0, max: 100 }, panRange: { min: -50, max: 50 } }
+    });
+    const baseSpec = { note: 60, velocity: 64, durationTicks: 4, timbre: 10, pan: 5, pitchBend: 0.2, releaseVelocity: 30 };
+    const baseNotes = [60, 64];
+
+    const duration = router._applyRepeatTarget(baseSpec, baseNotes, { amount: 1, target: 'duration' }, 1);
+    expect(duration.spec.durationTicks).to.be.greaterThan(4);
+    const note = router._applyRepeatTarget(baseSpec, baseNotes, { amount: 1, target: 'note' }, 1);
+    expect(note.activeNotes[0]).to.not.equal(60);
+    const timbre = router._applyRepeatTarget({ ...baseSpec, timbre: 10 }, baseNotes, { amount: 1, target: 'timbre' }, 1);
+    expect(timbre.spec.timbre).to.be.greaterThan(10);
+    const pan = router._applyRepeatTarget({ ...baseSpec, pan: 5 }, baseNotes, { amount: 1, target: 'pan' }, 1);
+    expect(pan.spec.pan).to.be.a('number');
+    const bend = router._applyRepeatTarget({ ...baseSpec, pitchBend: 0.5 }, baseNotes, { amount: 1, target: 'pitchBend' }, 1);
+    expect(bend.spec.pitchBend).to.be.a('number');
+    const attack = router._applyRepeatTarget(baseSpec, baseNotes, { amount: 1, target: 'attack' }, 1);
+    expect(attack.spec.velocity).to.be.greaterThan(64);
+    const sustain = router._applyRepeatTarget(baseSpec, baseNotes, { amount: 1, target: 'sustain' }, 1);
+    expect(sustain.spec.durationTicks).to.be.greaterThan(4);
+    const release = router._applyRepeatTarget(baseSpec, baseNotes, { amount: 1, target: 'release' }, 1);
+    expect(release.spec.releaseVelocity).to.be.greaterThan(0);
+
+    const ignored = router._applyRepeatTarget({ ...baseSpec, timbre: null }, baseNotes, { amount: 1, target: 'timbre' }, 1);
+    expect(ignored.spec.timbre).to.equal(null);
+    const unchanged = router._applyRepeatTarget(baseSpec, baseNotes, { amount: 0, target: 'velocity' }, 1);
+    expect(unchanged.spec).to.equal(baseSpec);
+  });
+
+  it('planEntries accounts for duration and MPE off messages', function() {
+    const { router } = makeRouter({ mpe: { enabled: true } });
+    router.scheduler.tickMs = 10;
+    const plan = router._planEntries({ note: 60, durationTicks: 2 }, 1000, 2);
+    expect(plan.off.count).to.equal(4);
+    const zero = router._planEntries({ note: 60, durationTicks: NaN }, 1000, 1);
+    expect(zero.off.count).to.equal(0);
+  });
+
+  it('shouldSend rejects when count exceeds the hard max', function() {
+    const snapshot = makeRateSnapshot({ count: 6, bytes: 0 }, {}, 1000);
+    const { router } = makeRateRouter(
+      { limits: { maxEventsPerSecond: 5, hardMaxEventsPerSecond: 6, maxBytesPerSecond: 1000 } },
+      snapshot
+    );
+    const plan = makePlan({ on: { count: 1, bytes: 3 }, off: { count: 1, bytes: 3 } });
+    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, { timeMs: 0 }, plan, 0);
+    expect(ok).to.equal(false);
+    expect(router.getRateReport().reason).to.equal('count-limit');
+  });
+
+  it('shouldSend handles priority saturation', function() {
+    const bySfx = new Map([[2, { count: 5, bytes: 10, priority: 2 }]]);
+    const snapshot = makeRateSnapshot({ count: 5, bytes: 10, bySfx }, {}, 100);
+    const usageShare = [{ sfxId: 2, count: 5, bytes: 10, priority: 2, percentCount: 1, percentBytes: 1 }];
+    const { router } = makeRateRouter(
+      { limits: { maxEventsPerSecond: 5, hardMaxEventsPerSecond: 10, maxBytesPerSecond: 100 } },
+      snapshot,
+      usageShare
+    );
+    const plan = makePlan({ on: { count: 1, bytes: 3 } });
+    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, { timeMs: 0 }, plan, 0);
+    expect(ok).to.equal(false);
+    expect(router.getRateReport().reason).to.equal('priority-saturated');
+  });
+
+  it('shouldSend rejects when available bytes are exhausted', function() {
+    const bySfx = new Map([[2, { count: 1, bytes: 10, priority: 2 }]]);
+    const snapshot = makeRateSnapshot({ count: 1, bytes: 10, bySfx }, {}, 10);
+    const usageShare = [{ sfxId: 2, count: 1, bytes: 10, priority: 2, percentCount: 1, percentBytes: 1 }];
+    const { router } = makeRateRouter(
+      { limits: { maxEventsPerSecond: 5, hardMaxEventsPerSecond: 10, maxBytesPerSecond: 10 } },
+      snapshot,
+      usageShare
+    );
+    const plan = makePlan({ on: { count: 1, bytes: 3 } });
+    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, { timeMs: 0 }, plan, 0);
+    expect(ok).to.equal(false);
+    expect(router.getRateReport().reason).to.equal('byte-limit');
+  });
+
+  it('shouldSend rejects when spacing is violated', function() {
+    const bySfx = new Map([[1, { count: 1, bytes: 3, priority: 1 }]]);
+    const snapshot = makeRateSnapshot({ count: 1, bytes: 3, bySfx }, {}, 1000);
+    const usageShare = [{ sfxId: 1, count: 1, bytes: 3, priority: 1, percentCount: 1, percentBytes: 0 }];
+    const { router } = makeRateRouter(
+      { limits: { maxEventsPerSecond: 1, hardMaxEventsPerSecond: 10, maxBytesPerSecond: 1000 } },
+      snapshot,
+      usageShare
+    );
+    router._lastAcceptedBySfx.set(1, 1000);
+    const plan = makePlan({ timeMs: 1000, on: { count: 1, bytes: 3 }, off: { timeMs: 1000 } });
+    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, { timeMs: 1000 }, plan, 1000);
+    expect(ok).to.equal(false);
+    expect(router.getRateReport().reason).to.equal('spacing');
+  });
+
+  it('shouldSend rejects when share budgets are exceeded', function() {
+    const bySfx = new Map([[1, { count: 2, bytes: 6, priority: 1 }]]);
+    const snapshot = makeRateSnapshot({ count: 2, bytes: 6, bySfx }, {}, 100);
+    const usageShare = [{ sfxId: 1, count: 2, bytes: 6, priority: 1, percentCount: 1, percentBytes: 0 }];
+    const { router } = makeRateRouter(
+      { limits: { maxEventsPerSecond: 2, hardMaxEventsPerSecond: 10, maxBytesPerSecond: 100 } },
+      snapshot,
+      usageShare
+    );
+    const plan = makePlan({ on: { count: 1, bytes: 3 } });
+    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, { timeMs: 0 }, plan, 0);
+    expect(ok).to.equal(false);
+    expect(router.getRateReport().reason).to.equal('share-throttle');
+  });
+
+  it('covers setup helpers and schedule resets', function() {
+    const { router, mapping } = makeRouter({ timing: { bpmBase: 100 } });
+    expect(router.mapping).to.equal(mapping);
+
+    const routerAlt = new MidiEventRouter({ timing: { bpmBase: 90 } });
+    expect(routerAlt.mapping).to.be.instanceof(MidiMapping);
+
+    let offCalls = 0;
+    const busA = { onEvent: { on() {}, off() { offCalls += 1; } } };
+    const busB = { onEvent: { on() {}, off() { offCalls += 1; } } };
+    router.attach(busA);
+    router.attach(busB);
+    router.detach();
+    expect(offCalls).to.be.greaterThan(0);
+
+    router.context = { game: { getGameTimer() { return { frameTime: 33, speedFactor: 1.5 }; } } };
+    expect(router._tickMsFromEvent({ tps: 50 })).to.equal(20);
+    expect(router._tickMsFromEvent({ frameMs: 40 })).to.equal(40);
+    expect(router._tickMsFromEvent({})).to.equal(33);
+
+    router.mapping.config.density = { windowTicks: 4 };
+    router._lastTickBySfx.set(1, 10);
+    expect(router._densityForEvent({ sfxId: 1, tick: 10 })).to.equal(1);
+    expect(router._densityForEvent({ sfxId: 1, tick: 14 })).to.equal(0);
+    expect(router._densityForEvent({ sfxId: 1, tick: 12 })).to.be.greaterThan(0);
+
+    router.scheduler = {
+      allNotesOff() { this.called = true; },
+      clearQueue() { this.cleared = true; }
+    };
+    router._clockFrameMs = 60;
+    router._clockSpeedFactor = 1;
+    const base = router._resolveScheduleBase(100, 30, 0.5);
+    expect(base).to.be.a('number');
+    expect(router._resolveScheduleBase(NaN, 30, 0.5)).to.equal(null);
+  });
+
+  it('covers priority, bpm, and arp keys', function() {
+    const { router } = makeRouter({ limits: { prioritySfx: [2] }, timing: { bpmBase: 120 } });
+    router.context = { game: { getGameTimer() { return { speedFactor: 2 }; } } };
+    expect(router._getEventPriority({ sfxId: 2 }, {})).to.equal(2);
+    expect(router._getEventPriority({ sfxId: 3 }, { priority: 5 })).to.equal(5);
+    expect(router._getEventPriority({ sfxId: 3 }, {})).to.equal(1);
+    expect(router._getBpm()).to.equal(240);
+
+    const sfx = { arp: { independent: true } };
+    expect(router._resolveArpKey({ triggerType: 1, sfxId: 2, objectId: 9 }, sfx)).to.include('object:9');
+    expect(router._resolveArpKey({ triggerType: 1, sfxId: 2, lemmingId: 3 }, sfx)).to.include('lemming:3');
+    expect(router._resolveArpKey({ triggerType: 1, sfxId: 2, x: 1, y: 2 }, sfx)).to.include('trigger:1:2');
+    expect(router._resolveArpKey({ sfxId: 2 }, {})).to.include('sfx:2');
+  });
+
+  it('covers repeat factors and targets', function() {
+    const { router } = makeRouter({
+      noteRange: { min: 0, max: 127 },
+      position: { timbreRange: { min: 0, max: 127 }, panRange: { min: -127, max: 127 } }
+    });
+    const repeatCfg = { maxRepeats: 2, windowBeats: 1 };
+    expect(router._getRepeatFactor('a', NaN, repeatCfg, 120)).to.equal(0);
+    router._getRepeatFactor('a', 0, repeatCfg, 120);
+    const factor = router._getRepeatFactor('a', 100, repeatCfg, 120);
+    expect(factor).to.be.greaterThan(0);
+
+    const spec = { note: 60, velocity: 64, durationTicks: 4, timbre: 10, pan: 0, pitchBend: 0.1, releaseVelocity: 50 };
+    const notes = [60, 64];
+    expect(router._applyRepeatTarget(spec, notes, { target: 'velocity' }, 0).spec).to.equal(spec);
+    expect(router._applyRepeatTarget(spec, notes, { target: 'velocity' }, 0.5).spec).to.equal(spec);
+    expect(router._applyRepeatTarget(spec, notes, { amount: 0, target: 'velocity' }, 1).spec).to.equal(spec);
+
+    router._applyRepeatTarget(spec, notes, { amount: 1, target: 'velocity' }, 0.5);
+    router._applyRepeatTarget(spec, notes, { amount: 1, target: 'duration' }, 0.5);
+    router._applyRepeatTarget(spec, notes, { amount: 1, target: 'note' }, 0.5);
+    router._applyRepeatTarget({ ...spec, timbre: NaN }, notes, { amount: 1, target: 'timbre' }, 0.5);
+    router._applyRepeatTarget(spec, notes, { amount: 1, target: 'timbre' }, 0.5);
+    router._applyRepeatTarget({ ...spec, pan: NaN }, notes, { amount: 1, target: 'pan' }, 0.5);
+    router._applyRepeatTarget(spec, notes, { amount: 1, target: 'pan' }, 0.5);
+    router._applyRepeatTarget({ ...spec, pitchBend: NaN }, notes, { amount: 1, target: 'pitchBend' }, 0.5);
+    router._applyRepeatTarget(spec, notes, { amount: 1, target: 'pitchBend' }, 0.5);
+    router._applyRepeatTarget(spec, notes, { amount: 1, target: 'attack' }, 0.5);
+    router._applyRepeatTarget(spec, notes, { amount: 1, target: 'decay' }, 0.5);
+    router._applyRepeatTarget(spec, notes, { amount: 1, target: 'sustain' }, 0.5);
+    router._applyRepeatTarget(spec, notes, { amount: 1, target: 'release' }, 0.5);
+    router._applyRepeatTarget(spec, notes, { amount: 1, target: 'unknown' }, 0.5);
+  });
+
+  it('plans entries and handles shouldSend under limits', function() {
+    const snapshot = makeRateSnapshot();
+    const scheduler = {
+      ...makeRateScheduler(snapshot),
+      tickMs: 50,
+      estimateMessages() { return { messages: 2, bytes: 6 }; }
+    };
+    const { router } = makeRouter(
+      { limits: { maxEventsPerSecond: 10, hardMaxEventsPerSecond: 10, maxBytesPerSecond: 1000 } },
+      { scheduler }
+    );
+    const plan = router._planEntries({ durationTicks: NaN }, -2000, 1);
+    expect(plan.off.count).to.equal(0);
+    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, { timeMs: -2000 }, plan, 0);
+    expect(ok).to.equal(true);
+  });
+
+  it('shouldSend rejects when hard max is exceeded', function() {
+    const bySfx = new Map();
+    const snapshot = makeRateSnapshot({ count: 2, bytes: 0, bySfx }, {}, 1000);
+    const { router } = makeRateRouter(
+      { limits: { maxEventsPerSecond: 1, hardMaxEventsPerSecond: 1, maxBytesPerSecond: 1000 } },
+      snapshot
+    );
+    const plan = makePlan();
+    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, { timeMs: 0 }, plan, 0);
+    expect(ok).to.equal(false);
+    expect(router.getRateReport().reason).to.equal('count-limit');
+  });
+});
diff --git a/test/midi/midi-event-router.07-midieventrouter.test.js b/test/midi/midi-event-router.07-midieventrouter.test.js
new file mode 100644
index 00000000..87e98fcf
--- /dev/null
+++ b/test/midi/midi-event-router.07-midieventrouter.test.js
@@ -0,0 +1,540 @@
+import { expect } from 'chai';
+import { withGlobalLemmings } from '../helpers/lemmings.js';
+import { MidiEventRouter } from '../../js/midi/MidiEventRouter.js';
+import { MidiMapping } from '../../js/midi/MidiMapping.js';
+import {
+  createMidiProjectFromMidiConfig,
+  projectToMidiConfig,
+  reduceMidiProject
+} from '../../js/midi/project/MidiProject.js';
+import { EventHandler } from '../../js/util/EventHandler.js';
+import { toMidiFlagTriggerType } from '../../js/midi/MidiFlagTriggers.js';
+
+const defaultSpec = () => ({ note: 60, velocity: 64, durationTicks: 1 });
+
+const sumPlanEntries = (plan, now = 0, windowMs = 1000) => {
+  const entries = Array.isArray(plan?.entries)
+    ? plan.entries
+    : [plan?.on, plan?.off].filter(Boolean);
+  let count = 0;
+  let bytes = 0;
+  for (const entry of entries) {
+    if (!Number.isFinite(entry?.timeMs)) continue;
+    if (entry.timeMs < now - windowMs || entry.timeMs >= now + windowMs) continue;
+    const entryCount = Math.max(0, Math.trunc(entry.count || 0));
+    const entryBytes = Math.max(0, Math.trunc(entry.bytes || entryCount * 3));
+    count += entryCount;
+    bytes += entryBytes;
+  }
+  return { count, bytes };
+};
+
+const planBudgetFromSnapshot = (snapshot, plan, now = 0) => {
+  const proposed = sumPlanEntries(plan, now);
+  return {
+    snapshot,
+    proposed,
+    combined: {
+      count: (snapshot?.past?.count || 0) + (snapshot?.next?.count || 0) + proposed.count,
+      bytes: (snapshot?.past?.bytes || 0) + (snapshot?.next?.bytes || 0) + proposed.bytes
+    }
+  };
+};
+
+const canScheduleFromSnapshot = (snapshot, plan, now = 0, options = {}) => {
+  const maxMessagesPerSecond = Math.max(1, options.maxMessagesPerSecond ?? snapshot?.maxMessagesPerSecond ?? 1000);
+  const maxBytesPerSecond = Math.max(1, options.maxBytesPerSecond ?? snapshot?.maxBytesPerSecond ?? 3906);
+  const budget = planBudgetFromSnapshot(snapshot, plan, now);
+  const overMessages = budget.combined.count > maxMessagesPerSecond;
+  const overBytes = budget.combined.bytes > maxBytesPerSecond;
+  return {
+    ok: !overMessages && !overBytes,
+    reason: overBytes ? 'byte-limit' : (overMessages ? 'count-limit' : null),
+    maxMessagesPerSecond,
+    maxBytesPerSecond,
+    ...budget
+  };
+};
+
+const makeSchedulerStub = (sent) => {
+  const planned = [];
+  const sumWindow = (entries, start, end) => {
+    let count = 0;
+    let bytes = 0;
+    const bySfx = new Map();
+    for (const entry of entries) {
+      if (entry.timeMs < start || entry.timeMs >= end) continue;
+      count += entry.count;
+      bytes += entry.bytes;
+      const curr = bySfx.get(entry.sfxId) || { count: 0, bytes: 0, priority: entry.priority ?? 1 };
+      curr.count += entry.count;
+      curr.bytes += entry.bytes;
+      bySfx.set(entry.sfxId, curr);
+    }
+    return { count, bytes, bySfx };
+  };
+  return {
+    output: {},
+    tickMs: 60,
+    config: {},
+    setTickMs(ms) { this.tickMs = ms; },
+    estimateMessages(spec) {
+      if (!spec || !Number.isFinite(spec.note)) return { messages: 0, bytes: 0 };
+      const mpeEnabled = !!this.config?.mpe?.enabled;
+      let messages = 1;
+      if (mpeEnabled) {
+        messages += 1;
+      } else if (spec.pitchBend != null && Number.isFinite(spec.pitchBend) && spec.pitchBend !== 0) {
+        messages += 1;
+      }
+      if (spec.timbre != null && Number.isFinite(spec.timbre)) messages += 1;
+      if (spec.pan != null && Number.isFinite(spec.pan)) messages += 1;
+      if (spec.durationTicks && spec.durationTicks > 0) {
+        messages += 1;
+        if (mpeEnabled) messages += 1;
+      }
+      return { messages, bytes: 3 * messages };
+    },
+    getRateSnapshot(now = 0) {
+      return {
+        now,
+        past: sumWindow(planned, now - 1000, now),
+        next: sumWindow(planned, now, now + 1000),
+        maxMessagesPerSecond: 1000,
+        maxBytesPerSecond: 3906
+      };
+    },
+    getPlanBudget(plan, now = 0) {
+      return planBudgetFromSnapshot(this.getRateSnapshot(now), plan, now);
+    },
+    canSchedule(plan, now = 0, options = {}) {
+      return canScheduleFromSnapshot(this.getRateSnapshot(now), plan, now, options);
+    },
+    reserve(plan, meta = {}, now = 0, options = {}) {
+      const check = this.canSchedule(plan, now, options);
+      if (!check.ok) return check;
+      const reservationId = planned.length + 1;
+      const entries = Array.isArray(plan?.entries)
+        ? plan.entries
+        : [
+          plan?.on ? { ...plan.on, phase: 'on' } : null,
+          plan?.off ? { ...plan.off, phase: 'off' } : null
+        ].filter(Boolean);
+      for (const entry of entries) {
+        planned.push({
+          timeMs: entry.timeMs,
+          count: Math.max(0, Math.trunc(entry.count || 0)),
+          bytes: Math.max(0, Math.trunc(entry.bytes || 0)),
+          sfxId: meta.sfxId,
+          priority: meta.priority,
+          reservationId,
+          phase: entry.phase ?? null
+        });
+      }
+      return { ...check, ok: true, reservationId };
+    },
+    getUsageShare(window = 'past', now = 0) {
+      const data = window === 'next'
+        ? sumWindow(planned, now, now + 1000)
+        : sumWindow(planned, now - 1000, now);
+      const total = data.count || 0;
+      const totalBytes = data.bytes || 0;
+      const shares = [];
+      for (const [sfxId, entry] of data.bySfx.entries()) {
+        shares.push({
+          sfxId,
+          count: entry.count,
+          bytes: entry.bytes,
+          priority: entry.priority ?? 1,
+          percentCount: total ? entry.count / total : 0,
+          percentBytes: totalBytes ? entry.bytes / totalBytes : 0
+        });
+      }
+      shares.sort((a, b) => b.count - a.count);
+      return shares;
+    },
+    sendNote(spec, meta = {}) {
+      sent.push(spec);
+      if (meta.rateReserved === true) return;
+      const timeMs = spec.timeMs ?? 0;
+      const durationMs = (spec.durationTicks ?? 0) * this.tickMs;
+      planned.push({ timeMs, count: 1, bytes: 3, sfxId: meta.sfxId, priority: meta.priority });
+      if (durationMs > 0) {
+        planned.push({ timeMs: timeMs + durationMs, count: 1, bytes: 3, sfxId: meta.sfxId, priority: meta.priority });
+      }
+    },
+    setConfig(config) { this.config = config || {}; },
+    setOutput() {},
+    dispose() {}
+  };
+};
+
+const makeRateSnapshot = (next = {}, past = {}, maxBytesPerSecond = 1000) => ({
+  next: { count: 0, bytes: 0, bySfx: new Map(), ...next },
+  past: { count: 0, bytes: 0, bySfx: new Map(), ...past },
+  maxBytesPerSecond
+});
+
+const makeRateScheduler = (snapshot, usageShare = []) => ({
+  getRateSnapshot(now = 0) {
+    return typeof snapshot === 'function' ? snapshot(now) : snapshot;
+  },
+  getPlanBudget(plan, now = 0) {
+    return planBudgetFromSnapshot(this.getRateSnapshot(now), plan, now);
+  },
+  canSchedule(plan, now = 0, options = {}) {
+    return canScheduleFromSnapshot(this.getRateSnapshot(now), plan, now, options);
+  },
+  reserve(plan, meta = {}, now = 0, options = {}) {
+    const check = this.canSchedule(plan, now, options);
+    return check.ok ? { ...check, reservationId: 1 } : check;
+  },
+  getUsageShare() { return usageShare; }
+});
+
+const makeRateRouter = (config, snapshot, usageShare = []) => (
+  makeRouter(config, { scheduler: makeRateScheduler(snapshot, usageShare) })
+);
+
+const makePlan = ({ timeMs = 0, on = {}, off = {} } = {}) => ({
+  on: { timeMs, count: 0, bytes: 0, ...on },
+  off: { timeMs, count: 0, bytes: 0, ...off }
+});
+
+const makeRouter = (config = {}, options = {}) => {
+  const sent = options.sent ?? [];
+  const mapping = config instanceof MidiMapping ? config : new MidiMapping(config);
+  const router = new MidiEventRouter(mapping);
+  router.scheduler = options.scheduler ?? makeSchedulerStub(sent);
+  router.scheduler.setConfig?.(mapping.config);
+  if (options.output === false) router.scheduler.output = null;
+  if (options.mapEvent) {
+    router.mapping.mapEvent = options.mapEvent;
+  } else if (options.defaultMapEvent) {
+    router.mapping.mapEvent = () => defaultSpec();
+  }
+  return { router, sent, mapping };
+};
+
+const makeArpRouter = (arp, overrides = {}, notes = [60, 64, 67]) => (
+  makeRouter({ limits: { maxEventsPerSecond: 1000 }, ...overrides }, {
+    mapEvent: () => ({
+      notes,
+      note: notes[0],
+      velocity: 64,
+      durationTicks: 1,
+      arp
+    })
+  })
+);
+
+describe('MidiEventRouter 7', function() {
+  it('shouldSend accounts for higher-priority traffic', function() {
+    const bySfx = new Map([
+      [2, { count: 2, bytes: 6, priority: 2 }]
+    ]);
+    const snapshot = makeRateSnapshot({ count: 2, bytes: 6, bySfx }, {}, 100);
+    const usageShare = [{ sfxId: 2, count: 2, bytes: 6, priority: 2, percentCount: 1, percentBytes: 1 }];
+    const { router } = makeRateRouter(
+      { limits: { maxEventsPerSecond: 2, hardMaxEventsPerSecond: 10, maxBytesPerSecond: 100 } },
+      snapshot,
+      usageShare
+    );
+    const plan = makePlan({ on: { count: 1, bytes: 3 } });
+    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, { timeMs: 0 }, plan, 0);
+    expect(ok).to.equal(false);
+    expect(router.getRateReport().reason).to.equal('priority-saturated');
+  });
+
+  it('onEvent applies repeat amount and boost settings', function() {
+    const { router } = makeRouter({
+      enabled: true,
+      timing: { bpmBase: 120 },
+      repeat: { amount: 0.5, target: 'velocity', maxRepeats: 2, windowBeats: 1 },
+      sfx: { '1': { note: 60 } }
+    });
+    const output = { channels: { 1: { sendNoteOn() {}, sendNoteOff() {}, sendPitchBend() {}, sendControlChange() {}, sendAllNotesOff() {}, sendPitchBendRange() {} } } };
+    router.scheduler.setOutput(output);
+    router._shouldSend = () => true;
+    router.scheduler.sendNote = () => {};
+
+    router._onEvent({ sfxId: 1, tick: 1, tps: 50, timeMs: 0 });
+    router._onEvent({ sfxId: 1, tick: 2, tps: 50, timeMs: 20 });
+
+    const { router: boostRouter } = makeRouter({
+      enabled: true,
+      timing: { bpmBase: 120 },
+      repeat: { velocityBoost: 0.2, durationBoost: 0.1, maxRepeats: 2, windowBeats: 1 },
+      sfx: { '1': { note: 60 } }
+    });
+    boostRouter.scheduler.setOutput(output);
+    boostRouter._shouldSend = () => true;
+    boostRouter.scheduler.sendNote = () => {};
+    boostRouter._onEvent({ sfxId: 1, tick: 1, tps: 50, timeMs: 0 });
+  });
+
+  it('onEvent fills defaults when repeat boosts are missing', function() {
+    const { router, sent } = makeRouter({
+      enabled: true,
+      limits: null,
+      timing: null,
+      repeat: null,
+      triggers: null,
+      sfx: { '1': { note: 60, repeat: { maxRepeats: 2, windowBeats: 1 } } }
+    }, { mapEvent: () => ({ note: 60 }) });
+    router.context = { level: { width: 200, height: 100 } };
+    router._nowMs = () => 0;
+
+    router._onEvent({ sfxId: 1, tick: 1, triggerType: 5, timeMs: 0, tps: 50 });
+
+    expect(sent.length).to.equal(1);
+    expect(sent[0].velocity).to.equal(64);
+    expect(sent[0].durationTicks).to.equal(1);
+  });
+
+  it('forwards track output metadata to the scheduler', function() {
+    const sent = [];
+    const metas = [];
+    const scheduler = makeSchedulerStub(sent);
+    scheduler.hasAnyOutput = () => true;
+    scheduler.hasOutput = outputId => outputId === 'track-out';
+    scheduler.sendNote = (spec, meta = {}) => {
+      sent.push({ ...spec });
+      metas.push({ ...meta });
+    };
+    const { router } = makeRouter({
+      enabled: true,
+      sfx: {
+        '1': {
+          note: 60,
+          outputId: 'track-out',
+          trackId: 'track-1',
+          voiceBudget: 5
+        }
+      }
+    }, { scheduler });
+    router._shouldSend = () => true;
+    router._nowMs = () => 0;
+
+    router._onEvent({ sfxId: 1, tick: 1, timeMs: 0, tps: 50 });
+
+    expect(sent).to.have.lengthOf(1);
+    expect(sent[0]).to.include({ outputId: 'track-out', trackId: 'track-1', voiceBudget: 5 });
+    expect(metas[0]).to.include({ outputId: 'track-out', trackId: 'track-1', voiceBudget: 5 });
+  });
+
+  it('dispatches project-lowered clip mappings through the router', function() {
+    let project = createMidiProjectFromMidiConfig({
+      enabled: true,
+      sfx: { '1': { name: 'skill-select', note: 60 } },
+      triggers: {}
+    });
+    project = reduceMidiProject(project, { type: 'clip.add', clip: { id: 'riff', name: 'Riff', lengthSteps: 4 } });
+    project = reduceMidiProject(project, {
+      type: 'clip.step.update',
+      clipId: 'riff',
+      stepIndex: 0,
+      patch: { note: 64, velocity: 90, durationTicks: 5 }
+    });
+    project = reduceMidiProject(project, {
+      type: 'clip.step.update',
+      clipId: 'riff',
+      stepIndex: 1,
+      patch: { note: 67, velocity: 70, durationTicks: 4 }
+    });
+    project = reduceMidiProject(project, {
+      type: 'clip.step.update',
+      clipId: 'riff',
+      stepIndex: 2,
+      patch: { note: 70, tie: true }
+    });
+    project = reduceMidiProject(project, {
+      type: 'clip.step.update',
+      clipId: 'riff',
+      stepIndex: 3,
+      patch: { note: 72, probability: 0 }
+    });
+    project = reduceMidiProject(project, { type: 'source.clip.assign', sourceId: 'sfx-1', clipId: 'riff' });
+
+    const sent = [];
+    const { router } = makeRouter(projectToMidiConfig(project, {}), { sent });
+    router.scheduler.sendNote = spec => sent.push({ ...spec });
+    router._shouldSend = () => true;
+    router._nowMs = () => 0;
+
+    router._onEvent({ sfxId: 1, tick: 1, timeMs: 0, tps: 50 });
+
+    expect(sent.map(spec => spec.note)).to.deep.equal([64, 67]);
+    expect(sent[0]).to.include({ velocity: 90, durationTicks: 5, channel: 1 });
+    expect(sent[0].notes).to.deep.equal([64, 67]);
+  });
+
+  it('covers attach cleanup and tick defaults', function() {
+    const { router: routerA, mapping } = makeRouter({ timing: { bpmBase: 10 } });
+    const routerB = new MidiEventRouter({ timing: { bpmBase: 120 } });
+    expect(routerA.mapping).to.equal(mapping);
+    expect(routerB.mapping).to.be.instanceOf(MidiMapping);
+
+    let onCalls = 0;
+    let offCalls = 0;
+    const onEvent = { on() { onCalls += 1; }, off() { offCalls += 1; } };
+    const bus = { onEvent };
+    routerA.attach(bus, {});
+    routerA.attach(bus, {});
+    routerA.detach();
+    expect(onCalls).to.equal(2);
+    expect(offCalls).to.equal(2);
+
+    routerA.context = { game: { getGameTimer() { return { frameTime: 30, speedFactor: 1 }; } } };
+    expect(routerA._tickMsFromEvent({ tps: 50 })).to.equal(20);
+    expect(routerA._tickMsFromEvent({ frameMs: 40 })).to.equal(40);
+    expect(routerA._tickMsFromEvent({})).to.equal(30);
+    routerA.context = {};
+    expect(routerA._tickMsFromEvent({})).to.equal(60);
+    expect(routerA._getBpm()).to.equal(20);
+  });
+
+  it('covers density and schedule base resets', function() {
+    const { router } = makeRouter({ density: { windowTicks: 4 } });
+    expect(router._densityForEvent({})).to.equal(0);
+    router._lastTickBySfx.set(1, 5);
+    expect(router._densityForEvent({ sfxId: 1, tick: 5 })).to.equal(1);
+    expect(router._densityForEvent({ sfxId: 1, tick: 9 })).to.equal(0);
+    expect(router._densityForEvent({ sfxId: 1, tick: 7 })).to.be.closeTo(0.5, 0.01);
+
+    const originalPerf = globalThis.performance;
+    globalThis.performance = undefined;
+    const now = router._nowMs();
+    globalThis.performance = originalPerf;
+    expect(Number.isFinite(now)).to.equal(true);
+
+    router.scheduler = null;
+    expect(router._resolveScheduleBase(NaN, 0, 0)).to.equal(null);
+
+    router._clockFrameMs = 10;
+    router._clockSpeedFactor = 1;
+    router._nowMs = () => 1000;
+    router._resolveScheduleBase(100, 20, 1);
+
+    let cleared = 0;
+    router.scheduler = { allNotesOff() { cleared += 1; }, clearQueue() { cleared += 1; } };
+    router._resolveScheduleBase(200, 21, 2);
+    expect(cleared).to.equal(2);
+  });
+
+  it('covers repeat target fallbacks and plan entries', function() {
+    const { router, mapping } = makeRouter({ repeat: { maxRepeats: 2, spacingTicks: 2 } });
+    const bpm = 60;
+    expect(router._getRepeatFactor('sfx:1', 0, mapping.config.repeat, bpm)).to.equal(0);
+    expect(router._getRepeatFactor('sfx:1', 1000, mapping.config.repeat, bpm)).to.be.greaterThan(0);
+
+    const spec = { note: 60, velocity: 64, durationTicks: 2, pitchBend: 0.2, releaseVelocity: 64 };
+    const notes = [60, 64];
+    const noAmount = router._applyRepeatTarget(spec, notes, { target: 'velocity', amount: 'bad' }, 1);
+    expect(noAmount.spec).to.equal(spec);
+    const zeroAmount = router._applyRepeatTarget(spec, notes, { target: 'velocity', amount: 0 }, 1);
+    expect(zeroAmount.spec).to.equal(spec);
+
+    router._applyRepeatTarget(spec, notes, { target: 'accent', amount: 0.5 }, 1);
+    router._applyRepeatTarget(spec, notes, { target: 'duration', amount: 0.5 }, 1);
+    router._applyRepeatTarget(spec, notes, { target: 'note', amount: 0.5 }, 1);
+    router._applyRepeatTarget({ ...spec, timbre: 10 }, notes, { target: 'timbre', amount: 0.5 }, 1);
+    router._applyRepeatTarget({ ...spec, pan: 0 }, notes, { target: 'pan', amount: 0.5 }, 1);
+    router._applyRepeatTarget({ ...spec, pitchBend: 0.5 }, notes, { target: 'pitchBend', amount: 0.5 }, 1);
+    router._applyRepeatTarget({ ...spec, pitchBend: NaN }, notes, { target: 'pitchBend', amount: 0.5 }, 1);
+    router._applyRepeatTarget(spec, notes, { target: 'attack', amount: 0.5 }, 1);
+    router._applyRepeatTarget(spec, notes, { target: 'decay', amount: 0.5 }, 1);
+    router._applyRepeatTarget(spec, notes, { target: 'sustain', amount: 0.5 }, 1);
+    router._applyRepeatTarget(spec, notes, { target: 'release', amount: 0.5 }, 1);
+    router._applyRepeatTarget(spec, notes, { target: 'unknown', amount: 0.5 }, 1);
+
+    const { router: mpeRouter } = makeRouter({ mpe: { enabled: true } });
+    mpeRouter.scheduler.tickMs = 10;
+    const planA = mpeRouter._planEntries({ note: 60, durationTicks: NaN }, 1000, 2);
+    const planB = mpeRouter._planEntries({ note: 60, durationTicks: 1 }, 1000, 1);
+    expect(planA.off.count).to.equal(0);
+    expect(planB.off.count).to.equal(2);
+  });
+
+  it('shouldSend enforces hard caps', function() {
+    const snapshot = makeRateSnapshot({ count: 10, bytes: 0 }, {}, 100);
+    const { router } = makeRateRouter(
+      { limits: { maxEventsPerSecond: 10, hardMaxEventsPerSecond: 11, maxBytesPerSecond: 100 } },
+      snapshot
+    );
+    const plan = makePlan({ on: { count: 2 } });
+    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, { timeMs: 0 }, plan, 0);
+    expect(ok).to.equal(false);
+    expect(router.getRateReport().reason).to.equal('count-limit');
+  });
+
+  it('shouldSend throttles on byte budgets and priorities', function() {
+    const bySfx = new Map([
+      [1, { count: 1, bytes: 0, priority: 1 }],
+      [2, { count: 1, bytes: 5, priority: 2 }]
+    ]);
+    const snapshot = makeRateSnapshot({ count: 2, bytes: 5, bySfx }, {}, 5);
+    const usageShare = [
+      { sfxId: 1, count: 1, bytes: 0, priority: 1, percentCount: 0.5, percentBytes: 0 },
+      { sfxId: 2, count: 1, bytes: 5, priority: 2, percentCount: 0.5, percentBytes: 1 }
+    ];
+    const { router } = makeRateRouter(
+      { limits: { maxEventsPerSecond: 2, hardMaxEventsPerSecond: 10, maxBytesPerSecond: 5 } },
+      snapshot,
+      usageShare
+    );
+    const plan = makePlan({ on: { count: 1 }, off: { timeMs: 500 } });
+    const ok = router._shouldSend({ sfxId: 3, priority: 1 }, { timeMs: 0 }, plan, 0);
+    expect(ok).to.equal(false);
+    expect(router.getRateReport().reason).to.equal('byte-limit');
+  });
+
+  it('setMapping accepts MidiMapping instances', function() {
+    const mapping = new MidiMapping({ timing: { bpmBase: 90 } });
+    let configured = null;
+    const { router } = makeRouter({}, {
+      scheduler: { setConfig(cfg) { configured = cfg; } }
+    });
+    router.setMapping(mapping);
+    expect(router.mapping).to.equal(mapping);
+    expect(configured).to.equal(mapping.config);
+  });
+
+  it('returns zero density when window ticks are disabled', function() {
+    const { router } = makeRouter({ density: null });
+    expect(router._densityForEvent({ sfxId: 1, tick: 10 })).to.equal(0);
+  });
+
+  it('resolves arpeggio keys to unknown when sfxId is missing', function() {
+    const { router } = makeRouter();
+    const key = router._resolveArpKey({}, {});
+    expect(key).to.equal('sfx:unknown');
+  });
+
+  it('merges trigger config into sfx overrides on events', function() {
+    let captured = null;
+    const { router, sent } = makeRouter({
+      enabled: true,
+      limits: { maxEventsPerSecond: 1000 },
+      sfx: { '1': { velocity: 10 } },
+      triggers: { '7': { velocity: 20 } }
+    }, {
+      mapEvent: (event, context, density, sfx) => {
+        captured = sfx;
+        return { note: 60, velocity: sfx.velocity, durationTicks: 1 };
+      }
+    });
+    router.scheduler.output = {};
+
+    router._onEvent({ sfxId: 1, tick: 1, tps: 50, triggerType: 7 });
+
+    expect(captured.velocity).to.equal(20);
+    expect(sent.length).to.equal(1);
+  });
+
+  it('returns zero repeat factors when repeats are disabled or invalid', function() {
+    const { router } = makeRouter();
+    const repeatCfg = { maxRepeats: 0, windowBeats: 0 };
+    expect(router._getRepeatFactor('sfx:1', NaN, repeatCfg, 0)).to.equal(0);
+  });
+});
diff --git a/test/midi/midi-event-router.08-midieventrouter.test.js b/test/midi/midi-event-router.08-midieventrouter.test.js
new file mode 100644
index 00000000..85cc9e3d
--- /dev/null
+++ b/test/midi/midi-event-router.08-midieventrouter.test.js
@@ -0,0 +1,366 @@
+import { expect } from 'chai';
+import { withGlobalLemmings } from '../helpers/lemmings.js';
+import { MidiEventRouter } from '../../js/midi/MidiEventRouter.js';
+import { MidiMapping } from '../../js/midi/MidiMapping.js';
+import { EventHandler } from '../../js/util/EventHandler.js';
+import { toMidiFlagTriggerType } from '../../js/midi/MidiFlagTriggers.js';
+
+const defaultSpec = () => ({ note: 60, velocity: 64, durationTicks: 1 });
+
+const sumPlanEntries = (plan, now = 0, windowMs = 1000) => {
+  const entries = Array.isArray(plan?.entries)
+    ? plan.entries
+    : [plan?.on, plan?.off].filter(Boolean);
+  let count = 0;
+  let bytes = 0;
+  for (const entry of entries) {
+    if (!Number.isFinite(entry?.timeMs)) continue;
+    if (entry.timeMs < now - windowMs || entry.timeMs >= now + windowMs) continue;
+    const entryCount = Math.max(0, Math.trunc(entry.count || 0));
+    const entryBytes = Math.max(0, Math.trunc(entry.bytes || entryCount * 3));
+    count += entryCount;
+    bytes += entryBytes;
+  }
+  return { count, bytes };
+};
+
+const planBudgetFromSnapshot = (snapshot, plan, now = 0) => {
+  const proposed = sumPlanEntries(plan, now);
+  return {
+    snapshot,
+    proposed,
+    combined: {
+      count: (snapshot?.past?.count || 0) + (snapshot?.next?.count || 0) + proposed.count,
+      bytes: (snapshot?.past?.bytes || 0) + (snapshot?.next?.bytes || 0) + proposed.bytes
+    }
+  };
+};
+
+const canScheduleFromSnapshot = (snapshot, plan, now = 0, options = {}) => {
+  const maxMessagesPerSecond = Math.max(1, options.maxMessagesPerSecond ?? snapshot?.maxMessagesPerSecond ?? 1000);
+  const maxBytesPerSecond = Math.max(1, options.maxBytesPerSecond ?? snapshot?.maxBytesPerSecond ?? 3906);
+  const budget = planBudgetFromSnapshot(snapshot, plan, now);
+  const overMessages = budget.combined.count > maxMessagesPerSecond;
+  const overBytes = budget.combined.bytes > maxBytesPerSecond;
+  return {
+    ok: !overMessages && !overBytes,
+    reason: overBytes ? 'byte-limit' : (overMessages ? 'count-limit' : null),
+    maxMessagesPerSecond,
+    maxBytesPerSecond,
+    ...budget
+  };
+};
+
+const makeSchedulerStub = (sent) => {
+  const planned = [];
+  const sumWindow = (entries, start, end) => {
+    let count = 0;
+    let bytes = 0;
+    const bySfx = new Map();
+    for (const entry of entries) {
+      if (entry.timeMs < start || entry.timeMs >= end) continue;
+      count += entry.count;
+      bytes += entry.bytes;
+      const curr = bySfx.get(entry.sfxId) || { count: 0, bytes: 0, priority: entry.priority ?? 1 };
+      curr.count += entry.count;
+      curr.bytes += entry.bytes;
+      bySfx.set(entry.sfxId, curr);
+    }
+    return { count, bytes, bySfx };
+  };
+  return {
+    output: {},
+    tickMs: 60,
+    config: {},
+    setTickMs(ms) { this.tickMs = ms; },
+    estimateMessages(spec) {
+      if (!spec || !Number.isFinite(spec.note)) return { messages: 0, bytes: 0 };
+      const mpeEnabled = !!this.config?.mpe?.enabled;
+      let messages = 1;
+      if (mpeEnabled) {
+        messages += 1;
+      } else if (spec.pitchBend != null && Number.isFinite(spec.pitchBend) && spec.pitchBend !== 0) {
+        messages += 1;
+      }
+      if (spec.timbre != null && Number.isFinite(spec.timbre)) messages += 1;
+      if (spec.pan != null && Number.isFinite(spec.pan)) messages += 1;
+      if (spec.durationTicks && spec.durationTicks > 0) {
+        messages += 1;
+        if (mpeEnabled) messages += 1;
+      }
+      return { messages, bytes: 3 * messages };
+    },
+    getRateSnapshot(now = 0) {
+      return {
+        now,
+        past: sumWindow(planned, now - 1000, now),
+        next: sumWindow(planned, now, now + 1000),
+        maxMessagesPerSecond: 1000,
+        maxBytesPerSecond: 3906
+      };
+    },
+    getPlanBudget(plan, now = 0) {
+      return planBudgetFromSnapshot(this.getRateSnapshot(now), plan, now);
+    },
+    canSchedule(plan, now = 0, options = {}) {
+      return canScheduleFromSnapshot(this.getRateSnapshot(now), plan, now, options);
+    },
+    reserve(plan, meta = {}, now = 0, options = {}) {
+      const check = this.canSchedule(plan, now, options);
+      if (!check.ok) return check;
+      const reservationId = planned.length + 1;
+      const entries = Array.isArray(plan?.entries)
+        ? plan.entries
+        : [
+          plan?.on ? { ...plan.on, phase: 'on' } : null,
+          plan?.off ? { ...plan.off, phase: 'off' } : null
+        ].filter(Boolean);
+      for (const entry of entries) {
+        planned.push({
+          timeMs: entry.timeMs,
+          count: Math.max(0, Math.trunc(entry.count || 0)),
+          bytes: Math.max(0, Math.trunc(entry.bytes || 0)),
+          sfxId: meta.sfxId,
+          priority: meta.priority,
+          reservationId,
+          phase: entry.phase ?? null
+        });
+      }
+      return { ...check, ok: true, reservationId };
+    },
+    getUsageShare(window = 'past', now = 0) {
+      const data = window === 'next'
+        ? sumWindow(planned, now, now + 1000)
+        : sumWindow(planned, now - 1000, now);
+      const total = data.count || 0;
+      const totalBytes = data.bytes || 0;
+      const shares = [];
+      for (const [sfxId, entry] of data.bySfx.entries()) {
+        shares.push({
+          sfxId,
+          count: entry.count,
+          bytes: entry.bytes,
+          priority: entry.priority ?? 1,
+          percentCount: total ? entry.count / total : 0,
+          percentBytes: totalBytes ? entry.bytes / totalBytes : 0
+        });
+      }
+      shares.sort((a, b) => b.count - a.count);
+      return shares;
+    },
+    sendNote(spec, meta = {}) {
+      sent.push(spec);
+      if (meta.rateReserved === true) return;
+      const timeMs = spec.timeMs ?? 0;
+      const durationMs = (spec.durationTicks ?? 0) * this.tickMs;
+      planned.push({ timeMs, count: 1, bytes: 3, sfxId: meta.sfxId, priority: meta.priority });
+      if (durationMs > 0) {
+        planned.push({ timeMs: timeMs + durationMs, count: 1, bytes: 3, sfxId: meta.sfxId, priority: meta.priority });
+      }
+    },
+    setConfig(config) { this.config = config || {}; },
+    setOutput() {},
+    dispose() {}
+  };
+};
+
+const makeRateSnapshot = (next = {}, past = {}, maxBytesPerSecond = 1000) => ({
+  next: { count: 0, bytes: 0, bySfx: new Map(), ...next },
+  past: { count: 0, bytes: 0, bySfx: new Map(), ...past },
+  maxBytesPerSecond
+});
+
+const makeRateScheduler = (snapshot, usageShare = []) => ({
+  getRateSnapshot(now = 0) {
+    return typeof snapshot === 'function' ? snapshot(now) : snapshot;
+  },
+  getPlanBudget(plan, now = 0) {
+    return planBudgetFromSnapshot(this.getRateSnapshot(now), plan, now);
+  },
+  canSchedule(plan, now = 0, options = {}) {
+    return canScheduleFromSnapshot(this.getRateSnapshot(now), plan, now, options);
+  },
+  reserve(plan, meta = {}, now = 0, options = {}) {
+    const check = this.canSchedule(plan, now, options);
+    return check.ok ? { ...check, reservationId: 1 } : check;
+  },
+  getUsageShare() { return usageShare; }
+});
+
+const makeRateRouter = (config, snapshot, usageShare = []) => (
+  makeRouter(config, { scheduler: makeRateScheduler(snapshot, usageShare) })
+);
+
+const makePlan = ({ timeMs = 0, on = {}, off = {} } = {}) => ({
+  on: { timeMs, count: 0, bytes: 0, ...on },
+  off: { timeMs, count: 0, bytes: 0, ...off }
+});
+
+const makeRouter = (config = {}, options = {}) => {
+  const sent = options.sent ?? [];
+  const mapping = config instanceof MidiMapping ? config : new MidiMapping(config);
+  const router = new MidiEventRouter(mapping);
+  router.scheduler = options.scheduler ?? makeSchedulerStub(sent);
+  router.scheduler.setConfig?.(mapping.config);
+  if (options.output === false) router.scheduler.output = null;
+  if (options.mapEvent) {
+    router.mapping.mapEvent = options.mapEvent;
+  } else if (options.defaultMapEvent) {
+    router.mapping.mapEvent = () => defaultSpec();
+  }
+  return { router, sent, mapping };
+};
+
+const makeArpRouter = (arp, overrides = {}, notes = [60, 64, 67]) => (
+  makeRouter({ limits: { maxEventsPerSecond: 1000 }, ...overrides }, {
+    mapEvent: () => ({
+      notes,
+      note: notes[0],
+      velocity: 64,
+      durationTicks: 1,
+      arp
+    })
+  })
+);
+
+describe('MidiEventRouter 8', function() {
+  it('applies repeat defaults when velocity and duration are missing', function() {
+    const { router } = makeRouter();
+    const baseSpec = { note: 60 };
+
+    const velocity = router._applyRepeatTarget(
+      baseSpec,
+      [60],
+      { amount: 0.5, target: 'velocity' },
+      1
+    ).spec.velocity;
+    expect(velocity).to.equal(96);
+
+    const duration = router._applyRepeatTarget(
+      baseSpec,
+      [60],
+      { amount: 0.5, target: 'duration' },
+      1
+    ).spec.durationTicks;
+    expect(duration).to.equal(2);
+
+    const release = router._applyRepeatTarget(
+      baseSpec,
+      [60],
+      { amount: 0.5, target: 'release' },
+      1
+    ).spec.releaseVelocity;
+    expect(release).to.equal(96);
+  });
+
+  it('defaults repeat targets when ranges and velocity are missing', function() {
+    const router = new MidiEventRouter(new MidiMapping({
+      position: { timbreRange: null, panRange: null }
+    }));
+    const baseSpec = { note: 60, timbre: 10, pan: 0 };
+    const notes = [60];
+
+    const timbre = router._applyRepeatTarget(
+      baseSpec,
+      notes,
+      { amount: 0.5, target: 'timbre' },
+      1
+    ).spec.timbre;
+    expect(timbre).to.be.within(0, 127);
+    expect(timbre).to.not.equal(10);
+
+    const pan = router._applyRepeatTarget(
+      baseSpec,
+      notes,
+      { amount: 0.5, target: 'pan' },
+      1
+    ).spec.pan;
+    expect(pan).to.be.within(-127, 127);
+
+    const attack = router._applyRepeatTarget(
+      { note: 60 },
+      notes,
+      { amount: 0.5, target: 'attack' },
+      1
+    ).spec.velocity;
+    expect(attack).to.equal(96);
+  });
+
+  it('replaces mappings when setMapping receives a plain object', function() {
+    const { router } = makeRouter();
+    router.setMapping({ enabled: true });
+    expect(router.mapping).to.be.instanceOf(MidiMapping);
+    expect(router.mapping.config.enabled).to.equal(true);
+  });
+
+  it('clamps notes to defaults when no note range is configured', function() {
+    const { router } = makeRouter({ noteRange: null, position: {} });
+    const adjusted = router._applyRepeatTarget(
+      { note: 60 },
+      [200],
+      { amount: 1, target: 'note' },
+      1
+    );
+    expect(adjusted.activeNotes[0]).to.equal(127);
+  });
+
+  it('reuses MidiMapping instances in setMapping', function() {
+    const mapping = new MidiMapping({ enabled: false });
+    const { router } = makeRouter();
+    router.setMapping(mapping);
+    expect(router.mapping).to.equal(mapping);
+  });
+
+  it('uses repeat fallbacks when window beats and max repeats are missing', function() {
+    const { router } = makeRouter();
+    const bpm = router._getBpm();
+    const repeatCfg = { maxRepeats: 1, windowBeats: 1 };
+    router._getRepeatFactor('sfx:1', 0, repeatCfg, bpm);
+    const factor = router._getRepeatFactor('sfx:1', 100, repeatCfg, bpm);
+    expect(factor).to.equal(1);
+
+    const fallback = router._getRepeatFactor('sfx:2', 50, { spacingTicks: 2 }, bpm);
+    expect(fallback).to.equal(0);
+
+    const emptyWindow = router._getRepeatFactor('sfx:3', 60, { maxRepeats: 2 }, bpm);
+    expect(emptyWindow).to.equal(0);
+  });
+
+  it('replaces null mappings with defaults', function() {
+    const { router } = makeRouter();
+    router.setMapping(null);
+    expect(router.mapping).to.be.instanceOf(MidiMapping);
+  });
+
+  it('uses repeat spacing fallbacks and default targets', function() {
+    const { router } = makeRouter({
+      noteRange: { min: null, max: null },
+      position: null
+    });
+    const bpm = router._getBpm();
+    router._getRepeatFactor('sfx:1', 0, { maxRepeats: 2, spacingTicks: 2 }, bpm);
+    const factor = router._getRepeatFactor('sfx:1', 100, { maxRepeats: 2, spacingTicks: 2 }, bpm);
+    expect(factor).to.be.greaterThan(0);
+
+    const baseSpec = { velocity: 50, note: 200 };
+    const adjusted = router._applyRepeatTarget(baseSpec, [200], { amount: 0.5 }, 1);
+    expect(adjusted.spec.velocity).to.be.greaterThan(50);
+    expect(adjusted.activeNotes[0]).to.equal(200);
+
+    const noteAdjusted = router._applyRepeatTarget(
+      baseSpec,
+      [200],
+      { amount: 0.5, target: 'note' },
+      1
+    );
+    expect(noteAdjusted.activeNotes[0]).to.equal(127);
+
+    const timbreAdjusted = router._applyRepeatTarget(
+      { ...baseSpec, timbre: 10 },
+      [60],
+      { amount: 0.5, target: 'timbre' },
+      1
+    );
+    expect(timbreAdjusted.spec.timbre).to.be.within(0, 127);
+  });
+});
diff --git a/test/midi/midi-event-router.test.js b/test/midi/midi-event-router.test.js
deleted file mode 100644
index 48909fc8..00000000
--- a/test/midi/midi-event-router.test.js
+++ /dev/null
@@ -1,1703 +0,0 @@
-import { expect } from 'chai';
-import { withGlobalLemmings } from '../helpers/lemmings.js';
-import { MidiEventRouter } from '../../js/midi/MidiEventRouter.js';
-import { MidiMapping } from '../../js/midi/MidiMapping.js';
-import { EventHandler } from '../../js/util/EventHandler.js';
-
-const defaultSpec = () => ({ note: 60, velocity: 64, durationTicks: 1 });
-
-const makeSchedulerStub = (sent) => {
-  const planned = [];
-  const sumWindow = (entries, start, end) => {
-    let count = 0;
-    let bytes = 0;
-    const bySfx = new Map();
-    for (const entry of entries) {
-      if (entry.timeMs < start || entry.timeMs >= end) continue;
-      count += entry.count;
-      bytes += entry.bytes;
-      const curr = bySfx.get(entry.sfxId) || { count: 0, bytes: 0, priority: entry.priority ?? 1 };
-      curr.count += entry.count;
-      curr.bytes += entry.bytes;
-      bySfx.set(entry.sfxId, curr);
-    }
-    return { count, bytes, bySfx };
-  };
-  return {
-    output: {},
-    tickMs: 60,
-    setTickMs(ms) { this.tickMs = ms; },
-    estimateMessages(spec) {
-      const off = spec.durationTicks > 0 ? 1 : 0;
-      return { messages: 1 + off, bytes: 3 * (1 + off) };
-    },
-    getRateSnapshot(now = 0) {
-      return {
-        now,
-        past: sumWindow(planned, now - 1000, now),
-        next: sumWindow(planned, now, now + 1000),
-        maxBytesPerSecond: 3906
-      };
-    },
-    getUsageShare(window = 'past', now = 0) {
-      const data = window === 'next'
-        ? sumWindow(planned, now, now + 1000)
-        : sumWindow(planned, now - 1000, now);
-      const total = data.count || 0;
-      const totalBytes = data.bytes || 0;
-      const shares = [];
-      for (const [sfxId, entry] of data.bySfx.entries()) {
-        shares.push({
-          sfxId,
-          count: entry.count,
-          bytes: entry.bytes,
-          priority: entry.priority ?? 1,
-          percentCount: total ? entry.count / total : 0,
-          percentBytes: totalBytes ? entry.bytes / totalBytes : 0
-        });
-      }
-      shares.sort((a, b) => b.count - a.count);
-      return shares;
-    },
-    sendNote(spec, meta = {}) {
-      sent.push(spec);
-      const timeMs = spec.timeMs ?? 0;
-      const durationMs = (spec.durationTicks ?? 0) * this.tickMs;
-      planned.push({ timeMs, count: 1, bytes: 3, sfxId: meta.sfxId, priority: meta.priority });
-      if (durationMs > 0) {
-        planned.push({ timeMs: timeMs + durationMs, count: 1, bytes: 3, sfxId: meta.sfxId, priority: meta.priority });
-      }
-    },
-    setConfig() {},
-    setOutput() {},
-    dispose() {}
-  };
-};
-
-const makeRateSnapshot = (next = {}, past = {}, maxBytesPerSecond = 1000) => ({
-  next: { count: 0, bytes: 0, bySfx: new Map(), ...next },
-  past: { count: 0, bytes: 0, bySfx: new Map(), ...past },
-  maxBytesPerSecond
-});
-
-const makeRateScheduler = (snapshot, usageShare = []) => ({
-  getRateSnapshot(now = 0) {
-    return typeof snapshot === 'function' ? snapshot(now) : snapshot;
-  },
-  getUsageShare() { return usageShare; }
-});
-
-const makeRateRouter = (config, snapshot, usageShare = []) => (
-  makeRouter(config, { scheduler: makeRateScheduler(snapshot, usageShare) })
-);
-
-const makePlan = ({ timeMs = 0, on = {}, off = {} } = {}) => ({
-  on: { timeMs, count: 0, bytes: 0, ...on },
-  off: { timeMs, count: 0, bytes: 0, ...off }
-});
-
-const makeRouter = (config = {}, options = {}) => {
-  const sent = options.sent ?? [];
-  const mapping = config instanceof MidiMapping ? config : new MidiMapping(config);
-  const router = new MidiEventRouter(mapping);
-  router.scheduler = options.scheduler ?? makeSchedulerStub(sent);
-  if (options.output === false) router.scheduler.output = null;
-  if (options.mapEvent) {
-    router.mapping.mapEvent = options.mapEvent;
-  } else if (options.defaultMapEvent) {
-    router.mapping.mapEvent = () => defaultSpec();
-  }
-  return { router, sent, mapping };
-};
-
-const makeArpRouter = (arp, overrides = {}, notes = [60, 64, 67]) => (
-  makeRouter({ limits: { maxEventsPerSecond: 1000 }, ...overrides }, {
-    mapEvent: () => ({
-      notes,
-      note: notes[0],
-      velocity: 64,
-      durationTicks: 1,
-      arp
-    })
-  })
-);
-
-describe('MidiEventRouter', function() {
-  it('computes density and tick duration', function() {
-    const densities = [];
-    const { router, sent } = makeRouter({ density: { windowTicks: 10 } }, {
-      mapEvent: (event, context, density) => {
-      densities.push(density);
-      return defaultSpec();
-      }
-    });
-
-    let now = 0;
-    router._nowMs = () => now;
-    router._onEvent({ sfxId: 1, tick: 1, tps: 50 });
-    router._onEvent({ sfxId: 1, tick: 2, tps: 50 });
-
-    expect(router.scheduler.tickMs).to.equal(20);
-    expect(densities[0]).to.equal(0);
-    expect(densities[1]).to.be.closeTo(0.9, 0.01);
-    expect(sent.length).to.equal(2);
-  });
-
-  it('passes reverse flags to the scheduler', function() {
-    const { router, sent } = makeRouter(new MidiMapping(), { defaultMapEvent: true });
-
-    router._onEvent({ sfxId: 1, tick: 1, reverse: true });
-
-    expect(sent[0].reverse).to.equal(true);
-  });
-
-  it('ignores events when disabled or output is missing', function() {
-    const cases = [
-      {
-        name: 'disabled mapping',
-        config: { enabled: false },
-        output: true,
-        events: [{ sfxId: 1, tick: 1 }]
-      },
-      {
-        name: 'missing output',
-        config: { enabled: true },
-        output: false,
-        events: [{ sfxId: 1, tick: 1 }, {}]
-      }
-    ];
-
-    for (const testCase of cases) {
-      const { router, sent } = makeRouter(testCase.config, {
-        defaultMapEvent: true,
-        output: testCase.output
-      });
-      for (const event of testCase.events) {
-        router._onEvent(event);
-      }
-      expect(sent.length, testCase.name).to.equal(0);
-    }
-  });
-
-  it('schedules ahead when event time is behind', function() {
-    const { router, sent } = makeRouter({
-      timing: { scheduleAheadMs: 50 },
-      limits: { maxEventsPerSecond: 1000 }
-    }, { defaultMapEvent: true });
-    router._nowMs = () => 1000;
-    router._resolveScheduleBase = () => 900;
-
-    router._onEvent({ sfxId: 1, tick: 1, timeMs: 0 });
-
-    expect(sent[0].timeMs).to.equal(1050);
-  });
-
-  it('enforces per-tick and per-second limits', function() {
-    const { router, sent } = makeRouter({
-      limits: { maxEventsPerTick: 1, maxEventsPerSecond: 2 }
-    }, { defaultMapEvent: true });
-
-    let now = 0;
-    router._nowMs = () => now;
-
-    router._onEvent({ sfxId: 1, tick: 1 });
-    router._onEvent({ sfxId: 1, tick: 1 });
-    expect(sent.length).to.equal(1);
-
-    router._onEvent({ sfxId: 1, tick: 2 });
-    expect(sent.length).to.equal(1);
-
-    now = 1000;
-    router._onEvent({ sfxId: 1, tick: 3 });
-    expect(sent.length).to.equal(2);
-  });
-
-  it('rejects events when higher-priority bytes saturate the window', function() {
-    const bySfx = new Map([[2, { count: 0, bytes: 9, priority: 2 }]]);
-    const snapshot = makeRateSnapshot(
-      { count: 11, bytes: 9, bySfx },
-      { count: 0, bytes: 0 },
-      9
-    );
-    const { router } = makeRateRouter({
-      limits: { maxEventsPerSecond: 10, hardMaxEventsPerSecond: 100, maxBytesPerSecond: 9 }
-    }, snapshot);
-    const plan = makePlan();
-    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, {}, plan, 0);
-    expect(ok).to.equal(false);
-    expect(router.getRateReport().reason).to.equal('byte-limit');
-  });
-
-  it('allows events when spacing and budgets are available', function() {
-    const snapshot = makeRateSnapshot(
-      { count: 10, bytes: 100 },
-      { count: 0, bytes: 0 },
-      1000
-    );
-    const { router } = makeRateRouter({
-      limits: { maxEventsPerSecond: 10, hardMaxEventsPerSecond: 100, maxBytesPerSecond: 1000 }
-    }, snapshot);
-    const plan = makePlan({ on: { count: 1, bytes: 3 } });
-    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, { timeMs: 0 }, plan, 0);
-    expect(ok).to.equal(true);
-  });
-
-  it('exposes the scheduler rate snapshot', function() {
-    const snapshot = { next: { count: 0, bytes: 0, bySfx: new Map() } };
-    const { router } = makeRouter({}, { scheduler: makeRateScheduler(snapshot) });
-    expect(router.getRateSnapshot()).to.equal(snapshot);
-  });
-
-  it('steps through arpeggio notes across events', function() {
-    const { router, sent } = makeArpRouter({ enabled: true, mode: 'up', length: 3 });
-
-    router._onEvent({ sfxId: 1, tick: 1, tps: 50 });
-    router._onEvent({ sfxId: 1, tick: 2, tps: 50 });
-
-    expect(sent[0].note).to.equal(60);
-    expect(sent[1].note).to.equal(64);
-  });
-
-  it('handles single-note arps without advancing', function() {
-    const { router, sent } = makeArpRouter(
-      { enabled: true, mode: 'up', length: 1 },
-      {},
-      [60]
-    );
-
-    router._onEvent({ sfxId: 1, tick: 1, tps: 50 });
-    router._onEvent({ sfxId: 1, tick: 2, tps: 50 });
-
-    expect(sent.length).to.equal(2);
-    expect(sent[0].note).to.equal(60);
-    expect(sent[1].note).to.equal(60);
-  });
-
-  it('handles downward arps with independent trigger keys', function() {
-    const { router, sent } = makeArpRouter(
-      { enabled: true, mode: 'down', length: 3 },
-      { triggers: { '5': { arp: { independent: true } } } }
-    );
-
-    router._onEvent({ sfxId: 1, tick: 1, tps: 50, triggerType: 5, objectId: 100 });
-    router._onEvent({ sfxId: 1, tick: 2, tps: 50, triggerType: 5, objectId: 100 });
-    router._onEvent({ sfxId: 1, tick: 3, tps: 50, triggerType: 5, objectId: 200 });
-
-    expect(sent[0].note).to.equal(67);
-    expect(sent[1].note).to.equal(64);
-    expect(sent[2].note).to.equal(67);
-  });
-
-  it('reverses direction for updown arps at bounds', function() {
-    const { router, sent } = makeArpRouter({ enabled: true, mode: 'updown', length: 3 });
-
-    router._onEvent({ sfxId: 1, tick: 1, tps: 50 });
-    router._onEvent({ sfxId: 1, tick: 2, tps: 50 });
-    router._onEvent({ sfxId: 1, tick: 3, tps: 50 });
-    router._onEvent({ sfxId: 1, tick: 4, tps: 50 });
-
-    expect(sent.map(entry => entry.note)).to.eql([60, 64, 67, 64]);
-  });
-
-  it('resets arpeggio state when the mode changes', function() {
-    const { router, sent } = makeArpRouter({ enabled: true, mode: 'up', length: 3 });
-
-    router._onEvent({ sfxId: 1, tick: 1, tps: 50 });
-    router.mapping.mapEvent = () => ({
-      notes: [60, 64, 67],
-      note: 60,
-      velocity: 64,
-      durationTicks: 1,
-      arp: { enabled: true, mode: 'down', length: 3 }
-    });
-    router._onEvent({ sfxId: 1, tick: 2, tps: 50 });
-
-    expect(sent.length).to.equal(2);
-  });
-
-  it('resets scheduling when speed changes', function() {
-    const sent = [];
-    const scheduler = makeSchedulerStub(sent);
-    let allOffCalls = 0;
-    scheduler.allNotesOff = () => { allOffCalls += 1; };
-    const { router } = makeRouter({ limits: { maxEventsPerSecond: 1000 } }, {
-      scheduler,
-      mapEvent: () => defaultSpec()
-    });
-    router._nowMs = () => 1000;
-
-    router._onEvent({ sfxId: 1, tick: 1, timeMs: 0, frameMs: 60, speedFactor: 1 });
-    router._onEvent({ sfxId: 1, tick: 2, timeMs: 60, frameMs: 120, speedFactor: 0.5 });
-
-    expect(allOffCalls).to.equal(1);
-  });
-
-  it('scales repeat intensity within a beat window', function() {
-    const { router, sent } = makeRouter({
-      repeat: {
-        maxRepeats: 2,
-        windowBeats: 4,
-        amount: null,
-        velocityBoost: 0.5,
-        durationBoost: 0.5
-      },
-      timing: { bpmBase: 120 },
-      limits: { maxEventsPerSecond: 1000 }
-    }, { mapEvent: () => ({ note: 60, velocity: 40, durationTicks: 2 }) });
-
-    router._nowMs = () => 1000;
-    router._onEvent({ sfxId: 1, tick: 1 });
-    router._onEvent({ sfxId: 1, tick: 2 });
-
-    expect(sent.length).to.equal(2);
-    expect(sent[1].velocity).to.be.greaterThan(sent[0].velocity);
-    expect(sent[1].durationTicks).to.be.greaterThan(sent[0].durationTicks);
-  });
-
-  it('applies repeat targets when amount is configured', function() {
-    const { router, sent } = makeRouter({
-      repeat: {
-        maxRepeats: 4,
-        windowBeats: 1,
-        amount: 1,
-        target: 'note'
-      },
-      timing: { bpmBase: 120 },
-      limits: { maxEventsPerSecond: 1000 }
-    }, { mapEvent: () => ({ note: 60, velocity: 40, durationTicks: 1 }) });
-
-    let now = 0;
-    router._nowMs = () => now;
-    router._onEvent({ sfxId: 1, tick: 1 });
-    now = 100;
-    router._onEvent({ sfxId: 1, tick: 2 });
-
-    expect(sent.length).to.equal(2);
-    expect(sent[1].note).to.be.greaterThan(sent[0].note);
-  });
-
-  it('drops events when byte limits are exceeded', function() {
-    const sent = [];
-    const baseSnapshot = makeRateSnapshot({ count: 1, bytes: 3 }, { count: 0, bytes: 0 }, 3);
-    const usageShare = [{ sfxId: 99, count: 1, bytes: 3, priority: 1, percentCount: 1, percentBytes: 1 }];
-    const scheduler = {
-      ...makeRateScheduler((now = 0) => ({ ...baseSnapshot, now }), usageShare),
-      output: {},
-      tickMs: 60,
-      setTickMs() {},
-      estimateMessages() { return { messages: 1, bytes: 3 }; },
-      sendNote() { sent.push(true); }
-    };
-    const { router } = makeRouter(
-      { limits: { maxEventsPerSecond: 1000, maxBytesPerSecond: 3 } },
-      {
-        scheduler,
-        mapEvent: () => ({ note: 60, velocity: 64, durationTicks: 1 })
-      }
-    );
-
-    router._onEvent({ sfxId: 1, tick: 1, tps: 50 });
-
-    expect(sent.length).to.equal(0);
-    expect(router.getRateReport().reason).to.equal('byte-limit');
-  });
-
-  it('attaches and detaches from sound buses', function() {
-    const { router } = makeRouter();
-    const busA = { onEvent: new EventHandler() };
-    const busB = { onEvent: new EventHandler() };
-    router.attach(busA);
-    expect(busA.onEvent.handlers.size).to.equal(1);
-    router.attach(busB);
-    expect(busA.onEvent.handlers.size).to.equal(0);
-    expect(busB.onEvent.handlers.size).to.equal(1);
-    router.detach();
-    expect(busB.onEvent.handlers.size).to.equal(0);
-  });
-
-  it('accepts plain mapping configs and resets context defaults', function() {
-    let configured = null;
-    const { router } = makeRouter({}, {
-      scheduler: { setConfig(cfg) { configured = cfg; } }
-    });
-    router.setMapping({ timing: { bpmBase: 90 } });
-    expect(router.mapping).to.be.instanceOf(MidiMapping);
-    expect(configured).to.equal(router.mapping.config);
-
-    const bus = { onEvent: new EventHandler() };
-    router.attach(bus, null);
-    expect(router.context).to.eql({});
-    router.detach();
-  });
-
-  it('keeps MidiMapping instances when setting mapping', function() {
-    const mapping = new MidiMapping({ timing: { bpmBase: 100 } });
-    const { router } = makeRouter();
-    router.setMapping(mapping);
-    expect(router.mapping).to.equal(mapping);
-  });
-
-  it('handles repeat factor and repeat targets directly', function() {
-    const { router } = makeRouter({
-      noteRange: { min: 0, max: 127 },
-      position: { timbreRange: { min: 0, max: 100 }, panRange: { min: -50, max: 50 } }
-    });
-    expect(router._getRepeatFactor('x', 10, { enabled: false }, 120)).to.equal(0);
-    expect(router._getRepeatFactor('x', Number.NaN, { maxRepeats: 1, windowBeats: 1 }, 120)).to.equal(0);
-
-    const baseSpec = { note: 60, velocity: 64, durationTicks: 2, timbre: 50, pan: 0, pitchBend: 0.2 };
-    const noteList = [60, 64];
-    const amountCfg = { amount: 1, target: 'timbre' };
-    const timbreResult = router._applyRepeatTarget(baseSpec, noteList, amountCfg, 0.5);
-    expect(timbreResult.spec.timbre).to.not.equal(50);
-
-    const panResult = router._applyRepeatTarget(baseSpec, noteList, { amount: 1, target: 'pan' }, 0.5);
-    expect(panResult.spec.pan).to.not.equal(0);
-
-    const attackResult = router._applyRepeatTarget(baseSpec, noteList, { amount: 1, target: 'attack' }, 0.5);
-    expect(attackResult.spec.velocity).to.not.equal(64);
-
-    const sustainResult = router._applyRepeatTarget(baseSpec, noteList, { amount: 1, target: 'sustain' }, 0.5);
-    expect(sustainResult.spec.durationTicks).to.not.equal(2);
-    const sustainDefault = router._applyRepeatTarget(
-      { ...baseSpec, durationTicks: null },
-      noteList,
-      { amount: 1, target: 'sustain' },
-      0.5
-    );
-    expect(sustainDefault.spec.durationTicks).to.be.at.least(1);
-
-    const noTimbre = router._applyRepeatTarget({ ...baseSpec, timbre: null }, noteList, { amount: 1, target: 'timbre' }, 0.5);
-    expect(noTimbre.spec.timbre).to.equal(null);
-    const noPan = router._applyRepeatTarget({ ...baseSpec, pan: null }, noteList, { amount: 1, target: 'pan' }, 0.5);
-    expect(noPan.spec.pan).to.equal(null);
-  });
-
-  it('reports priority saturation', function() {
-    const bySfx = new Map([[2, { count: 1000, bytes: 10, priority: 2 }]]);
-    const snapshot = makeRateSnapshot({ count: 1000, bytes: 10, bySfx }, {}, 1000);
-    const usageShare = [
-      { sfxId: 2, count: 1000, bytes: 10, priority: 2, percentCount: 1, percentBytes: 1 }
-    ];
-    const { router } = makeRateRouter({
-      timing: { bpmBase: 60 },
-      limits: { maxEventsPerSecond: 10, hardMaxEventsPerSecond: 2000, maxBytesPerSecond: 1000 }
-    }, snapshot, usageShare);
-    const plan = makePlan({ timeMs: 2000 });
-    const saturated = router._shouldSend({ sfxId: 1, priority: 1 }, { timeMs: 0 }, plan, 0);
-    expect(saturated).to.equal(false);
-    expect(router.getRateReport().reason).to.equal('priority-saturated');
-  });
-
-  it('defaults priorities when missing', function() {
-    const snapshot = makeRateSnapshot(
-      { count: 6, bytes: 0, bySfx: new Map([[2, { count: 1, bytes: 0 }]]) },
-      {},
-      1000
-    );
-    const usageShare = [{ sfxId: 2, count: 1, bytes: 0, percentCount: 1, percentBytes: 0 }];
-    const { router } = makeRateRouter({
-      timing: { bpmBase: 60 },
-      limits: { maxEventsPerSecond: 5, hardMaxEventsPerSecond: 10, maxBytesPerSecond: 1000 }
-    }, snapshot, usageShare);
-    const plan = makePlan({ on: { count: 1 }, off: { timeMs: 2000 } });
-    const ok = router._shouldSend({ sfxId: 1 }, {}, plan, 0);
-    expect(ok).to.equal(true);
-  });
-
-  it('reports spacing limits when events arrive too quickly', function() {
-    const snapshot = makeRateSnapshot({ count: 10, bytes: 0 }, {}, 1000);
-    const { router } = makeRateRouter({
-      timing: { bpmBase: 60 },
-      limits: { maxEventsPerSecond: 10, hardMaxEventsPerSecond: 100, maxBytesPerSecond: 1000 }
-    }, snapshot);
-    const plan = makePlan({ on: { count: 1 }, off: { timeMs: 2000 } });
-    router._lastAcceptedBySfx.set(1, 0);
-    const spacing = router._shouldSend({ sfxId: 1, priority: 1 }, {}, plan, 0);
-    expect(spacing).to.equal(false);
-    expect(router.getRateReport().reason).to.equal('spacing');
-  });
-
-  it('accounts for byte-heavy groups in share overage', function() {
-    const bySfx = new Map([
-      [2, { count: 1, bytes: 90, priority: 2 }],
-      [1, { count: 1, bytes: 20, priority: 1 }]
-    ]);
-    const snapshot = makeRateSnapshot({ count: 20, bytes: 0, bySfx }, {}, 100);
-    const usageShare = [{ sfxId: 1, count: 1, bytes: 20, priority: 1, percentCount: 1, percentBytes: 1 }];
-    const { router } = makeRateRouter({
-      timing: { bpmBase: 120 },
-      limits: { maxEventsPerSecond: 10, hardMaxEventsPerSecond: 100, maxBytesPerSecond: 100 }
-    }, snapshot, usageShare);
-    const plan = makePlan({ timeMs: 2000 });
-    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, { timeMs: 1000 }, plan, 0);
-    expect(ok).to.equal(false);
-    expect(router.getRateReport().reason).to.equal('share-throttle');
-  });
-
-  it('resets arp indices when out of range', function() {
-    const { router, sent } = makeArpRouter({ enabled: true, mode: 'up', length: 3 });
-    router._arpStateBySfx.set('sfx:1', { index: 99, dir: 1, mode: 'up', length: 3, seqKey: '60,64,67' });
-    router._onEvent({ sfxId: 1, tick: 1, tps: 50 });
-    expect(sent[0].note).to.equal(60);
-  });
-
-  it('defaults arp length to the note list', function() {
-    const { router, sent } = makeArpRouter(
-      { enabled: true, mode: 'down' },
-      { limits: { maxEventsPerSecond: 10000 } },
-      [60, 64]
-    );
-    router._onEvent({ sfxId: 1, tick: 1, tps: 50 });
-    expect(sent[0].note).to.equal(64);
-  });
-
-  it('builds context from game state and stage when available', function() {
-    const { router, sent } = makeRouter({ limits: { maxEventsPerSecond: 1000 } }, {
-      mapEvent: (event, context) => {
-        expect(context.levelWidth).to.equal(200);
-        expect(context.levelHeight).to.equal(100);
-        expect(context.viewRect.w).to.equal(200);
-        return { note: 60, velocity: 64, durationTicks: 0 };
-      }
-    });
-    router.context = {
-      game: { level: { width: 200, height: 100 } },
-      stage: { getGameViewRect() { return { x: 0, w: 200 }; } }
-    };
-    router._onEvent({ sfxId: 1, tick: 1, tps: 50 });
-    expect(sent.length).to.equal(1);
-  });
-
-  it('resolves arp keys with fallback coordinates', function() {
-    const { router } = makeRouter();
-    const key = router._resolveArpKey(
-      { triggerType: 7, sfxId: 1, x: NaN },
-      { arp: { independent: true } }
-    );
-    expect(key).to.equal('trigger:7:1:x:y');
-  });
-
-  it('emits performance measurements when enabled', function() {
-    const originalPerf = globalThis.performance;
-    let measures = 0;
-    globalThis.performance = { now: () => 0, measure: () => { measures += 1; } };
-    try {
-      withGlobalLemmings({ performanceAPI: true }, () => {
-        const { router } = makeRouter(
-          { limits: { maxEventsPerSecond: 1000 } },
-          { mapEvent: () => ({ note: 60, velocity: 64, durationTicks: 0 }) }
-        );
-        router._onEvent({ sfxId: 1, tick: 1, tps: 50 });
-        expect(measures).to.equal(1);
-      });
-    } finally {
-      globalThis.performance = originalPerf;
-    }
-  });
-
-  it('swallows performance measurement errors', function() {
-    const originalPerf = globalThis.performance;
-    globalThis.performance = { now: () => 0, measure: () => { throw new Error('boom'); } };
-    try {
-      withGlobalLemmings({ performanceAPI: true }, () => {
-        const { router, sent } = makeRouter(
-          { limits: { maxEventsPerSecond: 1000 } },
-          { mapEvent: () => ({ note: 60, velocity: 64, durationTicks: 0 }) }
-        );
-        router._onEvent({ sfxId: 1, tick: 1, tps: 50 });
-        expect(sent.length).to.equal(1);
-      });
-    } finally {
-      globalThis.performance = originalPerf;
-    }
-  });
-
-  it('dispose detaches and disposes scheduler', function() {
-    const { router } = makeRouter();
-    const bus = { onEvent: new EventHandler() };
-    const calls = [];
-    router.scheduler = { dispose() { calls.push('dispose'); } };
-    router.attach(bus);
-    router.dispose();
-    expect(bus.onEvent.handlers.size).to.equal(0);
-    expect(calls).to.eql(['dispose']);
-  });
-
-  it('computes tick duration and density helpers', function() {
-    const { router } = makeRouter({ density: { windowTicks: 4 } });
-    router.context = { game: { getGameTimer() { return { frameTime: 30 }; } } };
-    expect(router._tickMsFromEvent({ tps: 25 })).to.equal(40);
-    expect(router._tickMsFromEvent({ frameMs: 10 })).to.equal(10);
-    expect(router._tickMsFromEvent({})).to.equal(30);
-
-    expect(router._densityForEvent({})).to.equal(0);
-    router._lastTickBySfx.set(1, 5);
-    expect(router._densityForEvent({ sfxId: 1, tick: 5 })).to.equal(1);
-    expect(router._densityForEvent({ sfxId: 1, tick: 9 })).to.equal(0);
-  });
-
-  it('resets schedule base when timing changes', function() {
-    let cleared = 0;
-    const { router } = makeRouter({}, {
-      scheduler: {
-        allNotesOff() { cleared += 1; },
-        clearQueue() { cleared += 1; }
-      }
-    });
-    router._nowMs = () => 1000;
-
-    expect(router._resolveScheduleBase(NaN, 60, 1)).to.equal(null);
-    const base = router._resolveScheduleBase(100, 60, 1);
-    expect(base).to.equal(900);
-
-    router._resolveScheduleBase(120, 30, 1);
-    expect(cleared).to.equal(2);
-  });
-
-  it('computes priorities, bpm, and arp keys', function() {
-    const { router } = makeRouter({
-      limits: { prioritySfx: [5] },
-      timing: { bpmBase: 10 }
-    });
-    router.context = { game: { getGameTimer() { return { speedFactor: 2 }; } } };
-
-    expect(router._getEventPriority({ sfxId: 5 }, {})).to.equal(2);
-    expect(router._getEventPriority({ sfxId: 1 }, { priority: 3 })).to.equal(3);
-    expect(router._getEventPriority({ sfxId: 2 }, {})).to.equal(1);
-    expect(router._getBpm()).to.equal(20);
-
-    const arpCfg = { arp: { independent: true } };
-    expect(router._resolveArpKey({ triggerType: 7, sfxId: 1, objectId: 10 }, arpCfg))
-      .to.equal('trigger:7:1:object:10');
-    expect(router._resolveArpKey({ triggerType: 7, sfxId: 1, lemmingId: 5 }, arpCfg))
-      .to.equal('trigger:7:1:lemming:5');
-    expect(router._resolveArpKey({ triggerType: 7, sfxId: 1, x: 1, y: 2 }, arpCfg))
-      .to.equal('trigger:7:1:1:2');
-    expect(router._resolveArpKey({ sfxId: 2 }, {})).to.equal('sfx:2');
-  });
-
-  it('computes repeat factors and applies multiple targets', function() {
-    const { router } = makeRouter({
-      noteRange: { min: 0, max: 127 },
-      position: { timbreRange: { min: 0, max: 127 }, panRange: { min: -127, max: 127 } }
-    });
-
-    const repeatCfg = { maxRepeats: 2, windowBeats: 1, amount: 0.5, target: 'velocity' };
-    expect(router._getRepeatFactor('sfx:1', 0, repeatCfg, 60)).to.equal(0);
-    expect(router._getRepeatFactor('sfx:1', 500, repeatCfg, 60)).to.equal(0.5);
-
-    const baseSpec = { note: 60, velocity: 64, durationTicks: 4, releaseVelocity: 64 };
-    const notes = [60, 64];
-    const velocity = router._applyRepeatTarget(baseSpec, notes, repeatCfg, 0.5).spec;
-    expect(velocity.velocity).to.be.greaterThan(64);
-
-    const duration = router._applyRepeatTarget(baseSpec, notes, { amount: 0.5, target: 'duration' }, 1).spec;
-    expect(duration.durationTicks).to.be.greaterThan(4);
-
-    const note = router._applyRepeatTarget(baseSpec, notes, { amount: 0.5, target: 'note' }, 1);
-    expect(note.activeNotes[0]).to.be.greaterThan(60);
-
-    const timbre = router._applyRepeatTarget({ ...baseSpec, timbre: 10 }, notes, { amount: 0.5, target: 'timbre' }, 1).spec;
-    expect(timbre.timbre).to.be.greaterThan(10);
-
-    const pan = router._applyRepeatTarget({ ...baseSpec, pan: 0 }, notes, { amount: 0.5, target: 'pan' }, 1).spec;
-    expect(pan.pan).to.not.equal(0);
-
-    const bend = router._applyRepeatTarget({ ...baseSpec, pitchBend: 0.2 }, notes, { amount: 0.5, target: 'pitchBend' }, 1).spec;
-    expect(bend.pitchBend).to.be.greaterThan(0.2);
-
-    const attack = router._applyRepeatTarget(baseSpec, notes, { amount: 0.5, target: 'attack' }, 1).spec;
-    expect(attack.velocity).to.be.greaterThan(64);
-
-    const sustain = router._applyRepeatTarget(baseSpec, notes, { amount: 0.5, target: 'sustain' }, 1).spec;
-    expect(sustain.durationTicks).to.be.greaterThan(4);
-
-    const release = router._applyRepeatTarget(baseSpec, notes, { amount: 0.5, target: 'release' }, 1).spec;
-    expect(release.releaseVelocity).to.be.greaterThan(64);
-
-    const noAmount = router._applyRepeatTarget(baseSpec, notes, { target: 'velocity' }, 1);
-    expect(noAmount.spec.velocity).to.equal(64);
-  });
-
-  it('plans entries with mpe-aware off messages', function() {
-    const { router } = makeRouter({ mpe: { enabled: true } });
-    router.scheduler.tickMs = 10;
-    const plan = router._planEntries({ note: 60, durationTicks: 2 }, 100, 2);
-    expect(plan.on.count).to.equal(4);
-    expect(plan.off.count).to.equal(4);
-    const zero = router._planEntries({ note: 60, durationTicks: 0 }, 100, 1);
-    expect(zero.off.count).to.equal(0);
-  });
-
-  it('drops events when hard count limits are exceeded', function() {
-    const snapshot = makeRateSnapshot({ count: 7, bytes: 0 }, { count: 0, bytes: 0 }, 1000);
-    const { router } = makeRateRouter(
-      { limits: { maxEventsPerSecond: 5, hardMaxEventsPerSecond: 6 } },
-      snapshot
-    );
-    const plan = makePlan();
-    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, {}, plan, 0);
-    expect(ok).to.equal(false);
-    expect(router.getRateReport().reason).to.equal('count-limit');
-  });
-
-  it('drops events when higher priority consumes the budget', function() {
-    const bySfx = new Map([[2, { count: 5, bytes: 0, priority: 2 }]]);
-    const snapshot = makeRateSnapshot({ count: 5, bytes: 0, bySfx }, { count: 0, bytes: 0 }, 1000);
-    const { router } = makeRateRouter(
-      { limits: { maxEventsPerSecond: 5, hardMaxEventsPerSecond: 100, maxBytesPerSecond: 1000 } },
-      snapshot
-    );
-    const plan = makePlan({ on: { count: 1, bytes: 3 } });
-    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, {}, plan, 0);
-    expect(ok).to.equal(false);
-    expect(router.getRateReport().reason).to.equal('priority-saturated');
-  });
-
-  it('drops events when spacing or share budgets are exceeded', function() {
-    const scheduler = makeRateScheduler(
-      makeRateSnapshot({ count: 1, bytes: 0 }, { count: 0, bytes: 0 }, 100)
-    );
-    const { router } = makeRouter({
-      limits: { maxEventsPerSecond: 1, hardMaxEventsPerSecond: 100, maxBytesPerSecond: 100 },
-      timing: { bpmBase: 60 }
-    }, { scheduler });
-    const maxPerSecond = Math.min(
-      Math.max(router.mapping.config?.limits?.maxEventsPerSecond ?? 1000, 1),
-      1000
-    );
-    router._lastAcceptedBySfx.set(1, 0);
-    const spacingPlan = makePlan({ on: { count: maxPerSecond, bytes: 3 } });
-    const spacingOk = router._shouldSend(
-      { sfxId: 1, priority: 1 },
-      { timeMs: 0 },
-      spacingPlan,
-      0
-    );
-    expect(spacingOk).to.equal(false);
-    expect(router.getRateReport().reason).to.equal('spacing');
-
-    const bySfx = new Map([[1, { count: 4, bytes: 0, priority: 1 }]]);
-    router.scheduler.getRateSnapshot = () => (
-      makeRateSnapshot({ count: 4, bytes: 0, bySfx }, { count: 0, bytes: 0 }, 100)
-    );
-    router.scheduler.getUsageShare = () => ([
-      { sfxId: 1, count: 4, bytes: 0, priority: 1, percentCount: 1, percentBytes: 0 }
-    ]);
-    router._lastAcceptedBySfx.delete(1);
-    const sharePlan = makePlan({ timeMs: 2000, on: { count: 1, bytes: 3 } });
-    const shareOk = router._shouldSend(
-      { sfxId: 1, priority: 1 },
-      { timeMs: 2000 },
-      sharePlan,
-      2000
-    );
-    expect(shareOk).to.equal(false);
-    expect(router.getRateReport().reason).to.equal('share-throttle');
-  });
-
-  it('handles rate limits and early exits', function() {
-    const { router, sent } = makeRouter({ enabled: false });
-    router._onEvent({ sfxId: 1, tick: 1 });
-    expect(sent.length).to.equal(0);
-
-    router.setMapping({ enabled: true, limits: { maxEventsPerSecond: 1000 } });
-    router.scheduler.output = null;
-    router._onEvent({ sfxId: 1, tick: 1 });
-    expect(sent.length).to.equal(0);
-
-    router.scheduler.output = {};
-    router.mapping.mapEvent = () => null;
-    router._onEvent({ sfxId: 1, tick: 1 });
-    expect(sent.length).to.equal(0);
-
-    router.mapping.mapEvent = () => ({ note: 1, velocity: 1, durationTicks: 1 });
-    router.setMapping({ enabled: true, limits: { maxEventsPerSecond: 1 } });
-    router._onEvent({ sfxId: 1, tick: 1 });
-    router._onEvent({ sfxId: 1, tick: 2 });
-    expect(sent.length).to.equal(0);
-  });
-
-  it('forwards output updates and handles unknown repeat targets', function() {
-    let seen = null;
-    const { router } = makeRouter({}, { scheduler: { setOutput(output) { seen = output; } } });
-    const output = { channels: {} };
-    router.setOutput(output);
-    expect(seen).to.equal(output);
-
-    const spec = { note: 60, velocity: 64, durationTicks: 2 };
-    const result = router._applyRepeatTarget(
-      spec,
-      [60],
-      { amount: 0.5, target: 'unknown-target' },
-      1
-    );
-    expect(result.spec).to.deep.equal(spec);
-  });
-
-  it('forwards usage share queries to the scheduler', function() {
-    const { router } = makeRouter({}, { scheduler: { getUsageShare: window => [{ window }] } });
-    const share = router.getUsageShare('next');
-    expect(share[0].window).to.equal('next');
-  });
-
-  it('covers tick defaults and density edge cases', function() {
-    const { router, mapping } = makeRouter({ density: { windowTicks: 0 } });
-    router.context = {};
-
-    expect(router._tickMsFromEvent({})).to.equal(60);
-    expect(router._densityForEvent({ sfxId: 1, tick: 1 })).to.equal(0);
-
-    router.mapping.config.density.windowTicks = 5;
-    expect(router._densityForEvent({ sfxId: null, tick: 1 })).to.equal(0);
-    router._lastTickBySfx.set(1, 5);
-    expect(router._densityForEvent({ sfxId: 1, tick: 5 })).to.equal(1);
-    expect(router._densityForEvent({ sfxId: 1, tick: 20 })).to.equal(0);
-  });
-
-  it('falls back to Date.now when performance is missing', function() {
-    const { router } = makeRouter();
-    const originalPerf = globalThis.performance;
-    const originalDateNow = Date.now;
-    Date.now = () => 123;
-    globalThis.performance = undefined;
-    try {
-      expect(router._nowMs()).to.equal(123);
-    } finally {
-      Date.now = originalDateNow;
-      globalThis.performance = originalPerf;
-    }
-  });
-
-  it('reuses schedule base and respects spacing tick repeats', function() {
-    const { router, mapping } = makeRouter({ repeat: { maxRepeats: 2, spacingTicks: 2 } });
-    router._nowMs = () => 1000;
-    const base = router._resolveScheduleBase(100, 60, 1);
-    expect(base).to.equal(900);
-    const again = router._resolveScheduleBase(200, 60, 1);
-    expect(again).to.equal(base);
-
-    const factorA = router._getRepeatFactor('sfx:1', 1000, mapping.config.repeat, 60);
-    const factorB = router._getRepeatFactor('sfx:1', 1100, mapping.config.repeat, 60);
-    expect(factorA).to.equal(0);
-    expect(factorB).to.be.greaterThan(0);
-  });
-
-  it('returns repeat targets unchanged for missing numeric fields', function() {
-    const { router } = makeRouter();
-    const base = { note: 60, velocity: 64, durationTicks: 1 };
-    const none = router._applyRepeatTarget(base, [60], { amount: 1, target: 'timbre' }, 1);
-    expect(none.spec.timbre).to.equal(undefined);
-    const pan = router._applyRepeatTarget(base, [60], { amount: 1, target: 'pan' }, 1);
-    expect(pan.spec.pan).to.equal(undefined);
-    const bend = router._applyRepeatTarget(base, [60], { amount: 1, target: 'pitchBend' }, 1);
-    expect(bend.spec.pitchBend).to.equal(undefined);
-  });
-
-  it('drops events when available bytes are exhausted', function() {
-    const bySfx = new Map([[2, { count: 1, bytes: 100, priority: 2 }]]);
-    const snapshot = makeRateSnapshot({ count: 6, bytes: 100, bySfx }, { count: 0, bytes: 0 }, 100);
-    const { router } = makeRateRouter(
-      { limits: { maxEventsPerSecond: 5, hardMaxEventsPerSecond: 10, maxBytesPerSecond: 100 } },
-      snapshot
-    );
-    const plan = makePlan();
-    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, {}, plan, 0);
-    expect(ok).to.equal(false);
-    expect(router.getRateReport().reason).to.equal('byte-limit');
-  });
-
-  it('handles share reports without current entries', function() {
-    const bySfx = new Map([[2, { count: 5, bytes: 0, priority: 1 }]]);
-    const snapshot = makeRateSnapshot({ count: 6, bytes: 0, bySfx }, { count: 0, bytes: 0 }, 100);
-    const usageShare = [{ sfxId: 2, count: 5, bytes: 0, priority: 1, percentCount: 1, percentBytes: 0 }];
-    const { router } = makeRateRouter(
-      { limits: { maxEventsPerSecond: 5, hardMaxEventsPerSecond: 10, maxBytesPerSecond: 100 } },
-      snapshot,
-      usageShare
-    );
-    const plan = makePlan({ on: { count: 1, bytes: 3 }, off: { timeMs: 2000 } });
-    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, { timeMs: 0 }, plan, 0);
-    expect(ok).to.equal(true);
-  });
-
-  it('sends notes when ticks are missing and notes are empty', function() {
-    const { router, sent } = makeRouter(
-      { limits: { maxEventsPerSecond: 1000 } },
-      { mapEvent: () => ({ note: 60, notes: [], velocity: 64, durationTicks: 0 }) }
-    );
-    router._nowMs = () => 10;
-
-    router._onEvent({ sfxId: 1, timeMs: NaN });
-    expect(sent.length).to.equal(1);
-  });
-
-  it('constructs mapping from plain config objects', function() {
-    const router = new MidiEventRouter({ enabled: false });
-    expect(router.mapping).to.be.instanceOf(MidiMapping);
-    const routerWithMapping = new MidiEventRouter(new MidiMapping());
-    expect(routerWithMapping.mapping).to.be.instanceOf(MidiMapping);
-  });
-
-  it('attach removes existing listeners when re-attaching', function() {
-    let offCalls = 0;
-    const busA = { onEvent: { on() {}, off() { offCalls += 1; } } };
-    const busB = { onEvent: { on() {}, off() {} } };
-    const { router } = makeRouter();
-    router.attach(busA);
-    router.attach(busB);
-    expect(offCalls).to.equal(1);
-  });
-
-  it('tickMsFromEvent falls back to defaults without timers', function() {
-    const { router } = makeRouter();
-    router.context = {};
-    expect(router._tickMsFromEvent({})).to.equal(60);
-  });
-
-  it('nowMs uses performance when available', function() {
-    const { router } = makeRouter();
-    const originalPerf = globalThis.performance;
-    globalThis.performance = { now: () => 456 };
-    try {
-      expect(router._nowMs()).to.equal(456);
-    } finally {
-      globalThis.performance = originalPerf;
-    }
-  });
-
-  it('resets schedule base when speed changes without frame changes', function() {
-    let cleared = 0;
-    const { router } = makeRouter({}, {
-      scheduler: {
-        allNotesOff() { cleared += 1; },
-        clearQueue() { cleared += 1; }
-      }
-    });
-    router._nowMs = () => 1000;
-    router._resolveScheduleBase(100, 60, 1);
-    router._resolveScheduleBase(120, 60, 2);
-    expect(cleared).to.equal(2);
-    router._resolveScheduleBase(140, NaN, NaN);
-  });
-
-  it('getBpm returns scaled values above the minimum', function() {
-    const { router } = makeRouter({ timing: { bpmBase: 120 } });
-    router.context = { game: { getGameTimer() { return { speedFactor: 2 }; } } };
-    expect(router._getBpm()).to.equal(240);
-  });
-
-  it('resolveArpKey falls back when independence is disabled', function() {
-    const { router } = makeRouter();
-    expect(router._resolveArpKey({ triggerType: 3, sfxId: 2 }, { arp: { independent: false } }))
-      .to.equal('sfx:2');
-  });
-
-  it('getRepeatFactor returns zero for invalid repeat windows', function() {
-    const { router } = makeRouter();
-    expect(router._getRepeatFactor('sfx:1', 10, { maxRepeats: 0, windowBeats: 1 }, 120)).to.equal(0);
-    expect(router._getRepeatFactor('sfx:1', NaN, { maxRepeats: 2, windowBeats: 1 }, 120)).to.equal(0);
-    expect(router._getRepeatFactor('sfx:1', 10, { maxRepeats: 2, windowBeats: 1 }, 0)).to.equal(0);
-  });
-
-  it('applyRepeatTarget handles accent targets and zero factors', function() {
-    const { router } = makeRouter();
-    const baseSpec = { note: 60, velocity: 64, durationTicks: 2, releaseVelocity: 64 };
-    const unchanged = router._applyRepeatTarget(baseSpec, [60], { amount: 1, target: 'velocity' }, 0);
-    expect(unchanged.spec.velocity).to.equal(64);
-    const accent = router._applyRepeatTarget(baseSpec, [60], { amount: 0.5, target: 'accent' }, 1);
-    expect(accent.spec.velocity).to.be.greaterThan(64);
-  });
-
-  it('planEntries uses default off messages without MPE', function() {
-    const { router } = makeRouter({ mpe: { enabled: false } });
-    router.scheduler.tickMs = 10;
-    const plan = router._planEntries({ note: 60, durationTicks: 1 }, 1000, 1);
-    expect(plan.off.count).to.equal(1);
-  });
-
-  it('shouldSend ignores plans outside the next window', function() {
-    const snapshot = makeRateSnapshot();
-    const { router } = makeRateRouter(
-      { limits: { maxEventsPerSecond: 10, maxBytesPerSecond: 1000 } },
-      snapshot
-    );
-    const plan = makePlan({ on: { count: 1, bytes: 3 }, off: { timeMs: 5000, count: 1, bytes: 3 } });
-    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, {}, plan, 1000);
-    expect(ok).to.equal(true);
-  });
-
-  it('shouldSend accounts for higher and same priority entries', function() {
-    const bySfx = new Map([
-      [1, { count: 2, bytes: 6, priority: 1 }],
-      [2, { count: 2, bytes: 6, priority: 2 }]
-    ]);
-    const snapshot = makeRateSnapshot({ count: 4, bytes: 12, bySfx }, {}, 1000);
-    const { router } = makeRateRouter(
-      { limits: { maxEventsPerSecond: 10, maxBytesPerSecond: 1000 } },
-      snapshot
-    );
-    const plan = makePlan({ timeMs: 1000, on: { count: 1, bytes: 3 }, off: { timeMs: 1000 } });
-    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, { timeMs: 1000 }, plan, 1000);
-    expect(ok).to.equal(true);
-  });
-
-  it('tickMsFromEvent uses frameMs and timer fallbacks', function() {
-    const { router } = makeRouter();
-    expect(router._tickMsFromEvent({ frameMs: 33 })).to.equal(33);
-    router.context = { game: { getGameTimer() { return { frameTime: 42 }; } } };
-    expect(router._tickMsFromEvent({})).to.equal(42);
-  });
-
-  it('density handles zero and window limits', function() {
-    const { router } = makeRouter({ density: { windowTicks: 4 } });
-    router._lastTickBySfx.set(1, 10);
-    expect(router._densityForEvent({ sfxId: 1, tick: 10 })).to.equal(1);
-    expect(router._densityForEvent({ sfxId: 1, tick: 12 })).to.be.closeTo(0.5, 0.01);
-    expect(router._densityForEvent({ sfxId: 1, tick: 20 })).to.equal(0);
-    expect(router._densityForEvent({ sfxId: 2, tick: 1 })).to.equal(0);
-  });
-
-  it('resolveScheduleBase resets on frame or speed changes', function() {
-    const { router } = makeRouter();
-    router.scheduler = {};
-    router._nowMs = () => 1000;
-    expect(router._resolveScheduleBase(NaN, 0, 0)).to.equal(null);
-    router._resolveScheduleBase(100, 60, 1);
-
-    router.scheduler = { allNotesOff() { this.off = true; }, clearQueue() { this.clear = true; } };
-    router._resolveScheduleBase(110, 120, 1);
-    expect(router.scheduler.off).to.equal(true);
-    router._resolveScheduleBase(120, 120, 2);
-    expect(router.scheduler.clear).to.equal(true);
-    router._resolveScheduleBase(140, NaN, NaN);
-  });
-
-  it('getEventPriority uses sfx priority and priority lists', function() {
-    const { router } = makeRouter({ limits: { prioritySfx: [5] } });
-    expect(router._getEventPriority({ sfxId: 1 }, { priority: 3 })).to.equal(3);
-    expect(router._getEventPriority({ sfxId: 5 }, {})).to.equal(2);
-  });
-
-  it('resolveArpKey builds independent trigger keys', function() {
-    const { router } = makeRouter();
-    const sfx = { arp: { independent: true } };
-    expect(router._resolveArpKey({ triggerType: 1, sfxId: 2, objectId: 3 }, sfx))
-      .to.equal('trigger:1:2:object:3');
-    expect(router._resolveArpKey({ triggerType: 1, sfxId: 2, lemmingId: 4 }, sfx))
-      .to.equal('trigger:1:2:lemming:4');
-    expect(router._resolveArpKey({ triggerType: 1, sfxId: 2, x: 3, y: 4 }, sfx))
-      .to.equal('trigger:1:2:3:4');
-  });
-
-  it('getRepeatFactor uses spacingTicks and history', function() {
-    const { router } = makeRouter();
-    const repeatCfg = { maxRepeats: 2, spacingTicks: 1 };
-    const bpm = 120;
-    const first = router._getRepeatFactor('sfx:1', 0, repeatCfg, bpm);
-    const second = router._getRepeatFactor('sfx:1', 100, repeatCfg, bpm);
-    expect(first).to.equal(0);
-    expect(second).to.be.greaterThan(0);
-  });
-
-  it('applyRepeatTarget covers additional targets', function() {
-    const { router } = makeRouter({
-      noteRange: { min: 0, max: 127 },
-      position: { timbreRange: { min: 0, max: 100 }, panRange: { min: -50, max: 50 } }
-    });
-    const baseSpec = { note: 60, velocity: 64, durationTicks: 4, timbre: 10, pan: 5, pitchBend: 0.2, releaseVelocity: 30 };
-    const baseNotes = [60, 64];
-
-    const duration = router._applyRepeatTarget(baseSpec, baseNotes, { amount: 1, target: 'duration' }, 1);
-    expect(duration.spec.durationTicks).to.be.greaterThan(4);
-    const note = router._applyRepeatTarget(baseSpec, baseNotes, { amount: 1, target: 'note' }, 1);
-    expect(note.activeNotes[0]).to.not.equal(60);
-    const timbre = router._applyRepeatTarget({ ...baseSpec, timbre: 10 }, baseNotes, { amount: 1, target: 'timbre' }, 1);
-    expect(timbre.spec.timbre).to.be.greaterThan(10);
-    const pan = router._applyRepeatTarget({ ...baseSpec, pan: 5 }, baseNotes, { amount: 1, target: 'pan' }, 1);
-    expect(pan.spec.pan).to.be.a('number');
-    const bend = router._applyRepeatTarget({ ...baseSpec, pitchBend: 0.5 }, baseNotes, { amount: 1, target: 'pitchBend' }, 1);
-    expect(bend.spec.pitchBend).to.be.a('number');
-    const attack = router._applyRepeatTarget(baseSpec, baseNotes, { amount: 1, target: 'attack' }, 1);
-    expect(attack.spec.velocity).to.be.greaterThan(64);
-    const sustain = router._applyRepeatTarget(baseSpec, baseNotes, { amount: 1, target: 'sustain' }, 1);
-    expect(sustain.spec.durationTicks).to.be.greaterThan(4);
-    const release = router._applyRepeatTarget(baseSpec, baseNotes, { amount: 1, target: 'release' }, 1);
-    expect(release.spec.releaseVelocity).to.be.greaterThan(0);
-
-    const ignored = router._applyRepeatTarget({ ...baseSpec, timbre: null }, baseNotes, { amount: 1, target: 'timbre' }, 1);
-    expect(ignored.spec.timbre).to.equal(null);
-    const unchanged = router._applyRepeatTarget(baseSpec, baseNotes, { amount: 0, target: 'velocity' }, 1);
-    expect(unchanged.spec).to.equal(baseSpec);
-  });
-
-  it('planEntries accounts for duration and MPE off messages', function() {
-    const { router } = makeRouter({ mpe: { enabled: true } });
-    router.scheduler.tickMs = 10;
-    const plan = router._planEntries({ note: 60, durationTicks: 2 }, 1000, 2);
-    expect(plan.off.count).to.equal(4);
-    const zero = router._planEntries({ note: 60, durationTicks: NaN }, 1000, 1);
-    expect(zero.off.count).to.equal(0);
-  });
-
-  it('shouldSend rejects when count exceeds the hard max', function() {
-    const snapshot = makeRateSnapshot({ count: 6, bytes: 0 }, {}, 1000);
-    const { router } = makeRateRouter(
-      { limits: { maxEventsPerSecond: 5, hardMaxEventsPerSecond: 6, maxBytesPerSecond: 1000 } },
-      snapshot
-    );
-    const plan = makePlan({ on: { count: 1, bytes: 3 }, off: { count: 1, bytes: 3 } });
-    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, { timeMs: 0 }, plan, 0);
-    expect(ok).to.equal(false);
-    expect(router.getRateReport().reason).to.equal('count-limit');
-  });
-
-  it('shouldSend handles priority saturation', function() {
-    const bySfx = new Map([[2, { count: 5, bytes: 10, priority: 2 }]]);
-    const snapshot = makeRateSnapshot({ count: 5, bytes: 10, bySfx }, {}, 100);
-    const usageShare = [{ sfxId: 2, count: 5, bytes: 10, priority: 2, percentCount: 1, percentBytes: 1 }];
-    const { router } = makeRateRouter(
-      { limits: { maxEventsPerSecond: 5, hardMaxEventsPerSecond: 10, maxBytesPerSecond: 100 } },
-      snapshot,
-      usageShare
-    );
-    const plan = makePlan({ on: { count: 1, bytes: 3 } });
-    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, { timeMs: 0 }, plan, 0);
-    expect(ok).to.equal(false);
-    expect(router.getRateReport().reason).to.equal('priority-saturated');
-  });
-
-  it('shouldSend rejects when available bytes are exhausted', function() {
-    const bySfx = new Map([[2, { count: 1, bytes: 10, priority: 2 }]]);
-    const snapshot = makeRateSnapshot({ count: 1, bytes: 10, bySfx }, {}, 10);
-    const usageShare = [{ sfxId: 2, count: 1, bytes: 10, priority: 2, percentCount: 1, percentBytes: 1 }];
-    const { router } = makeRateRouter(
-      { limits: { maxEventsPerSecond: 5, hardMaxEventsPerSecond: 10, maxBytesPerSecond: 10 } },
-      snapshot,
-      usageShare
-    );
-    const plan = makePlan({ on: { count: 1, bytes: 3 } });
-    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, { timeMs: 0 }, plan, 0);
-    expect(ok).to.equal(false);
-    expect(router.getRateReport().reason).to.equal('byte-limit');
-  });
-
-  it('shouldSend rejects when spacing is violated', function() {
-    const bySfx = new Map([[1, { count: 1, bytes: 3, priority: 1 }]]);
-    const snapshot = makeRateSnapshot({ count: 1, bytes: 3, bySfx }, {}, 1000);
-    const usageShare = [{ sfxId: 1, count: 1, bytes: 3, priority: 1, percentCount: 1, percentBytes: 0 }];
-    const { router } = makeRateRouter(
-      { limits: { maxEventsPerSecond: 1, hardMaxEventsPerSecond: 10, maxBytesPerSecond: 1000 } },
-      snapshot,
-      usageShare
-    );
-    router._lastAcceptedBySfx.set(1, 1000);
-    const plan = makePlan({ timeMs: 1000, on: { count: 1, bytes: 3 }, off: { timeMs: 1000 } });
-    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, { timeMs: 1000 }, plan, 1000);
-    expect(ok).to.equal(false);
-    expect(router.getRateReport().reason).to.equal('spacing');
-  });
-
-  it('shouldSend rejects when share budgets are exceeded', function() {
-    const bySfx = new Map([[1, { count: 2, bytes: 6, priority: 1 }]]);
-    const snapshot = makeRateSnapshot({ count: 2, bytes: 6, bySfx }, {}, 100);
-    const usageShare = [{ sfxId: 1, count: 2, bytes: 6, priority: 1, percentCount: 1, percentBytes: 0 }];
-    const { router } = makeRateRouter(
-      { limits: { maxEventsPerSecond: 2, hardMaxEventsPerSecond: 10, maxBytesPerSecond: 100 } },
-      snapshot,
-      usageShare
-    );
-    const plan = makePlan({ on: { count: 1, bytes: 3 } });
-    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, { timeMs: 0 }, plan, 0);
-    expect(ok).to.equal(false);
-    expect(router.getRateReport().reason).to.equal('share-throttle');
-  });
-
-  it('covers setup helpers and schedule resets', function() {
-    const { router, mapping } = makeRouter({ timing: { bpmBase: 100 } });
-    expect(router.mapping).to.equal(mapping);
-
-    const routerAlt = new MidiEventRouter({ timing: { bpmBase: 90 } });
-    expect(routerAlt.mapping).to.be.instanceof(MidiMapping);
-
-    let offCalls = 0;
-    const busA = { onEvent: { on() {}, off() { offCalls += 1; } } };
-    const busB = { onEvent: { on() {}, off() { offCalls += 1; } } };
-    router.attach(busA);
-    router.attach(busB);
-    router.detach();
-    expect(offCalls).to.be.greaterThan(0);
-
-    router.context = { game: { getGameTimer() { return { frameTime: 33, speedFactor: 1.5 }; } } };
-    expect(router._tickMsFromEvent({ tps: 50 })).to.equal(20);
-    expect(router._tickMsFromEvent({ frameMs: 40 })).to.equal(40);
-    expect(router._tickMsFromEvent({})).to.equal(33);
-
-    router.mapping.config.density = { windowTicks: 4 };
-    router._lastTickBySfx.set(1, 10);
-    expect(router._densityForEvent({ sfxId: 1, tick: 10 })).to.equal(1);
-    expect(router._densityForEvent({ sfxId: 1, tick: 14 })).to.equal(0);
-    expect(router._densityForEvent({ sfxId: 1, tick: 12 })).to.be.greaterThan(0);
-
-    router.scheduler = {
-      allNotesOff() { this.called = true; },
-      clearQueue() { this.cleared = true; }
-    };
-    router._clockFrameMs = 60;
-    router._clockSpeedFactor = 1;
-    const base = router._resolveScheduleBase(100, 30, 0.5);
-    expect(base).to.be.a('number');
-    expect(router._resolveScheduleBase(NaN, 30, 0.5)).to.equal(null);
-  });
-
-  it('covers priority, bpm, and arp keys', function() {
-    const { router } = makeRouter({ limits: { prioritySfx: [2] }, timing: { bpmBase: 120 } });
-    router.context = { game: { getGameTimer() { return { speedFactor: 2 }; } } };
-    expect(router._getEventPriority({ sfxId: 2 }, {})).to.equal(2);
-    expect(router._getEventPriority({ sfxId: 3 }, { priority: 5 })).to.equal(5);
-    expect(router._getEventPriority({ sfxId: 3 }, {})).to.equal(1);
-    expect(router._getBpm()).to.equal(240);
-
-    const sfx = { arp: { independent: true } };
-    expect(router._resolveArpKey({ triggerType: 1, sfxId: 2, objectId: 9 }, sfx)).to.include('object:9');
-    expect(router._resolveArpKey({ triggerType: 1, sfxId: 2, lemmingId: 3 }, sfx)).to.include('lemming:3');
-    expect(router._resolveArpKey({ triggerType: 1, sfxId: 2, x: 1, y: 2 }, sfx)).to.include('trigger:1:2');
-    expect(router._resolveArpKey({ sfxId: 2 }, {})).to.include('sfx:2');
-  });
-
-  it('covers repeat factors and targets', function() {
-    const { router } = makeRouter({
-      noteRange: { min: 0, max: 127 },
-      position: { timbreRange: { min: 0, max: 127 }, panRange: { min: -127, max: 127 } }
-    });
-    const repeatCfg = { maxRepeats: 2, windowBeats: 1 };
-    expect(router._getRepeatFactor('a', NaN, repeatCfg, 120)).to.equal(0);
-    router._getRepeatFactor('a', 0, repeatCfg, 120);
-    const factor = router._getRepeatFactor('a', 100, repeatCfg, 120);
-    expect(factor).to.be.greaterThan(0);
-
-    const spec = { note: 60, velocity: 64, durationTicks: 4, timbre: 10, pan: 0, pitchBend: 0.1, releaseVelocity: 50 };
-    const notes = [60, 64];
-    expect(router._applyRepeatTarget(spec, notes, { target: 'velocity' }, 0).spec).to.equal(spec);
-    expect(router._applyRepeatTarget(spec, notes, { target: 'velocity' }, 0.5).spec).to.equal(spec);
-    expect(router._applyRepeatTarget(spec, notes, { amount: 0, target: 'velocity' }, 1).spec).to.equal(spec);
-
-    router._applyRepeatTarget(spec, notes, { amount: 1, target: 'velocity' }, 0.5);
-    router._applyRepeatTarget(spec, notes, { amount: 1, target: 'duration' }, 0.5);
-    router._applyRepeatTarget(spec, notes, { amount: 1, target: 'note' }, 0.5);
-    router._applyRepeatTarget({ ...spec, timbre: NaN }, notes, { amount: 1, target: 'timbre' }, 0.5);
-    router._applyRepeatTarget(spec, notes, { amount: 1, target: 'timbre' }, 0.5);
-    router._applyRepeatTarget({ ...spec, pan: NaN }, notes, { amount: 1, target: 'pan' }, 0.5);
-    router._applyRepeatTarget(spec, notes, { amount: 1, target: 'pan' }, 0.5);
-    router._applyRepeatTarget({ ...spec, pitchBend: NaN }, notes, { amount: 1, target: 'pitchBend' }, 0.5);
-    router._applyRepeatTarget(spec, notes, { amount: 1, target: 'pitchBend' }, 0.5);
-    router._applyRepeatTarget(spec, notes, { amount: 1, target: 'attack' }, 0.5);
-    router._applyRepeatTarget(spec, notes, { amount: 1, target: 'decay' }, 0.5);
-    router._applyRepeatTarget(spec, notes, { amount: 1, target: 'sustain' }, 0.5);
-    router._applyRepeatTarget(spec, notes, { amount: 1, target: 'release' }, 0.5);
-    router._applyRepeatTarget(spec, notes, { amount: 1, target: 'unknown' }, 0.5);
-  });
-
-  it('plans entries and handles shouldSend under limits', function() {
-    const snapshot = makeRateSnapshot();
-    const scheduler = {
-      ...makeRateScheduler(snapshot),
-      tickMs: 50,
-      estimateMessages() { return { messages: 2, bytes: 6 }; }
-    };
-    const { router } = makeRouter(
-      { limits: { maxEventsPerSecond: 10, hardMaxEventsPerSecond: 10, maxBytesPerSecond: 1000 } },
-      { scheduler }
-    );
-    const plan = router._planEntries({ durationTicks: NaN }, -2000, 1);
-    expect(plan.off.count).to.equal(0);
-    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, { timeMs: -2000 }, plan, 0);
-    expect(ok).to.equal(true);
-  });
-
-  it('shouldSend rejects when hard max is exceeded', function() {
-    const bySfx = new Map();
-    const snapshot = makeRateSnapshot({ count: 2, bytes: 0, bySfx }, {}, 1000);
-    const { router } = makeRateRouter(
-      { limits: { maxEventsPerSecond: 1, hardMaxEventsPerSecond: 1, maxBytesPerSecond: 1000 } },
-      snapshot
-    );
-    const plan = makePlan();
-    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, { timeMs: 0 }, plan, 0);
-    expect(ok).to.equal(false);
-    expect(router.getRateReport().reason).to.equal('count-limit');
-  });
-
-  it('shouldSend accounts for higher-priority traffic', function() {
-    const bySfx = new Map([
-      [2, { count: 2, bytes: 6, priority: 2 }]
-    ]);
-    const snapshot = makeRateSnapshot({ count: 2, bytes: 6, bySfx }, {}, 100);
-    const usageShare = [{ sfxId: 2, count: 2, bytes: 6, priority: 2, percentCount: 1, percentBytes: 1 }];
-    const { router } = makeRateRouter(
-      { limits: { maxEventsPerSecond: 2, hardMaxEventsPerSecond: 10, maxBytesPerSecond: 100 } },
-      snapshot,
-      usageShare
-    );
-    const plan = makePlan({ on: { count: 1, bytes: 3 } });
-    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, { timeMs: 0 }, plan, 0);
-    expect(ok).to.equal(false);
-    expect(router.getRateReport().reason).to.equal('priority-saturated');
-  });
-
-  it('onEvent applies repeat amount and boost settings', function() {
-    const { router } = makeRouter({
-      enabled: true,
-      timing: { bpmBase: 120 },
-      repeat: { amount: 0.5, target: 'velocity', maxRepeats: 2, windowBeats: 1 },
-      sfx: { '1': { note: 60 } }
-    });
-    const output = { channels: { 1: { sendNoteOn() {}, sendNoteOff() {}, sendPitchBend() {}, sendControlChange() {}, sendAllNotesOff() {}, sendPitchBendRange() {} } } };
-    router.scheduler.setOutput(output);
-    router._shouldSend = () => true;
-    router.scheduler.sendNote = () => {};
-
-    router._onEvent({ sfxId: 1, tick: 1, tps: 50, timeMs: 0 });
-    router._onEvent({ sfxId: 1, tick: 2, tps: 50, timeMs: 20 });
-
-    const { router: boostRouter } = makeRouter({
-      enabled: true,
-      timing: { bpmBase: 120 },
-      repeat: { velocityBoost: 0.2, durationBoost: 0.1, maxRepeats: 2, windowBeats: 1 },
-      sfx: { '1': { note: 60 } }
-    });
-    boostRouter.scheduler.setOutput(output);
-    boostRouter._shouldSend = () => true;
-    boostRouter.scheduler.sendNote = () => {};
-    boostRouter._onEvent({ sfxId: 1, tick: 1, tps: 50, timeMs: 0 });
-  });
-
-  it('onEvent fills defaults when repeat boosts are missing', function() {
-    const { router, sent } = makeRouter({
-      enabled: true,
-      limits: null,
-      timing: null,
-      repeat: null,
-      triggers: null,
-      sfx: { '1': { note: 60, repeat: { maxRepeats: 2, windowBeats: 1 } } }
-    }, { mapEvent: () => ({ note: 60 }) });
-    router.context = { level: { width: 200, height: 100 } };
-    router._nowMs = () => 0;
-
-    router._onEvent({ sfxId: 1, tick: 1, triggerType: 5, timeMs: 0, tps: 50 });
-
-    expect(sent.length).to.equal(1);
-    expect(sent[0].velocity).to.equal(64);
-    expect(sent[0].durationTicks).to.equal(1);
-  });
-
-  it('covers attach cleanup and tick defaults', function() {
-    const { router: routerA, mapping } = makeRouter({ timing: { bpmBase: 10 } });
-    const routerB = new MidiEventRouter({ timing: { bpmBase: 120 } });
-    expect(routerA.mapping).to.equal(mapping);
-    expect(routerB.mapping).to.be.instanceOf(MidiMapping);
-
-    let onCalls = 0;
-    let offCalls = 0;
-    const onEvent = { on() { onCalls += 1; }, off() { offCalls += 1; } };
-    const bus = { onEvent };
-    routerA.attach(bus, {});
-    routerA.attach(bus, {});
-    routerA.detach();
-    expect(onCalls).to.equal(2);
-    expect(offCalls).to.equal(2);
-
-    routerA.context = { game: { getGameTimer() { return { frameTime: 30, speedFactor: 1 }; } } };
-    expect(routerA._tickMsFromEvent({ tps: 50 })).to.equal(20);
-    expect(routerA._tickMsFromEvent({ frameMs: 40 })).to.equal(40);
-    expect(routerA._tickMsFromEvent({})).to.equal(30);
-    routerA.context = {};
-    expect(routerA._tickMsFromEvent({})).to.equal(60);
-    expect(routerA._getBpm()).to.equal(20);
-  });
-
-  it('covers density and schedule base resets', function() {
-    const { router } = makeRouter({ density: { windowTicks: 4 } });
-    expect(router._densityForEvent({})).to.equal(0);
-    router._lastTickBySfx.set(1, 5);
-    expect(router._densityForEvent({ sfxId: 1, tick: 5 })).to.equal(1);
-    expect(router._densityForEvent({ sfxId: 1, tick: 9 })).to.equal(0);
-    expect(router._densityForEvent({ sfxId: 1, tick: 7 })).to.be.closeTo(0.5, 0.01);
-
-    const originalPerf = globalThis.performance;
-    globalThis.performance = undefined;
-    const now = router._nowMs();
-    globalThis.performance = originalPerf;
-    expect(Number.isFinite(now)).to.equal(true);
-
-    router.scheduler = null;
-    expect(router._resolveScheduleBase(NaN, 0, 0)).to.equal(null);
-
-    router._clockFrameMs = 10;
-    router._clockSpeedFactor = 1;
-    router._nowMs = () => 1000;
-    router._resolveScheduleBase(100, 20, 1);
-
-    let cleared = 0;
-    router.scheduler = { allNotesOff() { cleared += 1; }, clearQueue() { cleared += 1; } };
-    router._resolveScheduleBase(200, 21, 2);
-    expect(cleared).to.equal(2);
-  });
-
-  it('covers repeat target fallbacks and plan entries', function() {
-    const { router, mapping } = makeRouter({ repeat: { maxRepeats: 2, spacingTicks: 2 } });
-    const bpm = 60;
-    expect(router._getRepeatFactor('sfx:1', 0, mapping.config.repeat, bpm)).to.equal(0);
-    expect(router._getRepeatFactor('sfx:1', 1000, mapping.config.repeat, bpm)).to.be.greaterThan(0);
-
-    const spec = { note: 60, velocity: 64, durationTicks: 2, pitchBend: 0.2, releaseVelocity: 64 };
-    const notes = [60, 64];
-    const noAmount = router._applyRepeatTarget(spec, notes, { target: 'velocity', amount: 'bad' }, 1);
-    expect(noAmount.spec).to.equal(spec);
-    const zeroAmount = router._applyRepeatTarget(spec, notes, { target: 'velocity', amount: 0 }, 1);
-    expect(zeroAmount.spec).to.equal(spec);
-
-    router._applyRepeatTarget(spec, notes, { target: 'accent', amount: 0.5 }, 1);
-    router._applyRepeatTarget(spec, notes, { target: 'duration', amount: 0.5 }, 1);
-    router._applyRepeatTarget(spec, notes, { target: 'note', amount: 0.5 }, 1);
-    router._applyRepeatTarget({ ...spec, timbre: 10 }, notes, { target: 'timbre', amount: 0.5 }, 1);
-    router._applyRepeatTarget({ ...spec, pan: 0 }, notes, { target: 'pan', amount: 0.5 }, 1);
-    router._applyRepeatTarget({ ...spec, pitchBend: 0.5 }, notes, { target: 'pitchBend', amount: 0.5 }, 1);
-    router._applyRepeatTarget({ ...spec, pitchBend: NaN }, notes, { target: 'pitchBend', amount: 0.5 }, 1);
-    router._applyRepeatTarget(spec, notes, { target: 'attack', amount: 0.5 }, 1);
-    router._applyRepeatTarget(spec, notes, { target: 'decay', amount: 0.5 }, 1);
-    router._applyRepeatTarget(spec, notes, { target: 'sustain', amount: 0.5 }, 1);
-    router._applyRepeatTarget(spec, notes, { target: 'release', amount: 0.5 }, 1);
-    router._applyRepeatTarget(spec, notes, { target: 'unknown', amount: 0.5 }, 1);
-
-    const { router: mpeRouter } = makeRouter({ mpe: { enabled: true } });
-    mpeRouter.scheduler.tickMs = 10;
-    const planA = mpeRouter._planEntries({ note: 60, durationTicks: NaN }, 1000, 2);
-    const planB = mpeRouter._planEntries({ note: 60, durationTicks: 1 }, 1000, 1);
-    expect(planA.off.count).to.equal(0);
-    expect(planB.off.count).to.equal(2);
-  });
-
-  it('shouldSend enforces hard caps', function() {
-    const snapshot = makeRateSnapshot({ count: 10, bytes: 0 }, {}, 100);
-    const { router } = makeRateRouter(
-      { limits: { maxEventsPerSecond: 10, hardMaxEventsPerSecond: 11, maxBytesPerSecond: 100 } },
-      snapshot
-    );
-    const plan = makePlan({ on: { count: 2 } });
-    const ok = router._shouldSend({ sfxId: 1, priority: 1 }, { timeMs: 0 }, plan, 0);
-    expect(ok).to.equal(false);
-    expect(router.getRateReport().reason).to.equal('count-limit');
-  });
-
-  it('shouldSend throttles on byte budgets and priorities', function() {
-    const bySfx = new Map([
-      [1, { count: 1, bytes: 0, priority: 1 }],
-      [2, { count: 1, bytes: 5, priority: 2 }]
-    ]);
-    const snapshot = makeRateSnapshot({ count: 2, bytes: 5, bySfx }, {}, 5);
-    const usageShare = [
-      { sfxId: 1, count: 1, bytes: 0, priority: 1, percentCount: 0.5, percentBytes: 0 },
-      { sfxId: 2, count: 1, bytes: 5, priority: 2, percentCount: 0.5, percentBytes: 1 }
-    ];
-    const { router } = makeRateRouter(
-      { limits: { maxEventsPerSecond: 2, hardMaxEventsPerSecond: 10, maxBytesPerSecond: 5 } },
-      snapshot,
-      usageShare
-    );
-    const plan = makePlan({ on: { count: 1 }, off: { timeMs: 500 } });
-    const ok = router._shouldSend({ sfxId: 3, priority: 1 }, { timeMs: 0 }, plan, 0);
-    expect(ok).to.equal(false);
-    expect(router.getRateReport().reason).to.equal('byte-limit');
-  });
-
-  it('setMapping accepts MidiMapping instances', function() {
-    const mapping = new MidiMapping({ timing: { bpmBase: 90 } });
-    let configured = null;
-    const { router } = makeRouter({}, {
-      scheduler: { setConfig(cfg) { configured = cfg; } }
-    });
-    router.setMapping(mapping);
-    expect(router.mapping).to.equal(mapping);
-    expect(configured).to.equal(mapping.config);
-  });
-
-  it('returns zero density when window ticks are disabled', function() {
-    const { router } = makeRouter({ density: null });
-    expect(router._densityForEvent({ sfxId: 1, tick: 10 })).to.equal(0);
-  });
-
-  it('resolves arpeggio keys to unknown when sfxId is missing', function() {
-    const { router } = makeRouter();
-    const key = router._resolveArpKey({}, {});
-    expect(key).to.equal('sfx:unknown');
-  });
-
-  it('merges trigger config into sfx overrides on events', function() {
-    let captured = null;
-    const { router, sent } = makeRouter({
-      enabled: true,
-      limits: { maxEventsPerSecond: 1000 },
-      sfx: { '1': { velocity: 10 } },
-      triggers: { '7': { velocity: 20 } }
-    }, {
-      mapEvent: (event, context, density, sfx) => {
-        captured = sfx;
-        return { note: 60, velocity: sfx.velocity, durationTicks: 1 };
-      }
-    });
-    router.scheduler.output = {};
-
-    router._onEvent({ sfxId: 1, tick: 1, tps: 50, triggerType: 7 });
-
-    expect(captured.velocity).to.equal(20);
-    expect(sent.length).to.equal(1);
-  });
-
-  it('returns zero repeat factors when repeats are disabled or invalid', function() {
-    const { router } = makeRouter();
-    const repeatCfg = { maxRepeats: 0, windowBeats: 0 };
-    expect(router._getRepeatFactor('sfx:1', NaN, repeatCfg, 0)).to.equal(0);
-  });
-
-  it('applies repeat defaults when velocity and duration are missing', function() {
-    const { router } = makeRouter();
-    const baseSpec = { note: 60 };
-
-    const velocity = router._applyRepeatTarget(
-      baseSpec,
-      [60],
-      { amount: 0.5, target: 'velocity' },
-      1
-    ).spec.velocity;
-    expect(velocity).to.equal(96);
-
-    const duration = router._applyRepeatTarget(
-      baseSpec,
-      [60],
-      { amount: 0.5, target: 'duration' },
-      1
-    ).spec.durationTicks;
-    expect(duration).to.equal(2);
-
-    const release = router._applyRepeatTarget(
-      baseSpec,
-      [60],
-      { amount: 0.5, target: 'release' },
-      1
-    ).spec.releaseVelocity;
-    expect(release).to.equal(96);
-  });
-
-  it('defaults repeat targets when ranges and velocity are missing', function() {
-    const router = new MidiEventRouter(new MidiMapping({
-      position: { timbreRange: null, panRange: null }
-    }));
-    const baseSpec = { note: 60, timbre: 10, pan: 0 };
-    const notes = [60];
-
-    const timbre = router._applyRepeatTarget(
-      baseSpec,
-      notes,
-      { amount: 0.5, target: 'timbre' },
-      1
-    ).spec.timbre;
-    expect(timbre).to.be.within(0, 127);
-    expect(timbre).to.not.equal(10);
-
-    const pan = router._applyRepeatTarget(
-      baseSpec,
-      notes,
-      { amount: 0.5, target: 'pan' },
-      1
-    ).spec.pan;
-    expect(pan).to.be.within(-127, 127);
-
-    const attack = router._applyRepeatTarget(
-      { note: 60 },
-      notes,
-      { amount: 0.5, target: 'attack' },
-      1
-    ).spec.velocity;
-    expect(attack).to.equal(96);
-  });
-
-  it('replaces mappings when setMapping receives a plain object', function() {
-    const { router } = makeRouter();
-    router.setMapping({ enabled: true });
-    expect(router.mapping).to.be.instanceOf(MidiMapping);
-    expect(router.mapping.config.enabled).to.equal(true);
-  });
-
-  it('clamps notes to defaults when no note range is configured', function() {
-    const { router } = makeRouter({ noteRange: null, position: {} });
-    const adjusted = router._applyRepeatTarget(
-      { note: 60 },
-      [200],
-      { amount: 1, target: 'note' },
-      1
-    );
-    expect(adjusted.activeNotes[0]).to.equal(127);
-  });
-
-  it('reuses MidiMapping instances in setMapping', function() {
-    const mapping = new MidiMapping({ enabled: false });
-    const { router } = makeRouter();
-    router.setMapping(mapping);
-    expect(router.mapping).to.equal(mapping);
-  });
-
-  it('uses repeat fallbacks when window beats and max repeats are missing', function() {
-    const { router } = makeRouter();
-    const bpm = router._getBpm();
-    const repeatCfg = { maxRepeats: 1, windowBeats: 1 };
-    router._getRepeatFactor('sfx:1', 0, repeatCfg, bpm);
-    const factor = router._getRepeatFactor('sfx:1', 100, repeatCfg, bpm);
-    expect(factor).to.equal(1);
-
-    const fallback = router._getRepeatFactor('sfx:2', 50, { spacingTicks: 2 }, bpm);
-    expect(fallback).to.equal(0);
-
-    const emptyWindow = router._getRepeatFactor('sfx:3', 60, { maxRepeats: 2 }, bpm);
-    expect(emptyWindow).to.equal(0);
-  });
-
-  it('replaces null mappings with defaults', function() {
-    const { router } = makeRouter();
-    router.setMapping(null);
-    expect(router.mapping).to.be.instanceOf(MidiMapping);
-  });
-
-  it('uses repeat spacing fallbacks and default targets', function() {
-    const { router } = makeRouter({
-      noteRange: { min: null, max: null },
-      position: null
-    });
-    const bpm = router._getBpm();
-    router._getRepeatFactor('sfx:1', 0, { maxRepeats: 2, spacingTicks: 2 }, bpm);
-    const factor = router._getRepeatFactor('sfx:1', 100, { maxRepeats: 2, spacingTicks: 2 }, bpm);
-    expect(factor).to.be.greaterThan(0);
-
-    const baseSpec = { velocity: 50, note: 200 };
-    const adjusted = router._applyRepeatTarget(baseSpec, [200], { amount: 0.5 }, 1);
-    expect(adjusted.spec.velocity).to.be.greaterThan(50);
-    expect(adjusted.activeNotes[0]).to.equal(200);
-
-    const noteAdjusted = router._applyRepeatTarget(
-      baseSpec,
-      [200],
-      { amount: 0.5, target: 'note' },
-      1
-    );
-    expect(noteAdjusted.activeNotes[0]).to.equal(127);
-
-    const timbreAdjusted = router._applyRepeatTarget(
-      { ...baseSpec, timbre: 10 },
-      [60],
-      { amount: 0.5, target: 'timbre' },
-      1
-    );
-    expect(timbreAdjusted.spec.timbre).to.be.within(0, 127);
-  });
-});
diff --git a/test/midi/midi-flag-triggers.test.js b/test/midi/midi-flag-triggers.test.js
new file mode 100644
index 00000000..325d186e
--- /dev/null
+++ b/test/midi/midi-flag-triggers.test.js
@@ -0,0 +1,33 @@
+import { expect } from 'chai';
+import {
+  MIDI_FLAG_TRIGGER_BASE,
+  MIDI_FLAG_TRIGGER_MAX,
+  clampMidiFlagId,
+  fromMidiFlagTriggerType,
+  isMidiFlagTriggerType,
+  toMidiFlagTriggerType
+} from '../../js/midi/MidiFlagTriggers.js';
+
+describe('MidiFlagTriggers', () => {
+  it('clamps and validates midi flag ids', () => {
+    expect(clampMidiFlagId(Number.NaN)).to.equal(null);
+    expect(clampMidiFlagId(0)).to.equal(null);
+    expect(clampMidiFlagId(2.9)).to.equal(2);
+    expect(clampMidiFlagId(MIDI_FLAG_TRIGGER_MAX + 100)).to.equal(MIDI_FLAG_TRIGGER_MAX);
+  });
+
+  it('converts flag ids to trigger types and back', () => {
+    expect(toMidiFlagTriggerType(7)).to.equal(MIDI_FLAG_TRIGGER_BASE + 7);
+    expect(toMidiFlagTriggerType(0)).to.equal(null);
+    expect(fromMidiFlagTriggerType(MIDI_FLAG_TRIGGER_BASE + 7)).to.equal(7);
+    expect(fromMidiFlagTriggerType(MIDI_FLAG_TRIGGER_BASE)).to.equal(null);
+    expect(fromMidiFlagTriggerType(MIDI_FLAG_TRIGGER_BASE + MIDI_FLAG_TRIGGER_MAX + 1)).to.equal(null);
+  });
+
+  it('detects midi flag trigger types', () => {
+    const triggerType = toMidiFlagTriggerType(9);
+    expect(isMidiFlagTriggerType(triggerType)).to.equal(true);
+    expect(isMidiFlagTriggerType(3)).to.equal(false);
+    expect(isMidiFlagTriggerType(MIDI_FLAG_TRIGGER_BASE + MIDI_FLAG_TRIGGER_MAX + 100)).to.equal(false);
+  });
+});
diff --git a/test/midi/midi-input-controller-coverage.test.js b/test/midi/midi-input-controller.coverage.01-midiinputcontroller-coverage-branches-and-fallba.test.js
similarity index 56%
rename from test/midi/midi-input-controller-coverage.test.js
rename to test/midi/midi-input-controller.coverage.01-midiinputcontroller-coverage-branches-and-fallba.test.js
index cdc46c6a..18e0b64f 100644
--- a/test/midi/midi-input-controller-coverage.test.js
+++ b/test/midi/midi-input-controller.coverage.01-midiinputcontroller-coverage-branches-and-fallba.test.js
@@ -1,245 +1,10 @@
 import { expect } from 'chai';
 import { MidiInputController } from '../../js/midi/input/MidiInputController.js';
+import { withPatchedGlobals } from '../support/globals.js';
 
 const makeConfig = (channel = 'omni') => ({ input: { channel } });
 
-describe('MidiInputController coverage', function() {
-  it('setConfig handles numeric and string channels', function() {
-    const controller = new MidiInputController({});
-    controller.setConfig(makeConfig(3));
-    expect(controller.channel).to.equal(3);
-    controller.setConfig(makeConfig('OmNi'));
-    expect(controller.channel).to.equal('omni');
-  });
-
-  it('applyConfigPatch uses handler before view overrides', function() {
-    const patches = [];
-    const view = { applyMidiOverrides() { patches.push('view'); } };
-    const controller = new MidiInputController(view, {
-      onConfigChange: patch => patches.push(patch)
-    });
-    controller._applyConfigPatch({ timing: { bpmBase: 140 } });
-    expect(patches.length).to.equal(1);
-    expect(patches[0].timing.bpmBase).to.equal(140);
-  });
-
-  it('setNested ignores empty paths and creates nested objects', function() {
-    const controller = new MidiInputController({});
-    const target = {};
-    controller._setNested(target, '', 1);
-    expect(Object.keys(target)).to.have.length(0);
-    controller._setNested(target, 'a.b.c', 2);
-    expect(target.a.b.c).to.equal(2);
-  });
-
-  it('setSpeedFactor routes to view selector or fallback field', function() {
-    const speeds = [];
-    const view = { selectSpeedFactor(value) { speeds.push(value); } };
-    const controller = new MidiInputController(view);
-    controller._setSpeedFactor(2);
-    expect(speeds[0]).to.equal(2);
-
-    const viewFallback = { gameSpeedFactor: 1 };
-    const controllerFallback = new MidiInputController(viewFallback);
-    controllerFallback._setSpeedFactor(3);
-    expect(viewFallback.gameSpeedFactor).to.equal(3);
-  });
-
-  it('changeSpeed reads from game timer when present', function() {
-    const speeds = [];
-    const view = {
-      selectSpeedFactor(value) { speeds.push(value); },
-      game: { getGameTimer() { return { speedFactor: 2 }; } }
-    };
-    const controller = new MidiInputController(view);
-    controller._changeSpeed(0.5);
-    expect(speeds[speeds.length - 1]).to.equal(2.5);
-  });
-
-  it('handles skill misses and action shortcuts', function() {
-    const view = {
-      gameSpeedFactor: 2,
-      game: { queueCommand() {} }
-    };
-    const config = {
-      input: {
-        channel: 'omni',
-        notes: {
-          skillBase: 60,
-          skillOrder: [],
-          actions: { speedReset: 60 }
-        }
-      }
-    };
-    const controller = new MidiInputController(view, { getConfig: () => config });
-    controller._handleNoteOn(60, 100, config, 1);
-    expect(view.gameSpeedFactor).to.equal(1);
-  });
-
-  it('maps control change entries with value lists and toggles', function() {
-    const patches = [];
-    const config = {
-      input: {
-        channel: 'omni',
-        cc: {
-          scaleName: { cc: 10, target: 'scale.name', values: ['major', 'minor'] },
-          viewPan: { cc: 11, target: 'position.viewPan', toggle: true },
-          floatValue: { cc: 12, target: 'timing.bpmBase', min: 0, max: 2 }
-        }
-      }
-    };
-    const controller = new MidiInputController({}, {
-      getConfig: () => config,
-      onConfigChange: patch => patches.push(patch)
-    });
-
-    controller._handleControlChange(10, 127, config);
-    controller._handleControlChange(11, 127, config);
-    controller._handleControlChange(12, 64, config);
-
-    expect(patches.some(patch => patch.scale?.name === 'minor')).to.equal(true);
-    expect(patches.some(patch => patch.position?.viewPan === true)).to.equal(true);
-    expect(patches.some(patch => typeof patch.timing?.bpmBase === 'number')).to.equal(true);
-  });
-
-  it('ignores messages on mismatched channels', function() {
-    const controller = new MidiInputController({}, { getConfig: () => makeConfig(2) });
-    let handled = false;
-    controller._handleNoteOn = () => { handled = true; };
-    controller._onMessage({ data: [0x90, 60, 100] });
-    expect(handled).to.equal(false);
-  });
-
-  it('applies view overrides and handles transport actions', function() {
-    const patches = [];
-    const view = {
-      applyMidiOverrides(patch) { patches.push(patch); },
-      moveToLevel() { this.moved = true; },
-      suspend() { this.paused = true; },
-      continue() { this.resumed = true; }
-    };
-    const config = {
-      input: {
-        channel: 'omni',
-        transport: { start: 'restart', stop: 'pause', continue: 'resume' }
-      }
-    };
-    const controller = new MidiInputController(view, { getConfig: () => config });
-    controller._applyConfigPatch({ timing: { bpmBase: 111 } });
-    expect(patches[0].timing.bpmBase).to.equal(111);
-
-    controller._onMessage({ data: [0xFA] });
-    controller._onMessage({ data: [0xFC] });
-    controller._onMessage({ data: [0xFB] });
-    expect(view.moved).to.equal(true);
-    expect(view.paused).to.equal(true);
-    expect(view.resumed).to.equal(true);
-  });
-
-  it('handles note capture, skill selection, and action shortcuts', function() {
-    let midiEnabled = true;
-    const patches = [];
-    const view = {
-      midiEnabled,
-      setMidiEnabled(value) { midiEnabled = value; this.midiEnabled = value; },
-      selectSpeedFactor(value) { this.lastSpeed = value; },
-      game: { queueCommand() {}, gameGui: {} }
-    };
-    const config = {
-      input: {
-        channel: 'omni',
-        notes: {
-          skillBase: 60,
-          skillOrder: ['CLIMBER'],
-          actions: {
-            pause: 36,
-            resume: 37,
-            restart: 38,
-            speedDown: 39,
-            speedUp: 40,
-            speedReset: 41,
-            toggleMidi: 42,
-            toggleViewPan: 43
-          }
-        }
-      },
-      position: { viewPan: false }
-    };
-    const controller = new MidiInputController(view, {
-      getConfig: () => config,
-      onConfigChange: patch => patches.push(patch)
-    });
-    const captured = [];
-    controller.setNoteCapture((note) => {
-      captured.push(note);
-      return true;
-    });
-    controller._handleNoteOn(60, 100, config, 1);
-    expect(captured).to.eql([60]);
-
-    controller.setNoteCapture(null);
-    controller._handleNoteOn(60, 100, config, 1);
-    controller._handleNoteOn(36, 100, config, 1);
-    controller._handleNoteOn(37, 100, config, 1);
-    controller._handleNoteOn(38, 100, config, 1);
-    controller._handleNoteOn(39, 100, config, 1);
-    controller._handleNoteOn(40, 100, config, 1);
-    controller._handleNoteOn(41, 100, config, 1);
-    controller._handleNoteOn(42, 100, config, 1);
-    controller._handleNoteOn(43, 100, config, 1);
-    expect(view.midiEnabled).to.equal(false);
-    expect(patches.some(patch => patch.position?.viewPan === true)).to.equal(true);
-
-    const before = view.lastSpeed;
-    controller._handleNoteOn(60, 0, config, 1);
-    expect(view.lastSpeed).to.equal(before);
-  });
-
-  it('maps control change branches and ignores note-off messages', function() {
-    const patches = [];
-    const view = { selectSpeedFactor(value) { this.speed = value; } };
-    const config = {
-      input: {
-        channel: 1,
-        cc: {
-          speed: { cc: 1, min: 0.1, max: 2 },
-          bpmBase: { cc: 2, min: 60, max: 200 },
-          intensity: { cc: 3, min: 10, max: 120 },
-          accent: { cc: 4, min: 0, max: 1 },
-          rounded: { cc: 5, target: 'noteDefaults.octave', min: 1, max: 8, round: true }
-        }
-      }
-    };
-    const controller = new MidiInputController(view, {
-      getConfig: () => config,
-      onConfigChange: patch => patches.push(patch)
-    });
-    controller._handleControlChange(1, 64, config);
-    controller._handleControlChange(2, 127, config);
-    controller._handleControlChange(3, 100, config);
-    controller._handleControlChange(4, 127, config);
-    controller._handleControlChange(5, 127, config);
-
-    expect(view.speed).to.be.greaterThan(0);
-    expect(patches.some(patch => patch.timing?.bpmBase)).to.equal(true);
-    expect(patches.some(patch => patch.velocityRange?.default)).to.equal(true);
-    expect(patches.some(patch => patch.density?.velocityBoost != null)).to.equal(true);
-
-    controller._onMessage({ data: [0x80, 60, 100] });
-  });
-
-  it('records last MIDI message when window is defined', function() {
-    const controller = new MidiInputController({}, { getConfig: () => makeConfig('omni') });
-    const originalWindow = globalThis.window;
-    globalThis.window = {};
-    try {
-      controller._onMessage({ data: [0xB0, 10, 20] });
-      expect(globalThis.window.lastMidiInputMessage).to.eql([0xB0, 10, 20]);
-    } finally {
-      globalThis.window = originalWindow;
-    }
-  });
-
+describe('MidiInputController coverage: branches and fallbacks 1', function() {
   it('uses view getMidiConfig when no getConfig is provided', function() {
     let calls = 0;
     const config = makeConfig('omni');
@@ -287,7 +52,7 @@ describe('MidiInputController coverage', function() {
     expect(patches).to.have.length(0);
   });
 
-  it('ignores realtime messages that are not transport commands', function() {  
+  it('ignores realtime messages that are not transport commands', function() {
     const controller = new MidiInputController({}, { getConfig: () => makeConfig('omni') });
     let transportCalls = 0;
     controller._handleTransport = () => { transportCalls += 1; };
@@ -298,10 +63,12 @@ describe('MidiInputController coverage', function() {
   it('covers constructor fallbacks and speed defaults', function() {
     const patches = [];
     const view = {
-      getMidiConfig() { return { input: { channel: null } }; },
-      applyMidiOverrides(patch) { patches.push(patch); }
+      getMidiConfig() { return { input: { channel: null } }; }
     };
-    const controller = new MidiInputController(view, { getConfig: 123 });
+    const controller = new MidiInputController(view, {
+      getConfig: 123,
+      onConfigChange: patch => patches.push(patch)
+    });
     expect(controller.getConfig()).to.eql({ input: { channel: null } });
     const nullView = new MidiInputController(null);
     expect(nullView.getConfig()).to.equal(undefined);
@@ -414,7 +181,6 @@ describe('MidiInputController coverage', function() {
     const patches = [];
     const view = {
       getMidiConfig() { return { input: { channel: null } }; },
-      applyMidiOverrides(patch) { patches.push(patch); },
       selectSpeedFactor(value) { this.speed = value; },
       gameSpeedFactor: 1,
       moveToLevel() { this.restarted = true; },
@@ -454,7 +220,10 @@ describe('MidiInputController coverage', function() {
       },
       position: { viewPan: true }
     };
-    const controller = new MidiInputController(view, { getConfig: null });
+    const controller = new MidiInputController(view, {
+      getConfig: null,
+      onConfigChange: patch => patches.push(patch)
+    });
     controller._onMessage({ data: [0xF8] });
     controller.setConfig(config);
     controller._applyConfigPatch({ timing: { bpmBase: 120 } });
@@ -516,7 +285,6 @@ describe('MidiInputController coverage', function() {
           position: { viewPan: false }
         };
       },
-      applyMidiOverrides() {},
       moveToLevel() { this.restarted = true; },
       suspend() { this.paused = true; },
       continue() { this.resumed = true; },
@@ -585,7 +353,6 @@ describe('MidiInputController coverage', function() {
           position: { viewPan: false }
         };
       },
-      applyMidiOverrides(patch) { patches.push(patch); },
       selectSpeedFactor(value) { this.speed = value; },
       gameSpeedFactor: 1,
       moveToLevel() { this.restarted = true; },
@@ -595,7 +362,9 @@ describe('MidiInputController coverage', function() {
       midiEnabled: true,
       game: { queueCommand() { this.queued = true; }, gameGui: {} }
     };
-    const controller = new MidiInputController(view);
+    const controller = new MidiInputController(view, {
+      onConfigChange: patch => patches.push(patch)
+    });
     controller.getConfig();
     controller.setConfig();
     const nullViewController = new MidiInputController(null);
@@ -660,113 +429,4 @@ describe('MidiInputController coverage', function() {
     expect(getCalls).to.equal(1);
     expect(viewCalls).to.equal(0);
   });
-
-  it('covers transport, actions, and control change defaults', function() {
-    const calls = { pause: 0, resume: 0, restart: 0, setSpeed: [] };
-    const patches = [];
-    const view = {
-      suspend() { calls.pause += 1; },
-      continue() { calls.resume += 1; },
-      moveToLevel() { calls.restart += 1; },
-      setMidiEnabled(value) { this.midiEnabled = value; },
-      applyMidiOverrides(patch) { patches.push(patch); },
-      midiEnabled: true,
-      gameSpeedFactor: 2,
-      game: { queueCommand() { calls.queued = true; }, gameGui: {} }
-    };
-    const config = {
-      input: {
-        channel: 'omni',
-        transport: { start: 'pause', stop: 'resume', continue: 'restart' },
-        notes: {
-          skillBase: 60,
-          skillOrder: ['CLIMBER'],
-          actions: {
-            pause: 70,
-            resume: 71,
-            restart: 72,
-            speedDown: 73,
-            speedUp: 74,
-            speedReset: 75,
-            toggleMidi: 76,
-            toggleViewPan: 77
-          }
-        },
-        cc: {
-          target: { cc: 10, target: 'timing.bpmBase' }
-        }
-      },
-      position: { viewPan: false }
-    };
-    const controller = new MidiInputController(view, { getConfig: () => config });
-    controller._setSpeedFactor = value => calls.setSpeed.push(value);
-    controller._handleTransport(0xFA, config);
-    controller._handleTransport(0xFC, config);
-    controller._handleTransport(0xFB, config);
-
-    controller._handleNoteOn(60, 100, config, 1);
-    expect(view.game.gameGui.skillSelectionChanged).to.equal(true);
-
-    controller._handleNoteOn(70, 100, config, 1);
-    controller._handleNoteOn(71, 100, config, 1);
-    controller._handleNoteOn(72, 100, config, 1);
-    controller._handleNoteOn(73, 100, config, 1);
-    controller._handleNoteOn(74, 100, config, 1);
-    controller._handleNoteOn(75, 100, config, 1);
-    controller._handleNoteOn(76, 100, config, 1);
-    controller._handleNoteOn(77, 100, config, 1);
-    controller._handleNoteOn(77, 0, config, 1);
-
-    controller._handleControlChange(10, 127, config);
-    expect(patches.length).to.equal(2);
-  });
-
-  it('uses default ranges for speed and intensity controls', function() {
-    const patches = [];
-    const view = {
-      applyMidiOverrides(patch) { patches.push(patch); },
-      game: { queueCommand() {}, gameGui: {} },
-      gameSpeedFactor: 1
-    };
-    const config = {
-      input: {
-        channel: 'omni',
-        cc: {
-          speed: { cc: 1 },
-          intensity: { cc: 7 }
-        }
-      }
-    };
-    const controller = new MidiInputController(view, { getConfig: () => config });
-    let speed = null;
-    controller._setSpeedFactor = value => { speed = value; };
-
-    controller._handleControlChange(1, 64, config);
-    controller._handleControlChange(7, 64, config);
-
-    expect(speed).to.be.greaterThan(0.1);
-    expect(speed).to.be.lessThan(8.1);
-    expect(patches[0].velocityRange.default).to.be.at.least(10);
-    expect(patches[0].velocityRange.default).to.be.at.most(127);
-  });
-
-  it('covers attach and fallback branches', function() {
-    const events = [];
-    const input = {
-      addListener(name) { events.push(['add', name]); },
-      removeListener(name) { events.push(['remove', name]); }
-    };
-    const view = { game: { queueCommand() {}, gameGui: {} } };
-    const controller = new MidiInputController(view);
-    controller.attach(input);
-    controller.attach(null);
-    expect(controller.input).to.equal(null);
-
-    const target = { timing: { bpmBase: 90 } };
-    controller._setNested(target, 'timing.bpmBase', 120);
-    expect(target.timing.bpmBase).to.equal(120);
-
-    controller._handleTransport(0xFA, { input: {} });
-    controller._handleControlChange(1, 64, { input: { cc: { speed: {} } } });
-  });
 });
diff --git a/test/midi/midi-input-controller.coverage.02-midiinputcontroller-coverage-branches-and-fallba.test.js b/test/midi/midi-input-controller.coverage.02-midiinputcontroller-coverage-branches-and-fallba.test.js
new file mode 100644
index 00000000..084ae83f
--- /dev/null
+++ b/test/midi/midi-input-controller.coverage.02-midiinputcontroller-coverage-branches-and-fallba.test.js
@@ -0,0 +1,120 @@
+import { expect } from 'chai';
+import { MidiInputController } from '../../js/midi/input/MidiInputController.js';
+import { withPatchedGlobals } from '../support/globals.js';
+
+const makeConfig = (channel = 'omni') => ({ input: { channel } });
+
+describe('MidiInputController coverage: branches and fallbacks 2', function() {
+  it('covers transport, actions, and control change defaults', function() {
+    const calls = { pause: 0, resume: 0, restart: 0, setSpeed: [] };
+    const patches = [];
+    const view = {
+      suspend() { calls.pause += 1; },
+      continue() { calls.resume += 1; },
+      moveToLevel() { calls.restart += 1; },
+      setMidiEnabled(value) { this.midiEnabled = value; },
+      midiEnabled: true,
+      gameSpeedFactor: 2,
+      game: { queueCommand() { calls.queued = true; }, gameGui: {} }
+    };
+    const config = {
+      input: {
+        channel: 'omni',
+        transport: { start: 'pause', stop: 'resume', continue: 'restart' },
+        notes: {
+          skillBase: 60,
+          skillOrder: ['CLIMBER'],
+          actions: {
+            pause: 70,
+            resume: 71,
+            restart: 72,
+            speedDown: 73,
+            speedUp: 74,
+            speedReset: 75,
+            toggleMidi: 76,
+            toggleViewPan: 77
+          }
+        },
+        cc: {
+          target: { cc: 10, target: 'timing.bpmBase' }
+        }
+      },
+      position: { viewPan: false }
+    };
+    const controller = new MidiInputController(view, {
+      getConfig: () => config,
+      onConfigChange: patch => patches.push(patch)
+    });
+    controller._setSpeedFactor = value => calls.setSpeed.push(value);
+    controller._handleTransport(0xFA, config);
+    controller._handleTransport(0xFC, config);
+    controller._handleTransport(0xFB, config);
+
+    controller._handleNoteOn(60, 100, config, 1);
+    expect(view.game.gameGui.skillSelectionChanged).to.equal(true);
+
+    controller._handleNoteOn(70, 100, config, 1);
+    controller._handleNoteOn(71, 100, config, 1);
+    controller._handleNoteOn(72, 100, config, 1);
+    controller._handleNoteOn(73, 100, config, 1);
+    controller._handleNoteOn(74, 100, config, 1);
+    controller._handleNoteOn(75, 100, config, 1);
+    controller._handleNoteOn(76, 100, config, 1);
+    controller._handleNoteOn(77, 100, config, 1);
+    controller._handleNoteOn(77, 0, config, 1);
+
+    controller._handleControlChange(10, 127, config);
+    expect(patches.length).to.equal(2);
+  });
+
+  it('uses default ranges for speed and intensity controls', function() {
+    const patches = [];
+    const view = {
+      game: { queueCommand() {}, gameGui: {} },
+      gameSpeedFactor: 1
+    };
+    const config = {
+      input: {
+        channel: 'omni',
+        cc: {
+          speed: { cc: 1 },
+          intensity: { cc: 7 }
+        }
+      }
+    };
+    const controller = new MidiInputController(view, {
+      getConfig: () => config,
+      onConfigChange: patch => patches.push(patch)
+    });
+    let speed = null;
+    controller._setSpeedFactor = value => { speed = value; };
+
+    controller._handleControlChange(1, 64, config);
+    controller._handleControlChange(7, 64, config);
+
+    expect(speed).to.be.greaterThan(0.1);
+    expect(speed).to.be.lessThan(8.1);
+    expect(patches[0].velocityRange.default).to.be.at.least(10);
+    expect(patches[0].velocityRange.default).to.be.at.most(127);
+  });
+
+  it('covers attach and fallback branches', function() {
+    const events = [];
+    const input = {
+      addListener(name) { events.push(['add', name]); },
+      removeListener(name) { events.push(['remove', name]); }
+    };
+    const view = { game: { queueCommand() {}, gameGui: {} } };
+    const controller = new MidiInputController(view);
+    controller.attach(input);
+    controller.attach(null);
+    expect(controller.input).to.equal(null);
+
+    const target = { timing: { bpmBase: 90 } };
+    controller._setNested(target, 'timing.bpmBase', 120);
+    expect(target.timing.bpmBase).to.equal(120);
+
+    controller._handleTransport(0xFA, { input: {} });
+    controller._handleControlChange(1, 64, { input: { cc: { speed: {} } } });
+  });
+});
diff --git a/test/midi/midi-input-controller.coverage.03-midiinputcontroller-coverage-config-and-mapping.test.js b/test/midi/midi-input-controller.coverage.03-midiinputcontroller-coverage-config-and-mapping.test.js
new file mode 100644
index 00000000..af1e903d
--- /dev/null
+++ b/test/midi/midi-input-controller.coverage.03-midiinputcontroller-coverage-config-and-mapping.test.js
@@ -0,0 +1,243 @@
+import { expect } from 'chai';
+import { MidiInputController } from '../../js/midi/input/MidiInputController.js';
+import { withPatchedGlobals } from '../support/globals.js';
+
+const makeConfig = (channel = 'omni') => ({ input: { channel } });
+
+describe('MidiInputController coverage: config and mapping', function() {
+  it('setConfig handles numeric and string channels', function() {
+    const controller = new MidiInputController({});
+    controller.setConfig(makeConfig(3));
+    expect(controller.channel).to.equal(3);
+    controller.setConfig(makeConfig('3'));
+    expect(controller.channel).to.equal(3);
+    controller.setConfig(makeConfig('OmNi'));
+    expect(controller.channel).to.equal('omni');
+  });
+
+  it('applyConfigPatch uses the project config handler', function() {
+    const patches = [];
+    const view = {};
+    const controller = new MidiInputController(view, {
+      onConfigChange: patch => patches.push(patch)
+    });
+    controller._applyConfigPatch({ timing: { bpmBase: 140 } });
+    expect(patches.length).to.equal(1);
+    expect(patches[0].timing.bpmBase).to.equal(140);
+  });
+
+  it('setNested ignores empty paths and creates nested objects', function() {
+    const controller = new MidiInputController({});
+    const target = {};
+    controller._setNested(target, '', 1);
+    expect(Object.keys(target)).to.have.length(0);
+    controller._setNested(target, 'a.b.c', 2);
+    expect(target.a.b.c).to.equal(2);
+  });
+
+  it('setSpeedFactor routes to view selector or fallback field', function() {
+    const speeds = [];
+    const view = { selectSpeedFactor(value) { speeds.push(value); } };
+    const controller = new MidiInputController(view);
+    controller._setSpeedFactor(2);
+    expect(speeds[0]).to.equal(2);
+
+    const viewFallback = { gameSpeedFactor: 1 };
+    const controllerFallback = new MidiInputController(viewFallback);
+    controllerFallback._setSpeedFactor(3);
+    expect(viewFallback.gameSpeedFactor).to.equal(3);
+  });
+
+  it('changeSpeed reads from game timer when present', function() {
+    const speeds = [];
+    const view = {
+      selectSpeedFactor(value) { speeds.push(value); },
+      game: { getGameTimer() { return { speedFactor: 2 }; } }
+    };
+    const controller = new MidiInputController(view);
+    controller._changeSpeed(0.5);
+    expect(speeds[speeds.length - 1]).to.equal(2.5);
+  });
+
+  it('handles skill misses and action shortcuts', function() {
+    const view = {
+      gameSpeedFactor: 2,
+      game: { queueCommand() {} }
+    };
+    const config = {
+      input: {
+        channel: 'omni',
+        notes: {
+          skillBase: 60,
+          skillOrder: [],
+          actions: { speedReset: 60 }
+        }
+      }
+    };
+    const controller = new MidiInputController(view, { getConfig: () => config });
+    controller._handleNoteOn(60, 100, config, 1);
+    expect(view.gameSpeedFactor).to.equal(1);
+  });
+
+  it('maps control change entries with value lists and toggles', function() {
+    const patches = [];
+    const config = {
+      input: {
+        channel: 'omni',
+        cc: {
+          scaleName: { cc: 10, target: 'scale.name', values: ['major', 'minor'] },
+          viewPan: { cc: 11, target: 'position.viewPan', toggle: true },
+          floatValue: { cc: 12, target: 'timing.bpmBase', min: 0, max: 2 }
+        }
+      }
+    };
+    const controller = new MidiInputController({}, {
+      getConfig: () => config,
+      onConfigChange: patch => patches.push(patch)
+    });
+
+    controller._handleControlChange(10, 127, config);
+    controller._handleControlChange(11, 127, config);
+    controller._handleControlChange(12, 64, config);
+
+    expect(patches.some(patch => patch.scale?.name === 'minor')).to.equal(true);
+    expect(patches.some(patch => patch.position?.viewPan === true)).to.equal(true);
+    expect(patches.some(patch => typeof patch.timing?.bpmBase === 'number')).to.equal(true);
+  });
+
+  it('ignores messages on mismatched channels', function() {
+    const controller = new MidiInputController({}, { getConfig: () => makeConfig(2) });
+    let handled = false;
+    controller._handleNoteOn = () => { handled = true; };
+    controller._onMessage({ data: [0x90, 60, 100] });
+    expect(handled).to.equal(false);
+  });
+
+  it('applies config handler patches and handles transport actions', function() {
+    const patches = [];
+    const view = {
+      moveToLevel() { this.moved = true; },
+      suspend() { this.paused = true; },
+      continue() { this.resumed = true; }
+    };
+    const config = {
+      input: {
+        channel: 'omni',
+        transport: { start: 'restart', stop: 'pause', continue: 'resume' }
+      }
+    };
+    const controller = new MidiInputController(view, {
+      getConfig: () => config,
+      onConfigChange: patch => patches.push(patch)
+    });
+    controller._applyConfigPatch({ timing: { bpmBase: 111 } });
+    expect(patches[0].timing.bpmBase).to.equal(111);
+
+    controller._onMessage({ data: [0xFA] });
+    controller._onMessage({ data: [0xFC] });
+    controller._onMessage({ data: [0xFB] });
+    expect(view.moved).to.equal(true);
+    expect(view.paused).to.equal(true);
+    expect(view.resumed).to.equal(true);
+  });
+
+  it('handles note capture, skill selection, and action shortcuts', function() {
+    let midiEnabled = true;
+    const patches = [];
+    const view = {
+      midiEnabled,
+      setMidiEnabled(value) { midiEnabled = value; this.midiEnabled = value; },
+      selectSpeedFactor(value) { this.lastSpeed = value; },
+      game: { queueCommand() {}, gameGui: {} }
+    };
+    const config = {
+      input: {
+        channel: 'omni',
+        notes: {
+          skillBase: 60,
+          skillOrder: ['CLIMBER'],
+          actions: {
+            pause: 36,
+            resume: 37,
+            restart: 38,
+            speedDown: 39,
+            speedUp: 40,
+            speedReset: 41,
+            toggleMidi: 42,
+            toggleViewPan: 43
+          }
+        }
+      },
+      position: { viewPan: false }
+    };
+    const controller = new MidiInputController(view, {
+      getConfig: () => config,
+      onConfigChange: patch => patches.push(patch)
+    });
+    const captured = [];
+    controller.setNoteCapture((note) => {
+      captured.push(note);
+      return true;
+    });
+    controller._handleNoteOn(60, 100, config, 1);
+    expect(captured).to.eql([60]);
+
+    controller.setNoteCapture(null);
+    controller._handleNoteOn(60, 100, config, 1);
+    controller._handleNoteOn(36, 100, config, 1);
+    controller._handleNoteOn(37, 100, config, 1);
+    controller._handleNoteOn(38, 100, config, 1);
+    controller._handleNoteOn(39, 100, config, 1);
+    controller._handleNoteOn(40, 100, config, 1);
+    controller._handleNoteOn(41, 100, config, 1);
+    controller._handleNoteOn(42, 100, config, 1);
+    controller._handleNoteOn(43, 100, config, 1);
+    expect(view.midiEnabled).to.equal(false);
+    expect(patches.some(patch => patch.position?.viewPan === true)).to.equal(true);
+
+    const before = view.lastSpeed;
+    controller._handleNoteOn(60, 0, config, 1);
+    expect(view.lastSpeed).to.equal(before);
+  });
+
+  it('maps control change branches and ignores note-off messages', function() {
+    const patches = [];
+    const view = { selectSpeedFactor(value) { this.speed = value; } };
+    const config = {
+      input: {
+        channel: 1,
+        cc: {
+          speed: { cc: 1, min: 0.1, max: 2 },
+          bpmBase: { cc: 2, min: 60, max: 200 },
+          intensity: { cc: 3, min: 10, max: 120 },
+          accent: { cc: 4, min: 0, max: 1 },
+          rounded: { cc: 5, target: 'noteDefaults.octave', min: 1, max: 8, round: true }
+        }
+      }
+    };
+    const controller = new MidiInputController(view, {
+      getConfig: () => config,
+      onConfigChange: patch => patches.push(patch)
+    });
+    controller._handleControlChange(1, 64, config);
+    controller._handleControlChange(2, 127, config);
+    controller._handleControlChange(3, 100, config);
+    controller._handleControlChange(4, 127, config);
+    controller._handleControlChange(5, 127, config);
+
+    expect(view.speed).to.be.greaterThan(0);
+    expect(patches.some(patch => patch.timing?.bpmBase)).to.equal(true);
+    expect(patches.some(patch => patch.velocityRange?.default)).to.equal(true);
+    expect(patches.some(patch => patch.density?.velocityBoost != null)).to.equal(true);
+
+    controller._onMessage({ data: [0x80, 60, 100] });
+  });
+
+  it('records last MIDI message when window is defined', function() {
+    const controller = new MidiInputController({}, { getConfig: () => makeConfig('omni') });
+    withPatchedGlobals({ window: {} }, () => {
+      controller._onMessage({ data: [0xB0, 10, 20] });
+      expect(globalThis.window.lastMidiInputMessage).to.eql([0xB0, 10, 20]);
+    });
+  });
+});
diff --git a/test/midi/midi-input-controller.test.js b/test/midi/midi-input-controller.test.js
index 41818b4f..2c9aff36 100644
--- a/test/midi/midi-input-controller.test.js
+++ b/test/midi/midi-input-controller.test.js
@@ -1,6 +1,7 @@
 import { expect } from 'chai';
 import { MidiInputController } from '../../js/midi/input/MidiInputController.js';
 import { SkillTypes } from '../../js/game/SkillTypes.js';
+import { withPatchedGlobals } from '../support/globals.js';
 
 describe('MidiInputController', function() {
   it('filters channels and selects skills', function() {
@@ -99,7 +100,7 @@ describe('MidiInputController', function() {
     expect(patches.some(patch => patch.density?.velocityBoost === 1)).to.equal(true);
   });
 
-  it('captures note input when a capture handler is active', function() {       
+  it('captures note input when a capture handler is active', function() {
     const commands = [];
     const view = {
       game: {
@@ -114,29 +115,86 @@ describe('MidiInputController', function() {
       }
     };
     const controller = new MidiInputController(view, { getConfig: () => config });
-    let captured = null;
-    controller.setNoteCapture((note) => {
-      captured = note;
+    const captured = [];
+    controller.setNoteCapture((note, velocity, channel) => {
+      captured.push({ note, velocity, channel });
       return true;
     });
 
     controller._onMessage({ data: [0x90, 60, 100] });
 
-    expect(captured).to.equal(60);
+    expect(captured).to.deep.equal([{ note: 60, velocity: 100, channel: 1 }]);
     expect(commands.length).to.equal(0);
   });
 
+  it('capture handlers respect channel filtering, velocity-zero note-ons, and fallthrough', function() {
+    const commands = [];
+    const view = {
+      game: {
+        queueCommand(cmd) { commands.push(cmd); },
+        gameGui: {}
+      }
+    };
+    const config = {
+      input: {
+        channel: 2,
+        notes: { skillBase: 60, skillOrder: ['CLIMBER'] }
+      }
+    };
+    const controller = new MidiInputController(view, { getConfig: () => config });
+    const captured = [];
+    controller.setNoteCapture((note, velocity, channel) => {
+      captured.push({ note, velocity, channel });
+      return false;
+    });
+
+    controller._onMessage({ data: [0x90, 60, 100] });
+    controller._onMessage({ data: [0x91, 60, 0] });
+    controller._onMessage({ data: [0x91, 60, 100] });
+
+    expect(captured).to.deep.equal([{ note: 60, velocity: 100, channel: 2 }]);
+    expect(commands.length).to.equal(1);
+    expect(commands[0].skill).to.equal(SkillTypes.CLIMBER);
+  });
+
+  it('captures normalized MIDI messages after channel filtering and can swallow dispatch', function() {
+    const commands = [];
+    const view = {
+      game: {
+        queueCommand(cmd) { commands.push(cmd); },
+        gameGui: {}
+      }
+    };
+    const config = {
+      input: {
+        channel: 3,
+        notes: { skillBase: 60, skillOrder: ['CLIMBER'] }
+      }
+    };
+    const controller = new MidiInputController(view, { getConfig: () => config });
+    const messages = [];
+    controller.setMessageCapture((message) => {
+      messages.push(message);
+      return true;
+    });
+
+    controller._onMessage({ data: [0x90, 60, 100], timeStamp: 5 });
+    controller._onMessage({ data: [0x92, 61, 0], timeStamp: 6 });
+    controller._onMessage({ data: [0x82, 61, 0], timeStamp: 7 });
+
+    expect(messages).to.have.lengthOf(2);
+    expect(messages[0]).to.include({ status: 0x92, type: 0x90, channel: 3, note: 61, velocity: 0, timestamp: 6 });
+    expect(messages[1]).to.include({ status: 0x82, type: 0x80, channel: 3, note: 61, velocity: 0, timestamp: 7 });
+    expect(commands).to.have.lengthOf(0);
+  });
+
   it('stores the last MIDI message on window', function() {
     const view = {};
     const controller = new MidiInputController(view, { getConfig: () => ({ input: { channel: 'omni' } }) });
-    const originalWindow = globalThis.window;
-    globalThis.window = {};
-    try {
+    withPatchedGlobals({ window: {} }, () => {
       controller._onMessage({ data: [0x90, 60, 100] });
       expect(globalThis.window.lastMidiInputMessage).to.eql([0x90, 60, 100]);
-    } finally {
-      globalThis.window = originalWindow;
-    }
+    });
   });
 
   it('sets gameSpeedFactor when no speed selector is present', function() {
@@ -181,12 +239,12 @@ describe('MidiInputController', function() {
     expect(calls.some(call => call.type === 'midimessage' && call.removed)).to.equal(true);
   });
 
-  it('applies config patches through the view when no handler is provided', function() {
+  it('ignores config patches when no handler is provided', function() {
     const patches = [];
-    const view = { applyMidiOverrides(patch) { patches.push(patch); } };
+    const view = {};
     const controller = new MidiInputController(view, { getConfig: () => ({ input: { channel: 'omni' } }) });
     controller._applyConfigPatch({ timing: { bpmBase: 140 } });
-    expect(patches).to.eql([{ timing: { bpmBase: 140 } }]);
+    expect(patches).to.eql([]);
   });
 
   it('uses the view config getter and adjusts speed with game timer', function() {
@@ -252,6 +310,154 @@ describe('MidiInputController', function() {
     expect(setCalled).to.equal(true);
   });
 
+  it('avoids redundant config normalization for unchanged config references', function() {
+    const config = { input: { channel: 'omni' } };
+    const controller = new MidiInputController({}, { getConfig: () => config });
+    let setCalls = 0;
+    const originalSetConfig = controller.setConfig.bind(controller);
+    controller.setConfig = (...args) => {
+      setCalls += 1;
+      return originalSetConfig(...args);
+    };
+    controller._onMessage({ data: [0xF8] });
+    controller._onMessage({ data: [0xF8] });
+    expect(setCalls).to.equal(1);
+  });
+
+  it('avoids redundant config normalization for equivalent wrapper objects', function() {
+    const sharedCc = { speed: { cc: 1, min: 0.1, max: 2 } };
+    const controller = new MidiInputController({}, {
+      getConfig: () => ({ input: { channel: 'omni', cc: sharedCc } })
+    });
+    let setCalls = 0;
+    const originalSetConfig = controller.setConfig.bind(controller);
+    controller.setConfig = (...args) => {
+      setCalls += 1;
+      return originalSetConfig(...args);
+    };
+
+    controller._onMessage({ data: [0xF8] });
+    controller._onMessage({ data: [0xF8] });
+
+    expect(setCalls).to.equal(1);
+  });
+
+  it('rebuilds CC mapping index when config CC bindings change', function() {
+    const speeds = [];
+    const patches = [];
+    const config = {
+      input: {
+        channel: 'omni',
+        cc: {
+          speed: { cc: 1, min: 0.1, max: 2 }
+        }
+      }
+    };
+    const controller = new MidiInputController({
+      selectSpeedFactor(value) { speeds.push(value); }
+    }, {
+      getConfig: () => config,
+      onConfigChange: patch => patches.push(patch)
+    });
+
+    controller._onMessage({ data: [0xB0, 1, 127] });
+    expect(speeds.length).to.equal(1);
+
+    config.input.cc = {
+      bpmBase: { cc: 2, min: 100, max: 200 }
+    };
+    controller._onMessage({ data: [0xB0, 2, 0] });
+    expect(patches.some(patch => patch.timing?.bpmBase === 100)).to.equal(true);
+
+    controller._onMessage({ data: [0xB0, 1, 127] });
+    expect(speeds.length).to.equal(1);
+  });
+
+  it('indexes note actions and rebuilds when note bindings change', function() {
+    const calls = { pause: 0, restart: 0 };
+    const config = {
+      input: {
+        channel: 'omni',
+        notes: {
+          actions: { pause: 40 }
+        }
+      }
+    };
+    const controller = new MidiInputController({
+      suspend() { calls.pause += 1; },
+      moveToLevel() { calls.restart += 1; }
+    }, {
+      getConfig: () => config
+    });
+
+    controller._onMessage({ data: [0x90, 40, 100] });
+    expect(calls.pause).to.equal(1);
+    expect(controller._noteActions.get(40)).to.equal('pause');
+
+    config.input.notes = {
+      actions: { restart: 41 }
+    };
+    controller._onMessage({ data: [0x90, 41, 100] });
+    controller._onMessage({ data: [0x90, 40, 100] });
+
+    expect(calls.restart).to.equal(1);
+    expect(calls.pause).to.equal(1);
+    expect(controller._noteActions.get(41)).to.equal('restart');
+  });
+
+  it('refreshes stale CC cache entries when mappings mutate in place', function() {
+    const speeds = [];
+    const config = {
+      input: {
+        channel: 'omni',
+        cc: {
+          speed: { cc: 1, min: 0.1, max: 2 }
+        }
+      }
+    };
+    const controller = new MidiInputController({
+      selectSpeedFactor(value) { speeds.push(value); }
+    }, {
+      getConfig: () => config
+    });
+
+    controller._onMessage({ data: [0xB0, 1, 127] });
+    expect(speeds.length).to.equal(1);
+
+    config.input.cc.speed.cc = 2;
+    controller._onMessage({ data: [0xB0, 1, 127] });
+    expect(speeds.length).to.equal(1);
+
+    controller._onMessage({ data: [0xB0, 2, 127] });
+    expect(speeds.length).to.equal(2);
+  });
+
+  it('resolveCcEntries rebuilds stale cache entries and rescans mappings', function() {
+    const config = {
+      input: {
+        channel: 'omni',
+        cc: {
+          speed: { cc: 1, min: 0.1, max: 2 },
+          accent: { cc: 2, min: 0, max: 1 }
+        }
+      }
+    };
+    const controller = new MidiInputController({}, { getConfig: () => config });
+    controller.setConfig(config);
+
+    const initial = controller._resolveCcEntries(1, config.input.cc);
+    expect(initial).to.have.length(1);
+    expect(initial[0].key).to.equal('speed');
+
+    config.input.cc.speed = { cc: 3, min: 0.1, max: 2 };
+    const stale = controller._resolveCcEntries(1, config.input.cc);
+    expect(stale).to.have.length(0);
+
+    const remapped = controller._resolveCcEntries(3, config.input.cc);
+    expect(remapped).to.have.length(1);
+    expect(remapped[0].key).to.equal('speed');
+  });
+
   it('defaults missing velocity and CC values to zero', function() {
     const controller = new MidiInputController({}, { getConfig: () => ({ input: { channel: 'omni' } }) });
     const noteCalls = [];
diff --git a/test/midi/midi-mapping-helpers.test.js b/test/midi/midi-mapping-helpers.test.js
index 46a2c694..2746bc74 100644
--- a/test/midi/midi-mapping-helpers.test.js
+++ b/test/midi/midi-mapping-helpers.test.js
@@ -22,22 +22,23 @@ describe('MidiMapping helpers', function() {
     expect(arrayOverride.noteRange).to.eql([1, 2, 3]);
   });
 
+  it('filters unsafe config merge keys without touching prototypes', function() {
+    const merged = __test__.mergeConfig(
+      { noteRange: { min: 40, max: 60 } },
+      JSON.parse('{"noteRange":{"max":72},"__proto__":{"polluted":true},"constructor":{"prototype":{"polluted":true}}}')
+    );
+
+    expect(merged.noteRange.max).to.equal(72);
+    expect(Object.prototype.hasOwnProperty.call(merged, '__proto__')).to.equal(false);
+    expect(Object.prototype.hasOwnProperty.call(merged, 'constructor')).to.equal(false);
+    expect(Object.getPrototypeOf(merged)).to.equal(null);
+    expect({}.polluted).to.equal(undefined);
+  });
+
   it('builds position mappings and axis values', function() {
     const mappings = __test__.resolvePositionMappings({ mappings: [{ axis: 'x' }] }, { min: 1, max: 2 });
     expect(mappings).to.have.length(1);
 
-    const toggles = __test__.resolvePositionMappings(
-      {
-        xToNote: true,
-        yToVelocity: true,
-        yToTimbre: true,
-        xNoteRange: { min: -5, max: 5 },
-        timbreRange: { min: 10, max: 20 }
-      },
-      { min: 10, max: 20 }
-    );
-    expect(toggles).to.have.length(3);
-
     const empty = __test__.resolvePositionMappings({}, { min: 1, max: 2 });
     expect(empty).to.have.length(0);
 
@@ -146,7 +147,12 @@ describe('MidiMapping helpers', function() {
     const fallbackScale = __test__.resolveScale(null);
     expect(fallbackScale.name).to.equal('chromatic-minor');
 
-    const mappings = __test__.resolvePositionMappings({ yToVelocity: true, yToTimbre: true }, null);
+    const mappings = __test__.resolvePositionMappings({
+      mappings: [
+        { axis: 'y', target: 'velocity', min: 127, max: 1 },
+        { axis: 'y', target: 'timbre', min: 127, max: 0 }
+      ]
+    }, null);
     expect(mappings[0].min).to.equal(127);
     expect(mappings[0].max).to.equal(1);
     expect(mappings[1].min).to.equal(127);
@@ -165,7 +171,7 @@ describe('MidiMapping helpers', function() {
     expect(__test__.clampNoteToRange(130, { min: 60 })).to.equal(118);
 
     const baseScale = { degrees: [0, 2, 4], root: 0 };
-    const chord = __test__.buildChordNotes(0, baseScale, 4, 'triad', 0);        
+    const chord = __test__.buildChordNotes(0, baseScale, 4, 'triad', 0);
     expect(chord).to.have.length(3);
   });
 
@@ -173,7 +179,7 @@ describe('MidiMapping helpers', function() {
     expect(__test__.isPlainObject(0)).to.not.be.ok;
 
     const mappings = __test__.resolvePositionMappings({ xToNote: true }, null);
-    expect(mappings[0].min).to.equal(0);
+    expect(mappings).to.have.length(0);
 
     const nullMappings = __test__.resolvePositionMappings(null, null);
     expect(nullMappings).to.have.length(0);
@@ -209,11 +215,11 @@ describe('MidiMapping helpers', function() {
     expect(customMappings).to.have.length(1);
 
     const mappings = __test__.resolvePositionMappings({
-      xToNote: true,
-      xNoteRange: { min: -5, max: 5 },
-      yToVelocity: true,
-      yToTimbre: true,
-      timbreRange: { min: 10, max: 20 }
+      mappings: [
+        { axis: 'x', target: 'note', min: -5, max: 5 },
+        { axis: 'y', target: 'velocity', min: 4, max: 2 },
+        { axis: 'y', target: 'timbre', min: 20, max: 10 }
+      ]
     }, { min: 2, max: 4 });
     expect(mappings).to.have.length(3);
 
diff --git a/test/midi/midi-mapping.01-midimapping.test.js b/test/midi/midi-mapping.01-midimapping.test.js
new file mode 100644
index 00000000..024183f3
--- /dev/null
+++ b/test/midi/midi-mapping.01-midimapping.test.js
@@ -0,0 +1,455 @@
+import { expect } from 'chai';
+import { MidiMapping } from '../../js/midi/MidiMapping.js';
+
+const basePosition = {
+  mappings: [],
+  viewPan: false
+};
+
+const normalizeConfig = (config = {}) => {
+  const hasPosition = Object.prototype.hasOwnProperty.call(config, 'position');
+  const position = hasPosition
+    ? (config.position === null ? null : { ...basePosition, ...config.position })
+    : basePosition;
+  return { ...config, position };
+};
+
+const makeMapping = (config) => new MidiMapping(normalizeConfig(config));
+const mapEvent = (config, event = { sfxId: 1 }, context = {}, density = 0, overrides) => {
+  const mapping = makeMapping(config);
+  return mapping.mapEvent(event, context, density, overrides);
+};
+
+const expectSpec = (spec, expected) => {
+  for (const [key, value] of Object.entries(expected)) {
+    expect(spec[key]).to.eql(value);
+  }
+};
+
+describe('MidiMapping 1', function() {
+  const mappingCases = [
+    {
+      name: 'applies position and density adjustments',
+      config: {
+        scale: { degrees: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11], root: 0 },
+        noteRange: { min: 60, max: 72 },
+        velocityRange: { min: 20, max: 100, default: 80 },
+        durationTicks: { default: 10, min: 2, max: 20 },
+        density: { windowTicks: 24, velocityBoost: 0.4, durationScale: 0.5 },
+        position: {
+          mappings: [
+            { axis: 'x', target: 'note', min: -12, max: 12, enabled: true },
+            { axis: 'y', target: 'velocity', min: 100, max: 20, enabled: true },
+            { axis: 'y', target: 'timbre', min: 100, max: 20, enabled: true }
+          ],
+          timbreRange: { min: 20, max: 100 }
+        }
+      },
+      event: { sfxId: 1, x: 100, y: 50 },
+      context: { levelWidth: 100, levelHeight: 100 },
+      density: 0.5,
+      expect: { note: 66, velocity: 72, durationTicks: 8, timbre: 60 }
+    },
+    {
+      name: 'applies note offsets to explicit notes',
+      config: {
+        noteRange: { min: 60, max: 72 },
+        position: {
+          mappings: [{ axis: 'x', target: 'note', min: 0, max: 12, enabled: true }]
+        },
+        sfx: { '1': { note: 60 } }
+      },
+      event: { sfxId: 1, x: 100 },
+      context: { levelWidth: 100, levelHeight: 100 },
+      expect: { note: 72 }
+    },
+    {
+      name: 'applies duration overrides from position mappings',
+      config: {
+        durationTicks: { default: 4, min: 1, max: 10 },
+        position: {
+          mappings: [{ axis: 'x', target: 'duration', min: 2, max: 6, enabled: true }]
+        }
+      },
+      event: { sfxId: 1, x: 50 },
+      context: { levelWidth: 100, levelHeight: 100 },
+      expect: { durationTicks: 4 }
+    },
+    {
+      name: 'applies pan overrides from position mappings',
+      config: {
+        position: {
+          mappings: [{ axis: 'x', target: 'pan', min: -127, max: 127, enabled: true }],
+          panRange: { min: -127, max: 127 }
+        }
+      },
+      event: { sfxId: 1, x: 100 },
+      context: { levelWidth: 100, levelHeight: 100 },
+      expect: { pan: 127 }
+    }
+  ];
+
+  for (const testCase of mappingCases) {
+    it(testCase.name, function() {
+      const spec = mapEvent(
+        testCase.config,
+        testCase.event,
+        testCase.context,
+        testCase.density,
+        testCase.overrides
+      );
+      expectSpec(spec, testCase.expect);
+    });
+  }
+
+  it('maps frequency to note and pitch bend', function() {
+    const freq = 440 * Math.pow(2, 0.5 / 12);
+    const mapping = makeMapping({
+      mpe: { pitchBendRange: { semitones: 2, cents: 0 } },
+      sfx: { '1': { frequencyHz: freq } }
+    });
+
+    const spec = mapping.mapEvent({ sfxId: 1 }, { levelWidth: 100, levelHeight: 100 }, 0);
+    const floatNote = 69 + 12 * Math.log2(freq / 440);
+    const baseNote = Math.round(floatNote);
+    const expectedBend = (floatNote - baseNote) / 2;
+
+    expect(spec.note).to.equal(baseNote);
+    expect(spec.pitchBend).to.be.closeTo(expectedBend, 0.01);
+    expect(spec.frequencyHz).to.equal(freq);
+  });
+
+  it('falls back to a safe pitch-bend range when semitones are invalid', function() {
+    const mapping = makeMapping({
+      mpe: { pitchBendRange: { semitones: 0, cents: 0 } },
+      sfx: { '1': { frequencyHz: 440 } }
+    });
+
+    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0);
+
+    expect(Number.isFinite(spec.pitchBend)).to.equal(true);
+    expect(spec.pitchBend).to.equal(0);
+  });
+
+  it('applies axisX/axisY mappings across targets', function() {
+    const spec = mapEvent({
+      velocityRange: { min: 1, max: 101, default: 1 },
+      durationTicks: { default: 5, min: 1, max: 10 },
+      position: {
+        mappings: [
+          { axisX: true, axisY: true, axisOp: 'sub', target: 'velocity', min: 1, max: 101, enabled: true },
+          { axisX: true, axisY: false, target: 'timbre', min: 0, max: 100, enabled: true },
+          { axisX: false, axisY: true, target: 'pan', min: -127, max: 127, enabled: true },
+          { axisX: false, axisY: false, target: 'duration', min: 1, max: 9, enabled: true }
+        ],
+        timbreRange: { min: 0, max: 100 },
+        panRange: { min: -127, max: 127 }
+      }
+    }, { sfxId: 1, x: 25, y: 75 }, { levelWidth: 100, levelHeight: 100 }, 0);
+
+    expectSpec(spec, {
+      velocity: 26,
+      timbre: 25,
+      pan: 64,
+      durationTicks: 5
+    });
+  });
+
+  it('skips axisX/axisY mappings when values are missing', function() {
+    const spec = mapEvent({
+      velocityRange: { min: 1, max: 127, default: 10 },
+      position: {
+        mappings: [{ axisX: true, axisY: true, axisOp: 'mul', target: 'velocity', min: 1, max: 127, enabled: true }]
+      }
+    }, { sfxId: 1, x: 50 }, { levelWidth: 100, levelHeight: null }, 0);
+
+    expect(spec.velocity).to.equal(10);
+  });
+
+  it('applies xy axis operations for mappings', function() {
+    const config = {
+      velocityRange: { min: 1, max: 101, default: 1 },
+      position: {
+        mappings: [
+          { axis: 'xy', axisOp: 'sub', target: 'velocity', min: 1, max: 101, enabled: true },
+          { axis: 'xy', axisOp: 'mul', target: 'timbre', min: 0, max: 100, enabled: true },
+          { axis: 'xy', axisOp: 'div', target: 'pan', min: -127, max: 127, enabled: true }
+        ],
+        timbreRange: { min: 0, max: 100 },
+        panRange: { min: -127, max: 127 }
+      }
+    };
+    const spec = mapEvent(config, { sfxId: 1, x: 25, y: 75 }, { levelWidth: 100, levelHeight: 100 }, 0);
+
+    expectSpec(spec, { velocity: 26, timbre: 19 });
+    expect(spec.pan).to.be.below(0);
+
+    const zeroSpec = mapEvent(config, { sfxId: 1, x: 25, y: 0 }, { levelWidth: 100, levelHeight: 100 }, 0);
+
+    expect(zeroSpec.pan).to.equal(127);
+  });
+
+  it('skips xy mappings when axis values are missing', function() {
+    const spec = mapEvent({
+      velocityRange: { min: 1, max: 127, default: 10 },
+      position: {
+        mappings: [{ axis: 'xy', target: 'velocity', min: 1, max: 127, enabled: true }]
+      }
+    }, { sfxId: 1, x: 50 }, { levelWidth: 100, levelHeight: null }, 0);
+
+    expect(spec.velocity).to.equal(10);
+  });
+
+  it('calculates pan from the view window', function() {
+    const mapping = makeMapping({
+      position: {
+        viewPan: true,
+        panRange: { min: -127, max: 127 },
+        panDeadZonePct: 0.1,
+        panOnscreenWeight: 1,
+        panOffscreenWeight: 0,
+        panOffscreenRange: 1
+      }
+    });
+
+    const center = mapping.mapEvent(
+      { sfxId: 1, x: 50 },
+      { viewRect: { x: 0, w: 100 } },
+      0
+    );
+    const right = mapping.mapEvent(
+      { sfxId: 1, x: 100 },
+      { viewRect: { x: 0, w: 100 } },
+      0
+    );
+
+    expect(center.pan).to.equal(0);
+    expect(right.pan).to.be.greaterThan(0);
+    expect(right.pan).to.be.at.most(127);
+  });
+
+  it('uses pan defaults when optional settings are missing', function() {
+    const spec = mapEvent(
+      { position: { viewPan: true } },
+      { sfxId: 1, x: 80 },
+      { viewRect: { x: 0, w: 100 }, levelWidth: 100 },
+      0
+    );
+
+    expect(spec.pan).to.be.at.least(-127);
+    expect(spec.pan).to.be.at.most(127);
+  });
+
+  it('falls back to view pan defaults when config values are null', function() {
+    const mapping = makeMapping({
+      position: {
+        viewPan: true,
+        panRange: null,
+        panDeadZonePct: null,
+        panOnscreenWeight: null,
+        panOffscreenWeight: null,
+        panOffscreenRange: null,
+      }
+    });
+
+    const spec = mapping.mapEvent(
+      { sfxId: 1, x: 80 },
+      { viewRect: { x: 0, w: 100 } },
+      0
+    );
+
+    expect(spec.pan).to.be.within(-127, 127);
+    expect(spec.pan).to.not.equal(0);
+  });
+
+  it('keeps view pan at zero when weights are zero', function() {
+    const mapping = makeMapping({
+      position: {
+        viewPan: true,
+        panRange: { min: -127, max: 127 },
+        panDeadZonePct: 0,
+        panOnscreenWeight: 0,
+        panOffscreenWeight: 0,
+        panOffscreenRange: 1,
+      }
+    });
+
+    const spec = mapping.mapEvent(
+      { sfxId: 1, x: 100 },
+      { viewRect: { x: 0, w: 50 } },
+      0
+    );
+
+    expect(spec.pan).to.equal(0);
+  });
+
+  it('uses default ranges when config values are null', function() {
+    const mapping = makeMapping({
+      noteRange: null,
+      velocityRange: null,
+      durationTicks: null,
+      density: null,
+      position: null,
+      noteDefaults: null,
+      envelope: null
+    });
+    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0);
+    expect(spec.note).to.be.a('number');
+    expect(spec.velocity).to.be.within(1, 127);
+  });
+
+  it('defaults axis and target when mappings omit them', function() {
+    const spec = mapEvent({
+      velocityRange: { min: 10, max: 20, default: 10 },
+      position: { mappings: [{ min: 10, max: 20, enabled: true }] }
+    }, { sfxId: 1, x: 100 }, { levelWidth: 100 }, 0);
+    expect(spec.velocity).to.equal(20);
+  });
+
+  it('uses default pitch bend range when mpe config is missing', function() {
+    const spec = mapEvent({
+      mpe: null,
+      sfx: { '1': { frequencyHz: 450 } }
+    }, { sfxId: 1 }, {}, 0);
+    expect(spec.pitchBend).to.be.a('number');
+  });
+
+  it('returns null for getSfxConfig when sfxId is null', function() {
+    const mapping = makeMapping();
+    expect(mapping.getSfxConfig(null)).to.equal(null);
+  });
+
+  it('keeps explicit velocity when position mappings are present', function() {
+    const spec = mapEvent({
+      velocityRange: { min: 10, max: 127, default: 80 },
+      position: { mappings: [{ axis: 'x', target: 'velocity', min: 10, max: 20, enabled: true }] }
+    }, { sfxId: 1, x: 100 }, { levelWidth: 100 }, 0, { velocity: 90 });
+
+    expect(spec.velocity).to.equal(90);
+  });
+
+  it('parses JSON input and handles invalid JSON', function() {
+    const valid = MidiMapping.fromJson('{"noteRange":{"min":50,"max":51}}');
+    expect(valid.config.noteRange.min).to.equal(50);
+    const direct = MidiMapping.fromJson({ noteRange: { min: 48, max: 49 } });
+    expect(direct.config.noteRange.max).to.equal(49);
+    const invalid = MidiMapping.fromJson('{bad');
+    expect(invalid.config).to.be.ok;
+  });
+
+  it('returns sfx config and skips disabled events', function() {
+    const mapping = new MidiMapping({
+      enabled: true,
+      sfx: { '2': { note: 61, disabled: true } }
+    });
+    expect(mapping.getSfxConfig(2).note).to.equal(61);
+    expect(mapping.getSfxConfig(3)).to.equal(null);
+    const spec = mapping.mapEvent({ sfxId: 2 }, {}, 0);
+    expect(spec).to.equal(null);
+
+    const disabled = new MidiMapping({ enabled: false });
+    expect(disabled.mapEvent({ sfxId: 1 }, {}, 0)).to.equal(null);
+  });
+
+  it('quantizes and clamps notes with custom scale', function() {
+    const mapping = makeMapping({
+      scale: { degrees: [], root: 0 },
+      noteRange: { min: 60, max: 61 }
+    });
+    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0);
+    expect(spec.note).to.equal(61);
+  });
+
+  it('covers position mapping targets and overrides', function() {
+    const mapping = new MidiMapping({
+      noteRange: { min: 60, max: 72 },
+      velocityRange: { min: 10, max: 120, default: 80 },
+      durationTicks: { min: 1, max: 10, default: 4 },
+      density: { velocityBoost: 0.5, durationScale: 0.5 },
+      position: {
+        mappings: [
+          { axis: 'x', target: 'note', max: 12, enabled: true },
+          { axis: 'x', target: 'velocity', enabled: true },
+          { axis: 'x', target: 'timbre', min: 0, max: 127, enabled: true },
+          { axis: 'x', target: 'pan', min: -50, max: 50, enabled: true },
+          { axis: 'x', target: 'duration', min: 2, max: 6, enabled: true },
+          { axis: 'x', target: 'pitchBend', min: -1, max: 1, enabled: true },
+          { axis: 'x', target: 'attack', min: 0, max: 2, enabled: true },
+          { axis: 'x', target: 'decay', min: 0, max: 2, enabled: true },
+          { axis: 'x', target: 'sustain', min: 0.5, max: 1.5, enabled: true },
+          { axis: 'x', target: 'release', min: 0, max: 2, enabled: true },
+          { axis: 'xy', target: 'velocity', min: 20, max: 100, enabled: true }
+        ],
+        timbreRange: { min: 0, max: 127 },
+        panRange: { min: -127, max: 127 },
+        viewPan: false
+      },
+      scale: { degrees: [0, 2, 4, 5, 7, 9, 11], root: 0 }
+    });
+
+    const spec = mapping.mapEvent(
+      { sfxId: 1, x: 50, y: 25, intensity: 1.2 },
+      { levelWidth: 100, levelHeight: 50 },
+      0.5,
+      { notes: [60, 64], envelope: { attack: 1.2 } }
+    );
+
+    expect(spec.notes).to.have.length(2);
+    expect(spec.pitchBend).to.be.a('number');
+    expect(spec.timbre).to.be.a('number');
+    expect(spec.pan).to.be.a('number');
+  });
+
+  it('skips mappings when axis values are missing', function() {
+    const spec = mapEvent({
+      position: {
+        mappings: [{ axis: 'y', target: 'velocity', min: 0, max: 127, enabled: true }]
+      }
+    }, { sfxId: 1, x: 10 }, { levelWidth: 100, levelHeight: null }, 0);
+    expect(spec.velocity).to.be.a('number');
+  });
+
+  it('handles null inputs for fromJson and mapEvent', function() {
+    const mapping = MidiMapping.fromJson(null);
+    expect(mapping.config).to.be.ok;
+    expect(mapping.mapEvent(null)).to.equal(null);
+  });
+
+  it('computes pan for offscreen events and keeps defaults', function() {
+    const spec = mapEvent({
+      position: {
+        viewPan: true,
+        panRange: { min: -127, max: 127 },
+        panDeadZonePct: 0.1,
+        panOnscreenWeight: 0.5,
+        panOffscreenWeight: 0.5,
+        panOffscreenRange: 1
+      }
+    }, { sfxId: 1, x: 300 }, { viewRect: { x: 0, w: 100 } }, 0);
+    expect(spec.pan).to.be.greaterThan(0);
+  });
+
+  it('builds chords and applies envelope settings', function() {
+    const mapping = makeMapping({
+      scale: { name: 'major', root: 0 },
+      noteDefaults: { octave: 4, degree: 0, chord: 'triad' },
+      envelope: { attack: 1.2, decay: 0.1, sustain: 1, release: 0.8 },
+      sfx: { '1': { degree: 0, chord: { type: 'triad' } } }
+    });
+
+    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0);
+    expect(spec.notes).to.have.length(3);
+    expect(spec.velocity).to.be.greaterThan(0);
+    expect(spec.releaseVelocity).to.be.greaterThan(0);
+  });
+
+  it('builds scale notes from degree without chords', function() {
+    const mapping = makeMapping({
+      scale: { degrees: [0, 2, 4, 5, 7, 9, 11], root: 0 },
+      noteRange: { min: 60, max: 72 },
+      sfx: { '1': { degree: 2, octave: 4 } }
+    });
+    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0);
+    expect(spec.note).to.be.within(60, 72);
+  });
+});
diff --git a/test/midi/midi-mapping.02-midimapping.test.js b/test/midi/midi-mapping.02-midimapping.test.js
new file mode 100644
index 00000000..c0b57469
--- /dev/null
+++ b/test/midi/midi-mapping.02-midimapping.test.js
@@ -0,0 +1,427 @@
+import { expect } from 'chai';
+import { MidiMapping } from '../../js/midi/MidiMapping.js';
+
+const basePosition = {
+  mappings: [],
+  viewPan: false
+};
+
+const normalizeConfig = (config = {}) => {
+  const hasPosition = Object.prototype.hasOwnProperty.call(config, 'position');
+  const position = hasPosition
+    ? (config.position === null ? null : { ...basePosition, ...config.position })
+    : basePosition;
+  return { ...config, position };
+};
+
+const makeMapping = (config) => new MidiMapping(normalizeConfig(config));
+const mapEvent = (config, event = { sfxId: 1 }, context = {}, density = 0, overrides) => {
+  const mapping = makeMapping(config);
+  return mapping.mapEvent(event, context, density, overrides);
+};
+
+const expectSpec = (spec, expected) => {
+  for (const [key, value] of Object.entries(expected)) {
+    expect(spec[key]).to.eql(value);
+  }
+};
+
+describe('MidiMapping 2', function() {
+  const mappingCases = [
+    {
+      name: 'applies position and density adjustments',
+      config: {
+        scale: { degrees: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11], root: 0 },
+        noteRange: { min: 60, max: 72 },
+        velocityRange: { min: 20, max: 100, default: 80 },
+        durationTicks: { default: 10, min: 2, max: 20 },
+        density: { windowTicks: 24, velocityBoost: 0.4, durationScale: 0.5 },
+        position: {
+          mappings: [
+            { axis: 'x', target: 'note', min: -12, max: 12, enabled: true },
+            { axis: 'y', target: 'velocity', min: 100, max: 20, enabled: true },
+            { axis: 'y', target: 'timbre', min: 100, max: 20, enabled: true }
+          ],
+          timbreRange: { min: 20, max: 100 }
+        }
+      },
+      event: { sfxId: 1, x: 100, y: 50 },
+      context: { levelWidth: 100, levelHeight: 100 },
+      density: 0.5,
+      expect: { note: 66, velocity: 72, durationTicks: 8, timbre: 60 }
+    },
+    {
+      name: 'applies note offsets to explicit notes',
+      config: {
+        noteRange: { min: 60, max: 72 },
+        position: {
+          mappings: [{ axis: 'x', target: 'note', min: 0, max: 12, enabled: true }]
+        },
+        sfx: { '1': { note: 60 } }
+      },
+      event: { sfxId: 1, x: 100 },
+      context: { levelWidth: 100, levelHeight: 100 },
+      expect: { note: 72 }
+    },
+    {
+      name: 'applies duration overrides from position mappings',
+      config: {
+        durationTicks: { default: 4, min: 1, max: 10 },
+        position: {
+          mappings: [{ axis: 'x', target: 'duration', min: 2, max: 6, enabled: true }]
+        }
+      },
+      event: { sfxId: 1, x: 50 },
+      context: { levelWidth: 100, levelHeight: 100 },
+      expect: { durationTicks: 4 }
+    },
+    {
+      name: 'applies pan overrides from position mappings',
+      config: {
+        position: {
+          mappings: [{ axis: 'x', target: 'pan', min: -127, max: 127, enabled: true }],
+          panRange: { min: -127, max: 127 }
+        }
+      },
+      event: { sfxId: 1, x: 100 },
+      context: { levelWidth: 100, levelHeight: 100 },
+      expect: { pan: 127 }
+    }
+  ];
+
+  for (const testCase of mappingCases) {
+    it(testCase.name, function() {
+      const spec = mapEvent(
+        testCase.config,
+        testCase.event,
+        testCase.context,
+        testCase.density,
+        testCase.overrides
+      );
+      expectSpec(spec, testCase.expect);
+    });
+  }
+
+  it('uses octave defaults when mapping degrees', function() {
+    const mapping = makeMapping({
+      noteDefaults: { degree: null, octave: null },
+      sfx: { '1': { degree: 2 }, '2': { degree: 2, octave: 5 } }
+    });
+
+    const fallback = mapping.mapEvent({ sfxId: 1 }, {}, 0);
+    expect(fallback.note).to.equal(50);
+
+    const explicit = mapping.mapEvent({ sfxId: 2 }, {}, 0);
+    expect(explicit.note).to.equal(62);
+  });
+
+  it('computes view pan using level width when viewRect is missing', function() {
+    const mapping = makeMapping({
+      position: {
+        viewPan: true,
+        panRange: { min: -127, max: 127 },
+        panDeadZonePct: 0.1,
+        panOnscreenWeight: 0.8,
+        panOffscreenWeight: 0.2,
+        panOffscreenRange: 1
+      }
+    });
+    const spec = mapping.mapEvent({ sfxId: 1, x: 75 }, { levelWidth: 100 }, 0);
+    expect(spec.pan).to.be.a('number');
+  });
+
+  it('keeps view pan null when view width is unavailable', function() {
+    const mapping = makeMapping({
+      position: {
+        viewPan: true,
+        panRange: null,
+        panDeadZonePct: null,
+        panOnscreenWeight: null,
+        panOffscreenWeight: null,
+        panOffscreenRange: null
+      }
+    });
+
+    const spec = mapping.mapEvent({ sfxId: 1, x: 10 }, {}, 0);
+    expect(spec.pan).to.equal(null);
+  });
+
+  it('falls back to the default scale when the name is unknown', function() {
+    const mapping = makeMapping({
+      scale: { name: 'mystery-scale', degrees: [] },
+      noteRange: { min: 60, max: 60 }
+    });
+
+    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0);
+    expect(spec.note).to.equal(60);
+  });
+
+  it('quantizes notes upward and downward to the scale', function() {
+    const mapping = makeMapping({
+      scale: { degrees: [0], root: 0 },
+      noteRange: { min: 0, max: 127 }
+    });
+
+    const up = mapping.mapEvent({ sfxId: 1 }, {}, 0, { note: 59 });
+    const down = mapping.mapEvent({ sfxId: 1 }, {}, 0, { note: 61 });
+    expect(up.note).to.equal(60);
+    expect(down.note).to.equal(60);
+  });
+
+  it('keeps notes unchanged when no scale degree is within range', function() {
+    const mapping = makeMapping({
+      scale: { degrees: [99], root: 0 },
+      noteRange: { min: 0, max: 127 }
+    });
+
+    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0, { note: 60 });
+    expect(spec.note).to.equal(60);
+  });
+
+  it('handles chord inversions', function() {
+    const mapping = new MidiMapping({
+      scale: { name: 'major', root: 0, degrees: [0, 2, 4, 5, 7, 9, 11] },
+      noteDefaults: { octave: 4, degree: 0, chord: 'triad' },
+      sfx: { '1': { degree: 0, chord: { type: 'triad', inversion: 1 } } }
+    });
+
+    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0);
+    expect(spec.notes).to.eql([52, 55, 60]);
+  });
+
+  it('maps degrees to scale notes when chord is not specified', function() {
+    const mapping = new MidiMapping({
+      scale: { name: 'major', root: 0, degrees: [0, 2, 4, 5, 7, 9, 11] },
+      noteDefaults: { octave: 4, degree: 0 },
+      sfx: { '1': { degree: 2, octave: 4 } }
+    });
+
+    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0);
+    expect(spec.note).to.equal(52);
+  });
+
+  it('applies note offsets to note arrays', function() {
+    const mapping = new MidiMapping({
+      noteRange: { min: 0, max: 127 },
+      position: {
+        mappings: [{ axis: 'x', target: 'note', min: 0, max: 12, enabled: true }],
+        viewPan: false
+      },
+      sfx: { '1': { notes: [60, 64, 67] } }
+    });
+
+    const spec = mapping.mapEvent(
+      { sfxId: 1, x: 100 },
+      { levelWidth: 100, levelHeight: 100 },
+      0
+    );
+
+    expect(spec.notes).to.eql([72, 76, 79]);
+    expect(spec.note).to.equal(72);
+  });
+
+  it('applies pitch bend and sustain overrides from position mappings', function() {
+    const spec = mapEvent({
+      position: {
+        mappings: [
+          { axis: 'x', target: 'pitchBend', min: -1, max: 1, enabled: true },
+          { axis: 'x', target: 'attack', min: 0, max: 2, enabled: true },
+          { axis: 'x', target: 'sustain', min: 0.5, max: 1.5, enabled: true },
+          { axis: 'x', target: 'unknown', min: 0, max: 1, enabled: true }
+        ]
+      }
+    }, { sfxId: 1, x: 100 }, { levelWidth: 100, levelHeight: 100 }, 0);
+
+    expect(spec.pitchBend).to.equal(1);
+    expect(spec.durationTicks).to.be.greaterThan(0);
+  });
+
+  it('applies intensity scaling and per-event envelope overrides', function() {
+    const spec = mapEvent({
+      velocityRange: { min: 10, max: 127, default: 50 },
+      envelope: { attack: 1, decay: 0, sustain: 1, release: 1 },
+      sfx: { '1': { envelope: { attack: 1.5, release: 0.5 } } }
+    }, { sfxId: 1, intensity: 1.2 }, {}, 0);
+    expect(spec.velocity).to.equal(90);
+    expect(spec.releaseVelocity).to.equal(45);
+  });
+
+  it('merges configs with overrides', function() {
+    const merged = MidiMapping.mergeConfigs(
+      { noteRange: { min: 40, max: 60 }, scale: { root: 1 } },
+      { noteRange: { max: 72 }, scale: { name: 'minor' } }
+    );
+    expect(merged.noteRange.min).to.equal(40);
+    expect(merged.noteRange.max).to.equal(72);
+    expect(merged.scale.root).to.equal(1);
+    expect(merged.scale.name).to.equal('minor');
+  });
+
+  it('handles null JSON input and array overrides', function() {
+    const fresh = MidiMapping.fromJson(null);
+    expect(fresh.config).to.be.ok;
+    const merged = MidiMapping.mergeConfigs(
+      { noteRange: { min: 40, max: 60 } },
+      { noteRange: [1, 2, 3] }
+    );
+    expect(merged.noteRange).to.eql([1, 2, 3]);
+  });
+
+  it('applies explicit position mappings', function() {
+    const mapping = makeMapping({
+      position: {
+        mappings: [
+          { axis: 'x', target: 'note', min: -12, max: 12, enabled: true },
+          { axis: 'y', target: 'velocity', min: 110, max: 10, enabled: true },
+          { axis: 'y', target: 'timbre', min: 127, max: 0, enabled: true }
+        ]
+      },
+      velocityRange: { min: 10, max: 110, default: 80 }
+    });
+    const spec = mapping.mapEvent(
+      { sfxId: 1, x: 100, y: 50 },
+      { levelWidth: 100, levelHeight: 100 },
+      0
+    );
+    expect(spec.timbre).to.be.within(0, 127);
+  });
+
+  it('applies mapping targets and skips missing axis values', function() {
+    const mapping = new MidiMapping({
+      noteRange: { min: 60, max: 72 },
+      velocityRange: { min: 1, max: 127, default: 60 },
+      durationTicks: { default: 4, min: 1, max: 10 },
+      position: {
+        mappings: [
+          { axis: 'x', target: 'note', min: -12, max: 12, enabled: true },
+          { axis: 'x', target: 'velocity', min: 10, max: 100, enabled: true },
+          { axis: 'y', target: 'timbre', min: 20, max: 80, enabled: true },
+          { axis: 'x', target: 'pan', min: -100, max: 100, enabled: true },
+          { axis: 'y', target: 'duration', min: 2, max: 6, enabled: true },
+          { axis: 'x', target: 'pitchBend', min: -1, max: 1, enabled: true },
+          { axis: 'x', target: 'attack', min: 0, max: 2, enabled: true },
+          { axis: 'x', target: 'decay', min: 0, max: 2, enabled: true },
+          { axis: 'y', target: 'sustain', min: 0.5, max: 1.5, enabled: true },
+          { axis: 'y', target: 'release', min: 0, max: 2, enabled: true },
+          { axis: 'x', enabled: true }
+        ],
+        viewPan: false
+      }
+    });
+    const spec = mapping.mapEvent(
+      { sfxId: 1, x: 50, y: 50 },
+      { levelWidth: 100, levelHeight: 100 },
+      0
+    );
+    expect(spec.pan).to.not.equal(null);
+    expect(spec.pitchBend).to.be.a('number');
+
+    const missingAxis = mapping.mapEvent(
+      { sfxId: 1, x: 50 },
+      { levelWidth: 100 },
+      0
+    );
+    expect(missingAxis.velocity).to.be.a('number');
+  });
+
+  it('quantizes notes already in scale and clamps out-of-range notes', function() {
+    const mapping = makeMapping({
+      scale: { degrees: [0, 4, 7], root: 0 },
+      noteRange: { min: 60, max: 72 },
+      sfx: { '1': { note: 64 } }
+    });
+    const inScale = mapping.mapEvent({ sfxId: 1 }, {}, 0);
+    expect(inScale.note).to.equal(64);
+
+    const clamped = mapping.mapEvent({ sfxId: 1 }, {}, 0, { note: 30 });
+    expect(clamped.note).to.equal(67);
+  });
+
+  it('builds sixth chords and falls back to triads', function() {
+    const mapping = new MidiMapping({
+      scale: { name: 'major', root: 0, degrees: [0, 2, 4, 5, 7, 9, 11] },
+      noteDefaults: { octave: 4, degree: 0, chord: 'triad' }
+    });
+    const sixth = mapping.mapEvent({ sfxId: 1 }, {}, 0, { degree: 0, chord: { type: 'sixth' } });
+    expect(sixth.notes).to.have.length(4);
+    const fallback = mapping.mapEvent({ sfxId: 1 }, {}, 0, { degree: 0, chord: { type: 'unknown' } });
+    expect(fallback.notes).to.have.length(3);
+  });
+
+  it('respects explicit values while applying pitch bend overrides', function() {
+    const mapping = new MidiMapping({
+      position: {
+        mappings: [
+          { axis: 'x', target: 'pitchBend', min: -1, max: 1, enabled: true },
+          { axis: 'x', target: 'velocity', min: 10, max: 100, enabled: true },
+          { axis: 'x', target: 'duration', min: 2, max: 6, enabled: true }
+        ],
+        viewPan: false
+      },
+      velocityRange: { min: 1, max: 127, default: 50 },
+      durationTicks: { default: 4, min: 1, max: 10 }
+    });
+
+    const specFreq = mapping.mapEvent(
+      { sfxId: 1, x: 50 },
+      { levelWidth: 100, levelHeight: 100 },
+      0,
+      { frequencyHz: 440, velocity: 90, durationTicks: 8 }
+    );
+    expect(specFreq.pitchBend).to.equal(0);
+    expect(specFreq.velocity).to.equal(90);
+    expect(specFreq.durationTicks).to.equal(8);
+
+    const specOverride = mapping.mapEvent(
+      { sfxId: 1, x: 100 },
+      { levelWidth: 100, levelHeight: 100 },
+      0
+    );
+    expect(specOverride.pitchBend).to.equal(1);
+  });
+
+  it('skips chord mapping when a note is already provided', function() {
+    const mapping = makeMapping({
+      scale: { name: 'major', root: 0, degrees: [0, 2, 4, 5, 7, 9, 11] },
+      noteRange: { min: 60, max: 72 }
+    });
+    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0, { chord: { type: 'triad' }, note: 65 });
+    expect(spec.notes).to.equal(null);
+    expect(spec.note).to.equal(65);
+  });
+
+  it('handles view pan dead zones and empty widths', function() {
+    const mapping = makeMapping({
+      position: {
+        viewPan: true,
+        panRange: { min: -127, max: 127 },
+        panDeadZonePct: 0.5,
+        panOnscreenWeight: 1,
+        panOffscreenWeight: 0,
+        panOffscreenRange: 1
+      }
+    });
+    const center = mapping.mapEvent({ sfxId: 1, x: 50 }, { viewRect: { x: 0, w: 100 } }, 0);
+    expect(center.pan).to.equal(0);
+
+    const zero = mapping.mapEvent({ sfxId: 1, x: 10 }, { viewRect: { x: 0, w: 0 } }, 0);
+    expect(zero.pan).to.equal(null);
+  });
+
+  it('returns null for missing events and ignores non-plain envelopes', function() {
+    const mapping = makeMapping();
+    expect(mapping.mapEvent(null, {}, 0)).to.equal(null);
+
+    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0, { envelope: [] });
+    expect(spec.velocity).to.be.a('number');
+  });
+
+  it('mapEvent uses defaults and override sfx', function() {
+    const mapping = makeMapping();
+    const spec = mapping.mapEvent({ sfxId: 1 });
+    expect(spec.note).to.be.a('number');
+
+    const overrideSpec = mapping.mapEvent({ sfxId: 1 }, undefined, undefined, { note: 70 });
+    expect(overrideSpec.note).to.equal(70);
+  });
+});
diff --git a/test/midi/midi-mapping.03-midimapping.test.js b/test/midi/midi-mapping.03-midimapping.test.js
new file mode 100644
index 00000000..f09a9352
--- /dev/null
+++ b/test/midi/midi-mapping.03-midimapping.test.js
@@ -0,0 +1,400 @@
+import { expect } from 'chai';
+import { MidiMapping } from '../../js/midi/MidiMapping.js';
+
+const basePosition = {
+  mappings: [],
+  viewPan: false
+};
+
+const normalizeConfig = (config = {}) => {
+  const hasPosition = Object.prototype.hasOwnProperty.call(config, 'position');
+  const position = hasPosition
+    ? (config.position === null ? null : { ...basePosition, ...config.position })
+    : basePosition;
+  return { ...config, position };
+};
+
+const makeMapping = (config) => new MidiMapping(normalizeConfig(config));
+const mapEvent = (config, event = { sfxId: 1 }, context = {}, density = 0, overrides) => {
+  const mapping = makeMapping(config);
+  return mapping.mapEvent(event, context, density, overrides);
+};
+
+const expectSpec = (spec, expected) => {
+  for (const [key, value] of Object.entries(expected)) {
+    expect(spec[key]).to.eql(value);
+  }
+};
+
+describe('MidiMapping 3', function() {
+  const mappingCases = [
+    {
+      name: 'applies position and density adjustments',
+      config: {
+        scale: { degrees: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11], root: 0 },
+        noteRange: { min: 60, max: 72 },
+        velocityRange: { min: 20, max: 100, default: 80 },
+        durationTicks: { default: 10, min: 2, max: 20 },
+        density: { windowTicks: 24, velocityBoost: 0.4, durationScale: 0.5 },
+        position: {
+          mappings: [
+            { axis: 'x', target: 'note', min: -12, max: 12, enabled: true },
+            { axis: 'y', target: 'velocity', min: 100, max: 20, enabled: true },
+            { axis: 'y', target: 'timbre', min: 100, max: 20, enabled: true }
+          ],
+          timbreRange: { min: 20, max: 100 }
+        }
+      },
+      event: { sfxId: 1, x: 100, y: 50 },
+      context: { levelWidth: 100, levelHeight: 100 },
+      density: 0.5,
+      expect: { note: 66, velocity: 72, durationTicks: 8, timbre: 60 }
+    },
+    {
+      name: 'applies note offsets to explicit notes',
+      config: {
+        noteRange: { min: 60, max: 72 },
+        position: {
+          mappings: [{ axis: 'x', target: 'note', min: 0, max: 12, enabled: true }]
+        },
+        sfx: { '1': { note: 60 } }
+      },
+      event: { sfxId: 1, x: 100 },
+      context: { levelWidth: 100, levelHeight: 100 },
+      expect: { note: 72 }
+    },
+    {
+      name: 'applies duration overrides from position mappings',
+      config: {
+        durationTicks: { default: 4, min: 1, max: 10 },
+        position: {
+          mappings: [{ axis: 'x', target: 'duration', min: 2, max: 6, enabled: true }]
+        }
+      },
+      event: { sfxId: 1, x: 50 },
+      context: { levelWidth: 100, levelHeight: 100 },
+      expect: { durationTicks: 4 }
+    },
+    {
+      name: 'applies pan overrides from position mappings',
+      config: {
+        position: {
+          mappings: [{ axis: 'x', target: 'pan', min: -127, max: 127, enabled: true }],
+          panRange: { min: -127, max: 127 }
+        }
+      },
+      event: { sfxId: 1, x: 100 },
+      context: { levelWidth: 100, levelHeight: 100 },
+      expect: { pan: 127 }
+    }
+  ];
+
+  for (const testCase of mappingCases) {
+    it(testCase.name, function() {
+      const spec = mapEvent(
+        testCase.config,
+        testCase.event,
+        testCase.context,
+        testCase.density,
+        testCase.overrides
+      );
+      expectSpec(spec, testCase.expect);
+    });
+  }
+
+  it('mapEvent applies mapping targets and disabled entries', function() {
+    const mapping = new MidiMapping({
+      noteRange: { min: 60, max: 72 },
+      velocityRange: { min: 1, max: 127, default: 64 },
+      durationTicks: { default: 4, min: 1, max: 10 },
+      density: { windowTicks: 10, velocityBoost: 0.1, durationScale: 0.1 },
+      position: {
+        mappings: [
+          { axis: 'x', target: 'note', min: -12, max: 12, enabled: true },
+          { axis: 'x', target: 'velocity', min: 10, max: 100, enabled: true },
+          { axis: 'y', target: 'timbre', min: 20, max: 80, enabled: true },
+          { axis: 'x', target: 'pan', min: -50, max: 50, enabled: true },
+          { axis: 'x', target: 'duration', min: 2, max: 6, enabled: true },
+          { axis: 'x', target: 'pitchBend', min: -1, max: 1, enabled: true },
+          { axis: 'x', target: 'attack', min: 0, max: 2, enabled: true },
+          { axis: 'y', target: 'sustain', min: 0.5, max: 1.5, enabled: true },
+          { axis: 'x', target: 'unknown', enabled: true },
+          { axis: 'y', target: 'velocity', enabled: false }
+        ],
+        viewPan: false,
+        timbreRange: { min: 0, max: 127 },
+        panRange: { min: -50, max: 50 }
+      }
+    });
+
+    const spec = mapping.mapEvent(
+      { sfxId: 1, x: 100, y: 50, intensity: 1.5 },
+      { levelWidth: 100, levelHeight: 100 },
+      0.5
+    );
+    expect(spec.timbre).to.be.within(0, 127);
+    expect(spec.pan).to.be.within(-50, 50);
+    expect(spec.durationTicks).to.be.at.least(1);
+
+    const missingAxis = mapping.mapEvent(
+      { sfxId: 1, x: 50 },
+      { levelWidth: 100 },
+      0
+    );
+    expect(missingAxis.timbre).to.equal(null);
+  });
+
+  it('mapEvent offsets note arrays and pitch bend overrides', function() {
+    const mapping = new MidiMapping({
+      noteRange: { min: 60, max: 72 },
+      velocityRange: { min: 1, max: 127, default: 60 },
+      position: {
+        mappings: [
+          { axis: 'x', target: 'note', min: 0, max: 12, enabled: true },
+          { axis: 'x', target: 'pitchBend', min: -1, max: 1, enabled: true }
+        ],
+        viewPan: false
+      },
+      sfx: { '1': { notes: [60, 64] } }
+    });
+
+    const spec = mapping.mapEvent(
+      { sfxId: 1, x: 100 },
+      { levelWidth: 100, levelHeight: 100 },
+      0
+    );
+    expect(spec.notes[0]).to.equal(72);
+    expect(spec.pitchBend).to.equal(1);
+  });
+
+  it('mapEvent applies envelope defaults and view pan fallbacks', function() {
+    const mapping = new MidiMapping({
+      envelope: { attack: NaN, decay: NaN, sustain: NaN, release: NaN },
+      position: {
+        mappings: [],
+        viewPan: true,
+        panDeadZonePct: 1,
+        panOnscreenWeight: 1,
+        panOffscreenWeight: 0,
+        panOffscreenRange: 1
+      }
+    });
+    const spec = mapping.mapEvent(
+      { sfxId: 1, x: 50 },
+      { viewRect: { x: 0, w: 100 } },
+      0,
+      { envelope: { attack: NaN } }
+    );
+    expect(spec.pan).to.equal(0);
+    expect(spec.releaseVelocity).to.be.a('number');
+  });
+
+  it('mapEvent returns null for missing events and uses defaults', function() {
+    const mapping = new MidiMapping();
+    expect(mapping.mapEvent(null, {}, 0)).to.equal(null);
+    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0);
+    expect(spec.note).to.be.a('number');
+  });
+
+  it('mapEvent handles overrides and unknown mapping targets', function() {
+    const mapping = new MidiMapping({
+      position: {
+        mappings: [
+          { axis: 'y', target: 'unknown', enabled: true },
+          { axis: 'y', target: 'velocity', enabled: false }
+        ],
+        viewPan: false
+      }
+    });
+    const spec = mapping.mapEvent(
+      { sfxId: 1, y: 50 },
+      { levelWidth: 100, levelHeight: 100 },
+      0,
+      { note: 60, velocity: 90 }
+    );
+    expect(spec.velocity).to.equal(90);
+  });
+
+  it('mapEvent uses pitch bend overrides without frequency data', function() {
+    const mapping = new MidiMapping({
+      position: {
+        mappings: [{ axis: 'x', target: 'pitchBend', min: -1, max: 1, enabled: true }],
+        viewPan: false
+      }
+    });
+    const spec = mapping.mapEvent(
+      { sfxId: 1, x: 100 },
+      { levelWidth: 100, levelHeight: 100 },
+      0,
+      { note: 60 }
+    );
+    expect(spec.pitchBend).to.equal(1);
+  });
+
+  it('uses note defaults for chord mapping when degree is missing', function() {
+    const mapping = new MidiMapping({
+      scale: { name: 'major', root: 0 },
+      noteDefaults: { degree: 1, octave: 5, chord: 'seventh' },
+      sfx: { '1': { chord: {} } }
+    });
+
+    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0);
+    expect(spec.notes).to.have.length(4);
+    expect(spec.note).to.equal(spec.notes[0]);
+  });
+
+  it('computes view pan from level width when no view rect is present', function() {
+    const mapping = makeMapping({
+      position: {
+        viewPan: true,
+        panRange: { min: -127, max: 127 },
+        panDeadZonePct: 0,
+        panOnscreenWeight: 1,
+        panOffscreenWeight: 0,
+        panOffscreenRange: 1
+      }
+    });
+
+    const spec = mapping.mapEvent({ sfxId: 1, x: 0 }, { levelWidth: 100 }, 0);
+    expect(spec.pan).to.be.lessThan(0);
+  });
+
+  it('builds chord defaults when note defaults are null', function() {
+    const mapping = makeMapping({
+      scale: { name: 'custom', root: 1, degrees: [0, 3, 7] },
+      noteDefaults: { degree: null, octave: null, chord: null },
+      noteRange: { min: 0, max: 127 },
+      sfx: { '1': { chord: {}, note: null } }
+    });
+
+    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0);
+    expect(spec.notes).to.have.length(3);
+    expect(spec.note).to.equal(49);
+  });
+
+  it('applies position mappings with null range defaults', function() {
+    const mapping = new MidiMapping({
+      noteRange: { min: 60, max: 72 },
+      velocityRange: { min: null, max: null, default: 80 },
+      durationTicks: { min: null, max: null, default: 4 },
+      position: {
+        mappings: [
+          { axis: 'x', target: 'note', enabled: true },
+          { axis: 'x', target: 'velocity', enabled: true },
+          { axis: 'y', target: 'timbre', enabled: true },
+          { axis: 'x', target: 'pan', enabled: true },
+          { axis: 'y', target: 'duration', enabled: true }
+        ],
+        xNoteRange: null,
+        timbreRange: null,
+        panRange: null,
+        viewPan: false
+      },
+      sfx: { '1': { note: 60 } }
+    });
+
+    const spec = mapping.mapEvent(
+      { sfxId: 1, x: 50, y: 50 },
+      { levelWidth: 100, levelHeight: 100 },
+      0
+    );
+
+    expect(spec.velocity).to.be.within(1, 127);
+    expect(spec.timbre).to.be.within(0, 127);
+    expect(spec.pan).to.be.within(-127, 127);
+    expect(spec.durationTicks).to.be.within(1, 999);
+  });
+
+  it('computes view pan fallbacks with view rect weights', function() {
+    const mapping = makeMapping({
+      position: {
+        viewPan: true,
+        panRange: { min: 0, max: 0 },
+        panDeadZonePct: 1,
+        panOnscreenWeight: 0,
+        panOffscreenWeight: 0,
+        panOffscreenRange: null
+      },
+      sfx: { '1': { note: 60 } }
+    });
+
+    const context = { viewRect: { x: 20, w: 100 }, levelWidth: 200 };
+    const centered = mapping.mapEvent({ sfxId: 1, x: 70 }, context, 0);
+    const offscreen = mapping.mapEvent({ sfxId: 1, x: 170 }, context, 0);
+    expect(centered.pan).to.equal(0);
+    expect(offscreen.pan).to.equal(0);
+  });
+
+  it('merges configs with default fallbacks', function() {
+    const merged = MidiMapping.mergeConfigs(null, null);
+    expect(merged.scale.name).to.be.a('string');
+  });
+
+  it('mergeConfigs preserves base when override is null', function() {
+    const merged = MidiMapping.mergeConfigs({ timing: { bpmBase: 90 } }, null);
+    expect(merged.timing.bpmBase).to.equal(90);
+  });
+
+  it('clamps notes when the note range min is null', function() {
+    const mapping = makeMapping({
+      noteRange: { min: null, max: 60 },
+      sfx: { '1': { note: 80 } }
+    });
+
+    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0);
+    expect(spec.note).to.equal(56);
+  });
+
+  it('skips chord mapping when a note is already set', function() {
+    const mapping = makeMapping({
+      scale: { name: 'major', root: 0 },
+      noteRange: { min: 0, max: 127 },
+      sfx: { '1': { note: 62, chord: { type: 'seventh' } } }
+    });
+
+    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0);
+    expect(spec.notes).to.equal(null);
+    expect(spec.note).to.equal(62);
+  });
+
+  it('uses fallback velocity and duration defaults when config values are null', function() {
+    const mapping = makeMapping({
+      velocityRange: { min: null, max: null, default: null },
+      durationTicks: { min: null, max: null, default: null }
+    });
+
+    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0);
+    expect(spec.velocity).to.equal(127);
+    expect(spec.durationTicks).to.equal(6);
+  });
+
+  it('uses scale degrees with a null root', function() {
+    const mapping = makeMapping({
+      scale: { name: 'custom', degrees: [0, 2, 4], root: null },
+      noteDefaults: { degree: 0, octave: 4 },
+      sfx: { '1': { degree: 1 } }
+    });
+
+    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0);
+    expect(spec.note).to.equal(50);
+  });
+
+  it('carries track voice budgets into mapped event specs', function() {
+    const mapping = makeMapping({
+      sfx: { '1': { note: 60, trackId: 'lead', voiceBudget: 3 } }
+    });
+
+    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0);
+    expect(spec).to.include({ trackId: 'lead', voiceBudget: 3 });
+  });
+
+  it('defaults axisOp to add when not provided', function() {
+    const spec = mapEvent({
+      velocityRange: { min: 0, max: 100, default: 0 },
+      position: {
+        mappings: [{ axis: 'xy', target: 'velocity', min: 0, max: 100, enabled: true }]
+      }
+    }, { sfxId: 1, x: 50, y: 50 }, { levelWidth: 100, levelHeight: 100 }, 0);
+    expect(spec.velocity).to.equal(50);
+  });
+});
diff --git a/test/midi/midi-mapping.test.js b/test/midi/midi-mapping.test.js
deleted file mode 100644
index 305d301c..00000000
--- a/test/midi/midi-mapping.test.js
+++ /dev/null
@@ -1,1068 +0,0 @@
-import { expect } from 'chai';
-import { MidiMapping } from '../../js/midi/MidiMapping.js';
-
-const basePosition = {
-  xToNote: false,
-  yToVelocity: false,
-  yToTimbre: false,
-  viewPan: false
-};
-
-const normalizeConfig = (config = {}) => {
-  const hasPosition = Object.prototype.hasOwnProperty.call(config, 'position');
-  const position = hasPosition
-    ? (config.position === null ? null : { ...basePosition, ...config.position })
-    : basePosition;
-  return { ...config, position };
-};
-
-const makeMapping = (config) => new MidiMapping(normalizeConfig(config));
-const mapEvent = (config, event = { sfxId: 1 }, context = {}, density = 0, overrides) => {
-  const mapping = makeMapping(config);
-  return mapping.mapEvent(event, context, density, overrides);
-};
-
-const expectSpec = (spec, expected) => {
-  for (const [key, value] of Object.entries(expected)) {
-    expect(spec[key]).to.eql(value);
-  }
-};
-
-describe('MidiMapping', function() {
-  it('maps frequency to note and pitch bend', function() {
-    const freq = 440 * Math.pow(2, 0.5 / 12);
-    const mapping = makeMapping({
-      mpe: { pitchBendRange: { semitones: 2, cents: 0 } },
-      sfx: { '1': { frequencyHz: freq } }
-    });
-
-    const spec = mapping.mapEvent({ sfxId: 1 }, { levelWidth: 100, levelHeight: 100 }, 0);
-    const floatNote = 69 + 12 * Math.log2(freq / 440);
-    const baseNote = Math.round(floatNote);
-    const expectedBend = (floatNote - baseNote) / 2;
-
-    expect(spec.note).to.equal(baseNote);
-    expect(spec.pitchBend).to.be.closeTo(expectedBend, 0.01);
-    expect(spec.frequencyHz).to.equal(freq);
-  });
-
-  const mappingCases = [
-    {
-      name: 'applies position and density adjustments',
-      config: {
-        scale: { degrees: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11], root: 0 },
-        noteRange: { min: 60, max: 72 },
-        velocityRange: { min: 20, max: 100, default: 80 },
-        durationTicks: { default: 10, min: 2, max: 20 },
-        density: { windowTicks: 24, velocityBoost: 0.4, durationScale: 0.5 },
-        position: {
-          xToNote: true,
-          xNoteRange: { min: -12, max: 12 },
-          yToVelocity: true,
-          yToTimbre: true,
-          timbreRange: { min: 20, max: 100 }
-        }
-      },
-      event: { sfxId: 1, x: 100, y: 50 },
-      context: { levelWidth: 100, levelHeight: 100 },
-      density: 0.5,
-      expect: { note: 66, velocity: 72, durationTicks: 8, timbre: 60 }
-    },
-    {
-      name: 'applies note offsets to explicit notes',
-      config: {
-        noteRange: { min: 60, max: 72 },
-        position: {
-          mappings: [{ axis: 'x', target: 'note', min: 0, max: 12, enabled: true }]
-        },
-        sfx: { '1': { note: 60 } }
-      },
-      event: { sfxId: 1, x: 100 },
-      context: { levelWidth: 100, levelHeight: 100 },
-      expect: { note: 72 }
-    },
-    {
-      name: 'applies duration overrides from position mappings',
-      config: {
-        durationTicks: { default: 4, min: 1, max: 10 },
-        position: {
-          mappings: [{ axis: 'x', target: 'duration', min: 2, max: 6, enabled: true }]
-        }
-      },
-      event: { sfxId: 1, x: 50 },
-      context: { levelWidth: 100, levelHeight: 100 },
-      expect: { durationTicks: 4 }
-    },
-    {
-      name: 'applies pan overrides from position mappings',
-      config: {
-        position: {
-          mappings: [{ axis: 'x', target: 'pan', min: -127, max: 127, enabled: true }],
-          panRange: { min: -127, max: 127 }
-        }
-      },
-      event: { sfxId: 1, x: 100 },
-      context: { levelWidth: 100, levelHeight: 100 },
-      expect: { pan: 127 }
-    }
-  ];
-
-  for (const testCase of mappingCases) {
-    it(testCase.name, function() {
-      const spec = mapEvent(
-        testCase.config,
-        testCase.event,
-        testCase.context,
-        testCase.density,
-        testCase.overrides
-      );
-      expectSpec(spec, testCase.expect);
-    });
-  }
-
-  it('applies axisX/axisY mappings across targets', function() {
-    const spec = mapEvent({
-      velocityRange: { min: 1, max: 101, default: 1 },
-      durationTicks: { default: 5, min: 1, max: 10 },
-      position: {
-        mappings: [
-          { axisX: true, axisY: true, axisOp: 'sub', target: 'velocity', min: 1, max: 101, enabled: true },
-          { axisX: true, axisY: false, target: 'timbre', min: 0, max: 100, enabled: true },
-          { axisX: false, axisY: true, target: 'pan', min: -127, max: 127, enabled: true },
-          { axisX: false, axisY: false, target: 'duration', min: 1, max: 9, enabled: true }
-        ],
-        timbreRange: { min: 0, max: 100 },
-        panRange: { min: -127, max: 127 }
-      }
-    }, { sfxId: 1, x: 25, y: 75 }, { levelWidth: 100, levelHeight: 100 }, 0);
-
-    expectSpec(spec, {
-      velocity: 26,
-      timbre: 25,
-      pan: 64,
-      durationTicks: 5
-    });
-  });
-
-  it('skips axisX/axisY mappings when values are missing', function() {
-    const spec = mapEvent({
-      velocityRange: { min: 1, max: 127, default: 10 },
-      position: {
-        mappings: [{ axisX: true, axisY: true, axisOp: 'mul', target: 'velocity', min: 1, max: 127, enabled: true }]
-      }
-    }, { sfxId: 1, x: 50 }, { levelWidth: 100, levelHeight: null }, 0);
-
-    expect(spec.velocity).to.equal(10);
-  });
-
-  it('applies xy axis operations for mappings', function() {
-    const config = {
-      velocityRange: { min: 1, max: 101, default: 1 },
-      position: {
-        mappings: [
-          { axis: 'xy', axisOp: 'sub', target: 'velocity', min: 1, max: 101, enabled: true },
-          { axis: 'xy', axisOp: 'mul', target: 'timbre', min: 0, max: 100, enabled: true },
-          { axis: 'xy', axisOp: 'div', target: 'pan', min: -127, max: 127, enabled: true }
-        ],
-        timbreRange: { min: 0, max: 100 },
-        panRange: { min: -127, max: 127 }
-      }
-    };
-    const spec = mapEvent(config, { sfxId: 1, x: 25, y: 75 }, { levelWidth: 100, levelHeight: 100 }, 0);
-
-    expectSpec(spec, { velocity: 26, timbre: 19 });
-    expect(spec.pan).to.be.below(0);
-
-    const zeroSpec = mapEvent(config, { sfxId: 1, x: 25, y: 0 }, { levelWidth: 100, levelHeight: 100 }, 0);
-
-    expect(zeroSpec.pan).to.equal(127);
-  });
-
-  it('skips xy mappings when axis values are missing', function() {
-    const spec = mapEvent({
-      velocityRange: { min: 1, max: 127, default: 10 },
-      position: {
-        mappings: [{ axis: 'xy', target: 'velocity', min: 1, max: 127, enabled: true }]
-      }
-    }, { sfxId: 1, x: 50 }, { levelWidth: 100, levelHeight: null }, 0);
-
-    expect(spec.velocity).to.equal(10);
-  });
-
-  it('calculates pan from the view window', function() {
-    const mapping = makeMapping({
-      position: {
-        viewPan: true,
-        panRange: { min: -127, max: 127 },
-        panDeadZonePct: 0.1,
-        panOnscreenWeight: 1,
-        panOffscreenWeight: 0,
-        panOffscreenRange: 1
-      }
-    });
-
-    const center = mapping.mapEvent(
-      { sfxId: 1, x: 50 },
-      { viewRect: { x: 0, w: 100 } },
-      0
-    );
-    const right = mapping.mapEvent(
-      { sfxId: 1, x: 100 },
-      { viewRect: { x: 0, w: 100 } },
-      0
-    );
-
-    expect(center.pan).to.equal(0);
-    expect(right.pan).to.be.greaterThan(0);
-    expect(right.pan).to.be.at.most(127);
-  });
-
-  it('uses pan defaults when optional settings are missing', function() {
-    const spec = mapEvent(
-      { position: { viewPan: true } },
-      { sfxId: 1, x: 80 },
-      { viewRect: { x: 0, w: 100 }, levelWidth: 100 },
-      0
-    );
-
-    expect(spec.pan).to.be.at.least(-127);
-    expect(spec.pan).to.be.at.most(127);
-  });
-
-  it('falls back to view pan defaults when config values are null', function() {
-    const mapping = makeMapping({
-      position: {
-        viewPan: true,
-        panRange: null,
-        panDeadZonePct: null,
-        panOnscreenWeight: null,
-        panOffscreenWeight: null,
-        panOffscreenRange: null,
-      }
-    });
-
-    const spec = mapping.mapEvent(
-      { sfxId: 1, x: 80 },
-      { viewRect: { x: 0, w: 100 } },
-      0
-    );
-
-    expect(spec.pan).to.be.within(-127, 127);
-    expect(spec.pan).to.not.equal(0);
-  });
-
-  it('keeps view pan at zero when weights are zero', function() {
-    const mapping = makeMapping({
-      position: {
-        viewPan: true,
-        panRange: { min: -127, max: 127 },
-        panDeadZonePct: 0,
-        panOnscreenWeight: 0,
-        panOffscreenWeight: 0,
-        panOffscreenRange: 1,
-      }
-    });
-
-    const spec = mapping.mapEvent(
-      { sfxId: 1, x: 100 },
-      { viewRect: { x: 0, w: 50 } },
-      0
-    );
-
-    expect(spec.pan).to.equal(0);
-  });
-
-  it('uses default ranges when config values are null', function() {
-    const mapping = makeMapping({
-      noteRange: null,
-      velocityRange: null,
-      durationTicks: null,
-      density: null,
-      position: null,
-      noteDefaults: null,
-      envelope: null
-    });
-    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0);
-    expect(spec.note).to.be.a('number');
-    expect(spec.velocity).to.be.within(1, 127);
-  });
-
-  it('defaults axis and target when mappings omit them', function() {
-    const spec = mapEvent({
-      velocityRange: { min: 10, max: 20, default: 10 },
-      position: { mappings: [{ min: 10, max: 20, enabled: true }] }
-    }, { sfxId: 1, x: 100 }, { levelWidth: 100 }, 0);
-    expect(spec.velocity).to.equal(20);
-  });
-
-  it('uses default pitch bend range when mpe config is missing', function() {
-    const spec = mapEvent({
-      mpe: null,
-      sfx: { '1': { frequencyHz: 450 } }
-    }, { sfxId: 1 }, {}, 0);
-    expect(spec.pitchBend).to.be.a('number');
-  });
-
-  it('returns null for getSfxConfig when sfxId is null', function() {
-    const mapping = makeMapping();
-    expect(mapping.getSfxConfig(null)).to.equal(null);
-  });
-
-  it('keeps explicit velocity when position mappings are present', function() {
-    const spec = mapEvent({
-      velocityRange: { min: 10, max: 127, default: 80 },
-      position: { mappings: [{ axis: 'x', target: 'velocity', min: 10, max: 20, enabled: true }] }
-    }, { sfxId: 1, x: 100 }, { levelWidth: 100 }, 0, { velocity: 90 });
-
-    expect(spec.velocity).to.equal(90);
-  });
-
-  it('parses JSON input and handles invalid JSON', function() {
-    const valid = MidiMapping.fromJson('{"noteRange":{"min":50,"max":51}}');
-    expect(valid.config.noteRange.min).to.equal(50);
-    const direct = MidiMapping.fromJson({ noteRange: { min: 48, max: 49 } });
-    expect(direct.config.noteRange.max).to.equal(49);
-    const invalid = MidiMapping.fromJson('{bad');
-    expect(invalid.config).to.be.ok;
-  });
-
-  it('returns sfx config and skips disabled events', function() {
-    const mapping = new MidiMapping({
-      enabled: true,
-      sfx: { '2': { note: 61, disabled: true } }
-    });
-    expect(mapping.getSfxConfig(2).note).to.equal(61);
-    expect(mapping.getSfxConfig(3)).to.equal(null);
-    const spec = mapping.mapEvent({ sfxId: 2 }, {}, 0);
-    expect(spec).to.equal(null);
-
-    const disabled = new MidiMapping({ enabled: false });
-    expect(disabled.mapEvent({ sfxId: 1 }, {}, 0)).to.equal(null);
-  });
-
-  it('quantizes and clamps notes with custom scale', function() {
-    const mapping = makeMapping({
-      scale: { degrees: [], root: 0 },
-      noteRange: { min: 60, max: 61 }
-    });
-    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0);
-    expect(spec.note).to.equal(61);
-  });
-
-  it('covers position mapping targets and overrides', function() {
-    const mapping = new MidiMapping({
-      noteRange: { min: 60, max: 72 },
-      velocityRange: { min: 10, max: 120, default: 80 },
-      durationTicks: { min: 1, max: 10, default: 4 },
-      density: { velocityBoost: 0.5, durationScale: 0.5 },
-      position: {
-        mappings: [
-          { axis: 'x', target: 'note', max: 12, enabled: true },
-          { axis: 'x', target: 'velocity', enabled: true },
-          { axis: 'x', target: 'timbre', min: 0, max: 127, enabled: true },
-          { axis: 'x', target: 'pan', min: -50, max: 50, enabled: true },
-          { axis: 'x', target: 'duration', min: 2, max: 6, enabled: true },
-          { axis: 'x', target: 'pitchBend', min: -1, max: 1, enabled: true },
-          { axis: 'x', target: 'attack', min: 0, max: 2, enabled: true },
-          { axis: 'x', target: 'decay', min: 0, max: 2, enabled: true },
-          { axis: 'x', target: 'sustain', min: 0.5, max: 1.5, enabled: true },
-          { axis: 'x', target: 'release', min: 0, max: 2, enabled: true },
-          { axis: 'xy', target: 'velocity', min: 20, max: 100, enabled: true }
-        ],
-        timbreRange: { min: 0, max: 127 },
-        panRange: { min: -127, max: 127 },
-        viewPan: false
-      },
-      scale: { degrees: [0, 2, 4, 5, 7, 9, 11], root: 0 }
-    });
-
-    const spec = mapping.mapEvent(
-      { sfxId: 1, x: 50, y: 25, intensity: 1.2 },
-      { levelWidth: 100, levelHeight: 50 },
-      0.5,
-      { notes: [60, 64], envelope: { attack: 1.2 } }
-    );
-
-    expect(spec.notes).to.have.length(2);
-    expect(spec.pitchBend).to.be.a('number');
-    expect(spec.timbre).to.be.a('number');
-    expect(spec.pan).to.be.a('number');
-  });
-
-  it('skips mappings when axis values are missing', function() {
-    const spec = mapEvent({
-      position: {
-        mappings: [{ axis: 'y', target: 'velocity', min: 0, max: 127, enabled: true }]
-      }
-    }, { sfxId: 1, x: 10 }, { levelWidth: 100, levelHeight: null }, 0);
-    expect(spec.velocity).to.be.a('number');
-  });
-
-  it('handles null inputs for fromJson and mapEvent', function() {
-    const mapping = MidiMapping.fromJson(null);
-    expect(mapping.config).to.be.ok;
-    expect(mapping.mapEvent(null)).to.equal(null);
-  });
-
-  it('computes pan for offscreen events and keeps defaults', function() {
-    const spec = mapEvent({
-      position: {
-        viewPan: true,
-        panRange: { min: -127, max: 127 },
-        panDeadZonePct: 0.1,
-        panOnscreenWeight: 0.5,
-        panOffscreenWeight: 0.5,
-        panOffscreenRange: 1
-      }
-    }, { sfxId: 1, x: 300 }, { viewRect: { x: 0, w: 100 } }, 0);
-    expect(spec.pan).to.be.greaterThan(0);
-  });
-
-  it('builds chords and applies envelope settings', function() {
-    const mapping = makeMapping({
-      scale: { name: 'major', root: 0 },
-      noteDefaults: { octave: 4, degree: 0, chord: 'triad' },
-      envelope: { attack: 1.2, decay: 0.1, sustain: 1, release: 0.8 },
-      sfx: { '1': { degree: 0, chord: { type: 'triad' } } }
-    });
-
-    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0);
-    expect(spec.notes).to.have.length(3);
-    expect(spec.velocity).to.be.greaterThan(0);
-    expect(spec.releaseVelocity).to.be.greaterThan(0);
-  });
-
-  it('builds scale notes from degree without chords', function() {
-    const mapping = makeMapping({
-      scale: { degrees: [0, 2, 4, 5, 7, 9, 11], root: 0 },
-      noteRange: { min: 60, max: 72 },
-      sfx: { '1': { degree: 2, octave: 4 } }
-    });
-    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0);
-    expect(spec.note).to.be.within(60, 72);
-  });
-
-  it('uses octave defaults when mapping degrees', function() {
-    const mapping = makeMapping({
-      noteDefaults: { degree: null, octave: null },
-      sfx: { '1': { degree: 2 }, '2': { degree: 2, octave: 5 } }
-    });
-
-    const fallback = mapping.mapEvent({ sfxId: 1 }, {}, 0);
-    expect(fallback.note).to.equal(50);
-
-    const explicit = mapping.mapEvent({ sfxId: 2 }, {}, 0);
-    expect(explicit.note).to.equal(62);
-  });
-
-  it('computes view pan using level width when viewRect is missing', function() {
-    const mapping = makeMapping({
-      position: {
-        viewPan: true,
-        panRange: { min: -127, max: 127 },
-        panDeadZonePct: 0.1,
-        panOnscreenWeight: 0.8,
-        panOffscreenWeight: 0.2,
-        panOffscreenRange: 1
-      }
-    });
-    const spec = mapping.mapEvent({ sfxId: 1, x: 75 }, { levelWidth: 100 }, 0);
-    expect(spec.pan).to.be.a('number');
-  });
-
-  it('keeps view pan null when view width is unavailable', function() {
-    const mapping = makeMapping({
-      position: {
-        viewPan: true,
-        panRange: null,
-        panDeadZonePct: null,
-        panOnscreenWeight: null,
-        panOffscreenWeight: null,
-        panOffscreenRange: null
-      }
-    });
-
-    const spec = mapping.mapEvent({ sfxId: 1, x: 10 }, {}, 0);
-    expect(spec.pan).to.equal(null);
-  });
-
-  it('falls back to the default scale when the name is unknown', function() {
-    const mapping = makeMapping({
-      scale: { name: 'mystery-scale', degrees: [] },
-      noteRange: { min: 60, max: 60 }
-    });
-
-    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0);
-    expect(spec.note).to.equal(60);
-  });
-
-  it('quantizes notes upward and downward to the scale', function() {
-    const mapping = makeMapping({
-      scale: { degrees: [0], root: 0 },
-      noteRange: { min: 0, max: 127 }
-    });
-
-    const up = mapping.mapEvent({ sfxId: 1 }, {}, 0, { note: 59 });
-    const down = mapping.mapEvent({ sfxId: 1 }, {}, 0, { note: 61 });
-    expect(up.note).to.equal(60);
-    expect(down.note).to.equal(60);
-  });
-
-  it('keeps notes unchanged when no scale degree is within range', function() {
-    const mapping = makeMapping({
-      scale: { degrees: [99], root: 0 },
-      noteRange: { min: 0, max: 127 }
-    });
-
-    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0, { note: 60 });
-    expect(spec.note).to.equal(60);
-  });
-
-  it('handles chord inversions', function() {
-    const mapping = new MidiMapping({
-      scale: { name: 'major', root: 0, degrees: [0, 2, 4, 5, 7, 9, 11] },
-      noteDefaults: { octave: 4, degree: 0, chord: 'triad' },
-      sfx: { '1': { degree: 0, chord: { type: 'triad', inversion: 1 } } }
-    });
-
-    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0);
-    expect(spec.notes).to.eql([52, 55, 60]);
-  });
-
-  it('maps degrees to scale notes when chord is not specified', function() {
-    const mapping = new MidiMapping({
-      scale: { name: 'major', root: 0, degrees: [0, 2, 4, 5, 7, 9, 11] },
-      noteDefaults: { octave: 4, degree: 0 },
-      sfx: { '1': { degree: 2, octave: 4 } }
-    });
-
-    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0);
-    expect(spec.note).to.equal(52);
-  });
-
-  it('applies note offsets to note arrays', function() {
-    const mapping = new MidiMapping({
-      noteRange: { min: 0, max: 127 },
-      position: {
-        mappings: [{ axis: 'x', target: 'note', min: 0, max: 12, enabled: true }],
-        viewPan: false
-      },
-      sfx: { '1': { notes: [60, 64, 67] } }
-    });
-
-    const spec = mapping.mapEvent(
-      { sfxId: 1, x: 100 },
-      { levelWidth: 100, levelHeight: 100 },
-      0
-    );
-
-    expect(spec.notes).to.eql([72, 76, 79]);
-    expect(spec.note).to.equal(72);
-  });
-
-  it('applies pitch bend and sustain overrides from position mappings', function() {
-    const spec = mapEvent({
-      position: {
-        mappings: [
-          { axis: 'x', target: 'pitchBend', min: -1, max: 1, enabled: true },
-          { axis: 'x', target: 'attack', min: 0, max: 2, enabled: true },
-          { axis: 'x', target: 'sustain', min: 0.5, max: 1.5, enabled: true },
-          { axis: 'x', target: 'unknown', min: 0, max: 1, enabled: true }
-        ]
-      }
-    }, { sfxId: 1, x: 100 }, { levelWidth: 100, levelHeight: 100 }, 0);
-
-    expect(spec.pitchBend).to.equal(1);
-    expect(spec.durationTicks).to.be.greaterThan(0);
-  });
-
-  it('applies intensity scaling and per-event envelope overrides', function() {
-    const spec = mapEvent({
-      velocityRange: { min: 10, max: 127, default: 50 },
-      envelope: { attack: 1, decay: 0, sustain: 1, release: 1 },
-      sfx: { '1': { envelope: { attack: 1.5, release: 0.5 } } }
-    }, { sfxId: 1, intensity: 1.2 }, {}, 0);
-    expect(spec.velocity).to.equal(90);
-    expect(spec.releaseVelocity).to.equal(45);
-  });
-
-  it('merges configs with overrides', function() {
-    const merged = MidiMapping.mergeConfigs(
-      { noteRange: { min: 40, max: 60 }, scale: { root: 1 } },
-      { noteRange: { max: 72 }, scale: { name: 'minor' } }
-    );
-    expect(merged.noteRange.min).to.equal(40);
-    expect(merged.noteRange.max).to.equal(72);
-    expect(merged.scale.root).to.equal(1);
-    expect(merged.scale.name).to.equal('minor');
-  });
-
-  it('handles null JSON input and array overrides', function() {
-    const fresh = MidiMapping.fromJson(null);
-    expect(fresh.config).to.be.ok;
-    const merged = MidiMapping.mergeConfigs(
-      { noteRange: { min: 40, max: 60 } },
-      { noteRange: [1, 2, 3] }
-    );
-    expect(merged.noteRange).to.eql([1, 2, 3]);
-  });
-
-  it('builds position mappings from toggle flags', function() {
-    const mapping = makeMapping({
-      position: {
-        xToNote: true,
-        yToVelocity: true,
-        yToTimbre: true,
-        xNoteRange: { min: -12, max: 12 },
-        timbreRange: { min: 0, max: 127 }
-      },
-      velocityRange: { min: 10, max: 110, default: 80 }
-    });
-    const spec = mapping.mapEvent(
-      { sfxId: 1, x: 100, y: 50 },
-      { levelWidth: 100, levelHeight: 100 },
-      0
-    );
-    expect(spec.timbre).to.be.within(0, 127);
-  });
-
-  it('applies mapping targets and skips missing axis values', function() {
-    const mapping = new MidiMapping({
-      noteRange: { min: 60, max: 72 },
-      velocityRange: { min: 1, max: 127, default: 60 },
-      durationTicks: { default: 4, min: 1, max: 10 },
-      position: {
-        mappings: [
-          { axis: 'x', target: 'note', min: -12, max: 12, enabled: true },
-          { axis: 'x', target: 'velocity', min: 10, max: 100, enabled: true },
-          { axis: 'y', target: 'timbre', min: 20, max: 80, enabled: true },
-          { axis: 'x', target: 'pan', min: -100, max: 100, enabled: true },
-          { axis: 'y', target: 'duration', min: 2, max: 6, enabled: true },
-          { axis: 'x', target: 'pitchBend', min: -1, max: 1, enabled: true },
-          { axis: 'x', target: 'attack', min: 0, max: 2, enabled: true },
-          { axis: 'x', target: 'decay', min: 0, max: 2, enabled: true },
-          { axis: 'y', target: 'sustain', min: 0.5, max: 1.5, enabled: true },
-          { axis: 'y', target: 'release', min: 0, max: 2, enabled: true },
-          { axis: 'x', enabled: true }
-        ],
-        viewPan: false
-      }
-    });
-    const spec = mapping.mapEvent(
-      { sfxId: 1, x: 50, y: 50 },
-      { levelWidth: 100, levelHeight: 100 },
-      0
-    );
-    expect(spec.pan).to.not.equal(null);
-    expect(spec.pitchBend).to.be.a('number');
-
-    const missingAxis = mapping.mapEvent(
-      { sfxId: 1, x: 50 },
-      { levelWidth: 100 },
-      0
-    );
-    expect(missingAxis.velocity).to.be.a('number');
-  });
-
-  it('quantizes notes already in scale and clamps out-of-range notes', function() {
-    const mapping = makeMapping({
-      scale: { degrees: [0, 4, 7], root: 0 },
-      noteRange: { min: 60, max: 72 },
-      sfx: { '1': { note: 64 } }
-    });
-    const inScale = mapping.mapEvent({ sfxId: 1 }, {}, 0);
-    expect(inScale.note).to.equal(64);
-
-    const clamped = mapping.mapEvent({ sfxId: 1 }, {}, 0, { note: 30 });
-    expect(clamped.note).to.equal(67);
-  });
-
-  it('builds sixth chords and falls back to triads', function() {
-    const mapping = new MidiMapping({
-      scale: { name: 'major', root: 0, degrees: [0, 2, 4, 5, 7, 9, 11] },       
-      noteDefaults: { octave: 4, degree: 0, chord: 'triad' }
-    });
-    const sixth = mapping.mapEvent({ sfxId: 1 }, {}, 0, { degree: 0, chord: { type: 'sixth' } });
-    expect(sixth.notes).to.have.length(4);
-    const fallback = mapping.mapEvent({ sfxId: 1 }, {}, 0, { degree: 0, chord: { type: 'unknown' } });
-    expect(fallback.notes).to.have.length(3);
-  });
-
-  it('respects explicit values while applying pitch bend overrides', function() {
-    const mapping = new MidiMapping({
-      position: {
-        mappings: [
-          { axis: 'x', target: 'pitchBend', min: -1, max: 1, enabled: true },
-          { axis: 'x', target: 'velocity', min: 10, max: 100, enabled: true },
-          { axis: 'x', target: 'duration', min: 2, max: 6, enabled: true }
-        ],
-        viewPan: false,
-        xToNote: false,
-        yToVelocity: false,
-        yToTimbre: false
-      },
-      velocityRange: { min: 1, max: 127, default: 50 },
-      durationTicks: { default: 4, min: 1, max: 10 }
-    });
-
-    const specFreq = mapping.mapEvent(
-      { sfxId: 1, x: 50 },
-      { levelWidth: 100, levelHeight: 100 },
-      0,
-      { frequencyHz: 440, velocity: 90, durationTicks: 8 }
-    );
-    expect(specFreq.pitchBend).to.equal(0);
-    expect(specFreq.velocity).to.equal(90);
-    expect(specFreq.durationTicks).to.equal(8);
-
-    const specOverride = mapping.mapEvent(
-      { sfxId: 1, x: 100 },
-      { levelWidth: 100, levelHeight: 100 },
-      0
-    );
-    expect(specOverride.pitchBend).to.equal(1);
-  });
-
-  it('skips chord mapping when a note is already provided', function() {
-    const mapping = makeMapping({
-      scale: { name: 'major', root: 0, degrees: [0, 2, 4, 5, 7, 9, 11] },
-      noteRange: { min: 60, max: 72 }
-    });
-    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0, { chord: { type: 'triad' }, note: 65 });
-    expect(spec.notes).to.equal(null);
-    expect(spec.note).to.equal(65);
-  });
-
-  it('handles view pan dead zones and empty widths', function() {
-    const mapping = makeMapping({
-      position: {
-        viewPan: true,
-        panRange: { min: -127, max: 127 },
-        panDeadZonePct: 0.5,
-        panOnscreenWeight: 1,
-        panOffscreenWeight: 0,
-        panOffscreenRange: 1
-      }
-    });
-    const center = mapping.mapEvent({ sfxId: 1, x: 50 }, { viewRect: { x: 0, w: 100 } }, 0);
-    expect(center.pan).to.equal(0);
-
-    const zero = mapping.mapEvent({ sfxId: 1, x: 10 }, { viewRect: { x: 0, w: 0 } }, 0);
-    expect(zero.pan).to.equal(null);
-  });
-
-  it('returns null for missing events and ignores non-plain envelopes', function() {
-    const mapping = makeMapping();
-    expect(mapping.mapEvent(null, {}, 0)).to.equal(null);
-
-    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0, { envelope: [] });
-    expect(spec.velocity).to.be.a('number');
-  });
-
-  it('mapEvent uses defaults and override sfx', function() {
-    const mapping = makeMapping();
-    const spec = mapping.mapEvent({ sfxId: 1 });
-    expect(spec.note).to.be.a('number');
-
-    const overrideSpec = mapping.mapEvent({ sfxId: 1 }, undefined, undefined, { note: 70 });
-    expect(overrideSpec.note).to.equal(70);
-  });
-
-  it('mapEvent applies mapping targets and disabled entries', function() {
-    const mapping = new MidiMapping({
-      noteRange: { min: 60, max: 72 },
-      velocityRange: { min: 1, max: 127, default: 64 },
-      durationTicks: { default: 4, min: 1, max: 10 },
-      density: { windowTicks: 10, velocityBoost: 0.1, durationScale: 0.1 },
-      position: {
-        mappings: [
-          { axis: 'x', target: 'note', min: -12, max: 12, enabled: true },
-          { axis: 'x', target: 'velocity', min: 10, max: 100, enabled: true },
-          { axis: 'y', target: 'timbre', min: 20, max: 80, enabled: true },
-          { axis: 'x', target: 'pan', min: -50, max: 50, enabled: true },
-          { axis: 'x', target: 'duration', min: 2, max: 6, enabled: true },
-          { axis: 'x', target: 'pitchBend', min: -1, max: 1, enabled: true },
-          { axis: 'x', target: 'attack', min: 0, max: 2, enabled: true },
-          { axis: 'y', target: 'sustain', min: 0.5, max: 1.5, enabled: true },
-          { axis: 'x', target: 'unknown', enabled: true },
-          { axis: 'y', target: 'velocity', enabled: false }
-        ],
-        viewPan: false,
-        xToNote: false,
-        yToVelocity: false,
-        yToTimbre: false,
-        timbreRange: { min: 0, max: 127 },
-        panRange: { min: -50, max: 50 }
-      }
-    });
-
-    const spec = mapping.mapEvent(
-      { sfxId: 1, x: 100, y: 50, intensity: 1.5 },
-      { levelWidth: 100, levelHeight: 100 },
-      0.5
-    );
-    expect(spec.timbre).to.be.within(0, 127);
-    expect(spec.pan).to.be.within(-50, 50);
-    expect(spec.durationTicks).to.be.at.least(1);
-
-    const missingAxis = mapping.mapEvent(
-      { sfxId: 1, x: 50 },
-      { levelWidth: 100 },
-      0
-    );
-    expect(missingAxis.timbre).to.equal(null);
-  });
-
-  it('mapEvent offsets note arrays and pitch bend overrides', function() {
-    const mapping = new MidiMapping({
-      noteRange: { min: 60, max: 72 },
-      velocityRange: { min: 1, max: 127, default: 60 },
-      position: {
-        mappings: [
-          { axis: 'x', target: 'note', min: 0, max: 12, enabled: true },
-          { axis: 'x', target: 'pitchBend', min: -1, max: 1, enabled: true }
-        ],
-        viewPan: false,
-        xToNote: false,
-        yToVelocity: false,
-        yToTimbre: false
-      },
-      sfx: { '1': { notes: [60, 64] } }
-    });
-
-    const spec = mapping.mapEvent(
-      { sfxId: 1, x: 100 },
-      { levelWidth: 100, levelHeight: 100 },
-      0
-    );
-    expect(spec.notes[0]).to.equal(72);
-    expect(spec.pitchBend).to.equal(1);
-  });
-
-  it('mapEvent applies envelope defaults and view pan fallbacks', function() {  
-    const mapping = new MidiMapping({
-      envelope: { attack: NaN, decay: NaN, sustain: NaN, release: NaN },
-      position: {
-        viewPan: true,
-        panDeadZonePct: 1,
-        panOnscreenWeight: 1,
-        panOffscreenWeight: 0,
-        panOffscreenRange: 1,
-        xToNote: false,
-        yToVelocity: false,
-        yToTimbre: false
-      }
-    });
-    const spec = mapping.mapEvent(
-      { sfxId: 1, x: 50 },
-      { viewRect: { x: 0, w: 100 } },
-      0,
-      { envelope: { attack: NaN } }
-    );
-    expect(spec.pan).to.equal(0);
-    expect(spec.releaseVelocity).to.be.a('number');
-  });
-
-  it('mapEvent returns null for missing events and uses defaults', function() {
-    const mapping = new MidiMapping();
-    expect(mapping.mapEvent(null, {}, 0)).to.equal(null);
-    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0);
-    expect(spec.note).to.be.a('number');
-  });
-
-  it('mapEvent handles overrides and unknown mapping targets', function() {
-    const mapping = new MidiMapping({
-      position: {
-        mappings: [
-          { axis: 'y', target: 'unknown', enabled: true },
-          { axis: 'y', target: 'velocity', enabled: false }
-        ],
-        viewPan: false
-      }
-    });
-    const spec = mapping.mapEvent(
-      { sfxId: 1, y: 50 },
-      { levelWidth: 100, levelHeight: 100 },
-      0,
-      { note: 60, velocity: 90 }
-    );
-    expect(spec.velocity).to.equal(90);
-  });
-
-  it('mapEvent uses pitch bend overrides without frequency data', function() {
-    const mapping = new MidiMapping({
-      position: {
-        mappings: [{ axis: 'x', target: 'pitchBend', min: -1, max: 1, enabled: true }],
-        viewPan: false,
-        xToNote: false,
-        yToVelocity: false,
-        yToTimbre: false
-      }
-    });
-    const spec = mapping.mapEvent(
-      { sfxId: 1, x: 100 },
-      { levelWidth: 100, levelHeight: 100 },
-      0,
-      { note: 60 }
-    );
-    expect(spec.pitchBend).to.equal(1);
-  });
-
-  it('uses note defaults for chord mapping when degree is missing', function() {
-    const mapping = new MidiMapping({
-      scale: { name: 'major', root: 0 },
-      noteDefaults: { degree: 1, octave: 5, chord: 'seventh' },
-      sfx: { '1': { chord: {} } }
-    });
-
-    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0);
-    expect(spec.notes).to.have.length(4);
-    expect(spec.note).to.equal(spec.notes[0]);
-  });
-
-  it('computes view pan from level width when no view rect is present', function() {
-    const mapping = makeMapping({
-      position: {
-        viewPan: true,
-        panRange: { min: -127, max: 127 },
-        panDeadZonePct: 0,
-        panOnscreenWeight: 1,
-        panOffscreenWeight: 0,
-        panOffscreenRange: 1
-      }
-    });
-
-    const spec = mapping.mapEvent({ sfxId: 1, x: 0 }, { levelWidth: 100 }, 0);
-    expect(spec.pan).to.be.lessThan(0);
-  });
-
-  it('builds chord defaults when note defaults are null', function() {
-    const mapping = makeMapping({
-      scale: { name: 'custom', root: 1, degrees: [0, 3, 7] },
-      noteDefaults: { degree: null, octave: null, chord: null },
-      noteRange: { min: 0, max: 127 },
-      sfx: { '1': { chord: {}, note: null } }
-    });
-
-    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0);
-    expect(spec.notes).to.have.length(3);
-    expect(spec.note).to.equal(49);
-  });
-
-  it('applies position mappings with null range defaults', function() {
-    const mapping = new MidiMapping({
-      noteRange: { min: 60, max: 72 },
-      velocityRange: { min: null, max: null, default: 80 },
-      durationTicks: { min: null, max: null, default: 4 },
-      position: {
-        mappings: [
-          { axis: 'x', target: 'note', enabled: true },
-          { axis: 'x', target: 'velocity', enabled: true },
-          { axis: 'y', target: 'timbre', enabled: true },
-          { axis: 'x', target: 'pan', enabled: true },
-          { axis: 'y', target: 'duration', enabled: true }
-        ],
-        xNoteRange: null,
-        timbreRange: null,
-        panRange: null,
-        viewPan: false
-      },
-      sfx: { '1': { note: 60 } }
-    });
-
-    const spec = mapping.mapEvent(
-      { sfxId: 1, x: 50, y: 50 },
-      { levelWidth: 100, levelHeight: 100 },
-      0
-    );
-
-    expect(spec.velocity).to.be.within(1, 127);
-    expect(spec.timbre).to.be.within(0, 127);
-    expect(spec.pan).to.be.within(-127, 127);
-    expect(spec.durationTicks).to.be.within(1, 999);
-  });
-
-  it('computes view pan fallbacks with view rect weights', function() {
-    const mapping = makeMapping({
-      position: {
-        viewPan: true,
-        panRange: { min: 0, max: 0 },
-        panDeadZonePct: 1,
-        panOnscreenWeight: 0,
-        panOffscreenWeight: 0,
-        panOffscreenRange: null
-      },
-      sfx: { '1': { note: 60 } }
-    });
-
-    const context = { viewRect: { x: 20, w: 100 }, levelWidth: 200 };
-    const centered = mapping.mapEvent({ sfxId: 1, x: 70 }, context, 0);
-    const offscreen = mapping.mapEvent({ sfxId: 1, x: 170 }, context, 0);
-    expect(centered.pan).to.equal(0);
-    expect(offscreen.pan).to.equal(0);
-  });
-
-  it('merges configs with default fallbacks', function() {
-    const merged = MidiMapping.mergeConfigs(null, null);
-    expect(merged.scale.name).to.be.a('string');
-  });
-
-  it('mergeConfigs preserves base when override is null', function() {
-    const merged = MidiMapping.mergeConfigs({ timing: { bpmBase: 90 } }, null);
-    expect(merged.timing.bpmBase).to.equal(90);
-  });
-
-  it('clamps notes when the note range min is null', function() {
-    const mapping = makeMapping({
-      noteRange: { min: null, max: 60 },
-      sfx: { '1': { note: 80 } }
-    });
-
-    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0);
-    expect(spec.note).to.equal(56);
-  });
-
-  it('skips chord mapping when a note is already set', function() {
-    const mapping = makeMapping({
-      scale: { name: 'major', root: 0 },
-      noteRange: { min: 0, max: 127 },
-      sfx: { '1': { note: 62, chord: { type: 'seventh' } } }
-    });
-
-    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0);
-    expect(spec.notes).to.equal(null);
-    expect(spec.note).to.equal(62);
-  });
-
-  it('uses fallback velocity and duration defaults when config values are null', function() {
-    const mapping = makeMapping({
-      velocityRange: { min: null, max: null, default: null },
-      durationTicks: { min: null, max: null, default: null }
-    });
-
-    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0);
-    expect(spec.velocity).to.equal(127);
-    expect(spec.durationTicks).to.equal(6);
-  });
-
-  it('uses scale degrees with a null root', function() {
-    const mapping = makeMapping({
-      scale: { name: 'custom', degrees: [0, 2, 4], root: null },
-      noteDefaults: { degree: 0, octave: 4 },
-      sfx: { '1': { degree: 1 } }
-    });
-
-    const spec = mapping.mapEvent({ sfxId: 1 }, {}, 0);
-    expect(spec.note).to.equal(50);
-  });
-
-  it('defaults axisOp to add when not provided', function() {
-    const spec = mapEvent({
-      velocityRange: { min: 0, max: 100, default: 0 },
-      position: {
-        mappings: [{ axis: 'xy', target: 'velocity', min: 0, max: 100, enabled: true }]
-      }
-    }, { sfxId: 1, x: 50, y: 50 }, { levelWidth: 100, levelHeight: 100 }, 0);
-    expect(spec.velocity).to.equal(50);
-  });
-});
diff --git a/test/midi/midi-project-storage.test.js b/test/midi/midi-project-storage.test.js
new file mode 100644
index 00000000..01d0d259
--- /dev/null
+++ b/test/midi/midi-project-storage.test.js
@@ -0,0 +1,168 @@
+import { expect } from 'chai';
+import {
+  LEGACY_MIDI_STORAGE_KEYS,
+  PROJECT_STORAGE_KEY,
+  TEMPLATE_STORAGE_KEY,
+  clearMidiProjectStorage,
+  loadMidiProject,
+  readStoredMidiProjectTemplates,
+  resetMidiProjectStorage,
+  saveMidiProject,
+  saveMidiProjectTemplate
+} from '../../js/midi/project/MidiProjectStorage.js';
+
+const createStorage = () => {
+  const backing = new Map();
+  const calls = { get: [], set: [], remove: [] };
+  return {
+    backing,
+    calls,
+    getItem(key) {
+      calls.get.push(key);
+      return backing.has(key) ? backing.get(key) : null;
+    },
+    setItem(key, value) {
+      calls.set.push([key, value]);
+      backing.set(key, value);
+    },
+    removeItem(key) {
+      calls.remove.push(key);
+      backing.delete(key);
+    }
+  };
+};
+
+describe('MidiProjectStorage', function() {
+  it('exports the canonical project key and legacy cleanup list', function() {
+    expect(PROJECT_STORAGE_KEY).to.equal('lemmings.midi.project.v1');
+    expect(TEMPLATE_STORAGE_KEY).to.equal('lemmings.midi.templates.v1');
+    expect(LEGACY_MIDI_STORAGE_KEYS).to.include.members([
+      'lemmings.midi.intent',
+      'lemmings.midi.overrides',
+      'lemmings.midi.inputId',
+      'lemmings.midi.outputId',
+      'lemmings.midi.enabled',
+      'lemmings.midi.inputChannel',
+      'lemmings.midi.viewPan',
+      'lemmings.midi.adsrTarget',
+      'lemmings.midi.tabLeft',
+      'lemmings.midi.tabRight',
+      'lemmings.midi.sectionStates',
+      'lemmings.midi.schemaHash',
+      'lemmings.midi.storageVersion',
+      'lemmings.midi.panelCollapsed',
+      'lemmings.midi.ui.audition'
+    ]);
+  });
+
+  it('loads stored projects after deleting legacy keys without migrating overrides', function() {
+    const storage = createStorage();
+    storage.backing.set('lemmings.midi.overrides', JSON.stringify({ sfx: { '1': { note: 99 } } }));
+    storage.backing.set('lemmings.midi.inputChannel', '12');
+
+    const project = loadMidiProject(storage, {
+      enabled: false,
+      input: { channel: 3 },
+      sfx: { '1': { note: 60, durationTicks: 4 } }
+    });
+
+    expect(project.enabled).to.equal(false);
+    expect(project.devices.inputChannel).to.equal(3);
+    expect(project.sources[0].mapping.note).to.equal(60);
+    expect(storage.backing.has('lemmings.midi.overrides')).to.equal(false);
+    expect(storage.backing.has('lemmings.midi.inputChannel')).to.equal(false);
+  });
+
+  it('saves sanitized projects and reloads the project storage key', function() {
+    const storage = createStorage();
+    const saved = saveMidiProject(storage, {
+      tracks: [{ id: 'track-a', channel: 99 }],
+      sources: [{ id: 'sfx-1', kind: 'sfx', sourceKey: '1', mapping: { note: 999 } }],
+      clips: [{ id: 'clip-a', name: 'Clip A', lengthSteps: 2, steps: [{ note: 64 }, { note: 67, velocity: 90 }] }],
+      automation: [{ id: 'lane-a', target: 'pan', axis: 'x', min: -50, max: 50 }],
+      ui: { selectedTrackId: 'track-a', selectedSourceId: 'sfx-1' }
+    });
+
+    expect(saved.tracks[0].channel).to.equal(16);
+    expect(saved.sources[0].mapping.note).to.equal(127);
+    expect(saved.clips[0].steps.map(step => step.note)).to.deep.equal([64, 67]);
+    expect(saved.automation[0]).to.include({ id: 'lane-a', target: 'pan', axis: 'x', min: -50, max: 50 });
+
+    const loaded = loadMidiProject(storage);
+    expect(loaded.tracks[0].channel).to.equal(16);
+    expect(loaded.sources[0].mapping.note).to.equal(127);
+    expect(loaded.clips[0].steps[1]).to.include({ note: 67, velocity: 90 });
+    expect(loaded.automation[0]).to.include({ id: 'lane-a', target: 'pan' });
+    expect(storage.calls.get).to.include(PROJECT_STORAGE_KEY);
+  });
+
+  it('resets to a fresh factory project and cleans all legacy keys', function() {
+    const storage = createStorage();
+    for (const key of LEGACY_MIDI_STORAGE_KEYS) {
+      storage.backing.set(key, 'legacy');
+    }
+    storage.backing.set(PROJECT_STORAGE_KEY, JSON.stringify({
+      sources: [{ id: 'sfx-old', kind: 'sfx', sourceKey: 'old', mapping: { note: 1 } }]
+    }));
+
+    const project = resetMidiProjectStorage(storage, {
+      enabled: true,
+      input: { channel: 'omni' },
+      sfx: { '7': { note: 70, disabled: true } }
+    });
+
+    expect(project.sources.map(source => source.sourceKey)).to.deep.equal(['7']);
+    expect(project.sources[0].enabled).to.equal(false);
+    expect(JSON.parse(storage.backing.get(PROJECT_STORAGE_KEY)).sources[0].sourceKey).to.equal('7');
+    for (const key of LEGACY_MIDI_STORAGE_KEYS) {
+      expect(storage.backing.has(key)).to.equal(false);
+    }
+  });
+
+  it('saves user templates and can reset a project from a selected template', function() {
+    const storage = createStorage();
+    const project = saveMidiProject(storage, {
+      enabled: true,
+      devices: { inputId: 'in-1', outputId: 'out-1', inputChannel: 7 },
+      tracks: [{ id: 'lead', name: 'Lead', channel: 3 }],
+      sources: [{ id: 'sfx-1', kind: 'sfx', sourceKey: '1', label: 'Skill', trackId: 'lead', mapping: { note: 72 } }],
+      ui: { selectedTrackId: 'lead', selectedSourceId: 'sfx-1' }
+    });
+
+    const template = saveMidiProjectTemplate(storage, project, {
+      id: 'lead-template',
+      name: 'Lead Template',
+      now: 99
+    });
+    expect(template).to.include({ id: 'lead-template', name: 'Lead Template' });
+    expect(template.project).to.include({ enabled: false, templateId: 'lead-template' });
+    expect(template.project.devices).to.deep.equal({ inputId: null, outputId: null, inputChannel: 7 });
+    expect(readStoredMidiProjectTemplates(storage).map(entry => entry.id)).to.deep.equal(['lead-template']);
+
+    const reset = resetMidiProjectStorage(storage, {
+      sfx: { '2': { note: 60 } },
+      triggers: {}
+    }, 'lead-template');
+    expect(reset).to.include({ enabled: false, templateId: 'lead-template', name: 'Lead Template' });
+    expect(reset.tracks[0]).to.include({ id: 'lead', name: 'Lead', channel: 3 });
+    expect(reset.sources[0]).to.include({ id: 'sfx-1', sourceKey: '1', trackId: 'lead' });
+    expect(reset.sources[0].mapping.note).to.equal(72);
+    expect(JSON.parse(storage.backing.get(TEMPLATE_STORAGE_KEY)).templates[0].id).to.equal('lead-template');
+  });
+
+  it('clears project and legacy storage keys and swallows storage failures', function() {
+    const storage = createStorage();
+    storage.backing.set(PROJECT_STORAGE_KEY, '{}');
+    clearMidiProjectStorage(storage);
+    expect(storage.backing.has(PROJECT_STORAGE_KEY)).to.equal(false);
+
+    const badStorage = {
+      getItem: () => { throw new Error('get'); },
+      setItem: () => { throw new Error('set'); },
+      removeItem: () => { throw new Error('remove'); }
+    };
+    expect(() => loadMidiProject(badStorage)).to.not.throw();
+    expect(() => saveMidiProject(badStorage, {})).to.not.throw();
+    expect(() => clearMidiProjectStorage(badStorage)).to.not.throw();
+  });
+});
diff --git a/test/midi/midi-project.test.js b/test/midi/midi-project.test.js
new file mode 100644
index 00000000..cf913264
--- /dev/null
+++ b/test/midi/midi-project.test.js
@@ -0,0 +1,760 @@
+import { expect } from 'chai';
+import { readFile } from 'node:fs/promises';
+import {
+  MIDI_PROJECT_EXPORT_KIND,
+  MIDI_PROJECT_VERSION,
+  MIDI_TEMPLATE_EXPORT_KIND,
+  createMidiProjectExportPayload,
+  createMidiProjectTemplate,
+  createMidiProjectFromMidiConfig,
+  detectMidiProjectConflicts,
+  importMidiProjectPayload,
+  projectToMidiConfig,
+  reduceMidiProject,
+  sanitizeMidiProject,
+  stringifyMidiProjectExport
+} from '../../js/midi/project/MidiProject.js';
+
+const loadFactoryConfig = async () => JSON.parse(
+  await readFile(new URL('../../midi-mapping.json', import.meta.url), 'utf8')
+);
+
+describe('MidiProject', function() {
+  it('creates a canonical project from the MIDI mapping factory config', async function() {
+    const factoryConfig = await loadFactoryConfig();
+    const project = createMidiProjectFromMidiConfig({
+      ...factoryConfig,
+      triggers: {
+        '42': { note: 72, velocity: 90, durationTicks: 5, pitchBend: 0.5, envelope: { attack: 1.2 } }
+      }
+    });
+
+    expect(project.version).to.equal(MIDI_PROJECT_VERSION);
+    expect(project.id).to.equal('factory-midi-project');
+    expect(project.templateId).to.equal('midi-mapping');
+    expect(project.enabled).to.equal(false);
+    expect(project.devices.inputChannel).to.equal('omni');
+    expect(project.transport).to.include({ bpmBase: 120, quantize: '1/16', swing: 0 });
+    expect(project.global.density).to.include({ velocityBoost: 0.4, durationScale: 0.5 });
+    expect(project.global.position).to.include({ viewPan: false });
+    expect(project.automation.map(lane => lane.target)).to.include.members(['velocity', 'timbre']);
+    expect(project.tracks[0]).to.include({
+      id: 'track-1',
+      outputId: null,
+      channel: 1,
+      instrumentLabel: 'General MIDI',
+      mute: false,
+      solo: false,
+      arm: false,
+      velocityScale: 1,
+      priority: 1,
+      voiceBudget: 32
+    });
+
+    const disabledSfx = project.sources.find(source => source.kind === 'sfx' && source.sourceKey === '19');
+    expect(disabledSfx).to.include({
+      id: 'sfx-19',
+      label: 'fell-off',
+      enabled: false,
+      trackId: 'track-1',
+      mode: 'direct',
+      clipId: null
+    });
+    expect(disabledSfx.mapping).to.include({ note: 50, durationTicks: 6 });
+    expect(disabledSfx.mapping.disabled).to.equal(undefined);
+
+    const trigger = project.sources.find(source => source.kind === 'trigger' && source.sourceKey === '42');
+    expect(trigger.mapping).to.include({
+      note: 72,
+      velocity: 90,
+      durationTicks: 5,
+      pitchBend: 0.5
+    });
+    expect(trigger.mapping.envelope).to.include({ attack: 1.2 });
+  });
+
+  it('sanitizes channels, notes, velocities, durations, ids, clips, and selections', function() {
+    const project = sanitizeMidiProject({
+      tracks: [
+        { id: 'track-a', channel: 99, priority: 2, mute: true, velocityScale: 9 },
+        { id: 'track-a', channel: -1 }
+      ],
+      sources: [
+        {
+          id: 'sfx-a',
+          kind: 'sfx',
+          sourceKey: '1',
+          trackId: 'track-a',
+          mapping: {
+            note: 999,
+            notes: [-5, 64, 999],
+            velocity: 0,
+            durationTicks: 9999,
+            pan: -999,
+            timbre: 999,
+            pitchBend: 7
+          }
+        },
+        { id: '', kind: 'bad', sourceKey: '', trackId: 'missing', mapping: { note: -7 } }
+      ],
+      clips: [
+        { id: 'clip-a', name: '', type: 'bad', lengthSteps: 999, steps: [{ note: 999, probability: 4 }] }
+      ],
+      automation: [
+        {
+          id: 'lane-a',
+          name: '',
+          target: 'bad',
+          axis: 'bad',
+          min: '10',
+          max: '20',
+          points: [{ beat: 4, value: 2 }, { beat: 1, value: 8 }]
+        },
+        { id: 'lane-a', target: 'pan', axis: 'xy', min: -999, max: 999 }
+      ],
+      global: {
+        density: { windowTicks: -1, velocityBoost: 99, durationScale: 2 },
+        envelope: { attack: 9, decay: -1, sustain: 3, release: 0.5 },
+        position: { viewPan: true, panRange: { min: -999, max: 999 } }
+      },
+      ui: {
+        selectedTrackId: 'missing',
+        selectedSourceId: 'missing',
+        selectedClipId: 'missing'
+      },
+      devices: {
+        inputChannel: 99
+      }
+    });
+
+    expect(project.tracks.map(track => track.id)).to.deep.equal(['track-a', 'track-a-2']);
+    expect(project.tracks[0]).to.include({ channel: 16, mute: true, velocityScale: 4 });
+    expect(project.tracks[1].channel).to.equal(1);
+    expect(project.devices.inputChannel).to.equal(16);
+    expect(project.sources[0].mapping).to.include({
+      note: 127,
+      velocity: 1,
+      durationTicks: 960,
+      pan: -127,
+      timbre: 127,
+      pitchBend: 1
+    });
+    expect(project.sources[0].mapping.notes).to.deep.equal([0, 64, 127]);
+    expect(project.sources[1]).to.include({ kind: 'sfx', sourceKey: '2', trackId: 'track-a' });
+    expect(project.clips).to.have.lengthOf(1);
+    expect(project.clips[0]).to.include({ name: 'Clip 1', type: 'stepPattern', lengthSteps: 256 });
+    expect(project.clips[0].steps[0]).to.include({ note: 127, probability: 1 });
+    expect(project.global.density).to.deep.equal({ windowTicks: 0, velocityBoost: 4, durationScale: 1 });
+    expect(project.global.envelope).to.deep.equal({ attack: 2, decay: 0, sustain: 2, release: 0.5 });
+    expect(project.global.position.viewPan).to.equal(true);
+    expect(project.global.position.panRange).to.deep.equal({ min: -127, max: 127 });
+    expect(project.automation.map(lane => lane.id)).to.deep.equal(['lane-a', 'lane-a-2']);
+    expect(project.automation[0]).to.include({ name: 'velocity modulation', target: 'velocity', axis: 'y', min: 10, max: 20 });
+    expect(project.automation[0].points.map(point => point.beat)).to.deep.equal([1, 4]);
+    expect(project.automation[1]).to.include({ target: 'pan', axis: 'xy', min: -999, max: 999 });
+    expect(project.ui.selectedTrackId).to.equal('track-a');
+    expect(project.ui.selectedSourceId).to.equal('sfx-a');
+    expect(project.ui.selectedClipId).to.equal(null);
+  });
+
+  it('reduces setup-to-audition project intents', function() {
+    let project = createMidiProjectFromMidiConfig({
+      sfx: { '1': { name: 'skill-select', note: 60, durationTicks: 4 } },
+      triggers: { '5': { name: 'trap', note: 55 } }
+    });
+
+    project = reduceMidiProject(project, { type: 'enabled.set', enabled: true });
+    project = reduceMidiProject(project, { type: 'devices.set', devices: { inputId: 'in-1', outputId: 'out-1', inputChannel: 4 } });
+    project = reduceMidiProject(project, { type: 'transport.set', transport: { bpmBase: 95, timeSignature: { beats: 7, unit: 8 } } });
+    project = reduceMidiProject(project, { type: 'track.add', track: { id: 'lead', name: 'Lead', channel: 3 } });
+    project = reduceMidiProject(project, { type: 'track.update', trackId: 'lead', patch: { solo: true, priority: 5, instrumentLabel: 'Lead synth' } });
+    project = reduceMidiProject(project, { type: 'track.select', trackId: 'lead' });
+    project = reduceMidiProject(project, { type: 'source.assignTrack', sourceId: 'sfx-1', trackId: 'lead' });
+    project = reduceMidiProject(project, { type: 'source.update', sourceId: 'sfx-1', patch: { enabled: true, label: 'Select' } });
+    project = reduceMidiProject(project, { type: 'source.mapping.update', sourceId: 'sfx-1', patch: { note: 200, velocity: 0, pan: -48, timbre: 96, pitchBend: 0.25, arp: { enabled: true, mode: 'down' } } });
+    project = reduceMidiProject(project, { type: 'source.select', sourceId: 'sfx-1' });
+    project = reduceMidiProject(project, { type: 'ui.set', ui: { activeRegion: 'audition' } });
+
+    expect(project.enabled).to.equal(true);
+    expect(project.devices).to.deep.equal({ inputId: 'in-1', outputId: 'out-1', inputChannel: 4 });
+    expect(project.transport.bpmBase).to.equal(95);
+    expect(project.transport.timeSignature).to.deep.equal({ beats: 7, unit: 8 });
+    expect(project.ui).to.include({ selectedTrackId: 'lead', selectedSourceId: 'sfx-1', activeRegion: 'audition' });
+    expect(project.tracks.find(track => track.id === 'lead')).to.include({ channel: 3, solo: true, priority: 5, instrumentLabel: 'Lead synth' });
+    expect(project.sources[0]).to.include({ trackId: 'lead', label: 'Select' });
+    expect(project.sources[0].mapping).to.include({ note: 127, velocity: 1, pan: -48, timbre: 96, pitchBend: 0.25 });
+    expect(project.sources[0].mapping.arp).to.include({ enabled: true, mode: 'down' });
+    expect(projectToMidiConfig(project, {}).sfx['1']).to.include({ pan: -48, timbre: 96, pitchBend: 0.25 });
+    expect(projectToMidiConfig(project, {}).sfx['1'].arp).to.include({ enabled: true, mode: 'down' });
+  });
+
+  it('sanitizes invalid reducer selection intents', function() {
+    let project = createMidiProjectFromMidiConfig({
+      sfx: { '1': { name: 'skill-select', note: 60 } },
+      triggers: {}
+    });
+    project = reduceMidiProject(project, {
+      type: 'clip.add',
+      clip: { id: 'riff', name: 'Riff', lengthSteps: 4 }
+    });
+
+    const badTrack = reduceMidiProject(project, { type: 'track.select', trackId: 'missing-track' });
+    expect(badTrack.ui).to.include({ selectedTrackId: 'track-1', activeRegion: 'tracks' });
+
+    const badSource = reduceMidiProject(project, { type: 'source.select', sourceId: 'missing-source' });
+    expect(badSource.ui).to.include({ selectedSourceId: 'sfx-1', activeRegion: 'sources' });
+
+    const badClip = reduceMidiProject(project, { type: 'clip.select', clipId: 'missing-clip' });
+    expect(badClip.ui).to.include({ selectedClipId: null, activeRegion: 'clips' });
+  });
+
+  it('ignores source track assignment intents for missing tracks', function() {
+    let project = createMidiProjectFromMidiConfig({
+      sfx: { '1': { name: 'skill-select', note: 60 } },
+      triggers: {}
+    });
+    project = reduceMidiProject(project, { type: 'track.add', track: { id: 'lead', name: 'Lead', channel: 3 } });
+    project = reduceMidiProject(project, { type: 'source.assignTrack', sourceId: 'sfx-1', trackId: 'lead' });
+    project = reduceMidiProject(project, { type: 'source.assignTrack', sourceId: 'sfx-1', trackId: 'ghost-track' });
+
+    const source = project.sources.find(entry => entry.id === 'sfx-1');
+    expect(source.trackId).to.equal('lead');
+    expect(projectToMidiConfig(project, {}).sfx['1']).to.include({ trackId: 'lead', channel: 3 });
+  });
+
+  it('sanitizes source mode clip intents without a valid clip back to direct mode', function() {
+    const project = createMidiProjectFromMidiConfig({
+      sfx: { '1': { name: 'skill-select', note: 60 } },
+      triggers: {}
+    });
+
+    const missingClip = reduceMidiProject(project, {
+      type: 'source.mode.set',
+      sourceId: 'sfx-1',
+      mode: 'clip',
+      clipId: 'missing-riff'
+    });
+
+    expect(missingClip.sources[0]).to.include({
+      mode: 'direct',
+      clipId: null
+    });
+    expect(missingClip.sources[0].mapping).to.include({ note: 60 });
+
+    const noResolvedClip = reduceMidiProject(project, {
+      type: 'source.mode.set',
+      sourceId: 'sfx-1',
+      mode: 'clip'
+    });
+
+    expect(noResolvedClip.sources[0]).to.include({
+      mode: 'direct',
+      clipId: null
+    });
+    expect(noResolvedClip.sources[0].mapping).to.include({ note: 60 });
+  });
+
+  it('removes tracks while rerouting sources and dropping track automation', function() {
+    let project = createMidiProjectFromMidiConfig({
+      position: { mappings: [] },
+      sfx: { '1': { name: 'skill-select', note: 60 } },
+      triggers: {}
+    });
+    project = reduceMidiProject(project, { type: 'track.add', track: { id: 'lead', name: 'Lead', channel: 3 } });
+    project = reduceMidiProject(project, { type: 'track.add', track: { id: 'drums', name: 'Drums', channel: 10 } });
+    project = reduceMidiProject(project, { type: 'source.assignTrack', sourceId: 'sfx-1', trackId: 'drums' });
+    project = reduceMidiProject(project, {
+      type: 'automation.add',
+      automation: { id: 'lane-drums', scope: 'track', trackId: 'drums', target: 'velocity', axis: 'y' }
+    });
+    project = reduceMidiProject(project, {
+      type: 'automation.add',
+      automation: { id: 'lane-lead', scope: 'track', trackId: 'lead', target: 'pan', axis: 'x' }
+    });
+    project = reduceMidiProject(project, { type: 'track.select', trackId: 'drums' });
+    project = reduceMidiProject(project, { type: 'track.remove', trackId: 'drums' });
+
+    expect(project.tracks.map(track => track.id)).to.deep.equal(['track-1', 'lead']);
+    expect(project.ui.selectedTrackId).to.equal('lead');
+    expect(project.sources[0].trackId).to.equal('lead');
+    expect(project.automation.map(lane => lane.id)).to.deep.equal(['lane-lead']);
+    expect(projectToMidiConfig(project, {}).sfx['1']).to.include({ trackId: 'lead', channel: 3 });
+
+    const afterLastGuard = reduceMidiProject(
+      reduceMidiProject(project, { type: 'track.remove', trackId: 'lead' }),
+      { type: 'track.remove', trackId: 'track-1' }
+    );
+    expect(afterLastGuard.tracks.map(track => track.id)).to.deep.equal(['track-1']);
+    expect(afterLastGuard.sources[0].trackId).to.equal('track-1');
+  });
+
+  it('ignores identity fields in reducer update intents', function() {
+    let project = createMidiProjectFromMidiConfig({
+      sfx: { '1': { name: 'skill-select', note: 60 } },
+      triggers: {}
+    });
+    project = reduceMidiProject(project, { type: 'track.add', track: { id: 'lead', name: 'Lead', channel: 3 } });
+    project = reduceMidiProject(project, { type: 'clip.add', clip: { id: 'riff', name: 'Riff', lengthSteps: 4 } });
+    project = reduceMidiProject(project, { type: 'automation.add', automation: { id: 'lane', target: 'velocity' } });
+    project = reduceMidiProject(project, { type: 'source.assignTrack', sourceId: 'sfx-1', trackId: 'lead' });
+    project = reduceMidiProject(project, { type: 'source.clip.assign', sourceId: 'sfx-1', clipId: 'riff' });
+
+    project = reduceMidiProject(project, { type: 'track.update', trackId: 'lead', patch: { id: 'renamed-track', name: 'Lead 2' } });
+    project = reduceMidiProject(project, { type: 'source.update', sourceId: 'sfx-1', patch: { id: 'renamed-source', label: 'Select 2' } });
+    project = reduceMidiProject(project, { type: 'clip.update', clipId: 'riff', patch: { id: 'renamed-clip', name: 'Riff 2' } });
+    project = reduceMidiProject(project, { type: 'automation.update', automationId: 'lane', patch: { id: 'renamed-lane', target: 'pan' } });
+
+    expect(project.tracks.map(track => track.id)).to.include('lead');
+    expect(project.sources.map(source => source.id)).to.include('sfx-1');
+    expect(project.clips.map(clip => clip.id)).to.include('riff');
+    expect(project.automation.map(lane => lane.id)).to.include('lane');
+    expect(project.sources[0]).to.include({ trackId: 'lead', clipId: 'riff' });
+    expect(projectToMidiConfig(project, {}).sfx['1']).to.include({ trackId: 'lead', clipId: 'riff' });
+  });
+
+  it('reduces clip library, step editing, source assignment, and runtime clip lowering', function() {
+    let project = createMidiProjectFromMidiConfig({
+      sfx: { '1': { name: 'skill-select', note: 60, durationTicks: 4 } },
+      triggers: { '5': { name: 'trap', note: 55 } }
+    });
+
+    project = reduceMidiProject(project, { type: 'clip.add', clip: { id: 'riff', name: 'Riff', lengthSteps: 4 } });
+    project = reduceMidiProject(project, { type: 'clip.update', clipId: 'riff', patch: { name: 'Lead Riff', type: 'arp', arp: { mode: 'down', pattern: { preset: 'custom', steps: ['up', 'hold', 'down'] } } } });
+    project = reduceMidiProject(project, { type: 'clip.step.update', clipId: 'riff', stepIndex: 0, patch: { note: 64, velocity: 96, durationTicks: 5 } });
+    project = reduceMidiProject(project, { type: 'clip.step.update', clipId: 'riff', stepIndex: 1, patch: { note: 67, probability: 0.5 } });
+    project = reduceMidiProject(project, { type: 'clip.step.update', clipId: 'riff', stepIndex: 2, patch: { note: 999, tie: true } });
+    project = reduceMidiProject(project, { type: 'source.clip.assign', sourceId: 'sfx-1', clipId: 'riff' });
+    project = reduceMidiProject(project, { type: 'source.clip.assign', sourceId: 'trigger-5', clipId: 'riff' });
+    project = reduceMidiProject(project, { type: 'clip.select', clipId: 'riff' });
+
+    expect(project.ui.selectedClipId).to.equal('riff');
+    expect(project.clips[0]).to.include({ id: 'riff', name: 'Lead Riff', type: 'arp', lengthSteps: 4 });
+    expect(project.clips[0].steps[0]).to.include({ index: 0, note: 64, velocity: 96, durationTicks: 5 });
+    expect(project.clips[0].steps[1]).to.include({ index: 1, note: 67, probability: 0.5 });
+    expect(project.clips[0].steps[2]).to.include({ index: 2, note: 127, tie: true });
+    expect(project.sources[0]).to.include({ mode: 'clip', clipId: 'riff', mapping: null });
+
+    const config = projectToMidiConfig(project, {});
+    expect(config.sfx['1']).to.include({
+      name: 'skill-select',
+      note: 64,
+      velocity: 96,
+      durationTicks: 5,
+      channel: 1,
+      clipId: 'riff',
+      clipType: 'arp'
+    });
+    expect(config.sfx['1'].notes).to.deep.equal([64, 67]);
+    expect(config.sfx['1'].arp).to.include({ enabled: true, mode: 'down', length: 2 });
+    expect(config.sfx['1'].arp.pattern).to.deep.equal({ preset: 'custom', steps: ['up', 'hold', 'down'] });
+    expect(config.triggers['5']).to.include({ note: 64, clipId: 'riff', clipType: 'arp' });
+    expect(config.triggers['5'].notes).to.deep.equal([64, 67]);
+  });
+
+  it('removes clips and returns affected sources to direct mode', function() {
+    let project = createMidiProjectFromMidiConfig({
+      sfx: { '1': { name: 'skill-select', note: 60 } },
+      triggers: { '5': { name: 'trap', note: 55 } }
+    });
+
+    project = reduceMidiProject(project, { type: 'clip.add', clip: { id: 'riff', name: 'Riff', lengthSteps: 4 } });
+    project = reduceMidiProject(project, { type: 'clip.add', clip: { id: 'fill', name: 'Fill', lengthSteps: 4 } });
+    project = reduceMidiProject(project, { type: 'source.clip.assign', sourceId: 'sfx-1', clipId: 'riff' });
+    project = reduceMidiProject(project, { type: 'source.clip.assign', sourceId: 'trigger-5', clipId: 'fill' });
+    project = reduceMidiProject(project, { type: 'clip.select', clipId: 'riff' });
+    project = reduceMidiProject(project, { type: 'clip.remove', clipId: 'riff' });
+
+    expect(project.clips.map(clip => clip.id)).to.deep.equal(['fill']);
+    expect(project.ui.selectedClipId).to.equal('fill');
+    expect(project.sources.find(source => source.id === 'sfx-1')).to.include({ mode: 'direct', clipId: null });
+    expect(project.sources.find(source => source.id === 'sfx-1').mapping).to.include({ note: null, velocity: null });
+    expect(project.sources.find(source => source.id === 'trigger-5')).to.include({ mode: 'clip', clipId: 'fill' });
+
+    project = reduceMidiProject(project, { type: 'clip.remove', clipId: 'fill' });
+    expect(project.clips).to.have.lengthOf(0);
+    expect(project.ui.selectedClipId).to.equal(null);
+    expect(project.sources.every(source => source.mode === 'direct')).to.equal(true);
+  });
+
+  it('duplicates clips without stealing source assignments', function() {
+    let project = createMidiProjectFromMidiConfig({
+      sfx: { '1': { name: 'skill-select', note: 60 } },
+      triggers: {}
+    });
+
+    project = reduceMidiProject(project, { type: 'clip.add', clip: { id: 'riff', name: 'Riff', type: 'arp', lengthSteps: 2 } });
+    project = reduceMidiProject(project, { type: 'clip.step.update', clipId: 'riff', stepIndex: 0, patch: { note: 64 } });
+    project = reduceMidiProject(project, { type: 'clip.update', clipId: 'riff', patch: { arp: { mode: 'updown', pattern: { preset: 'custom', steps: ['up', 'down'] } } } });
+    project = reduceMidiProject(project, { type: 'source.clip.assign', sourceId: 'sfx-1', clipId: 'riff' });
+    project = reduceMidiProject(project, { type: 'clip.duplicate', clipId: 'riff' });
+
+    const original = project.clips.find(clip => clip.id === 'riff');
+    const duplicate = project.clips.find(clip => clip.id !== 'riff');
+    expect(duplicate).to.include({ id: 'riff-copy', name: 'Riff Copy', type: 'arp', lengthSteps: 2 });
+    expect(duplicate.steps[0]).to.include({ note: 64 });
+    expect(duplicate.arp.pattern.steps).to.deep.equal(['up', 'down']);
+    expect(project.sources[0]).to.include({ mode: 'clip', clipId: 'riff' });
+    expect(project.ui.selectedClipId).to.equal('riff-copy');
+
+    project = reduceMidiProject(project, { type: 'clip.step.update', clipId: 'riff-copy', stepIndex: 0, patch: { note: 72 } });
+    project = reduceMidiProject(project, { type: 'clip.update', clipId: 'riff-copy', patch: { arp: { mode: 'down', pattern: { preset: 'custom', steps: ['down'] } } } });
+    expect(project.clips.find(clip => clip.id === original.id).steps[0].note).to.equal(64);
+    expect(project.clips.find(clip => clip.id === original.id).arp.pattern.steps).to.deep.equal(['up', 'down']);
+  });
+
+  it('flags reducer-assigned missing clips and lowers them as disabled runtime mappings', function() {
+    let project = createMidiProjectFromMidiConfig({
+      enabled: true,
+      sfx: { '1': { name: 'skill-select', note: 60, durationTicks: 4 } },
+      triggers: {}
+    });
+
+    project = reduceMidiProject(project, {
+      type: 'source.clip.assign',
+      sourceId: 'sfx-1',
+      clipId: 'missing-riff'
+    });
+
+    expect(project.sources[0]).to.include({
+      mode: 'clip',
+      clipId: null,
+      mapping: null
+    });
+
+    const report = detectMidiProjectConflicts(project);
+    expect(report.ok).to.equal(false);
+    expect(report.bySourceId['sfx-1'].map(issue => issue.code)).to.include('missing_clip');
+
+    const config = projectToMidiConfig(project, {});
+    expect(config.sfx['1']).to.include({
+      clipId: null,
+      clipType: 'stepPattern',
+      disabled: true
+    });
+    expect(config.sfx['1'].note).to.equal(null);
+    expect(config.sfx['1']).to.not.have.property('notes');
+    expect(config.sfx['1']).to.not.have.property('arp');
+  });
+
+  it('reduces global modulation and lowers automation lanes into runtime position mappings', function() {
+    let project = createMidiProjectFromMidiConfig({
+      enabled: true,
+      position: { mappings: [] },
+      sfx: { '1': { name: 'skill-select', note: 60, velocity: 80, durationTicks: 4 } },
+      triggers: {}
+    });
+
+    project = reduceMidiProject(project, {
+      type: 'global.update',
+      patch: {
+        velocityRange: { ...project.global.velocityRange, default: 96 },
+        density: { ...project.global.density, velocityBoost: 0.75 },
+        envelope: { ...project.global.envelope, attack: 1.4 },
+        position: { ...project.global.position, viewPan: true }
+      }
+    });
+    project = reduceMidiProject(project, { type: 'automation.add', automation: { id: 'lane', target: 'note', axis: 'x', min: -7, max: 7 } });
+    project = reduceMidiProject(project, { type: 'automation.update', automationId: 'lane', patch: { target: 'pan', axisOp: 'mul', min: -80, max: 80 } });
+    project = reduceMidiProject(project, { type: 'automation.point.update', automationId: 'lane', pointIndex: 0, patch: { beat: 2, value: 10 } });
+
+    expect(project.global.velocityRange.default).to.equal(96);
+    expect(project.global.density.velocityBoost).to.equal(0.75);
+    expect(project.global.envelope.attack).to.equal(1.4);
+    expect(project.global.position.viewPan).to.equal(true);
+    expect(project.automation[0]).to.include({ id: 'lane', target: 'pan', axis: 'x', axisOp: 'mul', min: -80, max: 80 });
+    expect(project.automation[0].points[0]).to.deep.equal({ beat: 2, value: 10 });
+
+    const config = projectToMidiConfig(project, {});
+    expect(config.velocityRange.default).to.equal(96);
+    expect(config.density.velocityBoost).to.equal(0.75);
+    expect(config.envelope.attack).to.equal(1.4);
+    expect(config.position.viewPan).to.equal(true);
+    expect(config.position.mappings).to.deep.equal([
+      {
+        axis: 'x',
+        axisOp: 'mul',
+        target: 'pan',
+        min: -80,
+        max: 80,
+        enabled: true,
+        points: [{ beat: 2, value: 10 }]
+      }
+    ]);
+  });
+
+  it('omits disabled automation lanes from runtime position mappings', function() {
+    let project = createMidiProjectFromMidiConfig({
+      enabled: true,
+      position: { mappings: [] },
+      sfx: { '1': { name: 'skill-select', note: 60, durationTicks: 4 } },
+      triggers: {}
+    });
+
+    project = reduceMidiProject(project, {
+      type: 'automation.add',
+      automation: { id: 'lane-pan', target: 'pan', axis: 'x', min: -64, max: 64 }
+    });
+    project = reduceMidiProject(project, {
+      type: 'automation.add',
+      automation: { id: 'lane-timbre', target: 'timbre', axis: 'y', min: 0, max: 127 }
+    });
+    project = reduceMidiProject(project, {
+      type: 'automation.update',
+      automationId: 'lane-timbre',
+      patch: { enabled: false }
+    });
+
+    const config = projectToMidiConfig(project, {});
+    expect(config.position.mappings).to.have.lengthOf(1);
+    expect(config.position.mappings[0]).to.include({
+      axis: 'x',
+      target: 'pan',
+      enabled: true
+    });
+    expect(config.position.mappings.some(mapping => mapping.target === 'timbre')).to.equal(false);
+  });
+
+  it('ignores automation track assignment updates for missing tracks', function() {
+    let project = createMidiProjectFromMidiConfig({
+      enabled: true,
+      position: { mappings: [] },
+      sfx: { '1': { name: 'skill-select', note: 60, durationTicks: 4 } },
+      triggers: {}
+    });
+    project = reduceMidiProject(project, { type: 'track.add', track: { id: 'lead', name: 'Lead', channel: 3 } });
+    project = reduceMidiProject(project, {
+      type: 'automation.add',
+      automation: { id: 'lane-lead', scope: 'track', trackId: 'lead', target: 'velocity', axis: 'y' }
+    });
+    project = reduceMidiProject(project, {
+      type: 'automation.update',
+      automationId: 'lane-lead',
+      patch: { trackId: 'ghost-track' }
+    });
+
+    expect(project.automation[0]).to.include({ scope: 'track', trackId: 'lead' });
+    expect(detectMidiProjectConflicts(project).issues.map(issue => issue.code)).to.not.include('missing_automation_track');
+  });
+
+  it('exports, imports, and templates sanitized MIDI projects', function() {
+    let project = createMidiProjectFromMidiConfig({
+      enabled: true,
+      input: { channel: 4 },
+      sfx: { '1': { name: 'skill-select', note: 60, velocity: 80, durationTicks: 4 } },
+      triggers: {}
+    });
+    project = reduceMidiProject(project, { type: 'track.update', trackId: 'track-1', patch: { channel: 3 } });
+    project = reduceMidiProject(project, { type: 'source.mapping.update', sourceId: 'sfx-1', patch: { note: 72 } });
+
+    const payload = createMidiProjectExportPayload(project, { exportedAt: 10 });
+    expect(payload).to.include({ kind: MIDI_PROJECT_EXPORT_KIND, version: MIDI_PROJECT_VERSION, exportedAt: 10 });
+    expect(payload.project.sources[0].mapping.note).to.equal(72);
+
+    const text = stringifyMidiProjectExport(project, { exportedAt: 11 });
+    const imported = importMidiProjectPayload(text);
+    expect(imported.sources[0].mapping.note).to.equal(72);
+    expect(imported.tracks[0].channel).to.equal(3);
+
+    const template = createMidiProjectTemplate(project, {
+      id: 'user-lead',
+      name: 'Lead Template',
+      now: 20
+    });
+    expect(template).to.include({ id: 'user-lead', name: 'Lead Template', createdAt: 20, updatedAt: 20 });
+    expect(template.project).to.include({ enabled: false, templateId: 'user-lead' });
+    expect(template.project.devices).to.deep.equal({ inputId: null, outputId: null, inputChannel: 4 });
+
+    const templatePayload = createMidiProjectExportPayload(project, {
+      asTemplate: true,
+      id: 'template-export',
+      name: 'Template Export',
+      exportedAt: 30,
+      now: 30
+    });
+    expect(templatePayload).to.include({ kind: MIDI_TEMPLATE_EXPORT_KIND, exportedAt: 30 });
+    const importedTemplate = importMidiProjectPayload(templatePayload);
+    expect(importedTemplate).to.include({ enabled: false, templateId: 'template-export' });
+    expect(importedTemplate.sources[0].mapping.note).to.equal(72);
+
+    expect(() => importMidiProjectPayload('{bad json')).to.throw('not valid JSON');
+    expect(() => importMidiProjectPayload({ kind: MIDI_PROJECT_EXPORT_KIND })).to.throw('did not contain a project');
+  });
+
+  it('applies track velocity scale to clip mappings', function() {
+    let project = createMidiProjectFromMidiConfig({
+      enabled: true,
+      sfx: { '1': { name: 'skill-select', note: 60 } },
+      triggers: {}
+    });
+    project = reduceMidiProject(project, { type: 'track.update', trackId: 'track-1', patch: { velocityScale: 0.5 } });
+    project = reduceMidiProject(project, { type: 'clip.add', clip: { id: 'riff', name: 'Riff', lengthSteps: 2 } });
+    project = reduceMidiProject(project, { type: 'clip.step.update', clipId: 'riff', stepIndex: 0, patch: { note: 64, velocity: 90 } });
+    project = reduceMidiProject(project, { type: 'source.clip.assign', sourceId: 'sfx-1', clipId: 'riff' });
+
+    const config = projectToMidiConfig(project, {});
+    expect(config.sfx['1']).to.include({ note: 64, velocity: 45, clipId: 'riff' });
+  });
+
+  it('detects duplicate runtime keys, invalid raw refs, disabled sources, and note range conflicts', function() {
+    const report = detectMidiProjectConflicts({
+      enabled: true,
+      devices: { inputChannel: 99 },
+      global: { noteRange: { min: 50, max: 70 } },
+      tracks: [
+        { id: 'track-1', name: 'Main', channel: 99, outputId: 'ghost-out' }
+      ],
+      clips: [
+        { id: 'clip-a', name: 'Clip A', lengthSteps: 2, steps: [{ note: 64 }] }
+      ],
+      sources: [
+        { id: 'dup-a', kind: 'sfx', sourceKey: '1', label: 'Duplicate A', trackId: 'track-1', enabled: true, mapping: { note: 120 } },
+        { id: 'dup-b', kind: 'sfx', sourceKey: '1', label: 'Duplicate B', trackId: 'missing-track', enabled: true, mapping: {} },
+        { id: 'clip-missing', kind: 'trigger', sourceKey: '5', label: 'Missing Clip', trackId: 'track-1', enabled: true, mode: 'clip', clipId: 'missing-clip' },
+        { id: 'disabled', kind: 'sfx', sourceKey: '2', label: 'Disabled', trackId: 'track-1', enabled: false, mapping: { note: 60 } }
+      ]
+    }, { availableOutputIds: [] });
+
+    const codes = report.issues.map(issue => issue.code);
+    expect(report.ok).to.equal(false);
+    expect(codes).to.not.include('track_output_ignored');
+    expect(codes).to.include.members([
+      'duplicate_source_key',
+      'missing_track',
+      'missing_clip',
+      'invalid_input_channel',
+      'invalid_track_channel',
+      'invalid_track_output',
+      'implicit_default_mapping',
+      'note_out_of_range',
+      'disabled_source'
+    ]);
+    expect(report.bySourceId['dup-a'].map(issue => issue.code)).to.include.members(['duplicate_source_key', 'note_out_of_range']);
+    expect(report.bySourceId['dup-b'].map(issue => issue.code)).to.include.members(['duplicate_source_key', 'missing_track', 'implicit_default_mapping']);
+    expect(report.bySourceId.disabled[0]).to.include({ severity: 'info', code: 'disabled_source' });
+  });
+
+  it('detects missing track-scoped automation conflicts', function() {
+    const report = detectMidiProjectConflicts({
+      tracks: [
+        { id: 'track-1', name: 'Main', channel: 1 }
+      ],
+      automation: [
+        {
+          id: 'lane-missing',
+          name: 'Missing Track Lane',
+          enabled: true,
+          scope: 'track',
+          trackId: 'ghost-track',
+          target: 'velocity',
+          axis: 'y'
+        }
+      ],
+      sources: []
+    });
+
+    expect(report.ok).to.equal(true);
+    expect(report.summary.warnings).to.equal(1);
+    expect(report.issues[0]).to.include({
+      severity: 'warning',
+      code: 'missing_automation_track',
+      automationId: 'lane-missing',
+      trackId: 'ghost-track'
+    });
+    expect(report.issues[0].path).to.deep.equal(['automation', 0, 'trackId']);
+  });
+
+  it('detects missing required project output conflicts', function() {
+    const report = detectMidiProjectConflicts({
+      enabled: true,
+      devices: { outputId: null },
+      tracks: [{ id: 'track-1', name: 'Main', channel: 1 }],
+      sources: []
+    }, { requireOutput: true });
+
+    expect(report.ok).to.equal(true);
+    expect(report.summary.warnings).to.equal(1);
+    expect(report.issues[0]).to.include({
+      severity: 'warning',
+      code: 'missing_project_output'
+    });
+    expect(report.issues[0].path).to.deep.equal(['devices', 'outputId']);
+    expect(report.bySourceId).to.deep.equal({});
+    expect(report.byTrackId).to.deep.equal({});
+  });
+
+  it('detects muted, solo-hidden, empty clip, and note collapse conflicts', function() {
+    const project = sanitizeMidiProject({
+      global: { noteRange: { min: 60, max: 60 } },
+      tracks: [
+        { id: 'muted', name: 'Muted', mute: true },
+        { id: 'lead', name: 'Lead', solo: true },
+        { id: 'hidden', name: 'Hidden' }
+      ],
+      clips: [
+        { id: 'empty', name: 'Empty', lengthSteps: 2, steps: [{ note: null }, { note: 65, probability: 0 }] },
+        { id: 'wide', name: 'Wide', lengthSteps: 2, steps: [{ note: 59 }, { note: 61 }] }
+      ],
+      sources: [
+        { id: 'muted-source', kind: 'sfx', sourceKey: '1', label: 'Muted Source', trackId: 'muted', enabled: true, mapping: { note: 60 } },
+        { id: 'hidden-source', kind: 'sfx', sourceKey: '2', label: 'Hidden Source', trackId: 'hidden', enabled: true, mapping: { note: 60 } },
+        { id: 'empty-clip-source', kind: 'sfx', sourceKey: '3', label: 'Empty Clip Source', trackId: 'lead', enabled: true, mode: 'clip', clipId: 'empty' },
+        { id: 'wide-clip-source', kind: 'sfx', sourceKey: '4', label: 'Wide Clip Source', trackId: 'lead', enabled: true, mode: 'clip', clipId: 'wide' }
+      ]
+    });
+
+    const report = detectMidiProjectConflicts(project);
+    expect(report.bySourceId['muted-source'].map(issue => issue.code)).to.include('track_muted');
+    expect(report.bySourceId['hidden-source'].map(issue => issue.code)).to.include('track_solo_hidden');
+    expect(report.bySourceId['empty-clip-source'].map(issue => issue.code)).to.include('silent_clip');
+    expect(report.bySourceId['wide-clip-source'].map(issue => issue.code)).to.include.members(['note_out_of_range', 'note_range_collapse']);
+  });
+
+  it('adapts projects back to MIDI config with direct mappings, channels, mute, and solo state', function() {
+    const project = sanitizeMidiProject({
+      enabled: true,
+      devices: { inputChannel: 7 },
+      transport: { bpmBase: 140, timeSignature: { beats: 3, unit: 4 }, quantize: '1/8', swing: 0.2 },
+      global: {
+        scale: { name: 'major', root: 2, degrees: [0, 2, 4, 5, 7, 9, 11] },
+        noteRange: { min: 24, max: 96 },
+        velocityRange: { min: 10, max: 127, default: 90 },
+        durationTicks: { min: 1, max: 64, default: 8 },
+        mpe: { enabled: false },
+        limits: { maxEventsPerSecond: 50 },
+        reverse: { allNotesOffOnToggle: true }
+      },
+      tracks: [
+        { id: 'drums', name: 'Drums', channel: 10, mute: true, priority: 3 },
+        { id: 'lead', name: 'Lead', channel: 2, solo: true, priority: 9, velocityScale: 0.5, voiceBudget: 4 },
+        { id: 'hidden', name: 'Hidden', channel: 4 }
+      ],
+      sources: [
+        { id: 'sfx-1', kind: 'sfx', sourceKey: '1', label: 'Skill', trackId: 'drums', enabled: true, mapping: { note: 60, durationTicks: 4 } },
+        { id: 'sfx-2', kind: 'sfx', sourceKey: '2', label: 'Lead', trackId: 'lead', enabled: true, mapping: { notes: [64, 67], velocity: 100 } },
+        { id: 'trigger-5', kind: 'midiFlag', sourceKey: '5', label: 'Flag', trackId: 'hidden', enabled: true, mapping: { degree: 2, octave: 4 } }
+      ]
+    });
+
+    const config = projectToMidiConfig(project, {
+      sfx: { old: { note: 1 } },
+      triggers: { old: { note: 2 } },
+      input: { enabled: false, channel: 1 }
+    });
+
+    expect(config.enabled).to.equal(true);
+    expect(config.input.enabled).to.equal(true);
+    expect(config.input.channel).to.equal(7);
+    expect(config.timing.bpmBase).to.equal(140);
+    expect(config.timing.timeSignature).to.deep.equal({ beats: 3, unit: 4 });
+    expect(config.timing).to.include({ quantize: '1/8', swing: 0.2 });
+    expect(config.scale.name).to.equal('major');
+    expect(config.noteRange).to.deep.equal({ min: 24, max: 96 });
+    expect(config.sfx).to.not.have.property('old');
+    expect(config.triggers).to.not.have.property('old');
+    expect(config.sfx['1']).to.include({ note: 60, durationTicks: 4, channel: 10, priority: 3, voiceBudget: 32, disabled: true });
+    expect(config.sfx['2']).to.include({ velocity: 50, channel: 2, priority: 9, voiceBudget: 4 });
+    expect(config.sfx['2']).to.not.have.property('disabled');
+    expect(config.sfx['2'].notes).to.deep.equal([64, 67]);
+    expect(config.triggers['5']).to.include({ degree: 2, octave: 4, channel: 4, voiceBudget: 32, disabled: true });
+  });
+});
diff --git a/test/midi/midi-scheduler.test.js b/test/midi/midi-scheduler.01-midischeduler.test.js
similarity index 72%
rename from test/midi/midi-scheduler.test.js
rename to test/midi/midi-scheduler.01-midischeduler.test.js
index 55d93c11..42d56de5 100644
--- a/test/midi/midi-scheduler.test.js
+++ b/test/midi/midi-scheduler.01-midischeduler.test.js
@@ -1,32 +1,15 @@
 import { expect } from 'chai';
-import FakeTimers from '@sinonjs/fake-timers';
 import { withConsoleStub } from '../helpers/console.js';
 import { withGlobalLemmings } from '../helpers/lemmings.js';
 import { MidiScheduler } from '../../js/midi/MidiScheduler.js';
+import { makeOutput } from '../support/midi-output.js';
+import { withFakeClockAndPerformance } from '../support/timers.js';
 
-const makeChannel = (id, calls) => ({
-  sendNoteOn(note, opts) { calls.push({ type: 'noteOn', id, note, opts }); },
-  sendNoteOff(note, opts) { calls.push({ type: 'noteOff', id, note, opts }); },
-  sendPitchBend(value, opts) { calls.push({ type: 'pitchBend', id, value, opts }); },
-  sendControlChange(cc, value, opts) { calls.push({ type: 'cc', id, cc, value, opts }); },
-  sendPitchBendRange(semitones, cents) {
-    calls.push({ type: 'bendRange', id, semitones, cents });
-  },
-  sendAllNotesOff() { calls.push({ type: 'allNotesOff', id }); }
-});
-
-const makeOutput = (ids, calls) => ({
-  channels: Object.fromEntries(ids.map(id => [id, makeChannel(id, calls)]))
-});
-
-describe('MidiScheduler', function() {
+describe('MidiScheduler 1', function() {
   it('schedules note offs and converts signed pan', function() {
     const calls = [];
     const output = makeOutput([1], calls);
-    const clock = FakeTimers.install({ now: 0, toFake: ['setTimeout', 'clearTimeout', 'Date'] });
-    const originalPerformance = globalThis.performance;
-    globalThis.performance = { now: () => clock.now };
-    try {
+    withFakeClockAndPerformance((clock) => {
       const scheduler = new MidiScheduler({
         mpe: { enabled: false },
         position: { panRange: { min: -127, max: 127 } }
@@ -48,10 +31,88 @@ describe('MidiScheduler', function() {
 
       clock.tick(25);
       expect(scheduler._activeNotes.size).to.equal(0);
-    } finally {
-      globalThis.performance = originalPerformance;
-      clock.uninstall();
+    });
+  });
+
+  it('routes notes and panic to registered track outputs', function() {
+    const projectCalls = [];
+    const trackCalls = [];
+    const projectOutput = makeOutput([1], projectCalls, 'project-out');
+    const trackOutput = makeOutput([1], trackCalls, 'track-out');
+    withFakeClockAndPerformance((clock) => {
+      const scheduler = new MidiScheduler({ mpe: { enabled: false } });
+      scheduler.setOutput(projectOutput);
+      scheduler.setOutputs([projectOutput, trackOutput]);
+      scheduler.setTickMs(10);
+
+      const ok = scheduler.sendNote({
+        note: 60,
+        velocity: 64,
+        durationTicks: 2,
+        outputId: 'track-out'
+      });
+
+      expect(ok).to.equal(true);
+      expect(projectCalls.some(call => call.type === 'noteOn')).to.equal(false);
+      expect(trackCalls.some(call => call.type === 'noteOn' && call.note === 60)).to.equal(true);
+      expect(trackCalls.some(call => call.type === 'noteOff' && call.note === 60)).to.equal(true);
+
+      clock.tick(25);
+      expect(scheduler._activeNotes.size).to.equal(0);
+
+      projectCalls.length = 0;
+      trackCalls.length = 0;
+      expect(scheduler.sendNote({ note: 62, durationTicks: 0, outputId: 'missing-out' })).to.equal(false);
+      expect(projectCalls.length).to.equal(0);
+      expect(trackCalls.length).to.equal(0);
+
+      scheduler.sendNote({ note: 64, durationTicks: 0 });
+      scheduler.sendNote({ note: 65, durationTicks: 0, outputId: 'track-out' });
+      scheduler.allNotesOff();
+      expect(projectCalls.some(call => call.type === 'allNotesOff')).to.equal(true);
+      expect(trackCalls.some(call => call.type === 'allNotesOff')).to.equal(true);
+    });
+  });
+
+  it('preserves routing metadata on unreserved planned sends', function() {
+    const calls = [];
+    const output = makeOutput([1], calls, 'out-1');
+    const scheduler = new MidiScheduler({ mpe: { enabled: false } });
+    scheduler.setOutput(output);
+    scheduler.setOutputs([output]);
+    scheduler.setTickMs(10);
+    const sendTimeMs = scheduler._nowMs() + 1000;
+
+    const ok = scheduler.sendNote(
+      {
+        note: 60,
+        velocity: 64,
+        durationTicks: 2,
+        timeMs: sendTimeMs,
+        trackId: 'lead',
+        outputId: 'out-1',
+        voiceBudget: 4
+      },
+      {
+        sfxId: 3,
+        priority: 2,
+        triggerType: 'skill'
+      }
+    );
+
+    expect(ok).to.equal(true);
+    expect(scheduler._ratePlanned).to.have.lengthOf(2);
+    for (const entry of scheduler._ratePlanned) {
+      expect(entry).to.include({
+        sfxId: 3,
+        priority: 2,
+        triggerType: 'skill',
+        trackId: 'lead',
+        outputId: 'out-1',
+        voiceBudget: 4
+      });
     }
+    expect(scheduler._ratePlanned.map(entry => entry.phase)).to.deep.equal(['on', 'off']);
   });
 
   it('swaps attack and release velocity when reversing', function() {
@@ -76,13 +137,10 @@ describe('MidiScheduler', function() {
     expect(noteOff.opts.rawRelease).to.equal(80);
   });
 
-  it('steals the oldest note when active count is exceeded', function() {       
+  it('steals the oldest note when active count is exceeded', function() {
     const calls = [];
     const output = makeOutput([1], calls);
-    const clock = FakeTimers.install({ now: 0, toFake: ['setTimeout', 'clearTimeout', 'Date'] });
-    const originalPerformance = globalThis.performance;
-    globalThis.performance = { now: () => clock.now };
-    try {
+    withFakeClockAndPerformance((clock) => {
       const scheduler = new MidiScheduler({
         mpe: { enabled: false },
         limits: { maxActiveNotes: 1 }
@@ -95,19 +153,34 @@ describe('MidiScheduler', function() {
 
       const noteOffs = calls.filter(c => c.type === 'noteOff').map(c => c.note);
       expect(noteOffs).to.include(60);
-    } finally {
-      globalThis.performance = originalPerformance;
-      clock.uninstall();
-    }
+    });
+  });
+
+  it('steals the oldest note on a track when its voice budget is exceeded', function() {
+    const calls = [];
+    const output = makeOutput([1], calls);
+    withFakeClockAndPerformance((clock) => {
+      const scheduler = new MidiScheduler({ mpe: { enabled: false } });
+      scheduler.setOutput(output);
+
+      scheduler.sendNote({ note: 60, velocity: 64, durationTicks: 0, trackId: 'lead', voiceBudget: 1 });
+      clock.tick(1);
+      scheduler.sendNote({ note: 62, velocity: 64, durationTicks: 0, trackId: 'pad', voiceBudget: 1 });
+      clock.tick(1);
+      scheduler.sendNote({ note: 64, velocity: 64, durationTicks: 0, trackId: 'lead', voiceBudget: 1 });
+
+      const noteOffs = calls.filter(c => c.type === 'noteOff').map(c => c.note);
+      expect(noteOffs).to.deep.equal([60]);
+      expect([...scheduler._activeNotes.values()].map(info => info.note).sort()).to.deep.equal([62, 64]);
+      expect(scheduler._countActiveNotesForTrack('lead')).to.equal(1);
+      expect(scheduler._countActiveNotesForTrack('pad')).to.equal(1);
+    });
   });
 
   it('initializes MPE channels and reuses the oldest member', function() {
     const calls = [];
     const output = makeOutput([1, 2, 3], calls);
-    const clock = FakeTimers.install({ now: 0, toFake: ['setTimeout', 'clearTimeout', 'Date'] });
-    const originalPerformance = globalThis.performance;
-    globalThis.performance = { now: () => clock.now };
-    try {
+    withFakeClockAndPerformance((clock) => {
       const scheduler = new MidiScheduler({
         mpe: {
           enabled: true,
@@ -136,10 +209,7 @@ describe('MidiScheduler', function() {
       expect(noteOff).to.be.ok;
       const timbreCalls = calls.filter(c => c.type === 'cc' && c.cc === 74);
       expect(timbreCalls.length).to.be.greaterThan(0);
-    } finally {
-      globalThis.performance = originalPerformance;
-      clock.uninstall();
-    }
+    });
   });
 
   it('clamps unsigned pan values to 0-127', function() {
@@ -163,7 +233,7 @@ describe('MidiScheduler', function() {
     expect(panCall.value).to.equal(0);
   });
 
-  it('allNotesOff resets active state when MPE is enabled', function() {        
+  it('allNotesOff resets active state when MPE is enabled', function() {
     const calls = [];
     const output = makeOutput([1, 2, 3], calls);
     const scheduler = new MidiScheduler({
@@ -211,13 +281,31 @@ describe('MidiScheduler', function() {
     expect(noteOn.id).to.equal(4);
   });
 
+  it('normalizes invalid limit values and channel configuration', function() {
+    const scheduler = new MidiScheduler({
+      limits: {
+        maxActiveNotes: 'bad',
+        maxEventsPerSecond: Number.NaN,
+        maxBytesPerSecond: -1
+      },
+      defaultChannel: 0,
+      mpe: {
+        enabled: true,
+        masterChannel: 20,
+        memberChannels: [2, 2, 0, 17, 'x']
+      }
+    });
+
+    expect(scheduler._maxActiveNotes).to.equal(32);
+    expect(scheduler._maxMessagesPerSecond).to.equal(1000);
+    expect(scheduler._maxBytesPerSecond).to.equal(3906.25);
+    expect(scheduler._allocateChannel()).to.equal(2);
+  });
+
   it('stops active channels and clears scheduled note offs', function() {
     const calls = [];
     const output = makeOutput([1, 2], calls);
-    const clock = FakeTimers.install({ now: 0, toFake: ['setTimeout', 'clearTimeout', 'Date'] });
-    const originalPerformance = globalThis.performance;
-    globalThis.performance = { now: () => clock.now };
-    try {
+    withFakeClockAndPerformance((clock) => {
       const scheduler = new MidiScheduler({
         mpe: { enabled: true, memberChannels: [2] }
       });
@@ -227,10 +315,7 @@ describe('MidiScheduler', function() {
       expect(scheduler._noteOffs.length).to.be.greaterThan(0);
       scheduler._stopActiveChannel(2);
       expect(scheduler._noteOffs.length).to.equal(0);
-    } finally {
-      globalThis.performance = originalPerformance;
-      clock.uninstall();
-    }
+    });
   });
 
   it('processes note offs safely without output', function() {
@@ -377,6 +462,29 @@ describe('MidiScheduler', function() {
     expect(snapshot.past.bySfx.get(1).count).to.equal(3);
   });
 
+  it('compacts stale rate entries in place and removes planned phases', function() {
+    const scheduler = new MidiScheduler({ mpe: { enabled: false } });
+    const keptSent = { timeMs: 900, count: 2, bytes: 6, sfxId: 1 };
+    const future = { timeMs: 1200, count: 1, bytes: 3, token: 7, phase: 'off' };
+    scheduler._rateSent = [
+      { timeMs: -5000, count: 1, bytes: 3 },
+      keptSent
+    ];
+    scheduler._ratePlanned = [
+      { timeMs: 800, count: 1, bytes: 3, token: 7, phase: 'on' },
+      future
+    ];
+
+    scheduler._pruneRateEntries(1000);
+
+    expect(scheduler._rateSent).to.include(keptSent);
+    expect(scheduler._rateSent.some(entry => entry.timeMs === 800)).to.equal(true);
+    expect(scheduler._ratePlanned).to.deep.equal([future]);
+
+    scheduler._removePlannedRateEntries(7, 'off');
+    expect(scheduler._ratePlanned).to.have.lengthOf(0);
+  });
+
   it('estimateMessages accounts for pitch bend without MPE', function() {
     const scheduler = new MidiScheduler({ mpe: { enabled: false } });
     const estimate = scheduler.estimateMessages({ note: 60, pitchBend: 0.5 });
@@ -435,69 +543,19 @@ describe('MidiScheduler', function() {
   it('tracks rate snapshots and clears queued events', function() {
     const calls = [];
     const output = makeOutput([1], calls);
-    const clock = FakeTimers.install({ now: 0, toFake: ['setTimeout', 'clearTimeout', 'Date'] });
-    const originalPerformance = globalThis.performance;
-    globalThis.performance = { now: () => clock.now, measure: () => {} };
-    try {
+    withFakeClockAndPerformance((clock) => {
       const scheduler = new MidiScheduler({ mpe: { enabled: false } });
       scheduler.setOutput(output);
       scheduler.setTickMs(10);
       scheduler.sendNote({ note: 60, velocity: 64, durationTicks: 1, timeMs: 500 });
+      scheduler._activeByChannel.set(1, { note: 60, token: 'token', mpe: false });
+      scheduler._activeNotes.set('token', { note: 60, channel: 1, mpe: false });
       const snapshot = scheduler.getRateSnapshot(0);
       expect(snapshot.next.count).to.be.greaterThan(0);
       scheduler.clearQueue();
       expect(scheduler._ratePlanned.length).to.equal(0);
-    } finally {
-      globalThis.performance = originalPerformance;
-      clock.uninstall();
-    }
-  });
-
-  it('logs when byte rate limits are exceeded', function() {
-    const scheduler = new MidiScheduler({ limits: { maxBytesPerSecond: 1 } });
-    const logs = [];
-    const restoreConsole = withConsoleStub({ error: msg => logs.push(msg) });
-    scheduler.getRateSnapshot = () => ({
-      past: { bytes: 2 },
-      next: { bytes: 0 }
-    });
-    scheduler._lastRateErrorMs = -2000;
-    scheduler._checkByteRate(0);
-    restoreConsole();
-    expect(logs.length).to.equal(1);
-  });
-
-  it('swallows performance measurement errors', function() {
-    const calls = [];
-    const output = makeOutput([1], calls);
-    const originalPerf = globalThis.performance;
-    globalThis.performance = { now: () => 0, measure: () => { throw new Error('boom'); } };
-    try {
-      withGlobalLemmings({ performanceAPI: true }, () => {
-        const scheduler = new MidiScheduler({ mpe: { enabled: false } });
-        scheduler.setOutput(output);
-        const ok = scheduler.sendNote({ note: 60, velocity: 64, durationTicks: 0 });
-        expect(ok).to.equal(true);
-      });
-    } finally {
-      globalThis.performance = originalPerf;
-    }
-  });
-
-  it('computes usage share for rate snapshots', function() {
-    const scheduler = new MidiScheduler({ mpe: { enabled: false } });
-    scheduler._rateSent = [
-      { timeMs: 900, count: 2, bytes: 6, sfxId: 1, priority: 1 }
-    ];
-    const shares = scheduler.getUsageShare('past', 1000);
-    expect(shares.length).to.equal(1);
-    expect(shares[0].sfxId).to.equal(1);
-    expect(shares[0].percentCount).to.equal(1);
-  });
-
-  it('counts pitch bend messages when MPE is disabled', function() {
-    const scheduler = new MidiScheduler({ mpe: { enabled: false } });
-    const estimate = scheduler.estimateMessages({ note: 60, pitchBend: 0.5, durationTicks: 0 });
-    expect(estimate.messages).to.equal(2);
+      expect(scheduler._activeByChannel.size).to.equal(0);
+      expect(scheduler._activeNotes.size).to.equal(0);
+    }, { performanceValue: (clock) => ({ now: () => clock.now, measure: () => {} }) });
   });
 });
diff --git a/test/midi/midi-scheduler.02-midischeduler.test.js b/test/midi/midi-scheduler.02-midischeduler.test.js
new file mode 100644
index 00000000..fc64bad2
--- /dev/null
+++ b/test/midi/midi-scheduler.02-midischeduler.test.js
@@ -0,0 +1,185 @@
+import { expect } from 'chai';
+import { withConsoleStub } from '../helpers/console.js';
+import { withGlobalLemmings } from '../helpers/lemmings.js';
+import { MidiScheduler } from '../../js/midi/MidiScheduler.js';
+import { makeOutput } from '../support/midi-output.js';
+import { withFakeClockAndPerformance } from '../support/timers.js';
+
+describe('MidiScheduler 2', function() {
+  it('reserves proposed messages against past and future traffic', function() {
+    const scheduler = new MidiScheduler({
+      mpe: { enabled: false },
+      limits: {
+        maxEventsPerSecond: 4,
+        maxBytesPerSecond: 999
+      }
+    });
+    scheduler._rateSent = [
+      { timeMs: 500, count: 2, bytes: 6, sfxId: 1, priority: 1 }
+    ];
+    scheduler._ratePlanned = [
+      { timeMs: 1200, count: 1, bytes: 3, sfxId: 2, priority: 1 }
+    ];
+
+    const rejected = scheduler.canSchedule(
+      { on: { timeMs: 1000, count: 2, bytes: 6 } },
+      1000,
+      { maxMessagesPerSecond: 4 }
+    );
+    expect(rejected.ok).to.equal(false);
+    expect(rejected.reason).to.equal('count-limit');
+
+    const reserved = scheduler.reserve(
+      { on: { timeMs: 1000, count: 1, bytes: 3 } },
+      { sfxId: 3, priority: 1 },
+      1000,
+      { maxMessagesPerSecond: 4 }
+    );
+    expect(reserved.ok).to.equal(true);
+    expect(reserved.reservationId).to.be.a('number');
+    const snapshot = scheduler.getRateSnapshot(1000);
+    expect(snapshot.past.count + snapshot.next.count).to.equal(4);
+    expect(snapshot.next.bySfx.get(3).count).to.equal(1);
+  });
+
+  it('preserves routing metadata on reserved rate entries', function() {
+    const scheduler = new MidiScheduler({
+      mpe: { enabled: false },
+      limits: {
+        maxEventsPerSecond: 8,
+        maxBytesPerSecond: 999
+      }
+    });
+
+    const reserved = scheduler.reserve(
+      { on: { timeMs: 1000, count: 1, bytes: 3 } },
+      {
+        sfxId: 3,
+        priority: 2,
+        triggerType: 'skill',
+        trackId: 'lead',
+        outputId: 'out-1',
+        voiceBudget: 4
+      },
+      1000,
+      { maxMessagesPerSecond: 8 }
+    );
+
+    expect(reserved.ok).to.equal(true);
+    expect(reserved.reservationId).to.be.a('number');
+    expect(scheduler._ratePlanned[0]).to.include({
+      reservationId: reserved.reservationId,
+      sfxId: 3,
+      priority: 2,
+      triggerType: 'skill',
+      trackId: 'lead',
+      outputId: 'out-1',
+      voiceBudget: 4
+    });
+  });
+
+  it('aggregates rate snapshots by track and output', function() {
+    const scheduler = new MidiScheduler({ mpe: { enabled: false } });
+    scheduler._ratePlanned = [
+      {
+        timeMs: 1000,
+        count: 2,
+        bytes: 6,
+        sfxId: 3,
+        priority: 2,
+        trackId: 'lead',
+        outputId: 'out-1',
+        voiceBudget: 4
+      },
+      {
+        timeMs: 1100,
+        count: 1,
+        bytes: 3,
+        sfxId: 4,
+        priority: 1,
+        trackId: 'lead',
+        outputId: 'out-1'
+      }
+    ];
+
+    const snapshot = scheduler.getRateSnapshot(1000);
+    expect(snapshot.next.byTrack.get('lead')).to.include({
+      count: 3,
+      bytes: 9,
+      voiceBudget: 4
+    });
+    expect(snapshot.next.byOutput.get('out-1')).to.include({
+      count: 3,
+      bytes: 9,
+      voiceBudget: 4
+    });
+  });
+
+  it('logs when byte rate limits are exceeded', function() {
+    const scheduler = new MidiScheduler({ limits: { maxBytesPerSecond: 1 } });
+    const logs = [];
+    const restoreConsole = withConsoleStub({ error: msg => logs.push(msg) });
+    scheduler.getRateSnapshot = () => ({
+      past: { bytes: 2 },
+      next: { bytes: 0 }
+    });
+    scheduler._lastRateErrorMs = -2000;
+    scheduler._checkByteRate(0);
+    restoreConsole();
+    expect(logs.length).to.equal(1);
+  });
+
+  it('logs when message rate limits are exceeded', function() {
+    const scheduler = new MidiScheduler({
+      limits: {
+        maxEventsPerSecond: 1,
+        maxBytesPerSecond: 999999
+      }
+    });
+    const logs = [];
+    const restoreConsole = withConsoleStub({ error: msg => logs.push(msg) });
+    scheduler.getRateSnapshot = () => ({
+      past: { count: 2, bytes: 0 },
+      next: { count: 0, bytes: 0 }
+    });
+    scheduler._lastRateErrorMs = -2000;
+    scheduler._checkByteRate(0);
+    restoreConsole();
+    expect(logs.length).to.equal(1);
+    expect(logs[0]).to.match(/messages\/sec/i);
+  });
+
+  it('swallows performance measurement errors', function() {
+    const calls = [];
+    const output = makeOutput([1], calls);
+    const originalPerf = globalThis.performance;
+    globalThis.performance = { now: () => 0, measure: () => { throw new Error('boom'); } };
+    try {
+      withGlobalLemmings({ performanceAPI: true }, () => {
+        const scheduler = new MidiScheduler({ mpe: { enabled: false } });
+        scheduler.setOutput(output);
+        const ok = scheduler.sendNote({ note: 60, velocity: 64, durationTicks: 0 });
+        expect(ok).to.equal(true);
+      });
+    } finally {
+      globalThis.performance = originalPerf;
+    }
+  });
+
+  it('computes usage share for rate snapshots', function() {
+    const scheduler = new MidiScheduler({ mpe: { enabled: false } });
+    scheduler._rateSent = [
+      { timeMs: 900, count: 2, bytes: 6, sfxId: 1, priority: 1 }
+    ];
+    const shares = scheduler.getUsageShare('past', 1000);
+    expect(shares.length).to.equal(1);
+    expect(shares[0].sfxId).to.equal(1);
+    expect(shares[0].percentCount).to.equal(1);
+  });
+
+  it('counts pitch bend messages when MPE is disabled', function() {
+    const scheduler = new MidiScheduler({ mpe: { enabled: false } });
+    const estimate = scheduler.estimateMessages({ note: 60, pitchBend: 0.5, durationTicks: 0 });
+    expect(estimate.messages).to.equal(2);
+  });
+});
diff --git a/test/midi/midi-scheduler.coverage.01-midischeduler-coverage-branch-paths-and-fallback.test.js b/test/midi/midi-scheduler.coverage.01-midischeduler-coverage-branch-paths-and-fallback.test.js
new file mode 100644
index 00000000..c4bf8799
--- /dev/null
+++ b/test/midi/midi-scheduler.coverage.01-midischeduler-coverage-branch-paths-and-fallback.test.js
@@ -0,0 +1,317 @@
+import { expect } from 'chai';
+import { withConsoleStub } from '../helpers/console.js';
+import { withGlobalLemmings, withMissingGlobalLemmings } from '../helpers/lemmings.js';
+import { MidiScheduler } from '../../js/midi/MidiScheduler.js';
+import { makeOutput } from '../support/midi-output.js';
+import { withPatchedGlobals } from '../support/globals.js';
+import { withFakeClock, withFakeClockAndPerformance } from '../support/timers.js';
+
+describe('MidiScheduler coverage: branch paths and fallbacks', function() {
+  it('sendNote records performance measurements when enabled', function() {
+    const calls = [];
+    const scheduler = new MidiScheduler({ mpe: { enabled: false }, defaultChannel: 1 });
+    scheduler.setOutput(makeOutput([1], calls));
+    const originalPerf = globalThis.performance;
+    let measures = 0;
+    globalThis.performance = { now: () => 1, measure: () => { measures += 1; } };
+    try {
+      withGlobalLemmings({ performanceAPI: true }, () => {
+        scheduler.sendNote({ note: 60, velocity: 64, durationTicks: 0 });
+        expect(measures).to.equal(1);
+      });
+    } finally {
+      globalThis.performance = originalPerf;
+    }
+  });
+
+  it('scheduleNoteOff appends entries already in order', function() {
+    const scheduler = new MidiScheduler({ mpe: { enabled: false } });
+    scheduler._noteOffs = [{ timeMs: 10 }, { timeMs: 20 }];
+    scheduler._scheduleNoteOff({ timeMs: 30 });
+    expect(scheduler._noteOffs.map(entry => entry.timeMs)).to.eql([10, 20, 30]);
+  });
+
+  it('armNoteOffTimer uses performance timing when available', function() {
+    const scheduler = new MidiScheduler({ mpe: { enabled: false } });
+    withFakeClockAndPerformance(() => {
+      scheduler._noteOffs = [{ timeMs: 5 }];
+      scheduler._armNoteOffTimer();
+      expect(scheduler._noteOffTimerId).to.not.equal(0);
+    }, { performanceValue: { now: () => 0 } });
+  });
+
+  it('processNoteOffs uses Date.now and skips non-mpe cleanup', function() {
+    const calls = [];
+    const scheduler = new MidiScheduler({ mpe: { enabled: false } });
+    scheduler.output = makeOutput([1], calls);
+    const originalPerf = globalThis.performance;
+    const originalDateNow = Date.now;
+    globalThis.performance = undefined;
+    Date.now = () => 0;
+    try {
+      scheduler._activeNotes.set(1, { note: 60, channel: 1, mpe: false, startedAt: 0 });
+      scheduler._noteOffs = [{ timeMs: 0, channel: 1, note: 60, token: 1, mpe: false }];
+      scheduler._processNoteOffs();
+      expect(scheduler._activeNotes.size).to.equal(0);
+    } finally {
+      Date.now = originalDateNow;
+      globalThis.performance = originalPerf;
+    }
+  });
+
+  it('allNotesOff uses default channel when MPE is disabled', function() {
+    const calls = [];
+    const scheduler = new MidiScheduler({ mpe: { enabled: false }, defaultChannel: 3 });
+    scheduler.setOutput(makeOutput([3], calls));
+    scheduler.allNotesOff();
+    const allNotes = calls.filter(call => call.type === 'allNotesOff').map(call => call.id);
+    expect(allNotes).to.eql([3]);
+  });
+
+  it('allNotesOff falls back to channel 1 when default is falsy', function() {
+    const calls = [];
+    const scheduler = new MidiScheduler({ mpe: { enabled: false }, defaultChannel: 0 });
+    scheduler.setOutput(makeOutput([1], calls));
+    scheduler.allNotesOff();
+    const allNotes = calls.filter(call => call.type === 'allNotesOff').map(call => call.id);
+    expect(allNotes).to.eql([1]);
+  });
+
+  it('dispose stops active channels before clearing state', function() {
+    const scheduler = new MidiScheduler({ mpe: { enabled: true } });
+    let stopped = 0;
+    scheduler._stopActiveChannel = () => { stopped += 1; };
+    scheduler._activeByChannel.set(2, { note: 60, token: 1, startedAt: 0 });
+    scheduler.dispose();
+    expect(stopped).to.equal(1);
+  });
+
+  it('covers config fallbacks and early returns', function() {
+    const scheduler = new MidiScheduler();
+    scheduler.setConfig(undefined);
+    expect(scheduler.config).to.eql({});
+
+    scheduler._initMpe();
+    scheduler.setConfig({ mpe: {} });
+    expect(scheduler._memberChannels).to.eql([]);
+
+    scheduler._stopActiveChannel(99);
+    scheduler.output = makeOutput([1], []);
+    scheduler._activeNotes.clear();
+    scheduler._stealOldestNote();
+  });
+
+  it('covers oldest token and missing info branches', function() {
+    const calls = [];
+    const scheduler = new MidiScheduler({ mpe: { enabled: false } });
+    scheduler.setOutput(makeOutput([1], calls));
+    scheduler._activeNotes = new Map([[1, { note: 60, channel: 1, mpe: false, startedAt: NaN }]]);
+    scheduler._stealOldestNote();
+    expect(scheduler._activeNotes.size).to.equal(1);
+
+    scheduler._activeNotes = {
+      size: 1,
+      entries: () => [[1, { note: 60, channel: 1, mpe: true, startedAt: 0 }]],
+      get: () => undefined
+    };
+    scheduler._stealOldestNote();
+    expect(calls.length).to.equal(0);
+  });
+
+  it('removes planned note-off rate entries when stealing active notes', function() {
+    const calls = [];
+    const scheduler = new MidiScheduler({ mpe: { enabled: false } });
+    scheduler.setOutput(makeOutput([1], calls));
+    scheduler._nowMs = () => 0;
+    scheduler._activeNotes.set(1, { note: 60, channel: 1, mpe: false, startedAt: 0 });
+    scheduler._ratePlanned = [
+      { timeMs: 10, count: 1, bytes: 3, token: 1, phase: 'off' },
+      { timeMs: 20, count: 1, bytes: 3, token: 1, phase: 'on' },
+      { timeMs: 30, count: 1, bytes: 3, token: 2, phase: 'off' }
+    ];
+
+    scheduler._stealOldestNote();
+
+    expect(scheduler._ratePlanned.some((entry) => entry.token === 1 && entry.phase === 'off')).to.equal(false);
+    expect(scheduler._ratePlanned.some((entry) => entry.token === 1 && entry.phase === 'on')).to.equal(true);
+    expect(scheduler._ratePlanned.some((entry) => entry.token === 2 && entry.phase === 'off')).to.equal(true);
+    expect(scheduler._rateSent.some((entry) => entry.token === 1 && entry.phase === 'off' && entry.count === 1)).to.equal(true);
+  });
+
+  it('covers perfEnabled permutations and pan handling', function() {
+    const calls = [];
+    const scheduler = new MidiScheduler({
+      mpe: { enabled: false },
+      defaultChannel: 1,
+      position: { panRange: { min: 0, max: 127 } }
+    });
+    scheduler.setOutput(makeOutput([1], calls));
+    const originalPerf = globalThis.performance;
+    try {
+      withMissingGlobalLemmings(() => {
+        scheduler.sendNote({ note: 60, pan: 10, durationTicks: NaN });
+      });
+
+      withGlobalLemmings({ perfMetrics: true }, () => {
+        globalThis.performance = undefined;
+        scheduler.sendNote({ note: 60, pan: 10, durationTicks: NaN });
+      });
+
+      withGlobalLemmings({ performanceAPI: true }, () => {
+        globalThis.performance = { now: () => 1 };
+        scheduler.sendNote({ note: 60, pan: 10, durationTicks: NaN });
+
+        globalThis.performance = { now: () => 1, measure: () => {} };
+        scheduler.sendNote({ note: 60, pan: 10, durationTicks: NaN });
+
+        let measures = 0;
+        scheduler.setConfig({
+          position: { panRange: { min: -127, max: 127 } },
+          defaultChannel: 1,
+          mpe: { enabled: false }
+        });
+        globalThis.performance = { now: () => 1, measure: () => { measures += 1; } };
+        scheduler.sendNote({ note: 60, pan: -10, durationTicks: 1 });
+        expect(measures).to.equal(1);
+      });
+    } finally {
+      globalThis.performance = originalPerf;
+    }
+  });
+
+  it('records last MIDI output message on window', function() {
+    const calls = [];
+    const scheduler = new MidiScheduler({ mpe: { enabled: false }, defaultChannel: 1 });
+    scheduler.setOutput(makeOutput([1], calls));
+    withPatchedGlobals({ window: {} }, () => {
+      scheduler.sendNote({ note: 60, velocity: 64, durationTicks: 0 });
+      expect(globalThis.window.lastMidiOutputMessage.type).to.equal('noteOn');
+    });
+  });
+
+  it('covers additional scheduler branch paths', function() {
+    const scheduler = new MidiScheduler(null);
+    scheduler.setConfig(null);
+    scheduler._initMpe();
+
+    scheduler.setOutput({ channels: {} });
+    scheduler.setConfig({ mpe: { enabled: true } });
+
+    const calls = [];
+    scheduler.setOutput(makeOutput([1], calls));
+    scheduler.setConfig({ mpe: { enabled: true, masterChannel: 1, memberChannels: [2] } });
+
+    scheduler._stealOldestNote();
+    scheduler._stopActiveChannel(99);
+
+    scheduler._rateSent = [{ timeMs: 0, count: 1, bytes: 3, sfxId: 1 }];
+    const snapshot = scheduler.getRateSnapshot(1);
+    expect(snapshot.past.bySfx.get(1).priority).to.equal(1);
+
+    scheduler.setConfig({ mpe: { enabled: false } });
+    const estimate = scheduler.estimateMessages({ note: 60, pitchBend: 0.5 });
+    expect(estimate.messages).to.equal(2);
+
+    scheduler._maxBytesPerSecond = 1000;
+    let errorCount = 0;
+    const restoreConsole = withConsoleStub({ error: () => { errorCount += 1; } });
+    try {
+      scheduler._checkByteRate(0);
+    } finally {
+      restoreConsole();
+    }
+    expect(errorCount).to.equal(0);
+
+    withPatchedGlobals({ performance: { now: () => 1, measure: () => {} } }, () => {
+      withMissingGlobalLemmings(() => {
+        scheduler.sendNote({ note: 60, durationTicks: NaN, pan: 0 });
+      });
+    });
+
+    withFakeClockAndPerformance(() => {
+      scheduler.output = makeOutput([1], []);
+      scheduler._activeNotes.set(1, { note: 60, channel: 1, mpe: false, startedAt: 0 });
+      scheduler._noteOffs = [{ timeMs: 0, token: 1, channel: 1, note: 60, mpe: false }];
+      scheduler._armNoteOffTimer();
+      scheduler._processNoteOffs();
+    }, { performanceValue: { now: () => 0 } });
+
+    const scheduler2 = new MidiScheduler({ mpe: { enabled: true, masterChannel: 1, memberChannels: [2] } });
+    scheduler2.setOutput(makeOutput([1], []));
+    scheduler2._noteOffTimerId = 1;
+    scheduler2.allNotesOff();
+  });
+
+  it('uses Date.now in timers when performance is missing', function() {
+    const scheduler = new MidiScheduler({ mpe: { enabled: false } });
+    withFakeClock(() => {
+      withPatchedGlobals({ performance: undefined }, () => {
+        scheduler._noteOffs = [{ timeMs: 5, token: 1 }];
+        scheduler._armNoteOffTimer();
+        expect(scheduler._noteOffTimerId).to.not.equal(0);
+
+        scheduler.output = makeOutput([1], []);
+        scheduler._activeNotes.set(1, { note: 60, channel: 1, mpe: true, startedAt: 0 });
+        scheduler._activeByChannel.set(1, { note: 60, token: 1, startedAt: 0 });
+        scheduler._noteOffs = [{ timeMs: 0, channel: 1, note: 60, token: 1, mpe: true }];
+        scheduler._processNoteOffs();
+        expect(scheduler._activeByChannel.size).to.equal(0);
+      });
+    });
+  });
+
+  it('clears mpe channels and timers when outputs are missing', function() {
+    const calls = [];
+    const scheduler = new MidiScheduler({ mpe: { enabled: true, masterChannel: 1, memberChannels: [2] } });
+    scheduler.setOutput(makeOutput([1], calls));
+    scheduler._noteOffTimerId = setTimeout(() => {}, 10);
+    scheduler._noteOffs.push({ timeMs: 1, token: 1 });
+    scheduler.allNotesOff();
+    expect(scheduler._noteOffTimerId).to.equal(0);
+    expect(calls.some(call => call.type === 'allNotesOff')).to.equal(true);
+  });
+
+  it('covers allocation fallbacks and rate helpers', function() {
+    const scheduler = new MidiScheduler({ mpe: { enabled: false }, defaultChannel: 9 });
+    expect(scheduler._allocateChannel()).to.equal(9);
+
+    scheduler.setConfig({ mpe: { enabled: true, masterChannel: 7, memberChannels: [] } });
+    scheduler._memberChannels = [];
+    expect(scheduler._allocateChannel()).to.equal(7);
+
+    scheduler._rateSent = [
+      { timeMs: 0, count: 1, bytes: 3, sfxId: 1 },
+      { timeMs: 0, count: 2, bytes: 6, sfxId: 1 }
+    ];
+    const snapshot = scheduler.getRateSnapshot(1);
+    expect(snapshot.past.bySfx.get(1).count).to.equal(3);
+
+    const estimate = scheduler.estimateMessages({ note: 60, pitchBend: 0.5 });
+    expect(estimate.messages).to.equal(2);
+  });
+
+  it('covers stopActiveChannel and cleanup branches', function() {
+    const calls = [];
+    const scheduler = new MidiScheduler({ mpe: { enabled: true, masterChannel: 1, memberChannels: [2] } });
+    scheduler.setOutput(makeOutput([1, 2], calls));
+    scheduler._activeByChannel.set(2, { note: 60, token: 1, startedAt: 0 });
+    scheduler._activeNotes.set(1, { note: 60, channel: 2, mpe: true, startedAt: 0 });
+    scheduler._stopActiveChannel(2);
+    expect(calls.some(call => call.type === 'noteOff')).to.equal(true);
+
+    scheduler._activeNotes.set(2, { note: 61, channel: 2, mpe: true, startedAt: 0 });
+    scheduler._stealOldestNote();
+
+    scheduler.output = null;
+    scheduler._stopActiveChannel(99);
+    scheduler._stealOldestNote();
+
+    scheduler.output = { channels: {} };
+    scheduler._noteOffTimerId = 1;
+    scheduler.allNotesOff();
+    expect(scheduler._noteOffTimerId).to.equal(0);
+
+    scheduler._activeByChannel.set(1, { note: 60, token: 1, startedAt: 0 });
+    scheduler.dispose();
+  });
+});
diff --git a/test/midi/midi-scheduler-coverage.test.js b/test/midi/midi-scheduler.coverage.02-midischeduler-coverage-core-behavior.test.js
similarity index 52%
rename from test/midi/midi-scheduler-coverage.test.js
rename to test/midi/midi-scheduler.coverage.02-midischeduler-coverage-core-behavior.test.js
index b884f874..30404b56 100644
--- a/test/midi/midi-scheduler-coverage.test.js
+++ b/test/midi/midi-scheduler.coverage.02-midischeduler-coverage-core-behavior.test.js
@@ -1,23 +1,12 @@
 import { expect } from 'chai';
 import { withConsoleStub } from '../helpers/console.js';
 import { withGlobalLemmings, withMissingGlobalLemmings } from '../helpers/lemmings.js';
-import FakeTimers from '@sinonjs/fake-timers';
 import { MidiScheduler } from '../../js/midi/MidiScheduler.js';
+import { makeOutput } from '../support/midi-output.js';
+import { withPatchedGlobals } from '../support/globals.js';
+import { withFakeClock, withFakeClockAndPerformance } from '../support/timers.js';
 
-const makeChannel = (id, calls) => ({
-  sendNoteOn(note, opts) { calls.push({ type: 'noteOn', id, note, opts }); },
-  sendNoteOff(note, opts) { calls.push({ type: 'noteOff', id, note, opts }); },
-  sendPitchBend(value, opts) { calls.push({ type: 'pitchBend', id, value, opts }); },
-  sendControlChange(cc, value, opts) { calls.push({ type: 'cc', id, cc, value, opts }); },
-  sendPitchBendRange(semitones, cents) { calls.push({ type: 'bendRange', id, semitones, cents }); },
-  sendAllNotesOff() { calls.push({ type: 'allNotesOff', id }); }
-});
-
-const makeOutput = (ids, calls) => ({
-  channels: Object.fromEntries(ids.map(id => [id, makeChannel(id, calls)]))
-});
-
-describe('MidiScheduler coverage', function() {
+describe('MidiScheduler coverage: core behavior', function() {
   it('initializes MPE when output is already set', function() {
     const calls = [];
     const output = makeOutput([1], calls);
@@ -53,11 +42,13 @@ describe('MidiScheduler coverage', function() {
     const output = makeOutput([2], calls);
     const scheduler = new MidiScheduler({ mpe: { enabled: true, memberChannels: [2] } });
     scheduler.setOutput(output);
+    scheduler._nowMs = () => 0;
     scheduler._activeNotes.set(1, { note: 60, channel: 2, mpe: true, startedAt: 0 });
     scheduler._activeByChannel.set(2, { note: 60, token: 1, startedAt: 0 });
     scheduler._stealOldestNote();
     expect(scheduler._activeByChannel.size).to.equal(0);
     expect(calls.some(call => call.type === 'pitchBend')).to.equal(true);
+    expect(scheduler._rateSent.some((entry) => entry.token === 1 && entry.phase === 'off' && entry.count === 2)).to.equal(true);
   });
 
   it('aggregates unknown sfx ids in rate snapshots', function() {
@@ -120,10 +111,7 @@ describe('MidiScheduler coverage', function() {
   it('processes note offs and clears mpe channel mappings', function() {
     const calls = [];
     const output = makeOutput([2], calls);
-    const clock = FakeTimers.install({ now: 0, toFake: ['setTimeout', 'clearTimeout', 'Date'] });
-    const originalPerformance = globalThis.performance;
-    globalThis.performance = { now: () => clock.now };
-    try {
+    withFakeClockAndPerformance((clock) => {
       const scheduler = new MidiScheduler({ mpe: { enabled: true } });
       scheduler.setOutput(output);
       scheduler._activeNotes.set(1, { note: 60, channel: 2, mpe: true, startedAt: 0 });
@@ -131,10 +119,7 @@ describe('MidiScheduler coverage', function() {
       scheduler._noteOffs.push({ timeMs: 0, channel: 2, note: 60, token: 1, mpe: true });
       scheduler._processNoteOffs();
       expect(scheduler._activeByChannel.size).to.equal(0);
-    } finally {
-      globalThis.performance = originalPerformance;
-      clock.uninstall();
-    }
+    });
   });
 
   it('handles allNotesOff when output is missing', function() {
@@ -277,21 +262,17 @@ describe('MidiScheduler coverage', function() {
 
   it('arms timers and processes note offs with missing outputs', function() {
     const scheduler = new MidiScheduler({ mpe: { enabled: false } });
-    const clock = FakeTimers.install({ now: 0, toFake: ['setTimeout', 'clearTimeout', 'Date'] });
-    const originalPerformance = globalThis.performance;
-    globalThis.performance = undefined;
-    try {
-      scheduler._noteOffTimerId = setTimeout(() => {}, 10);
-      scheduler._noteOffs.push({ timeMs: 0, token: 1 });
-      scheduler._armNoteOffTimer();
-      expect(scheduler._noteOffTimerId).to.not.equal(0);
-      scheduler.output = null;
-      scheduler._processNoteOffs();
-      expect(scheduler._noteOffTimerId).to.equal(0);
-    } finally {
-      globalThis.performance = originalPerformance;
-      clock.uninstall();
-    }
+    withFakeClock(() => {
+      withPatchedGlobals({ performance: undefined }, () => {
+        scheduler._noteOffTimerId = setTimeout(() => {}, 10);
+        scheduler._noteOffs.push({ timeMs: 0, token: 1 });
+        scheduler._armNoteOffTimer();
+        expect(scheduler._noteOffTimerId).to.not.equal(0);
+        scheduler.output = null;
+        scheduler._processNoteOffs();
+        expect(scheduler._noteOffTimerId).to.equal(0);
+      });
+    });
   });
 
   it('allNotesOff handles mpe channel lists and dispose clears active channels', function() {
@@ -309,6 +290,15 @@ describe('MidiScheduler coverage', function() {
     expect(stopped).to.equal(true);
   });
 
+  it('clearQueue resets both planned and sent rate windows', function() {
+    const scheduler = new MidiScheduler({ mpe: { enabled: false } });
+    scheduler._rateSent = [{ timeMs: 0, count: 1, bytes: 3 }];
+    scheduler._ratePlanned = [{ timeMs: 1, count: 1, bytes: 3 }];
+    scheduler.clearQueue();
+    expect(scheduler._rateSent).to.have.length(0);
+    expect(scheduler._ratePlanned).to.have.length(0);
+  });
+
   it('setConfig skips init when no output is present', function() {
     const scheduler = new MidiScheduler({ mpe: { enabled: false } });
     let initCalls = 0;
@@ -411,312 +401,4 @@ describe('MidiScheduler coverage', function() {
     }
     expect(errors.length).to.equal(1);
   });
-
-  it('sendNote records performance measurements when enabled', function() {
-    const calls = [];
-    const scheduler = new MidiScheduler({ mpe: { enabled: false }, defaultChannel: 1 });
-    scheduler.setOutput(makeOutput([1], calls));
-    const originalPerf = globalThis.performance;
-    let measures = 0;
-    globalThis.performance = { now: () => 1, measure: () => { measures += 1; } };
-    try {
-      withGlobalLemmings({ performanceAPI: true }, () => {
-        scheduler.sendNote({ note: 60, velocity: 64, durationTicks: 0 });
-        expect(measures).to.equal(1);
-      });
-    } finally {
-      globalThis.performance = originalPerf;
-    }
-  });
-
-  it('scheduleNoteOff appends entries already in order', function() {
-    const scheduler = new MidiScheduler({ mpe: { enabled: false } });
-    scheduler._noteOffs = [{ timeMs: 10 }, { timeMs: 20 }];
-    scheduler._scheduleNoteOff({ timeMs: 30 });
-    expect(scheduler._noteOffs.map(entry => entry.timeMs)).to.eql([10, 20, 30]);
-  });
-
-  it('armNoteOffTimer uses performance timing when available', function() {
-    const scheduler = new MidiScheduler({ mpe: { enabled: false } });
-    const clock = FakeTimers.install({ now: 0, toFake: ['setTimeout', 'clearTimeout', 'Date'] });
-    const originalPerf = globalThis.performance;
-    globalThis.performance = { now: () => 0 };
-    try {
-      scheduler._noteOffs = [{ timeMs: 5 }];
-      scheduler._armNoteOffTimer();
-      expect(scheduler._noteOffTimerId).to.not.equal(0);
-    } finally {
-      globalThis.performance = originalPerf;
-      clock.uninstall();
-    }
-  });
-
-  it('processNoteOffs uses Date.now and skips non-mpe cleanup', function() {
-    const calls = [];
-    const scheduler = new MidiScheduler({ mpe: { enabled: false } });
-    scheduler.output = makeOutput([1], calls);
-    const originalPerf = globalThis.performance;
-    const originalDateNow = Date.now;
-    globalThis.performance = undefined;
-    Date.now = () => 0;
-    try {
-      scheduler._activeNotes.set(1, { note: 60, channel: 1, mpe: false, startedAt: 0 });
-      scheduler._noteOffs = [{ timeMs: 0, channel: 1, note: 60, token: 1, mpe: false }];
-      scheduler._processNoteOffs();
-      expect(scheduler._activeNotes.size).to.equal(0);
-    } finally {
-      Date.now = originalDateNow;
-      globalThis.performance = originalPerf;
-    }
-  });
-
-  it('allNotesOff uses default channel when MPE is disabled', function() {
-    const calls = [];
-    const scheduler = new MidiScheduler({ mpe: { enabled: false }, defaultChannel: 3 });
-    scheduler.setOutput(makeOutput([3], calls));
-    scheduler.allNotesOff();
-    const allNotes = calls.filter(call => call.type === 'allNotesOff').map(call => call.id);
-    expect(allNotes).to.eql([3]);
-  });
-
-  it('allNotesOff falls back to channel 1 when default is falsy', function() {
-    const calls = [];
-    const scheduler = new MidiScheduler({ mpe: { enabled: false }, defaultChannel: 0 });
-    scheduler.setOutput(makeOutput([1], calls));
-    scheduler.allNotesOff();
-    const allNotes = calls.filter(call => call.type === 'allNotesOff').map(call => call.id);
-    expect(allNotes).to.eql([1]);
-  });
-
-  it('dispose stops active channels before clearing state', function() {        
-    const scheduler = new MidiScheduler({ mpe: { enabled: true } });
-    let stopped = 0;
-    scheduler._stopActiveChannel = () => { stopped += 1; };
-    scheduler._activeByChannel.set(2, { note: 60, token: 1, startedAt: 0 });    
-    scheduler.dispose();
-    expect(stopped).to.equal(1);
-  });
-
-  it('covers config fallbacks and early returns', function() {
-    const scheduler = new MidiScheduler();
-    scheduler.setConfig(undefined);
-    expect(scheduler.config).to.eql({});
-
-    scheduler._initMpe();
-    scheduler.setConfig({ mpe: {} });
-    expect(scheduler._memberChannels).to.eql([]);
-
-    scheduler._stopActiveChannel(99);
-    scheduler.output = makeOutput([1], []);
-    scheduler._activeNotes.clear();
-    scheduler._stealOldestNote();
-  });
-
-  it('covers oldest token and missing info branches', function() {
-    const calls = [];
-    const scheduler = new MidiScheduler({ mpe: { enabled: false } });
-    scheduler.setOutput(makeOutput([1], calls));
-    scheduler._activeNotes = new Map([[1, { note: 60, channel: 1, mpe: false, startedAt: NaN }]]);
-    scheduler._stealOldestNote();
-    expect(scheduler._activeNotes.size).to.equal(1);
-
-    scheduler._activeNotes = {
-      size: 1,
-      entries: () => [[1, { note: 60, channel: 1, mpe: true, startedAt: 0 }]],
-      get: () => undefined
-    };
-    scheduler._stealOldestNote();
-    expect(calls.length).to.equal(0);
-  });
-
-  it('covers perfEnabled permutations and pan handling', function() {
-    const calls = [];
-    const scheduler = new MidiScheduler({
-      mpe: { enabled: false },
-      defaultChannel: 1,
-      position: { panRange: { min: 0, max: 127 } }
-    });
-    scheduler.setOutput(makeOutput([1], calls));
-    const originalPerf = globalThis.performance;
-    try {
-      withMissingGlobalLemmings(() => {
-        scheduler.sendNote({ note: 60, pan: 10, durationTicks: NaN });
-      });
-
-      withGlobalLemmings({ perfMetrics: true }, () => {
-        globalThis.performance = undefined;
-        scheduler.sendNote({ note: 60, pan: 10, durationTicks: NaN });
-      });
-
-      withGlobalLemmings({ performanceAPI: true }, () => {
-        globalThis.performance = { now: () => 1 };
-        scheduler.sendNote({ note: 60, pan: 10, durationTicks: NaN });
-
-        globalThis.performance = { now: () => 1, measure: () => {} };
-        scheduler.sendNote({ note: 60, pan: 10, durationTicks: NaN });
-
-        let measures = 0;
-        scheduler.setConfig({
-          position: { panRange: { min: -127, max: 127 } },
-          defaultChannel: 1,
-          mpe: { enabled: false }
-        });
-        globalThis.performance = { now: () => 1, measure: () => { measures += 1; } };
-        scheduler.sendNote({ note: 60, pan: -10, durationTicks: 1 });
-        expect(measures).to.equal(1);
-      });
-    } finally {
-      globalThis.performance = originalPerf;
-    }
-  });
-
-  it('records last MIDI output message on window', function() {
-    const calls = [];
-    const scheduler = new MidiScheduler({ mpe: { enabled: false }, defaultChannel: 1 });
-    scheduler.setOutput(makeOutput([1], calls));
-    const originalWindow = globalThis.window;
-    globalThis.window = {};
-    try {
-      scheduler.sendNote({ note: 60, velocity: 64, durationTicks: 0 });
-      expect(globalThis.window.lastMidiOutputMessage.type).to.equal('noteOn');
-    } finally {
-      globalThis.window = originalWindow;
-    }
-  });
-
-  it('covers additional scheduler branch paths', function() {
-    const scheduler = new MidiScheduler(null);
-    scheduler.setConfig(null);
-    scheduler._initMpe();
-
-    scheduler.setOutput({ channels: {} });
-    scheduler.setConfig({ mpe: { enabled: true } });
-
-    const calls = [];
-    scheduler.setOutput(makeOutput([1], calls));
-    scheduler.setConfig({ mpe: { enabled: true, masterChannel: 1, memberChannels: [2] } });
-
-    scheduler._stealOldestNote();
-    scheduler._stopActiveChannel(99);
-
-    scheduler._rateSent = [{ timeMs: 0, count: 1, bytes: 3, sfxId: 1 }];
-    const snapshot = scheduler.getRateSnapshot(1);
-    expect(snapshot.past.bySfx.get(1).priority).to.equal(1);
-
-    scheduler.setConfig({ mpe: { enabled: false } });
-    const estimate = scheduler.estimateMessages({ note: 60, pitchBend: 0.5 });
-    expect(estimate.messages).to.equal(2);
-
-    scheduler._maxBytesPerSecond = 1000;
-    let errorCount = 0;
-    const restoreConsole = withConsoleStub({ error: () => { errorCount += 1; } });
-    try {
-      scheduler._checkByteRate(0);
-    } finally {
-      restoreConsole();
-    }
-    expect(errorCount).to.equal(0);
-
-    const originalPerf = globalThis.performance;
-    globalThis.performance = { now: () => 1, measure: () => {} };
-    withMissingGlobalLemmings(() => {
-      scheduler.sendNote({ note: 60, durationTicks: NaN, pan: 0 });
-    });
-    globalThis.performance = originalPerf;
-
-    const clock = FakeTimers.install({ now: 0, toFake: ['setTimeout', 'clearTimeout', 'Date'] });
-    globalThis.performance = { now: () => 0 };
-    try {
-      scheduler.output = makeOutput([1], []);
-      scheduler._activeNotes.set(1, { note: 60, channel: 1, mpe: false, startedAt: 0 });
-      scheduler._noteOffs = [{ timeMs: 0, token: 1, channel: 1, note: 60, mpe: false }];
-      scheduler._armNoteOffTimer();
-      scheduler._processNoteOffs();
-    } finally {
-      clock.uninstall();
-      globalThis.performance = originalPerf;
-    }
-
-    const scheduler2 = new MidiScheduler({ mpe: { enabled: true, masterChannel: 1, memberChannels: [2] } });
-    scheduler2.setOutput(makeOutput([1], []));
-    scheduler2._noteOffTimerId = 1;
-    scheduler2.allNotesOff();
-  });
-
-  it('uses Date.now in timers when performance is missing', function() {
-    const scheduler = new MidiScheduler({ mpe: { enabled: false } });
-    const clock = FakeTimers.install({ now: 0, toFake: ['setTimeout', 'clearTimeout', 'Date'] });
-    const originalPerf = globalThis.performance;
-    globalThis.performance = undefined;
-    try {
-      scheduler._noteOffs = [{ timeMs: 5, token: 1 }];
-      scheduler._armNoteOffTimer();
-      expect(scheduler._noteOffTimerId).to.not.equal(0);
-
-      scheduler.output = makeOutput([1], []);
-      scheduler._activeNotes.set(1, { note: 60, channel: 1, mpe: true, startedAt: 0 });
-      scheduler._activeByChannel.set(1, { note: 60, token: 1, startedAt: 0 });
-      scheduler._noteOffs = [{ timeMs: 0, channel: 1, note: 60, token: 1, mpe: true }];
-      scheduler._processNoteOffs();
-      expect(scheduler._activeByChannel.size).to.equal(0);
-    } finally {
-      globalThis.performance = originalPerf;
-      clock.uninstall();
-    }
-  });
-
-  it('clears mpe channels and timers when outputs are missing', function() {    
-    const calls = [];
-    const scheduler = new MidiScheduler({ mpe: { enabled: true, masterChannel: 1, memberChannels: [2] } });
-    scheduler.setOutput(makeOutput([1], calls));
-    scheduler._noteOffTimerId = setTimeout(() => {}, 10);
-    scheduler._noteOffs.push({ timeMs: 1, token: 1 });
-    scheduler.allNotesOff();
-    expect(scheduler._noteOffTimerId).to.equal(0);
-    expect(calls.some(call => call.type === 'allNotesOff')).to.equal(true);     
-  });
-
-  it('covers allocation fallbacks and rate helpers', function() {
-    const scheduler = new MidiScheduler({ mpe: { enabled: false }, defaultChannel: 9 });
-    expect(scheduler._allocateChannel()).to.equal(9);
-
-    scheduler.setConfig({ mpe: { enabled: true, masterChannel: 7, memberChannels: [] } });
-    scheduler._memberChannels = [];
-    expect(scheduler._allocateChannel()).to.equal(7);
-
-    scheduler._rateSent = [
-      { timeMs: 0, count: 1, bytes: 3, sfxId: 1 },
-      { timeMs: 0, count: 2, bytes: 6, sfxId: 1 }
-    ];
-    const snapshot = scheduler.getRateSnapshot(1);
-    expect(snapshot.past.bySfx.get(1).count).to.equal(3);
-
-    const estimate = scheduler.estimateMessages({ note: 60, pitchBend: 0.5 });
-    expect(estimate.messages).to.equal(2);
-  });
-
-  it('covers stopActiveChannel and cleanup branches', function() {
-    const calls = [];
-    const scheduler = new MidiScheduler({ mpe: { enabled: true, masterChannel: 1, memberChannels: [2] } });
-    scheduler.setOutput(makeOutput([1, 2], calls));
-    scheduler._activeByChannel.set(2, { note: 60, token: 1, startedAt: 0 });
-    scheduler._activeNotes.set(1, { note: 60, channel: 2, mpe: true, startedAt: 0 });
-    scheduler._stopActiveChannel(2);
-    expect(calls.some(call => call.type === 'noteOff')).to.equal(true);
-
-    scheduler._activeNotes.set(2, { note: 61, channel: 2, mpe: true, startedAt: 0 });
-    scheduler._stealOldestNote();
-
-    scheduler.output = null;
-    scheduler._stopActiveChannel(99);
-    scheduler._stealOldestNote();
-
-    scheduler.output = { channels: {} };
-    scheduler._noteOffTimerId = 1;
-    scheduler.allNotesOff();
-    expect(scheduler._noteOffTimerId).to.equal(0);
-
-    scheduler._activeByChannel.set(1, { note: 60, token: 1, startedAt: 0 });
-    scheduler.dispose();
-  });
 });
diff --git a/test/midi/midi-ui-controller.test.js b/test/midi/midi-ui-controller.test.js
index dc05d8d1..73604d0b 100644
--- a/test/midi/midi-ui-controller.test.js
+++ b/test/midi/midi-ui-controller.test.js
@@ -1,1210 +1,1866 @@
 import { expect } from 'chai';
 import { createMidiUiController } from '../../js/app/midiUiController.js';
 import { SoundEffectIds } from '../../js/game/SoundEvents.js';
-import { SkillTypes } from '../../js/game/SkillTypes.js';
 import { TriggerTypes } from '../../js/level/TriggerTypes.js';
-import { TestDocument, TestElement, createTestWindow } from '../helpers/test-dom.js';
-
-const register = (doc, tag, id, className = '') => {
-  const el = doc.createElement(tag);
-  if (className) el.className = className;
-  doc.registerElement(id, el);
-  return el;
-};
-
-if (!TestElement.prototype.contains) {
-  TestElement.prototype.contains = function(target) {
-    if (!target) return false;
-    if (target === this) return true;
-    return (this.children || []).some(child => (
-      typeof child.contains === 'function' ? child.contains(target) : child === target
-    ));
+import { toMidiFlagTriggerType } from '../../js/midi/MidiFlagTriggers.js';
+import { PROJECT_STORAGE_KEY } from '../../js/midi/project/MidiProjectStorage.js';
+import { TestDocument, createTestWindow } from '../helpers/test-dom.js';
+import { registerElement } from '../support/dom-fixtures.js';
+
+const registerSequencerDom = (doc) => {
+  doc.body = doc.createElement('body');
+  const ids = {
+    midiSequencerWorkspace: 'div',
+    midiProjectStatus: 'div',
+    errorDisplay: 'div',
+    midiEnabledToggle: 'input',
+    midiInSelect: 'select',
+    midiOutSelect: 'select',
+    midiInputChannel: 'select',
+    midiBpmBase: 'input',
+    midiTimeSignatureBeats: 'input',
+    midiTimeSignatureUnit: 'select',
+    midiScaleRoot: 'select',
+    midiScaleName: 'select',
+    midiQuantize: 'select',
+    midiSwing: 'input',
+    midiTemplateSelect: 'select',
+    midiProjectResetButton: 'button',
+    midiPanicButton: 'button',
+    midiReversePanicToggle: 'input',
+    midiTemplateSaveButton: 'button',
+    midiProjectExportButton: 'button',
+    midiProjectImportButton: 'button',
+    midiProjectImportInput: 'input',
+    midiSourceSearch: 'input',
+    midiSourceKindFilter: 'select',
+    midiSourceAssignFilter: 'select',
+    midiSourceList: 'div',
+    midiSourceCount: 'span',
+    midiTrackAdd: 'button',
+    midiTrackRemove: 'button',
+    midiTrackList: 'div',
+    midiClipAddButton: 'button',
+    midiClipDuplicateButton: 'button',
+    midiClipRemoveButton: 'button',
+    midiClipList: 'div',
+    midiSelectedSourceSummary: 'div',
+    midiAssignTrackSelect: 'select',
+    midiAssignSourceButton: 'button',
+    midiAuditionButton: 'button',
+    midiClipAuditionButton: 'button',
+    midiTrackName: 'input',
+    midiTrackInstrument: 'input',
+    midiTrackOutputSelect: 'select',
+    midiTrackChannel: 'input',
+    midiTrackPriority: 'input',
+    midiTrackVoiceBudget: 'input',
+    midiTrackVelocityScale: 'input',
+    midiTrackMute: 'input',
+    midiTrackSolo: 'input',
+    midiTrackArm: 'input',
+    midiSourceRevertButton: 'button',
+    midiSourceEnabled: 'input',
+    midiSourceTrackSelect: 'select',
+    midiSourceModeSelect: 'select',
+    midiSourceClipSelect: 'select',
+    midiAssignClipButton: 'button',
+    midiConflictSummary: 'div',
+    midiLearnPanel: 'div',
+    midiLearnStatus: 'div',
+    midiLearnButton: 'button',
+    midiLearnConfirmButton: 'button',
+    midiLearnCancelButton: 'button',
+    midiEnvelopeOverrideToggle: 'input',
+    midiMappingNote: 'input',
+    midiMappingDegree: 'input',
+    midiMappingOctave: 'input',
+    midiMappingVelocity: 'input',
+    midiMappingDuration: 'input',
+    midiMappingChord: 'select',
+    midiMappingChordInversion: 'input',
+    midiMappingArp: 'select',
+    midiMappingPan: 'input',
+    midiMappingTimbre: 'input',
+    midiMappingPitchBend: 'input',
+    midiEnvAttack: 'input',
+    midiEnvDecay: 'input',
+    midiEnvSustain: 'input',
+    midiEnvRelease: 'input',
+    midiClipName: 'input',
+    midiClipType: 'select',
+    midiClipArpModeField: 'label',
+    midiClipArpMode: 'select',
+    midiClipArpPatternField: 'label',
+    midiClipArpPattern: 'select',
+    midiClipLengthSteps: 'input',
+    midiRecordPanel: 'div',
+    midiRecordStatus: 'div',
+    midiRecordButton: 'button',
+    midiRecordCommitButton: 'button',
+    midiRecordCancelButton: 'button',
+    midiStepPatternGrid: 'div',
+    midiGlobalIntensity: 'input',
+    midiGlobalVelocityMin: 'input',
+    midiGlobalVelocityMax: 'input',
+    midiGlobalNoteMin: 'input',
+    midiGlobalNoteMax: 'input',
+    midiGlobalAccent: 'input',
+    midiGlobalViewPan: 'input',
+    midiGlobalPanMin: 'input',
+    midiGlobalPanMax: 'input',
+    midiGlobalPanDeadZone: 'input',
+    midiGlobalTimbreMin: 'input',
+    midiGlobalTimbreMax: 'input',
+    midiGlobalXNoteMin: 'input',
+    midiGlobalXNoteMax: 'input',
+    midiGlobalDensityWindow: 'input',
+    midiGlobalDurationScale: 'input',
+    midiGlobalMaxActiveNotes: 'input',
+    midiGlobalMaxEventsPerTick: 'input',
+    midiGlobalDurationDefault: 'input',
+    midiGlobalDurationMin: 'input',
+    midiGlobalDurationMax: 'input',
+    midiGlobalEnvAttack: 'input',
+    midiGlobalEnvDecay: 'input',
+    midiGlobalEnvSustain: 'input',
+    midiGlobalEnvRelease: 'input',
+    midiAutomationAddButton: 'button',
+    midiAutomationList: 'div',
+    midiSchedulerPressure: 'div',
+    midiOutputLog: 'div'
   };
-}
-
-const findElement = (root, predicate) => {
-  if (predicate(root)) return root;
-  for (const child of root.children || []) {
-    const found = findElement(child, predicate);
-    if (found) return found;
+  for (const [id, tag] of Object.entries(ids)) {
+    registerElement(doc, tag, id);
   }
-  return null;
-};
-
-const findRowInputByLabel = (root, labelText) => {
-  const row = findElement(root, el => (
-    el.tagName === 'LABEL' && el.children?.[0]?.textContent === labelText
-  ));
-  return row?.children?.[1] || null;
-};
-
-const setupRichSelectors = (doc) => {
-  doc.querySelectorAll = (selector) => {
-    const all = doc._all || [];
-    if (selector === 'details[data-section-key]') {
-      return all.filter(el => el.tagName === 'DETAILS' && el.dataset?.sectionKey);
-    }
-    const tabMatch = selector.match(/^\.(tab-button|tab-panel)\[data-tab-group(?:="([^"]*)")?\]$/);
-    if (tabMatch) {
-      const className = tabMatch[1];
-      const group = tabMatch[2];
-      return all.filter(el => (
-        el.classList?.contains(className) &&
-        el.dataset?.tabGroup &&
-        (!group || el.dataset.tabGroup === group)
-      ));
-    }
-    if (selector.startsWith('.')) {
-      const className = selector.slice(1);
-      return all.filter(el => el.classList?.contains(className));
-    }
-    return [];
-  };
-};
-
-const registerRangeInput = (doc, id) => {
-  const wrapper = doc.createElement('div');
-  const minLabel = doc.createElement('span');
-  minLabel.className = 'range-label';
-  const input = doc.createElement('input');
-  const maxLabel = doc.createElement('span');
-  maxLabel.className = 'range-label';
-  wrapper.appendChild(minLabel);
-  wrapper.appendChild(input);
-  wrapper.appendChild(maxLabel);
-  doc.registerElement(id, input);
-  return { wrapper, input, minLabel, maxLabel };
+  doc.getElementById('midiSourceKindFilter').value = 'all';
+  doc.getElementById('midiSourceAssignFilter').value = 'all';
+  doc.getElementById('midiSourceModeSelect').value = 'direct';
+  doc.getElementById('midiMappingArp').value = '';
+  doc.getElementById('midiClipType').value = 'stepPattern';
+  doc.getElementById('midiClipArpMode').value = 'up';
+  doc.getElementById('midiClipArpPattern').value = 'up';
+  doc.getElementById('midiScaleRoot').value = '0';
+  doc.getElementById('midiScaleName').value = 'chromatic-minor';
+  doc.getElementById('midiQuantize').value = '1/16';
+  doc.getElementById('midiTemplateSelect').value = 'midi-mapping';
 };
 
-const createWebMidiStub = (inputs, outputs) => {
-  const listeners = new Map();
-  return {
-    enabled: true,
-    inputs,
-    outputs,
-    getInputById(id) {
-      return (inputs || []).find(device => device.id === id) || null;
+const createControllerHarness = ({
+  factoryConfig = {
+    enabled: false,
+    input: { channel: 'omni' },
+    sfx: { '1': { name: 'skill-select', note: 60, durationTicks: 4 } },
+    triggers: {}
+  },
+  webMidi = { enabled: false, inputs: [], outputs: [] },
+  lemmings = {}
+} = {}) => {
+  const doc = new TestDocument();
+  registerSequencerDom(doc);
+  const win = createTestWindow();
+  const view = {
+    midiEnabled: false,
+    projectConfigs: [],
+    getMidiBaseConfig: () => factoryConfig,
+    setMidiProjectConfig(config) {
+      this.projectConfigs.push(config);
+      this._midiConfig = config;
     },
-    getOutputById(id) {
-      return (outputs || []).find(device => device.id === id) || null;
+    getMidiConfig() {
+      return this._midiConfig || null;
     },
-    addListener(type, handler) {
-      listeners.set(type, handler);
-    },
-    removeListener(type, handler) {
-      if (listeners.get(type) === handler) listeners.delete(type);
+    ...lemmings
+  };
+  const controller = createMidiUiController({
+    window: win,
+    document: doc,
+    getLemmings: () => view,
+    getWebMidi: () => webMidi,
+    downloadTextFile(document, text, filename, mimeType) {
+      view.downloads = view.downloads || [];
+      view.downloads.push({ text, filename, mimeType });
     },
-    emit(type) {
-      const handler = listeners.get(type);
-      if (handler) handler();
+    readTextFile(file) {
+      return Promise.resolve(file?.text ?? '');
     }
-  };
+  });
+  return { controller, doc, win, view, webMidi };
 };
 
-describe('midiUiController', function() {
-  it('persists the enabled toggle and disables controls', function() {
-    const doc = new TestDocument();
-    const win = createTestWindow();
-    const enabledToggle = register(doc, 'input', 'midiEnabledToggle');
-    const inputSelect = register(doc, 'select', 'midiInSelect');
-    const outputSelect = register(doc, 'select', 'midiOutSelect');
-    const inputChannel = register(doc, 'select', 'midiInputChannel');
-    const resetButton = register(doc, 'button', 'midiResetButton');
-    const viewPan = register(doc, 'input', 'midiViewPanToggle');
-    register(doc, 'div', 'errorDisplay');
-
-    const calls = [];
-    const lemmings = { setMidiEnabled(value) { calls.push(value); } };
-    const controller = createMidiUiController({
-      document: doc,
-      window: win,
-      getLemmings: () => lemmings
-    });
+describe('midiUiController sequencer', function() {
+  it('loads a factory project, removes legacy storage, and exposes the project hook', function() {
+    const { controller, win, view } = createControllerHarness();
+    win.localStorage.setItem('lemmings.midi.overrides', '{"sfx":{"1":{"note":99}}}');
 
     controller.bindMidiUi();
-    enabledToggle.checked = false;
-    enabledToggle.dispatchEvent({ type: 'change', target: enabledToggle });
-
-    expect(win.localStorage.getItem('lemmings.midi.enabled')).to.equal('false');
-    expect(calls).to.eql([false]);
-    expect(inputSelect.disabled).to.equal(true);
-    expect(outputSelect.disabled).to.equal(true);
-    expect(inputChannel.disabled).to.equal(true);
-    expect(resetButton.disabled).to.equal(true);
-    expect(viewPan.disabled).to.equal(true);
-  });
 
-  it('stores the input channel and updates overrides', function() {
-    const doc = new TestDocument();
-    const win = createTestWindow();
-    register(doc, 'input', 'midiEnabledToggle');
-    const inputChannel = register(doc, 'select', 'midiInputChannel');
-    register(doc, 'div', 'errorDisplay');
-
-    const controller = createMidiUiController({
-      document: doc,
-      window: win,
-      getLemmings: () => ({})
+    const project = win.__LEMMINGS_MIDI_UI__.getProject();
+    expect(project.sources[0]).to.include({
+      kind: 'sfx',
+      sourceKey: '1',
+      label: 'skill-select'
     });
-    controller.bindMidiUi();
+    expect(win.localStorage.getItem('lemmings.midi.overrides')).to.equal(null);
+    expect(win.localStorage.getItem(PROJECT_STORAGE_KEY)).to.be.a('string');
+    expect(view.projectConfigs.at(-1).sfx['1']).to.include({ note: 60, durationTicks: 4 });
+    expect(win.__LEMMINGS_MIDI_UI__).to.include.keys([
+      'getProject',
+      'dispatchProjectIntent',
+      'setProject',
+      'resetProject',
+      'exportProject',
+      'importProject',
+      'saveProjectTemplate',
+      'getProjectTemplates',
+      'getUiMetrics',
+      'audition',
+      'panic'
+    ]);
+    const metrics = win.__LEMMINGS_MIDI_UI__.getUiMetrics();
+    expect(metrics.renderCount).to.be.at.least(1);
+    expect(metrics.lastRenderDurationMs).to.be.at.least(0);
+    win.__LEMMINGS_MIDI_UI__.dispatchProjectIntent({ type: 'enabled.set', enabled: true });
+    expect(win.__LEMMINGS_MIDI_UI__.getUiMetrics().renderCount).to.be.greaterThan(metrics.renderCount);
+  });
 
-    inputChannel.value = '2';
-    inputChannel.dispatchEvent({ type: 'change', target: inputChannel });
+  it('dispatches project intents and writes only the project storage key', function() {
+    const { controller, win, view } = createControllerHarness();
+    controller.bindMidiUi();
 
-    expect(win.localStorage.getItem('lemmings.midi.inputChannel')).to.equal('2');
-    expect(controller.getMidiOverrides().input.channel).to.equal(2);
+    controller.dispatchProjectIntent({ type: 'enabled.set', enabled: true });
+    controller.dispatchProjectIntent({ type: 'track.add', track: { id: 'lead', name: 'Lead', channel: 3 } });
+    controller.dispatchProjectIntent({ type: 'source.assignTrack', sourceId: 'sfx-1', trackId: 'lead' });
+    controller.dispatchProjectIntent({ type: 'source.mapping.update', sourceId: 'sfx-1', patch: { note: 72, velocity: 100 } });
+
+    const stored = JSON.parse(win.localStorage.getItem(PROJECT_STORAGE_KEY));
+    expect(stored.enabled).to.equal(true);
+    expect(stored.tracks.map(track => track.id)).to.include('lead');
+    expect(stored.sources[0]).to.include({ trackId: 'lead' });
+    expect(stored.sources[0].mapping).to.include({ note: 72, velocity: 100 });
+    expect(win.localStorage.getItem('lemmings.midi.intent')).to.equal(null);
+    expect(win.localStorage.getItem('lemmings.midi.overrides')).to.equal(null);
+    expect(view.projectConfigs.at(-1).sfx['1']).to.include({ note: 72, velocity: 100, channel: 3 });
   });
 
-  it('resets stored overrides when schema hash changes', function() {
-    const doc = new TestDocument();
-    const win = createTestWindow();
-    win.localStorage.setItem('lemmings.midi.overrides', JSON.stringify({ timing: { bpmBase: 90 } }));
-    win.localStorage.setItem('lemmings.midi.schemaHash', 'old');
-    const applied = [];
-    const controller = createMidiUiController({
-      document: doc,
-      window: win,
-      getLemmings: () => ({
-        getMidiSchemaHash: () => 'new',
-        applyMidiOverrides(patch) { applied.push(patch); }
-      })
+  it('edits direct chord inversions and auditions chord notes', function() {
+    const sent = [];
+    const { controller, doc } = createControllerHarness({
+      lemmings: {
+        midiRouter: {
+          scheduler: {
+            sendNote(spec, meta) {
+              sent.push({ spec, meta });
+              return true;
+            },
+            allNotesOff() {},
+            clearQueue() {}
+          }
+        }
+      }
     });
-
     controller.bindMidiUi();
 
-    expect(win.localStorage.getItem('lemmings.midi.overrides')).to.equal(null);
-    expect(win.localStorage.getItem('lemmings.midi.schemaHash')).to.equal('new');
-    expect(controller.getMidiOverrides()).to.eql({});
-    expect(applied).to.eql([{}]);
+    const chord = doc.getElementById('midiMappingChord');
+    chord.value = 'triad';
+    chord.dispatchEvent({ type: 'change', target: chord });
+    const inversion = doc.getElementById('midiMappingChordInversion');
+    inversion.value = '1';
+    inversion.dispatchEvent({ type: 'change', target: inversion });
+
+    const mapping = controller.getProject().sources[0].mapping;
+    expect(mapping.note).to.equal(null);
+    expect(mapping.degree).to.equal(0);
+    expect(mapping.chord).to.deep.equal({ type: 'triad', inversion: 1 });
+    expect(inversion.disabled).to.equal(false);
+
+    expect(controller.audition()).to.equal(true);
+    expect(sent.map(entry => entry.spec.note)).to.deep.equal([50, 52, 60]);
+    expect(sent.every(entry => entry.meta.eventType === 'audition')).to.equal(true);
   });
 
-  it('collapses the left panel when the MIDI title is clicked', function() {
-    const doc = new TestDocument();
-    const win = createTestWindow();
-    const panel = register(doc, 'div', 'controlLeft');
-    const toggle = register(doc, 'div', 'midiPanelToggle');
+  it('skips audition for muted and solo-hidden tracks', function() {
+    const sent = [];
+    const { controller, doc } = createControllerHarness({
+      lemmings: {
+        midiRouter: {
+          scheduler: {
+            sendNote(spec, meta) {
+              sent.push({ spec, meta });
+              return true;
+            }
+          }
+        }
+      }
+    });
+    controller.bindMidiUi();
 
-    const controller = createMidiUiController({
-      document: doc,
-      window: win,
-      getLemmings: () => ({})
+    controller.dispatchProjectIntent({
+      type: 'track.update',
+      trackId: 'track-1',
+      patch: { mute: true }
+    });
+    expect(controller.audition({ sourceId: 'sfx-1' })).to.equal(false);
+    expect(sent).to.have.lengthOf(0);
+    expect(doc.getElementById('midiOutputLog').textContent).to.contain('Audition skipped: Track 1 muted');
+
+    controller.dispatchProjectIntent({
+      type: 'track.update',
+      trackId: 'track-1',
+      patch: { mute: false }
+    });
+    controller.dispatchProjectIntent({
+      type: 'track.add',
+      track: { id: 'lead', name: 'Lead', solo: true }
     });
+    expect(controller.audition({ sourceId: 'sfx-1' })).to.equal(false);
+    expect(sent).to.have.lengthOf(0);
+    expect(doc.getElementById('midiOutputLog').textContent).to.contain('Audition skipped: Track 1 hidden by solo');
+  });
 
+  it('edits direct arp mode and exports it to runtime config', function() {
+    const { controller, doc, view } = createControllerHarness();
     controller.bindMidiUi();
-    toggle.dispatchEvent({ type: 'click' });
-    expect(panel.classList.contains('collapsed')).to.equal(true);
-    expect(win.localStorage.getItem('lemmings.midi.panelCollapsed')).to.equal('true');
-  });
 
-  it('uses config defaults when storage is empty', function() {
-    const doc = new TestDocument();
-    const win = createTestWindow();
-    const viewPan = register(doc, 'input', 'midiViewPanToggle');
-    const inputChannel = register(doc, 'select', 'midiInputChannel');
+    const arp = doc.getElementById('midiMappingArp');
+    arp.value = 'down';
+    arp.dispatchEvent({ type: 'change', target: arp });
 
-    const config = {
-      position: { viewPan: true },
-      input: { channel: 3 },
-      timing: { bpmBase: 120 }
-    };
+    let mapping = controller.getProject().sources[0].mapping;
+    expect(mapping.arp).to.include({ enabled: true, mode: 'down' });
+    expect(view.projectConfigs.at(-1).sfx['1'].arp).to.include({ enabled: true, mode: 'down' });
 
-    const controller = createMidiUiController({
-      document: doc,
-      window: win,
-      getMidiConfig: () => config
-    });
+    arp.value = '';
+    arp.dispatchEvent({ type: 'change', target: arp });
+    mapping = controller.getProject().sources[0].mapping;
+    expect(mapping.arp).to.equal(null);
+    expect(view.projectConfigs.at(-1).sfx['1'].arp).to.equal(undefined);
+  });
 
+  it('edits direct expression controls and exports them to runtime config', function() {
+    const { controller, doc, view } = createControllerHarness();
     controller.bindMidiUi();
-    controller.refreshMidiUiFromConfig();
 
-    expect(viewPan.checked).to.equal(true);
-    expect(inputChannel.value).to.equal('3');
-    expect(win.localStorage.getItem('lemmings.midi.viewPan')).to.equal(null);
-    expect(win.localStorage.getItem('lemmings.midi.inputChannel')).to.equal(null);
+    const pan = doc.getElementById('midiMappingPan');
+    pan.value = '-32';
+    pan.dispatchEvent({ type: 'change', target: pan });
+    const timbre = doc.getElementById('midiMappingTimbre');
+    timbre.value = '91';
+    timbre.dispatchEvent({ type: 'change', target: timbre });
+    const bend = doc.getElementById('midiMappingPitchBend');
+    bend.value = '0.5';
+    bend.dispatchEvent({ type: 'change', target: bend });
+
+    const mapping = controller.getProject().sources[0].mapping;
+    expect(mapping).to.include({ pan: -32, timbre: 91, pitchBend: 0.5 });
+    expect(view.projectConfigs.at(-1).sfx['1']).to.include({ pan: -32, timbre: 91, pitchBend: 0.5 });
   });
 
-  it('shows omni when input channel defaults to omni', function() {
-    const doc = new TestDocument();
-    const win = createTestWindow();
-    const inputChannel = register(doc, 'select', 'midiInputChannel');
+  it('edits transport time signature controls', function() {
+    const { controller, doc, win, view } = createControllerHarness();
+    controller.bindMidiUi();
 
-    const controller = createMidiUiController({
-      document: doc,
-      window: win,
-      getMidiConfig: () => ({ input: { channel: 'omni' }, timing: { bpmBase: 120 } })
+    const beats = doc.getElementById('midiTimeSignatureBeats');
+    beats.value = '7';
+    beats.dispatchEvent({ type: 'change', target: beats });
+    const unit = doc.getElementById('midiTimeSignatureUnit');
+    unit.value = '8';
+    unit.dispatchEvent({ type: 'change', target: unit });
+    const quantize = doc.getElementById('midiQuantize');
+    quantize.value = '1/8';
+    quantize.dispatchEvent({ type: 'change', target: quantize });
+    const swing = doc.getElementById('midiSwing');
+    swing.value = '0.25';
+    swing.dispatchEvent({ type: 'change', target: swing });
+    const scaleRoot = doc.getElementById('midiScaleRoot');
+    scaleRoot.value = '2';
+    scaleRoot.dispatchEvent({ type: 'change', target: scaleRoot });
+    const scaleName = doc.getElementById('midiScaleName');
+    scaleName.value = 'major';
+    scaleName.dispatchEvent({ type: 'change', target: scaleName });
+    const reversePanic = doc.getElementById('midiReversePanicToggle');
+    reversePanic.checked = true;
+    reversePanic.dispatchEvent({ type: 'change', target: reversePanic });
+
+    const stored = JSON.parse(win.localStorage.getItem(PROJECT_STORAGE_KEY));
+    expect(stored.transport.timeSignature).to.deep.equal({ beats: 7, unit: 8 });
+    expect(stored.transport).to.include({ quantize: '1/8', swing: 0.25 });
+    expect(stored.global.scale).to.include({ name: 'major', root: 2 });
+    expect(stored.global.scale.degrees).to.deep.equal([0, 2, 4, 5, 7, 9, 11]);
+    expect(stored.global.reverse.allNotesOffOnToggle).to.equal(true);
+    expect(view.projectConfigs.at(-1).timing.timeSignature).to.deep.equal({ beats: 7, unit: 8 });
+    expect(view.projectConfigs.at(-1).timing).to.include({ quantize: '1/8', swing: 0.25 });
+    expect(view.projectConfigs.at(-1).scale).to.include({ name: 'major', root: 2 });
+    expect(view.projectConfigs.at(-1).scale.degrees).to.deep.equal([0, 2, 4, 5, 7, 9, 11]);
+    expect(view.projectConfigs.at(-1).reverse.allNotesOffOnToggle).to.equal(true);
+
+    controller.applyRuntimePatch({
+      timing: { timeSignature: { beats: 5, unit: 16 }, quantize: '1/32', swing: 0.5 },
+      scale: { name: 'minor', root: 5 }
     });
+    const patched = JSON.parse(win.localStorage.getItem(PROJECT_STORAGE_KEY));
+    expect(patched.transport.timeSignature).to.deep.equal({ beats: 5, unit: 16 });
+    expect(patched.transport).to.include({ quantize: '1/32', swing: 0.5 });
+    expect(patched.global.scale).to.include({ name: 'minor', root: 5 });
+    expect(patched.global.scale.degrees).to.deep.equal([0, 2, 3, 5, 7, 8, 10]);
+    expect(view.projectConfigs.at(-1).timing.timeSignature).to.deep.equal({ beats: 5, unit: 16 });
+    expect(view.projectConfigs.at(-1).timing).to.include({ quantize: '1/32', swing: 0.5 });
+    expect(view.projectConfigs.at(-1).scale).to.include({ name: 'minor', root: 5 });
+    expect(view.projectConfigs.at(-1).scale.degrees).to.deep.equal([0, 2, 3, 5, 7, 8, 10]);
+  });
 
-    controller.refreshMidiUiFromConfig();
-    expect(inputChannel.value).to.equal('omni');
+  it('edits arp clip mode and lowers it into runtime config', function() {
+    const { controller, doc, view } = createControllerHarness();
+    controller.bindMidiUi();
+    controller.dispatchProjectIntent({ type: 'clip.add', clip: { id: 'riff', name: 'Riff', type: 'arp', lengthSteps: 2 } });
+    controller.dispatchProjectIntent({ type: 'clip.step.update', clipId: 'riff', stepIndex: 0, patch: { note: 64 } });
+    controller.dispatchProjectIntent({ type: 'clip.step.update', clipId: 'riff', stepIndex: 1, patch: { note: 67 } });
+    controller.dispatchProjectIntent({ type: 'source.clip.assign', sourceId: 'sfx-1', clipId: 'riff' });
+
+    const arpField = doc.getElementById('midiClipArpModeField');
+    const arpMode = doc.getElementById('midiClipArpMode');
+    const arpPatternField = doc.getElementById('midiClipArpPatternField');
+    const arpPattern = doc.getElementById('midiClipArpPattern');
+    arpPatternField.appendChild(arpPattern);
+    expect(arpField.style.display).to.equal('');
+    expect(arpMode.disabled).to.equal(false);
+    expect(arpPatternField.style.display).to.equal('');
+    expect(arpPattern.disabled).to.equal(false);
+    expect(arpMode.value).to.equal('up');
+    expect(arpPattern.value).to.equal('up');
+
+    arpMode.value = 'updown';
+    arpMode.dispatchEvent({ type: 'change', target: arpMode });
+
+    const clip = controller.getProject().clips.find(entry => entry.id === 'riff');
+    expect(clip.arp).to.include({ mode: 'updown' });
+    expect(clip.arp.pattern.preset).to.equal('updown');
+    expect(view.projectConfigs.at(-1).sfx['1'].arp).to.include({ enabled: true, mode: 'updown', length: 2 });
+
+    arpPattern.value = 'custom';
+    arpPattern.dispatchEvent({ type: 'change', target: arpPattern });
+    const customClip = controller.getProject().clips.find(entry => entry.id === 'riff');
+    expect(customClip.arp.pattern.preset).to.equal('custom');
+    expect(customClip.arp.pattern.steps).to.deep.equal(['up', 'hold', 'down', 'hold', 'up', 'hold', 'down', 'hold']);
+    expect(view.projectConfigs.at(-1).sfx['1'].arp.pattern.preset).to.equal('custom');
+
+    arpPattern.focus();
+    expect(doc.activeElement).to.equal(arpPattern);
+    const clipType = doc.getElementById('midiClipType');
+    clipType.value = 'stepPattern';
+    clipType.dispatchEvent({ type: 'change', target: clipType });
+    expect(arpField.style.display).to.equal('none');
+    expect(arpMode.disabled).to.equal(true);
+    expect(arpPatternField.style.display).to.equal('none');
+    expect(arpPattern.disabled).to.equal(true);
+    expect(doc.activeElement).to.equal(clipType);
   });
 
-  it('populates key, scale, and event lists with default data', function() {
-    const doc = new TestDocument();
-    const win = createTestWindow();
-    const keySelect = register(doc, 'select', 'midiKeySelect');
-    const scaleSelect = register(doc, 'select', 'midiScaleSelect');
-    const eventList = register(doc, 'div', 'midiEventList');
-
-    const controller = createMidiUiController({
-      document: doc,
-      window: win,
-      getMidiConfig: () => ({ timing: { bpmBase: 120 }, sfx: {} })
+  it('edits modulation controls and exports runtime automation config', function() {
+    const { controller, doc, win, view } = createControllerHarness({
+      factoryConfig: {
+        enabled: false,
+        input: { channel: 'omni' },
+        position: { mappings: [] },
+        sfx: { '1': { name: 'skill-select', note: 60, durationTicks: 4 } },
+        triggers: {}
+      }
     });
+    controller.bindMidiUi();
 
-    controller.refreshMidiUiFromConfig();
-
-    expect(keySelect.children.length).to.be.greaterThan(1);
-    expect(scaleSelect.children.length).to.be.greaterThan(0);
-    expect(eventList.children.length).to.be.greaterThan(0);
-  });
-
-  it('updates current bpm when base bpm changes', function() {
-    const doc = new TestDocument();
-    const win = createTestWindow();
-    const bpmBase = register(doc, 'input', 'midiBpmBase');
-    const bpmCurrent = register(doc, 'span', 'midiBpmCurrent');
-    register(doc, 'input', 'midiEnabledToggle');
-    register(doc, 'div', 'errorDisplay');
-
-    const controller = createMidiUiController({
-      document: doc,
-      window: win,
-      getLemmings: () => ({ gameSpeedFactor: 2 }),
-      getMidiConfig: () => ({ timing: { bpmBase: 120 } })
+    const velocityScale = doc.getElementById('midiTrackVelocityScale');
+    velocityScale.value = '0.5';
+    velocityScale.dispatchEvent({ type: 'change', target: velocityScale });
+    const intensity = doc.getElementById('midiGlobalIntensity');
+    intensity.value = '96';
+    intensity.dispatchEvent({ type: 'change', target: intensity });
+    const velocityMin = doc.getElementById('midiGlobalVelocityMin');
+    velocityMin.value = '20';
+    velocityMin.dispatchEvent({ type: 'change', target: velocityMin });
+    const velocityMax = doc.getElementById('midiGlobalVelocityMax');
+    velocityMax.value = '110';
+    velocityMax.dispatchEvent({ type: 'change', target: velocityMax });
+    const noteMin = doc.getElementById('midiGlobalNoteMin');
+    noteMin.value = '36';
+    noteMin.dispatchEvent({ type: 'change', target: noteMin });
+    const noteMax = doc.getElementById('midiGlobalNoteMax');
+    noteMax.value = '96';
+    noteMax.dispatchEvent({ type: 'change', target: noteMax });
+    const accent = doc.getElementById('midiGlobalAccent');
+    accent.value = '0.8';
+    accent.dispatchEvent({ type: 'change', target: accent });
+    const densityWindow = doc.getElementById('midiGlobalDensityWindow');
+    densityWindow.value = '12';
+    densityWindow.dispatchEvent({ type: 'change', target: densityWindow });
+    const durationScale = doc.getElementById('midiGlobalDurationScale');
+    durationScale.value = '0.25';
+    durationScale.dispatchEvent({ type: 'change', target: durationScale });
+    const maxActiveNotes = doc.getElementById('midiGlobalMaxActiveNotes');
+    maxActiveNotes.value = '24';
+    maxActiveNotes.dispatchEvent({ type: 'change', target: maxActiveNotes });
+    const maxEventsPerTick = doc.getElementById('midiGlobalMaxEventsPerTick');
+    maxEventsPerTick.value = '16';
+    maxEventsPerTick.dispatchEvent({ type: 'change', target: maxEventsPerTick });
+    const durationDefault = doc.getElementById('midiGlobalDurationDefault');
+    durationDefault.value = '10';
+    durationDefault.dispatchEvent({ type: 'change', target: durationDefault });
+    const durationMin = doc.getElementById('midiGlobalDurationMin');
+    durationMin.value = '2';
+    durationMin.dispatchEvent({ type: 'change', target: durationMin });
+    const durationMax = doc.getElementById('midiGlobalDurationMax');
+    durationMax.value = '32';
+    durationMax.dispatchEvent({ type: 'change', target: durationMax });
+    const viewPan = doc.getElementById('midiGlobalViewPan');
+    viewPan.checked = true;
+    viewPan.dispatchEvent({ type: 'change', target: viewPan });
+    const panMin = doc.getElementById('midiGlobalPanMin');
+    panMin.value = '-48';
+    panMin.dispatchEvent({ type: 'change', target: panMin });
+    const panMax = doc.getElementById('midiGlobalPanMax');
+    panMax.value = '48';
+    panMax.dispatchEvent({ type: 'change', target: panMax });
+    const panDeadZone = doc.getElementById('midiGlobalPanDeadZone');
+    panDeadZone.value = '0.08';
+    panDeadZone.dispatchEvent({ type: 'change', target: panDeadZone });
+    const timbreMin = doc.getElementById('midiGlobalTimbreMin');
+    timbreMin.value = '12';
+    timbreMin.dispatchEvent({ type: 'change', target: timbreMin });
+    const timbreMax = doc.getElementById('midiGlobalTimbreMax');
+    timbreMax.value = '100';
+    timbreMax.dispatchEvent({ type: 'change', target: timbreMax });
+    const xNoteMin = doc.getElementById('midiGlobalXNoteMin');
+    xNoteMin.value = '-18';
+    xNoteMin.dispatchEvent({ type: 'change', target: xNoteMin });
+    const xNoteMax = doc.getElementById('midiGlobalXNoteMax');
+    xNoteMax.value = '18';
+    xNoteMax.dispatchEvent({ type: 'change', target: xNoteMax });
+    const globalAttack = doc.getElementById('midiGlobalEnvAttack');
+    globalAttack.value = '1.25';
+    globalAttack.dispatchEvent({ type: 'change', target: globalAttack });
+    const globalRelease = doc.getElementById('midiGlobalEnvRelease');
+    globalRelease.value = '0.75';
+    globalRelease.dispatchEvent({ type: 'change', target: globalRelease });
+    const envelopeToggle = doc.getElementById('midiEnvelopeOverrideToggle');
+    envelopeToggle.checked = true;
+    envelopeToggle.dispatchEvent({ type: 'change', target: envelopeToggle });
+
+    doc.getElementById('midiAutomationAddButton').dispatchEvent({ type: 'click', target: doc.getElementById('midiAutomationAddButton') });
+    const automationRow = doc.getElementById('midiAutomationList').children[0];
+    const axisOp = automationRow.children
+      .flatMap(child => child.children || [])
+      .find(child => child.className === 'midi-automation-axis-op');
+    axisOp.value = 'mul';
+    axisOp.dispatchEvent({ type: 'change', target: axisOp });
+    const pointBeat = automationRow.children
+      .flatMap(child => child.children || [])
+      .find(child => child.className === 'midi-automation-point-beat');
+    const pointValue = automationRow.children
+      .flatMap(child => child.children || [])
+      .find(child => child.className === 'midi-automation-point-value');
+    expect(pointBeat.value).to.equal('0');
+    expect(pointValue.value).to.equal('-12');
+    pointBeat.value = '2';
+    pointBeat.dispatchEvent({ type: 'change', target: pointBeat });
+    pointValue.value = '0.7';
+    pointValue.dispatchEvent({ type: 'change', target: pointValue });
+
+    const stored = JSON.parse(win.localStorage.getItem(PROJECT_STORAGE_KEY));
+    expect(stored.tracks[0].velocityScale).to.equal(0.5);
+    expect(stored.global.velocityRange).to.include({ default: 96, min: 20, max: 110 });
+    expect(stored.global.noteRange).to.include({ min: 36, max: 96 });
+    expect(stored.global.density).to.include({ velocityBoost: 0.8, windowTicks: 12, durationScale: 0.25 });
+    expect(stored.global.limits).to.include({ maxActiveNotes: 24, maxEventsPerTick: 16 });
+    expect(stored.global.durationTicks).to.include({ default: 10, min: 2, max: 32 });
+    expect(stored.global.position.viewPan).to.equal(true);
+    expect(stored.global.position.panRange).to.deep.equal({ min: -48, max: 48 });
+    expect(stored.global.position.panDeadZonePct).to.equal(0.08);
+    expect(stored.global.position.timbreRange).to.deep.equal({ min: 12, max: 100 });
+    expect(stored.global.position.xNoteRange).to.deep.equal({ min: -18, max: 18 });
+    expect(stored.global.envelope).to.include({ attack: 1.25, release: 0.75 });
+    expect(stored.sources[0].mapping.envelope).to.deep.equal({ attack: 1, decay: 0, sustain: 1, release: 1 });
+    expect(stored.automation).to.have.lengthOf(1);
+    expect(stored.automation[0].axisOp).to.equal('mul');
+    expect(stored.automation[0].points[0]).to.deep.equal({ beat: 2, value: 0.7 });
+    expect(automationRow.className).to.equal('midi-automation-row');
+
+    const runtime = view.projectConfigs.at(-1);
+    expect(runtime.velocityRange).to.include({ default: 96, min: 20, max: 110 });
+    expect(runtime.noteRange).to.include({ min: 36, max: 96 });
+    expect(runtime.density).to.include({ velocityBoost: 0.8, windowTicks: 12, durationScale: 0.25 });
+    expect(runtime.limits).to.include({ maxActiveNotes: 24, maxEventsPerTick: 16 });
+    expect(runtime.durationTicks).to.include({ default: 10, min: 2, max: 32 });
+    expect(runtime.position.viewPan).to.equal(true);
+    expect(runtime.position.panRange).to.deep.equal({ min: -48, max: 48 });
+    expect(runtime.position.panDeadZonePct).to.equal(0.08);
+    expect(runtime.position.timbreRange).to.deep.equal({ min: 12, max: 100 });
+    expect(runtime.position.xNoteRange).to.deep.equal({ min: -18, max: 18 });
+    expect(runtime.envelope).to.include({ attack: 1.25, release: 0.75 });
+    expect(runtime.position.mappings[0]).to.include({ target: 'note', axis: 'x', axisOp: 'mul', enabled: true });
+    expect(runtime.position.mappings[0].points).to.deep.equal([{ beat: 2, value: 0.7 }]);
+    expect(runtime.sfx['1'].velocity).to.equal(48);
+
+    controller.applyRuntimePatch({
+      noteRange: { min: 48, max: 84 },
+      velocityRange: { min: 24, max: 112 },
+      density: { windowTicks: 18, durationScale: 0.75 },
+      durationTicks: { default: 12, min: 3, max: 48 },
+      envelope: { sustain: 1.5 },
+      position: {
+        panRange: { min: -64, max: 64 },
+        timbreRange: { min: 10, max: 100 },
+        panDeadZonePct: 0.1
+      },
+      mpe: { enabled: false, masterChannel: 3 },
+      limits: { maxActiveNotes: 12, maxEventsPerTick: 8 },
+      reverse: { allNotesOffOnToggle: true }
     });
+    const afterPatch = JSON.parse(win.localStorage.getItem(PROJECT_STORAGE_KEY));
+    expect(afterPatch.global.noteRange).to.include({ min: 48, max: 84 });
+    expect(afterPatch.global.velocityRange).to.include({ default: 96, min: 24, max: 112 });
+    expect(afterPatch.global.density).to.include({ windowTicks: 18, durationScale: 0.75 });
+    expect(afterPatch.global.durationTicks).to.include({ default: 12, min: 3, max: 48 });
+    expect(afterPatch.global.envelope.sustain).to.equal(1.5);
+    expect(afterPatch.global.position.panRange).to.deep.equal({ min: -64, max: 64 });
+    expect(afterPatch.global.position.timbreRange).to.deep.equal({ min: 10, max: 100 });
+    expect(afterPatch.global.position.panDeadZonePct).to.equal(0.1);
+    expect(afterPatch.global.mpe).to.include({ enabled: false, masterChannel: 3 });
+    expect(afterPatch.global.limits).to.include({ maxActiveNotes: 12, maxEventsPerTick: 8 });
+    expect(afterPatch.global.reverse).to.include({ allNotesOffOnToggle: true });
+    expect(view.projectConfigs.at(-1).noteRange).to.include({ min: 48, max: 84 });
+    expect(view.projectConfigs.at(-1).velocityRange).to.include({ default: 96, min: 24, max: 112 });
+    expect(view.projectConfigs.at(-1).density).to.include({ windowTicks: 18, durationScale: 0.75 });
+    expect(view.projectConfigs.at(-1).durationTicks).to.include({ default: 12, min: 3, max: 48 });
+    expect(view.projectConfigs.at(-1).envelope.sustain).to.equal(1.5);
+    expect(view.projectConfigs.at(-1).position.panRange).to.deep.equal({ min: -64, max: 64 });
+    expect(view.projectConfigs.at(-1).position.timbreRange).to.deep.equal({ min: 10, max: 100 });
+    expect(view.projectConfigs.at(-1).position.panDeadZonePct).to.equal(0.1);
+    expect(view.projectConfigs.at(-1).mpe).to.include({ enabled: false, masterChannel: 3 });
+    expect(view.projectConfigs.at(-1).limits).to.include({ maxActiveNotes: 12, maxEventsPerTick: 8 });
+    expect(view.projectConfigs.at(-1).reverse).to.include({ allNotesOffOnToggle: true });
+
+    const removeButton = doc.getElementById('midiAutomationList').children[0].children.find(child => child.className === 'midi-automation-remove');
+    removeButton.dispatchEvent({ type: 'click', target: removeButton });
+    const afterRemove = JSON.parse(win.localStorage.getItem(PROJECT_STORAGE_KEY));
+    expect(afterRemove.automation).to.have.lengthOf(0);
+    expect(view.projectConfigs.at(-1).position.mappings).to.have.lengthOf(0);
+    expect(doc.getElementById('midiAutomationList').children[0].textContent).to.equal('No modulation lanes');
+  });
 
+  it('exports, imports, saves templates, and resets from a user template', async function() {
+    const { controller, doc, win, view } = createControllerHarness();
     controller.bindMidiUi();
-    bpmBase.value = '100';
-    bpmBase.dispatchEvent({ type: 'input', target: bpmBase });
 
-    expect(bpmCurrent.textContent).to.contain('2x 100 = 200 BPM');
+    controller.dispatchProjectIntent({ type: 'source.mapping.update', sourceId: 'sfx-1', patch: { note: 76 } });
+    const exported = controller.exportProject();
+    expect(exported.project.sources[0].mapping.note).to.equal(76);
+    expect(view.downloads[0]).to.include({
+      filename: 'factory-midi-project.lemmings-midi-project.json',
+      mimeType: 'application/json'
+    });
+    expect(JSON.parse(view.downloads[0].text).project.sources[0].mapping.note).to.equal(76);
+    expect(doc.getElementById('midiProjectStatus').textContent).to.equal('Exported project');
+    expect(doc.getElementById('midiOutputLog').textContent).to.contain('Exported project');
+
+    const template = controller.saveProjectTemplate({ id: 'lead-template', name: 'Lead Template', now: 10 });
+    expect(template).to.include({ id: 'lead-template', name: 'Lead Template' });
+    expect(controller.getProjectTemplates().map(entry => entry.id)).to.deep.equal(['lead-template']);
+    expect(doc.getElementById('midiTemplateSelect').children.map(option => option.value)).to.include('lead-template');
+    expect(doc.getElementById('midiProjectStatus').textContent).to.equal('Saved template Lead Template');
+    expect(doc.getElementById('midiOutputLog').textContent).to.contain('Saved template Lead Template');
+
+    const importedPayload = JSON.stringify({
+      kind: 'lemmings.midi.project',
+      version: 1,
+      project: {
+        ...controller.getProject(),
+        name: 'Imported Project',
+        sources: [
+          {
+            ...controller.getProject().sources[0],
+            mapping: { ...controller.getProject().sources[0].mapping, note: 81 }
+          }
+        ]
+      }
+    });
+    const imported = controller.importProject(importedPayload);
+    expect(imported).to.include({ name: 'Imported Project' });
+    expect(imported.sources[0].mapping.note).to.equal(81);
+    expect(JSON.parse(win.localStorage.getItem(PROJECT_STORAGE_KEY)).sources[0].mapping.note).to.equal(81);
+
+    doc.getElementById('midiTemplateSelect').value = 'lead-template';
+    const reset = controller.resetProject('lead-template');
+    expect(reset).to.include({ name: 'Lead Template', templateId: 'lead-template' });
+    expect(reset.sources[0].mapping.note).to.equal(76);
+    expect(doc.getElementById('midiProjectStatus').textContent).to.equal('Reset project from Lead Template');
+    expect(doc.getElementById('midiOutputLog').textContent).to.contain('Reset project from Lead Template');
+
+    await controller.importProjectFile({ text: '{"bad":' });
+    expect(doc.getElementById('errorDisplay').textContent).to.contain('not valid JSON');
+    expect(doc.getElementById('midiOutputLog').textContent).to.contain('Import failed:');
+    expect(doc.getElementById('midiOutputLog').textContent).to.contain('not valid JSON');
   });
 
-  it('populates position mapping defaults when ranges are missing', function() {
-    const doc = new TestDocument();
-    const win = createTestWindow();
-    const positionList = register(doc, 'div', 'midiPositionList');
-
-    const controller = createMidiUiController({
-      document: doc,
-      window: win,
-      getMidiConfig: () => ({
-        position: {
-          mappings: [{ axis: 'x', target: 'pan' }],
-          panRange: { min: -50, max: 50 }
-        },
-        timing: { bpmBase: 120 }
-      })
+  it('runs template operations from keyboard shortcuts', function() {
+    const { controller, doc, view } = createControllerHarness();
+    controller.bindMidiUi();
+    const workspace = doc.getElementById('midiSequencerWorkspace');
+    const importInput = doc.getElementById('midiProjectImportInput');
+    let importClicks = 0;
+    let prevented = 0;
+    let stopped = 0;
+    importInput.click = () => {
+      importClicks += 1;
+    };
+    const dispatchShortcut = (target, key) => target.dispatchEvent({
+      type: 'keydown',
+      key,
+      ctrlKey: true,
+      preventDefault() {
+        prevented += 1;
+      },
+      stopPropagation() {
+        stopped += 1;
+      }
     });
 
-    controller.refreshMidiUiFromConfig();
-
-    const rangeRow = findElement(positionList, el => (
-      el.tagName === 'LABEL' && el.children?.[0]?.textContent === 'Min / Max'
-    ));
-    const rangeInputs = rangeRow?.children?.[1] || null;
-    const minInput = rangeInputs?.children?.[0] || null;
-    const maxInput = rangeInputs?.children?.[1] || null;
-    expect(minInput).to.be.ok;
-    expect(maxInput).to.be.ok;
-    expect(minInput.value).to.equal('');
-    expect(maxInput.value).to.equal('');
-    expect(minInput.placeholder).to.equal('-50');
-    expect(maxInput.placeholder).to.equal('50');
+    dispatchShortcut(workspace, 's');
+    const template = controller.getProjectTemplates()[0];
+    expect(template.name).to.equal('Factory MIDI Project Template');
+    expect(doc.getElementById('midiProjectStatus').textContent).to.equal('Saved template Factory MIDI Project Template');
+
+    dispatchShortcut(workspace, 'e');
+    expect(view.downloads.at(-1).filename).to.equal('factory-midi-project.lemmings-midi-project.json');
+    expect(doc.getElementById('midiProjectStatus').textContent).to.equal('Exported project');
+
+    dispatchShortcut(workspace, 'i');
+    expect(importClicks).to.equal(1);
+
+    controller.dispatchProjectIntent({ type: 'source.mapping.update', sourceId: 'sfx-1', patch: { note: 83 } });
+    const templateSelect = doc.getElementById('midiTemplateSelect');
+    templateSelect.value = template.id;
+    dispatchShortcut(templateSelect, 'Enter');
+    expect(controller.getProject()).to.include({ name: 'Factory MIDI Project Template', templateId: template.id });
+    expect(controller.getProject().sources[0].mapping.note).to.equal(60);
+    expect(doc.getElementById('midiProjectStatus').textContent).to.equal('Reset project from Factory MIDI Project Template');
+    expect(prevented).to.equal(4);
+    expect(stopped).to.equal(4);
   });
 
-  it('populates MIDI device selects and attaches inputs', function() {
-    const doc = new TestDocument();
-    const win = createTestWindow();
-    const inputSelect = register(doc, 'select', 'midiInSelect');
-    const outputSelect = register(doc, 'select', 'midiOutSelect');
-    register(doc, 'input', 'midiViewPanToggle');
-    register(doc, 'select', 'midiInputChannel');
-    register(doc, 'div', 'errorDisplay');
-
-    const inputDevice = { id: 'in-1', name: 'Input 1' };
-    const outputDevice = { id: 'out-1', name: 'Output 1' };
-    const webMidi = {
-      enabled: true,
-      inputs: [inputDevice],
-      outputs: [outputDevice],
-      getInputById(id) { return this.inputs.find(dev => dev.id === id); },
-      getOutputById(id) { return this.outputs.find(dev => dev.id === id); }
+  it('learns a direct source note through the MIDI input capture hook', function() {
+    const captureCalls = [];
+    const fakeInputController = {
+      handler: null,
+      setNoteCapture(handler) {
+        captureCalls.push(handler);
+        this.handler = handler;
+      },
+      attach() {},
+      detach() {}
     };
+    const { controller, doc, win } = createControllerHarness();
+    controller.setMidiInputController(fakeInputController);
+    controller.bindMidiUi();
+    controller.dispatchProjectIntent({ type: 'track.update', trackId: 'track-1', patch: { arm: true } });
+
+    expect(controller.startLearn()).to.equal(true);
+    expect(fakeInputController.handler).to.be.a('function');
+    expect(fakeInputController.handler(82, 101, 5)).to.equal(true);
+    expect(doc.getElementById('midiLearnStatus').textContent).to.contain('Pending note 82');
+    expect(controller.confirmLearn()).to.equal(true);
+    expect(doc.getElementById('midiProjectStatus').textContent).to.equal('Learned skill-select');
+    expect(doc.getElementById('midiOutputLog').textContent).to.contain('Learned skill-select');
+
+    const stored = JSON.parse(win.localStorage.getItem(PROJECT_STORAGE_KEY));
+    expect(stored.sources[0].mapping).to.include({ note: 82, velocity: 101, degree: null, chord: null });
+    expect(stored.tracks[0]).to.include({ channel: 5, arm: true });
+    expect(captureCalls.at(-1)).to.equal(null);
+  });
 
-    let attached = null;
-    const midiInputController = {
-      attach(input) { attached = input; },
+  it('surfaces learn conflict warnings without blocking confirmation', function() {
+    const fakeInputController = {
+      handler: null,
+      setNoteCapture(handler) {
+        this.handler = handler;
+      },
+      attach() {},
       detach() {}
     };
+    const { controller, doc, win } = createControllerHarness();
+    controller.setMidiInputController(fakeInputController);
+    controller.bindMidiUi();
 
-    const controller = createMidiUiController({
-      document: doc,
-      window: win,
-      getLemmings: () => ({}),
-      getWebMidi: () => webMidi
+    controller.dispatchProjectIntent({
+      type: 'global.update',
+      patch: { noteRange: { min: 60, max: 70 } }
     });
-    controller.setMidiInputController(midiInputController);
-    controller.onEnabled();
 
-    expect(inputSelect.value).to.equal('in-1');
-    expect(outputSelect.value).to.equal('out-1');
-    expect(attached).to.equal(inputDevice);
+    expect(controller.startLearn()).to.equal(true);
+    expect(fakeInputController.handler(82, 101, 5)).to.equal(true);
+    expect(doc.getElementById('midiLearnStatus').textContent).to.contain('Pending note 82');
+    expect(doc.getElementById('midiLearnStatus').textContent).to.contain('1 warning');
+
+    expect(controller.confirmLearn()).to.equal(true);
+    const stored = JSON.parse(win.localStorage.getItem(PROJECT_STORAGE_KEY));
+    expect(stored.sources[0].mapping).to.include({ note: 82, velocity: 101 });
   });
 
-  it('builds event lists and wires updates into overrides', function() {
-    const doc = new TestDocument();
-    const win = createTestWindow();
-    register(doc, 'select', 'midiKeySelect');
-    register(doc, 'select', 'midiScaleSelect');
-    const eventList = register(doc, 'div', 'midiEventList');
-    const triggerList = register(doc, 'div', 'midiTriggerList');
-    register(doc, 'select', 'midiEnvTarget');
-    register(doc, 'select', 'midiRepeatTarget');
-    register(doc, 'input', 'midiRepeatAmount');
-    register(doc, 'div', 'errorDisplay');
-
-    const config = {
-      scale: { name: 'minor', root: 2 },
-      position: { xToNote: true, yToVelocity: false, yToTimbre: false },
-      velocityRange: { default: 90 },
-      density: { velocityBoost: 0.2 },
-      repeat: { maxRepeats: 2, spacingTicks: 3 },
-      envelope: { attack: 1, decay: 0.2, sustain: 0.5, release: 1 },
-      sfx: { '1': { note: 60, name: 'Test' } },
-      triggers: { '1': { note: 62 } },
-      timing: { bpmBase: 120 }
+  it('cancels learn capture and clears it on dispose', function() {
+    const captureCalls = [];
+    const fakeInputController = {
+      setNoteCapture(handler) {
+        captureCalls.push(handler);
+      },
+      attach() {},
+      detach() {}
     };
+    const { controller } = createControllerHarness();
+    controller.setMidiInputController(fakeInputController);
+    controller.bindMidiUi();
 
-    const controller = createMidiUiController({
-      document: doc,
-      window: win,
-      getMidiConfig: () => config
-    });
+    expect(controller.startLearn()).to.equal(true);
+    expect(captureCalls.at(-1)).to.be.a('function');
+    expect(controller.cancelLearn()).to.equal(true);
+    expect(captureCalls.at(-1)).to.equal(null);
 
-    expect(controller.refreshMidiUiFromConfig()).to.equal(true);
-    expect(eventList.children.length).to.equal(1);
-    expect(triggerList.children.length).to.be.greaterThan(0);
+    controller.startLearn();
+    controller.dispose();
+    expect(captureCalls.at(-1)).to.equal(null);
+  });
 
-    const keySelect = findElement(eventList.children[0], el => {
-      if (el.tagName !== 'SELECT') return false;
-      return (el.children || []).some(child => child.textContent === 'C');
+  it('cancels learn and recording capture flows with Escape', function() {
+    const captureCalls = [];
+    const messageCaptureCalls = [];
+    const fakeInputController = {
+      noteHandler: null,
+      messageHandler: null,
+      setNoteCapture(handler) {
+        captureCalls.push(handler);
+        this.noteHandler = handler;
+      },
+      setMessageCapture(handler) {
+        messageCaptureCalls.push(handler);
+        this.messageHandler = handler;
+      },
+      attach() {},
+      detach() {}
+    };
+    const { controller, doc } = createControllerHarness();
+    controller.setMidiInputController(fakeInputController);
+    controller.bindMidiUi();
+    const workspace = doc.getElementById('midiSequencerWorkspace');
+
+    expect(controller.startLearn()).to.equal(true);
+    expect(fakeInputController.noteHandler(82, 101, 5)).to.equal(true);
+    expect(doc.getElementById('midiLearnStatus').textContent).to.contain('Pending note 82');
+    workspace.dispatchEvent({
+      type: 'keydown',
+      key: 'Escape',
+      preventDefault() {},
+      stopPropagation() {}
     });
-    const noteOctave = findElement(eventList.children[0], el => (
-      el.tagName === 'INPUT' && el.type === 'number' && el.max === '9' && !el.disabled
-    ));
-    expect(keySelect).to.be.ok;
-    expect(noteOctave).to.be.ok;
-    keySelect.value = '5';
-    noteOctave.value = '5';
-    noteOctave.dispatchEvent({ type: 'change', target: noteOctave });
-    expect(controller.getMidiOverrides().sfx['1'].note).to.equal(65);
-
-    const triggerIndependent = findElement(triggerList, el => (
-      el.tagName === 'SPAN' && el.textContent === 'Independent arp'
-    ));
-    const eventIndependent = findElement(eventList, el => (
-      el.tagName === 'SPAN' && el.textContent === 'Independent arp'
-    ));
-    expect(triggerIndependent).to.be.ok;
-    expect(eventIndependent).to.equal(null);
+    expect(doc.getElementById('midiProjectStatus').textContent).to.equal('Learn canceled');
+    expect(doc.getElementById('midiLearnStatus').textContent).to.equal('Learn waits for the next note-on.');
+    expect(controller.getProject().sources[0].mapping.note).to.equal(60);
+    expect(captureCalls.at(-1)).to.equal(null);
+
+    controller.dispatchProjectIntent({ type: 'clip.add', clip: { id: 'escape-clip', name: 'Escape Clip', lengthSteps: 4 } });
+    expect(controller.startRecording()).to.equal(true);
+    expect(fakeInputController.messageHandler({ type: 0x90, note: 64, velocity: 90, channel: 1, timestamp: 0 })).to.equal(true);
+    expect(fakeInputController.messageHandler({ type: 0x80, note: 64, velocity: 0, channel: 1, timestamp: 240 })).to.equal(true);
+    expect(doc.getElementById('midiRecordStatus').textContent).to.contain('1 notes captured');
+    workspace.dispatchEvent({
+      type: 'keydown',
+      key: 'Escape',
+      preventDefault() {},
+      stopPropagation() {}
+    });
+    const clip = controller.getProject().clips.find(entry => entry.id === 'escape-clip');
+    expect(doc.getElementById('midiProjectStatus').textContent).to.equal('Recording canceled');
+    expect(doc.getElementById('midiRecordStatus').textContent).to.equal('Record writes captured notes into clip steps.');
+    expect(clip.steps[0].note).to.equal(60);
+    expect(messageCaptureCalls.at(-1)).to.equal(null);
   });
 
-  it('updates disabled toggles when re-enabled', function() {
-    const doc = new TestDocument();
-    const win = createTestWindow();
-    const eventList = register(doc, 'div', 'midiEventList');
-    register(doc, 'select', 'midiEnvTarget');
-    register(doc, 'div', 'errorDisplay');
-
-    const config = {
-      sfx: { '1': { note: 60, disabled: true } },
-      timing: { bpmBase: 120 }
+  it('cancels recording before starting learn capture', function() {
+    const captureCalls = [];
+    const messageCaptureCalls = [];
+    const fakeInputController = {
+      setNoteCapture(handler) {
+        captureCalls.push(handler);
+      },
+      setMessageCapture(handler) {
+        messageCaptureCalls.push(handler);
+      },
+      attach() {},
+      detach() {}
     };
+    const { controller, doc } = createControllerHarness();
+    controller.setMidiInputController(fakeInputController);
+    controller.bindMidiUi();
+    controller.dispatchProjectIntent({ type: 'clip.add', clip: { id: 'recorded', name: 'Recorded', lengthSteps: 4 } });
 
-    const controller = createMidiUiController({
-      document: doc,
-      window: win,
-      getMidiConfig: () => config
-    });
+    expect(controller.startRecording()).to.equal(true);
+    expect(messageCaptureCalls.at(-1)).to.be.a('function');
+    expect(controller.startLearn()).to.equal(true);
 
-    controller.refreshMidiUiFromConfig();
-    const enabledRow = findElement(eventList, el => (
-      el.tagName === 'LABEL' && el.children?.[0]?.textContent === 'Enabled'
-    ));
-    const enabledToggle = enabledRow?.children?.[1] || null;
-    expect(enabledToggle).to.be.ok;
-    enabledToggle.checked = true;
-    enabledToggle.dispatchEvent({ type: 'change', target: enabledToggle });
-    expect(controller.getMidiOverrides().sfx['1'].disabled).to.equal(false);
+    expect(messageCaptureCalls.at(-1)).to.equal(null);
+    expect(captureCalls.at(-1)).to.be.a('function');
+    expect(doc.getElementById('midiProjectStatus').textContent).to.equal('Learning next note');
+    expect(doc.getElementById('midiRecordStatus').textContent).to.equal('Record writes captured notes into clip steps.');
   });
 
-  it('updates repeat target and amount overrides', function() {
-    const doc = new TestDocument();
-    const win = createTestWindow();
-    const repeatTarget = register(doc, 'select', 'midiRepeatTarget');
-    const repeatAmount = register(doc, 'input', 'midiRepeatAmount');
-    const repeatSpacing = register(doc, 'select', 'midiRepeatSpacing');
-    const repeatCount = register(doc, 'input', 'midiRepeatCount');
-
-    const config = {
-      repeat: { maxRepeats: 2, windowBeats: 0.5, target: 'note', amount: 0.25 },
-      timing: { bpmBase: 120 }
+  it('records mocked MIDI notes into selected clip steps', function() {
+    const messageCaptureCalls = [];
+    const fakeInputController = {
+      setNoteCapture() {},
+      setMessageCapture(handler) {
+        messageCaptureCalls.push(handler);
+        this.handler = handler;
+      },
+      attach() {},
+      detach() {}
     };
+    const { controller, doc, win } = createControllerHarness();
+    controller.setMidiInputController(fakeInputController);
+    controller.bindMidiUi();
+    controller.dispatchProjectIntent({ type: 'clip.add', clip: { id: 'recorded', name: 'Recorded', lengthSteps: 4 } });
+
+    expect(controller.startRecording()).to.equal(true);
+    expect(fakeInputController.handler).to.be.a('function');
+    expect(fakeInputController.handler({ type: 0x90, note: 64, velocity: 90, channel: 1, timestamp: 0 })).to.equal(true);
+    expect(fakeInputController.handler({ type: 0x80, note: 64, velocity: 0, channel: 1, timestamp: 240 })).to.equal(true);
+    expect(fakeInputController.handler({ type: 0x90, note: 67, velocity: 88, channel: 1, timestamp: 260 })).to.equal(true);
+    expect(controller.commitRecording()).to.equal(true);
+    expect(doc.getElementById('midiProjectStatus').textContent).to.equal('Recorded 2 notes into Recorded');
+    expect(doc.getElementById('midiOutputLog').textContent).to.contain('Recorded 2 notes into Recorded');
+
+    const stored = JSON.parse(win.localStorage.getItem(PROJECT_STORAGE_KEY));
+    const clip = stored.clips.find(entry => entry.id === 'recorded');
+    expect(clip.steps[0]).to.include({ note: 64, velocity: 90, durationTicks: 2 });
+    expect(clip.steps[1]).to.include({ note: 67, velocity: 88 });
+    expect(messageCaptureCalls.at(-1)).to.equal(null);
+  });
 
-    const controller = createMidiUiController({
-      document: doc,
-      window: win,
-      getMidiConfig: () => config
-    });
+  it('records only notes that fit in the selected clip', function() {
+    const fakeInputController = {
+      setNoteCapture() {},
+      setMessageCapture(handler) {
+        this.handler = handler;
+      },
+      attach() {},
+      detach() {}
+    };
+    const { controller, doc, win } = createControllerHarness();
+    controller.setMidiInputController(fakeInputController);
+    controller.bindMidiUi();
+    controller.dispatchProjectIntent({ type: 'clip.add', clip: { id: 'one-step', name: 'One Step', lengthSteps: 1 } });
+
+    expect(controller.startRecording()).to.equal(true);
+    expect(fakeInputController.handler({ type: 0x90, note: 64, velocity: 90, channel: 1, timestamp: 0 })).to.equal(true);
+    expect(fakeInputController.handler({ type: 0x80, note: 64, velocity: 0, channel: 1, timestamp: 120 })).to.equal(true);
+    expect(fakeInputController.handler({ type: 0x90, note: 67, velocity: 88, channel: 1, timestamp: 140 })).to.equal(true);
+    expect(fakeInputController.handler({ type: 0x80, note: 67, velocity: 0, channel: 1, timestamp: 260 })).to.equal(true);
+    expect(controller.commitRecording()).to.equal(true);
+
+    const stored = JSON.parse(win.localStorage.getItem(PROJECT_STORAGE_KEY));
+    const clip = stored.clips.find(entry => entry.id === 'one-step');
+    expect(clip.steps).to.have.lengthOf(1);
+    expect(clip.steps[0]).to.include({ note: 64, velocity: 90 });
+    expect(doc.getElementById('midiOutputLog').textContent).to.contain('Recorded 1 note into One Step');
+  });
 
+  it('does not create clips when recording without a selected clip', function() {
+    const fakeInputController = {
+      setNoteCapture() {},
+      setMessageCapture() {
+        throw new Error('record capture should not start');
+      },
+      attach() {},
+      detach() {}
+    };
+    const { controller, doc } = createControllerHarness();
+    controller.setMidiInputController(fakeInputController);
     controller.bindMidiUi();
-    controller.refreshMidiUiFromConfig();
-    expect(repeatTarget.value).to.equal('note');
-
-    repeatTarget.value = 'velocity';
-    repeatTarget.dispatchEvent({ type: 'change', target: repeatTarget });
-    repeatAmount.value = '0.4';
-    repeatAmount.dispatchEvent({ type: 'change', target: repeatAmount });
-    repeatSpacing.value = '0.5';
-    repeatSpacing.dispatchEvent({ type: 'change', target: repeatSpacing });
-    repeatCount.value = '3';
-    repeatCount.dispatchEvent({ type: 'change', target: repeatCount });
-
-    const overrides = controller.getMidiOverrides();
-    expect(overrides.repeat.target).to.equal('velocity');
-    expect(overrides.repeat.amount).to.equal(0.4);
-    expect(overrides.repeat.windowBeats).to.equal(0.5);
-    expect(overrides.repeat.maxRepeats).to.equal(3);
+
+    expect(controller.startRecording()).to.equal(false);
+    expect(controller.getProject().clips).to.have.lengthOf(0);
+    expect(doc.getElementById('midiRecordStatus').textContent).to.equal('Create a clip before recording.');
   });
 
-  it('updates ADSR overrides for selected targets', function() {
-    const doc = new TestDocument();
-    const win = createTestWindow();
-    const envTarget = register(doc, 'select', 'midiEnvTarget');
-    const envAttack = register(doc, 'input', 'midiEnvAttack');
-    const envDecay = register(doc, 'input', 'midiEnvDecay');
-    const envSustain = register(doc, 'input', 'midiEnvSustain');
-    const envRelease = register(doc, 'input', 'midiEnvRelease');
-    register(doc, 'div', 'midiEventList');
-    register(doc, 'div', 'midiTriggerList');
-
-    const config = {
-      envelope: { attack: 0.5, decay: 0.2, sustain: 1, release: 0.8 },
-      sfx: { '1': { name: 'Test', envelope: { attack: 1.5 } } },
-      triggers: { '5': { envelope: { release: 0.3 } } },
-      timing: { bpmBase: 120 }
+  it('cancels recording and clears message capture on dispose', function() {
+    const messageCaptureCalls = [];
+    const fakeInputController = {
+      setNoteCapture() {},
+      setMessageCapture(handler) {
+        messageCaptureCalls.push(handler);
+      },
+      attach() {},
+      detach() {}
     };
+    const { controller } = createControllerHarness();
+    controller.setMidiInputController(fakeInputController);
+    controller.bindMidiUi();
+    controller.dispatchProjectIntent({ type: 'clip.add', clip: { id: 'recorded', name: 'Recorded', lengthSteps: 4 } });
 
-    const controller = createMidiUiController({
-      document: doc,
-      window: win,
-      getMidiConfig: () => config
-    });
+    expect(controller.startRecording()).to.equal(true);
+    expect(messageCaptureCalls.at(-1)).to.be.a('function');
+    expect(controller.cancelRecording()).to.equal(true);
+    expect(messageCaptureCalls.at(-1)).to.equal(null);
 
+    controller.startRecording();
+    controller.dispose();
+    expect(messageCaptureCalls.at(-1)).to.equal(null);
+  });
+
+  it('creates clips, assigns a source to clip mode, persists steps, and auditions clip notes', function() {
+    const sent = [];
+    const { controller, doc, win, view } = createControllerHarness({
+      lemmings: {
+        midiRouter: {
+          scheduler: {
+            sendNote(spec, meta) {
+              sent.push({ spec, meta });
+              return true;
+            }
+          }
+        }
+      }
+    });
     controller.bindMidiUi();
-    controller.refreshMidiUiFromConfig();
-    expect(envTarget.value).to.equal('global');
-    expect(envAttack.value).to.equal('0.5');
-
-    envTarget.value = 'sfx:1';
-    envTarget.dispatchEvent({ type: 'change', target: envTarget });
-    expect(win.localStorage.getItem('lemmings.midi.adsrTarget')).to.equal('sfx:1');
-    expect(envAttack.value).to.equal('1.5');
-
-    envAttack.value = '1.2';
-    envAttack.dispatchEvent({ type: 'change', target: envAttack });
-    expect(controller.getMidiOverrides().sfx['1'].envelope.attack).to.equal(1.2);
-
-    envTarget.value = 'trigger:5';
-    envTarget.dispatchEvent({ type: 'change', target: envTarget });
-    expect(envRelease.value).to.equal('0.3');
-    envAttack.value = '0.8';
-    envAttack.dispatchEvent({ type: 'change', target: envAttack });
-    expect(controller.getMidiOverrides().triggers['5'].envelope.attack).to.equal(0.8);
-
-    envTarget.value = 'global';
-    envTarget.dispatchEvent({ type: 'change', target: envTarget });
-    envAttack.value = '0.7';
-    envAttack.dispatchEvent({ type: 'change', target: envAttack });
-    expect(controller.getMidiOverrides().envelope.attack).to.equal(0.7);
-
-    envTarget.value = 'nonsense';
-    envTarget.dispatchEvent({ type: 'change', target: envTarget });
-    expect(envAttack.value).to.equal('0.5');
+
+    controller.dispatchProjectIntent({ type: 'clip.add', clip: { id: 'riff', name: 'Riff', lengthSteps: 4 } });
+    controller.dispatchProjectIntent({ type: 'clip.step.update', clipId: 'riff', stepIndex: 0, patch: { note: 65, velocity: 90, durationTicks: 7 } });
+    controller.dispatchProjectIntent({ type: 'clip.step.update', clipId: 'riff', stepIndex: 1, patch: { note: 69 } });
+    controller.dispatchProjectIntent({ type: 'source.clip.assign', sourceId: 'sfx-1', clipId: 'riff' });
+
+    const stored = JSON.parse(win.localStorage.getItem(PROJECT_STORAGE_KEY));
+    expect(stored.ui.selectedClipId).to.equal('riff');
+    expect(stored.clips[0].steps[0]).to.include({ note: 65, velocity: 90, durationTicks: 7 });
+    expect(stored.sources[0]).to.include({ mode: 'clip', clipId: 'riff', mapping: null });
+    expect(view.projectConfigs.at(-1).sfx['1']).to.include({ note: 65, velocity: 90, durationTicks: 7, clipId: 'riff' });
+    expect(view.projectConfigs.at(-1).sfx['1'].notes).to.deep.equal([65, 69]);
+    const stepGrid = doc.getElementById('midiStepPatternGrid');
+    expect(stepGrid.children).to.have.lengthOf(4);
+    expect(stepGrid.getAttribute('aria-rowcount')).to.equal('1');
+    expect(stepGrid.getAttribute('aria-colcount')).to.equal('4');
+    expect(stepGrid.children[0].getAttribute('aria-rowindex')).to.equal('1');
+    expect(stepGrid.children[0].getAttribute('aria-colindex')).to.equal('1');
+    expect(stepGrid.children[0].children[1].children[0].getAttribute('aria-label')).to.equal('Step 1 note');
+    const duration = stepGrid.children[0].children[3].children[0];
+    expect(duration.className).to.equal('midi-step-duration');
+    expect(duration.value).to.equal('7');
+    duration.value = '9';
+    duration.dispatchEvent({ type: 'change', target: duration });
+    const afterDurationEdit = JSON.parse(win.localStorage.getItem(PROJECT_STORAGE_KEY));
+    expect(afterDurationEdit.clips[0].steps[0].durationTicks).to.equal(9);
+    expect(view.projectConfigs.at(-1).sfx['1'].durationTicks).to.equal(9);
+
+    const stepControl = (stepIndex, childIndex) => stepGrid.children[stepIndex].children[childIndex].children[0];
+    const probability = stepControl(1, 4);
+    expect(probability.className).to.equal('midi-step-probability');
+    probability.value = '0.35';
+    probability.dispatchEvent({ type: 'change', target: probability });
+    const hold = stepControl(1, 5);
+    expect(hold.className).to.equal('midi-step-hold');
+    hold.checked = true;
+    hold.dispatchEvent({ type: 'change', target: hold });
+    const tie = stepControl(1, 6);
+    expect(tie.className).to.equal('midi-step-tie');
+    tie.checked = true;
+    tie.dispatchEvent({ type: 'change', target: tie });
+    const afterStepToggles = JSON.parse(win.localStorage.getItem(PROJECT_STORAGE_KEY));
+    expect(afterStepToggles.clips[0].steps[1]).to.include({ note: 69, probability: 0.35, hold: true, tie: true });
+    expect(view.projectConfigs.at(-1).sfx['1']).to.include({ note: 65 });
+    expect(view.projectConfigs.at(-1).sfx['1'].notes).to.equal(undefined);
+
+    const rest = stepGrid.children[1].children[7];
+    expect(rest.className).to.equal('midi-step-rest');
+    rest.dispatchEvent({ type: 'click', target: rest });
+    const afterRest = JSON.parse(win.localStorage.getItem(PROJECT_STORAGE_KEY));
+    expect(afterRest.clips[0].steps[1]).to.include({
+      note: null,
+      velocity: null,
+      durationTicks: null,
+      probability: 1,
+      hold: false,
+      tie: false
+    });
+    expect(view.projectConfigs.at(-1).sfx['1']).to.include({ note: 65 });
+    expect(view.projectConfigs.at(-1).sfx['1'].notes).to.equal(undefined);
+
+    expect(controller.audition({ sourceId: 'sfx-1' })).to.equal(true);
+    expect(sent.map(entry => entry.spec.note)).to.deep.equal([65]);
+    expect(sent[0].meta).to.include({ eventType: 'clip-audition', sourceId: 'sfx-1', trackId: 'track-1', clipId: 'riff' });
   });
 
-  it('filters events and triggers based on level context', function() {
-    const doc = new TestDocument();
-    const win = createTestWindow();
-    const eventList = register(doc, 'div', 'midiEventList');
-    const triggerList = register(doc, 'div', 'midiTriggerList');
-    register(doc, 'select', 'midiEnvTarget');
-    register(doc, 'div', 'errorDisplay');
-
-    const skills = {
-      cheatMode: false,
-      skills: [0, 0, 0, 0, 0, 1, 0, 0, 0],
-      getSkill(type) { return type === SkillTypes.BUILDER ? 1 : 0; }
-    };
-    const level = {
-      triggers: [{ type: TriggerTypes.DROWN, disableTicksCount: 0 }],
-      steelRanges: new Int32Array(0),
-      arrowRanges: new Int32Array(0)
-    };
-    const lemmings = { game: { level, getGameSkills() { return skills; } } };
-
-    const config = {
-      sfx: {
-        [SoundEffectIds.SKILL_SELECT]: { name: 'skill-select' },
-        [SoundEffectIds.BUILDER_STEP]: { name: 'builder-step' },
-        [SoundEffectIds.STEEL_HIT]: { name: 'steel-hit' },
-        [SoundEffectIds.DROWN]: { name: 'drown' }
+  it('removes selected clips and cancels active recording capture', function() {
+    const messageCaptureCalls = [];
+    const fakeInputController = {
+      setNoteCapture() {},
+      setMessageCapture(handler) {
+        messageCaptureCalls.push(handler);
       },
-      triggers: { '5': { note: 60 } },
-      timing: { bpmBase: 120 }
+      attach() {},
+      detach() {}
     };
+    const { controller, doc } = createControllerHarness();
+    controller.setMidiInputController(fakeInputController);
+    controller.bindMidiUi();
+    const remove = doc.getElementById('midiClipRemoveButton');
+    expect(remove.disabled).to.equal(true);
+
+    controller.dispatchProjectIntent({ type: 'clip.add', clip: { id: 'riff', name: 'Riff', lengthSteps: 4 } });
+    controller.dispatchProjectIntent({ type: 'clip.add', clip: { id: 'fill', name: 'Fill', lengthSteps: 4 } });
+    controller.dispatchProjectIntent({ type: 'source.clip.assign', sourceId: 'sfx-1', clipId: 'riff' });
+    controller.dispatchProjectIntent({ type: 'clip.select', clipId: 'riff' });
+    expect(remove.disabled).to.equal(false);
+    expect(controller.startRecording()).to.equal(true);
+    expect(messageCaptureCalls.at(-1)).to.be.a('function');
+
+    remove.dispatchEvent({ type: 'click', target: remove });
+
+    const project = controller.getProject();
+    expect(messageCaptureCalls.at(-1)).to.equal(null);
+    expect(project.clips.map(clip => clip.id)).to.deep.equal(['fill']);
+    expect(project.ui.selectedClipId).to.equal('fill');
+    expect(project.sources[0]).to.include({ mode: 'direct', clipId: null });
+    expect(project.sources[0].mapping).to.include({ note: null, velocity: null });
+    expect(doc.getElementById('midiRecordStatus').textContent).to.equal('Record writes captured notes into clip steps.');
+    expect(doc.getElementById('midiProjectStatus').textContent).to.equal('Removed clip Riff');
+    expect(doc.getElementById('midiOutputLog').textContent).to.contain('Removed clip Riff');
+  });
+
+  it('duplicates the selected clip from the clip library controls', function() {
+    const { controller, doc } = createControllerHarness();
+    controller.bindMidiUi();
+    const duplicateButton = doc.getElementById('midiClipDuplicateButton');
+    expect(duplicateButton.disabled).to.equal(true);
+
+    controller.dispatchProjectIntent({ type: 'clip.add', clip: { id: 'riff', name: 'Riff', lengthSteps: 4 } });
+    controller.dispatchProjectIntent({ type: 'clip.step.update', clipId: 'riff', stepIndex: 0, patch: { note: 65, velocity: 90 } });
+    controller.dispatchProjectIntent({ type: 'source.clip.assign', sourceId: 'sfx-1', clipId: 'riff' });
+    expect(duplicateButton.disabled).to.equal(false);
+
+    duplicateButton.dispatchEvent({ type: 'click', target: duplicateButton });
+
+    const project = controller.getProject();
+    expect(project.clips.map(clip => clip.id)).to.deep.equal(['riff', 'riff-copy']);
+    expect(project.ui.selectedClipId).to.equal('riff-copy');
+    expect(project.clips[1]).to.include({ name: 'Riff Copy', lengthSteps: 4 });
+    expect(project.clips[1].steps[0]).to.include({ note: 65, velocity: 90 });
+    expect(project.sources[0]).to.include({ mode: 'clip', clipId: 'riff' });
+    expect(doc.getElementById('midiProjectStatus').textContent).to.equal('Duplicated clip Riff Copy');
+    expect(doc.getElementById('midiOutputLog').textContent).to.contain('Duplicated clip Riff Copy');
+  });
 
-    const controller = createMidiUiController({
-      document: doc,
-      window: win,
-      getLemmings: () => lemmings,
-      getMidiConfig: () => config
+  it('reports responsive step grid aria geometry', function() {
+    const { controller, doc, win } = createControllerHarness();
+    win.innerWidth = 500;
+    controller.bindMidiUi();
+
+    controller.dispatchProjectIntent({ type: 'clip.add', clip: { id: 'phone-grid', name: 'Phone Grid', lengthSteps: 4 } });
+    const stepGrid = doc.getElementById('midiStepPatternGrid');
+    expect(stepGrid.getAttribute('aria-colcount')).to.equal('1');
+    expect(stepGrid.getAttribute('aria-rowcount')).to.equal('4');
+    expect(stepGrid.children[1].getAttribute('aria-rowindex')).to.equal('2');
+    expect(stepGrid.children[1].getAttribute('aria-colindex')).to.equal('1');
+    stepGrid.dispatchEvent({
+      type: 'keydown',
+      key: 'ArrowDown',
+      target: stepGrid.children[0].children[1].children[0],
+      preventDefault() {}
     });
+    expect(doc.activeElement).to.equal(stepGrid.children[1].children[1].children[0]);
 
+    win.innerWidth = 700;
     controller.refreshMidiUiFromConfig();
-    expect(eventList.children.length).to.equal(3);
-    expect(triggerList.children.length).to.equal(1);
+    expect(stepGrid.getAttribute('aria-colcount')).to.equal('2');
+    expect(stepGrid.getAttribute('aria-rowcount')).to.equal('2');
+    expect(stepGrid.children[2].getAttribute('aria-rowindex')).to.equal('2');
+    expect(stepGrid.children[2].getAttribute('aria-colindex')).to.equal('1');
+    stepGrid.dispatchEvent({
+      type: 'keydown',
+      key: 'ArrowDown',
+      target: stepGrid.children[0].children[1].children[0],
+      preventDefault() {}
+    });
+    expect(doc.activeElement).to.equal(stepGrid.children[2].children[1].children[0]);
   });
 
-  it('reads stored enabled state and storage keys', function() {
-    const doc = new TestDocument();
-    const win = createTestWindow();
-    win.localStorage.setItem('lemmings.midi.enabled', 'false');
+  it('disables clip assignment when no clip exists', function() {
+    const { controller, doc } = createControllerHarness();
+    controller.bindMidiUi();
 
-    const controller = createMidiUiController({
-      document: doc,
-      window: win,
-      getMidiConfig: () => ({ enabled: true })
-    });
+    const assignClip = doc.getElementById('midiAssignClipButton');
+    expect(assignClip.disabled).to.equal(true);
+    assignClip.dispatchEvent({ type: 'click', target: assignClip });
+    expect(controller.getProject().clips).to.have.lengthOf(0);
+    expect(controller.getProject().sources[0]).to.include({ mode: 'direct', clipId: null });
+  });
 
-    expect(controller.getStoredEnabled()).to.equal(false);
-    win.localStorage.removeItem('lemmings.midi.enabled');
-    expect(controller.getStoredEnabled()).to.equal(true);
+  it('keeps source mode direct when clip mode has no clip', function() {
+    const { controller, doc } = createControllerHarness();
+    controller.bindMidiUi();
 
-    const fallback = createMidiUiController({
-      document: doc,
-      window: win,
-      getMidiConfig: () => ({})
-    });
+    const mode = doc.getElementById('midiSourceModeSelect');
+    mode.value = 'clip';
+    mode.dispatchEvent({ type: 'change', target: mode });
 
-    expect(fallback.getStoredEnabled()).to.equal(false);
-    expect(controller.getStorageKeys()).to.have.property('enabled');
+    expect(controller.getProject().clips).to.have.lengthOf(0);
+    expect(controller.getProject().sources[0]).to.include({ mode: 'direct', clipId: null });
+    expect(doc.getElementById('midiSourceModeSelect').value).to.equal('direct');
+    expect(doc.getElementById('midiProjectStatus').textContent).to.equal('Create a clip before using clip mode');
   });
 
-  it('uses lemmings base config when no provider is supplied', function() {
-    const doc = new TestDocument();
-    const win = createTestWindow();
-    const baseConfig = { timing: { bpmBase: 110 } };
-    const controller = createMidiUiController({
-      document: doc,
-      window: win,
-      getLemmings: () => ({ getMidiBaseConfig: () => baseConfig })
+  it('filters silent and tied clip steps from runtime clip mappings', function() {
+    const { controller, view } = createControllerHarness();
+    controller.bindMidiUi();
+
+    controller.dispatchProjectIntent({ type: 'clip.add', clip: { id: 'filtered', name: 'Filtered', lengthSteps: 4 } });
+    controller.dispatchProjectIntent({
+      type: 'clip.step.update',
+      clipId: 'filtered',
+      stepIndex: 0,
+      patch: { note: 60, probability: 0 }
+    });
+    controller.dispatchProjectIntent({
+      type: 'clip.step.update',
+      clipId: 'filtered',
+      stepIndex: 1,
+      patch: { note: 62, tie: true }
+    });
+    controller.dispatchProjectIntent({
+      type: 'clip.step.update',
+      clipId: 'filtered',
+      stepIndex: 2,
+      patch: { note: 72, velocity: 85, durationTicks: 6 }
     });
+    controller.dispatchProjectIntent({
+      type: 'clip.step.update',
+      clipId: 'filtered',
+      stepIndex: 3,
+      patch: { note: 76 }
+    });
+    controller.dispatchProjectIntent({ type: 'source.clip.assign', sourceId: 'sfx-1', clipId: 'filtered' });
 
-    expect(controller.getMidiConfig()).to.equal(baseConfig);
+    const runtimeMapping = view.projectConfigs.at(-1).sfx['1'];
+    expect(runtimeMapping).to.include({ note: 72, velocity: 85, durationTicks: 6, clipId: 'filtered' });
+    expect(runtimeMapping.notes).to.deep.equal([72, 76]);
+    expect(runtimeMapping.disabled).to.equal(undefined);
   });
 
-  it('drops invalid stored overrides', function() {
-    const doc = new TestDocument();
-    const win = createTestWindow();
-    win.localStorage.setItem('lemmings.midi.overrides', JSON.stringify(['bad']));
-
-    const controller = createMidiUiController({
-      document: doc,
-      window: win
+  it('renders source conflict badges, conflict filters, and inspector warnings', function() {
+    const { controller, doc } = createControllerHarness({
+      factoryConfig: {
+        enabled: false,
+        input: { channel: 'omni' },
+        sfx: {
+          '1': { name: 'skill-select', note: 60, durationTicks: 4 },
+          '2': { name: 'builder', note: 60, durationTicks: 4 }
+        },
+        triggers: {}
+      }
+    });
+    controller.bindMidiUi();
+    const project = controller.getProject();
+    controller.setProject({
+      ...project,
+      sources: [
+        project.sources[0],
+        {
+          ...project.sources[1],
+          id: 'sfx-1-copy',
+          sourceKey: '1',
+          label: 'Duplicate Select'
+        }
+      ],
+      ui: { ...project.ui, selectedSourceId: 'sfx-1' }
     });
 
-    expect(controller.getMidiOverrides()).to.eql({});
+    const sourceRows = doc.getElementById('midiSourceList').children;
+    const conflictedRows = sourceRows.filter(row => row.classList?.contains('has-conflict'));
+    expect(conflictedRows).to.have.lengthOf(2);
+    expect(conflictedRows[0].children.some(child => child.className === 'midi-conflict-badge')).to.equal(true);
+    expect(conflictedRows[0].children.find(child => child.className === 'midi-conflict-badge')?.getAttribute('aria-hidden')).to.equal('true');
+    expect(doc.getElementById('midiConflictSummary').children[0].textContent).to.contain('Duplicate runtime key');
+
+    const filter = doc.getElementById('midiSourceAssignFilter');
+    filter.value = 'clean';
+    filter.dispatchEvent({ type: 'change', target: filter });
+    const empty = doc.getElementById('midiSourceList').children[0];
+    expect(empty.textContent).to.contain('No sources match');
+    expect(empty.getAttribute('role')).to.equal('option');
+    expect(empty.getAttribute('aria-disabled')).to.equal('true');
+    filter.value = 'conflicts';
+    filter.dispatchEvent({ type: 'change', target: filter });
+    expect(doc.getElementById('midiSourceList').children.filter(row => row.classList?.contains('has-conflict'))).to.have.lengthOf(2);
   });
 
-  it('applies stored section states via test hook', function() {
-    const doc = new TestDocument();
-    const win = createTestWindow();
-    setupRichSelectors(doc);
-    const section = doc.createElement('details');
-    section.dataset.sectionKey = 'alpha';
-    section.setAttribute = (name, value) => section.attributes.set(name, value);
-    section.hasAttribute = (name) => section.attributes.has(name);
-    section.setAttribute('open', '');
-    section.open = true;
-    win.localStorage.setItem('lemmings.midi.sectionStates', JSON.stringify({ alpha: false }));
-
-    const controller = createMidiUiController({
-      document: doc,
-      window: win
+  it('keeps direct source conflict summaries scoped away from the selected clip', function() {
+    const { controller, doc } = createControllerHarness({
+      factoryConfig: {
+        enabled: false,
+        input: { channel: 'omni' },
+        sfx: {
+          '1': { name: 'skill-select', note: 60, durationTicks: 4 },
+          '2': { name: 'builder', note: 62, durationTicks: 4 }
+        },
+        triggers: {}
+      }
     });
-
-    controller.__test__.applySectionStates({ useStored: true });
-    expect(section.dataset.defaultOpen).to.equal('true');
-    expect(section.open).to.equal(false);
+    controller.bindMidiUi();
+    controller.dispatchProjectIntent({ type: 'track.add', track: { id: 'lead', name: 'Lead', channel: 2 } });
+    controller.dispatchProjectIntent({ type: 'clip.add', clip: { id: 'silent', name: 'Silent Clip', lengthSteps: 4 } });
+    controller.dispatchProjectIntent({ type: 'source.assignTrack', sourceId: 'sfx-2', trackId: 'lead' });
+    controller.dispatchProjectIntent({ type: 'source.clip.assign', sourceId: 'sfx-2', clipId: 'silent' });
+    controller.dispatchProjectIntent({ type: 'source.select', sourceId: 'sfx-1' });
+    controller.dispatchProjectIntent({ type: 'track.select', trackId: 'track-1' });
+    controller.dispatchProjectIntent({ type: 'clip.select', clipId: 'silent' });
+
+    const summary = doc.getElementById('midiConflictSummary');
+    expect(summary.className).to.contain('is-clean');
+    expect(summary.textContent).to.equal('No conflicts for the selected source.');
   });
 
-  it('clears schema hash when reset defaults does not persist', function() {
-    const doc = new TestDocument();
-    const win = createTestWindow();
-    const lemmings = { applyMidiOverrides() {}, getMidiSchemaHash: () => 'hash' };
-    win.localStorage.setItem('lemmings.midi.schemaHash', 'old');
+  it('filters sources changed from the factory template', function() {
+    const { controller, doc } = createControllerHarness({
+      factoryConfig: {
+        enabled: false,
+        input: { channel: 'omni' },
+        sfx: {
+          '1': { name: 'skill-select', note: 60, durationTicks: 4 },
+          '2': { name: 'builder', note: 62, durationTicks: 4 }
+        },
+        triggers: {}
+      }
+    });
+    controller.bindMidiUi();
+    const filter = doc.getElementById('midiSourceAssignFilter');
+
+    filter.value = 'changed';
+    filter.dispatchEvent({ type: 'change', target: filter });
+    expect(doc.getElementById('midiSourceList').children[0].textContent).to.contain('No sources match');
+
+    controller.dispatchProjectIntent({ type: 'source.select', sourceId: 'sfx-2' });
+    controller.dispatchProjectIntent({ type: 'source.mapping.update', sourceId: 'sfx-2', patch: { note: 70 } });
+    const changedRows = doc.getElementById('midiSourceList').children.filter(row => row.classList?.contains('is-changed'));
+    expect(changedRows).to.have.lengthOf(1);
+    expect(changedRows[0].children[0].textContent).to.equal('builder');
+    expect(changedRows[0].children.some(child => child.textContent === 'Changed')).to.equal(true);
+    expect(changedRows[0].getAttribute('aria-label')).to.contain('changed');
+
+    const revert = doc.getElementById('midiSourceRevertButton');
+    expect(revert.disabled).to.equal(false);
+    revert.dispatchEvent({ type: 'click', target: revert });
+    expect(controller.getProject().sources.find(source => source.id === 'sfx-2').mapping.note).to.equal(62);
+    expect(doc.getElementById('midiProjectStatus').textContent).to.equal('Reverted builder');
+    expect(doc.getElementById('midiOutputLog').textContent).to.contain('Reverted builder');
+    expect(doc.getElementById('midiSourceList').children[0].textContent).to.contain('No sources match');
+  });
 
-    const controller = createMidiUiController({
-      document: doc,
-      window: win,
-      getLemmings: () => lemmings
+  it('filters sources available in the current level', function() {
+    const flagTrigger = toMidiFlagTriggerType(3);
+    const { controller, doc } = createControllerHarness({
+      factoryConfig: {
+        enabled: false,
+        input: { channel: 'omni' },
+        sfx: {
+          [SoundEffectIds.EXIT]: { name: 'exit', note: 60, durationTicks: 4 },
+          [SoundEffectIds.BUILDER_STEP]: { name: 'builder-step', note: 62, durationTicks: 4 }
+        },
+        triggers: {
+          [TriggerTypes.EXIT_LEVEL]: { name: 'exit-trigger', note: 64, durationTicks: 4 },
+          [TriggerTypes.TRAP]: { name: 'trap-trigger', note: 65, durationTicks: 4 }
+        }
+      },
+      lemmings: {
+        game: {
+          level: {
+            triggers: [{ type: TriggerTypes.EXIT_LEVEL }],
+            midiFlags: [{ id: 3, triggerType: flagTrigger }],
+            skills: []
+          },
+          getGameSkills() {
+            return { getSkill: () => 0 };
+          }
+        }
+      }
     });
+    controller.bindMidiUi();
 
-    controller.__test__.resetMidiDefaults(false);
-    expect(win.localStorage.getItem('lemmings.midi.schemaHash')).to.equal(null);
+    const filter = doc.getElementById('midiSourceAssignFilter');
+    filter.value = 'available';
+    filter.dispatchEvent({ type: 'change', target: filter });
+
+    const sourceIds = doc.getElementById('midiSourceList')
+      .children
+      .map(row => row.dataset?.sourceId)
+      .filter(Boolean);
+    expect(sourceIds).to.include(`sfx-${SoundEffectIds.EXIT}`);
+    expect(sourceIds).to.not.include(`sfx-${SoundEffectIds.BUILDER_STEP}`);
+    expect(sourceIds).to.include(`trigger-${TriggerTypes.EXIT_LEVEL}`);
+    expect(sourceIds).to.not.include(`trigger-${TriggerTypes.TRAP}`);
+    expect(sourceIds).to.include(`midiFlag-${flagTrigger}`);
+    expect(sourceIds).to.not.include(`trigger-${flagTrigger}`);
   });
 
-  it('persists tab and section state and resets on input change', function() {
-    const doc = new TestDocument();
-    setupRichSelectors(doc);
-    doc.body = doc.createElement('body');
-    const win = createTestWindow();
-    register(doc, 'input', 'midiEnabledToggle');
-    const inputSelect = register(doc, 'select', 'midiInSelect');
-    register(doc, 'select', 'midiInputChannel');
-    register(doc, 'div', 'controlLeft');
-    register(doc, 'div', 'midiPanelToggle');
-    register(doc, 'div', 'midiEventList');
-    register(doc, 'div', 'midiTriggerList');
-    register(doc, 'select', 'midiEnvTarget');
-    register(doc, 'div', 'errorDisplay');
-
-    const sectionA = doc.createElement('details');
-    sectionA.dataset.sectionKey = 'a';
-    sectionA.open = true;
-    sectionA.setAttribute = (name, value) => sectionA.attributes.set(name, value);
-    sectionA.hasAttribute = (name) => sectionA.attributes.has(name);
-    sectionA.setAttribute('open', '');
-
-    const sectionB = doc.createElement('details');
-    sectionB.dataset.sectionKey = 'b';
-    sectionB.open = false;
-    sectionB.setAttribute = (name, value) => sectionB.attributes.set(name, value);
-    sectionB.hasAttribute = (name) => sectionB.attributes.has(name);
-
-    const buttonA = register(doc, 'button', 'tabA', 'tab-button');
-    buttonA.dataset.tabGroup = 'midi-left';
-    buttonA.dataset.tabTarget = 'panelA';
-    const buttonB = register(doc, 'button', 'tabB', 'tab-button');
-    buttonB.dataset.tabGroup = 'midi-left';
-    buttonB.dataset.tabTarget = 'panelB';
-    const panelA = register(doc, 'div', 'panelA', 'tab-panel');
-    panelA.dataset.tabGroup = 'midi-left';
-    const panelB = register(doc, 'div', 'panelB', 'tab-panel');
-    panelB.dataset.tabGroup = 'midi-left';
-
-    win.localStorage.setItem('lemmings.midi.tabLeft', 'panelB');
-    win.localStorage.setItem('lemmings.midi.sectionStates', JSON.stringify({ a: false, b: true }));
-
-    const controller = createMidiUiController({
-      document: doc,
-      window: win,
-      getMidiConfig: () => ({ timing: { bpmBase: 120 } })
+  it('moves source keyboard navigation from the visible fallback row', function() {
+    const { controller, doc } = createControllerHarness({
+      factoryConfig: {
+        enabled: false,
+        input: { channel: 'omni' },
+        sfx: {
+          '1': { name: 'skill-select', note: 60, durationTicks: 4 },
+          '2': { name: 'builder', note: 62, durationTicks: 4 },
+          '3': { name: 'digger', note: 64, durationTicks: 4 }
+        },
+        triggers: {}
+      }
+    });
+    controller.bindMidiUi();
+    const filter = doc.getElementById('midiSourceAssignFilter');
+    filter.value = 'changed';
+    filter.dispatchEvent({ type: 'change', target: filter });
+
+    controller.dispatchProjectIntent({ type: 'source.mapping.update', sourceId: 'sfx-2', patch: { note: 70 } });
+    controller.dispatchProjectIntent({ type: 'source.mapping.update', sourceId: 'sfx-3', patch: { note: 71 } });
+    const sourceList = doc.getElementById('midiSourceList');
+    expect(sourceList.getAttribute('aria-activedescendant')).to.equal('midi-source-option-sfx-2');
+    sourceList.dispatchEvent({
+      type: 'keydown',
+      key: 'ArrowDown',
+      preventDefault() {}
     });
 
+    expect(controller.getProject().ui.selectedSourceId).to.equal('sfx-3');
+    expect(sourceList.getAttribute('aria-activedescendant')).to.equal('midi-source-option-sfx-3');
+  });
+
+  it('moves source, track, and clip listbox selections from the keyboard', function() {
+    const { controller, doc } = createControllerHarness({
+      factoryConfig: {
+        enabled: false,
+        input: { channel: 'omni' },
+        sfx: {
+          '1': { name: 'skill-select', note: 60, durationTicks: 4 },
+          '2': { name: 'builder', note: 62, durationTicks: 4 }
+        },
+        triggers: {}
+      }
+    });
     controller.bindMidiUi();
-    expect(buttonB.classList.contains('active')).to.equal(true);
-    expect(panelB.classList.contains('active')).to.equal(true);
-    expect(sectionA.open).to.equal(false);
-    expect(sectionB.open).to.equal(true);
-
-    sectionA.open = true;
-    sectionA.dispatchEvent({ type: 'toggle' });
-    expect(JSON.parse(win.localStorage.getItem('lemmings.midi.sectionStates')).a).to.equal(true);
-
-    buttonA.dispatchEvent({ type: 'click' });
-    expect(win.localStorage.getItem('lemmings.midi.tabLeft')).to.equal('panelA');
-
-    inputSelect.value = 'device';
-    inputSelect.dispatchEvent({ type: 'change', target: inputSelect });
-    expect(win.localStorage.getItem('lemmings.midi.tabLeft')).to.equal(null);
-    expect(win.localStorage.getItem('lemmings.midi.sectionStates')).to.equal(null);
+    let prevented = 0;
+    const keydown = (element, key) => element.dispatchEvent({
+      type: 'keydown',
+      key,
+      preventDefault() {
+        prevented += 1;
+      }
+    });
+
+    const sourceList = doc.getElementById('midiSourceList');
+    expect(sourceList.getAttribute('aria-activedescendant')).to.equal('midi-source-option-sfx-1');
+    keydown(sourceList, 'ArrowDown');
+    expect(controller.getProject().ui.selectedSourceId).to.equal('sfx-2');
+    expect(sourceList.getAttribute('aria-activedescendant')).to.equal('midi-source-option-sfx-2');
+    expect(sourceList.children[1].getAttribute('aria-selected')).to.equal('true');
+    expect(sourceList.children[1].tabIndex).to.equal(0);
+
+    controller.dispatchProjectIntent({ type: 'track.add', track: { id: 'bass', name: 'Bass', channel: 2 } });
+    controller.dispatchProjectIntent({ type: 'track.select', trackId: 'track-1' });
+    const trackList = doc.getElementById('midiTrackList');
+    keydown(trackList, 'End');
+    expect(controller.getProject().ui.selectedTrackId).to.equal('bass');
+    expect(trackList.getAttribute('aria-activedescendant')).to.equal('midi-track-option-bass');
+
+    controller.dispatchProjectIntent({ type: 'clip.add', clip: { id: 'riff', name: 'Riff', lengthSteps: 4 } });
+    controller.dispatchProjectIntent({ type: 'clip.add', clip: { id: 'fill', name: 'Fill', lengthSteps: 4 } });
+    controller.dispatchProjectIntent({ type: 'clip.select', clipId: 'riff' });
+    const clipList = doc.getElementById('midiClipList');
+    keydown(clipList, 'End');
+    expect(controller.getProject().ui.selectedClipId).to.equal('fill');
+    expect(clipList.getAttribute('aria-activedescendant')).to.equal('midi-clip-option-fill');
+    keydown(clipList, 'Home');
+    expect(controller.getProject().ui.selectedClipId).to.equal('riff');
+    expect(clipList.getAttribute('aria-activedescendant')).to.equal('midi-clip-option-riff');
+    expect(prevented).to.equal(4);
   });
 
-  it('captures notes and updates mapping entries', function() {
-    const doc = new TestDocument();
-    const win = createTestWindow();
-    const eventList = register(doc, 'div', 'midiEventList');
-    register(doc, 'div', 'midiTriggerList');
-    register(doc, 'select', 'midiEnvTarget');
-    register(doc, 'div', 'errorDisplay');
-
-    const trapId = SoundEffectIds.TRAP_ZAP;
-    const config = {
-      scale: { name: 'major', root: 0, degrees: [0, 2, 4, 5, 7, 9, 11] },
-      sfx: {
-        [trapId]: {
-          name: 'Trap',
-          degree: 1,
-          octave: 2,
-          arp: { enabled: true, mode: 'up', length: 2, independent: true },
-          priority: 2
-        }
+  it('removes selected tracks and cancels learn capture for that track', function() {
+    const captureCalls = [];
+    const fakeInputController = {
+      setNoteCapture(handler) {
+        captureCalls.push(handler);
       },
-      triggers: { '1': { note: 60 } },
-      timing: { bpmBase: 120 }
+      attach() {},
+      detach() {}
     };
+    const { controller, doc } = createControllerHarness({
+      factoryConfig: {
+        enabled: false,
+        input: { channel: 'omni' },
+        position: { mappings: [] },
+        sfx: { '1': { name: 'skill-select', note: 60, durationTicks: 4 } },
+        triggers: {}
+      }
+    });
+    controller.setMidiInputController(fakeInputController);
+    controller.bindMidiUi();
+    const remove = doc.getElementById('midiTrackRemove');
+    expect(remove.disabled).to.equal(true);
+
+    controller.dispatchProjectIntent({ type: 'track.add', track: { id: 'lead', name: 'Lead', channel: 3 } });
+    controller.dispatchProjectIntent({ type: 'track.add', track: { id: 'drums', name: 'Drums', channel: 10 } });
+    controller.dispatchProjectIntent({ type: 'source.assignTrack', sourceId: 'sfx-1', trackId: 'drums' });
+    controller.dispatchProjectIntent({
+      type: 'automation.add',
+      automation: { id: 'lane-drums', scope: 'track', trackId: 'drums', target: 'velocity', axis: 'y' }
+    });
+    expect(remove.disabled).to.equal(false);
+    expect(controller.startLearn()).to.equal(true);
+    expect(captureCalls.at(-1)).to.be.a('function');
+
+    remove.dispatchEvent({ type: 'click', target: remove });
+
+    const project = controller.getProject();
+    expect(captureCalls.at(-1)).to.equal(null);
+    expect(project.tracks.map(track => track.id)).to.deep.equal(['track-1', 'lead']);
+    expect(project.ui.selectedTrackId).to.equal('lead');
+    expect(project.sources[0].trackId).to.equal('lead');
+    expect(project.automation).to.have.lengthOf(0);
+    expect(doc.getElementById('midiLearnStatus').textContent).to.equal('Learn waits for the next note-on.');
+    expect(doc.getElementById('midiProjectStatus').textContent).to.equal('Removed track Drums');
+    expect(doc.getElementById('midiOutputLog').textContent).to.contain('Removed track Drums');
+  });
 
-    let noteCaptureHandler = null;
-    const midiInputController = {
-      setNoteCapture(handler) {
-        noteCaptureHandler = handler;
+  it('keeps a clip listbox option active when no clip is selected', function() {
+    const { controller, doc } = createControllerHarness();
+    controller.bindMidiUi();
+    controller.dispatchProjectIntent({ type: 'clip.add', clip: { id: 'riff', name: 'Riff', lengthSteps: 4 } });
+    controller.dispatchProjectIntent({ type: 'clip.add', clip: { id: 'fill', name: 'Fill', lengthSteps: 4 } });
+    controller.dispatchProjectIntent({
+      type: 'project.set',
+      project: {
+        ...controller.getProject(),
+        ui: {
+          ...controller.getProject().ui,
+          selectedClipId: null
+        }
       }
-    };
+    });
 
-    const controller = createMidiUiController({
-      document: doc,
-      window: win,
-      getMidiConfig: () => config
+    const clipList = doc.getElementById('midiClipList');
+    const activeId = clipList.getAttribute('aria-activedescendant');
+    const active = clipList.children.find(row => row.id === activeId);
+    expect(activeId).to.equal('midi-clip-option-riff');
+    expect(active.tabIndex).to.equal(0);
+    expect(active.getAttribute('aria-selected')).to.equal('false');
+    expect(controller.getProject().ui.selectedClipId).to.equal(null);
+
+    clipList.dispatchEvent({
+      type: 'keydown',
+      key: 'ArrowDown',
+      preventDefault() {}
     });
+    expect(controller.getProject().ui.selectedClipId).to.equal('fill');
+    expect(clipList.getAttribute('aria-activedescendant')).to.equal('midi-clip-option-fill');
+  });
 
-    controller.setMidiInputController(midiInputController);
-    controller.refreshMidiUiFromConfig();
+  it('panics by stopping notes and clearing queued MIDI events', function() {
+    let allNotesOffCalls = 0;
+    let clearQueueCalls = 0;
+    const { controller, doc } = createControllerHarness({
+      lemmings: {
+        midiRouter: {
+          scheduler: {
+            allNotesOff() {
+              allNotesOffCalls += 1;
+            },
+            clearQueue() {
+              clearQueueCalls += 1;
+            }
+          }
+        }
+      }
+    });
+    controller.bindMidiUi();
 
-    const mapping = eventList.children[0];
-    const summary = findElement(mapping, el => el.tagName === 'SUMMARY');
-    const enabledToggle = findElement(mapping, el => (
-      el.tagName === 'INPUT' && el.type === 'checkbox'
-    ));
-    const enabledLabel = findElement(mapping, el => el.className === 'panel-title-toggle');
-    summary.dispatchEvent({ type: 'click', target: enabledToggle, preventDefault() {} });
-    summary.dispatchEvent({ type: 'click', target: summary.children[0], preventDefault() {} });
-    enabledLabel.dispatchEvent({ type: 'click', stopPropagation() {} });
-    enabledToggle.dispatchEvent({ type: 'click', stopPropagation() {} });
-
-    const modeSelect = findRowInputByLabel(mapping, 'Mode');
-    const keySelect = findRowInputByLabel(mapping, 'Key');
-    const noteOctave = findRowInputByLabel(mapping, 'Octave');
-    const degreeInput = findRowInputByLabel(mapping, 'Degree');
-    const scaleOctave = findRowInputByLabel(mapping, 'Scale octave');
-    const chordSelect = findRowInputByLabel(mapping, 'Chord');
-    const arpToggle = findRowInputByLabel(mapping, 'Arp');
-    const arpMode = findRowInputByLabel(mapping, 'Arp mode');
-    const arpLength = findRowInputByLabel(mapping, 'Arp length');
-    const arpIndependent = findRowInputByLabel(mapping, 'Independent arp');
-    const priorityInput = findRowInputByLabel(mapping, 'Priority');
-
-    noteOctave.focus = () => noteOctave.dispatchEvent({ type: 'focus', target: noteOctave });
-    degreeInput.focus = () => degreeInput.dispatchEvent({ type: 'focus', target: degreeInput });
-    keySelect.focus = () => keySelect.dispatchEvent({ type: 'focus', target: keySelect });
-    const keyRow = findElement(mapping, el => (
-      el.tagName === 'LABEL' && el.children?.[0]?.textContent === 'Key'
-    ));
-    keyRow?.children?.[0]?.dispatchEvent({
-      type: 'click',
-      preventDefault() {},
-      stopPropagation() {}
+    expect(controller.panic()).to.equal(true);
+    expect(allNotesOffCalls).to.equal(1);
+    expect(clearQueueCalls).to.equal(1);
+    expect(doc.getElementById('midiOutputLog').textContent).to.contain('Panic sent');
+  });
+
+  it('shows queued scheduler pressure when no rate limit is active', function() {
+    const { controller, doc } = createControllerHarness({
+      lemmings: {
+        midiRouter: {
+          getRateReport() {
+            return null;
+          },
+          getRateSnapshot() {
+            return {
+              past: { count: 0 },
+              next: { count: 3 }
+            };
+          }
+        }
+      }
     });
 
-    modeSelect.value = 'degree';
-    modeSelect.dispatchEvent({ type: 'change', target: modeSelect });
-    degreeInput.dispatchEvent({ type: 'focus', target: degreeInput });
-    expect(noteCaptureHandler).to.be.a('function');
-    noteCaptureHandler(61);
-
-    modeSelect.value = 'note';
-    modeSelect.dispatchEvent({ type: 'change', target: modeSelect });
-    keySelect.dispatchEvent({ type: 'focus', target: keySelect });
-    expect(noteCaptureHandler).to.be.a('function');
-    noteCaptureHandler(60);
-    degreeInput.dispatchEvent({ type: 'focus', target: degreeInput });
-    degreeInput.dispatchEvent({ type: 'blur', target: degreeInput });
-
-    config.scale.degrees = null;
-    modeSelect.value = 'degree';
-    modeSelect.dispatchEvent({ type: 'change', target: modeSelect });
-    degreeInput.dispatchEvent({ type: 'focus', target: degreeInput });
-    expect(noteCaptureHandler).to.be.a('function');
-    noteCaptureHandler(62);
-
-    modeSelect.value = 'chord';
-    modeSelect.dispatchEvent({ type: 'change', target: modeSelect });
-    chordSelect.value = 'seventh';
-    chordSelect.dispatchEvent({ type: 'change', target: chordSelect });
-
-    arpToggle.checked = true;
-    arpMode.value = 'down';
-    arpLength.value = '4';
-    arpIndependent.checked = true;
-    priorityInput.value = '3';
-    enabledToggle.checked = false;
-    [arpToggle, arpMode, arpLength, arpIndependent, priorityInput, enabledToggle]
-      .forEach(el => el.dispatchEvent({ type: 'change', target: el }));
-
-    expect(controller.getMidiOverrides().sfx[trapId].priority).to.equal(3);
-    expect(controller.getMidiOverrides().sfx[trapId].disabled).to.equal(true);
-    expect(noteCaptureHandler).to.equal(null);
+    controller.bindMidiUi();
+    expect(doc.getElementById('midiSchedulerPressure').textContent).to.equal('Scheduler: queued 3');
   });
 
-  it('updates position mappings and defaults', function() {
-    const doc = new TestDocument();
-    const win = createTestWindow();
-    const positionList = register(doc, 'div', 'midiPositionList');
-    const positionAdd = register(doc, 'button', 'midiPositionAdd');
-    const intensity = registerRangeInput(doc, 'midiIntensity');
-    const accent = registerRangeInput(doc, 'midiAccent');
-    const repeatEnabled = register(doc, 'input', 'midiRepeatEnabled');
-    const repeatSection = register(doc, 'details', 'midiRepeatSection');
-    repeatSection.dataset.sectionKey = 'repeat';
-    const repeatCount = register(doc, 'input', 'midiRepeatCount');
-    const repeatSpacing = register(doc, 'select', 'midiRepeatSpacing');
-    const repeatTarget = register(doc, 'select', 'midiRepeatTarget');
-    const repeatAmount = register(doc, 'input', 'midiRepeatAmount');
-    const keySelect = register(doc, 'select', 'midiKeySelect');
-    const scaleSelect = register(doc, 'select', 'midiScaleSelect');
-    register(doc, 'div', 'midiEventList');
-    register(doc, 'div', 'midiTriggerList');
-    register(doc, 'select', 'midiEnvTarget');
-    register(doc, 'div', 'errorDisplay');
-
-    const config = {
-      position: {
-        xNoteRange: { min: 1, max: 12 },
-        panRange: { min: -1, max: 1 },
-        timbreRange: { min: 10, max: 100 },
-        mappings: [
-          { axis: 'x', target: 'note', min: 1, max: 12 },
-          { axis: 'y', target: 'velocity' },
-          { axis: 'xy', target: 'timbre' },
-          { axis: 'x', axisX: false, axisY: false, target: 'pan' },
-          { axis: 'x', target: 'duration' },
-          { axis: 'x', target: 'pitchBend' },
-          { axis: 'x', target: 'attack' },
-          { axis: 'x', target: 'sustain' },
-          { axis: 'x', target: 'unknown' }
-        ]
-      },
-      velocityRange: { min: 2, max: 120, default: 80 },
-      repeat: { windowBeats: 0.3 },
-      durationTicks: { min: 2, max: 16 },
-      timing: { bpmBase: 120 }
+  it('shows track output labels in track rows', function() {
+    const webMidi = {
+      enabled: true,
+      inputs: [],
+      outputs: [{ id: 'out-1', name: 'Output 1' }]
     };
+    const { controller, doc } = createControllerHarness({ webMidi });
+    controller.bindMidiUi();
 
-    let throwRefresh = false;
-    const originalGet = doc.getElementById.bind(doc);
-    doc.getElementById = (id) => {
-      if (throwRefresh && id === 'midiEventList') {
-        throw new Error('boom');
-      }
-      return originalGet(id);
-    };
+    let row = doc.getElementById('midiTrackList').children[0];
+    expect(row.children[1].textContent).to.contain('Project output');
+    expect(row.getAttribute('aria-label')).to.contain('Project output');
 
-    const controller = createMidiUiController({
-      document: doc,
-      window: win,
-      getMidiConfig: () => config
-    });
+    controller.dispatchProjectIntent({ type: 'track.update', trackId: 'track-1', patch: { outputId: 'out-1' } });
+    row = doc.getElementById('midiTrackList').children[0];
+    expect(row.children[1].textContent).to.contain('Output 1');
+    expect(row.getAttribute('aria-label')).to.contain('Output 1');
 
-    controller.bindMidiUi();
-    controller.refreshMidiUiFromConfig();
-    controller.refreshMidiUiFromConfig();
-    expect(repeatSpacing.children.some(child => child.value === '0.3')).to.equal(true);
-    accent.input.value = '0.4';
-    accent.input.dispatchEvent({ type: 'change', target: accent.input });
-    intensity.input.value = '75';
-    intensity.input.dispatchEvent({ type: 'change', target: intensity.input });
-    keySelect.value = '5';
-    keySelect.dispatchEvent({ type: 'change', target: keySelect });
-    scaleSelect.value = 'major';
-    scaleSelect.dispatchEvent({ type: 'change', target: scaleSelect });
-    repeatTarget.value = 'duration';
-    repeatTarget.dispatchEvent({ type: 'change', target: repeatTarget });
-    repeatAmount.value = '0.5';
-    repeatAmount.dispatchEvent({ type: 'change', target: repeatAmount });
-    repeatCount.value = '2';
-    repeatCount.dispatchEvent({ type: 'change', target: repeatCount });
-    const firstMapping = positionList.children[0];
-    const axisX = findElement(firstMapping, el => (
-      el.tagName === 'LABEL' && el.children?.[1]?.textContent === 'X'
-    ))?.children?.[0];
-    const axisY = findElement(firstMapping, el => (
-      el.tagName === 'LABEL' && el.children?.[1]?.textContent === 'Y'
-    ))?.children?.[0];
-    const axisOp = findElement(firstMapping, el => (
-      el.tagName === 'SELECT' && el.children?.[0]?.textContent === '+'
-    ));
-    const targetSelect = findElement(firstMapping, el => (
-      el.tagName === 'SELECT' &&
-      Array.from(el.children || []).some(child => child.textContent === 'Note offset')
-    ));
-    const minInput = findElement(firstMapping, el => (
-      el.tagName === 'INPUT' && el.type === 'number'
-    ));
-    const maxInput = findElement(firstMapping, el => (
-      el.tagName === 'INPUT' && el.type === 'number' && el !== minInput
-    ));
-    const removeButton = findElement(firstMapping, el => (
-      el.tagName === 'BUTTON' && el.textContent === 'Remove'
-    ));
-
-    axisX.checked = false;
-    axisY.checked = false;
-    axisX.dispatchEvent({ type: 'change', target: axisX });
-    axisY.dispatchEvent({ type: 'change', target: axisY });
-    axisOp.value = 'sub';
-    axisOp.dispatchEvent({ type: 'change', target: axisOp });
-    targetSelect.value = 'pan';
-    targetSelect.dispatchEvent({ type: 'change', target: targetSelect });
-    minInput.value = '4';
-    maxInput.value = '8';
-    maxInput.dispatchEvent({ type: 'change', target: maxInput });
-    minInput.value = '';
-    maxInput.value = '';
-    minInput.dispatchEvent({ type: 'change', target: minInput });
-    throwRefresh = true;
-    removeButton.dispatchEvent({ type: 'click', target: removeButton });
-    throwRefresh = false;
+    controller.dispatchProjectIntent({ type: 'track.update', trackId: 'track-1', patch: { outputId: 'missing-out' } });
+    row = doc.getElementById('midiTrackList').children[0];
+    expect(row.children[1].textContent).to.contain('Unavailable: missing-out');
+    expect(row.getAttribute('aria-label')).to.contain('Unavailable: missing-out');
+  });
 
-    repeatEnabled.checked = true;
-    repeatEnabled.dispatchEvent({ type: 'click', stopPropagation() {} });
-    repeatEnabled.dispatchEvent({ type: 'change', target: repeatEnabled });
+  it('rerenders sanitized track numeric controls after invalid edits', function() {
+    const { controller, doc, view } = createControllerHarness();
+    controller.bindMidiUi();
 
-    throwRefresh = true;
-    positionAdd.dispatchEvent({ type: 'click' });
-    throwRefresh = false;
-    const overrides = controller.getMidiOverrides();
-    expect(overrides.position.mappings[overrides.position.mappings.length - 1].min).to.equal(1);
+    const channel = doc.getElementById('midiTrackChannel');
+    channel.value = '99';
+    channel.dispatchEvent({ type: 'change', target: channel });
+    expect(controller.getProject().tracks[0].channel).to.equal(16);
+    expect(channel.value).to.equal('16');
+    expect(view.projectConfigs.at(-1).sfx['1'].channel).to.equal(16);
+
+    const voiceBudget = doc.getElementById('midiTrackVoiceBudget');
+    voiceBudget.value = '99';
+    voiceBudget.dispatchEvent({ type: 'change', target: voiceBudget });
+    expect(controller.getProject().tracks[0].voiceBudget).to.equal(32);
+    expect(voiceBudget.value).to.equal('32');
+
+    const velocityScale = doc.getElementById('midiTrackVelocityScale');
+    velocityScale.value = '9';
+    velocityScale.dispatchEvent({ type: 'change', target: velocityScale });
+    expect(controller.getProject().tracks[0].velocityScale).to.equal(4);
+    expect(velocityScale.value).to.equal('4');
   });
 
-  it('builds axis defaults from legacy position flags', function() {
-    const doc = new TestDocument();
-    const win = createTestWindow();
-    const positionList = register(doc, 'div', 'midiPositionList');
-    register(doc, 'select', 'midiKeySelect');
-    register(doc, 'select', 'midiScaleSelect');
-    register(doc, 'div', 'midiEventList');
-    register(doc, 'div', 'midiTriggerList');
-    register(doc, 'select', 'midiEnvTarget');
-    register(doc, 'div', 'errorDisplay');
-
-    const config = { timing: { bpmBase: 120 } };
-
-    const controller = createMidiUiController({
-      document: doc,
-      window: win,
-      getMidiConfig: () => config
+  it('summarizes selected source route channel and output', function() {
+    const webMidi = {
+      enabled: true,
+      inputs: [],
+      outputs: [{ id: 'out-1', name: 'Output 1' }]
+    };
+    const { controller, doc } = createControllerHarness({ webMidi });
+    controller.bindMidiUi();
+    controller.dispatchProjectIntent({
+      type: 'track.update',
+      trackId: 'track-1',
+      patch: { channel: 4, outputId: 'out-1' }
     });
 
-    controller.__test__.buildPositionMappingList(positionList, [
-      { axis: 'xy', target: 'velocity' },
-      { axis: 'y', target: 'note' },
-      { axis: 'x', target: 'pan' }
-    ], config);
-    expect(positionList.children.length).to.be.greaterThan(0);
+    const summary = doc.getElementById('midiSelectedSourceSummary').textContent;
+    expect(summary).to.contain('routes to Track 1 (ch 4, Output 1)');
+    expect(summary).to.contain('direct mode');
   });
 
-  it('refreshes devices and debug output and schedules device updates', function() {
-    const doc = new TestDocument();
-    setupRichSelectors(doc);
-    doc.body = doc.createElement('body');
-    const win = createTestWindow();
-    const intervals = [];
-    const timeouts = [];
-    const dispatched = [];
-    win.setInterval = (cb) => {
-      intervals.push(cb);
-      return intervals.length;
-    };
-    win.setTimeout = (cb) => {
-      timeouts.push(cb);
-      return timeouts.length;
+  it('shows no-device setup state and clears routed outputs', function() {
+    let registeredOutputs = null;
+    let allNotesOffCalls = 0;
+    let clearQueueCalls = 0;
+    const webMidi = {
+      enabled: true,
+      inputs: [],
+      outputs: [],
+      addListener() {},
+      removeListener() {}
     };
-    win.dispatchEvent = (event) => dispatched.push(event.type);
-
-    const enabledToggle = register(doc, 'input', 'midiEnabledToggle');
-    const inputSelect = register(doc, 'select', 'midiInSelect');
-    const outputSelect = register(doc, 'select', 'midiOutSelect');
-    const inputChannel = register(doc, 'select', 'midiInputChannel');
-    const viewPan = register(doc, 'input', 'midiViewPanToggle');
-    const resetButton = register(doc, 'button', 'midiResetButton');
-    const defaultsButton = register(doc, 'button', 'midiDefaultsButton');
-    const panelToggle = register(doc, 'div', 'midiPanelToggle');
-    const leftPanel = register(doc, 'div', 'controlLeft');
-    const bpmBase = register(doc, 'input', 'midiBpmBase');
-    const bpmCurrent = register(doc, 'span', 'midiBpmCurrent');
-    const debugInput = register(doc, 'span', 'midiDebugInput');
-    const debugOutput = register(doc, 'span', 'midiDebugOutput');
-    register(doc, 'div', 'errorDisplay');
-
-    win.localStorage.setItem('lemmings.midi.viewPan', 'true');
-    win.localStorage.setItem('lemmings.midi.inputId', 'missing');
-    win.localStorage.setItem('lemmings.midi.outputId', 'out-2');
-    win.localStorage.setItem('lemmings.midi.inputChannel', '2');
-
-    const inputs = [{ id: 'in-1', name: 'Input A' }];
-    const outputs = [
-      { id: 'out-1', name: 'Output A' },
-      { id: 'out-2', name: 'Output B' }
-    ];
-    const webMidi = createWebMidiStub(inputs, outputs);
-    const schedulerCalls = [];
-    const applied = [];
-    const timerState = { tps: Infinity, speedFactor: 1 };
-    const lemmings = {
-      midiRouter: {
-        scheduler: {
-          allNotesOff() { schedulerCalls.push('off'); },
-          clearQueue() { schedulerCalls.push('clear'); }
+    const { controller, doc, view } = createControllerHarness({
+      webMidi,
+      lemmings: {
+        midiRouter: {
+          scheduler: {
+            setOutputs(outputs) {
+              registeredOutputs = outputs;
+            },
+            allNotesOff() {
+              allNotesOffCalls += 1;
+            },
+            clearQueue() {
+              clearQueueCalls += 1;
+            }
+          }
         }
-      },
-      applyMidiOverrides(patch) { applied.push(patch); },
-      getMidiSchemaHash: () => null,
-      game: { getGameTimer() { return timerState; } }
-    };
-
-    const controller = createMidiUiController({
-      document: doc,
-      window: win,
-      getLemmings: () => lemmings,
-      getWebMidi: () => webMidi,
-      getMidiConfig: () => ({ timing: { bpmBase: 90 } })
+      }
     });
 
     controller.bindMidiUi();
-    controller.bindMidiUi();
-    win.lastMidiInputMessage = [144, 60, 127];
-    win.lastMidiOutputMessage = { note: 61, velocity: 100, channel: 2 };
-    intervals.forEach(cb => cb());
-    expect(debugInput.textContent).to.contain('Input: 90 3c 7f');
-    expect(debugOutput.textContent).to.contain('note 61');
-
-    delete timerState.tps;
-    timerState.frameTime = 16;
-    timerState.speedFactor = 0;
-    win.lastMidiOutputMessage = [1, 2, 3];
-    intervals.forEach(cb => cb());
-
-    win.lastMidiInputMessage = 'raw';
-    win.lastMidiOutputMessage = 'raw';
-    intervals.forEach(cb => cb());
-
-    win.lastMidiOutputMessage = { note: NaN, velocity: NaN, channel: NaN };
-    intervals.forEach(cb => cb());
-
-    win.lastMidiOutputMessage = null;
-    win.lastMidiInputMessage = [];
-    intervals.forEach(cb => cb());
-    expect(debugOutput.textContent).to.contain('--');
-
-    globalThis.Event = function Event(type) { this.type = type; };
-    panelToggle.dispatchEvent({ type: 'click' });
-    timeouts.shift()();
-    expect(dispatched).to.include('resize');
-    expect(leftPanel.classList.contains('collapsed')).to.equal(true);
-    delete globalThis.Event;
-
-    const midiInputController = {
-      attach(device) { this.attached = device; },
-      detach() { this.detached = true; },
-      setNoteCapture() {}
-    };
-    controller.setMidiInputController(midiInputController);
     controller.onEnabled();
-    controller.onEnabled();
-    const timerCount = timeouts.length;
-    webMidi.emit('connected');
-    webMidi.emit('connected');
-    expect(timeouts.length - timerCount).to.equal(1);
-    expect(inputSelect.value).to.equal('in-1');
-    expect(outputSelect.value).to.equal('out-2');
-    expect(viewPan.checked).to.equal(true);
-    expect(globalThis.lemmingsMidiViewPan).to.equal(true);
-    expect(midiInputController.attached).to.equal(inputs[0]);
-    expect(lemmings.midiOut).to.equal(outputs[1]);
-    outputSelect.value = 'out-1';
-    outputSelect.dispatchEvent({ type: 'change', target: outputSelect });
-    viewPan.checked = false;
-    viewPan.dispatchEvent({ type: 'change', target: viewPan });
-    resetButton.dispatchEvent({ type: 'click' });
-    defaultsButton.dispatchEvent({ type: 'click' });
-    expect(applied[applied.length - 1]).to.eql({});
-    enabledToggle.checked = true;
-    enabledToggle.dispatchEvent({ type: 'change', target: enabledToggle });
-
-    enabledToggle.checked = false;
-    enabledToggle.dispatchEvent({ type: 'change', target: enabledToggle });
-    expect(midiInputController.detached).to.equal(true);
-
-    while (timeouts.length) {
-      timeouts.shift()();
-    }
-
-    webMidi.enabled = false;
-    controller.setActiveMidiInput('in-1');
-    controller.setActiveMidiOutput('out-1');
 
-    webMidi.inputs = [];
-    webMidi.outputs = [];
-    webMidi.enabled = true;
-    controller.onEnabled();
-    controller.showError('nope');
-    const errorText = doc.getElementById('errorDisplay').innerHTML;
-    expect(errorText).to.contain('nope');
-    controller.showError(null);
+    expect(registeredOutputs).to.deep.equal([]);
+    expect(view.midiOut).to.equal(null);
+    expect(controller.getProject().devices).to.include({ inputId: null, outputId: null });
+    expect(doc.getElementById('midiInSelect').disabled).to.equal(true);
+    expect(doc.getElementById('midiOutSelect').disabled).to.equal(true);
+    expect(doc.getElementById('errorDisplay').textContent).to.contain('No input device');
+    expect(doc.getElementById('errorDisplay').textContent).to.contain('No output device');
+    expect(allNotesOffCalls).to.equal(1);
+    expect(clearQueueCalls).to.equal(1);
   });
 
-  it('retries scheduled refresh after errors', function() {
-    const doc = new TestDocument();
-    const originalGet = doc.getElementById.bind(doc);
-    let throwOnce = true;
-    doc.getElementById = (id) => {
-      if (throwOnce) {
-        throwOnce = false;
-        throw new Error('boom');
-      }
-      return originalGet(id);
-    };
-    const win = createTestWindow();
-    const timeouts = [];
-    win.setTimeout = (cb) => {
-      timeouts.push(cb);
-      return timeouts.length;
+  it('refreshes mocked devices, auditions through the selected track, and panics', function() {
+    const sent = [];
+    let registeredOutputs = [];
+    const webMidi = {
+      enabled: true,
+      inputs: [{ id: 'in-1', name: 'Input 1', addListener() {}, removeListener() {} }],
+      outputs: [{ id: 'out-1', name: 'Output 1' }],
+      getInputById(id) { return this.inputs.find(input => input.id === id) || null; },
+      getOutputById(id) { return this.outputs.find(output => output.id === id) || null; },
+      addListener() {},
+      removeListener() {}
     };
+    const { controller, doc, view } = createControllerHarness({
+      webMidi,
+      lemmings: {
+        midiRouter: {
+          getRateReport() {
+            return { reason: 'count-limit' };
+          },
+          scheduler: {
+            setOutputs(outputs) {
+              registeredOutputs = outputs;
+            },
+            sendNote(spec, meta) {
+              sent.push({ spec, meta });
+              return true;
+            },
+            allNotesOff() {
+              sent.push({ panic: true });
+            },
+            clearQueue() {}
+          }
+        }
+      }
+    });
 
-    const controller = createMidiUiController({
-      document: doc,
-      window: win,
-      getMidiConfig: () => ({ timing: { bpmBase: 120 } })
+    controller.bindMidiUi();
+    expect(doc.getElementById('midiSchedulerPressure').textContent).to.equal('Scheduler: count-limit');
+    controller.dispatchProjectIntent({ type: 'enabled.set', enabled: true });
+    controller.dispatchProjectIntent({
+      type: 'track.update',
+      trackId: 'track-1',
+      patch: { channel: 4, priority: 4, velocityScale: 0.5, voiceBudget: 5 }
+    });
+    controller.dispatchProjectIntent({
+      type: 'source.mapping.update',
+      sourceId: 'sfx-1',
+      patch: { velocity: 100, pan: -32, timbre: 91, pitchBend: 0.5 }
     });
+    controller.onEnabled();
 
-    controller.scheduleMidiUiRefresh();
-    while (timeouts.length) {
-      timeouts.shift()();
-    }
+    expect(doc.getElementById('midiInSelect').value).to.equal('in-1');
+    expect(doc.getElementById('midiOutSelect').value).to.equal('out-1');
+    expect(doc.getElementById('midiTrackOutputSelect').children.map(option => option.value)).to.include('out-1');
+    expect(view.midiOut).to.equal(webMidi.outputs[0]);
+    expect(registeredOutputs).to.deep.equal(webMidi.outputs);
+
+    const trackOutput = doc.getElementById('midiTrackOutputSelect');
+    trackOutput.value = 'out-1';
+    trackOutput.dispatchEvent({ type: 'change', target: trackOutput });
+    expect(controller.getProject().tracks[0].outputId).to.equal('out-1');
+    expect(controller.getMidiConfig().sfx['1'].outputId).to.equal('out-1');
+
+    expect(controller.audition()).to.equal(true);
+    const note = sent.find(entry => entry.spec);
+    expect(note.spec).to.include({
+      note: 60,
+      velocity: 50,
+      durationTicks: 4,
+      channel: 4,
+      pan: -32,
+      timbre: 91,
+      pitchBend: 0.5,
+      trackId: 'track-1',
+      voiceBudget: 5,
+      outputId: 'out-1'
+    });
+    expect(note.meta).to.include({
+      eventType: 'audition',
+      priority: 4,
+      sourceId: 'sfx-1',
+      trackId: 'track-1',
+      voiceBudget: 5,
+      outputId: 'out-1'
+    });
+
+    expect(controller.panic()).to.equal(true);
+    expect(sent.some(entry => entry.panic)).to.equal(true);
   });
 
-  it('logs refresh errors during bpm updates', function() {
-    const doc = new TestDocument();
-    const win = createTestWindow();
-    register(doc, 'span', 'midiBpmCurrent');
-    let throwOnce = true;
-    const originalGet = doc.getElementById.bind(doc);
-    doc.getElementById = (id) => {
-      if (id === 'midiEventList' && throwOnce) {
-        throwOnce = false;
-        throw new Error('boom');
-      }
-      return originalGet(id);
+  it('falls back to the next output when the selected MIDI output disappears', function() {
+    let registeredOutputs = [];
+    let allNotesOffCalls = 0;
+    let clearQueueCalls = 0;
+    const out1 = { id: 'out-1', name: 'Output 1' };
+    const out2 = { id: 'out-2', name: 'Output 2' };
+    const webMidi = {
+      enabled: true,
+      inputs: [{ id: 'in-1', name: 'Input 1', addListener() {}, removeListener() {} }],
+      outputs: [out1],
+      getInputById(id) { return this.inputs.find(input => input.id === id) || null; },
+      getOutputById(id) { return this.outputs.find(output => output.id === id) || null; },
+      addListener() {},
+      removeListener() {}
     };
-
-    const controller = createMidiUiController({
-      document: doc,
-      window: win,
-      getMidiConfig: () => ({ timing: { bpmBase: 120 } })
+    const { controller, doc, view } = createControllerHarness({
+      webMidi,
+      lemmings: {
+        midiRouter: {
+          scheduler: {
+            setOutputs(outputs) {
+              registeredOutputs = outputs;
+            },
+            allNotesOff() {
+              allNotesOffCalls += 1;
+            },
+            clearQueue() {
+              clearQueueCalls += 1;
+            }
+          }
+        }
+      }
     });
 
     controller.bindMidiUi();
+    controller.onEnabled();
+    expect(controller.getProject().devices.outputId).to.equal('out-1');
+
+    allNotesOffCalls = 0;
+    clearQueueCalls = 0;
+    webMidi.outputs = [out2];
+    controller.onEnabled();
+
+    expect(controller.getProject().devices.outputId).to.equal('out-2');
+    expect(doc.getElementById('midiOutSelect').value).to.equal('out-2');
+    expect(view.midiOut).to.equal(out2);
+    expect(registeredOutputs).to.deep.equal([out2]);
+    expect(allNotesOffCalls).to.equal(1);
+    expect(clearQueueCalls).to.equal(1);
   });
 });
diff --git a/test/midi/midi-ui-domain.test.js b/test/midi/midi-ui-domain.test.js
index 8b4857a2..16d210c5 100644
--- a/test/midi/midi-ui-domain.test.js
+++ b/test/midi/midi-ui-domain.test.js
@@ -2,6 +2,14 @@ import { expect } from 'chai';
 import {
   NOTE_NAMES,
   CHORD_OPTIONS,
+  ARP_PATTERN_VERSION,
+  ARP_PATTERN_STEP_OPTIONS,
+  ARP_PATTERN_PRESETS,
+  ARP_PATTERN_DEFAULT_STEPS,
+  createArpPatternFromPreset,
+  sanitizeArpPattern,
+  deriveArpModeFromPattern,
+  migrateArpConfig,
   POSITION_AXIS_OPERATORS,
   POSITION_TARGETS,
   REPEAT_TARGETS,
@@ -11,6 +19,7 @@ import {
   TRAP_SFX_IDS,
   EXCLUDED_SFX_IDS,
   SFX_NAME_BY_ID,
+  listTriggerEntries,
   collectTriggerTypes,
   resolveAvailableSfxIds,
   resolvePositionMappings
@@ -18,11 +27,16 @@ import {
 import { SoundEffectIds } from '../../js/game/SoundEvents.js';
 import { TriggerTypes } from '../../js/level/TriggerTypes.js';
 import { SkillTypes } from '../../js/game/SkillTypes.js';
+import { toMidiFlagTriggerType } from '../../js/midi/MidiFlagTriggers.js';
 
 describe('midiUiDomain', function() {
   it('exports static option lists and maps', function() {
     expect(NOTE_NAMES).to.have.length(12);
     expect(CHORD_OPTIONS).to.include('triad');
+    expect(ARP_PATTERN_VERSION).to.equal(1);
+    expect(ARP_PATTERN_STEP_OPTIONS.map(option => option.value)).to.include('up');
+    expect(ARP_PATTERN_PRESETS.map(option => option.value)).to.include('custom');
+    expect(ARP_PATTERN_DEFAULT_STEPS).to.equal(8);
     expect(POSITION_AXIS_OPERATORS.map(op => op.value)).to.include('add');
     expect(POSITION_TARGETS.map(target => target.value)).to.include('note');
     expect(REPEAT_TARGETS.map(target => target.value)).to.include('velocity');
@@ -34,6 +48,29 @@ describe('midiUiDomain', function() {
     expect(SFX_NAME_BY_ID.get(SoundEffectIds.BUILDER_STEP)).to.equal('builder-step');
   });
 
+  it('creates and sanitizes arp pattern presets deterministically', function() {
+    const down = createArpPatternFromPreset('down', 4);
+    expect(down.steps).to.eql(['down', 'down', 'down', 'down']);
+    const custom = sanitizeArpPattern({
+      preset: 'custom',
+      steps: ['up', 'noop', 'down', 'hold']
+    }, 'up');
+    expect(custom.preset).to.equal('custom');
+    expect(custom.steps).to.eql(['up', 'hold', 'down', 'hold']);
+  });
+
+  it('derives arp mode and migrates arp configs from legacy payloads', function() {
+    const mode = deriveArpModeFromPattern({
+      preset: 'custom',
+      steps: ['down', 'down', 'down']
+    }, 'up');
+    expect(mode).to.equal('down');
+    const migrated = migrateArpConfig({ enabled: true, mode: 'updown', length: 5 });
+    expect(migrated.pattern.preset).to.equal('updown');
+    expect(migrated.mode).to.equal('updown');
+    expect(migrated.length).to.equal(5);
+  });
+
   it('collectTriggerTypes returns empty for missing level', function() {
     const types = collectTriggerTypes(null);
     expect(types.size).to.equal(0);
@@ -47,7 +84,10 @@ describe('midiUiDomain', function() {
         { type: 'not-a-number' }
       ],
       arrowRanges: [{}],
-      steelRanges: [{}]
+      steelRanges: [{}],
+      midiFlags: [
+        { id: 2 }
+      ]
     };
     const types = collectTriggerTypes(level);
 
@@ -57,6 +97,20 @@ describe('midiUiDomain', function() {
     expect(types.has(TriggerTypes.ONEWAY_LEFT)).to.equal(true);
     expect(types.has(TriggerTypes.ONEWAY_RIGHT)).to.equal(true);
     expect(types.has(TriggerTypes.STEEL)).to.equal(true);
+    expect(types.has(toMidiFlagTriggerType(2))).to.equal(true);
+  });
+
+  it('lists trigger entries including dynamic midi flag trigger ids', function() {
+    const flagTrigger = toMidiFlagTriggerType(7);
+    const entries = listTriggerEntries(
+      { triggers: { [flagTrigger]: { note: 72 } } },
+      new Set([TriggerTypes.TRAP, flagTrigger]),
+      { midiFlags: [{ id: 7, triggerType: flagTrigger }] }
+    );
+    const trap = entries.find(entry => entry.value === TriggerTypes.TRAP);
+    const flag = entries.find(entry => entry.value === flagTrigger);
+    expect(trap?.name).to.equal('TRAP');
+    expect(flag?.name).to.equal('MIDI_FLAG_7');
   });
 
   it('resolveAvailableSfxIds returns all ids when level and skills missing', function() {
@@ -235,15 +289,14 @@ describe('midiUiDomain', function() {
     expect(mappings[0].axisOp).to.equal('add');
   });
 
-  it('resolvePositionMappings builds legacy mappings and uses ranges', function() {
+  it('resolvePositionMappings preserves explicit mapping ranges', function() {
     const config = {
-      velocityRange: { min: 5, max: 120 },
       position: {
-        xToNote: true,
-        xNoteRange: { min: -5, max: 5 },
-        yToVelocity: true,
-        yToTimbre: true,
-        timbreRange: { min: 10, max: 20 }
+        mappings: [
+          { axis: 'x', target: 'note', min: -5, max: 5, enabled: true },
+          { axis: 'y', target: 'velocity', min: 120, max: 5, enabled: true },
+          { axis: 'y', target: 'timbre', min: 20, max: 10, enabled: true }
+        ]
       }
     };
 
@@ -261,46 +314,11 @@ describe('midiUiDomain', function() {
     expect(mappings[2].max).to.equal(10);
   });
 
-  it('resolvePositionMappings uses default ranges for x mappings when missing', function() {
+  it('resolvePositionMappings returns empty when mappings are omitted', function() {
     const config = {
       position: {
-        xToNote: true
-      }
-    };
-
-    const mappings = resolvePositionMappings(config);
-
-    expect(mappings).to.have.length(1);
-    expect(mappings[0].target).to.equal('note');
-    expect(mappings[0].min).to.equal(0);
-    expect(mappings[0].max).to.equal(0);
-  });
-
-  it('resolvePositionMappings uses default ranges when missing', function() {
-    const config = {
-      position: {
-        yToVelocity: true,
-        yToTimbre: true
-      }
-    };
-
-    const mappings = resolvePositionMappings(config);
-
-    expect(mappings).to.have.length(2);
-    expect(mappings[0].target).to.equal('velocity');
-    expect(mappings[0].min).to.equal(127);
-    expect(mappings[0].max).to.equal(1);
-    expect(mappings[1].target).to.equal('timbre');
-    expect(mappings[1].min).to.equal(127);
-    expect(mappings[1].max).to.equal(0);
-  });
-
-  it('resolvePositionMappings returns empty when legacy flags disabled', function() {
-    const config = {
-      position: {
-        xToNote: false,
-        yToVelocity: false,
-        yToTimbre: false
+        xToNote: true,
+        yToVelocity: true
       }
     };
 
diff --git a/test/midi/midi-ui-storage.test.js b/test/midi/midi-ui-storage.test.js
deleted file mode 100644
index 38fe2190..00000000
--- a/test/midi/midi-ui-storage.test.js
+++ /dev/null
@@ -1,97 +0,0 @@
-import { expect } from 'chai';
-import {
-  midiStorageKeys,
-  readStoredMidiId,
-  storeMidiId,
-  readStoredJson,
-  storeJson
-} from '../../js/app/midi-ui/midiUiStorage.js';
-
-const createStorage = () => {
-  const calls = { get: [], set: [], remove: [] };
-  return {
-    calls,
-    getItem: (key) => {
-      calls.get.push(key);
-      return null;
-    },
-    setItem: (key, value) => {
-      calls.set.push([key, value]);
-    },
-    removeItem: (key) => {
-      calls.remove.push(key);
-    }
-  };
-};
-
-describe('midiUiStorage', function() {
-  it('exports storage keys for MIDI settings', function() {
-    expect(midiStorageKeys.inputId).to.equal('lemmings.midi.inputId');
-    expect(midiStorageKeys.outputId).to.equal('lemmings.midi.outputId');
-    expect(midiStorageKeys.sectionStates).to.equal('lemmings.midi.sectionStates');
-  });
-
-  it('reads stored MIDI ids and handles failures', function() {
-    const storage = createStorage();
-    storage.getItem = () => 'device-1';
-    expect(readStoredMidiId(storage, 'key')).to.equal('device-1');
-
-    expect(readStoredMidiId(null, 'key')).to.equal(null);
-
-    const badStorage = { getItem: () => { throw new Error('nope'); } };
-    expect(readStoredMidiId(badStorage, 'key')).to.equal(null);
-  });
-
-  it('stores MIDI ids and clears when empty', function() {
-    const storage = createStorage();
-    storeMidiId(storage, 'input', 'midi-1');
-    storeMidiId(storage, 'input', '');
-
-    expect(storage.calls.set).to.deep.equal([['input', 'midi-1']]);
-    expect(storage.calls.remove).to.deep.equal(['input']);
-  });
-
-  it('swallows storage errors when writing MIDI ids', function() {
-    const storage = {
-      setItem: () => { throw new Error('fail'); },
-      removeItem: () => { throw new Error('fail'); }
-    };
-
-    expect(() => storeMidiId(storage, 'input', 'midi-2')).to.not.throw();
-    expect(() => storeMidiId(storage, 'input', null)).to.not.throw();
-  });
-
-  it('reads stored JSON and handles missing or invalid values', function() {
-    const storage = createStorage();
-    storage.getItem = () => '{"a":1}';
-    expect(readStoredJson(storage, 'key')).to.deep.equal({ a: 1 });
-
-    storage.getItem = () => null;
-    expect(readStoredJson(storage, 'key')).to.equal(null);
-
-    storage.getItem = () => '{bad';
-    expect(readStoredJson(storage, 'key')).to.equal(null);
-
-    const badStorage = { getItem: () => { throw new Error('nope'); } };
-    expect(readStoredJson(badStorage, 'key')).to.equal(null);
-  });
-
-  it('stores JSON and removes entries when nullish', function() {
-    const storage = createStorage();
-    storeJson(storage, 'overrides', { a: 1 });
-    storeJson(storage, 'overrides', null);
-
-    expect(storage.calls.set).to.deep.equal([['overrides', '{"a":1}']]);
-    expect(storage.calls.remove).to.deep.equal(['overrides']);
-  });
-
-  it('swallows storage errors when writing JSON', function() {
-    const storage = {
-      setItem: () => { throw new Error('fail'); },
-      removeItem: () => { throw new Error('fail'); }
-    };
-
-    expect(() => storeJson(storage, 'overrides', { a: 2 })).to.not.throw();
-    expect(() => storeJson(storage, 'overrides', null)).to.not.throw();
-  });
-});
diff --git a/test/objectmanager.render.test.js b/test/objectmanager.render.test.js
index 30f15e29..321725a9 100644
--- a/test/objectmanager.render.test.js
+++ b/test/objectmanager.render.test.js
@@ -41,4 +41,125 @@ describe('ObjectManager.render', function () {
       { frame: 'frame2', x: 30, y: 40, cfg: obj2.drawProperties }
     ]);
   });
+
+  it('skips off-screen objects once frame bounds are cached', function () {
+    const timer = { getGameTicks() { return 10; } };
+    const manager = new ObjectManager(timer);
+    const calls = { visible: 0, hidden: 0 };
+    const visible = {
+      x: 4,
+      y: 4,
+      drawProperties: {},
+      animation: {
+        getFrame() {
+          calls.visible += 1;
+          return { width: 8, height: 8 };
+        }
+      }
+    };
+    const hidden = {
+      x: 200,
+      y: 4,
+      drawProperties: {},
+      animation: {
+        getFrame() {
+          calls.hidden += 1;
+          return { width: 8, height: 8 };
+        }
+      }
+    };
+    manager.addRange([visible, hidden]);
+
+    const draws = [];
+    const display = {
+      stage: {
+        getGameViewRect() {
+          return { x: 0, y: 0, w: 50, h: 20 };
+        }
+      },
+      drawFrameFlags(frame, x, y, cfg) {
+        draws.push({ frame, x, y, cfg });
+      }
+    };
+
+    manager.render(display);
+    manager.render(display);
+
+    expect(calls.visible).to.equal(2);
+    expect(calls.hidden).to.equal(1);
+    expect(draws).to.have.length(2);
+    expect(draws[0].x).to.equal(4);
+    expect(draws[1].x).to.equal(4);
+  });
+
+  it('indexes known wide objects into every x bucket they span', function () {
+    const timer = { getGameTicks() { return 1; } };
+    const manager = new ObjectManager(timer);
+    let frameCalls = 0;
+    const wide = {
+      x: 0,
+      y: 4,
+      drawProperties: {},
+      animation: {
+        frames: [{ width: 400, height: 12 }],
+        getFrame() {
+          frameCalls += 1;
+          return { width: 400, height: 12 };
+        }
+      }
+    };
+    manager.addRange([wide]);
+
+    const draws = [];
+    manager.render({
+      stage: {
+        getGameViewRect() {
+          return { x: 380, y: 0, w: 50, h: 20 };
+        }
+      },
+      drawFrameFlags(frame, x, y) {
+        draws.push({ frame, x, y });
+      }
+    });
+
+    expect(frameCalls).to.equal(1);
+    expect(draws).to.have.length(1);
+    expect(wide.__objectManagerBuckets).to.include.members([0, 1, 2, 3]);
+  });
+
+  it('moves unknown-width objects into ranged buckets after their first frame', function () {
+    const timer = { getGameTicks() { return 1; } };
+    const manager = new ObjectManager(timer);
+    let frameCalls = 0;
+    const wide = {
+      x: 0,
+      y: 4,
+      drawProperties: {},
+      animation: {
+        getFrame() {
+          frameCalls += 1;
+          return { width: 400, height: 12 };
+        }
+      }
+    };
+    manager.addRange([wide]);
+    expect(manager._unknownWidthObjects).to.eql([wide]);
+
+    const display = {
+      stage: {
+        getGameViewRect() {
+          return { x: 380, y: 0, w: 50, h: 20 };
+        }
+      },
+      drawFrameFlags() {}
+    };
+
+    manager.render(display);
+    expect(frameCalls).to.equal(1);
+    expect(manager._unknownWidthObjects).to.have.length(0);
+    expect(wide.__objectManagerBuckets).to.include.members([0, 1, 2, 3]);
+
+    manager.render(display);
+    expect(frameCalls).to.equal(2);
+  });
 });
diff --git a/test/offline-tools/packPipeline.test.js b/test/offline-tools/packPipeline.test.js
new file mode 100644
index 00000000..f9affbd3
--- /dev/null
+++ b/test/offline-tools/packPipeline.test.js
@@ -0,0 +1,165 @@
+import { expect } from 'chai';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'url';
+import { BinaryReader } from '../../js/data/BinaryReader.js';
+import { FileContainer } from '../../js/data/FileContainer.js';
+import { PackFilePart } from '../../js/data/PackFilePart.js';
+
+const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const scriptPath = path.join(rootDir, 'tools', 'packPipeline.js');
+
+const makeTempDir = () => fs.mkdtempSync(path.join(os.tmpdir(), 'lemmings-pack-pipeline-'));
+const withTempDir = (fn) => {
+  const dir = makeTempDir();
+  try {
+    return fn(dir);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+};
+
+const writeWord = (buffer, offset, value) => {
+  buffer[offset] = (value >> 8) & 0xff;
+  buffer[offset + 1] = value & 0xff;
+};
+
+const buildDat = (parts) => {
+  const chunks = [];
+  for (let i = 0; i < parts.length; i += 1) {
+    const raw = Uint8Array.from(parts[i]);
+    const packed = PackFilePart.pack(raw);
+    const size = packed.byteArray.length + 10;
+    const header = new Uint8Array(10);
+    header[0] = packed.initialBits;
+    header[1] = packed.checksum;
+    writeWord(header, 2, 0);
+    writeWord(header, 4, raw.length);
+    writeWord(header, 6, 0);
+    writeWord(header, 8, size);
+    chunks.push(Buffer.from(header));
+    chunks.push(Buffer.from(packed.byteArray));
+  }
+  return Buffer.concat(chunks);
+};
+
+const runPackPipeline = (args = [], cwd = rootDir) => (
+  spawnSync(process.execPath, [scriptPath, ...args], { cwd })
+);
+
+const readDatPart = (datPath, index) => {
+  const packed = fs.readFileSync(datPath);
+  const container = new FileContainer(new BinaryReader(new Uint8Array(packed), 0, packed.length, datPath));
+  const reader = container.getPart(index);
+  reader.setOffset(0);
+  const out = new Uint8Array(reader.length);
+  for (let i = 0; i < out.length; i += 1) out[i] = reader.readByte();
+  return out;
+};
+
+describe('packPipeline', function () {
+  it('unpacks and repacks DAT containers without changing part data', function () {
+    withTempDir((dir) => {
+      const sourceParts = [
+        Uint8Array.from([1, 2, 3, 4, 5, 6]),
+        Uint8Array.from([9, 8, 7, 6, 5, 4, 3, 2])
+      ];
+      const inputDat = path.join(dir, 'input.dat');
+      const unpackDir = path.join(dir, 'unpack');
+      const outputDat = path.join(dir, 'output.dat');
+      fs.writeFileSync(inputDat, buildDat(sourceParts));
+
+      const unpack = runPackPipeline(['unpack', inputDat, unpackDir]);
+      expect(unpack.status).to.equal(0);
+      const metaPath = path.join(unpackDir, 'meta.json');
+      expect(fs.existsSync(metaPath)).to.equal(true);
+      const meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+      expect(meta.partCount).to.equal(2);
+      expect(fs.readFileSync(path.join(unpackDir, 'part-000.bin'))).to.deep.equal(Buffer.from(sourceParts[0]));
+      expect(fs.readFileSync(path.join(unpackDir, 'part-001.bin'))).to.deep.equal(Buffer.from(sourceParts[1]));
+
+      const repack = runPackPipeline(['pack', metaPath, outputDat]);
+      expect(repack.status).to.equal(0);
+      expect(readDatPart(outputDat, 0)).to.deep.equal(sourceParts[0]);
+      expect(readDatPart(outputDat, 1)).to.deep.equal(sourceParts[1]);
+    });
+  });
+
+  it('patches a decompressed part and writes a new DAT', function () {
+    withTempDir((dir) => {
+      const sourceParts = [
+        Uint8Array.from([10, 20, 30, 40]),
+        Uint8Array.from([1, 1, 1, 1, 1, 1])
+      ];
+      const inputDat = path.join(dir, 'input.dat');
+      const outputDat = path.join(dir, 'patched.dat');
+      const patchFile = path.join(dir, 'patch.bin');
+      fs.writeFileSync(inputDat, buildDat(sourceParts));
+      fs.writeFileSync(patchFile, Buffer.from([0xaa, 0xbb, 0xcc]));
+
+      const patch = runPackPipeline([
+        'patch',
+        inputDat,
+        outputDat,
+        '--part',
+        '1',
+        '--offset',
+        '2',
+        '--file',
+        patchFile
+      ]);
+
+      expect(patch.status).to.equal(0);
+      expect(readDatPart(outputDat, 0)).to.deep.equal(sourceParts[0]);
+      expect(readDatPart(outputDat, 1)).to.deep.equal(Uint8Array.from([1, 1, 0xaa, 0xbb, 0xcc, 1]));
+    });
+  });
+
+  it('rejects metadata part paths outside the metadata directory', function () {
+    withTempDir((dir) => {
+      const unpackDir = path.join(dir, 'unpack');
+      fs.mkdirSync(unpackDir, { recursive: true });
+      fs.writeFileSync(path.join(dir, 'secret.bin'), Buffer.from([9, 9, 9]));
+      fs.writeFileSync(path.join(unpackDir, 'part-000.bin'), Buffer.from([1, 2, 3]));
+      const metaPath = path.join(unpackDir, 'meta.json');
+      const outputDat = path.join(dir, 'output.dat');
+      fs.writeFileSync(metaPath, JSON.stringify({
+        format: 'lemmings-dat-pipeline-v1',
+        parts: [
+          { index: 0, file: '../secret.bin', decompressedSize: 3 }
+        ]
+      }));
+
+      const result = runPackPipeline(['pack', metaPath, outputDat]);
+      expect(result.status).to.not.equal(0);
+      expect(result.stderr.toString()).to.match(/escapes base directory/i);
+      expect(fs.existsSync(outputDat)).to.equal(false);
+    });
+  });
+
+  it('rejects absolute metadata part paths', function () {
+    withTempDir((dir) => {
+      const metaPath = path.join(dir, 'meta.json');
+      const absPart = path.join(dir, 'part-000.bin');
+      fs.writeFileSync(absPart, Buffer.from([1]));
+      fs.writeFileSync(metaPath, JSON.stringify({
+        format: 'lemmings-dat-pipeline-v1',
+        parts: [
+          { index: 0, file: absPart, decompressedSize: 1 }
+        ]
+      }));
+
+      const result = runPackPipeline(['pack', metaPath, path.join(dir, 'output.dat')]);
+      expect(result.status).to.not.equal(0);
+      expect(result.stderr.toString()).to.match(/escapes base directory/i);
+    });
+  });
+
+  it('prints usage when command arguments are missing', function () {
+    const result = runPackPipeline([]);
+    expect(result.status).to.equal(0);
+    expect(result.stdout.toString()).to.match(/Usage:/);
+  });
+});
diff --git a/test/particletable.test.js b/test/particletable.test.js
index 3172fd78..37fabcc2 100644
--- a/test/particletable.test.js
+++ b/test/particletable.test.js
@@ -59,6 +59,26 @@ describe('ParticleTable', function() {
     expect(() => pt.draw(null, 0, 0, 0)).to.not.throw();
   });
 
+  it('drawMany batches multiple particle draws for the same frame', function() {
+    const pal = makePalette();
+    const pt = new ParticleTable(pal);
+    const calls = [];
+    const display = {
+      drawFrame(frame, x, y) {
+        calls.push({ frame, x, y });
+      }
+    };
+    const count = pt.drawMany(display, 0, [
+      { x: 1, y: 2 },
+      { x: Number.NaN, y: 3 },
+      { x: 4, y: 5 }
+    ]);
+    expect(count).to.equal(2);
+    expect(calls).to.have.length(2);
+    expect(calls[0].x).to.equal(1);
+    expect(calls[1].x).to.equal(4);
+  });
+
   it('builds a placeholder frame when particle data is empty', function() {
     const originalCache = ParticleTable._frameCache;
     ParticleTable._frameCache = new WeakMap();
diff --git a/test/performance-instrumentation.test.js b/test/performance-instrumentation.test.js
new file mode 100644
index 00000000..3ed5ef37
--- /dev/null
+++ b/test/performance-instrumentation.test.js
@@ -0,0 +1,45 @@
+import { expect } from 'chai';
+import {
+  canMeasurePerformance,
+  recordPerformanceMeasure,
+  resetPerformanceMeasureCounts
+} from '../js/util/performanceInstrumentation.js';
+
+describe('performanceInstrumentation', function () {
+  afterEach(function () {
+    resetPerformanceMeasureCounts();
+  });
+
+  it('detects measure support from an injected performance object', function () {
+    expect(canMeasurePerformance({ now() {}, measure() {} })).to.equal(true);
+    expect(canMeasurePerformance({ now() {} })).to.equal(false);
+  });
+
+  it('clears retained measures on a bounded cadence', function () {
+    const calls = [];
+    const perf = {
+      measure(name, options) { calls.push(['measure', name, options.start]); },
+      clearMeasures(name) { calls.push(['clear', name]); }
+    };
+
+    expect(recordPerformanceMeasure('hot-path', { start: 1 }, {
+      performanceRef: perf,
+      retention: 2
+    })).to.equal(true);
+    expect(recordPerformanceMeasure('hot-path', { start: 2 }, {
+      performanceRef: perf,
+      retention: 2
+    })).to.equal(true);
+    expect(recordPerformanceMeasure('hot-path', { start: 3 }, {
+      performanceRef: perf,
+      retention: 2
+    })).to.equal(true);
+
+    expect(calls).to.deep.equal([
+      ['measure', 'hot-path', 1],
+      ['measure', 'hot-path', 2],
+      ['clear', 'hot-path'],
+      ['measure', 'hot-path', 3]
+    ]);
+  });
+});
diff --git a/test/playwright-config.test.js b/test/playwright-config.test.js
new file mode 100644
index 00000000..57532fd9
--- /dev/null
+++ b/test/playwright-config.test.js
@@ -0,0 +1,27 @@
+import { expect } from 'chai';
+import {
+  DEFAULT_PLAYWRIGHT_BASE_URL,
+  resolvePlaywrightBaseUrl,
+  resolvePlaywrightWebServerPort
+} from '../playwright.config.js';
+
+describe('playwright.config', function () {
+  it('defaults to the localhost origin when no override is provided', function () {
+    expect(resolvePlaywrightBaseUrl('')).to.equal(DEFAULT_PLAYWRIGHT_BASE_URL);
+  });
+
+  it('normalizes env overrides to an origin-only base URL', function () {
+    expect(resolvePlaywrightBaseUrl(' https://10.0.0.126:8080/editor.html?e2e=1 ')).to.equal('https://10.0.0.126:8080');
+  });
+
+  it('derives the web server port from the configured base URL', function () {
+    expect(resolvePlaywrightWebServerPort('https://10.0.0.126:8080')).to.equal(8080);
+    expect(resolvePlaywrightWebServerPort('https://localhost')).to.equal(443);
+    expect(resolvePlaywrightWebServerPort('http://127.0.0.1')).to.equal(80);
+  });
+
+  it('rejects invalid base URLs', function () {
+    expect(() => resolvePlaywrightBaseUrl('not-a-url')).to.throw('Invalid LEMMINGS_E2E_BASE_URL');
+    expect(() => resolvePlaywrightBaseUrl('file:///tmp/app')).to.throw('must use http or https');
+  });
+});
diff --git a/test/processHtmlFile.test.js b/test/processHtmlFile.test.js
index 329dbc14..d6f5a825 100644
--- a/test/processHtmlFile.test.js
+++ b/test/processHtmlFile.test.js
@@ -3,6 +3,7 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import { pathToFileURL } from 'url';
+import { load } from 'cheerio';
 import { processHtmlFile } from '../scripts/processHtmlFile.js';
 
 const withTempDir = (fn) => {
@@ -43,6 +44,40 @@ describe('processHtmlFile options', function () {
     });
   });
 
+  it('ignores explicit URI schemes when rewriting', function () {
+    withTempDir((dir) => {
+      const html = `<!DOCTYPE html><html><head>
+        <script src="data:text/javascript,console.log('x')"></script>
+        <script src="blob:https://example.com/asset-id"></script>
+      </head><body></body></html>`;
+      const file = path.join(dir, 'index.html');
+      fs.writeFileSync(file, html);
+
+      const result = processHtmlFile(file, { rewritePaths: true });
+      assert.ok(result.html.includes('data:text/javascript,console.log'));
+      assert.ok(result.html.includes('blob:https://example.com/asset-id'));
+    });
+  });
+
+  it('ignores filesystem-absolute asset links when rewriting', function () {
+    withTempDir((dir) => {
+      const absScript = path.join(dir, 'abs.js');
+      const absStyle = path.join(dir, 'abs.css');
+      fs.writeFileSync(absScript, 'console.log("abs");');
+      fs.writeFileSync(absStyle, 'body{color:blue;}');
+      const html = `<!DOCTYPE html><html><head>
+        <link rel="stylesheet" href="${absStyle}">
+        <script src="${absScript}"></script>
+      </head><body></body></html>`;
+      const file = path.join(dir, 'index.html');
+      fs.writeFileSync(file, html);
+
+      const result = processHtmlFile(file, { rewritePaths: true });
+      assert.ok(result.html.includes(absStyle));
+      assert.ok(result.html.includes(absScript));
+    });
+  });
+
   it('rewrites relative asset links to file URLs', function () {
     withTempDir((dir) => {
       const jsPath = path.join(dir, 'app.js');
@@ -62,6 +97,19 @@ describe('processHtmlFile options', function () {
     });
   });
 
+  it('preserves query and hash suffixes when rewriting relative asset links', function () {
+    withTempDir((dir) => {
+      const jsPath = path.join(dir, 'app.js');
+      fs.writeFileSync(jsPath, 'console.log("hi");');
+      const html = '<!DOCTYPE html><html><head><script src="app.js?v=1#top"></script></head><body></body></html>';
+      const file = path.join(dir, 'index.html');
+      fs.writeFileSync(file, html);
+
+      const result = processHtmlFile(file, { rewritePaths: true });
+      assert.ok(result.html.includes(`${pathToFileURL(jsPath).href}?v=1#top`));
+    });
+  });
+
   it('inlines scripts and styles when requested', function () {
     withTempDir((dir) => {
       const jsPath = path.join(dir, 'app.js');
@@ -82,6 +130,23 @@ describe('processHtmlFile options', function () {
       assert.ok(!/src="app.js"/.test(result.html));
     });
   });
+
+  it('inlines CSS text without allowing literal closing style tags to break HTML', function () {
+    withTempDir((dir) => {
+      const cssPath = path.join(dir, 'style.css');
+      fs.writeFileSync(cssPath, 'body::before{content:"</style><script>x</script>";}');
+      const html = '<!DOCTYPE html><html><head><link rel="stylesheet" href="style.css"></head><body></body></html>';
+      const file = path.join(dir, 'index.html');
+      fs.writeFileSync(file, html);
+
+      const result = processHtmlFile(file, { inline: true });
+      const $ = load(result.html);
+      assert.ok(result.html.includes('<style>'));
+      assert.ok(!result.html.includes('</style><script>x</script>'));
+      assert.strictEqual($('script').length, 0);
+    });
+  });
+
   it('extracts inline event handlers', function () {
     withTempDir((dir) => {
       const html = '<!DOCTYPE html><html><body><button onclick="doThing()">go</button></body></html>';
@@ -97,4 +162,47 @@ describe('processHtmlFile options', function () {
       assert.ok(typeof handler.loc.end === 'number');
     });
   });
+
+  it('collects relative entry scripts when requested', function () {
+    withTempDir((dir) => {
+      const file = path.join(dir, 'index.html');
+      fs.writeFileSync(
+        file,
+        '<html><body><script src="./app.js?x=1"></script><script src="https://example.com/ext.js"></script></body></html>'
+      );
+      fs.writeFileSync(path.join(dir, 'app.js'), 'console.log("ok");');
+
+      const result = processHtmlFile(file, { includeExternalScripts: true });
+      assert.ok(Array.isArray(result.entryScripts));
+      assert.strictEqual(result.entryScripts.length, 1);
+      assert.strictEqual(result.entryScripts[0], path.resolve(dir, 'app.js'));
+    });
+  });
+
+  it('deduplicates entry scripts across query and hash variants', function () {
+    withTempDir((dir) => {
+      const file = path.join(dir, 'index.html');
+      fs.writeFileSync(
+        file,
+        '<html><body><script src="./app.js?v=1"></script><script src="app.js#frag"></script></body></html>'
+      );
+      fs.writeFileSync(path.join(dir, 'app.js'), 'console.log("ok");');
+
+      const result = processHtmlFile(file, { includeExternalScripts: true });
+      assert.deepStrictEqual(result.entryScripts, [path.resolve(dir, 'app.js')]);
+    });
+  });
+
+  it('returns rewritten html and entry scripts together when inlining with external script discovery', function () {
+    withTempDir((dir) => {
+      const file = path.join(dir, 'index.html');
+      fs.writeFileSync(path.join(dir, 'app.js'), 'console.log("inline-me");');
+      fs.writeFileSync(file, '<html><body><script src="./app.js?cache=1"></script></body></html>');
+
+      const result = processHtmlFile(file, { inline: true, includeExternalScripts: true });
+      assert.ok(typeof result.html === 'string');
+      assert.ok(result.html.includes('console.log("inline-me");'));
+      assert.deepStrictEqual(result.entryScripts, [path.resolve(dir, 'app.js')]);
+    });
+  });
 });
diff --git a/test/processhtmlfile.test.js b/test/processhtmlfile.test.js
deleted file mode 100644
index 329dbc14..00000000
--- a/test/processhtmlfile.test.js
+++ /dev/null
@@ -1,100 +0,0 @@
-import assert from 'assert';
-import fs from 'fs';
-import os from 'os';
-import path from 'path';
-import { pathToFileURL } from 'url';
-import { processHtmlFile } from '../scripts/processHtmlFile.js';
-
-const withTempDir = (fn) => {
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'html-'));
-  try {
-    return fn(dir);
-  } finally {
-    fs.rmSync(dir, { recursive: true, force: true });
-  }
-};
-
-describe('processHtmlFile options', function () {
-  it('extracts empty inline scripts', function () {
-    withTempDir((dir) => {
-      const html = '<!DOCTYPE html><html><head><script></script></head></html>';
-      const file = path.join(dir, 'index.html');
-      fs.writeFileSync(file, html);
-
-      const snippets = processHtmlFile(file);
-      assert.strictEqual(snippets.length, 1);
-      assert.strictEqual(snippets[0].type, 'script');
-      assert.strictEqual(snippets[0].code, '');
-    });
-  });
-
-  it('ignores absolute asset links when rewriting', function () {
-    withTempDir((dir) => {
-      const html = `<!DOCTYPE html><html><head>
-        <link rel="stylesheet" href="https://example.com/style.css">
-        <script src="https://example.com/app.js"></script>
-      </head><body></body></html>`;
-      const file = path.join(dir, 'index.html');
-      fs.writeFileSync(file, html);
-
-      const result = processHtmlFile(file, { rewritePaths: true });
-      assert.ok(result.html.includes('https://example.com/style.css'));
-      assert.ok(result.html.includes('https://example.com/app.js'));
-    });
-  });
-
-  it('rewrites relative asset links to file URLs', function () {
-    withTempDir((dir) => {
-      const jsPath = path.join(dir, 'app.js');
-      const cssPath = path.join(dir, 'style.css');
-      fs.writeFileSync(jsPath, 'console.log("hi");');
-      fs.writeFileSync(cssPath, 'body{color:red;}');
-      const html = `<!DOCTYPE html><html><head>
-        <link rel="stylesheet" href="style.css">
-        <script src="app.js"></script>
-      </head><body></body></html>`;
-      const file = path.join(dir, 'index.html');
-      fs.writeFileSync(file, html);
-
-      const result = processHtmlFile(file, { rewritePaths: true });
-      assert.ok(result.html.includes(pathToFileURL(cssPath).href));
-      assert.ok(result.html.includes(pathToFileURL(jsPath).href));
-    });
-  });
-
-  it('inlines scripts and styles when requested', function () {
-    withTempDir((dir) => {
-      const jsPath = path.join(dir, 'app.js');
-      const cssPath = path.join(dir, 'style.css');
-      fs.writeFileSync(jsPath, 'console.log("hi");');
-      fs.writeFileSync(cssPath, 'body{color:red;}');
-      const html = `<!DOCTYPE html><html><head>
-        <link rel="stylesheet" href="style.css">
-        <script src="app.js"></script>
-      </head><body></body></html>`;
-      const file = path.join(dir, 'index.html');
-      fs.writeFileSync(file, html);
-
-      const result = processHtmlFile(file, { inline: true });
-      assert.ok(/<style>body\{color:red;\}<\/style>/.test(result.html));
-      assert.ok(/<script>console.log\("hi"\);<\/script>/.test(result.html));
-      assert.ok(!/href="style.css"/.test(result.html));
-      assert.ok(!/src="app.js"/.test(result.html));
-    });
-  });
-  it('extracts inline event handlers', function () {
-    withTempDir((dir) => {
-      const html = '<!DOCTYPE html><html><body><button onclick="doThing()">go</button></body></html>';
-      const file = path.join(dir, 'index.html');
-      fs.writeFileSync(file, html);
-
-      const snippets = processHtmlFile(file);
-      assert.strictEqual(snippets.length, 1);
-      const handler = snippets[0];
-      assert.strictEqual(handler.type, 'handler');
-      assert.strictEqual(handler.attr, 'onclick');
-      assert.ok(typeof handler.loc.start === 'number');
-      assert.ok(typeof handler.loc.end === 'number');
-    });
-  });
-});
diff --git a/test/procgen-asset-manager.test.js b/test/procgen-asset-manager.test.js
new file mode 100644
index 00000000..b04a6e06
--- /dev/null
+++ b/test/procgen-asset-manager.test.js
@@ -0,0 +1,61 @@
+import { expect } from 'chai';
+import { ProcgenAssetManager } from '../js/app/procgenAssetManager.js';
+
+describe('ProcgenAssetManager', function () {
+  it('selects pieces using constraint filtering without building temp arrays', function () {
+    const manager = new ProcgenAssetManager({ random: () => 0 });
+    const pieces = [
+      { id: 'wide', bounds: { width: 12, height: 3 } },
+      { id: 'tall', bounds: { width: 4, height: 8 } },
+      { id: 'small', bounds: { width: 3, height: 3 } }
+    ];
+
+    const selected = manager._pickFromList(pieces, 5, 5, 3);
+
+    expect(selected.id).to.equal('tall');
+  });
+
+  it('falls back to the source list when no constrained candidates match', function () {
+    const manager = new ProcgenAssetManager({ random: () => 0.8 });
+    const pieces = [
+      { id: 'a', bounds: { width: 6, height: 2 } },
+      { id: 'b', bounds: { width: 7, height: 2 } }
+    ];
+
+    const selected = manager._pickFromList(pieces, 3, 9, 3);
+
+    expect(['a', 'b']).to.include(selected.id);
+  });
+
+  it('tags catalog pieces with the selected theme contract', function () {
+    const manager = new ProcgenAssetManager({ styleName: 'crystal' });
+    manager._buildTerrainCatalog({
+      styleName: 'crystal',
+      groundSet: 4,
+      terrainImages: [
+        {
+          width: 2,
+          height: 2,
+          frames: [new Uint8Array([
+            1, 1,
+            1, 0x80
+          ])]
+        }
+      ]
+    });
+    manager.groundSet = 4;
+
+    expect(manager.terrainPieces).to.have.length(1);
+    expect(manager.terrainPieces[0]).to.include({
+      id: 0,
+      styleName: 'crystal',
+      theme: 'crystal',
+      groundSet: 4
+    });
+    expect(manager.getThemeSummary()).to.include({
+      selectedTheme: 'crystal',
+      groundSet: 4,
+      terrainPieceCount: 1
+    });
+  });
+});
diff --git a/test/procgen-boot.test.js b/test/procgen-boot.test.js
new file mode 100644
index 00000000..01d4b19c
--- /dev/null
+++ b/test/procgen-boot.test.js
@@ -0,0 +1,296 @@
+import { expect } from 'chai';
+import { normalizeSeed } from '../js/core/seededRandom.js';
+import {
+  registerStyle,
+  registerClassicStyles,
+  resetStyleRegistry
+} from '../js/editor/StyleRegistry.js';
+
+describe('procgenBoot helpers', function () {
+  let procgenBoot;
+  let previousWindow;
+  let previousDocument;
+  let previousAutoBootFlag;
+
+  before(async function () {
+    previousWindow = globalThis.window;
+    previousDocument = globalThis.document;
+    previousAutoBootFlag = globalThis.__LEMMINGS_PROCGEN_NO_AUTO_BOOT__;
+    globalThis.__LEMMINGS_PROCGEN_NO_AUTO_BOOT__ = true;
+    globalThis.window = {};
+    globalThis.document = {};
+    procgenBoot = await import(`../js/app/procgenBoot.js?procgen_boot_test=${Date.now()}`);
+  });
+
+  after(function () {
+    if (previousAutoBootFlag === undefined) {
+      delete globalThis.__LEMMINGS_PROCGEN_NO_AUTO_BOOT__;
+    } else {
+      globalThis.__LEMMINGS_PROCGEN_NO_AUTO_BOOT__ = previousAutoBootFlag;
+    }
+    globalThis.window = previousWindow;
+    globalThis.document = previousDocument;
+    resetStyleRegistry();
+    registerClassicStyles();
+  });
+
+  afterEach(function () {
+    procgenBoot.disposeProcgenRuntime();
+    resetStyleRegistry();
+    registerClassicStyles();
+  });
+
+  it('resolves procgen seed with query -> storage -> timestamp precedence', function () {
+    globalThis.window = {
+      localStorage: {
+        getItem() {
+          return 'from-storage';
+        }
+      }
+    };
+
+    expect(procgenBoot.resolveProcgenSeed(new URLSearchParams('seed=42')))
+      .to.equal(normalizeSeed('42'));
+    expect(procgenBoot.resolveProcgenSeed(new URLSearchParams('')))
+      .to.equal(normalizeSeed('from-storage'));
+
+    const originalNow = Date.now;
+    Date.now = () => 123456789;
+    globalThis.window.localStorage.getItem = () => {
+      throw new Error('storage blocked');
+    };
+    try {
+      expect(procgenBoot.resolveProcgenSeed(new URLSearchParams('')))
+        .to.equal(normalizeSeed(123456789));
+    } finally {
+      Date.now = originalNow;
+    }
+  });
+
+  it('selects one deterministic compatible style without reading the previous run', async function () {
+    resetStyleRegistry();
+    registerStyle('alpha', { groundSet: 0 });
+    registerStyle('beta', { groundSet: 1 });
+    const writes = new Map();
+    let readCount = 0;
+    globalThis.window = {
+      localStorage: {
+        getItem() {
+          readCount += 1;
+          return null;
+        },
+        setItem(key, value) {
+          writes.set(key, value);
+        }
+      }
+    };
+
+    const style = await procgenBoot.pickProcgenStyle(null, { path: 'lemmings' }, () => 0);
+    expect(style).to.equal('alpha');
+    expect(readCount).to.equal(0);
+    expect(writes.get('procgen.style')).to.equal('alpha');
+  });
+
+  it('falls through style candidates when assets are missing', async function () {
+    resetStyleRegistry();
+    registerStyle('alpha', { groundSet: 0 });
+    registerStyle('beta', { groundSet: 1 });
+    const writes = new Map();
+    const calls = [];
+    globalThis.window = {
+      localStorage: {
+        getItem() {
+          return null;
+        },
+        setItem(key, value) {
+          writes.set(key, value);
+        }
+      }
+    };
+
+    const provider = {
+      async loadBinary(_path, filename) {
+        calls.push(filename);
+        if (filename.includes('1')) {
+          return new Uint8Array([1]);
+        }
+        throw new Error('missing asset');
+      }
+    };
+
+    const style = await procgenBoot.pickProcgenStyle(
+      provider,
+      { path: 'lemmings' },
+      () => 0
+    );
+    expect(style).to.equal('beta');
+    expect(calls.some(name => name.includes('VGAGR0'))).to.equal(true);
+    expect(calls.some(name => name.includes('VGAGR1'))).to.equal(true);
+    expect(writes.get('procgen.style')).to.equal('beta');
+  });
+
+  it('builds a selected theme contract for debug state', function () {
+    resetStyleRegistry();
+    registerStyle('alpha', { groundSet: 3 });
+
+    const contract = procgenBoot.buildProcgenThemeContract('alpha', { path: 'lemmings' });
+
+    expect(contract).to.deep.equal({
+      selectedTheme: 'alpha',
+      styleName: 'alpha',
+      groundSet: 3,
+      packPath: 'lemmings'
+    });
+  });
+
+  it('builds deterministic debug controller options from query params', function () {
+    const options = procgenBoot.buildProcgenControllerOptions(
+      new URLSearchParams([
+        ['gapChance', '1'],
+        ['gapMinWidth', '5'],
+        ['gapMaxWidth', '5'],
+        ['recentCertificateLimit', '8'],
+        ['procgenCertificateVerification', 'false']
+      ]),
+      {
+        gapChance: 0.08,
+        gapMinWidth: 3,
+        gapMaxWidth: 9,
+        recentCertificateLimit: 32,
+        procgenCertificateVerification: true
+      }
+    );
+
+    expect(options).to.include({
+      gapChance: 1,
+      gapMinWidth: 5,
+      gapMaxWidth: 5,
+      recentCertificateLimit: 8,
+      procgenCertificateVerification: false
+    });
+
+    const fallback = procgenBoot.buildProcgenControllerOptions(
+      new URLSearchParams('gapChance=not-a-number&procgenCertificateVerification=maybe'),
+      {
+        gapChance: 0.25,
+        procgenCertificateVerification: true
+      }
+    );
+
+    expect(fallback).to.include({
+      gapChance: 0.25,
+      procgenCertificateVerification: true
+    });
+  });
+
+  it('disposes active procgen runtime once and clears references', function () {
+    const calls = [];
+    procgenBoot.setActiveProcgenRuntimeForTest({
+      focusBlurCleanup() { calls.push('focusBlur'); },
+      controller: { stop() { calls.push('controller'); } },
+      stageAdapter: { dispose() { calls.push('stageAdapter'); } },
+      game: { stop() { calls.push('game'); } },
+      view: { dispose() { calls.push('view'); } }
+    });
+
+    procgenBoot.disposeProcgenRuntime();
+    procgenBoot.disposeProcgenRuntime();
+
+    expect(calls).to.deep.equal(['focusBlur', 'controller', 'stageAdapter', 'game', 'view']);
+  });
+
+  it('installs and disposes procgen boot listeners', function () {
+    const windowListeners = new Map();
+    const documentListeners = new Map();
+    globalThis.window = {
+      addEventListener(type, handler) {
+        windowListeners.set(type, handler);
+      },
+      removeEventListener(type, handler) {
+        if (windowListeners.get(type) === handler) windowListeners.delete(type);
+      }
+    };
+    globalThis.document = {
+      readyState: 'loading',
+      addEventListener(type, handler) {
+        documentListeners.set(type, handler);
+      },
+      removeEventListener(type, handler) {
+        if (documentListeners.get(type) === handler) documentListeners.delete(type);
+      }
+    };
+
+    procgenBoot.installProcgenBootListeners();
+    expect(windowListeners.has('resize')).to.equal(true);
+    expect(windowListeners.has('beforeunload')).to.equal(true);
+    expect(documentListeners.has('DOMContentLoaded')).to.equal(true);
+
+    procgenBoot.disposeProcgenBootListeners();
+    expect(windowListeners.size).to.equal(0);
+    expect(documentListeners.size).to.equal(0);
+  });
+
+  it('resizes canvas and updates stage using explicit runtime handles', function () {
+    const canvas = {
+      width: 0,
+      height: 0,
+      style: {}
+    };
+    let adapterResizeCalls = 0;
+    globalThis.window = {
+      devicePixelRatio: 1.5,
+      innerWidth: 640,
+      innerHeight: 360
+    };
+    globalThis.document = {
+      getElementById(id) {
+        if (id === 'gameCanvas') return canvas;
+        return null;
+      }
+    };
+
+    procgenBoot.setActiveProcgenRuntimeForTest({
+      stageAdapter: {
+        updateStageSize() {
+          adapterResizeCalls += 1;
+        }
+      }
+    });
+
+    procgenBoot.resizeCanvas();
+
+    expect(canvas.width).to.equal(960);
+    expect(canvas.height).to.equal(540);
+    expect(canvas.style.width).to.equal('640px');
+    expect(canvas.style.height).to.equal('360px');
+    expect(adapterResizeCalls).to.equal(1);
+  });
+
+  it('falls back to finite canvas dimensions when viewport metrics are invalid', function () {
+    const canvas = {
+      width: 0,
+      height: 0,
+      clientWidth: 320,
+      clientHeight: 200,
+      style: {}
+    };
+    globalThis.window = {
+      devicePixelRatio: Number.NaN,
+      innerWidth: undefined,
+      innerHeight: Number.NaN
+    };
+    globalThis.document = {
+      getElementById(id) {
+        if (id === 'gameCanvas') return canvas;
+        return null;
+      }
+    };
+
+    procgenBoot.resizeCanvas();
+
+    expect(canvas.width).to.equal(320);
+    expect(canvas.height).to.equal(200);
+    expect(canvas.style.width).to.equal('320px');
+    expect(canvas.style.height).to.equal('200px');
+  });
+});
diff --git a/test/procgen-controller.test.js b/test/procgen-controller.test.js
new file mode 100644
index 00000000..37ce215d
--- /dev/null
+++ b/test/procgen-controller.test.js
@@ -0,0 +1,754 @@
+import { expect } from 'chai';
+import { ProcgenController } from '../js/app/procgenController.js';
+import { SkillTypes } from '../js/game/SkillTypes.js';
+import { TriggerTypes } from '../js/level/TriggerTypes.js';
+import {
+  SOLVER_EXPLANATION_CODES,
+  SOLVER_RESULT_TYPES,
+  createSolverResult
+} from '../js/solver/SolverTypes.js';
+import {
+  PROCGEN_CHALLENGE_TYPES,
+  PROCGEN_FALLBACK_DECISIONS
+} from '../js/solver/ProcgenCertificates.js';
+
+const walkAction = { getActionName: () => 'walk' };
+const actionNamed = name => ({ getActionName: () => name });
+
+const makeLemming = (id, x, {
+  y = 60,
+  lookRight = true,
+  actionName = 'walk',
+  removed = false,
+  disabled = false,
+  state = 0,
+  hasParachute = false
+} = {}) => ({
+  id,
+  x,
+  y,
+  lookRight,
+  removed,
+  disabled,
+  state,
+  hasParachute,
+  action: actionNamed(actionName)
+});
+
+const createFrontierFixture = (lemmings, options = {}) => {
+  let tick = 0;
+  const manager = {
+    lemmings,
+    activeLemmings: lemmings,
+    selectedIndex: -1,
+    getLemming(id) {
+      return this.lemmings.find(lem => lem?.id === id) || null;
+    }
+  };
+  const controller = new ProcgenController({
+    game: {
+      getLemmingManager: () => manager,
+      getGameTimer: () => ({ tickIndex: tick })
+    },
+    level: {
+      width: 1000,
+      height: 160,
+      entrances: [{ x: 64, y: 80 }]
+    },
+    options
+  });
+  return {
+    controller,
+    manager,
+    advance(delta = 1) {
+      tick += delta;
+      return tick;
+    }
+  };
+};
+
+describe('ProcgenController', function () {
+  it('finds nearest hazard trigger in both scan directions', function () {
+    const level = {
+      triggers: [
+        { type: TriggerTypes.TRAP, x1: 22, x2: 26, y1: 0, y2: 12 },
+        { type: TriggerTypes.FRYING, x1: 15, x2: 16, y1: 0, y2: 12 },
+        { type: TriggerTypes.DROWN, x1: 7, x2: 9, y1: 0, y2: 12 },
+        { type: TriggerTypes.EXIT_LEVEL, x1: 13, x2: 14, y1: 0, y2: 12 }
+      ]
+    };
+    const controller = new ProcgenController({ level });
+    controller._rebuildHazardIndex();
+
+    const right = controller._findHazardAhead(12, 6, 20, 1);
+    expect(right).to.deep.equal({ dx: 3, type: TriggerTypes.FRYING });
+
+    const left = controller._findHazardAhead(12, 6, 20, -1);
+    expect(left).to.deep.equal({ dx: 4, type: TriggerTypes.DROWN });
+  });
+
+  it('prunes stale tracking state and offscreen gap backlog', function () {
+    const manager = {
+      lemmings: [{ id: 1, removed: false, disabled: false }]
+    };
+    const controller = new ProcgenController({
+      game: { getLemmingManager: () => manager },
+      level: {}
+    });
+    controller.fallEventMemoryTicks = 40;
+    controller._cameraX = 300;
+    controller._seenFalls.set(1, 145);
+    controller._seenFalls.set(2, 10);
+    controller._aiLemmingCooldown.set(1, 170);
+    controller._aiLemmingCooldown.set(2, 20);
+    controller._aiStallState.set(2, { stallTicks: 99 });
+    controller._gaps = [
+      { x: 20, width: 6, assigned: false },
+      { x: 180, width: 8, assigned: true }
+    ];
+
+    controller._pruneTrackingState(150);
+
+    expect(controller._seenFalls.has(1)).to.equal(true);
+    expect(controller._seenFalls.has(2)).to.equal(false);
+    expect(controller._aiLemmingCooldown.has(1)).to.equal(true);
+    expect(controller._aiLemmingCooldown.has(2)).to.equal(false);
+    expect(controller._aiStallState.has(2)).to.equal(false);
+    expect(controller._gaps).to.have.length(1);
+    expect(controller._gaps[0].x).to.equal(180);
+  });
+
+  it('cleans up obsolete gaps even when no lemmings are present', function () {
+    const manager = { lemmings: [] };
+    const controller = new ProcgenController({
+      game: { getLemmingManager: () => manager },
+      level: {}
+    });
+    controller._cameraX = 260;
+    controller._gaps = [
+      { x: 8, width: 4, assigned: false },
+      { x: 120, width: 12, assigned: false }
+    ];
+
+    controller._processGapBridges();
+
+    expect(controller._gaps).to.have.length(1);
+    expect(controller._gaps[0].x).to.equal(120);
+  });
+
+  it('uses injected rng streams for deterministic procgen decisions', function () {
+    const sequence = [0.1, 0.9, 0.2, 0.75, 0.33];
+    let index = 0;
+    const controller = new ProcgenController({
+      level: { width: 200, height: 80 },
+      options: {
+        rng: () => sequence[(index++) % sequence.length]
+      }
+    });
+    index = 0;
+
+    expect(controller._randInt(1, 10)).to.equal(2);
+    const plan = controller._seedStructurePlan();
+    expect(plan.type).to.equal('staircase');
+    expect(plan.remaining).to.equal(5);
+    expect(plan.step).to.equal(3);
+    expect(plan.direction).to.equal(-1);
+  });
+
+  it('advances and compacts gap scan cursor for large backlogs', function () {
+    const controller = new ProcgenController({ level: {} });
+    controller._gaps = Array.from({ length: 600 }, (_, i) => ({
+      x: i * 5,
+      width: 3,
+      assigned: false
+    }));
+
+    controller._pruneGapQueue(2200);
+
+    expect(controller._gapScanStart).to.equal(0);
+    expect(controller._gaps.length).to.be.lessThan(600);
+    expect(controller._gaps[0].x).to.be.at.least(2000);
+  });
+
+  it('reuses scan-cache results inside a single AI decision window', function () {
+    let gapDepthCalls = 0;
+    let wallHeightCalls = 0;
+    const ground = {
+      getColumnGapDepth() {
+        gapDepthCalls += 1;
+        return 1;
+      },
+      getColumnWallHeight() {
+        wallHeightCalls += 1;
+        return 0;
+      }
+    };
+    const controller = new ProcgenController({
+      level: {
+        height: 80,
+        groundMask: ground,
+        triggers: []
+      }
+    });
+    const lemming = { x: 40, y: 50, lookRight: true };
+
+    controller._beginScanCacheWindow(100);
+    controller._scanAhead(lemming);
+    const firstGapCalls = gapDepthCalls;
+    const firstWallCalls = wallHeightCalls;
+
+    controller._scanAhead(lemming);
+    expect(gapDepthCalls).to.equal(firstGapCalls);
+    expect(wallHeightCalls).to.equal(firstWallCalls);
+
+    controller._beginScanCacheWindow(101);
+    controller._scanAhead(lemming);
+    expect(gapDepthCalls).to.be.greaterThan(firstGapCalls);
+    expect(wallHeightCalls).to.be.greaterThan(firstWallCalls);
+  });
+
+  it('streams selected-theme pieces ahead of the live frontier', function () {
+    const lemming = makeLemming(5, 60);
+    const piece = {
+      id: 'route-cap',
+      styleName: 'crystal',
+      width: 10,
+      height: 4,
+      bounds: {
+        minX: 0,
+        minY: 0,
+        maxX: 9,
+        maxY: 3,
+        width: 10,
+        height: 4
+      }
+    };
+    const stamps = [];
+    const controller = new ProcgenController({
+      game: {
+        getLemmingManager: () => ({
+          lemmings: [lemming],
+          activeLemmings: [lemming]
+        }),
+        getGameTimer: () => ({ tickIndex: 10 })
+      },
+      level: {
+        width: 400,
+        height: 120,
+        entrances: [{ x: 64, y: 80 }]
+      },
+      assets: {
+        styleName: 'crystal',
+        pickGroundPiece() {
+          return piece;
+        },
+        pickDecorPiece() {
+          return null;
+        }
+      },
+      stamper: {
+        stamp(stampedPiece, x, y) {
+          stamps.push({ stampedPiece, x, y });
+          return {
+            x: x + stampedPiece.bounds.minX,
+            y: y + stampedPiece.bounds.minY,
+            width: stampedPiece.bounds.width,
+            height: stampedPiece.bounds.height
+          };
+        }
+      },
+      options: {
+        selectedTheme: 'crystal',
+        rng: () => 0,
+        groundHeight: 4,
+        segmentMinWidth: 40,
+        segmentMaxWidth: 40,
+        lookAheadMin: 80,
+        lookAheadMax: 80,
+        gapChance: 0,
+        decorChance: 0,
+        recentChunkLimit: 4,
+        recentPieceLimit: 16
+      }
+    });
+    controller._groundEndX = 100;
+    controller._groundTopY = 100;
+    controller._sustainBaseY = 100;
+    controller._sustainRemaining = 100;
+    controller._terrainPlan = { mode: 'flat', remaining: 100 };
+
+    controller._ensureGround(lemming.x);
+    const debug = controller.getDebugState();
+
+    expect(stamps.length).to.be.greaterThan(0);
+    expect(debug.selectedTheme).to.equal('crystal');
+    expect(debug.frontier.id).to.equal(5);
+    expect(debug.generatedEndX - debug.frontier.x).to.be.greaterThan(debug.lookahead.distance);
+    expect(debug.recentPieces).to.have.length.of.at.most(16);
+    expect(debug.recentPieces.every(entry => entry.theme === 'crystal')).to.equal(true);
+    expect(debug.recentChunks.every(entry => entry.theme === 'crystal')).to.equal(true);
+  });
+
+  it('records accepted procgen challenge certificates for generated gaps', function () {
+    const controller = new ProcgenController({
+      level: {
+        width: 120,
+        height: 80,
+        entrances: [{ x: 8, y: 40 }],
+        setGroundRect() {}
+      },
+      options: {
+        rng: () => 0,
+        groundHeight: 4,
+        segmentMinWidth: 12,
+        segmentMaxWidth: 12,
+        lookAheadMin: 24,
+        lookAheadMax: 24,
+        gapChance: 1,
+        gapMinWidth: 5,
+        gapMaxWidth: 5
+      }
+    });
+    controller._groundEndX = 10;
+    controller._groundTopY = 60;
+    controller._sustainBaseY = 60;
+    controller._sustainRemaining = 100;
+    controller._terrainPlan = { mode: 'flat', remaining: 100 };
+
+    controller._ensureGround(0);
+    const debug = controller.getDebugState();
+
+    expect(debug.recentCertificates.some(entry => {
+      return entry.challengeType === 'bridge-gap' && entry.decision === 'accept';
+    })).to.equal(true);
+    expect(debug.recentChunks.some(entry => {
+      return entry.type === 'gap' && entry.certificateDecision === 'accept';
+    })).to.equal(true);
+  });
+
+  it('simplifies generated gaps when certificate verification rejects builder budget', function () {
+    const controller = new ProcgenController({
+      level: {
+        width: 160,
+        height: 80,
+        entrances: [{ x: 8, y: 40 }],
+        setGroundRect() {}
+      },
+      options: {
+        rng: () => 0,
+        groundHeight: 4,
+        segmentMinWidth: 12,
+        segmentMaxWidth: 12,
+        lookAheadMin: 24,
+        lookAheadMax: 24,
+        gapChance: 1,
+        gapMinWidth: 20,
+        gapMaxWidth: 20,
+        procgenCertificateVerifier: () => createSolverResult({
+          resultType: SOLVER_RESULT_TYPES.FAILED,
+          summary: 'gap exceeds injected builder budget',
+          explanations: [SOLVER_EXPLANATION_CODES.GAP_EXCEEDS_BUILDER_BUDGET]
+        })
+      }
+    });
+    controller._groundEndX = 10;
+    controller._groundTopY = 60;
+    controller._sustainBaseY = 60;
+    controller._sustainRemaining = 100;
+    controller._terrainPlan = { mode: 'flat', remaining: 100 };
+
+    controller._ensureGround(0);
+    const debug = controller.getDebugState();
+    const simplified = debug.recentChunks.find(entry => entry.certificateDecision === 'simplify');
+
+    expect(controller._gaps[0].width).to.equal(8);
+    expect(simplified).to.include({
+      type: 'gap',
+      certificateDecision: 'simplify',
+      certificateResultType: SOLVER_RESULT_TYPES.FAILED
+    });
+  });
+
+  it('extends terrain instead of placing rejected no-route gaps', function () {
+    const painted = [];
+    const controller = new ProcgenController({
+      level: {
+        width: 160,
+        height: 80,
+        entrances: [{ x: 8, y: 40 }],
+        setGroundRect(x, y, width, height) {
+          painted.push({ x, y, width, height });
+        }
+      },
+      options: {
+        rng: () => 0,
+        groundHeight: 4,
+        segmentMinWidth: 12,
+        segmentMaxWidth: 12,
+        lookAheadMin: 24,
+        lookAheadMax: 24,
+        gapChance: 1,
+        gapMinWidth: 6,
+        gapMaxWidth: 6,
+        procgenCertificateVerifier: () => createSolverResult({
+          resultType: SOLVER_RESULT_TYPES.FAILED,
+          summary: 'missing route after injected verification',
+          explanations: [SOLVER_EXPLANATION_CODES.NO_ROUTE_TO_EXIT]
+        })
+      }
+    });
+    controller._groundEndX = 10;
+    controller._groundTopY = 60;
+    controller._sustainBaseY = 60;
+    controller._sustainRemaining = 100;
+    controller._terrainPlan = { mode: 'flat', remaining: 100 };
+
+    controller._ensureGround(0);
+    const debug = controller.getDebugState();
+    const fallback = debug.recentChunks.find(entry => entry.type === 'solver-fallback');
+
+    expect(painted.length).to.be.greaterThan(0);
+    expect(controller._gaps).to.have.length(0);
+    expect(fallback).to.include({
+      originalType: 'gap',
+      certificateDecision: 'extend',
+      certificateResultType: SOLVER_RESULT_TYPES.FAILED
+    });
+  });
+
+  it('tracks the rightmost viable frontier instead of the first lemming id', function () {
+    const manager = {
+      lemmings: [
+        { id: 0, x: 100, y: 60, lookRight: false, action: walkAction },
+        { id: 1, x: 95, y: 60, lookRight: true, action: walkAction },
+        { id: 2, x: 40, y: 60, lookRight: true, removed: true, action: walkAction }
+      ]
+    };
+    const controller = new ProcgenController({
+      game: {
+        getLemmingManager: () => manager,
+        getGameTimer: () => ({ tickIndex: 12 })
+      },
+      level: { width: 200, height: 120 },
+      assets: { styleName: 'dirt' },
+      options: { rngSeed: 123 }
+    });
+
+    const debug = controller.getDebugState();
+
+    expect(debug.selectedTheme).to.equal('dirt');
+    expect(debug.seed).to.equal(123);
+    expect(debug.frontier.id).to.equal(1);
+    expect(debug.frontier.x).to.equal(95);
+    expect(debug.frontier.viableCount).to.equal(2);
+  });
+
+  it('ignores selected lemming changes and falls back when the lead is removed', function () {
+    const lems = [
+      makeLemming(0, 120),
+      makeLemming(1, 190),
+      makeLemming(2, 250, { actionName: 'splatter' })
+    ];
+    const { controller, manager, advance } = createFrontierFixture(lems);
+
+    manager.selectedIndex = 0;
+    expect(controller._getFrontierLemming().id).to.equal(1);
+
+    manager.selectedIndex = 1;
+    advance();
+    expect(controller._getFrontierLemming().id).to.equal(1);
+
+    lems[1].removed = true;
+    advance();
+    expect(controller._getFrontierLemming().id).to.equal(0);
+    expect(controller._getFrontierSummary().reason).to.equal('walk');
+  });
+
+  it('drops stuck turnaround leads but keeps moving turnaround leads viable', function () {
+    const lead = makeLemming(7, 260, { lookRight: false });
+    const follower = makeLemming(3, 240);
+    const { controller, advance } = createFrontierFixture([lead, follower], {
+      frontierStuckTicks: 2,
+      frontierTurnaroundPenalty: 12
+    });
+
+    expect(controller._getFrontierState({ force: true }).id).to.equal(7);
+
+    advance();
+    follower.x += 1;
+    controller._getFrontierState({ force: true });
+    advance();
+    follower.x += 1;
+    const afterStall = controller._getFrontierState({ force: true });
+
+    expect(afterStall.id).to.equal(3);
+    expect(afterStall.reason).to.equal('walk');
+  });
+
+  it('keeps recoverable falling leads viable and skips lethal falls', function () {
+    const fallingLead = makeLemming(8, 280, {
+      actionName: 'falling',
+      state: 12
+    });
+    const follower = makeLemming(2, 230);
+    const { controller, advance } = createFrontierFixture([fallingLead, follower]);
+
+    expect(controller._getFrontierState({ force: true }).id).to.equal(8);
+
+    fallingLead.state = 100;
+    advance();
+    expect(controller._getFrontierState({ force: true }).id).to.equal(2);
+
+    fallingLead.hasParachute = true;
+    advance();
+    expect(controller._getFrontierState({ force: true }).id).to.equal(8);
+  });
+
+  it('bounds frontier, assist, fall, and gap tracking growth', function () {
+    const { controller } = createFrontierFixture([
+      makeLemming(1, 100),
+      makeLemming(2, 120)
+    ], {
+      frontierMaxTrackedLemmings: 3,
+      gapTrackingLimit: 3
+    });
+    for (let id = 1; id <= 12; id += 1) {
+      controller._frontierLemmingState.set(id, { lastSeenTick: id });
+      controller._aiLemmingCooldown.set(id, id);
+      controller._aiStallState.set(id, { lastSeenTick: id });
+      controller._seenFalls.set(id, id);
+    }
+    controller._gaps = Array.from({ length: 10 }, (_, index) => ({
+      x: index * 20,
+      width: 4,
+      assigned: false
+    }));
+
+    controller._pruneTrackingState(500);
+
+    expect(controller._frontierLemmingState.size).to.be.at.most(3);
+    expect(controller._aiLemmingCooldown.size).to.be.at.most(3);
+    expect(controller._aiStallState.size).to.be.at.most(3);
+    expect(controller._seenFalls.size).to.be.at.most(3);
+    expect(controller._gaps.length).to.be.at.most(3);
+    expect(controller._frontierLemmingState.has(1)).to.equal(true);
+    expect(controller._frontierLemmingState.has(2)).to.equal(true);
+  });
+
+  it('records no-op decisions for traversable terrain', function () {
+    const calls = [];
+    const controller = new ProcgenController({
+      game: {
+        getLemmingManager: () => ({
+          doLemmingAction(_lem, skill) {
+            calls.push(skill);
+            return true;
+          }
+        }),
+        getGameTimer: () => ({ tickIndex: 20 })
+      },
+      level: { width: 200, height: 120 }
+    });
+    controller._initAiDirector();
+    const lemming = { id: 1, x: 30, y: 60, lookRight: true, action: walkAction };
+
+    const result = controller._decideAssist(lemming, {
+      direction: 1,
+      gap: null,
+      wall: null,
+      hazard: null
+    }, 20);
+
+    expect(result).to.equal(null);
+    expect(calls).to.deep.equal([]);
+    expect(controller.getDebugState().recentAssists.at(-1)).to.include({
+      type: 'noop',
+      reason: 'traversable',
+      spent: false
+    });
+  });
+
+  it('records safe drops without spending a skill', function () {
+    const calls = [];
+    const controller = new ProcgenController({
+      game: {
+        getLemmingManager: () => ({
+          doLemmingAction(_lem, skill) {
+            calls.push(skill);
+            return true;
+          }
+        }),
+        getGameTimer: () => ({ tickIndex: 30 })
+      },
+      level: { width: 200, height: 120 }
+    });
+    controller._initAiDirector();
+    const lemming = { id: 1, x: 30, y: 60, lookRight: true, action: walkAction };
+
+    const result = controller._decideAssist(lemming, {
+      direction: 1,
+      gap: { dx: 2, width: 1, drop: 4 },
+      wall: null,
+      hazard: null
+    }, 30);
+
+    expect(result).to.equal(null);
+    expect(calls).to.deep.equal([]);
+    expect(controller.getDebugState().recentAssists.at(-1)).to.include({
+      type: 'noop',
+      reason: 'safe-drop',
+      spent: false
+    });
+  });
+
+  it('uses minimal skills for small gaps and small barriers', function () {
+    const calls = [];
+    const controller = new ProcgenController({
+      game: {
+        getLemmingManager: () => ({
+          doLemmingAction(_lem, skill) {
+            calls.push(skill);
+            return true;
+          }
+        }),
+        getGameTimer: () => ({ tickIndex: 40 })
+      },
+      level: { width: 200, height: 120 }
+    });
+    controller._initAiDirector();
+    const gapLemming = { id: 1, x: 30, y: 60, lookRight: true, action: walkAction };
+    const barrierLemming = { id: 2, x: 50, y: 60, lookRight: true, action: walkAction };
+
+    const gapResult = controller._decideAssist(gapLemming, {
+      direction: 1,
+      gap: { dx: 3, width: 4, drop: 2 },
+      wall: null,
+      hazard: null
+    }, 40);
+    const barrierResult = controller._decideAssist(barrierLemming, {
+      direction: 1,
+      gap: null,
+      wall: { dx: 2, height: controller.maxStepUp + 2 },
+      hazard: null
+    }, 45);
+
+    expect(gapResult).to.equal('builder');
+    expect(barrierResult).to.equal('bash');
+    expect(calls).to.deep.equal([SkillTypes.BUILDER, SkillTypes.BASHER]);
+    const assists = controller.getDebugState().recentAssists;
+    expect(assists.some(assist => assist.reason === 'small-gap' && assist.skillName === 'builder')).to.equal(true);
+    expect(assists.some(assist => assist.reason === 'small-barrier' && assist.skillName === 'basher')).to.equal(true);
+  });
+
+  it('records verified non-gap challenge certificates for assist decisions', function () {
+    const calls = [];
+    const controller = new ProcgenController({
+      game: {
+        getLemmingManager: () => ({
+          doLemmingAction(_lem, skill) {
+            calls.push(skill);
+            return true;
+          }
+        }),
+        getGameTimer: () => ({ tickIndex: 50 })
+      },
+      level: { width: 200, height: 140 },
+      options: {
+        procgenCertificateVerifier(certificate, chunk) {
+          expect(chunk.kind).to.equal('procgen-local-challenge');
+          expect(certificate.challengeType).to.be.oneOf([
+            PROCGEN_CHALLENGE_TYPES.BASH_BARRIER,
+            PROCGEN_CHALLENGE_TYPES.FALL_SURVIVAL
+          ]);
+          return createSolverResult({
+            resultType: SOLVER_RESULT_TYPES.SOLVED,
+            summary: `${certificate.challengeType} verified`
+          });
+        }
+      }
+    });
+    controller._initAiDirector();
+    const barrierLemming = { id: 7, x: 52, y: 60, lookRight: true, action: walkAction };
+    const fallLemming = { id: 8, x: 64, y: 60, lookRight: true, action: walkAction };
+
+    const barrierResult = controller._decideAssist(barrierLemming, {
+      direction: 1,
+      gap: null,
+      wall: { dx: 2, height: controller.maxStepUp + 3 },
+      hazard: null
+    }, 50);
+    const fallResult = controller._decideAssist(fallLemming, {
+      direction: 1,
+      gap: { dx: 4, width: 10, drop: controller.aiFloaterDrop + 4 },
+      wall: null,
+      hazard: null
+    }, 55);
+
+    expect(barrierResult).to.equal('bash');
+    expect(fallResult).to.equal('floater');
+    expect(calls).to.deep.equal([SkillTypes.BASHER, SkillTypes.FLOATER]);
+    const debug = controller.getDebugState();
+    expect(debug.recentCertificates.some(entry => {
+      return entry.source === 'assist' &&
+        entry.challengeType === PROCGEN_CHALLENGE_TYPES.BASH_BARRIER &&
+        entry.decision === PROCGEN_FALLBACK_DECISIONS.ACCEPT;
+    })).to.equal(true);
+    expect(debug.recentCertificates.some(entry => {
+      return entry.source === 'assist' &&
+        entry.challengeType === PROCGEN_CHALLENGE_TYPES.FALL_SURVIVAL &&
+        entry.decision === PROCGEN_FALLBACK_DECISIONS.ACCEPT;
+    })).to.equal(true);
+    expect(debug.recentAssists.some(assist => {
+      return assist.challengeType === PROCGEN_CHALLENGE_TYPES.BASH_BARRIER &&
+        assist.certificateDecision === PROCGEN_FALLBACK_DECISIONS.ACCEPT;
+    })).to.equal(true);
+  });
+
+  it('keeps assist decisions advisory when a non-gap certificate is rejected', function () {
+    const calls = [];
+    const controller = new ProcgenController({
+      game: {
+        getLemmingManager: () => ({
+          doLemmingAction(_lem, skill) {
+            calls.push(skill);
+            return true;
+          }
+        }),
+        getGameTimer: () => ({ tickIndex: 70 })
+      },
+      level: { width: 200, height: 120 },
+      options: {
+        procgenCertificateVerifier: () => createSolverResult({
+          resultType: SOLVER_RESULT_TYPES.UNSUPPORTED,
+          summary: 'unsupported injected assist check',
+          explanations: [SOLVER_EXPLANATION_CODES.UNSUPPORTED_MECHANIC]
+        })
+      }
+    });
+    controller._initAiDirector();
+    const lemming = { id: 9, x: 50, y: 60, lookRight: true, action: walkAction };
+
+    const result = controller._decideAssist(lemming, {
+      direction: 1,
+      gap: null,
+      wall: { dx: 2, height: controller.maxStepUp + 2 },
+      hazard: null
+    }, 70);
+
+    expect(result).to.equal('bash');
+    expect(calls).to.deep.equal([SkillTypes.BASHER]);
+    const debug = controller.getDebugState();
+    const certificate = debug.recentCertificates.at(-1);
+    expect(certificate).to.include({
+      source: 'assist',
+      challengeType: PROCGEN_CHALLENGE_TYPES.BASH_BARRIER,
+      decision: PROCGEN_FALLBACK_DECISIONS.REPLACE,
+      resultType: SOLVER_RESULT_TYPES.UNSUPPORTED
+    });
+    expect(debug.recentAssists.at(-1)).to.include({
+      challengeType: PROCGEN_CHALLENGE_TYPES.BASH_BARRIER,
+      certificateDecision: PROCGEN_FALLBACK_DECISIONS.REPLACE,
+      certificateResultType: SOLVER_RESULT_TYPES.UNSUPPORTED
+    });
+  });
+});
diff --git a/test/procgen-stage-adapter.test.js b/test/procgen-stage-adapter.test.js
new file mode 100644
index 00000000..3ac69c69
--- /dev/null
+++ b/test/procgen-stage-adapter.test.js
@@ -0,0 +1,208 @@
+import { expect } from 'chai';
+import { ProcgenStageAdapter } from '../js/app/procgenStageAdapter.js';
+
+const createWindowMock = () => {
+  const listeners = new Map();
+  return {
+    listeners,
+    addEventListener(type, handler) {
+      listeners.set(type, handler);
+    },
+    removeEventListener(type, handler) {
+      if (listeners.get(type) === handler) {
+        listeners.delete(type);
+      }
+    }
+  };
+};
+
+const createCanvasMock = () => {
+  const listeners = new Map();
+  const added = [];
+  const removed = [];
+  return {
+    listeners,
+    added,
+    removed,
+    addEventListener(type, handler, options) {
+      added.push({ type, handler, options });
+      listeners.set(type, handler);
+    },
+    removeEventListener(type, handler) {
+      removed.push({ type, handler });
+      if (listeners.get(type) === handler) {
+        listeners.delete(type);
+      }
+    }
+  };
+};
+
+const createAdapterFixture = () => {
+  const stageImageViewPoint = { x: 0, y: 0, scale: 1 };
+  const guiViewPoint = {
+    x: 0,
+    y: 0,
+    setX(v) { this.x = v; },
+    setY(v) { this.y = v; }
+  };
+  const originalSnapScale = (rawScale) => rawScale;
+  const stage = {
+    gameImgProps: {
+      viewPoint: stageImageViewPoint,
+      canvasViewportSize: { width: 320, height: 160 },
+      display: { worldDataSize: { width: 320, height: 160 } }
+    },
+    guiImgProps: {
+      display: {},
+      canvasViewportSize: { width: 1, height: 1 },
+      viewPoint: guiViewPoint
+    },
+    snapScale: originalSnapScale,
+    applyViewportCalls: [],
+    redrawCalls: 0,
+    updateStageSizeCalls: 0,
+    applyViewport(props, x, y, scale) {
+      this.applyViewportCalls.push({ props, x, y, scale });
+      props.viewPoint.scale = scale;
+    },
+    redraw() {
+      this.redrawCalls += 1;
+    },
+    updateStageSize() {
+      this.updateStageSizeCalls += 1;
+    }
+  };
+  const view = {
+    stage,
+    game: { level: { width: 320, height: 160 } }
+  };
+  const controller = {
+    level: { width: 320, height: 160 },
+    getGroundExtentX() { return 320; }
+  };
+  return { stage, view, controller, originalSnapScale };
+};
+
+describe('ProcgenStageAdapter', function () {
+  let previousWindow;
+
+  beforeEach(function () {
+    previousWindow = globalThis.window;
+    globalThis.window = createWindowMock();
+  });
+
+  afterEach(function () {
+    globalThis.window = previousWindow;
+  });
+
+  it('binds listeners once and disposes them cleanly', function () {
+    const canvas = createCanvasMock();
+    const { stage, view, controller, originalSnapScale } = createAdapterFixture();
+    const adapter = new ProcgenStageAdapter({ view, controller, canvas });
+
+    adapter.install();
+    adapter.install();
+
+    expect(canvas.added.filter(entry => entry.type === 'wheel')).to.have.lengthOf(1);
+    expect(globalThis.window.listeners.has('resize')).to.equal(true);
+    expect(stage.snapScale).to.not.equal(originalSnapScale);
+
+    adapter.dispose();
+    adapter.dispose();
+
+    expect(canvas.listeners.size).to.equal(0);
+    expect(globalThis.window.listeners.size).to.equal(0);
+    expect(stage.snapScale).to.equal(originalSnapScale);
+  });
+
+  it('rebinds listeners after a dispose/install cycle', function () {
+    const canvas = createCanvasMock();
+    const { view, controller } = createAdapterFixture();
+    const adapter = new ProcgenStageAdapter({ view, controller, canvas });
+
+    adapter.install();
+    adapter.dispose();
+    adapter.install();
+
+    expect(canvas.added.filter(entry => entry.type === 'wheel')).to.have.lengthOf(2);
+    expect(canvas.listeners.has('wheel')).to.equal(true);
+    expect(globalThis.window.listeners.has('resize')).to.equal(true);
+  });
+
+  it('handles wheel zoom with the installed listener', function () {
+    const canvas = createCanvasMock();
+    const { stage, view, controller } = createAdapterFixture();
+    const adapter = new ProcgenStageAdapter({ view, controller, canvas });
+    adapter.install();
+
+    const wheel = canvas.listeners.get('wheel');
+    expect(typeof wheel).to.equal('function');
+    let prevented = false;
+    wheel({
+      deltaY: -1,
+      preventDefault() {
+        prevented = true;
+      }
+    });
+
+    expect(prevented).to.equal(true);
+    expect(stage.applyViewportCalls).to.have.lengthOf(1);
+    expect(stage.redrawCalls).to.equal(1);
+  });
+
+  it('ignores wheel events with zero delta to avoid accidental zoom', function () {
+    const canvas = createCanvasMock();
+    const { stage, view, controller } = createAdapterFixture();
+    const adapter = new ProcgenStageAdapter({ view, controller, canvas });
+    adapter.install();
+
+    const wheel = canvas.listeners.get('wheel');
+    wheel({
+      deltaY: 0,
+      preventDefault() {}
+    });
+
+    expect(stage.applyViewportCalls).to.have.lengthOf(0);
+    expect(stage.redrawCalls).to.equal(0);
+  });
+
+  it('binds and unbinds resize listeners against provided window references', function () {
+    const canvas = createCanvasMock();
+    const win = createWindowMock();
+    const { view, controller } = createAdapterFixture();
+    const adapter = new ProcgenStageAdapter({ view, controller, canvas, windowRef: win });
+
+    adapter.install();
+    expect(win.listeners.has('resize')).to.equal(true);
+    expect(globalThis.window.listeners.has('resize')).to.equal(false);
+
+    adapter.dispose();
+    expect(win.listeners.has('resize')).to.equal(false);
+  });
+
+  it('updates stage size through explicit adapter handles', function () {
+    const canvas = createCanvasMock();
+    const { stage, view, controller } = createAdapterFixture();
+    const adapter = new ProcgenStageAdapter({ view, controller, canvas });
+
+    adapter.updateStageSize();
+    expect(stage.updateStageSizeCalls).to.equal(1);
+
+    adapter.install();
+    const onResize = globalThis.window.listeners.get('resize');
+    expect(typeof onResize).to.equal('function');
+    onResize();
+    expect(stage.updateStageSizeCalls).to.equal(2);
+  });
+
+  it('handles missing gui image properties without throwing', function () {
+    const canvas = createCanvasMock();
+    const { stage, view, controller } = createAdapterFixture();
+    stage.guiImgProps = null;
+    const adapter = new ProcgenStageAdapter({ view, controller, canvas });
+
+    expect(() => adapter.install()).to.not.throw();
+    adapter.updateStageSize();
+    expect(stage.updateStageSizeCalls).to.equal(1);
+  });
+});
diff --git a/test/procgen-terrain-stamper.test.js b/test/procgen-terrain-stamper.test.js
new file mode 100644
index 00000000..2774d3db
--- /dev/null
+++ b/test/procgen-terrain-stamper.test.js
@@ -0,0 +1,75 @@
+import { expect } from 'chai';
+import { ProcgenTerrainStamper } from '../js/app/procgenTerrainStamper.js';
+
+const createLevel = (width, height) => ({
+  width,
+  height,
+  groundImage: new Uint8ClampedArray(width * height * 4),
+  groundMask: {
+    mask: new Uint8Array(width * height)
+  },
+  applyGroundBulkChange() {}
+});
+
+describe('ProcgenTerrainStamper', function () {
+  it('clips partially offscreen stamps and reuses cached destination views', function () {
+    const level = createLevel(4, 4);
+    const bulkCalls = [];
+    level.applyGroundBulkChange = (...args) => bulkCalls.push(args);
+    const stamper = new ProcgenTerrainStamper(level);
+    const piece = {
+      image: {
+        width: 2,
+        height: 2,
+        palette: {
+          getColor(i) { return i + 1000; }
+        }
+      },
+      frame: new Uint8Array([
+        1, 2,
+        3, 4
+      ])
+    };
+
+    stamper.stamp(piece, -1, 1);
+    const firstView = stamper._dest32;
+
+    const idxA = (1 * level.width) + 0;
+    const idxB = (2 * level.width) + 0;
+    expect(level.groundMask.mask[idxA]).to.equal(1);
+    expect(level.groundMask.mask[idxB]).to.equal(1);
+    expect(firstView[idxA]).to.equal(1002);
+    expect(firstView[idxB]).to.equal(1004);
+    expect(bulkCalls.length).to.equal(1);
+    expect(bulkCalls[0][0]).to.equal(0);
+    expect(bulkCalls[0][1]).to.equal(1);
+
+    stamper.stamp(piece, 1, 1);
+    expect(stamper._dest32).to.equal(firstView);
+  });
+
+  it('respects noOverwrite during clipped writes', function () {
+    const level = createLevel(3, 3);
+    const stamper = new ProcgenTerrainStamper(level);
+    const piece = {
+      image: {
+        width: 1,
+        height: 1,
+        palette: {
+          getColor(i) { return i + 2000; }
+        }
+      },
+      frame: new Uint8Array([7])
+    };
+    const idx = (1 * level.width) + 1;
+    level.groundMask.mask[idx] = 1;
+    const before = new Uint32Array(level.groundImage.buffer);
+    before[idx] = 999;
+
+    stamper.stamp(piece, 1, 1, { noOverwrite: true });
+
+    const after = new Uint32Array(level.groundImage.buffer);
+    expect(level.groundMask.mask[idx]).to.equal(1);
+    expect(after[idx]).to.equal(999);
+  });
+});
diff --git a/test/register-service-worker.test.js b/test/register-service-worker.test.js
new file mode 100644
index 00000000..f241f11d
--- /dev/null
+++ b/test/register-service-worker.test.js
@@ -0,0 +1,210 @@
+import { expect } from 'chai';
+import {
+  registerServiceWorker,
+  shouldBypassServiceWorker
+} from '../js/app/registerServiceWorker.js';
+
+const flush = async () => {
+  await Promise.resolve();
+  await new Promise(resolve => setTimeout(resolve, 0));
+};
+
+describe('registerServiceWorker', function () {
+  it('bypasses service worker in perf/e2e/dev contexts', function () {
+    const baseLocation = {
+      protocol: 'https:',
+      hostname: 'example.com',
+      search: ''
+    };
+    expect(shouldBypassServiceWorker({ profile: 'perf', location: baseLocation })).to.equal(true);
+    expect(shouldBypassServiceWorker({ profile: 'classic', e2e: true, location: baseLocation })).to.equal(true);
+    expect(shouldBypassServiceWorker({
+      profile: 'classic',
+      location: { ...baseLocation, search: '?e2e=1' }
+    })).to.equal(true);
+    expect(shouldBypassServiceWorker({
+      profile: 'classic',
+      location: { protocol: 'https:', hostname: 'localhost', search: '' }
+    })).to.equal(true);
+    expect(shouldBypassServiceWorker({
+      profile: 'classic',
+      location: { protocol: 'https:', hostname: 'localhost', search: '?sw=1' }
+    })).to.equal(false);
+    expect(shouldBypassServiceWorker({
+      profile: 'classic',
+      location: { protocol: 'https:', hostname: 'localhost', search: '?sw=1&noSw=1' }
+    })).to.equal(true);
+    expect(shouldBypassServiceWorker({ profile: 'classic', location: baseLocation })).to.equal(false);
+    expect(shouldBypassServiceWorker({ profile: 'e2e', location: baseLocation })).to.equal(true);
+  });
+
+  it('registers service worker with runtime revision when enabled', async function () {
+    const calls = [];
+    const registration = {
+      waiting: null,
+      update() {
+        return Promise.resolve();
+      },
+      addEventListener() {}
+    };
+    const serviceWorker = {
+      controller: null,
+      register(url, options) {
+        calls.push({ url, options });
+        return Promise.resolve(registration);
+      },
+      addEventListener() {}
+    };
+    const windowRef = {
+      location: {
+        protocol: 'https:',
+        hostname: 'example.com',
+        search: ''
+      },
+      setInterval() {},
+      addEventListener() {}
+    };
+    const documentRef = {
+      readyState: 'complete',
+      visibilityState: 'visible',
+      addEventListener() {}
+    };
+
+    registerServiceWorker({
+      profile: 'classic',
+      revision: 'phase30b',
+      window: windowRef,
+      document: documentRef,
+      location: windowRef.location,
+      navigator: { serviceWorker }
+    });
+    await flush();
+
+    expect(calls).to.have.lengthOf(1);
+    expect(calls[0].url).to.equal('service-worker.js?rev=phase30b');
+    expect(calls[0].options).to.deep.equal({ updateViaCache: 'none' });
+  });
+
+  it('returns a disposable runtime that removes update listeners and intervals', async function () {
+    const removed = [];
+    const cleared = [];
+    const registration = {
+      waiting: null,
+      update() {
+        return Promise.resolve();
+      },
+      addEventListener() {},
+      removeEventListener(type) {
+        removed.push(`registration:${type}`);
+      }
+    };
+    const serviceWorker = {
+      controller: null,
+      register() {
+        return Promise.resolve(registration);
+      },
+      addEventListener() {},
+      removeEventListener(type) {
+        removed.push(`sw:${type}`);
+      }
+    };
+    const windowRef = {
+      location: {
+        protocol: 'https:',
+        hostname: 'example.com',
+        search: ''
+      },
+      setInterval() {
+        return 7;
+      },
+      clearInterval(id) {
+        cleared.push(id);
+      },
+      addEventListener() {},
+      removeEventListener(type) {
+        removed.push(`window:${type}`);
+      }
+    };
+    const documentRef = {
+      readyState: 'complete',
+      visibilityState: 'visible',
+      addEventListener() {},
+      removeEventListener(type) {
+        removed.push(`document:${type}`);
+      }
+    };
+
+    const runtime = registerServiceWorker({
+      profile: 'classic',
+      window: windowRef,
+      document: documentRef,
+      location: windowRef.location,
+      navigator: { serviceWorker }
+    });
+    await flush();
+    runtime.dispose();
+
+    expect(cleared).to.deep.equal([7]);
+    expect(removed).to.include.members([
+      'registration:updatefound',
+      'sw:controllerchange',
+      'document:visibilitychange',
+      'window:focus',
+      'window:online'
+    ]);
+  });
+
+  it('unregisters active service workers and clears app caches when bypassing', async function () {
+    const unregistered = [];
+    const deletedCaches = [];
+    const serviceWorker = {
+      getRegistrations() {
+        return Promise.resolve([
+          { unregister() { unregistered.push('a'); return Promise.resolve(true); } },
+          { unregister() { unregistered.push('b'); return Promise.resolve(true); } }
+        ]);
+      },
+      register() {
+        throw new Error('register should not be called while bypassing');
+      }
+    };
+    const cacheStorage = {
+      keys() {
+        return Promise.resolve([
+          'lemmings-core-v1',
+          'lem-other-cache',
+          'lemmings-runtime-v2'
+        ]);
+      },
+      delete(key) {
+        deletedCaches.push(key);
+        return Promise.resolve(true);
+      }
+    };
+    const windowRef = {
+      location: {
+        protocol: 'https:',
+        hostname: 'example.com',
+        search: ''
+      },
+      addEventListener() {}
+    };
+    const documentRef = {
+      readyState: 'complete',
+      addEventListener() {}
+    };
+
+    registerServiceWorker({
+      profile: 'perf',
+      window: windowRef,
+      document: documentRef,
+      location: windowRef.location,
+      navigator: { serviceWorker },
+      cacheStorage
+    });
+    await flush();
+
+    expect(unregistered).to.deep.equal(['a', 'b']);
+    expect(deletedCaches).to.deep.equal(['lemmings-core-v1', 'lemmings-runtime-v2']);
+  });
+});
diff --git a/test/release-readiness.test.js b/test/release-readiness.test.js
new file mode 100644
index 00000000..bfa5b9a9
--- /dev/null
+++ b/test/release-readiness.test.js
@@ -0,0 +1,245 @@
+import { expect } from 'chai';
+import {
+  REQUIRED_SECTIONS,
+  evaluateReleaseReadiness,
+  looksLikeWindowsAbsolutePath,
+  parseChecklistBySection,
+  run
+} from '../scripts/check-release-readiness.js';
+
+describe('release readiness checklist', function () {
+  it('parses checklist entries grouped by section', function () {
+    const sections = parseChecklistBySection('## Compatibility\n- [x] API contract validated\n\n## Migration\n- [ ] migration notes');
+    expect(Array.from(sections.keys())).to.deep.equal(['Compatibility', 'Migration']);
+    expect(sections.get('Compatibility')).to.deep.equal([
+      { checked: true, text: 'API contract validated' }
+    ]);
+    expect(sections.get('Migration')).to.deep.equal([
+      { checked: false, text: 'migration notes' }
+    ]);
+  });
+
+  it('parses headings with leading spaces and trailing hash markers', function () {
+    const sections = parseChecklistBySection('  ## Performance ##\n- [x] bench replay parity');
+    expect(Array.from(sections.keys())).to.deep.equal(['Performance']);
+    expect(sections.get('Performance')).to.deep.equal([
+      { checked: true, text: 'bench replay parity' }
+    ]);
+  });
+
+  it('passes when required sections are present and fully checked', function () {
+    const markdown = REQUIRED_SECTIONS.map((section) => (
+      `## ${section}\n- [x] complete`
+    )).join('\n\n');
+
+    const summary = evaluateReleaseReadiness(markdown, { requireAllChecked: true });
+    expect(summary.ok).to.equal(true);
+    expect(summary.missingSections).to.deep.equal([]);
+    expect(summary.emptySections).to.deep.equal([]);
+    expect(summary.uncheckedItems).to.deep.equal([]);
+  });
+
+  it('fails when required sections are missing or unchecked', function () {
+    const markdown = [
+      '## Compatibility',
+      '- [x] api compatibility verified',
+      '',
+      '## Migration',
+      '- [ ] migration rehearsal pending'
+    ].join('\n');
+
+    const summary = evaluateReleaseReadiness(markdown, { requireAllChecked: true });
+    expect(summary.ok).to.equal(false);
+    expect(summary.missingSections).to.include.members([
+      'Performance',
+      'Accessibility',
+      'Runtime Controls'
+    ]);
+    expect(summary.uncheckedItems).to.deep.equal([
+      { section: 'Migration', text: 'migration rehearsal pending' }
+    ]);
+  });
+
+  it('allows unchecked entries in non-strict mode while still requiring structure', function () {
+    const markdown = REQUIRED_SECTIONS.map((section) => (
+      `## ${section}\n- [ ] pending`
+    )).join('\n\n');
+
+    const summary = evaluateReleaseReadiness(markdown, { requireAllChecked: false });
+    expect(summary.ok).to.equal(true);
+    expect(summary.counts.uncheckedCount).to.equal(REQUIRED_SECTIONS.length);
+  });
+
+  it('run emits summary and succeeds when checklist passes', function () {
+    const logs = [];
+    const exits = [];
+    run([], {
+      cwd: 'C:/workspace',
+      fsImpl: {
+        readFileSync() {
+          return REQUIRED_SECTIONS.map(section => `## ${section}\n- [x] complete`).join('\n\n');
+        }
+      },
+      log: {
+        log(message) {
+          logs.push(message);
+        },
+        error() {}
+      },
+      exit(code) {
+        exits.push(code);
+      }
+    });
+    expect(exits).to.deep.equal([]);
+    expect(logs).to.have.lengthOf(1);
+    const parsed = JSON.parse(logs[0]);
+    expect(parsed.ok).to.equal(true);
+    expect(parsed.strict).to.equal(true);
+  });
+
+  it('distinguishes Windows-style absolute paths from POSIX roots', function () {
+    expect(looksLikeWindowsAbsolutePath('/workspace/docs/release-readiness.md')).to.equal(false);
+    expect(looksLikeWindowsAbsolutePath('docs/release-readiness.md')).to.equal(false);
+    expect(looksLikeWindowsAbsolutePath('C:/workspace/docs/release-readiness.md')).to.equal(true);
+    expect(looksLikeWindowsAbsolutePath('C:\\workspace\\docs\\release-readiness.md')).to.equal(true);
+    expect(looksLikeWindowsAbsolutePath('\\\\server\\share\\release-readiness.md')).to.equal(true);
+  });
+
+  it('run exits non-zero when checklist file cannot be loaded', function () {
+    const errors = [];
+    const exits = [];
+    run([], {
+      cwd: 'C:/workspace',
+      fsImpl: {
+        readFileSync() {
+          throw new Error('missing');
+        }
+      },
+      log: {
+        log() {},
+        error(message) {
+          errors.push(message);
+        }
+      },
+      exit(code) {
+        exits.push(code);
+      }
+    });
+    expect(exits).to.deep.equal([1]);
+    expect(errors[0]).to.contain('Unable to read release-readiness document');
+  });
+
+  it('run supports non-strict mode via --strict=false', function () {
+    const exits = [];
+    run(['--strict=false'], {
+      cwd: 'C:/workspace',
+      fsImpl: {
+        readFileSync() {
+          return REQUIRED_SECTIONS.map(section => `## ${section}\n- [ ] pending`).join('\n\n');
+        }
+      },
+      log: {
+        log() {},
+        error() {}
+      },
+      exit(code) {
+        exits.push(code);
+      }
+    });
+    expect(exits).to.deep.equal([]);
+  });
+
+  it('run exits non-zero and emits summary when checklist requirements fail', function () {
+    const logs = [];
+    const exits = [];
+    run([], {
+      cwd: 'C:/workspace',
+      fsImpl: {
+        readFileSync() {
+          return '## Compatibility\n- [x] complete';
+        }
+      },
+      log: {
+        log(message) {
+          logs.push(message);
+        },
+        error() {}
+      },
+      exit(code) {
+        exits.push(code);
+      }
+    });
+    expect(exits).to.deep.equal([1]);
+    expect(logs).to.have.lengthOf(1);
+    const parsed = JSON.parse(logs[0]);
+    expect(parsed.ok).to.equal(false);
+    expect(parsed.missingSections).to.include('Migration');
+  });
+
+  it('run supports release checklist file override via environment variable', function () {
+    const originalPath = process.env.LEMMINGS_RELEASE_READINESS_PATH;
+    process.env.LEMMINGS_RELEASE_READINESS_PATH = 'docs/custom-readiness.md';
+    const reads = [];
+    const exits = [];
+    try {
+      run([], {
+        cwd: 'C:/workspace',
+        fsImpl: {
+          readFileSync(file, encoding) {
+            reads.push({ file, encoding });
+            return REQUIRED_SECTIONS.map(section => `## ${section}\n- [x] done`).join('\n\n');
+          }
+        },
+        log: {
+          log() {},
+          error() {}
+        },
+        exit(code) {
+          exits.push(code);
+        }
+      });
+    } finally {
+      if (originalPath == null) {
+        delete process.env.LEMMINGS_RELEASE_READINESS_PATH;
+      } else {
+        process.env.LEMMINGS_RELEASE_READINESS_PATH = originalPath;
+      }
+    }
+
+    expect(reads).to.have.lengthOf(1);
+    expect(reads[0].encoding).to.equal('utf8');
+    expect(reads[0].file.replace(/\\/g, '/')).to.equal('C:/workspace/docs/custom-readiness.md');
+    expect(exits).to.deep.equal([]);
+  });
+
+  it('run prioritizes --file over environment path override', function () {
+    const originalPath = process.env.LEMMINGS_RELEASE_READINESS_PATH;
+    process.env.LEMMINGS_RELEASE_READINESS_PATH = 'docs/env-readiness.md';
+    const reads = [];
+    try {
+      run(['--file=docs/arg-readiness.md'], {
+        cwd: 'C:/workspace',
+        fsImpl: {
+          readFileSync(file) {
+            reads.push(file);
+            return REQUIRED_SECTIONS.map(section => `## ${section}\n- [x] done`).join('\n\n');
+          }
+        },
+        log: {
+          log() {},
+          error() {}
+        },
+        exit() {}
+      });
+    } finally {
+      if (originalPath == null) {
+        delete process.env.LEMMINGS_RELEASE_READINESS_PATH;
+      } else {
+        process.env.LEMMINGS_RELEASE_READINESS_PATH = originalPath;
+      }
+    }
+
+    expect(reads).to.have.lengthOf(1);
+    expect(reads[0].replace(/\\/g, '/')).to.equal('C:/workspace/docs/arg-readiness.md');
+  });
+});
diff --git a/test/render/minimap.test.js b/test/render/minimap.test.js
index 5f9f1606..5a76b166 100644
--- a/test/render/minimap.test.js
+++ b/test/render/minimap.test.js
@@ -49,25 +49,43 @@ describe('MiniMap', function() {
 
     counter.value = 5;
     miniMap.invalidateRegion(0, 0, 2, 2);
+    withGlobalLemmings({
+      stage: { getGameViewRect() { return { x: 0, y: 0, w: 50, h: 25 }; } },
+      game: { timeTravel: { isReversing: false } }
+    }, () => {
+      miniMap.render();
+    });
     expect(miniMap.terrain[0]).to.equal(5);
 
     miniMap.fog.fill(0);
     miniMap.reveal(0, 10);
     expect(miniMap.fog[0]).to.equal(1);
+    miniMap.fog.fill(0);
+    miniMap.reveal(-10, 5);
+    expect(Object.prototype.hasOwnProperty.call(miniMap.fog, '-1')).to.equal(false);
+    expect(miniMap.fog[0]).to.equal(0);
   });
 
   it('handles pointer events and death tracking', function() {
     const counter = { value: 1 };
     const level = makeLevel(counter);
     const guiDisplay = makeGuiDisplay();
-    const miniMap = new MiniMap({}, level, guiDisplay);
+    const records = [];
+    const miniMap = new MiniMap({}, level, guiDisplay, {
+      history: { recordMinimapDeath: (entry) => records.push(entry) }
+    });
 
     const destX = guiDisplay.worldDataSize.width - miniMap.width;
-    const destY = guiDisplay.worldDataSize.height - miniMap.height - 1;
+    const destY = guiDisplay.worldDataSize.height - miniMap.height;
 
     guiDisplay.onMouseDown.trigger({ x: destX + 10, y: destY + 5 });
-    const expectedX = ((level.width - guiDisplay.worldDataSize.width)
-      * ((10) / miniMap.width)) | 0;
+    const expectedX = Math.max(
+      0,
+      Math.min(
+        level.width - guiDisplay.worldDataSize.width,
+        ((level.width - guiDisplay.worldDataSize.width) * (10 / (miniMap.width - 1))) | 0
+      )
+    );
     expect(level.screenPositionX).to.equal(expectedX);
 
     guiDisplay.onMouseMove.trigger({ x: destX + 15, y: destY + 5 });
@@ -76,20 +94,77 @@ describe('MiniMap', function() {
     guiDisplay.onMouseUp.trigger({ x: destX + 20, y: destY + 5 });
     expect(guiDisplay.setScreenPositionCalls.length).to.equal(3);
 
+    guiDisplay.onMouseMove.trigger({ x: destX + miniMap.width - 1, y: destY + 5 });
+    expect(level.screenPositionX).to.equal(0);
+
+    guiDisplay.onMouseDown.trigger({ x: destX + 1, y: destY + miniMap.height - 1 });
+    expect(guiDisplay.setScreenPositionCalls.length).to.equal(4);
+
     guiDisplay.onMouseDown.trigger({ x: 1, y: 1 });
-    expect(guiDisplay.setScreenPositionCalls.length).to.equal(3);
+    expect(guiDisplay.setScreenPositionCalls.length).to.equal(4);
+    guiDisplay.onMouseDown.trigger({ x: Number.NaN, y: destY + 1 });
+    expect(guiDisplay.setScreenPositionCalls.length).to.equal(4);
+
+    miniMap.deadCount = miniMap.deadTTLs.length;
+    miniMap.addDeath(5, 5);
+    expect(records.length).to.equal(1);
+    expect(miniMap.deadTTLs.length).to.be.greaterThan(32);
+  });
+
+  it('uses stage viewport width for pointer mapping when available', function() {
+    const counter = { value: 1 };
+    const level = makeLevel(counter);
+    level.width = 500;
+    const guiDisplay = makeGuiDisplay();
+    const miniMap = new MiniMap({}, level, guiDisplay);
+    const destX = guiDisplay.worldDataSize.width - miniMap.width;
+    const destY = guiDisplay.worldDataSize.height - miniMap.height;
+    const stageWidth = 120;
 
-    const records = [];
     withGlobalLemmings({
-      game: {
-        history: { recordMinimapDeath: (entry) => records.push(entry) }
+      stage: {
+        getGameViewRect() {
+          return { x: 0, y: 0, w: stageWidth, h: 25 };
+        }
       }
     }, () => {
-      miniMap.deadCount = miniMap.deadTTLs.length;
-      miniMap.addDeath(5, 5);
-      expect(records.length).to.equal(1);
-      expect(miniMap.deadTTLs.length).to.be.greaterThan(32);
+      guiDisplay.onMouseDown.trigger({ x: destX + 10, y: destY + 5 });
+    });
+
+    const expectedX = Math.max(
+      0,
+      Math.min(
+        level.width - stageWidth,
+        ((level.width - stageWidth) * (10 / (miniMap.width - 1))) | 0
+      )
+    );
+    expect(level.screenPositionX).to.equal(expectedX);
+  });
+
+  it('normalizes invalid level dimensions to finite minimap scales', function() {
+    const counter = { value: 1 };
+    const level = makeLevel(counter);
+    level.width = 0;
+    level.height = Number.NaN;
+    const guiDisplay = makeGuiDisplay();
+    const miniMap = new MiniMap({}, level, guiDisplay);
+
+    expect(Number.isFinite(miniMap.scaleX)).to.equal(true);
+    expect(Number.isFinite(miniMap.scaleY)).to.equal(true);
+    expect(miniMap.scaleX).to.be.greaterThan(0);
+    expect(miniMap.scaleY).to.be.greaterThan(0);
+
+    const destX = guiDisplay.worldDataSize.width - miniMap.width;
+    const destY = guiDisplay.worldDataSize.height - miniMap.height;
+    miniMap.invalidateRegion(0, 0, 4, 4);
+    withGlobalLemmings({
+      stage: { getGameViewRect() { return { x: 0, y: 0, w: 50, h: 25 }; } },
+      game: { timeTravel: { isReversing: false } }
+    }, () => {
+      expect(() => miniMap.render()).to.not.throw();
+      guiDisplay.onMouseDown.trigger({ x: destX + 20, y: destY + 5 });
     });
+    expect(Number.isFinite(level.screenPositionX)).to.equal(true);
   });
 
   it('renders viewport, dots, and death flashes', function() {
@@ -164,6 +239,12 @@ describe('MiniMap', function() {
     const guiDisplay = makeGuiDisplay();
     const miniMap = new MiniMap({}, level, guiDisplay);
     miniMap.invalidateRegion(0, 0, 1, 1);
+    withGlobalLemmings({
+      stage: { getGameViewRect() { return { x: 0, y: 0, w: 50, h: 25 }; } },
+      game: { timeTravel: { isReversing: false } }
+    }, () => {
+      miniMap.render();
+    });
     expect(miniMap.terrain[0]).to.equal(72);
 
     withGlobalLemmings(null, () => {
@@ -197,7 +278,7 @@ describe('MiniMap', function() {
     const guiDisplay = makeGuiDisplay();
     const miniMap = new MiniMap({}, level, guiDisplay);
     const destX = guiDisplay.worldDataSize.width - miniMap.width;
-    const destY = guiDisplay.worldDataSize.height - miniMap.height - 1;
+    const destY = guiDisplay.worldDataSize.height - miniMap.height;
 
     miniMap.guiDisplay = null;
     guiDisplay.onMouseDown.trigger({ x: destX + 1, y: destY + 1 });
@@ -213,4 +294,92 @@ describe('MiniMap', function() {
     miniMap._mouseDown = true;
     guiDisplay.onMouseMove.trigger({ x: 1, y: 1 });
   });
+
+  it('reuses cached minimap frame composition when inputs are unchanged', function() {
+    const counter = { value: 1 };
+    const level = makeLevel(counter);
+    const guiDisplay = makeGuiDisplay();
+    const miniMap = new MiniMap({}, level, guiDisplay);
+    withGlobalLemmings({
+      stage: { getGameViewRect() { return { x: 0, y: 0, w: 50, h: 25 }; } },
+      game: { timeTravel: { isReversing: false } }
+    }, () => {
+      miniMap.render();
+      miniMap.render();
+    });
+    const diagnostics = miniMap.getRenderDiagnostics();
+    expect(diagnostics.composes).to.be.greaterThan(0);
+    expect(diagnostics.reuses).to.be.greaterThan(0);
+  });
+
+  it('bounds terrain revalidation queue growth under heavy updates', function() {
+    const counter = { value: 1 };
+    const level = makeLevel(counter);
+    const guiDisplay = makeGuiDisplay();
+    const miniMap = new MiniMap({}, level, guiDisplay);
+
+    const updates = miniMap.width * miniMap.height + 10;
+    for (let i = 0; i < updates; i += 1) {
+      const miniMapX = i % miniMap.width;
+      const miniMapY = 0;
+      miniMap.invalidateRegion(
+        Math.floor(miniMapX / miniMap.scaleX),
+        Math.floor(miniMapY / miniMap.scaleY),
+        1 / miniMap.scaleX,
+        1 / miniMap.scaleY
+      );
+    }
+
+    expect(miniMap.getRenderDiagnostics().terrainDirtyCount).to.be.at.most(miniMap.size);
+
+    withGlobalLemmings({
+      stage: { getGameViewRect() { return { x: 0, y: 0, w: 50, h: 25 }; } },
+      game: { timeTravel: { isReversing: false } }
+    }, () => {
+      miniMap.render();
+    });
+
+    expect(miniMap.getRenderDiagnostics().terrainDirtyCount).to.be.at.least(0);
+  });
+
+  it('keeps viewport pinned when map width does not exceed visible width', function() {
+    const counter = { value: 1 };
+    const level = makeLevel(counter);
+    level.width = 120;
+    const guiDisplay = makeGuiDisplay();
+    guiDisplay.worldDataSize.width = 200;
+    const miniMap = new MiniMap({}, level, guiDisplay);
+    const destX = guiDisplay.worldDataSize.width - miniMap.width;
+    const destY = guiDisplay.worldDataSize.height - miniMap.height;
+
+    guiDisplay.onMouseDown.trigger({ x: destX + miniMap.width - 1, y: destY + 5 });
+    expect(level.screenPositionX).to.equal(0);
+    expect(guiDisplay.setScreenPositionCalls.at(-1).x).to.equal(0);
+  });
+
+  it('evicts overwritten dirty indices when queue is saturated', function() {
+    const counter = { value: 1 };
+    const level = makeLevel(counter);
+    const guiDisplay = makeGuiDisplay();
+    const miniMap = new MiniMap({}, level, guiDisplay);
+
+    const overwritten = 17;
+    miniMap._terrainDirtyCount = miniMap.size;
+    miniMap._terrainDirtyRead = 0;
+    miniMap._terrainDirtyWrite = 0;
+    miniMap._terrainDirtyFlags.fill(0);
+    miniMap._terrainDirtyIndices[0] = overwritten;
+    miniMap._terrainDirtyFlags[overwritten] = 1;
+
+    const miniMapX = 22;
+    miniMap.invalidateRegion(
+      Math.floor(miniMapX / miniMap.scaleX),
+      0,
+      1 / miniMap.scaleX,
+      1 / miniMap.scaleY
+    );
+
+    expect(miniMap._terrainDirtyFlags[overwritten]).to.equal(0);
+    expect(miniMap._terrainDirtyCount).to.equal(miniMap.size);
+  });
 });
diff --git a/test/render/solidlayer.test.js b/test/render/solidlayer.test.js
index 4d73bc9b..fb68f747 100644
--- a/test/render/solidlayer.test.js
+++ b/test/render/solidlayer.test.js
@@ -27,6 +27,17 @@ describe('SolidLayer', function() {
     expect(layer.getColumnGapDepth(-1, 0, 2)).to.equal(3);
     expect(layer.getColumnGapDepth(0, -1, 2)).to.equal(3);
 
+    expect(layer.getColumnWallHeight(2, 3, 3)).to.equal(2);
+    expect(layer.getColumnWallHeight(1, 3, 3)).to.equal(1);
+    expect(layer.getColumnWallHeight(0, 3, 3)).to.equal(0);
+    expect(layer.getColumnWallHeight(-1, 3, 3)).to.equal(0);
+    expect(layer.getColumnWallHeight(2, 3, 0)).to.equal(0);
+    expect(layer.getColumnWallHeight(2, 3, -4)).to.equal(0);
+    const gapLayer = new SolidLayer(3, 4);
+    gapLayer.setMaskAt(1, 2);
+    gapLayer.setMaskAt(1, 0);
+    expect(gapLayer.getColumnWallHeight(1, 3, 3)).to.equal(1);
+
     expect(layer.countMaskInRect(1, 1, 3, 3, 2)).to.equal(2);
     expect(layer.countMaskInRect(0, 0, 4, 4)).to.equal(4);
     expect(layer.countMaskInRect(0, 0, 0, 2)).to.equal(0);
diff --git a/test/render/stage.01-stage.test.js b/test/render/stage.01-stage.test.js
new file mode 100644
index 00000000..03c22fae
--- /dev/null
+++ b/test/render/stage.01-stage.test.js
@@ -0,0 +1,426 @@
+import { expect } from 'chai';
+import { Stage } from '../../js/render/Stage.js';
+import { ViewPoint } from '../../js/render/ViewPoint.js';
+import { setDependency, resetDependencies, useGlobalLemmings, withGlobalLemmings } from '../helpers/lemmings.js';
+
+const makeContext = () => {
+  const ctx = {
+    canvas: null,
+    imageSmoothingEnabled: false,
+    globalAlpha: 1,
+    fillStyle: '',
+    putCalls: [],
+    drawCalls: [],
+    fillCalls: [],
+    textCalls: [],
+    createImageData(width, height) {
+      return { width, height, data: new Uint8ClampedArray(width * height * 4) };
+    },
+    putImageData(img, x, y) {
+      this.putCalls.push({ img, x, y });
+    },
+    getImageData(x, y, width, height) {
+      return { width, height, data: new Uint8ClampedArray(width * height * 4) };
+    },
+    fillRect(x, y, width, height) {
+      this.fillCalls.push({ x, y, width, height });
+    },
+    fillText(text, x, y) {
+      this.textCalls.push({ text, x, y });
+    },
+    drawImage(...args) {
+      this.drawCalls.push(args);
+    }
+  };
+  return ctx;
+};
+
+const makeCanvas = (width = 320, height = 200) => {
+  const ctx = makeContext();
+  const canvas = {
+    width,
+    height,
+    style: {},
+    getContext() { return ctx; },
+    addEventListener() {},
+    removeEventListener() {}
+  };
+  ctx.canvas = canvas;
+  return { canvas, ctx };
+};
+
+describe('Stage', function() {
+  const originalWindow = globalThis.window;
+
+  const originalDocument = globalThis.document;
+
+  const originalImageData = globalThis.ImageData;
+
+  const originalPerformance = globalThis.performance;
+
+  useGlobalLemmings({});
+
+  let now = 0;
+
+  beforeEach(function() {
+    now = 0;
+    globalThis.document = {
+      createElement() {
+        return makeCanvas(10, 10).canvas;
+      }
+    };
+    globalThis.window = {
+      requestAnimationFrame() { return 1; },
+      cancelAnimationFrame() {}
+    };
+    globalThis.ImageData = class {
+      constructor(data, width, height) {
+        this.data = data;
+        this.width = width;
+        this.height = height;
+      }
+    };
+    globalThis.performance = {
+      now: () => {
+        now += 1;
+        return now;
+      }
+    };
+  });
+
+  afterEach(function() {
+    resetDependencies();
+    globalThis.window = originalWindow;
+    globalThis.document = originalDocument;
+    globalThis.ImageData = originalImageData;
+    globalThis.performance = originalPerformance;
+  });
+
+  it('routes pointer events and handles zoom', function() {
+    const { canvas } = makeCanvas(320, 200);
+    const stage = new Stage(canvas);
+    stage.gameImgProps.display.initSize(100, 50);
+    stage.guiImgProps.display.initSize(80, 20);
+    stage.updateStageSize();
+
+    let lastDown = null;
+    stage.gameImgProps.display.onMouseDown.on(pos => { lastDown = pos; });
+
+    stage.controller.onMouseDown.trigger({ x: 10, y: 10 });
+    expect(lastDown).to.not.equal(null);
+    stage.controller.onMouseDown.trigger({ x: 1000, y: 1000 });
+
+    let updateArgs = null;
+    stage.updateViewPoint = (...args) => { updateArgs = args; };
+    stage.controller.onMouseMove.trigger({
+      x: 12,
+      y: 12,
+      mouseDownX: 10,
+      mouseDownY: 10,
+      deltaX: 3,
+      deltaY: -2,
+      button: true
+    });
+    expect(updateArgs).to.not.equal(null);
+
+    updateArgs = null;
+    stage.controller.onZoom.trigger({ x: 20, y: 10, deltaZoom: 5, velocity: 1 });
+    expect(updateArgs).to.not.equal(null);
+
+    updateArgs = null;
+    stage.gameImgProps.display = null;
+    stage.controller.onZoom.trigger({ x: 20, y: 10, deltaZoom: 5, velocity: 1 });
+    expect(updateArgs).to.equal(null);
+  });
+
+  it('routes right clicks and hover events', function() {
+    const { canvas } = makeCanvas(320, 200);
+    const stage = new Stage(canvas);
+    stage.gameImgProps.display.initSize(100, 50);
+    stage.guiImgProps.display.initSize(80, 20);
+    stage.updateStageSize();
+
+    let up = 0;
+    let rightDown = 0;
+    let rightUp = 0;
+    let dbl = 0;
+    let move = 0;
+    stage.gameImgProps.display.onMouseUp.on(() => { up += 1; });
+    stage.gameImgProps.display.onMouseRightDown.on(() => { rightDown += 1; });
+    stage.gameImgProps.display.onMouseRightUp.on(() => { rightUp += 1; });
+    stage.gameImgProps.display.onDoubleClick.on(() => { dbl += 1; });
+    stage.gameImgProps.display.onMouseMove.on(() => { move += 1; });
+
+    stage.controller.onMouseUp.trigger({ x: 1, y: 1 });
+    stage.controller.onMouseUp.trigger({ x: 1000, y: 1000 });
+    stage.controller.onMouseRightDown.trigger({ x: 1, y: 1 });
+    stage.controller.onMouseRightDown.trigger({ x: 1000, y: 1000 });
+    stage.controller.onMouseRightUp.trigger({ x: 1, y: 1 });
+    stage.controller.onMouseRightUp.trigger({ x: 1000, y: 1000 });
+    stage.controller.onDoubleClick.trigger({ x: 1, y: 1 });
+    stage.controller.onDoubleClick.trigger({ x: 1000, y: 1000 });
+    stage.controller.onMouseMove.trigger({ x: 2, y: 2, button: false });
+    stage.controller.onMouseMove.trigger({ x: 1000, y: 1000, button: false });
+    stage.controller.onMouseMove.trigger({
+      x: 2,
+      y: 2,
+      mouseDownX: 1000,
+      mouseDownY: 1000,
+      deltaX: 0,
+      deltaY: 0,
+      button: true
+    });
+    stage.panEnabled = false;
+    stage.controller.onMouseMove.trigger({
+      x: 2,
+      y: 2,
+      mouseDownX: 2,
+      mouseDownY: 2,
+      deltaX: 0,
+      deltaY: 0,
+      button: true
+    });
+
+    expect(up).to.equal(1);
+    expect(rightDown).to.equal(1);
+    expect(rightUp).to.equal(1);
+    expect(dbl).to.equal(1);
+    expect(move).to.equal(2);
+  });
+
+  it('draws cursor, fades, and overlays', function() {
+    const { canvas, ctx } = makeCanvas(200, 100);
+    const stage = new Stage(canvas);
+    stage.gameImgProps.display.initSize(40, 20);
+    stage.guiImgProps.display.initSize(40, 20);
+    stage.updateStageSize();
+
+    const drawCountBefore = ctx.drawCalls.length;
+    stage.setCursorSprite({
+      width: 4,
+      height: 4,
+      getData() { return new Uint8ClampedArray(4 * 4 * 4); }
+    });
+    stage.cursorX = 5;
+    stage.cursorY = 5;
+    stage.drawCursor();
+    expect(ctx.drawCalls.length).to.equal(drawCountBefore + 1);
+
+    stage.setCursorSprite(null);
+    expect(stage.cursorCanvas).to.equal(null);
+    const drawCountAfter = ctx.drawCalls.length;
+    stage.drawCursor();
+    expect(ctx.drawCalls.length).to.equal(drawCountAfter);
+
+    stage.startFadeOut();
+    now += 2400;
+    stage._updateFadeState(now);
+    expect(stage.fadeAlpha).to.equal(1);
+
+    let antsCalled = 0;
+    setDependency('drawMarchingAntRect', () => { antsCalled += 1; });
+
+    stage.startOverlayFade('rgba(1,2,3,0.5)', { x: 0, y: 0, width: 4, height: 4 }, 2);
+    stage.draw(stage.gameImgProps, stage.gameImgProps.display.getImageData());
+    expect(antsCalled).to.equal(1);
+
+    stage.overlayTimer = 1;
+    stage.startOverlayFade('rgba(1,2,3,0.5)', { x: 0, y: 0, width: 4, height: 4 }, 2);
+    now += 2400;
+    stage._updateFadeState(now);
+    expect(stage.overlayAlpha).to.equal(0);
+    expect(stage.overlayRect).to.equal(null);
+
+    stage.fadeTimer = 1;
+    stage.overlayTimer = 1;
+    stage.resetFade();
+    expect(stage.fadeTimer).to.equal(0);
+    expect(stage.overlayTimer).to.equal(0);
+  });
+
+  it('handles missing cursor canvas APIs safely', function() {
+    const { canvas } = makeCanvas(200, 100);
+    const stage = new Stage(canvas);
+    const originalDocument = globalThis.document;
+    globalThis.document = undefined;
+    expect(() => stage.setCursorSprite({
+      width: 4,
+      height: 4,
+      getData() { return new Uint8ClampedArray(4 * 4 * 4); }
+    })).to.not.throw();
+    expect(stage.cursorCanvas).to.equal(null);
+    globalThis.document = originalDocument;
+  });
+
+  it('keeps cursor rendered when static and redraws when it moves', function() {
+    const { canvas } = makeCanvas(200, 100);
+    const stage = new Stage(canvas);
+    stage.gameImgProps.display.initSize(40, 20);
+    stage.updateStageSize();
+
+    let clearCalls = 0;
+    let drawCalls = 0;
+    let cursorCalls = 0;
+    const originalClear = stage.clear;
+    const originalDraw = stage.draw;
+    const originalDrawCursor = stage.drawCursor;
+    stage.clear = (...args) => {
+      clearCalls += 1;
+      return originalClear.call(stage, ...args);
+    };
+    stage.draw = (...args) => {
+      drawCalls += 1;
+      return originalDraw.call(stage, ...args);
+    };
+    stage.drawCursor = () => {
+      cursorCalls += 1;
+      return originalDrawCursor.call(stage);
+    };
+
+    stage.setCursorSprite({
+      width: 4,
+      height: 4,
+      getData() { return new Uint8ClampedArray(4 * 4 * 4); }
+    });
+    stage.cursorX = 5;
+    stage.cursorY = 5;
+    stage.redraw();
+    expect(clearCalls).to.be.greaterThan(0);
+    expect(cursorCalls).to.equal(1);
+
+    const fullClearCalls = clearCalls;
+    stage.redraw();
+    expect(cursorCalls).to.equal(1);
+    expect(clearCalls).to.equal(fullClearCalls);
+
+    stage.cursorX = 8;
+    stage.cursorY = 8;
+    stage.redraw();
+    expect(cursorCalls).to.equal(2);
+    expect(clearCalls).to.be.greaterThan(fullClearCalls);
+    expect(drawCalls).to.be.at.least(0);
+  });
+
+  it('forces redraw when cursor sprite changes at a fixed position', function() {
+    const { canvas } = makeCanvas(200, 100);
+    const stage = new Stage(canvas);
+    stage.gameImgProps.display.initSize(40, 20);
+    stage.updateStageSize();
+
+    let clearCalls = 0;
+    const originalClear = stage.clear;
+    stage.clear = (...args) => {
+      clearCalls += 1;
+      return originalClear.call(stage, ...args);
+    };
+
+    stage.cursorX = 5;
+    stage.cursorY = 5;
+    stage.setCursorSprite({
+      width: 4,
+      height: 4,
+      getData() { return new Uint8ClampedArray(4 * 4 * 4); }
+    });
+    stage.redraw();
+    const baselineClearCalls = clearCalls;
+
+    stage.setCursorSprite({
+      width: 4,
+      height: 4,
+      getData() { return new Uint8ClampedArray(4 * 4 * 4); }
+    });
+    stage.redraw();
+    expect(clearCalls).to.be.greaterThan(baselineClearCalls);
+  });
+
+  it('forces a redraw when cursor visibility toggles without setter', function() {
+    const { canvas } = makeCanvas(200, 100);
+    const stage = new Stage(canvas);
+    stage.gameImgProps.display.initSize(40, 20);
+    stage.updateStageSize();
+
+    let clearCalls = 0;
+    const originalClear = stage.clear;
+    stage.clear = (...args) => {
+      clearCalls += 1;
+      return originalClear.call(stage, ...args);
+    };
+
+    stage.setCursorSprite({
+      width: 4,
+      height: 4,
+      getData() { return new Uint8ClampedArray(4 * 4 * 4); }
+    });
+    stage.redraw();
+    const baselineClearCalls = clearCalls;
+
+    stage.cursorCanvas = null;
+    stage.redraw();
+    expect(clearCalls).to.be.greaterThan(baselineClearCalls);
+  });
+
+  it('forces a redraw when overlay visibility toggles without dirtying overlay planes', function() {
+    const { canvas } = makeCanvas(200, 100);
+    const stage = new Stage(canvas);
+    stage.gameImgProps.display.initSize(40, 20);
+    stage.updateStageSize();
+
+    let clearCalls = 0;
+    const originalClear = stage.clear;
+    stage.clear = (...args) => {
+      clearCalls += 1;
+      return originalClear.call(stage, ...args);
+    };
+
+    const overlayDisplay = stage.getGameOverlayDisplay();
+    overlayDisplay.clear(0x00000000);
+    overlayDisplay.drawMarchingAntRect(1, 1, 6, 6, 2, 0);
+    stage.setGameOverlayVisible(true);
+    stage.redraw();
+    const baselineClearCalls = clearCalls;
+
+    stage.setGameOverlayVisible(false);
+    stage.redraw();
+
+    expect(stage.gameOverlayImgProps.display).to.equal(overlayDisplay);
+    expect(clearCalls).to.be.greaterThan(baselineClearCalls);
+  });
+
+  it('recycles consumed dirty-rect buffers after drawing', function() {
+    const { canvas } = makeCanvas(200, 100);
+    const stage = new Stage(canvas);
+    stage.gameImgProps.display.initSize(40, 20);
+    stage.updateStageSize();
+
+    const consumed = [{ x: 1, y: 2, width: 3, height: 4 }];
+    let released = null;
+    stage.gameImgProps.display.consumeDirtyRects = () => consumed;
+    stage.gameImgProps.display.releaseConsumedDirtyRects = (rects) => { released = rects; };
+
+    stage.draw(stage.gameImgProps, stage.gameImgProps.display.getImageData());
+    expect(released).to.equal(consumed);
+  });
+
+  it('keeps dirty-rect descriptors stable during draw blits', function() {
+    const { canvas } = makeCanvas(200, 100);
+    const stage = new Stage(canvas);
+    stage.gameImgProps.display.initSize(40, 20);
+    stage.updateStageSize();
+
+    const consumed = [
+      { x: 1, y: 2, width: 3, height: 4 },
+      { x: 8, y: 6, width: 5, height: 2 }
+    ];
+    const references = consumed.slice();
+    const before = consumed.map((rect) => ({ ...rect }));
+    stage.gameImgProps.display.consumeDirtyTiles = () => undefined;
+    stage.gameImgProps.display.consumeDirtyRects = () => consumed;
+    stage.gameImgProps.display.releaseConsumedDirtyRects = () => {};
+
+    stage.draw(stage.gameImgProps, stage.gameImgProps.display.getImageData());
+
+    expect(consumed).to.deep.equal(before);
+    expect(consumed[0]).to.equal(references[0]);
+    expect(consumed[1]).to.equal(references[1]);
+  });
+});
diff --git a/test/render/stage.02-stage.test.js b/test/render/stage.02-stage.test.js
new file mode 100644
index 00000000..5bbedaca
--- /dev/null
+++ b/test/render/stage.02-stage.test.js
@@ -0,0 +1,390 @@
+import { expect } from 'chai';
+import { Stage } from '../../js/render/Stage.js';
+import { ViewPoint } from '../../js/render/ViewPoint.js';
+import { setDependency, resetDependencies, useGlobalLemmings, withGlobalLemmings } from '../helpers/lemmings.js';
+
+const makeContext = () => {
+  const ctx = {
+    canvas: null,
+    imageSmoothingEnabled: false,
+    globalAlpha: 1,
+    fillStyle: '',
+    putCalls: [],
+    drawCalls: [],
+    fillCalls: [],
+    textCalls: [],
+    createImageData(width, height) {
+      return { width, height, data: new Uint8ClampedArray(width * height * 4) };
+    },
+    putImageData(img, x, y) {
+      this.putCalls.push({ img, x, y });
+    },
+    getImageData(x, y, width, height) {
+      return { width, height, data: new Uint8ClampedArray(width * height * 4) };
+    },
+    fillRect(x, y, width, height) {
+      this.fillCalls.push({ x, y, width, height });
+    },
+    fillText(text, x, y) {
+      this.textCalls.push({ text, x, y });
+    },
+    drawImage(...args) {
+      this.drawCalls.push(args);
+    }
+  };
+  return ctx;
+};
+
+const makeCanvas = (width = 320, height = 200) => {
+  const ctx = makeContext();
+  const canvas = {
+    width,
+    height,
+    style: {},
+    getContext() { return ctx; },
+    addEventListener() {},
+    removeEventListener() {}
+  };
+  ctx.canvas = canvas;
+  return { canvas, ctx };
+};
+
+describe('Stage', function() {
+  const originalWindow = globalThis.window;
+
+  const originalDocument = globalThis.document;
+
+  const originalImageData = globalThis.ImageData;
+
+  const originalPerformance = globalThis.performance;
+
+  useGlobalLemmings({});
+
+  let now = 0;
+
+  beforeEach(function() {
+    now = 0;
+    globalThis.document = {
+      createElement() {
+        return makeCanvas(10, 10).canvas;
+      }
+    };
+    globalThis.window = {
+      requestAnimationFrame() { return 1; },
+      cancelAnimationFrame() {}
+    };
+    globalThis.ImageData = class {
+      constructor(data, width, height) {
+        this.data = data;
+        this.width = width;
+        this.height = height;
+      }
+    };
+    globalThis.performance = {
+      now: () => {
+        now += 1;
+        return now;
+      }
+    };
+  });
+
+  afterEach(function() {
+    resetDependencies();
+    globalThis.window = originalWindow;
+    globalThis.document = originalDocument;
+    globalThis.ImageData = originalImageData;
+    globalThis.performance = originalPerformance;
+  });
+
+  it('recycles consumed dirty-tile buffers after drawing', function() {
+    const { canvas } = makeCanvas(200, 100);
+    const stage = new Stage(canvas);
+    stage.gameImgProps.display.initSize(40, 20);
+    stage.updateStageSize();
+
+    const consumedTiles = [{ x: 0, y: 0, width: 4, height: 4 }];
+    let releasedTiles = null;
+    stage.gameImgProps.display.consumeDirtyTiles = () => consumedTiles;
+    stage.gameImgProps.display.releaseConsumedDirtyTiles = (tiles) => { releasedTiles = tiles; };
+    stage.gameImgProps.display.consumeDirtyRects = () => [];
+
+    stage.draw(stage.gameImgProps, stage.gameImgProps.display.getImageData());
+    expect(releasedTiles).to.equal(consumedTiles);
+  });
+
+  it('falls back to dirty-rect blits when tile updates are empty', function() {
+    const { canvas } = makeCanvas(200, 100);
+    const stage = new Stage(canvas);
+    stage.gameImgProps.display.initSize(40, 20);
+    stage.updateStageSize();
+
+    const consumedRects = [{ x: 2, y: 3, width: 4, height: 5 }];
+    stage.gameImgProps.display.consumeDirtyTiles = () => [];
+    stage.gameImgProps.display.consumeDirtyRects = () => consumedRects;
+    stage.gameImgProps.display.releaseConsumedDirtyRects = () => {};
+
+    const displayCtx = stage.gameImgProps.ctx;
+    let putCount = 0;
+    const originalPut = displayCtx.putImageData.bind(displayCtx);
+    displayCtx.putImageData = (...args) => {
+      putCount += 1;
+      return originalPut(...args);
+    };
+
+    stage.draw(stage.gameImgProps, stage.gameImgProps.display.getImageData());
+    expect(putCount).to.equal(1);
+  });
+
+  it('forces full blits when cumulative frame damage crosses the region threshold', function() {
+    const { canvas } = makeCanvas(200, 100);
+    const stage = new Stage(canvas);
+    stage.gameImgProps.display.initSize(40, 20);
+    stage.updateStageSize();
+
+    const consumedRects = [
+      { x: 1, y: 1, width: 2, height: 2 },
+      { x: 5, y: 5, width: 2, height: 2 }
+    ];
+    stage.gameImgProps.display.consumeDirtyTiles = () => undefined;
+    stage.gameImgProps.display.consumeDirtyRects = () => consumedRects;
+    stage.gameImgProps.display.releaseConsumedDirtyRects = () => {};
+    stage._frameDamageStats = {
+      regionCount: 47,
+      dirtyArea: 0,
+      fullArea: 40 * 20,
+      uploadCalls: 0,
+      fullBlitCount: 0,
+      tileUpdateCount: 0
+    };
+
+    const putArgs = [];
+    stage.gameImgProps.ctx.putImageData = (...args) => {
+      putArgs.push(args);
+    };
+
+    stage.draw(stage.gameImgProps, stage.gameImgProps.display.getImageData());
+    expect(putArgs).to.have.length(1);
+    expect(putArgs[0]).to.have.length(3);
+    expect(stage._frameDamageStats.fullBlitCount).to.equal(1);
+  });
+
+  it('uses a single union blit when offscreen-present mode is active', function() {
+    const { canvas } = makeCanvas(200, 100);
+    const stage = new Stage(canvas);
+    stage.gameImgProps.display.initSize(40, 20);
+    stage.updateStageSize();
+    stage._renderExperiments.offscreenPresentActive = true;
+
+    const consumedRects = [
+      { x: 0, y: 0, width: 10, height: 10 },
+      { x: 5, y: 5, width: 10, height: 10 }
+    ];
+    stage.gameImgProps.display.consumeDirtyTiles = () => undefined;
+    stage.gameImgProps.display.consumeDirtyRects = () => consumedRects;
+    stage.gameImgProps.display.releaseConsumedDirtyRects = () => {};
+    stage._frameDamageStats = {
+      regionCount: 0,
+      dirtyArea: 0,
+      fullArea: 40 * 20,
+      uploadCalls: 0,
+      fullBlitCount: 0,
+      tileUpdateCount: 0
+    };
+
+    const putArgs = [];
+    stage.gameImgProps.ctx.putImageData = (...args) => {
+      putArgs.push(args);
+    };
+
+    stage.draw(stage.gameImgProps, stage.gameImgProps.display.getImageData());
+    expect(putArgs).to.have.length(1);
+    expect(putArgs[0]).to.have.length(7);
+    expect(stage._frameDamageStats.uploadCalls).to.equal(1);
+  });
+
+  it('rolls back offscreen-present mode when union blits fail at runtime', function() {
+    const { canvas } = makeCanvas(200, 100);
+    const stage = new Stage(canvas);
+    stage.gameImgProps.display.initSize(40, 20);
+    stage.updateStageSize();
+    stage._renderExperiments.offscreenPresentActive = true;
+
+    const consumedRects = [
+      { x: 0, y: 0, width: 10, height: 10 },
+      { x: 5, y: 5, width: 10, height: 10 }
+    ];
+    stage.gameImgProps.display.consumeDirtyTiles = () => undefined;
+    stage.gameImgProps.display.consumeDirtyRects = () => consumedRects;
+    stage.gameImgProps.display.releaseConsumedDirtyRects = () => {};
+    stage._frameDamageStats = {
+      regionCount: 0,
+      dirtyArea: 0,
+      fullArea: 40 * 20,
+      uploadCalls: 0,
+      fullBlitCount: 0,
+      tileUpdateCount: 0
+    };
+
+    let calls = 0;
+    stage.gameImgProps.ctx.putImageData = () => {
+      calls += 1;
+      if (calls === 1) {
+        throw new Error('present failed');
+      }
+    };
+
+    stage.draw(stage.gameImgProps, stage.gameImgProps.display.getImageData());
+    expect(calls).to.equal(consumedRects.length + 1);
+    expect(stage._renderExperiments.offscreenPresentActive).to.equal(false);
+    expect(stage._renderExperiments.rollbackReason).to.equal('offscreen_present_runtime_error');
+    expect(stage._frameDamageStats.uploadCalls).to.equal(consumedRects.length);
+  });
+
+  it('keeps updates visible when tile tracking is enabled after pending rect dirties', function() {
+    const { canvas } = makeCanvas(200, 100);
+    const stage = new Stage(canvas);
+    stage.gameImgProps.display.initSize(40, 20);
+    stage.updateStageSize();
+
+    const display = stage.gameImgProps.display;
+    display.markDirtyRect(1, 1, 4, 4);
+    display.setDirtyTileSize(8);
+
+    const displayCtx = stage.gameImgProps.ctx;
+    let putCount = 0;
+    const originalPut = displayCtx.putImageData.bind(displayCtx);
+    displayCtx.putImageData = (...args) => {
+      putCount += 1;
+      return originalPut(...args);
+    };
+
+    stage.draw(stage.gameImgProps, display.getImageData());
+    expect(putCount).to.be.greaterThan(0);
+  });
+
+  it('composites dedicated overlay planes without mutating base display dirty state', function() {
+    const { canvas } = makeCanvas(200, 100);
+    const stage = new Stage(canvas);
+    stage.gameImgProps.display.initSize(40, 20);
+    stage.guiImgProps.display.initSize(40, 20);
+    stage.updateStageSize();
+    stage.redraw(true);
+    expect(stage.gameImgProps.display.hasPendingDirty()).to.equal(false);
+
+    const gameOverlay = stage.getGameOverlayDisplay();
+    gameOverlay.clear(0x00000000);
+    gameOverlay.drawMarchingAntRect(1, 1, 6, 6, 2, 0);
+    stage.setGameOverlayVisible(true);
+    stage.redraw();
+
+    expect(stage.gameImgProps.display.hasPendingDirty()).to.equal(false);
+    expect(stage.gameOverlayImgProps.display).to.equal(gameOverlay);
+  });
+
+  it('parses overlay colors with and without alpha', function() {
+    const { canvas } = makeCanvas(200, 100);
+    const stage = new Stage(canvas);
+    stage.startOverlayFade('rgb(1, 2, 3)', null, 1);
+    expect(stage.overlayDashColor >>> 0).to.equal(0xFF030201);
+    stage.startOverlayFade('rgba(300, -10, 7.4, 1.5)', null, 1);
+    expect(stage.overlayDashColor >>> 0).to.equal(0xFF0700FF);
+    stage.startOverlayFade('rgba(1,2,3,0.5)', null, 1);
+    expect(stage.overlayDashColor >>> 0).to.equal(0x80030201);
+    stage.startOverlayFade('invalid', null, 1);
+    expect(stage.overlayDashColor >>> 0).to.equal(0xFFFFFFFF);
+  });
+
+  it('reuses fallback overlay surfaces without getImageData churn', function() {
+    const { canvas, ctx } = makeCanvas(200, 100);
+    let getImageCalls = 0;
+    ctx.getImageData = (x, y, width, height) => {
+      getImageCalls += 1;
+      return { width, height, data: new Uint8ClampedArray(width * height * 4) };
+    };
+
+    const stage = new Stage(canvas);
+    stage.gameImgProps.display.initSize(40, 20);
+    stage.guiImgProps.display.initSize(40, 20);
+    stage.updateStageSize();
+    stage.overlayAlpha = 1;
+    stage.overlayColor = 'rgba(10,20,30,0.5)';
+    stage.overlayDashColor = 0xFF030201;
+    stage.overlayDashLen = 2;
+    stage.overlayDashOffset = 1;
+    stage.overlayRect = { x: 4, y: 5, width: 10, height: 6 };
+
+    stage.draw(stage.gameImgProps, stage.gameImgProps.display.getImageData());
+    const firstFallback = stage._overlayFallbackImageData;
+    stage.overlayDashOffset = 2;
+    stage.draw(stage.gameImgProps, stage.gameImgProps.display.getImageData());
+
+    expect(getImageCalls).to.equal(0);
+    expect(stage._overlayFallbackImageData).to.equal(firstFallback);
+  });
+
+  it('renders an opt-in perf overlay and reports stage perf snapshots', function() {
+    const { canvas, ctx } = makeCanvas(200, 100);
+    const stage = new Stage(canvas);
+    stage.gameImgProps.display.initSize(40, 20);
+    stage.guiImgProps.display.initSize(40, 20);
+    stage.updateStageSize();
+
+    stage.setPerfOverlay(true, () => ({ lines: ['custom metric'] }));
+    stage.redraw();
+
+    const perf = stage.getPerfSnapshot();
+    expect(perf.frameCount).to.be.greaterThan(0);
+    expect(perf.frameMs).to.be.greaterThan(0);
+    expect(perf.frame.p95).to.be.greaterThan(0);
+    expect(perf.lastDamage.uploadCalls).to.be.at.least(0);
+    expect(perf.lastAllocations.rectListCreated).to.be.at.least(0);
+    expect(ctx.textCalls.some(call => call.text.includes('frame'))).to.equal(true);
+    expect(ctx.textCalls.some(call => call.text.includes('custom metric'))).to.equal(true);
+  });
+
+  it('tracks render experiment flags and rollback status', function() {
+    const { canvas } = makeCanvas(200, 100);
+    const stage = new Stage(canvas);
+    stage.setRenderExperimentFlags({
+      offscreenPresent: true,
+      workerOffscreen: true
+    });
+    const status = stage.getRenderExperimentStatus();
+    expect(status.offscreenPresentRequested).to.equal(true);
+    expect(status.workerOffscreenRequested).to.equal(true);
+    expect(typeof status.offscreenPresentActive).to.equal('boolean');
+    expect(typeof status.workerOffscreenActive).to.equal('boolean');
+  });
+
+  it('skips overlay layout sync when overlay planes are unused', function() {
+    const { canvas } = makeCanvas(200, 100);
+    const stage = new Stage(canvas);
+    stage.gameImgProps.display.initSize(40, 20);
+    stage.guiImgProps.display.initSize(40, 20);
+    stage.updateStageSize();
+
+    let layoutSyncCalls = 0;
+    let sizeSyncCalls = 0;
+    const originalLayoutSync = stage._syncOverlayLayout.bind(stage);
+    const originalSizeSync = stage._syncOverlayDisplaySize.bind(stage);
+    stage._syncOverlayLayout = () => {
+      layoutSyncCalls += 1;
+      return originalLayoutSync();
+    };
+    stage._syncOverlayDisplaySize = (...args) => {
+      sizeSyncCalls += 1;
+      return originalSizeSync(...args);
+    };
+
+    stage.redraw();
+    expect(layoutSyncCalls).to.equal(0);
+    expect(sizeSyncCalls).to.equal(0);
+
+    stage.getGameOverlayDisplay();
+    layoutSyncCalls = 0;
+    sizeSyncCalls = 0;
+    stage.redraw();
+    expect(layoutSyncCalls).to.be.greaterThan(0);
+    expect(sizeSyncCalls).to.be.greaterThan(0);
+  });
+});
diff --git a/test/render/stage.test.js b/test/render/stage.03-stage.test.js
similarity index 52%
rename from test/render/stage.test.js
rename to test/render/stage.03-stage.test.js
index ed7d2942..4f746171 100644
--- a/test/render/stage.test.js
+++ b/test/render/stage.03-stage.test.js
@@ -12,6 +12,7 @@ const makeContext = () => {
     putCalls: [],
     drawCalls: [],
     fillCalls: [],
+    textCalls: [],
     createImageData(width, height) {
       return { width, height, data: new Uint8ClampedArray(width * height * 4) };
     },
@@ -24,6 +25,9 @@ const makeContext = () => {
     fillRect(x, y, width, height) {
       this.fillCalls.push({ x, y, width, height });
     },
+    fillText(text, x, y) {
+      this.textCalls.push({ text, x, y });
+    },
     drawImage(...args) {
       this.drawCalls.push(args);
     }
@@ -47,16 +51,19 @@ const makeCanvas = (width = 320, height = 200) => {
 
 describe('Stage', function() {
   const originalWindow = globalThis.window;
+
   const originalDocument = globalThis.document;
+
   const originalImageData = globalThis.ImageData;
-  const originalSetInterval = globalThis.setInterval;
-  const originalClearInterval = globalThis.clearInterval;
+
+  const originalPerformance = globalThis.performance;
+
   useGlobalLemmings({});
 
-  let intervalCbs = [];
+  let now = 0;
 
   beforeEach(function() {
-    intervalCbs = [];
+    now = 0;
     globalThis.document = {
       createElement() {
         return makeCanvas(10, 10).canvas;
@@ -73,11 +80,12 @@ describe('Stage', function() {
         this.height = height;
       }
     };
-    globalThis.setInterval = (cb) => {
-      intervalCbs.push(cb);
-      return intervalCbs.length;
+    globalThis.performance = {
+      now: () => {
+        now += 1;
+        return now;
+      }
     };
-    globalThis.clearInterval = () => {};
   });
 
   afterEach(function() {
@@ -85,171 +93,7 @@ describe('Stage', function() {
     globalThis.window = originalWindow;
     globalThis.document = originalDocument;
     globalThis.ImageData = originalImageData;
-    globalThis.setInterval = originalSetInterval;
-    globalThis.clearInterval = originalClearInterval;
-  });
-
-  it('routes pointer events and handles zoom', function() {
-    const { canvas } = makeCanvas(320, 200);
-    const stage = new Stage(canvas);
-    stage.gameImgProps.display.initSize(100, 50);
-    stage.guiImgProps.display.initSize(80, 20);
-    stage.updateStageSize();
-
-    let lastDown = null;
-    stage.gameImgProps.display.onMouseDown.on(pos => { lastDown = pos; });
-
-    stage.controller.onMouseDown.trigger({ x: 10, y: 10 });
-    expect(lastDown).to.not.equal(null);
-    stage.controller.onMouseDown.trigger({ x: 1000, y: 1000 });
-
-    let updateArgs = null;
-    stage.updateViewPoint = (...args) => { updateArgs = args; };
-    stage.controller.onMouseMove.trigger({
-      x: 12,
-      y: 12,
-      mouseDownX: 10,
-      mouseDownY: 10,
-      deltaX: 3,
-      deltaY: -2,
-      button: true
-    });
-    expect(updateArgs).to.not.equal(null);
-
-    updateArgs = null;
-    stage.controller.onZoom.trigger({ x: 20, y: 10, deltaZoom: 5, velocity: 1 });
-    expect(updateArgs).to.not.equal(null);
-
-    updateArgs = null;
-    stage.gameImgProps.display = null;
-    stage.controller.onZoom.trigger({ x: 20, y: 10, deltaZoom: 5, velocity: 1 });
-    expect(updateArgs).to.equal(null);
-  });
-
-  it('routes right clicks and hover events', function() {
-    const { canvas } = makeCanvas(320, 200);
-    const stage = new Stage(canvas);
-    stage.gameImgProps.display.initSize(100, 50);
-    stage.guiImgProps.display.initSize(80, 20);
-    stage.updateStageSize();
-
-    let up = 0;
-    let rightDown = 0;
-    let rightUp = 0;
-    let dbl = 0;
-    let move = 0;
-    stage.gameImgProps.display.onMouseUp.on(() => { up += 1; });
-    stage.gameImgProps.display.onMouseRightDown.on(() => { rightDown += 1; });
-    stage.gameImgProps.display.onMouseRightUp.on(() => { rightUp += 1; });
-    stage.gameImgProps.display.onDoubleClick.on(() => { dbl += 1; });
-    stage.gameImgProps.display.onMouseMove.on(() => { move += 1; });
-
-    stage.controller.onMouseUp.trigger({ x: 1, y: 1 });
-    stage.controller.onMouseUp.trigger({ x: 1000, y: 1000 });
-    stage.controller.onMouseRightDown.trigger({ x: 1, y: 1 });
-    stage.controller.onMouseRightDown.trigger({ x: 1000, y: 1000 });
-    stage.controller.onMouseRightUp.trigger({ x: 1, y: 1 });
-    stage.controller.onMouseRightUp.trigger({ x: 1000, y: 1000 });
-    stage.controller.onDoubleClick.trigger({ x: 1, y: 1 });
-    stage.controller.onDoubleClick.trigger({ x: 1000, y: 1000 });
-    stage.controller.onMouseMove.trigger({ x: 2, y: 2, button: false });
-    stage.controller.onMouseMove.trigger({ x: 1000, y: 1000, button: false });
-    stage.controller.onMouseMove.trigger({
-      x: 2,
-      y: 2,
-      mouseDownX: 1000,
-      mouseDownY: 1000,
-      deltaX: 0,
-      deltaY: 0,
-      button: true
-    });
-    stage.panEnabled = false;
-    stage.controller.onMouseMove.trigger({
-      x: 2,
-      y: 2,
-      mouseDownX: 2,
-      mouseDownY: 2,
-      deltaX: 0,
-      deltaY: 0,
-      button: true
-    });
-
-    expect(up).to.equal(1);
-    expect(rightDown).to.equal(1);
-    expect(rightUp).to.equal(1);
-    expect(dbl).to.equal(1);
-    expect(move).to.equal(2);
-  });
-
-  it('draws cursor, fades, and overlays', function() {
-    const { canvas, ctx } = makeCanvas(200, 100);
-    const stage = new Stage(canvas);
-    stage.gameImgProps.display.initSize(40, 20);
-    stage.guiImgProps.display.initSize(40, 20);
-    stage.updateStageSize();
-
-    const drawCountBefore = ctx.drawCalls.length;
-    stage.setCursorSprite({
-      width: 4,
-      height: 4,
-      getData() { return new Uint8ClampedArray(4 * 4 * 4); }
-    });
-    stage.cursorX = 5;
-    stage.cursorY = 5;
-    stage.drawCursor();
-    expect(ctx.drawCalls.length).to.equal(drawCountBefore + 1);
-
-    stage.setCursorSprite(null);
-    expect(stage.cursorCanvas).to.equal(null);
-    const drawCountAfter = ctx.drawCalls.length;
-    stage.drawCursor();
-    expect(ctx.drawCalls.length).to.equal(drawCountAfter);
-
-    stage.startFadeOut();
-    for (let i = 0; i < 60; i++) intervalCbs[0]();
-    expect(stage.fadeAlpha).to.equal(1);
-
-    let antsCalled = 0;
-    setDependency('drawMarchingAntRect', () => { antsCalled += 1; });
-
-    stage.startOverlayFade('rgba(1,2,3,0.5)', { x: 0, y: 0, width: 4, height: 4 }, 2);
-    stage.draw(stage.gameImgProps, stage.gameImgProps.display.getImageData());
-    expect(antsCalled).to.equal(1);
-
-    stage.overlayTimer = 1;
-    stage.startOverlayFade('rgba(1,2,3,0.5)', { x: 0, y: 0, width: 4, height: 4 }, 2);
-    for (let i = 0; i < 60; i++) intervalCbs[1]();
-    expect(stage.overlayAlpha).to.equal(0);
-    expect(stage.overlayRect).to.equal(null);
-
-    stage.fadeTimer = 1;
-    stage.overlayTimer = 1;
-    stage.resetFade();
-    expect(stage.fadeTimer).to.equal(0);
-    expect(stage.overlayTimer).to.equal(0);
-  });
-
-  it('parses overlay colors with and without alpha', function() {
-    const { canvas } = makeCanvas(200, 100);
-    const stage = new Stage(canvas);
-    const originalExec = RegExp.prototype.exec;
-    RegExp.prototype.exec = function(str) {
-      if (
-        str === 'rgb(1,2,3)'
-        && this.source === 'rgba?\\((\\d+),(\\d+),(\\d+),(\\d*(?:\\.\\d+)?)\\)'
-      ) {
-        return ['rgb(1,2,3)', '1', '2', '3'];
-      }
-      return originalExec.call(this, str);
-    };
-    try {
-      stage.startOverlayFade('rgb(1,2,3)', null, 1);
-      expect(stage.overlayDashColor >>> 0).to.equal(0xFF030201);
-    } finally {
-      RegExp.prototype.exec = originalExec;
-    }
-    stage.startOverlayFade('invalid', null, 1);
-    expect(stage.overlayDashColor >>> 0).to.equal(0xFFFFFFFF);
+    globalThis.performance = originalPerformance;
   });
 
   it('clamps viewports and snaps scales', function() {
@@ -271,18 +115,21 @@ describe('Stage', function() {
     stage._rawScale = 1.5;
     let applied = null;
     let redraws = 0;
+    const redrawFlags = [];
     const originalApply = stage.applyViewport;
     stage.applyViewport = (...args) => { applied = args; };
-    stage.redraw = () => { redraws += 1; };
+    stage.redraw = (forceComposite = false) => {
+      redraws += 1;
+      redrawFlags.push(forceComposite);
+    };
     stage.setGameViewPointPosition(5, 6, { preserveScale: true });
     expect(applied[3]).to.equal(1.5);
     expect(redraws).to.equal(1);
 
-    withGlobalLemmings({ scale: 3 }, () => {
-      stage.applyViewport = originalApply;
-      stage.setGameViewPointPosition(2, 3);
-      expect(stage.gameImgProps.viewPoint.scale).to.equal(stage.snapScale(3));
-    });
+    stage.applyViewport = originalApply;
+    stage.setScaleProvider(() => 3);
+    stage.setGameViewPointPosition(2, 3);
+    expect(stage.gameImgProps.viewPoint.scale).to.equal(stage.snapScale(3));
 
     stage._rawScale = NaN;
     stage.setGameViewPointPosition(4, 5, { preserveScale: true });
@@ -292,15 +139,24 @@ describe('Stage', function() {
     stage.gameImgProps.viewPoint.scale = 0;
     stage.setGameViewPointPosition(4, Number.NaN, { preserveScale: true });
     expect(stage._rawScale).to.equal(1);
+    expect(Number.isFinite(stage.gameImgProps.viewPoint.x)).to.equal(true);
+    expect(stage.gameImgProps.viewPoint.y).to.equal(0);
 
-    withGlobalLemmings({ scale: 0 }, () => {
+    stage.setGameViewPointPosition(Number.NaN, Number.NaN, { preserveScale: true });
+    expect(Number.isFinite(stage.gameImgProps.viewPoint.x)).to.equal(true);
+    expect(Number.isFinite(stage.gameImgProps.viewPoint.y)).to.equal(true);
+
+    withGlobalLemmings({ scale: 4 }, () => {
+      stage.setScaleProvider(null);
       stage.gameImgProps.display.worldDataSize = { width: 200, height: 100 };
       stage.gameImgProps.canvasViewportSize = { width: 100, height: 100 };
       stage.gameImgProps.viewPoint.scale = 2;
       stage.setGameViewPointPosition(7, 8);
+      expect(stage.gameImgProps.viewPoint.scale).to.equal(2);
       expect(stage.gameImgProps.viewPoint.x).to.equal(7);
       expect(stage.gameImgProps.viewPoint.y).to.equal(8);
     });
+    expect(redrawFlags.every((flag) => flag === true)).to.equal(true);
 
     stage.clampViewPoint(null);
     stage.clampViewPoint({ display: null });
@@ -335,6 +191,30 @@ describe('Stage', function() {
     expect(stage.guiImgProps.height).to.equal(0);
   });
 
+  it('skips resize redraw work when dimensions are unchanged and displays are clean', function() {
+    const { canvas } = makeCanvas(320, 200);
+    const stage = new Stage(canvas);
+    stage.gameImgProps.display.initSize(100, 50);
+    stage.guiImgProps.display.initSize(80, 20);
+    stage.updateStageSize();
+
+    let clears = 0;
+    let draws = 0;
+    stage.clear = () => { clears += 1; };
+    stage.draw = () => { draws += 1; };
+
+    globalThis.window.requestAnimationFrame = (cb) => { cb(); return 1; };
+    stage.scheduleUpdateStageSize();
+    expect(clears).to.equal(0);
+    expect(draws).to.equal(0);
+
+    stage._resizeRaf = 0;
+    stage.gameImgProps.display.markDirtyRect(0, 0, 1, 1);
+    stage.scheduleUpdateStageSize();
+    expect(clears).to.be.greaterThan(0);
+    expect(draws).to.be.greaterThan(0);
+  });
+
   it('normalizes invalid HUD scale and view offsets', function() {
     const { canvas } = makeCanvas(200, 100);
     const stage = new Stage(canvas);
@@ -367,6 +247,20 @@ describe('Stage', function() {
     expect(ctx.drawCalls.length).to.equal(drawCount + 1);
   });
 
+  it('returns early when draw image payload is invalid', function() {
+    const { canvas, ctx } = makeCanvas(100, 80);
+    const stage = new Stage(canvas);
+    stage.gameImgProps.display.initSize(20, 10);
+    stage.gameImgProps.canvasViewportSize = { width: 10, height: 10 };
+    stage.gameImgProps.width = 10;
+    stage.gameImgProps.height = 10;
+
+    const drawCount = ctx.drawCalls.length;
+    expect(() => stage.draw(stage.gameImgProps, null)).to.not.throw();
+    expect(() => stage.draw(stage.gameImgProps, { width: 0, height: 10 })).to.not.throw();
+    expect(ctx.drawCalls.length).to.equal(drawCount);
+  });
+
   it('updates the view point for pan and zoom', function() {
     const { canvas } = makeCanvas(200, 100);
     const stage = new Stage(canvas);
@@ -403,6 +297,73 @@ describe('Stage', function() {
     expect(last.y).to.equal(-3);
   });
 
+  it('updates view point safely when GUI display is disabled', function() {
+    const { canvas } = makeCanvas(200, 100);
+    const stage = new Stage(canvas);
+    stage.gameImgProps.display.initSize(100, 50);
+    stage.guiImgProps.display.initSize(80, 20);
+    stage.updateStageSize();
+    const cleared = [];
+    const drawn = [];
+    stage.clear = (image) => {
+      cleared.push(image === stage.guiImgProps ? 'gui' : 'game');
+    };
+    stage.draw = (image) => {
+      drawn.push(image === stage.guiImgProps ? 'gui' : 'game');
+    };
+    let guiReads = 0;
+    stage.guiImgProps.display.getImageData = () => {
+      guiReads += 1;
+      return null;
+    };
+    stage.setGuiEnabled(false);
+
+    expect(() => stage.updateViewPoint(stage.gameImgProps, 10, 10, 50)).to.not.throw();
+    expect(guiReads).to.equal(0);
+    expect(cleared.length).to.be.at.least(1);
+    expect(cleared.every((name) => name === 'game')).to.equal(true);
+    expect(drawn.length).to.be.at.least(1);
+    expect(drawn.every((name) => name === 'game')).to.equal(true);
+  });
+
+  it('keeps GUI display clean when panning the game viewport', function() {
+    const { canvas } = makeCanvas(200, 100);
+    const stage = new Stage(canvas);
+    stage.gameImgProps.display.initSize(100, 50);
+    stage.guiImgProps.display.initSize(80, 20);
+    stage.updateStageSize();
+    const cleared = [];
+    const drawn = [];
+    stage.clear = (image) => {
+      cleared.push(image === stage.guiImgProps ? 'gui' : 'game');
+    };
+    stage.draw = (image) => {
+      drawn.push(image === stage.guiImgProps ? 'gui' : 'game');
+    };
+    let guiReads = 0;
+    stage.guiImgProps.display.getImageData = () => {
+      guiReads += 1;
+      return null;
+    };
+
+    stage.updateViewPoint(stage.gameImgProps, 12, -8, 0);
+
+    expect(cleared).to.deep.equal(['game']);
+    expect(drawn).to.deep.equal(['game']);
+    expect(guiReads).to.equal(0);
+  });
+
+  it('updates view point when GUI display lacks getImageData', function() {
+    const { canvas } = makeCanvas(200, 100);
+    const stage = new Stage(canvas);
+    stage.gameImgProps.display.initSize(100, 50);
+    stage.guiImgProps.display = {};
+    stage.clear = () => {};
+    stage.draw = () => {};
+
+    expect(() => stage.updateViewPoint(stage.gameImgProps, 12, 8, 0)).to.not.throw();
+  });
+
   it('covers updateViewPoint defaults and snapScale clamps', function() {
     const { canvas } = makeCanvas(200, 100);
     const stage = new Stage(canvas);
@@ -448,109 +409,4 @@ describe('Stage', function() {
       Stage.prototype.clear = originalClear;
     }
   });
-
-  it('recenters scale changes and redraws both layers', function() {
-    const { canvas } = makeCanvas(200, 100);
-    const stage = new Stage(canvas);
-    stage.gameImgProps.display.initSize(100, 50);
-    stage.guiImgProps.display.initSize(80, 20);
-    stage.updateStageSize();
-    stage.gameImgProps.viewPoint.scale = 1;
-
-    let draws = 0;
-    let clears = 0;
-    let cursors = 0;
-    stage.draw = () => { draws += 1; };
-    stage.clear = () => { clears += 1; };
-    stage.drawCursor = () => { cursors += 1; };
-
-    stage.setGameViewPointPosition(10, 10);
-    expect(stage.gameImgProps.viewPoint.scale).to.equal(stage.snapScale(2));
-
-    draws = 0;
-    clears = 0;
-    cursors = 0;
-    stage.redraw();
-    expect(draws).to.equal(2);
-    expect(clears).to.equal(1);
-    expect(cursors).to.equal(1);
-  });
-
-  it('returns gui image hits and null misses', function() {
-    const { canvas } = makeCanvas(200, 100);
-    const stage = new Stage(canvas);
-    stage.gameImgProps.display.initSize(100, 50);
-    stage.guiImgProps.display.initSize(80, 20);
-    stage.updateStageSize();
-
-    const guiX = stage.guiImgProps.x + 1;
-    const guiY = stage.guiImgProps.y + 1;
-    expect(stage.getStageImageAt(guiX, guiY)).to.equal(stage.guiImgProps);
-    expect(stage.getStageImageAt(1000, 1000)).to.equal(null);
-  });
-
-  it('returns cached displays when available', function() {
-    const { canvas } = makeCanvas(200, 100);
-    const stage = new Stage(canvas);
-    const gameDisplay = stage.getGameDisplay();
-    const guiDisplay = stage.getGuiDisplay();
-    expect(stage.getGameDisplay()).to.equal(gameDisplay);
-    expect(stage.getGuiDisplay()).to.equal(guiDisplay);
-  });
-
-  it('uses default overlay rect and reports game view rect', function() {
-    const { canvas, ctx } = makeCanvas(120, 90);
-    const stage = new Stage(canvas);
-    stage.gameImgProps.display.initSize(60, 30);
-    stage.guiImgProps.display.initSize(60, 10);
-    stage.updateStageSize();
-
-    stage.overlayAlpha = 0.5;
-    stage.overlayColor = 'rgba(10,20,30,0.5)';
-    stage.overlayRect = null;
-    stage.overlayDashLen = 0;
-    stage.draw(stage.gameImgProps, stage.gameImgProps.display.getImageData());
-    expect(ctx.fillCalls.length).to.be.greaterThan(0);
-
-    stage.gameImgProps.viewPoint.scale = 2;
-    stage.gameImgProps.canvasViewportSize = { width: 40, height: 20 };
-    const rect = stage.getGameViewRect();
-    expect(rect.w).to.equal(20);
-    expect(rect.h).to.equal(10);
-  });
-
-  it('resets overlays and disposes stage resources', function() {
-    const { canvas } = makeCanvas(120, 90);
-    const stage = new Stage(canvas);
-
-    stage.overlayAlpha = 1;
-    stage.overlayRect = { x: 1, y: 2, width: 3, height: 4 };
-    stage.overlayDashLen = 2;
-    stage.overlayTimer = 1;
-    stage.resetOverlayFade();
-    expect(stage.overlayAlpha).to.equal(0);
-    expect(stage.overlayRect).to.equal(null);
-    expect(stage.overlayDashLen).to.equal(0);
-    expect(stage.overlayTimer).to.equal(0);
-
-    let cancelled = 0;
-    globalThis.window.cancelAnimationFrame = () => { cancelled += 1; };
-    const gameDisplay = { called: 0, dispose() { this.called += 1; } };
-    const guiDisplay = { called: 0, dispose() { this.called += 1; } };
-    const controller = { called: 0, dispose() { this.called += 1; } };
-    stage.gameImgProps.display = gameDisplay;
-    stage.guiImgProps.display = guiDisplay;
-    stage.controller = controller;
-    stage._resizeRaf = 123;
-
-    stage.dispose();
-
-    expect(cancelled).to.equal(1);
-    expect(gameDisplay.called).to.equal(1);
-    expect(guiDisplay.called).to.equal(1);
-    expect(controller.called).to.equal(1);
-    expect(stage.gameImgProps).to.equal(null);
-    expect(stage.guiImgProps).to.equal(null);
-    expect(stage.stageCav).to.equal(null);
-  });
 });
diff --git a/test/render/stage.04-stage.test.js b/test/render/stage.04-stage.test.js
new file mode 100644
index 00000000..0827dc2a
--- /dev/null
+++ b/test/render/stage.04-stage.test.js
@@ -0,0 +1,237 @@
+import { expect } from 'chai';
+import { Stage } from '../../js/render/Stage.js';
+import { ViewPoint } from '../../js/render/ViewPoint.js';
+import { setDependency, resetDependencies, useGlobalLemmings, withGlobalLemmings } from '../helpers/lemmings.js';
+
+const makeContext = () => {
+  const ctx = {
+    canvas: null,
+    imageSmoothingEnabled: false,
+    globalAlpha: 1,
+    fillStyle: '',
+    putCalls: [],
+    drawCalls: [],
+    fillCalls: [],
+    textCalls: [],
+    createImageData(width, height) {
+      return { width, height, data: new Uint8ClampedArray(width * height * 4) };
+    },
+    putImageData(img, x, y) {
+      this.putCalls.push({ img, x, y });
+    },
+    getImageData(x, y, width, height) {
+      return { width, height, data: new Uint8ClampedArray(width * height * 4) };
+    },
+    fillRect(x, y, width, height) {
+      this.fillCalls.push({ x, y, width, height });
+    },
+    fillText(text, x, y) {
+      this.textCalls.push({ text, x, y });
+    },
+    drawImage(...args) {
+      this.drawCalls.push(args);
+    }
+  };
+  return ctx;
+};
+
+const makeCanvas = (width = 320, height = 200) => {
+  const ctx = makeContext();
+  const canvas = {
+    width,
+    height,
+    style: {},
+    getContext() { return ctx; },
+    addEventListener() {},
+    removeEventListener() {}
+  };
+  ctx.canvas = canvas;
+  return { canvas, ctx };
+};
+
+describe('Stage', function() {
+  const originalWindow = globalThis.window;
+
+  const originalDocument = globalThis.document;
+
+  const originalImageData = globalThis.ImageData;
+
+  const originalPerformance = globalThis.performance;
+
+  useGlobalLemmings({});
+
+  let now = 0;
+
+  beforeEach(function() {
+    now = 0;
+    globalThis.document = {
+      createElement() {
+        return makeCanvas(10, 10).canvas;
+      }
+    };
+    globalThis.window = {
+      requestAnimationFrame() { return 1; },
+      cancelAnimationFrame() {}
+    };
+    globalThis.ImageData = class {
+      constructor(data, width, height) {
+        this.data = data;
+        this.width = width;
+        this.height = height;
+      }
+    };
+    globalThis.performance = {
+      now: () => {
+        now += 1;
+        return now;
+      }
+    };
+  });
+
+  afterEach(function() {
+    resetDependencies();
+    globalThis.window = originalWindow;
+    globalThis.document = originalDocument;
+    globalThis.ImageData = originalImageData;
+    globalThis.performance = originalPerformance;
+  });
+
+  it('recenters scale changes and skips no-op redraw unless forced', function() {
+    const { canvas } = makeCanvas(200, 100);
+    const stage = new Stage(canvas);
+    stage.gameImgProps.display.initSize(100, 50);
+    stage.guiImgProps.display.initSize(80, 20);
+    stage.updateStageSize();
+    stage.gameImgProps.viewPoint.scale = 1;
+
+    let draws = 0;
+    let clears = 0;
+    let cursors = 0;
+    stage.draw = () => { draws += 1; };
+    stage.clear = () => { clears += 1; };
+    stage.drawCursor = () => { cursors += 1; };
+
+    stage.setGameViewPointPosition(10, 10);
+    expect(stage.gameImgProps.viewPoint.scale).to.equal(stage.snapScale(2));
+
+    draws = 0;
+    clears = 0;
+    cursors = 0;
+    stage.redraw();
+    expect(draws).to.equal(0);
+    expect(clears).to.equal(0);
+    expect(cursors).to.equal(0);
+
+    stage.redraw(true);
+    expect(draws).to.equal(2);
+    expect(clears).to.equal(1);
+    expect(cursors).to.equal(0);
+  });
+
+  it('avoids redundant pre-clear when setting game view point', function() {
+    const { canvas } = makeCanvas(200, 100);
+    const stage = new Stage(canvas);
+    stage.gameImgProps.display.initSize(100, 50);
+    stage.guiImgProps.display.initSize(80, 20);
+    stage.updateStageSize();
+    let clears = 0;
+    stage.clear = () => { clears += 1; };
+    stage.redraw = () => {};
+
+    stage.setGameViewPointPosition(10, 10);
+
+    expect(clears).to.equal(0);
+  });
+
+  it('returns gui image hits and null misses', function() {
+    const { canvas } = makeCanvas(200, 100);
+    const stage = new Stage(canvas);
+    stage.gameImgProps.display.initSize(100, 50);
+    stage.guiImgProps.display.initSize(80, 20);
+    stage.updateStageSize();
+
+    const guiX = stage.guiImgProps.x + 1;
+    const guiY = stage.guiImgProps.y + 1;
+    expect(stage.getStageImageAt(guiX, guiY)).to.equal(stage.guiImgProps);
+    expect(stage.getStageImageAt(1000, 1000)).to.equal(null);
+  });
+
+  it('returns cached displays when available', function() {
+    const { canvas } = makeCanvas(200, 100);
+    const stage = new Stage(canvas);
+    const gameDisplay = stage.getGameDisplay();
+    const guiDisplay = stage.getGuiDisplay();
+    expect(stage.getGameDisplay()).to.equal(gameDisplay);
+    expect(stage.getGuiDisplay()).to.equal(guiDisplay);
+  });
+
+  it('uses default overlay rect and reports game view rect', function() {
+    const { canvas, ctx } = makeCanvas(120, 90);
+    const stage = new Stage(canvas);
+    stage.gameImgProps.display.initSize(60, 30);
+    stage.guiImgProps.display.initSize(60, 10);
+    stage.updateStageSize();
+
+    stage.overlayAlpha = 0.5;
+    stage.overlayColor = 'rgba(10,20,30,0.5)';
+    stage.overlayRect = null;
+    stage.overlayDashLen = 0;
+    stage.draw(stage.gameImgProps, stage.gameImgProps.display.getImageData());
+    expect(ctx.fillCalls.length).to.be.greaterThan(0);
+
+    stage.gameImgProps.viewPoint.scale = 2;
+    stage.gameImgProps.canvasViewportSize = { width: 40, height: 20 };
+    const rect = stage.getGameViewRect();
+    expect(rect.w).to.equal(20);
+    expect(rect.h).to.equal(10);
+  });
+
+  it('resets overlays and disposes stage resources', function() {
+    const { canvas } = makeCanvas(120, 90);
+    const stage = new Stage(canvas);
+
+    stage.overlayAlpha = 1;
+    stage.overlayRect = { x: 1, y: 2, width: 3, height: 4 };
+    stage.overlayDashLen = 2;
+    stage.overlayTimer = 1;
+    stage.resetOverlayFade();
+    expect(stage.overlayAlpha).to.equal(0);
+    expect(stage.overlayRect).to.equal(null);
+    expect(stage.overlayDashLen).to.equal(0);
+    expect(stage.overlayTimer).to.equal(0);
+
+    let cancelled = 0;
+    globalThis.window.cancelAnimationFrame = () => { cancelled += 1; };
+    const gameDisplay = { called: 0, dispose() { this.called += 1; } };
+    const guiDisplay = { called: 0, dispose() { this.called += 1; } };
+    const controller = { called: 0, dispose() { this.called += 1; } };
+    stage.gameImgProps.display = gameDisplay;
+    stage.guiImgProps.display = guiDisplay;
+    stage.controller = controller;
+    stage._resizeRaf = 123;
+
+    stage.dispose();
+
+    expect(cancelled).to.equal(1);
+    expect(gameDisplay.called).to.equal(1);
+    expect(guiDisplay.called).to.equal(1);
+    expect(controller.called).to.equal(1);
+    expect(stage.gameImgProps).to.equal(null);
+    expect(stage.guiImgProps).to.equal(null);
+    expect(stage.stageCav).to.equal(null);
+  });
+
+  it('disposes safely when window is unavailable', function() {
+    const { canvas } = makeCanvas(120, 90);
+    const stage = new Stage(canvas);
+    stage._resizeRaf = 123;
+    const originalWindow = globalThis.window;
+    globalThis.window = undefined;
+    try {
+      expect(() => stage.dispose()).to.not.throw();
+      expect(stage.stageCav).to.equal(null);
+    } finally {
+      globalThis.window = originalWindow;
+    }
+  });
+});
diff --git a/test/rollout-flags.test.js b/test/rollout-flags.test.js
new file mode 100644
index 00000000..2b9fa1ca
--- /dev/null
+++ b/test/rollout-flags.test.js
@@ -0,0 +1,78 @@
+import { expect } from 'chai';
+import {
+  DEFAULT_RUNTIME_ROLLOUT_FLAGS,
+  resolveRuntimeRolloutFlags
+} from '../js/core/rolloutFlags.js';
+
+describe('rolloutFlags', function () {
+  it('returns stable defaults', function () {
+    expect(resolveRuntimeRolloutFlags({ search: '' })).to.deep.equal(DEFAULT_RUNTIME_ROLLOUT_FLAGS);
+  });
+
+  it('accepts runtime override objects', function () {
+    const resolved = resolveRuntimeRolloutFlags({
+      runtimeFlags: {
+        historyCodec: false
+      }
+    });
+
+    expect(resolved.historyCodec).to.equal(false);
+  });
+
+  it('applies query rollout and rollback toggles', function () {
+    const resolved = resolveRuntimeRolloutFlags({
+      search: '?rolloutRenderPresent=true&rollbackHistoryCodec=1'
+    });
+
+    expect(resolved.renderPresentPath).to.equal(true);
+    expect(resolved.historyCodec).to.equal(false);
+  });
+
+  it('supports rollbackAll emergency toggle', function () {
+    const resolved = resolveRuntimeRolloutFlags({
+      search: '?rollbackAll=1',
+      runtimeFlags: {
+        historyCodec: true,
+        renderPresentPath: true
+      }
+    });
+
+    expect(resolved).to.deep.equal({
+      historyCodec: false,
+      renderPresentPath: false
+    });
+  });
+
+  it('accepts explicit query objects and ignores unknown values', function () {
+    const query = new URLSearchParams('rolloutHistoryCodec=bogus&rollbackRenderPresent=1');
+    const resolved = resolveRuntimeRolloutFlags({
+      query,
+      runtimeFlags: { historyCodec: true, renderPresentPath: true }
+    });
+    expect(resolved.historyCodec).to.equal(true);
+    expect(resolved.renderPresentPath).to.equal(false);
+  });
+
+  it('respects caller-provided defaults for runtime rollout baselines', function () {
+    const resolved = resolveRuntimeRolloutFlags({
+      defaults: { historyCodec: false },
+      runtimeFlags: { renderPresentPath: true }
+    });
+
+    expect(resolved.historyCodec).to.equal(false);
+    expect(resolved.renderPresentPath).to.equal(true);
+  });
+
+  it('uses canonical query names for rollout flags', function () {
+    const query = new URLSearchParams('rolloutRenderPresent=false');
+    const resolved = resolveRuntimeRolloutFlags({ query });
+    expect(resolved.renderPresentPath).to.equal(false);
+  });
+
+  it('treats bare rollout query flags as enabled', function () {
+    const resolved = resolveRuntimeRolloutFlags({
+      search: '?rolloutRenderPresent'
+    });
+    expect(resolved.renderPresentPath).to.equal(true);
+  });
+});
diff --git a/test/run-tests-script.test.js b/test/run-tests-script.test.js
new file mode 100644
index 00000000..c5706b54
--- /dev/null
+++ b/test/run-tests-script.test.js
@@ -0,0 +1,435 @@
+import { expect } from 'chai';
+import { readFileSync } from 'node:fs';
+import {
+  RUNTIME_GUARD_TARGETS,
+  buildMochaArgsForCategories,
+  collectChangedFiles,
+  formatSelectionLines,
+  inferCategoriesFromChangedFiles,
+  main,
+  parseBoolEnv,
+  parseCliArgs,
+  resolveBaseRef,
+  resolveRuntimeBudgetMs,
+  runRuntimeGlobalGuard
+} from '../scripts/runTests.js';
+
+const createRunGitStub = (
+  responsesByCommand,
+  { defaultResponse = { status: 1, stdout: '' } } = {}
+) => (args) => {
+  const key = args.join(' ');
+  const response = responsesByCommand[key];
+  if (!response) {
+    return defaultResponse;
+  }
+  return response;
+};
+
+describe('scripts/runTests', function () {
+  it('parses changed/base/selection options and categories', function () {
+    const parsed = parseCliArgs(['--changed', '--base=origin/main', '--print-selection', 'editor']);
+    expect(parsed.changed).to.equal(true);
+    expect(parsed.baseRef).to.equal('origin/main');
+    expect(parsed.printSelection).to.equal(true);
+    expect(parsed.categories).to.deep.equal(['editor']);
+  });
+
+  it('treats --dry-run as a selection-print alias', function () {
+    const parsed = parseCliArgs(['--dry-run']);
+    expect(parsed.printSelection).to.equal(true);
+  });
+
+  it('parses budget guard environment helpers', function () {
+    expect(parseBoolEnv('true')).to.equal(true);
+    expect(parseBoolEnv('1')).to.equal(true);
+    expect(parseBoolEnv('off')).to.equal(false);
+    expect(resolveRuntimeBudgetMs('60000')).to.equal(60000);
+    expect(resolveRuntimeBudgetMs('bogus')).to.equal(180000);
+    expect(resolveRuntimeBudgetMs(Symbol('budget'))).to.equal(180000);
+  });
+
+  it('covers app, editor, render, and runtime slices with the singleton guard', function () {
+    expect(RUNTIME_GUARD_TARGETS).to.include.members([
+      'js/app/**/*.js',
+      'js/editor/**/*.js',
+      'js/render/**/*.js'
+    ]);
+  });
+
+  it('maps changed files to stable category selection', function () {
+    const categories = inferCategoriesFromChangedFiles([
+      'test/editor-ui-format.test.js',
+      'test/input/editor-keybindings.test.js',
+      'tools/offline/export.js',
+      '.github/workflows/tests.yml',
+      'docs/release-readiness.md'
+    ]);
+    expect(categories).to.include('editor');
+    expect(categories).to.include('offline-tools');
+    expect(categories).to.include('workflow');
+    expect(categories).to.include('release');
+  });
+
+  it('maps generic tools, offline tool sources, and bench paths to their dedicated categories', function () {
+    const categories = inferCategoriesFromChangedFiles([
+      'tools/packPipeline.js',
+      'tools/scanGreenPanel.js',
+      'scripts/bench-performance.js'
+    ]);
+    expect(categories).to.include('offline-tools');
+    expect(categories).to.include('tools');
+    expect(categories).to.include('bench');
+  });
+
+  it('falls back to full suite args whenever core is included', function () {
+    const args = buildMochaArgsForCategories(['editor', 'core']);
+    expect(args).to.deep.equal(['--recursive']);
+  });
+
+  it('builds focused args for release category', function () {
+    const args = buildMochaArgsForCategories(['release']);
+    expect(args).to.deep.equal(['test/release-readiness.test.js']);
+  });
+
+  it('builds focused args for bench category', function () {
+    const args = buildMochaArgsForCategories(['bench']);
+    expect(args).to.deep.equal(['test/*bench*.test.js']);
+  });
+
+  it('builds focused args for game category', function () {
+    const args = buildMochaArgsForCategories(['game']);
+    expect(args).to.deep.equal(['test/*game*.test.js']);
+  });
+
+  it('uses an explicit base ref without consulting git', function () {
+    const runGitCommand = createRunGitStub({});
+    const resolved = resolveBaseRef({ baseRef: 'origin/release', runGitCommand });
+    expect(resolved).to.deep.equal({
+      ref: 'origin/release',
+      source: 'explicit'
+    });
+  });
+
+  it('prefers the current branch upstream when resolving the default base ref', function () {
+    const runGitCommand = createRunGitStub({
+      'rev-parse --abbrev-ref --symbolic-full-name @{upstream}': {
+        status: 0,
+        stdout: 'origin/feature-branch\n'
+      }
+    });
+    const resolved = resolveBaseRef({ runGitCommand });
+    expect(resolved).to.deep.equal({
+      ref: 'origin/feature-branch',
+      source: 'upstream'
+    });
+  });
+
+  it('falls back to origin HEAD when no upstream is configured', function () {
+    const runGitCommand = createRunGitStub({
+      'symbolic-ref --quiet --short refs/remotes/origin/HEAD': {
+        status: 0,
+        stdout: 'origin/master\n'
+      }
+    });
+    const resolved = resolveBaseRef({ runGitCommand });
+    expect(resolved).to.deep.equal({
+      ref: 'origin/master',
+      source: 'origin-head'
+    });
+  });
+
+  it('falls back through known branch candidates when upstream and origin HEAD are unavailable', function () {
+    const runGitCommand = createRunGitStub({
+      'rev-parse --verify --quiet origin/master': {
+        status: 0,
+        stdout: 'abc123\n'
+      }
+    });
+    const resolved = resolveBaseRef({ runGitCommand });
+    expect(resolved).to.deep.equal({
+      ref: 'origin/master',
+      source: 'fallback'
+    });
+  });
+
+  it('returns null when no safe default base ref can be resolved', function () {
+    const runGitCommand = createRunGitStub({});
+    const resolved = resolveBaseRef({ runGitCommand });
+    expect(resolved).to.equal(null);
+  });
+
+  it('collects changed files from git outputs and untracked files', function () {
+    const runGitCommand = createRunGitStub({
+      'diff --name-only --diff-filter=ACMRD origin/main...HEAD': { status: 0, stdout: 'js/app/boot.js\n' },
+      'diff --name-only --cached --diff-filter=ACMRD': { status: 0, stdout: 'js/app/boot.js\n' },
+      'diff --name-only --diff-filter=ACMRD': { status: 0, stdout: 'js/editor/EditorController.js\n' },
+      'ls-files --others --exclude-standard': { status: 0, stdout: 'test/new.test.js\n' }
+    });
+    const files = collectChangedFiles({ baseRef: 'origin/main', runGitCommand });
+    expect(files).to.deep.equal([
+      'js/app/boot.js',
+      'js/editor/EditorController.js',
+      'test/new.test.js'
+    ]);
+  });
+
+  it('includes deleted files when collecting changed paths', function () {
+    const runGitCommand = createRunGitStub({
+      'diff --name-only --diff-filter=ACMRD origin/main...HEAD': { status: 0, stdout: 'mcp/old-tool.js\n' },
+      'diff --name-only --cached --diff-filter=ACMRD': { status: 0, stdout: '' },
+      'diff --name-only --diff-filter=ACMRD': { status: 0, stdout: '' },
+      'ls-files --others --exclude-standard': { status: 0, stdout: '' }
+    });
+    const files = collectChangedFiles({ baseRef: 'origin/main', runGitCommand });
+    expect(files).to.deep.equal(['mcp/old-tool.js']);
+  });
+
+  it('formats selection diagnostics with base, files, categories, and mocha args', function () {
+    const lines = formatSelectionLines({
+      resolvedBase: { ref: 'origin/main', source: 'origin-head' },
+      changedFiles: ['tools/packPipeline.js', 'test/offline-tools/packPipeline.test.js'],
+      categories: ['offline-tools'],
+      mochaArgs: ['test/offline-tools/*.test.js']
+    });
+    expect(lines).to.deep.equal([
+      'Resolved base ref: origin/main (origin-head)',
+      'Changed files (2): tools/packPipeline.js, test/offline-tools/packPipeline.test.js',
+      'Selected categories: offline-tools',
+      'Mocha args: test/offline-tools/*.test.js'
+    ]);
+  });
+
+  it('keeps critical checkJs typecheck enabled in tsconfig.checkjs.json', function () {
+    const config = JSON.parse(readFileSync(new URL('../tsconfig.checkjs.json', import.meta.url), 'utf8'));
+    expect(config.compilerOptions?.allowJs).to.equal(true);
+    expect(config.compilerOptions?.checkJs).to.equal(true);
+    expect(Array.isArray(config.include)).to.equal(true);
+    expect(config.include.length).to.be.greaterThan(0);
+  });
+
+  it('keeps maintained npm test subset scripts routed through scripts/runTests.js', function () {
+    const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    expect(pkg.scripts['test-core']).to.equal('node scripts/runTests.js game');
+    expect(pkg.scripts['test-bench-unit']).to.equal('node scripts/runTests.js bench');
+    expect(pkg.scripts['test-workflow']).to.equal('node scripts/runTests.js workflow');
+    expect(pkg.scripts['test-tools']).to.equal('node scripts/runTests.js tools');
+    expect(pkg.scripts['test-offline-tools']).to.equal('node scripts/runTests.js offline-tools');
+    expect(pkg.scripts['test-editor']).to.equal('node scripts/runTests.js editor');
+  });
+
+  it('falls back to full suite when no safe base ref can be resolved', function () {
+    const logs = { warn: [], error: [], log: [] };
+    const spawned = [];
+    const exits = [];
+    main(['--changed'], {
+      spawn: (cmd, args) => {
+        spawned.push({ cmd, args });
+        return { status: 0 };
+      },
+      runGitCommand: () => ({ status: 1, stdout: '' }),
+      log: {
+        warn: (msg) => logs.warn.push(msg),
+        error: (msg) => logs.error.push(msg),
+        log: (msg) => logs.log.push(msg)
+      },
+      exit: (code) => exits.push(code)
+    });
+    expect(logs.warn[0]).to.contain('safe base ref');
+    expect(spawned[0].args).to.include('--max-warnings=0');
+    expect(spawned[0].args).to.include(RUNTIME_GUARD_TARGETS[0]);
+    expect(spawned[1].args).to.include('-p');
+    expect(spawned[1].args).to.include('tsconfig.checkjs.json');
+    expect(spawned[2].args).to.include('--recursive');
+    expect(exits).to.deep.equal([0]);
+  });
+
+  it('falls back to full suite when changed-file collection fails for a resolved base', function () {
+    const logs = { warn: [], error: [], log: [] };
+    const spawned = [];
+    const exits = [];
+    const runGitCommand = createRunGitStub({
+      'rev-parse --abbrev-ref --symbolic-full-name @{upstream}': {
+        status: 0,
+        stdout: 'origin/feature-branch\n'
+      },
+      'diff --name-only --diff-filter=ACMRD origin/feature-branch...HEAD': {
+        status: 1,
+        stdout: ''
+      }
+    });
+    main(['--changed'], {
+      spawn: (cmd, args) => {
+        spawned.push({ cmd, args });
+        return { status: 0 };
+      },
+      runGitCommand,
+      log: {
+        warn: (msg) => logs.warn.push(msg),
+        error: (msg) => logs.error.push(msg),
+        log: (msg) => logs.log.push(msg)
+      },
+      exit: (code) => exits.push(code)
+    });
+    expect(logs.warn[0]).to.contain('origin/feature-branch');
+    expect(spawned[2].args).to.include('--recursive');
+    expect(exits).to.deep.equal([0]);
+  });
+
+  it('prints changed-file selection details without running guards or mocha', function () {
+    const logs = { warn: [], error: [], log: [] };
+    const spawned = [];
+    const exits = [];
+    const runGitCommand = createRunGitStub({
+      'diff --name-only --diff-filter=ACMRD origin/main...HEAD': {
+        status: 0,
+        stdout: 'tools/packPipeline.js\n'
+      },
+      'diff --name-only --cached --diff-filter=ACMRD': { status: 0, stdout: '' },
+      'diff --name-only --diff-filter=ACMRD': { status: 0, stdout: '' },
+      'ls-files --others --exclude-standard': { status: 0, stdout: '' }
+    });
+    main(['--changed', '--base=origin/main', '--print-selection'], {
+      spawn: (cmd, args) => {
+        spawned.push({ cmd, args });
+        return { status: 0 };
+      },
+      runGitCommand,
+      log: {
+        warn: (msg) => logs.warn.push(msg),
+        error: (msg) => logs.error.push(msg),
+        log: (msg) => logs.log.push(msg)
+      },
+      exit: (code) => exits.push(code)
+    });
+    expect(spawned).to.have.lengthOf(0);
+    expect(logs.warn).to.deep.equal([]);
+    expect(logs.log).to.deep.equal([
+      'Changed-file test selection: offline-tools',
+      'Changed-file base ref: origin/main (explicit)',
+      'Resolved base ref: origin/main (explicit)',
+      'Changed files (1): tools/packPipeline.js',
+      'Selected categories: offline-tools',
+      'Mocha args: test/offline-tools/*.test.js'
+    ]);
+    expect(exits).to.deep.equal([0]);
+  });
+
+  it('runs runtime global guard before mocha', function () {
+    const spawned = [];
+    const exits = [];
+    main([], {
+      spawn: (cmd, args) => {
+        spawned.push({ cmd, args });
+        return { status: 0 };
+      },
+      log: {
+        warn: () => {},
+        error: () => {},
+        log: () => {}
+      },
+      exit: (code) => exits.push(code)
+    });
+    expect(spawned[0].args).to.include('--max-warnings=0');
+    expect(spawned[0].args).to.include(RUNTIME_GUARD_TARGETS[0]);
+    expect(spawned[1].args).to.include('-p');
+    expect(spawned[1].args).to.include('tsconfig.checkjs.json');
+    expect(spawned[2].args).to.include('--recursive');
+    expect(exits).to.deep.equal([0]);
+  });
+
+  it('aborts test run when runtime global guard fails', function () {
+    const spawned = [];
+    const exits = [];
+    main([], {
+      spawn: (cmd, args) => {
+        spawned.push({ cmd, args });
+        if (spawned.length === 1) return { status: 1 };
+        return { status: 0 };
+      },
+      log: {
+        warn: () => {},
+        error: () => {},
+        log: () => {}
+      },
+      exit: (code) => exits.push(code)
+    });
+    expect(spawned).to.have.lengthOf(1);
+    expect(spawned[0].args).to.include('--max-warnings=0');
+    expect(exits).to.deep.equal([1]);
+  });
+
+  it('runRuntimeGlobalGuard reports success and failure statuses', function () {
+    const exits = [];
+    const success = runRuntimeGlobalGuard({
+      spawn: () => ({ status: 0 }),
+      log: { error: () => {} },
+      exit: (code) => exits.push(code)
+    });
+    const failure = runRuntimeGlobalGuard({
+      spawn: () => ({ status: 2 }),
+      log: { error: () => {} },
+      exit: (code) => exits.push(code)
+    });
+    expect(success).to.equal(true);
+    expect(failure).to.equal(false);
+    expect(exits).to.deep.equal([2]);
+  });
+
+  it('rejects unknown categories without running mocha', function () {
+    const exits = [];
+    const spawned = [];
+    main(['unknown-category'], {
+      spawn: () => {
+        spawned.push(true);
+        return { status: 0 };
+      },
+      log: {
+        warn: () => {},
+        error: () => {},
+        log: () => {}
+      },
+      exit: (code) => exits.push(code)
+    });
+
+    expect(spawned).to.have.lengthOf(0);
+    expect(exits).to.deep.equal([1]);
+  });
+
+  it('fails when budget enforcement is enabled and runtime exceeds threshold', function () {
+    const exits = [];
+    const spawned = [];
+    const originalEnforce = process.env.LEMMINGS_TEST_ENFORCE_BUDGET;
+    const originalBudget = process.env.LEMMINGS_TEST_BUDGET_MS;
+    const originalNow = Date.now;
+    let nowTick = 0;
+    Date.now = () => {
+      nowTick += 10;
+      return nowTick;
+    };
+    process.env.LEMMINGS_TEST_ENFORCE_BUDGET = 'true';
+    process.env.LEMMINGS_TEST_BUDGET_MS = '1';
+    try {
+      main([], {
+        spawn: () => {
+          spawned.push(true);
+          return { status: 0 };
+        },
+        log: {
+          warn: () => {},
+          error: () => {},
+          log: () => {}
+        },
+        exit: (code) => exits.push(code)
+      });
+    } finally {
+      Date.now = originalNow;
+      if (originalEnforce == null) delete process.env.LEMMINGS_TEST_ENFORCE_BUDGET;
+      else process.env.LEMMINGS_TEST_ENFORCE_BUDGET = originalEnforce;
+      if (originalBudget == null) delete process.env.LEMMINGS_TEST_BUDGET_MS;
+      else process.env.LEMMINGS_TEST_BUDGET_MS = originalBudget;
+    }
+    expect(spawned).to.have.lengthOf(3);
+    expect(exits).to.deep.equal([1]);
+  });
+});
diff --git a/test/runtime-profiles.test.js b/test/runtime-profiles.test.js
new file mode 100644
index 00000000..6a8038a2
--- /dev/null
+++ b/test/runtime-profiles.test.js
@@ -0,0 +1,46 @@
+import { expect } from 'chai';
+import {
+  DEFAULT_RUNTIME_PROFILE,
+  getProfileHistoryRetention,
+  getRuntimeProfileIds,
+  getRuntimeProfilePreset,
+  getSpecialHistoryRetention,
+  normalizeRuntimeProfile
+} from '../js/core/runtimeProfiles.js';
+
+describe('runtimeProfiles', function () {
+  it('normalizes aliases and falls back to default profiles', function () {
+    expect(normalizeRuntimeProfile('gameplay')).to.equal('classic');
+    expect(normalizeRuntimeProfile('MIDI')).to.equal('midi');
+    expect(normalizeRuntimeProfile('missing-profile')).to.equal(DEFAULT_RUNTIME_PROFILE);
+  });
+
+  it('returns expected preset ids and default preset fallback', function () {
+    const ids = getRuntimeProfileIds();
+    expect(ids).to.include.members(['classic', 'midi', 'editor', 'e2e', 'perf']);
+    expect(getRuntimeProfilePreset('does-not-exist').id).to.equal(DEFAULT_RUNTIME_PROFILE);
+  });
+
+  it('returns cloned history-retention values', function () {
+    const retention = getProfileHistoryRetention('perf');
+    expect(retention).to.deep.equal({
+      enableHistoryCap: true,
+      historyCapTicks: 12000,
+      historyWarnTicks: 9000
+    });
+    retention.historyCapTicks = 1;
+    expect(getProfileHistoryRetention('perf').historyCapTicks).to.equal(12000);
+  });
+
+  it('returns special history retention policies as clones', function () {
+    const endless = getSpecialHistoryRetention('endless');
+    expect(endless).to.deep.equal({
+      enableHistoryCap: true,
+      historyCapTicks: 24000,
+      historyWarnTicks: 18000
+    });
+    endless.historyCapTicks = 1;
+    expect(getSpecialHistoryRetention('endless').historyCapTicks).to.equal(24000);
+    expect(getSpecialHistoryRetention('unknown')).to.equal(null);
+  });
+});
diff --git a/test/seeded-random.test.js b/test/seeded-random.test.js
new file mode 100644
index 00000000..c89540fc
--- /dev/null
+++ b/test/seeded-random.test.js
@@ -0,0 +1,32 @@
+import { expect } from 'chai';
+import {
+  hashString32,
+  normalizeSeed,
+  deriveSeed,
+  createSeededRandom
+} from '../js/core/seededRandom.js';
+
+describe('seededRandom', function () {
+  it('normalizes numeric and string seeds deterministically', function () {
+    expect(normalizeSeed(123.9)).to.equal(123);
+    expect(normalizeSeed('123')).to.equal(123);
+    expect(normalizeSeed('0x7b')).to.equal(123);
+    expect(normalizeSeed('abc')).to.equal(hashString32('abc'));
+  });
+
+  it('derives scoped seeds stably from a base seed', function () {
+    const a = deriveSeed(1337, 'style');
+    const b = deriveSeed(1337, 'controller');
+    expect(a).to.not.equal(b);
+    expect(deriveSeed(1337, 'style')).to.equal(a);
+  });
+
+  it('produces repeatable random streams for a given seed', function () {
+    const a = createSeededRandom('procgen-seed');
+    const b = createSeededRandom('procgen-seed');
+    const samplesA = [a(), a(), a(), a()];
+    const samplesB = [b(), b(), b(), b()];
+    expect(samplesA).to.deep.equal(samplesB);
+    expect(samplesA.every(v => v >= 0 && v < 1)).to.equal(true);
+  });
+});
diff --git a/test/shortcut-overlay.test.js b/test/shortcut-overlay.test.js
new file mode 100644
index 00000000..9a9baddf
--- /dev/null
+++ b/test/shortcut-overlay.test.js
@@ -0,0 +1,159 @@
+import { expect } from 'chai';
+import { ShortcutOverlay } from '../js/app/shortcutOverlay.js';
+
+class FakeClassList {
+  constructor() {
+    this._set = new Set();
+  }
+
+  add(name) {
+    this._set.add(name);
+  }
+
+  remove(name) {
+    this._set.delete(name);
+  }
+
+  contains(name) {
+    return this._set.has(name);
+  }
+}
+
+class FakeElement {
+  constructor(doc, tagName = 'div') {
+    this.ownerDocument = doc;
+    this.tagName = tagName.toUpperCase();
+    this.children = [];
+    this.attributes = new Map();
+    this.classList = new FakeClassList();
+    this.listeners = new Map();
+    this.textContent = '';
+    this.className = '';
+    this.type = '';
+    this.isConnected = true;
+    this._selectors = new Map();
+  }
+
+  querySelector(selector) {
+    return this._selectors.get(selector) || null;
+  }
+
+  setSelector(selector, element) {
+    this._selectors.set(selector, element);
+  }
+
+  set innerHTML(value) {
+    this._innerHTML = String(value ?? '');
+    this.children = [];
+  }
+
+  get innerHTML() {
+    return this._innerHTML || '';
+  }
+
+  appendChild(child) {
+    this.children.push(child);
+    return child;
+  }
+
+  setAttribute(name, value) {
+    this.attributes.set(name, String(value));
+  }
+
+  getAttribute(name) {
+    return this.attributes.get(name) || null;
+  }
+
+  addEventListener(type, handler) {
+    if (!this.listeners.has(type)) this.listeners.set(type, []);
+    this.listeners.get(type).push(handler);
+  }
+
+  dispatchEvent(event) {
+    const handlers = this.listeners.get(event.type) || [];
+    for (const handler of handlers) {
+      handler({ target: this, ...event });
+    }
+  }
+
+  focus() {
+    this.ownerDocument.activeElement = this;
+  }
+}
+
+const createOverlayDom = () => {
+  const doc = {
+    activeElement: null,
+    createElement(tagName) {
+      return new FakeElement(doc, tagName);
+    }
+  };
+  const root = new FakeElement(doc, 'div');
+  const content = new FakeElement(doc, 'div');
+  const close = new FakeElement(doc, 'button');
+  const title = new FakeElement(doc, 'div');
+  root.setSelector('.shortcut-overlay__content', content);
+  root.setSelector('.shortcut-overlay__close', close);
+  root.setSelector('.shortcut-overlay__title', title);
+  root.setAttribute('aria-hidden', 'true');
+  return { doc, root, content, close, title };
+};
+
+describe('ShortcutOverlay', () => {
+  it('focuses the close button on show and restores previous focus on hide', () => {
+    const { doc, root, close, title } = createOverlayDom();
+    const opener = new FakeElement(doc, 'button');
+    doc.activeElement = opener;
+    const overlay = new ShortcutOverlay({
+      root,
+      title: 'Editor Shortcuts',
+      sections: [{
+        title: 'General',
+        entries: [{ action: 'toggle', label: 'Toggle shortcuts' }]
+      }],
+      getBindings: () => ['F1']
+    });
+
+    overlay.show();
+
+    expect(root.classList.contains('is-visible')).to.equal(true);
+    expect(root.getAttribute('aria-hidden')).to.equal('false');
+    expect(title.textContent).to.equal('Editor Shortcuts');
+    expect(doc.activeElement).to.equal(close);
+
+    overlay.hide();
+
+    expect(root.classList.contains('is-visible')).to.equal(false);
+    expect(root.getAttribute('aria-hidden')).to.equal('true');
+    expect(doc.activeElement).to.equal(opener);
+  });
+
+  it('closes on Escape and prevents the key event default', () => {
+    const { root } = createOverlayDom();
+    const overlay = new ShortcutOverlay({ root });
+    let prevented = false;
+
+    overlay.show();
+    root.dispatchEvent({
+      type: 'keydown',
+      key: 'Escape',
+      preventDefault() {
+        prevented = true;
+      }
+    });
+
+    expect(prevented).to.equal(true);
+    expect(root.getAttribute('aria-hidden')).to.equal('true');
+  });
+
+  it('keeps close-button clicks wired to hide the overlay', () => {
+    const { root, close } = createOverlayDom();
+    const overlay = new ShortcutOverlay({ root });
+
+    overlay.show();
+    close.dispatchEvent({ type: 'click' });
+
+    expect(root.classList.contains('is-visible')).to.equal(false);
+    expect(root.getAttribute('aria-hidden')).to.equal('true');
+  });
+});
diff --git a/test/solver-advisory.test.js b/test/solver-advisory.test.js
new file mode 100644
index 00000000..baca7675
--- /dev/null
+++ b/test/solver-advisory.test.js
@@ -0,0 +1,179 @@
+import { expect } from 'chai';
+import {
+  SOLVER_EXPLANATION_CODES,
+  SOLVER_RESULT_TYPES,
+  createSolverResult
+} from '../js/solver/SolverTypes.js';
+import {
+  createFlatWalkFixture,
+  createSmallGapFixture,
+  createSyntheticSolverFixture
+} from '../js/solver/SolverFixtures.js';
+import {
+  PROCGEN_FALLBACK_DECISIONS,
+  PROCGEN_CHALLENGE_TYPES,
+  createProcgenChallengeCertificate,
+  decideProcgenFallback,
+  verifyProcgenChallengeCertificate,
+  verifyProcgenChallengeCertificateSync
+} from '../js/solver/ProcgenCertificates.js';
+import {
+  EDITOR_ADVISORY_WARNING_CODES,
+  checkEditorSolvabilityAdvisory
+} from '../js/solver/EditorAdvisory.js';
+import { SkillTypes } from '../js/game/SkillTypes.js';
+
+describe('ProcgenCertificates', function() {
+  it('verifies positive local chunks through a tactical solver', async function() {
+    const chunk = createSmallGapFixture();
+    const certificate = createProcgenChallengeCertificate({
+      id: 'gap-bridge-1',
+      challengeType: PROCGEN_CHALLENGE_TYPES.BRIDGE_GAP,
+      expectedSkill: 'builder',
+      assignmentWindow: { start: 18, end: 48 },
+      expectedLandingSegment: { x0: 58, y0: 57, x1: 72, y1: 57 },
+      expectedExitSegment: { x0: 116, y0: 57, x1: 126, y1: 57 },
+      minimalSkillCount: 1
+    });
+    const verified = await verifyProcgenChallengeCertificate(certificate, chunk, {
+      tacticalSolver({ certificate: receivedCertificate, chunk: receivedChunk }) {
+        expect(receivedCertificate.expectedSkill).to.equal('builder');
+        expect(receivedCertificate.roughAssignmentWindow).to.deep.equal({ start: 18, end: 48 });
+        expect(receivedChunk.id).to.equal('small-gap');
+        return createSolverResult({
+          resultType: SOLVER_RESULT_TYPES.SOLVED,
+          summary: 'small gap verified',
+          actions: [{
+            skill: 'builder',
+            window: receivedCertificate.assignmentWindow,
+            rationale: 'bridge the local procgen gap'
+          }]
+        });
+      }
+    });
+    expect(verified.verificationResult.resultType).to.equal(SOLVER_RESULT_TYPES.SOLVED);
+    expect(verified.verificationResult.actions[0].skillType).to.equal('builder');
+    expect(decideProcgenFallback(verified.verificationResult).decision).to.equal(
+      PROCGEN_FALLBACK_DECISIONS.ACCEPT
+    );
+  });
+
+  it('returns unsupported instead of throwing when no tactical solver is available', async function() {
+    const verified = await verifyProcgenChallengeCertificate({
+      challengeType: PROCGEN_CHALLENGE_TYPES.BRIDGE_GAP,
+      expectedSkill: 'builder'
+    }, createSmallGapFixture(), {
+      tacticalSolver: null
+    });
+    expect(verified.verificationResult.resultType).to.equal(SOLVER_RESULT_TYPES.UNSUPPORTED);
+    expect(verified.verificationResult.explanations[0].code).to.equal(
+      SOLVER_EXPLANATION_CODES.UNSUPPORTED_MECHANIC
+    );
+  });
+
+  it('verifies local chunks through the default tactical solver', async function() {
+    const verified = await verifyProcgenChallengeCertificate({
+      challengeType: PROCGEN_CHALLENGE_TYPES.BRIDGE_GAP,
+      expectedSkill: 'builder'
+    }, createSmallGapFixture());
+
+    expect(verified.verificationResult.resultType).to.equal(SOLVER_RESULT_TYPES.SOLVED);
+    expect(decideProcgenFallback(verified.verificationResult).decision).to.equal(
+      PROCGEN_FALLBACK_DECISIONS.ACCEPT
+    );
+  });
+
+  it('supports synchronous procgen certificate decisions', function() {
+    const verified = verifyProcgenChallengeCertificateSync({
+      challengeType: PROCGEN_CHALLENGE_TYPES.BRIDGE_GAP,
+      expectedSkill: 'builder'
+    }, createSmallGapFixture());
+
+    expect(verified.verificationResult.resultType).to.equal(SOLVER_RESULT_TYPES.SOLVED);
+  });
+
+  it('chooses simplify, replace, and extend fallbacks for failed chunks', function() {
+    const simplify = decideProcgenFallback(createSolverResult({
+      resultType: SOLVER_RESULT_TYPES.FAILED,
+      explanations: [SOLVER_EXPLANATION_CODES.GAP_EXCEEDS_BUILDER_BUDGET]
+    }));
+    const replace = decideProcgenFallback(createSolverResult({
+      resultType: SOLVER_RESULT_TYPES.FAILED,
+      explanations: [SOLVER_EXPLANATION_CODES.HAZARD_UNAVOIDABLE]
+    }));
+    const extend = decideProcgenFallback(createSolverResult({
+      resultType: SOLVER_RESULT_TYPES.FAILED,
+      explanations: [SOLVER_EXPLANATION_CODES.MISSING_LANDING]
+    }));
+    expect(simplify.decision).to.equal(PROCGEN_FALLBACK_DECISIONS.SIMPLIFY);
+    expect(replace.decision).to.equal(PROCGEN_FALLBACK_DECISIONS.REPLACE);
+    expect(extend.decision).to.equal(PROCGEN_FALLBACK_DECISIONS.EXTEND);
+  });
+});
+
+describe('EditorAdvisory', function() {
+  it('returns non-blocking warnings for obvious advisory problems', function() {
+    const gap = createSmallGapFixture({
+      skills: {},
+      oneWay: [{ x: 20, y: 58, width: 20, height: 4 }],
+      hazards: [{ kind: 'teleporter', x: 64, y: 54, width: 8, height: 8 }]
+    });
+    const advisory = checkEditorSolvabilityAdvisory(gap);
+    const codes = advisory.warnings.map(warning => warning.code);
+    expect(advisory.canContinue).to.equal(true);
+    expect(advisory.blocksEditing).to.equal(false);
+    expect(advisory.blocksExport).to.equal(false);
+    expect(codes).to.include(EDITOR_ADVISORY_WARNING_CODES.UNREACHABLE_GAP);
+    expect(codes).to.include(EDITOR_ADVISORY_WARNING_CODES.INSUFFICIENT_SKILLS);
+    expect(codes).to.include(EDITOR_ADVISORY_WARNING_CODES.UNSUPPORTED_MECHANIC);
+  });
+
+  it('warns about lethal drops without blocking editing or export', function() {
+    const lethalDrop = createSyntheticSolverFixture({
+      id: 'lethal-drop',
+      width: 128,
+      height: 128,
+      ground: [
+        { x: 0, y: 24, width: 42, height: 4 },
+        { x: 58, y: 104, width: 70, height: 4 }
+      ],
+      entrances: [{ x: 8, y: 23 }],
+      exits: [{ x: 112, y: 103 }],
+      lemmings: [{ id: 0, x: 8, y: 23, lookRight: true, action: 'walking' }],
+      skills: { builder: 4 }
+    });
+    const advisory = checkEditorSolvabilityAdvisory(lethalDrop);
+    expect(advisory.blocksEditing).to.equal(false);
+    expect(advisory.blocksExport).to.equal(false);
+    expect(advisory.warnings.map(warning => warning.code)).to.include(
+      EDITOR_ADVISORY_WARNING_CODES.LETHAL_DROP
+    );
+  });
+
+  it('reads runtime skill arrays for advisory skill budgets', function() {
+    const gap = createSmallGapFixture({ skills: {} });
+    gap.skills = [];
+    gap.skills[SkillTypes.BUILDER] = 2;
+
+    const advisory = checkEditorSolvabilityAdvisory(gap);
+    const codes = advisory.warnings.map(warning => warning.code);
+
+    expect(codes).to.not.include(EDITOR_ADVISORY_WARNING_CODES.UNREACHABLE_GAP);
+    expect(codes).to.not.include(EDITOR_ADVISORY_WARNING_CODES.INSUFFICIENT_SKILLS);
+  });
+
+  it('returns deterministic missing entrance and exit warnings', function() {
+    const fixture = createFlatWalkFixture({
+      entrances: [],
+      exits: []
+    });
+    const first = checkEditorSolvabilityAdvisory(fixture);
+    const second = checkEditorSolvabilityAdvisory(fixture);
+    expect(first.warnings).to.deep.equal(second.warnings);
+    expect(first.warnings.map(warning => warning.code).slice(0, 2)).to.deep.equal([
+      EDITOR_ADVISORY_WARNING_CODES.MISSING_ENTRANCE,
+      EDITOR_ADVISORY_WARNING_CODES.MISSING_EXIT
+    ]);
+    expect(first.canContinue).to.equal(true);
+  });
+});
diff --git a/test/solver-analysis-reachability.test.js b/test/solver-analysis-reachability.test.js
new file mode 100644
index 00000000..9b0d6683
--- /dev/null
+++ b/test/solver-analysis-reachability.test.js
@@ -0,0 +1,48 @@
+import { expect } from 'chai';
+import {
+  createBarrierFixture,
+  createSmallGapFixture
+} from '../js/solver/SolverFixtures.js';
+import { analyzeSolverAffordances } from '../js/solver/SolverAnalysis.js';
+import {
+  buildReachabilityGraph,
+  invalidateReachabilityGraph
+} from '../js/solver/ReachabilityGraph.js';
+import { SOLVER_EXPLANATION_CODES } from '../js/solver/SolverTypes.js';
+
+describe('solver analysis and reachability graph', function () {
+  it('reports hazards and steel-blocked destructive affordances deterministically', function () {
+    const fixture = createBarrierFixture({
+      hazards: [{ x: 90, y: 55, width: 5, height: 3, kind: 'water' }],
+      steel: [{ x: 62, y: 48, width: 8, height: 10 }]
+    });
+
+    const first = analyzeSolverAffordances(fixture);
+    const second = analyzeSolverAffordances(fixture);
+    const basher = first.skillAffordances.find(entry => entry.skillType === 'basher');
+
+    expect(first.analysisHash).to.equal(second.analysisHash);
+    expect(first.hazards[0]).to.include({ kind: 'water', supported: true });
+    expect(basher.blocked).to.equal(true);
+    expect(basher.blockers.map(blocker => blocker.type)).to.include('steel');
+    expect(basher.explanation.code).to.equal(
+      SOLVER_EXPLANATION_CODES.BARRIER_BLOCKED_BY_STEEL
+    );
+  });
+
+  it('builds deterministic graph edges and invalidates mutation-overlapping data', function () {
+    const graph = buildReachabilityGraph(createSmallGapFixture());
+    const repeat = buildReachabilityGraph(createSmallGapFixture());
+    const buildEdge = graph.edges.find(edge => edge.type === 'build');
+
+    expect(graph.graphHash).to.equal(repeat.graphHash);
+    expect(graph.nodes.some(node => node.type === 'entrance')).to.equal(true);
+    expect(graph.nodes.some(node => node.type === 'exit')).to.equal(true);
+    expect(buildEdge.requiredSkills).to.deep.equal(['builder']);
+    expect(buildEdge.mutation).to.include({ kind: 'builder-bridge', skillType: 'builder' });
+
+    const invalidation = invalidateReachabilityGraph(graph, buildEdge.mutation);
+    expect(invalidation.requiresRebuild).to.equal(true);
+    expect(invalidation.invalidatedEdgeIds).to.include(buildEdge.id);
+  });
+});
diff --git a/test/solver-integration.test.js b/test/solver-integration.test.js
new file mode 100644
index 00000000..9f8e00ca
--- /dev/null
+++ b/test/solver-integration.test.js
@@ -0,0 +1,39 @@
+import { expect } from 'chai';
+import {
+  SOLVER_RESULT_TYPES,
+  createSmallGapFixture,
+  verifyActionReplay
+} from '../js/solver/index.js';
+
+describe('solver public API integration', function() {
+  it('replays a curated synthetic mini-level through the public solver surface', function() {
+    const result = verifyActionReplay(createSmallGapFixture(), [
+      {
+        tick: 25,
+        skill: 'builder',
+        target: { id: 0 },
+        preconditions: [
+          { type: 'skillAvailable', skillType: 'builder', count: 1 },
+          'target-active'
+        ],
+        expectedPostconditions: [
+          { type: 'lemmingSaved', id: 0 },
+          { type: 'savedCountAtLeast', count: 1 }
+        ],
+        rationale: 'bridge the curated checkpoint mini-level gap'
+      }
+    ], {
+      maxTicks: 180,
+      maxActions: 2,
+      targetSaveCount: 1
+    });
+
+    expect(result.resultType).to.equal(SOLVER_RESULT_TYPES.SOLVED);
+    expect(result.replaySummary.savedCount).to.equal(1);
+    expect(result.replaySummary.appliedActions[0]).to.include({
+      tick: 25,
+      skillType: 'builder',
+      lemmingId: 0
+    });
+  });
+});
diff --git a/test/solver-runner.test.js b/test/solver-runner.test.js
new file mode 100644
index 00000000..d9b0f018
--- /dev/null
+++ b/test/solver-runner.test.js
@@ -0,0 +1,212 @@
+import { expect } from 'chai';
+import {
+  createFlatWalkFixture,
+  createSmallGapFixture
+} from '../js/solver/SolverFixtures.js';
+import {
+  SOLVER_EXPLANATION_CODES,
+  SOLVER_RESULT_TYPES
+} from '../js/solver/SolverTypes.js';
+import {
+  createBuiltInLevelRunner,
+  createEditorLevelRunner,
+  createProcgenChunkRunner,
+  createRunnerFromSource,
+  verifyActionReplay
+} from '../js/solver/SolverRunner.js';
+
+describe('SolverRunner', function () {
+  it('creates a deterministic runner from synthetic fixture descriptors', function () {
+    const created = createRunnerFromSource({
+      kind: 'synthetic',
+      fixture: createFlatWalkFixture()
+    });
+
+    expect(created.result).to.equal(null);
+    expect(created.sourceKind).to.equal('synthetic');
+    expect(created.runner.getFinalStateSummary()).to.include({
+      id: 'flat-walk',
+      tick: 0,
+      savedCount: 0
+    });
+  });
+
+  it('replays positive synthetic action scripts successfully', function () {
+    const result = verifyActionReplay(createSmallGapFixture(), [
+      {
+        tick: 25,
+        skill: 'builder',
+        target: { id: 0 },
+        preconditions: [
+          { type: 'skillAvailable', skillType: 'builder', count: 1 },
+          'target-active'
+        ],
+        expectedPostconditions: [
+          { type: 'lemmingSaved', id: 0 },
+          { type: 'savedCountAtLeast', count: 1 },
+          { type: 'skillRemainingAtLeast', skillType: 'builder', count: 1 }
+        ],
+        rationale: 'bridge the small synthetic gap'
+      }
+    ], {
+      maxTicks: 180,
+      maxActions: 2,
+      targetSaveCount: 1
+    });
+
+    expect(result.resultType).to.equal(SOLVER_RESULT_TYPES.SOLVED);
+    expect(result.actions).to.have.length(1);
+    expect(result.budgetUsage.actions).to.equal(1);
+    expect(result.replaySummary.savedCount).to.equal(1);
+    expect(result.replaySummary.appliedActions).to.eql([
+      {
+        index: 0,
+        tick: 25,
+        skillType: 'builder',
+        target: { id: 0 },
+        lemmingId: 0
+      }
+    ]);
+  });
+
+  it('reports replay divergence when expected postconditions are not met', function () {
+    const result = verifyActionReplay(createFlatWalkFixture(), [
+      {
+        tick: 0,
+        skill: 'wait',
+        target: { id: 0 },
+        expectedPostconditions: [
+          { type: 'savedCountAtLeast', count: 2 }
+        ],
+        rationale: 'intentionally impossible postcondition'
+      }
+    ], {
+      maxTicks: 160,
+      maxActions: 1,
+      targetSaveCount: 1
+    });
+
+    expect(result.resultType).to.equal(SOLVER_RESULT_TYPES.FAILED);
+    expect(result.explanations[0].code).to.equal(SOLVER_EXPLANATION_CODES.REPLAY_DIVERGED);
+    expect(result.replaySummary.savedCount).to.equal(1);
+    expect(result.replaySummary.appliedActions).to.have.length(1);
+  });
+
+  it('terminates cleanly when replay tick budgets are exhausted', function () {
+    const result = verifyActionReplay(createFlatWalkFixture(), [], {
+      maxTicks: 10,
+      maxNodes: 50,
+      targetSaveCount: 1
+    });
+
+    expect(result.resultType).to.equal(SOLVER_RESULT_TYPES.TIMEOUT);
+    expect(result.explanations[0].code).to.equal(SOLVER_EXPLANATION_CODES.BUDGET_EXHAUSTED);
+    expect(result.budgetUsage.ticks).to.equal(10);
+    expect(result.replaySummary.tick).to.equal(10);
+    expect(result.replaySummary.savedCount).to.equal(0);
+  });
+
+  it('returns stable unsupported results for non-synthetic source entrypoints', function () {
+    const unsupported = [
+      createEditorLevelRunner({ kind: 'editor' }),
+      createProcgenChunkRunner({ kind: 'procgen' }),
+      createBuiltInLevelRunner({ kind: 'builtin' })
+    ];
+
+    for (const created of unsupported) {
+      expect(created.runner).to.equal(null);
+      expect(created.result.resultType).to.equal(SOLVER_RESULT_TYPES.UNSUPPORTED);
+      expect(created.result.replaySummary).to.equal(null);
+      expect(created.result.explanations[0].code).to.equal(
+        SOLVER_EXPLANATION_CODES.UNSUPPORTED_MECHANIC
+      );
+    }
+  });
+
+  it('creates runtime-authoritative adapters for non-synthetic source entrypoints', function () {
+    const makeAdapter = (id) => {
+      let tick = 0;
+      let savedCount = 0;
+      return {
+        id,
+        isRuntimeAuthoritative: true,
+        step(count = 1) {
+          tick += count;
+          if (tick >= 3) savedCount = 1;
+        },
+        applyAction(action) {
+          return {
+            ok: true,
+            lemmingId: 7,
+            skillType: action.skillType
+          };
+        },
+        getFinalStateSummary() {
+          return {
+            id,
+            tick,
+            savedCount,
+            deadCount: 0,
+            activeCount: savedCount ? 0 : 1,
+            needCount: 1,
+            releaseCount: 1,
+            leftCount: 0,
+            lemmings: savedCount ? [] : [{ id: 7, x: tick, y: 0, action: 'walking' }]
+          };
+        }
+      };
+    };
+
+    for (const kind of ['editor', 'procgen', 'builtin']) {
+      const created = createRunnerFromSource({
+        kind,
+        runner: makeAdapter(`${kind}-adapter`)
+      });
+
+      expect(created.result).to.equal(null);
+      expect(created.sourceKind).to.equal(kind);
+      expect(created.runner.getFinalStateSummary()).to.include({
+        sourceKind: kind,
+        id: `${kind}-adapter`
+      });
+    }
+  });
+
+  it('requires authoritative runtime replay before non-synthetic solved results', function () {
+    let tick = 0;
+    const result = verifyActionReplay({
+      kind: 'editor',
+      runner: {
+        id: 'advisory-adapter',
+        isRuntimeAuthoritative: false,
+        step(count = 1) {
+          tick += count;
+        },
+        applyAction(action) {
+          return { ok: true, lemmingId: 0, skillType: action.skillType };
+        },
+        getFinalStateSummary() {
+          return {
+            id: 'advisory-adapter',
+            tick,
+            savedCount: tick >= 1 ? 1 : 0,
+            deadCount: 0,
+            activeCount: tick >= 1 ? 0 : 1,
+            needCount: 1,
+            releaseCount: 1,
+            leftCount: 0,
+            lemmings: tick >= 1 ? [] : [{ id: 0, x: 0, y: 0 }]
+          };
+        }
+      }
+    }, [], {
+      maxTicks: 4,
+      targetSaveCount: 1
+    });
+
+    expect(result.resultType).to.equal(SOLVER_RESULT_TYPES.UNKNOWN);
+    expect(result.explanations[0].code).to.equal(
+      SOLVER_EXPLANATION_CODES.MISSING_RUNTIME_ADAPTER
+    );
+  });
+});
diff --git a/test/solver-state-geometry.test.js b/test/solver-state-geometry.test.js
new file mode 100644
index 00000000..7387efce
--- /dev/null
+++ b/test/solver-state-geometry.test.js
@@ -0,0 +1,179 @@
+import { expect } from 'chai';
+import {
+  createBarrierFixture,
+  createFlatWalkFixture,
+  createSmallGapFixture,
+  createSyntheticSolverFixture
+} from '../js/solver/SolverFixtures.js';
+import {
+  extractSolverState,
+  stableHash
+} from '../js/solver/SolverState.js';
+import { analyzeSolverGeometry } from '../js/solver/SolverGeometry.js';
+import { Level } from '../js/level/Level.js';
+import { Trigger } from '../js/level/Trigger.js';
+import { TriggerTypes } from '../js/level/TriggerTypes.js';
+import { SkillTypes } from '../js/game/SkillTypes.js';
+import { Range } from '../js/util/Range.js';
+
+const setGroundRow = (level, y, x1, x2) => {
+  for (let x = x1; x <= x2; x += 1) {
+    level.groundMask.setGroundAt(x, y);
+  }
+};
+
+describe('solver state and geometry foundations', function() {
+  it('extracts deterministic snapshots and stable hashes from synthetic fixtures', function() {
+    const first = extractSolverState(createFlatWalkFixture());
+    const second = extractSolverState(createFlatWalkFixture());
+
+    expect(first.snapshotHash).to.equal(second.snapshotHash);
+    expect(first.terrainHash).to.equal(second.terrainHash);
+    expect(first.terrainMutationHash).to.equal(second.terrainMutationHash);
+    expect(stableHash({ b: 2, a: 1 })).to.equal(stableHash({ a: 1, b: 2 }));
+
+    const mutated = createFlatWalkFixture();
+    mutated.baseGroundMask = new Uint8Array(mutated.groundMask);
+    mutated.groundMask[52 * mutated.width] = 0;
+    const changed = extractSolverState(mutated);
+
+    expect(changed.terrainHash).to.equal(first.terrainHash);
+    expect(changed.terrainMutationHash).to.not.equal(first.terrainMutationHash);
+  });
+
+  it('normalizes terrain, steel, one-way, hazards, lemmings, skills, timer, and victory fields', function() {
+    const fixture = createSyntheticSolverFixture({
+      id: 'state-fields',
+      width: 80,
+      height: 48,
+      ground: [{ x: 0, y: 40, width: 80, height: 4 }],
+      steel: [{ x: 10, y: 38, width: 3, height: 2 }],
+      oneWay: [{ x: 20, y: 36, width: 8, height: 4, direction: 'right' }],
+      hazards: [{ x: 34, y: 38, width: 6, height: 4, kind: 'water' }],
+      entrances: [{ x: 4, y: 39 }],
+      exits: [{ x: 72, y: 39 }],
+      lemmings: [{ id: 3, x: 5, y: 39, lookRight: false, action: 'walking', canClimb: true }],
+      skills: { builder: 2, digger: 1 },
+      timer: { tick: 42, timeLimit: 120 },
+      needCount: 2,
+      releaseCount: 5
+    });
+
+    const snapshot = extractSolverState(fixture);
+
+    expect(snapshot.id).to.equal('state-fields');
+    expect(snapshot.terrain.solidCount).to.equal(320);
+    expect(snapshot.steel.solidCount).to.equal(6);
+    expect(snapshot.steel.constraints[0]).to.include({ x: 10, y: 38, width: 3, height: 2 });
+    expect(snapshot.oneWay[0]).to.include({ x: 20, y: 36, width: 8, height: 4, direction: 'right' });
+    expect(snapshot.hazards[0]).to.include({ x: 34, y: 38, width: 6, height: 4, kind: 'water' });
+    expect(snapshot.entrances[0]).to.include({ x: 4, y: 39, width: 1, height: 1 });
+    expect(snapshot.exits[0]).to.include({ x: 72, y: 39, width: 1, height: 1 });
+    expect(snapshot.lemmings[0]).to.include({ id: 3, x: 5, y: 39, direction: 'left', canClimb: true });
+    expect(snapshot.skills.counts).to.include({ builder: 2, digger: 1 });
+    expect(snapshot.timer).to.include({ tick: 42, timeLimit: 120 });
+    expect(snapshot.victory).to.include({ needCount: 2, releaseCount: 5 });
+  });
+
+  it('extracts constraints and triggers from Level-like objects', function() {
+    const level = new Level(96, 64);
+    level.id = 'level-like-state';
+    setGroundRow(level, 52, 0, 95);
+    level.steelMask.setMaskAt(12, 52);
+    level.setSteelAreas([Object.assign(new Range(), { x: 12, y: 50, width: 4, height: 3 })]);
+    level.setArrowAreas([Object.assign(new Range(), { x: 24, y: 48, width: 8, height: 4, direction: 1 })]);
+    level.entrances.push({ x: 6, y: 51 });
+    level.triggers.push(new Trigger(TriggerTypes.EXIT_LEVEL, 82, 47, 90, 54));
+    level.triggers.push(new Trigger(TriggerTypes.DROWN, 44, 50, 48, 56));
+    level.skills[SkillTypes.BUILDER] = 4;
+    level.releaseCount = 10;
+    level.needCount = 7;
+    level.timeLimit = 5;
+
+    const snapshot = extractSolverState(level);
+
+    expect(snapshot.sourceKind).to.equal('level');
+    expect(snapshot.steel.constraints[0]).to.include({ x: 12, y: 50, width: 4, height: 3 });
+    expect(snapshot.oneWay[0]).to.include({ x: 24, y: 48, width: 8, height: 4, direction: 'right' });
+    expect(snapshot.exits[0]).to.include({ x: 82, y: 47, width: 8, height: 7, kind: 'exit' });
+    expect(snapshot.hazards[0]).to.include({ x: 44, y: 50, width: 4, height: 6, kind: 'drown' });
+    expect(snapshot.skills.counts.builder).to.equal(4);
+    expect(snapshot.victory).to.include({ needCount: 7, releaseCount: 10 });
+  });
+
+  it('finds walkable surfaces and continuous routes on flat fixtures', function() {
+    const geometry = analyzeSolverGeometry(createFlatWalkFixture());
+
+    expect(geometry.surfaces).to.have.length(1);
+    expect(geometry.surfaces[0]).to.include({ x: 0, y: 51, width: 120 });
+    expect(geometry.landingZones[0]).to.include({ surfaceId: 0, safe: true });
+    expect(geometry.routeContinuity.continuous).to.equal(true);
+    expect(geometry.routeContinuity.blocked).to.equal(false);
+  });
+
+  it('detects small gaps and preserves bridgeable route continuity', function() {
+    const geometry = analyzeSolverGeometry(createSmallGapFixture());
+    const gap = geometry.gaps.find(item => item.width === 10);
+
+    expect(gap).to.include({
+      x: 48,
+      y: 57,
+      width: 10,
+      isSmall: true,
+      bridgeable: true
+    });
+    expect(geometry.routeContinuity.continuous).to.equal(true);
+  });
+
+  it('detects barriers and blocks direct route continuity', function() {
+    const geometry = analyzeSolverGeometry(createBarrierFixture());
+
+    expect(geometry.barriers).to.have.length(1);
+    expect(geometry.barriers[0]).to.include({ x: 62, y: 48, width: 8, height: 10 });
+    expect(geometry.routeContinuity.continuous).to.equal(false);
+    expect(geometry.routeContinuity.reachableSurfaceIds).to.include(0);
+  });
+
+  it('computes cliff fall distances and landing zones', function() {
+    const fixture = createSyntheticSolverFixture({
+      id: 'safe-fall',
+      width: 96,
+      height: 64,
+      ground: [
+        { x: 0, y: 31, width: 21, height: 3 },
+        { x: 21, y: 45, width: 70, height: 3 }
+      ],
+      entrances: [{ x: 6, y: 30 }],
+      exits: [{ x: 70, y: 44 }]
+    });
+
+    const geometry = analyzeSolverGeometry(fixture);
+    const cliff = geometry.cliffs.find(item => item.surfaceId === 0 && item.side === 'right');
+
+    expect(cliff).to.include({ x: 21, y: 30, fallDistance: 14, safe: true });
+    expect(cliff.landing).to.include({ x: 21, y: 44, surfaceId: 1 });
+    expect(geometry.landingZones[1].incomingFalls[0]).to.include({ fromSurfaceId: 0, fallDistance: 14 });
+    expect(geometry.routeContinuity.continuous).to.equal(true);
+  });
+
+  it('marks large gap routes as discontinuous', function() {
+    const fixture = createSyntheticSolverFixture({
+      id: 'large-gap',
+      width: 128,
+      height: 64,
+      ground: [
+        { x: 0, y: 52, width: 32, height: 4 },
+        { x: 82, y: 52, width: 46, height: 4 }
+      ],
+      entrances: [{ x: 8, y: 51 }],
+      exits: [{ x: 100, y: 51 }]
+    });
+
+    const geometry = analyzeSolverGeometry(fixture);
+    const gap = geometry.gaps.find(item => item.width === 50);
+
+    expect(gap).to.include({ isSmall: false, bridgeable: false });
+    expect(geometry.routeContinuity.continuous).to.equal(false);
+    expect(geometry.routeContinuity.blocked).to.equal(true);
+  });
+});
diff --git a/test/solver-tactical.test.js b/test/solver-tactical.test.js
new file mode 100644
index 00000000..79336547
--- /dev/null
+++ b/test/solver-tactical.test.js
@@ -0,0 +1,187 @@
+import { expect } from 'chai';
+import {
+  SOLVER_EXPLANATION_CODES,
+  SOLVER_RESULT_TYPES
+} from '../js/solver/SolverTypes.js';
+import {
+  createBarrierFixture,
+  createFlatWalkFixture,
+  createSmallGapFixture,
+  createSyntheticSolverFixture
+} from '../js/solver/SolverFixtures.js';
+import { solveTactical } from '../js/solver/TacticalSolver.js';
+
+const explanationCodes = result => result.explanations.map(explanation => explanation.code);
+
+const expectActionContract = action => {
+  expect(action.skillType).to.be.a('string').and.not.equal('');
+  expect(action.target).to.be.an('object');
+  expect(action.tick).to.be.a('number');
+  expect(action.window).to.include.keys(['start', 'end']);
+  expect(action.preconditions).to.be.an('array').and.not.empty;
+  expect(action.expectedPostconditions).to.be.an('array').and.not.empty;
+  expect(action.rationale).to.be.a('string').and.not.equal('');
+};
+
+describe('TacticalSolver', function() {
+  it('bridges a small local gap with a builder script', function() {
+    const result = solveTactical(createSmallGapFixture());
+
+    expect(result.resultType).to.equal(SOLVER_RESULT_TYPES.SOLVED);
+    expect(result.actions).to.have.lengthOf(1);
+    expect(result.actions[0].skillType).to.equal('builder');
+    expectActionContract(result.actions[0]);
+    expect(result.budgetUsage.actions).to.equal(1);
+    expect(result.replaySummary).to.deep.equal({
+      verifier: 'local-tactical-fixture',
+      verified: true
+    });
+  });
+
+  it('clears a simple barrier with a destructive skill script', function() {
+    const result = solveTactical(createBarrierFixture({
+      skills: { basher: 1 }
+    }));
+
+    expect(result.resultType).to.equal(SOLVER_RESULT_TYPES.SOLVED);
+    expect(result.actions).to.have.lengthOf(1);
+    expect(result.actions[0].skillType).to.equal('basher');
+    expect(result.actions[0].expectedPostconditions[0]).to.include('clears simple barrier');
+    expectActionContract(result.actions[0]);
+  });
+
+  it('assigns a floater before a lethal local fall', function() {
+    const fixture = createSyntheticSolverFixture({
+      id: 'floater-fall',
+      width: 100,
+      height: 140,
+      ground: [
+        { x: 0, y: 24, width: 32, height: 4 },
+        { x: 48, y: 116, width: 52, height: 4 }
+      ],
+      entrances: [{ x: 10, y: 23 }],
+      exits: [{ x: 84, y: 115 }],
+      lemmings: [{ id: 7, x: 12, y: 23, lookRight: true, action: 'walking' }],
+      skills: { floater: 1 }
+    });
+    fixture.fall = {
+      x: 34,
+      fromY: 23,
+      toY: 115,
+      safeFallDistance: 60,
+      assignmentTick: 48
+    };
+
+    const result = solveTactical(fixture);
+
+    expect(result.resultType).to.equal(SOLVER_RESULT_TYPES.SOLVED);
+    expect(result.actions).to.have.lengthOf(1);
+    expect(result.actions[0].skillType).to.equal('floater');
+    expect(result.actions[0].tick).to.equal(48);
+    expect(result.actions[0].target.id).to.equal(7);
+    expectActionContract(result.actions[0]);
+  });
+
+  it('places a blocker for a supported local turnaround', function() {
+    const fixture = createFlatWalkFixture({
+      id: 'blocker-turnaround',
+      skills: { blocker: 1 }
+    });
+    fixture.blockerTurnaround = {
+      x: 28,
+      y: 51,
+      assignmentTick: 24
+    };
+
+    const result = solveTactical(fixture);
+
+    expect(result.resultType).to.equal(SOLVER_RESULT_TYPES.SOLVED);
+    expect(result.actions).to.have.lengthOf(1);
+    expect(result.actions[0].skillType).to.equal('blocker');
+    expect(result.actions[0].target.role).to.equal('turnaround-anchor');
+    expect(result.actions[0].expectedPostconditions[0]).to.include('crowd turns');
+    expectActionContract(result.actions[0]);
+  });
+
+  it('fails with a no-route explanation when a gap has no builder support', function() {
+    const result = solveTactical(createSmallGapFixture({
+      skills: {}
+    }));
+
+    expect(result.resultType).to.equal(SOLVER_RESULT_TYPES.FAILED);
+    expect(explanationCodes(result)).to.include(SOLVER_EXPLANATION_CODES.NO_ROUTE_TO_EXIT);
+    expect(result.summary).to.include('No route');
+  });
+
+  it('fails when a gap exceeds the available builder budget', function() {
+    const result = solveTactical(createSyntheticSolverFixture({
+      id: 'large-gap',
+      width: 160,
+      height: 80,
+      ground: [
+        { x: 0, y: 62, width: 32, height: 4 },
+        { x: 98, y: 62, width: 62, height: 4 }
+      ],
+      entrances: [{ x: 8, y: 61 }],
+      exits: [{ x: 140, y: 61 }],
+      lemmings: [{ id: 0, x: 18, y: 61, lookRight: true, action: 'walking' }],
+      skills: { builder: 2 }
+    }));
+
+    expect(result.resultType).to.equal(SOLVER_RESULT_TYPES.FAILED);
+    expect(explanationCodes(result)).to.include(SOLVER_EXPLANATION_CODES.GAP_EXCEEDS_BUILDER_BUDGET);
+    expect(result.explanations[0].data.neededBuilders).to.be.greaterThan(2);
+  });
+
+  it('fails when a destructive barrier path intersects steel', function() {
+    const result = solveTactical(createBarrierFixture({
+      steel: [{ x: 62, y: 48, width: 8, height: 10 }],
+      skills: { basher: 1 }
+    }));
+
+    expect(result.resultType).to.equal(SOLVER_RESULT_TYPES.FAILED);
+    expect(explanationCodes(result)).to.include(SOLVER_EXPLANATION_CODES.BARRIER_BLOCKED_BY_STEEL);
+    expect(result.summary).to.include('steel');
+  });
+
+  it('returns unsupported for mechanics outside tactical scope', function() {
+    const fixture = createFlatWalkFixture();
+    fixture.requiredMechanic = 'climber-route';
+
+    const result = solveTactical(fixture);
+
+    expect(result.resultType).to.equal(SOLVER_RESULT_TYPES.UNSUPPORTED);
+    expect(explanationCodes(result)).to.include(SOLVER_EXPLANATION_CODES.UNSUPPORTED_MECHANIC);
+    expect(result.explanations[0].detail).to.include('climber-route');
+  });
+
+  it('returns unknown when a barrier exceeds the bounded local solver', function() {
+    const result = solveTactical(createSyntheticSolverFixture({
+      id: 'tall-barrier',
+      width: 140,
+      height: 90,
+      ground: [
+        { x: 0, y: 72, width: 140, height: 4 },
+        { x: 62, y: 40, width: 8, height: 32 }
+      ],
+      entrances: [{ x: 12, y: 71 }],
+      exits: [{ x: 120, y: 71 }],
+      lemmings: [{ id: 0, x: 20, y: 71, lookRight: true, action: 'walking' }],
+      skills: { basher: 1 }
+    }));
+
+    expect(result.resultType).to.equal(SOLVER_RESULT_TYPES.UNKNOWN);
+    expect(explanationCodes(result)).to.include(SOLVER_EXPLANATION_CODES.STATE_EXPLOSION);
+    expect(result.summary).to.include('bounds');
+  });
+
+  it('returns timeout when node budget is exhausted', function() {
+    const result = solveTactical(createSmallGapFixture(), {
+      maxNodes: 1
+    });
+
+    expect(result.resultType).to.equal(SOLVER_RESULT_TYPES.TIMEOUT);
+    expect(explanationCodes(result)).to.include(SOLVER_EXPLANATION_CODES.BUDGET_EXHAUSTED);
+    expect(result.budgetUsage.nodes).to.be.greaterThan(1);
+  });
+});
diff --git a/test/solver-types.test.js b/test/solver-types.test.js
new file mode 100644
index 00000000..f94fe55d
--- /dev/null
+++ b/test/solver-types.test.js
@@ -0,0 +1,96 @@
+import { expect } from 'chai';
+import {
+  SOLVER_EXPLANATION_CODES,
+  SOLVER_MODES,
+  SOLVER_RESULT_TYPES,
+  createBudgetMeter,
+  createSolverResult,
+  normalizeActionScriptAction,
+  normalizeSolverOptions
+} from '../js/solver/SolverTypes.js';
+import {
+  createFlatWalkFixture,
+  createSmallGapFixture,
+  fillRect
+} from '../js/solver/SolverFixtures.js';
+
+describe('SolverTypes', function() {
+  it('normalizes solver options with stable defaults and skill subsets', function() {
+    const options = normalizeSolverOptions({
+      seed: '12',
+      mode: SOLVER_MODES.FULL,
+      skills: ['builder', 'builder', ' digger '],
+      targetSaveCount: 2,
+      maxTicks: 0,
+      maxNodes: 4,
+      maxActions: 1,
+      maxWallTimeMs: 3
+    });
+    expect(options).to.deep.equal({
+      seed: 12,
+      mode: SOLVER_MODES.FULL,
+      skillSubset: ['builder', 'digger'],
+      targetSaveCount: 2,
+      maxTicks: 1,
+      maxNodes: 4,
+      maxActions: 1,
+      maxWallTimeMs: 3
+    });
+  });
+
+  it('normalizes action scripts and result payloads', function() {
+    const action = normalizeActionScriptAction({
+      skill: 'builder',
+      targetSelector: { kind: 'frontier' },
+      tick: 12.8,
+      window: { start: 10, end: 20 },
+      preconditions: ['walking'],
+      expectedPostconditions: ['bridge-started'],
+      rationale: 'bridge gap'
+    });
+    expect(action).to.deep.equal({
+      skillType: 'builder',
+      target: { kind: 'frontier' },
+      tick: 12,
+      window: { start: 10, end: 20 },
+      preconditions: ['walking'],
+      expectedPostconditions: ['bridge-started'],
+      rationale: 'bridge gap'
+    });
+
+    const result = createSolverResult({
+      resultType: SOLVER_RESULT_TYPES.SOLVED,
+      actions: [action],
+      explanations: [SOLVER_EXPLANATION_CODES.NO_ROUTE_TO_EXIT],
+      budgetUsage: { ticks: 5, nodes: 6, actions: 1, wallTimeMs: 2 }
+    });
+    expect(result.resultType).to.equal(SOLVER_RESULT_TYPES.SOLVED);
+    expect(result.actions).to.deep.equal([action]);
+    expect(result.explanations[0].code).to.equal(SOLVER_EXPLANATION_CODES.NO_ROUTE_TO_EXIT);
+  });
+
+  it('tracks budgets and produces timeout results', function() {
+    let time = 100;
+    const meter = createBudgetMeter({ maxNodes: 1, maxTicks: 2, maxActions: 1, maxWallTimeMs: 5 }, () => time);
+    meter.recordNode();
+    meter.recordTick(2);
+    meter.recordAction();
+    expect(meter.isExceeded()).to.equal(false);
+    time = 106;
+    expect(meter.isExceeded()).to.equal(true);
+    const result = meter.timeoutResult();
+    expect(result.resultType).to.equal(SOLVER_RESULT_TYPES.TIMEOUT);
+    expect(result.explanations[0].code).to.equal(SOLVER_EXPLANATION_CODES.BUDGET_EXHAUSTED);
+  });
+});
+
+describe('SolverFixtures', function() {
+  it('creates deterministic synthetic fixtures with mask helpers', function() {
+    const flat = createFlatWalkFixture();
+    const gap = createSmallGapFixture();
+    expect(flat.groundMask[52 * flat.width]).to.equal(1);
+    expect(gap.groundMask[58 * gap.width + 52]).to.equal(0);
+    fillRect(gap.groundMask, gap.width, gap.height, { x: 50, y: 58, width: 4, height: 4 }, 1);
+    expect(gap.groundMask[58 * gap.width + 52]).to.equal(1);
+  });
+});
diff --git a/test/sound-events.test.js b/test/sound-events.test.js
index 73029e22..bf61b7dc 100644
--- a/test/sound-events.test.js
+++ b/test/sound-events.test.js
@@ -1,6 +1,11 @@
 import { expect } from 'chai';
 import { withGlobalLemmings } from './helpers/lemmings.js';
-import { SoundEventBus, getSoundBus } from '../js/game/SoundEvents.js';
+import {
+  SoundEventBus,
+  SoundEventTypes,
+  SoundEffectIds,
+  getSoundBus
+} from '../js/game/SoundEvents.js';
 
 describe('SoundEventBus', function() {
   it('skips emit when event is missing or queue is disabled', function() {
@@ -54,6 +59,14 @@ describe('SoundEventBus', function() {
     expect(payload.sfxId).to.equal(2);
     expect(payload.data).to.equal(1);
   });
+
+  it('skips enqueueing when the queue is full and no listeners exist', function() {
+    const bus = new SoundEventBus({ getGameTicks: () => 0, frameTime: 60 });
+    bus._queueLimit = 1;
+    bus.emitSfx(SoundEventTypes.SKILL_SELECT, SoundEffectIds.SKILL_SELECT);
+    bus.emitSfx(SoundEventTypes.SKILL_ASSIGN, SoundEffectIds.SKILL_ASSIGN);
+    expect(bus._queue.length).to.equal(1);
+  });
 });
 
 describe('getSoundBus', function() {
@@ -64,26 +77,7 @@ describe('getSoundBus', function() {
     });
   });
 
-  it('falls back to lemmings global when globalThis is missing', function() {
-    const bus = new SoundEventBus(null);
-    const prev = Object.getOwnPropertyDescriptor(globalThis, 'lemmings');
-    let access = 0;
-    Object.defineProperty(globalThis, 'lemmings', {
-      configurable: true,
-      get() {
-        access += 1;
-        if (access === 1) return null;
-        return { game: { soundEvents: bus } };
-      }
-    });
-    try {
-      expect(getSoundBus()).to.equal(bus);
-    } finally {
-      if (prev) {
-        Object.defineProperty(globalThis, 'lemmings', prev);
-      } else {
-        delete globalThis.lemmings;
-      }
-    }
+  it('returns null when no app context is available', function() {
+    expect(getSoundBus()).to.equal(null);
   });
 });
diff --git a/test/soundevents.test.js b/test/soundevents.test.js
deleted file mode 100644
index 89cbff1b..00000000
--- a/test/soundevents.test.js
+++ /dev/null
@@ -1,59 +0,0 @@
-import { expect } from 'chai';
-import {
-  SoundEventBus,
-  SoundEventTypes,
-  SoundEffectIds,
-  getSoundBus
-} from '../js/game/SoundEvents.js';
-import { withGlobalLemmings } from './helpers/lemmings.js';
-
-describe('SoundEventBus', function() {
-  it('emits payloads with timer context and queues them', function() {
-    const timer = {
-      getGameTicks: () => 5,
-      frameTime: 50,
-      speedFactor: 2,
-      tps: 20
-    };
-    const bus = new SoundEventBus(timer);
-    const events = [];
-    bus.onEvent.on(evt => events.push(evt));
-
-    bus.emit({
-      type: SoundEventTypes.LEVEL_START,
-      sfxId: SoundEffectIds.LEVEL_START,
-      x: 3
-    });
-
-    expect(events.length).to.equal(1);
-    const payload = events[0];
-    expect(payload.tick).to.equal(5);
-    expect(payload.timeMs).to.equal(250);
-    expect(payload.frameMs).to.equal(50);
-    expect(payload.speedFactor).to.equal(2);
-    expect(payload.tps).to.equal(20);
-    expect(payload.type).to.equal(SoundEventTypes.LEVEL_START);
-    expect(payload.sfxId).to.equal(SoundEffectIds.LEVEL_START);
-
-    const flushed = bus.flush();
-    expect(flushed.length).to.equal(1);
-    expect(bus.flush().length).to.equal(0);
-  });
-
-  it('skips enqueueing when the queue is full and no listeners exist', function() {
-    const bus = new SoundEventBus({ getGameTicks: () => 0, frameTime: 60 });
-    bus._queueLimit = 1;
-    bus.emitSfx(SoundEventTypes.SKILL_SELECT, SoundEffectIds.SKILL_SELECT);
-    bus.emitSfx(SoundEventTypes.SKILL_ASSIGN, SoundEffectIds.SKILL_ASSIGN);
-    expect(bus._queue.length).to.equal(1);
-  });
-});
-
-describe('getSoundBus', function() {
-  it('returns the global game sound bus when available', function() {
-    const bus = new SoundEventBus({ getGameTicks: () => 0, frameTime: 60 });
-    withGlobalLemmings({ game: { soundEvents: bus } }, () => {
-      expect(getSoundBus()).to.equal(bus);
-    });
-  });
-});
diff --git a/test/support/canvas.js b/test/support/canvas.js
new file mode 100644
index 00000000..4bc76f09
--- /dev/null
+++ b/test/support/canvas.js
@@ -0,0 +1,12 @@
+const createCanvasStub = ({ width = 800, height = 480 } = {}) => {
+  return {
+    width,
+    height,
+    style: {},
+    getBoundingClientRect() {
+      return { x: 0, y: 0, width, height };
+    }
+  };
+};
+
+export { createCanvasStub };
diff --git a/test/support/deps.js b/test/support/deps.js
new file mode 100644
index 00000000..c37d08d8
--- /dev/null
+++ b/test/support/deps.js
@@ -0,0 +1,17 @@
+import { Lemmings, setDependency } from '../helpers/lemmings.js';
+
+const applyDependencyOverrides = (overrides = {}) => {
+  const entries = Object.entries(overrides || {});
+  const originals = new Map();
+  for (const [key, value] of entries) {
+    originals.set(key, Lemmings[key]);
+    setDependency(key, value);
+  }
+  return () => {
+    for (const [key, original] of originals.entries()) {
+      setDependency(key, original);
+    }
+  };
+};
+
+export { applyDependencyOverrides };
diff --git a/test/support/dom-fixtures.js b/test/support/dom-fixtures.js
new file mode 100644
index 00000000..57afefb1
--- /dev/null
+++ b/test/support/dom-fixtures.js
@@ -0,0 +1,8 @@
+const registerElement = (doc, tag, id, className = '') => {
+  const el = doc.createElement(tag);
+  if (className) el.className = className;
+  doc.registerElement(id, el);
+  return el;
+};
+
+export { registerElement };
diff --git a/test/support/globals.js b/test/support/globals.js
new file mode 100644
index 00000000..5eaff3c2
--- /dev/null
+++ b/test/support/globals.js
@@ -0,0 +1,54 @@
+const hasOwn = Object.prototype.hasOwnProperty;
+
+const captureGlobalValues = (keys) => {
+  const snapshot = keys.map((key) => ({
+    key,
+    had: hasOwn.call(globalThis, key),
+    value: globalThis[key]
+  }));
+  return () => {
+    snapshot.forEach(({ key, had, value }) => {
+      if (had) {
+        globalThis[key] = value;
+      } else {
+        delete globalThis[key];
+      }
+    });
+  };
+};
+
+const patchGlobalValues = (overrides) => {
+  const keys = Object.keys(overrides);
+  const restore = captureGlobalValues(keys);
+  keys.forEach((key) => {
+    globalThis[key] = overrides[key];
+  });
+  return restore;
+};
+
+const withPatchedGlobals = (overrides, fn) => {
+  const restore = patchGlobalValues(overrides);
+  try {
+    const result = fn();
+    if (result && typeof result.then === 'function') {
+      return result.finally(restore);
+    }
+    restore();
+    return result;
+  } catch (err) {
+    restore();
+    throw err;
+  }
+};
+
+const useGlobalValueRestore = (keys) => {
+  let restore = () => {};
+  beforeEach(() => {
+    restore = captureGlobalValues(keys);
+  });
+  afterEach(() => {
+    restore();
+  });
+};
+
+export { captureGlobalValues, patchGlobalValues, withPatchedGlobals, useGlobalValueRestore };
diff --git a/test/support/history-fixtures.js b/test/support/history-fixtures.js
new file mode 100644
index 00000000..f8c68e3b
--- /dev/null
+++ b/test/support/history-fixtures.js
@@ -0,0 +1,150 @@
+import { HistoryStore } from '../../js/game/HistoryStore.js';
+import { SkillTypes } from '../../js/game/SkillTypes.js';
+
+const createStubTimer = () => ({
+  tickIndex: 0,
+  speedFactor: 1,
+  frameTime: 60,
+  onBeforeGameTick: { on() {}, off() {} },
+  onGameTick: { on() {}, off() {} }
+});
+
+
+const createHistoryFixture = () => {
+  const timer = createStubTimer();
+  const walkAction = { name: 'walk' };
+  const bomberAction = { name: 'bomber' };
+  const lemming = {
+    id: 0,
+    x: 5,
+    y: 6,
+    lookRight: true,
+    frameIndex: 0,
+    state: 1,
+    canClimb: false,
+    hasParachute: false,
+    removed: false,
+    disabled: false,
+    countdown: 0,
+    hasExploded: false,
+    lastTriggerType: null,
+    action: walkAction,
+    countdownAction: null
+  };
+  const skillActions = [];
+  skillActions[SkillTypes.BOMBER] = bomberAction;
+  const manager = {
+    lemmings: [lemming],
+    activeLemmings: [lemming],
+    _activeDirty: false,
+    actions: [walkAction],
+    skillActions,
+    actionTypeByAction: new Map([[walkAction, 0]]),
+    selectedIndex: -1,
+    spawnTotal: 1,
+    releaseTickIndex: 0,
+    mmTickCounter: 0,
+    nextNukingLemmingsIndex: -1,
+    _nukeTargets: null,
+    miniMap: null,
+    _lemmingCtor: function ReplayCtor(x, y, id) {
+      this.x = x;
+      this.y = y;
+      this.id = id;
+    },
+    getLemming: (id) => manager.lemmings[id] ?? null
+  };
+  const skills = { selectedSkill: 0, cheatMode: false, skills: [1] };
+  const victory = {
+    releaseRate: 1,
+    minReleaseRate: 1,
+    leftCount: 1,
+    outCount: 0,
+    survivorCount: 0,
+    isFinalize: false
+  };
+  const level = {
+    entrances: [{ _opened: false }],
+    groundMask: { mask: new Uint8Array(4) },
+    groundImage: new Uint8ClampedArray(16),
+    objects: [],
+    triggers: []
+  };
+  const triggerManager = {
+    _triggers: new Set(),
+    add(trigger) { this._triggers.add(trigger); },
+    removeByOwner(owner) {
+      for (const trig of Array.from(this._triggers)) {
+        if (trig.owner === owner) this._triggers.delete(trig);
+      }
+    }
+  };
+  const game = {
+    level,
+    triggerManager,
+    finalGameState: 0,
+    getLemmingManager: () => manager,
+    getGameTimer: () => timer,
+    getGameSkills: () => skills,
+    getVictoryCondition: () => victory
+  };
+  const history = new HistoryStore({ keyframeInterval: 5 });
+  history.attach(game, { captureBaseline: true });
+  return {
+    history,
+    game,
+    timer,
+    manager,
+    skills,
+    victory,
+    level,
+    triggerManager,
+    lemming,
+    walkAction,
+    bomberAction
+  };
+};
+
+const recordTick = (history, timer, tickIndex, mutate, nextTick = tickIndex + 1) => {
+  history.beginTick(tickIndex);
+  if (mutate) mutate();
+  if (timer) timer.tickIndex = nextTick;
+  history.endTick();
+};
+
+const runHistoryOps = (history, ops) => {
+  for (const [method, ...args] of ops) {
+    history[method](...args);
+  }
+};
+
+const scenario = (history, timer) => {
+  const api = {
+    tick(tickIndex, { ops = null, mutate = null, nextTick } = {}) {
+      recordTick(history, timer, tickIndex, () => {
+        if (ops && ops.length) runHistoryOps(history, ops);
+        if (mutate) mutate();
+      }, nextTick);
+      return api;
+    }
+  };
+  return api;
+};
+
+const seedHistory = (history, { deltas = [], keyframes = [] } = {}) => {
+  for (const tick of deltas) {
+    history._setDelta(tick, history._allocDelta(tick));
+  }
+  for (const tick of keyframes) {
+    history._setKeyframe(tick, { tickIndex: tick });
+  }
+};
+
+export {
+  createHistoryFixture,
+  createStubTimer,
+  recordTick,
+  runHistoryOps,
+  scenario,
+  seedHistory
+};
diff --git a/test/support/midi-output.js b/test/support/midi-output.js
new file mode 100644
index 00000000..9f72d667
--- /dev/null
+++ b/test/support/midi-output.js
@@ -0,0 +1,18 @@
+const makeChannel = (id, calls) => ({
+  sendNoteOn(note, opts) { calls.push({ type: 'noteOn', id, note, opts }); },
+  sendNoteOff(note, opts) { calls.push({ type: 'noteOff', id, note, opts }); },
+  sendPitchBend(value, opts) { calls.push({ type: 'pitchBend', id, value, opts }); },
+  sendControlChange(cc, value, opts) { calls.push({ type: 'cc', id, cc, value, opts }); },
+  sendPitchBendRange(semitones, cents) { calls.push({ type: 'bendRange', id, semitones, cents }); },
+  sendAllNotesOff() { calls.push({ type: 'allNotesOff', id }); }
+});
+
+const makeOutput = (ids, calls, outputId = null) => {
+  const output = {
+    channels: Object.fromEntries(ids.map((id) => [id, makeChannel(id, calls)]))
+  };
+  if (outputId) output.id = outputId;
+  return output;
+};
+
+export { makeChannel, makeOutput };
diff --git a/test/support/scenario-table.js b/test/support/scenario-table.js
new file mode 100644
index 00000000..412eabf2
--- /dev/null
+++ b/test/support/scenario-table.js
@@ -0,0 +1,22 @@
+const runScenarioTable = (cases, runCase) => {
+  const scenarios = Array.isArray(cases) ? cases : [];
+  for (const scenario of scenarios) {
+    it(scenario.name, function () {
+      return runCase(scenario);
+    });
+  }
+};
+
+const runAsyncScenarioTable = (cases, runCase) => {
+  const scenarios = Array.isArray(cases) ? cases : [];
+  for (const scenario of scenarios) {
+    it(scenario.name, async function () {
+      await runCase(scenario);
+    });
+  }
+};
+
+export {
+  runAsyncScenarioTable,
+  runScenarioTable
+};
diff --git a/test/support/timers.js b/test/support/timers.js
new file mode 100644
index 00000000..19a64beb
--- /dev/null
+++ b/test/support/timers.js
@@ -0,0 +1,52 @@
+import FakeTimers from '@sinonjs/fake-timers';
+import { patchGlobalValues } from './globals.js';
+
+const DEFAULT_CLOCK_OPTIONS = {
+  now: 0,
+  toFake: ['setTimeout', 'clearTimeout', 'Date']
+};
+
+const installFakeClock = (options = {}) => (
+  FakeTimers.install({ ...DEFAULT_CLOCK_OPTIONS, ...options })
+);
+
+const isPromiseLike = (value) => (
+  !!value && typeof value.then === 'function'
+);
+
+const runWithCleanup = (fn, cleanup) => {
+  let result;
+  try {
+    result = fn();
+  } catch (error) {
+    cleanup();
+    throw error;
+  }
+  if (isPromiseLike(result)) {
+    return result.finally(cleanup);
+  }
+  cleanup();
+  return result;
+};
+
+const withFakeClock = (fn, options = {}) => {
+  const clock = installFakeClock(options);
+  return runWithCleanup(() => fn(clock), () => {
+    clock.uninstall();
+  });
+};
+
+const withFakeClockAndPerformance = (fn, options = {}) => {
+  const { performanceValue, ...clockOptions } = options;
+  const clock = installFakeClock(clockOptions);
+  const perf = typeof performanceValue === 'function'
+    ? performanceValue(clock)
+    : (performanceValue || { now: () => clock.now });
+  const restore = patchGlobalValues({ performance: perf });
+  return runWithCleanup(() => fn(clock), () => {
+    restore();
+    clock.uninstall();
+  });
+};
+
+export { installFakeClock, withFakeClock, withFakeClockAndPerformance };
diff --git a/test/support/timers.test.js b/test/support/timers.test.js
new file mode 100644
index 00000000..045201da
--- /dev/null
+++ b/test/support/timers.test.js
@@ -0,0 +1,27 @@
+import { expect } from 'chai';
+import { withFakeClock, withFakeClockAndPerformance } from './timers.js';
+
+describe('test support timers helpers', function () {
+  it('keeps fake Date active for async callbacks', async function () {
+    const result = await withFakeClock(async (clock) => {
+      clock.tick(42);
+      await Promise.resolve();
+      return Date.now();
+    });
+
+    expect(result).to.equal(42);
+    expect(Date.now()).to.not.equal(42);
+  });
+
+  it('keeps fake performance active for async callbacks', async function () {
+    const originalPerformance = globalThis.performance;
+    const value = await withFakeClockAndPerformance(async (clock) => {
+      clock.tick(15);
+      await Promise.resolve();
+      return globalThis.performance.now();
+    });
+
+    expect(value).to.equal(15);
+    expect(globalThis.performance).to.equal(originalPerformance);
+  });
+});
diff --git a/test/testing-docs.test.js b/test/testing-docs.test.js
new file mode 100644
index 00000000..e6edbca1
--- /dev/null
+++ b/test/testing-docs.test.js
@@ -0,0 +1,46 @@
+import fs from 'node:fs';
+import { expect } from 'chai';
+
+const testingDoc = fs.readFileSync('docs/TESTING.md', 'utf8');
+const packageJson = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+
+const extractNpmRunScripts = (text) => {
+  const scripts = new Set();
+  const pattern = /`npm run ([^`\s]+)(?:\s+[^`]*)?`/g;
+  let match;
+  while ((match = pattern.exec(text))) {
+    scripts.add(match[1]);
+  }
+  return [...scripts].sort();
+};
+
+describe('testing documentation', function () {
+  it('keeps milestone checkpoint commands aligned with package scripts', function () {
+    const section = testingDoc.split('## Milestone checkpoint evidence')[1] || '';
+    expect(section).to.include('Capture matrix');
+    const documentedScripts = extractNpmRunScripts(section);
+    expect(documentedScripts).to.include.members([
+      'capture:e2e:midi',
+      'capture:e2e:editor',
+      'capture:e2e:procgen',
+      'test-e2e',
+      'test-e2e:harness',
+      'test-editor',
+      'bench-procgen-soak',
+      'test-bench-unit',
+      'format',
+      'check-undefined',
+      'lint',
+      'typecheck:critical'
+    ]);
+    const missing = documentedScripts.filter(script => !packageJson.scripts[script]);
+    expect(missing).to.deep.equal([]);
+  });
+
+  it('documents disposable capture output instead of committed artifacts', function () {
+    const section = testingDoc.split('## Milestone checkpoint evidence')[1] || '';
+    expect(section).to.include('temp/e2e-captures/');
+    expect(section).to.include('do not create committed galleries or manifests');
+    expect(section).to.include('Use `npm run release-readiness` only when');
+  });
+});
diff --git a/test/time-travel-controller.edge.test.js b/test/time-travel-controller.edge.test.js
new file mode 100644
index 00000000..5f63ef67
--- /dev/null
+++ b/test/time-travel-controller.edge.test.js
@@ -0,0 +1,243 @@
+import { expect } from 'chai';
+import { TimeTravelController } from '../js/game/TimeTravelController.js';
+
+describe('TimeTravelController edge cases', function() {
+  it('uses TIME_PER_FRAME_MS and skips small reverse deltas', function() {
+    const originalWindow = globalThis.window;
+    const originalPerformance = globalThis.performance;
+    let rafCallback = null;
+    globalThis.performance = { now: () => 0 };
+    globalThis.window = {
+      requestAnimationFrame(cb) {
+        rafCallback = cb;
+        return 1;
+      },
+      cancelAnimationFrame() {}
+    };
+    try {
+      const timer = {
+        frameTime: 0,
+        TIME_PER_FRAME_MS: 20,
+        isRunning: () => false,
+        suspend() {}
+      };
+      const history = { pause() {}, resume() {} };
+      const game = { getGameTimer: () => timer, inputEnabled: true };
+      const controller = new TimeTravelController(game, history);
+      const steps = [];
+      controller.stepBackward = (count) => steps.push(count);
+
+      controller.startReverse();
+      rafCallback?.(10);
+      rafCallback?.(25);
+
+      expect(steps).to.eql([1]);
+      controller.stopReverse();
+    } finally {
+      globalThis.window = originalWindow;
+      globalThis.performance = originalPerformance;
+    }
+  });
+
+  it('uses a default frame time and skips inactive reverse loops', function() {
+    const originalWindow = globalThis.window;
+    const originalPerformance = globalThis.performance;
+    let rafCallback = null;
+    globalThis.performance = { now: () => 0 };
+    globalThis.window = {
+      requestAnimationFrame(cb) {
+        rafCallback = cb;
+        return 1;
+      },
+      cancelAnimationFrame() {}
+    };
+    try {
+      const timer = { frameTime: 0, TIME_PER_FRAME_MS: 0, isRunning: () => false, suspend() {} };
+      const history = { pause() {}, resume() {} };
+      const game = { getGameTimer: () => timer, inputEnabled: true };
+      const controller = new TimeTravelController(game, history);
+      controller.stepBackward = () => {};
+
+      controller.startReverse();
+      rafCallback?.(700);
+      controller._reverseActive = false;
+      rafCallback?.(800);
+    } finally {
+      globalThis.window = originalWindow;
+      globalThis.performance = originalPerformance;
+    }
+  });
+
+  it('skips reverse sound emission when sound bus is missing', function() {
+    const timer = { tickIndex: 1 };
+    const history = {};
+    const game = { getGameTimer: () => timer };
+    const controller = new TimeTravelController(game, history);
+    controller._emitReverseEvents({ soundEvents: [{ sfxId: 1 }] });
+  });
+
+  it('stops reverse safely when RAF APIs disappear', function() {
+    const originalWindow = globalThis.window;
+    const timer = { tickIndex: 0, isRunning: () => false };
+    const game = { getGameTimer: () => timer, inputEnabled: true };
+    const controller = new TimeTravelController(game, { resume() {} });
+    controller._reverseActive = true;
+    controller._reverseRaf = 123;
+    controller._resumeForward = false;
+    globalThis.window = undefined;
+    try {
+      expect(() => controller.stopReverse()).to.not.throw();
+      expect(controller.isReversing).to.equal(false);
+      expect(controller._reverseRaf).to.equal(0);
+    } finally {
+      globalThis.window = originalWindow;
+    }
+  });
+
+  it('stops reverse without resuming when already paused', function() {
+    const originalWindow = globalThis.window;
+    const originalPerformance = globalThis.performance;
+    let resumed = 0;
+    let truncated = 0;
+    let continued = 0;
+    globalThis.performance = { now: () => 0 };
+    globalThis.window = {
+      requestAnimationFrame() { return 1; },
+      cancelAnimationFrame() {}
+    };
+    try {
+      const timer = {
+        frameTime: 60,
+        TIME_PER_FRAME_MS: 60,
+        isRunning: () => false,
+        suspend() {},
+        continue() { continued += 1; }
+      };
+      const history = {
+        pause() {},
+        resume() { resumed += 1; },
+        truncateAfter() { truncated += 1; }
+      };
+      const game = { getGameTimer: () => timer, inputEnabled: true };
+      const controller = new TimeTravelController(game, history);
+
+      controller.startReverse();
+      controller.stopReverse();
+
+      expect(resumed).to.equal(1);
+      expect(truncated).to.equal(0);
+      expect(continued).to.equal(0);
+      expect(game.inputEnabled).to.equal(true);
+    } finally {
+      globalThis.window = originalWindow;
+      globalThis.performance = originalPerformance;
+    }
+  });
+
+  it('caps reverse steps per frame and carries remainder', function() {
+    const originalWindow = globalThis.window;
+    const originalPerformance = globalThis.performance;
+    let rafCallback = null;
+    globalThis.performance = { now: () => 0 };
+    globalThis.window = {
+      requestAnimationFrame(cb) {
+        rafCallback = cb;
+        return 1;
+      },
+      cancelAnimationFrame() {}
+    };
+    try {
+      const timer = {
+        frameTime: 10,
+        TIME_PER_FRAME_MS: 10,
+        isRunning: () => false,
+        suspend() {}
+      };
+      const history = {
+        pause() {},
+        resume() {}
+      };
+      const game = { getGameTimer: () => timer, inputEnabled: true };
+      const controller = new TimeTravelController(game, history);
+      const steps = [];
+      controller.stepBackward = (count) => steps.push(count);
+      controller.maxReverseStepsPerFrame = 3;
+
+      controller.startReverse();
+      rafCallback?.(100);
+      rafCallback?.(120);
+
+      expect(steps).to.eql([3, 3]);
+      expect(controller._reverseCarryMs).to.equal(60);
+
+      controller.stopReverse();
+      expect(controller._reverseCarryMs).to.equal(0);
+    } finally {
+      globalThis.window = originalWindow;
+      globalThis.performance = originalPerformance;
+    }
+  });
+
+  it('uses raw reverse steps when maxReverseStepsPerFrame is invalid', function() {
+    const originalWindow = globalThis.window;
+    const originalPerformance = globalThis.performance;
+    let rafCallback = null;
+    globalThis.performance = { now: () => 0 };
+    globalThis.window = {
+      requestAnimationFrame(cb) {
+        rafCallback = cb;
+        return 1;
+      },
+      cancelAnimationFrame() {}
+    };
+    try {
+      const timer = {
+        frameTime: 10,
+        TIME_PER_FRAME_MS: 10,
+        isRunning: () => false,
+        suspend() {}
+      };
+      const history = { pause() {}, resume() {} };
+      const game = { getGameTimer: () => timer, inputEnabled: true };
+      const controller = new TimeTravelController(game, history);
+      controller.maxReverseStepsPerFrame = Number.NaN;
+      const steps = [];
+      controller.stepBackward = (count) => steps.push(count);
+
+      controller.startReverse();
+      rafCallback?.(50);
+      expect(steps[0]).to.equal(5);
+      controller.stopReverse();
+    } finally {
+      globalThis.window = originalWindow;
+      globalThis.performance = originalPerformance;
+    }
+  });
+
+  it('falls back to seek when backward delta applier is missing', function() {
+    const timer = { tickIndex: 4, isRunning: () => false, suspend() {} };
+    const history = {
+      getDelta() { return { tick: 3 }; }
+    };
+    const game = { getGameTimer: () => timer, render() {} };
+    const controller = new TimeTravelController(game, history);
+    const seeks = [];
+    controller.seekToTick = (tick) => seeks.push(tick);
+
+    controller.stepBackward(1);
+
+    expect(seeks).to.eql([3]);
+  });
+
+  it('skips seek application when applyKeyframe is missing', function() {
+    const timer = { tickIndex: 2, isRunning: () => false, suspend() {} };
+    const history = {
+      getKeyframeAtOrBefore() { return { tickIndex: 0 }; }
+    };
+    const game = { getGameTimer: () => timer, render() {} };
+    const controller = new TimeTravelController(game, history);
+
+    expect(() => controller.seekToTick(1)).to.not.throw();
+    expect(timer.tickIndex).to.equal(2);
+  });
+});
diff --git a/test/time-travel-controller.reverse.test.js b/test/time-travel-controller.reverse.test.js
new file mode 100644
index 00000000..cd60c57a
--- /dev/null
+++ b/test/time-travel-controller.reverse.test.js
@@ -0,0 +1,244 @@
+import { expect } from 'chai';
+import { TimeTravelController } from '../js/game/TimeTravelController.js';
+
+describe('TimeTravelController reverse playback', function() {
+  it('seeks forward using keyframes and deltas', function() {
+    const timer = { tickIndex: 5, isRunning: () => false, suspend() {} };
+    const history = {
+      getKeyframeAtOrBefore() { return { tickIndex: 0 }; },
+      getDelta(tick) { return tick < 2 ? { tick } : null; },
+      applyKeyframe(game, keyframe) { game._keyframe = keyframe; },
+      applyDeltaForward(game, delta) { game._forward = (game._forward || 0) + 1; }
+    };
+    const game = {
+      getGameTimer: () => timer,
+      render() {},
+      gameGui: { gameTimeChanged: false }
+    };
+    const controller = new TimeTravelController(game, history);
+
+    controller.seekToTick(2);
+
+    expect(game._keyframe.tickIndex).to.equal(0);
+    expect(game._forward).to.equal(2);
+    expect(timer.tickIndex).to.equal(2);
+    expect(game.gameGui.gameTimeChanged).to.equal(true);
+  });
+
+  it('uses the target tick when keyframe tickIndex is missing', function() {
+    const timer = { tickIndex: 3, isRunning: () => false, suspend() {} };
+    const history = {
+      getKeyframeAtOrBefore() { return {}; },
+      applyKeyframe() {}
+    };
+    const game = { getGameTimer: () => timer, render() {} };
+    const controller = new TimeTravelController(game, history);
+
+    controller.seekToTick(5);
+
+    expect(timer.tickIndex).to.equal(5);
+  });
+
+  it('clamps keyframe tickIndex when keyframe is ahead of target', function() {
+    const timer = { tickIndex: 0, isRunning: () => false, suspend() {} };
+    const history = {
+      getKeyframeAtOrBefore() { return { tickIndex: 99 }; },
+      applyKeyframe() {},
+      getDelta() { return null; },
+      applyDeltaForward() {}
+    };
+    const game = { getGameTimer: () => timer, render() {} };
+    const controller = new TimeTravelController(game, history);
+
+    controller.seekToTick(5);
+
+    expect(timer.tickIndex).to.equal(5);
+  });
+
+  it('breaks seek loops when deltas are missing', function() {
+    const timer = { tickIndex: 0, isRunning: () => false, suspend() {} };
+    const history = {
+      getKeyframeAtOrBefore() { return { tickIndex: 0 }; },
+      getDelta() { return null; },
+      applyKeyframe() {},
+      applyDeltaForward() { throw new Error('should not apply'); }
+    };
+    const game = { getGameTimer: () => timer, render() {} };
+    const controller = new TimeTravelController(game, history);
+
+    controller.seekToTick(2);
+
+    expect(timer.tickIndex).to.equal(0);
+  });
+
+  it('suspends running timers and falls back to delta arrays', function() {
+    let suspended = 0;
+    const timer = { tickIndex: 0, isRunning: () => true, suspend() { suspended += 1; } };
+    const applied = [];
+    const history = {
+      getKeyframeAtOrBefore() { return { tickIndex: 0 }; },
+      getDelta() { return undefined; },
+      deltas: [{ tick: 0 }],
+      applyKeyframe() {},
+      applyDeltaForward(game, delta) { applied.push(delta); }
+    };
+    const game = { getGameTimer: () => timer, render() {} };
+    const controller = new TimeTravelController(game, history);
+
+    controller.seekToTick(1);
+
+    expect(suspended).to.equal(1);
+    expect(applied).to.have.length(1);
+  });
+
+  it('skips seek when no keyframe is available', function() {
+    const timer = { tickIndex: 3, isRunning: () => false, suspend() {} };
+    const history = { getKeyframeAtOrBefore() { return null; } };
+    const game = { getGameTimer: () => timer, render() {} };
+    const controller = new TimeTravelController(game, history);
+
+    controller.seekToTick(2);
+
+    expect(timer.tickIndex).to.equal(3);
+  });
+
+  it('toggles reverse playback and restores input state', function() {
+    const originalWindow = globalThis.window;
+    const originalPerformance = globalThis.performance;
+    let suspended = 0;
+    let continued = 0;
+    let paused = 0;
+    let resumed = 0;
+    let truncated = 0;
+    globalThis.performance = { now: () => 0 };
+    globalThis.window = {
+      requestAnimationFrame() { return 1; },
+      cancelAnimationFrame() {}
+    };
+    try {
+      const timer = {
+        frameTime: 60,
+        TIME_PER_FRAME_MS: 60,
+        isRunning: () => true,
+        suspend() { suspended += 1; },
+        continue() { continued += 1; }
+      };
+      const history = {
+        pause() { paused += 1; },
+        resume() { resumed += 1; },
+        truncateAfter() { truncated += 1; }
+      };
+      const game = { getGameTimer: () => timer, inputEnabled: true };
+      const controller = new TimeTravelController(game, history);
+
+      controller.startReverse();
+      expect(controller.isReversing).to.equal(true);
+      expect(suspended).to.equal(1);
+      expect(paused).to.equal(1);
+      expect(game.inputEnabled).to.equal(false);
+
+      controller.stopReverse();
+      expect(controller.isReversing).to.equal(false);
+      expect(resumed).to.equal(1);
+      expect(truncated).to.equal(1);
+      expect(continued).to.equal(1);
+      expect(game.inputEnabled).to.equal(true);
+    } finally {
+      globalThis.window = originalWindow;
+      globalThis.performance = originalPerformance;
+    }
+  });
+
+  it('uses a sane reverse frame time when timer frame time is invalid', function() {
+    const originalWindow = globalThis.window;
+    const originalPerformance = globalThis.performance;
+    let rafCallback = null;
+    globalThis.performance = { now: () => 0 };
+    globalThis.window = {
+      requestAnimationFrame(cb) {
+        rafCallback = cb;
+        return 1;
+      },
+      cancelAnimationFrame() {}
+    };
+    try {
+      const timer = {
+        frameTime: 0,
+        TIME_PER_FRAME_MS: 0,
+        isRunning: () => false,
+        suspend() {},
+        tickIndex: 100
+      };
+      const game = { getGameTimer: () => timer, inputEnabled: true };
+      const history = { pause() {}, resume() {} };
+      const controller = new TimeTravelController(game, history);
+      let steps = 0;
+      controller.stepBackward = (count) => { steps += count; };
+
+      controller.startReverse();
+      expect(controller.isReversing).to.equal(true);
+      expect(typeof rafCallback).to.equal('function');
+
+      rafCallback(30);
+      expect(steps).to.equal(0);
+      rafCallback(61);
+      expect(steps).to.equal(1);
+
+      controller.stopReverse();
+      expect(controller.isReversing).to.equal(false);
+    } finally {
+      globalThis.window = originalWindow;
+      globalThis.performance = originalPerformance;
+    }
+  });
+
+  it('stores prior input state when missing', function() {
+    const originalWindow = globalThis.window;
+    const originalPerformance = globalThis.performance;
+    globalThis.performance = { now: () => 0 };
+    globalThis.window = {
+      requestAnimationFrame() { return 1; },
+      cancelAnimationFrame() {}
+    };
+    try {
+      const timer = { frameTime: 60, TIME_PER_FRAME_MS: 60, isRunning: () => false, suspend() {} };
+      const history = { pause() {} };
+      const game = { getGameTimer: () => timer };
+      const controller = new TimeTravelController(game, history);
+
+      controller.startReverse();
+      expect(controller._prevInputEnabled).to.equal(true);
+    } finally {
+      globalThis.window = originalWindow;
+      globalThis.performance = originalPerformance;
+    }
+  });
+
+  it('marks game gui on reverse toggle', function() {
+    const originalWindow = globalThis.window;
+    const originalPerformance = globalThis.performance;
+    globalThis.performance = { now: () => 0 };
+    globalThis.window = {
+      requestAnimationFrame() { return 1; },
+      cancelAnimationFrame() {}
+    };
+    try {
+      const timer = { frameTime: 60, TIME_PER_FRAME_MS: 60, isRunning: () => false, suspend() {}, continue() {} };
+      const history = { pause() {}, resume() {} };
+      const game = { getGameTimer: () => timer, inputEnabled: true, gameGui: { gameTimeChanged: false } };
+      const controller = new TimeTravelController(game, history);
+
+      controller.toggleReverse();
+      expect(controller.isReversing).to.equal(true);
+      expect(game.gameGui.gameTimeChanged).to.equal(true);
+
+      game.gameGui.gameTimeChanged = false;
+      controller.toggleReverse();
+      expect(controller.isReversing).to.equal(false);
+      expect(game.gameGui.gameTimeChanged).to.equal(true);
+    } finally {
+      globalThis.window = originalWindow;
+      globalThis.performance = originalPerformance;
+    }
+  });
+});
diff --git a/test/time-travel-controller.seek.test.js b/test/time-travel-controller.seek.test.js
new file mode 100644
index 00000000..322d9121
--- /dev/null
+++ b/test/time-travel-controller.seek.test.js
@@ -0,0 +1,238 @@
+import { expect } from 'chai';
+import { TimeTravelController } from '../js/game/TimeTravelController.js';
+
+describe('TimeTravelController seek and retention', function() {
+  it('steps backward and emits reverse sound events', function() {
+    const applied = [];
+    const events = [];
+    const timer = {
+      tickIndex: 1,
+      isRunning: () => false,
+      suspend() {},
+      frameTime: 60,
+      TIME_PER_FRAME_MS: 60
+    };
+    const history = {
+      deltas: [],
+      getDelta(tick) { return this.deltas[tick]; },
+      applyDeltaBackward(game, delta) {
+        applied.push(delta);
+      }
+    };
+    const delta = { soundEvents: [{ sfxId: 2, type: 'test' }] };
+    history.deltas[0] = delta;
+    const game = {
+      getGameTimer: () => timer,
+      soundEvents: { emit: event => events.push(event) },
+      render() {},
+      gameGui: { gameTimeChanged: false }
+    };
+    const controller = new TimeTravelController(game, history);
+
+    controller.stepBackward(1);
+
+    expect(timer.tickIndex).to.equal(0);
+    expect(applied).to.have.length(1);
+    expect(events[0].reverse).to.equal(true);
+    expect(events[0].sfxId).to.equal(2);
+    expect(game.gameGui.gameTimeChanged).to.equal(true);
+  });
+
+  it('configures bounded history retention on construction', function() {
+    let received = null;
+    const history = {
+      configureRetention(policy) {
+        received = policy;
+        return { ...policy, preserveFutureHistory: false };
+      }
+    };
+    const controller = new TimeTravelController({}, history);
+    expect(received).to.eql({
+      enableHistoryCap: true,
+      historyCapTicks: 20000,
+      historyWarnTicks: 15000
+    });
+    expect(controller.getHistoryRetention()).to.eql({
+      enableHistoryCap: true,
+      historyCapTicks: 20000,
+      historyWarnTicks: 15000,
+      preserveFutureHistory: false
+    });
+  });
+
+  it('applies explicit history retention overrides', function() {
+    const calls = [];
+    const history = {
+      configureRetention(policy) {
+        calls.push(policy);
+        return { ...policy };
+      }
+    };
+    const controller = new TimeTravelController({}, history);
+    const applied = controller.setHistoryRetention({
+      historyCapTicks: 9000,
+      historyWarnTicks: 7000,
+      preserveFutureHistory: true
+    });
+    expect(calls).to.have.length(2);
+    expect(calls[1]).to.eql({
+      enableHistoryCap: true,
+      historyCapTicks: 9000,
+      historyWarnTicks: 7000,
+      preserveFutureHistory: true
+    });
+    expect(applied).to.eql(calls[1]);
+    expect(controller.getHistoryRetention()).to.eql(calls[1]);
+  });
+
+  it('preserves replay hash through seek and reverse playback operations', function() {
+    const timer = { tickIndex: 2, isRunning: () => false, suspend() {} };
+    const timeline = [{ tick: 0, x: 1 }, { tick: 1, x: 2 }];
+    const hash = () => JSON.stringify(timeline);
+    const history = {
+      getKeyframeAtOrBefore() { return { tickIndex: 0 }; },
+      getDelta(tick) { return timeline[tick] || null; },
+      applyKeyframe() {},
+      applyDeltaForward() {},
+      applyDeltaBackward() {},
+      computeReplayHash() { return hash(); }
+    };
+    const game = {
+      getGameTimer: () => timer,
+      render() {},
+      gameGui: { gameTimeChanged: false }
+    };
+    const controller = new TimeTravelController(game, history);
+    const before = history.computeReplayHash();
+
+    controller.seekToTick(1);
+    controller.stepBackward(1);
+
+    const after = history.computeReplayHash();
+    expect(after).to.equal(before);
+  });
+
+  it('preserves replay hash through long seek and reverse cycles', function() {
+    const timer = { tickIndex: 180, isRunning: () => false, suspend() {} };
+    const timeline = Array.from({ length: 240 }, (_, tick) => ({
+      tick,
+      soundEvents: tick % 15 === 0 ? [{ sfxId: tick % 8 }] : []
+    }));
+    const hash = () => JSON.stringify(timeline);
+    const history = {
+      getKeyframeAtOrBefore() { return { tickIndex: 0 }; },
+      getDelta(tick) { return timeline[tick] || null; },
+      applyKeyframe() {},
+      applyDeltaForward() {},
+      applyDeltaBackward() {},
+      computeReplayHash() { return hash(); }
+    };
+    const game = {
+      getGameTimer: () => timer,
+      render() {},
+      gameGui: { gameTimeChanged: false }
+    };
+    const controller = new TimeTravelController(game, history);
+    const before = history.computeReplayHash();
+
+    for (let i = 0; i < 40; i += 1) {
+      const seekTarget = (i * 13) % 180;
+      controller.seekToTick(seekTarget);
+      controller.stepBackward((i % 5) + 1);
+    }
+    controller.seekToTick(180);
+
+    const after = history.computeReplayHash();
+    expect(after).to.equal(before);
+  });
+
+  it('returns early when dependencies are missing', function() {
+    const controller = new TimeTravelController(null, null);
+    controller.stepBackward(1);
+    controller.seekToTick(1);
+    controller.startReverse();
+    expect(controller.isReversing).to.equal(false);
+  });
+
+  it('does not enter reverse mode when RAF APIs are unavailable', function() {
+    const originalWindow = globalThis.window;
+    const originalPerformance = globalThis.performance;
+    let suspended = 0;
+    let paused = 0;
+    globalThis.performance = { now: () => 0 };
+    globalThis.window = undefined;
+    try {
+      const timer = {
+        frameTime: 60,
+        TIME_PER_FRAME_MS: 60,
+        isRunning: () => true,
+        suspend() { suspended += 1; }
+      };
+      const history = { pause() { paused += 1; } };
+      const game = { getGameTimer: () => timer, inputEnabled: true };
+      const controller = new TimeTravelController(game, history);
+
+      controller.startReverse();
+
+      expect(controller.isReversing).to.equal(false);
+      expect(suspended).to.equal(0);
+      expect(paused).to.equal(0);
+      expect(game.inputEnabled).to.equal(true);
+    } finally {
+      globalThis.window = originalWindow;
+      globalThis.performance = originalPerformance;
+    }
+  });
+
+  it('suspends the timer when stepping backward while running', function() {
+    let suspended = 0;
+    const timer = {
+      tickIndex: 1,
+      isRunning: () => true,
+      suspend() { suspended += 1; }
+    };
+    const history = {
+      getDelta() { return { soundEvents: [] }; },
+      applyDeltaBackward() {}
+    };
+    const game = { getGameTimer: () => timer, render() {}, gameGui: { gameTimeChanged: false } };
+    const controller = new TimeTravelController(game, history);
+
+    controller.stepBackward(1);
+
+    expect(suspended).to.equal(1);
+  });
+
+  it('clamps backward steps at tick zero', function() {
+    const timer = {
+      tickIndex: 0,
+      isRunning: () => false,
+      suspend() {}
+    };
+    let applied = 0;
+    const history = {
+      applyDeltaBackward() { applied += 1; }
+    };
+    const game = { getGameTimer: () => timer, render() {} };
+    const controller = new TimeTravelController(game, history);
+
+    controller.stepBackward(3);
+
+    expect(timer.tickIndex).to.equal(0);
+    expect(applied).to.equal(0);
+  });
+
+  it('seeks backward when a delta is missing', function() {
+    const timer = { tickIndex: 2, isRunning: () => false, suspend() {} };
+    const history = { deltas: [], getDelta() { return null; } };
+    const game = { getGameTimer: () => timer, render() {} };
+    const controller = new TimeTravelController(game, history);
+    const calls = [];
+    controller.seekToTick = (tick) => calls.push(tick);
+
+    controller.stepBackward(1);
+
+    expect(calls).to.eql([1]);
+    expect(timer.tickIndex).to.equal(2);
+  });
+});
diff --git a/test/time-travel-controller.test.js b/test/time-travel-controller.test.js
deleted file mode 100644
index c652e274..00000000
--- a/test/time-travel-controller.test.js
+++ /dev/null
@@ -1,475 +0,0 @@
-import { expect } from 'chai';
-import { TimeTravelController } from '../js/game/TimeTravelController.js';
-
-describe('TimeTravelController', function() {
-  it('steps backward and emits reverse sound events', function() {
-    const applied = [];
-    const events = [];
-    const timer = {
-      tickIndex: 1,
-      isRunning: () => false,
-      suspend() {},
-      frameTime: 60,
-      TIME_PER_FRAME_MS: 60
-    };
-    const history = {
-      deltas: [],
-      getDelta(tick) { return this.deltas[tick]; },
-      applyDeltaBackward(game, delta) {
-        applied.push(delta);
-      }
-    };
-    const delta = { soundEvents: [{ sfxId: 2, type: 'test' }] };
-    history.deltas[0] = delta;
-    const game = {
-      getGameTimer: () => timer,
-      soundEvents: { emit: event => events.push(event) },
-      render() {},
-      gameGui: { gameTimeChanged: false }
-    };
-    const controller = new TimeTravelController(game, history);
-
-    controller.stepBackward(1);
-
-    expect(timer.tickIndex).to.equal(0);
-    expect(applied).to.have.length(1);
-    expect(events[0].reverse).to.equal(true);
-    expect(events[0].sfxId).to.equal(2);
-    expect(game.gameGui.gameTimeChanged).to.equal(true);
-  });
-
-  it('returns early when dependencies are missing', function() {
-    const controller = new TimeTravelController(null, null);
-    controller.stepBackward(1);
-    controller.seekToTick(1);
-    controller.startReverse();
-    expect(controller.isReversing).to.equal(false);
-  });
-
-  it('suspends the timer when stepping backward while running', function() {
-    let suspended = 0;
-    const timer = {
-      tickIndex: 1,
-      isRunning: () => true,
-      suspend() { suspended += 1; }
-    };
-    const history = {
-      getDelta() { return { soundEvents: [] }; },
-      applyDeltaBackward() {}
-    };
-    const game = { getGameTimer: () => timer, render() {}, gameGui: { gameTimeChanged: false } };
-    const controller = new TimeTravelController(game, history);
-
-    controller.stepBackward(1);
-
-    expect(suspended).to.equal(1);
-  });
-
-  it('clamps backward steps at tick zero', function() {
-    const timer = {
-      tickIndex: 0,
-      isRunning: () => false,
-      suspend() {}
-    };
-    let applied = 0;
-    const history = {
-      applyDeltaBackward() { applied += 1; }
-    };
-    const game = { getGameTimer: () => timer, render() {} };
-    const controller = new TimeTravelController(game, history);
-
-    controller.stepBackward(3);
-
-    expect(timer.tickIndex).to.equal(0);
-    expect(applied).to.equal(0);
-  });
-
-  it('seeks backward when a delta is missing', function() {
-    const timer = { tickIndex: 2, isRunning: () => false, suspend() {} };
-    const history = { deltas: [], getDelta() { return null; } };
-    const game = { getGameTimer: () => timer, render() {} };
-    const controller = new TimeTravelController(game, history);
-    const calls = [];
-    controller.seekToTick = (tick) => calls.push(tick);
-
-    controller.stepBackward(1);
-
-    expect(calls).to.eql([1]);
-    expect(timer.tickIndex).to.equal(2);
-  });
-
-  it('seeks forward using keyframes and deltas', function() {
-    const timer = { tickIndex: 5, isRunning: () => false, suspend() {} };
-    const history = {
-      getKeyframeAtOrBefore() { return { tickIndex: 0 }; },
-      getDelta(tick) { return tick < 2 ? { tick } : null; },
-      applyKeyframe(game, keyframe) { game._keyframe = keyframe; },
-      applyDeltaForward(game, delta) { game._forward = (game._forward || 0) + 1; }
-    };
-    const game = {
-      getGameTimer: () => timer,
-      render() {},
-      gameGui: { gameTimeChanged: false }
-    };
-    const controller = new TimeTravelController(game, history);
-
-    controller.seekToTick(2);
-
-    expect(game._keyframe.tickIndex).to.equal(0);
-    expect(game._forward).to.equal(2);
-    expect(timer.tickIndex).to.equal(2);
-    expect(game.gameGui.gameTimeChanged).to.equal(true);
-  });
-
-  it('uses the target tick when keyframe tickIndex is missing', function() {
-    const timer = { tickIndex: 3, isRunning: () => false, suspend() {} };
-    const history = {
-      getKeyframeAtOrBefore() { return {}; },
-      applyKeyframe() {}
-    };
-    const game = { getGameTimer: () => timer, render() {} };
-    const controller = new TimeTravelController(game, history);
-
-    controller.seekToTick(5);
-
-    expect(timer.tickIndex).to.equal(5);
-  });
-
-  it('breaks seek loops when deltas are missing', function() {
-    const timer = { tickIndex: 0, isRunning: () => false, suspend() {} };
-    const history = {
-      getKeyframeAtOrBefore() { return { tickIndex: 0 }; },
-      getDelta() { return null; },
-      applyKeyframe() {},
-      applyDeltaForward() { throw new Error('should not apply'); }
-    };
-    const game = { getGameTimer: () => timer, render() {} };
-    const controller = new TimeTravelController(game, history);
-
-    controller.seekToTick(2);
-
-    expect(timer.tickIndex).to.equal(0);
-  });
-
-  it('suspends running timers and falls back to delta arrays', function() {
-    let suspended = 0;
-    const timer = { tickIndex: 0, isRunning: () => true, suspend() { suspended += 1; } };
-    const applied = [];
-    const history = {
-      getKeyframeAtOrBefore() { return { tickIndex: 0 }; },
-      getDelta() { return undefined; },
-      deltas: [{ tick: 0 }],
-      applyKeyframe() {},
-      applyDeltaForward(game, delta) { applied.push(delta); }
-    };
-    const game = { getGameTimer: () => timer, render() {} };
-    const controller = new TimeTravelController(game, history);
-
-    controller.seekToTick(1);
-
-    expect(suspended).to.equal(1);
-    expect(applied).to.have.length(1);
-  });
-
-  it('skips seek when no keyframe is available', function() {
-    const timer = { tickIndex: 3, isRunning: () => false, suspend() {} };
-    const history = { getKeyframeAtOrBefore() { return null; } };
-    const game = { getGameTimer: () => timer, render() {} };
-    const controller = new TimeTravelController(game, history);
-
-    controller.seekToTick(2);
-
-    expect(timer.tickIndex).to.equal(3);
-  });
-
-  it('toggles reverse playback and restores input state', function() {
-    const originalWindow = globalThis.window;
-    const originalPerformance = globalThis.performance;
-    let suspended = 0;
-    let continued = 0;
-    let paused = 0;
-    let resumed = 0;
-    let truncated = 0;
-    globalThis.performance = { now: () => 0 };
-    globalThis.window = {
-      requestAnimationFrame() { return 1; },
-      cancelAnimationFrame() {}
-    };
-    try {
-      const timer = {
-        frameTime: 60,
-        TIME_PER_FRAME_MS: 60,
-        isRunning: () => true,
-        suspend() { suspended += 1; },
-        continue() { continued += 1; }
-      };
-      const history = {
-        pause() { paused += 1; },
-        resume() { resumed += 1; },
-        truncateAfter() { truncated += 1; }
-      };
-      const game = { getGameTimer: () => timer, inputEnabled: true };
-      const controller = new TimeTravelController(game, history);
-
-      controller.startReverse();
-      expect(controller.isReversing).to.equal(true);
-      expect(suspended).to.equal(1);
-      expect(paused).to.equal(1);
-      expect(game.inputEnabled).to.equal(false);
-
-      controller.stopReverse();
-      expect(controller.isReversing).to.equal(false);
-      expect(resumed).to.equal(1);
-      expect(truncated).to.equal(1);
-      expect(continued).to.equal(1);
-      expect(game.inputEnabled).to.equal(true);
-    } finally {
-      globalThis.window = originalWindow;
-      globalThis.performance = originalPerformance;
-    }
-  });
-
-  it('stores prior input state when missing', function() {
-    const originalWindow = globalThis.window;
-    const originalPerformance = globalThis.performance;
-    globalThis.performance = { now: () => 0 };
-    globalThis.window = {
-      requestAnimationFrame() { return 1; },
-      cancelAnimationFrame() {}
-    };
-    try {
-      const timer = { frameTime: 60, TIME_PER_FRAME_MS: 60, isRunning: () => false, suspend() {} };
-      const history = { pause() {} };
-      const game = { getGameTimer: () => timer };
-      const controller = new TimeTravelController(game, history);
-
-      controller.startReverse();
-      expect(controller._prevInputEnabled).to.equal(true);
-    } finally {
-      globalThis.window = originalWindow;
-      globalThis.performance = originalPerformance;
-    }
-  });
-
-  it('marks game gui on reverse toggle', function() {
-    const originalWindow = globalThis.window;
-    const originalPerformance = globalThis.performance;
-    globalThis.performance = { now: () => 0 };
-    globalThis.window = {
-      requestAnimationFrame() { return 1; },
-      cancelAnimationFrame() {}
-    };
-    try {
-      const timer = { frameTime: 60, TIME_PER_FRAME_MS: 60, isRunning: () => false, suspend() {}, continue() {} };
-      const history = { pause() {}, resume() {} };
-      const game = { getGameTimer: () => timer, inputEnabled: true, gameGui: { gameTimeChanged: false } };
-      const controller = new TimeTravelController(game, history);
-
-      controller.toggleReverse();
-      expect(controller.isReversing).to.equal(true);
-      expect(game.gameGui.gameTimeChanged).to.equal(true);
-
-      game.gameGui.gameTimeChanged = false;
-      controller.toggleReverse();
-      expect(controller.isReversing).to.equal(false);
-      expect(game.gameGui.gameTimeChanged).to.equal(true);
-    } finally {
-      globalThis.window = originalWindow;
-      globalThis.performance = originalPerformance;
-    }
-  });
-
-  it('uses TIME_PER_FRAME_MS and skips small reverse deltas', function() {
-    const originalWindow = globalThis.window;
-    const originalPerformance = globalThis.performance;
-    let rafCallback = null;
-    globalThis.performance = { now: () => 0 };
-    globalThis.window = {
-      requestAnimationFrame(cb) {
-        rafCallback = cb;
-        return 1;
-      },
-      cancelAnimationFrame() {}
-    };
-    try {
-      const timer = {
-        frameTime: 0,
-        TIME_PER_FRAME_MS: 20,
-        isRunning: () => false,
-        suspend() {}
-      };
-      const history = { pause() {}, resume() {} };
-      const game = { getGameTimer: () => timer, inputEnabled: true };
-      const controller = new TimeTravelController(game, history);
-      const steps = [];
-      controller.stepBackward = (count) => steps.push(count);
-
-      controller.startReverse();
-      rafCallback?.(10);
-      rafCallback?.(25);
-
-      expect(steps).to.eql([1]);
-      controller.stopReverse();
-    } finally {
-      globalThis.window = originalWindow;
-      globalThis.performance = originalPerformance;
-    }
-  });
-
-  it('uses a default frame time and skips inactive reverse loops', function() {
-    const originalWindow = globalThis.window;
-    const originalPerformance = globalThis.performance;
-    let rafCallback = null;
-    globalThis.performance = { now: () => 0 };
-    globalThis.window = {
-      requestAnimationFrame(cb) {
-        rafCallback = cb;
-        return 1;
-      },
-      cancelAnimationFrame() {}
-    };
-    try {
-      const timer = { frameTime: 0, TIME_PER_FRAME_MS: 0, isRunning: () => false, suspend() {} };
-      const history = { pause() {}, resume() {} };
-      const game = { getGameTimer: () => timer, inputEnabled: true };
-      const controller = new TimeTravelController(game, history);
-      controller.stepBackward = () => {};
-
-      controller.startReverse();
-      rafCallback?.(700);
-      controller._reverseActive = false;
-      rafCallback?.(800);
-    } finally {
-      globalThis.window = originalWindow;
-      globalThis.performance = originalPerformance;
-    }
-  });
-
-  it('skips reverse sound emission when sound bus is missing', function() {
-    const timer = { tickIndex: 1 };
-    const history = {};
-    const game = { getGameTimer: () => timer };
-    const controller = new TimeTravelController(game, history);
-    controller._emitReverseEvents({ soundEvents: [{ sfxId: 1 }] });
-  });
-
-  it('stops reverse without resuming when already paused', function() {
-    const originalWindow = globalThis.window;
-    const originalPerformance = globalThis.performance;
-    let resumed = 0;
-    let truncated = 0;
-    let continued = 0;
-    globalThis.performance = { now: () => 0 };
-    globalThis.window = {
-      requestAnimationFrame() { return 1; },
-      cancelAnimationFrame() {}
-    };
-    try {
-      const timer = {
-        frameTime: 60,
-        TIME_PER_FRAME_MS: 60,
-        isRunning: () => false,
-        suspend() {},
-        continue() { continued += 1; }
-      };
-      const history = {
-        pause() {},
-        resume() { resumed += 1; },
-        truncateAfter() { truncated += 1; }
-      };
-      const game = { getGameTimer: () => timer, inputEnabled: true };
-      const controller = new TimeTravelController(game, history);
-
-      controller.startReverse();
-      controller.stopReverse();
-
-      expect(resumed).to.equal(1);
-      expect(truncated).to.equal(0);
-      expect(continued).to.equal(0);
-      expect(game.inputEnabled).to.equal(true);
-    } finally {
-      globalThis.window = originalWindow;
-      globalThis.performance = originalPerformance;
-    }
-  });
-
-  it('caps reverse steps per frame and carries remainder', function() {
-    const originalWindow = globalThis.window;
-    const originalPerformance = globalThis.performance;
-    let rafCallback = null;
-    globalThis.performance = { now: () => 0 };
-    globalThis.window = {
-      requestAnimationFrame(cb) {
-        rafCallback = cb;
-        return 1;
-      },
-      cancelAnimationFrame() {}
-    };
-    try {
-      const timer = {
-        frameTime: 10,
-        TIME_PER_FRAME_MS: 10,
-        isRunning: () => false,
-        suspend() {}
-      };
-      const history = {
-        pause() {},
-        resume() {}
-      };
-      const game = { getGameTimer: () => timer, inputEnabled: true };
-      const controller = new TimeTravelController(game, history);
-      const steps = [];
-      controller.stepBackward = (count) => steps.push(count);
-      controller.maxReverseStepsPerFrame = 3;
-
-      controller.startReverse();
-      rafCallback?.(100);
-      rafCallback?.(120);
-
-      expect(steps).to.eql([3, 3]);
-      expect(controller._reverseCarryMs).to.equal(60);
-
-      controller.stopReverse();
-      expect(controller._reverseCarryMs).to.equal(0);
-    } finally {
-      globalThis.window = originalWindow;
-      globalThis.performance = originalPerformance;
-    }
-  });
-
-  it('uses raw reverse steps when maxReverseStepsPerFrame is invalid', function() {
-    const originalWindow = globalThis.window;
-    const originalPerformance = globalThis.performance;
-    let rafCallback = null;
-    globalThis.performance = { now: () => 0 };
-    globalThis.window = {
-      requestAnimationFrame(cb) {
-        rafCallback = cb;
-        return 1;
-      },
-      cancelAnimationFrame() {}
-    };
-    try {
-      const timer = {
-        frameTime: 10,
-        TIME_PER_FRAME_MS: 10,
-        isRunning: () => false,
-        suspend() {}
-      };
-      const history = { pause() {}, resume() {} };
-      const game = { getGameTimer: () => timer, inputEnabled: true };
-      const controller = new TimeTravelController(game, history);
-      controller.maxReverseStepsPerFrame = Number.NaN;
-      const steps = [];
-      controller.stepBackward = (count) => steps.push(count);
-
-      controller.startReverse();
-      rafCallback?.(50);
-      expect(steps[0]).to.equal(5);
-      controller.stopReverse();
-    } finally {
-      globalThis.window = originalWindow;
-      globalThis.performance = originalPerformance;
-    }
-  });
-});
diff --git a/test/tools/nodefileprovider.test.js b/test/tools/nodefileprovider.test.js
index 5ca565e9..12b37b76 100644
--- a/test/tools/nodefileprovider.test.js
+++ b/test/tools/nodefileprovider.test.js
@@ -23,6 +23,28 @@ const packFile = path.join(rootDir, 'lemmings', 'LEVEL000.DAT');
 describe('NodeFileProvider', function() {
   let tmpDir;
   const makeProvider = (options) => new NodeFileProvider(tmpDir, options);
+  const writeNxp = (nxpPath, entries) => {
+    const tableEntrySize = 36;
+    const headerSize = 4 + (entries.length * tableEntrySize);
+    const dataSize = entries.reduce((sum, entry) => sum + entry.data.length, 0);
+    const out = Buffer.alloc(headerSize + dataSize);
+    out.writeUInt32LE(entries.length, 0);
+    let dataOffset = headerSize;
+    for (let i = 0; i < entries.length; i += 1) {
+      const entry = entries[i];
+      const base = 4 + (i * tableEntrySize);
+      const nameBuf = Buffer.from(entry.name, 'utf8');
+      if (nameBuf.length > 27) {
+        throw new Error(`NXP test entry name too long: ${entry.name}`);
+      }
+      nameBuf.copy(out, base);
+      out.writeUInt32LE(dataOffset, base + 28);
+      out.writeUInt32LE(entry.data.length, base + 32);
+      entry.data.copy(out, dataOffset);
+      dataOffset += entry.data.length;
+    }
+    fs.writeFileSync(nxpPath, out);
+  };
   const writeRarStub = () => {
     const rarPath = path.join(tmpDir, 'pack.rar');
     fs.writeFileSync(rarPath, Buffer.from([0]));
@@ -33,11 +55,16 @@ describe('NodeFileProvider', function() {
     tmpDir = fs.mkdtempSync(path.join(process.cwd(), 'test', 'tmp-nodefileprovider-'));
     fs.mkdirSync(path.join(tmpDir, 'data'), { recursive: true });
     fs.copyFileSync(packFile, path.join(tmpDir, 'LEVEL000.DAT'));
+    fs.copyFileSync(packFile, path.join(tmpDir, 'LEVEL..000.DAT'));
     fs.copyFileSync(packFile, path.join(tmpDir, 'data', 'LEVEL000.DAT'));
     const zip = new AdmZip();
     zip.addFile('data/LEVEL000.DAT', fs.readFileSync(packFile));
     zip.writeZip(path.join(tmpDir, 'pack.zip'));
     await tar.c({ file: path.join(tmpDir, 'pack.tar'), cwd: tmpDir }, ['data/LEVEL000.DAT']);
+    writeNxp(path.join(tmpDir, 'pack.nxp'), [
+      { name: 'data/LEVEL000.DAT', data: fs.readFileSync(packFile) },
+      { name: 'docs/readme.txt', data: Buffer.from('nxp-text') }
+    ]);
   });
 
   afterEach(function() {
@@ -64,6 +91,27 @@ describe('NodeFileProvider', function() {
 
     const tarLower = await provider.loadBinary('pack.tar', 'data/level000.dat');
     expect(tarLower.length).to.equal(buffer.length);
+
+    const nxpReader = await provider.loadBinary('pack.nxp', 'data/LEVEL000.DAT');
+    expect(nxpReader.length).to.equal(buffer.length);
+
+    const nxpLower = await provider.loadBinary('pack.nxp', 'data/level000.dat');
+    expect(nxpLower.length).to.equal(buffer.length);
+  });
+
+  it('loads archive entries when archive paths include trailing separators', async function() {
+    const provider = makeProvider();
+    const zipReader = await provider.loadBinary('pack.zip/', 'data/LEVEL000.DAT');
+    expect(zipReader.length).to.equal(fs.readFileSync(packFile).length);
+
+    const tarReader = await provider.loadBinary('pack.tar/', 'data/LEVEL000.DAT');
+    expect(tarReader.length).to.equal(fs.readFileSync(packFile).length);
+  });
+
+  it('defaults binary directory paths to provider root when omitted', async function() {
+    const provider = makeProvider();
+    const reader = await provider.loadBinary(undefined, 'LEVEL000.DAT');
+    expect(reader.length).to.equal(fs.readFileSync(packFile).length);
   });
 
   it('loads archive strings and validates entries', async function() {
@@ -75,7 +123,10 @@ describe('NodeFileProvider', function() {
     const tarText = await provider.loadString('pack.tar/LEVEL000.DAT');
     expect(tarText.length).to.be.greaterThan(0);
 
-    expect(() => provider._validateEntry('../evil.txt')).to.throw();        
+    const nxpText = await provider.loadString('pack.nxp/docs/readme.txt');
+    expect(nxpText).to.equal('nxp-text');
+
+    expect(() => provider._validateEntry('../evil.txt')).to.throw();
   });
 
   it('throws when archive text entries are missing', async function() {
@@ -88,6 +139,10 @@ describe('NodeFileProvider', function() {
       provider.loadString('pack.tar/missing.txt'),
       /not found/i
     );
+    await expectReject(
+      provider.loadString('pack.nxp/missing.txt'),
+      /not found/i
+    );
   });
 
   it('throws when archive binary entries are missing', async function() {
@@ -105,11 +160,22 @@ describe('NodeFileProvider', function() {
       provider.loadBinary('pack.rar', 'missing.dat'),
       /not found/i
     );
+    await expectReject(
+      provider.loadBinary('pack.nxp', 'missing.dat'),
+      /not found/i
+    );
   });
 
   it('normalizes validated entry paths', function() {
     const provider = makeProvider();
     expect(provider._validateEntry('data\\LEVEL000.DAT')).to.equal('data/LEVEL000.DAT');
+    expect(provider._validateEntry('data/LEVEL..000.DAT')).to.equal('data/LEVEL..000.DAT');
+  });
+
+  it('allows non-traversal file names with repeated dots', async function() {
+    const provider = makeProvider();
+    const reader = await provider.loadBinary('.', 'LEVEL..000.DAT');
+    expect(reader.length).to.equal(fs.readFileSync(packFile).length);
   });
 
   it('reads plain strings from disk', async function() {
@@ -120,6 +186,14 @@ describe('NodeFileProvider', function() {
     expect(text).to.equal('hello');
   });
 
+  it('rejects non-string loadString inputs', async function() {
+    const provider = makeProvider();
+    await expectReject(
+      provider.loadString(null),
+      /invalid file path/i
+    );
+  });
+
   it('reads plain strings from absolute paths', async function() {
     const provider = makeProvider();
     const textPath = path.join(tmpDir, 'abs.txt');
@@ -128,6 +202,30 @@ describe('NodeFileProvider', function() {
     expect(text).to.equal('abs');
   });
 
+  it('rejects parent traversal in plain string paths', async function() {
+    const provider = makeProvider();
+    await expectReject(
+      provider.loadString('../outside.txt'),
+      /invalid file path/i
+    );
+  });
+
+  it('rejects parent traversal in binary directory paths', async function() {
+    const provider = makeProvider();
+    await expectReject(
+      provider.loadBinary('../outside', 'LEVEL000.DAT'),
+      /invalid file path/i
+    );
+  });
+
+  it('rejects parent traversal in archive string paths', async function() {
+    const provider = makeProvider();
+    await expectReject(
+      provider.loadString('../pack.zip/data/LEVEL000.DAT'),
+      /invalid file path/i
+    );
+  });
+
   it('reads binary data from an absolute directory', async function() {
     const provider = makeProvider();
     const reader = await provider.loadBinary(tmpDir, 'LEVEL000.DAT');
@@ -140,9 +238,44 @@ describe('NodeFileProvider', function() {
     const zip2 = provider._getZip('pack.zip');
     expect(zip1).to.equal(zip2);
 
+    const zipUpdated = new AdmZip();
+    zipUpdated.addFile('data/LEVEL000.DAT', Buffer.from([1, 2, 3, 4]));
+    const zipPath = path.join(tmpDir, 'pack.zip');
+    zipUpdated.writeZip(zipPath);
+    const shifted = new Date(Date.now() + 2500);
+    fs.utimesSync(zipPath, shifted, shifted);
+    const zip3 = provider._getZip('pack.zip');
+    expect(zip3).to.not.equal(zip1);
+
     const tar1 = await provider._getTar('pack.tar');
     const tar2 = await provider._getTar('pack.tar');
     expect(tar1).to.equal(tar2);
+    await tar.c({ file: path.join(tmpDir, 'pack.tar'), cwd: tmpDir }, ['LEVEL000.DAT']);
+    const tarPath = path.join(tmpDir, 'pack.tar');
+    const tarShifted = new Date(Date.now() + 2500);
+    fs.utimesSync(tarPath, tarShifted, tarShifted);
+    const tar3 = await provider._getTar('pack.tar');
+    expect(tar3).to.not.equal(tar1);
+
+    const nxp1 = provider._getNxp('pack.nxp');
+    const nxp2 = provider._getNxp('pack.nxp');
+    expect(nxp1).to.equal(nxp2);
+    const nxpPath = path.join(tmpDir, 'pack.nxp');
+    const originalNxpStat = fs.statSync(nxpPath);
+    writeNxp(path.join(tmpDir, 'pack.nxp'), [
+      { name: 'data/LEVEL000.DAT', data: Buffer.from([7, 8, 9]) }
+    ]);
+    const nxpShifted = new Date(Date.now() + 3500);
+    fs.utimesSync(nxpPath, nxpShifted, nxpShifted);
+    const nxp3 = provider._getNxp('pack.nxp');
+    expect(nxp3).to.not.equal(nxp1);
+
+    writeNxp(path.join(tmpDir, 'pack.nxp'), [
+      { name: 'data/LEVEL000.DAT', data: Buffer.from([1, 2, 3]) }
+    ]);
+    fs.utimesSync(nxpPath, originalNxpStat.atime, originalNxpStat.mtime);
+    const nxp4 = provider._getNxp('pack.nxp');
+    expect(nxp4).to.not.equal(nxp3);
   });
 
   it('skips non-file tar entries', async function() {
@@ -183,6 +316,13 @@ describe('NodeFileProvider', function() {
 
     await provider.loadBinary('pack.rar', 'LEVEL000.DAT');
     expect(calls).to.equal(1);
+
+    const rarPath = path.join(tmpDir, 'pack.rar');
+    fs.writeFileSync(rarPath, Buffer.from([1]));
+    const shifted = new Date(Date.now() + 2500);
+    fs.utimesSync(rarPath, shifted, shifted);
+    await provider.loadBinary('pack.rar', 'LEVEL000.DAT');
+    expect(calls).to.equal(2);
   });
 
   it('skips rar directory entries and finds lower-case keys', async function() {
@@ -233,6 +373,21 @@ describe('NodeFileProvider', function() {
     expect(lowerEntry).to.be.ok;
   });
 
+  it('skips traversal-looking archive entries during fallback lookups', function() {
+    const provider = makeProvider();
+    const map = new Map([['../secret.txt', Buffer.from('secret')]]);
+    expect(provider._findEntry(map, 'secret.txt')).to.equal(null);
+
+    const fakeZip = {
+      getEntry() { return null; },
+      getEntries() {
+        return [{ entryName: '../secret.txt' }];
+      }
+    };
+    const found = provider._findZipEntry(fakeZip, 'secret.txt');
+    expect(found).to.equal(undefined);
+  });
+
   it('loads rar entries using a stubbed extractor', async function() {
     const provider = makeProvider();
     provider._getRar = async () => new Map([
@@ -258,9 +413,80 @@ describe('NodeFileProvider', function() {
     provider._getZip('pack.zip');
     await provider._getTar('pack.tar');
     provider.rarCache.set('rar', new Map());
+    provider._getNxp('pack.nxp');
     provider.clearCache();
     expect(provider.zipCache.size).to.equal(0);
     expect(provider.tarCache.size).to.equal(0);
     expect(provider.rarCache.size).to.equal(0);
+    expect(provider.nxpCache.size).to.equal(0);
+    expect(provider.getCacheStats().zip.bytes).to.equal(0);
+  });
+
+  it('bounds archive caches by entry count and bytes', function() {
+    const provider = makeProvider({
+      maxArchiveCacheEntries: 2,
+      maxArchiveCacheBytes: 1024
+    });
+    for (const name of ['a.nxp', 'b.nxp', 'c.nxp', 'd.nxp']) {
+      writeNxp(path.join(tmpDir, name), [
+        { name: 'data/file.bin', data: Buffer.from(name) }
+      ]);
+    }
+
+    provider._getNxp('a.nxp');
+    provider._getNxp('b.nxp');
+    provider._getNxp('c.nxp');
+    expect(provider.getCacheStats().nxp.entries).to.equal(2);
+    expect([...provider.nxpCache.keys()].map(key => path.basename(key))).to.deep.equal(['b.nxp', 'c.nxp']);
+
+    provider._getNxp('b.nxp');
+    provider._getNxp('d.nxp');
+    expect([...provider.nxpCache.keys()].map(key => path.basename(key))).to.deep.equal(['b.nxp', 'd.nxp']);
+
+    const byteBounded = makeProvider({
+      maxArchiveCacheEntries: 10,
+      maxArchiveCacheBytes: 5
+    });
+    writeNxp(path.join(tmpDir, 'e.nxp'), [
+      { name: 'data/file.bin', data: Buffer.from([1, 2, 3, 4]) }
+    ]);
+    writeNxp(path.join(tmpDir, 'f.nxp'), [
+      { name: 'data/file.bin', data: Buffer.from([5, 6, 7, 8]) }
+    ]);
+    byteBounded._getNxp('e.nxp');
+    byteBounded._getNxp('f.nxp');
+    expect(byteBounded.getCacheStats().nxp).to.include({
+      entries: 1,
+      bytes: 4
+    });
+  });
+
+  it('does not retain a single oversized archive entry', function() {
+    const provider = makeProvider({
+      maxArchiveCacheEntries: 10,
+      maxArchiveCacheBytes: 3
+    });
+    writeNxp(path.join(tmpDir, 'oversized.nxp'), [
+      { name: 'data/file.bin', data: Buffer.from([1, 2, 3, 4]) }
+    ]);
+
+    const map = provider._getNxp('oversized.nxp');
+    expect(map.get('data/file.bin').length).to.equal(4);
+    expect(provider.nxpCache.size).to.equal(0);
+    expect(provider.getCacheStats().nxp.bytes).to.equal(0);
+  });
+
+  it('rejects invalid nxp archives', function() {
+    const provider = makeProvider();
+    fs.writeFileSync(path.join(tmpDir, 'bad-count.nxp'), Buffer.from([2, 0, 0, 0]));
+    expect(() => provider._getNxp('bad-count.nxp')).to.throw(/invalid nxp table size/i);
+
+    const invalid = Buffer.alloc(4 + 36);
+    invalid.writeUInt32LE(1, 0);
+    Buffer.from('file.bin').copy(invalid, 4);
+    invalid.writeUInt32LE(999, 32);
+    invalid.writeUInt32LE(10, 36);
+    fs.writeFileSync(path.join(tmpDir, 'bad-bounds.nxp'), invalid);
+    expect(() => provider._getNxp('bad-bounds.nxp')).to.throw(/invalid nxp entry bounds/i);
   });
 });
diff --git a/test/trigger.test.js b/test/trigger.test.js
index 73c652ce..f246369d 100644
--- a/test/trigger.test.js
+++ b/test/trigger.test.js
@@ -1,5 +1,5 @@
 import { expect } from 'chai';
-import { useGlobalLemmings, withGlobalLemmings } from './helpers/lemmings.js';
+import { useGlobalLemmings } from './helpers/lemmings.js';
 import { Trigger } from '../js/level/Trigger.js';
 import { TriggerTypes } from '../js/level/TriggerTypes.js';
 
@@ -23,18 +23,15 @@ describe('Trigger', function() {
 
   it('records trigger cooldown when history is present', function() {
     const calls = [];
-    withGlobalLemmings({
-      game: {
-        history: {
-          recordTriggerCooldown(trigger, prev, next) {
-            calls.push({ trigger, prev, next });
-          }
+    const trig = new Trigger(TriggerTypes.EXIT_LEVEL, 0, 0, 10, 10, 2);
+    trig.runtime = {
+      history: {
+        recordTriggerCooldown(trigger, prev, next) {
+          calls.push({ trigger, prev, next });
         }
       }
-    }, () => {
-      const trig = new Trigger(TriggerTypes.EXIT_LEVEL, 0, 0, 10, 10, 2);
-      trig.trigger(1, 1, 0);
-    });
+    };
+    trig.trigger(1, 1, 0);
     expect(calls).to.have.length(1);
     expect(calls[0].prev).to.equal(0);
     expect(calls[0].next).to.equal(2);
@@ -45,7 +42,7 @@ describe('Trigger', function() {
     const mockDisplay = { calls: [], drawRect(...args) { this.calls.push(args); } };
     trig.draw(mockDisplay);
     expect(mockDisplay.calls).to.have.lengthOf(1);
-    expect(mockDisplay.calls[0]).to.eql([2, 3, 3, 4, 255, 0, 0]);
+    expect(mockDisplay.calls[0]).to.eql([2, 3, 2, 3, 255, 0, 0]);
   });
 
   it('invokes owner handler and returns NO_TRIGGER when outside bounds', function() {
@@ -59,6 +56,14 @@ describe('Trigger', function() {
     expect(outside).to.equal(TriggerTypes.NO_TRIGGER);
   });
 
+  it('treats right and bottom trigger bounds as exclusive', function() {
+    const trig = new Trigger(TriggerTypes.TRAP, 10, 20, 13, 24);
+    expect(trig.trigger(10, 20, 0)).to.equal(TriggerTypes.TRAP);
+    expect(trig.trigger(12, 23, 1)).to.equal(TriggerTypes.TRAP);
+    expect(trig.trigger(13, 23, 2)).to.equal(TriggerTypes.NO_TRIGGER);
+    expect(trig.trigger(12, 24, 2)).to.equal(TriggerTypes.NO_TRIGGER);
+  });
+
   it('wraps disabledUntilTick and skips arrow debug draw', function() {
     const trig = new Trigger(TriggerTypes.ONEWAY_LEFT, 0, 0, 1, 1);
     trig.disabledUntilTick = Number.MAX_SAFE_INTEGER;
diff --git a/test/triggermanager.test.js b/test/triggermanager.test.js
index 7ed98eb6..1299d007 100644
--- a/test/triggermanager.test.js
+++ b/test/triggermanager.test.js
@@ -1,5 +1,5 @@
 import { expect } from 'chai';
-import { useGlobalLemmings, withGlobalLemmings } from './helpers/lemmings.js';
+import { useGlobalLemmings } from './helpers/lemmings.js';
 import '../js/util/LogHandler.js';
 import '../js/render/ColorPalette.js';
 import '../js/render/Frame.js';
@@ -19,9 +19,9 @@ describe('TriggerManager', function () {
     const c = new Trigger(TriggerTypes.DROWN, 20, 20, 22, 22, 0, -1, { id: 'c' });
     tm.addRange([a, b, c]);
 
-    expect(tm._grid[0].has(a)).to.be.true;
-    expect(tm._grid[1].has(b)).to.be.true;
-    expect(tm._grid[3].has(c)).to.be.true;
+    expect(tm._grid[0].includes(a)).to.be.true;
+    expect(tm._grid[1].includes(b)).to.be.true;
+    expect(tm._grid[3].includes(c)).to.be.true;
 
     expect(tm.trigger(2, 2)).to.equal(TriggerTypes.TRAP);
     expect(tm.trigger(21, 2)).to.equal(TriggerTypes.FRYING);
@@ -29,10 +29,58 @@ describe('TriggerManager', function () {
     expect(tm.trigger(2, 21)).to.equal(TriggerTypes.NO_TRIGGER);
 
     tm.removeByOwner(a.owner);
-    expect(tm._grid[0].has(a)).to.be.false;
+    expect(tm._grid[0].includes(a)).to.be.false;
     expect(tm.trigger(2, 2)).to.equal(TriggerTypes.NO_TRIGGER);
   });
 
+  it('removes all same-owner triggers without skipping swap-pop entries', function () {
+    const timer = { tick: 0, getGameTicks () { return this.tick; } };
+    const tm = new TriggerManager(timer, 63, 31, 16);
+    const owner = { id: 'shared-owner' };
+    const a = new Trigger(TriggerTypes.BLOCKER_LEFT, 1, 1, 5, 5, 0, -1, owner);
+    const b = new Trigger(TriggerTypes.BLOCKER_RIGHT, 20, 1, 25, 5, 0, -1, owner);
+    tm.addRange([a, b]);
+
+    expect(tm.trigger(2, 2)).to.equal(TriggerTypes.BLOCKER_LEFT);
+    expect(tm.trigger(22, 2)).to.equal(TriggerTypes.BLOCKER_RIGHT);
+
+    tm.removeByOwner(owner);
+
+    expect(tm.trigger(2, 2)).to.equal(TriggerTypes.NO_TRIGGER);
+    expect(tm.trigger(22, 2)).to.equal(TriggerTypes.NO_TRIGGER);
+    expect(tm._ownerTriggers.has(owner)).to.equal(false);
+    expect(tm._triggers.size).to.equal(0);
+  });
+
+  it('cleans up owner triggers without touching other owners or leaving stale grid refs', function () {
+    const timer = { tick: 0, getGameTicks () { return this.tick; } };
+    const tm = new TriggerManager(timer, 63, 31, 16);
+    const ownerA = { id: 'owner-a' };
+    const ownerB = { id: 'owner-b' };
+    const a1 = new Trigger(TriggerTypes.TRAP, 1, 1, 5, 5, 0, -1, ownerA);
+    const a2 = new Trigger(TriggerTypes.FRYING, 18, 1, 25, 5, 0, -1, ownerA);
+    const b1 = new Trigger(TriggerTypes.DROWN, 34, 1, 40, 5, 0, -1, ownerB);
+    tm.addRange([a1, a2, b1]);
+
+    tm.removeByOwner(ownerA);
+
+    expect(tm._ownerTriggers.has(ownerA)).to.equal(false);
+    expect(tm._ownerTriggers.has(ownerB)).to.equal(true);
+    expect(tm.trigger(2, 2)).to.equal(TriggerTypes.NO_TRIGGER);
+    expect(tm.trigger(20, 2)).to.equal(TriggerTypes.NO_TRIGGER);
+    expect(tm.trigger(36, 2)).to.equal(TriggerTypes.DROWN);
+
+    for (const bucket of tm._grid) {
+      for (const trigger of bucket) {
+        expect(trigger.owner).to.not.equal(ownerA);
+      }
+    }
+
+    tm.removeByOwner(ownerA);
+    expect(tm.trigger(36, 2)).to.equal(TriggerTypes.DROWN);
+    expect(tm._triggers.size).to.equal(1);
+  });
+
   it('reuses debug frame', function () {
     const timer = { tick: 0, getGameTicks () { return this.tick; } };
     const tm = new TriggerManager(timer, 31, 31, 16);
@@ -64,11 +112,25 @@ describe('TriggerManager', function () {
 
     expect(tm.trigger(-1, 0)).to.equal(TriggerTypes.NO_TRIGGER);
     expect(tm.trigger(0, -1)).to.equal(TriggerTypes.NO_TRIGGER);
+    expect(tm.trigger(31, 1)).to.equal(TriggerTypes.NO_TRIGGER);
     expect(tm.trigger(32, 1)).to.equal(TriggerTypes.NO_TRIGGER);
+    expect(tm.trigger(1, 31)).to.equal(TriggerTypes.NO_TRIGGER);
     expect(tm.trigger(1, 32)).to.equal(TriggerTypes.NO_TRIGGER);
     expect(tm.trigger(2, 2)).to.equal(TriggerTypes.TRAP);
   });
 
+  it('uses real level dimensions and half-open trigger bounds', function () {
+    const timer = { tick: 0, getGameTicks () { return this.tick; } };
+    const tm = new TriggerManager(timer, 2000, 240, 16);
+    const tr = new Trigger(TriggerTypes.TRAP, 1700, 200, 1710, 210);
+    tm.add(tr);
+
+    expect(tm.trigger(1705, 205)).to.equal(TriggerTypes.TRAP);
+    expect(tm.trigger(1709, 209)).to.equal(TriggerTypes.TRAP);
+    expect(tm.trigger(1710, 209)).to.equal(TriggerTypes.NO_TRIGGER);
+    expect(tm.trigger(1709, 210)).to.equal(TriggerTypes.NO_TRIGGER);
+  });
+
   it('colors cells based on state in renderDebug', function () {
     const timer = { tick: 5, getGameTicks () { return this.tick; } };
     const tm = new TriggerManager(timer, 31, 31, 16);
@@ -114,21 +176,17 @@ describe('TriggerManager', function () {
 
   it('records history on add/remove when available', function () {
     const timer = { tick: 0, getGameTicks () { return this.tick; } };
-    const tm = new TriggerManager(timer, 31, 31, 16);
     const calls = { add: [], remove: [] };
-    withGlobalLemmings({
-      game: {
-        history: {
-          recordTriggerAdd(trigger, snapshot) { calls.add.push({ trigger, snapshot }); },
-          recordTriggerRemove(trigger, snapshot) { calls.remove.push({ trigger, snapshot }); }
-        }
+    const tm = new TriggerManager(timer, 31, 31, 16, {
+      history: {
+        recordTriggerAdd(trigger, snapshot) { calls.add.push({ trigger, snapshot }); },
+        recordTriggerRemove(trigger, snapshot) { calls.remove.push({ trigger, snapshot }); }
       }
-    }, () => {
-      const owner = { id: 7 };
-      const tr = new Trigger(TriggerTypes.TRAP, 1, 1, 5, 5, 0, 2, owner);
-      tm.add(tr);
-      tm.removeByOwner(owner);
     });
+    const owner = { id: 7 };
+    const tr = new Trigger(TriggerTypes.TRAP, 1, 1, 5, 5, 0, 2, owner);
+    tm.add(tr);
+    tm.removeByOwner(owner);
 
     expect(calls.add).to.have.length(1);
     expect(calls.add[0].snapshot.ownerId).to.equal(7);
@@ -138,26 +196,71 @@ describe('TriggerManager', function () {
 
   it('records null owner ids in history snapshots', function () {
     const timer = { tick: 0, getGameTicks () { return this.tick; } };
-    const tm = new TriggerManager(timer, 31, 31, 16);
     const calls = { add: [], remove: [] };
-    withGlobalLemmings({
-      game: {
-        history: {
-          recordTriggerAdd(trigger, snapshot) { calls.add.push({ trigger, snapshot }); },
-          recordTriggerRemove(trigger, snapshot) { calls.remove.push({ trigger, snapshot }); }
-        }
+    const tm = new TriggerManager(timer, 31, 31, 16, {
+      history: {
+        recordTriggerAdd(trigger, snapshot) { calls.add.push({ trigger, snapshot }); },
+        recordTriggerRemove(trigger, snapshot) { calls.remove.push({ trigger, snapshot }); }
       }
-    }, () => {
-      const tr = new Trigger(TriggerTypes.TRAP, 1, 1, 5, 5);
-      tm.add(tr);
-      tm.removeByOwner(null);
     });
+    const tr = new Trigger(TriggerTypes.TRAP, 1, 1, 5, 5);
+    tm.add(tr);
+    tm.removeByOwner(null);
 
     expect(calls.add[0].snapshot.ownerId).to.equal(null);
     expect(calls.remove[0].snapshot.ownerId).to.equal(null);
 
   });
 
+  it('runs observer triggers without blocking gameplay triggers', function () {
+    const timer = { tick: 0, getGameTicks () { return this.tick; } };
+    const cases = [
+      ['gameplay-first', (tm, gameplay, observer) => { tm.add(gameplay); tm.addObserver(observer); }],
+      ['observer-first', (tm, gameplay, observer) => { tm.addObserver(observer); tm.add(gameplay); }]
+    ];
+
+    for (const [name, register] of cases) {
+      const calls = [];
+      const tm = new TriggerManager(timer, 31, 31, 16);
+      const gameplay = new Trigger(TriggerTypes.EXIT_LEVEL, 1, 1, 5, 5, 0, -1, { id: `${name}:exit` });
+      const observer = new Trigger(TriggerTypes.NO_TRIGGER, 1, 1, 5, 5, 0, -1, {
+        id: `${name}:observer`,
+        onTrigger(tick, lemming, trigger, x, y) {
+          calls.push({ tick, x, y, trigger });
+        }
+      });
+      register(tm, gameplay, observer);
+
+      expect(tm.trigger(2, 2), name).to.equal(TriggerTypes.EXIT_LEVEL);
+      expect(calls).to.have.length(1);
+      expect(calls[0]).to.include({ tick: 0, x: 2, y: 2 });
+    }
+  });
+
+  it('keeps observer cooldown independent from gameplay resolution', function () {
+    const timer = { tick: 0, getGameTicks () { return this.tick; } };
+    const tm = new TriggerManager(timer, 31, 31, 16);
+    const calls = [];
+    const observer = new Trigger(TriggerTypes.NO_TRIGGER, 1, 1, 5, 5, 5, -1, {
+      id: 'observer',
+      onTrigger(tick) {
+        calls.push(tick);
+      }
+    });
+    const gameplay = new Trigger(TriggerTypes.TRAP, 1, 1, 5, 5, 0, -1, { id: 'trap' });
+    tm.addObserver(observer);
+    tm.add(gameplay);
+
+    expect(tm.trigger(2, 2, null, 0)).to.equal(TriggerTypes.TRAP);
+    expect(tm.trigger(2, 2, null, 1)).to.equal(TriggerTypes.TRAP);
+    expect(tm.trigger(2, 2, null, 4)).to.equal(TriggerTypes.TRAP);
+    expect(tm.trigger(2, 2, null, 5)).to.equal(TriggerTypes.TRAP);
+    expect(calls).to.eql([0, 5]);
+
+    tm.removeByOwner(gameplay.owner);
+    expect(tm.trigger(2, 2, null, 6)).to.equal(TriggerTypes.NO_TRIGGER);
+  });
+
   it('dispose clears references', function () {
     const timer = { tick: 0, getGameTicks () { return this.tick; } };
     const tm = new TriggerManager(timer, 31, 31, 16);
diff --git a/test/visual-capture-helper.test.js b/test/visual-capture-helper.test.js
new file mode 100644
index 00000000..edae4077
--- /dev/null
+++ b/test/visual-capture-helper.test.js
@@ -0,0 +1,44 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { expect } from 'chai';
+import {
+  DEFAULT_CAPTURE_ROOT,
+  normalizeClipRect,
+  resolveCaptureOutputDir,
+  sanitizeCaptureName
+} from '../e2e/helpers/visualCapture.js';
+
+describe('visual capture helper', function() {
+  it('sanitizes capture names for disposable file output', function() {
+    expect(sanitizeCaptureName(' MIDI sequencer / source browser ')).to.equal('MIDI-sequencer-source-browser');
+    expect(sanitizeCaptureName('')).to.equal('capture');
+  });
+
+  it('validates and clamps clip rectangles to the viewport', function() {
+    expect(normalizeClipRect(
+      { x: -5, y: 10, width: 25, height: 20 },
+      { width: 100, height: 100 }
+    )).to.eql({ x: 0, y: 10, width: 20, height: 20 });
+    expect(() => normalizeClipRect({ x: 120, y: 0, width: 10, height: 10 }, {
+      width: 100,
+      height: 100
+    })).to.throw(/outside the viewport/);
+    expect(() => normalizeClipRect({ x: 0, y: 0, width: 0, height: 10 })).to.throw(/Invalid clip/);
+  });
+
+  it('keeps capture output under temp/e2e-captures', async function() {
+    const root = path.resolve(DEFAULT_CAPTURE_ROOT);
+    const outDir = path.join(root, 'unit-helper');
+    await fs.rm(outDir, { recursive: true, force: true });
+    const resolved = await resolveCaptureOutputDir(outDir);
+    expect(resolved).to.equal(outDir);
+    expect(path.relative(root, resolved).startsWith('..')).to.equal(false);
+    let threw = false;
+    try {
+      await resolveCaptureOutputDir(path.resolve('temp', 'outside-captures'));
+    } catch (error) {
+      threw = /Capture output must stay/.test(error.message);
+    }
+    expect(threw).to.equal(true);
+  });
+});
diff --git a/test/workflow.test.js b/test/workflow.test.js
index 25e61530..5e01ac88 100644
--- a/test/workflow.test.js
+++ b/test/workflow.test.js
@@ -17,8 +17,11 @@ describe('GitHub test workflow', function () {
       'npm ci',
       'npm run check-undefined',
       'npm run lint',
+      'npm run release-readiness',
+      'npm run test-bench-unit',
       'npm test'
     ]);
+    expect(runSteps.some(step => step.includes('git diff --check'))).to.equal(true);
 
     const syncStep = steps.find(
       s => s.run && s.run.includes('git checkout origin/master -- tools')
diff --git a/tools/NodeFileProvider.js b/tools/NodeFileProvider.js
index 41e50f1b..764c5036 100644
--- a/tools/NodeFileProvider.js
+++ b/tools/NodeFileProvider.js
@@ -5,13 +5,31 @@ import AdmZip from 'adm-zip';
 import * as tar from 'tar';
 import { createExtractorFromFile, createExtractorFromData } from 'node-unrar-js';
 
+const DEFAULT_MAX_ARCHIVE_CACHE_ENTRIES = 8;
+const DEFAULT_MAX_ARCHIVE_CACHE_BYTES = 64 * 1024 * 1024;
+
 class NodeFileProvider {
   constructor(rootPath = '.', options = {}) {
     this.rootPath = rootPath;
     this.zipCache = new Map();
     this.tarCache = new Map();
     this.rarCache = new Map();
+    this.nxpCache = new Map();
     this._rar = options.rar || { createExtractorFromData, createExtractorFromFile };
+    this._archiveCacheLimits = {
+      maxEntries: Number.isFinite(options.maxArchiveCacheEntries) && options.maxArchiveCacheEntries > 0
+        ? Math.floor(options.maxArchiveCacheEntries)
+        : DEFAULT_MAX_ARCHIVE_CACHE_ENTRIES,
+      maxBytes: Number.isFinite(options.maxArchiveCacheBytes) && options.maxArchiveCacheBytes > 0
+        ? Math.floor(options.maxArchiveCacheBytes)
+        : DEFAULT_MAX_ARCHIVE_CACHE_BYTES
+    };
+    this._archiveCacheBytes = {
+      zip: 0,
+      tar: 0,
+      rar: 0,
+      nxp: 0
+    };
   }
 
   /**
@@ -21,30 +39,181 @@ class NodeFileProvider {
     this.zipCache.clear();
     this.tarCache.clear();
     this.rarCache.clear();
+    this.nxpCache.clear();
+    this._archiveCacheBytes.zip = 0;
+    this._archiveCacheBytes.tar = 0;
+    this._archiveCacheBytes.rar = 0;
+    this._archiveCacheBytes.nxp = 0;
+  }
+
+  getCacheStats() {
+    return {
+      maxEntries: this._archiveCacheLimits.maxEntries,
+      maxBytes: this._archiveCacheLimits.maxBytes,
+      zip: { entries: this.zipCache.size, bytes: this._archiveCacheBytes.zip },
+      tar: { entries: this.tarCache.size, bytes: this._archiveCacheBytes.tar },
+      rar: { entries: this.rarCache.size, bytes: this._archiveCacheBytes.rar },
+      nxp: { entries: this.nxpCache.size, bytes: this._archiveCacheBytes.nxp }
+    };
+  }
+
+  _estimateMapBytes(map) {
+    let total = 0;
+    for (const value of map?.values?.() || []) {
+      total += value?.byteLength ?? value?.length ?? 0;
+    }
+    return total;
+  }
+
+  _readCachedArchive(kind, cache, key, stat) {
+    const cached = cache.get(key);
+    if (!cached) return null;
+    if (!this._isCacheValid(cached, stat)) {
+      cache.delete(key);
+      this._archiveCacheBytes[kind] = Math.max(
+        0,
+        this._archiveCacheBytes[kind] - (cached.cacheBytes || 0)
+      );
+      return null;
+    }
+    cache.delete(key);
+    cache.set(key, cached);
+    return cached;
+  }
+
+  _rememberArchive(kind, cache, key, entry, cacheBytes = entry?.size || 0) {
+    const previous = cache.get(key);
+    if (previous) {
+      cache.delete(key);
+      this._archiveCacheBytes[kind] = Math.max(
+        0,
+        this._archiveCacheBytes[kind] - (previous.cacheBytes || 0)
+      );
+    }
+    const normalizedCacheBytes = Math.max(0, Number.isFinite(cacheBytes) ? cacheBytes : 0);
+    if (normalizedCacheBytes > this._archiveCacheLimits.maxBytes) {
+      return {
+        ...entry,
+        cacheBytes: normalizedCacheBytes
+      };
+    }
+    const next = {
+      ...entry,
+      cacheBytes: normalizedCacheBytes
+    };
+    cache.set(key, next);
+    this._archiveCacheBytes[kind] += next.cacheBytes;
+    while (
+      cache.size > 1
+      && (
+        cache.size > this._archiveCacheLimits.maxEntries
+        || this._archiveCacheBytes[kind] > this._archiveCacheLimits.maxBytes
+      )
+    ) {
+      const oldestKey = cache.keys().next().value;
+      const oldest = cache.get(oldestKey);
+      cache.delete(oldestKey);
+      this._archiveCacheBytes[kind] = Math.max(
+        0,
+        this._archiveCacheBytes[kind] - (oldest?.cacheBytes || 0)
+      );
+    }
+    return next;
   }
 
   _validateEntry(name) {
-    if (path.isAbsolute(name) || name.includes('..')) {
+    if (typeof name !== 'string') {
       throw new Error(`Invalid file path ${name}`);
     }
-    return name.replace(/\\/g, '/');
+    if (path.isAbsolute(name)) {
+      throw new Error(`Invalid file path ${name}`);
+    }
+    const normalized = name.replace(/\\/g, '/');
+    if (
+      normalized.includes('\0') ||
+      normalized.split('/').some(segment => segment === '..')
+    ) {
+      throw new Error(`Invalid file path ${name}`);
+    }
+    return normalized;
+  }
+
+  _normalizeArchivePath(archivePath) {
+    if (archivePath == null || archivePath === '') {
+      return '.';
+    }
+    const normalizedPath = String(archivePath);
+    if (path.isAbsolute(normalizedPath)) {
+      return normalizedPath;
+    }
+    return this._validateEntry(normalizedPath);
+  }
+
+  /**
+   * Normalize source paths like `pack.zip/` to `pack.zip` so archive detection
+   * still works when callers append trailing separators.
+   * @param {string} filePath
+   * @returns {string}
+   */
+  _trimTrailingSeparators(filePath) {
+    const trimmed = String(filePath).replace(/[\\/]+$/, '');
+    return trimmed || filePath;
+  }
+
+  /**
+   * Detect explicit `..` path traversal segments in a normalized archive key.
+   * @param {string} filePath
+   * @returns {boolean}
+   */
+  _containsTraversalSegment(filePath) {
+    const normalized = String(filePath).replace(/\\/g, '/');
+    return normalized.split('/').some(segment => segment === '..');
+  }
+
+  /**
+   * Read the archive stat fields used by cache validation.
+   * @param {string} absPath
+   * @returns {{mtimeMs:number,size:number,ctimeMs:number}}
+   */
+  _readArchiveStat(absPath) {
+    const stat = fs.statSync(absPath);
+    return {
+      mtimeMs: stat.mtimeMs,
+      size: stat.size,
+      ctimeMs: stat.ctimeMs
+    };
+  }
+
+  /**
+   * Determine whether a cached archive entry still matches filesystem metadata.
+   * @param {object} cached
+   * @param {{mtimeMs:number,size:number,ctimeMs:number}} stat
+   * @returns {boolean}
+   */
+  _isCacheValid(cached, stat) {
+    return !!cached &&
+      cached.mtimeMs === stat.mtimeMs &&
+      cached.size === stat.size &&
+      cached.ctimeMs === stat.ctimeMs;
   }
 
   _getZip(zipPath) {
     const abs = path.resolve(this.rootPath, zipPath);
-    let zip = this.zipCache.get(abs);
-    if (!zip) {
-      zip = new AdmZip(abs);
-      this.zipCache.set(abs, zip);
+    const stat = this._readArchiveStat(abs);
+    const cached = this._readCachedArchive('zip', this.zipCache, abs, stat);
+    if (!cached) {
+      const zip = new AdmZip(abs);
+      return this._rememberArchive('zip', this.zipCache, abs, { ...stat, zip }, stat.size).zip;
     }
-    return zip;
+    return cached.zip;
   }
 
   async _getTar(tarPath) {
     const abs = path.resolve(this.rootPath, tarPath);
-    let map = this.tarCache.get(abs);
-    if (!map) {
-      map = new Map();
+    const stat = this._readArchiveStat(abs);
+    const cached = this._readCachedArchive('tar', this.tarCache, abs, stat);
+    if (!cached) {
+      const map = new Map();
       await tar.t({
         file: abs,
         gzip: /(\.tar\.gz|\.tgz)$/i.test(tarPath),
@@ -57,16 +226,23 @@ class NodeFileProvider {
           });
         },
       });
-      this.tarCache.set(abs, map);
+      return this._rememberArchive(
+        'tar',
+        this.tarCache,
+        abs,
+        { ...stat, map },
+        this._estimateMapBytes(map)
+      ).map;
     }
-    return map;
+    return cached.map;
   }
 
   async _getRar(rarPath) {
     const abs = path.resolve(this.rootPath, rarPath);
-    let map = this.rarCache.get(abs);
-    if (!map) {
-      map = new Map();
+    const stat = this._readArchiveStat(abs);
+    const cached = this._readCachedArchive('rar', this.rarCache, abs, stat);
+    if (!cached) {
+      const map = new Map();
       const data = fs.readFileSync(abs);
       const extractor = await this._rar.createExtractorFromData({ data });
       const list = extractor.getFileList();
@@ -79,9 +255,63 @@ class NodeFileProvider {
           map.set(h.name.replace(/\\/g, '/'), Buffer.from(f.extraction));
         }
       }
-      this.rarCache.set(abs, map);
+      return this._rememberArchive(
+        'rar',
+        this.rarCache,
+        abs,
+        { ...stat, map },
+        this._estimateMapBytes(map)
+      ).map;
     }
-    return map;
+    return cached.map;
+  }
+
+  /**
+   * Parse legacy Flexi Toolkit `.nxp` archives:
+   * - uint32le entry count
+   * - table entries (36 bytes): name[28], offset uint32le, size uint32le
+   * - payload bytes follow immediately after the table
+   */
+  _getNxp(nxpPath) {
+    const abs = path.resolve(this.rootPath, nxpPath);
+    const stat = this._readArchiveStat(abs);
+    const cached = this._readCachedArchive('nxp', this.nxpCache, abs, stat);
+    if (cached) return cached.map;
+
+    const data = fs.readFileSync(abs);
+    if (data.length < 4) {
+      throw new Error(`Invalid NXP archive: ${nxpPath}`);
+    }
+    const entryCount = data.readUInt32LE(0);
+    const TABLE_ENTRY_SIZE = 36;
+    const tableSize = 4 + (entryCount * TABLE_ENTRY_SIZE);
+    if (tableSize > data.length) {
+      throw new Error(`Invalid NXP table size in ${nxpPath}`);
+    }
+
+    const map = new Map();
+    for (let i = 0; i < entryCount; i += 1) {
+      const base = 4 + (i * TABLE_ENTRY_SIZE);
+      const nameRaw = data.subarray(base, base + 28);
+      const zero = nameRaw.indexOf(0);
+      const name = nameRaw.subarray(0, zero >= 0 ? zero : nameRaw.length)
+        .toString('utf8')
+        .replace(/\\/g, '/');
+      const offset = data.readUInt32LE(base + 28);
+      const size = data.readUInt32LE(base + 32);
+      if (!name) continue;
+      if ((offset + size) > data.length) {
+        throw new Error(`Invalid NXP entry bounds for ${name} in ${nxpPath}`);
+      }
+      map.set(name, data.subarray(offset, offset + size));
+    }
+    return this._rememberArchive(
+      'nxp',
+      this.nxpCache,
+      abs,
+      { ...stat, map },
+      this._estimateMapBytes(map)
+    ).map;
   }
 
   _findEntry(map, entryName) {
@@ -89,6 +319,7 @@ class NodeFileProvider {
     if (map.has(entryName)) return map.get(entryName);
     if (map.has(lower)) return map.get(lower);
     for (const [k, v] of map.entries()) {
+      if (this._containsTraversalSegment(k)) continue;
       const l = k.toLowerCase();
       if (l === lower || l.endsWith('/' + lower)) return v;
     }
@@ -100,6 +331,7 @@ class NodeFileProvider {
     let entry = zip.getEntry(entryName) || zip.getEntry(lower);
     if (!entry) {
       entry = zip.getEntries().find(e => {
+        if (this._containsTraversalSegment(e.entryName)) return false;
         const eName = e.entryName.toLowerCase();
         return eName === lower || eName.endsWith('/' + lower);
       });
@@ -107,41 +339,62 @@ class NodeFileProvider {
     return entry;
   }
 
-  async loadBinary(dir, filename) {
+  /**
+   * Load a binary file either from a directory or from a supported archive.
+   * @param {string} [dir='.'] Directory or archive path.
+   * @param {string} filename Archive entry or file name.
+   * @returns {Promise<Lemmings.BinaryReader>}
+   */
+  async loadBinary(dir = '.', filename) {
     filename = this._validateEntry(filename);
-    if (/\.zip$/i.test(dir)) {
-      const zip = this._getZip(dir);
+    const sourcePath = this._trimTrailingSeparators(this._normalizeArchivePath(dir));
+    if (/\.zip$/i.test(sourcePath)) {
+      const zip = this._getZip(sourcePath);
       const entry = this._findZipEntry(zip, filename);
-      if (!entry) throw new Error(`File ${filename} not found in ${dir}`);
+      if (!entry) throw new Error(`File ${filename} not found in ${sourcePath}`);
       const buffer = entry.getData();
       const arr = new Uint8Array(buffer);
-      return new Lemmings.BinaryReader(arr, 0, arr.length, filename, dir);
-    } else if (/(\.tar\.gz|\.tgz|\.tar)$/i.test(dir)) {
-      const map = await this._getTar(dir);
+      return new Lemmings.BinaryReader(arr, 0, arr.length, filename, sourcePath);
+    } else if (/(\.tar\.gz|\.tgz|\.tar)$/i.test(sourcePath)) {
+      const map = await this._getTar(sourcePath);
+      const buf = this._findEntry(map, filename);
+      if (!buf) throw new Error(`File ${filename} not found in ${sourcePath}`);
+      const arr = new Uint8Array(buf);
+      return new Lemmings.BinaryReader(arr, 0, arr.length, filename, sourcePath);
+    } else if (/\.rar$/i.test(sourcePath)) {
+      const map = await this._getRar(sourcePath);
       const buf = this._findEntry(map, filename);
-      if (!buf) throw new Error(`File ${filename} not found in ${dir}`);
+      if (!buf) throw new Error(`File ${filename} not found in ${sourcePath}`);
       const arr = new Uint8Array(buf);
-      return new Lemmings.BinaryReader(arr, 0, arr.length, filename, dir);
-    } else if (/\.rar$/i.test(dir)) {
-      const map = await this._getRar(dir);
+      return new Lemmings.BinaryReader(arr, 0, arr.length, filename, sourcePath);
+    } else if (/\.nxp$/i.test(sourcePath)) {
+      const map = this._getNxp(sourcePath);
       const buf = this._findEntry(map, filename);
-      if (!buf) throw new Error(`File ${filename} not found in ${dir}`);
+      if (!buf) throw new Error(`File ${filename} not found in ${sourcePath}`);
       const arr = new Uint8Array(buf);
-      return new Lemmings.BinaryReader(arr, 0, arr.length, filename, dir);
+      return new Lemmings.BinaryReader(arr, 0, arr.length, filename, sourcePath);
     }
-    const fullPath = path.isAbsolute(dir)
-      ? path.join(dir, filename)
-      : path.join(this.rootPath, dir, filename);
+    const fullPath = path.isAbsolute(sourcePath)
+      ? path.join(sourcePath, filename)
+      : path.join(this.rootPath, sourcePath, filename);
     const buffer = fs.readFileSync(fullPath);
     const arr = new Uint8Array(buffer);
-    return new Lemmings.BinaryReader(arr, 0, arr.length, filename, dir);
+    return new Lemmings.BinaryReader(arr, 0, arr.length, filename, sourcePath);
   }
 
+  /**
+   * Load UTF-8 text from either the filesystem or an archive URL-like path.
+   * @param {string} file
+   * @returns {Promise<string>}
+   */
   async loadString(file) {
+    if (typeof file !== 'string') {
+      throw new Error(`Invalid file path ${file}`);
+    }
     file = file.replace(/\\/g, '/');
-    const m = file.match(/^(.*\.(?:zip|tar(?:\.gz)?|tgz|rar))\/(.+)$/i);
+    const m = file.match(/^(.*\.(?:zip|tar(?:\.gz)?|tgz|rar|nxp))\/(.+)$/i);
     if (m) {
-      const archive = m[1];
+      const archive = this._normalizeArchivePath(m[1]);
       const entryName = this._validateEntry(m[2]);
       if (/\.zip$/i.test(archive)) {
         const zip = this._getZip(archive);
@@ -158,11 +411,16 @@ class NodeFileProvider {
         const buf = this._findEntry(map, entryName);
         if (!buf) throw new Error(`File ${entryName} not found in ${archive}`);
         return Buffer.from(buf).toString('utf8');
+      } else if (/\.nxp$/i.test(archive)) {
+        const map = this._getNxp(archive);
+        const buf = this._findEntry(map, entryName);
+        if (!buf) throw new Error(`File ${entryName} not found in ${archive}`);
+        return Buffer.from(buf).toString('utf8');
       }
     }
     const fullPath = path.isAbsolute(file)
       ? file
-      : path.join(this.rootPath, file);
+      : path.join(this.rootPath, this._validateEntry(file));
     return fs.readFileSync(fullPath, 'utf8');
   }
 }
diff --git a/tools/packLevels.js b/tools/packLevels.js
index fce9ac56..d4a61f5e 100644
--- a/tools/packLevels.js
+++ b/tools/packLevels.js
@@ -1,6 +1,7 @@
 import { PackFilePart } from '../js/data/PackFilePart.js';
 import fs from 'fs';
 import path from 'path';
+import { once } from 'events';
 
 function usage() {
   console.log('Usage: node tools/packLevels.js <level dir> <out DAT>');
@@ -13,16 +14,23 @@ function usage() {
     return;
   }
 
-  const files = fs.readdirSync(levelDir)
-    .filter(f => fs.statSync(path.join(levelDir, f)).isFile())
+  const files = (await fs.promises.readdir(levelDir, { withFileTypes: true }))
+    .filter(entry => entry.isFile())
+    .map(entry => entry.name)
     .sort();
 
   const HEADER_SIZE = 10;
-  const parts = [];
+  const outStream = fs.createWriteStream(outFile);
   let totalSize = 0;
 
+  const writeChunk = async (chunk) => {
+    if (!outStream.write(chunk)) {
+      await once(outStream, 'drain');
+    }
+  };
+
   for (const file of files) {
-    const buf = fs.readFileSync(path.join(levelDir, file));
+    const buf = await fs.promises.readFile(path.join(levelDir, file));
     if (buf.length !== 2048) {
       console.warn(`Skipping ${file}: expected 2048 bytes, got ${buf.length}`);
       continue;
@@ -40,18 +48,15 @@ function usage() {
       (size >> 8) & 0xFF,
       size & 0xFF
     ]);
-    parts.push({ header, byteArray });
+    await writeChunk(header);
+    await writeChunk(byteArray);
     totalSize += size;
   }
 
-  const out = new Uint8Array(totalSize);
-  let offset = 0;
-  for (const { header, byteArray } of parts) {
-    out.set(header, offset);
-    out.set(byteArray, offset + HEADER_SIZE);
-    offset += header.length + byteArray.length;
-  }
+  await new Promise((resolve, reject) => {
+    outStream.once('error', reject);
+    outStream.end(resolve);
+  });
 
-  fs.writeFileSync(outFile, out);
-  console.log(`Wrote ${outFile}`);
+  console.log(`Wrote ${outFile} (${totalSize} bytes)`);
 })();
diff --git a/tools/packPipeline.js b/tools/packPipeline.js
new file mode 100644
index 00000000..dd7e0921
--- /dev/null
+++ b/tools/packPipeline.js
@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { BinaryReader } from '../js/data/BinaryReader.js';
+import { FileContainer } from '../js/data/FileContainer.js';
+import { PackFilePart } from '../js/data/PackFilePart.js';
+
+const USAGE = `Usage:
+  node tools/packPipeline.js unpack <input.dat> <outDir>
+  node tools/packPipeline.js pack <meta.json> <output.dat>
+  node tools/packPipeline.js patch <input.dat> <output.dat> --part <index> --offset <offset> --file <patch.bin>
+`;
+
+const parseInt10 = (value, fallback = null) => {
+  const num = Number.parseInt(String(value), 10);
+  return Number.isFinite(num) ? num : fallback;
+};
+
+const writeWord = (buffer, offset, value) => {
+  buffer[offset] = (value >> 8) & 0xff;
+  buffer[offset + 1] = value & 0xff;
+};
+
+const getInputReader = (inputPath) => {
+  const bytes = fs.readFileSync(inputPath);
+  const fileName = path.basename(inputPath);
+  const folderName = path.basename(path.dirname(inputPath));
+  return new BinaryReader(new Uint8Array(bytes), 0, bytes.length, fileName, folderName);
+};
+
+const getRawPartBytes = (part) => {
+  const unpacked = part.unpack();
+  const start = unpacked.hiddenOffset;
+  const end = start + unpacked.length;
+  return new Uint8Array(unpacked.data.slice(start, end));
+};
+
+const resolveMetadataPartPath = (baseDir, fileName) => {
+  if (typeof fileName !== 'string' || !fileName.trim()) {
+    throw new Error('invalid metadata part path');
+  }
+  if (fileName.includes('\0') || path.isAbsolute(fileName)) {
+    throw new Error(`metadata part path escapes base directory: ${fileName}`);
+  }
+  const rawPath = path.resolve(baseDir, fileName);
+  const relative = path.relative(baseDir, rawPath);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error(`metadata part path escapes base directory: ${fileName}`);
+  }
+  return rawPath;
+};
+
+const collectParts = (container) => {
+  const parts = container.parts;
+  const out = new Array(parts.length);
+  for (let i = 0; i < parts.length; i += 1) {
+    const part = parts[i];
+    out[i] = {
+      index: i,
+      unknown1: Number.isFinite(part.unknown1) ? part.unknown1 : 0,
+      unknown0: Number.isFinite(part.unknown0) ? part.unknown0 : 0,
+      raw: getRawPartBytes(part)
+    };
+  }
+  return out;
+};
+
+const buildDatBuffer = (parts) => {
+  const chunks = [];
+  for (let i = 0; i < parts.length; i += 1) {
+    const part = parts[i];
+    const packed = PackFilePart.pack(part.raw);
+    const size = packed.byteArray.length + 10;
+    const header = new Uint8Array(10);
+    header[0] = packed.initialBits & 0xff;
+    header[1] = packed.checksum & 0xff;
+    writeWord(header, 2, part.unknown1 | 0);
+    writeWord(header, 4, part.raw.length);
+    writeWord(header, 6, part.unknown0 | 0);
+    writeWord(header, 8, size);
+    chunks.push(Buffer.from(header));
+    chunks.push(Buffer.from(packed.byteArray));
+  }
+  return Buffer.concat(chunks);
+};
+
+const unpackCommand = (inputPath, outDir) => {
+  const reader = getInputReader(inputPath);
+  const container = new FileContainer(reader);
+  const parts = collectParts(container);
+
+  fs.mkdirSync(outDir, { recursive: true });
+  const metadata = {
+    format: 'lemmings-dat-pipeline-v1',
+    source: path.basename(inputPath),
+    partCount: parts.length,
+    parts: []
+  };
+
+  for (let i = 0; i < parts.length; i += 1) {
+    const part = parts[i];
+    const file = `part-${String(i).padStart(3, '0')}.bin`;
+    fs.writeFileSync(path.join(outDir, file), Buffer.from(part.raw));
+    metadata.parts.push({
+      index: part.index,
+      file,
+      decompressedSize: part.raw.length,
+      unknown1: part.unknown1,
+      unknown0: part.unknown0
+    });
+  }
+  fs.writeFileSync(path.join(outDir, 'meta.json'), JSON.stringify(metadata, null, 2));
+};
+
+const packCommand = (metaPath, outputPath) => {
+  const rawMeta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+  const baseDir = path.resolve(path.dirname(metaPath));
+  const entries = Array.isArray(rawMeta.parts) ? rawMeta.parts.slice() : [];
+  entries.sort((a, b) => (a.index | 0) - (b.index | 0));
+  const parts = new Array(entries.length);
+  for (let i = 0; i < entries.length; i += 1) {
+    const entry = entries[i];
+    const rawPath = resolveMetadataPartPath(baseDir, entry.file);
+    const raw = new Uint8Array(fs.readFileSync(rawPath));
+    parts[i] = {
+      index: entry.index | 0,
+      unknown1: Number.isFinite(entry.unknown1) ? entry.unknown1 : 0,
+      unknown0: Number.isFinite(entry.unknown0) ? entry.unknown0 : 0,
+      raw
+    };
+  }
+  const dat = buildDatBuffer(parts);
+  fs.writeFileSync(outputPath, dat);
+};
+
+const patchCommand = (inputPath, outputPath, args) => {
+  const partFlag = args.indexOf('--part');
+  const offsetFlag = args.indexOf('--offset');
+  const fileFlag = args.indexOf('--file');
+  if (partFlag < 0 || offsetFlag < 0 || fileFlag < 0) {
+    throw new Error('patch requires --part, --offset, and --file');
+  }
+  const partIndex = parseInt10(args[partFlag + 1], -1);
+  const patchOffset = parseInt10(args[offsetFlag + 1], -1);
+  const patchPath = args[fileFlag + 1];
+  if (partIndex < 0 || patchOffset < 0 || !patchPath) {
+    throw new Error('invalid patch arguments');
+  }
+
+  const reader = getInputReader(inputPath);
+  const container = new FileContainer(reader);
+  const parts = collectParts(container);
+  if (partIndex >= parts.length) {
+    throw new Error(`part index out of range: ${partIndex}`);
+  }
+  const patchBytes = new Uint8Array(fs.readFileSync(patchPath));
+  const target = parts[partIndex].raw;
+  if ((patchOffset + patchBytes.length) > target.length) {
+    throw new Error('patch exceeds decompressed part size');
+  }
+  target.set(patchBytes, patchOffset);
+
+  const dat = buildDatBuffer(parts);
+  fs.writeFileSync(outputPath, dat);
+};
+
+const main = () => {
+  const [command, ...args] = process.argv.slice(2);
+  if (!command) {
+    process.stdout.write(USAGE);
+    return;
+  }
+  try {
+    if (command === 'unpack') {
+      const [inputPath, outDir] = args;
+      if (!inputPath || !outDir) {
+        process.stdout.write(USAGE);
+        return;
+      }
+      unpackCommand(inputPath, outDir);
+      return;
+    }
+    if (command === 'pack') {
+      const [metaPath, outputPath] = args;
+      if (!metaPath || !outputPath) {
+        process.stdout.write(USAGE);
+        return;
+      }
+      packCommand(metaPath, outputPath);
+      return;
+    }
+    if (command === 'patch') {
+      const [inputPath, outputPath, ...rest] = args;
+      if (!inputPath || !outputPath) {
+        process.stdout.write(USAGE);
+        return;
+      }
+      patchCommand(inputPath, outputPath, rest);
+      return;
+    }
+    process.stdout.write(USAGE);
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    process.exit(1);
+  }
+};
+
+main();
diff --git a/tools/patchSprites.js b/tools/patchSprites.js
index 5df1fe51..69e34a97 100644
--- a/tools/patchSprites.js
+++ b/tools/patchSprites.js
@@ -4,6 +4,7 @@ import { NodeFileProvider } from './NodeFileProvider.js';
 import { PNG } from 'pngjs';
 import fs from 'fs';
 import path from 'path';
+import { once } from 'events';
 import { PackFilePart } from '../js/data/PackFilePart.js';
 
 function usage() {
@@ -31,7 +32,6 @@ async function main() {
   // Use an empty root path so absolute input paths work correctly
   const provider = new NodeFileProvider('');
   const datReader = await provider.loadBinary(path.dirname(datFile), path.basename(datFile));
-  const buf = fs.readFileSync(datFile);
   const container = new Lemmings.FileContainer(datReader);
 
   // Map of part index -> new raw buffer
@@ -111,34 +111,41 @@ async function main() {
     part._compressedData = packed.byteArray; // store temporarily
   }
 
-  // Serialize new container
+  // Serialize new container using streamed writes so large packs do not require
+  // a single contiguous output allocation.
   const HEADER_SIZE = 10;
+  const outStream = fs.createWriteStream(outFile);
   let total = 0;
-  for (const part of container.parts) {
-    const size = (part._compressedData ? part._compressedData.length : part.compressedSize) + HEADER_SIZE;
-    total += size;
-  }
-  const out = new Uint8Array(total);
-  let offset = 0;
+  const writeChunk = async (chunk) => {
+    if (!outStream.write(chunk)) {
+      await once(outStream, 'drain');
+    }
+  };
+
   for (const part of container.parts) {
     const data = part._compressedData || datReader.data.subarray(part.offset, part.offset + part.compressedSize);
-    out[offset] = part.initialBufferLen;
-    out[offset+1] = part.checksum;
-    out[offset+2] = (part.unknown1 >> 8) & 0xFF;
-    out[offset+3] = part.unknown1 & 0xFF;
-    out[offset+4] = (part.decompressedSize >> 8) & 0xFF;
-    out[offset+5] = part.decompressedSize & 0xFF;
-    out[offset+6] = (part.unknown0 >> 8) & 0xFF;
-    out[offset+7] = part.unknown0 & 0xFF;
+    const header = new Uint8Array(HEADER_SIZE);
+    header[0] = part.initialBufferLen;
+    header[1] = part.checksum;
+    header[2] = (part.unknown1 >> 8) & 0xFF;
+    header[3] = part.unknown1 & 0xFF;
+    header[4] = (part.decompressedSize >> 8) & 0xFF;
+    header[5] = part.decompressedSize & 0xFF;
+    header[6] = (part.unknown0 >> 8) & 0xFF;
+    header[7] = part.unknown0 & 0xFF;
     const size = data.length + HEADER_SIZE;
-    out[offset+8] = (size >> 8) & 0xFF;
-    out[offset+9] = size & 0xFF;
-    out.set(data, offset + HEADER_SIZE);
-    offset += size;
+    header[8] = (size >> 8) & 0xFF;
+    header[9] = size & 0xFF;
+    await writeChunk(header);
+    await writeChunk(data);
+    total += size;
   }
 
-  fs.writeFileSync(outFile, out);
-  console.log(`Wrote ${outFile}`);
+  await new Promise((resolve, reject) => {
+    outStream.once('error', reject);
+    outStream.end(resolve);
+  });
+  console.log(`Wrote ${outFile} (${total} bytes)`);
 }
 
 await main();
diff --git a/tsconfig.checkjs.json b/tsconfig.checkjs.json
new file mode 100644
index 00000000..a641308a
--- /dev/null
+++ b/tsconfig.checkjs.json
@@ -0,0 +1,37 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "checkJs": true,
+    "noEmit": true,
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": false,
+    "noImplicitAny": false,
+    "noResolve": true,
+    "lib": ["ES2022", "DOM"],
+    "skipLibCheck": true,
+    "types": []
+  },
+  "include": [
+    "js/game/HistoryStore.js",
+    "js/game/history/**/*.js",
+    "js/render/Stage.js",
+    "js/app/midi-ui/midiUiDebug.js",
+    "js/app/midi-ui/midiUiDevices.js",
+    "js/app/midi-ui/midiUiFeatureFlags.js",
+    "js/app/midi-ui/midiUiIntent.js",
+    "js/app/midi-ui/midiUiRefreshSections.js",
+    "js/editor/editor-controller/EditorControllerPointer.js",
+    "js/editor/editor-controller/EditorControllerPointerInput.js",
+    "js/editor/editor-controller/EditorControllerPointerSelection.js",
+    "js/editor/editor-controller/EditorControllerPointerTools.js",
+    "js/app/editor-ui/EditorUiBindings.js",
+    "js/app/editor-ui/EditorUiBindingControls.js",
+    "js/app/editor-ui/EditorUiBindingLifecycle.js",
+    "js/app/editor-ui/EditorUiBindingTools.js",
+    "js/app/e2e/E2EEditorApplyHelpers.js",
+    "js/level/Trigger.js",
+    "mcp/toolRouting.js"
+  ]
+}