@drawnagency/primitives 0.1.113 → 0.1.114

package/src/hooks/useEditorPersistence.ts

@@ -1,12 +1,14 @@
-import { useCallback, useMemo, useRef, useEffect } from "react";
+import { useCallback, useMemo, useRef, useEffect, useState } from "react";
 import type { SectionContent } from "../schemas/sections";
 import type { SiteIndex, SiteConfig } from "../schemas/site-config";
-import { persistAll, persistSiteConfig, deleteSectionRows } from "../lib/dexie";
+import { persistAll, deleteSectionRows } from "../lib/dexie";
 
 interface PersistenceState {
   pendingSections: Map<string, SectionContent>;
   indexDirty: boolean;
   configDirty: boolean;
+  pendingConfig: SiteConfig | null;
+  pendingDeletedRows: Set<string>;
   // Durable "unsaved index structure exists" signal. Unlike indexDirty — which is
   // flush-PENDING state and self-clears ~500ms after an edit — this mirrors the
   // lifetime of the Dexie siteIndex row: set on every structural edit, NOT
@@ -43,6 +45,22 @@ interface PersistenceOptions {
   deletedSectionsRef?: React.RefObject<Set<string>>;
 }
 
+const PERSIST_FAILED_COPY = "Your latest edits couldn't be stored in this browser. Keep this tab open and try saving again.";
+// How long Save/Discard wait on an in-flight IndexedDB write before giving up.
+// A hung transaction (Safari private mode, a quota prompt) never settles.
+const FLUSH_WAIT_MS = 10_000;
+
+/** Resolves true once `flush` settles (either way), false if it is still running after FLUSH_WAIT_MS. */
+async function settlesInTime(flush: Promise<void>): Promise<boolean> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timedOut = new Promise<false>((resolve) => { timer = setTimeout(() => resolve(false), FLUSH_WAIT_MS); });
+  try {
+    return await Promise.race([flush.then(() => true, () => true), timedOut]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 export function useEditorPersistence(
   siteIndexRef: React.RefObject<SiteIndex>,
   options?: PersistenceOptions,
@@ -51,67 +69,130 @@ export function useEditorPersistence(
     pendingSections: new Map(),
     indexDirty: false,
     configDirty: false,
+    pendingConfig: null,
+    pendingDeletedRows: new Set(),
     unsavedIndex: false,
     generation: 0,
     indexGeneration: 0,
     sectionGenerations: new Map(),
   });
+  const [persistenceError, setPersistenceError] = useState<string | null>(null);
+  const activeFlush = useRef<Promise<void> | null>(null);
+  // Writes given up on after FLUSH_WAIT_MS; their late outcome must not touch state.
+  const abandonedFlushes = useRef(new WeakSet<Promise<void>>());
+  // Bumped by discardPending so an in-flight flush can't restore discarded edits.
+  const discardEpoch = useRef(0);
   const flushTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const onFlushRef = useRef(options?.onFlush);
   useEffect(() => { onFlushRef.current = options?.onFlush; });
   const deletedSectionsRef = useRef(options?.deletedSectionsRef);
   useEffect(() => { deletedSectionsRef.current = options?.deletedSectionsRef; });
 
-  const flushToDexie = useCallback(async () => {
+  const flushToDexie = useCallback(async (opts?: { exit?: boolean }) => {
+    // Saves wait for an already-running flush before reading Dexie; its failure
+    // restored its entries into state, so this flush retries them. A write that
+    // never settles is abandoned so the editor can recover without a reload.
+    // A tab-close flush can't wait: the unloading page may never resume it, and
+    // IndexedDB applies its later transaction after the in-flight one anyway.
+    while (!opts?.exit && activeFlush.current) {
+      const inFlight = activeFlush.current;
+      if (!(await settlesInTime(inFlight))) abandonedFlushes.current.add(inFlight);
+      if (activeFlush.current === inFlight) activeFlush.current = null;
+    }
     const s = state.current;
-    if (s.pendingSections.size === 0 && !s.indexDirty) return;
+    if (s.pendingSections.size === 0 && !s.indexDirty && !s.pendingConfig && !s.pendingDeletedRows.size) return;
 
     const entries = Array.from(s.pendingSections.entries()).map(([sectionId, content]) => ({
       sectionId,
       content,
     }));
+    const entryGenerations = new Map(s.sectionGenerations);
     const wasIndexDirty = s.indexDirty;
+    const config = s.pendingConfig;
+    const deletedRows = s.pendingDeletedRows;
+    const epoch = discardEpoch.current;
 
     // Clear optimistically so new edits during the await go into a fresh set
     s.pendingSections = new Map();
     s.indexDirty = false;
+    s.pendingConfig = null;
+    s.pendingDeletedRows = new Set();
 
-    try {
-      // The deletion set is cumulative in shell state (cleared only on save or
-      // discard), so every flush rewrites the whole current set — a later flush
-      // can never narrow an earlier record.
-      const pendingDeletions = deletedSectionsRef.current?.current;
-      await persistAll(
-        entries,
-        wasIndexDirty ? siteIndexRef.current : undefined,
-        pendingDeletions && pendingDeletions.size > 0 ? [...pendingDeletions] : undefined,
-      );
-      // Fire only after a successful persist — broadcasting an edit that failed
-      // to persist would let peers diverge from what this editor can recover.
-      onFlushRef.current?.(entries, wasIndexDirty);
-    } catch (err) {
-      // Restore: merge back any entries that weren't re-dirtied during the await
+    // Merge back what this flush took, unless Discard ran since (it would
+    // resurrect discarded edits) or a newer edit superseded it.
+    const restore = () => {
+      if (discardEpoch.current !== epoch) return;
       for (const { sectionId, content } of entries) {
-        if (!s.pendingSections.has(sectionId)) {
+        if (!s.pendingSections.has(sectionId) && s.sectionGenerations.get(sectionId) === entryGenerations.get(sectionId)) {
           s.pendingSections.set(sectionId, content);
         }
       }
       if (wasIndexDirty) s.indexDirty = true;
-      console.error("Failed to flush to Dexie:", err);
+      if (config && !s.pendingConfig) s.pendingConfig = config;
+      for (const id of deletedRows) s.pendingDeletedRows.add(id);
+    };
+
+    let pending: Promise<void>;
+    const write = async () => {
+      try {
+        if (deletedRows.size) await deleteSectionRows([...deletedRows]);
+        // The deletion set is cumulative in shell state (cleared only on save or
+        // discard), so every flush rewrites the whole current set — a later flush
+        // can never narrow an earlier record.
+        const pendingDeletions = deletedSectionsRef.current?.current;
+        await persistAll(
+          entries,
+          wasIndexDirty ? siteIndexRef.current : undefined,
+          pendingDeletions && pendingDeletions.size > 0 ? [...pendingDeletions] : undefined,
+          config ?? undefined,
+        );
+      } catch (err) {
+        console.error("Failed to flush to Dexie:", err);
+        // An abandoned write was already restored when it was given up on.
+        if (!abandonedFlushes.current.has(pending)) {
+          restore();
+          setPersistenceError(PERSIST_FAILED_COPY);
+        }
+        throw new Error(PERSIST_FAILED_COPY, { cause: err });
+      }
+      if (abandonedFlushes.current.has(pending)) return;
+      setPersistenceError(null);
+      // Fire only after a successful persist — broadcasting an edit that failed
+      // to persist would let peers diverge from what this editor can recover.
+      // Config-only and row-delete-only flushes have nothing to broadcast.
+      if (entries.length > 0 || wasIndexDirty) onFlushRef.current?.(entries, wasIndexDirty);
+    };
+    pending = write();
+    activeFlush.current = pending;
+    try {
+      if (!(await settlesInTime(pending))) {
+        abandonedFlushes.current.add(pending);
+        restore();
+        setPersistenceError(PERSIST_FAILED_COPY);
+        throw new Error(PERSIST_FAILED_COPY);
+      }
+      await pending;
+    } finally {
+      if (activeFlush.current === pending) activeFlush.current = null;
     }
   }, [siteIndexRef]);
 
+  // Background flushes surface their error in the banner; explicit saves reject.
+  const flushInBackground = useCallback(() => {
+    void flushToDexie().catch(() => {});
+  }, [flushToDexie]);
+
   const scheduleFlush = useCallback(() => {
     if (flushTimerRef.current) clearTimeout(flushTimerRef.current);
-    flushTimerRef.current = setTimeout(flushToDexie, 500);
-  }, [flushToDexie]);
+    flushTimerRef.current = setTimeout(flushInBackground, 500);
+  }, [flushInBackground]);
 
   useEffect(() => {
     return () => {
       if (flushTimerRef.current) clearTimeout(flushTimerRef.current);
-      void flushToDexie();
+      flushInBackground();
     };
-  }, [flushToDexie]);
+  }, [flushInBackground]);
 
   // Flush pending edits when the tab is hidden or unloaded. The unmount cleanup
   // above is fire-and-forget and does not reliably complete during real document
@@ -126,7 +207,7 @@ export function useEditorPersistence(
         clearTimeout(flushTimerRef.current);
         flushTimerRef.current = null;
       }
-      void flushToDexie();
+      void flushToDexie({ exit: true }).catch(() => {});
     };
     const onVisibilityChange = () => {
       if (document.visibilityState === "hidden") flushOnExit();
@@ -165,9 +246,7 @@ export function useEditorPersistence(
     state.current.unsavedIndex = true;
     state.current.indexGeneration = ++state.current.generation;
     state.current.sectionGenerations.delete(sectionId);
-    deleteSectionRows([sectionId]).catch((err) => {
-      console.error("Failed to delete section row from Dexie:", err);
-    });
+    state.current.pendingDeletedRows.add(sectionId);
     scheduleFlush();
   }, [scheduleFlush]);
 
@@ -190,8 +269,10 @@ export function useEditorPersistence(
 
   const persistConfig = useCallback(async (config: SiteConfig) => {
     state.current.configDirty = true;
-    await persistSiteConfig(config);
-  }, []);
+    state.current.pendingConfig = config;
+    // Resolves once written; a failure surfaces in the persistence banner.
+    await flushToDexie().catch(() => {});
+  }, [flushToDexie]);
 
   const cancelPendingFlush = useCallback(() => {
     if (flushTimerRef.current) {
@@ -200,6 +281,28 @@ export function useEditorPersistence(
     }
   }, []);
 
+  const discardPending = useCallback(async () => {
+    cancelPendingFlush();
+    discardEpoch.current++;
+    // Finish an in-flight write before the caller clears Dexie, or it could
+    // recreate the rows after Discard has removed them. A write that never
+    // settles is abandoned rather than hanging Discard; if it lands later it can
+    // still write discarded rows, which no browser API lets us cancel.
+    while (activeFlush.current) {
+      const inFlight = activeFlush.current;
+      if (!(await settlesInTime(inFlight))) abandonedFlushes.current.add(inFlight);
+      if (activeFlush.current === inFlight) activeFlush.current = null;
+    }
+    state.current.pendingSections.clear();
+    state.current.pendingConfig = null;
+    state.current.pendingDeletedRows.clear();
+    state.current.indexDirty = false;
+    state.current.configDirty = false;
+    state.current.unsavedIndex = false;
+    state.current.sectionGenerations.clear();
+    setPersistenceError(null);
+  }, [cancelPendingFlush]);
+
   const isConfigDirty = useCallback(() => state.current.configDirty, []);
   const clearConfigDirty = useCallback(() => { state.current.configDirty = false; }, []);
   // Reflects whether an index change is pending flush to Dexie. NOTE: this is
@@ -236,14 +339,16 @@ export function useEditorPersistence(
     [],
   );
 
-  // Memoized, and every member above is already identity-stable, so this object
-  // is too. A fresh literal per render changed `persistence`'s identity on every
+  // Memoized, and every member above is identity-stable except persistenceError,
+  // which changes only when a flush fails or recovers — so this object is stable
+  // across ordinary edits. A fresh literal per render changed `persistence`'s identity on every
   // EditorShell render — which churned onBlockMove, getEditIntent,
   // onSectionChange, onAddSection, performDeleteSection, onReorderSections and
   // all twelve page/nav handlers, and made EditorContent tear down and
   // re-register its atlaskit drag monitors on every keystroke.
   return useMemo(
     () => ({
+      persistenceError,
       markSectionDirty,
       markIndexDirty,
       removeSection,
@@ -252,6 +357,7 @@ export function useEditorPersistence(
       persistConfig,
       flushNow: flushToDexie,
       cancelPendingFlush,
+      discardPending,
       isConfigDirty,
       clearConfigDirty,
       isIndexDirty,
@@ -262,8 +368,8 @@ export function useEditorPersistence(
       sectionDirtiedAfter,
     }),
     [
-      markSectionDirty, markIndexDirty, removeSection, dropPendingSection, hasPendingSection,
-      persistConfig, flushToDexie, cancelPendingFlush, isConfigDirty, clearConfigDirty,
+      persistenceError, markSectionDirty, markIndexDirty, removeSection, dropPendingSection, hasPendingSection,
+      persistConfig, flushToDexie, cancelPendingFlush, discardPending, isConfigDirty, clearConfigDirty,
       isIndexDirty, hasUnsavedIndex, clearUnsavedIndex, noteUnsavedIndex, currentGeneration,
       sectionDirtiedAfter,
     ],

package/src/hooks/useEditorPublish.ts

@@ -1,4 +1,7 @@
-import { useState, useCallback, useRef, useEffect } from "react";
+import { useState, useCallback, useRef } from "react";
+import { useNotice } from "./useNotice";
+import { COPY } from "../components/shared/copy";
+import type { NoticeTone } from "../components/shared/Notice";
 import type { SiteIndex, SiteConfig } from "../schemas/site-config";
 import type { SectionContent } from "../schemas/sections";
 import type { LoadedSection } from "../lib/loader";
@@ -81,7 +84,7 @@ interface PublishDeps {
   pendingMediaDeletions: string[];
   onMediaPublished: (publishedItems: MediaItem[], publishedDeletions: string[]) => void;
   onShasUpdated: (savedSha: string | null, mainSha: string | null) => void;
-  onPublishComplete?: () => void;
+  onPublishComplete?: (sha: string) => void;
   // The draft version this editor is based on (saved-branch head, or null when
   // no draft exists yet). Sent with saves so the server can 409 on a concurrent
   // edit instead of silently overwriting it. Read at save time (latest value).
@@ -171,23 +174,10 @@ export function useEditorPublish({
   onDocumentsDeleted,
 }: PublishDeps) {
   const [publishAction, setPublishAction] = useState<PublishAction>("idle");
-  const [publishFeedback, setPublishFeedback] = useState<string | null>(null);
+  const { notice: publishFeedback, show: showFeedback, clear: clearPublishFeedback } = useNotice();
   const [saveProgress, setSaveProgress] = useState<string | null>(null);
-  const feedbackTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const inFlightRef = useRef(false);
 
-  useEffect(() => {
-    return () => {
-      if (feedbackTimerRef.current) clearTimeout(feedbackTimerRef.current);
-    };
-  }, []);
-
-  const showFeedback = useCallback((message: string, duration: number) => {
-    setPublishFeedback(message);
-    if (feedbackTimerRef.current) clearTimeout(feedbackTimerRef.current);
-    feedbackTimerRef.current = setTimeout(() => setPublishFeedback(null), duration);
-  }, []);
-
   async function gatherMediaPayload(
     pendingItems: MediaItem[],
     pendingDeletions: string[],
@@ -591,7 +581,7 @@ export function useEditorPublish({
     recoveredRef.current = false;
     editTokenRef.current = getEditGeneration?.() ?? Number.MAX_SAFE_INTEGER;
     setPublishAction("saving");
-    setPublishFeedback(null);
+    clearPublishFeedback();
     return true;
   }
 
@@ -675,12 +665,13 @@ export function useEditorPublish({
     // M1 honesty: only claim the view was updated when recovery actually
     // rebased it this invocation (i.e. the RETRY 409'd). A failed/absent/
     // skipped recovery left the view untouched — say so.
+    const tone: NoticeTone = isConflict && recoveredRef.current ? "warning" : "error";
     const message = isConflict
       ? recoveredRef.current
         ? "Someone else saved while you were editing — your view has been updated; try saving again."
         : "This site was changed elsewhere — reload to get the latest, then re-apply your edits."
       : error instanceof Error && error.message ? error.message : `${failLabel} failed`;
-    showFeedback(message, isConflict ? 8000 : 6000);
+    showFeedback(tone, message, { ttlMs: isConflict ? 8000 : 6000 });
   }
 
   const handleSave = useCallback(async () => {
@@ -726,11 +717,11 @@ export function useEditorPublish({
         if (committedDocumentDeletions.length > 0) onDocumentsDeleted?.(committedDocumentDeletions);
       } catch (cleanupError) {
         console.error("Save succeeded but local cleanup failed:", cleanupError);
-        showFeedback("Saved, but the local cache couldn't be updated — reload the editor.", 8000);
+        showFeedback("warning", "Saved, but the local cache couldn't be updated — reload the editor.", { ttlMs: 8000 });
         return;
       }
 
-      showFeedback("Saved", 3000);
+      showFeedback("success", COPY.publish.saved, { ttlMs: 3000 });
     } catch (error) {
       reportSaveError(error, "Save");
     } finally {
@@ -748,7 +739,7 @@ export function useEditorPublish({
     if (inFlightRef.current) return;
     inFlightRef.current = true;
     setPublishAction("publishing");
-    setPublishFeedback(null);
+    clearPublishFeedback();
 
     try {
       const response = await fetch("/api/publish", {
@@ -772,10 +763,10 @@ export function useEditorPublish({
       // restored on a later cache hit. (Save & Publish already re-caches instead.)
       await clearContentCache();
       onShasUpdated(null, sha);
-      onPublishComplete?.();
+      onPublishComplete?.(sha);
     } catch (error) {
       console.error("Publish failed:", error);
-      showFeedback("Publish failed", 5000);
+      showFeedback("error", COPY.publish.publishFailed, { ttlMs: 5000 });
     } finally {
       inFlightRef.current = false;
       setPublishAction("idle");
@@ -833,7 +824,7 @@ export function useEditorPublish({
           // top of unknown local state would compound it — stop and tell the
           // editor to reload.
           console.error("Save succeeded but local cleanup failed:", cleanupError);
-          showFeedback("Saved, but the local cache couldn't be updated — reload the editor before publishing.", 8000);
+          showFeedback("warning", "Saved, but the local cache couldn't be updated — reload the editor before publishing.", { ttlMs: 8000 });
           return;
         }
       }
@@ -870,14 +861,14 @@ export function useEditorPublish({
         } catch (cleanupError) {
           console.error("Publish succeeded but the cache re-key failed:", cleanupError);
           onShasUpdated(null, sha);
-          onPublishComplete?.();
-          showFeedback("Published, but the local cache couldn't be updated — reload the editor.", 8000);
+          onPublishComplete?.(sha);
+          showFeedback("warning", "Published, but the local cache couldn't be updated — reload the editor.", { ttlMs: 8000 });
           return;
         }
       }
 
       onShasUpdated(null, sha);
-      onPublishComplete?.();
+      onPublishComplete?.(sha);
     } catch (error) {
       reportSaveError(error, "Publish");
     } finally {

package/src/hooks/useMediaPipeline.ts

@@ -12,7 +12,7 @@ import {
   markPendingMediaDeleted,
   removePendingMediaDeletion,
 } from "../lib/dexie";
-import { generateVideoPoster } from "../media/videoPoster";
+import { generateVideoPoster } from "../media/video-poster";
 import { ASSET_CACHE_CONTROL } from "../storage/types";
 import { tallyImageIds, collectImageIds, clearImageIds, applyLogoDeletion } from "../lib/image-refs";
 import { clearDocumentRefs, tallyDocumentIds } from "../lib/document-refs";

package/src/hooks/useNotice.ts

@@ -0,0 +1,45 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { NoticeTone } from "../components/shared/Notice";
+
+export interface NoticeState {
+  tone: NoticeTone;
+  message: string;
+}
+
+const DEFAULT_TTL_MS = 5000;
+
+/**
+ * One notice, one timer. `error` is sticky by default (no ttl) since it
+ * usually needs a deliberate dismiss; every other tone auto-clears.
+ * Call a second instance for a notice that must stay visible independently
+ * of another (e.g. toolbar feedback vs. a collab toast).
+ */
+export function useNotice() {
+  const [notice, setNotice] = useState<NoticeState | null>(null);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    return () => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+    };
+  }, []);
+
+  const clear = useCallback(() => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+    setNotice(null);
+  }, []);
+
+  const show = useCallback(
+    (tone: NoticeTone, message: string, options?: { ttlMs?: number }) => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+      setNotice({ tone, message });
+      const ttlMs = options?.ttlMs ?? (tone === "error" ? undefined : DEFAULT_TTL_MS);
+      if (ttlMs !== undefined) {
+        timerRef.current = setTimeout(() => setNotice(null), ttlMs);
+      }
+    },
+    [],
+  );
+
+  return { notice, show, clear };
+}

package/src/hooks/useSortableNavRow.ts

@@ -15,6 +15,17 @@ interface Options {
 const DRAG_TYPE = "nav-tree-row";
 
 /**
+ * One of three sibling drag-and-drop position hooks, split by location type
+ * rather than unified behind a generic `useSortable({ axis })`: this one
+ * (NavLocation — the Pages modal's group-aware nav tree), `useSortableRow`
+ * (flat index — section-ordering lists), and `useBlockDnd` (block/container id
+ * + index — the section canvas, root and nested). A fourth location type
+ * earns its own hook on the same shape (rowRef/handleRef, lazy atlaskit
+ * import, closest-edge state, a ref for the latest callback) rather than a
+ * parameter bag bolted onto an existing one — see docs/superpowers/specs/
+ * 2026-09-04-editor-ui-primitives-consolidation.md § D6 for why a shared
+ * `useSortable` was deferred.
+ *
  * Closest-edge drag wiring for one Pages-modal nav row. A sibling of
  * useSortableRow that speaks NavLocation instead of a flat index; the section
  * modal keeps using the original, so this cannot regress it.

package/src/hooks/useSortableRow.ts

@@ -11,6 +11,17 @@ interface UseSortableRowOptions {
 }
 
 /**
+ * One of three sibling drag-and-drop position hooks, split by location type
+ * rather than unified behind a generic `useSortable({ axis })`: this one (flat
+ * index — section-ordering lists, `EditableList`), `useSortableNavRow`
+ * (NavLocation — the Pages modal's group-aware nav tree), and `useBlockDnd`
+ * (block/container id + index — the section canvas, root and nested). A
+ * fourth location type earns its own hook on the same shape (rowRef/handleRef,
+ * lazy atlaskit import, closest-edge state, a ref for the latest callback)
+ * rather than a parameter bag bolted onto an existing one — see
+ * docs/superpowers/specs/2026-09-04-editor-ui-primitives-consolidation.md § D6
+ * for why a shared `useSortable` was deferred.
+ *
  * Closest-edge drag-to-reorder wiring for a single list row, shared by the
  * section- and page-ordering modals. Attach `rowRef` to the row element and
  * `handleRef` to the drag handle, and render
@@ -30,6 +41,15 @@ export function useSortableRow<R extends HTMLElement, H extends HTMLElement>({
   const [isDragging, setIsDragging] = useState(false);
   const [closestEdge, setClosestEdge] = useState<"top" | "bottom" | null>(null);
 
+  // Read through a ref so a changed `onReorder` identity doesn't re-register
+  // the atlaskit bindings mid-drag (which cancels the drag) — the same class
+  // of bug EditableList's `onReorderRef` fixed (2026-08-03). `index` stays a
+  // real effect dependency: a stale index would report the wrong
+  // `fromIndex`/`toIndex` on drop, the hazard useSortableNavRow's `locationOf`
+  // comment warns about for its own (non-re-subscribing) case.
+  const onReorderRef = useRef(onReorder);
+  onReorderRef.current = onReorder;
+
   useEffect(() => {
     if (!enabled) return;
     const row = rowRef.current;
@@ -79,7 +99,7 @@ export function useSortableRow<R extends HTMLElement, H extends HTMLElement>({
           const rawEdge = extractClosestEdge(self.data);
           const edge = rawEdge === "top" || rawEdge === "bottom" ? rawEdge : null;
           const toIndex = computeReorderTarget(fromIndex, index, edge);
-          if (toIndex !== null) onReorder(fromIndex, toIndex);
+          if (toIndex !== null) onReorderRef.current(fromIndex, toIndex);
         },
       });
 
@@ -93,7 +113,7 @@ export function useSortableRow<R extends HTMLElement, H extends HTMLElement>({
       cancelled = true;
       cleanup?.();
     };
-  }, [index, dragType, onReorder, enabled]);
+  }, [index, dragType, enabled]);
 
   return { rowRef, handleRef, isDragging, closestEdge };
 }

package/src/hooks/useStackedEscape.ts

@@ -0,0 +1,62 @@
+import { useEffect, useRef, type RefObject } from "react";
+
+export interface UseStackedEscapeOptions {
+  enabled: boolean;
+  /**
+   * Runs first, before the layer check would otherwise fall through to
+   * `onEscape`; returning `true` swallows the keypress entirely (the document
+   * editor overlay's blur-a-focused-field-first step).
+   */
+  before?: (e: KeyboardEvent) => boolean;
+}
+
+/**
+ * Shared "a modal above me owns Escape" rule. `EditorModal` marks its
+ * outermost layer with `data-modal-layer`; anything that might render BELOW
+ * one — a `Popover`, the doc file pane, the document editor overlay, and
+ * `EditorModal` itself (relative to another `EditorModal` opened on top of
+ * it) — must not react to an Escape meant for that layer instead.
+ *
+ * Attach the returned ref to your own `data-modal-layer` element (only
+ * `EditorModal` does) so the check can exclude it — otherwise it would always
+ * find itself and never fire. Callers that aren't a layer themselves (Popover,
+ * DocFilePane, the overlay) just ignore the return value: any layer at all
+ * then means something is stacked above them.
+ *
+ * For a tagged caller, "above" means a layer that FOLLOWS its own layer in
+ * DOM order (`compareDocumentPosition` + `DOCUMENT_POSITION_FOLLOWING`), not
+ * just "any other layer" — modals are appended later in DOM order than the
+ * ones already open, so this is what lets two stacked `EditorModal`s (e.g.
+ * Site Settings opening the Media Library over itself) resolve Escape to the
+ * topmost one only, then the next one down once that one closes.
+ */
+export function useStackedEscape<T extends HTMLElement = HTMLElement>(
+  onEscape: () => void,
+  { enabled, before }: UseStackedEscapeOptions,
+): RefObject<T | null> {
+  const layerRef = useRef<T | null>(null);
+
+  useEffect(() => {
+    if (!enabled) return;
+
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key !== "Escape") return;
+      const own = layerRef.current;
+      const layers = document.querySelectorAll<HTMLElement>("[data-modal-layer]");
+      const above = Array.from(layers).some((el) => {
+        if (el === own) return false;
+        if (!own) return true;
+        return Boolean(own.compareDocumentPosition(el) & Node.DOCUMENT_POSITION_FOLLOWING);
+      });
+      if (above) return;
+      if (before?.(e)) return;
+      e.preventDefault();
+      onEscape();
+    };
+
+    document.addEventListener("keydown", onKeyDown);
+    return () => document.removeEventListener("keydown", onKeyDown);
+  }, [enabled, onEscape, before]);
+
+  return layerRef;
+}

package/src/lib/block-dnd.ts

@@ -11,6 +11,8 @@ export interface BlockDragData {
   index: number;
   /** True if the dragged block is itself a container (used for the depth guard). */
   isContainer: boolean;
+  /** True if the dragged block is a Reference, which only expands at the page root. */
+  isReference?: boolean;
   [key: string | symbol]: unknown;
 }
 
@@ -27,6 +29,7 @@ export function buildBlockDragData(args: {
   containerId: string;
   index: number;
   isContainer: boolean;
+  isReference?: boolean;
 }): BlockDragData {
   return { dragType: "block", ...args };
 }
@@ -43,11 +46,13 @@ export function isBlockDragData(data: Record<string | symbol, unknown>): data is
  * May `source` drop into `dropContainerId`?
  * - A container block may only land at the page root (v1 one-level nesting → no
  *   container-in-container; MAX_BLOCK_DEPTH=2).
+ * - So may a Reference: it is expanded into its sources only at the page root,
+ *   so inside a container it would render nothing.
  * - Nothing may drop onto itself.
  */
 export function canDropBlock(source: BlockDragData, dropContainerId: string): boolean {
   if (source.blockId === dropContainerId) return false;
-  if (source.isContainer && dropContainerId !== ROOT_CONTAINER_ID) return false;
+  if ((source.isContainer || source.isReference) && dropContainerId !== ROOT_CONTAINER_ID) return false;
   return true;
 }
 

package/src/lib/block-move.ts

@@ -2,6 +2,7 @@ import type { LoadedSection } from "./loader";
 import type { Section } from "../schemas/sections";
 import type { SiteIndex, SectionMeta } from "../schemas/site-config";
 import { ROOT_CONTAINER_ID, canDropBlock } from "./block-dnd";
+import { REFERENCE_TYPE } from "./reference-type";
 import { getContainerChildren, reorderChild, insertChildAt, removeChildAt, placeBlockAtColumn, trimTrailingSpacers } from "./container-ops";
 import { reorderVisibleSectionInPage, visibleInsertPosition, addSectionToPage, removeSectionFromPages } from "./pages";
 
@@ -96,6 +97,7 @@ export function applyBlockMove(
     containerId: fromContainerId,
     index: fromIndex,
     isContainer: isContainerSection(draggedSection),
+    isReference: draggedSection.type === REFERENCE_TYPE,
   };
   if (!canDropBlock(dragData, toContainerId)) return noop(state);
 
@@ -200,6 +202,7 @@ function applyColumnPlacement(
     containerId: fromContainerId,
     index: fromIndex,
     isContainer: isContainerSection(draggedSection),
+    isReference: draggedSection.type === REFERENCE_TYPE,
   };
   if (!canDropBlock(dragData, toContainerId)) return noop(state);