@drawnagency/primitives 0.1.77 → 0.1.78

package/src/components/shell/MoveToFolderDialog.tsx

@@ -0,0 +1,78 @@
+import { useState } from "react";
+import { Folder, LayoutGrid } from "lucide-react";
+import { cn } from "../../lib/cn";
+import { Button } from "../shared/Button";
+import type { MediaFolder } from "../../media/types";
+import { buildFolderTree, type FolderTreeNode } from "../../lib/media-folders";
+
+export interface MoveToFolderDialogProps {
+  folders: Record<string, MediaFolder>;
+  /** Targets to disable (moving a folder: its own descendant set). */
+  disabledIds?: Set<string>;
+  /**
+   * Target that is a no-op (the items' current folder), disabled too.
+   * Omit (undefined) when there is no single no-op target — e.g. a
+   * heterogeneous selection — and nothing is disabled on that account.
+   */
+  currentTarget?: string | null;
+  onMove: (targetFolderId: string | null) => void;
+  onClose: () => void;
+}
+
+/** Sentinel for "no pick yet" — distinct from picking root (null). */
+const UNPICKED = Symbol("unpicked");
+
+export function MoveToFolderDialog({
+  folders, disabledIds, currentTarget, onMove, onClose,
+}: MoveToFolderDialogProps) {
+  const [picked, setPicked] = useState<string | null | typeof UNPICKED>(UNPICKED);
+  const tree = buildFolderTree(folders);
+
+  const row = (target: string | null, label: string, depth: number, icon: React.ReactNode) => {
+    const disabled = target === currentTarget || (target !== null && disabledIds?.has(target) === true);
+    const active = picked !== UNPICKED && picked === target;
+    return (
+      <button
+        key={target ?? "__root__"}
+        type="button"
+        disabled={disabled}
+        onClick={() => setPicked(target)}
+        className={cn(
+          "flex w-full items-center gap-1.5 rounded px-2 py-1.5 text-left text-sm",
+          disabled ? "cursor-not-allowed text-base-contrast-light/50" : "cursor-pointer hover:bg-base-accent",
+          active && "bg-primary/10 font-medium text-primary",
+        )}
+        style={{ paddingLeft: `${8 + depth * 14}px` }}
+      >
+        {icon}
+        <span className="min-w-0 flex-1 truncate">{label}</span>
+      </button>
+    );
+  };
+
+  const renderNodes = (nodes: FolderTreeNode[], depth: number): React.ReactNode[] =>
+    nodes.flatMap((node) => [
+      row(node.id, node.name, depth, <Folder size={14} className="shrink-0 text-base-contrast-light" />),
+      ...renderNodes(node.children, depth + 1),
+    ]);
+
+  return (
+    <div className="flex flex-col gap-3">
+      <div className="max-h-64 overflow-y-auto rounded-lg border border-base-200 p-1.5">
+        {row(null, "All media", 0, <LayoutGrid size={14} className="shrink-0 text-base-contrast-light" />)}
+        {renderNodes(tree, 0)}
+      </div>
+      <div className="flex justify-end gap-2">
+        <Button variant="secondary" size="sm" onClick={onClose}>Cancel</Button>
+        <Button
+          variant="primary"
+          size="sm"
+          disabled={picked === UNPICKED}
+          onClick={() => { if (picked !== UNPICKED) { onMove(picked); onClose(); } }}
+        >
+          Move
+        </Button>
+      </div>
+    </div>
+  );
+}

package/src/hooks/useEditorPublish.ts

@@ -5,6 +5,7 @@ import type { LoadedSection } from "../lib/loader";
 import type { MediaManifest, MediaItem } from "../media/types";
 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> {
@@ -198,19 +199,18 @@ export function useEditorPublish({
 
     let updatedManifest: MediaManifest | undefined;
     if (hasMediaChanges) {
-      // KNOWN LIMITATION (deferred): the manifest is rebuilt from THIS editor's
-      // view of manifest.images, so concurrent media changes by another editor
+      // 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.
-      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 };
+      updatedManifest = assembleSavedManifest(
+        manifest,
+        mediaUploads.map((u) => u.item),
+        pendingDeletions,
+      );
     }
 
     return { mediaUploads, updatedManifest, hasMediaChanges };
@@ -286,7 +286,10 @@ export function useEditorPublish({
       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 manifest: MediaManifest = {
+          images: { ...args.mediaManifest.images, ...committedImages },
+          folders: args.mediaManifest.folders,
+        };
         const data = await postSave({
           baseVersion,
           media: { uploads: chunk, deletions: [], manifest },

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 };
+}

package/src/hooks/useMediaPipeline.ts

@@ -14,6 +14,11 @@ import {
 } from "../lib/dexie";
 import { generateVideoPoster } from "../media/videoPoster";
 import { tallyImageIds, collectImageIds, clearImageIds } from "../lib/image-refs";
+import {
+  createFolderId, uniqueFolderName, effectiveParentId, canMoveFolder,
+  descendantFolderIds, itemFolderId, planFolderUpload,
+} from "../lib/media-folders";
+import type { MediaFolder } from "../media/types";
 
 interface UseMediaPipelineInput {
   siteConfig: SiteConfig | null;
@@ -28,6 +33,9 @@ interface UseMediaPipelineInput {
   // upload-intent errors, direct-to-bucket PUT failures) to the caller, which
   // decides how to display them (e.g. the media modal's rejection banner).
   onUploadError?: (message: string) => void;
+  // Surfaces non-error, informational notices (e.g. "N files already exist
+  // and were left where they are" on dedup skip) to the caller.
+  onUploadNotice?: (message: string) => void;
 }
 
 export function useMediaPipeline({
@@ -40,6 +48,7 @@ export function useMediaPipeline({
   setDirtySectionIds,
   markSectionDirty,
   onUploadError,
+  onUploadNotice,
 }: UseMediaPipelineInput) {
   const [processingItems, setProcessingItems] = useState<QueueItem[]>([]);
   const [pendingMediaItems, setPendingMediaItems] = useState<LibraryMediaItem[]>([]);
@@ -59,6 +68,9 @@ export function useMediaPipeline({
 
   const queueRef = useRef<ProcessingQueue | null>(null);
   const uploadCallbacksRef = useRef<Map<string, (imageId: string) => void>>(new Map());
+  // Display-folder target per in-flight upload, keyed by content hash. Set at
+  // enqueue time, consumed when the processing queue finalizes the item.
+  const uploadTargetsRef = useRef<Map<string, string | null>>(new Map());
   const destroyedRef = useRef(false);
 
   // Shared persistence path for every pending media item — the processing
@@ -135,6 +147,7 @@ export function useMediaPipeline({
             height: number,
           ) => {
             if (destroyedRef.current) return;
+            const targetFolderId = uploadTargetsRef.current.get(event.item.hash) ?? null;
             const item: LibraryMediaItem = {
               id: event.item.hash,
               hash: event.item.hash,
@@ -152,9 +165,11 @@ export function useMediaPipeline({
               })),
               alt: "",
               storage: "github",
+              ...(targetFolderId ? { folderId: targetFolderId } : {}),
             };
 
             const persisted = await finalizePendingMedia(item, localUrls, blobsMap);
+            uploadTargetsRef.current.delete(event.item.hash);
             if (!persisted) return;
 
             const callback = uploadCallbacksRef.current.get(event.item.hash);
@@ -201,6 +216,7 @@ export function useMediaPipeline({
       destroyedRef.current = true;
       queue.destroy();
       uploadCallbacksRef.current = new Map();
+      uploadTargetsRef.current = new Map();
     };
   // eslint-disable-next-line react-hooks/exhaustive-deps -- rebuild only when processing params change, not on every siteConfig reference change
   }, [mediaConfigKey, setLocalChangesExist]);
@@ -220,7 +236,7 @@ export function useMediaPipeline({
   // anything upstream of those stages (e.g. hashing), and the single outer
   // `finally` is the one place progress gets cleared, regardless of which
   // stage — or none — ran.
-  const uploadLargeVideo = useCallback(async (file: File, mediaConfig: SiteConfig["media"]) => {
+  const uploadLargeVideo = useCallback(async (file: File, mediaConfig: SiteConfig["media"], targetFolderId: string | null) => {
     let hash: string | undefined;
     try {
       const buffer = await file.arrayBuffer();
@@ -295,6 +311,7 @@ export function useMediaPipeline({
           // which ImageManifestSchema's z.number().positive().optional()
           // rejects on the next save — omit the field entirely instead.
           ...(Number.isFinite(duration) && duration > 0 ? { duration } : {}),
+          ...(targetFolderId ? { folderId: targetFolderId } : {}),
         };
         // Only the poster blob is persisted — the original lives in the bucket, so
         // save/publish never ships large base64 through the Netlify function.
@@ -322,12 +339,13 @@ export function useMediaPipeline({
     }
   }, [mediaManifest, pendingMediaItems, pendingDeletions, onUploadError, finalizePendingMedia]);
 
-  const handleMediaUpload = useCallback(async (files: File[]) => {
+  const handleMediaUpload = useCallback(async (files: File[], targetFolderId: string | null = null) => {
     if (!siteConfig) return;
     const mediaConfig = siteConfig.media;
     const queue = queueRef.current;
     if (!queue) return;
 
+    let alreadyExisting = 0;
     for (const file of files) {
       if (file.size > mediaConfig.maxFileSize) {
         if (file.type === "video/mp4" || file.type === "video/webm") {
@@ -336,7 +354,7 @@ export function useMediaPipeline({
           // this catch is defense-in-depth only, so it must NOT call
           // onUploadError again — doing so would double-report.
           try {
-            await uploadLargeVideo(file, mediaConfig);
+            await uploadLargeVideo(file, mediaConfig, targetFolderId);
           } catch (err) {
             console.error(`[useMediaPipeline] uploadLargeVideo threw unexpectedly for "${file.name}":`, err);
           }
@@ -356,7 +374,12 @@ export function useMediaPipeline({
       const isDeleted = pendingDeletions.includes(hash);
       const existsInManifest = hash in mediaManifest.images;
       const existsInPending = pendingMediaItems.some((i) => i.hash === hash);
-      if ((existsInManifest || existsInPending) && !isDeleted) continue;
+      if ((existsInManifest || existsInPending) && !isDeleted) {
+        alreadyExisting++;
+        continue;
+      }
+
+      uploadTargetsRef.current.set(hash, targetFolderId);
 
       let kind: "image" | "animated" | "video" = "image";
       if (file.type === "image/gif" || file.type === "image/apng") kind = "animated";
@@ -364,7 +387,14 @@ export function useMediaPipeline({
 
       queue.add({ buffer, originalName: file.name, mimeType: file.type, hash, kind });
     }
-  }, [siteConfig, mediaManifest, pendingMediaItems, pendingDeletions, onUploadError, uploadLargeVideo]);
+    if (alreadyExisting > 0) {
+      onUploadNotice?.(
+        alreadyExisting === 1
+          ? "1 file already exists in the library and was left where it is."
+          : `${alreadyExisting} files already exist in the library and were left where they are.`,
+      );
+    }
+  }, [siteConfig, mediaManifest, pendingMediaItems, pendingDeletions, onUploadError, onUploadNotice, uploadLargeVideo]);
 
   const handleMediaDelete = useCallback(async (ids: string[]) => {
     const idSet = new Set(ids);
@@ -417,7 +447,7 @@ export function useMediaPipeline({
     setMediaManifest((prev) => {
       const item = prev.images[id];
       if (!item) return prev;
-      return { images: { ...prev.images, [id]: { ...item, alt } } };
+      return { ...prev, images: { ...prev.images, [id]: { ...item, alt } } };
     });
     setPendingMediaItems((prev) =>
       prev.map((item) => (item.id === id ? { ...item, alt } : item)),
@@ -428,6 +458,126 @@ export function useMediaPipeline({
     setLocalChangesExist(true);
   }, [setMediaManifest, setLocalChangesExist]);
 
+  // --- Display-folder operations (pure manifest metadata; ride Save like alt text) ---
+
+  const handleFolderCreate = useCallback((name: string, parentId: string | null): string => {
+    const id = createFolderId();
+    setMediaManifest((prev) => ({
+      ...prev,
+      folders: { ...prev.folders, [id]: { name: uniqueFolderName(prev.folders, parentId, name), parentId } },
+    }));
+    setManifestDirty(true);
+    setLocalChangesExist(true);
+    return id;
+  }, [setMediaManifest, setLocalChangesExist]);
+
+  const handleFolderRename = useCallback((id: string, name: string) => {
+    setMediaManifest((prev) => {
+      const folder = prev.folders[id];
+      if (!folder) return prev;
+      const unique = uniqueFolderName(prev.folders, effectiveParentId(prev.folders, id), name, id);
+      return { ...prev, folders: { ...prev.folders, [id]: { ...folder, name: unique } } };
+    });
+    setManifestDirty(true);
+    setLocalChangesExist(true);
+  }, [setMediaManifest, setLocalChangesExist]);
+
+  const handleFolderMove = useCallback((id: string, parentId: string | null) => {
+    setMediaManifest((prev) => {
+      if (!canMoveFolder(prev.folders, id, parentId)) return prev;
+      return { ...prev, folders: { ...prev.folders, [id]: { ...prev.folders[id], parentId } } };
+    });
+    setManifestDirty(true);
+    setLocalChangesExist(true);
+  }, [setMediaManifest, setLocalChangesExist]);
+
+  const stripFolderId = (entry: LibraryMediaItem): LibraryMediaItem => {
+    const { folderId: _dropped, ...rest } = entry;
+    return rest;
+  };
+
+  const handleMediaMove = useCallback((ids: string[], folderId: string | null) => {
+    const idSet = new Set(ids);
+    const retarget = (entry: LibraryMediaItem): LibraryMediaItem =>
+      folderId === null ? stripFolderId(entry) : { ...entry, folderId };
+    setMediaManifest((prev) => {
+      const images = { ...prev.images };
+      for (const id of ids) if (images[id]) images[id] = retarget(images[id]);
+      return { ...prev, images };
+    });
+    setPendingMediaItems((prev) => prev.map((entry) => (idSet.has(entry.id) ? retarget(entry) : entry)));
+    setManifestDirty(true);
+    setLocalChangesExist(true);
+  }, [setMediaManifest, setLocalChangesExist]);
+
+  const handleFolderDelete = useCallback(async (id: string, contents: "move" | "delete") => {
+    if (contents === "delete") {
+      const doomed = descendantFolderIds(mediaManifest.folders, id);
+      const inDoomed = (entry: LibraryMediaItem) => {
+        const fid = itemFolderId(mediaManifest.folders, entry);
+        return fid !== null && doomed.has(fid);
+      };
+      const mediaIds = [
+        ...Object.values(mediaManifest.images).filter(inDoomed),
+        ...pendingMediaItems.filter(inDoomed),
+      ].map((entry) => entry.id);
+      if (mediaIds.length > 0) await handleMediaDelete([...new Set(mediaIds)]);
+      setMediaManifest((prev) => {
+        const folders = { ...prev.folders };
+        for (const fid of descendantFolderIds(prev.folders, id)) delete folders[fid];
+        return { ...prev, folders };
+      });
+    } else {
+      setMediaManifest((prev) => {
+        if (!prev.folders[id]) return prev;
+        const parentId = effectiveParentId(prev.folders, id);
+        const folders: Record<string, MediaFolder> = {};
+        for (const [fid, f] of Object.entries(prev.folders)) {
+          if (fid === id) continue;
+          folders[fid] = effectiveParentId(prev.folders, fid) === id ? { ...f, parentId } : f;
+        }
+        const images = { ...prev.images };
+        for (const [iid, entry] of Object.entries(images)) {
+          if (itemFolderId(prev.folders, entry) !== id) continue;
+          images[iid] = parentId === null ? stripFolderId(entry) : { ...entry, folderId: parentId };
+        }
+        return { ...prev, images, folders };
+      });
+      setPendingMediaItems((prev) =>
+        prev.map((entry) => {
+          if (entry.folderId !== id) return entry;
+          const parentId = effectiveParentId(mediaManifest.folders, id);
+          return parentId === null ? stripFolderId(entry) : { ...entry, folderId: parentId };
+        }),
+      );
+    }
+    setManifestDirty(true);
+    setLocalChangesExist(true);
+  }, [mediaManifest, pendingMediaItems, handleMediaDelete, setMediaManifest, setLocalChangesExist]);
+
+  const handleFolderUpload = useCallback(async (
+    entries: { file: File; relativePath: string }[],
+    currentFolderId: string | null,
+  ) => {
+    const plan = planFolderUpload(entries, mediaManifest.folders, currentFolderId);
+    if (Object.keys(plan.newFolders).length > 0) {
+      setMediaManifest((prev) => ({ ...prev, folders: { ...prev.folders, ...plan.newFolders } }));
+      setManifestDirty(true);
+      setLocalChangesExist(true);
+    }
+    // Group per target folder and reuse the standard upload path — dedup, size
+    // gates, and large-video tiering all apply per file.
+    const groups = new Map<string | null, File[]>();
+    for (const { file, folderId } of plan.fileTargets) {
+      const list = groups.get(folderId);
+      if (list) list.push(file);
+      else groups.set(folderId, [file]);
+    }
+    for (const [folderId, groupFiles] of groups) {
+      await handleMediaUpload(groupFiles, folderId);
+    }
+  }, [mediaManifest, handleMediaUpload, setMediaManifest, setLocalChangesExist]);
+
   // Count imageId references with a single structural pass per section (O(n)),
   // instead of stringifying every section and regex-scanning it per known id.
   // Counts every referenced imageId; the consumer (MediaLibraryModal) only looks
@@ -514,6 +664,12 @@ export function useMediaPipeline({
     handleMediaUpload,
     handleMediaDelete,
     handleMediaAltChange,
+    handleFolderCreate,
+    handleFolderRename,
+    handleFolderMove,
+    handleFolderDelete,
+    handleMediaMove,
+    handleFolderUpload,
     referenceCountMap,
     contextValue,
     enqueueFile,

package/src/lib/media-dnd.ts

@@ -0,0 +1,62 @@
+import type { MediaFolder, MediaItem } from "../media/types";
+import { canMoveFolder, itemFolderId } from "./media-folders";
+
+export interface MediaDragData {
+  dragType: "media-item";
+  mediaIds: string[];
+  [key: string | symbol]: unknown;
+}
+
+export interface MediaFolderDragData {
+  dragType: "media-folder";
+  folderId: string;
+  [key: string | symbol]: unknown;
+}
+
+export interface MediaFolderDropData {
+  dropType: "media-folder";
+  targetFolderId: string | null;
+  [key: string | symbol]: unknown;
+}
+
+export function buildMediaDragData(mediaIds: string[]): MediaDragData {
+  return { dragType: "media-item", mediaIds };
+}
+
+export function buildFolderDragData(folderId: string): MediaFolderDragData {
+  return { dragType: "media-folder", folderId };
+}
+
+export function buildFolderDropData(targetFolderId: string | null): MediaFolderDropData {
+  return { dropType: "media-folder", targetFolderId };
+}
+
+export function isMediaDragData(d: Record<string | symbol, unknown>): d is MediaDragData {
+  return d.dragType === "media-item";
+}
+
+export function isFolderDragData(d: Record<string | symbol, unknown>): d is MediaFolderDragData {
+  return d.dragType === "media-folder";
+}
+
+/** True when at least one dragged item would actually change folder. */
+export function canDropMediaInto(
+  drag: MediaDragData,
+  targetFolderId: string | null,
+  folders: Record<string, MediaFolder>,
+  itemsById: Record<string, MediaItem>,
+): boolean {
+  return drag.mediaIds.some((id) => {
+    const entry = itemsById[id];
+    return entry !== undefined && itemFolderId(folders, entry) !== targetFolderId;
+  });
+}
+
+/** Folder drops delegate to the tree-integrity guard (self/descendant/no-op). */
+export function canDropFolderInto(
+  drag: MediaFolderDragData,
+  targetFolderId: string | null,
+  folders: Record<string, MediaFolder>,
+): boolean {
+  return canMoveFolder(folders, drag.folderId, targetFolderId);
+}