@vibes.diy/prompts 14.1.20 → 14.1.22

package/llms/p5.md

@@ -0,0 +1,714 @@
+# p5.js API
+
+_Instance mode, the pinned import, determinism, and the drawing surface for generative sketches_
+
+Any request for generative art, a flow field, a particle field, a screensaver, a
+visualiser, a doodle pad, a drawing toy, a kaleidoscope, a plotter-style pattern
+or "a sketch" is a p5.js app: one canvas created by a p5 **instance**, driven by
+a `setup`/`draw` pair, mounted from a single `React.useEffect(() => {…}, [])`
+and torn down with `instance.remove()` on unmount. p5 gives you a canvas, a
+frame loop, Perlin noise and a seeded random generator for free.
+
+The whole model of p5 is two functions: `setup` runs once, `draw` runs about
+sixty times a second, forever. A still picture is a loop that draws the same
+thing every frame; an animation is a loop where something changed.
+
+## Complete starter — the shell every p5 vibe begins from
+
+This is a full, runnable `App.jsx`. Start here and grow it: the sketch is a
+factory function that receives the host element, the instance is built once in
+one `useEffect([])`, the canvas is sized from the host, and the cleanup removes
+the instance so remounts do not leak a second draw loop.
+
+App.jsx
+
+```jsx
+import React from "react";
+import p5 from "https://esm.sh/p5@1.11.13";
+
+const TAU = Math.PI * 2;
+
+// Canvas pixels cannot follow a CSS variable, so resolve the injected theme
+// tokens to concrete colors once per mount. Setting `color` on a throwaway
+// element and reading it back returns a resolved `rgb(...)` string even when the
+// token's value is a `color-mix()` or another `var()`, and the second argument
+// is the fallback for an app with no theme injected.
+function cssColor(host, token, fallback) {
+  const probe = document.createElement("span");
+  probe.style.display = "none";
+  probe.style.color = `var(${token}, ${fallback})`;
+  host.appendChild(probe);
+  const resolved = window.getComputedStyle(probe).color;
+  probe.remove();
+  return resolved || fallback;
+}
+
+// The sketch is a pure function of its parameters and its host element. Pass the
+// host in explicitly — never read p5's private `_userNode` to find it.
+function makeSketch({ params, host, stepsRef }) {
+  return (p) => {
+    let particles = [];
+    let palette = null;
+    let steps = 0;
+    let w = 0;
+    let h = 0;
+    let t = 0;
+
+    // Read the theme tokens into p5 colors. Called at setup AND whenever the
+    // page's CSS variables change under a live restyle.
+    const readPalette = () => {
+      const bg = p.color(cssColor(host, "--background", "#040a18"));
+      const ink = p.color(cssColor(host, "--accent", "#00e5ff"));
+      const fade = p.color(cssColor(host, "--background", "#040a18"));
+      fade.setAlpha(10);
+      ink.setAlpha(85);
+      palette = { bg, ink, fade };
+    };
+
+    // The step count lives inside this closure, and the Keep button lives in
+    // React — so publish it outward on every step. `p` exists ONLY here.
+    const publishSteps = () => {
+      if (stepsRef) stepsRef.current = steps;
+    };
+
+    const spawn = () => {
+      particles = [];
+      for (let i = 0; i < params.count; i++) {
+        const x = p.random(w);
+        const y = p.random(h);
+        particles.push({ x, y, px: x, py: y });
+      }
+    };
+
+    const advance = () => {
+      steps += 1;
+      t += params.speed * 0.0016;
+      for (const q of particles) {
+        const a = p.noise(q.x * params.grain, q.y * params.grain, t) * TAU * 2;
+        q.px = q.x;
+        q.py = q.y;
+        q.x += Math.cos(a) * params.speed;
+        q.y += Math.sin(a) * params.speed;
+        p.line(q.px, q.py, q.x, q.y);
+        if (q.x < -20 || q.x > w + 20 || q.y < -20 || q.y > h + 20) {
+          q.x = p.random(w);
+          q.y = p.random(h);
+          q.px = q.x;
+          q.py = q.y;
+        }
+      }
+    };
+
+    p.setup = () => {
+      w = Math.max(120, host.clientWidth || 320);
+      h = Math.max(120, host.clientHeight || 240);
+      const c = p.createCanvas(w, h);
+      if (c && c.elt) c.elt.style.display = "block";
+      p.pixelDensity(Math.min(window.devicePixelRatio || 1, 2));
+      p.randomSeed(params.seed);
+      p.noiseSeed(params.seed);
+
+      readPalette();
+      p.stroke(palette.ink);
+      p.strokeWeight(1);
+      p.background(palette.bg);
+      spawn();
+      publishSteps();
+    };
+
+    // ONE frame of the piece: the fade is part of the frame, not decoration
+    // around it, so the still render below replays this and not just advance().
+    const step = () => {
+      // Trails: dim what is already there instead of erasing it.
+      p.noStroke();
+      p.fill(palette.fade);
+      p.rect(0, 0, w, h);
+      p.stroke(palette.ink);
+      advance();
+    };
+
+    p.draw = () => {
+      step();
+      publishSteps();
+    };
+
+    // A live restyle swaps the page's CSS variables in place; the canvas is
+    // painted, so it has to be told. Called by the observer in App below.
+    p.retheme = () => {
+      if (palette === null) return;
+      readPalette();
+      p.stroke(palette.ink);
+      p.background(palette.bg);
+    };
+
+    p.mouseDragged = () => {
+      particles.push({ x: p.mouseX, y: p.mouseY, px: p.mouseX, py: p.mouseY });
+    };
+
+    p.touchMoved = () => {
+      particles.push({ x: p.mouseX, y: p.mouseY, px: p.mouseX, py: p.mouseY });
+      return false; // stop the browser scrolling the page under the finger
+    };
+
+    p.windowResized = () => {
+      w = Math.max(120, host.clientWidth);
+      h = Math.max(120, host.clientHeight);
+      p.resizeCanvas(w, h);
+      p.background(palette.bg);
+      spawn();
+    };
+  };
+}
+
+export default function App() {
+  const hostRef = React.useRef(null);
+  const stepsRef = React.useRef(0);
+  const [params, setParams] = React.useState({
+    count: 1200,
+    grain: 0.0022,
+    speed: 1.6,
+    seed: 1234,
+  });
+  const key = JSON.stringify(params);
+
+  React.useEffect(() => {
+    const node = hostRef.current;
+    if (!node) return undefined;
+    const instance = new p5(makeSketch({ params, host: node, stepsRef }), node);
+
+    // The Style tab recolors a running app by swapping the CSS variables with
+    // no remount, which every styled element follows and the canvas cannot.
+    // Watching the document's stylesheets is what makes the sketch follow too.
+    const observer = new MutationObserver(() => instance.retheme());
+    observer.observe(document.head, { childList: true, subtree: true, characterData: true });
+
+    return () => {
+      observer.disconnect();
+      instance.remove();
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key]);
+
+  return (
+    <div className="min-h-screen bg-[var(--background)] text-[var(--text-primary)] p-4">
+      <div
+        ref={hostRef}
+        className="w-full h-[70vh] overflow-hidden rounded-[var(--radius)] border border-[var(--border)]"
+        style={{ touchAction: "none" }}
+      />
+      <button
+        className="mt-3 rounded-full border border-[var(--border)] px-4 py-2 text-sm"
+        onClick={() => setParams((prev) => ({ ...prev, seed: Math.floor(Math.random() * 100000) }))}
+      >
+        Reseed
+      </button>
+    </div>
+  );
+}
+```
+
+Everything below grows that shell. The lifecycle above — one instance, one
+`useEffect`, `remove()` on cleanup — stays the spine of every p5 vibe.
+
+## Instance mode is how p5 runs in a vibe
+
+Every p5 tutorial on the internet opens with a global `function setup()`. That
+works when the sketch owns the whole page. In a vibe React owns the page, and
+the sketch is a component that mounts, unmounts, and mounts again every time an
+input changes — so the sketch must be an **instance**.
+
+**Create the instance inside one `React.useEffect` and return `() => instance.remove()` from it.**
+Without the cleanup, every change to the sketch's inputs mounts a fresh instance
+beside the old one and the old one keeps running: two draw loops, then four, a
+leaked canvas per change, and a sketch that gets mysteriously slower and
+blurrier every time a slider moves.
+
+**Assign every lifecycle hook on the instance** — `p.setup`, `p.draw`,
+`p.windowResized`, `p.mouseDragged` — rather than declaring them as globals.
+The instance is the only handle the sketch has, so everything it draws with goes
+through `p`: `p.noise`, `p.random`, `p.line`, `p.fill`.
+
+**Pass the host element into the sketch factory explicitly.** `new p5(sketch, host)`
+draws into that element instead of appending a canvas to the body, which is what
+keeps the layout React's and the pixels p5's. p5 also stashes the node on the
+instance, but that property is private — hand the node to your factory as an
+argument instead of reading `_userNode` back off `p`.
+
+```jsx
+const hostRef = React.useRef(null);
+
+React.useEffect(() => {
+  const node = hostRef.current;
+  if (!node) return undefined;
+  const instance = new p5(makeSketch({ params, host: node }), node);
+  return () => instance.remove();
+}, [key]);
+
+return <div ref={hostRef} className="w-full h-full" style={{ touchAction: "none" }} />;
+```
+
+Because the effect re-runs on a changed `key`, a parameter change is a clean
+swap: the old instance is removed, a new one is built, and the sketch stays a
+pure function of its parameters.
+
+## Importing p5
+
+**Import p5 from a version-pinned esm.sh URL: `import p5 from "https://esm.sh/p5@1.11.13"`.**
+A bare `"p5"` resolves to the 2.x line, which pulls a much heavier module graph
+(acorn, escodegen) into the sandbox for an API this doc never uses.
+
+Pinning is a correctness property here, not caution. For generative art a
+library bump can change what a piece *looks like* — a tweak to `noise()`, a
+different default `pixelDensity` — and a saved piece is a handful of numbers
+that assume the renderer they were saved on. Pin the version the way you would
+date a print.
+
+## Sizing the canvas
+
+Size from the host element, never from `window.innerWidth`: the sketch lives in
+a box React laid out, and the box is rarely the whole window.
+
+```js
+p.setup = () => {
+  w = Math.max(120, host.clientWidth || 320);
+  h = Math.max(120, host.clientHeight || 240);
+  p.createCanvas(w, h);
+};
+
+p.windowResized = () => {
+  w = Math.max(120, host.clientWidth);
+  h = Math.max(120, host.clientHeight);
+  p.resizeCanvas(w, h);
+};
+```
+
+`p.resizeCanvas` clears the canvas, so a trails sketch repaints its background
+and respawns its particles after a resize rather than resuming into an empty
+frame.
+
+**Cap pixel density at 2 for a live canvas and set `p.pixelDensity(1)` for thumbnails.**
+On a retina screen the cost of a frame is fill rate, not JavaScript, and a
+gallery of small cards at device density is the fastest way to make a page
+stutter.
+
+## Colour comes from the injected theme tokens
+
+The platform injects this app's colours as CSS variables — `--background`,
+`--surface`, `--primary`, `--secondary`, `--accent`, `--text-primary`,
+`--text-secondary`, `--border` — and the owner restyles the whole app by swapping
+those values. Everything outside the canvas reads them through Tailwind bracket
+notation (`bg-[var(--background)]`), but **canvas pixels cannot follow a CSS
+variable**, so a sketch that inlines `"#00e5ff"` is the one part of a themed vibe
+its owner can never restyle.
+
+**Resolve the theme tokens to concrete colours at setup, and use a literal only
+as the fallback when no theme is injected.** Reading the custom property
+straight off the host with `getComputedStyle(host).getPropertyValue("--accent")`
+is enough when the token holds a plain colour, but a token whose value is a
+`color-mix()` or another `var()` comes back unresolved and p5 cannot parse it.
+Letting the browser resolve it works for every value:
+
+```js
+function cssColor(host, token, fallback) {
+  const probe = document.createElement("span");
+  probe.style.display = "none";
+  probe.style.color = `var(${token}, ${fallback})`;
+  host.appendChild(probe);
+  const resolved = window.getComputedStyle(probe).color;
+  probe.remove();
+  return resolved || fallback;
+}
+
+p.setup = () => {
+  p.createCanvas(w, h);
+  const ink = p.color(cssColor(host, "--accent", "#00e5ff"));
+  ink.setAlpha(85); // p5 owns the alpha; the token owns the hue
+  p.stroke(ink);
+  p.background(p.color(cssColor(host, "--background", "#040a18")));
+};
+```
+
+Read the tokens **inside `setup`**, not at module scope, so a rebuilt instance
+picks up the current theme. Keep alpha in p5's hands with `setAlpha`: appending
+`"55"` to a token works only if the token happened to be a six-digit hex, and a
+resolved `rgb(...)` string it silently corrupts.
+
+**Reading at setup is not enough on its own, because a restyle does not rebuild
+the sketch.** The Style tab recolors a running app by swapping the page's CSS
+variables in place — it replaces the contents of a `<style>` element in the
+document head, with no remount — so every styled element re-renders through the
+cascade and the canvas, which is painted rather than styled, keeps the colours it
+resolved at setup until something unrelated happens to rebuild it. Watch the
+document's stylesheets and repaint:
+
+```jsx
+// in the sketch: re-read and repaint on demand
+p.retheme = () => {
+  if (palette === null) return; // setup has not run yet
+  readPalette();
+  p.stroke(palette.ink);
+  p.background(palette.bg);
+};
+
+// in the component: same effect that built the instance, same cleanup
+const instance = new p5(makeSketch({ params, host: node }), node);
+const observer = new MutationObserver(() => instance.retheme());
+observer.observe(document.head, { childList: true, subtree: true, characterData: true });
+return () => {
+  observer.disconnect();
+  instance.remove();
+};
+```
+
+`characterData` and `subtree` are both needed: a first push APPENDS the style
+element, and every push after it rewrites the text of the one already there. The
+observer belongs to the effect that built the instance, so it is disconnected in
+the same cleanup that removes it — an observer outliving its sketch is the same
+leak as a draw loop outliving its canvas.
+
+## Determinism — a picture is a handful of numbers
+
+**Call `p.randomSeed(seed)` and `p.noiseSeed(seed)` in `setup` so the sketch replays from its numbers instead of from its pixels.**
+Seed both generators and the simulation becomes reproducible: the same seed
+gives the same starting positions, the same wind, the same drift.
+
+This is the single most useful p5 idea for a vibe with a database. A saved piece
+is not a PNG — it is its parameters, its seed and **how far the simulation had
+run**, a few dozen bytes, and a fresh instance cooks that recipe again as many
+times as you like. So persist the numbers, not the pixels:
+
+`steps` is as load-bearing as `seed` — an animated sketch looks different at step
+100 and step 10,000 — and it is the number that is hardest to get at, because
+**`p` exists only inside the sketch factory and the Keep button lives in React**.
+Reaching for `p.frameCount` from a click handler is a `ReferenceError`. The
+sketch has to publish the count outward; a ref is the smallest way:
+
+```jsx
+// in the component
+const stepsRef = React.useRef(0);
+const { database, useLiveQuery } = useFireproof("pieces");
+
+React.useEffect(() => {
+  const instance = new p5(makeSketch({ params, host: node, stepsRef }), node);
+  return () => instance.remove();
+}, [key]);
+
+// in the sketch factory — `stepsRef` is an argument, so the closure can write it.
+// ONE counter with ONE owner: `advance()` is the only thing that increments it,
+// because it is the only thing that moves the simulation. Everything else reads.
+let steps = 0;
+const advance = () => {
+  steps += 1;
+  // …move every particle, draw its segment…
+};
+
+p.draw = () => {
+  step(); // calls advance() exactly once
+  if (stepsRef) stepsRef.current = steps;
+};
+
+// in the Keep handler — no `p` in sight
+async function keep() {
+  await database.put({ ...params, type: "piece", steps: stepsRef.current, created: Date.now() });
+}
+
+const { docs } = useLiveQuery("created", { descending: true, limit: 12 });
+```
+
+Keep the counter to one owner. It counts calls to `advance()`, so incrementing it
+anywhere else — in `draw`, in `step`, beside the publish — counts the same frame
+twice, and a card then replays twice the frames that were on screen when Keep was
+pressed, which is the exact error persisting `steps` exists to prevent.
+
+A card then renders exactly `doc.steps` steps (see the still-render pattern
+below), so the wall shows the piece at the moment it was kept rather than at
+whatever frame the card happened to reach. Loading somebody else's piece hands
+the reader a live sketch with their parameters in it, so nudging one number is a
+variation rather than a copy.
+
+Two honest limits, and say them in the app's own copy rather than promising more
+than it does:
+
+- **Hand-drawn input is not in the numbers.** If a person can drag on the canvas
+  to push ink into it, what they drew is unbounded input that no seed replays. A
+  kept piece is a canonical render of the recipe, not a snapshot of the canvas at
+  the moment of keeping — the recipe is exact, the print is fresh. An app that
+  needs the literal pixels is asking for an image, so capture one
+  (`p.saveCanvas`, or the canvas's own `toBlob`) and store that instead.
+- **The numbers fix the simulation, not the screen.** A canvas of a different
+  size or pixel density starts the particles in proportionally different places,
+  the way the same negative prints differently at different sizes.
+
+`Math.random()` is NOT covered by `randomSeed` — use `p.random()` everywhere
+inside a sketch that means to be reproducible, and `p.noise()` rather than any
+hand-rolled noise.
+
+## Still renders — a thumbnail is a loop you ran to completion
+
+To draw a gallery card, run the simulation inside `setup` for the stored number
+of steps and then stop the loop. Same sketch factory, one flag — and `steps`
+comes off the saved piece (`doc.steps`), which is what makes the card the piece
+its author kept:
+
+```js
+// ONE frame of the piece, called by both paths. The fade is part of a frame:
+// a still loop that calls only `advance()` accumulates different stroke opacity
+// than the live canvas did, so the card would not be the piece at identical
+// seed, parameters, size and step count.
+const step = () => {
+  p.noStroke();
+  p.fill(palette.fade);
+  p.rect(0, 0, w, h);
+  p.stroke(palette.ink);
+  advance();
+};
+
+p.setup = () => {
+  p.createCanvas(w, h);
+  p.pixelDensity(still ? 1 : Math.min(window.devicePixelRatio || 1, 2));
+  p.randomSeed(params.seed);
+  p.noiseSeed(params.seed);
+  readPalette();
+  p.background(palette.bg);
+  spawn();
+  if (still) {
+    for (let i = 0; i < steps; i++) step(); // the SAME step, not advance()
+    p.noLoop();
+  }
+};
+
+p.draw = () => {
+  if (still) return;
+  step();
+};
+```
+
+Whatever a live frame does — the fade, the stroke colour, a per-frame drift — the
+still path has to do too, or the card is a different picture from the one its
+author kept. `p.noLoop()` stops `draw` from being scheduled; `p.loop()` starts it again, and
+`p.redraw()` runs one frame on demand. A wall of stills is cheap because none
+of them are animating.
+
+## Performance
+
+A flow field draws thousands of segments a frame, so the per-item work is what
+decides whether it holds sixty frames a second.
+
+**Group by colour so `stroke()` changes a handful of times per frame instead of
+once per particle.** Bucket particles by palette band, sort by colour, or just
+guard the call:
+
+```js
+let cur = null;
+for (const q of particles) {
+  if (q.c !== cur) {
+    cur = q.c;
+    p.stroke(cur);
+  }
+  p.line(q.px, q.py, q.x, q.y);
+}
+```
+
+**Rotate coordinates by hand instead of `push`/`translate`/`rotate`/`pop` per
+item.** Precompute the sine and cosine of each symmetry arm once, then transform
+the two endpoints with arithmetic — the difference between one transform matrix
+and eleven thousand of them.
+
+```js
+const arms = [];
+for (let s = 0; s < symmetry; s++) {
+  const a = (TAU / symmetry) * s;
+  arms.push([Math.cos(a), Math.sin(a)]);
+}
+// per segment:
+for (const [co, si] of arms) {
+  p.line(cx + ax * co - ay * si, cy + ax * si + ay * co, cx + bx * co - by * si, cy + bx * si + by * co);
+}
+```
+
+**Use a translucent rectangle for trails instead of `background()`.** Painting a
+nearly-transparent rect over the canvas each frame dims the history a few
+percent rather than erasing it, which is most of what people mean when a sketch
+"looks generative". The alpha is the knob: lower is smokier, higher snaps back
+to dots.
+
+```js
+p.noStroke();
+p.fill(20, 20, 20, 12);
+p.rect(0, 0, width, height);
+```
+
+Other levers: keep the particle array a fixed size and recycle dead particles
+rather than allocating; keep React state out of the frame loop entirely (the
+loop mutates plain objects the sketch closed over, and React only ever sets the
+parameters); and for a field dense enough that 2D runs out of road, `WEBGL` mode
+with `p.createShader(vert, frag)` evaluates it per pixel on the GPU.
+
+## Mouse and touch
+
+p5 keeps `p.mouseX` / `p.mouseY` current and fills them from a touch too, so one
+handler usually covers both surfaces.
+
+```js
+p.mouseDragged = () => {
+  paintAt(p.mouseX, p.mouseY);
+};
+
+p.touchMoved = () => {
+  paintAt(p.mouseX, p.mouseY);
+  return false; // returning false prevents the browser's default scroll/zoom
+};
+```
+
+**Set `touchAction: "none"` on the host element** so a drag paints instead of
+scrolling the page on a phone. Returning `false` from `touchMoved` handles the
+gesture p5 sees; the CSS handles the gesture the browser would have taken first.
+
+## API surface
+
+### Canvas and lifecycle
+
+```js
+p.createCanvas(w, h); // or p.createCanvas(w, h, p.WEBGL)
+p.resizeCanvas(w, h);
+p.pixelDensity(1);
+p.noLoop();
+p.loop();
+p.redraw();
+p.frameRate(30);
+p.frameCount; // frames since setup
+p.deltaTime; // ms since the previous frame
+```
+
+### Drawing
+
+```js
+p.background("#040a18");
+p.fill(255, 120, 0, 40); // r, g, b, alpha 0-255
+p.noFill();
+p.stroke("#00e5ff55"); // 8-digit hex carries alpha
+p.noStroke();
+p.strokeWeight(1.5);
+
+p.line(x1, y1, x2, y2);
+p.circle(x, y, d);
+p.ellipse(x, y, w, h);
+p.rect(x, y, w, h, radius);
+p.triangle(x1, y1, x2, y2, x3, y3);
+p.point(x, y);
+
+p.beginShape();
+p.vertex(x, y);
+p.curveVertex(x, y);
+p.endShape(p.CLOSE);
+
+p.text("hello", x, y);
+p.textSize(16);
+p.textAlign(p.CENTER, p.CENTER);
+```
+
+### Colour
+
+```js
+p.colorMode(p.HSB, 360, 100, 100, 1);
+const c = p.color(200, 80, 90);
+p.lerpColor(a, b, 0.3);
+```
+
+### Numbers, randomness, noise
+
+```js
+p.random(max); // p.random(min, max), p.random(array)
+p.randomSeed(1234);
+p.noise(x, y, z); // 0..1 Perlin noise
+p.noiseSeed(1234);
+p.noiseDetail(octaves, falloff);
+p.map(v, inMin, inMax, outMin, outMax);
+p.constrain(v, min, max);
+p.lerp(a, b, t);
+p.dist(x1, y1, x2, y2);
+p.TWO_PI;
+p.sin(a);
+p.cos(a);
+```
+
+### Transforms
+
+```js
+p.push();
+p.translate(x, y);
+p.rotate(angle);
+p.scale(s);
+p.pop();
+```
+
+### Input
+
+```js
+p.mouseX;
+p.mouseY;
+p.pmouseX;
+p.pmouseY;
+p.mouseIsPressed;
+p.mousePressed = () => {};
+p.mouseDragged = () => {};
+p.mouseReleased = () => {};
+p.mouseWheel = (event) => {};
+p.touchStarted = () => {};
+p.touchMoved = () => false;
+p.touchEnded = () => {};
+p.keyPressed = () => {};
+p.key;
+p.keyCode;
+```
+
+### Pixels and export
+
+```js
+p.loadPixels();
+p.pixels; // flat RGBA array
+p.updatePixels();
+p.get(x, y); // one pixel
+p.createGraphics(w, h); // an offscreen buffer to draw into
+p.saveCanvas("piece", "png");
+```
+
+### WEBGL
+
+```js
+const shader = p.createShader(vertSource, fragSource);
+p.shader(shader);
+shader.setUniform("u_time", p.millis() / 1000);
+shader.setUniform("u_resolution", [w, h]);
+p.rect(-w / 2, -h / 2, w, h); // a full-canvas quad for the fragment shader
+p.box(50);
+p.sphere(40);
+p.orbitControl();
+```
+
+## Common gotchas
+
+**A global `function setup()` never runs.** In instance mode p5 only calls the
+hooks it finds on the instance, so a sketch written the tutorial way mounts a
+blank canvas and nothing reports a problem.
+
+**A missing `instance.remove()` is invisible until it is loud.** The symptom is
+a sketch that speeds up, brightens, or tears after a few parameter changes —
+that is two or four draw loops painting the same canvas.
+
+**`p.resizeCanvas` clears the drawing.** Repaint the background and reseed the
+simulation from `windowResized` rather than assuming the previous frame survived.
+
+**Do not drive the sketch from React state per frame.** A `setState` inside
+`draw` re-renders the tree sixty times a second; let the loop mutate plain
+objects and keep React for the controls.
+
+**`p.random()` is seeded; `Math.random()` is not.** Mixing them makes a sketch
+that looks reproducible until it isn't.
+
+**Colour with alpha is how trails and depth are made.** An 8-digit hex string
+(`"#00e5ff55"`) or a fourth argument to `fill`/`stroke` is usually the
+difference between a diagram and a picture.
+
+**One instance per host element.** Mounting a second p5 into the same node gives
+two canvases stacked in the same box.