@pramen/cms 0.0.49 → 0.0.51

package/dist/index.js

@@ -24,8 +24,8 @@
 //   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, BadRequest, Forbidden, PramenError, } from "@pramen/server";
-import { filterXSS } from "xss";
+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 { isSafeHref, normalizeHref } from "./href";
 /** Declare a typed block type. Pass `fields as const` to preserve the literals so
  * `BlockFieldsOf<typeof def>` infers the field shape:
  *
@@ -137,11 +137,49 @@ function tsTypeOf(f) {
             return "unknown";
     }
 }
+/** Which imported helper types a field schema actually needs, found by walking the tree
+ * (group/repeater nest, so a `richtext` three levels down still counts). Order is stable
+ * so the emitted import line does not churn between runs. */
+function referencedHelperTypes(fields) {
+    const found = new Set();
+    const walk = (defs) => {
+        for (const f of defs) {
+            if (f.type === "richtext")
+                found.add("RichText");
+            else if (f.type === "media")
+                found.add("ResolvedMedia");
+            else if (f.fields)
+                walk(f.fields);
+        }
+    };
+    walk(fields);
+    return ["ResolvedMedia", "RichText"].filter((t) => found.has(t));
+}
 const tsFieldLine = (f) => `${JSON.stringify(f.name)}${f.required ? "" : "?"}: ${tsTypeOf(f)};`;
 /** Emit a `.ts` module of per-slug field interfaces + a `BlockFieldsBySlug` registry from
  * DB-stored block types (`{ slug, fieldsSchema }` rows). The runtime counterpart to the
  * compile-time `InferBlockFields`, for webmaster-authored (data-driven) block types. */
 export function generateBlockTypes(blockTypes) {
+    // Slugs are webmaster-authored with no deploy, so they are not guaranteed to map to a
+    // valid or DISTINCT TypeScript identifier: "2-col" -> `interface 2ColFields` is a syntax
+    // error, and "rich-text"/"rich_text" both -> `RichTextFields`. Fail with the offending
+    // slugs rather than emit a file that does not parse.
+    const seen = new Map();
+    const bad = [];
+    for (const bt of blockTypes) {
+        const name = pascal(bt.slug);
+        // Unicode-aware: `úvodní-blok` -> `úvodníBlok` IS a legal TypeScript identifier, and an
+        // ASCII-only test rejected it — aborting codegen for the WHOLE tenant over a slug that
+        // works, with no fix short of renaming production data.
+        if (!/^[\p{ID_Start}$_][\p{ID_Continue}$]*$/u.test(name))
+            bad.push(`${bt.slug} (-> '${name}', not an identifier)`);
+        else if (seen.has(name))
+            bad.push(`${bt.slug} (-> '${name}', collides with '${seen.get(name)}')`);
+        else
+            seen.set(name, bt.slug);
+    }
+    if (bad.length)
+        throw new BadRequest(`cannot generate types for block type slug(s): ${bad.join("; ")}`);
     const interfaces = blockTypes
         .map((bt) => {
         const fields = Array.isArray(bt.fieldsSchema) ? bt.fieldsSchema : [];
@@ -150,9 +188,16 @@ export function generateBlockTypes(blockTypes) {
     })
         .join("\n\n");
     const registry = blockTypes.map((bt) => `  ${JSON.stringify(bt.slug)}: ${pascal(bt.slug)}Fields;`).join("\n");
-    return (`// AUTO-GENERATED by @pramen/cms — do not edit.\n` +
-        `import type { ResolvedMedia, RichText } from "@pramen/cms";\n\n` +
-        `${interfaces}\n\nexport interface BlockFieldsBySlug {\n${registry}\n}\n`);
+    // Import ONLY what the emitted interfaces reference: every tsconfig in this repo sets
+    // `noUnusedLocals`, so an unconditional import is a guaranteed TS6192 build break in the
+    // consumer's own project — for a file they are told not to edit.
+    //
+    // Walk the SCHEMA rather than regexing the rendered text: field names are printed into
+    // the output, so a field literally named `RichText` matched a `\bRichText\b` scan and
+    // produced the unused import this exists to avoid.
+    const used = referencedHelperTypes(blockTypes.flatMap((bt) => (Array.isArray(bt.fieldsSchema) ? bt.fieldsSchema : [])));
+    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
@@ -184,6 +229,9 @@ export const cmsSchema = {
         title: t.text(),
         fields: t.json(), // content matching the block type's fieldsSchema
         isReusable: defaultTo(t.bool(), false),
+        // Optimistic concurrency: bumped on every edit. A caller may pass the version it
+        // read as `expectedVersion` and get a 409 instead of silently clobbering.
+        version: defaultTo(t.int(), 1),
         createdAt: defaultTo(t.text(), expr.now()),
         updatedAt: defaultTo(t.text(), expr.now()),
     }), (r) => ({ type: r.belongsTo("cms_block_types", "typeId") })),
@@ -209,6 +257,11 @@ export const cmsSchema = {
         // (not "latest by timestamp") so selection is deterministic even when two publishes
         // land in the same second (expr.now() is second-precision).
         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
+        // page disappears from the public API and the editor alike without a single handler
+        // remembering to filter. `restorePage` clears it; `purgePage` removes the row.
+        deletedAt: indexed(t.text()),
         // SEO
         metaTitle: t.text(),
         metaDescription: t.text(),
@@ -218,6 +271,8 @@ export const cmsSchema = {
         ogDescription: t.text(),
         ogImage: t.uuid(), // a cms_media id, resolved to a URL at assemble time
         structuredData: t.json(), // JSON-LD, emitted as-is into <head>
+        // Optimistic concurrency — see cms_blocks.version.
+        version: defaultTo(t.int(), 1),
         createdAt: defaultTo(t.text(), expr.now()),
         updatedAt: defaultTo(t.text(), expr.now()),
     }), (r) => ({
@@ -261,12 +316,52 @@ export const cmsSchema = {
         note: t.text(),
         createdAt: defaultTo(t.text(), expr.now()),
     })),
+    // Revision history for COLLECTION rows (`supports: ["revisions"]`). One shared table
+    // rather than one per collection: a collection targets an arbitrary app entity, so there
+    // is no place to hang a per-entity revisions table and no way to declare a real FK to a
+    // target that varies. `collection` + `rowId` identify the subject; `rowId` is TEXT
+    // because a collection's PK may be a uuid or a textId.
+    //
+    // A revision holds the row's state BEFORE the write that created it, projected to the
+    // collection's declared fields — so restoring one is a plain reversal, and a snapshot
+    // taken before a field was dropped from `fields` cannot resurrect that column (restore
+    // replays through the same write whitelist).
+    cms_collection_revisions: Entity((t) => ({
+        id: primaryKey(generated(t.uuid())),
+        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.
+        //
+        // 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
+        // transactions), so two concurrent updates in different isolates can read the same MAX.
+        // The composite unique below is what makes that a visible failure instead of a silent
+        // duplicate that quietly restores the ordering ambiguity this column exists to remove.
+        revision: notNull(t.int()),
+        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.
+        createdAt: t.text(),
+    }), undefined, { unique: [["collection", "rowId", "revision"]] }),
     // 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) => ({
         id: primaryKey(generated(t.uuid())),
         file: t.fileRef(),
         alt: t.text(),
+        // Soft delete, as on cms_pages. The R2 OBJECT is deliberately kept while a media row
+        // is trashed — deleting the bytes would make restore a lie. `purgeMedia` drops both.
+        deletedAt: indexed(t.text()),
         createdAt: defaultTo(t.text(), expr.now()),
     })),
 };
@@ -320,8 +415,19 @@ export function validateFields(schema, values, path = "", opts = {}) {
                     throw new BadRequest(`field '${at}' must be a slug (lowercase letters, digits and single hyphens)`);
                 break;
             case "richtext":
-                if (typeof v !== "string" && typeof v !== "object")
-                    throw new BadRequest(`field '${at}' must be rich text`);
+                // A document tree, never a string. A legacy HTML value is REJECTED rather than
+                // silently normalized to an empty doc — a 400 names the migration; a blank field
+                // would look like the content simply vanished. Except where the bag carries stored
+                // data the caller never sent (see `legacyBaseline`).
+                if (typeof v === "string") {
+                    // Tolerated only if it is exactly what is already stored for this field.
+                    if (opts.legacyBaseline && opts.legacyBaseline[def.name] === v)
+                        break;
+                    throw new BadRequest(`field '${at}' must be a rich-text document, not an HTML string`);
+                }
+                if (typeof v !== "object" || Array.isArray(v) || v.type !== "doc") {
+                    throw new BadRequest(`field '${at}' must be a rich-text document ({ type: "doc", content: [...] })`);
+                }
                 break;
             case "number":
                 if (typeof v !== "number")
@@ -347,9 +453,18 @@ export function validateFields(schema, values, path = "", opts = {}) {
                 if (typeof v !== "string")
                     throw new BadRequest(`field '${at}' must be a media id (string)`);
                 break;
-            case "group":
-                validateFields(def.fields, v, at, opts);
+            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
+                // stored bag back — and placeBlock, which merges the block's OWN stored fields,
+                // could not place such a block at all. No editor can fix that: none ever mounted it.
+                const nested = opts.legacyBaseline?.[def.name];
+                validateFields(def.fields, v, at, {
+                    requireRequired: opts.requireRequired,
+                    legacyBaseline: nested && typeof nested === "object" && !Array.isArray(nested) ? nested : undefined,
+                });
                 break;
+            }
             case "repeater": {
                 if (!Array.isArray(v))
                     throw new BadRequest(`field '${at}' must be a list`);
@@ -357,7 +472,19 @@ export function validateFields(schema, values, path = "", opts = {}) {
                     throw new BadRequest(`field '${at}' needs at least ${def.min} item(s)`);
                 if (def.max != null && v.length > def.max)
                     throw new BadRequest(`field '${at}' allows at most ${def.max} item(s)`);
-                v.forEach((item, i) => validateFields(def.fields, item, `${at}[${i}]`, opts));
+                {
+                    // Per-item baseline, positionally — a repeater item that kept its slot keeps its
+                    // stored value, so an untouched legacy value inside one still validates.
+                    const base = opts.legacyBaseline?.[def.name];
+                    const baseItems = Array.isArray(base) ? base : [];
+                    v.forEach((item, i) => {
+                        const bi = baseItems[i];
+                        validateFields(def.fields, item, `${at}[${i}]`, {
+                            requireRequired: opts.requireRequired,
+                            legacyBaseline: bi && typeof bi === "object" && !Array.isArray(bi) ? bi : undefined,
+                        });
+                    });
+                }
                 break;
             }
             default:
@@ -365,40 +492,203 @@ export function validateFields(schema, values, path = "", opts = {}) {
         }
     }
 }
-// --- rich-text sanitization (server-side — the real XSS boundary) -------------
-//
-// richtext fields are HTML the site renders with set:html, so they MUST be sanitized
-// before persistence. Client-side scrubbing is not a boundary — a caller can POST any
-// value straight to these handlers. We sanitize on write against a strict tag/attribute
-// allow-list with js-xss (`xss`), which is SYNCHRONOUS and pure-JS — this matters because
-// sanitize runs inside the DO's storage.transaction(), where async stream I/O (e.g.
-// HTMLRewriter) deadlocks. js-xss drops disallowed tags/attributes and blanks
-// javascript:/data: URLs in href/src by default.
-const RT_WHITELIST = {
-    p: [], br: [], hr: [], blockquote: [], pre: [], code: [],
-    strong: [], b: [], em: [], i: [], u: [], s: [], strike: [], del: [], ins: [], mark: [], sub: [], sup: [],
-    h2: [], h3: [], h4: [], ul: [], ol: [], li: [], a: ["href", "title"],
+/** 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. */
+/** Highest heading level the shipped editor is configured for (StarterKit levels [1,2,3]). */
+export const MAX_HEADING_LEVEL = 3;
+export const DEFAULT_RICH_TEXT_SCHEMA = {
+    nodes: {
+        // NOTE: no `doc`. normalizeRichText builds the root itself and never looks it up, so
+        // an entry here would only ever authorize a NESTED doc — which TipTap cannot render
+        // (Document declares no renderHTML), blanking the field in the editor while the site
+        // renderers still showed the subtree. The first keystroke then saved the blank over it.
+        paragraph: [],
+        text: [],
+        hardBreak: [],
+        horizontalRule: [],
+        heading: ["level"],
+        blockquote: [],
+        codeBlock: ["language"],
+        bulletList: [],
+        orderedList: ["start"],
+        listItem: [],
+        taskList: [],
+        taskItem: ["checked"],
+    },
+    marks: {
+        bold: [],
+        italic: [],
+        underline: [],
+        strike: [],
+        code: [],
+        highlight: ["color"],
+        link: ["href", "title", "target"],
+    },
 };
-const RT_XSS_OPTS = { whiteList: RT_WHITELIST, stripIgnoreTag: true, stripIgnoreTagBody: ["script", "style"] };
-/** Sanitize one richtext HTML string to the allow-list. Synchronous by design. */
-function sanitizeRichText(html) {
-    return html ? filterXSS(html, RT_XSS_OPTS) : html;
+// Re-exported from the leaf module `./href` so `@pramen/cms/react` can import them at
+// runtime without dragging this file (and the whole server SDK) into a browser bundle.
+export { isSafeHref, normalizeHref } from "./href";
+/** Keep only the declared attributes, and only those holding a JSON primitive — an object
+ * or array in an attr is never something the editor emits, so it is smuggled payload. */
+/** Look a type up in an allow-list WITHOUT walking the prototype chain. A plain-object
+ * index resolves `constructor` / `toString` / `valueOf` to inherited members, which are
+ * truthy — so `{ type: "constructor" }` passed the gate and was stored, and its "allowed
+ * attributes" became the `Object` function (length 1, not iterable), throwing a TypeError
+ * inside the DO's storage.transaction(). Both renderers and TipTap then choke on the
+ * stored node, which bricks the row. */
+function allowedAttrsFor(table, type) {
+    if (typeof type !== "string" || !Object.hasOwn(table, type))
+        return undefined;
+    return table[type];
+}
+function normalizeAttrs(attrs, allowed, maxHeading = MAX_HEADING_LEVEL) {
+    if (!allowed.length || !attrs || typeof attrs !== "object" || Array.isArray(attrs))
+        return undefined;
+    const out = {};
+    for (const name of allowed) {
+        const v = attrs[name];
+        if (v === undefined)
+            continue;
+        if (v !== null && typeof v !== "string" && typeof v !== "number" && typeof v !== "boolean")
+            continue;
+        // CLAMP, don't drop. Dropping `level` left the node level-less, and TipTap's Heading
+        // declares `level: { default: 1 }` — so an imported h4 still opened as h1 and the next
+        // autosave still persisted h1, while the renderers fell back to h2. Same silent
+        // mutation the narrowing was meant to stop, plus an editor/site mismatch.
+        if (name === "level") {
+            if (typeof v !== "number" || !Number.isInteger(v))
+                continue;
+            out[name] = Math.min(Math.max(v, 1), maxHeading);
+            continue;
+        }
+        out[name] = v;
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+/** Drop unknown marks and any `link` whose href fails the scheme allow-list (dropping the
+ * whole mark, not just the href — an anchor with no destination is worse than plain text). */
+function normalizeMarks(marks, schema) {
+    if (!Array.isArray(marks))
+        return undefined;
+    const out = [];
+    for (const raw of marks) {
+        if (!raw || typeof raw !== "object")
+            continue;
+        const mark = raw;
+        const allowed = allowedAttrsFor(schema.marks, mark.type);
+        if (!allowed)
+            continue;
+        const attrs = normalizeAttrs(mark.attrs, allowed, schema.maxHeadingLevel);
+        if (mark.type === "link") {
+            if (!isSafeHref(attrs?.href))
+                continue;
+            // Persist the parser-normalized form, so what was validated is what resolves.
+            if (attrs && typeof attrs.href === "string")
+                attrs.href = normalizeHref(attrs.href);
+        }
+        out.push(attrs ? { type: mark.type, attrs } : { type: mark.type });
+    }
+    return out.length ? out : undefined;
+}
+/** How deep a document may nest before the normalizer stops descending. Real editor output
+ * is a handful of levels (list > item > paragraph > text); a hand-crafted doc nested tens
+ * of thousands deep would otherwise blow the stack INSIDE the DO's storage.transaction().
+ * JSON.parse is iterative in V8, so such a payload reaches the normalizer intact. */
+export const MAX_RICH_TEXT_DEPTH = 100;
+/** Normalize one node, or `null` if its type is not in the schema. */
+function normalizeNode(raw, schema, depth = 0) {
+    if (depth > MAX_RICH_TEXT_DEPTH)
+        return null;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const node = raw;
+    const allowed = allowedAttrsFor(schema.nodes, node.type);
+    if (!allowed)
+        return null;
+    const out = { type: node.type };
+    if (node.type === "text") {
+        // A text node with no string — or an EMPTY one — is not text. ProseMirror forbids an
+        // empty text node outright (`schema.text("")` throws "Empty text nodes are not
+        // allowed"), and the editor builds its document inside a useState initializer, so a
+        // stored `{type:"text",text:""}` would throw during render and take the edit UI down
+        // for that row permanently.
+        if (typeof node.text !== "string" || node.text === "")
+            return null;
+        out.text = node.text;
+        const marks = normalizeMarks(node.marks, schema);
+        if (marks)
+            out.marks = marks;
+    }
+    const attrs = normalizeAttrs(node.attrs, allowed, schema.maxHeadingLevel);
+    if (attrs)
+        out.attrs = attrs;
+    if (Array.isArray(node.content)) {
+        const content = normalizeNodes(node.content, schema, depth + 1);
+        if (content.length)
+            out.content = content;
+    }
+    return out;
+}
+function normalizeNodes(nodes, schema, depth = 0) {
+    const out = [];
+    for (const n of nodes) {
+        const node = normalizeNode(n, schema, depth);
+        if (node)
+            out.push(node);
+    }
+    return out;
+}
+/** Normalize a rich-text value to a document the renderers can trust. A value that is not
+ * a doc at all yields an empty doc — `validateFields` rejects those first, so in handler
+ * flow this only ever sees a doc; the fallback is for direct callers. */
+export function normalizeRichText(value, schema = DEFAULT_RICH_TEXT_SCHEMA) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return { type: "doc", content: [] };
+    const content = Array.isArray(value.content) ? normalizeNodes(value.content ?? [], schema) : [];
+    return { type: "doc", content };
 }
-/** Deep-sanitize the richtext fields in a values object against a field schema (recursing
- * into group/repeater). Returns a sanitized copy; non-richtext fields pass through. */
-export function sanitizeFields(schema, values) {
+/** The block-level node types that end a line when flattening to plain text. */
+const RT_BLOCK_TYPES = new Set(["paragraph", "heading", "listItem", "taskItem", "blockquote", "codeBlock", "horizontalRule"]);
+/** Flatten a rich-text document to plain text — for excerpts, meta descriptions, and search
+ * indexing, which want the words without the structure. */
+export function richTextToPlainText(value) {
+    const parts = [];
+    const walk = (nodes) => {
+        for (const node of nodes) {
+            if (node.type === "text")
+                parts.push(node.text ?? "");
+            else if (node.type === "hardBreak")
+                parts.push("\n");
+            if (node.content)
+                walk(node.content);
+            if (RT_BLOCK_TYPES.has(node.type))
+                parts.push("\n");
+        }
+    };
+    walk(value?.content ?? []);
+    // A block inside a block (a paragraph in a list item) closes both, so collapse the run:
+    // every boundary is worth exactly one line break in a flattened excerpt.
+    return parts.join("").replace(/\n{2,}/g, "\n").trim();
+}
+/** Deep-normalize the richtext fields in a values object against a field schema (recursing
+ * into group/repeater). Returns a normalized copy; other field types pass through. */
+export function normalizeFields(schema, values, richTextSchema = DEFAULT_RICH_TEXT_SCHEMA) {
     const defs = Array.isArray(schema) ? schema : [];
     const out = { ...values };
     for (const def of defs) {
         const v = out[def.name];
         if (v == null)
             continue;
-        if (def.type === "richtext" && typeof v === "string")
-            out[def.name] = sanitizeRichText(v);
+        // A legacy HTML string survives normalization untouched: normalizeRichText would turn
+        // it into an EMPTY doc, i.e. silently delete the content. It only reaches here on the
+        // `legacyBaseline` paths, where it is the stored value being echoed back.
+        if (def.type === "richtext")
+            out[def.name] = typeof v === "string" ? v : normalizeRichText(v, richTextSchema);
         else if (def.type === "group" && typeof v === "object" && !Array.isArray(v))
-            out[def.name] = sanitizeFields(def.fields, v);
+            out[def.name] = normalizeFields(def.fields, v, richTextSchema);
         else if (def.type === "repeater" && Array.isArray(v))
-            out[def.name] = v.map((it) => (it && typeof it === "object" ? sanitizeFields(def.fields, it) : it));
+            out[def.name] = v.map((it) => (it && typeof it === "object" ? normalizeFields(def.fields, it, richTextSchema) : it));
     }
     return out;
 }
@@ -533,6 +823,7 @@ async function assembleLive(db, page) {
         (regions[region] ??= []).push({
             id: String(m.p.id),
             block_id: String(m.block.id),
+            version: typeof m.block.version === "number" ? m.block.version : 1,
             block_type: typeById.get(String(m.block.typeId))?.slug ?? "unknown",
             title: m.block.title ?? null,
             fields: resolveMediaFields(m.fields, m.schema, mediaById),
@@ -595,6 +886,7 @@ function pageMeta(page, translations = [], ogImage = null, contentType = null) {
         slug: String(page.slug),
         status: String(page.status),
         locale: String(page.locale ?? "en"),
+        version: typeof page.version === "number" ? page.version : 1,
         contentType,
         translationGroupId: page.translationGroupId ?? null,
         translations,
@@ -635,15 +927,44 @@ async function assertRegionAllows(db, page, region, blockTypeSlug) {
         throw new BadRequest(`block type '${blockTypeSlug}' is not allowed in region '${region}'`);
     }
 }
+/** 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"];
+/** Resolve the preview signing secret, or `undefined` when nothing usable is configured. */
+export function previewSecret(env) {
+    return resolveSecret(env, PREVIEW_SECRET_NAMES);
+}
+const previewUnconfigured = () => new PramenError("page preview is not configured (set a strong PREVIEW_SECRET, FILES_SECRET or AUTH_SECRET)", 503, "unavailable");
+/** The viewer roles for a given handler config — `editorRoles ∪ reviewerRoles`, computed
+ * exactly as `createCmsHandlers` computes them.
+ *
+ * Exported so `cmsRoutes()` cannot drift from `createCmsHandlers()`: pass the SAME options
+ * object to both. Configuring the two independently was how the preview route ended up
+ * presenting an identity neither the handler gate nor the ACL accepted — and a partial
+ * customization still worked, so the failure appeared only for the app that had most
+ * carefully renamed its roles. */
+export function viewerRolesOf(opts = {}) {
+    return [...new Set([...(opts.editorRoles ?? ["editor", "admin"]), ...(opts.reviewerRoles ?? ["reviewer", "admin"])])];
+}
+/** The viewer roles for the DEFAULT handler config. */
+export const DEFAULT_VIEWER_ROLES = viewerRolesOf();
+/** Where a preview link is redeemed. Spread `cmsRoutes()` into `app.routes` to serve it. */
+export const PREVIEW_PATH = "/cms/preview";
+/** Default preview-link lifetime: 1 hour. Long enough to share and open, short enough that
+ * a link pasted into a public channel stops working the same afternoon. */
+export const DEFAULT_PREVIEW_TTL_SECONDS = 3600;
 /** Build the CMS handler map. Spread into your app's handlers. Editor mutations are
  * gated both by `auth` (fast 403 before the body) and by the row ACL (cmsPolicies). */
 export function createCmsHandlers(opts = {}) {
     const editorRoles = opts.editorRoles ?? ["editor", "admin"];
     const editor = { auth: editorRoles };
     const mediaMaxSize = opts.mediaMaxSize ?? 25_000_000;
-    const defaultLocale = opts.defaultLocale ?? "en";
+    const locales = opts.locales && opts.locales.length > 0 ? [...opts.locales] : ["en"];
+    const defaultLocale = locales[0];
     const reviewerRoles = opts.reviewerRoles ?? ["reviewer", "admin"];
     const reviewer = { auth: reviewerRoles };
+    const previewTtl = opts.previewTtlSeconds ?? DEFAULT_PREVIEW_TTL_SECONDS;
+    const rtSchema = opts.richTextSchema ?? DEFAULT_RICH_TEXT_SCHEMA;
     // 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])];
@@ -652,11 +973,83 @@ export function createCmsHandlers(opts = {}) {
     const actorOf = (ctx) => (typeof ctx.identity?.userId === "string" ? ctx.identity.userId : null);
     // Append an audit row for a workflow transition (synchronous, in the mutation's txn).
     const writeAudit = (db, e) => db.insert("cms_audit", { pageId: e.pageId, action: e.action, fromStatus: e.from ?? null, toStatus: e.to ?? null, actor: e.actor, note: e.note ?? null });
+    const mediaIdInput = {
+        input: (raw) => {
+            const o = asObj(raw);
+            if (typeof o.id !== "string" || o.id === "")
+                throw new BadRequest("id is required");
+            return { id: o.id };
+        },
+    };
+    /** Mark a table changed after a RAW `exec` write.
+     *
+     * `Db.exec` is the one write path that does not record `touched`, so the DO never
+     * broadcasts and every live subscriber keeps showing the pre-write state — a restored
+     * page stays missing from an open page list, a purged one stays present. `deletePage`
+     * goes through the ORM and DOES broadcast, so the staleness was asymmetric and read
+     * like a lost write. */
+    const markChanged = (db, ...tables) => {
+        const touched = db.touched;
+        if (touched)
+            for (const t of tables)
+                touched.add(t);
+    };
+    // --- optimistic concurrency ------------------------------------------------
+    //
+    // On the DO — the default store — a read-then-write inside one mutation is atomic: the
+    // Durable Object is a single writer and DoSqliteDriver.exec is synchronous. The EDITORS
+    // are not serialized, though: two people on the same page means last save wins, silently,
+    // with no signal to the loser. Passing back the `version` you read turns that into a 409.
+    //
+    // CAVEAT — the D1 store has no interactive transaction (D1Driver.transaction is a
+    // pass-through), so two requests in the same millisecond can both read and both write.
+    // The guard still catches the human-scale editor race; it is not a hard mutex there.
+    //
+    // Optional by design: omitting `expectedVersion` keeps last-write-wins, so nothing breaks.
+    const nextVersion = (row, expected, label) => {
+        // Do NOT default a missing version to 1. Under a field-restricted read grant that
+        // projected the column away, `current` would be 1 forever: a client that legitimately
+        // read version 7 gets a permanent unresolvable 409, and an unguarded save then LOWERS
+        // the stored version, so a genuinely stale write is accepted later.
+        if (typeof row.version !== "number") {
+            // Log the actionable detail, return a generic 500 — PramenError's message goes to the
+            // caller verbatim, so naming the column would leak the schema and ACL shape.
+            console.error(`pramen/cms: ${label} has no readable version — grant read on the \`version\` column`);
+            throw new Error("version unavailable");
+        }
+        const current = row.version;
+        if (expected !== undefined && expected !== current) {
+            throw new Conflict(`${label} was changed by someone else (you have version ${expected}, current is ${current}) — reload and reapply your edit`);
+        }
+        return current + 1;
+    };
+    const versionInput = (o) => {
+        if (o.expectedVersion === undefined)
+            return;
+        if (typeof o.expectedVersion !== "number" || !Number.isInteger(o.expectedVersion)) {
+            throw new BadRequest("expectedVersion must be an integer");
+        }
+    };
+    const pageIdInput = {
+        input: (raw) => {
+            const o = asObj(raw);
+            if (typeof o.pageId !== "string" || o.pageId === "")
+                throw new BadRequest("pageId is required");
+            return { pageId: o.pageId };
+        },
+    };
     // (slug, locale) uniqueness is enforced here because pramen's unique() is single-column.
     const assertSlugFree = async (db, slug, locale, exceptId) => {
-        const rows = await db.exec("SELECT id FROM cms_pages WHERE slug = ? AND locale = ? LIMIT 1", slug, locale);
-        if (rows[0] && String(rows[0].id) !== exceptId)
+        const rows = await db.exec("SELECT id, deletedAt FROM cms_pages WHERE slug = ? AND locale = ? LIMIT 1", slug, locale);
+        if (rows[0] && String(rows[0].id) !== exceptId) {
+            // A trashed page keeps its slug until purged (the (slug, locale) unique index is a
+            // DB constraint, not advisory). Say so, rather than leave the caller hunting for a
+            // page they cannot see.
+            if (rows[0].deletedAt != null) {
+                throw new BadRequest(`slug '${slug}' is held by a page in the trash for locale '${locale}' — restore or purge it first`);
+            }
             throw new BadRequest(`slug '${slug}' already exists for locale '${locale}'`);
+        }
     };
     const TASK_PUBLISH = "cms:publish";
     const TASK_UNPUBLISH = "cms:unpublish";
@@ -828,18 +1221,20 @@ export function createCmsHandlers(opts = {}) {
                 return { id: o.id, alt: typeof o.alt === "string" ? o.alt : null };
             },
         }),
-        /** Delete a media row AND its R2 blob. (Automatic orphan sweeping — media no longer
-         * referenced by any block — is future work; refs live inside opaque block JSON.) */
+        /** Trash a media row. The R2 OBJECT IS KEPT — deleting the bytes here would make
+         * `restoreMedia` a lie, and a block still referencing the id would render a dead url
+         * with no way back. `purgeMedia` is what drops both — and `listTrash` is how you find
+         * the id again, since every ACL-scoped read hides it from here on.
+         *
+         * (Automatic orphan sweeping — media no longer referenced by any block — is still
+         * future work; refs live inside opaque block JSON.) */
         deleteMedia: mutation(async (ctx, input) => {
             const db = cdb(ctx);
             const rows = await db.find({ from: "cms_media", where: { id: input.id }, limit: 1 });
             const media = rows[0];
             if (!media)
                 throw notFound("media");
-            const key = String(asObj(media.file).key ?? "");
-            await db.delete("cms_media", input.id);
-            if (key)
-                await ctx.files.delete(key).catch(() => { });
+            await db.update("cms_media", input.id, { deletedAt: new Date().toISOString() });
             return { ok: true };
         }, {
             ...editor,
@@ -850,6 +1245,33 @@ export function createCmsHandlers(opts = {}) {
                 return o;
             },
         }),
+        restoreMedia: mutation(async (ctx, input) => {
+            const db = cdb(ctx);
+            const rows = await db.exec("SELECT id FROM cms_media WHERE id = ? AND deletedAt IS NOT NULL LIMIT 1", input.id);
+            if (!rows[0])
+                throw notFound("trashed media");
+            await db.exec("UPDATE cms_media SET deletedAt = NULL WHERE id = ?", input.id);
+            markChanged(db, "cms_media");
+            return { ok: true };
+        }, { ...editor, ...mediaIdInput }),
+        /** Permanently remove trashed media — the row AND the R2 object. Reviewer-gated and
+         * irreversible; the blob is gone. */
+        purgeMedia: mutation(async (ctx, input) => {
+            const db = cdb(ctx);
+            const rows = await db.exec("SELECT id, file FROM cms_media WHERE id = ? AND deletedAt IS NOT NULL LIMIT 1", input.id);
+            const media = rows[0];
+            if (!media)
+                throw notFound("trashed media"); // purging live media is refused — trash it first
+            // `file` comes back raw from exec (the object↔JSON codec sits on the ORM path, not
+            // this one), so parse it before reaching for the key.
+            const file = typeof media.file === "string" ? JSON.parse(media.file) : asObj(media.file);
+            const key = String(file.key ?? "");
+            await db.exec("DELETE FROM cms_media WHERE id = ?", input.id);
+            markChanged(db, "cms_media");
+            if (key)
+                await ctx.files.delete(key).catch(() => { });
+            return { ok: true };
+        }, { ...reviewer, ...mediaIdInput }),
         listContentTypes: query((ctx) => cdb(ctx).find({ from: "cms_content_types", orderBy: { column: "name" } }), viewer),
         getContentType: query(async (ctx, input) => {
             const rows = await cdb(ctx).find({ from: "cms_content_types", where: { id: input.id }, limit: 1 });
@@ -880,7 +1302,11 @@ export function createCmsHandlers(opts = {}) {
         /** Update a page's SEO fields (meta/canonical/robots/OpenGraph/JSON-LD). Editor-gated. */
         updatePageSeo: mutation(async (ctx, input) => {
             const db = cdb(ctx);
-            const patch = { updatedAt: nowStamp() };
+            // Read first so the version can be compared; this patched blind before.
+            const seoRows = await db.find({ from: "cms_pages", where: { id: input.pageId }, limit: 1 });
+            if (!seoRows[0])
+                throw notFound("page");
+            const patch = { updatedAt: nowStamp(), version: nextVersion(seoRows[0], input.expectedVersion, "this page") };
             for (const k of ["metaTitle", "metaDescription", "canonicalUrl", "robots", "ogTitle", "ogDescription", "ogImage"]) {
                 if (k in input)
                     patch[k] = input[k];
@@ -897,6 +1323,7 @@ export function createCmsHandlers(opts = {}) {
                 const o = asObj(raw);
                 if (typeof o.pageId !== "string")
                     throw new BadRequest("pageId is required");
+                versionInput(o);
                 return o;
             },
         }),
@@ -905,14 +1332,14 @@ export function createCmsHandlers(opts = {}) {
          * Blocks are edited via addBlock/updateBlock; SEO via updatePageSeo; this covers the
          * page record itself, which was previously only settable at createPage. A slug/locale
          * change re-checks (slug, locale) uniqueness (excluding this page); `fields` is validated
-         * + sanitized against the content type's fieldsSchema, exactly like createPage. */
+         * + normalized against the content type's fieldsSchema, exactly like createPage. */
         updatePage: mutation(async (ctx, input) => {
             const db = cdb(ctx);
             const rows = await db.find({ from: "cms_pages", where: { id: input.pageId }, limit: 1 });
             const page = rows[0];
             if (!page)
                 throw notFound("page");
-            const patch = { updatedAt: nowStamp() };
+            const patch = { updatedAt: nowStamp(), version: nextVersion(page, input.expectedVersion, "this page") };
             if (input.title !== undefined)
                 patch.title = input.title;
             if (input.slug !== undefined || input.locale !== undefined) {
@@ -927,8 +1354,9 @@ export function createCmsHandlers(opts = {}) {
             if (input.fields !== undefined) {
                 const ctRows = await db.find({ from: "cms_content_types", where: { id: page.typeId }, limit: 1 });
                 const schema = ctRows[0]?.fieldsSchema;
-                validateFields(schema, input.fields, "page.fields", { requireRequired: false });
-                patch.fields = await sanitizeFields(schema, input.fields);
+                // Same whole-bag autosave as updateBlock — tolerate a stored legacy value.
+                validateFields(schema, input.fields, "page.fields", { requireRequired: false, legacyBaseline: asObj(page.fields) });
+                patch.fields = normalizeFields(schema, input.fields, rtSchema);
             }
             const updated = await db.update("cms_pages", input.pageId, patch);
             if (!updated)
@@ -944,6 +1372,7 @@ export function createCmsHandlers(opts = {}) {
                     if (o[k] !== undefined && typeof o[k] !== "string")
                         throw new BadRequest(`${k} must be a string`);
                 }
+                versionInput(o);
                 return o;
             },
         }),
@@ -955,7 +1384,7 @@ export function createCmsHandlers(opts = {}) {
             if (!ct)
                 throw new BadRequest("unknown content type");
             validateFields(ct.fieldsSchema, input.fields ?? {}, "page.fields", { requireRequired: false });
-            const cleanPageFields = await sanitizeFields(ct.fieldsSchema, input.fields ?? {});
+            const cleanPageFields = normalizeFields(ct.fieldsSchema, input.fields ?? {}, rtSchema);
             const locale = input.locale ?? defaultLocale;
             await assertSlugFree(db, input.slug, locale);
             const page = await db.insert("cms_pages", {
@@ -978,7 +1407,7 @@ export function createCmsHandlers(opts = {}) {
                         throw new BadRequest(`unknown block type '${d.blockTypeSlug}'`);
                     await assertRegionAllows(db, page, d.region, d.blockTypeSlug);
                     validateFields(bts[0].fieldsSchema, d.fields ?? {}, "", { requireRequired: false });
-                    const cleanDefault = await sanitizeFields(bts[0].fieldsSchema, d.fields ?? {});
+                    const cleanDefault = normalizeFields(bts[0].fieldsSchema, d.fields ?? {}, rtSchema);
                     const block = await db.insert("cms_blocks", { typeId: bts[0].id, fields: cleanDefault });
                     const position = await nextPosition(db, String(page.id), d.region);
                     await db.insert("cms_page_blocks", { pageId: page.id, blockId: block.id, region: d.region, position });
@@ -1019,9 +1448,16 @@ export function createCmsHandlers(opts = {}) {
                 group = crypto.randomUUID();
                 await db.update("cms_pages", String(src.id), { translationGroupId: group });
             }
-            const existing = await db.find({ from: "cms_pages", where: { translationGroupId: group, locale: input.locale }, limit: 1 });
-            if (existing[0])
-                throw new BadRequest(`a '${input.locale}' translation already exists`);
+            // Raw exec, like assertSlugFree: a check-then-act uniqueness guard must see TRASHED
+            // rows too. Through ctx.db the read scope hides them, so trashing a `cs` translation
+            // let a second one be created, and restoring the first left two live `cs` pages in
+            // one group — two <link rel="alternate" hreflang="cs"> on every sibling.
+            const existing = await db.exec("SELECT id, deletedAt FROM cms_pages WHERE translationGroupId = ? AND locale = ? LIMIT 1", group, input.locale);
+            if (existing[0]) {
+                throw new BadRequest(existing[0].deletedAt != null
+                    ? `a '${input.locale}' translation exists in the trash — restore or purge it first`
+                    : `a '${input.locale}' translation already exists`);
+            }
             const slug = input.slug ?? String(src.slug);
             await assertSlugFree(db, slug, input.locale);
             return db.insert("cms_pages", {
@@ -1064,9 +1500,21 @@ export function createCmsHandlers(opts = {}) {
                 return o;
             },
         }),
-        /** Distinct locales present across all pages. */
+        /** What this deployment supports, for an editor to render against — the pages-side
+         * counterpart to `listCollections`' `supports: [...]`.
+         *
+         * The editor asks the SERVER what exists rather than being told by its own /config.js:
+         * a client flag can hide a control but cannot make the data right, and the two drift
+         * the moment someone adds a locale. `multilingual` is the derived answer to the only
+         * question the UI actually asks, so each surface doesn't re-derive it from the list. */
+        listCmsCapabilities: query(() => ({ locales, defaultLocale, multilingual: locales.length > 1 }), 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. */
         listLocales: query(async (ctx) => {
-            const rows = await cdb(ctx).exec("SELECT DISTINCT locale FROM cms_pages ORDER BY locale");
+            // Raw exec bypasses the ACL, so the trash filter has to be written out by hand —
+            // otherwise the editor's locale switcher offers a locale with zero live pages.
+            const rows = await cdb(ctx).exec("SELECT DISTINCT locale FROM cms_pages WHERE deletedAt IS NULL ORDER BY locale");
             return rows.map((r) => String(r.locale ?? "en"));
         }, viewer),
         // ---- blocks & placement ----
@@ -1082,7 +1530,7 @@ export function createCmsHandlers(opts = {}) {
             const bt = await loadBlockTypeBySlug(db, input.blockTypeSlug);
             await assertRegionAllows(db, page, input.region, input.blockTypeSlug);
             validateFields(bt.fieldsSchema, input.fields ?? {}, "", { requireRequired: false });
-            const cleanFields = await sanitizeFields(bt.fieldsSchema, input.fields ?? {});
+            const cleanFields = normalizeFields(bt.fieldsSchema, input.fields ?? {}, rtSchema);
             const block = await db.insert("cms_blocks", {
                 typeId: bt.id,
                 title: input.title ?? null,
@@ -1129,8 +1577,12 @@ export function createCmsHandlers(opts = {}) {
             await assertRegionAllows(db, page, input.region, slug);
             let cleanOverrides = input.overrides ?? null;
             if (input.overrides !== undefined) {
-                validateFields(bts[0]?.fieldsSchema, { ...asObj(block.fields), ...input.overrides }, "", { requireRequired: false });
-                cleanOverrides = await sanitizeFields(bts[0]?.fieldsSchema, input.overrides);
+                // The merged bag includes the block's OWN stored fields, which may predate Portable
+                // Text. Tolerate a legacy string there so an untouched legacy block can still be
+                // placed; the overrides themselves are new input and stay strict below.
+                validateFields(bts[0]?.fieldsSchema, { ...asObj(block.fields), ...input.overrides }, "", { requireRequired: false, legacyBaseline: asObj(block.fields) });
+                validateFields(bts[0]?.fieldsSchema, input.overrides, "", { requireRequired: false });
+                cleanOverrides = normalizeFields(bts[0]?.fieldsSchema, input.overrides, rtSchema);
             }
             const position = input.position ?? (await nextPosition(db, input.pageId, input.region));
             return db.insert("cms_page_blocks", {
@@ -1171,13 +1623,19 @@ export function createCmsHandlers(opts = {}) {
             const block = rows[0];
             if (!block)
                 throw notFound("block");
+            // Conflict first, like updatePage: a stale write carrying invalid fields should say
+            // "someone else changed this", not 400 on content the caller is about to discard.
+            const blockVersion = nextVersion(block, input.expectedVersion, "this block");
             let cleanFields = input.fields;
             if (input.fields !== undefined) {
                 const bt = await db.find({ from: "cms_block_types", where: { id: block.typeId }, limit: 1 });
-                validateFields(bt[0]?.fieldsSchema, input.fields, "", { requireRequired: false });
-                cleanFields = await sanitizeFields(bt[0]?.fieldsSchema, input.fields);
+                // The editor autosaves the WHOLE fields bag ~800ms after any edit, so a legacy
+                // richtext value the author never touched rides along with an unrelated change.
+                // Rejecting it would 400 on every keystroke and make the block unsaveable.
+                validateFields(bt[0]?.fieldsSchema, input.fields, "", { requireRequired: false, legacyBaseline: asObj(block.fields) });
+                cleanFields = normalizeFields(bt[0]?.fieldsSchema, input.fields, rtSchema);
             }
-            const patch = { updatedAt: nowStamp() };
+            const patch = { updatedAt: nowStamp(), version: blockVersion };
             if (cleanFields !== undefined)
                 patch.fields = cleanFields;
             if (input.title !== undefined)
@@ -1189,6 +1647,7 @@ export function createCmsHandlers(opts = {}) {
                 const o = asObj(raw);
                 if (typeof o.blockId !== "string")
                     throw new BadRequest("blockId is required");
+                versionInput(o);
                 return o;
             },
         }),
@@ -1414,10 +1873,168 @@ export function createCmsHandlers(opts = {}) {
             },
         }),
         // ---- public content API ----
+        /** Mint a signed, self-expiring preview link for one page. Editor-gated to MINT —
+         * anyone holding the resulting link can redeem it, which is the point. */
+        signPagePreview: query(async (ctx, input) => {
+            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.
+            if (ctx.store === "d1")
+                throw new PramenError("page preview is not available on the D1 store (redemption requires the Durable Object)", 503, "unavailable");
+            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.
+            const rows = await db.find({ from: "cms_pages", where: { id: input.pageId }, limit: 1 });
+            const page = rows[0];
+            if (!page)
+                throw notFound("page");
+            const ttl = Math.max(60, Math.min(input.expiresIn ?? previewTtl, 30 * 24 * 3600));
+            const exp = Math.floor(Date.now() / 1000) + ttl;
+            // Server-resolved, never caller-supplied — so the tenant inside the signature
+            // cannot be steered by whoever asks for the link.
+            const tenant = ctx.tenant;
+            const token = await signToken({ t: tenant, p: String(page.id), exp }, secret);
+            // RELATIVE, like signed file urls — the client resolves it against the CMS origin.
+            return { url: `${PREVIEW_PATH}?token=${encodeURIComponent(token)}`, token, expiresAt: exp * 1000 };
+        }, {
+            ...editor,
+            input: (raw) => {
+                const o = asObj(raw);
+                // Unvalidated, a non-string pageId reached the query compiler and surfaced as a
+                // 500, and a string expiresIn made exp NaN — minting a link that always 403s,
+                // with nothing anywhere to explain why.
+                if (typeof o.pageId !== "string" || o.pageId === "")
+                    throw new BadRequest("pageId is required");
+                if (o.expiresIn !== undefined && (typeof o.expiresIn !== "number" || !Number.isFinite(o.expiresIn))) {
+                    throw new BadRequest("expiresIn must be a number of seconds");
+                }
+                return o;
+            },
+        }),
+        /** Assemble a page's LIVE draft by id. Not the redemption endpoint — that is the public
+         * `GET /cms/preview` route, which verifies the token and then calls this privileged.
+         * Role-gated so it is not an anonymous back door on the /rpc surface. */
+        getPagePreview: query(async (ctx, input) => {
+            const db = cdb(ctx);
+            const rows = await db.find({ from: "cms_pages", where: { id: input.pageId }, limit: 1 });
+            const page = rows[0];
+            if (!page)
+                throw notFound("page");
+            const assembled = await assembleLive(db, page);
+            assembled.isPreview = true;
+            return assembled;
+        }, {
+            ...viewer,
+            input: (raw) => {
+                const o = asObj(raw);
+                if (typeof o.pageId !== "string" || o.pageId === "")
+                    throw new BadRequest("pageId is required");
+                return { pageId: o.pageId };
+            },
+        }),
         /** Fetch an assembled page by slug (+ locale). Anonymous callers get the published
          * snapshot (the ACL scopes `cms_pages` reads to `status = published`). Editors may pass
          * `preview: true` to assemble the current DRAFT live from the tables. `locale` defaults
          * to the configured default locale; a slug is unique per locale. */
+        // --- trash: soft delete, restore, purge ---------------------------------
+        //
+        // A page had NO delete handler at all before this: once created it could only be
+        // unpublished, never removed. Delete is therefore introduced already soft — the row
+        // stays, `deletedAt` is stamped, and the ACL's read scope hides it everywhere.
+        //
+        // A trashed page KEEPS ITS SLUG. `(slug, locale)` is a DB unique constraint, so the
+        // alternatives were mangling the stored slug on delete or dropping the constraint —
+        // both worse than telling the caller plainly that the slug is in the trash. Purging
+        // frees it.
+        deletePage: mutation(async (ctx, input) => {
+            const db = cdb(ctx);
+            const rows = await db.find({ from: "cms_pages", where: { id: input.pageId }, limit: 1 });
+            if (!rows[0])
+                throw notFound("page"); // already trashed reads as absent — the scope hides it
+            const now = new Date().toISOString();
+            // Clear the schedule. The publish/unpublish tasks run on the SYSTEM task context,
+            // where the ACL is bypassed entirely — so the `deletedAt IS NULL` read scope does
+            // NOT protect them, and a page trashed before its scheduled time was republished,
+            // publicly live, with a fresh revision and nobody pressing publish. Clearing the
+            // timestamps makes the tasks' existing intent-token check reject both for free.
+            await db.update("cms_pages", input.pageId, { deletedAt: now, updatedAt: now, scheduledAt: null, unpublishAt: null });
+            await writeAudit(db, { pageId: input.pageId, action: "delete", from: String(rows[0].status ?? ""), to: "trashed", actor: actorOf(ctx) });
+            return { ok: true, deletedAt: now };
+        }, { ...editor, ...pageIdInput }),
+        /** What is currently in the trash — pages AND media. Read with `ctx.db.exec` because
+         * the ACL read scope hides exactly these rows: that is the scope doing its job, not a
+         * hole to patch.
+         *
+         * Media has to be listed here or it becomes UNREACHABLE the moment it is trashed —
+         * `listMedia`/`getMedia` are ACL-scoped, so neither `restoreMedia` nor `purgeMedia`
+         * could ever be called with its id again, while `/media/<key>` kept serving the bytes
+         * (that route streams from R2 with no DB lookup at all). */
+        listTrash: query(async (ctx, input) => {
+            // Truncate like listMedia/listPageAudit — a fractional LIMIT reaches SQLite and 500s,
+            // and any client computing `total / pages` sends one.
+            const limit = Math.min(Math.max(Math.trunc(Number(input.limit)) || 50, 1), 200);
+            const db = cdb(ctx);
+            const pages = await db.exec("SELECT id, title, slug, locale, status, deletedAt FROM cms_pages WHERE deletedAt IS NOT NULL ORDER BY deletedAt DESC LIMIT ?", limit);
+            const rawMedia = await db.exec("SELECT id, alt, file, deletedAt FROM cms_media WHERE deletedAt IS NOT NULL ORDER BY deletedAt DESC LIMIT ?", limit);
+            // The fileRef object<->JSON codec sits on the ORM path, not raw exec — parse here or
+            // a trash UI reusing the media card renders `/media/undefined`.
+            const media = rawMedia.map((m) => ({ ...m, file: typeof m.file === "string" ? JSON.parse(m.file) : m.file }));
+            return { pages, media };
+        }, { ...viewer, input: (raw) => {
+                const o = asObj(raw);
+                if (o.limit !== undefined && typeof o.limit !== "number")
+                    throw new BadRequest("limit must be a number");
+                return o;
+            } }),
+        restorePage: mutation(async (ctx, input) => {
+            const db = cdb(ctx);
+            const rows = await db.exec("SELECT id, slug, locale, status, scheduledAt, unpublishAt FROM cms_pages WHERE id = ? AND deletedAt IS NOT NULL LIMIT 1", input.pageId);
+            const page = rows[0];
+            if (!page)
+                throw notFound("trashed page");
+            // Defensive: the trashed row still occupies the (slug, locale) unique index, so in
+            // practice nothing can have taken the slug. Kept so a future change that DOES free
+            // the slug on delete surfaces as a clean 400 rather than a constraint violation.
+            await assertSlugFree(db, String(page.slug), String(page.locale), String(page.id));
+            await db.exec("UPDATE cms_pages SET deletedAt = NULL, updatedAt = ? WHERE id = ?", new Date().toISOString(), input.pageId);
+            markChanged(db, "cms_pages");
+            await writeAudit(db, { pageId: input.pageId, action: "restore", from: "trashed", to: String(page.status ?? ""), actor: actorOf(ctx) });
+            // deletePage had to clear any schedule (the publish task runs SYSTEM-scoped, outside
+            // the read scope). Restore cannot know what it was, so SAY so — otherwise a promo
+            // page due to auto-unpublish comes back live forever with nothing in the audit trail.
+            return { ok: true, scheduleCleared: page.scheduledAt != null || page.unpublishAt != null };
+        }, { ...editor, ...pageIdInput }),
+        /** Permanently remove a trashed page and everything hanging off it. Reviewer-gated:
+         * this is the only irreversible operation in the CMS. */
+        purgePage: mutation(async (ctx, input) => {
+            const db = cdb(ctx);
+            const rows = await db.exec("SELECT id FROM cms_pages WHERE id = ? AND deletedAt IS NOT NULL LIMIT 1", input.pageId);
+            if (!rows[0])
+                throw notFound("trashed page"); // purging a LIVE page is refused — trash it first
+            // Placements, revisions and audit rows are logical relations (no FK cascade), so
+            // clear them explicitly or they outlive the page as orphans.
+            //
+            // The BLOCKS themselves need the same treatment, and it has to happen before the
+            // placements go: a non-reusable block used only by this page becomes unreachable
+            // once its last placement is deleted (there is no listBlocks, and removeBlock needs
+            // a pageBlockId that no longer exists). Mirrors removeBlock's own GC.
+            const doomed = await db.exec(`SELECT b.id AS id FROM cms_blocks b
+           JOIN cms_page_blocks pb ON pb.blockId = b.id
+          WHERE pb.pageId = ? AND b.isReusable = 0
+            AND NOT EXISTS (SELECT 1 FROM cms_page_blocks o WHERE o.blockId = b.id AND o.pageId <> ?)`, input.pageId, input.pageId);
+            await db.exec("DELETE FROM cms_page_blocks WHERE pageId = ?", input.pageId);
+            for (const row of doomed)
+                await db.exec("DELETE FROM cms_blocks WHERE id = ?", String(row.id));
+            await db.exec("DELETE FROM cms_page_revisions WHERE pageId = ?", input.pageId);
+            await db.exec("DELETE FROM cms_audit WHERE pageId = ?", input.pageId);
+            await db.exec("DELETE FROM cms_pages WHERE id = ?", input.pageId);
+            markChanged(db, "cms_pages", "cms_page_blocks", "cms_blocks", "cms_page_revisions", "cms_audit");
+            return { ok: true };
+        }, { ...reviewer, ...pageIdInput }),
         getPage: query(async (ctx, input) => {
             const db = cdb(ctx);
             // Preview is an editor capability — gate it before the lookup so a non-editor gets a
@@ -1429,8 +2046,11 @@ export function createCmsHandlers(opts = {}) {
             const page = rows[0];
             if (!page)
                 throw notFound("page"); // also the anonymous-vs-draft case: ACL yields no row
-            if (input.preview)
-                return assembleLive(db, page);
+            if (input.preview) {
+                const live = await assembleLive(db, page);
+                live.isPreview = true; // same flag the token route sets, so a banner works either way
+                return live;
+            }
             // Public path: serve the page's current published revision snapshot (selected by the
             // page's `currentRevisionId` pointer — deterministic, unlike ordering by a
             // second-precision timestamp). We do NOT assemble live here: anonymous has no read
@@ -1450,6 +2070,11 @@ export function createCmsHandlers(opts = {}) {
                     // page row so a frontend head template never hits `page.seo` === undefined.
                     if (!snap.page.seo)
                         snap.page.seo = pageMeta(page).seo;
+                    // `version` from the LIVE row, never the snapshot: a snapshot is baked at publish
+                    // time, so a client echoing it would 409 forever after the first draft edit — and
+                    // a pre-`version` snapshot has none at all, which (typed `number`) silently drops
+                    // out of the request body and reverts to the last-write-wins this feature removes.
+                    snap.page.version = typeof page.version === "number" ? page.version : 1;
                     if (snap.page.translationGroupId === undefined)
                         snap.page.translationGroupId = page.translationGroupId ?? null;
                     return snap;
@@ -1481,11 +2106,31 @@ export const cmsHandlers = createCmsHandlers();
  * `editor` grants full CRUD across every cms_ table. */
 export function cmsPolicies(opts = {}) {
     const p = opts.prefix ?? "cms";
+    // `cms_collection_revisions` is deliberately NOT here: it is append-only, and this loop
+    // grants update AND delete. Spreading both fragments (which every wiring in the README
+    // does) would otherwise hand every editor the ability to rewrite or purge history through
+    // 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"];
+    // 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
+    // `where` would have to be remembered at ~40 call sites and would be wrong the first
+    // time someone forgot. The trash itself is read with `ctx.db.exec` (below), which is the
+    // documented raw escape hatch and deliberately outside this scope.
+    const notTrashed = { where: { deletedAt: { isNull: true } } };
+    const softDeleted = { cms_pages: true, cms_media: true };
     const editorPolicies = [];
     for (const table of tables) {
         for (const action of ["read", "create", "update", "delete"]) {
-            editorPolicies.push(policy(`${p}:editor:${table}:${action}`, table, action, allow()));
+            // UPDATE is scoped as well as READ. Handlers that read the row first already 404 on
+            // a trashed page, but `updatePageSeo`/`updateMedia` patched blind — so an editor with
+            // a stale tab could mutate a page a colleague had just trashed, and the write echo
+            // handed back the whole hidden row. Scoping the grant covers every future write
+            // handler too, rather than relying on each one remembering to read first.
+            const scoped = (action === "read" || action === "update") && softDeleted[table];
+            editorPolicies.push(policy(`${p}:editor:${table}:${action}`, table, action, scoped ? notTrashed : allow()));
         }
     }
     return {
@@ -1495,14 +2140,18 @@ export function cmsPolicies(opts = {}) {
             // can route/render by type. Slugs/names are structural, not sensitive.
             policy(`${p}:public:content-types:read`, "cms_content_types", "read", allow()),
             // Only published pages are readable; the snapshot carries the content.
-            policy(`${p}:public:pages:read`, "cms_pages", "read", { where: { status: "published" } }),
+            policy(`${p}:public:pages:read`, "cms_pages", "read", { where: { status: "published", deletedAt: { isNull: true } } }),
             // getPage reads the latest revision snapshot. Scope the grant by the revision's
             // PAGE being currently published (a relation-traversal where, compiled to a
             // subquery), so a revision of a later-unpublished/archived page is never publicly
             // readable — least-privilege even for a future revision-listing handler.
-            policy(`${p}:public:revisions:read`, "cms_page_revisions", "read", { where: { page: { status: "published" } } }),
+            // `deletedAt` as well as `status`: getPage 404s on the page lookup first today, so
+            // this is defense in depth — but a revision snapshot is a BAKED copy of the page's
+            // content, and a future revision-listing handler reading it directly would otherwise
+            // serve a trashed page's body.
+            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", allow()),
+            policy(`${p}:public:media:read`, "cms_media", "read", { where: { deletedAt: { isNull: true } } }),
         ],
         editor: editorPolicies,
     };
@@ -1535,12 +2184,238 @@ function collectionMeta(c) {
         titleField,
         idField: c.idField ?? "id",
         orderBy: c.orderBy,
+        supports: c.supports ?? [],
     };
 }
+export const COLLECTION_FEATURES = ["drafts", "scheduling", "revisions", "preview"];
+/** The columns each feature needs on the collection's entity. The app declares them (they
+ * are its own entity); the CMS writes them and `fields` may not. */
+export const COLLECTION_FEATURE_COLUMNS = {
+    drafts: ["status"],
+    scheduling: ["publishedAt", "scheduledAt", "unpublishAt"],
+    revisions: [],
+    preview: [],
+};
+/** Features that mean nothing on their own. Scheduling moves a row between draft and
+ * published; preview shows the unpublished version — both presuppose `drafts`. */
+const COLLECTION_FEATURE_REQUIRES = {
+    scheduling: "drafts",
+    preview: "drafts",
+};
+/** The shared revision table for collections (see `cmsSchema`). */
+export const COLLECTION_REVISIONS_TABLE = "cms_collection_revisions";
+/** The two `status` values a `drafts` collection uses. */
+export const COLLECTION_DRAFT = "draft";
+export const COLLECTION_PUBLISHED = "published";
+/** `collectionList` page size when the caller names none, and the ceiling it is clamped to.
+ * The cap is the point: an unbounded list of a wide entity is the D1-over-RPC failure mode
+ * (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
+ * `Date`) `toISOString()` throws a `RangeError` INSIDE the mutation — an opaque 500 for the
+ * common client slip of sending epoch microseconds. And from year 10000 up, `toISOString()`
+ * mints an EXPANDED-year string (`"+010000-01-01T00:00:00.000Z"`) whose leading `+` sorts
+ * BEFORE every ordinary timestamp — inverting every lexicographic comparison this feature
+ * rests on, so a takedown 8000 years out reads as already passed and a publish instant in
+ * the far future reads as due. One range check closes both. */
+const MIN_SCHEDULE_MS = 0;
+const MAX_SCHEDULE_MS = 253402300799999; // 9999-12-31T23:59:59.999Z
+const epochInput = (name, v) => {
+    if (typeof v !== "number" || !Number.isFinite(v))
+        throw new BadRequest(`${name} must be a finite epoch ms`);
+    if (!Number.isInteger(v))
+        throw new BadRequest(`${name} must be a whole number of epoch ms`);
+    if (v < MIN_SCHEDULE_MS || v > MAX_SCHEDULE_MS) {
+        throw new BadRequest(`${name} must be an epoch ms between ${MIN_SCHEDULE_MS} and ${MAX_SCHEDULE_MS} (1970 … 9999) — got ${v}`);
+    }
+    return v;
+};
+/** The column types a declared field can be stored in. A collection field is COLUMN-MAPPED,
+ * so the entity's column type has to match what the field writes: a `richtext`/`group`/
+ * `repeater` value is a document (`t.json()`), the rest are scalars. Getting this wrong is
+ * not a type error anywhere — it surfaces as a raw driver message on the first write
+ * ("Binding expected string, TypedArray, …"), which is why it is checked at boot. */
+const COLLECTION_FIELD_COLUMN_TYPES = {
+    text: ["text", "uuid"],
+    textarea: ["text"],
+    richtext: ["json"],
+    url: ["text"],
+    number: ["integer", "real"],
+    boolean: ["boolean", "integer"],
+    date: ["text"],
+    datetime: ["text"],
+    publish: ["text"],
+    slug: ["text"],
+    media: ["text", "uuid"],
+    select: ["text"],
+    repeater: ["json"],
+    group: ["json"],
+};
+/** 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
+ * field.
+ *
+ * Called by `createCollectionHandlers`. The point is that a misconfiguration surfaces when
+ * the Worker starts, naming the collection and the column — not as a 500 the first time an
+ * editor presses Publish, months later, on the one collection nobody exercised.
+ *
+ * `schema` is REQUIRED. Every check here reads the target entity, so a registry validated
+ * without one is not validated at all — and the failures it catches (a field name typo, a
+ * richtext field over a TEXT column, a non-PK idField) are exactly as fatal on a collection
+ * that declares no `supports` as on one that declares all four. */
+export function validateCollections(collections, schema) {
+    const seen = new Set();
+    const byEntity = new Map();
+    for (const c of collections) {
+        if (seen.has(c.slug))
+            throw new Error(`pramen/cms: duplicate collection slug '${c.slug}' — slugs are the handler registry's key`);
+        seen.add(c.slug);
+        // ONE collection per entity. The ACL keys policies by (role, entity, action) and
+        // OR-merges the matches — the policy NAME is not part of the key — so a second
+        // collection over the same entity does not add a second, separate view: it WIDENS the
+        // first one's read scope. Two `collectionPublicPolicies` grants over one entity collapse
+        // to the loosest of the two, which is how a `drafts`-only collection silently removes
+        // the `publishedAt <= $now()` and `unpublishAt > $now()` clauses from a `scheduling`
+        // sibling — publishing a row a year early and defeating its scheduled takedown.
+        const first = byEntity.get(c.entity);
+        if (first) {
+            throw new Error(`pramen/cms: collections '${first}' and '${c.slug}' both target entity '${c.entity}' — the ACL OR-merges policies on the same (role, entity, action), so a second collection widens the first one's read scope instead of adding a separate view. Register one collection per entity.`);
+        }
+        byEntity.set(c.entity, c.slug);
+    }
+    if (collections.length === 0)
+        return;
+    if (!schema) {
+        throw new Error(`pramen/cms: createCollectionHandlers needs your schema to check the registry against your entities: createCollectionHandlers(collections, { schema })`);
+    }
+    for (const c of collections) {
+        const features = c.supports ?? [];
+        const set = new Set(features);
+        for (const f of features) {
+            if (!COLLECTION_FEATURES.includes(f)) {
+                throw new Error(`pramen/cms: collection '${c.slug}' declares unknown feature '${String(f)}' (known: ${COLLECTION_FEATURES.join(", ")})`);
+            }
+            const needs = COLLECTION_FEATURE_REQUIRES[f];
+            if (needs && !set.has(needs)) {
+                throw new Error(`pramen/cms: collection '${c.slug}' declares '${f}', which needs '${needs}' — add it to \`supports\``);
+            }
+        }
+        const entity = schema[c.entity];
+        if (!entity)
+            throw new Error(`pramen/cms: collection '${c.slug}' targets entity '${c.entity}', which is not in the schema`);
+        const columns = entity.fields;
+        // EVERY collection handler dispatches to the default partition's DO: none of them
+        // declares a `partition`, and `/rpc` routes by the handler's. An entity parked in
+        // another partition therefore boots clean and then 400s on every single call
+        // (`assertInPartition`), and a preview link 404s forever — `callPrivileged` has no
+        // partition to pass either. Name it here instead.
+        const entityPartition = partitionOf(schema, c.entity);
+        if (entityPartition !== DEFAULT_PARTITION) {
+            throw new Error(`pramen/cms: collection '${c.slug}' targets entity '${c.entity}' in partition '${entityPartition}', but the collection handlers are dispatched to the '${DEFAULT_PARTITION}' partition — every call would fail. Keep a collection's entity in the default partition.`);
+        }
+        const idField = c.idField ?? "id";
+        if (!(idField in columns)) {
+            throw new Error(`pramen/cms: collection '${c.slug}' has idField '${idField}', which is not a column on '${c.entity}'`);
+        }
+        // …and it must be the PRIMARY KEY, not merely a column. Reads key on `idField`, but
+        // `db.update`/`db.delete` key on the entity's actual PK — so a non-PK idField loads a
+        // row fine and then writes nothing, surfacing as a 404 on a row the same handler just
+        // read. Exactly the misconfiguration this validator exists to name.
+        const pk = Object.entries(columns).find(([, f]) => f.primaryKey)?.[0] ?? "id";
+        if (idField !== pk) {
+            throw new Error(`pramen/cms: collection '${c.slug}' has idField '${idField}', but '${c.entity}' has primary key '${pk}' — writes key on the PK, so they would silently match no row`);
+        }
+        // Declared fields ARE columns on the entity (that is what "column-mapped" means), so a
+        // typo is a write that fails with the driver's own message and no HTTP status, and a
+        // document field over a TEXT column is the trap example/app.ts documents in a comment.
+        // Both are visible right here, with `columns` in hand.
+        for (const f of c.fields) {
+            const col = columns[f.name];
+            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];
+            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}`);
+            }
+            if (col.hidden) {
+                throw new Error(`pramen/cms: collection '${c.slug}' declares '${f.name}' as an editable field, but '${c.entity}.${f.name}' is hidden() — a hidden column is stripped from every read, so the editor would show it empty and overwrite it on every save`);
+            }
+        }
+        // A declared `orderBy` fails SILENTLY when the column does not exist: the dialect
+        // double-quotes the name and SQLite resolves an unknown quoted identifier to a string
+        // CONSTANT, so every row sorts equal and the list comes back in arbitrary storage order
+        // with no error anywhere.
+        if (c.orderBy && !(c.orderBy.column in columns)) {
+            throw new Error(`pramen/cms: collection '${c.slug}' orders by '${c.orderBy.column}', which is not a column on '${c.entity}' — SQLite would resolve the quoted name to a constant and sort every row equal`);
+        }
+        const declared = new Set(c.fields.map((f) => f.name));
+        for (const f of features) {
+            for (const col of COLLECTION_FEATURE_COLUMNS[f]) {
+                const column = columns[col];
+                if (!column) {
+                    throw new Error(`pramen/cms: collection '${c.slug}' declares '${f}', which manages a \`${col}\` column on '${c.entity}' — add \`${col}: t.text()\` to the entity`);
+                }
+                // NAME alone is not enough. The CMS writes these columns as TEXT (an ISO-8601
+                // instant or a status word) and compares them lexicographically in the public read
+                // scope, and every wrong declaration fails SILENTLY rather than loudly:
+                //   - `t.json()` stores `"\"published\""` (the Db chokepoint stringifies), so the
+                //     policy's `status = 'published'` never matches and the row is invisible
+                //     forever while `collectionPublish` echoes success;
+                //   - `notNull()` 500s on every create (the managed columns are seeded as NULL);
+                //   - `hidden()` strips the column from every read, disabling the spent-takedown
+                //     repair and hiding the state from the editor.
+                if (column.type !== "text") {
+                    throw new Error(`pramen/cms: collection '${c.slug}' declares '${f}', which manages \`${c.entity}.${col}\` as TEXT, but it is ${column.type} — declare it as \`${col}: t.text()\` (a non-TEXT column compares wrong against $now() and would never match the published scope)`);
+                }
+                if (column.notNull) {
+                    throw new Error(`pramen/cms: collection '${c.slug}' declares '${f}', which manages \`${c.entity}.${col}\`, but the column is notNull() — the CMS seeds and clears it with NULL, so every write would fail. Drop notNull() (a defaultTo() is fine).`);
+                }
+                if (column.hidden) {
+                    throw new Error(`pramen/cms: collection '${c.slug}' declares '${f}', which manages \`${c.entity}.${col}\`, but the column is hidden() — the CMS reads it back to decide the row's state, so it must be projectable`);
+                }
+                // `fields` IS the write whitelist. A `status` entry there would let any editor send
+                // `values: { status: "published" }` through collectionUpdate and bypass the publish
+                // handler entirely, leaving the gate as decoration over a client-set column.
+                if (declared.has(col)) {
+                    throw new Error(`pramen/cms: collection '${c.slug}' declares \`${col}\` as an editable field, but '${f}' manages that column — remove it from \`fields\` (it would be a client-writable publish gate)`);
+                }
+            }
+        }
+        if (set.has("revisions")) {
+            if (!schema[COLLECTION_REVISIONS_TABLE]) {
+                throw new Error(`pramen/cms: collection '${c.slug}' declares 'revisions', which needs the \`${COLLECTION_REVISIONS_TABLE}\` table — spread \`cmsSchema\` into defineSchema`);
+            }
+            // A DO cannot write across a partition boundary, so a collection entity parked in its
+            // own partition would 500 on the first snapshot insert (assertInPartition). The
+            // default-partition check above already covers this; keep the specific message for
+            // the case where `cms_collection_revisions` itself was moved.
+            const revPartition = partitionOf(schema, COLLECTION_REVISIONS_TABLE);
+            if (entityPartition !== revPartition) {
+                throw new Error(`pramen/cms: collection '${c.slug}' declares 'revisions', but '${c.entity}' is in partition '${entityPartition}' while \`${COLLECTION_REVISIONS_TABLE}\` is in '${revPartition}' — a write cannot cross partitions, so keep the entity in '${revPartition}'`);
+            }
+        }
+    }
+}
+/** Where a collection preview link is redeemed. Served by `cmsRoutes()`. */
+export const COLLECTION_PREVIEW_PATH = "/cms/preview/collection";
+/** Outbox task kinds behind `collectionSchedule`. Register the handlers with
+ * `app.tasks = { ...cmsTasks, ...createCollectionTasks(collections) }`. */
+export const TASK_COLLECTION_PUBLISH = "cms:collection:publish";
+export const TASK_COLLECTION_UNPUBLISH = "cms:collection:unpublish";
 /** Build generic CRUD handlers over the registered collections. Spread into your app's
  * handlers alongside `cmsHandlers`:
  *
- *   const handlers = { ...cmsHandlers, ...createCollectionHandlers([lectures]) };
+ *   const handlers = { ...cmsHandlers, ...createCollectionHandlers([lectures], { schema }) };
  *
  * Exposes `listCollections` (editor discovery) + `collectionList` / `collectionGet` /
  * `collectionCreate` / `collectionUpdate` / `collectionDelete`, all gated by `editorRoles`
@@ -1548,7 +2423,16 @@ function collectionMeta(c) {
  * `collectionPolicies` scopes them too). The `collection` param is resolved through the
  * registry — an unknown slug is a 400, never a raw table reference. */
 export function createCollectionHandlers(collections, opts = {}) {
+    // Boot check, before a single handler is built: unknown/incoherent features and missing
+    // managed columns throw here rather than 500ing on the first publish.
+    validateCollections(collections, opts.schema);
+    const collectionRtSchema = opts.richTextSchema ?? DEFAULT_RICH_TEXT_SCHEMA;
     const editor = { auth: opts.editorRoles ?? ["editor", "admin"] };
+    // Preview redemption presents editorRoles ∪ reviewerRoles (see `viewerRolesOf`), so the
+    // handler the route calls has to accept that set — gating it to `editor` alone would 403
+    // every preview link for a reviewer-only identity. Same wiring as `getPagePreview`.
+    const viewer = { auth: viewerRolesOf(opts) };
+    const previewTtl = opts.previewTtlSeconds ?? DEFAULT_PREVIEW_TTL_SECONDS;
     const bySlug = new Map(collections.map((c) => [c.slug, c]));
     const metas = collections.map(collectionMeta);
     const def = (slug) => {
@@ -1557,18 +2441,183 @@ export function createCollectionHandlers(collections, opts = {}) {
             throw new BadRequest(`unknown collection: ${String(slug)}`);
         return c;
     };
+    /** Narrow a stored snapshot to the columns a caller may read on the collection's entity.
+     * Used by both the history read and the restore write, so "what you can see" and "what you
+     * can put back" are the same set. */
+    const projectSnapshot = (snapshot, readable) => {
+        const obj = snapshot && typeof snapshot === "object" && !Array.isArray(snapshot) ? snapshot : {};
+        const out = {};
+        for (const [k, v] of Object.entries(obj))
+            if (readable.has(k))
+                out[k] = v;
+        return out;
+    };
     const idOf = (c) => c.idField ?? "id";
+    const has = (c, f) => (c.supports ?? []).includes(f);
+    const columnsOf = (c) => (opts.schema?.[c.entity]?.fields ?? {});
+    /** The list ordering, resolved ONCE against the entity. The documented default is
+     * `createdAt desc`, but that column is not guaranteed to exist — and an ORDER BY over a
+     * missing column does not fail: the dialect quotes the name, SQLite resolves the unknown
+     * quoted identifier to a string CONSTANT, every row sorts equal, and the list comes back
+     * in arbitrary storage order. Fall back to the PK, which always exists, so the order is at
+     * least stable and paging is coherent. (A DECLARED `orderBy` over a missing column is a
+     * boot error — see `validateCollections`.) */
+    const orderByOf = (c) => {
+        if (c.orderBy)
+            return { column: c.orderBy.column, dir: c.orderBy.dir ?? "desc" };
+        return { column: "createdAt" in columnsOf(c) ? "createdAt" : idOf(c), dir: "desc" };
+    };
+    const orderBys = new Map(collections.map((c) => [c.slug, orderByOf(c)]));
+    /** 400 (not 500) when a caller invokes a workflow handler on a collection that never
+     * opted into it — the handlers exist for every collection, the features do not. */
+    const needs = (c, f) => {
+        if (!has(c, f))
+            throw new BadRequest(`collection '${c.slug}' does not support '${f}' (add it to \`supports\`)`);
+    };
+    const loadRow = async (db, c, id) => {
+        const rows = await db.find({ from: c.entity, where: { [idOf(c)]: id }, limit: 1 });
+        const row = rows[0];
+        if (!row)
+            throw notFound(c.label);
+        return row;
+    };
+    /** Read a row's DECLARED FIELD columns unprojected, for the revision snapshot.
+     *
+     * `ctx.db.exec` is the documented raw escape hatch: it bypasses the row/field ACL, and it
+     * also bypasses the `Db` chokepoint's cell codec — so a json-backed column comes back as
+     * the stored TEXT and a boolean as 0/1. Both are decoded here from the entity's own column
+     * types (checked against the field types at boot), so a snapshot holds exactly what
+     * `db.find` would have returned for an unrestricted caller.
+     *
+     * Falls back to the ACL-projected row if the raw read comes back empty (a substrate quirk
+     * or a row deleted concurrently) — a partial snapshot beats no snapshot. */
+    const rawFieldValues = async (db, c, rowId, projected) => {
+        const columns = columnsOf(c);
+        const names = c.fields.map((f) => f.name).filter((n) => n in columns);
+        if (names.length === 0)
+            return {};
+        const cols = names.map((n) => `"${n}"`).join(", ");
+        // Identifiers, not values: `entity`, `idField` and every field name were checked against
+        // the schema at boot, so nothing caller-supplied is interpolated here. The id IS bound.
+        const rows = (await db.exec(`SELECT ${cols} FROM "${c.entity}" WHERE "${idOf(c)}" = ?`, rowId));
+        const raw = rows[0];
+        if (!raw) {
+            const fallback = {};
+            for (const f of c.fields)
+                if (f.name in projected)
+                    fallback[f.name] = projected[f.name];
+            return fallback;
+        }
+        const values = {};
+        for (const name of names) {
+            const v = raw[name];
+            const type = columns[name]?.type;
+            if (v == null)
+                values[name] = null;
+            else if ((type === "json" || type === "fileRef") && typeof v === "string") {
+                try {
+                    values[name] = JSON.parse(v);
+                }
+                catch {
+                    values[name] = v; // not JSON after all — keep the literal rather than losing it
+                }
+            }
+            else if (type === "boolean")
+                values[name] = typeof v === "boolean" ? v : v !== 0 && v !== 0n;
+            else
+                values[name] = v;
+        }
+        return values;
+    };
+    /** Snapshot a row's CURRENT (pre-write) state into `cms_collection_revisions`, so a
+     * revision always reads as "what it was before this edit" and restoring one is a plain
+     * reversal. Declared fields only — the snapshot is replayed through the same write
+     * whitelist on restore, so it can never carry a column the collection doesn't own.
+     * No-op unless the collection supports `revisions`. */
+    const snapshotRow = async (db, c, row, ctx, note) => {
+        if (!has(c, "revisions"))
+            return;
+        const rowId = String(row[idOf(c)]);
+        // The row handed in came through the ACL, so it is projected to what THIS caller may
+        // read — which would make history a function of who happened to make the edit: an
+        // editor whose read scope excludes `salary` would silently drop it from the snapshot,
+        // and every later "restore to before that edit" would restore an incomplete row.
+        // History is an audit record, not a view, so capture the row's REAL pre-state through
+        // the raw escape hatch and let the READ path decide who may see which of its fields
+        // (`collectionListRevisions` projects it back down).
+        const values = await rawFieldValues(db, c, rowId, row);
+        // Next in this row's sequence. Serialized by the DO's single writer; on D1 the composite
+        // unique on (collection, rowId, revision) is the backstop — see the schema note.
+        const [{ next = 1 } = {}] = (await db.exec(`SELECT COALESCE(MAX(revision), 0) + 1 AS next FROM ${COLLECTION_REVISIONS_TABLE} WHERE collection = ? AND rowId = ?`, c.slug, rowId));
+        await db.insert(COLLECTION_REVISIONS_TABLE, {
+            collection: c.slug,
+            rowId,
+            revision: next,
+            snapshot: values,
+            note,
+            actor: typeof ctx.identity?.userId === "string" ? ctx.identity.userId : null,
+            // Explicit, ms-precision, and the only writer of this column — see the schema note.
+            createdAt: isoStamp(),
+        });
+    };
+    /** Shared input validator for the `{ collection, id }` handlers. */
+    const rowInput = (raw) => {
+        const o = asObj(raw);
+        if (typeof o.collection !== "string" || o.collection === "")
+            throw new BadRequest("collection is required");
+        return { collection: o.collection, id: idInput(raw) };
+    };
+    const collectionInput = (raw) => {
+        const o = asObj(raw);
+        if (typeof o.collection !== "string" || o.collection === "")
+            throw new BadRequest("collection is required");
+        return o.collection;
+    };
+    /** `{ collection, values }` — the write handlers. `values` is validated against the field
+     * schema downstream (`toColumns`); this only rejects a non-object, so a string or an array
+     * cannot reach the field validator as a bag of index keys. */
+    const valuesInput = (raw) => {
+        const o = asObj(raw);
+        const values = o.values;
+        if (values === null || typeof values !== "object" || Array.isArray(values))
+            throw new BadRequest("values must be an object");
+        return { collection: collectionInput(raw), values: values };
+    };
+    const rowValuesInput = (raw) => ({
+        ...rowInput(raw),
+        values: valuesInput(raw).values,
+    });
+    /** `{ collection, limit?, offset? }`, both CLAMPED. `find` binds `limit` straight into
+     * `LIMIT ?`, and SQLite reads a negative limit as UNBOUNDED — so `limit: -1` dumps the
+     * whole table over RPC — while a fractional value reaches the driver as-is and 500s. */
+    const listInput = (raw) => {
+        const o = asObj(raw);
+        const num = (name, v) => {
+            if (v === undefined || v === null)
+                return undefined;
+            if (typeof v !== "number" || !Number.isFinite(v))
+                throw new BadRequest(`${name} must be a number`);
+            return Math.floor(v);
+        };
+        const limit = num("limit", o.limit);
+        const offset = num("offset", o.offset);
+        return {
+            collection: collectionInput(raw),
+            limit: limit === undefined ? undefined : Math.max(1, Math.min(limit, MAX_COLLECTION_LIST_LIMIT)),
+            offset: offset === undefined ? undefined : Math.max(0, offset),
+        };
+    };
     // Validate against the field schema, sanitize richtext, then PROJECT to declared field
     // names only — the write whitelist. `requireRequired` is off for updates (partial patch);
     // on for create. Nothing outside `c.fields` can reach the entity.
-    const toColumns = (c, values, requireRequired) => {
+    const toColumns = (c, values, requireRequired, legacyBaseline) => {
         const obj = asObj(values);
-        validateFields([...c.fields], obj, "", { requireRequired });
-        const sanitized = sanitizeFields([...c.fields], obj);
+        validateFields([...c.fields], obj, "", { requireRequired, legacyBaseline });
+        const normalized = normalizeFields([...c.fields], obj, collectionRtSchema);
         const out = {};
         for (const f of c.fields)
-            if (f.name in sanitized)
-                out[f.name] = sanitized[f.name];
+            if (f.name in normalized)
+                out[f.name] = normalized[f.name];
         return out;
     };
     const idInput = (raw) => {
@@ -1583,33 +2632,372 @@ export function createCollectionHandlers(collections, opts = {}) {
         listCollections: query(() => metas, editor),
         collectionList: query((ctx, input) => {
             const c = def(input.collection);
-            const limit = typeof input.limit === "number" ? input.limit : 100;
-            const offset = typeof input.offset === "number" ? input.offset : undefined;
-            return cdb(ctx).find({ from: c.entity, orderBy: c.orderBy ?? { column: "createdAt", dir: "desc" }, limit, offset });
-        }, editor),
+            return cdb(ctx).find({
+                from: c.entity,
+                orderBy: orderBys.get(c.slug) ?? orderByOf(c),
+                limit: input.limit ?? DEFAULT_COLLECTION_LIST_LIMIT,
+                offset: input.offset,
+            });
+        }, { ...editor, input: listInput }),
         collectionGet: query(async (ctx, input) => {
             const c = def(input.collection);
             const rows = await cdb(ctx).find({ from: c.entity, where: { [idOf(c)]: input.id }, limit: 1 });
             return rows[0] ?? null;
-        }, editor),
+        }, { ...editor, input: rowInput }),
         collectionCreate: mutation((ctx, input) => {
             const c = def(input.collection);
-            return cdb(ctx).insert(c.entity, toColumns(c, input.values, true));
-        }, editor),
+            const values = toColumns(c, input.values, true);
+            // Seed the managed columns explicitly rather than leaning on a column default: the
+            // entity belongs to the app, which may have declared `status` with no default (or a
+            // NOT NULL one). A new row always starts as a draft — publishing is a separate,
+            // separately-gated act.
+            if (has(c, "drafts"))
+                values.status = COLLECTION_DRAFT;
+            if (has(c, "scheduling")) {
+                values.publishedAt = null;
+                values.scheduledAt = null;
+                values.unpublishAt = null;
+            }
+            return cdb(ctx).insert(c.entity, values);
+        }, { ...editor, input: valuesInput }),
         collectionUpdate: mutation(async (ctx, input) => {
             const c = def(input.collection);
-            const updated = await cdb(ctx).update(c.entity, input.id, toColumns(c, input.values, false));
+            const db = cdb(ctx);
+            // Read the current row first: the editor autosaves the WHOLE values bag, so a
+            // pre-Portable-Text richtext value rides along with an unrelated edit. It is
+            // tolerated only when byte-identical to what is stored (see `legacyBaseline`).
+            // A policy may grant `update` without `read` on the entity — that worked before this
+            // pre-read existed, so it must not start 403ing. No baseline simply means a legacy
+            // string is rejected, which is the strict default.
+            let current;
+            try {
+                current = (await db.find({ from: c.entity, where: { [idOf(c)]: input.id }, limit: 1 }))[0];
+            }
+            catch {
+                current = undefined;
+            }
+            // Validate + whitelist the patch BEFORE snapshotting. `toColumns` throws on an invalid
+            // patch, and on the DO that rollback is free (the mutation is one transaction) — but
+            // `D1Driver.transaction` is a no-op, so snapshotting first meant a REJECTED edit still
+            // committed a revision on D1: a phantom entry recording no change, and a burnt value
+            // in the per-row `revision` counter.
+            const patch = toColumns(c, input.values, false, current);
+            // `current` is undefined only when the pre-read above was denied (an
+            // update-without-read grant), in which case there is nothing to snapshot — the
+            // revision is skipped rather than written empty.
+            if (current)
+                await snapshotRow(db, c, current, ctx, "edit");
+            const updated = await db.update(c.entity, input.id, patch);
             if (updated === undefined)
                 throw notFound(c.label);
             return updated;
-        }, editor),
+        }, { ...editor, input: rowValuesInput }),
         collectionDelete: mutation(async (ctx, input) => {
             const c = def(input.collection);
-            const ok = await cdb(ctx).delete(c.entity, input.id);
+            const db = cdb(ctx);
+            const ok = await db.delete(c.entity, input.id);
             if (!ok)
                 throw notFound(c.label);
+            // PURGE the row's revisions. Keeping them looks like free history, but a collection PK
+            // can be a caller-chosen textId — recreating a row with the same id would inherit the
+            // dead row's history, and `collectionRestoreRevision`'s scope check (collection +
+            // rowId) would happily write the deleted row's content over the new one. It also
+            // bounds the table: a collection has no trash, so nothing else ever collects these.
+            //
+            // Atomic with the delete on the DO (the mutation runs in storage.transaction). NOT on
+            // the D1 store, where `transaction` is a no-op — a failure in between leaves orphan
+            // revisions, which is exactly the inheritance above. Rare, and recoverable by
+            // deleting the recreated row, but it is not a guarantee on that substrate.
+            if (has(c, "revisions")) {
+                await db.exec(`DELETE FROM ${COLLECTION_REVISIONS_TABLE} WHERE collection = ? AND rowId = ?`, c.slug, input.id);
+            }
             return { ok: true };
-        }, { ...editor, input: (raw) => ({ collection: asObj(raw).collection, id: idInput(raw) }) }),
+        }, { ...editor, input: rowInput }),
+        // ---- drafts -------------------------------------------------------------
+        /** Move a row live. With `scheduling` this also stamps `publishedAt` (the column the
+         * public read scope compares against `$now()`) and clears `scheduledAt` — which makes
+         * any pending scheduled-publish task a no-op, since its intent token no longer matches.
+         * A pending scheduled UNPUBLISH is deliberately left standing: publishing early does not
+         * cancel a planned takedown. */
+        collectionPublish: mutation(async (ctx, input) => {
+            const c = def(input.collection);
+            needs(c, "drafts");
+            const db = cdb(ctx);
+            const row = await loadRow(db, c, input.id);
+            // Deliberately NOT snapshotted. A revision records CONTENT, and publishing changes
+            // none — the managed columns are excluded from `fields` by design, so a "publish"
+            // revision was byte-identical to the edit before it, and restoring it wrote only the
+            // declared fields and left the row live. That reads as a broken button; an entry that
+            // cannot be restored is worse than no entry.
+            const patch = { status: COLLECTION_PUBLISHED };
+            if (has(c, "scheduling")) {
+                const now = isoStamp();
+                patch.publishedAt = now;
+                patch.scheduledAt = null;
+                // Clear a takedown instant that has already PASSED. This is an EXPLICIT act by a
+                // human holding publish rights, which is why it resolves differently from the
+                // scheduled-publish task: that one converges to the state the schedule implies (a
+                // passed takedown wins, and the row lands down), while here the editor is saying
+                // "live, now" about a takedown that has already been served. A future one stands —
+                // publishing early does not cancel a planned removal — but a spent one is not
+                // "pending" at all, and since the public scope now enforces
+                // `unpublishAt IS NULL OR unpublishAt > $now()`, leaving it would make this very
+                // publish a no-op: the editor gets back `status: "published"` and the row stays
+                // invisible, with no error to explain it. That state is reachable whenever the
+                // unpublish task never ran (tasks unwired, outbox dead-lettered, no D1 cron).
+                if (typeof row.unpublishAt === "string" && row.unpublishAt <= now)
+                    patch.unpublishAt = null;
+            }
+            const updated = await db.update(c.entity, input.id, patch);
+            if (updated === undefined)
+                throw notFound(c.label);
+            return updated;
+        }, { ...editor, input: rowInput }),
+        /** Take a row back to draft, clearing every schedule. Both tokens are cleared, so a
+         * pending publish AND a pending unpublish both become no-ops — unpublishing is an
+         * explicit "this is not live and nothing is queued to change that". */
+        collectionUnpublish: mutation(async (ctx, input) => {
+            const c = def(input.collection);
+            needs(c, "drafts");
+            const db = cdb(ctx);
+            await loadRow(db, c, input.id);
+            const patch = { status: COLLECTION_DRAFT }; // not snapshotted — see collectionPublish
+            if (has(c, "scheduling")) {
+                patch.publishedAt = null;
+                patch.scheduledAt = null;
+                patch.unpublishAt = null;
+            }
+            const updated = await db.update(c.entity, input.id, patch);
+            if (updated === undefined)
+                throw notFound(c.label);
+            return updated;
+        }, { ...editor, input: rowInput }),
+        // ---- scheduling ---------------------------------------------------------
+        /** Schedule a future publish, and optionally a later unpublish. Mirrors `schedulePage`,
+         * including the INTENT TOKEN: the row stores the scheduled instants
+         * (`scheduledAt`/`unpublishAt`, ISO), the enqueued task carries a copy, and the task
+         * runs only if the two still match. A reschedule overwrites the token, a manual
+         * publish/unpublish clears it, and a duplicate delivery finds it already cleared — so a
+         * superseded or cancelled schedule is a silent no-op rather than a surprise publish.
+         *
+         * The tasks are enqueued in THIS mutation's transaction (the outbox is transactional),
+         * so a rolled-back schedule never leaves a task behind. They only run if you wired
+         * `createCollectionTasks` into `app.tasks`. */
+        collectionSchedule: mutation(async (ctx, input) => {
+            const c = def(input.collection);
+            needs(c, "scheduling");
+            const db = cdb(ctx);
+            const row = await loadRow(db, c, input.id);
+            const now = Date.now();
+            const publishToken = new Date(input.publishAt).toISOString();
+            // Cross-call ordering. The boundary validator compares the two instants WITHIN one
+            // call, which is not the invariant that matters: the documented way to move a publish
+            // date is `collectionSchedule({ publishAt })` with `unpublishAt` omitted, and an
+            // omitted takedown is left standing. Without this check a reschedule could push the
+            // publish PAST a pending takedown — the takedown then fires first (clearing itself),
+            // the publish fires after it against nothing, and the row is public with no takedown
+            // left and no repair path. Compare against the takedown that will actually be in
+            // effect: the one being written, or the one already stored.
+            const effectiveUnpublish = input.unpublishAt !== undefined
+                ? typeof input.unpublishAt === "number"
+                    ? new Date(input.unpublishAt).toISOString()
+                    : null
+                : typeof row.unpublishAt === "string" && row.unpublishAt !== ""
+                    ? row.unpublishAt
+                    : null;
+            if (effectiveUnpublish !== null && effectiveUnpublish <= publishToken) {
+                throw new BadRequest(`publishAt (${publishToken}) is at or after the scheduled takedown (${effectiveUnpublish}) — move or cancel the takedown too (pass \`unpublishAt\`, or \`unpublishAt: null\` to cancel it)`);
+            }
+            // PATCH semantics on the takedown: an ABSENT `unpublishAt` leaves an existing one
+            // alone. Writing null unconditionally meant that merely moving the publish date
+            // revoked a scheduled removal — and silently, since clearing the column also
+            // neutralizes the already-enqueued task through the intent-token check. Pass
+            // `unpublishAt: null` to cancel one deliberately.
+            const hasUnpublish = input.unpublishAt !== undefined;
+            const unpublishToken = typeof input.unpublishAt === "number" ? new Date(input.unpublishAt).toISOString() : null;
+            const patch = { scheduledAt: publishToken };
+            if (hasUnpublish)
+                patch.unpublishAt = unpublishToken;
+            // `loadRow` above goes through the READ scope; this goes through the UPDATE scope,
+            // which can be narrower. Without the check a role that may read but not update the row
+            // got `{ ok: true }` and two enqueued tasks over a write that never landed — the tasks
+            // then found `scheduledAt` still null, mismatched their intent token, and no-op'd. A
+            // confirmed schedule that silently never fires. Every sibling handler checks this.
+            const updated = await db.update(c.entity, input.id, patch);
+            if (updated === undefined)
+                throw notFound(c.label);
+            await ctx.tasks.enqueue({
+                kind: TASK_COLLECTION_PUBLISH,
+                payload: { collection: c.slug, id: input.id, token: publishToken },
+                delayMs: Math.max(0, input.publishAt - now),
+            });
+            if (typeof input.unpublishAt === "number") {
+                await ctx.tasks.enqueue({
+                    kind: TASK_COLLECTION_UNPUBLISH,
+                    payload: { collection: c.slug, id: input.id, token: unpublishToken },
+                    delayMs: Math.max(0, input.unpublishAt - now),
+                });
+            }
+            return { ok: true, scheduledAt: publishToken, ...(hasUnpublish ? { unpublishAt: unpublishToken } : {}) };
+        }, {
+            ...editor,
+            input: (raw) => {
+                const o = asObj(raw);
+                const base = rowInput(raw);
+                // Range-checked, not merely finite — see `epochInput`. An out-of-range value would
+                // otherwise either throw a RangeError inside the transaction (an opaque 500) or
+                // mint an expanded-year ISO string that compares backwards forever.
+                const publishAt = epochInput("publishAt", o.publishAt);
+                // `null` is the explicit "cancel the takedown"; absent leaves it untouched.
+                if (o.unpublishAt !== undefined && o.unpublishAt !== null) {
+                    const unpublishAt = epochInput("unpublishAt", o.unpublishAt);
+                    if (unpublishAt <= publishAt)
+                        throw new BadRequest("unpublishAt must be after publishAt");
+                    return { ...base, publishAt, unpublishAt };
+                }
+                // Only `unpublishAt: null` (cancel) and an absent key reach here.
+                return "unpublishAt" in o ? { ...base, publishAt, unpublishAt: null } : { ...base, publishAt };
+            },
+        }),
+        // ---- revisions ----------------------------------------------------------
+        /** A row's revision history, newest first. */
+        collectionListRevisions: query(async (ctx, input) => {
+            const c = def(input.collection);
+            needs(c, "revisions");
+            const db = cdb(ctx);
+            // Read the ROW through the ACL first. `cms_collection_revisions` is shared across
+            // every collection and `collectionPolicies` grants it a flat allow(), so without this
+            // a role holding narrower per-entity read policies could list the snapshots of a
+            // collection it cannot read through `collectionGet`. `collectionRestoreRevision`
+            // already had this via `loadRow`; the list path did not.
+            const row = await loadRow(db, c, input.id);
+            const revs = await db.find({
+                from: COLLECTION_REVISIONS_TABLE,
+                where: { collection: c.slug, rowId: input.id },
+                // By the monotonic counter, never by a timestamp — see the `revision` column.
+                orderBy: { column: "revision", dir: "desc" },
+                limit: input.limit ?? 50,
+            });
+            // Project every snapshot to the fields THIS caller may read on the collection's own
+            // entity. The row check above is a ROW-level gate, and `collectionPolicies` grants the
+            // shared revisions table a flat allow() — so without this a caller holding a
+            // FIELD-restricted read policy (`fields: ["id", "title", "status"]`) reads back the
+            // columns that policy withholds, in full, out of the snapshot JSON. History must not
+            // be a way around the field scope that governs the row itself.
+            //
+            // `loadRow` came through the ACL, and reads are column-projected, so its keys ARE the
+            // caller's readable columns.
+            const readable = new Set(Object.keys(row));
+            return revs.map((r) => ({ ...r, snapshot: projectSnapshot(r.snapshot, readable) }));
+        }, {
+            ...editor,
+            input: (raw) => {
+                const o = asObj(raw);
+                if (o.limit !== undefined && (typeof o.limit !== "number" || !Number.isFinite(o.limit)))
+                    throw new BadRequest("limit must be a number");
+                // CLAMPED, not just validated: `find` binds this straight into `LIMIT ?`, and SQLite
+                // reads a negative limit as UNBOUNDED — so `limit: -1` would dump a row's entire
+                // history. A fractional value would reach the driver as-is.
+                const limit = o.limit === undefined ? undefined : Math.max(1, Math.min(Math.floor(o.limit), 200));
+                return { ...rowInput(raw), limit };
+            },
+        }),
+        /** Restore a row to one of its revisions. The CURRENT state is snapshotted first, so a
+         * restore is itself undoable. */
+        collectionRestoreRevision: mutation(async (ctx, input) => {
+            const c = def(input.collection);
+            needs(c, "revisions");
+            const db = cdb(ctx);
+            const revs = await db.find({ from: COLLECTION_REVISIONS_TABLE, where: { id: input.revisionId }, limit: 1 });
+            const rev = revs[0];
+            // Scope the revision to THIS collection AND row. A revision id is otherwise a global
+            // handle into a table shared by every collection, so an id from another row — or
+            // another collection entirely — would write a foreign snapshot over this row.
+            if (!rev || String(rev.collection) !== c.slug || String(rev.rowId) !== input.id)
+                throw notFound("revision");
+            const current = await loadRow(db, c, input.id);
+            // A snapshot is built from an ACL-PROJECTED row, so a caller whose read scope excluded
+            // every declared column stored `{}`. `Db.update` returns undefined for a zero-column
+            // patch, which would surface below as "not found" for a row loaded two lines earlier —
+            // a misleading 404. Say what is actually wrong instead.
+            // Restore exactly the fields this caller can READ, for the same reason
+            // `collectionListRevisions` projects them: the snapshot is complete (it was captured
+            // through the raw path), and the shared revisions table is granted flat, so replaying
+            // it whole would let a field-restricted editor write back columns their own read
+            // policy withholds — restoring a value they cannot see, out of a version they cannot
+            // read. What you can see is what you can put back.
+            const visible = projectSnapshot(rev.snapshot, new Set(Object.keys(current)));
+            const restore = toColumns(c, visible, false, current);
+            if (Object.keys(restore).length === 0) {
+                throw new BadRequest(`revision ${input.revisionId} has no restorable fields (none of its columns are readable by this caller)`);
+            }
+            await snapshotRow(db, c, current, ctx, "restore");
+            // Replay through the SAME validate + whitelist as an ordinary write: a snapshot taken
+            // before a field was dropped from `fields` must not resurrect that column, and one
+            // taken before a field's type changed must not bypass validation.
+            const updated = await db.update(c.entity, input.id, restore);
+            if (updated === undefined)
+                throw notFound(c.label);
+            return updated;
+        }, {
+            ...editor,
+            input: (raw) => {
+                const o = asObj(raw);
+                if (typeof o.revisionId !== "string" || o.revisionId === "")
+                    throw new BadRequest("revisionId is required");
+                return { ...rowInput(raw), revisionId: o.revisionId };
+            },
+        }),
+        // ---- 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
+         * 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) => {
+            const c = def(input.collection);
+            needs(c, "preview");
+            const secret = previewSecret(ctx.env);
+            if (!secret)
+                throw previewUnconfigured(); // fail closed — never mint a forgeable link
+            // Redemption always reaches a Durable Object (callPrivileged -> PRAMEN.get) and has no
+            // notion of `x-pramen-store`, so a link minted on D1 would 404 forever while the
+            // editor reported success.
+            if (ctx.store === "d1") {
+                throw new PramenError("collection preview is not available on the D1 store (redemption requires the Durable Object)", 503, "unavailable");
+            }
+            const row = await loadRow(cdb(ctx), c, input.id);
+            const ttl = Math.max(60, Math.min(input.expiresIn ?? previewTtl, 30 * 24 * 3600));
+            const exp = Math.floor(Date.now() / 1000) + ttl;
+            // Server-resolved, never caller-supplied, so the tenant inside the signature cannot
+            // be steered by whoever asks for the link.
+            const token = await signToken({ t: ctx.tenant, c: c.slug, r: String(row[idOf(c)]), exp }, secret);
+            // RELATIVE, like signed file urls — the client resolves it against the CMS origin.
+            return { url: `${COLLECTION_PREVIEW_PATH}?token=${encodeURIComponent(token)}`, token, expiresAt: exp * 1000 };
+        }, {
+            ...editor,
+            input: (raw) => {
+                const o = asObj(raw);
+                if (o.expiresIn !== undefined && (typeof o.expiresIn !== "number" || !Number.isFinite(o.expiresIn))) {
+                    throw new BadRequest("expiresIn must be a number of seconds");
+                }
+                return { ...rowInput(raw), expiresIn: o.expiresIn };
+            },
+        }),
+        /** Read one row's live (possibly unpublished) state. Not the redemption endpoint — that
+         * is the public `GET /cms/preview/collection` route, which verifies the token and then
+         * calls this privileged. Role-gated so it is not an anonymous back door on /rpc. */
+        getCollectionPreview: query(async (ctx, input) => {
+            const c = def(input.collection);
+            needs(c, "preview");
+            const row = await loadRow(cdb(ctx), c, input.id);
+            const values = { [idOf(c)]: row[idOf(c)] };
+            for (const f of c.fields)
+                if (f.name in row)
+                    values[f.name] = row[f.name];
+            if (has(c, "drafts"))
+                values.status = row.status;
+            return { collection: c.slug, id: String(row[idOf(c)]), values };
+        }, { ...viewer, input: rowInput }),
     };
 }
 /** ACL fragments granting the editor role full CRUD over each collection's entity. Spread
@@ -1628,8 +3016,178 @@ export function collectionPolicies(collections, opts = {}) {
             out.push(policy(`${p}:editor:collection:${c.entity}:${action}`, c.entity, action, allow()));
         }
     }
+    // The revision table is SHARED across collections, so it is not covered by the per-entity
+    // grants above. Granting it here — rather than leaning on `cmsPolicies().editor` — keeps
+    // `revisions` self-contained: an app that registers collections without using the
+    // block/page half still gets a working feature instead of a 403 on every write. Read +
+    // create only; a revision is append-only, and nothing exposes editing or purging one.
+    if (collections.some((c) => (c.supports ?? []).includes("revisions"))) {
+        for (const action of ["read", "create"]) {
+            out.push(policy(`${p}:editor:${COLLECTION_REVISIONS_TABLE}:${action}`, COLLECTION_REVISIONS_TABLE, action, allow()));
+        }
+    }
     return out;
 }
+/** ACL fragments granting ANONYMOUS read of the PUBLISHED rows of every collection that
+ * supports `drafts`. Spread into your public role next to `cmsPolicies().public`:
+ *
+ *   role("anonymous", [...cmsPolicies().public, ...collectionPublicPolicies(collections)])
+ *
+ * This is the access boundary, not a UI filter — it is AND-merged into every `ctx.db` read
+ * of the entity, so an unpublished row is invisible to the public API, to relation
+ * traversals and to eager-loads alike, without a single query remembering to filter.
+ *
+ * With `scheduling`, the scope also requires `publishedAt <= $now()`. `status` alone would
+ * not be enough the moment anything writes a future `publishedAt`, and `{ publishedAt:
+ * { isNull: false } }` — the obvious-looking alternative — matches a FUTURE timestamp too,
+ * so a row scheduled for next week would be anonymously readable the moment it was saved.
+ * The comparison is lexicographic over TEXT, which is why every managed timestamp is minted
+ * as ISO-8601 UTC (`isoStamp`), the same shape `$now()` produces.
+ *
+ * Collections WITHOUT `drafts` get nothing here: they have no publish state, so their
+ * public exposure is entirely your app's own policy to write. */
+export function collectionPublicPolicies(collections, opts = {}) {
+    const p = opts.prefix ?? "cms";
+    const out = [];
+    for (const c of collections) {
+        const features = c.supports ?? [];
+        if (!features.includes("drafts"))
+            continue;
+        const name = `${p}:public:collection:${c.entity}:read`;
+        // The PUBLIC surface is exactly what the collection declares as editable, plus its id
+        // and the two columns a public page legitimately reads: `status` (constant `published`
+        // for every visible row) and, with `scheduling`, `publishedAt`.
+        //
+        // Granting the whole row instead would quietly publish every future column: an
+        // `internalNote` or `reviewerEmail` added to the entity — deliberately NOT a field —
+        // would go world-readable the moment a row was published, with nothing at boot or in
+        // review to catch it. But excluding `publishedAt` went too far the other way: the
+        // single most obvious public query, "newest published first", 403s for anonymous while
+        // working for an editor, because a caller may not order by a column it cannot read.
+        // A publication date is public by construction — it is printed on the page. The
+        // FORWARD-looking columns stay private: `scheduledAt` and `unpublishAt` would leak
+        // "this comes down on Friday" to everyone.
+        const fields = [c.idField ?? "id", ...c.fields.map((f) => f.name), "status", ...(features.includes("scheduling") ? ["publishedAt"] : [])];
+        out.push(features.includes("scheduling")
+            ? policy(name, c.entity, "read", {
+                fields,
+                where: {
+                    status: COLLECTION_PUBLISHED,
+                    // Both time clauses are OR-groups, so they go in an explicit `AND: [...]` —
+                    // two `OR` keys in one object literal would be the same property, and the
+                    // second would silently REPLACE the first.
+                    AND: [
+                        {
+                            // `publishedAt <= $now()` alone silently hides every published row with
+                            // no stamp — a `cmsBootstrap` seed, an import, a row published while the
+                            // collection was still `supports: ["drafts"]` — and does it EN MASSE the
+                            // moment `scheduling` is added to an existing collection, because
+                            // `NULL <= '2026-…'` is NULL, not true. NULL here means "published,
+                            // instant unknown", never "scheduled for later": `publishedAt` is a
+                            // managed column (never in the write whitelist) that only ever takes
+                            // `isoStamp()` or null, and a row awaiting a scheduled publish is
+                            // `status: 'draft'` with the instant in `scheduledAt`. So a missing stamp
+                            // cannot be a future one, and treating it as "already published" is both
+                            // safe and what the editor already shows.
+                            OR: [{ publishedAt: { isNull: true } }, { publishedAt: { lte: $now() } }],
+                        },
+                        {
+                            // A scheduled TAKEDOWN has to be enforced HERE, not only by the task. The
+                            // publish side is belt-and-braces (policy + task), but without this clause
+                            // an unpublish depends entirely on `createCollectionTasks` being wired and
+                            // the outbox draining — if either fails, a row an editor scheduled to come
+                            // down stays world-readable indefinitely, with no signal. That is the
+                            // wrong way round for a takedown, the direction that matters legally.
+                            OR: [{ unpublishAt: { isNull: true } }, { unpublishAt: { gt: $now() } }],
+                        },
+                    ],
+                },
+            })
+            : policy(name, c.entity, "read", { fields, where: { status: COLLECTION_PUBLISHED } }));
+    }
+    return out;
+}
+/** Task handlers backing `collectionSchedule`. Register alongside `cmsTasks`:
+ *
+ *   const app = { tasks: { ...cmsTasks, ...createCollectionTasks(collections) } };
+ *
+ * WITHOUT THIS WIRING A SCHEDULE NEVER FIRES: `collectionSchedule` still stores the
+ * instants and enqueues the tasks, but the drain finds no handler for their kind, so the
+ * row silently stays a draft. (`cmsTasks` has the same requirement for page scheduling.)
+ *
+ * They run with a privileged, system-scoped ctx off the write path, and each validates its
+ * INTENT TOKEN against the row's current `scheduledAt`/`unpublishAt` before acting — see
+ * `collectionSchedule`. */
+export function createCollectionTasks(collections) {
+    const bySlug = new Map(collections.map((c) => [c.slug, c]));
+    const run = async (ctx, payload, tokenColumn, buildPatch) => {
+        const { collection, id, token } = asObj(payload);
+        if (typeof collection !== "string" || typeof id !== "string")
+            return;
+        // Resolved through the REGISTRY, exactly as the handlers do — the payload's `collection`
+        // is never used as a table name.
+        const c = bySlug.get(collection);
+        // A slug the handlers accept but this registry does not know is a WIRING mistake:
+        // `createCollectionHandlers(collections)` and `createCollectionTasks(otherList)` built
+        // from different arrays. Returning quietly made the drain report `{ succeeded: 1 }`
+        // while the row stayed a draft forever — strictly worse than not registering the tasks
+        // at all, which dead-letters loudly. Throw so the outbox retries and then dead-letters
+        // with the slug in the message.
+        if (!c)
+            throw new Error(`pramen/cms: no collection '${collection}' in createCollectionTasks' registry — pass the SAME collections array to createCollectionHandlers and createCollectionTasks`);
+        const db = cdb(ctx);
+        const rows = await db.find({ from: c.entity, where: { [c.idField ?? "id"]: id }, limit: 1 });
+        const row = rows[0];
+        if (!row)
+            return;
+        // Intent check: act only if this task is still the row's active schedule. A reschedule
+        // (new token), a manual publish/unpublish (token cleared) or a duplicate delivery after
+        // this task already ran all make it a no-op.
+        //
+        // Require a NON-EMPTY token on both sides. Comparing the coalesced strings alone treats
+        // "no token in the payload" and "no schedule on the row" as a MATCH — so a payload
+        // without a token (a hand-drained or replayed outbox row) against a row whose
+        // `scheduledAt` is null, the normal state right after an unpublish, would publish it
+        // unconditionally. The guard should fail closed, not open.
+        const stored = typeof row[tokenColumn] === "string" ? row[tokenColumn] : "";
+        if (!token || !stored || stored !== token)
+            return;
+        await db.update(c.entity, id, buildPatch(row, isoStamp()));
+    };
+    return {
+        [TASK_COLLECTION_PUBLISH]: (ctx, payload) => run(ctx, payload, "scheduledAt", (row, now) => {
+            // CONVERGE to the state the schedule implies AT `now`, rather than blindly applying
+            // the step this task was enqueued for. A drain can lag arbitrarily (D1 cron
+            // granularity, outbox backoff, a stalled DO alarm), and the two tasks can arrive in
+            // either order, so "publish" has to mean "publish IF the takedown has not come yet".
+            //
+            // The previous behavior — publish anyway, and null the passed `unpublishAt` to keep
+            // the row visible — destroyed a scheduled takedown outright: the token the unpublish
+            // task compares against was gone, so it no-op'd, and the read scope's
+            // `unpublishAt IS NULL OR unpublishAt > $now()` backstop had nothing left to enforce.
+            // A row scheduled to come down at noon stayed world-readable forever, silently.
+            // A takedown that failing OPEN cannot be recovered from is the wrong way round.
+            if (typeof row.unpublishAt === "string" && row.unpublishAt !== "" && row.unpublishAt <= now) {
+                // Both instants are in the past: the row's whole scheduled life has elapsed.
+                // Land on the END state (down), and spend both tokens so neither task can fire
+                // against this schedule again.
+                return { status: COLLECTION_DRAFT, publishedAt: null, scheduledAt: null, unpublishAt: null };
+            }
+            // The ordinary case: publish now, keep a still-future takedown standing.
+            return { status: COLLECTION_PUBLISHED, publishedAt: now, scheduledAt: null };
+        }),
+        [TASK_COLLECTION_UNPUBLISH]: (ctx, payload) => 
+        // Clear `scheduledAt` too — the third column `collectionUnpublish` clears and this
+        // task used to leave behind. A pending publish token that survived a takedown is a
+        // live re-publish: if the publish task drains after this one (either order is
+        // possible) or is retried after a throw, it finds its token still matching and puts
+        // the row back up — with `unpublishAt` now null, permanently and with no repair path.
+        // A schedule always orders publish BEFORE takedown (`collectionSchedule` enforces it
+        // against the stored value as well as the submitted one), so any `scheduledAt` still
+        // standing at the takedown is spent by definition.
+        run(ctx, payload, "unpublishAt", () => ({ status: COLLECTION_DRAFT, publishedAt: null, scheduledAt: null, unpublishAt: null })),
+    };
+}
 // --- deferred tasks (scheduled publish/unpublish) ----------------------------
 /** Task handlers backing `schedulePage`. Register via `app.tasks = { ...cmsTasks }`.
  * They run with a privileged, system-scoped ctx off the write path (the outbox drain).
@@ -1696,11 +3254,23 @@ export function robotsTxt(opts) {
     const dis = (opts.disallow ?? []).map((p) => `Disallow: ${p}`).join("\n");
     return `User-agent: *\n${dis ? dis + "\n" : "Allow: /\n"}Sitemap: ${opts.origin}/sitemap.xml\n`;
 }
-/** Turnkey public routes for `GET /sitemap.xml` and `GET /robots.txt`. Spread into
+const previewJson = (status, code, message) => 
+// `{ ok, error, code }` — the shape every other pramen error uses (runtime/errors.ts).
+new Response(JSON.stringify({ ok: false, error: message, code }), {
+    status,
+    headers: { "content-type": "application/json; charset=utf-8", "cache-control": "private, no-store" },
+});
+/** One response for a missing, malformed, forged, or expired token — and for a page that
+ * is not there. Distinguishing them would let a caller probe for valid page ids. */
+const previewDenied = (status = 403, message = "invalid or expired preview link") => previewJson(status, status === 404 ? "not_found" : "forbidden", message);
+const preview503 = () => previewJson(503, "unavailable", "page preview is not configured (set a strong PREVIEW_SECRET, FILES_SECRET or AUTH_SECRET)");
+/** Turnkey public routes for `GET /sitemap.xml`, `GET /cms/preview` and `GET /robots.txt`. Spread into
  * `app.routes`. The sitemap pulls published pages via `callPrivileged(listPublishedPages)`.
  * `origin` defaults to the request's origin; `pageUrl` customizes the URL shape. */
 export function cmsRoutes(opts = {}) {
     const tenant = opts.tenant ?? "main";
+    const previewRoles = opts.viewerRoles ?? viewerRolesOf(opts.handlers);
+    const collectionPreviewRoles = opts.viewerRoles ?? viewerRolesOf(opts.collectionHandlers ?? opts.handlers);
     return [
         {
             method: "GET",
@@ -1713,6 +3283,90 @@ export function cmsRoutes(opts = {}) {
                 return new Response(xml, { headers: { "content-type": "application/xml; charset=utf-8" } });
             },
         },
+        {
+            // Redeem a preview link. PUBLIC and pre-auth by design — the signature IS the
+            // authorization, so a reviewer with no account can open it. The token is verified
+            // BEFORE any read, and it names one page, so a valid signature never widens into
+            // "see all drafts". Only then do we reach the DO, privileged.
+            method: "GET",
+            path: PREVIEW_PATH,
+            handler: async (request, env, ctx) => {
+                const secret = previewSecret(env);
+                // Fail closed: with no usable secret every signature would verify against a weak
+                // key, so refuse to verify at all rather than accept forged links.
+                if (!secret)
+                    return preview503();
+                const raw = new URL(request.url).searchParams.get("token");
+                if (!raw)
+                    return previewDenied();
+                const payload = await verifyToken(raw, secret);
+                if (!payload || typeof payload.p !== "string" || typeof payload.t !== "string")
+                    return previewDenied();
+                // The synthetic identity has to satisfy BOTH gates the DO applies: the handler's
+                // `auth` (viewerRoles) and the row ACL (whatever role the app granted cmsPolicies
+                // to). Hardcoding ["admin"] satisfied neither under the wiring this package's own
+                // README documents — `role("anonymous", …)` + `role("editor", …)`, no admin role
+                // at all — so every preview link 404'd. The e2e only passed because example/app.ts
+                // happens to define an admin role. Send the configured viewer roles instead.
+                const res = await ctx.callPrivileged({
+                    name: "getPagePreview",
+                    input: { pageId: payload.p },
+                    tenant: payload.t, // from the SIGNED payload, never from the query string
+                    roles: [...previewRoles],
+                });
+                const body = (await res.json().catch(() => ({})));
+                if (body.ok !== true) {
+                    // The client-visible response stays uniform (probe resistance), but LOG the real
+                    // reason: a role misconfiguration previously surfaced as an indistinguishable
+                    // "page not found" that could only be diagnosed by reading source.
+                    console.error(`pramen/cms: preview redemption failed (${res.status} ${body.code ?? "?"}: ${body.error ?? "no detail"})`);
+                    return previewDenied(404, "page not found");
+                }
+                // Never cache a draft, anywhere.
+                return new Response(JSON.stringify(body.result), {
+                    headers: { "content-type": "application/json; charset=utf-8", "cache-control": "private, no-store" },
+                });
+            },
+        },
+        {
+            // Redeem a COLLECTION preview link. Same contract as the page preview route above:
+            // public and pre-auth by design (the signature IS the authorization, so a reviewer
+            // with no account can open it), verified BEFORE any read, and scoped by the signed
+            // payload to one row of one collection — a valid signature never widens into "see
+            // every draft".
+            method: "GET",
+            path: COLLECTION_PREVIEW_PATH,
+            handler: async (request, env, ctx) => {
+                const secret = previewSecret(env);
+                // Fail closed: with no usable secret every signature would verify against a weak
+                // key, so refuse to verify at all rather than accept forged links.
+                if (!secret)
+                    return preview503();
+                const raw = new URL(request.url).searchParams.get("token");
+                if (!raw)
+                    return previewDenied();
+                const payload = await verifyToken(raw, secret);
+                if (!payload || typeof payload.c !== "string" || typeof payload.r !== "string" || typeof payload.t !== "string")
+                    return previewDenied();
+                const res = await ctx.callPrivileged({
+                    name: "getCollectionPreview",
+                    input: { collection: payload.c, id: payload.r },
+                    tenant: payload.t, // from the SIGNED payload, never from the query string
+                    roles: [...collectionPreviewRoles], // the COLLECTION handlers' gate — see `collectionHandlers`
+                });
+                const body = (await res.json().catch(() => ({})));
+                if (body.ok !== true) {
+                    // Uniform client-visible response (probe resistance), but LOG the real reason —
+                    // a role or wiring mistake here is otherwise indistinguishable from "not found".
+                    console.error(`pramen/cms: collection preview redemption failed (${res.status} ${body.code ?? "?"}: ${body.error ?? "no detail"})`);
+                    return previewDenied(404, "not found");
+                }
+                // Never cache a draft, anywhere.
+                return new Response(JSON.stringify(body.result), {
+                    headers: { "content-type": "application/json; charset=utf-8", "cache-control": "private, no-store" },
+                });
+            },
+        },
         {
             method: "GET",
             path: "/robots.txt",