refactor(producer): simplify — extract HDR compositor, delete dead code, consolidate patterns (#1414)

* refactor(producer): extract HDR compositor from renderOrchestrator

Move ~700 LOC of HDR compositing primitives (countNonZeroAlpha,
countNonZeroRgb48, cropRgb48le, HdrVideoFrameSource,
closeHdrVideoFrameSource, blitHdrVideoLayer, HdrImageBuffer,
blitHdrImageLayer, CompositeTransfer, shouldUseLayeredComposite,
resolveCompositeTransfer, HdrCompositeContext, compositeHdrFrame,
HdrTransitionMeta, TransitionRange) into a dedicated
hdrCompositor.ts module.

Remove backward-compat re-exports from renderOrchestrator (hdrPerf,
captureCost, shared) and rewire all import sites to the
authoritative source modules.

* refactor(producer): delete 4 re-export shim files

screenshotService.ts, videoFrameExtractor.ts, videoFrameInjector.ts,
and streamingEncoder.ts existed solely to re-export symbols from
@hyperframes/engine. No internal consumer imported from them except
index.ts → videoFrameInjector, which now imports directly from engine.

* refactor(producer): delete unused PNG decode/blit worker pool

The pool (455 LOC) and worker (127 LOC) were built speculatively for
pipelining Chrome screenshots with PNG decode/blit but were never
wired into any capture path. Zero non-test source files imported them.

Also removed the esbuild entry point from producer/build.mjs, the
tsup entry point + alpha-blit alias from cli/tsup.config.ts, and
the PNG worker bootstrap from cli/src/cli.ts.

* refactor(producer): centralize frame filename construction

Replace 4 inline padStart(6) template literals with shared helpers:
- formatCaptureFrameName(index, ext): zero-based, for internal capture
- formatExportFrameName(index, ext): zero-based input, one-based output
  for user-facing png-sequence export

* perf(producer): hoist allElementIds out of compositing loop

Move fullStacking.map() from inside the per-layer iteration to before
the loop, computing the element ID list once per frame instead of once
per DOM layer per frame.

* refactor(producer): consolidate HDR timing instrumentation

* refactor(producer): remove typecasts and deduplicate HDR capture patterns

- Extract seekInjectAndQueryStacking() and seekAndInject() helpers to
  deduplicate the seek+inject+query pattern across sequential loop,
  hybrid loop, and per-scene transition capture (3 call sites → 1 helper)
- Fix sceneBuf as Buffer casts by properly typing the scene-capture
  arrays as [Buffer, Set<string>][] instead of using as const + cast
- Replace as NonNullable<> cast on outputFormat with as const fallback
- Add explanatory comments on inherent linkedom DOM casts

* refactor(producer): name constants, type matrix, extract opacity helper

- Replace magic 0.001/0.999 with TRANSFORM_IDENTITY_EPSILON and
  OPAQUE_ALPHA_THRESHOLD; replace BPP=6 with RGB48_BYTES_PER_PIXEL
- Add AffineMatrix tuple type + isAffineMatrix guard, eliminating
  all 4 non-null assertions on matrix indices
- Extract resolveBlitOpacity() to replace 5 identical ternaries
- Narrow fallow-ignore-file to line-level complexity suppressions

Author: miguel-heygen

packages/cli/src/cli.ts

@@ -22,34 +22,24 @@ for (const stream of [process.stdout, process.stderr]) {
 }
 
 // ── Worker entry path bootstrap (must run before any producer/engine load) ──
-// The hf#677 worker_threads pools (`pngDecodeBlitWorkerPool`,
-// `shaderTransitionWorkerPool`) live in the producer package and try to
-// resolve their worker entry by probing for sibling `.js` files next to
+// The shaderTransitionWorkerPool lives in the producer package and resolves
+// its worker entry by probing for a sibling `.js` file next to
 // `import.meta.url`. When this CLI is bundled by tsup, the producer code is
 // inlined into `cli.js`, but `import.meta.url` resolves to the producer's
 // own dist path (NOT cli.js) on some module-graph layouts — so the sibling
-// probe lands in a directory that does not contain the bundled workers.
-// We emit the worker entries next to cli.js (see tsup.config.ts) and tell
-// the pools where to find them via the published env-var overrides. The
-// pools have an explicit `workerEntryPath` factory option as the canonical
-// API, but setting the env vars here covers every call site without having
-// to thread the path through the renderOrchestrator → captureHdrStage →
-// captureHdrHybridLoop chain.
+// probe lands in a directory that does not contain the bundled worker.
+// We emit the worker entry next to cli.js (see tsup.config.ts) and tell
+// the pool where to find it via the published env-var override.
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { existsSync } from "node:fs";
 
-// fallow-ignore-next-line complexity
 (() => {
   const here = dirname(fileURLToPath(import.meta.url));
   const shader = join(here, "shaderTransitionWorker.js");
-  const png = join(here, "pngDecodeBlitWorker.js");
   if (!process.env.HF_SHADER_WORKER_ENTRY && existsSync(shader)) {
     process.env.HF_SHADER_WORKER_ENTRY = shader;
   }
-  if (!process.env.HF_PNG_DECODE_BLIT_WORKER_ENTRY && existsSync(png)) {
-    process.env.HF_PNG_DECODE_BLIT_WORKER_ENTRY = png;
-  }
 })();
 
 // ── Fast-path exits ─────────────────────────────────────────────────────────

packages/cli/tsup.config.ts

@@ -7,20 +7,8 @@ const pkg = JSON.parse(readFileSync(new URL("./package.json", import.meta.url),
 };
 
 export default defineConfig({
-  // 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",
-    // hf#677/#732: shader-blend worker. Same `new Worker(<path>)`
-    // bundling rationale as `pngDecodeBlitWorker` above.
     shaderTransitionWorker: "../producer/src/services/shaderTransitionWorker.ts",
   },
   format: ["esm"],
@@ -96,10 +84,6 @@ var __dirname = __hf_dirname(__filename);`,
       "@hyperframes/aws-lambda/sdk": resolve(__dirname, "../aws-lambda/src/sdk/index.ts"),
       // Same for the GCP adapter's SDK subpath barrel.
       "@hyperframes/gcp-cloud-run/sdk": resolve(__dirname, "../gcp-cloud-run/src/sdk/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"),
       // hf#677 follow-up: the shader-blend worker imports from
       // `@hyperframes/engine/shader-transitions` (subpath export) — a
       // standalone TS file with zero internal imports that survives the

packages/producer/build.mjs

@@ -59,11 +59,6 @@ const sharedOpts = {
 await Promise.all([
   build({ ...sharedOpts, entryPoints: ["src/index.ts"], outfile: "dist/index.js" }),
   build({ ...sharedOpts, entryPoints: ["src/server.ts"], outfile: "dist/public-server.js" }),
-  build({
-    ...sharedOpts,
-    entryPoints: ["src/services/pngDecodeBlitWorker.ts"],
-    outfile: "dist/services/pngDecodeBlitWorker.js",
-  }),
   build({
     ...sharedOpts,
     entryPoints: ["src/services/shaderTransitionWorker.ts"],

packages/producer/src/index.ts

@@ -52,7 +52,7 @@ export {
 } from "./services/fileServer.js";
 
 // ── Video frame injection (Hyperframes-specific hook) ───────────────────────
-export { createVideoFrameInjector } from "./services/videoFrameInjector.js";
+export { createVideoFrameInjector } from "@hyperframes/engine";
 
 // ── Configuration ───────────────────────────────────────────────────────────
 export { resolveConfig, DEFAULT_CONFIG, type ProducerConfig } from "./config.js";

packages/producer/src/services/distributed/assemble.ts

@@ -37,6 +37,7 @@ import { dirname, join } from "node:path";
 import { applyFaststart, muxVideoWithAudio, runFfmpeg } from "@hyperframes/engine";
 import { fpsToFfmpegArg } from "@hyperframes/core";
 import { defaultLogger, type ProducerLogger } from "../../logger.js";
+import { formatExportFrameName } from "../../utils/paths.js";
 import { padOrTrimAudioToVideoFrameCount } from "../render/audioPadTrim.js";
 import type { ChunkSliceJson } from "../render/stages/freezePlan.js";
 import type { DistributedFormat } from "./shared.js";
@@ -397,7 +398,7 @@ function mergePngFrameDirs(
       throw new Error(`[assemble] png-sequence chunk has no frames: ${chunkDir}`);
     }
     for (const frame of frames) {
-      const dst = join(outputPath, `frame_${String(globalIdx + 1).padStart(6, "0")}.png`);
+      const dst = join(outputPath, formatExportFrameName(globalIdx, "png"));
       cpSync(join(chunkDir, frame), dst);
       globalIdx += 1;
     }