pngine 2.0.0 → 3.0.0

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.
@@ -55,6 +55,8 @@ export const MSG = {
55
55
  DESTROY: "destroy",
56
56
  SET_UNIFORM: "setUniform",
57
57
  GET_UNIFORMS: "getUniforms",
58
+ GET_STATS: "getStats",
59
+ STATS: "stats",
58
60
  RESIZE: "resize",
59
61
  READY: "ready",
60
62
  ERROR: "error",
@@ -65,6 +67,9 @@ export const MSG = {
65
67
  RESTART: "restart",
66
68
  DEVICE_LOST: "device-lost",
67
69
  DEVICE_RESTORED: "device-restored",
70
+ // Posted once handleDestroy has released the device. The host terminates on
71
+ // it (init-core.js destroy()), which is what keeps handleDestroy reachable.
72
+ DESTROYED: "destroyed",
68
73
  };
69
74
 
70
75
  const NO_EMBEDDED_EXECUTOR_ERROR =
@@ -95,6 +100,9 @@ export function createWorkerHandlers(env, opts = {}) {
95
100
  let canvas, device, context, gpu, wasm, memory;
96
101
  let initialized = false;
97
102
  let moduleLoaded = false;
103
+ // True once the current dispatcher has executed a command stream — the
104
+ // reset key for loadBytecode (a FAILED init leaves it dirty too).
105
+ let gpuDirty = false;
98
106
  let frameCount = 0;
99
107
  let debugMode = false;
100
108
  // Executor↔host ABI version (docs/abi.md); binaries without the export are v1.
@@ -201,13 +209,14 @@ export function createWorkerHandlers(env, opts = {}) {
201
209
 
202
210
  context = canvas.getContext("webgpu");
203
211
  const format = env.gpu.getPreferredCanvasFormat();
204
- // Header flag bit 3 → "opaque"; default stays the historical "premultiplied".
205
- const alphaMode = bytecode ? canvasAlphaMode(toU8(bytecode)) : "premultiplied";
212
+ // Header flag bit 3 → "premultiplied"; no payload → the spec default.
213
+ const alphaMode = bytecode ? canvasAlphaMode(toU8(bytecode)) : "opaque";
206
214
  context.configure({ device, format, alphaMode, usage: env.gpuTextureUsage.RENDER_ATTACHMENT | env.gpuTextureUsage.COPY_SRC });
207
215
 
208
216
  prefetch?.configure(device, format, alphaMode);
209
217
 
210
218
  wireDispatcher();
219
+ gpuDirty = false;
211
220
  }
212
221
 
213
222
  // Attach a one-shot lost handler. `reason === 'destroyed'` is our own
@@ -226,9 +235,11 @@ export function createWorkerHandlers(env, opts = {}) {
226
235
  const nowMs = env.now();
227
236
  if (nowMs - lastRecoverAt > RECOVER_COOLDOWN_MS) {
228
237
  lastRecoverAt = nowMs;
229
- recoverDevice().catch((err) => {
230
- post({ type: MSG.ERROR, message: `GPU recovery failed: ${err.message}` });
231
- });
238
+ // Through the FIFO, like every other state change: a direct call
239
+ // ran recovery beside the dispatch chain, and a LOAD landing while
240
+ // it awaited its device saw `deviceLost` still true and began a
241
+ // second one — two devices for one loss, one never destroyed.
242
+ dispatch({ type: MSG.RESTART });
232
243
  }
233
244
  }
234
245
  })
@@ -236,8 +247,16 @@ export function createWorkerHandlers(env, opts = {}) {
236
247
  }
237
248
 
238
249
  // Rebuild the GPU stack on a fresh device and reload a shader — the new one if
239
- // supplied, else the last good bytecode — then report ready. The dead device's
240
- // resources are abandoned, so clear moduleLoaded first for a clean build.
250
+ // supplied, else the last good bytecode — then report ready.
251
+ //
252
+ // The stack being replaced is RELEASED first, not abandoned: the old
253
+ // dispatcher's destroy() closes its bitmaps, drops its tables and flips
254
+ // `alive` so a create still suspended in it lands nowhere; the old device's
255
+ // destroy() is a spec no-op on a lost device and frees a LIVE one — the
256
+ // limits-exceed reload replaces a device nothing lost, and every buffer and
257
+ // texture of the previous payload stayed allocated with it until GC.
258
+ // `watchDeviceLost` ignores the resulting `destroyed` reason. (Third leak
259
+ // pass, LEAK-06's edge)
241
260
  async function recoverDevice(bytecode) {
242
261
  if (!initialized) return;
243
262
  const bc = bytecode ?? lastBytecode;
@@ -246,6 +265,9 @@ export function createWorkerHandlers(env, opts = {}) {
246
265
  // rebuilds an empty stack unconditionally, matching the original workers.
247
266
  if (!bc && selfRecover) return;
248
267
  moduleLoaded = false;
268
+ gpu?.destroy();
269
+ gpuDirty = false;
270
+ device?.destroy();
249
271
  await setupGpuStack(bc); // fresh device clears deviceLost; re-applies authored limits
250
272
  if (bc) await loadBytecode(bc);
251
273
  post({ type: MSG.DEVICE_RESTORED });
@@ -368,13 +390,19 @@ export function createWorkerHandlers(env, opts = {}) {
368
390
  // for input, init() to emit resource-creation commands, frame() to render,
369
391
  // getCommandPtr/getCommandLen for the command-buffer output.
370
392
  async function loadBytecode(bytecode) {
371
- // Reset GPU state if reloading
372
- if (moduleLoaded) {
393
+ // Reset GPU state if the dispatcher has executed anything. Keyed on
394
+ // `gpuDirty`, not `moduleLoaded`: the latter is set only on SUCCESS, so a
395
+ // load whose init stream rejected midway (an undecodable image blob, a
396
+ // refused wasm module) left its half-filled dispatcher in place and the
397
+ // next load ran on it — every create guard then skipped the new payload's
398
+ // resources for ids the failed one had filled. (Third leak pass)
399
+ if (gpuDirty) {
373
400
  gpu.destroy();
374
401
  wireDispatcher();
375
- moduleLoaded = false;
376
- uniformMap = null;
402
+ gpuDirty = false;
377
403
  }
404
+ moduleLoaded = false;
405
+ uniformMap = null;
378
406
 
379
407
  // Split PNGB: bytecode (small) → bytecodePtr, data section (large) → dataPtr
380
408
  const bytecodeArray = bytecode instanceof Uint8Array ? bytecode : new Uint8Array(bytecode);
@@ -388,13 +416,16 @@ export function createWorkerHandlers(env, opts = {}) {
388
416
  new Uint8Array(memory.buffer, bytecodePtr, dataOffset).set(bytecodeArray.subarray(0, dataOffset));
389
417
  wasm.setBytecodeLen(dataOffset);
390
418
 
391
- // Data section → separate data buffer (avoids bytecode buffer overflow for large payloads)
419
+ // Data section → separate data buffer (avoids bytecode buffer overflow for large payloads).
420
+ // setDataLen is called EVERY load — with 0 for an empty section, which the
421
+ // ABI defines as single-buffer mode — so a reload never inherits the
422
+ // previous payload's data length.
392
423
  const dataLen = dataEnd - dataOffset;
393
424
  if (dataLen > 0) {
394
425
  const dataPtr = wasm.getDataPtr();
395
426
  new Uint8Array(memory.buffer, dataPtr, dataLen).set(bytecodeArray.subarray(dataOffset, dataEnd));
396
- wasm.setDataLen(dataLen);
397
427
  }
428
+ wasm.setDataLen(dataLen);
398
429
 
399
430
  // Parse uniform table from bytecode before init (for runtime reflection)
400
431
  const { uniforms } = parseUniformTable(bytecodeArray);
@@ -409,10 +440,12 @@ export function createWorkerHandlers(env, opts = {}) {
409
440
  throw new Error(`Init failed: ${initResult}`);
410
441
  }
411
442
 
412
- // Execute the init command buffer (creates GPU resources)
443
+ // Execute the init command buffer (creates GPU resources). The dispatcher
444
+ // is dirty from here on, whether or not the stream completes.
413
445
  const initPtr = wasm.getCommandPtr();
414
446
  const initLen = wasm.getCommandLen();
415
447
  if (initPtr && initLen > 0) {
448
+ gpuDirty = true;
416
449
  await gpu.execute(initPtr);
417
450
  }
418
451
 
@@ -483,8 +516,18 @@ export function createWorkerHandlers(env, opts = {}) {
483
516
  gpu?.resizeCanvasBound?.(data.width, data.height);
484
517
  }
485
518
 
519
+ // Release everything this worker owns and tell the host it may terminate us.
520
+ //
521
+ // The ack is what makes this run at all: destroy() used to post `destroy` and
522
+ // terminate on the very next line, which discards the undelivered message —
523
+ // so this function was dead code on the normal path and the GPUDevice was
524
+ // left to the browser's reclamation of the worker agent. Now the host waits
525
+ // for MSG.DESTROYED (or a 250ms fallback), which also means the nulling below
526
+ // is load-bearing rather than ceremony: between the ack and the terminate
527
+ // this worker genuinely outlives its device.
486
528
  function handleDestroy() {
487
529
  moduleLoaded = false;
530
+ initialized = false;
488
531
  uniformMap = null;
489
532
  prefetch?.destroy();
490
533
  gpu?.destroy();
@@ -492,7 +535,20 @@ export function createWorkerHandlers(env, opts = {}) {
492
535
  device.destroy();
493
536
  device = null;
494
537
  }
495
- initialized = false;
538
+ // Drop the big retained references: the executor's WASM memory (its .bss
539
+ // arrays are the executor's entire state), the last payload, and the
540
+ // canvas/context pair holding the OffscreenCanvas.
541
+ gpu = null;
542
+ wasm = null;
543
+ memory = null;
544
+ lastBytecode = null;
545
+ context = null;
546
+ canvas = null;
547
+ prefetch = null;
548
+ // The lock's tail retains the last render closure (canvas, dims) on a
549
+ // worker that the destroy ack deliberately lets outlive its device.
550
+ renderLock = Promise.resolve();
551
+ post({ type: MSG.DESTROYED });
496
552
  }
497
553
 
498
554
  // Set a uniform value without triggering a draw.
@@ -526,6 +582,27 @@ export function createWorkerHandlers(env, opts = {}) {
526
582
  post({ type: MSG.UNIFORMS, uniforms });
527
583
  }
528
584
 
585
+ // Report live GPU-resource counts + the executor's WASM memory size.
586
+ //
587
+ // The instrument for a long-running session: everything else the host can see
588
+ // (heap size, frame rate) is downstream of GC timing, while these are what
589
+ // the runtime believes it still owns. Two properties are worth asserting in a
590
+ // soak, and both are stated here rather than inferred:
591
+ // • `gpu.live.*` flat across frames — the runtime creates nothing per frame.
592
+ // • `wasmBytes` constant — the shipped executor has NO allocator (its state
593
+ // is static .bss arrays, and nothing in src/ calls @wasmMemoryGrow), so a
594
+ // growing WASM memory is itself a bug signal, not normal churn.
595
+ function handleGetStats() {
596
+ post({
597
+ type: MSG.STATS,
598
+ gpu: gpu?.getStats?.() ?? null,
599
+ wasmBytes: memory?.buffer?.byteLength ?? 0,
600
+ frameCount,
601
+ moduleLoaded,
602
+ deviceLost,
603
+ });
604
+ }
605
+
529
606
  // WASM imports for the shared wasmUrl executor path (dev only).
530
607
  function getWasmImports() {
531
608
  return {
@@ -558,7 +635,7 @@ export function createWorkerHandlers(env, opts = {}) {
558
635
  }
559
636
  }
560
637
 
561
- async function dispatch(message) {
638
+ async function dispatchOne(message) {
562
639
  const { type, ...data } = message;
563
640
  try {
564
641
  switch (type) {
@@ -572,7 +649,11 @@ export function createWorkerHandlers(env, opts = {}) {
572
649
  await handleLoad(data);
573
650
  break;
574
651
  case MSG.RESTART:
575
- await recoverDevice(data.bytecode);
652
+ try {
653
+ await recoverDevice(data.bytecode);
654
+ } catch (err) {
655
+ throw new Error(`GPU recovery failed: ${err instanceof Error ? err.message : String(err)}`);
656
+ }
576
657
  break;
577
658
  case MSG.DESTROY:
578
659
  handleDestroy();
@@ -583,6 +664,9 @@ export function createWorkerHandlers(env, opts = {}) {
583
664
  case MSG.GET_UNIFORMS:
584
665
  handleGetUniforms();
585
666
  break;
667
+ case MSG.GET_STATS:
668
+ handleGetStats();
669
+ break;
586
670
  case MSG.RESIZE:
587
671
  handleResize(data);
588
672
  break;
@@ -595,12 +679,73 @@ export function createWorkerHandlers(env, opts = {}) {
595
679
  }
596
680
  }
597
681
 
682
+ // One message at a time.
683
+ //
684
+ // Each Worker message is delivered as its own task, and both entries wire
685
+ // `onmessage = (e) => dispatch(e.data)` — so two handler BODIES overlap
686
+ // whenever the first is suspended when the second arrives. The window is
687
+ // narrower than "any two messages" and worth naming precisely: a chain of
688
+ // awaits that all settle as microtasks finishes before the next task is even
689
+ // delivered, so overlap needs a genuinely async step. gpu.execute() has two
690
+ // (create_image_bitmap 0x0B, init_wasm_module 0x30), which means any payload
691
+ // carrying a `(texture … :data …)` suspends its load across tasks — where the
692
+ // editor's compile-per-keystroke meets its own rAF draw loop.
693
+ //
694
+ // Overlap is not a scheduling nicety there. `load` runs
695
+ // `gpu.destroy(); wireDispatcher()` underneath a suspended `await
696
+ // gpu.execute()`, and the resumed execute keeps driving the dispatcher just
697
+ // released — creating GPU objects into tables nothing will walk again. The
698
+ // mirror case is quieter and worse: a second load arriving while the first
699
+ // holds `moduleLoaded` false skips the reset branch entirely and inherits a
700
+ // LIVE dispatcher's tables, so the payload it replaced is never released at
701
+ // all. `withRenderLock` serializes only draw-vs-prefetch and cannot see any
702
+ // of this.
703
+ //
704
+ // FIFO, and the chain never rejects — dispatchOne reports its own errors —
705
+ // mirroring withRenderLock's shape.
706
+ let chain = Promise.resolve();
707
+ // Superseded rAF draws are dropped rather than rendered back-to-back once the
708
+ // stall clears: a frame whose time has already been overtaken is work nobody
709
+ // will see. A draw carrying `uniforms` is NEVER dropped — that state is
710
+ // host-supplied (anim.js draw(p, {uniforms})) and the next frame does not
711
+ // re-send it, so collapsing it would silently lose a write.
712
+ let queuedDraws = 0;
713
+ function dispatch(message) {
714
+ const supersedable = message.type === MSG.DRAW && !message.uniforms;
715
+ if (supersedable) queuedDraws++;
716
+ const run = () => {
717
+ if (supersedable && --queuedDraws > 0) return;
718
+ return dispatchOne(message);
719
+ };
720
+ const done = chain.then(run, run);
721
+ chain = done.then(
722
+ () => {},
723
+ () => {},
724
+ );
725
+ return done;
726
+ }
727
+
598
728
  // Build the prefetch capability now that the spine it layers over exists.
599
729
  if (makePrefetch) {
600
730
  prefetch = makePrefetch({
601
731
  env,
602
732
  post,
603
733
  render,
734
+ // Thumbnails must be side-effect-free: wasm.frame() advances the
735
+ // executor's frame_counter, which IS the ping-pong pool phase, so an
736
+ // odd number of thumbnail renders between live frames would invert
737
+ // every pooled binding. Save/restore the counter around the render;
738
+ // executors older than the additive setFrameCounter export keep the
739
+ // historical drift (`wasm` is read at call time — it is null while
740
+ // this capability is being built).
741
+ renderEphemeral: async (t, w, h) => {
742
+ const save = typeof wasm?.setFrameCounter === "function" ? wasm.getFrameCounter() : undefined;
743
+ try {
744
+ await render(t, w, h);
745
+ } finally {
746
+ if (save !== undefined) wasm.setFrameCounter(save);
747
+ }
748
+ },
604
749
  getCanvas: () => canvas,
605
750
  getGpu: () => gpu,
606
751
  loaded: () => moduleLoaded,
@@ -16,6 +16,16 @@
16
16
  // withRenderLock(fn) — serializes fn against handleDraw's live render, so a
17
17
  // live 'draw' can never share the offscreen render
18
18
  // target a still-in-flight prefetch render left active
19
+ //
20
+ // OWNERSHIP CONTRACT — `{type: "thumbnail", index, bitmap}`:
21
+ // the ImageBitmap is TRANSFERRED, so the worker gives up its only reference the
22
+ // moment it posts. The HOST owns it from there and MUST call `bitmap.close()`
23
+ // once it has drawn or uploaded it. An ImageBitmap holds decoded pixel memory
24
+ // that no GC pressure reliably reclaims on its own, and a scrubbing timeline
25
+ // emits one per thumb block — so a host that only drops the reference
26
+ // accumulates megabytes for the length of the session. This is the one
27
+ // lifetime rule the engine cannot enforce for its consumer; it is stated here
28
+ // because this file defines the message.
19
29
 
20
30
  export function createPrefetch(host) {
21
31
  const { env, post } = host;
@@ -50,7 +60,7 @@ export function createPrefetch(host) {
50
60
  // pipelines/buffers/bind groups stay valid across target swaps; the only
51
61
  // per-target variance is which context resolves the canvas-magic id. The
52
62
  // canvas survives a device loss, so reuse it across recoveries.
53
- function configure(device, format, alphaMode = "premultiplied") {
63
+ function configure(device, format, alphaMode = "opaque") {
54
64
  const canvas = host.getCanvas();
55
65
  if (!prefetchCanvas) prefetchCanvas = env.makeOffscreen(canvas.width, canvas.height);
56
66
  prefetchCtx = prefetchCanvas.getContext("webgpu");
@@ -132,9 +142,14 @@ export function createPrefetch(host) {
132
142
  if (!prefetchCtx || !prefetchCanvas) return;
133
143
  if (prefetchQueue.size === 0) return;
134
144
  prefetchDraining = true;
135
- const gpu = host.getGpu();
136
145
  try {
137
146
  while (prefetchQueue.size > 0 && host.loaded()) {
147
+ // Read the dispatcher INSIDE the loop: this drain yields between
148
+ // thumbnails, and a `load` landing in that yield replaces worker-core's
149
+ // dispatcher — a reference captured once would route the next
150
+ // thumbnail's render target onto a dispatcher the live draw no longer
151
+ // uses, or set the prefetch context on a destroyed one.
152
+ const gpu = host.getGpu();
138
153
  // The queue is a Map (index → uniforms): read its uniforms before delete.
139
154
  const idx = prefetchQueue.keys().next().value;
140
155
  const uniforms = prefetchQueue.get(idx);
@@ -154,7 +169,10 @@ export function createPrefetch(host) {
154
169
  // live frame does. null/absent leaves the shader's own defaults.
155
170
  if (uniforms) gpu.setUniforms(uniforms);
156
171
  const centerTime = Math.min((idx + 0.5) * thumbSecondsPerBlock, thumbMaxTime);
157
- await host.render(centerTime, prefetchCanvas.width, prefetchCanvas.height);
172
+ // renderEphemeral restores the executor frame counter afterwards
173
+ // (thumbnails must not shift ping-pong pool phase); fall back for
174
+ // hosts built before it existed.
175
+ await (host.renderEphemeral ?? host.render)(centerTime, prefetchCanvas.width, prefetchCanvas.height);
158
176
  } finally {
159
177
  gpu.setRenderTargetContext(null);
160
178
  }
@@ -8,7 +8,6 @@ import { browserEnv, createWorkerHandlers } from "./worker-core.js";
8
8
  const { dispatch } = createWorkerHandlers(browserEnv(), {
9
9
  allowWasmUrl: false,
10
10
  selfRecover: true,
11
- prefetch: false,
12
11
  });
13
12
 
14
13
  onmessage = (e) => dispatch(e.data);
Binary file
package/wasm/pngine.wasm CHANGED
Binary file