astroidjs 0.1.2 → 0.3.0

package/dist/email/send.js

@@ -0,0 +1,196 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// Best-effort delivery.
+//
+// Transactional mail in this stack is always store-and-forward: the inquiry row
+// is already in D1, the account already exists. Mail is the *notification* of
+// something that happened, so a mail failure must never fail the request that
+// caused it — and never throw into a `waitUntil` where it becomes an unhandled
+// rejection. Every path here resolves.
+//
+// The second job is the dev story. There is no EMAIL binding under `wrangler
+// dev`, and the single most common local task is "click the magic link" — so an
+// unconfigured mailer LOGS the message instead of silently dropping it, and it
+// logs the plaintext body, which is where the link is. That is the whole reason
+// every template renders a text alternative.
+//
+// This is the email module's half of the dormant-until-provisioned convention:
+// no binding means dormant and loudly simulated, not broken.
+import { sendEmail } from "louise-toolkit/email";
+import { resolveModuleSecrets } from "../secrets.js";
+/**
+ * The secrets the mailer needs. Just the envelope sender: the EMAIL binding is a
+ * binding, not a secret, so it's gated by presence rather than by value.
+ *
+ * Named here so `astroid doctor` and the scaffold's `.dev.vars` seed read the
+ * same list the runtime gate does.
+ */
+export const EMAIL_SECRET_NAMES = ["MAIL_FROM"];
+/**
+ * Resolve the email module's dormancy.
+ *
+ * Both halves are required, and for the same reason: a binding with no sender
+ * address can't build an envelope, and a sender address with no binding has
+ * nothing to send through. Either one missing means log-and-continue, which
+ * under `wrangler dev` (no EMAIL binding at all) is the normal case — and the
+ * reason the magic-link flow is still workable locally.
+ */
+export async function resolveMailerStatus(env) {
+    const secrets = await resolveModuleSecrets({ MAIL_FROM: env.MAIL_FROM });
+    const hasBinding = Boolean(env.EMAIL);
+    return {
+        configured: secrets.configured && hasBinding,
+        values: secrets.values,
+        missing: hasBinding ? [...secrets.missing] : [...secrets.missing, "EMAIL"],
+        hasBinding,
+    };
+}
+/**
+ * Build `MailerOptions` from an env, with dormancy already decided.
+ *
+ * The point of routing through {@link resolveMailerStatus} rather than checking
+ * `!env.EMAIL` inline is that the placeholder sentinel counts: a scaffold seeds
+ * `MAIL_FROM=DUMMY_REPLACE_ME`, and handing that to the Email API as an
+ * envelope sender is exactly the "called upstream with a dummy credential"
+ * failure the convention exists to prevent.
+ */
+export async function resolveMailer(env, overrides = {}) {
+    const status = await resolveMailerStatus(env);
+    return {
+        ...overrides,
+        binding: env.EMAIL ?? null,
+        from: status.values.MAIL_FROM ?? "noreply@localhost",
+        logOnly: overrides.logOnly || !status.configured,
+        status,
+    };
+}
+/**
+ * The console rendering of an unsent message.
+ *
+ * The body is the whole point in dev — that's where a sign-in link actually is,
+ * and printing it is what lets you sign in with no mail provider configured.
+ *
+ * It is also a credential. `logOnly` turns on whenever `MAIL_FROM` is unset, and
+ * that can happen in PRODUCTION — a secret that didn't get set, or a Secrets
+ * Store read that failed. The body then went to `console.info`, which means
+ * `wrangler tail` and every Logpush sink, carrying live single-use magic links
+ * and password-reset URLs. Anyone with read access to observability could take
+ * over an editor or portal account.
+ *
+ * So the body is printed only when we can see we're in development. Everywhere
+ * else the log still records that a message went unsent, and why, but not the
+ * credential inside it.
+ */
+function describe(mail, reason, includeBody) {
+    const head = [
+        `[astroid:email] ${reason} — not sent`,
+        `  to:      ${mail.to}`,
+        `  subject: ${mail.content.subject}`,
+    ];
+    if (!includeBody) {
+        return [
+            ...head,
+            "  (body withheld — it can contain a single-use sign-in or reset link, and this",
+            "   does not look like a development environment. Set MAIL_FROM and the EMAIL",
+            "   binding to deliver it, or pass `devLog: true` if this really is local.)",
+        ].join("\n");
+    }
+    return [...head, "  ---", ...mail.content.text.split("\n").map((line) => `  ${line}`), "  ---"].join("\n");
+}
+/**
+ * Best-effort "are we in development?".
+ *
+ * Deliberately conservative — it decides whether a credential is printed, so an
+ * unknown environment must read as production. Workers has no `NODE_ENV`, so we
+ * look at the signals that do exist and let a caller override explicitly.
+ */
+function looksLikeDev() {
+    // Vite/Astro define this at build time; `import.meta.env` is absent in a plain
+    // Worker, hence the guarded read.
+    const viteDev = import.meta.env?.DEV;
+    if (typeof viteDev === "boolean")
+        return viteDev;
+    const nodeEnv = globalThis.process
+        ?.env?.NODE_ENV;
+    if (typeof nodeEnv === "string")
+        return nodeEnv !== "production";
+    return false;
+}
+/**
+ * Send a batch of transactional messages, best effort.
+ *
+ * Delivery runs concurrently and independently: an inquiry sends a notification
+ * to the owner and a confirmation to the visitor, and the owner's copy must
+ * still arrive when the visitor typo'd their address. Callers get a result per
+ * message and decide whether to care.
+ *
+ * ```ts
+ * const results = await sendTransactional(
+ *   { binding: env.EMAIL, from: env.MAIL_FROM },
+ *   [
+ *     { to: owner, content: inquiryNotificationEmail(theme, i), replyTo: i.email },
+ *     { to: i.email, content: inquiryConfirmationEmail(theme, i) },
+ *   ],
+ * );
+ * ```
+ */
+export async function sendTransactional(options, mails) {
+    const log = options.log ?? ((message) => console.info(message));
+    const dormant = !options.binding || options.logOnly;
+    if (dormant) {
+        const reason = options.binding ? "log-only" : "not-configured";
+        const includeBody = options.devLog ?? looksLikeDev();
+        for (const mail of mails)
+            log(describe(mail, reason, includeBody));
+        return mails.map((mail) => ({
+            to: mail.to,
+            subject: mail.content.subject,
+            delivered: false,
+            reason,
+        }));
+    }
+    const binding = options.binding;
+    const settled = await Promise.allSettled(mails.map((mail) => sendEmail(binding, {
+        from: options.from,
+        to: mail.to,
+        subject: mail.content.subject,
+        html: mail.content.html,
+        text: mail.content.text,
+        ...(mail.replyTo ? { replyTo: mail.replyTo } : {}),
+    })));
+    return settled.map((result, i) => {
+        const mail = mails[i];
+        if (result.status === "fulfilled") {
+            return {
+                to: mail.to,
+                subject: mail.content.subject,
+                delivered: true,
+                messageId: result.value.messageId,
+            };
+        }
+        // A genuine delivery failure is LOGGED, not just returned.
+        //
+        // The result array was the only record of it, and the one caller that
+        // matters — the generated inquiry handler — discards it by design (the row
+        // is already durable, and the visitor must not see a 500 because the owner's
+        // notification bounced). So a dead Email Sending domain or an exhausted
+        // quota produced silence everywhere: a success page for the visitor, nothing
+        // for the owner, and nothing in `wrangler tail`. Weeks later someone asks
+        // why the contact form stopped working.
+        //
+        // Logged here rather than left to callers because this is the only place
+        // that knows a send was attempted and failed; `log` is already injectable
+        // for tests and for routing somewhere other than console.
+        const reason = result.reason instanceof Error ? result.reason.message : String(result.reason);
+        log(`[astroid:email] delivery FAILED to ${mail.to} (${mail.content.subject}): ${reason}`);
+        return { to: mail.to, subject: mail.content.subject, delivered: false, reason };
+    });
+}
+/**
+ * Bind a mailer's options once so call sites read as `mailer([...])`. Useful
+ * where the binding and sender are resolved per request but the sends are
+ * scattered (an inquiry hook, an auth callback).
+ */
+export function createMailer(options) {
+    return (mails) => sendTransactional(options, mails);
+}

package/dist/email/templates.d.ts

@@ -0,0 +1,24 @@
+import { type MailContent, type MailTheme } from "louise-toolkit/email";
+export type { MailContent, MailTheme };
+/** Editor sign-in magic link. */
+export declare function magicLinkEmail(theme: MailTheme, params: {
+    url: string;
+    toEmail: string;
+}): MailContent;
+/** Password-reset link (the portal's credential flow). */
+export declare function passwordResetEmail(theme: MailTheme, params: {
+    url: string;
+    toEmail: string;
+}): MailContent;
+/** The fields an inquiry contributes to both halves of the pair. */
+export interface InquiryDetails {
+    name: string;
+    email: string;
+    /** Subject line the visitor picked, if the form offers one. */
+    regarding?: string;
+    message: string;
+}
+/** Owner-facing notification for a new contact-form submission. */
+export declare function inquiryNotificationEmail(theme: MailTheme, i: InquiryDetails): MailContent;
+/** Confirmation back to whoever submitted the contact form. */
+export declare function inquiryConfirmationEmail(theme: MailTheme, i: InquiryDetails): MailContent;

package/dist/email/templates.js

@@ -0,0 +1,184 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The standard transactional set: sign-in link, password reset, and the
+// inquiry pair (notify the owner, confirm to the sender).
+//
+// All three consuming sites wrote these four, with the same structure and
+// near-identical copy — only the brand name differed, which is exactly what
+// makes them first-party rather than site-side. The brand-agnostic *frame*
+// (card, colour band, CTA button, paste-this-link fallback) already lives in
+// `louise-toolkit/email`; this file owns the wording and the layout inside it.
+//
+// Every template returns HTML **and** plaintext from one definition. The text
+// alternative is not decoration: a message with no text/plain part scores worse
+// with spam filters, and for a sign-in link the plaintext body is what a
+// terminal-based or accessibility client actually shows.
+//
+// Escaping is the other constant: every value that reaches these functions came
+// from a form or a database, and it lands inside an HTML document.
+import { escapeHtml, escapeMultiline, mailButton, mailFallbackLink, renderEmailShell, subjectSafe, } from "louise-toolkit/email";
+/** Body paragraph in the theme's sans stack. */
+const p = (theme, html, opts = {}) => `<p style="font-family:${theme.fonts.sans};font-size:${opts.muted ? "15px" : "16px"};line-height:1.6;color:${opts.muted ? theme.palette.inkMute : theme.palette.inkSoft};margin:${opts.margin ?? "0 0 12px"};">${html}</p>`;
+/** Small uppercase mono label. */
+const label = (theme, text, margin = "0 0 10px") => `<p style="font-family:${theme.fonts.mono};font-size:10px;letter-spacing:0.1em;text-transform:uppercase;color:${theme.palette.inkMute};margin:${margin};">${text}</p>`;
+/** A quoted block for user-authored text (a message body). */
+const quote = (theme, text) => `<div style="font-family:${theme.fonts.sans};font-size:15px;line-height:1.65;color:${theme.palette.ink};padding:16px 18px;background:${theme.palette.bgSoft};border:1px solid ${theme.palette.rule};border-radius:6px;">${escapeMultiline(text)}</div>`;
+/**
+ * A one-time link email — the shared shape behind sign-in and password reset.
+ * Both are "here is a URL, it expires, ignore this if it wasn't you", and the
+ * only differences are the words.
+ */
+function linkEmail(theme, opts) {
+    const bodyHtml = [
+        p(theme, opts.lead),
+        p(theme, `This link expires in <strong style="color:${theme.palette.ink};font-weight:600;">${opts.expiry}</strong> and can only be used once.`, { muted: true, margin: "0 0 30px" }),
+        mailButton(theme, { href: opts.url, label: `${opts.buttonLabel} &rarr;` }),
+        mailFallbackLink(theme, opts.url),
+        p(theme, opts.disclaimer, { muted: true, margin: "26px 0 0" }),
+    ].join("\n");
+    return {
+        subject: opts.subject,
+        html: renderEmailShell(theme, {
+            title: opts.title,
+            preheader: opts.preheader,
+            eyebrow: opts.eyebrow,
+            headline: opts.headline,
+            bodyHtml,
+            footerNote: `Sent to ${escapeHtml(opts.toEmail)} &middot; ${opts.footerNote}`,
+        }),
+        text: [
+            opts.headline.replace(/&[a-z]+;/g, "'"),
+            "",
+            opts.textLead,
+            `It expires in ${opts.expiry} and can only be used once.`,
+            "",
+            opts.url,
+            "",
+            opts.disclaimer.replace(/&[a-z]+;/g, "'").replace(/<[^>]+>/g, ""),
+        ].join("\n"),
+    };
+}
+/** Editor sign-in magic link. */
+export function magicLinkEmail(theme, params) {
+    const brand = theme.brand.name;
+    return linkEmail(theme, {
+        subject: `Your sign-in link — ${brand}`,
+        title: "Your sign-in link",
+        preheader: "Your one-time sign-in link — expires in 15 minutes.",
+        eyebrow: "Sign in",
+        headline: "Here&rsquo;s your magic link.",
+        lead: `Use the button below to sign in to ${escapeHtml(brand)}. No password needed.`,
+        expiry: "15 minutes",
+        buttonLabel: "Sign in",
+        url: params.url,
+        toEmail: params.toEmail,
+        disclaimer: "If you didn&rsquo;t request this, you can safely ignore this email.",
+        footerNote: "Automated sign-in message.",
+        textLead: `Use this link to sign in to ${brand} — no password needed.`,
+    });
+}
+/** Password-reset link (the portal's credential flow). */
+export function passwordResetEmail(theme, params) {
+    const brand = theme.brand.name;
+    return linkEmail(theme, {
+        subject: `Reset your password — ${brand}`,
+        title: "Reset your password",
+        preheader: "Reset your password — this link expires in 1 hour.",
+        eyebrow: "Password reset",
+        headline: "Reset your password.",
+        lead: `We got a request to reset the password on your ${escapeHtml(brand)} account. Use the button below to choose a new one.`,
+        expiry: "1 hour",
+        buttonLabel: "Reset your password",
+        url: params.url,
+        toEmail: params.toEmail,
+        disclaimer: "If you didn&rsquo;t request this, you can safely ignore this email &mdash; your password won&rsquo;t change.",
+        footerNote: "Automated account message.",
+        textLead: `We got a request to reset the password on your ${brand} account. Use this link to choose a new one.`,
+    });
+}
+/** Owner-facing notification for a new contact-form submission. */
+export function inquiryNotificationEmail(theme, i) {
+    const { palette: c, fonts: f } = theme;
+    const name = i.name.trim() || "Someone";
+    const safeEmail = escapeHtml(i.email);
+    const row = (k, v) => `<tr>
+<td style="padding:10px 0;border-bottom:1px solid ${c.ruleSoft};font-family:${f.mono};font-size:10px;letter-spacing:0.1em;text-transform:uppercase;color:${c.inkMute};white-space:nowrap;vertical-align:top;width:96px;">${k}</td>
+<td style="padding:10px 0 10px 16px;border-bottom:1px solid ${c.ruleSoft};font-family:${f.sans};font-size:15px;line-height:1.55;color:${c.ink};">${v}</td>
+</tr>`;
+    const bodyHtml = [
+        p(theme, "A new message just came in through the contact form.", { margin: "0 0 24px" }),
+        `<table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="margin:0 0 26px;">
+${row("From", escapeHtml(name))}
+${row("Email", `<a href="mailto:${safeEmail}" style="color:${c.accent};text-decoration:none;">${safeEmail}</a>`)}
+${i.regarding?.trim() ? row("Regarding", escapeHtml(i.regarding.trim())) : ""}
+</table>`,
+        label(theme, "Message"),
+        quote(theme, i.message),
+        p(theme, `Just reply to this email to respond to ${escapeHtml(name)} directly.`, {
+            muted: true,
+            margin: "24px 0 0",
+        }),
+    ].join("\n");
+    return {
+        // `subjectSafe` collapses newlines: a name field is visitor-supplied, and a
+        // newline in a Subject header is a header-injection primitive.
+        subject: subjectSafe(`New inquiry from ${name}`),
+        html: renderEmailShell(theme, {
+            title: "New inquiry",
+            preheader: escapeHtml(`${name} — ${i.regarding?.trim() || "New inquiry"}`),
+            eyebrow: "New inquiry",
+            headline: "You&rsquo;ve got a new message.",
+            bodyHtml,
+            footerNote: `Reply goes to ${safeEmail} &middot; Automated notification.`,
+        }),
+        text: [
+            "New inquiry",
+            "",
+            `From: ${name}`,
+            `Email: ${i.email}`,
+            ...(i.regarding?.trim() ? [`Regarding: ${i.regarding.trim()}`] : []),
+            "",
+            "Message:",
+            i.message,
+        ].join("\n"),
+    };
+}
+/** Confirmation back to whoever submitted the contact form. */
+export function inquiryConfirmationEmail(theme, i) {
+    const brand = theme.brand.name;
+    // Only the given name — "Hi Jane Smith" reads like a form letter, which is
+    // precisely what this is trying not to.
+    const first = i.name.trim().split(/\s+/)[0] || "there";
+    const bodyHtml = [
+        p(theme, `Hi ${escapeHtml(first)} &mdash; thanks for reaching out. Your message has landed, and we answer personally, usually within a business day or two.`),
+        i.regarding?.trim()
+            ? p(theme, `Regarding: <strong style="color:${theme.palette.ink};font-weight:600;">${escapeHtml(i.regarding.trim())}</strong>`, { muted: true, margin: "0 0 24px" })
+            : "",
+        label(theme, "Your message"),
+        quote(theme, i.message),
+        p(theme, "No need to reply &mdash; this is just a confirmation that yours came through.", {
+            muted: true,
+            margin: "24px 0 0",
+        }),
+    ].join("\n");
+    return {
+        subject: `Thanks for your message — ${brand}`,
+        html: renderEmailShell(theme, {
+            title: "We got your message",
+            preheader: "Thanks for reaching out — we answer personally, usually within a day or two.",
+            eyebrow: escapeHtml(brand),
+            headline: "Thanks &mdash; we&rsquo;ve got your message.",
+            bodyHtml,
+            footerNote: "Automated confirmation &middot; No reply needed.",
+        }),
+        text: [
+            `Hi ${first} — thanks for reaching out.`,
+            "",
+            "Your message has landed, and we answer personally, usually within a business day or two.",
+            ...(i.regarding?.trim() ? ["", `Regarding: ${i.regarding.trim()}`] : []),
+            "",
+            "Your message:",
+            i.message,
+        ].join("\n"),
+    };
+}

package/dist/email/theme.d.ts

@@ -0,0 +1,24 @@
+import type { MailPalette, MailTheme } from "louise-toolkit/email";
+import type { AstroidConfig } from "../config.js";
+/** Deep-mergeable overrides for the parts a site wants to own. */
+export interface MailThemeOverrides {
+    palette?: Partial<MailPalette>;
+    band?: string[];
+    fonts?: Partial<MailTheme["fonts"]>;
+    brand?: Partial<MailTheme["brand"]>;
+    radius?: number;
+    bandHeight?: number;
+    buttonShape?: MailTheme["buttonShape"];
+}
+/**
+ * Build the project's transactional-mail theme from its `defineAstroid` config.
+ *
+ * ```ts
+ * const theme = astroidMailTheme(config);
+ * const mail = magicLinkEmail(theme, { url, toEmail });
+ * ```
+ *
+ * An invalid or missing brand colour falls back to the ink neutral rather than
+ * throwing — a malformed hex in settings should not take out password reset.
+ */
+export declare function astroidMailTheme(config: AstroidConfig, overrides?: MailThemeOverrides): MailTheme;

package/dist/email/theme.js

@@ -0,0 +1,150 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// Deriving a `MailTheme` from the project's brand.
+//
+// The toolkit's email shell takes a fully-specified theme — ten palette slots, a
+// colour band, three font stacks. Every site hand-picked all of it, which is
+// exactly the kind of work a config should absorb: an Astroid project already
+// declares `theme.colors`, and that is enough to produce a mail theme that looks
+// deliberate rather than defaulted.
+//
+// Two decisions here are load-bearing:
+//
+//   1. **Neutrals are fixed, brand colours are derived.** Page background, ink,
+//      rules — those are typography choices, not brand ones, and a site that
+//      wants different ones passes an override. What varies per brand is the
+//      accent and the colour band, and both come from `theme.colors`.
+//   2. **The accent is contrast-corrected.** A pale brand colour used verbatim
+//      as the eyebrow + link colour is unreadable on a near-white card. Rather
+//      than hope nobody picks yellow, the accent is darkened until it clears
+//      WCAG AA against the card background.
+function hexToRgb(hex) {
+    const raw = hex.trim().replace(/^#/, "");
+    const full = raw.length === 3 ? [...raw].map((c) => c + c).join("") : raw;
+    if (!/^[0-9a-fA-F]{6}$/.test(full))
+        return null;
+    return [
+        Number.parseInt(full.slice(0, 2), 16),
+        Number.parseInt(full.slice(2, 4), 16),
+        Number.parseInt(full.slice(4, 6), 16),
+    ];
+}
+const rgbToHex = ([r, g, b]) => `#${[r, g, b]
+    .map((v) => Math.round(Math.max(0, Math.min(255, v)))
+    .toString(16)
+    .padStart(2, "0"))
+    .join("")}`;
+/** Linear blend from `a` to `b`; `t` of 0 is all `a`, 1 is all `b`. */
+const mix = (a, b, t) => [
+    a[0] + (b[0] - a[0]) * t,
+    a[1] + (b[1] - a[1]) * t,
+    a[2] + (b[2] - a[2]) * t,
+];
+const WHITE = [255, 255, 255];
+const BLACK = [0, 0, 0];
+const tint = (c, t) => mix(c, WHITE, t);
+const shade = (c, t) => mix(c, BLACK, t);
+/** WCAG relative luminance. */
+function luminance([r, g, b]) {
+    const channel = (v) => {
+        const s = v / 255;
+        return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+    };
+    return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+}
+/** WCAG contrast ratio between two colours (1–21). */
+function contrast(a, b) {
+    const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+    return (hi + 0.05) / (lo + 0.05);
+}
+/**
+ * Darken `color` until it clears `minRatio` against `bg`. A brand colour is
+ * chosen to look good on a website, and plenty of good ones (yellows, pale
+ * teals) are illegible as 11px uppercase text on a near-white email card — mail
+ * clients offer no dark-mode escape hatch, so this is corrected up front.
+ */
+function readableOn(color, bg, minRatio = 4.5) {
+    let out = color;
+    // 20 steps of 5% each bottoms out at black, which always passes on a light bg.
+    for (let i = 0; i < 20 && contrast(out, bg) < minRatio; i++)
+        out = shade(out, 0.05);
+    return out;
+}
+/**
+ * The five-cell colour band across the top of the card. Always five cells,
+ * whatever the brand supplies, so the masthead reads as a designed element
+ * rather than "however many colours happened to be configured":
+ *
+ *   one colour   → a light-to-dark ramp through it
+ *   two colours  → a ramp bridging the two
+ *   three        → the three, with a light lead and a dark tail
+ */
+function buildBand(colors) {
+    const [a, b, c] = colors;
+    if (!b)
+        return [tint(a, 0.4), tint(a, 0.18), a, shade(a, 0.18), shade(a, 0.34)].map(rgbToHex);
+    if (!c)
+        return [tint(a, 0.35), a, mix(a, b, 0.5), b, shade(b, 0.25)].map(rgbToHex);
+    return [tint(a, 0.3), a, b, c, shade(c, 0.25)].map(rgbToHex);
+}
+/** Warm-neutral defaults. Brand-agnostic typography choices, not brand ones. */
+const NEUTRALS = {
+    pageBg: "#EDEBE4",
+    bg: "#FFFDF7",
+    bgSoft: "#FAF7EF",
+    ink: "#1A1A1A",
+    inkSoft: "#4A4A4A",
+    inkMute: "#6D6D6D",
+    rule: "#E1DED4",
+    ruleSoft: "#EDEBE4",
+    onDark: "#FAF7EF",
+};
+/** Web-safe stacks. Email clients can't be relied on to load a webfont, so the
+ *  project's `theme.font` leads and a real fallback follows. */
+function buildFonts(font) {
+    const lead = font?.trim() ? `'${font.trim()}', ` : "";
+    return {
+        serif: `${lead}Georgia, 'Times New Roman', serif`,
+        sans: `${lead}-apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif`,
+        mono: "ui-monospace, Menlo, Consolas, 'Courier New', monospace",
+    };
+}
+/**
+ * Build the project's transactional-mail theme from its `defineAstroid` config.
+ *
+ * ```ts
+ * const theme = astroidMailTheme(config);
+ * const mail = magicLinkEmail(theme, { url, toEmail });
+ * ```
+ *
+ * An invalid or missing brand colour falls back to the ink neutral rather than
+ * throwing — a malformed hex in settings should not take out password reset.
+ */
+export function astroidMailTheme(config, overrides = {}) {
+    const cardBg = hexToRgb(NEUTRALS.bg) ?? WHITE;
+    const brandColors = [
+        config.theme.colors.brand,
+        config.theme.colors.secondary,
+        config.theme.colors.tertiary,
+    ]
+        .map((c) => (c ? hexToRgb(c) : null))
+        .filter((c) => c !== null);
+    const base = brandColors[0] ?? hexToRgb(NEUTRALS.ink);
+    return {
+        palette: {
+            ...NEUTRALS,
+            accent: rgbToHex(readableOn(base, cardBg)),
+            ...overrides.palette,
+        },
+        band: overrides.band ?? buildBand(brandColors.length ? brandColors : [base]),
+        fonts: { ...buildFonts(config.theme.font), ...overrides.fonts },
+        brand: {
+            name: config.theme.name,
+            footerLead: config.theme.name,
+            ...overrides.brand,
+        },
+        radius: overrides.radius ?? 8,
+        bandHeight: overrides.bandHeight ?? 110,
+        buttonShape: overrides.buttonShape ?? "pill",
+    };
+}

package/dist/errors.d.ts

@@ -3,3 +3,17 @@
 export declare class AstroidConfigError extends Error {
     constructor(message: string);
 }
+/**
+ * Thrown when an Astroid runtime helper is called with arguments that would
+ * produce a silently wrong result.
+ *
+ * Distinct from {@link AstroidConfigError}, which is a build-time contract: this
+ * one fires on a live request, so it must be something a handler can catch and
+ * turn into a 5xx rather than something that reads like a misconfigured project.
+ * Reserved for cases where carrying on would be worse than failing — a checkout
+ * whose idempotency key collides with another customer's, say, where the damage
+ * (a buyer who is never charged) is invisible at the call site.
+ */
+export declare class AstroidUsageError extends Error {
+    constructor(message: string);
+}

package/dist/errors.js

@@ -11,3 +11,20 @@ export class AstroidConfigError extends Error {
         this.name = "AstroidConfigError";
     }
 }
+/**
+ * Thrown when an Astroid runtime helper is called with arguments that would
+ * produce a silently wrong result.
+ *
+ * Distinct from {@link AstroidConfigError}, which is a build-time contract: this
+ * one fires on a live request, so it must be something a handler can catch and
+ * turn into a 5xx rather than something that reads like a misconfigured project.
+ * Reserved for cases where carrying on would be worse than failing — a checkout
+ * whose idempotency key collides with another customer's, say, where the damage
+ * (a buyer who is never charged) is invisible at the call site.
+ */
+export class AstroidUsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AstroidUsageError";
+    }
+}

package/dist/index.d.ts

@@ -1,5 +1,20 @@
+export * from "./analytics/index.js";
+export * from "./auth/index.js";
+export * from "./commerce/index.js";
 export * from "./config.js";
+export * from "./email/index.js";
 export * from "./errors.js";
+export * from "./secrets.js";
+export * from "./map/index.js";
+export * from "./portal/index.js";
+export * from "./portfolio/index.js";
 export * from "./project/index.js";
+export * from "./pwa/index.js";
+export * from "./realtime/index.js";
+export * from "./queues/index.js";
 export * from "./schema/index.js";
+export * from "./security/index.js";
+export * from "./seo/index.js";
+export * from "./status.js";
 export * from "./worker/index.js";
+export * from "./workflow/index.js";

package/dist/index.js

@@ -3,8 +3,23 @@
 // astroidjs — the opinionated meta-framework over Louise Toolkit + Astro.
 // Public entry. The configuration surface (`defineAstroid`) is the first
 // inhabitant; the generator, theme system, and section library follow.
+export * from "./analytics/index.js";
+export * from "./auth/index.js";
+export * from "./commerce/index.js";
 export * from "./config.js";
+export * from "./email/index.js";
 export * from "./errors.js";
+export * from "./secrets.js";
+export * from "./map/index.js";
+export * from "./portal/index.js";
+export * from "./portfolio/index.js";
 export * from "./project/index.js";
+export * from "./pwa/index.js";
+export * from "./realtime/index.js";
+export * from "./queues/index.js";
 export * from "./schema/index.js";
+export * from "./security/index.js";
+export * from "./seo/index.js";
+export * from "./status.js";
 export * from "./worker/index.js";
+export * from "./workflow/index.js";

package/dist/map/index.d.ts

@@ -0,0 +1,3 @@
+export { ASTROID_MAP_DEPENDENCIES, ASTROID_PMTILES_KEY, ASTROID_PMTILES_PATH, generateMapEmbedComponent, generateMapTileRoute, usesMap, } from "./scaffold.js";
+export { type ParsedRange, parseRangeHeader, type PmtilesHandlerOptions, type RangeObject, type RangeReader, type RangeSpec, servePmtiles, } from "./pmtiles.js";
+export { astroidMapStyle, type MapColors, type MapStyle, type MapStyleOptions } from "./style.js";