astroidjs 0.1.2 → 0.2.0

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,19 @@
+export * from "./analytics/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,22 @@
 // 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 "./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";

package/dist/map/index.js

@@ -0,0 +1,4 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+export { ASTROID_MAP_DEPENDENCIES, ASTROID_PMTILES_KEY, ASTROID_PMTILES_PATH, generateMapEmbedComponent, generateMapTileRoute, usesMap, } from "./scaffold.js";
+export { parseRangeHeader, servePmtiles, } from "./pmtiles.js";
+export { astroidMapStyle } from "./style.js";

package/dist/map/pmtiles.d.ts

@@ -0,0 +1,92 @@
+/**
+ * A byte range, shaped to be assignable to Cloudflare's `R2Range`.
+ *
+ * All-optional fields would NOT be: `R2Range` is a union whose members each
+ * require something (`{offset, length?}` | `{suffix}`), so a loose shape
+ * satisfies none of them.
+ */
+export type RangeSpec = {
+    offset: number;
+    length?: number;
+} | {
+    suffix: number;
+};
+/**
+ * How the archive is read. A function rather than a bucket interface, and
+ * deliberately so: `R2Bucket.get` is overloaded, and its first overload
+ * *requires* an options argument — which means no structural interface with an
+ * optional second parameter can accept a real `R2Bucket`. Taking a reader lets
+ * the call site use R2's own types and resolves the mismatch at the source, and
+ * incidentally makes this work over any storage rather than only R2.
+ */
+export type RangeReader = (range?: RangeSpec) => Promise<RangeObject | null>;
+export interface RangeObject {
+    /**
+     * Optional because `R2Bucket.get` is overloaded and its conditional form
+     * resolves to `R2Object`, which carries no body at all. Requiring one here
+     * makes a real `R2Bucket` fail to satisfy this interface.
+     */
+    body?: ReadableStream | null;
+    /** Size of the WHOLE object, not the returned slice. */
+    size: number;
+    /** What R2 actually returned — it clamps a range that runs past the end. */
+    range?: {
+        offset?: number;
+        length?: number;
+        suffix?: number;
+    };
+}
+/** A parsed `Range` header. */
+export type ParsedRange = {
+    kind: "range";
+    offset: number;
+    length?: number;
+} | {
+    kind: "suffix";
+    suffix: number;
+}
+/** Syntactically valid but unsatisfiable against this object → 416. */
+ | {
+    kind: "unsatisfiable";
+}
+/** Absent or unparseable → serve the whole object (per RFC 9110, an
+ *  unparseable Range is ignored rather than rejected). */
+ | null;
+/**
+ * Parse a `Range` header into something R2 understands.
+ *
+ * Handles the three forms that matter:
+ *   `bytes=0-1023`   a bounded window
+ *   `bytes=1024-`    open-ended, to the end
+ *   `bytes=-20000`   the LAST n bytes — the one the reference dropped
+ *
+ * Multi-range (`bytes=0-99,200-299`) returns null: it requires a multipart
+ * response no PMTiles client asks for, and serving the whole object is the
+ * spec-legal fallback.
+ */
+export declare function parseRangeHeader(header: string | null, size: number): ParsedRange;
+export interface PmtilesHandlerOptions {
+    /** Reads the archive, whole or by range. See {@link RangeReader}. */
+    read: RangeReader;
+    /**
+     * `Cache-Control` for the response. An archive is immutable — a re-clip
+     * overwrites the object wholesale — so the byte ranges cache hard at the
+     * edge. Default one day.
+     */
+    cacheControl?: string;
+}
+/**
+ * Serve a PMTiles archive from R2 with range support.
+ *
+ * ```ts
+ * export const GET: APIRoute = ({ request }) =>
+ *   servePmtiles(request, {
+ *     read: (range) => env.MEDIA.get(KEY, range ? { range } : undefined),
+ *   });
+ * ```
+ *
+ * A missing archive is a 404, not an error: the map module is usable before
+ * anyone has uploaded a basemap (the canvas renders its background and pin),
+ * which is the same dormant-until-provisioned posture as every other module.
+ */
+export declare function servePmtiles(request: Request, options: PmtilesHandlerOptions): Promise<Response>;