@pramen/cms-editor 0.0.49 → 0.0.50

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pramen/cms-editor",
-  "version": "0.0.49",
-  "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

@@ -129,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/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, FieldValues, 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);
 }
@@ -265,6 +271,185 @@ 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<FieldValues>({});
@@ -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>
@@ -629,7 +820,7 @@ 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(() => {
@@ -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. */
+/** 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 {
-  const first = Object.values(fields).find((v) => typeof v === "string" && v.trim());
-  if (typeof first !== "string") return "";
-  const text = plainText(first);
+  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) {

package/src/fields.tsx

@@ -3,13 +3,19 @@
 
 import { Button, Heading, Input, ModalDialog, ModalOverlay, ModalSurface, Text, Textarea } from "@podoba/react";
 import { BlockEditor } from "@podoba/react/editor";
+import { generateHTML, generateJSON } from "@tiptap/core";
+import Highlight from "@tiptap/extension-highlight";
+import TaskItem from "@tiptap/extension-task-item";
+import TaskList from "@tiptap/extension-task-list";
+import StarterKit from "@tiptap/starter-kit";
 import { useEffect, useRef, useState, type DragEvent, type ReactNode } from "react";
 import type { Api } from "./api";
-import type { FieldDefinition, FieldValue, FieldValues, Media } from "./types";
+import { isRichTextDoc, richTextToPlainText } from "./rich-text";
+import type { FieldDefinition, FieldValue, FieldValues, Media, RichTextDoc } from "./types";
 
 // Tokenized bare control (podoba's filled-field skin) for the native inputs that
 // don't map cleanly onto a podoba primitive (number/date/select/file).
-const CONTROL = "h-10 w-full rounded-lg border border-border bg-surface-card px-4 text-sm text-fg outline-none transition-colors placeholder:text-fg-muted focus:border-brand-green";
+export const CONTROL = "h-10 w-full rounded-lg border border-border bg-surface-card px-4 text-sm text-fg outline-none transition-colors placeholder:text-fg-muted focus:border-brand-green";
 
 function FieldShell({ label, children }: { label: ReactNode; children: ReactNode }) {
   return (
@@ -33,7 +39,7 @@ function FieldShell({ label, children }: { label: ReactNode; children: ReactNode
  * Returns "" for anything Date can't parse — a legacy or hand-written column value must
  * not reach the input as `NaN-NaN-NaNTNaN:NaN`, which the browser silently discards.
  */
-function toLocalInput(value: string): string {
+export function toLocalInput(value: string): string {
   const d = new Date(value);
   if (Number.isNaN(d.getTime())) return "";
   const pad = (n: number) => String(n).padStart(2, "0");
@@ -41,12 +47,12 @@ function toLocalInput(value: string): string {
 }
 
 /** A `datetime-local` string (local wall clock) -> the UTC ISO instant we store. */
-function fromLocalInput(local: string): string | null {
+export function fromLocalInput(local: string): string | null {
   const at = new Date(local);
   return Number.isNaN(at.getTime()) ? null : at.toISOString();
 }
 
-function formatWhen(value: string): string {
+export function formatWhen(value: string): string {
   const at = new Date(value);
   return Number.isNaN(at.getTime()) ? value : at.toLocaleString();
 }
@@ -195,11 +201,11 @@ function FieldInput({ def, value, onChange, api, hideLabelAs, siblings }: { def:
         <Textarea label={label} value={asText(value)} onChange={onChange} />
       );
     case "richtext":
-      // A rich-text value is an HTML string (round-trips with the site's set:html
-      // renderers). A legacy object value isn't editable here — fall back to raw text.
+      // A rich-text value is a document tree. A legacy HTML string still opens (it seeds
+      // the editor as-is) and is upgraded to a doc by the first save.
       return (
         <FieldShell label={label}>
-          <RichText value={typeof value === "string" ? value : ""} onChange={onChange as (v: string) => void} />
+          <RichText value={value as RichTextDoc | string | null} onChange={onChange as (v: RichTextDoc) => void} />
         </FieldShell>
       );
     case "number":
@@ -271,13 +277,90 @@ function FieldInput({ def, value, onChange, api, hideLabelAs, siblings }: { def:
 
 // --- rich text (WYSIWYG) --------------------------------------------------------------
 // The `richtext` field is podoba's Notion-style BlockEditor (Tiptap): `/` slash palette,
-// block conversion, inline bubble toolbar. Still an HTML string in/out, so it round-trips
-// with existing rich_text content + every set:html renderer — no value migration. The
-// server's sanitizeRichText() (@pramen/cms) remains the XSS boundary on write; ProseMirror
-// parses HTML to its schema on load, so scripts never survive into the editor either.
+// block conversion, inline bubble toolbar.
+//
+// The STORED value is a document tree (`RichTextDoc`), never HTML. BlockEditor's own
+// value contract is an HTML string — its docs call that presentation-only — so the
+// conversion happens here, at the boundary, and the HTML never leaves this component:
+// seeded from the stored doc on mount, converted back to a doc on every change.
+//
+// The extension set MUST match BlockEditor's, or a round-trip silently drops whatever
+// only its schema knows (task lists, highlights). Kept beside it here for that reason.
+const RT_EXTENSIONS = [
+  StarterKit.configure({ heading: { levels: [1, 2, 3] }, link: { openOnClick: false, autolink: true } }),
+  Highlight,
+  TaskList,
+  TaskItem.configure({ nested: true }),
+];
+
+/** Parse editor HTML into a document. Never throws: a parse failure yields an empty
+ * document rather than taking the render down (this runs on every keystroke). */
+function htmlToDoc(html: string): RichTextDoc {
+  try {
+    return generateJSON(html, RT_EXTENSIONS) as RichTextDoc;
+  } catch (e) {
+    console.error("pramen/cms-editor: could not parse editor HTML", e);
+    return { type: "doc", content: [] };
+  }
+}
+
+/** Seed HTML for the editor. A legacy HTML string passes through untouched — that is the
+ * migration ramp (see `RichText`, which upgrades it on mount).
+ *
+ * `generateHTML` throws a RangeError for any node or mark outside RT_EXTENSIONS, and this
+ * runs in a useState initializer with no ErrorBoundary above it — so an un-normalized
+ * document (a custom `richTextSchema`, an import, a bootstrap seed, `ctx.db.exec`) would
+ * throw during render and blank the whole SPA, not just this field. Fail to an empty
+ * editor and say so instead. */
+function docToEditorHtml(value: RichTextDoc | string | null | undefined): string {
+  if (typeof value === "string") return value;
+  if (!isRichTextDoc(value)) return "";
+  try {
+    return generateHTML(value, RT_EXTENSIONS);
+  } catch (e) {
+    console.error("pramen/cms-editor: rich-text document uses nodes this editor cannot render", e);
+    return "";
+  }
+}
+
+export function RichText({ value, onChange }: { value: RichTextDoc | string | null; onChange: (v: RichTextDoc) => void }) {
+  // BlockEditor requires its own HTML echoed back VERBATIM — normalising in render would
+  // re-seed the document on every keystroke and throw the caret back to the start. So the
+  // HTML lives in local state and the doc goes upward.
+  const [html, setHtml] = useState(() => docToEditorHtml(value));
+  const emitted = useRef<RichTextDoc | null>(null);
+
+  // Upgrade a legacy HTML value to a document AS SOON AS IT OPENS, not on first edit of
+  // this field. The server only tolerates a legacy string that is byte-identical to what
+  // is stored, and both renderers emit nothing for a string — so a value that is never
+  // upgraded stays invisible on the site forever. Converting on mount means any ordinary
+  // save (even of a sibling field) writes it back as a document.
+  const upgraded = useRef(false);
+  useEffect(() => {
+    if (upgraded.current || typeof value !== "string" || value === "") return;
+    upgraded.current = true;
+    const doc = htmlToDoc(value);
+    emitted.current = doc;
+    onChange(doc);
+  }, [value, onChange]);
+
+  // Re-seed only when the parent hands us a doc that is not the one we last emitted —
+  // i.e. the form switched to a different block, not our own change coming back around.
+  useEffect(() => {
+    if (value !== null && value === emitted.current) return;
+    setHtml(docToEditorHtml(value));
+    // Only the incoming value should re-seed; `html` is this effect's output, not its input.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [value]);
+
+  const handleChange = (nextHtml: string) => {
+    setHtml(nextHtml);
+    const doc = htmlToDoc(nextHtml);
+    emitted.current = doc;
+    onChange(doc);
+  };
 
-export function RichText({ value, onChange }: { value: string; onChange: (v: string) => void }) {
-  return <BlockEditor value={value} onChange={onChange} minHeight={180} placeholder="Write, or press '/' for blocks…" />;
+  return <BlockEditor value={html} onChange={handleChange} minHeight={180} placeholder="Write, or press '/' for blocks…" />;
 }
 
 /**
@@ -327,7 +410,11 @@ function Repeater({ def, value, onChange, api, label }: { def: FieldDefinition;
     for (const f of fields) {
       if (!readable.includes(f.type)) continue;
       const v = it[f.name];
-      if (typeof v === "string" && v.trim()) return v.replace(/<[^>]+>/g, " ").trim().slice(0, 80);
+      // A `richtext` value is a document tree, so a string check alone would skip the one
+      // prose field an item has — exactly the row this summary exists to distinguish.
+      const text = isRichTextDoc(v) ? richTextToPlainText(v) : typeof v === "string" ? v.replace(/<[^>]+>/g, " ") : "";
+      const trimmed = text.replace(/\s+/g, " ").trim();
+      if (trimmed) return trimmed.slice(0, 80);
     }
     return "";
   };

package/src/rich-text.ts

@@ -0,0 +1,30 @@
+// Rich-text helpers for the editor. Local mirrors of the @pramen/cms functions, kept here
+// because the editor is a self-contained browser app with no server-package dependency —
+// it speaks to the CMS purely over HTTP (see types.ts).
+
+import type { RichTextDoc, RichTextNode } from "./types";
+
+/** Is this value a rich-text document (rather than a legacy HTML string or a plain bag)? */
+export function isRichTextDoc(v: unknown): v is RichTextDoc {
+  return typeof v === "object" && v !== null && !Array.isArray(v) && (v as RichTextDoc).type === "doc";
+}
+
+/** The block-level node types that end a line when flattening to plain text. */
+const BLOCK_TYPES = new Set(["paragraph", "heading", "listItem", "taskItem", "blockquote", "codeBlock", "horizontalRule"]);
+
+/** Flatten a rich-text document to plain text — for list cells and collapsed-block
+ * previews, which want the words without the structure. Mirrors `richTextToPlainText`
+ * in @pramen/cms. */
+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 (BLOCK_TYPES.has(node.type)) parts.push("\n");
+    }
+  };
+  walk(value?.content ?? []);
+  return parts.join("").replace(/\n{2,}/g, "\n").trim();
+}