astroidjs 0.3.2 → 0.4.0

package/README.md

@@ -33,7 +33,7 @@ The whole shape of a project — its brand + theme + editable home, its commerce
 backend and optional modules — collapses into one typed config. **One brand per
 project:** every site Astroid targets serves a single brand from a single deploy,
 so the config describes one brand, not an array. What actually multiplexes is
-*editors* (Louise's org plugin) and *audiences* (a gated portal beside the public
+_editors_ (Louise's org plugin) and _audiences_ (a gated portal beside the public
 site) — both options on the one brand. The vocabulary is drawn from the real
 sites Astroid targets: a storefront (coracle.coffee), a wholesale front
 (ghostfire.coffee), an artist portfolio (themidwestartist.com), and a plain
@@ -131,16 +131,16 @@ wait on the work.
 Status codes are the only backpressure signal a provider gives you, so each one
 is picked for what it tells the sender to do:
 
-| Situation | Code | Why |
-|---|---|---|
-| Secret unprovisioned | 503 | Dormant is temporary — keep retrying so events delivered before you set the secret still land |
-| Bad / missing signature | 401 | Terminal. It won't verify on retry either, and retrying turns a misconfiguration into a flood |
-| Body isn't JSON | 400 | Terminal for the same reason |
-| Enqueue failed | 503 | The signature checked out, so the event is real — ask for redelivery |
-| Enqueued | 202 | Accepted, not done. That's the point of a queue |
+| Situation               | Code | Why                                                                                           |
+| ----------------------- | ---- | --------------------------------------------------------------------------------------------- |
+| Secret unprovisioned    | 503  | Dormant is temporary — keep retrying so events delivered before you set the secret still land |
+| Bad / missing signature | 401  | Terminal. It won't verify on retry either, and retrying turns a misconfiguration into a flood |
+| Body isn't JSON         | 400  | Terminal for the same reason                                                                  |
+| Enqueue failed          | 503  | The signature checked out, so the event is real — ask for redelivery                          |
+| Enqueued                | 202  | Accepted, not done. That's the point of a queue                                               |
 
 On the consumer side `astroidQueueHandler` owns the dispatch every site wrote: a
-periodic refresh re-syncs, a webhook re-syncs *only* if it touched the catalog,
+periodic refresh re-syncs, a webhook re-syncs _only_ if it touched the catalog,
 and everything else acks as a no-op. That last part matters — order and payment
 events arrive in volume and have nothing local to update, so treating them as
 actionable turns a busy sales day into a refresh storm.
@@ -195,7 +195,7 @@ settings is a site-wide kill switch that beats any page asking to be indexed —
 useful for staging.
 
 `<StructuredData>` emits a schema.org `@graph`: the business, the `WebSite`, and
-optionally the entity the page is *about* (a Product, a VisualArtwork). The
+optionally the entity the page is _about_ (a Product, a VisualArtwork). The
 business `@type` comes from the archetype (`storefront` → `Store`, `portfolio` →
 `Person`); set `seo.businessType` to a narrower subtype whenever you know one.
 The payload is escaped with `escapeJsonLd`, not `JSON.stringify` — `stringify`
@@ -219,7 +219,7 @@ email-bombing target, so the tightest budget in the set), the portal's
 credential surfaces when `portal.enabled`, checkout when `commerce` is set. The
 session-gated editor API stays out on purpose — a limiter that can lock the
 owner out of their own studio is worse than the abuse it stops. Add or override
-via `security.rateRules`, which is matched *before* the defaults, so you replace
+via `security.rateRules`, which is matched _before_ the defaults, so you replace
 one budget rather than the whole set.
 
 **The CSP is composed, and it's split for a reason.** `astroidSecurity(config)`
@@ -229,7 +229,7 @@ Astroid adds the one hash Astro can't produce itself: Solid's hydration
 bootstrap, injected by `@astrojs/solid-js` on every page with an island.
 Computing it from `generateHydrationScript()` means it tracks solid-js upgrades
 instead of going stale as a copy-pasted literal. Meanwhile the generated
-middleware rewrites *only* `style-src`, because Louise's data-driven `style=""`
+middleware rewrites _only_ `style-src`, because Louise's data-driven `style=""`
 carriers need `'unsafe-inline'` and a single hash in that directive would void
 it per spec — the two cannot share one directive.
 
@@ -240,8 +240,8 @@ import astroidConfig from "./astroid.config.ts";
 
 export default defineConfig({
   security: astroidSecurity(astroidConfig),
-  vite: { build: { ...ASTROID_VITE_BUILD } },  // assetsInlineLimit: 0 — an
-});                                            // inlined asset can't be hashed
+  vite: { build: { ...ASTROID_VITE_BUILD } }, // assetsInlineLimit: 0 — an
+}); // inlined asset can't be hashed
 ```
 
 Enabled modules contribute their own origins (a commerce provider's SDK hosts,
@@ -249,8 +249,8 @@ the captcha frame); `security.cspOrigins` adds anything Astroid can't see.
 
 ## Modules are dormant, not broken
 
-Astroid's optional modules are opt-in at the *config* level, never at the
-*account* level: switching commerce on must not require a Square account before
+Astroid's optional modules are opt-in at the _config_ level, never at the
+_account_ level: switching commerce on must not require a Square account before
 `pnpm dev` will boot. So a module whose secrets aren't provisioned is **dormant**
 — it renders, it serves, it says out loud that it's simulated, and it never calls
 upstream with a dummy credential. A fresh clone runs with zero external accounts.

package/bin/astroid.mjs

@@ -215,7 +215,7 @@ async function cmdDoctor(cwd, flags) {
     else
       err(
         "wrangler.jsonc has no `send_email` binding, but production sign-in emails the " +
-          "magic link (it is only console-logged in dev). Add: \"send_email\": [{ \"name\": \"EMAIL\" }]",
+          'magic link (it is only console-logged in dev). Add: "send_email": [{ "name": "EMAIL" }]',
       );
 
     if (hasBinding("DB")) ok("wrangler: D1 `DB` binding present");
@@ -328,7 +328,9 @@ async function cmdAstro(cwd, subcommand, flags, rest) {
   await cmdGenerate(cwd, flags, { quiet: true });
   const astroBin = resolveBin(cwd, "astro", "astro");
   if (!astroBin) {
-    fail("Could not find `astro` in this project. Run inside an Astroid project (with astro installed).");
+    fail(
+      "Could not find `astro` in this project. Run inside an Astroid project (with astro installed).",
+    );
   }
   const child = spawn(process.execPath, [astroBin, subcommand, ...rest], { stdio: "inherit", cwd });
   child.on("exit", (code) => process.exit(code ?? 0));
@@ -409,7 +411,9 @@ function provisionPlan(facts) {
 /** Look up a just-created resource's id by name via a `… list` JSON command. */
 function lookupId(wranglerBin, cwd, args, pick) {
   try {
-    const rows = JSON.parse(execFileSync(process.execPath, [wranglerBin, ...args], { cwd, encoding: "utf8" }));
+    const rows = JSON.parse(
+      execFileSync(process.execPath, [wranglerBin, ...args], { cwd, encoding: "utf8" }),
+    );
     return pick(Array.isArray(rows) ? rows : []) ?? null;
   } catch {
     return null;
@@ -453,7 +457,9 @@ async function cmdDeploy(cwd, flags, rest) {
   out("  Secrets:  wrangler secret put SESSION_SECRET   (prompted)");
   out("  Deploy:   wrangler deploy\n");
   if (!facts.hasAccount) {
-    out("  ! No account_id set — uncomment it in wrangler.jsonc or export CLOUDFLARE_ACCOUNT_ID.\n");
+    out(
+      "  ! No account_id set — uncomment it in wrangler.jsonc or export CLOUDFLARE_ACCOUNT_ID.\n",
+    );
   }
 
   if (dryRun) {
@@ -464,10 +470,14 @@ async function cmdDeploy(cwd, flags, rest) {
   // Gate the irreversible work behind a clear yes.
   if (!assumeYes) {
     if (!process.stdin.isTTY) {
-      fail("Refusing to provision + deploy non-interactively. Re-run with --yes (or --dry-run to preview).");
+      fail(
+        "Refusing to provision + deploy non-interactively. Re-run with --yes (or --dry-run to preview).",
+      );
     }
     const rl = createInterface({ input: process.stdin, output: process.stdout });
-    const answer = (await rl.question("Provision the above, then migrate + deploy? [y/N] ")).trim().toLowerCase();
+    const answer = (await rl.question("Provision the above, then migrate + deploy? [y/N] "))
+      .trim()
+      .toLowerCase();
     rl.close();
     if (answer !== "y" && answer !== "yes") {
       out("Aborted.");
@@ -477,7 +487,8 @@ async function cmdDeploy(cwd, flags, rest) {
 
   const wranglerBin = resolveBin(cwd, "wrangler", "wrangler");
   if (!wranglerBin) fail("Could not find `wrangler` in this project (add it as a devDependency).");
-  const runInherit = (args) => spawnSync(process.execPath, [wranglerBin, ...args], { cwd, stdio: "inherit" });
+  const runInherit = (args) =>
+    spawnSync(process.execPath, [wranglerBin, ...args], { cwd, stdio: "inherit" });
 
   // 1) Provision, patching discovered ids back into wrangler.jsonc.
   for (const s of plan) {
@@ -490,17 +501,28 @@ async function cmdDeploy(cwd, flags, rest) {
     }
 
     if (s.kind === "d1") {
-      const id = lookupId(wranglerBin, cwd, ["d1", "list", "--json"], (rows) => rows.find((r) => r.name === s.name)?.uuid);
+      const id = lookupId(
+        wranglerBin,
+        cwd,
+        ["d1", "list", "--json"],
+        (rows) => rows.find((r) => r.name === s.name)?.uuid,
+      );
       if (id) {
-        wrangler = wrangler.replace(/"database_id":\s*"<[^"]*>"/, `"database_id": ${JSON.stringify(id)}`);
+        wrangler = wrangler.replace(
+          /"database_id":\s*"<[^"]*>"/,
+          `"database_id": ${JSON.stringify(id)}`,
+        );
         writeFileSync(wranglerPath, wrangler);
         out(`  ↳ database_id = ${id}`);
       } else {
         out("  ↳ couldn't auto-detect the id — fill database_id in wrangler.jsonc by hand.");
       }
     } else if (s.kind === "kv") {
-      const id = lookupId(wranglerBin, cwd, ["kv", "namespace", "list"], (rows) =>
-        rows.find((r) => typeof r.title === "string" && r.title.endsWith(s.name))?.id,
+      const id = lookupId(
+        wranglerBin,
+        cwd,
+        ["kv", "namespace", "list"],
+        (rows) => rows.find((r) => typeof r.title === "string" && r.title.endsWith(s.name))?.id,
       );
       if (id) {
         wrangler = patchKvId(wrangler, s.name, id);
@@ -514,7 +536,8 @@ async function cmdDeploy(cwd, flags, rest) {
 
   // 2) Migrations.
   out(`\n▸ wrangler d1 migrations apply DB ${remoteArgs.join(" ")}`.trimEnd());
-  if (runInherit(["d1", "migrations", "apply", "DB", ...remoteArgs]).status !== 0) fail("Migrations failed.");
+  if (runInherit(["d1", "migrations", "apply", "DB", ...remoteArgs]).status !== 0)
+    fail("Migrations failed.");
 
   // 3) Secrets (interactive; wrangler prompts for the value).
   out("\n▸ wrangler secret put SESSION_SECRET");

package/dist/auth/index.js

@@ -50,10 +50,10 @@ export function assertAuthIsolation(config) {
         return;
     if (!portal.cookiePrefix || portal.cookiePrefix === ASTROID_EDITOR_COOKIE_PREFIX) {
         throw new AstroidConfigError(`portal.cookiePrefix must be set and distinct from the editor's (${JSON.stringify(ASTROID_EDITOR_COOKIE_PREFIX)}). Two instances sharing a cookie prefix silently sign you out of one when ` +
-            "you sign into the other. Pick a project-specific prefix (e.g. \"acme_shop\").");
+            'you sign into the other. Pick a project-specific prefix (e.g. "acme_shop").');
     }
     if (portal.tablePrefix === ASTROID_EDITOR_TABLE_PREFIX) {
         throw new AstroidConfigError(`portal.tablePrefix must differ from the editor's (${JSON.stringify(ASTROID_EDITOR_TABLE_PREFIX)}) — a shared table prefix merges the two instances into one user table. ` +
-            'Leave it unset (the unprefixed `user`/`session` tables) or use a distinct prefix.');
+            "Leave it unset (the unprefixed `user`/`session` tables) or use a distinct prefix.");
     }
 }

package/dist/commerce/checkout-scaffold.d.ts

@@ -23,13 +23,22 @@ export declare function generateAstroidCheckoutRoute(config: AstroidConfig): str
  */
 export declare function generateAstroidSquareCard(config: AstroidConfig): string | null;
 /**
- * The wrangler `vars` the card input needs, or `[]`.
+ * The wrangler `vars` Square needs, or `[]`.
  *
  * PUBLIC values, so they are vars rather than entries in the secret roster: the
  * application id is shipped to the browser by design, and the environment is a
  * choice, not a credential. Putting them in `credentials` would also fold them
  * into the dormancy gate, which is about whether the module can safely CALL
  * Square — a different question from whether the card field can render.
+ *
+ * The two vars are gated SEPARATELY, and that split is load-bearing.
+ * `SQUARE_ENVIRONMENT` selects the API HOST for every Square call, so it belongs
+ * to any project that talks to Square at all; `SQUARE_APP_ID` only mounts the
+ * browser card field. Gating both on card checkout — as this did until
+ * `invoicing: "square"` became expressible — left a site that runs Square for
+ * invoicing alone with no `SQUARE_ENVIRONMENT`, and `SquareConfig.environment`
+ * defaults to "sandbox". Every production invoice would have been created
+ * against the sandbox: no error, no warning, just money that never arrives.
  */
 export declare function astroidCheckoutVars(config: AstroidConfig): {
     name: string;

package/dist/commerce/checkout-scaffold.js

@@ -20,7 +20,7 @@
 // redirects to its own hosted checkout (no card token to charge) and Stripe has
 // no catalog API, so it fills the `invoicing` role rather than `storefront`.
 import { astroidCatalogMirror } from "./mirror.js";
-import { astroidCommerceRoles } from "./roles.js";
+import { astroidCommerceProviders, astroidCommerceRoles } from "./roles.js";
 /** Does this project take card payments in-page? Square storefront only. */
 export function usesCardCheckout(config) {
     return astroidCommerceRoles(config.commerce).storefront === "square";
@@ -65,7 +65,7 @@ export function generateAstroidCheckoutRoute(config) {
         "  resolveCommerceStatus,",
         "  type SecretSource,",
         "  verifyCheckout,",
-        "} from \"astroidjs\";",
+        '} from "astroidjs";',
         'import { createPayment } from "louise-toolkit/commerce/square";',
         'import { isSameOrigin } from "louise-toolkit/security";',
         'import astroidConfig from "../../../astroid.config.js";',
@@ -106,7 +106,7 @@ export function generateAstroidCheckoutRoute(config) {
         "  // an Origin/Referer matching the host; a non-browser caller (a stripped",
         "  // header) is refused. If you deliberately serve checkout from another origin,",
         "  // this is the line to relax — it's yours.",
-        "  if (!isSameOrigin(request)) return json({ error: \"Forbidden\" }, 403);",
+        '  if (!isSameOrigin(request)) return json({ error: "Forbidden" }, 403);',
         "",
         "  const body = (await request.json().catch(() => null)) as {",
         "    lines?: unknown;",
@@ -115,15 +115,15 @@ export function generateAstroidCheckoutRoute(config) {
         "    verificationToken?: unknown;",
         "    email?: unknown;",
         "  } | null;",
-        "  if (!body) return json({ error: \"Invalid JSON\" }, 400);",
+        '  if (!body) return json({ error: "Invalid JSON" }, 400);',
         "",
         "  // The cart id is the identity half of the idempotency key. It must be high",
         "  // entropy and client-generated ONCE per cart (a v4 uuid in localStorage):",
         "  // regenerate it per request and a double-click charges twice; make it",
         "  // guessable and someone else's identical cart can dedupe into your charge.",
-        "  const cartId = typeof body.cartId === \"string\" ? body.cartId : \"\";",
+        '  const cartId = typeof body.cartId === "string" ? body.cartId : "";',
         "  if (!/^[0-9a-f-]{36}$/i.test(cartId)) {",
-        "    return json({ error: \"A uuid `cartId` is required\" }, 400);",
+        '    return json({ error: "A uuid `cartId` is required" }, 400);',
         "  }",
         "",
         "  // 1 + 2: re-price and refuse on mismatch.",
@@ -153,12 +153,12 @@ export function generateAstroidCheckoutRoute(config) {
         "    });",
         "  }",
         "",
-        "  const sourceId = typeof body.sourceId === \"string\" ? body.sourceId : \"\";",
+        '  const sourceId = typeof body.sourceId === "string" ? body.sourceId : "";',
         '  if (!sourceId) return json({ error: "A card token (`sourceId`) is required" }, 400);',
         "",
         "  // Both are guaranteed real by the dormancy gate above; the narrowing here",
         "  // is for the type system, which can't know that. `environment` is a UNION",
-        "  // (\"sandbox\" | \"production\"), not a free string — an unrecognised value",
+        '  // ("sandbox" | "production"), not a free string — an unrecognised value',
         "  // would otherwise silently select the sandbox host in production.",
         '  const environment = env.SQUARE_ENVIRONMENT === "production" ? "production" : "sandbox";',
         "  const payment = await createPayment(",
@@ -172,7 +172,7 @@ export function generateAstroidCheckoutRoute(config) {
         '      amountMoney: { amount: check.subtotalCents, currency: "USD" },',
         '      locationId: env.SQUARE_LOCATION_ID ?? "",',
         "      idempotencyKey,",
-        "      ...(typeof body.verificationToken === \"string\"",
+        '      ...(typeof body.verificationToken === "string"',
         "        ? { verificationToken: body.verificationToken }",
         "        : {}),",
         '      ...(typeof body.email === "string" ? { buyerEmailAddress: body.email } : {}),',
@@ -270,37 +270,56 @@ export function generateAstroidSquareCard(config) {
         "",
     ].join("\n");
 }
+/** Does this project talk to Square in ANY role — storefront, invoicing, or
+ *  otherwise? Distinct from {@link usesCardCheckout}, which asks the narrower
+ *  question of whether the in-page card field renders. */
+function usesSquare(config) {
+    return astroidCommerceProviders(config.commerce).includes("square");
+}
 /**
- * The wrangler `vars` the card input needs, or `[]`.
+ * The wrangler `vars` Square needs, or `[]`.
  *
  * PUBLIC values, so they are vars rather than entries in the secret roster: the
  * application id is shipped to the browser by design, and the environment is a
  * choice, not a credential. Putting them in `credentials` would also fold them
  * into the dormancy gate, which is about whether the module can safely CALL
  * Square — a different question from whether the card field can render.
+ *
+ * The two vars are gated SEPARATELY, and that split is load-bearing.
+ * `SQUARE_ENVIRONMENT` selects the API HOST for every Square call, so it belongs
+ * to any project that talks to Square at all; `SQUARE_APP_ID` only mounts the
+ * browser card field. Gating both on card checkout — as this did until
+ * `invoicing: "square"` became expressible — left a site that runs Square for
+ * invoicing alone with no `SQUARE_ENVIRONMENT`, and `SquareConfig.environment`
+ * defaults to "sandbox". Every production invoice would have been created
+ * against the sandbox: no error, no warning, just money that never arrives.
  */
 export function astroidCheckoutVars(config) {
-    if (!usesCardCheckout(config))
-        return [];
-    return [
+    const vars = [];
+    // Browser-only, so card checkout is genuinely the right gate here.
+    if (usesCardCheckout(config)) {
         // Public app id from the Square dashboard (Developer → Credentials).
-        { name: "SQUARE_APP_ID", value: "" },
-        // "sandbox" until you have tested a real card end to end.
-        { name: "SQUARE_ENVIRONMENT", value: "sandbox" },
-    ];
+        vars.push({ name: "SQUARE_APP_ID", value: "" });
+    }
+    if (usesSquare(config)) {
+        // "sandbox" until you have tested a real payment end to end.
+        vars.push({ name: "SQUARE_ENVIRONMENT", value: "sandbox" });
+    }
+    return vars;
 }
 /**
  * The `CloudflareEnv` members the card input adds, as a block `create-astroid`
  * substitutes into `src/env.d.ts`. Empty without card checkout.
  */
 export function generateAstroidCheckoutEnv(config) {
-    if (!usesCardCheckout(config))
-        return "";
-    return [
-        "  /** Square's PUBLIC application id — shipped to the browser to mount the",
-        "   *  Web Payments card field. Not a secret; see wrangler.jsonc `vars`. */",
-        "  SQUARE_APP_ID: string;",
-        '  /** Square API environment: "sandbox" or "production". */',
-        "  SQUARE_ENVIRONMENT: string;",
-    ].join("\n");
+    // Mirrors the gating in `astroidCheckoutVars` — the app id is card-checkout
+    // only, the environment belongs to any project that calls Square at all.
+    const lines = [];
+    if (usesCardCheckout(config)) {
+        lines.push("  /** Square's PUBLIC application id — shipped to the browser to mount the", "   *  Web Payments card field. Not a secret; see wrangler.jsonc `vars`. */", "  SQUARE_APP_ID: string;");
+    }
+    if (usesSquare(config)) {
+        lines.push('  /** Square API environment: "sandbox" or "production". Selects the API', "   *  host for EVERY Square call, so it is required for invoicing too. */", "  SQUARE_ENVIRONMENT: string;");
+    }
+    return lines.join("\n");
 }

package/dist/commerce/index.d.ts

@@ -2,7 +2,7 @@ export { catalogNormalizer, type FourthwallProductLike, fourthwallToCatalogItem,
 export { type CheckoutVerification, checkoutIdempotencyKey, type ClientLine, type PriceLookup, verifyCheckout, type VerifiedLine, } 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, resolveCommerceStatus, } from "./secrets.js";
+export { COMMERCE_PROVIDER_SECRETS, type CommerceStatus, commerceSecretNames, type ProviderStatus, providerConfigured, resolveCommerceStatus, roleConfigured, } from "./secrets.js";
 export { assertCommerceRoles, astroidCommerceProviders, astroidCommerceRoles, type CommerceRole, hasStorefront, PROVIDER_ROLES, type ResolvedCommerceRoles, } from "./roles.js";
 export { astroidCatalogSync, astroidCatalogUpsert, type CatalogItem, type CatalogSyncOptions, type CatalogSyncResult, defaultSlug, type SyncDatabase, } from "./sync.js";
 export { astroidCheckoutVars, generateAstroidCheckoutEnv, generateAstroidCheckoutRoute, generateAstroidSquareCard, usesCardCheckout, } from "./checkout-scaffold.js";

package/dist/commerce/index.js

@@ -3,7 +3,7 @@ export { catalogNormalizer, fourthwallToCatalogItem, squareToCatalogItem, } from
 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";
-export { COMMERCE_PROVIDER_SECRETS, commerceSecretNames, resolveCommerceStatus, } from "./secrets.js";
+export { COMMERCE_PROVIDER_SECRETS, commerceSecretNames, providerConfigured, resolveCommerceStatus, roleConfigured, } from "./secrets.js";
 export { assertCommerceRoles, astroidCommerceProviders, astroidCommerceRoles, hasStorefront, PROVIDER_ROLES, } from "./roles.js";
 export { astroidCatalogSync, astroidCatalogUpsert, defaultSlug, } from "./sync.js";
 export { astroidCheckoutVars, generateAstroidCheckoutEnv, generateAstroidCheckoutRoute, generateAstroidSquareCard, usesCardCheckout, } from "./checkout-scaffold.js";

package/dist/commerce/roles.d.ts

@@ -1,20 +1,28 @@
 import type { CommerceConfig, CommerceProvider } from "../config.js";
 /** What a provider is being used FOR. */
-export type CommerceRole = "storefront" | "invoicing";
+export type CommerceRole = "storefront" | "invoicing" | "pos";
 /**
  * Which roles each provider can serve, derived from the surface its
  * `louise-toolkit/commerce/*` client actually exposes — not from what the
  * vendor's full API could theoretically do.
  *
- *   square      catalog + orders + payments, and `createInvoice`/`publishInvoice`
+ *   square      catalog + orders + payments, `createInvoice`/`publishInvoice`,
+ *               AND locations + per-location price overrides + inventory counts
  *   stripe      invoices + payment intents; NO catalog
- *   fourthwall  catalog + cart; NO invoicing
+ *   fourthwall  catalog + cart; NO invoicing, and NO locations or inventory —
+ *               its Platform API is create-only for products, so it cannot
+ *               model stock held at a place
+ *
+ * Square alone can serve `pos`, and that is a fact about the clients rather than
+ * a preference: `pos` needs `listLocations`, `location_overrides` and
+ * `batchChangeInventory`, none of which the other two clients expose.
  */
 export declare const PROVIDER_ROLES: Record<CommerceProvider, readonly CommerceRole[]>;
-/** The providers filling each role. Either may be absent. */
+/** The providers filling each role. Any may be absent. */
 export interface ResolvedCommerceRoles {
     storefront?: CommerceProvider;
     invoicing?: CommerceProvider;
+    pos?: CommerceProvider;
 }
 /**
  * Resolve a `commerce` block into role assignments.
@@ -27,6 +35,20 @@ export interface ResolvedCommerceRoles {
 export declare function astroidCommerceRoles(commerce: CommerceConfig | undefined): ResolvedCommerceRoles;
 /** Every distinct provider this project talks to, in a stable order. */
 export declare function astroidCommerceProviders(commerce: CommerceConfig | undefined): CommerceProvider[];
+/**
+ * True when this project sells in person — the switch for locations,
+ * per-location pricing and inventory.
+ */
+export declare const hasPos: (commerce: CommerceConfig | undefined) => boolean;
+/**
+ * True when Square is used with more than one Location, i.e. the location id
+ * comes from the request rather than the environment.
+ *
+ * Deliberately independent of which ROLE Square fills: a project could run
+ * multi-location invoicing without a `pos` storefront, and the consequence —
+ * no ambient `SQUARE_LOCATION_ID` — is the same either way.
+ */
+export declare const hasMultiLocation: (commerce: CommerceConfig | undefined) => boolean;
 /** True when this project sells anything at all. */
 export declare const hasStorefront: (commerce: CommerceConfig | undefined) => boolean;
 /**

package/dist/commerce/roles.js

@@ -21,12 +21,19 @@ import { AstroidConfigError } from "../errors.js";
  * `louise-toolkit/commerce/*` client actually exposes — not from what the
  * vendor's full API could theoretically do.
  *
- *   square      catalog + orders + payments, and `createInvoice`/`publishInvoice`
+ *   square      catalog + orders + payments, `createInvoice`/`publishInvoice`,
+ *               AND locations + per-location price overrides + inventory counts
  *   stripe      invoices + payment intents; NO catalog
- *   fourthwall  catalog + cart; NO invoicing
+ *   fourthwall  catalog + cart; NO invoicing, and NO locations or inventory —
+ *               its Platform API is create-only for products, so it cannot
+ *               model stock held at a place
+ *
+ * Square alone can serve `pos`, and that is a fact about the clients rather than
+ * a preference: `pos` needs `listLocations`, `location_overrides` and
+ * `batchChangeInventory`, none of which the other two clients expose.
  */
 export const PROVIDER_ROLES = {
-    square: ["storefront", "invoicing"],
+    square: ["storefront", "invoicing", "pos"],
     stripe: ["invoicing"],
     fourthwall: ["storefront"],
 };
@@ -52,13 +59,29 @@ export function astroidCommerceRoles(commerce) {
         roles.storefront = commerce.storefront;
     if (commerce.invoicing)
         roles.invoicing = commerce.invoicing;
+    if (commerce.pos)
+        roles.pos = commerce.pos;
     return roles;
 }
 /** Every distinct provider this project talks to, in a stable order. */
 export function astroidCommerceProviders(commerce) {
-    const { storefront, invoicing } = astroidCommerceRoles(commerce);
-    return [...new Set([storefront, invoicing].filter((p) => !!p))];
+    const { storefront, invoicing, pos } = astroidCommerceRoles(commerce);
+    return [...new Set([storefront, invoicing, pos].filter((p) => !!p))];
 }
+/**
+ * True when this project sells in person — the switch for locations,
+ * per-location pricing and inventory.
+ */
+export const hasPos = (commerce) => Boolean(astroidCommerceRoles(commerce).pos);
+/**
+ * True when Square is used with more than one Location, i.e. the location id
+ * comes from the request rather than the environment.
+ *
+ * Deliberately independent of which ROLE Square fills: a project could run
+ * multi-location invoicing without a `pos` storefront, and the consequence —
+ * no ambient `SQUARE_LOCATION_ID` — is the same either way.
+ */
+export const hasMultiLocation = (commerce) => commerce?.square?.locations === "multi";
 /** True when this project sells anything at all. */
 export const hasStorefront = (commerce) => Boolean(astroidCommerceRoles(commerce).storefront);
 /**
@@ -81,7 +104,12 @@ export function assertCommerceRoles(commerce) {
         known(provider);
         if (!PROVIDER_ROLES[provider].includes(role)) {
             const able = Object.keys(PROVIDER_ROLES).filter((p) => PROVIDER_ROLES[p].includes(role));
-            throw new AstroidConfigError(`commerce: ${provider} can't serve the "${role}" role — its louise-toolkit client has no ${role === "storefront" ? "catalog" : "invoicing"} API. Providers that can: ${able.join(", ")}.`);
+            const missing = {
+                storefront: "catalog",
+                invoicing: "invoicing",
+                pos: "locations/inventory",
+            }[role];
+            throw new AstroidConfigError(`commerce: ${provider} can't serve the "${role}" role — its louise-toolkit client has no ${missing} API. Providers that can: ${able.join(", ")}.`);
         }
     };
     // The shorthand assigns itself to a role it can serve, so it only has to be a
@@ -90,4 +118,11 @@ export function assertCommerceRoles(commerce) {
         known(commerce.provider);
     check("storefront", commerce.storefront);
     check("invoicing", commerce.invoicing);
+    check("pos", commerce.pos);
+    // `square.locations` only means something if Square is actually in play.
+    // Silently ignoring it would let a typo'd config look like it had opted into
+    // multi-location when nothing reads the setting.
+    if (commerce.square && !astroidCommerceProviders(commerce).includes("square")) {
+        throw new AstroidConfigError('commerce.square is set but no role is assigned to Square. Assign it to "storefront", "invoicing" or "pos", or drop the square block.');
+    }
 }

package/dist/commerce/secrets.d.ts

@@ -1,5 +1,6 @@
 import type { CommerceConfig, CommerceProvider } from "../config.js";
 import { type ModuleSecrets, type SecretSource } from "../secrets.js";
+import { type CommerceRole } from "./roles.js";
 /**
  * Per-provider secret names, split by what they gate.
  *
@@ -25,6 +26,21 @@ export declare const COMMERCE_PROVIDER_SECRETS: Record<CommerceProvider, {
  * do, only that something is missing.
  */
 export declare const COMMERCE_PROVIDER_SETUP: Record<CommerceProvider, string>;
+/**
+ * The credentials a provider needs **for this project's configuration**.
+ *
+ * Only Square varies, and only on one name. `SQUARE_LOCATION_ID` is required
+ * for a single-location project because Square's orders and payments endpoints
+ * refuse a request without one. Under `square.locations: "multi"` the location
+ * is a property of the *request* — which merchant's storefront is this? — so an
+ * ambient id is not just unnecessary, it is dangerous: any code path that
+ * defaulted to it would ring one merchant's sale against another merchant's
+ * books, and the sale would look perfectly successful while doing it.
+ *
+ * So it is dropped from the gate entirely rather than left optional. A name that
+ * is present-but-ignored is the kind of thing someone later "fixes" by using it.
+ */
+export declare function commerceProviderCredentials(provider: CommerceProvider, commerce: CommerceConfig | undefined): readonly string[];
 /**
  * Every secret name this project's commerce configuration needs, deduplicated
  * and in a stable order.
@@ -38,7 +54,7 @@ export declare function commerceSecretNames(commerce: CommerceConfig | undefined
 export interface ProviderStatus {
     provider: CommerceProvider;
     /** Which role(s) this provider fills for the project. */
-    roles: ("storefront" | "invoicing")[];
+    roles: CommerceRole[];
     /** API credentials — false means no live call can be made. */
     credentials: ModuleSecrets<string>;
     /** Webhook signing secret — false means the receiver answers 503. */
@@ -72,3 +88,22 @@ export interface CommerceStatus {
  * reason the mirror exists as a separate layer from the provider client.
  */
 export declare function resolveCommerceStatus(commerce: CommerceConfig | undefined, env: Record<string, SecretSource>): Promise<CommerceStatus>;
+/**
+ * Is THIS provider live?
+ *
+ * `CommerceStatus.configured` is an all-or-nothing aggregate (`every`), which is
+ * the right answer for "is the whole module ready" and the wrong one for gating
+ * a single call site. A two-provider project — Fourthwall for the storefront,
+ * Square for invoicing — reads `configured: false` the moment either half is
+ * unprovisioned, so gating the working Fourthwall checkout on the aggregate
+ * would silently simulate it because SQUARE's secrets are still placeholders.
+ *
+ * Gate each surface on the provider it actually calls.
+ */
+export declare function providerConfigured(status: CommerceStatus, provider: CommerceProvider): boolean;
+/**
+ * Is the provider filling this ROLE live? The role-shaped question, for code
+ * that cares about the capability rather than the vendor — "can I take a
+ * checkout?" rather than "is Square up?".
+ */
+export declare function roleConfigured(status: CommerceStatus, role: CommerceRole): boolean;

package/dist/commerce/secrets.js

@@ -20,7 +20,7 @@
 // `queues/scaffold.ts`, because it is the same fact: a provider's secret set.
 // The scaffold imports it from here so the two can't drift.
 import { resolveModuleSecrets } from "../secrets.js";
-import { astroidCommerceProviders, astroidCommerceRoles } from "./roles.js";
+import { astroidCommerceProviders, astroidCommerceRoles, hasMultiLocation, } from "./roles.js";
 /**
  * Per-provider secret names, split by what they gate.
  *
@@ -38,6 +38,8 @@ export const COMMERCE_PROVIDER_SECRETS = {
     // payments endpoints refuse a request without one, so a token on its own
     // leaves checkout broken rather than dormant. Requiring both is what makes
     // "configured" mean "can actually take money".
+    //
+    // UNLESS the project is multi-location — see `commerceProviderCredentials`.
     square: {
         credentials: ["SQUARE_ACCESS_TOKEN", "SQUARE_LOCATION_ID"],
         webhook: "SQUARE_WEBHOOK_SECRET",
@@ -67,6 +69,27 @@ export const COMMERCE_PROVIDER_SETUP = {
     stripe: "dashboard.stripe.com → Developers → API keys (secret key). Webhook secret: Developers → Webhooks → your endpoint → Signing secret.",
     fourthwall: "Fourthwall dashboard → Settings → For developers → Storefront token. Webhook secret: the same page → Webhooks.",
 };
+/**
+ * The credentials a provider needs **for this project's configuration**.
+ *
+ * Only Square varies, and only on one name. `SQUARE_LOCATION_ID` is required
+ * for a single-location project because Square's orders and payments endpoints
+ * refuse a request without one. Under `square.locations: "multi"` the location
+ * is a property of the *request* — which merchant's storefront is this? — so an
+ * ambient id is not just unnecessary, it is dangerous: any code path that
+ * defaulted to it would ring one merchant's sale against another merchant's
+ * books, and the sale would look perfectly successful while doing it.
+ *
+ * So it is dropped from the gate entirely rather than left optional. A name that
+ * is present-but-ignored is the kind of thing someone later "fixes" by using it.
+ */
+export function commerceProviderCredentials(provider, commerce) {
+    const spec = COMMERCE_PROVIDER_SECRETS[provider];
+    if (provider === "square" && hasMultiLocation(commerce)) {
+        return spec.credentials.filter((name) => name !== "SQUARE_LOCATION_ID");
+    }
+    return spec.credentials;
+}
 /**
  * Every secret name this project's commerce configuration needs, deduplicated
  * and in a stable order.
@@ -77,17 +100,19 @@ export const COMMERCE_PROVIDER_SETUP = {
  */
 export function commerceSecretNames(commerce) {
     const names = astroidCommerceProviders(commerce).flatMap((provider) => [
-        ...COMMERCE_PROVIDER_SECRETS[provider].credentials,
+        ...commerceProviderCredentials(provider, commerce),
         COMMERCE_PROVIDER_SECRETS[provider].webhook,
     ]);
     return [...new Set(names)];
 }
 /** Read one provider's secrets off an env-shaped record. */
-async function resolveProvider(provider, roles, env) {
+async function resolveProvider(provider, roles, env, commerce) {
     const spec = COMMERCE_PROVIDER_SECRETS[provider];
     const pick = (names) => Object.fromEntries(names.map((n) => [n, env[n]]));
     const [credentials, webhook] = await Promise.all([
-        resolveModuleSecrets(pick(spec.credentials)),
+        // Config-aware: a multi-location project must not be held dormant waiting
+        // for a SQUARE_LOCATION_ID it will never legitimately have.
+        resolveModuleSecrets(pick(commerceProviderCredentials(provider, commerce))),
         resolveModuleSecrets(pick([spec.webhook])),
     ]);
     return {
@@ -119,7 +144,7 @@ export async function resolveCommerceStatus(commerce, env) {
     if (providers.length === 0) {
         return { configured: false, enabled: false, providers: [], missing: [] };
     }
-    const resolved = await Promise.all(providers.map((provider) => resolveProvider(provider, ["storefront", "invoicing"].filter((r) => roles[r] === provider), env)));
+    const resolved = await Promise.all(providers.map((provider) => resolveProvider(provider, ["storefront", "invoicing", "pos"].filter((r) => roles[r] === provider), env, commerce)));
     return {
         configured: resolved.every((p) => p.configured),
         enabled: true,
@@ -127,3 +152,26 @@ export async function resolveCommerceStatus(commerce, env) {
         missing: resolved.flatMap((p) => [...p.credentials.missing, ...p.webhook.missing]),
     };
 }
+/**
+ * Is THIS provider live?
+ *
+ * `CommerceStatus.configured` is an all-or-nothing aggregate (`every`), which is
+ * the right answer for "is the whole module ready" and the wrong one for gating
+ * a single call site. A two-provider project — Fourthwall for the storefront,
+ * Square for invoicing — reads `configured: false` the moment either half is
+ * unprovisioned, so gating the working Fourthwall checkout on the aggregate
+ * would silently simulate it because SQUARE's secrets are still placeholders.
+ *
+ * Gate each surface on the provider it actually calls.
+ */
+export function providerConfigured(status, provider) {
+    return status.providers.some((p) => p.provider === provider && p.configured);
+}
+/**
+ * Is the provider filling this ROLE live? The role-shaped question, for code
+ * that cares about the capability rather than the vendor — "can I take a
+ * checkout?" rather than "is Square up?".
+ */
+export function roleConfigured(status, role) {
+    return status.providers.some((p) => p.roles.includes(role) && p.configured);
+}

package/dist/config.d.ts

@@ -1,4 +1,4 @@
-import type { SectionCatalog } from "louise-toolkit/content";
+import type { BlockCatalog, SectionCatalog } from "louise-toolkit/content";
 import type { RateRule } from "louise-toolkit/security";
 import type { CatalogMirrorConfig } from "./commerce/mirror.js";
 import type { astroidSectionCatalog } from "./components/sections.js";
@@ -156,8 +156,40 @@ export interface CommerceConfig {
      * Fourthwall as the storefront, because neither can do the other's job.
      */
     invoicing?: CommerceProvider;
+    /**
+     * In-person selling: physical inventory held at real places, sold at a
+     * counter or a market stall rather than through the site's own cart.
+     *
+     * Separate from `storefront` because they are genuinely different jobs and a
+     * site commonly runs both. themidwestartist.com sells print-on-demand merch
+     * through Fourthwall (`storefront`) while originals and self-stocked prints
+     * live in Square (`pos`) across several shops and galleries — one catalog per
+     * rail, neither able to do the other's job.
+     *
+     * What `pos` turns on that `storefront` does not: locations, per-location
+     * pricing, and per-location inventory.
+     */
+    pos?: CommerceProvider;
     /** The catalog mirror's shape — its mode, table name, and owned columns. */
     catalog?: CatalogMirrorConfig;
+    /** Square-specific options. Only meaningful when Square fills some role. */
+    square?: SquareCommerceConfig;
+}
+export interface SquareCommerceConfig {
+    /**
+     * How many Square Locations this project sells at.
+     *
+     * `"single"` (the default) is the ordinary case: one location, its id supplied
+     * once as `SQUARE_LOCATION_ID`, and every order placed against it.
+     *
+     * `"multi"` is the multi-merchant model — each merchant is a Location, and the
+     * id comes from the *request* (which merchant's storefront is this?) rather
+     * than from the environment. Setting it stops Astroid requiring
+     * `SQUARE_LOCATION_ID`: a single ambient location id is not merely unnecessary
+     * there, it is a hazard, because anything defaulting to it would silently ring
+     * one merchant's sale against another merchant's books.
+     */
+    locations?: "single" | "multi";
 }
 export interface QueuesConfig {
     /**
@@ -278,6 +310,20 @@ export interface AstroidConfig {
      * write paths agree. Omit to use Astroid's built-in catalog.
      */
     sectionCatalog?: SectionCatalog;
+    /**
+     * The site's catalog of BLOCK types (ADR 0005) — the block-level analogue of
+     * {@link sectionCatalog}, and required for any section whose def declares a
+     * `blocks` policy.
+     *
+     * Without it the server has no field shape to check a block against, so
+     * `validateSections` rejects every block `_type` as unknown and a block-bearing
+     * write 422s — the on-canvas block toolbar appears to work and then nothing
+     * saves. It also gates block rich-text **sanitization**: block fields are only
+     * scrubbed when their def is resolvable here.
+     *
+     * Omit for a sections-only site (no section declares `blocks`).
+     */
+    blockCatalog?: BlockCatalog;
     /** Optional capabilities switched on for this site. */
     modules?: ModuleKind[];
     /** Gated account/portal area (order tracking, client galleries). */

package/dist/config.js

@@ -93,7 +93,7 @@ export function defineAstroid(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 " +
-            "listing the prefixes you mean in `portal.routes` (e.g. `[{ prefix: \"/\" }]` with your " +
+            'listing the prefixes you mean in `portal.routes` (e.g. `[{ prefix: "/" }]` with your ' +
             "login and auth paths ahead of it).");
     }
     return config;

package/dist/email/send.js

@@ -95,7 +95,12 @@ function describe(mail, reason, includeBody) {
             "   binding to deliver it, or pass `devLog: true` if this really is local.)",
         ].join("\n");
     }
-    return [...head, "  ---", ...mail.content.text.split("\n").map((line) => `  ${line}`), "  ---"].join("\n");
+    return [
+        ...head,
+        "  ---",
+        ...mail.content.text.split("\n").map((line) => `  ${line}`),
+        "  ---",
+    ].join("\n");
 }
 /**
  * Best-effort "are we in development?".

package/dist/map/pmtiles.js

@@ -112,7 +112,7 @@ export async function servePmtiles(request, options) {
         // client's view of the archive.
         const got = object.range ?? {};
         const start = got.offset ?? (parsed.kind === "suffix" ? object.size - parsed.suffix : parsed.offset);
-        const length = got.length ?? (got.suffix ?? object.size - start);
+        const length = got.length ?? got.suffix ?? object.size - start;
         return new Response(head ? null : (object.body ?? null), {
             status: 206,
             headers: headers({

package/dist/map/scaffold.js

@@ -116,7 +116,7 @@ export function generateMapEmbedComponent(config) {
         "",
         "{",
         "  show ? (",
-        '    <div',
+        "    <div",
         '      class="astroid-map"',
         "      data-astroid-map",
         "      data-lat={nlat}",
@@ -159,12 +159,12 @@ export function generateMapEmbedComponent(config) {
         "      })));",
         "",
         "    const init = async (el: HTMLElement) => {",
-        '      const lat = Number(el.dataset.lat);',
-        '      const lng = Number(el.dataset.lng);',
+        "      const lat = Number(el.dataset.lat);",
+        "      const lng = Number(el.dataset.lng);",
         "      if (!Number.isFinite(lat) || !Number.isFinite(lng)) return;",
         "",
         "      const { maplibregl, Protocol } = await load();",
-        '      // Register the pmtiles:// protocol once so MapLibre range-reads the',
+        "      // Register the pmtiles:// protocol once so MapLibre range-reads the",
         "      // archive instead of requesting tile URLs.",
         '      maplibregl.addProtocol("pmtiles", new Protocol().tile);',
         "",
@@ -172,7 +172,7 @@ export function generateMapEmbedComponent(config) {
         "        container: el,",
         '        style: JSON.parse(el.dataset.style ?? "{}"),',
         "        center: [lng, lat],",
-        '        zoom: Number(el.dataset.zoom ?? 15),',
+        "        zoom: Number(el.dataset.zoom ?? 15),",
         "        // A map that swallows page scroll is a trap on mobile; cooperative",
         "        // gestures require an explicit modifier/two fingers to pan.",
         "        cooperativeGestures: true,",
@@ -182,7 +182,7 @@ export function generateMapEmbedComponent(config) {
         "      });",
         '      map.addControl(new maplibregl.NavigationControl({ showCompass: false }), "top-right");',
         "",
-        "      const pin = document.createElement(\"div\");",
+        '      const pin = document.createElement("div");',
         "      pin.style.cssText =",
         `        "width:18px;height:18px;border-radius:999px;background:${brand};" +`,
         '        "border:3px solid #fff;box-shadow:0 0 0 6px rgba(0,0,0,0.12);";',

package/dist/portal/scaffold.js

@@ -58,7 +58,7 @@ export function generateAstroidPortalAuth(config) {
         "        // only thing that applies the DUMMY_REPLACE_ME sentinel check. Built by",
         "        // hand, a fresh deploy with a real EMAIL binding but a placeholder",
         "        // MAIL_FROM read as configured and called the Email API with an envelope",
-        "        // sender of literally \"DUMMY_REPLACE_ME\" — rejected upstream, swallowed",
+        '        // sender of literally "DUMMY_REPLACE_ME" — rejected upstream, swallowed',
         "        // here, and reported to the user as a reset email that was sent.",
         "        const mailer = await resolveMailer(env);",
         "        await sendTransactional(mailer, [",

package/dist/project/generate.js

@@ -14,7 +14,7 @@
 //      them (fills real binding ids, secrets, account). `astroid generate` must
 //      NEVER clobber them, or it would wipe provisioned ids — so they live in a
 //      separate function the regenerate path doesn't call.
-import { ASTROID_VITALS_BINDING, astroidVitalsDataset, } from "../analytics/index.js";
+import { ASTROID_VITALS_BINDING, astroidVitalsDataset } from "../analytics/index.js";
 import { astroidCheckoutVars } from "../commerce/checkout-scaffold.js";
 import { astroidCommerceProviders } from "../commerce/roles.js";
 import { COMMERCE_PROVIDER_SECRETS, COMMERCE_PROVIDER_SETUP, commerceSecretNames, } from "../commerce/secrets.js";
@@ -130,7 +130,7 @@ export function generateAstroidWrangler(config) {
         p("  // `new_classes`) because the session keeps its authoritative state in");
         p("  // `ctx.storage`, which is the SQLite-backed store — and the storage");
         p("  // backend cannot be changed after the class is first deployed.");
-        p("  \"migrations\": [");
+        p('  "migrations": [');
         p(`    { "tag": ${JSON.stringify(ASTROID_REALTIME_MIGRATION_TAG)}, "new_sqlite_classes": [${JSON.stringify(ASTROID_EDIT_SESSION_CLASS)}] }`);
         p("  ],");
     }

package/dist/project/scaffold.js

@@ -71,7 +71,7 @@ export function generateAstroidScaffoldFiles(config) {
             "// here; the generated src/schema.ts re-exports everything from this file, so",
             "// drizzle-kit sees them and the worker can import them. Empty by default.",
             "//",
-            "// e.g.  export const redirects = sqliteTable(\"redirects\", { … });",
+            '// e.g.  export const redirects = sqliteTable("redirects", { … });',
             "export {};",
             "",
         ].join("\n"),

package/dist/pwa/generate.js

@@ -70,8 +70,18 @@ export function generateWebManifest(config) {
             // A maskable icon is a separate asset, not a flag on the same file: the
             // platform crops it to its own shape, so the artwork needs padding the
             // `any` icon shouldn't have.
-            { src: "/icons/maskable-192.png", sizes: "192x192", type: "image/png", purpose: "maskable" },
-            { src: "/icons/maskable-512.png", sizes: "512x512", type: "image/png", purpose: "maskable" },
+            {
+                src: "/icons/maskable-192.png",
+                sizes: "192x192",
+                type: "image/png",
+                purpose: "maskable",
+            },
+            {
+                src: "/icons/maskable-512.png",
+                sizes: "512x512",
+                type: "image/png",
+                purpose: "maskable",
+            },
         ],
     }, null, 2)}\n`;
 }

package/dist/queues/scaffold.js

@@ -120,7 +120,7 @@ export function generateAstroidQueueSeam(config) {
         "      //",
         `      //   const items = (await listCatalog(token)).map(${provider ?? "provider"}ToCatalogItem);`,
         `      //   const r = await astroidCatalogSync(items, { db: env.DB, table: ${JSON.stringify(table)} });`,
-        "      //   if (r.failed > 0) console.warn(\"[catalog] skipped\", r.failed, r.errors);",
+        '      //   if (r.failed > 0) console.warn("[catalog] skipped", r.failed, r.errors);',
         "      //",
         "      // The sync is idempotent (keyed on the provider's id) and never",
         "      // writes an owner-edited column, so it's safe to run on every event.",

package/dist/schema/collections.js

@@ -47,6 +47,19 @@ function pageMediaBase(config) {
 function resolveSectionCatalog(config) {
     return config.sectionCatalog ?? astroidSectionCatalog;
 }
+/**
+ * The block catalog a `pages` write is validated + sanitized against (ADR 0005).
+ * Defaults to empty, which is correct for a sections-only site: with no section
+ * declaring a `blocks` policy, no block is ever reached.
+ *
+ * It is NOT optional once a site does declare one. Unlike the section catalog
+ * there's no built-in fallback to borrow — block types are wholly site-defined —
+ * so an unset catalog means every block `_type` reads as unknown and the write
+ * 422s, and block rich text goes unsanitized because its def can't be resolved.
+ */
+function resolveBlockCatalog(config) {
+    return config.blockCatalog ?? {};
+}
 /**
  * Return a copy of a `pages` write payload with its `sections` rich-text fields
  * sanitized against the project media base — a no-op when the write carries no
@@ -61,7 +74,7 @@ export function sanitizeAstroidPageSections(config, data) {
     if (data.sections === undefined)
         return data;
     const mediaBase = pageMediaBase(config);
-    const sections = sanitizeSectionsRichText(data.sections, resolveSectionCatalog(config), (html) => sanitizeRichHtml(html, { mediaBase }));
+    const sections = sanitizeSectionsRichText(data.sections, resolveSectionCatalog(config), (html) => sanitizeRichHtml(html, { mediaBase }), resolveBlockCatalog(config));
     return { ...data, sections };
 }
 /**
@@ -77,6 +90,7 @@ export async function assertAstroidPageSections(config, data, operation = "updat
     await assertValidSections(resolveSectionCatalog(config), data.sections, {
         operation,
         mediaBase: pageMediaBase(config),
+        blockCatalog: resolveBlockCatalog(config),
     });
 }
 /**

package/dist/worker/generate.js

@@ -11,7 +11,7 @@
 // the pages routes is wired here — versionsRoute runs it through the collection's
 // beforeChange hook, and pagesRoute (which takes no collection config) through
 // the `astroidPagesWriteHooks` spread, so both write paths enforce one contract.
-import { ASTROID_VITALS_BINDING, generateAstroidCwvQuery, } from "../analytics/index.js";
+import { ASTROID_VITALS_BINDING, generateAstroidCwvQuery } from "../analytics/index.js";
 import { astroidEditorTable } from "../auth/index.js";
 import { astroidPortal } from "../portal/config.js";
 import { ASTROID_HEALTH_CRON, astroidCron, astroidUsesQueues } from "../queues/messages.js";
@@ -194,10 +194,7 @@ export function generateAstroidWorker(config) {
     p();
     p("// Editable site_settings columns the Settings panel may write, and which of");
     p("// them resolve to a media-library asset.");
-    const settingsImageKeys = [
-        ...ASTROID_SETTINGS_IMAGE_KEYS,
-        ...(config.settings?.imageKeys ?? []),
-    ];
+    const settingsImageKeys = [...ASTROID_SETTINGS_IMAGE_KEYS, ...(config.settings?.imageKeys ?? [])];
     const settingsCustomKeys = config.settings?.customKeys ?? [];
     // A custom-heavy site can override (or empty) the editable base columns.
     const settingsColumns = config.settings?.columns ?? ASTROID_SETTINGS_COLUMNS;
@@ -245,11 +242,11 @@ export function generateAstroidWorker(config) {
     p("async function runHealthScan(env: CloudflareEnv) {");
     p("  const origin = env.SITE_URL ?? MEDIA_BASE;");
     p("  const [brokenLinks, missingAlt, seoGaps] = await Promise.all([");
-    p("    checkLinks({ base: origin, paths: [\"/\"] }).catch(() => []),");
+    p('    checkLinks({ base: origin, paths: ["/"] }).catch(() => []),');
     p("    countRows(env, \"SELECT COUNT(*) AS n FROM media WHERE alt IS NULL OR alt = ''\"),");
     p("    countRows(");
     p("      env,");
-    p('      "SELECT COUNT(*) AS n FROM pages WHERE status = \'published\'" +');
+    p("      \"SELECT COUNT(*) AS n FROM pages WHERE status = 'published'\" +");
     p("      \" AND (seo_title IS NULL OR seo_title = '' OR seo_description IS NULL OR seo_description = '')\",");
     p("    ),");
     p("  ]);");
@@ -292,7 +289,7 @@ export function generateAstroidWorker(config) {
     p("  const row = await env.DB.prepare(");
     p('    "SELECT" +');
     p("    \" (SELECT COUNT(*) FROM pages WHERE status = 'draft') AS drafts,\" +");
-    p('    " (SELECT COUNT(DISTINCT parent_id) FROM pages_versions WHERE status = \'draft\') AS unpublished," +');
+    p("    \" (SELECT COUNT(DISTINCT parent_id) FROM pages_versions WHERE status = 'draft') AS unpublished,\" +");
     p('    " (SELECT MAX(updated_at) FROM pages) AS last_edited",');
     p("  ).first<{ drafts: number; unpublished: number; last_edited: number | null }>();");
     p("  if (!row) return undefined;");
@@ -352,7 +349,7 @@ export function generateAstroidWorker(config) {
     p("  // Wrapped UNCONDITIONALLY, and that is safe: `withEdgeCache` only stores a");
     p("  // response that carries a cacheable Cloudflare-CDN-Cache-Control directive,");
     p("  // and a page emits one only via `Astro.cache.set(...)` — which the scaffold");
-    p("  // gates on ASTROID_EDGE_CACHE being \"true\" AND the request not being in edit");
+    p('  // gates on ASTROID_EDGE_CACHE being "true" AND the request not being in edit');
     p("  // mode. With the var off (the default) every render is `no-store`, so this");
     p("  // layer stores nothing and is a transparent pass-through.");
     p("  //");

package/dist/workflow/generate.js

@@ -41,12 +41,12 @@ export function generateWorkflowSchema(config) {
         "  {",
         '    id: integer("id").primaryKey({ autoIncrement: true }),',
         `    ${camel(fk)}: text(${JSON.stringify(fk)}).notNull(),`,
-        '    /** The stage this row completes (0-based). */',
+        "    /** The stage this row completes (0-based). */",
         '    stage: integer("stage").notNull(),',
         "    /** Recorded values for the stage, [{ k, v }] JSON. */",
         '    specs: text("specs", { mode: "json" }).$type<{ k: string; v: string }[]>(),',
         '    initials: text("initials").notNull(),',
-        '    /** Account id when the pipeline runs behind a portal. */',
+        "    /** Account id when the pipeline runs behind a portal. */",
         '    actorId: text("actor_id"),',
         '    signedAt: integer("signed_at", { mode: "timestamp" })',
         "      .notNull()",
@@ -110,7 +110,7 @@ export function generateWorkflowRoute(config) {
         "    specs?: { k: string; v: string }[];",
         "  } | null;",
         "",
-        "  if (!body?.id || typeof body.stage !== \"number\") {",
+        '  if (!body?.id || typeof body.stage !== "number") {',
         '    return Response.json({ ok: false, error: "Bad request" }, { status: 400 });',
         "  }",
         "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astroidjs",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Astroid — an opinionated meta-framework over Louise Toolkit and Astro for building editable, multi-editor sites on Cloudflare Workers.",
   "keywords": [
     "astro",
@@ -17,10 +17,15 @@
     "url": "git+https://github.com/bowenlabs/louise-toolkit.git",
     "directory": "packages/astroid"
   },
-  "type": "module",
   "bin": {
     "astroid": "./bin/astroid.mjs"
   },
+  "files": [
+    "dist",
+    "bin",
+    "src/components"
+  ],
+  "type": "module",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -51,16 +56,18 @@
     },
     "./package.json": "./package.json"
   },
-  "files": [
-    "dist",
-    "bin",
-    "src/components"
-  ],
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "louise-toolkit": "0.18.0"
+    "louise-toolkit": "0.19.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "solid-js": "^1.9.14",
+    "typescript": "^5.8.0",
+    "vitest": "^4.1.10"
   },
   "peerDependencies": {
     "solid-js": "^1.9.0"
@@ -70,18 +77,12 @@
       "optional": true
     }
   },
-  "devDependencies": {
-    "@types/node": "^24.13.3",
-    "@typescript/native-preview": "7.0.0-dev.20260707.2",
-    "solid-js": "^1.9.14",
-    "typescript": "^5.8.0",
-    "vitest": "^4.1.10"
-  },
   "engines": {
     "node": ">=24.0.0"
   },
   "scripts": {
     "build": "tsgo -p tsconfig.build.json",
+    "check": "vp check",
     "test": "vp test",
     "typecheck": "tsgo --noEmit"
   }

package/src/components/sections.ts

@@ -30,12 +30,7 @@
 // import is TYPE-ONLY, so it erases at build and never drags the validator (or
 // drizzle, which that entry pulls in) into a page bundle.
 
-import type {
-  SectionCatalog,
-  SectionDef,
-  SectionField,
-  SectionItem,
-} from "louise-toolkit/content";
+import type { SectionCatalog, SectionDef, SectionField, SectionItem } from "louise-toolkit/content";
 
 export type { SectionCatalog, SectionDef, SectionField, SectionItem };