@driftengine/core 3.62.0 → 4.0.0

package/src/index.ts

@@ -6,7 +6,7 @@ export type { LoopHooks, FrameSource, LoopOptions } from './core/loop.ts';
 export { StepBudget } from './core/stepBudget.ts';
 export type { StepBudgetOptions } from './core/stepBudget.ts';
 export { hashToUnit, mulberry32, pickBySeed, savableMulberry32 } from './core/rng.ts';
-export { exactAcos, exactCos, exactExp, exactSin } from './math/exact.ts';
+export { exactAcos, exactCos, exactExp, exactLog, exactSin } from './math/exact.ts';
 export type { SavableRandom } from './core/rng.ts';
 export { TickTrace } from './core/tickTrace.ts';
 export type { TickTraceLike } from './core/tickTrace.ts';
@@ -120,8 +120,13 @@ export type { PickHit, PickableSource } from './render/pickable.ts';
 /* How big a piece of geometry is, which everything that culls or picks a detail level starts from. */
 export { boundsOfBox, boundsOfPositions, createBounds } from './math/bounds.ts';
 export type { Bounds } from './math/bounds.ts';
-export { createFrustum, frustumFromViewProjection, sphereInFrustum } from './math/frustum.ts';
-export type { Frustum } from './math/frustum.ts';
+export {
+  boxInFrustum,
+  createFrustum,
+  frustumFromViewProjection,
+  sphereInFrustum,
+} from './math/frustum.ts';
+export type { Frustum, FrustumPlanes } from './math/frustum.ts';
 export { boundsVisible } from './render/visibility.ts';
 export { apparentSize, lodForBounds } from './render/lod.ts';
 /* A transform hierarchy. Additive: nothing in the renderer knows a node exists. */
@@ -158,7 +163,27 @@ export type {
  * write to the frame stays refused while a write to a pass-owned target does not is written out.
  */
 export type { PassAttachmentOptions, PassTarget } from './render/passTarget.ts';
+/*
+ * The mip chain a pass has to build for itself on WebGPU, and the level count it needs to ask for.
+ *
+ * **Public because `gl.generateMipmap` has no WebGPU equivalent and every contributed pass that
+ * uploads a texture meets that the moment its texture is ever minified.** `ui2d` met it with a
+ * glyph atlas baked at 96 px and drawn at 11; writing the blit a second time there would have been
+ * a second WGSL shader to keep in step with this one, and the copy that quietly disagrees about
+ * the colour space is the one that would ship. `MipPipelines` is an interface rather than the
+ * renderer's cache so a pass can hand over a `Map` and nothing more.
+ */
+export {
+  generateMipChain,
+  mipLevelCount,
+  type MipPipelines,
+} from './render/backend/webgpu/surfaceTexturePass.ts';
 export { createPassAttachment } from './render/passTarget.ts';
+/*
+ * What a pass drawing the world does with `PrepareContext.jitter`, so a reconstructed frame's
+ * resolve finds its geometry where the renderer's own verbs put theirs.
+ */
+export { jitterClip } from './render/recon/jitter.ts';
 export type { FrameResource } from './render/frame/index.ts';
 /*
  * Occlusion culling, which is arithmetic rather than a GPU feature — so the class is public and a
@@ -191,7 +216,172 @@ export { createRenderer } from './render/backend/createRenderer.ts';
  * one is to write the object inline at the call — which is exactly how a choice ends up
  * duplicated across the several places an application creates a renderer.
  */
-export type { CreatedRenderer, CreateRendererOptions } from './render/backend/createRenderer.ts';
+export type {
+  CreatedRenderer,
+  CreateRendererOptions,
+  RenderPipeline,
+} from './render/backend/createRenderer.ts';
+/*
+ * The second pipeline, as the two things a consumer assembles: the scene packing and the pass
+ * that draws it.
+ *
+ * **Exported here and reached by nobody who does not ask for it.** `pipeline: 'gpu-driven'` on
+ * `createRenderer` is the permission — it fails at boot where the backend cannot run this — and
+ * `GpuDrivenPass` is the implementation, registered the way `@driftengine/splats` registers one.
+ * A consumer who names neither pays nothing: `core-only` is measured with these exported and does
+ * not move, because nothing in the forward path reaches them.
+ *
+ * It draws vertex colour, one directional term, a hemispheric ambient and an emissive add — not
+ * the standard material. `DRAFT_SCENES`, never `SCENES`, until it draws the six published ones.
+ */
+export {
+  GPU_DRIVEN_LISTS,
+  GpuDrivenPass,
+  MATERIAL_FLOATS,
+} from './render/backend/webgpu/gpuDrivenPass.ts';
+export type {
+  GpuDrivenList,
+  GpuDrivenMaterial,
+  GpuDrivenShadowOptions,
+  GpuDrivenView,
+} from './render/backend/webgpu/gpuDrivenPass.ts';
+/*
+ * **One environment, one haze, on both pipelines.** `GpuDrivenView.fog` is the medium the forward
+ * path binds, and a consumer drawing both in one frame fills it from `atmosphereFog` rather than
+ * working the numbers out again — the voxel sandbox's port is the first.
+ */
+export { atmosphereFog, createFogTarget } from './render/fog.ts';
+export type { FogOptions, FogTarget } from './render/fog.ts';
+export { buildGpuDrivenScene } from './render/gpudriven/sceneUpload.ts';
+export type { GpuDrivenMesh, GpuDrivenScene } from './render/gpudriven/sceneUpload.ts';
+/*
+ * **The scene a `GpuDrivenPass` takes**, which is a streaming one since 2026-09-18 — a static
+ * scene is one filled once, so there is a single path rather than two. `buildGpuDrivenScene` stays
+ * exported because it is the packer `streamScene.test.ts` holds the streaming layout to.
+ */
+export { StreamingScene, streamingScene } from './render/gpudriven/streamScene.ts';
+export type {
+  DirtySpan,
+  GeometrySink,
+  StreamCapacity,
+  StreamHandle,
+  StreamUpload,
+} from './render/gpudriven/streamScene.ts';
+export type { ClusterSource } from './render/gpudriven/clusterUpload.ts';
+export { packDecodeTables, programFromEncoded } from './render/gpudriven/decodeTables.ts';
+export type {
+  DecodeTables,
+  EncodedProgramShape,
+  GpuDrivenLatent,
+  GpuDrivenNetwork,
+  GpuDrivenProgram,
+} from './render/gpudriven/decodeTables.ts';
+export type { GpuDrivenTextures } from './render/gpudriven/materialTable.ts';
+/*
+ * **A network graph on a device**: the one neural runtime's device half. `@driftengine/texture`
+ * holds the references and validates a graph; this runs the validated graph, whose shapes it takes
+ * as given, on a device opened from whichever `GPU` the caller has — a browser's or the native
+ * host's Dawn. Exported because the device may not leave `render/`, so a package that runs a
+ * network does so through here or not at all.
+ */
+export { openInferenceDevice } from './render/inference/device.ts';
+export type { InferenceDevice } from './render/inference/device.ts';
+export { createGraphRunner } from './render/inference/runner.ts';
+/* The buffer-reuse rule, exported because `@driftengine/texture`'s evaluator plans by this one
+   rather than by a second copy of it — see `reuse.ts` for why it is on this side of the arrow. */
+export { planReuse } from './render/inference/reuse.ts';
+/* The tile lists a device draws a splat cloud from, beside the shader that walks them. */
+export {
+  countSplatTiles,
+  fillSplatTiles,
+  splatPixelBox,
+  splatTileGrid,
+  splatTileOffsets,
+  SPLAT_BIN_FLOATS,
+  SPLAT_TILE,
+} from './render/inference/splatTiles.ts';
+export type { BufferReuse } from './render/inference/reuse.ts';
+export type { GraphRunner } from './render/inference/runner.ts';
+export type {
+  DeviceAttribute,
+  DeviceGraph,
+  DeviceGraphNode,
+} from './render/inference/deviceGraph.ts';
+/**
+ * **Indirect light, as three levels that fall back to each other and never off the end.**
+ *
+ * `ROADMAP.md` refused screen-space global illumination because its error is unbounded — a ray
+ * that leaves the frame has no answer, and every technique that ships one anyway invents one from
+ * whatever happened to be on screen. This does not reverse that refusal: the screen is an
+ * accelerator with a world-space distance field behind it, whose error is bounded by its own
+ * resolution, and a probe volume behind *that*, which is never wrong and only ever coarse.
+ *
+ * **CPU-side, and reached by nobody who does not ask.** There is no WGSL, no pass and no renderer
+ * option yet, so no scene renders differently for these existing — this wave's first constraint,
+ * measured rather than asserted: the eight published scenes are 0 of 921,600 pixels against the
+ * build before them, and `core-only` is byte-identical with these exported and without them.
+ * Exported anyway, for the reason `bake/cluster.ts` was not: a capability with no route out of its
+ * package is one the first consumer finds by failing a boundary test.
+ */
+export {
+  GI_SOURCE_FIELD,
+  GI_SOURCE_PROBES,
+  GI_SOURCE_SCREEN,
+  newIndirectResult,
+  traceIndirect,
+} from './render/gi/chain.ts';
+export type { GiResources, GiSource, IndirectRay, IndirectResult } from './render/gi/chain.ts';
+export {
+  GLOBAL_FIELD_BLEND,
+  composeGlobalField,
+  createGlobalField,
+  sampleGlobalField,
+} from './render/gi/globalField.ts';
+export type {
+  FieldSource,
+  GlobalField,
+  GlobalFieldCascade,
+  GlobalFieldInstance,
+} from './render/gi/globalField.ts';
+export {
+  GI_SCREEN_MARCH,
+  SCREEN_TRACE_BIAS_M,
+  screenRayOrigin,
+  traceScreen,
+} from './render/gi/traceScreen.ts';
+export { FIELD_MARCH, coneRadiusAt, newFieldHit, traceField } from './render/gi/traceField.ts';
+export type { FieldHit, FieldMarch } from './render/gi/traceField.ts';
+export {
+  PROBE_VISIBILITY_SHARPNESS,
+  bakeProbeVisibility,
+  createProbeVisibility,
+  probeUpdateSchedule,
+  probeVisibilityWeight,
+  sampleProbeVolume,
+  visibleProbes,
+} from './render/gi/probeVolume.ts';
+export type { ProbeVisibility } from './render/gi/probeVolume.ts';
+export {
+  DENOISE_MIN_ALPHA,
+  filterStepFor,
+  newTemporalPixel,
+  spatialDenoise,
+  temporalDenoise,
+} from './render/gi/denoise.ts';
+export type { DenoiseFrame, SpatialOptions, TemporalPixel } from './render/gi/denoise.ts';
+export { reflectDirection, reflectionCone, traceReflection } from './render/gi/reflection.ts';
+/*
+ * The pass that draws the renderer's field on a device. WebGPU only, and it says so at
+ * registration rather than at the first frame: a distance field is composed by compute and WebGL2
+ * has none. It no longer composes one of its own — `addDistanceField` is how a scene declares
+ * what its indirect light may be traced against, and this marches what the renderer made of them.
+ */
+export { GiFieldPass } from './render/backend/webgpu/giFieldPass.ts';
+export type { GiFieldOptions } from './render/backend/webgpu/giFieldPass.ts';
+export { DistanceFieldScene, MAX_DISTANCE_FIELDS } from './render/gi/fieldScene.ts';
+export type { DistanceFieldInstance } from './render/gi/fieldScene.ts';
+export { placeCascade } from './render/gi/globalField.ts';
+export type { ReflectionOptions, ReflectiveSample } from './render/gi/reflection.ts';
 /*
  * The acceptance probe, exported because a consumer may want to ask the question itself — an
  * editor deciding whether to offer a backend, a shell deciding what to tell the player — and
@@ -462,6 +652,13 @@ export { DebugLines } from './render/debugLines.ts';
  * over and what a drag does, and fills line buffers the caller draws with `drawLines`.
  * Nothing here touches a context.
  */
+/*
+ * Ray intersection, exported because a consumer building a tool needs the same arithmetic the
+ * gizmo does. `editor/src/viewport/gizmo.ts` reaching into `src/math/intersect.ts` by path would
+ * be the editor using a private hook, which `ARCHITECTURE.md` treats as a hole in the engine
+ * rather than as the editor's problem — so the hole is closed here.
+ */
+export { rayClosestOnLine, rayPlane, raySphere } from './math/intersect.ts';
 export {
   GIZMO_GROUP_ACTIVE,
   GIZMO_GROUP_COLORS,
@@ -645,6 +842,30 @@ export type { ContactReport } from './dev/contactProbe.ts';
 
 export { GPU_SLOTS, GpuTimer } from './render/gpuTimer.ts';
 export type { GpuSample, GpuSlot } from './render/gpuTimer.ts';
+
+/*
+ * Per-pass timings, which are a readout rather than a frame graph.
+ *
+ * **`render/frame/index.ts` says nothing under it may be reached from outside `render/` yet, and
+ * this module is the exception with a reason.** The rest of that directory is the graph's
+ * construction — declarations, lifetimes, aliasing, scheduling — whose public shape the design
+ * leaves to a later phase, and exporting it now would fix a shape nobody has had to live with.
+ * A timing readout is not that: it is seven functions over three arrays, its own header argues why
+ * it is not a widening of `GpuTimer`, and anything that profiles a frame needs it.
+ *
+ * The editor is what made this concrete. `AGENTS.md`'s rule is that a consumer needing a private
+ * import has found a hole in the engine, and the hole is fixed here rather than worked around
+ * there — which is the whole reason the editor was built outside `packages/`.
+ */
+export {
+  createPassTimings,
+  passLabel,
+  passMs,
+  recordPassLabel,
+  recordPassSample,
+  resetPassTimings,
+} from './render/frame/passTimings.ts';
+export type { PassTimings } from './render/frame/passTimings.ts';
 export { classifyRightGesture } from './input/rightGesture.ts';
 export type { RightGesture, RightGestureOptions } from './input/rightGesture.ts';
 export { createWindState, sampleWind } from './render/wind.ts';
@@ -728,3 +949,39 @@ export type { TreeParams, TreeGeometry } from './geometry/treeBuilder.ts';
 export type { InstanceData } from './render/instancedMesh.ts';
 export type { MeshInstances } from './render/instances.ts';
 export type { WindProfile, WindState } from './render/wind.ts';
+
+/*
+ * Large worlds: the cell grid that streams and freezes, and the origin that rendering rebases
+ * against while the simulation never does. See `world/rebase.ts` for why that asymmetry is the
+ * rule the whole design hangs on.
+ */
+export {
+  cellBounds,
+  cellCoord,
+  cellCoordInRange,
+  cellCoordsOf,
+  cellIdFor,
+  cellIdFrom,
+  cellsInFrustum,
+  cellsInRadius,
+  createCellGrid,
+} from './world/cell.ts';
+export type { CellGrid } from './world/cell.ts';
+export { renderOrigin, toRenderSpace, toWorldSpace } from './world/rebase.ts';
+export {
+  cameraPositionFrom,
+  cellPredictor,
+  createCellStream,
+  pumpCellStream,
+  setCellStreamOrigin,
+} from './world/cellStream.ts';
+export type { CellStore, CellStream, CellStreamOptions } from './world/cellStream.ts';
+export {
+  createFrozenCells,
+  freezeCell,
+  frozenEntities,
+  frozenFingerprintContribution,
+  isCellFrozen,
+  thawCell,
+} from './world/freeze.ts';
+export type { FreezableWorld, FrozenCell, FrozenCells } from './world/freeze.ts';

package/src/input/input.ts

@@ -482,7 +482,12 @@ export class InputSource {
   ) {
     this.target = target;
     this.preventDefaultCodes = new Set(preventDefaultCodes);
-    this.isCoarse = window.matchMedia('(pointer: coarse)').matches;
+    /* Guarded, and `ui/fullscreen.ts` guards the identical query with the identical test. This
+       line is in a constructor, so unguarded it did not degrade a hint — it threw, and an embedder
+       without `matchMedia` could not construct input at all. False is what a runtime with no
+       pointer media query honestly is. */
+    this.isCoarse =
+      typeof window.matchMedia === 'function' && window.matchMedia('(pointer: coarse)').matches;
     this.deadzone = options.deadzone ?? DEFAULT_DEADZONE;
     this.autoPoll = options.autoPoll ?? true;
     for (const name of ['keyboard', 'mouse', 'touch', 'gamepad'] as const) {

package/src/math/exact.ts

@@ -18,9 +18,10 @@
  *
  * ## What is here, and what is deliberately not
  *
- * `exactSin`, `exactCos`, `exactExp`, `exactAcos`. Four, because four is what the engine and its
- * first consumer actually reach for: the terrain binding's slope angle needs `acos`, a lockstep
- * fixture rotating anything needs `sin` and `cos`, and exponential decay needs `exp`.
+ * `exactSin`, `exactCos`, `exactExp`, `exactAcos` and `exactLog`. Five, because five is what the
+ * engine and its first consumer actually reach for: the terrain binding's slope angle needs `acos`,
+ * a lockstep fixture rotating anything needs `sin` and `cos`, exponential decay needs `exp`, and a
+ * detector's box prior is a logit of the patch grid, which needs `log`.
  *
  * **`atan2` is absent.** It is the obvious fifth and nothing here needs one: `shape.ts` sorts by a
  * comparison key computed from two in-plane axes rather than by an angle, and `joints.ts` compares
@@ -239,6 +240,71 @@ export function exactExp(x: number): number {
   return sum * pow2(k);
 }
 
+/* fdlibm's `log` polynomial in s², for log(1 + f) around f = 0 by way of s = f / (2 + f). */
+const LG1 = 6.66666666666673513e-1;
+const LG2 = 3.999999999940941908e-1;
+const LG3 = 2.857142874366239149e-1;
+const LG4 = 2.222219843214978396e-1;
+const LG5 = 1.818357216161805012e-1;
+const LG6 = 1.531383769920937332e-1;
+const LG7 = 1.479819860511658591e-1;
+const TWO54 = 1.8014398509481984e16;
+const SMALLEST_NORMAL = 2.2250738585072014e-308;
+
+/* A double's two words, for reading and setting an exponent; one view, reused. */
+const words = new DataView(new ArrayBuffer(8));
+
+/**
+ * `Math.log`, reproducibly: fdlibm's algorithm, which is also V8's.
+ *
+ * Take the power of two out as `k` and leave a significand in [√2/2, √2), so that `f = m - 1` is
+ * small either side of zero; then log(1 + f) = f - f²/2 + s·(f²/2 + R(s²)) with s = f/(2 + f), and
+ * `k·ln 2` added back in two parts so the large part loses nothing. The exponent is read and the
+ * significand rescaled through the double's own words — integer operations, not transcendentals.
+ */
+export function exactLog(x: number): number {
+  if (Number.isNaN(x) || x < 0) return Number.NaN;
+  if (x === 0) return Number.NEGATIVE_INFINITY;
+  if (x === Number.POSITIVE_INFINITY) return x;
+
+  let k = 0;
+  let value = x;
+  if (value < SMALLEST_NORMAL) {
+    k = -54;
+    value *= TWO54;
+  }
+  words.setFloat64(0, value);
+  let hx = words.getUint32(0);
+  k += (hx >>> 20) - 1023;
+  hx &= 0x000fffff;
+  /* Keep the significand at or above √2/2: past √2, halve it and count one more power of two. */
+  const i = (hx + 0x95f64) & 0x100000;
+  words.setUint32(0, hx | (i ^ 0x3ff00000));
+  k += i >>> 20;
+  const f = words.getFloat64(0) - 1;
+
+  if ((0x000fffff & (2 + hx)) < 3) {
+    /* |f| < 2^-20: two terms of the series are the whole answer. */
+    if (f === 0) return k === 0 ? 0 : k * LN2_HI + k * LN2_LO;
+    const r = f * f * (0.5 - 0.33333333333333333 * f);
+    return k === 0 ? f - r : k * LN2_HI - (r - k * LN2_LO - f);
+  }
+  const s = f / (2 + f);
+  const z = s * s;
+  const w = z * z;
+  const t1 = w * (LG2 + w * (LG4 + w * LG6));
+  const t2 = z * (LG1 + w * (LG3 + w * (LG5 + w * LG7)));
+  const r = t2 + t1;
+  /* Far enough from one that f²/2 is worth carrying apart from f. */
+  if (((hx - 0x6147a) | (0x6b851 - hx)) > 0) {
+    const half = 0.5 * f * f;
+    return k === 0
+      ? f - (half - s * (half + r))
+      : k * LN2_HI - (half - (s * (half + r) + k * LN2_LO) - f);
+  }
+  return k === 0 ? f - s * (f - r) : k * LN2_HI - (s * (f - r) - k * LN2_LO - f);
+}
+
 /** fdlibm's `asin` rational on `z = x²`, valid where `z` is small. */
 function asinRational(z: number): number {
   const numerator = z * (P0 + z * (P1 + z * (P2 + z * (P3 + z * (P4 + z * P5)))));

package/src/math/frustum.ts

@@ -12,6 +12,12 @@ import type { ReadonlyMat4 } from 'gl-matrix';
  */
 export type Frustum = Float32Array;
 
+/**
+ * Planes in either precision. **Double precision is for a world past 2^24 units**, where a plane's
+ * offset is a number a single float cannot hold to the metre; `cellsInFrustum` asks for it.
+ */
+export type FrustumPlanes = Float32Array | Float64Array;
+
 /** Left, right, bottom, top, near, far — the order the extraction below produces. */
 const PLANE_COUNT = 6;
 
@@ -36,7 +42,10 @@ export function createFrustum(): Frustum {
  *
  * gl-matrix stores column-major, so `m[column * 4 + row]`.
  */
-export function frustumFromViewProjection(m: ReadonlyMat4, out: Frustum): Frustum {
+export function frustumFromViewProjection<T extends FrustumPlanes>(
+  m: ReadonlyMat4 | Float64Array,
+  out: T,
+): T {
   const m0 = m[0] ?? 0;
   const m1 = m[1] ?? 0;
   const m2 = m[2] ?? 0;
@@ -71,7 +80,14 @@ export function frustumFromViewProjection(m: ReadonlyMat4, out: Frustum): Frustu
   return out;
 }
 
-function setPlane(out: Frustum, index: number, x: number, y: number, z: number, d: number): void {
+function setPlane(
+  out: FrustumPlanes,
+  index: number,
+  x: number,
+  y: number,
+  z: number,
+  d: number,
+): void {
   const length = Math.sqrt(x * x + y * y + z * z);
   /* A degenerate matrix gives a zero-length normal; leaving it unscaled is better than NaN,
      and the plane then accepts everything, which is the safe direction for a cull to fail. */
@@ -96,7 +112,7 @@ function setPlane(out: Frustum, index: number, x: number, y: number, z: number,
  * a draw that was visible, which is the only asymmetry a cull may have.
  */
 export function sphereInFrustum(
-  frustum: Frustum,
+  frustum: FrustumPlanes,
   x: number,
   y: number,
   z: number,
@@ -113,3 +129,36 @@ export function sphereInFrustum(
   }
   return true;
 }
+
+/**
+ * Whether an axis-aligned box is anywhere inside the frustum, by the same question the sphere test
+ * asks: outside only when wholly beyond one plane.
+ *
+ * **The corner that decides it is chosen per plane** — the one furthest along that plane's normal.
+ * A fixed corner answers correctly for the planes whose normals happen to point its way and culls a
+ * box straddling any of the others. Conservative at the edges, as the sphere test is: a box near a
+ * corner of the frustum can be outside it and still kept.
+ */
+export function boxInFrustum(
+  frustum: FrustumPlanes,
+  minX: number,
+  minY: number,
+  minZ: number,
+  maxX: number,
+  maxY: number,
+  maxZ: number,
+): boolean {
+  for (let plane = 0; plane < PLANE_COUNT; plane += 1) {
+    const at = plane * 4;
+    const nx = frustum[at] ?? 0;
+    const ny = frustum[at + 1] ?? 0;
+    const nz = frustum[at + 2] ?? 0;
+    const reach =
+      nx * (nx >= 0 ? maxX : minX) +
+      ny * (ny >= 0 ? maxY : minY) +
+      nz * (nz >= 0 ? maxZ : minZ) +
+      (frustum[at + 3] ?? 0);
+    if (reach < 0) return false;
+  }
+  return true;
+}

package/src/render/backend/api.ts

@@ -761,7 +761,25 @@ export type RendererApi = Omit<
   updateMesh(mesh: MeshHandle, positions: Float32Array, normals?: Float32Array): void;
 
   /** Draw a handle this renderer made. Passing one from the other backend is a caller error. */
-  drawMesh(mesh: MeshHandle, model: ReadonlyMat4, depthLayer?: number, tint?: Vec3 | null): void;
+  drawMesh(
+    mesh: MeshHandle,
+    model: ReadonlyMat4,
+    depthLayer?: number,
+    tint?: Vec3 | null,
+    /**
+     * Where this mesh's surface was last frame, for a reconstruction's motion target.
+     *
+     * **Only a reconstruction reads it**, and only on WebGPU: it is what turns a moving object's
+     * stale history from a smear into a reprojection. A draw that says nothing gets the camera's
+     * motion, derived from the depth, which is exactly right for anything that did not move and
+     * wrong in proportion to how far a mover moved. Null and omitted mean the same thing.
+     *
+     * It is the *model* matrix this mesh was drawn with last frame, not a velocity: the pass
+     * transforms each vertex twice and lets the perspective divide do the rest, so a rotation and a
+     * scale are as correct as a translation.
+     */
+    previousModel?: ReadonlyMat4 | null,
+  ): void;
 
   /** Release the geometry behind a handle. */
   disposeMesh(mesh: MeshHandle): void;
@@ -800,3 +818,26 @@ export type RendererApi = Omit<
 
 /** Which backend is actually drawing. Reported, never inferred. */
 export type RenderBackend = 'webgl2' | 'webgpu';
+
+/**
+ * Whether this backend can be driven from buffers the GPU itself wrote.
+ *
+ * **A fact about the backend, not a method on this surface, and that is the finding rather than
+ * the shortcut.** Indirect execution needs a render or compute pass encoder, and both are already
+ * in the hands of the code that would use them: `PassContext` hands a contributed pass the
+ * `GPURenderPassEncoder`, and `ComputeDefinition.dispatch` hands a definition the
+ * `GPUComputePassEncoder` while saying in as many words that the workgroup count is the
+ * definition's and does not cross this surface. A `drawIndexedIndirect` here would be a second
+ * way to reach an encoder a caller already holds.
+ *
+ * So what is missing is not a verb. It is an answer to *may I*, which a GPU-driven pipeline has
+ * to ask before it builds an argument buffer nothing can consume.
+ *
+ * **WebGL2 is a refusal rather than an omission.** It has no compute stage to write an argument
+ * buffer and no indirect draw to read one. Emulating it means reading the buffer back to the
+ * processor and issuing the draws from there, which is slower than the ordinary path it would be
+ * pretending to replace — so this reports false and the GPU-driven pipeline is WebGPU-only.
+ */
+export function indirectSupport(backend: 'webgl2' | 'webgpu'): boolean {
+  return backend === 'webgpu';
+}

package/src/render/backend/budget.ts

@@ -1,12 +1,13 @@
 /**
  * What a frame asked of a backend, against what that backend allows.
  *
- * **This exists because a ceiling firing was unobservable.** The WebGPU backend holds ten per-frame
- * ceilings — draws, material changes, overlays, water bodies, light volumes, plumes, three kinds of
- * effect batch and the scatter shadow round — and past any of them it skips the work and writes one
- * `console.warn` for the lifetime of the renderer. WebGL2 holds none of them and draws everything.
- * So a scene over a ceiling renders differently on the two backends, silently, and a consumer
- * developing against WebGL2 has no way to see it coming.
+ * **This exists because a ceiling firing was unobservable.** The WebGPU backend holds fourteen
+ * per-frame ceilings — draws, material changes, two kinds of shadow draw, water bodies, light
+ * volumes, four kinds of effect batch and four kinds of overlay — and past any of them it skips the
+ * work and writes one `console.warn` for the lifetime of the renderer. WebGL2 holds none of them and
+ * draws everything. So a scene over a ceiling renders differently on the two backends, silently,
+ * and a consumer developing against WebGL2 had no way to see it coming — which is why WebGL2 counts
+ * the same fifteen lines by the same rules, and reports the number the other backend rations.
  *
  * **The cost of that was measured from outside.** A consumer spent weeks on ground that
  * vanished and reappeared as the camera moved; its own report still lists, as the decisive