@forgeax/engine-shader 0.1.2

package/src/lighting-punctual.wgsl

@@ -0,0 +1,274 @@
+#define_import_path forgeax_pbr::lighting_punctual
+
+// @forgeax/engine-shader - lighting-punctual.wgsl
+// (feat-20260523-shader-template-instance-split M5 / T02).
+//
+// Point + spot light evaluators extracted from pbr.wgsl
+// (feat-20260519-light-casters-point-spot-pbr M4 / w22 byte-equivalent
+// extraction). Both light types share a punctual BRDF body (GGX specular +
+// Lambertian diffuse + Three r184 squared finite-range attenuation); the
+// only difference is that SpotLight multiplies a cone-falloff factor
+// `smoothstep(cosOuter, cosInner, dot(l, -lightDir))` on top.
+//
+// charter P4 consistent abstraction: one body, two thin wrappers that each
+// carry exactly the parameters their light type needs. evalPoint avoids the
+// "evalPunctual(cosInner=1, cosOuter=-1, ...)" magic-value collapse pattern
+// since `smoothstep(-1, 1, x)` is the Hermite cubic 0..1 (not a constant 1).
+//
+// Range attenuation (Three r184 squared finite-range authority):
+//   atten = clamp(1 - (d^2 * invR^2)^2, 0, 1)^2 / max(d^2, 1e-4)
+// `max(d^2, 1e-4)` math safety net keeps the divisor finite when the
+// fragment is at the light position (zero-distance NaN guard, layer 2 of
+// the two-layer fail-fast strategy alongside the host-side bounds gate).
+// `invRangeSquared = 0` collapses the quartic falloff to a pure 1/d^2 law.
+//
+// Pure-function module aside from the brdf #import; takes all light + surface
+// parameters as args so the helper does not declare its own bindings (host
+// material shader owns the @group(0) light buffer namespace).
+//
+// Exports:
+//   - evalPoint(lightPos, colorTimesIntensity, invRangeSquared, ...) -> vec3<f32>
+//   - evalSpot(lightPos, lightDir, colorTimesIntensity, cosInner, cosOuter,
+//              invRangeSquared, ...) -> vec3<f32>
+
+#import forgeax_pbr::brdf::{f_schlick, v_smith, d_ggx}
+// feat-20260625-spot-light-shadow-mapping M3 / w15 (plan-strategy D-3 + D-5):
+// spot shadow sampling reuses the shared 2D 9-tap PCF core (sample_shadow_2d)
+// and the always-on `spotShadowMap` (binding 8) + `shadowSampler` (binding 4).
+// `shadowSampler` is imported UNCONDITIONALLY here (spot is always-on, D-5):
+// the point-shadow #ifdef block below must NOT re-import it (double import).
+#import forgeax_pbr::shadow_pcf::{sample_shadow_2d}
+#import forgeax_view::common::{spotShadowMap, shadowSampler}
+#ifdef POINT_SHADOW_AVAILABLE
+#import forgeax_pbr::shadow_pcf::{sample_shadow_cube_hw2x2}
+// Pull in the @group(0) @binding(5) shadowAtlas declaration from common.wgsl so
+// the free-identifier references in `evalPointShadowed` resolve through
+// naga_oil's import scope. (`shadowSampler` is already imported above for the
+// always-on spot path.)
+#import forgeax_view::common::{shadowAtlas}
+#endif
+
+// Shared punctual BRDF body returning (diffuse + specular) *
+// colorTimesIntensity * nDotL * attenuation. Cone factor is applied by the
+// caller (evalSpot only).
+fn evalPunctualBody(
+  lightPos            : vec3<f32>,
+  colorTimesIntensity : vec3<f32>,
+  invRangeSquared     : f32,
+  worldPos            : vec3<f32>,
+  normal              : vec3<f32>,
+  viewDir             : vec3<f32>,
+  baseColor           : vec3<f32>,
+  metallic            : f32,
+  alphaSq             : f32,
+  F0                  : vec3<f32>,
+) -> vec3<f32> {
+  let toLight = lightPos - worldPos;
+  let dSquared = max(dot(toLight, toLight), 1e-4);
+  let l = toLight / sqrt(dSquared);
+  let h = normalize(viewDir + l);
+  let nDotL = max(dot(normal, l), 0.0);
+  let nDotV = max(dot(normal, viewDir), 1e-5);
+  let nDotH = max(dot(normal, h), 0.0);
+  let vDotH = max(dot(viewDir, h), 0.0);
+  let f = f_schlick(vDotH, F0);
+  let specular = d_ggx(nDotH, alphaSq) * v_smith(nDotV, nDotL, alphaSq) * f;
+  let kd = (vec3<f32>(1.0) - f) * (1.0 - metallic);
+  let diffuse = kd * baseColor / 3.14159265;
+  let factor = max(min(1.0 - (dSquared * invRangeSquared) * (dSquared * invRangeSquared), 1.0), 0.0);
+  let attenuation = factor * factor / dSquared;
+  return (diffuse + specular) * colorTimesIntensity * nDotL * attenuation;
+}
+
+// Omnidirectional point light: no cone factor.
+fn evalPoint(
+  lightPos            : vec3<f32>,
+  colorTimesIntensity : vec3<f32>,
+  invRangeSquared     : f32,
+  worldPos            : vec3<f32>,
+  normal              : vec3<f32>,
+  viewDir             : vec3<f32>,
+  baseColor           : vec3<f32>,
+  metallic            : f32,
+  alphaSq             : f32,
+  F0                  : vec3<f32>,
+) -> vec3<f32> {
+  return evalPunctualBody(
+    lightPos, colorTimesIntensity, invRangeSquared,
+    worldPos, normal, viewDir, baseColor, metallic, alphaSq, F0,
+  );
+}
+
+#ifdef POINT_SHADOW_AVAILABLE
+// Shadow-modulated omnidirectional point light: same BRDF body * shadow factor.
+//
+// feat-20260612-point-light-shadows-urp-hdrp M3 / T-M3-3 + M4 / T-M4-3
+// (plan-strategy §D-1 + §D-8). Only emitted when POINT_SHADOW_AVAILABLE is
+// true (forward path with the cube_array atlas at @group(0) binding 5).
+// The shadow factor is reconstructed from `lightLocal` via the largest-axis
+// projection (research L0.5 Bevy pattern); the caller passes `near` / `far`
+// directly so both pipelines route the same constants without owning the
+// upstream binding (URP reads them from `shadowParams[layer]` at @group(0)
+// binding 6; HDRP unpacks them off `LightSlot.kind_and_pad.zw` per
+// plan-strategy §D-8).
+//
+// Caller responsibility: gate this on `shadowAtlasLayer >= 0` so the
+// no-shadow lights stay on the unshadowed `evalPoint` path; passing a
+// negative layer here is undefined (the cube_array view rejects it).
+fn evalPointShadowed(
+  lightPos            : vec3<f32>,
+  colorTimesIntensity : vec3<f32>,
+  invRangeSquared     : f32,
+  worldPos            : vec3<f32>,
+  normal              : vec3<f32>,
+  viewDir             : vec3<f32>,
+  baseColor           : vec3<f32>,
+  metallic            : f32,
+  alphaSq             : f32,
+  F0                  : vec3<f32>,
+  shadowAtlasLayer    : i32,
+  near                : f32,
+  far                 : f32,
+  depthBias           : f32,
+  normalBias          : f32,
+) -> vec3<f32> {
+  let lit = evalPunctualBody(
+    lightPos, colorTimesIntensity, invRangeSquared,
+    worldPos, normal, viewDir, baseColor, metallic, alphaSq, F0,
+  );
+  // Fragment-to-light direction; cubemap sample uses the local-space
+  // direction (research L0.5: Bevy convention). For a right-handed world,
+  // the cubemap convention flips Z so the +Z face look direction matches.
+  let toLight = lightPos - worldPos;
+  // Cubemap sample direction is from-fragment-to-light (Bevy + LearnOpenGL),
+  // negated to fragment-from-light when reconstructing the depth ref.
+  let lightLocal = vec3<f32>(toLight.x, toLight.y, -toLight.z);
+  // Reconstruct [0,1] NDC depth from world-space distance: largest-axis
+  // projection (research L0.5). Match the per-face perspective near / far
+  // configured by buildPointShadowMatrices (PointLightShadow.nearPlane /
+  // farPlane on the host).
+  let absV = abs(vec3<f32>(toLight.x, toLight.y, toLight.z));
+  let largestAxis = max(absV.x, max(absV.y, absV.z));
+  // Perspective z-NDC reconstruction for the largest axis as the eye-space
+  // -z component (cube face look direction is the +axis the absolute value
+  // selected). z_ndc = far * (largest - near) / (largest * (far - near)).
+  let denom = max(largestAxis * (far - near), 1e-6);
+  let depthRef = clamp(far * (largestAxis - near) / denom, 0.0, 1.0);
+  let nDotL = max(dot(normal, normalize(toLight)), 0.0);
+  let shadowFactor = sample_shadow_cube_hw2x2(
+    shadowAtlas, shadowSampler, lightLocal, shadowAtlasLayer,
+    depthRef, depthBias, normalBias, nDotL,
+  );
+  return lit * shadowFactor;
+}
+#endif
+
+// Cone-restricted spot light: BRDF body * smoothstep cone factor.
+// `cosInner` / `cosOuter` are pre-computed cosines (host-side
+// degree -> cosine conversion in extract-frame; plan-strategy D-S2).
+fn evalSpot(
+  lightPos            : vec3<f32>,
+  lightDir            : vec3<f32>,
+  colorTimesIntensity : vec3<f32>,
+  cosInner            : f32,
+  cosOuter            : f32,
+  invRangeSquared     : f32,
+  worldPos            : vec3<f32>,
+  normal              : vec3<f32>,
+  viewDir             : vec3<f32>,
+  baseColor           : vec3<f32>,
+  metallic            : f32,
+  alphaSq             : f32,
+  F0                  : vec3<f32>,
+) -> vec3<f32> {
+  let body = evalPunctualBody(
+    lightPos, colorTimesIntensity, invRangeSquared,
+    worldPos, normal, viewDir, baseColor, metallic, alphaSq, F0,
+  );
+  let toLight = lightPos - worldPos;
+  let l = normalize(toLight);
+  let cone = smoothstep(cosOuter, cosInner, dot(l, -lightDir));
+  return body * cone;
+}
+
+// feat-20260625-spot-light-shadow-mapping M3 / w15 (plan-strategy D-3 + D-4 +
+// D-5). Shadow-modulated spot light: the unshadowed `evalSpot` result times a
+// PCF shadow factor sampled from the spot's perspective depth-atlas tile.
+//
+// Mirrors `evalPointShadowed`'s "shadowed wrapper + upstream gate" pattern
+// (research Finding B3): the caller gates on `shadowAtlasTile >= 0` so
+// no-shadow / clipped / direction-degenerate spots (tile = -1, plan D-4) stay
+// on the unshadowed `evalSpot` path.
+//
+// Depth-ref reconstruction is the standard perspective `splane.z / splane.w`
+// non-linear depth (plan-strategy D-4, godot-point-spot-shadows wiki S3.4):
+// store-side and sample-side share the SAME perspective `lightViewProj`, so the
+// projection's non-linearity cancels and no near/far reconstruction is needed
+// (unlike the point cube path's largest-axis projection).
+//
+// Atlas tiling: the host packs up to 4 spot shadows into a 2x2 grid of one
+// `spotShadowDepth` texture (urp-pipeline.ts). Tile N occupies quadrant
+// (col = N % 2, row = N / 2); the [0,1] light-clip UV is scaled to a 0.5x0.5
+// sub-rect and offset to the tile origin. PCF taps stay inside the tile by
+// scaling the texel step to the half-resolution sub-rect.
+//
+// OOB / NaN gate (research Finding F1, mirrors lighting-directional.wgsl): a
+// degenerate `lightViewProj` (near-zero spot direction) yields NaN UVs; the
+// `>= 0 && <= 1` form is false for NaN, so the fragment returns fully lit
+// (shadowFactor = 1.0) instead of a hard-black artifact.
+fn evalSpotShadowed(
+  lightPos            : vec3<f32>,
+  lightDir            : vec3<f32>,
+  colorTimesIntensity : vec3<f32>,
+  cosInner            : f32,
+  cosOuter            : f32,
+  invRangeSquared     : f32,
+  worldPos            : vec3<f32>,
+  normal              : vec3<f32>,
+  viewDir             : vec3<f32>,
+  baseColor           : vec3<f32>,
+  metallic            : f32,
+  alphaSq             : f32,
+  F0                  : vec3<f32>,
+  lightViewProj       : mat4x4<f32>,
+  shadowAtlasTile     : i32,
+  depthBias           : f32,
+  normalBias          : f32,
+) -> vec3<f32> {
+  let body = evalSpot(
+    lightPos, lightDir, colorTimesIntensity, cosInner, cosOuter, invRangeSquared,
+    worldPos, normal, viewDir, baseColor, metallic, alphaSq, F0,
+  );
+
+  // Project the fragment into the spot's light clip space.
+  let splane = lightViewProj * vec4<f32>(worldPos, 1.0);
+  // Perspective divide; guard a zero/near-zero w (fragment behind the light or
+  // a degenerate matrix) so the OOB gate below catches it as fully lit.
+  let invW = select(1.0 / splane.w, 0.0, abs(splane.w) < 1e-6);
+  let ndcXY = splane.xy * invW;
+  let depthRef = splane.z * invW;
+  // Clip-space [-1,1] -> texture UV [0,1] with the standard Y flip.
+  let clipUv = vec2<f32>(ndcXY.x * 0.5 + 0.5, ndcXY.y * -0.5 + 0.5);
+
+  // OOB / NaN gate: outside the light frustum (or NaN from a degenerate matrix)
+  // returns fully lit. Mirrors the directional `>= 0 && <= 1` NaN-safe form.
+  if (!(clipUv.x >= 0.0 && clipUv.x <= 1.0 && clipUv.y >= 0.0 && clipUv.y <= 1.0 && depthRef <= 1.0)) {
+    return body;
+  }
+
+  // Map the [0,1] light-clip UV into the spot's 2x2 atlas tile sub-rect.
+  let col = f32(shadowAtlasTile % 2);
+  let row = f32(shadowAtlasTile / 2);
+  let tileOrigin = vec2<f32>(col, row) * 0.5;
+  let atlasUv = clipUv * 0.5 + tileOrigin;
+
+  // texel step within the half-resolution sub-rect (atlas is 2x tile size).
+  let atlasDims = vec2<f32>(textureDimensions(spotShadowMap, 0));
+  let texel = vec2<f32>(1.0, 1.0) / atlasDims;
+
+  let nDotL = max(dot(normal, normalize(lightPos - worldPos)), 0.0);
+  let shadowFactor = sample_shadow_2d(
+    spotShadowMap, shadowSampler, atlasUv, texel, depthRef, normalBias, depthBias, nDotL,
+  );
+  return body * shadowFactor;
+}

package/src/material/artifact-registry.ts

@@ -0,0 +1,78 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+
+export interface MaterialRuntimeArtifact {
+  readonly key: string;
+  readonly bytes: Uint8Array;
+  readonly digest?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+export interface MaterialArtifactInspection {
+  readonly key: string;
+  readonly digest?: string;
+  readonly byteLength: number;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+export interface MaterialArtifactConflictError {
+  readonly code: 'material-artifact-conflict';
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: {
+    readonly key: string;
+    readonly existingDigest?: string;
+    readonly incomingDigest?: string;
+  };
+}
+
+function equalBytes(left: Uint8Array, right: Uint8Array): boolean {
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+
+export class MaterialArtifactRegistry {
+  readonly #artifacts = new Map<string, MaterialRuntimeArtifact>();
+
+  register(
+    artifact: MaterialRuntimeArtifact,
+  ): Result<MaterialRuntimeArtifact, MaterialArtifactConflictError> {
+    const previous = this.#artifacts.get(artifact.key);
+    if (previous !== undefined) {
+      if (equalBytes(previous.bytes, artifact.bytes)) return ok(previous);
+      return err({
+        code: 'material-artifact-conflict',
+        expected: 'one immutable artifact byte sequence per specialization key',
+        hint: 're-cook the conflicting specialization and publish one artifact digest',
+        detail: {
+          key: artifact.key,
+          ...(previous.digest ? { existingDigest: previous.digest } : {}),
+          ...(artifact.digest ? { incomingDigest: artifact.digest } : {}),
+        },
+      });
+    }
+    const immutable = Object.freeze(artifact);
+    this.#artifacts.set(artifact.key, immutable);
+    return ok(immutable);
+  }
+
+  get(key: string): MaterialRuntimeArtifact | undefined {
+    return this.#artifacts.get(key);
+  }
+
+  inspect(key: string): MaterialArtifactInspection | undefined {
+    const artifact = this.#artifacts.get(key);
+    if (artifact === undefined) return undefined;
+    return {
+      key: artifact.key,
+      ...(artifact.digest === undefined ? {} : { digest: artifact.digest }),
+      byteLength: artifact.bytes.byteLength,
+      ...(artifact.metadata === undefined ? {} : { metadata: artifact.metadata }),
+    };
+  }
+}
+
+export function registerMaterialArtifact(
+  registry: MaterialArtifactRegistry,
+  artifact: MaterialRuntimeArtifact,
+): Result<MaterialRuntimeArtifact, MaterialArtifactConflictError> {
+  return registry.register(artifact);
+}

package/src/material/artifact-types.ts

@@ -0,0 +1,26 @@
+import type { BindGroupLayoutDescriptor } from '@forgeax/engine-types';
+
+export interface MaterialShaderArtifact {
+  readonly material: string;
+  readonly pass: string;
+  readonly wgsl: string;
+  readonly layoutIdentity: string;
+  readonly bindings: readonly BindGroupLayoutDescriptor[];
+  readonly deps: readonly string[];
+  readonly vertexInputs: readonly Readonly<Record<string, unknown>>[];
+  readonly specializationKey?: string;
+}
+
+export function isMaterialShaderArtifact(value: unknown): value is MaterialShaderArtifact {
+  if (value === null || typeof value !== 'object') return false;
+  const artifact = value as Partial<MaterialShaderArtifact>;
+  return (
+    typeof artifact.material === 'string' &&
+    typeof artifact.pass === 'string' &&
+    typeof artifact.wgsl === 'string' &&
+    typeof artifact.layoutIdentity === 'string' &&
+    Array.isArray(artifact.bindings) &&
+    Array.isArray(artifact.deps) &&
+    Array.isArray(artifact.vertexInputs)
+  );
+}

package/src/material-schemas.ts

@@ -0,0 +1,48 @@
+import type { ParamSchemaEntry } from '@forgeax/engine-types';
+
+export const STANDARD_PBR_ALPHA_CUTOFF_DEFAULT = 0;
+
+/** Shared material contract for the standard PBR and skinned PBR shaders. */
+export const DEFAULT_STANDARD_PBR_PARAM_SCHEMA: readonly ParamSchemaEntry[] = [
+  { name: 'baseColor', type: 'color', default: [1, 1, 1, 1] },
+  { name: 'metallic', type: 'f32', default: 0 },
+  { name: 'roughness', type: 'f32', default: 0.5 },
+  { name: 'metallicChannel', type: 'f32', default: 2 },
+  { name: 'roughnessChannel', type: 'f32', default: 1 },
+  { name: 'aoChannel', type: 'f32', default: 0 },
+  { name: 'extraChannel', type: 'f32', default: 0 },
+  { name: 'emissive', type: 'vec3', colorSpace: 'srgb', default: [0, 0, 0] },
+  { name: 'emissiveIntensity', type: 'f32', default: 0 },
+  { name: 'occlusionStrength', type: 'f32', default: 1 },
+  { name: 'alphaCutoff', type: 'f32', default: STANDARD_PBR_ALPHA_CUTOFF_DEFAULT },
+  { name: 'clearcoat', type: 'f32', default: 0 },
+  { name: 'clearcoatRoughness', type: 'f32', default: 0.5 },
+  { name: 'specularTint', type: 'vec3', colorSpace: 'srgb', default: [1, 1, 1] },
+  { name: 'normalScale', type: 'f32', default: 1 },
+  { name: 'baseColorTexture', type: 'texture2d' },
+  { name: 'metallicRoughnessTexture', type: 'texture2d' },
+  { name: 'normalTexture', type: 'texture2d' },
+  { name: 'specularTintTexture', type: 'texture2d' },
+  { name: 'emissiveTexture', type: 'texture2d' },
+  { name: 'occlusionTexture', type: 'texture2d' },
+];
+
+export const DEFAULT_UNLIT_PARAM_SCHEMA: readonly ParamSchemaEntry[] = [
+  { name: 'baseColor', type: 'color', default: [1, 1, 1, 1] },
+  { name: 'alphaCutoff', type: 'f32', default: 0 },
+  { name: 'baseColorTexture', type: 'texture2d' },
+];
+
+export const DEFAULT_SPRITE_PARAM_SCHEMA: readonly ParamSchemaEntry[] = [
+  { name: 'colorTint', type: 'vec4', colorSpace: 'srgb', default: [1, 1, 1, 1] },
+  { name: 'region', type: 'vec4', default: [0, 0, 1, 1] },
+  { name: 'pivotAndSize', type: 'vec4', default: [0.5, 0.5, 1, 1] },
+  { name: 'slicesAndMode', type: 'vec4', default: [0, 0, 0, 0] },
+  { name: 'baseColorTexture', type: 'texture2d' },
+];
+
+export const DEFAULT_MSDF_TEXT_PARAM_SCHEMA: readonly ParamSchemaEntry[] = [
+  { name: 'tintColor', type: 'color', default: [1, 1, 1, 1] },
+  { name: 'distanceRange', type: 'vec4', default: [4, 512, 512, 0] },
+  { name: 'baseColorTexture', type: 'texture2d' },
+];

package/src/msdf-text.wgsl

@@ -0,0 +1,208 @@
+#pragma variant_axis STORAGE_BUFFER_AVAILABLE
+
+#import forgeax_view::common::{View, FogViewParams, FogRay, Mesh, view, meshes, sampleMaterialTexture}
+#import forgeax_view::fog::{apply_fog}
+
+// @forgeax/engine-shader - msdf-text.wgsl
+// (feat-20260531-world-space-msdf-text-rendering M5 / w20).
+//
+// World-space MSDF text material -- the 5th MaterialAsset shader after
+// 'unlit' / 'standard' / 'sprite'. Text entities are baked into a standard
+// mesh entity (glyph quads in local layout space; position.xy = layout x/y,
+// position.z = 0; uv = atlas UV) and ride the existing forward path via
+// `materialShaderId='forgeax::msdf-text'` (D-7 -- zero new pipelineTag,
+// reuses the 'unlit' pipeline tag + transparent bucket + premultiplied
+// alpha blend ONE / ONE_MINUS_SRC_ALPHA).
+//
+// Anchors:
+//   - plan-strategy D-3 (GPU billboard; WGSL has no inverse(), camera basis
+//     reconstructed without inverse() -- Finding 5/6/7)
+//   - plan-strategy D-7 (premultiplied output vec4(tint.rgb*alpha, alpha);
+//     ONE / ONE_MINUS_SRC_ALPHA; writes hdrColor so bloom catches it -- R-7)
+//   - knowledge-base/wiki/msdf-text-rendering.md section 6 (median + screenPxRange
+//     SSOT) + section 2 (median-of-three corner preservation)
+//   - requirements AC-10 (GPU billboard not degenerate to a line) + AC-12
+//     (bloom / premultiplied) + C3 (materialShaderId path, zero pipelineTag)
+//     + C4 (billboard x pick orientation independence)
+//
+// Billboard construction (D-3 / Finding 5/6/7):
+//   The mesh vertex.pos.xy carries the per-glyph layout coordinate (already
+//   includes intra-line advance + multi-line \n offset baked by the layout
+//   system). The quad is expanded along the camera's right / up basis vectors
+//   in WORLD space so the text always faces the camera (Finding 7: the quad
+//   normal is the camera forward direction, so "text plane parallel to view
+//   ray" never happens -- no NaN / flip flicker). WGSL exposes no inverse()
+//   built-in (Finding 5); the camera right / up are reconstructed from the
+//   world-space anchor and `view.cameraPos` (a look-at frame) with only
+//   normalize / cross -- zero matrix inverse, zero per-frame CPU rewrite of
+//   the mesh. `anchor` = the model matrix translation column
+//   (meshes[idx].worldFromLocal column 3).
+//
+// Bindings (mirror sprite.wgsl / unlit.wgsl byte-for-byte so the shared
+// 4-BindGroupLayout chain is reused without a per-pipeline BGL; the
+// metallicRoughness / normal slots 3..6 stay declared-but-unused, bound to
+// pipelineState defaults at the host side -- D-1 candidate b):
+//
+//   @group(0) @binding(0) view                       uniform   (msdf-text reads
+//                                                               worldViewProj +
+//                                                               cameraPos)
+//   @group(1) @binding(0) material                   uniform   (tintColor vec4
+//                                                               + distanceRange
+//                                                               f32 + atlas dims)
+//   @group(1) @binding(1) baseColorSampler           sampler   (atlas sampler)
+//   @group(1) @binding(2) baseColorTexture           texture_2d<f32> (MSDF atlas)
+//   @group(2) @binding(0) meshes                     storage   (msdf-text reads
+//                                                               meshes[idx]
+//                                                               .worldFromLocal
+//                                                               translation
+//                                                               column = anchor)
+
+struct Material {
+  // tintColor: per-text color multiplied onto the reconstructed coverage
+  // alpha. Maps to the `tintColor` paramSchema entry (default opaque white).
+  tintColor : vec4<f32>,
+  // distanceRange: atlas-space distance-field width (msdfgen -pxrange output,
+  // = sidecar.common.distanceRange). atlasSize.xy carries the atlas pixel
+  // dimensions so screenPxRange can convert atlas units to screen pixels.
+  // distanceRange in .x; atlasSize in .yz; .w padding (std140 vec4 align).
+  distanceRange : vec4<f32>,
+  baseColorTextureCoordinatesTransform : vec4<f32>,
+  baseColorTextureCoordinatesMetadata : vec4<f32>,
+};
+
+@group(1) @binding(0) var<uniform> material : Material;
+@group(1) @binding(1) var baseColorSampler : sampler;
+@group(1) @binding(2) var baseColorTexture : texture_2d<f32>;
+// Preserve filtering reflection for the bound texture passed to the helper.
+fn materialTextureFilteringWitness() {
+  let base = baseColorTexture;
+  let baseWitness = textureSample(base, baseColorSampler, vec2<f32>(0.0));
+}
+
+struct VsIn {
+  @location(0) pos     : vec3<f32>,
+  @location(1) normal  : vec3<f32>,
+  @location(2) uv      : vec2<f32>,
+  @location(3) tangent : vec4<f32>,
+};
+
+struct VsOut {
+  @builtin(position) clip : vec4<f32>,
+  @location(0) uv         : vec2<f32>,
+  @location(1) worldPos   : vec3<f32>,
+};
+
+@vertex
+fn vs_main(in : VsIn, @builtin(instance_index) idx : u32) -> VsOut {
+  // anchor = the entity world-matrix translation column (D-3). The layout
+  // system bakes the glyph quads in local layout space (Y-up), so the model
+  // matrix is a pure Translate (Rotate / Scale folded into the layout) and
+  // its 4th column is the world-space anchor.
+  let model = meshes[idx].worldFromLocal;
+  let anchor = model[3].xyz;
+  // Camera look-at frame (Finding 5/6/7): forward = anchor -> camera. WGSL
+  // has no inverse() built-in; the right / up basis is reconstructed from
+  // `view.cameraPos` + the world up reference (0,1,0) with normalize / cross
+  // only -- zero matrix inverse, the quad normal is always the camera
+  // forward direction so the billboard never degenerates to a line.
+  let forward = normalize(view.cameraPos - anchor);
+  // Guard against the camera looking straight down/up the world-up axis
+  // (forward parallel to (0,1,0)): fall back to a +Z up reference so cross()
+  // stays well-conditioned. This is the only degenerate case (Finding 7) and
+  // is resolved here rather than producing a NaN basis.
+  let upRef = select(
+    vec3<f32>(0.0, 1.0, 0.0),
+    vec3<f32>(0.0, 0.0, 1.0),
+    abs(forward.y) > 0.999,
+  );
+  let right = normalize(cross(upRef, forward));
+  let up = cross(forward, right);
+  // Expand the glyph quad's local layout coordinate along the world-space
+  // right / up basis (Finding 6: billboard-rotate then translate). pos.z is
+  // 0 for every baked glyph vertex so it contributes nothing.
+  let world_pos = anchor + right * in.pos.x + up * in.pos.y;
+  var out : VsOut;
+  out.clip = view.worldViewProj * vec4<f32>(world_pos, 1.0);
+  out.uv = in.uv;
+  out.worldPos = world_pos;
+  return out;
+}
+
+// median(R, G, B): corner-preserving MSDF reconstruction operator (wiki
+// section 2). Picks the distance supported by two-or-more edges so sharp
+// corners survive bilinear upscaling (median = max(min, min(max)) form).
+fn median(r : f32, g : f32, b : f32) -> f32 {
+  return max(min(r, g), min(max(r, g), b));
+}
+
+// screenPxRange: converts the atlas-space distanceRange into a screen-pixel
+// ramp width using fwidth() of the atlas UV (wiki section 3.3 / section 6). The
+// `max(., 1.0)` floor keeps the anti-aliasing ramp at least half a pixel wide
+// (msdfgen README: ramp < 1 px degrades back to a hard step / aliasing).
+fn screen_px_range(uv : vec2<f32>) -> f32 {
+  let atlas_dims = material.distanceRange.yz;
+  let unit_range = vec2<f32>(material.distanceRange.x) / atlas_dims;
+  let screen_tex_size = vec2<f32>(1.0) / fwidth(uv);
+  return max(0.5 * dot(unit_range, screen_tex_size), 1.0);
+}
+
+fn applySceneFog(viewParams : View, color : vec3<f32>, alpha : f32, worldPos : vec3<f32>) -> vec4<f32> {
+  var origin = viewParams.cameraPos;
+  var direction = normalize(worldPos - origin);
+  var rayDistance = length(worldPos - origin);
+  if (viewParams.temporalProjection.z >= 0.5) {
+    let nearH = viewParams.inverseViewProj * vec4<f32>(0.0, 0.0, 0.0, 1.0);
+    let farH = viewParams.inverseViewProj * vec4<f32>(0.0, 0.0, 1.0, 1.0);
+    let nearPoint = nearH.xyz / nearH.w;
+    let farPoint = farH.xyz / farH.w;
+    direction = normalize(farPoint - nearPoint);
+    origin = worldPos - direction * dot(worldPos - viewParams.cameraPos, direction);
+    rayDistance = max(dot(worldPos - origin, direction), 0.0);
+  }
+  return apply_fog(viewParams.fog, FogRay(origin, direction, rayDistance), vec4<f32>(color, alpha));
+}
+
+// fs_main_hdr: outputs linear premultiplied alpha for the rgba16float
+// offscreen target (D-7 / R-7). The tonemap fullscreen pass handles sRGB
+// encoding; writing hdrColor lets the bloom bright-pass catch the text.
+@fragment
+fn fs_main_hdr(in : VsOut) -> @location(0) vec4<f32> {
+  let msd = sampleMaterialTexture(baseColorTexture, baseColorSampler, in.uv, material.baseColorTextureCoordinatesMetadata.zw).rgb;
+  let sd = median(msd.r, msd.g, msd.b);
+  // wiki section 3.3: opacity = clamp((sd - 0.5) * screenPxRange + 0.5, 0, 1)
+  // (linear ramp; equivalent to smoothstep(0.5 - delta, 0.5 + delta, sd) at
+  // sub-pixel error -- wiki section 3.2 form-equivalence callout).
+  let dist = (sd - 0.5) * screen_px_range(in.uv);
+  let alpha = clamp(dist + 0.5, 0.0, 1.0) * material.tintColor.a;
+  // Premultiplied output: rgb already multiplied by alpha for srcFactor=ONE /
+  // dstFactor=ONE_MINUS_SRC_ALPHA (wiki section 6 SSOT).
+  let fogged = applySceneFog(view, material.tintColor.rgb, alpha, in.worldPos);
+  return vec4<f32>(fogged.rgb * fogged.a, fogged.a);
+}
+
+// linear_to_srgb: per-channel IEC 61966-2-1 transfer function for the LDR
+// bgra8unorm swap-chain target (not hardware-sRGB-encoded). Alpha is NOT
+// encoded -- the blend equation operates on raw alpha.
+fn linear_to_srgb(linear : f32) -> f32 {
+  let c = clamp(linear, 0.0, 1.0);
+  return select(c * 12.92, pow(c, 1.0 / 2.4) * 1.055 - 0.055, c > 0.0031308);
+}
+
+// fs_main: LDR variant for the bgra8unorm target. Same coverage math as the
+// HDR variant; encodes RGB through the sRGB transfer function (the LDR target
+// is not hardware-sRGB-encoded), alpha stays linear through the blend.
+@fragment
+fn fs_main(in : VsOut) -> @location(0) vec4<f32> {
+  let msd = sampleMaterialTexture(baseColorTexture, baseColorSampler, in.uv, material.baseColorTextureCoordinatesMetadata.zw).rgb;
+  let sd = median(msd.r, msd.g, msd.b);
+  let dist = (sd - 0.5) * screen_px_range(in.uv);
+  let alpha = clamp(dist + 0.5, 0.0, 1.0) * material.tintColor.a;
+  let fogged = applySceneFog(view, material.tintColor.rgb, alpha, in.worldPos);
+  let premult = fogged.rgb * fogged.a;
+  return vec4<f32>(
+    linear_to_srgb(premult.r),
+    linear_to_srgb(premult.g),
+    linear_to_srgb(premult.b),
+    fogged.a,
+  );
+}