@ricsam/isolate 0.0.1 → 0.1.1

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

@@ -0,0 +1,996 @@
+/**
+ * Message types for the isolate daemon protocol.
+ *
+ * Frame format:
+ * ┌──────────┬──────────┬─────────────────┐
+ * │ Length   │ Type     │ Payload         │
+ * │ (4 bytes)│ (1 byte) │ (MessagePack)   │
+ * └──────────┴──────────┴─────────────────┘
+ */
+export declare const MessageType: {
+    readonly CREATE_RUNTIME: 1;
+    readonly DISPOSE_RUNTIME: 2;
+    readonly EVAL: 3;
+    readonly DISPATCH_REQUEST: 4;
+    readonly DISPATCH_REQUEST_ABORT: 5;
+    readonly WS_OPEN: 16;
+    readonly WS_MESSAGE: 17;
+    readonly WS_CLOSE: 18;
+    readonly FETCH_GET_UPGRADE_REQUEST: 19;
+    readonly FETCH_HAS_SERVE_HANDLER: 20;
+    readonly FETCH_HAS_ACTIVE_CONNECTIONS: 21;
+    readonly FETCH_WS_ERROR: 22;
+    readonly TIMERS_CLEAR_ALL: 23;
+    readonly CONSOLE_RESET: 24;
+    readonly CONSOLE_GET_TIMERS: 25;
+    readonly CONSOLE_GET_COUNTERS: 26;
+    readonly CONSOLE_GET_GROUP_DEPTH: 27;
+    readonly RUN_TESTS: 33;
+    readonly RESET_TEST_ENV: 34;
+    readonly HAS_TESTS: 35;
+    readonly GET_TEST_COUNT: 36;
+    readonly GET_COLLECTED_DATA: 51;
+    readonly CLEAR_COLLECTED_DATA: 52;
+    readonly RESPONSE_OK: 128;
+    readonly RESPONSE_ERROR: 129;
+    readonly RESPONSE_STREAM_START: 130;
+    readonly RESPONSE_STREAM_CHUNK: 131;
+    readonly RESPONSE_STREAM_END: 132;
+    readonly CALLBACK_INVOKE: 144;
+    readonly CALLBACK_RESPONSE: 145;
+    readonly CALLBACK_STREAM_START: 146;
+    readonly CALLBACK_STREAM_CHUNK: 147;
+    readonly CALLBACK_STREAM_END: 148;
+    readonly CALLBACK_STREAM_CANCEL: 149;
+    readonly CALLBACK_ABORT: 150;
+    readonly STREAM_PUSH: 160;
+    readonly STREAM_PULL: 161;
+    readonly STREAM_CLOSE: 162;
+    readonly STREAM_ERROR: 163;
+    readonly ISOLATE_EVENT: 192;
+    readonly CLIENT_EVENT: 193;
+    readonly PING: 240;
+    readonly PONG: 241;
+};
+export type MessageType = (typeof MessageType)[keyof typeof MessageType];
+/** Reverse lookup for message type names */
+export declare const MessageTypeName: Record<number, string>;
+export declare const ErrorCode: {
+    readonly INVALID_MESSAGE: 1001;
+    readonly UNKNOWN_MESSAGE_TYPE: 1002;
+    readonly MISSING_REQUIRED_FIELD: 1003;
+    readonly ISOLATE_NOT_FOUND: 2001;
+    readonly ISOLATE_DISPOSED: 2002;
+    readonly ISOLATE_MEMORY_LIMIT: 2003;
+    readonly ISOLATE_TIMEOUT: 2004;
+    readonly SCRIPT_ERROR: 3001;
+    readonly CALLBACK_ERROR: 3002;
+    readonly STREAM_NOT_FOUND: 4001;
+    readonly STREAM_CLOSED: 4002;
+    readonly CONNECTION_LOST: 5001;
+};
+export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+export interface BaseMessage {
+    /** Unique request ID for correlation */
+    requestId: number;
+}
+/** Custom function type indicator */
+export type CustomFunctionType = 'sync' | 'async' | 'asyncIterator';
+export interface CallbackRegistration {
+    /** Unique ID for this callback */
+    callbackId: number;
+    /** Callback name (e.g., "log", "warn", "fetch") */
+    name: string;
+    /** Function type: sync, async, or asyncIterator */
+    type: CustomFunctionType;
+}
+export interface ConsoleCallbackRegistrations {
+    onEntry?: CallbackRegistration;
+}
+export interface FsCallbackRegistrations {
+    readFile?: CallbackRegistration;
+    writeFile?: CallbackRegistration;
+    unlink?: CallbackRegistration;
+    readdir?: CallbackRegistration;
+    mkdir?: CallbackRegistration;
+    rmdir?: CallbackRegistration;
+    stat?: CallbackRegistration;
+    rename?: CallbackRegistration;
+}
+export interface CustomFunctionRegistrations {
+    [name: string]: CallbackRegistration;
+}
+/**
+ * Playwright operation sent from daemon to client via callback.
+ * The client executes this operation on the real Page object.
+ */
+export interface PlaywrightOperation {
+    type: "goto" | "reload" | "url" | "title" | "content" | "waitForSelector" | "waitForTimeout" | "waitForLoadState" | "evaluate" | "locatorAction" | "expectLocator" | "expectPage" | "request" | "goBack" | "goForward" | "waitForURL" | "waitForURLPredicate" | "waitForRequestStart" | "waitForRequestFinish" | "waitForRequestPredicateFinish" | "waitForResponseStart" | "waitForResponseFinish" | "waitForResponsePredicateFinish" | "clearCookies" | "screenshot" | "setViewportSize" | "viewportSize" | "emulateMedia" | "setExtraHTTPHeaders" | "bringToFront" | "close" | "isClosed" | "pdf" | "pause" | "frames" | "mainFrame" | "keyboardType" | "keyboardPress" | "keyboardDown" | "keyboardUp" | "keyboardInsertText" | "mouseMove" | "mouseClick" | "mouseDown" | "mouseUp" | "mouseWheel" | "addCookies" | "cookies" | "newContext" | "newPage" | "closeContext";
+    args: unknown[];
+    /** Target page ID (undefined = default page "page_0") */
+    pageId?: string;
+    /** Target context ID (undefined = default context "ctx_0") */
+    contextId?: string;
+}
+/**
+ * Result of a playwright operation.
+ */
+export type PlaywrightResult = {
+    ok: true;
+    value?: unknown;
+} | {
+    ok: false;
+    error: {
+        name: string;
+        message: string;
+    };
+};
+/**
+ * Callback registrations for playwright operations.
+ */
+export interface PlaywrightCallbackRegistration {
+    /** Callback ID for page operations */
+    handlerCallbackId: number;
+    /** If true, browser console logs are printed to stdout */
+    console?: boolean;
+    /** Optional callback for browser console log events (from the page, not sandbox) */
+    onBrowserConsoleLogCallbackId?: number;
+    /** Optional callback for network request events */
+    onNetworkRequestCallbackId?: number;
+    /** Optional callback for network response events */
+    onNetworkResponseCallbackId?: number;
+}
+export interface RuntimeCallbackRegistrations {
+    console?: ConsoleCallbackRegistrations;
+    fetch?: CallbackRegistration;
+    fs?: FsCallbackRegistrations;
+    moduleLoader?: CallbackRegistration;
+    custom?: CustomFunctionRegistrations;
+    playwright?: PlaywrightCallbackRegistration;
+}
+export interface TestEnvironmentCallbackRegistrations {
+    /** Callback for test events */
+    onEvent?: CallbackRegistration;
+}
+export interface TestEnvironmentOptionsProtocol {
+    /** Callback registrations for test events */
+    callbacks?: TestEnvironmentCallbackRegistrations;
+    /** Timeout for individual tests (ms) */
+    testTimeout?: number;
+}
+export interface PlaywrightOptionsProtocol {
+    /** Default timeout for Playwright operations in ms */
+    timeout?: number;
+}
+export interface CreateRuntimeRequest extends BaseMessage {
+    type: typeof MessageType.CREATE_RUNTIME;
+    options: {
+        memoryLimitMB?: number;
+        executionTimeout?: number;
+        callbacks?: RuntimeCallbackRegistrations;
+        /** Current working directory for path.resolve(). Defaults to "/" */
+        cwd?: string;
+        /** Enable test environment (describe, it, expect, etc.) */
+        testEnvironment?: boolean | TestEnvironmentOptionsProtocol;
+        /** Playwright runtime options */
+        playwright?: PlaywrightOptionsProtocol;
+        /** Namespace ID for runtime pooling/reuse. If provided, runtime will be cached on dispose. */
+        namespaceId?: string;
+    };
+}
+export interface DisposeRuntimeRequest extends BaseMessage {
+    type: typeof MessageType.DISPOSE_RUNTIME;
+    isolateId: string;
+    /** When true, permanently delete the runtime instead of soft-deleting namespaced runtimes. */
+    hard?: boolean;
+    /** Optional caller-supplied reason for disposal, used for diagnostics/logging. */
+    reason?: string;
+}
+export interface EvalRequest extends BaseMessage {
+    type: typeof MessageType.EVAL;
+    isolateId: string;
+    code: string;
+    filename?: string;
+    executionTimeout?: number;
+}
+export interface SerializedRequest {
+    method: string;
+    url: string;
+    headers: [string, string][];
+    /** Inline body for small payloads */
+    body?: Uint8Array | null;
+    /** Stream reference for large/streaming bodies */
+    bodyStreamId?: number;
+    /** Whether the request signal was already aborted when serialized */
+    signalAborted?: boolean;
+}
+export interface DispatchRequestRequest extends BaseMessage {
+    type: typeof MessageType.DISPATCH_REQUEST;
+    isolateId: string;
+    request: SerializedRequest;
+    context?: {
+        requestId?: string;
+        metadata?: Record<string, string>;
+    };
+}
+/**
+ * Abort an in-flight DISPATCH_REQUEST.
+ * This is fire-and-forget and does not produce a response.
+ */
+export interface DispatchRequestAbort {
+    type: typeof MessageType.DISPATCH_REQUEST_ABORT;
+    isolateId: string;
+    /** requestId of the corresponding DISPATCH_REQUEST */
+    targetRequestId: number;
+}
+export interface WsOpenRequest extends BaseMessage {
+    type: typeof MessageType.WS_OPEN;
+    isolateId: string;
+    connectionId: string;
+}
+export interface WsMessageRequest extends BaseMessage {
+    type: typeof MessageType.WS_MESSAGE;
+    isolateId: string;
+    connectionId: string;
+    data: string | Uint8Array;
+}
+export interface WsCloseRequest extends BaseMessage {
+    type: typeof MessageType.WS_CLOSE;
+    isolateId: string;
+    connectionId: string;
+    code: number;
+    reason: string;
+}
+export interface FetchGetUpgradeRequestRequest extends BaseMessage {
+    type: typeof MessageType.FETCH_GET_UPGRADE_REQUEST;
+    isolateId: string;
+}
+export interface FetchHasServeHandlerRequest extends BaseMessage {
+    type: typeof MessageType.FETCH_HAS_SERVE_HANDLER;
+    isolateId: string;
+}
+export interface FetchHasActiveConnectionsRequest extends BaseMessage {
+    type: typeof MessageType.FETCH_HAS_ACTIVE_CONNECTIONS;
+    isolateId: string;
+}
+export interface FetchWsErrorRequest extends BaseMessage {
+    type: typeof MessageType.FETCH_WS_ERROR;
+    isolateId: string;
+    connectionId: string;
+    error: string;
+}
+export interface TimersClearAllRequest extends BaseMessage {
+    type: typeof MessageType.TIMERS_CLEAR_ALL;
+    isolateId: string;
+}
+export interface ConsoleResetRequest extends BaseMessage {
+    type: typeof MessageType.CONSOLE_RESET;
+    isolateId: string;
+}
+export interface ConsoleGetTimersRequest extends BaseMessage {
+    type: typeof MessageType.CONSOLE_GET_TIMERS;
+    isolateId: string;
+}
+export interface ConsoleGetCountersRequest extends BaseMessage {
+    type: typeof MessageType.CONSOLE_GET_COUNTERS;
+    isolateId: string;
+}
+export interface ConsoleGetGroupDepthRequest extends BaseMessage {
+    type: typeof MessageType.CONSOLE_GET_GROUP_DEPTH;
+    isolateId: string;
+}
+export interface RunTestsRequest extends BaseMessage {
+    type: typeof MessageType.RUN_TESTS;
+    isolateId: string;
+    timeout?: number;
+}
+export interface ResetTestEnvRequest extends BaseMessage {
+    type: typeof MessageType.RESET_TEST_ENV;
+    isolateId: string;
+}
+export interface HasTestsRequest extends BaseMessage {
+    type: typeof MessageType.HAS_TESTS;
+    isolateId: string;
+}
+export interface GetTestCountRequest extends BaseMessage {
+    type: typeof MessageType.GET_TEST_COUNT;
+    isolateId: string;
+}
+export interface GetCollectedDataRequest extends BaseMessage {
+    type: typeof MessageType.GET_COLLECTED_DATA;
+    isolateId: string;
+}
+export interface ClearCollectedDataRequest extends BaseMessage {
+    type: typeof MessageType.CLEAR_COLLECTED_DATA;
+    isolateId: string;
+}
+export interface ResponseOk extends BaseMessage {
+    type: typeof MessageType.RESPONSE_OK;
+    data?: unknown;
+}
+export interface ResponseError extends BaseMessage {
+    type: typeof MessageType.RESPONSE_ERROR;
+    code: ErrorCode;
+    message: string;
+    details?: {
+        name: string;
+        stack?: string;
+        cause?: unknown;
+    };
+}
+export interface SerializedResponse {
+    status: number;
+    statusText: string;
+    headers: [string, string][];
+    /** Inline body for small payloads */
+    body?: Uint8Array | null;
+    /** Stream reference for large/streaming bodies */
+    bodyStreamId?: number;
+}
+export interface ResponseStreamStart extends BaseMessage {
+    type: typeof MessageType.RESPONSE_STREAM_START;
+    streamId: number;
+    metadata?: {
+        status?: number;
+        statusText?: string;
+        headers?: [string, string][];
+    };
+}
+export interface ResponseStreamChunk extends BaseMessage {
+    type: typeof MessageType.RESPONSE_STREAM_CHUNK;
+    streamId: number;
+    chunk: Uint8Array;
+}
+export interface ResponseStreamEnd extends BaseMessage {
+    type: typeof MessageType.RESPONSE_STREAM_END;
+    streamId: number;
+}
+export interface CallbackInvoke extends BaseMessage {
+    type: typeof MessageType.CALLBACK_INVOKE;
+    callbackId: number;
+    args: unknown[];
+    context?: {
+        requestId?: string;
+        metadata?: Record<string, string>;
+    };
+}
+export interface CallbackResponseMsg extends BaseMessage {
+    type: typeof MessageType.CALLBACK_RESPONSE;
+    result?: unknown;
+    error?: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+}
+/**
+ * Start a streaming callback response (client → daemon).
+ * Used when the callback returns a Response with a streaming body.
+ */
+export interface CallbackStreamStart extends BaseMessage {
+    type: typeof MessageType.CALLBACK_STREAM_START;
+    /** The stream ID for correlating chunks */
+    streamId: number;
+    /** Response metadata */
+    metadata: {
+        status: number;
+        statusText: string;
+        headers: [string, string][];
+        /** Response URL (for network responses) */
+        url?: string;
+    };
+}
+/**
+ * A chunk of streaming callback response data (client → daemon).
+ */
+export interface CallbackStreamChunk extends BaseMessage {
+    type: typeof MessageType.CALLBACK_STREAM_CHUNK;
+    /** The stream ID for correlation */
+    streamId: number;
+    /** The chunk data */
+    chunk: Uint8Array;
+}
+/**
+ * End of a streaming callback response (client → daemon).
+ */
+export interface CallbackStreamEnd extends BaseMessage {
+    type: typeof MessageType.CALLBACK_STREAM_END;
+    /** The stream ID for correlation */
+    streamId: number;
+}
+/**
+ * Cancel a streaming callback response (daemon → client).
+ * Tells the client to stop reading the response body.
+ */
+export interface CallbackStreamCancel {
+    type: typeof MessageType.CALLBACK_STREAM_CANCEL;
+    /** The stream ID to cancel */
+    streamId: number;
+}
+/**
+ * Abort an in-flight callback invocation (daemon → client).
+ * Tells the client to cancel the callback identified by targetRequestId.
+ */
+export interface CallbackAbort extends BaseMessage {
+    type: typeof MessageType.CALLBACK_ABORT;
+    /** requestId of the corresponding CALLBACK_INVOKE */
+    targetRequestId: number;
+    /** Optional reason for observability/debugging */
+    reason?: string;
+}
+export interface StreamPush {
+    type: typeof MessageType.STREAM_PUSH;
+    streamId: number;
+    chunk: Uint8Array;
+}
+export interface StreamPull {
+    type: typeof MessageType.STREAM_PULL;
+    streamId: number;
+    maxBytes: number;
+}
+export interface StreamClose {
+    type: typeof MessageType.STREAM_CLOSE;
+    streamId: number;
+}
+export interface StreamError {
+    type: typeof MessageType.STREAM_ERROR;
+    streamId: number;
+    error: string;
+}
+/** Event name constants for isolate → client events */
+export declare const IsolateEvents: {
+    readonly WS_COMMAND: "ws:command";
+    readonly WS_CLIENT_CONNECT: "ws:client-connect";
+    readonly WS_CLIENT_SEND: "ws:client-send";
+    readonly WS_CLIENT_CLOSE: "ws:client-close";
+};
+/** Event name constants for client → daemon events */
+export declare const ClientEvents: {
+    readonly WS_CLIENT_OPENED: "ws:client-opened";
+    readonly WS_CLIENT_MESSAGE: "ws:client-message";
+    readonly WS_CLIENT_CLOSED: "ws:client-closed";
+    readonly WS_CLIENT_ERROR: "ws:client-error";
+};
+/** Generic event from daemon to client */
+export interface IsolateEventMessage {
+    type: typeof MessageType.ISOLATE_EVENT;
+    isolateId: string;
+    event: string;
+    payload: unknown;
+}
+/** Generic event from client to daemon */
+export interface ClientEventMessage {
+    type: typeof MessageType.CLIENT_EVENT;
+    isolateId: string;
+    event: string;
+    payload: unknown;
+}
+export interface WsCommandPayload {
+    type: "message" | "close";
+    connectionId: string;
+    data?: string | Uint8Array;
+    code?: number;
+    reason?: string;
+}
+export interface WsClientConnectPayload {
+    socketId: string;
+    url: string;
+    protocols?: string[];
+}
+export interface WsClientSendPayload {
+    socketId: string;
+    data: string | Uint8Array;
+}
+export interface WsClientClosePayload {
+    socketId: string;
+    code?: number;
+    reason?: string;
+}
+export interface WsClientOpenedPayload {
+    socketId: string;
+    protocol: string;
+    extensions: string;
+}
+export interface WsClientMessagePayload {
+    socketId: string;
+    data: string | Uint8Array;
+}
+export interface WsClientClosedPayload {
+    socketId: string;
+    code: number;
+    reason: string;
+    wasClean: boolean;
+}
+export interface WsClientErrorPayload {
+    socketId: string;
+}
+/**
+ * Unified playwright event type for the onEvent callback.
+ */
+export type PlaywrightEvent = {
+    type: "browserConsoleLog";
+    level: string;
+    stdout: string;
+    location?: {
+        url?: string;
+        lineNumber?: number;
+        columnNumber?: number;
+    };
+    timestamp: number;
+} | {
+    type: "pageError";
+    name: string;
+    message: string;
+    stack?: string;
+    timestamp: number;
+} | {
+    type: "networkRequest";
+    requestId: string;
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    postData?: string;
+    resourceType?: string;
+    timestamp: number;
+} | {
+    type: "networkResponse";
+    requestId: string;
+    url: string;
+    status: number;
+    statusText?: string;
+    headers: Record<string, string>;
+    resourceType?: string;
+    timestamp: number;
+} | {
+    type: "requestFailure";
+    requestId: string;
+    url: string;
+    method: string;
+    failureText: string;
+    resourceType?: string;
+    timestamp: number;
+};
+export interface PingMessage {
+    type: typeof MessageType.PING;
+}
+export interface PongMessage {
+    type: typeof MessageType.PONG;
+}
+export type ClientMessage = CreateRuntimeRequest | DisposeRuntimeRequest | EvalRequest | DispatchRequestRequest | DispatchRequestAbort | WsOpenRequest | WsMessageRequest | WsCloseRequest | FetchGetUpgradeRequestRequest | FetchHasServeHandlerRequest | FetchHasActiveConnectionsRequest | FetchWsErrorRequest | TimersClearAllRequest | ConsoleResetRequest | ConsoleGetTimersRequest | ConsoleGetCountersRequest | ConsoleGetGroupDepthRequest | RunTestsRequest | ResetTestEnvRequest | HasTestsRequest | GetTestCountRequest | GetCollectedDataRequest | ClearCollectedDataRequest | CallbackResponseMsg | CallbackStreamStart | CallbackStreamChunk | CallbackStreamEnd | CallbackStreamCancel | StreamPush | StreamPull | StreamClose | StreamError | ClientEventMessage | PingMessage;
+export type DaemonMessage = ResponseOk | ResponseError | ResponseStreamStart | ResponseStreamChunk | ResponseStreamEnd | CallbackInvoke | CallbackAbort | StreamPush | StreamPull | StreamClose | StreamError | IsolateEventMessage | PongMessage;
+export type Message = ClientMessage | DaemonMessage;
+/**
+ * Module loader callback type.
+ * Called when the isolate imports a module dynamically.
+ *
+ * @param moduleName - The module specifier being imported
+ * @param importer - Information about the importing module
+ * @param importer.path - The resolved path of the importing module
+ * @param importer.resolveDir - The directory to resolve relative imports from
+ * @returns Object with code and resolveDir for the resolved module
+ */
+export type ModuleLoaderCallback = (moduleName: string, importer: {
+    path: string;
+    resolveDir: string;
+}) => ModuleLoaderResult | Promise<ModuleLoaderResult>;
+export interface ModuleLoaderResult {
+    code: string;
+    /** The filename for this module (basename only, no slashes). Combined with resolveDir to form the full path. */
+    filename: string;
+    resolveDir: string;
+    /** Mark as static to preserve across namespace reuse (e.g. node_modules).
+     *  Static modules and their transitive deps should all be static. */
+    static?: boolean;
+}
+/**
+ * A custom function that can be called from within the isolate.
+ */
+export type CustomFunction<T extends any[] = unknown[]> = (...args: T) => unknown | Promise<unknown>;
+/**
+ * An async generator function that can be consumed in the isolate via for await...of.
+ */
+export type CustomAsyncGeneratorFunction<T extends any[] = unknown[]> = (...args: T) => AsyncGenerator<unknown, unknown, unknown>;
+/**
+ * Custom function definition with metadata.
+ * Requires explicit `type` property to indicate function behavior.
+ */
+export interface CustomFunctionDefinition<T extends any[] = unknown[]> {
+    /** The function implementation */
+    fn: CustomFunction<T> | CustomAsyncGeneratorFunction<T>;
+    /** Function type: 'sync', 'async', or 'asyncIterator' */
+    type: CustomFunctionType;
+}
+/**
+ * Custom functions to register in the runtime.
+ * Each function must be defined with explicit type property.
+ *
+ * @example
+ * ```typescript
+ * customFunctions: {
+ *   // Sync function
+ *   getConfig: {
+ *     fn: () => ({ environment: "production" }),
+ *     type: 'sync',
+ *   },
+ *   // Async function
+ *   hashPassword: {
+ *     fn: async (password) => bcrypt.hash(password, 10),
+ *     type: 'async',
+ *   },
+ *   // Async iterator function
+ *   streamData: {
+ *     fn: async function* (options) {
+ *       for await (const chunk of someStream) {
+ *         yield chunk;
+ *       }
+ *     },
+ *     type: 'asyncIterator',
+ *   },
+ * }
+ * ```
+ */
+export type CustomFunctions<T extends Record<string, any[]> = Record<string, unknown[]>> = {
+    [K in keyof T]: CustomFunctionDefinition<T[K]>;
+};
+/**
+ * Console entry types for structured console output.
+ * Each entry type captures the specific data needed to render like DevTools.
+ * Output is pre-formatted as stdout strings (like Node.js console) inside the sandbox.
+ */
+export type ConsoleEntry = {
+    type: "output";
+    level: "log" | "warn" | "error" | "info" | "debug";
+    stdout: string;
+    groupDepth: number;
+} | {
+    /** Browser console output (from Playwright page, not sandbox) */
+    type: "browserOutput";
+    level: string;
+    stdout: string;
+    location?: {
+        url?: string;
+        lineNumber?: number;
+        columnNumber?: number;
+    };
+    timestamp: number;
+} | {
+    type: "dir";
+    stdout: string;
+    groupDepth: number;
+} | {
+    type: "table";
+    stdout: string;
+    groupDepth: number;
+} | {
+    type: "time";
+    label: string;
+    duration: number;
+    groupDepth: number;
+} | {
+    type: "timeLog";
+    label: string;
+    duration: number;
+    stdout: string;
+    groupDepth: number;
+} | {
+    type: "count";
+    label: string;
+    count: number;
+    groupDepth: number;
+} | {
+    type: "countReset";
+    label: string;
+    groupDepth: number;
+} | {
+    type: "assert";
+    stdout: string;
+    groupDepth: number;
+} | {
+    type: "group";
+    label: string;
+    collapsed: boolean;
+    groupDepth: number;
+} | {
+    type: "groupEnd";
+    groupDepth: number;
+} | {
+    type: "clear";
+} | {
+    type: "trace";
+    stdout: string;
+    stack: string;
+    groupDepth: number;
+};
+/**
+ * Console callback handlers with single structured callback.
+ */
+export interface ConsoleCallbacks {
+    /**
+     * Callback invoked for each console operation.
+     * Receives a structured entry with all data needed to render the output.
+     */
+    onEntry?: (entry: ConsoleEntry) => void;
+}
+/**
+ * Fetch request init type.
+ */
+export interface FetchRequestInit {
+    method: string;
+    headers: [string, string][];
+    /** Raw body bytes - use this if you need direct access to the body data */
+    rawBody: Uint8Array | null;
+    /** Body ready for use with fetch() - same data as rawBody but typed as BodyInit */
+    body: BodyInit | null;
+    signal: AbortSignal;
+}
+/**
+ * Fetch callback type.
+ */
+export type FetchCallback = (url: string, init: FetchRequestInit) => Response | Promise<Response>;
+/**
+ * WebSocket callback type.
+ * Called when isolate code creates an outbound WebSocket connection.
+ * Return a WebSocket to proxy the connection, or null to block it.
+ */
+export type WebSocketCallback = (url: string, protocols: string[]) => WebSocket | Promise<WebSocket | null> | null;
+/**
+ * File system callback handlers.
+ */
+export interface FileSystemCallbacks {
+    readFile?: (path: string) => Promise<ArrayBuffer>;
+    writeFile?: (path: string, data: ArrayBuffer) => Promise<void>;
+    unlink?: (path: string) => Promise<void>;
+    readdir?: (path: string) => Promise<string[]>;
+    mkdir?: (path: string, options?: {
+        recursive?: boolean;
+    }) => Promise<void>;
+    rmdir?: (path: string) => Promise<void>;
+    stat?: (path: string) => Promise<{
+        isFile: boolean;
+        isDirectory: boolean;
+        size: number;
+    }>;
+    rename?: (from: string, to: string) => Promise<void>;
+}
+/**
+ * Options for dispatching a request.
+ */
+export interface DispatchOptions {
+    /** AbortSignal to cancel the request */
+    signal?: AbortSignal;
+    /** Optional request identifier forwarded to host callbacks */
+    requestId?: string;
+    /** Optional metadata forwarded to host callbacks */
+    metadata?: Record<string, string>;
+}
+/**
+ * Options for eval() method.
+ */
+export interface EvalOptions {
+    /** Filename for stack traces */
+    filename?: string;
+    /** Timeout for the full eval execution in milliseconds */
+    executionTimeout?: number;
+}
+/**
+ * Test environment options for createRuntime.
+ */
+export interface TestEnvironmentOptions {
+    /** Receive test lifecycle events */
+    onEvent?: (event: TestEvent) => void;
+    /** Timeout for individual tests (ms) */
+    testTimeout?: number;
+}
+/**
+ * File data for setInputFiles operations.
+ */
+export interface PlaywrightFileData {
+    /** File name */
+    name: string;
+    /** MIME type */
+    mimeType: string;
+    /** File contents as Buffer */
+    buffer: Buffer;
+}
+/**
+ * Options for Playwright integration.
+ *
+ * Public API is handler-first: host-specific page wiring should be done by
+ * creating a handler (for example via `defaultPlaywrightHandler(page)`).
+ */
+export interface PlaywrightOptions {
+    /** Handler callback for Playwright operations (required when playwright is enabled) */
+    handler: (op: PlaywrightOperation) => Promise<PlaywrightResult>;
+    /** Default timeout for operations in ms */
+    timeout?: number;
+    /** If true, browser console logs are routed through console handler (or printed to stdout if no handler) */
+    console?: boolean;
+    /** Unified event callback for all playwright events */
+    onEvent?: (event: PlaywrightEvent) => void;
+}
+/**
+ * Base runtime options shared between isolate-client and isolate-runtime.
+ * Each package extends this with its own `fs` type.
+ */
+export interface BaseRuntimeOptions<T extends Record<string, any[]> = Record<string, unknown[]>> {
+    /** Memory limit in megabytes (optional) */
+    memoryLimitMB?: number;
+    /** Timeout for the full eval/test execution in milliseconds */
+    executionTimeout?: number;
+    /** Console callback handlers */
+    console?: ConsoleCallbacks;
+    /** Fetch callback handler */
+    fetch?: FetchCallback;
+    /** WebSocket callback handler for outbound connections from isolate */
+    webSocket?: WebSocketCallback;
+    /** Module loader callback for resolving dynamic imports */
+    moduleLoader?: ModuleLoaderCallback;
+    /** Custom functions callable from within the isolate */
+    customFunctions?: CustomFunctions<T>;
+    /** Current working directory for path.resolve(). Defaults to "/" */
+    cwd?: string;
+    /** Enable test environment (describe, it, expect, etc.) */
+    testEnvironment?: boolean | TestEnvironmentOptions;
+    /** Playwright options (handler-first API) */
+    playwright?: PlaywrightOptions;
+}
+export interface CreateRuntimeResult {
+    isolateId: string;
+    /** True if runtime was reused from namespace pool */
+    reused?: boolean;
+}
+export interface EvalResult {
+    value: unknown;
+}
+export interface DispatchRequestResult {
+    response: SerializedResponse;
+}
+export interface SuiteInfo {
+    name: string;
+    /** Ancestry path: ["outer", "inner"] */
+    path: string[];
+    /** Full display name: "outer > inner" */
+    fullName: string;
+    /** Nesting depth (0 for root-level suites) */
+    depth: number;
+}
+export interface SuiteResult extends SuiteInfo {
+    passed: number;
+    failed: number;
+    skipped: number;
+    todo: number;
+    duration: number;
+}
+export interface TestInfo {
+    name: string;
+    /** Suite ancestry */
+    suitePath: string[];
+    /** Full display name: "suite > test name" */
+    fullName: string;
+}
+export interface TestError {
+    message: string;
+    stack?: string;
+    /** For assertion failures */
+    expected?: unknown;
+    actual?: unknown;
+    /** e.g., "toBe", "toEqual", "toContain" */
+    matcherName?: string;
+}
+export interface TestResult extends TestInfo {
+    status: "pass" | "fail" | "skip" | "todo";
+    duration: number;
+    error?: TestError;
+}
+export type TestEvent = {
+    type: "runStart";
+    testCount: number;
+    suiteCount: number;
+} | {
+    type: "suiteStart";
+    suite: SuiteInfo;
+} | {
+    type: "suiteEnd";
+    suite: SuiteResult;
+} | {
+    type: "testStart";
+    test: TestInfo;
+} | {
+    type: "testEnd";
+    test: TestResult;
+} | {
+    type: "runEnd";
+    results: RunTestsResult;
+};
+export interface RunTestsResult {
+    passed: number;
+    failed: number;
+    skipped: number;
+    todo: number;
+    total: number;
+    duration: number;
+    success: boolean;
+    suites: SuiteResult[];
+    tests: TestResult[];
+}
+export interface PlaywrightTestResult {
+    passed: number;
+    failed: number;
+    total: number;
+    results: {
+        name: string;
+        passed: boolean;
+        error?: string;
+        duration: number;
+    }[];
+}
+export interface CollectedData {
+    /** Browser console logs (from the page, not sandbox) */
+    browserConsoleLogs: {
+        level: string;
+        stdout: string;
+        location?: {
+            url?: string;
+            lineNumber?: number;
+            columnNumber?: number;
+        };
+        timestamp: number;
+    }[];
+    pageErrors: {
+        name: string;
+        message: string;
+        stack?: string;
+        timestamp: number;
+    }[];
+    networkRequests: {
+        requestId: string;
+        url: string;
+        method: string;
+        headers: Record<string, string>;
+        postData?: string;
+        resourceType?: string;
+        timestamp: number;
+    }[];
+    networkResponses: {
+        requestId: string;
+        url: string;
+        status: number;
+        headers: Record<string, string>;
+        statusText?: string;
+        resourceType?: string;
+        timestamp: number;
+    }[];
+    requestFailures: {
+        requestId: string;
+        url: string;
+        method: string;
+        failureText: string;
+        resourceType?: string;
+        timestamp: number;
+    }[];
+}
+/**
+ * Normalize a filename to an absolute path for module resolution.
+ *
+ * Rules:
+ * - undefined/empty/"" → "/index.js"
+ * - Absolute paths (start with /) → normalized as-is
+ * - Relative paths starting with "./" → converted to absolute from root
+ * - Bare filenames (no leading ./ or /) → converted to absolute from root
+ * - Paths starting with "../" → Error (can't resolve parent of root)
+ * - Directory paths ("/" or "./") → append "index.js"
+ *
+ * @example
+ * normalizeEntryFilename(undefined)     // "/index.js"
+ * normalizeEntryFilename("")            // "/index.js"
+ * normalizeEntryFilename("app.js")      // "/app.js"
+ * normalizeEntryFilename("./app.js")    // "/app.js"
+ * normalizeEntryFilename("/app.js")     // "/app.js"
+ * normalizeEntryFilename("./foo/bar.js") // "/foo/bar.js"
+ * normalizeEntryFilename("/")           // "/index.js"
+ * normalizeEntryFilename("./")          // "/index.js"
+ * normalizeEntryFilename("../app.js")   // throws Error
+ *
+ * @throws Error if the filename cannot be normalized (e.g., starts with "../")
+ */
+export declare function normalizeEntryFilename(filename: string | undefined): string;