# 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.