@pramen/cms 0.0.48 → 0.0.50

package/src/index.ts

@@ -38,12 +38,20 @@ import {
   expr,
   policy,
   allow,
+  $now,
+  partitionOf,
+  DEFAULT_PARTITION,
   BadRequest,
   Forbidden,
   PramenError,
+  Conflict,
+  signToken,
+  verifyToken,
+  resolveSecret,
 } from "@pramen/server";
-import type { HandlerContext, Policy, FileRef, BootstrapFn } from "@pramen/server";
-import { filterXSS } from "xss";
+import type { HandlerContext, Policy, FileRef, BootstrapFn, JsonValue, SchemaDef, FieldDef, FieldType } from "@pramen/server";
+import type { EnvBag } from "@pramen/server";
+import { isSafeHref, normalizeHref } from "./href";
 
 // --- field schema DSL (the block-editor field language) ---------------------
 
@@ -131,7 +139,7 @@ export interface RegionDefinition {
 export interface DefaultBlockDefinition {
   region: string;
   blockTypeSlug: string;
-  fields?: Record<string, unknown>;
+  fields?: FieldValues;
 }
 
 // --- hybrid typed blocks: compile-time inference over a const FieldDefinition[] --------
@@ -142,8 +150,38 @@ export interface DefaultBlockDefinition {
 // the schema, exactly like `typeof app.handlers` types the RPC client. (A `pramen cms codegen`
 // command that emits these types from DB-stored schemas is future work.)
 
-/** A rich-text value — a serialized editor document (or a plain string). */
-export type RichText = string | { type: string; content?: unknown[] };
+/**
+ * A rich-text document — the editor's structured JSON (a ProseMirror/TipTap doc tree).
+ *
+ * **Not an HTML string.** HTML never enters storage: the write path validates this tree
+ * against a node/mark allow-list (`normalizeRichText`) and the render side maps node types
+ * to components, so there is no `set:html` / `dangerouslySetInnerHTML` anywhere in the
+ * chain and nothing to scrub. The one attribute that can still carry script is a `link`
+ * mark's `href`, so that one IS checked — see `isSafeHref`.
+ */
+export interface RichTextDoc {
+  type: "doc";
+  content?: RichTextNode[];
+}
+
+/** One node in a {@link RichTextDoc}. A leaf carries `text` (plus optional inline `marks`);
+ * a container carries `content`. */
+export interface RichTextNode {
+  type: string;
+  content?: RichTextNode[];
+  text?: string;
+  marks?: RichTextMark[];
+  attrs?: Record<string, JsonValue>;
+}
+
+/** An inline mark on a text node — bold, link, highlight, … */
+export interface RichTextMark {
+  type: string;
+  attrs?: Record<string, JsonValue>;
+}
+
+/** The value of a `richtext` field. */
+export type RichText = RichTextDoc;
 
 /** Map one FieldDefinition (as a const literal) to the TS type of its RENDERED value.
  * Media resolves to `ResolvedMedia` (the assemble-time shape a component receives). */
@@ -341,12 +379,45 @@ function tsTypeOf(f: FieldDefinition): string {
       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: readonly FieldDefinition[]): string[] {
+  const found = new Set<string>();
+  const walk = (defs: readonly FieldDefinition[]): void => {
+    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: FieldDefinition): string => `${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: Array<{ slug: string; fieldsSchema?: FieldDefinition[] | null }>): string {
+  // 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<string, string>();
+  const bad: string[] = [];
+  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 : [];
@@ -355,11 +426,16 @@ export function generateBlockTypes(blockTypes: Array<{ slug: string; fieldsSchem
     })
     .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 --------
@@ -396,6 +472,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()),
     }),
@@ -425,6 +504,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(),
@@ -434,6 +518,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()),
     }),
@@ -490,12 +576,53 @@ export const cmsSchema = {
     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()),
   })),
 };
@@ -507,6 +634,16 @@ export interface ValidateOpts {
    * writes (addBlock/updateBlock/createPage) pass `false` — a DRAFT block may be incomplete;
    * required is only mandatory when publishing. Type checks always run. */
   requireRequired?: boolean;
+  /** The row's CURRENTLY STORED field values. A legacy HTML-string `richtext` value is
+   * tolerated only when it is byte-identical to the stored one — i.e. the caller echoed
+   * back a pre-Portable-Text value it never authored (the editor autosaves the whole bag).
+   * Anything else is rejected.
+   *
+   * This must NOT be a plain boolean. The `xss` sanitizer is gone, and `normalizeFields`
+   * passes a tolerated string through untouched, so a blanket "allow strings" would let
+   * any caller store arbitrary unsanitized HTML — which every consumer still on the
+   * pre-migration `set:html` contract would then execute. */
+  legacyBaseline?: FieldValues;
 }
 
 /** Validate a block/page's `fields` payload against a field schema, throwing a 400 on
@@ -529,7 +666,7 @@ function isDateTimeString(v: string): boolean {
 export function validateFields(schema: FieldDefinition[] | undefined | null, values: unknown, path = "", opts: ValidateOpts = {}): void {
   const requireRequired = opts.requireRequired !== false;
   const defs = Array.isArray(schema) ? schema : [];
-  const obj = (values ?? {}) as Record<string, unknown>;
+  const obj = (values ?? {}) as FieldValues;
   if (typeof obj !== "object" || Array.isArray(obj)) throw new BadRequest(`${path || "fields"} must be an object`);
   for (const def of defs) {
     const at = path ? `${path}.${def.name}` : def.name;
@@ -555,7 +692,18 @@ export function validateFields(schema: FieldDefinition[] | undefined | null, val
         if (!isSlugString(v)) 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 as unknown as RichTextDoc).type !== "doc") {
+          throw new BadRequest(`field '${at}' must be a rich-text document ({ type: "doc", content: [...] })`);
+        }
         break;
       case "number":
         if (typeof v !== "number") throw new BadRequest(`field '${at}' must be a number`);
@@ -576,14 +724,35 @@ export function validateFields(schema: FieldDefinition[] | undefined | null, val
         // (collectMediaIds/resolveMediaFields only handle string ids).
         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 as FieldValues) : undefined,
+        });
         break;
+      }
       case "repeater": {
         if (!Array.isArray(v)) throw new BadRequest(`field '${at}' must be a list`);
         if (def.min != null && v.length < def.min) 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 as FieldValues) : undefined,
+            });
+          });
+        }
         break;
       }
       default:
@@ -592,39 +761,216 @@ export function validateFields(schema: FieldDefinition[] | undefined | null, val
   }
 }
 
-// --- rich-text sanitization (server-side — the real XSS boundary) -------------
+// --- rich text: the structural allow-list (server-side — the real XSS boundary) ---
+//
+// A `richtext` value is a document TREE, so there is no HTML to scrub — the boundary is
+// STRUCTURAL: an unknown node or mark type is dropped, only the attributes declared for a
+// type survive, an attribute value must be a JSON primitive, and a `link` href must pass a
+// scheme allow-list. Client-side checks are not a boundary — a caller can POST any value
+// straight to these handlers — so this runs on write, like the HTML sanitizer it replaces.
 //
-// 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: Record<string, string[]> = {
-  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"],
+// Everything here is SYNCHRONOUS and pure. That still matters: normalization runs inside
+// the DO's storage.transaction(), where async stream I/O (e.g. HTMLRewriter) deadlocks —
+// the same constraint that once ruled out a DOM-based sanitizer.
+
+/** The node/mark vocabulary a `richtext` value may use. A node entry maps a node type to
+ * the attribute names kept on it; a mark entry does the same for a mark type. */
+export interface RichTextSchema {
+  nodes: Record<string, readonly string[]>;
+  marks: Record<string, readonly string[]>;
+  /** Highest heading level accepted; anything above is CLAMPED to it, not dropped.
+   * Defaults to `MAX_HEADING_LEVEL` (3, the shipped editor's StarterKit config). Raise it
+   * if your editor is configured for more — this is the widening the docs promise. */
+  maxHeadingLevel?: number;
+}
+
+/** 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: RichTextSchema = {
+  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"] as string[] };
 
-/** Sanitize one richtext HTML string to the allow-list. Synchronous by design. */
-function sanitizeRichText(html: string): string {
-  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: Record<string, readonly string[]>, type: unknown): readonly string[] | undefined {
+  if (typeof type !== "string" || !Object.hasOwn(table, type)) return undefined;
+  return table[type];
+}
+
+function normalizeAttrs(attrs: unknown, allowed: readonly string[], maxHeading: number = MAX_HEADING_LEVEL): Record<string, JsonValue> | undefined {
+  if (!allowed.length || !attrs || typeof attrs !== "object" || Array.isArray(attrs)) return undefined;
+  const out: Record<string, JsonValue> = {};
+  for (const name of allowed) {
+    const v = (attrs as Record<string, unknown>)[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: unknown, schema: RichTextSchema): RichTextMark[] | undefined {
+  if (!Array.isArray(marks)) return undefined;
+  const out: RichTextMark[] = [];
+  for (const raw of marks) {
+    if (!raw || typeof raw !== "object") continue;
+    const mark = raw as RichTextMark;
+    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: unknown, schema: RichTextSchema, depth = 0): RichTextNode | null {
+  if (depth > MAX_RICH_TEXT_DEPTH) return null;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const node = raw as RichTextNode;
+  const allowed = allowedAttrsFor(schema.nodes, node.type);
+  if (!allowed) return null;
+
+  const out: RichTextNode = { 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: readonly unknown[], schema: RichTextSchema, depth = 0): RichTextNode[] {
+  const out: RichTextNode[] = [];
+  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: unknown, schema: RichTextSchema = DEFAULT_RICH_TEXT_SCHEMA): RichTextDoc {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return { type: "doc", content: [] };
+  const content = Array.isArray((value as RichTextDoc).content) ? normalizeNodes((value as RichTextDoc).content ?? [], schema) : [];
+  return { type: "doc", content };
+}
+
+/** 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: RichTextDoc | null | undefined): string {
+  const parts: string[] = [];
+  const walk = (nodes: readonly RichTextNode[]): void => {
+    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-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: FieldDefinition[] | undefined | null, values: Record<string, unknown>): Record<string, unknown> {
+/** 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: FieldDefinition[] | undefined | null,
+  values: FieldValues,
+  richTextSchema: RichTextSchema = DEFAULT_RICH_TEXT_SCHEMA,
+): FieldValues {
   const defs = Array.isArray(schema) ? schema : [];
-  const out: Record<string, unknown> = { ...values };
+  const out: FieldValues = { ...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);
-    else if (def.type === "group" && typeof v === "object" && !Array.isArray(v)) out[def.name] = sanitizeFields(def.fields, v as Record<string, unknown>);
-    else if (def.type === "repeater" && Array.isArray(v)) out[def.name] = v.map((it) => (it && typeof it === "object" ? sanitizeFields(def.fields, it as Record<string, unknown>) : it));
+    // 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] = normalizeFields(def.fields, v as FieldValues, richTextSchema);
+    else if (def.type === "repeater" && Array.isArray(v)) out[def.name] = v.map((it) => (it && typeof it === "object" ? normalizeFields(def.fields, it as FieldValues, richTextSchema) : it));
   }
   return out;
 }
@@ -632,13 +978,15 @@ export function sanitizeFields(schema: FieldDefinition[] | undefined | null, val
 // --- assembled-page shape (the content-API result + revision snapshot) --------
 
 export interface RenderedBlock {
+  /** The block's optimistic-concurrency token — pass back as `expectedVersion`. */
+  version: number;
   /** The placement id (cms_page_blocks) — stable per position; used for reorder/remove. */
   id: string;
   /** The underlying block instance id (cms_blocks) — used to edit the block's content. */
   block_id: string;
   block_type: string;
   title: string | null;
-  fields: Record<string, unknown>;
+  fields: FieldValues;
   is_shared: boolean;
 }
 
@@ -671,17 +1019,32 @@ export interface AssembledPage {
     translationGroupId: string | null;
     /** Published sibling locales of this page (for hreflang alternates). */
     translations: PageTranslation[];
-    fields: Record<string, unknown> | null;
+    fields: FieldValues | null;
     /** Back-compat: mirrors seo.metaTitle/metaDescription. */
     metaTitle: string | null;
     metaDescription: string | null;
     seo: PageSeo;
+    /** Optimistic-concurrency token — pass back as `expectedVersion` on a write. */
+    version: number;
   };
   regions: Record<string, RenderedBlock[]>;
+  /** True when this is a live draft assembled behind a preview grant, rather than the
+   * published snapshot — so a frontend can render a "you are viewing a draft" banner. */
+  isPreview?: boolean;
 }
 
 // --- media -------------------------------------------------------------------
 
+/** One authored field value inside a block / collection / page `fields` bag. Stored
+ * as JSON; a `"media"` field is resolved from its stored id to a `ResolvedMedia` at
+ * assemble time, and `group`/`repeater` fields nest further bags. */
+export type FieldValue = JsonValue | ResolvedMedia | RichTextDoc | FieldValues | FieldValue[];
+
+/** A block / collection / page `fields` bag — field name -> authored value. */
+export interface FieldValues {
+  [field: string]: FieldValue;
+}
+
 /** A `"media"` block field, resolved from a stored media id to a servable shape at
  * assemble time. `url` is the raw (full-size) serving path; pass `key` to `imageUrl()`
  * for on-the-fly transforms. `null` when the referenced media was deleted. */
@@ -720,7 +1083,7 @@ export function imageUrl(
 }
 
 /** Collect the media ids referenced by a fields payload, walking group/repeater nesting. */
-function collectMediaIds(fields: Record<string, unknown>, schema: FieldDefinition[] | undefined, acc: Set<string>): void {
+function collectMediaIds(fields: FieldValues, schema: FieldDefinition[] | undefined, acc: Set<string>): void {
   if (!Array.isArray(schema)) return;
   for (const def of schema) {
     const v = fields[def.name];
@@ -738,12 +1101,12 @@ function collectMediaIds(fields: Record<string, unknown>, schema: FieldDefinitio
 /** Return a copy of `fields` with every `"media"` field resolved from its id to a
  * `ResolvedMedia` (or null), recursing into group/repeater nesting. */
 function resolveMediaFields(
-  fields: Record<string, unknown>,
+  fields: FieldValues,
   schema: FieldDefinition[] | undefined,
   mediaById: Map<string, ResolvedMedia>,
-): Record<string, unknown> {
+): FieldValues {
   if (!Array.isArray(schema)) return fields;
-  const out: Record<string, unknown> = { ...fields };
+  const out: FieldValues = { ...fields };
   for (const def of schema) {
     const v = out[def.name];
     if (v == null) continue;
@@ -782,7 +1145,7 @@ interface CmsDb {
 const cdb = (ctx: HandlerContext): CmsDb => ctx.db as unknown as CmsDb;
 
 const notFound = (what: string) => new PramenError(`${what} not found`, 404, "not_found");
-const asObj = (v: unknown): Record<string, unknown> => (v && typeof v === "object" ? (v as Record<string, unknown>) : {});
+const asObj = (v: unknown): FieldValues => (v && typeof v === "object" ? (v as FieldValues) : {});
 // Timestamps in the SAME shape as the `expr.now()` column default (`datetime('now')`:
 // "YYYY-MM-DD HH:MM:SS", UTC, second precision) so a column's insert-default and its
 // handler-written updates stay lexically comparable (an ISO `T`/`Z` string sorts wrong).
@@ -816,7 +1179,9 @@ async function assembleLive(db: CmsDb, page: Record<string, unknown>): Promise<A
   // fields (id → ResolvedMedia) in one batched lookup across the whole page.
   const merged = placements.map((p) => {
     const block = asObj(p.block);
-    const fields = { ...asObj(block.fields), ...(p.isShared ? asObj(p.overrides) : {}) };
+    const fields = p.isShared
+      ? { ...asObj(block.fields), ...asObj(p.overrides) }
+      : { ...asObj(block.fields) };
     return { p, block, fields, schema: typeById.get(String(block.typeId))?.fieldsSchema };
   });
   const mediaIds = new Set<string>();
@@ -843,6 +1208,7 @@ async function assembleLive(db: CmsDb, page: Record<string, unknown>): Promise<A
     (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 as string | null) ?? null,
       fields: resolveMediaFields(m.fields, m.schema, mediaById),
@@ -905,10 +1271,11 @@ function pageMeta(page: Record<string, unknown>, translations: PageTranslation[]
     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 as string | null) ?? null,
     translations,
-    fields: (page.fields as Record<string, unknown> | null) ?? null,
+    fields: (page.fields as FieldValues | null) ?? null,
     metaTitle,
     metaDescription,
     seo: {
@@ -953,6 +1320,59 @@ async function assertRegionAllows(db: CmsDb, page: Record<string, unknown>, regi
 
 // --- handlers ----------------------------------------------------------------
 
+// --- page preview links (signed capability urls) -----------------------------
+//
+// Preview used to be a ROLE check, so previewing a draft required an editor account —
+// which excludes the person preview actually exists for: the stakeholder reviewing copy
+// before it ships. A preview link is instead a signed, self-expiring CAPABILITY: it names
+// ONE page, carries its own expiry, and is verified in the Worker before any read happens.
+// Minting stays editor-gated; redeeming needs no account at all.
+//
+// Same machinery as signed file urls (`signToken`/`verifyToken` from @pramen/server), and
+// the same fail-closed rule: without a usable secret we refuse to mint rather than hand out
+// forgeable links.
+
+/** What a preview link authorizes: one page, in one tenant, until `exp`. */
+export interface PreviewToken {
+  /** tenant */ t: string;
+  /** page id — the grant is scoped to this ONE page, never "all drafts" */ p: string;
+  /** expiry (epoch seconds) */ exp: number;
+}
+
+/** 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"] as const;
+
+/** Resolve the preview signing secret, or `undefined` when nothing usable is configured. */
+export function previewSecret(env: EnvBag): string | undefined {
+  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: CmsHandlerOpts = {}): string[] {
+  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;
+
 export interface CmsHandlerOpts {
   /** Roles permitted to call the editor mutations (also enforced by the ACL). Default
    * `["editor", "admin"]`. */
@@ -964,6 +1384,12 @@ export interface CmsHandlerOpts {
   /** Roles permitted to approve/reject a page in review and publish (the editorial gate).
    * Default `["reviewer", "admin"]`. */
   reviewerRoles?: readonly string[];
+  /** Preview-link lifetime in seconds. Default 3600 (1 hour). */
+  previewTtlSeconds?: number;
+  /** The node/mark vocabulary accepted on write. Defaults to `DEFAULT_RICH_TEXT_SCHEMA`
+   * (what the shipped editor produces). Widen it if your editor adds TipTap extensions —
+   * a node type absent from the schema is DROPPED on write, not rejected. */
+  richTextSchema?: RichTextSchema;
 }
 
 /** Build the CMS handler map. Spread into your app's handlers. Editor mutations are
@@ -975,6 +1401,8 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
   const defaultLocale = opts.defaultLocale ?? "en";
   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])];
@@ -986,14 +1414,86 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
   const writeAudit = (db: CmsDb, e: { pageId: string; action: string; from?: string; to?: string; actor: string | null; note?: string }) =>
     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: unknown): { id: string } => {
+      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: CmsDb, ...tables: string[]): void => {
+    const touched = (db as unknown as { touched?: Set<string> }).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: Record<string, unknown>, expected: number | undefined, label: string): number => {
+    // 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: Record<string, unknown>): void => {
+    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: unknown): { pageId: string } => {
+      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: CmsDb, slug: string, locale: string, exceptId?: string): Promise<void> => {
     const rows = await db.exec(
-      "SELECT id FROM cms_pages WHERE slug = ? AND locale = ? LIMIT 1",
+      "SELECT id, deletedAt FROM cms_pages WHERE slug = ? AND locale = ? LIMIT 1",
       slug,
       locale,
     );
-    if (rows[0] && String(rows[0].id) !== exceptId) throw new BadRequest(`slug '${slug}' already exists for locale '${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";
@@ -1161,16 +1661,19 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
       },
     }),
 
-    /** 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: { id: string }) => {
       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,
@@ -1181,6 +1684,32 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
       },
     }),
 
+    restoreMedia: mutation(async (ctx, input: { id: string }) => {
+      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 as const };
+    }, { ...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: { id: string }) => {
+      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) as { key?: string }) : 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 as const };
+    }, { ...reviewer, ...mediaIdInput }),
+
     listContentTypes: query((ctx) => cdb(ctx).find({ from: "cms_content_types", orderBy: { column: "name" } }), viewer),
 
     getContentType: query(async (ctx, input: { id: string }) => {
@@ -1212,9 +1741,12 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
     }),
 
     /** Update a page's SEO fields (meta/canonical/robots/OpenGraph/JSON-LD). Editor-gated. */
-    updatePageSeo: mutation(async (ctx, input: { pageId: string; metaTitle?: string | null; metaDescription?: string | null; canonicalUrl?: string | null; robots?: string | null; ogTitle?: string | null; ogDescription?: string | null; ogImage?: string | null; structuredData?: unknown }) => {
+    updatePageSeo: mutation(async (ctx, input: { pageId: string; metaTitle?: string | null; metaDescription?: string | null; canonicalUrl?: string | null; robots?: string | null; ogTitle?: string | null; ogDescription?: string | null; ogImage?: string | null; structuredData?: unknown; expectedVersion?: number }) => {
       const db = cdb(ctx);
-      const patch: Record<string, unknown> = { 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: Record<string, unknown> = { updatedAt: nowStamp(), version: nextVersion(seoRows[0], input.expectedVersion, "this page") };
       for (const k of ["metaTitle", "metaDescription", "canonicalUrl", "robots", "ogTitle", "ogDescription", "ogImage"] as const) {
         if (k in input) patch[k] = (input as Record<string, unknown>)[k];
       }
@@ -1227,6 +1759,7 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
       input: (raw): { pageId: string } => {
         const o = asObj(raw);
         if (typeof o.pageId !== "string") throw new BadRequest("pageId is required");
+        versionInput(o);
         return o as never;
       },
     }),
@@ -1236,13 +1769,13 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
      * 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. */
-    updatePage: mutation(async (ctx, input: { pageId: string; title?: string; slug?: string; locale?: string; fields?: Record<string, unknown> }) => {
+     * + normalized against the content type's fieldsSchema, exactly like createPage. */
+    updatePage: mutation(async (ctx, input: { pageId: string; title?: string; slug?: string; locale?: string; fields?: FieldValues; expectedVersion?: number }) => {
       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: Record<string, unknown> = { updatedAt: nowStamp() };
+      const patch: Record<string, unknown> = { updatedAt: nowStamp(), version: nextVersion(page, input.expectedVersion, "this page") };
       if (input.title !== undefined) patch.title = input.title;
       if (input.slug !== undefined || input.locale !== undefined) {
         const nextSlug = input.slug ?? String(page.slug);
@@ -1254,32 +1787,34 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
       if (input.fields !== undefined) {
         const ctRows = await db.find({ from: "cms_content_types", where: { id: page.typeId }, limit: 1 });
         const schema = ctRows[0]?.fieldsSchema as FieldDefinition[] | undefined;
-        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) as FieldValues });
+        patch.fields = normalizeFields(schema, input.fields, rtSchema);
       }
       const updated = await db.update("cms_pages", input.pageId, patch);
       if (!updated) throw notFound("page");
       return { ok: true, page: updated };
     }, {
       ...editor,
-      input: (raw): { pageId: string; title?: string; slug?: string; locale?: string; fields?: Record<string, unknown> } => {
+      input: (raw): { pageId: string; title?: string; slug?: string; locale?: string; fields?: FieldValues; expectedVersion?: number } => {
         const o = asObj(raw);
         if (typeof o.pageId !== "string") throw new BadRequest("pageId is required");
         for (const k of ["title", "slug", "locale"] as const) {
           if (o[k] !== undefined && typeof o[k] !== "string") throw new BadRequest(`${k} must be a string`);
         }
+        versionInput(o);
         return o as never;
       },
     }),
 
     /** Create a page and auto-scaffold its content type's default blocks. */
-    createPage: mutation(async (ctx, input: { typeId: string; title: string; slug: string; locale?: string; fields?: Record<string, unknown> }) => {
+    createPage: mutation(async (ctx, input: { typeId: string; title: string; slug: string; locale?: string; fields?: FieldValues }) => {
       const db = cdb(ctx);
       const ctRows = await db.find({ from: "cms_content_types", where: { id: input.typeId }, limit: 1 });
       const ct = ctRows[0];
       if (!ct) throw new BadRequest("unknown content type");
       validateFields(ct.fieldsSchema as FieldDefinition[] | undefined, input.fields ?? {}, "page.fields", { requireRequired: false });
-      const cleanPageFields = await sanitizeFields(ct.fieldsSchema as FieldDefinition[] | undefined, input.fields ?? {});
+      const cleanPageFields = normalizeFields(ct.fieldsSchema as FieldDefinition[] | undefined, input.fields ?? {}, rtSchema);
       const locale = input.locale ?? defaultLocale;
       await assertSlugFree(db, input.slug, locale);
 
@@ -1303,7 +1838,7 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
           if (!bts[0]) throw new BadRequest(`unknown block type '${d.blockTypeSlug}'`);
           await assertRegionAllows(db, page, d.region, d.blockTypeSlug);
           validateFields(bts[0].fieldsSchema as FieldDefinition[] | undefined, d.fields ?? {}, "", { requireRequired: false });
-          const cleanDefault = await sanitizeFields(bts[0].fieldsSchema as FieldDefinition[] | undefined, d.fields ?? {});
+          const cleanDefault = normalizeFields(bts[0].fieldsSchema as FieldDefinition[] | undefined, 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 });
@@ -1314,7 +1849,7 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
       return page;
     }, {
       ...editor,
-      input: (raw): { typeId: string; title: string; slug: string; locale?: string; fields?: Record<string, unknown> } => {
+      input: (raw): { typeId: string; title: string; slug: string; locale?: string; fields?: FieldValues } => {
         const o = asObj(raw);
         if (typeof o.typeId !== "string" || typeof o.title !== "string" || typeof o.slug !== "string") {
           throw new BadRequest("typeId, title and slug are required");
@@ -1341,8 +1876,22 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
         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", {
@@ -1385,7 +1934,9 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
 
     /** Distinct locales present across all pages. */
     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),
 
@@ -1393,7 +1944,7 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
     /** Create a block instance and place it into a page region in one call (the common
      * editor action). Validates the fields against the block type's schema and the region
      * against the content type's allow-list. */
-    addBlock: mutation(async (ctx, input: { pageId: string; blockTypeSlug: string; region: string; fields?: Record<string, unknown>; title?: string; position?: number; isReusable?: boolean }) => {
+    addBlock: mutation(async (ctx, input: { pageId: string; blockTypeSlug: string; region: string; fields?: FieldValues; title?: string; position?: number; isReusable?: boolean }) => {
       const db = cdb(ctx);
       const pages = await db.find({ from: "cms_pages", where: { id: input.pageId }, limit: 1 });
       const page = pages[0];
@@ -1401,7 +1952,7 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
       const bt = await loadBlockTypeBySlug(db, input.blockTypeSlug);
       await assertRegionAllows(db, page, input.region, input.blockTypeSlug);
       validateFields(bt.fieldsSchema as FieldDefinition[] | undefined, input.fields ?? {}, "", { requireRequired: false });
-      const cleanFields = await sanitizeFields(bt.fieldsSchema as FieldDefinition[] | undefined, input.fields ?? {});
+      const cleanFields = normalizeFields(bt.fieldsSchema as FieldDefinition[] | undefined, input.fields ?? {}, rtSchema);
 
       const block = await db.insert("cms_blocks", {
         typeId: bt.id,
@@ -1420,7 +1971,7 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
       return { block, placement };
     }, {
       ...editor,
-      input: (raw): { pageId: string; blockTypeSlug: string; region: string; fields?: Record<string, unknown>; title?: string; position?: number; isReusable?: boolean } => {
+      input: (raw): { pageId: string; blockTypeSlug: string; region: string; fields?: FieldValues; title?: string; position?: number; isReusable?: boolean } => {
         const o = asObj(raw);
         if (typeof o.pageId !== "string" || typeof o.blockTypeSlug !== "string" || typeof o.region !== "string") {
           throw new BadRequest("pageId, blockTypeSlug and region are required");
@@ -1435,7 +1986,7 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
      * can be placed on several pages; editing it updates them all, while `overrides` let one
      * placement diverge. The merged (base + overrides) result is validated against the
      * block type's field schema. */
-    placeBlock: mutation(async (ctx, input: { pageId: string; blockId: string; region: string; position?: number; overrides?: Record<string, unknown> }) => {
+    placeBlock: mutation(async (ctx, input: { pageId: string; blockId: string; region: string; position?: number; overrides?: FieldValues }) => {
       const db = cdb(ctx);
       const pages = await db.find({ from: "cms_pages", where: { id: input.pageId }, limit: 1 });
       const page = pages[0];
@@ -1448,8 +1999,12 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
       await assertRegionAllows(db, page, input.region, slug);
       let cleanOverrides: Record<string, unknown> | null = input.overrides ?? null;
       if (input.overrides !== undefined) {
-        validateFields(bts[0]?.fieldsSchema as FieldDefinition[] | undefined, { ...asObj(block.fields), ...input.overrides }, "", { requireRequired: false });
-        cleanOverrides = await sanitizeFields(bts[0]?.fieldsSchema as FieldDefinition[] | undefined, 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 as FieldDefinition[] | undefined, { ...asObj(block.fields), ...input.overrides }, "", { requireRequired: false, legacyBaseline: asObj(block.fields) as FieldValues });
+        validateFields(bts[0]?.fieldsSchema as FieldDefinition[] | undefined, input.overrides, "", { requireRequired: false });
+        cleanOverrides = normalizeFields(bts[0]?.fieldsSchema as FieldDefinition[] | undefined, input.overrides, rtSchema);
       }
       const position = input.position ?? (await nextPosition(db, input.pageId, input.region));
       return db.insert("cms_page_blocks", {
@@ -1462,7 +2017,7 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
       });
     }, {
       ...editor,
-      input: (raw): { pageId: string; blockId: string; region: string; position?: number; overrides?: Record<string, unknown> } => {
+      input: (raw): { pageId: string; blockId: string; region: string; position?: number; overrides?: FieldValues } => {
         const o = asObj(raw);
         if (typeof o.pageId !== "string" || typeof o.blockId !== "string" || typeof o.region !== "string") {
           throw new BadRequest("pageId, blockId and region are required");
@@ -1485,26 +2040,33 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
     }),
 
     /** Update a block's content (re-validated against its type's field schema). */
-    updateBlock: mutation(async (ctx, input: { blockId: string; fields?: Record<string, unknown>; title?: string }) => {
+    updateBlock: mutation(async (ctx, input: { blockId: string; fields?: FieldValues; title?: string; expectedVersion?: number }) => {
       const db = cdb(ctx);
       const rows = await db.find({ from: "cms_blocks", where: { id: input.blockId }, limit: 1 });
       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 as FieldDefinition[] | undefined, input.fields, "", { requireRequired: false });
-        cleanFields = await sanitizeFields(bt[0]?.fieldsSchema as FieldDefinition[] | undefined, 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 as FieldDefinition[] | undefined, input.fields, "", { requireRequired: false, legacyBaseline: asObj(block.fields) as FieldValues });
+        cleanFields = normalizeFields(bt[0]?.fieldsSchema as FieldDefinition[] | undefined, input.fields, rtSchema);
       }
-      const patch: Record<string, unknown> = { updatedAt: nowStamp() };
+      const patch: Record<string, unknown> = { updatedAt: nowStamp(), version: blockVersion };
       if (cleanFields !== undefined) patch.fields = cleanFields;
       if (input.title !== undefined) patch.title = input.title;
       return db.update("cms_blocks", input.blockId, patch);
     }, {
       ...editor,
-      input: (raw): { blockId: string; fields?: Record<string, unknown>; title?: string } => {
+      input: (raw): { blockId: string; fields?: FieldValues; title?: string; expectedVersion?: number } => {
         const o = asObj(raw);
         if (typeof o.blockId !== "string") throw new BadRequest("blockId is required");
+        versionInput(o);
         return o as never;
       },
     }),
@@ -1720,10 +2282,175 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
     }),
 
     // ---- 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: { pageId: string; expiresIn?: number }) => {
+      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<PreviewToken>({ 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): { pageId: string; expiresIn?: number } => {
+        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 as never;
+      },
+    }),
+
+    /** 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: { pageId: string }) => {
+      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): { pageId: string } => {
+        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: { pageId: string }) => {
+      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 as const, 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: { limit?: number }) => {
+      // 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) as JsonValue) : m.file }));
+      return { pages, media };
+    }, { ...viewer, input: (raw): { limit?: number } => {
+      const o = asObj(raw);
+      if (o.limit !== undefined && typeof o.limit !== "number") throw new BadRequest("limit must be a number");
+      return o as never;
+    } }),
+
+    restorePage: mutation(async (ctx, input: { pageId: string }) => {
+      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 as const, 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: { pageId: string }) => {
+      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 as const };
+    }, { ...reviewer, ...pageIdInput }),
+
     getPage: query(async (ctx, input: { slug: string; locale?: string; preview?: boolean }) => {
       const db = cdb(ctx);
       // Preview is an editor capability — gate it before the lookup so a non-editor gets a
@@ -1734,7 +2461,11 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
       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
@@ -1753,6 +2484,11 @@ export function createCmsHandlers(opts: CmsHandlerOpts = {}) {
           // those keys, but AssembledPage now types them as present — backfill from the live
           // 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 as string | null) ?? null;
           return snap;
         }
@@ -1790,11 +2526,31 @@ export interface CmsPolicyOpts {
  * `editor` grants full CRUD across every cms_ table. */
 export function cmsPolicies(opts: CmsPolicyOpts = {}): { public: Policy[]; editor: Policy[] } {
   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"] as const;
+  // 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: Record<string, true> = { cms_pages: true, cms_media: true };
   const editorPolicies: Policy[] = [];
   for (const table of tables) {
     for (const action of ["read", "create", "update", "delete"] as const) {
-      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 {
@@ -1804,14 +2560,18 @@ export function cmsPolicies(opts: CmsPolicyOpts = {}): { public: Policy[]; edito
       // 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,
   };
@@ -1827,8 +2587,9 @@ export function cmsPolicies(opts: CmsPolicyOpts = {}): { public: Policy[]; edito
 // list + form UI, without being bent into a cms_pages row.
 //
 // Column-mapped: each scalar FieldDefinition.name is a real column on the entity; a
-// repeater/group field maps to a t.json() column (the object↔JSON codec at the Db
-// chokepoint stores it transparently). The generic handlers dispatch through a registry
+// repeater/group/richtext field maps to a t.json() column (the object↔JSON codec at the
+// Db chokepoint stores it transparently). `richtext` belongs with the latter group — its
+// value is a document tree, and a TEXT column would bind the object raw and be rejected. The generic handlers dispatch through a registry
 // keyed by `slug`, so `collection`/`entity` can never be spoofed to reach an arbitrary
 // table, and writes are whitelisted to declared fields — the client can't set columns the
 // collection didn't declare (e.g. a `roles` or `passwordHash` column on the entity).
@@ -1861,6 +2622,11 @@ export interface CollectionDef {
   readonly idField?: string;
   /** Default list ordering; defaults to `{ column: "createdAt", dir: "desc" }`. */
   readonly orderBy?: { column: string; dir?: "asc" | "desc" };
+  /** Workflow features this collection opts into — see {@link CollectionFeature}. Each is
+   * backed by MANAGED COLUMNS on `entity` that the CMS writes and `fields` may not declare.
+   * Validated against your schema at `createCollectionHandlers` time (which is why that call
+   * needs `{ schema }` once this is set). Absent = a plain CRUD collection, as before. */
+  readonly supports?: readonly CollectionFeature[];
 }
 
 /** Declare a collection. Spread the results into `createCollectionHandlers` +
@@ -1894,6 +2660,9 @@ export interface CollectionMeta {
   titleField: string;
   idField: string;
   orderBy?: { column: string; dir?: "asc" | "desc" };
+  /** Workflow features enabled — the editor uses this to decide which affordances to show
+   * (a Publish button, a schedule picker, a revisions tab). Empty = plain CRUD. */
+  supports: readonly CollectionFeature[];
 }
 
 /** The public view of a collection def (defaults filled). */
@@ -1909,21 +2678,356 @@ function collectionMeta(c: CollectionDef): CollectionMeta {
     titleField,
     idField: c.idField ?? "id",
     orderBy: c.orderBy,
+    supports: c.supports ?? [],
   };
 }
 
+
+// --- collection workflow features (`supports`) -------------------------------
+//
+// A collection may opt into page-style workflow with `supports: ["drafts", ...]`. Each
+// feature is backed by MANAGED COLUMNS on the collection's OWN entity: the app declares the
+// columns, the CMS owns their values.
+//
+// That ownership is the whole difference from the `publish` FIELD type this replaces. A
+// `publish` field is an ordinary entry in `fields`, and `fields` is the write whitelist —
+// so "is this row live?" was a value the client sent in the `values` bag, and the access
+// boundary was whatever the client last wrote. A managed column is never in the whitelist
+// (declaring one as a field is a boot error, see `validateCollections`), so only
+// `collectionPublish` / `collectionSchedule` / the scheduled tasks can move a row live.
+//
+// TIMESTAMP FORMAT. Managed timestamps are minted as ISO-8601 UTC with a `Z`
+// (`2026-08-20T12:00:00.000Z`), in exactly one place (`isoStamp`). That is the format
+// `$now()` produces, and the published-read scope compares against it LEXICOGRAPHICALLY.
+// It is deliberately NOT `nowStamp()` (`expr.now()`'s "YYYY-MM-DD HH:MM:SS"), which sorts
+// against the ISO form as if hours apart. Minting in one place is what closes the trap
+// documented on the `publish` field: there, `publish` and `datetime` wrote different
+// formats into the same TEXT column and both passed validation.
+
+/** A workflow feature a collection can opt into.
+ *
+ * - `drafts` — a managed `status` column (`draft` | `published`) plus `collectionPublish` /
+ *   `collectionUnpublish`. Pair with `collectionPublicPolicies` so anonymous reads see
+ *   published rows only.
+ *
+ *   This gates VISIBILITY, not content. A collection is column-mapped — the public reads the
+ *   entity's own columns — so there is nowhere to stage an unpublished VERSION of a live
+ *   row: an edit (or a revision restore) on a published row is live immediately. That is the
+ *   one place collections do not reach page parity, where `getPage` serves a baked revision
+ *   snapshot. Unpublish first if an edit needs review.
+ * - `scheduling` — managed `publishedAt` / `scheduledAt` / `unpublishAt`, `collectionSchedule`,
+ *   and the deferred tasks from `createCollectionTasks`. Needs `drafts`.
+ * - `revisions` — a snapshot of the row's prior state on every write, in
+ *   `cms_collection_revisions`, with `collectionListRevisions` / `collectionRestoreRevision`.
+ * - `preview` — signed, single-row preview links (`signCollectionPreview`), redeemed at
+ *   `COLLECTION_PREVIEW_PATH` by the route `cmsRoutes()` serves. Needs `drafts`. It shows
+ *   the row's CURRENT state to whoever holds the link, which for a DRAFT is the unpublished
+ *   content and for a published row is what the public already sees (see `drafts` above:
+ *   there is no separate staged version to show). */
+export type CollectionFeature = "drafts" | "scheduling" | "revisions" | "preview";
+
+export const COLLECTION_FEATURES: readonly CollectionFeature[] = ["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: Readonly<Record<CollectionFeature, readonly string[]>> = {
+  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: Readonly<Partial<Record<CollectionFeature, CollectionFeature>>> = {
+  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 = (): string => 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: string, v: unknown): number => {
+  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: Readonly<Record<FieldDefinition["type"], readonly FieldType[]>> = {
+  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: readonly CollectionDef[], schema?: SchemaDef): void {
+  const seen = new Set<string>();
+  const byEntity = new Map<string, string>();
+  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<CollectionFeature>(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 as Record<string, FieldDef>;
+    // 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}'`,
+        );
+      }
+    }
+  }
+}
+
+/** A signed grant to preview ONE collection row. Mirrors {@link PreviewToken}. */
+export interface CollectionPreviewToken {
+  /** tenant */ t: string;
+  /** collection slug */ c: string;
+  /** row id — the grant is scoped to this ONE row, never "all drafts" */ r: string;
+  /** expiry (epoch seconds) */ exp: number;
+}
+
+/** 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";
+
+/** Options for `createCollectionHandlers`. */
+export interface CollectionHandlerOpts extends CmsHandlerOpts {
+  /** Your app's schema (the object you pass to `defineSchema`). REQUIRED: the whole registry
+   * is checked against it at boot by `validateCollections` — managed columns, declared
+   * field ↔ column types, the idField/PK pairing, `orderBy`, the partition — so a
+   * misconfiguration is a startup error naming the collection and the column rather than a
+   * 500 (or a silent wrong answer) on the first call. */
+  schema?: SchemaDef;
+}
+
 /** 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`
  * (a fast 403 before the body) AND the row ACL (they go through `ctx.db`, so
  * `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: readonly CollectionDef[], opts: CmsHandlerOpts = {}) {
+export function createCollectionHandlers(collections: readonly CollectionDef[], opts: CollectionHandlerOpts = {}) {
+  // 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] as const));
   const metas = collections.map(collectionMeta);
   const def = (slug: unknown): CollectionDef => {
@@ -1931,16 +3035,166 @@ export function createCollectionHandlers(collections: readonly CollectionDef[],
     if (!c) 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: unknown, readable: ReadonlySet<string>): Record<string, unknown> => {
+    const obj = snapshot && typeof snapshot === "object" && !Array.isArray(snapshot) ? (snapshot as Record<string, unknown>) : {};
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(obj)) if (readable.has(k)) out[k] = v;
+    return out;
+  };
   const idOf = (c: CollectionDef): string => c.idField ?? "id";
+  const has = (c: CollectionDef, f: CollectionFeature): boolean => (c.supports ?? []).includes(f);
+  const columnsOf = (c: CollectionDef): Record<string, FieldDef> => ((opts.schema?.[c.entity]?.fields ?? {}) as Record<string, FieldDef>);
+  /** 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: CollectionDef): { column: string; dir: "asc" | "desc" } => {
+    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)] as const));
+  /** 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: CollectionDef, f: CollectionFeature): void => {
+    if (!has(c, f)) throw new BadRequest(`collection '${c.slug}' does not support '${f}' (add it to \`supports\`)`);
+  };
+  const loadRow = async (db: CmsDb, c: CollectionDef, id: string): Promise<Record<string, unknown>> => {
+    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: CmsDb, c: CollectionDef, rowId: string, projected: Record<string, unknown>): Promise<Record<string, unknown>> => {
+    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)) as Array<Record<string, unknown>>;
+    const raw = rows[0];
+    if (!raw) {
+      const fallback: Record<string, unknown> = {};
+      for (const f of c.fields) if (f.name in projected) fallback[f.name] = projected[f.name];
+      return fallback;
+    }
+    const values: Record<string, unknown> = {};
+    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) as unknown;
+        } 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: CmsDb, c: CollectionDef, row: Record<string, unknown>, ctx: HandlerContext, note: string): Promise<void> => {
+    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,
+    )) as Array<{ next?: number }>;
+    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: unknown): { collection: string; id: string } => {
+    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: unknown): string => {
+    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: unknown): { collection: string; values: Record<string, unknown> } => {
+    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 as Record<string, unknown> };
+  };
+  const rowValuesInput = (raw: unknown): { collection: string; id: string; values: Record<string, unknown> } => ({
+    ...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: unknown): { collection: string; limit?: number; offset?: number } => {
+    const o = asObj(raw);
+    const num = (name: string, v: unknown): number | undefined => {
+      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: CollectionDef, values: unknown, requireRequired: boolean): Record<string, unknown> => {
+  const toColumns = (c: CollectionDef, values: unknown, requireRequired: boolean, legacyBaseline?: FieldValues): Record<string, unknown> => {
     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: Record<string, unknown> = {};
-    for (const f of c.fields) if (f.name in sanitized) out[f.name] = sanitized[f.name];
+    for (const f of c.fields) if (f.name in normalized) out[f.name] = normalized[f.name];
     return out;
   };
   const idInput = (raw: unknown): string => {
@@ -1956,35 +3210,371 @@ export function createCollectionHandlers(collections: readonly CollectionDef[],
 
     collectionList: query((ctx, input: { collection: string; limit?: number; offset?: number }) => {
       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: { collection: string; id: string }) => {
       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: { collection: string; values: Record<string, unknown> }) => {
       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: { collection: string; id: string; values: Record<string, unknown> }) => {
       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: FieldValues | undefined;
+      try {
+        current = (await db.find({ from: c.entity, where: { [idOf(c)]: input.id }, limit: 1 }))[0] as FieldValues | undefined;
+      } 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 as Record<string, unknown>, 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: { collection: string; id: string }) => {
       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 as const };
-    }, { ...editor, input: (raw) => ({ collection: asObj(raw).collection as string, 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: { collection: string; id: string }) => {
+      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: Record<string, unknown> = { 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: { collection: string; id: string }) => {
+      const c = def(input.collection);
+      needs(c, "drafts");
+      const db = cdb(ctx);
+      await loadRow(db, c, input.id);
+      const patch: Record<string, unknown> = { 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: { collection: string; id: string; publishAt: number; unpublishAt?: number | null }) => {
+      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: Record<string, unknown> = { 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 as const, scheduledAt: publishToken, ...(hasUnpublish ? { unpublishAt: unpublishToken } : {}) };
+    }, {
+      ...editor,
+      input: (raw): { collection: string; id: string; publishAt: number; unpublishAt?: number | null } => {
+        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: { collection: string; id: string; limit?: number }) => {
+      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): { collection: string; id: string; limit?: number } => {
+        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 as number), 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: { collection: string; id: string; revisionId: string }) => {
+      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 as FieldValues);
+      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): { collection: string; id: string; revisionId: string } => {
+        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: { collection: string; id: string; expiresIn?: number }) => {
+      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<CollectionPreviewToken>({ 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): { collection: string; id: string; expiresIn?: number } => {
+        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 as number | undefined };
+      },
+    }),
+
+    /** 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: { collection: string; id: string }) => {
+      const c = def(input.collection);
+      needs(c, "preview");
+      const row = await loadRow(cdb(ctx), c, input.id);
+      const values: Record<string, unknown> = { [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 }),
   };
 }
 
@@ -2004,9 +3594,184 @@ export function collectionPolicies(collections: readonly CollectionDef[], 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"] as const) {
+      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: readonly CollectionDef[], opts: CmsPolicyOpts = {}): Policy[] {
+  const p = opts.prefix ?? "cms";
+  const out: Policy[] = [];
+  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: readonly CollectionDef[]) {
+  const bySlug = new Map(collections.map((c) => [c.slug, c] as const));
+  const run = async (
+    ctx: HandlerContext,
+    payload: unknown,
+    tokenColumn: "scheduledAt" | "unpublishAt",
+    buildPatch: (row: Record<string, unknown>, now: string) => Record<string, unknown>,
+  ): Promise<void> => {
+    const { collection, id, token } = asObj(payload) as { collection?: string; id?: string; token?: string };
+    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] as string) : "";
+    if (!token || !stored || stored !== token) return;
+    await db.update(c.entity, id, buildPatch(row, isoStamp()));
+  };
+  return {
+    [TASK_COLLECTION_PUBLISH]: (ctx: HandlerContext, payload: unknown) =>
+      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: HandlerContext, payload: unknown) =>
+      // 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 }`.
@@ -2089,19 +3854,55 @@ export function robotsTxt(opts: { origin: string; disallow?: string[] }): string
 
 // Minimal shape of a pramen public route (see @pramen/server/worker app.routes).
 interface RouteCtx {
-  callPrivileged: (opts: { name: string; input?: unknown; tenant?: string; roles?: string[] }) => Promise<Response>;
+  callPrivileged: (opts: { name: string; input?: JsonValue; tenant?: string; roles?: string[] }) => Promise<Response>;
 }
 interface CmsRoute {
   method: string;
   path: string;
-  handler: (request: Request, env: Readonly<Record<string, unknown>>, ctx: RouteCtx) => Promise<Response>;
+  handler: (request: Request, env: EnvBag, ctx: RouteCtx) => Promise<Response>;
 }
 
-/** Turnkey public routes for `GET /sitemap.xml` and `GET /robots.txt`. Spread into
+const previewJson = (status: number, code: string, message: string): Response =>
+  // `{ 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"): Response =>
+  previewJson(status, status === 404 ? "not_found" : "forbidden", message);
+const preview503 = (): Response =>
+  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: { origin?: string; tenant?: string; pageUrl?: SitemapOpts["pageUrl"]; disallow?: string[] } = {}): CmsRoute[] {
+export function cmsRoutes(
+  opts: {
+    origin?: string;
+    tenant?: string;
+    pageUrl?: SitemapOpts["pageUrl"];
+    disallow?: string[];
+    /** The SAME options you passed to `createCmsHandlers`. The route derives its identity
+     * from them with `viewerRolesOf`, so the two cannot drift. (`viewerRoles` overrides it
+     * outright if you need to.) */
+    handlers?: CmsHandlerOpts;
+    /** The SAME options you passed to `createCollectionHandlers`, if they differ from
+     * `handlers`. The COLLECTION preview route has its own gate — `getCollectionPreview` is
+     * built by `createCollectionHandlers`, so an app that passes different `editorRoles` /
+     * `reviewerRoles` to the two factories would have the route present the page half's
+     * roles to a handler gated on the collection half's, and every collection preview link
+     * would 404 uniformly (the response is deliberately indistinguishable from "not
+     * found"). Defaults to `handlers`, which is right whenever both got the same options. */
+    collectionHandlers?: CmsHandlerOpts;
+    /** Explicit override for the roles the preview routes present to the DO. */
+    viewerRoles?: readonly string[];
+  } = {},
+): CmsRoute[] {
   const tenant = opts.tenant ?? "main";
+  const previewRoles = opts.viewerRoles ?? viewerRolesOf(opts.handlers);
+  const collectionPreviewRoles = opts.viewerRoles ?? viewerRolesOf(opts.collectionHandlers ?? opts.handlers);
   return [
     {
       method: "GET",
@@ -2114,6 +3915,85 @@ export function cmsRoutes(opts: { origin?: string; tenant?: string; pageUrl?: Si
         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<PreviewToken>(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(() => ({}))) as { ok?: boolean; result?: JsonValue; error?: string; code?: string };
+        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<CollectionPreviewToken>(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(() => ({}))) as { ok?: boolean; result?: JsonValue; error?: string; code?: string };
+        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",