@carbonenginejs/runtime-resource 0.11.1 → 0.12.1

package/docs/formats/webgl/decl-io.md

@@ -0,0 +1,1234 @@
+# DXBC -> GLSL ES 3.00 Lowering Spec: `decl-io` Family
+
+Status: Evolving
+Scope: `@carbonenginejs/runtime-resource/formats/webgl` declaration and stage-I/O lowering
+Audience: Shader translator maintainers and reviewers
+Summary: Defines the DXBC declaration and I/O rules used by the GLSL emitter.
+
+Target: GLSL ES 3.00 (WebGL2), vertex + pixel stages only. No SSBOs, no compute, no
+tessellation/geometry stages (facts for those stages are cited where they explain
+*why* a code path in the authority source is skipped, never as things this emitter
+must implement).
+
+Register model for this emitter (differs from stock HLSLcc, stated once here so every
+section below can just say "the float vec4 register file"): every DXBC temp/output
+register is stored as a `vec4` of floats. Instructions that need int or uint semantics
+bitcast at the use site with `floatBitsToInt` / `floatBitsToUint` on read and
+`intBitsToFloat` / `uintBitsToFloat` on write, exactly mirroring the bitcast operator
+names HLSLcc itself uses when it emits its own (non-register-collapsed) integer path
+(`GetBitcastOp`, `vendor/HLSLcc/src/toGLSLOperand.cpp:327-353`). Stock HLSLcc instead
+runs `DataTypeAnalysis` and gives each temp register a native-typed shadow variable
+(`u_xlatN` float, `u_xlatiN` int, `u_xlatuN` uint, ...). This spec calls out every
+place our float-only convention diverges from that stock behavior.
+
+Corpus counts (450k-instruction sweep, 1611 EVE Online DX11 effects), used to order
+sections by real-world impact:
+
+| Opcode | Count |
+|---|---|
+| `dcl_output` | 15197 |
+| `dcl_input` | 11726 |
+| `dcl_constant_buffer` | 10160 |
+| `dcl_input_ps` | 6995 |
+| `dcl_resource` | 6317 |
+| `dcl_global_flags` | 5848 |
+| `dcl_temps` | 5035 |
+| `dcl_sampler` | 3277 |
+| `dcl_output_siv` | 2825 |
+| `dcl_resource_structured` | 684 |
+| `dcl_input_ps_siv` | 538 |
+| `dcl_input_ps_sgv` | 42 |
+| `dcl_input_sgv` | 18 |
+| `dcl_indexable_temp` | 16 |
+| `dcl_input_siv` | 3 |
+| `customdata` | 159 |
+
+All line numbers below refer to `vendor/HLSLcc/src/toGLSLDeclaration.cpp`
+unless another file is named.
+
+---
+
+## Emission order and `#version` boilerplate
+
+Authority: `vendor/HLSLcc/src/toGLSL.cpp`.
+
+HLSLcc builds the final GLSL text as two bstrings that get concatenated at the very
+end (`toGLSL.cpp:1039` region: `// Concat extensions and glsl for the final shader
+code.`):
+
+1. `extensions` — seeded with the version string (`toGLSL.cpp:617`,
+   `GetVersionString(LANG_ES_300)` returns `"#version 300 es\n"` at `toGLSL.cpp:387`),
+   then every `#extension ... : require|enable` line added by `RequireExtension` /
+   `EnableExtension` calls made while walking declarations and instructions.
+2. `glsl` — populated in this order:
+   a. `AddVersionDependentCode` (`toGLSL.cpp:93`, called at `toGLSL.cpp:647`) emits,
+      for pixel shaders on an ES target (`toGLSL.cpp:307-328`):
+      ```
+      precision highp float;
+      precision highp int;
+      ```
+      (int precision is forced to `highp` "to avoid issues on platforms that
+      actually implement mediump" — comment at `toGLSL.cpp:326`). Vertex shaders get
+      no default-precision block from this path.
+   b. If the shader has any constant buffers or textures, two `#define` blocks for
+      `UNITY_LOCATION`/`UNITY_BINDING`/`HLSLCC_ENABLE_UNIFORM_BUFFERS` macros
+      (`toGLSL.cpp:667-691`). These are Unity-build plumbing; a from-scratch JS
+      emitter does not need the macro indirection, only the concrete
+      `layout(std140) uniform ... { vec4 data[N]; } cbN;` text it expands to when the
+      macros are defined to `1` (the emitter should hardcode the "enabled" expansion,
+      not restate the `#if`/`#else` machinery, since WebGL2 has no runtime toggle for
+      it).
+   c. `TranslateDeclaration` for every `Declaration` in bytecode order — this is the
+      entire `decl-io` family plus every other declaration opcode.
+   d. `void main() { ... }` with early-main redirect code, then translated
+      instructions.
+
+**WebGL2 note**: emit exactly `#version 300 es` as line 1, nothing before it (WebGL2
+rejects any non-comment/non-whitespace token before `#version`). Do not emit the
+`GL_FRAGMENT_PRECISION_HIGH` `#ifdef` dance used for `LANG_ES_100`
+(`toGLSL.cpp:311-320`) — that branch is ES 2.0-only; ES 3.00 always has `highp`
+fragment-shader float support and HLSLcc itself only takes the unconditional
+`precision highp float;` branch for `LANG_ES_300` (`toGLSL.cpp:321-324`).
+
+**Confidence: high** — this is a straight read of the concatenation order in
+`toGLSL.cpp`, not a translated instruction whose semantics could be ambiguous.
+
+---
+
+## `dcl_global_flags` (5848)
+
+**Semantics**: DXBC global shader flags (`D3D10_SB_GLOBAL_FLAGS`) declared once per
+shader: refactoring-allowed, force-early-depth-stencil, enable double-precision float
+ops, skip-optimization, enable raw/structured buffers, etc. Purely a compiler-hint
+bitfield, not a register declaration.
+
+**GLSL lowering**: `toGLSLDeclaration.cpp:2781-2809`. Only two bits produce any GLSL
+text in our target subset:
+- `GLOBAL_FLAG_FORCE_EARLY_DEPTH_STENCIL` on a pixel shader emits
+  `layout(early_fragment_tests) in;\n` (`2785-2789`) unconditionally — no target
+  language gate in the C++ source.
+- `GLOBAL_FLAG_REFACTORING_ALLOWED` combined with `HavePreciseQualifier` emits four
+  `precise <type> u_xlat_precise_<type>;` globals (`2790-2802`) — desktop-only
+  qualifier gate, unreachable for `LANG_ES_300`.
+- `GLOBAL_FLAG_ENABLE_DOUBLE_PRECISION_FLOAT_OPS` requires
+  `GL_ARB_gpu_shader_fp64` (`2803-2807`) — desktop-only, unreachable for ES targets.
+
+All other flag bits (skip-optimization, minimum-precision, enable-raw-and-structured,
+force-early-*, all-resources-bound, etc.) are read by the decoder for correctness of
+other lowering decisions but emit no GLSL text here.
+
+**Type rules**: n/a — no operands, no register.
+
+**Helpers needed**: none.
+
+**Edge cases**: this instruction fires on almost every real shader (5848/1611 files ≈
+one per shader stage), but the `FORCE_EARLY_DEPTH_STENCIL` bit itself is set on only a
+minority of those. **WebGL2 note (important deviation from stock HLSLcc)**:
+`layout(early_fragment_tests) in;` is a GLSL ES 3.10 / desktop-4.20 feature
+(`GL_ARB_shader_image_load_store` era) and is **not part of GLSL ES 3.00** — WebGL2
+will fail to compile a fragment shader containing this qualifier. Since the C++
+source emits it unconditionally whenever the flag bit is set and the stage is a
+pixel shader, this JS emitter must add a language gate stock HLSLcc does not have:
+suppress the `layout(early_fragment_tests) in;` line entirely when targeting ES 3.00
+(early-fragment-tests is a depth-test-ordering optimization hint only; skipping it is
+always semantically safe, just potentially slower).
+
+**Confidence: medium** — the flag-to-GLSL mapping is a direct source read (high
+confidence), but whether any EVE shader in the corpus actually sets
+`FORCE_EARLY_DEPTH_STENCIL` (making the WebGL2 gate load-bearing) was not verified
+against the corpus in this pass.
+
+---
+
+## `dcl_temps` (5035)
+
+**Semantics**: declares the count of general-purpose temporary registers (`r0..r{N-1}`)
+used by the current shader phase (`D3D10_SB_OPCODE_DCL_TEMPS`, one dword: `ui32NumTemps`).
+
+**GLSL lowering (stock HLSLcc)**: `toGLSLDeclaration.cpp:2425-2523`. For each temp
+index `i`, HLSLcc's `DataTypeAnalysis` pass has already recorded which *native* GLSL
+types that register was ever read/written as (`psFloatTempSizes[i]`,
+`psIntTempSizes[i]`, `psUIntTempSizes[i]`, `psBoolTempSizes[i]`, plus 16/12/10-bit
+minimum-precision and `fp64` variants), and HLSLcc declares one shadow variable per
+type actually used, e.g.:
+```
+vec4 u_xlat0;
+int u_xlati0;    // only if r0 was ever read/written as int
+uint u_xlatu0;   // only if r0 was ever read/written as uint
+```
+(prefix macro `HLSLCC_TEMP_PREFIX` = `"u_xlat"`, `vendor/HLSLcc/include/hlslcc.h:127`).
+On Switch targets only, each gets a `= <ctor>(0)` default initializer
+(`2436-2498`) to dodge a false-positive uninitialized-variable compiler warning;
+non-Switch targets declare with no initializer (`2501-2521`).
+
+**GLSL lowering (this emitter's float-only register file — required deviation)**:
+because this project does not run `DataTypeAnalysis` (that pass requires full
+def/use dataflow over the instruction stream, ref: project brief), declare exactly
+one `vec4` per temp index, unconditionally:
+```
+vec4 r0;
+vec4 r1;
+...
+vec4 r{N-1};
+```
+Every instruction that consumes `rN` as int/uint wraps the read in
+`floatBitsToInt(rN)` / `floatBitsToUint(rN)`; every instruction that produces an
+int/uint result destined for `rN` wraps the write in `intBitsToFloat(...)` /
+`uintBitsToFloat(...)` before assigning. This is the single largest structural
+deviation from the stock HLSLcc temp-register model in this whole family — flag it
+prominently to the instruction-family authors, since every arithmetic/logic opcode's
+lowering depends on this convention holding for `dcl_temps`-declared registers.
+
+**Type rules**: declared type is always `vec4` (float). Actual read/write type is
+determined per-instruction by the consuming/producing opcode, not by this
+declaration.
+
+**Helpers needed**: none beyond the four bitcast builtins (already core GLSL ES 3.00,
+not user-defined helpers).
+
+**Edge cases**: initializing temps to zero (as HLSLcc does only for Switch) is *not*
+required for GLSL ES 3.00/WebGL2 correctness in general, but this project's
+`vec4(0.0)` fallback convention for signature-only outputs (see `dcl_output` below)
+suggests the same defensive default-init could be applied here too if any code path
+is ever found reading a temp before it is written; no corpus evidence of that has
+been found (`TRANSPILING-GAPS.md` "Already handled" section reports 0 instruction
+blockers). Recommend leaving temps uninitialized (matches non-Switch stock
+behavior) unless a specific shader is found to depend on zero-init.
+
+**Confidence: high** for the *stock* semantics (direct source read); **medium** for
+the float-only deviation's completeness, since it depends on every opcode in the
+sibling instruction-lowering families correctly bitcasting at every read/write site —
+a single missed bitcast silently corrupts values without a compile error.
+
+---
+
+## `dcl_indexable_temp` (16)
+
+**Semantics**: declares a dynamically-indexable local array of temp registers
+(`x0[i]`-style addressing, as opposed to the flat `r#` file), used when HLSL source
+has to write to computed indices (e.g. unrolled small loops writing into a local
+array). Encodes register index, element count, and per-element component width.
+
+**GLSL lowering**: `toGLSLDeclaration.cpp:3085-3092`:
+```cpp
+bformata(glsl, "vec%d TempArray%d[%d];\n", ui32RegComponentSize, ui32RegIndex, ui32RegCount);
+```
+i.e. `vec{ComponentSize} TempArray{RegIndex}[{RegCount}];` — component width (1-4)
+comes directly from the DXBC declaration's `sIdxTemp.ui32RegComponentSize`, not from
+signature/DataTypeAnalysis lookups.
+
+**Type rules**: always declared as `float`-family vector (`vecN`), never `ivecN`/
+`uvecN`, even in stock HLSLcc — indexable temps are HLSL-source local arrays, whose
+element type is resolved by the DXBC compiler down to float storage before emission
+in every observed case in this authority source. This emitter should mirror that:
+declare `vecN TempArray{RegIndex}[RegCount];` where `N` is exactly the decoded
+`ui32RegComponentSize` (do not force to `vec4` — unlike the flat temp-register file,
+indexable-temp width is a hard DXBC-encoded fact, not a convention this project
+gets to choose). Bitcast at use sites the same way as regular temps if any consumer
+reads/writes it as int/uint.
+
+**Helpers needed**: none.
+
+**Edge cases**: rare (16 total instructions across the whole corpus) — low priority,
+but get the declared width right since a mismatched vector size is a hard GLSL
+compile error, not a silent bug.
+
+**WebGL2 notes**: none beyond standard array declaration syntax, which GLSL ES 3.00
+supports natively.
+
+**Confidence: high** — single unconditional code path, no branching on target
+language or shader stage.
+
+---
+
+## `dcl_constant_buffer` (10160)
+
+**Semantics**: declares a constant-buffer binding (`cb#`) and its total `vec4`-slot
+count, used by later `mov`/arithmetic instructions that read `cb#[i].component`.
+Authoritative source for constant *names/offsets/layout* is Carbon/Trinity RDEF-derived
+metadata, not this fork (`CARBONENGINEJS-FORK.md`: "Carbon/Trinity metadata remains
+authoritative for ... per-frame and per-object constant buffer layout"); this fork's
+job is only to keep the register-stable `cb#` GLSL symbol emitting correctly when that
+reflection metadata is present *or stripped*.
+
+**GLSL lowering — stripped-RDEF fallback (the path this project actually depends on)**:
+`toGLSLDeclaration.cpp:2530-2559`. When `GetConstantBufferFromBindingPoint` returns
+`nullptr` (no RDEF, or RDEF present but missing this specific buffer — the CarbonEngineJS
+fork's stripped-reflection case, `CARBONENGINEJS-FORK.md` "Constant-buffer operands
+emit fallback register access such as `cb3.data[0]`"), HLSLcc emits:
+```cpp
+bformata(glsl, "layout(std140) uniform %s {\n\tvec4 data[%d];\n} cb%d;\n",
+    name, psOperand->aui32ArraySizes[1], ui32BindingPoint);
+```
+i.e. exactly:
+```glsl
+layout(std140) uniform ConstantBuffer3 {
+    vec4 data[200];
+} cb3;
+```
+where `ConstantBuffer{N}` is a synthesized block-type name (`name` built at
+`2541-2542`, `sprintf(name, "ConstantBuffer%d", ui32BindingPoint)`), the instance
+name is always `cb{N}` (`ui32BindingPoint`), and the array size is
+`psOperand->aui32ArraySizes[1]` — the DXBC declaration's own encoded slot count, read
+directly off the `dcl_constant_buffer` instruction, independent of any reflection
+data. This `cbN.data[i]` register-stable access convention is the ABI this whole
+project is built to preserve (`CARBONENGINEJS-FORK.md` "Runtime Contract";
+`TRANSPILING-GAPS.md` records the cross-stage `ConstantBuffer0` size-mismatch bug
+this produces when VS/PS declare different slot counts for the same `cb#` — normalize
+to the maximum observed size across stages sharing a binding point before emitting).
+If `UNITY_LOCATION`/binding macros are relevant (`2550-2555`) they add a
+`UNITY_LOCATION(%d)` prefix, which this emitter should expand directly to
+`layout(location = N)` text (WebGL2 has no runtime macro toggle, so skip the
+`#if`/`#else` indirection described above).
+
+**GLSL lowering — named/reflected path**: when RDEF metadata for the named cbuffer
+*is* present, HLSLcc instead calls `DeclareUBOConstants`
+(`877-997`, used when `HLSLCC_FLAG_UNIFORM_BUFFER_OBJECT` is set) or
+`DeclareStructConstants` (`1094+`) to emit one named `float`/`vecN`/matrix member per
+reflected constant, inside `uniform {CBufferName} { ... };`. This path is **not** the
+ABI this project keeps stable end-to-end (Carbon metadata is the source of truth for
+per-constant names/offsets, per `CARBONENGINEJS-FORK.md`); treat the fallback
+`cbN.data[i]` form above as the primary target shape for this emitter, and the named
+path as background context only.
+
+**Type rules**: every `data[i]` slot is a `vec4` of floats; a `mov` or arithmetic
+instruction reading `cb3.data[5].x` as an int/uint bitcasts with `floatBitsToInt` /
+`floatBitsToUint` exactly like a temp register read (this project's cbuffers are
+`vec4`-slot float storage regardless of the HLSL source's cbuffer member types,
+mirroring how the fallback path above has no member-type information at all).
+
+**Helpers needed**: none for the declaration itself.
+
+**Edge cases**:
+- Cross-stage size mismatch: VS and PS `dcl_constant_buffer` for the same binding
+  point can carry different `aui32ArraySizes[1]` if each stage only reads a prefix of
+  the buffer (`TRANSPILING-GAPS.md`, "AB hull test-set blockers" — `boostervolumetric`
+  and `planeglow` failed WebGL2 *linking* because of this, not compilation). Emit the
+  **max** slot count seen for a given `cb#` across the linked program's stages.
+- Vulkan-subpass-input (`2561-2636`) and `OVR_multiview` (`2638-2664`) special cases
+  are Vulkan/Unity-specific and out of scope for this project's DX11→WebGL2 EVE
+  corpus. **Correction**: these two are the only special cases actually in the
+  `2561-2670` range; the `"$Globals"` name check is a *different* piece of code, not
+  located there. There are two distinct `$Globals`-related checks elsewhere in this
+  file: (1) `psCBuf->name[0] == '$'` at `2674`, inside the *named/reflected* path
+  (`2672-2687`), which chooses `DeclareStructConstants` over `DeclareUBOConstants`
+  when `HLSLCC_FLAG_GLOBAL_CONSTS_NEVER_IN_UBO` is also set; and (2) the `"$Globals"`
+  string checks inside `DeclareUBOConstants`/`DeclareStructConstants` themselves
+  (`883`, `888`, `1105`, `1142`). None of this is reached by the stripped-RDEF
+  fallback path this project depends on (that path returns at `2558` before any of
+  `2561` onward runs) — so the conclusion ("$Globals is out of scope, handled
+  generically by the synthesized `ConstantBufferN` name") still holds, just not for
+  the reason/line-range originally cited.
+
+**WebGL2 notes**: `layout(std140) uniform` blocks are core GLSL ES 3.00 — no
+extension required. `std140` layout rules (16-byte vec4 alignment, `vec4 data[]`
+array) mean every array element is a full 16 bytes regardless of the HLSL source
+type, which is exactly why the flat `vec4 data[N]` fallback shape is both simple and
+correct for any packed constant layout.
+
+**Confidence: high** for the stripped-RDEF fallback shape (this is exactly what
+`CARBONENGINEJS-FORK.md` documents as the load-bearing convention and what
+`toGLSLDeclaration.cpp:2557` literally emits); **medium** on the cross-stage
+normalization requirement, since that is a package/link-time policy documented in
+`TRANSPILING-GAPS.md` as a known bug rather than something already fixed in
+`toGLSLDeclaration.cpp` itself.
+
+---
+
+## `dcl_resource_structured` (684)
+
+**Semantics**: declares a structured-buffer shader resource (`t#`) with a known
+per-element byte stride, read via `ld_structured`. In EVE's skinned space-object
+shaders this is `BoneTransforms` (a `Buffer<float4x3>`-shaped structured resource of
+joint matrices), always paired with `ld_structured` in the instruction stream.
+
+**GLSL lowering (stock HLSLcc)**: `toGLSLDeclaration.cpp:3680-3684` calls
+`DeclareBufferVariable(..., isRaw=0, isUAV=0, ...)` (`1027-1092`), which emits an
+SSBO. **Correction to the exact emitted text** (verified against `1042-1088`): the
+struct member uses GLSL's `type[size] name;` array-declarator ordering, not
+`type name[size];`, and the buffer *block* name is plain `t0` (`BufName`), not a
+synthesized `t0_type_block_name` — the block's *member* variable is `t0_buf`:
+```glsl
+struct t0_type {
+    uint[3] value;   // stride/4, via bformata("...\t%s[%d] value;\n...", typeStr, stride/4)
+};
+layout(std430, binding = N) readonly buffer t0 {
+    t0_type t0_buf[];
+};
+```
+(exact struct/instance naming per `1035-1088`; `readonly` is unconditional for
+non-UAV structured buffers, `1069-1070`; on Switch targets only, the block name gets
+an `hlslcc_readonly` prefix instead, `1073`).
+
+**Stripped-RDEF fallback**: `CARBONENGINEJS-FORK.md` — "Structured-buffer
+declarations tolerate missing `RDEF` bindings by using the stride encoded in the DXBC
+declaration extension" — i.e. `psDecl->ui32BufferStride` is read directly off the
+`dcl_resource_structured` instruction's declaration-extension dword rather than off
+reflection metadata, so the struct-element count (`stride/4`) is always available
+even with `RDEF` stripped (decision shard
+`022-dxbc-dcl-resource-declaration-tails.md` covers the sibling `dcl_resource`
+one-word-tail decoding that established this pattern).
+
+**Type rules**: SSBO element type is `uint[]` (raw dwords); the consuming
+`ld_structured` instruction bitcasts each loaded dword to float/int/uint as needed
+at the read site (out of this family's scope — instruction family territory).
+
+**Helpers needed**: none for the declaration text itself.
+
+**Edge cases / WebGL2 notes (hard blocker, not a lowering detail)**: **GLSL ES 3.00
+has no shader storage buffers** — `buffer` blocks require GLSL ES 3.10+ or desktop
+`GL_ARB_shader_storage_buffer_object`. This emitter **must not** emit the SSBO form
+above for a WebGL2 target; it will not compile. The proven working path for this
+project is a **package-time ABI rewrite**, not a change to this opcode's GLSL
+lowering:
+- `CARBONENGINEJS-FORK.md` / `016-cewg-skinning-abi-lowering-for-ccpwgl-2026-06-30.md`
+  / `TRANSPILING-GAPS.md`: drop the `t0` SSBO declaration entirely, grow the
+  paired `ConstantBuffer3` (`cb3`) to at least `vec4 data[200]`, and rewrite every
+  `ld_structured` row load against `t0` into `cb3.data[26 + blendIndex * 3 + row]`
+  (the ccpwgl `EveShip2` `JointMat` uniform-block projection, `58` joints × `12`
+  floats/joint = `696` floats appended at `cb3[26..199]`).
+- This rewrite is package/runtime-ABI policy for the current ccpwgl compatibility
+  target, **not** a native CarbonEngineJS/Trinity representation
+  (`016-...md`, "Boundary" section) — a future non-ccpwgl consumer may want a real
+  buffer-texture or uniform-array representation of `BoneTransforms` instead of this
+  specific `cb3` splice.
+- Validated: `skinned_quadv5.sm_converted_hi` 75/75 shaders translate, 336/336
+  WebGL2 programs link after the rewrite; `skinned_quadheatv5` 63/63 / 240/240.
+
+**Confidence: high** on both "stock HLSLcc emits an SSBO" and "WebGL2 cannot use
+SSBOs" (directly cited, unambiguous); **medium** on the exact `cb3.data[26 + ...]`
+offset formula for any *other* structured buffer this family's opcode might describe
+in a shader outside the skinned space-object set — this is proven only for
+`BoneTransforms` specifically, not as a general `dcl_resource_structured` policy.
+
+---
+
+## `dcl_resource` (6317)
+
+**Semantics**: declares a texture shader-resource-view binding (`t#`) with a resource
+dimension (1D/2D/3D/Cube/arrays/MS variants/buffer) and a 4-nibble per-component
+return type (float/unorm/snorm/int/uint), consumed later by `sample*`/`ld`/`resinfo`
+instructions.
+
+**GLSL lowering**: `toGLSLDeclaration.cpp:2689-2758`. Non-Vulkan path:
+1. Optional `UNITY_LOCATION(%d)` prefix (`2700-2718`) — expand directly to
+   `layout(location = N)` for this project (see cbuffer section's note on macro
+   indirection).
+2. `RESOURCE_DIMENSION_BUFFER` → `uniform samplerBuffer`/`isamplerBuffer`/
+   `usamplerBuffer` (`2722-2733`, requires `GL_EXT_texture_buffer` on ES targets,
+   `1404-1405` inside `GetSamplerType`) — not expected in this project's vertex/pixel
+   corpus (texel buffers are rare in EVE effects; treat as low-priority).
+3. All 2D/1D/Cube/array-of-those dimensions → `TranslateResourceTexture(..., 1)`
+   (`1597-1687`), which emits:
+   ```glsl
+   uniform <precision> <samplerType> t{N};
+   ```
+   and, only if the resource is a shadow-comparison texture
+   (`psDecl->ui32IsShadowTex`), an *additional* `<samplerType>Shadow t{N}_shadow`-style
+   binding (`1668-1686`) — this second declaration is **unconditional** on
+   `ui32IsShadowTex`/`samplerCanDoShadowCmp` and fires regardless of whether
+   `HLSLCC_FLAG_COMBINE_TEXTURE_SAMPLERS` is set (that flag is not tested anywhere in
+   this code path). What the combine flag actually gates is a *separate*, earlier
+   block (`1632-1657`, inside `TranslateResourceTexture`): when
+   `HLSLCC_FLAG_COMBINE_TEXTURE_SAMPLERS` is set, HLSLcc emits one *additional*
+   `uniform <samplerType> <name>;` per (texture, sampler) pair actually used together
+   (name from `TextureSamplerName`, iterating `psDecl->samplersUsed`) — on top of, not
+   instead of, the plain `t{N}` declaration at `1659-1666`. Since this project's
+   `dcl_sampler` section concludes the combine flag is required for any GLSL-ES
+   target, expect these extra per-combo uniforms to be emitted too, and confirm which
+   name (`t{N}` vs. the combo name) the consuming `sample`/`sample_c` instruction
+   family actually references before assuming plain `t{N}` is the only symbol that
+   matters.
+4. `TEXTURE2DMS`/`TEXTURE3D`/`TEXTURE2DMSARRAY` → `TranslateResourceTexture(..., 0)`
+   (same emission, `samplerCanDoShadowCmp=0`, i.e. never a comparison sampler).
+
+**Sampler-type selection** (`GetSamplerType`, `1388-1551`): base type name keyed on
+`RESOURCE_DIMENSION` (`sampler2D`, `sampler3D`, `samplerCube`, `sampler2DArray`,
+`samplerCubeArray`, `sampler2DMS`, `sampler2DMSArray`, `sampler1D`/`1DArray`,
+`samplerBuffer`), then prefixed `i`/`u` if the resource's reflected
+`RESOURCE_RETURN_TYPE` is `RETURN_TYPE_SINT`/`RETURN_TYPE_UINT` (`1406-1544`); every
+other return type (`UNORM`/`SNORM`/`FLOAT`/`TYPELESS`) maps to the plain (float)
+sampler. Return type comes from `ResourceBinding::ui32ReturnType`
+(RDEF-reflected) when available; when RDEF is stripped, this fork's
+`dcl_resource` one-word declaration-tail decoding
+(`022-dxbc-dcl-resource-declaration-tails.md`) supplies the same fact from the raw
+DXBC declaration instead: the trailing dword is four 4-bit return-type nibbles,
+preserved as `declarationData.resourceReturnType` — decode return type from there
+when no RDEF binding is found, rather than defaulting to float/unorm blindly.
+
+**Texture type 3 == native 3D** (`027-texture-type-3-is-native-3d-not-legacy-atlas.md`):
+DXBC/Carbon resource type `3` (`RESOURCE_DIMENSION_TEXTURE3D`) is an authoritative
+native volume texture, not a legacy packed-2D-atlas convention some older ccpwgl code
+assumed — lower it to `sampler3D`/`texture3D`-family calls, never collapse it into
+`sampler2D`.
+
+**Type rules**: the sampler's *component* return type (float vs int vs uint) governs
+which `texture()`/`texelFetch()` overload the consuming instruction must call
+(`vec4`- vs `ivec4`- vs `uvec4`-returning) — declaration-time fact, consumed by the
+`sample`/`ld` instruction family (out of scope here beyond noting the dependency).
+
+**Helpers needed**: none for the declaration; sampler precision comes from
+`GetSamplerPrecision` (`1553-1569`) — **not** `highp` by default. The function only
+returns `"highp "` when the resource's reflected precision is explicitly
+`REFLECT_RESOURCE_PRECISION_HIGHP`; the `default`/`UNKNOWN`/`LOWP` case (`1560-1563`,
+the path this project's stripped-RDEF fallback always hits, since there is no
+reflected `ResourceBinding::ePrecision` to consult) returns `EmitLowp(...) ? "lowp "
+: "mediump "`, and `EmitLowp` (`languages.h:69-73`) is `true` only for `LANG_ES_100` —
+so for this project's `LANG_ES_300` target the *actual* default sampler precision
+emitted is **`mediump`**, not `highp`. (WebGL2 does support `highp` samplers in
+fragment shaders, unlike GLSL ES 1.00, but stock HLSLcc does not default to
+requesting it — this project must decide separately whether to request `highp`
+samplers, rather than assuming the stock lowering already does.)
+
+**Edge cases**: MSAA resource dimensions (`TEXTURE2DMS`/`TEXTURE2DMSARRAY`) need
+`GL_OES_texture_storage_multisample_2d_array` on ES targets for the array variant
+(`1516-1519`) — WebGL2 exposes multisample textures but **not** `texelFetch` on them
+from a fragment shader in the same way desktop does; treat multisample resources as
+out-of-scope/low-confidence for this corpus unless a specific EVE effect is proven to
+need them. Cube-array (`TEXTURECUBEARRAY`) needs
+`GL_OES_texture_cube_map_array`/`GL_EXT_texture_cube_map_array` (`1608-1619`) — **not
+core in GLSL ES 3.00**, only in 3.20/desktop or via those extensions, which are not
+universally available on WebGL2 (`OES_texture_cube_map_array` is an optional WebGL2
+extension) — flag as a target blocker if any EVE effect requires it without checking
+extension availability at runtime.
+
+**WebGL2 notes**: combined texture+sampler objects (GLSL `sampler2D` as a single
+opaque uniform) are exactly WebGL2's own texture model — no separate texture/sampler
+descriptor split is needed for this target (that split only matters for the Vulkan
+backend in `TranslateVulkanResource`, out of scope).
+
+**Confidence: high** for 2D/Cube/array dimension mapping (heavily used, directly
+cited); **medium** for MS/cube-array/buffer dimensions (low corpus incidence, GLSL ES
+3.00 extension availability not verified per-device).
+
+---
+
+## `dcl_sampler` (3277)
+
+**Semantics**: declares a sampler-state binding (`s#`) — filter mode, address mode,
+comparison mode, LOD clamp/bias — consumed by `sample`/`sample_c`/`sample_l`
+instructions when combined with a `t#` resource via `dcl_resource`'s
+`samplersUsed` set.
+
+**GLSL lowering**: `toGLSLDeclaration.cpp:3348-3365`. For **non-Vulkan** targets (this
+project's WebGL2 target), the entire case body is gated behind
+`if (psContext->IsVulkan()) { ...; break; }` — falling through to `break;` with **no
+GLSL text emitted at all** for OpenGL/GLSL/GLSL-ES targets. The separate sampler
+object is *not* represented as its own GLSL declaration on this target; it is folded
+into the combined `uniform sampler2D t{N};` declaration emitted by `dcl_resource`
+above (`HLSLCC_FLAG_COMBINE_TEXTURE_SAMPLERS`-style combined texture+sampler model,
+the only model GLSL ES 3.00 supports). The one piece of state this instruction does
+carry into codegen is whether the sampler is a comparison sampler
+(`D3D10_SB_SAMPLER_MODE_COMPARISON`) — that fact reaches
+`TranslateResourceTexture`'s shadow-texture branch (`ui32IsShadowTex`, decided
+upstream at declaration-plan time from which `s#`/`t#` pairs get used together in
+`sample_c`-family instructions, not from this opcode's own GLSL emission path).
+
+**Type rules**: n/a — no GLSL variable is produced for this opcode on WebGL2/GLSL
+targets.
+
+**Helpers needed**: none.
+
+**Edge cases**: DX11 sampler-state fields that have no WebGL2 shader-side
+representation at all (address mode, filter mode, LOD bias/clamp, anisotropy,
+border color) are **runtime binding-state policy**, not shader text — they must be
+applied via `gl.texParameteri`/`gl.samplerParameteri` from Carbon/Trinity sampler
+metadata at draw time, entirely outside this translator
+(`TRANSPILING-GAPS.md`, "Exporter and runtime policy": "WebGL sampler-state
+application" is explicitly listed as deferred/out-of-scope for the DXBC reader and
+draft transpiler).
+
+**WebGL2 notes**: this is the single opcode in the family whose stock-HLSLcc-for-our-
+target lowering is "emit nothing" — worth flagging clearly to the implementing
+engineer so they don't go looking for a `s0` GLSL symbol; the register-stable name
+`s0` only shows up in Carbon binding-manifest metadata (`CARBONENGINEJS-FORK.md`:
+"`s0`" is one of the register-stable symbols this fork preserves for
+`Tr2EffectBindingManifest`), not in the GLSL source text itself.
+
+**Confidence: high** — the Vulkan/non-Vulkan branch is unconditional and
+unambiguous; the only judgment call is confirming this project always wants
+`HLSLCC_FLAG_COMBINE_TEXTURE_SAMPLERS`-style combined sampling (yes — required for
+any WebGL2/GLSL-ES target, since GLSL ES 3.00 has no separate sampler-object type).
+
+---
+
+## `dcl_input` (11726)
+
+**Semantics**: declares a shader-stage input register (vertex-shader per-vertex
+attribute, or any non-pixel stage's plain input) bound to an input-signature (ISGN)
+row: semantic name/index, component mask, component type (float/sint/uint),
+interpolation mode (non-VS stages).
+
+**GLSL lowering**: `toGLSLDeclaration.cpp:2061-2186`. Several early-outs
+(`2070-2105`) skip declaration for control-flow/thread-ID-style pseudo-inputs and
+already-declared-as-array registers — none apply to plain vertex-shader attributes,
+the dominant case in this corpus. For a normal vertex input:
+1. Name: `GetDeclaredInputName` → `inputPrefix + semanticName + semanticIndex`
+   (`HLSLCrossCompilerContext.cpp:169-211`); for a vertex shader `inputPrefix =
+   "in_"` (`toGLSL.cpp:33`) — i.e. **`in_POSITION0`, `in_NORMAL0`, `in_TEXCOORD3`,
+   `in_BLENDINDICES0`**, etc. This `in_<SEMANTIC><index>` naming is the register-
+   stable vertex-attribute ABI surface Carbon metadata and package/runtime tooling
+   bind against.
+2. Storage qualifier: `"in"` for any target where `InOutSupported` is true
+   (`2121-2127`) — true for `LANG_ES_300` (WebGL2's `in`/`out` keyword model, not the
+   legacy `attribute`/`varying` GLSL ES 1.00 keywords).
+3. Precision: `highp` unless the operand carries a `OPERAND_MIN_PRECISION_*` hint
+   (`2129-2159`) — DXBC minimum-precision annotations are rare in this corpus; default
+   to `highp` for all vertex attributes absent contrary evidence.
+4. Component type/count (`DeclareInput`, `232-390`, using the ISGN row's
+   `eComponentType` and `GetNumberBitsSet(ui32Mask)` for element count, **not** the
+   operand's own write mask) → `float`/`vecN` (`INOUT_COMPONENT_FLOAT32`),
+   `int`/`ivecN` (`SINT32`), or `uint`/`uvecN` (`UINT32`) (`265-291`).
+5. Final text: `in <precision> <type> in_<SEMANTIC><index>;` (`362-388` default
+   branch, non-array case — the common case for VS attributes).
+
+**Attribute naming / BINORMAL→BITANGENT alias (load-bearing for this project)**:
+HLSLcc derives the attribute name purely from the DXBC ISGN semantic string, which
+for EVE's split-tangent-space vertex format is literally `BINORMAL` (`in_BINORMAL0`)
+— but Carbon/Trinity per-vertex-stream metadata for that exact same GR2 mesh channel
+calls it `BITANGENT`
+(`../shaderdiscovery/knowledge/trinity-metadata/shader-discovery-truths.md:126-133`,
+`../shaderdiscovery/knowledge/carbon-metadata-contract/hlslcc-transpile-spike.md:195-201`).
+This is a **naming alias, not a semantic difference** — same vertex buffer channel,
+two different names used by two different authorities. The proven fix is a
+package-time rewrite, *after* HLSLcc emission, not a change to this opcode's GLSL
+lowering itself: `scripts/packageTr2WebglEffect.js` normalizes every
+`in_BINORMAL{n} -> in_BITANGENT{n}` for a vertex shader whose stage contract
+declares a `BITANGENT` pipeline input, so the runtime's metadata-driven attribute
+binder (which looks up attributes by the Carbon name) finds the symbol it expects.
+Validated: `unpackedskinned_quadv5`/`unpackedskinned_quadheatv5` regenerated with no
+`in_BINORMAL*` symbols remaining, still link (336/336, 80/80 WebGL2 programs).
+**This emitter should keep emitting `in_BINORMALn`** (matching HLSLcc/DXBC ISGN
+truth) **and rely on the package-time rewrite step**, not bake a BINORMAL→BITANGENT
+special case into the opcode lowering itself — the alias is a runtime-ABI fact, not a
+DXBC-to-GLSL translation fact.
+
+**Type rules**: component type/count are ISGN facts (declaration-time), independent
+of this project's float-register-file convention for `r#` temps — a vertex attribute
+declared `uvec4` really is a GLSL `uvec4`-typed `in` variable at declaration time (see
+next paragraph for why that is still a problem at the runtime-binding layer).
+
+**Helpers needed**: `HandleInputRedirect` (`toGLSLDeclaration.cpp:1689-1806`) is an
+HLSLcc-internal hull/domain-shader phase-input staging mechanism (`phase{N}_Input...`
+temporaries) — out of scope for this project's vertex/pixel-only target; no
+equivalent helper is needed here.
+
+**Edge cases — the uvec/ivec attribute problem (required deviation, highest-priority
+item in this family)**: stock HLSLcc, run as designed, declares integer-semantic
+vertex inputs with their true GLSL integer vector type, e.g. `in uvec4
+in_BLENDINDICES0;` for a `BLENDINDICES` stream reflected as `UINT32` component type
+(`DeclareInput`, `270-274`). **This project's runtime (ccpwgl) binds all mesh
+attribute channels, including blend indices, as float vertex attributes via
+`gl.vertexAttribPointer` (not `vertexAttribIPointer`)** — a real `uvec4 in_...`
+declaration either fails to link against that float-typed buffer binding, or links
+but silently produces garbage/invisible geometry
+(`028-cewg-skinned-blend-index-abi-lowering.md`: "Raw CEWG validation can link
+integer attributes, but ccpwgl runtime binding can still fail or produce invisible
+geometry if the source reaches compile as `uvec4`."). The proven, validated fix
+(`028-...md`; `TRANSPILING-GAPS.md` "Ranked helper action plan" documents the general
+version of this class of bug): **lower every integer-component-type `dcl_input`
+vertex attribute to its float-vector equivalent at declaration time** —
+```glsl
+in vec4 in_BLENDINDICES0;   // not uvec4
+```
+and bitcast at every *use* site instead: any instruction reading `in_BLENDINDICES0`
+as an index wraps it in `floatBitsToUint(in_BLENDINDICES0)` (or, if the actual buffer
+data was uploaded as plain float index values rather than bit-pattern-encoded uints —
+verify per-attribute — a plain `uint(in_BLENDINDICES0.x)` truncating conversion
+instead of a bitcast; the CEWG lowering evidence describes casting at use sites but
+does not pin down which of these two forms every producer used, see Confidence
+below). This is the **general form** of the family-level "every register is a float
+vec4" convention applied specifically to `dcl_input`: unlike the `r#` temp file
+(where float-only storage is this project's own choice), for vertex attributes it is
+required by a concrete runtime constraint (float-only `vertexAttribPointer` binding),
+proven necessary by regression (skinned geometry disappearing) and proven sufficient
+(336/336 and 240/240 WebGL2 programs pass after the rewrite) in the corpus evidence
+cited above.
+
+**WebGL2 notes**: GLSL ES 3.00 does support genuine integer vertex attributes
+(`in uvec4`/`in ivec4` with `vertexAttribIPointer`) — the float-only lowering above is
+not a GLSL-ES-3.00 *language* limitation, it is a **runtime binding-layer**
+limitation specific to this project's current ccpwgl consumer. A future
+CarbonEngineJS-native consumer that binds attributes with `vertexAttribIPointer`
+could use the stock HLSLcc `uvec4`/`ivec4` declarations directly and should not
+inherit this workaround by default.
+
+**Confidence: medium** — the *requirement* to avoid integer vertex-attribute types is
+high confidence (proven by a specific regression + fix with before/after link
+counts); the *exact* per-attribute cast convention (bitcast-reinterpret vs.
+truncating-convert at the use site) is not nailed down to opcode-level precision in
+the cited evidence and should be confirmed against the actual uploaded vertex-buffer
+encoding for each integer semantic (`BLENDINDICES` specifically is documented;
+generalize cautiously to any other integer-typed vertex semantic found in the corpus).
+
+---
+
+## `dcl_input_ps` (6995)
+
+**Semantics**: declares a pixel-shader input register (an interpolated varying from
+the previous stage) bound to an ISGN row, carrying an explicit DXBC interpolation
+mode (`INTERPOLATION_CONSTANT`/`LINEAR`/`LINEAR_CENTROID`/`LINEAR_NOPERSPECTIVE`/etc.)
+that this instruction's own `value.eInterpolation` field encodes (distinct from plain
+`dcl_input`, which has no interpolation-mode payload).
+
+**GLSL lowering**: `toGLSLDeclaration.cpp:2217-2423`. Name via `GetDeclaredInputName`
+with `inputPrefix = "vs_"` (when the previous stage is a vertex shader, the common
+case for this corpus — `toGLSL.cpp:59-79`) → **`vs_<SEMANTIC><index>`**, matching the
+vertex shader's `outputPrefix = "vs_"` output name exactly (`toGLSL.cpp:34`), which is
+how HLSLcc keeps VS-output/PS-input varying names paired across the two independently
+compiled GLSL stage sources. Storage qualifier `"in"` (`2228-2231`, `InOutSupported`
+true for ES 300). Interpolation qualifier:
+- integer component type (`UINT32`/`SINT32`) forces `flat ` regardless of the DXBC
+  interpolation mode (`2238-2242`) — **GLSL spec requirement**, not a DXBC fact:
+  integer varyings must be flat-interpolated in any GLSL version.
+- otherwise, map `psDecl->value.eInterpolation` (`2245-2284`): `INTERPOLATION_CONSTANT`
+  → `"flat "`; `LINEAR` → `""`; `LINEAR_CENTROID` → `"centroid "`;
+  `LINEAR_NOPERSPECTIVE` → `"noperspective "` **only if** `hasNoPerspective` (true for
+  `eTargetLanguage > LANG_ES_310`, i.e. **false for `LANG_ES_300`** — `2225`,
+  `2263-2265`); `LINEAR_SAMPLE`/`LINEAR_NOPERSPECTIVE_SAMPLE` → `"sample "`/
+  `"noperspective sample "` similarly gated.
+- Precision: same `highp`/`mediump`/`lowp` mapping from `OPERAND_MIN_PRECISION_*` as
+  `dcl_input` (`2287-2317`).
+- Final text: `DeclareInput(...)` (`2418`) → same underlying emitter as `dcl_input`,
+  producing `<interp>in <precision> <type> vs_<SEMANTIC><index>;`.
+
+**Type rules**: identical component-type derivation to `dcl_input` (ISGN
+`eComponentType` → `float`/`int`/`uint` base, `GetNumberBitsSet(mask)` → vector
+width). The **integer-varying-must-be-flat** rule is a hard GLSL requirement in every
+GLSL version, not a WebGL2-specific quirk — always emit `flat` for integer pixel
+inputs regardless of the source DXBC interpolation mode field.
+
+**Helpers needed**: none beyond core-language `flat`/`centroid` qualifiers (both core
+in GLSL ES 3.00).
+
+**Edge cases — framebuffer-fetch special case**: `2319-2416` handles reading back a
+previously-written render target value (`SV_TargetN` bound both as PS input and PS
+output, gated on `EXT_shader_framebuffer_fetch` + `HLSLCC_FLAG_SHADER_FRAMEBUFFER_FETCH`)
+via `#define vs_SV_TargetN gl_LastFragData[N]` or a `layout(location=N) inout`
+declaration. `GL_EXT_shader_framebuffer_fetch` **is not universally available in
+WebGL2** and this project's target is standard WebGL2 fragment shaders reading only
+their own current-fragment inputs — treat this branch as out of scope / not expected
+to trigger in the EVE corpus; if it ever does, it is a target blocker requiring the
+extension's presence to be verified at runtime, not silently assumed.
+
+**WebGL2 notes**: `centroid`/`sample` interpolation qualifiers are core GLSL ES 3.00
+keywords (no extension needed). `noperspective` is **not** — GLSL ES 3.00's spec does
+not include `noperspective` as a keyword at all (it was added later, e.g. via
+`NV_shader_noperspective_interpolation` for ES 3.0/3.1, and core only from ES 3.20);
+WebGL2/ES 3.00 has no standard `noperspective` qualifier. The C++ source's own
+`hasNoPerspective` gate (`eTargetLanguage <= LANG_ES_310 ? 0 : 1`, `2225`) is
+therefore **correct as written, not stale or overly conservative** — it already
+disables `noperspective` for `LANG_ES_300` (and `LANG_ES_310`) and only enables it for
+targets above `LANG_ES_310`. This emitter should simply mirror that gate rather than
+second-guess it: if any EVE pixel shader declares `INTERPOLATION_LINEAR_NOPERSPECTIVE`,
+drop the qualifier for a `LANG_ES_300` target (falls back to perspective-correct
+interpolation, a visible but non-fatal quality difference, vs. a hard compile error
+from an unrecognized qualifier).
+
+**Confidence: high** — the name-prefix pairing and integer-flat rule are high
+confidence (direct source read, universal GLSL requirement); the
+`noperspective`-in-ES-3.00 gate was re-checked directly against the GLSL ES 3.00
+language facts (no `noperspective` keyword until ES 3.20 core / the
+`NV_shader_noperspective_interpolation` extension) and confirmed correct as written,
+so this is no longer an open question for this opcode.
+
+---
+
+## `dcl_output` (15197) — highest-frequency opcode in this family
+
+**Semantics**: declares a vertex/pixel-shader output register (`o#`) bound to an
+OSGN row (semantic name/index, component mask, component type), or (hull-shader
+control-point phase only, not in this project's scope) routed to `gl_Position`.
+
+**GLSL lowering**: `toGLSLDeclaration.cpp:2760-2779` → `AddUserOutput`
+(`594-854`), gated by `OutputNeedsDeclaring` (`HLSLCrossCompilerContext.cpp:279-330`)
+which dedups repeated partial-mask declarations of the same register via an
+`acOutputDeclared` bitmask (a register can legally receive several `dcl_output`
+instructions each covering a different component subset; only undeclared components
+trigger new text).
+- Component type/count: OSGN `eComponentType`/`GetNumberBitsSet(mask)` →
+  `float`/`vecN` (`FLOAT32`), `int`/`ivecN` (`SINT32`), `uint`/`uvecN` (`UINT32`)
+  (`622-655`) — identical derivation pattern to `dcl_input`.
+- Precision: `highp`/`mediump`/`lowp` from `OPERAND_MIN_PRECISION_*` (`657-689`).
+- **Pixel shader** (`691-795`): special output types first —
+  `OPERAND_TYPE_OUTPUT_DEPTH` → plain `gl_FragDepth` (built-in, no declaration
+  needed on GL/ES targets, `701-708`; the `EXT_frag_depth` `#define` shim at `703-706`
+  is `LANG_ES_100`-only, irrelevant for ES 300 where `gl_FragDepth` is core).
+  `OUTPUT_DEPTH_GREATER_EQUAL`/`OUTPUT_DEPTH_LESS_EQUAL` → `GL_ARB_conservative_depth`
+  layout qualifiers (`709-723`) — **desktop-only extension, not available in GLSL ES
+  3.00**; if an EVE pixel shader uses conditional depth output, this project must fall
+  back to plain unconstrained `gl_FragDepth` writes (drop the `depth_greater`/
+  `depth_less` hint — it is a performance hint only, never required for correctness).
+  Otherwise (`725-793`, the common `SV_TargetN` case): name =
+  `outputPrefix("") + semanticName + renderTargetIndex` i.e. plain `SV_TargetN`, and
+  an explicit `layout(location = N) out <precision><type> SV_TargetN;` the first time
+  render target `N` is seen (`748-789`). **Correction to the gating fact**: the
+  `layout(location=N)` here is *not* gated by `HaveInOutLocationQualifier` — that
+  function (`languages.h:102-109`) is `false` for `LANG_ES_300` (only `true` for
+  `>=LANG_410` or `LANG_ES_310`). The actual gate at `752-753` is
+  `HaveInOutLocationQualifier(...) || HaveLimitedInOutLocationQualifier(...)`, and it
+  is `HaveLimitedInOutLocationQualifier` (`languages.h:93-100`, explicitly commented
+  "Only on vertex inputs and pixel outputs") that returns `true` for `LANG_ES_300`,
+  satisfying the `||` and producing the explicit location. Net behavior is unchanged
+  (ES 300 pixel outputs do get `layout(location=N)`), but the responsible function is
+  `HaveLimitedInOutLocationQualifier`, not `HaveInOutLocationQualifier` — worth getting
+  right since the two gates diverge for other declarations in this same family (see
+  `dcl_input`'s vertex-attribute declaration below, which tests
+  `HaveInOutLocationQualifier` alone and therefore does *not* get an explicit location
+  on `LANG_ES_300`). WebGL2 **requires** explicit `layout(location=N)` for any
+  multi-render-target fragment shader (no implicit `gl_FragData[N]` indexing in the
+  ES 3.00 core profile; `WriteToFragData` is true only for legacy/ES 100 targets).
+- **Vertex shader** (`796-846`, the common case here since this project has no
+  geometry/hull/domain stages): name =
+  `outputPrefix("vs_") + semanticName + semanticIndex` → **`vs_<SEMANTIC><index>`**
+  (`804`), matching the pixel shader's `vs_`-prefixed input names described above.
+  Interpolation: integer types forced `flat` (`810-814`), float types resolved from
+  cross-stage dependency data (`GetInterpolationMode`, `815-818`) — in practice this
+  project should resolve interpolation per-varying from the **pixel shader's**
+  `dcl_input_ps` `value.eInterpolation` for the same semantic, since that is the only
+  side that actually encodes an interpolation mode in DXBC (vertex-shader outputs
+  carry no interpolation-mode field of their own). `layout(location=N)` from
+  `GetVaryingLocation` (`821-825`) — WebGL2 requires **matching** explicit varying
+  locations between the two independently compiled VS/PS GLSL programs when using
+  explicit locations, or (simpler, and what this project should default to) omit
+  `layout(location=...)` for varyings entirely and let the GLSL **linker** match by
+  name — WebGL2/GLSL ES 3.00 supports both; matching by name avoids a whole class of
+  location-numbering bugs across independently emitted VS/PS sources and is
+  recommended here. Final text: `<interp>out <precision><type> vs_<SEMANTIC><index>;`
+  (`838`).
+- Early-out: register 0 with legacy `"POS"` semantic name in a vertex shader returns
+  without declaring anything (`619-620`) — that register is expected to be routed to
+  `gl_Position` via a separate `dcl_output_siv` `NAME_POSITION` declaration elsewhere
+  in the same instruction stream (see next section); do not double-declare it.
+
+**Type rules**: identical component-type/count derivation to `dcl_input`/
+`dcl_input_ps` (OSGN-driven, not write-mask-driven). The destination write mask on
+the *declaration* itself only ever narrows which components get declared this pass
+(merged across multiple partial declarations via `acOutputDeclared`); it has no
+`_sat` concept — `saturate` only applies to the *instructions* that write the
+register, never to a `dcl_output` declaration itself.
+
+**Helpers needed**: `HandleOutputRedirect` — like `HandleInputRedirect`, this is
+HLSLcc's hull-shader phase-output staging machinery; out of scope for this project's
+vertex/pixel-only target.
+
+**Edge cases — signature-only vertex outputs**: `023-signature-only-vertex-output-fallback.md`
+documents `starmapnew`/`ubershader3d` variants whose OSGN declares outputs (`o3
+-> COLOR2`, `o4 -> TEXCOORD1`, etc. for `starmapnew`; `o2 -> COLOR1`, `o7 ->
+TEXCOORD4` for `ubershader3d`) with **no corresponding bytecode write** anywhere in
+the instruction stream (audited: `references: 0`). GLSL ES 3.00 does not guarantee
+zero-initialization of `out` varyings, and reading an unwritten varying downstream is
+undefined/implementation-defined — this project's proven, adopted policy is to emit
+an explicit deterministic zero-fill in early-main for any declared-but-never-written
+output: `vs_COLOR2 = vec4(0.0);` before the translated instruction stream runs. Treat
+this as expected, not a parser bug, for any output register with zero write
+references.
+
+**WebGL2 notes**: `layout(location=N)` for fragment-shader color outputs is
+mandatory when more than one is declared (no implicit indexing); prefer
+name-based linking (no `layout(location=...)`) for VS→PS varyings specifically,
+per the recommendation above, to avoid cross-stage location-numbering mismatches.
+
+**Confidence: high** for the SV_Target/varying declaration shape and naming
+convention (heavily used, directly cited, corpus-validated linking counts exist
+elsewhere in this family for related opcodes); **medium** for the
+"resolve VS-output interpolation from the paired PS-input's `dcl_input_ps` mode"
+policy recommendation, since that is this spec's own synthesis of how to handle
+cross-stage interpolation resolution for a from-scratch JS emitter, not a literal
+restatement of an already-proven CarbonEngineJS-fork behavior.
+
+---
+
+## `dcl_output_siv` (2825)
+
+**Semantics**: declares a vertex/geometry/domain-shader output register bound to a
+**system-value** semantic (`SV_Position`, `SV_RenderTargetArrayIndex`,
+`SV_ClipDistance`, `SV_CullDistance`, `SV_ViewportArrayIndex`, `SV_PrimitiveID`, plus
+tessellation-factor system values not relevant to this project's VS/PS-only scope)
+rather than an arbitrary user semantic.
+
+**GLSL lowering**: `toGLSLDeclaration.cpp:1899-2058`, switch on
+`psDecl->asOperands[0].eSpecialName`:
+- `NAME_POSITION` → `AddBuiltinOutput(psDecl, 0, "gl_Position")` (`1903-1907`) — the
+  **only** system value this project's vertex-shader corpus needs. `gl_Position` is
+  built-in in every GLSL version; no declaration text at all is emitted for it (the
+  register's read/write sites are simply redirected to the literal string
+  `gl_Position` instead of a synthesized varying name — see `AddBuiltinOutput`,
+  `413-...`, and note it early-returns immediately for any special name other than
+  `NAME_CLIP_DISTANCE`/`NAME_CULL_DISTANCE`, `419-420`, meaning **for `NAME_POSITION`
+  specifically this call is a pure no-op**: the redirection to `gl_Position` as an
+  operand string happens entirely in the instruction-translation/operand layer, not
+  here).
+- `NAME_RENDER_TARGET_ARRAY_INDEX` → `gl_Layer`, requiring
+  `GL_AMD_vertex_shader_layer` on a vertex shader (`1908-1928`) — **not standard in
+  GLSL ES 3.00/WebGL2**; this is a desktop-GL vendor extension. Multi-layer
+  rendering from a vertex shader is out of scope for this project's target; treat as
+  a target blocker if encountered, not a silently-degraded feature.
+- `NAME_CLIP_DISTANCE`/`NAME_CULL_DISTANCE` → `gl_ClipDistance`/`gl_CullDistance`
+  (`1929-1938`), requiring `GL_EXT_clip_cull_distance` on ES targets
+  (`449` inside `AddBuiltinOutput`) — this is a **real, available WebGL2 extension**
+  (`EXT_clip_cull_distance`), but is optional/not universally supported; treat as
+  conditionally available, verify at runtime before relying on it.
+- `NAME_VIEWPORT_ARRAY_INDEX` → `gl_ViewportIndex` (`1939-1943`) — desktop-only
+  (`GL_ARB_shader_viewport_layer_array`/`GL_NV_viewport_array2`), no WebGL2
+  equivalent; out of scope.
+- `NAME_PRIMITIVE_ID` → `gl_PrimitiveID` (`1949-1953`) — vertex shaders cannot write
+  `SV_PrimitiveID` in D3D (it is a geometry-shader-only output there); this branch is
+  reached only for geometry shaders, out of this project's scope.
+- `NAME_VERTEX_ID`/`NAME_INSTANCE_ID`/`NAME_IS_FRONT_FACE` → `ASSERT(0)` (`1944-1963`,
+  these are never legal *outputs*, only inputs — DXBC-level invariant, not a lowering
+  choice).
+- Tessellation-factor names (`NAME_FINAL_*_TESSFACTOR`, `1964-2047`) → hull-shader-only
+  `gl_TessLevelOuter`/`gl_TessLevelInner` array slots; entirely out of this project's
+  vertex/pixel-only scope.
+
+**Type rules**: `gl_Position` is always `vec4`; the `_siv` declaration itself carries
+no separate component-type fact beyond what the built-in GLSL variable already
+mandates.
+
+**Helpers needed**: none — every reachable case in this project's scope
+(`NAME_POSITION`) redirects to a language built-in with zero emitted declaration
+text.
+
+**Edge cases**: the DXBC-level invariant that `SV_Position` is always written in a
+vertex shader means this opcode should appear at least once per vertex-shader stage
+in the corpus (2825 occurrences across 1611 files' vertex + pixel-adjacent stages is
+consistent with "roughly one per vertex/domain/geometry stage, most of which are
+plain VS-only stages here").
+
+**WebGL2 notes**: of the system values this opcode can carry, only `SV_Position` (no
+extension) and, conditionally, `SV_ClipDistance`/`SV_CullDistance`
+(`EXT_clip_cull_distance`, optional) have any real WebGL2 story; every other branch
+listed above is a target blocker for this project's WebGL2 scope, not a lowering
+detail to implement.
+
+**Confidence: high** for `NAME_POSITION` (dominant case, direct source read,
+`TRANSPILING-GAPS.md` "Already handled": "`SV_Position`... [is] handled"); **low**
+for every other branch, since none of them are exercised in this project's proven
+VS/PS-only WebGL2 validation runs.
+
+---
+
+## `dcl_input_ps_siv` (538)
+
+**Semantics**: declares a pixel-shader input bound to a system-value semantic
+(`SV_Position` as `gl_FragCoord`, or `SV_RenderTargetArrayIndex` as `gl_Layer`).
+
+**GLSL lowering**: `toGLSLDeclaration.cpp:2188-2207`:
+- `NAME_POSITION` → `AddBuiltinInput(psDecl, "gl_FragCoord")` (built-in, no
+  declaration text — `gl_FragCoord` is core GLSL ES 3.00), **plus** an early-main
+  statement:
+  ```glsl
+  vec4 hlslcc_FragCoord = vec4(gl_FragCoord.xyz, 1.0/gl_FragCoord.w);
+  ```
+  (`2195`) — every read of the DXBC `SV_Position` pixel-shader input must be
+  redirected to `hlslcc_FragCoord`, **not** raw `gl_FragCoord`: the literal C++
+  text takes `gl_FragCoord.xyz` unchanged but replaces the `.w` component with
+  `1.0/gl_FragCoord.w`, reconciling a difference between what HLSL's
+  `SV_Position.w` and GLSL's `gl_FragCoord.w` each store in the 4th component.
+  Treat `hlslcc_FragCoord` as the mandatory redirect target for any
+  `SV_Position`-as-input read in a pixel shader, not `gl_FragCoord` directly — do
+  not attempt to re-derive or "simplify" the `1.0/gl_FragCoord.w` swap, just
+  reproduce the line as emitted.
+- `NAME_RENDER_TARGET_ARRAY_INDEX` → `gl_Layer` (`2198-2201`) — reading back which
+  array layer/cubemap face the primitive rasterized into; requires geometry-shader
+  layered rendering upstream, out of this project's scope.
+- Anything else → `ASSERT(0)` (`2203-2205`) — DXBC-level invariant, no other system
+  value is legal as a pixel-shader `_siv` input.
+
+**Type rules**: `gl_FragCoord`/`hlslcc_FragCoord` is always `vec4`.
+
+**Helpers needed**: the `hlslcc_FragCoord` early-main redirect line above — declare
+it as a **named helper convention** (a fixed early-main statement emitted whenever a
+`dcl_input_ps_siv NAME_POSITION` is seen), not a callable function, since it is a
+local variable substitution rather than a reusable GLSL function.
+
+**Edge cases**: `1.0/gl_FragCoord.w` divides by the fragment's window-space `w`
+reciprocal — if `gl_FragCoord.w` is ever exactly `0.0` (a fragment at infinite
+depth/degenerate clip-space w), this produces `inf`; no corpus evidence this occurs
+in practice (fragments with `w=0` do not typically survive clipping), but note it as
+a theoretical NaN/inf source worth being aware of, not one this project needs to
+guard defensively against absent contrary evidence.
+
+**WebGL2 notes**: `gl_FragCoord` is core; no extension needed. `gl_Layer` requires
+geometry-shader support, out of scope for this project.
+
+**Confidence: high** for `NAME_POSITION` (directly cited, dominant case — 538
+occurrences is consistent with "most pixel shaders read `SV_Position`"); **low** for
+`gl_Layer` (unreachable without geometry shaders in this project's stage set).
+
+---
+
+## `dcl_input_ps_sgv` (42) / `dcl_input_sgv` (18)
+
+**Semantics**: declares a pixel-shader (`_ps_sgv`) or vertex/other-stage (`_sgv`)
+input bound to a **system-generated-value** semantic — the DXBC category for values
+the *rasterizer/assembler* synthesizes rather than values passed through the
+interpolator pipeline: `SV_IsFrontFace`, `SV_SampleIndex`, `SV_VertexID`,
+`SV_InstanceID`, `SV_PrimitiveID`, plus the same position/layer/clip/cull/viewport
+names `_siv` also carries (both opcodes share one switch statement in the source).
+
+**GLSL lowering**: `toGLSLDeclaration.cpp:1815-1896` (both opcodes dispatch to this
+single `case` block). The branches relevant to this project's VS/PS-only scope:
+- `NAME_IS_FRONT_FACE` (pixel-shader-only in practice — `SV_IsFrontFace` is a PS
+  input) → `gl_FrontFacing`, with an explicit **cast trick**
+  (`1856-1869`):
+  ```cpp
+  if (HaveUnsignedTypes(psContext->psShader->eTargetLanguage))
+      AddBuiltinInput(psDecl, "(gl_FrontFacing ? 0xffffffffu : uint(0))");
+  else
+      AddBuiltinInput(psDecl, "(gl_FrontFacing ? 1 : 0)");
+  ```
+  The comment explains why: `if(gl_FrontFacing != 0)` failed to compile on Intel HD
+  4000 — no implicit bool↔int conversion on that driver — so HLSLcc always
+  materializes the DXBC **comparison-mask convention** explicitly at the point of
+  use: `SV_IsFrontFace` in DXBC is an integer that reads as `0xFFFFFFFF` (true) or
+  `0x00000000` (false), **not** a GLSL `bool`. For GLSL ES 3.00 (`HaveUnsignedTypes`
+  true), every read of this input must produce `0xffffffffu`/`uint(0)`, then get
+  bitcast with `uintBitsToFloat(...)` if the register file stores it as a float (per
+  this project's register convention) — i.e. the declaration-time substitution text
+  for `in_IS_FRONT_FACE`-style reads should literally be
+  `(gl_FrontFacing ? uintBitsToFloat(0xffffffffu) : uintBitsToFloat(uint(0)))` when
+  materializing it into this project's float register file, or equivalently
+  `uintBitsToFloat(gl_FrontFacing ? 0xffffffffu : 0u)` (matches the JS draft
+  transpiler's own hypothesis at
+  `../shaderdiscovery/src/core/transpiler/gles/Dx11GlesDraftTranspiler.js:1405`:
+  `splatScalarExpression("uintBitsToFloat(gl_FrontFacing ? 0xffffffffu : 0u)", count)`
+  — cross-checked against `toGLSLDeclaration.cpp:1864-1867` and confirmed
+  consistent).
+- `NAME_SAMPLE_INDEX` → `gl_SampleID`, requiring `GL_OES_sample_variables` on ES
+  targets (`1870-1876`) — this **is** a real, available WebGL2 extension
+  (`OES_sample_variables`), but optional; treat as conditionally available.
+- `NAME_VERTEX_ID` → `gl_VertexID` (`1878-1881`) — core in GLSL ES 3.00 for vertex
+  shaders, no extension needed. `TRANSPILING-GAPS.md` "Already handled":
+  "`SV_VertexID`... [is] handled."
+- `NAME_INSTANCE_ID` → `gl_InstanceID` (`1851-1854`) — core in GLSL ES 3.00, no
+  extension needed.
+- `NAME_PRIMITIVE_ID` → `gl_PrimitiveID`/`gl_PrimitiveIDIn` (`1883-1889`) — requires a
+  geometry shader upstream in practice, out of scope.
+- `NAME_RENDER_TARGET_ARRAY_INDEX`/`NAME_CLIP_DISTANCE`/`NAME_CULL_DISTANCE`/
+  `NAME_VIEWPORT_ARRAY_INDEX` (`1826-1850`) — same extension caveats as the `_siv`
+  output section above.
+- `default` (`1891-1894`) — falls back to a plain `in vec4 %s;` declaration using the
+  DXBC-provided special-name string directly, for any system-generated value this
+  switch doesn't special-case.
+
+**Type rules**: `gl_FrontFacing` is GLSL `bool`; every other value in this list is
+`int` (`gl_VertexID`, `gl_InstanceID`, `gl_SampleID`, `gl_PrimitiveID`). None of these
+match DXBC's `0xFFFFFFFF`/`0x00000000` mask convention natively except
+`SV_IsFrontFace`, which is why it alone gets the explicit ternary-to-mask
+materialization above; `gl_VertexID`/`gl_InstanceID`/etc. are read as plain signed
+`int` and bitcast with `intBitsToFloat` when stored into this project's float
+register file (not `uintBitsToFloat` — these are genuinely signed-int builtins in the
+GLSL spec, unlike the synthesized front-facing mask).
+
+**Helpers needed**: none beyond the inline ternary-to-mask expression for
+`SV_IsFrontFace` (a fixed substitution text, not a callable helper function).
+
+**Edge cases**: `SV_IsFrontFace`'s `0/0xFFFFFFFF` convention is exactly the
+**comparison-mask convention** called out at the top level of this spec family — even
+though this is a *declaration*-family opcode rather than an instruction, it is one of
+the few `decl-io` opcodes where the DXBC 0/0xFFFFFFFF-vs-GLSL-bool boundary has to be
+crossed at declaration time rather than left to a later comparison instruction.
+
+**WebGL2 notes**: `gl_VertexID`/`gl_InstanceID`/`gl_FrontFacing` are all core GLSL ES
+3.00 (no extension) — the dominant, high-confidence cases for this project.
+`gl_SampleID` needs an optional extension; primitive-ID/layer/clip/cull/viewport
+branches need geometry-shader support this project's target does not have.
+
+**Confidence: high** for `NAME_IS_FRONT_FACE`/`NAME_VERTEX_ID`/`NAME_INSTANCE_ID`
+(directly cited, corpus-relevant, `TRANSPILING-GAPS.md`-confirmed); **low** for every
+other branch (geometry-shader-dependent or low corpus incidence: 42+18=60 total
+instances is small next to the 15k+ `dcl_output` count, and most of that 60 is
+plausibly `SV_IsFrontFace`/`SV_VertexID` given this corpus is VS/PS-dominated).
+
+---
+
+## `dcl_input_siv` (3)
+
+**Semantics**: declares a non-pixel-shader input bound to a system-value semantic
+(shares the `NAME_*` enum with `dcl_output_siv`/`dcl_input_ps_siv`/`dcl_input_sgv`,
+but with its own narrow handling).
+
+**GLSL lowering**: `toGLSLDeclaration.cpp:2209-2215`:
+```cpp
+case OPCODE_DCL_INPUT_SIV:
+{
+    if (psShader->eShaderType == PIXEL_SHADER && psContext->psDependencies)
+    {
+        psContext->psDependencies->SetInterpolationMode(psDecl->asOperands[0].ui32RegisterNumber, psDecl->value.eInterpolation);
+    }
+    break;
+}
+```
+This opcode emits **no GLSL text of its own** in this project's scope. Its only
+effect is recording an interpolation-mode fact for a later `dcl_input_ps`/
+`dcl_input` declaration of the *same register* to consume when choosing that
+declaration's interpolation qualifier — and only when the current shader is itself
+the pixel shader (unreachable in the VS/PS pair unless this specific opcode is
+emitted for a PS input, which is unusual — `dcl_input_ps`/`dcl_input_ps_siv` normally
+carry that role for pixel shaders; `dcl_input_siv` proper is more commonly a
+non-pixel-stage opcode in the wider HLSLcc target matrix, e.g. domain/geometry-shader
+inputs receiving a previous stage's system value as an ordinary interpolated input).
+
+**Type rules**: n/a — no declaration text, no operand type conversion here.
+
+**Helpers needed**: none.
+
+**Edge cases**: only 3 occurrences in the entire 450k-instruction/1611-file corpus —
+lowest-frequency opcode in this family by a wide margin. Given this project has no
+geometry/domain/hull stages, verify what these 3 instances actually are before
+assuming the pixel-shader branch above is even the relevant one; they may be
+vertex-shader-side declarations that fall through this `case` doing nothing
+observable at all (the `if` guard requires `PIXEL_SHADER`, so a vertex-shader
+occurrence of this opcode is a complete no-op).
+
+**WebGL2 notes**: none — no GLSL is emitted.
+
+**Confidence: low** — three instances is too small a sample to be confident which
+concrete DXBC pattern in the EVE corpus produces this opcode versus its much more
+common `_ps_siv`/`_sgv`/`_ps_sgv` siblings; implement the no-op/interpolation-mode-
+recording behavior above as written in the source, but do not assume it is
+exercised meaningfully by this project's corpus.
+
+---
+
+## `customdata` (159, encodes an Immediate Constant Buffer)
+
+**Semantics**: DXBC `customdata` with subtype `ICB` (Immediate Constant Buffer) —
+an inline array of literal `vec4`-shaped constant data baked directly into the
+bytecode (as opposed to `dcl_constant_buffer`'s externally-bound `cb#`), addressed
+either directly by a fixed index or dynamically (`x0[aL]`-style) from instructions
+later in the stream.
+
+**GLSL lowering (non-Vulkan, non-Switch — this project's target)**:
+`toGLSLDeclaration.cpp:3007-3076`. HLSLcc walks `m_ConstantArrayInfo.m_Chunks`
+(pre-computed groupings of same-component-width, contiguously-accessed ICB slices)
+and, per chunk:
+1. Declares an array: `float ImmCB_{phase}_{chunkFirst}_{rebase}[{size}];` (scalar
+   chunk) or `vec{N} ImmCB_{phase}_{chunkFirst}_{rebase}[{size}];` (`N`-wide chunk)
+   (`3017-3020`).
+2. If the target lacks dynamic indexing support, additionally registers a
+   `DeclareDynamicIndexWrapper` (`3022-3029`) — irrelevant here since GLSL ES 3.00
+   (`HaveDynamicIndexing` true for ES 300) supports genuine dynamic array indexing
+   natively; this project should skip the wrapper machinery entirely and always emit
+   a real GLSL array.
+3. Populates each array element in **early-main** (not as a `const` initializer list
+   — note this is a *mutable* global-scope-declared, early-main-assigned array in
+   stock HLSLcc, not a `const` array), one assignment per element per component
+   (`3032-3074`):
+   ```glsl
+   ImmCB_0_0_0[0] = 1.5;
+   ImmCB_0_0_0[1] = uintBitsToFloat(uint(0x7FC00000u));  // NaN literal, bit-pattern form
+   ```
+   Float literals that are themselves NaN/Inf bit patterns
+   (`fpcheck(val[...])`, `3045-3048`, `3067-3070`) are re-encoded as
+   `uintBitsToFloat(uint(0x{hex}u))` rather than a literal `nan`/`inf` token (which
+   GLSL cannot parse directly) — **this bit-pattern-preserving encoding is the
+   correct/required approach for any ICB constant that is NaN or ±Inf, and this
+   project's emitter must replicate it**, since a plain decimal float literal cannot
+   represent those bit patterns exactly and GLSL has no `nan`/`inf` literal syntax.
+4. Vulkan target (`2975-2990`, background only — not this project's target):
+   `const uvec4 ImmCB_{phase}[] = uvec4[{count}](uvec4(0x..., ...), ...);` — a true
+   `const` array of raw-bit `uvec4`s.
+5. Switch target (`2991-3006`, background only): a `const vec4
+   ImmCB_{phase}[]` initialized with a `vec4[{count}]` array constructor whose
+   elements preserve raw bits with `uintBitsToFloat`; this is the
+   shape closest to "a `const vec4 array`" as the family brief describes, and is a
+   **better model for this project's emitter to imitate** than the non-Vulkan/
+   non-Switch mutable-early-main-array path above: declare
+   ```glsl
+   const vec4 ImmCB_{phase}[{count}] = vec4[{count}](
+       vec4(uintBitsToFloat(0x3FC00000u), uintBitsToFloat(0x00000000u), ...),
+       ...
+   );
+   ```
+   at global scope (every raw dword reinterpreted through `uintBitsToFloat`
+   uniformly, whether or not it happens to be a "nice" float, sidestepping the
+   `fpcheck`-conditional branching the CPU-target path uses) — simpler to implement
+   correctly in a from-scratch JS emitter and avoids the early-main mutable-global
+   pattern (which exists in stock HLSLcc mainly to support per-chunk dynamic-array
+   splitting this project doesn't need, since `HaveDynamicIndexing` is true and a
+   single flat `const vec4[]` can be indexed directly).
+
+**Type rules**: every ICB element is exactly 4 raw dwords; **always reinterpret via
+`uintBitsToFloat`** rather than trusting a decimal float re-parse of the DXBC literal
+value, to guarantee exact bit-for-bit reproduction of the original constant
+(including denormals/NaNs/Infs the HLSL compiler folded in). Consumers needing an
+int/uint view of an ICB element bitcast again at the use site
+(`floatBitsToInt`/`floatBitsToUint`) exactly like any other float-register-file read.
+
+**Helpers needed**: none — `uintBitsToFloat` is core GLSL ES 3.00.
+
+**Edge cases**: NaN/Inf constants are the primary edge case, handled correctly by
+the bit-pattern-preserving encoding above — do not let a JS `JSON.stringify`/decimal
+round-trip of the float value silently normalize a NaN payload or lose an Inf's
+sign bit; carry the raw `uint32` dword through to the emitted GLSL untouched.
+Dynamic indexing of the ICB (`x0[aL]`-style reads) is a plain GLSL array-index
+expression on this project's target (`HaveDynamicIndexing` true for ES 300),
+needing none of stock HLSLcc's non-dynamic-indexing wrapper-function fallback.
+
+**WebGL2 notes**: dynamic (non-constant-expression) array indexing of a global
+array is supported in GLSL ES 3.00's core profile (unlike GLSL ES 1.00, where it was
+restricted) — this project's target does not need the
+`DeclareDynamicIndexWrapper` fallback stock HLSLcc carries for older targets.
+
+**Confidence: medium** — the NaN/Inf bit-pattern-preserving requirement and the
+"prefer the Switch-shaped `const vec4[]` over the non-Vulkan/non-Switch mutable
+early-main array" recommendation are both this spec's own synthesis reasoned from
+reading three different target branches in the same source function, not a literal
+restatement of a single already-proven CarbonEngineJS-fork code path — validate the
+`const vec4[]` shape compiles and links correctly on an actual WebGL2 context before
+treating it as final.
+
+---
+
+## Helpers summary
+
+Every helper function/macro/convention this family requires the JS emitter to
+provide, in one place:
+
+| Helper | Kind | Used by | Definition |
+|---|---|---|---|
+| `floatBitsToInt` | core GLSL ES 3.00 builtin | any int-typed read of a float-register-file value (`dcl_temps`, `dcl_indexable_temp`, `dcl_constant_buffer` fallback slots, `customdata`, integer-lowered `dcl_input`) | built-in, no definition needed |
+| `floatBitsToUint` | core GLSL ES 3.00 builtin | same as above, uint-typed reads (also the `SV_IsFrontFace` mask materialization, `dcl_input_ps_sgv`/`dcl_input_sgv`) | built-in |
+| `intBitsToFloat` | core GLSL ES 3.00 builtin | writing an int-typed result into a float register (`gl_VertexID`/`gl_InstanceID`/`gl_PrimitiveID`/`gl_SampleID` materialization into the float register file) | built-in |
+| `uintBitsToFloat` | core GLSL ES 3.00 builtin | writing a uint-typed result into a float register; ICB literal decoding (`customdata`); `SV_IsFrontFace` mask materialization | built-in |
+| `hlslcc_FragCoord` early-main redirect | fixed substitution statement, not a function | `dcl_input_ps_siv` (`NAME_POSITION`) | `vec4 hlslcc_FragCoord = vec4(gl_FragCoord.xyz, 1.0/gl_FragCoord.w);` — every `SV_Position`-as-PS-input read must use this name, not raw `gl_FragCoord` |
+| `SV_IsFrontFace` mask expression | fixed substitution expression, not a function | `dcl_input_ps_sgv`/`dcl_input_sgv` (`NAME_IS_FRONT_FACE`) | `uintBitsToFloat(gl_FrontFacing ? 0xffffffffu : 0u)` materialized wherever the DXBC 0/0xFFFFFFFF mask value is read |
+| Integer-vertex-attribute float lowering | declaration-shape convention, not a function | `dcl_input` for any `INOUT_COMPONENT_UINT32`/`SINT32` vertex attribute (proven for `BLENDINDICES`; generalize cautiously) | declare `vec4`/`vecN` instead of `uvecN`/`ivecN`; bitcast at every use site |
+| `in_BINORMALn -> in_BITANGENTn` rename | package-time post-process, not a GLSL-emission-time helper | `dcl_input` split-tangent-space vertex shaders | applied by `scripts/packageTr2WebglEffect.js`-equivalent tooling **after** this family's GLSL text is emitted, keyed off the stage's Carbon metadata contract — do not bake into the opcode lowering itself |
+| Cross-stage `cbN` size normalization | package/link-time policy, not a per-shader GLSL-emission helper | `dcl_constant_buffer` | emit the **max** `data[]` slot count observed for a given `cb#` across every stage sharing that binding point in one linked program |
+| `BoneTransforms` SSBO→`cb3` splice | package-time ABI rewrite, not a GLSL-emission-time helper | `dcl_resource_structured` (skinned space-object shaders specifically) | drop the `t0` SSBO decl; grow `cb3` to `vec4 data[200]`; rewrite `ld_structured` row reads to `cb3.data[26 + blendIndex*3 + row]` |
+| `layout(early_fragment_tests) in;` suppression | emission-time language gate (not present in stock HLSLcc) | `dcl_global_flags` (`FORCE_EARLY_DEPTH_STENCIL`) | drop the qualifier entirely when targeting GLSL ES 3.00 |
+
+---
+
+## Cross-cutting risks (lowest-confidence areas across this whole family)
+
+1. **`dcl_input_siv`** (3 corpus instances) — sample too small to be confident the
+   documented no-op/interpolation-recording behavior is even the path exercised;
+   verify against the actual 3 instances before trusting this section.
+2. ~~`noperspective` on `dcl_input_ps`~~ — resolved during review: the C++ source's
+   `hasNoPerspective` gate (`>LANG_ES_310`) is correct, not stale — GLSL ES 3.00
+   genuinely has no `noperspective` keyword, so the gate should be mirrored as-is
+   rather than second-guessed. `sample`/`centroid` remain core ES 3.00 keywords with
+   no gating concern.
+3. **Integer-vertex-attribute float-lowering generalization** — proven and validated
+   specifically for `BLENDINDICES`/`uvec4`; whether the same treatment is correct for
+   every other `INOUT_COMPONENT_UINT32`/`SINT32` vertex semantic in the corpus (and
+   whether the use-site cast should be a bit-pattern `floatBitsToUint` reinterpret vs.
+   a value-preserving `uint(...)` truncating convert) has not been separately proven
+   per-semantic.
+4. **`customdata` emission shape** — this spec recommends the Switch-target's
+   `const vec4[]` shape over the stock non-Vulkan/non-Switch mutable-early-main-array
+   shape as simpler and sufficient for this project's ES-300-with-dynamic-indexing
+   target; this recommendation is this document's own synthesis, not a literally
+   cited already-proven CarbonEngineJS-fork code path, and should be validated by an
+   actual WebGL2 compile before being treated as settled.
+5. **`dcl_global_flags` / `layout(early_fragment_tests) in;`** — whether any EVE
+   effect in the corpus actually sets `FORCE_EARLY_DEPTH_STENCIL` (making the WebGL2
+   suppression gate load-bearing rather than theoretical) was not verified in this
+   pass.
+
+