@ricsam/isolate 0.0.1 → 0.1.0

package/dist/types/internal/fetch/consistency/origins.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Helper functions for creating web objects from different origins.
+ * Used to test that objects behave identically regardless of how they were created.
+ *
+ * Note: The `customFunction` origin is tested where supported. For Response and Request,
+ * this requires constructing the object in the isolate using parameters passed from
+ * a host custom function, since native objects cannot be serialized across the boundary.
+ */
+import { type RuntimeHandle } from "../../runtime/index.ts";
+export type ResponseOrigin = "direct" | "customFunction" | "fetchCallback";
+export type RequestOrigin = "direct" | "customFunction" | "serveRequest";
+export type HeadersOrigin = "direct" | "fromResponse" | "fromRequest";
+export type BlobOrigin = "direct";
+export type FileOrigin = "direct";
+export type URLOrigin = "direct" | "customFunction";
+export type URLSearchParamsOrigin = "direct" | "fromURL" | "fromCustomFunctionURL";
+export type FormDataOrigin = "direct" | "fromResponse";
+export type ReadableStreamOrigin = "direct" | "responseBody" | "blobStream" | "transformReadable";
+export type WritableStreamOrigin = "direct" | "transformWritable";
+export type TransformStreamOrigin = "direct";
+export type TextEncoderStreamOrigin = "direct";
+export type TextDecoderStreamOrigin = "direct";
+export type QueuingStrategyOrigin = "direct";
+export declare const RESPONSE_ORIGINS: ResponseOrigin[];
+export declare const REQUEST_ORIGINS: RequestOrigin[];
+export declare const HEADERS_ORIGINS: HeadersOrigin[];
+export declare const BLOB_ORIGINS: BlobOrigin[];
+export declare const FILE_ORIGINS: FileOrigin[];
+export declare const URL_ORIGINS: URLOrigin[];
+export declare const URLSEARCHPARAMS_ORIGINS: URLSearchParamsOrigin[];
+export declare const FORMDATA_ORIGINS: FormDataOrigin[];
+export declare const READABLE_STREAM_ORIGINS: ReadableStreamOrigin[];
+export declare const WRITABLE_STREAM_ORIGINS: WritableStreamOrigin[];
+export declare const TRANSFORM_STREAM_ORIGINS: TransformStreamOrigin[];
+export declare const TEXT_ENCODER_STREAM_ORIGINS: TextEncoderStreamOrigin[];
+export declare const TEXT_DECODER_STREAM_ORIGINS: TextDecoderStreamOrigin[];
+export declare const QUEUING_STRATEGY_ORIGINS: QueuingStrategyOrigin[];
+export type AbortControllerOrigin = "direct";
+export type AbortSignalOrigin = "direct";
+export declare const ABORT_CONTROLLER_ORIGINS: AbortControllerOrigin[];
+export declare const ABORT_SIGNAL_ORIGINS: AbortSignalOrigin[];
+export interface ConsistencyTestContext {
+    /** The runtime handle */
+    runtime: RuntimeHandle;
+    /** Execute code in the runtime */
+    eval(code: string): Promise<void>;
+    /** Dispatch an HTTP request to the serve() handler */
+    dispatchRequest(request: Request): Promise<Response>;
+    /** Set the mock response for the next fetch call */
+    setMockResponse(response: MockResponse): void;
+    /** Get a result from the isolate via setResult() */
+    getResult<T = unknown>(): T | undefined;
+    /** Clear the stored result */
+    clearResult(): void;
+    /** Dispose all resources */
+    dispose(): Promise<void>;
+}
+export interface MockResponse {
+    status?: number;
+    statusText?: string;
+    body?: string;
+    headers?: Record<string, string>;
+}
+/**
+ * Create a test context for consistency tests.
+ * Provides helpers for creating objects from different origins.
+ */
+export declare function createConsistencyTestContext(): Promise<ConsistencyTestContext>;
+export interface ResponseOptions {
+    status?: number;
+    statusText?: string;
+    headers?: Record<string, string>;
+}
+/**
+ * Create a Response in the isolate from the specified origin.
+ * The Response is stored at globalThis.__testResponse.
+ */
+export declare function getResponseFromOrigin(ctx: ConsistencyTestContext, origin: ResponseOrigin, body: string, options?: ResponseOptions): Promise<void>;
+export interface RequestOptions {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}
+/**
+ * Create a Request in the isolate from the specified origin.
+ * The Request is stored at globalThis.__testRequest.
+ */
+export declare function getRequestFromOrigin(ctx: ConsistencyTestContext, origin: RequestOrigin, url: string, options?: RequestOptions): Promise<void>;
+/**
+ * Create Headers in the isolate from the specified origin.
+ * The Headers is stored at globalThis.__testHeaders.
+ */
+export declare function getHeadersFromOrigin(ctx: ConsistencyTestContext, origin: HeadersOrigin, init: Record<string, string>): Promise<void>;
+export interface BlobOptions {
+    type?: string;
+}
+/**
+ * Create a Blob in the isolate from the specified origin.
+ * The Blob is stored at globalThis.__testBlob.
+ */
+export declare function getBlobFromOrigin(ctx: ConsistencyTestContext, origin: BlobOrigin, content: string, options?: BlobOptions): Promise<void>;
+export interface FileOptions {
+    type?: string;
+    lastModified?: number;
+}
+/**
+ * Create a File in the isolate from the specified origin.
+ * The File is stored at globalThis.__testFile.
+ */
+export declare function getFileFromOrigin(ctx: ConsistencyTestContext, origin: FileOrigin, content: string, filename: string, options?: FileOptions): Promise<void>;
+/**
+ * Create FormData in the isolate from the specified origin.
+ * The FormData is stored at globalThis.__testFormData.
+ */
+export declare function getFormDataFromOrigin(ctx: ConsistencyTestContext, origin: FormDataOrigin, entries: Array<[string, string]>): Promise<void>;
+/**
+ * Setup a serve handler that returns the specified response.
+ */
+export declare function setupServeHandler(ctx: ConsistencyTestContext, body: string, options?: ResponseOptions): Promise<void>;
+/**
+ * Dispatch a request and get the Response on the host side.
+ * This tests the host-side conversion of Response from isolate.
+ */
+export declare function getDispatchResponse(ctx: ConsistencyTestContext, body: string, options?: ResponseOptions): Promise<Response>;
+/**
+ * Create a ReadableStream in the isolate from the specified origin.
+ * The ReadableStream is stored at globalThis.__testReadableStream.
+ */
+export declare function getReadableStreamFromOrigin(ctx: ConsistencyTestContext, origin: ReadableStreamOrigin, chunks?: string[]): Promise<void>;
+/**
+ * Create a WritableStream in the isolate from the specified origin.
+ * The WritableStream is stored at globalThis.__testWritableStream.
+ * Also stores written chunks at globalThis.__testWrittenChunks.
+ */
+export declare function getWritableStreamFromOrigin(ctx: ConsistencyTestContext, origin: WritableStreamOrigin): Promise<void>;
+/**
+ * Create a TransformStream in the isolate from the specified origin.
+ * The TransformStream is stored at globalThis.__testTransformStream.
+ */
+export declare function getTransformStreamFromOrigin(ctx: ConsistencyTestContext, _origin: TransformStreamOrigin): Promise<void>;
+/**
+ * Create a TextEncoderStream in the isolate from the specified origin.
+ * The TextEncoderStream is stored at globalThis.__testTextEncoderStream.
+ */
+export declare function getTextEncoderStreamFromOrigin(ctx: ConsistencyTestContext, _origin: TextEncoderStreamOrigin): Promise<void>;
+export interface TextDecoderStreamOptions {
+    fatal?: boolean;
+    ignoreBOM?: boolean;
+}
+/**
+ * Create a TextDecoderStream in the isolate from the specified origin.
+ * The TextDecoderStream is stored at globalThis.__testTextDecoderStream.
+ */
+export declare function getTextDecoderStreamFromOrigin(ctx: ConsistencyTestContext, _origin: TextDecoderStreamOrigin, options?: TextDecoderStreamOptions): Promise<void>;
+/**
+ * Create a ByteLengthQueuingStrategy or CountQueuingStrategy in the isolate.
+ * The strategy is stored at globalThis.__testQueuingStrategy.
+ */
+export declare function getQueuingStrategyFromOrigin(ctx: ConsistencyTestContext, strategyType: "ByteLength" | "Count", highWaterMark?: number): Promise<void>;
+/**
+ * Create a URL in the isolate from the specified origin.
+ * The URL is stored at globalThis.__testURL.
+ */
+export declare function getURLFromOrigin(ctx: ConsistencyTestContext, origin: URLOrigin, urlString: string): Promise<void>;
+/**
+ * Create URLSearchParams in the isolate from the specified origin.
+ * The URLSearchParams is stored at globalThis.__testURLSearchParams.
+ */
+export declare function getURLSearchParamsFromOrigin(ctx: ConsistencyTestContext, origin: URLSearchParamsOrigin, init?: string): Promise<void>;
+/**
+ * Create an AbortController in the isolate from the specified origin.
+ * The AbortController is stored at globalThis.__testAbortController.
+ */
+export declare function getAbortControllerFromOrigin(ctx: ConsistencyTestContext, _origin: AbortControllerOrigin): Promise<void>;
+/**
+ * Create an AbortSignal in the isolate from the specified origin.
+ * The AbortSignal is stored at globalThis.__testAbortSignal.
+ */
+export declare function getAbortSignalFromOrigin(ctx: ConsistencyTestContext, _origin: AbortSignalOrigin): Promise<void>;

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

@@ -0,0 +1,93 @@
+import ivm from "isolated-vm";
+import { clearAllInstanceState } from "../core/index.ts";
+export { clearAllInstanceState };
+export interface FetchRequestInit {
+    method: string;
+    headers: [string, string][];
+    rawBody: Uint8Array | null;
+    body: BodyInit | null;
+    signal: AbortSignal;
+}
+export interface FetchOptions {
+    /** Handler for fetch requests from the isolate */
+    onFetch?: (url: string, init: FetchRequestInit) => Promise<Response>;
+}
+export interface UpgradeRequest {
+    requested: true;
+    connectionId: string;
+}
+export interface WebSocketCommand {
+    type: "message" | "close";
+    connectionId: string;
+    data?: string | ArrayBuffer;
+    code?: number;
+    reason?: string;
+}
+export interface ClientWebSocketCommand {
+    type: "connect" | "send" | "close";
+    socketId: string;
+    url?: string;
+    protocols?: string[];
+    data?: string | ArrayBuffer;
+    code?: number;
+    reason?: string;
+}
+export interface DispatchRequestOptions {
+    /** AbortSignal to mirror cancellation into request.signal inside isolate */
+    signal?: AbortSignal;
+}
+export interface FetchHandle {
+    dispose(): void;
+    /** Dispatch an HTTP request to the isolate's serve() handler */
+    dispatchRequest(request: Request, options?: DispatchRequestOptions): Promise<Response>;
+    /** Check if isolate requested WebSocket upgrade */
+    getUpgradeRequest(): UpgradeRequest | null;
+    /** Dispatch WebSocket open event to isolate */
+    dispatchWebSocketOpen(connectionId: string): void;
+    /** Dispatch WebSocket message event to isolate */
+    dispatchWebSocketMessage(connectionId: string, message: string | ArrayBuffer): void;
+    /** Dispatch WebSocket close event to isolate */
+    dispatchWebSocketClose(connectionId: string, code: number, reason: string): void;
+    /** Dispatch WebSocket error event to isolate */
+    dispatchWebSocketError(connectionId: string, error: Error): void;
+    /** Register callback for WebSocket commands from isolate */
+    onWebSocketCommand(callback: (cmd: WebSocketCommand) => void): () => void;
+    /** Check if serve() has been called */
+    hasServeHandler(): boolean;
+    /** Check if there are active WebSocket connections */
+    hasActiveConnections(): boolean;
+    /** Dispatch open event to a client WebSocket in the isolate */
+    dispatchClientWebSocketOpen(socketId: string, protocol: string, extensions: string): void;
+    /** Dispatch message event to a client WebSocket in the isolate */
+    dispatchClientWebSocketMessage(socketId: string, data: string | ArrayBuffer): void;
+    /** Dispatch close event to a client WebSocket in the isolate */
+    dispatchClientWebSocketClose(socketId: string, code: number, reason: string, wasClean: boolean): void;
+    /** Dispatch error event to a client WebSocket in the isolate */
+    dispatchClientWebSocketError(socketId: string): void;
+    /** Register callback for client WebSocket commands from isolate */
+    onClientWebSocketCommand(callback: (cmd: ClientWebSocketCommand) => void): () => void;
+    /** Register callback for events emitted from isolate code */
+    onEvent(callback: (event: string, payload: unknown) => void): () => void;
+    /** Dispatch an event into the isolate (calls __on listeners) */
+    dispatchEvent(event: string, payload: unknown): void;
+}
+/**
+ * Setup Fetch API in an isolated-vm context
+ *
+ * Injects fetch, Request, Response, Headers, FormData
+ * Also sets up core APIs (Blob, File, AbortController, etc.) if not already present
+ *
+ * @example
+ * const handle = await setupFetch(context, {
+ *   onFetch: async (url, init) => {
+ *     // Proxy fetch requests to the host
+ *     return fetch(url, init);
+ *   }
+ * });
+ *
+ * await context.eval(`
+ *   const response = await fetch("https://example.com");
+ *   const text = await response.text();
+ * `);
+ */
+export declare function setupFetch(context: ivm.Context, options?: FetchOptions): Promise<FetchHandle>;

package/dist/types/internal/fetch/stream-state.d.ts

@@ -0,0 +1,65 @@
+import ivm from "isolated-vm";
+export interface StreamState {
+    /** Buffered chunks waiting to be read */
+    queue: Uint8Array[];
+    /** Total bytes in queue (for backpressure) */
+    queueSize: number;
+    /** Stream has been closed (no more data) */
+    closed: boolean;
+    /** Stream encountered an error */
+    errored: boolean;
+    /** The error value if errored */
+    errorValue: unknown;
+    /** A pull is waiting for data */
+    pullWaiting: boolean;
+    /** Resolve function for waiting pull */
+    pullResolve: ((chunk: Uint8Array | null) => void) | null;
+    /** Reject function for waiting pull */
+    pullReject: ((error: unknown) => void) | null;
+}
+export interface StreamStateRegistry {
+    /** Create a new stream and return its ID */
+    create(): number;
+    /** Get stream state by ID */
+    get(streamId: number): StreamState | undefined;
+    /** Push a chunk to the stream's queue */
+    push(streamId: number, chunk: Uint8Array): boolean;
+    /** Pull a chunk from the stream (returns Promise that resolves when data available) */
+    pull(streamId: number): Promise<{
+        value: Uint8Array;
+        done: false;
+    } | {
+        done: true;
+    }>;
+    /** Close the stream (no more data) */
+    close(streamId: number): void;
+    /** Error the stream */
+    error(streamId: number, errorValue: unknown): void;
+    /** Check if stream queue is above high-water mark */
+    isQueueFull(streamId: number): boolean;
+    /** Delete stream state (cleanup) */
+    delete(streamId: number): void;
+    /** Clear all streams (context cleanup) */
+    clear(): void;
+    /** Cancel a stream and call its cleanup function */
+    cancel(streamId: number): void;
+    /** Register a cleanup function for a stream */
+    setCleanup(streamId: number, cleanup: () => Promise<void>): void;
+}
+/** Maximum bytes to buffer before backpressure kicks in */
+export declare const HIGH_WATER_MARK: number;
+/** Maximum number of chunks in queue */
+export declare const MAX_QUEUE_CHUNKS = 16;
+export declare function createStreamStateRegistry(): StreamStateRegistry;
+export declare function getStreamRegistryForContext(context: ivm.Context): StreamStateRegistry;
+export declare function clearStreamRegistryForContext(context: ivm.Context): void;
+/**
+ * Start reading from a native ReadableStream and push to host queue.
+ * Respects backpressure by pausing when queue is full.
+ *
+ * @param nativeStream The native ReadableStream to read from
+ * @param streamId The stream ID in the registry
+ * @param registry The stream state registry
+ * @returns Async cleanup function to cancel the reader
+ */
+export declare function startNativeStreamReader(nativeStream: ReadableStream<Uint8Array>, streamId: number, registry: StreamStateRegistry): () => Promise<void>;

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

@@ -0,0 +1,70 @@
+import ivm from "isolated-vm";
+import { clearAllInstanceState } from "../core/index.ts";
+export { clearAllInstanceState };
+export interface FileSystemHandler {
+    /** Get or create a file handle at the given path */
+    getFileHandle(path: string, options?: {
+        create?: boolean;
+    }): Promise<void>;
+    /** Get or create a directory handle at the given path */
+    getDirectoryHandle(path: string, options?: {
+        create?: boolean;
+    }): Promise<void>;
+    /** Remove a file or directory at the given path */
+    removeEntry(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    /** List contents of a directory */
+    readDirectory(path: string): Promise<Array<{
+        name: string;
+        kind: "file" | "directory";
+    }>>;
+    /** Read file content */
+    readFile(path: string): Promise<{
+        data: Uint8Array;
+        size: number;
+        lastModified: number;
+        type: string;
+    }>;
+    /** Write data to a file */
+    writeFile(path: string, data: Uint8Array, position?: number): Promise<void>;
+    /** Truncate a file to a specific size */
+    truncateFile(path: string, size: number): Promise<void>;
+    /** Get file metadata without reading content */
+    getFileMetadata(path: string): Promise<{
+        size: number;
+        lastModified: number;
+        type: string;
+    }>;
+}
+export interface FsOptions {
+    /** Get a file system handler for the given path */
+    getDirectory(path: string): Promise<FileSystemHandler>;
+}
+export interface FsHandle {
+    dispose(): void;
+}
+/**
+ * Setup File System Access API in an isolated-vm context
+ *
+ * Provides an OPFS-compatible FileSystemDirectoryHandle API
+ *
+ * @example
+ * const handle = await setupFs(context, {
+ *   getDirectory: async (path) => {
+ *     // Return a FileSystemHandler rooted at the given path
+ *     return createNodeFileSystemHandler(`./data${path}`);
+ *   }
+ * });
+ *
+ * await context.eval(`
+ *   const root = await getDirectory("/uploads");
+ *   const fileHandle = await root.getFileHandle("test.txt", { create: true });
+ *   const writable = await fileHandle.createWritable();
+ *   await writable.write("hello world");
+ *   await writable.close();
+ * `);
+ */
+export declare function setupFs(context: ivm.Context, options: FsOptions): Promise<FsHandle>;
+export { createNodeFileSystemHandler } from "./node-adapter.ts";
+export type { NodeFileSystemHandlerOptions } from "./node-adapter.ts";

package/dist/types/internal/fs/node-adapter.d.ts

@@ -0,0 +1,24 @@
+import * as nodeFs from "node:fs";
+import type { FileSystemHandler } from "./index.ts";
+export interface NodeFileSystemHandlerOptions {
+    /** Custom fs module (e.g., memfs for testing). Defaults to Node.js fs */
+    fs?: typeof nodeFs;
+}
+/**
+ * Create a FileSystemHandler backed by the Node.js filesystem
+ *
+ * @param rootPath - Absolute path to the root directory for the sandbox
+ * @param options - Optional configuration
+ * @returns FileSystemHandler implementation
+ *
+ * @example
+ * import { createNodeFileSystemHandler } from "./index.ts";
+ *
+ * const handler = createNodeFileSystemHandler("/tmp/sandbox");
+ *
+ * // Use with createRuntime
+ * const runtime = await createRuntime({
+ *   fs: { handler }
+ * });
+ */
+export declare function createNodeFileSystemHandler(rootPath: string, options?: NodeFileSystemHandlerOptions): FileSystemHandler;

package/dist/types/internal/module-loader/bundle.d.ts

@@ -0,0 +1,33 @@
+export declare function getNodeBuiltinShimCode(source: string): string;
+/**
+ * Bundle a bare specifier (npm package) using Rollup.
+ *
+ * Each unique bare specifier gets its own bundle with:
+ * - node-resolve with browser conditions
+ * - commonjs conversion
+ * - json support
+ * - process.env.NODE_ENV replacement
+ * - External deps (other npm packages) left as import statements
+ *
+ * Results are cached permanently (npm packages are static).
+ */
+export declare function bundleSpecifier(specifier: string, rootDir: string): Promise<{
+    code: string;
+}>;
+/**
+ * Bundle a host file using Rollup, inlining its relative imports.
+ *
+ * - Uses the host file path as Rollup input
+ * - Externalizes ALL bare specifiers (npm packages)
+ * - Strips TypeScript via processTypeScript
+ * - Shares the bundleCache/bundlesInFlight (no key collision since file paths start with `/`)
+ *
+ * Results are cached permanently.
+ */
+export declare function bundleHostFile(hostFilePath: string): Promise<{
+    code: string;
+}>;
+/**
+ * Clear the bundle cache. Useful for testing.
+ */
+export declare function clearBundleCache(): void;

package/dist/types/internal/module-loader/index.d.ts

@@ -0,0 +1,30 @@
+import type { ModuleLoaderCallback } from "../protocol/index.ts";
+import { type MappingConfig } from "./mappings.ts";
+export { parseMappings, virtualToHost, findNodeModulesMapping, findModuleAlias } from "./mappings.ts";
+export type { MappingConfig, PathMapping } from "./mappings.ts";
+export { resolveFilePath, detectFormat, parseSpecifier, isBareSpecifier } from "./resolve.ts";
+export { bundleSpecifier, bundleHostFile, clearBundleCache } from "./bundle.ts";
+export { isTypeScriptFile, processTypeScript } from "./strip-types.ts";
+/**
+ * Create a module loader callback that handles common patterns:
+ * - Mapping host filesystem paths to virtual isolate paths
+ * - Bundling npm packages with Rollup (ESM-first, browser conditions)
+ * - Reading user files directly from the host filesystem
+ *
+ * Each npm package subpath is bundled independently and cached as static.
+ *
+ * @example
+ * ```typescript
+ * import { defaultModuleLoader } from './index.ts';
+ *
+ * const loader = defaultModuleLoader(
+ *   { from: '/host/project/node_modules', to: '/node_modules' },
+ *   { from: '/host/project/src/entry.ts', to: '/app/entry.ts' }
+ * );
+ *
+ * const runtime = await createRuntime({
+ *   moduleLoader: loader,
+ * });
+ * ```
+ */
+export declare function defaultModuleLoader(...paths: MappingConfig[]): ModuleLoaderCallback;

package/dist/types/internal/module-loader/mappings.d.ts

@@ -0,0 +1,47 @@
+export interface PathMapping {
+    /** Original 'from' path (host) */
+    from: string;
+    /** Original 'to' path (virtual) */
+    to: string;
+    /** Whether this is a glob pattern */
+    isGlob: boolean;
+    /** For globs: the base path before the glob (host-side) */
+    hostBase: string;
+    /** For globs: the virtual mount point */
+    virtualMount: string;
+    /** Whether the host base ends with node_modules */
+    isNodeModules: boolean;
+    /** Whether this mapping is a module alias (to doesn't start with '/') */
+    isModuleAlias: boolean;
+}
+export interface MappingConfig {
+    from: string;
+    to: string;
+}
+/**
+ * Parse {from, to} pairs into structured PathMapping objects.
+ *
+ * - Glob patterns (contain `*`): extract base path before glob -> prefix mapping
+ * - Direct file paths (no glob): 1:1 mapping
+ * - Node modules detection: if base path ends with `node_modules`, flag as isNodeModules
+ */
+export declare function parseMappings(configs: MappingConfig[]): PathMapping[];
+/**
+ * Map a virtual path to a host path using the configured mappings.
+ * Returns null if no mapping matches.
+ */
+export declare function virtualToHost(virtualPath: string, mappings: PathMapping[]): string | null;
+/**
+ * Map a host path to a virtual path using the configured mappings.
+ * Returns null if no mapping matches.
+ */
+export declare function hostToVirtual(hostPath: string, mappings: PathMapping[]): string | null;
+/**
+ * Find the node_modules mapping (if any).
+ */
+export declare function findNodeModulesMapping(mappings: PathMapping[]): PathMapping | undefined;
+/**
+ * Find a module alias mapping that matches the given bare specifier.
+ * Returns undefined if no module alias matches.
+ */
+export declare function findModuleAlias(specifier: string, mappings: PathMapping[]): PathMapping | undefined;

package/dist/types/internal/module-loader/resolve.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Resolve a file path with extension probing, index fallback, and browser variant probing.
+ * Returns the resolved absolute path, or null if not found.
+ */
+export declare function resolveFilePath(basePath: string): string | null;
+/**
+ * Detect the format of a file based on its extension and content.
+ */
+export declare function detectFormat(filePath: string, code: string): "cjs" | "esm" | "json";
+/**
+ * Parse a bare specifier into package name and subpath.
+ *
+ * Examples:
+ *   "lodash" -> { packageName: "lodash", subpath: "" }
+ *   "lodash/chunk" -> { packageName: "lodash", subpath: "/chunk" }
+ *   "@scope/pkg" -> { packageName: "@scope/pkg", subpath: "" }
+ *   "@scope/pkg/sub/path" -> { packageName: "@scope/pkg", subpath: "/sub/path" }
+ */
+export declare function parseSpecifier(specifier: string): {
+    packageName: string;
+    subpath: string;
+};
+/**
+ * Check if a specifier is a bare specifier (npm package name, not relative/absolute).
+ */
+export declare function isBareSpecifier(specifier: string): boolean;

package/dist/types/internal/module-loader/strip-types.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Check if a file path is a TypeScript file that needs type processing.
+ */
+export declare function isTypeScriptFile(filePath: string): boolean;
+/**
+ * Process a TypeScript file for isolate use:
+ *
+ * 1. Strip TypeScript types
+ * 2. Elide import specifiers no longer referenced in the code body
+ *    (handles: `import { SomeType } from 'pkg'` where SomeType was only
+ *    used in type positions — the import survives stripping but the
+ *    usage doesn't, so V8 demands an export that doesn't exist in the bundle)
+ * 3. Add placeholder exports for type-only export names
+ *    (handles: `export interface Foo {}` disappears after stripping,
+ *    but other files may `import { Foo }` from this module)
+ *
+ * Returns valid JavaScript.
+ */
+export declare function processTypeScript(code: string, filename: string): string;

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

@@ -0,0 +1,23 @@
+import type ivm from "isolated-vm";
+export interface PathOptions {
+    /** Current working directory for path.resolve(). Defaults to "/" */
+    cwd?: string;
+}
+export interface PathHandle {
+    dispose(): void;
+}
+/**
+ * Setup path utilities in an isolated-vm context
+ *
+ * Provides path manipulation utilities similar to Node.js path module
+ * Uses POSIX-style paths only (always uses '/' as separator)
+ *
+ * @example
+ * const handle = await setupPath(context, { cwd: "/home/user" });
+ * await context.eval(\`
+ *   const joined = path.join("/foo", "bar", "baz");
+ *   const dir = path.dirname("/foo/bar/baz.txt");
+ *   const resolved = path.resolve("relative"); // Uses configured cwd
+ * \`);
+ */
+export declare function setupPath(context: ivm.Context, options?: PathOptions): Promise<PathHandle>;

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

@@ -0,0 +1,7 @@
+/**
+ * Client-safe exports for ./index.ts
+ * This module can be imported without loading isolated-vm
+ */
+export type { NetworkRequestInfo, NetworkResponseInfo, BrowserConsoleLogEntry, PageErrorInfo, RequestFailureInfo, DefaultPlaywrightHandler, DefaultPlaywrightHandlerMetadata, DefaultPlaywrightHandlerOptions, PlaywrightSetupOptions, PlaywrightHandle, PlaywrightCallback, } from "./types.ts";
+export type { PlaywrightOperation, PlaywrightResult, PlaywrightEvent, PlaywrightFileData } from "../protocol/index.ts";
+export { createPlaywrightHandler, defaultPlaywrightHandler, getDefaultPlaywrightHandlerMetadata, } from "./handler.ts";

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

@@ -0,0 +1,44 @@
+/**
+ * Shared handler code for ./index.ts
+ * Used by both index.ts (with isolated-vm) and client.ts (without isolated-vm)
+ */
+import type { Page, Locator as PlaywrightLocator, BrowserContext, Response } from "playwright";
+import { type DefaultPlaywrightHandlerMetadata, type DefaultPlaywrightHandlerOptions, type PlaywrightCallback, type PlaywrightSetupOptions } from "./types.ts";
+type ReadFileCallback = NonNullable<PlaywrightSetupOptions['readFile']>;
+type WriteFileCallback = NonNullable<PlaywrightSetupOptions['writeFile']>;
+export interface FileIOCallbacks {
+    readFile?: ReadFileCallback;
+    writeFile?: WriteFileCallback;
+}
+export declare function getLocator(page: Page, selectorType: string, selectorValue: string, optionsJson: string | null): PlaywrightLocator;
+export declare function executeLocatorAction(locator: PlaywrightLocator, action: string, actionArg: unknown, timeout: number, fileIO?: FileIOCallbacks): Promise<unknown>;
+export declare function executeExpectAssertion(locator: PlaywrightLocator, matcher: string, expected: unknown, negated: boolean, timeout: number): Promise<void>;
+export declare function executePageExpectAssertion(page: Page, matcher: string, expected: unknown, negated: boolean, timeout: number): Promise<void>;
+/**
+ * Registry for tracking multiple pages and contexts.
+ */
+export interface PlaywrightRegistry {
+    pages: Map<string, Page>;
+    contexts: Map<string, BrowserContext>;
+    nextPageId: number;
+    nextContextId: number;
+    pendingResponses: Map<string, Promise<Response>>;
+    pendingRequests: Map<string, Promise<import("playwright").Request>>;
+    nextListenerId: number;
+}
+/**
+ * Create a playwright handler from a Page object.
+ * 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?: DefaultPlaywrightHandlerOptions): PlaywrightCallback;
+/**
+ * Public helper for handler-first runtime options.
+ * Adds metadata used by adapters for local event capture and collected data.
+ */
+export declare function defaultPlaywrightHandler(page: Page, options?: DefaultPlaywrightHandlerOptions): PlaywrightCallback;
+/**
+ * Extract metadata from handlers created by defaultPlaywrightHandler().
+ */
+export declare function getDefaultPlaywrightHandlerMetadata(handler: PlaywrightCallback): DefaultPlaywrightHandlerMetadata | undefined;
+export {};