@agent-native/core 0.169.1 → 0.170.0

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

@@ -16,6 +16,7 @@ import { canonicalizeNfm, docToNfm, nfmToDoc } from "@shared/nfm";
 import {
   serializeRegistryBlockToMdx,
   parseRegistryBlockData,
+  type ParsedRegistryBlock,
 } from "@shared/nfm-registry";
 import { IconMusic, IconPhoto, IconVideo } from "@tabler/icons-react";
 import {
@@ -1741,6 +1742,7 @@ export function createVisualEditorExtensions({
  */
 interface RegistryBlockStoreEntry {
   type: string;
+  rawSource: string;
   base?: {
     title?: string;
     summary?: string;
@@ -1748,6 +1750,42 @@ interface RegistryBlockStoreEntry {
   };
   data: unknown;
   edited: boolean;
+  loadError?: {
+    reason: string;
+  };
+}
+
+export async function hydrateRegistryBlockRaw(
+  rawSource: string,
+): Promise<
+  | { status: "loaded"; block: ParsedRegistryBlock }
+  | { status: "error"; message: string; rawSource: string }
+> {
+  try {
+    const block = await parseRegistryBlockData(rawSource);
+    if (!block) {
+      return {
+        status: "error",
+        message: "unreadable",
+        rawSource,
+      };
+    }
+    return { status: "loaded", block };
+  } catch (error) {
+    return {
+      status: "error",
+      message: error instanceof Error ? error.message : "unreadable",
+      rawSource,
+    };
+  }
+}
+
+export function isRegistryBlockHydrationCurrent(
+  expectedRaw: string,
+  pendingRaw: string | undefined,
+  liveRaw: string,
+): boolean {
+  return pendingRaw === expectedRaw && liveRaw === expectedRaw;
 }
 
 function serializeRegistryBlockRaw(
@@ -1803,8 +1841,9 @@ function isNotionIncompatibleBlockType(blockType: string): boolean {
  * serializes identically to before.
  */
 function useRegistryBlockStore(editor: CoreEditor | null) {
+  const t = useT();
   const cacheRef = useRef<Map<string, RegistryBlockStoreEntry>>(new Map());
-  const pendingRef = useRef<Set<string>>(new Set());
+  const pendingRef = useRef<Map<string, string>>(new Map());
   // Bumping this state forces the NodeViews to re-read the cache once async
   // hydration (or an edit) lands. The `version` is surfaced to the side-map
   // value so the context reference changes on each bump — otherwise the Tiptap
@@ -1845,25 +1884,66 @@ function useRegistryBlockStore(editor: CoreEditor | null) {
         typeof node.attrs.title === "string" ? node.attrs.title : undefined;
       const summary =
         typeof node.attrs.summary === "string" ? node.attrs.summary : undefined;
+      const raw = typeof node.attrs.__raw === "string" ? node.attrs.__raw : "";
 
       const cached = cacheRef.current.get(blockId);
-      if (cached) {
-        return { id: blockId, title, summary, data: cached.data };
+      if (cached?.rawSource === raw) {
+        return {
+          id: blockId,
+          title,
+          summary,
+          data: cached.data,
+          loadError: cached.loadError
+            ? {
+                message: t("editor.registryBlockLoadError", {
+                  type:
+                    typeof node.attrs.blockType === "string"
+                      ? node.attrs.blockType
+                      : "registry",
+                  message:
+                    cached.loadError.reason === "unreadable"
+                      ? t("editor.registryBlockUnreadable")
+                      : cached.loadError.reason,
+                }),
+                rawSource: cached.rawSource,
+              }
+            : undefined,
+        };
       }
+      if (cached) cacheRef.current.delete(blockId);
 
       // Not hydrated yet: kick off a one-shot async parse of the verbatim MDX.
-      const raw = typeof node.attrs.__raw === "string" ? node.attrs.__raw : "";
-      if (raw && !pendingRef.current.has(blockId)) {
-        pendingRef.current.add(blockId);
-        void parseRegistryBlockData(raw)
-          .then((parsed) => {
-            if (parsed) {
+      if (pendingRef.current.get(blockId) !== raw) {
+        pendingRef.current.set(blockId, raw);
+        void hydrateRegistryBlockRaw(raw)
+          .then((result) => {
+            const live = findNode(blockId);
+            const liveRaw =
+              live && typeof live.node.attrs.__raw === "string"
+                ? live.node.attrs.__raw
+                : "";
+            if (
+              !isRegistryBlockHydrationCurrent(
+                raw,
+                pendingRef.current.get(blockId),
+                liveRaw,
+              )
+            ) {
+              if (pendingRef.current.get(blockId) === raw) {
+                pendingRef.current.delete(blockId);
+                bump();
+              }
+              return;
+            }
+            if (result.status === "loaded") {
+              const parsed = result.block;
               const existing = cacheRef.current.get(blockId);
               // A concurrent edit may have populated the cache first — don't
               // clobber it with the stale parse.
               if (!existing) {
                 cacheRef.current.set(blockId, {
                   type: parsed.type,
+                  rawSource: raw,
                   base: parsed.base,
                   data: parsed.data,
                   edited: false,
@@ -1902,6 +1982,8 @@ function useRegistryBlockStore(editor: CoreEditor | null) {
                         },
                       );
                       editor.view.dispatch(tr);
+                      const entry = cacheRef.current.get(blockId);
+                      if (entry) entry.rawSource = refreshedRaw;
                     } catch {
                       /* Keep the parsed cache; leave raw untouched if invalid. */
                     }
@@ -1909,18 +1991,31 @@ function useRegistryBlockStore(editor: CoreEditor | null) {
                 }
                 bump();
               }
+            } else if (!cacheRef.current.has(blockId)) {
+              cacheRef.current.set(blockId, {
+                type:
+                  typeof node.attrs.blockType === "string"
+                    ? node.attrs.blockType
+                    : "",
+                rawSource: result.rawSource,
+                data: undefined,
+                edited: false,
+                loadError: {
+                  reason: result.message,
+                },
+              });
+              bump();
             }
           })
-          .catch(() => {
-            /* Leave uncached; the NodeView keeps showing its placeholder. */
-          })
           .finally(() => {
-            pendingRef.current.delete(blockId);
+            if (pendingRef.current.get(blockId) === raw) {
+              pendingRef.current.delete(blockId);
+            }
           });
       }
       return undefined;
     },
-    [editor, findNode, bump],
+    [editor, findNode, bump, t],
   );
 
   const onBlockDataChange = useCallback(
@@ -1939,6 +2034,7 @@ function useRegistryBlockStore(editor: CoreEditor | null) {
       cacheRef.current.set(blockId, {
         type,
         base,
+        rawSource: typeof node.attrs.__raw === "string" ? node.attrs.__raw : "",
         data: nextData,
         edited: true,
       });
@@ -1954,6 +2050,8 @@ function useRegistryBlockStore(editor: CoreEditor | null) {
         bump();
         return;
       }
+      const updated = cacheRef.current.get(blockId);
+      if (updated) updated.rawSource = raw;
 
       const tr = editor.state.tr.setNodeMarkup(pos, undefined, {
         ...node.attrs,
@@ -2009,6 +2107,33 @@ export function VisualEditor({
   onSaveContentRef.current = onSaveContent;
   const onHistoryStateChangeRef = useRef(onHistoryStateChange);
   onHistoryStateChangeRef.current = onHistoryStateChange;
+  const historyStateNotificationRef = useRef<VisualEditorHistoryState | null>(
+    null,
+  );
+  const historyStateNotificationQueuedRef = useRef(false);
+  const editorMountedRef = useRef(false);
+  const notifyHistoryStateChange = useCallback(
+    (state: VisualEditorHistoryState) => {
+      historyStateNotificationRef.current = state;
+      if (historyStateNotificationQueuedRef.current) return;
+      historyStateNotificationQueuedRef.current = true;
+      queueMicrotask(() => {
+        historyStateNotificationQueuedRef.current = false;
+        const next = historyStateNotificationRef.current;
+        historyStateNotificationRef.current = null;
+        if (!editorMountedRef.current || !next) return;
+        onHistoryStateChangeRef.current?.(next);
+      });
+    },
+    [],
+  );
+  useEffect(() => {
+    editorMountedRef.current = true;
+    return () => {
+      editorMountedRef.current = false;
+      historyStateNotificationRef.current = null;
+    };
+  }, []);
   const notionPageLinksRef = useRef(notionPageLinks);
   notionPageLinksRef.current = notionPageLinks;
   const onMediaSourceCommittedRef = useRef<
@@ -2334,7 +2459,7 @@ export function VisualEditor({
     },
     editable,
     onTransaction: ({ editor }) => {
-      onHistoryStateChangeRef.current?.({
+      notifyHistoryStateChange({
         canUndo: editor.can().undo(),
         canRedo: editor.can().redo(),
       });

package/corpus/templates/content/app/components/sidebar/DocumentSidebar.tsx

@@ -65,6 +65,7 @@ import {
   DropdownMenuRadioItem,
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
+import { afterBodyPointerUnlock } from "@/components/ui/pointer-lock";
 import { ScrollArea } from "@/components/ui/scroll-area";
 import { Skeleton } from "@/components/ui/skeleton";
 import {
@@ -212,17 +213,6 @@ const TRASH_COLLAPSED_DEFAULT_MIGRATION_KEY =
   "content-sidebar-trash-collapsed-default-v2";
 const CONTENT_SIDEBAR_STATE_VERSION = 1 as const;
 
-function afterBodyPointerUnlock(callback: () => void) {
-  const run = () => {
-    if (document.body.style.pointerEvents === "none") {
-      window.requestAnimationFrame(run);
-      return;
-    }
-    callback();
-  };
-  window.requestAnimationFrame(run);
-}
-
 interface ContentSidebarStateSnapshot {
   version: typeof CONTENT_SIDEBAR_STATE_VERSION;
   expandedWorkspaceIds: string[];
@@ -376,7 +366,12 @@ function useDeferredFilesDatabaseId(
     return () => window.clearTimeout(timeout);
   }, [databaseId, deferUntilDocumentId, expanded]);
 
-  return expanded && ready ? databaseId : null;
+  // `databaseId` stays stable across the defer window so the query key never
+  // changes; only `enabled` pauses the fetch. Swapping `databaseId` itself to
+  // null here would move the tree to a disabled, never-fetched query key and
+  // drop the rows already on screen for the whole deferred window instead of
+  // just holding off the refetch.
+  return { databaseId: expanded ? databaseId : null, enabled: ready };
 }
 
 function WorkspaceSidebarItem({
@@ -472,12 +467,15 @@ function WorkspaceSidebarItem({
       removeActivation();
     };
   }, []);
-  const activeFilesDatabaseId = useDeferredFilesDatabaseId(
+  const deferredFilesDatabase = useDeferredFilesDatabaseId(
     space.filesDatabaseId,
     expanded,
     deferInitialReadUntilDocumentId,
   );
-  const filesDatabase = useContentDatabaseById(activeFilesDatabaseId);
+  const filesDatabase = useContentDatabaseById(
+    deferredFilesDatabase.databaseId,
+    { enabled: deferredFilesDatabase.enabled },
+  );
   const filesDatabaseData = isContentDatabaseUnavailable(filesDatabase.data)
     ? undefined
     : filesDatabase.data;

package/corpus/templates/content/app/components/ui/pointer-lock.ts

@@ -0,0 +1 @@
+export * from "@agent-native/toolkit/ui/pointer-lock";

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

@@ -693,12 +693,28 @@ export function useContentDatabase(
   };
 }
 
-export function useContentDatabaseById(databaseId: string | null) {
+// `enabled` pauses fetching without touching the query key: a caller that
+// wants to briefly hold off refetching (e.g. to avoid competing with a
+// higher-priority read) can pass `databaseId` unchanged and flip `enabled` to
+// false instead of nulling `databaseId` out. Nulling it changes the query key
+// to its disabled `undefined`-params form, which has no cached data of its
+// own and drops the rows already on screen for as long as it stays disabled.
+export function isContentDatabaseByIdQueryEnabled(
+  databaseId: string | null,
+  options?: { enabled?: boolean },
+): boolean {
+  return !!databaseId && options?.enabled !== false;
+}
+
+export function useContentDatabaseById(
+  databaseId: string | null,
+  options?: { enabled?: boolean },
+) {
   return useActionQuery<ContentDatabaseResponse>(
     "get-content-database",
     databaseId ? { databaseId } : undefined,
     {
-      enabled: !!databaseId,
+      enabled: isContentDatabaseByIdQueryEnabled(databaseId, options),
       retry: false,
       placeholderData: (previous, previousQuery) =>
         preserveScopedDatabasePlaceholder(previous, previousQuery, {

package/corpus/templates/content/app/hooks/use-local-storage.ts

@@ -1,6 +1,14 @@
-import { useState, useCallback, useEffect, useRef } from "react";
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react";
 
 const LOCAL_STORAGE_CHANGE_EVENT = "content-local-storage-change";
+const useIsomorphicLayoutEffect =
+  typeof window === "undefined" ? useEffect : useLayoutEffect;
 
 function readStorage<T>(key: string, defaultValue: T): T {
   if (typeof window === "undefined") return defaultValue;
@@ -19,25 +27,33 @@ export function useLocalStorage<T>(
 ): [T, (val: T | ((prev: T) => T)) => void] {
   const prevKeyRef = useRef(key);
   const [value, setValue] = useState<T>(() => readStorage(key, defaultValue));
+  const valueRef = useRef(value);
+  const keyChanged = prevKeyRef.current !== key;
+  const visibleValue = keyChanged ? readStorage(key, defaultValue) : value;
 
-  // Synchronously update value when key changes (no stale render)
-  if (prevKeyRef.current !== key) {
-    prevKeyRef.current = key;
-    const fresh = readStorage(key, defaultValue);
-    setValue(fresh);
-  }
+  useIsomorphicLayoutEffect(() => {
+    if (prevKeyRef.current !== key) {
+      prevKeyRef.current = key;
+      valueRef.current = visibleValue;
+      setValue(visibleValue);
+    }
+  }, [key, visibleValue]);
 
   useEffect(() => {
     function handleStorage(event: StorageEvent) {
       if (event.key === key) {
-        setValue(readStorage(key, defaultValue));
+        const next = readStorage(key, defaultValue);
+        valueRef.current = next;
+        setValue(next);
       }
     }
 
     function handleLocalStorageChange(event: Event) {
       const detail = (event as CustomEvent<{ key?: string; value?: T }>).detail;
       if (detail?.key === key) {
-        setValue(detail.value as T);
+        const next = detail.value as T;
+        valueRef.current = next;
+        setValue(next);
       }
     }
 
@@ -58,21 +74,21 @@ export function useLocalStorage<T>(
 
   const set = useCallback(
     (val: T | ((prev: T) => T)) => {
-      setValue((prev) => {
-        const next = val instanceof Function ? val(prev) : val;
-        try {
-          window.localStorage.setItem(key, JSON.stringify(next));
-          window.dispatchEvent(
-            new CustomEvent(LOCAL_STORAGE_CHANGE_EVENT, {
-              detail: { key, value: next },
-            }),
-          );
-        } catch {}
-        return next;
-      });
+      const next = val instanceof Function ? val(valueRef.current) : val;
+      valueRef.current = next;
+      setValue(next);
+      try {
+        window.localStorage.setItem(key, JSON.stringify(next));
+        window.dispatchEvent(
+          new CustomEvent(LOCAL_STORAGE_CHANGE_EVENT, {
+            detail: { key, value: next },
+          }),
+        );
+        // coercion-ok: local persistence is optional; the in-memory value remains available.
+      } catch {}
     },
     [key],
   );
 
-  return [value, set];
+  return [visibleValue, set];
 }

package/corpus/templates/content/app/i18n-data.ts

@@ -3167,6 +3167,8 @@ const enUS = {
     searchLanguages: "Search languages...",
     noBlocksFields: "No Blocks fields. Add one from the property menu.",
     noDocumentSelected: "No document selected",
+    registryBlockLoadError: "Could not load {{type}} block: {{message}}",
+    registryBlockUnreadable: "Persisted block source is unreadable.",
     blocksFieldRevisionConflict:
       "This Blocks field changed elsewhere. Your edit wasn't saved; the latest version is now shown.",
     couldNotReadLocalSourceFile: "Could not read local source file",
@@ -5762,6 +5764,8 @@ const editorMessagesByLocale = {
       red: "红色",
     },
     noDocumentSelected: "未选择文档",
+    registryBlockLoadError: "无法加载 {{type}} 块：{{message}}",
+    registryBlockUnreadable: "无法读取已保存的块源内容。",
     blocksFieldRevisionConflict:
       "此 Blocks 字段已在其他位置更改。你的编辑未保存；现已显示最新版本。",
     collabConnectingReadOnly: "正在连接实时编辑器。显示只读快照。",
@@ -6127,6 +6131,8 @@ const editorMessagesByLocale = {
       red: "Rojo",
     },
     noDocumentSelected: "Ningún documento seleccionado",
+    registryBlockLoadError: "No se pudo cargar el bloque {{type}}: {{message}}",
+    registryBlockUnreadable: "No se puede leer el origen guardado del bloque.",
     blocksFieldRevisionConflict:
       "Este campo de bloques cambió en otro lugar. Tu edición no se guardó; ahora se muestra la versión más reciente.",
     collabConnectingReadOnly:
@@ -6505,6 +6511,9 @@ const editorMessagesByLocale = {
       red: "Rouge",
     },
     noDocumentSelected: "Aucun document sélectionné",
+    registryBlockLoadError:
+      "Impossible de charger le bloc {{type}} : {{message}}",
+    registryBlockUnreadable: "La source enregistrée du bloc est illisible.",
     blocksFieldRevisionConflict:
       "Ce champ de blocs a été modifié ailleurs. Votre modification n’a pas été enregistrée ; la dernière version est maintenant affichée.",
     collabConnectingReadOnly:
@@ -6888,6 +6897,10 @@ const editorMessagesByLocale = {
       red: "Rot",
     },
     noDocumentSelected: "Kein Dokument ausgewählt",
+    registryBlockLoadError:
+      "Der Block {{type}} konnte nicht geladen werden: {{message}}",
+    registryBlockUnreadable:
+      "Die gespeicherte Blockquelle kann nicht gelesen werden.",
     blocksFieldRevisionConflict:
       "Dieses Blocks-Feld wurde an anderer Stelle geändert. Deine Bearbeitung wurde nicht gespeichert; jetzt wird die neueste Version angezeigt.",
     collabConnectingReadOnly:
@@ -7274,6 +7287,9 @@ const editorMessagesByLocale = {
       red: "赤",
     },
     noDocumentSelected: "ドキュメントが選択されていません",
+    registryBlockLoadError:
+      "{{type}} ブロックを読み込めませんでした: {{message}}",
+    registryBlockUnreadable: "保存されたブロックソースを読み取れません。",
     blocksFieldRevisionConflict:
       "このブロックフィールドは別の場所で変更されました。編集内容は保存されず、最新バージョンが表示されています。",
     collabConnectingReadOnly:
@@ -7649,6 +7665,8 @@ const editorMessagesByLocale = {
       red: "빨간색",
     },
     noDocumentSelected: "선택한 문서가 없습니다.",
+    registryBlockLoadError: "{{type}} 블록을 불러올 수 없습니다: {{message}}",
+    registryBlockUnreadable: "저장된 블록 소스를 읽을 수 없습니다.",
     blocksFieldRevisionConflict:
       "이 블록 필드가 다른 곳에서 변경되었습니다. 편집 내용은 저장되지 않았으며 최신 버전이 표시됩니다.",
     collabConnectingReadOnly:
@@ -8023,6 +8041,9 @@ const editorMessagesByLocale = {
       red: "Vermelho",
     },
     noDocumentSelected: "Nenhum documento selecionado",
+    registryBlockLoadError:
+      "Não foi possível carregar o bloco {{type}}: {{message}}",
+    registryBlockUnreadable: "Não foi possível ler a origem salva do bloco.",
     blocksFieldRevisionConflict:
       "Este campo de blocos foi alterado em outro lugar. Sua edição não foi salva; a versão mais recente agora está sendo exibida.",
     collabConnectingReadOnly:
@@ -8403,6 +8424,8 @@ const editorMessagesByLocale = {
       red: "लाल",
     },
     noDocumentSelected: "कोई दस्तावेज़ चयनित नहीं",
+    registryBlockLoadError: "{{type}} ब्लॉक लोड नहीं किया जा सका: {{message}}",
+    registryBlockUnreadable: "सहेजा गया ब्लॉक स्रोत पढ़ा नहीं जा सकता।",
     blocksFieldRevisionConflict:
       "यह ब्लॉक फ़ील्ड कहीं और बदल गया है। आपका संपादन सहेजा नहीं गया; अब नवीनतम संस्करण दिखाया जा रहा है।",
     collabConnectingReadOnly:
@@ -8773,6 +8796,8 @@ const editorMessagesByLocale = {
       red: "أحمر",
     },
     noDocumentSelected: "لم يتم تحديد أي مستند",
+    registryBlockLoadError: "تعذر تحميل كتلة {{type}}: {{message}}",
+    registryBlockUnreadable: "تعذرت قراءة مصدر الكتلة المحفوظ.",
     blocksFieldRevisionConflict:
       "تم تغيير حقل الكتل هذا في مكان آخر. لم يتم حفظ تعديلك؛ ويظهر الآن أحدث إصدار.",
     collabConnectingReadOnly:

package/corpus/templates/content/app/routes.ts

@@ -1,4 +1,6 @@
 import { type RouteConfig } from "@react-router/dev/routes";
 import { flatRoutes } from "@react-router/fs-routes";
 
-export default flatRoutes() satisfies RouteConfig;
+export default flatRoutes({
+  ignoredRouteFiles: ["**/*.test.{ts,tsx}", "**/*.spec.{ts,tsx}"],
+}) satisfies RouteConfig;

package/corpus/templates/content/changelog/2026-08-22-code-blocks-inserted-from-the-slash-menu-no-longer-get-stuck.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-22
+---
+
+Code and code-tabs blocks inserted from the slash menu no longer get stuck on "Loading…"

package/corpus/templates/content/changelog/2026-08-22-the-sidebar-page-tree-no-longer-flashes-empty-after-creating-a-page.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-22
+---
+
+The sidebar page tree no longer flashes empty for a moment after creating a new page