@pramen/cms-editor 0.0.52 → 0.0.53

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/cms-editor",
-  "version": "0.0.52",
+  "version": "0.0.53",
   "description": "Visual block/page editor for @pramen/cms \u2014 a standalone React SPA that talks to the CMS handlers over HTTP.",
   "license": "MIT",
   "repository": {
@@ -11,6 +11,10 @@
   "homepage": "https://github.com/netvarec/pramen#readme",
   "bugs": "https://github.com/netvarec/pramen/issues",
   "type": "module",
+  "exports": {
+    "./editor.js": "./dist/editor.js",
+    "./editor.css": "./dist/editor.css"
+  },
   "files": [
     "dist",
     "src"

package/src/api.ts

@@ -36,14 +36,26 @@ export function isTokenExpired(token: string): boolean {
 }
 
 const LS = "pramen.cmsEditor";
-export function loadConfig(): Config {
+
+/**
+ * The session for this page load.
+ *
+ * A backend DECLARED by the shell (see `mount.ts`) wins over anything stored: the server
+ * that served the editor knows where its own API is, so there is nothing for a person to
+ * type and get wrong, and a stale url from an earlier deployment can't outlive it. Only
+ * the token is the browser's to remember.
+ */
+export function loadConfig(declared?: { url: string; tenant: string }): Config {
+  let stored: Partial<Config> = {};
   try {
     const raw = localStorage.getItem(LS);
-    if (raw) return JSON.parse(raw) as Config;
+    if (raw) stored = JSON.parse(raw) as Partial<Config>;
   } catch {
     /* ignore */
   }
-  return { baseUrl: "http://localhost:8787", token: "", tenant: "main" };
+  const token = typeof stored.token === "string" ? stored.token : "";
+  if (declared) return { baseUrl: declared.url, tenant: declared.tenant, token };
+  return { baseUrl: stored.baseUrl ?? "http://localhost:8787", tenant: stored.tenant ?? "main", token };
 }
 export function saveConfig(cfg: Config): void {
   localStorage.setItem(LS, JSON.stringify(cfg));

package/src/app-context.tsx

@@ -7,12 +7,19 @@ import { Button, Input } from "@podoba/react";
 import { createContext, use, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { Api, clearConfig, isTokenExpired, loadConfig, saveConfig, type Config } from "./api";
 import { BRAND, SETUP_TITLE, type BrandConfig } from "./brand";
+import { readBackend, type BackendHost } from "./mount";
 import { DEFAULT_CAPABILITIES, type CmsCapabilities, type CollectionMeta, type JsonValue } from "./types";
 
 declare global {
   interface Window {
-    /** Runtime config set by the host's /config.js (see @pramen/cms-editor build). */
+    /** Runtime config written by the SHELL that served the editor — a server-rendered
+     * inline script, not a file anyone hand-edits (see `PramenAdmin.astro` in
+     * @pramen/cms-astro, and the dev preview in scripts/build.ts). */
     PRAMEN_CMS_EDITOR?: {
+      /** Which CMS Worker to call, and as which tenant. Declared by the shell because the
+       * server already knows — it is what makes the Setup screen a token field and
+       * nothing else. `url: ""` means the CMS is on this same origin. */
+      backend?: { url?: string; tenant?: string };
       signInUrl?: string;
       /** Hide the Pages tab for deployments that use collections only — no block/page
        * building. The tab is otherwise always shown and lands on an empty list, which
@@ -32,7 +39,11 @@ declare global {
   }
 }
 
-/** External sign-in URL, if the host configured one via /config.js. When set, an
+/** The backend the shell declared, or `undefined` when it declared none (the dev preview's
+ * standalone mode). Present ⇒ the Setup screen asks for a token and nothing else. */
+const BACKEND = readBackend(globalThis as BackendHost);
+
+/** External sign-in URL, if the host configured one. When set, an
  * unauthenticated OR expired session is redirected here instead of the built-in Setup
  * screen — for deployments whose auth (magic-link, SSO, …) lives on a separate page.
  *
@@ -88,14 +99,16 @@ export function useApp(): AppContextValue {
 }
 
 export function AppProvider({ children }: { children: React.ReactNode }) {
-  const [cfg, setCfg] = useState<Config>(loadConfig());
+  const [cfg, setCfg] = useState<Config>(() => loadConfig(BACKEND));
   const [me, setMe] = useState<Me | null>(null);
   const [collections, setCollections] = useState<CollectionMeta[]>([]);
   const [cms, setCms] = useState<CmsCapabilities>(DEFAULT_CAPABILITIES);
   const [error, setError] = useState("");
-  // A usable session = a base URL + a token that is NOT expired. An expired token counts as
-  // no session: otherwise the editor mounts and every RPC 403s into an error banner.
-  const authValid = Boolean(cfg.baseUrl && cfg.token) && !isTokenExpired(cfg.token);
+  // A usable session = somewhere to call + a token that is NOT expired. An expired token
+  // counts as no session: otherwise the editor mounts and every RPC 403s into an error
+  // banner. "Somewhere to call" is satisfied by a declared backend even when its url is the
+  // empty string, which is the same-origin case and a perfectly good place to call.
+  const authValid = Boolean(BACKEND || cfg.baseUrl) && Boolean(cfg.token) && !isTokenExpired(cfg.token);
   const api = useMemo(() => new Api(cfg, SIGN_IN_URL ? redirectToSignIn : undefined), [cfg]);
 
   // Unsaved-changes guard for in-app navigation. A ref, not state: the guard is read at
@@ -171,14 +184,28 @@ function Setup({ cfg, onSave }: { cfg: Config; onSave: (c: Config) => void }) {
         <h1 className="mb-4 text-display text-fg">
           {BRAND.name} <span className="text-fg-subtle">{SETUP_TITLE}</span>
         </h1>
+        {/* Two screens, because there are two things a deployment can leave unanswered. When
+            the shell declared a backend there is nothing to point at — asking for a URL that
+            is already known invites someone to type the mount path instead of the origin and
+            get a stream of "non-JSON response" back. */}
         <p className="mb-6 text-sm text-fg-muted">
-          Point at your Worker and paste an editor/reviewer JWT. CORS must allow this origin (<code>CORS_ORIGINS</code>).
+          {BACKEND ? (
+            <>Paste an editor/reviewer JWT to sign in.</>
+          ) : (
+            <>
+              Point at your Worker and paste an editor/reviewer JWT. CORS must allow this origin (<code>CORS_ORIGINS</code>).
+            </>
+          )}
         </p>
         <div className="flex flex-col gap-4">
-          <Input label="Worker base URL" value={c.baseUrl} onChange={(baseUrl) => setC({ ...c, baseUrl })} placeholder="https://your-worker.workers.dev" />
-          <Input label="Tenant" value={c.tenant} onChange={(tenant) => setC({ ...c, tenant })} placeholder="main" />
+          {BACKEND ? null : (
+            <>
+              <Input label="Worker base URL" value={c.baseUrl} onChange={(baseUrl) => setC({ ...c, baseUrl })} placeholder="https://your-worker.workers.dev" />
+              <Input label="Tenant" value={c.tenant} onChange={(tenant) => setC({ ...c, tenant })} placeholder="main" />
+            </>
+          )}
           <Input label="Bearer token (editor or reviewer)" value={c.token} onChange={(token) => setC({ ...c, token })} placeholder="eyJ…" />
-          <Button className="mt-2 w-full" onPress={() => onSave(c)} isDisabled={!c.baseUrl || !c.token}>
+          <Button className="mt-2 w-full" onPress={() => onSave(c)} isDisabled={(!BACKEND && !c.baseUrl) || !c.token}>
             Connect
           </Button>
         </div>

package/src/main.tsx

@@ -1,16 +1,18 @@
-import { BuzolaProvider } from "@buzola/router";
-import { StrictMode } from "react";
+import { BuzolaProvider, Router, createBrowserNavigationAdapter } from "@buzola/router";
+import { StrictMode, useRef } from "react";
 import { createRoot } from "react-dom/client";
 import { pageRegistry, routes } from "virtual:buzola/routes";
 import { AppProvider } from "./app-context";
 import { DOCUMENT_TITLE } from "./brand";
+import { isWithinBasePath, readBasePath, scopeToBasePath } from "./mount";
 
-// Styling is podoba: @podoba/tokens/variables.css + the compiled Tailwind (podoba
-// preset) are <link>ed by index.html (see scripts/build.ts). No more inline CSS.
+// Styling is podoba: the compiled Tailwind (podoba preset, with @podoba/tokens' variables
+// and the web font inlined) is a single stylesheet the SHELL links — see scripts/build.ts
+// for what is built, and @pramen/cms-astro for the shell that serves it.
 
-// The <title> in index.html is baked at build time, before any host config exists, so it
-// can only be the default. Re-apply the configured wordmark once /config.js has been read —
-// the static tag stays the pre-hydration fallback.
+// The shell's <title> is written before the app boots, so on a deployment that has
+// configured a wordmark it can only be the default. Re-apply the configured one here; the
+// server-rendered tag stays the pre-hydration fallback.
 //
 // `DOCUMENT_TITLE`, not `${BRAND.title} editor`: appending a fixed English noun to the one
 // string this feature exists to hand over would put a foreign word in a rebranded client's
@@ -18,11 +20,42 @@ import { DOCUMENT_TITLE } from "./brand";
 document.title = DOCUMENT_TITLE;
 
 const el = document.getElementById("app");
+const basePath = readBasePath(el);
+
+// The prefix and the URL the shell was served at come from the same place, so a mismatch
+// means the shell and the route that rendered it have drifted. Worth one line: the symptom
+// is otherwise a silent 404 on the host site for every click in the topbar, with an empty
+// console — buzola's own "no route matched" warning is dead here, because `_404.tsx`'s
+// catch-all guarantees a match.
+if (!isWithinBasePath(location.pathname, basePath)) {
+  console.warn(`pramen/cms-editor: mounted for "${basePath}" but served at "${location.pathname}" — navigation will leave the editor.`);
+}
+
+/** The router, built lazily so it exists only once there is a session to route.
+ *
+ * `AppProvider` renders the Setup screen (or hands off to sign-in) WITHOUT its children
+ * when there is no valid session, and `createBrowserNavigationAdapter()` throws outright on
+ * a browser with no Navigation API. Constructing at module scope would turn that into a
+ * blank page before `createRoot` ever ran; here it stays what it was — the Setup screen,
+ * where a first admin can still paste a JWT.
+ */
+function EditorRouter({ basePath }: { basePath: string }) {
+  const router = useRef<Router | null>(null);
+  router.current ??= new Router({
+    routes,
+    // Scoped, so a co-hosted editor intercepts navigation within its own mount only.
+    adapter: scopeToBasePath(createBrowserNavigationAdapter(), basePath),
+    pageRegistry,
+    basePath,
+  });
+  return <BuzolaProvider router={router.current} />;
+}
+
 if (el)
   createRoot(el).render(
     <StrictMode>
       <AppProvider>
-        <BuzolaProvider routes={routes} pageRegistry={pageRegistry} />
+        <EditorRouter basePath={basePath} />
       </AppProvider>
     </StrictMode>,
   );

package/src/mount.ts

@@ -0,0 +1,143 @@
+// Where the editor is mounted, and which backend it talks to — read off the shell that
+// served it.
+//
+// The SPA's routes are authored from "/" ("/media", "/pages/:pageId", …), so an editor
+// served under a path prefix needs buzola's Router to prepend it. That prefix is NOT
+// something a human configures: the server that ROUTED the request is the same one that
+// renders the shell, so it stamps the prefix onto the mount node and the two can never
+// disagree. `@pramen/cms-astro` injects its admin route and writes this attribute from a
+// single constant; the dev preview server does the same.
+//
+// A `data-*` attribute rather than a global, for the one value that must be right:
+// `dataset` is a string or undefined BY CONSTRUCTION, so there is no non-string value to
+// guard against, and it cannot be set for an element other than the one being mounted.
+//
+// Deliberately free of React and of any runtime buzola import (the adapter types below are
+// type-only, hence erased), so every rule here can be exercised without a DOM.
+
+import type { BuzolaNavigateEvent, NavigationAdapter } from "@buzola/router";
+
+/** A mount path must be a chain of path segments rooted at the origin.
+ *
+ * Rooted, and required to say so: buzola prepends the base path to every href it builds, so
+ * anything that is not already an absolute path resolves somewhere unintended. A leading
+ * slash is NOT added for a value missing one — that convenience is what turns a pasted
+ * `https://host/admin` into `/https://host/admin`, which is a real path and would be
+ * mounted. `//cdn.example.com` is rejected for the same reason: protocol-relative, and the
+ * natural product of `"/" + prefix` where the prefix already carried a slash.
+ *
+ * Segments only, too: a value carrying `?`, `#` or `\` is not a mount path, and each breaks
+ * routing in its own silent way (a query swallows the rest of every href; a backslash
+ * resolves off-site while looking local). */
+const MOUNT_PATH = /^\/[^/\\?#][^\\?#]*$/;
+
+/**
+ * Normalize the mount node's declared prefix to buzola's shape: `""` for the origin root,
+ * else a leading slash and no trailing one.
+ *
+ * Nothing declared means the root, which is how the editor has always been served. A
+ * declared-but-unusable value is WARNED about and falls back to the root rather than
+ * routing every link through a stray prefix — the value is server-generated, so if one
+ * ever fails this check something upstream is wrong and a green deploy is the worst place
+ * to discover it (`brand.ts` warns for the same reason).
+ */
+export function resolveBasePath(raw?: string | null): string {
+  const trimmed = (raw ?? "").trim();
+  if (trimmed === "" || trimmed === "/") return "";
+  if (!MOUNT_PATH.test(trimmed)) {
+    console.warn(`pramen/cms-editor: ignoring unusable mount path ${JSON.stringify(trimmed)} — mounting at the origin root.`);
+    return "";
+  }
+  return trimmed.replace(/\/+$/, "");
+}
+
+/** Read the prefix the shell stamped onto the mount node. */
+export function readBasePath(el: { dataset: DOMStringMap } | null): string {
+  return resolveBasePath(el?.dataset.basePath);
+}
+
+/**
+ * Whether a pathname is INSIDE a mount prefix — the prefix itself, or something below it.
+ *
+ * Anchored at a segment boundary on purpose. buzola's own `stripBasePath` is a bare
+ * `startsWith`, so with a prefix of `/cms` the host's `/cmsmedia` strips to `media` and
+ * renders the editor's Media library at a URL that has nothing to do with the editor.
+ */
+export function isWithinBasePath(pathname: string, basePath: string): boolean {
+  if (!basePath) return true;
+  return pathname === basePath || pathname.startsWith(`${basePath}/`);
+}
+
+/**
+ * Scope a navigation adapter to one mount prefix.
+ *
+ * `Router.start()` intercepts every navigation that matches a route, and `_404.tsx`
+ * registers the catch-all `/:__notFound+` — so EVERY same-origin path matches. At the
+ * origin root that is correct (the editor is the whole origin). Co-hosted under a prefix
+ * it is not: a click on the host site's own `/blog` would be cancelled by `event.intercept`
+ * and render the editor's "Nothing lives here" while the address bar reads `/blog`.
+ *
+ * Filtering at the adapter means the router never SEES an off-prefix navigation, so the
+ * browser handles it natively — no route table changes, no buzola fork.
+ */
+export function scopeToBasePath(inner: NavigationAdapter, basePath: string): NavigationAdapter {
+  if (!basePath) return inner;
+  type Handler = (event: BuzolaNavigateEvent) => void;
+  // Keyed by the caller's handler so `removeEventListener` can find the wrapper it added;
+  // without this the router's `start()` teardown would leave the listener attached.
+  const wrappers = new Map<Handler, Handler>();
+  return {
+    getCurrentURL: () => inner.getCurrentURL(),
+    navigate: (url, options) => inner.navigate(url, options),
+    back: () => inner.back(),
+    forward: () => inner.forward(),
+    getState: () => inner.getState(),
+    addEventListener(type, handler) {
+      const wrapper: Handler = (event) => {
+        // A malformed destination is not ours to claim.
+        let pathname: string;
+        try {
+          pathname = new URL(event.destination.url).pathname;
+        } catch {
+          return;
+        }
+        if (isWithinBasePath(pathname, basePath)) handler(event);
+      };
+      wrappers.set(handler, wrapper);
+      inner.addEventListener(type, wrapper);
+    },
+    removeEventListener(type, handler) {
+      const wrapper = wrappers.get(handler);
+      if (!wrapper) return;
+      wrappers.delete(handler);
+      inner.removeEventListener(type, wrapper);
+    },
+  };
+}
+
+/** The backend the shell declared: which Worker to call, and as which tenant.
+ *
+ * When present these are NOT read from (or written to) localStorage — the server knows
+ * where its own API is, and a stale stored value from an earlier deployment would win
+ * forever otherwise. Only the session token is the browser's to remember. */
+export interface DeclaredBackend {
+  /** Origin of the CMS Worker. `""` means same-origin. */
+  url: string;
+  tenant: string;
+}
+
+/** What the shell may set under `window.PRAMEN_CMS_EDITOR.backend`. */
+export interface BackendHost {
+  PRAMEN_CMS_EDITOR?: { backend?: { url?: unknown; tenant?: unknown } };
+}
+
+/** Read the declared backend off a host global, or `undefined` when the shell declared
+ * none (the dev preview's standalone mode, where the Setup screen asks for it). */
+export function readBackend(host: BackendHost | undefined): DeclaredBackend | undefined {
+  const declared = host?.PRAMEN_CMS_EDITOR?.backend;
+  // A url is what makes the declaration meaningful; `""` (same-origin) is a real value, so
+  // this tests for the STRING, not for truthiness.
+  if (typeof declared?.url !== "string") return undefined;
+  const tenant = typeof declared.tenant === "string" && declared.tenant.trim() !== "" ? declared.tenant.trim() : "main";
+  return { url: declared.url.replace(/\/+$/, ""), tenant };
+}

package/dist/config.js

@@ -1,15 +0,0 @@
-// Runtime configuration for the pramen CMS editor. Override this file in your host app —
-// no rebuild needed. Every field is optional:
-//
-//   window.PRAMEN_CMS_EDITOR = {
-//     // Send unauthenticated / expired sessions to your own sign-in page instead of the
-//     // built-in Setup screen (?setup=1 still forces Setup, to paste a first-admin JWT):
-//     signInUrl: "/signin/",
-//     // The wordmark in the topbar, on the Setup screen and in the browser tab. Set this
-//     // when you deploy the editor for a client — the default says "pramen", which is the
-//     // framework's name, not theirs. `suffix: null` drops the "· cms" half.
-//     brand: { name: "Acme", suffix: "cms" },
-//     hidePages: true,                                  // collections-only deployments
-//     extraNav: [{ label: "Curation", href: "/curate" }],
-//   };
-window.PRAMEN_CMS_EDITOR = window.PRAMEN_CMS_EDITOR || {};

package/dist/fonts/README.md

@@ -1,18 +0,0 @@
-# Font binaries
-
-`@font-face` in [`../fonts.css`](../fonts.css) references the file below by exact
-name. Drop the woff2 here and it's bundled and served by any consumer that
-imports `@podoba/tokens/fonts.css`.
-
-NC Fontina is a **variable font** — a single file covers the whole weight axis:
-
-| File                         | Axis    | Covers                                            |
-| ---------------------------- | ------- | ------------------------------------------------- |
-| `nc-fontina-variable.woff2`  | `wght`  | 400 `font-normal` · 500 `font-medium` · 600 `font-semibold` · 700 `font-bold` |
-
-The `@font-face` declares `font-weight: 100 900` (a range). Narrow it in
-`fonts.css` to the font's real `wght` axis if it's smaller (e.g. `400 700`).
-
-Italics: this upright file only. If NC Fontina has a separate italic file, add a
-second `@font-face` with `font-style: italic`; otherwise the browser synthesizes
-obliques where `italic` is used (e.g. the rich-text editor).

package/dist/fonts.css

@@ -1,45 +0,0 @@
-/*
- * @podoba/tokens/fonts.css — bundled web fonts for the design system.
- *
- * HAND-AUTHORED (unlike variables.css, which is generated). This file ships the
- * actual font binaries via @font-face and points the family-name token at them,
- * so any consumer gets the real typeface with a single import:
- *
- *   import "@podoba/tokens/variables.css";
- *   import "@podoba/tokens/fonts.css";   // ← add this alongside variables.css
- *
- * NC Fontina is our primary UI sans. The @font-face `src` uses relative URLs, so
- * bundlers (Vite/webpack/Next) resolve and fingerprint `./fonts/*.woff2` for you.
- * `font-display: swap` renders fallback text immediately and swaps in NC Fontina
- * when it loads — no invisible-text flash.
- *
- * Drop the binary into ./fonts/ as nc-fontina-variable.woff2 (see
- * ./fonts/README.md). This is a VARIABLE font: one file covers the whole weight
- * axis, so `font-weight` is a RANGE. NC Fontina's wght axis is 200–700 (verified
- * via fontTools); the components use font-normal (400), font-medium (500),
- * font-semibold (600), font-bold (700) — all inside that range.
- */
-
-@font-face {
-	font-family: 'NC Fontina';
-	font-style: normal;
-	font-weight: 200 700;
-	font-display: swap;
-	src: url('./fonts/nc-fontina-variable.woff2') format('woff2');
-}
-
-/*
- * Point the family-name token at NC Fontina. This override lives HERE, not in the
- * auto-generated variables.css (which would clobber it on the next token sync).
- * Because fonts.css is imported after variables.css, this :root rule wins the
- * cascade. The fallback stack mirrors the generated --font-sans so metrics stay
- * close before NC Fontina loads / if it fails.
- *
- * font-feature-settings turns on NC Fontina's stylistic sets ss02–ss05 (the
- * default letterforms the brand uses: jy/at/g ligatures and the @ alternate).
- * It's an inherited property, so declaring it on :root cascades to every element.
- */
-:root {
-	--font-sans: 'NC Fontina', ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
-	font-feature-settings: 'ss02' 1, 'ss03' 1, 'ss04' 1, 'ss05' 1;
-}

package/dist/index.html

@@ -1,19 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>pramen · cms editor</title>
-    <link rel="stylesheet" href="/fonts.css" />
-    <link rel="stylesheet" href="/app.css" />
-    <!-- Runtime config, loaded before the app so window.PRAMEN_CMS_EDITOR is set at boot.
-         A default config.js ships in dist; a host overrides it to set e.g. signInUrl or
-         the wordmark. The <title> below is the pre-hydration fallback — the app re-applies
-         the configured brand on boot, since this file is baked before any config exists. -->
-    <script src="/config.js"></script>
-  </head>
-  <body>
-    <div id="app"></div>
-    <script type="module" src="/main.a0tgw8hg.js"></script>
-  </body>
-</html>