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.
@@ -62,19 +62,32 @@ export function uniformTypeName(tag) {
62
62
  * block's base. `buffer` is null when the payload names nothing: one minted
63
63
  * before the buffer-name block (3.0.1 and earlier), or a buffer the block
64
64
  * does not list.
65
- * @param {Map<string, {bufferId: number, offset: number, size: number, type: number, elemCount: number}>} uniforms
65
+ *
66
+ * A control entry (parseUniformTable marks them) describes with the same key
67
+ * set as every field and `control: true`: type "f32", no buffer — its value
68
+ * reaches the GPU through the frame's own control-inputs write, so no host
69
+ * writeBuffer can name it — offset 0, elemCount 0 (§6.1).
70
+ * @param {Map<string, {bufferId: number, offset: number, size: number, type: number, elemCount: number, control?: boolean, slot?: number}>} uniforms
66
71
  * @param {Map<string, {id: number, pool?: number}>} buffers - the buffer-name block
67
- * @returns {Record<string, {type: string, size: number, buffer: string | null, offset: number, elemCount: number}>}
72
+ * @returns {Record<string, {type: string, size: number, buffer: string | null, offset: number, elemCount: number, control: boolean}>}
68
73
  */
69
74
  export function describeUniforms(uniforms, buffers) {
70
75
  const nameOf = (id) => {
71
76
  for (const [name, b] of buffers) if (id >= b.id && id < b.id + (b.pool || 1)) return name;
72
77
  return null;
73
78
  };
74
- /** @type {Record<string, {type: string, size: number, buffer: string | null, offset: number, elemCount: number}>} */
79
+ /** @type {Record<string, {type: string, size: number, buffer: string | null, offset: number, elemCount: number, control: boolean}>} */
75
80
  const out = {};
76
81
  for (const [name, info] of uniforms) {
77
- out[name] = { type: uniformTypeName(info.type), size: info.size, buffer: nameOf(info.bufferId), offset: info.offset, elemCount: info.elemCount };
82
+ const control = info.control === true;
83
+ out[name] = {
84
+ type: uniformTypeName(info.type),
85
+ size: info.size,
86
+ buffer: control ? null : nameOf(info.bufferId),
87
+ offset: info.offset,
88
+ elemCount: info.elemCount,
89
+ control,
90
+ };
78
91
  }
79
92
  return out;
80
93
  }
@@ -12,6 +12,11 @@ import { initialPlayback } from "./playback-state.js";
12
12
 
13
13
  const PNGB_HEADER_SIZE = 40;
14
14
  const PNGB_VERSION_V0 = 0;
15
+ // D6 (frame-program §12): version 1 marks an executor-less guarded payload.
16
+ // The viewer's contract still requires an embedded executor, but a v1 payload
17
+ // must be refused for THAT reason — never by the version gate, which an old
18
+ // runtime reads but a new one must not hide behind.
19
+ const PNGB_VERSION_V1 = 1;
15
20
  const PNGB_FLAG_HAS_EMBEDDED_EXECUTOR = 0x01;
16
21
  const NO_EMBEDDED_EXECUTOR_ERROR =
17
22
  "No embedded executor in payload. Use an embedded-executor PNG payload, or use pngine/dev with wasmUrl fallback.";
@@ -198,7 +203,7 @@ function assertEmbeddedExecutorPayload(bytecode) {
198
203
 
199
204
  const view = new DataView(bytecode.buffer, bytecode.byteOffset, bytecode.byteLength);
200
205
  const version = view.getUint16(4, true);
201
- if (version !== PNGB_VERSION_V0) {
206
+ if (version !== PNGB_VERSION_V0 && version !== PNGB_VERSION_V1) {
202
207
  throw new Error(`Unsupported PNGB version: ${version}`);
203
208
  }
204
209
 
@@ -35,7 +35,7 @@
35
35
  // whole block is dropped from its bundle. (RESIZE is NOT
36
36
  // gated — both profiles react to a canvas resize.)
37
37
 
38
- import { createCommandDispatcher, parseUniformTable, parseDeviceLimits, requiredFeaturesFor, canvasAlphaMode } from "./gpu.js";
38
+ import { createCommandDispatcher, parseUniformTable, parseDeviceLimits, requiredFeaturesFor, canvasAlphaMode, payloadHasGuards } from "./gpu.js";
39
39
  import { describeUniforms } from "./uniform-convert.js";
40
40
  import { parsePayload, getExecutorImports } from "./loader.js";
41
41
 
@@ -85,6 +85,16 @@ export const MSG = {
85
85
  const NO_EMBEDDED_EXECUTOR_ERROR =
86
86
  "No embedded executor in payload. Use an embedded-executor PNG payload, or use pngine/dev with wasmUrl fallback.";
87
87
 
88
+ // §9's load-time handshake: a payload whose header says has_guards carries
89
+ // frame-program instructions, and an executor that predates them treats each
90
+ // as a no-op and reads its OPERANDS as instructions — garbage, silently. The
91
+ // executor that runs it must export getControlPtr; refuse the load naming the
92
+ // two fixes. A guarded payload that EMBEDS its executor carries a current one
93
+ // (the same compiler set the bit), so it passes; an old RUNTIME rendering it
94
+ // never reaches this check and the guards run inside the embedded executor.
95
+ const GUARDED_PAYLOAD_ERROR =
96
+ "payload uses frame-program guards, but this executor predates them (no getControlPtr export) — re-embed the executor with a current pngine, or run the payload on a newer runtime";
97
+
88
98
  // The default browser environment, wired from worker globals. Only called from
89
99
  // the worker entries (never node), so the global references are safe here.
90
100
  export function browserEnv() {
@@ -137,6 +147,13 @@ export function createWorkerHandlers(env, opts = {}) {
137
147
  // GPU resource on a fresh device without the host re-sending it.
138
148
  let lastBytecode = null;
139
149
  let uniformMap = null;
150
+ // The EXECUTOR's control table as a host view (65 f32 over getControlPtr;
151
+ // slot 0 is `time`), rebuilt whenever an executor is adopted, and handed to
152
+ // whichever dispatcher then owns rendering — controls are written through
153
+ // gpu.setUniform (§6.1), so the dispatcher needs the view the executor
154
+ // reads. Null on an executor that predates the export; a payload that
155
+ // actually uses controls is refused at load (§9) rather than limping.
156
+ let controlTable = null;
140
157
  // The payload's buffer-name block, kept beside the uniform table so
141
158
  // getUniforms can name each field's buffer the way writeBuffer speaks it.
142
159
  let bufferNames = new Map();
@@ -192,6 +209,7 @@ export function createWorkerHandlers(env, opts = {}) {
192
209
  gpu = env.makeDispatcher(device, context);
193
210
  gpu.setDebug(debugMode);
194
211
  if (memory) gpu.setMemory(memory); // null at first init; handleInit binds it post-executor
212
+ if (controlTable) gpu.setControlTable(controlTable); // re-adopted on a reload's fresh dispatcher
195
213
  gpu.setCanvasSize(canvas.width, canvas.height);
196
214
  gpu.setOnShaderError((err) => { post({ type: "shader-error", ...err }); });
197
215
  gpu.setOnError((err) => reportCommandError(err.message, err.source));
@@ -220,6 +238,13 @@ export function createWorkerHandlers(env, opts = {}) {
220
238
  memory = wasm.memory;
221
239
  abiVersion = wasm.getAbiVersion?.() ?? 1;
222
240
  executorBytes = bytes;
241
+ // The control-table view follows the executor it reads: rebuilt on every
242
+ // adoption (a reload can swap executors), valid for the instance's life
243
+ // (the executor never grows its memory). Pushed to the dispatcher below —
244
+ // a kept dispatcher (gpuDirty false) must not keep the OLD memory's view.
245
+ controlTable = typeof wasm.getControlPtr === "function"
246
+ ? new Float32Array(memory.buffer, wasm.getControlPtr(), 65)
247
+ : null;
223
248
  if (debug) console.log("[Worker] Executor ABI version:", abiVersion);
224
249
  // The dispatcher decodes every command stream out of the EXECUTOR's
225
250
  // memory; a swap without this rebind reads the new payload's stream from
@@ -227,6 +252,7 @@ export function createWorkerHandlers(env, opts = {}) {
227
252
  // dispatcher (rebinding memory again); this covers a load whose previous
228
253
  // init stream was empty (gpuDirty false, dispatcher kept).
229
254
  gpu?.setMemory(memory);
255
+ gpu?.setControlTable?.(controlTable);
230
256
  }
231
257
 
232
258
  // The embedded executor a payload carries, or null when it has none. A
@@ -446,8 +472,14 @@ export function createWorkerHandlers(env, opts = {}) {
446
472
  wasm = instance.exports;
447
473
  memory = wasm.memory;
448
474
  abiVersion = wasm.getAbiVersion?.() ?? 1;
475
+ // Same view the embedded path builds (adoptExecutor): the shared
476
+ // executor's own table, handed to the dispatcher for setUniform routing.
477
+ controlTable = typeof wasm.getControlPtr === "function"
478
+ ? new Float32Array(memory.buffer, wasm.getControlPtr(), 65)
479
+ : null;
449
480
  if (data.debug) console.log("[Worker] Executor ABI version:", abiVersion);
450
481
  gpu.setMemory(memory);
482
+ gpu.setControlTable?.(controlTable);
451
483
  initialized = true;
452
484
 
453
485
  if (data.bytecode) await loadBytecode(data.bytecode);
@@ -520,6 +552,17 @@ export function createWorkerHandlers(env, opts = {}) {
520
552
  // for input, init() to emit resource-creation commands, frame() to render,
521
553
  // getCommandPtr/getCommandLen for the command-buffer output.
522
554
  async function loadBytecode(bytecode) {
555
+ // Normalize once, before every consumer below.
556
+ const bytecodeArray = bytecode instanceof Uint8Array ? bytecode : new Uint8Array(bytecode);
557
+
558
+ // The §9 handshake, FIRST: a refused load leaves the running engine
559
+ // exactly as it was (no dispatcher reset, no byte writes), the way a
560
+ // rejected executor adoption does. init() has not run, so there is no
561
+ // half-loaded state to unwind.
562
+ if (payloadHasGuards(bytecodeArray) && typeof wasm?.getControlPtr !== "function") {
563
+ throw new Error(GUARDED_PAYLOAD_ERROR);
564
+ }
565
+
523
566
  // Reset GPU state if the dispatcher has executed anything. Keyed on
524
567
  // `gpuDirty`, not `moduleLoaded`: the latter is set only on SUCCESS, so a
525
568
  // load whose init stream rejected midway (an undecodable image blob, a
@@ -536,7 +579,6 @@ export function createWorkerHandlers(env, opts = {}) {
536
579
  bufferNames = new Map();
537
580
 
538
581
  // Split PNGB: bytecode (small) → bytecodePtr, data section (large) → dataPtr
539
- const bytecodeArray = bytecode instanceof Uint8Array ? bytecode : new Uint8Array(bytecode);
540
582
  lastBytecode = bytecodeArray; // retain so device-loss recovery can rebuild resources
541
583
  const payloadOffsets = parsePayload(bytecodeArray).offsets;
542
584
  const dataOffset = payloadOffsets.data;
@@ -651,24 +693,45 @@ export function createWorkerHandlers(env, opts = {}) {
651
693
  }
652
694
  }
653
695
 
696
+ // The control table gets the same save/restore around a preview — at most
697
+ // 64 floats (§6.2). The SNAPSHOT is the prefetch's to take, inside its own
698
+ // locked section BEFORE it applies the thumbnail's uniforms: one taken
699
+ // here, inside renderEphemeral, would capture the thumbnail's values, and
700
+ // the resize repaint never changes controls at all. Restoring writes every
701
+ // slot back; slot 0 is the frame's own time and frame() overwrites it
702
+ // before the next body runs. A preview still cannot undo GPU work — the
703
+ // uniform writes that went to buffers stay.
704
+ function snapshotControls() {
705
+ return controlTable ? controlTable.slice() : null;
706
+ }
707
+ function restoreControls(saved) {
708
+ if (controlTable && saved) controlTable.set(saved);
709
+ }
710
+
654
711
  async function handleDraw(data) {
655
712
  if (!initialized || !moduleLoaded || deviceLost) return;
656
713
 
657
714
  // Apply pointer state before rendering (if provided)
658
715
  if (data.pointer) gpu.setPointer(data.pointer);
659
716
 
660
- // Apply uniforms before rendering (if provided)
661
- if (data.uniforms && typeof data.uniforms === "object") {
662
- const count = gpu.setUniforms(data.uniforms);
663
- if (debugMode && count > 0) {
664
- console.log(`[Worker] Set ${count} uniforms`);
665
- }
666
- }
667
-
668
717
  const t = data.time ?? 0;
669
718
  await withRenderLock(async () => {
719
+ // Host inputs land INSIDE the render lock (§6.2), at the head of the
720
+ // frame that carries them: uniforms and controls first, host buffer
721
+ // writes beside them, then the frame. Applied before the lock was
722
+ // taken, a thumbnail render could run between a draw's writes and its
723
+ // frame — overwriting the draw's control values with the thumbnail's
724
+ // `scene` lane, or leaking the draw's into the thumbnail, depending on
725
+ // the interleave. A control rides this same `uniforms` map (§6.1), so
726
+ // it inherits the ordering for free.
727
+ if (data.uniforms && typeof data.uniforms === "object") {
728
+ const count = gpu.setUniforms(data.uniforms);
729
+ if (debugMode && count > 0) {
730
+ console.log(`[Worker] Set ${count} uniforms`);
731
+ }
732
+ }
670
733
  // Host buffer writes ride the draw message and land at the head of the
671
- // frame that carries them — INSIDE the render lock, unlike the uniforms
734
+ // frame that carries them — INSIDE the render lock, like the uniforms
672
735
  // above, because a `poolIndex: "active"` write resolves against the
673
736
  // executor's frame counter, and a prefetch thumbnail render moves and
674
737
  // restores that counter under this same lock (renderEphemeral). Read
@@ -734,6 +797,7 @@ export function createWorkerHandlers(env, opts = {}) {
734
797
  moduleLoaded = false;
735
798
  initialized = false;
736
799
  uniformMap = null;
800
+ controlTable = null;
737
801
  bufferNames = new Map();
738
802
  frameNames = new Map();
739
803
  appliedFrame = null;
@@ -949,6 +1013,11 @@ export function createWorkerHandlers(env, opts = {}) {
949
1013
  // every pooled binding. renderEphemeral (shared with the resize
950
1014
  // repaint) saves and restores the counter around the render.
951
1015
  renderEphemeral,
1016
+ // The control-table half of the same side-effect-freeness: drain()
1017
+ // snapshots the live values before applying a thumbnail's uniforms and
1018
+ // restores them after (§6.2).
1019
+ snapshotControls,
1020
+ restoreControls,
952
1021
  getCanvas: () => canvas,
953
1022
  getGpu: () => gpu,
954
1023
  loaded: () => moduleLoaded,
@@ -9,6 +9,8 @@
9
9
  // env — makeOffscreen, grabBitmap, defer, gpuTextureUsage
10
10
  // post(msg, xfer?) — self.postMessage
11
11
  // render(t, w, h) — the shared frame renderer (awaited)
12
+ // snapshotControls()/restoreControls(saved) — the live control table's
13
+ // save/restore around a thumbnail's own uniforms (§6.2)
12
14
  // getCanvas() — the visible OffscreenCanvas (thumbnail source)
13
15
  // getGpu() — the current command dispatcher
14
16
  // loaded() — moduleLoaded (drain / prefetch guards)
@@ -163,6 +165,15 @@ export function createPrefetch(host) {
163
165
  // context (or capturing this block's frame onto the visible canvas).
164
166
  await host.withRenderLock(async () => {
165
167
  gpu.setRenderTargetContext(prefetchCtx);
168
+ // Snapshot the LIVE control values before the thumbnail's uniforms
169
+ // touch the table — inside this locked section, because that is
170
+ // where the values stop being live: a thumbnail's `scene` lane
171
+ // writes the same table the next live frame reads. Restored in the
172
+ // finally below, the way renderEphemeral restores the frame
173
+ // counter. (A snapshot taken inside renderEphemeral itself would
174
+ // capture the thumbnail's values — §6.2.) Uniform writes that went
175
+ // to GPU buffers are NOT restored: a preview cannot undo GPU work.
176
+ const savedControls = host.snapshotControls();
166
177
  try {
167
178
  // Apply this block's score uniforms (when present) so the thumbnail
168
179
  // renders the animation's value at its center time, exactly as the
@@ -174,6 +185,7 @@ export function createPrefetch(host) {
174
185
  // hosts built before it existed.
175
186
  await (host.renderEphemeral ?? host.render)(centerTime, prefetchCanvas.width, prefetchCanvas.height);
176
187
  } finally {
188
+ host.restoreControls(savedControls);
177
189
  gpu.setRenderTargetContext(null);
178
190
  }
179
191
  });
Binary file
package/wasm/pngine.wasm CHANGED
Binary file