@pramen/cms-astro 0.0.51 → 0.0.53

package/README.md

@@ -3,6 +3,122 @@
 Consume a [`@pramen/cms`](../cms) backend from an **Astro** site. Self-contained (no
 `@pramen/server` dependency — it speaks the CMS's public HTTP content API).
 
+## The front door: `pramenCms()`
+
+One integration, and the collections come from the store:
+
+```ts
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+import pramenCms from "@pramen/cms-astro";
+
+export default defineConfig({
+  integrations: [pramenCms({ backend: { url: "https://cms.example.workers.dev" } })],
+});
+```
+
+```ts
+// src/content.config.ts — once, and never again
+export { collections } from "pramen:cms";
+```
+
+That is the whole wiring. `collections: "auto"` (the default) asks the CMS which content
+types exist and generates one collection per type, named after its slug — so adding a
+content type in the editor takes effect on the next build with no code change. Pass a map
+when you want your own names or a subset: `collections: { clanky: "article" }`.
+
+The `pramen:cms` virtual module also exports the **configured client** and a bound
+**`resolve()`**, so a component that needs a media URL imports it instead of
+re-instantiating the client with a duplicated base URL:
+
+```astro
+---
+import { client, resolve } from "pramen:cms";
+const page = await client.getPage("o-nas");
+---
+<img src={resolve(page.page.fields.hero.url)} alt="" />
+```
+
+Types for that module are injected automatically (`pramen-cms.d.ts`), so there is no
+hand-written `d.ts` to keep in step.
+
+**Why the one-line re-export?** Astro has no API for an integration to define content
+collections — `astro:config:setup` offers routes, scripts, middleware, renderers and Vite
+config, and nothing for the content layer. Collections must be exported from
+`src/content.config.ts`. So the integration generates them and you re-export once, instead
+of hand-writing a `defineCollection` per type that has to track rows in the store.
+
+**`"auto"` fails the build if it cannot reach the CMS**, rather than generating nothing.
+Zero collections would otherwise build green and deploy an empty site. Discovery reads
+`listPublicContentTypes`, which is un-gated — no build-time token needed, and nothing new is
+exposed (a content type's slug already reaches the public through `listPublishedPages`). If
+your deployment does need auth for reads, pass `backend: { token }`.
+
+`createCmsClient` / `cmsLoader` stay exported and are documented below — the integration is
+the front door, not a replacement. A site that wants to define its own collections by hand
+still can.
+
+## Serving the editor: `admin`
+
+Add `admin: true` and this site also serves the [visual editor](../cms-editor), at
+`/_pramen/admin`:
+
+```ts
+integrations: [pramenCms({ backend: { url: "https://cms.example.workers.dev" }, admin: true })],
+```
+
+That injects **one catch-all Astro route**, so the editor is part of this site rather than
+something deployed beside it. What that buys, in order of how much time each used to cost:
+
+- **No `dist/` to deploy and no asset paths to get right.** The editor's `editor.js` /
+  `editor.css` are imported by the injected route and go through this site's bundler, which
+  emits and fingerprints them. A copied-in `index.html` could only ever reference them
+  root-absolute, so it worked at the origin root and nowhere else.
+- **No SPA-fallback rewrite.** `/_pramen/admin/pages/:id` is a real server route: a deep
+  link or a refresh is served like any other page.
+- **No second hostname for the editor** — it is a route on this site, not a separate
+  deploy pointed at a separate domain.
+- **CORS only if the CMS is elsewhere.** Serving the editor here does not move the API: it
+  still calls `backend.url`, so a CMS on its own Worker is still cross-origin and still
+  needs `CORS_ORIGINS` to allow this site. Co-deploy the CMS into this site's Worker (the
+  D1 store needs no `export`, so it can live in an Astro Worker) and `backend.url` becomes
+  same-origin — then there is genuinely no CORS.
+- **Nothing to point it at.** The shell tells the editor which Worker and tenant to call, so
+  the first screen asks for an editor/reviewer JWT and nothing else.
+
+The mount path is a constant, not an option: the same value is the injected route pattern
+*and* the prefix handed to the editor's router, so the two cannot drift into a router
+mounted where the server does not serve. `_pramen` is a reserved namespace — every ordinary
+path stays yours.
+
+Pass an object instead of `true` to configure the editor itself (this replaces its old
+`/config.js`, and is typed):
+
+```ts
+pramenCms({
+  backend: { url: "https://cms.example.workers.dev", tenant: "acme" },
+  admin: {
+    brand: { name: "Acme", suffix: "cms" },   // the wordmark; `suffix: null` drops the second half
+    signInUrl: "/signin/",                     // must be a page that EXISTS
+    hidePages: true,                           // collections-only deployments
+    extraNav: [{ label: "Curation", href: "/curate" }],
+  },
+})
+```
+
+`@pramen/cms-editor` is an **optional** peer dependency: install it only if you use `admin`.
+Omit the option and no route is injected and nothing is added to the site.
+
+A working site is in [`example/site`](../../example/site) — content collections and the admin
+route, wired in one `pramenCms()` call. It doubles as this package's end-to-end test
+(`test/astro-site.test.ts`).
+
+> `signInUrl` must be a page that already exists. An unauthenticated load calls it *after*
+> clearing the stored session, so a path that lands back inside the editor is a loop with
+> nothing to recover from. `?setup=1` always forces the built-in screen.
+
+## The kit of parts
+
 - **`createCmsClient({ baseUrl })`** — `getPage(slug, locale?)`, `listPublishedPages()`, and
   `getPreview(token)` to redeem a signed preview link (no session needed — the signature is
   the authorization; the result carries `isPreview: true`).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pramen/cms-astro",
-  "version": "0.0.51",
-  "description": "Astro integration for @pramen/cms \u2014 a build-time content-collection loader + a BlockRenderer for rendering CMS blocks in .astro pages.",
+  "version": "0.0.53",
+  "description": "Astro integration for @pramen/cms — a build-time content-collection loader + a BlockRenderer for rendering CMS blocks in .astro pages.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -14,7 +14,10 @@
   "sideEffects": false,
   "exports": {
     ".": "./src/index.ts",
+    "./integration": "./src/integration.ts",
+    "./admin": "./src/admin.ts",
     "./BlockRenderer.astro": "./src/BlockRenderer.astro",
+    "./PramenAdmin.astro": "./src/PramenAdmin.astro",
     "./RichText.astro": "./src/RichText.astro",
     "./RichTextMarks.astro": "./src/RichTextMarks.astro"
   },
@@ -22,7 +25,16 @@
     "src"
   ],
   "peerDependencies": {
-    "astro": ">=4"
+    "astro": ">=4",
+    "@pramen/cms-editor": "^0.0.52"
+  },
+  "peerDependenciesMeta": {
+    "@pramen/cms-editor": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@pramen/cms-editor": "0.0.53"
   },
   "publishConfig": {
     "access": "public"

package/src/PramenAdmin.astro

@@ -0,0 +1,51 @@
+---
+/**
+ * The CMS editor's shell — injected at `/_pramen/admin/[...path]` by
+ * `pramenCms({ admin: … })`. See `admin.ts` for why this is a route and not an index.html.
+ *
+ * Everything the SPA needs to boot, and nothing it could get wrong:
+ *
+ *  - The two assets are imported with `?url`, so the SITE's bundler emits, fingerprints and
+ *    serves them. There is no root-absolute path to break under a prefix and nothing for a
+ *    host to copy into the right directory.
+ *  - The mount node carries the prefix this route was injected at. Same constant, so the
+ *    router can never be mounted somewhere the server does not serve.
+ *  - The runtime config is an inline script written from typed integration options, ahead
+ *    of the module script that reads it.
+ *
+ * A catch-all pattern, so `/_pramen/admin/pages/:id` is a real server route: a deep link or
+ * a refresh is served like any other page, with no SPA-fallback rewrite for the host to
+ * configure (and to get wrong for its own 404s).
+ */
+import editorSrc from "@pramen/cms-editor/editor.js?url";
+import editorCss from "@pramen/cms-editor/editor.css?url";
+import { adminBasePath, adminConfigScript, adminTitle } from "pramen:cms/admin";
+
+// The editor is a client-side app against a live API — there is nothing to prerender, and
+// prerendering would bake one deployment's config into a static file.
+export const prerender = false;
+
+// Never store this in a shared cache. Without an explicit directive, caches fall back to
+// heuristic freshness (Cloudflare's Workers Cache keeps a header-less 200 for hours), and
+// this document carries the deployment's runtime config inline.
+Astro.response.headers.set("cache-control", "private, no-store");
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="robots" content="noindex, nofollow" />
+    {/* The pre-hydration fallback only. The bundle re-applies the configured wordmark on
+        boot, so this deliberately does not try to reproduce that string here — one place
+        builds it, and it is the one that owns the brand rules. */}
+    <title>{adminTitle}</title>
+    <link rel="stylesheet" href={editorCss} />
+    <script is:inline set:html={adminConfigScript} />
+  </head>
+  <body>
+    <div id="app" data-base-path={adminBasePath}></div>
+    <script is:inline type="module" src={editorSrc}></script>
+  </body>
+</html>

package/src/RichText.astro

@@ -22,6 +22,18 @@ interface Props {
 
 const { value, nodes } = Astro.props;
 const list = nodes ?? value?.content ?? [];
+
+/** The element name for a heading node. Computed HERE, in the frontmatter, and not inline
+ * in the template below: Astro's compiler scans a template expression for markup, so a `<`
+ * comparison inside one is read as the start of a tag and fails the build outright
+ * ("Unable to assign attributes when using <> Fragment shorthand syntax"). Frontmatter is
+ * plain TypeScript, where `<=` means what it says.
+ *
+ * Integer-checked as well as ranged — `h2.5` is not an element name. */
+function headingTag(level: unknown): string {
+  const ok = typeof level === "number" && Number.isInteger(level) && level >= 1 && level <= 6;
+  return ok ? `h${level}` : "h2";
+}
 ---
 
 {
@@ -39,10 +51,7 @@ const list = nodes ?? value?.content ?? [];
           </p>
         );
       case "heading": {
-        // Integer too — `h2.5` is an invalid element name.
-        const level =
-          typeof attrs.level === "number" && Number.isInteger(attrs.level) && attrs.level >= 1 && attrs.level <= 6 ? attrs.level : 2;
-        const Tag = `h${level}`;
+        const Tag = headingTag(attrs.level);
         return (
           <Tag>
             <Self nodes={children} />

package/src/admin.ts

@@ -0,0 +1,83 @@
+// The admin mount — where @pramen/cms-editor lives on the host site, and what the shell
+// tells it when it boots.
+//
+// The editor is a routed SPA. Serving it used to mean deploying its `dist/` somewhere and
+// asking the host for three things it had no way to verify: a catch-all rewrite to
+// index.html, hashed assets at the ORIGIN ROOT (so any prefix mount broke), and a
+// hand-edited `config.js` that failed silently when it 404'd. None of that survives here:
+// the integration injects ONE Astro route, so the host's own routing table serves every
+// deep link, its bundler emits and fingerprints the two assets, and the config is rendered
+// into the page from typed options.
+//
+// `ADMIN_BASE` is a constant, not an option. It is the pattern passed to `injectRoute` AND
+// the prefix stamped onto the mount node, so the route and the router cannot disagree —
+// which is the entire failure mode a configurable prefix invites. The `_`-prefixed segment
+// is a reserved namespace: the host keeps every ordinary path for its own pages.
+
+/** Where the editor is mounted on the host site. */
+export const ADMIN_BASE = "/_pramen/admin";
+
+/** The route pattern injected for it — one catch-all, so every in-app URL is a real server
+ * route and a refresh or a deep link is served like any other page. */
+export const ADMIN_ROUTE = `${ADMIN_BASE}/[...path]`;
+
+/** What the editor is handed at boot. Rendered into the shell as one inline script, so it
+ * is set before the bundle runs — the contract the old `/config.js` had, minus the file. */
+export interface AdminRuntimeConfig {
+  /** Which CMS Worker to call, and as which tenant. The editor asks for a token and
+   * nothing else once this is present. */
+  backend: { url: string; tenant: string };
+  /** The wordmark in the topbar, on the sign-in screen and in the browser tab. Set it when
+   * you deploy for a client — the default is the framework's name, not theirs. */
+  brand?: { name?: string; suffix?: string | null };
+  /** Send unauthenticated/expired sessions to your own sign-in page. Must be a page that
+   * EXISTS: the editor clears the session before redirecting, so a path that lands back
+   * inside the editor is a loop with nothing to recover from. */
+  signInUrl?: string;
+  /** Hide the Pages tab, for deployments that use collections only. */
+  hidePages?: boolean;
+  /** Extra top-nav links to companion tools the host serves. */
+  extraNav?: { label: string; href: string }[];
+}
+
+/** Options for the injected admin route. `true` is "mount it with the integration's own
+ * backend and no other configuration". */
+export type AdminOptions = boolean | Omit<AdminRuntimeConfig, "backend">;
+
+/** Characters that must not survive into an inline `<script>` verbatim. */
+const UNSAFE_IN_SCRIPT = /[<\u2028\u2029]/g;
+
+/** `<` as a JS unicode escape (so `</script>` cannot close the tag), and U+2028/U+2029 —
+ * legal in JSON strings, and historically line terminators in JS source — as their own. */
+function escapeForScript(char: string): string {
+  return `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`;
+}
+
+/**
+ * Serialize the runtime config for an inline `<script>`.
+ *
+ * `</script>` inside any string value would close the tag early and drop the rest of the
+ * page into the browser's HTML parser — and every one of these fields (a brand name, a nav
+ * label) is content someone types. Escaping at the JSON level is the fix that does not
+ * depend on where in the object the value happens to sit.
+ */
+export function serializeAdminConfig(cfg: AdminRuntimeConfig): string {
+  return `window.PRAMEN_CMS_EDITOR=${JSON.stringify(cfg).replace(UNSAFE_IN_SCRIPT, escapeForScript)};`;
+}
+
+/** The shell's `<title>`, which is only the pre-hydration fallback — the bundle re-applies
+ * the wordmark itself on boot. Mirrors `brand.ts`'s rule so the tab does not visibly change
+ * text a moment after load: a configured name replaces the whole string (nothing English is
+ * appended to a client's name), and `suffix: null` drops the second half. */
+export function adminDocumentTitle(cfg: AdminRuntimeConfig): string {
+  const name = cfg.brand?.name?.trim();
+  if (!name) return "pramen · cms editor";
+  const suffix = cfg.brand?.suffix === undefined ? "cms" : cfg.brand.suffix;
+  return suffix ? `${name} · ${suffix}` : name;
+}
+
+/** Build the runtime config from the integration's options and its backend descriptor. */
+export function adminRuntimeConfig(admin: AdminOptions, backend: { url: string; tenant?: string }): AdminRuntimeConfig {
+  const extra = admin === true ? {} : admin || {};
+  return { ...extra, backend: { url: backend.url.replace(/\/+$/, ""), tenant: backend.tenant ?? "main" } };
+}

package/src/index.ts

@@ -11,6 +11,16 @@
 
 import type { Loader, LoaderContext } from "astro/loaders";
 
+// The integration — the front door (`pramenCms()`), re-exported so
+// `import pramenCms from "@pramen/cms-astro"` works. The kit of parts below stays exported:
+// a site that defines its own collections by hand still can.
+export { pramenCms, default } from "./integration.js";
+export type { CmsBackend, CollectionMap, PramenCmsOptions } from "./integration.js";
+
+// The admin mount — the editor served as an injected route on this site (`admin: true`).
+export { ADMIN_BASE, ADMIN_ROUTE } from "./admin.js";
+export type { AdminOptions, AdminRuntimeConfig } from "./admin.js";
+
 /** Any JSON value — the wire form of everything the CMS stores. */
 export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
 

package/src/integration.ts

@@ -0,0 +1,257 @@
+// The Astro integration — one front door for a @pramen/cms backend (issue #35).
+//
+// Before this, a site hand-wired the kit of parts: instantiate `createCmsClient` in
+// `content.config.ts`, write one `defineCollection({ loader: cmsLoader({ client, type }) })`
+// per content type, then re-instantiate or re-import the client anywhere else that needs
+// `resolve()` for a media URL. Two things drifted: the base URL was repeated at every call
+// site, and the hand-written collection list had to be kept in step with content types that
+// are runtime ROWS — so adding a type in the editor silently did nothing until someone
+// remembered to edit the config.
+//
+// `pramenCms()` owns both. It builds the client once from a typed `backend` descriptor and
+// exposes it (plus the collections) through the `pramen:cms` virtual module.
+//
+// ON REGISTERING COLLECTIONS. Astro has no API for an integration to define content
+// collections — `astro:config:setup` offers routes, scripts, middleware, renderers and Vite
+// config, and nothing for the content layer (checked against Astro 7). Collections must be
+// exported from `src/content.config.ts`. So the integration generates them and the site
+// re-exports in one line:
+//
+//   // src/content.config.ts
+//   export { collections } from "pramen:cms";
+//
+// That is the honest version of "the integration registers them": one line that never
+// changes, instead of one `defineCollection` per type that has to track the store.
+
+import type { AstroIntegration } from "astro";
+import { fileURLToPath } from "node:url";
+import { ADMIN_BASE, ADMIN_ROUTE, adminDocumentTitle, adminRuntimeConfig, serializeAdminConfig, type AdminOptions } from "./admin.js";
+
+/** Where the CMS lives. A named descriptor rather than a bare `baseUrl` string, so a future
+ * local/in-process backend can be added without changing the call shape. */
+export interface CmsBackend {
+  /** The Worker's origin, e.g. `https://cms.example.workers.dev`. */
+  url: string;
+  /** Tenant to read. Default `"main"`. */
+  tenant?: string;
+  /** Bearer token, for reading a private deployment at build time. The public content API
+   * needs none — pass one only if your ACL does not grant anonymous reads. */
+  token?: string;
+}
+
+/** One generated collection: the Astro collection name, and the CMS content type it loads. */
+export type CollectionMap = Record<string, string>;
+
+export interface PramenCmsOptions {
+  backend: CmsBackend;
+  /**
+   * Which collections to generate.
+   *
+   * - `"auto"` (default) — one collection per content type in the store, named after the
+   *   type's slug. Discovered at config time, so adding a type in the editor takes effect
+   *   on the next build with no code change.
+   * - an explicit map — `{ articles: "article", pages: "page" }` — when you want your own
+   *   names, or a subset.
+   *
+   * `"auto"` costs one request during `astro:config:setup`. If it fails (the CMS is down,
+   * or unreachable from CI) the build FAILS rather than silently producing zero
+   * collections, which would otherwise surface as `getCollection("articles")` returning
+   * nothing and a site that builds green and empty.
+   */
+  collections?: "auto" | CollectionMap;
+  /** Restrict every generated collection to one locale. Omit to load all of them. */
+  locale?: string;
+  /**
+   * Serve the visual editor from this site, at `/_pramen/admin`.
+   *
+   * `true` mounts it against the same `backend` the collections load from; an object also
+   * carries the editor's own configuration (`brand`, `signInUrl`, `hidePages`, `extraNav`).
+   * Omit it and no admin route is injected at all — nothing is added to the site, and
+   * `@pramen/cms-editor` need not be installed.
+   *
+   * The route is a real Astro route, so deep links and refreshes are served by this site's
+   * router and the editor's two assets go through its bundler. There is nothing to deploy
+   * separately, no SPA-fallback rewrite to configure, and no second hostname for the editor.
+   *
+   * It does NOT move the API: the editor still calls `backend.url`, so a CMS on its own
+   * Worker stays cross-origin and still needs `CORS_ORIGINS`.
+   */
+  admin?: AdminOptions;
+}
+
+/** The virtual module the site imports from. */
+const VIRTUAL_ID = "pramen:cms";
+const RESOLVED_ID = "\0pramen:cms";
+
+/** A second one for the admin shell. Separate from `pramen:cms` so the injected route does
+ * not drag `astro:content` and the generated collections into a runtime page. */
+const ADMIN_VIRTUAL_ID = "pramen:cms/admin";
+const ADMIN_RESOLVED_ID = "\0pramen:cms/admin";
+
+/** Ask the CMS which content types exist. Public and un-gated (`listPublicContentTypes`),
+ * because this runs at BUILD time where there is no editor session — and a content type's
+ * slug is already public: `listPublishedPages` returns it for every published page. */
+async function discoverTypes(backend: CmsBackend): Promise<string[]> {
+  const base = backend.url.replace(/\/+$/, "");
+  const headers: Record<string, string> = { "content-type": "application/json", "x-pramen-tenant": backend.tenant ?? "main" };
+  if (backend.token) headers.authorization = `Bearer ${backend.token}`;
+  const res = await fetch(`${base}/rpc/listPublicContentTypes`, { method: "POST", headers, body: "{}" });
+  const body = (await res.json().catch(() => ({}))) as { ok?: boolean; result?: { slug: string }[]; error?: string };
+  if (body.ok !== true || !Array.isArray(body.result)) {
+    throw new Error(
+      `@pramen/cms-astro: collections: "auto" could not read content types from ${base} (HTTP ${res.status}${body.error ? `: ${body.error}` : ""}). ` +
+        `Pass an explicit map instead — collections: { articles: "article" } — or make the CMS reachable from this build.`,
+    );
+  }
+  return body.result.map((t) => t.slug).filter((s) => typeof s === "string" && s !== "");
+}
+
+/** A valid JS identifier-ish collection name. A content-type slug is author-controlled, and
+ * it lands in generated source as an object key — quote it, and refuse the ones that cannot
+ * be a collection name at all rather than emitting code that fails to parse. */
+function collectionKey(slug: string): string {
+  if (!/^[A-Za-z_][A-Za-z0-9_-]*$/.test(slug)) {
+    throw new Error(`@pramen/cms-astro: content-type slug ${JSON.stringify(slug)} cannot be a collection name — map it explicitly, e.g. collections: { myName: ${JSON.stringify(slug)} }`);
+  }
+  return slug;
+}
+
+/** Generate the virtual module's source. Everything the site needs from one import:
+ * the configured client, `resolve()` for media URLs, and the collections. */
+function moduleSource(backend: CmsBackend, map: CollectionMap, locale?: string): string {
+  const clientOpts = JSON.stringify({ baseUrl: backend.url, tenant: backend.tenant, token: backend.token });
+  const entries = Object.entries(map)
+    .map(([name, type]) => `  ${collectionKey(name)}: defineCollection({ loader: cmsLoader({ client, type: ${JSON.stringify(type)}${locale ? `, locale: ${JSON.stringify(locale)}` : ""} }) }),`)
+    .join("\n");
+  return `// GENERATED by @pramen/cms-astro (pramenCms integration) — do not edit.
+import { defineCollection } from "astro:content";
+import { createCmsClient, cmsLoader } from "@pramen/cms-astro";
+
+export const client = createCmsClient(${clientOpts});
+
+/** Absolute URL for a media path the CMS returned. Same base as the client, so a component
+ * never has to be handed the client (or a duplicated base URL) just to show an image. */
+export const resolve = (path) => client.resolve(path);
+
+export const collections = {
+${entries}
+};
+`;
+}
+
+/** Generate the admin shell's module: the mount prefix, the runtime config already
+ * serialized for an inline script, and the fallback tab title. Values, not logic — the
+ * shell is a template. */
+function adminModuleSource(admin: AdminOptions, backend: CmsBackend): string {
+  const cfg = adminRuntimeConfig(admin, backend);
+  return `// GENERATED by @pramen/cms-astro (pramenCms integration) — do not edit.
+export const adminBasePath = ${JSON.stringify(ADMIN_BASE)};
+export const adminConfigScript = ${JSON.stringify(serializeAdminConfig(cfg))};
+export const adminTitle = ${JSON.stringify(adminDocumentTitle(cfg))};
+`;
+}
+
+/** The `pramen:cms` module's types, injected so the site gets them with no manual d.ts. */
+const TYPES = `declare module "pramen:cms" {
+  import type { CmsClient } from "@pramen/cms-astro";
+  /** The configured CMS client — same instance the collections load through. */
+  export const client: CmsClient;
+  /** Absolute URL for a media path the CMS returned. */
+  export function resolve(path: string): string;
+  /** Generated content collections. Re-export from src/content.config.ts:
+   *  \`export { collections } from "pramen:cms";\` */
+  export const collections: Record<string, unknown>;
+}
+`;
+
+/** The admin shell's module types. Injected only when the admin route is. */
+const ADMIN_TYPES = `declare module "pramen:cms/admin" {
+  /** The prefix the admin route was injected at — stamped onto the editor's mount node. */
+  export const adminBasePath: string;
+  /** The editor's runtime config, serialized for an inline <script>. */
+  export const adminConfigScript: string;
+  /** Pre-hydration fallback for the shell's <title>. */
+  export const adminTitle: string;
+}
+`;
+
+/**
+ * The Astro integration for a @pramen/cms backend.
+ *
+ *   import pramenCms from "@pramen/cms-astro";
+ *
+ *   export default defineConfig({
+ *     integrations: [pramenCms({ backend: { url: "https://cms.example.workers.dev" } })],
+ *   });
+ *
+ * Then, once, in `src/content.config.ts`:
+ *
+ *   export { collections } from "pramen:cms";
+ *
+ * `createCmsClient` / `cmsLoader` stay exported — this is the front door, not a
+ * replacement. A site that wants to define its own collections by hand still can.
+ */
+export function pramenCms(opts: PramenCmsOptions): AstroIntegration {
+  if (!opts?.backend?.url) throw new Error("@pramen/cms-astro: pramenCms() needs a backend url — pramenCms({ backend: { url: \"https://cms.example.workers.dev\" } })");
+  return {
+    name: "@pramen/cms-astro",
+    hooks: {
+      "astro:config:setup": async ({ updateConfig, injectRoute, logger }) => {
+        const wanted = opts.collections ?? "auto";
+        const map: CollectionMap = wanted === "auto" ? Object.fromEntries((await discoverTypes(opts.backend)).map((s) => [collectionKey(s), s])) : wanted;
+        const names = Object.keys(map);
+        if (names.length === 0) {
+          // Not an error: a store with no content types yet is a legitimate early state.
+          // It IS worth saying out loud, because the symptom otherwise is `getCollection`
+          // throwing about a collection the site is sure it configured.
+          logger.warn(`no content types found at ${opts.backend.url} — no collections generated`);
+        } else {
+          logger.info(`${names.length} collection(s) from ${opts.backend.url}: ${names.join(", ")}`);
+        }
+        const code = moduleSource(opts.backend, map, opts.locale);
+        // Only when asked. A site that just reads content never installs @pramen/cms-editor,
+        // and an injected route would be a build error rather than an unused page.
+        const adminCode = opts.admin ? adminModuleSource(opts.admin, opts.backend) : undefined;
+        updateConfig({
+          vite: {
+            // The editor's bundle is a finished artifact, not source for this build to walk:
+            // it is emitted verbatim and referenced by url. `?url` alone asks for that, and
+            // this says so for the file itself, since a `.js` extension is otherwise the one
+            // thing a bundler assumes it should follow.
+            assetsInclude: ["**/@pramen/cms-editor/dist/editor.js"],
+            plugins: [
+              {
+                name: "pramen:cms",
+                // `enforce: "pre"` so this resolves before Astro's own alias handling sees
+                // an unknown bare specifier and reports it as a missing package.
+                enforce: "pre" as const,
+                resolveId(id: string) {
+                  if (id === VIRTUAL_ID) return RESOLVED_ID;
+                  if (id === ADMIN_VIRTUAL_ID && adminCode) return ADMIN_RESOLVED_ID;
+                  return null;
+                },
+                load(id: string) {
+                  if (id === RESOLVED_ID) return code;
+                  if (id === ADMIN_RESOLVED_ID) return adminCode;
+                  return null;
+                },
+              },
+            ],
+          },
+        });
+        if (adminCode) {
+          // One catch-all: every in-app URL is a real server route, so a deep link and a
+          // refresh are served like any other page. The pattern and the prefix the shell
+          // stamps on the mount node are the same constant — see admin.ts.
+          injectRoute({ pattern: ADMIN_ROUTE, entrypoint: fileURLToPath(new URL("./PramenAdmin.astro", import.meta.url)) });
+          logger.info(`editor mounted at ${ADMIN_BASE}`);
+        }
+      },
+      "astro:config:done": ({ injectTypes }) => {
+        injectTypes({ filename: "pramen-cms.d.ts", content: opts.admin ? `${TYPES}\n${ADMIN_TYPES}` : TYPES });
+      },
+    },
+  };
+}
+
+export default pramenCms;