astroidjs 0.1.1 → 0.2.0

package/dist/queues/scaffold.js

@@ -0,0 +1,204 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The two SCAFFOLD-ONCE files the queue pipeline needs: the consumer seam
+// (`src/queue.ts`) and the provider webhook receiver.
+//
+// Deliberately not part of the regenerated trio. Both exist to be edited — the
+// consumer is where a project says what a catalog refresh actually does, and the
+// webhook route is where it narrows which events it cares about. Regenerating
+// over them would erase exactly the work they're for. The same boundary
+// `generateAstroidWrangler` already lives on.
+import { astroidCatalogMirror } from "../commerce/mirror.js";
+import { astroidCommerceProviders, astroidCommerceRoles } from "../commerce/roles.js";
+import { COMMERCE_PROVIDER_SECRETS } from "../commerce/secrets.js";
+import { ASTROID_QUEUE_BINDING } from "./messages.js";
+/**
+ * Per-provider webhook facts: the header, the verifier, and how it's called.
+ *
+ * The signing-secret NAME is deliberately not here — it's one field of a
+ * provider's secret set, which `commerce/secrets.ts` owns so the wrangler
+ * generator, the status report, and this scaffold all read the same list.
+ */
+const PROVIDERS = {
+    square: {
+        module: "louise-toolkit/commerce/square",
+        verifier: "verifySquareSignature",
+        header: "x-square-hmacsha256-signature",
+        // Square signs the notification URL CONCATENATED with the body, so the URL
+        // has to match what's configured in the Square dashboard exactly.
+        call: "verifySquareSignature(url.href, raw, headers.get(HEADER), secret)",
+        note: "Square signs `notificationUrl + body`, so url.href must match the endpoint you registered.",
+    },
+    stripe: {
+        module: "louise-toolkit/commerce/stripe",
+        verifier: "verifyStripeSignature",
+        header: "stripe-signature",
+        // Stripe's header carries a timestamp; the verifier rejects replays outside
+        // its tolerance, so it needs the current time.
+        call: 'verifyStripeSignature(raw, headers.get(HEADER) ?? "", secret, Math.floor(Date.now() / 1000))',
+        note: "Stripe's signature is timestamped — the verifier rejects replays outside a 5-minute tolerance.",
+    },
+    fourthwall: {
+        module: "louise-toolkit/commerce/fourthwall",
+        verifier: "verifyFourthwallSignature",
+        header: "x-fourthwall-hmac-sha256",
+        call: "verifyFourthwallSignature(raw, headers.get(HEADER), secret)",
+        note: "Fourthwall signs the raw body only.",
+    },
+};
+/**
+ * The extra `CloudflareEnv` members the queue pipeline introduces, as a block
+ * `create-astroid` substitutes into the scaffolded `src/env.d.ts`.
+ *
+ * Substituted rather than always present because a declaration is a promise: a
+ * marketing site that types `COMMERCE_QUEUE` is claiming a binding its
+ * `wrangler.jsonc` never creates, and the first `env.COMMERCE_QUEUE.send()`
+ * someone writes against that type fails at runtime with the type system's
+ * blessing. Empty string when the project runs no consumer.
+ */
+export function generateAstroidEnvBindings(config) {
+    const providers = astroidCommerceProviders(config.commerce);
+    if (providers.length === 0)
+        return "";
+    return [
+        "  /** Queue producer — verified webhooks + the cron re-sync (src/queue.ts). */",
+        '  COMMERCE_QUEUE: Queue<import("astroidjs").AstroidQueueMessage>;',
+        // One secret SET per provider: a site running Stripe for invoicing and
+        // Fourthwall for the storefront talks to both, credentialed and signed
+        // independently. Every one is optional, because every one is allowed to be
+        // absent — that's what leaves the module dormant rather than broken.
+        ...providers.flatMap((provider) => [
+            `  /** ${provider} API credentials. Absent or still holding the`,
+            "   *  DUMMY_REPLACE_ME sentinel reads as unconfigured, which leaves commerce",
+            "   *  dormant: the D1 mirror still serves, nothing calls upstream. */",
+            ...COMMERCE_PROVIDER_SECRETS[provider].credentials.map((name) => `  ${name}?: string;`),
+            `  /** ${provider} webhook signing secret. Until it holds a real value the`,
+            "   *  receiver answers 503, so the provider keeps retrying and events",
+            "   *  delivered before you provisioned it still land afterwards. */",
+            `  ${COMMERCE_PROVIDER_SECRETS[provider].webhook}?: string;`,
+        ]),
+    ].join("\n");
+}
+/**
+ * `src/queue.ts` — the consumer seam the generated worker imports.
+ *
+ * `astroidQueueHandler` already owns the dispatch every site wrote (periodic
+ * refresh, catalog-affecting webhook, no-op for everything else); what's left
+ * for the project is what "refresh" means, which is why this is a file and not
+ * a generated constant.
+ */
+export function generateAstroidQueueSeam(config) {
+    // The STOREFRONT provider — it's the one with a catalog to re-sync. An
+    // invoicing-only provider has nothing for this hook to do.
+    const provider = astroidCommerceRoles(config.commerce).storefront;
+    const table = astroidCatalogMirror(config).table;
+    return [
+        "// The queue consumer — what each message actually does.",
+        "//",
+        "// Scaffolded once; yours to edit. `astroidQueueHandler` owns the dispatch",
+        "// (a periodic refresh and any catalog-affecting webhook trigger a re-sync;",
+        "// everything else acks as a no-op), so what's left here is what a refresh",
+        "// MEANS for this project.",
+        "//",
+        "// Throwing marks the message for retry. That's usually right — a failed",
+        "// refresh means the site is serving stale data — and Cloudflare routes it to",
+        "// the DLQ once it exceeds max_retries (wrangler.jsonc).",
+        'import { astroidQueueHandler, type AstroidQueueMessage } from "astroidjs";',
+        "",
+        "export async function handleQueueMessage(",
+        "  env: CloudflareEnv,",
+        "  message: AstroidQueueMessage,",
+        "): Promise<void> {",
+        "  await astroidQueueHandler({",
+        "    refreshCatalog: async () => {",
+        provider
+            ? `      // TODO: fetch the ${provider} catalog, normalize each item with`
+            : "      // TODO: fetch your catalog and normalize each item to a CatalogItem,",
+        provider
+            ? `      // ${provider}ToCatalogItem, then hand the array to astroidCatalogSync:`
+            : "      // then hand the array to astroidCatalogSync:",
+        "      //",
+        `      //   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);",
+        "      //",
+        "      // 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.",
+        "      //",
+        "      // It THROWS if every item failed (an unapplied migration, D1 down), and",
+        "      // letting that escape is correct: an uncaught throw here marks the",
+        "      // message for retry. Swallow it and the queue acks, the cron acks too,",
+        "      // and the site serves a frozen catalog with nothing in `wrangler tail`.",
+        "      // Partial failures don't throw — that's what `r.failed` above is for.",
+        "      void env;",
+        "    },",
+        "  })(message);",
+        "}",
+        "",
+    ]
+        .filter((line) => line !== "")
+        .join("\n");
+}
+/**
+ * The provider webhook receiver — `src/pages/api/webhooks/<provider>.ts`.
+ *
+ * Thin on purpose: `handleWebhook` owns the ordering (verify the raw body before
+ * parsing) and the status-code contract (which codes ask the provider to retry
+ * and which tell it to stop). What's here is the provider's own header and
+ * verifier, plus the secret read.
+ *
+ * Returns null when the project has no commerce provider — nothing to receive.
+ */
+export function generateAstroidWebhookRoute(config, forProvider) {
+    const provider = forProvider ?? astroidCommerceProviders(config.commerce)[0];
+    if (!provider)
+        return null;
+    const p = PROVIDERS[provider];
+    return [
+        `// ${provider[0].toUpperCase()}${provider.slice(1)} webhook receiver.`,
+        "//",
+        "// Scaffolded once; yours to edit. The order is the important part and",
+        "// `handleWebhook` owns it: the raw body is verified BEFORE anything parses",
+        "// it, then the event is enqueued and this returns immediately. The consumer",
+        "// (src/queue.ts) does the actual work, with Cloudflare owning retries + DLQ.",
+        "//",
+        `// ${p.note}`,
+        "//",
+        "// Unprovisioned (the secret is absent or still the placeholder) answers 503,",
+        "// which keeps the provider retrying — so events delivered before you set the",
+        "// secret land afterwards instead of being lost.",
+        'import type { APIRoute } from "astro";',
+        'import { handleWebhook, readModuleSecret } from "astroidjs";',
+        'import { env } from "cloudflare:workers";',
+        `import { ${p.verifier} } from ${JSON.stringify(p.module)};`,
+        "",
+        "export const prerender = false;",
+        "",
+        `const HEADER = ${JSON.stringify(p.header)};`,
+        "",
+        "export const POST: APIRoute = async ({ request, url }) => {",
+        "  const headers = request.headers;",
+        "  return handleWebhook(request, url, {",
+        `    provider: ${JSON.stringify(provider)},`,
+        `    secret: await readModuleSecret(env.${COMMERCE_PROVIDER_SECRETS[provider].webhook}),`,
+        `    queue: env.${ASTROID_QUEUE_BINDING},`,
+        `    verify: ({ raw, secret }) => ${p.call},`,
+        "  });",
+        "};",
+        "",
+    ].join("\n");
+}
+/**
+ * Every webhook receiver this project needs, as `{ path, contents }`.
+ *
+ * Plural because roles are: a site running Stripe for invoicing beside
+ * Fourthwall for the storefront receives from both, each with its own signing
+ * secret and header. One route per provider, not per role — a provider filling
+ * two roles still has one endpoint and one secret.
+ */
+export function generateAstroidWebhookRoutes(config) {
+    return astroidCommerceProviders(config.commerce).flatMap((provider) => {
+        const contents = generateAstroidWebhookRoute(config, provider);
+        return contents ? [{ path: `src/pages/api/webhooks/${provider}.ts`, contents }] : [];
+    });
+}

package/dist/queues/webhook.d.ts

@@ -0,0 +1,60 @@
+import type { AstroidQueueMessage } from "./messages.js";
+/**
+ * The queue producer surface used here — structural, so a real `Queue<T>`
+ * binding satisfies it without astroid depending on the Workers types.
+ *
+ * `Promise<unknown>` rather than `Promise<void>`: Cloudflare's `Queue.send`
+ * resolves to a `QueueSendResponse`, and a `void` return type would reject the
+ * actual binding. Nothing here reads the value.
+ */
+export interface QueueProducer<T = AstroidQueueMessage> {
+    send(message: T): Promise<unknown>;
+}
+export interface WebhookVerifyInput {
+    /** The raw request body, exactly as received. */
+    raw: string;
+    headers: Headers;
+    url: URL;
+    /** The signing secret — already checked to be real by the caller. */
+    secret: string;
+}
+export interface WebhookRouteOptions {
+    /** Which integration this endpoint serves — carried into the message. */
+    provider: string;
+    /**
+     * The signing secret, or `null` when unprovisioned. Read it with
+     * `readModuleSecret` so a placeholder counts as absent.
+     */
+    secret: string | null;
+    /** Signature check over the raw body — e.g. `verifySquareSignature`. */
+    verify: (input: WebhookVerifyInput) => boolean | Promise<boolean>;
+    /** The queue binding, or null/undefined when Queues aren't provisioned. */
+    queue?: QueueProducer | null;
+    /**
+     * Pull the event type out of the parsed payload. Defaults to a `type` field;
+     * override for providers that name it differently (Fourthwall's `testMode`
+     * envelope, Stripe's nested object).
+     */
+    eventType?: (payload: unknown) => string;
+    /**
+     * Decide whether an event is worth queueing at all. Returning false acks the
+     * delivery without enqueuing — the provider is satisfied and the consumer
+     * isn't woken for an event nothing acts on.
+     */
+    accept?: (type: string, payload: unknown) => boolean;
+}
+/**
+ * Handle one inbound provider webhook.
+ *
+ * ```ts
+ * export const POST: APIRoute = ({ request, url }) =>
+ *   handleWebhook(request, url, {
+ *     provider: "square",
+ *     secret: await readModuleSecret(env.SQUARE_WEBHOOK_SECRET),
+ *     queue: env.COMMERCE_QUEUE,
+ *     verify: ({ raw, headers, url, secret }) =>
+ *       verifySquareSignature(url.href, raw, headers.get("x-square-hmacsha256-signature"), secret),
+ *   });
+ * ```
+ */
+export declare function handleWebhook(request: Request, url: URL, options: WebhookRouteOptions): Promise<Response>;

package/dist/queues/webhook.js

@@ -0,0 +1,81 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The webhook receiver: verify → enqueue → return fast.
+//
+// All three sites wrote this route the same way, and the ordering is the part
+// worth encoding. **Verify the HMAC over the raw body before parsing anything.**
+// Not for style — parsing first means an unauthenticated caller can reach the
+// JSON parser and everything downstream of it, and re-serializing a parsed body
+// to check the signature is how signature checks quietly stop checking anything.
+// So the raw text is read once, verified, and only then parsed.
+//
+// The other half is what the status code means to the sender. Every provider
+// here retries on non-2xx, which makes the response the only backpressure signal
+// available: a 5xx means "try again", a 4xx means "never again", and returning
+// the wrong one either loses the event permanently or pins the provider in a
+// retry loop. Each code below is chosen for what it tells the sender to do.
+const text = (body, status) => new Response(body, { status, headers: { "content-type": "text/plain; charset=utf-8" } });
+/** Default event-type reader: a top-level `type` string. */
+function defaultEventType(payload) {
+    const type = payload?.type;
+    return typeof type === "string" ? type : "";
+}
+/**
+ * Handle one inbound provider webhook.
+ *
+ * ```ts
+ * export const POST: APIRoute = ({ request, url }) =>
+ *   handleWebhook(request, url, {
+ *     provider: "square",
+ *     secret: await readModuleSecret(env.SQUARE_WEBHOOK_SECRET),
+ *     queue: env.COMMERCE_QUEUE,
+ *     verify: ({ raw, headers, url, secret }) =>
+ *       verifySquareSignature(url.href, raw, headers.get("x-square-hmacsha256-signature"), secret),
+ *   });
+ * ```
+ */
+export async function handleWebhook(request, url, options) {
+    // 503, not 500 or 200: the module is dormant, which is a temporary state a
+    // deploy fixes. 5xx keeps the provider retrying, so events delivered during
+    // the gap land once the secret is provisioned instead of being lost.
+    if (!options.secret)
+        return text("Webhook not configured", 503);
+    const raw = await request.text();
+    let valid = false;
+    try {
+        valid = await options.verify({ raw, headers: request.headers, url, secret: options.secret });
+    }
+    catch {
+        valid = false;
+    }
+    // 401 is terminal on purpose. A signature that doesn't check out will never
+    // check out on retry, and asking the provider to keep trying turns a
+    // misconfiguration into a self-inflicted flood.
+    if (!valid)
+        return text("Invalid signature", 401);
+    let payload;
+    try {
+        payload = JSON.parse(raw);
+    }
+    catch {
+        // Also terminal — a body that isn't JSON now won't become JSON later.
+        return text("Invalid JSON", 400);
+    }
+    const type = (options.eventType ?? defaultEventType)(payload);
+    if (options.accept && !options.accept(type, payload)) {
+        return text("Ignored", 202);
+    }
+    if (!options.queue)
+        return text("Queue not configured", 503);
+    try {
+        await options.queue.send({ kind: "webhook", provider: options.provider, type, payload });
+    }
+    catch {
+        // The signature was good, so this event is real and worth keeping. 503 asks
+        // the provider to redeliver rather than dropping it.
+        return text("Queue unavailable", 503);
+    }
+    // 202, not 200: the work hasn't happened yet, it's been accepted. That's the
+    // entire point of enqueuing — the response returns before the consumer runs.
+    return text("Accepted", 202);
+}

package/dist/realtime/index.d.ts

@@ -0,0 +1 @@
+export { ASTROID_EDIT_SESSION_CLASS, ASTROID_REALTIME_BINDING, ASTROID_REALTIME_MIGRATION_TAG, generateAstroidEditSession, generateAstroidRealtimeEnv, usesRealtime, } from "./scaffold.js";

package/dist/realtime/index.js

@@ -0,0 +1,4 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The realtime module's scaffold surface (ADR 0002 / #71).
+export { ASTROID_EDIT_SESSION_CLASS, ASTROID_REALTIME_BINDING, ASTROID_REALTIME_MIGRATION_TAG, generateAstroidEditSession, generateAstroidRealtimeEnv, usesRealtime, } from "./scaffold.js";

package/dist/realtime/scaffold.d.ts

@@ -0,0 +1,30 @@
+import type { AstroidConfig } from "../config.js";
+/** The DO namespace binding name. Fixed, like the portal's prefixes: the client
+ *  and the route both address it, and a rename is a silent 503. */
+export declare const ASTROID_REALTIME_BINDING = "EDIT_SESSION";
+/** The exported class name wrangler resolves for the binding. Must match the
+ *  `class_name` in wrangler.jsonc AND be re-exported from the worker entry. */
+export declare const ASTROID_EDIT_SESSION_CLASS = "EditSessionDO";
+/** Migration tag for the DO class. Wrangler requires one; `v1` is the first. */
+export declare const ASTROID_REALTIME_MIGRATION_TAG = "v1";
+/** Is the realtime module switched on for this project? */
+export declare function usesRealtime(config: AstroidConfig): boolean;
+/**
+ * `src/edit-session.ts` — the site-owned Durable Object subclass.
+ *
+ * Scaffold-once: `persist` is where a project decides what a flush means, and
+ * the lock/field sets are tuning. What Astroid fixes is the delegation shape,
+ * because getting it wrong fails in ways that look like anything but a bug in
+ * this file — a missing `webSocketClose` leaks presence forever, a non-lazy
+ * session breaks after the first hibernation wake.
+ *
+ * Returns null when the project has no realtime module.
+ */
+export declare function generateAstroidEditSession(config: AstroidConfig): string | null;
+/**
+ * The `CloudflareEnv` member the realtime module adds, as a block
+ * `create-astroid` substitutes into `src/env.d.ts`. Empty without the module —
+ * a project that types a binding its wrangler.jsonc never creates is making a
+ * promise it doesn't keep.
+ */
+export declare function generateAstroidRealtimeEnv(config: AstroidConfig): string;

package/dist/realtime/scaffold.js

@@ -0,0 +1,159 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The realtime module (ADR 0002 / #71): per-page live editing over a Durable
+// Object, opt-in via `modules: ["realtime"]`.
+//
+// The package description has claimed "multi-editor sites" since 0.1.0, and this
+// is the half that makes it true for two people on the SAME page. (The other
+// axis — multi-EDITOR, i.e. an org of accounts — was always real.) Without it
+// two editors on one page clobber each other; the server-side draft merge
+// narrows the window but there is no live channel, no presence, and no signal
+// that someone else is in the same field.
+//
+// What Astroid generates and what it deliberately does NOT:
+//
+//   - The DO SUBCLASS is scaffold-once (`src/edit-session.ts`), because it must
+//     import `cloudflare:workers` — a runtime-only specifier the toolkit can't
+//     carry — and because its `persist` is the seam a project tunes. Louise
+//     ships the session LOGIC it delegates to; this is the boilerplate around it.
+//   - The wrangler `durable_objects` binding + `migrations` block, which is the
+//     part nobody gets right from memory: a DO class needs a migration tag, and
+//     a SQLite-backed one needs `new_sqlite_classes` rather than `new_classes`.
+//   - The `realtimeRoute` upgrade endpoint, in the generated worker.
+//
+// Persistence goes through `applySaveDraft` — the SAME path the fetch auto-save
+// uses. One write path, per the ADR: the DO is a new front end to it, not a
+// parallel store, so drafts, version history, publish, and read-your-writes all
+// stay intact.
+/** The DO namespace binding name. Fixed, like the portal's prefixes: the client
+ *  and the route both address it, and a rename is a silent 503. */
+export const ASTROID_REALTIME_BINDING = "EDIT_SESSION";
+/** The exported class name wrangler resolves for the binding. Must match the
+ *  `class_name` in wrangler.jsonc AND be re-exported from the worker entry. */
+export const ASTROID_EDIT_SESSION_CLASS = "EditSessionDO";
+/** Migration tag for the DO class. Wrangler requires one; `v1` is the first. */
+export const ASTROID_REALTIME_MIGRATION_TAG = "v1";
+/** Is the realtime module switched on for this project? */
+export function usesRealtime(config) {
+    return (config.modules ?? []).includes("realtime");
+}
+/**
+ * `src/edit-session.ts` — the site-owned Durable Object subclass.
+ *
+ * Scaffold-once: `persist` is where a project decides what a flush means, and
+ * the lock/field sets are tuning. What Astroid fixes is the delegation shape,
+ * because getting it wrong fails in ways that look like anything but a bug in
+ * this file — a missing `webSocketClose` leaks presence forever, a non-lazy
+ * session breaks after the first hibernation wake.
+ *
+ * Returns null when the project has no realtime module.
+ */
+export function generateAstroidEditSession(config) {
+    if (!usesRealtime(config))
+        return null;
+    return [
+        "// The per-page live editing session Durable Object (ADR 0002 / #71).",
+        "//",
+        "// Scaffolded once and yours to edit — `persist` in particular. What should NOT",
+        "// change is the delegation: every handler forwards to the session object, and",
+        "// the session is built LAZILY. A Durable Object is re-instantiated after a",
+        "// hibernation wake, so a session captured in a field initializer would be",
+        "// rebuilt anyway; the authoritative state lives in `ctx.storage` and the socket",
+        "// attachments, never in this class.",
+        "//",
+        "// This class must stay EXPORTED FROM src/worker.ts (it is, via a re-export) or",
+        "// wrangler can't resolve the `class_name` in the durable_objects binding.",
+        "",
+        'import { DurableObject } from "cloudflare:workers";',
+        'import { applySaveDraft } from "louise-toolkit/editor";',
+        'import { createEditSession, type EditSession } from "louise-toolkit/realtime";',
+        'import { astroidPagesCollection } from "astroidjs";',
+        'import astroidConfig from "../astroid.config.js";',
+        'import { pages, pagesVersions } from "./schema.js";',
+        "",
+        "const pagesCollection = astroidPagesCollection(astroidConfig);",
+        "",
+        `export class ${ASTROID_EDIT_SESSION_CLASS} extends DurableObject<CloudflareEnv> {`,
+        "  #session?: EditSession;",
+        "",
+        "  #s(): EditSession {",
+        "    this.#session ??= createEditSession(this.ctx, {",
+        "      // Allowlist = the collection's editable fields. A `change` for anything",
+        "      // else is dropped here as a cheap first gate; applySaveDraft re-validates",
+        "      // the merged draft on persist, so this is not the security boundary.",
+        "      fields: Object.keys(pagesCollection.fields),",
+        "      // The rich-text body is the one field where character-level merge matters,",
+        "      // so it takes a soft-lock (one editor at a time) instead of being",
+        "      // last-writer-wins clobbered. Locked values are never fanned out to peers,",
+        "      // so raw rich text doesn't cross sockets.",
+        '      lockFields: ["body"],',
+        "      persist: async (snapshot, editor, target) => {",
+        "        // Guard the collection: only `pages` is realtime, and a stray target",
+        "        // must never write into the wrong table.",
+        '        if (target.slug !== "pages") return;',
+        "        // The SAME merge-over-pending-draft path the fetch auto-save uses —",
+        "        // one write path, so drafts/history/publish semantics are identical.",
+        "        //",
+        "        // No `bufferKv` here on purpose: the DO's alarm IS the coalescer for",
+        "        // this page, so routing through the KV write-buffer as well would be",
+        "        // two layers of coalescing over one stream of edits.",
+        "        const result = await applySaveDraft(",
+        "          this.env,",
+        "          { table: pages, versionsTable: pagesVersions, config: pagesCollection },",
+        "          editor,",
+        "          target.id,",
+        "          snapshot,",
+        "        );",
+        "        // A THROW (D1 down) propagates so the alarm keeps the snapshot dirty",
+        "        // and retries. An `ok: false` is terminal — a deleted row, an invalid",
+        "        // draft — which a retry can't fix, so let the alarm clear it, but say",
+        "        // so rather than dropping it silently.",
+        "        if (!result.ok) {",
+        "          console.warn(",
+        "            `[realtime] draft flush for pages:${target.id} rejected: ${result.status} ${result.error}`,",
+        "          );",
+        "        }",
+        "      },",
+        "    });",
+        "    return this.#session;",
+        "  }",
+        "",
+        "  fetch(request: Request): Promise<Response> {",
+        "    return this.#s().fetch(request);",
+        "  }",
+        "",
+        "  webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): Promise<void> {",
+        "    return this.#s().webSocketMessage(ws, message);",
+        "  }",
+        "",
+        "  webSocketClose(ws: WebSocket, code: number, reason: string, wasClean: boolean): Promise<void> {",
+        "    return this.#s().webSocketClose(ws, code, reason, wasClean);",
+        "  }",
+        "",
+        "  webSocketError(ws: WebSocket, error: unknown): Promise<void> {",
+        "    return this.#s().webSocketError(ws, error);",
+        "  }",
+        "",
+        "  alarm(): Promise<void> {",
+        "    return this.#s().alarm();",
+        "  }",
+        "}",
+        "",
+    ].join("\n");
+}
+/**
+ * The `CloudflareEnv` member the realtime module adds, as a block
+ * `create-astroid` substitutes into `src/env.d.ts`. Empty without the module —
+ * a project that types a binding its wrangler.jsonc never creates is making a
+ * promise it doesn't keep.
+ */
+export function generateAstroidRealtimeEnv(config) {
+    if (!usesRealtime(config))
+        return "";
+    return [
+        "  /** Durable Object namespace for the per-page live editing session (ADR 0002).",
+        "   *  The realtime route answers 503 without it, so realtime is cleanly absent",
+        "   *  rather than erroring. */",
+        `  ${ASTROID_REALTIME_BINDING}: DurableObjectNamespace;`,
+    ].join("\n");
+}

package/dist/schema/collections.d.ts

@@ -1,15 +1,49 @@
-import { type CollectionConfig, type ContentConfig } from "louise-toolkit/content";
+import { type CollectionConfig, type ContentConfig } from "louise-toolkit/content/define";
 import type { AstroidConfig } from "../config.js";
 /**
- * The opinionated `pages` collection — the EDITABLE page fields, versioned
- * drafts, and full-text search. Keyed to the same names as Louise's `pagesColumns`
- * so a publish's `.set()` maps straight onto the physical columns; bookkeeping
- * columns (`id`/`status`/timestamps/`publishedVersionId`) live on the table via
- * `pagesColumns`, never here — matching the site's `pages-collection.ts`.
+ * 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
+ * `sections`. Pure; leaves every other field (and a partial PATCH's absent ones)
+ * untouched.
  *
- * Validated by `defineCollection` at build time, so a malformed field shape throws
- * here rather than at codegen.
+ * Exported because two write paths need it: the collection's `beforeChange` hook
+ * below, AND the raw `pagesRoute` (which does not run collection hooks — see
+ * {@link astroidPagesWriteHooks}).
  */
+export declare function sanitizeAstroidPageSections(config: AstroidConfig, data: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Validate the (already-sanitized) `sections` of a `pages` write against the
+ * catalog, throwing `LouiseValidationError` — an unknown `_type`, a field of the
+ * wrong shape, or a setting outside its declared options is rejected with a 422
+ * carrying the per-field violations. A no-op when the write carries no
+ * `sections`, so a partial PATCH of other fields isn't spuriously validated.
+ */
+export declare function assertAstroidPageSections(config: AstroidConfig, data: Record<string, unknown>, operation?: "create" | "update"): Promise<void>;
+/**
+ * The write-time hooks the raw `pagesRoute` (louise-toolkit/editor) needs to
+ * enforce the same section contract as the draft path.
+ *
+ * `pagesRoute` writes straight to the table and — unlike `versionsRoute` — takes
+ * no collection config, so it never runs the `beforeChange` hook below. Left
+ * bare (as it was), a direct `POST` / `PATCH /api/louise/pages/:id` persists an
+ * unknown section `_type`, a setting outside its options, or unsanitized section
+ * rich text: exactly what the hook exists to stop, silently missing from the one
+ * route the on-canvas *structural* edits flow through. `<Sections>` then skips
+ * the bad `_type`, so the section just vanishes with no error anywhere.
+ *
+ * These wire the SAME sanitize + validate the hook uses into `pagesRoute`'s
+ * `sanitize` / `transform` / `validate` seams, so both write paths enforce one
+ * contract. Spread into the route config:
+ *
+ *   pagesRoute({ table: pages, resolveEditor, fields, ...astroidPagesWriteHooks(config) })
+ */
+export declare function astroidPagesWriteHooks(config: AstroidConfig): {
+    sanitize: (html: string) => string;
+    transform: (data: Record<string, unknown>) => Record<string, unknown>;
+    validate: (data: Record<string, unknown>, ctx: {
+        operation: "create" | "update";
+    }) => Promise<void>;
+};
 export declare function astroidPagesCollection(config: AstroidConfig): CollectionConfig;
 /**
  * The Louise `ContentConfig` for an Astroid project. Today: the `pages`