@woosh/meep-engine 3.0.2 → 3.1.0

package/README.md

@@ -35,7 +35,12 @@ While other engines (like Unity) struggle with slow query times and documentatio
 ---
 
 ## ⚡ High-Performance Rendering
-Meep implements a Clustered Forward+ rendering pipeline, allowing for scenes that traditional web engines choke on.
+Meep 3 renders through **Shade**: a GPU-driven, visibility-buffer deferred renderer on **WebGPU**. Geometry is clustered into meshlets ahead of time and lives GPU-resident; culling runs on the GPU; lights are binned into froxels and applied deferred.
+
+**→ [The renderer contract](src/shade/RENDERER_CONTRACT.md)** — what it promises, how to put a model on the screen, and how to add your own work to the frame.
+**Coming from 2.x?** [Migration guide](MIGRATION_2_TO_3.md) · [Changelog](CHANGELOG.md).
+
+* **WebGPU only.** There is no WebGL fallback, no backend abstraction and no degradation tiers. Hardware below the device floor gets a clean failure message rather than a lesser picture.
 
 * **Unlimited Lighting:** Render thousands of point lights (muzzle flashes, explosions, torches) with clustered lighting.
 
@@ -43,7 +48,9 @@ Meep implements a Clustered Forward+ rendering pipeline, allowing for scenes tha
 
 * **Massive Terrain:** Chunk-based, auto-culled terrain system supporting up to 256 layers (vs Unity's 4).
 
-* **"Particular" Particle Engine:** A zero-allocation particle system with full lighting, soft particles, and automatic atlassing. Compiled into just 4 shaders to eliminate state-switching overhead.
+* **"Particular" Particle Engine:** A zero-allocation particle system with full lighting, soft particles, and automatic atlassing, drawn through the renderer's own billboard pipeline.
+
+* **Extensible frames:** Your own work goes into the frame as a *render extension* — a declared phase, declared ordering, and typed per-frame records — rather than as a patch to the pipeline.
 
 * **Path Tracing:** Includes a pure JS path tracer utilizing the engine's internal BVH.
 

package/package.json

@@ -6,7 +6,7 @@
   "description": "Pure JavaScript game engine. Fully featured and production ready.",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "3.0.2",
+  "version": "3.1.0",
   "exports": {
     "./build/*": "./build/*",
     "./src/*": "./src/*",

package/src/engine/grid/grid2transform/GridPosition2TransformSystem.d.ts

@@ -1,6 +1,6 @@
 export class GridPosition2TransformSystem extends System<any> {
     constructor();
-    dependencies: (typeof Transform | typeof GridPosition | typeof GridPosition2Transform)[];
+    dependencies: (typeof Transform | typeof GridPosition2Transform | typeof GridPosition)[];
     components_used: ResourceAccessSpecification<typeof Transform>[];
     data: any[];
     mapPoint: (x: any, y: any, v3: any) => void;
@@ -24,7 +24,7 @@ export class GridPosition2TransformSystem extends System<any> {
 }
 import { System } from '../../ecs/System.js';
 import { Transform } from '../../ecs/transform/Transform.js';
-import GridPosition from '../position/GridPosition.js';
 import { GridPosition2Transform } from './GridPosition2Transform.js';
+import GridPosition from '../position/GridPosition.js';
 import { ResourceAccessSpecification } from "../../../core/model/ResourceAccessSpecification.js";
 //# sourceMappingURL=GridPosition2TransformSystem.d.ts.map

package/src/engine/grid/grid2transform/GridPosition2TransformSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GridPosition2TransformSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/grid/grid2transform/GridPosition2TransformSystem.js"],"names":[],"mappings":"AAWA;IAOI,cASC;IAfD,yFAAiE;IACjE,iEAEE;IACF,YAAU;IAKN,4CAKC;IAGL;;;;;;OAMG;IACH,gBALW,sBAAsB,MACtB,YAAY,aACZ,SAAS,UACT,MAAM,QAgChB;IAED;;;;;;OAMG;IACH,kBALW,sBAAsB,MACtB,YAAY,aACZ,SAAS,UACT,MAAM,QAQhB;IAED,cAeC;CACJ;uBAhGsB,qBAAqB;0BAElB,kCAAkC;yBACnC,6BAA6B;uCACf,6BAA6B;4CALxB,oDAAoD"}
+{"version":3,"file":"GridPosition2TransformSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/grid/grid2transform/GridPosition2TransformSystem.js"],"names":[],"mappings":"AAWA;IAOI,cASC;IAfD,yFAAiE;IACjE,iEAEE;IACF,YAAU;IAKN,4CAKC;IAGL;;;;;;OAMG;IACH,gBALW,sBAAsB,MACtB,YAAY,aACZ,SAAS,UACT,MAAM,QAgChB;IAED;;;;;;OAMG;IACH,kBALW,sBAAsB,MACtB,YAAY,aACZ,SAAS,UACT,MAAM,QAQhB;IAED,cAeC;CACJ;uBAhGsB,qBAAqB;0BAElB,kCAAkC;uCAErB,6BAA6B;yBAD3C,6BAA6B;4CAJV,oDAAoD"}

package/src/engine/physics/fluid/ecs/FluidObstacleSystem.d.ts

@@ -64,11 +64,11 @@ export class FluidObstacleSystem extends System<any> {
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#349@#refresh_masks"(fluid: FluidComponent): void;
+    static "__#348@#refresh_masks"(fluid: FluidComponent): void;
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#349@#clear_field"(fluid: FluidComponent): void;
+    static "__#348@#clear_field"(fluid: FluidComponent): void;
     /**
      * Mark every cell of `fluid` whose centre lies within `inflation` of the
      * posed shape as solid. Iteration is clipped to the shape's world AABB
@@ -80,7 +80,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} inflation       world-units SDF threshold
      * @param {Float64Array} point     length-3 scratch
      */
-    static "__#349@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
+    static "__#348@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
     /**
      * Write the obstacle's translation velocity onto every face of every cell
      * it voxelized — the moving-wall boundary condition. Runs AFTER the mask
@@ -100,7 +100,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} wvy
      * @param {number} wvz
      */
-    static "__#349@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
+    static "__#348@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
     constructor();
     dependencies: (typeof FluidObstacle)[];
     components_used: (ResourceAccessSpecification<typeof Transform> | ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof FluidComponent> | ResourceAccessSpecification<typeof FluidObstacle>)[];

package/src/shade/RENDERER_CONTRACT.md

@@ -0,0 +1,568 @@
+# Shade — the renderer contract
+
+meep 3.0 has one renderer, and this is what it promises.
+
+It is written for somebody who has never seen the inside of it: by the end of §3 you have a model on
+the screen, and by the end of §6 you have your own work in the frame. Everything here is the public
+surface — the types you construct, the calls you make, and the two or three places where the answer
+is "no, and here is why".
+
+If you are looking for how it works rather than what it promises, the design documents are next to
+the code they describe: `renderer/extension/RENDER_EXTENSION_DESIGN.md`,
+`renderer/geometry/virtual/VIRTUAL_GEOMETRY_DESIGN.md`, `renderer/geometry/meshlet/README.md`,
+`renderer/NOTES.md`.
+
+---
+
+## 1. What Shade is
+
+A **GPU-driven, visibility-buffer deferred renderer on WebGPU.** Geometry is clustered into meshlets
+ahead of time and lives in one large GPU buffer; culling runs on the GPU; the rasterizer writes a
+visibility buffer and a G-buffer rather than shading as it draws; lights are binned into froxels and
+applied deferred; and the result is temporally resolved, upscaled, tonemapped and presented.
+
+Three consequences that shape everything below:
+
+- **A mesh is a small GPU-resident record, not a draw call you own.** You add a `Mesh` to a `Scene`;
+  what is drawn, in what order, and whether it is culled is the renderer's.
+- **Preparing geometry is a precompute.** Meshlet building, encoding and BVH construction happen
+  once per geometry. Content that rewrites its vertices every frame goes down a separate path (§8).
+- **The frame is a closed sequence with declared injection points.** You do not insert a pass
+  anywhere; you register an extension against a phase (§6).
+
+### What is deliberately absent
+
+| | |
+|---|---|
+| **No RHI, no backend abstraction** | There is one target, WebGPU. There is no seam where a second one would go, and adding one is not a small change. |
+| **No WebGL fallback** | Below-floor hardware gets a clean failure message (§2), not a degraded picture. |
+| **No degradation tiers** | There is one pipeline. Individual features can be switched off (`feature_shadows_enabled`, `feature_taa_enabled`, the resolution scale), but there is no "low quality" build of the frame. |
+| **No double-sided drawing** | Back faces are always culled. `ShadeMaterial.draw_side` records intent and does not change what is drawn; a surface that must be visible from behind needs its geometry cloned with flipped normals. |
+| **No compressed textures** | DDS, Draco and Basis are not supported anywhere. glTF files carrying `MSFT_texture_dds` load from their base PNG source. |
+
+---
+
+## 2. The device floor
+
+Shade requires a WebGPU device that meets a fixed floor. There is no feature detection beyond it and
+no branch that produces a lesser frame.
+
+**Required features** — the adapter must have both, or startup fails:
+
+- `indirect-first-instance` — indirect draw is used throughout
+- `float32-blendable` — order-independent transparency
+
+**Required limits:**
+
+- `maxStorageBuffersPerShaderStage` ≥ **10** (checked against the adapter before the device is
+  requested, so the failure names the number the adapter offered)
+- `maxColorAttachmentBytesPerSample` ≥ **32** — the G-buffer is wide
+- `maxBufferSize` and `maxStorageBufferBindingSize` are requested at whatever the adapter offers,
+  because the defaults are far too small
+
+**Taken when offered, never required:** `timestamp-query`, `subgroups`, `texture-formats-tier1`.
+`timestamp-query` drives GPU timers and nothing else, and some browsers withhold it on hardware that
+is otherwise fine — so the timers go quiet when it is absent rather than the renderer refusing to
+start.
+
+### When it is not met
+
+`Renderer.initialize()` throws a `ShadeDeviceFailure`, whose `message` is written to be shown to a
+person rather than logged. It distinguishes:
+
+| | |
+|---|---|
+| `webgpu_unavailable` | no `navigator.gpu` — WebGPU disabled or unsupported |
+| `adapter_unavailable` | no adapter at all |
+| `below_floor` | an adapter that does not meet §2, with the detail |
+| `device_request_failed` | the adapter refused the device |
+| `device_lost` | a working device went away while running |
+
+A device lost while running arrives on `Renderer.onDeviceFailure` instead of being thrown. **Shade
+does not recover a lost device.** Everything the renderer built lived on it, and the honest response
+is a message and a reload. The signal exists so an application can say so and save what it has.
+
+---
+
+## 3. Putting a model on the screen
+
+meep has no module aliases: every import is a relative path, and the ones below are written from
+`src/shade/` so they read like the tree in §10.
+
+```js
+import { Renderer } from "./renderer/Renderer.js";
+import { Scene } from "./renderer/scene/Scene.js";
+import { PerspectiveCamera } from "./renderer/camera/PerspectiveCamera.js";
+import { make_sunlight } from "./renderer/light/make_sunlight.js";
+import { load_gltf } from "./renderer/loader/gltf/load_gltf.js";
+import { create_frame_loop } from "./renderer/create_frame_loop.js";
+import { DEG_TO_RAD } from "../core/math/DEG_TO_RAD.js";
+import Vector3 from "../core/geom/Vector3.js";
+
+const canvas = document.querySelector("canvas");
+
+const renderer = new Renderer();
+
+await renderer.initialize({ context: canvas.getContext("webgpu") });
+
+const camera = new PerspectiveCamera();
+
+camera.transform.position.set(0, 2, -5);
+camera.transform.lookAt(Vector3.zero);
+camera.near = 0.1;
+camera.far = 200;
+camera.fov = 72 * DEG_TO_RAD;
+camera.aspect = renderer.aspect_ratio;
+
+const scene = new Scene();
+
+// nothing is lit without one, and the deferred shading pass has no default light
+scene.lights.add(make_sunlight({ intensity: 2.2 }));
+
+const bundle = await load_gltf("model.glb", { assetManager });
+
+scene.add(bundle.scenes);
+
+create_frame_loop(dt => renderer.render(camera, scene, dt));
+```
+
+That is the whole of it. Five things in it are worth stating outright.
+
+**`initialize` is asynchronous and may fail normally.** Acquiring a WebGPU device has no synchronous
+form and being refused one is an ordinary outcome, so it is a rejected promise carrying a
+`ShadeDeviceFailure` rather than a constructor that throws. Omit `context` and a full-viewport canvas
+is created for you; pass a `device` to share one you already have.
+
+**`assetManager` is required, and here is where one comes from.** A glTF is several files — a
+container, its `.bin` buffers, its images — and which of them are already in memory is not the
+parser's business to know. Every request the parse makes goes back through the manager, so they are
+cached, counted and cancellable like anything else the application loads. Two loaders are all
+`load_gltf` asks for:
+
+```js
+const assetManager = new AssetManager({ context: {}, executor: new ConcurrentExecutor() });
+
+await assetManager.registerLoader(GameAssetType.ArrayBuffer, new ArrayBufferLoader());
+await assetManager.registerLoader(GameAssetType.ImageBitmap, new ImageBitmapAssetLoader());
+
+assetManager.startup();
+```
+
+Pass a `scope` alongside it to tie a whole load to one cancellable unit, and a `fileMap` when the
+files come from a drop rather than from the network. An application already running meep's `Engine`
+has a configured manager on it and should use that one.
+
+**A model does not have to come from a file.** Everything `load_gltf` produces you can build
+directly, which is §4 in the other direction and needs no asset manager at all:
+
+```js
+const mesh = new Mesh();
+
+mesh.geometry = meshlet_geometry_build_from_geometry(make_torus_knot_geometry(1, 0.3, 128, 16));
+mesh.material = new StandardShadeMaterial();
+
+mesh.transform_local.setTranslation(0, 1, 0);
+mesh.updateMatrices();
+
+scene.add(mesh);
+```
+
+**`render` returns a boolean.** `false` means the previous frame has not finished and this one was
+not submitted. It is not an error.
+
+**`scene.add` takes a node or an array of them, and it recurses.** Nodes tagged `isLight` are routed
+to `scene.lights`, everything else into `scene.instances`; `scene.remove` mirrors it exactly.
+
+---
+
+## 4. The type model
+
+Everything in a scene is a **`Node3D`**: a TRS transform, a parent and children, and a row in the GPU
+scene-graph. `Scene` is itself a `Node3D` and occupies row 0, so posing the scene world-shifts
+everything under it.
+
+**A node is placed through `transform_local`, and everything else about where it is, is derived.**
+`transform_global` is recomputed from the local transform and the parent chain by `updateMatrices()`,
+which is also what refreshes a `Mesh`'s world-space bounds — so writing `transform_global` directly is
+undone the moment anything refreshes, and mutating `transform_local` without calling
+`updateMatrices()` leaves both the global transform and the bounds stale. A version counter on the
+node records the refresh, and the renderer compares against it.
+
+**A node's transform and a camera's are different types, deliberately, and this is the one place a
+newcomer will trip.** `Node3D.transform_local` is a `Transform64`: a flat `Float64Array` holding its
+own matrix, posed through `setTranslation(x, y, z)` / `setRotation(x, y, z, w)` / `setScale(x, y, z)`,
+with the buffer layout part of its contract so hot code can write it directly. A `Camera` is **not**
+a `Node3D` — it carries meep's ECS `Transform`, whose `position`, `rotation` and `scale` are
+observable vectors you assign into. The two keep distinct shapes on purpose and neither has the
+other's accessors: `node.transform_local.position` is `undefined`, and so is
+`camera.transform.translation`.
+
+```js
+node.transform_local.setTranslation(0, 1, 0);   // Transform64 — then updateMatrices()
+camera.transform.position.set(0, 2, -5);        // Transform    — reactive, no refresh call
+```
+
+```
+Scene  (Node3D, row 0)
+├── lights        LightCollection   — their own pipeline, not in the instance batch
+└── instances     InstanceBatch
+    ├── nodes     every Node3D ever added, in insertion order
+    └── instances the Mesh-bearing subset, which is what the rasterizer iterates
+```
+
+A **`Mesh`** is a `Node3D` plus two fields:
+
+```js
+mesh.geometry  // MeshletGeometry — what to draw
+mesh.material  // ShadeMaterial   — how to draw it
+```
+
+and a world-space `bounding_box` / `bounding_sphere` the renderer keeps for culling.
+
+### Geometry: two types, one of which is a precompute
+
+**`Geometry`** is the authoring form: named `Attribute`s over typed arrays, an optional index, a
+`bounding_box`/`bounding_sphere` computed on demand by `ensureBounds()`, and a `version` you bump
+through `needsUpdate = true` when you rewrite the arrays. Attributes are read by name:
+
+```js
+geometry.getAttribute(StandardAttributes.Position).data   // Float32Array
+geometry.index.data                                       // Uint32Array
+```
+
+Shade ships seven generators, all returning a `Geometry`, in `renderer/geometry/primitives/`:
+`make_box_geometry`, `make_plane_geometry`, `make_polyhedron_geometry`, `make_octahedron_geometry`,
+`make_torus_geometry`, `make_cylinder_geometry`, `make_torus_knot_geometry`.
+
+**`MeshletGeometry`** is the GPU form: triangles clustered into meshlets, attributes encoded, and a
+BVH over the clusters. This is what a `Mesh` carries, and it is what buys cluster culling and a
+compact residency.
+
+```js
+const meshlets = meshlet_geometry_build_from_geometry(geometry);
+```
+
+**That build is a precompute.** Do it once, when the content is created or loaded. If your vertices
+change every frame, you are on the wrong path — see §8.
+
+### Materials
+
+`ShadeMaterial` is the base: `transparency_mode`, `draw_mode`, `draw_side` (which records intent and
+does not change what is drawn — see §1). `StandardShadeMaterial` is the PBR one everything uses:
+
+| | |
+|---|---|
+| `texture_albedo` | base colour, alpha carries transparency |
+| `diffuse_color` | multiplied with the albedo |
+| `texture_normal` | tangent-space normals |
+| `texture_orm` | occlusion / roughness (G) / metalness (B), as glTF packs it |
+| `texture_emissive`, `emissive_factor` | |
+| `roughness_factor`, `metallic_factor` | multiplied with the ORM texture |
+| `transmission_factor`, `ior_factor` | |
+| `ambient_factors` | a `LinearModifier` over the indirect contribution |
+| `vt_stack` | opt-in virtual texturing; when set, albedo/normal/ORM come from streamed pages instead. Opaque materials only |
+
+### Textures
+
+Two objects, and the split matters: **`ShadeImage`** is the pixels, **`ShadeTexture`** is how to
+sample them. Two materials sampling one image differently are two textures over one image, and the
+image is uploaded once.
+
+```js
+const image   = ShadeImage.fromImageBitmap(bitmap);   // or fromSampler2D, or fromArrayBuffer
+const texture = ShadeTexture.from(image);
+
+texture.wrapS = TextureWrapType.Repeat;
+texture.magFilter = TextureFilterType.Linear;
+```
+
+`ShadeTexture` carries filters, wrap modes and flags (mipmap generation is on by default), and both
+types answer `equals`/`hash`, which is what lets the renderer de-duplicate uploads.
+
+### What a glTF becomes
+
+`load_gltf` returns a **`SceneBundle`** — three arrays out of the one file:
+
+```js
+bundle.scenes   // Node3D[]           — the scene roots, ready for scene.add
+bundle.skins    // Skin[]             — for GPUAnimationManager.register_skin
+bundle.clips    // ShadeAnimationClip[] — for register_clip
+```
+
+The bundle is **the model as loaded, not a placement of it.** Adding one bundle's roots to two
+scenes, or twice to one scene, shares nodes. meep's ECS layer provides
+`instantiate_scene_bundle(bundle)` for the copy a second placement needs — its own nodes, its own
+skin and its own retargeted clips — which is what makes two of one model possible.
+
+---
+
+## 5. The frame
+
+```
+FrameStart          view updated, nothing rasterized
+   ↓
+[ visibility buffer + G-buffer ]
+AfterGBuffer        surface properties written and readable, nothing lit
+   ↓
+[ clustered lighting, deferred shading, volumetrics ]
+AfterLighting       opaque lit and composited
+   ↓
+[ transparency ]
+AfterTransparency   the complete scene, HDR, internal resolution
+   ↓
+[ TAA / NSS upscale ]  ← resolution changes here
+BeforePresent       HDR, output resolution, immediately before tonemapping
+   ↓
+[ tonemap → canvas ]
+Overlay             display space, drawing onto the canvas
+```
+
+**The upscale is a phase boundary and it is the one thing about the frame you cannot assume away.**
+Three phases are before it and two are after. With `feature_taa_enabled === false` there is no
+upscale and the two sides are the same size. Nothing in this document states a resolution as a
+constant: ask `frame.resolution`, which is derived from the live handle and is right in every
+configuration, including under dynamic resolution scaling.
+
+---
+
+## 6. Adding your own work to the frame — render extensions
+
+An extension is **a named object with declarations and one method**.
+
+```js
+import { RenderExtension } from "./renderer/extension/RenderExtension.js";
+import { FramePhase } from "./renderer/extension/FramePhase.js";
+import { SceneColor } from "./renderer/extension/SceneColor.js";
+import { ViewTextures } from "./renderer/extension/ViewTextures.js";
+
+class TrailExtension extends RenderExtension {
+    name = "trails";
+
+    phase = FramePhase.AfterTransparency;
+
+    record(frame) {
+        if (this.#batch.count === 0) {
+            // nothing to draw, and the frame's colour is left exactly as it was
+            return;
+        }
+
+        const scene = frame.get(SceneColor);
+
+        scene.color = this.#renderer.graph_draw({
+            graph: frame.graph,
+            batch: this.#batch,
+            color: scene.color,
+            depth: frame.get(ViewTextures).depth,
+            camera: frame.view.camera.buffer
+        });
+    }
+}
+
+const registered = renderer.add_extension(new TrailExtension());
+// ...
+renderer.remove_extension(registered);
+```
+
+That is the whole mechanism. The rest of this section is what the four lines of it mean.
+
+### Records are the channel
+
+`record(frame)` **returns nothing.** Everything an extension exchanges with the frame goes through
+typed **records**: you read a frame-graph handle out of one and write a replacement back, and
+**writing a field is publication** — everything after you carries what you left.
+
+There is no privileged resource. The scene colour is published exactly the way a G-buffer target is,
+and exactly the way a record of your own is.
+
+| record | carried at | writable |
+|---|---|---|
+| `SceneColor` — `.color`, HDR | `AfterLighting` … `BeforePresent` | yes |
+| `GBufferTextures` — `.albedo` (AO in alpha), `.normal`, `.pbr`, `.emissive` | `AfterGBuffer` … `BeforePresent` | **`AfterGBuffer` only** |
+| `ViewTextures` — `.depth`, `.depth_previous`, `.visibility_mesh`, `.visibility_triangle` | `AfterGBuffer` … `BeforePresent` | yes |
+| `PresentTarget` — `.canvas` | `Overlay` only | yes |
+
+Three of those rows are the whole reason phases exist:
+
+- **`SceneColor` is not carried at `Overlay`.** A texture may not be a render attachment and a
+  sampled source in the same pass, so at `Overlay` the canvas is written and cannot be read. An
+  effect that needs the finished image as *input* — a colour grade, a full-screen re-composite —
+  belongs at `BeforePresent`. You find that out from `frame.get(SceneColor)`, which fails with a
+  sentence naming the phases that do carry it, rather than from a `-1` failing inside a binding
+  builder.
+- **`GBufferTextures` is in/out at `AfterGBuffer` and frozen afterwards.** Changing surface
+  properties means reading the targets, writing replacements and publishing the new handles — two of
+  the four are integer formats and cannot be blended, and nothing can be attachment and source at
+  once. It stays *readable* to `BeforePresent` because outline and selection effects legitimately
+  read it late; at that phase it is on the far side of the upscale and is therefore **a different
+  size from the colour beside it**. `frame.describe(handle)` is how a pass working across that
+  boundary learns the ratio.
+- **`PresentTarget` has one field and is not called `SceneColor` on purpose.** There is no colour
+  there to be tempted by. Keep the existing contents with a `load` op, write only your own pixels,
+  and publish the result back — that is what lets two overlay extensions compose.
+
+### Extending the vocabulary
+
+An extension can publish a record of its own for another extension to read, and doing so costs no
+edit to Shade:
+
+```js
+class VisibilityGrid extends FrameRecord {
+    #grid = -1;
+
+    static is_present_at(phase) { return true; }
+
+    get grid() { return this.read(this.#grid); }
+    set grid(handle) { this.#grid = this.publish(handle); }
+}
+
+// at FrameStart
+frame.create(VisibilityGrid).grid = record_the_grid_update(frame.graph);
+
+// at AfterTransparency, in another extension
+if (frame.has(VisibilityGrid)) { … frame.get(VisibilityGrid).grid … }
+```
+
+`has` / `get` / `create` are three calls rather than one `get_or_create` because **absent has to stay
+distinguishable from empty.**
+
+### Ordering
+
+Order is **declared**, never emergent:
+
+```js
+class DecalExtension extends RenderExtension {
+    phase = FramePhase.AfterGBuffer;
+    after = [TerrainSplatExtension];   // classes, not instances
+    before = [];
+}
+```
+
+Constraints name classes, so you do not need a reference to another system's object to state an
+order, and a class nobody registered is simply not a constraint. Two extensions on one phase with no
+path between them record in **ascending `name` order** — reproducible rather than correct, and chosen
+precisely so that adding an `await` to a system's startup cannot change the picture. A cycle is
+reported with the names on it.
+
+### What keeps your work alive
+
+The graph elides work whose output nothing consumes, and that applies to an extension exactly as it
+does to a built-in pass. Thread a result into a record and it is consumed. Write something imported —
+the canvas, an imported texture — and it is a side effect. Want work that runs regardless and
+`make_side_effect()` on the pass builder says so.
+
+**An extension whose whole recording is elided is a correct, cheaper frame, not a failure**, and
+nothing reports it as one. It is a grey cluster with your extension's name on it in a graph dump.
+
+### The rest of `FrameContext`
+
+| | |
+|---|---|
+| `frame.graph` | the frame's `FrameGraph`. Record into it with the `graph_*` helpers, exactly as the built-in passes do |
+| `frame.view` | the `GPUViewContext` — camera, uniforms, frame index |
+| `frame.phase` | which phase this is |
+| `frame.resolution` | `[width, height]` of what you are drawing into, from the live handle |
+| `frame.describe(handle)` | the descriptor of any resource, for a pass that has to relate two of them |
+| `frame.is_open` | records are per-frame. A record held past the end of the frame is a retained handle by another name, and both reading and publishing through one say so |
+
+### Not built yet
+
+Two pieces of the extension design are named in `RENDER_EXTENSION_DESIGN.md` and **do not exist**:
+`RenderExtensionRegistry.describe()` (printing the pipeline as data) and `FrameProduct` (opting into
+optional frame products such as velocity or a readable copy of the colour). Do not write against
+them.
+
+---
+
+## 7. Rendering somewhere other than the canvas
+
+```js
+import { GPUTextureContext } from "./renderer/texture/GPUTextureContext.js";
+
+renderer.render_to_target(camera, scene, dt, GPUTextureContext.fromTexture(texture, renderer.device));
+```
+
+`render()` *is* this call with the canvas's current texture as the target — the canvas is one target
+among others, not a privileged one.
+
+**The target says where the picture goes, not how big it is.** Everything the frame is built out of —
+the G-buffer, the visibility buffer, the depth ping-pong, the temporal history — is sized from
+`renderer.output_resolution`, so **the target must be that size**. A caller wanting a different one
+calls `renderer.resize()` first and puts the size back afterwards.
+
+This is what makes a frame readable at all: a canvas texture is configured by the presentation path
+and cannot carry `COPY_SRC`; a texture you own can. Thumbnails, asset previews and image-based tests
+all go through here.
+
+---
+
+## 8. Content whose vertices change — the dynamic-mesh path
+
+A trail behind a projectile, a ribbon, a tube along a path, a batch of CPU-simulated particles, a
+debug line: content rewritten every frame cannot pay for a meshlet build, and rebuilding meshlets per
+frame to force it down the standard path is explicitly not the answer.
+
+```js
+const mesh = DynamicMesh.from(geometry, [1, 0.5, 0, 1]);   // Geometry, not MeshletGeometry
+
+batch.add(mesh);          // DynamicMeshBatch, yours — not the Scene's
+mesh.visible = false;     // hide without leaving the batch
+geometry.needsUpdate = true;   // you say when the vertices changed; nothing watches the arrays
+```
+
+This is **a separate path, not a variant of the standard one.** A `DynamicMesh` holds a plain
+`Geometry`, is never in the scene's instance batch, gets no row in the scene database, and is drawn
+by a pipeline of its own after the standard geometry path has finished with the frame.
+
+Drawing it is a `GPUDynamicMeshRenderer` inside an extension of yours (§6). Two things to know:
+
+**There is one vertex layout and it is fixed** — 8 floats: position at `[0..2]`, one reserved slot at
+`[3]`, RGBA colour at `[4..7]`. A dynamic mesh is drawn by a single pipeline, so letting each geometry
+declare its own attribute set would buy nothing and cost either a pipeline per layout or a shader
+that branches per vertex. Your geometry needs a position attribute and an index; a colour attribute is
+optional and is multiplied by the mesh's flat `color`.
+
+**`GPUDynamicMeshRenderer.opaque` chooses blending or depth**, and it is a property of the pass
+rather than of a mesh — the whole batch moves together. Left `false` the content is blended and only depth-tests,
+which is what effects want. Set it and the pass writes depth instead: a solid surface with no meshlet
+build behind it has no depth ordering otherwise, and no CPU sort can give it one, because a painter's
+order over triangles is wrong wherever two of them interpenetrate.
+
+Residency is keyed on **the geometry**, not on batch membership, so a mesh that blinks off for a
+frame or is removed and re-added keeps its buffers.
+
+---
+
+## 9. Frame-level switches
+
+| | |
+|---|---|
+| `feature_shadows_enabled` | |
+| `feature_taa_enabled` | when off, there is no upscale and the phases either side of it are the same size |
+| `internal_resolution_scale` | render internally below output resolution; `DynamicResolutionScaling` drives it from frame time |
+| `pixel_ratio`, `output_resolution`, `aspect_ratio`, `resize(x, y)` | |
+| `motion_blur`, `dof`, `dof_unreal`, `nss`, `restir_di`, `path_tracer` | sub-objects with their own settings |
+| `frame_count`, `add_debug_frame(n)` | |
+
+---
+
+## 10. Where things live
+
+```
+shade/renderer/
+├── Renderer.js               the whole surface in §2, §7, §9
+├── scene/                    Scene, Node3D, Mesh, SkinnedMesh, DynamicMesh, InstanceBatch
+├── geometry/                 Geometry, MeshletGeometry, the builders, primitives/
+├── material/                 ShadeMaterial, StandardShadeMaterial
+├── texture/                  ShadeTexture, GPUTextureContext, source/ShadeImage
+├── light/                    LightCollection, make_sunlight, model/{Light,DirectionalLight,PointLight,SpotLight}
+├── camera/                   PerspectiveCamera
+├── loader/gltf/              load_gltf, SceneBundle
+├── extension/                RenderExtension, FrameContext, FrameRecord, the four records
+├── dynamic/                  GPUDynamicMeshRenderer and its one vertex layout
+└── animation/                GPUAnimationManager — skins and clips
+```
+
+`shade/device/mock/` holds a **validating software device**: no shader execution, but real validation
+of bindings, passes, resources and texture copies. It is how Shade's own tests run without a GPU, and
+it is available to yours. Specs must never acquire a real device — see `vitest.config.mjs`, which
+explains at length why.