@woosh/meep-engine 2.164.0 → 2.165.0

package/src/engine/graphics/sh3/lightmap/prototypeLightmapBaker.js

@@ -0,0 +1,186 @@
+import { BoxBufferGeometry, MeshStandardMaterial, SphereBufferGeometry } from "three";
+import Quaternion from "../../../../core/geom/Quaternion.js";
+import Vector3 from "../../../../core/geom/Vector3.js";
+import Tag from "../../../ecs/components/Tag.js";
+import Entity from "../../../ecs/Entity.js";
+import { Transform } from "../../../ecs/transform/Transform.js";
+import { EngineHarness } from "../../../EngineHarness.js";
+import { Light } from "../../ecs/light/Light.js";
+import LightSystem from "../../ecs/light/LightSystem.js";
+import { ShadedGeometry } from "../../ecs/mesh-v2/ShadedGeometry.js";
+import { ShadedGeometryFlags } from "../../ecs/mesh-v2/ShadedGeometryFlags.js";
+import { ShadedGeometrySystem } from "../../ecs/mesh-v2/ShadedGeometrySystem.js";
+import { bake_lightmap_for_scene } from "./bake_lightmap_for_scene.js";
+
+const harness = new EngineHarness();
+
+/**
+ * Add one coloured {@link ShadedGeometry} entity to the scene.
+ *
+ * @param {EntityComponentDataset} ecd
+ * @param {THREE.BufferGeometry} geometry
+ * @param {number} color hex colour
+ * @param {Vector3} position
+ * @param {Quaternion} [rotation]
+ */
+function spawn(ecd, geometry, color, position, rotation) {
+    const material = new MeshStandardMaterial({ color, roughness: 1, metalness: 0 });
+
+    const sg = ShadedGeometry.from(geometry, material);
+    sg.setFlag(ShadedGeometryFlags.CastShadow);
+    sg.setFlag(ShadedGeometryFlags.ReceiveShadow);
+    sg.setFlag(ShadedGeometryFlags.Visible);
+
+    const transform = new Transform();
+    transform.position.copy(position);
+    if (rotation !== undefined) {
+        transform.rotation.copy(rotation);
+    }
+
+    new Entity()
+        .add(sg)
+        .add(transform)
+        .add(Tag.fromJSON(["LightmapTarget"]))
+        .build(ecd);
+}
+
+/**
+ * Add a coloured light. DIRECTION lights bake crisp shadows; POINT lights add
+ * coloured bounce. Both are read by the path-traced bake.
+ *
+ * @param {EntityComponentDataset} ecd
+ * @param {number} type one of {@link Light.Type}
+ * @param {number[]} color linear [r, g, b] in 0..1
+ * @param {number} intensity
+ * @param {Object} placement
+ * @param {Vector3} [placement.position]
+ * @param {Vector3} [placement.direction]
+ * @param {number} [placement.distance] point-light influence radius
+ */
+function spawn_light(ecd, type, color, intensity, { position, direction, distance = 30 }) {
+    const light = new Light();
+    light.type.set(type);
+    light.color.setRGB(color[0], color[1], color[2]);
+    light.intensity.set(intensity);
+    light.distance.set(distance);
+    light.castShadow.set(true);
+
+    const transform = new Transform();
+    if (position !== undefined) {
+        transform.position.copy(position);
+    }
+    if (direction !== undefined) {
+        transform.rotation.lookRotation(direction.clone().normalize());
+    }
+
+    new Entity()
+        .add(light)
+        .add(transform)
+        .add(Tag.fromJSON(["Light"]))
+        .build(ecd);
+}
+
+/**
+ * @param {Engine} engine
+ */
+async function main(engine) {
+    const em = engine.entityManager;
+
+    await em.addSystem(new ShadedGeometrySystem(engine));
+    await em.addSystem(new LightSystem(engine, { shadowResolution: 2048 }));
+
+    // camera + orbital/keyboard controls; no terrain (we build our own platform),
+    // no engine lights (we place our own so we can dim them after the bake)
+    await EngineHarness.buildBasics({
+        engine,
+        focus: new Vector3(0, 1.5, 0),
+        pitch: 0.95,
+        yaw: 0.6,
+        distance: 18,
+        enableTerrain: false,
+        enableWater: false,
+        enableLights: false,
+        cameraController: true,
+        showFps: true,
+    });
+
+    const ecd = em.dataset;
+
+    // --- platform ---
+    spawn(ecd, new BoxBufferGeometry(16, 1, 16), 0xA1A1A1, new Vector3(0, -0.5, 0));
+
+    // --- a few shapes ---
+    spawn(ecd, new BoxBufferGeometry(2, 2, 2), 0xe23b3b, new Vector3(-4, 1, -2));
+    spawn(ecd, new BoxBufferGeometry(2, 4, 2), 0x3bd16f, new Vector3(3.5, 2, 2));
+    spawn(ecd, new SphereBufferGeometry(1.5, 32, 24), 0x4f86ff, new Vector3(0, 1.5, 3.5));
+    spawn(
+        ecd,
+        new BoxBufferGeometry(2.5, 2.5, 2.5),
+        0xf0c020,
+        new Vector3(2.5, 1.25, -3.5),
+        Quaternion.fromEulerAngles(0, Math.PI / 5, 0)
+    );
+
+    // --- lights (baked) ---
+    spawn_light(ecd, Light.Type.DIRECTION, [1.0, 0.95, 0.88], 1.6, { direction: new Vector3(-0.6, -1, -0.35) });
+    spawn_light(ecd, Light.Type.POINT, [1.0, 0.3, 0.18], 1, { position: new Vector3(-4, 2.5, 4), distance: 16 });
+    spawn_light(ecd, Light.Type.POINT, [0.18, 0.42, 1.0], 1, { position: new Vector3(5, 3, -5), distance: 16 });
+
+    const status = make_status_overlay();
+
+    // give the ECS one frame to settle transforms before baking
+    requestAnimationFrame(() => {
+        const group = bake_lightmap_for_scene({
+            ecd,
+            lightmap_resolution: 1024,
+            samples_per_texel: 1024,
+            min_bounce: 1,
+            max_bounce: 4,
+            padding: 2,
+        });
+
+        // expose for console poking
+        window.lightmap_bake = group;
+
+        // engine.executor.runGroup(group);
+
+        // progress readout
+        function poll() {
+            const p = group.computeProgress();
+            status.textContent = `Baking lightmap… ${(p * 100).toFixed(1)}%`;
+            if (p < 1) {
+                requestAnimationFrame(poll);
+            }
+        }
+
+        poll();
+    });
+}
+
+/**
+ * @returns {HTMLDivElement}
+ */
+function make_status_overlay() {
+    const el = document.createElement("div");
+    el.style.position = "fixed";
+    el.style.left = "8px";
+    el.style.top = "8px";
+    el.style.zIndex = "1000";
+    el.style.padding = "6px 10px";
+    el.style.font = "13px monospace";
+    el.style.color = "#fff";
+    el.style.background = "rgba(0,0,0,0.55)";
+    el.style.borderRadius = "4px";
+    el.style.pointerEvents = "none";
+    el.textContent = "Preparing bake…";
+    document.body.appendChild(el);
+    return el;
+}
+
+harness.initialize({
+    configuration(config) {
+
+        // config.addPlugin(AmbientOcclusionPostProcessEffect)
+
+    },
+}).then(main);

package/src/engine/graphics/sh3/path_tracer/PathTracedMesh.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PathTracedMesh.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/sh3/path_tracer/PathTracedMesh.js"],"names":[],"mappings":"AAgBA;IACI;;;OAGG;IACH,IAFU,MAAM,CAEO;IAEvB;;;OAGG;IACH,MAFU,KAAK,CAEI;IAEnB;;;OAGG;IACH,KAFU,sBAAoB,IAAI,CAEvB;IAGX;;;OAGG;IACH,UAFU,MAAM,cAAc,GAAC,IAAI,CAEnB;IAEhB;;;OAGG;IACH,UAFU,mBAAiB,IAAI,CAEf;IAYhB,sCAEC;IAED,kCAEC;IAED,2BAqBC;IAED,sBAGC;IAED,iCAUC;IAED,8BAEC;IAED;;;;OAIG;IACH,cAHW,IAAI,GACF,OAAO,CAWnB;IAED;;;;;;OAMG;IACH,SALW,MAAM,EAAE,OACR,MAAM,EAAE,GAAC,IAAI,aACb,MAAM,GACJ,MAAM,CA4BlB;;CACJ;sBA9JqB,wCAAwC;qBAKzC,sCAAsC"}
+{"version":3,"file":"PathTracedMesh.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/sh3/path_tracer/PathTracedMesh.js"],"names":[],"mappings":"AAgBA;IACI;;;OAGG;IACH,IAFU,MAAM,CAEO;IAEvB;;;OAGG;IACH,MAFU,KAAK,CAEI;IAEnB;;;OAGG;IACH,KAFU,sBAAoB,IAAI,CAEvB;IAGX;;;OAGG;IACH,UAFU,MAAM,cAAc,GAAC,IAAI,CAEnB;IAEhB;;;OAGG;IACH,UAFU,mBAAiB,IAAI,CAEf;IAYhB,sCAEC;IAED,kCAEC;IAED,2BAqBC;IAED,sBAGC;IAED,iCAUC;IAED,8BAEC;IAED;;;;OAIG;IACH,cAHW,IAAI,GACF,OAAO,CAWnB;IAED;;;;;;OAMG;IACH,SALW,MAAM,EAAE,OACR,MAAM,EAAE,GAAC,IAAI,aACb,MAAM,GACJ,MAAM,CA4BlB;;CACJ;sBA/JqB,wCAAwC;qBAMzC,sCAAsC"}

package/src/engine/graphics/sh3/path_tracer/PathTracedMesh.js

@@ -1,10 +1,10 @@
-import { mat4 } from "gl-matrix";
 import { array_copy } from "../../../../core/collection/array/array_copy.js";
 import { AABB3 } from "../../../../core/geom/3d/aabb/AABB3.js";
 import { aabb3_from_v3_array_transformed } from "../../../../core/geom/3d/aabb/aabb3_from_v3_array_transformed.js";
 import { m4_allocate } from "../../../../core/geom/3d/mat4/m4_allocate.js";
 import { m4_decompose } from "../../../../core/geom/3d/mat4/m4_decompose.js";
 import { m4_normal_matrix3 } from "../../../../core/geom/3d/mat4/m4_normal_matrix3.js";
+import { m4_invert } from "../../../../core/geom/3d/mat4/m4_invert.js";
 import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
 import Quaternion from "../../../../core/geom/Quaternion.js";
 import { v3_distance } from "../../../../core/geom/vec3/v3_distance.js";
@@ -95,7 +95,7 @@ export class PathTracedMesh {
     set transform(m) {
         array_copy(m, 0, this.#transform, 0, 16);
 
-        mat4.invert(this.#transform_inverse, m);
+        m4_invert(this.#transform_inverse, m);
 
         m4_normal_matrix3(this.#normal_matrix, this.#transform);
 

package/src/engine/graphics/sh3/path_tracer/PathTracer.js

@@ -1,5 +1,5 @@
-import { vec3 } from "gl-matrix";
 import { array_copy } from "../../../../core/collection/array/array_copy.js";
+import { v3_multiply } from "../../../../core/geom/vec3/v3_multiply.js";
 import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
 import { getBiasedNormalSample } from "./sampling/getBiasedNormalSample.js";
 
@@ -112,7 +112,7 @@ export class PathTracer {
             irradiance[2] += color_mask[2] * tmp_0[8];
 
             // fold the surface albedo into the path throughput
-            vec3.multiply(color_mask, color_mask, tmp_0);
+            v3_multiply(color_mask, 0, color_mask[0], color_mask[1], color_mask[2], tmp_0[0], tmp_0[1], tmp_0[2]);
 
             // construct new ray, aligned on the normal of the contact
             array_copy(tmp_0, 3, _ray_0, 3, 3); // copy surface normal into the direction slot (read by sample_lights)

package/src/engine/graphics/sh3/path_tracer/prepare_scene_gltf.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prepare_scene_gltf.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/sh3/path_tracer/prepare_scene_gltf.js"],"names":[],"mappings":"AAaA;;;;;qBAyBC;AAaD;;;;;;;;;;GAUG;AACH,mHAFY,QAAQ,IAAI,CAAC,CA8CxB;oBAnGmB,kCAAkC;iCAErB,qDAAqD"}
+{"version":3,"file":"prepare_scene_gltf.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/sh3/path_tracer/prepare_scene_gltf.js"],"names":[],"mappings":"AAeA;;;;;qBAyBC;AAaD;;;;;;;;;;GAUG;AACH,mHAFY,QAAQ,IAAI,CAAC,CA8CxB;oBAnGmB,kCAAkC;iCAErB,qDAAqD"}

package/src/engine/graphics/sh3/path_tracer/prepare_scene_gltf.js

@@ -1,9 +1,11 @@
-import { vec3 } from "gl-matrix";
 import { Box3, MeshStandardMaterial, PlaneBufferGeometry, Sphere } from "three";
+import { v3_length } from "../../../../core/geom/vec3/v3_length.js";
+import { v3_scale } from "../../../../core/geom/vec3/v3_scale.js";
 import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
 import { Color } from "../../../../core/color/Color.js";
 import { kelvin_to_rgb } from "../../../../core/color/kelvin/kelvin_to_rgb.js";
 import { noop } from "../../../../core/function/noop.js";
+import { v3_multiply } from "../../../../core/geom/vec3/v3_multiply.js";
 import Quaternion from "../../../../core/geom/Quaternion.js";
 import Vector3 from "../../../../core/geom/Vector3.js";
 import { Transform } from "../../../ecs/transform/Transform.js";
@@ -25,10 +27,10 @@ export function make_sun({
     const light = new DirectionalLight();
 
     light.color.parse(color);
-    vec3.multiply(light.color, light.color, temp_c);
+    v3_multiply(light.color, 0, light.color[0], light.color[1], light.color[2], temp_c[0], temp_c[1], temp_c[2]);
 
-    const n = vec3.length(light.color);
-    vec3.scale(light.color, light.color, 1 / n); // normalize color vector
+    const n = v3_length(light.color[0], light.color[1], light.color[2]);
+    v3_scale(light.color, 0, light.color[0], light.color[1], light.color[2], 1 / n); // normalize color vector
 
     light.intensity.set(intensity * n);
     light.direction.copy(direction);

package/src/engine/graphics/sh3/path_tracer/prototypePathTracer.js

@@ -1,4 +1,4 @@
-import { mat4 } from "gl-matrix";
+import { m4_from_rotation_translation_scale } from "../../../../core/geom/3d/mat4/m4_from_rotation_translation_scale.js";
 import { MeshStandardMaterial, OctahedronBufferGeometry, PerspectiveCamera, PlaneBufferGeometry } from "three";
 import { PLYLoader } from "three/examples/jsm/loaders/PLYLoader.js";
 
@@ -313,7 +313,7 @@ async function prepare_scene_rtiow(pt, camera) {
     function add_sphere(center, radius, material) {
 
         const mat = new Float32Array(16);
-        mat4.fromRotationTranslationScale(mat, [0, 0, 0, 1], center, [radius, radius, radius])
+        m4_from_rotation_translation_scale(mat, [0, 0, 0, 1], center, [radius, radius, radius])
 
         scene.createMesh(sphere_geo, material, mat);
 
@@ -357,7 +357,7 @@ async function prepare_scene_rtiow(pt, camera) {
 
 
             const mat = new Float32Array(16);
-            mat4.fromRotationTranslationScale(mat, [0, 0, 0, 1], center, [radius, radius, radius])
+            m4_from_rotation_translation_scale(mat, [0, 0, 0, 1], center, [radius, radius, radius])
 
             const material = new MeshStandardMaterial({
                 color: Color.fromHSV(random(), 0.9, 0.9).toHex()

package/src/engine/graphics/sh3/path_tracer/texture/sample_material.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sample_material.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/sh3/path_tracer/texture/sample_material.js"],"names":[],"mappings":"AA6CA;;;;;;;GAOG;AACH,qCANW,MAAM,EAAE,sCAER,MAAM,KACN,MAAM,KACN,MAAM,QA4FhB"}
+{"version":3,"file":"sample_material.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/sh3/path_tracer/texture/sample_material.js"],"names":[],"mappings":"AA8CA;;;;;;;GAOG;AACH,qCANW,MAAM,EAAE,sCAER,MAAM,KACN,MAAM,KACN,MAAM,QA4FhB"}

package/src/engine/graphics/sh3/path_tracer/texture/sample_material.js

@@ -1,6 +1,7 @@
-import { vec3 } from "gl-matrix";
 import { compute_binary_data_type_from_typed_array } from "../../../../../core/collection/array/typed/compute_binary_data_type_from_typed_array.js";
 import { v3_distance_sqr } from "../../../../../core/geom/vec3/v3_distance_sqr.js";
+import { v3_multiply } from "../../../../../core/geom/vec3/v3_multiply.js";
+import { v3_normalize_array } from "../../../../../core/geom/vec3/v3_normalize_array.js";
 import { v3_matrix3_rotate } from "../../../../../core/geom/vec3/v3_matrix3_rotate.js";
 import { decode_attribute_value } from "../../../geometry/decode_attribute_value.js";
 import { geometry_construct_triangle_normal } from "../../../geometry/geometry_construct_triangle_normal.js";
@@ -111,7 +112,7 @@ export function sample_material(
         normal[1] = normal[1] * 2 - 1;
         normal[2] = normal[2] * 2 - 1;
 
-        vec3.normalize(normal, normal);
+        v3_normalize_array(normal, 0, normal, 0);
 
         // needs transform
         v3_orthonormal_matrix_from_normal(scratch_m3, 0, out[3], out[4], out[5]);
@@ -126,13 +127,13 @@ export function sample_material(
     if (color_attribute !== undefined) {
         sample_color_attribute(color, color_attribute, index_0, index_1, index_2, u, v);
 
-        vec3.multiply(out, out, color);
+        v3_multiply(out, 0, out[0], out[1], out[2], color[0], color[1], color[2]);
     }
 
 
     material.diffuse.sample(color, texture_uv[0], texture_uv[1]);
 
-    vec3.multiply(out, out, color);
+    v3_multiply(out, 0, out[0], out[1], out[2], color[0], color[1], color[2]);
 
     // emissive radiance emitted by this surface
     material.emissive.sample(emissive, texture_uv[0], texture_uv[1]);

package/src/engine/graphics/sh3/sky/hosek/prototype_hosek.js

@@ -1,4 +1,4 @@
-import { vec3 } from "gl-matrix";
+import { v3_normalize_array } from "../../../../../core/geom/vec3/v3_normalize_array.js";
 import { CanvasView } from "../../../../../view/elements/CanvasView.js";
 import { Sampler2D } from "../../../texture/sampler/Sampler2D.js";
 import sampler2D2Canvas from "../../../texture/sampler/sampler2d_to_html_canvas.js";
@@ -52,7 +52,7 @@ for (let i = 0; i < sampler.width; i++) {
 
         const direction = [v_x, v_z, v_y];
 
-        vec3.normalize(direction, direction);
+        v3_normalize_array(direction, 0, direction, 0);
 
         sky(color, 0, direction, 0);
 

package/src/engine/input/devices/KeyboardDevice.d.ts

@@ -1,14 +1,61 @@
-import {InputDeviceSwitch} from "./InputDeviceSwitch";
-import Signal from "../../../core/events/signal/Signal";
-
-export default class KeyboardDevice {
-    constructor(domElement:EventTarget|Element)
-
-    readonly on: {up:Signal,down:Signal}
-
-    readonly keys:{[key:string]:InputDeviceSwitch}
-
-    start():void
-
-    stop():void
-}
+export default KeyboardDevice;
+/**
+ * Provides keyboard input.
+ * Listens for key events on a DOM element and provides signals and state for key presses.
+ * NOTE: if the bound element loses focus within the page (e.g. you hold "A" and click on some other element),
+ * the key remains pressed and the eventual physical release is picked up at the window level.
+ * NOTE: when the window itself loses focus (e.g. switching to another application), key releases can no longer
+ * be observed at all, so any "pressed" keys are forcibly released with the appropriate signal.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+declare class KeyboardDevice {
+    /**
+     * @param {EventTarget|Element} domElement The DOM element to listen for keyboard events on.  This element *must* be focusable (e.g., have a `tabindex` attribute).
+     * @throws {TypeError} If the provided `domElement` is not focusable and doesn't have a `tabindex` attribute.
+     */
+    constructor(domElement: EventTarget | Element);
+    /**
+     * @readonly
+     */
+    readonly on: {
+        /**
+         * Fires when any key is pressed
+         * @type {Signal<KeyboardEvent>}
+         */
+        down: Signal<KeyboardEvent>;
+        /**
+         * Fires when any key is released
+         * @type {Signal<KeyboardEvent>}
+         */
+        up: Signal<KeyboardEvent>;
+    };
+    /**
+     * See {@link KeyCodes} for valid IDs
+     * @readonly
+     * @type {Object<InputDeviceSwitch>}
+     *
+     * @example
+     *   const is_enter_pressed = keyboard.keys.enter.is_down;
+     */
+    readonly keys: any;
+    /**
+     * The DOM element being listened to.
+     * @type {EventTarget}
+     */
+    domElement: EventTarget;
+    /**
+     * Starts listening for keyboard events on the associated DOM element.
+     * @returns {void}
+     */
+    start(): void;
+    /**
+     * Stops listening for keyboard events.
+     * @returns {void}
+     */
+    stop(): void;
+    #private;
+}
+import Signal from "../../../core/events/signal/Signal.js";
+//# sourceMappingURL=KeyboardDevice.d.ts.map

package/src/engine/input/devices/KeyboardDevice.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"KeyboardDevice.d.ts","sourceRoot":"","sources":["../../../../../src/engine/input/devices/KeyboardDevice.js"],"names":[],"mappings":";AAYA;;;;;;;;GAQG;AACH;IA4BI;;;OAGG;IACH,wBAHW,WAAW,GAAC,OAAO,EAgC7B;IA3DD;;OAEG;IACH;QACI;;;WAGG;cADO,OAAO,aAAa,CAAC;QAG/B;;;WAGG;YADO,OAAO,aAAa,CAAC;MAGjC;IAEF;;;;;;;OAOG;IACH,mBAAU;IAkBN;;;OAGG;IACH,YAFU,WAAW,CAEO;IA8FhC;;;OAGG;IACH,SAFa,IAAI,CAahB;IAED;;;OAGG;IACH,QAFa,IAAI,CAahB;;CAEJ;mBArMkB,uCAAuC"}
+{"version":3,"file":"KeyboardDevice.d.ts","sourceRoot":"","sources":["../../../../../src/engine/input/devices/KeyboardDevice.js"],"names":[],"mappings":";AAYA;;;;;;;;;;GAUG;AACH;IA4BI;;;OAGG;IACH,wBAHW,WAAW,GAAC,OAAO,EAgC7B;IA3DD;;OAEG;IACH;QACI;;;WAGG;cADO,OAAO,aAAa,CAAC;QAG/B;;;WAGG;YADO,OAAO,aAAa,CAAC;MAGjC;IAEF;;;;;;;OAOG;IACH,mBAAU;IAkBN;;;OAGG;IACH,YAFU,WAAW,CAEO;IA2HhC;;;OAGG;IACH,SAFa,IAAI,CAWhB;IAED;;;OAGG;IACH,QAFa,IAAI,CAUhB;;CAEJ;mBA/NkB,uCAAuC"}

package/src/engine/input/devices/KeyboardDevice.js

@@ -13,8 +13,10 @@ const codeToKeyNameMap = [];
 /**
  * Provides keyboard input.
  * Listens for key events on a DOM element and provides signals and state for key presses.
- * NOTE: when losing focus of the application, any "pressed" keys will be automatically released.
- * For example, if you hold "A" and click over into another application window - A will be forcibly released with appropriate signal.
+ * NOTE: if the bound element loses focus within the page (e.g. you hold "A" and click on some other element),
+ * the key remains pressed and the eventual physical release is picked up at the window level.
+ * NOTE: when the window itself loses focus (e.g. switching to another application), key releases can no longer
+ * be observed at all, so any "pressed" keys are forcibly released with the appropriate signal.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -60,7 +62,7 @@ class KeyboardDevice {
             !isHTMLElementFocusable(domElement)
             && domElement.getAttribute('tabindex') === null
         ) {
-            new TypeError('Supplied element is not inherently focusable and does not have tabindex attribute, so it must have a tabindex attribute in order to be able receive keyboard events. Something like tabindex=0 would suffice.');
+            throw new TypeError('Supplied element is not inherently focusable and does not have tabindex attribute, so it must have a tabindex attribute in order to be able receive keyboard events. Something like tabindex=0 would suffice.');
         }
 
         /**
@@ -149,12 +151,41 @@ class KeyboardDevice {
 
     }
 
+    /**
+     * Recovery handler for key releases that happen while the bound element does not have focus.
+     * Covers the scenario where a key is pressed on the element, focus is then lost to another
+     * element in the page (e.g. via a mouse click), and only then is the physical key released.
+     * Registered on window in the bubble phase, so for keys released while the element still has
+     * focus the element-scoped handler runs first and this one sees the key as already released.
+     *
+     * @param {KeyboardEvent} event
+     */
+    #handlerWindowKeyUp = (event) => {
+        const keyName = codeToKeyNameMap[event.keyCode];
+
+        if (keyName === undefined) {
+            return;
+        }
+
+        const button = this.keys[keyName];
+
+        if (button.is_up) {
+            // key is not tracked as pressed; either it was never pressed via this device,
+            // or the element-scoped handler has already processed this release
+            return;
+        }
+
+        this.on.up.send1(event);
+
+        button.release();
+    }
+
     /**
      *
      * @param {FocusEvent} event
      */
-    #handleGlobalBlurEvent = (event) => {
-        // Element lost focus, we won't be able to capture key-up events
+    #handleWindowBlurEvent = (event) => {
+        // Window lost focus, we won't be able to capture key-up events
         // release all keys
         for (let keyName in KeyCodes) {
             this.keys[keyName].release();
@@ -170,12 +201,10 @@ class KeyboardDevice {
         el.addEventListener(KeyboardEvents.KeyDown, this.#handlerKeyDown);
         el.addEventListener(KeyboardEvents.KeyUp, this.#handlerKeyUp);
 
-        el.addEventListener('blur', this.#handleGlobalBlurEvent);
+        // catch releases of tracked keys that happen after the element lost focus within the page
+        window.addEventListener(KeyboardEvents.KeyUp, this.#handlerWindowKeyUp);
 
-        //https://w3c.github.io/uievents/#event-type-focusout
-        el.addEventListener('focusout', this.#handleGlobalBlurEvent);
-
-        window.addEventListener('blur', this.#handleGlobalBlurEvent);
+        window.addEventListener('blur', this.#handleWindowBlurEvent);
     }
 
     /**
@@ -187,12 +216,9 @@ class KeyboardDevice {
         el.removeEventListener(KeyboardEvents.KeyDown, this.#handlerKeyDown);
         el.removeEventListener(KeyboardEvents.KeyUp, this.#handlerKeyUp);
 
-        el.removeEventListener('blur', this.#handleGlobalBlurEvent);
-
-        //https://w3c.github.io/uievents/#event-type-focusout
-        el.removeEventListener('focusout', this.#handleGlobalBlurEvent);
+        window.removeEventListener(KeyboardEvents.KeyUp, this.#handlerWindowKeyUp);
 
-        window.removeEventListener('blur', this.#handleGlobalBlurEvent);
+        window.removeEventListener('blur', this.#handleWindowBlurEvent);
     }
 
 }

package/src/engine/input/devices/isHTMLElementFocusable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"isHTMLElementFocusable.d.ts","sourceRoot":"","sources":["../../../../../src/engine/input/devices/isHTMLElementFocusable.js"],"names":[],"mappings":"AAsBA;;;GAGG;AACH,2CAFW,OAAO,WASjB"}
+{"version":3,"file":"isHTMLElementFocusable.d.ts","sourceRoot":"","sources":["../../../../../src/engine/input/devices/isHTMLElementFocusable.js"],"names":[],"mappings":"AAeA;;;GAGG;AACH,2CAFW,OAAO,WASjB"}

package/src/engine/input/devices/isHTMLElementFocusable.js

@@ -5,17 +5,10 @@
  * @returns {boolean}
  */
 function isInstanceOf(thing, klass) {
-    if (klass === undefined) {
+    // constructors are functions; the check also guards against the class being absent in the environment
+    if (typeof klass !== "function") {
         return false;
     }
-    if (klass === null) {
-        return false;
-    }
-
-    if (typeof klass !== "object") {
-        return false;
-    }
-
 
     return thing instanceof klass;
 }