astroidjs 0.1.2 → 0.3.0

package/dist/schema/collections.js

@@ -5,13 +5,25 @@
 // Astroid decides WHICH collections and fields exist (its opinions); Louise's
 // codegen decides HOW they become D1 tables. Dependency flows one way — this
 // imports `louise-toolkit/content`, never the reverse.
-// `content/define` rather than the `content` barrel: the barrel eagerly pulls the
-// codegen/localApi/validation chunks, and those import drizzle-orm for real — an
-// *optional* peer of louise-toolkit, so importing it here forced a package on
-// consumers who only ever describe collections. This entry is the drizzle-free
-// half (see louise-toolkit/src/core/content/define.ts).
+// `content/define` and `content/sections` rather than the `content` barrel: the
+// barrel eagerly pulls the codegen/localApi/validation chunks, and those import
+// drizzle-orm for real — an *optional* peer of louise-toolkit, so importing it
+// here would force a package on consumers who only DESCRIBE content (e.g.
+// create-astroid's schema generators, which call this function but never run the
+// beforeChange hook below). Both entries are drizzle-free: `content/define` for
+// the config types/builders, and `content/sections` for the write-time section
+// validators. That second entry is what the Rule-evaluator split
+// (louise-toolkit/src/core/content/rule.ts) added, so this hook can import the
+// validators STATICALLY instead of the dynamic `import("louise-toolkit/content")`
+// it used to need to keep the CLI's graph drizzle-free.
 import { defineCollection, } from "louise-toolkit/content/define";
+import { assertValidSections, sanitizeSectionsRichText } from "louise-toolkit/content/sections";
 import { sanitizeRichHtml } from "louise-toolkit/security";
+// The catalog is the single declaration of what a section IS — the same object
+// the on-canvas editor mounts with and this hook validates against. It lives
+// beside the components (it ships as source for them) and is imported here so
+// the two can't drift.
+import { astroidSectionCatalog } from "../components/sections.js";
 /**
  * The opinionated `pages` collection — the EDITABLE page fields, versioned
  * drafts, and full-text search. Keyed to the same names as Louise's `pagesColumns`
@@ -22,12 +34,89 @@ import { sanitizeRichHtml } from "louise-toolkit/security";
  * Validated by `defineCollection` at build time, so a malformed field shape throws
  * here rather than at codegen.
  */
+/** The media base a `pages` write sanitizes rich content against (config, `/media` default). */
+function pageMediaBase(config) {
+    return config.deploy?.mediaBase ?? "/media";
+}
+/**
+ * The section catalog a `pages` write is validated + sanitized against: the
+ * site's own (`config.sectionCatalog`) when it registered bespoke sections, else
+ * Astroid's built-in vocabulary. This is what lets a site with its own section
+ * designs (coracle's 13) keep the same write contract as a stock Astroid site.
+ */
+function resolveSectionCatalog(config) {
+    return config.sectionCatalog ?? astroidSectionCatalog;
+}
+/**
+ * Return a copy of a `pages` write payload with its `sections` rich-text fields
+ * sanitized against the project media base — a no-op when the write carries no
+ * `sections`. Pure; leaves every other field (and a partial PATCH's absent ones)
+ * untouched.
+ *
+ * Exported because two write paths need it: the collection's `beforeChange` hook
+ * below, AND the raw `pagesRoute` (which does not run collection hooks — see
+ * {@link astroidPagesWriteHooks}).
+ */
+export function sanitizeAstroidPageSections(config, data) {
+    if (data.sections === undefined)
+        return data;
+    const mediaBase = pageMediaBase(config);
+    const sections = sanitizeSectionsRichText(data.sections, resolveSectionCatalog(config), (html) => sanitizeRichHtml(html, { mediaBase }));
+    return { ...data, sections };
+}
+/**
+ * Validate the (already-sanitized) `sections` of a `pages` write against the
+ * catalog, throwing `LouiseValidationError` — an unknown `_type`, a field of the
+ * wrong shape, or a setting outside its declared options is rejected with a 422
+ * carrying the per-field violations. A no-op when the write carries no
+ * `sections`, so a partial PATCH of other fields isn't spuriously validated.
+ */
+export async function assertAstroidPageSections(config, data, operation = "update") {
+    if (data.sections === undefined)
+        return;
+    await assertValidSections(resolveSectionCatalog(config), data.sections, {
+        operation,
+        mediaBase: pageMediaBase(config),
+    });
+}
+/**
+ * The write-time hooks the raw `pagesRoute` (louise-toolkit/editor) needs to
+ * enforce the same section contract as the draft path.
+ *
+ * `pagesRoute` writes straight to the table and — unlike `versionsRoute` — takes
+ * no collection config, so it never runs the `beforeChange` hook below. Left
+ * bare (as it was), a direct `POST` / `PATCH /api/louise/pages/:id` persists an
+ * unknown section `_type`, a setting outside its options, or unsanitized section
+ * rich text: exactly what the hook exists to stop, silently missing from the one
+ * route the on-canvas *structural* edits flow through. `<Sections>` then skips
+ * the bad `_type`, so the section just vanishes with no error anywhere.
+ *
+ * These wire the SAME sanitize + validate the hook uses into `pagesRoute`'s
+ * `sanitize` / `transform` / `validate` seams, so both write paths enforce one
+ * contract. Spread into the route config:
+ *
+ *   pagesRoute({ table: pages, resolveEditor, fields, ...astroidPagesWriteHooks(config) })
+ */
+export function astroidPagesWriteHooks(config) {
+    const mediaBase = pageMediaBase(config);
+    return {
+        // `body` is a richField, so it goes through pagesRoute's own sanitize seam —
+        // with the project media base, matching the hook rather than the toolkit
+        // default sanitizer that knows no media base.
+        sanitize: (html) => sanitizeRichHtml(html, { mediaBase }),
+        // `sections` is not a richField, so it's sanitized here in the transform,
+        // which pagesRoute runs BEFORE validate — the hook's sanitize-then-validate
+        // order.
+        transform: (data) => sanitizeAstroidPageSections(config, data),
+        validate: (data, ctx) => assertAstroidPageSections(config, data, ctx.operation),
+    };
+}
 export function astroidPagesCollection(config) {
     // The `body` is rich HTML edited in place (`<Editable type="richtext">`) and
     // staged as a draft, so sanitize it on every write — never store raw HTML. A
     // pasted `<img>` pointing off-origin (a hotlink) is dropped: body images must
     // live in the media library. Mirrors the reference site's pages-collection hook.
-    const mediaBase = config.deploy?.mediaBase ?? "/media";
+    const mediaBase = pageMediaBase(config);
     const fields = {};
     fields.slug = { type: "text", required: true };
     fields.title = { type: "text", required: true };
@@ -38,19 +127,28 @@ export function astroidPagesCollection(config) {
     fields.ogImage = { type: "text" };
     fields.noindex = { type: "checkbox" };
     fields.sortOrder = { type: "number" };
-    // Structured page-builder blocks (the editable home) — deep-validated against
-    // the section catalog on write in a later slice.
+    // Structured page-builder blocks (the editable home), deep-validated against
+    // the section catalog on write — see the beforeChange hook below.
     fields.sections = { type: "json" };
     return defineCollection({
         slug: "pages",
         fields,
         hooks: {
             beforeChange: [
-                ({ data }) => {
-                    if (typeof data.body === "string") {
-                        return { ...data, body: sanitizeRichHtml(data.body, { mediaBase }) };
+                async ({ data }) => {
+                    let next = data;
+                    if (typeof next.body === "string") {
+                        next = { ...next, body: sanitizeRichHtml(next.body, { mediaBase }) };
                     }
-                    return data;
+                    // Sanitize BEFORE validating: a richText field stores HTML, and
+                    // validating the raw value would pass content the sanitizer is about
+                    // to change. Same order as the body above. Both steps are shared with
+                    // the raw pagesRoute (see astroidPagesWriteHooks) so the two write
+                    // paths can't diverge — the sanitize throws nothing, the assert throws
+                    // LouiseValidationError → 422 with per-field violations.
+                    next = sanitizeAstroidPageSections(config, next);
+                    await assertAstroidPageSections(config, next, "update");
+                    return next;
                 },
             ],
         },

package/dist/schema/framework.js

@@ -9,6 +9,11 @@
  *  wholesale-inquiry module. Shared by table selection (here) and route selection
  *  (the worker route plan). */
 export function capturesInquiries(config) {
+    // Explicit override wins — a site whose inquiry surface is a bespoke section
+    // (coracle's custom `contactForm`) can't be detected from the built-in
+    // vocabulary, so it says so directly.
+    if (typeof config.inquiries === "boolean")
+        return config.inquiries;
     const wantsWholesale = (mods) => (mods ?? []).includes("wholesaleInquiry");
     return ((config.sections ?? []).includes("contact") ||
         wantsWholesale(config.modules) ||

package/dist/schema/generate.js

@@ -10,6 +10,7 @@
 // `generateSchemaSource`: the caller (the Astroid CLI, a later slice) writes the
 // result to disk and formats it. Import ordering matches the site's schema.ts so
 // a formatter never re-flags the generated file.
+import { generateCatalogTable } from "../commerce/mirror.js";
 import { astroidFrameworkTables } from "./framework.js";
 /**
  * Generate the TypeScript source of a site's Drizzle schema from an Astroid
@@ -22,10 +23,17 @@ export function generateAstroidSchema(config) {
     // pagesColumns is spread into `pages`; the framework tables are re-exported.
     // One import brings them all in (matching the site) so nothing is unused.
     const dbImports = [...framework, "pagesColumns"].sort();
+    const catalog = generateCatalogTable(config);
+    // Only import the column builders the emitted source actually uses — an
+    // unused import is a lint error in the project we're generating into, and a
+    // missing one (`real`, from the catalog's price/sortOrder) is a type error.
+    const drizzleImports = ["integer", "sqliteTable", "text"];
+    if (catalog?.includes("real("))
+        drizzleImports.push("real");
     return [
         "// Generated by astroidjs — do not hand-edit.",
         "// Source: your defineAstroid config.",
-        'import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";',
+        `import { ${drizzleImports.sort().join(", ")} } from "drizzle-orm/sqlite-core";`,
         'import { collectionVersionsTable, type JsonValue } from "louise-toolkit/content";',
         `import { ${dbImports.join(", ")} } from "louise-toolkit/db";`,
         "",
@@ -42,7 +50,15 @@ export function generateAstroidSchema(config) {
         "// JSON blob — so the table only needs the slug.",
         'export const pagesVersions = collectionVersionsTable({ slug: "pages", fields: {} });',
         "",
+        ...(catalog ? [catalog] : []),
         `export { ${framework.join(", ")} };`,
         "",
+        "// Site-owned tables (the ones Astroid doesn't manage): a project declares",
+        "// its own Drizzle tables in src/schema.site.ts and they're re-exported here",
+        "// so drizzle-kit sees them and the generated worker can import them. The file",
+        "// is scaffold-once — empty until a project adds a table — so this re-export is",
+        "// always safe.",
+        'export * from "./schema.site.js";',
+        "",
     ].join("\n");
 }

package/dist/secrets.d.ts

@@ -0,0 +1,54 @@
+import { type SecretSource } from "louise-toolkit/security";
+export type { SecretSource };
+/**
+ * The placeholder every Astroid scaffold seeds its unprovisioned secrets with.
+ * Reading it back means "not configured yet", never a credential — the value is
+ * deliberately loud so it is obvious in a Secrets Store listing or a log line.
+ *
+ * It matches the sentinel `louise-toolkit`'s Turnstile gate already recognizes,
+ * so the captcha pair follows the same convention as every Astroid module.
+ */
+export declare const ASTROID_SECRET_PLACEHOLDER = "DUMMY_REPLACE_ME";
+/**
+ * Read one secret under the Astroid convention: `null` unless it holds a real,
+ * non-placeholder value. Thin by design — the reason to call this rather than
+ * `readSecret` directly is that it binds Astroid's sentinel for you.
+ */
+export declare function readModuleSecret(source: SecretSource): Promise<string | null>;
+/** The resolved secret set for one module, plus the gate derived from it. */
+export interface ModuleSecrets<K extends string> {
+    /**
+     * True when EVERY secret the module declared resolved to a real value. The
+     * module's `isConfigured()` should be exactly this — partial provisioning is
+     * treated as dormant, since a half-configured integration fails at the worst
+     * possible moment (mid-checkout) rather than at boot.
+     */
+    configured: boolean;
+    /** Each declared secret's resolved value, or `null` where unprovisioned. */
+    values: Record<K, string | null>;
+    /** The still-unprovisioned names, in declaration order — the "why not" list. */
+    missing: K[];
+}
+/**
+ * Resolve a module's secrets in one pass.
+ *
+ * ```ts
+ * const secrets = await resolveModuleSecrets({
+ *   SQUARE_ACCESS_TOKEN: env.SQUARE_ACCESS_TOKEN,
+ *   SQUARE_WEBHOOK_SECRET: env.SQUARE_WEBHOOK_SECRET,
+ * });
+ * if (!secrets.configured) return simulatedCheckout();  // dormant path
+ * ```
+ *
+ * Reads run concurrently: a Secrets Store `.get()` is a real await, and a module
+ * with four secrets should not pay for four sequential round-trips on the
+ * request path.
+ */
+export declare function resolveModuleSecrets<K extends string>(sources: Record<K, SecretSource>): Promise<ModuleSecrets<K>>;
+/**
+ * A one-line, human-readable status for a module — what `astroid doctor`, a dev
+ * server banner, or a health endpoint should print. Naming the missing secrets
+ * is the whole point: "commerce is off" sends someone reading source, "commerce
+ * is dormant — set SQUARE_ACCESS_TOKEN" does not.
+ */
+export declare function describeModuleStatus<K extends string>(module: string, status: ModuleSecrets<K>): string;

package/dist/secrets.js

@@ -0,0 +1,80 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The dormant-until-provisioned convention.
+//
+// Astroid's optional modules are opt-in at the CONFIG level but not at the
+// account level: switching `commerce` on in `defineAstroid` must not require a
+// Square account before `pnpm dev` will boot. So every module here follows one
+// rule — a module whose secrets are unprovisioned is DORMANT: it renders, it
+// serves, it says out loud that it is simulated, and it never calls upstream
+// with a dummy credential.
+//
+// The mechanism is `readSecret` from `louise-toolkit/security` (a secret that is
+// absent / unreadable / empty / a placeholder reads as `null`). What lives here
+// is the *convention* over it, which is Astroid's opinion, not the toolkit's:
+//
+//   1. ONE sentinel — `ASTROID_SECRET_PLACEHOLDER` — seeded by `create-astroid`
+//      into every secret a scaffold declares, so a fresh clone has a complete,
+//      valid binding set and zero real credentials.
+//   2. `resolveModuleSecrets` collapses a module's whole secret set into one
+//      `configured` gate plus the list of what's still missing, so a module's
+//      `isConfigured()` and its "why not" message come from the same read.
+//
+// This mirrors what all three consuming sites converged on independently.
+import { readSecret } from "louise-toolkit/security";
+/**
+ * The placeholder every Astroid scaffold seeds its unprovisioned secrets with.
+ * Reading it back means "not configured yet", never a credential — the value is
+ * deliberately loud so it is obvious in a Secrets Store listing or a log line.
+ *
+ * It matches the sentinel `louise-toolkit`'s Turnstile gate already recognizes,
+ * so the captcha pair follows the same convention as every Astroid module.
+ */
+export const ASTROID_SECRET_PLACEHOLDER = "DUMMY_REPLACE_ME";
+/**
+ * Read one secret under the Astroid convention: `null` unless it holds a real,
+ * non-placeholder value. Thin by design — the reason to call this rather than
+ * `readSecret` directly is that it binds Astroid's sentinel for you.
+ */
+export function readModuleSecret(source) {
+    return readSecret(source, { placeholder: ASTROID_SECRET_PLACEHOLDER });
+}
+/**
+ * Resolve a module's secrets in one pass.
+ *
+ * ```ts
+ * const secrets = await resolveModuleSecrets({
+ *   SQUARE_ACCESS_TOKEN: env.SQUARE_ACCESS_TOKEN,
+ *   SQUARE_WEBHOOK_SECRET: env.SQUARE_WEBHOOK_SECRET,
+ * });
+ * if (!secrets.configured) return simulatedCheckout();  // dormant path
+ * ```
+ *
+ * Reads run concurrently: a Secrets Store `.get()` is a real await, and a module
+ * with four secrets should not pay for four sequential round-trips on the
+ * request path.
+ */
+export async function resolveModuleSecrets(sources) {
+    const names = Object.keys(sources);
+    const resolved = await Promise.all(names.map((name) => readModuleSecret(sources[name])));
+    const values = {};
+    const missing = [];
+    names.forEach((name, i) => {
+        const value = resolved[i] ?? null;
+        values[name] = value;
+        if (value === null)
+            missing.push(name);
+    });
+    return { configured: missing.length === 0, values, missing };
+}
+/**
+ * A one-line, human-readable status for a module — what `astroid doctor`, a dev
+ * server banner, or a health endpoint should print. Naming the missing secrets
+ * is the whole point: "commerce is off" sends someone reading source, "commerce
+ * is dormant — set SQUARE_ACCESS_TOKEN" does not.
+ */
+export function describeModuleStatus(module, status) {
+    if (status.configured)
+        return `${module}: configured`;
+    return `${module}: dormant (simulated) — unprovisioned secret(s): ${status.missing.join(", ")}`;
+}

package/dist/security/index.d.ts

@@ -0,0 +1 @@
+export { ASTROID_CHECKOUT_PATH, ASTROID_PORTAL_BASE_PATH, astroidRateRules, type RateRule, } from "./rate-rules.js";

package/dist/security/index.js

@@ -0,0 +1,2 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+export { ASTROID_CHECKOUT_PATH, ASTROID_PORTAL_BASE_PATH, astroidRateRules, } from "./rate-rules.js";

package/dist/security/rate-rules.d.ts

@@ -0,0 +1,21 @@
+import type { RateRule } from "louise-toolkit/security";
+import type { AstroidConfig } from "../config.js";
+export type { RateRule };
+/**
+ * Base path the customer/portal Better Auth instance mounts at — its own
+ * handler, separate from the editor's `/api/auth`. Fixed by Astroid so the rate
+ * rules, the middleware, and the portal routes can't drift apart.
+ */
+export declare const ASTROID_PORTAL_BASE_PATH = "/api/portal-auth";
+/** Path the commerce module's checkout POSTs to. */
+export declare const ASTROID_CHECKOUT_PATH = "/api/checkout";
+/**
+ * The rule set for a project, derived from its config: the editor sign-in
+ * surface always, the portal's credential surfaces when a portal is enabled, and
+ * checkout when commerce is configured.
+ *
+ * Rules are matched first-wins, and `security.rateRules` from the config are
+ * placed FIRST — so a site tightens or loosens any default by declaring its own
+ * rule for that path, rather than losing the whole set to override one budget.
+ */
+export declare function astroidRateRules(config: AstroidConfig): RateRule[];

package/dist/security/rate-rules.js

@@ -0,0 +1,110 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// Rate-limit rules as data.
+//
+// The limiter mechanism lives in `louise-toolkit/security` and is deliberately
+// unopinionated: which routes, and which budgets, are policy. But the policy
+// turned out not to vary. All three consuming sites independently wrote the same
+// `RateRule[]` — the same public POST surfaces, the same 10-minute windows,
+// budgets within a factor of one of each other — differing only where the site
+// had a surface the others didn't (a portal, a checkout). That is a default, not
+// a per-site decision, so Astroid derives the whole set from the config.
+//
+// What's in scope: the public, UNAUTHENTICATED POST surfaces. Editor endpoints
+// (`/api/louise/*`) are session-gated and stay out on purpose — a limiter that
+// can lock the owner out of their own studio is worse than the abuse it stops.
+// The contact form is also absent by design: it's a worker route with its own
+// per-form limiter, and worker routes are matched before Astro's middleware ever
+// runs, so a rule here would never fire.
+/**
+ * Base path the customer/portal Better Auth instance mounts at — its own
+ * handler, separate from the editor's `/api/auth`. Fixed by Astroid so the rate
+ * rules, the middleware, and the portal routes can't drift apart.
+ */
+export const ASTROID_PORTAL_BASE_PATH = "/api/portal-auth";
+/** Path the commerce module's checkout POSTs to. */
+export const ASTROID_CHECKOUT_PATH = "/api/checkout";
+/** Ten minutes. Every default budget uses this window — long enough that a
+ *  burst can't wait it out, short enough that a false positive self-heals. */
+const WINDOW = 600;
+const exact = (path) => (p) => p === path;
+/**
+ * The rule set for a project, derived from its config: the editor sign-in
+ * surface always, the portal's credential surfaces when a portal is enabled, and
+ * checkout when commerce is configured.
+ *
+ * Rules are matched first-wins, and `security.rateRules` from the config are
+ * placed FIRST — so a site tightens or loosens any default by declaring its own
+ * rule for that path, rather than losing the whole set to override one budget.
+ */
+export function astroidRateRules(config) {
+    const rules = [...(config.security?.rateRules ?? [])];
+    // Magic-link sign-in is the email-bombing target: without a cap, anyone who
+    // knows an editor's address can trigger unbounded sign-in mail (their inbox,
+    // your Email + Worker spend). Tightest budget in the set.
+    rules.push({
+        name: "magic-link",
+        method: "POST",
+        match: exact("/api/auth/sign-in/magic-link"),
+        limit: 5,
+        windowSec: WINDOW,
+    });
+    // Everything else Better Auth serves (passkey challenges, sign-out, callbacks)
+    // behind a looser catch-all. Ordered after the specific rule above, which
+    // matters: `matchRateRule` takes the first match.
+    rules.push({
+        name: "auth",
+        method: "POST",
+        match: (p) => p.startsWith("/api/auth/"),
+        limit: 30,
+        windowSec: WINDOW,
+    });
+    if (config.portal?.enabled) {
+        // The portal's mount is configurable (a site may already ship a second
+        // instance at its own path), so the credential-surface rules must track the
+        // resolved base path, not the default constant — mirrors `astroidPortal`.
+        const base = config.portal.basePath ?? ASTROID_PORTAL_BASE_PATH;
+        // Customer credentials, unlike the editor's, are password-based — so these
+        // guard credential stuffing and enumeration, not just mail volume.
+        rules.push({
+            name: "portal-signup",
+            method: "POST",
+            match: exact(`${base}/sign-up/email`),
+            limit: 10,
+            windowSec: WINDOW,
+        });
+        rules.push({
+            name: "portal-signin",
+            method: "POST",
+            match: exact(`${base}/sign-in/email`),
+            limit: 15,
+            windowSec: WINDOW,
+        });
+        rules.push({
+            name: "portal-reset-request",
+            method: "POST",
+            match: exact(`${base}/request-password-reset`),
+            limit: 5,
+            windowSec: WINDOW,
+        });
+        rules.push({
+            name: "portal-reset",
+            method: "POST",
+            match: exact(`${base}/reset-password`),
+            limit: 15,
+            windowSec: WINDOW,
+        });
+    }
+    if (config.commerce) {
+        // Loosest budget in the set: a real shopper retries, edits, and re-submits a
+        // cart, so this is abuse control, not flow control.
+        rules.push({
+            name: "checkout",
+            method: "POST",
+            match: exact(ASTROID_CHECKOUT_PATH),
+            limit: 20,
+            windowSec: WINDOW,
+        });
+    }
+    return rules;
+}

package/dist/seo/index.d.ts

@@ -0,0 +1,3 @@
+export { type AstroidSeoOptions, type AstroidSeoSettings, type PageSeoInput, type ResolvedSeo, resolvePageSeo, } from "./resolve.js";
+export { astroidNoindexPaths, astroidRobotsTxt, astroidSitemapXml, type RobotsOptions, type SitemapEntry, type SitemapOptions, } from "./routes.js";
+export { ARCHETYPE_BUSINESS_TYPE, astroidStructuredData, escapeJsonLd, type JsonLdNode, type StructuredDataInput, } from "./structured-data.js";

package/dist/seo/index.js

@@ -0,0 +1,4 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+export { resolvePageSeo, } from "./resolve.js";
+export { astroidNoindexPaths, astroidRobotsTxt, astroidSitemapXml, } from "./routes.js";
+export { ARCHETYPE_BUSINESS_TYPE, astroidStructuredData, escapeJsonLd, } from "./structured-data.js";

package/dist/seo/resolve.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The `site_settings` subset the SEO layer reads. Structurally typed, so a
+ * composed settings table (or a plain object in a test) satisfies it without
+ * Astroid knowing anything about the rest of the row.
+ */
+export interface AstroidSeoSettings {
+    siteName?: string | null;
+    tagline?: string | null;
+    metaDescription?: string | null;
+    defaultOgImageUrl?: string | null;
+    /** Site-wide kill switch — noindex every page (staging, pre-launch). */
+    disableIndexing?: boolean | null;
+}
+/** Per-page SEO: an editor's overrides, or a built-in page's own defaults. */
+export interface PageSeoInput {
+    /** Bare title, pre-template. Omit for the site-wide default. */
+    title?: string | null;
+    description?: string | null;
+    /** Absolute URL or a site-root path; resolved against the serving origin. */
+    ogImage?: string | null;
+    /** `"website"` (default), or `"article"` / `"product"` for a richer card. */
+    ogType?: string | null;
+    /** Keep this page out of the index (cart, checkout, account, auth). */
+    noindex?: boolean | null;
+}
+export interface AstroidSeoOptions {
+    /** Canonical URL of the page being rendered — absolute. */
+    canonical: string;
+    /**
+     * Title template, `%s` standing in for the page title. Applied ONLY when the
+     * page supplies a title. Default `"%s | <siteName>"`.
+     */
+    titleTemplate?: string;
+    /** `@<handle>` for Twitter/X card attribution. */
+    twitterHandle?: string;
+    /** OG locale, e.g. `"en_US"`. */
+    locale?: string;
+}
+/** Everything a `<head>` needs, fully resolved and absolute. */
+export interface ResolvedSeo {
+    /** Final `<title>` — templated when the page supplied one. */
+    title: string;
+    /** Untemplated page title, for OG/Twitter (which shouldn't carry the site
+     *  suffix twice — the OG `site_name` already says it). */
+    bareTitle: string;
+    description?: string;
+    canonical: string;
+    ogType: string;
+    ogImage?: string;
+    ogImageAlt?: string;
+    siteName?: string;
+    locale?: string;
+    twitterHandle?: string;
+    noindex: boolean;
+}
+/**
+ * Resolve a page's SEO against the site settings.
+ *
+ * ```ts
+ * const seo = resolvePageSeo(settings, { title: page.seoTitle, noindex: page.noindex }, {
+ *   canonical: Astro.url.href,
+ * });
+ * ```
+ *
+ * `settings.disableIndexing` wins over everything: it's the site-wide kill
+ * switch, so a page that asks to be indexed on a staging deploy still isn't.
+ */
+export declare function resolvePageSeo(settings: AstroidSeoSettings, page: PageSeoInput | undefined, options: AstroidSeoOptions): ResolvedSeo;

package/dist/seo/resolve.js

@@ -0,0 +1,73 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// SEO resolution — settings defaults + per-page overrides, collapsed into the
+// exact set of values a `<head>` needs.
+//
+// Both sites that hand-built this layer converged on the same three-level
+// fallback (page override → the page's computed default → the site-wide
+// setting) and the same non-obvious details: an empty string is *unset*, not a
+// blank tag, so clearing a field in the editor falls back instead of publishing
+// an empty `<meta>`; and the title template applies only when a page supplies
+// its own title, so the home page reads "Acme Coffee" rather than
+// "Acme Coffee | Acme Coffee".
+//
+// Kept as a pure function rather than baked into the component so it can be
+// unit-tested, and so a route that isn't rendering a page (an OG-image endpoint,
+// a feed) can resolve the same values.
+/** Trimmed value, or undefined — an empty/whitespace string counts as unset. */
+const clean = (value) => {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+};
+/** Absolute URL for a path or URL, or undefined if it can't be resolved. */
+function absolute(value, base) {
+    const raw = clean(value);
+    if (!raw)
+        return undefined;
+    try {
+        return new URL(raw, base).toString();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve a page's SEO against the site settings.
+ *
+ * ```ts
+ * const seo = resolvePageSeo(settings, { title: page.seoTitle, noindex: page.noindex }, {
+ *   canonical: Astro.url.href,
+ * });
+ * ```
+ *
+ * `settings.disableIndexing` wins over everything: it's the site-wide kill
+ * switch, so a page that asks to be indexed on a staging deploy still isn't.
+ */
+export function resolvePageSeo(settings, page = {}, options) {
+    const siteName = clean(settings.siteName);
+    const pageTitle = clean(page.title);
+    const template = options.titleTemplate ?? (siteName ? `%s | ${siteName}` : "%s");
+    // No page title → the site-wide title stands alone. Templating it would read
+    // "Acme Coffee | Acme Coffee".
+    const bareTitle = pageTitle ?? siteName ?? "";
+    const title = pageTitle ? template.replace("%s", pageTitle) : bareTitle;
+    const description = clean(page.description) ?? clean(settings.metaDescription);
+    const ogImage = absolute(page.ogImage, options.canonical) ??
+        absolute(settings.defaultOgImageUrl, options.canonical);
+    return {
+        title,
+        bareTitle,
+        description,
+        canonical: options.canonical,
+        ogType: clean(page.ogType) ?? "website",
+        ogImage,
+        ogImageAlt: ogImage
+            ? [siteName, bareTitle].filter(Boolean).join(" — ") || undefined
+            : undefined,
+        siteName,
+        locale: clean(options.locale),
+        twitterHandle: clean(options.twitterHandle),
+        // The site-wide switch is deliberately not overridable per page.
+        noindex: Boolean(settings.disableIndexing) || Boolean(page.noindex),
+    };
+}