@hyperframes/engine 0.7.59 → 0.7.61

package/dist/utils/gpuParityDiff.js

@@ -0,0 +1,205 @@
+/**
+ * GPU Parity Diff — diagnostic helpers for detecting shape-dependent
+ * hardware-GPU capture bugs by comparing frames captured via the two
+ * capture paths (hardware-GPU vs software-GPU / screenshot bypass).
+ *
+ * Field pattern this exists to catch:
+ *
+ *   • ts=1784049136 · hardware-GPU capture emitted intermittent black
+ *     rectangles in one scene; `--no-browser-gpu --low-memory-mode
+ *     --workers 1` (software-GPU screenshot mode) resolved it.
+ *   • ts=1784032286 · animated `clip-path` on a large image → intermittent
+ *     black rectangles from Chrome capture; deterministic precomposited
+ *     swipe states removed the artifact.
+ *   • Baseline · JetBrains Mono glyph-drop on parallel/BeginFrame text
+ *     capture.
+ *
+ * Common shape: hardware-GPU writes solid-black regions where content
+ * should exist; software-GPU / screenshot fallback renders the same
+ * region correctly. A raw per-pixel diff is a coarse signal for this —
+ * on its own it fires on every animation frame's compositor jitter, so
+ * this module also isolates the *asymmetric* black-in-A-only pattern
+ * that is the diagnostic fingerprint of the bug.
+ *
+ * This module is the reduced-scope first pass: a pure helper + unit
+ * tests. Wiring a `hyperframes verify-gpu-parity` CLI surface, capture
+ * orchestration, and integration coverage is intentionally deferred to
+ * a follow-up so the diagnostic primitive can land and be exercised
+ * against real captured frames in isolation.
+ */
+import { decodePng } from "./alphaBlit.js";
+// ── Defaults ────────────────────────────────────────────────────────────────
+const DEFAULT_PIXEL_CHANNEL_TOLERANCE = 8;
+const DEFAULT_BLACK_SUM_THRESHOLD = 12;
+const DEFAULT_CONTENT_SUM_THRESHOLD = 32;
+const DEFAULT_BLACK_ONLY_FRACTION_THRESHOLD = 0.001;
+// ── Core diff ───────────────────────────────────────────────────────────────
+/**
+ * Compare two RGBA frames captured via different GPU paths.
+ *
+ * The two inputs must have identical dimensions; on mismatch this throws
+ * (with the mismatched sizes surfaced in the message) so callers cannot
+ * silently compare misaligned frames.
+ *
+ * Alpha channel is *not* considered for the black-only detection — Chrome's
+ * capture output is opaque along the code paths this diagnostic targets,
+ * and considering alpha would false-positive on legitimately transparent
+ * pixels. `pixelChannelTolerance` also compares only R/G/B for the same
+ * reason.
+ */
+export function diffGpuParityFrames(a, b, options = {}) {
+    if (a.width !== b.width || a.height !== b.height) {
+        throw new Error(`diffGpuParityFrames: frame size mismatch — A is ${a.width}x${a.height}, ` +
+            `B is ${b.width}x${b.height}`);
+    }
+    const expectedLen = a.width * a.height * 4;
+    if (a.data.length !== expectedLen) {
+        throw new Error(`diffGpuParityFrames: frame A data length ${a.data.length} does not match ` +
+            `expected ${expectedLen} (${a.width}x${a.height} * 4)`);
+    }
+    if (b.data.length !== expectedLen) {
+        throw new Error(`diffGpuParityFrames: frame B data length ${b.data.length} does not match ` +
+            `expected ${expectedLen} (${b.width}x${b.height} * 4)`);
+    }
+    const tol = options.pixelChannelTolerance ?? DEFAULT_PIXEL_CHANNEL_TOLERANCE;
+    const blackSum = options.blackSumThreshold ?? DEFAULT_BLACK_SUM_THRESHOLD;
+    const contentSum = options.contentSumThreshold ?? DEFAULT_CONTENT_SUM_THRESHOLD;
+    if (contentSum <= blackSum) {
+        throw new Error(`diffGpuParityFrames: contentSumThreshold (${contentSum}) must be strictly greater ` +
+            `than blackSumThreshold (${blackSum}) — overlapping thresholds would double-classify ` +
+            `borderline pixels`);
+    }
+    const total = a.width * a.height;
+    const aData = a.data;
+    const bData = b.data;
+    let diffPixels = 0;
+    let blackOnlyAPixels = 0;
+    let blackOnlyBPixels = 0;
+    let aMinX = a.width;
+    let aMinY = a.height;
+    let aMaxX = -1;
+    let aMaxY = -1;
+    let bMinX = a.width;
+    let bMinY = a.height;
+    let bMaxX = -1;
+    let bMaxY = -1;
+    for (let y = 0; y < a.height; y++) {
+        for (let x = 0; x < a.width; x++) {
+            const i = (y * a.width + x) * 4;
+            const ar = aData[i] ?? 0;
+            const ag = aData[i + 1] ?? 0;
+            const ab = aData[i + 2] ?? 0;
+            const br = bData[i] ?? 0;
+            const bg = bData[i + 1] ?? 0;
+            const bb = bData[i + 2] ?? 0;
+            if (Math.abs(ar - br) > tol || Math.abs(ag - bg) > tol || Math.abs(ab - bb) > tol) {
+                diffPixels++;
+            }
+            const aSum = ar + ag + ab;
+            const bSum = br + bg + bb;
+            if (aSum <= blackSum && bSum >= contentSum) {
+                blackOnlyAPixels++;
+                if (x < aMinX)
+                    aMinX = x;
+                if (y < aMinY)
+                    aMinY = y;
+                if (x > aMaxX)
+                    aMaxX = x;
+                if (y > aMaxY)
+                    aMaxY = y;
+            }
+            else if (bSum <= blackSum && aSum >= contentSum) {
+                blackOnlyBPixels++;
+                if (x < bMinX)
+                    bMinX = x;
+                if (y < bMinY)
+                    bMinY = y;
+                if (x > bMaxX)
+                    bMaxX = x;
+                if (y > bMaxY)
+                    bMaxY = y;
+            }
+        }
+    }
+    return {
+        width: a.width,
+        height: a.height,
+        totalPixels: total,
+        diffPixels,
+        diffFraction: diffPixels / total,
+        blackOnlyInA: {
+            pixels: blackOnlyAPixels,
+            fraction: blackOnlyAPixels / total,
+            boundingBox: blackOnlyAPixels === 0
+                ? null
+                : { x: aMinX, y: aMinY, width: aMaxX - aMinX + 1, height: aMaxY - aMinY + 1 },
+        },
+        blackOnlyInB: {
+            pixels: blackOnlyBPixels,
+            fraction: blackOnlyBPixels / total,
+            boundingBox: blackOnlyBPixels === 0
+                ? null
+                : { x: bMinX, y: bMinY, width: bMaxX - bMinX + 1, height: bMaxY - bMinY + 1 },
+        },
+    };
+}
+/**
+ * PNG-buffer convenience wrapper around `diffGpuParityFrames`. Decodes
+ * both inputs via `decodePng` and delegates. Errors from the decoder are
+ * re-thrown with `cause` preserved so the failing side (A or B) is
+ * obvious in the stack.
+ */
+export function diffGpuParityPngs(pngA, pngB, options = {}) {
+    let a;
+    let b;
+    try {
+        a = decodePng(pngA);
+    }
+    catch (err) {
+        throw new Error(`diffGpuParityPngs: failed to decode frame A`, { cause: err });
+    }
+    try {
+        b = decodePng(pngB);
+    }
+    catch (err) {
+        throw new Error(`diffGpuParityPngs: failed to decode frame B`, { cause: err });
+    }
+    return diffGpuParityFrames(a, b, options);
+}
+/**
+ * Verdict wrapper — returns `{ ok, reason }` suitable for a follow-up
+ * CLI or gate to emit. `ok === false` when either black-only fraction
+ * exceeds `blackOnlyFractionThreshold`. Raw diff numbers are always
+ * included on both branches so callers can log or gate on their own
+ * metrics without a second pass.
+ */
+export function verifyGpuParity(a, b, options = {}) {
+    const diff = diffGpuParityFrames(a, b, options);
+    const threshold = options.blackOnlyFractionThreshold ?? DEFAULT_BLACK_ONLY_FRACTION_THRESHOLD;
+    if (diff.blackOnlyInA.fraction > threshold) {
+        const bb = diff.blackOnlyInA.boundingBox;
+        const region = bb ? ` (bbox ${bb.x},${bb.y} ${bb.width}x${bb.height})` : "";
+        return {
+            ok: false,
+            reason: `hardware-GPU frame has ${diff.blackOnlyInA.pixels} pixel(s) ` +
+                `(${(diff.blackOnlyInA.fraction * 100).toFixed(3)}%) that are solid-black ` +
+                `while software-GPU frame has content there${region} — likely shape-dependent ` +
+                `hardware-GPU capture bug`,
+            diff,
+        };
+    }
+    if (diff.blackOnlyInB.fraction > threshold) {
+        const bb = diff.blackOnlyInB.boundingBox;
+        const region = bb ? ` (bbox ${bb.x},${bb.y} ${bb.width}x${bb.height})` : "";
+        return {
+            ok: false,
+            reason: `software-GPU frame has ${diff.blackOnlyInB.pixels} pixel(s) ` +
+                `(${(diff.blackOnlyInB.fraction * 100).toFixed(3)}%) that are solid-black ` +
+                `while hardware-GPU frame has content there${region} — unexpected inverse ` +
+                `pattern, worth investigating`,
+            diff,
+        };
+    }
+    return { ok: true, reason: "", diff };
+}
+//# sourceMappingURL=gpuParityDiff.js.map

package/dist/utils/gpuParityDiff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpuParityDiff.js","sourceRoot":"","sources":["../../src/utils/gpuParityDiff.ts"],"names":[],"mappings":"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"}

package/dist/utils/managedChildProcess.d.ts

@@ -0,0 +1,50 @@
+import type { ChildProcess } from "node:child_process";
+export type ManagedProcessTerminationReason = "exit" | "abort" | "deadline" | "inactivity" | "spawn_error";
+export interface ManagedChildProcessOutcome {
+    reason: ManagedProcessTerminationReason;
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    stderr: string;
+    durationMs: number;
+    error?: Error;
+}
+export interface ManagedChildProcessOptions {
+    signal?: AbortSignal;
+    deadlineAtMs?: number;
+    inactivityTimeoutMs?: number;
+    terminationGraceMs?: number;
+    stderrMaxBytes?: number;
+    onStderr?: (chunk: string) => void;
+    now?: () => number;
+}
+/** Owns cancellation, escalation, stderr and reaping for one child process. */
+export declare class ManagedChildProcess {
+    readonly child: ChildProcess;
+    private readonly options;
+    private readonly startedAtMs;
+    private readonly now;
+    private readonly outcomePromise;
+    private resolveOutcome;
+    private requestedReason;
+    private stderrTail;
+    private spawned;
+    private settled;
+    private deadlineTimer;
+    private inactivityTimer;
+    private escalationTimer;
+    constructor(child: ChildProcess, options?: ManagedChildProcessOptions);
+    wait(): Promise<ManagedChildProcessOutcome>;
+    get isSettled(): boolean;
+    markActivity(): void;
+    private readonly onStderr;
+    private readonly onSpawn;
+    private readonly onClose;
+    private readonly onError;
+    private installAbort;
+    private readonly onAbort;
+    private installDeadline;
+    private requestTermination;
+    private settle;
+    private clearTimers;
+}
+//# sourceMappingURL=managedChildProcess.d.ts.map

package/dist/utils/managedChildProcess.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"managedChildProcess.d.ts","sourceRoot":"","sources":["../../src/utils/managedChildProcess.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,MAAM,MAAM,+BAA+B,GACvC,MAAM,GACN,OAAO,GACP,UAAU,GACV,YAAY,GACZ,aAAa,CAAC;AAElB,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,+BAA+B,CAAC;IACxC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAKD,+EAA+E;AAC/E,qBAAa,mBAAmB;IAe5B,QAAQ,CAAC,KAAK,EAAE,YAAY;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAf1B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAsC;IACrE,OAAO,CAAC,cAAc,CAAiD;IACvE,OAAO,CAAC,eAAe,CAChB;IACP,OAAO,CAAC,UAAU,CAAmB;IACrC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,aAAa,CAA+B;IACpD,OAAO,CAAC,eAAe,CAA+B;IACtD,OAAO,CAAC,eAAe,CAA+B;gBAG3C,KAAK,EAAE,YAAY,EACX,OAAO,GAAE,0BAA+B;IAiB3D,IAAI,IAAI,OAAO,CAAC,0BAA0B,CAAC;IAI3C,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,YAAY,IAAI,IAAI;IAUpB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAQvB;IAEF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAEtB;IAEF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAQtB;IAEF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAUtB;IAEF,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAEtB;IAEF,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,kBAAkB;IAyB1B,OAAO,CAAC,MAAM;IAYd,OAAO,CAAC,WAAW;CAQpB"}

package/dist/utils/managedChildProcess.js

@@ -0,0 +1,148 @@
+const DEFAULT_TERMINATION_GRACE_MS = 2_000;
+const DEFAULT_STDERR_MAX_BYTES = 64 * 1024;
+/** Owns cancellation, escalation, stderr and reaping for one child process. */
+export class ManagedChildProcess {
+    child;
+    options;
+    startedAtMs;
+    now;
+    outcomePromise;
+    resolveOutcome;
+    requestedReason = null;
+    stderrTail = Buffer.alloc(0);
+    spawned = false;
+    settled = false;
+    deadlineTimer = null;
+    inactivityTimer = null;
+    escalationTimer = null;
+    constructor(child, options = {}) {
+        this.child = child;
+        this.options = options;
+        this.now = options.now ?? Date.now;
+        this.startedAtMs = this.now();
+        this.outcomePromise = new Promise((resolve) => {
+            this.resolveOutcome = resolve;
+        });
+        child.stderr?.on("data", this.onStderr);
+        child.once("spawn", this.onSpawn);
+        child.once("close", this.onClose);
+        child.on("error", this.onError);
+        this.installAbort();
+        this.installDeadline();
+        this.markActivity();
+    }
+    wait() {
+        return this.outcomePromise;
+    }
+    get isSettled() {
+        return this.settled;
+    }
+    markActivity() {
+        if (this.settled || this.options.inactivityTimeoutMs === undefined)
+            return;
+        if (this.inactivityTimer)
+            clearTimeout(this.inactivityTimer);
+        this.inactivityTimer = setTimeout(() => this.requestTermination("inactivity"), Math.max(0, this.options.inactivityTimeoutMs));
+        this.inactivityTimer.unref?.();
+    }
+    onStderr = (data) => {
+        const chunk = Buffer.isBuffer(data) ? data : Buffer.from(data);
+        const maxBytes = this.options.stderrMaxBytes ?? DEFAULT_STDERR_MAX_BYTES;
+        this.stderrTail = Buffer.concat([this.stderrTail, chunk]);
+        if (this.stderrTail.byteLength > maxBytes) {
+            this.stderrTail = this.stderrTail.subarray(this.stderrTail.byteLength - maxBytes);
+        }
+        this.options.onStderr?.(chunk.toString());
+    };
+    onSpawn = () => {
+        this.spawned = true;
+    };
+    onClose = (exitCode, signal) => {
+        this.settle({
+            reason: this.requestedReason ?? "exit",
+            exitCode,
+            signal,
+            stderr: this.stderrTail.toString(),
+            durationMs: this.now() - this.startedAtMs,
+        });
+    };
+    onError = (error) => {
+        if (this.spawned)
+            return;
+        this.settle({
+            reason: "spawn_error",
+            exitCode: null,
+            signal: null,
+            stderr: this.stderrTail.length > 0 ? this.stderrTail.toString() : error.message,
+            durationMs: this.now() - this.startedAtMs,
+            error,
+        });
+    };
+    installAbort() {
+        const signal = this.options.signal;
+        if (!signal)
+            return;
+        if (signal.aborted) {
+            this.requestTermination("abort");
+            return;
+        }
+        signal.addEventListener("abort", this.onAbort, { once: true });
+    }
+    onAbort = () => {
+        this.requestTermination("abort");
+    };
+    installDeadline() {
+        if (this.options.deadlineAtMs === undefined)
+            return;
+        const remainingMs = Math.max(0, this.options.deadlineAtMs - this.now());
+        this.deadlineTimer = setTimeout(() => this.requestTermination("deadline"), remainingMs);
+        this.deadlineTimer.unref?.();
+    }
+    requestTermination(reason) {
+        if (this.settled || this.requestedReason)
+            return;
+        this.requestedReason = reason;
+        try {
+            this.child.kill("SIGTERM");
+        }
+        catch {
+            // A close/error event owns settlement; escalation remains the backstop.
+        }
+        const graceMs = this.options.terminationGraceMs ?? DEFAULT_TERMINATION_GRACE_MS;
+        this.escalationTimer = setTimeout(() => {
+            if (this.settled)
+                return;
+            try {
+                this.child.kill("SIGKILL");
+            }
+            catch {
+                // The child may have exited between the settled check and kill.
+            }
+        }, Math.max(0, graceMs));
+        this.escalationTimer.unref?.();
+    }
+    settle(outcome) {
+        if (this.settled)
+            return;
+        this.settled = true;
+        this.clearTimers();
+        this.options.signal?.removeEventListener("abort", this.onAbort);
+        this.child.stderr?.off("data", this.onStderr);
+        this.child.off("spawn", this.onSpawn);
+        this.child.off("close", this.onClose);
+        this.child.off("error", this.onError);
+        this.resolveOutcome(outcome);
+    }
+    clearTimers() {
+        if (this.deadlineTimer)
+            clearTimeout(this.deadlineTimer);
+        if (this.inactivityTimer)
+            clearTimeout(this.inactivityTimer);
+        if (this.escalationTimer)
+            clearTimeout(this.escalationTimer);
+        this.deadlineTimer = null;
+        this.inactivityTimer = null;
+        this.escalationTimer = null;
+    }
+}
+//# sourceMappingURL=managedChildProcess.js.map

package/dist/utils/managedChildProcess.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"managedChildProcess.js","sourceRoot":"","sources":["../../src/utils/managedChildProcess.ts"],"names":[],"mappings":"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"}

package/dist/utils/processTracker.js

@@ -3,7 +3,7 @@ export function trackChildProcess(proc) {
     tracked.add(proc);
     const remove = () => tracked.delete(proc);
     proc.once("exit", remove);
-    proc.once("error", remove);
+    proc.once("close", remove);
 }
 /**
  * SIGTERM all tracked child processes, then SIGKILL any that survive

package/dist/utils/runFfmpeg.d.ts

@@ -4,6 +4,7 @@
  * Extracts the repeated spawn-stderr-timeout-abort-close-error pattern
  * that appears across audioMixer and chunkEncoder into a single helper.
  */
+import { type ManagedProcessTerminationReason } from "./managedChildProcess.js";
 export interface RunFfmpegOptions {
     signal?: AbortSignal;
     timeout?: number;
@@ -14,6 +15,8 @@ export interface RunFfmpegResult {
     exitCode: number | null;
     stderr: string;
     durationMs: number;
+    terminationReason: ManagedProcessTerminationReason;
+    error?: Error;
 }
 /**
  * Build a user-facing error message for a failed ffmpeg invocation.

package/dist/utils/runFfmpeg.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runFfmpeg.d.ts","sourceRoot":"","sources":["../../src/utils/runFfmpeg.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AAMH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AA+BD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,MAAkC,GAC5C,MAAM,CAgBR;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAyDjG"}
+{"version":3,"file":"runFfmpeg.d.ts","sourceRoot":"","sources":["../../src/utils/runFfmpeg.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AAKH,OAAO,EAEL,KAAK,+BAA+B,EACrC,MAAM,0BAA0B,CAAC;AAElC,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,+BAA+B,CAAC;IACnD,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AA+BD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,MAAkC,GAC5C,MAAM,CAgBR;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAkBjG"}

package/dist/utils/runFfmpeg.js

@@ -8,6 +8,7 @@
 import { spawn } from "child_process";
 import { getFfmpegBinary } from "./ffmpegBinaries.js";
 import { trackChildProcess } from "./processTracker.js";
+import { ManagedChildProcess, } from "./managedChildProcess.js";
 const DEFAULT_TIMEOUT = 300_000;
 const DEFAULT_STDERR_TAIL_LINES = 15;
 function formatWindowsFfmpegExit(exitCode) {
@@ -57,57 +58,22 @@ export function formatFfmpegError(exitCode, stderr, tailLines = DEFAULT_STDERR_T
         : `FFmpeg exited with code ${exitCode}`;
 }
 export async function runFfmpeg(args, opts) {
-    const startMs = Date.now();
-    const signal = opts?.signal;
     const timeout = opts?.timeout ?? DEFAULT_TIMEOUT;
-    const onStderr = opts?.onStderr;
-    return new Promise((resolve) => {
-        const ffmpeg = spawn(getFfmpegBinary(), args);
-        trackChildProcess(ffmpeg);
-        let stderr = "";
-        const onAbort = () => {
-            ffmpeg.kill("SIGTERM");
-        };
-        if (signal) {
-            if (signal.aborted) {
-                ffmpeg.kill("SIGTERM");
-            }
-            else {
-                signal.addEventListener("abort", onAbort, { once: true });
-            }
-        }
-        const timer = setTimeout(() => {
-            ffmpeg.kill("SIGTERM");
-        }, timeout);
-        ffmpeg.stderr.on("data", (data) => {
-            const chunk = data.toString();
-            stderr += chunk;
-            if (onStderr) {
-                onStderr(chunk);
-            }
-        });
-        ffmpeg.on("close", (code) => {
-            clearTimeout(timer);
-            if (signal)
-                signal.removeEventListener("abort", onAbort);
-            resolve({
-                success: !signal?.aborted && code === 0,
-                exitCode: code,
-                stderr,
-                durationMs: Date.now() - startMs,
-            });
-        });
-        ffmpeg.on("error", (err) => {
-            clearTimeout(timer);
-            if (signal)
-                signal.removeEventListener("abort", onAbort);
-            resolve({
-                success: false,
-                exitCode: null,
-                stderr: err.message,
-                durationMs: Date.now() - startMs,
-            });
-        });
+    const ffmpeg = spawn(getFfmpegBinary(), args);
+    trackChildProcess(ffmpeg);
+    const managed = new ManagedChildProcess(ffmpeg, {
+        signal: opts?.signal,
+        deadlineAtMs: Date.now() + timeout,
+        onStderr: opts?.onStderr,
     });
+    const outcome = await managed.wait();
+    return {
+        success: outcome.reason === "exit" && outcome.exitCode === 0,
+        exitCode: outcome.exitCode,
+        stderr: outcome.stderr,
+        durationMs: outcome.durationMs,
+        terminationReason: outcome.reason,
+        error: outcome.error,
+    };
 }
 //# sourceMappingURL=runFfmpeg.js.map

package/dist/utils/runFfmpeg.js.map

@@ -1 +1 @@
-{"version":3,"file":"runFfmpeg.js","sourceRoot":"","sources":["../../src/utils/runFfmpeg.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runFfmpeg.js","sourceRoot":"","sources":["../../src/utils/runFfmpeg.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.7.59",
+  "version": "0.7.61",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
@@ -38,7 +38,8 @@
     "linkedom": "^0.18.12",
     "puppeteer": "^25.2.1",
     "puppeteer-core": "^25.2.1",
-    "@hyperframes/core": "^0.7.59"
+    "@hyperframes/core": "^0.7.61",
+    "@hyperframes/parsers": "^0.7.61"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",