@pramen/cms 0.0.63 → 0.0.64

package/dist/blockkit.d.ts

@@ -1,8 +1,16 @@
 import type { HandlerContext, JsonValue, SchemaDef } from "@pramen/server";
+import { type AdminPanelDef } from "./panel";
 /** Text with no formatting. Rendered as text, never as markup — the editor puts every
  * string through React, so there is no HTML path here to sanitize. */
 export type AdminText = string;
-/** An input a form (or an actions row) can carry. */
+/** An input a form, an actions row or a table cell can carry.
+ *
+ * `error` is the per-FIELD failure, rendered under the offending input. The page-level
+ * `toast` cannot do that job: it names no field, it is gone in three seconds while the bad
+ * value is still on screen, and a form with six inputs gives the reader no way to tell which
+ * one "25:00 is not a time" is about. It is a plain part of the render — the whole page
+ * comes back on every interaction, so an error lives exactly as long as the response that
+ * carried it, and there is nothing to clear. */
 export type AdminInput = {
     type: "text_input";
     action_id: string;
@@ -11,6 +19,7 @@ export type AdminInput = {
     initial_value?: string;
     multiline?: boolean;
     required?: boolean;
+    error?: AdminText;
 } | {
     type: "number_input";
     action_id: string;
@@ -20,6 +29,7 @@ export type AdminInput = {
     min?: number;
     max?: number;
     required?: boolean;
+    error?: AdminText;
 } | {
     type: "select";
     action_id: string;
@@ -30,11 +40,13 @@ export type AdminInput = {
     }[];
     initial_value?: string;
     required?: boolean;
+    error?: AdminText;
 } | {
     type: "toggle";
     action_id: string;
     label?: AdminText;
     initial_value?: boolean;
+    error?: AdminText;
 }
 /** Write-only: never echoed back to the browser once stored. The editor renders it as a
  * password field and sends it only on submit; a page that stores one must NOT put it back
@@ -45,6 +57,7 @@ export type AdminInput = {
     label?: AdminText;
     placeholder?: AdminText;
     required?: boolean;
+    error?: AdminText;
 };
 /** A button. `value` rides back on the interaction, so one `action_id` can serve a row. */
 export interface AdminButton {
@@ -58,6 +71,30 @@ export interface AdminButton {
     confirm?: AdminText;
 }
 export type AdminElement = AdminButton | AdminInput;
+/** Every `AdminElement` tag, as a runtime set.
+ *
+ * Both halves need this at RUNTIME, which is why it is a value and not only a union: the
+ * server checks that an object sitting in a table cell really is an element, and the editor
+ * decides from the same set whether a cell draws as text or as a control. The editor keeps
+ * its own copy (it has no dependency on this package) and `test/cms-editor-mirrors.test.ts`
+ * fails if the two drift. */
+export declare const ADMIN_ELEMENT_TYPES: readonly ["button", "text_input", "number_input", "select", "toggle", "secret_input"];
+/** What one table cell holds: a value to READ, or an element to ACT with.
+ *
+ * The alternative shape was a per-COLUMN element declaration — `columns: [{ key, label,
+ * element }]` — and it is the wrong unit. Everything about a row's control is a fact of the
+ * ROW: the button's `value` is that row's id, its label is "Hide" or "Show" depending on
+ * that row's state, and a row that must not be touched carries no control at all. A column
+ * declaration would have to be a template with a substitution language, which is a second
+ * vocabulary to design and to escape. A cell already varies per row, so the element goes in
+ * the cell and the column keeps saying only where it lands. A cell is a value OR an element,
+ * never both; a column that wants both is two columns.
+ *
+ * The two are told apart by SHAPE: a display value is a primitive, an element is an object,
+ * and nothing else may be an object. `normalizeAdminResponse` enforces that, so a page that
+ * splats a whole row (`rows: found`) into the table is named at the boundary instead of
+ * rendering a column of `[object Object]` — or, worse, of half-elements. */
+export type AdminCell = AdminText | number | boolean | null | AdminElement;
 /** One block in a rendered admin page. */
 export type AdminBlock = {
     type: "header";
@@ -81,13 +118,17 @@ export type AdminBlock = {
         label: AdminText;
         value: AdminText;
     }[];
-} | {
+}
+/** `block_id` rides back on an interaction a CELL fired, the same way an `actions` block's
+ * does — so a page with two tables can tell which one a shared `action_id` came from. */
+ | {
     type: "table";
+    block_id?: string;
     columns: {
         key: string;
         label: AdminText;
     }[];
-    rows: Record<string, AdminText | number | boolean | null>[];
+    rows: Record<string, AdminCell>[];
     empty?: AdminText;
 } | {
     type: "stats";
@@ -165,6 +206,10 @@ export declare const MAX_ADMIN_BLOCK_DEPTH = 4;
  * Without it `ctx.db.find({ from: "lectures", where: { title: { contains: q } } })` resolves
  * the table against the default `SchemaDef` and every column reads as a number. */
 export interface AdminPageDef<S extends SchemaDef = SchemaDef> {
+    /** Discriminates this from an `AdminPanelDef` in the registry the two share. Optional and
+     * defaulted, because a Block Kit page is what `adminPage()` has always produced and
+     * nothing should have to start saying so. */
+    readonly kind?: "blocks";
     /** URL + registry key: the page is served at `/apps/:slug` in the editor. */
     readonly slug: string;
     /** Nav label. */
@@ -198,19 +243,39 @@ export interface AdminPageDef<S extends SchemaDef = SchemaDef> {
  *   });
  */
 export declare function adminPage<S extends SchemaDef = SchemaDef>(slug: string, opts: Omit<AdminPageDef<S>, "slug">): AdminPageDef<S>;
-/** The client-facing view of a page — what the editor needs to put it in the nav. Never
- * the `render` function, and never the role list (which is a server fact; a page the caller
- * may not open is simply absent from the listing). */
+/** One entry in the custom-screens registry: a Block Kit page, or a panel the browser
+ * renders. They share a registry — and so a slug space, a route and a nav band — because
+ * from the editor's side they are the same thing (a project's own screen inside the chrome)
+ * differing only in where the rendering happens. Two registries would have made a slug
+ * collision between them a runtime surprise instead of a boot error. */
+export type AdminScreenDef<S extends SchemaDef = SchemaDef> = AdminPageDef<S> | AdminPanelDef;
+/** Every screen kind, as a runtime set. A value and not only a union because the editor
+ * keeps its own copy and `test/cms-editor-mirrors.test.ts` fails if the two drift — a kind
+ * the server sends and the editor has not heard of is a nav entry that renders nothing. */
+export declare const ADMIN_PAGE_KINDS: readonly ["blocks", "panel"];
+export type AdminPageKind = (typeof ADMIN_PAGE_KINDS)[number];
+/** The client-facing view of a registered screen — what the editor needs to put it in the
+ * nav and decide how to render it. Never the `render` function, and never the role list
+ * (which is a server fact; a screen the caller may not open is simply absent from the
+ * listing). */
 export interface AdminPageMeta {
     slug: string;
     label: string;
     icon?: string;
     navOrder: number;
+    /** `"blocks"` (Block Kit, rendered from this response) or `"panel"` (a component the
+     * deployment's panel bundle registered under this slug). */
+    kind: AdminPageKind;
 }
-/** Validate a registry at boot: slugs are unique and routable, and every page can be
+/** Validate a registry at boot: slugs are unique and routable, and every screen can be
  * addressed. Called by `createAdminPageHandlers`, so a mistake surfaces when the Worker
- * starts rather than as a 404 the first time someone opens the one page nobody exercised. */
-export declare function validateAdminPages(pages: readonly AdminPageDef[]): void;
+ * starts rather than as a 404 the first time someone opens the one page nobody exercised.
+ *
+ * Pages and panels are validated TOGETHER, against one `seen` set: they share `/apps/:slug`,
+ * so two entries with the same slug are a collision whatever their kinds — and the one that
+ * would win is decided by insertion order into a Map, which is not a thing to leave to
+ * chance. */
+export declare function validateAdminPages(pages: readonly AdminScreenDef[]): void;
 export interface AdminPageHandlerOpts {
     /** Default roles for a page that declares none. Pass the same `editorRoles` the rest of
      * the CMS uses, so one deployment has one answer to "who may author". */
@@ -224,10 +289,14 @@ export interface AdminPageHandlerOpts {
  * There is no ACL fragment to spread: a page reads through `ctx.db` under whatever policies
  * the caller already has, so there is nothing here to grant.
  */
-export declare function createAdminPageHandlers(pages: readonly AdminPageDef[], opts?: AdminPageHandlerOpts): {
-    /** The pages THIS caller may open. Filtered rather than role-annotated: a nav entry
-     * that 403s when clicked is worse than one that is not there, and the role list is a
-     * server fact the browser has no use for. */
+export declare function createAdminPageHandlers(pages: readonly AdminScreenDef[], opts?: AdminPageHandlerOpts): {
+    /** The screens THIS caller may open — Block Kit pages and panels alike. Filtered rather
+     * than role-annotated: a nav entry that 403s when clicked is worse than one that is not
+     * there, and the role list is a server fact the browser has no use for.
+     *
+     * A panel is filtered by exactly the same gate, which is the whole reason it is a
+     * registry entry rather than a client-side registration: the browser bundle decides
+     * only how the screen DRAWS, never whether this caller has one. */
     listAdminPages: import("@pramen/server").Handler<unknown, AdminPageMeta[]>;
     /**
      * Render a page, or act on it and render the result.
@@ -251,6 +320,9 @@ export declare function createAdminPageHandlers(pages: readonly AdminPageDef[],
  *   - `image.url` becomes an `<img src>`, so it goes through the same `isSafeHref`
  *     allow-list a rich-text link mark does.
  *   - nesting is capped, because rendering is recursive.
+ *   - a table cell that is an OBJECT is claiming to be an element, and is checked as one.
+ *   - every input's `action_id` is claimed once per page, because the editor keys the
+ *     page's whole value bag by it.
  *
  * A bad block throws rather than being dropped: this is the page author's own output, and a
  * block that silently vanishes is a bug that reads as "the data isn't there".

package/dist/blockkit.js

@@ -21,6 +21,46 @@
 // `FieldDefinition[]` -> `FieldForm` is already "server-described form, host-rendered". Block
 // Kit is those two taken all the way: arbitrary admin PAGES, not just forms over rows.
 //
+// AND YET `adminPanel()` SHIPS BESIDE IT, WHICH IS PROJECT CODE IN THE BROWSER
+//
+// It does, and the paragraph above is not quietly wrong — the two are one position, not two.
+// What that paragraph rejects is publishing the EDITOR'S COMPONENT LIBRARY so that every
+// project assembles its own admin out of it: that is what makes N forks of the same 80%,
+// because each project then owns the chrome, the nav, the page list, the login and the media
+// browser, and every fix has to be made N times. A panel is the opposite trade — ONE SCREEN,
+// rendered inside chrome that is still ours, at a route that is still ours, from a registry
+// entry that is still the server's. No component API is published: a panel is handed React,
+// four props and nothing else (`panel-runtime.ts` in @pramen/cms-editor is a long argument
+// about what is deliberately absent from that list), so there is nothing to reassemble an
+// admin out of and no reason to fork one.
+//
+// What the objection DOES carry over is version skew, and it is not waved away: a panel is
+// compiled at the project's build, against whichever React they had, and linked at runtime
+// against whichever React the editor loaded. That is why the seam is a numbered contract a
+// bundle must STATE and the editor refuses on mismatch, rather than a promise in a README.
+// Skew becomes one refusal naming the slug and the fix, on the screen the panel should have
+// been — which is precisely what "N per-project forks" never had.
+//
+// WHICH TO REACH FOR, AND WHAT THE SECOND ONE COSTS
+//
+// `adminPage()` for a list-and-form screen: rows, filters, a form, a confirm. No build step,
+// no bundle to keep deployed in step with the admin, no React version to keep aligned, and no
+// project code in the browser at all. `adminPanel()` when the screen IS the interaction —
+// something that responds as you type, a row that expands, a dialog, a canvas, a date input.
+// Those are not elements Block Kit happens to be missing; they are things a server-driven
+// vocabulary cannot express, and the list does not shrink by adding blocks.
+//
+// The cost, stated plainly, because it is what makes that order more than a preference: A
+// PANEL IS TRUSTED CODE. Its bundle runs in the editor's own page with the editor's own
+// session in scope — it can read the stored token, make any call the caller could make, and
+// render anything anywhere on the page. `roles` on `adminPanel()` decides who is SHOWN the
+// screen and the ACL still bounds what the server will do for whoever is asking, but neither
+// constrains the bundle. `PanelApi` is a CONVENIENCE — the one obvious way to make an
+// authenticated call — and not a sandbox; there is no sandbox to be had short of a
+// cross-origin iframe, which would give up the shared chrome that is the entire point. Ship a
+// panel you wrote, from your own origin, and treat its bundle as part of the admin. Block
+// Kit's headline property is that none of this paragraph is ever needed.
+//
 // WHAT IT IS NOT
 //
 // It is not a way to reach past the ACL. A page's `render` is an ordinary handler body: it
@@ -34,6 +74,15 @@
 import { BadRequest, mutation, query } from "@pramen/server";
 import { isSafeHref, normalizeHref } from "./href";
 import { NAV_ORDER } from "./nav";
+import { isAdminPanel } from "./panel";
+/** Every `AdminElement` tag, as a runtime set.
+ *
+ * Both halves need this at RUNTIME, which is why it is a value and not only a union: the
+ * server checks that an object sitting in a table cell really is an element, and the editor
+ * decides from the same set whether a cell draws as text or as a control. The editor keeps
+ * its own copy (it has no dependency on this package) and `test/cms-editor-mirrors.test.ts`
+ * fails if the two drift. */
+export const ADMIN_ELEMENT_TYPES = ["button", "text_input", "number_input", "select", "toggle", "secret_input"];
 /** How deep `columns` / `accordion` may nest blocks. Rendering is recursive and the
  * response is server-authored but not necessarily hand-written, so it is capped. */
 export const MAX_ADMIN_BLOCK_DEPTH = 4;
@@ -53,9 +102,18 @@ export const MAX_ADMIN_BLOCK_DEPTH = 4;
 export function adminPage(slug, opts) {
     return { ...opts, slug };
 }
-/** Validate a registry at boot: slugs are unique and routable, and every page can be
+/** Every screen kind, as a runtime set. A value and not only a union because the editor
+ * keeps its own copy and `test/cms-editor-mirrors.test.ts` fails if the two drift — a kind
+ * the server sends and the editor has not heard of is a nav entry that renders nothing. */
+export const ADMIN_PAGE_KINDS = ["blocks", "panel"];
+/** Validate a registry at boot: slugs are unique and routable, and every screen can be
  * addressed. Called by `createAdminPageHandlers`, so a mistake surfaces when the Worker
- * starts rather than as a 404 the first time someone opens the one page nobody exercised. */
+ * starts rather than as a 404 the first time someone opens the one page nobody exercised.
+ *
+ * Pages and panels are validated TOGETHER, against one `seen` set: they share `/apps/:slug`,
+ * so two entries with the same slug are a collision whatever their kinds — and the one that
+ * would win is decided by insertion order into a Map, which is not a thing to leave to
+ * chance. */
 export function validateAdminPages(pages) {
     const seen = new Set();
     for (const p of pages) {
@@ -67,7 +125,10 @@ export function validateAdminPages(pages) {
         seen.add(p.slug);
         if (p.label.trim() === "")
             throw new Error(`pramen/cms: admin page '${p.slug}' has an empty label — it would render an unnamed nav entry`);
-        if (typeof p.render !== "function")
+        // A panel has no server render by definition, so the check is skipped for it rather
+        // than relaxed for everyone: "no render function" stays a boot error for a Block Kit
+        // page, which is the one it was written to catch.
+        if (!isAdminPanel(p) && typeof p.render !== "function")
             throw new Error(`pramen/cms: admin page '${p.slug}' has no render function`);
     }
 }
@@ -93,12 +154,16 @@ export function createAdminPageHandlers(pages, opts = {}) {
     const rolesFor = (p) => p.roles ?? defaultRoles;
     const mayOpen = (ctx, p) => held(ctx).some((r) => rolesFor(p).includes(r));
     return {
-        /** The pages THIS caller may open. Filtered rather than role-annotated: a nav entry
-         * that 403s when clicked is worse than one that is not there, and the role list is a
-         * server fact the browser has no use for. */
+        /** The screens THIS caller may open — Block Kit pages and panels alike. Filtered rather
+         * than role-annotated: a nav entry that 403s when clicked is worse than one that is not
+         * there, and the role list is a server fact the browser has no use for.
+         *
+         * A panel is filtered by exactly the same gate, which is the whole reason it is a
+         * registry entry rather than a client-side registration: the browser bundle decides
+         * only how the screen DRAWS, never whether this caller has one. */
         listAdminPages: query((ctx) => pages
             .filter((p) => mayOpen(ctx, p))
-            .map((p) => ({ slug: p.slug, label: p.label, icon: p.icon, navOrder: p.navOrder ?? NAV_ORDER.adminPages }))),
+            .map((p) => ({ slug: p.slug, label: p.label, icon: p.icon, navOrder: p.navOrder ?? NAV_ORDER.adminPages, kind: isAdminPanel(p) ? "panel" : "blocks" }))),
         /**
          * Render a page, or act on it and render the result.
          *
@@ -117,6 +182,13 @@ export function createAdminPageHandlers(pages, opts = {}) {
             // Before `render`, so a page's own code never runs for a caller who may not open it.
             if (!mayOpen(ctx, page))
                 throw new BadRequest(`unknown admin page '${input.page}'`);
+            // A panel renders in the BROWSER, so there is nothing here to interact with. Said
+            // plainly rather than folded into "unknown admin page": the caller may open this
+            // screen (it passed the gate above), so hiding its existence would only send whoever
+            // wired the call looking for a registration mistake that is not there. It is a client
+            // bug — the editor routes a panel to its component and never calls this.
+            if (isAdminPanel(page))
+                throw new BadRequest(`admin page '${input.page}' is a panel — it renders in the browser and has no server-side render`);
             const res = await page.render(ctx, input);
             return normalizeAdminResponse(res);
         }, {
@@ -157,6 +229,9 @@ export function createAdminPageHandlers(pages, opts = {}) {
  *   - `image.url` becomes an `<img src>`, so it goes through the same `isSafeHref`
  *     allow-list a rich-text link mark does.
  *   - nesting is capped, because rendering is recursive.
+ *   - a table cell that is an OBJECT is claiming to be an element, and is checked as one.
+ *   - every input's `action_id` is claimed once per page, because the editor keys the
+ *     page's whole value bag by it.
  *
  * A bad block throws rather than being dropped: this is the page author's own output, and a
  * block that silently vanishes is a bug that reads as "the data isn't there".
@@ -164,12 +239,16 @@ export function createAdminPageHandlers(pages, opts = {}) {
 export function normalizeAdminResponse(res) {
     if (!res || !Array.isArray(res.blocks))
         throw new Error("pramen/cms: an admin page must return { blocks: [...] }");
-    const out = { blocks: res.blocks.map((b) => normalizeAdminBlock(b, 0)) };
+    // One set for the WHOLE response, because the value bag it guards is per PAGE, not per
+    // block — an input in a form and an input in a table cell collide just as hard as two in
+    // one form.
+    const inputIds = new Set();
+    const out = { blocks: res.blocks.map((b) => normalizeAdminBlock(b, 0, inputIds)) };
     if (res.toast)
         out.toast = { text: String(res.toast.text), tone: res.toast.tone };
     return out;
 }
-function normalizeAdminBlock(block, depth) {
+function normalizeAdminBlock(block, depth, inputIds) {
     if (depth >= MAX_ADMIN_BLOCK_DEPTH)
         throw new Error(`pramen/cms: admin blocks nest deeper than ${MAX_ADMIN_BLOCK_DEPTH} levels`);
     switch (block.type) {
@@ -180,16 +259,66 @@ function normalizeAdminBlock(block, depth) {
             return { ...block, url };
         }
         case "columns":
-            return { ...block, columns: block.columns.map((col) => col.map((b) => normalizeAdminBlock(b, depth + 1))) };
+            return { ...block, columns: block.columns.map((col) => col.map((b) => normalizeAdminBlock(b, depth + 1, inputIds))) };
         case "accordion":
-            return { ...block, blocks: block.blocks.map((b) => normalizeAdminBlock(b, depth + 1)) };
+            return { ...block, blocks: block.blocks.map((b) => normalizeAdminBlock(b, depth + 1, inputIds)) };
         case "form":
             // `block_id` is how the editor keys a form's local values. Two forms sharing one would
             // share their state, so the second would submit the first one's inputs.
             if (!block.block_id)
                 throw new Error("pramen/cms: a `form` block needs a block_id");
+            for (const f of block.fields)
+                claimInputId(f, `form '${block.block_id}'`, inputIds);
             return block;
+        case "actions":
+            for (const el of block.elements)
+                if (el.type !== "button")
+                    claimInputId(el, "an `actions` block", inputIds);
+            return block;
+        case "table": {
+            // Only the cells a COLUMN names are looked at, because only those are rendered. A key
+            // in `rows` with no column is data the table happens to carry along; checking it would
+            // reject rows a page is free to build wide and display narrow.
+            for (const [i, row] of block.rows.entries()) {
+                for (const c of block.columns) {
+                    const cell = row[c.key];
+                    if (!isElementCell(cell))
+                        continue;
+                    checkCellElement(cell, c.key, i);
+                    if (cell.type !== "button")
+                        claimInputId(cell, `table column '${c.key}'`, inputIds);
+                }
+            }
+            return block;
+        }
         default:
             return block;
     }
 }
+/** An object in a cell is claiming to be an element — nothing else may be one. Narrowed to
+ * `AdminElement` here only so the check that follows can read its tag; whether it IS one is
+ * exactly what {@link checkCellElement} decides. */
+const isElementCell = (cell) => cell !== null && typeof cell === "object";
+function checkCellElement(cell, column, rowIndex) {
+    const where = `table column '${column}', row ${rowIndex}`;
+    const kinds = ADMIN_ELEMENT_TYPES;
+    if (!kinds.includes(cell.type)) {
+        throw new Error(`pramen/cms: ${where} holds an object that is not an admin element (type ${JSON.stringify(cell.type)}). A cell is a value or one of ${kinds.join(", ")} — a whole row object put in a cell would render as [object Object]`);
+    }
+    if (!cell.action_id)
+        throw new Error(`pramen/cms: the element in ${where} has no action_id — nothing would come back when it fires`);
+    if (cell.type === "button" && !cell.label)
+        throw new Error(`pramen/cms: the button in ${where} has no label — it would draw as an empty control`);
+}
+/** Claim one input's `action_id` for the page.
+ *
+ * The editor holds ONE value bag for the whole page, keyed by `action_id`, because that is
+ * what makes a filter in one block reach a button in another. So two inputs sharing an id
+ * are one field wearing two hats, which is only ever a bug — and the way to write it by
+ * accident is to build a table and put the same input literal in every row. */
+function claimInputId(input, where, seen) {
+    if (seen.has(input.action_id)) {
+        throw new Error(`pramen/cms: action_id '${input.action_id}' is used by more than one input on this page (${where}) — the editor keys the page's value bag by action_id, so they would be ONE field: same value shown in every copy, and the last write wins on submit. A per-ROW input has to mint a per-row id (\`hours:\${row.id}\`); a per-row BUTTON does not, because its \`value\` rides back on the interaction instead`);
+    }
+    seen.add(input.action_id);
+}

package/dist/index.d.ts

@@ -1149,8 +1149,12 @@ export declare function taxonomyApplies(row: {
 }, target: TaxonomyTarget): boolean;
 /** Block Kit — custom admin pages, described as JSON and rendered by the editor. See
  * `./blockkit`. Re-exported so a host imports `adminPage` beside `collection`. */
-export { adminPage, createAdminPageHandlers, normalizeAdminResponse, validateAdminPages, MAX_ADMIN_BLOCK_DEPTH, } from "./blockkit";
-export type { AdminBlock, AdminButton, AdminElement, AdminInput, AdminInteractionType, AdminPageDef, AdminPageHandlerOpts, AdminPageInteraction, AdminPageMeta, AdminPageResponse, AdminText, } from "./blockkit";
+export { adminPage, createAdminPageHandlers, normalizeAdminResponse, validateAdminPages, ADMIN_ELEMENT_TYPES, ADMIN_PAGE_KINDS, MAX_ADMIN_BLOCK_DEPTH, } from "./blockkit";
+export type { AdminBlock, AdminButton, AdminCell, AdminElement, AdminInput, AdminInteractionType, AdminPageDef, AdminPageHandlerOpts, AdminPageInteraction, AdminPageKind, AdminPageMeta, AdminPageResponse, AdminScreenDef, AdminText, } from "./blockkit";
+/** Custom admin PANELS — a project's own React screen inside the editor's chrome, for the
+ * screens a server-driven vocabulary cannot carry. See `./panel`. */
+export { adminPanel, isAdminPanel } from "./panel";
+export type { AdminPanelDef } from "./panel";
 /**
  * Columns this package wrote in the pre-ISO space form that the SCHEMA cannot identify.
  *

package/dist/index.js

@@ -851,7 +851,10 @@ async function assertTermsApplyTo(db, termIds, target) {
 }
 /** Block Kit — custom admin pages, described as JSON and rendered by the editor. See
  * `./blockkit`. Re-exported so a host imports `adminPage` beside `collection`. */
-export { adminPage, createAdminPageHandlers, normalizeAdminResponse, validateAdminPages, MAX_ADMIN_BLOCK_DEPTH, } from "./blockkit";
+export { adminPage, createAdminPageHandlers, normalizeAdminResponse, validateAdminPages, ADMIN_ELEMENT_TYPES, ADMIN_PAGE_KINDS, MAX_ADMIN_BLOCK_DEPTH, } from "./blockkit";
+/** Custom admin PANELS — a project's own React screen inside the editor's chrome, for the
+ * screens a server-driven vocabulary cannot carry. See `./panel`. */
+export { adminPanel, isAdminPanel } from "./panel";
 /**
  * Columns this package wrote in the pre-ISO space form that the SCHEMA cannot identify.
  *

package/dist/panel.d.ts

@@ -0,0 +1,53 @@
+/** One custom admin panel: a nav entry the browser bundle fills in.
+ *
+ * There is no `render` here and there is not meant to be one — the rendering half is a
+ * React component the deployment's panel bundle registers under the same `slug`. Everything
+ * that decides whether the entry EXISTS is here, on the server, where it can be enforced.
+ */
+export interface AdminPanelDef {
+    /** Discriminates a panel from an `AdminPageDef` in the one registry they share. Set by
+     * {@link adminPanel}; it is a required field rather than an inferred one so a hand-built
+     * object literal cannot be a half-declared panel. */
+    readonly kind: "panel";
+    /** URL + registry key: served at `/apps/:slug` in the editor, and the id the browser
+     * bundle registers its component under. */
+    readonly slug: string;
+    /** Nav label. */
+    readonly label: string;
+    /** Optional nav icon (emoji or short string). */
+    readonly icon?: string;
+    /** Where it sits in the nav — see `NAV_ORDER`. Defaults to `NAV_ORDER.adminPages`. */
+    readonly navOrder?: number;
+    /** Roles that may open it. Defaults to the deployment's `editorRoles`, exactly as a Block
+     * Kit page's does — one registry, one gate.
+     *
+     * This is the ONLY authorization a panel gets for free. A panel's own code runs in the
+     * browser, so every call it makes is an ordinary RPC under the caller's own identity and
+     * ACL; this list decides who is shown the screen, not what the screen may do. */
+    readonly roles?: readonly string[];
+}
+/**
+ * Declare a custom admin panel. Spread the result into `createAdminPageHandlers` alongside
+ * any `adminPage()`s:
+ *
+ *   const curation = adminPanel("curation", {
+ *     label: "Curation",
+ *     icon: "🎛",
+ *     navOrder: NAV_ORDER.media + 10,
+ *     roles: ["editor", "admin"],
+ *   });
+ *
+ *   handlers = { ...createAdminPageHandlers([desk, curation], { editorRoles }) };
+ *
+ * The matching component is registered by the deployment's panel bundle — see the
+ * "Custom admin panels" section of the CMS docs.
+ */
+export declare function adminPanel(slug: string, opts: Omit<AdminPanelDef, "slug" | "kind">): AdminPanelDef;
+/** Whether a registry entry is a panel (and so has no server-side render).
+ *
+ * Reads the discriminant rather than testing for the ABSENCE of `render`: "no render" is
+ * also what a malformed page looks like, and `validateAdminPages` has to be able to tell a
+ * panel from a page someone forgot to finish. */
+export declare function isAdminPanel(def: {
+    readonly kind?: string;
+}): def is AdminPanelDef;

package/dist/panel.js

@@ -0,0 +1,74 @@
+// A custom admin PANEL — a project's own React screen, rendered inside the editor's chrome
+// at a real route with a real nav entry.
+//
+// WHY A SECOND KIND, WHEN `adminPage()` EXISTS
+//
+// Block Kit (`adminPage()`) is a server-driven vocabulary: the handler returns JSON, the
+// editor renders it, and the whole page comes back on every interaction. That is exactly
+// right for a list-and-form screen, and it is the reason no project JavaScript runs in the
+// admin. But the properties that make it safe are the same ones that cap it — an input
+// cannot fire an interaction, every control is disabled for the round trip (so focus and
+// caret are lost on each keystroke that matters), a table row cannot expand, and there is
+// no link, no redirect, no dialog, no autofocus and no date input. Those are not gaps to
+// patch one element at a time; a screen that needs local interaction needs local code.
+//
+// The alternative a project reaches for when Block Kit runs out is what this replaces: a
+// standalone React SPA served next to the editor with the chrome rebuilt by hand. It goes
+// out of the application, it does not have the same layout, and every chrome fix has to be
+// made twice.
+//
+// So a panel is the SAME registry entry as a Block Kit page with the render moved to the
+// browser. Same slug space, same `/apps/:slug` route, same "Apps" band in the nav, and —
+// the part that matters — the same server-side role filter: a panel the caller may not open
+// is absent from `listAdminPages`, so there is no nav entry to click and no route to reach.
+//
+// WHAT LIVES WHERE. The server owns everything a nav entry is made of (slug, label, icon,
+// position, roles); the browser bundle owns only the component. That split is deliberate:
+// if the bundle declared the label and the position, a client that failed to load would
+// take the nav entry with it, and a client that loaded would be declaring its own placement
+// with nothing to check it against. A panel whose bundle never registers is a listed entry
+// that renders a diagnostic — which is a legible failure — rather than a section that
+// silently ceases to exist.
+//
+// WHAT IS GIVEN UP. Block Kit's headline property is that no project JavaScript ever runs in
+// the admin (#33). A panel gives that up, deliberately and only where a deployment asks for
+// it: the bundle runs in the editor's own page with the editor's own session in scope, so it
+// can read the stored token and call anything the caller can. `roles` below and the ACL still
+// bound what the SERVER will do, and `PanelApi` is a small surface to write against, but
+// neither is a sandbox — a panel is part of the admin, not a guest in it. That is the reason
+// `adminPage()` remains the first thing to reach for and this the second.
+//
+// The same reconciliation is written from the other side at the top of `blockkit.ts` — why
+// "do not ship the component tree" and this are one position rather than two, and which of
+// the pair to reach for first. Read together; changing one without the other leaves the
+// framework arguing with itself.
+//
+// A LEAF module, like `href.ts` and `nav.ts`: `blockkit.ts` imports it to widen the
+// registry, and it imports nothing back.
+/**
+ * Declare a custom admin panel. Spread the result into `createAdminPageHandlers` alongside
+ * any `adminPage()`s:
+ *
+ *   const curation = adminPanel("curation", {
+ *     label: "Curation",
+ *     icon: "🎛",
+ *     navOrder: NAV_ORDER.media + 10,
+ *     roles: ["editor", "admin"],
+ *   });
+ *
+ *   handlers = { ...createAdminPageHandlers([desk, curation], { editorRoles }) };
+ *
+ * The matching component is registered by the deployment's panel bundle — see the
+ * "Custom admin panels" section of the CMS docs.
+ */
+export function adminPanel(slug, opts) {
+    return { ...opts, kind: "panel", slug };
+}
+/** Whether a registry entry is a panel (and so has no server-side render).
+ *
+ * Reads the discriminant rather than testing for the ABSENCE of `render`: "no render" is
+ * also what a malformed page looks like, and `validateAdminPages` has to be able to tell a
+ * panel from a page someone forgot to finish. */
+export function isAdminPanel(def) {
+    return def.kind === "panel";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/cms",
-  "version": "0.0.63",
+  "version": "0.0.64",
   "description": "Optional block/page builder for pramen — Drupal-Paragraphs-style typed blocks in named regions, reusable blocks, scheduled publishing, built entirely from pramen primitives.",
   "license": "MIT",
   "repository": {
@@ -41,7 +41,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pramen/server": "0.0.63"
+    "@pramen/server": "0.0.64"
   },
   "peerDependencies": {
     "react": ">=18"

package/src/blockkit.ts

@@ -21,6 +21,46 @@
 // `FieldDefinition[]` -> `FieldForm` is already "server-described form, host-rendered". Block
 // Kit is those two taken all the way: arbitrary admin PAGES, not just forms over rows.
 //
+// AND YET `adminPanel()` SHIPS BESIDE IT, WHICH IS PROJECT CODE IN THE BROWSER
+//
+// It does, and the paragraph above is not quietly wrong — the two are one position, not two.
+// What that paragraph rejects is publishing the EDITOR'S COMPONENT LIBRARY so that every
+// project assembles its own admin out of it: that is what makes N forks of the same 80%,
+// because each project then owns the chrome, the nav, the page list, the login and the media
+// browser, and every fix has to be made N times. A panel is the opposite trade — ONE SCREEN,
+// rendered inside chrome that is still ours, at a route that is still ours, from a registry
+// entry that is still the server's. No component API is published: a panel is handed React,
+// four props and nothing else (`panel-runtime.ts` in @pramen/cms-editor is a long argument
+// about what is deliberately absent from that list), so there is nothing to reassemble an
+// admin out of and no reason to fork one.
+//
+// What the objection DOES carry over is version skew, and it is not waved away: a panel is
+// compiled at the project's build, against whichever React they had, and linked at runtime
+// against whichever React the editor loaded. That is why the seam is a numbered contract a
+// bundle must STATE and the editor refuses on mismatch, rather than a promise in a README.
+// Skew becomes one refusal naming the slug and the fix, on the screen the panel should have
+// been — which is precisely what "N per-project forks" never had.
+//
+// WHICH TO REACH FOR, AND WHAT THE SECOND ONE COSTS
+//
+// `adminPage()` for a list-and-form screen: rows, filters, a form, a confirm. No build step,
+// no bundle to keep deployed in step with the admin, no React version to keep aligned, and no
+// project code in the browser at all. `adminPanel()` when the screen IS the interaction —
+// something that responds as you type, a row that expands, a dialog, a canvas, a date input.
+// Those are not elements Block Kit happens to be missing; they are things a server-driven
+// vocabulary cannot express, and the list does not shrink by adding blocks.
+//
+// The cost, stated plainly, because it is what makes that order more than a preference: A
+// PANEL IS TRUSTED CODE. Its bundle runs in the editor's own page with the editor's own
+// session in scope — it can read the stored token, make any call the caller could make, and
+// render anything anywhere on the page. `roles` on `adminPanel()` decides who is SHOWN the
+// screen and the ACL still bounds what the server will do for whoever is asking, but neither
+// constrains the bundle. `PanelApi` is a CONVENIENCE — the one obvious way to make an
+// authenticated call — and not a sandbox; there is no sandbox to be had short of a
+// cross-origin iframe, which would give up the shared chrome that is the entire point. Ship a
+// panel you wrote, from your own origin, and treat its bundle as part of the admin. Block
+// Kit's headline property is that none of this paragraph is ever needed.
+//
 // WHAT IT IS NOT
 //
 // It is not a way to reach past the ACL. A page's `render` is an ordinary handler body: it
@@ -36,6 +76,7 @@ import { BadRequest, mutation, query } from "@pramen/server";
 import type { HandlerContext, JsonValue, SchemaDef } from "@pramen/server";
 import { isSafeHref, normalizeHref } from "./href";
 import { NAV_ORDER } from "./nav";
+import { isAdminPanel, type AdminPanelDef } from "./panel";
 
 // --- the block/element vocabulary ------------------------------------------------------
 
@@ -43,16 +84,23 @@ import { NAV_ORDER } from "./nav";
  * string through React, so there is no HTML path here to sanitize. */
 export type AdminText = string;
 
-/** An input a form (or an actions row) can carry. */
+/** An input a form, an actions row or a table cell can carry.
+ *
+ * `error` is the per-FIELD failure, rendered under the offending input. The page-level
+ * `toast` cannot do that job: it names no field, it is gone in three seconds while the bad
+ * value is still on screen, and a form with six inputs gives the reader no way to tell which
+ * one "25:00 is not a time" is about. It is a plain part of the render — the whole page
+ * comes back on every interaction, so an error lives exactly as long as the response that
+ * carried it, and there is nothing to clear. */
 export type AdminInput =
-  | { type: "text_input"; action_id: string; label?: AdminText; placeholder?: AdminText; initial_value?: string; multiline?: boolean; required?: boolean }
-  | { type: "number_input"; action_id: string; label?: AdminText; placeholder?: AdminText; initial_value?: number; min?: number; max?: number; required?: boolean }
-  | { type: "select"; action_id: string; label?: AdminText; options: { value: string; label: AdminText }[]; initial_value?: string; required?: boolean }
-  | { type: "toggle"; action_id: string; label?: AdminText; initial_value?: boolean }
+  | { type: "text_input"; action_id: string; label?: AdminText; placeholder?: AdminText; initial_value?: string; multiline?: boolean; required?: boolean; error?: AdminText }
+  | { type: "number_input"; action_id: string; label?: AdminText; placeholder?: AdminText; initial_value?: number; min?: number; max?: number; required?: boolean; error?: AdminText }
+  | { type: "select"; action_id: string; label?: AdminText; options: { value: string; label: AdminText }[]; initial_value?: string; required?: boolean; error?: AdminText }
+  | { type: "toggle"; action_id: string; label?: AdminText; initial_value?: boolean; error?: AdminText }
   /** Write-only: never echoed back to the browser once stored. The editor renders it as a
    * password field and sends it only on submit; a page that stores one must NOT put it back
    * in `initial_value` on the next render, which is why there is no such key here. */
-  | { type: "secret_input"; action_id: string; label?: AdminText; placeholder?: AdminText; required?: boolean };
+  | { type: "secret_input"; action_id: string; label?: AdminText; placeholder?: AdminText; required?: boolean; error?: AdminText };
 
 /** A button. `value` rides back on the interaction, so one `action_id` can serve a row. */
 export interface AdminButton {
@@ -68,6 +116,32 @@ export interface AdminButton {
 
 export type AdminElement = AdminButton | AdminInput;
 
+/** Every `AdminElement` tag, as a runtime set.
+ *
+ * Both halves need this at RUNTIME, which is why it is a value and not only a union: the
+ * server checks that an object sitting in a table cell really is an element, and the editor
+ * decides from the same set whether a cell draws as text or as a control. The editor keeps
+ * its own copy (it has no dependency on this package) and `test/cms-editor-mirrors.test.ts`
+ * fails if the two drift. */
+export const ADMIN_ELEMENT_TYPES = ["button", "text_input", "number_input", "select", "toggle", "secret_input"] as const;
+
+/** What one table cell holds: a value to READ, or an element to ACT with.
+ *
+ * The alternative shape was a per-COLUMN element declaration — `columns: [{ key, label,
+ * element }]` — and it is the wrong unit. Everything about a row's control is a fact of the
+ * ROW: the button's `value` is that row's id, its label is "Hide" or "Show" depending on
+ * that row's state, and a row that must not be touched carries no control at all. A column
+ * declaration would have to be a template with a substitution language, which is a second
+ * vocabulary to design and to escape. A cell already varies per row, so the element goes in
+ * the cell and the column keeps saying only where it lands. A cell is a value OR an element,
+ * never both; a column that wants both is two columns.
+ *
+ * The two are told apart by SHAPE: a display value is a primitive, an element is an object,
+ * and nothing else may be an object. `normalizeAdminResponse` enforces that, so a page that
+ * splats a whole row (`rows: found`) into the table is named at the boundary instead of
+ * rendering a column of `[object Object]` — or, worse, of half-elements. */
+export type AdminCell = AdminText | number | boolean | null | AdminElement;
+
 /** One block in a rendered admin page. */
 export type AdminBlock =
   | { type: "header"; text: AdminText; level?: 1 | 2 | 3 }
@@ -77,7 +151,9 @@ export type AdminBlock =
   | { type: "context"; text: AdminText }
   /** Label/value pairs, for a record's details. */
   | { type: "fields"; fields: { label: AdminText; value: AdminText }[] }
-  | { type: "table"; columns: { key: string; label: AdminText }[]; rows: Record<string, AdminText | number | boolean | null>[]; empty?: AdminText }
+  /** `block_id` rides back on an interaction a CELL fired, the same way an `actions` block's
+   * does — so a page with two tables can tell which one a shared `action_id` came from. */
+  | { type: "table"; block_id?: string; columns: { key: string; label: AdminText }[]; rows: Record<string, AdminCell>[]; empty?: AdminText }
   | { type: "stats"; stats: { label: AdminText; value: AdminText; hint?: AdminText }[] }
   | { type: "actions"; block_id?: string; elements: AdminElement[] }
   | { type: "form"; block_id: string; fields: AdminInput[]; submit: { label: AdminText; action_id: string } }
@@ -128,6 +204,10 @@ export const MAX_ADMIN_BLOCK_DEPTH = 4;
  * Without it `ctx.db.find({ from: "lectures", where: { title: { contains: q } } })` resolves
  * the table against the default `SchemaDef` and every column reads as a number. */
 export interface AdminPageDef<S extends SchemaDef = SchemaDef> {
+  /** Discriminates this from an `AdminPanelDef` in the registry the two share. Optional and
+   * defaulted, because a Block Kit page is what `adminPage()` has always produced and
+   * nothing should have to start saying so. */
+  readonly kind?: "blocks";
   /** URL + registry key: the page is served at `/apps/:slug` in the editor. */
   readonly slug: string;
   /** Nav label. */
@@ -165,20 +245,42 @@ export function adminPage<S extends SchemaDef = SchemaDef>(slug: string, opts: O
   return { ...opts, slug };
 }
 
-/** The client-facing view of a page — what the editor needs to put it in the nav. Never
- * the `render` function, and never the role list (which is a server fact; a page the caller
- * may not open is simply absent from the listing). */
+/** One entry in the custom-screens registry: a Block Kit page, or a panel the browser
+ * renders. They share a registry — and so a slug space, a route and a nav band — because
+ * from the editor's side they are the same thing (a project's own screen inside the chrome)
+ * differing only in where the rendering happens. Two registries would have made a slug
+ * collision between them a runtime surprise instead of a boot error. */
+export type AdminScreenDef<S extends SchemaDef = SchemaDef> = AdminPageDef<S> | AdminPanelDef;
+
+/** Every screen kind, as a runtime set. A value and not only a union because the editor
+ * keeps its own copy and `test/cms-editor-mirrors.test.ts` fails if the two drift — a kind
+ * the server sends and the editor has not heard of is a nav entry that renders nothing. */
+export const ADMIN_PAGE_KINDS = ["blocks", "panel"] as const;
+export type AdminPageKind = (typeof ADMIN_PAGE_KINDS)[number];
+
+/** The client-facing view of a registered screen — what the editor needs to put it in the
+ * nav and decide how to render it. Never the `render` function, and never the role list
+ * (which is a server fact; a screen the caller may not open is simply absent from the
+ * listing). */
 export interface AdminPageMeta {
   slug: string;
   label: string;
   icon?: string;
   navOrder: number;
+  /** `"blocks"` (Block Kit, rendered from this response) or `"panel"` (a component the
+   * deployment's panel bundle registered under this slug). */
+  kind: AdminPageKind;
 }
 
-/** Validate a registry at boot: slugs are unique and routable, and every page can be
+/** Validate a registry at boot: slugs are unique and routable, and every screen can be
  * addressed. Called by `createAdminPageHandlers`, so a mistake surfaces when the Worker
- * starts rather than as a 404 the first time someone opens the one page nobody exercised. */
-export function validateAdminPages(pages: readonly AdminPageDef[]): void {
+ * starts rather than as a 404 the first time someone opens the one page nobody exercised.
+ *
+ * Pages and panels are validated TOGETHER, against one `seen` set: they share `/apps/:slug`,
+ * so two entries with the same slug are a collision whatever their kinds — and the one that
+ * would win is decided by insertion order into a Map, which is not a thing to leave to
+ * chance. */
+export function validateAdminPages(pages: readonly AdminScreenDef[]): void {
   const seen = new Set<string>();
   for (const p of pages) {
     if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(p.slug) || p.slug.length > 80) {
@@ -187,7 +289,10 @@ export function validateAdminPages(pages: readonly AdminPageDef[]): void {
     if (seen.has(p.slug)) throw new Error(`pramen/cms: duplicate admin page slug '${p.slug}' — the slug is the registry's key`);
     seen.add(p.slug);
     if (p.label.trim() === "") throw new Error(`pramen/cms: admin page '${p.slug}' has an empty label — it would render an unnamed nav entry`);
-    if (typeof p.render !== "function") throw new Error(`pramen/cms: admin page '${p.slug}' has no render function`);
+    // A panel has no server render by definition, so the check is skipped for it rather
+    // than relaxed for everyone: "no render function" stays a boot error for a Block Kit
+    // page, which is the one it was written to catch.
+    if (!isAdminPanel(p) && typeof p.render !== "function") throw new Error(`pramen/cms: admin page '${p.slug}' has no render function`);
   }
 }
 
@@ -213,21 +318,25 @@ export interface AdminPageHandlerOpts {
  * There is no ACL fragment to spread: a page reads through `ctx.db` under whatever policies
  * the caller already has, so there is nothing here to grant.
  */
-export function createAdminPageHandlers(pages: readonly AdminPageDef[], opts: AdminPageHandlerOpts = {}) {
+export function createAdminPageHandlers(pages: readonly AdminScreenDef[], opts: AdminPageHandlerOpts = {}) {
   validateAdminPages(pages);
   const defaultRoles = opts.editorRoles ?? ["editor", "admin"];
   const bySlug = new Map(pages.map((p) => [p.slug, p]));
-  const rolesFor = (p: AdminPageDef): readonly string[] => p.roles ?? defaultRoles;
-  const mayOpen = (ctx: HandlerContext, p: AdminPageDef): boolean => held(ctx).some((r) => rolesFor(p).includes(r));
+  const rolesFor = (p: AdminScreenDef): readonly string[] => p.roles ?? defaultRoles;
+  const mayOpen = (ctx: HandlerContext, p: AdminScreenDef): boolean => held(ctx).some((r) => rolesFor(p).includes(r));
 
   return {
-    /** The pages THIS caller may open. Filtered rather than role-annotated: a nav entry
-     * that 403s when clicked is worse than one that is not there, and the role list is a
-     * server fact the browser has no use for. */
+    /** The screens THIS caller may open — Block Kit pages and panels alike. Filtered rather
+     * than role-annotated: a nav entry that 403s when clicked is worse than one that is not
+     * there, and the role list is a server fact the browser has no use for.
+     *
+     * A panel is filtered by exactly the same gate, which is the whole reason it is a
+     * registry entry rather than a client-side registration: the browser bundle decides
+     * only how the screen DRAWS, never whether this caller has one. */
     listAdminPages: query((ctx): AdminPageMeta[] =>
       pages
         .filter((p) => mayOpen(ctx, p))
-        .map((p) => ({ slug: p.slug, label: p.label, icon: p.icon, navOrder: p.navOrder ?? NAV_ORDER.adminPages })),
+        .map((p) => ({ slug: p.slug, label: p.label, icon: p.icon, navOrder: p.navOrder ?? NAV_ORDER.adminPages, kind: isAdminPanel(p) ? "panel" : "blocks" })),
     ),
 
     /**
@@ -246,6 +355,12 @@ export function createAdminPageHandlers(pages: readonly AdminPageDef[], opts: Ad
       if (!page) throw new BadRequest(`unknown admin page '${input.page}'`);
       // Before `render`, so a page's own code never runs for a caller who may not open it.
       if (!mayOpen(ctx, page)) throw new BadRequest(`unknown admin page '${input.page}'`);
+      // A panel renders in the BROWSER, so there is nothing here to interact with. Said
+      // plainly rather than folded into "unknown admin page": the caller may open this
+      // screen (it passed the gate above), so hiding its existence would only send whoever
+      // wired the call looking for a registration mistake that is not there. It is a client
+      // bug — the editor routes a panel to its component and never calls this.
+      if (isAdminPanel(page)) throw new BadRequest(`admin page '${input.page}' is a panel — it renders in the browser and has no server-side render`);
       const res = await page.render(ctx, input);
       return normalizeAdminResponse(res);
     }, {
@@ -282,18 +397,25 @@ export function createAdminPageHandlers(pages: readonly AdminPageDef[], opts: Ad
  *   - `image.url` becomes an `<img src>`, so it goes through the same `isSafeHref`
  *     allow-list a rich-text link mark does.
  *   - nesting is capped, because rendering is recursive.
+ *   - a table cell that is an OBJECT is claiming to be an element, and is checked as one.
+ *   - every input's `action_id` is claimed once per page, because the editor keys the
+ *     page's whole value bag by it.
  *
  * A bad block throws rather than being dropped: this is the page author's own output, and a
  * block that silently vanishes is a bug that reads as "the data isn't there".
  */
 export function normalizeAdminResponse(res: AdminPageResponse): AdminPageResponse {
   if (!res || !Array.isArray(res.blocks)) throw new Error("pramen/cms: an admin page must return { blocks: [...] }");
-  const out: AdminPageResponse = { blocks: res.blocks.map((b) => normalizeAdminBlock(b, 0)) };
+  // One set for the WHOLE response, because the value bag it guards is per PAGE, not per
+  // block — an input in a form and an input in a table cell collide just as hard as two in
+  // one form.
+  const inputIds = new Set<string>();
+  const out: AdminPageResponse = { blocks: res.blocks.map((b) => normalizeAdminBlock(b, 0, inputIds)) };
   if (res.toast) out.toast = { text: String(res.toast.text), tone: res.toast.tone };
   return out;
 }
 
-function normalizeAdminBlock(block: AdminBlock, depth: number): AdminBlock {
+function normalizeAdminBlock(block: AdminBlock, depth: number, inputIds: Set<string>): AdminBlock {
   if (depth >= MAX_ADMIN_BLOCK_DEPTH) throw new Error(`pramen/cms: admin blocks nest deeper than ${MAX_ADMIN_BLOCK_DEPTH} levels`);
   switch (block.type) {
     case "image": {
@@ -302,15 +424,63 @@ function normalizeAdminBlock(block: AdminBlock, depth: number): AdminBlock {
       return { ...block, url };
     }
     case "columns":
-      return { ...block, columns: block.columns.map((col) => col.map((b) => normalizeAdminBlock(b, depth + 1))) };
+      return { ...block, columns: block.columns.map((col) => col.map((b) => normalizeAdminBlock(b, depth + 1, inputIds))) };
     case "accordion":
-      return { ...block, blocks: block.blocks.map((b) => normalizeAdminBlock(b, depth + 1)) };
+      return { ...block, blocks: block.blocks.map((b) => normalizeAdminBlock(b, depth + 1, inputIds)) };
     case "form":
       // `block_id` is how the editor keys a form's local values. Two forms sharing one would
       // share their state, so the second would submit the first one's inputs.
       if (!block.block_id) throw new Error("pramen/cms: a `form` block needs a block_id");
+      for (const f of block.fields) claimInputId(f, `form '${block.block_id}'`, inputIds);
       return block;
+    case "actions":
+      for (const el of block.elements) if (el.type !== "button") claimInputId(el, "an `actions` block", inputIds);
+      return block;
+    case "table": {
+      // Only the cells a COLUMN names are looked at, because only those are rendered. A key
+      // in `rows` with no column is data the table happens to carry along; checking it would
+      // reject rows a page is free to build wide and display narrow.
+      for (const [i, row] of block.rows.entries()) {
+        for (const c of block.columns) {
+          const cell = row[c.key];
+          if (!isElementCell(cell)) continue;
+          checkCellElement(cell, c.key, i);
+          if (cell.type !== "button") claimInputId(cell, `table column '${c.key}'`, inputIds);
+        }
+      }
+      return block;
+    }
     default:
       return block;
   }
 }
+
+/** An object in a cell is claiming to be an element — nothing else may be one. Narrowed to
+ * `AdminElement` here only so the check that follows can read its tag; whether it IS one is
+ * exactly what {@link checkCellElement} decides. */
+const isElementCell = (cell: AdminCell | undefined): cell is AdminElement => cell !== null && typeof cell === "object";
+
+function checkCellElement(cell: AdminElement, column: string, rowIndex: number): void {
+  const where = `table column '${column}', row ${rowIndex}`;
+  const kinds = ADMIN_ELEMENT_TYPES as readonly string[];
+  if (!kinds.includes(cell.type)) {
+    throw new Error(`pramen/cms: ${where} holds an object that is not an admin element (type ${JSON.stringify(cell.type)}). A cell is a value or one of ${kinds.join(", ")} — a whole row object put in a cell would render as [object Object]`);
+  }
+  if (!cell.action_id) throw new Error(`pramen/cms: the element in ${where} has no action_id — nothing would come back when it fires`);
+  if (cell.type === "button" && !cell.label) throw new Error(`pramen/cms: the button in ${where} has no label — it would draw as an empty control`);
+}
+
+/** Claim one input's `action_id` for the page.
+ *
+ * The editor holds ONE value bag for the whole page, keyed by `action_id`, because that is
+ * what makes a filter in one block reach a button in another. So two inputs sharing an id
+ * are one field wearing two hats, which is only ever a bug — and the way to write it by
+ * accident is to build a table and put the same input literal in every row. */
+function claimInputId(input: AdminInput, where: string, seen: Set<string>): void {
+  if (seen.has(input.action_id)) {
+    throw new Error(
+      `pramen/cms: action_id '${input.action_id}' is used by more than one input on this page (${where}) — the editor keys the page's value bag by action_id, so they would be ONE field: same value shown in every copy, and the last write wins on submit. A per-ROW input has to mint a per-row id (\`hours:\${row.id}\`); a per-row BUTTON does not, because its \`value\` rides back on the interaction instead`,
+    );
+  }
+  seen.add(input.action_id);
+}

package/src/index.ts

@@ -1306,22 +1306,32 @@ export {
   createAdminPageHandlers,
   normalizeAdminResponse,
   validateAdminPages,
+  ADMIN_ELEMENT_TYPES,
+  ADMIN_PAGE_KINDS,
   MAX_ADMIN_BLOCK_DEPTH,
 } from "./blockkit";
 export type {
   AdminBlock,
   AdminButton,
+  AdminCell,
   AdminElement,
   AdminInput,
   AdminInteractionType,
   AdminPageDef,
   AdminPageHandlerOpts,
   AdminPageInteraction,
+  AdminPageKind,
   AdminPageMeta,
   AdminPageResponse,
+  AdminScreenDef,
   AdminText,
 } from "./blockkit";
 
+/** Custom admin PANELS — a project's own React screen inside the editor's chrome, for the
+ * screens a server-driven vocabulary cannot carry. See `./panel`. */
+export { adminPanel, isAdminPanel } from "./panel";
+export type { AdminPanelDef } from "./panel";
+
 /**
  * Columns this package wrote in the pre-ISO space form that the SCHEMA cannot identify.
  *

package/src/panel.ts

@@ -0,0 +1,105 @@
+// A custom admin PANEL — a project's own React screen, rendered inside the editor's chrome
+// at a real route with a real nav entry.
+//
+// WHY A SECOND KIND, WHEN `adminPage()` EXISTS
+//
+// Block Kit (`adminPage()`) is a server-driven vocabulary: the handler returns JSON, the
+// editor renders it, and the whole page comes back on every interaction. That is exactly
+// right for a list-and-form screen, and it is the reason no project JavaScript runs in the
+// admin. But the properties that make it safe are the same ones that cap it — an input
+// cannot fire an interaction, every control is disabled for the round trip (so focus and
+// caret are lost on each keystroke that matters), a table row cannot expand, and there is
+// no link, no redirect, no dialog, no autofocus and no date input. Those are not gaps to
+// patch one element at a time; a screen that needs local interaction needs local code.
+//
+// The alternative a project reaches for when Block Kit runs out is what this replaces: a
+// standalone React SPA served next to the editor with the chrome rebuilt by hand. It goes
+// out of the application, it does not have the same layout, and every chrome fix has to be
+// made twice.
+//
+// So a panel is the SAME registry entry as a Block Kit page with the render moved to the
+// browser. Same slug space, same `/apps/:slug` route, same "Apps" band in the nav, and —
+// the part that matters — the same server-side role filter: a panel the caller may not open
+// is absent from `listAdminPages`, so there is no nav entry to click and no route to reach.
+//
+// WHAT LIVES WHERE. The server owns everything a nav entry is made of (slug, label, icon,
+// position, roles); the browser bundle owns only the component. That split is deliberate:
+// if the bundle declared the label and the position, a client that failed to load would
+// take the nav entry with it, and a client that loaded would be declaring its own placement
+// with nothing to check it against. A panel whose bundle never registers is a listed entry
+// that renders a diagnostic — which is a legible failure — rather than a section that
+// silently ceases to exist.
+//
+// WHAT IS GIVEN UP. Block Kit's headline property is that no project JavaScript ever runs in
+// the admin (#33). A panel gives that up, deliberately and only where a deployment asks for
+// it: the bundle runs in the editor's own page with the editor's own session in scope, so it
+// can read the stored token and call anything the caller can. `roles` below and the ACL still
+// bound what the SERVER will do, and `PanelApi` is a small surface to write against, but
+// neither is a sandbox — a panel is part of the admin, not a guest in it. That is the reason
+// `adminPage()` remains the first thing to reach for and this the second.
+//
+// The same reconciliation is written from the other side at the top of `blockkit.ts` — why
+// "do not ship the component tree" and this are one position rather than two, and which of
+// the pair to reach for first. Read together; changing one without the other leaves the
+// framework arguing with itself.
+//
+// A LEAF module, like `href.ts` and `nav.ts`: `blockkit.ts` imports it to widen the
+// registry, and it imports nothing back.
+
+/** One custom admin panel: a nav entry the browser bundle fills in.
+ *
+ * There is no `render` here and there is not meant to be one — the rendering half is a
+ * React component the deployment's panel bundle registers under the same `slug`. Everything
+ * that decides whether the entry EXISTS is here, on the server, where it can be enforced.
+ */
+export interface AdminPanelDef {
+  /** Discriminates a panel from an `AdminPageDef` in the one registry they share. Set by
+   * {@link adminPanel}; it is a required field rather than an inferred one so a hand-built
+   * object literal cannot be a half-declared panel. */
+  readonly kind: "panel";
+  /** URL + registry key: served at `/apps/:slug` in the editor, and the id the browser
+   * bundle registers its component under. */
+  readonly slug: string;
+  /** Nav label. */
+  readonly label: string;
+  /** Optional nav icon (emoji or short string). */
+  readonly icon?: string;
+  /** Where it sits in the nav — see `NAV_ORDER`. Defaults to `NAV_ORDER.adminPages`. */
+  readonly navOrder?: number;
+  /** Roles that may open it. Defaults to the deployment's `editorRoles`, exactly as a Block
+   * Kit page's does — one registry, one gate.
+   *
+   * This is the ONLY authorization a panel gets for free. A panel's own code runs in the
+   * browser, so every call it makes is an ordinary RPC under the caller's own identity and
+   * ACL; this list decides who is shown the screen, not what the screen may do. */
+  readonly roles?: readonly string[];
+}
+
+/**
+ * Declare a custom admin panel. Spread the result into `createAdminPageHandlers` alongside
+ * any `adminPage()`s:
+ *
+ *   const curation = adminPanel("curation", {
+ *     label: "Curation",
+ *     icon: "🎛",
+ *     navOrder: NAV_ORDER.media + 10,
+ *     roles: ["editor", "admin"],
+ *   });
+ *
+ *   handlers = { ...createAdminPageHandlers([desk, curation], { editorRoles }) };
+ *
+ * The matching component is registered by the deployment's panel bundle — see the
+ * "Custom admin panels" section of the CMS docs.
+ */
+export function adminPanel(slug: string, opts: Omit<AdminPanelDef, "slug" | "kind">): AdminPanelDef {
+  return { ...opts, kind: "panel", slug };
+}
+
+/** Whether a registry entry is a panel (and so has no server-side render).
+ *
+ * Reads the discriminant rather than testing for the ABSENCE of `render`: "no render" is
+ * also what a malformed page looks like, and `validateAdminPages` has to be able to tell a
+ * panel from a page someone forgot to finish. */
+export function isAdminPanel(def: { readonly kind?: string }): def is AdminPanelDef {
+  return def.kind === "panel";
+}