@flrande/browserctl 0.1.0-dev.7.1

package/packages/driver-managed/src/managed-local-driver.ts

@@ -0,0 +1,2021 @@
+import type {
+  BrowserDriver,
+  BrowserDriverScreenshot,
+  DriverObject
+} from "../../core/src/driver";
+import type { ProfileId, TargetId } from "../../core/src/types";
+
+export type ManagedLocalBrowserName = "chromium" | "firefox" | "webkit";
+
+export type ManagedLocalBrowserLaunchConfig = {
+  browserName: ManagedLocalBrowserName;
+  headless: boolean;
+  channel?: string;
+  executablePath?: string;
+  launchTimeoutMs?: number;
+  args: string[];
+};
+
+export type ManagedLocalDriverConfig = {
+  runtime?: ManagedLocalDriverRuntime;
+  browserName?: ManagedLocalBrowserName;
+  headless?: boolean;
+  channel?: string;
+  executablePath?: string;
+  launchTimeoutMs?: number;
+  args?: string[];
+};
+
+export type ManagedLocalDriverStatus = {
+  kind: "managed-local";
+  connected: boolean;
+  launched: boolean;
+  browserName: ManagedLocalBrowserName;
+  headless: boolean;
+  channel?: string;
+  executablePath?: string;
+  launchTimeoutMs?: number;
+};
+
+export type ManagedLocalConsoleEntryLocation = {
+  url?: string;
+  lineNumber?: number;
+  columnNumber?: number;
+};
+
+export type ManagedLocalConsoleEntry = {
+  type: string;
+  text: string;
+  timestamp: string;
+  location?: ManagedLocalConsoleEntryLocation;
+};
+
+export type ManagedLocalNetworkRequestSummary = {
+  requestId: string;
+  url: string;
+  method?: string;
+  resourceType?: string;
+  status?: number;
+  timestamp: string;
+};
+
+export type ManagedLocalNetworkResponseBody = {
+  body: string;
+  encoding: "utf8" | "base64";
+};
+
+export type ManagedLocalSnapshot = {
+  kind: "managed-local";
+  profile: ProfileId;
+  targetId: TargetId;
+  hasTarget: boolean;
+  url?: string;
+  title?: string;
+  html?: string;
+  requestSummaries?: ManagedLocalNetworkRequestSummary[];
+};
+
+export type ManagedLocalScreenshot = {
+  kind: "managed-local";
+  profile: ProfileId;
+  targetId: TargetId;
+  hasTarget: boolean;
+  mimeType?: string;
+  encoding?: "base64";
+  imageBase64?: string;
+  width?: number;
+  height?: number;
+};
+
+export type ManagedLocalTelemetryDriverExtensions = {
+  getConsoleEntries?(targetId: TargetId, profile?: ProfileId): ManagedLocalConsoleEntry[];
+  getNetworkResponseBody?(
+    requestId: string,
+    targetId: TargetId,
+    profile?: ProfileId
+  ): ManagedLocalNetworkResponseBody | undefined;
+};
+
+export type ManagedLocalLocator = {
+  click(): Promise<void>;
+  fill(value: string): Promise<void>;
+  type(value: string): Promise<void>;
+};
+
+export type ManagedLocalKeyboard = {
+  press(key: string): Promise<void>;
+};
+
+export type ManagedLocalPage = {
+  goto(url: string): Promise<void>;
+  bringToFront(): Promise<void>;
+  close(): Promise<void>;
+  url(): string;
+  title(): Promise<string>;
+  content(): Promise<string>;
+  screenshot?(options?: Record<string, unknown>): Promise<unknown>;
+  locator(selector: string): ManagedLocalLocator;
+  keyboard?: ManagedLocalKeyboard;
+  on?(eventName: string, listener: (payload: unknown) => unknown): void;
+};
+
+export type ManagedLocalBrowserContext = {
+  newPage(): Promise<ManagedLocalPage>;
+  close(): Promise<void>;
+};
+
+export type ManagedLocalBrowser = {
+  newContext(): Promise<ManagedLocalBrowserContext>;
+  close(): Promise<void>;
+};
+
+export type ManagedLocalDriverRuntime = {
+  launch(config: ManagedLocalBrowserLaunchConfig): Promise<ManagedLocalBrowser>;
+};
+
+const DEFAULT_PROFILE_ID: ProfileId = "profile:managed-local:default";
+const DEFAULT_BROWSER_NAME: ManagedLocalBrowserName = "chromium";
+const DEFAULT_HEADLESS = true;
+
+type ManagedLocalTab = {
+  url: string;
+  page: ManagedLocalPage;
+};
+
+type ManagedLocalProfileState = {
+  nextTargetNumber: number;
+  tabs: Map<TargetId, ManagedLocalTab>;
+  tabOrder: TargetId[];
+  focusedTargetId?: TargetId;
+  context?: ManagedLocalBrowserContext;
+};
+
+type ManagedLocalTargetOperationState = {
+  uploadFiles: string[];
+  dialogArmedCount: number;
+  triggerCount: number;
+  downloadInFlight?: Promise<ManagedLocalDownloadArtifact>;
+  latestDownload?: ManagedLocalDownloadArtifact;
+};
+
+type ManagedLocalDownloadArtifact = {
+  path: string;
+  suggestedFilename?: string;
+  url?: string;
+  mimeType?: string;
+};
+
+type ManagedLocalTargetTelemetryState = {
+  consoleEntries: ManagedLocalConsoleEntry[];
+  requestSummaries: ManagedLocalNetworkRequestSummary[];
+  networkResponseBodies: Map<string, ManagedLocalNetworkResponseBody>;
+  nextRequestNumber: number;
+};
+
+function resolveProfileId(profile?: ProfileId): ProfileId {
+  return profile ?? DEFAULT_PROFILE_ID;
+}
+
+function createTargetId(profileId: ProfileId, targetNumber: number): TargetId {
+  return `target:managed-local:${profileId}:${targetNumber}`;
+}
+
+function createProfileState(): ManagedLocalProfileState {
+  return {
+    nextTargetNumber: 1,
+    tabs: new Map<TargetId, ManagedLocalTab>(),
+    tabOrder: []
+  };
+}
+
+function createTargetOperationState(): ManagedLocalTargetOperationState {
+  return {
+    uploadFiles: [],
+    dialogArmedCount: 0,
+    triggerCount: 0
+  };
+}
+
+function createTargetTelemetryState(): ManagedLocalTargetTelemetryState {
+  return {
+    consoleEntries: [],
+    requestSummaries: [],
+    networkResponseBodies: new Map<string, ManagedLocalNetworkResponseBody>(),
+    nextRequestNumber: 1
+  };
+}
+
+function createDownloadPath(profileId: ProfileId, targetId: TargetId, triggerCount: number): string {
+  return `managed-local-${encodeURIComponent(profileId)}-${encodeURIComponent(targetId)}-${triggerCount}.bin`;
+}
+
+function createRequestId(profileId: ProfileId, targetId: TargetId, requestNumber: number): string {
+  return `request:managed-local:${encodeURIComponent(profileId)}:${encodeURIComponent(targetId)}:${requestNumber}`;
+}
+
+function toErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : "Unexpected managed-local driver failure.";
+}
+
+function readActionPayloadString(payload: DriverObject | undefined, key: string): string | undefined {
+  const value = payload?.[key];
+  return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+
+function readActionPayloadNumber(payload: DriverObject | undefined, key: string): number | undefined {
+  const value = payload?.[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readObjectMethod<TValue>(value: unknown, methodName: string): TValue | undefined {
+  if (typeof value !== "object" || value === null) {
+    return undefined;
+  }
+
+  const method = (value as Record<string, unknown>)[methodName];
+  if (typeof method !== "function") {
+    return undefined;
+  }
+
+  try {
+    return (method as () => TValue).call(value);
+  } catch {
+    return undefined;
+  }
+}
+
+function getObjectMethod(
+  value: unknown,
+  methodName: string
+): ((...args: unknown[]) => unknown) | undefined {
+  if (typeof value !== "object" || value === null) {
+    return undefined;
+  }
+
+  const method = (value as Record<string, unknown>)[methodName];
+  return typeof method === "function" ? (method as (...args: unknown[]) => unknown) : undefined;
+}
+
+function readObjectStringProperty(value: unknown, key: string): string | undefined {
+  if (typeof value !== "object" || value === null) {
+    return undefined;
+  }
+
+  const property = (value as Record<string, unknown>)[key];
+  return typeof property === "string" ? property : undefined;
+}
+
+function readObjectNumberProperty(value: unknown, key: string): number | undefined {
+  if (typeof value !== "object" || value === null) {
+    return undefined;
+  }
+
+  const property = (value as Record<string, unknown>)[key];
+  return typeof property === "number" ? property : undefined;
+}
+
+function readConsoleEntry(value: unknown): ManagedLocalConsoleEntry {
+  const locationValue = readObjectMethod<unknown>(value, "location");
+  const locationUrl = readObjectStringProperty(locationValue, "url");
+  const locationLineNumber = readObjectNumberProperty(locationValue, "lineNumber");
+  const locationColumnNumber = readObjectNumberProperty(locationValue, "columnNumber");
+
+  const hasLocation =
+    locationUrl !== undefined || locationLineNumber !== undefined || locationColumnNumber !== undefined;
+
+  return {
+    type: readObjectMethod<string>(value, "type") ?? "log",
+    text: readObjectMethod<string>(value, "text") ?? "",
+    timestamp: new Date().toISOString(),
+    ...(hasLocation
+      ? {
+          location: {
+            ...(locationUrl !== undefined ? { url: locationUrl } : {}),
+            ...(locationLineNumber !== undefined ? { lineNumber: locationLineNumber } : {}),
+            ...(locationColumnNumber !== undefined ? { columnNumber: locationColumnNumber } : {})
+          }
+        }
+      : {})
+  };
+}
+
+function readNetworkSummary(
+  value: unknown,
+  requestId: string
+): ManagedLocalNetworkRequestSummary {
+  const requestValue = readObjectMethod<unknown>(value, "request");
+  const method = readObjectMethod<string>(requestValue, "method");
+  const resourceType = readObjectMethod<string>(requestValue, "resourceType");
+  const status = readObjectMethod<number>(value, "status");
+
+  return {
+    requestId,
+    url: readObjectMethod<string>(value, "url") ?? "",
+    ...(typeof method === "string" ? { method } : {}),
+    ...(typeof resourceType === "string" ? { resourceType } : {}),
+    ...(typeof status === "number" ? { status } : {}),
+    timestamp: new Date().toISOString()
+  };
+}
+
+function toBase64(value: ArrayBuffer | Uint8Array): string {
+  const bytes = value instanceof Uint8Array ? value : new Uint8Array(value);
+  return Buffer.from(bytes).toString("base64");
+}
+
+function parseScreenshotBase64(
+  value: string
+): { mimeType: string; imageBase64: string } | undefined {
+  const trimmedValue = value.trim();
+  if (trimmedValue.length === 0) {
+    return undefined;
+  }
+
+  const dataUrlMatch = /^data:([^;,]+);base64,(.+)$/i.exec(trimmedValue);
+  if (dataUrlMatch !== null) {
+    const mimeType = dataUrlMatch[1] ?? "image/png";
+    const imageBase64 = dataUrlMatch[2] ?? "";
+    if (imageBase64.length === 0) {
+      return undefined;
+    }
+
+    return {
+      mimeType,
+      imageBase64
+    };
+  }
+
+  return {
+    mimeType: "image/png",
+    imageBase64: trimmedValue
+  };
+}
+
+type ManagedLocalScreenshotImage = {
+  mimeType: string;
+  encoding: "base64";
+  imageBase64: string;
+  width?: number;
+  height?: number;
+};
+
+function toOptionalPositiveNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
+}
+
+function readScreenshotImage(value: unknown): ManagedLocalScreenshotImage | undefined {
+  if (value instanceof Uint8Array || value instanceof ArrayBuffer) {
+    return {
+      mimeType: "image/png",
+      encoding: "base64",
+      imageBase64: toBase64(value)
+    };
+  }
+
+  if (typeof value === "string") {
+    const parsed = parseScreenshotBase64(value);
+    if (parsed === undefined) {
+      return undefined;
+    }
+
+    return {
+      mimeType: parsed.mimeType,
+      encoding: "base64",
+      imageBase64: parsed.imageBase64
+    };
+  }
+
+  if (typeof value !== "object" || value === null) {
+    return undefined;
+  }
+
+  const imageBase64 = readObjectStringProperty(value, "imageBase64");
+  if (imageBase64 === undefined || imageBase64.trim().length === 0) {
+    return undefined;
+  }
+
+  const rawEncoding = readObjectStringProperty(value, "encoding");
+  if (rawEncoding !== undefined && rawEncoding !== "base64") {
+    return undefined;
+  }
+
+  const mimeType = readObjectStringProperty(value, "mimeType") ?? "image/png";
+  const width = toOptionalPositiveNumber(readObjectNumberProperty(value, "width"));
+  const height = toOptionalPositiveNumber(readObjectNumberProperty(value, "height"));
+
+  return {
+    mimeType,
+    encoding: "base64",
+    imageBase64: imageBase64.trim(),
+    ...(width !== undefined ? { width } : {}),
+    ...(height !== undefined ? { height } : {})
+  };
+}
+
+async function capturePageScreenshot(page: ManagedLocalPage): Promise<ManagedLocalScreenshotImage> {
+  const screenshotMethod = getObjectMethod(page, "screenshot");
+  if (typeof screenshotMethod !== "function") {
+    throw new Error("Screenshot is not supported by this driver runtime.");
+  }
+
+  const screenshot = await screenshotMethod.call(page, {
+    type: "png"
+  });
+  const parsedScreenshot = readScreenshotImage(screenshot);
+  if (parsedScreenshot === undefined) {
+    throw new Error("Unexpected screenshot payload from driver runtime.");
+  }
+
+  return parsedScreenshot;
+}
+
+type ManagedLocalCookie = {
+  name: string;
+  value: string;
+  domain?: string;
+  path?: string;
+  expires?: number;
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: string;
+  url?: string;
+};
+
+function normalizeCookies(value: unknown): ManagedLocalCookie[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  const cookies: ManagedLocalCookie[] = [];
+  for (const item of value) {
+    if (!isObjectRecord(item)) {
+      continue;
+    }
+
+    const name = readObjectStringProperty(item, "name");
+    const cookieValue = readObjectStringProperty(item, "value");
+    if (name === undefined || cookieValue === undefined) {
+      continue;
+    }
+
+    const domain = readObjectStringProperty(item, "domain");
+    const path = readObjectStringProperty(item, "path");
+    const sameSite = readObjectStringProperty(item, "sameSite");
+    const url = readObjectStringProperty(item, "url");
+    const expiresRaw = readObjectNumberProperty(item, "expires");
+    const httpOnlyRaw = item.httpOnly;
+    const secureRaw = item.secure;
+
+    cookies.push({
+      name,
+      value: cookieValue,
+      ...(domain !== undefined ? { domain } : {}),
+      ...(path !== undefined ? { path } : {}),
+      ...(typeof expiresRaw === "number" && Number.isFinite(expiresRaw) ? { expires: expiresRaw } : {}),
+      ...(typeof httpOnlyRaw === "boolean" ? { httpOnly: httpOnlyRaw } : {}),
+      ...(typeof secureRaw === "boolean" ? { secure: secureRaw } : {}),
+      ...(sameSite !== undefined ? { sameSite } : {}),
+      ...(url !== undefined ? { url } : {})
+    });
+  }
+
+  return cookies;
+}
+
+function toCookieInput(cookie: ManagedLocalCookie): Record<string, unknown> | undefined {
+  const base: Record<string, unknown> = {
+    name: cookie.name,
+    value: cookie.value
+  };
+
+  if (cookie.url !== undefined) {
+    return {
+      ...base,
+      url: cookie.url,
+      ...(cookie.expires !== undefined ? { expires: cookie.expires } : {}),
+      ...(cookie.httpOnly !== undefined ? { httpOnly: cookie.httpOnly } : {}),
+      ...(cookie.secure !== undefined ? { secure: cookie.secure } : {}),
+      ...(cookie.sameSite !== undefined ? { sameSite: cookie.sameSite } : {})
+    };
+  }
+
+  if (cookie.domain !== undefined && cookie.path !== undefined) {
+    return {
+      ...base,
+      domain: cookie.domain,
+      path: cookie.path,
+      ...(cookie.expires !== undefined ? { expires: cookie.expires } : {}),
+      ...(cookie.httpOnly !== undefined ? { httpOnly: cookie.httpOnly } : {}),
+      ...(cookie.secure !== undefined ? { secure: cookie.secure } : {}),
+      ...(cookie.sameSite !== undefined ? { sameSite: cookie.sameSite } : {})
+    };
+  }
+
+  return undefined;
+}
+
+function parseStorageScope(scope: string | undefined): "local" | "session" | undefined {
+  if (scope === "local" || scope === "session") {
+    return scope;
+  }
+
+  return undefined;
+}
+
+function parseFrameIndex(frameId: string | undefined): number | undefined {
+  if (typeof frameId !== "string") {
+    return undefined;
+  }
+
+  const match = /^frame:(\d+)$/.exec(frameId.trim());
+  if (match === null) {
+    return undefined;
+  }
+
+  const parsed = Number.parseInt(match[1] ?? "", 10);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+async function evaluateInPage<TResult>(
+  page: ManagedLocalPage,
+  callback: (arg: unknown) => unknown,
+  arg: unknown
+): Promise<TResult> {
+  const evaluateMethod = getObjectMethod(page, "evaluate");
+  if (typeof evaluateMethod !== "function") {
+    throw new Error("Driver runtime page does not support evaluate.");
+  }
+
+  const result = await evaluateMethod.call(page, callback, arg);
+  return result as TResult;
+}
+
+async function readNetworkResponseBody(value: unknown): Promise<ManagedLocalNetworkResponseBody | undefined> {
+  const textMethod = getObjectMethod(value, "text");
+  if (typeof textMethod === "function") {
+    try {
+      const textResult = await textMethod.call(value);
+      if (typeof textResult === "string") {
+        return {
+          body: textResult,
+          encoding: "utf8"
+        };
+      }
+    } catch {
+      // Ignore body extraction failures from optional runtime hooks.
+    }
+  }
+
+  const bodyMethod = getObjectMethod(value, "body");
+  if (typeof bodyMethod !== "function") {
+    return undefined;
+  }
+
+  try {
+    const bodyResult = await bodyMethod.call(value);
+    if (typeof bodyResult === "string") {
+      return {
+        body: bodyResult,
+        encoding: "utf8"
+      };
+    }
+
+    if (bodyResult instanceof Uint8Array || bodyResult instanceof ArrayBuffer) {
+      return {
+        body: toBase64(bodyResult),
+        encoding: "base64"
+      };
+    }
+
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function attachTelemetryListeners(
+  page: ManagedLocalPage,
+  profileId: ProfileId,
+  targetId: TargetId,
+  telemetryState: ManagedLocalTargetTelemetryState,
+  operationState: ManagedLocalTargetOperationState
+): void {
+  if (typeof page.on !== "function") {
+    return;
+  }
+
+  page.on("console", (message) => {
+    telemetryState.consoleEntries.push(readConsoleEntry(message));
+  });
+
+  page.on("response", async (response) => {
+    const requestId = createRequestId(profileId, targetId, telemetryState.nextRequestNumber);
+    telemetryState.nextRequestNumber += 1;
+    telemetryState.requestSummaries.push(readNetworkSummary(response, requestId));
+
+    const body = await readNetworkResponseBody(response);
+    if (body !== undefined) {
+      telemetryState.networkResponseBodies.set(requestId, body);
+    }
+  });
+
+  page.on("dialog", async (dialog) => {
+    if (operationState.dialogArmedCount <= 0) {
+      return;
+    }
+
+    operationState.dialogArmedCount -= 1;
+    const acceptMethod = getObjectMethod(dialog, "accept");
+    if (typeof acceptMethod === "function") {
+      try {
+        await acceptMethod.call(dialog);
+        return;
+      } catch {
+        // Fall through to dismiss.
+      }
+    }
+
+    const dismissMethod = getObjectMethod(dialog, "dismiss");
+    if (typeof dismissMethod === "function") {
+      try {
+        await dismissMethod.call(dialog);
+      } catch {
+        // Ignore dialog dismissal failures.
+      }
+    }
+  });
+}
+
+async function readDownloadArtifact(
+  value: unknown,
+  fallbackPath: string
+): Promise<ManagedLocalDownloadArtifact> {
+  let resolvedPath = fallbackPath;
+  const pathMethod = getObjectMethod(value, "path");
+  if (typeof pathMethod === "function") {
+    try {
+      const pathResult = await pathMethod.call(value);
+      if (typeof pathResult === "string" && pathResult.trim().length > 0) {
+        resolvedPath = pathResult;
+      }
+    } catch {
+      // Ignore path() failures and keep fallback path.
+    }
+  }
+
+  const saveAsMethod = getObjectMethod(value, "saveAs");
+  if (typeof saveAsMethod === "function") {
+    try {
+      await saveAsMethod.call(value, fallbackPath);
+      resolvedPath = fallbackPath;
+    } catch {
+      // Ignore saveAs failures and keep best-effort path.
+    }
+  }
+
+  const suggestedFilename = readObjectMethod<string>(value, "suggestedFilename");
+  const url = readObjectMethod<string>(value, "url");
+  const mimeType = readObjectMethod<string>(value, "mimeType");
+
+  return {
+    path: resolvedPath,
+    ...(typeof suggestedFilename === "string" ? { suggestedFilename } : {}),
+    ...(typeof url === "string" ? { url } : {}),
+    ...(typeof mimeType === "string" ? { mimeType } : {})
+  };
+}
+
+function createPlaywrightRuntime(): ManagedLocalDriverRuntime {
+  return {
+    launch: async (config) => {
+      const playwright = await import("playwright-core");
+      const browserType =
+        config.browserName === "firefox"
+          ? playwright.firefox
+          : config.browserName === "webkit"
+            ? playwright.webkit
+            : playwright.chromium;
+
+      return browserType.launch({
+        headless: config.headless,
+        channel: config.channel,
+        executablePath: config.executablePath,
+        timeout: config.launchTimeoutMs,
+        args: config.args.length === 0 ? undefined : config.args
+      });
+    }
+  };
+}
+
+export function createManagedLocalDriver(
+  config: ManagedLocalDriverConfig = {}
+): BrowserDriver<ManagedLocalDriverStatus, ManagedLocalSnapshot> &
+  ManagedLocalTelemetryDriverExtensions &
+  BrowserDriverScreenshot<ManagedLocalScreenshot> {
+  const launchConfig: ManagedLocalBrowserLaunchConfig = {
+    browserName: config.browserName ?? DEFAULT_BROWSER_NAME,
+    headless: config.headless ?? DEFAULT_HEADLESS,
+    channel: config.channel,
+    executablePath: config.executablePath,
+    launchTimeoutMs: config.launchTimeoutMs,
+    args: config.args === undefined ? [] : [...config.args]
+  };
+  const runtime = config.runtime ?? createPlaywrightRuntime();
+  const profileStates = new Map<ProfileId, ManagedLocalProfileState>();
+  const profileInitInFlight = new Map<ProfileId, Promise<ManagedLocalProfileState>>();
+  const targetOperationStates = new Map<ProfileId, Map<TargetId, ManagedLocalTargetOperationState>>();
+  const targetTelemetryStates = new Map<ProfileId, Map<TargetId, ManagedLocalTargetTelemetryState>>();
+  let browser: ManagedLocalBrowser | undefined;
+  let launchInFlight: Promise<ManagedLocalBrowser> | undefined;
+
+  async function ensureBrowser(): Promise<ManagedLocalBrowser> {
+    if (browser !== undefined) {
+      return browser;
+    }
+
+    if (launchInFlight === undefined) {
+      launchInFlight = runtime
+        .launch({ ...launchConfig, args: [...launchConfig.args] })
+        .then((createdBrowser) => {
+          browser = createdBrowser;
+          return createdBrowser;
+        })
+        .finally(() => {
+          launchInFlight = undefined;
+        });
+    }
+
+    return launchInFlight;
+  }
+
+  async function ensureProfileState(profileId: ProfileId): Promise<ManagedLocalProfileState> {
+    const existingState = profileStates.get(profileId);
+    if (existingState !== undefined) {
+      if (existingState.context === undefined) {
+        const inFlight = profileInitInFlight.get(profileId);
+        if (inFlight !== undefined) {
+          return inFlight;
+        }
+
+        const initPromise = (async () => {
+          existingState.context = await (await ensureBrowser()).newContext();
+          return existingState;
+        })().finally(() => {
+          profileInitInFlight.delete(profileId);
+        });
+
+        profileInitInFlight.set(profileId, initPromise);
+        return initPromise;
+      }
+
+      return existingState;
+    }
+
+    const createdState = createProfileState();
+    profileStates.set(profileId, createdState);
+    const initPromise = (async () => {
+      createdState.context = await (await ensureBrowser()).newContext();
+      return createdState;
+    })()
+      .catch((error: unknown) => {
+        // Roll back profile state if launch/context setup failed before any tab existed.
+        if (createdState.tabOrder.length === 0) {
+          profileStates.delete(profileId);
+        }
+
+        throw error;
+      })
+      .finally(() => {
+        profileInitInFlight.delete(profileId);
+      });
+
+    profileInitInFlight.set(profileId, initPromise);
+    return initPromise;
+  }
+
+  async function closeProfileResources(
+    profileId: ProfileId,
+    profileState: ManagedLocalProfileState
+  ): Promise<void> {
+    if (profileState.context !== undefined) {
+      await profileState.context.close();
+      profileState.context = undefined;
+    }
+
+    profileStates.delete(profileId);
+    targetOperationStates.delete(profileId);
+    targetTelemetryStates.delete(profileId);
+
+    if (profileStates.size === 0 && browser !== undefined) {
+      await browser.close();
+      browser = undefined;
+    }
+  }
+
+  function requireTargetInProfile(
+    profileId: ProfileId,
+    targetId: TargetId
+  ): { profileState: ManagedLocalProfileState; tab: ManagedLocalTab } {
+    const profileState = profileStates.get(profileId);
+    const tab = profileState?.tabs.get(targetId);
+    if (profileState === undefined || tab === undefined) {
+      throw new Error(`Unknown targetId: ${targetId} (profile: ${profileId})`);
+    }
+
+    return { profileState, tab };
+  }
+
+  function getOrCreateTargetOperationState(
+    profileId: ProfileId,
+    targetId: TargetId,
+    validateTarget = true
+  ): ManagedLocalTargetOperationState {
+    if (validateTarget) {
+      requireTargetInProfile(profileId, targetId);
+    }
+
+    let profileOperationStates = targetOperationStates.get(profileId);
+    if (profileOperationStates === undefined) {
+      profileOperationStates = new Map<TargetId, ManagedLocalTargetOperationState>();
+      targetOperationStates.set(profileId, profileOperationStates);
+    }
+
+    const existingState = profileOperationStates.get(targetId);
+    if (existingState !== undefined) {
+      return existingState;
+    }
+
+    const createdState = createTargetOperationState();
+    profileOperationStates.set(targetId, createdState);
+    return createdState;
+  }
+
+  function getOrCreateProfileTelemetryStates(
+    profileId: ProfileId
+  ): Map<TargetId, ManagedLocalTargetTelemetryState> {
+    const existingStates = targetTelemetryStates.get(profileId);
+    if (existingStates !== undefined) {
+      return existingStates;
+    }
+
+    const createdStates = new Map<TargetId, ManagedLocalTargetTelemetryState>();
+    targetTelemetryStates.set(profileId, createdStates);
+    return createdStates;
+  }
+
+  function findTelemetryState(
+    targetId: TargetId,
+    profile?: ProfileId
+  ): ManagedLocalTargetTelemetryState | undefined {
+    if (profile !== undefined) {
+      return targetTelemetryStates.get(resolveProfileId(profile))?.get(targetId);
+    }
+
+    for (const profileTelemetryStates of targetTelemetryStates.values()) {
+      const telemetryState = profileTelemetryStates.get(targetId);
+      if (telemetryState !== undefined) {
+        return telemetryState;
+      }
+    }
+
+    return undefined;
+  }
+
+  function ensureDownloadInFlight(
+    profileId: ProfileId,
+    targetId: TargetId,
+    tab: ManagedLocalTab,
+    operationState: ManagedLocalTargetOperationState
+  ): Promise<ManagedLocalDownloadArtifact> {
+    if (operationState.downloadInFlight !== undefined) {
+      return operationState.downloadInFlight;
+    }
+
+    const fallbackPath = createDownloadPath(
+      profileId,
+      targetId,
+      Math.max(operationState.triggerCount, 1)
+    );
+    const waitForEventMethod = getObjectMethod(tab.page, "waitForEvent");
+    if (typeof waitForEventMethod !== "function") {
+      const artifact: ManagedLocalDownloadArtifact = { path: fallbackPath };
+      operationState.latestDownload = artifact;
+      const resolved = Promise.resolve(artifact);
+      operationState.downloadInFlight = resolved;
+      return resolved;
+    }
+
+    const inFlight = (async () => {
+      const rawDownload = await waitForEventMethod.call(tab.page, "download");
+      const artifact = await readDownloadArtifact(rawDownload, fallbackPath);
+      operationState.latestDownload = artifact;
+      return artifact;
+    })().finally(() => {
+      if (operationState.downloadInFlight === inFlight) {
+        operationState.downloadInFlight = undefined;
+      }
+    });
+
+    operationState.downloadInFlight = inFlight;
+    return inFlight;
+  }
+
+  return {
+    status: async () => ({
+      kind: "managed-local",
+      connected: browser !== undefined,
+      launched: browser !== undefined,
+      browserName: launchConfig.browserName,
+      headless: launchConfig.headless,
+      channel: launchConfig.channel,
+      executablePath: launchConfig.executablePath,
+      launchTimeoutMs: launchConfig.launchTimeoutMs
+    }),
+    listProfiles: async () => {
+      const knownProfiles = new Set<ProfileId>([DEFAULT_PROFILE_ID]);
+      for (const profileId of profileStates.keys()) {
+        knownProfiles.add(profileId);
+      }
+
+      return Array.from(knownProfiles).sort();
+    },
+    listTabs: async (profile) => {
+      const profileId = resolveProfileId(profile);
+      const profileState = profileStates.get(profileId);
+      return profileState === undefined ? [] : [...profileState.tabOrder];
+    },
+    openTab: async (url, profile) => {
+      const profileId = resolveProfileId(profile);
+      const profileState = await ensureProfileState(profileId);
+      const targetId = createTargetId(profileId, profileState.nextTargetNumber);
+      const context = profileState.context;
+      if (context === undefined) {
+        throw new Error(`No browser context available for profile: ${profileId}`);
+      }
+
+      const page = await context.newPage();
+      const telemetryState = createTargetTelemetryState();
+      const operationState = getOrCreateTargetOperationState(profileId, targetId, false);
+      attachTelemetryListeners(page, profileId, targetId, telemetryState, operationState);
+      await page.goto(url);
+
+      profileState.nextTargetNumber += 1;
+      profileState.tabs.set(targetId, { url, page });
+      profileState.tabOrder.push(targetId);
+      getOrCreateProfileTelemetryStates(profileId).set(targetId, telemetryState);
+      if (profileState.focusedTargetId === undefined) {
+        profileState.focusedTargetId = targetId;
+      }
+
+      return targetId;
+    },
+    focusTab: async (targetId, profile) => {
+      const profileId = resolveProfileId(profile);
+      const { profileState, tab } = requireTargetInProfile(profileId, targetId);
+      await tab.page.bringToFront();
+      profileState.focusedTargetId = targetId;
+    },
+    closeTab: async (targetId, profile) => {
+      const profileId = resolveProfileId(profile);
+      const { profileState, tab } = requireTargetInProfile(profileId, targetId);
+
+      await tab.page.close();
+
+      profileState.tabs.delete(targetId);
+      profileState.tabOrder = profileState.tabOrder.filter((existingTargetId) => existingTargetId !== targetId);
+      if (profileState.focusedTargetId === targetId) {
+        profileState.focusedTargetId = profileState.tabOrder[0];
+      }
+
+      const profileOperationStates = targetOperationStates.get(profileId);
+      profileOperationStates?.delete(targetId);
+      if (profileOperationStates !== undefined && profileOperationStates.size === 0) {
+        targetOperationStates.delete(profileId);
+      }
+
+      const profileTelemetryStates = targetTelemetryStates.get(profileId);
+      profileTelemetryStates?.delete(targetId);
+      if (profileTelemetryStates !== undefined && profileTelemetryStates.size === 0) {
+        targetTelemetryStates.delete(profileId);
+      }
+
+      if (profileState.tabOrder.length === 0) {
+        await closeProfileResources(profileId, profileState);
+      }
+    },
+    snapshot: async (targetId, profile) => {
+      const profileId = resolveProfileId(profile);
+      const tab = profileStates.get(profileId)?.tabs.get(targetId);
+      if (tab === undefined) {
+        return {
+          kind: "managed-local",
+          profile: profileId,
+          targetId,
+          hasTarget: false
+        };
+      }
+
+      const requestSummaries =
+        targetTelemetryStates
+          .get(profileId)
+          ?.get(targetId)
+          ?.requestSummaries.map((summary) => ({ ...summary })) ?? [];
+
+      return {
+        kind: "managed-local",
+        profile: profileId,
+        targetId,
+        hasTarget: true,
+        url: tab.page.url(),
+        title: await tab.page.title(),
+        html: await tab.page.content(),
+        requestSummaries
+      };
+    },
+    screenshot: async (targetId, profile) => {
+      const profileId = resolveProfileId(profile);
+      const tab = profileStates.get(profileId)?.tabs.get(targetId);
+      if (tab === undefined) {
+        return {
+          kind: "managed-local",
+          profile: profileId,
+          targetId,
+          hasTarget: false
+        };
+      }
+
+      const screenshot = await capturePageScreenshot(tab.page);
+      return {
+        kind: "managed-local",
+        profile: profileId,
+        targetId,
+        hasTarget: true,
+        ...screenshot
+      };
+    },
+    act: async (action, targetId, profile) => {
+      const profileId = resolveProfileId(profile);
+      const tab = profileStates.get(profileId)?.tabs.get(targetId);
+      if (tab === undefined) {
+        return {
+          actionType: action.type,
+          profile: profileId,
+          targetId,
+          targetKnown: false,
+          ok: false,
+          error: `Unknown targetId: ${targetId} (profile: ${profileId})`
+        };
+      }
+
+      const payload = action.payload;
+      const profileState = profileStates.get(profileId);
+      const operationState = getOrCreateTargetOperationState(profileId, targetId);
+      const baseResult = {
+        actionType: action.type,
+        profile: profileId,
+        targetId,
+        targetKnown: true
+      };
+
+      const performAction = async (): Promise<{
+        ok: boolean;
+        executed: boolean;
+        error?: string;
+        data?: Record<string, unknown>;
+      }> => {
+        switch (action.type) {
+          case "navigate":
+          case "goto": {
+            const nextUrl = readActionPayloadString(payload, "url");
+            if (nextUrl === undefined) {
+              return {
+                ok: false,
+                executed: false,
+                error: "action.payload.url is required for navigate action."
+              };
+            }
+
+            await tab.page.goto(nextUrl);
+            tab.url = nextUrl;
+            return { ok: true, executed: true };
+          }
+          case "click": {
+            const selector = readActionPayloadString(payload, "selector");
+            if (selector === undefined) {
+              return {
+                ok: false,
+                executed: false,
+                error: "action.payload.selector is required for click action."
+              };
+            }
+
+            const locator = tab.page.locator(selector);
+            if (operationState.uploadFiles.length > 0) {
+              const setInputFilesMethod = getObjectMethod(locator, "setInputFiles");
+              if (typeof setInputFilesMethod === "function") {
+                await setInputFilesMethod.call(locator, [...operationState.uploadFiles]);
+                operationState.uploadFiles = [];
+                return { ok: true, executed: true };
+              }
+            }
+
+            await locator.click();
+            return { ok: true, executed: true };
+          }
+          case "fill": {
+            const selector = readActionPayloadString(payload, "selector");
+            const value = readActionPayloadString(payload, "value");
+            if (selector === undefined || value === undefined) {
+              return {
+                ok: false,
+                executed: false,
+                error: "action.payload.selector and action.payload.value are required for fill action."
+              };
+            }
+
+            await tab.page.locator(selector).fill(value);
+            return { ok: true, executed: true };
+          }
+          case "type": {
+            const selector = readActionPayloadString(payload, "selector");
+            const text = readActionPayloadString(payload, "text");
+            if (selector === undefined || text === undefined) {
+              return {
+                ok: false,
+                executed: false,
+                error: "action.payload.selector and action.payload.text are required for type action."
+              };
+            }
+
+            await tab.page.locator(selector).type(text);
+            return { ok: true, executed: true };
+          }
+          case "press": {
+            const key = readActionPayloadString(payload, "key");
+            if (key === undefined || tab.page.keyboard === undefined) {
+              return {
+                ok: false,
+                executed: false,
+                error: "action.payload.key is required for press action."
+              };
+            }
+
+            await tab.page.keyboard.press(key);
+            return { ok: true, executed: true };
+          }
+          case "domQuery": {
+            const selector = readActionPayloadString(payload, "selector");
+            if (selector === undefined) {
+              return {
+                ok: false,
+                executed: false,
+                error: "action.payload.selector is required for domQuery action."
+              };
+            }
+
+            const customDomQueryMethod = getObjectMethod(tab.page, "domQuery");
+            if (typeof customDomQueryMethod === "function") {
+              const customResult = await customDomQueryMethod.call(tab.page, selector);
+              return {
+                ok: true,
+                executed: true,
+                data: isObjectRecord(customResult)
+                  ? customResult
+                  : {
+                      selector,
+                      found: false
+                    }
+              };
+            }
+
+            const queryResult = await evaluateInPage<Record<string, unknown>>(
+              tab.page,
+              (rawArg) => {
+                const selectorValue =
+                  rawArg !== null &&
+                  typeof rawArg === "object" &&
+                  typeof (rawArg as { selector?: unknown }).selector === "string"
+                    ? (rawArg as { selector: string }).selector
+                    : "";
+                const element = selectorValue.length > 0 ? document.querySelector(selectorValue) : null;
+                if (element === null) {
+                  return {
+                    selector: selectorValue,
+                    found: false
+                  };
+                }
+
+                const attributes: Record<string, string> = {};
+                for (const attribute of Array.from(element.attributes)) {
+                  attributes[attribute.name] = attribute.value;
+                }
+
+                return {
+                  selector: selectorValue,
+                  found: true,
+                  node: {
+                    tagName: element.tagName.toLowerCase(),
+                    id: element.id || undefined,
+                    className: element.className || undefined,
+                    text: (element.textContent || "").trim().slice(0, 300),
+                    attributes
+                  }
+                };
+              },
+              { selector }
+            );
+
+            return {
+              ok: true,
+              executed: true,
+              data: isObjectRecord(queryResult)
+                ? queryResult
+                : {
+                    selector,
+                    found: false
+                  }
+            };
+          }
+          case "domQueryAll": {
+            const selector = readActionPayloadString(payload, "selector");
+            if (selector === undefined) {
+              return {
+                ok: false,
+                executed: false,
+                error: "action.payload.selector is required for domQueryAll action."
+              };
+            }
+
+            const customDomQueryAllMethod = getObjectMethod(tab.page, "domQueryAll");
+            if (typeof customDomQueryAllMethod === "function") {
+              const customResult = await customDomQueryAllMethod.call(tab.page, selector);
+              return {
+                ok: true,
+                executed: true,
+                data: isObjectRecord(customResult)
+                  ? customResult
+                  : {
+                      selector,
+                      count: 0,
+                      nodes: []
+                    }
+              };
+            }
+
+            const queryResult = await evaluateInPage<Record<string, unknown>>(
+              tab.page,
+              (rawArg) => {
+                const selectorValue =
+                  rawArg !== null &&
+                  typeof rawArg === "object" &&
+                  typeof (rawArg as { selector?: unknown }).selector === "string"
+                    ? (rawArg as { selector: string }).selector
+                    : "";
+                const elements = selectorValue.length > 0 ? document.querySelectorAll(selectorValue) : [];
+                const nodes = Array.from(elements).map((element, index) => {
+                  const attributes: Record<string, string> = {};
+                  for (const attribute of Array.from(element.attributes)) {
+                    attributes[attribute.name] = attribute.value;
+                  }
+
+                  return {
+                    index,
+                    tagName: element.tagName.toLowerCase(),
+                    id: element.id || undefined,
+                    className: element.className || undefined,
+                    text: (element.textContent || "").trim().slice(0, 300),
+                    attributes
+                  };
+                });
+
+                return {
+                  selector: selectorValue,
+                  count: nodes.length,
+                  nodes
+                };
+              },
+              { selector }
+            );
+
+            return {
+              ok: true,
+              executed: true,
+              data: isObjectRecord(queryResult)
+                ? queryResult
+                : {
+                    selector,
+                    count: 0,
+                    nodes: []
+                  }
+            };
+          }
+          case "elementScreenshot": {
+            const selector = readActionPayloadString(payload, "selector");
+            if (selector === undefined) {
+              return {
+                ok: false,
+                executed: false,
+                error: "action.payload.selector is required for elementScreenshot action."
+              };
+            }
+
+            const customElementScreenshotMethod = getObjectMethod(tab.page, "elementScreenshot");
+            if (typeof customElementScreenshotMethod === "function") {
+              const customResult = await customElementScreenshotMethod.call(tab.page, selector);
+              return {
+                ok: true,
+                executed: true,
+                data: isObjectRecord(customResult)
+                  ? customResult
+                  : {
+                      selector,
+                      found: false
+                    }
+              };
+            }
+
+            const found = await evaluateInPage<boolean>(
+              tab.page,
+              (rawArg) => {
+                const selectorValue =
+                  rawArg !== null &&
+                  typeof rawArg === "object" &&
+                  typeof (rawArg as { selector?: unknown }).selector === "string"
+                    ? (rawArg as { selector: string }).selector
+                    : "";
+                return selectorValue.length > 0 && document.querySelector(selectorValue) !== null;
+              },
+              { selector }
+            );
+            if (!found) {
+              return {
+                ok: true,
+                executed: true,
+                data: {
+                  selector,
+                  found: false
+                }
+              };
+            }
+
+            const locator = tab.page.locator(selector);
+            const locatorScreenshotMethod = getObjectMethod(locator, "screenshot");
+            if (typeof locatorScreenshotMethod !== "function") {
+              return {
+                ok: true,
+                executed: false
+              };
+            }
+
+            const rawScreenshot = await locatorScreenshotMethod.call(locator, { type: "png" });
+            const parsedScreenshot = readScreenshotImage(rawScreenshot);
+            if (parsedScreenshot === undefined) {
+              return {
+                ok: false,
+                executed: false,
+                error: "Unable to parse element screenshot payload."
+              };
+            }
+
+            return {
+              ok: true,
+              executed: true,
+              data: {
+                selector,
+                found: true,
+                ...parsedScreenshot
+              }
+            };
+          }
+          case "a11ySnapshot": {
+            const selector = readActionPayloadString(payload, "selector");
+            const customA11ySnapshotMethod = getObjectMethod(tab.page, "a11ySnapshot");
+            if (typeof customA11ySnapshotMethod === "function") {
+              const customResult = await customA11ySnapshotMethod.call(tab.page, selector);
+              return {
+                ok: true,
+                executed: true,
+                data: isObjectRecord(customResult)
+                  ? customResult
+                  : {
+                      found: false
+                    }
+              };
+            }
+
+            const accessibilityValue =
+              typeof tab.page === "object" && tab.page !== null
+                ? (tab.page as Record<string, unknown>).accessibility
+                : undefined;
+            const accessibilitySnapshotMethod = getObjectMethod(accessibilityValue, "snapshot");
+            if (typeof accessibilitySnapshotMethod === "function") {
+              const snapshot = await accessibilitySnapshotMethod.call(accessibilityValue, {});
+              return {
+                ok: true,
+                executed: true,
+                data: {
+                  selector,
+                  found: true,
+                  snapshot
+                }
+              };
+            }
+
+            const fallbackSnapshot = await evaluateInPage<Record<string, unknown>>(
+              tab.page,
+              (rawArg) => {
+                const selectorValue =
+                  rawArg !== null &&
+                  typeof rawArg === "object" &&
+                  typeof (rawArg as { selector?: unknown }).selector === "string"
+                    ? (rawArg as { selector: string }).selector
+                    : "";
+                const root =
+                  selectorValue.length > 0
+                    ? document.querySelector(selectorValue)
+                    : document.body ?? document.documentElement;
+                if (root === null) {
+                  return {
+                    selector: selectorValue,
+                    found: false
+                  };
+                }
+
+                const build = (element: Element, depth: number): Record<string, unknown> => {
+                  const role =
+                    element.getAttribute("role") ??
+                    (element.tagName.toLowerCase() === "a"
+                      ? "link"
+                      : element.tagName.toLowerCase() === "button"
+                        ? "button"
+                        : element.tagName.toLowerCase() === "input"
+                          ? "textbox"
+                          : "generic");
+                  const name =
+                    element.getAttribute("aria-label") ??
+                    element.getAttribute("alt") ??
+                    (element.textContent || "").trim().slice(0, 120);
+                  if (depth >= 5) {
+                    return {
+                      role,
+                      ...(name.length > 0 ? { name } : {})
+                    };
+                  }
+
+                  const children = Array.from(element.children)
+                    .slice(0, 30)
+                    .map((child) => build(child, depth + 1));
+                  return {
+                    role,
+                    ...(name.length > 0 ? { name } : {}),
+                    ...(children.length > 0 ? { children } : {})
+                  };
+                };
+
+                return {
+                  selector: selectorValue,
+                  found: true,
+                  snapshot: build(root, 0)
+                };
+              },
+              { selector: selector ?? "" }
+            );
+
+            return {
+              ok: true,
+              executed: true,
+              data: isObjectRecord(fallbackSnapshot)
+                ? fallbackSnapshot
+                : {
+                    selector,
+                    found: false
+                  }
+            };
+          }
+          case "cookieGet": {
+            const cookieName = readActionPayloadString(payload, "name");
+            const customCookieGetMethod = getObjectMethod(tab.page, "cookieGet");
+            if (typeof customCookieGetMethod === "function") {
+              const customResult = await customCookieGetMethod.call(tab.page, cookieName);
+              return {
+                ok: true,
+                executed: true,
+                data: isObjectRecord(customResult)
+                  ? customResult
+                  : {
+                      cookies: []
+                    }
+              };
+            }
+
+            const context = profileState?.context;
+            const cookiesMethod = context === undefined ? undefined : getObjectMethod(context, "cookies");
+            if (typeof cookiesMethod !== "function") {
+              return {
+                ok: true,
+                executed: false
+              };
+            }
+
+            let rawCookies: unknown;
+            try {
+              rawCookies = await cookiesMethod.call(context, [tab.page.url()]);
+            } catch {
+              rawCookies = await cookiesMethod.call(context);
+            }
+            const cookies = normalizeCookies(rawCookies).filter(
+              (cookie) => cookieName === undefined || cookie.name === cookieName
+            );
+            return {
+              ok: true,
+              executed: true,
+              data: {
+                cookies,
+                ...(cookieName !== undefined ? { name: cookieName } : {})
+              }
+            };
+          }
+          case "cookieSet": {
+            const cookieName = readActionPayloadString(payload, "name");
+            const cookieValue = readActionPayloadString(payload, "value");
+            const cookieUrl = readActionPayloadString(payload, "url") ?? tab.page.url();
+            if (cookieName === undefined || cookieValue === undefined) {
+              return {
+                ok: false,
+                executed: false,
+                error: "action.payload.name and action.payload.value are required for cookieSet action."
+              };
+            }
+
+            const customCookieSetMethod = getObjectMethod(tab.page, "cookieSet");
+            if (typeof customCookieSetMethod === "function") {
+              const customResult = await customCookieSetMethod.call(tab.page, {
+                name: cookieName,
+                value: cookieValue,
+                url: cookieUrl
+              });
+              return {
+                ok: true,
+                executed: true,
+                data: isObjectRecord(customResult)
+                  ? customResult
+                  : {
+                      set: true,
+                      cookie: {
+                        name: cookieName,
+                        value: cookieValue,
+                        url: cookieUrl
+                      }
+                    }
+              };
+            }
+
+            const context = profileState?.context;
+            const addCookiesMethod = context === undefined ? undefined : getObjectMethod(context, "addCookies");
+            if (typeof addCookiesMethod !== "function") {
+              return {
+                ok: true,
+                executed: false
+              };
+            }
+
+            await addCookiesMethod.call(context, [
+              {
+                name: cookieName,
+                value: cookieValue,
+                url: cookieUrl
+              }
+            ]);
+
+            return {
+              ok: true,
+              executed: true,
+              data: {
+                set: true,
+                cookie: {
+                  name: cookieName,
+                  value: cookieValue,
+                  url: cookieUrl
+                }
+              }
+            };
+          }
+          case "cookieClear": {
+            const cookieName = readActionPayloadString(payload, "name");
+            const customCookieClearMethod = getObjectMethod(tab.page, "cookieClear");
+            if (typeof customCookieClearMethod === "function") {
+              const customResult = await customCookieClearMethod.call(tab.page, cookieName);
+              return {
+                ok: true,
+                executed: true,
+                data: isObjectRecord(customResult)
+                  ? customResult
+                  : {
+                      cleared: true
+                    }
+              };
+            }
+
+            const context = profileState?.context;
+            const clearCookiesMethod = context === undefined ? undefined : getObjectMethod(context, "clearCookies");
+            if (typeof clearCookiesMethod !== "function") {
+              return {
+                ok: true,
+                executed: false
+              };
+            }
+
+            if (cookieName === undefined) {
+              await clearCookiesMethod.call(context);
+              return {
+                ok: true,
+                executed: true,
+                data: {
+                  cleared: true,
+                  count: -1
+                }
+              };
+            }
+
+            const cookiesMethod = getObjectMethod(context, "cookies");
+            const addCookiesMethod = getObjectMethod(context, "addCookies");
+            if (typeof cookiesMethod !== "function" || typeof addCookiesMethod !== "function") {
+              return {
+                ok: true,
+                executed: false
+              };
+            }
+
+            let rawCookies: unknown;
+            try {
+              rawCookies = await cookiesMethod.call(context, [tab.page.url()]);
+            } catch {
+              rawCookies = await cookiesMethod.call(context);
+            }
+            const currentCookies = normalizeCookies(rawCookies);
+            const keptCookieInputs = currentCookies
+              .filter((cookie) => cookie.name !== cookieName)
+              .map((cookie) => toCookieInput(cookie))
+              .filter((cookie): cookie is Record<string, unknown> => cookie !== undefined);
+            const removedCount = currentCookies.length - keptCookieInputs.length;
+
+            await clearCookiesMethod.call(context);
+            if (keptCookieInputs.length > 0) {
+              await addCookiesMethod.call(context, keptCookieInputs);
+            }
+
+            return {
+              ok: true,
+              executed: true,
+              data: {
+                cleared: true,
+                name: cookieName,
+                count: removedCount
+              }
+            };
+          }
+          case "storageGet": {
+            const scope = parseStorageScope(readActionPayloadString(payload, "scope"));
+            const key = readActionPayloadString(payload, "key");
+            if (scope === undefined || key === undefined) {
+              return {
+                ok: false,
+                executed: false,
+                error: "action.payload.scope and action.payload.key are required for storageGet action."
+              };
+            }
+
+            const customStorageGetMethod = getObjectMethod(tab.page, "storageGet");
+            if (typeof customStorageGetMethod === "function") {
+              const customResult = await customStorageGetMethod.call(tab.page, scope, key);
+              return {
+                ok: true,
+                executed: true,
+                data: isObjectRecord(customResult)
+                  ? customResult
+                  : {
+                      scope,
+                      key,
+                      exists: false
+                    }
+              };
+            }
+
+            const result = await evaluateInPage<Record<string, unknown>>(
+              tab.page,
+              (rawArg) => {
+                const scopeValue =
+                  rawArg !== null &&
+                  typeof rawArg === "object" &&
+                  typeof (rawArg as { scope?: unknown }).scope === "string"
+                    ? (rawArg as { scope: string }).scope
+                    : "local";
+                const keyValue =
+                  rawArg !== null &&
+                  typeof rawArg === "object" &&
+                  typeof (rawArg as { key?: unknown }).key === "string"
+                    ? (rawArg as { key: string }).key
+                    : "";
+                const storage = scopeValue === "session" ? window.sessionStorage : window.localStorage;
+                const value = storage.getItem(keyValue);
+                return {
+                  scope: scopeValue,
+                  key: keyValue,
+                  exists: value !== null,
+                  ...(value !== null ? { value } : {})
+                };
+              },
+              { scope, key }
+            );
+
+            return {
+              ok: true,
+              executed: true,
+              data: isObjectRecord(result)
+                ? result
+                : {
+                    scope,
+                    key,
+                    exists: false
+                  }
+            };
+          }
+          case "storageSet": {
+            const scope = parseStorageScope(readActionPayloadString(payload, "scope"));
+            const key = readActionPayloadString(payload, "key");
+            const value = readActionPayloadString(payload, "value");
+            if (scope === undefined || key === undefined || value === undefined) {
+              return {
+                ok: false,
+                executed: false,
+                error: "action.payload.scope, action.payload.key and action.payload.value are required for storageSet action."
+              };
+            }
+
+            const customStorageSetMethod = getObjectMethod(tab.page, "storageSet");
+            if (typeof customStorageSetMethod === "function") {
+              const customResult = await customStorageSetMethod.call(tab.page, scope, key, value);
+              return {
+                ok: true,
+                executed: true,
+                data: isObjectRecord(customResult)
+                  ? customResult
+                  : {
+                      scope,
+                      key,
+                      value,
+                      set: true
+                    }
+              };
+            }
+
+            await evaluateInPage(
+              tab.page,
+              (rawArg) => {
+                const scopeValue =
+                  rawArg !== null &&
+                  typeof rawArg === "object" &&
+                  typeof (rawArg as { scope?: unknown }).scope === "string"
+                    ? (rawArg as { scope: string }).scope
+                    : "local";
+                const keyValue =
+                  rawArg !== null &&
+                  typeof rawArg === "object" &&
+                  typeof (rawArg as { key?: unknown }).key === "string"
+                    ? (rawArg as { key: string }).key
+                    : "";
+                const valueText =
+                  rawArg !== null &&
+                  typeof rawArg === "object" &&
+                  typeof (rawArg as { value?: unknown }).value === "string"
+                    ? (rawArg as { value: string }).value
+                    : "";
+                const storage = scopeValue === "session" ? window.sessionStorage : window.localStorage;
+                storage.setItem(keyValue, valueText);
+              },
+              { scope, key, value }
+            );
+
+            return {
+              ok: true,
+              executed: true,
+              data: {
+                scope,
+                key,
+                value,
+                set: true
+              }
+            };
+          }
+          case "frameList": {
+            const customFrameListMethod = getObjectMethod(tab.page, "frameList");
+            if (typeof customFrameListMethod === "function") {
+              const customResult = await customFrameListMethod.call(tab.page);
+              return {
+                ok: true,
+                executed: true,
+                data: isObjectRecord(customResult)
+                  ? customResult
+                  : {
+                      frames: []
+                    }
+              };
+            }
+
+            const framesMethod = getObjectMethod(tab.page, "frames");
+            if (typeof framesMethod !== "function") {
+              return {
+                ok: true,
+                executed: false
+              };
+            }
+
+            const rawFrames = await framesMethod.call(tab.page);
+            if (!Array.isArray(rawFrames)) {
+              return {
+                ok: true,
+                executed: true,
+                data: {
+                  frames: []
+                }
+              };
+            }
+
+            const mainFrameMethod = getObjectMethod(tab.page, "mainFrame");
+            const mainFrame = typeof mainFrameMethod === "function" ? await mainFrameMethod.call(tab.page) : undefined;
+            const frames = rawFrames.map((frame, index) => {
+              const name = readObjectMethod<string>(frame, "name");
+              const url = readObjectMethod<string>(frame, "url") ?? "";
+              return {
+                frameId: `frame:${index}`,
+                index,
+                ...(typeof name === "string" && name.length > 0 ? { name } : {}),
+                url,
+                isMainFrame: frame === mainFrame
+              };
+            });
+
+            return {
+              ok: true,
+              executed: true,
+              data: {
+                frames
+              }
+            };
+          }
+          case "frameSnapshot": {
+            const frameId = readActionPayloadString(payload, "frameId");
+            if (frameId === undefined) {
+              return {
+                ok: false,
+                executed: false,
+                error: "action.payload.frameId is required for frameSnapshot action."
+              };
+            }
+
+            const customFrameSnapshotMethod = getObjectMethod(tab.page, "frameSnapshot");
+            if (typeof customFrameSnapshotMethod === "function") {
+              const customResult = await customFrameSnapshotMethod.call(tab.page, frameId);
+              return {
+                ok: true,
+                executed: true,
+                data: isObjectRecord(customResult)
+                  ? customResult
+                  : {
+                      frameId,
+                      found: false
+                    }
+              };
+            }
+
+            const frameIndex = parseFrameIndex(frameId);
+            if (frameIndex === undefined) {
+              return {
+                ok: false,
+                executed: false,
+                error: `Invalid frameId: ${frameId}`
+              };
+            }
+
+            const framesMethod = getObjectMethod(tab.page, "frames");
+            if (typeof framesMethod !== "function") {
+              return {
+                ok: true,
+                executed: false
+              };
+            }
+
+            const rawFrames = await framesMethod.call(tab.page);
+            if (!Array.isArray(rawFrames) || frameIndex >= rawFrames.length) {
+              return {
+                ok: true,
+                executed: true,
+                data: {
+                  frameId,
+                  found: false
+                }
+              };
+            }
+
+            const frame = rawFrames[frameIndex];
+            const contentMethod = getObjectMethod(frame, "content");
+            if (typeof contentMethod !== "function") {
+              return {
+                ok: true,
+                executed: false
+              };
+            }
+
+            const mainFrameMethod = getObjectMethod(tab.page, "mainFrame");
+            const mainFrame = typeof mainFrameMethod === "function" ? await mainFrameMethod.call(tab.page) : undefined;
+            const frameName = readObjectMethod<string>(frame, "name");
+            const frameUrl = readObjectMethod<string>(frame, "url") ?? "";
+            const frameHtml = await contentMethod.call(frame);
+
+            return {
+              ok: true,
+              executed: true,
+              data: {
+                frameId,
+                index: frameIndex,
+                found: true,
+                ...(typeof frameName === "string" && frameName.length > 0 ? { name: frameName } : {}),
+                url: frameUrl,
+                isMainFrame: frame === mainFrame,
+                html: typeof frameHtml === "string" ? frameHtml : ""
+              }
+            };
+          }
+          default:
+            return {
+              ok: true,
+              executed: false
+            };
+        }
+      };
+
+      try {
+        return {
+          ...baseResult,
+          ...(await performAction())
+        };
+      } catch (error) {
+        return {
+          ...baseResult,
+          ok: false,
+          executed: false,
+          error: toErrorMessage(error)
+        };
+      }
+    },
+    armUpload: async (targetId, files, profile) => {
+      const profileId = resolveProfileId(profile);
+      const operationState = getOrCreateTargetOperationState(profileId, targetId);
+      operationState.uploadFiles = [...files];
+    },
+    armDialog: async (targetId, profile) => {
+      const profileId = resolveProfileId(profile);
+      const operationState = getOrCreateTargetOperationState(profileId, targetId);
+      operationState.dialogArmedCount += 1;
+    },
+    waitDownload: async (targetId, profile) => {
+      const profileId = resolveProfileId(profile);
+      const { tab } = requireTargetInProfile(profileId, targetId);
+      const operationState = getOrCreateTargetOperationState(profileId, targetId);
+      const download = await ensureDownloadInFlight(profileId, targetId, tab, operationState);
+
+      return {
+        path: download.path,
+        profile: profileId,
+        targetId,
+        uploadFiles: [...operationState.uploadFiles],
+        dialogArmedCount: operationState.dialogArmedCount,
+        triggerCount: operationState.triggerCount,
+        ...(download.suggestedFilename !== undefined
+          ? { suggestedFilename: download.suggestedFilename }
+          : {}),
+        ...(download.url !== undefined ? { url: download.url } : {}),
+        ...(download.mimeType !== undefined ? { mimeType: download.mimeType } : {})
+      };
+    },
+    triggerDownload: async (targetId, profile) => {
+      const profileId = resolveProfileId(profile);
+      const { tab } = requireTargetInProfile(profileId, targetId);
+      const operationState = getOrCreateTargetOperationState(profileId, targetId);
+      operationState.triggerCount += 1;
+      void ensureDownloadInFlight(profileId, targetId, tab, operationState);
+    },
+    getConsoleEntries: (targetId, profile) => {
+      const telemetryState = findTelemetryState(targetId, profile);
+      return telemetryState === undefined ? [] : telemetryState.consoleEntries.map((entry) => ({ ...entry }));
+    },
+    getNetworkResponseBody: (requestId, targetId, profile) => {
+      const body = findTelemetryState(targetId, profile)?.networkResponseBodies.get(requestId);
+      return body === undefined ? undefined : { ...body };
+    }
+  };
+}