@woosh/meep-engine 3.9.0 → 3.11.0

package/src/shade/device/IMMEDIATE_DATA_PLAN_2026_08_28.md

@@ -0,0 +1,451 @@
+# WGSL immediate data in Shade — landing plan, 2026-08-28
+
+How to bring the WGSL `immediate` address space (`var<immediate>` + `GPUBindingCommandsMixin.setImmediates`)
+into Shade, starting from `ShadeGPUCommandContext.allocateTransientBuffer` and the call sites that
+feed it.
+
+**Verdict:** worth landing. Shade already models this exact concept, under this exact name, on top of
+uniform buffers — nineteen of the twenty structs literally called `PUSH_CONSTANTS` fit inside the
+64-byte budget unmodified. With no fallback in scope the remaining work is small and almost entirely
+additive.
+
+> **Scope decision (rev 2).** An earlier revision of this plan carried a dual-lowering fallback:
+> `var<immediate>` where supported, `@group(N) @binding(0) var<uniform>` where not, chosen by a
+> capability probe. That is now **out of scope**, and it should never have been in it —
+> [`RENDERER_CONTRACT.md` §2](../RENDERER_CONTRACT.md) already states the rule it violated: *"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."* `ShadeDeviceFailureReason` says the same thing in its header
+> comment, citing D6/I-8: no degradation tiers, no fallbacks, no feature-detection branches.
+>
+> Immediates therefore join the floor rather than getting a compatibility path. That deletes: the
+> import-time capability probe and its unrecoverable failure mode, the extra bind group the fallback
+> lowering needed, the resulting exclusion of the 7 shaders already at `maxBindGroups: 4`, and the
+> `vi.resetModules()` dance every dual-lowering spec would have required. If a fallback is ever
+> genuinely wanted, §9 shows why it belongs in a shader variant rather than in the binding machinery.
+
+---
+
+## 1. What the feature is, restricted to what matters here
+
+Immediates are WebGPU's portable spelling of Vulkan push constants / D3D12 root constants / Metal
+`setBytes`. The parts that constrain this plan:
+
+| | Value |
+|---|---|
+| WGSL gate | `requires immediate_address_space;` — a **language extension**, not a `GPUFeatureName` |
+| Detection | `navigator.gpu.wgslLanguageFeatures.has('immediate_address_space')` — synchronous, no adapter needed |
+| Size budget | `maxImmediateSize`, default **64 bytes**, multiple of 4, **no separate Compatibility Mode default** |
+| Declaration | Module scope, immutable, **no `@group` / `@binding`** |
+| Store type | Host-shareable constructible, **arrays and structs containing arrays are disallowed** |
+| Count | **At most one** immediate variable statically accessed per entry point |
+| Layout rules | Storage-space (natural alignment), **not** uniform-space |
+| API | `pass.setImmediates(rangeOffset, data, dataOffset, dataSize)`, on render pass, compute pass and bundle encoders |
+| Pipeline layout | `GPUPipelineLayoutDescriptor.immediateSize` (default 0, ≤ `maxImmediateSize`, multiple of 4) |
+| Init | Bytes start zeroed but **slots start unset**; a draw reading an unset 4-byte slot is a validation error |
+| Reset | Per-encoder; survives `setPipeline`, cleared by a new pass and by `executeBundles` |
+
+Because `maxImmediateSize` is a `maximum`-class limit with a default of 64 and no compat-mode
+reduction, **any adapter that exposes the WGSL extension reports at least 64 bytes**. There is no
+device where the language feature is present and the budget is not. That is what makes a floor check
+sufficient and a runtime branch unnecessary.
+
+Availability is a browser-version question, not a hardware one: Vulkan's `maxPushConstantsSize` is
+core-1.0 with a 128-byte required minimum and no feature bit, and no device in the
+`vulkan.gpuinfo.org` corpus reports below 128. Chrome ships immediates in 149–150.
+
+---
+
+## 2. The current path, traced
+
+Shade already has this pattern, three layers deep.
+
+**Declaration** — `ShaderResourceGroupDescriptor.addUniform` (`ShaderResourceGroupDescriptor.js:335`):
+
+```js
+const PUSH_CONSTANTS = WebGPUStruct.from({
+    probe_index_offset: u32,
+    probe_update_count: u32,
+    probe_resolution: u32,
+    probe_count: u32
+});
+
+resources.createGroup()
+    .addUniform("settings", PUSH_CONSTANTS)
+    .addTexture("tAtlas_radiance");
+```
+
+**Codegen** — `ShaderResourceSetDescriptor.generateCodeChunk` (`ShaderResourceSetDescriptor.js:305`)
+emits `@group(0) @binding(0) var<uniform> settings : PUSH_CONSTANTS;`.
+
+**Upload, per dispatch** — `ShadeGPUCommandContext.allocateTransientValueBuffer` (`:598`):
+
+```js
+const settings = context.encoder.allocateTransientValueBuffer(PUSH_CONSTANTS, { … });
+
+shader.dispatch({ encoder: context.encoder, bindings: { settings, … } });
+```
+
+which lands in `allocateTransientBuffer` (`:538`) → `GPUBufferAllocator.get` (pooled), then
+`writeValueBuffer` (`:620`) → staging buffer → `copyBufferToBuffer`, then a `BindGroupDescriptor` hash
+lookup in `GraphicsContext.setPipelineBindings` (`GraphicsContext.js:211`) and finally
+`pass.setBindGroup(i, bind_group)`.
+
+The FrameGraph route reaches the same place: `graph_compute_pass` → `graph_prepare_bindings` →
+`encoder_prepare_shader_binding` (`:34`), which turns a raw value or `ArrayBuffer` into a transient
+uniform buffer on the spot.
+
+**Scale of the surface:**
+
+- 67 `allocateTransientValueBuffer` call sites, 11 `allocateTransientBufferAndLoad`, 21 `graph_import_typed_buffer`
+- 300 `addUniform` declarations; 22 of those *call sites* name a `*PUSH_CONSTANTS*` type, across
+  **20 distinct struct definitions** (`LPV_ACCUMULATION_PUSH_CONSTANTS` is shared by four shaders).
+  The table in §6 is per-struct, so it has 20 rows, not 22
+- The single most common transient value type is a bare `u32` (12 sites)
+
+---
+
+## 3. What the win actually is
+
+Not bandwidth. 64 bytes at a few hundred dispatches a frame is noise on any bus.
+
+The win is the machinery each of those 20-byte structs currently drags behind it:
+
+1. **A pooled `GPUBuffer` acquire/release per value.** `GPUBufferAllocator.get` plus the transient
+   tracking array in `ShadeGPUCommandContext`, per dispatch, per frame.
+2. **A staging buffer, a `getMappedRange`, an `unmap` and a `copyBufferToBuffer` per value** —
+   `writeValueBuffer` does all four for what is often four bytes.
+3. **A `BindGroupDescriptor` construction plus a `HashMap` lookup per value**, and a cache entry
+   whose key changes every time the value changes — so the small-uniform bind groups are the ones
+   least likely to hit the cache.
+4. **Two JS allocations per value, in the serialiser.** `writeValueBuffer` reaches
+   `write_gpu_typed_buffer`, which calls `scratch_buffer.fromArrayBuffer(data)`, which constructs a
+   fresh `DataView` and `Uint8Array` over the target every single call. Per dispatch, per frame, in a
+   codebase that advertises "zero-allocation" in its own package keywords. The immediate path writes
+   into a persistent `BinaryBuffer` and allocates nothing (§6, L3).
+5. **A `@binding` slot** in the group the settings share.
+
+Point 5 is *only* a binding, not a group. Measured across all twenty candidates: the settings uniform
+shares its group with textures and storage buffers in every case, at a median of about four resources
+per group. No bind group slot is recovered anywhere in the current codebase. (An earlier revision
+claimed otherwise and built an argument on it; that argument is withdrawn.)
+
+**The strongest case is `graph_import_typed_buffer`** (`renderer/shader/graph/graph_import_typed_buffer.js`,
+21 call sites). It does not use the transient pool at all — per execution it calls `device.createBuffer`
+with `mappedAtCreation`, `getMappedRange`, `unmap`, `copyBufferToBuffer`, then `destroy` on
+`encoder.onFinished`. A full buffer create-and-destroy per frame per value, carrying things like
+`LPV_ACCUMULATION_PUSH_CONSTANTS` at 20 bytes. The source carries a standing TODO ("this is pretty
+inefficient, figure out a way to skip needing 2 buffers") and a 2025-09-13 note that the obvious fix —
+transient buffer plus `queue.writeBuffer` — produced garbage for reasons never tracked down.
+Immediates make the two-buffer dance unnecessary by construction for the ≤64-byte cases rather than
+requiring that bug to be found first.
+
+Caveat: converting a `graph_import_typed_buffer` site is *not* a drop-in. It returns a graph resource
+id that passes consume as an ordinary binding, so the consuming pass stops declaring a graph input.
+Higher payoff per site, higher cost per site.
+
+Honest counterweight: on hardware, a 64-byte immediate may well land in a driver-managed constant
+bank rather than in registers, so do not promise a shader-side speedup. Promise the removal of
+CPU-side per-draw allocation, and measure the rest.
+
+---
+
+## 4. The floor
+
+Immediates become a floor requirement, stated in `RENDERER_CONTRACT.md` §2 next to
+`indirect-first-instance` and `maxStorageBuffersPerShaderStage ≥ 10`, and checked in `Renderer.js`
+using the idiom already there (`Renderer.js:1123`).
+
+Two checks, both before the device is requested, so the failure names what was missing:
+
+```js
+// earliest — wgslLanguageFeatures lives on navigator.gpu, no adapter required
+if (!gpu.wgslLanguageFeatures.has('immediate_address_space')) {
+    throw ShadeDeviceFailure.below_floor(
+        "requires WGSL immediate data (Chrome 149+); this browser does not support it"
+    );
+}
+
+// beside the existing maxStorageBuffersPerShaderStage check, on the adapter
+const maxImmediateSize = adapter.limits.maxImmediateSize;
+if (maxImmediateSize < 64) {
+    throw ShadeDeviceFailure.below_floor(
+        `requires 64 bytes of immediate data, adapter offers ${maxImmediateSize}`
+    );
+}
+```
+
+`below_floor` is the right reason code: an adapter that does not meet §2, with the detail. Nothing
+goes in `requiredFeatures` — `immediate_address_space` is a WGSL language extension, not a
+`GPUFeatureName`, and adding it there would make `requestDevice` reject on every device. Nothing goes
+in `requiredLimits` either: 64 is the spec default, so a device gets it without asking.
+
+**When the floor rises.** Not in the plumbing commits — a shader that declares no immediate emits no
+`requires` directive and needs nothing. The floor and the checks land in the same commit as the
+**first migrated shader** (§8 step 6), so the engine keeps running on older Chrome for as long as it
+still can. That is one commit where the browser support statement changes, and it should say so in
+its message.
+
+---
+
+## 5. The one structural obstacle
+
+`ShaderResourceSetDescriptor` is a list of groups; a group is a list of resources; a resource has a
+`binding_index`. Everything downstream — `generateBindings` returning `GPUBindingResource[][]`,
+`generatePipelineLayoutDescriptor` producing one `BindGroupLayoutDescriptor` per group,
+`generateCodeChunk` prefixing every declaration with `@group(g) @binding(b)` — assumes that shape.
+
+An immediate has no group, no binding, and there is at most one per entry point. It has to live
+*beside* the groups, and its value needs a second route to the pass encoder that ends in
+`setImmediates` rather than `setBindGroup`.
+
+Nothing about that requires a device, so the whole thing stays where Shade already does its work:
+in descriptors built at module scope. `PipelineLayoutDescriptor` is device-free by design and stays
+that way.
+
+---
+
+## 6. The landing plan
+
+**L1 — declaration + codegen**
+
+- `ShaderResourceSetDescriptor`: an `#immediate` slot beside `#groups`, a `setImmediate(name, type)`
+  that rejects a second call, plus validation at declaration time: `type.size <= 64`, no arrays
+  anywhere in the type (walk it — `WebGPUArray` members and nested structs both), no atomics, size a
+  multiple of 4.
+- `generateCodeChunk` (`ShaderResourceSetDescriptor.js:305`): emit `var<immediate> name : Type;`
+  first, with no `@group`/`@binding` prefix.
+- `ShaderDescriptor.compile` (`ShaderDescriptor.js:53`): the existing mechanism emits
+  `enable ${extension};`. Language extensions use **`requires`**. That needs a second channel on
+  `CodeChunk` — `addLanguageExtension` beside `addExtension` — and a `requires` line in the prelude.
+  Do not overload `addExtension`; its assert is against `WebGPUExtensionType`, which is the
+  `GPUFeatureName` namespace.
+
+**L2 — pipeline layout**
+
+- `PipelineLayoutDescriptor`: an `immediateSize = 0` field, threaded through `from`, `forStage`,
+  `fromJSON`, `hash`, `equals`, `copy`, `clone`. Missing it from `hash`/`equals` would silently alias
+  two layouts that differ only in immediate size — cheap mistake, expensive symptom.
+- `PipelineLayoutManager.#create_pipeline_layout` (`PipelineLayoutManager.js:85`): pass it to
+  `createPipelineLayout`.
+- `generatePipelineLayoutDescriptor` / `generatePipelineLayout`: set it from `roundUp(4, type.size)`.
+
+**L3 — binding resolution and the call**
+
+**Do not change the return shape of `generateBindings`.** Returning `{ groups, immediate }` would
+break all **10** external callers (`GPUParticularRenderer`, `GPUDynamicMeshResidency`,
+`graph_draw_lightmap_viz_buffer`, `prototypeParticleSystem`, `graph_atorus_denoise_luma`,
+`graph_rasterize_meshes_transparent_oit`, `ComputeShader`, `ImageShader`, `RenderPassDescriptor`,
+`GPUWaterRenderer`) and force the new field through the **22** external
+`constructRenderPass`/`constructComputePass` call sites. Purely additive instead:
+
+- `ShaderResourceSetDescriptor.writeImmediate(map, buffer)` — a *new* method that **allocates
+  nothing**. It writes the immediate value into a caller-owned `BinaryBuffer` at that buffer's
+  current `position`, advances `position` by the type's size, and returns `false` when the shader
+  declares no immediate. Every existing `generateBindings` caller is untouched.
+
+  Use the already-exported `write_wgsl_type_value(value, buffer, type)`
+  (`serde/write_gpu_typed_buffer.js:114`), which takes a `BinaryBuffer` directly. **Do not** route
+  this through `write_gpu_typed_buffer` (`:188`): that wrapper calls
+  `scratch_buffer.fromArrayBuffer(data)`, and `fromArrayBuffer` constructs `new DataView(data)` and
+  `new Uint8Array(data)` on every call — two allocations per write, and it resets `position` to 0.
+  The zero-allocation entry point already exists and is public; the wrapper is the thing to avoid.
+
+- `GraphicsContext.setPipelineBindings` (`GraphicsContext.js:211`) gains an optional fourth
+  parameter — the `BinaryBuffer`, plus the byte offset and length written. After the `setBindGroup`
+  loop: `pass.setImmediates(0, buffer.data, byte_offset, byte_length)`. `setImmediates` takes
+  `AllowSharedBufferSource`, and for a plain `ArrayBuffer` the offset and size arguments are in
+  **bytes**, so the backing store is passed through with no copy on our side. All four existing
+  callers keep working.
+
+- `ImageShader.draw` and `ComputeShader.constructPass`/`dispatch` set `position`, call
+  `writeImmediate`, and thread the buffer plus range through as optional fields.
+
+Three properties of `BinaryBuffer` that this design has to respect:
+
+1. **`data` is not stable.** `setCapacity` (and therefore `ensureCapacity`) reallocates the backing
+   `ArrayBuffer` and rebinds `dataView` / `__data_uint8`. Read `buffer.data` at the point of the
+   `setImmediates` call, never cache it — and size the buffer once at construction so it never grows
+   mid-frame.
+2. **Endianness is not the default.** `BinaryBuffer` defaults to `EndianType.LittleEndian`, but the
+   serde module's own scratch sets `endianness = platform_compute_endianness()` (`:179`) because GPU
+   buffer contents must match the host. A caller-supplied buffer that skips this writes correct-looking
+   bytes that are wrong on a big-endian host and identical on the one you test on. Set it at
+   construction, and assert it in `writeImmediate`.
+3. **Ownership.** One long-lived buffer on `ShadeGPUCommandContext`, sized to `maxImmediateSize` at
+   construction, is enough — `setImmediates` copies the bytes at call time, so the region is free for
+   reuse immediately after. The API is still parameterised on `position` rather than hardcoding 0,
+   because that costs nothing and leaves room for a caller that wants to stage several values or keep
+   a frame log of them.
+- `encoder_prepare_shader_binding` (`:34`): in the immediate case, return the raw value rather than
+  allocating a transient buffer.
+
+**The eight bypass paths.** `setPipelineBindings` does not cover everything. Eight files drive
+`pass.setBindGroup` directly and never touch it — `GPUMaterialManager`, `prototypeParticleSystem`,
+`graph_build_depth_mipmap`, `render_copy_texture`, `graph_rasterize_meshes_alpha_tested`,
+`graph_rasterize_meshes_transparent_oit`, `draw_texture_as_rgba`, `WebGPUMipmapGenerator`. A shader
+migrated in one of those needs its own `setImmediates` call at the right point in the loop. None of
+the twenty candidates lives there, so this constrains future migration rather than this landing — but
+it must not be assumed away.
+
+**L4 — the test tiers**
+
+Without a fallback these are not optional: they are the only way immediates get exercised outside a
+browser.
+
+- **WGSL validation** (`wgsl/validate_wgsl_source.js`) — teach it that `var<immediate>` is legal and
+  `requires immediate_address_space;` is a valid directive, so the new declaration does not trip the
+  foreign-token or undeclared-call rules.
+- **JS emulator** — a real trap. `collectGlobalVariable`
+  (`wgsl/emulator/WGSLJavaScriptCompiler.js:825`) only pushes to `globalBindings` when *both* `group`
+  and `binding` are non-null (`:862`). A `var<immediate>` has neither, is not `workgroup`, and falls
+  through to the `privateGlobals` branch, where it is **silently default-initialised**. Every emulator
+  spec for an immediate-using chunk would pass while reading zeros. Route
+  `address_space === 'immediate'` into `globalBindings` with a null group/binding so
+  `emu.bindings.settings = {…}` keeps working by name.
+- **SoftwareGPUDevice** — `DEFAULT_LIMITS.maxImmediateSize` (`mock/SoftwareGPUDevice.js:67`) is
+  already present, set to `0`. Raise it to 64, add `setImmediates` to `SoftwareGPURenderPassEncoder`
+  (`:130`) and `SoftwareGPUComputePassEncoder` (`:108`) with the spec's `[[immediate_data]]` /
+  `[[immediate_slots_set]]` state, validate `rangeOffset % 4`, size `% 4` and the range bound, and
+  snapshot the bytes into each recorded draw/dispatch the way `#snapshot_bindings` already snapshots
+  bind groups. Follow the folder's stated policy in `mock/IMPLEMENTATION_PLAN.md` §2: validation
+  errors go through `generate_error`, they do not throw. `createPipelineLayout` (`:766`) gains the
+  `immediateSize ≤ maxImmediateSize` and `% 4` checks. Emulate the unset-slot rule too — it is the
+  mock's chance to catch a missing `setImmediates` before a browser does.
+- **Playground** — one pass converted end to end and run in Chrome before any bulk migration.
+
+**L5 — migration**
+
+Smallest first. `shader_read_out_bucket` (4 bytes, one `u32`) is the ideal first patient;
+`shader_generate_rays` and `shader_shadow_upscale` are the same shape.
+
+**It is not one line per shader.** Only 5 of the 20 candidates supply their settings implicitly, by
+passing a plain object in `bindings` and letting `encoder_prepare_shader_binding` allocate. The other
+~15 have an explicit `allocateTransientValueBuffer` or `graph_import_typed_buffer` call that
+pre-builds the buffer and passes the `GPUBuffer`. Those need two edits: the declaration, and the call
+site that stops pre-allocating.
+
+---
+
+## 7. Candidate inventory
+
+Every struct named `*PUSH_CONSTANTS*`, sized by `WebGPUStruct` (the same natural-alignment layout the
+`immediate` address space uses). Sizes were re-derived programmatically — field lists extracted from
+source and fed back through the real `WebGPUStruct.from`, not computed by hand.
+
+| Struct | Size | Verdict |
+|---|---:|---|
+| `shader_read_out_bucket` | 4 | fits |
+| `shader_generate_rays` | 4 | fits |
+| `shader_shadow_upscale` | 4 | fits |
+| `shader_sharc_evict` | 8 | fits |
+| `shader_lightmap_accummulate_tile` | 8 | fits |
+| `shader_lightmap_tile_composit` | 8 | fits |
+| `graph_lpv_store_sh` | 16 | fits |
+| `shader_perfect_perspective` | 16 | fits, see note |
+| `graph_lvp_atlas_to_sh` | 20 | fits |
+| `LPV_ACCUMULATION_PUSH_CONSTANTS` | 20 | fits |
+| `shader_lpv_accumulate_depth` | 20 | fits |
+| `graph_sample_light_probes` | 20 | fits |
+| `graph_reduce_atlas_to_sh` | 24 | fits |
+| `shader_lpv_build_gbuffer` | 24 | fits |
+| `shader_update_clipmap_cascade` | 32 | fits |
+| `graph_lpv_shade` | 32 | fits |
+| `shader_build_scene_sdf_f32` | 32 | fits |
+| `shader_scene_sdf_debug_viz` | 32 | fits |
+| `shader_scene_sdf_soft_shadows` | 48 | fits |
+| `LIGHT_CLUSTER_ASSIGNMENT_PUSH_CONSTANTS` | 128 | **cannot move** |
+
+`LIGHT_CLUSTER_ASSIGNMENT_PUSH_CONSTANTS` fails twice: 128 bytes against a 64-byte budget, and
+`frustum: WebGPUArray.from(vec4f, 6)` is an array, which the `immediate` address space disallows
+outright. It stays a uniform buffer. If the rest is worth moving later, the split is
+`{cluster_params, screen_resolution, distance_min, distance_max}` at 32 bytes as an immediate with the
+frustum left in a buffer — a follow-up, not part of this landing.
+
+Note on `shader_perfect_perspective`: its `use_vignette` member is typed `bool`, and Shade's `bool`
+primitive (`WEBGPU_WGSL_PRIMITIVE_TYPES.js:8`) is a 4-byte type. WGSL's host-shareable set is numeric
+scalars, vectors, matrices, atomics, arrays and structs of those — `bool` is in none of them, in *any*
+address space, uniform included. So this is a pre-existing condition rather than something immediates
+introduce, but the member needs to become `u32` before this struct can move. Worth checking whether
+that shader is reachable at all; grep finds no importer.
+
+Beyond the named ones, the 12 bare-`u32` `allocateTransientValueBuffer` sites are the same pattern
+without the naming, and are equally good candidates.
+
+### What must not move
+
+`CAMERA_UNIFORM_STRUCT` (~640 bytes: eight `mat4x4f`, a six-element `vec4f` frustum array, and more)
+and `VIEW_UNIFORM_STRUCT` account for 116 of the 300 `addUniform` calls. They are per-view, written
+once, read by everything — over budget, containing arrays, and not per-draw data. They stay. Same for
+anything reached through `GPUDatabase` or `GPUSingleTypeTable`.
+
+---
+
+## 8. Commit sequence
+
+Steps 1–5 are inert without a shader that declares an immediate, so the engine still runs on older
+Chrome throughout. Step 6 is where the floor rises.
+
+1. `feat(shade): the software device carries immediate data` — L4's mock work alone. Raises
+   `maxImmediateSize` to 64, adds `setImmediates` to both pass encoders with spec state and
+   validation, `immediateSize` validation on `createPipelineLayout`.
+   Note while doing this: the `DEFAULT_LIMITS` doc comment claims the table was "verified field by
+   field against a Dawn default device (`webgpu` package, already a dependency)". **That package is
+   not a dependency** — `webgpu` appears in `package.json` only as a `keywords` entry, and is absent
+   from `node_modules`. So `maxImmediateSize: 0` cannot be re-verified from this repo, and raising it
+   to 64 rests on the spec's `maximum`-class default rather than a Dawn reading. Say that in the
+   comment instead of repeating an unverifiable citation.
+2. `fix(shade): the emulator does not silently zero an immediate` — the `WGSLJavaScriptCompiler`
+   fall-through at `:862`, plus the `validate_wgsl_source` rules. A spec that fails before and passes
+   after.
+3. `feat(shade): pipeline layouts carry an immediate size` — L2, pinned by a `SoftwareGPUDevice` spec.
+4. `feat(shade): shaders can declare immediate data` — L1. The `requires` channel on `CodeChunk`,
+   `setImmediate` on the set descriptor, the declaration-time validation.
+5. `feat(shade): immediate data reaches the pass encoder` — L3. `generateImmediateBytes`, the optional
+   `setPipelineBindings` parameter, `encoder_prepare_shader_binding` stops allocating for immediates.
+6. `feat(shade): immediate data joins the device floor` — the two `Renderer.js` checks, the
+   `RENDERER_CONTRACT.md` §2 amendment, **and** the first migrated shader
+   (`shader_read_out_bucket`), together. This is the commit that raises the browser requirement to
+   Chrome 149+; its message should say so plainly.
+7. `refactor(shade): <pass> passes its settings as immediate data` — one per shader thereafter.
+
+Measure between 6 and 7, and again after the first handful of 7s: transient buffer acquisitions per
+frame and bind-group cache misses per frame are the two numbers that should move. If they do not,
+stop migrating the `allocateTransientValueBuffer` sites and spend the effort on the
+`graph_import_typed_buffer` consumers instead, where the per-frame cost is a whole buffer rather than
+a pool hit.
+
+---
+
+## 9. If a fallback is ever wanted anyway
+
+It belongs in a shader variant, not in the binding machinery — and Shade already supports that with
+no new mechanism. `ShaderDescriptor.compile()` clones the body chunk and adds the resource set's
+generated chunk as a dependency:
+
+```js
+const chunk = this.#body.clone();
+chunk.addDependency(this.#resources.generateCodeChunk());
+```
+
+So one `CodeChunk` body pairs with two different `ShaderResourceSetDescriptor`s to produce two
+`ShaderDescriptor`s — immediate and uniform — from a single source of shader text, selected by
+whoever constructs them. The body never changes: `settings.probe_count` reads identically either way.
+
+That is a per-shader, opt-in decision made by the shader's author, which is a very different thing
+from a capability branch threaded through codegen, pipeline layout, binding resolution and the test
+harness. Keeping the door open costs nothing; walking through it preemptively cost a great deal.
+
+---
+
+## 10. Open questions
+
+- **Is Chrome 149+ acceptable as the engine floor, and when?** This is now the only gating question
+  in the plan. Steps 1–5 can land regardless; step 6 needs an answer. Immediates are in Chrome
+  149–150, so the answer is partly a calendar question about how far behind the target audience runs.
+- **Should `setImmediate` live on `ShaderResourceSetDescriptor` or on `ShaderDescriptor`?** The set
+  descriptor is where every other resource is declared; but an immediate is not a bound resource —
+  the spec is explicit that it is part of the *shader interface*, not the *resource interface*.
+  Recommendation: the set descriptor, because that is what `generateCodeChunk` and the binding path
+  already walk, and splitting across two objects buys nothing.
+- **Is 64 bytes worth revisiting later?** `maxImmediateSize` is raisable, but D3D12's root signature
+  budget means no browser is likely to expose more. Plan around 64 permanently.

package/src/shade/device/ShadeGPUCommandContext.d.ts

@@ -35,6 +35,27 @@ export class ShadeGPUCommandContext {
      * @param {function} debug_timers_callback
      */
     enable_debug_timers(debug_timers_callback: Function): void;
+    /**
+     * Resolves after this context's timings have been read back and handed to its recorder.
+     *
+     * **Not the same moment as {@link done}.** `done` resolves from `onFinished`, which fires
+     * synchronously at submit — before any timestamp has been read. A caller that closes its frame
+     * on `done` commits an empty one, every time. Already-resolved when nothing is profiling.
+     *
+     * @returns {Promise<void>}
+     */
+    get profiling_absorbed(): Promise<void>;
+    /**
+     * Record this context's pass timings into `recorder`.
+     *
+     * Independent of {@link enable_debug_timers}, which is the console-shaped one-off; both share
+     * the underlying {@link GPUTimerArray} and either may enable it.
+     *
+     * @param {GPUFrameRecorder} recorder
+     * @param {number} query_set_id this context's index within the frame
+     * @returns {void}
+     */
+    enable_profiling(recorder: GPUFrameRecorder, query_set_id: number): void;
     /**
      *
      * @return {GPUDevice}

package/src/shade/device/ShadeGPUCommandContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShadeGPUCommandContext.d.ts","sourceRoot":"","sources":["../../../../src/shade/device/ShadeGPUCommandContext.js"],"names":[],"mappings":"AA6BA;;;;;;GAMG;AACH;IA8II;;;;;OAKG;IACH,iDAHW,MAAM,GACJ,sBAAsB,CA6BlC;IA3KD;;;;OAIG;IACH,iBAEC;IAED;;;OAGG;IACH,mCAEC;IASD;;;;OAIG;IACH,qCAEC;IAaD;;;OAGG;IACH,2DAQC;IAOD;;;OAGG;IACH,wBAEC;IAED;;;OAGG;IACH,+BAEC;IAqBD;;;OAGG;IACH,yBAA0B;IAE1B;;;OAGG;IACH,6BAA8B;IAE9B;;;OAGG;IACH,0BAcC;IA6CD;;;OAGG;IACH,2BAFa,wBAAwB,CAIpC;IAED;;;OAGG;IACH,qCAWC;IAED;;;;;OAKG;IACH,wCAHW,MAAM,SACN,MAAM,QAWhB;IAED;;;;OAIG;IACH,qBAEC;IAED;;;;;;;;;OASG;IACH,oDALW,MAAM,6CAEN,MAAM,SACN,MAAM,QAqChB;IAGD;;;;;OAKG;IACH,uHAKC;IAED;;;;OAIG;IACH,+EAoBC;IAED;;;;;;OAMG;IACH,sGA2BC;IAED;;;;OAIG;IACH,sBAFW,MAAM,QAOhB;IAED;;;OAGG;IACH,sBAIC;IAED;;;;OAIG;IACH,yBAFW,MAAM,QAKhB;IAED;;;;;;;;OAQG;IACH,+FAPW,MAAM,wBAyChB;IAED;;;;OAIG;IACH,2EAmBC;IAED;;;;;;;OAOG;IACH,mDALW,MAAM,cACN,MAAM,6CAEN,MAAM,QAIhB;IAED;;;;;;OAMG;IACH,2CAFY,OAAO,CAYlB;IAUD;;;;;;OAMG;IACH,+BAJW,MAAM,iBAAe,QACrB,MAAM,aAuBhB;IAED;;;;;;;OAOG;IACH,qCANW,WAAW,UACX,MAAM,iBAAe,WACrB,MAAM,SACN,MAAM,aAwBhB;IAED;;;;;;OAMG;IACH,oEAHW,MAAM,iBAAe,aAgB/B;IAED;;;;;;OAMG;IACH,wDAJW,MAAM,sCAuBhB;IAED;;;;;;;OAOG;IACH,8CALW,MAAM,QACN,WAAW,eACX,MAAM,QACN,MAAM,QAuBhB;IA0BD;;OAEG;IACH,eAkDC;;CACJ;yCAnuBwC,qCAAqC"}
+{"version":3,"file":"ShadeGPUCommandContext.d.ts","sourceRoot":"","sources":["../../../../src/shade/device/ShadeGPUCommandContext.js"],"names":[],"mappings":"AA+BA;;;;;;GAMG;AACH;IAkPI;;;;;OAKG;IACH,iDAHW,MAAM,GACJ,sBAAsB,CA6BlC;IA/QD;;;;OAIG;IACH,iBAEC;IAED;;;OAGG;IACH,mCAEC;IASD;;;;OAIG;IACH,qCAEC;IAaD;;;OAGG;IACH,2DAQC;IA8DD;;;;;;;;OAQG;IACH,wCAEC;IAED;;;;;;;;;OASG;IACH,2DAHW,MAAM,GACJ,IAAI,CAiBhB;IAOD;;;OAGG;IACH,wBAEC;IAED;;;OAGG;IACH,+BAEC;IAqBD;;;OAGG;IACH,yBAA0B;IAE1B;;;OAGG;IACH,6BAA8B;IAE9B;;;OAGG;IACH,0BAcC;IA6CD;;;OAGG;IACH,2BAFa,wBAAwB,CAIpC;IAED;;;OAGG;IACH,qCAWC;IAED;;;;;OAKG;IACH,wCAHW,MAAM,SACN,MAAM,QAWhB;IAED;;;;OAIG;IACH,qBAEC;IAED;;;;;;;;;OASG;IACH,oDALW,MAAM,6CAEN,MAAM,SACN,MAAM,QAqChB;IAGD;;;;;OAKG;IACH,uHAKC;IAED;;;;OAIG;IACH,+EAQC;IA+DD;;;;;;OAMG;IACH,sGA6BC;IAoCD;;;;OAIG;IACH,sBAFW,MAAM,QAOhB;IAED;;;OAGG;IACH,sBAIC;IAED;;;;OAIG;IACH,yBAFW,MAAM,QAKhB;IAED;;;;;;;;OAQG;IACH,+FAPW,MAAM,wBA2ChB;IAED;;;;OAIG;IACH,2EAOC;IAED;;;;;;;OAOG;IACH,mDALW,MAAM,cACN,MAAM,6CAEN,MAAM,QAIhB;IAED;;;;;;OAMG;IACH,2CAFY,OAAO,CAYlB;IAUD;;;;;;OAMG;IACH,+BAJW,MAAM,iBAAe,QACrB,MAAM,aAuBhB;IAED;;;;;;;OAOG;IACH,qCANW,WAAW,UACX,MAAM,iBAAe,WACrB,MAAM,SACN,MAAM,aAwBhB;IAED;;;;;;OAMG;IACH,oEAHW,MAAM,iBAAe,aAgB/B;IAED;;;;;;OAMG;IACH,wDAJW,MAAM,sCAuBhB;IAED;;;;;;;OAOG;IACH,8CALW,MAAM,QACN,WAAW,eACX,MAAM,QACN,MAAM,QAuBhB;IA0BD;;OAEG;IACH,eAgEC;;CACJ;yCAh6BwC,qCAAqC"}