feat(shaders): detect stale WGSL twins by hashing the authored GLSL

A generated WGSL twin was only ever (re)generated when MISSING — edit the
GLSL and the committed/generated twin silently went stale, so WebGPU kept
rendering the old shader and CI --check (presence-only) waved it through.
That undermined the contract that GLSL is the single source and the WGSL
twin is a derivative.

Make the derivation verifiable: each generated `wgsl full` twin now stores
`// source-hash: <hash>` of the authored GLSL (everything but the generated
sections, trimmed so generate→check round-trips exactly). needsTwin()/
sourceHash() are exported, pure and engine-free, so one definition of "stale"
is shared by:
- the CLI + CI --check (a stale or hash-less twin now reports would-generate),
- the editor's on-open generation (regenerates stale twins, not just missing).

Hand-authored `wgsl` twins (builtins) and `#pragma switch` shaders are left
alone. All committed generated twins gain their source-hash (WGSL bytes
unchanged — deterministic; +2 lines each). Extends the CI twin guard from
presence to freshness.

Verified: unit tests for the missing/fresh/stale/legacy/hand-authored/switch/
twin-edit-vs-glsl-edit cases; editing a shader's GLSL then opening it under
ESTELLA_SHOT_BACKEND=webgpu logs "generated 1 WGSL twin(s) on open" (the
editor now regenerates the stale twin). 3612 SDK tests green.

Author: esengine

desktop/electron/shaderTwins.ts

@@ -42,6 +42,9 @@ async function findEsshaders(dir: string, out: string[] = []): Promise<string[]>
 }
 
 interface TwinGenerator {
+    /** True when the shader has no twin, or a generated twin whose stored
+     *  source-hash no longer matches its GLSL (stale). Pure + cheap (no engine). */
+    needsTwin(source: string): boolean;
     loadTwinModule(): Promise<{ esshader_cookInfo(source: string, features: string): unknown }>;
     processFile(
         module: unknown,
@@ -67,15 +70,11 @@ export async function ensureProjectShaderTwins(
     const result = { generated: [] as string[], failed: [] as string[], skipped: [] as string[] };
 
     const files = await findEsshaders(root);
-    const needy: string[] = [];
-    for (const f of files) {
-        const src = await readFile(f, 'utf8').catch(() => '');
-        if (src.includes('#pragma fragment wgsl')) continue; // already has a twin
-        if (src.includes('#pragma switch')) { result.skipped.push(f); continue; }
-        needy.push(f);
-    }
-    if (needy.length === 0) return result;
+    if (files.length === 0) return result;
 
+    // Import the generator up front — cheap (pure JS; the engine + converter wasm
+    // load only in loadTwinModule below) — so its needsTwin decides which shaders
+    // are missing OR stale (a twin whose source-hash no longer matches its GLSL).
     let gen: TwinGenerator;
     try {
         const url = pathToFileURL(path.join(repoRoot, 'tools', 'gen-shader-twins.mjs')).href;
@@ -85,6 +84,13 @@ export async function ensureProjectShaderTwins(
         return result;
     }
 
+    const needy: string[] = [];
+    for (const f of files) {
+        const src = await readFile(f, 'utf8').catch(() => '');
+        if (gen.needsTwin(src)) needy.push(f);
+    }
+    if (needy.length === 0) return result;
+
     const module = await gen.loadTwinModule();
     for (const f of needy) {
         try {

desktop/public/scenes/mat-builtin-lit/lit.esshader

@@ -26,6 +26,7 @@ void main() {
 #pragma vertex wgsl full
 // GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
 // Regenerate after changing the GLSL stages above.
+// source-hash: 9f608a54b0f5c530
 struct gl_PerVertex {
     @builtin(position) gl_Position: vec4<f32>,
     gl_PointSize: f32,
@@ -101,6 +102,7 @@ fn vs_main(@location(0) a_position: vec2<f32>, @location(1) a_color: vec4<f32>,
 #pragma fragment wgsl full
 // GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
 // Regenerate after changing the GLSL stages above.
+// source-hash: 9f608a54b0f5c530
 struct Light2D {
     posDir: vec4<f32>,
     color: vec4<f32>,

desktop/public/scenes/mat-dissolve/dissolve.esshader

@@ -39,6 +39,7 @@ void main() {
 #pragma vertex wgsl full
 // GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
 // Regenerate after changing the GLSL stages above.
+// source-hash: 99e3d67aae0be3c6
 struct gl_PerVertex {
     @builtin(position) gl_Position: vec4<f32>,
     gl_PointSize: f32,
@@ -108,6 +109,7 @@ fn vs_main(@location(0) a_position: vec2<f32>, @location(1) a_color: vec4<f32>,
 #pragma fragment wgsl full
 // GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
 // Regenerate after changing the GLSL stages above.
+// source-hash: 99e3d67aae0be3c6
 struct MaterialConstants {
     u_progress: f32,
     u_edgeColor: vec4<f32>,

desktop/public/scenes/mat-graph/graph-tint.esshader

@@ -42,6 +42,7 @@ void main() {
 #pragma vertex wgsl full
 // GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
 // Regenerate after changing the GLSL stages above.
+// source-hash: 17d9cf90b8470378
 struct gl_PerVertex {
     @builtin(position) gl_Position: vec4<f32>,
     gl_PointSize: f32,
@@ -114,6 +115,7 @@ fn vs_main(@location(0) a_position: vec2<f32>, @location(1) a_color: vec4<f32>,
 #pragma fragment wgsl full
 // GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
 // Regenerate after changing the GLSL stages above.
+// source-hash: 17d9cf90b8470378
 struct MaterialConstants {
     u_tint: vec4<f32>,
 }

desktop/public/scenes/mat-lit-flatnormal/lit-fn.esshader

@@ -50,6 +50,7 @@ void main() {
 #pragma vertex wgsl full
 // GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
 // Regenerate after changing the GLSL stages above.
+// source-hash: 2109a83ca59fdb20
 struct gl_PerVertex {
     @builtin(position) gl_Position: vec4<f32>,
     gl_PointSize: f32,
@@ -121,6 +122,7 @@ fn vs_main(@location(0) a_position: vec2<f32>, @location(1) a_color: vec4<f32>,
 #pragma fragment wgsl full
 // GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
 // Regenerate after changing the GLSL stages above.
+// source-hash: 2109a83ca59fdb20
 struct Light2D {
     posDir: vec4<f32>,
     color: vec4<f32>,

desktop/public/scenes/mat-lit-normal/lit-normal.esshader

@@ -50,6 +50,7 @@ void main() {
 #pragma vertex wgsl full
 // GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
 // Regenerate after changing the GLSL stages above.
+// source-hash: 60ae4382caf672f0
 struct gl_PerVertex {
     @builtin(position) gl_Position: vec4<f32>,
     gl_PointSize: f32,
@@ -121,6 +122,7 @@ fn vs_main(@location(0) a_position: vec2<f32>, @location(1) a_color: vec4<f32>,
 #pragma fragment wgsl full
 // GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
 // Regenerate after changing the GLSL stages above.
+// source-hash: 60ae4382caf672f0
 struct Light2D {
     posDir: vec4<f32>,
     color: vec4<f32>,

desktop/public/scenes/mat-lit/lit.esshader

@@ -49,6 +49,7 @@ void main() {
 #pragma vertex wgsl full
 // GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
 // Regenerate after changing the GLSL stages above.
+// source-hash: 95a1f35f723b831c
 struct gl_PerVertex {
     @builtin(position) gl_Position: vec4<f32>,
     gl_PointSize: f32,
@@ -116,6 +117,7 @@ fn vs_main(@location(0) a_position: vec2<f32>, @location(1) a_color: vec4<f32>,
 #pragma fragment wgsl full
 // GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
 // Regenerate after changing the GLSL stages above.
+// source-hash: 95a1f35f723b831c
 struct Light2D {
     posDir: vec4<f32>,
     color: vec4<f32>,

desktop/public/scenes/mat-tex/masked.esshader

@@ -41,6 +41,7 @@ void main() {
 #pragma vertex wgsl full
 // GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
 // Regenerate after changing the GLSL stages above.
+// source-hash: 70fc4540fdcdb04a
 struct gl_PerVertex {
     @builtin(position) gl_Position: vec4<f32>,
     gl_PointSize: f32,
@@ -107,6 +108,7 @@ fn vs_main(@location(0) a_position: vec2<f32>, @location(1) a_color: vec4<f32>,
 #pragma fragment wgsl full
 // GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
 // Regenerate after changing the GLSL stages above.
+// source-hash: 70fc4540fdcdb04a
 struct TimeConstants {
     u_time: vec4<f32>,
     u_viewport: vec4<f32>,

examples/effects-gallery/assets/materials/hit-flash.esshader

@@ -24,6 +24,7 @@ void main() {
 #pragma vertex wgsl full
 // GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
 // Regenerate after changing the GLSL stages above.
+// source-hash: 1c3115bd7b73f674
 struct gl_PerVertex {
     @builtin(position) gl_Position: vec4<f32>,
     gl_PointSize: f32,
@@ -91,6 +92,7 @@ fn vs_main(@location(0) a_position: vec2<f32>, @location(1) a_color: vec4<f32>,
 #pragma fragment wgsl full
 // GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
 // Regenerate after changing the GLSL stages above.
+// source-hash: 1c3115bd7b73f674
 struct MaterialConstants {
     u_flash: f32,
     u_flashColor: vec4<f32>,

examples/effects-gallery/assets/materials/outline.esshader

@@ -33,6 +33,7 @@ void main() {
 #pragma vertex wgsl full
 // GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
 // Regenerate after changing the GLSL stages above.
+// source-hash: 0d65463ea0c29816
 struct gl_PerVertex {
     @builtin(position) gl_Position: vec4<f32>,
     gl_PointSize: f32,
@@ -100,6 +101,7 @@ fn vs_main(@location(0) a_position: vec2<f32>, @location(1) a_color: vec4<f32>,
 #pragma fragment wgsl full
 // GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.
 // Regenerate after changing the GLSL stages above.
+// source-hash: 0d65463ea0c29816
 struct MaterialConstants {
     u_outlineColor: vec4<f32>,
     u_outlineWidth: f32,