@woosh/meep-engine 2.163.11 → 2.165.0

package/src/engine/graphics/trail/tube/TubeXPlugin.js

@@ -0,0 +1,80 @@
+import { Cache } from "../../../../core/cache/Cache.js";
+import { invokeObjectEquals } from "../../../../core/model/object/invokeObjectEquals.js";
+import { invokeObjectHash } from "../../../../core/model/object/invokeObjectHash.js";
+import { GameAssetType } from "../../../asset/GameAssetType.js";
+import { EnginePlugin } from "../../../plugin/EnginePlugin.js";
+import { TubeMaterialX } from "./TubeMaterialX.js";
+
+/**
+ * Shares and caches {@link TubeMaterialX} instances across all {@link Trail3D}
+ * tubes. Mirrors {@link RibbonXPlugin} but needs no screen-resolution uniform,
+ * since the tube extrudes in world space rather than screen space.
+ *
+ * Acquired lazily by {@link Trail3DSystem} via `engine.plugins.acquire`; it does
+ * not need explicit registration.
+ */
+export class TubeXPlugin extends EnginePlugin {
+
+    /**
+     * @type {Cache<TubeXMaterialSpec, TubeMaterialX>}
+     */
+    #materialCache = null;
+
+    initialize(engine) {
+        super.initialize(engine);
+
+        this.id = 'tube-x-plugin';
+
+        this.#materialCache = new Cache({
+            maxWeight: 128,
+
+            keyHashFunction: invokeObjectHash,
+            keyEqualityFunction: invokeObjectEquals
+        });
+    }
+
+    /**
+     * @param {TubeXMaterialSpec} spec
+     * @returns {TubeMaterialX}
+     */
+    obtain_material_x(spec) {
+        return this.#materialCache.getOrCompute(spec, this.#build_material, this);
+    }
+
+    /**
+     * @param {TubeXMaterialSpec} spec
+     * @returns {TubeMaterialX}
+     */
+    #build_material(spec) {
+
+        const material = new TubeMaterialX({
+            transparent: true,
+            depthWrite: spec.depthWrite,
+            wireframe: false
+        });
+
+        if (typeof spec.diffuse === "string") {
+            const am = this.engine.assetManager;
+
+            am.get({
+                path: spec.diffuse,
+                type: GameAssetType.Texture,
+                callback: (asset) => {
+                    /**
+                     * @type {Texture}
+                     */
+                    const texture = asset.create();
+
+                    texture.generateMipmaps = true;
+
+                    material.uniforms.uDiffuse.value = texture;
+                }, failure: console.warn
+            });
+
+            material.defines.USE_TEXTURE = true;
+            material.needsUpdate = true;
+        }
+
+        return material;
+    }
+}

package/src/engine/graphics/trail/tube/simulator/TubeXFixedPhysicsSimulator.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Fixed-function simulation for {@link TubeX} tubes — the 3D analogue of
+ * {@link RibbonXFixedPhysicsSimulator}. Ages every knot, fades its alpha to zero
+ * as it approaches `max_age`, and flows the along-tube UV coordinate with age.
+ */
+export class TubeXFixedPhysicsSimulator {
+    /**
+     * @param {TubeX} tube
+     * @param {number} max_age
+     * @param {number} timeDelta
+     */
+    update(tube: TubeX, max_age: number, timeDelta: number): void;
+}
+//# sourceMappingURL=TubeXFixedPhysicsSimulator.d.ts.map

package/src/engine/graphics/trail/tube/simulator/TubeXFixedPhysicsSimulator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TubeXFixedPhysicsSimulator.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/graphics/trail/tube/simulator/TubeXFixedPhysicsSimulator.js"],"names":[],"mappings":"AAGA;;;;GAIG;AACH;IAEI;;;;OAIG;IACH,6BAHW,MAAM,aACN,MAAM,QAiBhB;CACJ"}

package/src/engine/graphics/trail/tube/simulator/TubeXFixedPhysicsSimulator.js

@@ -0,0 +1,32 @@
+import { clamp01 } from "../../../../../core/math/clamp01.js";
+import { TUBE_ATTRIBUTE_ADDRESS_AGE, TUBE_ATTRIBUTE_ADDRESS_UV_V } from "../tube_attributes_spec.js";
+
+/**
+ * Fixed-function simulation for {@link TubeX} tubes — the 3D analogue of
+ * {@link RibbonXFixedPhysicsSimulator}. Ages every knot, fades its alpha to zero
+ * as it approaches `max_age`, and flows the along-tube UV coordinate with age.
+ */
+export class TubeXFixedPhysicsSimulator {
+
+    /**
+     * @param {TubeX} tube
+     * @param {number} max_age
+     * @param {number} timeDelta
+     */
+    update(tube, max_age, timeDelta) {
+
+        const n = tube.getCount();
+
+        for (let i = 0; i < n; i++) {
+            const age = tube.incrementKnotAttribute_Scalar(i, TUBE_ATTRIBUTE_ADDRESS_AGE, timeDelta);
+
+            const relative_age = clamp01(age / max_age);
+
+            // fade out with age
+            tube.setKnotAlpha(i, 1.0 - relative_age);
+
+            // flow the along-tube UV with age
+            tube.setKnotAttribute_Scalar(i, TUBE_ATTRIBUTE_ADDRESS_UV_V, relative_age);
+        }
+    }
+}

package/src/engine/graphics/trail/tube/tube_attributes_spec.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Per-vertex attribute layout for a {@link TubeX}.
+ *
+ * Unlike {@link RibbonX} (which extrudes in screen space and therefore stores
+ * the neighbouring positions to derive a 2D normal), the tube extrudes in WORLD
+ * space inside the vertex shader using a per-knot tangent frame. Every vertex of
+ * a knot's ring shares the same centre/frame/colour/etc and differs only by `off`
+ * (its angular position around the ring), so the heavy per-frame work is just
+ * writing the knot centre + frame to the ring's `radial+1` rows.
+ *
+ * Layout is floats-first then a uint8 colour triple, padded to a 4-byte multiple
+ * so the interleaved Float32 view (stride = bytesPerRecord >> 2) stays aligned —
+ * the same trick {@link ribbon_attributes_spec} relies on.
+ */
+export const tube_attributes_spec: RowFirstTableSpec;
+export const TUBE_ATTRIBUTE_ADDRESS_AGE: 0;
+export const TUBE_ATTRIBUTE_ADDRESS_POSITION: 1;
+export const TUBE_ATTRIBUTE_ADDRESS_NORMAL: 4;
+export const TUBE_ATTRIBUTE_ADDRESS_BINORMAL: 7;
+export const TUBE_ATTRIBUTE_ADDRESS_OFF: 10;
+export const TUBE_ATTRIBUTE_ADDRESS_UV_V: 11;
+export const TUBE_ATTRIBUTE_ADDRESS_ALPHA: 12;
+export const TUBE_ATTRIBUTE_ADDRESS_THICKNESS: 13;
+export const TUBE_ATTRIBUTE_ADDRESS_COLOR: 14;
+import { RowFirstTableSpec } from "../../../../core/collection/table/RowFirstTableSpec.js";
+//# sourceMappingURL=tube_attributes_spec.d.ts.map

package/src/engine/graphics/trail/tube/tube_attributes_spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tube_attributes_spec.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/trail/tube/tube_attributes_spec.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AACH,qDAuC4B;AAG5B,2CAA4C;AAC5C,gDAAiD;AACjD,8CAA+C;AAC/C,gDAAiD;AACjD,4CAA6C;AAC7C,6CAA8C;AAC9C,8CAA+C;AAC/C,kDAAmD;AACnD,8CAA+C;kCAlEb,wDAAwD"}

package/src/engine/graphics/trail/tube/tube_attributes_spec.js

@@ -0,0 +1,69 @@
+import { EndianType } from "../../../../core/binary/EndianType.js";
+import { BinaryDataType } from "../../../../core/binary/type/BinaryDataType.js";
+import { RowFirstTableSpec } from "../../../../core/collection/table/RowFirstTableSpec.js";
+
+/**
+ * Per-vertex attribute layout for a {@link TubeX}.
+ *
+ * Unlike {@link RibbonX} (which extrudes in screen space and therefore stores
+ * the neighbouring positions to derive a 2D normal), the tube extrudes in WORLD
+ * space inside the vertex shader using a per-knot tangent frame. Every vertex of
+ * a knot's ring shares the same centre/frame/colour/etc and differs only by `off`
+ * (its angular position around the ring), so the heavy per-frame work is just
+ * writing the knot centre + frame to the ring's `radial+1` rows.
+ *
+ * Layout is floats-first then a uint8 colour triple, padded to a 4-byte multiple
+ * so the interleaved Float32 view (stride = bytesPerRecord >> 2) stays aligned —
+ * the same trick {@link ribbon_attributes_spec} relies on.
+ */
+export const tube_attributes_spec = new RowFirstTableSpec([
+    // age (CPU-side bookkeeping for the simulator; NOT a GPU attribute)
+    BinaryDataType.Float32,
+
+    // position (ring centre, world space)
+    BinaryDataType.Float32,
+    BinaryDataType.Float32,
+    BinaryDataType.Float32,
+
+    // frame normal (ring basis axis 1, world space, unit)
+    BinaryDataType.Float32,
+    BinaryDataType.Float32,
+    BinaryDataType.Float32,
+
+    // frame binormal (ring basis axis 2, world space, unit)
+    BinaryDataType.Float32,
+    BinaryDataType.Float32,
+    BinaryDataType.Float32,
+
+    // off (angular position around the ring, 0..1; STATIC per radial index = uv.x)
+    BinaryDataType.Float32,
+
+    // uv_v (position along the tube; DYNAMIC = uv.y)
+    BinaryDataType.Float32,
+
+    // alpha
+    BinaryDataType.Float32,
+
+    // thickness (tube diameter; radius = thickness * 0.5)
+    BinaryDataType.Float32,
+
+    // color
+    BinaryDataType.Uint8,
+    BinaryDataType.Uint8,
+    BinaryDataType.Uint8,
+
+    // padding -> bytesPerRecord = 60 (divisible by 4, keeps the Float32 view aligned)
+    BinaryDataType.Uint8,
+
+], EndianType.LittleEndian);
+
+// Column indices into {@link tube_attributes_spec} for RowFirstTable read/write.
+export const TUBE_ATTRIBUTE_ADDRESS_AGE = 0;
+export const TUBE_ATTRIBUTE_ADDRESS_POSITION = 1;
+export const TUBE_ATTRIBUTE_ADDRESS_NORMAL = 4;
+export const TUBE_ATTRIBUTE_ADDRESS_BINORMAL = 7;
+export const TUBE_ATTRIBUTE_ADDRESS_OFF = 10;
+export const TUBE_ATTRIBUTE_ADDRESS_UV_V = 11;
+export const TUBE_ATTRIBUTE_ADDRESS_ALPHA = 12;
+export const TUBE_ATTRIBUTE_ADDRESS_THICKNESS = 13;
+export const TUBE_ATTRIBUTE_ADDRESS_COLOR = 14;

package/src/engine/graphics/trail/tube/tube_frame.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Compute a rotation-minimising (parallel-transported) tangent frame for one knot
+ * of a tube and write it as `[Nx, Ny, Nz, Bx, By, Bz]` to `out` at `out_offset`.
+ *
+ * Given the local unit tangent `T` and the previous knot's normal `prevN`, the new
+ * normal is `prevN` projected onto the plane perpendicular to `T` (Gram-Schmidt) —
+ * this is the discrete rotation-minimising frame, which carries the ring's
+ * orientation forward with no twist as the tangent turns. The binormal is `T × N`.
+ *
+ * When `prevN` is (nearly) parallel to `T` the projection collapses; we then
+ * bootstrap a stable arbitrary basis from `T` alone via
+ * {@link v3_orthonormal_matrix_from_normal}. This is a genuine geometric
+ * degeneracy (motion exactly along the previous normal), not a defensive guard.
+ *
+ * Equivalent to `m3_make_rotation_TBN(M, T, prevN)` (whose binormal row is
+ * `prevN × T` and whose normal row is the same projection), but written inline so
+ * we can detect the degeneracy BEFORE normalising — `Vector3.set` asserts on NaN,
+ * so feeding a zero vector to a normalising primitive would throw in dev builds.
+ *
+ * PRECONDITION: `T` is a unit vector. `prevN` should be a unit vector.
+ *
+ * @param {number[]|Float32Array|Float64Array} out
+ * @param {number} out_offset
+ * @param {number} tx unit tangent x
+ * @param {number} ty unit tangent y
+ * @param {number} tz unit tangent z
+ * @param {number} pnx previous normal x
+ * @param {number} pny previous normal y
+ * @param {number} pnz previous normal z
+ */
+export function tube_frame_transport(out: number[] | Float32Array | Float64Array, out_offset: number, tx: number, ty: number, tz: number, pnx: number, pny: number, pnz: number): void;
+//# sourceMappingURL=tube_frame.d.ts.map

package/src/engine/graphics/trail/tube/tube_frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tube_frame.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/trail/tube/tube_frame.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,0CATW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,QAoChB"}

package/src/engine/graphics/trail/tube/tube_frame.js

@@ -0,0 +1,83 @@
+import { v3_orthonormal_matrix_from_normal } from "../../../../core/geom/vec3/v3_orthonormal_matrix_from_normal.js";
+
+/**
+ * Below this squared length the projected normal is treated as degenerate (the
+ * previous normal was ~parallel to the new tangent) and we bootstrap a fresh
+ * basis instead of normalising a near-zero vector.
+ * @type {number}
+ */
+const FRAME_DEGENERATE_EPSILON_SQR = 1e-10;
+
+/**
+ * Scratch for the bootstrap path; module-static so transport never allocates.
+ * Float64 so the util doesn't lose precision internally — the caller decides the
+ * storage precision of the result.
+ * @type {Float64Array}
+ */
+const _boot = new Float64Array(9);
+
+/**
+ * Compute a rotation-minimising (parallel-transported) tangent frame for one knot
+ * of a tube and write it as `[Nx, Ny, Nz, Bx, By, Bz]` to `out` at `out_offset`.
+ *
+ * Given the local unit tangent `T` and the previous knot's normal `prevN`, the new
+ * normal is `prevN` projected onto the plane perpendicular to `T` (Gram-Schmidt) —
+ * this is the discrete rotation-minimising frame, which carries the ring's
+ * orientation forward with no twist as the tangent turns. The binormal is `T × N`.
+ *
+ * When `prevN` is (nearly) parallel to `T` the projection collapses; we then
+ * bootstrap a stable arbitrary basis from `T` alone via
+ * {@link v3_orthonormal_matrix_from_normal}. This is a genuine geometric
+ * degeneracy (motion exactly along the previous normal), not a defensive guard.
+ *
+ * Equivalent to `m3_make_rotation_TBN(M, T, prevN)` (whose binormal row is
+ * `prevN × T` and whose normal row is the same projection), but written inline so
+ * we can detect the degeneracy BEFORE normalising — `Vector3.set` asserts on NaN,
+ * so feeding a zero vector to a normalising primitive would throw in dev builds.
+ *
+ * PRECONDITION: `T` is a unit vector. `prevN` should be a unit vector.
+ *
+ * @param {number[]|Float32Array|Float64Array} out
+ * @param {number} out_offset
+ * @param {number} tx unit tangent x
+ * @param {number} ty unit tangent y
+ * @param {number} tz unit tangent z
+ * @param {number} pnx previous normal x
+ * @param {number} pny previous normal y
+ * @param {number} pnz previous normal z
+ */
+export function tube_frame_transport(out, out_offset, tx, ty, tz, pnx, pny, pnz) {
+    const d = pnx * tx + pny * ty + pnz * tz;
+
+    let nx = pnx - d * tx;
+    let ny = pny - d * ty;
+    let nz = pnz - d * tz;
+
+    const n_len2 = nx * nx + ny * ny + nz * nz;
+
+    if (n_len2 > FRAME_DEGENERATE_EPSILON_SQR) {
+        const inv = 1 / Math.sqrt(n_len2);
+
+        nx *= inv;
+        ny *= inv;
+        nz *= inv;
+
+        out[out_offset] = nx;
+        out[out_offset + 1] = ny;
+        out[out_offset + 2] = nz;
+
+        // B = T x N (unit, since T and N are orthonormal)
+        out[out_offset + 3] = ty * nz - tz * ny;
+        out[out_offset + 4] = tz * nx - tx * nz;
+        out[out_offset + 5] = tx * ny - ty * nx;
+    } else {
+        v3_orthonormal_matrix_from_normal(_boot, 0, tx, ty, tz);
+
+        out[out_offset] = _boot[0];
+        out[out_offset + 1] = _boot[1];
+        out[out_offset + 2] = _boot[2];
+        out[out_offset + 3] = _boot[3];
+        out[out_offset + 4] = _boot[4];
+        out[out_offset + 5] = _boot[5];
+    }
+}

package/src/engine/graphics/util/composeMatrix4.js

@@ -1,4 +1,4 @@
-import { compose_matrix4_array } from "../../../core/geom/3d/mat4/compose_matrix4_array.js";
+import { m4_compose } from "../../../core/geom/3d/mat4/m4_compose.js";
 
 /**
  *
@@ -9,5 +9,5 @@ import { compose_matrix4_array } from "../../../core/geom/3d/mat4/compose_matrix
  */
 export function composeMatrix4(result, position, rotation, scale) {
     const te = result.elements;
-    compose_matrix4_array(te, position, rotation, scale);
+    m4_compose(te, position, rotation, scale);
 }

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;
 }

package/src/engine/navigation/mesh/NavigationMesh.js

@@ -2,9 +2,9 @@ import { BVH } from "../../../core/bvh2/bvh3/BVH.js";
 import { BinaryTopology, NULL_POINTER } from "../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
 import Vector3 from "../../../core/geom/Vector3.js";
 import { navmesh_build_topology } from "./build/navmesh_build_topology.js";
-import { bt_mesh_face_find_path_polyanya } from "./bt_mesh_face_find_path_polyanya.js";
-import { bvh_build_from_bt_mesh } from "./bvh_build_from_bt_mesh.js";
-import { bvh_query_nearest_face } from "./bvh_query_nearest_face.js";
+import { bt_mesh_face_find_path_polyanya } from "../../../core/geom/3d/topology/struct/binary/query/bt_mesh_face_find_path_polyanya.js";
+import { bt_mesh_build_face_bvh } from "../../../core/geom/3d/topology/struct/binary/query/bt_mesh_build_face_bvh.js";
+import { bt_mesh_find_nearest_face } from "../../../core/geom/3d/topology/struct/binary/query/bt_mesh_find_nearest_face.js";
 
 // snapped (on-mesh) start/goal positions, reused across queries
 const scratch_start_point = new Float32Array(3);
@@ -80,7 +80,7 @@ export class NavigationMesh {
             up,
         });
 
-        bvh_build_from_bt_mesh(this.bvh, this.topology);
+        bt_mesh_build_face_bvh(this.bvh, this.topology);
     }
 
 
@@ -114,14 +114,14 @@ export class NavigationMesh {
         const mesh = this.topology;
         const bvh = this.bvh;
 
-        const start_face_id = bvh_query_nearest_face(bvh, mesh, start_x, start_y, start_z, scratch_start_point);
+        const start_face_id = bt_mesh_find_nearest_face(bvh, mesh, start_x, start_y, start_z, scratch_start_point);
 
         if (start_face_id === NULL_POINTER) {
             // probably topology is empty
             return 0;
         }
 
-        const goal_face_id = bvh_query_nearest_face(bvh, mesh, goal_x, goal_y, goal_z, scratch_goal_point);
+        const goal_face_id = bt_mesh_find_nearest_face(bvh, mesh, goal_x, goal_y, goal_z, scratch_goal_point);
 
         if (goal_face_id === NULL_POINTER) {
             // should never happen if we got the start face

package/src/engine/navigation/mesh/PATHFINDING_PLAN.md

@@ -193,7 +193,7 @@ Built as a **standalone 2-D module** `bt_mesh_face_find_path_polyanya` (xy-plane
    sidestepped it by orienting on face normals, not a cone). Full `navigation/mesh` suite stays green.
 
    **Path validation + a finding (done).** Both benches keep their paths and validate them against a
-   BVH: `bvh_segment_penetrates_mesh` flags any piece that crosses a triangle interior transversally, and
+   BVH: `bt_mesh_segment_penetrates_surface` flags any piece that crosses a triangle interior transversally, and
    sampling reports how far each piece strays off the surface. The finding: a **corner-only** waypoint path
    is correct only AT its turning corners, so the straight chord between two corners on different levels
    flew over / cut through the ramped geometry between them (the funnel had the same property) — on the

package/src/engine/navigation/mesh/build/clip_soup_against_overhangs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clip_soup_against_overhangs.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/navigation/mesh/build/clip_soup_against_overhangs.js"],"names":[],"mappings":"AA+MA;;;;;;;;GAQG;AACH,kDARW,MAAM,EAAE,kBACR,MAAM,wCAEN,MAAM,gBACN,MAAM,gBAEJ,MAAM,EAAE,CAkOpB"}
+{"version":3,"file":"clip_soup_against_overhangs.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/navigation/mesh/build/clip_soup_against_overhangs.js"],"names":[],"mappings":"AAiKA;;;;;;;;GAQG;AACH,kDARW,MAAM,EAAE,kBACR,MAAM,wCAEN,MAAM,gBACN,MAAM,gBAEJ,MAAM,EAAE,CAkOpB"}