@forgeax/engine-shader 0.1.2

package/src/taa-resolve.wgsl

@@ -0,0 +1,129 @@
+#define_import_path forgeax_view::taa_resolve
+
+#import forgeax_view::common::fullscreen_triangle
+#import forgeax_view::common::FullscreenOutput
+
+struct TaaResolveParams {
+  currentJitterUv : vec2<f32>,
+  historyValid : u32,
+  temporalFrameIndex : u32,
+};
+
+struct TaaResolveOutput {
+  @location(0) color : vec4<f32>,
+  @location(1) temporal : vec4<f32>,
+};
+
+@group(0) @binding(0) var currentColor : texture_2d<f32>;
+@group(0) @binding(1) var currentTemporal : texture_2d<f32>;
+@group(0) @binding(2) var historyColor : texture_2d<f32>;
+@group(0) @binding(3) var historyTemporal : texture_2d<f32>;
+@group(0) @binding(4) var historySampler : sampler;
+@group(0) @binding(5) var<uniform> params : TaaResolveParams;
+
+fn rgbToYCoCg(rgb : vec3<f32>) -> vec3<f32> {
+  return vec3<f32>(
+    dot(rgb, vec3<f32>(0.25, 0.5, 0.25)),
+    dot(rgb, vec3<f32>(0.5, 0.0, -0.5)),
+    dot(rgb, vec3<f32>(-0.25, 0.5, -0.25)),
+  );
+}
+
+fn yCoCgToRgb(value : vec3<f32>) -> vec3<f32> {
+  return vec3<f32>(value.x + value.y - value.z, value.x + value.z, value.x - value.y - value.z);
+}
+
+fn luminance(rgb : vec3<f32>) -> f32 {
+  return dot(rgb, vec3<f32>(0.2126, 0.7152, 0.0722));
+}
+
+fn jitterCorrectedCurrent(uv : vec2<f32>) -> vec4<f32> {
+  // The resolve and history live in the unjittered output domain. The main
+  // scene raster is the only jittered consumer, so re-center its color here;
+  // packed motion is already unjittered currentUv - previousUv.
+  return textureSampleLevel(currentColor, historySampler, uv + params.currentJitterUv, 0.0);
+}
+
+fn closestCurrentTemporal(pixel : vec2<i32>, dimensions : vec2<i32>) -> vec4<f32> {
+  var closest = vec4<f32>(0.0, 0.0, -1.0, 1.0);
+  var closestDepth = 1e20;
+  for (var y = -1; y <= 1; y += 1) {
+    for (var x = -1; x <= 1; x += 1) {
+      let samplePixel = clamp(pixel + vec2<i32>(x, y), vec2<i32>(0), dimensions - vec2<i32>(1));
+      let candidate = textureLoad(currentTemporal, samplePixel, 0);
+      if candidate.z >= 0.0 && candidate.z < closestDepth {
+        closest = candidate;
+        closestDepth = candidate.z;
+      }
+    }
+  }
+  return closest;
+}
+
+@vertex
+fn vs_taa_resolve(@builtin(vertex_index) vertexIndex : u32) -> FullscreenOutput {
+  return fullscreen_triangle(vertexIndex);
+}
+
+@fragment
+fn fs_taa_resolve(in : FullscreenOutput) -> TaaResolveOutput {
+  let dimensions = vec2<i32>(textureDimensions(currentColor));
+  let pixel = clamp(vec2<i32>(in.position.xy), vec2<i32>(0), dimensions - vec2<i32>(1));
+  let current = jitterCorrectedCurrent(in.uv);
+  let temporal = closestCurrentTemporal(pixel, dimensions);
+
+  var output : TaaResolveOutput;
+  output.temporal = temporal;
+  output.color = current;
+
+  let historyUv = in.uv - temporal.xy;
+  let historyInBounds = all(historyUv >= vec2<f32>(0.0)) && all(historyUv < vec2<f32>(1.0));
+  if params.historyValid == 0u || !historyInBounds || temporal.z < 0.0 {
+    return output;
+  }
+
+  let previousTemporal = textureSampleLevel(historyTemporal, historySampler, historyUv, 0.0);
+  let depthDelta = abs(previousTemporal.z - temporal.z);
+  let depthThreshold = max(0.01, temporal.z * 0.01);
+  if previousTemporal.z < 0.0 || depthDelta > depthThreshold {
+    return output;
+  }
+
+  var neighborhoodMin = vec3<f32>(1e20);
+  var neighborhoodMax = vec3<f32>(-1e20);
+  var neighborhoodMean = vec3<f32>(0.0);
+  var neighborhoodSquareMean = vec3<f32>(0.0);
+  for (var y = -1; y <= 1; y += 1) {
+    for (var x = -1; x <= 1; x += 1) {
+      let sampleUv = in.uv + vec2<f32>(f32(x), f32(y)) / vec2<f32>(dimensions);
+      let sampleValue = rgbToYCoCg(jitterCorrectedCurrent(sampleUv).rgb);
+      neighborhoodMin = min(neighborhoodMin, sampleValue);
+      neighborhoodMax = max(neighborhoodMax, sampleValue);
+      neighborhoodMean += sampleValue;
+      neighborhoodSquareMean += sampleValue * sampleValue;
+    }
+  }
+  neighborhoodMean /= 9.0;
+  neighborhoodSquareMean /= 9.0;
+  let sigma = sqrt(max(neighborhoodSquareMean - neighborhoodMean * neighborhoodMean, vec3<f32>(0.0)));
+  let clipMin = max(neighborhoodMin, neighborhoodMean - sigma * 1.25);
+  let clipMax = min(neighborhoodMax, neighborhoodMean + sigma * 1.25);
+
+  let sampledHistory = textureSampleLevel(historyColor, historySampler, historyUv, 0.0);
+  let clippedHistoryRgb = yCoCgToRgb(clamp(rgbToYCoCg(sampledHistory.rgb), clipMin, clipMax));
+  let velocityFactor = 1.0 - clamp(length(temporal.xy) * 64.0, 0.0, 1.0);
+  let reactiveFactor = 1.0 - clamp(temporal.w, 0.0, 1.0);
+  let depthFactor = 1.0 - clamp(depthDelta / depthThreshold, 0.0, 1.0);
+  let currentLuma = luminance(current.rgb);
+  let historyLuma = luminance(clippedHistoryRgb);
+  let lumaDelta = abs(historyLuma - currentLuma);
+  let unbiasedLumaDelta = clamp(lumaDelta / max(max(currentLuma, historyLuma), 0.2), 0.0, 1.0);
+  let lumaFactor = (1.0 - unbiasedLumaDelta) * (1.0 - unbiasedLumaDelta);
+  let fixedPresetWeight = mix(0.88, 0.97, lumaFactor);
+  let startupWeight = f32(params.temporalFrameIndex) / f32(params.temporalFrameIndex + 1u);
+  let progressiveWeight = select(fixedPresetWeight, min(startupWeight, fixedPresetWeight), params.temporalFrameIndex < 8u);
+  let rejectionFactor = min(reactiveFactor, min(velocityFactor, depthFactor));
+  let historyWeight = progressiveWeight * rejectionFactor;
+  output.color = vec4<f32>(mix(current.rgb, clippedHistoryRgb, historyWeight), current.a);
+  return output;
+}

package/src/tbn.wgsl

@@ -0,0 +1,54 @@
+#define_import_path forgeax_pbr::tbn
+
+// @forgeax/engine-shader - tbn.wgsl (feat-20260523-shader-template-instance-split
+// M5 / T01).
+//
+// Tangent-space normal decode + TBN basis composition helpers extracted from
+// pbr.wgsl fs_main body. Pure-function module (zero @group / @binding) so it
+// composes cleanly into any material shader that wants tangent-space normal
+// mapping with the host's per-vertex tangent (vec4 with handedness in .w).
+//
+// RG-only tangent normal decode mirrors pbr.wgsl pre-split semantics
+// (charter P5 byte-equivalent extraction). The default 1x1 normal fallback
+// texture RG=(128,128) decodes to tangent (0,0,1) -- zero perturbation when
+// normalTexture is absent (host-side defaultNormalTextureView). RG encoding
+// also matches BC5 / RG normal maps and tolerates RGB normal maps (b is
+// dropped, z is recomputed -- equivalent for unit vectors).
+//
+// Exports:
+//   - decodeTangentSpaceNormalRg(rg)          -> vec3<f32>  (pure)
+//   - scaleTangentSpaceNormal(tn, scale)      -> vec3<f32>  (pure)
+//   - applyTBN(worldNormal, worldTangent, tn) -> vec3<f32>  (pure)
+
+// Decode a tangent-space normal from the RG channels of a normal-map sample.
+// Z is reconstructed via z = sqrt(saturate(1 - x^2 - y^2)); saturate guards
+// against numerically-out-of-unit (x,y) producing NaN.
+fn decodeTangentSpaceNormalRg(rg: vec2<f32>) -> vec3<f32> {
+  let xy = rg * 2.0 - vec2<f32>(1.0);
+  let z = sqrt(saturate(1.0 - dot(xy, xy)));
+  return vec3<f32>(xy, z);
+}
+
+// Scale the XY perturbation while reconstructing Z so normalScale=0 restores
+// the flat tangent normal and normalScale=1 preserves the sampled normal.
+fn scaleTangentSpaceNormal(tn: vec3<f32>, scale: f32) -> vec3<f32> {
+  let xy = tn.xy * scale;
+  let z = sqrt(saturate(1.0 - dot(xy, xy)));
+  return vec3<f32>(xy, z);
+}
+
+// Build the TBN basis from interpolated world-space normal + per-vertex
+// tangent (xyz with handedness sign in .w), then transform a tangent-space
+// normal `tn` into world-space. Re-normalises the input world normal +
+// re-orthogonalises the tangent against the normal so that small interpolation
+// drift across triangle barycentrics does not skew the basis.
+fn applyTBN(
+  worldNormal  : vec3<f32>,
+  worldTangent : vec4<f32>,
+  tn           : vec3<f32>,
+) -> vec3<f32> {
+  let n0 = normalize(worldNormal);
+  let t0 = normalize(worldTangent.xyz - dot(worldTangent.xyz, n0) * n0);
+  let b0 = cross(n0, t0) * worldTangent.w;
+  return normalize(t0 * tn.x + b0 * tn.y + n0 * tn.z);
+}

package/src/tonemap.ts

@@ -0,0 +1,13 @@
+/** Numeric mode IDs consumed by the built-in tonemap WGSL module. */
+export const TONEMAP_SHADER_MODE = {
+  none: 0,
+  reinhardExtended: 1,
+  linear: 2,
+  cineon: 3,
+  acesFilmic: 4,
+  agx: 5,
+  neutral: 6,
+  reinhard: 7,
+} as const;
+
+export type TonemapShaderMode = (typeof TONEMAP_SHADER_MODE)[keyof typeof TONEMAP_SHADER_MODE];

package/src/tonemap.wgsl

@@ -0,0 +1,177 @@
+#define_import_path forgeax_view::tonemap
+
+// @forgeax/engine-shader - Three r184 tone mapping output module.
+//
+// The public modes and formulas are the Three.js r184 oracle. The numeric
+// values are the binding contract mirrored by TONEMAP_SHADER_MODE in tonemap.ts.
+// `reinhard-extended` remains Forgeax's existing luminance-domain curve; the
+// distinct `reinhard` mode is Three's per-channel Reinhard curve.
+
+#import forgeax_view::common::FullscreenOutput
+#import forgeax_view::common::fullscreen_triangle
+#import forgeax_view::common::linearToSrgbOetf
+
+const TONEMAP_LUMINANCE_EPSILON : f32 = 1e-5;
+
+struct TonemapParams {
+  exposure   : f32,
+  whitePoint : f32,
+  mode       : u32,
+  pad1       : f32,
+};
+
+@group(1) @binding(0) var hdr  : texture_2d<f32>;
+@group(1) @binding(1) var samp : sampler;
+@group(1) @binding(2) var<uniform> params : TonemapParams;
+
+@vertex
+fn vs_main(@builtin(vertex_index) vertex_index : u32) -> FullscreenOutput {
+  return fullscreen_triangle(vertex_index);
+}
+
+fn tonemapReinhardExtended(color : vec3<f32>) -> vec3<f32> {
+  let luma = dot(color, vec3<f32>(0.2126, 0.7152, 0.0722));
+  let lw_sq = params.whitePoint * params.whitePoint;
+  let luma_prime = (luma * (1.0 + luma / lw_sq)) / (1.0 + luma);
+  let scale = luma_prime / max(luma, TONEMAP_LUMINANCE_EPSILON);
+  return color * scale;
+}
+
+fn tonemapLinear(color : vec3<f32>) -> vec3<f32> {
+  return clamp(color, vec3<f32>(0.0), vec3<f32>(1.0));
+}
+
+fn tonemapReinhard(color : vec3<f32>) -> vec3<f32> {
+  return clamp(color / (color + vec3<f32>(1.0)), vec3<f32>(0.0), vec3<f32>(1.0));
+}
+
+fn tonemapCineon(color : vec3<f32>) -> vec3<f32> {
+  let x = max(color - vec3<f32>(0.004), vec3<f32>(0.0));
+  let a = x * (6.2 * x + vec3<f32>(0.5));
+  let b = x * (6.2 * x + vec3<f32>(1.7)) + vec3<f32>(0.06);
+  return pow(a / b, vec3<f32>(2.2));
+}
+
+fn acesInput(color : vec3<f32>) -> vec3<f32> {
+  return vec3<f32>(
+    dot(vec3<f32>(0.59719, 0.35458, 0.04823), color),
+    dot(vec3<f32>(0.07600, 0.90834, 0.01566), color),
+    dot(vec3<f32>(0.02840, 0.13383, 0.83777), color),
+  );
+}
+
+fn acesOutput(color : vec3<f32>) -> vec3<f32> {
+  return vec3<f32>(
+    dot(vec3<f32>(1.60475, -0.53108, -0.07367), color),
+    dot(vec3<f32>(-0.10208, 1.10813, -0.00605), color),
+    dot(vec3<f32>(-0.00327, -0.07276, 1.07602), color),
+  );
+}
+
+fn tonemapAcesFilmic(color : vec3<f32>) -> vec3<f32> {
+  let input = acesInput(color / vec3<f32>(0.6));
+  let a = input * (input + vec3<f32>(0.0245786)) - vec3<f32>(0.000090537);
+  let b = input * ((input + vec3<f32>(0.4329510)) * vec3<f32>(0.983729)) + vec3<f32>(0.238081);
+  return clamp(acesOutput(a / b), vec3<f32>(0.0), vec3<f32>(1.0));
+}
+
+fn rec2020FromSrgb(color : vec3<f32>) -> vec3<f32> {
+  return vec3<f32>(
+    dot(vec3<f32>(0.6274, 0.3293, 0.0433), color),
+    dot(vec3<f32>(0.0691, 0.9195, 0.0113), color),
+    dot(vec3<f32>(0.0164, 0.0880, 0.8956), color),
+  );
+}
+
+fn srgbFromRec2020(color : vec3<f32>) -> vec3<f32> {
+  return vec3<f32>(
+    dot(vec3<f32>(1.6605, -0.5876, -0.0728), color),
+    dot(vec3<f32>(-0.1246, 1.1329, -0.0083), color),
+    dot(vec3<f32>(-0.0182, -0.1006, 1.1187), color),
+  );
+}
+
+fn agxContrastApprox(x : vec3<f32>) -> vec3<f32> {
+  let x2 = x * x;
+  let x4 = x2 * x2;
+  return 15.5 * x4 * x2
+    - 40.14 * x4 * x
+    + 31.96 * x4
+    - 6.868 * x2 * x
+    + 0.4298 * x2
+    + 0.1191 * x
+    - vec3<f32>(0.00232);
+}
+
+fn agxInset(color : vec3<f32>) -> vec3<f32> {
+  return vec3<f32>(
+    dot(vec3<f32>(0.856627153315983, 0.0951212405381588, 0.0482516061458583), color),
+    dot(vec3<f32>(0.137318972929847, 0.761241990602591, 0.101439036467562), color),
+    dot(vec3<f32>(0.11189821299995, 0.0767994186031903, 0.811302368396859), color),
+  );
+}
+
+fn agxOutset(color : vec3<f32>) -> vec3<f32> {
+  return vec3<f32>(
+    dot(vec3<f32>(1.1271005818144368, -0.11060664309660323, -0.016493938717834573), color),
+    dot(vec3<f32>(-0.1413297634984383, 1.157823702216272, -0.016493938717834257), color),
+    dot(vec3<f32>(-0.14132976349843826, -0.11060664309660294, 1.2519364065950405), color),
+  );
+}
+
+fn tonemapAgx(color : vec3<f32>) -> vec3<f32> {
+  let min_ev = -12.47393;
+  let max_ev = 4.026069;
+  let rec2020 = agxInset(rec2020FromSrgb(color));
+  let log_color = log2(max(rec2020, vec3<f32>(1e-10)));
+  let normalized = clamp(
+    (log_color - vec3<f32>(min_ev)) / vec3<f32>(max_ev - min_ev),
+    vec3<f32>(0.0),
+    vec3<f32>(1.0),
+  );
+  let contrasted = agxContrastApprox(normalized);
+  let encoded = pow(max(agxOutset(contrasted), vec3<f32>(0.0)), vec3<f32>(2.2));
+  return clamp(srgbFromRec2020(encoded), vec3<f32>(0.0), vec3<f32>(1.0));
+}
+
+fn tonemapNeutral(color : vec3<f32>) -> vec3<f32> {
+  let start_compression = 0.8 - 0.04;
+  let desaturation = 0.15;
+  let x = min(color.r, min(color.g, color.b));
+  let offset = select(0.04, x - 6.25 * x * x, x < 0.08);
+  var compressed = color - vec3<f32>(offset);
+  let peak = max(compressed.r, max(compressed.g, compressed.b));
+  if (peak < start_compression) {
+    return compressed;
+  }
+  let d = 1.0 - start_compression;
+  let new_peak = 1.0 - d * d / (peak + d - start_compression);
+  compressed *= new_peak / peak;
+  let g = 1.0 - 1.0 / (desaturation * (peak - new_peak) + 1.0);
+  return mix(compressed, vec3<f32>(new_peak), g);
+}
+
+@fragment
+fn fs_main(in : FullscreenOutput) -> @location(0) vec4<f32> {
+  // linearHdrColorDomain: hdr is sampled before the only HDR-to-LDR stage.
+  // linearLdrColorDomain: the output pass emits the display-target domain.
+  let source = textureSample(hdr, samp, in.uv);
+  let sample : vec3<f32> = source.rgb;
+  let exposed : vec3<f32> = sample * params.exposure;
+  var mapped : vec3<f32>;
+  switch (params.mode) {
+    case 1u: { mapped = tonemapReinhardExtended(exposed); }
+    case 2u: { mapped = tonemapLinear(exposed); }
+    case 3u: { mapped = tonemapCineon(exposed); }
+    case 4u: { mapped = tonemapAcesFilmic(exposed); }
+    case 5u: { mapped = tonemapAgx(exposed); }
+    case 6u: { mapped = tonemapNeutral(exposed); }
+    case 7u: { mapped = tonemapReinhard(exposed); }
+    // Mode 0 is the linear-LDR output pass used when tone mapping is disabled.
+    // It targets the raw canvas format and mirrors Three r184's output OETF.
+    default: { mapped = linearToSrgbOetf(exposed); }
+  }
+  // The mode-0 output pass is display-encoded; other modes retain their
+  // existing tonemap output contract.
+  return vec4<f32>(mapped, source.a);
+}

package/src/types.ts

@@ -0,0 +1,59 @@
+// @forgeax/engine-shader/types — shared variant types consumed by the runtime
+// variant resolution layer (createRenderer.ts M3). The SSOT for the manifest
+// schema stays in @forgeax/engine-vite-plugin-shader; this file re-declares the
+// runtime-visible subset so the engine-shader package avoids a physical import
+// of the build-time plugin (physical-isolation grep gate).
+
+/**
+ * Single variant within a material-shader manifest entry.
+ * `definesKey` is the canonical defines string (sorted `key=value` pairs joined
+ * with `+`). Empty key `""` denotes the default variant (all axes `true`).
+ *
+ * Authored by vite-plugin-shader Cartesian compile at buildStart; consumed by
+ * createRenderer variant resolution at engine boot (plan-strategy D-6).
+ *
+ * feat-20260613 fix-issue-2 (D-1 / D-2 bindingLayout cut): the runtime
+ * derives the BGL from `derive(paramSchema).bglEntries`; manifest entries
+ * no longer carry a bindingLayout sidecar (§Change stance: no v1/v2
+ * dual-path, no incremental drop window).
+ */
+export interface MaterialShaderManifestVariant {
+  readonly definesKey: string;
+  readonly defines: Record<string, boolean>;
+  readonly composedWgsl: string;
+}
+
+/**
+ * A material-shader entry in manifest.json carrying zero or more variants.
+ *
+ * When `variants` is empty the entry is single-variant (no `#pragma variant_axis`
+ * in the source). Otherwise `composedWgsl` carries the default
+ * (all-true) variant for backward compat; the `variants[]` array contains every
+ * compiled combination.
+ *
+ * For Engine.create() internal use only; AI users never see this type.
+ */
+export interface MaterialShaderManifestEntry {
+  readonly identifier: string;
+  readonly sourcePath: string;
+  readonly composedWgsl: string;
+  readonly paramSchema: string;
+  readonly variants: readonly MaterialShaderManifestVariant[];
+  /**
+   * feat-20260629 M4: uvSetCount from naga vertex @location reflection.
+   * Populated by vite-plugin-shader at build time from compileShader output.
+   * The runtime reads this for clamp-to-last alias in deriveVertexBufferLayout.
+   */
+  readonly uvSetCount?: number;
+}
+
+/**
+ * Look up a variant by canonical defines key.
+ * Returns `undefined` when no variant matches the requested key.
+ */
+export function findVariantByKey(
+  entry: MaterialShaderManifestEntry,
+  definesKey: string,
+): MaterialShaderManifestVariant | undefined {
+  return entry.variants.find((v) => v.definesKey === definesKey);
+}

package/src/unlit.wgsl

@@ -0,0 +1,186 @@
+#define_import_path forgeax_material::unlit
+#import forgeax_view::common::{View, FogViewParams, FogRay, Mesh, InstanceData, view, meshes, instances, sampleMaterialTextureLinear, packSceneTemporal}
+#import forgeax_view::fog::{apply_fog}
+
+#pragma variant_axis STORAGE_BUFFER_AVAILABLE
+#pragma variant_axis VERTEX_COLOR_AVAILABLE
+
+// @forgeax/engine-shader - unlit.wgsl (M5 feat-20260511-asset-system-v1;
+// refactored M5 T-18 feat-20260512-naga-oil-composition-hmr to pull View +
+// Mesh via naga_oil #import; expanded feat-20260518-pbr-direct-lighting-mvp
+// M2 / w8 to share binding 0-6 layout + 12-floats VsIn with pbr.wgsl).
+//
+// Minimal unlit material shader: world * view * proj transform + flat
+// fragment output of `material.baseColor * sample(baseColorTexture)`. No
+// lighting, no normal mapping, no metallic/roughness. Consumed by
+// RenderSystem when the material dispatch tag resolves to 'unlit'
+// (plan-strategy D-P4 / requirements AC-07). The pipeline binds:
+//
+//   @group(0) @binding(0) view                       uniform   (see common.wgsl;
+//                                                               unlit only reads
+//                                                               worldViewProj)
+//   @group(1) @binding(0) material                   uniform   (vec4 baseColor;
+//                                                               metallic/roughness
+//                                                               unused on this path)
+//   @group(1) @binding(1) baseColorSampler           sampler
+//   @group(1) @binding(2) baseColorTexture           texture_2d<f32>
+//   @group(2) @binding(0) meshes                     storage   (see common.wgsl;
+//                                                               normalMatrix not
+//                                                               consumed in unlit)
+//   @group(3) @binding(0) instances                  storage   (per-instance
+//                                                               localFromInstance mat4;
+//                                                               indexed by @builtin
+//                                                               (instance_index);
+//                                                               see common.wgsl)
+//
+// Material bindings are derived from the built-in paramSchema. Procedural
+// geometry (M4) emits 12-floats vertex stride
+// (pos+normal+uv+tangent); BUILTIN_CUBE / TRIANGLE keep 6-floats stride and
+// route to a dedicated unlit pipeline branch wired by RenderSystem (M3 w22).
+// This shader file consumes the 12-floats path; the 6-floats path is the
+// vertex pipeline branch's responsibility.
+
+struct Material {
+  baseColor : vec4<f32>,
+  alphaCutoff : 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>,
+#ifdef VERTEX_COLOR_AVAILABLE
+  @location(13) color : vec4<f32>,
+#endif
+};
+struct VsOut {
+  @builtin(position) clip : vec4<f32>,
+  @location(0) uv : vec2<f32>,
+  @location(1) worldPos : vec3<f32>,
+#ifdef VERTEX_COLOR_AVAILABLE
+  @location(14) color : vec4<f32>,
+#endif
+};
+
+@vertex
+fn vs_main(in : VsIn, @builtin(instance_index) idx : u32) -> VsOut {
+  // feat-20260604-instances-per-instance-transform-shader-group3-bin M1 / w5:
+  // entity world from meshes[0] (dynamic-offset window), per-instance local
+  // from instances[idx] (flat @group(3) buffer indexed by instance_index).
+  // Combine: entity_world * per_instance_local.
+  let world = meshes[0].worldFromLocal * instances[idx].localFromInstance * vec4<f32>(in.pos, 1.0);
+  var out : VsOut;
+  out.clip = view.worldViewProj * world;
+  out.uv = in.uv;
+  out.worldPos = world.xyz;
+#ifdef VERTEX_COLOR_AVAILABLE
+  out.color = in.color;
+#endif
+  return out;
+}
+
+fn materialVertexColor(in : VsOut) -> vec4<f32> {
+#ifdef VERTEX_COLOR_AVAILABLE
+  return in.color;
+#else
+  return vec4<f32>(1.0);
+#endif
+}
+
+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));
+}
+
+@fragment
+fn fs_main(in : VsOut) -> @location(0) vec4<f32> {
+  let texSample = sampleMaterialTextureLinear(baseColorTexture, baseColorSampler, in.uv, material.baseColorTextureCoordinatesMetadata.zw);
+  let vertexColor = materialVertexColor(in);
+  let alpha = material.baseColor.a * texSample.a * vertexColor.a;
+  if (material.alphaCutoff > 0.0 && alpha < material.alphaCutoff) {
+    discard;
+  }
+  return applySceneFog(
+    view,
+    material.baseColor.rgb * texSample.rgb * vertexColor.rgb,
+    alpha,
+    in.worldPos,
+  );
+}
+
+struct TemporalVsOut {
+  @builtin(position) clip : vec4<f32>,
+  @location(0) uv : vec2<f32>,
+  @location(1) @interpolate(linear) currentClip : vec4<f32>,
+  @location(2) @interpolate(linear) previousClip : vec4<f32>,
+#ifdef VERTEX_COLOR_AVAILABLE
+  @location(14) color : vec4<f32>,
+#endif
+};
+
+@vertex
+fn vs_temporal(in : VsIn, @builtin(instance_index) idx : u32) -> TemporalVsOut {
+  let currentWorld =
+    meshes[0].worldFromLocal * instances[idx].localFromInstance * vec4<f32>(in.pos, 1.0);
+  var previousWorld = currentWorld;
+#if STORAGE_BUFFER_AVAILABLE == true
+  previousWorld = meshes[0].previousWorldFromLocal *
+    instances[idx].previousLocalFromInstance * vec4<f32>(in.pos, 1.0);
+#endif
+  var out : TemporalVsOut;
+  out.currentClip = view.temporalCurrentViewProj * currentWorld;
+  out.clip = out.currentClip;
+  out.previousClip = view.temporalPreviousViewProj * previousWorld;
+  out.uv = in.uv;
+#ifdef VERTEX_COLOR_AVAILABLE
+  out.color = in.color;
+#endif
+  return out;
+}
+
+fn temporalVertexColor(in : TemporalVsOut) -> vec4<f32> {
+#ifdef VERTEX_COLOR_AVAILABLE
+  return in.color;
+#else
+  return vec4<f32>(1.0);
+#endif
+}
+
+@fragment
+fn fs_temporal(in : TemporalVsOut) -> @location(0) vec4<f32> {
+  let texSample = sampleMaterialTextureLinear(baseColorTexture, baseColorSampler, in.uv, material.baseColorTextureCoordinatesMetadata.zw);
+  let vertexColor = temporalVertexColor(in);
+  let alpha = material.baseColor.a * texSample.a * vertexColor.a;
+  if (material.alphaCutoff > 0.0 && alpha < material.alphaCutoff) {
+    discard;
+  }
+  var reactive = 1.0;
+#if STORAGE_BUFFER_AVAILABLE == true
+  reactive = meshes[0].temporal.x;
+#endif
+  return packSceneTemporal(in.currentClip, in.previousClip, reactive);
+}