astroidjs 0.1.1 → 0.2.0

package/dist/map/pmtiles.js

@@ -0,0 +1,130 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// Byte-range serving from R2 — the plumbing under the self-hosted basemap.
+//
+// A PMTiles archive is one immutable blob, often hundreds of megabytes, and the
+// client reads a few kilobytes at a time: a header, then directory pages, then
+// individual tiles. That only works if the server honours HTTP range requests,
+// which is the whole reason this file exists rather than a plain R2 passthrough.
+//
+// Serving it same-origin (rather than off a media domain) is what keeps the CSP
+// at `connect-src 'self'` with no external tile host and no API key, and
+// sidesteps any CORS policy on the bucket.
+//
+// The range parsing is deliberately complete. The implementation this
+// generalizes matched only `bytes=<start>-<end?>`, so a SUFFIX range
+// (`bytes=-20000`, "the last 20 KB" — how a client reads a footer without
+// knowing the length) fell through to serving the ENTIRE archive. That is a
+// correct-looking response and a catastrophic one.
+/**
+ * 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 function parseRangeHeader(header, size) {
+    if (!header)
+        return null;
+    const value = header.trim();
+    if (!value.startsWith("bytes="))
+        return null;
+    const spec = value.slice("bytes=".length).trim();
+    if (spec.includes(","))
+        return null;
+    const suffix = /^-(\d+)$/.exec(spec);
+    if (suffix) {
+        const n = Number(suffix[1]);
+        // "last 0 bytes" is unsatisfiable per RFC 9110; a suffix larger than the
+        // object legally means the whole object.
+        if (n === 0)
+            return { kind: "unsatisfiable" };
+        return { kind: "suffix", suffix: Math.min(n, size) };
+    }
+    const bounded = /^(\d+)-(\d*)$/.exec(spec);
+    if (!bounded)
+        return null;
+    const start = Number(bounded[1]);
+    if (start >= size)
+        return { kind: "unsatisfiable" };
+    if (bounded[2] === "")
+        return { kind: "range", offset: start };
+    const end = Number(bounded[2]);
+    if (end < start)
+        return { kind: "unsatisfiable" };
+    // An end past the object is clamped, not an error — a client asking for more
+    // than exists gets what exists.
+    return { kind: "range", offset: start, length: Math.min(end, size - 1) - start + 1 };
+}
+const CONTENT_TYPE = "application/octet-stream";
+/**
+ * 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 async function servePmtiles(request, options) {
+    const { read, cacheControl = "public, max-age=86400" } = options;
+    const headers = (extra) => ({
+        "content-type": CONTENT_TYPE,
+        "accept-ranges": "bytes",
+        "cache-control": cacheControl,
+        ...extra,
+    });
+    // HEAD is how a client discovers the length before ranging into the archive.
+    const head = request.method === "HEAD";
+    const rangeHeader = request.headers.get("range");
+    // Without the size, an unsatisfiable range can't be told from a valid one, so
+    // the object is fetched first when a range is present.
+    const probe = rangeHeader ? await read() : null;
+    if (rangeHeader && !probe)
+        return new Response("Basemap not found", { status: 404 });
+    const size = probe?.size ?? 0;
+    const parsed = rangeHeader ? parseRangeHeader(rangeHeader, size) : null;
+    if (parsed?.kind === "unsatisfiable") {
+        return new Response(null, {
+            status: 416,
+            // RFC 9110: a 416 states the object's real length so the client can retry.
+            headers: headers({ "content-range": `bytes */${size}` }),
+        });
+    }
+    if (parsed) {
+        const object = await read(parsed.kind === "suffix"
+            ? { suffix: parsed.suffix }
+            : { offset: parsed.offset, ...(parsed.length ? { length: parsed.length } : {}) });
+        if (!object)
+            return new Response("Basemap not found", { status: 404 });
+        // Trust what R2 says it returned rather than what was asked for — it clamps
+        // ranges, and a Content-Range that disagrees with the body corrupts the
+        // client's view of the archive.
+        const got = object.range ?? {};
+        const start = got.offset ?? (parsed.kind === "suffix" ? object.size - parsed.suffix : parsed.offset);
+        const length = got.length ?? (got.suffix ?? object.size - start);
+        return new Response(head ? null : (object.body ?? null), {
+            status: 206,
+            headers: headers({
+                "content-range": `bytes ${start}-${start + length - 1}/${object.size}`,
+                "content-length": String(length),
+            }),
+        });
+    }
+    const object = await read();
+    if (!object)
+        return new Response("Basemap not found", { status: 404 });
+    return new Response(head ? null : (object.body ?? null), {
+        headers: headers({ "content-length": String(object.size) }),
+    });
+}

package/dist/map/scaffold.d.ts

@@ -0,0 +1,29 @@
+import type { AstroidConfig } from "../config.js";
+/** Default R2 object key for the basemap archive. */
+export declare const ASTROID_PMTILES_KEY = "map/basemap.pmtiles";
+/** Default route the archive is served from, same-origin. */
+export declare const ASTROID_PMTILES_PATH = "/map/basemap.pmtiles";
+/** True when this project switched the map module on. */
+export declare const usesMap: (config: AstroidConfig) => boolean;
+/**
+ * `src/pages/map/basemap.pmtiles.ts` — the range-serving tile route.
+ *
+ * Thin: `servePmtiles` owns range parsing, the 206/416 contract, and trusting
+ * R2's clamped range over the requested one. What's here is which bucket and
+ * which key.
+ */
+export declare function generateMapTileRoute(config: AstroidConfig): string | null;
+/**
+ * `src/components/MapEmbed.astro` — the map itself.
+ *
+ * The lazy load is not an optimisation detail, it's the reason this is usable:
+ * MapLibre is ~1 MB, and a location map is almost always below the fold. The
+ * library is fetched only once a container nears the viewport, and memoized so
+ * two maps on a page download it once.
+ */
+export declare function generateMapEmbedComponent(config: AstroidConfig): string | null;
+/** The npm dependencies the map module needs in the scaffold. */
+export declare const ASTROID_MAP_DEPENDENCIES: {
+    readonly "maplibre-gl": "^5.9.0";
+    readonly pmtiles: "^4.4.0";
+};

package/dist/map/scaffold.js

@@ -0,0 +1,212 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The map module's scaffold-once files: the tile route and `<MapEmbed>`.
+//
+// GENERATED rather than shipped as a component, for a concrete reason. MapLibre
+// GL is ~1 MB and `pmtiles` is its companion; a `MapEmbed.astro` living in
+// astroid's own `src/components/` would make both a hard requirement of the
+// package — every project installing them, and the CI probe that type-checks
+// the component library needing them too — for a feature most sites never turn
+// on. Generating the component into the projects that enable the module keeps
+// the dependency where the decision was made.
+//
+// It also puts the pin, the gesture handling, and the placeholder in the
+// project's hands, which is right: those are brand, and brand is site-owned.
+/** Default R2 object key for the basemap archive. */
+export const ASTROID_PMTILES_KEY = "map/basemap.pmtiles";
+/** Default route the archive is served from, same-origin. */
+export const ASTROID_PMTILES_PATH = "/map/basemap.pmtiles";
+/** True when this project switched the map module on. */
+export const usesMap = (config) => (config.modules ?? []).includes("map");
+/**
+ * `src/pages/map/basemap.pmtiles.ts` — the range-serving tile route.
+ *
+ * Thin: `servePmtiles` owns range parsing, the 206/416 contract, and trusting
+ * R2's clamped range over the requested one. What's here is which bucket and
+ * which key.
+ */
+export function generateMapTileRoute(config) {
+    if (!usesMap(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",
+        "// ranges it needs per tile.",
+        "//",
+        "// Same-origin is the point: no external tile host and no API key means the",
+        "// CSP stays at `connect-src 'self'`, and any CORS policy on the bucket is",
+        "// 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",
+        "// broken):",
+        `//   wrangler r2 object put ${config.key}-media/${ASTROID_PMTILES_KEY} \\`,
+        "//     --file=extract.pmtiles --content-type=application/octet-stream --remote",
+        "//",
+        "// Build an extract for your area with the Protomaps CLI:",
+        "//   pmtiles extract https://build.protomaps.com/<date>.pmtiles extract.pmtiles \\",
+        "//     --bbox=<minLon,minLat,maxLon,maxLat>",
+        'import type { APIRoute } from "astro";',
+        'import { servePmtiles } from "astroidjs";',
+        'import { env } from "cloudflare:workers";',
+        "",
+        "export const prerender = false;",
+        "",
+        `const KEY = ${JSON.stringify(ASTROID_PMTILES_KEY)};`,
+        "",
+        "export const GET: APIRoute = ({ request }) =>",
+        "  servePmtiles(request, {",
+        "    // The reader is a closure rather than the bucket itself: R2Bucket.get is",
+        "    // overloaded with a required-options first signature, which no structural",
+        "    // interface can accept. Calling it here uses R2's own types.",
+        "    read: (range) => env.MEDIA.get(KEY, range ? { range } : undefined),",
+        "  });",
+        "",
+        "// HEAD lets a client learn the archive's length before ranging into it.",
+        "export const HEAD = GET;",
+        "",
+    ].join("\n");
+}
+/**
+ * `src/components/MapEmbed.astro` — the map itself.
+ *
+ * The lazy load is not an optimisation detail, it's the reason this is usable:
+ * MapLibre is ~1 MB, and a location map is almost always below the fold. The
+ * library is fetched only once a container nears the viewport, and memoized so
+ * two maps on a page download it once.
+ */
+export function generateMapEmbedComponent(config) {
+    if (!usesMap(config))
+        return null;
+    const brand = config.theme.colors.brand;
+    return [
+        "---",
+        "// A MapLibre map over the self-hosted PMTiles basemap, centred on exact",
+        "// 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",
+        "// a network call that can fail, drift, or land on the wrong side of the",
+        "// street. Renders the slot (your placeholder) when they're missing.",
+        'import { astroidMapStyle } from "astroidjs";',
+        "",
+        "interface Props {",
+        "  // Section fields arrive as strings; a literal number is fine too.",
+        "  lat?: number | string;",
+        "  lng?: number | string;",
+        "  zoom?: number;",
+        "  aspect?: string;",
+        "}",
+        "",
+        'const { lat, lng, zoom = 15, aspect = "4/3" } = Astro.props;',
+        'const num = (v: number | string | undefined) => (v === "" || v == null ? Number.NaN : Number(v));',
+        "const nlat = num(lat);",
+        "const nlng = num(lng);",
+        "const show = Number.isFinite(nlat) && Number.isFinite(nlng);",
+        "",
+        "// Built here and handed to the client as data, so the brand palette lives in",
+        "// one place instead of being duplicated into the script.",
+        "const style = JSON.stringify(",
+        "  astroidMapStyle({",
+        `    pmtilesUrl: ${JSON.stringify(ASTROID_PMTILES_PATH)},`,
+        `    colors: { water: ${JSON.stringify(brand)} },`,
+        "  }),",
+        ");",
+        "---",
+        "",
+        "{",
+        "  show ? (",
+        '    <div',
+        '      class="astroid-map"',
+        "      data-astroid-map",
+        "      data-lat={nlat}",
+        "      data-lng={nlng}",
+        "      data-zoom={zoom}",
+        "      data-style={style}",
+        "      style={`aspect-ratio:${aspect}`}",
+        "    />",
+        "  ) : (",
+        "    <slot />",
+        "  )",
+        "}",
+        "",
+        "<style>",
+        "  .astroid-map {",
+        "    overflow: hidden;",
+        "    border-radius: 1rem;",
+        `    background: ${brand}1a;`,
+        "  }",
+        "</style>",
+        "",
+        "<script>",
+        "  // MapLibre is ~1 MB and a location map is almost always below the fold, so",
+        "  // nothing is downloaded until a container nears the viewport. The loader is",
+        "  // memoized: two maps on a page fetch the library once.",
+        '  const els = [...document.querySelectorAll<HTMLElement>("[data-astroid-map]")];',
+        "",
+        "  if (els.length > 0) {",
+        "    let loader: Promise<{ maplibregl: any; Protocol: any }> | null = null;",
+        "    const load = () =>",
+        "      (loader ??= Promise.all([",
+        '        import("maplibre-gl"),',
+        '        import("pmtiles"),',
+        '        import("maplibre-gl/dist/maplibre-gl.css"),',
+        "      ]).then(([maplibre, pmtiles]) => ({",
+        "        // maplibre-gl ships as CJS: under ESM interop the API may be on",
+        "        // `.default` or be the namespace itself. Accept either.",
+        "        maplibregl: (maplibre as any).default ?? maplibre,",
+        "        Protocol: (pmtiles as any).Protocol,",
+        "      })));",
+        "",
+        "    const init = async (el: HTMLElement) => {",
+        '      const lat = Number(el.dataset.lat);',
+        '      const lng = Number(el.dataset.lng);',
+        "      if (!Number.isFinite(lat) || !Number.isFinite(lng)) return;",
+        "",
+        "      const { maplibregl, Protocol } = await load();",
+        '      // Register the pmtiles:// protocol once so MapLibre range-reads the',
+        "      // archive instead of requesting tile URLs.",
+        '      maplibregl.addProtocol("pmtiles", new Protocol().tile);',
+        "",
+        "      const map = new maplibregl.Map({",
+        "        container: el,",
+        '        style: JSON.parse(el.dataset.style ?? "{}"),',
+        "        center: [lng, lat],",
+        '        zoom: Number(el.dataset.zoom ?? 15),',
+        "        // A map that swallows page scroll is a trap on mobile; cooperative",
+        "        // gestures require an explicit modifier/two fingers to pan.",
+        "        cooperativeGestures: true,",
+        "        dragRotate: false,",
+        "        pitchWithRotate: false,",
+        "        touchPitch: false,",
+        "      });",
+        '      map.addControl(new maplibregl.NavigationControl({ showCompass: false }), "top-right");',
+        "",
+        "      const pin = document.createElement(\"div\");",
+        "      pin.style.cssText =",
+        `        "width:18px;height:18px;border-radius:999px;background:${brand};" +`,
+        '        "border:3px solid #fff;box-shadow:0 0 0 6px rgba(0,0,0,0.12);";',
+        "      new maplibregl.Marker({ element: pin }).setLngLat([lng, lat]).addTo(map);",
+        "    };",
+        "",
+        "    const io = new IntersectionObserver(",
+        "      (entries, obs) => {",
+        "        for (const entry of entries) {",
+        "          if (!entry.isIntersecting) continue;",
+        "          obs.unobserve(entry.target);",
+        "          init(entry.target as HTMLElement);",
+        "        }",
+        "      },",
+        '      { rootMargin: "200px" },',
+        "    );",
+        "    for (const el of els) io.observe(el);",
+        "  }",
+        "</script>",
+        "",
+    ].join("\n");
+}
+/** The npm dependencies the map module needs in the scaffold. */
+export const ASTROID_MAP_DEPENDENCIES = {
+    "maplibre-gl": "^5.9.0",
+    pmtiles: "^4.4.0",
+};

package/dist/map/style.d.ts

@@ -0,0 +1,58 @@
+/** Brand colours the style is built from. Every one has a sensible default, so
+ *  `astroidMapStyle({ pmtilesUrl })` already produces a usable map. */
+export interface MapColors {
+    /** Land / page background. */
+    land?: string;
+    water?: string;
+    /** Parks, woods, scrub. */
+    green?: string;
+    /** Minor roads. */
+    road?: string;
+    /** Arterials and highways. */
+    arterial?: string;
+    /** Hairline road edges. */
+    casing?: string;
+    building?: string;
+    boundary?: string;
+    /** Label ink, when `glyphs` is supplied. */
+    label?: string;
+    /** Label halo, when `glyphs` is supplied. */
+    labelHalo?: string;
+}
+export interface MapStyleOptions {
+    /**
+     * URL of the archive, same-origin. Passed to MapLibre as `pmtiles://<url>`,
+     * which the `pmtiles` protocol handler turns into range reads.
+     */
+    pmtilesUrl: string;
+    colors?: MapColors;
+    /**
+     * SDF glyph URL template (e.g. `"/map/fonts/{fontstack}/{range}.pbf"`).
+     * Omit for an unlabelled map — which is the honest default, since labels
+     * without self-hosted glyphs mean an external font host and a looser CSP.
+     */
+    glyphs?: string;
+    /** Font stack for labels. Only used when `glyphs` is set. */
+    fontstack?: string;
+    /** Attribution shown in the corner. Protomaps basemaps derive from OSM, and
+     *  the licence requires the credit — so it defaults to present, not absent. */
+    attribution?: string;
+}
+/** A MapLibre style. Typed loosely on purpose — see the header. */
+export interface MapStyle {
+    version: 8;
+    glyphs?: string;
+    sources: Record<string, unknown>;
+    layers: Record<string, unknown>[];
+}
+/**
+ * Build a brand-recoloured basemap style over a self-hosted PMTiles archive.
+ *
+ * ```ts
+ * const style = astroidMapStyle({
+ *   pmtilesUrl: `${location.origin}/map/basemap.pmtiles`,
+ *   colors: { water: theme.colors.brand },
+ * });
+ * ```
+ */
+export declare function astroidMapStyle(options: MapStyleOptions): MapStyle;

package/dist/map/style.js

@@ -0,0 +1,154 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// A MapLibre style, built from brand colours.
+//
+// Deliberately dependency-free: a style is JSON, so this returns a plain object
+// rather than importing `maplibre-gl` (a megabyte) or `protomaps-themes-base`
+// for its types. astroidjs stays installable by a project that will never draw
+// a map, and a project that wants Protomaps' full maintained theme can swap
+// this out — the only contract is "an object MapLibre accepts".
+//
+// The layer set is the quiet-basemap subset: land, water, green space, a road
+// ramp with casings, buildings, and admin boundaries. Labels are opt-in and
+// need `glyphs`, because self-hosted SDF glyph ranges are a provisioning step
+// (and the reason the reference site could keep `font-src 'self'`).
+//
+// Source layer names follow the Protomaps v3 schema, which is what a `pmtiles`
+// archive built with `pmtiles extract` / planetiler contains.
+const DEFAULTS = {
+    land: "#faf7ef",
+    water: "#9fdad8",
+    green: "#e9efdc",
+    road: "#fffdf7",
+    arterial: "#f3eee0",
+    casing: "#ece5d2",
+    building: "#f0e9d9",
+    boundary: "#cfc6b0",
+    label: "#2a2a2a",
+    labelHalo: "#fffdf7",
+};
+/**
+ * Build a brand-recoloured basemap style over a self-hosted PMTiles archive.
+ *
+ * ```ts
+ * const style = astroidMapStyle({
+ *   pmtilesUrl: `${location.origin}/map/basemap.pmtiles`,
+ *   colors: { water: theme.colors.brand },
+ * });
+ * ```
+ */
+export function astroidMapStyle(options) {
+    const c = { ...DEFAULTS, ...options.colors };
+    const { pmtilesUrl, glyphs, fontstack = "Noto Sans Regular", attribution = '<a href="https://openstreetmap.org">OpenStreetMap</a> · <a href="https://protomaps.com">Protomaps</a>', } = options;
+    const layers = [
+        { id: "background", type: "background", paint: { "background-color": c.land } },
+        {
+            id: "earth",
+            type: "fill",
+            source: "protomaps",
+            "source-layer": "earth",
+            paint: { "fill-color": c.land },
+        },
+        {
+            id: "landuse",
+            type: "fill",
+            source: "protomaps",
+            "source-layer": "landuse",
+            // Only the green classes; leaving the rest unpainted keeps the map quiet
+            // rather than blotchy.
+            filter: ["in", "pmap:kind", "park", "forest", "wood", "grass", "scrub", "farmland"],
+            paint: { "fill-color": c.green },
+        },
+        {
+            id: "water",
+            type: "fill",
+            source: "protomaps",
+            "source-layer": "water",
+            paint: { "fill-color": c.water },
+        },
+        {
+            id: "buildings",
+            type: "fill",
+            source: "protomaps",
+            "source-layer": "buildings",
+            // Buildings only resolve once you're zoomed in; drawing them earlier is
+            // noise at city scale.
+            minzoom: 14,
+            paint: { "fill-color": c.building },
+        },
+        // Casings sit UNDER the road fills, so a road reads as a stroked ribbon
+        // rather than a flat band. Order matters more than colour here.
+        {
+            id: "roads-casing",
+            type: "line",
+            source: "protomaps",
+            "source-layer": "roads",
+            paint: {
+                "line-color": c.casing,
+                "line-width": ["interpolate", ["exponential", 1.6], ["zoom"], 10, 1.5, 16, 10],
+            },
+        },
+        {
+            id: "roads",
+            type: "line",
+            source: "protomaps",
+            "source-layer": "roads",
+            paint: {
+                "line-color": [
+                    "match",
+                    ["get", "pmap:kind"],
+                    "highway",
+                    c.arterial,
+                    "major_road",
+                    c.arterial,
+                    c.road,
+                ],
+                "line-width": ["interpolate", ["exponential", 1.6], ["zoom"], 10, 0.8, 16, 7],
+            },
+        },
+        {
+            id: "boundaries",
+            type: "line",
+            source: "protomaps",
+            "source-layer": "boundaries",
+            paint: { "line-color": c.boundary, "line-width": 0.8, "line-dasharray": [3, 2] },
+        },
+    ];
+    if (glyphs) {
+        layers.push({
+            id: "roads-labels",
+            type: "symbol",
+            source: "protomaps",
+            "source-layer": "roads",
+            minzoom: 14,
+            layout: {
+                "text-field": ["get", "name"],
+                "text-font": [fontstack],
+                "text-size": 11,
+                "symbol-placement": "line",
+            },
+            paint: { "text-color": c.label, "text-halo-color": c.labelHalo, "text-halo-width": 1.5 },
+        }, {
+            id: "places-labels",
+            type: "symbol",
+            source: "protomaps",
+            "source-layer": "places",
+            layout: { "text-field": ["get", "name"], "text-font": [fontstack], "text-size": 13 },
+            paint: { "text-color": c.label, "text-halo-color": c.labelHalo, "text-halo-width": 1.5 },
+        });
+    }
+    return {
+        version: 8,
+        ...(glyphs ? { glyphs } : {}),
+        sources: {
+            protomaps: {
+                type: "vector",
+                // The `pmtiles://` prefix is what routes reads through the protocol
+                // handler the page registers, instead of MapLibre fetching tile URLs.
+                url: `pmtiles://${pmtilesUrl}`,
+                attribution,
+            },
+        },
+        layers,
+    };
+}

package/dist/portal/config.d.ts

@@ -0,0 +1,26 @@
+import type { AstroidConfig } from "../config.js";
+import type { PortalGuardConfig, PortalRoute } from "./guard.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 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. */
+export declare const ASTROID_PORTAL_TABLE_PREFIX = "portal_";
+/** Everything the generated portal wiring needs, defaults applied. */
+export interface ResolvedPortal {
+    enabled: boolean;
+    basePath: string;
+    cookiePrefix: string;
+    tablePrefix: string;
+    roles: string[];
+    /** First role in `roles` — what a newly created account gets. */
+    defaultRole: string;
+    routes: PortalRoute[];
+    home: Record<string, string>;
+    signUp: boolean;
+    gated: boolean;
+}
+/** Resolve the portal block, or null when the project has no portal. */
+export declare function astroidPortal(config: AstroidConfig): ResolvedPortal | null;
+/** The guard config for a project, ready to hand to `portalGuard`. */
+export declare function astroidPortalGuardConfig(config: AstroidConfig): PortalGuardConfig | null;

package/dist/portal/config.js

@@ -0,0 +1,50 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// 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.
+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. */
+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" }];
+/** Resolve the portal block, or null when the project has no portal. */
+export function astroidPortal(config) {
+    const portal = config.portal;
+    if (!portal?.enabled)
+        return null;
+    const roles = portal.roles?.length ? portal.roles : ["customer"];
+    return {
+        enabled: true,
+        basePath: ASTROID_PORTAL_BASE_PATH,
+        cookiePrefix: ASTROID_PORTAL_COOKIE_PREFIX,
+        tablePrefix: ASTROID_PORTAL_TABLE_PREFIX,
+        roles,
+        defaultRole: roles[0],
+        routes: portal.routes?.length ? portal.routes : DEFAULT_ROUTES,
+        home: portal.home ?? {},
+        signUp: portal.signUp ?? false,
+        gated: portal.gated ?? false,
+    };
+}
+/** The guard config for a project, ready to hand to `portalGuard`. */
+export function astroidPortalGuardConfig(config) {
+    const portal = astroidPortal(config);
+    if (!portal)
+        return null;
+    return {
+        routes: portal.routes,
+        loginPath: "/login",
+        home: (role) => portal.home[role] ?? "/portal",
+    };
+}