astroidjs 0.13.0 → 0.14.0

package/bin/astroid.mjs

@@ -264,9 +264,15 @@ async function cmdDoctor(cwd, flags) {
     }
   }
 
-  // 3. migrations directory (matches the generated wrangler `migrations_dir`).
-  if (existsSync(join(cwd, "migrations"))) ok("migrations/ directory present");
-  else warn("no migrations/ directory — create your D1 schema migrations there.");
+  // 3. migrations directory: the D1 `migrations_dir` wrangler.jsonc declares,
+  //    or `migrations/`, the generated default, when it names none. A site that
+  //    keeps its migrations under another name (drizzle/) isn't missing them.
+  const wranglerText = existsSync(wranglerPath) ? readFileSync(wranglerPath, "utf8") : "";
+  const migrationsDir =
+    wranglerText.match(/"migrations_dir"\s*:\s*"([^"]+)"/)?.[1]?.replace(/\/+$/, "") ??
+    "migrations";
+  if (existsSync(join(cwd, migrationsDir))) ok(`${migrationsDir}/ directory present`);
+  else warn(`no ${migrationsDir}/ directory — create your D1 schema migrations there.`);
 
   // 4. Local secret provisioning—which modules will run dormant under
   //    `astroid dev`, and what to set to wake them.

package/dist/analytics/index.js

@@ -51,14 +51,14 @@ export function generateAstroidVitalsBeacon(config, beacon) {
     return {
         path: "public/vitals.js",
         contents: [
-            "// Real-visitor Core Web Vitals beacon — generated by astroidjs.",
+            "// Real-visitor Core Web Vitals beacon—generated by astroidjs.",
             "//",
             "// A static file, not an inline script: Astro hashes processed scripts into",
             "// script-src, and an is:inline script with generated content can't be",
             "// hashed, so it would be CSP-blocked. From public/ it is same-origin and",
             "// already covered by script-src 'self'.",
             "//",
-            "// It reports once per page, on visibilitychange → hidden, via sendBeacon —",
+            "// It reports once per page, on visibilitychange → hidden, via sendBeacon—",
             "// so it costs nothing on the critical path and never blocks unload.",
             beacon,
             "",

package/dist/commerce/checkout-scaffold.js

@@ -42,12 +42,12 @@ export function generateAstroidCheckoutRoute(config) {
     return [
         "// Server-authoritative checkout (POST /api/checkout).",
         "//",
-        "// Scaffolded once and yours to extend — shipping, tax, an order row, a",
+        "// Scaffolded once and yours to extend—shipping, tax, an order row, a",
         "// receipt email all belong here. What should NOT change is the ORDER of the",
         "// steps below; each one is load-bearing:",
         "//",
         multi
-            ? "//   0. Resolve WHICH MERCHANT this sale belongs to, from the host — never\n" +
+            ? "//   0. Resolve WHICH MERCHANT this sale belongs to, from the host—never\n" +
                 "//      from the request body. See `resolveLocationId` below."
             : null,
         multi
@@ -65,7 +65,7 @@ export function generateAstroidCheckoutRoute(config) {
         "//      a double-clicked Pay button charges once while two customers buying",
         "//      the same thing stay two charges.",
         "//   4. Charge only when commerce is actually provisioned. With placeholder",
-        "//      secrets this simulates instead — it must never call Square with a",
+        "//      secrets this simulates instead—it must never call Square with a",
         "//      dummy credential.",
         multi
             ? "//\n" +
@@ -95,13 +95,13 @@ export function generateAstroidCheckoutRoute(config) {
                 "// ── Which merchant is this? ────────────────────────────────────────────────",
                 "//",
                 '// `square.locations: "multi"` means the location is a property of the',
-                "// REQUEST, not of the environment — which is why Astroid does not require a",
+                "// REQUEST, not of the environment—which is why Astroid does not require a",
                 "// SQUARE_LOCATION_ID for this project. Fill this in and keep two rules:",
                 "//",
                 "//   * Derive it from the HOST (or an authenticated session), never from the",
                 "//     request body. A body-supplied location lets a customer name the",
                 "//     cheapest merchant's id and pay that price at the dearest merchant's",
-                "//     shop — the same exploit as a client-supplied price, one level back.",
+                "//     shop—the same exploit as a client-supplied price, one level back.",
                 "//   * Return null for anything unrecognised. Falling back to a default",
                 "//     rings one merchant's sale against another merchant's books, and looks",
                 "//     completely successful while doing it.",
@@ -125,7 +125,7 @@ export function generateAstroidCheckoutRoute(config) {
                 "  // mirror holds ONE price per item, so it structurally cannot answer",
                 '  // "what does this cost at this location". `retrieveVariationPricesAt`',
                 "  // resolves `location_overrides`, and omits any variation the merchant",
-                "  // does not carry — so an unstocked id fails closed as `unavailable`",
+                "  // does not carry—so an unstocked id fails closed as `unavailable`",
                 "  // instead of silently selling at the base price.",
                 "  const locationId = scope?.locationId;",
                 "  if (!locationId) return new Map();",
@@ -150,7 +150,7 @@ export function generateAstroidCheckoutRoute(config) {
                 "  const prices = new Map<string, number>();",
                 "  for (const item of items) {",
                 "    // The mirror stores MAJOR units (dollars); the charge is in minor units.",
-                "    // `Math.round` is not decoration — 19.99 * 100 is 1998.9999999999998, and",
+                "    // `Math.round` is not decoration—19.99 * 100 is 1998.9999999999998, and",
                 "    // a float cent here fails the exact-equality staleness check on every",
                 "    // single checkout.",
                 "    if (variantIds.includes(item.externalId)) {",
@@ -174,7 +174,7 @@ export function generateAstroidCheckoutRoute(config) {
         "  // or probe prices, even though the card token itself is single-use. Requires",
         "  // an Origin/Referer matching the host; a non-browser caller (a stripped",
         "  // header) is refused. If you deliberately serve checkout from another origin,",
-        "  // this is the line to relax — it's yours.",
+        "  // this is the line to relax—it's yours.",
         '  if (!isSameOrigin(request)) return json({ error: "Forbidden" }, 403);',
         "",
         "  const body = (await request.json().catch(() => null)) as {",
@@ -203,7 +203,7 @@ export function generateAstroidCheckoutRoute(config) {
                 '    return json({ error: "This storefront is not open for orders." }, 409);',
                 "  }",
                 "",
-                "  // 4, EARLY — and the ordering is the point. Re-pricing per location is",
+                "  // 4, EARLY—and the ordering is the point. Re-pricing per location is",
                 "  // itself a live Square call, so the dormancy gate has to precede",
                 "  // verification here rather than follow it; running it after would call",
                 "  // Square with a placeholder token, which this route must never do.",
@@ -231,7 +231,7 @@ export function generateAstroidCheckoutRoute(config) {
                 "  const check = await verifyCheckout(body.lines, serverPrices, {",
                 "    scope: { locationId },",
                 "  });",
-                "  // Every stale line, with its live price — feed `issues` to `repairCart`",
+                "  // Every stale line, with its live price—feed `issues` to `repairCart`",
                 "  // (louise-toolkit/commerce) to fix the whole cart in one step.",
                 "  if (!check.ok) {",
                 "    return json({ error: check.message, reason: check.reason, issues: check.issues }, 409);",
@@ -243,7 +243,7 @@ export function generateAstroidCheckoutRoute(config) {
             : [
                 "  // 1 + 2: re-price and refuse on mismatch.",
                 "  const check = await verifyCheckout(body.lines, serverPrices);",
-                "  // Every stale line, with its live price — feed `issues` to `repairCart`",
+                "  // Every stale line, with its live price—feed `issues` to `repairCart`",
                 "  // (louise-toolkit/commerce) to fix the whole cart in one step.",
                 "  if (!check.ok) {",
                 "    return json({ error: check.message, reason: check.reason, issues: check.issues }, 409);",
@@ -253,7 +253,7 @@ export function generateAstroidCheckoutRoute(config) {
                 '  const idempotencyKey = await checkoutIdempotencyKey(check, "order", cartId);',
                 "",
                 "  // 4: dormant until provisioned. An unconfigured store still re-prices and",
-                "  // still refuses a stale cart — it just doesn't move money.",
+                "  // still refuses a stale cart—it just doesn't move money.",
                 "  // Cast as the toolkit's own `astroidModuleStatus` does: `readSecret`",
                 "  // accepts a plain string OR a Secrets Store binding, which CloudflareEnv",
                 "  // types more narrowly than the resolver's `SecretSource` map.",
@@ -278,7 +278,7 @@ export function generateAstroidCheckoutRoute(config) {
         "",
         "  // Both are guaranteed real by the dormancy gate above; the narrowing here",
         "  // is for the type system, which can't know that. `environment` is a UNION",
-        '  // ("sandbox" | "production"), not a free string — an unrecognised value',
+        '  // ("sandbox" | "production"), not a free string—an unrecognised value',
         "  // would otherwise silently select the sandbox host in production.",
         '  const environment = env.SQUARE_ENVIRONMENT === "production" ? "production" : "sandbox";',
         "  const payment = await createPayment(",
@@ -291,7 +291,7 @@ export function generateAstroidCheckoutRoute(config) {
         "      // The SERVER's number, never the client's.",
         '      amountMoney: { amount: check.subtotalCents, currency: "USD" },',
         multi
-            ? "      // The location the cart was PRICED against — necessarily the same one,\n" +
+            ? "      // The location the cart was PRICED against—necessarily the same one,\n" +
                 "      // or the sale rings against a merchant who never quoted this total."
             : null,
         multi ? "      locationId," : '      locationId: env.SQUARE_LOCATION_ID ?? "",',
@@ -336,7 +336,7 @@ export function generateAstroidSquareCard(config) {
         "---",
         "// Square Web Payments card input.",
         "//",
-        "// The card field is an IFRAME served by Square's CDN — the raw number never",
+        "// The card field is an IFRAME served by Square's CDN—the raw number never",
         "// enters this page's DOM and never reaches the Worker, which is what keeps the",
         "// site out of PCI scope. `tokenize()` returns a single-use token; POST it to",
         "// /api/checkout, which re-prices server-side before charging.",
@@ -348,7 +348,7 @@ export function generateAstroidSquareCard(config) {
         ...(multi
             ? [
                 "// Multi-location: the merchant is a property of the PAGE, so the id comes",
-                "// in as a prop. Only the card iframe is bound to it — the charge takes its",
+                "// in as a prop. Only the card iframe is bound to it—the charge takes its",
                 "// location from the server, which resolves it independently in",
                 "// /api/checkout. This one cannot pick the merchant, and shouldn't: it is",
                 "// rendered from markup a customer can reach.",
@@ -359,7 +359,7 @@ export function generateAstroidSquareCard(config) {
                 "",
             ]
             : []),
-        "// The PUBLIC application id — safe in the browser, unlike the access token.",
+        "// The PUBLIC application id—safe in the browser, unlike the access token.",
         "// Absent (an unprovisioned store) → render nothing rather than a dead form.",
         "const appId = env.SQUARE_APP_ID;",
         multi ? null : "const locationId = env.SQUARE_LOCATION_ID;",
@@ -463,7 +463,7 @@ export function generateAstroidCheckoutEnv(config) {
     // only, the environment belongs to any project that calls Square at all.
     const lines = [];
     if (usesCardCheckout(config)) {
-        lines.push("  /** Square's PUBLIC application id — shipped to the browser to mount the", "   *  Web Payments card field. Not a secret; see wrangler.jsonc `vars`. */", "  SQUARE_APP_ID: string;");
+        lines.push("  /** Square's PUBLIC application id—shipped to the browser to mount the", "   *  Web Payments card field. Not a secret; see wrangler.jsonc `vars`. */", "  SQUARE_APP_ID: string;");
     }
     if (usesSquare(config)) {
         lines.push('  /** Square API environment: "sandbox" or "production". Selects the API', "   *  host for EVERY Square call, so it is required for invoicing too. */", "  SQUARE_ENVIRONMENT: string;");

package/dist/commerce/mirror.js

@@ -54,7 +54,7 @@ export const BUILT_IN_OWNED = {
         type: "text",
         values: ["draft", "published"],
         default: "draft",
-        note: "New remote items land as draft — nothing goes live until someone says so.",
+        note: "New remote items land as draft—nothing goes live until someone says so.",
     },
     sortOrder: { type: "real", default: 0 },
     featured: { type: "boolean", default: false },
@@ -114,11 +114,11 @@ export function generateCatalogTable(config) {
     p(`// The catalog ${mode}. The provider is the source of truth; these rows are`);
     p(mode === "mirror"
         ? "// a local copy plus the owner's edits. Pulled columns are overwritten every"
-        : "// the owner's edits only — catalog fields are read live from the provider.");
+        : "// the owner's edits only—catalog fields are read live from the provider.");
     p("// sync; owned columns are preserved. See astroidCatalogUpsert.");
     p(`export const ${camel(table)} = sqliteTable(${JSON.stringify(table)}, {`);
     p('  id: integer("id").primaryKey({ autoIncrement: true }),');
-    p("  // The provider's id for this item — the sync's idempotency key.");
+    p("  // The provider's id for this item—the sync's idempotency key.");
     p('  externalId: text("external_id").notNull().unique(),');
     if (mode === "mirror") {
         p("  // --- PULLED: overwritten on every sync, never hand-edit ---");

package/dist/config.d.ts

@@ -408,6 +408,19 @@ export interface SettingsConfig {
     /** Extra media-library image keys beyond the base logo/favicon/OG defaults—*
       settings values validated as media-library URLs on write. */
     imageKeys?: string[];
+    /**
+     * Take per-key sanitizers and a GET transform from the scaffold-once
+     * `src/settings-hooks.ts`. The generated `settingsRoute` and the scaffolded
+     * settings Action both spread them in, so the two write paths clean a value
+     * the same way.
+     *
+     * The allowlist alone decides only which keys are written, not what's in
+     * them. Turn this on when a site's settings need clamping or normalizing
+     * before they're stored, such as a length limit, an email address, or a
+     * nested config object. The hooks live in a module rather than in this config
+     * because a sanitizer usually imports runtime code, which the CLI can't load.
+     */
+    hooks?: boolean;
 }
 /** Media-library upload policy. */
 export interface MediaConfig {
@@ -426,6 +439,18 @@ export interface MediaConfig {
      */
     maxUploadBytes?: number;
 }
+export interface PagesConfig {
+    /**
+     * Take a transform and extra reserved slugs for the `pages` route from the
+     * scaffold-once `src/pages-hooks.ts`. The generated worker passes them to
+     * `astroidPagesWriteHooks`, so the site's transform runs before Astroid's own
+     * section sanitize and validate.
+     *
+     * Turn this on when a site cleans a page write itself: normalizing the slug,
+     * clamping a title, or filling a new page's defaults.
+     */
+    hooks?: boolean;
+}
 export interface DeployConfig {
     platform: "cloudflare";
     /** Media base for R2 + `cf-image` resizing—matches Louise's media route
@@ -504,6 +529,8 @@ export interface AstroidConfig {
     settings?: SettingsConfig;
     /** Media-library upload policy (for example, a larger `maxUploadBytes`). */
     media?: MediaConfig;
+    /** The editable `pages` collection's site-owned write hooks. */
+    pages?: PagesConfig;
     /**
      * Force the contact form + `inquiries` table on or off. Omit to detect from
      * the config (a `contact` section, or a wholesale-inquiry module). Set `true`

package/dist/map/scaffold.js

@@ -30,7 +30,7 @@ export function generateMapTileRoute(config) {
         return null;
     return [
         "// Serves the self-hosted Protomaps basemap (one PMTiles archive) from R2,",
-        "// same-origin, with HTTP range support — the client reads only the byte",
+        "// same-origin, with HTTP range support—the client reads only the byte",
         "// ranges it needs per tile.",
         "//",
         "// Same-origin is the point: no external tile host and no API key means the",
@@ -38,7 +38,7 @@ export function generateMapTileRoute(config) {
         "// irrelevant.",
         "//",
         "// Upload an archive to this key before the map draws anything (until then",
-        "// the canvas shows its background and pin — the module is dormant, not",
+        "// the canvas shows its background and pin—the module is dormant, not",
         "// broken):",
         `//   wrangler r2 object put ${config.key}-media/${ASTROID_PMTILES_KEY} \\`,
         "//     --file=extract.pmtiles --content-type=application/octet-stream --remote",
@@ -82,7 +82,7 @@ export function generateMapEmbedComponent(config) {
     return [
         "---",
         "// A MapLibre map over the self-hosted PMTiles basemap, centred on exact",
-        "// coordinates. Scaffolded once; yours to edit — the pin, the gestures, and",
+        "// coordinates. Scaffolded once; yours to edit—the pin, the gestures, and",
         "// the placeholder are brand decisions.",
         "//",
         "// Coordinates, never a geocoded address string: geocoding at render time is",
@@ -195,7 +195,7 @@ export function generateMapEmbedComponent(config) {
         "          if (!entry.isIntersecting) continue;",
         "          obs.unobserve(entry.target);",
         "          // `init` is async and nothing awaits it, so without this catch a",
-        "          // failed chunk fetch — a page load racing a deploy is enough — is a",
+        "          // failed chunk fetch—a page load racing a deploy is enough—is a",
         "          // silent unhandled rejection: the container just stays an empty",
         "          // tinted box with nothing in the console to explain it.",
         "          init(entry.target as HTMLElement).catch((err) => {",

package/dist/portal/config.d.ts

@@ -4,7 +4,7 @@ import type { PortalGuardConfig, PortalRoute } from "./guard.js";
  *  (`better-auth`) so the two sessions can coexist on one origin. */
 export declare const ASTROID_PORTAL_COOKIE_PREFIX = "portal";
 /** Table-name prefix for the portal's Better Auth tables—`portal_user`,
- *  `portal_session`, … The studio owns the unprefixed names. */
+ *  `portal_session`, … The studio's tables carry the `louise_` prefix. */
 export declare const ASTROID_PORTAL_TABLE_PREFIX = "portal_";
 /** Everything the generated portal wiring needs, defaults applied. */
 export interface ResolvedPortal {

package/dist/portal/config.js

@@ -3,18 +3,19 @@
 // Portal defaults derived from the project config—the single place that knows
 // the portal's mount, cookie prefix, table prefix, and guard table.
 //
-// The isolation constants are fixed rather than configurable, and that's the
-// point: the studio instance MUST keep Better Auth's defaults (`/api/auth`, the
-// unprefixed tables) because the Louise editor client hardcodes them, so the
-// portal is the one that moves. Leaving that to a project invites the one
-// mistake that matters—two instances sharing a cookie prefix, where signing
-// into one silently signs you out of the other, intermittently, in production.
+// The studio instance keeps `/api/auth` because the Louise editor client
+// hardcodes it, so the portal is the one that moves: its own mount, cookie
+// prefix, and table prefix. The defaults are safe distinct values, and
+// `defineAstroid` rejects any override that collides with the editor. That guards
+// the one mistake that matters—two instances sharing a cookie prefix, where
+// signing into one silently signs you out of the other, intermittently, in
+// production.
 import { ASTROID_PORTAL_BASE_PATH } from "../security/rate-rules.js";
 /** Cookie prefix for the portal instance. Distinct from the studio's default
  *  (`better-auth`) so the two sessions can coexist on one origin. */
 export const ASTROID_PORTAL_COOKIE_PREFIX = "portal";
 /** Table-name prefix for the portal's Better Auth tables—`portal_user`,
- *  `portal_session`, … The studio owns the unprefixed names. */
+ *  `portal_session`, … The studio's tables carry the `louise_` prefix. */
 export const ASTROID_PORTAL_TABLE_PREFIX = "portal_";
 /** Default guard table: the account area, for any signed-in portal user. */
 const DEFAULT_ROUTES = [{ prefix: "/portal" }, { prefix: "/api/portal" }];
@@ -27,7 +28,7 @@ export function astroidPortal(config) {
     return {
         enabled: true,
         // Isolation is configurable so a site with an existing second instance
-        // (coracle's shop account at /api/shop-auth, cookie `coracle_shop`, the
+        // (for example, a shop account at /api/shop-auth with its own cookie and the
         // unprefixed `user` tables) keeps its live mount + cookies unchanged. The
         // defaults stay the safe distinct-from-editor values; `defineAstroid`'s
         // `assertAuthIsolation` rejects a resolved value that collides with the

package/dist/portal/scaffold.js

@@ -21,13 +21,13 @@ export function generateAstroidPortalAuth(config) {
     if (!portal)
         return null;
     return [
-        "// The PORTAL auth instance — customers/members, separate from the editor.",
+        "// The PORTAL auth instance—customers/members, separate from the editor.",
         "//",
         "// Scaffolded once; yours to edit (the reset email, extra user columns, what",
         "// role a new account gets). Three things should NOT change: the basePath,",
         "// the cookiePrefix, and the tablePrefix. The studio instance keeps Better",
         "// Auth's defaults because the Louise editor client hardcodes them, so this",
-        "// one moves — and if the two ever share a cookie prefix, signing into one",
+        "// one moves—and if the two ever share a cookie prefix, signing into one",
         "// silently signs you out of the other.",
         'import { astroidMailTheme, magicLinkEmail, passwordResetEmail, resolveMailer, sendTransactional } from "astroidjs";',
         'import { env } from "cloudflare:workers";',
@@ -41,7 +41,7 @@ export function generateAstroidPortalAuth(config) {
         "  return getLouiseAuth(env, new URL(request.url).origin, {",
         "    rpName: astroidConfig.theme.name,",
         "    mailFrom: { email: env.MAIL_FROM, name: astroidConfig.theme.name },",
-        "    // The portal never sends magic links — it's email + password — but the",
+        "    // The portal never sends magic links—it's email + password—but the",
         "    // toolkit's config asks for a renderer, so give it the real one.",
         "    renderMagicLinkEmail: ({ url, toEmail }) => magicLinkEmail(MAIL_THEME, { url, toEmail }),",
         `    basePath: ${JSON.stringify(portal.basePath)},`,
@@ -51,14 +51,14 @@ export function generateAstroidPortalAuth(config) {
         "      minPasswordLength: 8,",
         portal.signUp
             ? "      // Public sign-up is ON for this project."
-            : "      // Accounts are provisioned by staff — no public sign-up.",
+            : "      // Accounts are provisioned by staff—no public sign-up.",
         `      disableSignUp: ${!portal.signUp},`,
         "      sendResetPassword: async ({ user, url }) => {",
         "        // Through `resolveMailer`, NOT a hand-built options object: it is the",
         "        // only thing that applies the DUMMY_REPLACE_ME sentinel check. Built by",
         "        // hand, a fresh deploy with a real EMAIL binding but a placeholder",
         "        // MAIL_FROM read as configured and called the Email API with an envelope",
-        '        // sender of literally "DUMMY_REPLACE_ME" — rejected upstream, swallowed',
+        '        // sender of literally "DUMMY_REPLACE_ME"—rejected upstream, swallowed',
         "        // here, and reported to the user as a reset email that was sent.",
         "        const mailer = await resolveMailer(env);",
         "        await sendTransactional(mailer, [",
@@ -66,7 +66,7 @@ export function generateAstroidPortalAuth(config) {
         "        ]);",
         "      },",
         "    },",
-        "    // The portal has its own users — never the editor allowlist.",
+        "    // The portal has its own users—never the editor allowlist.",
         "    resolveAdmins: () => [],",
         "  });",
         "}",
@@ -133,7 +133,7 @@ export function generateAstroidPortalLocals(config) {
     if (!astroidPortal(config))
         return "";
     return [
-        "    /** The signed-in PORTAL user (customers/members) — distinct from",
+        "    /** The signed-in PORTAL user (customers/members)—distinct from",
         "     *  `editor`, which is the studio session. Null when signed out. */",
         '    portalUser: import("astroidjs").PortalUser | null;',
     ].join("\n");

package/dist/portal/session.d.ts

@@ -1,13 +1,19 @@
 import type { PortalUser } from "./guard.js";
-/** Resolves the portal user for a request, or null when signed out. */
-export type PortalSessionResolver = (request: Request) => Promise<PortalUser | null>;
+/** Resolves the portal user for a request, or null when signed out. A site's
+ *  resolver can return its own richer user type; see {@link resolvePortalSession}. */
+export type PortalSessionResolver<U extends PortalUser = PortalUser> = (request: Request) => Promise<U | null>;
 /**
  * Resolve the portal session at most once per request.
  *
  * Shares the *promise*, not the result, so two callers racing during the same
  * request both await one lookup rather than starting a second.
+ *
+ * Generic over the site's user type, so the result keeps whatever the site's
+ * resolver returns (a customer ID, display initials) instead of narrowing to
+ * `PortalUser`. Every caller in a request passes the same resolver, so the
+ * shared promise always holds that type.
  */
-export declare function resolvePortalSession(request: Request, resolve: PortalSessionResolver): Promise<PortalUser | null>;
+export declare function resolvePortalSession<U extends PortalUser = PortalUser>(request: Request, resolve: PortalSessionResolver<U>): Promise<U | null>;
 /** JSON response helper—the shape every portal API route returns. */
 export declare function json(body: unknown, status?: number, headers?: Record<string, string>): Response;
 /** True when the request came from this same origin. */

package/dist/portal/session.js

@@ -18,6 +18,11 @@ const inFlight = new WeakMap();
  *
  * Shares the *promise*, not the result, so two callers racing during the same
  * request both await one lookup rather than starting a second.
+ *
+ * Generic over the site's user type, so the result keeps whatever the site's
+ * resolver returns (a customer ID, display initials) instead of narrowing to
+ * `PortalUser`. Every caller in a request passes the same resolver, so the
+ * shared promise always holds that type.
  */
 export function resolvePortalSession(request, resolve) {
     const existing = inFlight.get(request);

package/dist/portfolio/scaffold.js

@@ -25,7 +25,7 @@ export function generateAstroidGalleryPage(config) {
     const mediaBase = config.deploy?.mediaBase ?? "/media";
     return [
         "---",
-        "// The work gallery — a justified grid over the media library.",
+        "// The work gallery—a justified grid over the media library.",
         "//",
         "// Scaffolded once; yours to edit. The layout primitive is general",
         "// (astroidjs/components/JustifiedGallery.astro); what lives here is this",
@@ -33,8 +33,8 @@ export function generateAstroidGalleryPage(config) {
         "//",
         "// Rows carry `alt`/`caption` from the media registry, so an editor fixes alt",
         "// text once in the library and every gallery showing that asset picks it up.",
-        "// Assets missing width/height still render — the client corrects the layout",
-        "// once the image decodes — but they cost a visible reflow, so it's worth",
+        "// Assets missing width/height still render—the client corrects the layout",
+        "// once the image decodes—but they cost a visible reflow, so it's worth",
         "// backfilling dimensions on older uploads.",
         'import JustifiedGallery from "astroidjs/components/JustifiedGallery.astro";',
         'import type { GalleryItem } from "astroidjs/components/justify";',
@@ -59,7 +59,7 @@ export function generateAstroidGalleryPage(config) {
         "  ).all<MediaRow>();",
         "  rows = result.results ?? [];",
         "} catch {",
-        "  // No DB binding yet (pre-provision) — render the empty state.",
+        "  // No DB binding yet (pre-provision)—render the empty state.",
         "}",
         "",
         "const items: GalleryItem[] = rows.map((row) => ({",

package/dist/project/actions.js

@@ -29,12 +29,15 @@ export function generateAstroidActions(config) {
             ? `        columns: ${JSON.stringify(columnsOverride)},`
             : "        columns: ASTROID_SETTINGS_COLUMNS,",
         ...(customKeys.length ? [`        customKeys: ${JSON.stringify(customKeys)},`] : []),
+        // The same sanitizers the generated settingsRoute spreads in. An Action
+        // writes no GET, so `read` has nothing to do here.
+        ...(config.settings?.hooks ? ["        sanitize: settingsHooks.sanitize,"] : []),
         extraImageKeys.length
             ? `        imageKeys: [...ASTROID_SETTINGS_IMAGE_KEYS, ...${JSON.stringify(extraImageKeys)}],`
             : "        imageKeys: ASTROID_SETTINGS_IMAGE_KEYS,",
     ];
     return [
-        "// The typed Astro Actions surface — ADR 0001 layer 2.",
+        "// 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.",
@@ -54,17 +57,20 @@ export function generateAstroidActions(config) {
         "  louiseSettingsAction,",
         '} from "@louise-toolkit/astro";',
         "import {",
-        "  ASTROID_SETTINGS_COLUMNS,",
+        // Only when the Action uses it: a site that overrides the columns gets them
+        // as a literal, and an unused import is a lint error in its own file.
+        ...(columnsOverride ? [] : ["  ASTROID_SETTINGS_COLUMNS,"]),
         "  ASTROID_SETTINGS_IMAGE_KEYS,",
         "  astroidPagesCollection,",
         '} from "astroidjs";',
         'import astroidConfig from "../../astroid.config.js";',
         'import { pages, pagesVersions, siteSettings } from "../schema.js";',
+        ...(config.settings?.hooks ? ['import { settingsHooks } from "../settings-hooks.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.",
+        "// 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",
@@ -74,7 +80,7 @@ export function generateAstroidActions(config) {
         "",
         "export const server = {",
         "  louise: {",
-        "    // Inline field save (title, SEO) — the live, non-versioned path.",
+        "    // Inline field save (title, SEO)—the live, non-versioned path.",
         "    save: defineAction(",
         "      louiseSaveAction({",
         "        ...deps,",
@@ -87,7 +93,7 @@ export function generateAstroidActions(config) {
         "      }),",
         "    ),",
         "",
-        "    // The versioned body/sections save — stages a DRAFT, exactly as",
+        "    // The versioned body/sections save—stages a DRAFT, exactly as",
         "    // versionsRoute does, through the same `applySaveDraft`.",
         "    saveDraft: defineAction(",
         "      louiseSaveDraftAction({",
@@ -108,7 +114,7 @@ export function generateAstroidActions(config) {
         "        ...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",
+        "        // 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.",
         ...settingsExtra,
         '        mediaBase: astroidConfig.deploy?.mediaBase ?? "/media",',