@pramen/cms 0.0.61 → 0.0.64

package/README.md

@@ -126,6 +126,34 @@ entry, so doing it there made the returned array stop matching the `as const` li
   the tenant's `media/` prefix); the client PUTs the bytes, then `createMedia({ ref, alt? })`
   confirms the blob is in R2 and persists a `cms_media` row. `listMedia`/`getMedia`/`deleteMedia`
   (deleteMedia also removes the R2 blob) round it out. Editor-gated.
+- **Browsing:** `listMedia({ limit, offset, q?, sort?, kind?, term? })`. `q` matches the filename **or**
+  the alt text (case-insensitive; a `%` or `_` in the needle is a literal), `sort` is one of
+  `newest`/`oldest`/`name`/`name_desc`/`largest`/`smallest`, and `kind` narrows to
+  `image`/`video`/`audio`/`document`/`other`. All three are applied in SQL rather than to the
+  page that arrived, so they mean what they say on a library larger than one page. `sort` and
+  `kind` are closed vocabularies — a caller never names a column — and an unrecognised value
+  falls back to the default instead of erroring.
+
+  This is what `cms_media.filename`/`contentType`/`size` are for: `file` is a `fileRef` (JSON in
+  a TEXT cell), which `orderBy` and `where` cannot see into, so the three fields the library
+  queries by are projected onto indexed columns when a row is created. **Spread `cmsMigrations`
+  into `app.migrations`** to backfill rows written before those columns existed — without it
+  they keep NULL, sort together under a name sort, and answer only the `other` filter.
+- **Tagging:** files carry taxonomy terms from the same `cms_taxonomies`/`cms_terms` tables pages
+  use, through a `cms_media_terms` junction — one vocabulary, edited in one place, applied to
+  whichever of the two it declares. A vocabulary carries **`appliesTo`** — `["page"]`,
+  `["media"]`, both, or `null` for everything (which is what an un-narrowed one, and every row
+  written before the column existed, means). `listTaxonomies({ target })` narrows to it, and
+  `setPageTerms`/`setMediaTerms` REFUSE a term from a vocabulary that does not apply, so it is a
+  rule rather than a UI hint. Narrowing a vocabulary away from something it is still assigned to
+  is refused too — those assignments would stay stored and stop being reachable from the panel
+  that could remove them. `listMediaTerms({ mediaId })` reads a file's terms and `setMediaTerms({ mediaId, termIds })`
+  replaces them wholesale (set semantics, like `setPageTerms`); `listMedia({ term })` filters by
+  one, ANDed with `kind` and `q`. The filter is a relation traversal compiled to a subquery, so
+  it narrows in SQL like every other option here. Deleting a term takes its assignments with it
+  (a real `ON DELETE CASCADE`), and trashing a file does NOT — only `purgeMedia` does, so a
+  restored file keeps its tags. Declared to the editor as
+  `listCmsCapabilities().mediaTerms`.
 - **Reference from a block:** a `"media"` field stores a `cms_media` id. At assemble/publish time
   the id is resolved (recursively, through group/repeater nesting) to a `ResolvedMedia`
   `{ id, key, url, alt, contentType, filename }` in the snapshot — so the content API returns a
@@ -195,6 +223,12 @@ authorization. Spread `cmsRoutes()` into `app.routes` to serve `GET /cms/preview
 verifies the token in the Worker before any read and returns the live draft with
 `isPreview: true` and `Cache-Control: private, no-store`.
 
+That route answers with **JSON** — this CMS is headless, so it has the draft and no idea what
+it should look like. Your site renders it: redeem the same token with `client.getPreview(token)`
+(`@pramen/cms-astro`) from a route of your own, through the same components the published page
+uses, and point the editor's Preview link button at it with `admin.previewUrl`. A working one
+is `example/site/src/pages/preview.astro`.
+
 If you pass custom roles to `createCmsHandlers`, hand `cmsRoutes` the **same options
 object** — it derives the route's identity from them, so the two cannot drift:
 

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