@wix/himalaya-cli 0.1071.0 → 0.1073.0

package/templates/nonprofit-cause-owner/dev/index.ts

@@ -71537,6 +71537,35 @@ const TEMPLATED: { pattern: string; display: string; liveSeed?: LiveSeed; static
                 }
               }
             },
+            {
+              "id": "event_form.description_note",
+              "body": {
+                "package": "himalaya",
+                "type": "Text",
+                "props": {
+                  "text": "$service:himiOwnerLiteEventForm.descriptionNote",
+                  "style": "footnote",
+                  "color": "textSecondary",
+                  "collapseWhenEmpty": true
+                }
+              }
+            },
+            {
+              "id": "event_form.description_preview",
+              "body": {
+                "package": "himalaya",
+                "type": "Text",
+                "props": {
+                  "text": "$service:himiOwnerLiteEventForm.description",
+                  "style": "body",
+                  "maxLines": 8,
+                  "collapseWhenEmpty": true
+                }
+              },
+              "modifiers": {
+                "hiddenPath": "$service:himiOwnerLiteEventForm.descriptionEditable"
+              }
+            },
             {
               "id": "event_form.form",
               "body": {
@@ -71581,6 +71610,9 @@ const TEMPLATED: { pattern: string; display: string; liveSeed?: LiveSeed; static
                             "multilineMaxLines": 3
                           }
                         }
+                      },
+                      "modifiers": {
+                        "hiddenPath": "$service:himiOwnerLiteEventForm.descriptionProtected"
                       }
                     }
                   ],

package/templates/nonprofit-cause-owner/tier5-src/_shared/owner-rich-guard.ts

@@ -0,0 +1,64 @@
+// [rico] #3363 — may a plain owner form round-trip this body? Ricos uses owner-post-content's
+// hasRichBody; these cover the Stores HTML description and the FAQ's legacy DraftJS answer.
+// [rico] #3365 moves htmlIsTrivial into @himalaya/wix-rich-content with these exact semantics.
+
+/** A tag opener (`<p`, `</p`, `<!--`), as opposed to a bare `<` in prose ("cups < 8 cm"). */
+const TAG = /<[a-z!/?]/i;
+
+/** True when a plain text field can hold this HTML without losing anything: empty, bare text
+ *  (no tag — a lone `<` in prose is text), or exactly one attribute-less `<p>…</p>` with no
+ *  inner tags. */
+export function htmlIsTrivial(html: string | null | undefined): boolean {
+  const s = (html ?? "").trim();
+  return !s || !TAG.test(s) || /^<p>[^<>]*<\/p>$/.test(s);
+}
+
+const ENTITIES: Record<string, string> = { "&nbsp;": " ", "&amp;": "&", "&lt;": "<", "&gt;": ">", "&quot;": "\"", "&#39;": "'" };
+
+/** Read-only preview text for an HTML body: block closes become lines, tags are stripped (a bare
+ *  `<` in prose is kept), the basic entities decode, and blank lines drop. */
+export function htmlPreviewText(html: string | null | undefined): string {
+  return (html ?? "").replace(/<br\s*\/?>/gi, "\n").replace(/<\/(p|h[1-6]|li|div|blockquote|pre|tr)>/gi, "\n")
+    .replace(/<\/?[a-z!?][^>]*>/gi, "").replace(/&(nbsp|amp|lt|gt|quot|#39);/g, (m) => ENTITIES[m] ?? m)
+    .split("\n").map((l) => l.replace(/\s+/g, " ").trim()).filter(Boolean).join("\n");
+}
+
+type RicosNode = { type?: unknown; nodes?: unknown; textData?: { decorations?: unknown }; paragraphData?: unknown; [key: string]: unknown };
+const onlyKeys = (o: object, allowed: string[]) => Object.keys(o).every((k) => allowed.includes(k));
+const emptyObject = (v: unknown) => v === undefined || (!!v && typeof v === "object" && Object.keys(v as object).length === 0);
+
+/** The paragraph styling a PLAIN paragraph still carries on the Ricos wire (Events v3 sends
+ *  `{ textStyle: { textAlignment: "AUTO" }, indentation: 0 }` on every paragraph). */
+function defaultParagraphData(pd: unknown): boolean {
+  if (pd === undefined) return true;
+  if (!pd || typeof pd !== "object" || !onlyKeys(pd, ["textStyle", "indentation"])) return false;
+  const { textStyle, indentation } = pd as { textStyle?: unknown; indentation?: unknown };
+  if (indentation !== undefined && indentation !== 0) return false;
+  if (textStyle === undefined) return true;
+  if (!textStyle || typeof textStyle !== "object" || !onlyKeys(textStyle, ["textAlignment"])) return false;
+  const align = (textStyle as { textAlignment?: unknown }).textAlignment;
+  return align === undefined || align === "AUTO";
+}
+
+/** True when a plain text field can round-trip this Ricos document: no document styling, and
+ *  only paragraphs of undecorated text whose paragraph data is the wire default. Anything else —
+ *  a heading, list, link, bold run, media node, alignment or indent — is rich. */
+export function ricosIsPlain(doc: { nodes?: unknown; documentStyle?: unknown } | null | undefined): boolean {
+  if (!doc || !emptyObject(doc.documentStyle)) return false;
+  const nodes = Array.isArray(doc.nodes) ? (doc.nodes as RicosNode[]) : [];
+  return nodes.every((n) => !!n && typeof n === "object" && n.type === "PARAGRAPH"
+    && onlyKeys(n, ["type", "id", "nodes", "paragraphData"]) && defaultParagraphData(n.paragraphData)
+    && (Array.isArray(n.nodes) ? (n.nodes as RicosNode[]) : []).every((t) => !!t && typeof t === "object" && t.type === "TEXT"
+      && onlyKeys(t, ["type", "id", "textData", "nodes"]) && (!Array.isArray(t.nodes) || t.nodes.length === 0)
+      && !(Array.isArray(t.textData?.decorations) && t.textData.decorations.length)));
+}
+
+/** Preview text for a legacy DraftJS document: its `blocks[].text` joined by a blank line, or ""
+ *  when the payload is not DraftJS JSON (never a throw). */
+export function draftjsText(raw: string | null | undefined): string {
+  try {
+    const doc = JSON.parse(raw ?? "") as { blocks?: Array<{ text?: unknown }> } | null;
+    const blocks = Array.isArray(doc?.blocks) ? doc.blocks : [];
+    return blocks.map((b) => (typeof b?.text === "string" ? b.text : "")).join("\n\n").trim();
+  } catch { return ""; }
+}

package/templates/nonprofit-cause-owner/tier5-src/himi-owner-lite-event-form/index.ts

@@ -8,7 +8,11 @@
 
 import { defineService } from "@himalaya/state";
 import { getEvent, updateEvent, type WixEvent } from "@himalaya/wix-events";
-import { normalizeEvent, eventDescription } from "../_shared/himi-events.js";
+import { normalizeEvent } from "../_shared/himi-events.js";
+import { postBodyText, plainPostBody } from "../_shared/owner-post-content.js";
+// Not owner-post-content's hasRichBody: Events v3 sends default paragraphData on EVERY paragraph
+// (which hasRichBody reads as formatting) and a documentStyle it never looks at.
+import { ricosIsPlain } from "../_shared/owner-rich-guard.js";
 import { ownerLoadError, isBridgeUnavailable, isOwnerPreviewDemo, shouldQueueOwnerWrite } from "../_shared/owner-load-error.js";
 import { DEMO_EVENTS, DEMO_NOTE, DEMO_SAVE_NOTE, demoRefusalPatch } from "../_shared/owner-preview-demo.js";
 import { stashCopy, copyParam } from "../_shared/himi-copy.js";
@@ -35,7 +39,17 @@ interface EventFormState {
   id: string;
   heading: string;
   title: string;
+  /** [rico] #3363 — the Events v3 Ricos `description` as text (read with `fields=TEXTS`). While
+   *  `descriptionProtected`, it is a read-only preview. */
   description: string;
+  /** The description as loaded (or last saved). A save writes `description` only when the
+   *  submitted value differs from it, so an untouched body is never re-written. */
+  originalDescription: string;
+  /** A Ricos description with formatting or media the plain field would flatten: it loads locked,
+   *  the descriptor shows a preview + `descriptionNote`, and an edit is refused. */
+  descriptionProtected: boolean;
+  descriptionEditable: boolean;
+  descriptionNote: string;
   when: string;
   location: string;
   status: "idle" | "loading" | "saving" | "saved" | "error";
@@ -94,6 +108,10 @@ function shape(s: Partial<EventFormState>): EventFormState {
     heading: s.heading ?? copyParam("ownerEventForm.headingEdit", "Edit event"),
     title: s.title ?? "",
     description: s.description ?? "",
+    originalDescription: s.originalDescription ?? s.description ?? "",
+    descriptionProtected: s.descriptionProtected ?? false,
+    descriptionEditable: !(s.descriptionProtected ?? false),
+    descriptionNote: s.descriptionProtected ? copyParam("ownerEventForm.richDescriptionNote", "This description has formatting or media. Edit it in your site dashboard to keep that content intact; the title can be changed here.") : "",
     when: s.when ?? "—",
     location: s.location ?? "—",
     status: s.status ?? "idle",
@@ -145,7 +163,8 @@ const svc = defineService<EventFormState, {
         return shape({ ...s, status: "error", error: "Sample item not found." });
       }
       try {
-        const res = await getEvent(id);
+        // `TEXTS` is the v3 fieldset that returns the Ricos `description`; a bare GET omits it.
+        const res = await getEvent(id, { fields: ["TEXTS"] });
         const ev = (res.event ?? res) as WixEvent;
         if (!ev || !(ev as any).id) {
           return shape({ ...s, mode, id, status: "error", error: copyParam("ownerEventForm.errorNotFound", "Event not found") });
@@ -157,7 +176,14 @@ const svc = defineService<EventFormState, {
           id,
           heading: copyParam("ownerEventForm.headingEdit", "Edit event"),
           title: ev.title ?? "",
-          description: (eventDescription(ev) || "").trim(),
+          // The v3 Ricos `description` only: `shortDescription` and `about` are separate fields
+          // this form never writes, so showing them here would invite an edit that lands elsewhere.
+          ...(() => {
+            const raw = (ev as unknown as { description?: unknown }).description;
+            const doc = raw && typeof raw === "object" && Array.isArray((raw as { nodes?: unknown }).nodes) ? raw as Parameters<typeof postBodyText>[0] : null;
+            const text = doc ? postBodyText(doc) : typeof raw === "string" ? raw.trim() : "";
+            return { description: text, originalDescription: text, descriptionProtected: doc ? !ricosIsPlain(doc as { nodes?: unknown; documentStyle?: unknown }) : false };
+          })(),
           when: row.dateLine || "—",
           location: row.location || "—",
           status: "idle",
@@ -172,6 +198,8 @@ const svc = defineService<EventFormState, {
             ...s, mode, id, heading: "Edit event",
             title: String(cached.title ?? cached.name ?? ""),
             description: String(cached.description ?? ""),
+            // An older cached row carries no verdict, so it stays locked: fail closed.
+            originalDescription: String(cached.description ?? ""), descriptionProtected: cached.descriptionProtected !== "false",
             when: String(cached.when ?? cached.dateLine ?? "—"),
             location: String(cached.location ?? "—"),
             status: "idle", error: "", savedMessage: "",
@@ -195,18 +223,23 @@ const svc = defineService<EventFormState, {
       const v = values ?? {};
       const title = String(v.title ?? s.title).trim();
       const description = String(v.description ?? s.description).trim();
+      // A queue replay boots a FRESH worker (empty baseline), so it carries the original verdict.
+      const descriptionEdited = typeof v.descriptionEdited === "string" ? v.descriptionEdited === "true" : description !== s.originalDescription.trim();
+      if (descriptionEdited && s.descriptionProtected) return shape({ ...s, status: "error", savedMessage: "", error: copyParam("ownerEventForm.richDescriptionError", "This description has formatting or media. Edit it in your site dashboard to keep that content intact.") });
       if (!title) return shape({ ...s, status: "error", error: copyParam("ownerEventForm.titleRequired", "Title is required"), savedMessage: "" });
       if (!s.id) return shape({ ...s, status: "error", error: copyParam("ownerEventForm.errorNoEvent", "No event to edit."), savedMessage: "" });
 
       // updateEvent(id, event) wraps the body as { event } internally, so pass the
-      // event fields directly. Only the text the form can safely edit is written.
-      const event: any = {
-        title,
-        ...(description ? { description } : {}),
+      // event fields directly. Only the text the form can safely edit is written: the
+      // description only when edited, and always as a Ricos document (never a string).
+      // A local structural type, not WixEventWrite: templates compile against the
+      // PUBLISHED SDK until its next release.
+      const event: { title: string; description?: { nodes: unknown[] } } = {
+        title, ...(descriptionEdited ? { description: description ? plainPostBody(description) as { nodes: unknown[] } : { nodes: [] } } : {}),
       };
 
       // Optimistic local write — the detail/list repaint from cache immediately.
-      const localRow: DbEntity = { id: s.id, name: title, title, description, when: s.when, location: s.location };
+      const localRow: DbEntity = { id: s.id, name: title, title, description, descriptionProtected: String(s.descriptionProtected), when: s.when, location: s.location };
       await cachePut(localRow);
       try {
         await updateEvent(s.id, event);
@@ -217,6 +250,7 @@ const svc = defineService<EventFormState, {
           heading: copyParam("ownerEventForm.headingEdit", "Edit event"),
           title,
           description,
+          originalDescription: descriptionEdited ? description : s.originalDescription,
           status: "saved",
           error: "",
           savedMessage: copyParam("ownerEventForm.savedMessage", "Event saved."),
@@ -230,10 +264,10 @@ const svc = defineService<EventFormState, {
           if (s.demoNote) return demoRefusal(s);
           // Real device offline: the optimistic cache row already shows; queue the
           // write to replay (WriteQueue, idempotent) when connectivity returns.
-          await queueWrite("tier5.himiOwnerLiteEventForm.submit", { id: s.id, title, description });
+          await queueWrite("tier5.himiOwnerLiteEventForm.submit", { id: s.id, title, description, descriptionEdited: String(descriptionEdited) });
           return shape({
             ...s, mode: "edit", id: s.id, heading: copyParam("ownerEventForm.headingEdit", "Edit event"),
-            title, description, status: "saved", error: "",
+            title, description, originalDescription: descriptionEdited ? description : s.originalDescription, status: "saved", error: "",
             savedMessage: copyParam("ownerEventForm.savedOffline", "Saved offline — will sync when you reconnect."),
             savedId: s.id,
           });

package/templates/owner-lite/dev/index.ts

@@ -73734,6 +73734,35 @@ const SCREENS = runtimeSetting({
                 }
               }
             },
+            {
+              "id": "faq_question.answer_note",
+              "body": {
+                "package": "himalaya",
+                "type": "Text",
+                "props": {
+                  "text": "$service:himiOwnerLiteFaqQuestionForm.answerNote",
+                  "style": "footnote",
+                  "color": "textSecondary",
+                  "collapseWhenEmpty": true
+                }
+              }
+            },
+            {
+              "id": "faq_question.answer_preview",
+              "body": {
+                "package": "himalaya",
+                "type": "Text",
+                "props": {
+                  "text": "$service:himiOwnerLiteFaqQuestionForm.answer",
+                  "style": "body",
+                  "maxLines": 8,
+                  "collapseWhenEmpty": true
+                }
+              },
+              "modifiers": {
+                "hiddenPath": "$service:himiOwnerLiteFaqQuestionForm.answerEditable"
+              }
+            },
             {
               "id": "faq_question.form",
               "body": {
@@ -73779,6 +73808,9 @@ const SCREENS = runtimeSetting({
                             "autoCapitalization": "sentences"
                           }
                         }
+                      },
+                      "modifiers": {
+                        "hiddenPath": "$service:himiOwnerLiteFaqQuestionForm.answerProtected"
                       }
                     },
                     {
@@ -73946,6 +73978,35 @@ const SCREENS = runtimeSetting({
                 }
               }
             },
+            {
+              "id": "faq_question.answer_note",
+              "body": {
+                "package": "himalaya",
+                "type": "Text",
+                "props": {
+                  "text": "$service:himiOwnerLiteFaqQuestionForm.answerNote",
+                  "style": "footnote",
+                  "color": "textSecondary",
+                  "collapseWhenEmpty": true
+                }
+              }
+            },
+            {
+              "id": "faq_question.answer_preview",
+              "body": {
+                "package": "himalaya",
+                "type": "Text",
+                "props": {
+                  "text": "$service:himiOwnerLiteFaqQuestionForm.answer",
+                  "style": "body",
+                  "maxLines": 8,
+                  "collapseWhenEmpty": true
+                }
+              },
+              "modifiers": {
+                "hiddenPath": "$service:himiOwnerLiteFaqQuestionForm.answerEditable"
+              }
+            },
             {
               "id": "faq_question.form",
               "body": {
@@ -73991,6 +74052,9 @@ const SCREENS = runtimeSetting({
                             "autoCapitalization": "sentences"
                           }
                         }
+                      },
+                      "modifiers": {
+                        "hiddenPath": "$service:himiOwnerLiteFaqQuestionForm.answerProtected"
                       }
                     },
                     {
@@ -78045,6 +78109,35 @@ const SCREENS = runtimeSetting({
                 }
               }
             },
+            {
+              "id": "product_form.description_note",
+              "body": {
+                "package": "himalaya",
+                "type": "Text",
+                "props": {
+                  "text": "$service:himiOwnerLiteProductForm.descriptionNote",
+                  "style": "footnote",
+                  "color": "textSecondary",
+                  "collapseWhenEmpty": true
+                }
+              }
+            },
+            {
+              "id": "product_form.description_preview",
+              "body": {
+                "package": "himalaya",
+                "type": "Text",
+                "props": {
+                  "text": "$service:himiOwnerLiteProductForm.description",
+                  "style": "body",
+                  "maxLines": 8,
+                  "collapseWhenEmpty": true
+                }
+              },
+              "modifiers": {
+                "hiddenPath": "$service:himiOwnerLiteProductForm.descriptionEditable"
+              }
+            },
             {
               "id": "product_form.form",
               "body": {
@@ -78131,6 +78224,9 @@ const SCREENS = runtimeSetting({
                             "multilineMaxLines": 3
                           }
                         }
+                      },
+                      "modifiers": {
+                        "hiddenPath": "$service:himiOwnerLiteProductForm.descriptionProtected"
                       }
                     }
                   ],
@@ -78658,6 +78754,35 @@ const TEMPLATED: { pattern: string; display: string; liveSeed?: LiveSeed; static
                 }
               }
             },
+            {
+              "id": "product_form.description_note",
+              "body": {
+                "package": "himalaya",
+                "type": "Text",
+                "props": {
+                  "text": "$service:himiOwnerLiteProductForm.descriptionNote",
+                  "style": "footnote",
+                  "color": "textSecondary",
+                  "collapseWhenEmpty": true
+                }
+              }
+            },
+            {
+              "id": "product_form.description_preview",
+              "body": {
+                "package": "himalaya",
+                "type": "Text",
+                "props": {
+                  "text": "$service:himiOwnerLiteProductForm.description",
+                  "style": "body",
+                  "maxLines": 8,
+                  "collapseWhenEmpty": true
+                }
+              },
+              "modifiers": {
+                "hiddenPath": "$service:himiOwnerLiteProductForm.descriptionEditable"
+              }
+            },
             {
               "id": "product_form.form",
               "body": {
@@ -78744,6 +78869,9 @@ const TEMPLATED: { pattern: string; display: string; liveSeed?: LiveSeed; static
                             "multilineMaxLines": 3
                           }
                         }
+                      },
+                      "modifiers": {
+                        "hiddenPath": "$service:himiOwnerLiteProductForm.descriptionProtected"
                       }
                     }
                   ],
@@ -79182,6 +79310,35 @@ const TEMPLATED: { pattern: string; display: string; liveSeed?: LiveSeed; static
                 }
               }
             },
+            {
+              "id": "event_form.description_note",
+              "body": {
+                "package": "himalaya",
+                "type": "Text",
+                "props": {
+                  "text": "$service:himiOwnerLiteEventForm.descriptionNote",
+                  "style": "footnote",
+                  "color": "textSecondary",
+                  "collapseWhenEmpty": true
+                }
+              }
+            },
+            {
+              "id": "event_form.description_preview",
+              "body": {
+                "package": "himalaya",
+                "type": "Text",
+                "props": {
+                  "text": "$service:himiOwnerLiteEventForm.description",
+                  "style": "body",
+                  "maxLines": 8,
+                  "collapseWhenEmpty": true
+                }
+              },
+              "modifiers": {
+                "hiddenPath": "$service:himiOwnerLiteEventForm.descriptionEditable"
+              }
+            },
             {
               "id": "event_form.form",
               "body": {
@@ -79226,6 +79383,9 @@ const TEMPLATED: { pattern: string; display: string; liveSeed?: LiveSeed; static
                             "multilineMaxLines": 3
                           }
                         }
+                      },
+                      "modifiers": {
+                        "hiddenPath": "$service:himiOwnerLiteEventForm.descriptionProtected"
                       }
                     }
                   ],
@@ -84882,6 +85042,35 @@ const TEMPLATED: { pattern: string; display: string; liveSeed?: LiveSeed; static
                 }
               }
             },
+            {
+              "id": "faq_question.answer_note",
+              "body": {
+                "package": "himalaya",
+                "type": "Text",
+                "props": {
+                  "text": "$service:himiOwnerLiteFaqQuestionForm.answerNote",
+                  "style": "footnote",
+                  "color": "textSecondary",
+                  "collapseWhenEmpty": true
+                }
+              }
+            },
+            {
+              "id": "faq_question.answer_preview",
+              "body": {
+                "package": "himalaya",
+                "type": "Text",
+                "props": {
+                  "text": "$service:himiOwnerLiteFaqQuestionForm.answer",
+                  "style": "body",
+                  "maxLines": 8,
+                  "collapseWhenEmpty": true
+                }
+              },
+              "modifiers": {
+                "hiddenPath": "$service:himiOwnerLiteFaqQuestionForm.answerEditable"
+              }
+            },
             {
               "id": "faq_question.form",
               "body": {
@@ -84927,6 +85116,9 @@ const TEMPLATED: { pattern: string; display: string; liveSeed?: LiveSeed; static
                             "autoCapitalization": "sentences"
                           }
                         }
+                      },
+                      "modifiers": {
+                        "hiddenPath": "$service:himiOwnerLiteFaqQuestionForm.answerProtected"
                       }
                     },
                     {

package/templates/owner-lite/tier5-src/_shared/owner-rich-guard.ts

@@ -0,0 +1,64 @@
+// [rico] #3363 — may a plain owner form round-trip this body? Ricos uses owner-post-content's
+// hasRichBody; these cover the Stores HTML description and the FAQ's legacy DraftJS answer.
+// [rico] #3365 moves htmlIsTrivial into @himalaya/wix-rich-content with these exact semantics.
+
+/** A tag opener (`<p`, `</p`, `<!--`), as opposed to a bare `<` in prose ("cups < 8 cm"). */
+const TAG = /<[a-z!/?]/i;
+
+/** True when a plain text field can hold this HTML without losing anything: empty, bare text
+ *  (no tag — a lone `<` in prose is text), or exactly one attribute-less `<p>…</p>` with no
+ *  inner tags. */
+export function htmlIsTrivial(html: string | null | undefined): boolean {
+  const s = (html ?? "").trim();
+  return !s || !TAG.test(s) || /^<p>[^<>]*<\/p>$/.test(s);
+}
+
+const ENTITIES: Record<string, string> = { "&nbsp;": " ", "&amp;": "&", "&lt;": "<", "&gt;": ">", "&quot;": "\"", "&#39;": "'" };
+
+/** Read-only preview text for an HTML body: block closes become lines, tags are stripped (a bare
+ *  `<` in prose is kept), the basic entities decode, and blank lines drop. */
+export function htmlPreviewText(html: string | null | undefined): string {
+  return (html ?? "").replace(/<br\s*\/?>/gi, "\n").replace(/<\/(p|h[1-6]|li|div|blockquote|pre|tr)>/gi, "\n")
+    .replace(/<\/?[a-z!?][^>]*>/gi, "").replace(/&(nbsp|amp|lt|gt|quot|#39);/g, (m) => ENTITIES[m] ?? m)
+    .split("\n").map((l) => l.replace(/\s+/g, " ").trim()).filter(Boolean).join("\n");
+}
+
+type RicosNode = { type?: unknown; nodes?: unknown; textData?: { decorations?: unknown }; paragraphData?: unknown; [key: string]: unknown };
+const onlyKeys = (o: object, allowed: string[]) => Object.keys(o).every((k) => allowed.includes(k));
+const emptyObject = (v: unknown) => v === undefined || (!!v && typeof v === "object" && Object.keys(v as object).length === 0);
+
+/** The paragraph styling a PLAIN paragraph still carries on the Ricos wire (Events v3 sends
+ *  `{ textStyle: { textAlignment: "AUTO" }, indentation: 0 }` on every paragraph). */
+function defaultParagraphData(pd: unknown): boolean {
+  if (pd === undefined) return true;
+  if (!pd || typeof pd !== "object" || !onlyKeys(pd, ["textStyle", "indentation"])) return false;
+  const { textStyle, indentation } = pd as { textStyle?: unknown; indentation?: unknown };
+  if (indentation !== undefined && indentation !== 0) return false;
+  if (textStyle === undefined) return true;
+  if (!textStyle || typeof textStyle !== "object" || !onlyKeys(textStyle, ["textAlignment"])) return false;
+  const align = (textStyle as { textAlignment?: unknown }).textAlignment;
+  return align === undefined || align === "AUTO";
+}
+
+/** True when a plain text field can round-trip this Ricos document: no document styling, and
+ *  only paragraphs of undecorated text whose paragraph data is the wire default. Anything else —
+ *  a heading, list, link, bold run, media node, alignment or indent — is rich. */
+export function ricosIsPlain(doc: { nodes?: unknown; documentStyle?: unknown } | null | undefined): boolean {
+  if (!doc || !emptyObject(doc.documentStyle)) return false;
+  const nodes = Array.isArray(doc.nodes) ? (doc.nodes as RicosNode[]) : [];
+  return nodes.every((n) => !!n && typeof n === "object" && n.type === "PARAGRAPH"
+    && onlyKeys(n, ["type", "id", "nodes", "paragraphData"]) && defaultParagraphData(n.paragraphData)
+    && (Array.isArray(n.nodes) ? (n.nodes as RicosNode[]) : []).every((t) => !!t && typeof t === "object" && t.type === "TEXT"
+      && onlyKeys(t, ["type", "id", "textData", "nodes"]) && (!Array.isArray(t.nodes) || t.nodes.length === 0)
+      && !(Array.isArray(t.textData?.decorations) && t.textData.decorations.length)));
+}
+
+/** Preview text for a legacy DraftJS document: its `blocks[].text` joined by a blank line, or ""
+ *  when the payload is not DraftJS JSON (never a throw). */
+export function draftjsText(raw: string | null | undefined): string {
+  try {
+    const doc = JSON.parse(raw ?? "") as { blocks?: Array<{ text?: unknown }> } | null;
+    const blocks = Array.isArray(doc?.blocks) ? doc.blocks : [];
+    return blocks.map((b) => (typeof b?.text === "string" ? b.text : "")).join("\n\n").trim();
+  } catch { return ""; }
+}