astroidjs 0.1.1 → 0.2.0

package/dist/portal/guard.d.ts

@@ -0,0 +1,48 @@
+/** A signed-in portal user, as far as the guard is concerned. */
+export interface PortalUser {
+    role: string;
+    [key: string]: unknown;
+}
+/** One rule: everything under `prefix` requires one of `roles`. */
+export interface PortalRoute {
+    /** Path prefix, e.g. `/portal` — matches the prefix itself and everything
+     *  beneath it, but NOT `/portalling`. */
+    prefix: string;
+    /** Roles allowed through. Empty means "any signed-in user". */
+    roles?: string[];
+}
+export interface PortalGuardConfig {
+    /** The rule table, in order. The first matching prefix decides. */
+    routes: PortalRoute[];
+    /** Where to send a signed-out visitor. Default `/login`. */
+    loginPath?: string;
+    /** Landing page for a signed-in user, by role — used to bounce someone who
+     *  reached an area they don't belong in. Default `/portal` for everyone. */
+    home?: (role: string) => string;
+}
+/** What the guard decided. `null` means "carry on". */
+export type GuardDecision = null | {
+    kind: "redirect";
+    location: string;
+} | {
+    kind: "json";
+    status: 401 | 403;
+    body: {
+        ok: false;
+        error: string;
+    };
+};
+/** Prefix match on a path SEGMENT boundary — `/portal` covers `/portal` and
+ *  `/portal/orders`, but never `/portalling`. */
+export declare function matchesPrefix(path: string, prefix: string): boolean;
+/**
+ * Decide whether a request may proceed.
+ *
+ * Pure — it returns a decision rather than a `Response`, so it's testable
+ * without an Astro context and the middleware stays responsible for turning a
+ * decision into a redirect or a body.
+ */
+export declare function portalGuard(path: string, user: PortalUser | null, config: PortalGuardConfig): GuardDecision;
+/** Turn a decision into a `Response`. `redirect` is left to the caller, since
+ *  Astro's context builds those with its own base-path handling. */
+export declare function guardResponse(decision: Exclude<GuardDecision, null>): Response | null;

package/dist/portal/guard.js

@@ -0,0 +1,64 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// Role-gated routing for the portal.
+//
+// coracle and ghostfire independently built the same thing: a declarative table
+// of `prefix → roles`, walked once per request. Declarative rather than a guard
+// call inside each page, because a guard you have to remember to write is a
+// guard someone eventually forgets — and the page that forgets it is the one
+// that leaks.
+//
+// Three answers, and which one you give matters:
+//
+//   not signed in, HTML   → redirect to the login page, carrying `next`
+//   not signed in, API    → 401 JSON (a redirect to an HTML login page is
+//                           useless to fetch(); it looks like success)
+//   signed in, wrong role → 403 for API, and for HTML a redirect to the area
+//                           this user DOES have — not back to login, which
+//                           reads as "your password failed" when it didn't
+/** Prefix match on a path SEGMENT boundary — `/portal` covers `/portal` and
+ *  `/portal/orders`, but never `/portalling`. */
+export function matchesPrefix(path, prefix) {
+    return path === prefix || path.startsWith(`${prefix}/`);
+}
+/**
+ * Decide whether a request may proceed.
+ *
+ * Pure — it returns a decision rather than a `Response`, so it's testable
+ * without an Astro context and the middleware stays responsible for turning a
+ * decision into a redirect or a body.
+ */
+export function portalGuard(path, user, config) {
+    const rule = config.routes.find((r) => matchesPrefix(path, r.prefix));
+    if (!rule)
+        return null;
+    // An API route answers in JSON whatever happens: redirecting `fetch()` to an
+    // HTML login page returns 200 and a page of markup, which client code reads
+    // as success and then fails on somewhere far less obvious.
+    const isApi = path.startsWith("/api/");
+    if (!user) {
+        if (isApi)
+            return { kind: "json", status: 401, body: { ok: false, error: "Unauthorized" } };
+        const login = config.loginPath ?? "/login";
+        return { kind: "redirect", location: `${login}?next=${encodeURIComponent(path)}` };
+    }
+    const allowed = !rule.roles?.length || rule.roles.includes(user.role);
+    if (!allowed) {
+        if (isApi)
+            return { kind: "json", status: 403, body: { ok: false, error: "Forbidden" } };
+        // Signed in, wrong door. Sending them back to /login would say "your
+        // credentials failed" about credentials that worked fine.
+        return { kind: "redirect", location: config.home?.(user.role) ?? "/portal" };
+    }
+    return null;
+}
+/** Turn a decision into a `Response`. `redirect` is left to the caller, since
+ *  Astro's context builds those with its own base-path handling. */
+export function guardResponse(decision) {
+    if (decision.kind === "redirect")
+        return null;
+    return new Response(JSON.stringify(decision.body), {
+        status: decision.status,
+        headers: { "content-type": "application/json" },
+    });
+}

package/dist/portal/index.d.ts

@@ -0,0 +1,5 @@
+export { ASTROID_PORTAL_COOKIE_PREFIX, ASTROID_PORTAL_TABLE_PREFIX, astroidPortal, astroidPortalGuardConfig, type ResolvedPortal, } from "./config.js";
+export { type GuardDecision, guardResponse, matchesPrefix, portalGuard, type PortalGuardConfig, type PortalRoute, type PortalUser, } from "./guard.js";
+export { definePortalNav, type PortalNav, type PortalNavItem } from "./nav.js";
+export { generateAstroidPortalAuth, generateAstroidPortalAuthRoute, generateAstroidPortalLocals, } from "./scaffold.js";
+export { type CustomerGuardResult, isSameOrigin, json, type PortalSessionResolver, requireCustomer, resolvePortalSession, } from "./session.js";

package/dist/portal/index.js

@@ -0,0 +1,6 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+export { ASTROID_PORTAL_COOKIE_PREFIX, ASTROID_PORTAL_TABLE_PREFIX, astroidPortal, astroidPortalGuardConfig, } from "./config.js";
+export { guardResponse, matchesPrefix, portalGuard, } from "./guard.js";
+export { definePortalNav } from "./nav.js";
+export { generateAstroidPortalAuth, generateAstroidPortalAuthRoute, generateAstroidPortalLocals, } from "./scaffold.js";
+export { isSameOrigin, json, requireCustomer, resolvePortalSession, } from "./session.js";

package/dist/portal/nav.d.ts

@@ -0,0 +1,26 @@
+export interface PortalNavItem {
+    label: string;
+    href: string;
+    /** Roles that may see this item. Omit for "everyone signed in". */
+    roles?: string[];
+    /** Optional icon name, passed through to the shell's slot. */
+    icon?: string;
+}
+export interface PortalNav {
+    items: PortalNavItem[];
+    /** The items this role may see. */
+    forRole(role: string | null | undefined): PortalNavItem[];
+    /** The item matching a path, by the same prefix rule the guard uses. */
+    activeFor(path: string): PortalNavItem | null;
+}
+/**
+ * Declare the portal navigation.
+ *
+ * ```ts
+ * export const nav = definePortalNav([
+ *   { label: "Orders", href: "/portal/orders" },
+ *   { label: "Team", href: "/admin/team", roles: ["manager"] },
+ * ]);
+ * ```
+ */
+export declare function definePortalNav(items: PortalNavItem[]): PortalNav;

package/dist/portal/nav.js

@@ -0,0 +1,35 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The portal's navigation, as data.
+//
+// Two things fall out of declaring it rather than writing markup per page.
+// Items can be filtered by the viewer's role in one place — so an item a user
+// can't reach is never rendered, instead of rendered-then-403'd, which reads as
+// a broken link. And "which item is active" is computed the same way the guard
+// matches prefixes, so the highlight can't disagree with the routing.
+import { matchesPrefix } from "./guard.js";
+/**
+ * Declare the portal navigation.
+ *
+ * ```ts
+ * export const nav = definePortalNav([
+ *   { label: "Orders", href: "/portal/orders" },
+ *   { label: "Team", href: "/admin/team", roles: ["manager"] },
+ * ]);
+ * ```
+ */
+export function definePortalNav(items) {
+    return {
+        items,
+        forRole(role) {
+            return items.filter((item) => !item.roles?.length || (role ? item.roles.includes(role) : false));
+        },
+        activeFor(path) {
+            // Longest href first, so `/portal/orders` wins over `/portal` on a page
+            // both would match — otherwise the parent item is always the active one.
+            return ([...items]
+                .sort((a, b) => b.href.length - a.href.length)
+                .find((item) => matchesPrefix(path, item.href)) ?? null);
+        },
+    };
+}

package/dist/portal/scaffold.d.ts

@@ -0,0 +1,28 @@
+import type { AstroidConfig } from "../config.js";
+/**
+ * `src/portal-auth.ts` — the portal Better Auth instance and its session
+ * resolver.
+ *
+ * Returns null when the project has no portal.
+ */
+export declare function generateAstroidPortalAuth(config: AstroidConfig): string | null;
+/**
+ * `src/pages/api/portal-auth/[...all].ts` — the portal's Better Auth catch-all,
+ * mounted at its own basePath so it never collides with the studio's
+ * `/api/auth`.
+ *
+ * Lives here rather than as a literal in `create-astroid` for the same reason
+ * the archetype sections moved (#277): the scaffolder is plain JS, so a drifted
+ * import path there is invisible until a user's build fails. It is also the half
+ * `generateAstroidPortalAuth` is useless without — `src/portal-auth.ts` exports
+ * `handlePortalAuth`, and nothing calls it unless this route exists.
+ *
+ * Returns null when the project has no portal.
+ */
+export declare function generateAstroidPortalAuthRoute(config: AstroidConfig): string | null;
+/**
+ * The `App.Locals` member the portal adds, as a block `create-astroid`
+ * substitutes into `src/env.d.ts`. Empty without a portal — a project that
+ * types `portalUser` it never sets is inviting a null-check nobody needs.
+ */
+export declare function generateAstroidPortalLocals(config: AstroidConfig): string;

package/dist/portal/scaffold.js

@@ -0,0 +1,140 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The portal's SCAFFOLD-ONCE pieces: the second Better Auth instance, and the
+// `App.Locals` / `CloudflareEnv` additions that come with it.
+//
+// The auth instance is scaffolded rather than generated because a site edits it
+// — the reset email, the role a new account gets, extra user columns. What
+// Astroid fixes are the three things that must not drift: the mount, the cookie
+// prefix, and the table prefix. Get any of those wrong and the two instances
+// fight over one origin's cookies, which fails intermittently and looks like a
+// session bug rather than a configuration one.
+import { astroidPortal } from "./config.js";
+/**
+ * `src/portal-auth.ts` — the portal Better Auth instance and its session
+ * resolver.
+ *
+ * Returns null when the project has no portal.
+ */
+export function generateAstroidPortalAuth(config) {
+    const portal = astroidPortal(config);
+    if (!portal)
+        return null;
+    return [
+        "// The PORTAL auth instance — customers/members, separate from the editor.",
+        "//",
+        "// Scaffolded once; yours to edit (the reset email, extra user columns, what",
+        "// role a new account gets). Three things should NOT change: the basePath,",
+        "// the cookiePrefix, and the tablePrefix. The studio instance keeps Better",
+        "// Auth's defaults because the Louise editor client hardcodes them, so this",
+        "// one moves — and if the two ever share a cookie prefix, signing into one",
+        "// silently signs you out of the other.",
+        'import { astroidMailTheme, magicLinkEmail, passwordResetEmail, resolveMailer, sendTransactional } from "astroidjs";',
+        'import { env } from "cloudflare:workers";',
+        'import { getLouiseAuth } from "louise-toolkit/auth";',
+        'import astroidConfig from "../astroid.config.js";',
+        "",
+        "const MAIL_THEME = astroidMailTheme(astroidConfig);",
+        "",
+        "/** The request-scoped portal auth instance. */",
+        "function getPortalAuth(request: Request) {",
+        "  return getLouiseAuth(env, new URL(request.url).origin, {",
+        "    rpName: astroidConfig.theme.name,",
+        "    mailFrom: { email: env.MAIL_FROM, name: astroidConfig.theme.name },",
+        "    // The portal never sends magic links — it's email + password — but the",
+        "    // toolkit's config asks for a renderer, so give it the real one.",
+        "    renderMagicLinkEmail: ({ url, toEmail }) => magicLinkEmail(MAIL_THEME, { url, toEmail }),",
+        `    basePath: ${JSON.stringify(portal.basePath)},`,
+        `    cookiePrefix: ${JSON.stringify(portal.cookiePrefix)},`,
+        `    tablePrefix: ${JSON.stringify(portal.tablePrefix)},`,
+        "    customers: {",
+        "      minPasswordLength: 8,",
+        portal.signUp
+            ? "      // Public sign-up is ON for this project."
+            : "      // Accounts are provisioned by staff — no public sign-up.",
+        `      disableSignUp: ${!portal.signUp},`,
+        "      sendResetPassword: async ({ user, url }) => {",
+        "        // Through `resolveMailer`, NOT a hand-built options object: it is the",
+        "        // only thing that applies the DUMMY_REPLACE_ME sentinel check. Built by",
+        "        // hand, a fresh deploy with a real EMAIL binding but a placeholder",
+        "        // MAIL_FROM read as configured and called the Email API with an envelope",
+        "        // sender of literally \"DUMMY_REPLACE_ME\" — rejected upstream, swallowed",
+        "        // here, and reported to the user as a reset email that was sent.",
+        "        const mailer = await resolveMailer(env);",
+        "        await sendTransactional(mailer, [",
+        "          { to: user.email, content: passwordResetEmail(MAIL_THEME, { url, toEmail: user.email }) },",
+        "        ]);",
+        "      },",
+        "    },",
+        "    // The portal has its own users — never the editor allowlist.",
+        "    resolveAdmins: () => [],",
+        "  });",
+        "}",
+        "",
+        "/** Better Auth catch-all for the portal, mounted at its own basePath. */",
+        "export async function handlePortalAuth(request: Request): Promise<Response> {",
+        "  const auth = await getPortalAuth(request);",
+        "  return auth.handler(request);",
+        "}",
+        "",
+        "/**",
+        " * Resolve the signed-in portal user, or null. The generated middleware passes",
+        " * this to `resolvePortalSession`, which shares the lookup for the request.",
+        " */",
+        "export async function resolvePortalUser(request: Request) {",
+        "  try {",
+        "    const auth = await getPortalAuth(request);",
+        "    const session = await auth.api.getSession({ headers: request.headers });",
+        "    const user = session?.user;",
+        "    if (!user) return null;",
+        `    return { id: user.id, email: user.email ?? "", role: user.role ?? ${JSON.stringify(portal.defaultRole)} };`,
+        "  } catch {",
+        "    // No bindings (plain `astro preview`) → treat as signed out.",
+        "    return null;",
+        "  }",
+        "}",
+        "",
+    ].join("\n");
+}
+/**
+ * `src/pages/api/portal-auth/[...all].ts` — the portal's Better Auth catch-all,
+ * mounted at its own basePath so it never collides with the studio's
+ * `/api/auth`.
+ *
+ * Lives here rather than as a literal in `create-astroid` for the same reason
+ * the archetype sections moved (#277): the scaffolder is plain JS, so a drifted
+ * import path there is invisible until a user's build fails. It is also the half
+ * `generateAstroidPortalAuth` is useless without — `src/portal-auth.ts` exports
+ * `handlePortalAuth`, and nothing calls it unless this route exists.
+ *
+ * Returns null when the project has no portal.
+ */
+export function generateAstroidPortalAuthRoute(config) {
+    if (!astroidPortal(config))
+        return null;
+    return [
+        "// The portal Better Auth catch-all, mounted at its own basePath so it",
+        "// never collides with the studio's /api/auth.",
+        'import type { APIRoute } from "astro";',
+        'import { handlePortalAuth } from "../../../portal-auth.js";',
+        "",
+        "export const prerender = false;",
+        "",
+        "export const ALL: APIRoute = ({ request }) => handlePortalAuth(request);",
+        "",
+    ].join("\n");
+}
+/**
+ * The `App.Locals` member the portal adds, as a block `create-astroid`
+ * substitutes into `src/env.d.ts`. Empty without a portal — a project that
+ * types `portalUser` it never sets is inviting a null-check nobody needs.
+ */
+export function generateAstroidPortalLocals(config) {
+    if (!astroidPortal(config))
+        return "";
+    return [
+        "    /** The signed-in PORTAL user (customers/members) — distinct from",
+        "     *  `editor`, which is the studio session. Null when signed out. */",
+        '    portalUser: import("astroidjs").PortalUser | null;',
+    ].join("\n");
+}

package/dist/portal/session.d.ts

@@ -0,0 +1,36 @@
+import type { PortalUser } from "./guard.js";
+/** Resolves the portal user for a request, or null when signed out. */
+export type PortalSessionResolver = (request: Request) => Promise<PortalUser | null>;
+/**
+ * Resolve the portal session at most once per request.
+ *
+ * Shares the *promise*, not the result, so two callers racing during the same
+ * request both await one lookup rather than starting a second.
+ */
+export declare function resolvePortalSession(request: Request, resolve: PortalSessionResolver): Promise<PortalUser | null>;
+/** JSON response helper — the shape every portal API route returns. */
+export declare function json(body: unknown, status?: number, headers?: Record<string, string>): Response;
+/** True when the request came from this same origin. */
+export declare function isSameOrigin(request: Request): boolean;
+export type CustomerGuardResult = {
+    ok: true;
+    user: PortalUser;
+} | {
+    ok: false;
+    response: Response;
+};
+/**
+ * Guard a portal API handler: a signed-in user, and — on mutations — a
+ * same-origin request.
+ *
+ * ```ts
+ * const guard = await requireCustomer(request, (req) => portalUser(req));
+ * if (!guard.ok) return guard.response;
+ * // guard.user is signed in and this is a same-origin call
+ * ```
+ *
+ * `roles` narrows further, for a route only some portal users may reach.
+ */
+export declare function requireCustomer(request: Request, resolve: PortalSessionResolver, options?: {
+    roles?: string[];
+}): Promise<CustomerGuardResult>;

package/dist/portal/session.js

@@ -0,0 +1,86 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// Resolving the portal session once per request, and guarding mutations.
+//
+// The middleware resolves it (to gate routes) and so does whatever handler runs
+// next (to know who's asking). Both hitting the session store is a wasted D1
+// round-trip on every authenticated request, so the in-flight promise is shared
+// per request via a `WeakMap` — keyed on the `Request`, which means entries
+// disappear with the request rather than needing eviction.
+//
+// `requireCustomer` then adds the check a session alone doesn't give you:
+// same-origin on mutations. A cookie is attached by the browser to any request
+// to this origin, including one a third-party page triggered — so a session
+// proves identity, and the origin check proves intent.
+const inFlight = new WeakMap();
+/**
+ * Resolve the portal session at most once per request.
+ *
+ * Shares the *promise*, not the result, so two callers racing during the same
+ * request both await one lookup rather than starting a second.
+ */
+export function resolvePortalSession(request, resolve) {
+    const existing = inFlight.get(request);
+    if (existing)
+        return existing;
+    // A rejected lookup degrades to signed-out rather than propagating: missing
+    // bindings under plain `astro preview` shouldn't 500 a public page.
+    const promise = resolve(request).catch(() => null);
+    inFlight.set(request, promise);
+    return promise;
+}
+/** JSON response helper — the shape every portal API route returns. */
+export function json(body, status = 200, headers = {}) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json", ...headers },
+    });
+}
+/** Methods that change state, and therefore need the origin check. */
+const MUTATING = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+/** True when the request came from this same origin. */
+export function isSameOrigin(request) {
+    const target = new URL(request.url).origin;
+    const origin = request.headers.get("origin");
+    if (origin)
+        return origin === target;
+    // No Origin header: browsers always send one on cross-origin mutations, so
+    // its absence means a same-origin or non-browser caller. Fall back to Referer
+    // when present, and allow otherwise — being stricter would break legitimate
+    // server-to-server callers without stopping a real CSRF, which always carries
+    // an Origin.
+    const referer = request.headers.get("referer");
+    if (referer) {
+        try {
+            return new URL(referer).origin === target;
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Guard a portal API handler: a signed-in user, and — on mutations — a
+ * same-origin request.
+ *
+ * ```ts
+ * const guard = await requireCustomer(request, (req) => portalUser(req));
+ * if (!guard.ok) return guard.response;
+ * // guard.user is signed in and this is a same-origin call
+ * ```
+ *
+ * `roles` narrows further, for a route only some portal users may reach.
+ */
+export async function requireCustomer(request, resolve, options = {}) {
+    if (MUTATING.has(request.method) && !isSameOrigin(request)) {
+        return { ok: false, response: json({ ok: false, error: "Forbidden" }, 403) };
+    }
+    const user = await resolvePortalSession(request, resolve);
+    if (!user)
+        return { ok: false, response: json({ ok: false, error: "Unauthorized" }, 401) };
+    if (options.roles?.length && !options.roles.includes(user.role)) {
+        return { ok: false, response: json({ ok: false, error: "Forbidden" }, 403) };
+    }
+    return { ok: true, user };
+}

package/dist/portfolio/index.d.ts

@@ -0,0 +1 @@
+export { generateAstroidGalleryPage } from "./scaffold.js";

package/dist/portfolio/index.js

@@ -0,0 +1,4 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The `portfolio` archetype's scaffold surface.
+export { generateAstroidGalleryPage } from "./scaffold.js";

package/dist/portfolio/scaffold.d.ts

@@ -0,0 +1,9 @@
+import type { AstroidConfig } from "../config.js";
+/**
+ * `src/pages/work.astro` — the portfolio gallery. Null for any other archetype.
+ *
+ * Intrinsic `width`/`height` are carried through deliberately: they feed the
+ * pre-decode layout, so a library with dimensions recorded lays out correctly on
+ * first paint instead of reflowing once the images decode.
+ */
+export declare function generateAstroidGalleryPage(config: AstroidConfig): string | null;

package/dist/portfolio/scaffold.js

@@ -0,0 +1,93 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The `portfolio` archetype's scaffold-once page: a justified gallery over the
+// media library.
+//
+// Scaffold-once, not regenerated, for the usual reason — this is the first file
+// a portfolio site edits (which assets appear, in what order, whether tiles link
+// to a detail page), so `astroid generate` must never rewrite it.
+//
+// It exists because the primitives alone don't finish the job. `<MediaSlot>` and
+// `<JustifiedGallery>` are archetype-agnostic, but the wiring between them and
+// the media registry — the public URL shape, filtering to images, carrying
+// alt/caption and intrinsic dimensions through so the first paint isn't a guess
+// — is identical every time, and is exactly what the consuming sites hand-wrote.
+/**
+ * `src/pages/work.astro` — the portfolio gallery. Null for any other archetype.
+ *
+ * Intrinsic `width`/`height` are carried through deliberately: they feed the
+ * pre-decode layout, so a library with dimensions recorded lays out correctly on
+ * first paint instead of reflowing once the images decode.
+ */
+export function generateAstroidGalleryPage(config) {
+    if (config.archetype !== "portfolio")
+        return null;
+    const mediaBase = config.deploy?.mediaBase ?? "/media";
+    return [
+        "---",
+        "// The work gallery — a justified grid over the media library.",
+        "//",
+        "// Scaffolded once; yours to edit. The layout primitive is general",
+        "// (astroidjs/components/JustifiedGallery.astro); what lives here is this",
+        "// project's own answer to *which* assets appear and in what order.",
+        "//",
+        "// Rows carry `alt`/`caption` from the media registry, so an editor fixes alt",
+        "// text once in the library and every gallery showing that asset picks it up.",
+        "// Assets missing width/height still render — the client corrects the layout",
+        "// once the image decodes — but they cost a visible reflow, so it's worth",
+        "// backfilling dimensions on older uploads.",
+        'import JustifiedGallery from "astroidjs/components/JustifiedGallery.astro";',
+        'import type { GalleryItem } from "astroidjs/components/justify";',
+        'import { env } from "cloudflare:workers";',
+        'import Site from "../layouts/Site.astro";',
+        "",
+        "export const prerender = false;",
+        "",
+        "interface MediaRow {",
+        "  key: string;",
+        "  alt: string | null;",
+        "  caption: string | null;",
+        "  width: number | null;",
+        "  height: number | null;",
+        "}",
+        "",
+        "let rows: MediaRow[] = [];",
+        "try {",
+        "  const result = await env.DB.prepare(",
+        '    "SELECT key, alt, caption, width, height FROM media" +',
+        "      \" WHERE content_type LIKE 'image/%' ORDER BY uploaded_at DESC LIMIT 120\",",
+        "  ).all<MediaRow>();",
+        "  rows = result.results ?? [];",
+        "} catch {",
+        "  // No DB binding yet (pre-provision) — render the empty state.",
+        "}",
+        "",
+        "const items: GalleryItem[] = rows.map((row) => ({",
+        `  src: \`${mediaBase}/\${row.key}\`,`,
+        '  // An asset with no alt gets "" rather than its filename: an empty alt makes',
+        "  // a screen reader skip a decorative tile, while a filename is read aloud",
+        "  // character by character and tells the listener nothing.",
+        '  alt: row.alt ?? "",',
+        "  ...(row.caption ? { caption: row.caption } : {}),",
+        "  ...(row.width ? { width: row.width } : {}),",
+        "  ...(row.height ? { height: row.height } : {}),",
+        "}));",
+        "---",
+        "",
+        '<Site title="Work">',
+        '  <main class="mx-auto max-w-6xl px-6 py-16">',
+        '    <h1 class="text-4xl font-bold">Work</h1>',
+        "    {",
+        "      items.length > 0 ? (",
+        '        <JustifiedGallery items={items} class="mt-8" />',
+        "      ) : (",
+        '        <p class="mt-6 opacity-70">',
+        "          Upload images in the media library and they&apos;ll appear here.",
+        "        </p>",
+        "      )",
+        "    }",
+        "  </main>",
+        "</Site>",
+        "",
+    ].join("\n");
+}

package/dist/project/actions.d.ts

@@ -0,0 +1,3 @@
+import type { AstroidConfig } from "../config.js";
+/** `src/actions/index.ts` — the typed mutation surface, scaffolded once. */
+export declare function generateAstroidActions(_config: AstroidConfig): string;