@pramen/cms-editor 0.0.63 → 0.0.64

package/dist/panel-jsx-dev-runtime.js

@@ -0,0 +1,8 @@
+// GENERATED by @pramen/cms-editor's build — do not edit.
+// Resolves the bare specifier "react/jsx-dev-runtime" 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.PRAMEN_CMS_EDITOR_RUNTIME?.jsxDevRuntime;
+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 { Fragment, jsxDEV } = m;

package/dist/panel-jsx-runtime.js

@@ -0,0 +1,8 @@
+// GENERATED by @pramen/cms-editor's build — do not edit.
+// Resolves the bare specifier "react/jsx-runtime" 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.PRAMEN_CMS_EDITOR_RUNTIME?.jsxRuntime;
+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 { Fragment, jsx, jsxs } = m;

package/dist/panel-react-dom.js

@@ -0,0 +1,8 @@
+// GENERATED by @pramen/cms-editor's build — do not edit.
+// Resolves the bare specifier "react-dom" 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.PRAMEN_CMS_EDITOR_RUNTIME?.reactDom;
+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 { createPortal, flushSync, preconnect, prefetchDNS, preinit, preinitModule, preload, preloadModule, requestFormReset, unstable_batchedUpdates, useFormState, useFormStatus, version } = m;

package/dist/panel-react.js

@@ -0,0 +1,8 @@
+// GENERATED by @pramen/cms-editor's build — do not edit.
+// Resolves the bare specifier "react" 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.PRAMEN_CMS_EDITOR_RUNTIME?.react;
+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 { Activity, Children, Component, Fragment, Profiler, PureComponent, StrictMode, Suspense, act, cache, cacheSignal, captureOwnerStack, cloneElement, createContext, createElement, createRef, forwardRef, isValidElement, lazy, memo, startTransition, unstable_useCacheRefresh, use, useActionState, useCallback, useContext, useDebugValue, useDeferredValue, useEffect, useEffectEvent, useId, useImperativeHandle, useInsertionEffect, useLayoutEffect, useMemo, useOptimistic, useReducer, useRef, useState, useSyncExternalStore, useTransition, version } = m;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/cms-editor",
-  "version": "0.0.63",
+  "version": "0.0.64",
   "description": "Visual block/page editor for @pramen/cms — a standalone React SPA that talks to the CMS handlers over HTTP.",
   "license": "MIT",
   "repository": {
@@ -13,7 +13,11 @@
   "type": "module",
   "exports": {
     "./editor.js": "./dist/editor.js",
-    "./editor.css": "./dist/editor.css"
+    "./editor.css": "./dist/editor.css",
+    "./panel-react.js": "./dist/panel-react.js",
+    "./panel-react-dom.js": "./dist/panel-react-dom.js",
+    "./panel-jsx-runtime.js": "./dist/panel-jsx-runtime.js",
+    "./panel-jsx-dev-runtime.js": "./dist/panel-jsx-dev-runtime.js"
   },
   "files": [
     "dist",

package/src/app-context.tsx

@@ -29,6 +29,11 @@ declare global {
        * Rendered as plain external `<a>` links, positioned by `order` (see `NAV_ORDER`) and
        * defaulting to after the built-in tabs. */
       extraNav?: { label: string; href: string; target?: "_blank" | "_self"; order?: number }[];
+      /** Module URLs of this deployment's PANEL bundles — the project's own React screens,
+       * rendered inside the chrome at `/apps/:slug`. Imported by the editor at boot (see
+       * `main.tsx`), not by a script tag of the shell's, because the shared React they
+       * import has to be published first. */
+      panels?: string[];
       /** 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
@@ -98,9 +103,10 @@ interface AppContextValue {
   /** Collections registered on the server (from `listCollections`) — drives the nav + the
    * generic list/edit routes. Empty when the server registers none. */
   collections: CollectionMeta[];
-  /** Custom admin pages the CALLER may open (from `listAdminPages`) — Block Kit screens a
-   * project registered with `adminPage()`. They render inside the editor's own chrome, at a
-   * nav position they choose, which is the difference from an `extraNav` link.
+  /** Custom admin screens the CALLER may open (from `listAdminPages`) — Block Kit pages a
+   * project registered with `adminPage()`, and panels it registered with `adminPanel()`.
+   * They render inside the editor's own chrome, at a nav position they choose, which is the
+   * difference from an `extraNav` link.
    *
    * Filtered server-side by role, so there is no entry here the caller cannot open. An app
    * that registers none (or a server without the handler) leaves this empty; a failure is

package/src/blockkit.tsx

@@ -20,7 +20,8 @@ import { useCallback, useEffect, useState } from "react";
 import type { Api } from "./api";
 import { CONTROL } from "./fields";
 import { WRAP } from "./chrome";
-import type { AdminBlock, AdminElement, AdminInput, AdminPageResponse, JsonValue } from "./types";
+import { ADMIN_ELEMENT_TYPES } from "./types";
+import type { AdminBlock, AdminCell, AdminElement, AdminInput, AdminPageResponse, JsonValue } from "./types";
 
 
 /** Values held for the inputs of one block, keyed by `action_id`. */
@@ -138,10 +139,10 @@ export function BlockList({ blocks, values, setValue, disabled, onFire }: { bloc
   );
 }
 
-/** A stable React key for a block. `form` carries a required `block_id`; `actions` may.
- * Prefixed so a block_id can never collide with a bare index from a sibling. */
+/** A stable React key for a block. `form` carries a required `block_id`; `actions` and
+ * `table` may. Prefixed so a block_id can never collide with a bare index from a sibling. */
 function blockKey(block: AdminBlock, i: number): string {
-  const id = block.type === "form" ? block.block_id : block.type === "actions" ? block.block_id : undefined;
+  const id = block.type === "form" || block.type === "actions" || block.type === "table" ? block.block_id : undefined;
   return id ? `id:${id}` : `${block.type}:${i}`;
 }
 
@@ -188,7 +189,10 @@ function BlockView({ block, values, setValue, disabled, onFire }: { block: Admin
         </div>
       );
     case "table":
-      return <TableBlock block={block} />;
+      // The only interactive-capable block that used NOT to get the value bag. A row could
+      // show that a venue is hidden and could not offer the switch, so a list of 800 rows
+      // had to be written as 800 `actions` blocks — a table with the table taken out.
+      return <TableBlock block={block} values={values} setValue={setValue} disabled={disabled} onFire={onFire} />;
     case "image":
       return (
         <figure className="m-0">
@@ -222,7 +226,7 @@ function BlockView({ block, values, setValue, disabled, onFire }: { block: Admin
   }
 }
 
-function TableBlock({ block }: { block: Extract<AdminBlock, { type: "table" }> }) {
+function TableBlock({ block, values, setValue, disabled, onFire }: { block: Extract<AdminBlock, { type: "table" }>; disabled: boolean; onFire: (f: Fired) => void } & ValueBag) {
   if (block.rows.length === 0) return <p className="text-sm text-fg-subtle">{block.empty ?? "Nothing here."}</p>;
   return (
     // Wide tables scroll INSIDE their own container; the page must not scroll sideways.
@@ -239,7 +243,9 @@ function TableBlock({ block }: { block: Extract<AdminBlock, { type: "table" }> }
           {block.rows.map((row, i) => (
             <tr key={i}>
               {block.columns.map((c) => (
-                <td key={c.key} className="border-b border-border px-3 py-2 text-fg">{cell(row[c.key])}</td>
+                <td key={c.key} className="border-b border-border px-3 py-2 text-fg">
+                  <CellView value={row[c.key]} blockId={block.block_id} values={values} setValue={setValue} disabled={disabled} onFire={onFire} />
+                </td>
               ))}
             </tr>
           ))}
@@ -249,9 +255,31 @@ function TableBlock({ block }: { block: Extract<AdminBlock, { type: "table" }> }
   );
 }
 
-function cell(v: string | number | boolean | null | undefined): string {
+/** One cell: a value to read, or a control to act with.
+ *
+ * A cell's element is the SAME `ElementView` an `actions` block renders, on the same page
+ * value bag and the same `onFire` — a row's button is not a special kind of button, it is a
+ * button that happens to sit in a row. What identifies the row is the button's `value`,
+ * which is the idiom that already existed ("one `action_id` can serve a row"); an input in a
+ * cell has to carry a per-row `action_id` instead, since the bag is keyed by it, and the
+ * server refuses a response where two of them collide. */
+function CellView({ value, blockId, values, setValue, disabled, onFire }: { value: AdminCell | undefined; blockId?: string; disabled: boolean; onFire: (f: Fired) => void } & ValueBag) {
+  if (isElementCell(value)) return <ElementView el={value} blockId={blockId} compact values={values} setValue={setValue} disabled={disabled} onFire={onFire} />;
+  return <>{cell(value)}</>;
+}
+
+/** A cell is a value or an element, told apart by shape — the same discrimination the server
+ * enforces on the way out, so nothing else can be an object by the time it gets here. */
+function isElementCell(v: AdminCell | undefined): v is AdminElement {
+  return v !== null && typeof v === "object" && (ADMIN_ELEMENT_TYPES as readonly string[]).includes(v.type);
+}
+
+function cell(v: AdminCell | undefined): string {
   if (v === null || v === undefined) return "";
   if (typeof v === "boolean") return v ? "yes" : "no";
+  // An object that is not an element cannot reach a browser through a checked response; if
+  // one does, it is named rather than stringified into `[object Object]`.
+  if (typeof v === "object") return `[unsupported cell: ${String(v.type)}]`;
   return String(v);
 }
 
@@ -260,28 +288,46 @@ function ActionsBlock({ block, values, setValue, disabled, onFire }: { block: Ex
   // `onFire` attaches the whole bag, so a filter in this block reaches a button in another.
   return (
     <div className="flex flex-wrap items-end gap-3">
-      {block.elements.map((el, i) =>
-        el.type === "button" ? (
-          <Button
-            key={i}
-            variant={el.style === "primary" ? "primary" : el.style === "danger" ? "ghost" : "secondary"}
-            className={el.style === "danger" ? "text-danger" : undefined}
-            isDisabled={disabled}
-            onPress={() => {
-              if (el.confirm && !confirm(el.confirm)) return;
-              onFire({ type: "block_action", action_id: el.action_id, block_id: block.block_id, value: el.value ?? null });
-            }}
-          >
-            {el.label}
-          </Button>
-        ) : (
-          <InputView key={el.action_id} input={el} value={values[el.action_id]} onChange={(v) => setValue(el.action_id, v)} disabled={disabled} />
-        ),
-      )}
+      {block.elements.map((el, i) => (
+        <ElementView key={el.type === "button" ? `b:${i}` : `i:${el.action_id}`} el={el} blockId={block.block_id} values={values} setValue={setValue} disabled={disabled} onFire={onFire} />
+      ))}
     </div>
   );
 }
 
+/**
+ * One element — a button that fires, or an input bound to the page's value bag.
+ *
+ * Shared by `actions` and by a table cell so that the two cannot drift: a row's control has
+ * to reach the handler with exactly what a toolbar control reaches it with, or "the button
+ * in the row" becomes a second, weaker kind of button.
+ *
+ * `compact` is a rendering decision, not vocabulary: a control inside a data row is not a
+ * toolbar call-to-action, and 800 pill buttons at CTA size make a table unreadable. The
+ * server says what the control IS; the host decides how big it draws.
+ */
+function ElementView({ el, blockId, compact, values, setValue, disabled, onFire }: { el: AdminElement; blockId?: string; compact?: boolean; disabled: boolean; onFire: (f: Fired) => void } & ValueBag) {
+  if (el.type === "button") {
+    return (
+      <Button
+        size={compact ? "sm" : undefined}
+        variant={el.style === "primary" ? "primary" : el.style === "danger" ? "ghost" : "secondary"}
+        className={el.style === "danger" ? "text-danger" : undefined}
+        isDisabled={disabled}
+        onPress={() => {
+          if (el.confirm && !confirm(el.confirm)) return;
+          // `value` is what identifies the ROW: one `action_id` serves every row of a table,
+          // and the value says which one it was.
+          onFire({ type: "block_action", action_id: el.action_id, block_id: blockId, value: el.value ?? null });
+        }}
+      >
+        {el.label}
+      </Button>
+    );
+  }
+  return <InputView input={el} value={values[el.action_id]} onChange={(v) => setValue(el.action_id, v)} disabled={disabled} />;
+}
+
 function FormBlock({ block, values, setValue, disabled, onFire }: { block: Extract<AdminBlock, { type: "form" }>; disabled: boolean; onFire: (f: Fired) => void } & ValueBag) {
   // No local state: the page owns the bag and re-seeds it from every response, so a form
   // cannot keep values the server has since replaced. (The `block_id` key in `BlockList` is
@@ -313,20 +359,27 @@ function FormBlock({ block, values, setValue, disabled, onFire }: { block: Extra
 
 const isInput = (el: AdminElement): el is AdminInput => el.type !== "button";
 
-/** Every input on a page, in declaration order, including those nested in `columns` and
- * `accordion`. The page seeds its whole value bag from this on every response. */
+/** Every input on a page, in declaration order, including those in table cells and those
+ * nested in `columns` and `accordion`. The page seeds its whole value bag from this on every
+ * response — an input the walk misses renders empty however good its `initial_value` was,
+ * and then submits that emptiness. */
 function collectInputs(blocks: readonly AdminBlock[], out: AdminInput[] = []): AdminInput[] {
   for (const b of blocks) {
     if (b.type === "form") out.push(...b.fields);
     else if (b.type === "actions") out.push(...b.elements.filter(isInput));
+    // Only cells a COLUMN names, because only those are rendered — the same set the server
+    // checks for colliding `action_id`s, so the two halves agree on what is on the page.
+    else if (b.type === "table") for (const row of b.rows) for (const c of b.columns) { const v = row[c.key]; if (isElementCell(v) && isInput(v)) out.push(v); }
     else if (b.type === "columns") for (const col of b.columns) collectInputs(col, out);
     else if (b.type === "accordion") collectInputs(b.blocks, out);
   }
   return out;
 }
 
-/** The page's value bag as a fresh response describes it. */
-function seedValues(blocks: readonly AdminBlock[]): BlockValues {
+/** The page's value bag as a fresh response describes it. Exported for the test that holds
+ * the seeding contract: it is a pure function of one response, and a table cell's input is
+ * only reachable through it. */
+export function seedValues(blocks: readonly AdminBlock[]): BlockValues {
   return initialValues(collectInputs(blocks));
 }
 
@@ -353,11 +406,31 @@ function InputView({ input, value, onChange, disabled }: { input: AdminInput; va
     </span>
   ) : null;
 
+  /**
+   * The server's verdict on THIS field, under the field it is about.
+   *
+   * The page-level `toast` was the only failure surface there was, and it is the wrong one
+   * for "25:00 is not a time" or "the end is before the start": it names no field, it is
+   * gone in three seconds, and it floats at the top of a form whose sixth input is the
+   * problem. It cannot be worked around from the page either — `form` renders a flat list of
+   * inputs, so a page cannot interleave a `context` block to put the message where it
+   * belongs.
+   *
+   * It is drawn from the response, not from state: the whole page re-renders on every
+   * interaction, so the error is exactly as old as the values beside it and there is nothing
+   * to invalidate. `role="alert"` because it appears in answer to something the user just
+   * did, so a screen reader has to be told without being asked.
+   */
+  const error = input.error ? (
+    <span role="alert" className="text-caption text-danger">{input.error}</span>
+  ) : null;
+
   if (input.type === "toggle") {
     return (
       <label className="flex items-center gap-2">
-        <input type="checkbox" checked={value === true} disabled={disabled} onChange={(e) => onChange(e.target.checked)} />
+        <input type="checkbox" checked={value === true} disabled={disabled} aria-invalid={input.error ? true : undefined} onChange={(e) => onChange(e.target.checked)} />
         <span className="text-sm text-fg">{input.label ?? input.action_id}</span>
+        {error}
       </label>
     );
   }
@@ -366,7 +439,7 @@ function InputView({ input, value, onChange, disabled }: { input: AdminInput; va
     <label className="flex min-w-[180px] flex-col gap-1.5">
       {label}
       {input.type === "select" ? (
-        <select className={CONTROL} value={typeof value === "string" ? value : ""} disabled={disabled} aria-label={input.label ?? input.action_id} onChange={(e) => onChange(e.target.value)}>
+        <select className={CONTROL} value={typeof value === "string" ? value : ""} disabled={disabled} aria-invalid={input.error ? true : undefined} aria-label={input.label ?? input.action_id} onChange={(e) => onChange(e.target.value)}>
           <option value="">—</option>
           {input.options.map((o) => <option key={o.value} value={o.value}>{o.label}</option>)}
         </select>
@@ -378,6 +451,7 @@ function InputView({ input, value, onChange, disabled }: { input: AdminInput; va
           max={input.max}
           placeholder={input.placeholder}
           disabled={disabled}
+          aria-invalid={input.error ? true : undefined}
           aria-label={input.label ?? input.action_id}
           value={typeof value === "number" ? String(value) : ""}
           onChange={(e) => onChange(e.target.value === "" ? null : Number(e.target.value))}
@@ -387,6 +461,7 @@ function InputView({ input, value, onChange, disabled }: { input: AdminInput; va
           className={`${CONTROL} h-auto min-h-24 py-2.5`}
           placeholder={input.placeholder}
           disabled={disabled}
+          aria-invalid={input.error ? true : undefined}
           aria-label={input.label ?? input.action_id}
           value={typeof value === "string" ? value : ""}
           onChange={(e) => onChange(e.target.value)}
@@ -400,11 +475,13 @@ function InputView({ input, value, onChange, disabled }: { input: AdminInput; va
           autoComplete={input.type === "secret_input" ? "new-password" : undefined}
           placeholder={input.placeholder}
           disabled={disabled}
+          aria-invalid={input.error ? true : undefined}
           aria-label={input.label ?? input.action_id}
           value={typeof value === "string" ? value : ""}
           onChange={(e) => onChange(e.target.value)}
         />
       )}
+      {error}
     </label>
   );
 }

package/src/main.tsx

@@ -5,6 +5,9 @@ import { pageRegistry, routes } from "virtual:buzola/routes";
 import { AppProvider } from "./app-context";
 import { DOCUMENT_TITLE } from "./brand";
 import { isWithinBasePath, readBasePath, scopeToBasePath } from "./mount";
+import { publishPanelRuntime, type PanelRuntimeHost } from "./panel-runtime";
+import { loadPanelBundles, readPanelUrls, type PanelHost } from "./panels";
+import { initTheme } from "./theme";
 
 // 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
@@ -19,6 +22,21 @@ import { isWithinBasePath, readBasePath, scopeToBasePath } from "./mount";
 // tab, and `suffix: null` ("just our name") could never drop it.
 document.title = DOCUMENT_TITLE;
 
+// Before the first paint, so an editor left in dark mode does not flash white on every load
+// — which is what an effect inside the root layout could never avoid.
+initTheme();
+
+// The shared React, published FIRST: a panel bundle's very first `import "react"` resolves
+// through the shell's import map to a shim that reads this back out, so the global has to
+// exist before any bundle is imported. See `panel-runtime.ts`.
+publishPanelRuntime(globalThis as PanelRuntimeHost);
+
+// …then the bundles themselves, NOT awaited. Every other fact the chrome is built from
+// arrives a round trip late too (`listAdminPages` is what puts a panel in the nav at all),
+// and awaiting a third-party fetch here would mean one hanging request is a blank admin.
+// A panel's route re-reads the registry as registrations land — see `panels.ts`.
+void loadPanelBundles(readPanelUrls(globalThis as PanelHost, typeof location === "undefined" ? "" : location.href));
+
 const el = document.getElementById("app");
 const basePath = readBasePath(el);
 

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;
+`;
+}