astroidjs 0.15.0 → 0.16.0

package/README.md

@@ -339,11 +339,13 @@ Astro app—in one step.
 
 ## Roadmap
 
-1. ✅ **Config surface** (`defineAstroid`)—single brand per project.
-2. ✅ Config → generated Drizzle schema.
-3. ✅ Config → generated `worker.ts` + middleware (no hand-wired route ordering).
-4. ✅ `<Section>` / `<Editable>` / `<Collection>` component primitives.
-5. ✅ **CLI**—`astroid generate / doctor / dev / build / deploy`; `create-astroid`
+Every item on the first roadmap has shipped:
+
+1. **Config surface** (`defineAstroid`)—single brand per project.
+2. Config → generated Drizzle schema.
+3. Config → generated `worker.ts` + middleware (no hand-wired route ordering).
+4. `<Section>` / `<Editable>` / `<Collection>` component primitives.
+5. **CLI**—`astroid generate / doctor / dev / build / deploy`; `create-astroid`
    scaffold (`pnpm create astroid`).
 
 ## License

package/bin/astroid.mjs

@@ -8,6 +8,7 @@
 //   astroid dev      [...astro args]                   generate, then `astro dev`
 //   astroid build    [...astro args]                   generate, then `astro build`
 //   astroid deploy   [--dry-run] [--yes] [--local]     provision + migrate + secrets + deploy
+//   astroid ship     production | preview              migrate, then deploy or preview (Workers Builds)
 //
 // It loads the project's `astroid.config.ts` with Node's native TypeScript
 // stripping (the config only imports the built `astroidjs`, so it resolves), and
@@ -23,6 +24,16 @@ import { pathToFileURL } from "node:url";
 
 const GENERATORS_URL = new URL("../dist/index.js", import.meta.url).href;
 
+/** The repository root, where `.github/` lives, or null outside a git checkout.
+ *  A site's Astroid project can sit below it (`workers/site`). */
+function gitRoot(cwd) {
+  try {
+    return execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8" }).trim();
+  } catch {
+    return null;
+  }
+}
+
 // --- tiny arg parser -------------------------------------------------------
 // Splits at the first non-flag token into { command, flags, rest }. `rest` is
 // everything after the command, preserved verbatim so `dev`/`build` can forward
@@ -77,7 +88,12 @@ async function loadConfig(cwd, explicit) {
 
 // --- commands --------------------------------------------------------------
 async function cmdGenerate(cwd, flags, { quiet = false } = {}) {
-  const { generateAstroidProject, generateAstroidScaffoldFiles } = await import(GENERATORS_URL);
+  const {
+    generateAstroidProject,
+    generateAstroidScaffoldFiles,
+    generateAstroidReleaseWorkflow,
+    ASTROID_RELEASE_WORKFLOW_PATH,
+  } = await import(GENERATORS_URL);
   const { config } = await loadConfig(cwd, flags.config);
   const files = generateAstroidProject(config);
   for (const file of files) {
@@ -87,6 +103,16 @@ async function cmdGenerate(cwd, flags, { quiet = false } = {}) {
     if (!quiet) out(`  ✓ ${file.path}`);
   }
 
+  // The release workflow, at the repository root rather than the project,
+  // because GitHub reads workflows only from there. Regenerated like the trio.
+  const root = gitRoot(cwd);
+  if (root) {
+    const abs = join(root, ASTROID_RELEASE_WORKFLOW_PATH);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, generateAstroidReleaseWorkflow());
+    if (!quiet) out(`  ✓ ${ASTROID_RELEASE_WORKFLOW_PATH} (repository root)`);
+  }
+
   // Scaffold-once files for whatever modules the config switched on.
   //
   // Written only when ABSENT—each is a seam the project owns, so overwriting
@@ -124,8 +150,15 @@ async function cmdGenerate(cwd, flags, { quiet = false } = {}) {
 }
 
 async function cmdDoctor(cwd, flags) {
-  const { generateAstroidProject, generateAstroidScaffoldFiles, astroidUsesQueues, astroidCrons } =
-    await import(GENERATORS_URL);
+  const {
+    generateAstroidProject,
+    generateAstroidScaffoldFiles,
+    astroidUsesQueues,
+    astroidCrons,
+    checkWranglerPreviews,
+    generateAstroidReleaseWorkflow,
+    ASTROID_RELEASE_WORKFLOW_PATH,
+  } = await import(GENERATORS_URL);
   const { config, path: configPath } = await loadConfig(cwd, flags.config);
 
   const problems = []; // { level: "error" | "warn", msg }
@@ -264,6 +297,31 @@ async function cmdDoctor(cwd, flags) {
     }
   }
 
+  // 1c. The release workflow at the repository root: a tag on `main` moves
+  //     `deploy/production`, which Workers Builds deploys. Stale is an error for
+  //     the same reason the trio's is: it decides which commits reach production.
+  const root = gitRoot(cwd);
+  if (!root) {
+    warn(`not in a git checkout, so ${ASTROID_RELEASE_WORKFLOW_PATH} can't be checked.`);
+  } else {
+    const abs = join(root, ASTROID_RELEASE_WORKFLOW_PATH);
+    if (!existsSync(abs))
+      err(`${ASTROID_RELEASE_WORKFLOW_PATH} is missing — run \`astroid generate\`.`);
+    else if (readFileSync(abs, "utf8") !== generateAstroidReleaseWorkflow())
+      err(`${ASTROID_RELEASE_WORKFLOW_PATH} is stale — run \`astroid generate\`.`);
+    else ok(`${ASTROID_RELEASE_WORKFLOW_PATH} is up to date`);
+  }
+
+  // 2b. Staging: the `previews` block (louise-toolkit ADR 0017). A Preview
+  //     inherits nothing, so a binding left out crashes it and one copied from
+  //     production writes production data; see src/project/previews.ts.
+  if (existsSync(wranglerPath)) {
+    const previews = checkWranglerPreviews(readFileSync(wranglerPath, "utf8"));
+    for (const m of previews.ok) ok(m);
+    for (const m of previews.warnings) warn(m);
+    for (const m of previews.errors) err(m);
+  }
+
   // 3. migrations directory: the D1 `migrations_dir` wrangler.jsonc declares,
   //    or `migrations/`, the generated default, when it names none. A site that
   //    keeps its migrations under another name (drizzle/) isn't missing them.
@@ -403,7 +461,10 @@ function provisionPlan(facts) {
   }
   for (const { binding, id } of facts.kv) {
     if (isPlaceholder(id)) {
-      steps.push({ kind: "kv", name: binding, args: ["kv", "namespace", "create", binding] });
+      // The placeholder names the namespace (`<run: wrangler kv namespace
+      // create acme-rl>`); an older one without a name falls back to the binding.
+      const title = id.match(/kv namespace create ([^\s>]+)/)?.[1] ?? binding;
+      steps.push({ kind: "kv", name: title, binding, args: ["kv", "namespace", "create", title] });
     }
   }
   // Queues carry no id, so there's no placeholder to test—creating one that
@@ -531,7 +592,7 @@ async function cmdDeploy(cwd, flags, rest) {
         (rows) => rows.find((r) => typeof r.title === "string" && r.title.endsWith(s.name))?.id,
       );
       if (id) {
-        wrangler = patchKvId(wrangler, s.name, id);
+        wrangler = patchKvId(wrangler, s.binding, id);
         writeFileSync(wranglerPath, wrangler);
         out(`  ↳ ${s.name} id = ${id}`);
       } else {
@@ -597,10 +658,172 @@ Usage:
   astroid dev      [...astro args]                   regenerate, then run \`astro dev\`
   astroid build    [...astro args]                   regenerate, then run \`astro build\`
   astroid deploy   [--dry-run] [--yes] [--local]     provision bindings + migrate + secrets + deploy
+  astroid ship     production | preview              migrate D1, then deploy or preview (Workers Builds runs this)
+  astroid provision [--dry-run] [--yes]              create the resources wrangler.jsonc names by placeholder, staging included
 
 New project:  pnpm create astroid@latest
 `;
 
+// `astroid provision` creates what `wrangler.jsonc` still names by placeholder,
+// top level and `previews` alike, and writes each new ID back in place of its
+// placeholder. It never deploys, so it's safe to run before a site's first
+// release, and re-running it only creates what's still missing. Secrets and
+// dashboard settings need a person, so it prints those instead.
+async function cmdProvision(cwd, rest) {
+  const dryRun = rest.includes("--dry-run");
+  const assumeYes = rest.includes("--yes") || rest.includes("-y");
+  const wranglerPath = join(cwd, "wrangler.jsonc");
+  if (!existsSync(wranglerPath)) fail("wrangler.jsonc not found — run inside an Astroid project.");
+
+  const { provisionPlan, applyProvisionedId } = await import(GENERATORS_URL);
+  let text = readFileSync(wranglerPath, "utf8");
+  const plan = provisionPlan(text);
+
+  out("astroid provision — plan:\n");
+  if (plan.steps.length === 0) out("  (nothing to create: every binding has an ID)");
+  for (const s of plan.steps) {
+    const note = s.kind === "r2" ? "   (an existing bucket is fine)" : "";
+    out(`  wrangler ${s.args.join(" ")}${note}`);
+  }
+  if (!plan.hasAccount && !process.env.CLOUDFLARE_ACCOUNT_ID) {
+    out(
+      "\n  ! No account_id in wrangler.jsonc and no CLOUDFLARE_ACCOUNT_ID, so wrangler picks one.",
+    );
+  }
+  const printSecrets = () => {
+    if (plan.secrets.length === 0) return;
+    out("\nSecrets Store secrets it binds; create any that don't exist yet:");
+    for (const s of plan.secrets) {
+      out(
+        `  [${s.environment}] wrangler secrets-store secret create ${s.storeId} ` +
+          `--name ${s.secretName} --scopes workers --remote`,
+      );
+    }
+  };
+
+  if (dryRun) {
+    printSecrets();
+    out("\n(dry run — nothing created)");
+    return;
+  }
+  if (plan.steps.length > 0 && !assumeYes) {
+    if (!process.stdin.isTTY)
+      fail("Refusing to create resources non-interactively. Re-run with --yes.");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = (await rl.question("\nCreate the above? [y/N] ")).trim().toLowerCase();
+    rl.close();
+    if (answer !== "y" && answer !== "yes") {
+      out("Aborted.");
+      return;
+    }
+  }
+
+  const wranglerBin = resolveBin(cwd, "wrangler", "wrangler");
+  if (!wranglerBin) fail("Could not find `wrangler` in this project.");
+  for (const s of plan.steps) {
+    out(`\n▸ wrangler ${s.args.join(" ")}`);
+    // A create that fails because the resource exists is fine: the lookup
+    // below finds it, so a re-run after a partial one picks up where it was.
+    spawnSync(process.execPath, [wranglerBin, ...s.args], { cwd, stdio: "inherit" });
+    if (s.kind === "r2") continue;
+    const id =
+      s.kind === "d1"
+        ? lookupId(
+            wranglerBin,
+            cwd,
+            ["d1", "list", "--json"],
+            (rows) => rows.find((r) => r.name === s.name)?.uuid,
+          )
+        : lookupId(
+            wranglerBin,
+            cwd,
+            ["kv", "namespace", "list"],
+            (rows) => rows.find((r) => r.title === s.name)?.id,
+          );
+    if (!id) fail(`Couldn't find the ID of ${s.name} after creating it. Fill it in by hand.`);
+    text = applyProvisionedId(text, s.placeholder, id);
+    writeFileSync(wranglerPath, text);
+    out(`  ↳ ${s.name} = ${id}`);
+  }
+  printSecrets();
+  out("\n✓ Provisioned. Commit wrangler.jsonc; the dashboard steps are in the site's RUNBOOK.");
+}
+
+// `astroid ship` is what Workers Builds runs, so the deploy logic lives in the
+// repository instead of a dashboard field. An account move once rewrote a
+// site's dashboard deploy command to a bare `wrangler deploy`, and migrations
+// silently stopped. Migrations run first, so new code never meets an old schema.
+//
+//   astroid ship production   the deploy/production build: migrate D1, then deploy
+//   astroid ship preview      every other branch: migrate the staging D1, then
+//                             `wrangler preview`, named for the branch
+async function cmdShip(cwd, target) {
+  if (target !== "production" && target !== "preview") {
+    fail("Usage: astroid ship production | preview");
+  }
+  const wranglerBin = resolveBin(cwd, "wrangler", "wrangler");
+  if (!wranglerBin) fail("Could not find `wrangler` in this project.");
+  const run = (args) => {
+    out(`\n▸ wrangler ${args.join(" ")}`);
+    const res = spawnSync(process.execPath, [wranglerBin, ...args], { cwd, stdio: "inherit" });
+    if (res.status !== 0) process.exit(res.status ?? 1);
+  };
+  const wranglerPath = join(cwd, "wrangler.jsonc");
+  if (!existsSync(wranglerPath)) fail("wrangler.jsonc not found — run inside an Astroid project.");
+
+  if (target === "production") {
+    run(["d1", "migrations", "apply", "DB", "--remote"]);
+    run(["deploy"]);
+    return;
+  }
+
+  // The staging database is declared only inside `previews`, and wrangler's
+  // migrations command reads top-level `d1_databases`. So write a throwaway
+  // config naming it, derived from wrangler.jsonc on every run, rather than a
+  // second committed file that could drift from the binding.
+  const { parseJsonc } = await import(GENERATORS_URL);
+  const config = parseJsonc(readFileSync(wranglerPath, "utf8"));
+  const prodDb = (config.d1_databases ?? []).find((d) => d.binding === "DB");
+  const stagingDb = (config.previews?.d1_databases ?? []).find((d) => d.binding === "DB");
+  if (stagingDb && prodDb) {
+    const migrationsDir = resolve(cwd, prodDb.migrations_dir ?? "migrations");
+    const tmp = join(cwd, ".wrangler", "astroid-preview-migrations.jsonc");
+    mkdirSync(dirname(tmp), { recursive: true });
+    writeFileSync(
+      tmp,
+      JSON.stringify(
+        {
+          d1_databases: [
+            {
+              binding: "PREVIEW_DB",
+              database_name: stagingDb.database_name,
+              database_id: stagingDb.database_id,
+              migrations_dir: migrationsDir,
+            },
+          ],
+        },
+        null,
+        2,
+      ),
+    );
+    run(["d1", "migrations", "apply", "PREVIEW_DB", "--remote", "--config", tmp]);
+  } else {
+    out("\n(no staging D1 in `previews`, so no staging migrations to apply)");
+  }
+
+  // Workers Builds names the branch in WORKERS_CI_BRANCH; a Preview name is a
+  // DNS label, so a branch like feature/12-login becomes feature-12-login.
+  const branch = process.env.WORKERS_CI_BRANCH;
+  const name = branch
+    ? branch
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 63)
+    : undefined;
+  run(["preview", ...(name ? ["--name", name] : [])]);
+}
+
 async function main() {
   const { command, flags, rest } = parseArgs(process.argv.slice(2));
   const cwd = flags.cwd ? resolve(flags.cwd) : process.cwd();
@@ -622,6 +845,12 @@ async function main() {
     case "deploy":
       await cmdDeploy(cwd, flags, rest);
       break;
+    case "ship":
+      await cmdShip(cwd, rest[0]);
+      break;
+    case "provision":
+      await cmdProvision(cwd, rest);
+      break;
     case "help":
     case "--help":
     case "-h":

package/dist/portfolio/scaffold.js

@@ -62,8 +62,12 @@ export function generateAstroidGalleryPage(config) {
         "  // No DB binding yet (pre-provision)—render the empty state.",
         "}",
         "",
+        "// This environment's media base: production's, or a staging Preview's own",
+        "// `/media`, where the Preview's uploads live.",
+        `const mediaBase = (env.MEDIA_URL || ${JSON.stringify(mediaBase)}).replace(/\\/+$/, "");`,
+        "",
         "const items: GalleryItem[] = rows.map((row) => ({",
-        `  src: \`${mediaBase}/\${row.key}\`,`,
+        "  src: `${mediaBase}/${row.key}`,",
         '  // An asset with no alt gets "" rather than its filename: an empty alt makes',
         "  // a screen reader skip a decorative tile, while a filename is read aloud",
         "  // character by character and tells the listener nothing.",

package/dist/project/actions.js

@@ -61,6 +61,7 @@ export function generateAstroidActions(config) {
         // as a literal, and an unused import is a lint error in its own file.
         ...(columnsOverride ? [] : ["  ASTROID_SETTINGS_COLUMNS,"]),
         "  ASTROID_SETTINGS_IMAGE_KEYS,",
+        "  astroidMediaBase,",
         "  astroidPagesCollection,",
         '} from "astroidjs";',
         'import astroidConfig from "../../astroid.config.js";',
@@ -117,7 +118,11 @@ export function generateAstroidActions(config) {
         "        // than copied—a second literal here is a list that drifts from the",
         "        // one the routes check against, and nothing would fail when it did.",
         ...settingsExtra,
-        '        mediaBase: astroidConfig.deploy?.mediaBase ?? "/media",',
+        "        // Read on each save, so a staging Preview accepts images from its own",
+        "        // `/media` (see astroidMediaBase).",
+        "        get mediaBase() {",
+        "          return astroidMediaBase(astroidConfig);",
+        "        },",
         "      }),",
         "    ),",
         "  },",

package/dist/project/generate.js

@@ -209,10 +209,11 @@ export function generateAstroidWrangler(config) {
     p("  // KV: RL = the security rate limiter (it also holds the daily site-health");
     p("  // summary under its own key—one small singleton blob, not worth a binding");
     p("  // someone has to remember to provision); DRAFTS = the autosave write-buffer.");
-    p("  // Create each: `wrangler kv namespace create <RL|DRAFTS>`.");
+    p("  // Named for the project, so two sites in one account don't collide.");
+    p("  // `astroid provision` creates each and fills in its id.");
     p('  "kv_namespaces": [');
-    p('    { "binding": "RL", "id": "<run: wrangler kv namespace create RL>" },');
-    p('    { "binding": "DRAFTS", "id": "<run: wrangler kv namespace create DRAFTS>" },');
+    p(`    { "binding": "RL", "id": "<run: wrangler kv namespace create ${key}-rl>" },`);
+    p(`    { "binding": "DRAFTS", "id": "<run: wrangler kv namespace create ${key}-drafts>" },`);
     p("  ],");
     // Email Sending. NOT optional decoration: `src/env.d.ts` declares EMAIL as a
     // required member, and Better Auth's magic-link path console-logs the link in

package/dist/project/index.d.ts

@@ -2,3 +2,6 @@ export * from "./generate.js";
 export * from "./actions.js";
 export * from "./scaffold.js";
 export * from "./seed.js";
+export * from "./previews.js";
+export * from "./release.js";
+export * from "./provision.js";

package/dist/project/index.js

@@ -6,3 +6,6 @@ export * from "./generate.js";
 export * from "./actions.js";
 export * from "./scaffold.js";
 export * from "./seed.js";
+export * from "./previews.js";
+export * from "./release.js";
+export * from "./provision.js";

package/dist/project/previews.d.ts

@@ -0,0 +1,18 @@
+/** One finding, in the order `doctor` prints them. */
+export interface PreviewsFindings {
+    ok: string[];
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * Parse JSONC: strip `//` and block comments outside strings, then trailing
+ * commas. `wrangler.jsonc` is written by hand and commented heavily, which is
+ * why `doctor` reads the rest of it by regex; this check needs the structure.
+ */
+export declare function parseJsonc(text: string): unknown;
+/**
+ * Check the `previews` block of a `wrangler.jsonc` against its production
+ * settings. Returns what passed and what didn't; an error means a Preview
+ * would crash or touch production.
+ */
+export declare function checkWranglerPreviews(text: string): PreviewsFindings;

package/dist/project/previews.js

@@ -0,0 +1,215 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The `previews` block check `astroid doctor` runs (louise-toolkit ADR 0017).
+//
+// A site's staging is Cloudflare's Worker Previews: `main` and every pull
+// request run as Previews of the one Worker, with the settings in the
+// `previews` block of `wrangler.jsonc`. Previews inherit NOTHING from the top
+// level, which is the point and also the trap:
+//
+//   - A binding the code reads that the block leaves out is `undefined` on a
+//     Preview, and the Worker throws (Cloudflare's error 1101).
+//   - A binding the block copies verbatim points a Preview at production's
+//     database or bucket, so a branch writes production data. That's the
+//     failure staging exists to prevent, and nothing else would catch it.
+//   - Crons, routes, and queue consumers don't target Previews, so putting
+//     them in the block does nothing and reads as if it did.
+//
+// Pure: text in, findings out, so it's tested directly and the CLI only prints.
+/**
+ * Parse JSONC: strip `//` and block comments outside strings, then trailing
+ * commas. `wrangler.jsonc` is written by hand and commented heavily, which is
+ * why `doctor` reads the rest of it by regex; this check needs the structure.
+ */
+export function parseJsonc(text) {
+    let out = "";
+    let inString = false;
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        const next = text[i + 1];
+        if (inString) {
+            out += c;
+            if (c === "\\")
+                out += text[++i] ?? "";
+            else if (c === '"')
+                inString = false;
+        }
+        else if (c === '"') {
+            inString = true;
+            out += c;
+        }
+        else if (c === "/" && next === "/") {
+            while (i < text.length && text[i] !== "\n")
+                i++;
+            out += "\n";
+        }
+        else if (c === "/" && next === "*") {
+            i += 2;
+            while (i < text.length && !(text[i] === "*" && text[i + 1] === "/"))
+                i++;
+            i++;
+        }
+        else {
+            out += c;
+        }
+    }
+    return JSON.parse(out.replace(/,(\s*[}\]])/g, "$1"));
+}
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const list = (v) => (Array.isArray(v) ? v.filter(isObject) : []);
+const STORAGE = [
+    {
+        what: "D1 database",
+        get: (c) => list(c.d1_databases),
+        name: (b) => b.binding,
+        resource: (b) => String(b.database_id ?? b.database_name ?? ""),
+    },
+    {
+        what: "KV namespace",
+        get: (c) => list(c.kv_namespaces),
+        name: (b) => b.binding,
+        resource: (b) => String(b.id ?? ""),
+    },
+    {
+        what: "R2 bucket",
+        get: (c) => list(c.r2_buckets),
+        name: (b) => b.binding,
+        resource: (b) => String(b.bucket_name ?? ""),
+    },
+    {
+        what: "Secrets Store secret",
+        get: (c) => list(c.secrets_store_secrets),
+        name: (b) => b.binding,
+        resource: (b) => `${String(b.store_id ?? "")}/${String(b.secret_name ?? "")}`,
+    },
+    {
+        what: "Analytics Engine dataset",
+        get: (c) => list(c.analytics_engine_datasets),
+        name: (b) => b.binding,
+        resource: (b) => String(b.dataset ?? ""),
+    },
+    {
+        what: "Vectorize index",
+        get: (c) => list(c.vectorize),
+        name: (b) => b.binding,
+        resource: (b) => String(b.index_name ?? ""),
+    },
+    {
+        what: "queue producer",
+        get: (c) => list(isObject(c.queues) ? c.queues.producers : undefined),
+        name: (b) => b.binding,
+        resource: (b) => String(b.queue ?? ""),
+        optional: "queue consumers can't target a Preview, so a Preview leaves the queue unbound and the side effects run inline",
+    },
+    {
+        what: "Workflow",
+        get: (c) => list(c.workflows),
+        name: (b) => b.binding,
+        resource: (b) => String(b.name ?? ""),
+        optional: "a Preview calls the production Workflow's code and bindings, so it leaves the binding out and falls back",
+    },
+];
+/** Bindings with no staging resource behind them: a Preview needs the key, and
+ *  nothing to provision. A Durable Object namespace is one: Cloudflare gives
+ *  each Preview its own instances of the class. */
+const API_BINDINGS = [
+    "ai",
+    "images",
+    "browser",
+    "send_email",
+    "version_metadata",
+    "durable_objects",
+];
+/**
+ * Check the `previews` block of a `wrangler.jsonc` against its production
+ * settings. Returns what passed and what didn't; an error means a Preview
+ * would crash or touch production.
+ */
+export function checkWranglerPreviews(text) {
+    const findings = { ok: [], errors: [], warnings: [] };
+    let config;
+    try {
+        const parsed = parseJsonc(text);
+        if (!isObject(parsed))
+            throw new Error("not an object");
+        config = parsed;
+    }
+    catch (err) {
+        findings.errors.push(`wrangler.jsonc doesn't parse (${err.message}).`);
+        return findings;
+    }
+    const previews = config.previews;
+    if (!isObject(previews)) {
+        findings.warnings.push("wrangler.jsonc has no `previews` block, so this site has no staging. Branch builds " +
+            "either fail or run with production's data (louise-toolkit ADR 0017).");
+        return findings;
+    }
+    for (const key of ["triggers", "routes"]) {
+        if (key in previews) {
+            findings.errors.push(`\`previews.${key}\` does nothing: ${key === "triggers" ? "Cron Triggers" : "routes"} ` +
+                "target production only. Remove it; Preview hosts come from a route with " +
+                "`previews_enabled` at the top level.");
+        }
+    }
+    if (isObject(previews.queues) && "consumers" in previews.queues) {
+        findings.errors.push("`previews.queues.consumers` does nothing: queue consumers can't target a Preview. Remove it.");
+    }
+    for (const kind of STORAGE) {
+        const staging = new Map(kind.get(previews).map((b) => [kind.name(b), b]));
+        for (const prod of kind.get(config)) {
+            const name = String(kind.name(prod));
+            const preview = staging.get(kind.name(prod));
+            if (!preview) {
+                if (kind.optional)
+                    findings.ok.push(`previews: ${kind.what} \`${name}\` left out (${kind.optional})`);
+                else
+                    findings.errors.push(`\`previews\` has no ${kind.what} \`${name}\`. A Preview inherits nothing, so code ` +
+                        `that reads \`env.${name}\` throws there. Bind it to a staging ${kind.what}.`);
+            }
+            else if (kind.resource(preview) === kind.resource(prod)) {
+                findings.errors.push(`\`previews\` binds ${kind.what} \`${name}\` to production's (${kind.resource(prod)}), ` +
+                    "so every branch would read and write production data. Bind it to a staging one.");
+            }
+            else {
+                findings.ok.push(`previews: ${kind.what} \`${name}\` bound to a staging resource`);
+            }
+        }
+    }
+    for (const key of API_BINDINGS) {
+        if (!(key in config))
+            continue;
+        if (key in previews)
+            findings.ok.push(`previews: \`${key}\` binding present`);
+        else
+            findings.errors.push(`\`previews\` has no \`${key}\` binding. A Preview inherits nothing, so code that uses ` +
+                "it throws there. Copy the binding into `previews`; it needs no staging resource.");
+    }
+    const prodVars = isObject(config.vars) ? config.vars : {};
+    const stagingVars = isObject(previews.vars) ? previews.vars : {};
+    const missingVars = Object.keys(prodVars).filter((key) => !(key in stagingVars));
+    if (missingVars.length) {
+        findings.errors.push(`\`previews.vars\` is missing ${missingVars.map((v) => `\`${v}\``).join(", ")}. Vars aren't ` +
+            "inherited, so each is undefined on a Preview. Give each a staging value.");
+    }
+    else if (Object.keys(prodVars).length) {
+        findings.ok.push(`previews: all ${Object.keys(prodVars).length} vars have a staging value`);
+    }
+    for (const key of ["SITE_URL", "MEDIA_URL"]) {
+        const value = prodVars[key];
+        // A path such as `/media` resolves against whichever host serves it, so a
+        // Preview sharing production's path still serves its own bucket.
+        const isOrigin = typeof value === "string" && /^https?:\/\//.test(value);
+        if (key in prodVars && isOrigin && stagingVars[key] === value) {
+            findings.errors.push(`\`previews.vars.${key}\` is production's (${String(prodVars[key])}), so a Preview ` +
+                "links to or serves from production. Point it at staging.");
+        }
+    }
+    const previewHost = list(config.routes).find((r) => r.previews_enabled === true);
+    if (previewHost)
+        findings.ok.push(`previews: served on \`<name>.${String(previewHost.pattern)}\``);
+    else
+        findings.warnings.push("No route has `previews_enabled`, so Previews are reachable only on workers.dev. Add a " +
+            'preview-only custom domain: `{ "pattern": "staging.example.com", "custom_domain": true, ' +
+            '"previews_enabled": true, "enabled": false }`.');
+    return findings;
+}

package/dist/project/provision.d.ts

@@ -0,0 +1,26 @@
+/** One resource to create. `placeholder` is the text its ID replaces. */
+export interface ProvisionStep {
+    kind: "d1" | "kv" | "r2";
+    name: string;
+    /** The `wrangler` arguments that create it. */
+    args: string[];
+    placeholder?: string;
+}
+/** A Secrets Store secret the config binds, which only a person can set. */
+export interface ProvisionSecret {
+    binding: string;
+    storeId: string;
+    secretName: string;
+    /** `production` for a top-level binding, `staging` for one in `previews`. */
+    environment: "production" | "staging";
+}
+export interface ProvisionPlan {
+    steps: ProvisionStep[];
+    secrets: ProvisionSecret[];
+    /** Whether `account_id` is set, so wrangler doesn't have to pick one. */
+    hasAccount: boolean;
+}
+/** Build the plan from a `wrangler.jsonc`, top level and `previews` alike. */
+export declare function provisionPlan(text: string): ProvisionPlan;
+/** Put a created resource's ID in place of its placeholder, everywhere. */
+export declare function applyProvisionedId(text: string, placeholder: string, id: string): string;

package/dist/project/provision.js

@@ -0,0 +1,65 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The plan `astroid provision` runs: which Cloudflare resources a site's
+// `wrangler.jsonc` still names by placeholder, and which secrets it binds.
+//
+// A placeholder names the command that creates its resource, such as
+// `<run: wrangler d1 create acme-staging>`, so the plan reads it rather than
+// guessing a name. The same placeholder can stand for two bindings that share
+// one namespace, and replacing the text everywhere it appears fills both.
+// Buckets carry a name instead of an ID, so every bucket the file names is
+// created, and one that already exists is fine.
+//
+// Pure: text in, plan out, so it's tested directly and the CLI only runs it.
+import { parseJsonc } from "./previews.js";
+const PLACEHOLDER = /<run:\s*wrangler\s+(d1\s+create|kv\s+namespace\s+create)\s+([^\s>]+)\s*>/g;
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const list = (v) => (Array.isArray(v) ? v.filter(isObject) : []);
+/** Build the plan from a `wrangler.jsonc`, top level and `previews` alike. */
+export function provisionPlan(text) {
+    const steps = [];
+    const seen = new Set();
+    for (const match of text.matchAll(PLACEHOLDER)) {
+        const placeholder = match[0];
+        if (seen.has(placeholder))
+            continue;
+        seen.add(placeholder);
+        const name = match[2];
+        steps.push(match[1].startsWith("d1")
+            ? { kind: "d1", name, args: ["d1", "create", name], placeholder }
+            : { kind: "kv", name, args: ["kv", "namespace", "create", name], placeholder });
+    }
+    const config = parseJsonc(text);
+    const top = isObject(config) ? config : {};
+    const previews = isObject(top.previews) ? top.previews : {};
+    const buckets = new Set([...list(top.r2_buckets), ...list(previews.r2_buckets)]
+        .map((b) => b.bucket_name)
+        .filter((name) => typeof name === "string" && !name.startsWith("<")));
+    for (const name of buckets) {
+        steps.push({ kind: "r2", name, args: ["r2", "bucket", "create", name] });
+    }
+    const secrets = [];
+    for (const [environment, section] of [
+        ["production", top],
+        ["staging", previews],
+    ]) {
+        for (const s of list(section.secrets_store_secrets)) {
+            secrets.push({
+                binding: String(s.binding ?? ""),
+                storeId: String(s.store_id ?? ""),
+                secretName: String(s.secret_name ?? ""),
+                environment,
+            });
+        }
+    }
+    const account = top.account_id;
+    return {
+        steps,
+        secrets,
+        hasAccount: typeof account === "string" && account.length > 0 && !account.startsWith("<"),
+    };
+}
+/** Put a created resource's ID in place of its placeholder, everywhere. */
+export function applyProvisionedId(text, placeholder, id) {
+    return text.split(placeholder).join(id);
+}

package/dist/project/release.d.ts

@@ -0,0 +1,6 @@
+/** The branch Workers Builds deploys to production from. */
+export declare const ASTROID_DEPLOY_BRANCH = "deploy/production";
+/** Where the workflow lives, relative to the repository root. */
+export declare const ASTROID_RELEASE_WORKFLOW_PATH = ".github/workflows/release.yml";
+/** The release workflow's contents. Pure, and the same for every site. */
+export declare function generateAstroidReleaseWorkflow(): string;

package/dist/project/release.js

@@ -0,0 +1,79 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The release workflow every site runs (louise-toolkit ADR 0017, amended).
+//
+// Releases are trunk-based: a `v<version>` tag on a commit of `main` is the
+// release, and a `release/<version>` branch exists only when a released version
+// needs a patch and `main` has moved on. Workers Builds deploys on branch
+// pushes and can't watch tags, so the tag's workflow moves one branch,
+// `deploy/production`, to the tagged commit, and Workers Builds deploys that.
+// Nobody commits to the branch; it's a tag carried as a branch, and GitHub never
+// holds a Cloudflare credential.
+//
+// A regenerated file, like the worker trio: `astroid generate` rewrites it and
+// `astroid doctor` fails when it drifts, so a hand edit can't quietly change
+// which commits reach production.
+/** The branch Workers Builds deploys to production from. */
+export const ASTROID_DEPLOY_BRANCH = "deploy/production";
+/** Where the workflow lives, relative to the repository root. */
+export const ASTROID_RELEASE_WORKFLOW_PATH = ".github/workflows/release.yml";
+/** The release workflow's contents. Pure, and the same for every site. */
+export function generateAstroidReleaseWorkflow() {
+    return `# Generated by astroid. Don't edit: \`astroid generate\` rewrites this file and
+# \`astroid doctor\` fails when it drifts.
+#
+# A release is a tag, v<major>.<minor>.<patch>, on a commit of main, or of a
+# release/<version> branch when a released version needs a patch. This moves
+# ${ASTROID_DEPLOY_BRANCH} to the tagged commit, and Workers Builds deploys it to
+# production. Nobody commits to ${ASTROID_DEPLOY_BRANCH}; a repository ruleset lets
+# only this workflow update it. To roll back, tag the earlier commit with the
+# next patch version.
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write
+
+# One release at a time, in the order the tags arrived.
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Check the tag
+        run: |
+          tag="$GITHUB_REF_NAME"
+          if ! [[ "$tag" =~ ^v[0-9]+\\.[0-9]+\\.[0-9]+$ ]]; then
+            echo "::error::A release tag is v<major>.<minor>.<patch>, such as v1.4.0. Got $tag."
+            exit 1
+          fi
+          sha="$(git rev-list -n 1 "$tag")"
+          if git merge-base --is-ancestor "$sha" origin/main; then
+            echo "$tag is on main."
+          elif git branch -r --contains "$sha" | grep -q "origin/release/"; then
+            echo "$tag is on a release branch."
+          else
+            echo "::error::$tag isn't on main or a release/ branch, so it can't be released."
+            exit 1
+          fi
+          echo "SHA=$sha" >> "$GITHUB_ENV"
+
+      - name: Move ${ASTROID_DEPLOY_BRANCH} to the tag
+        run: git push --force origin "$SHA:refs/heads/${ASTROID_DEPLOY_BRANCH}"
+
+      - name: Create the GitHub release
+        env:
+          GH_TOKEN: \${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" --verify-tag --generate-notes
+`;
+}

package/dist/queues/scaffold.js

@@ -196,10 +196,14 @@ export function generateAstroidWebhookRoute(config, forProvider) {
         "// Unprovisioned (the secret is absent or still the placeholder) answers 503,",
         "// which keeps the provider retrying—so events delivered before you set the",
         "// secret land afterwards instead of being lost.",
+        "//",
+        "// A staging Preview has no queue, since a consumer can't target one, so",
+        "// there the event runs in the request through the same handler instead.",
         'import type { APIRoute } from "astro";',
         'import { handleWebhook, readModuleSecret } from "astroidjs";',
         'import { env } from "cloudflare:workers";',
         `import { ${p.verifier} } from ${JSON.stringify(p.module)};`,
+        'import { handleQueueMessage } from "../../../queue";',
         "",
         "export const prerender = false;",
         "",
@@ -211,6 +215,7 @@ export function generateAstroidWebhookRoute(config, forProvider) {
         `    provider: ${JSON.stringify(provider)},`,
         `    secret: await readModuleSecret(env.${COMMERCE_PROVIDER_SECRETS[provider].webhook}),`,
         `    queue: env.${ASTROID_QUEUE_BINDING},`,
+        "    inline: (message) => handleQueueMessage(env, message),",
         `    verify: ({ raw, secret }) => ${p.call},`,
         "  });",
         "};",

package/dist/queues/webhook.d.ts

@@ -30,6 +30,22 @@ export interface WebhookRouteOptions {
     verify: (input: WebhookVerifyInput) => boolean | Promise<boolean>;
     /** The queue binding, or null/undefined when Queues aren't provisioned. */
     queue?: QueueProducer | null;
+    /**
+     * Run a message in the request instead, when `queue` is absent. A staging
+     * Preview leaves the queue unbound, because a queue consumer can't target a
+     * Preview (louise-toolkit ADR 0017), so without this every webhook a Preview
+     * receives answers 503 and the provider retries it forever.
+     *
+     * Pass the same handler the queue consumer runs: `(message) =>
+     * handleQueueMessage(env, message)`. Throwing answers 503, so the provider
+     * redelivers, which is the retry the queue would have given it.
+     *
+     * It's a fallback, not an alternative: a sync that outlasts the provider's
+     * delivery timeout reads to the provider as a failure, which is why
+     * production enqueues. On staging, with a sandbox catalog, that's a fair
+     * trade, and the queue wins whenever both are there.
+     */
+    inline?: (message: AstroidQueueMessage) => Promise<void>;
     /**
      * Pull the event type out of the parsed payload. Defaults to a `type` field;
      * override for providers that name it differently (Fourthwall's `testMode`

package/dist/queues/webhook.js

@@ -65,10 +65,27 @@ export async function handleWebhook(request, url, options) {
     if (options.accept && !options.accept(type, payload)) {
         return text("Ignored", 202);
     }
-    if (!options.queue)
-        return text("Queue not configured", 503);
+    const message = {
+        kind: "webhook",
+        provider: options.provider,
+        type,
+        payload,
+    };
+    if (!options.queue) {
+        if (!options.inline)
+            return text("Queue not configured", 503);
+        try {
+            await options.inline(message);
+        }
+        catch {
+            // Same contract as a failed send: the event is real, so ask for it again.
+            return text("Processing failed", 503);
+        }
+        // 200, not 202: the work already happened.
+        return text("Processed", 200);
+    }
     try {
-        await options.queue.send({ kind: "webhook", provider: options.provider, type, payload });
+        await options.queue.send(message);
     }
     catch {
         // The signature was good, so this event is real and worth keeping. 503 asks

package/dist/schema/collections.js

@@ -21,6 +21,7 @@
 // `louise-toolkit/src/...`—that resolves only because the workspace aliases the
 // package to its source, and would break the moment astroid consumes a published
 // tarball (#327).
+import { astroidMediaBase } from "./media-base.js";
 import { defineCollection, } from "louise-toolkit/content/define";
 import { assertValidSections, sanitizeSectionsRichText } from "louise-toolkit/content/sections";
 import { sanitizeRichHtml } from "louise-toolkit/security";
@@ -39,10 +40,9 @@ import { astroidSectionCatalog } from "../components/sections.js";
  * Validated by `defineCollection` at build time, so a malformed field shape throws
  * here rather than at codegen.
  */
-/** The media base a `pages` write sanitizes rich content against (config, `/media` default). */
-function pageMediaBase(config) {
-    return config.deploy?.mediaBase ?? "/media";
-}
+/** The media base a `pages` write sanitizes rich content against, read when the
+ *  write runs so a Preview checks against its own base (see media-base.ts). */
+const pageMediaBase = astroidMediaBase;
 /**
  * The section catalog a `pages` write is validated + sanitized against: the
  * site's own (`config.sectionCatalog`) when it registered bespoke sections, else
@@ -113,12 +113,11 @@ export const ASTROID_RESERVED_SLUGS = [
     "sitemap.xml",
 ];
 export function astroidPagesWriteHooks(config, site = {}) {
-    const mediaBase = pageMediaBase(config);
     return {
         // `body` is a richField, so it goes through pagesRoute's own sanitize seam—with
         // the project media base, matching the hook rather than the toolkit
         // default sanitizer that knows no media base.
-        sanitize: (html) => sanitizeRichHtml(html, { mediaBase }),
+        sanitize: (html) => sanitizeRichHtml(html, { mediaBase: pageMediaBase(config) }),
         // `sections` is not a richField, so it's sanitized here in the transform,
         // which pagesRoute runs BEFORE validate—the hook's sanitize-then-validate
         // order. The site's own transform runs first, so Astroid's sanitize sees
@@ -136,7 +135,6 @@ export function astroidPagesCollection(config) {
     // staged as a draft, so sanitize it on every write—never store raw HTML. A
     // pasted `<img>` pointing off-origin (a hotlink) is dropped: body images must
     // live in the media library. Mirrors the reference site's pages-collection hook.
-    const mediaBase = pageMediaBase(config);
     const fields = {};
     fields.slug = { type: "text", required: true };
     fields.title = { type: "text", required: true };
@@ -158,7 +156,10 @@ export function astroidPagesCollection(config) {
                 async ({ data }) => {
                     let next = data;
                     if (typeof next.body === "string") {
-                        next = { ...next, body: sanitizeRichHtml(next.body, { mediaBase }) };
+                        next = {
+                            ...next,
+                            body: sanitizeRichHtml(next.body, { mediaBase: pageMediaBase(config) }),
+                        };
                     }
                     // Sanitize BEFORE validating: a richText field stores HTML, and
                     // validating the raw value would pass content the sanitizer is about

package/dist/schema/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./collections.js";
 export * from "./framework.js";
 export * from "./generate.js";
+export * from "./media-base.js";

package/dist/schema/index.js

@@ -4,3 +4,4 @@
 export * from "./collections.js";
 export * from "./framework.js";
 export * from "./generate.js";
+export * from "./media-base.js";

package/dist/schema/media-base.d.ts

@@ -0,0 +1,13 @@
+import type { AstroidConfig } from "../config.js";
+/**
+ * Record the running deployment's media base, `vars.MEDIA_URL`. The generated
+ * worker calls this at startup; an empty or absent value leaves the config's
+ * base in effect.
+ */
+export declare function setAstroidMediaBase(base: string | undefined): void;
+/**
+ * The media base a write is checked against: the running deployment's when the
+ * worker recorded one, else `deploy.mediaBase`, else `/media`. Call it when the
+ * check runs, not when it's built.
+ */
+export declare function astroidMediaBase(config: AstroidConfig): string;

package/dist/schema/media-base.js

@@ -0,0 +1,33 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The media base the running Worker serves from, for the checks that can't read
+// a request's `env`.
+//
+// The page sanitizers and the settings action are built once, from the config,
+// and drizzle-kit loads the schema that builds them outside a Worker. So they
+// can't take `env.MEDIA_URL` the way the generated routes do. Left on the fixed
+// `deploy.mediaBase`, a staging Preview, which serves media from its own
+// `/media`, drops every image uploaded on it as a hotlink.
+//
+// So the generated worker records `MEDIA_URL` once, at startup, and these checks
+// read it when they run. That's safe as module state because a Worker isolate
+// runs one deployment, and `MEDIA_URL` is fixed per deployment: production's
+// isolates hold production's base, and a Preview's hold the Preview's.
+let runtimeMediaBase;
+/**
+ * Record the running deployment's media base, `vars.MEDIA_URL`. The generated
+ * worker calls this at startup; an empty or absent value leaves the config's
+ * base in effect.
+ */
+export function setAstroidMediaBase(base) {
+    const trimmed = base?.replace(/\/+$/, "");
+    runtimeMediaBase = trimmed ? trimmed : undefined;
+}
+/**
+ * The media base a write is checked against: the running deployment's when the
+ * worker recorded one, else `deploy.mediaBase`, else `/media`. Call it when the
+ * check runs, not when it's built.
+ */
+export function astroidMediaBase(config) {
+    return runtimeMediaBase ?? (config.deploy?.mediaBase ?? "/media").replace(/\/+$/, "");
+}

package/dist/worker/generate.js

@@ -122,7 +122,9 @@ export function generateAstroidWorker(config) {
                 // The site's sanitize + read hooks (config.settings.hooks), spread last
                 // so they add to the call rather than replace any part of it.
                 const hooksArg = config.settings?.hooks ? ", ...settingsHooks" : "";
-                return `settingsRoute({ table: siteSettings, resolveEditor, columns: SETTINGS_COLUMNS, imageKeys: SETTINGS_IMAGE_KEYS, mediaBase: MEDIA_BASE${customArg}${hooksArg} })`;
+                // Built per request, because the media base is per environment: a
+                // Preview's `MEDIA_URL` differs from production's (see `mediaBaseOf`).
+                return `(request, env, ctx) => settingsRoute({ table: siteSettings, resolveEditor, columns: SETTINGS_COLUMNS, imageKeys: SETTINGS_IMAGE_KEYS, mediaBase: mediaBaseOf(env)${customArg}${hooksArg} })(request, env, ctx)`;
             }
             // `aiRunner` rather than `(env) => env.AI`: it reads the binding AND the
             // LOUISE_AI kill switch, so all three assists share one definition of
@@ -201,6 +203,7 @@ export function generateAstroidWorker(config) {
         "astroidPagesCollection",
         "astroidPagesWriteHooks",
         "readModuleSecret",
+        "setAstroidMediaBase",
         ...(inquiries ? ["sendInquiryMail"] : []),
         ...(queues ? ["type AstroidQueueMessage"] : []),
     ].sort();
@@ -228,7 +231,18 @@ export function generateAstroidWorker(config) {
         p('import { handleQueueMessage } from "./queue.js";');
     }
     p();
-    p(`const MEDIA_BASE = ${JSON.stringify(mediaBase)};`);
+    p(`const DEFAULT_MEDIA_BASE = ${JSON.stringify(mediaBase)};`);
+    p("// The public media base for this request's environment. `vars.MEDIA_URL`");
+    p('// wins, so a Preview sets its own (a path such as "/media", served from the');
+    p("// Preview's own host, since a Preview can't know its hostname in advance).");
+    p("// Read per request, not baked in: one build serves production and every");
+    p("// Preview, so nothing that differs between them can be a constant.");
+    p("const mediaBaseOf = (env: CloudflareEnv): string =>");
+    p('  (env.MEDIA_URL || DEFAULT_MEDIA_BASE).replace(/\\/+$/, "");');
+    p("// The checks built once from the config (the page sanitizers, the settings");
+    p("// action) read the base when they run. Recorded at startup, since an isolate");
+    p("// runs one deployment and `MEDIA_URL` is fixed per deployment.");
+    p("setAstroidMediaBase(env.MEDIA_URL);");
     p("const pagesCollection = astroidPagesCollection(astroidConfig);");
     p("// Sanitize + section-catalog validation for the raw pagesRoute, which runs");
     p("// no collection hook—the same contract versionsRoute gets from the config.");
@@ -294,7 +308,7 @@ export function generateAstroidWorker(config) {
     p("// failed crawl or a failed COUNT yields zero rather than aborting the scan,");
     p("// because a partial health report is worth strictly more than none.");
     p("async function runHealthScan(env: CloudflareEnv) {");
-    p("  const origin = env.SITE_URL ?? MEDIA_BASE;");
+    p("  const origin = env.SITE_URL ?? mediaBaseOf(env);");
     p("  const [brokenLinks, missingAlt, seoGaps] = await Promise.all([");
     p('    checkLinks({ base: origin, paths: ["/"] }).catch(() => []),');
     p("    countRows(env, \"SELECT COUNT(*) AS n FROM media WHERE alt IS NULL OR alt = ''\"),");
@@ -376,17 +390,26 @@ export function generateAstroidWorker(config) {
     }
     p("];");
     p();
-    p("// Stream uploaded media back from R2 at MEDIA_BASE (self-hosted, no public bucket).");
+    p("// Stream uploaded media back from R2 at the media base (self-hosted, no public");
+    p("// bucket). The base takes two shapes, and each is matched its own way:");
     p("//");
-    p("// Scoped by ORIGIN, not by path prefix: MEDIA_BASE is an origin, and a");
-    p('// `url.pathname` ("/web/foo.jpg") can never start with one. Comparing the two');
-    p("// against each other made the guard permanently false, so the route never ran");
-    p("// and every uploaded asset fell through to the site's 404 page. On the media");
-    p("// host the whole pathname is the R2 key.");
+    p('// - An ORIGIN ("https://media.example.com") is a media host, where the whole');
+    p("//   pathname is the R2 key. Compared by origin, never by path prefix: a");
+    p('//   `url.pathname` ("/web/foo.jpg") can never start with an origin, and a guard');
+    p("//   that compared the two once never ran, so every upload 404'd.");
+    p('// - A PATH ("/media") is a prefix on the site\'s own host, which is how a');
+    p("//   Preview serves media, since it can't know its hostname in advance.");
     p("const mediaAssetRoute: WorkerRoute<CloudflareEnv> = async (request, env) => {");
     p("  const url = new URL(request.url);");
-    p("  if (url.origin !== MEDIA_BASE) return undefined;");
-    p("  const key = decodeURIComponent(url.pathname.slice(1));");
+    p("  const base = mediaBaseOf(env);");
+    p('  const path = base.startsWith("/")');
+    p("    ? url.pathname.startsWith(`${base}/`)");
+    p("      ? url.pathname.slice(base.length + 1)");
+    p('      : ""');
+    p("    : url.origin === base");
+    p("      ? url.pathname.slice(1)");
+    p('      : "";');
+    p("  const key = decodeURIComponent(path);");
     p("  if (!key) return undefined;");
     p("  const obj = await env.MEDIA.get(key);");
     p('  if (!obj) return new Response("Not found", { status: 404 });');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astroidjs",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Astroid — an opinionated meta-framework over Louise Toolkit and Astro for building editable, multi-editor sites on Cloudflare Workers.",
   "keywords": [
     "astro",