@pramen/cms-editor 0.0.48 → 0.0.50

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pramen/cms-editor",
-  "version": "0.0.48",
-  "description": "Visual block/page editor for @pramen/cms — a standalone React SPA that talks to the CMS handlers over HTTP.",
+  "version": "0.0.50",
+  "description": "Visual block/page editor for @pramen/cms \u2014 a standalone React SPA that talks to the CMS handlers over HTTP.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -11,7 +11,10 @@
   "homepage": "https://github.com/netvarec/pramen#readme",
   "bugs": "https://github.com/netvarec/pramen/issues",
   "type": "module",
-  "files": ["dist", "src"],
+  "files": [
+    "dist",
+    "src"
+  ],
   "scripts": {
     "build": "bun run scripts/build.ts",
     "dev": "bun run scripts/build.ts --watch",
@@ -20,16 +23,17 @@
   },
   "dependencies": {
     "@buzola/router": "^0.0.12",
-    "@podoba/react": "^0.0.32",
-    "@podoba/tokens": "^0.0.32",
-    "@podoba/tailwind": "^0.0.32",
-    "@tiptap/react": "^3.27.4",
-    "@tiptap/pm": "^3.27.4",
-    "@tiptap/starter-kit": "^3.27.4",
-    "@tiptap/extension-placeholder": "^3.27.4",
+    "@podoba/react": "^0.0.34",
+    "@podoba/tailwind": "^0.0.34",
+    "@podoba/tokens": "^0.0.34",
+    "@tiptap/core": "^3.27.4",
     "@tiptap/extension-highlight": "^3.27.4",
-    "@tiptap/extension-task-list": "^3.27.4",
+    "@tiptap/extension-placeholder": "^3.27.4",
     "@tiptap/extension-task-item": "^3.27.4",
+    "@tiptap/extension-task-list": "^3.27.4",
+    "@tiptap/pm": "^3.27.4",
+    "@tiptap/react": "^3.27.4",
+    "@tiptap/starter-kit": "^3.27.4",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },

package/src/api.ts

@@ -2,6 +2,7 @@
 // same transport shape as @pramen/admin's api.ts. Config is persisted in localStorage.
 
 import type { AssembledPage, AuditEntry, BlockType, ContentType, Media, Page } from "./types";
+import type { RpcInput } from "./types";
 
 export interface Config {
   baseUrl: string;
@@ -72,20 +73,21 @@ export class Api {
   }
 
   /** Call a CMS RPC handler. Throws ApiError on a non-`ok` envelope. */
-  async call<T = unknown>(name: string, input?: unknown): Promise<T> {
+  async call<T = unknown>(name: string, input?: RpcInput): Promise<T> {
     // Expired token: hand off to sign-in instead of firing a request that will 403 into an
     // error banner. The returned promise never settles — navigation is already underway.
     if (this.onExpired && this.cfg.token && isTokenExpired(this.cfg.token)) {
       this.onExpired();
       return new Promise<T>(() => {});
     }
+    const headers = new Headers({
+      "content-type": "application/json",
+      "x-pramen-tenant": this.cfg.tenant || "main",
+    });
+    if (this.cfg.token) headers.set("authorization", `Bearer ${this.cfg.token}`);
     const res = await fetch(`${this.base()}/rpc/${name}`, {
       method: "POST",
-      headers: {
-        "content-type": "application/json",
-        "x-pramen-tenant": this.cfg.tenant || "main",
-        ...(this.cfg.token ? { authorization: `Bearer ${this.cfg.token}` } : {}),
-      },
+      headers,
       body: JSON.stringify(input ?? {}),
     });
     let body: { ok?: boolean; result?: unknown; error?: string; code?: string };
@@ -127,6 +129,12 @@ export class Api {
   getMedia = (id: string) => this.call<Media | null>("getMedia", { id });
   updateMedia = (id: string, alt: string | null) => this.call<Media>("updateMedia", { id, alt });
   deleteMedia = (id: string) => this.call<{ ok: true }>("deleteMedia", { id });
+  // Trash is not a UI nicety here: deleteMedia no longer removes the R2 object, so without
+  // a reachable purge a file can be "deleted" in the library and still be served on the
+  // live site — the case a takedown request actually needs.
+  listTrash = (limit = 50) => this.call<{ pages: Page[]; media: Media[] }>("listTrash", { limit });
+  restoreMedia = (id: string) => this.call<{ ok: true }>("restoreMedia", { id });
+  purgeMedia = (id: string) => this.call<{ ok: true }>("purgeMedia", { id });
 
   /** Full upload flow: sign → PUT the bytes → persist a `cms_media` row. Returns the row. */
   async uploadMedia(file: File): Promise<Media> {

package/src/app-context.tsx

@@ -6,7 +6,7 @@
 import { Button, Input } from "@podoba/react";
 import { createContext, use, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { Api, clearConfig, isTokenExpired, loadConfig, saveConfig, type Config } from "./api";
-import type { CollectionMeta } from "./types";
+import type { CollectionMeta, JsonValue } from "./types";
 
 declare global {
   interface Window {
@@ -42,7 +42,7 @@ function redirectToSignIn(): void {
 export interface Me {
   userId?: string;
   roles?: string[];
-  [k: string]: unknown;
+  [k: string]: JsonValue | undefined;
 }
 
 interface AppContextValue {

package/src/components.tsx

@@ -5,10 +5,11 @@
 import { Button, Heading, Input, ModalDialog, ModalOverlay, ModalSurface, Textarea } from "@podoba/react";
 import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
 import { Api, ApiError } from "./api";
-import { FieldForm, slugify } from "./fields";
+import { CONTROL, FieldForm, formatWhen, fromLocalInput, slugify, toLocalInput } from "./fields";
 import type { Config } from "./api";
 import type { Me } from "./app-context";
-import type { AssembledPage, AuditEntry, BlockType, CollectionMeta, ContentType, FieldDefinition, Media, Page, RegionDefinition, RenderedBlock } from "./types";
+import { isRichTextDoc, richTextToPlainText } from "./rich-text";
+import type { AssembledPage, AuditEntry, BlockType, CollectionMeta, ContentType, FieldDefinition, FieldValue, FieldValues, Media, Page, RegionDefinition, RenderedBlock } from "./types";
 
 export type InspectorTab = "settings" | "seo" | "workflow" | "i18n" | "audit";
 export const INSPECTOR_TABS: InspectorTab[] = ["settings", "seo", "workflow", "i18n", "audit"];
@@ -186,11 +187,16 @@ function CreatePage({ api, onClose, onCreated, onError }: { api: Api; onClose: (
 // collections, zero per-collection code. Rows are addressed by `def.idField` (the entity's
 // PK column, defaults "id"); the server resolves the real PK from the value.
 
-/** Render a list-cell value as a short string (objects/arrays are summarized, not dumped). */
+/** Render a list-cell value as a short string (objects/arrays are summarized, not dumped).
+ * A `richtext` column is a document tree, so flatten it to words rather than showing "—". */
 function cellText(v: unknown): string {
   if (v == null) return "";
   if (typeof v === "boolean") return v ? "yes" : "no";
   if (Array.isArray(v)) return v.length === 1 ? "1 item" : `${v.length} items`;
+  if (isRichTextDoc(v)) {
+    const text = richTextToPlainText(v).replace(/\s+/g, " ").trim();
+    return text.length > 80 ? text.slice(0, 80) + "…" : text;
+  }
   if (typeof v === "object") return "—";
   return String(v);
 }
@@ -201,7 +207,7 @@ function cellText(v: unknown): string {
 const COLLECTION_PAGE_SIZE = 50;
 
 export function CollectionList({ api, def, onOpen, onNew, onError }: { api: Api; def: CollectionMeta; onOpen: (id: string) => void; onNew: () => void; onError: (s: string) => void }) {
-  const [rows, setRows] = useState<Record<string, unknown>[]>([]);
+  const [rows, setRows] = useState<FieldValues[]>([]);
   const [offset, setOffset] = useState(0);
   const [hasMore, setHasMore] = useState(false);
   const [loading, setLoading] = useState(true);
@@ -210,7 +216,7 @@ export function CollectionList({ api, def, onOpen, onNew, onError }: { api: Api;
     (off: number) => {
       setLoading(true);
       return api
-        .call<Record<string, unknown>[]>("collectionList", { collection: def.slug, limit: COLLECTION_PAGE_SIZE, offset: off })
+        .call<FieldValues[]>("collectionList", { collection: def.slug, limit: COLLECTION_PAGE_SIZE, offset: off })
         .then((r) => {
           setRows((prev) => (off === 0 ? r : [...prev, ...r]));
           // A full page means there is probably more; a short one is definitely the end.
@@ -265,9 +271,188 @@ export function CollectionList({ api, def, onOpen, onNew, onError }: { api: Api;
   );
 }
 
+/** The workflow surface for a collection row — the UI half of the server's `supports`.
+ *
+ * Without this the feature is unreachable from the editor: `collectionCreate` always seeds
+ * `status: "draft"` and `collectionUpdate` strips `status` from the values bag (it is a
+ * MANAGED column, deliberately not in the write whitelist), so a row authored here could
+ * never be made public. Publishing has to be its own gated call, and this is where it is
+ * made. Every control is driven by `def.supports`, so a plain CRUD collection renders
+ * nothing at all.
+ *
+ * The row's managed columns come back on `collectionGet`/the write echoes, so the panel
+ * reads its state from the same `values` bag the form holds. */
+function CollectionWorkflow({
+  api,
+  def,
+  id,
+  values,
+  onChanged,
+  onError,
+}: {
+  api: Api;
+  def: CollectionMeta;
+  id: string;
+  values: FieldValues;
+  onChanged: (row: FieldValues) => void;
+  onError: (s: string) => void;
+}) {
+  const supports = def.supports ?? [];
+  const [busy, setBusy] = useState(false);
+  const [scheduling, setScheduling] = useState(false);
+  const [publishAt, setPublishAt] = useState("");
+  const [takedownAt, setTakedownAt] = useState("");
+  const [preview, setPreview] = useState<string | null>(null);
+  const [revisions, setRevisions] = useState<Array<{ id: string; revision: number; note: string | null; actor: string | null; createdAt: string }> | null>(null);
+
+  const status = typeof values.status === "string" ? values.status : "draft";
+  const published = status === "published";
+  const str = (k: string) => (typeof values[k] === "string" && values[k] !== "" ? (values[k] as string) : null);
+  const scheduledAt = str("scheduledAt");
+  const unpublishAt = str("unpublishAt");
+  const publishedAt = str("publishedAt");
+
+  if (supports.length === 0) return null;
+
+  const act = async (name: string, input: Record<string, unknown> = {}) => {
+    setBusy(true);
+    try {
+      const row = await api.call<FieldValues>(name, { collection: def.slug, id, ...input });
+      // The publish/unpublish handlers echo the persisted row; `collectionSchedule` returns
+      // `{ ok, scheduledAt, … }`, so re-read rather than merging a non-row shape in.
+      if (row && typeof row === "object" && def.idField in row) onChanged(row);
+      else {
+        const fresh = await api.call<FieldValues | null>("collectionGet", { collection: def.slug, id });
+        if (fresh) onChanged(fresh);
+      }
+      return true;
+    } catch (e) {
+      onError(errMsg(e));
+      return false;
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const saveSchedule = async () => {
+    const at = publishAt ? fromLocalInput(publishAt) : null;
+    if (!at) return onError("Pick a publication date and time first.");
+    const down = takedownAt ? fromLocalInput(takedownAt) : null;
+    if (takedownAt && !down) return onError("That takedown date is not a valid date and time.");
+    // `unpublishAt` is PATCH semantics server-side: omitted leaves an existing takedown
+    // standing, `null` cancels it. Send it explicitly whenever the scheduler is open, so
+    // what the editor sees in the two inputs is exactly what is stored.
+    const ok = await act("collectionSchedule", { publishAt: Date.parse(at), unpublishAt: down ? Date.parse(down) : null });
+    if (ok) setScheduling(false);
+  };
+
+  const openScheduler = () => {
+    setPublishAt(toLocalInput(scheduledAt ?? publishedAt ?? new Date().toISOString()));
+    setTakedownAt(unpublishAt ? toLocalInput(unpublishAt) : "");
+    setScheduling((v) => !v);
+  };
+
+  const mintPreview = async () => {
+    setBusy(true);
+    try {
+      const r = await api.call<{ url: string }>("signCollectionPreview", { collection: def.slug, id });
+      const url = api.resolve(r.url);
+      setPreview(url);
+      // Best-effort: the clipboard needs a secure context and a permission, and the link is
+      // rendered either way.
+      await navigator.clipboard?.writeText(url).catch(() => {});
+    } catch (e) {
+      onError(errMsg(e));
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const loadRevisions = async () => {
+    if (revisions) return setRevisions(null); // toggle closed
+    try {
+      setRevisions(await api.call<NonNullable<typeof revisions>>("collectionListRevisions", { collection: def.slug, id }));
+    } catch (e) {
+      onError(errMsg(e));
+    }
+  };
+
+  const restore = async (revisionId: string) => {
+    if (!confirm("Restore this version? The current content is snapshotted first, so this is itself undoable.")) return;
+    if (await act("collectionRestoreRevision", { revisionId })) setRevisions(null);
+  };
+
+  return (
+    <div className="flex flex-col gap-3 rounded-[14px] border border-border bg-surface-card px-[18px] py-4">
+      <div className="flex flex-wrap items-center gap-2">
+        <span className="text-fg-subtle">Status</span>
+        <Pill status={status}>{status}</Pill>
+        {publishedAt && published ? <span className="text-fg-subtle">since {formatWhen(publishedAt)}</span> : null}
+        {scheduledAt ? <span className="text-accent-strong">publishes {formatWhen(scheduledAt)}</span> : null}
+        {unpublishAt ? <span className="text-danger">comes down {formatWhen(unpublishAt)}</span> : null}
+      </div>
+      <div className="flex flex-wrap items-center gap-2">
+        {supports.includes("drafts") && !published ? (
+          <Button size="sm" isDisabled={busy} onPress={() => void act("collectionPublish")}>Publish now</Button>
+        ) : null}
+        {supports.includes("drafts") && published ? (
+          <Button variant="secondary" size="sm" isDisabled={busy} onPress={() => void act("collectionUnpublish")}>Unpublish</Button>
+        ) : null}
+        {supports.includes("scheduling") ? (
+          <Button variant="secondary" size="sm" isDisabled={busy} onPress={openScheduler}>{scheduledAt ? "Change schedule" : "Schedule…"}</Button>
+        ) : null}
+        {supports.includes("preview") ? (
+          <Button variant="ghost" size="sm" isDisabled={busy} onPress={() => void mintPreview()}>Preview link</Button>
+        ) : null}
+        {supports.includes("revisions") ? (
+          <Button variant="ghost" size="sm" isDisabled={busy} onPress={() => void loadRevisions()}>{revisions ? "Hide history" : "History"}</Button>
+        ) : null}
+      </div>
+      {scheduling ? (
+        <div className="flex flex-col gap-2 border-t border-border pt-3">
+          <label className="flex flex-col gap-1 text-sm">
+            <span className="font-medium text-fg">Publish at</span>
+            <input className={CONTROL} type="datetime-local" value={publishAt} onChange={(e) => setPublishAt(e.target.value)} />
+          </label>
+          <label className="flex flex-col gap-1 text-sm">
+            <span className="font-medium text-fg">Take down at (optional)</span>
+            <input className={CONTROL} type="datetime-local" value={takedownAt} onChange={(e) => setTakedownAt(e.target.value)} />
+          </label>
+          <p className="text-fg-subtle">
+            Scheduling does not take a live row down — it publishes at the first instant. A takedown must be after the publication time. Leave it empty to
+            cancel one.
+          </p>
+          <div className="flex gap-2">
+            <Button size="sm" isDisabled={busy} onPress={() => void saveSchedule()}>Save schedule</Button>
+            <Button variant="ghost" size="sm" onPress={() => setScheduling(false)}>Cancel</Button>
+          </div>
+        </div>
+      ) : null}
+      {preview ? (
+        <div className="border-t border-border pt-3 text-sm">
+          <span className="text-fg-subtle">Preview link (copied): </span>
+          <a className="break-all underline" href={preview} target="_blank" rel="noreferrer">{preview}</a>
+        </div>
+      ) : null}
+      {revisions ? (
+        <div className="flex flex-col gap-2 border-t border-border pt-3">
+          {revisions.map((r) => (
+            <div className={`${ROW} text-xs`} key={r.id}>
+              <span className="rounded-full bg-surface-muted px-2 py-0.5 font-mono text-xs text-fg-muted">#{r.revision}</span>
+              <span className="flex-1 truncate text-fg-subtle">{r.note ?? "edit"} · {r.actor ?? "system"} · {formatWhen(r.createdAt)}</span>
+              <Button variant="ghost" size="sm" isDisabled={busy} onPress={() => void restore(r.id)}>Restore</Button>
+            </div>
+          ))}
+          {revisions.length === 0 ? <p className="text-fg-subtle">No history yet.</p> : null}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
 export function CollectionEditor({ api, def, id, onSaved, onDeleted, onBack, onError }: { api: Api; def: CollectionMeta; id: string | null; onSaved: () => void; onDeleted: () => void; onBack: () => void; onError: (s: string) => void }) {
   const isNew = id === null;
-  const [values, setValues] = useState<Record<string, unknown>>({});
+  const [values, setValues] = useState<FieldValues>({});
   const [loading, setLoading] = useState(!isNew);
   const [missing, setMissing] = useState(false);
   const [busy, setBusy] = useState(false);
@@ -278,7 +463,7 @@ export function CollectionEditor({ api, def, id, onSaved, onDeleted, onBack, onE
     let live = true;
     setLoading(true);
     setMissing(false);
-    api.call<Record<string, unknown> | null>("collectionGet", { collection: def.slug, id })
+    api.call<FieldValues | null>("collectionGet", { collection: def.slug, id })
       .then((row) => { if (!live) return; if (row) setValues(row); else setMissing(true); })
       .catch((e) => onError(errMsg(e)))
       .finally(() => { if (live) setLoading(false); });
@@ -296,7 +481,7 @@ export function CollectionEditor({ api, def, id, onSaved, onDeleted, onBack, onE
       } else {
         // Editing: stay on the form. Reflect the persisted row the update echoes back (server
         // defaults / normalization applied) and flash a confirmation instead of navigating.
-        const updated = await api.call<Record<string, unknown>>("collectionUpdate", { collection: def.slug, id, values });
+        const updated = await api.call<FieldValues>("collectionUpdate", { collection: def.slug, id, values });
         if (updated) setValues(updated);
         setOk(true);
         setTimeout(() => setOk(false), 1200);
@@ -333,6 +518,12 @@ export function CollectionEditor({ api, def, id, onSaved, onDeleted, onBack, onE
       ) : (
         <div className="flex max-w-[720px] flex-col gap-4">
           {ok ? <Banner ok>saved</Banner> : null}
+          {/* Publishing is a separate, separately-gated call — `status` is a managed column
+              the ordinary save cannot touch — so the workflow controls live outside the
+              form. Only on an existing row: there is nothing to publish until it exists. */}
+          {!isNew && id ? (
+            <CollectionWorkflow api={api} def={def} id={id} values={values} onChanged={setValues} onError={onError} />
+          ) : null}
           <FieldForm schema={def.fields} value={values} onChange={setValues} api={api} />
           <div className="mt-2 flex items-center gap-2">
             <Button onPress={save} isDisabled={busy}>{busy ? "Saving…" : isNew ? "Create" : "Save"}</Button>
@@ -427,7 +618,7 @@ export function PageEditor({ api, page, blockTypes, tab, onTab, onBack, onChange
     });
     try {
       const { block, placement } = await api.call<{
-        block: { id: string; title?: string | null; fields?: Record<string, unknown> | null };
+        block: { id: string; title?: string | null; fields?: FieldValues | null };
         placement: { id: string; isShared?: boolean | number };
       }>("addBlock", { pageId: page.id, blockTypeSlug: slug, region, fields: {} });
       const rb: RenderedBlock = {
@@ -470,7 +661,7 @@ export function PageEditor({ api, page, blockTypes, tab, onTab, onBack, onChange
 
   // Patch a block's raw fields into local state after an inline save — keeps the collapsed
   // preview fresh without a full reload (which would remount every editor + lose caret/focus).
-  const patchBlockFields = useCallback((placementId: string, fields: Record<string, unknown>) => {
+  const patchBlockFields = useCallback((placementId: string, fields: FieldValues) => {
     setAssembled((prev) => {
       if (!prev) return prev;
       const next: Record<string, RenderedBlock[]> = {};
@@ -539,7 +730,7 @@ export function PageEditor({ api, page, blockTypes, tab, onTab, onBack, onChange
             not in the inspector. For a content type with no regions (a fixed layout, all
             of it page fields) this is the entire editor; the canvas is never empty. */}
         {pageSchema.length ? (
-          <PageFields api={api} page={page} schema={pageSchema} initialFields={(assembled?.page.fields as Record<string, unknown>) ?? {}} onDirtyChange={reportDirty} onError={setErr} />
+          <PageFields api={api} page={page} schema={pageSchema} initialFields={(assembled?.page.fields as FieldValues) ?? {}} onDirtyChange={reportDirty} onError={setErr} />
         ) : null}
         {regions.map((r) => {
           const blocks = assembled?.regions[r.name] ?? [];
@@ -611,7 +802,7 @@ function BlockCard({ api, block, blockType, isFirst, isLast, onMove, onRemove, o
   isLast: boolean;
   onMove: (dir: number) => void;
   onRemove: () => void;
-  onPatch: (placementId: string, fields: Record<string, unknown>) => void;
+  onPatch: (placementId: string, fields: FieldValues) => void;
   onDirtyChange: (placementId: string, dirty: boolean) => void;
   onError: (s: string) => void;
   dragging: boolean;
@@ -621,7 +812,7 @@ function BlockCard({ api, block, blockType, isFirst, isLast, onMove, onRemove, o
   onDropBlock: () => void;
   onDragEndBlock: () => void;
 }) {
-  const [fields, setFields] = useState<Record<string, unknown> | null>(null);
+  const [fields, setFields] = useState<FieldValues | null>(null);
   const [collapsed, setCollapsed] = useState(false);
   const [saveState, setSaveState] = useState<"idle" | "saving" | "saved">("idle");
   const saved = useRef<string>(""); // JSON of the last-persisted fields — the dirty baseline
@@ -629,13 +820,13 @@ function BlockCard({ api, block, blockType, isFirst, isLast, onMove, onRemove, o
   const blockId = block.block_id;
   const placementId = block.id;
 
-  // Load RAW fields (media as ids, richtext as HTML) so the value round-trips on save.
+  // Load RAW fields (media as ids, richtext as a document tree) so the value round-trips on save.
   // A pending optimistic block has no persisted row yet — start empty and skip the fetch
   // (its temp id would 404); when it reconciles to real ids the card remounts and fetches.
   useEffect(() => {
     if (block.pending) { setFields({}); saved.current = "{}"; return; }
     let alive = true;
-    api.call<{ fields?: Record<string, unknown> }>("getBlock", { blockId }).then((b) => {
+    api.call<{ fields?: FieldValues }>("getBlock", { blockId }).then((b) => {
       if (!alive) return;
       const f = b?.fields ?? {};
       setFields(f);
@@ -680,7 +871,7 @@ function BlockCard({ api, block, blockType, isFirst, isLast, onMove, onRemove, o
     return () => clearTimeout(t);
   }, [fields, block.pending]);
 
-  const change = (next: Record<string, unknown>) => setFields(next);
+  const change = (next: FieldValues) => setFields(next);
 
   // Report dirty state up (for the editor's leave/unload guard); clear it on unmount so a
   // removed block never leaves a stale "unsaved" flag behind.
@@ -891,8 +1082,8 @@ function PageMeta({ api, page, onSaved, onError }: { api: Api; page: Page; onSav
 }
 
 /** The page's own FIELDS — its content. Rendered in the canvas, at full width. */
-function PageFields({ api, page, schema, initialFields, onDirtyChange, onError }: { api: Api; page: Page; schema: FieldDefinition[]; initialFields: Record<string, unknown>; onDirtyChange: (id: string, dirty: boolean) => void; onError: (s: string) => void }) {
-  const [fields, setFields] = useState<Record<string, unknown>>(initialFields);
+function PageFields({ api, page, schema, initialFields, onDirtyChange, onError }: { api: Api; page: Page; schema: FieldDefinition[]; initialFields: FieldValues; onDirtyChange: (id: string, dirty: boolean) => void; onError: (s: string) => void }) {
+  const [fields, setFields] = useState<FieldValues>(initialFields);
   const [ok, setOk] = useState(false);
   const [busy, setBusy] = useState(false);
 
@@ -1095,6 +1286,10 @@ export function MediaLibrary({ api, onError }: { api: Api; onError: (s: string)
   const [hasMore, setHasMore] = useState(false);
   const [selected, setSelected] = useState<Media | null>(null);
   const [busy, setBusy] = useState(false);
+  // Trashed files. Deleting no longer removes the R2 object, so without this the bytes stay
+  // publicly fetchable with no way to reach purgeMedia — the case a takedown request needs.
+  const [trash, setTrash] = useState<Media[]>([]);
+  const [showTrash, setShowTrash] = useState(false);
 
   const load = useCallback(
     (off: number) => {
@@ -1109,7 +1304,30 @@ export function MediaLibrary({ api, onError }: { api: Api; onError: (s: string)
     },
     [api, onError],
   );
+  const loadTrash = useCallback(() => {
+    api.listTrash().then((r) => setTrash(r.media ?? [])).catch((e) => onError(errMsg(e)));
+  }, [api, onError]);
   useEffect(() => { load(0); }, [load]);
+  useEffect(() => { loadTrash(); }, [loadTrash]);
+
+  const restore = async (id: string) => {
+    try {
+      await api.restoreMedia(id);
+      loadTrash();
+      load(0);
+    } catch (e) {
+      onError(errMsg(e));
+    }
+  };
+  const purge = async (id: string) => {
+    if (!confirm("Delete this file permanently? The file itself is removed and cannot be recovered.")) return;
+    try {
+      await api.purgeMedia(id);
+      loadTrash();
+    } catch (e) {
+      onError(errMsg(e));
+    }
+  };
 
   const upload = async (files: FileList | null) => {
     if (!files?.length) return;
@@ -1153,13 +1371,37 @@ export function MediaLibrary({ api, onError }: { api: Api; onError: (s: string)
             <Button variant="secondary" size="sm" onPress={() => load(offset)}>Load more</Button>
           </div>
         ) : null}
+        {trash.length > 0 ? (
+          <div className="mt-6 border-t border-border pt-4">
+            <button type="button" className="text-small text-fg-muted underline" onClick={() => setShowTrash((v) => !v)}>
+              {showTrash ? "Hide" : "Show"} trash ({trash.length})
+            </button>
+            {showTrash ? (
+              <>
+                <p className="mt-2 text-small text-fg-subtle">
+                  Trashed files are hidden from the library but the file itself still exists — a page published
+                  while it was in use keeps showing it. Delete permanently to remove the file.
+                </p>
+                <div className="mt-2.5 flex flex-col gap-1.5">
+                  {trash.map((m) => (
+                    <div key={m.id} className="flex items-center gap-2.5 rounded-lg border border-border bg-surface-muted px-3 py-2">
+                      <span className="flex-1 truncate text-small text-fg-muted">{m.file?.filename ?? m.id}</span>
+                      <Button variant="secondary" size="sm" onPress={() => restore(m.id)}>Restore</Button>
+                      <Button variant="secondary" size="sm" onPress={() => purge(m.id)}>Delete permanently</Button>
+                    </div>
+                  ))}
+                </div>
+              </>
+            ) : null}
+          </div>
+        ) : null}
         {selected ? (
           <MediaDetail
             api={api}
             media={selected}
             onClose={() => setSelected(null)}
             onSaved={(m) => { setSelected(m); setMedia((prev) => prev.map((x) => (x.id === m.id ? m : x))); }}
-            onDeleted={(id) => { setSelected(null); setMedia((prev) => prev.filter((x) => x.id !== id)); }}
+            onDeleted={(id) => { setSelected(null); setMedia((prev) => prev.filter((x) => x.id !== id)); loadTrash(); }}
             onError={onError}
           />
         ) : null}
@@ -1185,7 +1427,7 @@ function MediaDetail({ api, media, onClose, onSaved, onDeleted, onError }: { api
     }
   };
   const del = async () => {
-    if (!confirm("Delete this file permanently? If a block or page still references it, that image will break — this cannot be undone.")) return;
+    if (!confirm("Move this file to the trash? It disappears from the library, but a page published while it was in use keeps showing it — delete it permanently from the trash to remove the file itself.")) return;
     setBusy(true);
     try {
       await api.deleteMedia(media.id);
@@ -1479,11 +1721,22 @@ function plainText(html: string): string {
     .replace(/\s+/g, " ")
     .trim();
 }
-/** One-line preview for a collapsed block: the first non-empty string field, tags stripped. */
-function blockPreview(fields: Record<string, unknown>): string {
-  const first = Object.values(fields).find((v) => typeof v === "string" && v.trim());
-  if (typeof first !== "string") return "";
-  const text = plainText(first);
+/** Readable text for one field value, whatever shape it is. A `richtext` field is a
+ * document tree, so the first non-empty STRING is no longer enough — a block whose only
+ * field is prose would read "empty". Legacy HTML strings still pass through `plainText`. */
+function fieldText(v: FieldValue): string {
+  if (typeof v === "string") return plainText(v);
+  if (isRichTextDoc(v)) return richTextToPlainText(v).replace(/\s+/g, " ").trim();
+  return "";
+}
+/** One-line preview for a collapsed block: the first field with readable text in it. */
+function blockPreview(fields: FieldValues): string {
+  let text = "";
+  for (const v of Object.values(fields)) {
+    text = fieldText(v);
+    if (text) break;
+  }
+  if (!text) return "";
   return text.length > 90 ? text.slice(0, 90) + "…" : text;
 }
 function reorderMove(blocks: RenderedBlock[], region: string, i: number, d: number, reorder: (region: string, order: string[]) => void) {