alchemy 2.0.0-beta.70 → 2.0.0-beta.72

package/src/Cloudflare/Queues/Queue.ts

@@ -1,4 +1,5 @@
 import * as queues from "@distilled.cloud/cloudflare/queues";
+import * as workers from "@distilled.cloud/cloudflare/workers";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as MutableHashMap from "effect/MutableHashMap";
@@ -11,9 +12,12 @@ import * as RpcProvider from "../../Local/RpcProvider.ts";
 import { createPhysicalName } from "../../PhysicalName.ts";
 import * as Provider from "../../Provider.ts";
 import { isResourceOfType, Resource } from "../../Resource.ts";
+import { Stack } from "../../Stack.ts";
 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
+import { detachQueueConsumersOfScript } from "./Consumer.ts";
 import {
   generateLocalId,
+  isLiveId,
   LOCAL_ENTRY_URL,
   LocalRuntimeState,
   localRuntimeServices,
@@ -138,7 +142,10 @@ export const ProviderLive = () =>
       let observed:
         | { queueId?: string | null; queueName?: string | null }
         | undefined;
-      if (output?.queueId) {
+      // A `dev:` id (a mis-stamped legacy local row) is not a real queue id —
+      // skip the lookup (Cloudflare rejects it as a malformed parameter) and
+      // fall through to the name scan.
+      if (output?.queueId && isLiveId(output.queueId)) {
         observed = yield* queues
           .getQueue({
             accountId: acct,
@@ -189,11 +196,18 @@ export const ProviderLive = () =>
       };
     }),
     delete: Effect.fn(function* ({ output }) {
+      // A `dev:` id means the physical resource only ever existed locally
+      // (a mis-stamped legacy row) — there is nothing to delete, and the
+      // API would reject the id as a malformed parameter.
+      if (!isLiveId(output.queueId)) return;
       // Dependents (e.g. R2 event notification configs targeting this
       // queue) may still be tearing down concurrently — ride out the
       // dependency violation briefly, then fail loudly instead of
-      // silently leaking the queue.
-      yield* queues
+      // silently leaking the queue. A worker producer binding
+      // (`QueueInUseByWorkerBinding`) gets a shorter window: a sibling
+      // Worker's just-processed delete/unbind takes a few seconds to
+      // propagate to the queues subsystem.
+      const attempt = queues
         .deleteQueue({
           accountId: output.accountId,
           queueId: output.queueId,
@@ -206,8 +220,34 @@ export const ProviderLive = () =>
               Schedule.recurs(8),
             ]),
           }),
+          Effect.retry({
+            while: (e) => e._tag === "QueueInUseByWorkerBinding",
+            schedule: Schedule.max([
+              Schedule.spaced("2 seconds"),
+              Schedule.recurs(6),
+            ]),
+          }),
           Effect.catchTag("QueueNotFound", () => Effect.void),
         );
+      yield* attempt.pipe(
+        // Still pinned by a worker producer binding after the propagation
+        // window: every *tracked* worker is deleted or unbound before its
+        // queues by dependency order, so the referencing script is an
+        // orphaned generation leaked by a pre-stamping dev run (a local-
+        // stamped row whose real script was never deleted). Remove the
+        // scripts that carry this stack+stage's ownership tags and retry;
+        // a script from outside this stack+stage keeps the typed failure.
+        Effect.catchTag("QueueInUseByWorkerBinding", (cause) =>
+          Effect.gen(function* () {
+            const removed = yield* deleteOwnedProducerScripts(
+              output.accountId,
+              output.queueId,
+            );
+            if (removed === 0) return yield* Effect.fail(cause);
+            return yield* attempt;
+          }),
+        ),
+      );
     }),
     list: Effect.fn(function* () {
       const { accountId } = yield* yield* CloudflareEnvironment;
@@ -231,7 +271,7 @@ export const ProviderLive = () =>
     }),
     read: Effect.fn(function* ({ id, output, olds }) {
       const { accountId } = yield* yield* CloudflareEnvironment;
-      if (output?.queueId) {
+      if (output?.queueId && isLiveId(output.queueId)) {
         return yield* queues
           .getQueue({
             accountId: output.accountId,
@@ -270,6 +310,80 @@ const createQueueName = (id: string, name: string | undefined) =>
     })).toLowerCase();
   });
 
+/**
+ * Delete the worker scripts that hold a producer binding on `queueId` AND
+ * carry this stack+stage's `alchemy:` ownership tags. Returns how many
+ * scripts were deleted.
+ *
+ * Used by the live queue delete when `QueueInUseByWorkerBinding` persists
+ * past the propagation-lag retry window: tracked workers are always
+ * deleted/unbound before their queues, so an own-stack script still
+ * binding the queue at that point is an orphaned generation (leaked by a
+ * pre-stamping dev run that rewrote the worker's row as local). Scripts
+ * without our ownership tags are left alone.
+ */
+const deleteOwnedProducerScripts = Effect.fn(function* (
+  accountId: string,
+  queueId: string,
+) {
+  const stack = yield* Stack;
+  const queue = yield* queues
+    .getQueue({ accountId, queueId })
+    .pipe(
+      Effect.catchTag(["QueueNotFound", "InvalidRoute"], () =>
+        Effect.succeed(undefined),
+      ),
+    );
+  const producerScripts = Array.from(
+    new Set(
+      (queue?.producers ?? []).flatMap((producer) =>
+        producer.type === "worker" &&
+        "scriptName" in producer &&
+        producer.scriptName
+          ? [producer.scriptName]
+          : [],
+      ),
+    ),
+  );
+  let removed = 0;
+  for (const scriptName of producerScripts) {
+    const settings = yield* workers
+      .getScriptScriptAndVersionSetting({ accountId, scriptName })
+      .pipe(
+        Effect.catchTag(["WorkerNotFound", "WorkerHasNoVersions"], () =>
+          Effect.succeed(undefined),
+        ),
+      );
+    const tags = new Set(settings?.tags ?? []);
+    if (
+      !tags.has(`alchemy:stack:${stack.name}`) ||
+      !tags.has(`alchemy:stage:${stack.stage}`)
+    ) {
+      continue;
+    }
+    yield* Effect.logWarning(
+      `Cloudflare Queue delete: removing orphaned worker script ` +
+        `"${scriptName}" that still binds queue ${queueId} (leaked by a ` +
+        `pre-providerMode dev run)`,
+    );
+    yield* workers.deleteScript({ accountId, scriptName, force: true }).pipe(
+      // The orphan may also be registered as a queue consumer — detach
+      // its consumers and retry, mirroring the Worker provider's own
+      // delete recovery.
+      Effect.catchTag("QueueConsumerConflict", () =>
+        detachQueueConsumersOfScript(accountId, scriptName).pipe(
+          Effect.andThen(
+            workers.deleteScript({ accountId, scriptName, force: true }),
+          ),
+        ),
+      ),
+      Effect.catchTag("WorkerNotFound", () => Effect.void),
+    );
+    removed++;
+  }
+  return removed;
+});
+
 // Cloudflare's `listQueues` accepts no name/prefix filter, so
 // adoption-by-name has to scan every page. Use the paginated
 // `.items` stream off the un-yielded operation method.
@@ -293,6 +407,15 @@ export const ProviderLocal = () =>
         diff: Effect.fn(function* ({ id, olds = {}, news = {}, output }) {
           const { accountId } = yield* yield* CloudflareEnvironment;
           if (!output?.queueId) return { action: "update" };
+          // A real (non-`dev:`) queueId on a local-mode row is legacy damage:
+          // pre-stamping dev runs preserved the live id, which the worker
+          // binding then treats as an `Alchemy.remote()` queue and fails on
+          // the missing producer shim. Replace so the new generation mints a
+          // true local identity (delete best-effort removes the stray live
+          // queue).
+          if (isLiveId(output.queueId)) {
+            return { action: "replace" };
+          }
           if (!isResolved(news)) return undefined;
           const name = yield* createQueueName(id, news.name);
           const oldName = output?.queueName
@@ -316,7 +439,13 @@ export const ProviderLocal = () =>
         reconcile: Effect.fn(function* ({ id, news = {}, output }) {
           const { accountId } = yield* yield* CloudflareEnvironment;
           const queue: Queue["Attributes"] = {
-            queueId: output?.queueId ?? generateLocalId(),
+            // Never carry a real (non-`dev:`) id forward onto a local row —
+            // the worker binding would treat it as an `Alchemy.remote()`
+            // queue and fail on the missing producer shim.
+            queueId:
+              output?.queueId && !isLiveId(output.queueId)
+                ? output.queueId
+                : generateLocalId(),
             queueName: yield* createQueueName(id, news.name),
             accountId: output?.accountId ?? accountId,
           };
@@ -325,6 +454,29 @@ export const ProviderLocal = () =>
         }),
         delete: Effect.fn(function* ({ output }) {
           MutableHashMap.remove(localRuntimeState.queues, output.queueId);
+          // Legacy local-mode rows written before providerMode stamping can
+          // carry a real queue's id — remove the live queue too so migrating
+          // the row to a true local identity doesn't leak it.
+          if (isLiveId(output.queueId)) {
+            yield* queues
+              .deleteQueue({
+                accountId: output.accountId,
+                queueId: output.queueId,
+              })
+              .pipe(
+                Effect.retry({
+                  while: (e) => e._tag === "QueueInUseByEventNotification",
+                  schedule: Schedule.max([
+                    Schedule.exponential("1 second"),
+                    Schedule.recurs(8),
+                  ]),
+                }),
+                Effect.catchTag(
+                  ["QueueNotFound", "InvalidRoute"],
+                  () => Effect.void,
+                ),
+              );
+          }
         }),
       };
     }),

package/src/Cloudflare/R2/LocalR2Gateway.ts

@@ -17,8 +17,8 @@
  *
  * NOT exported from `index.ts` — capability-internal scaffolding.
  */
-import { R2Bucket } from "@distilled.cloud/cloudflare-runtime/bindings";
-import { open } from "@distilled.cloud/cloudflare-runtime/platform-proxy";
+import { R2Bucket } from "@alchemy.run/cloudflare-runtime/core/bindings";
+import { open } from "@alchemy.run/cloudflare-runtime/core/platform-proxy";
 import type * as runtime from "@cloudflare/workers-types";
 import type * as Context from "effect/Context";
 import * as Effect from "effect/Effect";

package/src/Cloudflare/SecretsStore/LocalSecretsStoreGateway.ts

@@ -17,8 +17,8 @@
  * NOT exported from `index.ts` — provider-internal scaffolding.
  */
 import type * as runtime from "@cloudflare/workers-types";
-import { SecretsStore } from "@distilled.cloud/cloudflare-runtime/bindings";
-import { open } from "@distilled.cloud/cloudflare-runtime/platform-proxy";
+import { SecretsStore } from "@alchemy.run/cloudflare-runtime/core/bindings";
+import { open } from "@alchemy.run/cloudflare-runtime/core/platform-proxy";
 import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
 import { gatewayName } from "../LocalGateway.ts";

package/src/Cloudflare/SecretsStore/Secret.ts

@@ -1,4 +1,4 @@
-import type { RuntimeServices } from "@distilled.cloud/cloudflare-runtime";
+import type { RuntimeServices } from "@alchemy.run/cloudflare-runtime/core";
 import * as secretsStore from "@distilled.cloud/cloudflare/secrets-store";
 import * as Console from "effect/Console";
 import * as Effect from "effect/Effect";

package/src/Cloudflare/StateStore/Api.ts

@@ -331,6 +331,13 @@ export default Worker(
  * have.
  */
 const HttpPlatformStub = Layer.succeed(HttpPlatform.HttpPlatform, {
+  platform: "web",
+  // Advertises no algorithms, so the compression middleware never engages
+  // and compressResponse is never called.
+  compression: {
+    algorithms: new Set<HttpPlatform.CompressionAlgorithm>(),
+    compressResponse: (response) => Effect.succeed(response),
+  },
   fileResponse: () => Effect.die("HttpPlatform.fileResponse not supported"),
   fileWebResponse: () =>
     Effect.die("HttpPlatform.fileWebResponse not supported"),

package/src/Cloudflare/Website/Astro.ts

@@ -52,9 +52,10 @@ export interface AstroProps<
   sessionKVBindingName?: string | false;
   /**
    * Serializable Astro config merged into the in-memory configuration.
-   * The project's `astro.config.*` file is NOT read — the integration is
-   * fully programmatic (the Cloudflare adapter, output target, and Vite
-   * environments are managed for you).
+   * The project's `astro.config.*` file loads natively; astro merges
+   * these options OVER it (scalars override the file). The Cloudflare
+   * adapter, output target, and Vite environments are managed for you —
+   * do not declare an `adapter` in the config file.
    */
   astro?: {
     /** The full URL the site deploys to (`Astro.site`). */
@@ -89,19 +90,19 @@ export interface AstroProps<
  * project.
  *
  * `Astro` runs Astro's programmatic build with a wrangler-free
- * Cloudflare adapter (`@distilled.cloud/astro`): server-rendered pages
+ * Cloudflare adapter (`@alchemy.run/cloudflare-frameworks/astro`): server-rendered pages
  * execute in the Worker, prerendered pages and client assets deploy as
- * static assets — no `astro.config.*`, adapter setup, or Wrangler
- * configuration required.
+ * static assets. Your `astro.config.*` loads natively — no adapter
+ * setup or Wrangler configuration required.
  *
  * Input files are content-hashed (respecting `.gitignore` by default)
  * so unchanged projects skip the build and deploy entirely.
  *
- * The `@distilled.cloud/astro` package must be installed in your
- * project (it is loaded dynamically at deploy time):
+ * The `@alchemy.run/cloudflare-frameworks` package must be installed in your
+ * project; its `/astro` export is loaded dynamically at deploy time:
  *
  * ```sh
- * bun add -d @distilled.cloud/astro
+ * bun add -d @alchemy.run/cloudflare-frameworks
  * ```
  *
  * @resource
@@ -194,8 +195,15 @@ export interface AstroProps<
  * ```
  *
  * @section Astro Configuration
- * The integration is fully programmatic — your `astro.config.*` file is
- * not read. Common serializable options are exposed under `astro`.
+ * Your `astro.config.*` file loads natively — integrations, Vite
+ * plugins, and other non-serializable options work as usual. Common
+ * serializable options are exposed under `astro` for deploy-specific
+ * overrides; astro merges them OVER the config file (scalars override,
+ * arrays like `integrations` concatenate). The Cloudflare adapter is
+ * injected for you — declaring an `adapter` in the config file fails
+ * the build. `output` defaults to `"server"`, superseding a file-level
+ * `output`; opt into a fully prerendered site with
+ * `astro: { output: "static" }`.
  *
  * @example Setting the site URL and source directory
  * ```typescript
@@ -287,7 +295,7 @@ export const Astro: {
             // `no_nodejs_compat` opt-out and the v2-mode date guard).
             main: undefined!,
             source: {
-              provider: "@distilled.cloud/astro/source",
+              provider: "@alchemy.run/cloudflare-frameworks/astro/source",
               devMode: "server",
               options: {
                 rootDir: props.rootDir,

package/src/Cloudflare/Website/Nextjs.ts

@@ -15,14 +15,16 @@ import {
 
 /**
  * The module specifier of the Next.js source provider. Loaded with a
- * dynamic `import()`, so `@distilled.cloud/nextjs` must be installed in
- * the deploying project.
+ * dynamic `import()`, so `@alchemy.run/cloudflare-frameworks` must be installed
+ * in the deploying project. The provider is exposed through its `/nextjs`
+ * subpath.
  */
-const NEXTJS_SOURCE_PROVIDER = "@distilled.cloud/nextjs/source";
+const NEXTJS_SOURCE_PROVIDER =
+  "@alchemy.run/cloudflare-frameworks/nextjs/source";
 
 /**
  * The default compatibility date when none is provided. Matches the
- * `@distilled.cloud/nextjs` integration's own default so deploy and local
+ * `@alchemy.run/cloudflare-frameworks/nextjs` integration's own default so deploy and local
  * dev agree.
  */
 const DEFAULT_COMPATIBILITY_DATE = "2026-05-12";
@@ -36,6 +38,8 @@ export interface NextjsBuildOptions {
   configPath?: string;
   /**
    * The command the OpenNext pipeline runs to build the Next.js app.
+   * A `buildCommand` set in the project's `open-next.config.ts` takes
+   * precedence over this option.
    * @default "npx next build"
    */
   buildCommand?: string;
@@ -103,16 +107,17 @@ export interface NextjsProps<
  * A Cloudflare Worker deployed from a Next.js project.
  *
  * `Nextjs` builds the app with the wrangler-free OpenNext pipeline from
- * [`@distilled.cloud/nextjs`](https://github.com/alchemy-run/cloudflare-tools):
+ * [`@alchemy.run/cloudflare-frameworks/nextjs`](https://github.com/alchemy-run/alchemy/tree/main/packages/cloudflare-frameworks/src/nextjs):
  * `next build` runs through `@opennextjs/cloudflare`, the resulting worker
  * is bundled into a self-contained ES module set, and the static assets
  * (including prerendered pages and the read-only incremental cache) deploy
  * as Workers static assets. Input files are content-hashed so unchanged
  * projects skip the build and deploy entirely.
  *
- * Both `@distilled.cloud/nextjs` and its peer `@opennextjs/cloudflare`
- * must be installed in the deploying project — the source provider is
- * loaded with a dynamic `import()`.
+ * Both `@alchemy.run/cloudflare-frameworks` and its peer
+ * `@opennextjs/cloudflare` must be installed in the deploying project. The
+ * source provider is loaded from the package's `/nextjs` export with a dynamic
+ * `import()`.
  *
  * Local dev (`alchemy dev`) defaults to preview parity — the built worker
  * served under workerd. Set `nextjs: { devMode: "hmr" }` for the real

package/src/Cloudflare/Website/Nuxt.ts

@@ -17,7 +17,7 @@ import {
  * installed in the user's project — `loadSource` fails with a
  * `SourceProviderError` naming it otherwise.
  */
-const NUXT_SOURCE_PROVIDER = "@distilled.cloud/nuxt/source";
+const NUXT_SOURCE_PROVIDER = "@alchemy.run/cloudflare-frameworks/nuxt/source";
 
 export interface NuxtProps<
   Bindings extends WorkerBindingProps = {},
@@ -59,8 +59,8 @@ export interface NuxtProps<
   memo?: MemoOptions;
   /**
    * Nuxt configuration overrides merged over the project's own
-   * `nuxt.config.ts` (the override wins). Unlike some siblings, the
-   * project's config file IS loaded natively — this is for
+   * `nuxt.config.ts` (the override wins). The project's config file is
+   * loaded natively — modules, layers, and all — so this is for
    * deploy-specific tweaks (`routeRules`, `runtimeConfig`, ...). Must be
    * JSON-serializable (it persists in state). Do not set `nitro.preset`
    * here — the Cloudflare deploy target owns the preset and a foreign
@@ -84,8 +84,9 @@ export interface NuxtProps<
  * deploys as the Worker script; client assets and prerendered pages
  * (`.output/public`) deploy as Worker static assets.
  *
- * Requires the `@distilled.cloud/nuxt` package to be installed in your
- * project (alongside `nuxt` itself). Input files are content-hashed
+ * Requires the `@alchemy.run/cloudflare-frameworks` package to be installed in
+ * your project; the integration is loaded from its `/nuxt` export. Input files
+ * are content-hashed
  * (respecting `.gitignore` by default) so unchanged projects skip the
  * build and deploy entirely.
  *

package/src/Cloudflare/Website/Octane.ts

@@ -17,7 +17,8 @@ import {
  * installed in the user's project — `loadSource` fails with a
  * `SourceProviderError` naming it otherwise.
  */
-const OCTANE_SOURCE_PROVIDER = "@distilled.cloud/octane/source";
+const OCTANE_SOURCE_PROVIDER =
+  "@alchemy.run/cloudflare-frameworks/octane/source";
 
 export interface OctaneProps<
   Bindings extends WorkerBindingProps = {},
@@ -65,9 +66,10 @@ export interface OctaneProps<
  * `dist/client` deploys as static assets — no Wrangler configuration and
  * no build command required.
  *
- * Requires the `@distilled.cloud/octane` package to be installed in your
- * project (alongside `octane`, `@octanejs/vite-plugin`, and
- * `@octanejs/adapter-cloudflare`). Input files are content-hashed
+ * Requires the `@alchemy.run/cloudflare-frameworks` package to be installed in
+ * your project; the integration is loaded from its `/octane` export. The
+ * project also needs `octane`, `@octanejs/vite-plugin`, and
+ * `@octanejs/adapter-cloudflare`. Input files are content-hashed
  * (respecting `.gitignore` by default) so unchanged projects skip the
  * build and deploy entirely.
  *

package/src/Cloudflare/Website/SvelteKit.ts

@@ -33,12 +33,15 @@ export interface SvelteKitProps<
    */
   memo?: MemoOptions;
   /**
-   * SvelteKit configuration passed to the `sveltekit(config)` Vite plugin.
-   * Since kit v3 the configuration lives in memory (a `svelte.config.js` on
-   * disk is an upstream error), so this is the place for `alias`, `paths`,
-   * `prerender`, and the rest of the kit config surface. The `adapter`
-   * field is injected by Alchemy's wrangler-free Cloudflare adapter — do
-   * not set it here. Must be JSON-serializable (it persists in state).
+   * SvelteKit configuration overrides. A project-owned `vite.config.*`
+   * loads natively — its `sveltekit(...)` call is the primary config
+   * source — and these options are merged OVER it (the override wins).
+   * Without a config file, this is the whole kit config. Construction-time
+   * options (`preprocess`, `extensions`, `compilerOptions`, `vitePlugin`)
+   * only apply in the no-config-file case — put them in your own
+   * `sveltekit(...)` call otherwise. The `adapter` field is injected by
+   * Alchemy's wrangler-free Cloudflare adapter — do not set it here. Must
+   * be JSON-serializable (it persists in state).
    */
   kit?: Record<string, unknown>;
   /**
@@ -77,13 +80,15 @@ export interface SvelteKitProps<
  *
  * `SvelteKit` builds the app with SvelteKit's own Vite pipeline and a
  * wrangler-free in-memory Cloudflare adapter, then re-bundles the
- * Node-flavored server output for workerd — no `svelte.config.js`, no
+ * Node-flavored server output for workerd. A project-owned
+ * `vite.config.*` loads natively (its `sveltekit(...)` options apply) —
+ * no `svelte.config.js` (kit v3 dropped it), no
  * `@sveltejs/adapter-cloudflare`, no Wrangler configuration required.
  * Client assets and prerendered pages are deployed as Worker static
  * assets; dynamic routes are served by the generated Worker.
  *
- * The `@distilled.cloud/sveltekit` package must be installed in your
- * project — it is loaded dynamically at deploy time.
+ * The `@alchemy.run/cloudflare-frameworks` package must be installed in your
+ * project — its `/sveltekit` export is loaded dynamically at deploy time.
  *
  * Input files are content-hashed (respecting `.gitignore` by default) so
  * unchanged projects skip the build and deploy entirely.
@@ -130,7 +135,9 @@ export interface SvelteKitProps<
  * ```
  *
  * @section Kit and Adapter Options
- * The kit config surface is passed in-memory via `kit`; the generated
+ * Kit options normally live in the `sveltekit(...)` call in your
+ * `vite.config.ts`, which loads natively; `kit` is a deploy-time
+ * override layer merged over them (the override wins). The generated
  * Cloudflare adapter is configured via `adapter`.
  *
  * @example SPA-style 404 fallback
@@ -232,7 +239,7 @@ export const SvelteKit: {
                   }
                 : props?.assets,
             source: {
-              provider: "@distilled.cloud/sveltekit/source",
+              provider: "@alchemy.run/cloudflare-frameworks/sveltekit/source",
               devMode: "server",
               options: {
                 rootDir: props?.rootDir,

package/src/Cloudflare/Website/Waku.ts

@@ -17,7 +17,7 @@ import {
  * installed in the user's project — `loadSource` fails with a
  * `SourceProviderError` naming it otherwise.
  */
-const WAKU_SOURCE_PROVIDER = "@distilled.cloud/waku/source";
+const WAKU_SOURCE_PROVIDER = "@alchemy.run/cloudflare-frameworks/waku/source";
 
 export interface WakuProps<
   Bindings extends WorkerBindingProps = {},
@@ -51,20 +51,25 @@ export interface WakuProps<
    */
   rootDir?: string;
   /**
-   * Waku source directory, relative to {@link rootDir}.
-   * @default "src"
+   * Waku source directory, relative to {@link rootDir}. Setting this
+   * overrides a `srcDir` in the project's `waku.config.*`.
+   * @default the project's `waku.config.*` value, or waku's own default (`"src"`)
    */
   srcDir?: string;
   /**
    * Waku build output directory, relative to {@link rootDir}. The server
    * bundle is read from `<distDir>/server` and the client assets from
-   * `<distDir>/public`.
-   * @default "dist"
+   * `<distDir>/public`. Setting this overrides a `distDir` in the
+   * project's `waku.config.*` — if your config file customizes `distDir`,
+   * mirror it here (or exclude it via `memo`) so the build output doesn't
+   * pollute the rebuild hash.
+   * @default the project's `waku.config.*` value, or waku's own default (`"dist"`)
    */
   distDir?: string;
   /**
-   * Base path the app is served under.
-   * @default "/"
+   * Base path the app is served under. Setting this overrides a
+   * `basePath` in the project's `waku.config.*`.
+   * @default the project's `waku.config.*` value, or waku's own default (`"/"`)
    */
   basePath?: string;
   /**
@@ -92,12 +97,18 @@ export interface WakuProps<
  * A Cloudflare Worker deployed from a [Waku](https://waku.gg) project.
  *
  * `Waku` builds the project programmatically — no `waku.config.ts` edits,
- * no Wrangler configuration, and no build command required. The RSC server
+ * no Wrangler configuration, and no build command required. A project's
+ * `waku.config.*` loads natively (same as waku's CLI) as the base config,
+ * with `srcDir`/`distDir`/`basePath` from this resource winning per key;
+ * `unstable_adapter` is owned by Alchemy and must not be set. Note that a
+ * standalone `vite.config.ts` is NOT loaded (same as waku's CLI) — Vite
+ * config belongs in `waku.config.*`'s `vite` field. The RSC server
  * bundle deploys as the Worker script and the client output (including
  * SSG-prerendered pages) deploys as static assets.
  *
- * Requires the `@distilled.cloud/waku` package to be installed in your
- * project (alongside `waku` itself). Input files are content-hashed
+ * Requires the `@alchemy.run/cloudflare-frameworks` package to be installed in
+ * your project; the integration is loaded from its `/waku` export. Input files
+ * are content-hashed
  * (respecting `.gitignore` by default) so unchanged projects skip the
  * build and deploy entirely.
  *