@ricsam/isolate 0.1.10 → 0.1.12

package/README.md

@@ -1,6 +1,6 @@
 # @ricsam/isolate
 
-`@ricsam/isolate` is a runtime-centric JavaScript sandbox built on an async-context-enabled [`@ricsam/isolated-vm`](https://github.com/ricsam/isolated-vm) engine build. It gives you a single host API for running isolated code with web-style capabilities such as `fetch`, files, streams, server handlers, module loading, and Playwright-backed browser tests.
+`@ricsam/isolate` is a runtime-centric JavaScript sandbox built on an async-context-enabled [`@ricsam/isolated-vm`](https://github.com/ricsam/isolated-vm) engine build. It gives you a single host API for running isolated code with web-style capabilities such as `fetch`, files, streams, server handlers, nested sandboxes, module loading, and Playwright-backed browser tests.
 
 ## Installation
 
@@ -10,7 +10,7 @@ npm add @ricsam/isolate @ricsam/isolated-vm
 
 The `@ricsam/isolated-vm` peer includes the `createContext({ asyncContext: true })` support required by this repo. Upstream `isolated-vm` will fail fast during runtime boot with a clear AsyncContext error.
 
-Install Playwright when you want browser runtimes:
+Install Playwright when you want browser-enabled runtimes or test runtimes:
 
 ```bash
 npm add playwright
@@ -24,12 +24,16 @@ npm add playwright
 - `createModuleResolver()` to provide virtual modules, source trees, mounted `node_modules`, and fallback resolution
 - `createFileBindings()` to expose a rooted file API to sandboxed code
 - `getTypeProfile()`, `typecheck()`, and `formatTypecheckErrors()` for sandbox-aware TypeScript tooling
+- `@ricsam/isolate/playwright` to build handler-first Playwright sessions without importing internals
 
 The host can create three runtime styles:
 
 - `host.createRuntime()` for scripts, agents, and ad hoc execution
 - `host.createAppServer()` for `serve()`-based request handlers
-- `host.createBrowserRuntime()` for Playwright-backed execution
+- `host.createTestRuntime()` for test suites with optional Playwright-backed browser access
+- `host.getNamespacedRuntime()` for persistent mixed script/test/browser sessions keyed by namespace
+
+Inside sandbox code, `@ricsam/isolate` is also available as a synthetic module. It exports a sandbox-only `createIsolateHost()` that lets a runtime create nested runtimes, app servers, and test runtimes without exposing daemon configuration to the sandbox.
 
 ## Host Bindings
 
@@ -40,9 +44,19 @@ Each runtime is configured through `bindings`, which describe how sandboxed code
 - `files` exposes a safe, root-scoped filesystem
 - `modules` resolves virtual modules, source trees, and mounted packages
 - `tools` exposes async host functions and async iterators
+- `browser` exposes a Playwright-like browser surface backed either by a stable handler or by host `createContext()` and `createPage()` callbacks
 
 Every host callback receives a `HostCallContext` with an `AbortSignal`, runtime identity, resource identity, and request metadata.
 
+`bindings.browser` is intentionally smaller than a full Playwright browser. It injects a global `browser` object with `browser.newContext()` and `browser.contexts()`, and returned contexts expose `context.newPage()` and `context.pages()`. Browser-level shutdown stays on the host side, while the sandbox can still close pages and contexts that it created.
+
+Choose exactly one browser mode per runtime:
+
+- factory-first: provide `createContext()` and optionally `createPage()`, `readFile()`, and `writeFile()`
+- handler-first: provide `handler`, usually from `createPlaywrightSessionHandler(...)`
+
+Do not mix `handler` with `createContext()` / `createPage()` / `readFile()` / `writeFile()` in the same binding.
+
 ## Async Context
 
 Runtimes created by `@ricsam/isolate` enable the TC39 proposal-style `AsyncContext` global inside the sandbox. This is an experimental surface for now, and the proposal API is used to implement the `node:async_hooks` shim exported to sandboxed code.
@@ -145,6 +159,51 @@ try {
 }
 ```
 
+## Nested Hosts Inside The Sandbox
+
+Sandbox code can import `@ricsam/isolate` and create child runtimes against the same top-level host connection.
+
+```ts
+const runtime = await host.createRuntime({
+  bindings: {
+    console: {
+      onEntry(entry) {
+        if (entry.type === "output") {
+          console.log(entry.stdout);
+        }
+      },
+    },
+  },
+});
+
+await runtime.eval(`
+  import { createIsolateHost } from "@ricsam/isolate";
+
+  const nestedHost = createIsolateHost();
+  const child = await nestedHost.createRuntime({
+    bindings: {
+      tools: {
+        greet: async (name) => "hello " + name,
+      },
+    },
+  });
+
+  await child.eval('console.log(await greet("nested"))');
+  await child.dispose();
+  await nestedHost.close();
+`);
+```
+
+Nested hosts support:
+
+- `createRuntime()`
+- `createAppServer()`
+- `createTestRuntime()`
+- `diagnostics()`
+- `close()`
+
+Child runtimes can reuse the same binding shapes as top-level runtimes. That includes isolate-authored callbacks, async iterators, module resolvers, file bindings, and browser handles.
+
 ## App Servers
 
 `createAppServer()` is the long-lived server-oriented API. It boots a runtime around an entry module that calls `serve()` and then lets the host dispatch requests into it.
@@ -183,51 +242,227 @@ await host.close();
 
 `server.handle()` returns either a normal HTTP response or WebSocket upgrade metadata. The `server.ws` helpers let the host continue an upgraded connection by sending open, message, close, and error events back into the runtime.
 
-## Browser Runtimes
+## Browser Bindings In Script And Server Runtimes
+
+## Namespaced Sessions
+
+`host.getNamespacedRuntime(key, options)` is the public persistent-session API. It is the supported way to reuse one underlying runtime across multiple calls while refreshing host bindings on each acquire.
+
+Use it when you want patterns like:
 
-`createBrowserRuntime()` runs sandboxed code against a Playwright page while keeping the host in control of file access, diagnostics, and browser event collection.
+- script calls that keep module state or globals between runs
+- Playwright browser contexts/pages that stay alive behind one stable handler
+- later `runTests(code)` calls that should see existing `browser.contexts()`
+
+Normal `session.dispose()` is a soft dispose for that namespace. The next acquire of the same key reuses the cached runtime. `host.disposeNamespace(key)` is the hard-delete path for active or pooled namespaces and invalidates any live handles in the current process.
 
 ```ts
 import { chromium } from "playwright";
 import { createIsolateHost } from "@ricsam/isolate";
+import { createPlaywrightSessionHandler } from "@ricsam/isolate/playwright";
 
 const browser = await chromium.launch();
-const context = await browser.newContext();
-const page = await context.newPage();
+const host = await createIsolateHost();
+const playwright = createPlaywrightSessionHandler({
+  createContext: async (options) =>
+    await browser.newContext(options ?? undefined),
+  createPage: async (context) =>
+    await context.newPage(),
+});
+
+const session = await host.getNamespacedRuntime("playwright:preview:session", {
+  bindings: {
+    browser: {
+      handler: playwright.handler,
+    },
+  },
+});
+
+await session.eval(`
+  globalThis.ctx = await browser.newContext();
+  globalThis.page = await globalThis.ctx.newPage();
+  await globalThis.page.goto("https://example.com");
+`);
+
+await session.dispose();
+
+const reused = await host.getNamespacedRuntime("playwright:preview:session", {
+  bindings: {
+    browser: {
+      handler: playwright.handler,
+    },
+  },
+});
+
+const results = await reused.runTests(`
+  test("sees the existing browser state", async () => {
+    const contexts = await browser.contexts();
+    expect(contexts.length).toBe(1);
+    const pages = await contexts[0].pages();
+    expect(pages.length).toBe(1);
+  });
+`);
+
+console.log(results.success);
+
+await host.disposeNamespace("playwright:preview:session");
+await browser.close();
+await host.close();
+```
+
+Lifecycle notes:
+
+- only one live handle per namespace is allowed at a time
+- `runTests(code)` resets test registration before loading and running the provided suite
+- runtime globals, module state, and Playwright resources are preserved across soft dispose and reacquire
+- browser shutdown stays host-owned; page/context shutdown stays sandbox-owned
+- preview URL rewriting remains host-specific and stays outside isolate
 
+## Browser Bindings In Script And Server Runtimes
+
+If you provide `bindings.browser`, script and app runtimes get a global `browser` factory even when they are not full Playwright browser runtimes.
+
+```ts
+import { chromium } from "playwright";
+import { createIsolateHost } from "@ricsam/isolate";
+
+const browser = await chromium.launch();
+const host = await createIsolateHost();
+
+const runtime = await host.createRuntime({
+  bindings: {
+    browser: {
+      createContext: async (options) =>
+        await browser.newContext(options ?? undefined),
+      createPage: async (contextInstance) =>
+        await contextInstance.newPage(),
+    },
+  },
+});
+
+await runtime.eval(`
+  const ctx = await browser.newContext({
+    viewport: { width: 1280, height: 720 },
+  });
+  const page = await ctx.newPage();
+
+  await page.goto("https://example.com");
+  console.log(await page.title());
+  console.log(typeof browser.close);
+
+  await page.close();
+  await ctx.close();
+`);
+
+await runtime.dispose();
+await browser.close();
+await host.close();
+```
+
+In these runtimes:
+
+- `browser.newContext()` is available
+- `browser.contexts()` is available
+- `context.newPage()` is available
+- `context.pages()` is available
+- `page.close()` and `context.close()` are available
+- `browser.close()` is not exposed inside the sandbox
+- `page` and `context` are never injected as implicit globals
+
+## Test Runtimes
+
+`createTestRuntime()` enables `describe`, `test`/`it`, hooks, and `expect`. If you also provide `bindings.browser`, the same test runtime gets Playwright-style browser access and matcher support, but you are responsible for explicit page/context lifecycle inside the suite.
+
+```ts
+import { chromium } from "playwright";
+import { createIsolateHost } from "@ricsam/isolate";
+
+const browser = await chromium.launch();
 const host = await createIsolateHost();
-const runtime = await host.createBrowserRuntime({
-  key: "example/browser",
-  bindings: {},
-  features: { tests: true },
-  browser: {
-    page,
-    captureConsole: true,
+const runtime = await host.createTestRuntime({
+  key: "example/browser-test",
+  bindings: {
+    browser: {
+      captureConsole: true,
+      createContext: async (options) =>
+        await browser.newContext(options ?? undefined),
+      createPage: async (contextInstance) =>
+        await contextInstance.newPage(),
+    },
   },
 });
 
 const result = await runtime.run(
   `
+    let ctx;
+    let page;
+
+    beforeAll(async () => {
+      ctx = await browser.newContext();
+      page = await ctx.newPage();
+    });
+
+    afterAll(async () => {
+      await ctx.close();
+    });
+
     test("loads a page", async () => {
-      await page.goto("https://example.com");
+      expect((await browser.contexts()).length).toBe(1);
+      expect((await ctx.pages()).length).toBe(1);
+      await page.goto("https://example.com", {
+        waitUntil: "domcontentloaded",
+      });
       await expect(page).toHaveTitle(/Example Domain/);
     });
   `,
   {
     filename: "/browser-test.ts",
-    asTestSuite: true,
     timeoutMs: 10_000,
   },
 );
 
-console.log(result.tests);
+console.log(result);
 
 await runtime.dispose();
-await context.close();
 await browser.close();
 await host.close();
 ```
 
+From inside another sandbox, `nestedHost.createTestRuntime()` can reuse the sandbox `browser` handle:
+
+```ts
+import { createIsolateHost } from "@ricsam/isolate";
+
+const nestedHost = createIsolateHost();
+const child = await nestedHost.createTestRuntime({
+  bindings: {
+    browser,
+  },
+});
+
+await child.run(`
+  let ctx;
+  let page;
+
+  beforeAll(async () => {
+    ctx = await browser.newContext();
+    page = await ctx.newPage();
+  });
+
+  afterAll(async () => {
+    await ctx.close();
+  });
+
+  test("loads a nested page", async () => {
+    await page.goto("https://example.com");
+    await expect(page).toHaveTitle(/Example Domain/);
+  });
+`);
+
+await child.dispose();
+await nestedHost.close();
+```
+
 ## Module Resolution
 
 `createModuleResolver()` is a fluent builder. You can mix and match:
@@ -278,6 +513,10 @@ Built-in profiles:
 
 Capabilities can extend a profile with `fetch`, `files`, `tests`, `browser`, `tools`, `console`, `encoding`, and `timers`.
 
+- Use `browser` when sandbox code should typecheck `browser.newContext()`, `browser.contexts()`, `context.newPage()`, and `context.pages()`
+- The browser test profile does not assume implicit global `page` or `context`
+- The synthetic sandbox import `import { createIsolateHost } from "@ricsam/isolate"` is included in all type profiles
+
 ## Daemon CLI
 
 The package also exposes an `isolate-daemon` binary:

package/dist/cjs/bridge/diagnostics.cjs

@@ -39,7 +39,8 @@ var __export = (target, all) => {
 // src/bridge/diagnostics.ts
 var exports_diagnostics = {};
 __export(exports_diagnostics, {
-  createRuntimeDiagnostics: () => createRuntimeDiagnostics
+  createRuntimeDiagnostics: () => createRuntimeDiagnostics,
+  createBrowserDiagnostics: () => createBrowserDiagnostics
 });
 module.exports = __toCommonJS(exports_diagnostics);
 function createRuntimeDiagnostics() {
@@ -54,5 +55,39 @@ function createRuntimeDiagnostics() {
     lifecycleState: "idle"
   };
 }
+function createBrowserDiagnostics(collectedData, trackedResources) {
+  const contextIds = new Set;
+  const pageIds = new Set;
+  for (const entry of collectedData.browserConsoleLogs) {
+    contextIds.add(entry.contextId);
+    pageIds.add(entry.pageId);
+  }
+  for (const entry of collectedData.pageErrors) {
+    contextIds.add(entry.contextId);
+    pageIds.add(entry.pageId);
+  }
+  for (const entry of collectedData.networkRequests) {
+    contextIds.add(entry.contextId);
+    pageIds.add(entry.pageId);
+  }
+  for (const entry of collectedData.networkResponses) {
+    contextIds.add(entry.contextId);
+    pageIds.add(entry.pageId);
+  }
+  for (const entry of collectedData.requestFailures) {
+    contextIds.add(entry.contextId);
+    pageIds.add(entry.pageId);
+  }
+  return {
+    contexts: trackedResources?.contexts.length ?? contextIds.size,
+    pages: trackedResources?.pages.length ?? pageIds.size,
+    browserConsoleLogs: collectedData.browserConsoleLogs.length,
+    networkRequests: collectedData.networkRequests.length,
+    networkResponses: collectedData.networkResponses.length,
+    pageErrors: collectedData.pageErrors.length,
+    requestFailures: collectedData.requestFailures.length,
+    collectedData
+  };
+}
 
-//# debugId=40FF8D24B6369A0D64756E2164756E21
+//# debugId=8BF2916FF62F72B164756E2164756E21

package/dist/cjs/bridge/diagnostics.cjs.map

@@ -2,9 +2,9 @@
   "version": 3,
   "sources": ["../../../src/bridge/diagnostics.ts"],
   "sourcesContent": [
-    "import type { RuntimeDiagnostics } from \"../types.cjs\";\n\nexport interface MutableRuntimeDiagnostics extends RuntimeDiagnostics {\n  activeRequests: number;\n  activeResources: number;\n  pendingFiles: number;\n  pendingFetches: number;\n  pendingModules: number;\n  pendingTools: number;\n  streamCount: number;\n  lifecycleState: \"idle\" | \"active\" | \"reloading\" | \"disposing\";\n}\n\nexport function createRuntimeDiagnostics(): MutableRuntimeDiagnostics {\n  return {\n    activeRequests: 0,\n    activeResources: 0,\n    pendingFiles: 0,\n    pendingFetches: 0,\n    pendingModules: 0,\n    pendingTools: 0,\n    streamCount: 0,\n    lifecycleState: \"idle\",\n  };\n}\n"
+    "import type { CollectedData } from \"../internal/client/index.cjs\";\nimport type { BrowserDiagnostics, RuntimeDiagnostics } from \"../types.cjs\";\n\nexport interface MutableRuntimeDiagnostics extends RuntimeDiagnostics {\n  activeRequests: number;\n  activeResources: number;\n  pendingFiles: number;\n  pendingFetches: number;\n  pendingModules: number;\n  pendingTools: number;\n  streamCount: number;\n  lifecycleState: \"idle\" | \"active\" | \"reloading\" | \"disposing\";\n}\n\nexport function createRuntimeDiagnostics(): MutableRuntimeDiagnostics {\n  return {\n    activeRequests: 0,\n    activeResources: 0,\n    pendingFiles: 0,\n    pendingFetches: 0,\n    pendingModules: 0,\n    pendingTools: 0,\n    streamCount: 0,\n    lifecycleState: \"idle\",\n  };\n}\n\nexport function createBrowserDiagnostics(\n  collectedData: CollectedData,\n  trackedResources?: { contexts: string[]; pages: string[] },\n): BrowserDiagnostics {\n  const contextIds = new Set<string>();\n  const pageIds = new Set<string>();\n  for (const entry of collectedData.browserConsoleLogs) {\n    contextIds.add(entry.contextId);\n    pageIds.add(entry.pageId);\n  }\n  for (const entry of collectedData.pageErrors) {\n    contextIds.add(entry.contextId);\n    pageIds.add(entry.pageId);\n  }\n  for (const entry of collectedData.networkRequests) {\n    contextIds.add(entry.contextId);\n    pageIds.add(entry.pageId);\n  }\n  for (const entry of collectedData.networkResponses) {\n    contextIds.add(entry.contextId);\n    pageIds.add(entry.pageId);\n  }\n  for (const entry of collectedData.requestFailures) {\n    contextIds.add(entry.contextId);\n    pageIds.add(entry.pageId);\n  }\n\n  return {\n    contexts: trackedResources?.contexts.length ?? contextIds.size,\n    pages: trackedResources?.pages.length ?? pageIds.size,\n    browserConsoleLogs: collectedData.browserConsoleLogs.length,\n    networkRequests: collectedData.networkRequests.length,\n    networkResponses: collectedData.networkResponses.length,\n    pageErrors: collectedData.pageErrors.length,\n    requestFailures: collectedData.requestFailures.length,\n    collectedData,\n  };\n}\n"
   ],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAaO,SAAS,wBAAwB,GAA8B;AAAA,EACpE,OAAO;AAAA,IACL,gBAAgB;AAAA,IAChB,iBAAiB;AAAA,IACjB,cAAc;AAAA,IACd,gBAAgB;AAAA,IAChB,gBAAgB;AAAA,IAChB,cAAc;AAAA,IACd,aAAa;AAAA,IACb,gBAAgB;AAAA,EAClB;AAAA;",
-  "debugId": "40FF8D24B6369A0D64756E2164756E21",
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAcO,SAAS,wBAAwB,GAA8B;AAAA,EACpE,OAAO;AAAA,IACL,gBAAgB;AAAA,IAChB,iBAAiB;AAAA,IACjB,cAAc;AAAA,IACd,gBAAgB;AAAA,IAChB,gBAAgB;AAAA,IAChB,cAAc;AAAA,IACd,aAAa;AAAA,IACb,gBAAgB;AAAA,EAClB;AAAA;AAGK,SAAS,wBAAwB,CACtC,eACA,kBACoB;AAAA,EACpB,MAAM,aAAa,IAAI;AAAA,EACvB,MAAM,UAAU,IAAI;AAAA,EACpB,WAAW,SAAS,cAAc,oBAAoB;AAAA,IACpD,WAAW,IAAI,MAAM,SAAS;AAAA,IAC9B,QAAQ,IAAI,MAAM,MAAM;AAAA,EAC1B;AAAA,EACA,WAAW,SAAS,cAAc,YAAY;AAAA,IAC5C,WAAW,IAAI,MAAM,SAAS;AAAA,IAC9B,QAAQ,IAAI,MAAM,MAAM;AAAA,EAC1B;AAAA,EACA,WAAW,SAAS,cAAc,iBAAiB;AAAA,IACjD,WAAW,IAAI,MAAM,SAAS;AAAA,IAC9B,QAAQ,IAAI,MAAM,MAAM;AAAA,EAC1B;AAAA,EACA,WAAW,SAAS,cAAc,kBAAkB;AAAA,IAClD,WAAW,IAAI,MAAM,SAAS;AAAA,IAC9B,QAAQ,IAAI,MAAM,MAAM;AAAA,EAC1B;AAAA,EACA,WAAW,SAAS,cAAc,iBAAiB;AAAA,IACjD,WAAW,IAAI,MAAM,SAAS;AAAA,IAC9B,QAAQ,IAAI,MAAM,MAAM;AAAA,EAC1B;AAAA,EAEA,OAAO;AAAA,IACL,UAAU,kBAAkB,SAAS,UAAU,WAAW;AAAA,IAC1D,OAAO,kBAAkB,MAAM,UAAU,QAAQ;AAAA,IACjD,oBAAoB,cAAc,mBAAmB;AAAA,IACrD,iBAAiB,cAAc,gBAAgB;AAAA,IAC/C,kBAAkB,cAAc,iBAAiB;AAAA,IACjD,YAAY,cAAc,WAAW;AAAA,IACrC,iBAAiB,cAAc,gBAAgB;AAAA,IAC/C;AAAA,EACF;AAAA;",
+  "debugId": "8BF2916FF62F72B164756E2164756E21",
   "names": []
 }