@pramen/cms 0.0.59 → 0.0.61

package/dist/index.js

@@ -24,8 +24,9 @@
 //   const acl = [ role("anonymous", [...cmsPolicies().public]),
 //                 role("editor",    [...cmsPolicies().editor]) ];
 //   const app = { schema, handlers, acl, tasks: { ...cmsTasks } };
-import { Entity, query, mutation, primaryKey, generated, notNull, unique, indexed, defaultTo, expr, policy, allow, $now, partitionOf, DEFAULT_PARTITION, BadRequest, Forbidden, PramenError, Conflict, signToken, verifyToken, resolveSecret, } from "@pramen/server";
+import { Entity, query, mutation, primaryKey, generated, notNull, unique, indexed, defaultTo, expr, policy, allow, $now, partitionOf, DEFAULT_PARTITION, BadRequest, Forbidden, PramenError, Conflict, signToken, verifyToken, resolveSecret, authorizeHandler, } from "@pramen/server";
 import { isSafeHref, normalizeHref } from "./href";
+import { NAV_ORDER } from "./nav";
 /** Declare a typed block type. Pass `fields as const` to preserve the literals so
  * `BlockFieldsOf<typeof def>` infers the field shape:
  *
@@ -38,6 +39,15 @@ import { isSafeHref, normalizeHref } from "./href";
  * Spread `hero` (minus fieldsSchema key naming) into `createBlockType`, and use
  * `BlockFieldsOf<typeof hero>` to type the block's React component. */
 export function defineBlockType(slug, fields, opts = {}) {
+    // A PURE constructor: it returns exactly what it was given, so `fieldsSchema` really is
+    // `F` and `BlockFieldsOf<typeof def>` describes the array that will be stored. Validation
+    // deliberately does NOT live here — it lives in `cmsBootstrap`, the thing that writes.
+    // `BlockTypeDef` is a structural interface, so an object literal, a `.map` or a codegen
+    // step reaches the store without passing through this function at all; checking here would
+    // have guarded the convenient path and left the sink open. Canonicalizing here was worse
+    // still: `validateFieldSchema` REBUILDS every entry (trimming names, dropping type-inert
+    // keys), so the returned array stopped matching the const literal `F` is inferred from and
+    // the cast became a lie a component would follow into `fields["  title  "] === undefined`.
     return { slug, name: opts.name ?? slug, fieldsSchema: fields, description: opts.description, icon: opts.icon, category: opts.category };
 }
 /** Declare a content type in code. Spread the result into `cmsBootstrap({ contentTypes })`:
@@ -48,17 +58,108 @@ export function defineBlockType(slug, fields, opts = {}) {
  *     regions: [{ name: "content", allowedTypes: ["rich_text", "image"] }],
  *   }); */
 export function defineContentType(slug, opts) {
+    // Pure, for the same reason as `defineBlockType` — `cmsBootstrap` validates.
     return { slug, name: opts.name ?? slug, description: opts.description, fields: opts.fields, regions: opts.regions, defaultBlocks: opts.defaultBlocks };
 }
 const sameJson = (a, b) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+/** The default `owner` — see {@link cmsBootstrap}. */
+export const CMS_BOOTSTRAP_OWNER = "cms";
+/**
+ * Validate + canonicalize what a `cmsBootstrap` will write, at FACTORY-call time.
+ *
+ * This lives here rather than in `defineBlockType`/`defineContentType` because those are
+ * optional conveniences: `BlockTypeDef`/`ContentTypeDef` are exported STRUCTURAL interfaces,
+ * so an object literal, a `.map` over a config file or a codegen step reaches `upsertBySlug`
+ * without passing through either helper. Checking in the helper guarded the convenient path
+ * and left the sink open — and the row it wrote was then locked `managedBy`, so an invalid
+ * schema could never be repaired through the product. `cmsBootstrap(defs)` is the one call
+ * every code-defined type goes through.
+ *
+ * Held to the SAME rules the editor's `createBlockType`/`createContentType` enforce
+ * (`normalizeFieldSchema`, `normalizeRegions`, `normalizeDefaultBlocks`), because the
+ * alternative is a code-declared type storing a schema the builder then refuses to save —
+ * the only surface reporting the problem being the one that cannot fix it.
+ *
+ * EVERY problem is reported together, not just the first: this throws at app construction
+ * (`app.ts` module scope, like `validateCollections` in `createCollectionHandlers` and
+ * `validateMigrations` in `createPramen`), where fixing them one deploy at a time is the
+ * difference between one round trip and six.
+ */
+function validateCmsDefinitions(defs) {
+    const problems = [];
+    const at = (what, slug, e) => {
+        problems.push(`  ${what} ${JSON.stringify(slug)}: ${e instanceof Error ? e.message : String(e)}`);
+    };
+    const blockTypes = [];
+    const btSeen = new Set();
+    for (const bt of defs.blockTypes ?? []) {
+        try {
+            const slug = assertRegistryKey(bt.slug, "block type slug");
+            // Last-wins on a repeated slug is how two feature modules both exporting a `cta` block
+            // type converge to whichever import order won, with nothing said about it.
+            if (btSeen.has(slug))
+                throw new BadRequest(`declared twice — the second declaration would silently overwrite the first`);
+            btSeen.add(slug);
+            blockTypes.push({
+                name: assertLabel(bt.name ?? slug, "block type name"),
+                slug,
+                description: bt.description ?? null,
+                fieldsSchema: normalizeFieldSchema(bt.fieldsSchema, "fieldsSchema"),
+                icon: bt.icon ?? null,
+                category: bt.category ?? null,
+            });
+        }
+        catch (e) {
+            at("block type", bt.slug, e);
+        }
+    }
+    const contentTypes = [];
+    const ctSeen = new Set();
+    for (const ct of defs.contentTypes ?? []) {
+        try {
+            // The slug FIRST: it is what every other message names, and validating regions ahead
+            // of it produced an error that never mentioned the type whose slug was also wrong —
+            // fix the regions, redeploy, meet the second failure.
+            const slug = assertRegistryKey(ct.slug, "content type slug");
+            if (ctSeen.has(slug))
+                throw new BadRequest(`declared twice — the second declaration would silently overwrite the first`);
+            ctSeen.add(slug);
+            const regions = normalizeRegions(ct.regions);
+            contentTypes.push({
+                name: assertLabel(ct.name ?? slug, "content type name"),
+                slug,
+                description: ct.description ?? null,
+                fieldsSchema: normalizeFieldSchema(ct.fields, "fields"),
+                regions,
+                defaultBlocks: normalizeDefaultBlocks(ct.defaultBlocks, regions),
+            });
+        }
+        catch (e) {
+            at("content type", ct.slug, e);
+        }
+    }
+    if (problems.length > 0) {
+        throw new Error(`cmsBootstrap: ${problems.length} invalid type definition(s)\n${problems.join("\n")}`);
+    }
+    return { blockTypes, contentTypes };
+}
 /** Insert `values` if no row has this `slug`, else patch only the columns that drifted
- * (never `id`/`slug`/`createdAt`). Idempotent — an identical definition is a no-op. */
-async function upsertBySlug(db, table, slug, values) {
+ * (never `id`/`slug`/`createdAt`). Idempotent — an identical definition is a no-op.
+ *
+ * Returns false, having written NOTHING, when the existing row belongs to someone else —
+ * an editor-authored type (`managedBy` null) or another reconciler's. Adopting it was a
+ * silent takeover: name and schema replaced by the code literal, and then the row locked, so
+ * the editor could not even put back what it had just lost. `createBlockType` refuses this
+ * exact slug collision at the RPC edge; the reconciler used to win it without a word. */
+async function upsertBySlug(db, table, owner, values) {
+    const slug = String(values.slug);
     const existing = (await db.find({ from: table, where: { slug }, limit: 1 }))[0];
     if (!existing) {
-        await db.insert(table, values);
-        return;
+        await db.insert(table, { ...values, managedBy: owner });
+        return true;
     }
+    if (existing.managedBy !== owner)
+        return false;
     const patch = {};
     for (const [k, v] of Object.entries(values)) {
         if (k === "slug")
@@ -68,6 +169,28 @@ async function upsertBySlug(db, table, slug, values) {
     }
     if (Object.keys(patch).length)
         await db.update(table, String(existing.id), patch);
+    return true;
+}
+/** Release the rows THIS owner wrote and no longer declares.
+ *
+ * A type dropped from the repo keeps its row — pages are still built out of it — but nothing
+ * converges it any more, so leaving it read-only in the builder would be a lock with nothing
+ * behind it, next to a note pointing at code that no longer mentions it.
+ *
+ * Scoped to `managedBy = owner`, which is what makes `cmsBootstrap` composable: a sweep
+ * cannot otherwise tell "not mine" from "no longer declared", so two reconcilers in one
+ * `app.bootstrap` released each other's rows on every boot and half the types silently fell
+ * back to editable. A table the call says nothing about (`blockTypes` absent — the KEY, not
+ * an empty array) is left alone rather than swept. */
+async function releaseUndeclared(db, table, owner, declared) {
+    // `select` because this runs on the boot critical path — inside `blockConcurrencyWhile` on
+    // a DO's first fetch, and at every isolate init on D1 where each statement is a round trip.
+    // Without it the read pulls and JSON-parses every row's whole field schema to look at two
+    // columns (the GitHub #22 shape).
+    for (const row of await db.find({ from: table, where: { managedBy: owner }, select: ["id", "slug"] })) {
+        if (!declared.has(String(row.slug)))
+            await db.update(table, String(row.id), { managedBy: null });
+    }
 }
 /** Build a pramen `bootstrap` reconciler that upserts code-defined block + content types by
  * `slug` on each boot. Idempotent: inserts a missing type, updates a drifted one, leaves an
@@ -77,30 +200,51 @@ async function upsertBySlug(db, table, slug, values) {
  *     bootstrap: [ cmsBootstrap({ blockTypes: [...], contentTypes: [...] }) ] };
  *
  * Runs with a privileged system Db, so a fresh/reprovisioned database converges to the
- * code-declared types with no manual createContentType/createBlockType call. */
-export function cmsBootstrap(defs) {
+ * code-declared types with no manual createContentType/createBlockType call.
+ *
+ * Every row it writes is stamped `managedBy: owner`, which makes the editor show it
+ * read-only — convergence and an editor pointed at the same rows are otherwise a silent
+ * data-loss pair (GitHub #48). A type that drops out of the declaration is released back to
+ * the editor; a row this owner did not write is never touched, so a second reconciler (a
+ * package shipping its own block types, say) composes as long as it passes its own `owner`.
+ *
+ * The definitions are validated HERE, when the app is constructed, and every problem is
+ * reported at once — see {@link validateCmsDefinitions}. */
+export function cmsBootstrap(defs, opts = {}) {
+    const owner = opts.owner ?? CMS_BOOTSTRAP_OWNER;
+    const { blockTypes, contentTypes } = validateCmsDefinitions(defs);
+    // Presence of the KEY, not truthiness of the array: `blockTypes: []` is "I declare none",
+    // which must sweep, while an absent key is "I say nothing about block types", which must
+    // not. Truthiness read `[]` as the latter four lines after `?? []` read it as the former,
+    // and the difference was invisible at the call site — `features.flatMap(f => f.blockTypes)`
+    // on an empty list silently unlocked every code-defined type in every tenant.
+    const sweepBlockTypes = "blockTypes" in defs;
+    const sweepContentTypes = "contentTypes" in defs;
     return async ({ db }) => {
         const sys = db;
-        for (const bt of defs.blockTypes ?? []) {
-            await upsertBySlug(sys, "cms_block_types", bt.slug, {
-                name: bt.name,
-                slug: bt.slug,
-                description: bt.description ?? null,
-                fieldsSchema: bt.fieldsSchema ?? [],
-                icon: bt.icon ?? null,
-                category: bt.category ?? null,
-            });
-        }
-        for (const ct of defs.contentTypes ?? []) {
-            await upsertBySlug(sys, "cms_content_types", ct.slug, {
-                name: ct.name,
-                slug: ct.slug,
-                description: ct.description ?? null,
-                fieldsSchema: ct.fields ?? [],
-                regions: ct.regions ?? [],
-                defaultBlocks: ct.defaultBlocks ?? [],
-            });
-        }
+        // Per-definition, so one failure does not skip every later type AND both sweeps. The
+        // boot runner only logs a throwing reconciler, so an aborted pass leaves the store half
+        // converged for that isolate's whole lifetime with nothing to retry it. A UNIQUE
+        // violation is the expected instance: `app.bootstrap` has no lease, and on D1 two cold
+        // isolates can both find a slug missing and both insert it.
+        const reconcile = async (table, values) => {
+            try {
+                if (!(await upsertBySlug(sys, table, owner, values))) {
+                    console.warn(`@pramen/cms: ${table}.${String(values.slug)} already exists and is not owned by '${owner}' — leaving it alone (code-defined types cannot take over a row someone else authored)`);
+                }
+            }
+            catch (e) {
+                console.error(`@pramen/cms: failed to reconcile ${table}.${String(values.slug)}:`, e);
+            }
+        };
+        for (const bt of blockTypes)
+            await reconcile("cms_block_types", bt);
+        if (sweepBlockTypes)
+            await releaseUndeclared(sys, "cms_block_types", owner, new Set(blockTypes.map((bt) => String(bt.slug))));
+        for (const ct of contentTypes)
+            await reconcile("cms_content_types", ct);
+        if (sweepContentTypes)
+            await releaseUndeclared(sys, "cms_content_types", owner, new Set(contentTypes.map((ct) => String(ct.slug))));
     };
 }
 // --- codegen: emit .ts field interfaces from DB-stored block schemas ------------------
@@ -129,6 +273,9 @@ function tsTypeOf(f) {
             return "boolean";
         case "media":
             return "ResolvedMedia | null";
+        // An opaque id — the record it points at may not be ours to type.
+        case "reference":
+            return f.multiple ? "string[]" : "string";
         case "group":
             return `{ ${(f.fields ?? []).map(tsFieldLine).join(" ")} }`;
         case "repeater":
@@ -199,9 +346,21 @@ export function generateBlockTypes(blockTypes) {
     const importLine = used.length ? `import type { ${used.join(", ")} } from "@pramen/cms";\n\n` : "";
     return `// AUTO-GENERATED by @pramen/cms — do not edit.\n${importLine}${interfaces}\n\nexport interface BlockFieldsBySlug {\n${registry}\n}\n`;
 }
-// --- schema fragment: spread into your defineSchema so the tables migrate --------
-/** The block/page builder tables. All in the default partition (relations can't cross
- * partitions). Prefixed `cms_` to avoid colliding with your own entities. */
+/** How deep a menu tree may nest. Menus are stored as one document, so without a cap a
+ * client could post a tree deep enough to blow the stack in the resolver — and no real
+ * navigation is more than three levels anyway. */
+export const MAX_MENU_DEPTH = 5;
+/** How many items one menu may hold, at every level combined.
+ *
+ * Depth alone is not a bound: a FLAT list of 800 `page` items is legal under
+ * `MAX_MENU_DEPTH` and turns every anonymous `getMenu` — the read on every page render of
+ * the site — into a single `WHERE id IN (?×800)`, which the read engine emits with no
+ * chunking. Every other read added alongside this one is bounded (`MAX_TERMS`,
+ * `clampLimit`); this one was not, and it is the one on the hot path. */
+export const MAX_MENU_ITEMS = 200;
+/** How deep a term hierarchy may nest — the same argument as {@link MAX_MENU_DEPTH}, except
+ * here the tree is rows and the risk is a parent CYCLE, which `assertTermParent` refuses. */
+export const MAX_TERM_DEPTH = 5;
 export const cmsSchema = {
     cms_content_types: Entity((t) => ({
         id: primaryKey(generated(t.uuid())),
@@ -211,6 +370,8 @@ export const cmsSchema = {
         fieldsSchema: t.json(), // FieldDefinition[] for page-level fields
         regions: t.json(), // RegionDefinition[]
         defaultBlocks: t.json(), // DefaultBlockDefinition[]
+        // Which reconciler owns this row. See cms_block_types.managedBy.
+        managedBy: t.text(),
         createdAt: defaultTo(t.text(), expr.now()),
     })),
     cms_block_types: Entity((t) => ({
@@ -221,6 +382,21 @@ export const cmsSchema = {
         fieldsSchema: t.json(), // FieldDefinition[]
         icon: t.text(),
         category: t.text(),
+        // NON-NULL while this row is CODE-DEFINED, holding the OWNER id of the `cmsBootstrap`
+        // that declares it. The editor authors these rows too (GitHub #9), and the two were
+        // otherwise indistinguishable: an editor would add a field, get a 200, and lose it
+        // silently at the next cold start when `upsertBySlug` patched the column back to the
+        // literal in `app.ts`. So it is set by the reconciler, refused by `updateBlockType` /
+        // `updateContentType`, and rendered read-only in the builder. Cleared again when the
+        // definition leaves the repo — a lock with nothing behind it is worse than no lock.
+        //
+        // An OWNER id rather than a boolean because `app.bootstrap` is a composable array. With
+        // a flag, two `cmsBootstrap` calls each released the other's rows on every boot: the
+        // sweep cannot tell "this row is not mine" from "this row is no longer declared", so
+        // half the types silently fell back to editable and #48 came straight back for them. A
+        // reconciler now only releases what IT wrote, which is also what lets a package ship its
+        // own block types beside the app's.
+        managedBy: t.text(),
         createdAt: defaultTo(t.text(), expr.now()),
     })),
     cms_blocks: Entity((t) => ({
@@ -261,7 +437,8 @@ export const cmsSchema = {
         unpublishAt: t.text(),
         // The revision the public content API serves — set on publish. A direct pointer
         // (not "latest by timestamp") so selection is deterministic even when two publishes
-        // land in the same second (expr.now() is second-precision).
+        // land in the same instant. `expr.now()` carries milliseconds now, which narrows the
+        // window without closing it — a pointer has no window at all.
         currentRevisionId: t.uuid(),
         // Soft delete: the epoch-ISO instant the page was trashed, NULL while it is live.
         // Every read scope AND-merges `deletedAt IS NULL` (see cmsPolicies), so a trashed
@@ -284,6 +461,10 @@ export const cmsSchema = {
     }), (r) => ({
         type: r.belongsTo("cms_content_types", "typeId"),
         placements: r.hasMany("cms_page_blocks", "pageId"),
+        // Taxonomy terms, through the explicit junction. `where: { terms: { slug: "news" } }`
+        // compiles to a nested subquery, so "pages in this category" is an ordinary query and
+        // not a second handler.
+        terms: r.manyToMany("cms_terms", { through: "cms_page_terms", sourceColumn: "pageId", targetColumn: "termId" }),
     }), { unique: [["slug", "locale"]] }),
     cms_page_blocks: Entity((t) => ({
         id: primaryKey(generated(t.uuid())),
@@ -337,11 +518,11 @@ export const cmsSchema = {
         collection: indexed(notNull(t.text())),
         rowId: indexed(notNull(t.text())),
         // A monotonic per-row counter, and the ONLY ordering key. Timestamps cannot do this
-        // job: `expr.now()` is second-resolution and even an ISO ms stamp collides, because a
-        // collection revision is written on EVERY edit and two writes land in the same
-        // millisecond often enough to be reproducible. Ordering then falls to a uuid tiebreak,
-        // which is deterministic but NOT insertion order — so "restore the previous version"
-        // could pick the wrong snapshot.
+        // job even at millisecond resolution: a collection revision is written on EVERY edit,
+        // and two writes land in the same millisecond often enough to be reproducible. Ordering
+        // then falls to a uuid tiebreak, which is deterministic but NOT insertion order — so
+        // "restore the previous version" could pick the wrong snapshot. (`expr.now()` was also
+        // second-resolution when this was written, which made the same point louder.)
         //
         // The read-then-increment in `snapshotRow` is serialized by the DO's single writer. On
         // the D1 store it is NOT — `D1Driver.transaction` is a no-op (D1 has no interactive
@@ -352,13 +533,133 @@ export const cmsSchema = {
         snapshot: t.json(),
         note: t.text(),
         actor: t.text(),
-        // NO expr.now() default. `snapshotRow` is the only writer and stamps this itself with
-        // ISO-8601 ms precision, because unlike cms_page_revisions (written only on publish) a
-        // collection revision is written on EVERY edit — an autosave followed immediately by a
-        // publish lands two rows in the same second, and `datetime('now')` (second resolution)
-        // would make "the previous version" an arbitrary pick between them.
+        // NO expr.now() default: `snapshotRow` is the only writer and stamps it. That is now a
+        // consistency choice rather than a precision one — `expr.now()` carries milliseconds
+        // too — but `revision` above is what actually orders these rows, and a column no
+        // writer but `snapshotRow` touches cannot drift from it.
         createdAt: t.text(),
     }), undefined, { unique: [["collection", "rowId", "revision"]] }),
+    // --- site furniture: menus, redirects, taxonomies, widget areas ------------------
+    //
+    // The WordPress-parity furniture every client project reinvents by hand. All four are
+    // SITE-level, not page-level: they exist once per deployment and are read by the layout,
+    // not by a page's regions.
+    // A named navigation menu. `items` is a nested `MenuItem[]` document rather than a rows
+    // table, because a menu is edited and read WHOLE — every read is `getMenu("primary")`,
+    // and every write is "here is the new tree". Rows would buy per-item queries nobody makes
+    // and cost a recursive assemble on the one read that matters. The tree is depth-capped on
+    // write (`MAX_MENU_DEPTH`), which is the constraint a rows table would have got for free.
+    cms_menus: Entity((t) => ({
+        id: primaryKey(generated(t.uuid())),
+        // The key `getMenu(name)` resolves — stable, referenced from layout code, and so NOT
+        // renameable through `updateMenu` (the label is what an editor retitles).
+        name: unique(notNull(t.text())),
+        label: notNull(t.text()),
+        items: t.json(), // MenuItem[]
+        // Optimistic concurrency, as on cms_pages/cms_blocks. It matters MORE here, not less:
+        // `updateMenu` writes the whole `items` document, so two editors on one menu meant the
+        // second silently replaced the first's entire tree — where a page edit at least
+        // conflicts per field.
+        version: defaultTo(t.int(), 1),
+        createdAt: defaultTo(t.text(), expr.now()),
+        updatedAt: defaultTo(t.text(), expr.now()),
+    })),
+    // A URL redirect. Needed the moment a slug changes on a live site — which the `slug`
+    // field's own docs already flag ("silently rewriting a slug changes a live URL and breaks
+    // every link to it").
+    //
+    // `fromPath`/`toPath`, not `from`/`to`: `from` is a SQL keyword, and while the dialect
+    // quotes every identifier, a column named `from` also collides with the `find({ from })`
+    // query key — a `where: { from: ... }` reads as a table reference to anyone skimming.
+    cms_redirects: Entity((t) => ({
+        id: primaryKey(generated(t.uuid())),
+        // Unique because resolution is an exact lookup: two rows for one path is a coin flip
+        // over which redirect a visitor gets, and the DB is the only place that can refuse it.
+        fromPath: unique(notNull(t.text())),
+        toPath: notNull(t.text()),
+        // 301 (permanent) or 302 (temporary). INT, and constrained on write — a redirect status
+        // is not free-form, and a typo here is a broken response, not a broken page.
+        status: defaultTo(t.int(), 301),
+        // Off-switch that keeps the row. A redirect is usually disabled to TEST whether it is
+        // still needed; deleting it loses the record of what the old URL was.
+        enabled: defaultTo(t.bool(), true),
+        note: t.text(),
+        createdAt: defaultTo(t.text(), expr.now()),
+        updatedAt: defaultTo(t.text(), expr.now()),
+    })),
+    // NOTE: deliberately no hit counter. Counting would make `resolveRedirect` — the one
+    // handler anonymous traffic calls on every 404 — a WRITE, which is an unauthenticated
+    // row mutation on the hot path and, on the DO, a transaction per miss. Redirect usage
+    // belongs in the edge's own logs.
+    // A classification vocabulary: `category` (hierarchical) and `tag` (flat) are just two
+    // rows here, which is why there is no built-in of either — a deployment declares what it
+    // classifies by, the same way it declares its content types.
+    cms_taxonomies: Entity((t) => ({
+        id: primaryKey(generated(t.uuid())),
+        slug: unique(notNull(t.text())),
+        label: notNull(t.text()),
+        pluralLabel: t.text(),
+        description: t.text(),
+        // Hierarchical vocabularies allow `parentId` on their terms; flat ones reject it on
+        // write. Enforced in the handler, not the schema — one term table serves both.
+        hierarchical: defaultTo(t.bool(), false),
+        createdAt: defaultTo(t.text(), expr.now()),
+    })),
+    cms_terms: Entity((t) => ({
+        id: primaryKey(generated(t.uuid())),
+        taxonomyId: indexed(notNull(t.uuid())),
+        slug: notNull(t.text()),
+        label: notNull(t.text()),
+        description: t.text(),
+        // Self-referential, and a REAL FK: deleting a parent term must not leave children
+        // pointing at a row that is gone (the front end would render an orphan branch that
+        // no listing can reach). `setNull` promotes them to the top level instead, which is
+        // the only non-destructive answer — `cascade` would silently delete a subtree.
+        parentId: t.uuid(),
+        position: defaultTo(t.int(), 0),
+        createdAt: defaultTo(t.text(), expr.now()),
+    }), (r) => ({
+        taxonomy: r.belongsTo("cms_taxonomies", "taxonomyId", { onDelete: "cascade" }),
+        parent: r.belongsTo("cms_terms", "parentId", { onDelete: "setNull" }),
+        pages: r.hasMany("cms_page_terms", "termId"),
+    }), 
+    // A slug identifies a term WITHIN its vocabulary — `/category/news` and `/tag/news`
+    // are two different terms, and both are legitimate.
+    { unique: [["taxonomyId", "slug"]] }),
+    // The term-assignment junction — an EXPLICIT entity, which is what `manyToMany` means
+    // here: `ctx.db.insert("cms_page_terms", …)` links, `delete` unlinks, and `where`
+    // traverses it as a nested subquery. No synthetic table, no write API to learn.
+    cms_page_terms: Entity((t) => ({
+        id: primaryKey(generated(t.uuid())),
+        pageId: indexed(notNull(t.uuid())),
+        termId: indexed(notNull(t.uuid())),
+    }), (r) => ({
+        page: r.belongsTo("cms_pages", "pageId", { onDelete: "cascade" }),
+        term: r.belongsTo("cms_terms", "termId", { onDelete: "cascade" }),
+    }), 
+    // One assignment per (page, term). Without it a double-submit leaves a page tagged
+    // twice and every `with: { terms: true }` renders the term twice.
+    { unique: [["pageId", "termId"]] }),
+    // A named template region an admin fills without touching code — the sidebar, the footer
+    // column, the pre-footer strip.
+    //
+    // Kept as its own entity rather than a page-less `cms_blocks` region, which was the
+    // tempting reuse. A block placement is `(pageId, region, position)` with `pageId` NOT
+    // NULL: making it nullable to model "belongs to no page" would put a null branch through
+    // every placement read, every region assemble and every page-scoped ACL clause, to model
+    // something that shares no field with a page (no slug, no status, no revisions, no
+    // workflow). A widget area is a small ordered document, and that is what it is stored as.
+    cms_widget_areas: Entity((t) => ({
+        id: primaryKey(generated(t.uuid())),
+        name: unique(notNull(t.text())),
+        label: notNull(t.text()),
+        description: t.text(),
+        widgets: t.json(), // Widget[]
+        // Same argument as cms_menus.version — `updateWidgetArea` replaces the whole list.
+        version: defaultTo(t.int(), 1),
+        createdAt: defaultTo(t.text(), expr.now()),
+        updatedAt: defaultTo(t.text(), expr.now()),
+    })),
     // Media: a fileRef column holds only R2 metadata; bytes live in R2, uploaded via
     // ctx.files + the Worker /files/* route. Block `fields` reference a media id.
     cms_media: Entity((t) => ({
@@ -371,6 +672,29 @@ export const cmsSchema = {
         createdAt: defaultTo(t.text(), expr.now()),
     })),
 };
+/** 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";
+/**
+ * Columns this package wrote in the pre-ISO space form that the SCHEMA cannot identify.
+ *
+ * `isoTimestampBackfill()` finds every column whose DEFAULT is `expr.now()` on its own.
+ * `cms_pages.publishedAt` has no default at all — `doPublish` stamped it from handler code,
+ * in the same space form, to stay comparable with the `updatedAt` written beside it. There
+ * is nothing on that column to find, so it is named here.
+ *
+ * Spread it into the migration if your store was ever written by a build older than this
+ * one:
+ *
+ * ```ts
+ * migrations: [isoTimestampBackfill({ extraColumns: CMS_LEGACY_TIMESTAMP_COLUMNS })]
+ * ```
+ *
+ * Costs nothing on a store that was not — the UPDATE matches no rows.
+ */
+export const CMS_LEGACY_TIMESTAMP_COLUMNS = {
+    cms_pages: ["publishedAt"],
+};
 /** Validate a block/page's `fields` payload against a field schema, throwing a 400 on
  * the first violation. Recursive (repeater/group). Lenient on unknown field types. */
 /** A calendar date, `YYYY-MM-DD` (what an <input type="date"> emits) — must also parse. */
@@ -459,6 +783,22 @@ export function validateFields(schema, values, path = "", opts = {}) {
                 if (typeof v !== "string")
                     throw new BadRequest(`field '${at}' must be a media id (string)`);
                 break;
+            // An OPAQUE id: the record may live in another table, or in a system we do not own,
+            // so there is nothing to check it against here beyond its shape. The picker's
+            // `referenceFrom` handler is the authority on which ids exist, and it runs under the
+            // caller's own ACL — so validating against a list fetched here would be both a second
+            // round trip and a weaker check than the one the storing handler already makes.
+            case "reference":
+                if (def.multiple) {
+                    if (!Array.isArray(v))
+                        throw new BadRequest(`field '${at}' must be a list of ids`);
+                    if (v.some((id) => typeof id !== "string"))
+                        throw new BadRequest(`field '${at}' must be a list of ids (strings)`);
+                }
+                else if (typeof v !== "string") {
+                    throw new BadRequest(`field '${at}' must be an id (string)`);
+                }
+                break;
             case "group": {
                 // The baseline MUST descend. Stopping at the top level meant a pre-migration
                 // richtext value nested in a group was rejected on every write that echoed the
@@ -498,6 +838,216 @@ export function validateFields(schema, values, path = "", opts = {}) {
         }
     }
 }
+// --- validating an AUTHORED field schema -------------------------------------
+//
+// `validateFields` above checks a VALUE against a schema. This checks the SCHEMA itself.
+//
+// It did not exist while the only way to create a block type was a developer writing
+// `defineBlockType(...)` in the repo, where tsc is the check. Now that the editor authors
+// types (GitHub #9), `fieldsSchema` arrives from a browser as free JSON into a `t.json()`
+// column — and a malformed one is not caught anywhere downstream: `FieldForm` renders
+// `null` for an unknown type, `validateFields` skips it ("lenient on unknown field types"),
+// and the block silently loses that field's content on every save. A duplicate `name` is
+// worse: two controls write the same key, so one of them can never be saved at all.
+/** Every field type the runtime knows. Exported because the editor's type-builder offers
+ * exactly this list — one definition, so a type added here appears there without a second
+ * edit, and a type removed here cannot be authored. */
+export const FIELD_TYPES = [
+    "text", "textarea", "richtext", "url", "number", "boolean", "date", "datetime",
+    "publish", "slug", "media", "select", "reference", "repeater", "group",
+];
+/** Types whose `fields` nest a further schema. */
+const NESTING_TYPES = ["group", "repeater"];
+/** How deep an authored field schema may nest. A schema is rendered by a recursive
+ * component and validated by a recursive function, so the cap is what keeps both bounded
+ * against a hand-posted document; nothing real nests past two or three. */
+export const MAX_FIELD_DEPTH = 5;
+/** A field NAME is an object key in a `fields` bag and a property name in generated TS
+ * (`generateBlockTypes`), so it is held to what can be both. */
+const FIELD_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** A REGION name. Looser than a field name by one character, because the two are not the
+ * same kind of thing: a field name is emitted as a TS property by `generateBlockTypes`, so
+ * it must be an identifier, while a region name is only ever an object key on the assembled
+ * page (`regions["main-content"]`). Held to `FIELD_NAME` it rejected hyphenated names that
+ * pre-date this validation and are stored today — which would have made every future save
+ * of such a content type fail, with the only fix being a rename that orphans its
+ * placements. */
+const REGION_NAME = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+/**
+ * Validate and canonicalize an authored `FieldDefinition[]`, throwing a 400 on the first
+ * problem. Returns the CLEANED schema — each field rebuilt from the keys its type actually
+ * uses, so a `select`'s stale `options` cannot ride along on a field someone switched to
+ * `text` and reappear if they switch back.
+ */
+export function validateFieldSchema(raw, path = "fieldsSchema", depth = 0) {
+    if (raw == null)
+        return [];
+    if (!Array.isArray(raw))
+        throw new BadRequest(`${path} must be a list of field definitions`);
+    if (depth >= MAX_FIELD_DEPTH)
+        throw new BadRequest(`${path} nests deeper than ${MAX_FIELD_DEPTH} levels`);
+    const seen = new Set();
+    return raw.map((entry, i) => {
+        const o = asObj(entry);
+        const at = `${path}[${i}]`;
+        const name = typeof o.name === "string" ? o.name.trim() : "";
+        if (!FIELD_NAME.test(name)) {
+            throw new BadRequest(`${at}.name must be a field name (a letter or underscore, then letters/digits/underscores), got ${JSON.stringify(o.name)}`);
+        }
+        // Siblings only — a nested `group` legitimately reuses a name from the outer level,
+        // because it writes into its own bag.
+        if (seen.has(name))
+            throw new BadRequest(`${path} declares '${name}' twice — two controls would write the same key and one could never be saved`);
+        seen.add(name);
+        const type = o.type;
+        if (!FIELD_TYPES.includes(type)) {
+            throw new BadRequest(`${at}.type is '${String(o.type)}', which is not a field type (known: ${FIELD_TYPES.join(", ")})`);
+        }
+        const f = { name, type };
+        if (typeof o.label === "string" && o.label.trim() !== "")
+            f.label = o.label.trim();
+        if (o.required === true)
+            f.required = true;
+        if (o.default !== undefined)
+            f.default = o.default;
+        if (NESTING_TYPES.includes(type)) {
+            f.fields = validateFieldSchema(o.fields, `${at}.fields`, depth + 1);
+            // A `group` with no fields renders an empty box; a `repeater` with none renders rows
+            // of nothing and an Add button. Both are the shape of a half-finished edit, and both
+            // are silently useless rather than visibly wrong, so they are refused here.
+            if (f.fields.length === 0)
+                throw new BadRequest(`${at} is a '${type}' and needs at least one nested field`);
+            if (type === "repeater") {
+                if (typeof o.min === "number" && Number.isFinite(o.min))
+                    f.min = Math.max(0, Math.trunc(o.min));
+                if (typeof o.max === "number" && Number.isFinite(o.max))
+                    f.max = Math.max(1, Math.trunc(o.max));
+                if (f.min != null && f.max != null && f.min > f.max)
+                    throw new BadRequest(`${at} has min ${f.min} above max ${f.max}`);
+            }
+        }
+        else if (type === "select") {
+            // `optionsFrom` takes precedence at render time, so requiring options alongside it
+            // would reject the live-data case the option exists for.
+            if (typeof o.optionsFrom === "string" && o.optionsFrom.trim() !== "") {
+                f.optionsFrom = assertHandlerName(o.optionsFrom, `${at}.optionsFrom`);
+            }
+            else {
+                const options = Array.isArray(o.options) ? o.options.map((v) => String(v).trim()).filter((v) => v !== "") : [];
+                if (options.length === 0)
+                    throw new BadRequest(`${at} is a 'select' and needs either \`options\` or an \`optionsFrom\` handler`);
+                if (new Set(options).size !== options.length)
+                    throw new BadRequest(`${at} lists the same option twice`);
+                f.options = options;
+            }
+        }
+        else if (type === "slug") {
+            // `from` is optional (a slug typed by hand is legitimate), but naming a field that is
+            // not there is a control that silently never follows anything.
+            if (typeof o.from === "string" && o.from.trim() !== "")
+                f.from = o.from.trim();
+        }
+        else if (type === "reference") {
+            if (typeof o.referenceFrom !== "string" || o.referenceFrom.trim() === "") {
+                throw new BadRequest(`${at} is a 'reference' and needs a \`referenceFrom\` query handler`);
+            }
+            f.referenceFrom = assertHandlerName(o.referenceFrom, `${at}.referenceFrom`);
+            if (o.multiple === true)
+                f.multiple = true;
+        }
+        return f;
+    });
+}
+/** Resolve `slug` cross-references inside one schema, now that every sibling is known: a
+ * `slug` field's `from` must name a field that exists AT THE SAME LEVEL (the editor reads
+ * it out of the sibling bag) and holds text. Separate pass because forward references are
+ * legitimate — a slug may precede the title it follows. */
+export function checkSlugSources(schema, path = "fieldsSchema") {
+    const byName = new Map(schema.map((f) => [f.name, f]));
+    schema.forEach((f, i) => {
+        if (f.type === "slug" && f.from) {
+            const src = byName.get(f.from);
+            if (!src)
+                throw new BadRequest(`${path}[${i}] derives from '${f.from}', which is not a field alongside it`);
+            if (!["text", "textarea", "select", "url"].includes(src.type)) {
+                throw new BadRequest(`${path}[${i}] derives from '${f.from}', which is a '${src.type}' — a slug can only follow a text field`);
+            }
+        }
+        if (f.fields)
+            checkSlugSources(f.fields, `${path}[${i}].fields`);
+    });
+}
+/** Validate + canonicalize an authored field schema end to end. */
+export function normalizeFieldSchema(raw, path = "fieldsSchema") {
+    const schema = validateFieldSchema(raw, path);
+    checkSlugSources(schema, path);
+    return schema;
+}
+/**
+ * Validate a content type's `regions`.
+ *
+ * A region NAME is the key `addBlock({ region })` resolves and the key of the assembled
+ * `regions` object a front end reads, so it is held to the same shape as a field name. An
+ * `allowedTypes` entry is a block-type SLUG; it is not checked against the block types that
+ * exist, on purpose — a content type declaring a region for a block type that has not been
+ * created yet is an ordinary order of work, and `assertRegionAllows` is what enforces the
+ * list at placement time.
+ */
+export function normalizeRegions(raw) {
+    if (!Array.isArray(raw) || raw.length === 0)
+        throw new BadRequest("at least one region is required");
+    const seen = new Set();
+    return raw.map((entry, i) => {
+        const o = asObj(entry);
+        const name = typeof o.name === "string" ? o.name.trim() : "";
+        if (!REGION_NAME.test(name))
+            throw new BadRequest(`regions[${i}].name must be a region name (a letter or underscore, then letters/digits/hyphens/underscores), got ${JSON.stringify(o.name)}`);
+        if (seen.has(name))
+            throw new BadRequest(`regions declares '${name}' twice — the assembled page is keyed by region name, so one would overwrite the other`);
+        seen.add(name);
+        const region = { name };
+        if (typeof o.label === "string" && o.label.trim() !== "")
+            region.label = o.label.trim();
+        // `null` and omitted both mean "any block type"; an empty ARRAY means "none", which is
+        // a region nothing can ever be placed in. Almost always a half-finished edit, so it is
+        // normalized to "any" rather than stored as a region that silently refuses everything.
+        if (Array.isArray(o.allowedTypes)) {
+            const allowed = o.allowedTypes.map((v) => String(v).trim()).filter((v) => v !== "");
+            region.allowedTypes = allowed.length > 0 ? [...new Set(allowed)] : null;
+        }
+        else {
+            region.allowedTypes = null;
+        }
+        return region;
+    });
+}
+/** Validate a content type's `defaultBlocks` against its own regions. A default block that
+ * names a region the type does not declare is created into nowhere — `createPage` would
+ * place it under a key no renderer reads. */
+export function normalizeDefaultBlocks(raw, regions) {
+    if (raw == null)
+        return [];
+    if (!Array.isArray(raw))
+        throw new BadRequest("defaultBlocks must be a list");
+    const names = new Set(regions.map((r) => r.name));
+    return raw.map((entry, i) => {
+        const o = asObj(entry);
+        const region = typeof o.region === "string" ? o.region.trim() : "";
+        const blockTypeSlug = typeof o.blockTypeSlug === "string" ? o.blockTypeSlug.trim() : "";
+        if (!names.has(region))
+            throw new BadRequest(`defaultBlocks[${i}] targets region '${region}', which this content type does not declare`);
+        if (!blockTypeSlug)
+            throw new BadRequest(`defaultBlocks[${i}] needs a blockTypeSlug`);
+        const allowed = regions.find((r) => r.name === region)?.allowedTypes;
+        if (allowed && !allowed.includes(blockTypeSlug)) {
+            throw new BadRequest(`defaultBlocks[${i}] places '${blockTypeSlug}' into region '${region}', which does not allow it`);
+        }
+        const out = { region, blockTypeSlug };
+        if (o.fields !== undefined)
+            out.fields = asObj(o.fields);
+        return out;
+    });
+}
 /** What the shipped editor can actually produce (TipTap StarterKit + Highlight + TaskList,
  * as configured by @podoba/react's BlockEditor). Pass your own to `normalizeFields` if your
  * editor adds extensions — a node type absent from the schema is dropped on write. */
@@ -769,14 +1319,31 @@ function resolveMediaFields(fields, schema, mediaById) {
 const cdb = (ctx) => ctx.db;
 const notFound = (what) => new PramenError(`${what} not found`, 404, "not_found");
 const asObj = (v) => (v && typeof v === "object" ? v : {});
-// Timestamps in the SAME shape as the `expr.now()` column default (`datetime('now')`:
-// "YYYY-MM-DD HH:MM:SS", UTC, second precision) so a column's insert-default and its
-// handler-written updates stay lexically comparable (an ISO `T`/`Z` string sorts wrong).
-const nowStamp = () => new Date().toISOString().slice(0, 19).replace("T", " ");
-const isEditor = (ctx, roles) => {
-    const held = ctx.identity?.roles ?? (ctx.identity?.role ? [ctx.identity.role] : []);
-    return held.some((r) => roles.includes(r));
-};
+/**
+ * An ISO-8601 UTC instant — the ONE format every timestamp this package writes by hand is
+ * in, so it compares correctly against `$now()` and against the `expr.now()` column
+ * defaults beside it.
+ *
+ * There used to be two of these. `expr.now()` emitted the `datetime('now')` space form, so
+ * page-workflow stamps (`updatedAt`, `publishedAt`) matched THAT to stay lexically
+ * comparable with their own column default, while collection managed timestamps minted ISO
+ * to stay comparable with `$now()`. One column could not satisfy both, and the split was
+ * the honest way to live with it — a trap documented at length on the `publish` field.
+ *
+ * `expr.now()` is ISO now, so the two requirements are the same requirement and there is
+ * one helper. Existing rows written in the old shape are rewritten by
+ * `isoTimestampBackfill()` (see `CMS_LEGACY_TIMESTAMP_COLUMNS`).
+ */
+const isoStamp = () => new Date().toISOString();
+/** Alias kept because the page-workflow call sites read as "stamp it now". Same function. */
+const nowStamp = isoStamp;
+/** Does the caller hold one of these roles?
+ *
+ * Delegates to `authorizeHandler`, which is what the dispatcher uses to enforce a handler's
+ * own `auth` — so "may call this handler" and "counts as an editor here" cannot answer
+ * differently. The local copy took `roles` OR `role`, where the framework takes the UNION,
+ * so an identity carrying both saw only one of them. */
+const isEditor = (ctx, roles) => authorizeHandler([...roles], ctx.identity ?? null);
 /** Assemble a page LIVE from its placements/blocks/types, grouped by region and ordered
  * by position, merging each shared placement's `overrides` over its block's fields. */
 /** Resolve a page's content-type slug from its `typeId` (null when the type row is gone). */
@@ -933,6 +1500,441 @@ async function assertRegionAllows(db, page, region, blockTypeSlug) {
         throw new BadRequest(`block type '${blockTypeSlug}' is not allowed in region '${region}'`);
     }
 }
+// --- handlers ----------------------------------------------------------------
+// --- page preview links (signed capability urls) -----------------------------
+//
+// Preview used to be a ROLE check, so previewing a draft required an editor account —
+// which excludes the person preview actually exists for: the stakeholder reviewing copy
+// before it ships. A preview link is instead a signed, self-expiring CAPABILITY: it names
+// ONE page, carries its own expiry, and is verified in the Worker before any read happens.
+// Minting stays editor-gated; redeeming needs no account at all.
+//
+// Same machinery as signed file urls (`signToken`/`verifyToken` from @pramen/server), and
+// the same fail-closed rule: without a usable secret we refuse to mint rather than hand out
+// forgeable links.
+// --- site furniture: normalization + resolution helpers ----------------------
+//
+// All of this runs on the WRITE path. A menu, a term tree and a widget list are documents
+// the client posts whole, so "the editor wouldn't send that" is not a boundary — every one
+// of these shapes is reachable with a curl.
+const MENU_ITEM_KINDS = ["custom", "page", "term", "collection"];
+/** A stable machine key — the string `getMenu(name)` / `getWidgetArea(name)` resolves, and
+ * a taxonomy's URL segment. Same rule as a page slug, and for the same reason: it lands in
+ * a route. */
+function assertKey(v, what) {
+    const s = typeof v === "string" ? v.trim() : "";
+    if (!isSlugString(s))
+        throw new BadRequest(`${what} must be a key (lowercase letters, digits and single hyphens), got ${JSON.stringify(v)}`);
+    return s;
+}
+/** A REGISTRY key — a block type's slug. Looser than {@link assertKey} by one character:
+ * underscores are admitted, because a block-type slug is not a URL segment. It is the key a
+ * front end maps to a component (`{ rich_text: RichText }`), and `rich_text` is the
+ * convention every existing schema and the shipped example already use. */
+function assertRegistryKey(v, what) {
+    const str = typeof v === "string" ? v.trim() : "";
+    if (!/^[a-z0-9]+(?:[-_][a-z0-9]+)*$/.test(str) || str.length > 80) {
+        throw new BadRequest(`${what} must be a key (lowercase letters, digits, and single hyphens or underscores), got ${JSON.stringify(v)}`);
+    }
+    return str;
+}
+/** Refuse an editor write to a CODE-DEFINED type.
+ *
+ * `cmsBootstrap` reconciles these rows on every boot, so a save here would return 200 and
+ * then be reverted at the next cold start, taking any content authored against the added
+ * field with it. A 409 is the honest answer: the row exists, the edit is well-formed, and
+ * the conflict is with a definition that lives somewhere this request cannot reach.
+ *
+ * The editor renders a managed type read-only, so this is the curl / stale-tab half.
+ *
+ * The caller MUST have read `managedBy` explicitly (`select`), not taken it off a wide read.
+ * Reads are column-projected against the caller's policy, so under a read policy with a
+ * `fields` list the column is simply absent — and a guard written as "absent means editable"
+ * disarms itself for exactly the deployments that restrict fields. `select` fails CLOSED
+ * instead: an unreadable column is a 403 before this runs. */
+export function assertNotManaged(row, what, defineFn) {
+    if (!("managedBy" in row))
+        throw new Error(`assertNotManaged: 'managedBy' was not selected for ${what} — the guard would fail open`);
+    if (row.managedBy == null)
+        return;
+    throw new Conflict(`${what} '${String(row.slug)}' is defined in code (cmsBootstrap owner '${String(row.managedBy)}') — edit its ` +
+        `${defineFn}(...) declaration and redeploy. A change saved here would be reverted on the next boot.`);
+}
+/**
+ * An RPC handler name, as an authored field schema may name one (`optionsFrom`,
+ * `referenceFrom`).
+ *
+ * Shape-checked rather than merely non-empty, because the editor interpolates it straight
+ * into a request path — `fetch(\`${base}/rpc/${name}\`)`. `"../admin/data"` normalizes to
+ * `/admin/data`, so a stored string an EDITOR authored became an arbitrary same-origin
+ * authenticated POST fired by whoever opened the block — including an admin, whose token
+ * passes the `/admin/*` gate the editor role cannot. A handler name is an identifier;
+ * nothing that can traverse a path is one.
+ */
+function assertHandlerName(v, what) {
+    const str = typeof v === "string" ? v.trim() : "";
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(str) || str.length > 80) {
+        throw new BadRequest(`${what} must be a handler name (a letter or underscore, then letters/digits/underscores), got ${JSON.stringify(v)}`);
+    }
+    return str;
+}
+/**
+ * A menu item's `ref` for a non-`custom` kind.
+ *
+ * `menuHref` interpolates this into a path, so a ref starting with `/` produced
+ * `//evil.example/` — protocol-relative, off-origin, in the site's primary nav on every
+ * page — while the sibling `custom` branch three lines away ran the same string through
+ * `isSafeHref`. A reference is an id or a slug: no slashes, no scheme, no dots.
+ */
+function assertRef(v, label, kind) {
+    const str = typeof v === "string" ? v.trim() : "";
+    if (!/^[A-Za-z0-9_-]{1,200}$/.test(str)) {
+        throw new BadRequest(`menu item '${label}' is a '${kind}' item, so its \`ref\` must be an id or slug (letters, digits, hyphens, underscores), got ${JSON.stringify(v)}`);
+    }
+    return str;
+}
+function assertLabel(v, what) {
+    const s = typeof v === "string" ? v.trim() : "";
+    if (!s)
+        throw new BadRequest(`${what} must not be empty`);
+    return s;
+}
+/**
+ * Validate + canonicalize a posted menu tree.
+ *
+ * Every item is rebuilt field by field rather than spread: `items` is a `t.json()` column,
+ * so anything in the posted object would be stored verbatim and handed to a layout that
+ * renders it. Rebuilding is what makes the stored document exactly the declared shape.
+ */
+function normalizeMenuItems(raw, depth = 0, budget = { left: MAX_MENU_ITEMS }) {
+    if (!Array.isArray(raw)) {
+        if (raw == null)
+            return [];
+        throw new BadRequest("menu items must be a list");
+    }
+    if (depth >= MAX_MENU_DEPTH)
+        throw new BadRequest(`menu items may nest at most ${MAX_MENU_DEPTH} levels deep`);
+    return raw.map((entry, i) => {
+        // Counted across the WHOLE tree, not per level — the budget is threaded through the
+        // recursion for that reason.
+        if (--budget.left < 0)
+            throw new BadRequest(`a menu may hold at most ${MAX_MENU_ITEMS} items`);
+        const o = asObj(entry);
+        const label = assertLabel(o.label, `menu item [${i}] label`);
+        const kind = (typeof o.kind === "string" ? o.kind : "custom");
+        if (!MENU_ITEM_KINDS.includes(kind)) {
+            throw new BadRequest(`menu item '${label}' has unknown kind '${String(o.kind)}' (known: ${MENU_ITEM_KINDS.join(", ")})`);
+        }
+        // A stable id per item. Minted here when absent so a client that posts a tree without
+        // ids still gets reorderable rows back, rather than a list React can only key by index.
+        const item = { id: typeof o.id === "string" && o.id.trim() !== "" ? o.id.trim() : crypto.randomUUID(), label, kind };
+        if (kind === "custom") {
+            // The SAME allow-list a rich-text link mark goes through. A menu is rendered into an
+            // `<a href>` on every page of the site, so `javascript:` here is exactly the hole
+            // `isSafeHref` exists to close — and the editor is not the only writer.
+            const url = normalizeHref(typeof o.url === "string" ? o.url : "");
+            if (!isSafeHref(url))
+                throw new BadRequest(`menu item '${label}' needs a valid url (http(s), mailto:, tel:, a rooted path, or #anchor)`);
+            item.url = url;
+        }
+        else {
+            item.ref = assertRef(o.ref, label, kind);
+        }
+        // `target` is written into an anchor; anything but the four browsing-context keywords
+        // is a named window, which is a way to reuse a tab the site does not own.
+        if (typeof o.target === "string" && o.target !== "") {
+            if (!["_self", "_blank", "_parent", "_top"].includes(o.target))
+                throw new BadRequest(`menu item '${label}' has an unsupported target '${o.target}'`);
+            item.target = o.target;
+        }
+        if (typeof o.titleAttr === "string" && o.titleAttr !== "")
+            item.titleAttr = o.titleAttr;
+        if (typeof o.cssClasses === "string" && o.cssClasses !== "")
+            item.cssClasses = o.cssClasses;
+        const children = normalizeMenuItems(o.children, depth + 1, budget);
+        if (children.length > 0)
+            item.children = children;
+        return item;
+    });
+}
+/** Every `page`/`term` ref in a tree, so resolution is two queries rather than one per item. */
+function collectMenuRefs(items, pages, terms) {
+    for (const it of items) {
+        if (it.ref) {
+            if (it.kind === "page")
+                pages.add(it.ref);
+            else if (it.kind === "term")
+                terms.add(it.ref);
+        }
+        if (it.children)
+            collectMenuRefs(it.children, pages, terms);
+    }
+}
+/** A URL redirect's status. 301/308 are permanent (cached by browsers, and by search
+ * engines as a canonical move); 302/307 are not. Anything else is not a redirect. */
+export const REDIRECT_STATUSES = [301, 302, 307, 308];
+/**
+ * The stored form of a redirect's `fromPath`: a rooted, query-less, fragment-less path.
+ *
+ * Canonicalized rather than merely validated, because matching is an exact string lookup
+ * against a UNIQUE column. `"/old"` and `"/old/"` are the same URL to a visitor and two
+ * rows here, so the second one is dead the moment the first exists — and which one wins is
+ * whichever the editor happened to type. Trailing slash off (except the root), fragment
+ * and query dropped, percent-encoding left exactly as written (the parser's, and the
+ * request's, canonical form).
+ */
+export function normalizeRedirectPath(raw) {
+    const s = typeof raw === "string" ? normalizeHref(raw) : "";
+    if (!s.startsWith("/") || s.startsWith("//") || s.startsWith("/\\")) {
+        throw new BadRequest(`redirect path must be a rooted path like /old-url, got ${JSON.stringify(raw)}`);
+    }
+    const path = s.split("#")[0].split("?")[0];
+    const trimmed = path.length > 1 ? path.replace(/\/+$/, "") || "/" : "/";
+    // PERCENT-ENCODED, through the same parser the request goes through. A visitor's path
+    // reaches `resolveRedirect` as `url.pathname`, which the WHATWG parser has already
+    // encoded — so an editor typing `/o-nás` stored a string that the exact-match lookup
+    // could never be handed, and the redirect silently never fired. On precisely the
+    // non-English sites where slug changes are most common. Idempotent: an already-encoded
+    // path parses back to itself.
+    try {
+        return new URL(trimmed, "https://pramen.invalid").pathname;
+    }
+    catch {
+        throw new BadRequest(`redirect path is not a usable path: ${JSON.stringify(raw)}`);
+    }
+}
+/**
+ * Is this redirect a loop — does its destination resolve back to its own source?
+ *
+ * Compared through `normalizeRedirectPath` on BOTH sides, which a raw `from === to` did
+ * not do: `from: "/old", to: "/old/"` differ as strings, so the guard passed — and then a
+ * visitor hitting `/old` was sent to `/old/`, whose 404 handler canonicalizes the trailing
+ * slash back to `/old` and matches the same row. An infinite redirect, from the one pair
+ * the guard exists to catch. (A test here even asserted this pair was fine, on the reading
+ * that a trailing-slash redirect is a normal canonicalization — true in general, and not
+ * true when the lookup canonicalizes the slash away again.)
+ *
+ * An absolute destination is never a loop with a rooted source: it names an origin, and
+ * `resolveRedirect` is only ever handed a path.
+ */
+function isSelfRedirect(fromPath, toPath) {
+    if (/^https?:\/\//i.test(toPath))
+        return false;
+    try {
+        return normalizeRedirectPath(toPath) === fromPath;
+    }
+    catch {
+        return false;
+    }
+}
+/** A redirect's destination: a rooted path or an absolute http(s) url. `mailto:`/`tel:` are
+ * refused — they are not somewhere a `Location` header can send a page request. */
+function normalizeRedirectTarget(raw) {
+    const s = typeof raw === "string" ? normalizeHref(raw) : "";
+    const ok = /^https?:\/\//i.test(s) || (s.startsWith("/") && !s.startsWith("//") && !s.startsWith("/\\"));
+    if (!ok)
+        throw new BadRequest(`redirect target must be a rooted path or an absolute http(s) url, got ${JSON.stringify(raw)}`);
+    return s;
+}
+/** Assemble a flat term list into a forest, ordered by `position` then `label`.
+ *
+ * A term whose `parentId` names a row that is not in `rows` is treated as a ROOT rather
+ * than dropped. That is the case where a parent was deleted mid-read (the FK sets children
+ * to NULL, but a snapshot taken across the two states can see the old value) — and a term
+ * that vanishes from a vocabulary listing is a worse answer than one that shows up a level
+ * too high.
+ */
+function buildTermTree(rows) {
+    const byId = new Map();
+    for (const r of rows)
+        byId.set(r.id, { ...r, children: [] });
+    const roots = [];
+    for (const node of byId.values()) {
+        const parent = node.parentId ? byId.get(node.parentId) : undefined;
+        // `parent !== node` guards the one cycle a single row can make on its own; deeper
+        // cycles are refused on write by `assertTermParent`, which is where a cycle is
+        // actually preventable.
+        if (parent && parent !== node)
+            parent.children.push(node);
+        else
+            roots.push(node);
+    }
+    const sort = (list) => {
+        list.sort((a, b) => a.position - b.position || a.label.localeCompare(b.label));
+        for (const t of list)
+            if (t.children)
+                sort(t.children);
+        return list;
+    };
+    return sort(roots);
+}
+const WIDGET_TYPES = ["content", "menu", "component"];
+/** A list limit from client input, clamped to what `listPages` already allows. Absent or
+ * unusable falls back to the default rather than to "unbounded" — a request with no limit
+ * on a store reached over RPC is the shape that made lists hang (GitHub #22). */
+function clampLimit(v) {
+    const n = typeof v === "number" && Number.isFinite(v) ? Math.floor(v) : PAGE_LIST_LIMIT;
+    return Math.max(1, Math.min(n, PAGE_LIST_MAX_LIMIT));
+}
+/** The most terms one vocabulary (or one page) may carry in a single read.
+ *
+ * A vocabulary is read WHOLE by `listTerms`/`getTermTree` — a tree cannot be paged without
+ * either losing branches or fetching ancestors separately — so the cap is what keeps that
+ * read bounded. Tags are the case that grows without anyone deciding to grow it. */
+const MAX_TERMS = 1000;
+function redirectPatch(raw, requireEnds) {
+    const o = asObj(raw);
+    const out = {};
+    if (requireEnds || o.fromPath !== undefined)
+        out.fromPath = normalizeRedirectPath(o.fromPath);
+    if (requireEnds || o.toPath !== undefined)
+        out.toPath = normalizeRedirectTarget(o.toPath);
+    if (o.status !== undefined) {
+        const status = typeof o.status === "number" ? Math.trunc(o.status) : NaN;
+        if (!REDIRECT_STATUSES.includes(status))
+            throw new BadRequest(`redirect status must be one of ${REDIRECT_STATUSES.join(", ")}`);
+        out.status = status;
+    }
+    if (o.enabled !== undefined)
+        out.enabled = Boolean(o.enabled);
+    if (o.note !== undefined)
+        out.note = typeof o.note === "string" ? o.note : null;
+    return out;
+}
+/** A required row id from client input. */
+function requireId(raw, what = "id") {
+    const v = asObj(raw)[what];
+    if (typeof v !== "string" || v === "")
+        throw new BadRequest(`${what} is required`);
+    return v;
+}
+/** Resolve a taxonomy by its slug. */
+async function taxonomyBySlug(db, slug) {
+    const rows = await db.find({ from: "cms_taxonomies", where: { slug }, select: ["id", "hierarchical"], limit: 1 });
+    const row = rows[0];
+    return row ? { id: String(row.id), hierarchical: Boolean(row.hierarchical) } : null;
+}
+/**
+ * Check a proposed `parentId` for a term: it exists, it is in the SAME vocabulary, the
+ * vocabulary is hierarchical, the tree stays inside {@link MAX_TERM_DEPTH}, and — for an
+ * update — the new parent is not the term itself or one of its own descendants.
+ *
+ * The cycle check is the one that matters. `ON DELETE SET NULL` keeps the FK honest but
+ * says nothing about shape, so `A.parent = B; B.parent = A` is two perfectly legal writes
+ * that together make `buildTermTree` produce a forest missing both, and any recursive
+ * renderer loop forever. It is only preventable on write, which is here.
+ */
+async function assertTermParent(db, tax, parentId, termId) {
+    if (parentId === null)
+        return;
+    if (!tax.hierarchical)
+        throw new BadRequest("this vocabulary is flat — its terms cannot have a parent");
+    if (termId !== null && parentId === termId)
+        throw new BadRequest("a term cannot be its own parent");
+    // How many levels the MOVED term itself occupies. A leaf is 1; a term with children takes
+    // its subtree with it, and a cap that ignored that admitted a 5-level tree grafted under a
+    // 4-level parent. Zero cost on the create path, where there is no subtree yet.
+    const moving = termId === null ? 1 : await subtreeHeight(db, tax.id, termId);
+    let cursor = parentId;
+    // `depth` counts ANCESTORS walked. The moved term sits at `ancestors + moving` levels, and
+    // that is what the cap governs — counting ancestors alone admitted one level too many
+    // (a chain of 5 put the new term at level 6 under a cap of 5).
+    for (let depth = 0; cursor !== null; depth++) {
+        // About to walk ancestor number `depth + 1`. The moved term would then sit at
+        // `(depth + 1) + moving` levels, and THAT is what the cap governs.
+        if (depth + 1 + moving > MAX_TERM_DEPTH)
+            throw new BadRequest(`terms may nest at most ${MAX_TERM_DEPTH} levels deep`);
+        const rows = await db.find({ from: "cms_terms", where: { id: cursor }, select: ["id", "taxonomyId", "parentId"], limit: 1 });
+        const row = rows[0];
+        if (!row)
+            throw new BadRequest("parent term not found");
+        if (String(row.taxonomyId) !== tax.id)
+            throw new BadRequest("a term's parent must be in the same vocabulary");
+        // Walking UP from the proposed parent: meeting the term being edited means the parent
+        // is one of its own descendants, which is the cycle.
+        if (termId !== null && String(row.id) === termId)
+            throw new BadRequest("a term cannot be moved under one of its own descendants");
+        cursor = row.parentId == null ? null : String(row.parentId);
+    }
+}
+/** How many levels a term's own subtree occupies (a leaf is 1).
+ *
+ * One query for the whole vocabulary rather than a walk per level: a vocabulary is already
+ * read whole by `listTerms`/`getTermTree` and capped at `MAX_TERMS`, so this is the same
+ * bounded read those make, not a new unbounded one. */
+async function subtreeHeight(db, taxonomyId, rootId) {
+    const rows = await db.find({ from: "cms_terms", where: { taxonomyId }, select: ["id", "parentId"], limit: MAX_TERMS });
+    const children = new Map();
+    for (const r of rows) {
+        const parent = r.parentId == null ? null : String(r.parentId);
+        if (parent)
+            children.set(parent, [...(children.get(parent) ?? []), String(r.id)]);
+    }
+    // Iterative, and bounded by MAX_TERMS: a cycle already in the store (written before the
+    // check that now prevents one) must not spin here.
+    let level = 0;
+    let frontier = [rootId];
+    const seen = new Set();
+    while (frontier.length > 0 && level <= MAX_TERM_DEPTH + 1) {
+        level++;
+        const next = [];
+        for (const id of frontier) {
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            next.push(...(children.get(id) ?? []));
+        }
+        frontier = next;
+    }
+    return level;
+}
+/**
+ * Validate + canonicalize a posted widget list.
+ *
+ * Rebuilt field by field for the same reason a menu tree is: `widgets` is a `t.json()`
+ * column handed straight to a layout, so whatever the client posts is what renders.
+ * A `content` widget's rich text goes through the SAME `normalizeRichText` allow-list every
+ * block field does — this is a second write path into the same renderer, and it must not be
+ * a weaker one.
+ */
+function normalizeWidgets(raw, rtSchema) {
+    if (!Array.isArray(raw)) {
+        if (raw == null)
+            return [];
+        throw new BadRequest("widgets must be a list");
+    }
+    return raw.map((entry, i) => {
+        const o = asObj(entry);
+        const type = (typeof o.type === "string" ? o.type : "");
+        if (!WIDGET_TYPES.includes(type))
+            throw new BadRequest(`widget [${i}] has unknown type '${String(o.type)}' (known: ${WIDGET_TYPES.join(", ")})`);
+        const w = { id: typeof o.id === "string" && o.id.trim() !== "" ? o.id.trim() : crypto.randomUUID(), type };
+        if (typeof o.title === "string" && o.title !== "")
+            w.title = o.title;
+        if (type === "content") {
+            w.content = normalizeRichText(o.content, rtSchema);
+        }
+        else if (type === "menu") {
+            w.menuName = assertKey(o.menuName, `widget [${i}] menuName`);
+        }
+        else {
+            const id = typeof o.componentId === "string" ? o.componentId.trim() : "";
+            if (!id)
+                throw new BadRequest(`widget [${i}] is a component widget and needs a componentId`);
+            w.componentId = id;
+            // Props are opaque to the CMS — the front end's component owns their meaning — but
+            // they must be a JSON OBJECT, not a bare array or scalar that a spread would silently
+            // turn into indexed props.
+            if (o.componentProps !== undefined) {
+                if (o.componentProps === null || typeof o.componentProps !== "object" || Array.isArray(o.componentProps)) {
+                    throw new BadRequest(`widget [${i}] componentProps must be an object`);
+                }
+                w.componentProps = o.componentProps;
+            }
+        }
+        return w;
+    });
+}
 /** Secret preference order. `PREVIEW_SECRET` lets an operator rotate preview links without
  * invalidating every signed file url, but falling back keeps the common case zero-config. */
 export const PREVIEW_SECRET_NAMES = ["PREVIEW_SECRET", "FILES_SECRET", "AUTH_SECRET"];
@@ -977,6 +1979,16 @@ export function createCmsHandlers(opts = {}) {
     const reviewer = { auth: reviewerRoles };
     const previewTtl = opts.previewTtlSeconds ?? DEFAULT_PREVIEW_TTL_SECONDS;
     const rtSchema = opts.richTextSchema ?? DEFAULT_RICH_TEXT_SCHEMA;
+    const menuHref = opts.menuHref ?? ((target) => {
+        switch (target.kind) {
+            // The locale segment appears only where there is a choice to make. A monolingual site
+            // getting `/en/about` is the sitemap default's known wart, and a menu is the one place
+            // it would be visible in the site's own chrome.
+            case "page": return locales.length > 1 ? `/${target.locale}/${target.slug}` : `/${target.slug}`;
+            case "term": return `/${target.taxonomy}/${target.slug}`;
+            case "collection": return `/${target.slug}/`;
+        }
+    });
     // Anyone who edits OR reviews may VIEW content (a reviewer must preview a page + load its
     // content type/blocks before approving). Read/preview handlers use this; writes stay editor.
     const viewerRoles = [...new Set([...editorRoles, ...reviewerRoles])];
@@ -1071,13 +2083,95 @@ export function createCmsHandlers(opts = {}) {
             throw new BadRequest(`slug '${slug}' already exists for locale '${locale}'${under} — slugs are unique across all content types`);
         }
     };
+    /**
+     * One stored menu row, with its references resolved to hrefs.
+     *
+     * Shared by `getMenu` and `getWidgetArea` rather than inlined in the first: a `menu`
+     * widget embeds a menu, and returning its RAW items there skipped every rule this
+     * function exists to apply — a `page` item came back with no `url` at all (the layout
+     * renders `href=undefined`) and an UNPUBLISHED page's label and id were served to
+     * anonymous callers, which is precisely what the drop below prevents on the other path.
+     */
+    const resolveMenuRow = async (db, row) => {
+        const items = Array.isArray(row.items) ? row.items : [];
+        // Two lookups for the whole tree, not one per item. Both go through `ctx.db`, so the
+        // caller's own read scope applies: for an anonymous visitor that is the public policy
+        // (published, not trashed), which is precisely the filter a menu needs — a link to a
+        // page that has been unpublished must not render.
+        const pageIds = new Set();
+        const termIds = new Set();
+        collectMenuRefs(items, pageIds, termIds);
+        const pages = new Map();
+        if (pageIds.size > 0) {
+            const found = await db.find({ from: "cms_pages", where: { id: { in: [...pageIds] } }, select: ["id", "slug", "locale"], limit: pageIds.size });
+            for (const p of found)
+                pages.set(String(p.id), { slug: String(p.slug), locale: String(p.locale ?? defaultLocale) });
+        }
+        const terms = new Map();
+        if (termIds.size > 0) {
+            const found = await db.find({ from: "cms_terms", where: { id: { in: [...termIds] } }, select: ["id", "slug", "taxonomyId"], limit: termIds.size });
+            const taxIds = [...new Set(found.map((t) => String(t.taxonomyId)))];
+            const taxa = taxIds.length > 0 ? await db.find({ from: "cms_taxonomies", where: { id: { in: taxIds } }, select: ["id", "slug"], limit: taxIds.length }) : [];
+            const taxSlug = new Map(taxa.map((t) => [String(t.id), String(t.slug)]));
+            for (const t of found) {
+                const tax = taxSlug.get(String(t.taxonomyId));
+                if (tax)
+                    terms.set(String(t.id), { slug: String(t.slug), taxonomy: tax });
+            }
+        }
+        // An item whose target no longer resolves is DROPPED, together with its subtree. A
+        // nav entry that renders no href is a dead link on every page of the site, and
+        // hoisting orphaned children would silently promote a third-level item into the top
+        // bar. The editor's own `listMenus` returns the raw tree, so nothing is lost there.
+        const resolve = (list) => {
+            const out = [];
+            for (const item of list) {
+                let url = item.url;
+                if (item.kind === "page") {
+                    const page = item.ref ? pages.get(item.ref) : undefined;
+                    if (!page)
+                        continue;
+                    url = menuHref({ kind: "page", slug: page.slug, locale: page.locale });
+                }
+                else if (item.kind === "term") {
+                    const term = item.ref ? terms.get(item.ref) : undefined;
+                    if (!term)
+                        continue;
+                    url = menuHref({ kind: "term", taxonomy: term.taxonomy, slug: term.slug });
+                }
+                else if (item.kind === "collection") {
+                    if (!item.ref)
+                        continue;
+                    url = menuHref({ kind: "collection", slug: item.ref });
+                }
+                // The MINTED url goes through the same allow-list the `custom` branch enforces on
+                // write. A reference is interpolated into a path (`/${slug}/`), and a `ref` that
+                // began with a slash produced `//evil.example/` — protocol-relative, off-origin,
+                // in the site's primary nav on every page. `assertRef` refuses that shape on
+                // write; this is the second half, because `menuHref` is host-supplied and a
+                // deployment's own mapping can build an unsafe href out of a safe ref.
+                if (!url || !isSafeHref(url))
+                    continue;
+                const children = item.children ? resolve(item.children) : [];
+                out.push({ ...item, url, ...(children.length > 0 ? { children } : { children: undefined }) });
+            }
+            return out;
+        };
+        return { id: String(row.id), name: String(row.name), label: String(row.label), items: resolve(items) };
+    };
     const TASK_PUBLISH = "cms:publish";
     const TASK_UNPUBLISH = "cms:unpublish";
     return {
         // ---- block types & content types (data-driven definitions) ----
         listBlockTypes: query((ctx) => cdb(ctx).find({ from: "cms_block_types", orderBy: { column: "name" } })),
         createBlockType: mutation(async (ctx, input) => {
-            return cdb(ctx).insert("cms_block_types", {
+            const db = cdb(ctx);
+            // A clean 409 before the UNIQUE constraint fires. The editor authors these now, and a
+            // raw constraint error reads as "the CMS broke" rather than "that slug is taken".
+            const clash = await db.find({ from: "cms_block_types", where: { slug: input.slug }, select: ["id"], limit: 1 });
+            if (clash[0])
+                throw new Conflict(`block type '${input.slug}' already exists`);
+            return db.insert("cms_block_types", {
                 name: input.name,
                 slug: input.slug,
                 description: input.description ?? null,
@@ -1091,11 +2185,31 @@ export function createCmsHandlers(opts = {}) {
                 const o = asObj(raw);
                 if (typeof o.name !== "string" || typeof o.slug !== "string")
                     throw new BadRequest("name and slug are required");
-                return o;
+                if (o.name.trim() === "")
+                    throw new BadRequest("name must not be empty");
+                return {
+                    name: o.name.trim(),
+                    // A block type's slug is a registry key: the editor's inserter, `assertRegionAllows`
+                    // and `@pramen/cms/react`'s component map all resolve it. Held to the same shape as
+                    // any other key rather than accepted as free text.
+                    slug: assertRegistryKey(o.slug, "block type slug"),
+                    description: typeof o.description === "string" ? o.description : undefined,
+                    icon: typeof o.icon === "string" ? o.icon : undefined,
+                    category: typeof o.category === "string" ? o.category : undefined,
+                    fieldsSchema: normalizeFieldSchema(o.fieldsSchema),
+                };
             },
         }),
         createContentType: mutation(async (ctx, input) => {
-            return cdb(ctx).insert("cms_content_types", {
+            const db = cdb(ctx);
+            // The same pre-check `createBlockType` and every `create*` in this file already do.
+            // It was the one create handler without it, so a duplicate slug surfaced as a raw
+            // `UNIQUE constraint failed` with no status — a 500. Newly likely: an editor just told
+            // a content type is code-defined and read-only will try to recreate it under that slug.
+            const clash = await db.find({ from: "cms_content_types", where: { slug: input.slug }, select: ["id"], limit: 1 });
+            if (clash[0])
+                throw new Conflict(`content type '${input.slug}' already exists`);
+            return db.insert("cms_content_types", {
                 name: input.name,
                 slug: input.slug,
                 regions: input.regions ?? [],
@@ -1112,11 +2226,20 @@ export function createCmsHandlers(opts = {}) {
                 // editor (`/types/:slug`) and the key `listPages({ contentType })` resolves. An
                 // empty one builds `/types/` — a path the router drops the empty segment from, so
                 // the type gets a tab that cannot be reached and a list that cannot be addressed.
-                if (o.name.trim() === "" || o.slug.trim() === "")
-                    throw new BadRequest("name and slug must not be empty");
-                if (!Array.isArray(o.regions) || o.regions.length === 0)
-                    throw new BadRequest("at least one region is required");
-                return o;
+                if (o.name.trim() === "")
+                    throw new BadRequest("name must not be empty");
+                const regions = normalizeRegions(o.regions);
+                return {
+                    name: o.name.trim(),
+                    // The SAME rule a block-type slug follows. They were split — block types admitted
+                    // `_`, content types did not — for no reason that survives inspection: both are
+                    // registry keys, and an underscore is as legal in the `/types/:slug` segment as it
+                    // is anywhere else in a URL. The example itself ships `seeded_doc`.
+                    slug: assertRegistryKey(o.slug, "content type slug"),
+                    regions,
+                    fieldsSchema: normalizeFieldSchema(o.fieldsSchema),
+                    defaultBlocks: normalizeDefaultBlocks(o.defaultBlocks, regions),
+                };
             },
         }),
         /** Update a block type (found by `id` or `slug`). `slug` is the stable key and is
@@ -1124,10 +2247,14 @@ export function createCmsHandlers(opts = {}) {
          * what lets a schema evolve (e.g. a field text → date) without recreating the type. */
         updateBlockType: mutation(async (ctx, input) => {
             const db = cdb(ctx);
-            const rows = await db.find({ from: "cms_block_types", where: input.id ? { id: input.id } : { slug: input.slug }, limit: 1 });
+            // `select` for BOTH reasons the projection exists: the guard needs `managedBy` to be
+            // present rather than projected away, and the lookup has no use for the wide
+            // `fieldsSchema` blob it used to fetch and JSON-parse to read three columns.
+            const rows = await db.find({ from: "cms_block_types", where: input.id ? { id: input.id } : { slug: input.slug }, select: ["id", "slug", "managedBy"], limit: 1 });
             const row = rows[0];
             if (!row)
                 throw notFound("block type");
+            assertNotManaged(row, "block type", "defineBlockType");
             const patch = {};
             for (const k of ["name", "fieldsSchema", "icon", "category", "description"]) {
                 if (k in input)
@@ -1140,7 +2267,14 @@ export function createCmsHandlers(opts = {}) {
                 const o = asObj(raw);
                 if (typeof o.id !== "string" && typeof o.slug !== "string")
                     throw new BadRequest("id or slug is required");
-                return o;
+                const out = { ...o };
+                // `name` is the label in the editor's inserter; blanking it leaves an unnamed entry
+                // nobody can identify.
+                if (o.name !== undefined)
+                    out.name = assertLabel(o.name, "block type name");
+                if (o.fieldsSchema !== undefined)
+                    out.fieldsSchema = normalizeFieldSchema(o.fieldsSchema);
+                return out;
             },
         }),
         /** Update a content type (found by `id` or `slug`). `slug` is the stable key and is
@@ -1149,15 +2283,24 @@ export function createCmsHandlers(opts = {}) {
             const db = cdb(ctx);
             if ("regions" in input && (!Array.isArray(input.regions) || input.regions.length === 0))
                 throw new BadRequest("at least one region is required");
-            const rows = await db.find({ from: "cms_content_types", where: input.id ? { id: input.id } : { slug: input.slug }, limit: 1 });
+            // `regions` as well, because the `defaultBlocks`-only patch below checks against the
+            // STORED regions. See the block-type lookup for why this is a `select` at all.
+            const rows = await db.find({ from: "cms_content_types", where: input.id ? { id: input.id } : { slug: input.slug }, select: ["id", "slug", "managedBy", "regions"], limit: 1 });
             const row = rows[0];
             if (!row)
                 throw notFound("content type");
+            assertNotManaged(row, "content type", "defineContentType");
             const patch = {};
             for (const k of ["name", "regions", "fieldsSchema", "defaultBlocks"]) {
                 if (k in input)
                     patch[k] = input[k];
             }
+            // A `defaultBlocks` patch that does NOT also send regions is checked here against the
+            // STORED ones — the input parser has no row to read, and a default block placed into a
+            // region the type does not declare is created into a key no renderer looks at.
+            if (patch.defaultBlocks !== undefined && patch.regions === undefined) {
+                patch.defaultBlocks = normalizeDefaultBlocks(patch.defaultBlocks, (Array.isArray(row.regions) ? row.regions : []));
+            }
             return db.update("cms_content_types", String(row.id), patch);
         }, {
             ...editor,
@@ -1165,10 +2308,619 @@ export function createCmsHandlers(opts = {}) {
                 const o = asObj(raw);
                 if (typeof o.id !== "string" && typeof o.slug !== "string")
                     throw new BadRequest("id or slug is required");
+                const out = { ...o };
                 // `name` is the editor's tab label; blanking it leaves an unlabelled tab.
-                if (typeof o.name === "string" && o.name.trim() === "")
-                    throw new BadRequest("name must not be empty");
-                return o;
+                if (o.name !== undefined)
+                    out.name = assertLabel(o.name, "content type name");
+                if (o.regions !== undefined)
+                    out.regions = normalizeRegions(o.regions);
+                if (o.fieldsSchema !== undefined)
+                    out.fieldsSchema = normalizeFieldSchema(o.fieldsSchema);
+                // Checked against the regions being SAVED where the same call sends both — patching
+                // only `defaultBlocks` cannot see the stored regions from an input parser, and the
+                // handler re-checks below.
+                if (out.defaultBlocks !== undefined && out.regions !== undefined) {
+                    out.defaultBlocks = normalizeDefaultBlocks(out.defaultBlocks, out.regions);
+                }
+                return out;
+            },
+        }),
+        // ---- site furniture: menus ----------------------------------------------
+        //
+        // A menu is read WHOLE (`getMenu("primary")` on every page render) and written whole.
+        // The public read RESOLVES references — that is what makes a `page` item follow its
+        // page's slug instead of freezing the href an editor typed once.
+        /** One menu, references resolved to hrefs. PUBLIC — a menu is site chrome.
+         *
+         * Returns `null` for an unknown name rather than 404ing, because a layout asking for a
+         * menu it has not created yet is the normal state of a site being built, and a thrown
+         * error there takes down every page instead of rendering no nav. */
+        getMenu: query(async (ctx, input) => {
+            const rows = await cdb(ctx).find({ from: "cms_menus", where: { name: input.name }, limit: 1 });
+            const row = rows[0];
+            if (!row)
+                return null;
+            return resolveMenuRow(cdb(ctx), row);
+        }, {
+            input: (raw) => ({ name: assertKey(asObj(raw).name, "menu name") }),
+        }),
+        /** Every menu, RAW (references unresolved) — the editor's list.
+         *
+         * Capped like every other list here. A site-furniture table is small by nature, which is
+         * an argument for the cap being generous, not for its absence: an unbounded SELECT of a
+         * wide row over RPC is the D1 failure shape from GitHub #22, and "small by nature" is
+         * not a property the query planner knows about. */
+        listMenus: query((ctx) => cdb(ctx).find({ from: "cms_menus", orderBy: { column: "label" }, limit: PAGE_LIST_MAX_LIMIT }), viewer),
+        createMenu: mutation(async (ctx, input) => {
+            const db = cdb(ctx);
+            // A clean 409, as every sibling create handler gives. Without it a taken key surfaced
+            // as the UNIQUE constraint's own 500 — and the e2e only asserts "not 200", so it
+            // could not tell the two apart.
+            const clash = await db.find({ from: "cms_menus", where: { name: input.name }, select: ["id"], limit: 1 });
+            if (clash[0])
+                throw new Conflict(`menu '${input.name}' already exists`);
+            return db.insert("cms_menus", { name: input.name, label: input.label, items: input.items ?? [] });
+        }, {
+            ...editor,
+            input: (raw) => {
+                const o = asObj(raw);
+                return { name: assertKey(o.name, "menu name"), label: assertLabel(o.label, "menu label"), items: normalizeMenuItems(o.items) };
+            },
+        }),
+        /** Patch a menu found by `id` or `name`. `name` is the key layout code resolves and is
+         * NOT mutable — retitling is what `label` is for. */
+        updateMenu: mutation(async (ctx, input) => {
+            const db = cdb(ctx);
+            const rows = await db.find({ from: "cms_menus", where: input.id ? { id: input.id } : { name: input.name }, limit: 1 });
+            const row = rows[0];
+            if (!row)
+                throw notFound("menu");
+            const patch = { updatedAt: nowStamp(), version: nextVersion(row, input.expectedVersion, "this menu") };
+            if (input.label !== undefined)
+                patch.label = input.label;
+            if (input.items !== undefined)
+                patch.items = input.items;
+            return db.update("cms_menus", String(row.id), patch);
+        }, {
+            ...editor,
+            input: (raw) => {
+                const o = asObj(raw);
+                const out = {};
+                if (typeof o.id === "string")
+                    out.id = o.id;
+                else if (typeof o.name === "string")
+                    out.name = assertKey(o.name, "menu name");
+                else
+                    throw new BadRequest("id or name is required");
+                if (o.label !== undefined)
+                    out.label = assertLabel(o.label, "menu label");
+                if (o.items !== undefined)
+                    out.items = normalizeMenuItems(o.items);
+                if (typeof o.expectedVersion === "number")
+                    out.expectedVersion = o.expectedVersion;
+                return out;
+            },
+        }),
+        deleteMenu: mutation(async (ctx, input) => {
+            const ok = await cdb(ctx).delete("cms_menus", input.id);
+            if (!ok)
+                throw notFound("menu");
+            return { ok: true };
+        }, {
+            ...editor,
+            input: (raw) => {
+                const id = asObj(raw).id;
+                if (typeof id !== "string" || id === "")
+                    throw new BadRequest("id is required");
+                return { id };
+            },
+        }),
+        // ---- site furniture: redirects -------------------------------------------
+        /** Resolve a request path to its redirect, or `null`. PUBLIC and READ-ONLY: this is
+         * what a front end calls on a 404, so it is anonymous traffic on the hot path.
+         *
+         * `enabled` is enforced by the public read POLICY, not by a `where` here, so a disabled
+         * redirect is invisible to every anonymous read (this handler, a future listing, a
+         * relation traversal) rather than to the one call that remembered to filter. */
+        resolveRedirect: query(async (ctx, input) => {
+            const rows = await cdb(ctx).find({ from: "cms_redirects", where: { fromPath: input.path, enabled: true }, select: ["toPath", "status"], limit: 1 });
+            const row = rows[0];
+            return row ? { to: String(row.toPath), status: Number(row.status ?? 301) } : null;
+        }, {
+            input: (raw) => ({ path: normalizeRedirectPath(asObj(raw).path) }),
+        }),
+        listRedirects: query((ctx, input) => {
+            return cdb(ctx).find({ from: "cms_redirects", orderBy: { column: "fromPath" }, limit: input.limit ?? PAGE_LIST_LIMIT, offset: input.offset ?? 0 });
+        }, {
+            ...viewer,
+            input: (raw) => {
+                const o = asObj(raw);
+                return { limit: clampLimit(o.limit), offset: typeof o.offset === "number" && o.offset > 0 ? Math.floor(o.offset) : 0 };
+            },
+        }),
+        createRedirect: mutation(async (ctx, input) => {
+            // A redirect to itself is an infinite loop the moment it is enabled, and the browser
+            // is what discovers it. Cheap to refuse here; impossible to diagnose from the outside.
+            if (isSelfRedirect(input.fromPath, input.toPath))
+                throw new BadRequest("a redirect cannot point at itself");
+            const db = cdb(ctx);
+            const clash = await db.find({ from: "cms_redirects", where: { fromPath: input.fromPath }, select: ["id"], limit: 1 });
+            if (clash[0])
+                throw new Conflict(`a redirect from '${input.fromPath}' already exists`);
+            return db.insert("cms_redirects", {
+                fromPath: input.fromPath,
+                toPath: input.toPath,
+                status: input.status ?? 301,
+                enabled: input.enabled ?? true,
+                note: input.note ?? null,
+            });
+        }, {
+            ...editor,
+            input: (raw) => redirectPatch(raw, true),
+        }),
+        updateRedirect: mutation(async (ctx, input) => {
+            const db = cdb(ctx);
+            const rows = await db.find({ from: "cms_redirects", where: { id: input.id }, limit: 1 });
+            const row = rows[0];
+            if (!row)
+                throw notFound("redirect");
+            const from = input.fromPath ?? String(row.fromPath);
+            const to = input.toPath ?? String(row.toPath);
+            if (isSelfRedirect(from, to))
+                throw new BadRequest("a redirect cannot point at itself");
+            if (input.fromPath && input.fromPath !== row.fromPath) {
+                const clash = await db.find({ from: "cms_redirects", where: { fromPath: input.fromPath }, select: ["id"], limit: 1 });
+                if (clash[0])
+                    throw new Conflict(`a redirect from '${input.fromPath}' already exists`);
+            }
+            const patch = { updatedAt: nowStamp() };
+            for (const k of ["fromPath", "toPath", "status", "enabled", "note"]) {
+                if (input[k] !== undefined)
+                    patch[k] = input[k];
+            }
+            return db.update("cms_redirects", input.id, patch);
+        }, {
+            ...editor,
+            input: (raw) => ({ id: requireId(raw), ...redirectPatch(raw, false) }),
+        }),
+        deleteRedirect: mutation(async (ctx, input) => {
+            const ok = await cdb(ctx).delete("cms_redirects", input.id);
+            if (!ok)
+                throw notFound("redirect");
+            return { ok: true };
+        }, {
+            ...editor,
+            input: (raw) => {
+                const id = asObj(raw).id;
+                if (typeof id !== "string" || id === "")
+                    throw new BadRequest("id is required");
+                return { id };
+            },
+        }),
+        // ---- site furniture: taxonomies ------------------------------------------
+        //
+        // `category` and `tag` are not built in: they are two rows a deployment creates, the
+        // same way it creates its content types. A vocabulary that is hierarchical allows
+        // `parentId` on its terms; a flat one refuses it rather than storing something no
+        // listing renders.
+        /** Every vocabulary. PUBLIC — like content types, a taxonomy's slug is structural (it
+         * is a URL segment) and a front end routes on it. */
+        listTaxonomies: query((ctx) => cdb(ctx).find({ from: "cms_taxonomies", orderBy: { column: "label" }, limit: PAGE_LIST_MAX_LIMIT })),
+        createTaxonomy: mutation(async (ctx, input) => {
+            const db = cdb(ctx);
+            const clash = await db.find({ from: "cms_taxonomies", where: { slug: input.slug }, select: ["id"], limit: 1 });
+            if (clash[0])
+                throw new Conflict(`taxonomy '${input.slug}' already exists`);
+            return db.insert("cms_taxonomies", {
+                slug: input.slug,
+                label: input.label,
+                pluralLabel: input.pluralLabel ?? null,
+                description: input.description ?? null,
+                hierarchical: input.hierarchical ?? false,
+            });
+        }, {
+            ...editor,
+            input: (raw) => {
+                const o = asObj(raw);
+                return {
+                    slug: assertKey(o.slug, "taxonomy slug"),
+                    label: assertLabel(o.label, "taxonomy label"),
+                    pluralLabel: typeof o.pluralLabel === "string" ? o.pluralLabel : undefined,
+                    description: typeof o.description === "string" ? o.description : undefined,
+                    hierarchical: typeof o.hierarchical === "boolean" ? o.hierarchical : undefined,
+                };
+            },
+        }),
+        /** Patch a vocabulary. `slug` is a URL segment and the key `listTerms` resolves, so it
+         * is not mutable — the same rule content types and block types already follow.
+         *
+         * Turning `hierarchical` OFF is refused while any term still has a parent. Allowing it
+         * would leave a stored hierarchy that no reader renders and no writer can clear, and
+         * flattening the terms silently is a destructive edit behind a checkbox. */
+        updateTaxonomy: mutation(async (ctx, input) => {
+            const db = cdb(ctx);
+            const rows = await db.find({ from: "cms_taxonomies", where: { id: input.id }, limit: 1 });
+            const row = rows[0];
+            if (!row)
+                throw notFound("taxonomy");
+            if (input.hierarchical === false && row.hierarchical) {
+                const nested = await db.find({ from: "cms_terms", where: { taxonomyId: input.id, parentId: { isNull: false } }, select: ["id"], limit: 1 });
+                if (nested[0])
+                    throw new BadRequest("this vocabulary still has nested terms — move them to the top level before making it flat");
+            }
+            const patch = {};
+            for (const k of ["label", "pluralLabel", "description", "hierarchical"]) {
+                if (input[k] !== undefined)
+                    patch[k] = input[k];
+            }
+            return db.update("cms_taxonomies", input.id, patch);
+        }, {
+            ...editor,
+            input: (raw) => {
+                const o = asObj(raw);
+                if (typeof o.id !== "string" || o.id === "")
+                    throw new BadRequest("id is required");
+                const out = { id: o.id };
+                if (o.label !== undefined)
+                    out.label = assertLabel(o.label, "taxonomy label");
+                if (o.pluralLabel !== undefined)
+                    out.pluralLabel = typeof o.pluralLabel === "string" ? o.pluralLabel : null;
+                if (o.description !== undefined)
+                    out.description = typeof o.description === "string" ? o.description : null;
+                if (typeof o.hierarchical === "boolean")
+                    out.hierarchical = o.hierarchical;
+                return out;
+            },
+        }),
+        /** Delete a vocabulary. Its terms go with it, and their page assignments with those —
+         * both by real `ON DELETE CASCADE`, so the cleanup is the DB's and cannot be half-done
+         * by a handler that threw between two writes. */
+        deleteTaxonomy: mutation(async (ctx, input) => {
+            const ok = await cdb(ctx).delete("cms_taxonomies", input.id);
+            if (!ok)
+                throw notFound("taxonomy");
+            return { ok: true };
+        }, {
+            ...editor,
+            input: (raw) => {
+                const id = asObj(raw).id;
+                if (typeof id !== "string" || id === "")
+                    throw new BadRequest("id is required");
+                return { id };
+            },
+        }),
+        /** One vocabulary's terms, flat, ordered. PUBLIC. */
+        listTerms: query(async (ctx, input) => {
+            const db = cdb(ctx);
+            const tax = await taxonomyBySlug(db, input.taxonomy);
+            if (!tax)
+                return [];
+            const rows = await db.find({ from: "cms_terms", where: { taxonomyId: tax.id }, orderBy: [{ column: "position" }, { column: "label" }], limit: MAX_TERMS });
+            return rows;
+        }, {
+            input: (raw) => ({ taxonomy: assertKey(asObj(raw).taxonomy, "taxonomy slug") }),
+        }),
+        /** One vocabulary's terms as a TREE. PUBLIC. Assembled here rather than by the caller
+         * because a hierarchy is what the nav renders and every consumer would otherwise write
+         * the same fold. */
+        getTermTree: query(async (ctx, input) => {
+            const db = cdb(ctx);
+            const tax = await taxonomyBySlug(db, input.taxonomy);
+            if (!tax)
+                return [];
+            const rows = await db.find({ from: "cms_terms", where: { taxonomyId: tax.id }, limit: MAX_TERMS });
+            return buildTermTree(rows);
+        }, {
+            input: (raw) => ({ taxonomy: assertKey(asObj(raw).taxonomy, "taxonomy slug") }),
+        }),
+        createTerm: mutation(async (ctx, input) => {
+            const db = cdb(ctx);
+            const tax = await taxonomyBySlug(db, input.taxonomy);
+            if (!tax)
+                throw notFound("taxonomy");
+            await assertTermParent(db, tax, input.parentId ?? null, null);
+            const clash = await db.find({ from: "cms_terms", where: { taxonomyId: tax.id, slug: input.slug }, select: ["id"], limit: 1 });
+            if (clash[0])
+                throw new Conflict(`term '${input.slug}' already exists in '${input.taxonomy}'`);
+            return db.insert("cms_terms", {
+                taxonomyId: tax.id,
+                slug: input.slug,
+                label: input.label,
+                description: input.description ?? null,
+                parentId: input.parentId ?? null,
+                position: input.position ?? 0,
+            });
+        }, {
+            ...editor,
+            input: (raw) => {
+                const o = asObj(raw);
+                return {
+                    taxonomy: assertKey(o.taxonomy, "taxonomy slug"),
+                    slug: assertKey(o.slug, "term slug"),
+                    label: assertLabel(o.label, "term label"),
+                    description: typeof o.description === "string" ? o.description : undefined,
+                    parentId: typeof o.parentId === "string" && o.parentId !== "" ? o.parentId : null,
+                    position: typeof o.position === "number" ? Math.trunc(o.position) : undefined,
+                };
+            },
+        }),
+        updateTerm: mutation(async (ctx, input) => {
+            const db = cdb(ctx);
+            const rows = await db.find({ from: "cms_terms", where: { id: input.id }, limit: 1 });
+            const row = rows[0];
+            if (!row)
+                throw notFound("term");
+            const taxRows = await db.find({ from: "cms_taxonomies", where: { id: row.taxonomyId }, limit: 1 });
+            const tax = taxRows[0];
+            if (!tax)
+                throw notFound("taxonomy");
+            if (input.parentId !== undefined) {
+                await assertTermParent(db, { id: String(tax.id), hierarchical: Boolean(tax.hierarchical) }, input.parentId, input.id);
+            }
+            // A term's slug IS mutable, unlike a taxonomy's: it is the leaf of a URL, an editor
+            // fixing a typo in one is routine, and the uniqueness that matters is enforced below
+            // and by the composite index behind it.
+            if (input.slug && input.slug !== row.slug) {
+                const clash = await db.find({ from: "cms_terms", where: { taxonomyId: row.taxonomyId, slug: input.slug }, select: ["id"], limit: 1 });
+                if (clash[0])
+                    throw new Conflict(`term '${input.slug}' already exists in this vocabulary`);
+            }
+            const patch = {};
+            for (const k of ["slug", "label", "description", "parentId", "position"]) {
+                if (input[k] !== undefined)
+                    patch[k] = input[k];
+            }
+            return db.update("cms_terms", input.id, patch);
+        }, {
+            ...editor,
+            input: (raw) => {
+                const o = asObj(raw);
+                if (typeof o.id !== "string" || o.id === "")
+                    throw new BadRequest("id is required");
+                const out = { id: o.id };
+                if (o.slug !== undefined)
+                    out.slug = assertKey(o.slug, "term slug");
+                if (o.label !== undefined)
+                    out.label = assertLabel(o.label, "term label");
+                if (o.description !== undefined)
+                    out.description = typeof o.description === "string" ? o.description : null;
+                if (o.parentId !== undefined)
+                    out.parentId = typeof o.parentId === "string" && o.parentId !== "" ? o.parentId : null;
+                if (typeof o.position === "number")
+                    out.position = Math.trunc(o.position);
+                return out;
+            },
+        }),
+        /** Delete a term. Children are promoted to the top level (`ON DELETE SET NULL`) and
+         * page assignments are removed (`ON DELETE CASCADE`) — see `cms_terms.parentId`. */
+        deleteTerm: mutation(async (ctx, input) => {
+            const ok = await cdb(ctx).delete("cms_terms", input.id);
+            if (!ok)
+                throw notFound("term");
+            return { ok: true };
+        }, {
+            ...editor,
+            input: (raw) => {
+                const id = asObj(raw).id;
+                if (typeof id !== "string" || id === "")
+                    throw new BadRequest("id is required");
+                return { id };
+            },
+        }),
+        /** A page's assigned terms. PUBLIC (a published page's classification is public). */
+        listPageTerms: query(async (ctx, input) => {
+            const db = cdb(ctx);
+            // Read the PAGE first, through `ctx.db`, so the caller's own page scope decides
+            // whether this answers at all. Without it the handler never touched `cms_pages` — and
+            // the public grants on the junction and on terms are unscoped `allow()` — so anyone
+            // holding a page id could read a draft or trashed page's classification, and the
+            // non-empty answer confirmed the page exists. `listPagesByTerm` was already safe for
+            // the opposite reason: it traverses `where: { terms: … }`, so the page scope
+            // AND-merges. This is the same rule, applied from the other end.
+            const page = await db.find({ from: "cms_pages", where: { id: input.pageId }, select: ["id"], limit: 1 });
+            if (!page[0])
+                return [];
+            const links = await db.find({ from: "cms_page_terms", where: { pageId: input.pageId }, select: ["termId"], limit: MAX_TERMS });
+            const ids = links.map((l) => String(l.termId));
+            if (ids.length === 0)
+                return [];
+            const rows = await db.find({ from: "cms_terms", where: { id: { in: ids } }, orderBy: [{ column: "position" }, { column: "label" }], limit: ids.length });
+            return rows;
+        }, {
+            input: (raw) => {
+                const id = asObj(raw).pageId;
+                if (typeof id !== "string" || id === "")
+                    throw new BadRequest("pageId is required");
+                return { pageId: id };
+            },
+        }),
+        /** Replace a page's term assignments wholesale.
+         *
+         * Set semantics, not add/remove: the editor's panel holds the whole selection, and two
+         * calls that each patch one end of it race into a state neither asked for. Existing
+         * links that survive are LEFT ALONE rather than deleted and reinserted, so the junction
+         * rows (and any future column on them) are stable across a save that changed nothing. */
+        setPageTerms: mutation(async (ctx, input) => {
+            const db = cdb(ctx);
+            const pages = await db.find({ from: "cms_pages", where: { id: input.pageId }, select: ["id"], limit: 1 });
+            if (!pages[0])
+                throw notFound("page");
+            const wanted = new Set(input.termIds);
+            if (wanted.size > 0) {
+                // Every id must be a real term. Without this the junction happily stores a dangling
+                // uuid — the FK would catch it, but as a driver error with no HTTP status.
+                const found = await db.find({ from: "cms_terms", where: { id: { in: [...wanted] } }, select: ["id"], limit: wanted.size });
+                if (found.length !== wanted.size)
+                    throw new BadRequest("one or more termIds are not terms");
+            }
+            const existing = await db.find({ from: "cms_page_terms", where: { pageId: input.pageId }, select: ["id", "termId"], limit: MAX_TERMS });
+            const have = new Map(existing.map((l) => [String(l.termId), String(l.id)]));
+            for (const [termId, linkId] of have)
+                if (!wanted.has(termId))
+                    await db.delete("cms_page_terms", linkId);
+            for (const termId of wanted)
+                if (!have.has(termId))
+                    await db.insert("cms_page_terms", { pageId: input.pageId, termId });
+            return { ok: true, count: wanted.size };
+        }, {
+            ...editor,
+            input: (raw) => {
+                const o = asObj(raw);
+                if (typeof o.pageId !== "string" || o.pageId === "")
+                    throw new BadRequest("pageId is required");
+                if (!Array.isArray(o.termIds))
+                    throw new BadRequest("termIds must be a list");
+                const ids = o.termIds.map((v) => {
+                    if (typeof v !== "string" || v === "")
+                        throw new BadRequest("termIds must be a list of ids");
+                    return v;
+                });
+                if (ids.length > MAX_TERMS)
+                    throw new BadRequest(`a page may carry at most ${MAX_TERMS} terms`);
+                return { pageId: o.pageId, termIds: ids };
+            },
+        }),
+        /** Published pages carrying a term. PUBLIC.
+         *
+         * A relation traversal (`where: { terms: { id } }`), so the page read scope is
+         * AND-merged as it is anywhere else — traversal cannot widen access, and an anonymous
+         * caller sees published pages only. */
+        listPagesByTerm: query(async (ctx, input) => {
+            const db = cdb(ctx);
+            const tax = await taxonomyBySlug(db, input.taxonomy);
+            if (!tax)
+                return [];
+            const terms = await db.find({ from: "cms_terms", where: { taxonomyId: tax.id, slug: input.term }, select: ["id"], limit: 1 });
+            const term = terms[0];
+            if (!term)
+                return [];
+            return db.find({
+                from: "cms_pages",
+                where: { terms: { id: String(term.id) } },
+                orderBy: { column: "createdAt", dir: "desc" },
+                select: ["id", "typeId", "title", "slug", "locale", "status", "publishedAt"],
+                limit: input.limit ?? PAGE_LIST_LIMIT,
+                offset: input.offset ?? 0,
+            });
+        }, {
+            input: (raw) => {
+                const o = asObj(raw);
+                return {
+                    taxonomy: assertKey(o.taxonomy, "taxonomy slug"),
+                    term: assertKey(o.term, "term slug"),
+                    limit: clampLimit(o.limit),
+                    offset: typeof o.offset === "number" && o.offset > 0 ? Math.floor(o.offset) : 0,
+                };
+            },
+        }),
+        // ---- site furniture: widget areas ----------------------------------------
+        /** One widget area, with `menu` widgets resolved to their menus. PUBLIC.
+         *
+         * `null` for an unknown name, for the same reason `getMenu` returns null: a layout
+         * asking for a sidebar nobody has filled in yet is the normal state of a site under
+         * construction, and throwing there takes down the page. */
+        getWidgetArea: query(async (ctx, input) => {
+            const db = cdb(ctx);
+            const rows = await db.find({ from: "cms_widget_areas", where: { name: input.name }, limit: 1 });
+            const row = rows[0];
+            if (!row)
+                return null;
+            const widgets = Array.isArray(row.widgets) ? row.widgets : [];
+            // Resolved inline so a layout renders a whole sidebar from ONE call. A menu widget
+            // that names a menu which no longer exists keeps `menu: null` rather than being
+            // dropped — unlike a menu ITEM, an empty widget is a visible hole an editor can see
+            // and fix, where a silently missing one is not.
+            const names = [...new Set(widgets.filter((w) => w.type === "menu" && w.menuName).map((w) => w.menuName))];
+            const menus = new Map();
+            if (names.length > 0) {
+                const found = await db.find({ from: "cms_menus", where: { name: { in: names } }, limit: names.length });
+                // RESOLVED, exactly as `getMenu` returns it. Embedding the raw row here served an
+                // unpublished page's label and id to anonymous callers and handed the layout an
+                // item with no `url` — the two things the resolver exists to prevent, skipped
+                // because this path had its own one-line copy of "read the menu".
+                for (const m of found)
+                    menus.set(String(m.name), await resolveMenuRow(db, m));
+            }
+            return {
+                id: String(row.id),
+                name: String(row.name),
+                label: String(row.label),
+                description: row.description == null ? null : String(row.description),
+                widgets: widgets.map((w) => (w.type === "menu" && w.menuName ? { ...w, menu: menus.get(w.menuName) ?? null } : w)),
+            };
+        }, {
+            input: (raw) => ({ name: assertKey(asObj(raw).name, "widget area name") }),
+        }),
+        listWidgetAreas: query((ctx) => cdb(ctx).find({ from: "cms_widget_areas", orderBy: { column: "label" }, limit: PAGE_LIST_MAX_LIMIT }), viewer),
+        createWidgetArea: mutation(async (ctx, input) => {
+            const db = cdb(ctx);
+            const clash = await db.find({ from: "cms_widget_areas", where: { name: input.name }, select: ["id"], limit: 1 });
+            if (clash[0])
+                throw new Conflict(`widget area '${input.name}' already exists`);
+            return db.insert("cms_widget_areas", {
+                name: input.name,
+                label: input.label,
+                description: input.description ?? null,
+                widgets: input.widgets ?? [],
+            });
+        }, {
+            ...editor,
+            input: (raw) => {
+                const o = asObj(raw);
+                return {
+                    name: assertKey(o.name, "widget area name"),
+                    label: assertLabel(o.label, "widget area label"),
+                    description: typeof o.description === "string" ? o.description : undefined,
+                    widgets: normalizeWidgets(o.widgets, rtSchema),
+                };
+            },
+        }),
+        updateWidgetArea: mutation(async (ctx, input) => {
+            const db = cdb(ctx);
+            const rows = await db.find({ from: "cms_widget_areas", where: input.id ? { id: input.id } : { name: input.name }, limit: 1 });
+            const row = rows[0];
+            if (!row)
+                throw notFound("widget area");
+            const patch = { updatedAt: nowStamp(), version: nextVersion(row, input.expectedVersion, "this widget area") };
+            for (const k of ["label", "description", "widgets"]) {
+                if (input[k] !== undefined)
+                    patch[k] = input[k];
+            }
+            return db.update("cms_widget_areas", String(row.id), patch);
+        }, {
+            ...editor,
+            input: (raw) => {
+                const o = asObj(raw);
+                const out = {};
+                if (typeof o.id === "string")
+                    out.id = o.id;
+                else if (typeof o.name === "string")
+                    out.name = assertKey(o.name, "widget area name");
+                else
+                    throw new BadRequest("id or name is required");
+                if (o.label !== undefined)
+                    out.label = assertLabel(o.label, "widget area label");
+                if (o.description !== undefined)
+                    out.description = typeof o.description === "string" ? o.description : null;
+                if (o.widgets !== undefined)
+                    out.widgets = normalizeWidgets(o.widgets, rtSchema);
+                if (typeof o.expectedVersion === "number")
+                    out.expectedVersion = o.expectedVersion;
+                return out;
+            },
+        }),
+        deleteWidgetArea: mutation(async (ctx, input) => {
+            const ok = await cdb(ctx).delete("cms_widget_areas", input.id);
+            if (!ok)
+                throw notFound("widget area");
+            return { ok: true };
+        }, {
+            ...editor,
+            input: (raw) => {
+                const id = asObj(raw).id;
+                if (typeof id !== "string" || id === "")
+                    throw new BadRequest("id is required");
+                return { id };
             },
         }),
         // ---- media library ----
@@ -1652,7 +3404,30 @@ export function createCmsHandlers(opts = {}) {
          * feature would render N tabs all showing every type's pages under a heading claiming
          * otherwise — and "New page" from any of them would stamp that tab's type. Declared, not
          * inferred: fail closed on the pooled list rather than open on N lying ones. */
-        listCmsCapabilities: query(() => ({ locales, defaultLocale, multilingual: locales.length > 1, pagesByType: true }), viewer),
+        listCmsCapabilities: query((ctx) => ({
+            locales,
+            defaultLocale,
+            multilingual: locales.length > 1,
+            pagesByType: true,
+            // Same kind of declaration as `pagesByType`, for the same reason: an OLDER server has
+            // no menu/redirect/taxonomy/widget handlers at all, and a nav section whose every
+            // screen 404s is worse than one that is absent. Fails closed by being absent there.
+            siteFurniture: true,
+            // Whether `managedBy` means anything on this server. Declared for the same reason as
+            // its neighbours: `@pramen/cms-editor` is a separate package with no dependency on
+            // `@pramen/cms`, so a newer editor CAN run against an older server — where every row
+            // reports no owner, nothing renders read-only, the save succeeds, and it is reverted at
+            // the next cold start. That is GitHub #48 in the deployment that upgraded the editor to
+            // fix it. Absent ⇒ the editor treats no type as code-defined, which is correct there.
+            codeDefinedTypes: true,
+            // PER-CALLER, unlike everything else here. `viewer` is `editorRoles ∪ reviewerRoles`,
+            // so a reviewer-only session reaches this handler and every read handler — but every
+            // WRITE is `editorRoles`. Without this the editor renders the authoring surfaces
+            // (Types, Menus, Redirects, …) for a reviewer and each one 403s on its first save.
+            // The editor cannot work it out for itself: it knows the caller's roles from `me` but
+            // not which roles this deployment configured as `editorRoles`.
+            canEdit: isEditor(ctx, editorRoles),
+        }), viewer),
         /** Distinct locales present across all pages. NOTE: a DATA query — what is in the
          * store — not configuration. `listCmsCapabilities().locales` is what the deployment
          * declares; these two differ while a locale is declared but not yet authored. */
@@ -2024,10 +3799,11 @@ export function createCmsHandlers(opts = {}) {
             const secret = previewSecret(ctx.env);
             if (!secret)
                 throw previewUnconfigured(); // fail closed — never mint a forgeable link
-            // The redeem route always reaches a Durable Object (callPrivileged -> PRAMEN.get); it
-            // has no notion of `x-pramen-store`. Minting on the D1 store therefore produces a
-            // link that 404s forever while the editor reports success — refuse instead of
-            // handing out a token that cannot work.
+            // This used to refuse on the D1 store: redemption goes through `ctx.callPrivileged`,
+            // which only forwarded to a DO, so a link minted on D1 would have 404'd forever while
+            // the editor reported success. `callPrivileged` now dispatches locally in the Worker
+            // on D1, so both stores mint. The redeem route is a BROWSER request carrying no
+            // `x-pramen-store`, so a D1 deployment still needs `PRAMEN_STORE=d1` to route it.
             const db = cdb(ctx);
             // Read the page through the ACL first: minting a link is granting access to it, so a
             // caller who cannot read the page must not be able to mint a link that can.
@@ -2255,7 +4031,12 @@ export function cmsPolicies(opts = {}) {
     // any app handler, silently overriding the read+create grant `collectionPolicies` emits —
     // duplicate policies on the same (role, entity, action) OR-merge, so the wider one wins.
     // The collection half owns that table's grant; see `collectionPolicies`.
-    const tables = ["cms_content_types", "cms_block_types", "cms_blocks", "cms_pages", "cms_page_blocks", "cms_page_revisions", "cms_media", "cms_audit"];
+    const tables = [
+        "cms_content_types", "cms_block_types", "cms_blocks", "cms_pages", "cms_page_blocks", "cms_page_revisions", "cms_media", "cms_audit",
+        // Site furniture. Full CRUD for an editor, like every other cms_ table — the per-handler
+        // `auth` gate is what separates editor from reviewer; this is the row scope.
+        "cms_menus", "cms_redirects", "cms_taxonomies", "cms_terms", "cms_page_terms", "cms_widget_areas",
+    ];
     // Soft-deleted rows are filtered in the ACL, not in each handler. A read scope is
     // AND-merged into every `ctx.db` read, so one policy hides a trashed row from the public
     // API, the editor, relation traversals and eager-loads at once — where a per-handler
@@ -2295,10 +4076,47 @@ export function cmsPolicies(opts = {}) {
             policy(`${p}:public:revisions:read`, "cms_page_revisions", "read", { where: { page: { status: "published", deletedAt: { isNull: true } } } }),
             // Media metadata is public (the bytes are separately gated by signed urls).
             policy(`${p}:public:media:read`, "cms_media", "read", { where: { deletedAt: { isNull: true } } }),
+            // --- site furniture ---
+            // A menu is site chrome, rendered on every page. `getMenu` resolves its page
+            // references THROUGH `ctx.db`, so the public page scope above is what decides whether
+            // a link to an unpublished page renders — the menu grant does not widen it.
+            policy(`${p}:public:menus:read`, "cms_menus", "read", allow()),
+            // Only ENABLED redirects. `resolveRedirect` also filters, but the scope is the real
+            // boundary: a disabled redirect is one an editor has deliberately taken out of
+            // service, and it must stay invisible to every anonymous read, not just that one.
+            policy(`${p}:public:redirects:read`, "cms_redirects", "read", { where: { enabled: true } }),
+            // Taxonomies and terms are structural (they are URL segments a front end routes on),
+            // exactly like content-type slugs. The junction is granted too, because
+            // `where: { terms: … }` on a page compiles to a subquery THROUGH it — without the
+            // grant the traversal matches nothing and "pages in this category" is silently empty.
+            policy(`${p}:public:taxonomies:read`, "cms_taxonomies", "read", allow()),
+            policy(`${p}:public:terms:read`, "cms_terms", "read", allow()),
+            policy(`${p}:public:page-terms:read`, "cms_page_terms", "read", allow()),
+            policy(`${p}:public:widget-areas:read`, "cms_widget_areas", "read", allow()),
         ],
         editor: editorPolicies,
     };
 }
+// --- collections: edit arbitrary pramen entities in the CMS editor -----------
+//
+// The block/page model is one opinionated shape (a routable page with a mandatory slug +
+// regions of blocks). A COLLECTION is the generic escape hatch: it points the editor at
+// one of YOUR OWN pramen entities (spread into defineSchema alongside cmsSchema) and
+// describes how to edit it with the SAME field DSL that blocks use. So "Lectures" is a
+// first-class, queryable entity — real columns, relations, cell-ACL — that also gets a
+// list + form UI, without being bent into a cms_pages row.
+//
+// Column-mapped: each scalar FieldDefinition.name is a real column on the entity; a
+// repeater/group/richtext field maps to a t.json() column (the object↔JSON codec at the
+// Db chokepoint stores it transparently). `richtext` belongs with the latter group — its
+// value is a document tree, and a TEXT column would bind the object raw and be rejected. The generic handlers dispatch through a registry
+// keyed by `slug`, so `collection`/`entity` can never be spoofed to reach an arbitrary
+// table, and writes are whitelisted to declared fields — the client can't set columns the
+// collection didn't declare (e.g. a `roles` or `passwordHash` column on the entity).
+/** Nav positions for the editor's built-in sections — see `./nav`. Re-exported here so a
+ * host writing `app.ts` imports it from the same place as `collection()`. It LIVES in a leaf
+ * module because `blockkit.ts` needs it too and must not depend on this one. */
+export { NAV_ORDER } from "./nav";
 /** Declare a collection. Spread the results into `createCollectionHandlers` +
  * `collectionPolicies`:
  *
@@ -2322,6 +4140,7 @@ function collectionMeta(c) {
         label: c.label,
         pluralLabel: c.pluralLabel ?? `${c.label}s`,
         icon: c.icon,
+        navOrder: c.navOrder ?? NAV_ORDER.collections,
         fields: c.fields,
         list: c.list ?? [titleField],
         titleField,
@@ -2355,10 +4174,6 @@ export const COLLECTION_PUBLISHED = "published";
  * (GitHub #22), and `LIMIT -1` is SQLite for "no limit". */
 const DEFAULT_COLLECTION_LIST_LIMIT = 100;
 const MAX_COLLECTION_LIST_LIMIT = 500;
-/** An ISO-8601 UTC instant — the one format every managed collection timestamp is written
- * in, so it compares correctly against `$now()`. See the note above on why this is not
- * `nowStamp()`. */
-const isoStamp = () => new Date().toISOString();
 /** The epoch-ms range a schedule may name: 1970-01-01 up to (not including) year 10000.
  *
  * `Number.isFinite` is NOT a sufficient bound, in two directions. Above `8.64e15` (the max
@@ -2398,9 +4213,21 @@ const COLLECTION_FIELD_COLUMN_TYPES = {
     slug: ["text"],
     media: ["text", "uuid"],
     select: ["text"],
+    // A SINGLE reference is one opaque id in a TEXT column. `multiple: true` stores an array
+    // and needs `t.json()` — `referenceColumnTypes` below is what actually decides, because
+    // this table is keyed by type alone and a reference is the one type whose storage depends
+    // on a second flag.
+    reference: ["text", "uuid"],
     repeater: ["json"],
     group: ["json"],
 };
+/** The column types a field can be stored in, including the one case the type alone does
+ * not settle (`reference` + `multiple`). */
+function fieldColumnTypes(f) {
+    if (f.type === "reference" && f.multiple)
+        return ["json"];
+    return COLLECTION_FIELD_COLUMN_TYPES[f.type];
+}
 /** Check a collection registry at BOOT: slugs and entities are unique, features are known
  * and have their prerequisites, every declared field maps to a column that can hold it, and
  * every managed column exists, has the shape the CMS writes, and is not also an editable
@@ -2485,7 +4312,7 @@ export function validateCollections(collections, schema) {
             if (!col) {
                 throw new Error(`pramen/cms: collection '${c.slug}' declares a field '${f.name}', which is not a column on '${c.entity}' — a collection field is column-mapped, so every declared field needs its own column`);
             }
-            const allowed = COLLECTION_FIELD_COLUMN_TYPES[f.type];
+            const allowed = fieldColumnTypes(f);
             if (allowed && !allowed.includes(col.type)) {
                 const want = allowed.map((t) => `t.${t === "integer" ? "int" : t === "boolean" ? "bool" : t}()`).join(" or ");
                 throw new Error(`pramen/cms: collection '${c.slug}' declares '${f.name}' as '${f.type}', which is stored as ${allowed.join("/")}, but '${c.entity}.${f.name}' is ${col.type} — declare it as ${want}`);
@@ -3093,7 +4920,7 @@ export function createCollectionHandlers(collections, opts = {}) {
         }),
         // ---- preview ------------------------------------------------------------
         /** Mint a signed link that shows ONE row's unpublished state, to whoever holds it.
-         * Mirrors `signPagePreview` — same secret, same TTL clamp, same D1 refusal, and the
+         * Mirrors `signPagePreview` — same secret, same TTL clamp, works on both stores, and the
          * same rule that the row is read through the ACL FIRST: minting a link is granting
          * access to the row, so a caller who cannot read it must not be able to mint one. */
         signCollectionPreview: query(async (ctx, input) => {