@wix/himalaya-cli 0.1172.0 → 0.1174.0

package/templates/owner-lite/tier5-src/_shared/owner-editor-value.ts

@@ -8,7 +8,7 @@
 // drops nodes the owner never touched).
 // Inside the platform source this import is a relative path, so node test runs resolve it; an app's
 // copy imports "@himalaya/wix-rich-content".
-import { parseRicosJson, RICH_CONTENT_LIMITS, type RicosDocument } from "@himalaya/wix-rich-content";
+import { parseRicosJson, isPlainRicos, RICH_CONTENT_LIMITS, type RicosDocument } from "@himalaya/wix-rich-content";
 
 export type EditorValue =
   | { kind: "absent" }                                  // leave the stored body untouched
@@ -45,12 +45,78 @@ function overLimits(doc: RicosDocument): boolean {
   return false;
 }
 
-/** `raw` is `values[name]`; `seededJson` is the string the form published as the editor's seed. */
-export function editorValue(raw: unknown, seededJson: string): EditorValue {
-  if (typeof raw !== "string" || raw === "") return { kind: "absent" };
-  if (seededJson !== "" && raw === seededJson) return { kind: "unchanged" };
+const TEXT_ONLY = new Set(["PARAGRAPH", "TEXT", "HEADING", "BULLETED_LIST", "ORDERED_LIST", "LIST_ITEM", "BLOCKQUOTE", "CODE_BLOCK"]);
+/** No visible text and no non-text node (an image, a divider, an embed…): an empty body. */
+export function isEmptyDocument(doc: RicosDocument): boolean {
+  const empty = (nodes: RicosDocument["nodes"] | undefined): boolean => (nodes ?? []).every((n) =>
+    TEXT_ONLY.has(String(n?.type)) && !String(n.textData?.text ?? "").trim() && empty(n.nodes));
+  return empty(doc.nodes);
+}
+
+/** A Ricos JSON string checked as every viewer would: the limits first, then the shape. */
+function checkedDocument(raw: string): EditorValue {
   if (utf8Bytes(raw) > RICH_CONTENT_LIMITS.maxBytes) return { kind: "too_large" };
   const doc = parseRicosJson(raw);
   if (!doc) return { kind: "invalid" };
   return overLimits(doc) ? { kind: "too_large" } : { kind: "doc", doc, json: raw };
 }
+
+/** `raw` is `values[name]`; `seededJson` is the string the form published as the editor's seed. */
+export function editorValue(raw: unknown, seededJson: string): EditorValue {
+  if (typeof raw !== "string" || raw === "") return { kind: "absent" };
+  if (seededJson !== "" && raw === seededJson) return { kind: "unchanged" };
+  const checked = checkedDocument(raw);
+  // An empty editor over no body (a record that had none) writes nothing, rather than an empty document.
+  if (checked.kind === "doc" && seededJson === "" && isEmptyDocument(checked.doc)) return { kind: "unchanged" };
+  return checked;
+}
+
+// ── The per-field editor machinery every owner form shares (post body, event / product description,
+// FAQ answer). Each form keeps `<key>Json` (the seed), `<key>Pending` and `<key>Dirty` in its state.
+
+/** `<key>Pending`: until this run's load lands, the descriptor hides the editor — it seeds ONCE, so a
+ *  provisional editor the owner typed into would keep that text over the real document.
+ *  `<key>Dirty`: the editor's on_change fired since the field was loaded or saved. Once ready the bag
+ *  ALWAYS holds a document — the engine's own re-serialization of the seed, not byte-equal to it — so
+ *  only this says the owner edited the field. Every arm fires a pending on_change before it releases a
+ *  Form submit, so an edit made inside the debounce window is reported before the submit reads it. */
+export interface EditorGate { pending: boolean; dirty: boolean }
+
+/** What a live submit does with `values[name]`: only an edit the editor reported counts. */
+export function editorSubmitValue(raw: unknown, seededJson: string, gate: EditorGate): EditorValue {
+  return gate.pending || !gate.dirty ? { kind: "absent" } : editorValue(raw, seededJson);
+}
+
+/** A queued write's document. A replay runs in a FRESH worker with no editor, so the string is checked
+ *  again (shape and limits); "absent" when the item carries none. Never "unchanged": it was an edit. */
+export function queuedDocument(raw: unknown): EditorValue {
+  return typeof raw === "string" && raw !== "" ? checkedDocument(raw) : { kind: "absent" };
+}
+
+/** The editor's on_change: the field is now edited, and a confirmation of an earlier save is stale.
+ *  No timing window: an arm fires the pending on_change BEFORE it releases a submit, so any on_change
+ *  that arrives after a save carries an edit that save did not write. */
+export function editorChanged<S extends { status: string; savedMessage: string }>(s: S): Pick<S, "status" | "savedMessage"> {
+  return { status: s.status === "saved" ? "idle" : s.status, savedMessage: "" };
+}
+
+/** The offline cache's verdict on the stored body (`<key>Protected`): rich unless KNOWN plain. From the
+ *  document when the form knows it; otherwise plain only when the record was loaded as plain. A bundle
+ *  rolled back past the editor reads this flag to decide whether its plain field may overwrite the body. */
+export function cachedRichVerdict(doc: RicosDocument | null, knownPlain: boolean): "true" | "false" {
+  if (doc) return isPlainRicos(doc) ? "false" : "true";
+  return knownPlain ? "false" : "true";
+}
+
+/** Cold boot: the runtime lays this service's last persisted snapshot over its declared state, so the
+ *  editor's first seed would be the document as it was when the screen last ran — and a Save after
+ *  typing would write it over whatever the record holds now. Blank the hydrated seed and reset the gate
+ *  before anything renders, in place (no action has run yet). `extra` resets further UI state. */
+export function resetHydratedEditor(svc: unknown, keys: { json: string; pending: string; dirty: string }, pendingAtBoot: boolean, extra: Record<string, unknown> = {}): void {
+  const booted = (svc as { getState?: () => Record<string, unknown> | undefined }).getState?.();
+  if (!booted || typeof booted !== "object") return;
+  if (booted[keys.json]) booted[keys.json] = "";
+  booted[keys.pending] = pendingAtBoot;
+  booted[keys.dirty] = false;
+  Object.assign(booted, extra);
+}

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

@@ -2,7 +2,7 @@
 // this file adds the read-only previews the forms show for a locked body, and the FAQ's legacy DraftJS answer.
 // Inside the platform source this import is a relative path, so node test runs resolve it; an app's copy
 // imports "@himalaya/wix-rich-content".
-import { htmlIsTrivial, isPlainRicos } from "@himalaya/wix-rich-content";
+import { htmlIsTrivial } from "@himalaya/wix-rich-content";
 
 export { htmlIsTrivial };
 
@@ -16,14 +16,6 @@ export function htmlPreviewText(html: string | null | undefined): string {
     .split("\n").map((l) => l.replace(/\s+/g, " ").trim()).filter(Boolean).join("\n");
 }
 
-/** 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 (Events v3 sends
- *  `{ textStyle: { textAlignment: "AUTO" }, indentation: 0 }` on every paragraph). Anything else —
- *  a heading, list, link, bold run, media node, alignment or indent — is rich, and so is a missing
- *  document (callers decide what an absent body means). */
-export const ricosIsPlain = (doc: { nodes?: unknown; documentStyle?: unknown } | null | undefined): boolean =>
-  !!doc && isPlainRicos(doc);
-
 /** 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 {

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

@@ -10,9 +10,9 @@ import { defineService } from "@himalaya/state";
 import { getEvent, updateEvent, type WixEvent } from "@himalaya/wix-events";
 import { normalizeEvent } from "../_shared/himi-events.js";
 import { postBodyText, plainPostBody } from "../_shared/owner-post-content.js";
-// Events v3 sends default paragraphData on EVERY paragraph and an empty documentStyle; ricosIsPlain
-// reads both as plain.
-import { ricosIsPlain } from "../_shared/owner-rich-guard.js";
+import { editorSubmitValue, queuedDocument, editorChanged, cachedRichVerdict, resetHydratedEditor } from "../_shared/owner-editor-value.js";
+import { parseRicosJson } from "@himalaya/wix-rich-content";
+import { ricosUploadService } from "@himalaya/wix-rich-content-editor";
 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";
@@ -39,14 +39,27 @@ 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. */
+  /** The Events v3 Ricos `description` as text (read with `fields=TEXTS`): the plain field's value,
+   *  the locked preview, and the cached row's mirror. */
   description: string;
-  /** The description as loaded (or last saved). A save writes `description` only when the
+  /** The description as loaded (or last saved). The plain field 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. */
+  /** How THIS record's description is edited:
+   *  "editor" — the RichContentEditor, seeded with `descriptionJson` (every live event; sample data);
+   *  "plain"  — the plain text field (an offline row cached as plain before the editor existed);
+   *  "locked" — neither (an offline row cached as rich, with no document to seed the editor). */
+  descriptionMode: "editor" | "plain" | "locked";
+  /** The Ricos description as a JSON string: the editor's seed ("" when the event has none, and until
+   *  this run's load lands — see the boot reset below). Re-based to the saved document after a save. */
+  descriptionJson: string;
+  descriptionFieldHidden: boolean;   // the plain text field (bag key `descriptionText`)
+  descriptionEditorHidden: boolean;  // the RichContentEditor (bag key `description`)
+  /** The editor gate (`EditorGate` in _shared/owner-editor-value.ts): edited since load/save, and
+   *  hidden until this run's load lands. */
+  descriptionDirty: boolean;
+  descriptionPending: boolean;
+  /** Derived from the mode: "locked" shows the preview + `descriptionNote`, and refuses an edit. */
   descriptionProtected: boolean;
   descriptionEditable: boolean;
   descriptionNote: string;
@@ -99,9 +112,14 @@ function navInputId(): string {
   return typeof input?.id === "string" ? input.id : "";
 }
 
+/** What every load that publishes a description resets: the editor may show it, nothing is edited yet. */
+const DESCRIPTION_LOADED = { descriptionPending: false, descriptionDirty: false } as const;
+const docJson = (doc: unknown): string => (doc ? JSON.stringify(doc) : "");
+
 function shape(s: Partial<EventFormState>): EventFormState {
   const id = typeof s.id === "string" ? s.id : "";
   const savedId = typeof s.savedId === "string" ? s.savedId : id;
+  const mode = s.descriptionMode ?? "editor";
   return {
     mode: "edit",
     id,
@@ -109,9 +127,15 @@ function shape(s: Partial<EventFormState>): EventFormState {
     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.") : "",
+    descriptionMode: mode,
+    descriptionJson: s.descriptionJson ?? "",
+    descriptionFieldHidden: mode !== "plain",
+    descriptionEditorHidden: mode !== "editor",
+    descriptionDirty: s.descriptionDirty ?? false,
+    descriptionPending: s.descriptionPending ?? false,
+    descriptionProtected: mode === "locked",
+    descriptionEditable: mode !== "locked",
+    descriptionNote: mode === "locked" ? 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",
@@ -137,11 +161,18 @@ function demoRefusal(s: Parameters<typeof shape>[0]): ReturnType<typeof shape> {
   return shape({ ...s, ...demoRefusalPatch(copyParam("ownerCommon.demoSaveNote", DEMO_SAVE_NOTE)) });
 }
 
+// The RichContentEditor's image tool (the editor's upload contract). The component picks and PUTs
+// the bytes; this service mints the signed Wix Media URL with the worker's own wixApi, so no token
+// reaches the page. Registered BEFORE the form's service on purpose: the worker test harnesses treat a
+// bundle's LAST defineService as its service.
+ricosUploadService("himiOwnerLiteEventFormUploads");
+
 const svc = defineService<EventFormState, {
   load: (s: EventFormState, arg?: unknown) => Promise<EventFormState>;
+  descriptionChanged: (s: EventFormState, arg?: unknown) => EventFormState;
   submit: (s: EventFormState, values?: Record<string, unknown>) => Promise<EventFormState>;
 }>("himiOwnerLiteEventForm", {
-  state: shape({ mode: startMode, id: initialInput.id ?? "" }),
+  state: shape({ mode: startMode, id: initialInput.id ?? "", descriptionPending: true }),
   actions: {
     load: async (s, arg) => {
       stashCopy(arg); // absorb the descriptor's onAppear copy-pack param
@@ -156,6 +187,7 @@ const svc = defineService<EventFormState, {
             return shape({
               ...s, mode, id, heading: copyParam("ownerEventForm.headingEdit", "Edit event"),
               title: d.title, description: d.description, when: d.dateLine, location: d.location,
+              ...DESCRIPTION_LOADED, descriptionMode: "editor", descriptionJson: docJson(plainPostBody(d.description)),
               status: "idle", error: "", savedMessage: "", demoNote: copyParam("ownerCommon.demoNote", DEMO_NOTE),
             });
           }
@@ -182,7 +214,10 @@ const svc = defineService<EventFormState, {
             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 };
+            // Edited in the RichContentEditor, seeded with the event's own document byte for byte (never
+            // re-encoded); a legacy string seeds as paragraphs, and none seeds an empty editor.
+            return { ...DESCRIPTION_LOADED, description: text, originalDescription: text, descriptionMode: "editor" as const,
+              descriptionJson: doc ? JSON.stringify(raw) : text ? docJson(plainPostBody(text)) : "" };
           })(),
           when: row.dateLine || "—",
           location: row.location || "—",
@@ -198,8 +233,11 @@ 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",
+            originalDescription: String(cached.description ?? ""), ...DESCRIPTION_LOADED,
+            // A row cached with its document reopens in the editor. An older row has none, so its verdict
+            // decides: plain when it was plain, else locked (it carries no verdict either: fail closed).
+            ...(cached.descriptionJson ? { descriptionMode: "editor" as const, descriptionJson: String(cached.descriptionJson) }
+              : { descriptionMode: cached.descriptionProtected === "false" ? "plain" as const : "locked" as const, descriptionJson: "" }),
             when: String(cached.when ?? cached.dateLine ?? "—"),
             location: String(cached.location ?? "—"),
             status: "idle", error: "", savedMessage: "",
@@ -211,6 +249,7 @@ const svc = defineService<EventFormState, {
             return shape({
               ...s, mode, id, heading: copyParam("ownerEventForm.headingEdit", "Edit event"),
               title: d.title, description: d.description, when: d.dateLine, location: d.location,
+              ...DESCRIPTION_LOADED, descriptionMode: "editor", descriptionJson: docJson(plainPostBody(d.description)),
               status: "idle", error: "", savedMessage: "", demoNote: copyParam("ownerCommon.demoNote", DEMO_NOTE),
             });
           }
@@ -218,59 +257,83 @@ const svc = defineService<EventFormState, {
         return shape({ ...s, mode, id, status: "error", error: ownerLoadError(e) });
       }
     },
+    // The editor's on_change carries `args.dirty` only; the document stays in the form bag.
+    descriptionChanged: (s) => shape({ ...s, descriptionDirty: true, ...editorChanged(s) }),
     submit: async (s, values) => {
       if (isOwnerPreviewDemo() || s.demoNote) return demoRefusal(s);
       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.") });
+      // The description, per record mode. A queue replay boots a FRESH worker and says so with
+      // `descriptionEdited`: this bundle's editor items add the document as `descriptionJson`; the
+      // plain items (and the pre-editor bundle's) carry plain text only.
+      const replay = typeof v.descriptionEdited === "string";
+      let doc: { nodes: unknown[] } | null = null;   // the Ricos description to WRITE; null leaves it as it is
+      let docRaw = "";                               // the editor's own string (queue item, re-seed, cache)
+      let tooLarge = false;
+      if (replay) {
+        const queued = queuedDocument(v.descriptionJson);
+        // A queued document that no longer reads (or is past the limits) writes NOTHING, and says so.
+        if (queued.kind === "invalid" || queued.kind === "too_large") return shape({ ...s, status: "error", savedMessage: "", error: copyParam("ownerEventForm.queuedDescriptionError", "The description saved offline could not be read, so nothing was written. Edit it again.") });
+        if (queued.kind === "doc") { doc = queued.doc as { nodes: unknown[] }; docRaw = queued.json; }
+        else if (v.descriptionEdited === "true") { const t = String(v.description ?? "").trim(); doc = t ? plainPostBody(t) as { nodes: unknown[] } : { nodes: [] }; }
+      } else if (s.descriptionMode === "editor") {
+        // Only an edit the editor reported counts (EditorGate). Absent (the editor never became ready):
+        // save the rest and leave the description as it is.
+        const ev = editorSubmitValue(v.description, s.descriptionJson, { pending: s.descriptionPending, dirty: s.descriptionDirty });
+        if (ev.kind === "invalid") return shape({ ...s, status: "error", savedMessage: "", error: copyParam("ownerEventForm.editorReadError", "Couldn’t read the description from the editor. Nothing was saved; try again.") });
+        if (ev.kind === "doc") { doc = ev.doc as { nodes: unknown[] }; docRaw = ev.json; }
+        tooLarge = ev.kind === "too_large";
+      } else {
+        // Plain or locked: the plain text field, under its own bag key.
+        const t = String(v.descriptionText ?? s.description).trim();
+        if (t !== s.originalDescription.trim()) {
+          if (s.descriptionMode === "locked") 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.") });
+          doc = t ? plainPostBody(t) as { nodes: unknown[] } : { nodes: [] };
+        }
+      }
+      const description = doc ? postBodyText(doc as never) : s.description;   // the plain-text mirror
       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: the
-      // description only when edited, and always as a Ricos document (never a string).
-      // A local structural type, not WixEventWrite: templates compile against the
+      // updateEvent(id, event) wraps the body as { event } internally, so pass the event fields
+      // directly. Only what the owner edited is written, the description 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: [] } } : {}),
-      };
+      const event: { title: string; description?: { nodes: unknown[] } } = { title, ...(doc ? { description: doc } : {}) };
 
-      // Optimistic local write — the detail/list repaint from cache immediately.
-      const localRow: DbEntity = { id: s.id, name: title, title, description, descriptionProtected: String(s.descriptionProtected), when: s.when, location: s.location };
-      await cachePut(localRow);
+      // Optimistic local write — the detail/list repaint from cache immediately. The document the record
+      // now holds, when known, rides along so an offline reopen seeds the editor with it.
+      const loadedJson = s.descriptionMode === "editor" && !s.descriptionPending ? s.descriptionJson : "";
+      const heldJson = docRaw || (doc ? JSON.stringify(doc) : loadedJson);
+      const heldDoc = doc ?? (loadedJson ? parseRicosJson(loadedJson) : null);
+      // Plain only when KNOWN plain: a plain row, or a loaded event with no description. Before load
+      // lands nothing is known, so the row stays protected (fail closed).
+      const knownPlain = s.descriptionMode === "plain" || (s.descriptionMode === "editor" && !s.descriptionPending && s.descriptionJson === "");
+      await cachePut({ id: s.id, name: title, title, description, descriptionProtected: cachedRichVerdict(heldDoc as never, knownPlain), ...(heldJson ? { descriptionJson: heldJson } : {}), when: s.when, location: s.location });
+      const savedState = (savedMessage: string) => shape({
+        ...s, mode: "edit", id: s.id, heading: copyParam("ownerEventForm.headingEdit", "Edit event"),
+        title, description, originalDescription: doc ? description : s.originalDescription,
+        ...(docRaw ? { descriptionJson: docRaw } : {}),
+        descriptionDirty: doc ? false : s.descriptionDirty,
+        status: "saved", savedMessage, savedId: s.id,
+        error: tooLarge ? copyParam("ownerEventForm.descriptionTooLarge", "The description is too long to save, so it was left as it was. Your other changes were saved.") : "",
+      });
       try {
         await updateEvent(s.id, event);
-        return shape({
-          ...s,
-          mode: "edit",
-          id: s.id,
-          heading: copyParam("ownerEventForm.headingEdit", "Edit event"),
-          title,
-          description,
-          originalDescription: descriptionEdited ? description : s.originalDescription,
-          status: "saved",
-          error: "",
-          savedMessage: copyParam("ownerEventForm.savedMessage", "Event saved."),
-          savedId: s.id,
-        });
+        return savedState(copyParam("ownerEventForm.savedMessage", "Event saved."));
       } catch (e) {
         if (shouldQueueOwnerWrite(e)) {
           // Demo / web-preview (no owner bridge; the record came from demo sample
           // data, marked by demoNote): a queued write could never replay, so answer
           // with the demo save note instead of the real-offline write-behind.
           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, descriptionEdited: String(descriptionEdited) });
-          return shape({
-            ...s, mode: "edit", id: s.id, heading: copyParam("ownerEventForm.headingEdit", "Edit event"),
-            title, description, originalDescription: descriptionEdited ? description : s.originalDescription, status: "saved", error: "",
-            savedMessage: copyParam("ownerEventForm.savedOffline", "Saved offline — will sync when you reconnect."),
-            savedId: s.id,
-          });
+          // Real device offline: the optimistic cache row already shows; queue the write to replay
+          // (WriteQueue, idempotent) when connectivity returns. A document rides as `descriptionJson`
+          // with descriptionEdited "false", so a bundle rolled back past this change leaves the
+          // description rather than flattening it to text.
+          await queueWrite("tier5.himiOwnerLiteEventForm.submit", { id: s.id, title, description,
+            ...(docRaw ? { descriptionJson: docRaw, descriptionEdited: "false" } : { descriptionEdited: String(doc !== null) }) });
+          return savedState(copyParam("ownerEventForm.savedOffline", "Saved offline — will sync when you reconnect."));
         }
         return shape({ ...s, status: "error", error: ownerLoadError(e), savedMessage: "" });
       }
@@ -278,4 +341,7 @@ const svc = defineService<EventFormState, {
   },
 });
 
+// Adopter contract: the editor seeds once, so a cold boot must not seed it with the last run's document.
+resetHydratedEditor(svc, { json: "descriptionJson", pending: "descriptionPending", dirty: "descriptionDirty" }, true);
+
 export { svc };

package/templates/owner-lite/tier5-src/himi-owner-lite-faq-question-form/index.ts

@@ -2,17 +2,28 @@
 // otherwise spin forever and leave a create/submit permanently pending.
 import { defineService } from "@himalaya/state";
 import { createQuestionEntry, getQuestionEntry, queryCategories, queryQuestionEntries, updateQuestionEntry, type WixCategory, type WixQuestionEntry } from "@himalaya/wix-faq";
-import { postBodyText } from "../_shared/owner-post-content.js";
+import { postBodyText, plainPostBody } from "../_shared/owner-post-content.js";
 import { draftjsText } from "../_shared/owner-rich-guard.js";
+import { editorSubmitValue, isEmptyDocument, resetHydratedEditor } from "../_shared/owner-editor-value.js";
+import { parseRicosJson, type RicosDocument } from "@himalaya/wix-rich-content";
+import { ricosUploadService } from "@himalaya/wix-rich-content-editor";
 
-interface State { id: string; revision: string; mode: "create" | "edit"; heading: string; question: string; answer: string; categoryId: string; statusValue: "VISIBLE" | "HIDDEN"; categoryOptions: Array<{id:string;label:string}>; error: string; conflict: boolean; noConflict: boolean; savedMessage: string; savedId: string; answerFormat: "plain" | "rich" | "draftjs"; answerProtected: boolean; answerEditable: boolean; answerNote: string; }
+interface State { id: string; revision: string; mode: "create" | "edit"; heading: string; question: string; answer: string; categoryId: string; statusValue: "VISIBLE" | "HIDDEN"; categoryOptions: Array<{id:string;label:string}>; error: string; conflict: boolean; noConflict: boolean; savedMessage: string; savedId: string; answerFormat: "plain" | "rich" | "draftjs"; answerProtected: boolean; answerEditable: boolean; answerNote: string;
+ /** [rico] #3373 — how the answer is edited: "editor" (an existing Ricos or plain answer, in the RichContentEditor),
+  *  "plain" (a new question's text field, bag key `answerText`), "locked" (a legacy DraftJS answer, #2134). */
+ answerMode: "editor" | "plain" | "locked";
+ /** The editor's seed: the answer as a Ricos JSON string ("" until this run's load lands; see the boot reset). */
+ answerJson: string; answerFieldHidden: boolean; answerEditorHidden: boolean;
+ /** The editor gate (`EditorGate` in _shared/owner-editor-value.ts): edited since load/save; hidden until load lands. */
+ answerDirty: boolean; answerPending: boolean; }
 const input = ((globalThis as { himalaya?: { input?: { id?: string } } }).himalaya?.input) ?? {};
 const msg = (e: unknown) => String((e as { message?: unknown })?.message ?? e);
 const isConflict = (e: unknown) => /\b409\b|conflict|revision/i.test(msg(e));
 const offline = (e: unknown) => /offline|network|connect|bridge|fetch/i.test(msg(e));
-// [rico] #3363 — the answer is a one-of (draftjs | richContent | plainText) and this form edits plainText
-// only. A rich or DraftJS answer loads LOCKED: `answer` holds its read-only preview, the required check
-// is skipped, and plainText stays out of the PATCH and its fieldMask. #3373 replaces the lock with the editor.
+// [rico] #3363 — the answer is a one-of (draftjs | richContent | plainText). [rico] #3373 — an existing Ricos
+// or plain answer is edited in the RichContentEditor and written as `richContent` once edited (a plain answer
+// becomes Ricos, #2134). A legacy DraftJS answer loads LOCKED: `answer` holds its read-only preview, the
+// required check is skipped, and the answer stays out of the PATCH and its fieldMask.
 const RICH_ANSWER_NOTE = "This answer has formatting or media. Edit it in your site dashboard to keep that content intact; the question, category and visibility can be changed here.";
 const RICH_ANSWER_ERROR = "This answer has formatting or media. Edit it in your site dashboard to keep that content intact.";
 // A locked answer whose only content is media/embeds has no preview text. `answer` is also the
@@ -23,8 +34,64 @@ const answerOf = (q: WixQuestionEntry): { answerFormat: State["answerFormat"]; a
   : q.draftjs ? { answerFormat: "draftjs", answer: draftjsText(q.draftjs) || MEDIA_ONLY_ANSWER } : { answerFormat: "plain", answer: q.plainText ?? "" };
 async function categories(): Promise<WixCategory[]> { const out: WixCategory[]=[]; let cursor=""; const seen=new Set<string>(); do { const r=await queryCategories({query:{cursorPaging:{limit:100,...(cursor?{cursor}:{})},sort:[{fieldName:"sortOrder",order:"ASC"}]}}); out.push(...(r.categories??[])); const next=r.pagingMetadata?.cursors?.next??"";if(!next||seen.has(next))break;seen.add(next);cursor=next; } while(cursor); return out; }
 async function appendOrder(): Promise<number> { let max=-1,cursor=""; const seen=new Set<string>(); do { const r=await queryQuestionEntries({contentFormat:"PLAIN_TEXT",query:{cursorPaging:{limit:100,...(cursor?{cursor}:{})}}}); for(const q of r.questionEntries??[]) max=Math.max(max,q.sortOrder??-1); const next=r.pagingMetadata?.cursors?.next??"";if(!next||seen.has(next))break;seen.add(next);cursor=next; } while(cursor); return max+1; }
-const shape=(s:Partial<State>):State=>({ id:s.id??input.id??"", revision:s.revision??"", mode:s.mode??((s.id??input.id)?"edit":"create"), heading:s.heading??((s.id??input.id)?"Edit question":"New question"), question:s.question??"", answer:s.answer??"", categoryId:s.categoryId??"", statusValue:s.statusValue??"HIDDEN", categoryOptions:s.categoryOptions??[], error:s.error??"", conflict:s.conflict??false, noConflict:!(s.conflict??false), savedMessage:s.savedMessage??"", savedId:s.savedId??"", ...(() => { const f = s.answerFormat ?? "plain"; return { answerFormat: f, answerProtected: f !== "plain", answerEditable: f === "plain", answerNote: f !== "plain" ? RICH_ANSWER_NOTE : "" }; })() });
-const svc=defineService<State,{load:(s:State,a?:unknown)=>Promise<State>;submit:(s:State,v?:Record<string,unknown>)=>Promise<State>}>("himiOwnerLiteFaqQuestionForm",{state:shape({}),actions:{
- load:async(s,a)=>{const id=input.id||String((a as {id?:unknown})?.id??s.id);try{const cats=await categories();const options=cats.map(c=>({id:c.id??"",label:c.title?.trim()||"Untitled category"}));if(!id)return shape({...s,mode:"create",categoryOptions:options,statusValue:"HIDDEN"});const q=(await getQuestionEntry(id)).questionEntry;if(!q) return shape({...s,id,error:"Question not found",categoryOptions:options});return shape({...s,id,revision:q.revision??"",mode:"edit",heading:"Edit question",question:q.question??"",...answerOf(q),categoryId:q.categoryId??"",statusValue:q.status==="VISIBLE"?"VISIBLE":"HIDDEN",categoryOptions:options,error:"",conflict:false});}catch(e){return shape({...s,id,error:offline(e)?"Connect to the internet to load this question.":msg(e)});}},
- submit:async(s,v)=>{const question=String(v?.question??s.question).trim(),answer=String(v?.answer??s.answer).trim(),categoryId=String(v?.categoryId??s.categoryId),statusValue=String(v?.status??s.statusValue)==="VISIBLE"?"VISIBLE":"HIDDEN";const locked=s.mode==="edit"&&s.answerProtected;if(locked&&answer!==s.answer.trim())return shape({...s,error:RICH_ANSWER_ERROR,savedMessage:""});if(!question||(!locked&&!answer))return shape({...s,error:"Question and answer are required.",savedMessage:""});try{if(s.mode==="edit"){if(!s.revision)return shape({...s,error:"Refresh before saving; this question has no current revision.",conflict:true});const r=await updateQuestionEntry(s.id,{questionEntry:locked?{id:s.id,revision:s.revision,question,categoryId,status:statusValue}:{id:s.id,revision:s.revision,question,plainText:answer,categoryId,status:statusValue},fieldMask:locked?["question","categoryId","status"]:["question","plainText","categoryId","status"]});return shape({...s,revision:r.questionEntry?.revision??s.revision,question,answer:locked?s.answer:answer,categoryId,statusValue,error:"",conflict:false,savedMessage:"Question saved.",savedId:s.id});}const r=await createQuestionEntry({questionEntry:{question,plainText:answer,categoryId,status:statusValue,sortOrder:await appendOrder()}});return shape({...s,id:r.questionEntry?.id??"",revision:r.questionEntry?.revision??"",mode:"edit",heading:"Edit question",question,answer,categoryId,statusValue,error:"",savedMessage:"Question created.",savedId:r.questionEntry?.id??""});}catch(e){if(isConflict(e))return shape({...s,error:"This question changed elsewhere. Refresh before saving again.",conflict:true,savedMessage:""});return shape({...s,error:offline(e)?"Connect to the internet and try again. This change was not queued.":msg(e),savedMessage:""});}}
-}}); export {svc,appendOrder};
+const ANSWER_LOADED={answerPending:false,answerDirty:false} as const;
+const shape=(s:Partial<State>):State=>({ id:s.id??input.id??"", revision:s.revision??"", mode:s.mode??((s.id??input.id)?"edit":"create"), heading:s.heading??((s.id??input.id)?"Edit question":"New question"), question:s.question??"", answer:s.answer??"", categoryId:s.categoryId??"", statusValue:s.statusValue??"HIDDEN", categoryOptions:s.categoryOptions??[], error:s.error??"", conflict:s.conflict??false, noConflict:!(s.conflict??false), savedMessage:s.savedMessage??"", savedId:s.savedId??"", ...(() => { const f = s.answerFormat ?? "plain";
+  const editing = (s.mode ?? ((s.id ?? input.id) ? "edit" : "create")) === "edit";
+  const mode = s.answerMode ?? (f === "draftjs" ? "locked" : editing ? "editor" : "plain");
+  return { answerFormat: f, answerMode: mode, answerJson: s.answerJson ?? "", answerFieldHidden: mode !== "plain", answerEditorHidden: mode !== "editor",
+   answerDirty: s.answerDirty ?? false, answerPending: s.answerPending ?? false,
+   answerProtected: mode === "locked", answerEditable: mode !== "locked", answerNote: mode === "locked" ? RICH_ANSWER_NOTE : "" }; })() });
+// The RichContentEditor's image tool: this service mints the signed Wix Media URL with the worker's own wixApi.
+// Registered BEFORE the form's service: the worker test harnesses treat a bundle's LAST defineService as its service.
+ricosUploadService("himiOwnerLiteFaqQuestionFormUploads");
+const svc=defineService<State,{load:(s:State,a?:unknown)=>Promise<State>;answerChanged:(s:State,a?:unknown)=>State;submit:(s:State,v?:Record<string,unknown>)=>Promise<State>}>("himiOwnerLiteFaqQuestionForm",{state:shape({answerPending:!!input.id}),actions:{
+ load:async(s,a)=>{const id=input.id||String((a as {id?:unknown})?.id??s.id);try{const cats=await categories();const options=cats.map(c=>({id:c.id??"",label:c.title?.trim()||"Untitled category"}));if(!id)return shape({...s,...ANSWER_LOADED,mode:"create",answerMode:"plain",answerJson:"",categoryOptions:options,statusValue:"HIDDEN"});const q=(await getQuestionEntry(id)).questionEntry;if(!q) return shape({...s,id,error:"Question not found",categoryOptions:options});return shape({...s,id,revision:q.revision??"",mode:"edit",heading:"Edit question",question:q.question??"",...((a)=>({...a,...ANSWER_LOADED,answerMode:a.answerFormat==="draftjs"?"locked" as const:"editor" as const,
+  // The seed is the stored document byte for byte (never re-encoded); a plain answer seeds as paragraphs.
+  answerJson:a.answerFormat==="draftjs"?"":q.richContent?JSON.stringify(q.richContent):q.plainText?JSON.stringify(plainPostBody(q.plainText)):""}))(answerOf(q)),categoryId:q.categoryId??"",statusValue:q.status==="VISIBLE"?"VISIBLE":"HIDDEN",categoryOptions:options,error:"",conflict:false});}catch(e){return shape({...s,id,error:offline(e)?"Connect to the internet to load this question.":msg(e)});}},
+ // The editor's on_change carries `args.dirty` only; the document stays in the form bag.
+ // Any on_change after a save is an edit that save did not write (every arm fires the pending on_change
+ // before releasing a submit), so the confirmation goes.
+ answerChanged:(s)=>shape({...s,answerDirty:true,savedMessage:""}),
+ submit:async(s,v)=>{
+  const question=String(v?.question??s.question).trim(),categoryId=String(v?.categoryId??s.categoryId),statusValue=String(v?.status??s.statusValue)==="VISIBLE"?"VISIBLE":"HIDDEN";
+  const editing=s.mode==="edit";
+  // The answer, per mode. Editor: `values.answer` is the RichContentEditor's document, or absent (the editor
+  // never became ready: the answer is left untouched). Only an edit the editor reported counts. Plain / locked:
+  // the plain field, under its own bag key `answerText`.
+  let doc:RicosDocument|null=null,docRaw="",answer=s.answer,tooLarge=false;
+  if(editing&&s.answerMode==="editor"){
+    const ev=editorSubmitValue(v?.answer,s.answerJson,{pending:s.answerPending,dirty:s.answerDirty});
+    if(ev.kind==="invalid")return shape({...s,error:"Couldn’t read the answer from the editor. Nothing was saved; try again.",savedMessage:""});
+    if(ev.kind==="doc"){doc=ev.doc;docRaw=ev.json;answer=postBodyText(ev.doc as never);}
+    tooLarge=ev.kind==="too_large";
+    // Required, enforced HERE: native Save does not gate on the RichContentEditor. An untouched editor keeps
+    // the stored answer, so it must have one: an empty plain answer, or a Ricos one with no text and no
+    // media, does not.
+    const stored=s.answerJson?parseRicosJson(s.answerJson):null;
+    const keptEmpty=!doc&&(s.answerFormat==="plain"?!s.answer.trim():!stored||isEmptyDocument(stored));
+    if(!question||(doc&&isEmptyDocument(doc))||keptEmpty)return shape({...s,error:"Question and answer are required.",savedMessage:""});
+  }else{
+    answer=String(v?.answerText??s.answer).trim();
+    const locked=editing&&s.answerMode==="locked";
+    if(locked&&answer!==s.answer.trim())return shape({...s,error:RICH_ANSWER_ERROR,savedMessage:""});
+    if(!question||(!locked&&!answer))return shape({...s,error:"Question and answer are required.",savedMessage:""});
+  }
+  try{
+    if(editing){
+      if(!s.revision)return shape({...s,error:"Refresh before saving; this question has no current revision.",conflict:true});
+      const plainEdit=s.answerMode==="plain";
+      const questionEntry={id:s.id,revision:s.revision,question,categoryId,status:statusValue,...(doc?{richContent:doc as never}:plainEdit?{plainText:answer}:{})};
+      const fieldMask=["question",...(doc?["richContent"]:plainEdit?["plainText"]:[]),"categoryId","status"];
+      const r=await updateQuestionEntry(s.id,{questionEntry,fieldMask});
+      return shape({...s,revision:r.questionEntry?.revision??s.revision,question,answer,...(doc?{answerFormat:"rich" as const,answerJson:docRaw}:{}),
+        answerDirty:doc?false:s.answerDirty,categoryId,statusValue,conflict:false,savedMessage:"Question saved.",savedId:s.id,
+        error:tooLarge?"The answer is too long to save, so it was left as it was. Your other changes were saved.":""});
+    }
+    const r=await createQuestionEntry({questionEntry:{question,plainText:answer,categoryId,status:statusValue,sortOrder:await appendOrder()}});
+    return shape({...s,id:r.questionEntry?.id??"",revision:r.questionEntry?.revision??"",mode:"edit",heading:"Edit question",question,answer,categoryId,statusValue,error:"",savedMessage:"Question created.",savedId:r.questionEntry?.id??""});
+  }catch(e){if(isConflict(e))return shape({...s,error:"This question changed elsewhere. Refresh before saving again.",conflict:true,savedMessage:""});return shape({...s,error:offline(e)?"Connect to the internet and try again. This change was not queued.":msg(e),savedMessage:""});}
+ }
+}});
+// Adopter contract: the editor seeds once, so a cold boot must not seed it with the last run's document.
+resetHydratedEditor(svc,{json:"answerJson",pending:"answerPending",dirty:"answerDirty"},!!input.id);
+export {svc,appendOrder};