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

package/dist/cjs/tests/public-api/v3-core.test.js

@@ -0,0 +1,104 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var import_vitest = require("vitest");
+var Stagehand = __toESM(require("@browserbasehq/stagehand"), 1);
+(0, import_vitest.describe)("V3 Core public API types", () => {
+  (0, import_vitest.describe)("Stagehand", () => {
+    (0, import_vitest.it)("has correct public interface shape", () => {
+      (0, import_vitest.expectTypeOf)().toExtend();
+    });
+    (0, import_vitest.it)("act accepts Action as first parameter", () => {
+      const mockAction = {};
+      (0, import_vitest.expectTypeOf)().toBeCallableWith(
+        mockAction,
+        {}
+      );
+    });
+    (0, import_vitest.it)("extract accepts instruction and schema", () => {
+      const mockSchema = {};
+      (0, import_vitest.expectTypeOf)().toBeCallableWith(
+        "instruction",
+        mockSchema,
+        {}
+      );
+    });
+    (0, import_vitest.it)("observe accepts instruction and options", () => {
+      (0, import_vitest.expectTypeOf)().toBeCallableWith(
+        "instruction",
+        {}
+      );
+    });
+    (0, import_vitest.it)("agent execute accepts page option", () => {
+      const mockPage = {};
+      (0, import_vitest.expectTypeOf)().toBeCallableWith({
+        instruction: "test",
+        page: mockPage
+      });
+    });
+  });
+  (0, import_vitest.describe)("StagehandMetrics", () => {
+    (0, import_vitest.it)("matches the published metrics shape", () => {
+      (0, import_vitest.expectTypeOf)().toEqualTypeOf();
+    });
+  });
+  (0, import_vitest.describe)("V3", () => {
+    (0, import_vitest.it)("is exported", () => {
+      (0, import_vitest.expect)(Stagehand.V3).toBeDefined();
+    });
+  });
+  (0, import_vitest.describe)("V3Evaluator", () => {
+    (0, import_vitest.it)("is exported", () => {
+      (0, import_vitest.expect)(Stagehand.V3Evaluator).toBeDefined();
+    });
+    (0, import_vitest.it)("has ask method", () => {
+      (0, import_vitest.expectTypeOf)().toExtend();
+    });
+    (0, import_vitest.it)("has batchAsk method", () => {
+      (0, import_vitest.expectTypeOf)().toExtend();
+    });
+  });
+  (0, import_vitest.describe)("V3FunctionName", () => {
+    const expectedFunctionNames = [
+      "ACT",
+      "EXTRACT",
+      "OBSERVE",
+      "AGENT"
+    ];
+    (0, import_vitest.it)("matches the known function name literals", () => {
+      (0, import_vitest.expectTypeOf)().toExtend();
+    });
+  });
+  (0, import_vitest.describe)("connectToMCPServer", () => {
+    (0, import_vitest.it)("has correct parameter types", () => {
+      (0, import_vitest.expectTypeOf)(
+        Stagehand.connectToMCPServer
+      ).parameters.branded.toEqualTypeOf();
+    });
+  });
+  (0, import_vitest.describe)("LOG_LEVEL_NAMES", () => {
+    (0, import_vitest.it)("maps numeric levels to strings", () => {
+      (0, import_vitest.expectTypeOf)().toExtend();
+    });
+  });
+});
+//# sourceMappingURL=v3-core.test.js.map

package/dist/cjs/tests/public-api/v3-core.test.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../tests/public-api/v3-core.test.ts"],
+  "sourcesContent": ["import { describe, expect, expectTypeOf, it } from \"vitest\";\nimport * as Stagehand from \"@browserbasehq/stagehand\";\n\ndescribe(\"V3 Core public API types\", () => {\n  describe(\"Stagehand\", () => {\n    type ExpectedShape = {\n      init: () => Promise<void>;\n      close: (opts?: { force?: boolean }) => Promise<void>;\n      act: (\n        input: string | Stagehand.Action,\n        options?: Stagehand.ActOptions,\n      ) => Promise<Stagehand.ActResult>;\n      extract: (...args: unknown[]) => Promise<unknown>;\n      observe: (...args: unknown[]) => Promise<Stagehand.Action[]>;\n      agent: (config?: Stagehand.AgentConfig) => {\n        execute: (\n          instructionOrOptions: string | Stagehand.AgentExecuteOptions,\n        ) => Promise<Stagehand.AgentResult>;\n      };\n      connectURL: () => string;\n      context: unknown;\n      metrics: Promise<Stagehand.StagehandMetrics>;\n      history: Promise<ReadonlyArray<Stagehand.HistoryEntry>>;\n      llmClient: Stagehand.LLMClient;\n      browserbaseSessionID: string | undefined;\n      browserbaseSessionURL: string | undefined;\n      browserbaseDebugURL: string | undefined;\n      experimental: boolean;\n      logInferenceToFile: boolean;\n      verbose: 0 | 1 | 2;\n      logger: (logLine: Stagehand.LogLine) => void;\n      isAgentReplayActive: () => boolean;\n      recordAgentReplayStep: (step: unknown) => void;\n    };\n\n    type StagehandInstance = InstanceType<typeof Stagehand.Stagehand>;\n\n    it(\"has correct public interface shape\", () => {\n      expectTypeOf<StagehandInstance>().toExtend<ExpectedShape>();\n    });\n\n    it(\"act accepts Action as first parameter\", () => {\n      const mockAction = {} as Stagehand.Action;\n      expectTypeOf<StagehandInstance[\"act\"]>().toBeCallableWith(\n        mockAction,\n        {} as Stagehand.ActOptions,\n      );\n    });\n\n    it(\"extract accepts instruction and schema\", () => {\n      const mockSchema = {} as Stagehand.StagehandZodSchema;\n      expectTypeOf<StagehandInstance[\"extract\"]>().toBeCallableWith(\n        \"instruction\",\n        mockSchema,\n        {} as Stagehand.ExtractOptions,\n      );\n    });\n\n    it(\"observe accepts instruction and options\", () => {\n      expectTypeOf<StagehandInstance[\"observe\"]>().toBeCallableWith(\n        \"instruction\",\n        {} as Stagehand.ObserveOptions,\n      );\n    });\n\n    it(\"agent execute accepts page option\", () => {\n      type AgentReturn = ReturnType<StagehandInstance[\"agent\"]>;\n      const mockPage = {} as Stagehand.AnyPage;\n      expectTypeOf<AgentReturn[\"execute\"]>().toBeCallableWith({\n        instruction: \"test\",\n        page: mockPage,\n      } satisfies Stagehand.AgentExecuteOptions);\n    });\n  });\n\n  describe(\"StagehandMetrics\", () => {\n    type ExpectedStagehandMetrics = {\n      actPromptTokens: number;\n      actCompletionTokens: number;\n      actReasoningTokens: number;\n      actCachedInputTokens: number;\n      actInferenceTimeMs: number;\n      extractPromptTokens: number;\n      extractCompletionTokens: number;\n      extractReasoningTokens: number;\n      extractCachedInputTokens: number;\n      extractInferenceTimeMs: number;\n      observePromptTokens: number;\n      observeCompletionTokens: number;\n      observeReasoningTokens: number;\n      observeCachedInputTokens: number;\n      observeInferenceTimeMs: number;\n      agentPromptTokens: number;\n      agentCompletionTokens: number;\n      agentReasoningTokens: number;\n      agentCachedInputTokens: number;\n      agentInferenceTimeMs: number;\n      totalPromptTokens: number;\n      totalCompletionTokens: number;\n      totalReasoningTokens: number;\n      totalCachedInputTokens: number;\n      totalInferenceTimeMs: number;\n    };\n\n    it(\"matches the published metrics shape\", () => {\n      expectTypeOf<Stagehand.StagehandMetrics>().toEqualTypeOf<ExpectedStagehandMetrics>();\n    });\n  });\n\n  describe(\"V3\", () => {\n    // V3 is the same class as Stagehand, just re-exported with a different name.\n    // The public interface shape is already tested in the \"Stagehand\" test above.\n    it(\"is exported\", () => {\n      expect(Stagehand.V3).toBeDefined();\n    });\n  });\n\n  describe(\"V3Evaluator\", () => {\n    type V3EvaluatorInstance = InstanceType<typeof Stagehand.V3Evaluator>;\n\n    it(\"is exported\", () => {\n      expect(Stagehand.V3Evaluator).toBeDefined();\n    });\n\n    it(\"has ask method\", () => {\n      expectTypeOf<V3EvaluatorInstance[\"ask\"]>().toExtend<\n        (options: unknown) => Promise<unknown>\n      >();\n    });\n\n    it(\"has batchAsk method\", () => {\n      expectTypeOf<V3EvaluatorInstance[\"batchAsk\"]>().toExtend<\n        (options: unknown) => Promise<unknown[]>\n      >();\n    });\n  });\n\n  describe(\"V3FunctionName\", () => {\n    const expectedFunctionNames = [\n      \"ACT\",\n      \"EXTRACT\",\n      \"OBSERVE\",\n      \"AGENT\",\n    ] as const;\n\n    it(\"matches the known function name literals\", () => {\n      expectTypeOf<Stagehand.V3FunctionName>().toExtend<\n        (typeof expectedFunctionNames)[number]\n      >();\n      void expectedFunctionNames; // Mark as used to satisfy ESLint\n    });\n  });\n\n  describe(\"connectToMCPServer\", () => {\n    type ExpectedServerConfig =\n      | string\n      | URL\n      | { command: string; args?: string[]; env?: Record<string, string> }\n      | { serverUrl: string | URL; clientOptions?: unknown };\n\n    it(\"has correct parameter types\", () => {\n      expectTypeOf(\n        Stagehand.connectToMCPServer,\n      ).parameters.branded.toEqualTypeOf<[ExpectedServerConfig]>();\n    });\n  });\n\n  describe(\"LOG_LEVEL_NAMES\", () => {\n    type ExpectedLOG_LEVEL_NAMES = Record<Stagehand.LogLevel, string>;\n\n    it(\"maps numeric levels to strings\", () => {\n      expectTypeOf<\n        typeof Stagehand.LOG_LEVEL_NAMES\n      >().toExtend<ExpectedLOG_LEVEL_NAMES>();\n    });\n  });\n});\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;AAAA,oBAAmD;AACnD,gBAA2B;AAAA,IAE3B,wBAAS,4BAA4B,MAAM;AACzC,8BAAS,aAAa,MAAM;AAiC1B,0BAAG,sCAAsC,MAAM;AAC7C,sCAAgC,EAAE,SAAwB;AAAA,IAC5D,CAAC;AAED,0BAAG,yCAAyC,MAAM;AAChD,YAAM,aAAa,CAAC;AACpB,sCAAuC,EAAE;AAAA,QACvC;AAAA,QACA,CAAC;AAAA,MACH;AAAA,IACF,CAAC;AAED,0BAAG,0CAA0C,MAAM;AACjD,YAAM,aAAa,CAAC;AACpB,sCAA2C,EAAE;AAAA,QAC3C;AAAA,QACA;AAAA,QACA,CAAC;AAAA,MACH;AAAA,IACF,CAAC;AAED,0BAAG,2CAA2C,MAAM;AAClD,sCAA2C,EAAE;AAAA,QAC3C;AAAA,QACA,CAAC;AAAA,MACH;AAAA,IACF,CAAC;AAED,0BAAG,qCAAqC,MAAM;AAE5C,YAAM,WAAW,CAAC;AAClB,sCAAqC,EAAE,iBAAiB;AAAA,QACtD,aAAa;AAAA,QACb,MAAM;AAAA,MACR,CAAyC;AAAA,IAC3C,CAAC;AAAA,EACH,CAAC;AAED,8BAAS,oBAAoB,MAAM;AA6BjC,0BAAG,uCAAuC,MAAM;AAC9C,sCAAyC,EAAE,cAAwC;AAAA,IACrF,CAAC;AAAA,EACH,CAAC;AAED,8BAAS,MAAM,MAAM;AAGnB,0BAAG,eAAe,MAAM;AACtB,gCAAO,UAAU,EAAE,EAAE,YAAY;AAAA,IACnC,CAAC;AAAA,EACH,CAAC;AAED,8BAAS,eAAe,MAAM;AAG5B,0BAAG,eAAe,MAAM;AACtB,gCAAO,UAAU,WAAW,EAAE,YAAY;AAAA,IAC5C,CAAC;AAED,0BAAG,kBAAkB,MAAM;AACzB,sCAAyC,EAAE,SAEzC;AAAA,IACJ,CAAC;AAED,0BAAG,uBAAuB,MAAM;AAC9B,sCAA8C,EAAE,SAE9C;AAAA,IACJ,CAAC;AAAA,EACH,CAAC;AAED,8BAAS,kBAAkB,MAAM;AAC/B,UAAM,wBAAwB;AAAA,MAC5B;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAEA,0BAAG,4CAA4C,MAAM;AACnD,sCAAuC,EAAE,SAEvC;AAAA,IAEJ,CAAC;AAAA,EACH,CAAC;AAED,8BAAS,sBAAsB,MAAM;AAOnC,0BAAG,+BAA+B,MAAM;AACtC;AAAA,QACE,UAAU;AAAA,MACZ,EAAE,WAAW,QAAQ,cAAsC;AAAA,IAC7D,CAAC;AAAA,EACH,CAAC;AAED,8BAAS,mBAAmB,MAAM;AAGhC,0BAAG,kCAAkC,MAAM;AACzC,sCAEE,EAAE,SAAkC;AAAA,IACxC,CAAC;AAAA,EACH,CAAC;AACH,CAAC;",
+  "names": []
+}

package/dist/cjs/tests/safety-confirmation.test.js

@@ -0,0 +1,134 @@
+var import_vitest = require("vitest");
+var import_OpenAICUAClient = require("../lib/v3/agent/OpenAICUAClient.js");
+var import_GoogleCUAClient = require("../lib/v3/agent/GoogleCUAClient.js");
+const openAISafetyInvoker = import_OpenAICUAClient.OpenAICUAClient.prototype.handleSafetyConfirmation;
+const googleSafetyInvoker = import_GoogleCUAClient.GoogleCUAClient.prototype.handleSafetyConfirmation;
+function createOpenAIClient() {
+  return new import_OpenAICUAClient.OpenAICUAClient(
+    "openai",
+    "openai/computer-use-preview",
+    "test instructions",
+    { apiKey: "test" }
+  );
+}
+function createGoogleClient() {
+  return new import_GoogleCUAClient.GoogleCUAClient(
+    "google",
+    "google/gemini-2.5-computer-use-preview-10-2025",
+    "test instructions",
+    { apiKey: "test" }
+  );
+}
+(0, import_vitest.describe)("Safety Confirmation Handler", () => {
+  (0, import_vitest.describe)("OpenAI-style (pending_safety_checks)", () => {
+    const mockChecks = [
+      {
+        id: "check-1",
+        code: "malicious_instructions",
+        message: "Potentially harmful action detected"
+      }
+    ];
+    (0, import_vitest.it)("returns checks when handler acknowledges", async () => {
+      const client = createOpenAIClient();
+      const handler = import_vitest.vi.fn(async () => ({
+        acknowledged: true
+      }));
+      client.setSafetyConfirmationHandler(handler);
+      const logger = import_vitest.vi.fn();
+      const result = await openAISafetyInvoker.call(client, mockChecks, logger);
+      (0, import_vitest.expect)(handler).toHaveBeenCalledWith(mockChecks);
+      (0, import_vitest.expect)(result).toEqual(mockChecks);
+    });
+    (0, import_vitest.it)("returns undefined when handler rejects", async () => {
+      const client = createOpenAIClient();
+      const handler = import_vitest.vi.fn(async () => ({
+        acknowledged: false
+      }));
+      client.setSafetyConfirmationHandler(handler);
+      const logger = import_vitest.vi.fn();
+      const result = await openAISafetyInvoker.call(client, mockChecks, logger);
+      (0, import_vitest.expect)(handler).toHaveBeenCalledWith(mockChecks);
+      (0, import_vitest.expect)(result).toBeUndefined();
+    });
+    (0, import_vitest.it)("auto-acknowledges when no handler is set", async () => {
+      const client = createOpenAIClient();
+      const logger = import_vitest.vi.fn();
+      const result = await openAISafetyInvoker.call(client, mockChecks, logger);
+      (0, import_vitest.expect)(result).toEqual(mockChecks);
+    });
+  });
+  (0, import_vitest.describe)("Google-style (safety_decision)", () => {
+    const mockDecision = {
+      decision: "require_confirmation",
+      explanation: "Cookie consent dialog detected"
+    };
+    (0, import_vitest.it)("returns 'true' when handler acknowledges", async () => {
+      const client = createGoogleClient();
+      const handler = import_vitest.vi.fn(async () => ({
+        acknowledged: true
+      }));
+      client.setSafetyConfirmationHandler(handler);
+      const logger = import_vitest.vi.fn();
+      const result = await googleSafetyInvoker.call(
+        client,
+        mockDecision,
+        logger
+      );
+      (0, import_vitest.expect)(handler).toHaveBeenCalledWith([
+        {
+          id: "google-safety-decision",
+          code: "safety_decision",
+          message: JSON.stringify(mockDecision, null, 2)
+        }
+      ]);
+      (0, import_vitest.expect)(result).toBe("true");
+    });
+    (0, import_vitest.it)("returns undefined when handler rejects", async () => {
+      const client = createGoogleClient();
+      const handler = import_vitest.vi.fn(async () => ({
+        acknowledged: false
+      }));
+      client.setSafetyConfirmationHandler(handler);
+      const logger = import_vitest.vi.fn();
+      const result = await googleSafetyInvoker.call(
+        client,
+        mockDecision,
+        logger
+      );
+      (0, import_vitest.expect)(handler).toHaveBeenCalled();
+      (0, import_vitest.expect)(result).toBeUndefined();
+    });
+    (0, import_vitest.it)("auto-acknowledges when no handler is set", async () => {
+      const client = createGoogleClient();
+      const logger = import_vitest.vi.fn();
+      const result = await googleSafetyInvoker.call(
+        client,
+        mockDecision,
+        logger
+      );
+      (0, import_vitest.expect)(result).toBe("true");
+    });
+    (0, import_vitest.it)("handles string safety decisions", async () => {
+      const client = createGoogleClient();
+      const handler = import_vitest.vi.fn(async () => ({
+        acknowledged: true
+      }));
+      client.setSafetyConfirmationHandler(handler);
+      const logger = import_vitest.vi.fn();
+      const result = await googleSafetyInvoker.call(
+        client,
+        "Simple string decision",
+        logger
+      );
+      (0, import_vitest.expect)(handler).toHaveBeenCalledWith([
+        {
+          id: "google-safety-decision",
+          code: "safety_decision",
+          message: "Simple string decision"
+        }
+      ]);
+      (0, import_vitest.expect)(result).toBe("true");
+    });
+  });
+});
+//# sourceMappingURL=safety-confirmation.test.js.map

package/dist/cjs/tests/safety-confirmation.test.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../tests/safety-confirmation.test.ts"],
+  "sourcesContent": ["import { describe, it, expect, vi } from \"vitest\";\nimport { OpenAICUAClient } from \"../lib/v3/agent/OpenAICUAClient.js\";\nimport { GoogleCUAClient } from \"../lib/v3/agent/GoogleCUAClient.js\";\nimport type {\n  SafetyCheck,\n  SafetyConfirmationHandler,\n} from \"../lib/v3/types/public/agent.js\";\nimport type { LogLine } from \"../lib/v3/types/public/logs.js\";\n\ntype LoggerMock = (message: LogLine) => void;\n\nconst openAISafetyInvoker = (\n  OpenAICUAClient.prototype as unknown as {\n    handleSafetyConfirmation: (\n      this: OpenAICUAClient,\n      pendingSafetyChecks: SafetyCheck[],\n      logger: LoggerMock,\n    ) => Promise<SafetyCheck[] | undefined>;\n  }\n).handleSafetyConfirmation;\n\nconst googleSafetyInvoker = (\n  GoogleCUAClient.prototype as unknown as {\n    handleSafetyConfirmation: (\n      this: GoogleCUAClient,\n      safetyDecision: unknown,\n      logger: LoggerMock,\n    ) => Promise<string | undefined>;\n  }\n).handleSafetyConfirmation;\n\nfunction createOpenAIClient(): OpenAICUAClient {\n  return new OpenAICUAClient(\n    \"openai\",\n    \"openai/computer-use-preview\",\n    \"test instructions\",\n    { apiKey: \"test\" },\n  );\n}\n\nfunction createGoogleClient(): GoogleCUAClient {\n  return new GoogleCUAClient(\n    \"google\",\n    \"google/gemini-2.5-computer-use-preview-10-2025\",\n    \"test instructions\",\n    { apiKey: \"test\" },\n  );\n}\n\ndescribe(\"Safety Confirmation Handler\", () => {\n  describe(\"OpenAI-style (pending_safety_checks)\", () => {\n    const mockChecks: SafetyCheck[] = [\n      {\n        id: \"check-1\",\n        code: \"malicious_instructions\",\n        message: \"Potentially harmful action detected\",\n      },\n    ];\n\n    it(\"returns checks when handler acknowledges\", async () => {\n      const client = createOpenAIClient();\n      const handler: SafetyConfirmationHandler = vi.fn(async () => ({\n        acknowledged: true,\n      }));\n      client.setSafetyConfirmationHandler(handler);\n      const logger = vi.fn<LoggerMock>();\n      const result = await openAISafetyInvoker.call(client, mockChecks, logger);\n\n      expect(handler).toHaveBeenCalledWith(mockChecks);\n      expect(result).toEqual(mockChecks);\n    });\n\n    it(\"returns undefined when handler rejects\", async () => {\n      const client = createOpenAIClient();\n      const handler: SafetyConfirmationHandler = vi.fn(async () => ({\n        acknowledged: false,\n      }));\n      client.setSafetyConfirmationHandler(handler);\n      const logger = vi.fn<LoggerMock>();\n      const result = await openAISafetyInvoker.call(client, mockChecks, logger);\n\n      expect(handler).toHaveBeenCalledWith(mockChecks);\n      expect(result).toBeUndefined();\n    });\n\n    it(\"auto-acknowledges when no handler is set\", async () => {\n      const client = createOpenAIClient();\n      const logger = vi.fn<LoggerMock>();\n      const result = await openAISafetyInvoker.call(client, mockChecks, logger);\n      expect(result).toEqual(mockChecks);\n    });\n  });\n\n  describe(\"Google-style (safety_decision)\", () => {\n    const mockDecision = {\n      decision: \"require_confirmation\",\n      explanation: \"Cookie consent dialog detected\",\n    };\n\n    it(\"returns 'true' when handler acknowledges\", async () => {\n      const client = createGoogleClient();\n      const handler: SafetyConfirmationHandler = vi.fn(async () => ({\n        acknowledged: true,\n      }));\n      client.setSafetyConfirmationHandler(handler);\n      const logger = vi.fn<LoggerMock>();\n      const result = await googleSafetyInvoker.call(\n        client,\n        mockDecision,\n        logger,\n      );\n\n      expect(handler).toHaveBeenCalledWith([\n        {\n          id: \"google-safety-decision\",\n          code: \"safety_decision\",\n          message: JSON.stringify(mockDecision, null, 2),\n        },\n      ]);\n      expect(result).toBe(\"true\");\n    });\n\n    it(\"returns undefined when handler rejects\", async () => {\n      const client = createGoogleClient();\n      const handler: SafetyConfirmationHandler = vi.fn(async () => ({\n        acknowledged: false,\n      }));\n      client.setSafetyConfirmationHandler(handler);\n      const logger = vi.fn<LoggerMock>();\n      const result = await googleSafetyInvoker.call(\n        client,\n        mockDecision,\n        logger,\n      );\n\n      expect(handler).toHaveBeenCalled();\n      expect(result).toBeUndefined();\n    });\n\n    it(\"auto-acknowledges when no handler is set\", async () => {\n      const client = createGoogleClient();\n      const logger = vi.fn<LoggerMock>();\n      const result = await googleSafetyInvoker.call(\n        client,\n        mockDecision,\n        logger,\n      );\n      expect(result).toBe(\"true\");\n    });\n\n    it(\"handles string safety decisions\", async () => {\n      const client = createGoogleClient();\n      const handler: SafetyConfirmationHandler = vi.fn(async () => ({\n        acknowledged: true,\n      }));\n      client.setSafetyConfirmationHandler(handler);\n      const logger = vi.fn<LoggerMock>();\n      const result = await googleSafetyInvoker.call(\n        client,\n        \"Simple string decision\",\n        logger,\n      );\n\n      expect(handler).toHaveBeenCalledWith([\n        {\n          id: \"google-safety-decision\",\n          code: \"safety_decision\",\n          message: \"Simple string decision\",\n        },\n      ]);\n      expect(result).toBe(\"true\");\n    });\n  });\n});\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/cjs/tests/snapshot-a11y-resolvers.test.js

@@ -0,0 +1,370 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var import_vitest = require("vitest");
+var import_a11yTree = require("../lib/v3/understudy/a11y/snapshot/a11yTree.js");
+var focusSelectors = __toESM(require("../lib/v3/understudy/a11y/snapshot/focusSelectors.js"), 1);
+var import_mockCDPSession = require("./helpers/mockCDPSession.js");
+var import_executionContextRegistry = require("../lib/v3/understudy/executionContextRegistry.js");
+var import_capture = require("../lib/v3/understudy/a11y/snapshot/capture.js");
+var domTree = __toESM(require("../lib/v3/understudy/a11y/snapshot/domTree.js"), 1);
+var a11yTree = __toESM(require("../lib/v3/understudy/a11y/snapshot/a11yTree.js"), 1);
+var logger = __toESM(require("../lib/v3/logger.js"), 1);
+const stringType = "string";
+const baseAxNodes = () => [
+  {
+    nodeId: "1",
+    role: { type: stringType, value: "RootWebArea" },
+    backendDOMNodeId: 100,
+    childIds: ["2"],
+    ignored: false
+  },
+  {
+    nodeId: "2",
+    role: { type: stringType, value: "link" },
+    name: { type: stringType, value: "Docs" },
+    backendDOMNodeId: 101,
+    parentId: "1",
+    childIds: [],
+    properties: [
+      {
+        name: "url",
+        value: { type: stringType, value: "https://example.com" }
+      }
+    ],
+    ignored: false
+  }
+];
+const baseHandlers = {
+  "Accessibility.enable": async () => ({}),
+  "Runtime.enable": async () => ({}),
+  "DOM.enable": async () => ({})
+};
+(0, import_vitest.describe)("a11yForFrame", () => {
+  (0, import_vitest.beforeEach)(() => {
+    import_vitest.vi.restoreAllMocks();
+  });
+  (0, import_vitest.it)("returns full outline and url map when no focus selector is provided", async () => {
+    const session = new import_mockCDPSession.MockCDPSession({
+      ...baseHandlers,
+      "Accessibility.getFullAXTree": async () => ({ nodes: baseAxNodes() })
+    });
+    const opts = {
+      focusSelector: void 0,
+      experimental: false,
+      tagNameMap: { "enc-100": "#document", "enc-101": "a" },
+      scrollableMap: {},
+      encode: (backend) => `enc-${backend}`
+    };
+    const result = await (0, import_a11yTree.a11yForFrame)(session, void 0, opts);
+    (0, import_vitest.expect)(result.scopeApplied).toBe(false);
+    (0, import_vitest.expect)(result.urlMap["enc-101"]).toBe("https://example.com");
+    (0, import_vitest.expect)(result.outline).toContain("Docs");
+  });
+  (0, import_vitest.it)("scopes the tree to the resolved focus selector target", async () => {
+    const nodes = baseAxNodes().map(
+      (n) => n.nodeId === "2" ? {
+        ...n,
+        childIds: ["3"]
+      } : n
+    );
+    nodes.push({
+      nodeId: "3",
+      parentId: "2",
+      childIds: [],
+      role: { type: stringType, value: "StaticText" },
+      backendDOMNodeId: 102,
+      ignored: false
+    });
+    let scopedOnce = false;
+    const session = new import_mockCDPSession.MockCDPSession({
+      ...baseHandlers,
+      "Accessibility.getFullAXTree": async (params) => {
+        if (params?.frameId && !scopedOnce) {
+          scopedOnce = true;
+          throw new Error("does not belong to the target");
+        }
+        return { nodes };
+      },
+      "DOM.describeNode": async () => ({
+        node: { backendNodeId: 101 }
+      })
+    });
+    const resolveSpy = import_vitest.vi.spyOn(focusSelectors, "resolveObjectIdForXPath").mockResolvedValue("object-1");
+    const opts = {
+      focusSelector: "xpath=//a",
+      experimental: false,
+      tagNameMap: { "enc-101": "a" },
+      scrollableMap: {},
+      encode: (backend) => `enc-${backend}`
+    };
+    const result = await (0, import_a11yTree.a11yForFrame)(session, "frame-1", opts);
+    (0, import_vitest.expect)(result.scopeApplied).toBe(true);
+    (0, import_vitest.expect)(result.outline).not.toContain("RootWebArea");
+    (0, import_vitest.expect)(resolveSpy).toHaveBeenCalled();
+    resolveSpy.mockRestore();
+  });
+  (0, import_vitest.it)("falls back to full tree when resolveObjectId throws", async () => {
+    const session = new import_mockCDPSession.MockCDPSession({
+      ...baseHandlers,
+      "Accessibility.getFullAXTree": async () => ({ nodes: baseAxNodes() })
+    });
+    import_vitest.vi.spyOn(focusSelectors, "resolveObjectIdForCss").mockRejectedValue(
+      new Error("fail")
+    );
+    const opts = {
+      focusSelector: ".btn",
+      experimental: false,
+      tagNameMap: {},
+      scrollableMap: {},
+      encode: (backend) => `enc-${backend}`
+    };
+    const result = await (0, import_a11yTree.a11yForFrame)(session, "frame-1", opts);
+    (0, import_vitest.expect)(result.scopeApplied).toBe(false);
+  });
+});
+(0, import_vitest.describe)("resolveObjectIdForXPath", () => {
+  (0, import_vitest.beforeEach)(() => {
+    import_vitest.vi.restoreAllMocks();
+  });
+  (0, import_vitest.it)("evaluates in the target frame's main world when available", async () => {
+    import_vitest.vi.spyOn(import_executionContextRegistry.executionContexts, "waitForMainWorld").mockResolvedValue(42);
+    import_vitest.vi.spyOn(import_executionContextRegistry.executionContexts, "getMainWorld").mockReturnValue(void 0);
+    const session = new import_mockCDPSession.MockCDPSession({
+      "Runtime.evaluate": async (params) => {
+        (0, import_vitest.expect)(params?.contextId).toBe(42);
+        return { result: { objectId: "node-obj" } };
+      }
+    });
+    const objectId = await focusSelectors.resolveObjectIdForXPath(
+      session,
+      "//div",
+      "frame-1"
+    );
+    (0, import_vitest.expect)(objectId).toBe("node-obj");
+  });
+  (0, import_vitest.it)("returns null when evaluation throws or reports exception details", async () => {
+    import_vitest.vi.spyOn(import_executionContextRegistry.executionContexts, "waitForMainWorld").mockRejectedValue(
+      new Error("missing")
+    );
+    import_vitest.vi.spyOn(import_executionContextRegistry.executionContexts, "getMainWorld").mockReturnValue(void 0);
+    const session = new import_mockCDPSession.MockCDPSession({
+      "Runtime.evaluate": async () => ({
+        result: {},
+        exceptionDetails: { exception: { description: "bad" } }
+      })
+    });
+    const objectId = await focusSelectors.resolveObjectIdForXPath(
+      session,
+      "//div",
+      "frame-2"
+    );
+    (0, import_vitest.expect)(objectId).toBeNull();
+  });
+});
+(0, import_vitest.describe)("resolveObjectIdForCss", () => {
+  (0, import_vitest.beforeEach)(() => {
+    import_vitest.vi.restoreAllMocks();
+  });
+  (0, import_vitest.it)("returns primary evaluation result when available", async () => {
+    import_vitest.vi.spyOn(import_executionContextRegistry.executionContexts, "waitForMainWorld").mockResolvedValue(7);
+    const session = new import_mockCDPSession.MockCDPSession({
+      "Runtime.evaluate": async () => ({
+        result: { objectId: "primary-obj" }
+      })
+    });
+    const objectId = await focusSelectors.resolveObjectIdForCss(
+      session,
+      ".btn",
+      "frame-1"
+    );
+    (0, import_vitest.expect)(objectId).toBe("primary-obj");
+  });
+  (0, import_vitest.it)("falls back to the pierce selector when the primary lookup fails", async () => {
+    let call = 0;
+    const session = new import_mockCDPSession.MockCDPSession({
+      "Runtime.evaluate": async (params) => {
+        call++;
+        if (call === 1) {
+          (0, import_vitest.expect)(String(params?.expression)).toContain("resolveCssSelector");
+          return { result: {} };
+        }
+        (0, import_vitest.expect)(String(params?.expression)).toContain(
+          "resolveCssSelectorPierce"
+        );
+        return { result: { objectId: "css-obj" } };
+      }
+    });
+    const objectId = await focusSelectors.resolveObjectIdForCss(
+      session,
+      ".btn",
+      void 0
+    );
+    (0, import_vitest.expect)(objectId).toBe("css-obj");
+  });
+  (0, import_vitest.it)("returns null when both primary and fallback evaluations throw", async () => {
+    import_vitest.vi.spyOn(import_executionContextRegistry.executionContexts, "waitForMainWorld").mockResolvedValue(11);
+    import_vitest.vi.spyOn(import_executionContextRegistry.executionContexts, "getMainWorld").mockReturnValue(void 0);
+    const session = new import_mockCDPSession.MockCDPSession({
+      "Runtime.evaluate": async () => ({
+        result: {},
+        exceptionDetails: { exception: { description: "fail" } }
+      })
+    });
+    const objectId = await focusSelectors.resolveObjectIdForCss(
+      session,
+      ".missing",
+      "frame-1"
+    );
+    (0, import_vitest.expect)(objectId).toBeNull();
+  });
+});
+(0, import_vitest.describe)("tryScopedSnapshot", () => {
+  const ordinal = (frameId) => frameId === "frame-1" ? 0 : 1;
+  const context = {
+    rootId: "frame-1",
+    frames: ["frame-1", "frame-2"],
+    parentByFrame: /* @__PURE__ */ new Map([
+      ["frame-1", null],
+      ["frame-2", "frame-1"]
+    ])
+  };
+  const makePage = (session, overrides) => ({
+    mainFrameId: () => "frame-1",
+    asProtocolFrameTree: () => ({
+      frame: { id: "frame-1" },
+      childFrames: [{ frame: { id: "frame-2" } }]
+    }),
+    listAllFrameIds: () => ["frame-1", "frame-2"],
+    getSessionForFrame: () => session,
+    getOrdinal: (fid) => ordinal(fid),
+    ...overrides
+  });
+  (0, import_vitest.beforeEach)(() => {
+    import_vitest.vi.restoreAllMocks();
+  });
+  (0, import_vitest.it)("returns scoped snapshot when focus selector resolves via CSS hops", async () => {
+    const session = new import_mockCDPSession.MockCDPSession({});
+    const domMapsSpy = import_vitest.vi.spyOn(domTree, "domMapsForSession").mockResolvedValue({
+      tagNameMap: { "1-10": "div" },
+      xpathMap: { "1-10": "/div[1]" },
+      scrollableMap: {}
+    });
+    const a11ySpy = import_vitest.vi.spyOn(a11yTree, "a11yForFrame").mockResolvedValue({
+      outline: "[1-10] div",
+      urlMap: { "1-10": "https://example.com" },
+      scopeApplied: true
+    });
+    import_vitest.vi.spyOn(focusSelectors, "resolveCssFocusFrameAndTail").mockResolvedValue({
+      targetFrameId: "frame-2",
+      tailSelector: ".btn-inner",
+      absPrefix: "/html/body/iframe[1]"
+    });
+    const result = await (0, import_capture.tryScopedSnapshot)(
+      makePage(session),
+      { focusSelector: ".btn" },
+      context,
+      true
+    );
+    (0, import_vitest.expect)(result).not.toBeNull();
+    (0, import_vitest.expect)(result?.combinedXpathMap["1-10"]).toBe(
+      "/html/body/iframe[1]/div[1]"
+    );
+    (0, import_vitest.expect)(domMapsSpy).toHaveBeenCalled();
+    (0, import_vitest.expect)(a11ySpy).toHaveBeenCalled();
+  });
+  (0, import_vitest.it)("returns null and logs fallback when scope is not applied", async () => {
+    const session = new import_mockCDPSession.MockCDPSession({});
+    import_vitest.vi.spyOn(domTree, "domMapsForSession").mockResolvedValue({
+      tagNameMap: { "1-10": "div" },
+      xpathMap: { "1-10": "/div[1]" },
+      scrollableMap: {}
+    });
+    import_vitest.vi.spyOn(a11yTree, "a11yForFrame").mockResolvedValue({
+      outline: "ignored",
+      urlMap: {},
+      scopeApplied: false
+    });
+    const loggerSpy = import_vitest.vi.spyOn(logger, "v3Logger").mockImplementation(() => {
+    });
+    const result = await (0, import_capture.tryScopedSnapshot)(
+      makePage(session),
+      { focusSelector: ".btn" },
+      context,
+      false
+    );
+    (0, import_vitest.expect)(result).toBeNull();
+    (0, import_vitest.expect)(loggerSpy).toHaveBeenCalled();
+  });
+  (0, import_vitest.it)("returns null immediately when no focus selector is provided", async () => {
+    const result = await (0, import_capture.tryScopedSnapshot)(
+      makePage(new import_mockCDPSession.MockCDPSession({})),
+      {},
+      context,
+      true
+    );
+    (0, import_vitest.expect)(result).toBeNull();
+  });
+  (0, import_vitest.it)("supports XPath focus resolution branch", async () => {
+    const session = new import_mockCDPSession.MockCDPSession({});
+    import_vitest.vi.spyOn(domTree, "domMapsForSession").mockResolvedValue({
+      tagNameMap: { "1-10": "div" },
+      xpathMap: { "1-10": "/div[1]" },
+      scrollableMap: {}
+    });
+    import_vitest.vi.spyOn(a11yTree, "a11yForFrame").mockResolvedValue({
+      outline: "[1-10] div",
+      urlMap: {},
+      scopeApplied: true
+    });
+    import_vitest.vi.spyOn(focusSelectors, "resolveFocusFrameAndTail").mockResolvedValue({
+      targetFrameId: "frame-1",
+      tailXPath: "//div[1]",
+      absPrefix: ""
+    });
+    const result = await (0, import_capture.tryScopedSnapshot)(
+      makePage(session),
+      { focusSelector: "xpath=//div" },
+      context,
+      true
+    );
+    (0, import_vitest.expect)(result).not.toBeNull();
+    (0, import_vitest.expect)(result?.combinedXpathMap["1-10"]).toBe("/div[1]");
+  });
+  (0, import_vitest.it)("logs and returns null when resolver throws", async () => {
+    const session = new import_mockCDPSession.MockCDPSession({});
+    import_vitest.vi.spyOn(focusSelectors, "resolveCssFocusFrameAndTail").mockRejectedValue(
+      new Error("bad selector")
+    );
+    const loggerSpy = import_vitest.vi.spyOn(logger, "v3Logger").mockImplementation(() => {
+    });
+    const result = await (0, import_capture.tryScopedSnapshot)(
+      makePage(session),
+      { focusSelector: ".bad" },
+      context,
+      true
+    );
+    (0, import_vitest.expect)(result).toBeNull();
+    (0, import_vitest.expect)(loggerSpy).toHaveBeenCalled();
+  });
+});
+//# sourceMappingURL=snapshot-a11y-resolvers.test.js.map