astroidjs 0.13.0 → 0.14.0

package/dist/project/generate.js

@@ -98,7 +98,7 @@ export function generateAstroidWrangler(config) {
     const p = (s = "") => lines.push(s);
     p("{");
     p('  "$schema": "node_modules/wrangler/config-schema.json",');
-    p("  // The Cloudflare Worker name — also the default *.workers.dev subdomain.");
+    p("  // The Cloudflare Worker name—also the default *.workers.dev subdomain.");
     p(`  "name": ${JSON.stringify(key)},`);
     p("  // Pin your account so deploys don't prompt (or set CLOUDFLARE_ACCOUNT_ID).");
     p('  // "account_id": "<your-cloudflare-account-id>",');
@@ -108,7 +108,7 @@ export function generateAstroidWrangler(config) {
     p("  // global_fetch_strictly_public: a fetch to this zone goes through Cloudflare's");
     p("  // front door like any Internet request, past the WAF and bot rules (ADR 0012).");
     p("  // If the daily health scan starts reporting broken links that aren't, a zone");
-    p("  // rule is challenging its self-crawl — allow it rather than drop the flag.");
+    p("  // rule is challenging its self-crawl—allow it rather than drop the flag.");
     p('  "compatibility_flags": ["nodejs_compat", "global_fetch_strictly_public"],');
     p("  // @astrojs/cloudflare builds this entry and wires the static assets under dist/.");
     p('  "main": "src/worker.ts",');
@@ -124,7 +124,7 @@ export function generateAstroidWrangler(config) {
             // `custom_domain: true` on a pattern containing `*`, which is precisely
             // why `hosts` cannot express this.
             p("    // Wildcard tenant hosts (`tenancy.hostPattern`). A zone route, NOT a");
-            p("    // custom_domain — Cloudflare refuses a wildcard custom domain. The");
+            p("    // custom_domain—Cloudflare refuses a wildcard custom domain. The");
             p("    // apex is routed separately above: `*.example.com` does NOT match");
             p("    // `example.com`, so without a `hosts` entry the apex would 404.");
             p(`    { "pattern": ${JSON.stringify(`${tenancy.hostPattern}/*`)}, "zone_name": ${JSON.stringify(tenancyZone(tenancy))} },`);
@@ -146,7 +146,7 @@ export function generateAstroidWrangler(config) {
         p("  },");
         p("  // A DO class needs a migration tag. `new_sqlite_classes` (NOT");
         p("  // `new_classes`) because the session keeps its authoritative state in");
-        p("  // `ctx.storage`, which is the SQLite-backed store — and the storage");
+        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(`    { "tag": ${JSON.stringify(ASTROID_REALTIME_MIGRATION_TAG)}, "new_sqlite_classes": [${JSON.stringify(ASTROID_EDIT_SESSION_CLASS)}] }`);
@@ -164,7 +164,7 @@ export function generateAstroidWrangler(config) {
         const { queue, dlq } = astroidQueueNames(config);
         p("  // Provider webhooks are verified at the edge, then enqueued here so the");
         p("  // receiver can return fast. Retries + DLQ routing are Cloudflare's, not");
-        p("  // the consumer's — set them here, not in code.");
+        p("  // the consumer's—set them here, not in code.");
         p(`  // Create both: \`wrangler queues create ${queue}\` and \`… ${dlq}\`.`);
         p('  "queues": {');
         p(`    "producers": [{ "queue": ${JSON.stringify(queue)}, "binding": ${JSON.stringify(ASTROID_QUEUE_BINDING)} }],`);
@@ -197,17 +197,17 @@ export function generateAstroidWrangler(config) {
     p('  "images": { "binding": "IMAGES" },');
     p("  // Analytics Engine: real-visitor Core Web Vitals. Free, and the ingest");
     p("  // route accepts-and-drops without it, so it costs nothing unused. Reading");
-    p("  // the p75 back out needs CF_ACCOUNT_ID + CF_API_TOKEN (see .env.example) —");
+    p("  // the p75 back out needs CF_ACCOUNT_ID + CF_API_TOKEN (see .env.example)—");
     p("  // until those are real the Health badge reads 'not measured yet'.");
     p(`  "analytics_engine_datasets": [{ "binding": ${JSON.stringify(ASTROID_VITALS_BINDING)}, "dataset": ${JSON.stringify(astroidVitalsDataset(config))} }],`);
     p("  // Workers AI. Powers the editor's rewrite + SEO-suggest buttons and alt-text");
-    p("  // generation on upload — all of which SHIP IN THE EDITOR DRAWER already and,");
+    p("  // generation on upload—all of which SHIP IN THE EDITOR DRAWER already and,");
     p("  // without this binding, were permanently invisible: their routes answer 503");
     p("  // and the client hides the button. No account setup beyond the binding, and");
     p("  // every call is editor-gated, so a visitor can never spend your AI budget.");
     p('  "ai": { "binding": "AI" },');
     p("  // KV: RL = the security rate limiter (it also holds the daily site-health");
-    p("  // summary under its own key — one small singleton blob, not worth a binding");
+    p("  // summary under its own key—one small singleton blob, not worth a binding");
     p("  // someone has to remember to provision); DRAFTS = the autosave write-buffer.");
     p("  // Create each: `wrangler kv namespace create <RL|DRAFTS>`.");
     p('  "kv_namespaces": [');
@@ -221,7 +221,7 @@ export function generateAstroidWrangler(config) {
     // sign-in was impossible on every DEPLOYED site, while every local build
     // and every CI scaffold passed. Nothing in this repo runs a deployed scaffold,
     // which is why it survived.
-    p("  // Cloudflare Email Sending — magic-link sign-in + inquiry notifications.");
+    p("  // Cloudflare Email Sending—magic-link sign-in + inquiry notifications.");
     p("  // Sign-in DEPENDS on this: in production the magic link is emailed, not logged.");
     p("  // Enable Email Sending for your zone, then verify the address in MAIL_FROM.");
     p('  "send_email": [{ "name": "EMAIL" }],');
@@ -239,7 +239,7 @@ export function generateAstroidWrangler(config) {
     p("    // Turn it on for a PREVIEW deploy first and walk the activation runbook");
     p("    // (docs/adr/0004-edge-caching.md). `caches.default` is not cleared by");
     p("    // Cloudflare Dev Mode or Purge Everything, so a bad prod flip is hard to");
-    p("    // undo — this feature was reverted twice for exactly that.");
+    p("    // undo—this feature was reverted twice for exactly that.");
     p('    "ASTROID_EDGE_CACHE": "false",');
     for (const v of astroidCheckoutVars(config)) {
         // Public, not secret—the app id ships to the browser to mount the card
@@ -255,7 +255,7 @@ export function generateAstroidWrangler(config) {
     // is generated from the same declaration the runtime dormancy gate reads.
     const secretNames = commerceSecretNames(config.commerce);
     if (secretNames.length > 0) {
-        p("  // Commerce secrets — set OUTSIDE this file (it's committed):");
+        p("  // Commerce secrets—set OUTSIDE this file (it's committed):");
         p("  //   local:    .dev.vars (see .env.example, seeded with DUMMY_REPLACE_ME)");
         p("  //   deployed: `wrangler secret put <NAME>`, or a Secrets Store binding");
         p("  // Until each is real, commerce stays dormant: the D1 mirror serves, the");

package/dist/project/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./generate.js";
 export * from "./actions.js";
 export * from "./scaffold.js";
+export * from "./seed.js";

package/dist/project/index.js

@@ -5,3 +5,4 @@
 export * from "./generate.js";
 export * from "./actions.js";
 export * from "./scaffold.js";
+export * from "./seed.js";

package/dist/project/scaffold.js

@@ -37,6 +37,51 @@ import { generateAstroidEditSession } from "../realtime/scaffold.js";
 import { generatePwaHeaders, generateServiceWorker, generateWebManifest, resolvePwa, } from "../pwa/generate.js";
 import { astroidUsesQueues } from "../queues/messages.js";
 import { generateAstroidQueueSeam, generateAstroidWebhookRoutes } from "../queues/scaffold.js";
+/** `src/pages-hooks.ts`—the site's pages-route hooks, scaffolded once. */
+function generateAstroidPagesHooks() {
+    return [
+        "// The pages route's site-owned hooks. The generated worker passes",
+        "// `pagesHooks` to astroidPagesWriteHooks, which runs your `transform` before",
+        "// Astroid's own section sanitize and validate. Scaffolded once and yours to",
+        "// edit.",
+        "//",
+        "// `transform` gets the allowlisted fields of a write and returns what to",
+        "// store: normalize the slug, clamp a title, fill a new page's defaults.",
+        "// `validate` rejects a write by throwing a LouiseValidationError (a 422).",
+        "// `reservedSlugs` adds to the paths no page may take (ASTROID_RESERVED_SLUGS),",
+        "// such as one of your own file routes.",
+        'import type { AstroidPagesHooks } from "astroidjs";',
+        "",
+        "export const pagesHooks: AstroidPagesHooks = {",
+        "  reservedSlugs: [],",
+        "};",
+        "",
+    ].join("\n");
+}
+/** `src/settings-hooks.ts`—the site's settings sanitizers, scaffolded once. */
+function generateAstroidSettingsHooks() {
+    return [
+        "// The Settings panel's sanitize + read hooks. The generated worker spreads",
+        "// `settingsHooks` into its settingsRoute call, and src/actions/index.ts",
+        "// passes `sanitize` to the settings Action, so both write paths clean a value",
+        "// the same way. Scaffolded once and yours to edit.",
+        "//",
+        "// `sanitize` maps a settings key to a function that returns the value to",
+        "// store. It runs before the link-scheme and media-URL checks, and only on",
+        "// keys the allowlist (settings.columns + settings.customKeys) already accepts.",
+        "// `read` transforms the merged settings on GET, for example to fill keys an",
+        "// older row lacks from your defaults.",
+        'import type { SettingsRouteHooks } from "louise-toolkit/editor";',
+        "",
+        "export const settingsHooks: SettingsRouteHooks = {",
+        "  sanitize: {",
+        "    // For example, trim and cap a headline:",
+        '    // heroHeadline: (v) => (typeof v === "string" ? v.trim().slice(0, 120) : ""),',
+        "  },",
+        "};",
+        "",
+    ].join("\n");
+}
 /**
  * Every scaffold-once file this config implies.
  *
@@ -68,15 +113,26 @@ export function generateAstroidScaffoldFiles(config) {
     files.push({
         path: "src/schema.site.ts",
         contents: [
-            "// Site-owned Drizzle tables — the ones Astroid doesn't manage. Declare them",
+            "// Site-owned Drizzle tables—the ones Astroid doesn't manage. Declare them",
             "// 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", { … });',
+            '// For example: export const redirects = sqliteTable("redirects", { … });',
             "export {};",
             "",
         ].join("\n"),
     });
+    // --- pages: the transform + reserved-slugs seam ---------------------------
+    if (config.pages?.hooks) {
+        files.push({ path: "src/pages-hooks.ts", contents: generateAstroidPagesHooks() });
+    }
+    // --- settings: the sanitize + read seam ------------------------------------
+    // Only when asked for (settings.hooks): the generated worker and the Actions
+    // surface both import it, so it must exist whenever either does. Scaffolded
+    // empty, which leaves the route exactly as it is without hooks.
+    if (config.settings?.hooks) {
+        files.push({ path: "src/settings-hooks.ts", contents: generateAstroidSettingsHooks() });
+    }
     // --- the typed Astro Actions surface --------------------------------------
     // Always: every project has editable pages, and the routes alone leave the
     // Astro-native half of ADR 0001 unbuilt. Scaffold-once because it is meant to

package/dist/project/seed.d.ts

@@ -0,0 +1,22 @@
+import type { AstroidConfig, SectionKind } from "../config.js";
+/** A stored section item: its `_type`, field values, and settings tokens. */
+export interface AstroidSeedSection {
+    _type: SectionKind;
+    _settings?: Record<string, string>;
+    [field: string]: unknown;
+}
+/**
+ * The sections a new project's home page starts with: the config's `sections`,
+ * or its archetype's default when the config doesn't list any, each with
+ * sample content.
+ */
+export declare function astroidHomeSeedSections(config: AstroidConfig): AstroidSeedSection[];
+/**
+ * `seed/home.seed.sql`: one idempotent insert of the published `home` page,
+ * with the sections from {@link astroidHomeSeedSections}.
+ *
+ * Every value is escaped here, so a brand name with an apostrophe produces
+ * valid SQL. The template's token substitution can't escape, which is why the
+ * seed isn't a template file.
+ */
+export declare function generateAstroidHomeSeed(config: AstroidConfig): string;

package/dist/project/seed.js

@@ -0,0 +1,214 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The home page a new project seeds, built from its own config.
+//
+// This used to be a fixed file in the `create-astroid` template, and it seeded
+// the marketing sections (`hero`, `featureGrid`, `cta`) for every archetype. A
+// portfolio's config listed `hero`, `gallery`, `aboutIntro`, and `contact`, but
+// its first page showed a feature grid and a call to action instead. Building
+// the seed from the same section list the config holds means the two can't
+// disagree.
+//
+// It isn't in `generateAstroidScaffoldFiles`, on purpose: a seed runs once,
+// against a fresh database, so `astroid generate` has no reason to write it
+// back into a project that deleted it.
+import { ASTROID_ARCHETYPE_SECTIONS } from "../config.js";
+/**
+ * Sample content for every section kind, keyed by `SectionKind`.
+ *
+ * A `Record` over the whole vocabulary rather than just the kinds an archetype
+ * uses today, so adding a section to the catalog is a compile error here until
+ * it has a sample. That keeps a site's `sections` override seedable, whatever
+ * it lists.
+ *
+ * The copy tells the owner how to replace it, because it's the first thing they
+ * see after signing in. Images are left empty: a new project has no media, and
+ * every section with an image renders without one.
+ */
+const SAMPLES = {
+    hero: (brand) => ({
+        heading: brand,
+        subheading: "Sign in, switch on edit mode, and type to change this text.",
+        ctaLabel: "Get in touch",
+        ctaHref: "/contact",
+        _settings: { colorway: "base", align: "center" },
+    }),
+    featureGrid: () => ({
+        heading: "What you offer",
+        items: [
+            { title: "First thing", body: "Describe it here." },
+            { title: "Second thing", body: "And this one." },
+            { title: "Third thing", body: "And this one too." },
+        ],
+        _settings: { colorway: "base" },
+    }),
+    cta: () => ({
+        heading: "Ready when you are",
+        body: "Replace this copy with your own.",
+        ctaLabel: "Contact us",
+        ctaHref: "/contact",
+        _settings: { colorway: "brand", align: "center" },
+    }),
+    gallery: () => ({
+        heading: "Selected work",
+        items: [],
+        _settings: { colorway: "base" },
+    }),
+    media: () => ({
+        heading: "A closer look",
+        _settings: { colorway: "base" },
+    }),
+    splitImage: () => ({
+        heading: "Tell your story",
+        body: "<p>Add an image and a few sentences about what makes this place yours.</p>",
+        _layout: "imageStart",
+        _settings: { colorway: "base" },
+    }),
+    steps: () => ({
+        heading: "How it works",
+        items: [
+            { title: "Get in touch", body: "Say what you need." },
+            { title: "Plan it together", body: "Agree on the details." },
+            { title: "Done", body: "Describe the result here." },
+        ],
+        _settings: { colorway: "base" },
+    }),
+    banner: () => ({
+        text: "Announce something here, like new hours or a seasonal special.",
+        _settings: { colorway: "brand", align: "center" },
+    }),
+    faq: () => ({
+        heading: "Questions",
+        items: [
+            { question: "What's the first question people ask?", answer: "<p>Answer it here.</p>" },
+            { question: "And the second?", answer: "<p>Answer that one here.</p>" },
+        ],
+        _settings: { colorway: "base" },
+    }),
+    pricingTiers: () => ({
+        heading: "Pricing",
+        items: [
+            {
+                name: "Starter",
+                price: "$10",
+                period: "/mo",
+                features: [{ text: "Describe what's included" }],
+                featured: "no",
+            },
+            {
+                name: "Plus",
+                price: "$20",
+                period: "/mo",
+                features: [{ text: "Everything in Starter" }, { text: "And more" }],
+                featured: "yes",
+            },
+        ],
+        _settings: { colorway: "base" },
+    }),
+    testimonial: () => ({
+        quote: "Put a favorite thing a customer said about you here.",
+        attribution: "Alex",
+        role: "Customer",
+        _settings: { colorway: "base", align: "center" },
+    }),
+    aboutIntro: (brand) => ({
+        heading: `About ${brand}`,
+        body: "<p>Say who you are, what you make, and why it matters to you.</p>",
+        _settings: { colorway: "base" },
+    }),
+    productGrid: () => ({
+        heading: "Featured",
+        items: [
+            { name: "First product", price: "$12" },
+            { name: "Second product", price: "$18" },
+            { name: "Third product", price: "$24" },
+        ],
+        _settings: { colorway: "base" },
+    }),
+    locationHours: () => ({
+        heading: "Visit",
+        address: "Your street address\nCity, region, and postal code",
+        phone: "800-555-0100",
+        items: [
+            { day: "Monday to Friday", hours: "8 AM to 6 PM" },
+            { day: "Saturday and Sunday", hours: "9 AM to 4 PM" },
+        ],
+        _settings: { colorway: "base" },
+    }),
+    contact: () => ({
+        heading: "Get in touch",
+        blurb: "Questions, orders, or just saying hello: send a message.",
+        _settings: { colorway: "secondary" },
+    }),
+};
+/**
+ * The sections a new project's home page starts with: the config's `sections`,
+ * or its archetype's default when the config doesn't list any, each with
+ * sample content.
+ */
+export function astroidHomeSeedSections(config) {
+    const kinds = config.sections ?? ASTROID_ARCHETYPE_SECTIONS[config.archetype];
+    return kinds.map((kind) => ({ _type: kind, ...SAMPLES[kind](config.theme.name) }));
+}
+/** A SQLite string literal. Doubling `'` is the only escape SQLite needs. */
+function sqlString(value) {
+    return `'${value.replaceAll("'", "''")}'`;
+}
+/**
+ * `seed/home.seed.sql`: one idempotent insert of the published `home` page,
+ * with the sections from {@link astroidHomeSeedSections}.
+ *
+ * Every value is escaped here, so a brand name with an apostrophe produces
+ * valid SQL. The template's token substitution can't escape, which is why the
+ * seed isn't a template file.
+ */
+export function generateAstroidHomeSeed(config) {
+    const brand = config.theme.name;
+    const sections = JSON.stringify(astroidHomeSeedSections(config), null, 2);
+    const body = `<p>Welcome to ${escapeHtml(brand)}. Sign in at <code>/login</code>, switch on edit mode, and change this text in place, then select Publish.</p>`;
+    return [
+        "-- Seed the editable home page (slug `home`) that src/pages/index.astro renders.",
+        "-- Idempotent. Apply once after migrations:",
+        "--   wrangler d1 execute DB --file seed/home.seed.sql --remote",
+        "--   (drop --remote for the local dev D1)",
+        "--",
+        "-- `sections` is the page-builder array: the same shape the on-canvas editor",
+        "-- reads and the server validates against the section catalog on write. Each item",
+        '-- is `{"_type": …, …fields, "_settings": {…}}`, and `_settings` holds TOKENS',
+        "-- (colorway, align), never CSS, so a re-theme needs no content change. The list",
+        "-- matches `sections` in astroid.config.ts.",
+        "--",
+        "-- Seeding it is deliberate: an empty array renders an empty page, and a blank",
+        "-- canvas is a worse first run than having something real to click on and edit.",
+        "--",
+        "-- Full-text search (the editor's Pages search) is kept in sync on PUBLISH, so a",
+        "-- row inserted with raw SQL like this isn't in the index until you either",
+        "-- publish an edit to it or backfill once with `POST /api/louise/pages/reindex`",
+        "-- (signed in). The page renders fine either way; only in-editor search is",
+        "-- affected.",
+        "--",
+        "-- To override just the <head> title and description (not the on-page H1), add",
+        "-- `seo_title` and `seo_description` columns below. `seo_title` is run through the",
+        "-- config's title template, which already appends the brand, so set the page",
+        '-- part only ("Pricing"), not "Pricing | Your brand".',
+        "INSERT OR IGNORE INTO pages (slug, title, body, sections, status, sort_order, created_at, updated_at)",
+        "VALUES (",
+        "  'home',",
+        `  ${sqlString(brand)},`,
+        `  ${sqlString(body)},`,
+        `  json(${sqlString(sections)}),`,
+        "  'published',",
+        "  0,",
+        "  unixepoch(),",
+        "  unixepoch()",
+        ");",
+        "",
+    ].join("\n");
+}
+function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;");
+}

package/dist/pwa/generate.js

@@ -111,11 +111,11 @@ export function generateServiceWorker(config) {
     return [
         `// Service worker for the ${config.theme.name} PWA, scoped to ${pwa.scope}.`,
         "//",
-        "// Generated by Astroid. Safe to edit — bump CACHE to invalidate everything",
+        "// Generated by Astroid. Safe to edit—bump CACHE to invalidate everything",
         "// on the next visit.",
         "//",
         "// What it deliberately never caches, and why:",
-        "//   /api/*        checkout, auth, and every Louise write — a cached POST",
+        "//   /api/*        checkout, auth, and every Louise write—a cached POST",
         "//                 response or a stale session is worse than being offline",
         "//   editor routes the studio must always be live",
         "//   ?louise URLs  an edit-mode request; caching one would serve an editor a",
@@ -126,8 +126,8 @@ export function generateServiceWorker(config) {
         ...(pwa.offlineFallback
             ? [
                 "// A prerendered page with no session-specific markup. The scope root is",
-                "// the app SHELL, which on an auth-gated app is `Cache-Control: no-store`",
-                "// — so falling back to it serves either nothing or someone else's shell.",
+                "// the app SHELL, which on an auth-gated app is `Cache-Control: no-store`—",
+                "// so falling back to it serves either nothing or someone else's shell.",
                 `const OFFLINE = ${JSON.stringify(pwa.offlineFallback)};`,
             ]
             : []),
@@ -165,7 +165,7 @@ export function generateServiceWorker(config) {
         "  );",
         "}",
         "",
-        "/** Hashed build output — the filename changes when the content does, so it",
+        "/** Hashed build output—the filename changes when the content does, so it",
         " *  can be cached forever without a staleness risk. */",
         "function isImmutable(url) {",
         "  return url.pathname.startsWith('/_astro/') || url.pathname.startsWith('/icons/');",
@@ -181,7 +181,7 @@ export function generateServiceWorker(config) {
         "  // Cross-origin requests belong to whoever serves them.",
         "  if (url.origin !== self.location.origin) return;",
         "  if (isDynamic(url)) return;",
-        "  // Outside the scope this worker has no business intercepting — the rest of",
+        "  // Outside the scope this worker has no business intercepting—the rest of",
         "  // the site is CMS-edited and must stay live.",
         "  if (SCOPE !== '/' && !url.pathname.startsWith(SCOPE)) return;",
         "",
@@ -245,7 +245,7 @@ export function generatePwaHeaders(config) {
     return [
         "",
         "# The service worker must revalidate on every load, or a bad worker sticks",
-        "# around until its cache entry expires — and it controls every page in scope.",
+        "# around until its cache entry expires—and it controls every page in scope.",
         `${base}/sw.js`,
         "  Cache-Control: no-cache",
         "",

package/dist/queues/scaffold.js

@@ -36,7 +36,7 @@ const PROVIDERS = {
         // 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.",
+        note: "Stripe's signature is timestamped—the verifier rejects replays outside a 5-minute tolerance.",
     },
     fourthwall: {
         module: "louise-toolkit/commerce/fourthwall",
@@ -61,7 +61,7 @@ export function generateAstroidEnvBindings(config) {
     if (providers.length === 0)
         return "";
     return [
-        "  /** Queue producer — verified webhooks + the cron re-sync (src/queue.ts). */",
+        "  /** 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
@@ -97,15 +97,15 @@ export function generateAstroidQueueSeam(config) {
     // in rather than leaving it to be discovered on a busy day (#294).
     const multiProvider = astroidCommerceProviders(config.commerce).length > 1;
     return [
-        "// The queue consumer — what each message actually does.",
+        "// 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",
+        "// 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";',
         "",
@@ -118,7 +118,7 @@ export function generateAstroidQueueSeam(config) {
             ? [
                 `    // This project runs more than one commerce provider, and the catalog is`,
                 `    // ${provider}'s. Scoping the refresh keeps the OTHER provider's webhooks from`,
-                `    // triggering it — Square alone emits an inventory event on every sale, which`,
+                `    // triggering it—Square alone emits an inventory event on every sale, which`,
                 `    // unscoped would re-sync ${provider} once per transaction.`,
                 `    catalogProvider: ${JSON.stringify(provider)},`,
             ]
@@ -143,7 +143,7 @@ export function generateAstroidQueueSeam(config) {
                 "      // takes `retry: { attempts: 3 }`, backing off on 429/5xx inside every",
                 "      // verb. It is off by default because a checkout route has a customer",
                 "      // watching a spinner, and there a fast failure beats a slow one. Here",
-                "      // the opposite holds — a catalog push that gives up halfway is worse.",
+                "      // the opposite holds—a catalog push that gives up halfway is worse.",
             ]
             : [
                 "      // Nobody is watching this run, so ask for backoff on 429/5xx wherever",
@@ -158,7 +158,7 @@ export function generateAstroidQueueSeam(config) {
         "      // 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.",
+        "      // Partial failures don't throw—that's what `r.failed` above is for.",
         "      void env;",
         "    },",
         "  })(message);",
@@ -194,7 +194,7 @@ export function generateAstroidWebhookRoute(config, forProvider) {
         `// ${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",
+        "// 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";',

package/dist/realtime/scaffold.js

@@ -54,7 +54,7 @@ export function generateAstroidEditSession(config) {
     return [
         "// The per-page live editing session Durable Object (ADR 0002 / #71).",
         "//",
-        "// Scaffolded once and yours to edit — `persist` in particular. What should NOT",
+        "// 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",
@@ -91,7 +91,7 @@ export function generateAstroidEditSession(config) {
         "        // 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 —",
+        "        // 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",
@@ -105,8 +105,8 @@ export function generateAstroidEditSession(config) {
         "          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",
+        "        // 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(",

package/dist/schema/collections.d.ts

@@ -37,12 +37,43 @@ export declare function assertAstroidPageSections(config: AstroidConfig, data: R
  *
  *   pagesRoute({ table: pages, resolveEditor, fields, ...astroidPagesWriteHooks(config) })
  */
-export declare function astroidPagesWriteHooks(config: AstroidConfig): {
+/** The write context `pagesRoute` passes to a transform or validator. */
+export interface AstroidPagesWriteContext {
+    operation: "create" | "update";
+}
+/**
+ * A site's own `pagesRoute` hooks, exported as `pagesHooks` from the
+ * scaffold-once `src/pages-hooks.ts` when `pages.hooks` is on.
+ */
+export interface AstroidPagesHooks {
+    /**
+     * Clean a page write before Astroid's section sanitize and validate run, for
+     * example to normalize the slug, clamp a title, or fill a new page's defaults.
+     * It gets only the allowlisted fields of the write.
+     */
+    transform?: (data: Record<string, unknown>, ctx: AstroidPagesWriteContext) => Record<string, unknown> | Promise<Record<string, unknown>>;
+    /**
+     * Reject a write, after both transforms and before Astroid's own section
+     * validation. Throw a `LouiseValidationError` for a 422 with per-field
+     * violations, for example when a required field is empty.
+     */
+    validate?: (data: Record<string, unknown>, ctx: AstroidPagesWriteContext) => void | Promise<void>;
+    /** Slugs to refuse on top of {@link ASTROID_RESERVED_SLUGS}, such as a path
+     *  a site's own file route serves. */
+    reservedSlugs?: Iterable<string>;
+}
+/**
+ * Slugs no page may take, on any site. Each one is a path Astro, Cloudflare,
+ * or Astroid serves before the catch-all page route, so a page saved under it
+ * would be unreachable, and nothing would say why. `pagesRoute` refuses them
+ * with a 422 instead.
+ */
+export declare const ASTROID_RESERVED_SLUGS: readonly string[];
+export declare function astroidPagesWriteHooks(config: AstroidConfig, site?: AstroidPagesHooks): {
     sanitize: (html: string) => string;
-    transform: (data: Record<string, unknown>) => Record<string, unknown>;
-    validate: (data: Record<string, unknown>, ctx: {
-        operation: "create" | "update";
-    }) => Promise<void>;
+    transform: (data: Record<string, unknown>, ctx: AstroidPagesWriteContext) => Promise<Record<string, unknown>>;
+    validate: (data: Record<string, unknown>, ctx: AstroidPagesWriteContext) => Promise<void>;
+    reservedSlugs: string[];
 };
 export declare function astroidPagesCollection(config: AstroidConfig): CollectionConfig;
 /**