@pramen/cms-editor 0.0.52 → 0.0.54

package/README.md

@@ -1,7 +1,7 @@
 # @pramen/cms-editor
 
-A **visual block/page editor** for [`@pramen/cms`](../cms) — a standalone React SPA that
-talks to the CMS handlers over HTTP. It mutates through the *semantic* handlers
+A **visual block/page editor** for [`@pramen/cms`](../cms) — a React SPA that talks to the
+CMS handlers over HTTP, served by your own site (see [Deploy it](#deploy-it)). It mutates through the *semantic* handlers
 (`addBlock`/`updateBlock`/`reorderRegion`/`publishPage`/…), so field validation, region
 allow-lists, and the review/publish gates are all enforced server-side.
 
@@ -26,43 +26,89 @@ allow-lists, and the review/publish gates are all enforced server-side.
 ## Run it
 
 ```bash
-bun run --cwd packages/cms-editor build    # → dist/ (index.html + hashed JS)
+bun run --cwd packages/cms-editor build    # -> dist/editor.js + dist/editor.css
 bun run --cwd packages/cms-editor dev      # watch + preview on http://localhost:5175
 ```
 
-It's a **standalone static SPA** (no server-package dependency — local types + `fetch`).
-Deploy `dist/` anywhere; it talks cross-origin to your Worker, so set `CORS_ORIGINS` to allow
-the editor's origin. On first load, paste your Worker base URL, tenant, and an
-**editor/reviewer JWT**. (Co-hosting on the Worker via an `assets` binding is a possible
-follow-up.)
+The build produces exactly **two files** and no `index.html`. That is deliberate: a baked
+shell can only hard-code root-absolute asset paths, which works at the origin root and
+nowhere else, and its companion `config.js` was a hand-edited untyped global that failed
+silently the moment it 404'd.
 
-**SPA fallback (required).** Because views are real URLs, the host must serve `index.html`
-for any unmatched, extensionless path (deep link or refresh) and serve hashed assets from
-the root. The dev preview server already does this; on a static host configure a catch-all
-rewrite to `/index.html` (Cloudflare Pages/`assets` handle this by default). The bundle is
-referenced by an **absolute** path (`/main.<hash>.js`), so it loads correctly from any route
-depth — don't rewrite it to a relative path.
+## Deploy it
 
-## Configure it (`/config.js`)
+A **host serves it**, from a shell it renders. For an Astro site that is one line — see
+[`@pramen/cms-astro`](../cms-astro):
 
-`dist/config.js` is loaded before the app boots and sets `window.PRAMEN_CMS_EDITOR`. Override
-that one file on your host — no rebuild, no fork. Every field is optional, and the shipped
-file has them all commented out; **add them one at a time**:
+```js
+// astro.config.mjs
+pramenCms({ backend: { url: "https://cms.example.workers.dev" }, admin: true })
+```
+
+That injects a catch-all route at `/_pramen/admin`, so every view is a real server route on
+the site's own origin: no `dist/` to copy, no SPA-fallback rewrite, and no second hostname
+for the editor. The site's bundler emits and fingerprints `editor.js` / `editor.css` like
+any other asset, which is what makes serving it under a prefix work.
+
+It does not move the API, though. The editor still calls the CMS at the `backend.url` the
+shell declares, so a CMS on its own Worker is still cross-origin and still needs
+`CORS_ORIGINS` to allow the site. CORS goes away only when the CMS shares the site's
+origin.
+
+Everything the bundle needs at boot comes from that shell, and nothing else:
+
+| What | How the shell provides it | Read by |
+| --- | --- | --- |
+| Where it is mounted | `data-base-path` on the mount node | `src/mount.ts` |
+| Which Worker + tenant to call | `window.PRAMEN_CMS_EDITOR.backend` | `src/mount.ts` |
+| Wordmark, sign-in URL, nav | the rest of `window.PRAMEN_CMS_EDITOR` | `src/brand.ts`, `src/app-context.tsx` |
+
+The mount prefix is the constant the route was injected at, stamped onto the node by the
+same code that injected it — so the router cannot be mounted somewhere the server does not
+serve. Navigation is scoped to it, so a co-hosted editor intercepts only its own URLs
+(`_404.tsx`'s catch-all matches every same-origin path, which un-scoped would mean a click
+on the host's own `/blog` rendering the editor's "Nothing lives here").
+
+**To write your own shell** (a Worker route, another framework), render: the stylesheet, a
+`<div id="app" data-base-path="…">`, an inline script setting `window.PRAMEN_CMS_EDITOR`,
+and `<script type="module" src="…editor.js">` — in that order. The dev preview in
+`scripts/build.ts` is the smallest complete example.
+
+## Configure it
+
+The editor's own options travel in `window.PRAMEN_CMS_EDITOR`, which the integration writes
+from typed options (`admin: { … }`) — there is no file to edit:
 
 ```js
-window.PRAMEN_CMS_EDITOR = {
+admin: {
   brand: { name: "Acme", suffix: "cms" },            // the wordmark — see below
   // signInUrl: "/signin/",                          // ONLY once that page exists — see the warning
   // hidePages: true,                                // collections-only deployments
-  // extraNav: [{ label: "Curation", href: "/curate" }],
-};
+  // extraNav: [{ label: "Curation", href: "/curate", target: "_self" }],
+}
 ```
 
-> **`signInUrl` must be a page that exists, and same-origin needs care.** An unauthenticated
-> load calls it after clearing the stored session, so if the path 404s into this SPA's own
-> catch-all (which a same-origin extensionless path does — see the SPA-fallback note above),
-> the editor bounces between the redirect and itself with no session to recover from. Point
-> it at a page you have already deployed, and prefer a separate origin.
+`extraNav` links open in a **new tab** by default, because the editor's catch-all route
+matches every same-origin path — a same-tab click would land on the editor's own 404 instead
+of your tool. Add `target: "_self"` to ask for a same-tab navigation; it is honoured only
+where the router provably will not claim the url:
+
+| Link | Editor mounted under a prefix | Editor at the origin root |
+| --- | --- | --- |
+| Another origin (`https://tools.acme.com/x`) | same tab | same tab |
+| Same origin, outside the mount (`/curate`) | same tab | new tab |
+| Same origin, inside the mount | new tab | new tab |
+
+Anything else — a relative href that resolves back inside the mount, a `javascript:` url, an
+unparseable one — degrades to a new tab rather than stranding the editor on its 404. A
+same-tab link runs the unsaved-changes guard first, so it cannot silently discard an edit in
+progress.
+
+> **`signInUrl` must be a page that exists.** An unauthenticated load calls it after
+> clearing the stored session, so a path that 404s into this SPA's own catch-all leaves the
+> editor bouncing between the redirect and itself with no session to recover from. Point it
+> at a page you have already deployed. `?setup=1` always forces the built-in screen, for
+> pasting a first-admin JWT.
 
 **Set `brand` when you deploy this for a client.** The editor ships as a package an agency
 installs on someone else's behalf, so the default wordmark — `pramen · cms editor`, in the
@@ -76,12 +122,8 @@ A malformed `brand` can never take the editor down: a non-string value is ignore
 than thrown on, and a `brand` that yields no usable name logs a console warning instead of
 silently shipping "pramen" to your client.
 
-The `<title>` in `index.html` is baked at build time, before any config exists, so the app
-re-applies the configured brand on boot; the static tag is the pre-hydration fallback, which
-means the default shows for the moment before the bundle runs.
-
-A clean build regenerates `config.js` when it is missing, but never overwrites one that is
-already there — including on every `dev` rebuild — so an edit you are previewing survives.
+The shell's `<title>` is written before the bundle runs, so the app re-applies the
+configured brand on boot; the server-rendered tag is the pre-hydration fallback.
 
 Settings → About still reports `pramen · cms-editor`. That row names the *software* you are
 running, not the deployment, which is what an About panel is for.