GPU programs and connected surfaces — preview version 7

This is the common compute layer for grid and mesh calculations. It is not a
built-in general FEM, FDTD, fluid or soft-body solver. Verified example algorithms
are separate from the infrastructure. Check getGPUCapabilities().typedPrograms
and runtimeWGSL on the loaded WebGPU player before use.

createGPUProgram(name, buffers)
Create paused named GPU state. Each buffer has name, type (f32 or u32), count,
components (default 1), optional initial values (f32) or integers (u32), and units.
Initial arrays contain exactly count*components scalars; omitted arrays start zero.
Arrays in WGSL are SCALARS: xyz for item i is at offsets 3*i, 3*i+1, 3*i+2.
Grid metadata: nx,ny,nz (product <= count), positive spacing {x,y,z}, spatialOffset
in grid-cell units, timeOffset in timestep units. These describe staggering;
the engine does not invent interpolation or implement equations from metadata.
Use 1..24 buffers, at most four programs and 128 MiB total typed-buffer storage;
combined old/new GPU storage is limited to 512 MiB. Device limits also apply.
Commands are limited to 2 MB JSON; use initialization kernels for large arrays.

compileGPUProgram(name, passes)
Each pass has name, count (number of invocations), bindings and source.
Each binding has name (WGSL identifier), buffer (the stored buffer name), access
('read', 'write' or u32-only 'atomic'). A buffer may appear only once in a pass. At most 8 storage
bindings per pass (or the lower device limit), 32 passes, 120000 source characters.
Provide fn update(i:u32). The engine adds main and workgroup_size(64), bounds the
invocations to count, supplies bindings and this uniform:
struct Params { count:u32, dt:f32, time:f32, step:u32 };
params is at binding 0. Storage bindings follow in their declared order.
WGSL binding type is array<f32> or array<u32> with scalar stride 4 bytes.
Write bindings are read_write in WGSL, allowing a thread to update its OWN item.
Never read another thread's changing item. Separate old/new buffers or pass stages
are required for neighbor dependencies. Duplicate aliases are rejected; the
platform does not prove arbitrary user WGSL race-free or scientifically correct.
Passes execute in declared order on one GPU queue. No implicit full-buffer copies.
Every pass sees the same dt,time,step for a simulation step. All stages compile
before replacing the old program. Failure retains the entire previous program.
Small beam examples use single-thread dot reductions; this is NOT a scalable
reduction implementation for large meshes. Add hierarchical reductions as needed.

stepGPUProgram(name, dt, steps=1)
Run 1..256 steps while paused and wait for submitted GPU work. dt must be positive
and <= .1. Solver-specific stability bounds are the caller's responsibility.
For a static iterative solver, steps are iterations and reported time is only a
numerical counter, not physical elapsed time.
runGPUProgram(name, dt, speed=1, maxSteps=16)
pauseGPUProgram(name)
Fixed dt, playback speed >0 and <=10, at most 1..256 steps per frame. Overload
skips wall-clock catch-up, never increases dt or skips simulated states.
getGPUProgramState(name)
Reports time, steps, running, dt, speed, maxSteps, skippedWallSeconds, bytes and
bufferCount. Physical time may run slower than requested playback under load.
measureGPUBuffer(name, buffer, offset=0, count=1)
Read 1..1024 scalar entries asynchronously; returns values or integers.
Only one probe at a time per program. Keep probes sparse; no frame-sized readback.
removeGPUProgram(name)
Disposes the program and its rendering. clearRun/clearCode clear all programs
through the existing GPU lifecycle. Reset by removing and recreating from a recipe;
exact resume snapshots are not yet implemented.

showGPUSurface(name, positions, triangles, field, vertices, triangleCount, options)
Buffers: positions=f32 xyz; triangles=u32 three vertex indices; field=f32 scalar
per vertex. Supply valid initial triangle indices and preserve them in kernels.
options: min=-1,max=1,extent=100,grid=true. Fixed color range maps blue->white->red;
add an explicit legend with quantity and units to the activity UI. No auto-scaling.
extent is a fixed bounding-box half-size around the world origin, not a collider.
The renderer reads the shared buffers directly. Mesh edge overlay shows surface
triangles, not automatically the solver's volume elements. Lighting is a fixed
scientific display light; no shadows, textures or PhysX deforming MeshCollider.
Use the existing MainCamera. Display colors do not change physics.

Examples and validation
activities/beam-bending.js: 1D Euler-Bernoulli beam elements, static linear elastic
solve using preconditioned conjugate gradients. A rectangular surface follows the
nodal displacement and slope; axial bending stress is computed from curvature.
This is a small-deflection BEAM model, not a general tetrahedral soft-body solver.
Default L=4 m, section .3 x .4 m, E=20 MPa, tip load=-100 N. Expected tip=-.0666667 m,
root surface stress +/-50000 Pa. Normal stress sign: positive tension.
activities/fdtd-waves.js: periodic 2D Yee TEz update, normalized epsilon=mu=1.
Electric field at integer time; magnetic fields start at -dt/2 with staggered
positions. Known standing Fourier mode validates the update and dispersion.
Not yet physical SI material input, PML, absorption, or an open-space pulse lesson.
These are separate activities and must not overwrite Lens Optics Test.

Native tests: Assets/Editor/CSGPUProgramTests.cs runs actual GPU kernels via the
JSON command boundary and checks analytical beam/eigenmode wave results. Browser
WGSL needs its own actual-device checks; native HLSL success is not proof of parity.

Version7 fluid tools: see FLUIDS.txt. Atomic bindings expose array<atomic<u32>>; no floating point atomics. showGPUSurface style="glass" is display only; solver supplies collision. showGPUFluid connects xyz f32 positions to a screen-space water renderer.

Version8: showGPUFluid adds adjustable narrow-range depth smoothing, thickness
filtering, tint, roughness, IOR and refraction controls. Read FLUIDS.txt.

Version10: fluidAnisotropy; showGPUFluid anisotropy:true reconstructs local sheets
and streams from GPU particle neighborhoods. See FLUIDS.txt.

Version11: fluidOptics; particleVolume normalizes optical thickness. Snell refraction, dielectric Fresnel and GGX highlights. See FLUIDS.txt for limits and the continuous Pouring Water example.