@pramen/cms-editor 0.0.63 → 0.0.65

package/src/panel-runtime.ts

@@ -0,0 +1,105 @@
+// What the editor bundle publishes on `globalThis` for panel bundles to build against.
+//
+// A panel is a separate bundle that renders into THIS bundle's React tree. Two copies of
+// React in one page share no hook dispatcher, so a second copy does not degrade — the first
+// `useState` in a panel throws "invalid hook call" and the screen is a blank error. The
+// panel bundle therefore cannot contain React; it must import the one already here.
+//
+// So the editor publishes its React (plus react-dom and both JSX runtimes) on a global, and
+// the shell's import map points those bare specifiers at four tiny shim modules that read it
+// back out — see `panel-globals.ts`, which GENERATES the shims from the very namespaces
+// published here, so the names they re-export cannot drift from the React actually loaded.
+//
+// The consequence, and the whole point: a panel is written as ordinary React, with ordinary
+// `import { useState } from "react"`, built with react/react-dom marked external. Nothing
+// about the source says it is a panel except the one `registerPanel` call. That is what
+// makes an existing standalone screen portable rather than rewritable.
+//
+// THE SURFACE IS FOUR NAMESPACES AND ONE FUNCTION, and it is meant to stay that size —
+// every name here is a thing this package can never move again:
+//
+//   - `react` — the shared copy. Non-negotiable; it is the reason this exists.
+//   - `reactDom` — shared for the same reason, one level down. A panel that bundled its own
+//     react-dom would be a SECOND RECONCILER driving one React, which is worse than a second
+//     React because it can appear to work. It is also where `createPortal` lives, and a
+//     dialog is the first thing a panel needs that Block Kit could not express.
+//   - `jsxRuntime` / `jsxDevRuntime` — the automatic JSX transform emits imports from
+//     `react/jsx-runtime`, or from `react/jsx-dev-runtime` when the panel is built
+//     unminified. A panel bundle does not choose this, its compiler does — and the dev half
+//     is the one that MUST be here: left out, a development build resolves that specifier
+//     from the consumer's own node_modules and quietly bundles a second React, which is the
+//     exact failure this whole mechanism exists to prevent, arriving on the one build where
+//     nobody is looking for it.
+//   - `registerPanel` — the registration itself, and the gate: it refuses a bundle whose
+//     stated contract is not the one this editor implements, naming the slug and the fix.
+//     See `PANEL_RUNTIME_CONTRACT` in `panels.ts` for what bumps that number, and the note
+//     below for why the number itself is not published here.
+//
+// Not published, and each for a reason: the `Api` class (a panel gets the narrow `PanelApi`
+// through props — see `panels.ts`), the router (a panel owns its own screen, not the
+// editor's routing table), the podoba component library (it is a dependency a panel can
+// install itself, and freezing OUR version of it as a global API is a promise this package
+// should not make), and the app context (it carries the CMS's own state, none of which is a
+// project screen's business).
+
+import * as react from "react";
+import * as reactDom from "react-dom";
+import * as jsxRuntime from "react/jsx-runtime";
+import * as jsxDevRuntime from "react/jsx-dev-runtime";
+import { registerPanel, type PanelRegistration } from "./panels";
+
+/** Where the runtime is published. Namespaced away from `PRAMEN_CMS_EDITOR`, which is the
+ * SHELL's config: that object is written by the server and read by the editor, this one is
+ * written by the editor and read by panel bundles, and putting them together would invite a
+ * shell to think it may set part of this. */
+export const PANEL_RUNTIME_GLOBAL = "PRAMEN_CMS_EDITOR_RUNTIME";
+
+// THE CONTRACT NUMBER IS NOT ON THIS OBJECT, and that omission is the point of the check
+// rather than a gap in it. A panel must state the contract it was BUILT against; publishing
+// ours would put the answer key beside the question, since
+// `PRAMEN_CMS_EDITOR_RUNTIME.contract` is shorter to write than the literal and would satisfy
+// every editor forever — the check would then be this editor comparing its number to its
+// number. The number a panel states is `PANEL_RUNTIME_CONTRACT` in `panels.ts`, taken from
+// the docs or from a refusal message, which prints both sides. It was published here once,
+// read by nothing, and that is exactly what a version guarantee looks like when it is only a
+// field.
+
+export interface PanelRuntime {
+  readonly react: typeof react;
+  readonly reactDom: typeof reactDom;
+  readonly jsxRuntime: typeof jsxRuntime;
+  readonly jsxDevRuntime: typeof jsxDevRuntime;
+  registerPanel(def: PanelRegistration): void;
+}
+
+/** The host object a panel runtime is published on. */
+export interface PanelRuntimeHost {
+  [PANEL_RUNTIME_GLOBAL]?: PanelRuntime;
+}
+
+export function panelRuntime(): PanelRuntime {
+  return {
+    react,
+    reactDom,
+    jsxRuntime,
+    jsxDevRuntime,
+    // Wrapped rather than passed by reference so the published function is this module's,
+    // not the registry's — the registry keeps a second parameter (its warning sink) that is
+    // a test seam and must not become part of the surface a panel bundle can reach.
+    registerPanel: (def) => registerPanel(def),
+  };
+}
+
+/**
+ * Publish the runtime. Called at the very top of `main.tsx`, before anything is imported
+ * dynamically and before the router mounts, so that by the time a panel bundle's first
+ * `import "react"` is evaluated the global is already there.
+ *
+ * Publishing is unconditional — it does not wait to see whether any panel is configured.
+ * The object is four references; making it conditional would mean a deployment that adds a
+ * panel later has a second thing to switch on, and a debugging session that starts with
+ * "is the runtime there?" would have two answers.
+ */
+export function publishPanelRuntime(host: PanelRuntimeHost): void {
+  host[PANEL_RUNTIME_GLOBAL] = panelRuntime();
+}

package/src/panels.ts

@@ -0,0 +1,420 @@
+// The panel registry — where a deployment's own React screens are registered, and what
+// they are handed.
+//
+// A panel is a component in a SEPARATE bundle, built by the consuming project, that renders
+// inside this editor's chrome at `/apps/:slug`. The entry itself is a server fact
+// (`adminPanel()` in @pramen/cms): the server owns the slug, label, icon, position and the
+// role filter, and the bundle owns only the component. So this module never decides whether
+// a panel exists — it answers "is there a component for this slug yet, and if not, was one
+// turned away", and nothing more.
+//
+// HOW A BUNDLE GETS LOADED, AND WHY THE EDITOR DOES THE LOADING
+//
+// The obvious shape is for the shell to emit a second `<script type="module">` beside the
+// editor's. It does not work in either order. Placed FIRST, the panel bundle evaluates
+// before the editor has published the React it must share, so its very first import fails.
+// Placed SECOND, it races the editor's own first render, and a deep link to `/apps/:slug`
+// would resolve before the component it needs exists.
+//
+// So the shell declares panel bundle URLs as configuration and the EDITOR imports them,
+// after publishing the runtime and before mounting the router. Ordering stops being a
+// property of script tags and becomes a line of code. It also makes failure containable:
+// a bundle that 404s or throws costs its own panel, and the admin still boots.
+//
+// The loads are NOT awaited before the first paint. Everything else in the chrome already
+// arrives a round trip late (`listAdminPages` is what puts the entry in the nav at all), and
+// blocking `createRoot` on a third-party fetch means one hanging request is a blank admin.
+// Registration therefore notifies subscribers and the panel route re-reads — which is also
+// what makes "still loading" tellable from "the bundle never registered this slug".
+//
+// Deliberately free of React at RUNTIME (the component type below is erased), so every rule
+// here can be exercised without a DOM — the same discipline `mount.ts` keeps.
+
+import type { ComponentType } from "react";
+import type { RpcInput } from "./types";
+
+/** The authenticated transport a panel is handed.
+ *
+ * A NARROW view of the editor's `Api`, not the class itself. `Api` carries ~40 typed
+ * wrappers for CMS handlers — pages, media, menus, taxonomies — and none of that is a
+ * panel's business; handing the object over would make every one of those methods an API to
+ * keep. What a panel needs is the ability to call ITS OWN project handlers with the
+ * session's credentials attached, plus a way to turn a relative media path into a URL.
+ *
+ * The session is not exposed and cannot be: no token, no base URL, no tenant. A panel calls
+ * through this or it does not call at all, which keeps one answer to "what does an
+ * authenticated request from the admin look like".
+ */
+export interface PanelApi {
+  /** Call a CMS/project RPC handler as the signed-in user. Rejects with the server's error
+   * message on a non-`ok` envelope. */
+  call<T = unknown>(name: string, input?: RpcInput): Promise<T>;
+  /** Absolute URL for a relative media/serving path the backend returned. */
+  resolve(path: string): string;
+}
+
+/** What a panel component is handed. Four things, and the case for each:
+ *
+ *  - `api` — a panel with no authenticated transport is a static page.
+ *  - `basePath` — the editor may be mounted under a prefix (`/__admin`), and a panel that
+ *    builds its own hrefs has no other way to stay inside it. Without this the one thing a
+ *    panel is FOR — being part of the admin — is the thing it gets wrong.
+ *  - `theme` — the chrome's light/dark choice. Styling follows automatically (podoba tokens
+ *    flip on `[data-theme]` at the document root), so this is for the decisions CSS cannot
+ *    make: a chart's palette, a canvas, an embedded third-party widget.
+ *  - `setError` — the editor has ONE error surface, the banner in the root layout. A panel
+ *    that invented a second would put failures in a place the reader has not learned to
+ *    look, and the two would style differently.
+ *
+ * What is deliberately NOT here is the identity (`me`). It is one `api.call("me")` away, and
+ * a panel that branches on the caller's roles to decide what to show is doing client-side
+ * authorization — the gate that counts is `roles` on `adminPanel()`, enforced server-side
+ * before the entry is even listed. Making the roles inconvenient to reach is the point.
+ */
+export interface PanelProps {
+  api: PanelApi;
+  basePath: string;
+  theme: "light" | "dark";
+  setError: (message: string) => void;
+}
+
+// --- the runtime contract ----------------------------------------------------------------
+//
+// A panel bundle is COMPILED there and LINKED here. Its JSX calls and its hook usage are
+// fixed at the consumer's build against whichever React they had installed; the React it
+// actually runs on is the one this editor loaded, on a deployment they do not control, at
+// whatever version that deployment is pinned to. Nothing in the loading path notices the
+// difference — the import map resolves, the shims hand over a perfectly good React — so a
+// mismatch surfaces as a missing export or a hook that behaves differently, somewhere inside
+// a stranger's minified bundle, with no message anyone can act on.
+//
+// So a bundle has to SAY which contract it was built against, and be turned away if it is not
+// this one.
+
+/**
+ * The panel runtime contract this editor implements.
+ *
+ * WHAT BUMPS IT. Three things, and this is the whole list:
+ *
+ *   1. **A React major in this package.** A panel's hooks and JSX are compiled against one
+ *      React's rules and executed against the editor's; going 19 -> 20 here silently moves
+ *      every panel bundle ever built onto a React it was not written for. This is the rule
+ *      that gets missed, because a React bump is a line in `package.json` nowhere near this
+ *      file — hence `PANEL_RUNTIME_REACT_MAJOR` below, which a test pins to the manifest.
+ *   2. **A change to what a panel is handed.** A key leaving `PanelProps`, or one changing
+ *      meaning; the same for `PanelApi`. ADDING a key is not a bump — a panel that does not
+ *      read it cannot notice.
+ *   3. **A change to the published runtime.** A name leaving `panel-runtime.ts`, or the
+ *      global it is published on being renamed.
+ *
+ * What does NOT bump it is everything a panel cannot reach: the chrome, the routes, the CMS
+ * handlers, podoba's version, this package's own release number. A contract that moved for
+ * those would be a release version wearing a check's clothes — every panel refused on an
+ * unrelated upgrade, and the only available response would be to edit the literal without
+ * rebuilding anything. A check people learn to satisfy blindly is worse than no check.
+ */
+export const PANEL_RUNTIME_CONTRACT = 1;
+
+/**
+ * The React major `PANEL_RUNTIME_CONTRACT` stands for.
+ *
+ * Written down so rule 1 above has somewhere to be enforced rather than only stated:
+ * `test/cms-editor-panels.test.ts` reads the `react` range out of this package's manifest and
+ * fails if it has moved past this number. Upgrading React therefore cannot silently leave the
+ * contract behind — the bump gets decided, in a red test, by whoever did the upgrade.
+ */
+export const PANEL_RUNTIME_REACT_MAJOR = 19;
+
+/** What a bundle passes to `registerPanel`: a slug, the contract it was built against, and
+ * the component to draw for it.
+ *
+ * No label, no icon, no position — those travel on the server's `adminPanel()` entry. If the
+ * bundle declared them, a bundle that failed to load would take the nav entry with it (so
+ * the section would silently cease to exist rather than say what went wrong), and a bundle
+ * that loaded would be asserting its own placement with nothing to check it against.
+ */
+export interface PanelRegistration {
+  /** Must match the `adminPanel()` slug on the server. A slug the server did not register
+   * (or did not list for this caller) is simply never routed to. */
+  slug: string;
+  /**
+   * The {@link PANEL_RUNTIME_CONTRACT} this bundle was BUILT against — a literal in the
+   * bundle's own source, `contract: 1`.
+   *
+   * A LITERAL, and it can be nothing else. None of this editor is in a panel bundle at build
+   * time: react, react-dom and both JSX runtimes are external and resolve, at runtime, to the
+   * copies this editor published. So every value the bundle could look up is this editor's,
+   * and a check fed from `globalThis` would be comparing our number to our number and passing
+   * for every bundle ever built. The literal is the only fact about the BUILD that survives
+   * into the bundle, which is why the published runtime does not carry the number at all —
+   * see `panel-runtime.ts`.
+   *
+   * That makes it the same kind of claim as a `peerDependencies` range: the author asserts it
+   * and the host verifies the shape. It can be edited without rebuilding and no check can
+   * catch that — but it cannot be edited by ACCIDENT, and it is the one line the refusal
+   * message names, right after telling you to rebuild.
+   *
+   * Required, never defaulted. A default is a value for the bundles that say nothing, and
+   * those are exactly the set this exists for: everything built before the field existed
+   * would be waved through as current.
+   */
+  contract: number;
+  render: ComponentType<PanelProps>;
+}
+
+/** What the registry KEEPS: the slug and the component.
+ *
+ * A separate type from `PanelRegistration` because the contract is a fact about the CALL, not
+ * about the panel — once it has been checked there is nothing left to store, and storing it
+ * would leave a field a later reader could imagine still differs from ours. */
+export interface RegisteredPanel {
+  slug: string;
+  render: ComponentType<PanelProps>;
+}
+
+const panels = new Map<string, RegisteredPanel>();
+const listeners = new Set<() => void>();
+/** Bundle imports still in flight. What tells "loading" from "loaded and never registered
+ * this slug" — the two look identical from the registry alone, and the second is a
+ * diagnostic worth printing rather than a spinner to leave up forever. */
+let inFlight = 0;
+/** Bumped on every registration, every refusal and every change to `inFlight`, and read as
+ * the `useSyncExternalStore` snapshot. A number rather than the Map, because a snapshot has to
+ * be referentially stable between notifications and a Map that is mutated in place is not. */
+let version = 0;
+/** Why a slug's registration was REFUSED, keyed by slug, so the panel's own route can say it
+ * instead of the generic "nothing registered this slug". The bundle IS there and it DID run;
+ * a refusal that reached only the console leaves the screen telling the reader something that
+ * is true and useless, and points them at the one thing that is not the problem. */
+const refusals = new Map<string, string>();
+
+function notify(): void {
+  version += 1;
+  for (const listener of [...listeners]) listener();
+}
+
+/** Turn a registration away.
+ *
+ * One sentence, two readers: it is rendered by the panel's route for whoever is looking at
+ * the admin, and warned for whoever is looking at the build — so it is written to read as
+ * prose in both places, with the package prefix added only on the console side. `notify`,
+ * because a route already mounted on that slug is showing "Loading…" and has to be told the
+ * loading ended in a refusal. */
+function refuse(slug: string, reason: string, warn: (msg: string) => void): void {
+  refusals.set(slug, reason);
+  warn(`pramen/cms-editor: ${reason}`);
+  notify();
+}
+
+/**
+ * Why a bundle's stated contract is unacceptable, or `undefined` if it is fine.
+ *
+ * BOTH directions are refusals, because they are different mistakes with different fixes. A
+ * bundle BEHIND this editor is stale — built against a React, or a `PanelProps`, that is not
+ * what it will be handed. A bundle AHEAD of it is not itself wrong; the deployment is, with a
+ * panel and an admin shipped out of step, and rendering it would link it against a runtime
+ * missing whatever the newer contract added. Accepting either would trade a message naming
+ * the slug for a crash inside someone else's bundle.
+ *
+ * A separate exported function, and not folded into `registerPanel`, so the sentence a
+ * consumer will actually be sent can be asserted on its own — the wording IS the feature
+ * here, and a check whose only test is "it refused" pins none of it.
+ *
+ * `implemented` is a parameter rather than a read of the constant for one reason, and it is
+ * not tidiness: at contract 1 there is no legal number BELOW ours, so the stale branch has
+ * nothing to be exercised with and would ship as a branch whose only evidence is that it
+ * typechecks. It is the same kind of seam as `warn`, and the registry never passes it.
+ */
+export function contractRefusal(slug: string, stated: unknown, implemented: number = PANEL_RUNTIME_CONTRACT): string | undefined {
+  // `stated` came out of a foreign bundle's object literal, so it is genuinely unknown: `"1"`
+  // is what a hand-edited build config produces, `NaN` is what `Number(undefined)` produces,
+  // and neither is a version. `Number.isInteger` alone would reject every one of them at
+  // RUNTIME — the `typeof` is what narrows the value for the comparisons below, and dropping
+  // it as redundant is a type error, not a passing simplification.
+  if (typeof stated !== "number" || !Number.isInteger(stated) || stated < 1) {
+    return `The '${slug}' panel did not state which panel runtime contract it was built against. Add \`contract: ${implemented}\` to its registerPanel() call and rebuild it against the @pramen/cms-editor this admin serves (React ${PANEL_RUNTIME_REACT_MAJOR}).`;
+  }
+  if (stated < implemented) {
+    return `The '${slug}' panel was built against panel runtime contract ${stated}, and this editor implements ${implemented}. Rebuild the bundle against the @pramen/cms-editor this admin serves (React ${PANEL_RUNTIME_REACT_MAJOR}) and set \`contract: ${implemented}\` in its registerPanel() call.`;
+  }
+  if (stated > implemented) {
+    return `The '${slug}' panel was built against panel runtime contract ${stated}, and this editor implements ${implemented}. Upgrade @pramen/cms-editor — and the shell that serves it — to the release implementing contract ${stated}, or rebuild the panel against this one.`;
+  }
+  return undefined;
+}
+
+/**
+ * Register a panel component. Called by a panel bundle, through the runtime published on
+ * `globalThis` — see `panel-runtime.ts`.
+ *
+ * THE CONTRACT IS CHECKED HERE, not in the runtime wrapper that publishes this function, and
+ * that is a decision rather than a convenience. This is the only chokepoint: the wrapper is
+ * one caller of it, and a check living there would leave the registry itself accepting a
+ * bundle built for another React — so the invariant would hold on one path and be a comment
+ * on every other. It is also the same KIND of judgement as the two refusals beside it (a
+ * missing slug, a `render` that is not a component): whether this registration may enter the
+ * registry at all. And it is here rather than in the generated shims because a shim resolves
+ * one bare specifier and has no registration to inspect — by the time anything knows a
+ * contract was stated, it is in this function's argument.
+ *
+ * A duplicate slug REPLACES rather than throwing. Registration happens inside a dynamic
+ * import of code this editor does not own, where a throw is swallowed into the loader's
+ * per-bundle catch and shows up as "the panel never registered" — the least informative
+ * possible report of "you registered it twice". A warning names both the slug and the fact,
+ * and the last registration wins, which is the only rule that makes a dev-time hot reload
+ * (re-evaluating the same bundle) behave. A refusal is not a throw for the same reason.
+ */
+export function registerPanel(def: PanelRegistration, warn: (msg: string) => void = console.warn): void {
+  const slug = typeof def?.slug === "string" ? def.slug.trim() : "";
+  if (!slug) {
+    // The only refusal with nothing to record it under, and nowhere to render it: without a
+    // slug there is no route to put it on. The console is the whole report.
+    warn("pramen/cms-editor: ignoring a panel registered with no slug — the slug is what matches it to its adminPanel() entry.");
+    return;
+  }
+  // Before `render`, because the contract is what decides whether the rest of this call means
+  // what it appears to: a bundle built for another React may well hand over a function that
+  // is not a component this editor can drive.
+  const mismatch = contractRefusal(slug, def.contract);
+  if (mismatch !== undefined) return refuse(slug, mismatch, warn);
+  const rendered = typeof def.render;
+  if (rendered !== "function") {
+    return refuse(slug, `The '${slug}' panel was ignored: 'render' must be a React component, and this one is of type ${rendered}.`, warn);
+  }
+  if (panels.has(slug)) warn(`pramen/cms-editor: panel '${slug}' was registered twice — the last registration wins.`);
+  // A registration that lands CLEARS the slug's refusal: a dev loop that fixes the contract
+  // and re-evaluates the bundle must not leave the old message on the screen.
+  refusals.delete(slug);
+  panels.set(slug, { slug, render: def.render });
+  notify();
+}
+
+/** The component registered for a slug, or `undefined`. */
+export function getPanel(slug: string): RegisteredPanel | undefined {
+  return panels.get(slug);
+}
+
+/** Why this slug's registration was turned away, if it was — read by the panel route, so a
+ * refused panel says what happened on the screen it was supposed to be. */
+export function panelRefusal(slug: string): string | undefined {
+  return refusals.get(slug);
+}
+
+/** Have all declared bundles finished loading (however they finished)? */
+export function panelsSettled(): boolean {
+  return inFlight === 0;
+}
+
+/** The registry's version — the `useSyncExternalStore` snapshot. */
+export function panelsVersion(): number {
+  return version;
+}
+
+export function subscribePanels(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/** Drop every registration and every listener. Tests only — the registry is module state,
+ * and a test that registered a panel must not leak it into the next one. */
+export function resetPanels(): void {
+  panels.clear();
+  listeners.clear();
+  refusals.clear();
+  inFlight = 0;
+  version = 0;
+}
+
+// --- bundle loading ---------------------------------------------------------------------
+
+/** What the shell may set under `window.PRAMEN_CMS_EDITOR.panels`. */
+export interface PanelHost {
+  PRAMEN_CMS_EDITOR?: { panels?: unknown };
+}
+
+/**
+ * Resolve one declared bundle URL, or reject it.
+ *
+ * These strings are `import()`ed, which is to say EXECUTED, so the check is about what a
+ * scheme can do and not about tidiness. `javascript:`, `data:` and `blob:` all parse
+ * happily as URLs and all name code with no origin to attribute it to; an http(s) URL is
+ * fetched under the page's own CSP and shows up in the network log like every other asset.
+ * So the allow-list is the two hierarchical web schemes and nothing else.
+ *
+ * Resolved against the DOCUMENT rather than the origin, for the reason `opensInSameTab`
+ * spells out: a relative specifier is what the browser would itself resolve that way, and
+ * resolving against `location.origin` instead would silently load a different file. It also
+ * means a fingerprinted asset path emitted by the host's bundler (`/_astro/panel.a1b2.js`)
+ * needs no special handling — it is just an absolute path.
+ */
+export function panelBundleUrl(raw: unknown, documentUrl: string): string | undefined {
+  if (typeof raw !== "string" || raw.trim() === "") return undefined;
+  let url: URL;
+  try {
+    url = new URL(raw.trim(), documentUrl);
+  } catch {
+    return undefined;
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") return undefined;
+  return url.href;
+}
+
+/**
+ * The bundle URLs the shell declared, resolved and filtered.
+ *
+ * A rejected entry is WARNED about and dropped rather than throwing: the value is
+ * server-generated (see `AdminRuntimeConfig` in @pramen/cms-astro), so one that fails this
+ * check means something upstream is wrong — and taking the whole admin down over a bad panel
+ * URL would be the worst possible place to discover it. `brand.ts` and `mount.ts` fail the
+ * same way for the same reason.
+ */
+export function readPanelUrls(host: PanelHost | undefined, documentUrl: string, warn: (msg: string) => void = console.warn): string[] {
+  const declared = host?.PRAMEN_CMS_EDITOR?.panels;
+  if (declared === undefined) return [];
+  if (!Array.isArray(declared)) {
+    warn("pramen/cms-editor: ignoring `panels` — it must be an array of module URLs.");
+    return [];
+  }
+  const out: string[] = [];
+  for (const entry of declared) {
+    const url = panelBundleUrl(entry, documentUrl);
+    if (url === undefined) warn(`pramen/cms-editor: ignoring unusable panel bundle URL ${JSON.stringify(entry)} — it must be an http(s) URL or a path.`);
+    else out.push(url);
+  }
+  return out;
+}
+
+/** How a bundle is fetched. A parameter so the loader can be exercised without a network. */
+export type PanelImporter = (url: string) => Promise<unknown>;
+
+const dynamicImport: PanelImporter = (url) => import(/* @vite-ignore */ url);
+
+/**
+ * Import every declared panel bundle, in parallel.
+ *
+ * Per-bundle `catch`, not one `try` around the lot: bundles are independent deployments of
+ * independent project code, and one that 404s must not take the others' registrations with
+ * it. The returned promise settles when all of them have, which is what `panelsSettled`
+ * reports — nothing awaits it on the boot path.
+ */
+export async function loadPanelBundles(
+  urls: readonly string[],
+  importer: PanelImporter = dynamicImport,
+  warn: (msg: string) => void = console.warn,
+): Promise<void> {
+  if (urls.length === 0) return;
+  inFlight += urls.length;
+  notify();
+  await Promise.all(
+    urls.map((url) =>
+      importer(url)
+        .catch((e: unknown) => {
+          warn(`pramen/cms-editor: panel bundle ${url} failed to load — ${String((e as Error)?.message ?? e)}`);
+        })
+        .finally(() => {
+          inFlight -= 1;
+          notify();
+        }),
+    ),
+  );
+}

package/src/routes/_layout.tsx

@@ -39,9 +39,9 @@ import { pagesHidden, splitsByType } from "../components";
 import { APP_BAR_H } from "../chrome";
 import { DarkThemeIcon, GroupFoldedIcon, GroupOpenIcon, LightThemeIcon, MenuToggleIcon, NAV_GLYPHS, RailToggleIcon, SettingsIcon, SignOutIcon } from "../icons";
 import { opensInSameTab } from "../mount";
+import { setTheme, useTheme } from "../theme";
 import { buildNav, NAV_SECTION_IDS, navSections, navSectionsAreLabelled, railIsNarrow, type ExtraNavLink, type NavIcon, type NavSectionId } from "../nav";
 
-const THEME_KEY = "pramen.cms.theme";
 /** Which nav groups this browser has folded away. Per-browser, like the theme — it is a
  * reading preference, not deployment configuration, and nothing server-side should carry it. */
 const COLLAPSED_KEY = "pramen.cms.nav.collapsed";
@@ -148,12 +148,10 @@ export default function RootLayout() {
   // 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.
-  const [theme, setTheme] = useState(() => (typeof localStorage !== "undefined" ? localStorage.getItem(THEME_KEY) ?? "light" : "light"));
-  useEffect(() => {
-    document.documentElement.dataset.theme = theme === "dark" ? "dark" : "light";
-    localStorage.setItem(THEME_KEY, theme);
-  }, [theme]);
+  // Dark mode. The choice lives in `theme.ts` rather than here: podoba's tokens flip under
+  // `[data-theme="dark"]` on the document root, `main.tsx` applies the stored one before the
+  // first paint, and a PANEL is handed the same value — three readers, so one store.
+  const theme = useTheme();
 
   // Below `md` the rail collapses to a disclosure under the brand row. A DISCLOSURE, not an
   // overlay drawer: an overlay owes the reader a focus trap, a restore and an Esc handler,

package/src/routes/admin-page.tsx

@@ -1,14 +1,26 @@
-// A custom admin page (`/apps/:slug`) — Block Kit, rendered inside the editor's own chrome.
+// A project's own screen (`/apps/:slug`), rendered inside the editor's own chrome.
 //
 // Routed BY THE EDITOR, which is the point: an `extraNav` link has to open a new tab,
 // because `_404.tsx` registers the catch-all `/:__notFound+` and a same-tab click on an
-// unmounted editor lands on the in-app 404. A registered page has a real route, so it is
+// unmounted editor lands on the in-app 404. A registered screen has a real route, so it is
 // part of the admin rather than a link out of it.
+//
+// ONE route for two kinds. A Block Kit page (`adminPage()`) is described as JSON by the
+// server and rendered here; a panel (`adminPanel()`) is a React component the deployment's
+// own bundle registered. They share this route because they share everything a URL and a nav
+// entry are made of — the slug space, the role filter, the "Apps" band, the breadcrumb — and
+// differ only in where the rendering happens. Splitting them would have meant a second
+// route, a second nav band and a slug that could mean two things.
 
-import { createPage, useNavigate } from "@buzola/router";
+import { createPage, useNavigate, useRouter } from "@buzola/router";
+import { useMemo, useSyncExternalStore } from "react";
 import { useApp } from "../app-context";
 import { AdminPageView } from "../blockkit";
 import { Notice } from "../components";
+import { PanelBoundary } from "../panel-boundary";
+import { getPanel, panelRefusal, panelsSettled, panelsVersion, subscribePanels, type PanelProps } from "../panels";
+import { useTheme } from "../theme";
+import { adminPageKind } from "../types";
 import { Button } from "@podoba/react";
 
 export default createPage()
@@ -29,8 +41,70 @@ export default createPage()
         </Notice>
       );
     }
+    if (adminPageKind(def) === "panel") return <PanelRoute slug={def.slug} />;
     // Keyed on the slug so switching between two pages REMOUNTS the view: buzola renders the
     // same component instance across a params-only change, and the blocks, the form values
     // and any toast all belong to one page.
     return <AdminPageView api={api} key={def.slug} slug={def.slug} label={def.label} onError={setError} />;
   });
+
+/**
+ * A panel: the component the deployment's own bundle registered for this slug.
+ *
+ * The registry is external state that changes without React knowing — bundles are imported
+ * from `main.tsx` and register whenever they land — so it is read through
+ * `useSyncExternalStore` rather than an effect. That is what makes a deep link to a panel
+ * work: the route can mount before the bundle has finished loading, and re-renders when it
+ * has, instead of deciding once and being wrong forever.
+ */
+function PanelRoute({ slug }: { slug: string }) {
+  const { api, setError } = useApp();
+  const theme = useTheme();
+  const basePath = useRouter().basePath;
+  const version = useSyncExternalStore(subscribePanels, panelsVersion, panelsVersion);
+  // `version` is the snapshot, not the value — a stable number is what a store hook needs,
+  // and the lookup is what the render actually wants. Depending on it is the point.
+  const panel = useMemo(() => getPanel(slug), [slug, version]);
+
+  if (!panel) {
+    // Three different situations, and only the first is a spinner.
+    //
+    // A REFUSAL comes first because it is the one the generic message would actively mislead
+    // about: the bundle is listed, it loaded, it ran, and it called `registerPanel` — telling
+    // the reader to go and check those four things sends them past the actual answer. The
+    // registry already holds a sentence naming the slug and the fix (a contract built against
+    // a different editor, a `render` that is not a component), so it is shown verbatim.
+    //
+    // Otherwise: the server listed this panel (it is in `adminPages`, so the caller may open
+    // it), which means the bundle either has not landed yet or landed and never registered
+    // this slug. The last is a deployment mistake — a missing `panels` entry, a bundle built
+    // without the `registerPanel` call, a slug typo between `app.ts` and the bundle — and it
+    // is one nobody can diagnose from a spinner.
+    //
+    // Read during render, not through a second store: a refusal calls the same `notify` a
+    // registration does, so `version` above is already the subscription that brings this
+    // component back when one is recorded.
+    const refused = panelRefusal(slug);
+    return (
+      <Notice>
+        {refused ??
+          (panelsSettled()
+            ? `No panel is registered for '${slug}'. Check that this deployment's panel bundle is listed in the admin's \`panels\` config and calls registerPanel({ slug: "${slug}", … }).`
+            : "Loading…")}
+      </Notice>
+    );
+  }
+
+  const props: PanelProps = { api, basePath, theme, setError };
+  // Keyed on the slug for the same reason a Block Kit page is: buzola keeps one component
+  // instance across a params-only change, and a panel's state belongs to its own screen.
+  //
+  // Wrapped, because this is someone else's component in our tree: React unmounts the whole
+  // root on an uncaught render error, so without the boundary one bad panel does not break a
+  // screen, it blanks the admin — no sidebar, and no way off the route that is failing.
+  return (
+    <PanelBoundary key={slug} slug={slug}>
+      <panel.render {...props} />
+    </PanelBoundary>
+  );
+}