ci: ?nogrid escape hatch replaces ciSkip for the Grid-stall trio; UPSTREAM B12

DemoHelpers honors a test-only ?nogrid query param; CI navigates the three
Grid+node-graph stall examples with it instead of skipping them - restores
smoke coverage AND doubles as the bisection experiment (green = Grid-shader
hypothesis confirmed; still stalling = falsified, revert to skips).

B12: useUniforms scope/name strings flow unvalidated into WGSL identifiers
(kebab-case scope = runtime shader compile error; suggest sanitize or throw).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: DennisSmolek

docs/UPSTREAM.md

@@ -135,6 +135,19 @@ commit** (AGENTS.md points agents at this file).
 - **Suggested fix**: let `Fn`'s type accept a tuple of node-typed params (generic
   parameter per arg, or a `Fn<[Node<'float'>, Node<'vec3'>]>` signature).
 
+### B12 · fiber: `useUniforms` scope/name strings flow unvalidated into WGSL identifiers
+
+- **What**: the debug name fiber generates for a uniform (`${scope}_${name}`) ends up
+  as a WGSL struct member identifier. WGSL forbids hyphens (and other JS-string-legal
+  characters), so a kebab-case scope name (`useUniforms('halftone-purple', …)`)
+  produces a **runtime fragment-shader compile error** — tsc and the build both pass;
+  nothing fails until the shader compiles in the browser.
+- **Evidence**: hit porting `webgpu_tsl_halftone`; caught only by our smoke suite's
+  console-error assertion. Renaming the scope to camelCase fixed it.
+- **Suggested fix**: sanitize the generated identifier (replace non-`[A-Za-z0-9_]`
+  chars) or throw early from `useUniforms` with a clear message naming the offending
+  scope/key. Silent pass-through into codegen is the worst of the options.
+
 ### B11 · @types/three: `Scene.fogNode` missing
 
 - **What**: `Scene.fogNode` is a real webgpu runtime property (read by

src/app/manifest.ts

@@ -12,6 +12,9 @@ export interface ExampleMeta {
   credits?: string
   /** CI smoke-tier exception (SPEC §10): reason this example can't run on SwiftShader. */
   ciSkip?: string
+  /** CI runs this example with ?nogrid (DemoHelpers grid suppressed) — SwiftShader
+   * Grid+node-graph stall workaround that keeps smoke coverage. Value = reason. */
+  ciNoGrid?: string
 }
 
 export const exampleMeta = examples as ExampleMeta[]

src/examples.json

@@ -17,7 +17,7 @@
     "tags": ["animation", "skinning", "instancing", "gltf", "tsl", "post-processing", "leva"],
     "original": "https://threejs.org/examples/#webgpu_skinning_instancing",
     "credits": "Michelle model from the three.js examples",
-    "ciSkip": "SwiftShader readiness stall — fits the Grid+custom-node-graph pattern (see HANDOFF: grid-only passes, nodes-only passes, both hang pipeline compile silently)"
+    "ciNoGrid": "SwiftShader stall when Grid + custom node graph coexist (see HANDOFF); grid suppressed via ?nogrid in CI so the example itself still smoke-tests"
   },
   {
     "slug": "postprocessing-bloom-emissive",
@@ -39,7 +39,7 @@
     "tags": ["tsl", "render-to-texture", "post-processing", "pointer"],
     "original": "https://threejs.org/examples/#webgpu_rtt",
     "credits": "uv_grid_opengl texture from the three.js examples",
-    "ciSkip": "SwiftShader readiness stall, zero page errors (2x180s); passes on Metal. Fits the Grid+custom-node-graph pattern (see HANDOFF)"
+    "ciNoGrid": "SwiftShader stall when Grid + custom node graph coexist (see HANDOFF); grid suppressed via ?nogrid in CI so the example itself still smoke-tests"
   },
   {
     "slug": "shadow-contact",
@@ -53,7 +53,7 @@
     "tags": ["tsl", "node-material", "gltf", "leva"],
     "original": "https://threejs.org/examples/#webgpu_tsl_halftone",
     "credits": "Michelle model from the three.js examples",
-    "ciSkip": "SwiftShader readiness stall, zero page errors (2x180s); passes on Metal. Fits the Grid+custom-node-graph pattern (see HANDOFF)"
+    "ciNoGrid": "SwiftShader stall when Grid + custom node graph coexist (see HANDOFF); grid suppressed via ?nogrid in CI so the example itself still smoke-tests"
   },
   {
     "slug": "sprites",

src/utils/DemoHelpers.tsx

@@ -21,6 +21,13 @@ export interface DemoHelpersProps {
   pan?: boolean
 }
 
+// Test-only escape hatch: `?nogrid` suppresses the grid regardless of props. CI uses
+// it for examples hitting the SwiftShader stall (Grid + custom node graph hangs
+// pipeline compile on software Vulkan — see docs/HANDOFF.md); also the bisection
+// probe for that bug. Read once at module load; not part of the component API.
+const NOGRID_OVERRIDE =
+  typeof window !== 'undefined' && new URLSearchParams(window.location.search).has('nogrid')
+
 export function DemoHelpers({
   grid = true,
   controls = true,
@@ -31,7 +38,7 @@ export function DemoHelpers({
 }: DemoHelpersProps) {
   return (
     <>
-      {grid && (
+      {grid && !NOGRID_OVERRIDE && (
         <Grid
           position={[0, 0.002, 0]}
           infiniteGrid

tests/smoke.spec.ts

@@ -13,6 +13,9 @@ const IGNORED_CONSOLE = [
 
 for (const { slug, ...meta } of examples) {
   const ciSkip = 'ciSkip' in meta ? String(meta.ciSkip) : undefined
+  // ciNoGrid: run the example in CI with DemoHelpers' grid suppressed (?nogrid) —
+  // works around the SwiftShader Grid+node-graph stall WITHOUT losing smoke coverage.
+  const ciNoGrid = 'ciNoGrid' in meta ? String(meta.ciNoGrid) : undefined
   test(`${slug}: WebGPU context, readiness signal, non-black canvas`, async ({ page }) => {
     // Exception list (SPEC §10, three.js-CI prior art): examples too heavy for
     // SwiftShader declare ciSkip WITH A REASON in the manifest. They still run locally.
@@ -26,7 +29,7 @@ for (const { slug, ...meta } of examples) {
       errors.push(`console.error: ${text}`)
     })
 
-    await page.goto(`/examples/${slug}`)
+    await page.goto(`/examples/${slug}${process.env.CI && ciNoGrid ? '?nogrid' : ''}`)
 
     // Readiness = loaders settled + clean frames (window.__exampleReady, set by
     // <ReadinessSignal> inside DemoHelpers). Poll instead of sleeping. CI gets a