@woosh/meep-engine 3.0.2 → 3.2.0

package/src/REVIEW_2026_08_06/engine-misc.md

@@ -1,248 +1,248 @@
-# Correctness review — engine misc (save, metrics, platform, google, ui, options, scene, plugin, knowledge, achievements, development, logging, notify, simulation, reference, engine root)
-
-Reviewed 2026-08-06. Correctness only. All paths absolute under
-`H:/git/moh/app/src/mir-engine/meep/src/engine/`.
-
----
-
-### EMISC-1 IndexedDB store reports success before the transaction commits (silent save loss)
-- **Severity**: MAJOR
-- **File**: `save/storage/IndexedDBStorage.js:98-128` (also `remove` at :45-76)
-- **Defect**: `store()` resolves the caller on the *request*'s `success` event. In IndexedDB a request succeeding does not mean the data is durable — the write is only committed when the enclosing transaction fires `complete`. A transaction that aborts after the request succeeded (quota exceeded at commit, browser eviction, page teardown) never notifies anyone, because no `abort`/`error` listener is attached to the transaction. The file's own header says `TODO add QuotaExceededError handling`.
-- **Failure scenario**: `GameSaveStateManager.store()` → `storage.store('game-save-state-<id>-data', <8 MB ArrayBuffer>, resolve, reject)`. The `put` request fires `success`, `resolve()` runs, `GameStateLoader.save()` resolves and the UI prints "saved". The transaction then aborts with `QuotaExceededError` on commit. Nothing rejects, nothing logs. The slot id was already appended to the id list by `StorageBackedSet` (a separate transaction that fit), so the next `update()` lists a save whose data key does not exist; loading it resolves with `undefined` (see EMISC-11) and the run is unrecoverable.
-- **Fix**: hold the transaction (`const tx = db.transaction(...)`), resolve on `tx.addEventListener('complete', ...)` and reject on `tx.addEventListener('abort'|'error', ...)`; keep the request-level `error` listener only to capture the reason.
-- **Confidence**: Confirmed
-
----
-
-### EMISC-2 `Engine.start()` throws when constructed with `enableAudio: false`
-- **Severity**: MAJOR
-- **File**: `Engine.js:584`
-- **Defect**: The constructor only creates `this.sound` when `enableAudio !== false` (`Engine.js:290-302`), and `#initialize_audio()` explicitly guards `sound === undefined` (`Engine.js:421-424`). `start()` does not: `this.sound.start()` is evaluated unconditionally while building the `Promise.all` array, so it throws synchronously before `start()` returns a promise.
-- **Failure scenario**: `const e = new Engine(new InMemoryEnginePlatform(), {enableAudio:false, enableGraphics:false}); await e.start();` → `TypeError: Cannot read properties of undefined (reading 'start')` thrown synchronously out of `start()`. This exact construction is used by in-repo specs (`Engine.spec.js:12`, `EngineConfiguration.spec.js:24`, `ecs/dynamic_actions/DynamicActorSystem.spec.js:12`) — none can call `start()` today.
-- **Fix**: `const p_sound = this.sound === undefined ? Promise.resolve() : this.sound.start();` then chain `promiseEntityManager` off `p_sound`.
-- **Confidence**: Confirmed
-
----
-
-### EMISC-3 `Engine.render()` dereferences `graphics` before the guard that tests it
-- **Severity**: MAJOR
-- **File**: `Engine.js:542-549`
-- **Defect**: 
-  ```js
-  const graphics = this.graphics;
-  if (graphics.autoDraw) { graphics.needDraw = true; }   // line 544 — unguarded
-  if (graphics && this.renderingEnabled && graphics.needDraw) { ... }  // line 549 — guard, too late
-  ```
-  The later `graphics &&` proves the author expects `graphics` to be absent (it is, whenever `enableGraphics:false`).
-- **Failure scenario**: `new Engine(platform, {enableGraphics:false, enableAudio:true})`, then `start()`. `start()` schedules `requestAnimationFrame(this.#animation_frame)` (`Engine.js:596`), which calls `this.render()` (`Engine.js:621`) → `TypeError: Cannot read properties of undefined (reading 'autoDraw')` on every animation frame, forever, and the frame-delay metric at `Engine.js:629` is never recorded. Two other sites in scope have the same unguarded dependency once graphics is disabled: `ui/GUIEngine.js:481` (`engine.graphics.domElement.classList` inside the cursor `process` callback, run during `startup`) and `ui/bindings/DomElementProcessorManager.js:300,309`.
-- **Fix**: move the `autoDraw` read inside the existing `graphics !== undefined` guard (single `if (graphics !== undefined && this.renderingEnabled) { if (graphics.autoDraw) graphics.needDraw = true; ... }`), and guard the two GUI sites the same way.
-- **Confidence**: Confirmed
-
----
-
-### EMISC-4 `Engine.stop()` throws instead of shutting down, and never stops the render loop
-- **Severity**: MAJOR
-- **File**: `Engine.js:635-656` (interacts with `simulation/Ticker.js:250`)
-- **Defect**: `stop()` calls `this.ticker.pause()`. `Ticker.pause()` throws `Error("Not currently running")` whenever `is_active` is false (`simulation/Ticker.js:261-263`), and `is_active` requires *both* handles to be set — but `Ticker.start()` discards the handle of its first `requestAnimationFrame` (`Ticker.js:250`), so `is_active` stays `false` from `start()` until the first rAF *and* the following `setTimeout(...,0)` have both run. Additionally `stop()` uses `pause()` rather than `ticker.stop()`, so the ticker's rAF/timeout loop keeps cycling after shutdown, and the engine's own `#animation_frame` rAF loop (`Engine.js:616-630`) is never cancelled at all — no handle is ever stored for it.
-- **Failure scenario A**: `await engine.start(); await engine.stop();` (the options load at `Engine.js:603` resolves on a microtask with `InMemoryStorage`, well before the first rAF) → `stop()` throws at the first statement after the monitor stop; `entityManager.shutdown`, `plugins.shutdown`, `gui.shutdown` and `assetManager.shutdown` never run, leaving all listeners, timers and GPU resources alive.
-- **Failure scenario B**: the same in a backgrounded tab, where rAF never fires — `is_active` is permanently false, so `engine.stop()` can never succeed.
-- **Failure scenario C**: after a `stop()` that does get past the throw, `#animation_frame` keeps calling `this.render()` every frame forever, retaining the whole engine graph.
-- **Fix**: call `this.ticker.stop()` (idempotent, no throw) in `Engine.stop()`; store the `#animation_frame` handle in a field and `cancelAnimationFrame` it in `stop()`; store the first rAF handle in `Ticker.start()` (see known-issue list).
-- **Confidence**: Confirmed
-
----
-
-### EMISC-5 `Engine.start()` reports success after a failed startup
-- **Severity**: MAJOR
-- **File**: `Engine.js:583-610`
-- **Defect**: The `Promise.all([...])` rejection handler is `function (e) { logger.error(...) }` — it logs and returns `undefined`, which *fulfils* the promise returned by `start()`. Nothing downstream can tell startup apart from failure, and the fulfilment branch (ticker start, options load) is skipped.
-- **Failure scenario**: `staticKnowledge.load()` fails to fetch `data/database/.../data.json` (404 after a deploy). `start()` resolves. `EngineHarness.initialize` then proceeds to `document.body.appendChild(...)` and resolves the harness promise with a "started" engine whose ticker was never started (`Engine.js:599` skipped), whose options were never loaded (`:603` skipped) and whose knowledge tables are empty — the game renders a black screen with no error surfaced to the caller.
-- **Fix**: rethrow after logging (`(e) => { logger.error(...); throw e; }`) so `start()` rejects.
-- **Confidence**: Confirmed
-
----
-
-### EMISC-6 `Clock.pause()` accumulates time while the clock is already stopped
-- **Severity**: MAJOR
-- **File**: `Clock.js:87-91`
-- **Defect**: 
-  ```js
-  pause() {
-      this.__isRunning = false;
-      updateElapsedTime(this);   // module-level fn: adds (now - __lastMeasurement) * speed unconditionally
-  }
-  ```
-  It calls the *module* helper, bypassing the `__isRunning` check in `Clock.updateElapsedTime()` (`:108-113`). Every `pause()` on an already-paused (or never-started) clock injects the interval since the last measurement into `elapsedTime`.
-- **Failure scenario**: player alt-tabs; `Ticker.#suspend()` calls `clock.pause()` at t=100 s (`simulation/Ticker.js:120`). Ten minutes later, while still hidden, the app pauses explicitly (`ticker.pause()` → `clock.pause()`, `Ticker.js:269`). The second `pause()` adds 600 s to `elapsedTime` even though the clock was stopped the whole time. `DynamicActorSystem.getCurrentTime()` (`ecs/dynamic_actions/DynamicActorSystem.js:174`) and `VoiceSystem.getCurrentTime()` (`ecs/speaker/VoiceSystem.js:262`) read that value directly, and cooldowns are stored as absolute ready-times (`DynamicActorSystem.js:248,405`) — so on return every global cooldown is considered expired and the actor barks fire in a burst. Second instance of the same defect: `new Ticker()` calls `clock.pause()` in its constructor (`Ticker.js:72`) on a clock whose `__lastMeasurement` is still `0`, so a fresh `Engine`'s clock starts at "seconds since page load" instead of 0, contradicting `getElapsedTime()`'s documented contract.
-- **Fix**: `pause() { this.updateElapsedTime(); this.__isRunning = false; }` — use the guarded instance method and clear the flag afterwards.
-- **Confidence**: Confirmed
-
----
-
-### EMISC-7 Plugins that skip `super.initialize()/super.startup()` never leave `ProcessState.New`, so startup re-runs
-- **Severity**: MAJOR
-- **File**: `achievements/AchievementManager.js:232-238` and `:421-430`; `save/GameStateLoader.js:15-17`
-- **Defect**: `BaseProcess` is what advances the state machine (`core/process/BaseProcess.js:24-59`), and `PluginReferenceContext` navigates purely on that state (`plugin/PluginReferenceContext.js:20-95`). `AchievementManager.initialize()` overrides `EnginePlugin.initialize()` without calling `super.initialize(engine)`, and `AchievementManager.startup()`/`GameStateLoader.startup()` never call `super.startup()`. Their state therefore stays `New` (resp. `Initialized`) forever. `navigate_to_running` re-runs `initialize()` + `startup()` on *every* transition request instead of short-circuiting, and `navigate_to_finalized` returns immediately for state `New` — so `shutdown()` is never invoked. `ui/bindings/DomElementProcessorManager.js:267-280` does it correctly, which shows the intended contract.
-- **Failure scenario**: any plugin that declares `AchievementManager` in `dependencies`, or a second `plugins.startup()` (engine restart), routes through `__transition_plugin_to_state` (`plugin/EnginePluginManager.js:75-101`), which sees `dependency_state !== Running` and calls `transition(Running)` again → `navigate_to_running` → `AchievementManager.startup()` a second time → `loadDefinitions()` pushes a full duplicate set into `this.entries` (`AchievementManager.js:249-255`). Result: every achievement appears twice in the list UI, `activate()` registers two handlers per id while `this.handlers[id]` keeps only the last one (the first can never be removed by `deactivateEntry`), and an already-unlocked achievement re-presents its popup + sound. Separately, `Engine.stop()` → `plugins.shutdown()` never calls `AchievementManager.shutdown()` at all, so blackboard references and trigger subscriptions survive engine teardown.
-- **Fix**: call `super.initialize(engine)` at the end of `AchievementManager.initialize`, and `await super.startup()` / `super.startup()` in both `startup()` overrides.
-- **Confidence**: Confirmed
-
----
-
-### EMISC-8 `AchievementManager.startup()` does not await `initializeGateway()`
-- **Severity**: MAJOR
-- **File**: `achievements/AchievementManager.js:421-430` (call at :427)
-- **Defect**: `this.initializeGateway();` is fired without `await`, then `this.isStarted.set(true)` runs immediately. `initializeGateway` awaits `gateway.getUnlocked()` (a storage round trip) before it sets `isGatewayInitialized`. Setting `isStarted` flips `isActive` (`:108-119`) → `activate()` → `activateEntry()` → `ReactiveExpression.process()` which invokes the handler synchronously with the current value (`core/model/reactive/model/ReactiveExpression.js:88-95`).
-- **Failure scenario**: a save is loaded whose blackboard already satisfies an achievement condition, so the blackboard is attached before startup. `startup()` → `isStarted.set(true)` → `activate()` → handler fires `true` → `unlock(id)`. Inside `unlock`, `this.isGatewayInitialized.getValue()` is still `false` (`:157`), so `deactivateEntry()` and `present()` are both skipped: the achievement is written to the gateway and to the blackboard but the player never sees the notification, and the trigger stays subscribed so it can fire again. Additionally, a rejection from `getUnlocked()` becomes an unhandled promise rejection with no state change at all (`isGatewayInitialized` stays false permanently, so *no* achievement is ever presented for the rest of the session).
-- **Fix**: `await this.initializeGateway();` before `this.isStarted.set(true)`.
-- **Confidence**: Confirmed
-
----
-
-### EMISC-9 `EngineHarness.initialize()` uses an async function as a Promise executor — failures vanish and the promise never settles
-- **Severity**: MAJOR
-- **File**: `EngineHarness.js:126-166`
-- **Defect**: `new Promise(async function (resolve, reject) { ... })`. Any rejection inside the executor rejects the *executor's own* (discarded) promise; `resolve`/`reject` are never called, so the promise returned by `initialize()` — and cached in `this.p` — stays pending forever. There is no `try/catch` and `reject` is never used.
-- **Failure scenario**: a plugin's `startup()` throws inside `await config.apply(engine)` (`:135`), or `await engine.start()` rejects (`:140`). `await EngineHarness.bootstrap({configuration})` never resolves and never rejects: the harness hangs with a blank page, no console error, and the memoised `this.p` guarantees every retry hangs too.
-- **Fix**: make the body a plain async function and return its promise (`const promise = (async () => { ... return engine; })();`), or wrap the executor body in `try { ... } catch (e) { reject(e); }`.
-- **Confidence**: Confirmed
-
----
-
-### EMISC-10 `GameStateLoader.count()` has no rejection path — the promise never settles on failure
-- **Severity**: MAJOR
-- **File**: `save/GameStateLoader.js:119-136`
-- **Defect**: `gameSaves.update().then(() => { ... resolve(matches.length); });` — no second `then` argument, no `.catch(reject)`, unlike `load()` (`:110`) and `exists()` (`:164`) which both wire `reject`.
-- **Failure scenario**: `update()` rejects because the IndexedDB list read fails (private-browsing quota, corrupt store, DB open error propagated from `IndexedDBStorage.list`'s `.catch(reject)`). The `resolve` callback is never called and `reject` is never called, so a caller doing `new Promise((res, rej) => loader.count(name, res, rej))` awaits forever — the save-slot UI spins with no error, and the failure only shows up as an unhandled rejection in the console.
-- **Fix**: append `.catch(reject)` (and pass a `reject` through, matching `exists()`).
-- **Confidence**: Confirmed
-
----
-
-### EMISC-11 `GameStateLoader.load()` resolves with `undefined` for a save that does not exist
-- **Severity**: MAJOR
-- **File**: `save/GameStateLoader.js:68-111` (legacy branch at :101-103)
-- **Defect**: When no non-locked metadata matches, `load()` falls back to `legacyLoad` → `storage.loadBinary(name, resolve, ...)`. Both storage backends deliberately use `undefined` as the "missing key" sentinel (`save/storage/IndexedDBStorage.js:88-90` resolves `event.target.result`; `save/storage/InMemoryStorage.js:15` resolves `this.#data.get(key)`), and every other consumer checks for it (`save/StorageBackedList.js:59`, `achievements/gateway/StorageAchievementGateway.js:29`). `load()` does not: it forwards `undefined` to the success callback, so "no such save" is reported as "load succeeded, here is your data".
-- **Failure scenario**: `model/game/Game.js:102-106` calls `gameStateLoader.load('auto-save', json => loadStateJSON(json))` with no reject handler. With no auto-save present, `loadStateJSON(undefined)` → `game.initializeFromState(undefined)` → TypeError deep inside state restoration instead of a clean "no save found". The same path is reachable from any UI that offers Load before a save exists.
-- **Fix**: in the legacy branch, reject (or resolve a documented sentinel) when the loaded value is `undefined`, e.g. `lResolve` wrapped: `data => data === undefined ? lReject(new Error(...)) : lResolve(data)`.
-- **Confidence**: Confirmed
-
----
-
-### EMISC-12 `pickDefaultLocale()` can return a locale that is not among the supported options
-- **Severity**: MAJOR
-- **File**: `platform/WebEnginePlatform.js:35-98` (`:81-85`)
-- **Defect**: When no supplied locale scores above 0, the function returns the hard-coded `'en-gb'` regardless of whether `'en-gb'` is in `localeOptions`. The documented contract (`platform/EnginePlatform.js:18-22`: `@param {string[]} options @returns {string}`) is that the result is one of `options`.
-- **Failure scenario**: a title shipping `['ru', 'de']` runs on a browser with `navigator.languages === ['ja-JP']`. Every option scores 0, so `pickDefaultLocale` returns `'en-gb'`. `Localization.loadLocale('en-gb')` then requests a locale file that was never built; the load fails and every `getString(key)` renders the literal `@key` placeholder throughout the UI.
-- **Failure scenario (secondary)**: `localeOptions === []` → `array_pick_best_element` returns `undefined` → `best.score` throws `TypeError`.
-- **Fix**: fall back to `localeOptions[0]` (mirroring `InMemoryEnginePlatform.pickDefaultLocale`) rather than a hard-coded id.
-- **Confidence**: Confirmed
-
----
-
-### EMISC-13 The `meep` library imports source from the host application
-- **Severity**: MAJOR
-- **File**: `save/GameStateLoader.js:1`, `scene/SerializedScene.js:1`
-- **Defect**: 
-  - `import { GameSaveStateMetadata } from "../../../../view/game/save/GameSaveStateMetadata.js";` resolves to `app/src/mir-engine/view/game/save/GameSaveStateMetadata.js` — outside the `meep/` package. The symbol is referenced only from a JSDoc `@type`, so the runtime dependency is entirely gratuitous.
-  - `import { MirScene } from "../../../../model/game/scenes/MirScene.js";` resolves to `app/src/mir-engine/model/game/scenes/MirScene.js`; `SerializedScene extends MirScene`, i.e. an engine class is rooted in a game-specific class.
-- **Failure scenario**: any consumer that installs `meep` on its own (the package is published as `@woosh/meep-engine`, and app code already imports it by that specifier — see `view/game/save/GameSaveStateManager.js:1-3`) fails at bundle time with `Module not found: ../../../../view/game/save/GameSaveStateMetadata.js`. Inside this repo the effect is that the entire `view/game/save` and `model/game/scenes` subtrees are pulled into any bundle that touches the save subsystem.
-- **Fix**: delete the `GameSaveStateMetadata` import (JSDoc-only — reference the type by name or drop the annotation). For `SerializedScene`, base it on the engine's own `Scene` and let the game subclass it, or move `SerializedScene` out of `meep` into the app.
-- **Confidence**: Confirmed
-
----
-
-### EMISC-14 `getURLHash()`'s non-browser guard throws instead of guarding
-- **Severity**: MINOR
-- **File**: `platform/GetURLHash.js:8-10`
-- **Defect**: `if (window === undefined) { return result; }` — in an environment where `window` is not *declared*, evaluating the identifier throws `ReferenceError` before the comparison happens; in a browser the comparison is never true. The guard can therefore never fire. The correct form is `typeof window === "undefined"` (compare with `browserInfo.js:12-16` and `simulation/Ticker.js:146`, which both use `globalThis.X === undefined` correctly).
-- **Failure scenario**: `getURLHash()` (public export, also used by `EngineHarness.setLocale` at `EngineHarness.js:45`) called from Node/SSR/a worker → `ReferenceError: window is not defined`, where the author's intent was an empty `{}`.
-- **Fix**: `const w = globalThis.window; if (w === undefined) { return result; }`.
-- **Confidence**: Confirmed
-
----
-
-### EMISC-15 `Scene.setup()` reads the global `name` instead of `this.name`
-- **Severity**: MINOR
-- **File**: `scene/Scene.js:84`
-- **Defect**: `` promiseTask(..., `${name} scene setup`) `` — `name` is not in scope; it resolves to the global. There is no local, parameter or class field named `name` in that method.
-- **Failure scenario**: in a browser, `window.name` is normally `""`, so a scene called "main" produces the task label `" scene setup"` instead of `"main scene setup"`, and that label is what the loading screen shows. In Node (specs, headless tooling) there is no global `name`, so `Scene.setup()` throws `ReferenceError: name is not defined` — module code is strict, so there is no implicit-global fallback.
-- **Fix**: `` `${this.name} scene setup` ``.
-- **Confidence**: Confirmed
-
----
-
-### EMISC-16 `IndexedDBStorage.list()` uses the removed `IDBTransaction.READ_ONLY` constant
-- **Severity**: MINOR
-- **File**: `save/storage/IndexedDBStorage.js:133`
-- **Defect**: `db.transaction(MAIN_STORE_NAME, IDBTransaction.READ_ONLY)` while every other method in the file correctly uses `IndexedDBTransactionMode.ReadOnly`. The legacy `IDBTransaction` constants were removed from the spec; in current browsers the expression evaluates to `undefined` (which WebIDL then defaults back to `"readonly"`, so it happens to work), and the statement additionally hard-depends on the `IDBTransaction` *global* existing.
-- **Failure scenario**: running against an IndexedDB shim that provides `indexedDB` but does not install `IDBTransaction` as a global (a common way to polyfill for tests/Node) — `store`, `load` and `remove` all work, while `list()` alone throws `ReferenceError: IDBTransaction is not defined`, which surfaces as `Storage.contains()` failing (`save/Storage.js:105-110` is implemented on top of `list`).
-- **Fix**: `IndexedDBTransactionMode.ReadOnly`.
-- **Confidence**: Confirmed
-
----
-
-### EMISC-17 One failed achievement write poisons every later `unlock()`
-- **Severity**: MINOR
-- **File**: `achievements/gateway/StorageAchievementGateway.js:39-74`
-- **Defect**: The serialisation chain is built with `this.last.finally(cb)`. `Promise.prototype.finally` propagates the *upstream* settlement: once `this.last` is rejected, every subsequent `unlock()` returns a promise that rejects with the original, stale reason even when its own write succeeded — and `this.last` is then re-poisoned, permanently.
-- **Failure scenario**: `unlock('first_blood')` fails (storage error). `this.last` is a rejected promise. `unlock('level_10')` later writes the id to storage successfully, but the promise it returns rejects with the `first_blood` error. `AchievementManager.unlock()` ignores the returned promise (`achievements/AchievementManager.js:149`), so this manifests as one unhandled rejection per achievement for the rest of the session, and any caller that does await it sees a false failure.
-- **Fix**: chain with `this.last.then(cb, cb)` (as `StorageBackedSet.read` does at `save/StorageBackedList.js:71`) so each write's result is independent.
-- **Confidence**: Confirmed
-
----
-
-### EMISC-18 `browserInfo()` returns `version: undefined` on Opera, and does not cache the IE/Opera results
-- **Severity**: MINOR
-- **File**: `browserInfo.js:26-31` (cache at `:8`,`:45`)
-- **Defect**: `ua.match(/\bOPR|Edge\/(\d+)/)` — the capture group belongs only to the `Edge/(\d+)` alternative, so for an Opera UA (`... OPR/98.0.4759.15`) the `\bOPR` branch matches and `tem[1]` is `undefined`. The function returns `{name:'Opera', version: undefined}`. The IE and Opera branches also `return` before `cached = result`, so the memoisation at `:8` never applies to them (every call re-runs the regexes).
-- **Failure scenario**: on Opera, `browserInfo().version` is `undefined`; any gate of the form `browserInfo().version >= 90` evaluates `undefined >= 90` → `false`, so a version-gated code path is taken as if the browser were ancient. (Chromium Edge's UA token is `Edg/`, not `Edge/`, so Edge never matches this branch at all and is reported as Chrome.)
-- **Fix**: `/\b(?:OPR|Edge)\/(\d+)/` and assign `cached` on every return path.
-- **Confidence**: Confirmed
-
----
-
-### EMISC-19 `count()` counts locked saves that `exists()` and `load()` deliberately ignore
-- **Severity**: MINOR
-- **File**: `save/GameStateLoader.js:131` vs `:84-95` and `:155`
-- **Defect**: `load()` filters `m.locked` out and `exists()` filters `!m.locked`, but `count()` matches on name only.
-- **Failure scenario**: the only save named `"quicksave"` is locked. `count('quicksave')` → `1`, so an overwrite-confirmation dialog is shown ("1 save exists, overwrite?"), while `exists('quicksave')` → falls through to `legacyExists` → `false` and `load('quicksave')` falls through to the legacy path and resolves `undefined` (EMISC-11). The three APIs disagree about the same slot.
-- **Fix**: apply the same `!m.locked` predicate in `count()`.
-- **Confidence**: Confirmed
-
----
-
-### EMISC-20 `DomElementProcessorManager.unlink()` leaves every binding live; a restart double-binds
-- **Severity**: MINOR
-- **File**: `ui/bindings/DomElementProcessorManager.js:303-310` (vs `link` at `:286-301`)
-- **Defect**: `link()` walks the tree and creates a `DomElementBinding` per match, storing them in `__element_to_bindings`. `unlink()` disconnects the observer and removes the pre-render handler but never calls `binding.unbind()` (which is what runs `processor.shutdown()`) and never clears `__element_to_bindings`.
-- **Failure scenario**: `plugins.shutdown()` → `unlink()`, then a later `plugins.startup()` → `link()` → `__handleAttachedElement(root)` re-binds every still-attached element, appending a *second* binding to the existing array. `__handle_frame_entry` then runs both processors per element per frame; for `DomElementProcessorTilt3D` two handlers write `el.style.transform` in sequence each frame, and the first generation's processors can never be shut down because their bindings are unreachable through any element-removal path that would call `unbind()`.
-- **Fix**: in `unlink()`, iterate `__element_to_bindings`, call `unbind()` on each binding, then `clear()` the map.
-- **Confidence**: Confirmed
-
----
-
-### EMISC-21 Viewport sizing always falls back to `window`; the sized-container path is unreachable
-- **Severity**: MINOR
-- **File**: `Engine.js:475-490`
-- **Defect**: 
-  ```js
-  while (parentElement !== null && parentElement.innerWidth === undefined) { parentElement = parentElement.parentElement; }
-  ```
-  `innerWidth` is a `Window` property; no `Element` ever has it, so the condition holds for every ancestor and the loop always terminates with `parentElement === null` (past `<html>`), after which the code substitutes `window`. The intended "traverse up until we find an element with defined dimensions" can never succeed.
-- **Failure scenario**: the engine is mounted into a 640×480 host `<div>` (an embedded/editor layout) with `graphics_control_viewport_size` enabled. Instead of sizing to the container, `viewStack.size` is set to `window.innerWidth/innerHeight`, so the canvas and the whole GUI stack overflow the container by the full page size, and every `resize` re-applies it.
-- **Fix**: measure the host element with `getBoundingClientRect()`/`clientWidth`/`clientHeight` (checking for a non-zero box) instead of probing for `innerWidth`.
-- **Confidence**: Confirmed
-
----
-
-## Status of previously-known issues
-
-| Known issue | Status |
-| --- | --- |
-| `Ticker.pause()` not pausing the clock | FIXED — `simulation/Ticker.js:269` now calls `this.clock.pause()` (but see EMISC-6: `Clock.pause()` itself over-accumulates). |
-| `Ticker.start()` discarding the rAF handle | STILL PRESENT — `simulation/Ticker.js:250`; consequences: `is_active` is false for the first frame after `start()` (breaks `pause()`/`resume()`/`Engine.stop()`, EMISC-4), and a `stop()` issued before that first frame cannot cancel it, so the loop resurrects itself and runs forever. |
-| `SceneManager.clear()` leaving clock speed-modifiers applied | FIXED — `scene/SceneManager.js:153-165` routes through `deactivateScene()`. |
-| `ElasticSearchLogger` posting a JSON array / `performance.now()` as `@timestamp` | PARTIALLY FIXED — NDJSON `_bulk` body is correct (`logging/elastic/ElasticSearchLogger.js:110-123`); the timestamp is STILL `performance.now()` (`:151`, emitted at `:117`), so every document lands at 1970-01-01 + a few seconds in Elasticsearch. |
-| `GUIEngine.shutdown` leaks | STILL PRESENT — `ui/GUIEngine.js:501-513` does not stop `this.ticker` (started at `:470`), does not unbind `engine.gameView.size.process` (`:464`), does not unbind `this.cursor.process` (`:476`), does not detach `this.view` from `gameView`, and never calls `shutdown()` on any `SceneGUIContext` in `sceneContexts`. |
+# Correctness review — engine misc (save, metrics, platform, google, ui, options, scene, plugin, knowledge, achievements, development, logging, notify, simulation, reference, engine root)
+
+Reviewed 2026-08-06. Correctness only. All paths absolute under
+`H:/git/moh/app/src/mir-engine/meep/src/engine/`.
+
+---
+
+### EMISC-1 IndexedDB store reports success before the transaction commits (silent save loss)
+- **Severity**: MAJOR
+- **File**: `save/storage/IndexedDBStorage.js:98-128` (also `remove` at :45-76)
+- **Defect**: `store()` resolves the caller on the *request*'s `success` event. In IndexedDB a request succeeding does not mean the data is durable — the write is only committed when the enclosing transaction fires `complete`. A transaction that aborts after the request succeeded (quota exceeded at commit, browser eviction, page teardown) never notifies anyone, because no `abort`/`error` listener is attached to the transaction. The file's own header says `TODO add QuotaExceededError handling`.
+- **Failure scenario**: `GameSaveStateManager.store()` → `storage.store('game-save-state-<id>-data', <8 MB ArrayBuffer>, resolve, reject)`. The `put` request fires `success`, `resolve()` runs, `GameStateLoader.save()` resolves and the UI prints "saved". The transaction then aborts with `QuotaExceededError` on commit. Nothing rejects, nothing logs. The slot id was already appended to the id list by `StorageBackedSet` (a separate transaction that fit), so the next `update()` lists a save whose data key does not exist; loading it resolves with `undefined` (see EMISC-11) and the run is unrecoverable.
+- **Fix**: hold the transaction (`const tx = db.transaction(...)`), resolve on `tx.addEventListener('complete', ...)` and reject on `tx.addEventListener('abort'|'error', ...)`; keep the request-level `error` listener only to capture the reason.
+- **Confidence**: Confirmed
+
+---
+
+### EMISC-2 `Engine.start()` throws when constructed with `enableAudio: false`
+- **Severity**: MAJOR
+- **File**: `Engine.js:584`
+- **Defect**: The constructor only creates `this.sound` when `enableAudio !== false` (`Engine.js:290-302`), and `#initialize_audio()` explicitly guards `sound === undefined` (`Engine.js:421-424`). `start()` does not: `this.sound.start()` is evaluated unconditionally while building the `Promise.all` array, so it throws synchronously before `start()` returns a promise.
+- **Failure scenario**: `const e = new Engine(new InMemoryEnginePlatform(), {enableAudio:false, enableGraphics:false}); await e.start();` → `TypeError: Cannot read properties of undefined (reading 'start')` thrown synchronously out of `start()`. This exact construction is used by in-repo specs (`Engine.spec.js:12`, `EngineConfiguration.spec.js:24`, `ecs/dynamic_actions/DynamicActorSystem.spec.js:12`) — none can call `start()` today.
+- **Fix**: `const p_sound = this.sound === undefined ? Promise.resolve() : this.sound.start();` then chain `promiseEntityManager` off `p_sound`.
+- **Confidence**: Confirmed
+
+---
+
+### EMISC-3 `Engine.render()` dereferences `graphics` before the guard that tests it
+- **Severity**: MAJOR
+- **File**: `Engine.js:542-549`
+- **Defect**: 
+  ```js
+  const graphics = this.graphics;
+  if (graphics.autoDraw) { graphics.needDraw = true; }   // line 544 — unguarded
+  if (graphics && this.renderingEnabled && graphics.needDraw) { ... }  // line 549 — guard, too late
+  ```
+  The later `graphics &&` proves the author expects `graphics` to be absent (it is, whenever `enableGraphics:false`).
+- **Failure scenario**: `new Engine(platform, {enableGraphics:false, enableAudio:true})`, then `start()`. `start()` schedules `requestAnimationFrame(this.#animation_frame)` (`Engine.js:596`), which calls `this.render()` (`Engine.js:621`) → `TypeError: Cannot read properties of undefined (reading 'autoDraw')` on every animation frame, forever, and the frame-delay metric at `Engine.js:629` is never recorded. Two other sites in scope have the same unguarded dependency once graphics is disabled: `ui/GUIEngine.js:481` (`engine.graphics.domElement.classList` inside the cursor `process` callback, run during `startup`) and `ui/bindings/DomElementProcessorManager.js:300,309`.
+- **Fix**: move the `autoDraw` read inside the existing `graphics !== undefined` guard (single `if (graphics !== undefined && this.renderingEnabled) { if (graphics.autoDraw) graphics.needDraw = true; ... }`), and guard the two GUI sites the same way.
+- **Confidence**: Confirmed
+
+---
+
+### EMISC-4 `Engine.stop()` throws instead of shutting down, and never stops the render loop
+- **Severity**: MAJOR
+- **File**: `Engine.js:635-656` (interacts with `simulation/Ticker.js:250`)
+- **Defect**: `stop()` calls `this.ticker.pause()`. `Ticker.pause()` throws `Error("Not currently running")` whenever `is_active` is false (`simulation/Ticker.js:261-263`), and `is_active` requires *both* handles to be set — but `Ticker.start()` discards the handle of its first `requestAnimationFrame` (`Ticker.js:250`), so `is_active` stays `false` from `start()` until the first rAF *and* the following `setTimeout(...,0)` have both run. Additionally `stop()` uses `pause()` rather than `ticker.stop()`, so the ticker's rAF/timeout loop keeps cycling after shutdown, and the engine's own `#animation_frame` rAF loop (`Engine.js:616-630`) is never cancelled at all — no handle is ever stored for it.
+- **Failure scenario A**: `await engine.start(); await engine.stop();` (the options load at `Engine.js:603` resolves on a microtask with `InMemoryStorage`, well before the first rAF) → `stop()` throws at the first statement after the monitor stop; `entityManager.shutdown`, `plugins.shutdown`, `gui.shutdown` and `assetManager.shutdown` never run, leaving all listeners, timers and GPU resources alive.
+- **Failure scenario B**: the same in a backgrounded tab, where rAF never fires — `is_active` is permanently false, so `engine.stop()` can never succeed.
+- **Failure scenario C**: after a `stop()` that does get past the throw, `#animation_frame` keeps calling `this.render()` every frame forever, retaining the whole engine graph.
+- **Fix**: call `this.ticker.stop()` (idempotent, no throw) in `Engine.stop()`; store the `#animation_frame` handle in a field and `cancelAnimationFrame` it in `stop()`; store the first rAF handle in `Ticker.start()` (see known-issue list).
+- **Confidence**: Confirmed
+
+---
+
+### EMISC-5 `Engine.start()` reports success after a failed startup
+- **Severity**: MAJOR
+- **File**: `Engine.js:583-610`
+- **Defect**: The `Promise.all([...])` rejection handler is `function (e) { logger.error(...) }` — it logs and returns `undefined`, which *fulfils* the promise returned by `start()`. Nothing downstream can tell startup apart from failure, and the fulfilment branch (ticker start, options load) is skipped.
+- **Failure scenario**: `staticKnowledge.load()` fails to fetch `data/database/.../data.json` (404 after a deploy). `start()` resolves. `EngineHarness.initialize` then proceeds to `document.body.appendChild(...)` and resolves the harness promise with a "started" engine whose ticker was never started (`Engine.js:599` skipped), whose options were never loaded (`:603` skipped) and whose knowledge tables are empty — the game renders a black screen with no error surfaced to the caller.
+- **Fix**: rethrow after logging (`(e) => { logger.error(...); throw e; }`) so `start()` rejects.
+- **Confidence**: Confirmed
+
+---
+
+### EMISC-6 `Clock.pause()` accumulates time while the clock is already stopped
+- **Severity**: MAJOR
+- **File**: `Clock.js:87-91`
+- **Defect**: 
+  ```js
+  pause() {
+      this.__isRunning = false;
+      updateElapsedTime(this);   // module-level fn: adds (now - __lastMeasurement) * speed unconditionally
+  }
+  ```
+  It calls the *module* helper, bypassing the `__isRunning` check in `Clock.updateElapsedTime()` (`:108-113`). Every `pause()` on an already-paused (or never-started) clock injects the interval since the last measurement into `elapsedTime`.
+- **Failure scenario**: player alt-tabs; `Ticker.#suspend()` calls `clock.pause()` at t=100 s (`simulation/Ticker.js:120`). Ten minutes later, while still hidden, the app pauses explicitly (`ticker.pause()` → `clock.pause()`, `Ticker.js:269`). The second `pause()` adds 600 s to `elapsedTime` even though the clock was stopped the whole time. `DynamicActorSystem.getCurrentTime()` (`ecs/dynamic_actions/DynamicActorSystem.js:174`) and `VoiceSystem.getCurrentTime()` (`ecs/speaker/VoiceSystem.js:262`) read that value directly, and cooldowns are stored as absolute ready-times (`DynamicActorSystem.js:248,405`) — so on return every global cooldown is considered expired and the actor barks fire in a burst. Second instance of the same defect: `new Ticker()` calls `clock.pause()` in its constructor (`Ticker.js:72`) on a clock whose `__lastMeasurement` is still `0`, so a fresh `Engine`'s clock starts at "seconds since page load" instead of 0, contradicting `getElapsedTime()`'s documented contract.
+- **Fix**: `pause() { this.updateElapsedTime(); this.__isRunning = false; }` — use the guarded instance method and clear the flag afterwards.
+- **Confidence**: Confirmed
+
+---
+
+### EMISC-7 Plugins that skip `super.initialize()/super.startup()` never leave `ProcessState.New`, so startup re-runs
+- **Severity**: MAJOR
+- **File**: `achievements/AchievementManager.js:232-238` and `:421-430`; `save/GameStateLoader.js:15-17`
+- **Defect**: `BaseProcess` is what advances the state machine (`core/process/BaseProcess.js:24-59`), and `PluginReferenceContext` navigates purely on that state (`plugin/PluginReferenceContext.js:20-95`). `AchievementManager.initialize()` overrides `EnginePlugin.initialize()` without calling `super.initialize(engine)`, and `AchievementManager.startup()`/`GameStateLoader.startup()` never call `super.startup()`. Their state therefore stays `New` (resp. `Initialized`) forever. `navigate_to_running` re-runs `initialize()` + `startup()` on *every* transition request instead of short-circuiting, and `navigate_to_finalized` returns immediately for state `New` — so `shutdown()` is never invoked. `ui/bindings/DomElementProcessorManager.js:267-280` does it correctly, which shows the intended contract.
+- **Failure scenario**: any plugin that declares `AchievementManager` in `dependencies`, or a second `plugins.startup()` (engine restart), routes through `__transition_plugin_to_state` (`plugin/EnginePluginManager.js:75-101`), which sees `dependency_state !== Running` and calls `transition(Running)` again → `navigate_to_running` → `AchievementManager.startup()` a second time → `loadDefinitions()` pushes a full duplicate set into `this.entries` (`AchievementManager.js:249-255`). Result: every achievement appears twice in the list UI, `activate()` registers two handlers per id while `this.handlers[id]` keeps only the last one (the first can never be removed by `deactivateEntry`), and an already-unlocked achievement re-presents its popup + sound. Separately, `Engine.stop()` → `plugins.shutdown()` never calls `AchievementManager.shutdown()` at all, so blackboard references and trigger subscriptions survive engine teardown.
+- **Fix**: call `super.initialize(engine)` at the end of `AchievementManager.initialize`, and `await super.startup()` / `super.startup()` in both `startup()` overrides.
+- **Confidence**: Confirmed
+
+---
+
+### EMISC-8 `AchievementManager.startup()` does not await `initializeGateway()`
+- **Severity**: MAJOR
+- **File**: `achievements/AchievementManager.js:421-430` (call at :427)
+- **Defect**: `this.initializeGateway();` is fired without `await`, then `this.isStarted.set(true)` runs immediately. `initializeGateway` awaits `gateway.getUnlocked()` (a storage round trip) before it sets `isGatewayInitialized`. Setting `isStarted` flips `isActive` (`:108-119`) → `activate()` → `activateEntry()` → `ReactiveExpression.process()` which invokes the handler synchronously with the current value (`core/model/reactive/model/ReactiveExpression.js:88-95`).
+- **Failure scenario**: a save is loaded whose blackboard already satisfies an achievement condition, so the blackboard is attached before startup. `startup()` → `isStarted.set(true)` → `activate()` → handler fires `true` → `unlock(id)`. Inside `unlock`, `this.isGatewayInitialized.getValue()` is still `false` (`:157`), so `deactivateEntry()` and `present()` are both skipped: the achievement is written to the gateway and to the blackboard but the player never sees the notification, and the trigger stays subscribed so it can fire again. Additionally, a rejection from `getUnlocked()` becomes an unhandled promise rejection with no state change at all (`isGatewayInitialized` stays false permanently, so *no* achievement is ever presented for the rest of the session).
+- **Fix**: `await this.initializeGateway();` before `this.isStarted.set(true)`.
+- **Confidence**: Confirmed
+
+---
+
+### EMISC-9 `EngineHarness.initialize()` uses an async function as a Promise executor — failures vanish and the promise never settles
+- **Severity**: MAJOR
+- **File**: `EngineHarness.js:126-166`
+- **Defect**: `new Promise(async function (resolve, reject) { ... })`. Any rejection inside the executor rejects the *executor's own* (discarded) promise; `resolve`/`reject` are never called, so the promise returned by `initialize()` — and cached in `this.p` — stays pending forever. There is no `try/catch` and `reject` is never used.
+- **Failure scenario**: a plugin's `startup()` throws inside `await config.apply(engine)` (`:135`), or `await engine.start()` rejects (`:140`). `await EngineHarness.bootstrap({configuration})` never resolves and never rejects: the harness hangs with a blank page, no console error, and the memoised `this.p` guarantees every retry hangs too.
+- **Fix**: make the body a plain async function and return its promise (`const promise = (async () => { ... return engine; })();`), or wrap the executor body in `try { ... } catch (e) { reject(e); }`.
+- **Confidence**: Confirmed
+
+---
+
+### EMISC-10 `GameStateLoader.count()` has no rejection path — the promise never settles on failure
+- **Severity**: MAJOR
+- **File**: `save/GameStateLoader.js:119-136`
+- **Defect**: `gameSaves.update().then(() => { ... resolve(matches.length); });` — no second `then` argument, no `.catch(reject)`, unlike `load()` (`:110`) and `exists()` (`:164`) which both wire `reject`.
+- **Failure scenario**: `update()` rejects because the IndexedDB list read fails (private-browsing quota, corrupt store, DB open error propagated from `IndexedDBStorage.list`'s `.catch(reject)`). The `resolve` callback is never called and `reject` is never called, so a caller doing `new Promise((res, rej) => loader.count(name, res, rej))` awaits forever — the save-slot UI spins with no error, and the failure only shows up as an unhandled rejection in the console.
+- **Fix**: append `.catch(reject)` (and pass a `reject` through, matching `exists()`).
+- **Confidence**: Confirmed
+
+---
+
+### EMISC-11 `GameStateLoader.load()` resolves with `undefined` for a save that does not exist
+- **Severity**: MAJOR
+- **File**: `save/GameStateLoader.js:68-111` (legacy branch at :101-103)
+- **Defect**: When no non-locked metadata matches, `load()` falls back to `legacyLoad` → `storage.loadBinary(name, resolve, ...)`. Both storage backends deliberately use `undefined` as the "missing key" sentinel (`save/storage/IndexedDBStorage.js:88-90` resolves `event.target.result`; `save/storage/InMemoryStorage.js:15` resolves `this.#data.get(key)`), and every other consumer checks for it (`save/StorageBackedList.js:59`, `achievements/gateway/StorageAchievementGateway.js:29`). `load()` does not: it forwards `undefined` to the success callback, so "no such save" is reported as "load succeeded, here is your data".
+- **Failure scenario**: `model/game/Game.js:102-106` calls `gameStateLoader.load('auto-save', json => loadStateJSON(json))` with no reject handler. With no auto-save present, `loadStateJSON(undefined)` → `game.initializeFromState(undefined)` → TypeError deep inside state restoration instead of a clean "no save found". The same path is reachable from any UI that offers Load before a save exists.
+- **Fix**: in the legacy branch, reject (or resolve a documented sentinel) when the loaded value is `undefined`, e.g. `lResolve` wrapped: `data => data === undefined ? lReject(new Error(...)) : lResolve(data)`.
+- **Confidence**: Confirmed
+
+---
+
+### EMISC-12 `pickDefaultLocale()` can return a locale that is not among the supported options
+- **Severity**: MAJOR
+- **File**: `platform/WebEnginePlatform.js:35-98` (`:81-85`)
+- **Defect**: When no supplied locale scores above 0, the function returns the hard-coded `'en-gb'` regardless of whether `'en-gb'` is in `localeOptions`. The documented contract (`platform/EnginePlatform.js:18-22`: `@param {string[]} options @returns {string}`) is that the result is one of `options`.
+- **Failure scenario**: a title shipping `['ru', 'de']` runs on a browser with `navigator.languages === ['ja-JP']`. Every option scores 0, so `pickDefaultLocale` returns `'en-gb'`. `Localization.loadLocale('en-gb')` then requests a locale file that was never built; the load fails and every `getString(key)` renders the literal `@key` placeholder throughout the UI.
+- **Failure scenario (secondary)**: `localeOptions === []` → `array_pick_best_element` returns `undefined` → `best.score` throws `TypeError`.
+- **Fix**: fall back to `localeOptions[0]` (mirroring `InMemoryEnginePlatform.pickDefaultLocale`) rather than a hard-coded id.
+- **Confidence**: Confirmed
+
+---
+
+### EMISC-13 The `meep` library imports source from the host application
+- **Severity**: MAJOR
+- **File**: `save/GameStateLoader.js:1`, `scene/SerializedScene.js:1`
+- **Defect**: 
+  - `import { GameSaveStateMetadata } from "../../../../view/game/save/GameSaveStateMetadata.js";` resolves to `app/src/mir-engine/view/game/save/GameSaveStateMetadata.js` — outside the `meep/` package. The symbol is referenced only from a JSDoc `@type`, so the runtime dependency is entirely gratuitous.
+  - `import { MirScene } from "../../../../model/game/scenes/MirScene.js";` resolves to `app/src/mir-engine/model/game/scenes/MirScene.js`; `SerializedScene extends MirScene`, i.e. an engine class is rooted in a game-specific class.
+- **Failure scenario**: any consumer that installs `meep` on its own (the package is published as `@woosh/meep-engine`, and app code already imports it by that specifier — see `view/game/save/GameSaveStateManager.js:1-3`) fails at bundle time with `Module not found: ../../../../view/game/save/GameSaveStateMetadata.js`. Inside this repo the effect is that the entire `view/game/save` and `model/game/scenes` subtrees are pulled into any bundle that touches the save subsystem.
+- **Fix**: delete the `GameSaveStateMetadata` import (JSDoc-only — reference the type by name or drop the annotation). For `SerializedScene`, base it on the engine's own `Scene` and let the game subclass it, or move `SerializedScene` out of `meep` into the app.
+- **Confidence**: Confirmed
+
+---
+
+### EMISC-14 `getURLHash()`'s non-browser guard throws instead of guarding
+- **Severity**: MINOR
+- **File**: `platform/GetURLHash.js:8-10`
+- **Defect**: `if (window === undefined) { return result; }` — in an environment where `window` is not *declared*, evaluating the identifier throws `ReferenceError` before the comparison happens; in a browser the comparison is never true. The guard can therefore never fire. The correct form is `typeof window === "undefined"` (compare with `browserInfo.js:12-16` and `simulation/Ticker.js:146`, which both use `globalThis.X === undefined` correctly).
+- **Failure scenario**: `getURLHash()` (public export, also used by `EngineHarness.setLocale` at `EngineHarness.js:45`) called from Node/SSR/a worker → `ReferenceError: window is not defined`, where the author's intent was an empty `{}`.
+- **Fix**: `const w = globalThis.window; if (w === undefined) { return result; }`.
+- **Confidence**: Confirmed
+
+---
+
+### EMISC-15 `Scene.setup()` reads the global `name` instead of `this.name`
+- **Severity**: MINOR
+- **File**: `scene/Scene.js:84`
+- **Defect**: `` promiseTask(..., `${name} scene setup`) `` — `name` is not in scope; it resolves to the global. There is no local, parameter or class field named `name` in that method.
+- **Failure scenario**: in a browser, `window.name` is normally `""`, so a scene called "main" produces the task label `" scene setup"` instead of `"main scene setup"`, and that label is what the loading screen shows. In Node (specs, headless tooling) there is no global `name`, so `Scene.setup()` throws `ReferenceError: name is not defined` — module code is strict, so there is no implicit-global fallback.
+- **Fix**: `` `${this.name} scene setup` ``.
+- **Confidence**: Confirmed
+
+---
+
+### EMISC-16 `IndexedDBStorage.list()` uses the removed `IDBTransaction.READ_ONLY` constant
+- **Severity**: MINOR
+- **File**: `save/storage/IndexedDBStorage.js:133`
+- **Defect**: `db.transaction(MAIN_STORE_NAME, IDBTransaction.READ_ONLY)` while every other method in the file correctly uses `IndexedDBTransactionMode.ReadOnly`. The legacy `IDBTransaction` constants were removed from the spec; in current browsers the expression evaluates to `undefined` (which WebIDL then defaults back to `"readonly"`, so it happens to work), and the statement additionally hard-depends on the `IDBTransaction` *global* existing.
+- **Failure scenario**: running against an IndexedDB shim that provides `indexedDB` but does not install `IDBTransaction` as a global (a common way to polyfill for tests/Node) — `store`, `load` and `remove` all work, while `list()` alone throws `ReferenceError: IDBTransaction is not defined`, which surfaces as `Storage.contains()` failing (`save/Storage.js:105-110` is implemented on top of `list`).
+- **Fix**: `IndexedDBTransactionMode.ReadOnly`.
+- **Confidence**: Confirmed
+
+---
+
+### EMISC-17 One failed achievement write poisons every later `unlock()`
+- **Severity**: MINOR
+- **File**: `achievements/gateway/StorageAchievementGateway.js:39-74`
+- **Defect**: The serialisation chain is built with `this.last.finally(cb)`. `Promise.prototype.finally` propagates the *upstream* settlement: once `this.last` is rejected, every subsequent `unlock()` returns a promise that rejects with the original, stale reason even when its own write succeeded — and `this.last` is then re-poisoned, permanently.
+- **Failure scenario**: `unlock('first_blood')` fails (storage error). `this.last` is a rejected promise. `unlock('level_10')` later writes the id to storage successfully, but the promise it returns rejects with the `first_blood` error. `AchievementManager.unlock()` ignores the returned promise (`achievements/AchievementManager.js:149`), so this manifests as one unhandled rejection per achievement for the rest of the session, and any caller that does await it sees a false failure.
+- **Fix**: chain with `this.last.then(cb, cb)` (as `StorageBackedSet.read` does at `save/StorageBackedList.js:71`) so each write's result is independent.
+- **Confidence**: Confirmed
+
+---
+
+### EMISC-18 `browserInfo()` returns `version: undefined` on Opera, and does not cache the IE/Opera results
+- **Severity**: MINOR
+- **File**: `browserInfo.js:26-31` (cache at `:8`,`:45`)
+- **Defect**: `ua.match(/\bOPR|Edge\/(\d+)/)` — the capture group belongs only to the `Edge/(\d+)` alternative, so for an Opera UA (`... OPR/98.0.4759.15`) the `\bOPR` branch matches and `tem[1]` is `undefined`. The function returns `{name:'Opera', version: undefined}`. The IE and Opera branches also `return` before `cached = result`, so the memoisation at `:8` never applies to them (every call re-runs the regexes).
+- **Failure scenario**: on Opera, `browserInfo().version` is `undefined`; any gate of the form `browserInfo().version >= 90` evaluates `undefined >= 90` → `false`, so a version-gated code path is taken as if the browser were ancient. (Chromium Edge's UA token is `Edg/`, not `Edge/`, so Edge never matches this branch at all and is reported as Chrome.)
+- **Fix**: `/\b(?:OPR|Edge)\/(\d+)/` and assign `cached` on every return path.
+- **Confidence**: Confirmed
+
+---
+
+### EMISC-19 `count()` counts locked saves that `exists()` and `load()` deliberately ignore
+- **Severity**: MINOR
+- **File**: `save/GameStateLoader.js:131` vs `:84-95` and `:155`
+- **Defect**: `load()` filters `m.locked` out and `exists()` filters `!m.locked`, but `count()` matches on name only.
+- **Failure scenario**: the only save named `"quicksave"` is locked. `count('quicksave')` → `1`, so an overwrite-confirmation dialog is shown ("1 save exists, overwrite?"), while `exists('quicksave')` → falls through to `legacyExists` → `false` and `load('quicksave')` falls through to the legacy path and resolves `undefined` (EMISC-11). The three APIs disagree about the same slot.
+- **Fix**: apply the same `!m.locked` predicate in `count()`.
+- **Confidence**: Confirmed
+
+---
+
+### EMISC-20 `DomElementProcessorManager.unlink()` leaves every binding live; a restart double-binds
+- **Severity**: MINOR
+- **File**: `ui/bindings/DomElementProcessorManager.js:303-310` (vs `link` at `:286-301`)
+- **Defect**: `link()` walks the tree and creates a `DomElementBinding` per match, storing them in `__element_to_bindings`. `unlink()` disconnects the observer and removes the pre-render handler but never calls `binding.unbind()` (which is what runs `processor.shutdown()`) and never clears `__element_to_bindings`.
+- **Failure scenario**: `plugins.shutdown()` → `unlink()`, then a later `plugins.startup()` → `link()` → `__handleAttachedElement(root)` re-binds every still-attached element, appending a *second* binding to the existing array. `__handle_frame_entry` then runs both processors per element per frame; for `DomElementProcessorTilt3D` two handlers write `el.style.transform` in sequence each frame, and the first generation's processors can never be shut down because their bindings are unreachable through any element-removal path that would call `unbind()`.
+- **Fix**: in `unlink()`, iterate `__element_to_bindings`, call `unbind()` on each binding, then `clear()` the map.
+- **Confidence**: Confirmed
+
+---
+
+### EMISC-21 Viewport sizing always falls back to `window`; the sized-container path is unreachable
+- **Severity**: MINOR
+- **File**: `Engine.js:475-490`
+- **Defect**: 
+  ```js
+  while (parentElement !== null && parentElement.innerWidth === undefined) { parentElement = parentElement.parentElement; }
+  ```
+  `innerWidth` is a `Window` property; no `Element` ever has it, so the condition holds for every ancestor and the loop always terminates with `parentElement === null` (past `<html>`), after which the code substitutes `window`. The intended "traverse up until we find an element with defined dimensions" can never succeed.
+- **Failure scenario**: the engine is mounted into a 640×480 host `<div>` (an embedded/editor layout) with `graphics_control_viewport_size` enabled. Instead of sizing to the container, `viewStack.size` is set to `window.innerWidth/innerHeight`, so the canvas and the whole GUI stack overflow the container by the full page size, and every `resize` re-applies it.
+- **Fix**: measure the host element with `getBoundingClientRect()`/`clientWidth`/`clientHeight` (checking for a non-zero box) instead of probing for `innerWidth`.
+- **Confidence**: Confirmed
+
+---
+
+## Status of previously-known issues
+
+| Known issue | Status |
+| --- | --- |
+| `Ticker.pause()` not pausing the clock | FIXED — `simulation/Ticker.js:269` now calls `this.clock.pause()` (but see EMISC-6: `Clock.pause()` itself over-accumulates). |
+| `Ticker.start()` discarding the rAF handle | STILL PRESENT — `simulation/Ticker.js:250`; consequences: `is_active` is false for the first frame after `start()` (breaks `pause()`/`resume()`/`Engine.stop()`, EMISC-4), and a `stop()` issued before that first frame cannot cancel it, so the loop resurrects itself and runs forever. |
+| `SceneManager.clear()` leaving clock speed-modifiers applied | FIXED — `scene/SceneManager.js:153-165` routes through `deactivateScene()`. |
+| `ElasticSearchLogger` posting a JSON array / `performance.now()` as `@timestamp` | PARTIALLY FIXED — NDJSON `_bulk` body is correct (`logging/elastic/ElasticSearchLogger.js:110-123`); the timestamp is STILL `performance.now()` (`:151`, emitted at `:117`), so every document lands at 1970-01-01 + a few seconds in Elasticsearch. |
+| `GUIEngine.shutdown` leaks | STILL PRESENT — `ui/GUIEngine.js:501-513` does not stop `this.ticker` (started at `:470`), does not unbind `engine.gameView.size.process` (`:464`), does not unbind `this.cursor.process` (`:476`), does not detach `this.view` from `gameView`, and never calls `shutdown()` on any `SceneGUIContext` in `sceneContexts`. |