@agent-native/core 0.101.7 → 0.101.10

package/corpus/templates/content/app/components/editor/previewDocumentSaveController.ts

@@ -61,12 +61,39 @@ export interface PreviewDocumentPayload {
   loadedContentWasEmpty?: boolean;
 }
 
-export interface PreviewDocumentSaveSkipped {
-  skipped: true;
+export interface PreviewDocumentSaveDeferred {
+  outcome: "deferred";
+  reason: "hydration" | "conflict";
+  conflictSnapshot?: PreviewDocumentDraftSnapshot;
 }
 
-export function skippedPreviewDocumentSave(): PreviewDocumentSaveSkipped {
-  return { skipped: true };
+export interface PreviewDocumentSaveAdapter {
+  save: (
+    documentId: string,
+    payload: PreviewDocumentPayload,
+    baseline?: PreviewDocumentPayload,
+  ) => Promise<unknown>;
+  onSaved?: (payload: PreviewDocumentPayload) => void;
+  onError?: (error: unknown) => void;
+  onDraftConflict?: (snapshot: PreviewDocumentDraftSnapshot) => void;
+}
+
+export interface PreviewDocumentDraftSnapshot {
+  lastSaved: PreviewDocumentPayload;
+  pending: PreviewDocumentPayload;
+  deferredReason: PreviewDocumentSaveDeferred["reason"] | null;
+}
+
+/**
+ * The save could not run yet, but the payload is still user-owned and must stay
+ * dirty until a later flush can persist it. This is intentionally different
+ * from success: callers must never advance or reset the confirmed baseline.
+ */
+export function deferredPreviewDocumentSave(
+  reason: PreviewDocumentSaveDeferred["reason"] = "hydration",
+  conflictSnapshot?: PreviewDocumentDraftSnapshot,
+): PreviewDocumentSaveDeferred {
+  return { outcome: "deferred", reason, conflictSnapshot };
 }
 
 export interface PreviewDocumentSaveController {
@@ -89,6 +116,19 @@ export interface PreviewDocumentSaveController {
   cancel(): void;
   /** Adopt `payload` as the confirmed-saved baseline (no save scheduled). */
   mark(payload: PreviewDocumentPayload): void;
+  /**
+   * Adopt a fresher server baseline while retaining the user's pending title
+   * and content. Used only after an explicit "keep local draft" choice.
+   */
+  rebasePending(payload: PreviewDocumentPayload): void;
+  /** Replace callbacks captured by an older preview mount. */
+  replaceSaveAdapter(adapter: PreviewDocumentSaveAdapter): void;
+  /** Serializable dirty state for bounded browser draft storage. */
+  draftSnapshot(): PreviewDocumentDraftSnapshot;
+  /** Restore a previously persisted dirty draft into a fresh controller. */
+  restoreDraft(snapshot: PreviewDocumentDraftSnapshot): void;
+  /** Notify whichever preview mount currently owns this controller. */
+  notifyDraftConflict(snapshot: PreviewDocumentDraftSnapshot): void;
   /** The payload last CONFIRMED persisted. */
   readonly lastSaved: PreviewDocumentPayload;
   /** The latest payload the user has typed (may differ from lastSaved). */
@@ -97,6 +137,8 @@ export interface PreviewDocumentSaveController {
   readonly hasPendingTimer: boolean;
   /** Whether a save() call is currently outstanding (in flight). */
   readonly isSaving: boolean;
+  /** Why the latest attempted save remains dirty, if it was deferred. */
+  readonly deferredReason: PreviewDocumentSaveDeferred["reason"] | null;
   /**
    * Whether this controller has confirmed at least one local save since creation.
    * Until the server query echoes that payload, clean local state is newer than
@@ -109,25 +151,21 @@ function payloadsEqual(a: PreviewDocumentPayload, b: PreviewDocumentPayload) {
   return a.title === b.title && a.content === b.content;
 }
 
-export function createPreviewDocumentSaveController(args: {
-  /**
-   * The document id this controller persists to, fixed for its entire life. A
-   * controller NEVER changes which document it targets — switching rows acquires
-   * a different controller (see previewDocumentSaveRegistry).
-   */
-  documentId: string;
-  initial: PreviewDocumentPayload;
-  /** Persist `payload` to this controller's document. */
-  save: (
-    documentId: string,
-    payload: PreviewDocumentPayload,
-  ) => Promise<unknown>;
-  onSaved?: (payload: PreviewDocumentPayload) => void;
-  onError?: (error: unknown) => void;
-  debounceMs?: number;
-  setTimeoutFn?: typeof setTimeout;
-  clearTimeoutFn?: typeof clearTimeout;
-}): PreviewDocumentSaveController {
+export function createPreviewDocumentSaveController(
+  args: PreviewDocumentSaveAdapter & {
+    /**
+     * The document id this controller persists to, fixed for its entire life. A
+     * controller NEVER changes which document it targets — switching rows acquires
+     * a different controller (see previewDocumentSaveRegistry).
+     */
+    documentId: string;
+    initial: PreviewDocumentPayload;
+    /** Persist `payload` to this controller's document. */
+    debounceMs?: number;
+    setTimeoutFn?: typeof setTimeout;
+    clearTimeoutFn?: typeof clearTimeout;
+  },
+): PreviewDocumentSaveController {
   const documentId = args.documentId;
   const debounceMs = args.debounceMs ?? 450;
   const setTimeoutFn = args.setTimeoutFn ?? setTimeout;
@@ -137,6 +175,13 @@ export function createPreviewDocumentSaveController(args: {
   let pending: PreviewDocumentPayload = { ...args.initial };
   let timer: ReturnType<typeof setTimeout> | null = null;
   let hasSavedLocally = false;
+  let deferredReason: PreviewDocumentSaveDeferred["reason"] | null = null;
+  let saveAdapter: PreviewDocumentSaveAdapter = {
+    save: args.save,
+    onSaved: args.onSaved,
+    onError: args.onError,
+    onDraftConflict: args.onDraftConflict,
+  };
 
   // The single in-flight save, or null when idle. A debounced edit made while
   // this is set does NOT start a new save; it updates `pending` and a trailing
@@ -161,29 +206,42 @@ export function createPreviewDocumentSaveController(args: {
     if (payloadsEqual(pending, lastSaved)) return; // nothing dirty.
 
     const attempted = { ...pending };
-    const promise = Promise.resolve(args.save(documentId, attempted))
+    const promise = Promise.resolve(
+      saveAdapter.save(documentId, attempted, { ...lastSaved }),
+    )
       .then((result) => {
         if (
           result &&
           typeof result === "object" &&
-          "skipped" in result &&
-          result.skipped === true
+          "outcome" in result &&
+          result.outcome === "deferred" &&
+          "reason" in result &&
+          (result.reason === "hydration" || result.reason === "conflict")
         ) {
-          pending = { ...lastSaved };
+          // Hydration can begin after a keystroke but before the debounce fires.
+          // Keep the attempted payload dirty so the registry can retain it across
+          // close/reopen and a later flush can retry it. A deferred save is not a
+          // successful save, and user-authored content is never disposable.
+          deferredReason = result.reason;
           inFlight = null;
+          const deferredResult = result as PreviewDocumentSaveDeferred;
+          if (deferredResult.conflictSnapshot) {
+            saveAdapter.onDraftConflict?.(deferredResult.conflictSnapshot);
+          }
           return;
         }
         lastSaved = attempted;
         hasSavedLocally = true;
+        deferredReason = null;
         inFlight = null;
-        args.onSaved?.(attempted);
+        saveAdapter.onSaved?.(attempted);
         // A trailing edit may have landed while this save was in flight. Issue
         // exactly one more for the LATEST payload. Bounded: stops once quiescent.
         kick();
       })
       .catch((error) => {
         inFlight = null;
-        args.onError?.(error);
+        saveAdapter.onError?.(error);
       });
     inFlight = promise;
   }
@@ -201,10 +259,12 @@ export function createPreviewDocumentSaveController(args: {
     documentId,
     changeTitle(title: string) {
       pending = { ...pending, title };
+      deferredReason = null;
       schedule();
     },
     changeContent(content: string) {
       pending = { ...pending, content };
+      deferredReason = null;
       schedule();
     },
     flush() {
@@ -233,6 +293,38 @@ export function createPreviewDocumentSaveController(args: {
       lastSaved = { ...payload };
       pending = { ...payload };
       hasSavedLocally = false;
+      deferredReason = null;
+    },
+    rebasePending(payload: PreviewDocumentPayload) {
+      clearTimer();
+      lastSaved = { ...payload };
+      pending = {
+        ...pending,
+        loadedUpdatedAt: payload.loadedUpdatedAt,
+        loadedContentWasEmpty: payload.loadedContentWasEmpty,
+      };
+      hasSavedLocally = false;
+      deferredReason = null;
+    },
+    replaceSaveAdapter(adapter: PreviewDocumentSaveAdapter) {
+      saveAdapter = adapter;
+    },
+    draftSnapshot() {
+      return {
+        lastSaved: { ...lastSaved },
+        pending: { ...pending },
+        deferredReason,
+      };
+    },
+    restoreDraft(snapshot: PreviewDocumentDraftSnapshot) {
+      clearTimer();
+      lastSaved = { ...snapshot.lastSaved };
+      pending = { ...snapshot.pending };
+      deferredReason = snapshot.deferredReason;
+      hasSavedLocally = false;
+    },
+    notifyDraftConflict(snapshot: PreviewDocumentDraftSnapshot) {
+      saveAdapter.onDraftConflict?.(snapshot);
     },
     get lastSaved() {
       return { ...lastSaved };
@@ -246,6 +338,9 @@ export function createPreviewDocumentSaveController(args: {
     get isSaving() {
       return inFlight !== null;
     },
+    get deferredReason() {
+      return deferredReason;
+    },
     get hasSavedLocally() {
       return hasSavedLocally;
     },

package/corpus/templates/content/app/components/editor/previewDocumentSaveRegistry.ts

@@ -67,12 +67,14 @@ function controllerIsDirty(controller: PreviewDocumentSaveController): boolean {
 export function acquirePreviewDocumentSaveController(
   documentId: string,
   factory: () => PreviewDocumentSaveController,
+  refreshAdapter?: (controller: PreviewDocumentSaveController) => void,
 ): PreviewDocumentSaveController {
   let entry = registry.get(documentId);
   if (!entry) {
     entry = { controller: factory(), refCount: 0, evicting: false };
     registry.set(documentId, entry);
   }
+  refreshAdapter?.(entry.controller);
   entry.refCount += 1;
   // A reopen before a pending eviction settled: keep the instance alive.
   entry.evicting = false;

package/corpus/templates/content/app/global.css

@@ -364,6 +364,21 @@
   line-height: 1.45;
 }
 
+.notion-editor h5 {
+  font-size: 1em;
+  font-weight: 600;
+  margin: 0.8em 0 0.15em;
+  line-height: 1.5;
+}
+
+.notion-editor h6 {
+  font-size: 0.95em;
+  font-weight: 600;
+  margin: 0.75em 0 0.15em;
+  line-height: 1.5;
+  color: hsl(var(--muted-foreground));
+}
+
 /* Paragraphs */
 .notion-editor p {
   margin: 0.5em 0;
@@ -408,7 +423,9 @@
 .notion-editor h1.is-empty::before,
 .notion-editor h2.is-empty::before,
 .notion-editor h3.is-empty::before,
-.notion-editor h4.is-empty::before {
+.notion-editor h4.is-empty::before,
+.notion-editor h5.is-empty::before,
+.notion-editor h6.is-empty::before {
   content: attr(data-placeholder);
   float: left;
   color: hsl(var(--muted-foreground));

package/corpus/templates/content/app/hooks/use-content-database.ts

@@ -4,6 +4,8 @@ import type {
   AddDatabaseItemRequest,
   AttachContentDatabaseSourceRequest,
   BuilderCmsModelsResponse,
+  CancelPreparedBuilderSourceUpdateRequest,
+  CancelPreparedBuilderSourceUpdateResponse,
   ChangeContentDatabaseSourceRoleRequest,
   ContentDatabaseResponse,
   ContentDatabasePersonalViewResponse,
@@ -25,6 +27,7 @@ import type {
   ExecuteBuilderSourceExecutionRequest,
   MoveDatabaseItemRequest,
   PrepareBuilderSourceExecutionRequest,
+  PreviewBuilderSourceReviewResponse,
   PrepareBuilderSourceReviewRequest,
   PrepareBuilderSourceReviewResponse,
   ProcessBuilderBodyHydrationRequest,
@@ -815,6 +818,27 @@ export function useAddContentDatabaseSourceFieldProperty(documentId: string) {
   });
 }
 
+export function useMaterializeBuilderRequiredFields(documentId: string) {
+  const queryClient = useQueryClient();
+  return useActionMutation<
+    ContentDatabaseResponse,
+    { documentId: string; sourceId: string }
+  >("materialize-builder-required-fields", {
+    onSuccess: (data) => {
+      writeContentDatabaseResponseToCache(queryClient, documentId, data);
+      queryClient.invalidateQueries({
+        queryKey: contentDatabaseQueryKey(documentId),
+      });
+      queryClient.invalidateQueries({
+        queryKey: ["action", "get-content-database-source", { documentId }],
+      });
+      queryClient.invalidateQueries({
+        queryKey: ["action", "list-document-properties", { documentId }],
+      });
+    },
+  });
+}
+
 export function useBuilderCmsModels(enabled: boolean) {
   return useActionQuery<BuilderCmsModelsResponse>(
     "list-builder-cms-models",
@@ -1014,6 +1038,23 @@ export function usePrepareBuilderSourceExecution(documentId: string) {
   });
 }
 
+export function useCancelPreparedBuilderSourceUpdate(documentId: string) {
+  const queryClient = useQueryClient();
+  return useActionMutation<
+    CancelPreparedBuilderSourceUpdateResponse,
+    CancelPreparedBuilderSourceUpdateRequest
+  >("cancel-prepared-builder-source-update", {
+    onSuccess: () => {
+      queryClient.invalidateQueries({
+        queryKey: contentDatabaseQueryKey(documentId),
+      });
+      queryClient.invalidateQueries({
+        queryKey: ["action", "get-content-database-source", { documentId }],
+      });
+    },
+  });
+}
+
 export function useValidateBuilderSourceExecution(documentId: string) {
   const queryClient = useQueryClient();
   return useActionMutation<
@@ -1099,6 +1140,33 @@ export function usePrepareBuilderSourceReview(documentId: string) {
   });
 }
 
+export function usePreviewBuilderSourceReview(args: {
+  documentId: string;
+  sourceId: string | null;
+  scope: "selected" | "all";
+  documentIds?: string[];
+  enabled: boolean;
+}) {
+  return useActionQuery<PreviewBuilderSourceReviewResponse>(
+    "preview-builder-source-review",
+    args.enabled && args.sourceId
+      ? {
+          documentId: args.documentId,
+          sourceId: args.sourceId,
+          scope: args.scope,
+          documentIds: args.documentIds,
+        }
+      : undefined,
+    {
+      enabled: args.enabled && !!args.sourceId,
+      retry: false,
+      staleTime: 0,
+      gcTime: 0,
+      refetchOnWindowFocus: false,
+    },
+  );
+}
+
 export function useStageBuilderSourceBulkUpdate(documentId: string) {
   const queryClient = useQueryClient();
   return useActionMutation<

package/corpus/templates/content/app/hooks/use-documents.ts

@@ -92,13 +92,15 @@ export function seedDatabaseItemDocumentCaches(
   // Seed only cold caches. Overwriting an existing entry would bump its
   // freshness with possibly older table-snapshot data (a background database
   // refetch can lag a just-saved document edit) and suppress the correcting
-  // refetch for the whole staleTime window. Rows whose Builder body has not
-  // hydrated yet, or whose source-backed list snapshot intentionally omits the
-  // body, are never seeded: their empty table-snapshot `content` would render as
-  // an authoritative empty document.
+  // refetch for the whole staleTime window. Source-backed rows are never seeded:
+  // list snapshots are not authoritative enough to unlock the body editor, even
+  // when they happen to contain non-empty content. The dedicated get-document
+  // response owns that decision and prevents an edit from racing hydration.
   if (
     !databaseItemBodyHydrationIsPending(item) &&
     !sourceBackedEmptyBody &&
+    !item.bodyHydration &&
+    !item.document.databaseMembership?.sourceId &&
     queryClient.getQueryData(documentQueryKey(item.document.id)) === undefined
   ) {
     queryClient.setQueryData<Document>(documentQueryKey(item.document.id), {
@@ -139,6 +141,53 @@ export function useDocument(id: string | null) {
   });
 }
 
+export interface PreviewDocumentDraftRecord {
+  documentId: string;
+  title: string;
+  content: string;
+  baseDocumentUpdatedAt: string | null;
+  loadedContentWasEmpty: number;
+  deferredReason: string | null;
+  version: number;
+  updatedAt: string;
+}
+
+export function usePreviewDocumentDraft(documentId: string | null) {
+  return useActionQuery<{ draft: PreviewDocumentDraftRecord | null }>(
+    "get-preview-document-draft",
+    documentId ? { documentId } : undefined,
+    { enabled: !!documentId, retry: false },
+  );
+}
+
+export function useUpdatePreviewDocumentDraft() {
+  return useActionMutation<
+    {
+      status: "saved" | "deleted" | "conflict";
+      draft: PreviewDocumentDraftRecord | null;
+    },
+    | {
+        operation: "upsert";
+        documentId: string;
+        expectedVersion: number | null;
+        draft: {
+          title: string;
+          content: string;
+          baseDocumentUpdatedAt: string | null;
+          loadedContentWasEmpty: boolean;
+          deferredReason: "hydration" | "conflict" | null;
+        };
+      }
+    | {
+        operation: "delete";
+        documentId: string;
+        expectedVersion: number;
+        expectedTitle: string;
+        expectedContent: string;
+      }
+  >("update-preview-document-draft");
+}
+
 export function useCreateDocument() {
   return useActionMutation<Document, DocumentCreateRequest>("create-document");
 }

package/corpus/templates/content/app/i18n/zh-TW.ts

@@ -578,6 +578,13 @@ const messages = {
     addDetailsToExistingItems: "為現有項目新增詳細資料",
     addedFieldsFromSource: "已從此來源新增 {{count}} 個欄位。",
     addedOneFieldFromSource: "已從此來源新增 1 個欄位。",
+    addRequiredFields: "新增必填欄位",
+    publishingFieldsAdded: "已新增發布欄位",
+    requiredBuilderFieldsReady:
+      "{{count}} 個 Builder 必填欄位已可在 Content 中編輯。",
+    requiredPublishingFields: "必填發布欄位",
+    requiredPublishingFieldsDescription:
+      "新增此集合發布前 Builder 所需的中繼資料：{{fields}}。",
     addingDetails: "正在新增詳細資料",
     addingDetailsMatchedOn: "正在新增以 {{field}} 比對的詳細資料。",
     addingItems: "正在新增項目",
@@ -628,6 +635,7 @@ const messages = {
     noPendingLocalBuilderChanges: "尚無待處理的本機 Builder 變更。",
     needsAttention: "需要處理",
     failedYouCanRetry: "失敗 — 您可以重試",
+    reconciliationRequired: "需要核對 — 請勿重試",
     needsAFreshReview: "需要重新審查",
     working: "處理中…",
     ready: "就緒",
@@ -653,6 +661,11 @@ const messages = {
     builderBodySyncing: "內容仍在從 Builder 同步",
     builderBodySyncingDescription:
       "同步 Builder 正文完成前會暫停編輯，避免覆寫既有文章內容。",
+    builderDraftConflictTitle: "你編輯期間收到了新的 Builder 內容",
+    builderDraftConflictDescription:
+      "你的本機草稿已保留。你可以保留草稿以在本機取代新同步的正文，或重新載入 Builder 正文。",
+    keepLocalDraft: "保留本機草稿",
+    reloadBuilderBody: "重新載入 Builder 正文",
     builderBodiesHydrated: "已同步 {{hydrated}} / {{total}} 個正文",
     builderReviewShowingRows:
       "此次審查顯示 {{total}} 個 Builder 列中的 {{shown}} 個。",
@@ -870,6 +883,8 @@ const messages = {
     retry: "Retry",
     reviewBeforeTheyReachBuilder: "在傳送到 Builder 前審核。",
     reviewDiff: "審核差異",
+    reviewDiffDescription: "在任何內容傳送到 Builder 前載入完整的內容差異。",
+    loadingCompleteBuilderDiff: "正在載入完整的 Builder 差異…",
     sampleMatches: "範例匹配",
     showAll: "顯示全部",
     sortAscending: "升序排序",
@@ -917,6 +932,7 @@ const messages = {
     builderModel: "Builder 模型",
     builderPreparingGate: "正在準備 Builder gate，並透過受保護路徑送出。",
     builderPushFinished: "Builder 推送已完成。",
+    builderPushAlreadyRunning: "Builder 推送已在執行中。未送出第二次寫入。",
     builderPushedReconciled: "已送出至 Builder 並完成本機對帳。",
     builderPushWillSend: "送出會透過受保護的 Builder 路徑寫入 autosave。",
     builderWritesDisabledCheckOnly: "Builder 寫入已停用。送出只會檢查更新。",
@@ -926,6 +942,15 @@ const messages = {
     checksOnly: "僅檢查",
     close: "關閉",
     closeBuilderUpdateReview: "關閉 Builder 更新審查",
+    cancelPreparedUpdate: "取消已準備的更新",
+    cancelPreparedUpdateQuestion: "要取消這個已準備的更新嗎？",
+    cancelPreparedUpdateDescription:
+      "這會在送出前停止本機執行並保留稽核記錄。不會向 Builder 傳送任何內容。",
+    keepPreparedUpdate: "保留已準備的更新",
+    cancellingPreparedUpdate: "正在取消…",
+    preparedUpdateCancelled: "已取消準備好的 Builder 更新",
+    preparedUpdateAlreadyCancelled: "準備好的 Builder 更新已被取消",
+    cancelPreparedUpdateFailed: "未能取消準備好的 Builder 更新",
     disabled: "已停用",
     draft: "草稿",
     enabled: "已啟用",