@drawnagency/primitives 0.1.76 → 0.1.78

package/src/components/shell/EditorShell.tsx

@@ -10,7 +10,7 @@ import type { SiteIndex, SiteConfig, Page } from "../../schemas/site-config";
 import type { Audience } from "../../auth/types";
 import type { MediaManifest } from "../../media/types";
 import type { QueueItem } from "../../media/queue";
-import { SiteConfigSchema } from "../../schemas/site-config";
+import { SiteConfigSchema, IndexSchema } from "../../schemas/site-config";
 import { ensureSanitizer } from "../../lib/sanitize";
 import { EditorProvider, useEditorContext } from "./EditorContext";
 import { makeBlockMoveDispatch } from "./blockMoveDispatch";
@@ -27,7 +27,7 @@ import { ProcessingIndicator } from "./ProcessingIndicator";
 import { SectionSkeleton } from "./SectionSkeleton";
 import { SectionTypePicker } from "./SectionTypePicker";
 import { ensureSectionsRegistered } from "../sections/register";
-import { getSection, getAllSections } from "../../lib/registry";
+import { getSection, getAllSections, getSchema } from "../../lib/registry";
 import { childInsertableTypes, insertChildAt } from "../../lib/container-ops";
 import { buildInsertMenuOptions, resolveInsertedContent } from "../../lib/insert-menu";
 
@@ -49,8 +49,18 @@ import {
   getPendingMediaItems,
   getPendingMediaBlobs,
   getPendingMediaDeletions,
+  getDirtySectionRows,
+  deleteSectionRows,
+  preserveEdit,
 } from "../../lib/dexie";
+import { rebaseContent } from "../../collab/rebase";
+import { deriveRecoveryInputs, applyConflictChoices } from "../../collab/recovery";
+import { getCollabProvider } from "../../collab/provider-registry";
+import type { CollabBootstrap, CollabPeer, CollabStatus, SavedMessage, TakeoverMessage } from "../../collab/types";
+import { ConflictDialog, type ConflictItem } from "../editor/ConflictDialog";
+import { PresenceAvatars } from "../editor/PresenceAvatars";
 import { useEditorPersistence } from "../../hooks/useEditorPersistence";
+import { useCollabSession, type UseCollabSessionResult } from "../../hooks/useCollabSession";
 import { useEditorPublish } from "../../hooks/useEditorPublish";
 import { useContentLifecycle } from "../../hooks/useContentLifecycle";
 import { useBuildStatus } from "../../hooks/useBuildStatus";
@@ -89,6 +99,18 @@ type ShellState =
   | { phase: "recovery"; latestTimestamp: string }
   | { phase: "ready" };
 
+// The parsed shape of GET /api/content?branch=saved (the fresh draft snapshot).
+interface SavedContent {
+  sha: string;
+  sections: LoadedSection[];
+  index: SiteIndex;
+  siteConfig: Record<string, unknown>;
+  savedBranchSha: string | null;
+  changedSectionIds: string[];
+  mainIndex: SiteIndex;
+  mediaManifest?: MediaManifest;
+}
+
 interface Props {
   headSha: string;
   // Head of the branch the editor actually loads (draft `saved` if it exists,
@@ -110,6 +132,11 @@ interface Props {
   // Controls the configurator's banner + test panel; the config UI itself
   // always works so editors can prepare before activation.
   chatbotPlatformEnabled?: boolean;
+  // Server-minted collaboration bootstrap (Task 10 wires this through the edit
+  // page). Null/absent → solo mode: the provider registry has no provider, or
+  // this session can't join, so useCollabSession stays offline and every
+  // lock/broadcast call is a no-op.
+  collabBootstrap?: CollabBootstrap | null;
 }
 
 export default function EditorShell({
@@ -120,6 +147,7 @@ export default function EditorShell({
   capabilities,
   currentUser,
   chatbotPlatformEnabled = false,
+  collabBootstrap,
 }: Props) {
   const [shellState, setShellState] = useState<ShellState>({ phase: "loading-content" });
   const [sections, setSections] = useState<LoadedSection[]>([]);
@@ -130,7 +158,7 @@ export default function EditorShell({
   const [showSiteSettings, setShowSiteSettings] = useState(false);
   const [dirtySectionIds, setDirtySectionIds] = useState<Set<string>>(new Set());
   const [siteConfig, setSiteConfig] = useState<SiteConfig | null>(null);
-  const [mediaManifest, setMediaManifest] = useState<MediaManifest>({ images: {} });
+  const [mediaManifest, setMediaManifest] = useState<MediaManifest>({ images: {}, folders: {} });
   const [showMediaLibrary, setShowMediaLibrary] = useState(false);
   const [mediaModalMode, setMediaModalMode] = useState<"select" | "manage">("manage");
   const [mediaSelectCallback, setMediaSelectCallback] = useState<((id: string) => void) | null>(null);
@@ -146,6 +174,13 @@ export default function EditorShell({
   }, [savedSha]);
   const [changedSectionIds, setChangedSectionIds] = useState<Set<string>>(new Set());
   const [mainIndex, setMainIndex] = useState<SiteIndex | null>(null);
+  // Ref mirrors of the diff state, so save-time callbacks (which run inside a
+  // stale handleSave closure) and recoverConflict's synchronous post-rebase
+  // bookkeeping always read/write the latest values.
+  const changedSectionIdsRef = useRef<Set<string>>(new Set());
+  useEffect(() => { changedSectionIdsRef.current = changedSectionIds; }, [changedSectionIds]);
+  const mainIndexRef = useRef<SiteIndex | null>(null);
+  useEffect(() => { mainIndexRef.current = mainIndex; }, [mainIndex]);
   const [viewSections, setViewSections] = useState<LoadedSection[] | null>(null);
   const [showRestoreModal, setShowRestoreModal] = useState(false);
   const [showOrderingModal, setShowOrderingModal] = useState(false);
@@ -157,8 +192,21 @@ export default function EditorShell({
   // upload-intent failures, direct-to-bucket PUT failures) in the media
   // library modal, alongside its existing client-side rejection banner.
   const [uploadErrorMessage, setUploadErrorMessage] = useState<string | null>(null);
+  // Surfaces useMediaPipeline's onUploadNotice (e.g. "N files already exist
+  // and were left where they are" on dedup skip) in the media library modal.
+  const [uploadNotice, setUploadNotice] = useState<string | null>(null);
   const [activePageId, setActivePageId] = useState<string | null>(null);
   const [movingSectionId, setMovingSectionId] = useState<string | null>(null);
+  // Set by recoverConflict when a rebase surfaces overlapping edits; drives the
+  // keep-mine/take-theirs dialog. `resolve` is the promise resolver recovery
+  // awaits, so the dialog's Continue hands the choices straight back.
+  const [conflictState, setConflictState] = useState<
+    { items: ConflictItem[]; resolve: (choices: Record<string, "mine" | "theirs">) => void } | null
+  >(null);
+  // Collaboration: transient toast ("Drew took over Hero …") and the section a
+  // takeover confirmation is pending for.
+  const [remoteNotice, setRemoteNotice] = useState<string | null>(null);
+  const [pendingTakeoverId, setPendingTakeoverId] = useState<string | null>(null);
 
   const siteIndexRef = useRef<SiteIndex>({ siteId, pages: [], sections: {} });
   // Ids of sections that exist on the remote (loaded from server, or persisted by
@@ -171,7 +219,51 @@ export default function EditorShell({
   useEffect(() => { siteIndexRef.current = siteIndex; }, [siteIndex]);
   useEffect(() => { void ensureSanitizer(); }, []);
 
-  const persistence = useEditorPersistence(siteIndexRef);
+  // --- Collaboration refs ---
+  // Freshest dirty-section set for the inbound remote-section handler (never
+  // apply a peer's edit over our own unsaved work).
+  const dirtySectionIdsRef = useRef<Set<string>>(new Set());
+  useEffect(() => { dirtySectionIdsRef.current = dirtySectionIds; }, [dirtySectionIds]);
+  // Toggled by useEditorPublish around a save; the remote saved-event handler
+  // defers while it is true (our own save's response path owns the state).
+  const inFlightSaveRef = useRef(false);
+  // Mirror of the live collab session, read by handlers/callbacks defined before
+  // useCollabSession is instantiated (breaks the definition-order cycle).
+  const collabRef = useRef<UseCollabSessionResult | null>(null);
+  const noticeTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  useEffect(() => () => { if (noticeTimerRef.current) clearTimeout(noticeTimerRef.current); }, []);
+  // Per-section memoized onEditIntent closures — SectionWrapper re-binds its
+  // focus listeners whenever onEditIntent's identity changes, so each section
+  // must get a STABLE function instance across renders.
+  const editIntentByIdRef = useRef(new Map<string, () => Promise<boolean>>());
+  // The section the local user last expressed edit intent on. Drives the
+  // focus-move lock release: when intent moves to a new section, the previous
+  // one's lock is released if it carries no unsaved work.
+  const focusedSectionIdRef = useRef<string | null>(null);
+
+  // Transient collaboration toast (single slot, 8s auto-dismiss).
+  const showRemoteNotice = useCallback((text: string) => {
+    setRemoteNotice(text);
+    if (noticeTimerRef.current) clearTimeout(noticeTimerRef.current);
+    noticeTimerRef.current = setTimeout(() => setRemoteNotice(null), 8000);
+  }, []);
+
+  // Broadcast piggyback: after a debounced flush, forward held-lock section
+  // edits + index changes to peers. Only sections THIS editor holds are
+  // broadcast (peers ignore updates for sections they don't see us holding).
+  const onFlush = useCallback(
+    (entries: { sectionId: string; content: SectionContent }[], indexFlushed: boolean) => {
+      const collab = collabRef.current;
+      if (!collab) return;
+      for (const { sectionId, content } of entries) {
+        if (collab.heldByMe.has(sectionId)) collab.broadcastSectionUpdate(sectionId, content);
+      }
+      if (indexFlushed) collab.broadcastIndexUpdate(siteIndexRef.current);
+    },
+    [],
+  );
+
+  const persistence = useEditorPersistence(siteIndexRef, { onFlush });
 
   const sectionsById = useMemo(() => {
     const map: Record<string, LoadedSection> = {};
@@ -228,10 +320,354 @@ export default function EditorShell({
     setDirtySectionIds,
     markSectionDirty: persistence.markSectionDirty,
     onUploadError: (message) => setUploadErrorMessage(message),
+    onUploadNotice: setUploadNotice,
   });
 
   const buildStatus = useBuildStatus();
 
+  // Fetch + parse the fresh saved-branch snapshot. Shared by the initial
+  // loadContent and by recoverConflict (409 auto-recovery) so both read the
+  // draft head the same way.
+  const fetchSavedContent = useCallback(async (): Promise<SavedContent> => {
+    const response = await fetch("/api/content?branch=saved");
+    if (!response.ok) throw new Error(`Failed to load content: ${response.status}`);
+    const data = await response.json();
+    return {
+      sha: data.sha,
+      sections: data.sections as LoadedSection[],
+      index: data.index as SiteIndex,
+      siteConfig: data.siteConfig as Record<string, unknown>,
+      savedBranchSha: data.savedBranchSha ?? null,
+      changedSectionIds: (data.changedSectionIds ?? []) as string[],
+      mainIndex: (data.mainIndex ?? data.index) as SiteIndex,
+      mediaManifest: data.mediaManifest as MediaManifest | undefined,
+    };
+  }, []);
+
+  // 409 auto-recovery: another editor moved the draft head. Re-fetch the fresh
+  // saved branch, rebase local unsaved work on top, resolve any true overlaps
+  // via the keep-mine/take-theirs dialog, refresh the optimistic-concurrency
+  // base, and report success so the save retries once. The decision logic lives
+  // in the pure collab/recovery + collab/rebase modules; this function is the
+  // IO glue (fetch, Dexie, dialog, setState).
+  const recoverConflict = useCallback(async (): Promise<boolean> => {
+    try {
+      const remote = await fetchSavedContent();
+      const dirtyRows = await getDirtySectionRows();
+      const dirtyIds = new Set(dirtyRows.map((r) => r.sectionId));
+
+      // Clean baseline = the last agreed-with-server snapshot in the Dexie
+      // contentCache — NOT sectionsRef.current, which carries local dirty edits.
+      // The cache is re-primed at every lifecycle point (load, successful save
+      // via onBaselineCommitted, and below on every recovery), so it is present
+      // whenever a 409 can happen; if it is somehow missing,
+      // deriveRecoveryInputs degrades conservatively (dialog, never a silent
+      // local-wins merge).
+      const cached = await getCachedContent();
+      const { remoteChangedIds, locallyAddedIds } = deriveRecoveryInputs({
+        baseline: cached ? { sections: cached.sections, index: cached.index } : null,
+        remote: { sections: remote.sections, index: remote.index },
+        dirtyRows,
+        deletedIds: deletedSections,
+      });
+
+      const result = rebaseContent({
+        localSections: sectionsRef.current,
+        localIndex: siteIndexRef.current,
+        localIndexDirty: true, // conservative: preserves any local structural work
+        dirtySectionIds: dirtyIds,
+        locallyAddedIds,
+        locallyDeletedIds: deletedSections,
+        remoteSections: remote.sections,
+        remoteIndex: remote.index,
+        // rebaseContent self-detects remote deletions of dirty sections, so we
+        // only fold in remote CONTENT changes here (per Task 4 contract).
+        remoteChangedIds,
+      });
+
+      let mergedSections = result.sections;
+      let mergedIndex = result.index;
+      if (result.conflictIds.length > 0) {
+        const choices = await new Promise<Record<string, "mine" | "theirs">>((resolve) => {
+          setConflictState({
+            items: result.conflictIds.map((id) => ({
+              sectionId: id,
+              label: getSection(siteIndexRef.current.sections[id]?.type ?? "")?.label ?? id,
+            })),
+            resolve,
+          });
+        });
+        setConflictState(null);
+        const applied = applyConflictChoices({
+          merged: { sections: mergedSections, index: mergedIndex },
+          remoteSections: remote.sections,
+          choices,
+        });
+        mergedSections = applied.sections;
+        mergedIndex = applied.index;
+        for (const p of applied.preserved) {
+          // The local copy is always snapshotted — no choice is destructive.
+          await preserveEdit(p.sectionId, p.section as unknown as SectionContent, "conflict");
+        }
+        // Drop the dirty rows "theirs" overrode so the retry doesn't re-send them.
+        if (applied.droppedDirtyIds.length > 0) await deleteSectionRows(applied.droppedDirtyIds);
+      }
+
+      setSections(mergedSections);
+      setSiteIndex(mergedIndex);
+      setSavedSha(remote.savedBranchSha);
+      setChangedSectionIds(new Set(remote.changedSectionIds));
+      setMainIndex(remote.mainIndex);
+      // Refresh the refs synchronously: getBaseVersion reads savedShaRef and
+      // performSave reads siteIndexRef + the dirty rows on the IMMEDIATE retry
+      // (and onBaselineCommitted reads the diff refs right after it), before
+      // React flushes the setState calls above into their mirror effects.
+      savedShaRef.current = remote.savedBranchSha;
+      sectionsRef.current = mergedSections;
+      siteIndexRef.current = mergedIndex;
+      changedSectionIdsRef.current = new Set(remote.changedSectionIds);
+      mainIndexRef.current = remote.mainIndex;
+      remoteSectionIdsRef.current = new Set(mergedIndex.pages.flatMap((p) => p.order));
+      // C2: the cache is the CLEAN baseline — always the fetched remote
+      // snapshot, never the rebased result. Caching the rebase (local dirty
+      // overlays folded in) would poison the next recovery's diff: dirty
+      // sections would read as remote-unchanged (silent local-wins) and a
+      // locally-added section would read as "deleted remotely".
+      await cacheContent(
+        remote.sha ?? remote.savedBranchSha ?? headSha,
+        remote.sections,
+        remote.index,
+        remote.siteConfig,
+        { savedBranchSha: remote.savedBranchSha, changedSectionIds: remote.changedSectionIds, mainIndex: remote.mainIndex },
+      );
+      return true;
+    } catch (err) {
+      console.error("Conflict recovery failed:", err);
+      return false;
+    }
+  }, [fetchSavedContent, deletedSections, headSha]);
+
+  // --- Collaboration: inbound saved-event rebase + takeover ---
+
+  // A peer committed a save to the draft branch. Re-fetch the fresh saved
+  // snapshot and rebase local unsaved work under it — the SAME machinery as the
+  // 409 recovery, but from a background event, so it NEVER opens the conflict
+  // dialog: local dirty work wins for any conflictIds (rebaseContent keeps the
+  // local copies), and the next interactive save's 409 recovery arbitrates.
+  const handleRemoteSaved = useCallback(async (msg: SavedMessage): Promise<void> => {
+    // Bail conditions, re-checked after EVERY await: (a) our own save is in
+    // flight — its response path owns state, and a stale refetch landing
+    // mid-save would regress savedShaRef/baseline and force spurious 409s over
+    // the user's own work; (b) own-save echo — the server fans our save back to
+    // us, but savedShaRef already points at msg.newSha, so there is nothing to
+    // sync (and refetching would be wasted work racing the post-save cleanup).
+    const stale = () => inFlightSaveRef.current || savedShaRef.current === msg.newSha;
+    if (stale()) return;
+    try {
+      const remote = await fetchSavedContent();
+      if (stale()) return;
+      const dirtyRows = await getDirtySectionRows();
+      if (stale()) return;
+      // Clean baseline from the content cache (never sectionsRef, which carries
+      // dirty overlays). deriveRecoveryInputs computes BOTH remoteChangedIds and
+      // locallyAddedIds; rebaseContent self-detects remote deletions.
+      const cached = await getCachedContent();
+      // Last await above — one final check guards the whole synchronous
+      // setState + cacheContent block below.
+      if (stale()) return;
+      // Dirty = Dexie rows ∪ the synchronously-maintained state mirror ∪ held
+      // locks: a just-typed edit can lag the Dexie rows by up to the 500ms
+      // flush debounce, and anything we hold must never be overwritten by a
+      // background sync. The rebase reads content from sectionsRef, which
+      // already has the freshest keystrokes.
+      const dirtyIds = new Set([
+        ...dirtyRows.map((r) => r.sectionId),
+        ...dirtySectionIdsRef.current,
+        ...(collabRef.current?.heldByMe ?? []),
+      ]);
+      const { remoteChangedIds, locallyAddedIds } = deriveRecoveryInputs({
+        baseline: cached ? { sections: cached.sections, index: cached.index } : null,
+        remote: { sections: remote.sections, index: remote.index },
+        dirtyRows: [...dirtyIds].map((sectionId) => ({ sectionId })),
+        deletedIds: deletedSections,
+      });
+      const result = rebaseContent({
+        localSections: sectionsRef.current,
+        localIndex: siteIndexRef.current,
+        // Durable unsaved-structure signal — NOT isIndexDirty(), which clears
+        // ~500ms after the edit (flush-pending only) and would hand a remote
+        // save the local structural work on a plate.
+        localIndexDirty: persistence.hasUnsavedIndex(),
+        dirtySectionIds: dirtyIds,
+        locallyAddedIds,
+        locallyDeletedIds: deletedSections,
+        remoteSections: remote.sections,
+        remoteIndex: remote.index,
+        remoteChangedIds,
+      });
+
+      // The rebased result goes into React state (live view)...
+      setSections(result.sections);
+      setSiteIndex(result.index);
+      setSavedSha(remote.savedBranchSha);
+      setChangedSectionIds(new Set(remote.changedSectionIds));
+      setMainIndex(remote.mainIndex);
+      sectionsRef.current = result.sections;
+      siteIndexRef.current = result.index;
+      savedShaRef.current = remote.savedBranchSha;
+      changedSectionIdsRef.current = new Set(remote.changedSectionIds);
+      mainIndexRef.current = remote.mainIndex;
+      remoteSectionIdsRef.current = new Set(result.index.pages.flatMap((p) => p.order));
+
+      // ...but the CLEAN fetched remote snapshot is what gets cached as the
+      // baseline (amendment 1: caching the rebased result would poison the next
+      // 409 recovery — dirty sections would read as remote-unchanged and a ghost
+      // race would never surface).
+      await cacheContent(
+        remote.sha ?? remote.savedBranchSha ?? headSha,
+        remote.sections,
+        remote.index,
+        remote.siteConfig,
+        { savedBranchSha: remote.savedBranchSha, changedSectionIds: remote.changedSectionIds, mainIndex: remote.mainIndex },
+      );
+    } catch (err) {
+      console.error("Remote saved-event sync failed:", err);
+    }
+  }, [fetchSavedContent, deletedSections, persistence, headSha]);
+
+  // A peer stole this section's lock. Snapshot the local edit (recoverable),
+  // drop the dirty row so it isn't re-sent, and surface a toast.
+  const handleTakenOver = useCallback(async (msg: TakeoverMessage): Promise<void> => {
+    const local = sectionsRef.current.find((s) => s.section.id === msg.sectionId);
+    if (local) await preserveEdit(msg.sectionId, local.section as unknown as SectionContent, "takeover");
+    // Drop BOTH stores of the victim's edit: the persisted Dexie row AND the
+    // un-flushed in-memory pending entry — otherwise a keystroke typed just
+    // before the takeover re-persists on the next debounce flush and the next
+    // save re-sends stale content for a section we no longer hold.
+    persistence.dropPendingSection(msg.sectionId);
+    await deleteSectionRows([msg.sectionId]);
+    setDirtySectionIds((prev) => {
+      const next = new Set(prev);
+      next.delete(msg.sectionId);
+      return next;
+    });
+    const label = getSection(siteIndexRef.current.sections[msg.sectionId]?.type ?? "")?.label
+      ?? siteIndexRef.current.sections[msg.sectionId]?.type
+      ?? msg.sectionId;
+    showRemoteNotice(`${msg.byEmail} took over "${label}" — your unsaved edits to it were safely stored.`);
+  }, [persistence, showRemoteNotice]);
+
+  const collab = useCollabSession({
+    provider: getCollabProvider(),
+    bootstrap: collabBootstrap ?? null,
+    onRemoteSectionUpdate: (msg) => {
+      // Ephemeral live view: never touch Dexie, never apply over own dirty work
+      // or a section we hold.
+      if (dirtySectionIdsRef.current.has(msg.sectionId)) return;
+      if (collabRef.current?.heldByMe.has(msg.sectionId)) return;
+      const raw = msg.content;
+      // z.unknown() passes when the key is absent — guard undefined/null/non-object.
+      if (raw === undefined || raw === null || typeof raw !== "object") return;
+      const type = (raw as { type?: unknown }).type;
+      if (typeof type !== "string") return;
+      const schema = getSchema(type);
+      if (!schema) return;
+      const parsed = schema.safeParse(raw);
+      if (!parsed.success) return;
+      const validated = parsed.data as Record<string, unknown>;
+      setSections((prev) => prev.map((s) =>
+        s.section.id === msg.sectionId ? { ...s, section: { ...s.section, ...validated } } : s,
+      ));
+    },
+    onRemoteIndexUpdate: (msg) => {
+      // Ignore inbound indexes until the initial load settles: before
+      // loadContent finishes, sectionsRef.current is [] so the prune below would
+      // strip every order to empty and momentarily install an empty-order index.
+      if (shellState.phase !== "ready") return;
+      // While we have unsaved structural work, the save-time rebase resolves
+      // the overlap — don't clobber local structure with the peer's. Durable
+      // signal (survives the flush debounce), not isIndexDirty().
+      if (persistence.hasUnsavedIndex()) return;
+      const parsed = IndexSchema.safeParse(msg.index);
+      if (!parsed.success) return;
+      // PRUNE ids we hold no content for before applying. An id in the peer's
+      // index with no counterpart in our local sections state is either (a) the
+      // peer's unsaved ADD — its section file is not on the branch yet, so
+      // letting it into siteIndexRef would poison OUR next save with a dangling
+      // index ref the server rejects (live new-section appearance is deliberately
+      // deferred to the peer's save, which arrives via the saved-event sync); or
+      // (b) a section WE deleted unsaved — our deletion stands until save-time
+      // arbitration.
+      const localIds = new Set(sectionsRef.current.map((s) => s.section.id));
+      const pruned: SiteIndex = {
+        ...parsed.data,
+        pages: parsed.data.pages.map((p) => ({ ...p, order: p.order.filter((id) => localIds.has(id)) })),
+        sections: Object.fromEntries(
+          Object.entries(parsed.data.sections).filter(([id]) => localIds.has(id)),
+        ),
+      };
+      setSiteIndex(pruned);
+      siteIndexRef.current = pruned;
+    },
+    onRemoteSaved: (msg) => { void handleRemoteSaved(msg); },
+    onTakenOver: (msg) => { void handleTakenOver(msg); },
+  });
+  useEffect(() => { collabRef.current = collab; }, [collab]);
+
+  // Stable per-section onEditIntent: focus + lock request. The cached closure
+  // always calls the LIVE session via collabRef, so it needn't change identity.
+  const getEditIntent = useCallback((id: string): (() => Promise<boolean>) => {
+    const cache = editIntentByIdRef.current;
+    let fn = cache.get(id);
+    if (!fn) {
+      fn = async () => {
+        const session = collabRef.current;
+        // Focus-move release: browse-clicking must not accumulate locks that
+        // block peers on sections we never edited. Release the previously
+        // focused section's lock IF it carries no unsaved work — dirty state,
+        // an un-flushed keystroke, or a local add all keep the lock held.
+        const prev = focusedSectionIdRef.current;
+        if (
+          prev && prev !== id && session?.heldByMe.has(prev) &&
+          !dirtySectionIdsRef.current.has(prev) &&
+          !persistence.hasPendingSection(prev)
+        ) {
+          session.releaseAfterSave([prev]);
+        }
+        focusedSectionIdRef.current = id;
+        session?.setFocus(id);
+        const ok = (await session?.requestEdit(id)) ?? true;
+        // A denial with no visible lock badge is the ghost-lock window: the
+        // holder's presence dropped but their editor_locks row is still fresh
+        // (<45s). Tell the user instead of failing silently; no further
+        // blocking — the row goes stale within 45s and the save-time 409
+        // arbitration remains the safety net.
+        if (!ok) showRemoteNotice("Someone else is editing this section — try again in a moment.");
+        return ok;
+      };
+      cache.set(id, fn);
+    }
+    return fn;
+  }, [persistence, showRemoteNotice]);
+
+  const confirmTakeover = useCallback((id: string) => setPendingTakeoverId(id), []);
+  const performTakeover = useCallback(async () => {
+    const id = pendingTakeoverId;
+    setPendingTakeoverId(null);
+    if (!id) return;
+    const ok = await collabRef.current?.takeover(id);
+    if (!ok) return;
+    // The stolen section's latest broadcast content is already in local state
+    // (applied as remote-ephemeral). Mark it dirty so it persists and the
+    // lock-hold broadcast rule applies.
+    const local = sectionsRef.current.find((s) => s.section.id === id);
+    if (!local) return;
+    const { id: _omit, ...content } = local.section;
+    persistence.markSectionDirty(id, content as SectionContent);
+    setLocalChangesExist(true);
+    setDirtySectionIds((prev) => new Set(prev).add(id));
+  }, [pendingTakeoverId, persistence]);
+
   const { publishAction, publishFeedback, saveProgress, handleSave, handlePublish, handleSaveAndPublish } = useEditorPublish({
     flushNow: persistence.flushNow,
     cancelPendingFlush: persistence.cancelPendingFlush,
@@ -241,12 +677,37 @@ export default function EditorShell({
     siteConfig,
     sections,
     deletedSectionIds: Array.from(deletedSections),
-    onSuccess: () => {
-      setDirtySectionIds(new Set());
-      setDeletedSections(new Set());
-      setLocalChangesExist(false);
+    onSuccess: (savedSectionIds: string[], { editToken, sentDeletedIds }) => {
+      // Generation-guarded post-save clears: any edit made WHILE the save was
+      // in flight (generation > the token captured at save begin) was NOT
+      // carried by it and must survive every clear below — the in-memory
+      // mirror of discardSavedChanges' updatedAt compare-and-clear.
+      setDirtySectionIds((prev) =>
+        new Set([...prev].filter((id) => persistence.sectionDirtiedAfter(id, editToken))));
+      // Clear only the deletions this save actually sent; one scheduled
+      // mid-save must ride the next save.
+      const sentDeleted = new Set(sentDeletedIds);
+      setDeletedSections((prev) => new Set([...prev].filter((id) => !sentDeleted.has(id))));
+      // The committed index is no longer unsaved structure (mirrors
+      // discardSavedChanges clearing the Dexie siteIndex row just before this)
+      // — UNLESS a structural edit landed mid-save: then the clear no-ops and
+      // we re-mark, because discardSavedChanges wiped the Dexie siteIndex row
+      // wholesale and the surviving live structure must re-persist.
+      persistence.clearUnsavedIndex(editToken);
+      if (persistence.hasUnsavedIndex()) persistence.markIndexDirty();
+      const survivorsExist =
+        [...dirtySectionIdsRef.current].some((id) => persistence.sectionDirtiedAfter(id, editToken)) ||
+        persistence.hasUnsavedIndex();
+      setLocalChangesExist(survivorsExist);
       // Everything in the index now exists remotely (it was just saved).
       remoteSectionIdsRef.current = new Set(siteIndexRef.current.pages.flatMap((p) => p.order));
+      // Release the locks we held on the committed sections — EXCEPT any
+      // re-dirtied mid-save (they carry unsent work; keep holding). The server
+      // fans the saved-event out to peers (Task 10), so no client broadcast here.
+      collabRef.current?.releaseAfterSave(
+        savedSectionIds.filter((id) => !persistence.sectionDirtiedAfter(id, editToken)));
+      collabRef.current?.setFocus(null);
+      focusedSectionIdRef.current = null;
     },
     mediaManifest,
     manifestDirty: mediaPipeline.manifestDirty,
@@ -280,7 +741,7 @@ export default function EditorShell({
         for (const id of publishedDeletions) {
           delete images[id];
         }
-        return { images };
+        return { ...prev, images };
       });
     },
     onShasUpdated: (newSavedSha, newMainSha) => {
@@ -289,6 +750,27 @@ export default function EditorShell({
     },
     onPublishComplete: buildStatus.startTracking,
     getBaseVersion: () => savedShaRef.current,
+    recoverConflict,
+    // C1: re-prime the clean content-cache baseline after every successful plain
+    // save (discardSavedChanges just cleared it). The hook hands us the COMMITTED
+    // snapshot (sent content + sent index); we add the diff bookkeeping: the
+    // just-saved sections now differ from main, so fold them into
+    // changedSectionIds (state + ref + cache stay consistent, and a reload that
+    // hits this cache shows the same badges the server would report).
+    onBaselineCommitted: async ({ sha, sections: baselineSections, index, savedIds }) => {
+      const changed = new Set(
+        [...changedSectionIdsRef.current, ...savedIds].filter((id) => id in index.sections),
+      );
+      changedSectionIdsRef.current = changed;
+      setChangedSectionIds(changed);
+      await cacheContent(sha, baselineSections, index, (siteConfig ?? {}) as Record<string, unknown>, {
+        savedBranchSha: sha,
+        changedSectionIds: [...changed],
+        mainIndex: mainIndexRef.current,
+      });
+    },
+    savingRef: inFlightSaveRef,
+    getEditGeneration: persistence.currentGeneration,
   });
 
   const { buttonState } = useContentLifecycle({
@@ -388,7 +870,7 @@ export default function EditorShell({
       let loadedSections: LoadedSection[];
       let loadedIndex: SiteIndex;
       let loadedConfig: SiteConfig;
-      let loadedManifest: MediaManifest = { images: {} };
+      let loadedManifest: MediaManifest = { images: {}, folders: {} };
 
       // Key the content cache on the head of the branch we actually load (the
       // draft `saved` branch if it exists, else main), provided by the SSR edit
@@ -417,25 +899,23 @@ export default function EditorShell({
         setChangedSectionIds(new Set(cached.changedSectionIds ?? []));
         setMainIndex(cached.mainIndex ?? loadedIndex);
       } else {
-        const response = await fetch("/api/content?branch=saved");
-        if (!response.ok) throw new Error(`Failed to load content: ${response.status}`);
-        const data = await response.json();
+        const data = await fetchSavedContent();
         loadedSections = data.sections;
         loadedIndex = data.index;
         loadedConfig = SiteConfigSchema.parse(data.siteConfig);
         await cacheContent(data.sha, data.sections, data.index, data.siteConfig, {
-          savedBranchSha: data.savedBranchSha ?? null,
-          changedSectionIds: data.changedSectionIds ?? [],
-          mainIndex: data.mainIndex ?? data.index,
+          savedBranchSha: data.savedBranchSha,
+          changedSectionIds: data.changedSectionIds,
+          mainIndex: data.mainIndex,
         });
         if (data.mediaManifest) {
-          loadedManifest = data.mediaManifest as MediaManifest;
+          loadedManifest = data.mediaManifest;
           await persistMediaManifest(loadedManifest);
         }
-        setSavedSha(data.savedBranchSha ?? null);
+        setSavedSha(data.savedBranchSha);
         setMainSha(headSha);
-        setChangedSectionIds(new Set(data.changedSectionIds ?? []));
-        setMainIndex(data.mainIndex ?? data.index);
+        setChangedSectionIds(new Set(data.changedSectionIds));
+        setMainIndex(data.mainIndex);
       }
 
       if (cancelled) return;
@@ -490,7 +970,7 @@ export default function EditorShell({
       setShellState({ phase: "error", message: err instanceof Error ? err.message : "Failed to load content" });
     });
     return () => { cancelled = true; };
-  }, [headSha, draftHeadSha, siteId, applySiteConfigPreview]);
+  }, [headSha, draftHeadSha, siteId, applySiteConfigPreview, fetchSavedContent]);
 
   // --- Recovery handlers ---
 
@@ -525,6 +1005,10 @@ export default function EditorShell({
         [...remoteSectionIdsRef.current].filter((id) => !restoredIds.has(id)),
       );
       setDeletedSections(rediscoveredDeletions);
+      // A restored Dexie siteIndex row IS unsaved structural work from the
+      // prior session — prime the durable signal even though no markIndexDirty
+      // ran this session.
+      persistence.noteUnsavedIndex();
     } else {
       setSections((prev) =>
         prev.map((loaded) => {
@@ -576,8 +1060,11 @@ export default function EditorShell({
       }
     }
     const savedManifest = await getMediaManifest();
-    setMediaManifest(savedManifest ?? { images: {} });
+    setMediaManifest(savedManifest ?? { images: {}, folders: {} });
     persistence.clearConfigDirty();
+    // Discard wiped the Dexie siteIndex row — no unsaved structure remains.
+    // Tokenless: discard is unconditional, unlike the save-success clear.
+    persistence.clearUnsavedIndex();
     setShellState({ phase: "ready" });
   }, [applySiteConfigPreview, persistence]);
 
@@ -623,6 +1110,12 @@ export default function EditorShell({
       persistence.markIndexDirty();
       setLocalChangesExist(true);
       setDirtySectionIds((prev) => new Set(prev).add(id));
+      // Spec: new sections are creator-locked. Acquiring the lock here (not on
+      // first focus) protects the fresh id against concurrent MCP writes via
+      // the locks table and lets its content ride the held-lock broadcast
+      // (peers drop it until our save lands — live new-section appearance is
+      // save-time sync by design).
+      void collabRef.current?.requestEdit(id);
     },
     [persistence, resolvedActivePage],
   );
@@ -902,6 +1395,9 @@ export default function EditorShell({
             onOrderingClick={() => setShowOrderingModal(true)}
             onPagesClick={() => setShowPagesModal(true)}
             onChatbotClick={() => setShowChatbotConfig(true)}
+            collabPeers={collab.peers}
+            collabSelfId={collabBootstrap?.userId ?? null}
+            collabStatus={collab.status}
           />
 
           {/* Bug reports persist via Supabase. On the password-only (zero-Supabase)
@@ -932,6 +1428,15 @@ export default function EditorShell({
             </div>
           )}
 
+          {remoteNotice && (
+            <div
+              role="status"
+              className="fixed left-1/2 top-14 z-50 -translate-x-1/2 rounded-md border border-base-200 bg-base px-4 py-2 text-xs font-medium text-base-content shadow-lg"
+            >
+              {remoteNotice}
+            </div>
+          )}
+
           <HistoryOrEditorContent
             index={siteIndex}
             activeSections={activeSections}
@@ -954,6 +1459,9 @@ export default function EditorShell({
               mainIndex={mainIndex}
               changedSectionIds={changedSectionIds}
               viewSections={viewSections}
+              locks={collab.locks}
+              getEditIntent={getEditIntent}
+              onTakeover={confirmTakeover}
             />
           </HistoryOrEditorContent>
           <GlobalModal />
@@ -1018,6 +1526,9 @@ export default function EditorShell({
             }}
             title="Media Library"
             size="large"
+            // Padding lives on the two scroll columns inside MediaLibraryModal
+            // so their scrollbars sit at the pane edges.
+            noPadding
           >
             <MediaLibraryModal
               mode={mediaModalMode}
@@ -1041,6 +1552,15 @@ export default function EditorShell({
               uploadProgress={mediaPipeline.uploadProgress}
               uploadError={uploadErrorMessage}
               onDismissUploadError={() => setUploadErrorMessage(null)}
+              folders={mediaManifest.folders}
+              onCreateFolder={mediaPipeline.handleFolderCreate}
+              onRenameFolder={mediaPipeline.handleFolderRename}
+              onMoveFolder={mediaPipeline.handleFolderMove}
+              onDeleteFolder={mediaPipeline.handleFolderDelete}
+              onMoveMedia={mediaPipeline.handleMediaMove}
+              onFolderUpload={mediaPipeline.handleFolderUpload}
+              uploadNotice={uploadNotice}
+              onDismissUploadNotice={() => setUploadNotice(null)}
             />
           </EditorModal>
           <EditorModal
@@ -1084,6 +1604,27 @@ export default function EditorShell({
             isRestoring={isRestoring}
             onRestore={handleHistoryRestore}
           />
+          {conflictState && (
+            <ConflictDialog conflicts={conflictState.items} onResolve={conflictState.resolve} />
+          )}
+          <EditorModal
+            isOpen={pendingTakeoverId !== null}
+            onClose={() => setPendingTakeoverId(null)}
+            title="Take over section"
+          >
+            <p className="mb-4 text-sm text-base-contrast-light">
+              Another editor is currently editing this section. Take over to edit it yourself?
+              Their unsaved edits will be safely stored.
+            </p>
+            <div className="flex justify-end gap-3">
+              <Button variant="secondary" size="md" onClick={() => setPendingTakeoverId(null)}>
+                Cancel
+              </Button>
+              <Button variant="primary" size="md" onClick={performTakeover}>
+                Take over
+              </Button>
+            </div>
+          </EditorModal>
         </div>
         </MediaLibraryContext.Provider>
       </EditorModalProvider>
@@ -1228,6 +1769,9 @@ function EditorContent({
   mainIndex,
   changedSectionIds,
   viewSections,
+  locks,
+  getEditIntent,
+  onTakeover,
 }: {
   sections: LoadedSection[];
   activePageSectionIds: string[];
@@ -1245,6 +1789,11 @@ function EditorContent({
   mainIndex: SiteIndex | null;
   changedSectionIds: Set<string>;
   viewSections: LoadedSection[] | null;
+  // Collaboration: peers' held locks (keyed by sectionId, self excluded), a
+  // stable per-section edit-intent factory, and the takeover confirm trigger.
+  locks: Map<string, CollabPeer>;
+  getEditIntent: (id: string) => () => Promise<boolean>;
+  onTakeover: (id: string) => void;
 }) {
   const { isEditMode, viewBranch } = useEditorContext();
   const { openModal, closeModal } = useEditorModal();
@@ -1351,6 +1900,9 @@ function EditorContent({
                   mainStatus={mainIndex?.sections[section.id]?.status ?? null}
                   contentDiffersFromMain={changedSectionIds.has(section.id) || dirtySectionIds.has(section.id)}
                   isLocalOnly={dirtySectionIds.has(section.id) && !changedSectionIds.has(section.id)}
+                  lockedBy={locks.get(section.id) ? { email: locks.get(section.id)!.email } : null}
+                  onTakeover={() => onTakeover(section.id)}
+                  onEditIntent={getEditIntent(section.id)}
                   options={{
                     ...(section.content as Record<string, unknown>),
                     ...("options" in section ? (section.options as Record<string, unknown>) : {}),
@@ -1568,6 +2120,9 @@ function EditorToolbar({
   onOrderingClick,
   onPagesClick,
   onChatbotClick,
+  collabPeers,
+  collabSelfId,
+  collabStatus,
 }: {
   buttonState: "synced" | "publish" | "saveAndPublish";
   localChangesExist: boolean;
@@ -1588,6 +2143,9 @@ function EditorToolbar({
   onOrderingClick: () => void;
   onPagesClick: () => void;
   onChatbotClick: () => void;
+  collabPeers: CollabPeer[];
+  collabSelfId: string | null;
+  collabStatus: CollabStatus;
 }) {
   const { isEditMode, viewBranch, setViewBranch, toggleEditMode, historyState, setHistoryState } = useEditorContext();
 
@@ -1640,6 +2198,7 @@ function EditorToolbar({
                   Discard Changes
                 </Button>
               )}
+              <PresenceAvatars peers={collabPeers} selfUserId={collabSelfId} status={collabStatus} />
             </div>
             <div className="flex items-center justify-center">
               <StatusText