@saacms/host-astro 0.1.0

package/README.md

@@ -0,0 +1,44 @@
+# @saacms/host-astro
+
+The Astro [host adapter](../../CONTEXT.md#architectural-primitives) for saacms. Knows how to:
+
+1. Generate `.astro` route files into `src/pages/<page-url>.astro` for Pages and Page templates (per ADR 0003).
+2. Emit the small mount file at `src/pages/api/saacms/[...slug].ts` that binds saacms's runtime handler into Astro's API surface (per ADR 0001).
+3. Generate per-Block preview routes the Puck canvas fetches at edit time (per ADR 0004 Mode 2).
+
+This is the **only host adapter shipped in v1 alpha** (per [ADR 0024](../../docs/adr/0024-v1-alpha-scope-astro-cloudflare.md)). Other hosts (`host-nextjs`, `host-sveltekit`, `host-nuxt`) follow in v1.x.
+
+## Reading order (relevant ADRs)
+
+- [ADR 0001 — Content compiler + serverless runtime](../../docs/adr/0001-content-compiler-delivery.md)
+- [ADR 0003 — saacms owns the host's route filesystem](../../docs/adr/0003-saacms-owns-routing.md)
+- [ADR 0004 — Block authoring: dual mode + preview-fetch](../../docs/adr/0004-block-authoring-dual-mode-with-preview-fetch.md)
+- [ADR 0007 — Render mode is per-Page-template](../../docs/adr/0007-render-mode-per-template.md)
+- [ADR 0009 — Media as Collection kind (repo vs bucket)](../../docs/adr/0009-media-as-collection-kind.md)
+- [ADR 0021 — Rendering and caching across the coupling spectrum](../../docs/adr/0021-rendering-and-caching-across-coupling-spectrum.md)
+- [ADR 0024 — v1 alpha scope: Astro + Cloudflare](../../docs/adr/0024-v1-alpha-scope-astro-cloudflare.md)
+
+## Status
+
+**Scaffold.** Interface shape and template files are defined; the route emitter is a stub. Real `.astro` source emission lands alongside the v1.0 alpha milestone.
+
+## Why Astro, why now
+
+Per ADR 0024 — Astro's "lightest framework that works" philosophy aligns with the saacms performance philosophy (ADR 0022 P1). Astro Server Islands give us PPR-equivalent partial rendering without framework-specific magic. Cloudflare Pages + D1 + R2 + Astro is the cleanest single stack to prove the architecture against before fanning out to Next.js / SvelteKit / Nuxt in v1.x.
+
+## Templates
+
+Three text templates live under `templates/`. They are intentionally **not** TypeScript — they are emitted verbatim by the saacms compile step into the user's project, where their imports refer to user-side files (`../../../../saacms.config.ts`, `../../../saacms/blocks/*.astro`).
+
+- `templates/api-mount.ts.txt` — the file `saacms init` writes to `src/pages/api/saacms/[...slug].ts`.
+- `templates/preview-route.astro.txt` — the per-Block preview route template (ADR 0004 Mode 2).
+- `templates/page-route.astro.txt` — the per-Page route template, emitted by the route emitter.
+
+## Known reconciliation TODO
+
+The local `HostAdapter` interface in `src/types.ts` diverges slightly from the canonical interface exported by `@saacms/core` (`src/host/index.ts`). This is a v1-scaffold artefact — subagents wrote both in parallel without final cross-check. To do before first real implementation pass:
+
+- Adopt `core`'s `GenerateRouteContext` / `GeneratedRoute` / `MountTemplate` shape verbatim
+- Drop `_core-shim.ts` (use `@saacms/core` brand types directly)
+- Rename `assetRoot()` → `assetRoot` (readonly property, per core)
+- Rename `previewRouteTemplate(slug)` → fold into `generatePreviewRoute(ctx)` per core's contract

package/dist/_core-shim.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Local shim of the brand types this package needs from `@saacms/core`.
+ *
+ * TODO: delete this file and import from `@saacms/core/types` once that path
+ * is wired through and the cross-package build graph is hooked up. Keeping a
+ * shim now lets the package typecheck in isolation at the v1 scaffold stage.
+ *
+ * The brand definitions MUST stay structurally compatible with the canonical
+ * ones in `packages/core/src/types/ids.ts` so a future direct import is a
+ * drop-in replacement.
+ */
+declare const __brand: unique symbol;
+export type PageID = string & {
+    readonly [__brand]: "PageID";
+};
+export type BlockSlug = string & {
+    readonly [__brand]: "BlockSlug";
+};
+export {};
+//# sourceMappingURL=_core-shim.d.ts.map

package/dist/_core-shim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_core-shim.d.ts","sourceRoot":"","sources":["../src/_core-shim.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,CAAC,MAAM,OAAO,EAAE,OAAO,MAAM,CAAA;AAEpC,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAA;CAAE,CAAA;AAC9D,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,OAAO,CAAC,EAAE,WAAW,CAAA;CAAE,CAAA"}

package/dist/_core-shim.js

@@ -0,0 +1,12 @@
+/**
+ * Local shim of the brand types this package needs from `@saacms/core`.
+ *
+ * TODO: delete this file and import from `@saacms/core/types` once that path
+ * is wired through and the cross-package build graph is hooked up. Keeping a
+ * shim now lets the package typecheck in isolation at the v1 scaffold stage.
+ *
+ * The brand definitions MUST stay structurally compatible with the canonical
+ * ones in `packages/core/src/types/ids.ts` so a future direct import is a
+ * drop-in replacement.
+ */
+export {};

package/dist/host-astro-adapter.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Astro implementation of the HostAdapter interface.
+ *
+ * Per ADR 0024, Astro is the only supported host in v1 alpha. This adapter:
+ *   - reports its `assetRoot()` for repo-mode media (per ADR 0009),
+ *   - hands `saacms init` the contents of the API mount file
+ *     (per ADR 0001),
+ *   - emits `.astro` route files into `src/pages/<page-url>.astro`
+ *     (per ADR 0003 + ADR 0007),
+ *   - emits per-Block preview routes the Puck canvas fetches
+ *     (per ADR 0004 Mode 2).
+ *
+ * `generateRoute` renders the Page's stored Block tree into real Astro markup
+ * (per ADR 0003 + ADR 0004 Mode 1 + ADR 0010); `generatePreviewRoute` remains
+ * a scaffold stub at this milestone.
+ */
+import type { HostAdapter, PuckLayout } from "./types.ts";
+/**
+ * Render a stored saacms draft tree to one well-formed Astro/HTML fragment.
+ *
+ * Pure: same input → same output, no I/O. `generateRoute` splices the result
+ * into the Astro body. Absent/empty layout → `<main></main>` (never the old
+ * placeholder, never a throw). Unknown Block types degrade to an HTML comment
+ * so a stale tree still emits its siblings (forward-compat, ADR 0004).
+ */
+export declare function renderBlockTree(layout: PuckLayout | undefined): string;
+export interface AstroHostAdapterOptions {
+    /**
+     * Override the default assets root used for repo-mode media (per ADR 0009).
+     * Defaults to "public/" — the conventional Astro static-asset directory.
+     */
+    readonly assetRoot?: string;
+}
+export declare function createAstroHostAdapter(opts?: AstroHostAdapterOptions): HostAdapter;
+//# sourceMappingURL=host-astro-adapter.d.ts.map

package/dist/host-astro-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-astro-adapter.d.ts","sourceRoot":"","sources":["../src/host-astro-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAQH,OAAO,KAAK,EAIV,WAAW,EAEX,UAAU,EAEX,MAAM,YAAY,CAAA;AAkJnB;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,MAAM,CAMtE;AAuCD,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED,wBAAgB,sBAAsB,CACpC,IAAI,GAAE,uBAA4B,GACjC,WAAW,CAuGb"}

package/dist/host-astro-adapter.js

@@ -0,0 +1,58 @@
+/**
+ * Astro implementation of the HostAdapter interface.
+ *
+ * Per ADR 0024, Astro is the only supported host in v1 alpha. This adapter:
+ *   - reports its `assetRoot()` for repo-mode media (per ADR 0009),
+ *   - hands `saacms init` the contents of the API mount file
+ *     (per ADR 0001),
+ *   - emits `.astro` route files into `src/pages/<page-url>.astro`
+ *     (per ADR 0003 + ADR 0007),
+ *   - emits per-Block preview routes the Puck canvas fetches
+ *     (per ADR 0004 Mode 2).
+ *
+ * The route + preview emitters are stubs at this scaffold milestone.
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// Templates live one level up from src/ in the published package layout.
+const TEMPLATES_DIR = resolve(__dirname, "..", "templates");
+const MOUNT_TEMPLATE = readFileSync(resolve(TEMPLATES_DIR, "api-mount.ts.txt"), "utf8");
+const PREVIEW_TEMPLATE = readFileSync(resolve(TEMPLATES_DIR, "preview-route.astro.txt"), "utf8");
+export function createAstroHostAdapter(opts = {}) {
+    const assetRootPath = opts.assetRoot ?? "public/";
+    return {
+        name: "astro",
+        assetRoot() {
+            return assetRootPath;
+        },
+        mountTemplate() {
+            return MOUNT_TEMPLATE;
+        },
+        previewRouteTemplate(blockSlug) {
+            // Substitute the ${blockSlug} placeholder in the template literally.
+            // The template is intentionally not a JS template literal — it lives in
+            // a .txt file so the user's Astro toolchain doesn't try to compile it
+            // when emitted into their project.
+            return PREVIEW_TEMPLATE.replaceAll("${blockSlug}", blockSlug);
+        },
+        generateRoute(page, _options) {
+            // v1 scaffold: return a stub file at the conventional Astro location.
+            // Real emission lands per ADR 0003 + ADR 0007 + ADR 0021.
+            return {
+                path: `src/pages/${page.url}.astro`,
+                source: "// generated by saacms host-astro\n" +
+                    "<!-- TODO: emit Page tree as .astro source -->\n",
+            };
+        },
+        generatePreviewRoute(block) {
+            // v1 scaffold: emit a placeholder preview route at the conventional
+            // location. Real emission substitutes the Block's slug + props schema.
+            return {
+                path: `src/pages/saacms/preview/${block.slug}.astro`,
+                source: PREVIEW_TEMPLATE.replaceAll("${blockSlug}", block.slug),
+            };
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @saacms/host-astro — public surface.
+ *
+ * The Astro host adapter (per ADR 0024 v1 alpha scope). Exports the factory
+ * `astroHostAdapter()` that returns a `HostAdapter` for use in
+ * `saacms.config.ts`:
+ *
+ * ```ts
+ * import { astroHostAdapter } from "@saacms/host-astro"
+ * import { defineConfig } from "@saacms/core"
+ *
+ * export default defineConfig({
+ *   host: astroHostAdapter(),
+ *   // ...
+ * })
+ * ```
+ */
+import { type AstroHostAdapterOptions } from "./host-astro-adapter.ts";
+import type { HostAdapter } from "./types.ts";
+export { createAstroHostAdapter } from "./host-astro-adapter.ts";
+export type { AstroHostAdapterOptions } from "./host-astro-adapter.ts";
+export type { Block, GeneratedFile, GenerateRouteOptions, HostAdapter, Page, } from "./types.ts";
+/**
+ * Convenience alias — the canonical name used by user code in
+ * `saacms.config.ts`. Equivalent to `createAstroHostAdapter(opts)`.
+ */
+export declare function astroHostAdapter(opts?: AstroHostAdapterOptions): HostAdapter;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,yBAAyB,CAAA;AAChC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE7C,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAA;AAChE,YAAY,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAA;AACtE,YAAY,EACV,KAAK,EACL,aAAa,EACb,oBAAoB,EACpB,WAAW,EACX,IAAI,GACL,MAAM,YAAY,CAAA;AAEnB;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,CAAC,EAAE,uBAAuB,GAAG,WAAW,CAE5E"}

package/dist/index.js

@@ -0,0 +1,193 @@
+// src/host-astro-adapter.ts
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { SCHEME_COOKIE, DARK_MODE_COOKIE } from "@saacms/core";
+var __dirname2 = dirname(fileURLToPath(import.meta.url));
+var TEMPLATES_DIR = resolve(__dirname2, "..", "templates");
+var MOUNT_TEMPLATE = readFileSync(resolve(TEMPLATES_DIR, "api-mount.ts.txt"), "utf8");
+var PREVIEW_TEMPLATE = readFileSync(resolve(TEMPLATES_DIR, "preview-route.astro.txt"), "utf8");
+function assertSafeUrl(url) {
+  if (url.includes("\\")) {
+    throw new Error(`generateRoute: url '${url}' contains a backslash; use forward slashes`);
+  }
+  if (url.startsWith("/")) {
+    throw new Error(`generateRoute: url '${url}' is absolute; pass a path without a leading slash`);
+  }
+  for (const segment of url.split("/")) {
+    if (segment === "..") {
+      throw new Error(`generateRoute: url '${url}' contains a '..' segment; refusing to escape src/pages`);
+    }
+  }
+}
+var HTML_ATTR_ESCAPE = {
+  "&": "&",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+  "'": "&#39;"
+};
+function escapeAttr(value) {
+  return value.replace(/[&<>"']/g, (c) => HTML_ATTR_ESCAPE[c] ?? c);
+}
+function isRecord(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+var CUSTOM_ELEMENT_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)+$/;
+var SAFE_ATTR_NAME = /^[a-zA-Z_][a-zA-Z0-9_.:-]*$/;
+function isBindValue(v) {
+  return isRecord(v) && v.kind === "bind" && typeof v.path === "string";
+}
+function renderNode(node) {
+  if (!isRecord(node))
+    return "";
+  const slug = typeof node.block === "string" ? node.block : "";
+  if (!CUSTOM_ELEMENT_NAME.test(slug)) {
+    const raw = String(node.block ?? "");
+    const safe = raw.replace(/-{2,}/g, "-").replace(/>/g, "").replace(/[\r\n]+/g, " ");
+    return `<!-- saacms: unknown block '${safe}' -->`;
+  }
+  const props = isRecord(node.props) ? node.props : {};
+  const attrParts = [];
+  const jsonProps = {};
+  for (const [key, value] of Object.entries(props)) {
+    if (value === null || value === undefined)
+      continue;
+    if (isBindValue(value)) {
+      attrParts.push(`data-saacms-bind="${escapeAttr(value.path)}"`);
+      continue;
+    }
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      if (!SAFE_ATTR_NAME.test(key))
+        continue;
+      attrParts.push(`${key}="${escapeAttr(String(value))}"`);
+      continue;
+    }
+    jsonProps[key] = value;
+  }
+  if (Object.keys(jsonProps).length > 0) {
+    attrParts.push(`props="${escapeAttr(JSON.stringify(jsonProps))}"`);
+  }
+  const children = Array.isArray(node.children) ? node.children.map(renderNode).join("") : "";
+  const attrs = attrParts.length > 0 ? " " + attrParts.join(" ") : "";
+  return `<${slug}${attrs}>${children}</${slug}>`;
+}
+function renderBlockTree(layout) {
+  const tree = layout?.tree;
+  const nodes = isRecord(tree) && Array.isArray(tree.nodes) ? tree.nodes : [];
+  if (nodes.length === 0)
+    return "<main></main>";
+  return `<main>${nodes.map(renderNode).join("")}</main>`;
+}
+function parseCookies(header) {
+  if (header.length === 0)
+    return {};
+  return Object.fromEntries(header.split(";").map((pair) => {
+    const eqIdx = pair.indexOf("=");
+    if (eqIdx === -1)
+      return [pair.trim(), ""];
+    return [pair.slice(0, eqIdx).trim(), pair.slice(eqIdx + 1).trim()];
+  }));
+}
+var themeImpl = {
+  resolveActiveScheme(req) {
+    const cookies = parseCookies(req.headers.get("cookie") ?? "");
+    return {
+      schemeId: cookies[SCHEME_COOKIE] ?? null,
+      darkMode: cookies[DARK_MODE_COOKIE] === "1"
+    };
+  },
+  emitThemeStyles(tokens) {
+    const props = Object.entries(tokens).map(([k, v]) => `  --${k}: ${v};`).join(`
+`);
+    return `<style>:root {
+${props}
+}</style>`;
+  },
+  emitThemeAttribute(schemeId, darkMode) {
+    const dark = darkMode ? ' class="dark"' : "";
+    return `data-theme="${schemeId}"${dark}`;
+  }
+};
+function createAstroHostAdapter(opts = {}) {
+  const assetRootPath = opts.assetRoot ?? "public/";
+  return {
+    name: "astro",
+    theme: themeImpl,
+    assetRoot() {
+      return assetRootPath;
+    },
+    mountTemplate() {
+      return MOUNT_TEMPLATE;
+    },
+    previewRouteTemplate(blockSlug) {
+      return PREVIEW_TEMPLATE.replaceAll("${blockSlug}", blockSlug);
+    },
+    generateRoute(page, options) {
+      assertSafeUrl(page.url);
+      const effectiveMode = options.forceRenderMode ?? page.renderMode;
+      if (effectiveMode !== "static" && effectiveMode !== "isr" && effectiveMode !== "dynamic") {
+        throw new Error(`generateRoute: unrecognised render mode '${String(effectiveMode)}'`);
+      }
+      const filePath = page.url === "" ? "src/pages/index.astro" : `src/pages/${page.url}.astro`;
+      const frontmatterLines = [
+        "// generated by saacms host-astro — do not edit",
+        `// saacms-page-id: ${page.id}`,
+        `// render-mode: ${effectiveMode}`
+      ];
+      if (effectiveMode === "static") {
+        frontmatterLines.push("export const prerender = true");
+      } else if (effectiveMode === "isr") {
+        frontmatterLines.push("export const prerender = true");
+        frontmatterLines.push("export const revalidate = 60");
+      } else {
+        frontmatterLines.push("export const prerender = false");
+      }
+      let source;
+      if (options.theme) {
+        const { tokens, schemeId, darkMode } = options.theme;
+        const themeAttr = themeImpl.emitThemeAttribute(schemeId, darkMode);
+        const styleBlock = themeImpl.emitThemeStyles(tokens);
+        const body = renderBlockTree(page.layout);
+        source = `---
+` + frontmatterLines.join(`
+`) + `
+---
+` + `
+` + `<html ${themeAttr}>
+` + `<head>
+` + styleBlock + `
+</head>
+` + `<body>
+` + body + `
+</body>
+` + `</html>
+`;
+      } else {
+        source = `---
+` + frontmatterLines.join(`
+`) + `
+---
+` + `
+` + renderBlockTree(page.layout) + `
+`;
+      }
+      return { path: filePath, source };
+    },
+    generatePreviewRoute(block) {
+      return {
+        path: `src/pages/saacms/preview/${block.slug}.astro`,
+        source: PREVIEW_TEMPLATE.replaceAll("${blockSlug}", block.slug)
+      };
+    }
+  };
+}
+
+// src/index.ts
+function astroHostAdapter(opts) {
+  return createAstroHostAdapter(opts ?? {});
+}
+export {
+  createAstroHostAdapter,
+  astroHostAdapter
+};

package/dist/types.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Local type definitions for the host-astro adapter.
+ *
+ * TODO: once `@saacms/core` exports a canonical `HostAdapter` interface
+ * (per ADR 0020 — Hosting bounded context, Host adapter aggregate root), import
+ * it from there and delete the local copy. The shape declared here is the
+ * minimum surface area host-astro needs to fulfill its responsibilities; the
+ * canonical core interface will be a strict superset.
+ */
+import type { BlockSlug, PageID } from "./_core-shim.ts";
+import type { ThemeRenderContract } from "@saacms/core";
+export type { ThemeRenderContract };
+/**
+ * One Block instance in a stored saacms draft tree.
+ *
+ * This shape is DERIVED FROM (verified against, not guessed) what
+ * `@saacms/admin`'s `PatternMapper.puckDataToDraft` actually emits and what
+ * `puckOnPublishHandler` persists as a Page's stored `layout`:
+ *
+ *   SaacmsDraft = { tree: { root: { props: {…} }, nodes: SaacmsNode[] } }
+ *   SaacmsNode  = { block: string, id: string, props: {…} }
+ *
+ * host-astro mirrors it structurally — it never imports `@measured/puck` nor
+ * `@saacms/admin`, so the host type boundary stays editor-agnostic (ADR 0004).
+ * `children` is an additive optional field for nested zones the renderer
+ * recurses through; PatternMapper's current output is flat, so it is absent
+ * today but the contract is forward-compatible.
+ */
+export interface PuckLayoutNode {
+    /** The Block slug, e.g. "saacms-hero" (PatternMapper's `SaacmsNode.block`). */
+    readonly block: string;
+    /** Stable node id (PatternMapper hoists this out of props). */
+    readonly id?: string;
+    /** Block instance props (the `id` already stripped by PatternMapper). */
+    readonly props?: Readonly<Record<string, unknown>>;
+    /** Nested child nodes for zoned Blocks; recursed in tree order. */
+    readonly children?: ReadonlyArray<PuckLayoutNode>;
+}
+/**
+ * Stored Puck Block tree JSON — the saacms draft tree. Opaque to the type
+ * system, validated structurally at render time (it originates as core
+ * `PageDef.layout?: unknown`). Mirrors the exact shape produced by
+ * `PatternMapper.puckDataToDraft`.
+ */
+export interface PuckLayout {
+    readonly tree: {
+        readonly root?: {
+            readonly props?: Readonly<Record<string, unknown>>;
+        };
+        readonly nodes: ReadonlyArray<PuckLayoutNode>;
+    };
+}
+/**
+ * The Page projection passed to a host adapter's route emitter.
+ *
+ * TODO: replace with the canonical Page aggregate from `@saacms/core/types`
+ * once it lands.
+ */
+export interface Page {
+    readonly id: PageID;
+    /** URL path WITHOUT a leading slash, e.g. "about" or "blog/[slug]". */
+    readonly url: string;
+    /** Render mode (per ADR 0007). v1 ships "static" and "isr". */
+    readonly renderMode: "static" | "isr" | "dynamic";
+    /** Stored Puck Block tree JSON (the saacms draft tree). Opaque; validated at render. Mirrors core PageDef.layout. */
+    readonly layout?: PuckLayout;
+}
+/**
+ * The Block projection passed to a host adapter's preview-route emitter.
+ *
+ * TODO: replace with the canonical Block aggregate from `@saacms/core/types`
+ * once it lands.
+ */
+export interface Block {
+    readonly slug: BlockSlug;
+    /** Per ADR 0004 — "web-component" or "framework-native". */
+    readonly authoringMode: "web-component" | "framework-native";
+}
+/** A file the host adapter would write into the user's repo. */
+export interface GeneratedFile {
+    /** Path relative to the host project root (e.g. "src/pages/about.astro"). */
+    readonly path: string;
+    /** Verbatim file contents to write. */
+    readonly source: string;
+}
+/**
+ * Per-emit options the route emitter uses to decide what to emit.
+ *
+ * Currently a placeholder; will grow as the static / isr / dynamic emit
+ * branches land (per ADR 0007 + ADR 0021).
+ */
+export interface GenerateRouteOptions {
+    /** Force a specific render mode override (used by the test suite). */
+    readonly forceRenderMode?: "static" | "isr" | "dynamic";
+    /** Optional theme options; when provided, the emitted file wraps content in a full HTML shell. */
+    readonly theme?: {
+        readonly tokens: Record<string, string>;
+        readonly schemeId: string;
+        readonly darkMode: boolean;
+    };
+}
+/**
+ * The host-adapter contract.
+ *
+ * TODO: import from `@saacms/core` once exported there.
+ */
+export interface HostAdapter {
+    /** Stable string identifier for this host (e.g. "astro", "nextjs"). */
+    readonly name: string;
+    /** Repo-relative directory where repo-mode media is committed (ADR 0009). */
+    assetRoot(): string;
+    /**
+     * The verbatim source of the API mount file `saacms init` writes into the
+     * user's project (per ADR 0001).
+     */
+    mountTemplate(): string;
+    /**
+     * The verbatim source of a per-Block preview route, with `${blockSlug}`
+     * substituted (per ADR 0004 Mode 2).
+     */
+    previewRouteTemplate(blockSlug: string): string;
+    /** Emit one route file for a Page (per ADR 0003). */
+    generateRoute(page: Page, options: GenerateRouteOptions): GeneratedFile;
+    /** Emit one preview route for a Block (per ADR 0004 Mode 2). */
+    generatePreviewRoute(block: Block): GeneratedFile;
+    /** Theme render contract (ADR 0033) — no-FOUC themed SSR. */
+    readonly theme: ThemeRenderContract;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AACxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AACvD,YAAY,EAAE,mBAAmB,EAAE,CAAA;AAEnC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,cAAc;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAA;IACpB,yEAAyE;IACzE,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IAClD,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC,cAAc,CAAC,CAAA;CAClD;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE;QACb,QAAQ,CAAC,IAAI,CAAC,EAAE;YAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;SAAE,CAAA;QACtE,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,cAAc,CAAC,CAAA;KAC9C,CAAA;CACF;AAED;;;;;GAKG;AACH,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,uEAAuE;IACvE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,+DAA+D;IAC/D,QAAQ,CAAC,UAAU,EAAE,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAA;IACjD,qHAAqH;IACrH,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAA;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,4DAA4D;IAC5D,QAAQ,CAAC,aAAa,EAAE,eAAe,GAAG,kBAAkB,CAAA;CAC7D;AAED,gEAAgE;AAChE,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,uCAAuC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,sEAAsE;IACtE,QAAQ,CAAC,eAAe,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAA;IACvD,kGAAkG;IAClG,QAAQ,CAAC,KAAK,CAAC,EAAE;QACf,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;QACzB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;KAC3B,CAAA;CACF;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB,6EAA6E;IAC7E,SAAS,IAAI,MAAM,CAAA;IAEnB;;;OAGG;IACH,aAAa,IAAI,MAAM,CAAA;IAEvB;;;OAGG;IACH,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAA;IAE/C,qDAAqD;IACrD,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAAA;IAEvE,gEAAgE;IAChE,oBAAoB,CAAC,KAAK,EAAE,KAAK,GAAG,aAAa,CAAA;IAEjD,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAA;CACpC"}

package/dist/types.js

@@ -0,0 +1,10 @@
+/**
+ * Local type definitions for the host-astro adapter.
+ *
+ * TODO: once `@saacms/core` exports a canonical `HostAdapter` interface
+ * (per ADR 0020 — Hosting bounded context, Host adapter aggregate root), import
+ * it from there and delete the local copy. The shape declared here is the
+ * minimum surface area host-astro needs to fulfill its responsibilities; the
+ * canonical core interface will be a strict superset.
+ */
+export {};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@saacms/host-astro",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./templates/*": "./templates/*"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc --build",
+    "typecheck": "tsc --build --noEmit",
+    "prepack": "cp package.json package.json.pack-bak && bun run ../../scripts/prepack-pkg.ts",
+    "postpack": "mv package.json.pack-bak package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@saacms/core": "workspace:*"
+  },
+  "peerDependencies": {
+    "astro": "^4.0.0 || ^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "astro": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.7.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}

package/templates/api-mount.ts.txt

@@ -0,0 +1,12 @@
+// generated by saacms — do not edit
+import { createSaacmsRuntime } from "@saacms/core/runtime"
+import config from "../../../../saacms.config.ts"
+
+const handler = createSaacmsRuntime(config)
+export const GET = handler.fetch
+export const POST = handler.fetch
+export const PUT = handler.fetch
+export const PATCH = handler.fetch
+export const DELETE = handler.fetch
+export const OPTIONS = handler.fetch
+export const prerender = false

package/templates/page-route.astro.txt

@@ -0,0 +1,13 @@
+---
+// generated by saacms — do not edit
+// per-Page route emitted by @saacms/host-astro's route emitter.
+//
+// v1 alpha scaffold: this template is a comment-only stub. The real emitter
+// (per ADR 0003 + ADR 0007) will substitute:
+//   - the Page's URL pattern + render mode (static | isr) into the file path
+//     and any export const prerender / revalidate config,
+//   - the Puck Block tree as a sequence of Block imports + element usages,
+//   - any binding-expression resolution for Page-template renders (per ADR 0010),
+//   - the cache-tag emission for the coupling mode (per ADR 0021).
+---
+<!-- TODO: emit Page tree as .astro source -->

package/templates/preview-route.astro.txt

@@ -0,0 +1,8 @@
+---
+// generated by saacms — preview route for ${blockSlug}
+const url = new URL(Astro.request.url)
+const propsJson = url.searchParams.get("props") ?? "{}"
+const props = JSON.parse(propsJson)
+import Block from "../../../saacms/blocks/${blockSlug}.astro"
+---
+<Block {...props} />