@driftengine/core 3.63.0 → 4.0.0

package/CHANGELOG.json

@@ -1,4 +1,115 @@
 [
+  {
+    "version": "4.0.0",
+    "date": "2026-09-20",
+    "entries": [
+      {
+        "kind": "changed",
+        "short": "A video becomes a scene, the engine runs without a browser, and the editor opens. Five new packages, a GPU driven pipeline, worlds past float precision, and 769 public symbols added, none removed.",
+        "text": "**This is a major version for what it adds, not for what it breaks.** Five packages are new — `capture`, `native-host`, `nav`, `texture` and `tools` — alongside an `editor` application workspace, bringing the tree to twenty-three packages. Across every package barrel, **769 public symbols were added and none were removed**, so a game built against 3.63.0 compiles against this unchanged.\n\n**What is in it, in one paragraph.** A GPU-driven pipeline behind one option, and a frame graph under the renderer. Temporal reconstruction, and indirect light that falls back through a bounded world-space field rather than guessing off the edge of the screen. Worlds larger than single precision can address, streamed by where the camera is about to look, with terrain that decides its own detail and a navigation mesh across it. Textures as compiled programs over a latent rather than images, with residency predicted instead of reacted to. An editor that opens, scrubs the simulation backwards, and lets a scene be edited while it runs. The engine on a native window with no browser in the process. And a video of a room becoming a scene with colliders, materials and proposed entities, on the player's own device.\n\n**What a consumer owes the upgrade is the bump itself.** A release moves `version` in twenty-five manifests, the sixty-nine internal `@driftengine/*` ranges that pin the packages to each other, and `package-lock.json` — ninety-five places. That count was ninety-three in this repository's own notes until it was counted rather than read, immediately before this release, and answered two more.\n\nNothing here moves the `driftscript` pin, which is a published package on a version line this repository does not own."
+      },
+      {
+        "kind": "added",
+        "short": "The editor opens. npm run editor gives a menu bar, a viewport, docked panels, picking, a gizmo, undo and a command palette, on the browser and on a native window.",
+        "text": "**`npm run editor` and it is there.** A menu bar, a viewport, docked panel slots, selection by picking, delete, undo, redo, select-all and a command palette. Every edit is a `Command` on a stack, so a panel cannot touch the world except through something the stack can put back.\n\n**`app.ts` is the general shell and `shell.ts` is the product**, which is a deviation from the design and the right one: assembling a product into the reusable shell would make it depend on a selection model. The dock is a binary tree of splits with one panel per region, and `panels/docked.ts` is the single seam that closes a `Panel<W, V>`'s generics and owns the title strip.\n\n**The gizmo is the editor's arithmetic rather than core's, and the reason is a conditioning number.** Core translates by the closest point between the ray and the axis line, which is right and refuses only within `1e-6` of parallel; between that cutoff and a comfortable angle the answer divides by the squared sine, so **two degrees off the axis multiplies a pixel of mouse noise by 820**. A drag here is computed against a plane containing the axis, chosen per drag as the one whose normal most faces the camera: the two candidates are orthogonal, so the conditioning is never worse than **√2** where a fixed choice reaches a billion four times a turn. An axis pointing at the camera has no good plane at all, so the drag is refused rather than invented. Commands carry absolute positions rather than deltas, which is what makes the merge contract's trap harmless: applying an absorbed command twice writes the same position twice, where a delta would move the object twice as far as the pointer and read as a sensitivity bug.\n\n**What it does not do is in `editor/README.md` rather than left to be found**: there are no tabs and no splitter dragging, and nothing paints the gizmo's arms."
+      },
+      {
+        "kind": "added",
+        "short": "Play in editor, and a scrubber that runs the simulation backwards. Scrub to any recorded frame and play forward again, frame-for-frame identical to a run that never scrubbed.",
+        "text": "**Press play, press stop, and the scene is exactly as it was** — the oldest defect an editor has. `editor/src/pie/session.ts` captures the world before the first step and restores it on stop, checked by a digest of the whole world rather than a spot check of a few fields. Advancing and stepping are different verbs: a loop calls `advancePie` every frame and it does nothing while paused, and a person presses step and gets exactly that many frames and a session still paused. The world arrives through `Snapshotter`, the engine's own seam, so nothing here knows what a world is.\n\n**Scrub the simulation backwards to any recorded frame, and forward again unchanged.** A keyframe every _n_ frames plus the input log between reconstructs any frame exactly, because the simulation is deterministic. The assertion that matters is the second one: scrub back, play forward, and compare against a run that never scrubbed, frame for frame. **A scrubber that perturbs the simulation is worse than none**, because it produces a version of the bug that is not the bug. A frame the ring has dropped is reported as gone and never as the nearest one.\n\n**Change something at frame four hundred and the rest happens differently.** `editDuringPlay.ts` records the edit and re-simulates from its frame rather than applying it on the spot, which is one path instead of two and the only arrangement under which scrubbing away and back keeps the change. The edit is the same `Command` an inspector emits at rest, so it is undoable and there is no second way to write the world. Editor edits stay out of the input log, because an editor command is not something a peer sends.\n\n**And when two runs stop agreeing, the frame and then the component.** `divergence.ts` binary-searches the per-frame fingerprints and `@driftengine/tools` compares the per-component hashes at that frame. Three things are reported as themselves rather than as a number meaning something else: agreement is not frame zero, no overlap is not agreement, and a whole-world difference no recorded component accounts for is said plainly.\n\n**What this cost is the shortest honest summary of the determinism work.** A timeline, a slider, and the rule that an edit during play goes into the log. Snapshots, rewind, input logs, deterministic replay and fingerprints all shipped already, for the netcode."
+      },
+      {
+        "kind": "added",
+        "short": "@driftengine/tools, 3,395 gzipped bytes: a shipped game can carry the editor inspector, console, profiler and network panel, with the command stack that makes their edits undoable.",
+        "text": "**A game can ship the editor's panels, and a game that does not pays nothing.** `@driftengine/tools` is the inspector, the console, the profiler and the network panel, with the command stack that makes their edits undoable, at **3,395 bytes gzipped**.\n\n**The line is what a panel needs, not what it shows.** A scene tree and an asset browser want a project, and a shipped game has none, so those stayed in the editor. `Panel.route` returns a `Command` or nothing, so an in-game inspector edit goes onto an undo stack without the game arranging anything.\n\nEvery other package's size floor is unchanged by this one existing, which is the argument rather than a claim about tree-shaking."
+      },
+      {
+        "kind": "added",
+        "short": "A node graph canvas over three vocabularies: materials compile to a DTEX decode program, particles to the pool options the engine already takes, and behaviour to DriftScript source.",
+        "text": "**One editor over three node vocabularies**, in `editor/src/graph/`. Nodes and links with a cycle refused by name and by node; every edit a command, including a node drag, which merges into one undo entry; a canvas that pans and zooms about the pointer.\n\n**The hit test is handed no view at all.** `buildGraphGeometry` turns graph space into screen space once, into arrays, and both the draw and the hit test read those arrays — because the commonest defect in a graph editor is a hit test that disagrees with the draw about the pan or the zoom, and the only way to prevent it for good is to leave no second place that could apply a transform. Automatic arrangement reads the graph and never the current positions, so tidying is not path-dependent.\n\n**A material graph's compile target is a `DTEX` decode program, not a shader** — the fact a reader most needs and least expects. A texture was already defined as a small interpreted decode program, so a material graph is a visual editor for exactly that structure: a graph-authored material and a baked one are indistinguishable downstream, and the graph editor is a debugger for baked materials as a side effect. A node the vocabulary cannot express grows the decode vocabulary, which costs bytes linearly because an operation is data.\n\n**A particle graph compiles to the `ParticlePoolOptions` the engine already takes**, plus the emission the pool has never owned, so a compiled graph is two records rather than a third representation to keep in step. Randomness is a seed and never the global generator. A curve is two numbers, because two is what `ParticlePool` interpolates between, so a preview agrees with the frame. Capacity is derived from rate × life rather than typed in.\n\n**A behaviour graph emits DriftScript source, and DriftScript's own compiler is what judges it.** The graph gets no semantics, no effect analysis and no hot reload of its own, which is what makes a graph and hand-written code the same artefact and lets a project mix them. A graph **can** write a component it never declared, and the real compiler refuses it with DS0288 in the words a person hand-writing that file would get.\n\n**Each vocabulary ships one honest refusal.** `separate` is in the material palette and deliberately does not compile, because splitting a colour into channels is the first node somebody reaches for that this genuinely cannot do; `turbulence` is the particle vocabulary's."
+      },
+      {
+        "kind": "added",
+        "short": "A script editor in the editor, backed by the DriftScript language server rather than a second implementation of the language. It works with no client attached at all.",
+        "text": "**DriftScript is edited against the language server that already exists, not a second language implementation.** `editor/src/panels/script.ts` is a text view, a diagnostic gutter and a completion popup; every rule about what the language means stays with the compiler, which is the same line the behaviour-graph editor holds and for the same reason.\n\n**It works with no client at all** — a headless build has none and a test has none, so it is a text view before it is anything else.\n\n**The server's view of the buffer lags it by a message**, so a diagnostic arrives describing text already deleted every time somebody types quickly. Ranges are clamped, and one entirely past the end collapses to an empty mark at the end rather than disappearing, because the server has something to say and dropping it loses the only sign that it did. **Nothing awaits the server**: a change notification goes out and the buffer is already updated, and a completion reply arriving after a dismissal is dropped rather than reopening a popup over text somebody went back to typing."
+      },
+      {
+        "kind": "added",
+        "short": "@driftengine/capture: a video becomes a scene you can walk around in, on the player device and with no service. Depth and poses, a fused surface, colliders, a navmesh and proposed entities.",
+        "text": "**A clip becomes a surface, on the device, with no service.** `@driftengine/capture` takes a `FrameSource` — a video element in a browser, ffmpeg on the native host — chooses frames, runs Depth Anything 3 Small for poses, depth, intrinsics and a confidence together, fuses the views into a truncated signed-distance volume, marches it and decimates the result. Then `collisionMesh` makes it something a `CharacterController` stands on, a navigation mesh bakes from the same surface, `delight` separates what the surface reflects from the light it was photographed under, and `segmentGeometry` and `proposeEntities` cut it into regions and say what each might be.\n\n**The same stages run in both hosts with nothing in the package changed between them.** Measured 2026-09-20 on an RX 9070 XT over six frames of a 1,401-frame 1080p handheld clip: **7.2 s in the browser and 9.05 s on the native host**, of which 3.6 s and 5.5 s are loading the weights. A room came back as 33,060 triangles over 1.08 × 0.70 × 1.08 m, with one navigation polygon and eight entity proposals, in a 1.09 MB file.\n\n**Its maturity is stated rather than implied, stage by stage, because a reconstruction that looks finished and is not costs a consumer more than one that says so.** Geometry reconstructs what a clip saw from where the clip saw it and nothing more. Colliders hold where the capture has a surface, and the capture does not have one everywhere: dropping a controller from a metre above over a three-by-three grid, **three of nine landed on it and six fell through**, which is the reconstruction being patchy rather than the colliders failing. Delighting recovers colour and says how much it trusts it, and on ordinary footage that is not much — a mean confidence of **0.276** on a wooden table and **0.249** on a room. It cannot remove a cast shadow, because a shadowed point is shadowed from every camera and agreement is not evidence of albedo. Entity proposals arrive unlabelled and undecided: a person accepts or rejects each one in the editor, and the file records decisions rather than guesses.\n\n**Three limits ship as limits.** **Six frames is the ceiling on this device** and ten is refused with an invalid pipeline layout. **The metric scale is not verified**: no capture in this record contained an object of known size, so the metres are the model's claim rather than a measurement. And delighting is the most expensive stage by thirty times — **44 s over 16,670 triangles and 179 s over 33,060** — because it ray-casts each vertex against every triangle with no acceleration structure. Colour is per vertex, so its detail ceiling is the mesh rather than the footage.\n\n**Each model definition is held to the upstream's own code on a seeded miniature**, rather than to a picture that looks about right: Depth Anything 3 agrees to **3 parts per million**, Depth Anything V2 to 7.8e-7, MobileSAM to 3.1e-6, SAM 2.1 to 7.4e-6, and OWLv2 to 4.1e-6 with its box prior held bit for bit. An unread weight is refused, so a branch this engine sets aside is set aside by name.\n\n**The package floor is 66,373 gzipped bytes**, built up a stage at a time so the bill is legible: the largest single step is the Gaussian fit at 5,336, and the assembly step's 7,683 is `@driftengine/drft`'s whole writer rather than this package's code.\n\n**No weights are distributed with this engine.** `tools/capture-weights/` fetches each model at the revision its manifest pins, verifies it and converts it; a game that ships one ships it under that model's own licence, and `CREDITS.md` and `NOTICE` carry the attribution. The runtime never fetches."
+      },
+      {
+        "kind": "added",
+        "short": "@driftengine/native-host runs the engine on Node, Dawn and SDL with no browser and no engine code changed, and draws the published scenes pixel-identically to Chrome.",
+        "text": "**The engine on a native window and a native WebGPU device, with no browser between them.** `@driftengine/native-host` supplies the page a game expects around its canvas — a window, a GPU, events, gamepads, audio — and **no engine code changed to make it work**. A game's whole contract is one export: the manifest's `native.entry` names a module exporting `mount(canvas)`.\n\n**All nine published scenes come back 0 of 776,960 pixels against Chrome**, checked by `npm run native:gate`. Measured on an RX 9070 XT: **730 ms median from spawn to first frame** — 275 ms to reach the game's `mount`, 355 to build a WebGPU renderer and 85 to its first frame — in a **61.3 MB** archive. Of that 355 ms the adapter and the device are 30; the rest is pipelines the binding has no cache for, which Chrome builds warm in 75 ms, and that gap is recorded as an absent capability rather than smoothed over.\n\n**This is what the platform rule was written for.** Nothing under `src/` may call a platform API directly when a consumer might want a different one, and until a second host existed that rule was held by review. Every platform touch this host had to answer was a capability the caller supplies or a page global, never a call buried in the engine. What each host can do that the other cannot is recorded both ways in `docs/CAPABILITIES.md` §2a, the host's side guarded by a `present` block so a capability cannot quietly go.\n\n**Four defects in it were found by a person at the machine and by no gate**, which is worth publishing because the shape recurs. A first key press was reported as an auto-repeat: the code read `(event.repeat ?? 0) !== 0`, which is right for the number the platform's types declare and inverted for the boolean it actually gives, so held keys were discarded while tapped keys still worked. **Two automated checks confirmed it working**, because a replayed key carries the number `0`, which coerces correctly. Two platform handles were closed twice, each ending the process. A keyboard's power-key endpoint enumerated as a gamepad and took the first pad slot; a device with no axes and no hats is not offered as one now.\n\n**And the editor on this host painted its interface after `endFrame`**, which survives on WebGL2 and vanishes on WebGPU: 0 pixels above black after, 1,747,114 before, with one line moved. It was invisible to every capture, because a readback reads the canvas texture and a texture that is never presented still reads back perfectly.\n\nWindows and macOS are not built yet; the Linux target is."
+      },
+      {
+        "kind": "added",
+        "short": "@driftengine/texture and the DTEX chunk: a texture as a compiled decode program over a latent rather than an image, streaming by tile with a content hash so identical tiles share a payload.",
+        "text": "**A material in the container as a decode program over a latent, rather than as pictures.** `@driftengine/texture` is the interpreter and `drft/src/dtex.ts` is the chunk: the latent grid, the channel specs, the graph's nodes, a small network's shape and weights, and a tile table with a **content hash** per tile so two identical tiles share one payload.\n\n**The chunk carries no semantics.** `@driftengine/drft` has no dependencies and does not know what an operation means, so the types are plain arrays that `@driftengine/texture`'s satisfy structurally — the arrangement `Terrain` already has with `Heightfield` across the physics boundary. **It validates containment, not meaning**: a tile whose bytes run past the payload and a result register no node writes are refused, because those hand a reader arbitrary memory or an uninitialised value. Those guards are unreachable through the writer, so the tests corrupt a written chunk to reach them.\n\n**No per-chunk version**, which is where it departs from its design: the file's version covers the format and a second one is a second thing to keep in step. It is additive, so an older reader skips it by its length and loses only the material it could not have decoded.\n\n**And a texture cannot move the simulation, asserted rather than left true by construction.** A run sampling an animated `DTEX` every tick fingerprints identically to a run sampling nothing, and the same simulation run twice at different wall-clock times fingerprints identically, because `t` is the caller's, from the simulation's clock. A run that reads a wall clock instead is asserted to **diverge**, without which the first two pass for a decoder that reads a clock nobody noticed."
+      },
+      {
+        "kind": "added",
+        "short": "Texture streaming that decides residency from where the camera will be, not where it has been. Measured on a scripted flight: 296 late samples predicted against 1,294 reactive.",
+        "text": "**Residency is decided by looking at where the camera _will_ be.** The state of the art is reactive by construction — the most widely deployed implementation's own documentation says streaming is reactive by nature, because nothing can know a tile is needed until a frame has already needed it. That is true of an engine that cannot run its simulation forward and put it back. This one does it every frame, for the netcode.\n\n`predictViews` saves, advances _n_ deterministic steps with no rendering, samples which tiles those views want, and restores. **No feedback buffer and no readback**, so it works for passes that could never write feedback. What those views want is `tilesForView`'s answer: each instance inside a predicted view names the level its nearest point asks for, the finer one within an eighth of a level of a boundary, and every coarser one a sampler falls back to, most important first — so the answer at any budget is a prefix of the answer with none.\n\n**Measured on a scripted flight down a corridor of real latents, 452 tiles through a 256-page cache and never more than 102 in a frame: 296 late samples predicted against 1,294 reactive**, and the 296 are exactly the three frames before the first fetch could possibly have landed.\n\n**Mispredicting degrades rather than fails, and that is asserted rather than claimed.** A camera reversing every three frames is what prediction cannot help with, and the cost is a wasted fetch and a late tile, which is what a reactive engine does on every frame. Measured on that flight: **102 late samples predicted against 755 reactive**. The floor of this mechanism is everyone else's ceiling.\n\n**A tile that will not arrive stops being waited for.** A fetch resolving with nothing leaves the tile requested and its in-flight slot occupied forever if nobody handles it, and a handful of those stops streaming entirely with no error anywhere. A missing tile is remembered as missing, a rejection is treated identically, bytes larger than a page are refused rather than truncated, and a fetch landing after its tile was evicted is dropped.\n\n**And the decode can move from per-sample to residency time**, which is the fallback the design named before the risk could arrive: decode once when a tile becomes resident and sample it as an ordinary texture after. That loses procedural and per-sample parameterisation for the affected materials and keeps the compression, the joint channels and the streaming."
+      },
+      {
+        "kind": "added",
+        "short": "Runtime-writable textures that survive replay. A scorch mark goes into the input log, so a recording plays back the same burnt wall instead of a clean one.",
+        "text": "**A scorch mark is in the input log, so a replay burns the same wall.** Runtime-mutable textures normally break replay: the marks are not part of the simulation and nothing records them, so a recording plays back clean walls and nothing fails at the time.\n\n`overlay/sparse.ts` allocates only the tiles a mark touched and tracks written per texel **and** per channel; `overlay/journal.ts` records every write beside the input. **Rolling back is rebuilding from the journal**, because a write is not invertible — two marks on one texel leave no record of what was underneath. The journal is truncated on rollback, or a replay draws both what happened and what was undone."
+      },
+      {
+        "kind": "added",
+        "short": "@driftengine/nav, 8,401 gzipped bytes: geometry becomes walkable convex polygons and a straight line across them. It reverses a refusal that had named its own trigger.",
+        "text": "**`@driftengine/nav` ships, at 8,401 bytes gzipped, and it reverses a refusal that named its own trigger.** `core/src/nav/navGraph.ts` states that it is a graph rather than a mesh, that this is a decision rather than a first step, and that a mesh is the row that is still open if a world's walkable space is genuinely a region. A streamed open world is that world.\n\nGeometry becomes a walkable voxel field — two layers under an overhang, which is why it is voxels and not a heightfield — then a watershed partition, contours checked for self-intersection rather than assumed simple, and convex polygons whose adjacency is symmetric. A one-directional build makes paths work in one direction only and nothing says so.\n\n**One A\\* in the repository**: the query builds a `NavGraph` and hands it to core's existing `NavSearch`, then funnels, so open ground is a straight line and not a walk along polygon centres. The graph is not replaced; it stays right for roads, corridors and docking lanes.\n\n**Two limitations ship with a test pinning each.** A region with a free-standing pillar loses the inner loop, so an agent walks through the pillar; and the funnel gives the shortest path through the corridor A\\* chose, 10.75 against an ideal 9.81 on one wall.\n\n**Steering is still refused**, which is the line the reversal did not cross: a path is a function of geometry and an engine can own one, but how a character moves along it is a game's feel."
+      },
+      {
+        "kind": "added",
+        "short": "A world bigger than a float. Simulation coordinates stay absolute and double; only rendering rebases, in whole cells, so a replay fingerprint cannot depend on where the camera stood.",
+        "text": "**The simulation never rebases; rendering does.** `core/src/world/` holds a sparse cell grid, a render origin that follows the camera in whole cells, and the rule that keeps them apart: simulation coordinates stay absolute and double, because a rebase would change floating-point results and therefore the replay fingerprint — only in sessions that crossed an origin boundary, which is a divergence nobody reproduces on demand.\n\n**The origin moves in whole cells**, since a continuously moving one re-quantises every vertex every frame and the world shimmers: measured over a 220-tick walk at the far end of the world, it moves **75 times rather than 220**. A round trip through render space costs an ulp of a number under five hundred and **does not grow with distance**, where the same coordinate put into single precision is wrong by **exactly one metre** at 2²⁴–2²⁵, because single precision counts in twos there.\n\n**Cells stream by where the camera will look, not only by where it will be.** `cellsInFrustum` walks the box round a predicted view's corners in double precision and keeps a cell unless it lies wholly beyond one plane: 33,554 km out, it tells a sliver a tenth of a metre inside the view from one a tenth outside, which planes held in single precision keep both of.\n\n**Freezing is a simulation decision and unloading is a memory one**, and `world/freeze.ts` keeps them apart on purpose. A cell outside the simulated radius freezes whether or not its contents are resident, and only a frozen cell may be unloaded, so streaming can change where the bytes live and never what the simulation computes. The alternative — unloading causing freezing — makes the simulation depend on how much memory a machine had, which is a divergence that appears on one player's computer and nowhere else. **A frozen cell still contributes to the fingerprint**, from a digest taken when it froze, because a run that agrees only once everything has thawed is a run that disagreed for a while. What it costs is stated rather than discovered: an agent in an unloaded cell does not walk anywhere, does not age and does not finish what it was doing."
+      },
+      {
+        "kind": "added",
+        "short": "Terrain decides its own detail per patch in one pass, and a heightfield is stored as a DTEX layer. Collision reads the decoded heights, so the renderer and the query cannot disagree.",
+        "text": "**Which squares of the field to draw, at what detail, as one decision per patch.** `terrain/src/clipmap.ts` takes a camera and a patch index and answers, reading the frame and nothing else — which is what lets it move into a compute pass beside the cluster cut rather than be rewritten there.\n\nEach level's block snaps to an **even** patch index, which is the whole of why the levels nest: an even multiple of a level's patch span is a multiple of the next level's, so a finer block's edge always falls on a coarser patch boundary. **The hole a finer level leaves is not fixed at the centre**, which looks wrong and is right: levels re-centre at different moments, so culling by coverage rather than by a central hole is what removes the need for the L-shaped stitching strip the usual implementation carries. Asserted by counting: **65,536 field cells drawn, exactly, at every one of thirty-three camera positions across a coarse patch** — an area equal to the footprint with no cell counted twice is no overlap and no hole, together.\n\n**A heightfield is a `DTEX` layer, and collision reads the decoded numbers rather than the source ones.** Terrain inherits the format's residency, streaming and determinism instead of growing an image path of its own. **The design had the requirement backwards**: it asked that decoded heights match the source within the format's tolerance, which they do and which is not enough — a renderer reading the layer while a query reads the source differ by exactly that tolerance, everywhere, permanently, and a character floating by a fraction of a millimetre on every surface in the world is a defect nobody attributes. So `terrainFromHeightLayer` builds the `Terrain` from the decoded samples and everything reads that one object.\n\nSplat weights decode renormalised, since four weights rounded to eight bits sum to between 0.994 and 1.006, and a shader that trusts the sum shades a whole hillside wrong, smoothly enough to read as lighting."
+      },
+      {
+        "kind": "added",
+        "short": "Hierarchical detail, baked offline: a distant block of a city is one coarse mesh and a distant tree is its own picture. A proxy that would not be cheaper is refused rather than shipped.",
+        "text": "**A distant block of a city is one coarse mesh, and a distant tree is its own picture.** `assets/src/bake/hlod.ts` builds both offline. The proxy is not a new mesh merger — `coarseLevel.ts` already emits the boundary of an occupancy grid rather than decimating a surface, which is what stops a merge growing triangles through a car's bodywork — so what is new is the grouping and the level schedule.\n\n**A proxy can be refused, and that is the honest half.** A grid-based merge cannot promise fewer triangles than its input, because its output scales with surface area rather than with triangle count, so the half-budget is checked and a group that is already cheap gets `null` instead of something larger than what it replaced.\n\n**The impostor's hard part is its edges.** Colour is dilated past the silhouette and every tile carries a two-texel gutter, because a transparent texel left at the clear colour is what makes a distant tree glow at its atlas seams. Measured on a tree at eight directions a side: **1.0000 silhouette agreement on a baked direction and 0.9083 between two**, since the blend carries no parallax correction and the fix costs the square of the direction count."
+      },
+      {
+        "kind": "added",
+        "short": "DriftTR, an analytic temporal reconstruction tier on WebGPU, off by default. At ratio 1.5 the gilded chamber costs 2.42 to 2.49 ms of GPU against 3.08 to 3.15 with it off.",
+        "text": "**DriftTR, the analytic tier, ships on WebGPU and is off by default.** `quality.reconstruction` takes a ratio from 1.3 to 2.0, and anything outside it is off. The world draws at the output size divided by that ratio, jittered along a Halton sequence of eight phases for every output pixel a render pixel covers, and a compute resolve accumulates it into the output: history read bicubically where the surface was, clipped to its neighbourhood's variance box in YCoCg, refused where depth, motion or normals say it is another surface, and sharpened inside the range of its neighbours.\n\nCamera motion comes from the frame's depth; a draw that states its previous transform or skin palette is drawn again into a motion target. A contributed pass is handed the frame's jitter through `PrepareContext.jitter`, and the GPU-driven pipeline and splats draw with it.\n\n**Measured on the gilded chamber at 1280 by 607, three runs each: 3.08 to 3.15 ms of GPU off, 2.62 to 2.69 at 1.3, 2.42 to 2.49 at 1.5 and 2.16 at 2.** `recon-parity.mjs` holds the resolve's WGSL to its reference over seven frames, `ghost-check.mjs` measures a moving object under a still camera and `pan-check.mjs` a moving camera over a still world, and **a replay fingerprints the same with it on at every ratio as with it off**.\n\nA multisampled frame is not reconstructed, and says so once. The learned tier and frame generation are not in this release and are recorded as absent."
+      },
+      {
+        "kind": "added",
+        "short": "A GPU-driven pipeline behind createRenderer({ pipeline: gpu-driven }), opt-in and WebGPU only. It refuses on a backend without indirect draws rather than falling back quietly.",
+        "text": "**The GPU-driven pipeline is opt-in, WebGPU only, and refuses rather than falls back.** `createRenderer({ pipeline: 'gpu-driven' })` on a backend without indirect draws throws with the reason in words, checked against the backend that will _draw_ rather than the one that was asked for — three of the paths into that decision arrive having already fallen back from WebGPU.\n\nInstance culling, a level cut, a depth reduction, cluster culling, a near-plane refusal, compaction into one draw, a visibility buffer, material binning, surface reconstruction, the lit expression, the shadow lookup, the gradient a compute invocation has to assemble for itself, the octahedral probe mapping, the DriftTexture decode interpreter and the surface frame a textured pixel is read with, and the network evaluator in single and half precision.\n\n**Every pass is written twice** — once in TypeScript as the reference and once in WGSL — and `scripts/gpu-parity.mjs` runs twenty checks requiring the two to agree on a real device. **Until 2026-09-17 that was one short**: the instance cull was checked on the device and never dispatched by the pass, so every cluster of a mesh wholly outside the view was cut and tested one by one. It is a stage of the frame now, and the eighteen scenes are 0 of 921,600 pixels against the build before it.\n\n**Its scene streams, and keeps no copy of what it uploads.** The pass first built its scene in a method whose constructor said the geometry does not move — and a voxel world streams chunks as a player walks and remeshes one on every block they break. Vertices and indices now go through a `GeometrySink` straight into the device's buffers when a mesh is placed, because holding them as well doubled what a world costs and, at the voxel sandbox's radius 32, the copy was an `ArrayBuffer` Chrome will not allocate. **There is one path and not two**: the static case is a scene filled once and never emptied, asserted to pack byte for byte the way the old builder did, because two paths would mean the draft rigs exercise the path no published scene uses, which is how a control stops being a control.\n\n**Timings are a range rather than a number, because the device clock is quantised.** Four captures of each rig land on multiples of about 0.065 ms and nothing between them, so a single frame's figure is a bucket and quoting one is quoting the low end of a distribution."
+      },
+      {
+        "kind": "added",
+        "short": "Indirect light as three levels that fall back to each other and never off the end: the screen, a world-space distance field, and a probe volume. CPU-side, and no scene draws differently.",
+        "text": "**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.\n\n`traceIndirect` takes a ray and a `GiResources` and answers from the best level that can; `GI_SOURCE_SCREEN`, `GI_SOURCE_FIELD` and `GI_SOURCE_PROBES` say which one did, so a caller can see the fallback rather than infer it. A scene that wants indirect light and declared no grid is given one that fits it.\n\n**It is 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** — 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. It is exported anyway, because a capability with no route out of its package is one the first consumer finds by failing a boundary test."
+      },
+      {
+        "kind": "added",
+        "short": "A frame graph under the renderer: a recording arena, a resource table, a scheduler and a replay, none of which import a backend, so the scheduling is proven by assertion rather than a picture.",
+        "text": "**The frame's pure half.** `core/src/render/frame/` holds the recording arena, the resource table, the scheduler and the replay, and **imports neither backend** — which is what lets the scheduling be proven by assertion rather than by a picture.\n\nA node declares what it touches, by bit where a mask has bits and by identifier when it has run out of them, and a transient resource knows when it is born and when nothing needs it again. `FrameResource` and `PassTimings` are the public surface; the rest stays under `render/`, because nothing outside it may reach in yet and saying so is cheaper than discovering a consumer who did."
+      },
+      {
+        "kind": "added",
+        "short": "A compute shader can be tested. gpuCompute.mjs runs WGSL on a real device and reads the buffers back, from a loopback server, because navigator.gpu is not exposed on about:blank.",
+        "text": "**`packages/core/scripts/gpuCompute.mjs` runs WGSL on a real device and reads the buffers back**, which is what lets the GPU-driven pipeline's arithmetic have a test at all. Before it, the WGSL half had nothing but a generator check that confirms a committed file matches its source — which says nothing about whether the arithmetic is right.\n\n**It serves its own page from a loopback server**, because `navigator.gpu` is not exposed on `about:blank` and `http://localhost` is a secure context. There is no dev server to start first.\n\n`scripts/gpu-parity.mjs` runs the passes over generated input and requires agreement: **256 spheres with 149 culled, 256 clusters with 58 selected, and a 37×21 depth pyramid reduced to 18×10** — an odd size on purpose, because the extra row and column are what a reduction gets wrong. Both answers must occur in each case, or the agreement is between two constants. **The check was audited by breaking the WGSL five ways** — the reversed-Z minimum, the conservative direction of the cull, the second half of the cut rule, the plane normalisation and the odd-row fold — and it caught all five."
+      },
+      {
+        "kind": "note",
+        "short": "What 4.0.0 does not do, stated as deliberately as what it does: no texture atlas or metric anchor on a capture, no learned reconstruction tier, and a proof suite deferred out of this release.",
+        "text": "**This project treats an absence as a deliverable**, and `docs/CAPABILITIES.md` §2 names a sentinel symbol per absent row — the symbol that would exist if the work had landed — so the suite goes red on the day one arrives rather than the documentation going quietly stale.\n\n**DriftCapture's three.** There is no texture atlas: colour is one value per vertex, so the detail ceiling is the mesh rather than the footage. There is no delighting prior, so a grey object on a grey floor has no chromaticity to tell shading from paint. And there is no metric anchor: no clip in this record contained an object of known size, so the scale is the model's claim rather than a measurement.\n\n**Reconstruction ships its analytic tier only.** The learned tier and frame generation inside the frame are not here.\n\n**Screen-space global illumination stays refused in writing**, for the reason given when it was first refused: its error is unbounded. What ships instead falls back through a bounded world-space field to a probe volume.\n\n**A proof suite was planned for this release and deferred out of it**, deliberately, so that what is in 4.0.0 is what has been run rather than what was scheduled.\n\n**Two things in this release have been used by one person and no more**: the editor, which nobody who did not write it has opened, and the native host on Windows and macOS, which is not built at all. The Linux target is."
+      }
+    ]
+  },
   {
     "version": "3.63.0",
     "date": "2026-09-14",

package/NOTICE

@@ -7,3 +7,23 @@ This product includes software developed at Drift Technologies
 Licensed under the Apache License, Version 2.0. Section 4(d) of that licence
 requires this NOTICE to be reproduced in any derivative work you distribute,
 in the source, the documentation, or a display generated by the work.
+
+Models run by DriftCapture
+--------------------------
+DriftCapture runs the models below. Their weights are not in this repository
+and are not distributed with it: tools/capture-weights/ fetches each at the
+revision its manifest pins, verifies it, and converts it, and a game that
+ships one ships it under that model's own licence. Each model's definition in
+this engine is written from its project's published code.
+
+- Depth Anything 3 Small and Depth Anything 3 Base. Apache License 2.0.
+  Copyright (c) 2025 ByteDance Ltd. and/or its affiliates.
+- Depth Anything V2 Small. Apache License 2.0. The University of Hong Kong
+  and TikTok; converted to the Transformers layout by The HuggingFace Team.
+- MobileSAM. Apache License 2.0. Its image encoder is TinyViT, Copyright (c)
+  2022 Microsoft; its prompt encoder and mask decoder are Segment Anything's,
+  Copyright (c) Meta Platforms, Inc. and affiliates.
+- SAM 2.1 tiny. Apache License 2.0. Copyright (c) Meta Platforms, Inc. and
+  affiliates.
+- OWLv2 base patch16. Apache License 2.0. Copyright 2023 Google AI and The
+  HuggingFace Team.

package/README.md

@@ -2,7 +2,7 @@
 
 The runtime everything needs: renderer, loop, camera, input, geometry. Collision and dynamics live in [`@driftengine/physics`](../physics/README.md), which this package depends on and re-exports whole, so reaching for them through this barrel works as it always did.
 
-**Cost: 670.0 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`, which fails if it drifts more than
+**Cost: 698.4 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`, which fails if it drifts more than
 3% — the number is a fact about the build rather than a claim in a document.
 
 Part of [DriftEngine](../../README.md). See [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md)

package/dist/core/loop.js

@@ -3,7 +3,19 @@ import { framesHeld } from './bootGate.js';
 export function startLoop(hooks, options = {}) {
     const fixedDt = options.fixedDt ?? 1 / 60;
     const maxFrameTime = options.maxFrameTime ?? 0.25;
-    let last = performance.now();
+    /**
+     * When the last frame arrived, on the timebase the frames themselves use.
+     *
+     * **Null until the first frame whenever a source was supplied, because that source owns the
+     * timebase and this loop has no way to ask what it is.** Seeding from `performance.now()`
+     * regardless is what this did, and for the window it is right — a `DOMHighResTimeStamp` and
+     * `performance.now()` share an origin. For anything else it mixes two clocks: the synthetic
+     * session in `@driftengine/xr` counts from its own zero, so the first delta became sixteen
+     * milliseconds minus a process uptime, the accumulator went as negative as that, and the
+     * simulation stopped ticking until it climbed back — one dead frame per sixteen milliseconds the
+     * process had been alive. A caller that supplies the frames supplies the timebase.
+     */
+    let last = options.frameSource === undefined ? performance.now() : null;
     let accumulator = 0;
     /**
      * Fixed steps taken, offset by `startTick`.
@@ -23,13 +35,17 @@ export function startLoop(hooks, options = {}) {
      * another, because the two run at different rates and share no accumulator worth carrying across.
      */
     const source = options.frameSource ?? {
+        // platform: browser default — `LoopOptions.frameSource` is the seam
         requestAnimationFrame: (callback) => requestAnimationFrame(callback),
         cancelAnimationFrame: (handle) => {
+            // platform: browser default — as above
             cancelAnimationFrame(handle);
         },
     };
     const frame = (now, xrFrame) => {
         rafId = source.requestAnimationFrame(frame);
+        /* The first frame of a supplied source establishes the origin, so it advances nothing. */
+        const previous = last ?? now;
         /*
          * **Held: draw nothing, advance nothing, and bank nothing.**
          *
@@ -48,7 +64,7 @@ export function startLoop(hooks, options = {}) {
             accumulator = 0;
             return;
         }
-        let frameDt = (now - last) / 1000;
+        let frameDt = (now - previous) / 1000;
         last = now;
         const wallDt = frameDt;
         if (frameDt > maxFrameTime)

package/dist/core/storage.js

@@ -35,6 +35,7 @@ export class BrowserStore {
         if (!this.available)
             return this.fallback.read(key);
         try {
+            // platform: browser default — `KeyValueStore` is the seam; see `MemoryStore` beside it
             return localStorage.getItem(key);
         }
         catch {
@@ -46,6 +47,7 @@ export class BrowserStore {
         if (!this.available)
             return;
         try {
+            // platform: browser default — as above
             localStorage.setItem(key, value);
         }
         catch {
@@ -57,6 +59,7 @@ export class BrowserStore {
         if (!this.available)
             return;
         try {
+            // platform: browser default — as above
             localStorage.removeItem(key);
         }
         catch {
@@ -69,7 +72,9 @@ function probeLocalStorage() {
         // Reading is not enough of a probe: some browsers allow the read and throw
         // only on write, which would strand a store that reports itself healthy.
         const probe = '__driftengine_probe__';
+        // platform: feature probe — a blocked store must be found by trying it
         localStorage.setItem(probe, '1');
+        // platform: feature probe — as above
         localStorage.removeItem(probe);
         return true;
     }

package/dist/geometry/meshBuilder.d.ts

@@ -332,7 +332,7 @@ export declare class MeshBuilder {
      */
     addBlob(center: Vec3, radiusAt: (u: number, v: number) => number, color: Vec3 | ((u: number, v: number) => Vec3), emissive?: number, segments?: number, rings?: number, specular?: number): this;
     /** A sphere, which is a capsule with no shaft. */
-    addSphere(center: Vec3, radius: number, color: Vec3, emissive?: number, segments?: number, rings?: number): this;
+    addSphere(center: Vec3, radius: number, color: Vec3, emissive?: number, segments?: number, rings?: number, specular?: number): this;
     /** Add a faceted cylinder aligned to one principal axis. */
     addCylinder(center: Vec3, radius: number, halfLength: number, axis: 'x' | 'y' | 'z', color: Vec3, emissive?: number, segments?: number, specular?: number): this;
     /**

package/dist/geometry/meshBuilder.js

@@ -678,8 +678,12 @@ export class MeshBuilder {
         return this;
     }
     /** A sphere, which is a capsule with no shaft. */
-    addSphere(center, radius, color, emissive = 0, segments = 12, rings = 6) {
-        return this.addCapsule(center, radius, 0, color, emissive, segments, rings);
+    addSphere(center, radius, color, emissive = 0, segments = 12, rings = 6, 
+    /* `addCapsule` has taken one since it existed; forwarding it is what was missing, and a
+       sphere that cannot carry the specular a box can is the reason no page here could draw a
+       polished surface under a direct light. */
+    specular = 0) {
+        return this.addCapsule(center, radius, 0, color, emissive, segments, rings, specular);
     }
     /** Add a faceted cylinder aligned to one principal axis. */
     addCylinder(center, radius, halfLength, axis, color, emissive = 0, segments = 12, specular = 0) {

package/dist/index.d.ts

@@ -5,7 +5,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';
@@ -54,8 +54,8 @@ export { PickableSet } from './render/pickable.ts';
 export type { PickHit, PickableSource } from './render/pickable.ts';
 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';
 export { SceneNode } from './scene/node.ts';
@@ -66,12 +66,67 @@ export type { PassContext, PassDefinition, PassDevice, PassHandle, PrepareContex
 export type { PassAttachmentOptions, PassTarget } from './render/passTarget.ts';
 export { generateMipChain, mipLevelCount, type MipPipelines, } from './render/backend/webgpu/surfaceTexturePass.ts';
 export { createPassAttachment } from './render/passTarget.ts';
+export { jitterClip } from './render/recon/jitter.ts';
 export type { FrameResource } from './render/frame/index.ts';
 export type { OcclusionOptions } from './render/occlusion.ts';
 export { OcclusionBuffer } from './render/occlusion.ts';
 export type { ComputeContext, ComputeDefinition, ComputeDevice, ComputeHandle, } from './render/compute.ts';
 export { createRenderer } from './render/backend/createRenderer.ts';
-export type { CreatedRenderer, CreateRendererOptions } from './render/backend/createRenderer.ts';
+export type { CreatedRenderer, CreateRendererOptions, RenderPipeline, } from './render/backend/createRenderer.ts';
+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';
+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';
+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';
+export { openInferenceDevice } from './render/inference/device.ts';
+export type { InferenceDevice } from './render/inference/device.ts';
+export { createGraphRunner } from './render/inference/runner.ts';
+export { planReuse } from './render/inference/reuse.ts';
+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';
+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';
 export { GRADE_PLACEHOLDER_SIZE, MAX_GRADE_SIZE, identityGradeLut } from './render/colourGrade.ts';
 export type { ColourGradeLut } from './render/colourGrade.ts';
 export { probeDevice } from './render/backend/probe.ts';
@@ -195,6 +250,7 @@ export type { ColliderSurfaceOptions } from './physics/colliderSurface.ts';
 export { BoxSurface } from './physics/boxSurface.ts';
 export { heightSurface } from './physics/heightSurface.ts';
 export { DebugLines } from './render/debugLines.ts';
+export { rayClosestOnLine, rayPlane, raySphere } from './math/intersect.ts';
 export { GIZMO_GROUP_ACTIVE, GIZMO_GROUP_COLORS, GIZMO_GROUP_COUNT, GIZMO_GROUP_NEUTRAL, GIZMO_GROUP_X, GIZMO_GROUP_Y, GIZMO_GROUP_Z, GIZMO_NONE, GIZMO_ROTATE_X, GIZMO_ROTATE_Y, GIZMO_ROTATE_Z, GIZMO_SCALE_UNIFORM, GIZMO_SCALE_X, GIZMO_SCALE_Y, GIZMO_SCALE_Z, GIZMO_TRANSLATE_X, GIZMO_TRANSLATE_XY, GIZMO_TRANSLATE_Y, GIZMO_TRANSLATE_YZ, GIZMO_TRANSLATE_Z, GIZMO_TRANSLATE_ZX, Gizmo, gizmoScaleFor, } from './render/gizmo.ts';
 export type { GizmoMode, GizmoSpace } from './render/gizmo.ts';
 export { RainField } from './render/rainField.ts';
@@ -253,6 +309,8 @@ export { CONTACT_LIMIT, createContactReports, describeContacts } from './dev/con
 export type { ContactReport } from './dev/contactProbe.ts';
 export { GPU_SLOTS, GpuTimer } from './render/gpuTimer.ts';
 export type { GpuSample, GpuSlot } from './render/gpuTimer.ts';
+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';
@@ -288,3 +346,10 @@ 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';
+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/dist/index.js

@@ -3,7 +3,7 @@
 export { startLoop } from './core/loop.js';
 export { StepBudget } from './core/stepBudget.js';
 export { hashToUnit, mulberry32, pickBySeed, savableMulberry32 } from './core/rng.js';
-export { exactAcos, exactCos, exactExp, exactSin } from './math/exact.js';
+export { exactAcos, exactCos, exactExp, exactLog, exactSin } from './math/exact.js';
 export { TickTrace } from './core/tickTrace.js';
 export { BrowserStore, MemoryStore, defaultStore } from './core/storage.js';
 /* The same seam over a backend that answers later, with the queue, the retry and the status. */
@@ -60,7 +60,7 @@ export { MAX_DEPTH_LAYER, Renderer, WebGL2Renderer } from './render/backend/webg
 export { PickableSet } from './render/pickable.js';
 /* 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.js';
-export { createFrustum, frustumFromViewProjection, sphereInFrustum } from './math/frustum.js';
+export { boxInFrustum, createFrustum, frustumFromViewProjection, sphereInFrustum, } from './math/frustum.js';
 export { boundsVisible } from './render/visibility.js';
 export { apparentSize, lodForBounds } from './render/lod.js';
 /* A transform hierarchy. Additive: nothing in the renderer knows a node exists. */
@@ -79,6 +79,11 @@ export { createVisitResult, visitVisible } from './scene/visit.js';
  */
 export { generateMipChain, mipLevelCount, } from './render/backend/webgpu/surfaceTexturePass.js';
 export { createPassAttachment } from './render/passTarget.js';
+/*
+ * 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.js';
 export { OcclusionBuffer } from './render/occlusion.js';
 /*
  * `Renderer` above stays exported and is not deprecated. `createRenderer` is the way to get
@@ -87,6 +92,80 @@ export { OcclusionBuffer } from './render/occlusion.js';
  * take one.
  */
 export { createRenderer } from './render/backend/createRenderer.js';
+/*
+ * 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.js';
+/*
+ * **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.js';
+export { buildGpuDrivenScene } from './render/gpudriven/sceneUpload.js';
+/*
+ * **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.js';
+export { packDecodeTables, programFromEncoded } from './render/gpudriven/decodeTables.js';
+/*
+ * **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.js';
+export { createGraphRunner } from './render/inference/runner.js';
+/* 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.js';
+/* 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.js';
+/**
+ * **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.js';
+export { GLOBAL_FIELD_BLEND, composeGlobalField, createGlobalField, sampleGlobalField, } from './render/gi/globalField.js';
+export { GI_SCREEN_MARCH, SCREEN_TRACE_BIAS_M, screenRayOrigin, traceScreen, } from './render/gi/traceScreen.js';
+export { FIELD_MARCH, coneRadiusAt, newFieldHit, traceField } from './render/gi/traceField.js';
+export { PROBE_VISIBILITY_SHARPNESS, bakeProbeVisibility, createProbeVisibility, probeUpdateSchedule, probeVisibilityWeight, sampleProbeVolume, visibleProbes, } from './render/gi/probeVolume.js';
+export { DENOISE_MIN_ALPHA, filterStepFor, newTemporalPixel, spatialDenoise, temporalDenoise, } from './render/gi/denoise.js';
+export { reflectDirection, reflectionCone, traceReflection } from './render/gi/reflection.js';
+/*
+ * 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.js';
+export { DistanceFieldScene, MAX_DISTANCE_FIELDS } from './render/gi/fieldScene.js';
+export { placeCascade } from './render/gi/globalField.js';
 /*
  * 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
@@ -225,6 +304,13 @@ export { DebugLines } from './render/debugLines.js';
  * 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.js';
 export { GIZMO_GROUP_ACTIVE, GIZMO_GROUP_COLORS, GIZMO_GROUP_COUNT, GIZMO_GROUP_NEUTRAL, GIZMO_GROUP_X, GIZMO_GROUP_Y, GIZMO_GROUP_Z, GIZMO_NONE, GIZMO_ROTATE_X, GIZMO_ROTATE_Y, GIZMO_ROTATE_Z, GIZMO_SCALE_UNIFORM, GIZMO_SCALE_X, GIZMO_SCALE_Y, GIZMO_SCALE_Z, GIZMO_TRANSLATE_X, GIZMO_TRANSLATE_XY, GIZMO_TRANSLATE_Y, GIZMO_TRANSLATE_YZ, GIZMO_TRANSLATE_Z, GIZMO_TRANSLATE_ZX, Gizmo, gizmoScaleFor, } from './render/gizmo.js';
 export { RainField } from './render/rainField.js';
 export { coveredAbove } from './physics/heightSurface.js';
@@ -286,6 +372,21 @@ export { bakeOverlay, drawPixelText, pixelTextCells, pixelTextSize } from './ui/
 export { FpsMeter } from './dev/fpsMeter.js';
 export { CONTACT_LIMIT, createContactReports, describeContacts } from './dev/contactProbe.js';
 export { GPU_SLOTS, GpuTimer } from './render/gpuTimer.js';
+/*
+ * 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.js';
 export { classifyRightGesture } from './input/rightGesture.js';
 export { createWindState, sampleWind } from './render/wind.js';
 export { advanceWindField, createWindField } from './render/windField.js';
@@ -329,3 +430,12 @@ export { parseSdfFont } from './render/sdfFont.js';
 export { DEFAULT_SDF_TEXT_STYLE, SdfTextLayout } from './render/sdfTextLayout.js';
 export { WindStreakRenderer } from './render/windStreakRenderer.js';
 export { buildTree } from './geometry/treeBuilder.js';
+/*
+ * 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.js';
+export { renderOrigin, toRenderSpace, toWorldSpace } from './world/rebase.js';
+export { cameraPositionFrom, cellPredictor, createCellStream, pumpCellStream, setCellStreamOrigin, } from './world/cellStream.js';
+export { createFrozenCells, freezeCell, frozenEntities, frozenFingerprintContribution, isCellFrozen, thawCell, } from './world/freeze.js';