@downdraft/engine 0.1.0 → 0.1.2-alpha.5

package/dist/core/src/index.js

@@ -0,0 +1,191 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// @downdraft/engine — public API barrel
+//
+// Re-exports from sub-barrels (ecs, render, assets, material, module, scene,
+// physics, util) plus remaining direct exports for modules without a sub-barrel.
+// ─────────────────────────────────────────────────────────────────────────────
+/// <reference path="./webgpu-destroy-augmentation.d.ts" />
+// Sub-barrel re-exports — these aggregate all items from their respective domains.
+export * from "./assets/index.js";
+export * from "./ecs/index.js";
+export * from "./library/index.js";
+export * from "./material/index.js";
+export * from "./module/index.js";
+export * from "./physics/index.js";
+export * from "./plugin/index.js";
+export * from "./render/index.js";
+export * from "./scene/index.js";
+export * from "./util/index.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Engine version — single source of truth for the engine's semver.
+// Used by the feature log, save headers (via features.saves.engineVersion
+// default), and any code that needs to report the running engine version.
+// Sourced from package.json so it can never drift from the published version.
+// Defined in ./version.ts so leaf-import consumers skip this barrel.
+// ─────────────────────────────────────────────────────────────────────────────
+export { ENGINE_VERSION } from "./version.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Worker (task-worker lives outside ecs/)
+// ─────────────────────────────────────────────────────────────────────────────
+export { hasTask, registerTask, unregisterTask } from "./worker/task-worker.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Change Detection
+// ─────────────────────────────────────────────────────────────────────────────
+export { ChangeTracker } from "./change-detection/tracker.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Engine Types (math, identifiers, enums, message protocols)
+// ─────────────────────────────────────────────────────────────────────────────
+export { EntityFlags } from "./types/engine-types.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// SAB
+// ─────────────────────────────────────────────────────────────────────────────
+export { CoreInputChannel } from "./sab/core-input-channel.js";
+export { InputSABChannel } from "./sab/input.js";
+export { createMultiInputChannel, DEFAULT_KEY_BITFIELD_COUNT, DEFAULT_MAX_PLAYERS, MultiInputChannel } from "./sab/multi-input-channel.js";
+// Game Input SAB Channel
+export { INP, INP_FLAG, INP_HDR, INPUT_MAGIC, INPUT_VERSION, InputBufferReader, InputBufferWriter, InputChannel, KEY, MAX_INPUT_PLAYERS } from "./sab/game-input.js";
+// Sim SAB Channel
+export { allocateInputBuffer, allocateSimBuffer, ENT, MAX_ENTITIES, MAX_PLAYERS, PLR, PLR_FLAG, SIM_ENTITY_SLOT_SIZE, SIM_HDR, SIM_MAGIC, SIM_PLAYER_SLOT_SIZE, SIM_VERSION, SimBufferReader, SimBufferWriter, SimChannel } from "./sab/sim-channel.js";
+// SAB Framework
+export { defineChannel, defineManifest } from "./sab/define.js";
+export { isDebug, resetWarnings, ValidationError as SABValidationError, setDebug, warnOnce } from "./sab/errors.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Worker
+// ─────────────────────────────────────────────────────────────────────────────
+export { BaseWorkerHost } from "./worker/base-worker-host.js";
+export { BufferSyncHost, BufferSyncWorker, isBufferSyncMessage } from "./worker/buffer-sync.js";
+export { CrashRecoveryManager, DEFAULT_RECOVERY_CONFIG } from "./worker/crash-recovery.js";
+export { EntitySimWorkerHost } from "./worker/entity-sim-worker-host.js";
+export { exposeProfilingApi, InstrumentedWorkerHost } from "./worker/instrumented-worker-host.js";
+export { expose, exposeEvents, getWorkerHost, wrap } from "./worker/rpc.js";
+export { createSimWorker } from "./worker/sim-worker-base.js";
+export { RawInputRegionWriter, SimWorkerHost } from "./worker/sim-worker-host.js";
+export { createTaskWorker, PortChannel, TaskPool } from "./worker/task-pool.js";
+// SAB polyfill (no-op where SharedArrayBuffer is native)
+export { usingRealSAB } from "./sab/sab-polyfill.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Input
+// ─────────────────────────────────────────────────────────────────────────────
+export { InputContextRouter } from "./input/context.js";
+export { createDomInputHandler } from "./input/dom-handler.js";
+export { LocalPlayerManager } from "./input/local-player-manager.js";
+export { InputMapping } from "./input/mapping.js";
+export { createMultiInputBridge, createMultiInputWriter, MultiInputSABBridge, MultiInputSABWriter } from "./input/multi-sab-bridge.js";
+export { MultiInputState } from "./input/multi-state.js";
+export { InputSABBridge } from "./input/sab-bridge.js";
+export { InputContext, InputState } from "./input/state.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Platform
+// ─────────────────────────────────────────────────────────────────────────────
+export { createGlob, globAssets } from "./platform/glob-polyfill.js";
+export { getDpr, HiDPIManager } from "./platform/hidpi.js";
+export { RPC } from "./platform/rpc.js";
+export { getHostCapabilities, getNativeHost, hasHMR, isBun, isDev, isDevMode, NATIVE_HOST_CAPABILITIES } from "./platform/runtime.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Mesh
+// ─────────────────────────────────────────────────────────────────────────────
+export { MeshBuilder } from "./mesh/builder.js";
+export { BSPNode, csgIntersect, csgSubtract, csgUnion } from "./mesh/csg.js";
+export { createGreasedLine, createGreasedLineMeshData } from "./mesh/greased-line.js";
+export { cone, cylinder, disc, lathe, ribbon, tessellatedPlane, torus, tube } from "./mesh/parametric.js";
+export { gpuVertexFormat, PBR_VERTEX_LAYOUT, SKINNED_VERTEX_LAYOUT, STANDARD_VERTEX_LAYOUT, vertexFormatSize, wgslVertexFormat } from "./mesh/vertex-layout.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Telemetry
+// ─────────────────────────────────────────────────────────────────────────────
+export { TelemetryCollector } from "./telemetry/collector.js";
+export { DEFAULT_GC_CONTROLLER_CONFIG, GCController } from "./telemetry/gc-controller.js";
+export { startGCProfiler } from "./telemetry/gc-profiler.js";
+export { GCTracker } from "./telemetry/gc-tracker.js";
+export { GPUProfiler } from "./telemetry/gpu-profiler.js";
+export { GPUResourceTracker } from "./telemetry/gpu-resource-tracker.js";
+export { GPUTimer } from "./telemetry/gpu-timer.js";
+export { GPUTimerPool } from "./telemetry/gpu-timer-pool.js";
+export { TelemetryReporter } from "./telemetry/reporter.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Profiling (in-game declarative profiling system)
+//
+// The full profiling API is available via the `@downdraft/engine/profiling`
+// subpath. Here we re-export the most commonly used items for convenience.
+// Workers import the prelude via `import "@downdraft/engine/profiling/worker-prelude"`.
+// ─────────────────────────────────────────────────────────────────────────────
+export { DEFAULT_RENDERER_WARNING_RULES, DEFAULT_WORKER_WARNING_RULES, EventLoopMonitor, TaskLatencyHistogram, TraceEventWriter, WarningEngine } from "./profiling/index.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Debug Draw
+// ─────────────────────────────────────────────────────────────────────────────
+export { DebugLines } from "./debug-draw/lines.js";
+export { DebugPoints } from "./debug-draw/points.js";
+export { DebugDrawQueue } from "./debug-draw/queue.js";
+export { DebugTextRenderer } from "./debug-draw/text.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Scripting
+// ─────────────────────────────────────────────────────────────────────────────
+export { createScriptBinding } from "./scripting/binding.js";
+export { HotReloader } from "./scripting/hot-reload.js";
+export { ScriptingSystem } from "./scripting/script.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Save (legacy ECS serializer)
+// ─────────────────────────────────────────────────────────────────────────────
+export { SaveSystem } from "./save/migrate.js";
+export { CURRENT_SCHEMA_VERSION, SchemaRegistry } from "./save/schema.js";
+export { Serializer } from "./save/serializer.js";
+// Save (new persistence system)
+export { decodeHeader, encodeHeader, engineVersionString, HEADER_SIZE, packEngineVersion, readHeaderFromFile, SAVE_FORMAT_VERSION, SAVE_MAGIC, unpackEngineVersion, XXH128_SIZE } from "./save/binary-format.js";
+export { MigrationRegistryImpl } from "./save/migration-registry.js";
+// Grid save system factory — eliminates duplicated save-system boilerplate
+export { createGameSaveSystem } from "./save/game-save-system.js";
+export { createGridSaveSystem } from "./save/grid-save-system.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Animation
+// ─────────────────────────────────────────────────────────────────────────────
+export * from "./animation/index.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Mesh Skinning
+// ─────────────────────────────────────────────────────────────────────────────
+export { BoneTransforms, buildSkinnedMeshFromGLTF, createSkinMatricesBuffer, MAX_BONES, SkinnedMesh } from "./mesh/skinning.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Audio
+// ─────────────────────────────────────────────────────────────────────────────
+export { AudioEngine } from "./audio/engine.js";
+export { DEFAULT_AUDIO_CONFIG } from "./audio/interface.js";
+export { AudioListener, createAudioListener, listenerToState } from "./audio/listener.js";
+export { AudioMixer } from "./audio/mixer.js";
+export { audioBackendRegistry } from "./audio/registry.js";
+export { AudioSABChannel, AudioSABChannelDef } from "./audio/sab.js";
+export { AudioSource, createAmbientAudioSource, createAudioSource, createSpatialAudioSource } from "./audio/source.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Particles
+// ─────────────────────────────────────────────────────────────────────────────
+export * from "./particles/index.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// UI — input router contract + font-scale storage helpers (html-ui renders the
+// actual documents; see modules/html-ui and libraries/blitz-ui)
+// ─────────────────────────────────────────────────────────────────────────────
+export { UIInputRouter } from "./input/ui-router.js";
+export { detectSystemFontScale, FONT_SCALE_STORAGE_KEY, getEffectiveFontScale, getSystemFontScale, loadUserFontScale, saveUserFontScale } from "./ui-font-scale.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Math
+// ─────────────────────────────────────────────────────────────────────────────
+export { composeMat4Into, invertMat4, invertMat4Into, lookAtMat4Into, multiplyMat4Into, perspectiveMat4Into, transformMat4Vec4 } from "./math/mat4.js";
+export { PerlinNoise2D } from "./math/perlin-noise-2d.js";
+export { PerlinNoise3D } from "./math/perlin-noise-3d.js";
+export { eulerXYZToQuat, quatMul } from "./math/quat.js";
+export { createRng, mulberry32 } from "./math/rng.js";
+export { fastCos, fastSin } from "./math/trig.js";
+export { fbm2D, hash2, smoothstep, valueNoise2D } from "./math/value-noise.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Stores
+// ─────────────────────────────────────────────────────────────────────────────
+export { createBaseGameStoreState } from "./stores/game-store.js";
+export { useHotReloadStore } from "./stores/hot-reload-store.js";
+// Sim Worker Loop (reusable setTimeout-based loop for Web Workers)
+export { SimWorkerLoop } from "./sim/worker-loop.js";
+// Hot-Reload Pipeline (framework-owned hot-reload lifecycle)
+export { HotReloadPipeline } from "./sim/hot-reload-pipeline.js";
+export { SimStateHelper } from "./sim/sim-state-helper.js";
+export { TransientStateRegistry } from "./sim/transient-state-registry.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Safety utilities (path validation, safe JSON parse, bounds checking)
+// ─────────────────────────────────────────────────────────────────────────────
+export { assertBounds, assertCount, assertFinite, assertPositive, clamp, clampSafeInt, MAX_ARRAY_LENGTH, MAX_DECOMPRESS_SIZE, MAX_FACE_COUNT, MAX_FETCH_SIZE, MAX_MIP_LEVELS, MAX_NODE_DEPTH, MAX_TEXTURE_DIM, MAX_VERTEX_COUNT } from "./safety/bounds.js";
+export { safeJsonParse, safeJsonParseWithSchema, sanitizeObject } from "./safety/json.js";
+export { confinePath, isPathSafe, sanitizeUri } from "./safety/path.js";

package/dist/core/src/input/context.js

@@ -0,0 +1,69 @@
+import { InputContext } from "./state.js";
+export class InputContextRouter {
+    state;
+    contextMappings = new Map();
+    currentContext = InputContext.Editor;
+    uiInputRouter = null;
+    constructor(state) {
+        this.state = state;
+    }
+    registerContext(ctx, mappings) {
+        this.contextMappings.set(ctx, mappings);
+    }
+    setUIInputRouter(router) {
+        this.uiInputRouter = router;
+        router.setInputState(this.state);
+    }
+    setContext(ctx) {
+        this.currentContext = ctx;
+        this.state.setContext(ctx);
+    }
+    getActiveContext() {
+        if (this.currentContext === InputContext.UI)
+            return InputContext.UI;
+        if (this.currentContext === InputContext.Game)
+            return InputContext.Game;
+        return InputContext.Editor;
+    }
+    isActionDown(action) {
+        const mappings = this.contextMappings.get(this.currentContext);
+        if (!mappings)
+            return false;
+        const codes = mappings.get(action);
+        if (!codes)
+            return false;
+        for (let i = 0; i < codes.length; i++) {
+            if (this.state.isKeyDown(codes[i]))
+                return true;
+        }
+        return false;
+    }
+    wasActionPressed(action) {
+        const mappings = this.contextMappings.get(this.currentContext);
+        if (!mappings)
+            return false;
+        const codes = mappings.get(action);
+        if (!codes)
+            return false;
+        for (let i = 0; i < codes.length; i++) {
+            if (this.state.wasKeyPressed(codes[i]))
+                return true;
+        }
+        return false;
+    }
+    update() {
+        if (this.currentContext === InputContext.UI && this.uiInputRouter) {
+            this.uiInputRouter.update();
+        }
+    }
+    handleKeyDown(code) {
+        if (this.currentContext === InputContext.UI && this.uiInputRouter) {
+            this.uiInputRouter.handleKeyDown(code);
+        }
+    }
+    handleKeyUp(code) {
+        if (this.currentContext === InputContext.UI && this.uiInputRouter) {
+            this.uiInputRouter.handleKeyUp(code);
+        }
+    }
+}

package/dist/core/src/input/dom-handler.js

@@ -0,0 +1,288 @@
+// ============================================================================
+// createDomInputHandler — batteries-included DOM input capture.
+//
+// Every game hand-rolled the same ~100-270-line input handler: window
+// keydown/keyup feeding a keyMap, canvas mousedown + window mouseup for
+// buttons, canvas mousemove → canvas-space coords, wheel accumulation,
+// contextmenu suppression — with no destroy() (leaks on hot reload) and no
+// test-input injection.
+//
+// This factory wires DOM events into the engine's InputState plus a named
+// "held actions" bag (keyMap → action flags like `left`/`jump`), and adds:
+//   - destroy() — removes every listener (hot-reload safe)
+//   - injectInput()/clearInjectedInput() — MCP test input (satisfies the
+//     StandardInputInjector surface used by createStandardAutomationTools)
+//   - update() — per-frame drain for injected frames (call once per frame)
+//
+// Usage:
+//   const input = createDomInputHandler({
+//     canvas,
+//     preset: "wasd",                      // a/d/w/s/arrows/space → left/right/up/down/jump
+//     keys: { "e": "use", "code:KeyQ": "drop" },
+//     onKeyPress: { "F6": () => toggleInspect() },
+//     mouseCoords: "css",
+//   });
+//   // per frame:
+//   input.update();
+//   if (input.held.left) ...
+//   if (input.state.wheelDelta) zoom *= ...
+//   input.state.endFrame();               // clears edge sets + deltas
+//   // on hot-reload:
+//   input.destroy();
+// ============================================================================
+import { InputState } from "./state.js";
+/** Standard WASD+arrows+Space preset: e.key → action name. */
+const WASD_PRESET = {
+    a: "left", A: "left", ArrowLeft: "left",
+    d: "right", D: "right", ArrowRight: "right",
+    w: "up", W: "up", ArrowUp: "up",
+    s: "down", S: "down", ArrowDown: "down",
+    " ": "jump", Space: "jump", Spacebar: "jump",
+};
+export function createDomInputHandler(opts) {
+    const { canvas } = opts;
+    const state = new InputState();
+    const held = {};
+    const injected = [];
+    // ── Key map: e.key → action, plus "code:" entries keyed on e.code ──
+    const keyMap = {
+        ...(opts.preset === "wasd" ? WASD_PRESET : {}),
+        ...opts.keys,
+    };
+    const preventKeys = opts.preventDefaultKeys ?? true;
+    const recomputeHeld = (action) => {
+        // An action is held if any mapped key is currently down. We track key
+        // strings (not codes) for the held bag since the map is e.key-based.
+        held[action] = downKeyStringsFor(action).size > 0;
+    };
+    // Track which physical key-strings are down per action.
+    const downKeysByAction = new Map();
+    const downKeyStringsFor = (action) => {
+        let s = downKeysByAction.get(action);
+        if (!s) {
+            s = new Set();
+            downKeysByAction.set(action, s);
+        }
+        return s;
+    };
+    const lookupAction = (e) => {
+        const byCode = keyMap[`code:${e.code}`];
+        if (byCode)
+            return { mapKey: `code:${e.code}`, action: byCode };
+        const byKey = keyMap[e.key];
+        if (byKey)
+            return { mapKey: e.key, action: byKey };
+        return null;
+    };
+    // Track physically-held keys/buttons so injected-frame expiry only releases
+    // inputs that aren't also held by the real user.
+    const physKeys = new Set();
+    const physButtons = new Set();
+    // Live-frame contribution counts for injected keys/actions/buttons — a
+    // contribution is released when no live frame still holds it.
+    const injectedKeys = new Map();
+    const injectedActions = new Map();
+    const injectedButtons = new Map();
+    const liveFrames = new Set();
+    const releaseFrame = (f) => {
+        // oxlint-disable-next-line downdraft/no-for-of -- iterates Iterable<number>; for..of required
+        for (const code of f.keys ?? []) {
+            const n = (injectedKeys.get(code) ?? 1) - 1;
+            if (n > 0)
+                injectedKeys.set(code, n);
+            else {
+                injectedKeys.delete(code);
+                if (!physKeys.has(code))
+                    state.keyUp(code);
+            }
+        }
+        // oxlint-disable-next-line downdraft/no-for-of -- iterates Iterable<string>; for..of required
+        for (const action of f.actions ?? []) {
+            const n = (injectedActions.get(action) ?? 1) - 1;
+            if (n > 0)
+                injectedActions.set(action, n);
+            else {
+                injectedActions.delete(action);
+                recomputeHeld(action);
+            }
+        }
+        const buttons = [f.leftMouse ? 0 : -1, f.middleMouse ? 1 : -1, f.rightMouse ? 2 : -1];
+        for (let _i = 0, _it = buttons, _n = _it.length; _i < _n; _i++) {
+            const button = _it[_i];
+            if (button < 0)
+                continue;
+            const n = (injectedButtons.get(button) ?? 1) - 1;
+            if (n > 0)
+                injectedButtons.set(button, n);
+            else {
+                injectedButtons.delete(button);
+                if (!physButtons.has(button))
+                    state.mouseUp(button);
+            }
+        }
+    };
+    const onKeyDown = (e) => {
+        const code = e.keyCode || 0;
+        state.keyDown(code);
+        physKeys.add(code);
+        const hit = lookupAction(e);
+        if (hit) {
+            downKeyStringsFor(hit.action).add(hit.mapKey);
+            held[hit.action] = true;
+            if (preventKeys)
+                e.preventDefault();
+        }
+        opts.onKeyPress?.[e.key]?.(e, handler);
+        opts.onKeyPress?.[`code:${e.code}`]?.(e, handler);
+        opts.onKeyDown?.(e, handler);
+    };
+    const onKeyUp = (e) => {
+        const code = e.keyCode || 0;
+        state.keyUp(code);
+        physKeys.delete(code);
+        const hit = lookupAction(e);
+        if (hit) {
+            downKeysByAction.get(hit.action)?.delete(hit.mapKey);
+            recomputeHeld(hit.action);
+            if (preventKeys)
+                e.preventDefault();
+        }
+        opts.onKeyUp?.(e, handler);
+    };
+    // ── Mouse ──
+    const coordScale = opts.mouseCoords === "canvas";
+    const toCanvasCoords = (e) => {
+        const rect = canvas.getBoundingClientRect();
+        const x = e.clientX - rect.left;
+        const y = e.clientY - rect.top;
+        if (!coordScale)
+            return { x, y };
+        return {
+            x: x * (canvas.width / rect.width),
+            y: y * (canvas.height / rect.height),
+        };
+    };
+    const insideCanvas = (e) => {
+        const rect = canvas.getBoundingClientRect();
+        return e.clientX >= rect.left && e.clientX <= rect.right &&
+            e.clientY >= rect.top && e.clientY <= rect.bottom;
+    };
+    const handler = {
+        state,
+        held,
+        mouseValid: false,
+        isDown: (action) => held[action] === true,
+        injectInput(frame) {
+            injected.push(frame);
+        },
+        clearInjectedInput() {
+            injected.forEach((f) => { releaseFrame(f); ; });
+            injected.length = 0;
+            liveFrames.clear();
+        },
+        update() {
+            for (let i = injected.length - 1; i >= 0; i--) {
+                const f = injected[i];
+                if (!liveFrames.has(f)) {
+                    liveFrames.add(f);
+                    // oxlint-disable-next-line downdraft/no-for-of -- iterates Iterable<number>; for..of required
+                    for (const code of f.keys ?? [])
+                        injectedKeys.set(code, (injectedKeys.get(code) ?? 0) + 1);
+                    // oxlint-disable-next-line downdraft/no-for-of -- iterates Iterable<string>; for..of required
+                    for (const action of f.actions ?? [])
+                        injectedActions.set(action, (injectedActions.get(action) ?? 0) + 1);
+                    if (f.leftMouse)
+                        injectedButtons.set(0, (injectedButtons.get(0) ?? 0) + 1);
+                    if (f.middleMouse)
+                        injectedButtons.set(1, (injectedButtons.get(1) ?? 0) + 1);
+                    if (f.rightMouse)
+                        injectedButtons.set(2, (injectedButtons.get(2) ?? 0) + 1);
+                }
+                // oxlint-disable-next-line downdraft/no-for-of -- iterates Iterable<number>; for..of required
+                for (const code of f.keys ?? [])
+                    state.keyDown(code);
+                // oxlint-disable-next-line downdraft/no-for-of -- iterates Iterable<string>; for..of required
+                for (const action of f.actions ?? [])
+                    held[action] = true;
+                if (f.leftMouse)
+                    state.mouseDown(0);
+                if (f.middleMouse)
+                    state.mouseDown(1);
+                if (f.rightMouse)
+                    state.mouseDown(2);
+                if (f.mouseDx || f.mouseDy) {
+                    state.mouseDeltaX += f.mouseDx ?? 0;
+                    state.mouseDeltaY += f.mouseDy ?? 0;
+                }
+                if (f.wheel)
+                    state.wheel(f.wheel);
+                f.framesRemaining--;
+                if (f.framesRemaining <= 0) {
+                    injected.splice(i, 1);
+                    liveFrames.delete(f);
+                    releaseFrame(f);
+                }
+            }
+        },
+        destroy() {
+            window.removeEventListener("keydown", onKeyDown);
+            window.removeEventListener("keyup", onKeyUp);
+            canvas.removeEventListener("mousedown", onMouseDown);
+            (opts.windowMouseUp ?? true ? window : canvas).removeEventListener("mouseup", onMouseUp);
+            (opts.windowMouseMove ? window : canvas).removeEventListener("mousemove", onMouseMove);
+            canvas.removeEventListener("contextmenu", onContextMenu);
+            canvas.removeEventListener("auxclick", onPrevent);
+            canvas.removeEventListener("wheel", onWheel);
+            injected.length = 0;
+        },
+    };
+    const onMouseDown = (e) => {
+        const pos = toCanvasCoords(e);
+        state.mouseMove(pos.x, pos.y, 0, 0);
+        state.mouseDown(e.button);
+        physButtons.add(e.button);
+        opts.onMouseDown?.(e, pos, handler);
+    };
+    const onMouseUp = (e) => {
+        state.mouseUp(e.button);
+        physButtons.delete(e.button);
+        opts.onMouseUp?.(e, handler);
+    };
+    const onMouseMove = (e) => {
+        const pos = toCanvasCoords(e);
+        state.mouseMove(pos.x, pos.y, e.movementX ?? 0, e.movementY ?? 0);
+        handler.mouseValid = insideCanvas(e);
+        opts.onMouseMove?.(e, pos, handler);
+    };
+    const onContextMenu = (e) => e.preventDefault();
+    const onPrevent = (e) => e.preventDefault();
+    const onWheel = (e) => {
+        e.preventDefault();
+        // Normalize to integer notches (scroll up = +1 = zoom in, matching the
+        // per-game convention).
+        state.wheel(e.deltaY < 0 ? 1 : e.deltaY > 0 ? -1 : 0);
+        opts.onWheel?.(e, handler);
+    };
+    // ── Wire listeners ──
+    window.addEventListener("keydown", onKeyDown);
+    window.addEventListener("keyup", onKeyUp);
+    canvas.addEventListener("mousedown", onMouseDown);
+    (opts.windowMouseUp ?? true ? window : canvas).addEventListener("mouseup", onMouseUp);
+    (opts.windowMouseMove ? window : canvas).addEventListener("mousemove", onMouseMove);
+    if (opts.suppressContextMenu ?? true) {
+        canvas.addEventListener("contextmenu", onContextMenu);
+        canvas.addEventListener("auxclick", onPrevent);
+    }
+    if (opts.wheel ?? true) {
+        canvas.addEventListener("wheel", onWheel, { passive: false });
+    }
+    // Initialize mouse to canvas center so a click before the first mousemove
+    // targets the middle of the view (where the player usually is) instead of
+    // the top-left corner.
+    if (opts.centerInitialMouse ?? true) {
+        const rect = canvas.getBoundingClientRect();
+        state.mouseX = coordScale ? canvas.width / 2 : rect.width / 2;
+        state.mouseY = coordScale ? canvas.height / 2 : rect.height / 2;
+    }
+    return handler;
+}