@ricsam/isolate 0.0.1 → 0.1.1

package/dist/types/internal/playwright/index.d.ts

@@ -0,0 +1,14 @@
+import ivm from "isolated-vm";
+import { DEFAULT_PLAYWRIGHT_HANDLER_META } from "./types.ts";
+export { createPlaywrightHandler, defaultPlaywrightHandler, getDefaultPlaywrightHandlerMetadata, } from "./handler.ts";
+export type { PlaywrightOperation, PlaywrightResult, PlaywrightEvent, PlaywrightFileData } from "../protocol/index.ts";
+export { DEFAULT_PLAYWRIGHT_HANDLER_META };
+export type { NetworkRequestInfo, NetworkResponseInfo, BrowserConsoleLogEntry, PageErrorInfo, RequestFailureInfo, PlaywrightCallback, PlaywrightSetupOptions, PlaywrightHandle, } from "./types.ts";
+import type { PlaywrightSetupOptions, PlaywrightHandle } from "./types.ts";
+/**
+ * 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): Promise<PlaywrightHandle>;

package/dist/types/internal/playwright/types.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Client-safe types for ./index.ts
+ * This module can be imported without loading isolated-vm
+ */
+export type { PlaywrightOperation, PlaywrightResult, PlaywrightEvent, PlaywrightFileData, } from "../protocol/index.ts";
+export interface NetworkRequestInfo {
+    requestId: string;
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    postData?: string;
+    resourceType: string;
+    timestamp: number;
+}
+export interface NetworkResponseInfo {
+    requestId: string;
+    url: string;
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    resourceType?: string;
+    timestamp: number;
+}
+/**
+ * Browser console log entry - logs from the page context (not sandbox).
+ */
+export interface BrowserConsoleLogEntry {
+    level: string;
+    stdout: string;
+    location?: {
+        url?: string;
+        lineNumber?: number;
+        columnNumber?: number;
+    };
+    timestamp: number;
+}
+export interface PageErrorInfo {
+    name: string;
+    message: string;
+    stack?: string;
+    timestamp: number;
+}
+export interface RequestFailureInfo {
+    requestId: string;
+    url: string;
+    method: string;
+    failureText: string;
+    resourceType?: string;
+    timestamp: number;
+}
+/**
+ * Callback type for handling playwright operations.
+ * Used for remote execution where the page lives on the client.
+ */
+export type PlaywrightCallback = (op: import("../protocol/index.ts").PlaywrightOperation) => Promise<import("../protocol/index.ts").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("../protocol/index.ts").PlaywrightFileData> | import("../protocol/index.ts").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;
+    /** Callback to evaluate a predicate function inside the isolate (used by waitForURL/Request/Response with function predicates) */
+    evaluatePredicate?: (predicateId: number, data: unknown) => boolean;
+}
+/**
+ * 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.
+ */
+export interface PlaywrightSetupOptions {
+    /** Direct page object (for local use) */
+    page?: import("playwright").Page;
+    /** Handler callback (for remote use - daemon invokes this) */
+    handler?: PlaywrightCallback;
+    /** Default timeout for operations */
+    timeout?: number;
+    /** If true, browser console logs are printed to stdout */
+    console?: boolean;
+    /** Unified event callback for all playwright events */
+    onEvent?: (event: import("../protocol/index.ts").PlaywrightEvent) => 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("../protocol/index.ts").PlaywrightFileData> | import("../protocol/index.ts").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;
+    /** Get browser console logs (from the page, not sandbox) */
+    getBrowserConsoleLogs(): BrowserConsoleLogEntry[];
+    /** Get uncaught page errors */
+    getPageErrors(): PageErrorInfo[];
+    getNetworkRequests(): NetworkRequestInfo[];
+    getNetworkResponses(): NetworkResponseInfo[];
+    /** Get network request failures (DNS, abort, connection reset, etc.) */
+    getRequestFailures(): RequestFailureInfo[];
+    clearCollected(): void;
+}

package/dist/types/internal/protocol/codec.d.ts

@@ -0,0 +1,242 @@
+/**
+ * MessagePack codec with custom extension types for the isolate protocol.
+ */
+import type { Message } from "./types.ts";
+/**
+ * Extension type codes for custom data types.
+ */
+export declare const ExtType: {
+    /** Reference to an isolate instance */
+    readonly ISOLATE_REF: 1;
+    /** Reference to a registered callback */
+    readonly CALLBACK_REF: 2;
+    /** Reference to a stream */
+    readonly STREAM_REF: 3;
+    /** Structured error object */
+    readonly ERROR: 4;
+    /** Reference to Blob/File data */
+    readonly BLOB_REF: 5;
+    /** Date value */
+    readonly DATE: 6;
+    /** RegExp value */
+    readonly REGEXP: 7;
+    /** Undefined value (null is natively supported) */
+    readonly UNDEFINED: 8;
+    /** BigInt value */
+    readonly BIGINT: 9;
+    /** Request object */
+    readonly REQUEST: 10;
+    /** Response object */
+    readonly RESPONSE: 11;
+    /** Headers object */
+    readonly HEADERS: 12;
+    /** File object */
+    readonly FILE: 13;
+    /** FormData object */
+    readonly FORMDATA: 14;
+    /** URL object */
+    readonly URL_REF: 15;
+    /** Promise reference */
+    readonly PROMISE: 16;
+    /** AsyncIterator reference */
+    readonly ASYNC_ITERATOR: 17;
+};
+export type ExtType = (typeof ExtType)[keyof typeof ExtType];
+/**
+ * Represents a reference to an isolate.
+ */
+export interface IsolateRef {
+    __type: "IsolateRef";
+    isolateId: string;
+}
+/**
+ * Represents a reference to a callback.
+ */
+export interface CallbackRef {
+    __type: "CallbackRef";
+    callbackId: number;
+}
+/**
+ * Represents a reference to a stream.
+ */
+export interface StreamRef {
+    __type: "StreamRef";
+    streamId: number;
+    direction: "upload" | "download";
+}
+/**
+ * Represents a structured error.
+ */
+export interface ErrorRef {
+    __type: "ErrorRef";
+    name: string;
+    message: string;
+    stack?: string;
+    code?: number;
+}
+/**
+ * Represents a reference to blob data.
+ */
+export interface BlobRef {
+    __type: "BlobRef";
+    blobId: number;
+    size: number;
+    type: string;
+}
+/**
+ * Represents a serialized Date value.
+ */
+export interface DateRef {
+    __type: "DateRef";
+    timestamp: number;
+}
+/**
+ * Represents a serialized RegExp value.
+ */
+export interface RegExpRef {
+    __type: "RegExpRef";
+    source: string;
+    flags: string;
+}
+/**
+ * Represents an undefined value (since msgpack doesn't natively support undefined).
+ */
+export interface UndefinedRef {
+    __type: "UndefinedRef";
+}
+/**
+ * Represents a serialized BigInt value.
+ */
+export interface BigIntRef {
+    __type: "BigIntRef";
+    value: string;
+}
+/**
+ * Represents a serialized Uint8Array value.
+ * Uses number[] instead of Uint8Array for JSON compatibility.
+ */
+export interface Uint8ArrayRef {
+    __type: "Uint8ArrayRef";
+    data: number[];
+}
+/**
+ * Represents a serialized Request object.
+ * Uses number[] instead of Uint8Array for JSON compatibility.
+ */
+export interface RequestRef {
+    __type: "RequestRef";
+    url: string;
+    method: string;
+    headers: [string, string][];
+    body: number[] | null;
+    mode?: string;
+    credentials?: string;
+    cache?: string;
+    redirect?: string;
+    referrer?: string;
+    referrerPolicy?: string;
+    integrity?: string;
+}
+/**
+ * Represents a serialized Response object.
+ * Uses number[] instead of Uint8Array for JSON compatibility.
+ */
+export interface ResponseRef {
+    __type: "ResponseRef";
+    status: number;
+    statusText: string;
+    headers: [string, string][];
+    body: number[] | null;
+}
+/**
+ * Represents a serialized Headers object.
+ */
+export interface HeadersRef {
+    __type: "HeadersRef";
+    pairs: [string, string][];
+}
+/**
+ * Represents a serialized File object (includes the data inline).
+ * Uses number[] instead of Uint8Array for JSON compatibility.
+ */
+export interface FileRef {
+    __type: "FileRef";
+    name: string;
+    type: string;
+    lastModified: number;
+    data: number[];
+}
+/**
+ * Represents a serialized FormData object.
+ */
+export interface FormDataRef {
+    __type: "FormDataRef";
+    entries: [string, string | FileRef][];
+}
+/**
+ * Represents a serialized URL object.
+ */
+export interface URLRef {
+    __type: "URLRef";
+    href: string;
+}
+/**
+ * Represents a reference to a pending Promise.
+ */
+export interface PromiseRef {
+    __type: "PromiseRef";
+    promiseId: number;
+}
+/**
+ * Represents a reference to an async iterator.
+ */
+export interface AsyncIteratorRef {
+    __type: "AsyncIteratorRef";
+    iteratorId: number;
+    __nextCallbackId?: number;
+    __returnCallbackId?: number;
+    __throwCallbackId?: number;
+}
+export type ExtensionType = IsolateRef | CallbackRef | StreamRef | ErrorRef | BlobRef | DateRef | RegExpRef | UndefinedRef | BigIntRef | RequestRef | ResponseRef | HeadersRef | FileRef | FormDataRef | URLRef | PromiseRef | AsyncIteratorRef;
+/**
+ * Encode a message to MessagePack bytes.
+ */
+export declare function encodeMessage(message: Message): Uint8Array;
+/**
+ * Decode MessagePack bytes to a message.
+ */
+export declare function decodeMessage(data: Uint8Array): Message;
+/**
+ * Encode any value to MessagePack bytes.
+ */
+export declare function encodeValue(value: unknown): Uint8Array;
+/**
+ * Decode MessagePack bytes to any value.
+ */
+export declare function decodeValue(data: Uint8Array): unknown;
+export declare function createIsolateRef(isolateId: string): IsolateRef;
+export declare function createCallbackRef(callbackId: number): CallbackRef;
+export declare function createStreamRef(streamId: number, direction: "upload" | "download"): StreamRef;
+export declare function createErrorRef(name: string, message: string, stack?: string, code?: number): ErrorRef;
+export declare function createBlobRef(blobId: number, size: number, type: string): BlobRef;
+export declare function createDateRef(timestamp: number): DateRef;
+export declare function createRegExpRef(source: string, flags: string): RegExpRef;
+export declare function createUndefinedRef(): UndefinedRef;
+export declare function createBigIntRef(value: string): BigIntRef;
+export declare function createUint8ArrayRef(data: number[]): Uint8ArrayRef;
+export declare function createRequestRef(url: string, method: string, headers: [string, string][], body: number[] | null, options?: {
+    mode?: string;
+    credentials?: string;
+    cache?: string;
+    redirect?: string;
+    referrer?: string;
+    referrerPolicy?: string;
+    integrity?: string;
+}): RequestRef;
+export declare function createResponseRef(status: number, statusText: string, headers: [string, string][], body: number[] | null): ResponseRef;
+export declare function createHeadersRef(pairs: [string, string][]): HeadersRef;
+export declare function createFileRef(name: string, type: string, lastModified: number, data: number[]): FileRef;
+export declare function createFormDataRef(entries: [string, string | FileRef][]): FormDataRef;
+export declare function createURLRef(href: string): URLRef;
+export declare function createPromiseRef(promiseId: number): PromiseRef;
+export declare function createAsyncIteratorRef(iteratorId: number): AsyncIteratorRef;

package/dist/types/internal/protocol/framing.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Frame parser and builder for the isolate protocol.
+ *
+ * Frame format:
+ * ┌──────────┬──────────┬─────────────────┐
+ * │ Length   │ Type     │ Payload         │
+ * │ (4 bytes)│ (1 byte) │ (MessagePack)   │
+ * └──────────┴──────────┴─────────────────┘
+ *
+ * - Length: uint32 BE, size of Type + Payload (excludes the length field itself)
+ * - Type: uint8, message type from MessageType enum
+ * - Payload: MessagePack encoded message body
+ */
+import { MessageType, type Message } from "./types.ts";
+/** Header size: 4 bytes for length + 1 byte for type */
+export declare const HEADER_SIZE = 5;
+/** Maximum frame size (10MB) */
+export declare const MAX_FRAME_SIZE: number;
+/** Threshold above which bodies should be streamed (1MB) */
+export declare const STREAM_THRESHOLD: number;
+/** Default chunk size for streaming (256KB) */
+export declare const STREAM_CHUNK_SIZE: number;
+/** Default credit for backpressure (1MB) */
+export declare const STREAM_DEFAULT_CREDIT: number;
+/**
+ * Build a frame from a message.
+ *
+ * @param message - The message to encode
+ * @returns Complete frame as Uint8Array
+ */
+export declare function buildFrame(message: Message): Uint8Array;
+/**
+ * Build multiple frames from messages.
+ *
+ * @param messages - Messages to encode
+ * @returns Combined frames as single Uint8Array
+ */
+export declare function buildFrames(messages: Message[]): Uint8Array;
+/**
+ * Parse result from the frame parser.
+ */
+export interface ParsedFrame {
+    type: MessageType;
+    message: Message;
+}
+/**
+ * Incremental frame parser for streaming data.
+ *
+ * Usage:
+ * ```ts
+ * const parser = createFrameParser();
+ * socket.on('data', (chunk) => {
+ *   for (const frame of parser.feed(chunk)) {
+ *     handleMessage(frame.message);
+ *   }
+ * });
+ * ```
+ */
+export interface FrameParser {
+    /**
+     * Feed data to the parser and yield complete frames.
+     * @param chunk - Incoming data chunk
+     */
+    feed(chunk: Uint8Array): Generator<ParsedFrame>;
+    /**
+     * Get the number of bytes currently buffered.
+     */
+    bufferedBytes(): number;
+    /**
+     * Reset the parser state.
+     */
+    reset(): void;
+}
+/**
+ * Create a new frame parser.
+ */
+export declare function createFrameParser(): FrameParser;
+/**
+ * Parse a single complete frame.
+ *
+ * @param data - Complete frame data
+ * @returns Parsed frame or null if incomplete
+ * @throws Error if frame is invalid
+ */
+export declare function parseFrame(data: Uint8Array): ParsedFrame | null;
+/**
+ * Get the message type name for debugging.
+ */
+export declare function getMessageTypeName(type: MessageType): string;

package/dist/types/internal/protocol/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * ./index.ts
+ *
+ * Protocol definitions, codec, and framing for the isolate daemon.
+ */
+export * from "./types.ts";
+export { encodeMessage, decodeMessage, encodeValue, decodeValue, createIsolateRef, createCallbackRef, createStreamRef, createErrorRef, createBlobRef, createDateRef, createRegExpRef, createUndefinedRef, createBigIntRef, createRequestRef, createResponseRef, createHeadersRef, createFileRef, createFormDataRef, createURLRef, createPromiseRef, createAsyncIteratorRef, ExtType, type IsolateRef, type CallbackRef, type StreamRef, type ErrorRef, type BlobRef, type DateRef, type RegExpRef, type UndefinedRef, type BigIntRef, type RequestRef, type ResponseRef, type HeadersRef, type FileRef, type FormDataRef, type URLRef, type PromiseRef, type AsyncIteratorRef, type ExtensionType, } from "./codec.ts";
+export { marshalValue, marshalValueSync, unmarshalValue, MarshalError, isPromiseRef, isAsyncIteratorRef, type MarshalContext, type UnmarshalContext, } from "./marshalValue.ts";
+export { serializeRequest, serializeResponse, deserializeRequest, deserializeResponse, } from "./serialization.ts";
+export { buildFrame, buildFrames, createFrameParser, parseFrame, getMessageTypeName, HEADER_SIZE, MAX_FRAME_SIZE, STREAM_THRESHOLD, STREAM_CHUNK_SIZE, STREAM_DEFAULT_CREDIT, type ParsedFrame, type FrameParser, } from "./framing.ts";

package/dist/types/internal/protocol/marshalValue.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Value marshalling for custom function arguments and return values.
+ *
+ * Provides type-preserving serialization for JavaScript types that would
+ * otherwise lose fidelity when JSON stringified.
+ */
+/**
+ * Error thrown when a value cannot be marshalled.
+ */
+export declare class MarshalError extends Error {
+    constructor(message: string);
+}
+/**
+ * Context for marshalling values (host → isolate).
+ */
+export interface MarshalContext {
+    /** Register a function callback and return its ID */
+    registerCallback?: (fn: Function) => number;
+    /** Register a Promise and return its ID */
+    registerPromise?: (promise: Promise<unknown>) => number;
+    /** Register an AsyncIterator and return its ID */
+    registerIterator?: (iterator: AsyncIterator<unknown>) => number;
+    /** Register a Blob and return its ID */
+    registerBlob?: (blob: Blob) => number;
+}
+/**
+ * Context for unmarshalling values (isolate → host).
+ */
+export interface UnmarshalContext {
+    /** Get a callback function by ID */
+    getCallback?: (id: number) => ((...args: unknown[]) => unknown) | undefined;
+    /** Create a proxy Promise for a PromiseRef */
+    createPromiseProxy?: (promiseId: number) => Promise<unknown>;
+    /** Create a proxy AsyncIterator for an AsyncIteratorRef */
+    createIteratorProxy?: (iteratorId: number) => AsyncIterator<unknown>;
+    /** Get a Blob by ID */
+    getBlob?: (blobId: number) => Blob | undefined;
+}
+/**
+ * Type guard for PromiseRef values.
+ */
+export declare function isPromiseRef(value: unknown): value is {
+    __type: "PromiseRef";
+    promiseId: number;
+};
+/**
+ * Type guard for AsyncIteratorRef values.
+ */
+export declare function isAsyncIteratorRef(value: unknown): value is {
+    __type: "AsyncIteratorRef";
+    iteratorId: number;
+};
+/**
+ * Marshal a JavaScript value to a serializable format.
+ *
+ * Converts JavaScript types that lose fidelity when JSON stringified into
+ * Ref objects that can be reconstructed on the other side.
+ *
+ * @param value - The value to marshal
+ * @param ctx - Optional context for registering callbacks, promises, etc.
+ * @param depth - Current recursion depth (used for circular reference detection)
+ * @param seen - WeakSet of seen objects (for circular reference detection)
+ * @returns The marshalled value (may be async for Request/Response/File/Blob/FormData)
+ */
+export declare function marshalValue(value: unknown, ctx?: MarshalContext, depth?: number, seen?: WeakSet<object>): Promise<unknown>;
+/**
+ * Synchronous marshal for values that don't require async operations.
+ * Throws if the value contains Request, Response, File, Blob, or FormData.
+ */
+export declare function marshalValueSync(value: unknown, ctx?: MarshalContext, depth?: number, seen?: WeakSet<object>): unknown;
+/**
+ * Unmarshal a serialized value back to JavaScript types.
+ *
+ * @param value - The value to unmarshal
+ * @param ctx - Optional context for resolving callbacks, promises, etc.
+ * @param depth - Current recursion depth
+ * @returns The unmarshalled JavaScript value
+ */
+export declare function unmarshalValue(value: unknown, ctx?: UnmarshalContext, depth?: number): unknown;

package/dist/types/internal/protocol/serialization.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Request/Response serialization utilities.
+ *
+ * Shared by both isolate-daemon and isolate-client for converting
+ * between Web API Request/Response objects and serializable data.
+ */
+import type { SerializedRequest, SerializedResponse } from "./types.ts";
+/**
+ * Serialize a Request to a plain object for transmission over IPC.
+ */
+export declare function serializeRequest(request: Request): Promise<SerializedRequest>;
+/**
+ * Serialize a Response to a plain object for transmission over IPC.
+ */
+export declare function serializeResponse(response: Response): Promise<SerializedResponse>;
+/**
+ * Deserialize a plain object back into a Request.
+ */
+export declare function deserializeRequest(data: SerializedRequest): Request;
+/**
+ * Deserialize a plain object back into a Response.
+ */
+export declare function deserializeResponse(data: SerializedResponse): Response;