@woosh/meep-engine 3.47.0 → 3.49.0

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

@@ -0,0 +1,680 @@
+# Shader switches: a proposal (2026-10-16, revision c; stage 1 landed)
+
+**Status: stage 1 is on master (2026-10-16; §12). Stages 2 and 3 are open (§6, §11).**
+
+§0 records your decisions, §4–§6 the design and its stages, and §12 what stage 1 contains and how it was checked:
+the shade suite (879 files, 6,744 tests), `check-types` at the base's 18, and a device run. 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 source or primary docs. Unreal was read in the installed UE 5.4 tree. 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.** `RenderCore/Public/ShaderPermutation.h`. A dimension is a C++ type made by
+`SHADER_PERMUTATION_BOOL` / `_INT` / `_RANGE_INT` / `_SPARSE_INT` / `_ENUM_CLASS`, each carrying a `DefineName`.
+`TShaderPermutationDomain<…>` is their product, and its permutation id is mixed-radix over the dimensions
+(`ToDimensionValueId`). A shader class lists its dimensions. `FDeferredLightPS` (`Renderer/Private/LightRendering.cpp:816`)
+has 14 of them, including `FVirtualShadowMapMask`.
+
+- `ShouldCompilePermutation` culls combinations: a directional light × the VSM mask is never compiled.
+- `RemapPermutation` folds combinations together: visualize-culling forces the others off.
+- `ModifyCompilationEnvironment` adds the VSM defines only when that dimension is on.
+- The draw site sets every dimension by hand (`LightRendering.cpp:2804-2833`), 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*. `FVertexFactoryType::ModifyCompilationEnvironment` maps the virtual include path
+`/Engine/Generated/VertexFactory.ush` to `#include "<this factory's file>"` (`RenderCore/Public/VertexFactory.h:418-420`).
+`/Engine/Generated/Material.ush` is mapped to the generated material code (`Engine/Private/Materials/MaterialShared.cpp:3357`).
+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. Distinct variants are distinct pipelines. Sets that produce the same text share one: LPV and
+  IBL on the transparent paths, or any set differing only in switches a shader does not have.
+- **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` + 3 textures, 3 buffers | Brick4 and STBN yes; LPV's only when LPV runs |
+| froxel GI (a module per mode) | Brick4 `brick4`; LPV its atlas and buffers | Brick4 yes; LPV's only when LPV runs |
+| deferred heavy/ReSTIR (factory) | `tRestirRadiance` | only when ReSTIR runs |
+
+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.
+
+**Unmeasured:** whether an unread binding in a layout costs anything at draw time. I know of no reason it would, and
+`SHADING_LIGHT_RESOURCE_GROUP` is already shared by shaders that do not read all of it. Stage 2 would measure the
+transparent pass before and after.
+
+### 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.
+- **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.
+
+### 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. The shape of Unreal's `SHADER_PERMUTATION_ENUM_CLASS`/`_BOOL`, and like its `SPARSE_INT` 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.
+
+Open: whether stage 2 (§6) follows next, `INDIRECT_LIGHTING` and `LOCAL_LIGHT_SHADING` with the bindings union.
+
+## 12. 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.