@drawnagency/primitives 0.1.76 → 0.1.78

package/src/hooks/useEditorPublish.ts

@@ -1,9 +1,12 @@
 import { useState, useCallback, useRef, useEffect } from "react";
 import type { SiteIndex, SiteConfig } from "../schemas/site-config";
+import type { SectionContent } from "../schemas/sections";
 import type { LoadedSection } from "../lib/loader";
 import type { MediaManifest, MediaItem } from "../media/types";
-import { getDirtySectionRows, hasLocalChanges, discardSavedChanges, cacheContent, clearContentCache, getPendingMediaBlobs, clearPendingMediaByIds } from "../lib/dexie";
+import { getDirtySectionRows, hasLocalChanges, discardSavedChanges, cacheContent, clearContentCache, getCachedContent, getPendingMediaBlobs, clearPendingMediaByIds } from "../lib/dexie";
 import { packUploads, type MediaUploadPayload } from "../lib/save-chunks";
+import { assembleSavedManifest } from "../lib/media-folders";
+import { buildCommittedBaseline } from "../collab/recovery";
 
 function blobToBase64(blob: Blob): Promise<string> {
   return new Promise((resolve, reject) => {
@@ -58,7 +61,14 @@ interface PublishDeps {
   siteConfig: SiteConfig | null;
   sections: LoadedSection[];
   deletedSectionIds?: string[];
-  onSuccess: () => void;
+  /** Receives the ids that were actually committed this save (so the caller can
+   *  release exactly those sections' locks), plus:
+   *  - editToken: the edit-generation captured at save BEGIN. The caller's
+   *    post-save clears must be guarded on it — any edit with a newer generation
+   *    happened while this save was in flight and was NOT carried by it.
+   *  - sentDeletedIds: the deletion ids this save actually sent, so the caller
+   *    clears only those (a deletion scheduled mid-save must stay scheduled). */
+  onSuccess: (savedSectionIds: string[], meta: { editToken: number; sentDeletedIds: string[] }) => void;
   mediaManifest: MediaManifest;
   manifestDirty: boolean;
   clearManifestDirty: () => void;
@@ -71,8 +81,30 @@ interface PublishDeps {
   // 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).
   getBaseVersion: () => string | null;
+  /** Injected by EditorShell. On a 409 (concurrent edit) the save calls this to
+   *  re-fetch the fresh draft, rebase local unsaved work on top, and refresh the
+   *  optimistic-concurrency base (savedShaRef). Returns true when recovery
+   *  succeeded and the save should be retried once; false (or undefined) means
+   *  fall through to the honest conflict toast. */
+  recoverConflict?: () => Promise<boolean>;
+  /** Injected by EditorShell. After every successful plain save, receives the
+   *  COMMITTED snapshot (sent content substituted into the previous clean
+   *  baseline, plus the sent index) so the shell can re-prime the content-cache
+   *  baseline that recoverConflict diffs against. Without this, the baseline
+   *  dies at the first save (discardSavedChanges clears it) and later 409
+   *  recoveries would silently merge local-wins. */
+  onBaselineCommitted?: (args: { sha: string; sections: LoadedSection[]; index: SiteIndex; savedIds: string[] }) => Promise<void>;
   /** Test hook: overrides the per-request payload budget (default 4MB). */
   saveChunkBudget?: number;
+  /** Injected by EditorShell. Mirrors this hook's in-flight-save state out to the
+   *  shell so background collaboration handlers (e.g. the remote saved-event
+   *  rebase) can defer while our own save's response path owns the state. */
+  savingRef?: React.MutableRefObject<boolean>;
+  /** Injected by EditorShell (persistence.currentGeneration). Read at save begin
+   *  to mint the editToken passed back through onSuccess. Absent (tests without
+   *  collab wiring): the token degrades to MAX_SAFE_INTEGER, i.e. "nothing was
+   *  edited after capture" — the pre-generation wholesale-clear behavior. */
+  getEditGeneration?: () => number;
 }
 
 interface GatheredMedia {
@@ -102,7 +134,11 @@ export function useEditorPublish({
   onShasUpdated,
   onPublishComplete,
   getBaseVersion,
+  recoverConflict,
+  onBaselineCommitted,
   saveChunkBudget,
+  savingRef,
+  getEditGeneration,
 }: PublishDeps) {
   const [publishAction, setPublishAction] = useState<PublishAction>("idle");
   const [publishFeedback, setPublishFeedback] = useState<string | null>(null);
@@ -163,14 +199,18 @@ export function useEditorPublish({
 
     let updatedManifest: MediaManifest | undefined;
     if (hasMediaChanges) {
-      const images = { ...manifest.images };
-      for (const upload of mediaUploads) {
-        images[upload.item.id] = upload.item;
-      }
-      for (const id of pendingDeletions) {
-        delete images[id];
-      }
-      updatedManifest = { images };
+      // Preserves folders (and any future manifest keys) and heals dangling
+      // folder refs — never rebuild the manifest as a bare { images }.
+      // KNOWN LIMITATION (deferred): the assembly starts from THIS editor's
+      // view of the manifest, so concurrent media changes by another editor
+      // are last-writer-wins — a manifest entry they added since our load is
+      // dropped from the write (their files remain; the entry orphans). Fixing
+      // this needs a merge against the remote manifest at save time.
+      updatedManifest = assembleSavedManifest(
+        manifest,
+        mediaUploads.map((u) => u.item),
+        pendingDeletions,
+      );
     }
 
     return { mediaUploads, updatedManifest, hasMediaChanges };
@@ -186,7 +226,16 @@ export function useEditorPublish({
     mediaManifest: MediaManifest;
     manifestDirty: boolean;
     saveChunkBudget?: number;
-  }): Promise<{ sha: string; savedSections: { sectionId: string; updatedAt: string }[]; uploadedItems: MediaItem[] }> {
+  }): Promise<{
+    sha: string;
+    // sectionId+updatedAt for compare-and-clear cleanup, plus the SENT content —
+    // the committed-baseline re-prime needs exactly what went to the server (not
+    // the current view state, which may carry mid-flight edits).
+    savedSections: { sectionId: string; updatedAt: string; content: SectionContent }[];
+    uploadedItems: MediaItem[];
+    // The index actually sent (deletions applied) — the committed index state.
+    sentIndex: SiteIndex;
+  }> {
     const dirty = await getDirtySectionRows();
     const gathered = await gatherMediaPayload(
       args.pendingMediaItems,
@@ -233,56 +282,72 @@ export function useEditorPublish({
     const committedImages: Record<string, MediaItem> = {};
     let sent = 0;
 
-    for (const chunk of leadChunks) {
-      setSaveProgress(`Saving images ${sent + chunk.length}/${totalUploads}…`);
-      for (const upload of chunk) committedImages[upload.item.id] = upload.item;
-      const manifest: MediaManifest = { images: { ...args.mediaManifest.images, ...committedImages } };
-      const data = await postSave({
-        baseVersion,
-        media: { uploads: chunk, deletions: [], manifest },
-      });
-      baseVersion = data.sha;
-      sent += chunk.length;
-      const chunkItems = chunk.map((u) => u.item);
-      uploadedItems.push(...chunkItems);
-      // Promote committed items immediately so a later failure can't re-send
-      // them. A failure HERE is tolerable: re-sending identical blobs on the
-      // next save is harmless (same content, same paths).
-      try {
-        await clearPendingMediaByIds(chunkItems.map((i) => i.id), []);
-        onMediaPublished(chunkItems, []);
-      } catch (promoteError) {
-        console.error("Failed to promote committed media chunk locally:", promoteError);
+    try {
+      for (const chunk of leadChunks) {
+        setSaveProgress(`Saving images ${sent + chunk.length}/${totalUploads}…`);
+        for (const upload of chunk) committedImages[upload.item.id] = upload.item;
+        const manifest: MediaManifest = {
+          images: { ...args.mediaManifest.images, ...committedImages },
+          folders: args.mediaManifest.folders,
+        };
+        const data = await postSave({
+          baseVersion,
+          media: { uploads: chunk, deletions: [], manifest },
+        });
+        baseVersion = data.sha;
+        sent += chunk.length;
+        const chunkItems = chunk.map((u) => u.item);
+        uploadedItems.push(...chunkItems);
+        // Promote committed items immediately so a later failure can't re-send
+        // them. A failure HERE is tolerable: re-sending identical blobs on the
+        // next save is harmless (same content, same paths).
+        try {
+          await clearPendingMediaByIds(chunkItems.map((i) => i.id), []);
+          onMediaPublished(chunkItems, []);
+        } catch (promoteError) {
+          console.error("Failed to promote committed media chunk locally:", promoteError);
+        }
       }
-    }
 
-    if (leadChunks.length > 0) {
-      setSaveProgress(finalUploads.length > 0 ? `Saving images ${totalUploads}/${totalUploads}…` : null);
-    }
+      if (leadChunks.length > 0) {
+        setSaveProgress(finalUploads.length > 0 ? `Saving images ${totalUploads}/${totalUploads}…` : null);
+      }
 
-    const responseData = await postSave({
-      sections: dirty.map(({ sectionId, content }) => ({ id: sectionId, content })),
-      siteIndex,
-      baseVersion,
-      ...(args.deletedSectionIds?.length ? { deletedSectionIds: args.deletedSectionIds } : {}),
-      ...(args.isConfigDirty() ? { siteConfig: args.siteConfig } : {}),
-      ...(gathered.hasMediaChanges ? {
-        media: {
-          uploads: finalUploads,
-          deletions: args.pendingMediaDeletions.map((id) => ({
-            id,
-            folder: args.mediaManifest.images[id]?.folder,
-          })).filter((d) => d.folder),
-          manifest: gathered.updatedManifest,
-        },
-      } : {}),
-    });
+      const responseData = await postSave({
+        sections: dirty.map(({ sectionId, content }) => ({ id: sectionId, content })),
+        siteIndex,
+        baseVersion,
+        ...(args.deletedSectionIds?.length ? { deletedSectionIds: args.deletedSectionIds } : {}),
+        ...(args.isConfigDirty() ? { siteConfig: args.siteConfig } : {}),
+        ...(gathered.hasMediaChanges ? {
+          media: {
+            uploads: finalUploads,
+            deletions: args.pendingMediaDeletions.map((id) => ({
+              id,
+              folder: args.mediaManifest.images[id]?.folder,
+            })).filter((d) => d.folder),
+            manifest: gathered.updatedManifest,
+          },
+        } : {}),
+      });
 
-    return {
-      sha: responseData.sha,
-      savedSections: dirty.map(({ sectionId, updatedAt }) => ({ sectionId, updatedAt })),
-      uploadedItems: [...uploadedItems, ...finalUploads.map((u) => u.item)],
-    };
+      return {
+        sha: responseData.sha,
+        savedSections: dirty.map(({ sectionId, updatedAt, content }) => ({ sectionId, updatedAt, content })),
+        uploadedItems: [...uploadedItems, ...finalUploads.map((u) => u.item)],
+        sentIndex: siteIndex,
+      };
+    } catch (error) {
+      // I2: once a lead chunk has committed (advancing the draft head), a 409
+      // must NOT trigger auto-recovery — the retry would rebuild the manifest
+      // from this invocation's stale closure, dropping the just-promoted items
+      // and orphaning their committed files. Mark the error so the recovery
+      // wrapper falls through to the honest toast instead.
+      if (sent > 0 && error && typeof error === "object") {
+        (error as { leadChunksCommitted?: boolean }).leadChunksCommitted = true;
+      }
+      throw error;
+    }
   }
 
   // --- Shared save orchestration ---
@@ -290,9 +355,24 @@ export function useEditorPublish({
   // change-detection, the /api/save request, and the post-save cleanup stay in
   // one place and can't drift between the two paths.
 
+  // Whether THIS save invocation's recoverConflict actually rebased the view —
+  // gates the 409 toast copy: "your view has been updated" must only be claimed
+  // when it is true. Reset at the start of every save.
+  const recoveredRef = useRef(false);
+
+  // Edit-generation captured at save begin. Edits with a newer generation
+  // happened mid-save (after the payload snapshot) — onSuccess receives this
+  // token so the shell's post-save clears can spare them. Captured BEFORE the
+  // flush: an edit landing during the flush itself then reads as "after the
+  // token" and is kept — erring toward a stale dirty badge, never lost work.
+  const editTokenRef = useRef(Number.MAX_SAFE_INTEGER);
+
   function tryBeginSave(): boolean {
     if (!siteConfig || inFlightRef.current) return false;
     inFlightRef.current = true;
+    if (savingRef) savingRef.current = true;
+    recoveredRef.current = false;
+    editTokenRef.current = getEditGeneration?.() ?? Number.MAX_SAFE_INTEGER;
     setPublishAction("saving");
     setPublishFeedback(null);
     return true;
@@ -315,6 +395,30 @@ export function useEditorPublish({
     });
   }
 
+  // Wraps a save attempt with single-shot 409 auto-recovery: when the server
+  // rejects the save because another editor moved the draft head, ask
+  // recoverConflict() to re-fetch + rebase local work and refresh savedShaRef,
+  // then retry exactly once. Any other error (or a declined/absent recovery)
+  // propagates to reportSaveError. At most one retry per save invocation — never
+  // a loop, since the retry runs runPerformSave() directly, not this wrapper.
+  async function saveWithConflictRecovery(): ReturnType<typeof runPerformSave> {
+    try {
+      return await runPerformSave();
+    } catch (error) {
+      const status = (error as { status?: number })?.status;
+      // I2: no recovery once lead media chunks committed this invocation — see
+      // the flag's source in performSave.
+      const leadCommitted = (error as { leadChunksCommitted?: boolean })?.leadChunksCommitted === true;
+      if (status === 409 && !leadCommitted && recoverConflict && (await recoverConflict())) {
+        // recoverConflict rebased local state and refreshed savedShaRef —
+        // getBaseVersion() now returns the fresh draft head. One retry only.
+        recoveredRef.current = true;
+        return await runPerformSave();
+      }
+      throw error;
+    }
+  }
+
   // Clear the Dexie rows + pending media for what was actually committed. In the
   // publish path this MUST run before cacheContent: discardSavedChanges clears
   // only the rows we sent (preserving edits typed during the request) AND
@@ -330,17 +434,27 @@ export function useEditorPublish({
     await clearPendingMediaByIds(uploadedItems.map((i) => i.id), pendingMediaDeletions);
   }
 
-  function finishSave(uploadedItems: MediaItem[]): void {
+  function finishSave(uploadedItems: MediaItem[], savedSectionIds: string[]): void {
     clearConfigDirty();
     clearManifestDirty();
-    onSuccess();
+    onSuccess(savedSectionIds, {
+      editToken: editTokenRef.current,
+      sentDeletedIds: deletedSectionIds ?? [],
+    });
     onMediaPublished(uploadedItems, pendingMediaDeletions);
   }
 
   function reportSaveError(error: unknown, failLabel: string): void {
     console.error(`${failLabel} failed:`, error);
-    const message = error instanceof Error && error.message ? error.message : `${failLabel} failed`;
     const isConflict = (error as { status?: number })?.status === 409;
+    // 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 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);
   }
 
@@ -356,12 +470,31 @@ export function useEditorPublish({
         return;
       }
 
-      const { sha, savedSections, uploadedItems } = await runPerformSave();
+      const { sha, savedSections, uploadedItems, sentIndex } = await saveWithConflictRecovery();
       onShasUpdated(sha, null);
 
       try {
+        // C1: read the previous clean baseline BEFORE commitSavedRows clears the
+        // content cache, then re-prime it with the COMMITTED snapshot keyed at
+        // the new sha. Post-recovery the cache holds the fetched remote snapshot,
+        // so this correctly layers only the retried dirty rows on top of it.
+        const prevBaseline = onBaselineCommitted ? await getCachedContent() : null;
         await commitSavedRows(savedSections, uploadedItems);
-        finishSave(uploadedItems);
+        if (onBaselineCommitted) {
+          const baselineSections = buildCommittedBaseline({
+            baselineSections: prevBaseline?.sections ?? null,
+            fallbackSections: sections,
+            savedRows: savedSections,
+            sentIndex,
+          });
+          await onBaselineCommitted({
+            sha,
+            sections: baselineSections,
+            index: sentIndex,
+            savedIds: savedSections.map((s) => s.sectionId),
+          });
+        }
+        finishSave(uploadedItems, savedSections.map((s) => s.sectionId));
       } 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);
@@ -373,10 +506,11 @@ export function useEditorPublish({
       reportSaveError(error, "Save");
     } finally {
       inFlightRef.current = false;
+      if (savingRef) savingRef.current = false;
       setPublishAction("idle");
       setSaveProgress(null);
     }
-  }, [flushNow, cancelPendingFlush, isConfigDirty, clearConfigDirty, siteIndexRef, siteConfig, deletedSectionIds, onSuccess, mediaManifest, manifestDirty, clearManifestDirty, pendingMediaItems, pendingMediaDeletions, onMediaPublished, onShasUpdated, showFeedback, saveChunkBudget]);
+  }, [flushNow, cancelPendingFlush, isConfigDirty, clearConfigDirty, siteIndexRef, siteConfig, sections, deletedSectionIds, onSuccess, mediaManifest, manifestDirty, clearManifestDirty, pendingMediaItems, pendingMediaDeletions, onMediaPublished, onShasUpdated, showFeedback, recoverConflict, onBaselineCommitted, saveChunkBudget, getEditGeneration]);
 
   const handlePublish = useCallback(async () => {
     setPublishAction("publishing");
@@ -422,10 +556,11 @@ export function useEditorPublish({
 
       const hasLocalEdits = await hasPendingEdits();
 
-      let savedSections: { sectionId: string; updatedAt: string }[] = [];
+      let savedSections: { sectionId: string; updatedAt: string; content: SectionContent }[] = [];
       let uploadedItems: MediaItem[] = [];
+      let sentIndex: SiteIndex | null = null;
       if (hasLocalEdits) {
-        ({ savedSections, uploadedItems } = await runPerformSave());
+        ({ savedSections, uploadedItems, sentIndex } = await saveWithConflictRecovery());
       }
 
       setPublishAction("publishing");
@@ -448,12 +583,21 @@ export function useEditorPublish({
 
       if (hasLocalEdits) {
         try {
+          // C1 parity with handleSave: read the previous clean baseline before
+          // the invalidation, then re-cache the COMMITTED snapshot (sent content
+          // + sent index — never the live view state, which may carry mid-flight
+          // edits) against the PUBLISHED sha; the draft branch is gone after
+          // publish, so this is the snapshot a later cache hit restores.
+          const prevBaseline = await getCachedContent();
           await commitSavedRows(savedSections, uploadedItems);
-          // Re-cache against the PUBLISHED sha (commitSavedRows just invalidated the
-          // cache); the draft branch is gone after publish, so this is the snapshot a
-          // later cache hit restores.
-          await cacheContent(sha, sections, siteIndexRef.current, siteConfig!);
-          finishSave(uploadedItems);
+          const baselineSections = buildCommittedBaseline({
+            baselineSections: prevBaseline?.sections ?? null,
+            fallbackSections: sections,
+            savedRows: savedSections,
+            sentIndex: sentIndex!,
+          });
+          await cacheContent(sha, baselineSections, sentIndex!, siteConfig!);
+          finishSave(uploadedItems, savedSections.map((s) => s.sectionId));
         } catch (cleanupError) {
           console.error("Publish succeeded but local cleanup failed:", cleanupError);
           onShasUpdated(null, sha);
@@ -469,10 +613,11 @@ export function useEditorPublish({
       reportSaveError(error, "Publish");
     } finally {
       inFlightRef.current = false;
+      if (savingRef) savingRef.current = false;
       setPublishAction("idle");
       setSaveProgress(null);
     }
-  }, [flushNow, cancelPendingFlush, isConfigDirty, clearConfigDirty, siteIndexRef, siteConfig, sections, deletedSectionIds, onSuccess, mediaManifest, manifestDirty, clearManifestDirty, pendingMediaItems, pendingMediaDeletions, onMediaPublished, onShasUpdated, showFeedback, onPublishComplete, saveChunkBudget]);
+  }, [flushNow, cancelPendingFlush, isConfigDirty, clearConfigDirty, siteIndexRef, siteConfig, sections, deletedSectionIds, onSuccess, mediaManifest, manifestDirty, clearManifestDirty, pendingMediaItems, pendingMediaDeletions, onMediaPublished, onShasUpdated, showFeedback, onPublishComplete, recoverConflict, saveChunkBudget, getEditGeneration]);
 
   return { publishAction, publishFeedback, saveProgress, handleSave, handlePublish, handleSaveAndPublish };
 }

package/src/hooks/useMediaFolderDnd.ts

@@ -0,0 +1,129 @@
+import { useEffect, useRef, useState } from "react";
+import type { MediaFolder, MediaItem } from "../media/types";
+import {
+  buildFolderDropData, canDropFolderInto, canDropMediaInto,
+  isFolderDragData, isMediaDragData,
+  type MediaDragData, type MediaFolderDragData,
+} from "../lib/media-dnd";
+
+/** Delay before a hovered collapsed tree node auto-expands during a drag. */
+const HOVER_EXPAND_MS = 600;
+
+interface UseFolderDropTargetArgs {
+  targetFolderId: string | null;
+  enabled: boolean;
+  /** Refs (not values) so drops read fresh state without re-registering targets. */
+  foldersRef: React.RefObject<Record<string, MediaFolder>>;
+  itemsByIdRef: React.RefObject<Record<string, MediaItem>>;
+  onMoveMedia: (ids: string[], target: string | null) => void;
+  onMoveFolder: (id: string, target: string | null) => void;
+  /** Fired after a sustained drag hover (tree hover-to-expand). */
+  onDragHover?: () => void;
+}
+
+export function useFolderDropTarget<E extends HTMLElement>({
+  targetFolderId, enabled, foldersRef, itemsByIdRef, onMoveMedia, onMoveFolder, onDragHover,
+}: UseFolderDropTargetArgs) {
+  const ref = useRef<E>(null);
+  const [isDropTarget, setIsDropTarget] = useState(false);
+  const callbacksRef = useRef({ onMoveMedia, onMoveFolder, onDragHover });
+  callbacksRef.current = { onMoveMedia, onMoveFolder, onDragHover };
+
+  useEffect(() => {
+    if (!enabled) return;
+    const element = ref.current;
+    if (!element) return;
+
+    let cleanup: (() => void) | undefined;
+    let cancelled = false;
+    let hoverTimer: ReturnType<typeof setTimeout> | undefined;
+    const clearHover = () => {
+      if (hoverTimer !== undefined) clearTimeout(hoverTimer);
+      hoverTimer = undefined;
+    };
+
+    import("@atlaskit/pragmatic-drag-and-drop/element/adapter").then(({ dropTargetForElements }) => {
+      if (cancelled) return;
+      cleanup = dropTargetForElements({
+        element,
+        getData: () => buildFolderDropData(targetFolderId),
+        canDrop: ({ source }) => {
+          const folders = foldersRef.current ?? {};
+          if (isMediaDragData(source.data)) {
+            return canDropMediaInto(source.data, targetFolderId, folders, itemsByIdRef.current ?? {});
+          }
+          if (isFolderDragData(source.data)) {
+            return canDropFolderInto(source.data, targetFolderId, folders);
+          }
+          return false;
+        },
+        onDragEnter: () => {
+          setIsDropTarget(true);
+          if (callbacksRef.current.onDragHover) {
+            clearHover();
+            hoverTimer = setTimeout(() => callbacksRef.current.onDragHover?.(), HOVER_EXPAND_MS);
+          }
+        },
+        onDragLeave: () => {
+          setIsDropTarget(false);
+          clearHover();
+        },
+        onDrop: ({ source }) => {
+          setIsDropTarget(false);
+          clearHover();
+          if (isMediaDragData(source.data)) {
+            callbacksRef.current.onMoveMedia(source.data.mediaIds, targetFolderId);
+          } else if (isFolderDragData(source.data)) {
+            callbacksRef.current.onMoveFolder(source.data.folderId, targetFolderId);
+          }
+        },
+      });
+    });
+
+    return () => {
+      cancelled = true;
+      clearHover();
+      cleanup?.();
+    };
+  }, [enabled, targetFolderId, foldersRef, itemsByIdRef]);
+
+  return { ref, isDropTarget };
+}
+
+interface UseMediaDraggableArgs {
+  enabled: boolean;
+  getDragData: () => MediaDragData | MediaFolderDragData;
+}
+
+export function useMediaDraggable<E extends HTMLElement>({ enabled, getDragData }: UseMediaDraggableArgs) {
+  const ref = useRef<E>(null);
+  const [isDragging, setIsDragging] = useState(false);
+  const getDragDataRef = useRef(getDragData);
+  getDragDataRef.current = getDragData;
+
+  useEffect(() => {
+    if (!enabled) return;
+    const element = ref.current;
+    if (!element) return;
+
+    let cleanup: (() => void) | undefined;
+    let cancelled = false;
+
+    import("@atlaskit/pragmatic-drag-and-drop/element/adapter").then(({ draggable }) => {
+      if (cancelled) return;
+      cleanup = draggable({
+        element,
+        getInitialData: () => getDragDataRef.current(),
+        onDragStart: () => setIsDragging(true),
+        onDrop: () => setIsDragging(false),
+      });
+    });
+
+    return () => {
+      cancelled = true;
+      cleanup?.();
+    };
+  }, [enabled]);
+
+  return { ref, isDragging };
+}