astroidjs 0.1.1 → 0.2.0

package/dist/project/actions.js

@@ -0,0 +1,106 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// `src/actions/index.ts` — the Astro-native, typed mutation surface (ADR 0001
+// layer 2), beside the framework-agnostic `/api/louise/*` routes.
+//
+// Astroid generated only the route half. That is not a missing convenience: the
+// two entrypoints write the SAME rows, and the whole reason `louise-toolkit/astro`
+// exposes these factories is that each one shares the raw route's store path —
+// `applyFieldSave`, `applySettingsPatch`, `applySaveDraft`. A project that wired
+// its own Actions by hand would get a second write path, and a second write path
+// is where validation, sanitization, and draft-merge semantics drift apart
+// silently (#138).
+//
+// So this file is SCAFFOLD-ONCE and is meant to be added to — the reference site
+// keeps its own bespoke actions right beside these — but the three below come
+// pre-wired against the same tables and the same collection config the generated
+// worker uses.
+/** `src/actions/index.ts` — the typed mutation surface, scaffolded once. */
+export function generateAstroidActions(_config) {
+    return [
+        "// The typed Astro Actions surface — ADR 0001 layer 2.",
+        "//",
+        "// Scaffolded once and yours to ADD to: put your own `defineAction`s in the",
+        "// `server` object below, alongside these.",
+        "//",
+        "// What matters about the three that ship here is that they are NOT a second",
+        "// implementation. Each factory shares the store path of its raw",
+        "// `/api/louise/*` counterpart (`applyFieldSave`, `applySettingsPatch`,",
+        "// `applySaveDraft`), so a field is validated once and written in exactly one",
+        "// place however it was called. Hand-rolling an Action that writes the same",
+        "// row is how sanitization and draft-merge semantics drift apart without",
+        "// anything failing.",
+        'import { ActionError, defineAction } from "astro:actions";',
+        'import { env } from "cloudflare:workers";',
+        "import {",
+        "  louiseSaveAction,",
+        "  louiseSaveDraftAction,",
+        "  louiseSettingsAction,",
+        '} from "louise-toolkit/astro";',
+        "import {",
+        "  ASTROID_SETTINGS_COLUMNS,",
+        "  ASTROID_SETTINGS_IMAGE_KEYS,",
+        "  astroidPagesCollection,",
+        '} from "astroidjs";',
+        'import astroidConfig from "../../astroid.config.js";',
+        'import { pages, pagesVersions, siteSettings } from "../schema.js";',
+        "",
+        "const pagesCollection = astroidPagesCollection(astroidConfig);",
+        "",
+        "// Astro v6+ removed `Astro.locals.runtime.env`, so the bindings are resolved",
+        "// from `cloudflare:workers` — the same env the raw routes read.",
+        "const getEnv = () => env as unknown as CloudflareEnv;",
+        "",
+        "// `getEditor` is left to its default (`locals.editor`), which the generated",
+        "// middleware sets for a signed-in editor. A falsy result answers 401, so these",
+        "// carry the same gate as the routes rather than a parallel one.",
+        "const deps = { ActionError, getEnv };",
+        "",
+        "export const server = {",
+        "  louise: {",
+        "    // Inline field save (title, SEO) — the live, non-versioned path.",
+        "    save: defineAction(",
+        "      louiseSaveAction({",
+        "        ...deps,",
+        "        collections: {",
+        "          pages: {",
+        "            table: pages,",
+        '            fields: ["title", "seoTitle", "seoDescription"],',
+        "          },",
+        "        },",
+        "      }),",
+        "    ),",
+        "",
+        "    // The versioned body/sections save — stages a DRAFT, exactly as",
+        "    // versionsRoute does, through the same `applySaveDraft`.",
+        "    saveDraft: defineAction(",
+        "      louiseSaveDraftAction({",
+        "        ...deps,",
+        "        table: pages,",
+        "        versionsTable: pagesVersions,",
+        "        config: pagesCollection,",
+        "        // The same KV write-buffer the route uses. Both entrypoints coalesce",
+        "        // through one buffer, so an autosave burst is one D1 write however",
+        "        // the client happened to call in.",
+        "        bufferKv: (e) => e.DRAFTS,",
+        "      }),",
+        "    ),",
+        "",
+        "    // The Settings-panel patch (brand, nav, contact, SEO defaults).",
+        "    settings: defineAction(",
+        "      louiseSettingsAction({",
+        "        ...deps,",
+        "        table: siteSettings,",
+        "        // The SAME allowlist the generated worker enforces, imported rather",
+        "        // than copied — a second literal here is a list that drifts from the",
+        "        // one the routes check against, and nothing would fail when it did.",
+        "        columns: ASTROID_SETTINGS_COLUMNS,",
+        "        imageKeys: ASTROID_SETTINGS_IMAGE_KEYS,",
+        '        mediaBase: astroidConfig.deploy?.mediaBase ?? "/media",',
+        "      }),",
+        "    ),",
+        "  },",
+        "};",
+        "",
+    ].join("\n");
+}

package/dist/project/generate.d.ts

@@ -12,6 +12,21 @@ export interface GeneratedFile {
  * once files (wrangler.jsonc, astro.config, auth.ts) are NOT here by design.
  */
 export declare function generateAstroidProject(config: AstroidConfig): GeneratedFile[];
+/**
+ * The module-secret block `create-astroid` substitutes into `.env.example`.
+ *
+ * Every name is seeded with the placeholder sentinel rather than left empty,
+ * which is the whole trick behind a scaffold that runs with no accounts: the
+ * bindings all EXIST and all read as unconfigured, so each module takes its
+ * dormant path deliberately instead of hitting an undefined-binding error. The
+ * names come from {@link commerceSecretNames}, the same declaration the runtime
+ * gate and the generated `env.d.ts` read.
+ *
+ * Empty string when the project enables no module that needs credentials — the
+ * core secrets (session, Turnstile, mail) are already in the template file, with
+ * their own prose.
+ */
+export declare function generateAstroidSecretsEnv(config: AstroidConfig): string;
 /**
  * Generate a floor `wrangler.jsonc` from the config: the Worker name + editable
  * bindings a baseline Louise site needs (D1, R2 media, the rate-limit + autosave

package/dist/project/generate.js

@@ -14,6 +14,13 @@
 //      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 { astroidCheckoutVars } from "../commerce/checkout-scaffold.js";
+import { astroidCommerceProviders } from "../commerce/roles.js";
+import { COMMERCE_PROVIDER_SECRETS, COMMERCE_PROVIDER_SETUP, commerceSecretNames, } from "../commerce/secrets.js";
+import { ASTROID_QUEUE_BINDING, astroidCron, astroidCrons, astroidQueueNames, astroidUsesQueues, } from "../queues/messages.js";
+import { ASTROID_EDIT_SESSION_CLASS, ASTROID_REALTIME_BINDING, ASTROID_REALTIME_MIGRATION_TAG, usesRealtime, } from "../realtime/scaffold.js";
+import { ASTROID_SECRET_PLACEHOLDER } from "../secrets.js";
 import { generateAstroidSchema } from "../schema/generate.js";
 import { generateAstroidMiddleware, generateAstroidWorker } from "../worker/generate.js";
 /**
@@ -29,6 +36,43 @@ export function generateAstroidProject(config) {
         { path: "src/middleware.ts", contents: generateAstroidMiddleware(config) },
     ];
 }
+/**
+ * The module-secret block `create-astroid` substitutes into `.env.example`.
+ *
+ * Every name is seeded with the placeholder sentinel rather than left empty,
+ * which is the whole trick behind a scaffold that runs with no accounts: the
+ * bindings all EXIST and all read as unconfigured, so each module takes its
+ * dormant path deliberately instead of hitting an undefined-binding error. The
+ * names come from {@link commerceSecretNames}, the same declaration the runtime
+ * gate and the generated `env.d.ts` read.
+ *
+ * Empty string when the project enables no module that needs credentials — the
+ * core secrets (session, Turnstile, mail) are already in the template file, with
+ * their own prose.
+ */
+export function generateAstroidSecretsEnv(config) {
+    const providers = astroidCommerceProviders(config.commerce);
+    if (providers.length === 0)
+        return "";
+    const lines = [
+        "",
+        "# --- commerce -------------------------------------------------------------",
+        "#",
+        "# Seeded with the DUMMY_REPLACE_ME sentinel, which reads as NOT CONFIGURED.",
+        "# Commerce is dormant until every value below is real: the D1 catalog mirror",
+        "# still serves whatever it last synced, the webhook receiver answers 503 (so",
+        "# the provider retries rather than dropping events), and checkout is",
+        "# simulated. Nothing calls the provider with a placeholder credential.",
+    ];
+    for (const provider of providers) {
+        const spec = COMMERCE_PROVIDER_SECRETS[provider];
+        lines.push("#", `# ${provider}: ${COMMERCE_PROVIDER_SETUP[provider]}`);
+        for (const name of [...spec.credentials, spec.webhook]) {
+            lines.push(`${name}=${ASTROID_SECRET_PLACEHOLDER}`);
+        }
+    }
+    return lines.join("\n");
+}
 // Pinned compatibility date for the emitted Worker. A literal (Astroid's
 // generators are pure — no `Date.now()`), bumped deliberately when the runtime
 // baseline moves; matches the reference site's wrangler.jsonc.
@@ -73,6 +117,50 @@ export function generateAstroidWrangler(config) {
         p("  // No `hosts` in your config → deploys to <name>.workers.dev. Add a");
         p('  // "routes" block with a custom_domain pattern to serve a real domain.');
     }
+    if (usesRealtime(config)) {
+        // The per-page live editing session (ADR 0002). Two halves, and BOTH are
+        // required — a binding with no migration is a deploy error, and the class
+        // must also be exported from the worker entry (the generated src/worker.ts
+        // re-exports it) or wrangler can't resolve `class_name`.
+        p("  // Durable Object: the per-page live editing session (realtime module).");
+        p('  "durable_objects": {');
+        p(`    "bindings": [{ "name": ${JSON.stringify(ASTROID_REALTIME_BINDING)}, "class_name": ${JSON.stringify(ASTROID_EDIT_SESSION_CLASS)} }]`);
+        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("  // 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)}] }`);
+        p("  ],");
+    }
+    // Crons. ONE `scheduled` handler receives all of them and tells them apart by
+    // `controller.cron`, so this list and the handler's dispatch must agree
+    // exactly — both come from `astroidCrons`, which is why it exists.
+    //
+    // Daily: the site-health scan (broken links, missing alt text, SEO gaps).
+    // Hourly (commerce only): the catalog re-sync safety net, so a missed or DLQ'd
+    // webhook can only leave the site stale until the next tick.
+    p(`  "triggers": { "crons": ${JSON.stringify(astroidCrons(config))} },`);
+    if (astroidUsesQueues(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(`  // Create both: \`wrangler queues create ${queue}\` and \`… ${dlq}\`.`);
+        p('  "queues": {');
+        p(`    "producers": [{ "queue": ${JSON.stringify(queue)}, "binding": ${JSON.stringify(ASTROID_QUEUE_BINDING)} }],`);
+        p('    "consumers": [');
+        p("      {");
+        p(`        "queue": ${JSON.stringify(queue)},`);
+        p(`        "max_batch_size": ${config.queues?.maxBatchSize ?? 10},`);
+        p(`        "max_batch_timeout": ${config.queues?.maxBatchTimeout ?? 30},`);
+        p(`        "max_retries": ${config.queues?.maxRetries ?? 5},`);
+        p(`        "dead_letter_queue": ${JSON.stringify(dlq)},`);
+        p("      },");
+        p("    ],");
+        p("  },");
+    }
     p("  // D1 holds pages / site_settings / media / inquiries (schema in src/schema.ts,");
     p("  // migrations in ./migrations). Create it: `wrangler d1 create <name>`.");
     p('  "d1_databases": [');
@@ -89,20 +177,74 @@ export function generateAstroidWrangler(config) {
     p("  // Cloudflare Images: the media route reads upload dimensions + backs server-");
     p("  // side re-encode. Also @astrojs/cloudflare's production image service.");
     p('  "images": { "binding": "IMAGES" },');
-    p("  // KV: RL = the security rate limiter; DRAFTS = the autosave write-buffer.");
+    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("  // 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("  // 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("  // someone has to remember to provision); DRAFTS = the autosave write-buffer.");
     p("  // Create each: `wrangler kv namespace create <RL|DRAFTS>`.");
     p('  "kv_namespaces": [');
     p('    { "binding": "RL", "id": "<run: wrangler kv namespace create RL>" },');
     p('    { "binding": "DRAFTS", "id": "<run: wrangler kv namespace create DRAFTS>" },');
     p("  ],");
+    // Email Sending. NOT optional decoration: `src/env.d.ts` declares EMAIL as a
+    // required member, and Better Auth's magic-link path console-logs the link in
+    // dev but calls `env.EMAIL.send(...)` unconditionally in production. Without
+    // this binding that call is a TypeError on a binding that was never created —
+    // so 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("  // 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" }],');
     p("  // Public base for media URLs; same-origin keeps media self-contained. Read off");
     p("  // the runtime env by the framework-agnostic media route, so it stays a `var`.");
     p('  "vars": {');
     p(`    "MEDIA_URL": ${JSON.stringify(mediaBase)},`);
     p(`    "SITE_URL": ${JSON.stringify(primaryHost ? `https://${primaryHost}` : `https://${key}.workers.dev`)},`);
-    p('    // The editor allowlist / owner. Wire this into your auth seam (src/auth.ts).');
+    p("    // The editor allowlist / owner. Wire this into your auth seam (src/auth.ts).");
     p('    "OWNER_EMAIL": "",');
+    p("    // Edge caching for published pages (ADR 0004). OFF by default, and the");
+    p("    // default is the safe state: with it off every render is `no-store` and");
+    p("    // the Worker cache layer stores nothing.");
+    p("    //");
+    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('    "ASTROID_EDGE_CACHE": "false",');
+    for (const v of astroidCheckoutVars(config)) {
+        // Public, not secret — the app id ships to the browser to mount the card
+        // field, and the environment is a choice. Keeping them out of the secret
+        // roster also keeps them out of the dormancy gate, which asks whether we can
+        // safely CALL Square, not whether a card field can render.
+        p(`    ${JSON.stringify(v.name)}: ${JSON.stringify(v.value)},`);
+    }
     p("  },");
+    // Secrets are NOT vars: they belong in .dev.vars locally and in `wrangler
+    // secret put` / Secrets Store when deployed. Listing the names here is
+    // deliberate — this is the file someone opens when provisioning, and the list
+    // 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("  //   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");
+        p("  // webhook receiver answers 503, and nothing calls the provider.");
+        for (const name of secretNames)
+            p(`  //   ${name}`);
+    }
     p('  "observability": { "enabled": true },');
     p("}");
     p();

package/dist/project/index.d.ts

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

package/dist/project/index.js

@@ -3,3 +3,5 @@
 // Project generation — config → the files the `astroid` CLI writes (the
 // regenerated schema/worker/middleware trio + the scaffold-once wrangler.jsonc).
 export * from "./generate.js";
+export * from "./actions.js";
+export * from "./scaffold.js";

package/dist/project/scaffold.d.ts

@@ -0,0 +1,29 @@
+import type { AstroidConfig } from "../config.js";
+/**
+ * A file written once, then owned by the project.
+ *
+ * `apply` is the whole contract. `"skip"` (the default) leaves an existing file
+ * alone. `"append-once"` is for the files a project accumulates into rather than
+ * owns outright — `public/_headers` gets a stanza per module, and a second
+ * module must not erase the first one's.
+ */
+export interface ScaffoldFile {
+    /** Path relative to the project root, POSIX-separated. */
+    path: string;
+    contents: string;
+    /** What to do when the path already exists. Default `"skip"`. */
+    apply?: "skip" | "append-once";
+    /**
+     * For `"append-once"`: a substring that proves this stanza is already there.
+     * Without it a re-run would append a duplicate every time.
+     */
+    marker?: string;
+}
+/**
+ * Every scaffold-once file this config implies.
+ *
+ * Ordered by module so a `generate` that writes several prints them in a stable
+ * sequence. Returns `[]` for a plain marketing site with no modules — the
+ * baseline floor is entirely the regenerated trio plus the static template.
+ */
+export declare function generateAstroidScaffoldFiles(config: AstroidConfig): ScaffoldFile[];

package/dist/project/scaffold.js

@@ -0,0 +1,140 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// Every SCAFFOLD-ONCE file a config implies, in one list.
+//
+// This exists because the split between "generated" and "scaffolded" was drawn
+// in the wrong place. `generateAstroidProject` returns the regenerated trio, and
+// that trio emits STATIC IMPORTS of scaffold-once modules:
+//
+//   src/worker.ts      → import { handleQueueMessage } from "./queue.js"
+//   src/middleware.ts  → import { resolvePortalUser } from "./portal-auth.js"
+//
+// The files behind those imports were written in exactly one place —
+// `create-astroid`'s CLI — and nothing else could produce them. So turning a
+// module on AFTER scaffold, by editing the one typed config the framework is
+// built around, regenerated a trio importing files that did not exist. `astroid
+// doctor` reported "healthy" and the project failed in Vite.
+//
+// Aggregating them here makes `astroid generate` able to complete a config
+// change, `astroid doctor` able to notice one it hasn't, and `create-astroid`
+// stop hand-listing the same nine files a third time.
+//
+// SCAFFOLD-ONCE means what it says: every file here is written only when ABSENT.
+// Each one exists to be edited (what a catalog refresh means, which events
+// matter, what a reset email says), so regenerating over it would destroy the
+// work the seam exists to hold.
+import { generateAstroidCheckoutRoute, generateAstroidSquareCard, } from "../commerce/checkout-scaffold.js";
+import { generateCatalogMigrationSql } from "../commerce/mirror.js";
+import { generateAstroidVitalsBeacon } from "../analytics/index.js";
+import { generateAstroidActions } from "./actions.js";
+import { cwvBeaconScript } from "louise-toolkit/analytics";
+import { generateMapEmbedComponent, generateMapTileRoute } from "../map/scaffold.js";
+import { generateAstroidGalleryPage } from "../portfolio/scaffold.js";
+import { generateAstroidPortalAuth, generateAstroidPortalAuthRoute } from "../portal/scaffold.js";
+import { generateAstroidEditSession } from "../realtime/scaffold.js";
+import { generatePwaHeaders, generateServiceWorker, generateWebManifest } from "../pwa/generate.js";
+import { astroidUsesQueues } from "../queues/messages.js";
+import { generateAstroidQueueSeam, generateAstroidWebhookRoutes } from "../queues/scaffold.js";
+/**
+ * Every scaffold-once file this config implies.
+ *
+ * Ordered by module so a `generate` that writes several prints them in a stable
+ * sequence. Returns `[]` for a plain marketing site with no modules — the
+ * baseline floor is entirely the regenerated trio plus the static template.
+ */
+export function generateAstroidScaffoldFiles(config) {
+    const files = [];
+    // --- commerce: the catalog table's migration ------------------------------
+    // Numbered 0003 so it lands after the template's 0000_content and the auth
+    // pair (0001, 0002) that `create-astroid` writes. Without it `--commerce`
+    // scaffolded a `products` table into src/schema.ts that no migration ever
+    // created, and the first sync wrote nothing while reporting success.
+    const catalogSql = generateCatalogMigrationSql(config);
+    if (catalogSql)
+        files.push({ path: "migrations/0003_catalog.sql", contents: catalogSql });
+    // --- the CWV beacon -------------------------------------------------------
+    // A static file under public/, so it is same-origin and covered by
+    // `script-src 'self'` — an inline script carrying generated content could not
+    // be hashed into the CSP and would be blocked.
+    const beacon = generateAstroidVitalsBeacon(config, cwvBeaconScript());
+    files.push({ path: beacon.path, contents: beacon.contents });
+    // --- 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
+    // be added to.
+    files.push({ path: "src/actions/index.ts", contents: generateAstroidActions(config) });
+    // --- commerce: the server-authoritative payment seam ----------------------
+    // Scaffold-once: a real store adds shipping, tax, an order row, a receipt.
+    // What's fixed is the sequence that keeps a charge correct.
+    const checkoutRoute = generateAstroidCheckoutRoute(config);
+    if (checkoutRoute)
+        files.push({ path: "src/pages/api/checkout.ts", contents: checkoutRoute });
+    const squareCard = generateAstroidSquareCard(config);
+    if (squareCard)
+        files.push({ path: "src/components/SquareCard.astro", contents: squareCard });
+    // --- queues: the consumer seam + one receiver per commerce provider --------
+    // Both exist to be edited (what a refresh means; which events matter), which
+    // is why `astroid generate` must never rewrite them.
+    if (astroidUsesQueues(config)) {
+        files.push({ path: "src/queue.ts", contents: generateAstroidQueueSeam(config) });
+        // One receiver per provider — a site can run two (invoicing + storefront).
+        for (const route of generateAstroidWebhookRoutes(config)) {
+            files.push({ path: route.path, contents: route.contents });
+        }
+    }
+    // --- portfolio: the gallery page -----------------------------------------
+    // "Which assets appear, in what order" is the first thing a portfolio changes.
+    const gallery = generateAstroidGalleryPage(config);
+    if (gallery)
+        files.push({ path: "src/pages/work.astro", contents: gallery });
+    // --- pwa: the service worker, manifest, and its headers -------------------
+    // Static files under public/, not generated source — a service worker is not
+    // bundled, and `_headers` is shared with whatever else writes to it.
+    const sw = generateServiceWorker(config);
+    if (sw) {
+        files.push({ path: "public/sw.js", contents: sw });
+        const manifest = generateWebManifest(config);
+        if (manifest)
+            files.push({ path: "public/manifest.webmanifest", contents: manifest });
+        const headers = generatePwaHeaders(config);
+        if (headers) {
+            files.push({
+                path: "public/_headers",
+                contents: headers,
+                apply: "append-once",
+                // The service-worker path is the one token this stanza always contains
+                // and nothing else in a `_headers` file would.
+                marker: "/sw.js",
+            });
+        }
+    }
+    // --- map: the tile route + embed component --------------------------------
+    // Generated into the project rather than shipped in astroidjs so maplibre-gl
+    // stays a dependency of the projects that actually draw a map.
+    const tileRoute = generateMapTileRoute(config);
+    if (tileRoute)
+        files.push({ path: "src/pages/map/basemap.pmtiles.ts", contents: tileRoute });
+    const mapEmbed = generateMapEmbedComponent(config);
+    if (mapEmbed)
+        files.push({ path: "src/components/MapEmbed.astro", contents: mapEmbed });
+    // --- realtime: the per-page edit-session Durable Object -------------------
+    // Scaffold-once because it must import `cloudflare:workers` (runtime-only) and
+    // because `persist` is the seam a project tunes.
+    const editSession = generateAstroidEditSession(config);
+    if (editSession)
+        files.push({ path: "src/edit-session.ts", contents: editSession });
+    // --- portal: the second auth instance + its mounted catch-all -------------
+    // A site edits the reset email and the role a new account gets, but not the
+    // mount/cookie/table prefixes that keep the two instances isolated.
+    const portalAuth = generateAstroidPortalAuth(config);
+    if (portalAuth) {
+        files.push({ path: "src/portal-auth.ts", contents: portalAuth });
+        const route = generateAstroidPortalAuthRoute(config);
+        // Always non-null alongside portalAuth (same `astroidPortal` gate), but the
+        // types don't know that and a silent drop here is a portal that cannot
+        // authenticate — so assert it rather than `?.`-ing it away.
+        if (route)
+            files.push({ path: "src/pages/api/portal-auth/[...all].ts", contents: route });
+    }
+    return files;
+}

package/dist/pwa/generate.d.ts

@@ -0,0 +1,49 @@
+import type { AstroidConfig } from "../config.js";
+/** Tuning for the PWA scaffold. Every field has a sensible derivation. */
+export interface PwaConfig {
+    /**
+     * URL prefix the app is installed at. Default `"/"`.
+     *
+     * A narrower scope (`"/order"`) is usually right: it keeps the worker off the
+     * marketing pages entirely, which is both safer and a smaller cache.
+     */
+    scope?: string;
+    /** Home screen name. Defaults to the brand name. */
+    shortName?: string;
+    description?: string;
+    /** `standalone` (default) hides browser chrome; `browser` opts out of it. */
+    display?: "standalone" | "minimal-ui" | "fullscreen" | "browser";
+    orientation?: "any" | "portrait" | "landscape";
+    /** Splash background. Defaults to white. */
+    backgroundColor?: string;
+    /** Theme colour. Defaults to the brand colour. */
+    themeColor?: string;
+    /** Extra paths to precache alongside the scope root. */
+    shell?: string[];
+}
+/** True when this project switched the PWA on. */
+export declare const usesPwa: (config: AstroidConfig) => boolean;
+/** Resolved PWA settings — config over derivation over default. */
+export declare function resolvePwa(config: AstroidConfig): Required<Omit<PwaConfig, "shell">> & {
+    shell: string[];
+};
+/**
+ * `public/manifest.webmanifest`.
+ *
+ * Icons are declared but NOT generated — a brand's icon is not something a
+ * scaffold can invent, and emitting placeholders would produce an installable
+ * app with a grey square for a face. The generated README step says to add them.
+ */
+export declare function generateWebManifest(config: AstroidConfig): string | null;
+/** `public/sw.js`. Plain JS — a service worker is not bundled. */
+export declare function generateServiceWorker(config: AstroidConfig): string | null;
+/**
+ * The `public/_headers` block the PWA needs.
+ *
+ * `Service-Worker-Allowed` is emitted ONLY when the scope is broader than the
+ * script's own location — which, with `sw.js` at the root, never is. Emitting it
+ * unconditionally (as the reference does) is harmless but misleading: it implies
+ * a requirement that isn't there, and someone later moving the script will trust
+ * a header that no longer says what they need.
+ */
+export declare function generatePwaHeaders(config: AstroidConfig): string | null;