pngine 4.2.1 → 4.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -402,6 +402,7 @@
402
402
  (member :name pngine-inputs :description "16 B: time, canvasWidth, canvasHeight, aspect (all f32). Runtime-provided; there is no authored document declaration to navigate to.")
403
403
  (member :name scene-time-inputs :description "12 B: time, canvasWidth, canvasHeight (all f32) — the first 12 bytes of pngine-inputs. True scene timing is not modelled yet. Runtime-provided; there is no authored document declaration to navigate to.")
404
404
  (member :name pngine-frame-inputs :description "20 B: the 16 B of pngine-inputs, then frameIndex (u32) — the executor's frame counter, which is also the ping-pong pool phase. For a jitter sequence (TAA) or any per-frame rotation. Runtime-provided; there is no authored document declaration to navigate to.")
405
+ (member :name control-inputs :description "4 B per declared `(control …)`, in declaration order; the frame's own `write-buffer` carries them, so a guard and a shader read one value.")
405
406
  (member :name pointer-inputs :description "48 B: x, y, clickX, clickY, dx, dy, buttons, pressure, modifiers, scrollX, scrollY, _pad (all f32). Runtime-provided; there is no authored document declaration to navigate to.")))
406
407
  ; The two ref arms are ONE cross-ref target group, never a union of two ref
407
408
  ; kinds: a union resolves first-match while the emitter looks the name up in
@@ -417,6 +418,28 @@
417
418
  :underlying union
418
419
  :union (union-shape :alternatives [builtin-data-source data-or-wasm-ref]))
419
420
 
421
+ ; ---- the guard subject: a builtin control or a declared one ----
422
+ ; A `(step-group :when …)` names ONE thing, and the two things it can name
423
+ ; live in different tables. The union of a member set and a reference kind is
424
+ ; `write-buffer-source`'s shape, not a second mechanism: the arms overlap on
425
+ ; the symbol shape, so a name neither accepts reports
426
+ ; `union_no_branch_matched` naming both explanations, and a name only the
427
+ ; reference arm could mean reports that arm's own `not_cross_ref`. Splitting
428
+ ; it into two keys would let an author write both spellings at once.
429
+ (value-kind :name builtin-control
430
+ :description "A control the engine provides every frame. Runtime-provided; there is no authored document declaration to navigate to."
431
+ :underlying symbol
432
+ :members (member-set
433
+ (member :name time :description "The built-in control the engine sets every frame: seconds since the frame program started. Needs no (control …) declaration; the compiler reserves the name, so a declared control cannot shadow it.")))
434
+ (value-kind :name control-ref
435
+ :description "Reference to a declared (control :name …)."
436
+ :underlying symbol
437
+ :cross-ref (cross-ref :target [pngine/control]))
438
+ (value-kind :name control-source
439
+ :description "The subject of a guard: the builtin control time, or a name declared by (control …)."
440
+ :underlying union
441
+ :union (union-shape :alternatives [builtin-control control-ref]))
442
+
420
443
  ; `byte-size` was `[byte-count data-ref]` — a union whose ref arm meant "size
421
444
  ; this buffer from that data without filling it". Every corpus use of it also
422
445
  ; carried `:mapped-at-creation <the same data>`, naming one thing twice, and
@@ -1071,13 +1094,14 @@
1071
1094
  ; `duplicate_cross_ref_target` at the declaration, so a step can never be
1072
1095
  ; ambiguous. A named graph is in the list because the frame names it in the
1073
1096
  ; AUTHORED aggregate, where it is a `(pass-graph …)` / `(draw-graph …)` and
1074
- ; not yet the `(step-group …)` its hook emits.
1097
+ ; not yet the `(step-group …)` its hook emits; a `(select …)` joins for the
1098
+ ; same reason (2089e59's fix, applied to the fourth member).
1075
1099
  ; (It used to be a union tried in order, while the emitter kept
1076
1100
  ; one table for both pass kinds — a collision silently dropped the render pass.)
1077
1101
  (value-kind :name frame-step
1078
- :description "One frame step: a render-pass, compute-pass or queue name, a named pass-graph/draw-graph (a step group), or a step-group name (one namespace across the forms)."
1102
+ :description "One frame step: a render-pass, compute-pass or queue name, a named pass-graph/draw-graph (a step group), a step-group name, or a select name (one namespace across the forms)."
1079
1103
  :underlying symbol
1080
- :cross-ref (cross-ref :target [render-pass compute-pass queue step-group pass-graph draw-graph]))
1104
+ :cross-ref (cross-ref :target [render-pass compute-pass queue step-group pass-graph draw-graph select]))
1081
1105
  (value-kind :name frame-step-list
1082
1106
  :description "Passes and queues run every frame, in order."
1083
1107
  :underlying vector :vector (vector-shape :element frame-step :max-len 2048))
@@ -1672,7 +1696,7 @@
1672
1696
  ; document said twice what the widened union now says once, and the
1673
1697
  ; exclusive-group existed to stop an author saying both.
1674
1698
  (key :name data :type write-buffer-source
1675
- :description "Source: a (data …) ref, a (wasm-call …) whose result is written each frame, or a runtime builtin — pngine-inputs (16B time/width/height/aspect), scene-time-inputs (12B), pngine-frame-inputs (20B, + frameIndex), pointer-inputs (48B)."))
1699
+ :description "Source: a (data …) ref, a (wasm-call …) whose result is written each frame, or a runtime builtin — pngine-inputs (16B time/width/height/aspect), scene-time-inputs (12B), pngine-frame-inputs (20B, + frameIndex), pointer-inputs (48B), control-inputs (4B per declared (control …) in declaration order)."))
1676
1700
 
1677
1701
  ; Both ends of a copy are dictionaries in the IDL
1678
1702
  ; (GPUTexelCopyTextureInfo / GPUCopyExternalImageSourceInfo), so they are
@@ -2313,6 +2337,20 @@
2313
2337
  (key :name index-buffer :type buffer-ref :optional true
2314
2338
  :description "Index buffer when the bundle draws indexed."))
2315
2339
 
2340
+ ; A host-settable f32. It is one value with two readers: a guard compares it
2341
+ ; before a group runs, and a shader samples the same slot through
2342
+ ; `control-inputs`, so the branch and the draw cannot disagree. The schema
2343
+ ; carries what it can (a unique name, a real default); the rest are compiler
2344
+ ; checks and the description says so rather than implying enforcement here:
2345
+ ; `time` is reserved, the name must be a WGSL identifier because it becomes a
2346
+ ; struct member, and it must not collide with a reflected uniform field
2347
+ ; because the host addresses both by bare name.
2348
+ (form :name control
2349
+ :description "A named f32 the host sets, readable by guards and by shaders through control-inputs. `time` is reserved by the compiler. The name must be a WGSL identifier and must not collide with a reflected uniform field — both are compiler checks, not schema rules."
2350
+ (key :name name :type symbol
2351
+ :description "Control name, unique among controls. It names a WGSL struct member in control-inputs, so it must be a WGSL identifier, and the host addresses it and reflected uniforms by bare name, so it must not collide with one (both compiler checks).")
2352
+ (key :name default :type real :default 0
2353
+ :description "Initial value: a literal, a bounded expression, or a bare (define …) name. Omitted, it is 0. The compiler rejects a value that is not finite after f32 rounding."))
2316
2354
  ; A named sequence of frame steps, expanded WHERE IT IS NAMED. This is what a
2317
2355
  ; `(draw-graph …)` or `(pass-graph …)` with a `:name` emits instead of a
2318
2356
  ; frame: a graph is several passes, so without a name for the set there is no
@@ -2320,11 +2358,34 @@
2320
2358
  ; document's only frame and refuse the other. Nothing reaches the wire — the
2321
2359
  ; emitter inlines a group's steps into the frame that names it, so a frame
2322
2360
  ; over groups emits exactly the ops the same frame written out by hand does.
2361
+ ;
2362
+ ; The guard keys are shaped so the schema can carry the rules (plan 4.6):
2363
+ ; `:when` is one union slot, each comparison is the existing `real` kind,
2364
+ ; and `:requires [when]` turns a comparison or `:else` written without a
2365
+ ; subject into a located reject instead of inert input. Which key means what
2366
+ ; is in each description; holding TWO comparisons is a window, which is why
2367
+ ; that sentence sits on the comparison keys rather than in one shared place.
2323
2368
  (form :name step-group
2324
- :description "A named sequence of frame steps, inlined wherever a (frame …) or another group names it. Emitted by a named (draw-graph …) / (pass-graph …); writable by hand to name a sequence once and run it in several frames."
2369
+ :description "A named sequence of frame steps, inlined wherever a (frame …) or another group names it. Emitted by a named (draw-graph …) / (pass-graph …); writable by hand to name a sequence once and run it in several frames. With :when the group runs only when every comparison key holds (no comparison key = nonzero), and :else names the steps that run otherwise; without :when the group behaves exactly as today."
2325
2370
  (key :name name :type symbol)
2326
2371
  (key :name perform :type frame-step-list
2327
- :description "The steps this group stands for, in order."))
2372
+ :description "The steps this group stands for, in order.")
2373
+ (key :name when :type control-source :optional true
2374
+ :description "The guard's subject: the builtin control time, or a (control …) name. The group runs only when every comparison key holds; with no comparison key it runs when the control is nonzero.")
2375
+ (key :name is :type real :optional true :requires [when]
2376
+ :description "Holds when the control equals this value (an exact f32 comparison). Written beside another comparison key, both must hold — two keys make a window.")
2377
+ (key :name is-not :type real :optional true :requires [when]
2378
+ :description "Holds when the control does not equal this value. Written beside another comparison key, both must hold — two keys make a window.")
2379
+ (key :name below :type real :optional true :requires [when]
2380
+ :description "Holds when the control is less than this value. Written beside another comparison key, both must hold — two keys make a window, as in :at-least 10 :below 10.5.")
2381
+ (key :name above :type real :optional true :requires [when]
2382
+ :description "Holds when the control is greater than this value. Written beside another comparison key, both must hold — two keys make a window.")
2383
+ (key :name at-least :type real :optional true :requires [when]
2384
+ :description "Holds when the control is greater than or equal to this value. Written beside another comparison key, both must hold — two keys make a window.")
2385
+ (key :name at-most :type real :optional true :requires [when]
2386
+ :description "Holds when the control is less than or equal to this value. Written beside another comparison key, both must hold — two keys make a window.")
2387
+ (key :name else :type frame-step-list :optional true :requires [when]
2388
+ :description "The steps that run when the guard does not hold. Needs :when; a group without a guard has nothing to be the alternative to."))
2328
2389
  (form :name frame
2329
2390
  :description "Frame program: what runs each frame, in order."
2330
2391
  (key :name name :type symbol)
@@ -2335,6 +2396,66 @@
2335
2396
  (key :name perform :type frame-step-list
2336
2397
  :description "Passes and queues run every frame, in order."))
2337
2398
 
2399
+ ; =====================================================================
2400
+ ; `(select …)` sugar — lowered to a chain of guarded step-groups by
2401
+ ; pngine/select-v1 (plan frame-program §4.3)
2402
+ ; =====================================================================
2403
+ ; `select` picks the first case whose comparison holds, and the whole thing
2404
+ ; is sugar: the hook lowers it to the chain of guarded `(step-group …)`
2405
+ ; forms a hand-written document would spell out. The schema carries what it
2406
+ ; can (the case count, the `:on` union, the comparison keys as `real`); the
2407
+ ; one rule no key-set can express — "a case carries at least one comparison
2408
+ ; key", because a key-set has no min-children — is the hook's, refused on
2409
+ ; the case's own span. The default belongs in `:else`.
2410
+ ;
2411
+ ; The count bound is head-set bounds on the slot-local `case` form: below
2412
+ ; the floor `positional_missing` (on the select's head), above the ceiling
2413
+ ; `positional_too_many` (on the 65th child) — the same per-head cardinality
2414
+ ; mechanism the pipeline sections use.
2415
+ (value-kind :name select-section :underlying form :heads (head-set
2416
+ (head :name case :min 1 :max 64)))
2417
+ ; One case. The comparison keys are the six a `(step-group …)` guard takes,
2418
+ ; with the same meanings (every key written must hold, so two keys make a
2419
+ ; window); the subject is the select's `:on`, written once, which is why
2420
+ ; these carry no `:requires`. No `:name` — a case is a positional arm, not a
2421
+ ; target, and the group the hook builds for it is named after the SELECT.
2422
+ (form :name case
2423
+ :description "One case of a (select …): at least one comparison key (the default belongs in the select's :else), and the steps to perform when it is the first case that holds."
2424
+ (key :name is :type real :optional true
2425
+ :description "Holds when the control equals this value (an exact f32 comparison). Written beside another comparison key, both must hold — two keys make a window.")
2426
+ (key :name is-not :type real :optional true
2427
+ :description "Holds when the control does not equal this value. Written beside another comparison key, both must hold — two keys make a window.")
2428
+ (key :name below :type real :optional true
2429
+ :description "Holds when the control is less than this value. Written beside another comparison key, both must hold — two keys make a window.")
2430
+ (key :name above :type real :optional true
2431
+ :description "Holds when the control is greater than this value. Written beside another comparison key, both must hold — two keys make a window.")
2432
+ (key :name at-least :type real :optional true
2433
+ :description "Holds when the control is greater than or equal to this value. Written beside another comparison key, both must hold — two keys make a window.")
2434
+ (key :name at-most :type real :optional true
2435
+ :description "Holds when the control is less than or equal to this value. Written beside another comparison key, both must hold — two keys make a window.")
2436
+ (key :name perform :type frame-step-list
2437
+ :description "The steps this case performs when it is the first case that holds."))
2438
+ ; The chain's shape, for the reader: `(select :name backdrop :on scene (case
2439
+ ; :is 0 :perform [linePass]) (case :is 1 :perform [gatesPass]) :else
2440
+ ; [ringPass])` lowers to
2441
+ ; (step-group :name backdrop :when scene :is 0 :perform [linePass] :else [backdrop__case1])
2442
+ ; (step-group :name backdrop__case1 :when scene :is 1 :perform [gatesPass] :else [ringPass])
2443
+ ; — the first group keeps the select's name (so a frame names `backdrop`
2444
+ ; either way), continuations follow the hooks' double-underscore convention,
2445
+ ; and the last case's `:else` is the select's `:else`.
2446
+ (form :name select
2447
+ :description "Pick the first case whose comparison holds. Sugar: pngine/select-v1 lowers it to a chain of guarded (step-group …) forms, so a frame names the select exactly as it names a group. Cases are tried in source order and the first match wins (overlap is legal — that is what makes a :below cascade work); no match and no :else, the select does nothing."
2448
+ :lowering (lowering :hook pngine/select-v1
2449
+ :produces [step-group])
2450
+ :positional select-section
2451
+ (key :name name :type symbol
2452
+ :description "Select name — the first group of the lowered chain keeps it, so a (frame …) names the select itself, and the continuation groups are <name>__caseN.")
2453
+ (key :name on :type control-source
2454
+ :description "The control every case compares — the builtin time, or a name declared by (control …). Becomes :when on every group the lowering emits.")
2455
+ (key :name else :type frame-step-list :optional true
2456
+ :description "The steps that run when no case holds. Becomes the last group's :else, so it is the chain's fallback arm."))
2457
+
2458
+
2338
2459
  ; ---- init sugar: lowered to compute-pipeline + bind-group + compute-pass ----
2339
2460
  (form :name init
2340
2461
  :description "One-shot compute init of a storage buffer (first frame only)."
@@ -2416,7 +2537,7 @@
2416
2537
  :positional pass-section
2417
2538
  (key :name name :type symbol)
2418
2539
  (key :name code :type string
2419
- :description "WGSL fragment (or compute) source; the hook injects the binding prelude (pngine uniforms, pointer, sampler, dep/feedback textures, D0… data buffers). Required — the hook always refused its absence.")
2540
+ :description "WGSL fragment (or compute) source; the hook injects the binding prelude (pngine uniforms, pointer, sampler, dep/feedback textures, D0… data buffers, and — when the document declares (control …) forms and the code names `controls` — the ControlInputs struct, one f32 member per control in declaration order, on the next binding, with a graph-shared buffer and one control-inputs write per frame). Required — the hook always refused its absence.")
2420
2541
  (key :name feedback :type boolean :optional true
2421
2542
  :description "Ping-pong texture pair for feedback; the previous frame is readable as prev_<name>.")
2422
2543
  ; The intermediate's texel format, which is ONE value in WebGPU terms: the
package/src/anim.js CHANGED
@@ -58,6 +58,22 @@ function checkTime(time) {
58
58
  return time;
59
59
  }
60
60
 
61
+ /**
62
+ * A loop length is null (the unbounded clock) or a finite number of seconds
63
+ * greater than zero. Zero, a negative length, NaN, an Infinity or a string
64
+ * would divide the clock into a range nobody meant, so it is the caller's bug,
65
+ * refused before anything changes the way a bad `time` is.
66
+ * @param {unknown} loop
67
+ * @returns {number|null}
68
+ */
69
+ function checkLoop(loop) {
70
+ if (loop === null) return loop;
71
+ if (typeof loop !== "number" || !Number.isFinite(loop) || loop <= 0) {
72
+ throw new TypeError(`loop must be null or a finite number of seconds greater than zero, got ${String(loop)}`);
73
+ }
74
+ return loop;
75
+ }
76
+
61
77
  /**
62
78
  * The trailing options of setUniform/setUniforms/writeBuffer: an object or
63
79
  * nothing. The positional boolean setUniform once took (a no-op in every
@@ -127,23 +143,48 @@ export function draw(p, opts = {}) {
127
143
  }
128
144
 
129
145
  /**
130
- * Start animation loop
146
+ * Start animation loop.
147
+ *
148
+ * `loop` is the clock length in seconds, or null for the unbounded clock.
149
+ * Absent, the length already set (if any) stays, so a pause and resume keeps
150
+ * it. The option applies to an instance that is already playing too — the
151
+ * PLAY transition returns early there, but the length still lands.
152
+ *
131
153
  * @param {Pngine} p
154
+ * @param {{ loop?: number|null }} [opts]
132
155
  * @returns {Pngine}
133
156
  */
134
- export function play(p) {
157
+ export function play(p, opts = {}) {
158
+ if (opts === null || typeof opts !== "object") throw new TypeError(`play: the second argument is an options object, { loop: 60 }, got ${String(opts)}`);
159
+ if (opts.loop !== undefined) checkLoop(opts.loop);
135
160
  const i = p._;
136
- if (!i || i.pb.playing) return p;
161
+ if (!i) return p;
162
+
163
+ const now = performance.now();
164
+ if (opts.loop !== undefined) {
165
+ const before = i.pb.time;
166
+ i.pb = reduce(i.pb, { type: "SET_LOOP", loop: opts.loop, now });
167
+ // Setting the loop can wrap a running clock backward (t=61 → 1 under a
168
+ // 60s length). The TICK seam below cannot catch that one: the next tick
169
+ // moves FORWARD from the wrapped time, so audio would keep playing from
170
+ // 61 while the video restarts at 1. Seek here, before the early return.
171
+ if (i.audio && i.pb.playing && i.pb.time < before) i.audio.seek(i.pb.time);
172
+ }
173
+ if (i.pb.playing) return p;
137
174
 
138
- i.pb = reduce(i.pb, { type: "PLAY", now: performance.now() });
175
+ i.pb = reduce(i.pb, { type: "PLAY", now });
139
176
 
140
177
  // Start audio synced with visual time
141
178
  if (i.audio) i.audio.play(i.pb.time);
142
179
 
143
- // The clock runs unbounded: nothing ends the loop but pause/stop/destroy.
180
+ // Nothing ends the loop but pause/stop/destroy. A loop length wraps the
181
+ // clock; a tick that comes back lower than the one before it is the seam,
182
+ // so the song restarts at the wrapped offset in the same frame.
144
183
  const loop = () => {
145
184
  if (!i.pb.playing) return;
185
+ const before = i.pb.time;
146
186
  i.pb = reduce(i.pb, { type: "TICK", now: performance.now() });
187
+ if (i.audio && i.pb.time < before) i.audio.seek(i.pb.time);
147
188
  draw(p, { time: i.pb.time });
148
189
  i.animationId = requestAnimationFrame(loop);
149
190
  };
@@ -193,6 +234,12 @@ export function stop(p) {
193
234
 
194
235
  /**
195
236
  * Seek to specific time
237
+ *
238
+ * With a loop length set, a time past it wraps into the range (the floor form
239
+ * from frame-program §6.5) and the wrapped time is what the draw carries, what
240
+ * `p.time` reads and what the song seeks to. An explicit `draw(p, { time })`
241
+ * still sends the time it was given, unwrapped.
242
+ *
196
243
  * @param {Pngine} p
197
244
  * @param {number} time - Time in seconds
198
245
  * @returns {Pngine}
@@ -203,10 +250,11 @@ export function seek(p, time) {
203
250
  if (!i) return p;
204
251
 
205
252
  i.pb = reduce(i.pb, { type: "SEEK", now: performance.now(), time });
253
+ const wrapped = i.pb.time;
206
254
 
207
- if (i.audio) i.audio.seek(time);
255
+ if (i.audio) i.audio.seek(wrapped);
208
256
 
209
- draw(p, { time });
257
+ draw(p, { time: wrapped });
210
258
  return p;
211
259
  }
212
260
 
package/src/core.js CHANGED
@@ -75,6 +75,17 @@ export function createCoreDispatcher(device, ctx) {
75
75
  dispatcher.setUniformTable(table);
76
76
  },
77
77
 
78
+ /**
79
+ * Install the executor's control table: the Float32Array a host
80
+ * builds over `getControlPtr()` (65 slots — `time` at 0, controls at
81
+ * 1..64), or null when the executor predates the export. No copy:
82
+ * setUniform writes a control where the executor reads it, in place.
83
+ * @param {Float32Array|null} view
84
+ */
85
+ setControlTable(view) {
86
+ dispatcher.setControlTable(view);
87
+ },
88
+
78
89
  /**
79
90
  * Install the payload's buffer names, so writeBuffers/getBuffers can
80
91
  * address a buffer by the `(buffer :name …)` the author wrote. The
package/src/gpu.js CHANGED
@@ -82,6 +82,11 @@ const PNGB_FLAG_DEVICE_LIMITS = 0x04;
82
82
  // Header flag bit 4: the uniform-table section carries a buffer-name block
83
83
  // after its bindings (docs/plans/public-write-buffer.md D2).
84
84
  const PNGB_FLAG_BUFFER_NAMES = 0x10;
85
+ // Header flag bits 5 and 6 (frame-program §7.2): bit 5, the section carries a
86
+ // control-name block after the buffer-name block; bit 6, `has_guards` — the
87
+ // payload uses frame-program instructions (§9's load-time handshake).
88
+ const PNGB_FLAG_CONTROL_NAMES = 0x20;
89
+ const PNGB_FLAG_HAS_GUARDS = 0x40;
85
90
  // flags bit 3 — the author requested a PREMULTIPLIED canvas ((canvas
86
91
  // :alpha-mode premultiplied)); clear = "opaque", the GPUCanvasConfiguration
87
92
  // default. The bit used to mean the opposite, back when this runtime's own
@@ -102,6 +107,22 @@ export function canvasAlphaMode(bytecode) {
102
107
  return (view.getUint16(6, true) & PNGB_FLAG_PREMULTIPLIED_CANVAS) ? "premultiplied" : "opaque";
103
108
  }
104
109
 
110
+ /**
111
+ * Whether a payload's header sets `has_guards` (flag bit 6): it carries
112
+ * frame-program instructions. The §9 load-time handshake reads this — such a
113
+ * payload must run on an executor that exports getControlPtr, or the executor
114
+ * reads the guard instructions' operands as instructions and renders garbage.
115
+ * False for a non-PNGB or a short buffer (nothing to refuse).
116
+ * @param {Uint8Array|null|undefined} bytecode
117
+ * @returns {boolean}
118
+ */
119
+ export function payloadHasGuards(bytecode) {
120
+ if (!bytecode || bytecode.length < PNGB_HEADER_SIZE) return false;
121
+ const view = new DataView(bytecode.buffer, bytecode.byteOffset, bytecode.byteLength);
122
+ if (view.getUint32(0, true) !== PNGB_MAGIC) return false;
123
+ return (view.getUint16(6, true) & PNGB_FLAG_HAS_GUARDS) === PNGB_FLAG_HAS_GUARDS;
124
+ }
125
+
105
126
  /**
106
127
  * Parse uniform table from PNGB bytecode.
107
128
  * Returns: { uniforms: Map<string, {bufferId, offset, size, type, elemCount}>,
@@ -116,6 +137,11 @@ export function canvasAlphaMode(bytecode) {
116
137
  * own queue ops write it every draw. Read only behind header flag bit 4 and
117
138
  * only within the section, so a payload minted before the block — or one
118
139
  * whose bit is clear — parses to an empty map and nothing else changes.
140
+ *
141
+ * The uniform-table section's second tail block (header flag bit 5) lists the
142
+ * document's declared controls; each joins `uniforms` marked
143
+ * `{ control: true, slot }` — slot is 1-based, slot 0 being `time`. See the
144
+ * block's reader below for the reserved-empty-slot rule.
119
145
  */
120
146
  export function parseUniformTable(bytecode) {
121
147
  const view = new DataView(bytecode.buffer, bytecode.byteOffset, bytecode.byteLength);
@@ -187,6 +213,34 @@ export function parseUniformTable(bytecode) {
187
213
  }
188
214
  }
189
215
 
216
+ // The control-name block, after the buffer-name block (§7.2): [count u16]
217
+ // then one string id per control, in slot order — element i is slot i + 1,
218
+ // because slot 0 is `time` and never listed. Each control joins the SAME
219
+ // `uniforms` map the reflected fields live in, marked `control` (§6.1), so
220
+ // every consumer of the map sees it; it has no GPU buffer of its own
221
+ // (control-inputs writes it each frame), so bufferId is -1 — no created
222
+ // buffer id. An entry whose string is EMPTY is a reserved slot (the name
223
+ // did not fit the string table; a slot is never reassigned): it counts for
224
+ // control-inputs but joins no map, so setUniform('') keeps the plain "no
225
+ // uniform named" refusal and later slots keep their numbers.
226
+ if ((view.getUint16(6, true) & PNGB_FLAG_CONTROL_NAMES) && pos + 2 <= sectionEnd) {
227
+ const controlCount = view.getUint16(pos, true);
228
+ pos += 2;
229
+ for (let i = 0; i < controlCount && pos + 2 <= sectionEnd; i++, pos += 2) {
230
+ const name = strings[view.getUint16(pos, true)];
231
+ if (!name) continue; // a reserved slot: unnamed, unlistable, still counted
232
+ uniforms.set(name, {
233
+ control: true,
234
+ slot: i + 1,
235
+ bufferId: -1,
236
+ offset: 0,
237
+ size: 4,
238
+ type: 0, // UT_F32 — controls are f32 only in this version (§4.1)
239
+ elemCount: 0,
240
+ });
241
+ }
242
+ }
243
+
190
244
  return { uniforms, strings, buffers };
191
245
  }
192
246
 
@@ -923,17 +977,25 @@ export function createCommandDispatcher(device, ctx) {
923
977
  // whole WASM memory.
924
978
  onQueryResult = onError = onShaderError = null;
925
979
  uniformMap = null;
980
+ controlTable = null;
926
981
  mem = null;
927
982
  targetCtx = null;
928
983
  enc = pass = null;
929
984
  }
930
985
 
931
- // Uniform table: Map<string, {bufferId, offset, size, type, elemCount}>
986
+ // Uniform table: Map<string, {bufferId, offset, size, type, elemCount}> —
987
+ // plus control entries {control: true, slot, …} (parseUniformTable).
932
988
  let uniformMap = null;
989
+ // The EXECUTOR's control table as a host view: 65 f32 over getControlPtr
990
+ // (slot 0 is `time`). Installed by the worker or a core-tier host once the
991
+ // executor is instantiated; valid for the instance's life (the executor
992
+ // never grows its memory). Null until then, and on an executor that
993
+ // predates the export — setUniform refuses a control then.
994
+ let controlTable = null;
933
995
 
934
996
  /**
935
997
  * Set uniform table from parsed bytecode.
936
- * @param {Map<string, {bufferId, offset, size, type, elemCount}>} map
998
+ * @param {Map<string, {bufferId: number, offset: number, size: number, type: number, elemCount: number, control?: boolean, slot?: number}>} map
937
999
  */
938
1000
  function setUniformTable(map) {
939
1001
  uniformMap = map;
@@ -941,10 +1003,24 @@ export function createCommandDispatcher(device, ctx) {
941
1003
  }
942
1004
 
943
1005
  /**
944
- * Set a uniform value by name.
1006
+ * Install the executor's control table — the Float32Array a host builds
1007
+ * over `getControlPtr()` (65 slots: `time` at 0, controls at 1..64), or
1008
+ * null when the executor predates the export. No copy: writes land where
1009
+ * the executor reads them, the same frame.
1010
+ * @param {Float32Array|null} view
1011
+ */
1012
+ function setControlTable(view) {
1013
+ controlTable = view;
1014
+ }
1015
+
1016
+ /**
1017
+ * Set a uniform value by name. A name that is a CONTROL
1018
+ * (getUniforms marks them) is written into the executor's control table —
1019
+ * install the getControlPtr view first with setControlTable — and takes
1020
+ * exactly one finite number; every other name is packed for its GPU buffer.
945
1021
  * @param {string} name - Uniform field name
946
1022
  * @param {number|number[]|number[][]} value - Value to set (a nested array for a matrix or an array field)
947
- * @returns {boolean} - true if uniform was found and written; a refusal reached onError
1023
+ * @returns {boolean} - true if the value was written; a refusal reached onError
948
1024
  */
949
1025
  // A refusal reaches the host through onError (source "set-uniform"), the
950
1026
  // route writeBuffer's refusals take — it was a DEBUG-gated console.warn, so
@@ -956,6 +1032,24 @@ export function createCommandDispatcher(device, ctx) {
956
1032
  return false;
957
1033
  }
958
1034
 
1035
+ // A control is one f32 the EXECUTOR owns (§6.1): write the table the
1036
+ // guard compares and control-inputs copies, in place — no queue
1037
+ // writeBuffer, so the branch and the shader read the same value in the
1038
+ // same frame. Slot 0 (`time`) is never in the map.
1039
+ if (info.control) {
1040
+ if (!controlTable) {
1041
+ onError && onError({ message: `setUniform: '${name}' is a control, but this executor predates getControlPtr — re-embed the executor with a current pngine, or run the payload on a newer runtime`, source: "set-uniform" });
1042
+ return false;
1043
+ }
1044
+ if (typeof value !== "number" || !Number.isFinite(value)) {
1045
+ onError && onError({ message: `setUniform: control '${name}' takes one finite number, got ${Array.isArray(value) ? "an array" : String(value)}`, source: "set-uniform" });
1046
+ return false;
1047
+ }
1048
+ controlTable[info.slot] = value;
1049
+ DEBUG && dbg && console.log(`[GPU] setUniform: control ${name} = ${value} @ slot ${info.slot}`);
1050
+ return true;
1051
+ }
1052
+
959
1053
  const buffer = buf[info.bufferId];
960
1054
  if (!buffer) {
961
1055
  onError && onError({ message: `setUniform: '${name}' names a buffer this payload never created`, source: "set-uniform" });
@@ -1058,6 +1152,7 @@ export function createCommandDispatcher(device, ctx) {
1058
1152
  setOnError(fn) { onError = fn; },
1059
1153
  setOnQueryResult(fn) { onQueryResult = fn; },
1060
1154
  setUniformTable,
1155
+ setControlTable,
1061
1156
  setUniform,
1062
1157
  setUniforms,
1063
1158
  // Host writes by SJON buffer name; bodies in gpu-host-write.js.
package/src/loader.js CHANGED
@@ -4,9 +4,9 @@
4
4
  * Parses PNGB v0 format to detect and extract embedded executor WASM.
5
5
  * Falls back to shared executor if not embedded.
6
6
  *
7
- * PNGB v0 Header (40 bytes):
7
+ * PNGB Header (40 bytes):
8
8
  * - magic: "PNGB" (4 bytes)
9
- * - version: u16 (0)
9
+ * - version: u16 (0; 1 marks an executor-less guarded payload — D6)
10
10
  * - flags: u16 (bit 0 = has_embedded_executor, bit 1 = has_animation_table)
11
11
  * - plugins: u8 (PluginSet bitfield)
12
12
  * - reserved: [3]u8
@@ -25,6 +25,10 @@ if (typeof EMBEDDED_ONLY === "undefined") globalThis.EMBEDDED_ONLY = false;
25
25
 
26
26
  const PNGB_MAGIC = [0x50, 0x4e, 0x47, 0x42]; // "PNGB"
27
27
  const VERSION_V0 = 0;
28
+ // D6 (frame-program §12): version 1 marks an executor-less guarded payload —
29
+ // the only signal a runtime that predates the §9 handshake obeys. Every
30
+ // reader of the field accepts both; the 40-byte layout is unchanged.
31
+ const VERSION_V1 = 1;
28
32
  const HEADER_SIZE_V0 = 40;
29
33
 
30
34
  // Header flags
@@ -58,17 +62,20 @@ export function parsePayload(pngb) {
58
62
  const view = new DataView(pngb.buffer, pngb.byteOffset, pngb.byteLength);
59
63
  const version = view.getUint16(4, true);
60
64
 
61
- if (version !== VERSION_V0) {
65
+ // v0, and v1 for an executor-less guarded payload (D6): the §9 handshake,
66
+ // not this gate, refuses the pairing that is unsafe to run.
67
+ if (version !== VERSION_V0 && version !== VERSION_V1) {
62
68
  throw new Error(`Unsupported PNGB version: ${version}`);
63
69
  }
64
70
 
65
- return parseV0Header(pngb, view);
71
+ return parseV0Header(pngb, view, version);
66
72
  }
67
73
 
68
74
  /**
69
- * Parse v0 header (40 bytes)
75
+ * Parse the 40-byte header (v0 layout, shared by v1 — D6 changed the field's
76
+ * value, never its size or position).
70
77
  */
71
- function parseV0Header(pngb, view) {
78
+ function parseV0Header(pngb, view, version) {
72
79
  const flags = view.getUint16(6, true);
73
80
  const plugins = pngb[8];
74
81
  const executorOffset = view.getUint32(12, true);
@@ -89,7 +96,7 @@ function parseV0Header(pngb, view) {
89
96
  const bytecodeLength = stringTableOffset - bytecodeOffset;
90
97
 
91
98
  return {
92
- version: VERSION_V0,
99
+ version,
93
100
  hasEmbeddedExecutor,
94
101
  hasAnimationTable,
95
102
  plugins: parsePlugins(plugins),
@@ -1,15 +1,21 @@
1
1
  // Pure playback state machine — the single owner of all play/pause/time math.
2
2
  //
3
- // State: { playing, time, startedAtMs, frame }
3
+ // State: { playing, time, startedAtMs, frame, loop }
4
4
  // startedAtMs is the performance.now() baseline chosen so that
5
5
  // startedAtMs = nowMs - time*1000 ⇒ a TICK(nowMs) recovers `time`.
6
6
  // frame is the pin setFrame holds: a `(frame :name …)` string, or null for
7
7
  // the executor's own choice. It rides every draw message.
8
+ // loop is the clock length in seconds, or null for unbounded. A TICK, PAUSE
9
+ // or SEEK whose time reaches it wraps into [0, loop) with the floor form
10
+ // below and rebases startedAtMs, so the invariant above keeps holding and
11
+ // a tab that stalled for several periods lands inside the range in one
12
+ // tick. DRAW records the time it was given, unwrapped.
8
13
  // anim.js is a thin driver: it reads the clock, dispatches actions here, then
9
14
  // performs the effects (audio, worker draw, requestAnimationFrame) implied by
10
15
  // the state transition. No playback field is written outside reduce().
11
16
  //
12
- // The clock runs unbounded. There used to be an animation-timeline arm here —
17
+ // The clock runs unbounded until a host sets a loop. There used to be an
18
+ // animation-timeline arm here —
13
19
  // scenes resolved from the time, an end behaviour that wrapped or halted it —
14
20
  // over a table the worker stopped delivering in Dec 2025 and no SJON form
15
21
  // emits, so it was unreachable through pngine() for as long as it existed
@@ -24,32 +30,63 @@
24
30
 
25
31
  // Fresh stopped machine. A new object each call so nothing shares mutable state.
26
32
  export function initialPlayback() {
27
- return { playing: false, time: 0, startedAtMs: 0, frame: null };
33
+ return { playing: false, time: 0, startedAtMs: 0, frame: null, loop: null };
34
+ }
35
+
36
+ // The floor form from frame-program §6.5. It stays in [0, loop) for a negative
37
+ // time, where `time % loop` goes negative; null (or a state from before the
38
+ // loop existed) is the unbounded clock.
39
+ function wrapToLoop(time, loop) {
40
+ if (loop === null || loop === undefined) return time;
41
+ return (time / loop - Math.floor(time / loop)) * loop;
28
42
  }
29
43
 
30
44
  // Pure reducer: (state, action) → state. Unknown actions are the identity.
31
45
  export function reduce(state, action) {
32
46
  switch (action.type) {
47
+ case "SET_LOOP": {
48
+ const time = action.loop === null ? state.time : wrapToLoop(state.time, action.loop);
49
+ return {
50
+ ...state,
51
+ loop: action.loop,
52
+ time,
53
+ startedAtMs: state.playing && time !== state.time ? action.now - time * 1000 : state.startedAtMs,
54
+ };
55
+ }
56
+
33
57
  case "PLAY":
34
58
  if (state.playing) return state;
35
59
  return { ...state, playing: true, startedAtMs: action.now - state.time * 1000 };
36
60
 
37
- case "PAUSE":
61
+ case "PAUSE": {
38
62
  if (!state.playing) return state;
39
- return { ...state, playing: false, time: (action.now - state.startedAtMs) / 1000 };
63
+ const raw = (action.now - state.startedAtMs) / 1000;
64
+ const time = wrapToLoop(raw, state.loop);
65
+ return {
66
+ ...state,
67
+ playing: false,
68
+ time,
69
+ startedAtMs: time === raw ? state.startedAtMs : action.now - time * 1000,
70
+ };
71
+ }
40
72
 
41
73
  case "STOP":
42
74
  return { ...state, playing: false, time: 0, startedAtMs: action.now };
43
75
 
44
- case "SEEK":
76
+ case "SEEK": {
77
+ const time = wrapToLoop(action.time, state.loop);
45
78
  return {
46
79
  ...state,
47
- time: action.time,
48
- startedAtMs: state.playing ? action.now - action.time * 1000 : state.startedAtMs,
80
+ time,
81
+ startedAtMs: state.playing ? action.now - time * 1000 : state.startedAtMs,
49
82
  };
83
+ }
50
84
 
51
- case "TICK":
52
- return { ...state, time: (action.now - state.startedAtMs) / 1000 };
85
+ case "TICK": {
86
+ const raw = (action.now - state.startedAtMs) / 1000;
87
+ const time = wrapToLoop(raw, state.loop);
88
+ return time === raw ? { ...state, time } : { ...state, time, startedAtMs: action.now - time * 1000 };
89
+ }
53
90
 
54
91
  case "DRAW":
55
92
  return action.record !== undefined ? { ...state, time: action.record } : state;