astroidjs 0.6.0 → 0.7.0

package/dist/commerce/checkout.d.ts

@@ -17,18 +17,83 @@ export interface VerifiedLine {
     unitPriceCents: number;
     subtotalCents: number;
 }
+/**
+ * Why a cart was refused.
+ *
+ * `"unavailable"` and `"out-of-stock"` are deliberately distinct even though
+ * both come back as "the lookup didn't price it". They are different facts about
+ * the world and want different words in front of a customer: a delisted item is
+ * gone and should leave the cart, while a sold-out one is coming back and is
+ * worth a notify-me. Collapsing them tells someone to remove an item the shop
+ * will restock on Tuesday.
+ *
+ * A lookup can only produce `"out-of-stock"` by saying so — see
+ * {@link ScopedPriceLookup} — because a bare `Map` has no way to distinguish
+ * them and guessing would put the wrong sentence on the screen.
+ */
+export type CheckoutRefusal = "empty" | "unavailable" | "out-of-stock" | "price-changed" | "invalid";
 export type CheckoutVerification = {
     ok: true;
     lines: VerifiedLine[];
     subtotalCents: number;
 } | {
     ok: false;
-    reason: "empty" | "unavailable" | "price-changed" | "invalid";
+    reason: CheckoutRefusal;
     message: string;
 };
 /** Look up current prices, in minor units, keyed by variant id. Anything the
  *  map omits is treated as no longer purchasable. */
 export type PriceLookup = (variantIds: string[]) => Promise<Map<string, number>>;
+/** Where the sale is happening. Optional, and providers without a location
+ *  dimension ignore it — a single-merchant Square account or Fourthwall store
+ *  passes nothing and behaves exactly as before. */
+export interface CheckoutScope {
+    /** Provider location id (Square) or equivalent merchant key. */
+    locationId?: string;
+}
+/**
+ * A richer lookup result, for providers that can tell "delisted" from
+ * "sold out".
+ *
+ * A lookup may return either a plain `Map<string, number>` (prices only, an
+ * omission means unavailable) or this. Both are accepted, so the plain form
+ * stays valid and nothing existing has to change.
+ */
+export interface ScopedPrices {
+    /** variantId → unit price in minor units, at the requested scope. */
+    prices: Map<string, number>;
+    /** Variant ids that exist and are priced but cannot be sold right now. */
+    outOfStock?: Iterable<string>;
+}
+/**
+ * A price lookup that knows WHERE the sale is happening.
+ *
+ * This is the multi-merchant checkout guard. One shared catalog sold through
+ * several merchants carries a different price per location — each shop's
+ * commission is absorbed in its own override — so re-pricing a cart against
+ * base prices lets a customer pay the cheapest merchant's price at the dearest
+ * merchant's storefront. That is not a rounding error; it is the same class of
+ * bug as trusting the client's `unitPriceCents`, just one level further back.
+ *
+ * `scope` is optional so a {@link PriceLookup} is still assignable here — an
+ * existing single-location lookup simply ignores the extra argument, which is
+ * exactly what a function of lower arity does in JavaScript.
+ *
+ * Return the map alone, or a {@link ScopedPrices} when the provider can
+ * distinguish sold-out from delisted:
+ *
+ * ```ts
+ * const lookup: ScopedPriceLookup = async (ids, scope) => {
+ *   const money = await retrieveVariationPricesAt(sq, ids, scope?.locationId ?? DEFAULT);
+ *   return new Map([...money].map(([id, m]) => [id, m.amount]));
+ * };
+ * ```
+ */
+export type ScopedPriceLookup = (variantIds: string[], scope?: CheckoutScope) => Promise<Map<string, number> | ScopedPrices>;
+export interface VerifyCheckoutOptions {
+    /** Passed through to the lookup. Omit for a single-location store. */
+    scope?: CheckoutScope;
+}
 /**
  * Re-price a cart against the provider and decide whether it may proceed.
  *
@@ -37,8 +102,15 @@ export type PriceLookup = (variantIds: string[]) => Promise<Map<string, number>>
  * if (!check.ok) return json({ error: check.message }, 409);
  * await charge(check.subtotalCents);   // the SERVER's number
  * ```
+ *
+ * With a per-merchant catalog, pass the location the order is being placed at
+ * and use a lookup that resolves overrides:
+ *
+ * ```ts
+ * const check = await verifyCheckout(body.lines, pricesAt, { scope: { locationId } });
+ * ```
  */
-export declare function verifyCheckout(lines: unknown, lookup: PriceLookup): Promise<CheckoutVerification>;
+export declare function verifyCheckout(lines: unknown, lookup: ScopedPriceLookup, options?: VerifyCheckoutOptions): Promise<CheckoutVerification>;
 /**
  * A deterministic idempotency key for one buyer's checkout attempt.
  *

package/dist/commerce/checkout.js

@@ -14,6 +14,12 @@
 // body and anyone can buy anything for a penny.
 import { AstroidUsageError } from "../errors.js";
 const MAX_QUANTITY = 999;
+/** Accept either lookup shape without making every caller branch. */
+function normalizeLookup(result) {
+    if (result instanceof Map)
+        return { prices: result, outOfStock: new Set() };
+    return { prices: result.prices, outOfStock: new Set(result.outOfStock ?? []) };
+}
 /**
  * Re-price a cart against the provider and decide whether it may proceed.
  *
@@ -22,8 +28,19 @@ const MAX_QUANTITY = 999;
  * if (!check.ok) return json({ error: check.message }, 409);
  * await charge(check.subtotalCents);   // the SERVER's number
  * ```
+ *
+ * With a per-merchant catalog, pass the location the order is being placed at
+ * and use a lookup that resolves overrides:
+ *
+ * ```ts
+ * const check = await verifyCheckout(body.lines, pricesAt, { scope: { locationId } });
+ * ```
  */
-export async function verifyCheckout(lines, lookup) {
+export async function verifyCheckout(lines, 
+// Typed as the scoped form alone rather than a union: a `PriceLookup` is
+// already structurally assignable here (fewer parameters, narrower return),
+// and a union of call signatures would reject the two-argument call below.
+lookup, options = {}) {
     if (!Array.isArray(lines) || lines.length === 0) {
         return { ok: false, reason: "empty", message: "Your cart is empty." };
     }
@@ -44,10 +61,20 @@ export async function verifyCheckout(lines, lookup) {
         }
         parsed.push({ variantId: l.variantId, quantity: l.quantity, unitPriceCents: l.unitPriceCents });
     }
-    const prices = await lookup([...new Set(parsed.map((l) => l.variantId))]);
+    const { prices, outOfStock } = normalizeLookup(await lookup([...new Set(parsed.map((l) => l.variantId))], options.scope));
     const verified = [];
     let subtotalCents = 0;
     for (const line of parsed) {
+        // Checked before the price, because a sold-out variant is usually still
+        // priced: reading `prices` first would report it as available and let the
+        // charge through.
+        if (outOfStock.has(line.variantId)) {
+            return {
+                ok: false,
+                reason: "out-of-stock",
+                message: "An item in your cart just sold out.",
+            };
+        }
         const serverPrice = prices.get(line.variantId);
         if (serverPrice === undefined) {
             return {

package/dist/commerce/index.d.ts

@@ -1,5 +1,5 @@
-export { catalogNormalizer, type FourthwallProductLike, fourthwallToCatalogItem, type SquareItemLike, squareToCatalogItem, } from "./adapters.js";
-export { type CheckoutVerification, checkoutIdempotencyKey, type ClientLine, type PriceLookup, verifyCheckout, type VerifiedLine, } from "./checkout.js";
+export { catalogNormalizer, type FourthwallProductLike, fourthwallToCatalogItem, type SquareAdapterOptions, squareItemSoldAt, type SquareItemLike, type SquareLocationOverrideLike, type SquarePresenceLike, squareToCatalogItem, } from "./adapters.js";
+export { type CheckoutRefusal, type CheckoutScope, type CheckoutVerification, checkoutIdempotencyKey, type ClientLine, type PriceLookup, type ScopedPriceLookup, type ScopedPrices, verifyCheckout, type VerifiedLine, type VerifyCheckoutOptions, } from "./checkout.js";
 export { astroidCatalogLoaderConfig, type CatalogDatabase, type CatalogProduct, type CatalogReadOptions, readCatalog, readCatalogItem, } from "./loader.js";
 export { astroidCatalogMirror, BUILT_IN_OWNED, type CatalogMirrorConfig, generateCatalogMigrationSql, generateCatalogTable, type OwnedColumn, PULLED_COLUMNS, } from "./mirror.js";
 export { COMMERCE_PROVIDER_SECRETS, type CommerceStatus, commerceSecretNames, type ProviderStatus, providerConfigured, resolveCommerceStatus, roleConfigured, } from "./secrets.js";

package/dist/commerce/index.js

@@ -1,5 +1,5 @@
 // Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
-export { catalogNormalizer, fourthwallToCatalogItem, squareToCatalogItem, } from "./adapters.js";
+export { catalogNormalizer, fourthwallToCatalogItem, squareItemSoldAt, squareToCatalogItem, } from "./adapters.js";
 export { checkoutIdempotencyKey, verifyCheckout, } from "./checkout.js";
 export { astroidCatalogLoaderConfig, readCatalog, readCatalogItem, } from "./loader.js";
 export { astroidCatalogMirror, BUILT_IN_OWNED, generateCatalogMigrationSql, generateCatalogTable, PULLED_COLUMNS, } from "./mirror.js";

package/dist/config.d.ts

@@ -212,6 +212,76 @@ export interface QueuesConfig {
     /** Seconds the consumer waits to fill a batch. Default 30. */
     maxBatchTimeout?: number;
 }
+/**
+ * One project-declared scheduled trigger, beyond the two Astroid derives (the
+ * daily health scan and the hourly catalog re-sync).
+ *
+ * Declaring it here rather than by hand is what keeps `wrangler.jsonc` and the
+ * generated `scheduled` dispatch in agreement. Adding a cron to `triggers.crons`
+ * alone produces a trigger Cloudflare fires and the dispatch never matches —
+ * unreachable code that costs an invocation and does nothing, with no error
+ * anywhere. Adding it in the dashboard instead drifts from the config that is
+ * supposed to describe the deploy.
+ */
+/**
+ * Serve `*.example.com` from this one Worker — scoped views of **this brand's**
+ * data, narrowed by host. A per-merchant storefront, a per-client gallery.
+ *
+ * Not multi-brand: see the note at the top of this file. Same theme, same
+ * catalog, same editors; the host selects a slice.
+ *
+ * Astroid provides only the plumbing that cannot live in a site: the wildcard
+ * Worker route (which `hosts` cannot express) and the one middleware file Astro
+ * permits. **Everything that decides anything stays yours** — what a label maps
+ * to, whether the lookup is cached, and what an unknown host should do. Those
+ * live in the scaffolded `src/tenancy.ts`, which is yours to edit.
+ */
+export interface TenancyConfig {
+    /**
+     * The wildcard host, e.g. `"*.example.com"`. Emitted as a **zone route**
+     * (`{ pattern, zone_name }`), never `custom_domain: true` — a wildcard cannot
+     * be a custom domain, which is exactly why `hosts` cannot express this.
+     */
+    hostPattern: string;
+    /**
+     * The Cloudflare zone the pattern belongs to. Defaults to `hostPattern` minus
+     * its leading `*.`, which is right whenever the wildcard sits directly under
+     * the zone apex. Set it explicitly for a deeper pattern — `*.shop.example.com`
+     * is served by the `example.com` zone, not a `shop.example.com` one.
+     */
+    zone?: string;
+    /**
+     * Labels that are **not** tenants — `www`, `admin`, `studio`, `api`. These
+     * skip the tenant lookup entirely and render the ordinary site.
+     *
+     * Declared here rather than in the seam because the generated middleware needs
+     * it before it can decide whether to call the seam at all, and because
+     * forgetting `www` is the mistake that turns your marketing homepage into a
+     * failed tenant lookup.
+     */
+    reserved?: string[];
+    /**
+     * Internal path prefix a tenant request is rewritten to. Default `"/t"`, so
+     * `acme.example.com/prints` renders `/t/acme/prints`.
+     *
+     * The visitor's URL never changes — this is an internal rewrite, so links
+     * built from `Astro.url` stay public and correct.
+     */
+    rewritePrefix?: string;
+}
+export interface AstroidCron {
+    /** Standard 5-field cron, UTC — e.g. `"*/15 * * * *"`. */
+    expression: string;
+    /**
+     * The queue message this trigger sends. **Enqueued, never run inline**, so the
+     * work takes the same retry and DLQ path as every other message and a slow job
+     * can't hold the scheduled handler open.
+     *
+     * Typed `unknown` because the consumer owns the message vocabulary: whatever
+     * you put here arrives at your `handleQueueMessage`'s `onMessage`.
+     */
+    message: unknown;
+}
 export interface SeoConfig {
     /**
      * `<title>` template, `%s` standing in for the page title. Applied only when
@@ -293,6 +363,12 @@ export interface AstroidConfig {
     key: string;
     /** Hostname(s) this site serves (prod + preview), for custom-domain routes. */
     hosts?: string[];
+    /**
+     * Serve a wildcard host from this Worker, mapping each subdomain to an
+     * internal path prefix. See {@link TenancyConfig} — and note it is an
+     * *audiences* axis, not multi-brand.
+     */
+    tenancy?: TenancyConfig;
     /** Starting shape; sets section/module/nav defaults the site can override. */
     archetype: Archetype;
     /** The single brand's theme (display name + color tokens + font). */
@@ -332,6 +408,16 @@ export interface AstroidConfig {
     commerce?: CommerceConfig;
     /** Queue consumer + cron safety net. Defaults on when `commerce` is set. */
     queues?: QueuesConfig;
+    /**
+     * Extra scheduled triggers beyond Astroid's two. Each is emitted into **both**
+     * `triggers.crons` and the generated `scheduled` dispatch, so the pair cannot
+     * drift. See {@link AstroidCron}.
+     *
+     * Requires the queue consumer, since a cron's work is enqueued rather than run
+     * inline; `defineAstroid` refuses the combination rather than generating a
+     * `send` against a binding that doesn't exist.
+     */
+    crons?: AstroidCron[];
     /** Title template, structured-data type, and social-card attribution. */
     seo?: SeoConfig;
     /** Additions to the rate-limit rules + CSP origins Astroid derives. */
@@ -350,22 +436,4 @@ export interface AstroidConfig {
     pwa?: PwaConfig;
     deploy?: DeployConfig;
 }
-/**
- * Define an Astroid project. An identity function in the shape of Astro's
- * `defineConfig`: it returns the config verbatim with full type-checking +
- * inference, and validates the invariants that would otherwise fail deep inside
- * generation (a non-empty project `key`, since it names the generated bindings;
- * a brand `theme.name` + `colors.brand`, since they seed the site and theme).
- *
- * ```ts
- * export default defineAstroid({
- *   key: "coracle",
- *   archetype: "storefront",
- *   theme: { name: "Coracle Coffee", colors: { brand: "#1f6f78" } },
- *   sections: ["hero", "banner", "productGrid", "locationHours", "contact"],
- *   commerce: { provider: "square" },
- *   deploy: { platform: "cloudflare" },
- * });
- * ```
- */
 export declare function defineAstroid(config: AstroidConfig): AstroidConfig;

package/dist/config.js

@@ -10,10 +10,16 @@
 //
 // ONE brand per project. Every site Astroid targets (coracle.coffee,
 // ghostfire.coffee, themidwestartist.com, louise-web) serves a single brand from a
-// single deploy — none does host/tenant dispatch. The axis that genuinely
-// multiplexes is *editors* (Louise's org plugin, #100) and *audiences* (a gated
-// portal alongside the public site), not brands — so both live here as options on
-// the one brand, not as a `brands[]` array.
+// single deploy. The axis that genuinely multiplexes is *editors* (Louise's org
+// plugin, #100) and *audiences* — a gated portal alongside the public site, or a
+// per-merchant storefront on its own subdomain (`tenancy`) — not brands. So all
+// of them live here as options on the one brand, not as a `brands[]` array.
+//
+// `tenancy` is worth being precise about, because "serves many hosts" sounds like
+// the thing this paragraph rules out and isn't. It serves scoped VIEWS OF ONE
+// BRAND'S DATA — the same theme, the same catalog, the same editors — narrowed by
+// host. It is the portal's axis, one step further out. A second brand still means
+// a second project.
 //
 // The vocabulary below is not invented: `Archetype`, `SectionKind`, and
 // `ModuleKind` are extracted from the real sites Astroid targets — a storefront
@@ -22,6 +28,12 @@
 import { assertAuthIsolation } from "./auth/index.js";
 import { assertCommerceRoles } from "./commerce/roles.js";
 import { AstroidConfigError } from "./errors.js";
+// The cron facts come from the module that derives them, so the duplicate check
+// can't drift from what `astroidCrons` actually emits. A real import rather than
+// a type-only one, which is safe here: `queues/messages.ts` imports this file
+// type-only, so the cycle erases at build and nothing circular exists at runtime.
+// It is also dependency-free, so `create-astroid`'s graph is unchanged.
+import { ASTROID_HEALTH_CRON, astroidCron, astroidUsesQueues } from "./queues/messages.js";
 /**
  * Each archetype's default home-page sections.
  *
@@ -61,6 +73,75 @@ export const ASTROID_ARCHETYPE_SECTIONS = {
  * });
  * ```
  */
+/**
+ * Both ways a project-declared cron silently does nothing.
+ *
+ * A duplicate expression is the sharper one: the generated dispatch matches on
+ * `controller.cron` in order, so a custom trigger colliding with a derived one
+ * (or another custom one) never reaches its own branch. Cloudflare fires it, the
+ * first branch handles it, and the config reads as though both are live —
+ * exactly the unreachable-trigger failure `config.crons` exists to prevent.
+ */
+function assertCrons(config) {
+    const crons = config.crons ?? [];
+    if (crons.length === 0)
+        return;
+    if (!astroidUsesQueues(config)) {
+        throw new AstroidConfigError("`crons` needs the queue consumer: a cron's work is enqueued, not run inline, and " +
+            "without it the generated handler would `send` to a binding this project never creates. " +
+            "Set `queues: { enabled: true }`, or drop the crons.");
+    }
+    const seen = new Map([[ASTROID_HEALTH_CRON, "the daily health scan"]]);
+    const catalog = astroidCron(config);
+    if (catalog)
+        seen.set(catalog, "the catalog re-sync (`queues.cron`)");
+    for (const cron of crons) {
+        const expression = cron.expression?.trim();
+        if (!expression) {
+            throw new AstroidConfigError("Every entry in `crons` needs a non-empty `expression`");
+        }
+        const owner = seen.get(expression);
+        if (owner) {
+            throw new AstroidConfigError(`Duplicate cron \`${expression}\` — it already belongs to ${owner}. One \`scheduled\` ` +
+                "handler dispatches on the expression, so the first branch wins and this one would " +
+                "never run. Use a different minute.");
+        }
+        seen.set(expression, "another entry in `crons`");
+    }
+}
+/**
+ * The tenancy misconfigurations that fail late, or not at all.
+ *
+ * All three are cheap to state and expensive to discover: two surface as a
+ * wrangler deploy error naming a zone or a pattern rather than the config that
+ * produced it, and the third never surfaces at all — it just serves the wrong
+ * page.
+ */
+function assertTenancy(config) {
+    const tenancy = config.tenancy;
+    if (!tenancy)
+        return;
+    const pattern = tenancy.hostPattern?.trim();
+    if (!pattern) {
+        throw new AstroidConfigError('`tenancy.hostPattern` is required, e.g. `"*.example.com"`');
+    }
+    if (!pattern.startsWith("*.")) {
+        throw new AstroidConfigError(`\`tenancy.hostPattern\` must be a wildcard starting with "*." — got "${pattern}". ` +
+            "A fixed host is a custom domain: put it in `hosts` instead.");
+    }
+    const apex = pattern.slice(2);
+    if (!apex.includes(".")) {
+        throw new AstroidConfigError(`\`tenancy.hostPattern\` "${pattern}" has no domain after the wildcard`);
+    }
+    // A wildcard does NOT match its own apex, so the apex needs its own route.
+    // Without one it 404s — and the symptom is "the marketing site is down"
+    // immediately after enabling a feature that reads like it only adds hosts.
+    if (!(config.hosts ?? []).some((host) => host.toLowerCase() === apex.toLowerCase())) {
+        throw new AstroidConfigError(`\`tenancy.hostPattern\` is "${pattern}", but "${apex}" is not in \`hosts\`. ` +
+            "A wildcard route does not match its own apex, so the apex would 404. " +
+            `Add "${apex}" to \`hosts\`.`);
+    }
+}
 export function defineAstroid(config) {
     if (!config.key || config.key.trim().length === 0) {
         throw new AstroidConfigError("Astroid config requires a non-empty `key` (it names the generated worker/D1/R2 bindings)");
@@ -90,6 +171,8 @@ export function defineAstroid(config) {
     // control that silently does nothing is strictly worse than one that isn't
     // offered: the first gives false confidence, the second sends you looking for
     // an answer. Fail loudly, at config load, naming the workaround.
+    assertCrons(config);
+    assertTenancy(config);
     if (config.portal?.gated) {
         throw new AstroidConfigError("`portal.gated` is not implemented — it is accepted but wires no guard, so the site " +
             "would be fully public while appearing gated. Remove it, and gate the whole site by " +

package/dist/index.d.ts

@@ -16,5 +16,6 @@ export * from "./schema/index.js";
 export * from "./security/index.js";
 export * from "./seo/index.js";
 export * from "./status.js";
+export * from "./tenancy/index.js";
 export * from "./worker/index.js";
 export * from "./workflow/index.js";

package/dist/index.js

@@ -21,5 +21,6 @@ export * from "./schema/index.js";
 export * from "./security/index.js";
 export * from "./seo/index.js";
 export * from "./status.js";
+export * from "./tenancy/index.js";
 export * from "./worker/index.js";
 export * from "./workflow/index.js";

package/dist/project/generate.js

@@ -21,6 +21,7 @@ import { COMMERCE_PROVIDER_SECRETS, COMMERCE_PROVIDER_SETUP, commerceSecretNames
 import { ASTROID_QUEUE_BINDING, astroidCron, astroidCrons, astroidQueueNames, astroidUsesQueues, } from "../queues/messages.js";
 import { ASTROID_EDIT_SESSION_CLASS, ASTROID_REALTIME_BINDING, ASTROID_REALTIME_MIGRATION_TAG, usesRealtime, } from "../realtime/scaffold.js";
 import { ASTROID_SECRET_PLACEHOLDER } from "../secrets.js";
+import { tenancyZone } from "../tenancy/index.js";
 import { generateAstroidSchema } from "../schema/generate.js";
 import { generateAstroidMiddleware, generateAstroidWorker } from "../worker/generate.js";
 /**
@@ -105,12 +106,23 @@ export function generateAstroidWrangler(config) {
     p('  "compatibility_flags": ["nodejs_compat"],');
     p("  // @astrojs/cloudflare builds this entry and wires the static assets under dist/.");
     p('  "main": "src/worker.ts",');
-    if (primaryHost) {
+    const tenancy = config.tenancy;
+    if (primaryHost || tenancy) {
         p("  // Custom domains this Worker serves (from your defineAstroid `hosts`).");
         p('  "routes": [');
         for (const host of hosts) {
             p(`    { "pattern": ${JSON.stringify(host)}, "custom_domain": true },`);
         }
+        if (tenancy) {
+            // A wildcard is a ZONE route, never a custom domain — Cloudflare rejects
+            // `custom_domain: true` on a pattern containing `*`, which is precisely
+            // why `hosts` cannot express this.
+            p("    // Wildcard tenant hosts (`tenancy.hostPattern`). A zone route, NOT a");
+            p("    // custom_domain — Cloudflare refuses a wildcard custom domain. The");
+            p("    // apex is routed separately above: `*.example.com` does NOT match");
+            p("    // `example.com`, so without a `hosts` entry the apex would 404.");
+            p(`    { "pattern": ${JSON.stringify(`${tenancy.hostPattern}/*`)}, "zone_name": ${JSON.stringify(tenancyZone(tenancy))} },`);
+        }
         p("  ],");
     }
     else {

package/dist/project/scaffold.js

@@ -32,8 +32,9 @@ import { generateMapEmbedComponent, generateMapTileRoute } from "../map/scaffold
 import { generateAstroidGalleryPage } from "../portfolio/scaffold.js";
 import { astroidPortal } from "../portal/config.js";
 import { generateAstroidPortalAuth, generateAstroidPortalAuthRoute } from "../portal/scaffold.js";
+import { generateAstroidTenancy } from "../tenancy/index.js";
 import { generateAstroidEditSession } from "../realtime/scaffold.js";
-import { generatePwaHeaders, generateServiceWorker, generateWebManifest } from "../pwa/generate.js";
+import { generatePwaHeaders, generateServiceWorker, generateWebManifest, resolvePwa, } from "../pwa/generate.js";
 import { astroidUsesQueues } from "../queues/messages.js";
 import { generateAstroidQueueSeam, generateAstroidWebhookRoutes } from "../queues/scaffold.js";
 /**
@@ -110,19 +111,29 @@ export function generateAstroidScaffoldFiles(config) {
     // bundled, and `_headers` is shared with whatever else writes to it.
     const sw = generateServiceWorker(config);
     if (sw) {
-        files.push({ path: "public/sw.js", contents: sw });
+        // `emitDir` puts them where the BROWSER will ask for them. A PWA on its own
+        // subdomain that rewrites to a path prefix (studio.example.com/ → /studio/)
+        // fetches /sw.js at its own origin root, which rewrites to /studio/sw.js —
+        // so a worker emitted at the public root is a 404 nothing explains.
+        const pwaDir = resolvePwa(config).emitDir;
+        const publicBase = pwaDir ? `public/${pwaDir}` : "public";
+        files.push({ path: `${publicBase}/sw.js`, contents: sw });
         const manifest = generateWebManifest(config);
-        if (manifest)
-            files.push({ path: "public/manifest.webmanifest", contents: manifest });
+        if (manifest) {
+            files.push({ path: `${publicBase}/manifest.webmanifest`, contents: manifest });
+        }
         const headers = generatePwaHeaders(config);
         if (headers) {
             files.push({
+                // `_headers` stays at the public root wherever the worker lives — it is
+                // one file for the whole site, and Cloudflare only reads it there.
                 path: "public/_headers",
                 contents: headers,
                 apply: "append-once",
                 // The service-worker path is the one token this stanza always contains
-                // and nothing else in a `_headers` file would.
-                marker: "/sw.js",
+                // and nothing else in a `_headers` file would. Includes the emit dir, so
+                // moving the worker rewrites the stanza rather than appending a second.
+                marker: `${pwaDir ? `/${pwaDir}` : ""}/sw.js`,
             });
         }
     }
@@ -141,6 +152,12 @@ export function generateAstroidScaffoldFiles(config) {
     const editSession = generateAstroidEditSession(config);
     if (editSession)
         files.push({ path: "src/edit-session.ts", contents: editSession });
+    // --- tenancy: what a subdomain maps to ------------------------------------
+    // Astroid owns the wildcard route and the middleware wiring; this file owns
+    // every decision — the lookup, its caching, and what an unknown host means.
+    const tenancy = generateAstroidTenancy(config);
+    if (tenancy)
+        files.push({ path: "src/tenancy.ts", contents: tenancy });
     // --- portal: the second auth instance + its mounted catch-all -------------
     // A site edits the reset email and the role a new account gets, but not the
     // mount/cookie/table prefixes that keep the two instances isolated.

package/dist/pwa/generate.d.ts

@@ -20,12 +20,45 @@ export interface PwaConfig {
     themeColor?: string;
     /** Extra paths to precache alongside the scope root. */
     shell?: string[];
+    /**
+     * A prerendered page to serve when a navigation fails offline, e.g.
+     * `"/offline"`.
+     *
+     * Without it the fallback is the scope root — the *dynamic* app shell, which
+     * is exactly the wrong thing to precache when the app is auth-gated: that
+     * response carries `Cache-Control: no-store`, so either nothing is cached and
+     * the fallback is empty, or a signed-in shell is stored and later served to
+     * whoever opens the app next.
+     *
+     * Point it at a page with no session-specific markup. It is precached with the
+     * shell, so it must be prerendered — a dynamic route here fails at exactly the
+     * moment it is needed.
+     */
+    offlineFallback?: string;
+    /**
+     * Subdirectory under `public/` to emit `sw.js` and the manifest into, e.g.
+     * `"studio"`. Default: the public root.
+     *
+     * For a PWA served from its own subdomain that rewrites to a path prefix —
+     * `studio.example.com/` → `/studio/` — the browser fetches `/sw.js` at *its*
+     * origin root, which rewrites to `/studio/sw.js`. Emitting at the public root
+     * puts the file where nothing will ask for it.
+     *
+     * Set this to the same prefix the host rewrites to. With `scope` equal to the
+     * serving path, no `Service-Worker-Allowed` header is needed — a worker may
+     * always control its own directory and below.
+     */
+    emitDir?: string;
 }
 /** True when this project switched the PWA on. */
 export declare const usesPwa: (config: AstroidConfig) => boolean;
 /** Resolved PWA settings — config over derivation over default. */
-export declare function resolvePwa(config: AstroidConfig): Required<Omit<PwaConfig, "shell">> & {
+export declare function resolvePwa(config: AstroidConfig): Required<Omit<PwaConfig, "shell" | "offlineFallback" | "emitDir">> & {
     shell: string[];
+    /** `null` when the app falls back to the scope root (see the config note). */
+    offlineFallback: string | null;
+    /** Normalized to no leading/trailing slash; `""` for the public root. */
+    emitDir: string;
 };
 /**
  * `public/manifest.webmanifest`.

package/dist/pwa/generate.js

@@ -39,9 +39,24 @@ export function resolvePwa(config) {
         orientation: pwa.orientation ?? "any",
         backgroundColor: pwa.backgroundColor ?? "#ffffff",
         themeColor: pwa.themeColor ?? config.theme.colors.brand,
-        shell: [scope, "/manifest.webmanifest", ...(pwa.shell ?? [])],
+        offlineFallback: pwa.offlineFallback ?? null,
+        emitDir: (pwa.emitDir ?? "").replace(/^\/+|\/+$/g, ""),
+        // The offline page is precached with the shell — a fallback fetched on
+        // demand is a fallback that isn't there when the network is.
+        shell: [
+            scope,
+            `${assetBase(pwa.emitDir)}/manifest.webmanifest`,
+            ...(pwa.offlineFallback ? [pwa.offlineFallback] : []),
+            ...(pwa.shell ?? []),
+        ],
     };
 }
+/** URL prefix the emitted `sw.js` + manifest are served from — `""` at the
+ *  public root, `"/studio"` under an `emitDir`. */
+function assetBase(emitDir) {
+    const dir = (emitDir ?? "").replace(/^\/+|\/+$/g, "");
+    return dir ? `/${dir}` : "";
+}
 /**
  * `public/manifest.webmanifest`.
  *
@@ -108,6 +123,14 @@ export function generateServiceWorker(config) {
         "//                 present as 'my changes don't save'",
         `const CACHE = ${JSON.stringify(cacheName)};`,
         `const SCOPE = ${JSON.stringify(pwa.scope)};`,
+        ...(pwa.offlineFallback
+            ? [
+                "// A prerendered page with no session-specific markup. The scope root is",
+                "// the app SHELL, which on an auth-gated app is `Cache-Control: no-store`",
+                "// — so falling back to it serves either nothing or someone else's shell.",
+                `const OFFLINE = ${JSON.stringify(pwa.offlineFallback)};`,
+            ]
+            : []),
         `const SHELL = ${JSON.stringify([...new Set(pwa.shell)])};`,
         "",
         "self.addEventListener('install', (event) => {",
@@ -175,7 +198,9 @@ export function generateServiceWorker(config) {
         "            .catch(() => {});",
         "          return res;",
         "        })",
-        "        .catch(() => caches.match(req).then((r) => r || caches.match(SCOPE))),",
+        pwa.offlineFallback
+            ? "        .catch(() => caches.match(req).then((r) => r || caches.match(OFFLINE))),"
+            : "        .catch(() => caches.match(req).then((r) => r || caches.match(SCOPE))),",
         "    );",
         "    return;",
         "  }",
@@ -213,14 +238,18 @@ export function generateServiceWorker(config) {
 export function generatePwaHeaders(config) {
     if (!usesPwa(config))
         return null;
+    // Paths must match where the files are actually emitted — a stanza for
+    // `/sw.js` while the worker lives at `/studio/sw.js` sets headers on nothing,
+    // and the no-cache rule is what stops a bad worker sticking around.
+    const base = assetBase(config.pwa?.emitDir);
     return [
         "",
         "# The service worker must revalidate on every load, or a bad worker sticks",
         "# around until its cache entry expires — and it controls every page in scope.",
-        "/sw.js",
+        `${base}/sw.js`,
         "  Cache-Control: no-cache",
         "",
-        "/manifest.webmanifest",
+        `${base}/manifest.webmanifest`,
         "  Content-Type: application/manifest+json",
         "  Cache-Control: public, max-age=3600",
         "",