# Fluid sandbox ## What this builds A full-screen fluid you smear with the pointer. Ink (dye) is advected by a velocity field, stepped by a stable solver at a fixed timestep. A scripted stroke, on a deterministic field, produces a golden frame. Basic checks cover bounds and a divergence or residual bound. This is an original sandbox, not a copy of a famous demo's look. Read `spekkr.inputs.json` first. `title` is a corner label. `viscosity` is the diffusion amount. `resolution` sizes the grid. `dye` and `bounds` change what is drawn and how the edges behave. ## Out of scope - A physically certified CFD code. - Network or a gallery of other people's strokes in the checks. - A 3D volume in this version. ## Requirements Each requirement has an id. Checks name the id they cover. ### R1. The solver - A fixed timestep of 1/60 s. The chosen resolution is a square grid. - With `bounds` on, velocity at the edge cells is 0. With `bounds` off, the field wraps. - After 30 steps of a rest field (no stroke), the L2 of velocity is under 1e-6. After a scripted stroke, no cell is NaN or infinite, and dye stays in [0, 1] per channel. Accept when: the rest residual, the bounds, the dye range, and the NaN check all pass at 128 and 256. ### R2. A scripted stroke - `fixtures/fluid-stroke.json` is a list of pointer samples (x, y, force, colour) at listed ticks. - At tick 40 the dye field, rendered, matches `stroke-mid`. At tick 180 it matches `stroke-settled`, both at viscosity 0.8, 256, bounds on, seed 0. - A second splat fixture produces `splat-two` at tick 90. Accept when: the two tapes match the goldens within the tolerance, and a second run of each hashes the same dye checksum. ### R3. Files - One command runs the field checks and the tapes, and writes the four screenshots including `clear`. No network. Tests may run the solver on the CPU if a GPU is missing, as long as the checksums match. Accept when: the command passes at 128 and 256. ### R4. Inputs - The build reads `spekkr.inputs.json`. Settings label the UI, options turn features on or off, and a swap must be one of its choices. - A value outside a stated range, or a swap that is not one of its choices, is refused before the app starts its checks, with a message that names the key. Accept when: the default inputs render, an illegal swap is refused by name, and changing a visible setting (for example the title) shows up in a later check. ## Verification A scripted stroke on a deterministic solver produces a golden frame and a dye checksum. Rest-state residual, closed bounds, dye range, and a no-NaN check are tested. A CPU reference is preferred in CI. No network. ## Definition of done - Every acceptance check above runs from one command, and all pass at the person's inputs. - A README says how to smear ink, how to run the checks, and how to fall back to a CPU solver.