@browserbasehq/orca 3.0.9-alpha-4 → 3.1.0-patch.0

package/dist/esm/lib/v3/shutdown/cleanupLocal.js

@@ -0,0 +1,30 @@
+import fs from "node:fs";
+/**
+ * Shared cleanup logic for locally launched Chrome.
+ *
+ * Used by both `V3.close()` (normal shutdown) and the supervisor process
+ * (crash cleanup). The caller provides a `killChrome` callback since the
+ * kill mechanism differs: chrome-launcher's `chrome.kill()` in-process
+ * vs raw `process.kill(pid)` from the supervisor.
+ */
+export async function cleanupLocalBrowser(opts) {
+    if (opts.killChrome) {
+        try {
+            await opts.killChrome();
+        }
+        catch {
+            // best-effort
+        }
+    }
+    if (opts.createdTempProfile &&
+        !opts.preserveUserDataDir &&
+        opts.userDataDir) {
+        try {
+            fs.rmSync(opts.userDataDir, { recursive: true, force: true });
+        }
+        catch {
+            // ignore cleanup errors
+        }
+    }
+}
+//# sourceMappingURL=cleanupLocal.js.map

package/dist/esm/lib/v3/shutdown/cleanupLocal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanupLocal.js","sourceRoot":"","sources":["../../../../../lib/v3/shutdown/cleanupLocal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAEzB;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,IAKzC;IACC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,cAAc;QAChB,CAAC;IACH,CAAC;IACD,IACE,IAAI,CAAC,kBAAkB;QACvB,CAAC,IAAI,CAAC,mBAAmB;QACzB,IAAI,CAAC,WAAW,EAChB,CAAC;QACD,IAAI,CAAC;YACH,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAChE,CAAC;QAAC,MAAM,CAAC;YACP,wBAAwB;QAC1B,CAAC;IACH,CAAC;AACH,CAAC","sourcesContent":["import fs from \"node:fs\";\n\n/**\n * Shared cleanup logic for locally launched Chrome.\n *\n * Used by both `V3.close()` (normal shutdown) and the supervisor process\n * (crash cleanup). The caller provides a `killChrome` callback since the\n * kill mechanism differs: chrome-launcher's `chrome.kill()` in-process\n * vs raw `process.kill(pid)` from the supervisor.\n */\nexport async function cleanupLocalBrowser(opts: {\n  killChrome?: () => Promise<void> | void;\n  userDataDir?: string;\n  createdTempProfile?: boolean;\n  preserveUserDataDir?: boolean;\n}): Promise<void> {\n  if (opts.killChrome) {\n    try {\n      await opts.killChrome();\n    } catch {\n      // best-effort\n    }\n  }\n  if (\n    opts.createdTempProfile &&\n    !opts.preserveUserDataDir &&\n    opts.userDataDir\n  ) {\n    try {\n      fs.rmSync(opts.userDataDir, { recursive: true, force: true });\n    } catch {\n      // ignore cleanup errors\n    }\n  }\n}\n"]}

package/dist/esm/lib/v3/shutdown/supervisor.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shutdown supervisor process.
+ *
+ * This process watches a lifeline (stdin/IPC). When the parent dies, the
+ * lifeline closes and the supervisor performs best-effort cleanup:
+ * - LOCAL: kill Chrome + remove temp profile (when keepAlive is false)
+ * - STAGEHAND_API: request session release (when keepAlive is false)
+ */
+export {};

package/dist/esm/lib/v3/shutdown/supervisor.js

@@ -0,0 +1,156 @@
+/**
+ * Shutdown supervisor process.
+ *
+ * This process watches a lifeline (stdin/IPC). When the parent dies, the
+ * lifeline closes and the supervisor performs best-effort cleanup:
+ * - LOCAL: kill Chrome + remove temp profile (when keepAlive is false)
+ * - STAGEHAND_API: request session release (when keepAlive is false)
+ */
+import Browserbase from "@browserbasehq/sdk";
+import { cleanupLocalBrowser } from "./cleanupLocal.js";
+const SIGKILL_POLL_MS = 500;
+const SIGKILL_TIMEOUT_MS = 10_000;
+const PID_POLL_INTERVAL_MS = 500;
+let armed = false;
+let config = null;
+let cleanupPromise = null;
+const exit = (code = 0) => {
+    try {
+        process.exit(code);
+    }
+    catch {
+        // ignore
+    }
+};
+const safeKill = async (pid) => {
+    const isAlive = () => {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    if (!isAlive())
+        return;
+    try {
+        process.kill(pid, "SIGTERM");
+    }
+    catch {
+        return;
+    }
+    const deadline = Date.now() + SIGKILL_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, SIGKILL_POLL_MS));
+        if (!isAlive())
+            return;
+    }
+    try {
+        process.kill(pid, "SIGKILL");
+    }
+    catch {
+        // best-effort
+    }
+};
+let pidGone = false;
+let pidPollTimer = null;
+const startPidPolling = (pid) => {
+    if (pidPollTimer)
+        return;
+    pidPollTimer = setInterval(() => {
+        try {
+            process.kill(pid, 0);
+        }
+        catch {
+            pidGone = true;
+            if (pidPollTimer) {
+                clearInterval(pidPollTimer);
+                pidPollTimer = null;
+            }
+        }
+    }, PID_POLL_INTERVAL_MS);
+};
+const cleanupLocal = async (cfg) => {
+    if (cfg.keepAlive)
+        return;
+    await cleanupLocalBrowser({
+        killChrome: cfg.pid && !pidGone ? () => safeKill(cfg.pid) : undefined,
+        userDataDir: cfg.userDataDir,
+        createdTempProfile: cfg.createdTempProfile,
+        preserveUserDataDir: cfg.preserveUserDataDir,
+    });
+};
+const cleanupBrowserbase = async (cfg) => {
+    if (cfg.keepAlive)
+        return;
+    if (!cfg.apiKey || !cfg.projectId || !cfg.sessionId)
+        return;
+    try {
+        const bb = new Browserbase({ apiKey: cfg.apiKey });
+        await bb.sessions.update(cfg.sessionId, {
+            status: "REQUEST_RELEASE",
+            projectId: cfg.projectId,
+        });
+    }
+    catch {
+        // best-effort cleanup
+    }
+};
+const runCleanup = () => {
+    if (!cleanupPromise) {
+        cleanupPromise = (async () => {
+            const cfg = config;
+            if (!cfg || !armed)
+                return;
+            armed = false;
+            if (cfg.kind === "LOCAL") {
+                await cleanupLocal(cfg);
+                return;
+            }
+            if (cfg.kind === "STAGEHAND_API") {
+                await cleanupBrowserbase(cfg);
+            }
+        })();
+    }
+    return cleanupPromise;
+};
+const onLifelineClosed = () => {
+    void runCleanup().finally(() => exit(0));
+};
+const onMessage = (raw) => {
+    if (!raw || typeof raw !== "object")
+        return;
+    const msg = raw;
+    if (msg.type === "config") {
+        config = msg.config ?? null;
+        armed = Boolean(config) && config?.keepAlive === false;
+        if (armed && config?.kind === "LOCAL" && config?.pid) {
+            startPidPolling(config.pid);
+        }
+        try {
+            process.send?.({ type: "ready" });
+        }
+        catch {
+            // ignore IPC failures
+        }
+        return;
+    }
+    if (msg.type === "exit") {
+        armed = false;
+        exit(0);
+    }
+};
+// Keep stdin open as a lifeline to the parent process.
+try {
+    process.stdin.resume();
+    process.stdin.on("end", onLifelineClosed);
+    process.stdin.on("close", onLifelineClosed);
+    process.stdin.on("error", onLifelineClosed);
+}
+catch {
+    // ignore
+}
+process.on("disconnect", onLifelineClosed);
+process.on("message", onMessage);
+//# sourceMappingURL=supervisor.js.map

package/dist/esm/lib/v3/shutdown/supervisor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.js","sourceRoot":"","sources":["../../../../../lib/v3/shutdown/supervisor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Shutdown supervisor process.\n *\n * This process watches a lifeline (stdin/IPC). When the parent dies, the\n * lifeline closes and the supervisor performs best-effort cleanup:\n * - LOCAL: kill Chrome + remove temp profile (when keepAlive is false)\n * - STAGEHAND_API: request session release (when keepAlive is false)\n */\n\nimport Browserbase from \"@browserbasehq/sdk\";\nimport type {\n  ShutdownSupervisorConfig,\n  ShutdownSupervisorMessage,\n} from \"../types/private/shutdown.js\";\nimport { cleanupLocalBrowser } from \"./cleanupLocal.js\";\n\nconst SIGKILL_POLL_MS = 500;\nconst SIGKILL_TIMEOUT_MS = 10_000;\nconst PID_POLL_INTERVAL_MS = 500;\n\nlet armed = false;\nlet config: ShutdownSupervisorConfig | null = null;\nlet cleanupPromise: Promise<void> | null = null;\n\nconst exit = (code = 0): void => {\n  try {\n    process.exit(code);\n  } catch {\n    // ignore\n  }\n};\n\nconst safeKill = async (pid: number): Promise<void> => {\n  const isAlive = (): boolean => {\n    try {\n      process.kill(pid, 0);\n      return true;\n    } catch {\n      return false;\n    }\n  };\n\n  if (!isAlive()) return;\n  try {\n    process.kill(pid, \"SIGTERM\");\n  } catch {\n    return;\n  }\n\n  const deadline = Date.now() + SIGKILL_TIMEOUT_MS;\n  while (Date.now() < deadline) {\n    await new Promise((resolve) => setTimeout(resolve, SIGKILL_POLL_MS));\n    if (!isAlive()) return;\n  }\n  try {\n    process.kill(pid, \"SIGKILL\");\n  } catch {\n    // best-effort\n  }\n};\n\nlet pidGone = false;\nlet pidPollTimer: NodeJS.Timeout | null = null;\n\nconst startPidPolling = (pid: number): void => {\n  if (pidPollTimer) return;\n  pidPollTimer = setInterval(() => {\n    try {\n      process.kill(pid, 0);\n    } catch {\n      pidGone = true;\n      if (pidPollTimer) {\n        clearInterval(pidPollTimer);\n        pidPollTimer = null;\n      }\n    }\n  }, PID_POLL_INTERVAL_MS);\n};\n\nconst cleanupLocal = async (\n  cfg: Extract<ShutdownSupervisorConfig, { kind: \"LOCAL\" }>,\n) => {\n  if (cfg.keepAlive) return;\n  await cleanupLocalBrowser({\n    killChrome: cfg.pid && !pidGone ? () => safeKill(cfg.pid) : undefined,\n    userDataDir: cfg.userDataDir,\n    createdTempProfile: cfg.createdTempProfile,\n    preserveUserDataDir: cfg.preserveUserDataDir,\n  });\n};\n\nconst cleanupBrowserbase = async (\n  cfg: Extract<ShutdownSupervisorConfig, { kind: \"STAGEHAND_API\" }>,\n) => {\n  if (cfg.keepAlive) return;\n  if (!cfg.apiKey || !cfg.projectId || !cfg.sessionId) return;\n  try {\n    const bb = new Browserbase({ apiKey: cfg.apiKey });\n    await bb.sessions.update(cfg.sessionId, {\n      status: \"REQUEST_RELEASE\",\n      projectId: cfg.projectId,\n    });\n  } catch {\n    // best-effort cleanup\n  }\n};\n\nconst runCleanup = (): Promise<void> => {\n  if (!cleanupPromise) {\n    cleanupPromise = (async () => {\n      const cfg = config;\n      if (!cfg || !armed) return;\n      armed = false;\n      if (cfg.kind === \"LOCAL\") {\n        await cleanupLocal(cfg);\n        return;\n      }\n      if (cfg.kind === \"STAGEHAND_API\") {\n        await cleanupBrowserbase(cfg);\n      }\n    })();\n  }\n  return cleanupPromise;\n};\n\nconst onLifelineClosed = () => {\n  void runCleanup().finally(() => exit(0));\n};\n\nconst onMessage = (raw: unknown) => {\n  if (!raw || typeof raw !== \"object\") return;\n  const msg = raw as ShutdownSupervisorMessage;\n  if (msg.type === \"config\") {\n    config = msg.config ?? null;\n    armed = Boolean(config) && config?.keepAlive === false;\n    if (armed && config?.kind === \"LOCAL\" && config?.pid) {\n      startPidPolling(config.pid);\n    }\n    try {\n      process.send?.({ type: \"ready\" });\n    } catch {\n      // ignore IPC failures\n    }\n    return;\n  }\n  if (msg.type === \"exit\") {\n    armed = false;\n    exit(0);\n  }\n};\n\n// Keep stdin open as a lifeline to the parent process.\ntry {\n  process.stdin.resume();\n  process.stdin.on(\"end\", onLifelineClosed);\n  process.stdin.on(\"close\", onLifelineClosed);\n  process.stdin.on(\"error\", onLifelineClosed);\n} catch {\n  // ignore\n}\n\nprocess.on(\"disconnect\", onLifelineClosed);\nprocess.on(\"message\", onMessage);\n"]}

package/dist/esm/lib/v3/shutdown/supervisorClient.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Parent-side helper for spawning the shutdown supervisor process.
+ *
+ * The supervisor runs out-of-process and watches a lifeline pipe. If the parent
+ * dies, the supervisor performs best-effort cleanup (Chrome kill or Browserbase
+ * session release) when keepAlive is false.
+ */
+import type { ShutdownSupervisorConfig, ShutdownSupervisorHandle } from "../types/private/shutdown.js";
+/**
+ * Start a supervisor process for crash cleanup. Returns a handle that can
+ * stop the supervisor during a normal shutdown.
+ */
+export declare function startShutdownSupervisor(config: ShutdownSupervisorConfig, opts?: {
+    onError?: (error: Error, context: string) => void;
+}): ShutdownSupervisorHandle | null;

package/dist/esm/lib/v3/shutdown/supervisorClient.js

@@ -0,0 +1,97 @@
+/**
+ * Parent-side helper for spawning the shutdown supervisor process.
+ *
+ * The supervisor runs out-of-process and watches a lifeline pipe. If the parent
+ * dies, the supervisor performs best-effort cleanup (Chrome kill or Browserbase
+ * session release) when keepAlive is false.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { ShutdownSupervisorResolveError, ShutdownSupervisorSpawnError, } from "../types/private/shutdownErrors.js";
+const READY_TIMEOUT_MS = 500;
+// Prefer import.meta.url — always correct per-module in ESM.
+// __dirname may be an incorrect polyfill in some tsx / loader configurations.
+const thisDir = path.dirname(fileURLToPath(import.meta.url));
+const resolveSupervisorScript = () => {
+    const jsPath = path.resolve(thisDir, "supervisor.js");
+    if (fs.existsSync(jsPath)) {
+        return { command: process.execPath, args: [jsPath] };
+    }
+    const tsPath = path.resolve(thisDir, "supervisor.ts");
+    if (fs.existsSync(tsPath)) {
+        return { command: process.execPath, args: ["--import", "tsx", tsPath] };
+    }
+    return null;
+};
+/**
+ * Start a supervisor process for crash cleanup. Returns a handle that can
+ * stop the supervisor during a normal shutdown.
+ */
+export function startShutdownSupervisor(config, opts) {
+    const resolved = resolveSupervisorScript();
+    if (!resolved) {
+        opts?.onError?.(new ShutdownSupervisorResolveError(`Shutdown supervisor script missing (searched ${thisDir} for supervisor.js or supervisor.ts).`), "resolve");
+        return null;
+    }
+    const child = spawn(resolved.command, resolved.args, {
+        stdio: ["pipe", "ignore", "ignore", "ipc"],
+        detached: true,
+    });
+    child.on("error", (error) => {
+        opts?.onError?.(new ShutdownSupervisorSpawnError(`Shutdown supervisor failed to start: ${error.message}`), "spawn");
+    });
+    try {
+        child.unref();
+        const stdin = child.stdin;
+        stdin?.unref?.();
+    }
+    catch {
+        // best-effort: avoid keeping the event loop alive
+    }
+    try {
+        const message = { type: "config", config };
+        child.send?.(message);
+    }
+    catch {
+        // ignore IPC failures
+    }
+    const ready = new Promise((resolve) => {
+        let resolved = false;
+        const done = () => {
+            if (resolved)
+                return;
+            resolved = true;
+            clearTimeout(timer);
+            child.off("message", onMessage);
+            resolve();
+        };
+        const timer = setTimeout(done, READY_TIMEOUT_MS);
+        const onMessage = (msg) => {
+            const payload = msg;
+            if (payload?.type === "ready") {
+                done();
+            }
+        };
+        child.on("message", onMessage);
+        child.on("exit", done);
+    });
+    const stop = () => {
+        try {
+            const message = { type: "exit" };
+            child.send?.(message);
+        }
+        catch {
+            // ignore
+        }
+        try {
+            child.disconnect?.();
+        }
+        catch {
+            // ignore
+        }
+    };
+    return { stop, ready };
+}
+//# sourceMappingURL=supervisorClient.js.map

package/dist/esm/lib/v3/shutdown/supervisorClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisorClient.js","sourceRoot":"","sources":["../../../../../lib/v3/shutdown/supervisorClient.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAMzC,OAAO,EACL,8BAA8B,EAC9B,4BAA4B,GAC7B,MAAM,oCAAoC,CAAC;AAE5C,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAC7B,6DAA6D;AAC7D,8EAA8E;AAC9E,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE7D,MAAM,uBAAuB,GAAG,GAGvB,EAAE;IACT,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;IACtD,IAAI,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC;IACvD,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;IACtD,IAAI,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,UAAU,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC;IAC1E,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CACrC,MAAgC,EAChC,IAA4D;IAE5D,MAAM,QAAQ,GAAG,uBAAuB,EAAE,CAAC;IAC3C,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,IAAI,EAAE,OAAO,EAAE,CACb,IAAI,8BAA8B,CAChC,gDAAgD,OAAO,uCAAuC,CAC/F,EACD,SAAS,CACV,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,IAAI,EAAE;QACnD,KAAK,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC;QAC1C,QAAQ,EAAE,IAAI;KACf,CAAC,CAAC;IACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;QAC1B,IAAI,EAAE,OAAO,EAAE,CACb,IAAI,4BAA4B,CAC9B,wCAAwC,KAAK,CAAC,OAAO,EAAE,CACxD,EACD,OAAO,CACR,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC;QACH,KAAK,CAAC,KAAK,EAAE,CAAC;QACd,MAAM,KAAK,GAAG,KAAK,CAAC,KAAiD,CAAC;QACtE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC;IACnB,CAAC;IAAC,MAAM,CAAC;QACP,kDAAkD;IACpD,CAAC;IAED,IAAI,CAAC;QACH,MAAM,OAAO,GAA8B,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;QACtE,KAAK,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,sBAAsB;IACxB,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAC1C,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,MAAM,IAAI,GAAG,GAAG,EAAE;YAChB,IAAI,QAAQ;gBAAE,OAAO;YACrB,QAAQ,GAAG,IAAI,CAAC;YAChB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,KAAK,CAAC,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;YAChC,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC;QACF,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;QACjD,MAAM,SAAS,GAAG,CAAC,GAAY,EAAE,EAAE;YACjC,MAAM,OAAO,GAAG,GAAgC,CAAC;YACjD,IAAI,OAAO,EAAE,IAAI,KAAK,OAAO,EAAE,CAAC;gBAC9B,IAAI,EAAE,CAAC;YACT,CAAC;QACH,CAAC,CAAC;QACF,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;QAC/B,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACzB,CAAC,CAAC,CAAC;IAEH,MAAM,IAAI,GAAG,GAAG,EAAE;QAChB,IAAI,CAAC;YACH,MAAM,OAAO,GAA8B,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;YAC5D,KAAK,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,CAAC;QACxB,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,IAAI,CAAC;YACH,KAAK,CAAC,UAAU,EAAE,EAAE,CAAC;QACvB,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;IACH,CAAC,CAAC;IAEF,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AACzB,CAAC","sourcesContent":["/**\n * Parent-side helper for spawning the shutdown supervisor process.\n *\n * The supervisor runs out-of-process and watches a lifeline pipe. If the parent\n * dies, the supervisor performs best-effort cleanup (Chrome kill or Browserbase\n * session release) when keepAlive is false.\n */\n\nimport fs from \"node:fs\";\nimport path from \"node:path\";\nimport { spawn } from \"node:child_process\";\nimport { fileURLToPath } from \"node:url\";\nimport type {\n  ShutdownSupervisorConfig,\n  ShutdownSupervisorHandle,\n  ShutdownSupervisorMessage,\n} from \"../types/private/shutdown.js\";\nimport {\n  ShutdownSupervisorResolveError,\n  ShutdownSupervisorSpawnError,\n} from \"../types/private/shutdownErrors.js\";\n\nconst READY_TIMEOUT_MS = 500;\n// Prefer import.meta.url — always correct per-module in ESM.\n// __dirname may be an incorrect polyfill in some tsx / loader configurations.\nconst thisDir = path.dirname(fileURLToPath(import.meta.url));\n\nconst resolveSupervisorScript = (): {\n  command: string;\n  args: string[];\n} | null => {\n  const jsPath = path.resolve(thisDir, \"supervisor.js\");\n  if (fs.existsSync(jsPath)) {\n    return { command: process.execPath, args: [jsPath] };\n  }\n  const tsPath = path.resolve(thisDir, \"supervisor.ts\");\n  if (fs.existsSync(tsPath)) {\n    return { command: process.execPath, args: [\"--import\", \"tsx\", tsPath] };\n  }\n  return null;\n};\n\n/**\n * Start a supervisor process for crash cleanup. Returns a handle that can\n * stop the supervisor during a normal shutdown.\n */\nexport function startShutdownSupervisor(\n  config: ShutdownSupervisorConfig,\n  opts?: { onError?: (error: Error, context: string) => void },\n): ShutdownSupervisorHandle | null {\n  const resolved = resolveSupervisorScript();\n  if (!resolved) {\n    opts?.onError?.(\n      new ShutdownSupervisorResolveError(\n        `Shutdown supervisor script missing (searched ${thisDir} for supervisor.js or supervisor.ts).`,\n      ),\n      \"resolve\",\n    );\n    return null;\n  }\n\n  const child = spawn(resolved.command, resolved.args, {\n    stdio: [\"pipe\", \"ignore\", \"ignore\", \"ipc\"],\n    detached: true,\n  });\n  child.on(\"error\", (error) => {\n    opts?.onError?.(\n      new ShutdownSupervisorSpawnError(\n        `Shutdown supervisor failed to start: ${error.message}`,\n      ),\n      \"spawn\",\n    );\n  });\n\n  try {\n    child.unref();\n    const stdin = child.stdin as unknown as { unref?: () => void } | null;\n    stdin?.unref?.();\n  } catch {\n    // best-effort: avoid keeping the event loop alive\n  }\n\n  try {\n    const message: ShutdownSupervisorMessage = { type: \"config\", config };\n    child.send?.(message);\n  } catch {\n    // ignore IPC failures\n  }\n\n  const ready = new Promise<void>((resolve) => {\n    let resolved = false;\n    const done = () => {\n      if (resolved) return;\n      resolved = true;\n      clearTimeout(timer);\n      child.off(\"message\", onMessage);\n      resolve();\n    };\n    const timer = setTimeout(done, READY_TIMEOUT_MS);\n    const onMessage = (msg: unknown) => {\n      const payload = msg as ShutdownSupervisorMessage;\n      if (payload?.type === \"ready\") {\n        done();\n      }\n    };\n    child.on(\"message\", onMessage);\n    child.on(\"exit\", done);\n  });\n\n  const stop = () => {\n    try {\n      const message: ShutdownSupervisorMessage = { type: \"exit\" };\n      child.send?.(message);\n    } catch {\n      // ignore\n    }\n    try {\n      child.disconnect?.();\n    } catch {\n      // ignore\n    }\n  };\n\n  return { stop, ready };\n}\n"]}

package/dist/esm/lib/v3/tests/agent-abort-signal.spec.js

@@ -0,0 +1,113 @@
+import { test, expect } from "@playwright/test";
+import { V3 } from "../v3.js";
+import { v3TestConfig } from "./v3.config.js";
+import { AgentAbortError } from "../types/public/sdkErrors.js";
+test.describe("Stagehand agent abort signal", () => {
+  let v3;
+  test.beforeEach(async () => {
+    v3 = new V3({
+      ...v3TestConfig,
+      experimental: true
+    });
+    await v3.init();
+  });
+  test.afterEach(async () => {
+    await v3?.close?.().catch(() => {
+    });
+  });
+  test("non-streaming: abort signal stops execution and throws AgentAbortError", async () => {
+    test.setTimeout(6e4);
+    const agent = v3.agent({
+      model: "anthropic/claude-haiku-4-5-20251001"
+    });
+    const page = v3.context.pages()[0];
+    await page.goto("https://example.com");
+    const controller = new AbortController();
+    setTimeout(() => controller.abort(), 500);
+    await expect(
+      agent.execute({
+        instruction: "Describe every visual element on this page in extreme detail. Describe at least 100 different elements.",
+        maxSteps: 50,
+        signal: controller.signal
+      })
+    ).rejects.toThrow(AgentAbortError);
+  });
+  test("streaming: abort signal stops stream and rejects result with AgentAbortError", async () => {
+    test.setTimeout(6e4);
+    const agent = v3.agent({
+      stream: true,
+      model: "anthropic/claude-haiku-4-5-20251001"
+    });
+    const page = v3.context.pages()[0];
+    await page.goto("https://example.com");
+    const controller = new AbortController();
+    setTimeout(() => controller.abort(), 500);
+    const streamResult = await agent.execute({
+      instruction: "Describe every visual element on this page in extreme detail. Describe at least 100 different elements.",
+      maxSteps: 50,
+      signal: controller.signal
+    });
+    const consumeStream = async () => {
+      for await (const _ of streamResult.textStream) {
+      }
+    };
+    const [, resultError] = await Promise.allSettled([
+      consumeStream(),
+      streamResult.result
+    ]);
+    expect(resultError.status).toBe("rejected");
+    expect(resultError.reason).toBeInstanceOf(
+      AgentAbortError
+    );
+  });
+  test("non-streaming: already aborted signal throws AgentAbortError immediately", async () => {
+    test.setTimeout(2e4);
+    const agent = v3.agent({
+      model: "anthropic/claude-haiku-4-5-20251001"
+    });
+    const page = v3.context.pages()[0];
+    await page.goto("https://example.com");
+    const controller = new AbortController();
+    controller.abort();
+    await expect(
+      agent.execute({
+        instruction: "This should not run.",
+        maxSteps: 3,
+        signal: controller.signal
+      })
+    ).rejects.toThrow(AgentAbortError);
+  });
+  test("non-streaming: execution completes normally without abort signal", async () => {
+    test.setTimeout(6e4);
+    const agent = v3.agent({
+      model: "anthropic/claude-haiku-4-5-20251001"
+    });
+    const page = v3.context.pages()[0];
+    await page.goto("https://example.com");
+    const result = await agent.execute({
+      instruction: "Describe this page briefly.",
+      maxSteps: 3
+    });
+    expect(result.success).toBe(true);
+    expect(result.completed).toBe(true);
+  });
+  test("streaming: execution completes normally without abort signal", async () => {
+    test.setTimeout(6e4);
+    const agent = v3.agent({
+      stream: true,
+      model: "anthropic/claude-haiku-4-5-20251001"
+    });
+    const page = v3.context.pages()[0];
+    await page.goto("https://example.com");
+    const streamResult = await agent.execute({
+      instruction: "Describe this page briefly.",
+      maxSteps: 3
+    });
+    for await (const _ of streamResult.textStream) {
+    }
+    const result = await streamResult.result;
+    expect(result.success).toBe(true);
+    expect(result.completed).toBe(true);
+  });
+});
+//# sourceMappingURL=agent-abort-signal.spec.js.map

package/dist/esm/lib/v3/tests/agent-abort-signal.spec.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../lib/v3/tests/agent-abort-signal.spec.ts"],
+  "sourcesContent": ["import { test, expect } from \"@playwright/test\";\nimport { V3 } from \"../v3.js\";\nimport { v3TestConfig } from \"./v3.config.js\";\nimport { AgentAbortError } from \"../types/public/sdkErrors.js\";\n\ntest.describe(\"Stagehand agent abort signal\", () => {\n  let v3: V3;\n\n  test.beforeEach(async () => {\n    v3 = new V3({\n      ...v3TestConfig,\n      experimental: true,\n    });\n    await v3.init();\n  });\n\n  test.afterEach(async () => {\n    await v3?.close?.().catch(() => {});\n  });\n\n  test(\"non-streaming: abort signal stops execution and throws AgentAbortError\", async () => {\n    test.setTimeout(60000);\n\n    const agent = v3.agent({\n      model: \"anthropic/claude-haiku-4-5-20251001\",\n    });\n\n    const page = v3.context.pages()[0];\n    await page.goto(\"https://example.com\");\n\n    const controller = new AbortController();\n\n    // Abort after 500ms - should be enough for the LLM to start but not finish\n    setTimeout(() => controller.abort(), 500);\n\n    await expect(\n      agent.execute({\n        instruction:\n          \"Describe every visual element on this page in extreme detail. Describe at least 100 different elements.\",\n        maxSteps: 50,\n        signal: controller.signal,\n      }),\n    ).rejects.toThrow(AgentAbortError);\n  });\n\n  test(\"streaming: abort signal stops stream and rejects result with AgentAbortError\", async () => {\n    test.setTimeout(60000);\n\n    const agent = v3.agent({\n      stream: true,\n      model: \"anthropic/claude-haiku-4-5-20251001\",\n    });\n\n    const page = v3.context.pages()[0];\n    await page.goto(\"https://example.com\");\n\n    const controller = new AbortController();\n\n    // Abort after 500ms\n    setTimeout(() => controller.abort(), 500);\n\n    const streamResult = await agent.execute({\n      instruction:\n        \"Describe every visual element on this page in extreme detail. Describe at least 100 different elements.\",\n      maxSteps: 50,\n      signal: controller.signal,\n    });\n\n    // Handle both stream consumption and result promise together\n    // The result promise will reject with AgentAbortError when aborted\n    const consumeStream = async () => {\n      // eslint-disable-next-line @typescript-eslint/no-unused-vars\n      for await (const _ of streamResult.textStream) {\n        // Just consume chunks until stream ends\n      }\n    };\n\n    // Both should complete - stream ends and result rejects\n    const [, resultError] = await Promise.allSettled([\n      consumeStream(),\n      streamResult.result,\n    ]);\n\n    // The result should have rejected with AgentAbortError\n    expect(resultError.status).toBe(\"rejected\");\n    expect((resultError as PromiseRejectedResult).reason).toBeInstanceOf(\n      AgentAbortError,\n    );\n  });\n\n  test(\"non-streaming: already aborted signal throws AgentAbortError immediately\", async () => {\n    test.setTimeout(20000);\n\n    const agent = v3.agent({\n      model: \"anthropic/claude-haiku-4-5-20251001\",\n    });\n\n    const page = v3.context.pages()[0];\n    await page.goto(\"https://example.com\");\n\n    // Create an already aborted controller\n    const controller = new AbortController();\n    controller.abort();\n\n    await expect(\n      agent.execute({\n        instruction: \"This should not run.\",\n        maxSteps: 3,\n        signal: controller.signal,\n      }),\n    ).rejects.toThrow(AgentAbortError);\n  });\n\n  test(\"non-streaming: execution completes normally without abort signal\", async () => {\n    test.setTimeout(60000);\n\n    const agent = v3.agent({\n      model: \"anthropic/claude-haiku-4-5-20251001\",\n    });\n\n    const page = v3.context.pages()[0];\n    await page.goto(\"https://example.com\");\n\n    // No signal provided - should complete normally\n    const result = await agent.execute({\n      instruction: \"Describe this page briefly.\",\n      maxSteps: 3,\n    });\n\n    expect(result.success).toBe(true);\n    expect(result.completed).toBe(true);\n  });\n\n  test(\"streaming: execution completes normally without abort signal\", async () => {\n    test.setTimeout(60000);\n\n    const agent = v3.agent({\n      stream: true,\n      model: \"anthropic/claude-haiku-4-5-20251001\",\n    });\n\n    const page = v3.context.pages()[0];\n    await page.goto(\"https://example.com\");\n\n    // No signal provided - should complete normally\n    const streamResult = await agent.execute({\n      instruction: \"Describe this page briefly.\",\n      maxSteps: 3,\n    });\n\n    // Consume the stream first\n    // eslint-disable-next-line @typescript-eslint/no-unused-vars\n    for await (const _ of streamResult.textStream) {\n      // Just consume\n    }\n\n    // Now get the final result\n    const result = await streamResult.result;\n\n    expect(result.success).toBe(true);\n    expect(result.completed).toBe(true);\n  });\n});\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/esm/lib/v3/tests/agent-cache-self-heal.spec.js

@@ -0,0 +1,80 @@
+import { test, expect } from "@playwright/test";
+import fs from "fs/promises";
+import path from "path";
+import { V3 } from "../v3.js";
+import { v3TestConfig } from "./v3.config.js";
+test.describe("Agent cache self-heal (e2e)", () => {
+  let v3;
+  let cacheDir;
+  test.beforeEach(async ({}, testInfo) => {
+    await fs.mkdir(testInfo.outputDir, { recursive: true });
+    cacheDir = await fs.mkdtemp(path.join(testInfo.outputDir, "agent-cache-"));
+    v3 = new V3({
+      ...v3TestConfig,
+      cacheDir,
+      selfHeal: true
+    });
+    await v3.init();
+  });
+  test.afterEach(async () => {
+    await v3?.close?.().catch(() => {
+    });
+  });
+  test("replays heal corrupted selectors", async () => {
+    test.setTimeout(12e4);
+    const agent = v3.agent({
+      model: "anthropic/claude-haiku-4-5-20251001"
+    });
+    const page = v3.context.pages()[0];
+    const url = "https://browserbase.github.io/stagehand-eval-sites/sites/shadow-dom/";
+    const instruction = "click the button";
+    await page.goto(url, { waitUntil: "networkidle" });
+    const firstResult = await agent.execute({ instruction, maxSteps: 20 });
+    expect(firstResult.success).toBe(true);
+    const cachePath = await locateAgentCacheFile(cacheDir);
+    const originalEntry = await readCacheEntry(cachePath);
+    const originalActionStep = findFirstActionStep(originalEntry);
+    expect(originalActionStep).toBeDefined();
+    const originalSelector = originalActionStep?.actions?.[0]?.selector;
+    expect(typeof originalSelector).toBe("string");
+    if (originalActionStep?.actions?.[0]) {
+      originalActionStep.actions[0].selector = "xpath=/yeee";
+    }
+    await fs.writeFile(
+      cachePath,
+      JSON.stringify(originalEntry, null, 2),
+      "utf8"
+    );
+    await page.goto(url, { waitUntil: "networkidle" });
+    const replayResult = await agent.execute({ instruction, maxSteps: 20 });
+    expect(replayResult.success).toBe(true);
+    const healedEntry = await readCacheEntry(cachePath);
+    const healedActionStep = findFirstActionStep(healedEntry);
+    expect(healedActionStep?.actions?.[0]?.selector).toBe(originalSelector);
+    expect(healedActionStep?.actions?.[0]?.selector).not.toBe("xpath=/yeee");
+    expect(healedEntry.timestamp).not.toBe(originalEntry.timestamp);
+  });
+});
+async function locateAgentCacheFile(cacheDir) {
+  const deadline = Date.now() + 1e4;
+  while (Date.now() < deadline) {
+    const entries = await fs.readdir(cacheDir);
+    const agentFiles = entries.filter((file) => file.startsWith("agent-"));
+    if (agentFiles.length > 0) {
+      return path.join(cacheDir, agentFiles[0]);
+    }
+    await new Promise((resolve) => setTimeout(resolve, 200));
+  }
+  throw new Error("Timed out waiting for agent cache entry to be written");
+}
+async function readCacheEntry(cachePath) {
+  const raw = await fs.readFile(cachePath, "utf8");
+  return JSON.parse(raw);
+}
+function findFirstActionStep(entry) {
+  return entry.steps.find((step) => {
+    const actions = step.actions;
+    return Array.isArray(actions) && actions.length > 0;
+  });
+}
+//# sourceMappingURL=agent-cache-self-heal.spec.js.map

package/dist/esm/lib/v3/tests/agent-cache-self-heal.spec.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../lib/v3/tests/agent-cache-self-heal.spec.ts"],
+  "sourcesContent": ["import { test, expect } from \"@playwright/test\";\nimport fs from \"fs/promises\";\nimport path from \"path\";\nimport { V3 } from \"../v3.js\";\nimport { v3TestConfig } from \"./v3.config.js\";\nimport type {\n  AgentReplayActStep,\n  AgentReplayFillFormStep,\n  CachedAgentEntry,\n} from \"../types/private/cache.js\";\n\ntest.describe(\"Agent cache self-heal (e2e)\", () => {\n  let v3: V3;\n  let cacheDir: string;\n\n  // eslint-disable-next-line no-empty-pattern\n  test.beforeEach(async ({}, testInfo) => {\n    await fs.mkdir(testInfo.outputDir, { recursive: true });\n    cacheDir = await fs.mkdtemp(path.join(testInfo.outputDir, \"agent-cache-\"));\n    v3 = new V3({\n      ...v3TestConfig,\n      cacheDir,\n      selfHeal: true,\n    });\n    await v3.init();\n  });\n\n  test.afterEach(async () => {\n    await v3?.close?.().catch(() => {});\n  });\n\n  test(\"replays heal corrupted selectors\", async () => {\n    test.setTimeout(120_000);\n\n    const agent = v3.agent({\n      model: \"anthropic/claude-haiku-4-5-20251001\",\n    });\n    const page = v3.context.pages()[0];\n    const url =\n      \"https://browserbase.github.io/stagehand-eval-sites/sites/shadow-dom/\";\n    const instruction = \"click the button\";\n\n    await page.goto(url, { waitUntil: \"networkidle\" });\n    const firstResult = await agent.execute({ instruction, maxSteps: 20 });\n    expect(firstResult.success).toBe(true);\n\n    const cachePath = await locateAgentCacheFile(cacheDir);\n    const originalEntry = await readCacheEntry(cachePath);\n    const originalActionStep = findFirstActionStep(originalEntry);\n    expect(originalActionStep).toBeDefined();\n    const originalSelector = originalActionStep?.actions?.[0]?.selector;\n    expect(typeof originalSelector).toBe(\"string\");\n\n    // Corrupt the cached selector so the replay needs to self-heal.\n    if (originalActionStep?.actions?.[0]) {\n      originalActionStep.actions[0].selector = \"xpath=/yeee\";\n    }\n    await fs.writeFile(\n      cachePath,\n      JSON.stringify(originalEntry, null, 2),\n      \"utf8\",\n    );\n\n    // Second run should replay from cache, self-heal, and update the file.\n    await page.goto(url, { waitUntil: \"networkidle\" });\n    const replayResult = await agent.execute({ instruction, maxSteps: 20 });\n    expect(replayResult.success).toBe(true);\n\n    const healedEntry = await readCacheEntry(cachePath);\n    const healedActionStep = findFirstActionStep(healedEntry);\n    expect(healedActionStep?.actions?.[0]?.selector).toBe(originalSelector);\n    expect(healedActionStep?.actions?.[0]?.selector).not.toBe(\"xpath=/yeee\");\n    expect(healedEntry.timestamp).not.toBe(originalEntry.timestamp);\n  });\n});\n\nasync function locateAgentCacheFile(cacheDir: string): Promise<string> {\n  const deadline = Date.now() + 10_000;\n  while (Date.now() < deadline) {\n    const entries = await fs.readdir(cacheDir);\n    const agentFiles = entries.filter((file) => file.startsWith(\"agent-\"));\n    if (agentFiles.length > 0) {\n      return path.join(cacheDir, agentFiles[0]!);\n    }\n    await new Promise((resolve) => setTimeout(resolve, 200));\n  }\n  throw new Error(\"Timed out waiting for agent cache entry to be written\");\n}\n\nasync function readCacheEntry(cachePath: string): Promise<CachedAgentEntry> {\n  const raw = await fs.readFile(cachePath, \"utf8\");\n  return JSON.parse(raw) as CachedAgentEntry;\n}\n\ntype StepWithActions = AgentReplayActStep | AgentReplayFillFormStep;\n\nfunction findFirstActionStep(\n  entry: CachedAgentEntry,\n): StepWithActions | undefined {\n  return entry.steps.find((step) => {\n    const actions = (step as StepWithActions).actions;\n    return Array.isArray(actions) && actions.length > 0;\n  }) as StepWithActions | undefined;\n}\n"],
+  "mappings": "AAAA,SAAS,MAAM,cAAc;AAC7B,OAAO,QAAQ;AACf,OAAO,UAAU;AACjB,SAAS,UAAU;AACnB,SAAS,oBAAoB;AAO7B,KAAK,SAAS,+BAA+B,MAAM;AACjD,MAAI;AACJ,MAAI;AAGJ,OAAK,WAAW,OAAO,CAAC,GAAG,aAAa;AACtC,UAAM,GAAG,MAAM,SAAS,WAAW,EAAE,WAAW,KAAK,CAAC;AACtD,eAAW,MAAM,GAAG,QAAQ,KAAK,KAAK,SAAS,WAAW,cAAc,CAAC;AACzE,SAAK,IAAI,GAAG;AAAA,MACV,GAAG;AAAA,MACH;AAAA,MACA,UAAU;AAAA,IACZ,CAAC;AACD,UAAM,GAAG,KAAK;AAAA,EAChB,CAAC;AAED,OAAK,UAAU,YAAY;AACzB,UAAM,IAAI,QAAQ,EAAE,MAAM,MAAM;AAAA,IAAC,CAAC;AAAA,EACpC,CAAC;AAED,OAAK,oCAAoC,YAAY;AACnD,SAAK,WAAW,IAAO;AAEvB,UAAM,QAAQ,GAAG,MAAM;AAAA,MACrB,OAAO;AAAA,IACT,CAAC;AACD,UAAM,OAAO,GAAG,QAAQ,MAAM,EAAE,CAAC;AACjC,UAAM,MACJ;AACF,UAAM,cAAc;AAEpB,UAAM,KAAK,KAAK,KAAK,EAAE,WAAW,cAAc,CAAC;AACjD,UAAM,cAAc,MAAM,MAAM,QAAQ,EAAE,aAAa,UAAU,GAAG,CAAC;AACrE,WAAO,YAAY,OAAO,EAAE,KAAK,IAAI;AAErC,UAAM,YAAY,MAAM,qBAAqB,QAAQ;AACrD,UAAM,gBAAgB,MAAM,eAAe,SAAS;AACpD,UAAM,qBAAqB,oBAAoB,aAAa;AAC5D,WAAO,kBAAkB,EAAE,YAAY;AACvC,UAAM,mBAAmB,oBAAoB,UAAU,CAAC,GAAG;AAC3D,WAAO,OAAO,gBAAgB,EAAE,KAAK,QAAQ;AAG7C,QAAI,oBAAoB,UAAU,CAAC,GAAG;AACpC,yBAAmB,QAAQ,CAAC,EAAE,WAAW;AAAA,IAC3C;AACA,UAAM,GAAG;AAAA,MACP;AAAA,MACA,KAAK,UAAU,eAAe,MAAM,CAAC;AAAA,MACrC;AAAA,IACF;AAGA,UAAM,KAAK,KAAK,KAAK,EAAE,WAAW,cAAc,CAAC;AACjD,UAAM,eAAe,MAAM,MAAM,QAAQ,EAAE,aAAa,UAAU,GAAG,CAAC;AACtE,WAAO,aAAa,OAAO,EAAE,KAAK,IAAI;AAEtC,UAAM,cAAc,MAAM,eAAe,SAAS;AAClD,UAAM,mBAAmB,oBAAoB,WAAW;AACxD,WAAO,kBAAkB,UAAU,CAAC,GAAG,QAAQ,EAAE,KAAK,gBAAgB;AACtE,WAAO,kBAAkB,UAAU,CAAC,GAAG,QAAQ,EAAE,IAAI,KAAK,aAAa;AACvE,WAAO,YAAY,SAAS,EAAE,IAAI,KAAK,cAAc,SAAS;AAAA,EAChE,CAAC;AACH,CAAC;AAED,eAAe,qBAAqB,UAAmC;AACrE,QAAM,WAAW,KAAK,IAAI,IAAI;AAC9B,SAAO,KAAK,IAAI,IAAI,UAAU;AAC5B,UAAM,UAAU,MAAM,GAAG,QAAQ,QAAQ;AACzC,UAAM,aAAa,QAAQ,OAAO,CAAC,SAAS,KAAK,WAAW,QAAQ,CAAC;AACrE,QAAI,WAAW,SAAS,GAAG;AACzB,aAAO,KAAK,KAAK,UAAU,WAAW,CAAC,CAAE;AAAA,IAC3C;AACA,UAAM,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,GAAG,CAAC;AAAA,EACzD;AACA,QAAM,IAAI,MAAM,uDAAuD;AACzE;AAEA,eAAe,eAAe,WAA8C;AAC1E,QAAM,MAAM,MAAM,GAAG,SAAS,WAAW,MAAM;AAC/C,SAAO,KAAK,MAAM,GAAG;AACvB;AAIA,SAAS,oBACP,OAC6B;AAC7B,SAAO,MAAM,MAAM,KAAK,CAAC,SAAS;AAChC,UAAM,UAAW,KAAyB;AAC1C,WAAO,MAAM,QAAQ,OAAO,KAAK,QAAQ,SAAS;AAAA,EACpD,CAAC;AACH;",
+  "names": []
+}