@pramen/cms-editor 0.0.61 → 0.0.64

package/src/nav.ts

@@ -31,6 +31,41 @@ export interface ExtraNavLink {
   order?: number;
 }
 
+/** The glyphs the sidebar can draw, by NAME.
+ *
+ * A name, not a component: this module is a pure function of the session's facts and is
+ * tested without a DOM, so it must not import JSX. `NAV_GLYPHS` in `icons.tsx` maps each
+ * name to the drawing, and because this is a closed union a glyph added here without a
+ * drawing is a compile error rather than a blank square in the nav. */
+export type NavGlyph =
+  | "pages"
+  | "collection"
+  | "media"
+  | "menus"
+  | "taxonomies"
+  | "widgets"
+  | "redirects"
+  | "app"
+  | "types"
+  | "users"
+  | "settings"
+  | "link";
+
+/** What sits in an entry's icon slot.
+ *
+ * Two cases because a collection and a Block Kit page may declare their OWN icon
+ * server-side, and that is an arbitrary string (an emoji, in practice). It used to be
+ * prepended to the label — which read as part of the words, wrapped with them, and could
+ * not be aligned with anything. In a sidebar the icon is a column, so a declared emoji goes
+ * in that column and the built-in glyph is the fallback. */
+export type NavIcon = { kind: "glyph"; name: NavGlyph } | { kind: "emoji"; char: string };
+
+/** A server-declared icon if there is one, else the section's own glyph. */
+function iconFor(declared: string | undefined, fallback: NavGlyph): NavIcon {
+  const char = declared?.trim();
+  return char ? { kind: "emoji", char } : { kind: "glyph", name: fallback };
+}
+
 /** One entry in the primary nav.
  *
  * `kind` is what the layout switches on to render it; everything else here is the data it
@@ -38,8 +73,8 @@ export interface ExtraNavLink {
  * buzola page, and the layout is where navigation (and the unsaved-changes guard it runs
  * through) belongs. */
 export type NavEntry =
-  | { kind: "route"; key: string; order: number; label: string; page: NavPage; params?: Record<string, string> }
-  | { kind: "link"; key: string; order: number; link: ExtraNavLink };
+  | { kind: "route"; key: string; order: number; icon: NavIcon; label: string; page: NavPage; params?: Record<string, string> }
+  | { kind: "link"; key: string; order: number; icon: NavIcon; link: ExtraNavLink };
 
 /** What the nav is built from. All of it is already in the app context; passing it in keeps
  * this a pure function of the session's facts. */
@@ -76,10 +111,10 @@ export function buildNav(input: NavInput): NavEntry[] {
       // slug. The label is the type's own `name`, so a host that wants a plural tab writes
       // one.
       for (const t of contentTypes ?? []) {
-        entries.push({ kind: "route", key: `type:${t.slug}`, order: NAV_ORDER.pages, label: t.name, page: "type", params: { slug: t.slug } });
+        entries.push({ kind: "route", key: `type:${t.slug}`, order: NAV_ORDER.pages, icon: { kind: "glyph", name: "pages" }, label: t.name, page: "type", params: { slug: t.slug } });
       }
     } else {
-      entries.push({ kind: "route", key: "pages", order: NAV_ORDER.pages, label: "Pages", page: "home" });
+      entries.push({ kind: "route", key: "pages", order: NAV_ORDER.pages, icon: { kind: "glyph", name: "pages" }, label: "Pages", page: "home" });
     }
   }
 
@@ -88,22 +123,23 @@ export function buildNav(input: NavInput): NavEntry[] {
       kind: "route",
       key: `col:${c.slug}`,
       order: c.navOrder ?? NAV_ORDER.collections,
-      label: `${c.icon ? `${c.icon} ` : ""}${c.pluralLabel}`,
+      icon: iconFor(c.icon, "collection"),
+      label: c.pluralLabel,
       page: "collection",
       params: { slug: c.slug },
     });
   }
 
-  entries.push({ kind: "route", key: "media", order: NAV_ORDER.media, label: "Media", page: "media" });
+  entries.push({ kind: "route", key: "media", order: NAV_ORDER.media, icon: { kind: "glyph", name: "media" }, label: "Media", page: "media" });
 
   if (cms.siteFurniture) {
-    entries.push({ kind: "route", key: "menus", order: NAV_ORDER.menus, label: "Menus", page: "menus" });
+    entries.push({ kind: "route", key: "menus", order: NAV_ORDER.menus, icon: { kind: "glyph", name: "menus" }, label: "Menus", page: "menus" });
     // Taxonomies classify PAGES — `cms_page_terms` links a term to a page and to nothing
     // else — so a collections-only deployment has nothing to classify and the section would
     // be a vocabulary editor with no subject.
-    if (!hidePages) entries.push({ kind: "route", key: "taxonomies", order: NAV_ORDER.taxonomies, label: "Taxonomies", page: "taxonomies" });
-    entries.push({ kind: "route", key: "widgets", order: NAV_ORDER.widgets, label: "Widgets", page: "widgets" });
-    entries.push({ kind: "route", key: "redirects", order: NAV_ORDER.redirects, label: "Redirects", page: "redirects" });
+    if (!hidePages) entries.push({ kind: "route", key: "taxonomies", order: NAV_ORDER.taxonomies, icon: { kind: "glyph", name: "taxonomies" }, label: "Taxonomies", page: "taxonomies" });
+    entries.push({ kind: "route", key: "widgets", order: NAV_ORDER.widgets, icon: { kind: "glyph", name: "widgets" }, label: "Widgets", page: "widgets" });
+    entries.push({ kind: "route", key: "redirects", order: NAV_ORDER.redirects, icon: { kind: "glyph", name: "redirects" }, label: "Redirects", page: "redirects" });
   }
 
   // A project's own screens, INSIDE the chrome and at a position they choose. This is the
@@ -111,24 +147,122 @@ export function buildNav(input: NavInput): NavEntry[] {
   // the odd 10% of a client site was a separate deployment that looked nothing like the
   // admin it hung off.
   for (const p of adminPages) {
-    entries.push({ kind: "route", key: `app:${p.slug}`, order: p.navOrder ?? NAV_ORDER.adminPages, label: `${p.icon ? `${p.icon} ` : ""}${p.label}`, page: "admin-page", params: { slug: p.slug } });
+    entries.push({ kind: "route", key: `app:${p.slug}`, order: p.navOrder ?? NAV_ORDER.adminPages, icon: iconFor(p.icon, "app"), label: p.label, page: "admin-page", params: { slug: p.slug } });
   }
 
   // Authoring the SCHEMA, not content — so it is gated on `canEdit` (every handler behind
   // it is editor-only) and hidden where there is no block/page builder to define types for.
   if (!hidePages && cms.canEdit) {
-    entries.push({ kind: "route", key: "types", order: NAV_ORDER.types, label: "Types", page: "schema" });
+    entries.push({ kind: "route", key: "types", order: NAV_ORDER.types, icon: { kind: "glyph", name: "types" }, label: "Types", page: "schema" });
   }
 
-  if (isAdmin) entries.push({ kind: "route", key: "users", order: NAV_ORDER.users, label: "Users", page: "users" });
-  entries.push({ kind: "route", key: "settings", order: NAV_ORDER.settings, label: "Settings", page: "settings" });
+  if (isAdmin) entries.push({ kind: "route", key: "users", order: NAV_ORDER.users, icon: { kind: "glyph", name: "users" }, label: "Users", page: "users" });
+  entries.push({ kind: "route", key: "settings", order: NAV_ORDER.settings, icon: { kind: "glyph", name: "settings" }, label: "Settings", page: "settings" });
 
   for (const link of extraNav) {
     // Keyed on href AND label: two entries may legitimately point at the same href and
     // differ only in label or target, and keyed on href alone React reconciles them
     // together — the rendered label can end up on the other one's anchor.
-    entries.push({ kind: "link", key: `extra:${link.href}|${link.label}`, order: link.order ?? NAV_ORDER.extra, link });
+    entries.push({ kind: "link", key: `extra:${link.href}|${link.label}`, order: link.order ?? NAV_ORDER.extra, icon: { kind: "glyph", name: "link" }, link });
   }
 
   return entries.sort((a, b) => a.order - b.order);
 }
+
+// --- sections ---------------------------------------------------------------------------
+//
+// Twelve items in one flat list is the thing that stopped being legible — it overran the
+// topbar, and a sidebar alone only turns a crowded row into a long column. So the nav is
+// GROUPED. Grouping rather than hiding: everything a session may reach stays one click away
+// (a submenu costs a click and hides the thing being looked for), and the headings answer
+// "where would I look for this" instead of making the reader scan twelve equal rows.
+//
+// A section is a BAND OF `order`, not a hand-written list of keys. That keeps the one
+// contract this module has — position is a number a host sets (`navOrder` on a collection
+// or an admin page, `order` on an `extraNav` link) — the single thing that decides where an
+// entry appears. A host placing a section at 250 lands in Content, at 450 in Site, exactly
+// as the number reads. Enumerating keys instead would have made a host-placed entry land
+// visually inside a group it was not a member of.
+
+/** A group of nav entries, in order. */
+export type NavSectionId = "content" | "site" | "apps" | "system";
+
+export interface NavSection {
+  id: NavSectionId;
+  /** The heading. Rendered only when there is more than one section — see `navSections`. */
+  label: string;
+  entries: NavEntry[];
+}
+
+/** The bands, in order. `upTo` is EXCLUSIVE, and each is expressed against `NAV_ORDER`
+ * rather than a literal so the two cannot drift: a built-in moving to a new position moves
+ * with its band. */
+const BANDS: readonly { id: NavSectionId; label: string; upTo: number }[] = [
+  // Pages / content types, collections, media — the things an editor came here to write.
+  { id: "content", label: "Content", upTo: NAV_ORDER.menus },
+  // Menus, taxonomies, widget areas, redirects — site-level furniture, not page content.
+  { id: "site", label: "Site", upTo: NAV_ORDER.adminPages },
+  // A project's own Block Kit screens. Their own band rather than a tail of "System",
+  // because they are the project's, and the whole point of `adminPage()` is that they are
+  // not administration of the CMS.
+  { id: "apps", label: "Apps", upTo: NAV_ORDER.types },
+  // Types, users, settings, and host links to companion tools.
+  { id: "system", label: "System", upTo: Number.POSITIVE_INFINITY },
+];
+
+/** Every section id, in rail order. Derived from `BANDS` rather than written out again, so
+ * a new group cannot exist in the layout's eyes but not in the reader's stored folds (or the
+ * reverse). It is what makes a persisted fold PARSEABLE: a value read back out of
+ * localStorage is checked against this, so a stale id from an older version — or anything a
+ * hand-edit put there — is dropped rather than carried into state as "some string". */
+export const NAV_SECTION_IDS: readonly NavSectionId[] = BANDS.map((b) => b.id);
+
+/**
+ * Group the entries `buildNav` returned, dropping empty sections.
+ *
+ * Takes the already-ordered list rather than re-deriving it: the order IS the grouping, so
+ * a second traversal that could disagree with the first would be a bug waiting to happen.
+ * Entries stay in the order they came in, which is what carries the sub-orderings that have
+ * no numeric expression (content-type tabs among themselves, collections sharing a
+ * `navOrder`).
+ */
+export function navSections(entries: NavEntry[]): NavSection[] {
+  const sections: NavSection[] = BANDS.map((b) => ({ id: b.id, label: b.label, entries: [] }));
+  for (const entry of entries) {
+    // The last band is unbounded, so `find` always hits; the `??` is for the type checker.
+    const i = BANDS.findIndex((b) => entry.order < b.upTo);
+    (sections[i === -1 ? sections.length - 1 : i] as NavSection).entries.push(entry);
+  }
+  return sections.filter((s) => s.entries.length > 0);
+}
+
+/**
+ * Should the sections be LABELLED?
+ *
+ * A single heading over the whole nav names nothing — it is a caption on a list with no
+ * sibling to distinguish it from — and a collections-only deployment (`hidePages`, no site
+ * furniture) genuinely is one group. So the headings appear once there are at least two,
+ * and the small deployment keeps a plain list.
+ */
+export function navSectionsAreLabelled(sections: NavSection[]): boolean {
+  return sections.length > 1;
+}
+
+/**
+ * Is the rail ACTUALLY narrowed?
+ *
+ * A named function for `choice && wide`, because conflating those two is what broke it. The
+ * choice is per-browser and persisted; narrowing is expressed entirely in `md:`-scoped
+ * classes, so it only exists at desktop widths. A rail narrowed on a laptop therefore came
+ * back "narrowed" on a phone, where every one of those classes is inert — the rows kept their
+ * labels and their full width, while the JS gated on the stored choice removed all four group
+ * headings, and the hairline that stands in for a heading at 56px is `md:`-only too. One
+ * undifferentiated column of a dozen rows, and the toggle that would undo it is
+ * `hidden md:inline-flex`: no way back from that viewport.
+ *
+ * So JS has to agree with the breakpoint rather than ignore it, and everything conditional —
+ * headings, folding, the hairline — reads this instead of the stored value.
+ */
+export function railIsNarrow(choice: boolean, wideViewport: boolean): boolean {
+  return choice && wideViewport;
+}

package/src/page-header.tsx

@@ -0,0 +1,128 @@
+// The screen header: a cover panel carrying the title and the primary action, which STAYS as
+// the page scrolls.
+//
+// A LEAF module, and it has to be one. `components.tsx` already imports from `furniture.tsx`
+// (for `flattenTerms`), so the two near-identical headers that used to live one in each — a
+// 56px `Hero` and a 40px `Head` — could not be deduplicated by either importing the other
+// without a cycle. Below both, they are one component.
+//
+// ONE type scale, and no `size` prop. The 40px variant was inherited from `Head`: the
+// site-furniture screens (Menus, Taxonomies, Widgets, Redirects) had always been set quieter
+// than the libraries, back when a header was type on the page and the difference read as
+// hierarchy. It does not survive the cover: every screen now gets the same panel with the same
+// generated artwork, so a smaller title on four of them reads as an oversight rather than a
+// rank, and "Navigation" at 40px beside "Media" at 56px is a question a reader has to stop and
+// ask.
+//
+// STICKY, and condensing. The header is the only thing on screen that says which of a dozen
+// interchangeable list screens you are on, and scrolling a media library past the first row
+// used to take it away — leaving a wall of thumbnails with no title and no primary action.
+// Sticky alone would be worse than that: a 190px banner pinned to the top eats a third of the
+// viewport on every scroll. So it condenses — same panel, same artwork, same button, a third
+// of the height — which is the only version of "keep it" that a long list can afford.
+
+import { useEffect, useState, type ReactNode } from "react";
+import { BELOW_APP_BAR } from "./chrome";
+import { CoverArt } from "./cover";
+
+/** TWO thresholds, not one — this is hysteresis, and without it the header flickers.
+ *
+ * Condensing REMOVES about 90px of header, which shortens the document by the same amount. If
+ * the reader is anywhere the browser then has to clamp the scroll offset, `scrollY` moves on
+ * its own — back under a single threshold, which expands the header, which lengthens the
+ * document, which moves `scrollY` again. The state is an input to its own condition, so one
+ * threshold is a feedback loop by construction and no amount of debouncing fixes it: the
+ * oscillation is in the layout, not in the event rate.
+ *
+ * The gap has to exceed the height the switch removes, or the loop simply reappears further
+ * down. `EXPAND_BELOW` is deliberately small so that returning to the top always restores the
+ * full header.
+ */
+const CONDENSE_ABOVE_PX = 120;
+const EXPAND_BELOW_PX = 16;
+
+/**
+ * Has the page scrolled far enough to condense the header?
+ *
+ * On `window`, because the editor's shell deliberately keeps the DOCUMENT as its scroller (the
+ * rail is a sticky grid column, not an inner scroll pane) — so this is the one scroll position
+ * there is. `passive` since nothing here can cancel the scroll, and React bails out of a
+ * re-render when the value is unchanged, so a scroll inside the dead band costs a comparison.
+ */
+function useCondensed(): boolean {
+  const [condensed, setCondensed] = useState(false);
+  useEffect(() => {
+    // Reads the CURRENT value rather than closing over it, so the listener is registered once
+    // and the dead band is evaluated against what is actually on screen.
+    const onScroll = (): void =>
+      setCondensed((was) => (was ? window.scrollY > EXPAND_BELOW_PX : window.scrollY > CONDENSE_ABOVE_PX));
+    onScroll(); // a deep link can land already scrolled (browser scroll restoration)
+    window.addEventListener("scroll", onScroll, { passive: true });
+    return () => window.removeEventListener("scroll", onScroll);
+  }, []);
+  return condensed;
+}
+
+/**
+ * The header.
+ *
+ * Seeded on `lead`, NOT on `em`. `lead` is the screen's name ("Media", a collection's plural
+ * label) and `em` is its state ("None yet", "3 files") — seeding on what is displayed would
+ * redraw the artwork every time someone uploaded a file, which is the one thing a picture
+ * meant to make a screen RECOGNISABLE must never do.
+ *
+ * The mask over the art is a hard requirement, not polish: the title is large and set left, and
+ * `from-surface-card` fading to transparent is what guarantees it never lands on pattern
+ * whatever the seed produced. The `via` stop is the whole tuning knob — at `/85` the middle of
+ * the panel is still 85% panel colour and the artwork only ever appears in the last third,
+ * which is a cover you cannot see; `/70` clears the type (which ends around 26% of the width)
+ * and lets the field read across the rest.
+ */
+export function PageHeader({ lead, em, children }: { lead: string; em: string; children?: ReactNode }) {
+  const condensed = useCondensed();
+  return (
+    // The GUTTER is what sticks, not the panel: pinning the panel alone would let rows scroll
+    // through the 28px of page margin either side of it and out the rounded corners. `bg-surface`
+    // on this wrapper is therefore load-bearing, not decoration.
+    //
+    // NO padding above: the panel meets the app bar directly, so the two read as one block of
+    // chrome rather than a bar with a panel parked under it. That also leaves nothing on this
+    // wrapper that changes between the two states, which is why the collapse transition lives
+    // only on the panel below — a transition on an element whose padding is constant is dead
+    // code that looks load-bearing.
+    //
+    // `z-20` sits above the list and below the rail's mobile disclosure (which is in flow above
+    // it) and every modal overlay (z-50).
+    <div className={`sticky ${BELOW_APP_BAR} z-20 mx-auto max-w-[1200px] bg-surface px-7 pb-4`}>
+      <div className="relative isolate overflow-hidden rounded-panel border border-border bg-surface-card">
+        <CoverArt seed={lead} />
+        <div className="absolute inset-0 bg-gradient-to-r from-surface-card via-surface-card/70 to-transparent" />
+        <div
+          className={`relative grid grid-cols-[1fr_auto] items-center gap-6 px-8 transition-[padding] duration-150 ease-out max-[820px]:grid-cols-1 ${
+            condensed ? "py-3.5" : "py-9"
+          }`}
+        >
+          {/* Condensed, the two halves run on ONE line. Stacked they would keep the full
+              header's height and defeat the point; and the title has to stay a single `<h1>`
+              across the switch, or a screen reader is handed a new heading every time the
+              reader scrolls. */}
+          <h1
+            // NO transition on the type. `transition-all` here animated `font-size` 56px -> 22px,
+            // which relayouts the panel on every frame of the tween — on a STICKY element whose
+            // height feeds back into the scroll position, which is the other half of the flicker.
+            // And `display` (two stacked lines -> one baseline row) cannot be tweened at all, so
+            // the line count snapped mid-animation regardless. The type switches at once; the
+            // padding below carries the motion.
+            className={`m-0 font-normal tracking-[-0.01em] ${
+              condensed ? "flex items-baseline gap-2 text-[22px] leading-tight" : "text-[56px] leading-[1.05] max-[820px]:text-[40px]"
+            }`}
+          >
+            <span className={condensed ? "text-fg-subtle" : "block text-fg-subtle"}>{lead}</span>
+            <span className={condensed ? "text-fg" : "block text-fg"}>{em}</span>
+          </h1>
+          {children}
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/panel-boundary.tsx

@@ -0,0 +1,67 @@
+// The blast radius of a panel.
+//
+// A panel is a project's own component rendering inside THIS app's React tree, which is the
+// whole point of it — and the cost of that is that a throw in its render is a throw in ours.
+// React's answer to an uncaught render error is to unmount the entire root, so without a
+// boundary one bad panel does not break a screen, it blanks the admin: no sidebar, no way to
+// navigate off the route that is failing, and a reload lands straight back on it because the
+// URL is a real route.
+//
+// So the panel route wraps it. The chrome survives, the reader is told which panel failed and
+// with what, and every other section stays one click away.
+//
+// A CLASS, because `componentDidCatch`/`getDerivedStateFromError` have no hook equivalent —
+// there is still no way to catch a render error from a function component. Its own module so
+// the decision is testable without dragging in the router and the design system.
+
+import { Component, type ErrorInfo, type ReactNode } from "react";
+
+interface Props {
+  /** Named in the message — a deployment with three panels needs to know which one. */
+  slug: string;
+  children: ReactNode;
+}
+
+interface State {
+  /** The failure's message, or `null` while the panel is fine. */
+  failure: string | null;
+}
+
+/** What a caught error reads as. A named function because it is the one piece of judgement
+ * here: an error with no message (a thrown string, a thrown object) must still produce
+ * something a reader can act on, and `String(undefined)` is not it. */
+export function panelFailureMessage(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.trim() === "" ? "threw a value with no message" : message;
+}
+
+export class PanelBoundary extends Component<Props, State> {
+  override state: State = { failure: null };
+
+  static getDerivedStateFromError(error: unknown): State {
+    return { failure: panelFailureMessage(error) };
+  }
+
+  override componentDidCatch(error: unknown, info: ErrorInfo): void {
+    // The rendered message names the panel and the error; the console gets the component
+    // stack, which is the half a developer needs and a reader cannot use.
+    console.error(`pramen/cms-editor: panel '${this.props.slug}' failed to render`, error, info.componentStack);
+  }
+
+  override componentDidUpdate(prev: Props): void {
+    // Navigating to a different panel must clear the failure — the route keys on the slug so
+    // this rarely fires, but a boundary that latched would turn one panel's bug into every
+    // panel's bug for the rest of the session.
+    if (prev.slug !== this.props.slug && this.state.failure !== null) this.setState({ failure: null });
+  }
+
+  override render(): ReactNode {
+    if (this.state.failure === null) return this.props.children;
+    return (
+      <div role="alert" className="rounded-panel border border-border bg-surface-card px-6 py-5 text-sm text-fg-muted">
+        <p className="mb-1 text-fg">The <strong>{this.props.slug}</strong> panel failed to render.</p>
+        <p className="font-mono text-caption">{this.state.failure}</p>
+      </div>
+    );
+  }
+}

package/src/panel-globals.ts

@@ -0,0 +1,103 @@
+// The three shim modules a PANEL bundle's bare imports resolve to.
+//
+// A panel is a project's own React screen, built as a separate bundle and rendered inside
+// this editor's tree. It cannot contain React: two copies in one page share no hook
+// dispatcher, so the panel's first `useState` throws "invalid hook call". It must instead
+// link against the React the editor already loaded — which is published on a global by
+// `panel-runtime.ts`, and reached from a panel's ordinary `import { useState } from "react"`
+// through an import map in the shell (see `PramenAdmin.astro`) pointing at these files.
+//
+// GENERATED, not hand-written, and that is the whole reason this module exists rather than
+// three checked-in files. A shim has to re-export every name STATICALLY — ESM named exports
+// cannot be computed — so by hand the list would be a copy of React's export table that
+// nobody would ever revisit. A name missing from it is not a build error anywhere: it is a
+// browser link error ("does not provide an export named 'useDeferredValue'") in someone
+// else's panel, months later, on the one deployment that used that hook. So the list is read
+// off the very modules the editor bundles, at the moment it bundles them, and cannot drift
+// from them by construction.
+//
+// Source-side rather than inside `scripts/build.ts` so the generator is typechecked and can
+// be exercised by tests — `test/cms-editor-panel-globals.test.ts` builds a panel against the
+// generated text and renders it, which is the only way to prove the mechanism end to end
+// without a browser.
+
+/** A module namespace as this generator must treat one: an opaque bag whose NAMES are the
+ * entire subject. There is no schema to decode it against — the point is that the list comes
+ * from React rather than from anything written here — so the contract is deliberately just
+ * "an object with a possible CJS-interop `default`". */
+export interface ModuleNamespace {
+  readonly default?: ModuleNamespace;
+}
+
+/** One shim: which bare specifier it stands in for, which key on the published runtime it
+ * reads, and what it is written to. */
+export interface PanelGlobalShim {
+  /** Filename under `dist/`, and the package export a shell imports with `?url`. */
+  readonly file: string;
+  /** The bare specifier an import map points at this file. */
+  readonly specifier: string;
+  /** The property of `PRAMEN_CMS_EDITOR_RUNTIME` holding the namespace. */
+  readonly runtimeKey: "react" | "reactDom" | "jsxRuntime" | "jsxDevRuntime";
+}
+
+/** The whole set. Four, and meant to stay four — see the surface note in `panel-runtime.ts`
+ * for why each is here and what is deliberately not. */
+export const PANEL_GLOBAL_SHIMS: readonly PanelGlobalShim[] = [
+  { file: "panel-react.js", specifier: "react", runtimeKey: "react" },
+  { file: "panel-react-dom.js", specifier: "react-dom", runtimeKey: "reactDom" },
+  { file: "panel-jsx-runtime.js", specifier: "react/jsx-runtime", runtimeKey: "jsxRuntime" },
+  // The transform a panel built UNMINIFIED emits instead. Not an optional nicety: without
+  // it that specifier resolves from the consumer's own node_modules and a second React ends
+  // up in the bundle, silently, on exactly the build a developer iterates on.
+  { file: "panel-jsx-dev-runtime.js", specifier: "react/jsx-dev-runtime", runtimeKey: "jsxDevRuntime" },
+];
+
+/**
+ * The names a shim may re-export, read off a module namespace: real identifiers only.
+ *
+ * The namespace is unwrapped through `default` first, because React and its JSX runtimes are
+ * CJS: a bundler's interop puts the real `module.exports` on `default` and mirrors the named
+ * exports beside it. Enumerating the unwrapped object means the list is the one `require`
+ * would have produced, rather than one that depends on which interop the editor happened to
+ * be built with — and it is the same unwrap the generated shim performs at runtime, so the
+ * names written out are exactly the names that will be there to destructure.
+ *
+ * `default` is excluded because it is a keyword (it gets its own `export default` line), and
+ * `__`-prefixed keys because React's namespaces carry interop bookkeeping and internals
+ * (`__esModule`, `__CLIENT_INTERNALS_…`) that are nobody's API — re-exporting them would put
+ * this package's name on a promise React itself does not make.
+ *
+ * Sorted, so a rebuild against the same React produces a byte-identical file and a diff of
+ * `dist/` says something.
+ */
+export function exportableNames(ns: ModuleNamespace): string[] {
+  const real = ns.default ?? ns;
+  return Object.keys(real)
+    .filter((k) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(k) && k !== "default" && !k.startsWith("__"))
+    .sort();
+}
+
+/**
+ * The shim's source.
+ *
+ * The `?.` and the throw are not defensive noise. This is the first module a panel bundle
+ * imports, so it is the one place where "the editor did not publish its runtime" — a panel
+ * loaded outside the admin, or a shell that emitted the import map but not the editor — can
+ * be reported as itself instead of as `Cannot read properties of undefined (reading
+ * 'react')` from somewhere inside a stranger's bundle.
+ *
+ * `ns.default ?? ns` is the same CJS-interop unwrap `exportableNames` performs, and it has to
+ * be: the names written into this file were read off the unwrapped object, so the object
+ * destructured here must be that object and not the namespace around it.
+ */
+export function panelShimSource(shim: PanelGlobalShim, names: readonly string[], runtimeGlobal: string): string {
+  return `// GENERATED by @pramen/cms-editor's build — do not edit.
+// Resolves the bare specifier "${shim.specifier}" for a panel bundle, against the React the
+// editor already loaded. Wired up by the shell's import map; see docs/cms.md.
+const ns = globalThis.${runtimeGlobal}?.${shim.runtimeKey};
+if (!ns) throw new Error("pramen/cms-editor: no editor runtime on this page — a panel bundle was loaded outside the CMS editor, or before it booted.");
+const m = ns.default ?? ns;
+export default m;
+export const { ${names.join(", ")} } = m;
+`;
+}

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();
+}