@driftengine/core 4.8.1 → 4.8.2

package/CHANGELOG.json

@@ -1,4 +1,90 @@
 [
+  {
+    "version": "4.8.2",
+    "date": "2026-10-03",
+    "entries": [
+      {
+        "kind": "fixed",
+        "short": "A component a script names to `drift/ecs` by a string counts as the access the schedule checks, so `reads Hunger` for a count is no longer called unused.",
+        "text": "`ecs.count(world, \"Hunger\")` reaches a schedule that refuses a component the system did not declare, and the compiler never counted the name: the declaration the host demanded was called unused (DS0291), and leaving it out compiled clean and was refused once per tick. DriftScript 1.17.0 lets a capability say which parameter names a component and how, and `drift/ecs` marks `has`, `read`, `count`, `at`, `findNearest`, `query` and `view` as reads and `attach`, `detach` and `write` as writes, so a string literal there counts exactly as `e.Hunger` does. `without` is not marked, as an exclusion never looks inside the component. driftscript 1.17.0, pinned in four manifests: the editor carries the pin too, which is now said where the others are. Reported from a game."
+      },
+      {
+        "kind": "fixed",
+        "short": "The lit shader carries glass, profiles and cookies, effects tables, DriftLight and clustering only once a scene uses them, so a phone no longer pays for all of it on every pixel.",
+        "text": "From 4.5.0 every lit pipeline compiled in the coloured-glass shadow lookups, and since then the measured-profile and cookie reads, the effects-table load, DriftLight's volume reads and the clustered arm of the light loop, whether a scene used any of them or not. Each sat behind a uniform branch, which keeps its code and its registers; the clustered arm also ran a view transform, two logarithms and a texel fetch on every lit pixel. On a desktop GPU none of this showed; on a phone the point-lit scenes fell to 10 to 20 fps while the sea and the voxel sandbox held, which is what pointed at the lit pass. On the phone that reported it, 4.8.2 runs them smoothly where 4.8.1 crawled. Each is now a pipeline constant the device compiles away, off until it is used and then rebuilt on, once: glass when a shadow pass is first offered a pane, fixtures when a profile or cookie is loaded, effects when a material carries a table, DriftLight when a volume is set; clustering follows `clusteredLights`. On WebGPU the rebuilt set swaps in together when it has compiled, so no frame mixes the two; on WebGL2 it is a synchronous recompile at the next `beginFrame`. Measured with RADV's own statistics, the lit shader went from 10,134 instructions and 144 registers to 4,641 and 96 on WebGL2, and from 10,544 and 120 to 5,276 and 96 on WebGPU, below 4.4.2's 5,335 and 5,859. Every published scene is pixel-identical to 4.8.1 on both backends, and so are the pages that turn each feature on: glass under the sun, a lamp and a rectangle, a profile, an effects table, a DriftLight volume and clustered lighting. What it costs is the frames between a feature's first use and its rebuild, which draw without it."
+      },
+      {
+        "kind": "fixed",
+        "short": "On WebGPU a panel or a contributed pass drawn after `endFrame` with the frame graph on is drawn, where it was lost to a destroyed canvas texture.",
+        "text": "With the graph on, a verb drawn after `endFrame` records rather than opening the overlay pass, and only an opening queued the microtask that submits it before the browser presents. `fillPanel` and `drawPass` recorded and queued nothing, so their work waited for the next `beginFrame`, whose replay drew onto a canvas texture already presented: \"Destroyed texture used in a submit\", and no interface. Recording after the present now queues the submission as opening it does. Reported from a game drawing its HUD over the finished frame, which had turned the graph off to get it back."
+      },
+      {
+        "kind": "fixed",
+        "short": "A contributed pass is told the format and samples of the pass it lands in, and ui2d's sprite pass draws after `endFrame` on WebGPU, where it was refused.",
+        "text": "`PassDevice` says what the frame is, the scene target at the scene's samples, and a pass drawn after `endFrame` lands on the canvas at one sample, so a pipeline built from the device was refused there. The WebGPU `PassContext` now carries `format`, `depthFormat` and `samples` for the pass the draw lands in, read from the same cache a mesh drawn there uses, and `@driftengine/ui2d`'s sprite pass keeps a pipeline per target and chooses at the draw. A game had registered its HUD's sprite pass for the canvas by hand to get round it. Code that builds a `PassContext` itself, which is test code, now supplies the three."
+      },
+      {
+        "kind": "fixed",
+        "short": "A ragdoll turns each joint by the bone that starts at it, so a skinned limb follows its body, where it trailed by a bone.",
+        "text": "`writePose` turned joint j by the body standing on the bone that ends at j, and a skinned limb follows the joint it starts from: the forearm is weighted to the elbow. So a limb was drawn in line with the bone before it, 0.47 m from its body at the hands in a doll synced and never stepped, as reported from a game. Each joint is now turned by its first bone below, and a joint with none below it rides the bone it hangs off; `drive` steers the same bone the write reads, and `sync` carries a bone's twist about its own length, which a wrist with a thumb beside the fingers needs. Translations are each parent's own frame, where they were world offsets that only agreed with a rig unrotated at rest. A root's rotation is written in the frame of the node placed at `rootX`, `rootY` and `rootZ`. The chains the tests were built from were straight and unrotated, which is why none of this showed; an arm with real rotations now stands beside them."
+      },
+      {
+        "kind": "fixed",
+        "short": "A character controller accelerates and brakes along a diagonal as fast as along an axis, where it gained speed √2 times as fast.",
+        "text": "The wanted velocity was clamped as a vector and then approached one world axis at a time, each by the whole step, so a diagonal from rest had 2.83 m/s three ticks in where a straight run had 2.0, and stopped √2 times as fast. It now moves toward the wanted velocity by at most the step in length, and lands on it exactly. What it gives up is that each axis no longer reaches its target on its own schedule: turning from one direction to another now curves rather than squaring the corner."
+      },
+      {
+        "kind": "added",
+        "short": "An action can be bound to mouse buttons, `{ device: 'mouse', button: 'left' }`, held, pressed and claimed like a key.",
+        "text": "`DigitalAction.mouseButtons` and the `mouse` binding device, saved and loaded with the rest, and `InputSource.mouseDown`, `mousePressed` and `consumeMousePress` per button, with the keyboard's edge rules: a press is pressed over the source's target, released anywhere, and a lost focus or a cancelled pointer releases every button. `MouseButton` is `left`, `middle`, `right`, `back` or `forward`. A binding narrowed as keyboard-or-else-gamepad no longer compiles, since there is a third device; the input example and the gamepad page are corrected. A game read `mousedown` itself beside the actions it bound everything else through."
+      },
+      {
+        "kind": "added",
+        "short": "`beginViewModel` and `endViewModel` draw a first person's arms and weapon in the nearest sliver of depth, so they never go into a wall and the world's depth is kept.",
+        "text": "What is drawn between the two lands in the nearest share of the depth range, 1% by default (`VIEW_MODEL_DEPTH_SHARE`): the viewport's depth bounds on WebGPU and `gl.depthRange` on WebGL2, at whichever end the context's convention puts near. The world's depth is not cleared, so ambient occlusion, depth of field and fog still see the world behind the weapon, which clearing it inside an inset did not. `endFrame` closes a view model left open. Its pixels take no motion of their own under temporal reconstruction, so a view model is drawn with multisampling. A game had squeezed the depth through a camera of its own for want of this."
+      },
+      {
+        "kind": "fixed",
+        "short": "`ParticlePool.emit` draws a particle the frame it is born, where it waited for the next `update`.",
+        "text": "The drawn streams are compacted live particles and only `update` rebuilt them, so a burst emitted after the frame's update, a muzzle flash or a hit's sparks, appeared a frame late, and a pool updated only while it had something live never showed its first particle. `emit` now writes the particle into both streams at once, into the entry of the particle it replaces where the ring is full, and onto the end otherwise. A game called `update(0)` before every draw to see its own effects."
+      },
+      {
+        "kind": "fixed",
+        "short": "The tools overlay draws its panels on a background under their titles, the console draws where it has scrolled, and Ctrl+Shift+Z redoes.",
+        "text": "The overlay gives each panel a dark background and a title row `PANEL_TITLE_HEIGHT` pixels tall, so the tools example no longer lays a backdrop under each site; colours with alpha reach the painter as `#rrggbbaa`, which its contract always allowed. The console copies its scroll to the node the overlay draws and takes the window from the height its panel is given, so it shows the newest lines, a wheel moves them and a click picks the row under the pointer; the overlay takes a wheel over a panel whether or not the panel made a command of it, so the page no longer scrolls underneath. Ctrl+Shift+Z redoes with the capital a browser reports for it. An `f32` field reads as the shortest decimal that stores as the same float, `0.55` rather than `0.550000011920929`. A `LockstepSession` is handed to `observeSession` and `sessionReadout` as it is, through a public `rewindDepth`, and the package README edits through `setFieldCommand` where its example did not compile."
+      },
+      {
+        "kind": "changed",
+        "short": "`World.add` and `definePrefab` refuse a field the component does not have, where the value was dropped without a word.",
+        "text": "A store fills every field its schema declares and never looked at the other keys, so a misspelt field was dropped and the field it meant took its default; one consumer's had been dropped since the component was written. An add now refuses one by name and lists the fields there are, before anything is stored, as `write` and a component's declared defaults already did, and `definePrefab` refuses one when the prefab is defined rather than at its first spawn. A scene read back is migrated onto the current schema first, so a renamed field in a save still loads."
+      },
+      {
+        "kind": "fixed",
+        "short": "An interface tree draws and hit-tests by layer, so a raised popup covers a later sibling and takes the pointer there.",
+        "text": "`UiNode.layer` was sorted by `layerOrder` and read by nothing that draws or points: a dropdown raised over the panel its control sits in was drawn under a later sibling and the pointer reached the sibling through it. `drawUiTree` now draws layer by layer, lowest first and tree order within one, each with the clips it would have had, and `uiHitTest` searches from the highest layer down. A tree with no raised node is drawn and searched in one walk, as before."
+      },
+      {
+        "kind": "fixed",
+        "short": "An audio mix that is not running hands a recording no stream, so a clip started before a gesture keeps its picture instead of half a second of it.",
+        "text": "`AudioGraph.captureStream` answered a live track from a suspended context, which never carries a sample, and a recorder given one stalled on it: a recording started from a script click kept 19 frames of 120 and no sound. It answers `null` until the context runs, and the tap after."
+      },
+      {
+        "kind": "fixed",
+        "short": "`beginInset` is documented as returning the aspect it returns, and answers the asked-for box's aspect on a lost WebGPU device instead of 0.",
+        "text": "The WebGPU renderer's comment said it returned the inset's height in device pixels, which both backends stopped doing; and with no pass to draw into it returned 0, a projection of infinities in the caller's camera. It answers the aspect of the box asked for there."
+      },
+      {
+        "kind": "added",
+        "short": "A mesh with no texture coordinates drawn with an albedo, normal or emissive map is said once, where the maps were ignored in silence.",
+        "text": "Every map on such a mesh reads one texel, so an emissive map made nothing glow and the frame was identical with and without it. The first such draw of each mesh says so, on both backends. A one-colour ORM map is not counted: read at one texel it is the constant roughness and metalness it was bound for."
+      },
+      {
+        "kind": "fixed",
+        "short": "`probeXrSupport` takes the WebGL2 context a game draws with, without a cast, and `XrRuntime` is exported.",
+        "text": "Its parameter was a type whose one member is optional, which TypeScript treats as weak, and the DOM types do not declare `makeXRCompatible` on `WebGL2RenderingContext`, so the context every game holds did not compile until it was cast. It takes any object and asks for the method. `XrRuntime`, what `HostServices.xr` takes, is exported from `@driftengine/script`."
+      }
+    ]
+  },
   {
     "version": "4.8.1",
     "date": "2026-10-03",

package/dist/index.d.ts

@@ -277,6 +277,7 @@ export type { GroundSurface, RibbonSurfaceOptions, SurfaceHit } from './physics/
 export { CompositeSurface } from './physics/compositeSurface.ts';
 export { colliderSurface } from './physics/colliderSurface.ts';
 export { DEPTH_CLEAR, DEPTH_COMPARE, DEPTH_COMPARE_EQUAL, DEPTH_FORMAT, DEPTH_OFFSET_SIGN, REVERSED_DEPTH, conventionalDepth, } from './render/depthConvention.ts';
+export { VIEW_MODEL_DEPTH_SHARE } from './render/viewModel.ts';
 export type { ColliderSurfaceOptions } from './physics/colliderSurface.ts';
 export { BoxSurface } from './physics/boxSurface.ts';
 export { heightSurface } from './physics/heightSurface.ts';
@@ -307,7 +308,7 @@ export { AXIS_X, AXIS_Y, AXIS_Z, ColliderSet, aabbFromCenter, bodyBounds, boxCol
 export { InputSource } from './input/input.ts';
 export { isTypingTarget } from './input/typingTarget.ts';
 export type { TouchPoint, InputCallbacks } from './input/input.ts';
-export type { GamepadIdentity, GamepadView, InputOptions, InputSourceName } from './input/input.ts';
+export type { GamepadIdentity, GamepadView, InputOptions, InputSourceName, MouseButton, } from './input/input.ts';
 export type { InputDevice } from './input/activeDevice.ts';
 export type { GamepadFamily } from './input/gamepadIdentity.ts';
 export { DEFAULT_DEADZONE } from './input/gamepadMapping.ts';

package/dist/index.js

@@ -338,6 +338,8 @@ export { colliderSurface } from './physics/colliderSurface.js';
  * `EXT_clip_control`.
  */
 export { DEPTH_CLEAR, DEPTH_COMPARE, DEPTH_COMPARE_EQUAL, DEPTH_FORMAT, DEPTH_OFFSET_SIGN, REVERSED_DEPTH, conventionalDepth, } from './render/depthConvention.js';
+/* How much of the depth range `beginViewModel` takes when it is given no share. See `viewModel.ts`. */
+export { VIEW_MODEL_DEPTH_SHARE } from './render/viewModel.js';
 export { BoxSurface } from './physics/boxSurface.js';
 export { heightSurface } from './physics/heightSurface.js';
 export { DebugLines } from './render/debugLines.js';

package/dist/input/actionMap.d.ts

@@ -1,5 +1,5 @@
 import type { KeyValueStore } from '../core/storage.ts';
-import type { InputSource } from './input.ts';
+import type { InputSource, MouseButton } from './input.ts';
 import type { GamepadButton } from './gamepadMapping.ts';
 /**
  * Actions a game asks about, and the bindings that satisfy them.
@@ -20,11 +20,16 @@ export type Binding = {
 } | {
     readonly device: 'gamepad';
     readonly button: GamepadButton;
+} | {
+    readonly device: 'mouse';
+    readonly button: MouseButton;
 };
 /** Jump, fire, pause: a state, bound to keys and buttons. */
 export interface DigitalAction {
     readonly keys?: readonly string[];
     readonly buttons?: readonly GamepadButton[];
+    /** Mouse buttons, pressed over the input source's target: fire on the left, aim on the right. */
+    readonly mouseButtons?: readonly MouseButton[];
 }
 /**
  * Move, look: a direction rather than a state.

package/dist/input/actionMap.js

@@ -26,13 +26,17 @@ export class ActionMap {
     down(action) {
         return this.any(action, (binding) => binding.device === 'keyboard'
             ? this.input.isDown(binding.code)
-            : (this.input.pad(0)?.down(binding.button) ?? false));
+            : binding.device === 'mouse'
+                ? this.input.mouseDown(binding.button)
+                : (this.input.pad(0)?.down(binding.button) ?? false));
     }
     /** Whether anything bound to it went down since the last poll. Readable by anything. */
     pressed(action) {
         return this.any(action, (binding) => binding.device === 'keyboard'
             ? this.input.keyPressed(binding.code)
-            : (this.input.pad(0)?.pressed(binding.button) ?? false));
+            : binding.device === 'mouse'
+                ? this.input.mousePressed(binding.button)
+                : (this.input.pad(0)?.pressed(binding.button) ?? false));
     }
     /**
      * The same edge, claimed: true for exactly one caller.
@@ -50,6 +54,10 @@ export class ActionMap {
                 if (this.input.consumeKeyPress(binding.code))
                     return true;
             }
+            else if (binding.device === 'mouse') {
+                if (this.input.consumeMousePress(binding.button))
+                    return true;
+            }
             else if (this.input.pad(0)?.consumePress(binding.button) === true) {
                 return true;
             }
@@ -291,15 +299,17 @@ function bindingsOf(definition) {
         list.push({ device: 'keyboard', code });
     for (const button of definition.buttons ?? [])
         list.push({ device: 'gamepad', button });
+    for (const button of definition.mouseButtons ?? [])
+        list.push({ device: 'mouse', button });
     return list;
 }
 function sameBinding(a, b) {
-    if (a.device !== b.device)
-        return false;
-    return a.device === 'keyboard' && b.device === 'keyboard'
-        ? a.code === b.code
-        : a.device === 'gamepad' && b.device === 'gamepad' && a.button === b.button;
+    if (a.device === 'keyboard' || b.device === 'keyboard') {
+        return a.device === 'keyboard' && b.device === 'keyboard' && a.code === b.code;
+    }
+    return a.device === b.device && a.button === b.button;
 }
+const MOUSE_BUTTONS = new Set(['left', 'middle', 'right', 'back', 'forward']);
 function sameList(a, b) {
     return a.length === b.length && a.every((entry, at) => sameBinding(entry, b[at]));
 }
@@ -310,5 +320,8 @@ function isBinding(value) {
     const candidate = value;
     if (candidate.device === 'keyboard')
         return typeof candidate.code === 'string';
+    if (candidate.device === 'mouse') {
+        return typeof candidate.button === 'string' && MOUSE_BUTTONS.has(candidate.button);
+    }
     return candidate.device === 'gamepad' && typeof candidate.button === 'string';
 }

package/dist/input/input.d.ts

@@ -34,6 +34,8 @@ export interface TouchPoint {
 }
 /** The devices this source watches, and the granularity a consumer may switch off. */
 export type InputSourceName = 'keyboard' | 'mouse' | 'touch' | 'gamepad';
+/** A mouse button by what it is, in `MouseEvent.button` order. */
+export type MouseButton = 'left' | 'middle' | 'right' | 'back' | 'forward';
 export interface InputOptions {
     /**
      * Turn a device off. Absent means on.
@@ -147,6 +149,19 @@ export declare class InputSource {
     private mouseDx;
     private mouseDy;
     private mouseButtonDown;
+    /**
+     * Each mouse button's own state, as the keyboard's sets are for keys: held, pressed since the
+     * last poll, claimed this frame, and waiting for somebody to act on it. Bits, by `MOUSE_BIT`.
+     *
+     * **Beside `mouseButtonDown`, not instead of it.** That flag is "a button is held", which is what
+     * an unlocked drag-to-look reads; a game binding fire to the left button and aim to the right
+     * needs to know which, and to see a release of one while the other stays down.
+     */
+    private mouseHeld;
+    private mousePressedNow;
+    private mousePressedNext;
+    private mouseClaimed;
+    private mouseUnclaimed;
     private readonly disposers;
     /** Which device the player last actually used, and who wants telling when that changes. */
     private readonly active;
@@ -262,6 +277,19 @@ export declare class InputSource {
     keyPressed(code: string): boolean;
     /** The same edge, claimed: true for exactly one caller, then gone for everybody. */
     consumeKeyPress(code: string): boolean;
+    /**
+     * Whether a mouse button is held: pressed over the target and not yet released anywhere.
+     *
+     * A browser opens its context menu on the right button's release; a game binding that button
+     * cancels `contextmenu` on its canvas, which is a decision about the page and not this source's.
+     */
+    mouseDown(button: MouseButton): boolean;
+    /** Whether a mouse button went down since the last poll, as `keyPressed` is for a key. */
+    mousePressed(button: MouseButton): boolean;
+    /** The same edge, claimed, as `consumeKeyPress` is for a key: true for exactly one caller. */
+    consumeMousePress(button: MouseButton): boolean;
+    /** Every button up and every waiting press gone: what a lost focus or a cancelled pointer means. */
+    private releaseMouse;
     /**
      * Add a device-event subscriber. Multiple reusable control layers may listen
      * without overwriting one another; interpretation still happens outside the

package/dist/input/input.js

@@ -81,6 +81,18 @@ export function askForPointerLock(request) {
         }
     });
 }
+/** One bit a button, so the held, pressed and claimed states are integers and a read allocates nothing. */
+const MOUSE_BIT = {
+    left: 1,
+    middle: 2,
+    right: 4,
+    back: 8,
+    forward: 16,
+};
+/** `MouseEvent.button` as a bit, or 0 for a button past the five this names. */
+function mouseBit(button) {
+    return button >= 0 && button < 5 ? 1 << button : 0;
+}
 /** Scratch for the deadzone, at module scope because `axis` is a per-frame read. */
 const deadzoned = { x: 0, y: 0 };
 /** Four is past generous for local play, and the array is preallocated to it. */
@@ -261,6 +273,19 @@ export class InputSource {
     mouseDx = 0;
     mouseDy = 0;
     mouseButtonDown = false;
+    /**
+     * Each mouse button's own state, as the keyboard's sets are for keys: held, pressed since the
+     * last poll, claimed this frame, and waiting for somebody to act on it. Bits, by `MOUSE_BIT`.
+     *
+     * **Beside `mouseButtonDown`, not instead of it.** That flag is "a button is held", which is what
+     * an unlocked drag-to-look reads; a game binding fire to the left button and aim to the right
+     * needs to know which, and to see a release of one while the other stays down.
+     */
+    mouseHeld = 0;
+    mousePressedNow = 0;
+    mousePressedNext = 0;
+    mouseClaimed = 0;
+    mouseUnclaimed = 0;
     disposers = [];
     /** Which device the player last actually used, and who wants telling when that changes. */
     active = new ActiveDevice();
@@ -369,14 +394,22 @@ export class InputSource {
             this.keys.clear();
             this.keysUnclaimed.clear();
         });
-        this.listen(target, 'mousedown', () => {
+        this.listen(target, 'mousedown', (e) => {
             if (!this.enabled.mouse)
                 return;
             this.mouseButtonDown = true;
+            const bit = mouseBit(e.button);
+            this.mouseHeld |= bit;
+            this.mousePressedNext |= bit;
+            this.mouseUnclaimed |= bit;
             this.active.use('mouse');
         });
-        this.listen(window, 'mouseup', () => {
+        /* On the window, so a press that becomes a drag off the canvas still comes back up. */
+        this.listen(window, 'mouseup', (e) => {
             this.mouseButtonDown = false;
+            const bit = mouseBit(e.button);
+            this.mouseHeld &= ~bit;
+            this.mouseUnclaimed &= ~bit;
         });
         /*
          * **Released by anything that can eat the mouseup, exactly as the keys are.**
@@ -398,16 +431,12 @@ export class InputSource {
          * `visibilitychange` as well as `blur`, because a tab switched away with a button held
          * comes back to a document that never saw the release either.
          */
-        this.listen(window, 'blur', () => {
-            this.mouseButtonDown = false;
-        });
-        this.listen(window, 'pointercancel', () => {
-            this.mouseButtonDown = false;
-        });
+        this.listen(window, 'blur', () => this.releaseMouse());
+        this.listen(window, 'pointercancel', () => this.releaseMouse());
         /* Not in `GlobalEventHandlersEventMap`, so it is bound directly and disposed by hand. */
         const onHidden = () => {
             if (document.visibilityState !== 'visible')
-                this.mouseButtonDown = false;
+                this.releaseMouse();
         };
         document.addEventListener('visibilitychange', onHidden);
         this.disposers.push(() => document.removeEventListener('visibilitychange', onHidden));
@@ -508,6 +537,10 @@ export class InputSource {
         spent.clear();
         this.keysPressedNext = spent;
         this.keysClaimed.clear();
+        /* The mouse buttons' frame boundary, on the same poll and by the same rule. */
+        this.mousePressedNow = this.mousePressedNext;
+        this.mousePressedNext = 0;
+        this.mouseClaimed = 0;
         if (!this.enabled.gamepad)
             return;
         const source = globalThis
@@ -601,6 +634,35 @@ export class InputSource {
         this.keysClaimed.add(code);
         return true;
     }
+    /**
+     * Whether a mouse button is held: pressed over the target and not yet released anywhere.
+     *
+     * A browser opens its context menu on the right button's release; a game binding that button
+     * cancels `contextmenu` on its canvas, which is a decision about the page and not this source's.
+     */
+    mouseDown(button) {
+        return (this.mouseHeld & MOUSE_BIT[button]) !== 0;
+    }
+    /** Whether a mouse button went down since the last poll, as `keyPressed` is for a key. */
+    mousePressed(button) {
+        const bit = MOUSE_BIT[button];
+        return (this.mousePressedNow & bit) !== 0 && (this.mouseClaimed & bit) === 0;
+    }
+    /** The same edge, claimed, as `consumeKeyPress` is for a key: true for exactly one caller. */
+    consumeMousePress(button) {
+        const bit = MOUSE_BIT[button];
+        if ((this.mouseUnclaimed & bit) === 0)
+            return false;
+        this.mouseUnclaimed &= ~bit;
+        this.mouseClaimed |= bit;
+        return true;
+    }
+    /** Every button up and every waiting press gone: what a lost focus or a cancelled pointer means. */
+    releaseMouse() {
+        this.mouseButtonDown = false;
+        this.mouseHeld = 0;
+        this.mouseUnclaimed = 0;
+    }
     /**
      * Add a device-event subscriber. Multiple reusable control layers may listen
      * without overwriting one another; interpretation still happens outside the

package/dist/input/inputHarness.d.ts

@@ -36,6 +36,15 @@ export declare function fakeBrowser(id?: string): {
     /** Press a key, as the window would deliver it. `target` is nothing a game is typing into. */
     keyDown(code: string): void;
     keyUp(code: string): void;
+    /**
+     * Press a mouse button over the target, by `MouseEvent.button`: 0 left, 1 middle, 2 right.
+     * Pressed on the target and released on the window, as a browser delivers a drag that ends
+     * off the canvas.
+     */
+    mouseDown(button: number): void;
+    mouseUp(button: number): void;
+    /** The window losing focus, which eats every release that would have followed. */
+    blur(): void;
     /** Run exactly one animation frame, which is what a poll rides on. */
     frame(): void;
     restore(): void;

package/dist/input/inputHarness.js

@@ -60,9 +60,23 @@ export function fakeBrowser(id = 'Xbox 360 Controller (XInput STANDARD GAMEPAD)'
     };
     const frameCallbacks = [];
     let nextFrameHandle = 1;
+    const targetListeners = new Map();
     const target = {
-        addEventListener: () => { },
-        removeEventListener: () => { },
+        addEventListener: (type, fn) => {
+            const existing = targetListeners.get(type);
+            if (existing === undefined)
+                targetListeners.set(type, [fn]);
+            else
+                existing.push(fn);
+        },
+        removeEventListener: (type, fn) => {
+            const existing = targetListeners.get(type);
+            if (existing === undefined)
+                return;
+            const at = existing.indexOf(fn);
+            if (at >= 0)
+                existing.splice(at, 1);
+        },
         requestPointerLock: () => undefined,
         getBoundingClientRect: () => ({ left: 0, top: 0, width: 640, height: 480 }),
     };
@@ -169,6 +183,24 @@ export function fakeBrowser(id = 'Xbox 360 Controller (XInput STANDARD GAMEPAD)'
             for (const fn of windowListeners.get('keyup') ?? [])
                 fn({ code });
         },
+        /**
+         * Press a mouse button over the target, by `MouseEvent.button`: 0 left, 1 middle, 2 right.
+         * Pressed on the target and released on the window, as a browser delivers a drag that ends
+         * off the canvas.
+         */
+        mouseDown(button) {
+            for (const fn of targetListeners.get('mousedown') ?? [])
+                fn({ button, movementX: 0 });
+        },
+        mouseUp(button) {
+            for (const fn of windowListeners.get('mouseup') ?? [])
+                fn({ button });
+        },
+        /** The window losing focus, which eats every release that would have followed. */
+        blur() {
+            for (const fn of windowListeners.get('blur') ?? [])
+                fn({});
+        },
         /** Run exactly one animation frame, which is what a poll rides on. */
         frame() {
             const pending = frameCallbacks.splice(0, frameCallbacks.length);

package/dist/render/backend/webgl2/renderer.d.ts

@@ -781,8 +781,8 @@ export declare class WebGL2Renderer implements RendererApi {
      */
     get presentedFrames(): number;
     private presentedFrameCount;
-    private readonly flatProgram;
-    private readonly flatUniforms;
+    private flatProgram;
+    private flatUniforms;
     /**
      * The lit fragment source every flat program is built from, and the budget it was built at.
      *
@@ -793,7 +793,7 @@ export declare class WebGL2Renderer implements RendererApi {
      * for a lazily compiled variant to end up at a different light budget from the one the renderer
      * uploads for, which is a picture nobody could explain.
      */
-    private readonly flatFragSource;
+    private flatFragSource;
     /**
      * How many lights this renderer's shader has room for, after the device had its say.
      *
@@ -1294,6 +1294,27 @@ export declare class WebGL2Renderer implements RendererApi {
      * each such draw and handed back, where the other backend bakes it into a pipeline.
      */
     private materialDoubleSided;
+    /** Whether the bound material has a map, for the warning a mesh with no coordinates earns. */
+    private materialHasMaps;
+    /** The material last set, so a lit program rebuilt for glass can be given it. */
+    private currentMaterial;
+    /**
+     * The lit stage's switches: what the lit programs were compiled with (`litOn`), and what the
+     * profile and the content have asked for since (`litWanted`).
+     *
+     * **Each is off until it is used** — glass until a pane is offered, a fixture until one is loaded,
+     * the effects until a material carries a table, DriftLight until a volume is set — and then on for
+     * good, rebuilt at the next `beginFrame`. Clustering is the profile's. The code costs the lit pass
+     * registers on every surface whether it finds anything or not, and a world without the feature
+     * draws the same picture without it. `PipelineCache.litSwitches` makes the same decision on the
+     * other backend. The frame a feature is first used in draws without it; the rebuild is a
+     * synchronous compile, and the next frame waits for it.
+     */
+    private readonly litOn;
+    private readonly litWanted;
+    private litAsked;
+    /** Ask for a switch, which the next `beginFrame` compiles in. Never glass with it turned off. */
+    private askLit;
     /**
      * The one sink handed to every caster enumeration.
      *
@@ -2523,6 +2544,17 @@ export declare class WebGL2Renderer implements RendererApi {
      * rather than propagating. Only a shader that will not link at *any* budget throws, and it
      * throws a sentence with the device's numbers in it rather than a bare driver string.
      */
+    /** The lit fragment source this renderer's profile compiles, at a light budget. */
+    private flatFragAt;
+    /**
+     * Every lit program that exists, compiled again with the switches asked for since, at the budget
+     * the renderer already uploads for, and given the pass and the material the old one held.
+     *
+     * At `beginFrame`, not where a feature was first used: a pane is offered inside a shadow pass
+     * with the depth program bound, and a program swapped under it would draw the next caster with
+     * the lit one.
+     */
+    private rebuildLit;
     private fitFlatProgram;
     /**
      * How many point lights this renderer's shader shades at once.
@@ -2716,6 +2748,23 @@ export declare class WebGL2Renderer implements RendererApi {
     fillPanel(rect: InsetRect, color: Vec3, alpha: number): void;
     /** Give the whole canvas back. Safe to call without a matching `beginInset`. */
     endInset(): void;
+    /**
+     * Draw what follows as a **view model**, in the nearest sliver of depth, until `endViewModel`.
+     *
+     * A first-person view model — arms and a held weapon — drawn with the frame's camera, or with one
+     * of its own through `bindMeshPass`, lands in front of anything past the near plane without the
+     * world's depth being cleared, so every pass that reads depth afterwards still sees the world.
+     * `share` is how much of the range it takes, 1% by default. See `viewModel.ts` for what it gives
+     * up, which includes temporal reconstruction: draw a view model with multisampling.
+     *
+     * Not inside an inset: an inset has its own depth, cleared for it, and needs no squeeze.
+     */
+    beginViewModel(share?: number): void;
+    /** Give the whole depth range back. Safe to call without a matching `beginViewModel`. */
+    endViewModel(): void;
+    /** Whether a view model is being drawn, so `endFrame` can close one the caller left open. */
+    private viewModelActive;
+    private readonly viewModelRange;
     /**
      * How much speed blur the frame about to be drawn should resolve with, 0 to 1.
      *