summaryrefslogtreecommitdiff
path: root/examples/noc/notes/research-processing-p5.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-16 21:28:20 -0300
committerGabriel Schneider <[email protected]>2026-11-16 21:28:20 -0300
commit6933f99ddb2d7103515d26838496309a807bba26 (patch)
tree991c2fe7d4a57957222876e190fa4d16a0fb889c /examples/noc/notes/research-processing-p5.md
parent82fca5c9f29124f37f6dcd08e73e6999ce44a69d (diff)
downloadsketchbook-6933f99ddb2d7103515d26838496309a807bba26.tar.gz
sketchbook-6933f99ddb2d7103515d26838496309a807bba26.zip
Move standalone sketches into sketchbook examples
Diffstat (limited to 'examples/noc/notes/research-processing-p5.md')
-rw-r--r--examples/noc/notes/research-processing-p5.md461
1 files changed, 461 insertions, 0 deletions
diff --git a/examples/noc/notes/research-processing-p5.md b/examples/noc/notes/research-processing-p5.md
new file mode 100644
index 0000000..33a6bd3
--- /dev/null
+++ b/examples/noc/notes/research-processing-p5.md
@@ -0,0 +1,461 @@
+# Processing / p5.js → sketchbook
+
+What to take from Processing 4 and p5.js 2.4 so that sketchbook is as quick
+to iterate in, without giving up what sketchbook gets right: plain-data State,
+deterministic replayed `update`, `draw` that emits commands as data, every
+command runnable by both hosts, GPU work as data.
+
+Paths below are relative to:
+- `P/` = `~/05-genizah/processing4/core/src/processing/`
+- `p5/` = `~/05-genizah/p5.js/src/` (2.4.0-rc.2, commit 1ae94e6)
+- `sb/` = `~/00-projects/0x4200.cafe/01-drat-meout/lib/sketchbook/`
+
+**Evidence from the NoC ports.** Two port batches running now
+(`src/helpers_a.zig`, `src/helpers_b.zig`) each wrote the same helpers
+without coordinating: 60 Hz steps from tick events, PVector's
+`setMag/limit/heading/fromAngle`, `random(lo, hi)` over
+`std.Random.DefaultPrng`, Processing's `noise()`, a fixed-capacity `List`
+for State, and a "Pen" (fill/stroke/weight/transform, circle/line/polygon)
+that rasterizes a `vector.Drawing` through `vector.Renderer(.cpu|.gpu)` into
+an image every frame. That is the shopping list. Most items below exist so
+that the next port does not write these helpers a third time.
+
+---
+
+## 1. How Processing and p5 do it
+
+| Area | Processing 4 | p5.js 2.4 | sketchbook today → verdict |
+|---|---|---|---|
+| **Draw loop, frame persistence** | `handleDraw` `P/core/PApplet.java:2026-2120`: `setup()` when `frameCount==0`, latches `pmouseX` (2099), `draw()`, then `dequeueEvents()` (2112): callbacks run *after* draw. The canvas is never cleared for you. | `_draw` `p5/core/main.js:311-362`: rAF, throttled to the target fps with a 5 ms epsilon. `redraw` `p5/core/structure.js:326-365` resets **only the matrix** (342) and bumps `frameCount`. Fill/stroke set late in one frame carry into the next. Canvas persists. | Host clears to black every frame and draws again while paused or seeking (`sb/src/host/Host.zig:285-287`). **Keep.** Persistence is a trap (§3). |
+| **frameCount / deltaTime / millis / frameRate** | `frameCount` field (693); `frameRate` is an EMA (2085-2090); `millis()` is wall-clock `currentTimeMillis - offset` (2887). | `deltaTime` from rAF timestamps (`main.js:331`); `millis` `p5/utilities/time_date.js:237`; `frameRate(fps)` `p5/core/environment.js:397`. | `in.frame` is bumped in `draw` (`Host.zig:277`), so it counts redraws. **`in.dt` is not set during replay**: the playing branch of `Host.frame` (`Host.zig:229`) never writes it, and `Host.update` (243-254) does not either. `in.now` is the host clock live but recording-relative in replay (`sb/src/abi.zig:53-54`, `sb/src/host/timeline.zig:114`). So an `update` that reads `in.dt` or `in.now` replays differently. **Fix it, and add a State `Clock`** (P5). |
+| **random** | `PApplet.java:4696-4801`: a lazy `new java.util.Random()` (4707) that is unseeded unless you call `randomSeed`; `randomGaussian` → `Random.nextGaussian` (4738). `PVector.random2D()` uses `Math.random()` unless you pass the applet (`P/core/PVector.java:242-245`), so it **ignores randomSeed**. | `p5/math/random.js`: Numerical Recipes LCG (13-27), state stored per instance; **falls back to `Math.random()` until seeded** (278-282). Gaussian is Marsaglia polar with the spare value `y2` kept **module-global** (18, 360-379), so it is shared across instances. `p5.Vector.random2D` uses `Math.random` (`p5/math/p5.Vector.js:3150`). | No helpers; the ports use `std.Random.DefaultPrng` in State. **Take, as a generator stored in State with a pinned algorithm, plus stateless keyed randomness** (P3). |
+| **noise** | `PApplet.java:4845-5057`: *value* noise (not gradient noise) on a 4096-float lattice; **`abs()` on every coordinate** (4937), so `noise(-x) == noise(x)`; cosine-LUT smoothing (`noise_fsc`); 4 octaves with falloff 0.5; the table is filled lazily from an unseeded `Random`; `noiseSeed` drops the table (5053). | `p5/math/noise.js`: a straight port (header 1-13), `Math.cos` smoothing (29); **the table is module-global** (31, 268-273), shared by every p5 instance on the page; `noiseSeed` refills it from an LCG (466-505). | None. **Take, as pure functions with the seed as an argument, plus a faithful "classic" mode for ports** (P4). |
+| **Style state, push/pop** | `P/core/PStyle.java`: about 30 public fields. `pushStyle` copies all of PStyle into an array stack (`P/core/PGraphics.java:6268-6298`) and throws on underflow (6294). `push()` = `pushStyle()` + `pushMatrix()` (5273). | `p5/core/States.js:1-33`: records diffs (`setValue` remembers a key's first old value); `push` saves the diff and `pop` applies it (`p5/core/p5.Renderer.js:142-155`); **a pop on an empty stack silently uses `{}`** (151). Renderer2D also calls `ctx.save/restore` (`p5/core/p5.Renderer2D.js:877-892`). | No style. **Take, as a value (`Pen`) whose copies replace push/pop** (P2). |
+| **Matrix stack** | Java2D keeps a stack of cloned `AffineTransform`s (`P/awt/PGraphicsJava2D.java:75, 2159-2176`). OpenGL keeps 32-deep `float[16]` stacks (`P/opengl/PGraphicsOpenGL.java:302-320, 3683-3715`). | 2D uses the canvas context's transform (`resetMatrix` `p5.Renderer2D.js:834`). 3D keeps `states.uModelMatrix`, cloned on write (`p5/core/p5.Renderer3D.js:98, 787-805`). | None. **Take, as a CPU-side affine inside the Pen.** Commands stay in absolute canvas pixels. |
+| **beginShape / vertex / endShape, batching** | `beginShape` stores the kind (`PGraphics.java:1198`); `vertex` writes into `vertices[][]` (1362). OpenGL **tessellates at `endShape` with the current modelview applied on the CPU** (`PGraphicsOpenGL.java:2180-2222`), appends to `tessGeo`, and flushes only when full or when state changes (1930-1940, 2247-2280: "the modelview transformation has been applied already ... set the OpenGL modelview matrix as the identity"). A `blendMode` change forces a flush (6212-6216). Java2D builds a `GeneralPath` (`PGraphicsJava2D.java:58, 746`). | Every primitive becomes a `p5.Shape` made of primitives (`p5/shape/custom_shapes.js:687`), turned into output by visitors: `PrimitiveToPath2DConverter` (1270) for 2D, `PrimitiveToVerticesConverter` (1554) for WebGL. Renderer2D does one `ctx.fill`/`ctx.stroke` per shape (`p5.Renderer2D.js:280-301`). WebGL issues **one draw call per immediate shape** (`p5.Renderer3D.js:528-547`); only `buildGeometry` is retained. | Only `rect` fills; the ports go through the vector module. **Take Processing's model**: tessellate in shared Zig with the transform applied, batch, and emit one flat-colored triangle command (P1). p5's shape-as-data visitor is the right internal structure for `sk.Path`. |
+| **rectMode / ellipseMode** | A switch inside `rect` (`PGraphics.java:2684-2718`). | `modeAdjust` (`p5/core/helpers.js:12-60`). | **Trap as a mode.** Take it as rect constructors (P11). |
+| **colorMode / HSB / lerpColor** | `colorCalc` clamps to the mode's maxes and converts HSB→RGB inline (`PGraphics.java:7684-7735`); `colorMode` (7560-7578); `lerpColor` (8122-8134). | `colorMode` keeps per-mode maxes in renderer state (`p5/color/setting.js:1044-1065`); Color sits on colorjs spaces (`p5/color/p5.Color.js:59-101`); `lerpColor` interpolates in the current space (`p5/color/creating_reading.js:1825-1845`). | `shape.color` is duck-typed RGB only. **Take, as pure constructors and `mix(space)`. Not as a mode** (P8). |
+| **blendMode** | OpenGL flushes, then sets the blend equation per mode (`PGraphicsOpenGL.java:6212-6260`). | Sets `globalCompositeOperation` (`p5.Renderer2D.js:475-500`); SUBTRACT is WebGL-only (481). | Only alpha blending for 2D; `abi.gpu.Blend` covers passes. **Take, as a Pen field that becomes a stateful command only when it changes, limited to modes both hosts can run** (P9). |
+| **Offscreen buffers** | `createGraphics` (`P/core/PApplet.java:1764-1880`) returns a full PGraphics with its own style and matrix state. | `createGraphics` (`p5/core/rendering.js:407`), `p5.Graphics` with its own renderer (`p5/core/p5.Graphics.js:27-38`; `reset()` resets only the matrix, 232); `createFramebuffer` (`rendering.js:559`, `p5/webgl/p5.Framebuffer.js:58`). | GPU passes already draw into Images; 2D commands cannot. **Take, as a target command** (P10). |
+| **Shaders, filter, uniforms** | `loadShader` (`PGraphics.java:1945`, `PGraphicsOpenGL.java:6911`); uniforms go into a **HashMap by name**, applied at bind time (`P/opengl/PShaderOpenGL.java:742-760`); `filter(PShader)` (`PGraphicsOpenGL.java:6049`). | `loadShader` is async (`p5/webgl/material.js:130`); `setUniform` by name **silently ignores unknown names** (`p5/webgl/p5.Shader.js:1141-1150`); `modify(hooks)` patches shaders through string hooks (425); built-in filters are made with strands (`p5/core/filterShaders.js:12`). | Comptime std140 structs, glslc/naga at build time, pipelines cached by content hash. **Better already. Keep it**, and add a stock fullscreen/filter helper (P12). |
+| **Input** | `mouseX` etc. are globals (352); `pmouseX` latched once per frame (2099); callbacks are queued and dispatched after draw (2112, 2264). | Globals plus callbacks fired from DOM handlers at event time (`p5/events/keyboard.js:606-623`, `p5/events/pointer.js:1067, 1231`). | A recorded `Event` list handed to `update`. **Better already.** Add sugar (P14). |
+| **saveFrame** | `saveFrame("f-####.png")` writes synchronously and numbers by frameCount (`PApplet.java:3559-3620`). | `saveCanvas` (`p5/image/image.js:250`); `saveFrames` captures on a wall-clock `setInterval`, **capped at 15 s and 22 fps** (631-660). | `screenshot` in scripts. **Take, as a deterministic export from a recording** (P13). |
+| **PVector / map / constrain** | Mutating methods with static twins (`PVector.java`). `map`/`constrain` (`PApplet.java:4657, 4326`). | `p5.Vector`; `map(…, withinBounds)` (`p5/math/calculation.js:866`). | `@Vector(2, f32)` already has `+ - *`, and State can hold vectors (`sb/src/layout.zig:87, 125`). **Take the missing functions** (P7). |
+| **Tweak mode** | The editor replaces every literal with `tweakmode_int[i]`/`tweakmode_float[i]` (`~/05-genizah/processing4/java/src/processing/mode/java/JavaEditor.java:2140`) and injects a UDP server thread into the sketch (`.../tweak/TweakClient.java:123`). | n/a | `sb/docs/regions-in-source.md` gets the same result with no code injected (rewrite the literal, hot reload). **Keep sketchbook's design.** |
+
+---
+
+## 2. Proposals
+
+Each proposal gives: how a sketch reads, where it lives, cost on native and
+web, and the invariant it touches. "sketch lib" means `sb/src/sketch/`,
+which is compiled into the sketch and so behaves the same on both hosts.
+
+### Relation to research-love (notes/research-love-raylib.md)
+
+LÖVE, raylib and Processing's OpenGL renderer arrive at the same design: CPU
+transform, CPU tessellation, flat batches. So P1, P2, P5, P3/P4, P9 and P10
+below agree with research-love's P2, P1, P3, P4, P5 and P6. Where this
+document differs:
+- **One command per shape, as research-love has it** (`Command.shape`, no overlap *within* a shape). I drop my "union over the whole command" contract: p5 composites each shape on its own (`p5.Renderer2D.js:280-301`), so overlapping translucent circles must darken. Coalescing is a host-local optimization, and it is **safe only for opaque runs**: merging translucent shapes into one path would change the picture on the web.
+- **Blend: three 2D modes, not four.** I had `screen` through `SDL_ComposeCustomBlendMode`. It does not match Canvas2D when alpha < 1: canvas gives `a·s + d·(1 − a·s)`, while the factor pair (SRC_ALPHA, ONE_MINUS_SRC_COLOR) gives `a·s + d·(1 − s)`. Agreed: `{alpha, add, multiply}`.
+- **Use `Input.jumped`** (research-love P6) instead of my `ss.drawn != ticks` check in P10.
+- **New here:** the `in.dt`/`in.now` replay bug (P5), seed-ignoring `random2D` and module-global noise state in the references (§3), deterministic export (P13), and radius over diameter (P2).
+- **Build-time knobs** (the owner's rule): see "Build options" after P14.
+
+### P1. `Command.triangles` + tessellation in the Frame (lines, circles, polygons, strokes)
+
+> Superseded in naming and contract by research-love's `Command.shape`
+> (one shape per command, no overlap within it, optional AA fringe). The
+> web code and segment-count rule below still apply. Batch only opaque
+> same-color runs, and do it in the host.
+
+The single biggest gap. Tessellate in shared Zig and keep both hosts simple.
+This is Processing's OpenGL model, transform applied on the CPU.
+
+```zig
+// abi.zig, Command
+/// Triangles, 3 points each, in canvas pixels, any winding, filled once
+/// with `color`: where triangles overlap, the color is applied once (union),
+/// as one canvas path fill would.
+triangles: struct { color: Color, points: []const [2]f32 },
+```
+
+Tessellation lives in the sketch lib (`sb/src/sketch/tess.zig`, about 400 lines):
+- ellipses and arcs as fans, with the segment count taken from the on-screen radius: `n = clamp(ceil(π / acos(1 - 0.25/r_px)), 8, 256)`, where `r_px = r * m.scaleFactor()`;
+- lines and polylines as quads, plus join wedges (miter, bevel, round) and caps;
+- simple concave polygons by ear clipping. Holes and self-intersection go to the `vector` module, which stays the high-quality path (AA, gradients, even-odd).
+
+Batching: the Frame keeps the index of the last `.triangles` command and a
+scratch `ArrayList([2]f32)`. An emit with the same **opaque** color and blend
+appends to that list and patches the command's slice; anything else closes
+the batch. Translucent shapes are never merged, because union semantics would
+stop overlapping circles from darkening, unlike p5. (p5 WebGL's one draw per
+shape, `p5.Renderer3D.js:528-547`, is what this avoids.)
+
+- **Native** (`sb/src/host/gfx.zig`, about 60 lines): opaque → one `SDL_RenderGeometry` (`/usr/include/SDL3/SDL_render.h:2464`) from an `SDL_Vertex` array in the frame arena. Translucent → draw opaque into a bbox-sized scratch target, then composite it with alpha mod, so stroke joins do not double-blend. Not antialiased at first. A later MSAA SDL_GPU pipeline for this one command is a host-only change: no sketch changes.
+- **Web** (about 20 lines of JS plus one `extern "canvas"` in `sb/src/sketch/web.zig`):
+ ```js
+ triangles(ptr, n, r, g, b, a) {
+ const v = new Float32Array(wasm.memory.buffer, ptr, n * 2), p = new Path2D();
+ for (let i = 0; i < n * 2; i += 6) { // force one winding so nonzero = union
+ const [ax, ay, bx, by, cx, cy] = v.subarray(i, i + 6);
+ p.moveTo(ax, ay);
+ if ((bx - ax) * (cy - ay) - (by - ay) * (cx - ax) >= 0) { p.lineTo(bx, by); p.lineTo(cx, cy); }
+ else { p.lineTo(cx, cy); p.lineTo(bx, by); }
+ }
+ ctx.fillStyle = rgba(r, g, b, a); ctx.fill(p, 'nonzero');
+ },
+ ```
+ One path per command means no seams between triangles, and union coverage for free.
+- **Invariants**: commands stay data, both hosts run it, `abi.hash` changes. State is untouched.
+
+### P2. `sk.Pen`: style and transform as a value; push/pop is `const`
+
+```zig
+pub fn draw(s: *const State, f: *sk.Frame) void {
+ f.clear(0xffffff);
+ const pen = f.pen(.{ .fill = 0x7f7f7f, .stroke = .{ .color = 0x000000, .weight = 2 } });
+ for (s.movers.view()) |m| pen.circle(m.pos, m.mass * 4);
+
+ // push(); translate(); rotate(); ...; pop();
+ const arm = pen.translate(s.origin).rotate(s.angle);
+ arm.line(.{ 0, 0 }, .{ s.len, 0 });
+ arm.with(.{ .fill = sk.hsv(0.02, 0.7, 0.9) }).circle(.{ s.len, 0 }, 12);
+ // no pop: `arm` goes out of scope
+
+ var wave = f.path(); // beginShape()
+ for (s.ys, 0..) |y, i| wave.lineTo(.{ @as(f32, @floatFromInt(i)) * 8, y }); // vertex()
+ pen.with(.{ .fill = null }).draw(wave); // endShape()
+}
+```
+
+```zig
+// sb/src/sketch/pen.zig
+pub const Stroke = struct { color: Color = .black, weight: f32 = 1, cap: Cap = .round, join: Join = .miter };
+pub const Style = struct { fill: ?Color = .white, stroke: ?Stroke = null, blend: Composite = .alpha };
+pub const Pen = struct {
+ frame: *Frame,
+ m: Affine = .identity,
+ style: Style = .{},
+ pub fn with(p: Pen, overrides: anytype) Pen // Style fields by name; colors duck-typed
+ pub fn translate(p: Pen, by: anytype) Pen // any point type
+ pub fn rotate(p: Pen, radians: f32) Pen
+ pub fn scale(p: Pen, by: anytype) Pen // f32 or point
+ pub fn circle(p: Pen, center: anytype, radius: f32) void
+ pub fn ellipse(p: Pen, center: anytype, radii: anytype) void
+ pub fn arc(p: Pen, center: anytype, radii: anytype, from: f32, to: f32, kind: enum { open, chord, pie }) void
+ pub fn rect(p: Pen, r: anytype) void // emits `.rect` when m is translate+scale
+ pub fn line(p: Pen, a: anytype, b: anytype) void
+ pub fn polyline(p: Pen, points: anytype) void // slice of any point type
+ pub fn polygon(p: Pen, points: anytype) void
+ pub fn point(p: Pen, at: anytype) void
+ pub fn draw(p: Pen, path: Path) void // fill then stroke
+ pub fn image(p: Pen, img: Image, dst: anytype, options: anytype) void // affine via P6b
+};
+```
+
+- Opinion: use **radius, not diameter** (`circle(x, y, d)` in p5). It matches `ellipse(center, radii)` and the Camera's math. Write the port gotcha in the docs once.
+- `Affine` moves from `sb/src/vector/geom.zig:36` into the sketch lib; `vector` re-exports it, so there is one type.
+- `sk.Path` is a scratch-allocated builder (`moveTo`, `lineTo`, `quadTo`, `cubicTo`, `close`, with a new subpath on `moveTo` as `beginContour`). It is p5's Shape-as-data idea, without the begin/end state machine.
+- Where: sketch lib only, about 200 lines. Cost: none on the hosts.
+- Invariant: none. The Frame is rebuilt for each draw (`sb/src/sketch/root.zig:381`), so nothing can leak from frame to frame (the p5 bug at `structure.js:342`), and a forgotten pop cannot exist.
+
+### P3. `sk.Rng` in State, with a pinned algorithm, plus keyed stateless randomness
+
+```zig
+pub const State = struct {
+ rng: sk.Rng = .init(1), // randomSeed(1)
+ clock: sk.Clock = .{},
+ walker: sk.V2 = .{ 320, 240 },
+};
+pub fn update(s: *State, in: *const sk.Input) void {
+ for (0..s.clock.steps(in, 60)) |_|
+ s.walker += .{ s.rng.range(-1, 1), s.rng.range(-1, 1) };
+}
+pub fn draw(s: *const State, f: *sk.Frame) void {
+ // jitter in draw: still while paused, identical on replay
+ for (s.stars.view(), 0..) |star, i|
+ pen.point(star + sk.v2.splat(sk.rand.at(s.seed, .{ i, s.clock.ticks }) - 0.5));
+}
+```
+
+```zig
+pub const Rng = struct {
+ /// PCG32. Pinned here, not `std.Random.DefaultPrng`: a Zig release may
+ /// change that alias, or `Random.float`, under a saved recording.
+ state: u64,
+ inc: u64 = 0xda3e39cb94b95bdb,
+ spare: f32 = 0, // Marsaglia's second value, kept in State
+ has_spare: bool = false, // (p5 keeps it module-global: random.js:18)
+ pub fn init(seed: u64) Rng
+ pub fn float(r: *Rng) f32 // [0, 1)
+ pub fn range(r: *Rng, lo: f32, hi: f32) f32 // random(lo, hi)
+ pub fn below(r: *Rng, comptime T: type, n: T) T
+ pub fn chance(r: *Rng, p: f32) bool
+ pub fn gaussian(r: *Rng, mean: f32, sd: f32) f32
+ pub fn pick(r: *Rng, items: anytype) @TypeOf(&items[0])
+ pub fn onCircle(r: *Rng) V2 // PVector.random2D, seeded
+ pub fn fork(r: Rng, key: u64) Rng // an independent stream per subsystem
+ pub fn random(r: *Rng) std.Random // for std.Random.shuffle and friends
+};
+pub const rand = struct {
+ /// Stateless: the same seed and key give the same number. The key is a
+ /// tuple of ints.
+ pub fn at(seed: u64, key: anytype) f32
+};
+```
+
+- Opinion for hot reload: one sequential stream makes edits non-local. Add one `random()` call in `update` and every later draw shifts. Prefer `fork(id)` per entity or `rand.at(seed, .{ id, tick })`. Then editing one subsystem leaves the others' randomness alone, which matters when you iterate against a saved State.
+- Where: sketch lib, about 120 lines. Hosts: none. Invariant: supports determinism. Every field is plain data, so it migrates by field.
+
+### P4. `sk.noise`: pure, seeded, with a GLSL twin; `Classic` for parity with the book
+
+```zig
+const n = sk.noise.fbm(s.seed, sk.V2{ x * 0.01, y * 0.01 }, .{}); // ≈ p5 noise(x*.01, y*.01), 0..1
+const g = sk.noise.perlin(s.seed, .{ x, y, t }); // gradient noise, -1..1
+const P = sk.noise.Classic(.processing, 0); // noiseSeed(0), bit for bit
+const v = P.get(x, y, 0);
+```
+
+- `perlin(seed: u32, p: anytype)` is improved gradient noise. It hashes `(seed, lattice)` instead of building a permutation table, so a runtime seed costs nothing and there is no lazy init. `fbm(seed, p, .{ .octaves = 4, .falloff = 0.5, .lacunarity = 2 })` rescales to 0..1 like p5.
+- `Classic(comptime gen: enum { processing, p5 }, comptime seed: u64)` is a type whose 4096-float table is built at comptime (16 KiB rodata). `.processing` uses java.util.Random (as `helpers_a.zig` already does); `.p5` uses the LCG from `noise.js:466-505`. It keeps the `abs()` mirror (`PApplet.java:4937`) **only here**, for porting; the docs explain why the default avoids it.
+- `sb/shaders/noise.glsl` with the same hash, so a compute flow field and a CPU flow field agree, up to float precision. GPU results never feed `update`.
+- Where: sketch lib, about 150 lines, plus the GLSL include (through `addShaders` include paths). Invariant: none. Pure functions are safe in `update` and `draw`.
+
+### P5. Time: a `sk.Clock` in State, and make `in.dt` honest in `update`
+
+```zig
+pub const Clock = struct {
+ carry: f64 = 0, // tick seconds not yet stepped
+ ticks: u64 = 0, // frameCount, for update
+ seconds: f64 = 0, // millis() / 1000, for update
+ /// Fixed steps of 1/hz covered by this update's tick events; at most 8
+ /// (no spiral of death).
+ pub fn steps(c: *Clock, in: *const Input, hz: f32) u32
+ /// Variable dt: the seconds this update's ticks carry.
+ pub fn advance(c: *Clock, in: *const Input) f32
+};
+```
+
+Both port batches wrote `steps60` by hand. With it, NoC examples that assume
+one step per frame run at the book's speed on a 120 Hz display. p5 runs them
+at double speed there.
+
+Host fix (about 10 lines, `Host.zig:243`): in `Host.update`, set `input.dt`
+from the `tick` events being fed (their `x`), live and replayed alike. State in
+`abi.zig` that `in.now` and `in.frame` are draw-only (or give `update` an
+`Input` copy where `now` is recording-relative in both modes). Today a sketch
+that integrates `in.dt` in `update` replays wrong, quietly. Same fix in
+`sb/src/sketch/web.zig`'s driver.
+
+- Invariant: **restores** determinism of `update`.
+
+### P6. `sk.List(T, N)` for State, and element-wise migration of arrays of structs
+
+```zig
+pub const Particle = struct { pos: sk.V2, vel: sk.V2, life: f32 = 1, hue: f32 = 0 }; // added `hue` live
+pub const State = struct { particles: sk.List(Particle, 2048) = .{} };
+// update:
+_ = s.particles.append(.{ .pos = origin, .vel = s.rng.onCircle() });
+var i: u32 = 0;
+while (i < s.particles.len) { if (dead(s.particles.at(i))) s.particles.swapRemove(i) else i += 1; }
+```
+
+- `List` (sketch lib, about 60 lines): `items: [N]T = undefined, len: u32 = 0`; `view`, `slice`, `at`, `append → bool`, `swapRemove`, `orderedRemove`, `clear`. `view()` clamps `len` to `N`, in case a migration shrank the capacity.
+- **The real problem:** `[N]Particle` is one leaf (`sb/src/abi.zig:558-560`, "arrays stay whole"), and `migrate` copies a leaf only when its hash and size match (`sb/src/host/memory.zig:95-110`). Add `hue` to Particle and on reload `items` resets to its default (`undefined`) while `len` (unchanged u32) is **kept**, so the sketch iterates garbage (coordinator, board). Changing the capacity does the same. That is exactly when you want to see the change on the live swarm. With element-wise migration a bare `[N]T` + `n: u32` is enough. `List` is then convenience only.
+- Proposal: reflect `[N]struct` as per-field leaves `particles.items[].pos` with `count` and `stride` added to `abi.Field` (an extern on-disk struct, so bump the state-file header version). `migrate` then copies `min(old_count, new_count)` elements field by field. Console and probe learn the path `particles.items[3].pos`.
+- Where: `sb/src/layout.zig` and `sb/src/host/memory.zig`, plus console and probe paths; about 200 lines. Web: nothing, since nothing persists there. Invariant: **extends** field-by-field migration. State stays plain data.
+
+### P7. `sk.V2` and `sk.v2`, plus `sk.map`
+
+```zig
+pub const V2 = @Vector(2, f32);
+pub const v2 = struct {
+ splat, length, lengthSq, dist, normalize, setLength, limit, heading,
+ fromAngle, rotate, dot, cross, perp, angleBetween, reflect,
+};
+pub fn map(v: f32, from: [2]f32, to: [2]f32) f32 // and mapClamped
+```
+
+Zig has no scalar broadcast (`v * 2` must be `v * @as(V2, @splat(2))`;
+see the coordinator's shader note), so `v2.scale(v, s)` and `v2.splat` carry
+most of the weight. Use Zig names, and add a one-line PVector→v2 table in the docs (`mag` →
+`length`, `setMag` → `setLength`). Lerp is already `tween.lerp`. Sketch lib,
+about 80 lines. No invariant.
+
+### P8. Color: constructors and `mix`, never a mode
+
+```zig
+f.clear(sk.hsv(0.6, 0.3, 0.1));
+pen.with(.{ .fill = .{ .h = s.hue, .s = 0.8, .v = 1 } }).circle(p, 6); // duck-typed HSV
+const c = sk.color.mix(a, b, t, .oklab); // lerpColor, in a chosen space
+```
+
+`hsv`, `hsl`, `oklch` return `abi.Color`. Hue is in **turns** (0..1, wraps),
+consistent with the existing 0..1 float channels. `shape.isColor` also
+accepts `h/s/v[/a]` and `h/s/l[/a]` fields. Sketch lib, about 120 lines. No
+invariant. Avoids Processing's mode-dependent meaning of `fill(a, b, c)`.
+
+### P9. Blend as a style field, emitted as a stateful command only on change
+
+```zig
+const glow = pen.with(.{ .fill = sk.hsv(0.1, 0.6, 1).alpha(40), .blend = .add });
+for (s.sparks.view()) |sp| glow.circle(sp.pos, 6);
+```
+
+- (Revised: `screen` dropped. See "Relation to research-love". The modes are `{alpha, add, multiply}`.)
+- `abi.Composite = enum { alpha, add, multiply }` and `Command.blend: Composite`. It is stateful like `clip` already is. The Frame emits it only when the Pen's blend differs from the last one emitted, and closes the triangle batch when it changes (Processing flushes on a blend change, `PGraphicsOpenGL.java:6212-6216`).
+- Native: `SDL_SetRenderDrawBlendMode` (and texture blend for images): BLEND, ADD, MUL; screen through `SDL_ComposeCustomBlendMode(ONE, ONE_MINUS_SRC_COLOR, ADD, …)`, logged once where the fallback renderer refuses it. Web: `source-over`, `lighter`, `multiply`, `screen`. Reset to `alpha` before overlays, as clip is reset (`Host.zig:304`). About 30 lines native, 5 web.
+- Not included: `replace`/`copy`, because canvas `copy` clears outside the shape; difference and exclusion, because SDL fixed-function blending cannot do them. A mode only one host can run breaks the "both hosts" invariant.
+
+### P10. Offscreen 2D targets (createGraphics)
+
+```zig
+// Session
+trail: sk.Image = .none,
+drawn: u64 = 0,
+// draw
+if (ss.trail == .none) ss.trail = f.host.newTarget(960, 600);
+if (f.in.jumped) ss.drawn = 0; // seek/load: start the layer over (research-love's Input.jumped)
+if (ss.drawn != s.clock.ticks) { // accumulate only when State moved
+ ss.drawn = s.clock.ticks;
+ f.target(ss.trail, .{ .clear = null }); // keep last frame's pixels
+ pen.with(.{ .fill = sk.Color.white.alpha(12) }).rect(.{ .w = 960, .h = 600 }); // fade
+ for (s.movers.view()) |m| pen.circle(m.pos, 8);
+ f.target(.none, .{});
+}
+f.image(ss.trail, .{ .w = 960, .h = 600 }, .{});
+```
+
+- `Host.VTable.newTarget(w, h) Image` creates an `SDL_TEXTUREACCESS_TARGET` texture in `Images` (a streaming texture cannot also be a target). `Command.target: struct { image: Image, clear: ?Color }`, where `.none` means the canvas. **Native must go back to `self.offscreen` when headless** (`Host.zig:529-530`), not to null, and reset the target before overlays. Web: each target image gets its own canvas and context, and the module-level `ctx` is swapped. About 60 lines each.
+- Invariant: a target's pixels are **Session** state, presentation only. They are not snapshotted, and after a seek they are wrong until they refill. The pattern above stops pause from repeating the accumulation; document that. Anything that must replay exactly belongs in State (a ring buffer of past positions).
+
+### P6b. Images under a transform (folded into P2, needs one ABI field)
+
+`Command.image` gains `quad: ?[3][2]f32 = null` (origin, right, down
+corners). Native: `SDL_RenderTextureAffine` (`SDL_render.h:2337`), which
+takes exactly those three points. Web: `ctx.setTransform` from the three
+points, `drawImage`, then reset. About 15 lines each. Text keeps axis-aligned
+cells: the Pen moves its origin only.
+
+### P11. Rect anchors as constructors (rectMode, ellipseMode)
+
+```zig
+pen.rect(sk.shape.centered(p, .{ 40, 20 })); // rectMode(CENTER)
+pen.rect(sk.shape.corners(a, b)); // rectMode(CORNERS)
+```
+
+Sketch lib, about 20 lines. A call means the same thing wherever it appears.
+
+### P12. `sk.fx`: a shadertoy pass and stock filters, built on GPU-as-data
+
+```zig
+sk.fx.shade(f, ss.view, shaders.plasma_frag, Plasma{ .t = s.clock.seconds }); // fullscreen
+sk.fx.filter(f, .{ .src = ss.trail, .dst = ss.soft, .op = .{ .blur = 4 } }); // filter(BLUR, 4)
+```
+
+Builds `abi.gpu.Pass` with a built-in attribute-less fullscreen vertex
+shader. Filters (blur, threshold, invert, gray, posterize, and feedback,
+which reads the previous frame) ship as sketchbook shaders, compiled once
+into SPIR-V and WGSL. Needs P10 to filter 2D drawing. Sketch lib plus
+shaders, about 250 lines. No ABI change. Live shader editing already works
+(`zig build lib --watch` → new hash → new pipeline); nothing to copy from
+`loadShader`.
+
+### P13. Deterministic frame export from a recording (saveFrames done right)
+
+```
+> export 2 out/frames 60 # recording 2 → out/frames/0000.png …, at its recorded ticks
+# in a .script: export 2 out/frames
+```
+
+Host-only (native): restore the recording's snapshot, then for each recorded
+tick run update, draw, and the existing screenshot path
+(`Host.zig:319-323`), with an optional `--scale` to render the canvas at N×.
+It renders offline and identically every time, at any length. p5's
+`saveFrames` is wall-clock `setInterval` and capped at 15 s / 22 fps
+(`image.js:631-660`). About 100 lines. Not a Command, so the "both hosts"
+rule does not apply. The web has no export.
+
+### P14. Input sugar (pmouse, clicked)
+
+```zig
+if (in.clicked(.left)) s.target = in.mouse(); // mouse_down in this update's events
+s.trail_delta = in.mouse() - in.prevMouse(); // pmouseX / pmouseY
+```
+
+`Input.prev_mouse_x/y` is set by the host at the start of `update`, before
+`track` (`Host.zig:245`; the same in the web driver). It is derived from
+events only, so it replays. `mouse()` returns `@Vector(2, f32)`; `clicked`
+and `unclicked` mirror `pressed`. About 30 lines in `abi.zig`, 2 lines per
+host.
+
+(Smaller: `f.textWidth(bytes, scale)` = codepoints × 8 × scale, so text can
+be centered without an align mode.)
+
+### Build options: where Processing's global modes go
+
+Processing and p5 put these choices in mutable runtime globals
+(`size()`/`settings()`, `colorMode`, `noiseDetail`, renderer `P2D`/`WEBGL`,
+`smooth()`, `pixelDensity`). The owner's rule is that they are per-app build
+decisions. Mechanism: `sb.app(.{ ..., .options = .{ ... } })` writes a
+generated `sketch_options` module that the sketch lib imports, so each knob
+is a comptime constant, the same on native and web. No runtime state, and a
+`-D` flag can override it.
+
+```zig
+const app = sb.app(.{
+ .name = "flow_field",
+ .root_source_file = b.path("src/flow_field.zig"),
+ .options = .{
+ .noise = .processing, // .perlin (default) | .processing | .p5: what sk.noise.get(x, y, z) is
+ .noise_seed = 0, // for the classic tables (comptime, 16 KiB rodata)
+ .hue = .turns, // .turns | .degrees: what `.h` means in duck-typed colors
+ .antialias = .fringe, // .none (pixel art) | .fringe: whether the Pen emits AA fringes
+ .canvas = .{ 640, 360 }, // overrides `pub const width/height` (or -Dcanvas=640x360)
+ },
+});
+```
+
+- **Noise flavour** replaces `Classic(.processing, 0)` from P4: `sk.noise.get` is fixed at build time. A port sets `.noise = .processing` once and gets the book's pictures. `perlin`/`fbm` with an explicit seed stay available.
+- **Hue unit / colour range** replaces `colorMode`. It is fixed per app, so `.{ .h = 200 }` can never mean two things in one program.
+- **Renderer / AA** replaces `P2D`/`JAVA2D`/`smooth()`: whether the Pen emits fringes, and later which native backend runs `shape` (SDL_RenderGeometry or an MSAA SDL_GPU pipeline).
+- **Not build options:** seeds of the simulation (they are State: `rng: sk.Rng = .init(1)`), step rate (a `Clock.steps(in, hz)` argument), and pen style (a value in `draw`).
+- Cost: about 40 lines in `sb/build.zig`, nothing in the hosts. Invariant: none. These are compile-time constants.
+
+---
+
+## 3. Do not copy
+
+1. **Implicit "current renderer" style and matrix state** (`fill()`, `stroke()`, `translate()` mutating a global). In p5 it leaks across frames, because `redraw` resets only the matrix (`structure.js:342`); a pop on an empty stack is silent in p5 (`p5.Renderer.js:151`) and throws in Processing (`PGraphics.java:6294`). The Pen value does all of this with Zig's own scoping.
+2. **Modes that change what a call means**: `rectMode`, `ellipseMode`, `imageMode`, `colorMode`. Each is action at a distance. Use constructors and explicit types.
+3. **Unseeded or hidden randomness**: Processing's lazy unseeded `Random` (`PApplet.java:4707`), p5's `Math.random` fallback (`random.js:278-282`), `random2D` ignoring the seed (`PVector.java:244`, `p5.Vector.js:3150`), the module-global noise table and gaussian spare (`noise.js:31`, `random.js:18`). In `update` these break replay. In `draw` they make a paused sketch flicker and a replay look different. Every generator is a value in State, or a pure function of a seed you pass.
+4. **Not calling `background()` to keep the previous frame.** The host clears and draws again on pause and seek (`Host.zig:285-287`), so accumulation would double on pause and be wrong after a seek. Use a ring buffer in State, or an explicit target (P10) under the "only when State moved" rule.
+5. **Event callbacks that mutate globals at arbitrary times**: p5 at DOM time (`keyboard.js:606-623`), Processing after draw (`PApplet.java:2112`). The ordered, recorded `in.events` is the right model.
+6. **Wall-clock time in simulation**: `millis()` (`PApplet.java:2887`), rAF `deltaTime` (`main.js:331`), `frameRate(fps)` as the physics rate. Simulation time comes from recorded ticks through `Clock`. (Today's `in.dt`/`in.now` in `update` break this quietly: P5.)
+7. **Shaders loaded by path at runtime, with uniforms set by string name**: Processing's HashMap (`PShaderOpenGL.java:742`), p5 ignoring a mistyped name (`p5.Shader.js:1147-1150`). Comptime std140 structs plus build-time compilation catch the typo, and the web host would need naga in the browser.
+8. **p5.strands and `modify(hooks)`** (string-hooked shader patching, `p5.Shader.js:425`): a lot of machinery for what an `#include` and a GLSL function already do.
+9. **`noLoop` / `loop` / `redraw`**: draw runs every frame and is cheap. A "static" sketch is State that stops changing. A redraw switch would only add a mode.
+10. **Variadic overloads** (`fill(gray)`, `fill(r, g, b)`, `random(array)`, `color(...)`): use one signature per function, with duck-typed arguments checked at comptime, as `shape.zig` already does.
+11. **One GPU draw per immediate shape** (`p5.Renderer3D.js:528-547`): batch in the Frame instead (P1).
+12. **Retained `PShape`/`createShape` trees with mutable children**: retained geometry that needs it is a `Buffer` (`host.newBuffer` and `f.upload`), which already exists and is data.
+13. **The `abs()` mirror in classic noise** as the default (`PApplet.java:4937`): keep it only behind `Classic`, for porting.
+14. **`saveFrame` as a draw-time side effect**: replays and seeks would fire it again. Export is a host tool over recordings (P13).
+
+---
+
+## Ranking
+
+1. P1 `.triangles` + Frame tessellation and batching
+2. P2 `Pen` value (style + affine; push/pop is a `const`)
+3. P5 `Clock`, and fix `in.dt`/`in.now` in `update` (a correctness bug today)
+4. P3 `Rng` in State (pinned PCG32), plus `rand.at` keyed randomness
+5. P6 `List(T, N)` + element-wise migration of struct arrays
+6. P4 `noise` (seeded, pure, GLSL twin, `Classic` for parity)
+7. P7 `V2`/`v2` + `map`
+8. P8 `hsv`/`oklch`/`mix`, duck-typed HSV
+9. P10 offscreen 2D targets (unlocks trails and P12)
+10. P9 blend modes both hosts can run ({alpha, add, multiply}) + build options for noise, hue and AA
+
+Next after these: P13 export, P6b affine images, P12 fx, P14 input sugar, P11 anchors.