@lunora/browser 1.0.0-alpha.4 → 1.0.0-alpha.40

package/LICENSE.md

@@ -103,3 +103,9 @@ Unless required by applicable law or agreed to in writing, software distributed
 under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
 CONDITIONS OF ANY KIND, either express or implied. See the License for the
 specific language governing permissions and limitations under the License.
+
+<!-- DEPENDENCIES -->
+<!-- /DEPENDENCIES -->
+
+<!-- TYPE_DEPENDENCIES -->
+<!-- /TYPE_DEPENDENCIES -->

package/README.md

@@ -10,6 +10,8 @@
 
 <!-- END_PACKAGE_OG_IMAGE_PLACEHOLDER -->
 
+> **Experimental** — this package is outside the Lunora 1.0 stability promise: its API may change in any release, without a major version bump.
+
 <br />
 
 <div align="center">
@@ -105,9 +107,11 @@ If you deliberately drive the browser at an internal service reachable through a
 const browser = createBrowser({ binding: env.BROWSER, launch, allowPrivateTargets: true });
 ```
 
-Only set `allowPrivateTargets` when every URL is trusted — it re-opens the SSRF surface. The guard does not resolve DNS, so a public hostname that resolves to a private address (DNS rebinding) is out of scope; keep caller-supplied URLs trusted regardless.
+Only set `allowPrivateTargets` when every URL is trusted — it re-opens the SSRF surface.
+
+DNS rebinding is covered too: whenever `allowedHosts` is unset, the host is resolved over DoH and refused if it maps to a private address, before the browser launches and again on every redirect hop. Setting `allowedHosts` turns that re-check off, because an exact-host allowlist already closes rebinding and may deliberately name an internal host reachable over a Tunnel; pass `resolveDns: true` to force both.
 
-> This README covers the basics. For the full API, options, and guides, see the **[documentation](https://lunora.sh/docs/addons/browser)**.
+> This README covers the basics. For the full API, options, and guides, see the **[documentation](https://lunora.sh/docs/packages/browser)**.
 
 ## Related
 

package/dist/index.d.mts

@@ -1,25 +1,28 @@
 /**
-* Structural projection of the Cloudflare **Browser Rendering** binding
-* (`env.BROWSER`). The binding is a `Fetcher` under the hood — `@cloudflare/playwright`
-* drives it via `launch(env.BROWSER)`. Declared locally (an empty structural
-* marker) so unit tests can pass a plain-object double and the real binding
-* satisfies the same shape without importing `@cloudflare/workers-types` into
-* the public surface. See https://developers.cloudflare.com/browser-rendering/.
-*
-* It is intentionally opaque: callers never touch the binding directly, they
-* hand it to {@link LunoraBrowserOptions.binding} and the Playwright layer
-* consumes it. Typed as a non-empty marker so an arbitrary value (e.g. `{}`)
-* doesn't silently type-check where a binding is required.
-*/
+ * Structural projection of the Cloudflare **Browser Rendering** binding
+ * (`env.BROWSER`). The binding is a `Fetcher` under the hood — `@cloudflare/playwright`
+ * drives it via `launch(env.BROWSER)`. Declared locally (an empty structural
+ * marker) so unit tests can pass a plain-object double and the real binding
+ * satisfies the same shape without importing `@cloudflare/workers-types` into
+ * the public surface. See https://developers.cloudflare.com/browser-rendering/.
+ *
+ * It is intentionally opaque: callers never touch the binding directly, they
+ * hand it to {@link LunoraBrowserOptions.binding} and the Playwright layer
+ * consumes it. `fetch` is REQUIRED (the real binding is a `Fetcher`, so it
+ * always has one) so the marker actually excludes an arbitrary value like `{}` —
+ * a bare object fails to type-check where a binding is required, catching the
+ * misuse at the call site instead of deferring to an opaque launch error.
+ * @experimental
+ */
 interface BrowserBindingLike {
-  readonly fetch?: (...args: never[]) => unknown;
+  readonly fetch: typeof fetch;
 }
 /**
-* Minimal projection of a Playwright `Route` (the argument the `page.route`
-* handler receives). Only the members the SSRF redirect guard drives are
-* declared: inspect the intercepted request's URL / navigation-ness, then either
-* let it proceed ({@link RouteLike.continue}) or reject it ({@link RouteLike.abort}).
-*/
+ * Minimal projection of a Playwright `Route` (the argument the `page.route`
+ * handler receives). Only the members the SSRF redirect guard drives are
+ * declared: inspect the intercepted request's URL / navigation-ness, then either
+ * let it proceed ({@link RouteLike.continue}) or reject it ({@link RouteLike.abort}).
+ */
 interface RouteLike {
   /** Reject the intercepted request (fail-closed); `errorCode` is a Playwright abort reason. */
   abort: (errorCode?: string) => Promise<void>;
@@ -32,28 +35,29 @@ interface RouteLike {
   };
 }
 /**
-* Minimal projection of a Playwright `Page` — just the methods the helpers drive.
-* Declared structurally so a test can inject a plain stub instead of a real
-* headless page (which needs workerd + the Browser Rendering binding).
-*/
+ * Minimal projection of a Playwright `Page` — just the methods the helpers drive.
+ * Declared structurally so a test can inject a plain stub instead of a real
+ * headless page (which needs workerd + the Browser Rendering binding).
+ * @experimental
+ */
 interface PageLike {
   /** Return the page's serialized HTML after the navigation settles. */
   content: () => Promise<string>;
   /** Run a function in the page context and return its (serializable) result. */
-  evaluate: <T>(function_: (...args: never[]) => T) => Promise<T>;
+  evaluate: <T>(function_: () => T) => Promise<T>;
   /** Navigate to a URL; resolves once the configured wait condition is met. */
   goto: (url: string, options?: {
     timeout?: number;
-    waitUntil?: string;
+    waitUntil?: "commit" | "domcontentloaded" | "load" | "networkidle";
   }) => Promise<unknown>;
   /** Render the page to a PDF buffer. */
   pdf: (options?: Record<string, unknown>) => Promise<Uint8Array>;
   /**
-  * Register a request interceptor (Playwright `page.route`). Optional: a fake
-  * or older page double without it still works — the SSRF redirect guard only
-  * activates when interception is available, and the initial-URL guard applies
-  * regardless. `pattern` follows Playwright's glob/URL matcher.
-  */
+   * Register a request interceptor (Playwright `page.route`). Optional: a fake
+   * or older page double without it still works — the SSRF redirect guard only
+   * activates when interception is available, and the initial-URL guard applies
+   * regardless. `pattern` follows Playwright's glob/URL matcher.
+   */
   route?: (pattern: string, handler: (route: RouteLike) => unknown) => Promise<void>;
   /** Render the page to a PNG/JPEG buffer. */
   screenshot: (options?: Record<string, unknown>) => Promise<Uint8Array>;
@@ -64,154 +68,274 @@ interface PageLike {
   }) => Promise<void>;
 }
 /**
-* Minimal projection of a Playwright `BrowserContext`. Only `newPage` is used;
-* declared structurally for the same test-double reason as {@link PageLike}.
-*/
+ * Minimal projection of a Playwright `BrowserContext`. Only `newPage` is used;
+ * declared structurally for the same test-double reason as {@link PageLike}.
+ * @experimental
+ */
 interface BrowserContextLike {
   newPage: () => Promise<PageLike>;
 }
 /**
-* Minimal projection of a Playwright `Browser` (the value `launch` resolves to).
-* Only `newContext`/`close` are used; declared structurally for the same
-* test-double reason as {@link PageLike}.
-*/
+ * Minimal projection of a Playwright `Browser` (the value `launch` resolves to).
+ * Only `newContext`/`close` are used; declared structurally for the same
+ * test-double reason as {@link PageLike}.
+ * @experimental
+ */
 interface BrowserLike {
   close: () => Promise<void>;
   newContext: () => Promise<BrowserContextLike>;
+  /**
+   * The Browser Rendering session this browser is attached to, when the
+   * runtime exposes it.
+   *
+   * Optional because this is a structural projection, not a re-declaration of
+   * the upstream Playwright type — but without it there is no way to learn
+   * the id of a session you just held open with `launch(fn, { keepAlive })`,
+   * which makes {@link Browser.connect} unreachable except by guessing from
+   * {@link Browser.sessions}.
+   */
+  sessionId?: () => string | undefined;
 }
 /**
-* Structural projection of `@cloudflare/playwright`'s `launch` export
-* (`import { launch } from "@cloudflare/playwright"`). Injected via
-* {@link LunoraBrowserOptions.launch} so the factory never imports
-* `@cloudflare/playwright` at module top — that keeps the heavy optional peer
-* dep out of the bundle for apps that never screenshot, and lets tests pass a
-* fake. Calling it with the Browser Rendering binding resolves a {@link BrowserLike}.
-*/
+ * Structural projection of `@cloudflare/playwright`'s `launch` export
+ * (`import { launch } from "@cloudflare/playwright"`). Injected via
+ * {@link LunoraBrowserOptions.launch} so the factory never imports
+ * `@cloudflare/playwright` at module top — that keeps the heavy optional peer
+ * dep out of the bundle for apps that never screenshot, and lets tests pass a
+ * fake. Calling it with the Browser Rendering binding resolves a {@link BrowserLike}.
+ * @experimental
+ */
 type BrowserLaunchLike = (binding: BrowserBindingLike, options?: Record<string, unknown>) => Promise<BrowserLike>;
-/** Options shared by the page-driving helpers ({@link Browser.screenshot} etc.). */
+/**
+ * One live Browser Rendering session, as `@cloudflare/playwright`'s `sessions()`
+ * reports it. `connectionId` is set while another worker holds the session — you
+ * can only {@link Browser.connect} to a free one.
+ * @experimental
+ */
+interface BrowserSession {
+  connectionId?: string;
+  sessionId: string;
+  startTime?: number;
+}
+/**
+ * Structural projection of `@cloudflare/playwright`'s `connect` export —
+ * re-attaches to an existing session rather than starting a new browser.
+ * Injected like {@link BrowserLaunchLike} so the peer dep stays optional.
+ * @experimental
+ */
+type BrowserConnectLike = (binding: BrowserBindingLike, sessionId: string) => Promise<BrowserLike>;
+/**
+ * Structural projection of `@cloudflare/playwright`'s `sessions` export — lists
+ * the account's live Browser Rendering sessions for this binding.
+ * @experimental
+ */
+type BrowserSessionsLike = (binding: BrowserBindingLike) => Promise<ReadonlyArray<BrowserSession>>;
+/**
+ * Options shared by the page-driving helpers ({@link Browser.screenshot} etc.).
+ * @experimental
+ */
 interface NavigateOptions {
   /**
-  * Hard timeout in milliseconds for the navigation + operation. Clamped to a
-  * sane ceiling so a hung/hostile page can't pin the worker. Default 30000.
-  */
+   * Hard timeout in milliseconds for the navigation + operation. Clamped to a
+   * sane ceiling so a hung/hostile page can't pin the worker. Default 30000.
+   */
   timeoutMs?: number;
   /**
-  * Playwright navigation wait condition. Playwright's set differs from
-  * Puppeteer's: `load`, `domcontentloaded`, `networkidle`, `commit`.
-  * Default `load`.
-  */
+   * Playwright navigation wait condition. Playwright's set differs from
+   * Puppeteer's: `load`, `domcontentloaded`, `networkidle`, `commit`.
+   * Default `load`.
+   */
   waitUntil?: "commit" | "domcontentloaded" | "load" | "networkidle";
 }
-/** Options for {@link Browser.screenshot}. */
+/**
+ * Options for {@link Browser.screenshot}.
+ * @experimental
+ */
 interface ScreenshotOptions extends NavigateOptions {
   /** Capture the full scrollable page rather than just the viewport. */
   fullPage?: boolean;
   /** Image encoding. Default `png`. */
   type?: "jpeg" | "png";
   /**
-  * Viewport size. Each dimension is hard-capped (see the factory's
-  * `MAX_VIEWPORT_*`) so a caller can't request a multi-million-pixel render.
-  */
+   * Viewport size. Each dimension is hard-capped (see the factory's
+   * `MAX_VIEWPORT_*`) so a caller can't request a multi-million-pixel render.
+   */
   viewport?: {
     height: number;
     width: number;
   };
 }
-/** Options for {@link Browser.pdf}. */
+/**
+ * Options for {@link Browser.pdf}.
+ * @experimental
+ */
 interface PdfOptions extends NavigateOptions {
   /** Paper format (`A4`, `Letter`, …) forwarded to Playwright. */
   format?: string;
   /** Print background graphics. Default `false`. */
   printBackground?: boolean;
   /**
-  * Viewport used while laying out the page before printing. Hard-capped like
-  * {@link ScreenshotOptions.viewport}.
-  */
+   * Viewport used while laying out the page before printing. Hard-capped like
+   * {@link ScreenshotOptions.viewport}.
+   */
   viewport?: {
     height: number;
     width: number;
   };
 }
+/**
+ * `LunoraBrowserOptions` is part of the experimental `@lunora/browser` API and may change without a major version bump.
+ * @experimental
+ */
 interface LunoraBrowserOptions {
   /**
-  * Strict host allowlist. When set (non-empty), a navigation URL is refused
-  * unless its hostname exactly matches one of these entries (case-insensitive,
-  * trailing-dot-normalized, IPv6 brackets stripped). This is the only guard
-  * that fully closes DNS rebinding: a public hostname that resolves to a
-  * private/metadata IP can still be pinned out if it isn't on the list. Set it
-  * whenever you pass client-controlled URLs to the browser. Leave it unset (the
-  * default) to keep the previous behavior (only the string-based SSRF guard).
-  */
+   * Strict host allowlist. When set (non-empty), a navigation URL is refused
+   * unless its hostname exactly matches one of these entries (case-insensitive,
+   * trailing-dot-normalized, IPv6 brackets stripped). This is the only guard
+   * that fully closes DNS rebinding: a public hostname that resolves to a
+   * private/metadata IP can still be pinned out if it isn't on the list. Set it
+   * whenever you pass client-controlled URLs to the browser.
+   *
+   * Leaving it unset (the default) is NOT unguarded: it turns
+   * {@link LunoraBrowserOptions.resolveDns} on, so every host is resolved over
+   * DoH and refused if it maps to a private address. Setting an allowlist turns
+   * that re-check off (the allowlist is the stronger guard, and may deliberately
+   * name an internal host); `resolveDns: true` forces both.
+   */
   allowedHosts?: string[];
   /**
-  * Opt out of the SSRF guard that, by default, refuses to navigate to a
-  * private / internal / loopback / link-local host (RFC1918, `127.0.0.0/8`,
-  * `169.254.0.0/16` incl. the cloud-metadata address, CGNAT, IPv6 ULA/
-  * link-local, and `localhost` / `*.internal` / `*.local` literals). Leave it
-  * `false` (the default) unless every caller-supplied URL is trusted — e.g.
-  * you deliberately drive the browser at an internal service reachable through
-  * a Cloudflare Tunnel / private-network binding. Setting it `true` re-opens
-  * the SSRF surface, so never combine it with caller-controlled URLs.
-  */
+   * Opt out of the SSRF guard that, by default, refuses to navigate to a
+   * private / internal / loopback / link-local host (RFC1918, `127.0.0.0/8`,
+   * `169.254.0.0/16` incl. the cloud-metadata address, CGNAT, IPv6 ULA/
+   * link-local, and `localhost` / `*.internal` / `*.local` literals). Leave it
+   * `false` (the default) unless every caller-supplied URL is trusted — e.g.
+   * you deliberately drive the browser at an internal service reachable through
+   * a Cloudflare Tunnel / private-network binding. Setting it `true` re-opens
+   * the SSRF surface, so never combine it with caller-controlled URLs.
+   */
   allowPrivateTargets?: boolean;
   /** The Cloudflare Browser Rendering binding (`env.BROWSER`). Required. */
   binding: BrowserBindingLike;
   /**
-  * The `@cloudflare/playwright` `launch` function. Injected rather than
-  * imported at module top so the optional peer dep stays out of the bundle
-  * for non-browser apps and tests can pass a double. The generated worker
-  * passes the real function; omitting it makes the helper throw on first use
-  * with a clear "install `@cloudflare/playwright`" error.
-  */
+   * The `@cloudflare/playwright` `connect` function, injected like
+   * {@link LunoraBrowserOptions.launch}. Required for {@link Browser.connect}.
+   */
+  connect?: BrowserConnectLike;
+  /**
+   * The `@cloudflare/playwright` `launch` function. Injected rather than
+   * imported at module top so the optional peer dep stays out of the bundle
+   * for non-browser apps and tests can pass a double. The generated worker
+   * passes the real function; omitting it makes the helper throw on first use
+   * with a clear "install `@cloudflare/playwright`" error.
+   */
   launch?: BrowserLaunchLike;
   /**
-  * Best-effort DNS-rebinding re-check. When `true` (and `allowPrivateTargets`
-  * is `false`), the factory resolves the URL's hostname over Cloudflare DoH
-  * (`https://cloudflare-dns.com/dns-query`) and refuses to navigate if any
-  * resolved A/AAAA record is a private/internal address — closing the gap
-  * where a public hostname resolves to a private IP after the string guard
-  * passes. Off by default: it adds a DNS round-trip and is TOCTOU-imperfect
-  * (the browser re-resolves independently). If the DoH lookup itself fails, it
-  * falls back to the string guard rather than allowing a resolved private IP.
-  * For a hard guarantee prefer {@link LunoraBrowserOptions.allowedHosts}.
-  */
+   * Best-effort DNS-rebinding re-check. When `true` (and `allowPrivateTargets`
+   * is `false`), the factory resolves the URL's hostname over Cloudflare DoH
+   * (`https://cloudflare-dns.com/dns-query`) and refuses to navigate if any
+   * resolved A/AAAA record is a private/internal address — closing the gap
+   * where a public hostname resolves to a private IP after the string guard
+   * passes.
+   *
+   * **On by default when no {@link LunoraBrowserOptions.allowedHosts} is set**,
+   * because a `scrape`/`screenshot` action that forwards a client-supplied URL
+   * is the common shape and the string guard alone lets
+   * `http://127.0.0.1.nip.io:8787/…` through to an internal service. It costs
+   * one DNS round-trip per navigation and is TOCTOU-imperfect (the browser
+   * re-resolves independently), and if the DoH lookup itself fails it falls
+   * back to the string guard rather than allowing a resolved private IP.
+   *
+   * Configuring `allowedHosts` turns it OFF by default: an exact-origin
+   * allowlist is the stronger guard and may deliberately name an internal host
+   * (reachable over a Tunnel / private-network binding) that a resolved-address
+   * check would refuse. Set this explicitly to `true` to run both, or to
+   * `false` for trusted, non-caller-supplied URLs where the round-trip matters.
+   */
   resolveDns?: boolean;
   /**
-  * Default navigation timeout (ms) applied when a per-call `timeoutMs` is not
-  * given. Clamped to the factory's `MAX_TIMEOUT_MS`. Default 30000.
-  */
+   * The `@cloudflare/playwright` `sessions` function, injected like
+   * {@link LunoraBrowserOptions.launch}. Required for {@link Browser.sessions}.
+   */
+  sessions?: BrowserSessionsLike;
+  /**
+   * Default navigation timeout (ms) applied when a per-call `timeoutMs` is not
+   * given. Clamped to the factory's `MAX_TIMEOUT_MS`. Default 30000.
+   */
   timeoutMs?: number;
 }
 /**
-* The `ctx.browser` surface — Cloudflare Browser Rendering driven through
-* `@cloudflare/playwright`. **Action-only**: every method performs
-* non-deterministic network I/O (it navigates a real headless browser to a
-* URL), so codegen wires it onto `ActionCtx` exclusively — never `QueryCtx`/
-* `MutationCtx` — exactly like `ctx.ai` / `ctx.fetch`. Each helper launches a
-* browser, opens a context + page, navigates, performs the op, and always
-* closes the browser in a `finally` (a leaked session is billed and
-* rate-limited).
-*/
+ * The `ctx.browser` surface — Cloudflare Browser Rendering driven through
+ * `@cloudflare/playwright`. **Action-only**: every method performs
+ * non-deterministic network I/O (it navigates a real headless browser to a
+ * URL), so codegen wires it onto `ActionCtx` exclusively — never `QueryCtx`/
+ * `MutationCtx` — exactly like `ctx.ai` / `ctx.fetch`. Each helper launches a
+ * browser, opens a context + page, navigates, performs the op, and always
+ * closes the browser in a `finally` (a leaked session is billed and
+ * rate-limited).
+ * @experimental
+ */
 interface Browser {
+  /**
+   * Re-attach to an existing session and hand the browser to `fn`.
+   *
+   * Get the id either by reading it inside the call that opened the session
+   * (`launch(async (browser) => browser.sessionId?.(), { keepAlive: 600 })`)
+   * and persisting it, or by picking a free one out of
+   * {@link Browser.sessions} — an entry with a `connectionId` is already held
+   * by another worker.
+   *
+   * The session is deliberately **left open** afterwards — closing it is the
+   * whole thing you are avoiding. Close it when the flow is done by passing
+   * `close: true`, or let `keepAlive` lapse.
+   *
+   * This is what makes agent-style browsing possible: a model calls
+   * `navigate`, then `click`, then `extract` as three separate action
+   * invocations, and the page has to survive between them. With only the
+   * per-call lifecycle each step got a fresh browser, so `click` ran against
+   * a blank page — silently, which is the worst shape for that bug.
+   */
+  connect: <T>(sessionId: string, function_: (browser: BrowserLike) => Promise<T>, options?: {
+    close?: boolean;
+  }) => Promise<T>;
   /** Serialized HTML of `url` after navigation settles. */
   content: (url: string, options?: NavigateOptions) => Promise<string>;
   /**
-  * Low-level escape hatch: launch a raw Playwright `Browser` and hand it to
-  * `fn` (e.g. for multi-page flows or APIs not surfaced here). The browser is
-  * **always closed** when `fn` resolves or throws — do not retain references
-  * to it past the callback.
-  */
-  launch: <T>(function_: (browser: BrowserLike) => Promise<T>) => Promise<T>;
+   * Low-level escape hatch: launch a raw Playwright `Browser` and hand it to
+   * `fn` (e.g. for multi-page flows or APIs not surfaced here).
+   *
+   * The browser is **always closed** when `fn` resolves or throws — unless
+   * `keepAlive` is a number of seconds **between 10 and 600**, which holds the
+   * session open for that long so a later {@link Browser.connect} can
+   * re-attach. `0`, a negative value and `NaN` all mean "do not keep alive"
+   * and take the always-close path (a held session is billed, so the
+   * ambiguous values fall to the safe side); a positive value outside the
+   * 10–600s window Browser Rendering accepts throws `BAD_REQUEST` rather than
+   * being sent on for the provider to refuse. Do not retain references to the
+   * browser past the callback either way.
+   */
+  launch: <T>(function_: (browser: BrowserLike) => Promise<T>, options?: {
+    keepAlive?: number;
+  }) => Promise<T>;
   /** Render `url` to a PDF buffer. */
   pdf: (url: string, options?: PdfOptions) => Promise<Uint8Array>;
   /**
-  * Navigate to `url`, run `fn` inside the page context, and return its
-  * (serializable) result. `fn` runs in the browser, not the worker — it
-  * cannot close over worker-side variables.
-  */
+   * Navigate to `url`, run `fn` inside the page context, and return its
+   * (serializable) result. `fn` runs in the browser, not the worker — it
+   * cannot close over worker-side variables.
+   */
   scrape: <T>(url: string, function_: (...args: never[]) => T, options?: NavigateOptions) => Promise<T>;
   /** Render `url` to an image buffer (PNG by default). */
   screenshot: (url: string, options?: ScreenshotOptions) => Promise<Uint8Array>;
+  /**
+   * List the live Browser Rendering sessions for this binding, so a caller can
+   * pick a free one to {@link Browser.connect} to. An entry with a
+   * `connectionId` is already held by another worker.
+   */
+  sessions: () => Promise<ReadonlyArray<BrowserSession>>;
 }
+/**
+ * `createBrowser` is part of the experimental `@lunora/browser` API and may change without a major version bump.
+ * @experimental
+ */
 declare const createBrowser: (options: LunoraBrowserOptions) => Browser;
 export { type Browser, type BrowserBindingLike, type BrowserContextLike, type BrowserLaunchLike, type BrowserLike, type LunoraBrowserOptions, type NavigateOptions, type PageLike, type PdfOptions, type ScreenshotOptions, createBrowser };

package/dist/index.d.ts

@@ -1,25 +1,28 @@
 /**
-* Structural projection of the Cloudflare **Browser Rendering** binding
-* (`env.BROWSER`). The binding is a `Fetcher` under the hood — `@cloudflare/playwright`
-* drives it via `launch(env.BROWSER)`. Declared locally (an empty structural
-* marker) so unit tests can pass a plain-object double and the real binding
-* satisfies the same shape without importing `@cloudflare/workers-types` into
-* the public surface. See https://developers.cloudflare.com/browser-rendering/.
-*
-* It is intentionally opaque: callers never touch the binding directly, they
-* hand it to {@link LunoraBrowserOptions.binding} and the Playwright layer
-* consumes it. Typed as a non-empty marker so an arbitrary value (e.g. `{}`)
-* doesn't silently type-check where a binding is required.
-*/
+ * Structural projection of the Cloudflare **Browser Rendering** binding
+ * (`env.BROWSER`). The binding is a `Fetcher` under the hood — `@cloudflare/playwright`
+ * drives it via `launch(env.BROWSER)`. Declared locally (an empty structural
+ * marker) so unit tests can pass a plain-object double and the real binding
+ * satisfies the same shape without importing `@cloudflare/workers-types` into
+ * the public surface. See https://developers.cloudflare.com/browser-rendering/.
+ *
+ * It is intentionally opaque: callers never touch the binding directly, they
+ * hand it to {@link LunoraBrowserOptions.binding} and the Playwright layer
+ * consumes it. `fetch` is REQUIRED (the real binding is a `Fetcher`, so it
+ * always has one) so the marker actually excludes an arbitrary value like `{}` —
+ * a bare object fails to type-check where a binding is required, catching the
+ * misuse at the call site instead of deferring to an opaque launch error.
+ * @experimental
+ */
 interface BrowserBindingLike {
-  readonly fetch?: (...args: never[]) => unknown;
+  readonly fetch: typeof fetch;
 }
 /**
-* Minimal projection of a Playwright `Route` (the argument the `page.route`
-* handler receives). Only the members the SSRF redirect guard drives are
-* declared: inspect the intercepted request's URL / navigation-ness, then either
-* let it proceed ({@link RouteLike.continue}) or reject it ({@link RouteLike.abort}).
-*/
+ * Minimal projection of a Playwright `Route` (the argument the `page.route`
+ * handler receives). Only the members the SSRF redirect guard drives are
+ * declared: inspect the intercepted request's URL / navigation-ness, then either
+ * let it proceed ({@link RouteLike.continue}) or reject it ({@link RouteLike.abort}).
+ */
 interface RouteLike {
   /** Reject the intercepted request (fail-closed); `errorCode` is a Playwright abort reason. */
   abort: (errorCode?: string) => Promise<void>;
@@ -32,28 +35,29 @@ interface RouteLike {
   };
 }
 /**
-* Minimal projection of a Playwright `Page` — just the methods the helpers drive.
-* Declared structurally so a test can inject a plain stub instead of a real
-* headless page (which needs workerd + the Browser Rendering binding).
-*/
+ * Minimal projection of a Playwright `Page` — just the methods the helpers drive.
+ * Declared structurally so a test can inject a plain stub instead of a real
+ * headless page (which needs workerd + the Browser Rendering binding).
+ * @experimental
+ */
 interface PageLike {
   /** Return the page's serialized HTML after the navigation settles. */
   content: () => Promise<string>;
   /** Run a function in the page context and return its (serializable) result. */
-  evaluate: <T>(function_: (...args: never[]) => T) => Promise<T>;
+  evaluate: <T>(function_: () => T) => Promise<T>;
   /** Navigate to a URL; resolves once the configured wait condition is met. */
   goto: (url: string, options?: {
     timeout?: number;
-    waitUntil?: string;
+    waitUntil?: "commit" | "domcontentloaded" | "load" | "networkidle";
   }) => Promise<unknown>;
   /** Render the page to a PDF buffer. */
   pdf: (options?: Record<string, unknown>) => Promise<Uint8Array>;
   /**
-  * Register a request interceptor (Playwright `page.route`). Optional: a fake
-  * or older page double without it still works — the SSRF redirect guard only
-  * activates when interception is available, and the initial-URL guard applies
-  * regardless. `pattern` follows Playwright's glob/URL matcher.
-  */
+   * Register a request interceptor (Playwright `page.route`). Optional: a fake
+   * or older page double without it still works — the SSRF redirect guard only
+   * activates when interception is available, and the initial-URL guard applies
+   * regardless. `pattern` follows Playwright's glob/URL matcher.
+   */
   route?: (pattern: string, handler: (route: RouteLike) => unknown) => Promise<void>;
   /** Render the page to a PNG/JPEG buffer. */
   screenshot: (options?: Record<string, unknown>) => Promise<Uint8Array>;
@@ -64,154 +68,274 @@ interface PageLike {
   }) => Promise<void>;
 }
 /**
-* Minimal projection of a Playwright `BrowserContext`. Only `newPage` is used;
-* declared structurally for the same test-double reason as {@link PageLike}.
-*/
+ * Minimal projection of a Playwright `BrowserContext`. Only `newPage` is used;
+ * declared structurally for the same test-double reason as {@link PageLike}.
+ * @experimental
+ */
 interface BrowserContextLike {
   newPage: () => Promise<PageLike>;
 }
 /**
-* Minimal projection of a Playwright `Browser` (the value `launch` resolves to).
-* Only `newContext`/`close` are used; declared structurally for the same
-* test-double reason as {@link PageLike}.
-*/
+ * Minimal projection of a Playwright `Browser` (the value `launch` resolves to).
+ * Only `newContext`/`close` are used; declared structurally for the same
+ * test-double reason as {@link PageLike}.
+ * @experimental
+ */
 interface BrowserLike {
   close: () => Promise<void>;
   newContext: () => Promise<BrowserContextLike>;
+  /**
+   * The Browser Rendering session this browser is attached to, when the
+   * runtime exposes it.
+   *
+   * Optional because this is a structural projection, not a re-declaration of
+   * the upstream Playwright type — but without it there is no way to learn
+   * the id of a session you just held open with `launch(fn, { keepAlive })`,
+   * which makes {@link Browser.connect} unreachable except by guessing from
+   * {@link Browser.sessions}.
+   */
+  sessionId?: () => string | undefined;
 }
 /**
-* Structural projection of `@cloudflare/playwright`'s `launch` export
-* (`import { launch } from "@cloudflare/playwright"`). Injected via
-* {@link LunoraBrowserOptions.launch} so the factory never imports
-* `@cloudflare/playwright` at module top — that keeps the heavy optional peer
-* dep out of the bundle for apps that never screenshot, and lets tests pass a
-* fake. Calling it with the Browser Rendering binding resolves a {@link BrowserLike}.
-*/
+ * Structural projection of `@cloudflare/playwright`'s `launch` export
+ * (`import { launch } from "@cloudflare/playwright"`). Injected via
+ * {@link LunoraBrowserOptions.launch} so the factory never imports
+ * `@cloudflare/playwright` at module top — that keeps the heavy optional peer
+ * dep out of the bundle for apps that never screenshot, and lets tests pass a
+ * fake. Calling it with the Browser Rendering binding resolves a {@link BrowserLike}.
+ * @experimental
+ */
 type BrowserLaunchLike = (binding: BrowserBindingLike, options?: Record<string, unknown>) => Promise<BrowserLike>;
-/** Options shared by the page-driving helpers ({@link Browser.screenshot} etc.). */
+/**
+ * One live Browser Rendering session, as `@cloudflare/playwright`'s `sessions()`
+ * reports it. `connectionId` is set while another worker holds the session — you
+ * can only {@link Browser.connect} to a free one.
+ * @experimental
+ */
+interface BrowserSession {
+  connectionId?: string;
+  sessionId: string;
+  startTime?: number;
+}
+/**
+ * Structural projection of `@cloudflare/playwright`'s `connect` export —
+ * re-attaches to an existing session rather than starting a new browser.
+ * Injected like {@link BrowserLaunchLike} so the peer dep stays optional.
+ * @experimental
+ */
+type BrowserConnectLike = (binding: BrowserBindingLike, sessionId: string) => Promise<BrowserLike>;
+/**
+ * Structural projection of `@cloudflare/playwright`'s `sessions` export — lists
+ * the account's live Browser Rendering sessions for this binding.
+ * @experimental
+ */
+type BrowserSessionsLike = (binding: BrowserBindingLike) => Promise<ReadonlyArray<BrowserSession>>;
+/**
+ * Options shared by the page-driving helpers ({@link Browser.screenshot} etc.).
+ * @experimental
+ */
 interface NavigateOptions {
   /**
-  * Hard timeout in milliseconds for the navigation + operation. Clamped to a
-  * sane ceiling so a hung/hostile page can't pin the worker. Default 30000.
-  */
+   * Hard timeout in milliseconds for the navigation + operation. Clamped to a
+   * sane ceiling so a hung/hostile page can't pin the worker. Default 30000.
+   */
   timeoutMs?: number;
   /**
-  * Playwright navigation wait condition. Playwright's set differs from
-  * Puppeteer's: `load`, `domcontentloaded`, `networkidle`, `commit`.
-  * Default `load`.
-  */
+   * Playwright navigation wait condition. Playwright's set differs from
+   * Puppeteer's: `load`, `domcontentloaded`, `networkidle`, `commit`.
+   * Default `load`.
+   */
   waitUntil?: "commit" | "domcontentloaded" | "load" | "networkidle";
 }
-/** Options for {@link Browser.screenshot}. */
+/**
+ * Options for {@link Browser.screenshot}.
+ * @experimental
+ */
 interface ScreenshotOptions extends NavigateOptions {
   /** Capture the full scrollable page rather than just the viewport. */
   fullPage?: boolean;
   /** Image encoding. Default `png`. */
   type?: "jpeg" | "png";
   /**
-  * Viewport size. Each dimension is hard-capped (see the factory's
-  * `MAX_VIEWPORT_*`) so a caller can't request a multi-million-pixel render.
-  */
+   * Viewport size. Each dimension is hard-capped (see the factory's
+   * `MAX_VIEWPORT_*`) so a caller can't request a multi-million-pixel render.
+   */
   viewport?: {
     height: number;
     width: number;
   };
 }
-/** Options for {@link Browser.pdf}. */
+/**
+ * Options for {@link Browser.pdf}.
+ * @experimental
+ */
 interface PdfOptions extends NavigateOptions {
   /** Paper format (`A4`, `Letter`, …) forwarded to Playwright. */
   format?: string;
   /** Print background graphics. Default `false`. */
   printBackground?: boolean;
   /**
-  * Viewport used while laying out the page before printing. Hard-capped like
-  * {@link ScreenshotOptions.viewport}.
-  */
+   * Viewport used while laying out the page before printing. Hard-capped like
+   * {@link ScreenshotOptions.viewport}.
+   */
   viewport?: {
     height: number;
     width: number;
   };
 }
+/**
+ * `LunoraBrowserOptions` is part of the experimental `@lunora/browser` API and may change without a major version bump.
+ * @experimental
+ */
 interface LunoraBrowserOptions {
   /**
-  * Strict host allowlist. When set (non-empty), a navigation URL is refused
-  * unless its hostname exactly matches one of these entries (case-insensitive,
-  * trailing-dot-normalized, IPv6 brackets stripped). This is the only guard
-  * that fully closes DNS rebinding: a public hostname that resolves to a
-  * private/metadata IP can still be pinned out if it isn't on the list. Set it
-  * whenever you pass client-controlled URLs to the browser. Leave it unset (the
-  * default) to keep the previous behavior (only the string-based SSRF guard).
-  */
+   * Strict host allowlist. When set (non-empty), a navigation URL is refused
+   * unless its hostname exactly matches one of these entries (case-insensitive,
+   * trailing-dot-normalized, IPv6 brackets stripped). This is the only guard
+   * that fully closes DNS rebinding: a public hostname that resolves to a
+   * private/metadata IP can still be pinned out if it isn't on the list. Set it
+   * whenever you pass client-controlled URLs to the browser.
+   *
+   * Leaving it unset (the default) is NOT unguarded: it turns
+   * {@link LunoraBrowserOptions.resolveDns} on, so every host is resolved over
+   * DoH and refused if it maps to a private address. Setting an allowlist turns
+   * that re-check off (the allowlist is the stronger guard, and may deliberately
+   * name an internal host); `resolveDns: true` forces both.
+   */
   allowedHosts?: string[];
   /**
-  * Opt out of the SSRF guard that, by default, refuses to navigate to a
-  * private / internal / loopback / link-local host (RFC1918, `127.0.0.0/8`,
-  * `169.254.0.0/16` incl. the cloud-metadata address, CGNAT, IPv6 ULA/
-  * link-local, and `localhost` / `*.internal` / `*.local` literals). Leave it
-  * `false` (the default) unless every caller-supplied URL is trusted — e.g.
-  * you deliberately drive the browser at an internal service reachable through
-  * a Cloudflare Tunnel / private-network binding. Setting it `true` re-opens
-  * the SSRF surface, so never combine it with caller-controlled URLs.
-  */
+   * Opt out of the SSRF guard that, by default, refuses to navigate to a
+   * private / internal / loopback / link-local host (RFC1918, `127.0.0.0/8`,
+   * `169.254.0.0/16` incl. the cloud-metadata address, CGNAT, IPv6 ULA/
+   * link-local, and `localhost` / `*.internal` / `*.local` literals). Leave it
+   * `false` (the default) unless every caller-supplied URL is trusted — e.g.
+   * you deliberately drive the browser at an internal service reachable through
+   * a Cloudflare Tunnel / private-network binding. Setting it `true` re-opens
+   * the SSRF surface, so never combine it with caller-controlled URLs.
+   */
   allowPrivateTargets?: boolean;
   /** The Cloudflare Browser Rendering binding (`env.BROWSER`). Required. */
   binding: BrowserBindingLike;
   /**
-  * The `@cloudflare/playwright` `launch` function. Injected rather than
-  * imported at module top so the optional peer dep stays out of the bundle
-  * for non-browser apps and tests can pass a double. The generated worker
-  * passes the real function; omitting it makes the helper throw on first use
-  * with a clear "install `@cloudflare/playwright`" error.
-  */
+   * The `@cloudflare/playwright` `connect` function, injected like
+   * {@link LunoraBrowserOptions.launch}. Required for {@link Browser.connect}.
+   */
+  connect?: BrowserConnectLike;
+  /**
+   * The `@cloudflare/playwright` `launch` function. Injected rather than
+   * imported at module top so the optional peer dep stays out of the bundle
+   * for non-browser apps and tests can pass a double. The generated worker
+   * passes the real function; omitting it makes the helper throw on first use
+   * with a clear "install `@cloudflare/playwright`" error.
+   */
   launch?: BrowserLaunchLike;
   /**
-  * Best-effort DNS-rebinding re-check. When `true` (and `allowPrivateTargets`
-  * is `false`), the factory resolves the URL's hostname over Cloudflare DoH
-  * (`https://cloudflare-dns.com/dns-query`) and refuses to navigate if any
-  * resolved A/AAAA record is a private/internal address — closing the gap
-  * where a public hostname resolves to a private IP after the string guard
-  * passes. Off by default: it adds a DNS round-trip and is TOCTOU-imperfect
-  * (the browser re-resolves independently). If the DoH lookup itself fails, it
-  * falls back to the string guard rather than allowing a resolved private IP.
-  * For a hard guarantee prefer {@link LunoraBrowserOptions.allowedHosts}.
-  */
+   * Best-effort DNS-rebinding re-check. When `true` (and `allowPrivateTargets`
+   * is `false`), the factory resolves the URL's hostname over Cloudflare DoH
+   * (`https://cloudflare-dns.com/dns-query`) and refuses to navigate if any
+   * resolved A/AAAA record is a private/internal address — closing the gap
+   * where a public hostname resolves to a private IP after the string guard
+   * passes.
+   *
+   * **On by default when no {@link LunoraBrowserOptions.allowedHosts} is set**,
+   * because a `scrape`/`screenshot` action that forwards a client-supplied URL
+   * is the common shape and the string guard alone lets
+   * `http://127.0.0.1.nip.io:8787/…` through to an internal service. It costs
+   * one DNS round-trip per navigation and is TOCTOU-imperfect (the browser
+   * re-resolves independently), and if the DoH lookup itself fails it falls
+   * back to the string guard rather than allowing a resolved private IP.
+   *
+   * Configuring `allowedHosts` turns it OFF by default: an exact-origin
+   * allowlist is the stronger guard and may deliberately name an internal host
+   * (reachable over a Tunnel / private-network binding) that a resolved-address
+   * check would refuse. Set this explicitly to `true` to run both, or to
+   * `false` for trusted, non-caller-supplied URLs where the round-trip matters.
+   */
   resolveDns?: boolean;
   /**
-  * Default navigation timeout (ms) applied when a per-call `timeoutMs` is not
-  * given. Clamped to the factory's `MAX_TIMEOUT_MS`. Default 30000.
-  */
+   * The `@cloudflare/playwright` `sessions` function, injected like
+   * {@link LunoraBrowserOptions.launch}. Required for {@link Browser.sessions}.
+   */
+  sessions?: BrowserSessionsLike;
+  /**
+   * Default navigation timeout (ms) applied when a per-call `timeoutMs` is not
+   * given. Clamped to the factory's `MAX_TIMEOUT_MS`. Default 30000.
+   */
   timeoutMs?: number;
 }
 /**
-* The `ctx.browser` surface — Cloudflare Browser Rendering driven through
-* `@cloudflare/playwright`. **Action-only**: every method performs
-* non-deterministic network I/O (it navigates a real headless browser to a
-* URL), so codegen wires it onto `ActionCtx` exclusively — never `QueryCtx`/
-* `MutationCtx` — exactly like `ctx.ai` / `ctx.fetch`. Each helper launches a
-* browser, opens a context + page, navigates, performs the op, and always
-* closes the browser in a `finally` (a leaked session is billed and
-* rate-limited).
-*/
+ * The `ctx.browser` surface — Cloudflare Browser Rendering driven through
+ * `@cloudflare/playwright`. **Action-only**: every method performs
+ * non-deterministic network I/O (it navigates a real headless browser to a
+ * URL), so codegen wires it onto `ActionCtx` exclusively — never `QueryCtx`/
+ * `MutationCtx` — exactly like `ctx.ai` / `ctx.fetch`. Each helper launches a
+ * browser, opens a context + page, navigates, performs the op, and always
+ * closes the browser in a `finally` (a leaked session is billed and
+ * rate-limited).
+ * @experimental
+ */
 interface Browser {
+  /**
+   * Re-attach to an existing session and hand the browser to `fn`.
+   *
+   * Get the id either by reading it inside the call that opened the session
+   * (`launch(async (browser) => browser.sessionId?.(), { keepAlive: 600 })`)
+   * and persisting it, or by picking a free one out of
+   * {@link Browser.sessions} — an entry with a `connectionId` is already held
+   * by another worker.
+   *
+   * The session is deliberately **left open** afterwards — closing it is the
+   * whole thing you are avoiding. Close it when the flow is done by passing
+   * `close: true`, or let `keepAlive` lapse.
+   *
+   * This is what makes agent-style browsing possible: a model calls
+   * `navigate`, then `click`, then `extract` as three separate action
+   * invocations, and the page has to survive between them. With only the
+   * per-call lifecycle each step got a fresh browser, so `click` ran against
+   * a blank page — silently, which is the worst shape for that bug.
+   */
+  connect: <T>(sessionId: string, function_: (browser: BrowserLike) => Promise<T>, options?: {
+    close?: boolean;
+  }) => Promise<T>;
   /** Serialized HTML of `url` after navigation settles. */
   content: (url: string, options?: NavigateOptions) => Promise<string>;
   /**
-  * Low-level escape hatch: launch a raw Playwright `Browser` and hand it to
-  * `fn` (e.g. for multi-page flows or APIs not surfaced here). The browser is
-  * **always closed** when `fn` resolves or throws — do not retain references
-  * to it past the callback.
-  */
-  launch: <T>(function_: (browser: BrowserLike) => Promise<T>) => Promise<T>;
+   * Low-level escape hatch: launch a raw Playwright `Browser` and hand it to
+   * `fn` (e.g. for multi-page flows or APIs not surfaced here).
+   *
+   * The browser is **always closed** when `fn` resolves or throws — unless
+   * `keepAlive` is a number of seconds **between 10 and 600**, which holds the
+   * session open for that long so a later {@link Browser.connect} can
+   * re-attach. `0`, a negative value and `NaN` all mean "do not keep alive"
+   * and take the always-close path (a held session is billed, so the
+   * ambiguous values fall to the safe side); a positive value outside the
+   * 10–600s window Browser Rendering accepts throws `BAD_REQUEST` rather than
+   * being sent on for the provider to refuse. Do not retain references to the
+   * browser past the callback either way.
+   */
+  launch: <T>(function_: (browser: BrowserLike) => Promise<T>, options?: {
+    keepAlive?: number;
+  }) => Promise<T>;
   /** Render `url` to a PDF buffer. */
   pdf: (url: string, options?: PdfOptions) => Promise<Uint8Array>;
   /**
-  * Navigate to `url`, run `fn` inside the page context, and return its
-  * (serializable) result. `fn` runs in the browser, not the worker — it
-  * cannot close over worker-side variables.
-  */
+   * Navigate to `url`, run `fn` inside the page context, and return its
+   * (serializable) result. `fn` runs in the browser, not the worker — it
+   * cannot close over worker-side variables.
+   */
   scrape: <T>(url: string, function_: (...args: never[]) => T, options?: NavigateOptions) => Promise<T>;
   /** Render `url` to an image buffer (PNG by default). */
   screenshot: (url: string, options?: ScreenshotOptions) => Promise<Uint8Array>;
+  /**
+   * List the live Browser Rendering sessions for this binding, so a caller can
+   * pick a free one to {@link Browser.connect} to. An entry with a
+   * `connectionId` is already held by another worker.
+   */
+  sessions: () => Promise<ReadonlyArray<BrowserSession>>;
 }
+/**
+ * `createBrowser` is part of the experimental `@lunora/browser` API and may change without a major version bump.
+ * @experimental
+ */
 declare const createBrowser: (options: LunoraBrowserOptions) => Browser;
 export { type Browser, type BrowserBindingLike, type BrowserContextLike, type BrowserLaunchLike, type BrowserLike, type LunoraBrowserOptions, type NavigateOptions, type PageLike, type PdfOptions, type ScreenshotOptions, createBrowser };

package/dist/index.mjs

@@ -1 +1 @@
-export { createBrowser } from './packem_shared/createBrowser-BaV8oQ-4.mjs';
+import{createBrowser as o}from"./packem_shared/createBrowser-CN6x72HL.mjs";export{o as createBrowser};

package/dist/packem_shared/createBrowser-CN6x72HL.mjs

@@ -0,0 +1 @@
+import{LunoraError as u}from"@lunora/errors";const x=/^\d{1,3}$/u,C=/^::ffff:([\da-f]{1,4}):([\da-f]{1,4})$/u,F=/^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/u,X=/^::(\d{1,3}(?:\.\d{1,3}){3})$/u,Q=/^::([\da-f]{1,4}):([\da-f]{1,4})$/u,z=/^64:ff9b::[\da-f]{1,4}:[\da-f]{1,4}$/u,G=/^\[|\]$/gu,j=/\.$/u,v=t=>{const e=t.split(".");if(e.length!==4)return;const r=e.map(n=>x.test(n)?Number(n):-1);if(!r.some(n=>n<0||n>255))return[r[0],r[1],r[2],r[3]]},y=([t,e])=>t===0||t===10||t===127||t===100&&e>=64&&e<=127||t===169&&e===254||t===172&&e>=16&&e<=31||t===192&&e===168||t>=224,D=(t,e)=>{const r=Number.parseInt(t??"",16),n=Number.parseInt(e??"",16);return!Number.isFinite(r)||!Number.isFinite(n)?!0:y([Math.floor(r/256),r%256,Math.floor(n/256),n%256])},L=t=>{const e=t.toLowerCase(),r=C.exec(e);if(r)return D(r[1],r[2]);const n=F.exec(e);if(n){const f=v(n[1]??"");return f===void 0||y(f)}const i=X.exec(e);if(i){const f=v(i[1]??"");return f===void 0||y(f)}const c=Q.exec(e);return c?D(c[1],c[2]):z.test(e)||e.startsWith("2002:")||e.startsWith("2001:0:")?!0:e==="::"||e==="::1"||e.startsWith("fc")||e.startsWith("fd")||e.startsWith("fe8")||e.startsWith("fe9")||e.startsWith("fea")||e.startsWith("feb")},q=t=>t==="localhost"||t.endsWith(".localhost")||t.endsWith(".local")||t.endsWith(".internal")||t.endsWith(".home.arpa"),h=t=>t.replaceAll(G,"").replace(j,"").toLowerCase(),O=t=>{const e=h(t);if(e.includes(":"))return L(e);const r=v(e);return r===void 0?q(e):y(r)},Y="https://cloudflare-dns.com/dns-query",T=1,N=28,J=2e3,Z=(t,e)=>{if(e===T){const r=v(t);return r===void 0||y(r)}return L(t.toLowerCase())},S=async(t,e,r)=>{try{const n=await fetch(`${Y}?name=${encodeURIComponent(t)}&type=${String(e)}`,{headers:{accept:"application/dns-json"},signal:AbortSignal.timeout(r)});return n.ok?(await n.json()).Answer??[]:void 0}catch{return}},K=async(t,e=J)=>{const r=h(t);if(r.includes(":")||v(r)!==void 0)return{kind:"unknown"};const[n,i]=await Promise.all([S(r,T,e),S(r,N,e)]);if(n===void 0&&i===void 0)return{kind:"unknown"};for(const c of[...n??[],...i??[]])if((c.type===T||c.type===N)&&Z(c.data,c.type))return{address:c.data,kind:"private"};return{kind:"public"}},A=3e4,tt=12e4,et=3840,rt=4320,R=10,M=600,U=5e3,$=async(t,e=U)=>{const r=h(new URL(t).hostname),n=await K(r,e);if(n.kind==="private")throw new u("FORBIDDEN",`@lunora/browser: url host "${r}" resolves to a private/internal address (${n.address}); refusing to navigate (DNS-rebinding guard)`)},B=(t,e,r)=>{if(typeof t!="string"||t.length===0)throw new u("BAD_REQUEST","@lunora/browser: url must be a non-empty string");let n;try{n=new URL(t)}catch{throw new u("BAD_REQUEST",`@lunora/browser: url must be an absolute http(s) URL (got "${t}")`)}if(n.protocol!=="http:"&&n.protocol!=="https:")throw new u("BAD_REQUEST",`@lunora/browser: url protocol must be http(s) (got "${n.protocol}")`);if(n.username!==""||n.password!=="")throw new u("BAD_REQUEST","@lunora/browser: url must not embed credentials (strip the `user:pass@` userinfo)");if(r&&r.length>0){const i=h(n.hostname);if(!r.some(c=>h(c)===i))throw new u("FORBIDDEN",`@lunora/browser: url host "${n.hostname}" is not in the configured allowedHosts allowlist`)}if(!e&&O(n.hostname))throw new u("FORBIDDEN",`@lunora/browser: url host "${n.hostname}" is a private/internal address; pass createBrowser({ …, allowPrivateTargets: true }) to allow it`);return n.toString()},H=(t,e)=>Number.isFinite(t)?Math.min(Math.max(1,Math.floor(t)),e):e,nt=t=>({height:H(t.height,rt),width:H(t.width,et)}),ot=(t,e)=>{const r=t??e??A,n=Number.isFinite(r)?r:A;return Math.min(Math.max(1,Math.floor(n)),tt)},st=async(t,e)=>{let r;try{return await Promise.race([t(),new Promise((n,i)=>{r=setTimeout(()=>{i(new u("BROWSER_TIMEOUT",`@lunora/browser: navigation + operation exceeded the ${String(e)}ms timeout budget`,{status:504}))},e)})])}finally{r!==void 0&&clearTimeout(r)}},k=async t=>{try{await t.close()}catch{}},ht=t=>{if(!t.binding)throw new TypeError("@lunora/browser: `binding` is required (env.BROWSER)");const e=()=>{if(!t.launch)throw new u("INTERNAL",'@lunora/browser: `launch` is not available — install the `@cloudflare/playwright` peer dependency. The generated worker wires it for you; outside codegen pass it via createBrowser({ binding, launch }) (import { launch } from "@cloudflare/playwright").');return t.launch},r=(s,o)=>{if(!s)throw new u("INTERNAL",`@lunora/browser: \`${o}\` is not available — install the \`@cloudflare/playwright\` peer dependency. The generated worker wires it for you; outside codegen pass it via createBrowser({ binding, ${o} }).`);return s},n=async(s,o)=>{const a=o!==void 0&&Number.isFinite(o)&&o>0?o:void 0;if(a!==void 0&&(a<R||a>M))throw new u("BAD_REQUEST",`@lunora/browser: keepAlive must be between ${String(R)} and ${String(M)} seconds (Browser Rendering accepts keep_alive from 10s to 10min; got ${String(o)})`);const l=await e()(t.binding,a===void 0?void 0:{keep_alive:a*1e3});if(a!==void 0)return await s(l);try{return await s(l)}finally{await k(l)}},i=async(s,o,a,l)=>{const p=t.allowPrivateTargets??!1,_=B(s,p,t.allowedHosts),E=ot(o.timeoutMs,t.timeoutMs),I=t.resolveDns??(t.allowedHosts?.length??0)===0,P=Math.min(E,U);!p&&I&&await $(_,P);const W=async m=>{B(m,p,t.allowedHosts),!p&&I&&await $(m,P)},V=m=>{let g;try{g=new URL(m)}catch{return!1}if(g.protocol!=="http:"&&g.protocol!=="https:")return!1;if(t.allowedHosts&&t.allowedHosts.length>0){const d=h(g.hostname);if(!t.allowedHosts.some(w=>h(w)===d))return!0}return O(g.hostname)};return n(async m=>{const d=await(await m.newContext()).newPage();return d.route&&(!p||(t.allowedHosts?.length??0)>0)&&await d.route("**/*",async w=>{const b=w.request();if(!(b.isNavigationRequest?.()??!0)){if(V(b.url())){await w.abort("blockedbyclient");return}await w.continue();return}try{await W(b.url())}catch{await w.abort("blockedbyclient");return}await w.continue()}),l&&d.setViewportSize&&await d.setViewportSize(nt(l)),st(async()=>(await d.goto(_,{timeout:E,waitUntil:o.waitUntil??"load"}),a(d)),E)})};return{connect:async(s,o,a={})=>{const l=await r(t.connect,"connect")(t.binding,s);if(a.close!==!0)return await o(l);try{return await o(l)}finally{await k(l)}},content:async(s,o={})=>i(s,o,async a=>a.content()),launch:async(s,o={})=>n(s,o.keepAlive),pdf:async(s,o={})=>i(s,o,async a=>a.pdf({format:o.format,printBackground:o.printBackground??!1}),o.viewport),scrape:async(s,o,a={})=>i(s,a,async l=>l.evaluate(o)),screenshot:async(s,o={})=>i(s,o,async a=>a.screenshot({fullPage:o.fullPage??!1,type:o.type??"png"}),o.viewport),sessions:async()=>await r(t.sessions,"sessions")(t.binding)}};export{ht as createBrowser};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/browser",
-  "version": "1.0.0-alpha.4",
+  "version": "1.0.0-alpha.40",
   "description": "Cloudflare Browser Rendering for Lunora: ctx.browser screenshots, PDF, and scraping in actions",
   "keywords": [
     "browser-rendering",
@@ -46,7 +46,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/errors": "1.0.0-alpha.1"
+    "@lunora/errors": "1.0.0-alpha.31"
   },
   "peerDependencies": {
     "@cloudflare/playwright": ">=1.0.0"

package/dist/packem_shared/createBrowser-BaV8oQ-4.mjs

@@ -1,273 +0,0 @@
-import { LunoraError } from '@lunora/errors';
-
-const DEFAULT_TIMEOUT_MS = 3e4;
-const MAX_TIMEOUT_MS = 12e4;
-const MAX_VIEWPORT_WIDTH = 3840;
-const MAX_VIEWPORT_HEIGHT = 4320;
-const IPV4_OCTET = /^\d{1,3}$/;
-const IPV6_MAPPED_HEX = /^::ffff:([\da-f]{1,4}):([\da-f]{1,4})$/;
-const IPV6_MAPPED_DOTTED = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/;
-const IPV6_COMPATIBLE_DOTTED = /^::(\d{1,3}(?:\.\d{1,3}){3})$/;
-const IPV6_COMPATIBLE_HEX = /^::([\da-f]{1,4}):([\da-f]{1,4})$/;
-const IPV6_NAT64_HEX = /^64:ff9b::[\da-f]{1,4}:[\da-f]{1,4}$/;
-const IPV6_BRACKETS = /^\[|\]$/g;
-const TRAILING_DOT = /\.$/;
-const parseIpv4 = (host) => {
-  const parts = host.split(".");
-  if (parts.length !== 4) {
-    return void 0;
-  }
-  const octets = parts.map((part) => IPV4_OCTET.test(part) ? Number(part) : -1);
-  if (octets.some((octet) => octet < 0 || octet > 255)) {
-    return void 0;
-  }
-  const result = [octets[0], octets[1], octets[2], octets[3]];
-  return result;
-};
-const isPrivateIpv4 = ([a, b]) => a === 0 || // 0.0.0.0/8 "this host"
-a === 10 || // 10.0.0.0/8 private
-a === 127 || // 127.0.0.0/8 loopback
-a === 100 && b >= 64 && b <= 127 || // 100.64.0.0/10 CGNAT
-a === 169 && b === 254 || // 169.254.0.0/16 link-local (incl. 169.254.169.254 metadata)
-a === 172 && b >= 16 && b <= 31 || // 172.16.0.0/12 private
-a === 192 && b === 168 || // 192.168.0.0/16 private
-a >= 224;
-const isPrivateEmbeddedIpv4 = (highGroup, lowGroup) => {
-  const high = Number.parseInt(highGroup ?? "", 16);
-  const low = Number.parseInt(lowGroup ?? "", 16);
-  if (!Number.isFinite(high) || !Number.isFinite(low)) {
-    return true;
-  }
-  return isPrivateIpv4([Math.floor(high / 256), high % 256, Math.floor(low / 256), low % 256]);
-};
-const isPrivateIpv6 = (host) => {
-  const ip = host.toLowerCase();
-  const mappedHex = IPV6_MAPPED_HEX.exec(ip);
-  if (mappedHex) {
-    return isPrivateEmbeddedIpv4(mappedHex[1], mappedHex[2]);
-  }
-  const mappedDotted = IPV6_MAPPED_DOTTED.exec(ip);
-  if (mappedDotted) {
-    const v4 = parseIpv4(mappedDotted[1] ?? "");
-    return v4 === void 0 || isPrivateIpv4(v4);
-  }
-  const compatDotted = IPV6_COMPATIBLE_DOTTED.exec(ip);
-  if (compatDotted) {
-    const v4 = parseIpv4(compatDotted[1] ?? "");
-    return v4 === void 0 || isPrivateIpv4(v4);
-  }
-  const compatHex = IPV6_COMPATIBLE_HEX.exec(ip);
-  if (compatHex) {
-    return isPrivateEmbeddedIpv4(compatHex[1], compatHex[2]);
-  }
-  if (IPV6_NAT64_HEX.test(ip)) {
-    return true;
-  }
-  return ip === "::" || // unspecified
-  ip === "::1" || // loopback
-  ip.startsWith("fc") || // fc00::/7 unique-local
-  ip.startsWith("fd") || // fc00::/7 unique-local
-  ip.startsWith("fe8") || // fe80::/10 link-local
-  ip.startsWith("fe9") || ip.startsWith("fea") || ip.startsWith("feb");
-};
-const DOH_ENDPOINT = "https://cloudflare-dns.com/dns-query";
-const DOH_TIMEOUT_MS = 5e3;
-const DNS_TYPE_A = 1;
-const DNS_TYPE_AAAA = 28;
-const normalizeHost = (host) => host.replaceAll(IPV6_BRACKETS, "").replace(TRAILING_DOT, "").toLowerCase();
-const isPrivateResolvedIp = (data, type) => {
-  if (type === DNS_TYPE_A) {
-    const v4 = parseIpv4(data);
-    return v4 === void 0 || isPrivateIpv4(v4);
-  }
-  return isPrivateIpv6(data.toLowerCase());
-};
-const dohLookup = async (hostname, type, timeoutMs = DOH_TIMEOUT_MS) => {
-  try {
-    const response = await fetch(`${DOH_ENDPOINT}?name=${encodeURIComponent(hostname)}&type=${String(type)}`, {
-      headers: { accept: "application/dns-json" },
-      // Bound the lookup so a stalled resolver can't hang the worker; an
-      // abort surfaces as a rejection caught below → `undefined` → the
-      // caller falls back to the (already-passed) string guard.
-      signal: AbortSignal.timeout(timeoutMs)
-    });
-    if (!response.ok) {
-      return void 0;
-    }
-    const body = await response.json();
-    return body.Answer ?? [];
-  } catch {
-    return void 0;
-  }
-};
-const assertResolvedHostIsPublic = async (target, timeoutMs = DOH_TIMEOUT_MS) => {
-  const host = normalizeHost(new URL(target).hostname);
-  if (host.includes(":") || parseIpv4(host) !== void 0) {
-    return;
-  }
-  const [aRecords, aaaaRecords] = await Promise.all([dohLookup(host, DNS_TYPE_A, timeoutMs), dohLookup(host, DNS_TYPE_AAAA, timeoutMs)]);
-  if (aRecords === void 0 && aaaaRecords === void 0) {
-    return;
-  }
-  for (const answer of [...aRecords ?? [], ...aaaaRecords ?? []]) {
-    if ((answer.type === DNS_TYPE_A || answer.type === DNS_TYPE_AAAA) && isPrivateResolvedIp(answer.data, answer.type)) {
-      throw new LunoraError(
-        "FORBIDDEN",
-        `@lunora/browser: url host "${host}" resolves to a private/internal address (${answer.data}); refusing to navigate (DNS-rebinding guard)`
-      );
-    }
-  }
-};
-const isPrivateHostname = (host) => host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local") || host.endsWith(".internal") || host.endsWith(".home.arpa");
-const isPrivateTarget = (parsed) => {
-  const host = parsed.hostname.replaceAll(IPV6_BRACKETS, "").replace(TRAILING_DOT, "");
-  if (host.includes(":")) {
-    return isPrivateIpv6(host);
-  }
-  const v4 = parseIpv4(host);
-  return v4 === void 0 ? isPrivateHostname(host.toLowerCase()) : isPrivateIpv4(v4);
-};
-const validateUrl = (url, allowPrivateTargets, allowedHosts) => {
-  if (typeof url !== "string" || url.length === 0) {
-    throw new TypeError("@lunora/browser: url must be a non-empty string");
-  }
-  let parsed;
-  try {
-    parsed = new URL(url);
-  } catch {
-    throw new TypeError(`@lunora/browser: url must be an absolute http(s) URL (got "${url}")`);
-  }
-  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-    throw new TypeError(`@lunora/browser: url protocol must be http(s) (got "${parsed.protocol}")`);
-  }
-  if (parsed.username !== "" || parsed.password !== "") {
-    throw new LunoraError("INTERNAL", "@lunora/browser: url must not embed credentials (strip the `user:pass@` userinfo)");
-  }
-  if (allowedHosts && allowedHosts.length > 0) {
-    const host = normalizeHost(parsed.hostname);
-    if (!allowedHosts.some((entry) => normalizeHost(entry) === host)) {
-      throw new LunoraError("FORBIDDEN", `@lunora/browser: url host "${parsed.hostname}" is not in the configured allowedHosts allowlist`);
-    }
-  }
-  if (!allowPrivateTargets && isPrivateTarget(parsed)) {
-    throw new LunoraError(
-      "INTERNAL",
-      `@lunora/browser: url host "${parsed.hostname}" is a private/internal address; pass createBrowser({ …, allowPrivateTargets: true }) to allow it`
-    );
-  }
-  return parsed.toString();
-};
-const clampDimension = (value, max) => {
-  if (!Number.isFinite(value)) {
-    return max;
-  }
-  return Math.min(Math.max(1, Math.floor(value)), max);
-};
-const clampViewport = (viewport) => {
-  return {
-    height: clampDimension(viewport.height, MAX_VIEWPORT_HEIGHT),
-    width: clampDimension(viewport.width, MAX_VIEWPORT_WIDTH)
-  };
-};
-const resolveTimeout = (callTimeout, factoryTimeout) => {
-  const requested = callTimeout ?? factoryTimeout ?? DEFAULT_TIMEOUT_MS;
-  const safe = Number.isFinite(requested) ? requested : DEFAULT_TIMEOUT_MS;
-  return Math.min(Math.max(1, Math.floor(safe)), MAX_TIMEOUT_MS);
-};
-const createBrowser = (options) => {
-  if (!options.binding) {
-    throw new TypeError("@lunora/browser: `binding` is required (env.BROWSER)");
-  }
-  const getLaunch = () => {
-    if (!options.launch) {
-      throw new LunoraError(
-        "INTERNAL",
-        '@lunora/browser: `launch` is not available — install the `@cloudflare/playwright` peer dependency. The generated worker wires it for you; outside codegen pass it via createBrowser({ binding, launch }) (import { launch } from "@cloudflare/playwright").'
-      );
-    }
-    return options.launch;
-  };
-  const withBrowser = async (use) => {
-    const browser = await getLaunch()(options.binding);
-    try {
-      return await use(browser);
-    } finally {
-      try {
-        await browser.close();
-      } catch {
-      }
-    }
-  };
-  const withPage = async (url, navigate, use, viewport) => {
-    const allowPrivateTargets = options.allowPrivateTargets ?? false;
-    const target = validateUrl(url, allowPrivateTargets, options.allowedHosts);
-    const timeout = resolveTimeout(navigate.timeoutMs, options.timeoutMs);
-    const resolveDns = options.resolveDns ?? false;
-    const dohTimeout = Math.min(timeout, DOH_TIMEOUT_MS);
-    if (!allowPrivateTargets && resolveDns) {
-      await assertResolvedHostIsPublic(target, dohTimeout);
-    }
-    const assertNavigationAllowed = async (requestUrl) => {
-      validateUrl(requestUrl, allowPrivateTargets, options.allowedHosts);
-      if (resolveDns) {
-        await assertResolvedHostIsPublic(requestUrl, dohTimeout);
-      }
-    };
-    return withBrowser(async (browser) => {
-      const context = await browser.newContext();
-      const page = await context.newPage();
-      if (!allowPrivateTargets && page.route) {
-        await page.route("**/*", async (route) => {
-          const request = route.request();
-          const isNavigation = request.isNavigationRequest?.() ?? true;
-          if (!isNavigation) {
-            await route.continue();
-            return;
-          }
-          try {
-            await assertNavigationAllowed(request.url());
-          } catch {
-            await route.abort("blockedbyclient");
-            return;
-          }
-          await route.continue();
-        });
-      }
-      if (viewport && page.setViewportSize) {
-        await page.setViewportSize(clampViewport(viewport));
-      }
-      await page.goto(target, { timeout, waitUntil: navigate.waitUntil ?? "load" });
-      return use(page);
-    });
-  };
-  const screenshot = async (url, screenshotOptions = {}) => withPage(
-    url,
-    screenshotOptions,
-    async (page) => page.screenshot({
-      fullPage: screenshotOptions.fullPage ?? false,
-      type: screenshotOptions.type ?? "png"
-    }),
-    screenshotOptions.viewport
-  );
-  const pdf = async (url, pdfOptions = {}) => withPage(
-    url,
-    pdfOptions,
-    async (page) => page.pdf({
-      format: pdfOptions.format,
-      printBackground: pdfOptions.printBackground ?? false
-    }),
-    pdfOptions.viewport
-  );
-  const content = async (url, navigateOptions = {}) => withPage(url, navigateOptions, async (page) => page.content());
-  const scrape = async (url, function_, navigateOptions = {}) => withPage(url, navigateOptions, async (page) => page.evaluate(function_));
-  const launch = async (function_) => withBrowser(function_);
-  return {
-    content,
-    launch,
-    pdf,
-    scrape,
-    screenshot
-  };
-};
-
-export { createBrowser };