p5.js prototypes

A p5.js run in this lab is a folder of source that a browser opens, not a chat artifact that scrolls away. lab_new writes it, lab_lint judges it, the tab shows it, and it stays on disk where you can change it and look again.

The shape of a run

lab/p5js/<slug>/
  sketch.js     the prototype: setup(), draw(), and the algorithm's state
  index.html    the shell: the library, the seed, the controls. GENERATED.
  p5.min.js     p5.js, vendored so the run is offline. GENERATED.
  README.md     what it is and how to run it. GENERATED.
  NOTES.md      the seed, what to look at, what to try. GENERATED.

Edit sketch.js. Add a parameter by adding an entry to the params array in index.html AND reading it in sketch.js — the control is generated from that array, so there is no second place to keep in step.

The contract: one object

The shell puts everything the sketch needs on window.__dshProtoLab__:

window.__dshProtoLab__.seed          // an integer; the same seed draws the same picture
window.__dshProtoLab__.params        // [{ name, min, max, value, step }, ...]
window.__dshProtoLab__.param('name') // the ONLY way a sketch should read a tunable
window.__dshProtoLab__.drew = true   // set at the end of the first draw() - see below

Seed yourself before anything is drawn — this snippet is executed by the package's own check against a stub p5, so it is a shape that runs:

// The shell creates both holders before this factory runs.
const spec = window.__dshProtoLab__;

window.__dshProtoLabLifecycle__.setup = function () {
  randomSeed(spec.seed);
  noiseSeed(spec.seed);
  createCanvas(windowWidth, windowHeight).parent('lab-stage');
  background(0);
};

let first = true;
window.__dshProtoLabLifecycle__.draw = function () {
  // ... the algorithm ...
  if (first) { spec.drew = true; first = false; }
};

Why the lifecycle goes into a holder instead of onto window. p5's own auto-start watches window.setup and window.draw and constructs its OWN instance the moment either appears — so a sketch that installs them on window races the framework for its own lifecycle, and p5's instance wins. The shell hands the two functions to its own new p5({ setup, draw }) instead, and the sketch never touches those two names. lab_new writes this shape for you.

Three things follow from that contract, and all three are checked:

• randomSeed and noiseSeed are not optional. Without them the run is not reproducible, lab_lint reports unseeded, and "same seed, same picture" stops being true — which is the only reason a seed exists.
• window.__dshProtoLab__.drew = true at the end of the first draw() is how the shell and the headless render check tell a drawn frame from a canvas that stayed black because setup() threw.
• Read tunables through window.__dshProtoLab__.param(name), never by copying a number into a second variable at load time: the slider has to change the algorithm.

Derive the algorithm; do not pick a pattern

The order that produces something worth keeping:

1. The concept — one sentence, and it is about the process, not the image: "seeds drift along a noisy vector field and die of old age, so density accumulates where the field slows them". lab_new concept="...".
2. The derivation — what quantities does that sentence name? particles, a field, a lifetime, a respawn rule. Those become state and parameters.
3. The seed's job — say what varies with it (initial population, respawn positions, the noise offset), because that is what makes a seed worth scrubbing rather than a randomisation button.
4. The code — and only then choose the p5 calls that express the derivation.

What separates a prototype from a doodle is not the number of features. It is that the picture is a consequence of a rule you can state, and that changing one number shows you the rule working. If you cannot say which parameter would change the picture and how, the algorithm is not finished.

The rules that matter in a browser

• The frame is a budget. 60 fps is ~16 ms for everything in draw(). A few thousand particles with one line() each is fine; a nested loop over every pixel is not. When something is expensive, say so in NOTES.md and give it a parameter that turns it down.
• Recompute per frame, store per particle. The field is a function of position (noise(x * scale, y * scale, t)); never cache it into a grid unless you also make rebuilding it cheap.
• A veil beats a clear for anything that moves. fill(0, 8); rect(0, 0, w, h) in draw() accumulates paths into density; background(0) throws the history away.
• windowResized() — the canvas is the window, so resize and rebuild, rather than letting the browser stretch the canvas.
• Offline means offline. No CDN <script>, no remote image, no font URL. The library is already beside the run; if you need another file, put it in the folder. lab_lint reports remote-asset as an error.
• The preview is one composed page. It inlines the library and sketch.js and permits no network at all, so a loadImage('data/x.png') will work when index.html is opened in a browser and will NOT work in the Lab tab (lab_lint warns loads-a-file). Do not design around the preview — design the run, and open the file when you need assets.

Workflow

lab_new   runtime=p5js concept="..." params=[{name:"particles",min:200,max:6000,value:1800,step:50}]
lab_read  run=p5js/<slug> file=sketch.js
          ... edit sketch.js ...
lab_lint  run=p5js/<slug>

Then look at it: the Lab tab in the right bar, or the run's own index.html in a browser. ?seed=42 (and any parameter, ?seed=42&particles=900) explores the space without touching the file.

Aim your effort where it shows: get one gesture right — the field, the palette, the respawn rule — rather than four half-tuned ones. Then write down in NOTES.md what you saw and what you would try next, because that is the file the next person (or the next you) reads first.

Examples that ship with this skill

Two complete, seed-reproducible runs sit in examples/ beside this file; read them as reference, and instantiate one to work on it:

lab_new action=example runtime=p5js example=flow-field
lab_new action=example runtime=p5js example=attractor-nodes

example	concept	seed
flow-field	particles carried by layered noise, fading trails accumulating where the field slows	20260401
attractor-nodes	a population pulled toward moving attractors, its traces mapping the basins between them	20260402

Both are checked: every example is rendered headlessly by this package's own check, and a different seed must produce a different picture.