# sketchbook, iteration 1: design Merged from the 12 Nature of Code ports (friction-a/b.md), three research notes, two adversarial critiques (critique-core.md, critique-zig.md), the shader pass (../../shaders/README.md) and board.md. Nothing here is built yet; `lib/sketchbook` is untouched. ## Principles (owner) - The deterministic core stays: State is plain data, `update` sees only State and Input and is replayed, `draw` emits commands as data, and both hosts run every command. - The new API is a **layer on top**, Zig-style (`std.posix` under `std.Io`). Today's `abi.Command`, `f.emit`, GPU passes, `Input.events` and Frame methods stay as they are. The new layer is sketch-library code with no hidden state that hands its intermediate data out: a Pen yields triangles you can emit yourself or feed to your own GPU pass. - Build knobs live in `build.zig`, but the critics drew a line: **a build option must not change what `update` computes or the state-file format** (a `-D` noise flavour or snapshot count makes a recording or a state file mean something else). Knobs that pass this test: test optimize mode, shader language, web/PWA, tools. ## What the ports showed - Both porters independently wrote the same ~200-line helper file: circles/lines/stroke under a transform through the `vector` module, PVector ops, a PRNG in State, Perlin noise, a fixed-capacity list, a fixed-step clock. 9 ports need filled/stroked circles, 3 need line segments, 2 need convex triangles, 3 need translate·rotate, 4 need alpha. Nothing used arcs, blend modes, HSV, image transforms, or randomness in `draw`. - **Three host bugs** surfaced, each found independently by more than one agent and confirmed by experiment: 1. Seek feeds the whole recording to **one** `update`, with mouse/key state as of the batch's end. `accel_to_mouse` ends at (581, 311) by playback but (350, 195) by `seek end`. Slow-frame playback batches too. `in.dt`/`in.now` are wrong during replay (Host.zig:229-246). 2. Input state is not part of snapshots/recordings: a replay after a live mouse move ends at (163, 102) instead of (581, 311). 3. Arrays are opaque migration leaves: change an element type or a capacity and the array resets to `undefined` while its `len` is kept, giving garbage elements, or a panic on shrink. The game's tracker songs are exposed the same way. Separately, a state file the host doesn't recognise is **truncated** on open (memory.zig:129). ## Disagreements, decided | Question | Decision | Why | | --- | --- | --- | | `Command.shape` payload: `triangles` (critic-zig) or `points + ends + indices` (critic-core) | **`{ color, points, ends, indices }`** | Measured: Canvas2D fills a triangle soup 3.6× slower than the outline (1000 circles: 11 vs 3 ms), and seams between separately filled triangles show. The web fills the subpaths as one nonzero path; native passes points+indices straight to `SDL_RenderGeometry`. The library guarantees positive winding and disjoint triangles. | | `Vec2` struct with methods (research-zig) or `@Vector(2, f32)` | **`@Vector`** + host splits vector lanes into leaves | `+=` stays; one type with the shaders (`vec2`). The real problems (unreadable in console/scripts, Debug's 16-byte layout resetting on `-Doptimize`, padding garbage in `diff`) are fixed in the host by lane leaves and leaf-wise compare. | | `Rng` wrapper / own PCG32 vs std generator | **`std.Random.Xoshiro256` (concrete, never `DefaultPrng`) in State, plus a build stamp in recordings** | No wrapper earns its lines (`std.math.lerp(lo, hi, r.float(f32))`). The concrete type can't silently change via the `DefaultPrng` alias, and the stamp warns when a recording is played against a different build. Open question below if you want our own algorithm anyway. | | Clock cap (≤ 8 steps/call) | **Keep the cap, after the per-tick host fix** | With one `update` per tick, the cap depends only on the recorded tick, so it replays identically; it prevents the spiral of death after a stall. Before the host fix every Clock design is wrong. | | AA fringe on shapes | **No fringe** | It halves 1 px line intensity on the web (128 vs 255). Native shapes are aliased like `rect` today; see open questions. | ## Iteration 1, in order Each step ships with its tests (details in critique-core §3). **A. Host behaviour (no API change)** 1. One `update` per tick: playback, seek and step deliver whole frames; `in.dt`/`in.now` come from the tick in both live and replay (so they match bit for bit); Input is reset and re-seeded on record start and snapshot restore. Tests: play-vs-seek-vs-step equal the stop snapshot; replay after a live move equals the first replay. 2. Inspection: `@Vector` lanes and array elements become addressable leaves (`get/set/expect pos[0]`, `boids.buffer[3].pos[1]`), `diff` compares leaf by leaf, and script `expect`/`await` take `~tol`. This removes the 8 State fields the ports added only for their tests. 3. Element-wise array migration (copy shared elements field by field, enums by name, clamp on shrink), with a reader for today's state files. Never truncate an unrecognised file; refuse it instead. Fixture: a copy of `drat-meout.state` keeps every value. **B. The one new host primitive** 4. `Command.shape { color, points: []const [2]f32, ends: []const u32, indices: []const u32 }`: one SDL_RenderGeometry call natively, one nonzero path fill on the web. Tests on both hosts: overlapping translucent circles, a concave polygon, an acute translucent zig-zag stroke (no holes, no double blend), a 1 px line, and 5000 circles under 16 ms on the web. **C. The new layer (sketch library; pure, no state of its own)** 5. `sk.math`, one geometry module shared with `vector`: `Vec = @Vector(2, f32)`, `scale`, `distance`, `withLength` (setMag), `clampLength` (limit), `angle` (heading), `unit` (fromAngle), `Affine.place(at, radians)`, `noise(seed, x, y, z)` (table-free, golden values equal on native and wasm). The README gets a PVector-name table. 6. `sk.draw`, two levels: - L1: `fillCircle`, `strokeCircle`, `fillPolygon`, `strokePolygon`, `strokeLine`. Each appends to a caller-owned `sk.draw.Tessellation` (points, ends, indices), using a caller-given allocator, with an `Affine`. - L2: `Pen { fill: ?Color, stroke: ?Color, width, xf }` as plain data, where `pen.transformed(m)` is the push. `sk.draw.circle/line/polygon(f, …, pen)` tessellate into scratch memory and emit `shape`; on out-of-memory they log and drop, like `Frame.emit`. Radius, not diameter. One colour type (`abi.Color`, with `Color.gray(v)`). 7. Root: `sk.Clock { hz, owed, count, steps(in) }` and `sk.List(T, cap)` with std names (`appendBounded`, `orderedRemove`, `swapRemove`, `slice`, `constSlice`), clamped, defaulting to `@splat(.{})` (not `zeroes`: enums without a 0 tag). **D. Parity fixes and tooling** 8. Web image tint keeps RGB (it keeps only alpha today); native MSAA passes with `clear = null` load (clearing on first use, since Vulkan starts undefined and WebGPU zeroed). 9. Recordings carry the sketch build hash; `play` warns on a mismatch. 10. Build/harness: - `addZigShaders` moves into sketchbook's build.zig, with the SPIR-V fix-up tool (from sketches/shaders). - An e2e optimize option. - Concurrent e2e runs get unique store paths. - Fix the teardown segfault on the store-busy path (Host.zig:118). - Investigate `LeakedSdlMemory` under parallel e2e (−j1 passes 12/12). **E. Then:** rewrite the 12 ports on the new layer, delete helpers_a/b.zig, and compare line counts (critic-zig estimates 778→~640 in the ports and 296→~25 in the helpers). At least one port (flocking) drops to L1/L0 to batch 1000 boids into 2 commands. ## Deferred (no port needs it yet) Offscreen targets, `jumped`, Layer/Ring for trails (2 ports, both with workarounds that stay correct after a seek), blend modes (SDL's multiply differs from Canvas for α<1), colour spaces, image affines, textures in GPU passes, `Draw.instances` (safe whenever wanted), arcs/ellipses/joins, input sugar, fallible `draw`, host constants as build options (never as compile-time file-format constants). ## Open questions for the owner 1. **Native antialiasing.** Canvas2D antialiases shapes; SDL_RenderGeometry does not, so native circles look jaggier than the same sketch on the web. Accept it for iteration 1, or add an MSAA SDL_GPU pipeline for `shape` on the host (no API change)? 2. **RNG.** Concrete std `Xoshiro256` plus the build stamp, or our own pinned generator (PCG32) so recordings survive Zig upgrades? 3. **Processing-exact noise.** One sketchbook noise in the library, with porter-a's exact Processing `noise()` kept in the noc project for faithful ports. Fine? 4. **Order.** A (host fixes) first is safest, since it changes behaviour under your existing recordings and the game. Or start with B+C to see the ports shrink sooner? ## Decisions taken (owner delegated them) 1. Native shapes ship aliased in iteration 1; antialiasing becomes a phase-3 feature, driven by the recursive tree (thin lines). 2. RNG: `std.Random.Xoshiro256` used directly in State, plus the build stamp on recordings. 3. One table-free noise in the library; porter-a's Processing-exact `noise()` stays in the noc project. 4. Order: iteration 1 (host fixes + drawing layer, built in parallel by core-host and draw-layer), then rewrite the 12 ports on it, then phase 3. ## Phase 3: new examples that need the deferred features Each feature is built only together with an example that needs it, and the example is written from scratch on the new API. | Example (NoC 2nd ed.) | Feature it drives | | --- | --- | | 4.8 Image texture system: smoke | `imageMode(CENTER)`-style placement, image tint alpha on both hosts, Gaussian random (`std.Random.floatNorm`) | | 4.9 Additive blending | blend modes (`alpha`, `add`), with SDL vs Canvas parity tests | | 8.6 Recursive tree | recursion over `Pen.transformed`, stroke width from the mouse, native antialiasing for thin lines | | 8.5 Koch curve | data that grows 4× per click: `List` capacity vs Store-backed growth | | 8.9 L-system | strings that grow to thousands of characters: State vs Store, turtle push/pop | | 5.8 Path following | translucent thick polylines with joins (miter/round/bevel), `noFill` shapes | | 5.13 Quadtree | stroked rects, points, thousands of shapes per frame | | 5.12 Bin-lattice separation | 2000 boids: batching/instancing performance | | 11.1 Flappy bird | text, game loop, restart: game-style structure | | 0.1/0.6 walkers (rewritten again) | offscreen targets + `Input.jumped` for trails, replacing the Session-repaint workaround | ## Acceptance: live reload, per example (owner) Every example (the 12 rewritten ports, the phase-3 examples, the Book of Shaders sketch) must hot-reload both its Zig code and its shaders with State kept. Checked automatically, not by hand: - `App.addReloadCheck(.{ .script, .edits })` in sketchbook's build.zig builds the library twice: as written, and from a copy of the sources with textual `edits` applied (`.{ .file, .old, .new }`, failing the build if `old` is not found exactly once). It runs the script through the generic host with `{v2}` defined as the second build. - Each example's reload script plays a while, takes a screenshot, checks State fields, runs `load {v2}`, checks that the same State values carried over, plays on, and takes a second screenshot. A compare step asserts the screenshots differ where the edit should show. - Each example declares one code edit (e.g. a color or a force constant in `draw`/`update`). Shader examples also declare one shader edit, in Zig and in GLSL. - Checked once by hand: the file watcher path (`zig build run` with `zig build lib --watch`) on one example, editing a Zig shader. ## Acceptance: timeline, per example (owner) Every example must scrub correctly: pause, go back, replay. Each example gets a timeline script that: 1. records its own interaction (clicks, drags, keys) for a few seconds, then stops and snapshots slot N; 2. `play`s to the end, and the state equals slot N exactly (leaf by leaf, no tolerance: this is the determinism claim); 3. `seek`s to the end, and to the middle then plays on: both equal slot N; 4. `step`s back and forward and lands on the same frames; 5. pauses for a while: State does not move (`draw` must not change it); 6. replays after a live mouse move: equals the first replay (critic-core E2); 7. screenshots after a seek and compares with the live screenshot at the same point. This catches draw-side caches (trails) that the state check cannot see; the walkers' trails must pass it once phase 3 adds targets and `Input.jumped`. Script support (core-host): `expect-snapshot N` (live state equals slot N, leaf-wise, reporting the first differing leaves) and screenshot equality (shared compare tool with draw-layer's reload check). ### Phase 3 addition: vector GPU backend draw count (from perf.md) fix1–3 (pipeline looked up once per pass, redundant state calls skipped, one vertex binding) are applied in lib/sketchbook. What's left is ~0.6 µs of driver CPU per draw, and the vector GPU backend issues 2 draws per filled shape. Cut the draw count: convex single shapes drawn directly (no stencil), and fills with disjoint bounds batched into one stencil + one cover draw. Driven by 5.13 Quadtree / 5.12 Bin lattice when drawn through `vector`, and measured with perf.md's bench.