@pramen/cms-astro 0.0.52 → 0.0.53

package/README.md

@@ -58,6 +58,65 @@ your deployment does need auth for reads, pass `backend: { token }`.
 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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pramen/cms-astro",
-  "version": "0.0.52",
-  "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",
@@ -15,7 +15,9 @@
   "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"
   },
@@ -23,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

@@ -17,6 +17,10 @@ import type { Loader, LoaderContext } from "astro/loaders";
 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

@@ -24,7 +24,8 @@
 // changes, instead of one `defineCollection` per type that has to track the store.
 
 import type { AstroIntegration } from "astro";
-import { createCmsClient, type CmsClient } from "./index.js";
+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. */
@@ -60,12 +61,33 @@ export interface PramenCmsOptions {
   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. */
@@ -117,6 +139,18 @@ ${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";
@@ -130,6 +164,17 @@ const TYPES = `declare module "pramen:cms" {
 }
 `;
 
+/** 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.
  *
@@ -151,7 +196,7 @@ export function pramenCms(opts: PramenCmsOptions): AstroIntegration {
   return {
     name: "@pramen/cms-astro",
     hooks: {
-      "astro:config:setup": async ({ updateConfig, logger }) => {
+      "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);
@@ -164,8 +209,16 @@ export function pramenCms(opts: PramenCmsOptions): AstroIntegration {
           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",
@@ -173,18 +226,29 @@ export function pramenCms(opts: PramenCmsOptions): AstroIntegration {
                 // an unknown bare specifier and reports it as a missing package.
                 enforce: "pre" as const,
                 resolveId(id: string) {
-                  return id === VIRTUAL_ID ? RESOLVED_ID : null;
+                  if (id === VIRTUAL_ID) return RESOLVED_ID;
+                  if (id === ADMIN_VIRTUAL_ID && adminCode) return ADMIN_RESOLVED_ID;
+                  return null;
                 },
                 load(id: string) {
-                  return id === RESOLVED_ID ? code : null;
+                  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: TYPES });
+        injectTypes({ filename: "pramen-cms.d.ts", content: opts.admin ? `${TYPES}\n${ADMIN_TYPES}` : TYPES });
       },
     },
   };