@hyperframes/engine 0.7.60 → 0.7.61

package/dist/services/browserLeasePool.js

@@ -0,0 +1,210 @@
+function freezeFingerprint(fingerprint) {
+    return Object.freeze({
+        ...fingerprint,
+        args: Object.freeze([...fingerprint.args]),
+    });
+}
+function fingerprintKey(fingerprint) {
+    return JSON.stringify([
+        fingerprint.args,
+        fingerprint.executablePath ?? null,
+        fingerprint.browserTimeoutMs,
+        fingerprint.protocolTimeoutMs,
+        fingerprint.requestedCaptureMode,
+    ]);
+}
+/** Owns pooled browser generations and hands callers exactly-once leases. */
+export class BrowserLeasePool {
+    options;
+    available = new Map();
+    entries = new Set();
+    leasesByBrowser = new Map();
+    drainPromise = null;
+    constructor(options) {
+        this.options = options;
+    }
+    async acquire(fingerprintInput, pooled) {
+        if (this.drainPromise)
+            await this.drainPromise;
+        const fingerprint = freezeFingerprint(fingerprintInput);
+        const entry = this.reserveEntry(fingerprint, pooled);
+        return this.issueLease(entry);
+    }
+    async issueLease(entry) {
+        try {
+            const result = await entry.launchPromise;
+            if (entry.state !== "ready") {
+                throw new Error("Browser pool drained during acquisition");
+            }
+            return this.createLease(entry, result);
+        }
+        catch (error) {
+            entry.refCount = Math.max(0, entry.refCount - 1);
+            throw error;
+        }
+    }
+    reserveEntry(fingerprint, pooled) {
+        const key = fingerprintKey(fingerprint);
+        let entry = pooled ? this.available.get(key) : undefined;
+        if (entry?.state === "ready" && !entry.result?.browser.connected) {
+            this.requestClose(entry, true);
+            entry = undefined;
+        }
+        if (!entry || entry.state === "closing")
+            return this.createEntry(key, fingerprint, pooled);
+        entry.refCount += 1;
+        return entry;
+    }
+    /** Preserve legacy release-by-handle only when ownership is unambiguous. */
+    async releaseByBrowser(browser) {
+        const leases = this.leasesByBrowser.get(browser);
+        if (leases?.size === 1) {
+            const lease = leases.values().next().value;
+            await lease.release();
+            return;
+        }
+        if (leases) {
+            throw new Error(`Cannot release a pooled browser by handle while ${leases.size} leases are active; release the owning BrowserLease instead`);
+        }
+        await this.options.close(browser).catch(() => { });
+    }
+    /** Preserve the legacy ambiguous-handle no-op without closing another owner's browser. */
+    forceReleaseByBrowser(browser) {
+        const leases = this.leasesByBrowser.get(browser);
+        if (leases?.size === 1) {
+            const lease = leases.values().next().value;
+            lease.forceRelease();
+            return;
+        }
+        if (leases)
+            return;
+        this.options.forceClose(browser);
+    }
+    drain() {
+        if (this.drainPromise)
+            return this.drainPromise;
+        const entries = [...this.entries];
+        for (const entry of entries)
+            this.requestClose(entry, false);
+        this.drainPromise = Promise.all(entries.map((entry) => entry.closePromise)).then(() => {
+            this.drainPromise = null;
+        });
+        return this.drainPromise;
+    }
+    /** Test-only state reset. Call `drain()` first when entries own real browsers. */
+    reset() {
+        this.available.clear();
+        this.entries.clear();
+        this.leasesByBrowser.clear();
+        this.drainPromise = null;
+    }
+    createEntry(key, fingerprint, pooled) {
+        const entry = {
+            key,
+            fingerprint,
+            pooled,
+            state: "launching",
+            refCount: 1,
+            closeRequested: false,
+            forceCloseRequested: false,
+            launchPromise: undefined,
+        };
+        entry.launchPromise = this.options.launch(fingerprint).then((result) => {
+            entry.result = result;
+            if (entry.closeRequested) {
+                entry.state = "closing";
+            }
+            else {
+                entry.state = "ready";
+            }
+            return result;
+        }, (error) => {
+            if (this.available.get(key) === entry)
+                this.available.delete(key);
+            this.entries.delete(entry);
+            throw error;
+        });
+        this.entries.add(entry);
+        if (pooled)
+            this.available.set(key, entry);
+        return entry;
+    }
+    createLease(entry, result) {
+        let active = true;
+        let lease;
+        const deactivate = (force) => {
+            if (!active)
+                return false;
+            active = false;
+            this.removeLease(result.browser, lease);
+            entry.refCount = Math.max(0, entry.refCount - 1);
+            if (entry.refCount === 0)
+                this.requestClose(entry, force);
+            return true;
+        };
+        lease = {
+            ...result,
+            fingerprint: entry.fingerprint,
+            release: async () => {
+                if (!deactivate(false))
+                    return;
+                await entry.closePromise;
+            },
+            forceRelease: () => {
+                if (!deactivate(true) && entry.refCount === 0 && entry.closePromise) {
+                    this.requestClose(entry, true);
+                }
+            },
+        };
+        const leases = this.leasesByBrowser.get(result.browser) ?? new Set();
+        leases.add(lease);
+        this.leasesByBrowser.set(result.browser, leases);
+        return lease;
+    }
+    requestClose(entry, force) {
+        if (force) {
+            entry.forceCloseRequested = true;
+            entry.forceClose?.();
+        }
+        if (entry.closePromise)
+            return;
+        entry.closeRequested = true;
+        if (this.available.get(entry.key) === entry)
+            this.available.delete(entry.key);
+        entry.closePromise = entry.launchPromise
+            .then(async (result) => {
+            entry.state = "closing";
+            if (entry.forceCloseRequested) {
+                this.options.forceClose(result.browser);
+            }
+            else {
+                await Promise.race([
+                    this.options.close(result.browser).catch(() => { }),
+                    new Promise((resolve) => {
+                        entry.forceClose = () => {
+                            entry.forceClose = undefined;
+                            this.options.forceClose(result.browser);
+                            resolve();
+                        };
+                    }),
+                ]);
+            }
+        })
+            .catch(() => { })
+            .finally(() => {
+            entry.forceClose = undefined;
+            this.entries.delete(entry);
+            if (entry.result)
+                this.leasesByBrowser.delete(entry.result.browser);
+        });
+    }
+    removeLease(browser, lease) {
+        const leases = this.leasesByBrowser.get(browser);
+        if (!leases)
+            return;
+        leases.delete(lease);
+        if (leases.size === 0)
+            this.leasesByBrowser.delete(browser);
+    }
+}
+//# sourceMappingURL=browserLeasePool.js.map

package/dist/services/browserLeasePool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browserLeasePool.js","sourceRoot":"","sources":["../../src/services/browserLeasePool.ts"],"names":[],"mappings":"AA4CA,SAAS,iBAAiB,CACxB,WAAqC;IAErC,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,GAAG,WAAW;QACd,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;KAC3C,CAAC,CAAC;AACL,CAAC;AAED,SAAS,cAAc,CAAC,WAA+C;IACrE,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,WAAW,CAAC,IAAI;QAChB,WAAW,CAAC,cAAc,IAAI,IAAI;QAClC,WAAW,CAAC,gBAAgB;QAC5B,WAAW,CAAC,iBAAiB;QAC7B,WAAW,CAAC,oBAAoB;KACjC,CAAC,CAAC;AACL,CAAC;AAED,6EAA6E;AAC7E,MAAM,OAAO,gBAAgB;IAME;IALZ,SAAS,GAAG,IAAI,GAAG,EAA4B,CAAC;IAChD,OAAO,GAAG,IAAI,GAAG,EAAoB,CAAC;IACtC,eAAe,GAAG,IAAI,GAAG,EAA8B,CAAC;IACjE,YAAY,GAAyB,IAAI,CAAC;IAElD,YAA6B,OAAgC;QAAhC,YAAO,GAAP,OAAO,CAAyB;IAAG,CAAC;IAEjE,KAAK,CAAC,OAAO,CACX,gBAA0C,EAC1C,MAAe;QAEf,IAAI,IAAI,CAAC,YAAY;YAAE,MAAM,IAAI,CAAC,YAAY,CAAC;QAE/C,MAAM,WAAW,GAAG,iBAAiB,CAAC,gBAAgB,CAAC,CAAC;QACxD,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;QACrD,OAAO,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IAEO,KAAK,CAAC,UAAU,CAAC,KAAuB;QAC9C,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,aAAa,CAAC;YACzC,IAAI,KAAK,CAAC,KAAK,KAAK,OAAO,EAAE,CAAC;gBAC5B,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;YAC7D,CAAC;YACD,OAAO,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QACzC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC;YACjD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAEO,YAAY,CAClB,WAA+C,EAC/C,MAAe;QAEf,MAAM,GAAG,GAAG,cAAc,CAAC,WAAW,CAAC,CAAC;QACxC,IAAI,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACzD,IAAI,KAAK,EAAE,KAAK,KAAK,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC;YACjE,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YAC/B,KAAK,GAAG,SAAS,CAAC;QACpB,CAAC;QACD,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;QAC3F,KAAK,CAAC,QAAQ,IAAI,CAAC,CAAC;QACpB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,4EAA4E;IAC5E,KAAK,CAAC,gBAAgB,CAAC,OAAgB;QACrC,MAAM,MAAM,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACjD,IAAI,MAAM,EAAE,IAAI,KAAK,CAAC,EAAE,CAAC;YACvB,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,KAAqB,CAAC;YAC3D,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC;YACtB,OAAO;QACT,CAAC;QACD,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CACb,mDAAmD,MAAM,CAAC,IAAI,6DAA6D,CAC5H,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACpD,CAAC;IAED,0FAA0F;IAC1F,qBAAqB,CAAC,OAAgB;QACpC,MAAM,MAAM,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACjD,IAAI,MAAM,EAAE,IAAI,KAAK,CAAC,EAAE,CAAC;YACvB,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,KAAqB,CAAC;YAC3D,KAAK,CAAC,YAAY,EAAE,CAAC;YACrB,OAAO;QACT,CAAC;QACD,IAAI,MAAM;YAAE,OAAO;QACnB,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IACnC,CAAC;IAED,KAAK;QACH,IAAI,IAAI,CAAC,YAAY;YAAE,OAAO,IAAI,CAAC,YAAY,CAAC;QAChD,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;QAClC,KAAK,MAAM,KAAK,IAAI,OAAO;YAAE,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QAC7D,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE;YACpF,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QAC3B,CAAC,CAAC,CAAC;QACH,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED,kFAAkF;IAClF,KAAK;QACH,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QACvB,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrB,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;QAC7B,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;IAC3B,CAAC;IAEO,WAAW,CACjB,GAAW,EACX,WAA+C,EAC/C,MAAe;QAEf,MAAM,KAAK,GAAqB;YAC9B,GAAG;YACH,WAAW;YACX,MAAM;YACN,KAAK,EAAE,WAAW;YAClB,QAAQ,EAAE,CAAC;YACX,cAAc,EAAE,KAAK;YACrB,mBAAmB,EAAE,KAAK;YAC1B,aAAa,EAAE,SAAoD;SACpE,CAAC;QACF,KAAK,CAAC,aAAa,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,IAAI,CACzD,CAAC,MAAM,EAAE,EAAE;YACT,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC;YACtB,IAAI,KAAK,CAAC,cAAc,EAAE,CAAC;gBACzB,KAAK,CAAC,KAAK,GAAG,SAAS,CAAC;YAC1B,CAAC;iBAAM,CAAC;gBACN,KAAK,CAAC,KAAK,GAAG,OAAO,CAAC;YACxB,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,CAAC,EACD,CAAC,KAAc,EAAE,EAAE;YACjB,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,KAAK;gBAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAClE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC3B,MAAM,KAAK,CAAC;QACd,CAAC,CACF,CAAC;QACF,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACxB,IAAI,MAAM;YAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC3C,OAAO,KAAK,CAAC;IACf,CAAC;IAEO,WAAW,CAAC,KAAuB,EAAE,MAA2B;QACtE,IAAI,MAAM,GAAG,IAAI,CAAC;QAClB,IAAI,KAAmB,CAAC;QACxB,MAAM,UAAU,GAAG,CAAC,KAAc,EAAW,EAAE;YAC7C,IAAI,CAAC,MAAM;gBAAE,OAAO,KAAK,CAAC;YAC1B,MAAM,GAAG,KAAK,CAAC;YACf,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;YACxC,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC;YACjD,IAAI,KAAK,CAAC,QAAQ,KAAK,CAAC;gBAAE,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;YAC1D,OAAO,IAAI,CAAC;QACd,CAAC,CAAC;QACF,KAAK,GAAG;YACN,GAAG,MAAM;YACT,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,OAAO,EAAE,KAAK,IAAI,EAAE;gBAClB,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC;oBAAE,OAAO;gBAC/B,MAAM,KAAK,CAAC,YAAY,CAAC;YAC3B,CAAC;YACD,YAAY,EAAE,GAAG,EAAE;gBACjB,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,QAAQ,KAAK,CAAC,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;oBACpE,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;gBACjC,CAAC;YACH,CAAC;SACF,CAAC;QACF,MAAM,MAAM,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,GAAG,EAAgB,CAAC;QACnF,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAClB,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACjD,OAAO,KAAK,CAAC;IACf,CAAC;IAEO,YAAY,CAAC,KAAuB,EAAE,KAAc;QAC1D,IAAI,KAAK,EAAE,CAAC;YACV,KAAK,CAAC,mBAAmB,GAAG,IAAI,CAAC;YACjC,KAAK,CAAC,UAAU,EAAE,EAAE,CAAC;QACvB,CAAC;QACD,IAAI,KAAK,CAAC,YAAY;YAAE,OAAO;QAC/B,KAAK,CAAC,cAAc,GAAG,IAAI,CAAC;QAC5B,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,KAAK;YAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC9E,KAAK,CAAC,YAAY,GAAG,KAAK,CAAC,aAAa;aACrC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE;YACrB,KAAK,CAAC,KAAK,GAAG,SAAS,CAAC;YACxB,IAAI,KAAK,CAAC,mBAAmB,EAAE,CAAC;gBAC9B,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAC1C,CAAC;iBAAM,CAAC;gBACN,MAAM,OAAO,CAAC,IAAI,CAAC;oBACjB,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC;oBAClD,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;wBAC5B,KAAK,CAAC,UAAU,GAAG,GAAG,EAAE;4BACtB,KAAK,CAAC,UAAU,GAAG,SAAS,CAAC;4BAC7B,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;4BACxC,OAAO,EAAE,CAAC;wBACZ,CAAC,CAAC;oBACJ,CAAC,CAAC;iBACH,CAAC,CAAC;YACL,CAAC;QACH,CAAC,CAAC;aACD,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC;aACf,OAAO,CAAC,GAAG,EAAE;YACZ,KAAK,CAAC,UAAU,GAAG,SAAS,CAAC;YAC7B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC3B,IAAI,KAAK,CAAC,MAAM;gBAAE,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACtE,CAAC,CAAC,CAAC;IACP,CAAC;IAEO,WAAW,CAAC,OAAgB,EAAE,KAAmB;QACvD,MAAM,MAAM,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACjD,IAAI,CAAC,MAAM;YAAE,OAAO;QACpB,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACrB,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC;YAAE,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC9D,CAAC;CACF"}

package/dist/services/browserManager.d.ts

@@ -6,15 +6,14 @@
  */
 import type { Browser, PuppeteerNode } from "puppeteer-core";
 import { type EngineConfig } from "../config.js";
-export type CaptureMode = "beginframe" | "screenshot" | "drawelement";
-export interface AcquiredBrowser {
-    browser: Browser;
-    captureMode: CaptureMode;
-}
+import { type BrowserLease, type CaptureMode } from "./browserLeasePool.js";
+export { BrowserLeasePool } from "./browserLeasePool.js";
+export type { BrowserLaunchFingerprint, BrowserLease, BrowserPoolState, CaptureMode, } from "./browserLeasePool.js";
+export type AcquiredBrowser = BrowserLease;
 /**
  * Resolve chrome-headless-shell binary for deterministic BeginFrame rendering.
  * Checks config.chromePath, then PRODUCER_HEADLESS_SHELL_PATH env var,
- * then scans Puppeteer's managed cache at ~/.cache/puppeteer/chrome-headless-shell/.
+ * then the CLI browser override, HyperFrames' managed cache, and Puppeteer's cache.
  */
 export declare function resolveHeadlessShellPath(config?: Partial<Pick<EngineConfig, "chromePath">>): string | undefined;
 export declare const ENABLE_BROWSER_POOL: boolean;
@@ -41,7 +40,7 @@ export declare function resolveBrowserGpuMode(mode: EngineConfig["browserGpuMode
     platform?: NodeJS.Platform;
 }): Promise<"software" | "hardware">;
 export declare function acquireBrowser(chromeArgs: string[], config?: Partial<Pick<EngineConfig, "browserTimeout" | "protocolTimeout" | "enableBrowserPool" | "chromePath" | "forceScreenshot">>): Promise<AcquiredBrowser>;
-export declare function releaseBrowser(browser: Browser, config?: Partial<Pick<EngineConfig, "enableBrowserPool">>): Promise<void>;
+export declare function releaseBrowser(browser: Browser, _config?: Partial<Pick<EngineConfig, "enableBrowserPool">>): Promise<void>;
 export declare function forceReleaseBrowser(browser: Browser): void;
 /**
  * Forcefully close the pooled browser if one exists, regardless of refCount.

package/dist/services/browserManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browserManager.d.ts","sourceRoot":"","sources":["../../src/services/browserManager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAK7D,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAyFjE,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,YAAY,GAAG,aAAa,CAAC;AAEtE,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC,GACjD,MAAM,GAAG,SAAS,CAiCpB;AAQD,eAAO,MAAM,mBAAmB,SAAmC,CAAC;AA2EpE,gDAAgD;AAChD,wBAAgB,qCAAqC,IAAI,IAAI,CAE5D;AAkED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,YAAY,CAAC,gBAAgB,CAAC,EACpC,OAAO,GAAE;IACP,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CACvB,GACL,OAAO,CAAC,UAAU,GAAG,UAAU,CAAC,CAMlC;AA4BD,wBAAsB,cAAc,CAClC,UAAU,EAAE,MAAM,EAAE,EACpB,MAAM,CAAC,EAAE,OAAO,CACd,IAAI,CACF,YAAY,EACZ,gBAAgB,GAAG,iBAAiB,GAAG,mBAAmB,GAAG,YAAY,GAAG,iBAAiB,CAC9F,CACF,GACA,OAAO,CAAC,eAAe,CAAC,CAsD1B;AAsED,wBAAsB,cAAc,CAClC,OAAO,EAAE,OAAO,EAChB,MAAM,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,mBAAmB,CAAC,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CAgBf;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA8B1D;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CActD;AAED,uCAAuC;AACvC,wBAAgB,yBAAyB,IAAI,IAAI,CAKhD;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI,CAE3E;AAyCD,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC5B;AAKD,wBAAgB,eAAe,CAC7B,OAAO,EAAE,sBAAsB,EAC/B,MAAM,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,gBAAgB,GAAG,YAAY,GAAG,YAAY,CAAC,CAAC,GACnF,MAAM,EAAE,CA0FV"}
+{"version":3,"file":"browserManager.d.ts","sourceRoot":"","sources":["../../src/services/browserManager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAK7D,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjE,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,WAAW,EACjB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,YAAY,EACV,wBAAwB,EACxB,YAAY,EACZ,gBAAgB,EAChB,WAAW,GACZ,MAAM,uBAAuB,CAAC;AAqF/B,MAAM,MAAM,eAAe,GAAG,YAAY,CAAC;AA4C3C;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC,GACjD,MAAM,GAAG,SAAS,CA8BpB;AAGD,eAAO,MAAM,mBAAmB,SAAmC,CAAC;AA2EpE,gDAAgD;AAChD,wBAAgB,qCAAqC,IAAI,IAAI,CAE5D;AAkED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,YAAY,CAAC,gBAAgB,CAAC,EACpC,OAAO,GAAE;IACP,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CACvB,GACL,OAAO,CAAC,UAAU,GAAG,UAAU,CAAC,CAMlC;AAsCD,wBAAsB,cAAc,CAClC,UAAU,EAAE,MAAM,EAAE,EACpB,MAAM,CAAC,EAAE,OAAO,CACd,IAAI,CACF,YAAY,EACZ,gBAAgB,GAAG,iBAAiB,GAAG,mBAAmB,GAAG,YAAY,GAAG,iBAAiB,CAC9F,CACF,GACA,OAAO,CAAC,eAAe,CAAC,CAG1B;AAgFD,wBAAsB,cAAc,CAClC,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,mBAAmB,CAAC,CAAC,GACzD,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAE1D;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAEtD;AAED,uCAAuC;AACvC,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI,CAE3E;AAyCD,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC5B;AAKD,wBAAgB,eAAe,CAC7B,OAAO,EAAE,sBAAsB,EAC/B,MAAM,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,gBAAgB,GAAG,YAAY,GAAG,YAAY,CAAC,CAAC,GACnF,MAAM,EAAE,CA0FV"}

package/dist/services/browserManager.js

@@ -10,6 +10,8 @@ import { join } from "path";
 import { homedir } from "os";
 import { DEFAULT_CONFIG } from "../config.js";
 import { getSystemTotalMb, LOW_MEMORY_TOTAL_MB_THRESHOLD } from "./systemMemory.js";
+import { BrowserLeasePool, } from "./browserLeasePool.js";
+export { BrowserLeasePool } from "./browserLeasePool.js";
 let _puppeteer;
 function isSoftwareWebGlRenderer(rendererInfo) {
     const renderer = rendererInfo.trim().toLowerCase();
@@ -76,28 +78,33 @@ async function probeHardwareWebGlInfo(ppt, options) {
         await probeBrowser?.close().catch(() => { });
     }
 }
-/**
- * Resolve chrome-headless-shell binary for deterministic BeginFrame rendering.
- * Checks config.chromePath, then PRODUCER_HEADLESS_SHELL_PATH env var,
- * then scans Puppeteer's managed cache at ~/.cache/puppeteer/chrome-headless-shell/.
- */
-export function resolveHeadlessShellPath(config) {
-    if (config?.chromePath) {
-        return config.chromePath;
-    }
-    if (process.env.PRODUCER_HEADLESS_SHELL_PATH) {
-        const envPath = process.env.PRODUCER_HEADLESS_SHELL_PATH;
-        if (!existsSync(envPath)) {
-            throw new Error(`[BrowserManager] Chrome binary not found at PRODUCER_HEADLESS_SHELL_PATH="${envPath}". ` +
-                "Run `hyperframes browser ensure` to re-download.");
+function compareBrowserVersionsDescending(left, right) {
+    const parse = (value) => {
+        const version = value.slice(value.indexOf("-") + 1);
+        const segments = [];
+        for (const segment of version.split(".")) {
+            const parsed = Number.parseInt(segment, 10);
+            if (!Number.isFinite(parsed))
+                break;
+            segments.push(parsed);
         }
-        return envPath;
-    }
-    const baseDir = join(homedir(), ".cache", "puppeteer", "chrome-headless-shell");
+        return segments;
+    };
+    const leftSegments = parse(left);
+    const rightSegments = parse(right);
+    const length = Math.max(leftSegments.length, rightSegments.length);
+    for (let index = 0; index < length; index += 1) {
+        const difference = (rightSegments[index] ?? 0) - (leftSegments[index] ?? 0);
+        if (difference !== 0)
+            return difference;
+    }
+    return 0;
+}
+function findCachedHeadlessShell(baseDir) {
     if (!existsSync(baseDir))
         return undefined;
     try {
-        const versions = readdirSync(baseDir).sort().reverse(); // newest first
+        const versions = readdirSync(baseDir).sort(compareBrowserVersionsDescending);
         for (const version of versions) {
             const candidates = [
                 join(baseDir, version, "chrome-headless-shell-linux64", "chrome-headless-shell"),
@@ -112,14 +119,38 @@ export function resolveHeadlessShellPath(config) {
         }
     }
     catch {
-        // ignore
+        // Ignore unreadable cache directories and continue browser discovery.
     }
     return undefined;
 }
-let pooledBrowser = null;
-let pooledBrowserRefCount = 0;
-let pooledCaptureMode = "screenshot";
-let _pooledBrowserLaunchPromise = null;
+/**
+ * Resolve chrome-headless-shell binary for deterministic BeginFrame rendering.
+ * Checks config.chromePath, then PRODUCER_HEADLESS_SHELL_PATH env var,
+ * then the CLI browser override, HyperFrames' managed cache, and Puppeteer's cache.
+ */
+export function resolveHeadlessShellPath(config) {
+    if (config?.chromePath) {
+        return config.chromePath;
+    }
+    if (process.env.PRODUCER_HEADLESS_SHELL_PATH) {
+        const envPath = process.env.PRODUCER_HEADLESS_SHELL_PATH;
+        if (!existsSync(envPath)) {
+            throw new Error(`[BrowserManager] Chrome binary not found at PRODUCER_HEADLESS_SHELL_PATH="${envPath}". ` +
+                "Run `hyperframes browser ensure` to re-download.");
+        }
+        return envPath;
+    }
+    if (process.env.HYPERFRAMES_BROWSER_PATH) {
+        const envPath = process.env.HYPERFRAMES_BROWSER_PATH;
+        if (!existsSync(envPath)) {
+            throw new Error(`[BrowserManager] Chrome binary not found at HYPERFRAMES_BROWSER_PATH="${envPath}". ` +
+                "Run `hyperframes browser ensure` to re-download.");
+        }
+        return envPath;
+    }
+    const home = homedir();
+    return (findCachedHeadlessShell(join(home, ".cache", "hyperframes", "chrome", "chrome-headless-shell")) ?? findCachedHeadlessShell(join(home, ".cache", "puppeteer", "chrome-headless-shell")));
+}
 // Preserve the producer-era export so re-export shims keep the same public API.
 export const ENABLE_BROWSER_POOL = DEFAULT_CONFIG.enableBrowserPool;
 // Flags only meaningful when Chrome's compositor is driven by
@@ -284,153 +315,71 @@ export function resolveBrowserGpuMode(mode, options = {}) {
 function logResolvedBrowserGpuMode(resolved, reason) {
     console.error(`[hyperframes] browserGpuMode auto → ${resolved} (${reason})`);
 }
-/**
- * Resolve the capture mode the caller expects, WITHOUT launching a browser.
- * Used to validate pool compatibility before returning a cached instance.
- */
-function resolveRequestedCaptureMode(config) {
-    const headlessShell = resolveHeadlessShellPath(config);
-    // BeginFrame requires chrome-headless-shell AND Linux — crashes on
-    // macOS/Windows (crbug.com/40656275).
-    const isLinux = process.platform === "linux";
-    const forceScreenshot = config?.forceScreenshot ?? DEFAULT_CONFIG.forceScreenshot;
-    if (headlessShell && isLinux && !forceScreenshot)
-        return "beginframe";
-    return "screenshot";
+function createBrowserLaunchFingerprint(chromeArgs, config) {
+    const launchConfig = {
+        browserTimeout: DEFAULT_CONFIG.browserTimeout,
+        protocolTimeout: DEFAULT_CONFIG.protocolTimeout,
+        forceScreenshot: DEFAULT_CONFIG.forceScreenshot,
+        ...config,
+    };
+    const headlessShell = resolveHeadlessShellPath(launchConfig);
+    const requestedCaptureMode = headlessShell && process.platform === "linux" && !launchConfig.forceScreenshot
+        ? "beginframe"
+        : "screenshot";
+    return {
+        args: chromeArgs,
+        executablePath: headlessShell,
+        browserTimeoutMs: launchConfig.browserTimeout,
+        protocolTimeoutMs: launchConfig.protocolTimeout,
+        requestedCaptureMode,
+    };
 }
 export async function acquireBrowser(chromeArgs, config) {
     const enablePool = config?.enableBrowserPool ?? DEFAULT_CONFIG.enableBrowserPool;
-    if (enablePool && pooledBrowser) {
-        if (!pooledBrowser.connected) {
-            pooledBrowser = null;
-            pooledBrowserRefCount = 0;
-            _pooledBrowserLaunchPromise = null;
-        }
-        else {
-            // Validate mode compatibility: a caller that needs screenshot mode
-            // (forceScreenshot, alpha output, BeginFrame timeout retry) must not
-            // receive a beginframe browser — the BeginFrame-only flags make the
-            // compositor wait for frames the screenshot path never sends.
-            const requestedMode = resolveRequestedCaptureMode(config);
-            if (pooledCaptureMode === requestedMode) {
-                pooledBrowserRefCount += 1;
-                return { browser: pooledBrowser, captureMode: pooledCaptureMode };
-            }
-            // Mode mismatch — skip pool, launch a dedicated browser for this caller.
-            // Don't evict the pooled browser: other sessions may still hold refs.
-        }
-    }
-    // Dedup concurrent launches: when the pool is enabled and multiple callers
-    // (e.g. parallel workers via Promise.all) race into acquireBrowser before
-    // the first launch completes, they would all see pooledBrowser === null and
-    // each spawn a separate Chrome. Cache the in-flight launch Promise so the
-    // second+ callers await the same one instead of launching again.
-    if (enablePool && _pooledBrowserLaunchPromise) {
-        const result = await _pooledBrowserLaunchPromise;
-        const requestedMode = resolveRequestedCaptureMode(config);
-        if (result.captureMode === requestedMode) {
-            pooledBrowserRefCount += 1;
-            return result;
-        }
-        // Mode mismatch with pending launch — launch a dedicated browser.
-    }
-    const launchPromise = launchBrowser(chromeArgs, config);
-    if (enablePool && !pooledBrowser && !_pooledBrowserLaunchPromise) {
-        _pooledBrowserLaunchPromise = launchPromise;
-        try {
-            const result = await launchPromise;
-            pooledBrowser = result.browser;
-            pooledBrowserRefCount = 1;
-            pooledCaptureMode = result.captureMode;
-            return result;
-        }
-        finally {
-            _pooledBrowserLaunchPromise = null;
-        }
-    }
-    return launchPromise;
+    return browserLeasePool.acquire(createBrowserLaunchFingerprint(chromeArgs, config), enablePool);
 }
 // fallow-ignore-next-line complexity
-async function launchBrowser(chromeArgs, config) {
-    // Config chromePath overrides env var / auto-detection.
-    const headlessShell = resolveHeadlessShellPath(config);
-    // BeginFrame requires chrome-headless-shell AND Linux (crashes on
-    // macOS/Windows — crbug.com/40656275).
-    const isLinux = process.platform === "linux";
-    const forceScreenshot = config?.forceScreenshot ?? DEFAULT_CONFIG.forceScreenshot;
-    let captureMode;
-    let executablePath;
-    if (headlessShell && isLinux && !forceScreenshot) {
-        captureMode = "beginframe";
-        executablePath = headlessShell;
-    }
-    else {
-        // Screenshot mode with renderSeek: works on all platforms.
-        captureMode = "screenshot";
-        executablePath = headlessShell ?? undefined;
-    }
+async function launchBrowser(fingerprint) {
     const ppt = await getPuppeteer();
-    const browserTimeout = config?.browserTimeout ?? DEFAULT_CONFIG.browserTimeout;
-    const protocolTimeout = config?.protocolTimeout ?? DEFAULT_CONFIG.protocolTimeout;
-    let browser = await ppt.launch({
-        headless: true,
-        args: chromeArgs,
-        defaultViewport: null,
-        executablePath,
-        timeout: browserTimeout,
-        protocolTimeout,
-    });
-    const browserVersion = await browser.version().catch(() => "unknown");
-    const gpuFlags = chromeArgs.filter((a) => a.startsWith("--use-gl=") || a.startsWith("--use-angle="));
-    console.log(`[BrowserManager] Browser launched (${browserVersion}, ${captureMode}, gl=${gpuFlags.join(" ") || "default"}, headlessShell=${!!headlessShell}, platform=${process.platform})`);
-    if (captureMode === "beginframe") {
-        const supported = await probeBeginFrameSupport(browser).catch(() => true);
-        if (!supported) {
-            await browser.close().catch(() => { });
-            console.warn("[BrowserManager] HeadlessExperimental.beginFrame unavailable in this Chromium build; falling back to screenshot mode.");
-            captureMode = "screenshot";
-            browser = await ppt.launch({
-                headless: true,
-                args: stripBeginFrameFlags(chromeArgs),
-                defaultViewport: null,
-                executablePath,
-                timeout: browserTimeout,
-                protocolTimeout,
-            });
+    let captureMode = fingerprint.requestedCaptureMode;
+    let browser;
+    try {
+        browser = await ppt.launch({
+            headless: true,
+            args: [...fingerprint.args],
+            defaultViewport: null,
+            executablePath: fingerprint.executablePath,
+            timeout: fingerprint.browserTimeoutMs,
+            protocolTimeout: fingerprint.protocolTimeoutMs,
+        });
+        const browserVersion = await browser.version().catch(() => "unknown");
+        const gpuFlags = fingerprint.args.filter((a) => a.startsWith("--use-gl=") || a.startsWith("--use-angle="));
+        console.log(`[BrowserManager] Browser launched (${browserVersion}, ${captureMode}, gl=${gpuFlags.join(" ") || "default"}, headlessShell=${!!fingerprint.executablePath}, platform=${process.platform})`);
+        if (captureMode === "beginframe") {
+            const supported = await probeBeginFrameSupport(browser).catch(() => true);
+            if (!supported) {
+                await browser.close().catch(() => { });
+                browser = undefined;
+                console.warn("[BrowserManager] HeadlessExperimental.beginFrame unavailable in this Chromium build; falling back to screenshot mode.");
+                captureMode = "screenshot";
+                browser = await ppt.launch({
+                    headless: true,
+                    args: stripBeginFrameFlags([...fingerprint.args]),
+                    defaultViewport: null,
+                    executablePath: fingerprint.executablePath,
+                    timeout: fingerprint.browserTimeoutMs,
+                    protocolTimeout: fingerprint.protocolTimeoutMs,
+                });
+            }
         }
+        return { browser, captureMode };
     }
-    return { browser, captureMode };
-}
-export async function releaseBrowser(browser, config) {
-    const enablePool = config?.enableBrowserPool ?? DEFAULT_CONFIG.enableBrowserPool;
-    if (!enablePool) {
-        await browser.close().catch(() => { });
-        return;
-    }
-    if (pooledBrowser && pooledBrowser === browser) {
-        pooledBrowserRefCount = Math.max(0, pooledBrowserRefCount - 1);
-        if (pooledBrowserRefCount === 0) {
-            await browser.close().catch(() => { });
-            pooledBrowser = null;
-            _pooledBrowserLaunchPromise = null;
-        }
-        return;
+    catch (error) {
+        await browser?.close().catch(() => { });
+        throw error;
     }
-    await browser.close().catch(() => { });
 }
-export function forceReleaseBrowser(browser) {
-    if (pooledBrowser && pooledBrowser === browser) {
-        // If other sessions still hold refs, just drop ours — don't kill the
-        // shared Chrome out from under them. The browser will be cleaned up when
-        // the last session releases or drainBrowserPool is called.
-        if (pooledBrowserRefCount > 1) {
-            pooledBrowserRefCount -= 1;
-            return;
-        }
-        pooledBrowserRefCount = 0;
-        pooledBrowser = null;
-        _pooledBrowserLaunchPromise = null;
-    }
+function forceCloseBrowserProcess(browser) {
     const proc = browser.process?.();
     if (proc && !proc.killed) {
         try {
@@ -447,32 +396,28 @@ export function forceReleaseBrowser(browser) {
         // Best-effort cleanup.
     }
 }
+const browserLeasePool = new BrowserLeasePool({
+    launch: launchBrowser,
+    close: async (browser) => browser.close(),
+    forceClose: forceCloseBrowserProcess,
+});
+export async function releaseBrowser(browser, _config) {
+    await browserLeasePool.releaseByBrowser(browser);
+}
+export function forceReleaseBrowser(browser) {
+    browserLeasePool.forceReleaseByBrowser(browser);
+}
 /**
  * Forcefully close the pooled browser if one exists, regardless of refCount.
  * Used for explicit cleanup at process exit or between independent render jobs
  * that should not share browser state.
  */
 export async function drainBrowserPool() {
-    // Await any in-flight launch first — otherwise the launch resolves after we
-    // drain and produces a browser that nobody references (orphan).
-    const pending = _pooledBrowserLaunchPromise;
-    _pooledBrowserLaunchPromise = null;
-    if (pending) {
-        await pending.then((r) => r.browser.close()).catch(() => { });
-    }
-    if (pooledBrowser) {
-        const browser = pooledBrowser;
-        pooledBrowser = null;
-        pooledBrowserRefCount = 0;
-        await browser.close().catch(() => { });
-    }
+    await browserLeasePool.drain();
 }
 /** Test-only: reset all pool state. */
 export function _resetBrowserPoolForTests() {
-    pooledBrowser = null;
-    pooledBrowserRefCount = 0;
-    pooledCaptureMode = "screenshot";
-    _pooledBrowserLaunchPromise = null;
+    browserLeasePool.reset();
 }
 /** Test-only: inject a mock PuppeteerNode so tests bypass the dynamic import. */
 export function _setPuppeteerForTests(mock) {