@pramen/cms-editor 0.0.52 → 0.0.54

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/cms-editor",
-  "version": "0.0.52",
+  "version": "0.0.54",
   "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
@@ -20,7 +27,7 @@ declare global {
       hidePages?: boolean;
       /** Extra top-nav links to companion tools the host serves (e.g. a curation page).
        * Rendered as plain external `<a>` links after the built-in tabs. */
-      extraNav?: { label: string; href: string }[];
+      extraNav?: { label: string; href: string; target?: "_blank" | "_self" }[];
       /** The wordmark in the topbar, on the Setup screen, and in the browser tab.
        *
        * This editor ships as a package an agency deploys FOR ITS CLIENT, so the default
@@ -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,203 @@
+// 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 non-empty path segments rooted at the origin, written
+ * only in characters that `URL.pathname` returns UNENCODED.
+ *
+ * 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.
+ *
+ * The character set is not a style choice. Every comparison against a mount path in this
+ * file — and buzola's own `stripBasePath`, which we cannot change — is a raw `startsWith`
+ * against a `URL.pathname`, which is percent-ENCODED. Admit a character the parser encodes
+ * and the two sides can never match: a mount of `/správa` is compared against
+ * `/spr%C3%A1va/...` and EVERY in-prefix url reads as off-prefix. So the admitted set is
+ * derived from the parser rather than guessed — `"<>^`{}`, backslash, space and everything
+ * non-ASCII all encode, and are refused here. */
+const MOUNT_PATH = /^(?:\/[A-Za-z0-9!$%&'()*+,\-.:;=@[\]_|~]+)+$/;
+
+/**
+ * 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();
+  // Trailing slashes come off FIRST, so `MOUNT_PATH` only ever judges the canonical form
+  // and a value that is nothing but slashes collapses to the root rather than being warned
+  // about as malformed.
+  const canonical = trimmed.replace(/\/+$/, "");
+  if (canonical === "") return "";
+  if (!MOUNT_PATH.test(canonical)) {
+    console.warn(`pramen/cms-editor: ignoring unusable mount path ${JSON.stringify(trimmed)} — mounting at the origin root.`);
+    return "";
+  }
+  return canonical;
+}
+
+/** 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>();
+  // Spread, not a hand-written list of the seven methods. Enumerating them forwards
+  // correctly today but only fails safe by luck: tsc catches a newly REQUIRED member of
+  // `NavigationAdapter`, while an OPTIONAL one is silently dropped — and the next planned
+  // buzola bump (past ^0.0.12, for `router.leaveApp`) is exactly where such a member would
+  // arrive. Overriding the two listener methods is the whole of what this wrapper does.
+  return {
+    ...inner,
+    addEventListener(type, handler) {
+      // Adding the same handler twice would attach two wrappers to the inner adapter while
+      // the map kept only the second, so the first could never be removed and would keep
+      // feeding a torn-down router. Nothing does this today (`Router.start()` mints a fresh
+      // closure per call), which is precisely why it should be closed while it is free.
+      if (wrappers.has(handler)) return;
+      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);
+    },
+  };
+}
+
+/**
+ * Whether a host-configured nav link may navigate the CURRENT tab.
+ *
+ * The default for `extraNav` is a new tab, because `_404.tsx` registers the catch-all
+ * `/:__notFound+`: an unmounted editor's router matches every same-origin path, so a
+ * same-tab click would land on the in-app 404 instead of the tool. `target: "_self"` asks
+ * for the co-hosted case, and is honoured only where it cannot strand the user.
+ *
+ * Lives here, not in the layout, for two reasons: these are the same containment rules
+ * `scopeToBasePath` enforces and they belong beside them, and a predicate that decides
+ * whether a click escapes the SPA has to be testable without a DOM. `documentUrl` is a
+ * PARAMETER rather than a read of `window.location` for the same reason — and because it
+ * is the one input that must not be guessed:
+ *
+ *   - Resolve against `location.origin` and a relative href like `"curate"` is judged as
+ *     `/curate` while the browser navigates to `<current dir>/curate`. Off-prefix by the
+ *     check, in-prefix in fact, so the link lands on the very 404 this exists to avoid.
+ *     `?tab=x` and `#top` are the same mistake with an even wider gap.
+ *   - So the caller passes the document URL the browser will itself resolve against.
+ */
+export function opensInSameTab(href: string, target: string | undefined, basePath: string, documentUrl: string): boolean {
+  if (target !== "_self") return false;
+  let url: URL;
+  let docOrigin: string;
+  try {
+    url = new URL(href, documentUrl);
+    docOrigin = new URL(documentUrl).origin;
+  } catch {
+    return false;
+  }
+  // `new URL` happily parses `javascript:` and `data:`, and their `pathname` is an opaque
+  // string that trivially fails any containment test — so without this they would take the
+  // same-tab branch and shed the `rel` that used to confine them. A url with no hierarchical
+  // path cannot be reasoned about as "inside or outside the mount"; the answer is no.
+  if (url.protocol !== "http:" && url.protocol !== "https:") return false;
+  // Cross-origin ALWAYS escapes on its own — the catch-all can only claim same-origin paths
+  // — so it is safe in the same tab whether or not this editor is mounted. That makes an
+  // external tool the one configuration that works at the origin root, which is the opposite
+  // of what a bare `basePath` check concludes.
+  if (url.origin !== docOrigin) return true;
+  // Same origin: safe only where the router will not claim it. At the root `isWithinBasePath`
+  // is true for everything, so this correctly refuses every same-origin `_self` there.
+  return !isWithinBasePath(url.pathname, basePath);
+}
+
+/** 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/src/routes/_layout.tsx

@@ -2,11 +2,12 @@
 // wrapped around every route via <Outlet />. Tab highlighting is derived from the
 // current path, so a deep link or refresh lands with the right tab lit.
 
-import { Outlet, useNavigate, useRoute } from "@buzola/router";
+import { Outlet, useNavigate, useRoute, useRouter } from "@buzola/router";
 import { Button, Card, MoonIcon, SunIcon, Text, Topbar } from "@podoba/react";
 import { useEffect, useState } from "react";
 import { useApp } from "../app-context";
 import { BRAND } from "../brand";
+import { opensInSameTab } from "../mount";
 
 const THEME_KEY = "pramen.cms.theme";
 
@@ -18,8 +19,11 @@ export default function RootLayout() {
   // Every chrome action here is a way OUT of the current screen, so it runs through that
   // screen's unsaved-changes guard first (the page editor registers one; with no guard
   // registered this is a pass-through). In-app navigation fires no `beforeunload`, so
-  // without this the topbar silently discards unsaved edits. The external `extraNav` links
-  // open in a new tab and leave nothing behind, so they stay unguarded.
+  // without this the topbar silently discards unsaved edits. An `extraNav` link that opens a
+  // NEW tab leaves this document alone and needs no guard; one honoured as `_self` is a real
+  // cross-document navigation, so it takes the guard too (below). `beforeunload` is not a
+  // fallback for it — only `PageEditor` registers one, so a dirty CollectionEditor form would
+  // otherwise be discarded with no prompt of any kind.
   const guarded = (go: () => void) => () => { if (confirmNavigation()) go(); };
 
   // Dark mode: podoba tokens flip under `[data-theme="dark"]` — no `dark:` prefixes.
@@ -47,6 +51,13 @@ export default function RootLayout() {
   // Collections-only deployments hide the block/page builder entirely.
   const hidePages = typeof window !== "undefined" ? window.PRAMEN_CMS_EDITOR?.hidePages === true : false;
 
+  // See the extraNav comment below. The rules live in `mount.ts` beside the containment they
+  // depend on; what this supplies is the URL the BROWSER will resolve a relative href
+  // against — the current document, not the origin. Empty when there is no `window`, which
+  // makes every href unparseable and so degrades to the safe new-tab default.
+  const basePath = useRouter().basePath;
+  const documentUrl = typeof window !== "undefined" ? window.location.href : "";
+
   return (
     // Page-level surface so the whole viewport (not just the topbar + cards) flips
     // under `[data-theme="dark"]` — otherwise the body stays white in dark mode.
@@ -89,24 +100,21 @@ export default function RootLayout() {
             Settings
           </Button>
           {extraNav.map((l) => (
-            // Companion tools live OUTSIDE this SPA (a separate static page/worker route), so
-            // open them in a new tab. NOT a style choice, and `target: "_self"` alone would not
-            // fix it: `_404.tsx` registers the catch-all `/:__notFound+`, so buzola matches
-            // EVERY same-origin path and intercepts it — a same-tab click and `location.assign`
-            // both land on the in-app 404 (verified). Only a cross-origin url escapes on its own.
+            // Defaults to a new tab: a companion tool is normally a separate deployment, and
+            // `_404.tsx` registers the catch-all `/:__notFound+`, so the router matches every
+            // SAME-ORIGIN path — a same-tab click would land on the in-app 404 rather than the
+            // tool. `target: "_self"` asks for the co-hosted case, and is honoured only where
+            // the router provably will not claim the url (`opensInSameTab` in mount.ts):
+            //
+            //   - cross-origin: always, mounted or not. The catch-all cannot reach another
+            //     origin, so this is the ONE case that also works at the origin root.
+            //   - same-origin: only outside the mount prefix, where `scopeToBasePath` leaves
+            //     the navigation to the browser. At the root there is no outside, so never.
             //
-            // The supported same-tab route is `router.leaveApp(href)` (@buzola/router >= 0.0.16),
-            // which releases one navigation to the browser. This package still pins ^0.0.12, so
-            // adopting it is a version bump plus a `target` option on the config item.
-            <a
-              key={l.href}
-              href={l.href}
-              target="_blank"
-              rel="noopener noreferrer"
-              className="rounded-md px-2.5 py-1.5 text-small text-fg-muted transition-colors hover:bg-surface-muted hover:text-fg"
-            >
-              {l.label}
-            </a>
+            // Anything else degrades to the new tab rather than stranding the user on a 404.
+            // (When @buzola/router moves past ^0.0.12 here, `router.leaveApp(href)` releases
+            // one navigation to the browser and makes same-origin `_self` work unmounted too.)
+            <NavLink key={`${l.href}|${l.label}`} link={l} sameTab={opensInSameTab(l.href, l.target, basePath, documentUrl)} confirm={confirmNavigation} />
           ))}
         </Topbar.Nav>
         <Topbar.Actions>
@@ -136,3 +144,29 @@ export default function RootLayout() {
     </div>
   );
 }
+
+/** One host-configured link to a companion tool.
+ *
+ * `rel="noreferrer"` is on BOTH branches. `noopener` is genuinely moot in the same tab (no
+ * new browsing context is created, so there is no `window.opener` to sever) but `noreferrer`
+ * is not: without it a click from `/_pramen/admin/pages/<id>` hands that full url to the
+ * destination as `Referer`, and `_self` is honoured for cross-origin destinations.
+ *
+ * The key pairs href with label, because two entries may legitimately point at the same href
+ * and differ only in label or target — keyed on href alone React reconciles them together
+ * and the rendered label can end up on the other one's anchor.
+ */
+function NavLink({ link, sameTab, confirm }: { link: { label: string; href: string; target?: string }; sameTab: boolean; confirm: () => boolean }) {
+  return (
+    <a
+      href={link.href}
+      rel={sameTab ? "noreferrer" : "noopener noreferrer"}
+      // Only the same-tab case unloads this document, so only it consults the guard.
+      onClick={sameTab ? (e) => { if (!confirm()) e.preventDefault(); } : undefined}
+      {...(sameTab ? {} : { target: "_blank" })}
+      className="rounded-md px-2.5 py-1.5 text-small text-fg-muted transition-colors hover:bg-surface-muted hover:text-fg"
+    >
+      {link.label}
+    </a>
+  );
+}

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>