@lunora/browser 1.0.0-alpha.6 → 1.0.0-alpha.8

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">

package/dist/index.d.mts

@@ -8,11 +8,14 @@
 *
 * 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.
+* 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: (...args: never[]) => unknown;
 }
 /**
 * Minimal projection of a Playwright `Route` (the argument the `page.route`
@@ -35,6 +38,7 @@ 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).
+* @experimental
 */
 interface PageLike {
   /** Return the page's serialized HTML after the navigation settles. */
@@ -66,6 +70,7 @@ interface 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>;
@@ -74,6 +79,7 @@ interface BrowserContextLike {
 * 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>;
@@ -86,9 +92,13 @@ interface BrowserLike {
 * `@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.). */
+/**
+* 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
@@ -102,7 +112,10 @@ interface NavigateOptions {
   */
   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;
@@ -117,7 +130,10 @@ interface ScreenshotOptions extends NavigateOptions {
     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;
@@ -132,6 +148,10 @@ interface PdfOptions extends NavigateOptions {
     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
@@ -191,6 +211,7 @@ interface LunoraBrowserOptions {
 * 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 {
   /** Serialized HTML of `url` after navigation settles. */
@@ -213,5 +234,9 @@ interface Browser {
   /** Render `url` to an image buffer (PNG by default). */
   screenshot: (url: string, options?: ScreenshotOptions) => Promise<Uint8Array>;
 }
+/**
+* `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

@@ -8,11 +8,14 @@
 *
 * 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.
+* 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: (...args: never[]) => unknown;
 }
 /**
 * Minimal projection of a Playwright `Route` (the argument the `page.route`
@@ -35,6 +38,7 @@ 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).
+* @experimental
 */
 interface PageLike {
   /** Return the page's serialized HTML after the navigation settles. */
@@ -66,6 +70,7 @@ interface 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>;
@@ -74,6 +79,7 @@ interface BrowserContextLike {
 * 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>;
@@ -86,9 +92,13 @@ interface BrowserLike {
 * `@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.). */
+/**
+* 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
@@ -102,7 +112,10 @@ interface NavigateOptions {
   */
   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;
@@ -117,7 +130,10 @@ interface ScreenshotOptions extends NavigateOptions {
     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;
@@ -132,6 +148,10 @@ interface PdfOptions extends NavigateOptions {
     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
@@ -191,6 +211,7 @@ interface LunoraBrowserOptions {
 * 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 {
   /** Serialized HTML of `url` after navigation settles. */
@@ -213,5 +234,9 @@ interface Browser {
   /** Render `url` to an image buffer (PNG by default). */
   screenshot: (url: string, options?: ScreenshotOptions) => Promise<Uint8Array>;
 }
+/**
+* `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';
+export { createBrowser } from './packem_shared/createBrowser-CZmfQ38r.mjs';

package/dist/packem_shared/{createBrowser-BaV8oQ-4.mjs → createBrowser-CZmfQ38r.mjs}

@@ -129,19 +129,19 @@ const isPrivateTarget = (parsed) => {
 };
 const validateUrl = (url, allowPrivateTargets, allowedHosts) => {
   if (typeof url !== "string" || url.length === 0) {
-    throw new TypeError("@lunora/browser: url must be a non-empty string");
+    throw new LunoraError("BAD_REQUEST", "@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}")`);
+    throw new LunoraError("BAD_REQUEST", `@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}")`);
+    throw new LunoraError("BAD_REQUEST", `@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)");
+    throw new LunoraError("BAD_REQUEST", "@lunora/browser: url must not embed credentials (strip the `user:pass@` userinfo)");
   }
   if (allowedHosts && allowedHosts.length > 0) {
     const host = normalizeHost(parsed.hostname);
@@ -151,7 +151,7 @@ const validateUrl = (url, allowPrivateTargets, allowedHosts) => {
   }
   if (!allowPrivateTargets && isPrivateTarget(parsed)) {
     throw new LunoraError(
-      "INTERNAL",
+      "FORBIDDEN",
       `@lunora/browser: url host "${parsed.hostname}" is a private/internal address; pass createBrowser({ …, allowPrivateTargets: true }) to allow it`
     );
   }
@@ -174,6 +174,27 @@ const resolveTimeout = (callTimeout, factoryTimeout) => {
   const safe = Number.isFinite(requested) ? requested : DEFAULT_TIMEOUT_MS;
   return Math.min(Math.max(1, Math.floor(safe)), MAX_TIMEOUT_MS);
 };
+const withDeadline = async (operation, timeoutMs) => {
+  let timer;
+  try {
+    return await Promise.race([
+      operation(),
+      new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+          reject(
+            new LunoraError("BROWSER_TIMEOUT", `@lunora/browser: navigation + operation exceeded the ${String(timeoutMs)}ms timeout budget`, {
+              status: 504
+            })
+          );
+        }, timeoutMs);
+      })
+    ]);
+  } finally {
+    if (timer !== void 0) {
+      clearTimeout(timer);
+    }
+  }
+};
 const createBrowser = (options) => {
   if (!options.binding) {
     throw new TypeError("@lunora/browser: `binding` is required (env.BROWSER)");
@@ -209,18 +230,40 @@ const createBrowser = (options) => {
     }
     const assertNavigationAllowed = async (requestUrl) => {
       validateUrl(requestUrl, allowPrivateTargets, options.allowedHosts);
-      if (resolveDns) {
+      if (!allowPrivateTargets && resolveDns) {
         await assertResolvedHostIsPublic(requestUrl, dohTimeout);
       }
     };
+    const isBlockedSubresource = (rawUrl) => {
+      let parsed;
+      try {
+        parsed = new URL(rawUrl);
+      } catch {
+        return false;
+      }
+      if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return false;
+      }
+      if (options.allowedHosts && options.allowedHosts.length > 0) {
+        const host = normalizeHost(parsed.hostname);
+        if (!options.allowedHosts.some((entry) => normalizeHost(entry) === host)) {
+          return true;
+        }
+      }
+      return isPrivateTarget(parsed);
+    };
     return withBrowser(async (browser) => {
       const context = await browser.newContext();
       const page = await context.newPage();
-      if (!allowPrivateTargets && page.route) {
+      if (page.route && (!allowPrivateTargets || (options.allowedHosts?.length ?? 0) > 0)) {
         await page.route("**/*", async (route) => {
           const request = route.request();
           const isNavigation = request.isNavigationRequest?.() ?? true;
           if (!isNavigation) {
+            if (isBlockedSubresource(request.url())) {
+              await route.abort("blockedbyclient");
+              return;
+            }
             await route.continue();
             return;
           }
@@ -236,8 +279,10 @@ const createBrowser = (options) => {
       if (viewport && page.setViewportSize) {
         await page.setViewportSize(clampViewport(viewport));
       }
-      await page.goto(target, { timeout, waitUntil: navigate.waitUntil ?? "load" });
-      return use(page);
+      return withDeadline(async () => {
+        await page.goto(target, { timeout, waitUntil: navigate.waitUntil ?? "load" });
+        return use(page);
+      }, timeout);
     });
   };
   const screenshot = async (url, screenshotOptions = {}) => withPage(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/browser",
-  "version": "1.0.0-alpha.6",
+  "version": "1.0.0-alpha.8",
   "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.3"
+    "@lunora/errors": "1.0.0-alpha.5"
   },
   "peerDependencies": {
     "@cloudflare/playwright": ">=1.0.0"