# Research: Zig std and sketchbook internals, for imperative creative coding Scope: what sketchbook should add or change so Nature of Code style sketches are easy to write while staying Zig-ish (explicit, no hidden globals, explicit allocators, std idioms). This covers Zig 0.17 std and sketchbook's own internals. Processing/p5 and LÖVE/raylib API surveys, and shaders in depth, are covered elsewhere. Paths below are relative to `lib/sketchbook/` unless they start with `src/` of the game (`../../src/...`) or `sketches/noc/`. Experiments were run in a scratch dir against the real `src/abi.zig`, `src/layout.zig` and `src/host/memory.zig`, using zig 0.17.0. They are marked **[verified]**. --- ## 0. The strongest evidence: the NoC ports already hit every gap `sketches/noc/src/helpers_a.zig` and `helpers_b.zig` were written separately by two port batches. Both re-implement the same missing pieces: | Gap | helpers_a | helpers_b | Game (`../../src`) | | --- | --- | --- | --- | | PVector ops on `@Vector(2,f32)` | `setMag`, `limit`, `splat` (:32-40) | `mag`, `dist`, `scale`, `normalize`, `setMag`, `limit`, `heading`, `fromAngle` (:210-234) | — | | `random(lo, hi)` over a State PRNG | `range` (:42) | `random` (:240) | — | | `noise()` | Processing's exact table at comptime (:50-129) | table rebuilt from a seed (:279-336) | — | | Pointer-free list for State | — | `List(T, cap)` (:247-273) | `dialogue.State.offered`+`count`, `Choice.text`+`len`, `room.Layout.items`+`len`, `tracker.Song.order`+`order_len` | | Circles/lines/polygons with fill+stroke | `Pen` over `vector.Drawing.Builder`, GPU renderer (:146-193) | `Pen` + `Canvas` over CPU renderer (:350-399) | `ui.outline` = 4 fills (`ui.zig:20`); the cursor tail is 96 one-pixel-ish rects (`ui.zig:88-105`) | | Transform (push/translate/rotate/pop) | `Style.transform: Affine` | `Pen.transform: Affine` (:356) | — | | Fixed 60 Hz step | `steps60` (:17-27) | absent: batch B steps per frame, so speed depends on refresh rate | `dialogue.end(dt, ...)` uses tick dt | | `map()` | `map` (:132) | — | — | | draw returning errors | — | every sketch wraps: `paint(...) catch \|err\| f.host.print(...)` (`flocking.zig:130`, `system_of_systems.zig:68`, `flow_field.zig:102`, `the_wave.zig:26`) | — | | No-`background()` trails | — | — | `random_walk.zig` keeps a `StaticBitSet(640*360)` in State and re-uploads 900 KB of pixels every frame (:19, :48-53) | Every proposal below is something at least one of these files had to build by hand. --- ## 1. Variable numbers of entities in State ### What layout reflection does today `src/layout.zig:41-57` flattens *structs* into dotted leaves; everything else, arrays included, is **one leaf** (`:50-53`, `leaf()` at `:59-78` gives arrays kind `.array`). The leaf hash is the structural signature (`:116-147`): an array's signature is `[N]` ++ the element's full signature, and a struct's signature includes every field name, offset and type. Migration (`src/host/memory.zig:95-111`) copies a leaf only if `before.hash == leaf.hash and before.size == leaf.size`; otherwise the leaf keeps the new default. Enums are remapped by tag name (`:113-120`); nothing else is. ### What that means for particle lists [verified] Prototype: `List(P, cap) = struct { buffer: [cap]P, len: u32 }`, migrated with the real `memory.migrate`: | Edit while running | Result | | --- | --- | | Add a field to `P` | `buffer` reset (every particle zeroed), `len` **kept** (10 zombie particles at the origin) | | Capacity 64 → 128 | `buffer` reset, `len` kept | | Capacity 64 → 4 | `buffer` reset, `len = 10` kept, so `buffer[0..len]` is **out of bounds** (`helpers_b.List.slice` at :254 would panic) | | Same with a struct-of-arrays list (one `[cap]F` per field) | adding a field keeps every other column (`kept=3 reset=1`), with no host change | The game has the same hazard, and worse: `tracker.State.songs: [8]Song` (`../../src/tracker.zig:56`) is one leaf. Adding any field to `Song` (a `swing` byte, say) on hot reload **erases every song the player composed**. ### std 0.17 situation - `std.BoundedArray` is gone: removed in `196e36bbb2` ("std: remove BoundedArray … handled by ArrayListUnmanaged via the '...Bounded' method variants"). The idiom now is `std.ArrayList(T).initBuffer(&buf)` plus `appendBounded`, `addOneBounded`, `insertBounded`, … which return `error.OutOfMemory` when full (`/usr/lib/zig/std/array_list.zig:681`, `:1046`, `:1425`). - `ArrayList` holds a slice (`items: Slice`, `:647`) and `MultiArrayList` holds `bytes: [*]u8` (`multi_array_list.zig:26`): neither can live in State. `layout.check` rejects them at compile time, which is right. - `initBuffer` is fine for *locals* in `update`/`draw` (`room.Layout` could be one), but State needs its own pointer-free type. ### Proposal: `sk.List(T, capacity)` (and `sk.Ring`) Mirror std naming so it reads like `ArrayList`'s bounded API, and clamp the length so a capacity shrink can never index out of bounds. ```zig // src/sketch/list.zig pub fn List(comptime T: type, comptime capacity: u32) type { return struct { const Self = @This(); pub const Elem = T; pub const cap = capacity; /// Zeroed, not undefined: state files and snapshots stay comparable. buffer: [capacity]T = @splat(std.mem.zeroes(T)), len: u32 = 0, pub const empty: Self = .{}; /// Live elements. Clamped: after a capacity shrink `len` may exceed `cap`. pub fn items(l: *Self) []T { return l.buffer[0..@min(l.len, capacity)]; } pub fn constItems(l: *const Self) []const T { return l.buffer[0..@min(l.len, capacity)]; } /// Same contract as `ArrayList.appendBounded`. pub fn append(l: *Self, item: T) error{OutOfMemory}!void; pub fn addOne(l: *Self) error{OutOfMemory}!*T; pub fn swapRemove(l: *Self, i: usize) T; // O(1), for particles pub fn orderedRemove(l: *Self, i: usize) T; // keeps draw order pub fn clear(l: *Self) void; pub fn full(l: *const Self) bool; }; } /// Fixed-size history: `push` overwrites the oldest. For trails, recent /// events, and "what happened since the last draw" (see section 5). pub fn Ring(comptime T: type, comptime capacity: u32) type { return struct { buffer: [capacity]T = @splat(std.mem.zeroes(T)), /// Items ever pushed: a sequence number that also survives wrap-around. pushed: u64 = 0, pub fn push(r: *@This(), item: T) void; pub fn latest(r: *const @This(), n: usize) Iterator; // newest n, oldest first pub fn since(r: *const @This(), seq: u64) Iterator; // pushed after `seq` }; } ``` Usage (NoC 4.2, particle system): ```zig pub const State = struct { rng: std.Random.DefaultPrng = .init(4), particles: sk.List(Particle, 512) = .empty, }; // update, per fixed step s.particles.append(.spawn(s.rng.random(), origin)) catch {}; // full: drop, like a capped emitter var i: usize = 0; while (i < s.particles.items().len) { const p = &s.particles.items()[i]; p.step(); if (p.dead()) _ = s.particles.swapRemove(i) else i += 1; } ``` Optional `sk.Soa(T, cap)` with `items(.pos)` (the `MultiArrayList` API shape) gives per-field migration for free. The prototype needs one fix: use each field's own default for its column (`attrs.defaultValue(F)`), not `zeroes`. Without that, a new `mass: f32 = 1` column came back as 0 [verified]. SoA reads worse for NoC code, so it is a niche tool, not the default. **Cost:** `List` + `Ring` + tests: about 150 lines, half a day. No host change. ### Proposal: element-wise array migration in the host Make the reflected layout understand repetition, so arrays of structs migrate field by field and element by element, and arrays whose element type is unchanged keep their common prefix. 1. `abi.Field` (`src/abi.zig:561`) gains `count: u32 = 1, stride: u32 = 0, elem_hash: u64 = 0`. 2. `layout.flatten` (`src/layout.zig:41`): for `[N]S` where `S` is a non-packed struct, recurse into `S` with the path `name[]` and emit leaves with `count = N, stride = @sizeOf(S)`, so you get `particles.buffer[].pos.x`. For arrays of scalars or enums, emit one leaf with `elem_hash` = hash of the child. Nested arrays of structs (tracker `Song.patterns`) can either multiply into up to three `(count, stride)` dimensions, or stop at one level and rely on rule 3 for the inner arrays. 3. `memory.migrate` (`src/host/memory.zig:95`): - a repeated leaf copies `min(old.count, new.count)` elements at their strides; - an array leaf whose hash differs but whose `elem_hash` matches copies the common prefix (capacity change); - enum elements get `remapEnum` per element. 4. `StoredField` (`memory.zig:40`) gets the new fields; bump `file_magic` to `SKETCH02` (`memory.zig:23`), and treat old files as foreign, which is the existing path for a missing layout. 5. `fields.zig` (`format`/`set`, `:7-50`) and `web.zig` `sk_field`/`sk_tag` (`:321-358`) accept an index in the path: `particles.buffer[3].pos.x`. Then console `get`/`set`, script `expect`/`await`, the probe and `window.sketch.field()` can all address individual entities. 6. The memory overlay (`host/overlay.zig:18`) shows one row per leaf, so a repeated leaf stays one row (`particles.buffer[].pos.x ×512`). With that change, adding `mass` to `Particle` keeps every position and velocity, a capacity change keeps the first `min` particles, and the tracker songs survive a new `Song` field. **Cost:** about 230 lines including tests (layout 40, abi 5, memory 50, fields 40, web 15, overlay 10, tests 70). About 1 day. `abi.hash` changes automatically (`abi.zig:635`). --- ## 2. Deterministic randomness and noise ### PRNG in State: already works [verified] ```zig pub const State = struct { rng: std.Random.DefaultPrng = .init(42) }; ``` - `DefaultPrng = Xoshiro256` (`/usr/lib/zig/std/Random.zig:13`), whose state is `s: [4]u64` (`Random/Xoshiro256.zig:9`): no pointers, so `layout.check` accepts it. - `.init(42)` works as a field default: `seed` runs SplitMix64 at comptime. - Reflection gives one leaf, `rng.s` (kind `.array`, 32 bytes). It migrates byte for byte as long as the generator type does not change. - `std.Random` (the interface from `.random()`) holds a pointer and a function pointer. Putting it in State is a compile error, which is correct: take it locally. - **Determinism across hosts [verified]:** a checksum over 20k values of `float(f32)`, `floatNorm(f32)` (ziggurat tables), `@sin` and the noise below was identical (`514686fd`) in native Debug (self-hosted backend), native ReleaseFast (LLVM), wasm32 Debug and wasm32 ReleaseSmall. Recordings and web replays agree. - Smaller alternatives if size matters: `SplitMix64` (8 B), `Pcg` (16 B), `Xoroshiro128` (16 B), `Sfc64` (32 B). `Isaac64` (about 4 KB) and `ChaCha` are overkill. - `std.Io` has randomness too (`Io.zig:1-14`). That is exactly what `update` must not use: it is a nondeterministic source. Sketches should never be handed an `Io` in `update`; the existing `call` dispatcher (`src/sketch/root.zig:235-269`) already rejects unknown parameter types. ### Proposal: don't wrap the PRNG; add free functions over `std.Random` Wrapping std's generator would duplicate its whole API. The Zig-ish move is to keep `std.Random` as the interface and add the handful of creative-coding draws as free functions: ```zig // src/sketch/random.zig: every function takes the std interface pub fn range(r: std.Random, lo: f32, hi: f32) f32; // p5 random(lo, hi) pub fn gaussian(r: std.Random, mean: f32, sd: f32) f32; // randomGaussian, via floatNorm pub fn chance(r: std.Random, p: f32) bool; pub fn unit(r: std.Random) sk.Vec2; // PVector.random2D pub fn inRect(r: std.Random, rect: anytype) sk.Vec2; pub fn pick(r: std.Random, comptime T: type, items: []const T) T; /// Monte Carlo / "accept-reject" (NoC 0.5). pub fn acceptReject(r: std.Random, comptime f: fn (f32) f32) f32; /// A generator for entity `i`, independent of how many numbers others drew: /// edits that add a draw elsewhere don't reshuffle this entity. pub fn stream(seed: u64, i: u64) std.Random.DefaultPrng; // .init(std.hash.int(seed ^ i *% K)) ``` ```zig // update const r = s.rng.random(); for (0..n) |_| try s.walkers.append(.{ .pos = sk.random.inRect(r, bounds), .step = sk.random.gaussian(r, 0, 2) }); ``` **Where the seed comes from:** - a fixed default (reproducible art); - `init(s, host)` with `s.rng = .init(host.clock())`. Init is not replayed, and the seed is saved with the state, so replays still match; - a console `set rng.s ...` (works today). **Randomness in `draw`** (p5 sketches often call `random()` there): `draw` cannot write State. Use a local `std.Random.DefaultPrng.init(seed ^ in.frame)`, or the stateless `sk.noise.hash01(seed, i)`. **Cost:** about 60 lines, a couple of hours. ### Proposal: `sk.noise`, pure functions of seed and coordinates Two flavours, both with no mutable globals: ```zig // src/sketch/noise.zig /// Gradient noise, about -1..1, a pure function: lattice corners hashed with /// `std.hash.int` and `seed`. No permutation table, so the seed can be a /// runtime State field. pub fn perlin2(seed: u32, x: f32, y: f32) f32; pub fn perlin3(seed: u32, x: f32, y: f32, z: f32) f32; // flow fields animated by z = t pub const Fbm = struct { octaves: u4 = 4, falloff: f32 = 0.5, lacunarity: f32 = 2 }; /// p5's noise(x, y): 0..1, octaves summed. pub fn fbm2(seed: u32, x: f32, y: f32, o: Fbm) f32; pub fn fbm3(seed: u32, x: f32, y: f32, z: f32, o: Fbm) f32; pub fn hash01(seed: u32, i: u32) f32; // stable "random" per index, for draw /// Processing's own noise() (PApplet), for ports checked against reference /// images: 4096 floats from java.util.Random's LCG. Build it where the seed /// is known: at comptime for a constant seed (helpers_a.zig:52), or in /// Session/on the stack from a State seed (helpers_b.zig:285). Not in State: /// it is derived data (16 KiB). pub const Classic = struct { table: [4096]f32, pub fn init(seed: u64) Classic; pub fn get(n: *const Classic, x: f32, y: f32, z: f32) f32; }; ``` A 40-line `perlin2`/`fbm2` prototype passed range, smoothness and seed-sensitivity tests, and gave the same bits on native and wasm [verified] (range about -0.75..0.70, which is typical for 2D Perlin). Simplex/OpenSimplex2 can come later; Perlin covers NoC chapter 0 and the flow-field examples. **Cost:** about 200 lines including Classic and tests, half a day. --- ## 3. Math vocabulary: `Vec2` struct vs `@Vector(2, f32)` vs duck typing ### What exists - `src/sketch/shape.zig` duck-types points: anything with `x`/`y`, or 2+ element vectors or arrays (`:9-22`). Helpers return the caller's type (`Out`, `:52-60`). - `src/sketch/tween.zig:8-33` `lerp` works on floats, vectors, arrays and structs (it splats `t` for vectors). `progress` (`:65`) is inverse-lerp clamped, and `ease.*` (`:72`) are the easing curves. - `src/vector/geom.zig:6-34` already uses `Vec = @Vector(2, f32)` with free functions `dot`, `cross`, `length`, `normalize`, `perp`, `mix`, `splat`, plus a full `Affine` (`:36-97`). That is the obvious seed of `sk.math`. - `std.math` has `lerp` (with `@mulAdd`, where `t` must match the vector type, so it needs a splat; `math.zig:1382`), `clamp` (scalars and vectors, `:526`), `wrap` to `[-r, r)` (`:443`), `degreesToRadians`/`radiansToDegrees` (`:268`, `:303`), `tau`, `atan2`, `hypot`. It has **no** `remap`/`map`, `smoothstep`, `fract`, `sign`, or angle normalization to `[0, tau)`. ### `@Vector` findings [verified] - Operators work for vector with vector: `pos += vel; vel += acc;`. Scalar with vector does **not**: `v * 2` is "mixed scalar and vector operands". You need `v * @as(Vec, @splat(k))`, or `v *= @splat(k)` where the result type is known. Both batches wrote `scale(v, s)` for exactly this reason (`helpers_b.zig:216`). - No `.x`/`.y`: you write `p[0]`/`p[1]`, which is what `flocking.zig:43-46` has to do. - **Layout differs by backend:** `@sizeOf/@alignOf(@Vector(2, f32))` is **16/16 on x86_64 with the self-hosted backend (Debug)**, and 8/8 with LLVM (`-fllvm`, ReleaseFast), on wasm32 and on aarch64. So: - in Debug, every `Vec2` in State takes double the space; - switching `-Doptimize` changes the size, so `migrate` resets every vector leaf (`memory.zig:102` checks size) and every array-of-structs containing one (the signature includes offsets). - Reflection treats a vector as an opaque leaf (`layout.zig:66`, kind `.bytes`). `fields.zig` prints `<16 bytes>` (`:22`) and refuses `set` (`:47`). So `get mover.pos`, `set mover.pos.x 100` and a script's `expect mover.pos.x 320` are all impossible with `@Vector` state today. ### Proposal 1. **`sk.Vec2 = extern struct { x: f32 = 0, y: f32 = 0 }`** as the type to *store*. It is 8 bytes everywhere, flattens to `pos.x`/`pos.y` float leaves (console, scripts, probe and overlay all work), and `shape.zig` already accepts it. Its methods follow PVector, so NoC translates line for line, left to right: ```zig pub const Vec2 = extern struct { x: f32 = 0, y: f32 = 0, pub const zero: Vec2 = .{}; pub fn xy(x: f32, y: f32) Vec2; pub fn add(a: Vec2, b: Vec2) Vec2; pub fn sub(a: Vec2, b: Vec2) Vec2; pub fn scale(a: Vec2, k: f32) Vec2; pub fn div(a: Vec2, k: f32) Vec2; pub fn mul(a: Vec2, b: Vec2) Vec2; // component-wise pub fn dot(a: Vec2, b: Vec2) f32; pub fn cross(a: Vec2, b: Vec2) f32; pub fn len(a: Vec2) f32; pub fn lenSq(a: Vec2) f32; pub fn dist(a: Vec2, b: Vec2) f32; pub fn normalize(a: Vec2) Vec2; // zero stays zero pub fn withLen(a: Vec2, m: f32) Vec2; // setMag pub fn limit(a: Vec2, max: f32) Vec2; pub fn heading(a: Vec2) f32; pub fn fromAngle(rad: f32) Vec2; pub fn rotate(a: Vec2, rad: f32) Vec2; pub fn perp(a: Vec2) Vec2; pub fn lerp(a: Vec2, b: Vec2, t: f32) Vec2; pub fn simd(a: Vec2) @Vector(2, f32); pub fn of(v: @Vector(2, f32)) Vec2; }; ``` ```zig // NoC 1.10, accelerating toward the mouse const dir = sk.Vec2.xy(in.mouse_x, in.mouse_y).sub(m.pos).withLen(0.2); m.vel = m.vel.add(dir).limit(m.top_speed); m.pos = m.pos.add(m.vel); ``` Compare `b.limit(b.setMag(b.scale(sum, 1 / count), maxspeed) - self.velocity, maxforce)` (`flocking.zig:77`). 2. **Keep `@Vector` as the compute type**, for anyone who prefers operators: `sk.math` free functions take `anytype` and follow geom's `@Vector` versions, so `pos += vel` code works without conversions. For hot loops over thousands of entities, `simd()`/`of()` convert at the edges. 3. **Teach `layout.flatten` to split `@Vector(N, T)` leaves into `name[0..N]` scalar leaves.** That is about 10 lines, and makes `@Vector` state inspectable even for sketches that choose it. The backend size difference remains, so document "prefer `sk.Vec2` in State". 4. **`sk.math`** (scalars; lift `geom.Affine` as `sk.Affine` with `.identity`, `.translate`, `.rotate`, `.scale`, `.mul`, `.apply`): ```zig /// p5 map(): ranges as pairs so the five floats can't be misordered. pub fn remap(v: f32, from: [2]f32, to: [2]f32) f32; pub fn remapClamped(v: f32, from: [2]f32, to: [2]f32) f32; pub fn smoothstep(e0: f32, e1: f32, x: f32) f32; pub fn fract(x: f32) f32; pub fn angle(rad: f32) f32; // normalized to [0, tau) pub fn approach(cur: f32, target: f32, max_step: f32) f32; ``` ```zig const y = sk.math.remap(@sin(angle), .{ -1, 1 }, .{ 0, height }); ``` Re-export rather than duplicate: `sk.math.clamp = std.math.clamp`, and `lerp` stays `tween.lerp` (it already splats). **Cost:** Vec2 + `sk.math` + Affine lift is about 250 lines with tests, about 1 day. Vector leaf flattening: 1 hour. --- ## 4. Drawing vocabulary: circles, lines, polylines, polygons, transforms ### What the hosts can do now - Commands (`src/abi.zig:225-300`): `clear`, `rect`, `image`, `text`, `clip`, plus GPU/compute. - **Native:** `src/host/gfx.zig:112-148` executes 2D commands on an `SDL_Renderer` created on the SDL_GPU device (`Host.zig:110-116`; it falls back to any renderer without a GPU). The vendored SDL 3.4 has `SDL_RenderGeometry` / `SDL_RenderGeometryRaw` (colored triangles, optional texture), `SDL_RenderLines` (1 px only), and `SDL_RenderTextureAffine` (an image under an arbitrary affine transform), all in `zig-pkg/sdl-*/include/SDL3/SDL_render.h:2331, 2458, 2491`. The SDL renderer has **no MSAA**, so anything not axis-aligned is aliased unless the geometry carries its own feathered fringe (ImGui/NanoVG style). - **Web:** `web/host.js:441-485` draws into a 2D canvas, which has native antialiased `moveTo/lineTo/arc/ellipse/fill/stroke/setTransform`. It has no per-vertex colour: Canvas2D cannot shade triangles. - **GPU passes** (`abi.gpu.Pass`) run on SDL_GPU and WebGPU alike. That is what the vector module uses. ### Options and costs **A. Shape commands, rasterized natively by each host (recommended).** Add one command, `path`, and let each host draw it its own way: ```zig // abi.Command /// A polyline or polygon in canvas coordinates, filled and/or stroked. /// `points` is bulk data: scratch, session or store memory. path: struct { points: []const Vec2, // extern {x, y} closed: bool = true, fill: ?Color = null, stroke: ?Color = null, width: f32 = 1, join: enum(u8) { miter, bevel, round } = .miter, cap: enum(u8) { butt, round, square } = .round, }, ``` - **Web:** a `canvas.path(ptr, len, closed, fill_rgba, stroke_rgba, width, join, cap)` import reads a `Float32Array` view of wasm memory, then does `beginPath`/`moveTo`/`lineTo`/`fill`/`stroke`. That is about 25 lines of JS plus 5 in `web.zig` (`submit`, `:175-211`). It is exact and antialiased. - **Native:** tessellate in Zig, then call `SDL_RenderGeometry`: - fill: a fan for convex shapes, ear clipping for simple concave ones; - stroke: per-segment quads plus miter/bevel/round joins and caps; - a 1 px alpha fringe, so edges are antialiased like canvas. Shared Zig, about 300 lines (fill, stroke, fringe, tests). It can reuse `vector/geom.zig` and the join math in `vector/Polygons.zig:153-335`. `gfx.draw` (`gfx.zig:112`) needs an arena parameter for vertices (`Host.zig:303` and `:316` pass `frame_arena`). Converting to `SDL_Vertex` (float colour, `SDL_render.h:89-94`) is one loop. About 40 lines in gfx.zig. Known gap: translucent strokes double-blend where joint triangles overlap (ImGui has the same); canvas does not. - **Frame helpers** (`src/sketch/root.zig`, next to `fill` at `:77`) build points in scratch: ```zig pub const Style = struct { fill: ?Color = null, stroke: ?Color = null, width: f32 = 1, join: ... = .miter, cap: ... = .round, }; pub fn line(f: *Frame, a: anytype, b: anytype, style: Style) void; pub fn polyline(f: *Frame, points: []const Vec2, style: Style) void; pub fn polygon(f: *Frame, points: []const Vec2, style: Style) void; pub fn circle(f: *Frame, center: anytype, radius: f32, style: Style) void; // n from radius pub fn ellipse(f: *Frame, center: anytype, rx: f32, ry: f32, style: Style) void; pub fn arc(f: *Frame, center: anytype, r: f32, from: f32, to: f32, style: Style) void; pub fn strokeRect(f: *Frame, r: anytype, color: anytype, width: f32) void; // replaces ui.outline ``` - **Transform:** a plain field on the Frame value the sketch already holds. It is not a hidden global, and push/pop is `defer`: ```zig pub const Frame = struct { ..., transform: Affine = .identity, ... }; for (s.boids.constItems()) |b| { const saved = f.transform; defer f.transform = saved; f.transform = f.transform.mul(.translate(b.pos.x, b.pos.y)).mul(.rotate(b.vel.heading())); f.polygon(&.{ .xy(6, 0), .xy(-6, -3), .xy(-6, 3) }, ink); } ``` Helpers apply `transform` to points on the CPU before emitting. A rotated `fill` becomes a `path`. `image` gets an optional affine: native `SDL_RenderTextureAffine` (origin, right, down = the matrix columns, `SDL_render.h:2331`); web `ctx.save(); ctx.transform(a,b,c,d,e,f); drawImage; ctx.restore()`. About 15 lines per host. `clip` and `text` take translation and scale only. - **Scale:** 2048 boids is 2048 `path` commands. That is cheap on canvas, and native batches inside SDL. No JSON, unlike GPU passes on the web. - **Total cost for A:** abi 20 lines, Frame helpers + Style + transform 150, tessellator 300, gfx 40, web.zig 10, host.js 40, e2e screenshots. **About 2 days.** **B. Sketch-side tessellation into a `triangles` command.** Native is easy (`SDL_RenderGeometry`, about 30 lines). The web cannot do per-vertex colour in Canvas2D, and filling triangle by triangle leaves antialiasing seams. Only worth adding *later* for meshes (native exact; web approximates with flat-colour paths), not as the shape primitive. **C. Tessellate into a library-owned GPU pass** (one MSAA draw of all shapes, with shaders built like `vector`'s). The look is identical on both hosts (SDL_GPU / WebGPU MSAA), and trails come almost free (section 5). But it requires a GPU (no WebGPU in insecure contexts or on Firefox Linux), draws into a separate image so ordering with `rect`/`text` means layers, and needs a shader build step in the sketch library. **About 3 days.** A good second backend for heavy particle counts, not the first. **D. The vector module, as the NoC helpers do now.** - `Renderer(.gpu)` emits 2 draws per fill and 2 per stroke (`vector/Gpu.zig:63-80`): 4 draws per stroked, filled boid, so 8k draws for 2048 boids, each serialised to JSON on the web (`web.zig:231-280`). - `Renderer(.cpu)` re-rasterizes and re-uploads the whole canvas every frame (`vector/root.zig:118-123`). Both are right for SVG and manim-style work, but heavyweight as the default `circle()`. **Recommendation:** A now; C later as an opt-in "many shapes" backend. --- ## 5. Persistence of the frame (trails, no `background()`) ### Facts - **Native** clears the window every frame (`Host.zig:285-287`) and presents a swapchain whose old contents are undefined. Nothing persists without an offscreen target. - **Web:** the 2D canvas keeps its pixels between frames unless the sketch clears or `fit()` resizes (`host.js:21-31`). So web "persists" by accident, and the hosts disagree. - **GPU passes with `.clear = null`** keep the image's previous contents (`abi.zig:440`): - Web honours that even with MSAA: the msaa attachment is stored and loaded (`host.js:221-235`). - **Native does not when `samples > 1`:** `gpu.zig:214` forces `LOADOP_CLEAR` for multisampled passes. That is a host divergence. The fix is `SDL_GPU_STOREOP_RESOLVE_AND_STORE` and `LOADOP_LOAD` on the msaa texture when `clear == null` (about 5 lines). - `random_walk.zig` works around all this by keeping a 28 KB bitset in State and re-uploading 900 KB of RGBA every frame (`:19`, `:48-53`). That is deterministic but heavy. - When paused, `draw` still runs every frame (`Host.frame`, `:228-242`). Naive accumulation therefore keeps adding the same shapes while paused, and after a seek the accumulated picture belongs to another timeline. ### Proposal: `target` command + `sk.Layer` ```zig // abi.Command /// Commands after this draw into `image` (from Host.newImage), or the canvas again with null. target: ?Image, ``` - **Native:** `SDL_SetRenderTarget(renderer, texture)`. Restore to `self.offscreen` when headless (`Host.zig:524-535`), else NULL. Reset the clip rect on every switch. `Images.new` (`gfx.zig:44-48`) must create `SDL_TEXTUREACCESS_TARGET` textures (or add `newCanvas`). Verify that `SDL_UpdateTexture` (`.pixels`) still works on target textures, and how logical presentation and render scale apply per target in SDL 3.4: a 10-line experiment. `.clear` calls `sk_text_begin_frame` (`gfx.zig:115`), which flushes first (`vendor/text.c:105-113`), so it is safe. Text density inside a target needs checking (`text.c:115`). - **Web:** `newImage` already makes a 2D canvas per image (`host.js:427-431`). `target(id)` switches the `ctx` the canvas imports draw with (make it `let`). Identity transform for image canvases, `fit()`'s scale for the main one. About 15 lines. - Make sure `.image` of the *current* target is refused, since you can't sample what you're drawing. ```zig /// Session: an accumulating picture. A presentation cache, not state: it /// restarts after a seek, a replay or a reload, and adds nothing while paused. pub const Layer = struct { image: Image = .none, w: u32 = 0, h: u32 = 0, /// The state step drawn last. drawn: u64 = 0, /// Starts drawing into the layer; false when `step` has not moved on. /// Clears on first use, on size change, and when `step` went backwards. pub fn begin(l: *Layer, f: *Frame, step: u64, clear: Color) bool; /// Back to the canvas, and shows the layer at `dst`. pub fn end(l: *Layer, f: *Frame, dst: anytype) void; }; ``` ```zig // NoC 0.1 random walk, without a bitset in State: pub const State = struct { walker: sk.Vec2 = .xy(320, 180), rng: std.Random.DefaultPrng = .init(1), clock: sk.Clock = .{}, /// Every position since the last draw could have missed: steps are /// fixed-rate, frames are not. recent: sk.Ring(sk.Vec2, 64) = .{}, }; pub fn draw(s: *const State, ss: *Session, f: *sk.Frame) void { if (ss.trail.begin(f, s.recent.pushed, .white)) { var it = s.recent.since(ss.trail.drawn); while (it.next()) |p| f.fill(.{ .x = p.x, .y = p.y, .w = 1, .h = 1 }, .black); } ss.trail.end(f, .{ .x = 0, .y = 0, .w = 640, .h = 360 }); } ``` `Ring.since` is what makes it exact: at 30 Hz display and a 60 Hz step, every step is still drawn. For p5's `background(0, 12)` fading trails, draw a translucent full-canvas `fill` into the layer first. Known 8-bit residue: the fade never reaches pure black. Document it. For pictures that must be exact under seek (sand piles, CA history), keep the data in State (bitset or `List`) as `random_walk` does. The Layer is the cheap answer for everything else. **Cost:** abi 3 lines, gfx/Host 30, web 20, Layer + Ring 80, native MSAA load fix 5. **About 1 day.** --- ## 6. What to lift from the game and the NoC helpers | Where | What | Lift as | | --- | --- | --- | | `helpers_a.zig:17-27` (both batches needed it; B is frame-rate dependent without it) | 60 Hz fixed step from tick dt, clock in State | `sk.Clock = struct { carry: f64 = 0, steps: u64 = 0, pub fn advance(c: *Clock, in: *const Input, hz: f32) u32 }`, used as `for (0..s.clock.advance(in, 60)) \|_\| step(s);` | | `flocking.zig:128-135` and three more | `paint(...) catch \|err\| f.host.print(...)` wrappers | Let `draw`/`init`/`update` return `!void`. In `Glue` (`root.zig:282-292`): if the return type is an error union, log `"{name}: {t}"` through `host.print`. About 8 lines. Frame drawing methods stay infallible (they already log OOM, `root.zig:65-67`). | | `ui.zig:16-18` | `rect(x, y, w, h)` constructor | decl literal `sk.Rect.xywh(x, y, w, h)`, so `.xywh(...)` where the type is known | | `ui.zig:20-25` | outline as 4 fills | `f.strokeRect` / `path` with `stroke` | | `ui.zig:88-105` | tail as 96 rects | `f.polyline(points, .{ .stroke = pink, .width = 3 })` | | `ui.zig:30-35`, used by computer/lock/inventory/portrait/dialogue | press-and-release-on-same-target click | `sk.Press(Target)`: `pressed: T = none`, `fn click(p, target, e) bool`. Every scene's `pressed: Target = .none` + `ui.clicked` call becomes one field and one method. | | `ui.zig:37-64` | beveled button | stays game-side (it's a look), but motivates `sk.Press` | | `dialogue.zig:38-50`, `Choice` `:26-34`, `room.zig:75-92`, `tracker.zig:30` | `[N]T` + `len` everywhere, `[N]u8` text + `len` | `sk.List(T, N)`; `sk.List(u8, N)` with `appendSlice`/`set(text)` for bounded strings | | `assets.zig:150-243`, `sounds.zig:69-104` | lazily loaded catalogue keyed by a comptime-generated enum, in Session | `sk.Images(Id)` / `sk.Sounds(Id)` over `std.EnumArray(Id, Image)` plus a `loaded` bitset, with `get(host, id)` and `check(host) usize`. `std.EnumArray` is the std idiom here. | | `sounds.zig:50-67` | per-bank serial counters + active bits to retrigger voices | a `sk.Cue` (serial: u16, `fire()`) in State, taken by `f.voice(.{ .serial = s.cue.serial, ... })`; this generalises `sk.Request` (`request.zig:11`) | | `ui.zig:68-84` | damped follower advanced per event | an example, not library (NoC chapter 3 springs cover it) | | `room.zig:69-71` | rect scaled from source-image pixels | `sk.shape.scale(r, k)` next to `inset`/`offset` (`shape.zig:126-135`) | | `flocking.zig:131-134` | timing draw with `host.clock()` + env flag | host overlay `overlay timing`: the host already knows each draw's duration | ### API-shape proposals from std conventions - **Decl literals:** `.empty` for containers (`List`), `.init(seed)` for things that need arguments (PRNG, `Classic`), `.zero`/`.identity` for values (`Vec2`, `Affine`), and `Color.gray(v)`, `.rgb()`, `.hsv()`, `.hex()` constructors. These only work where the parameter is *typed*. With `anytype` (`shape.color`, `shape.zig:94`), `f.clear(.gray(51))` fails to compile ("not a function") [verified]. Two cheap fixes: 1. `shape.color` maps an enum literal to a `Color` declaration (`@field(Color, @tagName(c))`), so `f.clear(.black)` works [verified]; 2. new APIs take `Style`/`Color` typed (`Style.fill: ?Color`), so `.{ .fill = .gray(127) }` works. - **Options structs** with defaults, as std does (`std.ArrayList.initCapacity` aside, see `Io.Dir.OpenOptions`): `f.image(img, dst, options: anytype)` (`root.zig:81`) is the only `anytype` options parameter left. Type it as `struct { src: ?Rect = null, tint: Color = .white, transform: ?Affine = null }` for ZLS completion and better errors, as `audio`/`pixels`/`download` already are (`:113-157`). - **Errors:** container ops return `error.OutOfMemory` like the `*Bounded` ArrayList methods, so `try`/`catch {}` reads the same as std. - **std.Io:** don't hand sketches an `Io`. `Host` (`abi.zig:445-531`) is already the explicit capability object, it covers what sketches need (files, clock, env), and the web has no `Io` implementation. Keep `Io` out of `update` above all: its randomness and clock are nondeterministic. - **SPIR-V (brief):** 0.17 has `std.spirv` (builtins as `addrspace(.input)` externs, `spirv.zig:1-25`), `callconv(.spirv_vertex/.spirv_fragment/.spirv_kernel)` (`lang.zig:382-384`) and `@SpirvType`. The interest for this design is that a Zig shader could share `sk.Vec2`/vertex structs directly with option C's shape pipeline. But web still needs WGSL via naga, which the GLSL path already does. Left to the shader research. --- ## Cross-check against the other research (board.md) - **research-love P2 `Command.shape`** (one colour, pre-transformed triangles that don't overlap, plus an optional alpha fringe; the web fills them as one nonzero path): **I adopt it in place of my `path` command (option A).** - Tessellation stays in the hot-reloadable library, both hosts get the same geometry, and the host side is about 30 lines each. gfx.draw needs an arena parameter (`Host.zig:303,316`). One fill per shape on the web has no seams. - Risk to test: strip-tessellated strokes fold back on the inner side of acute joins. The flipped, opposite-winding triangles cancel under nonzero on the web (a hole) and double-blend natively. Compute inner-join points, falling back to bevel when the miter passes the segment ends, and add a translucent zig-zag e2e screenshot on both hosts. - My section 4 frame helpers (`line/polygon/circle/...`, `Style`, `f.transform` with `defer`) still hold; research-love's `Pen` value (`translated()` returns a copy) is the same idea. Either works; the Pen copy needs no `defer`. - **research-love P4 `sk.Rng{ s: [4]u32 }` integer-only**, and research-p5's "pin the PRNG": agree on owning the generator, because a std release could change `DefaultPrng` or `Random.float` under saved recordings. Float parity is *not* the reason: std floats already match bit for bit across hosts (section 2). Two corrections: 1. the `s` array is not visible to `get`/`set` today (`fields.zig:22,47`) until arrays become indexed leaves (section 1); 2. noise needs a `seed` parameter (`simplex2(x, y)` has none), because flow_field reseeds on click (`flow_field.zig:91`). - **research-love P10 `sk.Bounded` and `sk.v2` over `@Vector`**: - `Bounded` = my `List`: same migration hazard (verified), so it needs element-wise migration and clamped `items()`. - `sk.v2` is fine as compute functions, but don't recommend `@Vector` *storage* in State: it is 16 B in Debug on x86_64 and opaque to get/set/expect. Store `extern Vec2`, or at least split vector leaves into `[0]`/`[1]`. - **research-love P6 targets + `Input.jumped`**: adopt `jumped` in place of my step-went-backwards heuristic. Keep the two extra rules from section 5: no accumulation while paused, and `Ring.since` for skipped steps. - **Coordinator: element-wise migration is the real gap**: confirmed by running the real `memory.migrate` (section 1). - **Owner: knobs in build.zig.** These host constants are hardcoded today: - `slot_count = 8` and `header_len = 64 KiB` (`memory.zig:21-22`); - `store_base` and `store_reserve = 64 GiB` (`:318-320`); - the web event queue `[1024]Event` (`web.zig:74`); - `keep_frames = 300` and `staging_size = 4 MiB` (`gpu.zig:13,108`); - and a `use_llvm` choice for Debug sketch libs, which fixes `@Vector`'s layout. These belong in `sketchbook.init(b, .{ ... })` (`build.zig:202`) as a generated options module. Algorithm choices (noise flavour, PRNG) stay as explicit calls in code, not build-global modes. --- ## Ranked proposals | # | Proposal | Cost | Removes | | --- | --- | --- | --- | | 1 | `Command.shape` (research-love P2; replaces my `path`) + lib tessellator + `f.line/polyline/polygon/circle/ellipse/arc/strokeRect` / Pen + `Style` + transform + image affine | ~2 days | both `Pen`s, the vector-module dependency for basic shapes, `ui.outline`, the 96-rect tail | | 2 | `sk.List(T, cap)` (clamped `items()`, std bounded naming) + `sk.Ring` | ½ day | helpers_b List, every `[N]T + len` in the game | | 3 | Element-wise array migration (repeat leaves, prefix copy, indexed paths) | ~1 day | particle wipes and zombie `len` on reload; protects tracker songs | | 4 | `sk.Vec2` extern struct with PVector methods + `sk.math` (`remap` with ranges, `smoothstep`, `fract`, `angle`) + `sk.Affine` lifted from `vector.geom`; flatten `@Vector` leaves | ~1 day | both batches' PVector helpers, `p[0]` indexing, uninspectable vector state, backend-dependent 16-byte vectors | | 5 | Randomness: own pinned generator (`sk.Rng`, research-love P4, Xoshiro/PCG with our own `float`), or `std.Random.Xoshiro256` by concrete name, never the `DefaultPrng` alias; free helpers `range/gaussian/unit/pick/stream` | 2 h | `range`/`random` helpers | | 5b | Build options for hardcoded host constants (snapshot slots, header size, store reserve, web event queue, gpu cache/staging, Debug backend) | ½ day | owner's "knobs in build.zig" | | 6 | `sk.noise`: table-free `perlin2/3`, `fbm` with options, `hash01`, Processing-exact `Classic` | ½ day | both noise ports | | 7 | `target` command + `sk.Layer` (+ native MSAA `clear = null` fix) | ~1 day | random_walk's bitset + full re-upload; host divergence | | 8 | `sk.Clock` fixed step | 1 h | `steps60`; batch B's refresh-rate-dependent speed | | 9 | Fallible `draw`/`update`/`init` logged by Glue; typed options; decl-literal colours (`.black`, `.gray(v)`) | 2 h | four `paint` wrappers; `anytype` papercuts | | 10 | Game lifts: `sk.Press(T)`, `sk.Images(Id)`/`Sounds(Id)` over `std.EnumArray`, `sk.Cue` | ½ day | per-scene click bookkeeping, asset library boilerplate |