@woosh/meep-engine 3.14.6 → 3.16.0

package/src/shade/RENDERER_CONTRACT.md

@@ -1,580 +1,584 @@
-# 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 it 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 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
-
-The renderer 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. **The
-renderer does not recover a lost device.** Everything it 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
-```
-
-Seven generators ship, 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` and `draw_side`.
-
-**`draw_side` is part of the rasterization bucket key, and it changes what is drawn.** `Front` (the
-default) culls back faces, `Back` culls front faces, and `Double` culls neither — the three map
-straight onto the pipeline's cull mode, so a bucket exists per side that any material in the scene
-asks for. A face seen from behind is shaded with its normal flipped, so `Double` is a working
-double-sided material and not a hint. glTF `doubleSided: true` arrives as `Double` and stays that
-way; the loader's fix-up pass only rewrites `Back` to `Front`, by flipping the geometry.
-
-Shadow passes invert the mapping — `Front` culls *front* faces there — so a one-sided surface casts
-from its back face and does not shadow-acne against its own lit side. `Double` has no opposite and
-stays unculled in both.
-
-`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 the renderer:
-
-```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` | |
-| `profile_session` | assign a `GPUProfileSession` to record GPU timings; null when nothing is profiling |
-
----
-
-## 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 the renderer'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.
+# 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 it 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 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
+
+The renderer 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` — the MBOIT transparency mode blends into 32-bit float targets. The default mode,
+  AVBOIT, blends `rgba16float` only and does not need it. The feature stays on the floor while MBOIT is
+  selectable at all; retiring it from the floor means retiring MBOIT.
+
+**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. **The
+renderer does not recover a lost device.** Everything it 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
+```
+
+Seven generators ship, 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` and `draw_side`.
+
+**`draw_side` is part of the rasterization bucket key, and it changes what is drawn.** `Front` (the
+default) culls back faces, `Back` culls front faces, and `Double` culls neither — the three map
+straight onto the pipeline's cull mode, so a bucket exists per side that any material in the scene
+asks for. A face seen from behind is shaded with its normal flipped, so `Double` is a working
+double-sided material and not a hint. glTF `doubleSided: true` arrives as `Double` and stays that
+way; the loader's fix-up pass only rewrites `Back` to `Front`, by flipping the geometry.
+
+Shadow passes invert the mapping — `Front` culls *front* faces there — so a one-sided surface casts
+from its back face and does not shadow-acne against its own lit side. `Double` has no opposite and
+stays unculled in both.
+
+`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 the renderer:
+
+```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 |
+| `transparency_mode` | `ShadeTransparencyMode.AVBOIT` (default) or `.MBOIT`; both run at the one transparency call site with the same inputs, safe to flip per frame |
+| `avboit` | `AVBOITSettings`: `transmission_tint_from_base_color` (default off) filters transmitted light by base colour per channel under AVBOIT — off, a flip of `transparency_mode` changes no material's meaning |
+| `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` | |
+| `profile_session` | assign a `GPUProfileSession` to record GPU timings; null when nothing is profiling |
+
+---
+
+## 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 the renderer'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.