@driftengine/core 4.8.1 → 4.8.3

package/CHANGELOG.json

@@ -1,4 +1,146 @@
 [
+  {
+    "version": "4.8.3",
+    "date": "2026-10-04",
+    "entries": [
+      {
+        "kind": "fixed",
+        "short": "Ambient occlusion no longer darkens smoke, glass, water or text by the corner behind them: it darkens only the part of a pixel they let through, on both backends.",
+        "text": "Occlusion is applied in the composite from the depth the opaque world leaves, after every translucent draw has landed, and a particle or a pane writes no depth, so a puff of smoke in front of a wall was darkened by the corner behind it: reported as walls and figures behind a cloud showing through it as dark outlines, and nothing at all with occlusion off. The scene's alpha now carries how much of each pixel is still the opaque surface. The frame clears it to 1, an opaque draw writes 1, and every blended draw states what it does to it: what covers (glass, smoke, water, lines, text, panels, sprites, splats) multiplies it by what it lets through, what transmits (the global medium, the order-independent composite) by its own transmittance, and what adds light or is a layer of the surface (caustics, light volumes, bolts, a wet film, decals, reflections) leaves it alone. The composite darkens that share and no more, and the temporal resolve and the reconstruction carry it through. Measured on both backends, plain, with temporal antialiasing and with DriftTR, against a darkened join: a pane at 0.85 opacity keeps 0.15 of the darkening behind it and a cluster of smoke none, while the open join and every frame with occlusion off are unchanged to the pixel. What it gives up is light added in front of an occluded corner, which is darkened with the surface it lands on as before, and the GPU-driven pipeline's own blended surfaces, which still take the occlusion behind them because its blit's alpha is the mask that says where it drew. A pass of your own states its blending with `SCENE_ALPHA_COVERS`, `SCENE_ALPHA_TRANSMITS` or `SCENE_ALPHA_KEEPS` on WebGPU, and `blendCovering`, `blendTransmitting` or `blendKeeping` on WebGL2."
+      },
+      {
+        "kind": "fixed",
+        "short": "A particle's size is documented as what it always was, a half-width from the centre to an edge: a particle of size 0.5 is a metre across.",
+        "text": "`ParticleInstances.sizes` and a pool's `sizeStart` and `sizeEnd` were documented as metres across, and the quad spans twice the size, a corner at minus and plus one on each axis, so a caller who sized by the documentation drew every particle twice as wide as meant. The drawing is unchanged, because every effect already tuned against it would have halved; the type, the pool's options and the manual now say half-width."
+      },
+      {
+        "kind": "fixed",
+        "short": "A bone too short for a body no longer cuts a ragdoll in two: what hangs below it is jointed to the bone above, and stops colliding with the bones it meets there.",
+        "text": "A rig often puts one joint exactly on another, a collar on the chest joint or a helper on the hips, and a bone shorter than `minLength` gets no body. What hung below such a bone was jointed to nothing, because a bone was jointed to the bone ending at its parent joint and that joint had none: in a limp fall the spine above a collar flew 3.9 m off the hips. And it collided with every bone it met at that point, because the shared-end rule compared parent joints by index, so capsules out of one point separated whichever way rounding said and a reaction depended on which way the character faced. A short bone is now transparent: each joint resolves to the nearest one above it that a body ends at, for jointing and for collision alike, and where a short bone lies between, the joint is anchored where the two bones meet at rest, so a still doll does not move on its first tick."
+      },
+      {
+        "kind": "fixed",
+        "short": "A ragdoll draws every bone under a joint on its own body, so after a fall a second thigh or a clavicle no longer hangs off the body beside it.",
+        "text": "`writePose` turned a joint by its first bone below and placed every child by the rig's offset from that turn, so at a joint with several bones below it, hips over a spine and two thighs, a chest over a neck and two clavicles, every branch but the first was swung by the first one's rotation and drawn off its own body. Reported from a game as a foot 0.24 m and an arm 0.17 m from their bodies after a fall; a test fall measured a thigh 97.5 cm out. Each joint is now placed along its own bone as that bone's body holds it, at the rig's length and in the parent's frame, which for the first branch is the rig's offset exactly. Lengths never stretch. A joint with no bone of its own keeps the rig's offset."
+      },
+      {
+        "kind": "added",
+        "short": "`setSurfaceFog(false)` takes the next opaque draws out of the fog, so a floor can recede into the medium while figures standing on it keep their colour.",
+        "text": "Opaque draws could not opt out of the medium: `drawTranslucentMesh` had `fog: false` and the shader a per-draw switch, and nothing reached it for `drawMesh`. A ported game darkening its floor with distance had to darken its figures with it, or leave the far floor 18% too bright. `setSurfaceFog(enabled)` is a surface dial like `setSurfaceGrain`: material state for the draws that follow, read by instanced and skinned draws too, and restored by `bindMeshPass`. A translucent draw's own `fog` is measured against it and puts it back. Verified on both backends with two identical far pillars, one fogged and one not, and a pane between them asking for fog under the dial."
+      },
+      {
+        "kind": "added",
+        "short": "`outputTransform: 'shoulder'` keeps sRGB's midtones and eases only the highlights, by their brightest channel, so an overbright red stays red instead of turning pink.",
+        "text": "A fourth output transform. `'srgb'` clips each channel at 1, so an overbright colour shifts hue on its way to white: `(1.6, 0.4, 0.2)` clips to `(1, 0.4, 0.2)`, pinker and wider. `'shoulder'` leaves everything below 0.8 alone and eases the brightest channel toward 1, as `0.8 + 0.2e / (e + 0.2)` of an excess `e`, scaling the other two with it, so the same colour becomes `(0.96, 0.24, 0.12)`. It is the curve a ported game's own resolve applies, and it has none of ACES's toe or desaturation. One definition shared by the forward passes and the resolve, measured on both backends with the composite on and off: `(250, 134, 97)` against sRGB's `(255, 170, 124)`."
+      },
+      {
+        "kind": "added",
+        "short": "Materials take `uOffset` and `vOffset`, so one quad draws any cell of a flipbook or an atlas, and a cutout's shadow is cut from the same cell.",
+        "text": "`SurfaceMaterial` had a UV scale and no offset, so a flipbook could not choose its cell through the material and a game built one quad mesh per cell, 106 meshes for four strips. `uOffset` and `vOffset` are added after the scale, `uv * scale + offset`, for every map of the material, and they reach the cutout depth and shadow passes, so a card's shadow has the holes of the cell its colour shows. Both backends, mesh and instanced draws."
+      },
+      {
+        "kind": "added",
+        "short": "`AudioGraph.restart(fromSec)` starts every stem from a point in the track, locked together, for music held to a game's own clock.",
+        "text": "The transport could only go back to the top, so music held to a frame counter, which has to resume where that counter is after a skip, ran its own source into the music bus outside every stem's lock. `restart(fromSec)` stops the stems and starts them all from that point at one instant, wrapped by each stem's length, and returns how long until it is heard. `restart()` is unchanged."
+      },
+      {
+        "kind": "changed",
+        "short": "A sound slot registered without a synth is required: if none of its files loads, `load` rejects naming it, after every other slot has loaded.",
+        "text": "Every slot had to carry a synthesised stand-in, which is right for a footstep and wrong for a score that has to be the file or nothing, so such a score was decoded outside the registry. `SoundSource.synth` is optional now. A slot without one is required: when none of its candidates loads it is listed in `unbuilt`, and `load` still settles every other slot before rejecting with an error naming each missing required slot and the files it tried. A slot with a synth behaves as before."
+      },
+      {
+        "kind": "fixed",
+        "short": "A WebSocket or WebRTC transport reads a text frame as its UTF-8 bytes, and counts a frame it cannot read as dropped, where both vanished in silence.",
+        "text": "`WebSocketTransport` and `WebRtcTransport` discarded any message that arrived as a string, without counting it in `dropped`, on the ground that a payload through UTF-8 loses its high bytes. That is true of binary data sent as text and not of a peer that speaks text: a text frame is lossless UTF-8 by the protocol, and a client against a server sending text received nothing at all. Text now arrives as exactly the bytes the sender wrote, anything else unreadable is counted, and both transports share the one rule."
+      }
+    ]
+  },
+  {
+    "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/README.md

@@ -6,7 +6,7 @@ carries the loop, the renderer, cameras, input, the scene graph, geometry, text
 and the whole of [`@driftengine/physics`](https://driftengine.dev/docs/simulation/rigid-bodies),
 which it re-exports. The rest of the engine is separate packages you add when you need them.
 
-**Cost: 699.0 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`,
+**Cost: 710.5 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`,
 which fails the build if the figure drifts by more than 3%.
 
 The manual is at **[driftengine.dev/docs](https://driftengine.dev/docs)**, with an example running

package/dist/index.d.ts

@@ -277,6 +277,8 @@ 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 { SCENE_ALPHA_COVERS, SCENE_ALPHA_KEEPS, SCENE_ALPHA_TRANSMITS, blendCovering, blendKeeping, blendTransmitting, } from './render/sceneCoverage.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 +309,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,14 @@ 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';
+/*
+ * **What a contributed pass's blended draw does to the scene's alpha**, which carries how much of
+ * each pixel is still the opaque surface: the share the composite's ambient occlusion may darken.
+ * A pass blending into the scene states one of these for its alpha. See `sceneCoverage.ts`.
+ */
+export { SCENE_ALPHA_COVERS, SCENE_ALPHA_KEEPS, SCENE_ALPHA_TRANSMITS, blendCovering, blendKeeping, blendTransmitting, } from './render/sceneCoverage.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/materialChanges.d.ts

@@ -27,8 +27,13 @@ export interface DrawMaterialOptions {
     /** Whether the draw refracts this time, which a backend decides by whether it has a snapshot. */
     readonly refracting: boolean;
 }
-/** Whether a draw's options differ from the pass's, so it takes a material and leaves one to restore. */
-export declare function ownsMaterial(options: DrawMaterialOptions): boolean;
+/**
+ * Whether a draw's options differ from the pass's, so it takes a material and leaves one to restore.
+ *
+ * `passFog` is how the surfaces around it meet the medium — `FOG_RECEDE` unless `setSurfaceFog`
+ * turned it off — so a translucent draw asking for what the pass already has takes nothing.
+ */
+export declare function ownsMaterial(options: DrawMaterialOptions, passFog?: number): boolean;
 /** Whether the next draw shares the open material or opens a new one. */
 export declare class MaterialChanges {
     /**

package/dist/render/backend/materialChanges.js

@@ -18,11 +18,16 @@
  * slot on the backend that keeps slots, and comparing every field would cost more than the slot.
  */
 import { FOG_RECEDE } from './drawFog.js';
-/** Whether a draw's options differ from the pass's, so it takes a material and leaves one to restore. */
-export function ownsMaterial(options) {
+/**
+ * Whether a draw's options differ from the pass's, so it takes a material and leaves one to restore.
+ *
+ * `passFog` is how the surfaces around it meet the medium — `FOG_RECEDE` unless `setSurfaceFog`
+ * turned it off — so a translucent draw asking for what the pass already has takes nothing.
+ */
+export function ownsMaterial(options, passFog = FOG_RECEDE) {
     return (options.opacity < 1 ||
         !options.lit ||
-        options.fog !== FOG_RECEDE ||
+        options.fog !== passFog ||
         !options.toneMapped ||
         options.refracting);
 }