animader-cli 0.0.0-stage → 0.1.1

package/starters/circle/README.md

@@ -0,0 +1,50 @@
+# An Animader project
+
+This folder was created by `animader new` with the circle starter: one
+circle kernel, an eight-second path with beat pulses, and a complete
+timeline. Three authored files carry the piece:
+
+- `program.sjon` — the GPU program: the buffers, the circle kernel and
+  the passes that run each frame.
+- `timeline.piece.sjon` — the musical timeline: tempo, meter, sections
+  and the lanes that animate the program's fields.
+- one soundtrack file — `soundtrack.wav`, the labeled test tone (not
+  music).
+
+## Host duration
+
+`animader.json` holds the host settings. `seconds` is the real playback
+length the host uses. The musical lengths inside the timeline (bars,
+beats, tempo) are musical time; the host plays the `seconds` it finds in
+`animader.json`, or an explicit `--seconds` you pass.
+
+## The workflow this project is shaped for
+
+`animader dev` (play the project while you edit), `animader build`
+(validate and write the generated output) and `animader export --out dist`
+(write a standalone release to a fresh folder) are the commands this
+layout targets. They are provided by the `animader` CLI — run
+`animader --help` to see which commands your version provides.
+
+## Editing
+
+Edit `program.sjon` or `timeline.piece.sjon` in any editor. The dev
+server keeps running until you stop it: press Ctrl-C in its terminal
+before running other project commands.
+
+## Replacing the soundtrack
+
+Move your own audio into this folder as `soundtrack.wav`,
+`soundtrack.ogg` or `soundtrack.opus`. Exactly one recognized soundtrack
+may exist here at a time, so move the replaced file out of the project
+yourself — the host never deletes author audio. The generated
+`soundtrack.wav` is a labeled test tone, not music.
+
+## Generated output and exports
+
+`out/` holds generated build output. `.gitignore` already ignores
+`out/`, the default `dist/` export, its staging directory and its
+detached size report; an export to another name needs matching ignore
+entries of its own (for `--out release`: `release/`, `release.next`,
+`release.size.json`). Exports write to a fresh folder and never
+overwrite an existing one.

package/starters/circle/animader.json

@@ -0,0 +1,4 @@
+{
+  "format": "animader-project/1",
+  "seconds": 8
+}

package/starters/circle/gitignore

@@ -0,0 +1,9 @@
+# Generated build output.
+out/
+
+# The default export destination, its staging directory and its detached
+# size report. An export to another name needs its own ignore entries,
+# for example release/, release.next and release.size.json for --out release.
+dist/
+dist.next
+dist.size.json

package/starters/circle/kernels/circle.wgsl

@@ -0,0 +1,32 @@
+struct Params {
+  beat: f32,
+  scene: f32,
+  x: f32,
+  radius: f32,
+}
+struct Inputs {
+  time: f32,
+  width: f32,
+  height: f32,
+  aspect: f32,
+}
+@group(0) @binding(0) var<uniform> params: Params;
+@group(0) @binding(1) var<uniform> inputs: Inputs;
+
+@vertex
+fn vs(@builtin(vertex_index) i: u32) -> @builtin(position) vec4f {
+  let x = f32(i & 1u) * 4.0 - 1.0;
+  let y = f32(i >> 1u) * 4.0 - 1.0;
+  return vec4f(x, y, 0.0, 1.0);
+}
+
+@fragment
+fn fs(@builtin(position) pos: vec4f) -> @location(0) vec4f {
+  let uv = pos.xy / vec2f(inputs.width, inputs.height);
+  let p = (uv - vec2f(params.x, 0.5)) * vec2f(inputs.aspect, 1.0);
+  let aa = 1.0 / inputs.height;
+  let pulse = 1.0 + 0.15 * (1.0 - smoothstep(0.0, 0.30, fract(params.beat)));
+  let r = params.radius * pulse;
+  let circle = 1.0 - smoothstep(r - aa, r + aa, length(p));
+  return vec4f(mix(vec3f(0.96, 0.95, 0.92), vec3f(0.12, 0.12, 0.15), circle), 1.0);
+}

package/starters/circle/program.sjon

@@ -0,0 +1,34 @@
+; program.sjon — the circle program from TUTORIAL.md step 4: one fullscreen
+; triangle, one fragment-shaded circle, one pass per frame. The defaults
+; feed Params in kernels/circle.wgsl in order: beat, scene, x, radius.
+
+(data :name defaults :float32 [0.0 0.0 0.20 0.045])
+(buffer :name params :usage [uniform copy-dst] :data defaults)
+
+(buffer :name inputs :size 16 :usage [uniform copy-dst])
+(queue :name writeInputs
+  (write-buffer :buffer inputs :offset 0 :data pngine-inputs))
+
+(shader-module :name circleCode :file "kernels/circle.wgsl")
+
+(render-pipeline :name circlePipe :layout auto
+  (vertex :module circleCode :entry vs)
+  (fragment :module circleCode :entry fs
+    (color-target :format preferred-canvas-format))
+  (primitive :topology triangle-list))
+
+(bind-group :name circleBinds :layout circlePipe :group 0
+  (entry :binding 0 :buffer params)
+  (entry :binding 1 :buffer inputs))
+
+(render-pass :name picture
+  (color-attachment :view context-current-texture
+    :clear-value [0.96 0.95 0.92 1.0]
+    :load-op clear :store-op store)
+  :pipeline circlePipe
+  :bind-groups [circleBinds]
+  (draw :vertex-count 3))
+
+(frame :name main
+  :before [writeInputs]
+  :perform [picture])

package/starters/circle/timeline.piece.sjon

@@ -0,0 +1,26 @@
+; timeline.piece.sjon — TUTORIAL.md steps 5 and 6: four bars of 4/4 at
+; 120 qpm (eight seconds), the score's beat handed to the shader, the
+; circle's journey across the canvas and its radius pulse on every beat.
+
+(animader :name circle-journey :version 1
+  :default-world live :worlds [live])
+
+(world :name live
+  :time live :params defaults :input live :viewport [1280 720]
+  :assets project :state live)
+
+(timeline :title "A circle, for now" :length 4bar :end hold)
+(tempo-point :at 0q :qpm 120)
+(meter-point :at 0q :sig [4 4])
+(section :name one :at 0bar :dur 4bar)
+
+(lane :name beat-ramp :kind formula :target beat :expr beat)
+
+(lane :name journey-x :kind curve :target x
+  (keyframe :at 0b :value 0.20 :ease linear)
+  (keyframe :at 16b :value 0.80 :ease linear))
+
+(lane :name size :kind curve :target radius
+  (keyframe :at 0b :value 0.045 :ease linear)
+  (keyframe :at 8b :value 0.080 :ease in-out-sine)
+  (keyframe :at 16b :value 0.045 :ease in-out-sine))

package/starters/ember/kernels/curl.wgsl

@@ -0,0 +1,10 @@
+// The curl of a simplex field: a divergence-free velocity, the thing
+// `evolve`'s `(curl :scale s :amount a)` step samples. Two finite
+// differences of the scalar field, rotated a quarter turn.
+fn curl(p: vec2f, scale: f32, t: f32) -> vec2f {
+  let e = 0.01;
+  let q = p * scale + vec2f(t * 0.15, -t * 0.11);
+  let dx = simplex(q + vec2f(e, 0.0)) - simplex(q - vec2f(e, 0.0));
+  let dy = simplex(q + vec2f(0.0, e)) - simplex(q - vec2f(0.0, e));
+  return vec2f(dy, -dx) / (2.0 * e);
+}

package/starters/ember/kernels/ember.wgsl

@@ -0,0 +1,10 @@
+// The author's own kernel: a colour for a particle from its speed, black
+// body from a deep red through orange to a pale yellow, the way an ember
+// brightens when it moves.
+fn ember(speed: f32) -> vec3f {
+  let s = clamp(speed * 6.0, 0.0, 1.0);
+  let cold = vec3f(0.55, 0.08, 0.02);
+  let warm = vec3f(1.0, 0.45, 0.08);
+  let hot = vec3f(1.0, 0.92, 0.6);
+  return select(mix(cold, warm, s * 2.0), mix(warm, hot, s * 2.0 - 1.0), s > 0.5);
+}

package/starters/ember/kernels/hash.wgsl

@@ -0,0 +1,12 @@
+// A small integer hash to [0, 1). PCG-style, deterministic on every
+// device, which is what a seed table wants: the same particle draws the
+// same home on every run.
+fn hash_u32(x: u32) -> u32 {
+  var h = x * 747796405u + 2891336453u;
+  h = ((h >> ((h >> 28u) + 4u)) ^ h) * 277803737u;
+  return (h >> 22u) ^ h;
+}
+
+fn hash(x: u32) -> f32 {
+  return f32(hash_u32(x)) / 4294967296.0;
+}

package/starters/ember/kernels/simplex.wgsl

@@ -0,0 +1,27 @@
+// 2D simplex noise in [-1, 1], Ashima's, the field `haze` ramps and the
+// field `curl` differentiates. `position` in, one value out.
+fn mod289_2(x: vec2f) -> vec2f { return x - floor(x * (1.0 / 289.0)) * 289.0; }
+fn mod289_3(x: vec3f) -> vec3f { return x - floor(x * (1.0 / 289.0)) * 289.0; }
+fn permute3(x: vec3f) -> vec3f { return mod289_3(((x * 34.0) + 1.0) * x); }
+
+fn simplex(v: vec2f) -> f32 {
+  let C = vec4f(0.211324865405187, 0.366025403784439, -0.577350269189626, 0.024390243902439);
+  var i = floor(v + dot(v, C.yy));
+  let x0 = v - i + dot(i, C.xx);
+  var i1 = vec2f(0.0, 1.0);
+  if (x0.x > x0.y) { i1 = vec2f(1.0, 0.0); }
+  var x12 = x0.xyxy + C.xxzz;
+  x12 = vec4f(x12.xy - i1, x12.zw);
+  i = mod289_2(i);
+  let p = permute3(permute3(i.y + vec3f(0.0, i1.y, 1.0)) + i.x + vec3f(0.0, i1.x, 1.0));
+  var m = max(vec3f(0.5) - vec3f(dot(x0, x0), dot(x12.xy, x12.xy), dot(x12.zw, x12.zw)), vec3f(0.0));
+  m = m * m;
+  m = m * m;
+  let x = 2.0 * fract(p * C.www) - 1.0;
+  let h = abs(x) - 0.5;
+  let ox = floor(x + 0.5);
+  let a0 = x - ox;
+  m = m * (1.79284291400159 - 0.85373472095314 * (a0 * a0 + h * h));
+  let g = vec3f(a0.x * x0.x + h.x * x0.y, a0.yz * x12.xz + h.yz * x12.yw);
+  return 130.0 * dot(m, g);
+}

package/starters/ember/program.sjon

@@ -0,0 +1,328 @@
+; program.sjon — the hello piece, written by hand in pngine's forms. The twin
+; of `piece.sjon`, which says the same thing in animader's vocabulary; this
+; file is what the CLI runs. Every place the writing was tedious is a line in
+; TEDIUM.md, with the verb that would have absorbed it.
+;
+;   pngine validate program.sjon
+;   pngine render -f -s 1280x720 -t 1.44 -o out.png program.sjon   ; one tick, at t
+;   pngine inspect program.sjon --deep --phase frame --frames 0,1,10,60 --time-step 0.01 --json
+;
+; The word EMBER is a span table baked by canto (bake/spans.bin). A seed
+; pass draws every particle a home inside the letters; a compute step moves
+; the particles by a curl field, a spring back home and the pointer; a draw
+; paints them as sprites into a texture; a feedback pass keeps their trails;
+; a last pass composes the trails over a haze and tonemaps to the canvas.
+
+; density: the one structural number. `(define …)` reaches every numeric slot
+; and never the WGSL, so the shaders read the buffer's own length instead.
+(define :name N :value 24000)
+
+; --- kernels, checked inside the modules that assemble them ---
+(wgsl :name hash    :file "kernels/hash.wgsl")
+(wgsl :name simplex :file "kernels/simplex.wgsl")
+(wgsl :name curl    :file "kernels/curl.wgsl" :imports [simplex])
+(wgsl :name ember   :file "kernels/ember.wgsl")
+
+; --- the params: PROGRAM defaults in a uniform the world may overwrite ---
+; grain, heat, and two pads. Filled from the data at creation and never
+; written by the frame, so a host write to `params` (the knob, the score)
+; lands and stays. (`:init` takes compute passes only, so a `(queue …)`
+; could not do this once.)
+(data :name paramDefaults :float32 [4.7 0.6 0.0 0.0])
+(buffer :name params :usage [uniform copy-dst] :data paramDefaults)
+
+; --- what the world supplies every frame: time and the pointer ---
+; The struct's members are named t, w, h, asp because the sugar passes
+; below build their own `pngine` uniform with time/width/height/aspect, and
+; a name shared by two buffers makes `setUniform` ambiguous (graph_compose).
+; `ptr` and `target` are reserved words in WGSL; naga says so where
+; wgslender lets `ptr` pass.
+(buffer :name inputs :size 16 :usage [uniform copy-dst])
+(queue :name writeInputs (write-buffer :buffer inputs :offset 0 :data pngine-inputs))
+(buffer :name pointerBuf :size 48 :usage [uniform copy-dst])
+(queue :name writePointer (write-buffer :buffer pointerBuf :offset 0 :data pointer-inputs))
+
+; --- letters: the span table, bytes verbatim, read by the seed pass ---
+(data :name lettersTable (bytes :file "bake/spans.bin"))
+(buffer :name letters :usage [storage] :data lettersTable)
+
+; --- dust: one record per particle, home, position, velocity, seed, pad ---
+(buffer :name dust :size (* N 32) :usage [vertex storage] :pool 2)
+
+; seeds: `pixel → element`. Each invocation draws a cell of the word's
+; coverage, area-weighted, and makes it the particle's home. The table's
+; row cumulative is inclusive (zlug SPN1); row 0 is the top of the box.
+(shader-module :name seedCode :imports [hash] :code """
+struct Particle { home : vec2f, pos : vec2f, vel : vec2f, seed : f32, pad : f32 }
+@group(0) @binding(0) var<storage, read> table : array<u32>;
+@group(0) @binding(1) var<storage, read_write> a : array<Particle>;
+@group(0) @binding(2) var<storage, read_write> b : array<Particle>;
+
+// The bake's box, [0, 3.248] x [-0.244, 0.928] em, as an aspect. Baked
+// into the WGSL because a `(define …)` cannot reach it; see bake/provenance.txt.
+const BOX_ASPECT : f32 = 2.772;
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) id : vec3u) {
+  let i = id.x;
+  if (i >= arrayLength(&a)) { return; }
+  let rows = table[1] & 0xffffu;
+  let cols = table[1] >> 16u;
+  let count = table[2];
+  let total = table[3];
+  let goal = min(u32(hash(i) * f32(total)), total - 1u);
+  // the first row whose inclusive cumulative passes the target
+  var lo = 0u;
+  var hi = rows - 1u;
+  while (lo < hi) {
+    let mid = (lo + hi) / 2u;
+    if (table[4u + mid * 2u + 1u] > goal) { hi = mid; } else { lo = mid + 1u; }
+  }
+  let r = lo;
+  let first = table[4u + r * 2u];
+  var next = count;
+  if (r + 1u < rows) { next = table[4u + (r + 1u) * 2u]; }
+  var before = 0u;
+  if (r > 0u) { before = table[4u + (r - 1u) * 2u + 1u]; }
+  var rem = goal - before;
+  var col = 0u;
+  for (var s = first; s < next; s = s + 1u) {
+    let w = table[4u + rows * 2u + s];
+    let x0 = w & 0xffffu;
+    let x1 = w >> 16u;
+    let width = x1 - x0;
+    if (rem < width) { col = x0 + rem; break; }
+    rem = rem - width;
+    col = x1 - 1u;
+  }
+  let u = (f32(col) + hash(i * 3u + 1u)) / f32(cols);
+  let v = (f32(r) + hash(i * 3u + 2u)) / f32(rows);
+  // title space: the word one unit wide, centred, y up
+  let home = vec2f((u - 0.5) * 1.0, (0.5 - v) / BOX_ASPECT);
+  var p : Particle;
+  p.home = home;
+  p.pos = home;
+  p.vel = vec2f(0.0, 0.0);
+  p.seed = hash(i * 3u + 3u);
+  p.pad = 0.0;
+  a[i] = p;
+  b[i] = p;
+}
+""")
+
+; dust: `element → element`. The curl step scaled by heat, the spring that
+; reassembles the word, the repel from the pointer, in title space, where
+; `title` is the space that rotates with time and carries the user's nudge.
+(shader-module :name stepCode :imports [curl] :code """
+struct Particle { home : vec2f, pos : vec2f, vel : vec2f, seed : f32, pad : f32 }
+struct Params { grain : f32, heat : f32, pad0 : f32, pad1 : f32 }
+struct Inputs { t : f32, w : f32, h : f32, asp : f32 }
+struct Pointer { x : f32, y : f32, clickX : f32, clickY : f32, dx : f32, dy : f32,
+                 buttons : f32, pressure : f32, modifiers : f32, scrollX : f32, scrollY : f32, pad : f32 }
+@group(0) @binding(0) var<uniform> params : Params;
+@group(0) @binding(1) var<uniform> inputs : Inputs;
+@group(0) @binding(2) var<uniform> pointer : Pointer;
+@group(0) @binding(3) var<storage, read> src : array<Particle>;
+@group(0) @binding(4) var<storage, read_write> dst : array<Particle>;
+
+// (space :name title :transform (trs :rotate (* time .05) :scale 1.1) :user (translate [.12 -.03]))
+fn title(p : vec2f, t : f32) -> vec2f {
+  let a = t * 0.05;
+  let c = cos(a);
+  let s = sin(a);
+  let r = vec2f(p.x * c - p.y * s, p.x * s + p.y * c) * 1.1;
+  return r + vec2f(0.12, -0.03);
+}
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) id : vec3u) {
+  let i = id.x;
+  if (i >= arrayLength(&src)) { return; }
+  var p = src[i];
+  let t = inputs.t;
+  // A second is a hundred ticks and this pass runs once per tick, so the
+  // step is a hundredth whatever the paint rate (docs/05-model.md, the tick
+  // and the paint). One frame of the program is one tick; the player steps
+  // the due ticks and paints the last.
+  let dt = 0.01;
+  let goal = title(p.home, t);
+  // (curl :scale 3 :amount heat). The amount is per tick, a hundred a
+  // second: the curl's gradient is order one, and the spring below wins
+  // at rest, so the word breathes and reassembles rather than dissolves.
+  let flow = curl(p.pos + vec2f(p.seed * 0.01, 0.0), 3.0, t) * params.heat * 0.06;
+  // the reassembling: a spring to the home the title space carries
+  let spring = (goal - p.pos) * 6.0;
+  // (repel :from (convert pointer :to title) :radius .18): the pointer arrives in
+  // canvas uv, y down; title space is the sprite space below, y up
+  var repel = vec2f(0.0, 0.0);
+  if (pointer.x > 0.0 || pointer.y > 0.0) {
+    let at = vec2f((pointer.x * 2.0 - 1.0) / 1.3, (1.0 - pointer.y * 2.0) / (1.3 * inputs.asp));
+    let away = p.pos - at;
+    let d = length(away);
+    if (d < 0.18) { repel = normalize(away + vec2f(0.0001, 0.0)) * (0.18 - d) * 30.0; }
+  }
+  p.vel = (p.vel + (flow + spring + repel) * dt) * 0.92;
+  p.pos = p.pos + p.vel * dt;
+  dst[i] = p;
+}
+""")
+
+; sparks: `element → surface`. Every particle as a sprite, its colour from
+; its speed through the author's `ember` kernel, drawn into a texture.
+(data :name quad :float32 [-1.0 -1.0  1.0 -1.0  -1.0 1.0  -1.0 1.0  1.0 -1.0  1.0 1.0])
+(buffer :name quadVB :usage [vertex] :data quad)
+
+(shader-module :name sparkCode :imports [ember] :code """
+struct Inputs { t : f32, w : f32, h : f32, asp : f32 }
+@group(0) @binding(0) var<uniform> inputs : Inputs;
+struct VsOut { @builtin(position) pos : vec4f, @location(0) uv : vec2f, @location(1) color : vec3f }
+
+@vertex
+fn vs(@location(0) home : vec2f, @location(1) pos : vec2f, @location(2) vel : vec2f,
+      @location(3) corner : vec2f) -> VsOut {
+  // (paint … :size .004): title space to clip space, the word 1.3 wide,
+  // which keeps it inside the frame with the title's scale and nudge
+  let size = 0.004 * 1.3;
+  let centre = vec2f(pos.x * 1.3, pos.y * 1.3 * inputs.asp);
+  var out : VsOut;
+  out.pos = vec4f(centre + corner * vec2f(size, size * inputs.asp), 0.0, 1.0);
+  out.uv = corner;
+  out.color = ember(length(vel));
+  return out;
+}
+
+@fragment
+fn fs(in : VsOut) -> @location(0) vec4f {
+  // The deposit per tick. The trails keep 0.965 of it a tick, a hundred
+  // ticks a second, so a still particle sums to about 28 deposits; this
+  // keeps the letters short of white and lets a moving one glow.
+  let d = length(in.uv);
+  let a = smoothstep(1.0, 0.3, d) * 0.035;
+  return vec4f(in.color * a, a);
+}
+""")
+
+(texture :name sparksTex :size canvas :format rgba16float
+  :usage [render-attachment texture-binding])
+
+(render-pipeline :name sparkPipe :layout auto
+  (vertex :module sparkCode :entry vs
+    (vertex-buffer :array-stride 32 :step-mode instance
+      (attribute :shader-location 0 :offset 0 :format float32x2)
+      (attribute :shader-location 1 :offset 8 :format float32x2)
+      (attribute :shader-location 2 :offset 16 :format float32x2))
+    (vertex-buffer :array-stride 8 :step-mode vertex
+      (attribute :shader-location 3 :offset 0 :format float32x2)))
+  (fragment :module sparkCode :entry fs
+    (color-target :format rgba16float
+      (blend (color :src-factor one :dst-factor one :operation add)
+             (alpha :src-factor one :dst-factor one :operation add))))
+  (primitive :topology triangle-list))
+
+(bind-group :name sparkBinds :layout sparkPipe :group 0
+  (entry :binding 0 :buffer inputs))
+
+(render-pass :name sparks
+  (color-attachment :view sparksTex :clear-value [0.0 0.0 0.0 0.0] :load-op clear :store-op store)
+  :pipeline sparkPipe
+  :bind-groups [sparkBinds]
+  :vertex-buffers [dust quadVB]
+  :vertex-buffers-pool-offsets [1 0]
+  (draw :vertex-count 6 :instance-count N))
+
+; ground: `pixel → surface`. The haze, a ramp over simplex noise at the
+; grain the params hold, as a hand-written fullscreen pass, because a
+; `(pass …)` cannot bind the params buffer.
+(shader-module :name groundCode :imports [simplex] :code """
+struct Params { grain : f32, heat : f32, pad0 : f32, pad1 : f32 }
+struct Inputs { t : f32, w : f32, h : f32, asp : f32 }
+@group(0) @binding(0) var<uniform> params : Params;
+@group(0) @binding(1) var<uniform> inputs : Inputs;
+
+@vertex
+fn vs(@builtin(vertex_index) i : u32) -> @builtin(position) vec4f {
+  let x = f32(i32(i & 1u) * 4 - 1);
+  let y = f32(i32(i >> 1u) * 4 - 1);
+  return vec4f(x, y, 0.0, 1.0);
+}
+
+@fragment
+fn fs(@builtin(position) pos : vec4f) -> @location(0) vec4f {
+  let uv = pos.xy / vec2f(inputs.w, inputs.h);
+  let p = vec2f(uv.x * inputs.asp, uv.y);
+  // (field :name haze :value (ramp (simplex position :scale grain)))
+  let n = simplex(p * params.grain + vec2f(inputs.t * 0.02, 0.0)) * 0.5 + 0.5;
+  let ramp = mix(vec3f(0.015, 0.008, 0.02), vec3f(0.14, 0.06, 0.05), n * n);
+  return vec4f(ramp, 1.0);
+}
+""")
+
+(texture :name groundTex :size canvas :format rgba8unorm
+  :usage [render-attachment texture-binding])
+
+(render-pipeline :name groundPipe :layout auto
+  (vertex :module groundCode :entry vs)
+  (fragment :module groundCode :entry fs (color-target :format rgba8unorm))
+  (primitive :topology triangle-list))
+
+(bind-group :name groundBinds :layout groundPipe :group 0
+  (entry :binding 0 :buffer params)
+  (entry :binding 1 :buffer inputs))
+
+(render-pass :name ground
+  (color-attachment :view groundTex :clear-value [0.0 0.0 0.0 1.0] :load-op clear :store-op store)
+  :pipeline groundPipe
+  :bind-groups [groundBinds]
+  (draw :vertex-count 3))
+
+; --- the compute pipelines and passes ---
+(compute-pipeline :name seedPipe :layout auto (compute :module seedCode :entry main))
+(bind-group :name seedBinds :layout seedPipe :group 0 :pool 2
+  (entry :binding 0 :buffer letters)
+  (entry :binding 1 :buffer dust :ping-pong 0)
+  (entry :binding 2 :buffer dust :ping-pong 1))
+(compute-pass :name seed :pipeline seedPipe :bind-groups [seedBinds]
+  (dispatch :workgroups [(ceil (/ N 64))]))
+
+(compute-pipeline :name stepPipe :layout auto (compute :module stepCode :entry main))
+(bind-group :name stepBinds :layout stepPipe :group 0 :pool 2
+  (entry :binding 0 :buffer params)
+  (entry :binding 1 :buffer inputs)
+  (entry :binding 2 :buffer pointerBuf)
+  (entry :binding 3 :buffer dust :ping-pong 0)
+  (entry :binding 4 :buffer dust :ping-pong 1))
+(compute-pass :name step :pipeline stepPipe :bind-groups [stepBinds]
+  (dispatch :workgroups [(ceil (/ N 64))]))
+
+; trails and final: `surface → memory` and `surface, surface → surface`.
+; The sugar tier reads the two textures by name; `prev_trails` is last
+; frame's output, decayed.
+(pass-graph :name look
+  (pass :name trails :feedback true :reads [sparksTex] :format rgba16float :code """
+    @fragment fn fs(@builtin(position) pos: vec4f) -> @location(0) vec4f {
+      // The pass addresses its canvas-sized textures through pngine's own
+      // extent; the group's list therefore carries `trails__uq` in front of
+      // it, and the frame's solo text names that queue.
+      let uv = pos.xy / vec2f(pngine.width, pngine.height);
+      let at = vec2i(uv * vec2f(pngine.width, pngine.height));
+      // (feedback :name trails :source sparks :decay .965)
+      let prev = textureLoad(prev_trails, at, 0).rgb * 0.965;
+      let now = textureLoad(sparksTex, at, 0).rgb;
+      return vec4f(prev + now, 1.0);
+    }
+  """)
+  (pass :name final :reads [groundTex] :code """
+    @fragment fn fs(@builtin(position) pos: vec4f) -> @location(0) vec4f {
+      let uv = pos.xy / vec2f(pngine.width, pngine.height);
+      // (compose :name final :a ground :b trails), then a tonemap to the canvas
+      let g = textureSample(groundTex, samp, uv).rgb;
+      let t = textureSample(trails, samp, uv).rgb;
+      let hdr = g + t;
+      return vec4f(hdr / (hdr + vec3f(1.0)), 1.0);
+    }
+  """))
+
+(frame :name main
+  :init [seed]
+  :before [writeInputs writePointer]
+  :perform [step sparks ground look])

package/starters/ember/timeline.piece.sjon

@@ -0,0 +1,34 @@
+; The hello piece's derived spelling, the browser seat: the aggregate
+; carries tempura's own roots inline, so one fetch from the page is the
+; whole document the boundary walks (`PieceHost.score`, the wasm
+; `anm_piece_score`). A wasm boundary has no filesystem, so the split
+; spelling's `:timeline` file cannot reach it; these inline roots can. The
+; page opens this file with `?seat=timeline` and drives the derived score
+; through the same compile, evaluate and route path as its authored score
+; (`player/player.js`, `player/seat.js`). The param's appended control and
+; the `warmth` lane both name registry-0 `heat`, and pacer writes the
+; control after every track, so `heat` is the control's value on every
+; frame, idle at 0.6 and held at the slider's value, while the `churn`
+; lane's own `grain` target moves the picture (the tenth ruling,
+; 2026-10-07). The gate's bytes and numbers live in
+; `npm/animader/test/derived-seat.test.js`; the browser pass replays them
+; through `player/check.mjs` case 14.
+(animader :name ember :version 1
+  :default-world live
+  :worlds  [live])
+
+(param :name heat :default 0.6 :range [0 2])
+
+(world :name live
+  :time live :params defaults :input live :viewport [1280 720]
+  :assets project :state live)
+
+(timeline :title "ember, the mix" :length 4bar :end hold)
+(tempo-point :at 0q :qpm 120)
+(meter-point :at 0q :sig [4 4])
+(lane :name warmth :kind curve :target heat
+  (keyframe :at 0q :value 0.1)
+  (keyframe :at 4bar :value 0.9))
+(lane :name churn :kind curve :target grain
+  (keyframe :at 0q :value 4.7)
+  (keyframe :at 4bar :value 9.4))