feat(producer): add pngDecodeBlitWorkerPool (hf#732 PR 2/5) (#757)

## Summary

PR 2 of 5 in the hf#732 decomposition stack. Adds a `worker_threads`-based pool that offloads PNG decode + alpha-blit onto a fixed-size pool. **No production wiring yet** — the pool stands alone and ships behind a later PR in the stack.

### New files

- `packages/producer/src/services/pngDecodeBlitWorker.ts` — worker entry. Imports from `@hyperframes/engine/alpha-blit` (zero-import TS source, survives the `new Worker(<path>)` loader boundary).
- `packages/producer/src/services/pngDecodeBlitWorkerPool.ts` — fixed-size pool with `run()` API. Uses `transferList` for buffer ownership transfer (no 16bpc HDR buffer copies).
- `packages/producer/src/services/pngDecodeBlitWorkerPool.test.ts` — 6 vitest tests pinning byte-equivalence with inline path, transferList correctness, concurrent dispatch, termination semantics. All pass.

### Build wiring

- `packages/cli/tsup.config.ts`: second tsup entry emits `dist/pngDecodeBlitWorker.js` next to `dist/cli.js`. Without this entry the pool's `new Worker(<path>)` would fail at runtime in the shipped CLI.
- `packages/producer/build.mjs`: third esbuild entry mirrors the wiring for direct producer consumers.
- `packages/engine/package.json`: adds `./alpha-blit` subpath export pointing at `src/utils/alphaBlit.ts`.

## Stack

Stacked on top of #756 (PR 1: worker-count cap). No behavior change in any render.

## Test plan

- [x] 6 pool tests pass
- [x] Producer + engine typecheck clean
- [x] oxlint clean

— Vai

Author: vanceingalls

packages/cli/tsup.config.ts

@@ -7,7 +7,19 @@ const pkg = JSON.parse(readFileSync(new URL("./package.json", import.meta.url),
 };
 
 export default defineConfig({
-  entry: ["src/cli.ts"],
+  // hf#732 lever-4: emit BOTH the CLI bundle and the PNG decode + alpha-blit
+  // worker entry. The producer's `pngDecodeBlitWorkerPool` instantiates a
+  // Node `worker_threads` Worker via `new Worker(<path>)`, which is a
+  // filesystem load — it cannot share the parent module graph. The pool's
+  // path resolver probes for `pngDecodeBlitWorker.js` next to its own loaded
+  // module (which lives inside `dist/cli.js` after the producer is
+  // `noExternal`'d and bundled in). Without this entry the file would not
+  // exist at runtime and the pool would either crash or silently fall back
+  // to inline decode/blit, killing the perf gain.
+  entry: {
+    cli: "src/cli.ts",
+    pngDecodeBlitWorker: "../producer/src/services/pngDecodeBlitWorker.ts",
+  },
   format: ["esm"],
   outDir: "dist",
   target: "node22",
@@ -56,6 +68,10 @@ var __dirname = __hf_dirname(__filename);`,
   esbuildOptions(options) {
     options.alias = {
       "@hyperframes/producer": resolve(__dirname, "../producer/src/index.ts"),
+      // hf#732 lever-4: alias for the PNG decode+blit worker's import.
+      // `alphaBlit.ts` is import-free (only zlib) so the worker survives
+      // the worker_thread loader boundary directly via this TS source.
+      "@hyperframes/engine/alpha-blit": resolve(__dirname, "../engine/src/utils/alphaBlit.ts"),
     };
     options.loader = { ...options.loader, ".browser.js": "text" };
   },

packages/engine/package.json

@@ -11,7 +11,8 @@
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./alpha-blit": "./src/utils/alphaBlit.ts"
   },
   "scripts": {
     "build": "tsc",

packages/producer/build.mjs

@@ -21,6 +21,9 @@ const workspaceAliasPlugin = {
     build.onResolve({ filter: /^@hyperframes\/engine$/ }, () => ({
       path: resolve(scriptDir, "../engine/src/index.ts"),
     }));
+    build.onResolve({ filter: /^@hyperframes\/engine\/alpha-blit$/ }, () => ({
+      path: resolve(scriptDir, "../engine/src/utils/alphaBlit.ts"),
+    }));
     build.onResolve({ filter: /^@hyperframes\/core$/ }, () => ({
       path: resolve(scriptDir, "../core/src/index.ts"),
     }));
@@ -55,6 +58,22 @@ await Promise.all([
     entryPoints: ["src/server.ts"],
     outfile: "dist/public-server.js",
   }),
+  // PNG decode + alpha-blit worker (hf#732 lever-4). Loaded by
+  // `pngDecodeBlitWorkerPool.createPngDecodeBlitWorkerPool` via
+  // `new Worker(<path>)`. Must be a separate entry point so the worker
+  // module is standalone and shares no parent module-graph state.
+  build({
+    bundle: true,
+    platform: "node",
+    target: "node22",
+    format: "esm",
+    external: ["puppeteer", "esbuild", "postcss"],
+    plugins: [workspaceAliasPlugin],
+    minify: false,
+    sourcemap: true,
+    entryPoints: ["src/services/pngDecodeBlitWorker.ts"],
+    outfile: "dist/services/pngDecodeBlitWorker.js",
+  }),
 ]);
 
 // Copy core runtime artifacts so the producer can find them at dist/

packages/producer/src/services/pngDecodeBlitWorker.ts

@@ -0,0 +1,122 @@
+/**
+ * Worker entry point for off-main-thread PNG decode + alpha blit. The
+ * companion to `pngDecodeBlitWorkerPool.ts`. See that file for the rationale
+ * (hf#732 lever-4: overlap Chrome's screenshot with Node's decode+blit).
+ *
+ * Lifecycle:
+ *
+ * 1. Pool constructor spawns N of these workers up front.
+ * 2. Main thread posts `{ png, pngOffset, pngLength, dest, destOffset,
+ *    destLength, width, height, transfer }` with `transferList: [png, dest]`.
+ *    Both underlying ArrayBuffers are detached on the sender; the caller
+ *    must NOT touch them until the worker replies.
+ * 3. Worker wraps each ArrayBuffer as a Node Buffer view (zero-copy),
+ *    runs `decodePng` to get an RGBA8 Uint8Array, then `blitRgba8OverRgb48le`
+ *    to composite the decoded pixels onto the rgb48le `dest` buffer in
+ *    the requested transfer space.
+ * 4. Worker posts `{ ok, png, dest, decodeMs, blitMs }` back with
+ *    `transferList: [png, dest]`. Both ArrayBuffers return to the main
+ *    thread; the caller swaps `result.dest` into its render state.
+ * 5. On decode/blit exception, worker posts `{ ok: false, error, png,
+ *    dest }` — both ArrayBuffers still returned so the caller can release
+ *    them.
+ *
+ * The worker holds no per-frame state. The intermediate RGBA8 decode
+ * buffer is allocated per-call and dropped on the worker side.
+ *
+ * Import strategy: identical to `shaderTransitionWorker.ts` — use the
+ * `./alpha-blit` subpath export of `@hyperframes/engine` rather than the
+ * package root, because the root pulls in the full engine graph and the
+ * tsx loader's `.js → .ts` rewrite does not survive the Worker boundary
+ * under dev/test.
+ */
+
+import { parentPort } from "node:worker_threads";
+import { decodePng, blitRgba8OverRgb48le } from "@hyperframes/engine/alpha-blit";
+
+interface DecodeBlitJobRequest {
+  png: ArrayBuffer;
+  pngOffset: number;
+  pngLength: number;
+  dest: ArrayBuffer;
+  destOffset: number;
+  destLength: number;
+  width: number;
+  height: number;
+  transfer: string;
+}
+
+interface DecodeBlitJobOk {
+  ok: true;
+  png: ArrayBuffer;
+  dest: ArrayBuffer;
+  decodeMs: number;
+  blitMs: number;
+}
+
+interface DecodeBlitJobErr {
+  ok: false;
+  error: string;
+  png: ArrayBuffer;
+  dest: ArrayBuffer;
+}
+
+export type DecodeBlitJobResult = DecodeBlitJobOk | DecodeBlitJobErr;
+
+if (!parentPort) {
+  // Defensive — this module is only meaningful inside a worker_thread.
+  // eslint-disable-next-line no-console
+  console.warn("[pngDecodeBlitWorker] no parentPort; module loaded on main thread");
+} else {
+  parentPort.on("message", (msg: DecodeBlitJobRequest) => {
+    const { png, pngOffset, pngLength, dest, destOffset, destLength, width, height, transfer } =
+      msg;
+    // Re-wrap the transferred ArrayBuffers as Node Buffer views. The
+    // dispatcher in the pool normalizes inputs to offset-0 ArrayBuffers
+    // before transfer (avoiding the 8KB shared-pool DataCloneError), so
+    // pngOffset / destOffset are 0 and pngLength / destLength match the
+    // backing ArrayBuffer byteLength in practice. We still honor the
+    // forwarded values so the worker is robust if the dispatcher ever
+    // changes (e.g. ships a slice over a larger transferred ArrayBuffer).
+    const pngBuf = Buffer.from(png, pngOffset, pngLength);
+    const destBuf = Buffer.from(dest, destOffset, destLength);
+
+    try {
+      const decodeStart = Date.now();
+      const { data: rgba } = decodePng(pngBuf);
+      const decodeMs = Date.now() - decodeStart;
+
+      const blitStart = Date.now();
+      // `blitRgba8OverRgb48le` accepts the CompositeTransfer string as a
+      // typed union. The pool's `transfer` field is `string` for transport
+      // simplicity; the actual values flow through unchanged from the
+      // orchestrator's HdrCompositeContext and the function validates at
+      // its own boundary.
+      blitRgba8OverRgb48le(
+        rgba,
+        destBuf,
+        width,
+        height,
+        transfer as Parameters<typeof blitRgba8OverRgb48le>[4],
+      );
+      const blitMs = Date.now() - blitStart;
+
+      const reply: DecodeBlitJobOk = {
+        ok: true,
+        png,
+        dest,
+        decodeMs,
+        blitMs,
+      };
+      parentPort!.postMessage(reply, [png, dest]);
+    } catch (err) {
+      const reply: DecodeBlitJobErr = {
+        ok: false,
+        error: err instanceof Error ? err.message : String(err),
+        png,
+        dest,
+      };
+      parentPort!.postMessage(reply, [png, dest]);
+    }
+  });
+}