@agent-native/core 0.90.1 → 0.90.2

package/corpus/templates/content/actions/update-document.ts

@@ -75,6 +75,30 @@ function normalizedBuilderBodyProse(content: string | null | undefined) {
     .trim();
 }
 
+export function isEffectivelyEmptyDocumentContent(
+  content: string | null | undefined,
+) {
+  const normalized = (content ?? "").trim();
+  return normalized === "" || normalized === "<empty-block/>";
+}
+
+export function shouldRejectStaleEmptyBodySave(args: {
+  incomingContent: string | null | undefined;
+  currentContent: string | null | undefined;
+  loadedUpdatedAt: string | null | undefined;
+  currentUpdatedAt: string | null | undefined;
+  loadedContentWasEmpty?: boolean | null | undefined;
+}) {
+  if (!args.loadedUpdatedAt || !args.currentUpdatedAt) return false;
+  if (!isEffectivelyEmptyDocumentContent(args.incomingContent)) return false;
+  if (isEffectivelyEmptyDocumentContent(args.currentContent)) return false;
+  if (args.loadedContentWasEmpty === true) return true;
+  return (
+    new Date(args.currentUpdatedAt).getTime() >
+    new Date(args.loadedUpdatedAt).getTime()
+  );
+}
+
 /**
  * Best-effort quote of the first changed span between two document bodies, used
  * as the `{ kind: "text", quote }` descriptor so the recent-edit highlight lands
@@ -133,6 +157,14 @@ export default defineAction({
       .boolean()
       .optional()
       .describe("Favorite status (true/false)"),
+    loadedUpdatedAt: z
+      .string()
+      .optional()
+      .describe("Document updatedAt value the client loaded before editing"),
+    loadedContentWasEmpty: z
+      .boolean()
+      .optional()
+      .describe("Whether the client-loaded content snapshot was empty"),
     // Optional optimistic-concurrency guard for content saves: the
     // `updatedAt` of the document snapshot the caller last loaded/reconciled.
     // When provided alongside `content`, the write is a compare-and-swap on
@@ -229,6 +261,17 @@ export default defineAction({
           content = existing.content;
         }
       }
+      if (
+        shouldRejectStaleEmptyBodySave({
+          incomingContent: content,
+          currentContent: existing.content,
+          loadedUpdatedAt: args.loadedUpdatedAt,
+          currentUpdatedAt: existing.updatedAt,
+          loadedContentWasEmpty: args.loadedContentWasEmpty,
+        })
+      ) {
+        content = existing.content;
+      }
     }
 
     // Detect actual changes — a no-op call (e.g. the editor echoing back the

package/corpus/templates/content/app/components/editor/BuilderBodySyncingNotice.tsx

@@ -0,0 +1,21 @@
+import { IconLoader2 } from "@tabler/icons-react";
+
+export function BuilderBodySyncingNotice({
+  title,
+  description,
+}: {
+  title: string;
+  description: string;
+}) {
+  return (
+    <div className="rounded-lg border border-dashed border-border bg-muted/35 px-4 py-5 text-sm">
+      <div className="flex items-center gap-2 font-medium text-foreground">
+        <IconLoader2 className="size-4 animate-spin text-muted-foreground" />
+        {title}
+      </div>
+      <p className="mt-2 max-w-2xl leading-6 text-muted-foreground">
+        {description}
+      </p>
+    </div>
+  );
+}

package/corpus/templates/content/app/components/editor/DocumentDatabase.tsx

@@ -18,7 +18,6 @@ export function DocumentDatabase({ document, canEdit }: DocumentDatabaseProps) {
       databaseId={databaseId}
       databaseDocumentId={document.id}
       canEdit={canEdit}
-      documentOverride={document}
     />
   );
 }

package/corpus/templates/content/app/components/editor/DocumentEditor.tsx

@@ -11,7 +11,7 @@ import {
   type CollabUser,
 } from "@agent-native/core/client";
 import type { Document, DocumentSyncStatus } from "@shared/api";
-import { IconArrowLeft, IconDatabase } from "@tabler/icons-react";
+import { IconArrowLeft, IconDatabase, IconLoader2 } from "@tabler/icons-react";
 import { IconLock } from "@tabler/icons-react";
 import { useQueryClient } from "@tanstack/react-query";
 import {
@@ -54,6 +54,11 @@ import {
 } from "@/lib/local-content-source-files";
 import { cn } from "@/lib/utils";
 
+import {
+  documentBodyHydrationIsPending,
+  isEffectivelyEmptyDocumentContent,
+} from "./body-hydration";
+import { BuilderBodySyncingNotice } from "./BuilderBodySyncingNotice";
 import type { CommentTextAnchor } from "./comment-anchors";
 import { CommentsSidebar } from "./CommentsSidebar";
 import { DocumentBlockFields } from "./DocumentBlockFields";
@@ -309,7 +314,6 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
   );
   const canEdit = document.canEdit ?? true;
   const canEditRef = useRef(canEdit);
-  canEditRef.current = canEdit;
   // The block render context (asset/upload resolvers, inline markdown reader,
   // panel popover) is stable for the editor's lifetime. Created once here and
   // provided alongside the content block registry so every registry block in the
@@ -468,6 +472,10 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
     requestSource: TAB_ID,
     user: currentUser,
   });
+  const bodyHydrationPending = documentBodyHydrationIsPending(document);
+  const editorCanEdit =
+    canEdit && !bodyHydrationPending && (isLocalFileDocument || !collabLoading);
+  canEditRef.current = editorCanEdit;
 
   // Initialize from fetched document, reset on document switch
   useEffect(() => {
@@ -601,7 +609,14 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
     const serverContent = document.content;
     const lastSaved = lastSavedContentRef.current;
     if (serverContent === lastSaved.content) return;
-    const adopt = localContent === lastSaved.content || contentExternalIsNewer;
+    const staleEmptyLocalOverFreshServer =
+      isEffectivelyEmptyDocumentContent(lastSaved.content) &&
+      isEffectivelyEmptyDocumentContent(localContent) &&
+      !isEffectivelyEmptyDocumentContent(serverContent);
+    const adopt =
+      localContent === lastSaved.content ||
+      contentExternalIsNewer ||
+      staleEmptyLocalOverFreshServer;
     if (adopt) {
       if (saveTimeoutRef.current) {
         clearTimeout(saveTimeoutRef.current);
@@ -701,6 +716,13 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
             : undefined;
         return await updateDocument.mutateAsync({
           id: documentId,
+          loadedUpdatedAt: documentUpdatedAtRef.current ?? undefined,
+          loadedContentWasEmpty:
+            updates.content !== undefined
+              ? isEffectivelyEmptyDocumentContent(
+                  lastSavedContentRef.current.content,
+                )
+              : undefined,
           ...updates,
           ...(baseUpdatedAt !== undefined ? { baseUpdatedAt } : {}),
         });
@@ -997,7 +1019,7 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
   // key we force an immediate (non-debounced) save of the current editor
   // state, then delete the key so `pull-document` knows the flush landed.
   useEffect(() => {
-    if (!canEdit || isLocalFileDocument) return;
+    if (!editorCanEdit || isLocalFileDocument) return;
     let active = true;
     const flushKey = `flush-request-${documentId}`;
     const flushPath = agentNativePath(
@@ -1060,29 +1082,29 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
       active = false;
       clearTimeout(timer);
     };
-  }, [canEdit, documentId, isLocalFileDocument, persistDocumentUpdates]);
+  }, [documentId, editorCanEdit, isLocalFileDocument, persistDocumentUpdates]);
 
   const handleTitleChange = useCallback(
     (newTitle: string) => {
-      if (!canEdit) return;
+      if (!editorCanEdit) return;
       setLocalTitle(newTitle);
       debouncedSave(newTitle, localContentRef.current);
     },
-    [canEdit, debouncedSave],
+    [debouncedSave, editorCanEdit],
   );
 
   const handleContentChange = useCallback(
     (newContent: string) => {
-      if (!canEdit) return;
+      if (!editorCanEdit) return;
       setLocalContent(newContent);
       debouncedSave(localTitleRef.current, newContent);
     },
-    [canEdit, debouncedSave],
+    [debouncedSave, editorCanEdit],
   );
 
   const handleContentSaveNow = useCallback(
     async (newContent: string) => {
-      if (!canEdit) return false;
+      if (!editorCanEdit) return false;
       if (saveTimeoutRef.current) {
         clearTimeout(saveTimeoutRef.current);
         saveTimeoutRef.current = null;
@@ -1096,7 +1118,7 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
       );
       return result.contentPersisted;
     },
-    [canEdit, saveDocumentImmediately],
+    [editorCanEdit, saveDocumentImmediately],
   );
 
   // Comments state — pending comment from text selection
@@ -1114,11 +1136,12 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
   );
   const hasComments =
     !isLocalFileDocument &&
-    canEdit &&
+    editorCanEdit &&
     ((threads?.length ?? 0) > 0 || !!pendingComment);
   const hasCommentRailSpace = useMinViewportWidth(1024);
   const showDesktopComments = hasComments && hasCommentRailSpace;
-  const showCommentsSheet = hasComments && canEdit && !showDesktopComments;
+  const showCommentsSheet =
+    hasComments && editorCanEdit && !showDesktopComments;
 
   const handleComment = useCallback(
     (
@@ -1175,7 +1198,7 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
 
   const handleTitlePaste = useCallback(
     (event: ClipboardEvent<HTMLTextAreaElement>) => {
-      if (!canEdit) return;
+      if (!editorCanEdit) return;
 
       const pastedText = event.clipboardData.getData("text/plain");
       if (!pastedText) return;
@@ -1196,12 +1219,12 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
         titleInputRef.current?.setSelectionRange(nextCaret, nextCaret);
       });
     },
-    [canEdit, handleTitleChange, localTitle],
+    [editorCanEdit, handleTitleChange, localTitle],
   );
 
   // Auto-focus title on new empty documents once collab finishes loading
   useEffect(() => {
-    if (canEdit && !collabLoading && shouldFocusTitleRef.current) {
+    if (editorCanEdit && shouldFocusTitleRef.current) {
       shouldFocusTitleRef.current = false;
       requestAnimationFrame(() => titleInputRef.current?.focus());
     }
@@ -1212,10 +1235,6 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
     [document, documents],
   );
 
-  if (!isLocalFileDocument && collabLoading) {
-    return <DocumentEditorSkeleton />;
-  }
-
   const sidebar = (
     <CommentsSidebar
       documentId={documentId}
@@ -1315,7 +1334,7 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
                   />
                   {document.icon || !isDatabasePage ? (
                     <div className="mb-1">
-                      {canEdit ? (
+                      {editorCanEdit ? (
                         <EmojiPicker
                           icon={document.icon}
                           defaultIcon={defaultIcon}
@@ -1376,6 +1395,7 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
                       titleFocusedRef.current = false;
                     }}
                     onKeyDown={(e) => {
+                      if (!editorCanEdit) return;
                       if (e.key === "Enter") {
                         e.preventDefault();
                         const pm = window.document.querySelector(
@@ -1386,7 +1406,7 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
                     }}
                     aria-label={t("editor.documentTitle")}
                     placeholder={t("editor.title")}
-                    readOnly={!canEdit}
+                    readOnly={!editorCanEdit}
                     style={{ fieldSizing: "content" } as any}
                     className={cn(
                       "block w-full resize-none overflow-hidden break-words border-none bg-transparent p-0 font-bold leading-tight text-foreground outline-none placeholder:text-muted-foreground/40",
@@ -1396,7 +1416,7 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
                   {document.databaseMembership && !isLocalFileDocument ? (
                     <DocumentProperties
                       documentId={documentId}
-                      canEdit={canEdit}
+                      canEdit={editorCanEdit}
                     />
                   ) : null}
                 </div>
@@ -1418,6 +1438,17 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
                   }}
                 >
                   {(() => {
+                    if (bodyHydrationPending) {
+                      return (
+                        <BuilderBodySyncingNotice
+                          title={t("editor.builderBodySyncing")}
+                          description={t(
+                            "editor.builderBodySyncingDescription",
+                          )}
+                        />
+                      );
+                    }
+
                     // The primary "Content" Blocks field IS the document body,
                     // with the full collaborative editor. It renders chromeless
                     // when it's the only Blocks field, or inside a
@@ -1425,7 +1456,7 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
                     // fields.
                     const primaryEditor = (
                       <VisualEditor
-                        key={documentId}
+                        key={`${documentId}:${editorCanEdit && !isLocalFileDocument ? "live" : "snapshot"}`}
                         documentId={documentId}
                         content={
                           isLocalFileDocument ? localContent : document.content
@@ -1445,13 +1476,13 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
                         collabSynced={collabEnabled ? collabSynced : true}
                         awareness={collabEnabled ? awareness : null}
                         user={currentUser}
-                        editable={canEdit}
+                        editable={editorCanEdit}
                         localFileMode={isLocalFileDocument}
                         localFilePath={
                           isLocalFileDocument ? document.source?.path : null
                         }
                         onComment={
-                          canEdit && !isLocalFileDocument
+                          editorCanEdit && !isLocalFileDocument
                             ? handleComment
                             : undefined
                         }
@@ -1459,7 +1490,7 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
                         activeThreadId={activeThreadId}
                         pendingHighlight={pendingComment?.range ?? null}
                         onActivateThread={
-                          canEdit && !isLocalFileDocument
+                          editorCanEdit && !isLocalFileDocument
                             ? setSelectedThreadId
                             : undefined
                         }
@@ -1476,7 +1507,7 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
                       return (
                         <DocumentBlockFields
                           documentId={documentId}
-                          canEdit={canEdit}
+                          canEdit={editorCanEdit}
                           primaryEditor={primaryEditor}
                         />
                       );
@@ -1484,6 +1515,17 @@ function DocumentEditorBody({ documentId, document }: DocumentEditorBodyProps) {
 
                     return primaryEditor;
                   })()}
+                  {!bodyHydrationPending &&
+                  !isLocalFileDocument &&
+                  collabLoading ? (
+                    <div
+                      className="mt-4 inline-flex items-center gap-2 rounded-md border border-border bg-muted/40 px-3 py-2 text-xs text-muted-foreground"
+                      role="status"
+                    >
+                      <IconLoader2 className="size-3.5 animate-spin" />
+                      {t("editor.collabConnectingReadOnly")}
+                    </div>
+                  ) : null}
                 </div>
               </div>
 

package/corpus/templates/content/app/components/editor/DocumentProperties.tsx

@@ -2621,6 +2621,17 @@ export function AddProperty({
     }))
     .filter((group) => group.fields.length > 0);
   const addPropertySearchInputRef = useRef<HTMLInputElement>(null);
+  const [pendingPropertyType, setPendingPropertyType] =
+    useState<DocumentPropertyType | null>(null);
+  const [pendingSourceFieldId, setPendingSourceFieldId] = useState<
+    string | null
+  >(null);
+  const [addPropertyError, setAddPropertyError] = useState<string | null>(null);
+  const isAddingProperty =
+    configure.isPending ||
+    addSourceFieldProperty.isPending ||
+    pendingPropertyType !== null ||
+    pendingSourceFieldId !== null;
 
   useEffect(() => {
     if (!open) return;
@@ -2632,27 +2643,49 @@ export function AddProperty({
   }, [open]);
 
   function closeAddPropertyPicker() {
+    if (isAddingProperty) return;
     setTypeQuery("");
+    setAddPropertyError(null);
     setOpen(false);
   }
 
   async function add(type: DocumentPropertyType) {
     const label = t(`editor.propertyTypes.${type}`);
-    await configure.mutateAsync({
-      documentId,
-      name: label,
-      type,
-      options: defaultPropertyOptions(type),
-    });
-    closeAddPropertyPicker();
+    setPendingPropertyType(type);
+    setPendingSourceFieldId(null);
+    setAddPropertyError(null);
+    try {
+      await configure.mutateAsync({
+        documentId,
+        name: label,
+        type,
+        options: defaultPropertyOptions(type),
+      });
+      setTypeQuery("");
+      setOpen(false);
+    } catch (error) {
+      setAddPropertyError(error instanceof Error ? error.message : "");
+    } finally {
+      setPendingPropertyType(null);
+    }
   }
 
   async function addFromSourceField(sourceFieldId: string) {
-    await addSourceFieldProperty.mutateAsync({
-      documentId,
-      sourceFieldId,
-    });
-    closeAddPropertyPicker();
+    setPendingSourceFieldId(sourceFieldId);
+    setPendingPropertyType(null);
+    setAddPropertyError(null);
+    try {
+      await addSourceFieldProperty.mutateAsync({
+        documentId,
+        sourceFieldId,
+      });
+      setTypeQuery("");
+      setOpen(false);
+    } catch (error) {
+      setAddPropertyError(error instanceof Error ? error.message : "");
+    } finally {
+      setPendingSourceFieldId(null);
+    }
   }
 
   return (
@@ -2661,7 +2694,7 @@ export function AddProperty({
       onOpenChange={(nextOpen) => {
         if (nextOpen) {
           setOpen(true);
-        } else {
+        } else if (!isAddingProperty) {
           closeAddPropertyPicker();
         }
       }}
@@ -2729,11 +2762,16 @@ export function AddProperty({
                     aria-label={t("editor.properties.sourceField", {
                       name: field.sourceFieldLabel,
                     })}
-                    disabled={addSourceFieldProperty.isPending}
+                    disabled={isAddingProperty}
+                    aria-busy={pendingSourceFieldId === field.id}
                     className="flex w-full items-center gap-2 rounded px-2 py-1.5 text-left text-sm hover:bg-accent disabled:opacity-50"
                     onClick={() => void addFromSourceField(field.id)}
                   >
-                    <IconLink className="size-4 shrink-0 text-muted-foreground" />
+                    {pendingSourceFieldId === field.id ? (
+                      <Spinner className="size-4 shrink-0 text-muted-foreground" />
+                    ) : (
+                      <IconLink className="size-4 shrink-0 text-muted-foreground" />
+                    )}
                     <span className="min-w-0 flex-1 truncate">
                       {field.sourceFieldLabel}
                     </span>
@@ -2761,10 +2799,15 @@ export function AddProperty({
                     type: t(`editor.propertyTypes.${type}`),
                   })}
                   className="flex w-full items-center gap-2 rounded px-2 py-1.5 text-left text-sm hover:bg-accent"
-                  disabled={configure.isPending}
+                  disabled={isAddingProperty}
+                  aria-busy={pendingPropertyType === type}
                   onClick={() => void add(type)}
                 >
-                  <Icon className="size-4 text-muted-foreground" />
+                  {pendingPropertyType === type ? (
+                    <Spinner className="size-4 text-muted-foreground" />
+                  ) : (
+                    <Icon className="size-4 text-muted-foreground" />
+                  )}
                   <span className="flex-1">
                     {t(`editor.propertyTypes.${type}`)}
                   </span>
@@ -2776,6 +2819,15 @@ export function AddProperty({
                 </button>
               );
             })}
+            {addPropertyError !== null ? (
+              <div
+                role="alert"
+                className="px-2 py-1.5 text-xs text-destructive"
+              >
+                {t("editor.properties.addPropertyFailed")}
+                {addPropertyError ? ` ${addPropertyError}` : null}
+              </div>
+            ) : null}
           </div>
         </div>
       </PopoverContent>

package/corpus/templates/content/app/components/editor/VisualEditor.tsx

@@ -326,7 +326,7 @@ const JoinFirstBodyBlockToTitle = Extension.create<{
 
       const text = firstBlock.textContent.trim();
       if (!text) {
-        queueMicrotask(() => this.options.onJoinTitle?.(""));
+        setTimeout(() => this.options.onJoinTitle?.(""), 0);
         return true;
       }
 
@@ -336,7 +336,7 @@ const JoinFirstBodyBlockToTitle = Extension.create<{
           ? state.tr.replaceWith(0, firstBlock.nodeSize, paragraph.create())
           : state.tr.delete(0, firstBlock.nodeSize);
       view.dispatch(tr.scrollIntoView());
-      queueMicrotask(() => this.options.onJoinTitle?.(text));
+      setTimeout(() => this.options.onJoinTitle?.(text), 0);
       return true;
     };
 
@@ -1731,7 +1731,7 @@ export function VisualEditor({
         // clobber DB content with an empty string). `registerEmitted` records
         // this as the last-emitted value and returns false to skip the save.
         if (!guards.registerEmitted(normalized)) return true;
-        queueMicrotask(() => onChangeRef.current(normalized));
+        setTimeout(() => onChangeRef.current(normalized), 0);
         return true;
       } catch (err: any) {
         toast.error(
@@ -2172,7 +2172,7 @@ export function VisualEditor({
       ) as HTMLElement | null;
       if (!el) return;
       const id = el.getAttribute("data-comment-thread");
-      if (id) onActivateThread(id);
+      if (id) setTimeout(() => onActivateThread(id), 0);
     };
     dom.addEventListener("click", handleClick);
     return () => dom.removeEventListener("click", handleClick);

package/corpus/templates/content/app/components/editor/body-hydration.ts

@@ -0,0 +1,112 @@
+import type {
+  ContentDatabaseBodyHydration,
+  ContentDatabaseBodyHydrationSummary,
+  ContentDatabaseItem,
+  Document,
+} from "@shared/api";
+
+export function builderBodyHydrationIsPending(
+  hydration: ContentDatabaseBodyHydration | null | undefined,
+) {
+  return (
+    !!hydration &&
+    (hydration.status === "pending" || hydration.status === "hydrating")
+  );
+}
+
+export function builderBodyHydrationIsTerminalError(
+  hydration: ContentDatabaseBodyHydration | null | undefined,
+) {
+  return hydration?.status === "error";
+}
+
+export function builderBodyHydrationDisplayHydratedCount(args: {
+  summary: ContentDatabaseBodyHydrationSummary;
+  highWaterCount?: number | null;
+}) {
+  const total = Math.max(0, args.summary.total);
+  const unresolved = Math.max(
+    0,
+    args.summary.pending + args.summary.hydrating + args.summary.error,
+  );
+  const maxResolved = Math.max(0, total - unresolved);
+  return Math.min(
+    Math.max(args.summary.hydrated, args.highWaterCount ?? 0),
+    unresolved > 0 ? maxResolved : total,
+  );
+}
+
+export function databaseItemBodyHydrationIsPending(
+  item: Pick<ContentDatabaseItem, "bodyHydration" | "document">,
+) {
+  if (
+    item.document.databaseMembership?.sourceId &&
+    !item.bodyHydration &&
+    !item.document.databaseMembership.bodyHydration
+  ) {
+    return true;
+  }
+  return builderBodyHydrationIsPending(
+    item.bodyHydration ?? item.document.databaseMembership?.bodyHydration,
+  );
+}
+
+export function documentBodyHydrationIsPending(
+  document: Pick<Document, "databaseMembership">,
+) {
+  return builderBodyHydrationIsPending(
+    document.databaseMembership?.bodyHydration,
+  );
+}
+
+export function previewBodyHydrationIsPending(args: {
+  item: Pick<ContentDatabaseItem, "bodyHydration" | "document">;
+  document: Pick<Document, "databaseMembership"> | null | undefined;
+}) {
+  const membership =
+    args.document?.databaseMembership ?? args.item.document.databaseMembership;
+  if (
+    membership?.sourceId &&
+    !args.document &&
+    !args.item.bodyHydration &&
+    !args.item.document.databaseMembership?.bodyHydration
+  ) {
+    return true;
+  }
+  return (
+    databaseItemBodyHydrationIsPending(args.item) ||
+    (args.document ? documentBodyHydrationIsPending(args.document) : false)
+  );
+}
+
+export function previewBodyHydrationIsTerminalError(args: {
+  item: Pick<ContentDatabaseItem, "bodyHydration" | "document">;
+  document: Pick<Document, "databaseMembership"> | null | undefined;
+}) {
+  return (
+    builderBodyHydrationIsTerminalError(
+      args.document?.databaseMembership?.bodyHydration,
+    ) ||
+    builderBodyHydrationIsTerminalError(
+      args.item.bodyHydration ??
+        args.item.document.databaseMembership?.bodyHydration,
+    )
+  );
+}
+
+export function isEffectivelyEmptyDocumentContent(
+  content: string | null | undefined,
+) {
+  const normalized = (content ?? "").trim();
+  return normalized === "" || normalized === "<empty-block/>";
+}
+
+export function shouldIgnorePreviewEmptyNormalization(args: {
+  currentContent: string | null | undefined;
+  nextContent: string | null | undefined;
+}) {
+  return (
+    isEffectivelyEmptyDocumentContent(args.currentContent) &&
+    isEffectivelyEmptyDocumentContent(args.nextContent)
+  );
+}