@pramen/cms 0.0.48 → 0.0.50

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import type { HandlerContext, Policy, FileRef, BootstrapFn } from "@pramen/server";
+import type { HandlerContext, Policy, FileRef, BootstrapFn, JsonValue, SchemaDef } from "@pramen/server";
+import type { EnvBag } from "@pramen/server";
 /** A field in a block type's (or content type's) field schema. Recursive: a `repeater`
  * or `group` nests `fields`. Mirrors WollyCMS's FieldDefinition. */
 export interface FieldDefinition {
@@ -69,13 +70,37 @@ export interface RegionDefinition {
 export interface DefaultBlockDefinition {
     region: string;
     blockTypeSlug: string;
-    fields?: Record<string, unknown>;
+    fields?: FieldValues;
 }
-/** A rich-text value — a serialized editor document (or a plain string). */
-export type RichText = string | {
+/**
+ * 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?: unknown[];
-};
+    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). */
 export type FieldTsType<D extends FieldDefinition> = D["type"] extends "text" | "textarea" | "url" | "select" | "date" | "datetime" | "publish" | "slug" ? string : D["type"] extends "richtext" ? RichText : D["type"] extends "number" ? number : D["type"] extends "boolean" ? boolean : D["type"] extends "media" ? ResolvedMedia | null : D["type"] extends "group" ? InferBlockFields<NonNullable<D["fields"]>> : D["type"] extends "repeater" ? InferBlockFields<NonNullable<D["fields"]>>[] : unknown;
@@ -266,6 +291,11 @@ export declare const cmsSchema: {
         } & {
             readonly default: false;
         };
+        version: {
+            readonly type: "integer";
+        } & {
+            readonly default: 1;
+        };
         createdAt: {
             readonly type: "text";
         } & {
@@ -340,6 +370,11 @@ export declare const cmsSchema: {
         currentRevisionId: {
             readonly type: "uuid";
         };
+        deletedAt: {
+            readonly type: "text";
+        } & {
+            readonly index: true;
+        };
         metaTitle: {
             readonly type: "text";
         };
@@ -364,6 +399,11 @@ export declare const cmsSchema: {
         structuredData: {
             readonly type: "json";
         };
+        version: {
+            readonly type: "integer";
+        } & {
+            readonly default: 1;
+        };
         createdAt: {
             readonly type: "text";
         } & {
@@ -517,6 +557,47 @@ export declare const cmsSchema: {
             readonly defaultExpr: string;
         };
     }, Record<string, never>>;
+    cms_collection_revisions: import("@pramen/server").EntityDef<{
+        id: {
+            readonly type: "uuid";
+        } & {
+            readonly generated: true;
+        } & {
+            readonly primaryKey: true;
+            readonly notNull: true;
+        };
+        collection: {
+            readonly type: "text";
+        } & {
+            readonly notNull: true;
+        } & {
+            readonly index: true;
+        };
+        rowId: {
+            readonly type: "text";
+        } & {
+            readonly notNull: true;
+        } & {
+            readonly index: true;
+        };
+        revision: {
+            readonly type: "integer";
+        } & {
+            readonly notNull: true;
+        };
+        snapshot: {
+            readonly type: "json";
+        };
+        note: {
+            readonly type: "text";
+        };
+        actor: {
+            readonly type: "text";
+        };
+        createdAt: {
+            readonly type: "text";
+        };
+    }, Record<string, never>>;
     cms_media: import("@pramen/server").EntityDef<{
         id: {
             readonly type: "uuid";
@@ -532,6 +613,11 @@ export declare const cmsSchema: {
         alt: {
             readonly type: "text";
         };
+        deletedAt: {
+            readonly type: "text";
+        } & {
+            readonly index: true;
+        };
         createdAt: {
             readonly type: "text";
         } & {
@@ -544,19 +630,60 @@ 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;
 }
 export declare function validateFields(schema: FieldDefinition[] | undefined | null, values: unknown, path?: string, opts?: ValidateOpts): void;
-/** 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 declare function sanitizeFields(schema: FieldDefinition[] | undefined | null, values: Record<string, unknown>): Record<string, unknown>;
+/** 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 declare const MAX_HEADING_LEVEL = 3;
+export declare const DEFAULT_RICH_TEXT_SCHEMA: RichTextSchema;
+export { isSafeHref, normalizeHref } from "./href";
+/** 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 declare const MAX_RICH_TEXT_DEPTH = 100;
+/** 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 declare function normalizeRichText(value: unknown, schema?: RichTextSchema): RichTextDoc;
+/** Flatten a rich-text document to plain text — for excerpts, meta descriptions, and search
+ * indexing, which want the words without the structure. */
+export declare function richTextToPlainText(value: RichTextDoc | null | undefined): string;
+/** 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 declare function normalizeFields(schema: FieldDefinition[] | undefined | null, values: FieldValues, richTextSchema?: RichTextSchema): FieldValues;
 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;
 }
 export interface PageTranslation {
@@ -586,13 +713,26 @@ 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;
+}
+/** 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()`
@@ -618,6 +758,33 @@ export declare function imageUrl(key: string, opts?: {
     quality?: number;
     format?: "auto" | "webp" | "avif";
 }): string;
+/** 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 declare const PREVIEW_SECRET_NAMES: readonly ["PREVIEW_SECRET", "FILES_SECRET", "AUTH_SECRET"];
+/** Resolve the preview signing secret, or `undefined` when nothing usable is configured. */
+export declare function previewSecret(env: EnvBag): string | undefined;
+/** 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 declare function viewerRolesOf(opts?: CmsHandlerOpts): string[];
+/** The viewer roles for the DEFAULT handler config. */
+export declare const DEFAULT_VIEWER_ROLES: string[];
+/** Where a preview link is redeemed. Spread `cmsRoutes()` into `app.routes` to serve it. */
+export declare 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 declare const DEFAULT_PREVIEW_TTL_SECONDS = 3600;
 export interface CmsHandlerOpts {
     /** Roles permitted to call the editor mutations (also enforced by the ACL). Default
      * `["editor", "admin"]`. */
@@ -629,6 +796,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
  * gated both by `auth` (fast 403 before the body) and by the row ACL (cmsPolicies). */
@@ -699,13 +872,30 @@ export declare function createCmsHandlers(opts?: CmsHandlerOpts): {
         id: string;
         alt: string | null;
     }, Record<string, unknown>>;
-    /** 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: import("@pramen/server").Handler<{
         id: string;
     }, {
         ok: boolean;
     }>;
+    restoreMedia: import("@pramen/server").Handler<{
+        id: string;
+    }, {
+        ok: true;
+    }>;
+    /** Permanently remove trashed media — the row AND the R2 object. Reviewer-gated and
+     * irreversible; the blob is gone. */
+    purgeMedia: import("@pramen/server").Handler<{
+        id: string;
+    }, {
+        ok: true;
+    }>;
     listContentTypes: import("@pramen/server").Handler<unknown, Record<string, unknown>[]>;
     getContentType: import("@pramen/server").Handler<{
         id: string;
@@ -731,13 +921,14 @@ export declare 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. */
+     * + normalized against the content type's fieldsSchema, exactly like createPage. */
     updatePage: import("@pramen/server").Handler<{
         pageId: string;
         title?: string;
         slug?: string;
         locale?: string;
-        fields?: Record<string, unknown>;
+        fields?: FieldValues;
+        expectedVersion?: number;
     }, {
         ok: boolean;
         page: Record<string, unknown>;
@@ -748,7 +939,7 @@ export declare function createCmsHandlers(opts?: CmsHandlerOpts): {
         title: string;
         slug: string;
         locale?: string;
-        fields?: Record<string, unknown>;
+        fields?: FieldValues;
     }, Record<string, unknown>>;
     /** Create a translation of an existing page: a new page in `locale` sharing the
      * source's translationGroupId (and content type). Content starts empty — the editor
@@ -778,7 +969,7 @@ export declare function createCmsHandlers(opts?: CmsHandlerOpts): {
         pageId: string;
         blockTypeSlug: string;
         region: string;
-        fields?: Record<string, unknown>;
+        fields?: FieldValues;
         title?: string;
         position?: number;
         isReusable?: boolean;
@@ -797,7 +988,7 @@ export declare function createCmsHandlers(opts?: CmsHandlerOpts): {
         blockId: string;
         region: string;
         position?: number;
-        overrides?: Record<string, unknown>;
+        overrides?: FieldValues;
     }, Record<string, unknown>>;
     /** Fetch a block's RAW content (media fields as ids, not resolved) — for editing. */
     getBlock: import("@pramen/server").Handler<{
@@ -806,8 +997,9 @@ export declare function createCmsHandlers(opts?: CmsHandlerOpts): {
     /** Update a block's content (re-validated against its type's field schema). */
     updateBlock: import("@pramen/server").Handler<{
         blockId: string;
-        fields?: Record<string, unknown>;
+        fields?: FieldValues;
         title?: string;
+        expectedVersion?: number;
     }, Record<string, unknown> | undefined>;
     /** Reorder a region: `order` is the page_block ids in their new order. It must cover
      * EXACTLY the region's current placements (same set, no dups) — otherwise a partial or
@@ -891,10 +1083,61 @@ export declare function createCmsHandlers(opts?: CmsHandlerOpts): {
         ok: boolean;
         publishInMs: number;
     }>;
+    /** 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: import("@pramen/server").Handler<{
+        pageId: string;
+        expiresIn?: number;
+    }, {
+        url: string;
+        token: string;
+        expiresAt: number;
+    }>;
+    /** 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: import("@pramen/server").Handler<{
+        pageId: string;
+    }, AssembledPage>;
     /** 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. */
+    deletePage: import("@pramen/server").Handler<{
+        pageId: string;
+    }, {
+        ok: true;
+        deletedAt: string;
+    }>;
+    /** 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: import("@pramen/server").Handler<{
+        limit?: number;
+    }, {
+        pages: Record<string, unknown>[];
+        media: {
+            file: unknown;
+        }[];
+    }>;
+    restorePage: import("@pramen/server").Handler<{
+        pageId: string;
+    }, {
+        ok: true;
+        scheduleCleared: boolean;
+    }>;
+    /** Permanently remove a trashed page and everything hanging off it. Reviewer-gated:
+     * this is the only irreversible operation in the CMS. */
+    purgePage: import("@pramen/server").Handler<{
+        pageId: string;
+    }, {
+        ok: true;
+    }>;
     getPage: import("@pramen/server").Handler<{
         slug: string;
         locale?: string;
@@ -969,13 +1212,30 @@ export declare const cmsHandlers: {
         id: string;
         alt: string | null;
     }, Record<string, unknown>>;
-    /** 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: import("@pramen/server").Handler<{
         id: string;
     }, {
         ok: boolean;
     }>;
+    restoreMedia: import("@pramen/server").Handler<{
+        id: string;
+    }, {
+        ok: true;
+    }>;
+    /** Permanently remove trashed media — the row AND the R2 object. Reviewer-gated and
+     * irreversible; the blob is gone. */
+    purgeMedia: import("@pramen/server").Handler<{
+        id: string;
+    }, {
+        ok: true;
+    }>;
     listContentTypes: import("@pramen/server").Handler<unknown, Record<string, unknown>[]>;
     getContentType: import("@pramen/server").Handler<{
         id: string;
@@ -1001,13 +1261,14 @@ export declare const cmsHandlers: {
      * Blocks are edited via addBlock/updateBlock; SEO via updatePageSeo; this covers the
      * page record itself, which was previously only settable at createPage. A slug/locale
      * change re-checks (slug, locale) uniqueness (excluding this page); `fields` is validated
-     * + sanitized against the content type's fieldsSchema, exactly like createPage. */
+     * + normalized against the content type's fieldsSchema, exactly like createPage. */
     updatePage: import("@pramen/server").Handler<{
         pageId: string;
         title?: string;
         slug?: string;
         locale?: string;
-        fields?: Record<string, unknown>;
+        fields?: FieldValues;
+        expectedVersion?: number;
     }, {
         ok: boolean;
         page: Record<string, unknown>;
@@ -1018,7 +1279,7 @@ export declare const cmsHandlers: {
         title: string;
         slug: string;
         locale?: string;
-        fields?: Record<string, unknown>;
+        fields?: FieldValues;
     }, Record<string, unknown>>;
     /** Create a translation of an existing page: a new page in `locale` sharing the
      * source's translationGroupId (and content type). Content starts empty — the editor
@@ -1048,7 +1309,7 @@ export declare const cmsHandlers: {
         pageId: string;
         blockTypeSlug: string;
         region: string;
-        fields?: Record<string, unknown>;
+        fields?: FieldValues;
         title?: string;
         position?: number;
         isReusable?: boolean;
@@ -1067,7 +1328,7 @@ export declare const cmsHandlers: {
         blockId: string;
         region: string;
         position?: number;
-        overrides?: Record<string, unknown>;
+        overrides?: FieldValues;
     }, Record<string, unknown>>;
     /** Fetch a block's RAW content (media fields as ids, not resolved) — for editing. */
     getBlock: import("@pramen/server").Handler<{
@@ -1076,8 +1337,9 @@ export declare const cmsHandlers: {
     /** Update a block's content (re-validated against its type's field schema). */
     updateBlock: import("@pramen/server").Handler<{
         blockId: string;
-        fields?: Record<string, unknown>;
+        fields?: FieldValues;
         title?: string;
+        expectedVersion?: number;
     }, Record<string, unknown> | undefined>;
     /** Reorder a region: `order` is the page_block ids in their new order. It must cover
      * EXACTLY the region's current placements (same set, no dups) — otherwise a partial or
@@ -1161,10 +1423,61 @@ export declare const cmsHandlers: {
         ok: boolean;
         publishInMs: number;
     }>;
+    /** 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: import("@pramen/server").Handler<{
+        pageId: string;
+        expiresIn?: number;
+    }, {
+        url: string;
+        token: string;
+        expiresAt: number;
+    }>;
+    /** 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: import("@pramen/server").Handler<{
+        pageId: string;
+    }, AssembledPage>;
     /** 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. */
+    deletePage: import("@pramen/server").Handler<{
+        pageId: string;
+    }, {
+        ok: true;
+        deletedAt: string;
+    }>;
+    /** 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: import("@pramen/server").Handler<{
+        limit?: number;
+    }, {
+        pages: Record<string, unknown>[];
+        media: {
+            file: unknown;
+        }[];
+    }>;
+    restorePage: import("@pramen/server").Handler<{
+        pageId: string;
+    }, {
+        ok: true;
+        scheduleCleared: boolean;
+    }>;
+    /** Permanently remove a trashed page and everything hanging off it. Reviewer-gated:
+     * this is the only irreversible operation in the CMS. */
+    purgePage: import("@pramen/server").Handler<{
+        pageId: string;
+    }, {
+        ok: true;
+    }>;
     getPage: import("@pramen/server").Handler<{
         slug: string;
         locale?: string;
@@ -1219,6 +1532,11 @@ export interface CollectionDef {
         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` +
  * `collectionPolicies`:
@@ -1251,18 +1569,87 @@ export interface CollectionMeta {
         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[];
+}
+/** 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 declare const COLLECTION_FEATURES: readonly CollectionFeature[];
+/** 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 declare const COLLECTION_FEATURE_COLUMNS: Readonly<Record<CollectionFeature, readonly string[]>>;
+/** The shared revision table for collections (see `cmsSchema`). */
+export declare const COLLECTION_REVISIONS_TABLE = "cms_collection_revisions";
+/** The two `status` values a `drafts` collection uses. */
+export declare const COLLECTION_DRAFT = "draft";
+export declare const COLLECTION_PUBLISHED = "published";
+/** 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 declare function validateCollections(collections: readonly CollectionDef[], schema?: SchemaDef): void;
+/** 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 declare const COLLECTION_PREVIEW_PATH = "/cms/preview/collection";
+/** Outbox task kinds behind `collectionSchedule`. Register the handlers with
+ * `app.tasks = { ...cmsTasks, ...createCollectionTasks(collections) }`. */
+export declare const TASK_COLLECTION_PUBLISH = "cms:collection:publish";
+export declare 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 declare function createCollectionHandlers(collections: readonly CollectionDef[], opts?: CmsHandlerOpts): {
+export declare function createCollectionHandlers(collections: readonly CollectionDef[], opts?: CollectionHandlerOpts): {
     /** The registered collections (defaults filled) — editor discovery. Editor-gated so
      * the collection schemas aren't exposed to anonymous callers. */
     listCollections: import("@pramen/server").Handler<unknown, CollectionMeta[]>;
@@ -1290,6 +1677,81 @@ export declare function createCollectionHandlers(collections: readonly Collectio
     }, {
         ok: true;
     }>;
+    /** 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: import("@pramen/server").Handler<{
+        collection: string;
+        id: string;
+    }, Record<string, unknown>>;
+    /** 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: import("@pramen/server").Handler<{
+        collection: string;
+        id: string;
+    }, Record<string, unknown>>;
+    /** 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: import("@pramen/server").Handler<{
+        collection: string;
+        id: string;
+        publishAt: number;
+        unpublishAt?: number | null;
+    }, {
+        unpublishAt?: string | null | undefined;
+        ok: true;
+        scheduledAt: string;
+    }>;
+    /** A row's revision history, newest first. */
+    collectionListRevisions: import("@pramen/server").Handler<{
+        collection: string;
+        id: string;
+        limit?: number;
+    }, {
+        snapshot: Record<string, unknown>;
+    }[]>;
+    /** Restore a row to one of its revisions. The CURRENT state is snapshotted first, so a
+     * restore is itself undoable. */
+    collectionRestoreRevision: import("@pramen/server").Handler<{
+        collection: string;
+        id: string;
+        revisionId: string;
+    }, Record<string, unknown>>;
+    /** 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: import("@pramen/server").Handler<{
+        collection: string;
+        id: string;
+        expiresIn?: number;
+    }, {
+        url: string;
+        token: string;
+        expiresAt: number;
+    }>;
+    /** 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: import("@pramen/server").Handler<{
+        collection: string;
+        id: string;
+    }, {
+        collection: string;
+        id: string;
+        values: Record<string, unknown>;
+    }>;
 };
 /** ACL fragments granting the editor role full CRUD over each collection's entity. Spread
  * into your editor role next to `cmsPolicies().editor`:
@@ -1300,6 +1762,40 @@ export declare function createCollectionHandlers(collections: readonly Collectio
  * them. Your app may already declare its own policies over the entity (e.g. a public read
  * scope) — these only ADD the editor grant the CMS UI needs. */
 export declare function collectionPolicies(collections: readonly CollectionDef[], opts?: CmsPolicyOpts): Policy[];
+/** 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 declare function collectionPublicPolicies(collections: readonly CollectionDef[], opts?: CmsPolicyOpts): Policy[];
+/** 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 declare function createCollectionTasks(collections: readonly CollectionDef[]): {
+    "cms:collection:publish": (ctx: HandlerContext, payload: unknown) => Promise<void>;
+    "cms:collection:unpublish": (ctx: HandlerContext, payload: unknown) => Promise<void>;
+};
 /** Task handlers backing `schedulePage`. Register via `app.tasks = { ...cmsTasks }`.
  * They run with a privileged, system-scoped ctx off the write path (the outbox drain).
  *
@@ -1336,7 +1832,7 @@ export declare function robotsTxt(opts: {
 interface RouteCtx {
     callPrivileged: (opts: {
         name: string;
-        input?: unknown;
+        input?: JsonValue;
         tenant?: string;
         roles?: string[];
     }) => Promise<Response>;
@@ -1344,9 +1840,9 @@ interface RouteCtx {
 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
+/** 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 declare function cmsRoutes(opts?: {
@@ -1354,5 +1850,18 @@ export declare function cmsRoutes(opts?: {
     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[];
-export {};