@woosh/meep-engine 3.60.4 → 3.60.6

package/src/shade/renderer/shader/compiler/SHADER_SWITCH_PROPOSAL_2026_10_16.md

@@ -1,927 +0,0 @@
-# Shader switches: a proposal (2026-10-16, revision c; stages 1 and 2 landed)
-
-**Status: stages 1 and 2 are on master (2026-10-16). Stage 3, declared bindings, is built in a worktree, uncommitted
-(§12.3).**
-
-§0 records your decisions, §4–§6 the design and its stages, and §12 what each stage contains and how it was checked. Revisions (a) and (b) are superseded by your answers.
-
-## 0. Decided so far
-
-From your answers of 2026-10-16:
-
-- **D1 — a switch is an integer.** A boolean is a switch of two values. A shader depends on several switches. A
-  switch is a value, not a chunk, and one switch may be decided at several places in the graph. (Confirmed.)
-- **D2 — a switched shader specializes to a static graph.** A switched shader and an immutable set of switch values
-  become an ordinary, fully static `CodeChunk` graph. The shader object caches its variants by the set.
-  `GraphicsContext` knows nothing of switches.
-- **D3 — every switch defaults to 0.**
-- **D4 — code first, the kludges fixed after.** In the first stage, alternatives differ in code only. The long-term
-  design still has to remove the existing kludges, resources included, and a refactor is fine.
-
-From your answers to revision (b):
-
-- **D5 — resources: one interface per definition (§5.2).** It is the union of its alternatives' bindings, bound by
-  name, with defaults for what a mode lacks. Stage 3's declared bindings are wanted later; they will change the shape
-  of a shader class a little.
-- **D6 — no flip machinery.** Pipelines made on first use compile synchronously, as they do today. A flip compiles the
-  new variants then, and nothing extra is built for it.
-- **D7 — a variant's label carries its set:** `Shade From G-Buffer [shadow directional technique=Virtual]`.
-- **D8 — no interface declaration.** A choice never inspects its alternatives, and the parent never white-boxes what
-  sits behind a switch. The per-value specs are what link every alternative into its real shaders.
-- **D9 — the API is `ShaderSwitch.enum(label, Enum)` and `ShaderSwitch.bool(label)`,** one mechanism underneath. A
-  switch's values are its own: the enum's members, or `false`/`true`. Sets, choices, labels and errors use them, and
-  errors and labels name the member.
-  - *My call, inside D3:* an enum must have a member equal to 0, the default, and one without is refused at
-    `enum()`. A bool's default is `false`. If you would rather the first-declared member be the default, it is a
-    one-line change.
-
-What follows from those:
-
-- **Pins are gone.** Their only use was a pair of exports with different bindings. §5 makes one definition serve every
-  value, and a pipeline that wants another value passes another set.
-- **The linker is untouched.** `compile()` links static graphs only, and refuses a graph that still holds a choice.
-  Revision (a) threaded the set through `compile()`; this revision does not.
-
-## 1. Summary
-
-```js
-// a switch over an engine enum, 0 by default; or ShaderSwitch.bool(label), false by default
-export const ShadowDirectionalTechnique = { Cascades: 0, Virtual: 1 };
-export const SHADOW_DIRECTIONAL_TECHNIQUE = ShaderSwitch.enum('shadow directional technique', ShadowDirectionalTechnique);
-
-// where a graph decides it: the export every importer already uses
-export const chunk_shadowmap_sample_directional = CodeChunkChoice.from(SHADOW_DIRECTIONAL_TECHNIQUE);
-chunk_shadowmap_sample_directional.add(ShadowDirectionalTechnique.Cascades, chunk_shadowmap_sample_directional_cascades);
-chunk_shadowmap_sample_directional.add(ShadowDirectionalTechnique.Virtual, chunk_shadowmap_sample_directional_virtual);
-
-// an immutable, interned set of values; a switch it does not name is at its default
-const switches = ShaderSwitchSet.EMPTY.with(SHADOW_DIRECTIONAL_TECHNIQUE, ShadowDirectionalTechnique.Virtual);
-
-// the graph, specialized: every choice replaced by its selected alternative, so no choice is left
-const static_body = body.specialize(switches);
-
-// the shader caches its variants by the set; a variant is an ordinary static shader
-shader_deferred_main.variant(switches).draw({ /* … */ });
-shader_deferred_main.descriptor.switches; // [SHADOW_DIRECTIONAL_TECHNIQUE]
-```
-
-For the case that prompted this, `chunk_shadowmap_sample_directional` becomes a choice between `_cascades` and
-`_virtual`. None of the chunks above it changes, and none of the nine shaders that reach it changes its chunk code.
-
-Measured on the real `Shade From G-Buffer` module (§7):
-
-- **Cascades** drops exactly the 14 VSM functions and 4 VSM declarations: 96 → 82 functions, 69,917 → 59,892
-  characters.
-- **Virtual** drops the 2-function cascade walk: 94 functions.
-- In both, only `shadowmap_sample_directional` changes body.
-- **Tint** (Chrome, RTX 4090) compiles all three with no messages.
-- **Pipeline creation** in Chrome takes 0.81–0.83× (cascades) and 0.66–0.70× (virtual) of the shipped shader's.
-- **Cost of a variant:** specializing plus linking takes 0.075–0.083 ms across runs, the same as linking the shipped
-  shader today.
-  A repeat `variant(set)` lookup takes 0.1 µs and allocates nothing.
-
-The deferred GPU time measured earlier on the same variants (as hand-made twins) was 0.936× for cascades and 0.957×
-for virtual, with byte-identical images.
-
-**The long-term shape (§5–§6).** Each switched shader is one definition. It declares every binding any of its
-alternatives reads, and a binding a mode does not have falls back to a declared default. Owners bind by name and
-hand the renderer's set to `variant()`. That removes, in three stages:
-
-- the two IBL/Brick4 forward-fragment twins;
-- the paired AVBOIT/MBOIT/water exports and the `use_brick4 ? […] : […]` bind-entry arrays;
-- the `build_deferred_main_shader` and `build_ssr_resolve_shader` factories;
-- the per-mode froxel GI shaders;
-- water's hidden GI dependency;
-- the five owners' branches on `indirect_lighting_mode`.
-
-Open questions are in §11.
-
-## 2. What the engine does today
-
-There are four ways a shader chooses an implementation today. None of them can be seen in the chunk graph.
-
-1. **A runtime branch on a global choice.** `shadowmap_sample_directional` branches per light on
-   `shadowmap.virtual_map != NULL`, though the technique is per renderer (`Renderer.feature_virtual_shadow_maps` →
-   `GPUSceneShadowmapContext.use_virtual_shadow_maps`). Both paths are linked into nine shader definitions:
-   - deferred heavy and deferred ReSTIR (`shader_deferred_main.js`);
-   - AVBOIT draw IBL and Brick4 (`TemplatePassDescriptor`, one pipeline per material template);
-   - MBOIT resolve IBL and Brick4;
-   - volumetrics build-lighting and build-irradiance;
-   - water finalize.
-
-   The chain is `chunk_shadowmap_sample_directional` → `chunk_shadowmap_get_light_visibility` →
-   `chunk_shade_directional_lights` → `chunk_shade_standard_material_direct` (and `_restir`) → the shader bodies.
-   Volumetrics and water optics reach it from `chunk_shadowmap_get_light_visibility` directly.
-2. **A factory parameter at the root.** `build_deferred_main_shader({ label, shading_chunk, with_restir })` builds heavy
-   and ReSTIR, and the Renderer picks the export by `feature_restir_di_enabled`. This is the `make_shader({ flag })`
-   shape that `no-nested-shader-codegen` rules out. ReSTIR also adds a binding, `tRestirRadiance`.
-3. **A twin of an intermediate chunk.** `chunk_forward_shade_standard_fragment_ibl` and `_brick4` are 178 and 185 lines
-   that differ in 46 lines: the indirect-lighting block, plus comments that have already drifted apart. They feed
-   `shader_avboit_draw_ibl` / `_brick4` and `shader_oit_resolve_moments_ibl` / `shader_oit_resolve_moments`.
-   The owners pick by `indirect_lighting_mode` (`graph_rasterize_meshes_transparent_avboit.js:538`,
-   `graph_rasterize_meshes_transparent_oit.js:150`) and build different bind groups, because Brick4 adds a `brick4`
-   storage buffer to the view group.
-4. **A function filled in at the root.** Water's `finalize_body` calls `water_gi_specular` and `water_gi_irradiance`
-   without listing a dependency that defines them. `water_finalize_shader_ibl` / `_brick4` add `chunk_water_gi_ibl` or
-   `_brick4` beside it (`shader_water.js:593-597`). Nothing needs a twin, but the dependency is invisible.
-
-A switch with its choices gives all four one declared form: pattern 1 in stage 1 (shadows), and patterns 2, 3 and 4
-in stage 2, once one definition can carry every alternative's bindings (§5).
-
-The engine already has an *open* interface of the same shape. A material template supplies `material_surface` and
-`material_opacity` to every pass by function name (`ShadeMaterialTemplate.surface` / `.opacity`), as Unreal's materials
-and vertex factories do. Switches are the *closed* counterpart: an engine-owned choice whose values the engine knows.
-Neither replaces the other.
-
-## 3. What other engines do
-
-Read from primary docs and references. The rest comes from the research brief
-`shader-switch-prior-art.md` in the side-notes folder of this session group, which has the URLs and identifiers; its
-Bevy and gpuweb claims were re-checked against the pages.
-
-**Unreal: permutation domains.** A dimension is a C++ type (bool, int, range, sparse int, or enum), each carrying a preprocessor define name. Their product is a permutation domain whose permutation id is mixed-radix over the dimensions. A shader class lists its dimensions (for example, the deferred light pixel shader has 14 of them, including the virtual shadow map mask).
-
-- Unused combinations are culled before compilation (e.g., a directional light × the VSM mask is never compiled).
-- Redundant combinations are remapped together (e.g., visualize-culling forces the others off).
-- Conditional defines (such as VSM defines) are added to the compilation environment only when that dimension is on.
-- The draw site sets every dimension by hand, then asks the shader map for
-  `(shader type, permutation id)`. **The owner knows every dimension.** Nothing derives the domain: the shader class lists it
-  and the draw site sets it.
-- Dimensions select `#if` blocks. Dependencies are `#include`s, which can sit inside an `#if`, but nothing declares
-  what each value pulls in.
-
-**Unreal: vertex factories and materials.** These are the other half of Unreal's answer, and they are an *interface
-slot*. The vertex factory compilation environment maps a virtual include path to the concrete implementation's source file.
-
-Every shader that includes the path gets the implementation the compile supplies, and nothing in between is twinned.
-The shader map is keyed by material × vertex factory × shader type × permutation.
-
-Note that Unreal's deferred light shader does not choose its *shadow technique* this way. VSM is projected into a
-screen-space mask beforehand, and the light shader only chooses whether to read the mask.
-
-**Unity: keywords.** A pass declares its keyword sets by hand with `#pragma multi_compile` / `shader_feature`
-(`_local`, `_vertex`/`_fragment` suffixes). A plain `#include` drops the pragmas of the file it includes, so a library's
-switches do not reach the shader that uses it. `#include_with_pragmas` exists to let them, and URP's `Lit.shader` uses
-it to pull in whole keyword bundles. That is Unity working its way toward a domain derived from the includes.
-
-- Since 2021.2 every declared keyword is local to the shader's `LocalKeywordSpace`. A `GlobalKeyword` is mapped into
-  each shader's space by name.
-- Setting a keyword the shader does not declare does nothing. This design does the same: values for other switches
-  are ignored.
-- Variants are looked up by closest match, and a missing one falls back silently. We should not copy that.
-
-**Bevy and naga_oil.** naga_oil passes one global map of shader defs to every module. Each module's `effective_defs`
-are collected by syntax: every name in an `#if`/`#ifdef`, whether or not its branch is taken, plus the effective defs of
-every import. So a module's domain is derived and transitive. The module is cached by a key made only of those defs
-(`ModuleKey::from_members`). That is this design's `descriptor.switches` and its key, arrived at independently.
-
-The code itself is chosen by `#ifdef` inside the text, the conditional-template shape this engine rejects.
-
-naga_oil's other route is `virtual fn` in a base module and `override fn base::f` in the top-level shader. A
-`Redirector` then rewrites every call in the final module, so no intermediate module is twinned. But the redirect is
-global, so two call sites cannot get different implementations. That is candidate B (§10).
-
-**Bevy 0.20 (released 2026-10-08) has since moved all its shaders to WESL** and removed its own WGSL dialect (checked
-against the release post). The release says nothing about what replaces `virtual fn`/`override fn`.
-
-**WESL.** `@if`/`@elif`/`@else` attributes go on declarations, statements, struct members and imports. The conditions
-are names joined with `! && ||`; they carry no values. Features are one flat set for the whole link.
-
-- The spec makes an unset feature that is used a link error. wesl-js treats it as false. wesl-rs offers
-  `Enable/Disable/Keep/Error` and defaults to `Disable`.
-- A removed branch need not be valid, and only declarations reachable from the root are emitted.
-- A module-parameters proposal (#222, unimplemented) would fork only the declarations that depend on a parameter.
-
-**gpuweb / WGSL.** WGSL itself has no conditional compilation, shipped or accepted. The only thread is gpuweb#5140,
-"@if for conditions", which is open in Milestone 3 with no decision (checked). Reviewers there asked for *declared*
-conditions, so that a library can say which conditions it reads. That is the same requirement as here.
-
-`override` is pipeline-overridable, but the spec defines a shader as the call closure from the entry point *whatever the
-constants' values*. A function reached only through a false `if` on an override is part of the shader, its bindings stay
-in the shader's interface, and nothing requires the dead branch to be removed. Chrome's Tint keeps it as `if (false)`
-(measured 2026-10-16), and DXC then drops it.
-
-This is a second reason an override is the wrong mechanism, beyond hiding the dependency. A Brick4-or-IBL override would
-still need the `brick4` buffer bound in IBL mode.
-
-**Slang: link-time `extern`/`export`.** A module declares `extern struct S : IFoo;` or `extern static const int k;`. A
-provider module declares `export struct S : IFoo = Impl;`. The program is composed from the modules chosen
-(`createCompositeComponentType`) and then `link()`ed. Unselected providers never enter the program, and intermediate
-modules compile once.
-
-This is the cleanest prior art for choosing deep in a graph without duplication, and it is open, like B. Whether any
-API lists a module's unresolved externs is unverified.
-
-**Filament** chooses the shadow technique per View at *run time*. Only the sampler type is a variant; PCF, VSM and
-EVSM are a uniform (`frameUniforms.shadowSamplingType`). That is today's meep, the runtime branch, which costs 4–6 % of
-the deferred pass here.
-
-**Godot** reads each specialization constant through an accessor that falls back to a push constant when built as an
-"ubershader". One source then serves both the specialized pipeline and a fallback compiled in the background. We do not
-need that, because `PipelineEnquiry` already compiles off the main thread.
-
-**What this design takes, and what it leaves.**
-
-- **From Unreal:** a dimension as an object with a closed value set, and a key per shader made of its values. But not
-  the owner listing every dimension; here the graph lists them.
-- **From naga_oil:** deriving the domain transitively from the graph, and keying only on it.
-- **From Unity:** values a shader does not use are ignored.
-- **From WESL's spec:** an unset value is an error, not false.
-- **From Slang and vertex factories:** the implementation is linked in *beside* the code that calls it, so nothing in
-  between is twinned or rebuilt.
-- **Left out:** conditional text inside a chunk (Unreal's and naga_oil's `#if`, WESL's `@if` on statements), which is
-  what `CodeChunk` exists to avoid. Also left out: global redirects (naga_oil overrides) and closest-match fallback
-  (Unity).
-
-An alternative here is a whole chunk with its own dependencies, which is WESL's `@if` on a declaration, raised to a
-declared, typed choice.
-
-## 4. The design
-
-### 4.1 Pieces
-
-| piece | is | API |
-|---|---|---|
-| `ShaderSwitch` | a named choice over an engine enum's members (default: the member equal to 0) or over `false`/`true` (default `false`) | `ShaderSwitch.enum(label, Enum)`, `ShaderSwitch.bool(label)`; `label`, `values`, `default_value`, `is_value(v)`, `name_of(v)` |
-| `ShaderSwitchSet` | immutable, **interned** values for some switches; a switch it does not name is at its default | `EMPTY`, `with(switch, value)`, `get(switch)`, `restricted_to(switches)` |
-| `CodeChunkChoice` | a chunk standing for one alternative per value of one switch | `CodeChunkChoice.from(switch)`, `add(value, chunk)`, `alternative_for(set)` |
-| `CodeChunk.specialize(set)` | the graph with every choice replaced by its selected alternative | returns a static `CodeChunk` |
-| `CodeChunk.collectSwitches()` | every switch the graph decides, through every alternative | `ShaderSwitch[]` |
-| `variant(set)` | on `ShaderDescriptor`, `ImageShader`, `ComputeShader`, and (designed) `TemplatePassDescriptor` | a static shader of the same class |
-
-**Interning** makes a set a value: two sets that give every switch the same value are one object, and a switch set to
-0 is not stored. So:
-
-- `a.with(X, 1).with(Y, 2) === a.with(Y, 2).with(X, 1)`;
-- `EMPTY.with(X, X.default_value) === EMPTY`;
-- every cache keys by identity;
-- `toString()` names the members, `shadow directional technique=Virtual`, which is what labels carry (D7);
-- `with` returns `this` when the value is already that, so a renderer re-deriving its set every frame allocates
-  nothing until a flag changes.
-
-Each set is made once, on first use, and kept for the process, so the table only grows by sets actually used.
-
-### 4.2 Specialization: a switched graph becomes a static one
-
-`specialize(set)` walks the graph once, depth-first, with a memo from source chunk to result:
-
-- A **choice** becomes the specialization of the alternative `set` selects. An alternative may itself be a choice of
-  another switch.
-- A **chunk whose dependencies all come back as themselves** is returned as it is. Everything not above a choice is
-  shared with the source graph, and a graph with no choice specializes to itself.
-- **Any other chunk** becomes a new `CodeChunk`: the same text and extensions, with specialized dependencies. If two
-  dependencies resolve to the same chunk, it is kept once.
-- **The memo** keeps what two chunks share in the source shared in the result, so a diamond stays a diamond.
-
-`compile()` is unchanged, except that it throws, naming the choice, if a choice reaches it. The linker only ever sees
-static graphs.
-
-`collectSwitches()` walks every alternative, selected or not, so a switch nested inside one alternative is still in
-the shader's domain.
-
-Errors:
-
-- a value with no alternative at a choice names the switch and the value;
-- a cycle through any alternative is refused at `add()`;
-- a choice equals only itself, since every choice has the same empty text.
-
-### 4.3 Variants on the shader classes
-
-"The shader" caches its variants by the set, as you asked. Every class has the same shape, `variant(set)`:
-
-1. Look `set` up by identity. A frame asking again stops here: 0.1 µs, no allocation.
-2. Restrict it to the descriptor's `switches`. Sets that agree on this shader's switches get the same variant.
-3. If the restricted set is `EMPTY`, return `this`. The object a module exports *is* the all-defaults variant, so
-   `shader.pipeline` and `descriptor.source` keep meaning what they mean today.
-4. Otherwise build, once, a static object of the same class from the specialized descriptor.
-
-| class | status | variant is |
-|---|---|---|
-| `ShaderDescriptor` | prototyped | `ShaderDescriptor.from({ label: '<label> [<set>]', resources: same object, body: body.specialize(set) })`. `switches` = `body.collectSwitches()`. `source` = the all-zeros variant. |
-| `ImageShader` | prototyped | `new ImageShader({ descriptor: descriptor.variant(set), targets, depthStencil })`, the same targets and depth state as the original. |
-| `ComputeShader` | prototyped | `new ComputeShader(descriptor.variant(set))`. Refused if its `@workgroup_size` differs from the original's: a switch changes what a pass computes, never how it is dispatched. |
-| `TemplatePassDescriptor` | designed | a sibling sharing `label`, `build` and the attachments. `build(template, set)` gets the set and returns `….variant(set).source`; existing builds that ignore the second argument keep working. Its own per-manager × template × cull-mode cache is unchanged. The reads of `.pipeline` for its layout (`graph_rasterize_meshes_transparent_avboit.js:287`, `:593`; `graph_rasterize_meshes_transparent_oit.js:205`, `:353`) becomes a `pipeline_layout` getter, so a sibling needs no pipeline of its own. |
-| water's finalize pipeline | designed | `create_water_finalize_pipeline(set)`, cached the same way. |
-
-A few things fall out of variants being whole static objects:
-
-- `features` (the `enable` list) and `validate_against_device` are per variant, with no extra work.
-- Labels carry the set, so profiler entries and validation errors name the variant they came from.
-
-### 4.4 Where the set comes from
-
-- **Who builds it.** The Renderer, from its feature flags, at the start of `render()`:
-
-  ```js
-  this.#shader_switches = this.#shader_switches
-      .with(SHADOW_DIRECTIONAL_TECHNIQUE, this.feature_virtual_shadow_maps ? ShadowDirectionalTechnique.Virtual : ShadowDirectionalTechnique.Cascades)
-      .with(INDIRECT_LIGHTING, this.indirect_lighting_mode)                                   // stage 2
-      .with(LOCAL_LIGHT_SHADING, this.feature_restir_di_enabled ? LocalLightShading.ReSTIR : LocalLightShading.Clustered); // stage 2
-  ```
-
-  This allocates nothing while the flags are unchanged.
-- **How it reaches owners.** Each owner is handed it the way it is handed `indirect_lighting_mode` today: the deferred
-  pass in the Renderer, the volumetrics and transparency graph functions through their options, water through its
-  draw call. An owner passes the set opaquely to `variant()`. It never learns which switches its shaders contain, and
-  in stage 2 the set replaces the `indirect_lighting_mode` parameter it carries today.
-- **A per-pipeline choice.** An owner asks for it explicitly, with `shader.variant(switches.with(X, v))`, for example a
-  debug view that forces cascades.
-- **A forgotten set.** With D3 an owner that forgets to pass the set draws the all-defaults variant, silently. That is the price of
-  defaults. The domain is enumerable, so a review can list every shader with non-empty `switches` and check that its
-  owner calls `variant`.
-
-### 4.5 Caching and keys
-
-- **Shader level:** by set identity, then by the restricted set (§4.3).
-- **GPU pipeline managers: unchanged.** `RenderPipelineManager` and `ComputePipelineManager` key by descriptor, which
-  includes the WGSL text and the label. Distinct variants are distinct pipelines. Sets differing only in switches a
-  shader does not have share one, because the variant is restricted to the shader's own switches first.
-  - *Corrected in stage 2:* sets that produce the same text through different values do not share. LPV and IBL on
-    the transparent paths and water link the same code, but D7 puts the set in the label and descriptor equality
-    compares labels, so LPV gets its own pipeline: one extra compile when LPV is switched on.
-- **What affects what.** `descriptor.switches` lists a shader's switches, and `TemplatePassDescriptor.switches_of(template)`
-  does the same per template, since a template's own chunks may hold a choice. "Which pipelines does flipping X
-  recompile" is the set of shaders whose `switches` include X.
-
-### 4.6 Preparation, and a flip
-
-- **Offers.** The Renderer offers `shader.variant(this.#shader_switches).pipeline` and hands the set to the `enquire_*`
-  functions, so only the selected variants are prepared.
-- **When the set changes**, nothing extra happens (D6). The first frame that draws with the new set makes its
-  variants through `obtain`, synchronously, as a feature turned on after `initialize()` does today. That is about 1 s
-  cold for the deferred shader. The shadow records and the shaders flip in that same frame.
-- **Speculative offers.** The domain is enumerable, so a settings screen can offer the other value in the background to
-  make flips instant.
-
-### 4.7 Specs
-
-- **Existing specs keep passing.** With D3 they test the all-defaults variant, and the whole shade suite (877 files) passes on the
-  prototype unchanged.
-- **New specs per switched shader:** "every value validates as WGSL", a plain `for` over `switch.values` inside one test,
-  not `.each`.
-- **Chunk-level harnesses** that compile a graph containing a choice call `specialize(set)` first. The linker refuses
-  one that does not.
-
-## 5. Resources: the long-term half
-
-### 5.1 What differs between alternatives today
-
-| fork | bindings only one mode has | does the resource exist in the other modes? |
-|---|---|---|
-| AVBOIT draw, MBOIT resolve | `brick4` (in the view group) | yes: `Brick4LightMap` creates its buffer in its constructor, per scene |
-| water finalize | `brick4`, `view` (an extra group) | yes |
-| SSR resolve (`build_ssr_resolve_shader` factory) | IBL `tEnvironment`; Brick4 `brick4`, `tSTBN_vec2`; LPV `tEnvironment` + 2 textures, 3 buffers + 1 uniform | Brick4, STBN and LPV's buffers yes; LPV's atlas textures only once LPV runs |
-| froxel GI (a module per mode) | IBL `environment_sh`; Brick4 `brick4`; LPV 3 buffers + 1 uniform | yes |
-| deferred heavy/ReSTIR (factory) | `tRestirRadiance` | only when ReSTIR runs |
-
-*Corrected in stage 2:* LPV's buffers exist in every mode. `GPUSceneContext`'s constructor makes the
-`GPULightProbeVolume` beside the `Brick4LightMap`, and its buffers are created there at a reserved minimum (one probe,
-one tetrahedron, a BVH root). Only the atlas textures wait: a `GPUTextureContext` allocates on first use, and nothing
-uses them outside LPV.
-
-Mode-specific bindings cannot simply get a group of their own. The raster passes already use groups 0–3 (material,
-scene, view, lights), which is all WebGPU guarantees (`maxBindGroups` defaults to 4, and the device floor does not
-raise it).
-
-### 5.2 Recommended: one interface per definition, the union of its alternatives'
-
-A switched shader's resource set declares every binding any of its alternatives reads. Switches then change code only,
-never the interface (D4 holds forever, not just in stage 1). It follows that:
-
-- **Layouts don't depend on the set.** The shared groups (`SHADING_LIGHT_RESOURCE_GROUP`, `FORWARD_LIGHT_LAYOUT`) and the
-  bind groups built from them stay shared across variants and passes. A layout may list a binding the selected variant
-  does not read; WebGPU allows that.
-- **Owners bind by name.** `group.generateBindings(map, encoder)` already does this, and every pass becomes
-  "pass what you have". The positional `use_brick4 ? [ … ] : [ … ]` arrays in the AVBOIT and MBOIT owners go.
-- **A binding a mode lacks falls back to its declared default.**
-  - Textures already take one: `addTexture(…, BLACK_PIXEL_TEXTURE)` is in use. `tRestirRadiance` defaults to black.
-  - Storage buffers have no default parameter today. One convention would be added: `addStorageBuffer(name, type,
-    write, default_value)`, with the engine's zero buffer of the type's minimum size. LPV's three buffers need it.
-  - *As built in stage 2, your option B on the frame graph path only:* `addStorageBuffer(name, type, write,
-    transient_default)`. The declaration says only whether the convention applies. A frame graph pass given nothing
-    for such a binding binds a transient storage buffer of the type's minimum binding size from the frame's pool, so
-    there is no buffer to keep and no lifecycle. Its contents are whatever the pooled buffer last held, so it may
-    only stand in for a binding the selected variant does not read, and an assert checks exactly that: the module
-    names the binding nowhere but its declaration, comments aside. A pass that binds by hand (`generateBindings`)
-    gets no default and is told so.
-  - Owners pass only what the running mode has. The Renderer hands SSR and froxel GI Brick4's map, or the light
-    probe volume, only while that mode runs. AVBOIT, MBOIT and water bind by hand and pass Brick4's buffer, which
-    exists in every mode (§5.1).
-  - Textures: `tRestirRadiance` and LPV's `lpv_atlas_depth` default to `BLACK_PIXEL_TEXTURE`, and
-    `lpv_atlas_radiance`, a `uint` binding, to a new one-texel `r32uint` zero, `ZERO_UINT_PIXEL_TEXTURE`. LPV's
-    `lpv_metadata` uniform defaults to a volume of no probes.
-
-**Measured in stage 2 (§12.2):** an unread binding in a layout costs nothing measurable at draw time. The AVBOIT draw
-and the SSR resolve take the same GPU time with the union of bindings as with their own mode's.
-
-### 5.3 Later, and optional: chunks declare the bindings they read
-
-Today `chunk_shade_directional_lights` says in prose that it "relies on the `light_data` storage binding and the shadow
-atlas bindings being present". `chunk_water_gi_brick4` says "Expects `brick4` and `view`". These are implicit
-dependencies, of the same kind as water's hidden GI function.
-
-A chunk would declare them through a channel beside `addExtension`: `chunk.requireResource(RESOURCE_BRICK4)`, with the
-resource descriptor exported once. `compile()` collects them over the static graph as it collects extensions, and
-`ShaderDescriptor` checks each against its resource set by name and type. The error names both: "`chunk_brick4_sample_*`
-reads `brick4`, which `AVBOIT / draw` does not bind".
-
-With switches, a variant's required set is then known exactly. Migration is chunk by chunk, since an undeclared read
-works as it does today.
-
-### 5.4 Considered and not recommended
-
-- **Resources chosen by switch, per variant.** A group, or entries within one, would change with the set, so each
-  variant binds only what it reads. Shared groups would stop being shared whenever a variant read less than all of
-  one, and owners would build a bind group per variant. It buys nothing measured.
-- **A group per mode.** It does not fit in 4 groups.
-
-## 6. Migration, in three stages
-
-Each stage is a set of one-concern commits, red-then-green where it fixes something.
-
-### Stage 1: the mechanism and shadows (code-only)
-
-1. The compiler layer as prototyped: `ShaderSwitch`, `ShaderSwitchSet`, `CodeChunkChoice`, `specialize`,
-   `collectSwitches`, and `variant` on `ShaderDescriptor`, `ImageShader` and `ComputeShader`.
-2. `TemplatePassDescriptor.variant` and `build(template, set)`. `.pipeline` reads for layout become `pipeline_layout`.
-   Water's finalize builder takes a set.
-3. Shadows:
-   - add `ShadowDirectionalTechnique { Cascades: 0, Virtual: 1 }` and
-     `SHADOW_DIRECTIONAL_TECHNIQUE = ShaderSwitch.enum('shadow directional technique', ShadowDirectionalTechnique)`;
-   - split `_cascades` (today's function without the virtual branch) from `_virtual` (record read; NULL → 1.0; else
-     `shadowmap_sample_virtual`);
-   - make `chunk_shadowmap_sample_directional` the choice. Nothing above it changes.
-4. The Renderer builds `#shader_switches` and hands it to:
-   - the deferred pass;
-   - volumetrics build-lighting and build-irradiance;
-   - AVBOIT and MBOIT;
-   - water;
-   - the `enquire_*` functions.
-
-5. Specs: about a dozen that compile these shaders directly gain a loop over the technique.
-
-### Stage 2: resources, and the forks that needed them
-
-Every step below is "one definition, one choice, bind by name".
-
-- **`INDIRECT_LIGHTING = ShaderSwitch.enum('indirect lighting', ShadeIndirectLightingMode)`**, the enum as it is, with IBL
-  as 0.
-  - **Forward fragment:** one `chunk_forward_shade_standard_fragment` calling `forward_sample_indirect(…)`. A choice
-    provides it: IBL → environment, Brick4 → `brick4_sample_forward_indirect`, LPV → environment. This replaces the
-    178/185-line twins.
-  - **AVBOIT and MBOIT:** one draw and one resolve, each with `brick4` in the view group. The `_ibl`/`_brick4` exports and
-    the branch on `indirect_lighting_mode` in both owners go.
-  - **Water:** one finalize shader. `chunk_water_gi` is a choice, and `finalize_body` lists it as a dependency, so the
-    hidden dependency becomes explicit.
-  - **SSR resolve:** one shader. `ssr_sample_radiance` (and `ssr_sample_hit_irradiance`) are choices, and
-    `build_ssr_resolve_shader` goes.
-  - **Froxel GI:** one shader whose per-froxel radiance lookup is a choice; the three modules become three alternatives.
-- **`LOCAL_LIGHT_SHADING = ShaderSwitch.enum('local light shading', LocalLightShading)`**, `{ Clustered: 0, ReSTIR: 1 }`. The deferred body depends on a choice between
-  `chunk_shade_standard_material_direct` and `_restir`. `tRestirRadiance` defaults to black.
-  `build_deferred_main_shader` and `shader_deferred_main_restir` go. The forward paths keep linking the clustered chunk
-  directly, so they never depend on the switch.
-- **The storage-buffer default convention** (§5.2), for LPV's buffers. *Built on the frame graph path only (§5.2).*
-- **Measure:** the transparent pass and SSR before and after, by the paired method.
-
-### Stage 3 (optional): declared bindings
-
-`requireResource` and the link-time check (§5.3), then chunk by chunk, starting with the ones that say "relies on" or
-"expects" in prose. *Built for every chunk the switched shaders link (§12.3).*
-
-### What goes away, in total
-
-- **Duplicate code:**
-  - the forward fragment twins;
-  - the AVBOIT and MBOIT export pairs;
-  - the water finalize pair;
-  - two per-mode SSR wrappers and three froxel GI modules, which become alternatives;
-  - `shader_deferred_main_restir`.
-- **Factories:** `build_deferred_main_shader` and `build_ssr_resolve_shader`.
-- **Owner branches:** five `switch`/`?:` on `indirect_lighting_mode`, two positional bind-entry pairs, and the
-  `indirect_lighting_mode` parameter threaded through those owners.
-- **A runtime branch:** the per-light shadow technique branch, worth 4–6 % of the deferred pass.
-
-## 7. Prototype and measurements
-
-### Specs, 33 new tests
-
-- `compiler/ShaderSwitch.spec.js`, 4 tests: an enum's members in declaration order with default 0; a bool's
-  `false`/`true` with default `false`; an enum without a 0 member refused; repeated values refused.
-- `compiler/CodeChunkChoice.spec.js`, 16 tests:
-  - only the selected closure is linked;
-  - an unnamed enum switch is 0, an unnamed bool `false`;
-  - an enum with gaps between its values;
-  - a choice three chunks deep needs one copy of each chunk above it;
-  - a shared chunk stays one chunk;
-  - topological order;
-  - a static graph is its own specialization;
-  - the linker refuses a choice;
-  - discovery from above;
-  - a switch nested in one alternative, and one with 3 values;
-  - an alternative that is a choice;
-  - one switch at two places;
-  - a missing alternative names the switch and the member;
-  - cycles;
-  - identity.
-- `compiler/ShaderSwitchSet.spec.js`, 5 tests: interning regardless of order; a default is not stored; a changed
-  value; restriction; `toString` names the members.
-- `ShaderDescriptor.spec.js`, 4 tests: domain found two chunks down; `source` is the all-defaults variant; a variant
-  links one alternative, has no switches and is labelled `… technique=Virtual`; sets that agree share a variant, and
-  the empty set gives the descriptor itself.
-- `ImageShader.spec.js`, 2 tests, and `ComputeShader.spec.js`, 2 tests: the variant's pipeline code and targets, caching,
-  `this` for all-defaults, and a variant with another `@workgroup_size` refused.
-
-### The real deferred shader
-
-A scratch probe (`scratchpad/probe/shadow_choice.probe.js`, not in the tree) rebuilds the four chunks above
-`chunk_shadowmap_sample_directional` from their real `.text` and dependency lists, with the choice in its place. In the
-engine they would not change at all.
-
-| | characters | functions | engine validator | Tint (Chrome, RTX 4090) | vs shipped |
-|---|---|---|---|---|---|
-| shipped (both paths) | 69,917 | 96 | pass | 0 messages | |
-| cascades | 59,892 | 82 | pass | 0 messages | −14 VSM functions, −4 VSM structs/consts; only `shadowmap_sample_directional` changed |
-| virtual | 62,682 | 94 | pass | 0 messages | −`shadowmap_csm_compute_cascade_blended` and its row read, −2 structs; only `shadowmap_sample_directional` changed |
-
-- **Link time**, median of 200 interleaved runs: today's `compile()` 0.079 / 0.083 ms in two runs; `specialize` +
-  `compile()` of a variant 0.075 / 0.083 ms.
-- **`variant(set)` with a set already seen:** 0.1 µs.
-- **Pipeline creation** (`tint_check.mjs`):
-  - **Method.** `createRenderPipelineAsync` with the deferred pass's vertex stage, target and depth state, and
-    `layout: 'auto'`. One at a time, rotating order, 8 rounds. A fresh seed constant per compile, so neither Dawn's
-    nor the driver's cache serves it.
-  - **Results.** Two runs: shipped 1251 / 1225 ms, cascades 1009 / 1017 ms (0.81× / 0.83×), virtual 877 / 810 ms
-    (0.70× / 0.66×).
-  - **Caveat.** This is wall time on a busy box, not the trace's `InitializeImpl`, so it compares with the earlier
-    twins (0.78× / 0.66×) by ratio only.
-- **GPU time was not re-measured.** The 0.936× / 0.957× were measured on twins built by the same removals. The cascades
-  variant is that twin. The virtual variant is the twin's branch inverted (`== NULL → 1.0` first).
-
-## 8. Costs
-
-| part | size |
-|---|---|
-| prototype as it stands | 3 classes (540 lines with docs); `CodeChunk` +135; `ShaderDescriptor` +67/−1; `ImageShader` +51; `ComputeShader` +49; 6 spec files (504 lines) |
-| rest of stage 1 (estimate) | `TemplatePassDescriptor` (~50), water builder, Renderer set + plumbing to the owners and the enquiries (~100), shadow split (1 file into 3), ~12 specs |
-| stage 2 (estimate) | the steps of §6 stage 2, each mostly deletion. Expected net negative in lines, not counted. |
-
-Runtime:
-
-- No per-frame allocation once the set is steady.
-- A lookup is 0.1 µs, and a variant costs 0.075–0.083 ms to specialize and link.
-- A flip compiles the affected variants on first use (D6). The old ones stay cached.
-
-Risks:
-
-- **A forgotten set draws the all-defaults variant silently (§4.4).**
-- **Errors move to first use.** A broken non-zero alternative only shows when a pipeline is made. The per-value specs
-  catch it.
-
-## 9. Reuse map
-
-| piece | reuses / generalises |
-|---|---|
-| specialization | `CodeChunk`'s own graph and private fields, with the same identity-based dedup the linker relies on. No second linker; `compile()` is untouched. |
-| values | engine enums as they are (`ShadeIndirectLightingMode` unchanged), or a bool. Like Unreal's enum/bool/sparse-int permutation dimensions, an enum need not be contiguous. |
-| variant objects | `ShaderDescriptor`, `ImageShader`, `ComputeShader` and `TemplatePassDescriptor` themselves. A variant is one of them, so draw, dispatch, validation and the profiler need nothing new. |
-| GPU pipeline cache | `RenderPipelineManager` / `ComputePipelineManager` unchanged. Text equality separates and shares variants. |
-| preparation | `PipelineEnquiry` and `prepare()` at start-up, offering the selected variants. A flip uses `obtain` as anything made on first use does. |
-| bind by name | `ShaderResourceGroupDescriptor.generateBindings`, and texture `default_value` (`BLACK_PIXEL_TEXTURE`). One new default convention, for storage buffers. |
-| declared bindings (stage 3) | the `addExtension` / `addLanguageExtension` channel: collected at link, the same way. |
-| `ProgrammableStage.constants` | left for what `override` is for: numbers. Not for choosing code. |
-
-## 10. Candidates considered (revision a)
-
-- **A: a switch is the choice.** The value is an alternative chunk, and each place where the graph chooses is its own
-  switch. It would make the renderer name every place a decision is made. Superseded by D1.
-- **B: open slots filled by whoever builds the shader.** This is Unreal's vertex-factory include, naga_oil's
-  `override fn`, Slang's `extern`/`export`, and today's water GI. Nothing can enumerate a slot's implementations, so
-  preparation and specs cannot loop over variants. Material templates already are the engine's open interface.
-- **C: a switch decided at choices in the graph.** This is the design above, now with enum and bool values (D1, D9), a
-  static graph per variant (D2) and a default (D3).
-- **Rejected before this proposal:** WGSL `override` constants. They hide the dependency, and the spec keeps a function
-  reached through a false override `if` in the shader, its bindings included.
-
-## 11. Open questions for Alex
-
-The design questions are closed (D1–D9). An enum must have a member equal to 0, a rule Alex kept. Stage 1 landed as
-four one-concern commits:
-
-1. the compiler layer;
-2. the shader classes' `variant`;
-3. `TemplatePassDescriptor`'s;
-4. the shadow switch with the renderer's set and its plumbing.
-
-Stage 2 landed as seven, with the storage-buffer default as you chose it: option B, on the frame graph path only
-(§5.2).
-
-Stage 3 is built and checked (§12.3), uncommitted. Open: landing, proposed as five one-concern commits,
-master-direct:
-
-1. a resource's declaration apart from its placement (`ShaderResourceDescriptor`'s factories, `group.add`,
-   `isSatisfiedBy`);
-2. chunks declare the bindings they read, and a shader's link checks them (`requireResource`);
-3. six shaders bind what their chunks read: the SDF build, screen-space shadows, the four lightmap debug views;
-4. the switched shaders' chunks declare their bindings, with the audit spec;
-5. this document.
-
-Also open from stage 3: how the sky reaches water's optics chunks, so they can list the GI they call (§12.3).
-
-## 12. As built
-
-### 12.1 Stage 1, as landed (2026-10-16)
-
-#### What it contains
-
-- **The mechanism:**
-  - `ShaderSwitch` (`enum` / `bool`), `ShaderSwitchSet` and `CodeChunkChoice`;
-  - `CodeChunk.specialize` and `collectSwitches`;
-  - `variant(set)` on `ShaderDescriptor`, `ImageShader`, `ComputeShader` and `TemplatePassDescriptor`.
-
-  A `TemplatePassDescriptor` build is now `(template, switches)`. The four transparent passes that light fragments
-  build `….variant(switches)`, and their pipeline labels carry the set. Owners read a template pass's layout through
-  `pipeline_layout`, so a variant needs no pipeline of its own.
-- **The shadow switch:**
-  - `ShadowDirectionalTechnique { Cascades: 0, Virtual: 1 }`;
-  - `SHADOW_DIRECTIONAL_TECHNIQUE = ShaderSwitch.enum('shadow directional technique', ShadowDirectionalTechnique)`;
-  - `chunk_shadowmap_sample_directional_cascades` and `chunk_shadowmap_sample_directional_virtual`.
-
-  `chunk_shadowmap_sample_directional` is now the choice between those two alternatives. No chunk above it changed.
-- **The renderer:**
-  - `Renderer.#shader_switches` follows `feature_virtual_shadow_maps`. It is updated in `#draw_to_target`, beside the
-    shadow context's own flag, and in `enquirePipelines`, and readable as `renderer.shader_switches`.
-  - It is handed to:
-    - the deferred pass;
-    - `GPUViewVolumetrics.graph_update`, which passes it to froxel irradiance and light scattering;
-    - the AVBOIT orchestrator, which passes it to the draw pass and to each side channel's `avboit_prepare` (water);
-    - the MBOIT orchestrator, for its resolve pass.
-- **Water:** `create_water_finalize_pipeline_ibl/brick4(switches)`, and `GPUWaterRenderer` caches the result per GI mode
-  and set.
-
-#### Tests
-
-- **`shadow_directional_technique_consumers.spec.js`** covers all nine shaders under both techniques. In each, exactly
-  the selected technique's sampling is linked, the other's is absent, and the module passes the WGSL checks. With every
-  switch at its default, the result is cascades.
-- **`TemplatePassDescriptor.spec.js`** (3 tests): a variant builds each template for its set; one variant per set, and
-  the pass itself for the empty set; a variant shares its original's attachments and layout.
-- **The AVBOIT orchestrator spec** gained a test on the software device: water's optics pipeline, as recorded on the
-  device, links the technique of the set the orchestrator was handed. It fails if the orchestrator stops passing the set
-  to side channels (checked).
-- **Five chunk-level harnesses now specialize before linking**, which the linker requires:
-  - the cascades harness to Cascades;
-  - the VSM harness to Virtual — 4 of its 6 tests fail if it is built for Cascades instead (checked);
-  - the normal-decode harness and the two water-optics harnesses to the default.
-- **Gates:** the shade suite passes, 879 files and 6,744 tests. `check-types` reads 18 against the base's 18.
-
-#### Device check (one-off, headless Chrome, RTX 4090)
-
-The stage-1 tree and its base (`03d5816bd`) were served side by side.
-
-- **VSM playground (deferred lighting).**
-  - Stage 1 makes two shadow-sampling pipelines: `Shade From G-Buffer`, cascades only, offered at start-up; and
-    `Shade From G-Buffer [shadow directional technique=Virtual]`, virtual only. No pipeline links both.
-  - The base makes one pipeline that links both.
-- **Images.** Stage 1 against the base differs in no more pixels than the base against itself, with the playground's
-  movers animating and the filter jittered per frame:
-
-  | technique | stage 1 vs base | base vs base |
-  |---|---|---|
-  | cascades | 6.3 % of pixels | 7.4 % |
-  | virtual | 5.5 % of pixels | 7.8 % |
-
-- **The same playground with a fog volume added from the page (deferred + volumetric lighting).**
-  - Stage 1 adds `Volumetrics / build lighting`, cascades only, and `Volumetrics / build lighting [shadow directional
-    technique=Virtual]`, virtual only. The base has one, which links both.
-  - The fog's per-frame jitter moves most pixels by a level or two, in both comparisons alike:
-
-    | technique | stage 1 vs base: pixels off by > 8 levels (mean max-channel difference) | base vs base |
-    |---|---|---|
-    | cascades | 5.97 % (4.32) | 5.70 % (4.33) |
-    | virtual | 6.00 % (4.38) | 5.81 % (4.44) |
-- **Console errors.** `vsm: feedback readback failed` appears only after a tab is closed, on the base as on stage 1.
-  It is a readback cut short by the close.
-
-Not checked on the device:
-
-- **water and MBOIT,** whose playground does not expose its renderer for the flip. They are covered on the software
-  device and by the consumer spec.
-- **GPU time of the variants.** The 0.936× / 0.957× of revision (a) were measured on equivalent twins.
-
-### 12.2 Stage 2, as landed (2026-10-16, `6e263855d`..`e354def85`)
-
-#### What it contains
-
-- **Two switches,** set by the Renderer's `#update_shader_switches` beside the shadow technique:
-  - `INDIRECT_LIGHTING = ShaderSwitch.enum('indirect lighting', ShadeIndirectLightingMode)`, from
-    `indirect_lighting_mode`;
-  - `LOCAL_LIGHT_SHADING = ShaderSwitch.enum('local light shading', LocalLightShading)`, `{ Clustered: 0, ReSTIR: 1 }`,
-    from `feature_restir_di_enabled`.
-- **Six choices,** each where a graph asks for the light:
-
-  | choice | IBL | Brick4 | LPV |
-  |---|---|---|---|
-  | `chunk_forward_sample_indirect` | environment | `brick4_sample_forward_indirect` | environment |
-  | `chunk_water_gi` (now listed by `finalize_body`) | `chunk_water_gi_ibl` | `chunk_water_gi_brick4` | `chunk_water_gi_ibl` |
-  | `chunk_ssr_sample_radiance` | environment | `brick4_sample_specular` | `lpv_sample_radiance` |
-  | `chunk_ssr_add_hit_irradiance` | nothing | nothing | the LPV bounce at the hit |
-  | `chunk_volumetrics_gi_sample` | `environment_sh` | `brick4_sample_sh` | the LPV mesh |
-
-  and `chunk_shade_standard_material_direct_deferred` on `LOCAL_LIGHT_SHADING`: the clustered chunk, or `_restir`.
-- **One definition each:** `chunk_forward_shade_standard_fragment`, `shader_avboit_draw`, `shader_oit_resolve_moments`,
-  `water_finalize_shader` (`create_water_finalize_pipeline(switches)`), `ssr_resolve_shader`, `shader_volumetrics_gi`,
-  `shader_deferred_main`. Each declares the union of its alternatives' bindings.
-- **Gone:** the forward twins; `shader_avboit_draw_ibl`/`_brick4`; `shader_oit_resolve_moments_ibl`; water's `_ibl`/
-  `_brick4` shaders, pipelines and resource sets; `build_ssr_resolve_shader` and the three per-mode resolves; the
-  three froxel GI modules; `build_deferred_main_shader` and `shader_deferred_main_restir`.
-- **Owners:** no pass below the Renderer takes `indirect_lighting_mode` any more. The AVBOIT orchestrator, its side
-  channels' `avboit_prepare`, the MBOIT orchestrator, `GPUViewVolumetrics.graph_update` and `SSR.graph_pass` take the
-  set alone.
-  - AVBOIT and MBOIT bind their view group by name (`AVBOIT_DRAW_VIEW_GROUP`, `OIT_RESOLVE_VIEW_GROUP`, through
-    `generateBindings`). The positional pairs are gone.
-  - SSR and froxel GI take Brick4's map and the light probe volume as optional sources, and the Renderer hands them
-    the running mode's alone. Another mode's bindings are the shader's defaults (§5.2).
-  - Water binds Brick4's buffer and the view in every mode, by hand: both exist in every mode.
-  - SSR restarts its history when its resolve variant changes, where it used to compare modes.
-  - The Renderer's own branches on the mode stay: they pick passes, not shaders (the diffuse/specular pair, Brick4's
-    fused pass, the enquiry, the LPV update).
-- **Defaults** (§5.2): storage buffers with a transient default (`brick4` in SSR and froxel GI, and the LPV's three
-  buffers through `LPV_SHADER_RESOURCE_GROUP_WITH_DEFAULTS`, a twin of the shared group that the passes which always
-  bind the volume keep using); `lpv_metadata` a volume of no probes; `tRestirRadiance` and `lpv_atlas_depth`
-  `BLACK_PIXEL_TEXTURE`; `lpv_atlas_radiance` the new `ZERO_UINT_PIXEL_TEXTURE`.
-
-#### What changed in the code
-
-Every variant was diffed against the shader it replaces, declaration by declaration, with the order-dependent
-`Struct_N` names normalised:
-
-- **Same code:** water's optics under Brick4, the AVBOIT Brick4 vertex stage, and deferred ReSTIR.
-- **One wrapper function more** (`forward_sample_indirect`, `volumetrics_gi_sample`, `ssr_add_hit_irradiance`), which
-  the caller now calls in place of the code it wrapped: the transparent passes, SSR and froxel GI.
-- **Declarations only:** the union's bindings, and binding numbers shifted to make room for them. Deferred
-  (clustered) gains `tRestirRadiance`.
-
-#### Tests
-
-- **`indirect_lighting_consumers.spec.js`** (5 tests): the AVBOIT draw and MBOIT resolve for the standard template,
-  water's optics, SSR's resolve and froxel GI, under every mode. Each variant links only its mode's sampling, passes
-  the WGSL checks, and has the same layout or resources as every other mode's; with every switch at its default the
-  result is IBL.
-- **`shader_deferred_main.spec.js`** (3 tests): each way of shading local lights links its own code, and the two bind
-  alike with `tRestirRadiance` black by default.
-- **`storage_buffer_transient_default.spec.js`** (4 tests, software device): a pass given nothing binds a transient
-  buffer of the minimum binding size; a pass given the buffer binds it; a shader that reads a binding left to its
-  default is refused; binding by hand, the default is no default. Each fails with its piece of the mechanism
-  disabled (checked).
-- **Owners pass the running mode's source alone:** `SSR.spec.js` and `graph_build_froxel_gi.spec.js` check, per mode,
-  that the pass binds that mode's source and no other's, and that the frame then submits on the software device.
-  An owner binding another mode's source, as option A would have, fails them (checked).
-- **Water's dependency is pinned:** taking `chunk_water_gi` back out of `finalize_body` fails the consumer spec's water
-  test and both water optics rows of `water_shaders_wgsl_validity.spec.js` (checked).
-- **The AVBOIT orchestrator spec** gained a test on the software device: water's optics are drawn with the mode of the
-  set the orchestrator is handed, and bind every mode's resources by name without an error.
-- **`shadow_directional_technique_consumers.spec.js`** now crosses the shadow technique with every indirect lighting
-  mode and both ways of shading local lights. Fifteen other specs follow the renames.
-- **Gates:** the shade suite passes, 894 files and 6,787 tests. `check-types` reads 18, the same as the base.
-
-#### Device checks (one-off, headless Chrome, RTX 4090)
-
-- **One mode per pipeline.** A probe recorded every pipeline's WGSL while the avboit, water_refraction and
-  particle_ecs playgrounds were switched through IBL, Brick4 and LPV, AVBOIT and MBOIT, with SSR and then ReSTIR on.
-  Every pipeline of a switched shader links exactly one mode's sampling:
-
-  | shader | pipelines |
-  |---|---|
-  | AVBOIT draw, MBOIT resolve, water optics | the default (environment), `[indirect lighting=Brick4]` (Brick4), `[indirect lighting=LPV]` (environment) |
-  | SSR resolve | one per mode, each linking only its own |
-  | Volumetrics / GI | one per mode, each linking only its own |
-  | Shade From G-Buffer | the default (clustered), `[local light shading=ReSTIR]` (ReSTIR) |
-
-  No compilation or validation errors came from these shaders, with option B's defaults standing in for the other
-  modes' sources in SSR and froxel GI (run again after B).
-- **GPU time, before and after.** A bench copy of the tree held both paths, the old per-mode shader with its own
-  bindings and the new one with the union, and its owners picked one per frame. Arms alternated in blocks of four
-  frames inside one capture, the first frame of each block dropped, with four captures per setting in alternating
-  order (`ab_drive`). Frames were checked to have drawn the arm's own pass. Spans are quantised to 1.024 µs, so the
-  medians are what can be read:
-
-  | pass | setting | median, old / new | captures |
-  |---|---|---|---|
-  | AVBOIT draw | IBL, avboit playground | 1.000 | 4 of 4 |
-  | AVBOIT draw | Brick4 | 1.000 | 4 of 4 |
-  | SSR resolve | IBL, ssr_reprojection, lateral and still, 1280 | 1.000 | 7 of 8; the eighth 0.976, one quantum |
-  | SSR resolve | Brick4, lateral | 1.000 in one capture, 1.018 (one quantum) in three | 4 |
-
-  Pass times were about 59 µs (AVBOIT IBL), 66–69 µs (AVBOIT Brick4), 42 µs (SSR IBL) and 56–57 µs (SSR Brick4).
-  The avboit playground found no environment map on this machine and lit the scene by its own lights alone.
-  These were taken before option B, with the scene's buffers in the entries the variant does not read; B puts
-  transient buffers there instead, which changes nothing the shader reads.
-
-#### Found along the way, not changed
-
-- **ReSTIR DI's resample and spatial passes do not compile in Chrome.** `WEIGHT_LIMIT = 3.4028235e38` in
-  `restir/reservoir/shader.js` rounds above the largest f32, and Tint refuses it. This predates stage 2 (`57e2f80b2`).
-  The deferred pass's ReSTIR variant itself compiles.
-- **`chunk_water_inscatter` and `chunk_water_receiver_downwelling`** still call `water_gi_irradiance` without listing
-  a dependency. Their spec harnesses supply a stub. `finalize_body` lists `chunk_water_gi`, so the shader's graph
-  is explicit.
-- **LPV's transparent and water variants** are separate pipelines with the same code as IBL's (§4.5's correction).
-
-### 12.3 Stage 3, as built (2026-10-16, uncommitted)
-
-#### What it contains
-
-- **A declaration apart from its placement.** `ShaderResourceDescriptor.uniform`, `.storageBuffer`, `.texture`,
-  `.storageTexture` and `.sampler` make a declaration alone: name, kind, type, default. The group's `addX` methods call
-  them, and `group.add(declaration)` places a copy (`clone_declaration`), so one declaration sits in any number of
-  groups at their own binding indices and visibilities.
-- **What satisfies a declaration** (`isSatisfiedBy`): a binding of the same name and WGSL type with at least the
-  declared access. A read-only storage buffer is satisfied by a read-write one, a `float` texture by an
-  `unfilterable-float` one; `depth` is a type of its own; a sampler is a comparison sampler or not; a storage texture
-  keeps its format and dimension, with its access a subset. Placement, visibility and defaults do not count.
-- **The channel,** beside `addExtension`: `CodeChunk.requireResource(declaration)`, read back through
-  `required_resources`. `specialize` and `copy` carry it, and a choice refuses one, since it has no text to read
-  with. `compile()` returns `resources`: each declaration once, with the first chunk in link order that declared it.
-- **The check.** `ShaderDescriptor.compile()` looks each declaration up in its resource set by name:
-  - unbound: `'light_count' reads 'light_data', which 'test unbound' does not bind`;
-  - mistyped: `… reads 'light_data' as a read-only-storage buffer of array< u32 >, which 'test mistyped' binds as a
-    2d unfilterable-float texture`.
-  
-  Image, compute and template shaders all compile through it, so a variant checks only what its selected
-  alternatives declare. It throws rather than asserts: it runs once per variant, at link.
-- **`ShaderDescriptor.body`,** the graph a shader links, choices still in it.
-- **Declarations, exported where the data lives:**
-
-  | file | declarations |
-  |---|---|
-  | `camera/CAMERA_RESOURCE.js`, `view/VIEW_RESOURCE.js` | `camera`, `view` |
-  | `light/LIGHT_DATA_RESOURCE.js`, `light/cluster/LIGHT_CLUSTER_RESOURCES.js` | `light_data`; `cluster_parameters`, `cluster_lookup`, `cluster_data` |
-  | `light/environment/ENVIRONMENT_MAP_RESOURCE.js`, `ENVIRONMENT_SH_RESOURCE.js` | `tEnvironment`, `environment_sh` |
-  | `shadow/map/SHADOWMAP_RESOURCES.js` | `shadowmapAtlas`, `sCompareLinear` |
-  | `global_illumination/brick4/gpu/BRICK4_RESOURCE.js`, `…/octahedral/LPV_SHADER_RESOURCE_GROUP.js` | `brick4`; the light probe volume's six |
-  | `STATIC_GRAPHICS_ENGINE_ASSET_RESOURCES.js`, `texture/SAMPLER_LINEAR_RESOURCE.js` | `tSTBN_vec2`, `tSTBN_vec3`, `tSplitSum`; `sLinear` |
-  | `deferred/GBUFFER_RESOURCES.js`, `restir/di/RESTIR_RADIANCE_RESOURCE.js` | `gBufferPBR`, `gBufferAlbedo`, `gBufferEmissive`, `tAlbedoAO`; `tRestirRadiance` |
-  | `volumetrics/VOLUMETRICS_RESOURCES.js`, `…/gi/volumetrics_gi_resources.js`, `chunk_volumetrics_sun_optical_depth.js` | `volumetrics_metadata`, `tVolumetrics`, `tParticipatingMedia1`; `tGIY`, `tGICoCg`; the sun's cascades |
-  | `shader/chunk/screen_space/SCREEN_SPACE_RESOURCES.js` | `tDepth`, `tHZB`, `tNormal` |
-  | `geometry/GEOMETRY_ATTRIBUTE_DATA_RESOURCE.js`, `geometry/meshlet/MESHLET_METADATA_RESOURCE.js`, `scene/SCENE_DATABASE_RESOURCE.js` | `meshlet_data`, `meshlet_metadata`, `scene_database` |
-  | `material/standard/SHADING_MATERIAL_RESOURCE_GROUP.js`, `water/surface/WATER_SURFACE_RESOURCES.js`, `water/shader_water.js` | the standard material's nine; the surface interface's five; water's trace and LOD |
-
-- **Migrated:** every chunk the eight switched shaders link in any variant declares what its own functions read,
-  and so do the sibling chunks in the same files: 56 chunks in 52 files. The prose lists of bindings they replace are gone ("relies on the `light_data` storage
-  binding…", "Bindings it reads: …").
-- **Groups built from the declarations:** `SHADING_LIGHT_RESOURCE_GROUP`, `LPV_SHADER_RESOURCE_GROUP`,
-  `SHADING_MATERIAL_RESOURCE_GROUP`, the froxel GI group, water's resources and the sun's cascades in the lighting pass.
-  Every other group keeps its `addX` calls, which satisfy the declarations by name and type.
-
-#### What changed in the code
-
-Every exported shader and every variant of the switched ones, 406 modules, was linked on the base and on stage 3
-and compared with the `Struct_N` names normalised. 399 are identical. The rest are the six shaders below, which gain
-the bindings their chunks read, and one script's error message (a path).
-
-#### Found and fixed: six shaders that could not compile
-
-A migrated chunk is checked wherever it is linked, and six shaders link one that reads a binding they never bound.
-Tint (headless Chrome, RTX 4090) refuses master's sources for all six: `unresolved value 'meshlet_data'` in the
-geometry SDF build and the four lightmap debug views (`density`, `uv_checker`, `view_flat`, `view_sh`), and
-`unresolved value 'tHZB'` in screen-space shadows. Until now they failed at `createShaderModule`; the check fails
-them at link, and their modules threw on import. None is reached in-tree: `GPUGeometryManager.sdf` throws "Not
-implemented", and nothing imports the other five. Each now binds what its chunks read, appended to its group:
-
-- **Screen-space shadows:** `tHZB`. Compiles on Tint.
-- **Geometry SDF build:** `meshlet_metadata` and `meshlet_data`, and `GPUGeometrySDFManager` passes
-  `geometries.meshlets`' buffers as every other dispatch does. Compiles on Tint.
-- **The lightmap debug views:** the same two buffers, so they import again. On Tint they now stop at `struct member
-  lightmap_uvs not found`: the mesh struct no longer has the field. Not changed.
-
-#### Tests
-
-- **`ShaderResourceDescriptor.spec.js`** (6 tests): what satisfies a declaration, per kind.
-- **`ShaderResourceGroupDescriptor.spec.js`** (+1): one declaration in two groups sits at each group's index, and
-  visibility is the group's.
-- **`CodeChunk.spec.js`** (+1) and **`CodeChunkChoice.spec.js`** (+1): collection at link; a choice refuses a
-  declaration.
-- **`ShaderDescriptor.spec.js`** (+4): unbound and mistyped name the chunk, the binding and the shader; a binding read
-  as declared, or read-write, links the same source as no declaration; a variant checks only its selected alternative.
-- **`switched_shaders_declare_bindings.spec.js`** (7 tests), the audit: every chunk of the eight switched shaders,
-  in every variant, declares exactly the module-scope bindings its own functions read, parsed, with parameters and
-  locals excluded. The shader's body is where its bindings are written, and declares nothing. It failed with 106
-  findings over 50 chunks before the migration.
-- **`GPUGeometrySDFManager.spec.js`:** its geometry manager stand-in gains the meshlet buffers.
-- **Gates:** the shade suite passes, 901 files and 6,833 tests. `check-types` reads 18, the same as the base.
-
-#### Device check (one-off, in-app browser)
-
-The modules are the same text, so the check is that the renderer's pipelines still link and run. The avboit
-playground compiled its nine AVBOIT modules and drew AVBOIT and MBOIT, under IBL and Brick4 each, for 2,038 frames;
-the vsm playground drew cascades and then virtual shadow maps. No uncaptured device error came from either.
-
-#### Found along the way, not changed
-
-- **Water's optics still call `water_gi_irradiance` without a dependency.** Making `chunk_water_gi` their dependency
-  was tried: the shader is unchanged, but the in-scatter oracle and the downwelling spec harnesses supply their own
-  stub through that name, and would then link two definitions, which the emulator tolerates and WGSL does not.
-  Fixing it means a choice of how the sky reaches these chunks: an argument, or a stub chunk the harness specializes in.
-- **The lightmap debug views' `lightmap_uvs`,** above.
-- **Placement derived from the declarations,** the larger change to the shader class this stage anticipated (§5.3):
-  not built. Groups still place their bindings by hand, and declarations only check them.