alchemy 2.0.0-beta.51 → 2.0.0-beta.52

package/src/Cloudflare/Browser/Browser.ts

@@ -32,9 +32,10 @@ type BindEffect = Effect.Effect<BrowserClient, never, BrowserBinding>;
  * Worker and returns the runtime {@link BrowserClient} — no separate
  * `.bind(...)` step required.
  *
- * The divergence is achieved via `[Symbol.iterator]`: the object is not an
- * `Effect` (so `InferEnv` resolves it to the native `Fetcher` in the `env`
- * position), but it is iterable as one when `yield*`-ed.
+ * The divergence is achieved via `[Symbol.iterator]`: the object is
+ * deliberately not an `Effect` (so `InferEnv` and the Worker `env` resolver
+ * keep it as the native `BrowserRun` rather than `yield*`-ing it), but it is
+ * iterable as one when `yield*`-ed.
  */
 export interface Browser {
   kind: BrowserTypeId;
@@ -53,7 +54,73 @@ export const isBrowser = (value: unknown): value is Browser =>
  * @binding
  *
  * @section Effect-style Worker (recommended)
- * @example Render a page title with managed browser cleanup
+ * @example Bind the runtime client and convert a page to Markdown
+ * Yielding the marker attaches the binding to the surrounding Worker and
+ * returns the runtime {@link BrowserClient}. Every `cf.BrowserRun` method is
+ * mirrored as an Effect, so no `Effect.tryPromise` wrapping is needed.
+ * ```typescript
+ * import * as Effect from "effect/Effect";
+ *
+ * Cloudflare.Worker(
+ *   "BrowserWorker",
+ *   { main: import.meta.filename },
+ *   Effect.gen(function* () {
+ *     const browser = yield* Cloudflare.Browser({ name: "BROWSER" });
+ *
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         return yield* browser.markdown({ url: "https://example.com" });
+ *       }),
+ *     };
+ *   }).pipe(Effect.provide(Cloudflare.BrowserBindingLive)),
+ * );
+ * ```
+ *
+ * @section Quick Actions
+ * @example Render content, screenshot, PDF, and structured data
+ * JSON quick actions resolve to their parsed payload; binary actions
+ * (`screenshot`, `pdf`) resolve to a `Stream` of bytes. No `Promise` or
+ * `Response.json()` in sight.
+ * ```typescript
+ * import * as Effect from "effect/Effect";
+ * import * as Stream from "effect/Stream";
+ *
+ * const browser = yield* Cloudflare.Browser({ name: "BROWSER" });
+ * const url = "https://example.com";
+ *
+ * // HTML content — parsed payload, title lives in `meta`.
+ * const content = yield* browser.content({ url });
+ * const title = content.meta.title;
+ *
+ * // Scrape elements by CSS selector.
+ * yield* browser.scrape({ url, elements: [{ selector: "h1" }] });
+ *
+ * // Extract all links.
+ * const { result: links } = yield* browser.links({ url });
+ *
+ * // Binary actions stream bytes — collect or pipe them.
+ * const png = yield* browser.screenshot({ url }).pipe(Stream.runCollect);
+ * const pdf = yield* browser.pdf({ url }).pipe(Stream.runCollect);
+ *
+ * // AI-extracted structured data.
+ * yield* browser.json({ url, prompt: "Extract the page heading" });
+ * ```
+ *
+ * @example Call the generic `quickAction` directly
+ * The named methods are thin wrappers over `quickAction`, which mirrors
+ * `cf.BrowserRun["quickAction"]` one-to-one.
+ * ```typescript
+ * const browser = yield* Cloudflare.Browser({ name: "BROWSER" });
+ *
+ * const res = yield* browser.quickAction("snapshot", {
+ *   url: "https://example.com",
+ * });
+ * ```
+ *
+ * @section Driving Puppeteer
+ * @example Use the raw `cf.BrowserRun` binding with `@cloudflare/puppeteer`
+ * `raw` hands you the underlying runtime binding. Puppeteer is promise-based,
+ * so this is the one place you reach for `Effect.tryPromise`.
  * ```typescript
  * import puppeteer from "@cloudflare/puppeteer";
  * import * as Effect from "effect/Effect";
@@ -62,25 +129,30 @@ export const isBrowser = (value: unknown): value is Browser =>
  *   "BrowserWorker",
  *   { main: import.meta.filename },
  *   Effect.gen(function* () {
- *     // Attaches the binding to this Worker AND returns the runtime client.
  *     const browser = yield* Cloudflare.Browser({ name: "BROWSER" });
  *
  *     return {
- *       fetch: browser.withBrowser(puppeteer, (browser) =>
- *         Effect.gen(function* () {
- *           const page = yield* Effect.tryPromise(() => browser.newPage());
+ *       fetch: Effect.gen(function* () {
+ *         const binding = yield* browser.raw;
+ *         const session = yield* Effect.tryPromise(() =>
+ *           puppeteer.launch(binding),
+ *         );
+ *         try {
+ *           const page = yield* Effect.tryPromise(() => session.newPage());
  *           yield* Effect.tryPromise(() => page.goto("https://example.com"));
  *           const title = yield* Effect.tryPromise(() => page.title());
  *           return Response.json({ title });
- *         }),
- *       ),
+ *         } finally {
+ *           yield* Effect.promise(() => session.close());
+ *         }
+ *       }),
  *     };
  *   }).pipe(Effect.provide(Cloudflare.BrowserBindingLive)),
  * );
  * ```
  *
  * @section Worker binding metadata
- * @example
+ * @example Declare the binding on `env`
  * ```typescript
  * export const Worker = Cloudflare.Worker("Worker", {
  *   main: "./src/worker.ts",
@@ -90,7 +162,7 @@ export const isBrowser = (value: unknown): value is Browser =>
  * });
  *
  * export type WorkerEnv = Cloudflare.InferEnv<typeof Worker>;
- * //   { BROWSER: Fetcher }
+ * //   { BROWSER: BrowserRun }
  * ```
  *
  * @example Async-style worker with the raw runtime binding

package/src/Cloudflare/Browser/BrowserBinding.ts

@@ -2,8 +2,10 @@ import type * as cf from "@cloudflare/workers-types";
 import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
+import * as Stream from "effect/Stream";
 import * as Binding from "../../Binding.ts";
 import type { ResourceLike } from "../../Resource.ts";
+import type { RuntimeContext } from "../../RuntimeContext.ts";
 import { isWorker, WorkerEnvironment } from "../Workers/Worker.ts";
 import type { Browser as BrowserLike } from "./Browser.ts";
 
@@ -12,39 +14,143 @@ export class BrowserError extends Data.TaggedError("BrowserError")<{
   cause: unknown;
 }> {}
 
-export interface BrowserHandle {
-  close(): Promise<void>;
-}
+/** The `Response` type returned by the Cloudflare Browser Rendering binding. */
+type BrowserResponse = Awaited<ReturnType<cf.BrowserRun["fetch"]>>;
 
-export interface BrowserPuppeteer<Browser extends BrowserHandle> {
-  launch(binding: cf.Fetcher): Promise<Browser>;
-}
+/** An Effect produced by a {@link BrowserClient} operation. */
+type BrowserEffect<A> = Effect.Effect<A, BrowserError, RuntimeContext>;
+
+/** A byte stream produced by a binary {@link BrowserClient} action. */
+type BrowserByteStream = Stream.Stream<
+  Uint8Array,
+  BrowserError,
+  RuntimeContext
+>;
+
+// Quick action option types, re-exported so callers don't reach into the
+// `@cloudflare/workers-types` namespace directly.
+export type BrowserScreenshotOptions = cf.BrowserRunScreenshotOptions;
+export type BrowserPDFOptions = cf.BrowserRunPDFOptions;
+export type BrowserContentOptions = cf.BrowserRunContentOptions;
+export type BrowserScrapeOptions = cf.BrowserRunScrapeOptions;
+export type BrowserLinksOptions = cf.BrowserRunLinksOptions;
+export type BrowserSnapshotOptions = cf.BrowserRunSnapshotOptions;
+export type BrowserJsonOptions = cf.BrowserRunJsonOptions;
+export type BrowserMarkdownOptions = cf.BrowserRunMarkdownOptions;
+
+// Quick action success payloads.
+export type BrowserContentResult = cf.BrowserRunContentSuccessResponse;
+export type BrowserScrapeResult = cf.BrowserRunScrapeSuccessResponse;
+export type BrowserLinksResult = cf.BrowserRunLinksSuccessResponse;
+export type BrowserSnapshotResult = cf.BrowserRunSnapshotSuccessResponse;
+export type BrowserJsonResult = cf.BrowserRunJsonSuccessResponse;
+export type BrowserMarkdownResult = cf.BrowserRunMarkdownSuccessResponse;
+export type BrowserErrorResponse = cf.BrowserRunErrorResponse;
 
 /**
  * Effect-native client for a Cloudflare Browser Rendering binding.
  *
- * Browser Rendering's Workers binding is consumed by `@cloudflare/puppeteer`.
- * Alchemy keeps Puppeteer as a caller-provided dependency while wrapping
- * launch and cleanup in Effects.
+ * Mirrors the runtime {@link cf.BrowserRun} binding, translating its shapes
+ * into Effect-native ones: JSON quick actions resolve to their parsed success
+ * payload, and binary actions (`screenshot`, `pdf`) resolve to a `Stream` of
+ * the response bytes. Non-success responses fail with {@link BrowserError}, so
+ * callers never touch a `Promise` or `Response.json()` themselves. Use
+ * `Cloudflare.Browser.bind(browser)` (or `yield* Cloudflare.Browser(...)`)
+ * inside a Worker's init phase to obtain it.
+ *
+ * The {@link raw} accessor and {@link fetch} are the only promise-shaped
+ * escape hatches — they exist for libraries like `@cloudflare/puppeteer` that
+ * consume the binding directly.
  */
 export interface BrowserClient {
   /**
    * Effect resolving to the raw Cloudflare Browser Rendering runtime binding.
+   *
+   * Pass it to `@cloudflare/puppeteer`'s `puppeteer.launch(binding)` to drive a
+   * full browser session.
+   */
+  raw: Effect.Effect<cf.BrowserRun, never, RuntimeContext>;
+  /**
+   * Send a raw HTTP request to the Browser Run API and resolve to the raw
+   * `Response`. Used by libraries like `@cloudflare/puppeteer` to acquire and
+   * connect to a browser instance.
+   */
+  fetch(
+    ...args: Parameters<cf.BrowserRun["fetch"]>
+  ): BrowserEffect<BrowserResponse>;
+  /**
+   * Run a Browser Run quick action, resolving to the parsed success payload
+   * (or a byte `Stream` for binary actions). Mirrors
+   * `cf.BrowserRun["quickAction"]`; the {@link screenshot}, {@link pdf},
+   * {@link content}, {@link scrape}, {@link links}, {@link snapshot},
+   * {@link json}, and {@link markdown} methods are thin wrappers over the
+   * corresponding action.
+   */
+  quickAction(
+    action: "screenshot",
+    options: BrowserScreenshotOptions,
+  ): BrowserByteStream;
+  quickAction(action: "pdf", options: BrowserPDFOptions): BrowserByteStream;
+  quickAction(
+    action: "content",
+    options: BrowserContentOptions,
+  ): BrowserEffect<BrowserContentResult>;
+  quickAction(
+    action: "scrape",
+    options: BrowserScrapeOptions,
+  ): BrowserEffect<BrowserScrapeResult>;
+  quickAction(
+    action: "links",
+    options: BrowserLinksOptions,
+  ): BrowserEffect<BrowserLinksResult>;
+  quickAction(
+    action: "snapshot",
+    options: BrowserSnapshotOptions,
+  ): BrowserEffect<BrowserSnapshotResult>;
+  quickAction(
+    action: "json",
+    options: BrowserJsonOptions,
+  ): BrowserEffect<BrowserJsonResult>;
+  quickAction(
+    action: "markdown",
+    options: BrowserMarkdownOptions,
+  ): BrowserEffect<BrowserMarkdownResult>;
+  /**
+   * Take a screenshot of a web page, streaming the raw image bytes.
+   */
+  screenshot(options: BrowserScreenshotOptions): BrowserByteStream;
+  /**
+   * Generate a PDF of a web page, streaming the raw PDF bytes.
+   */
+  pdf(options: BrowserPDFOptions): BrowserByteStream;
+  /**
+   * Get the HTML content of a web page.
+   */
+  content(options: BrowserContentOptions): BrowserEffect<BrowserContentResult>;
+  /**
+   * Scrape elements from a web page by CSS selector.
+   */
+  scrape(options: BrowserScrapeOptions): BrowserEffect<BrowserScrapeResult>;
+  /**
+   * Extract all links from a web page.
+   */
+  links(options: BrowserLinksOptions): BrowserEffect<BrowserLinksResult>;
+  /**
+   * Get both the HTML content and a base64-encoded screenshot of a web page.
    */
-  raw: Effect.Effect<cf.Fetcher, never, WorkerEnvironment>;
+  snapshot(
+    options: BrowserSnapshotOptions,
+  ): BrowserEffect<BrowserSnapshotResult>;
   /**
-   * Launch a Browser Rendering session through `@cloudflare/puppeteer`.
+   * Extract structured JSON data from a web page using AI.
    */
-  launch<Browser extends BrowserHandle>(
-    puppeteer: BrowserPuppeteer<Browser>,
-  ): Effect.Effect<Browser, BrowserError, WorkerEnvironment>;
+  json(options: BrowserJsonOptions): BrowserEffect<BrowserJsonResult>;
   /**
-   * Launch a browser, run an Effect with it, and close it afterward.
+   * Convert a web page to Markdown.
    */
-  withBrowser<Browser extends BrowserHandle, A, E, R>(
-    puppeteer: BrowserPuppeteer<Browser>,
-    use: (browser: Browser) => Effect.Effect<A, E, R>,
-  ): Effect.Effect<A, BrowserError | E, WorkerEnvironment | R>;
+  markdown(
+    options: BrowserMarkdownOptions,
+  ): BrowserEffect<BrowserMarkdownResult>;
 }
 
 export class BrowserBinding extends Binding.Service<
@@ -56,14 +162,14 @@ export const BrowserBindingLive = Layer.effect(
   BrowserBinding,
   Effect.gen(function* () {
     const Policy = yield* BrowserBindingPolicy;
+    const env = yield* WorkerEnvironment;
 
     return Effect.fn(function* (browser: BrowserLike) {
       yield* Policy(browser);
-      // Cloudflare exposes Browser Rendering as a service-style binding for
-      // @cloudflare/puppeteer; workers-types has no narrower interface.
-      const raw = WorkerEnvironment.useSync(
-        (env) => (env as Record<string, cf.Fetcher>)[browser.name]!,
-      );
+      const raw: Effect.Effect<cf.BrowserRun, never, RuntimeContext> =
+        Effect.sync(
+          () => (env as Record<string, cf.BrowserRun>)[browser.name]!,
+        );
       return makeBrowserClient(raw);
     });
   }),
@@ -106,23 +212,89 @@ const tryPromise = <T>(fn: () => Promise<T>): Effect.Effect<T, BrowserError> =>
       }),
   });
 
+/** Actions whose successful response is raw binary rather than JSON. */
+const BINARY_ACTIONS = new Set(["screenshot", "pdf"]);
+
+/** Build a {@link BrowserError} from a non-success Browser Run response. */
+const failResponse = (
+  action: string,
+  response: BrowserResponse,
+): Effect.Effect<never, BrowserError> =>
+  tryPromise(() => response.text()).pipe(
+    Effect.flatMap((body) => {
+      let cause: unknown = body;
+      try {
+        cause = JSON.parse(body);
+      } catch {
+        // keep the raw text as the cause
+      }
+      const message =
+        (cause as cf.BrowserRunErrorResponse | undefined)?.errors?.[0]
+          ?.message ??
+        `Browser Rendering '${action}' failed with status ${response.status}`;
+      return Effect.fail(new BrowserError({ message, cause }));
+    }),
+  );
+
 /** @internal */
 export const makeBrowserClient = (
-  raw: Effect.Effect<cf.Fetcher, never, WorkerEnvironment>,
+  raw: Effect.Effect<cf.BrowserRun, never, RuntimeContext>,
 ): BrowserClient => {
-  const launch = <Browser extends BrowserHandle>(
-    puppeteer: BrowserPuppeteer<Browser>,
-  ) =>
+  const respond = (
+    action: string,
+    options: unknown,
+  ): Effect.Effect<BrowserResponse, BrowserError, RuntimeContext> =>
     raw.pipe(
-      Effect.flatMap((binding) => tryPromise(() => puppeteer.launch(binding))),
+      Effect.flatMap((binding) =>
+        tryPromise(() => binding.quickAction(action as any, options as any)),
+      ),
+      Effect.flatMap((response) =>
+        response.ok ? Effect.succeed(response) : failResponse(action, response),
+      ),
+    );
+
+  const jsonAction = <T>(action: string, options: unknown): BrowserEffect<T> =>
+    respond(action, options).pipe(
+      Effect.flatMap((response) =>
+        tryPromise(() => response.json() as Promise<T>),
+      ),
     );
 
+  const streamAction = (action: string, options: unknown): BrowserByteStream =>
+    respond(action, options).pipe(
+      Effect.map((response) =>
+        Stream.fromReadableStream({
+          evaluate: () =>
+            response.body as any as ReadableStream<Uint8Array<ArrayBufferLike>>,
+          onError: (cause) =>
+            new BrowserError({
+              message: `Browser Rendering '${action}' stream failed`,
+              cause,
+            }),
+        }),
+      ),
+      Stream.unwrap,
+    );
+
+  const quickAction = ((action: string, options: unknown) =>
+    BINARY_ACTIONS.has(action)
+      ? streamAction(action, options)
+      : jsonAction(action, options)) as BrowserClient["quickAction"];
+
   return {
     raw,
-    launch,
-    withBrowser: (puppeteer, use) =>
-      Effect.acquireUseRelease(launch(puppeteer), use, (browser) =>
-        tryPromise(() => browser.close()),
+    fetch: (...args) =>
+      raw.pipe(
+        Effect.flatMap((binding) => tryPromise(() => binding.fetch(...args))),
       ),
+    quickAction,
+    screenshot: (options) => streamAction("screenshot", options),
+    pdf: (options) => streamAction("pdf", options),
+    content: (options) => jsonAction("content", options),
+    scrape: (options) => jsonAction("scrape", options),
+    links: (options) => jsonAction("links", options),
+    snapshot: (options) => jsonAction("snapshot", options),
+    json: (options) => jsonAction("json", options),
+    markdown: (options) => jsonAction("markdown", options),
   } satisfies BrowserClient;
 };

package/src/Cloudflare/Browser/index.ts

@@ -6,6 +6,19 @@ export {
   BrowserBindingPolicyLive,
   BrowserError,
   type BrowserClient,
-  type BrowserHandle,
-  type BrowserPuppeteer,
+  type BrowserScreenshotOptions,
+  type BrowserPDFOptions,
+  type BrowserContentOptions,
+  type BrowserScrapeOptions,
+  type BrowserLinksOptions,
+  type BrowserSnapshotOptions,
+  type BrowserJsonOptions,
+  type BrowserMarkdownOptions,
+  type BrowserContentResult,
+  type BrowserScrapeResult,
+  type BrowserLinksResult,
+  type BrowserSnapshotResult,
+  type BrowserJsonResult,
+  type BrowserMarkdownResult,
+  type BrowserErrorResponse,
 } from "./BrowserBinding.ts";

package/src/Cloudflare/Container/ContainerBinding.ts

@@ -18,16 +18,11 @@ export const bindContainer = Effect.fnUntraced(function* <Shape, Req = never>(
 ) {
   const namespace = yield* DurableObjectNamespace;
 
-  const container =
-    "asEffect" in containerEff
-      ? yield* containerEff as any as Effect.Effect<
-          ContainerApplication & Rpc<Shape>
-        >
-      : Effect.isEffect(containerEff)
-        ? yield* containerEff as unknown as Effect.Effect<
-            ContainerApplication & Rpc<Shape>
-          >
-        : containerEff;
+  const container = Effect.isEffect(containerEff)
+    ? yield* containerEff as unknown as Effect.Effect<
+        ContainerApplication & Rpc<Shape>
+      >
+    : containerEff;
 
   yield* container.bind`${namespace}`({
     durableObjects: {

package/src/Cloudflare/Images/Images.ts

@@ -32,9 +32,10 @@ type BindEffect = Effect.Effect<ImagesClient, never, ImagesBinding>;
  * Worker and returns the runtime {@link ImagesClient} — no separate `.bind(...)`
  * step required.
  *
- * The divergence is achieved via `[Symbol.iterator]`: the object is not an
- * `Effect` (so `InferEnv` resolves it to the native `ImagesBinding` in the
- * `env` position), but it is iterable as one when `yield*`-ed.
+ * The divergence is achieved via `[Symbol.iterator]`: the object is
+ * deliberately not an `Effect` (so `InferEnv` and the Worker `env` resolver
+ * keep it as the native `ImagesBinding` rather than `yield*`-ing it), but it
+ * is iterable as one when `yield*`-ed.
  */
 export interface Images {
   kind: ImagesTypeId;

package/src/Cloudflare/Providers.ts

@@ -8,6 +8,7 @@ import * as Schedule from "effect/Schedule";
 import { CredentialsStoreLive } from "../Auth/Credentials.ts";
 import { ProfileLive } from "../Auth/Profile.ts";
 import { Command } from "../Build/Command.ts";
+import { DevServer, DevServerProvider } from "../Build/DevServer.ts";
 import * as Build from "../Build/index.ts";
 import { KeyPair, KeyPairProvider } from "../KeyPair.ts";
 import * as Provider from "../Provider.ts";
@@ -67,6 +68,7 @@ export const providers = () =>
       Containers.Container,
       D1.D1ConnectionPolicy,
       D1.D1Database,
+      DevServer,
       Dns.DnsReadPolicy,
       Dns.DnsReadWritePolicy,
       Dns.DnsWritePolicy,
@@ -103,6 +105,7 @@ export const providers = () =>
       Workers.BindWorkerPolicy,
       Workers.CronEventSourcePolicy,
       Workers.FetchPolicy,
+      Workers.VersionMetadataBindingPolicy,
       Workers.Worker,
       Workflows.WorkflowResource,
       Zaraz.ZarazConfig,
@@ -121,6 +124,7 @@ export const providers = () =>
         Containers.ContainerProvider(),
         D1.D1ConnectionPolicyLive,
         D1.DatabaseProvider(),
+        DevServerProvider(),
         Dns.DnsReadPolicyLive,
         Dns.DnsReadWritePolicyLive,
         Dns.DnsWritePolicyLive,
@@ -155,6 +159,7 @@ export const providers = () =>
         Workers.BindWorkerPolicyLive,
         Workers.CronEventSourcePolicyLive,
         Workers.FetchPolicyLive,
+        Workers.VersionMetadataBindingPolicyLive,
         Workers.WorkerProvider(),
         Workflows.WorkflowProvider(),
         Zaraz.ZarazConfigProvider(),

package/src/Cloudflare/RateLimit/RateLimit.ts

@@ -52,9 +52,10 @@ type BindEffect = Effect.Effect<RateLimitClient, never, RateLimitBinding>;
  * Worker and returns the runtime {@link RateLimitClient} — no separate
  * `.bind(...)` step required.
  *
- * The divergence is achieved via `[Symbol.iterator]`: the object is not an
- * `Effect` (so `InferEnv` resolves it to the native `cf.RateLimit` in the
- * `env` position), but it is iterable as one when `yield*`-ed.
+ * The divergence is achieved via `[Symbol.iterator]`: the object is
+ * deliberately not an `Effect` (so `InferEnv` and the Worker `env` resolver
+ * keep it as the native `cf.RateLimit` rather than `yield*`-ing it), but it is
+ * iterable as one when `yield*`-ed.
  */
 export interface RateLimit {
   kind: RateLimitTypeId;