@ricsam/isolate-playwright 0.1.12 → 0.1.13

package/dist/types/index.d.ts

@@ -1,7 +1,11 @@
 import ivm from "isolated-vm";
-import type { Page } from "playwright";
-import type { PlaywrightOperation, PlaywrightResult, PlaywrightEvent } from "@ricsam/isolate-protocol";
-export type { PlaywrightOperation, PlaywrightResult, PlaywrightEvent } from "@ricsam/isolate-protocol";
+import type { Page, BrowserContext, BrowserContextOptions } from "playwright";
+import type { PlaywrightOperation, PlaywrightResult, PlaywrightEvent, PlaywrightFileData } from "@ricsam/isolate-protocol";
+import { DEFAULT_PLAYWRIGHT_HANDLER_META, type DefaultPlaywrightHandlerMetadata, type DefaultPlaywrightHandlerOptions } from "./types.ts";
+export type { PlaywrightOperation, PlaywrightResult, PlaywrightEvent, PlaywrightFileData } from "@ricsam/isolate-protocol";
+export { DEFAULT_PLAYWRIGHT_HANDLER_META };
+export type ReadFileCallback = (filePath: string) => Promise<PlaywrightFileData> | PlaywrightFileData;
+export type WriteFileCallback = (filePath: string, data: Buffer) => Promise<void> | void;
 export interface NetworkRequestInfo {
     url: string;
     method: string;
@@ -44,15 +48,21 @@ export interface PlaywrightSetupOptions {
     console?: boolean;
     /** Unified event callback for all playwright events */
     onEvent?: (event: PlaywrightEvent) => void;
-}
-/**
- * @deprecated Use PlaywrightSetupOptions instead
- */
-export interface PlaywrightOptions {
-    page: Page;
-    timeout?: number;
-    onNetworkRequest?: (info: NetworkRequestInfo) => void;
-    onNetworkResponse?: (info: NetworkResponseInfo) => void;
+    /**
+     * Callback invoked when context.newPage() is called from within the isolate.
+     * Host creates/configures the new page. If not provided, newPage() will throw an error.
+     * Receives the BrowserContext so you can call context.newPage().
+     * @param context - The BrowserContext that requested the new page
+     * @returns The new Page object
+     */
+    createPage?: (context: BrowserContext) => Promise<Page> | Page;
+    /**
+     * Callback invoked when browser.newContext() is called from within the isolate.
+     * Host creates/configures the new context. If not provided, newContext() will throw an error.
+     * @param options - Browser context options passed from the isolate
+     * @returns The new BrowserContext object
+     */
+    createContext?: (options?: BrowserContextOptions) => Promise<BrowserContext> | BrowserContext;
 }
 export interface PlaywrightHandle {
     dispose(): void;
@@ -67,13 +77,20 @@ export interface PlaywrightHandle {
  * This handler is called by the daemon (via callback) when sandbox needs page operations.
  * Used for remote runtime where the browser runs on the client.
  */
-export declare function createPlaywrightHandler(page: Page, options?: {
-    timeout?: number;
-}): PlaywrightCallback;
+export declare function createPlaywrightHandler(page: Page, options?: DefaultPlaywrightHandlerOptions): PlaywrightCallback;
+/**
+ * Public helper for handler-first runtime options.
+ * Adds metadata used by adapter layers for local event capture.
+ */
+export declare function defaultPlaywrightHandler(page: Page, options?: DefaultPlaywrightHandlerOptions): PlaywrightCallback;
+/**
+ * Extract metadata from handlers created by defaultPlaywrightHandler().
+ */
+export declare function getDefaultPlaywrightHandlerMetadata(handler: PlaywrightCallback): DefaultPlaywrightHandlerMetadata | undefined;
 /**
  * Set up playwright in an isolate context.
  *
  * For local use: provide `page` option (direct page access)
  * For remote use: provide `handler` option (callback pattern)
  */
-export declare function setupPlaywright(context: ivm.Context, options: PlaywrightSetupOptions | PlaywrightOptions): Promise<PlaywrightHandle>;
+export declare function setupPlaywright(context: ivm.Context, options: PlaywrightSetupOptions): Promise<PlaywrightHandle>;

package/dist/types/types.d.ts

@@ -2,7 +2,7 @@
  * Client-safe types for @ricsam/isolate-playwright
  * This module can be imported without loading isolated-vm
  */
-export type { PlaywrightOperation, PlaywrightResult, PlaywrightEvent, } from "@ricsam/isolate-protocol";
+export type { PlaywrightOperation, PlaywrightResult, PlaywrightEvent, PlaywrightFileData, } from "@ricsam/isolate-protocol";
 export interface NetworkRequestInfo {
     url: string;
     method: string;
@@ -31,6 +31,40 @@ export interface BrowserConsoleLogEntry {
  * Used for remote execution where the page lives on the client.
  */
 export type PlaywrightCallback = (op: import("@ricsam/isolate-protocol").PlaywrightOperation) => Promise<import("@ricsam/isolate-protocol").PlaywrightResult>;
+/**
+ * Symbol key used to attach metadata to handlers created by
+ * defaultPlaywrightHandler(). Enables adapter layers to keep local ergonomics
+ * (event capture, collected data) without exposing page-mode in runtime options.
+ */
+export declare const DEFAULT_PLAYWRIGHT_HANDLER_META: unique symbol;
+/**
+ * Options for defaultPlaywrightHandler(page, options).
+ */
+export interface DefaultPlaywrightHandlerOptions {
+    /** Default timeout for operations */
+    timeout?: number;
+    /** Callback to read files for setInputFiles() with file paths */
+    readFile?: (filePath: string) => Promise<import("@ricsam/isolate-protocol").PlaywrightFileData> | import("@ricsam/isolate-protocol").PlaywrightFileData;
+    /** Callback to write files for screenshot()/pdf() with path option */
+    writeFile?: (filePath: string, data: Buffer) => Promise<void> | void;
+    /** Callback to create new pages when context.newPage() is called */
+    createPage?: (context: import("playwright").BrowserContext) => Promise<import("playwright").Page> | import("playwright").Page;
+    /** Callback to create new contexts when browser.newContext() is called */
+    createContext?: (options?: import("playwright").BrowserContextOptions) => Promise<import("playwright").BrowserContext> | import("playwright").BrowserContext;
+}
+/**
+ * Metadata attached to handlers created by defaultPlaywrightHandler().
+ */
+export interface DefaultPlaywrightHandlerMetadata {
+    page: import("playwright").Page;
+    options?: DefaultPlaywrightHandlerOptions;
+}
+/**
+ * Handler created by defaultPlaywrightHandler().
+ */
+export type DefaultPlaywrightHandler = PlaywrightCallback & {
+    [DEFAULT_PLAYWRIGHT_HANDLER_META]?: DefaultPlaywrightHandlerMetadata;
+};
 /**
  * Options for setting up playwright in an isolate.
  */
@@ -45,15 +79,33 @@ export interface PlaywrightSetupOptions {
     console?: boolean;
     /** Unified event callback for all playwright events */
     onEvent?: (event: import("@ricsam/isolate-protocol").PlaywrightEvent) => void;
-}
-/**
- * @deprecated Use PlaywrightSetupOptions instead
- */
-export interface PlaywrightOptions {
-    page: import("playwright").Page;
-    timeout?: number;
-    onNetworkRequest?: (info: NetworkRequestInfo) => void;
-    onNetworkResponse?: (info: NetworkResponseInfo) => void;
+    /**
+     * Callback to read files for setInputFiles() operations.
+     * This allows the host to control which files the isolate can access.
+     * If not provided, setInputFiles() with file paths will throw an error.
+     */
+    readFile?: (filePath: string) => Promise<import("@ricsam/isolate-protocol").PlaywrightFileData> | import("@ricsam/isolate-protocol").PlaywrightFileData;
+    /**
+     * Callback to write files for screenshot() and pdf() operations with path option.
+     * This allows the host to control where files are written.
+     * If not provided, screenshot()/pdf() with path option will throw an error.
+     */
+    writeFile?: (filePath: string, data: Buffer) => Promise<void> | void;
+    /**
+     * Callback invoked when context.newPage() is called from within the isolate.
+     * Host creates/configures the new page. If not provided, newPage() will throw an error.
+     * Receives the BrowserContext so you can call context.newPage().
+     * @param context - The BrowserContext that requested the new page
+     * @returns The new Page object
+     */
+    createPage?: (context: import("playwright").BrowserContext) => Promise<import("playwright").Page> | import("playwright").Page;
+    /**
+     * Callback invoked when browser.newContext() is called from within the isolate.
+     * Host creates/configures the new context. If not provided, newContext() will throw an error.
+     * @param options - Browser context options passed from the isolate
+     * @returns The new BrowserContext object
+     */
+    createContext?: (options?: import("playwright").BrowserContextOptions) => Promise<import("playwright").BrowserContext> | import("playwright").BrowserContext;
 }
 export interface PlaywrightHandle {
     dispose(): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/isolate-playwright",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "main": "./dist/cjs/index.cjs",
   "types": "./dist/types/index.d.ts",
   "exports": {