@drawnagency/primitives 0.1.76 → 0.1.78

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/index.ts

@@ -4,3 +4,5 @@ export * from "./auth";
 export * from "./media";
 export * from "./deploy";
 export * from "./storage";
+export * from "./collab/types";
+export { setCollabProvider, getCollabProvider } from "./collab/provider-registry";

package/src/lib/dexie.ts

@@ -67,6 +67,14 @@ interface PendingMediaDeletionRow {
   deletedAt: string;
 }
 
+export interface PreservedEditRow {
+  id: string;
+  sectionId: string;
+  content: SectionContent;
+  reason: "takeover" | "conflict";
+  preservedAt: string;
+}
+
 class EditorDatabase extends Dexie {
   sections!: Dexie.Table<SectionRow, string>;
   siteIndex!: Dexie.Table<SiteIndexRow, string>;
@@ -76,6 +84,7 @@ class EditorDatabase extends Dexie {
   mediaManifest!: Dexie.Table<MediaManifestRow, string>;
   pendingMedia!: Dexie.Table<PendingMediaRow, string>;
   pendingMediaDeletions!: Dexie.Table<PendingMediaDeletionRow, string>;
+  preservedEdits!: Dexie.Table<PreservedEditRow, string>;
 
   constructor(siteId: string) {
     super(`brand-portal-${siteId}`);
@@ -164,6 +173,20 @@ class EditorDatabase extends Dexie {
       await tx.table("siteIndex").clear();
       await tx.table("contentCache").clear();
     });
+    // v9: preservedEdits store — snapshots of local edits about to be
+    // superseded by a takeover or conflict resolution, so nothing is silently
+    // destroyed.
+    this.version(9).stores({
+      sections: "sectionId",
+      siteIndex: "key",
+      meta: "key",
+      siteConfig: "key",
+      contentCache: "key",
+      mediaManifest: "key",
+      pendingMedia: "id",
+      pendingMediaDeletions: "id",
+      preservedEdits: "id, sectionId",
+    });
   }
 }
 
@@ -539,3 +562,24 @@ export async function clearPendingMediaByIds(
     if (deletionIds.length > 0) await database.pendingMediaDeletions.bulkDelete(deletionIds);
   });
 }
+
+/** Snapshot a local edit that is about to be superseded (takeover or conflict
+ *  resolution) so it is recoverable rather than silently destroyed. */
+export async function preserveEdit(
+  sectionId: string,
+  content: SectionContent,
+  reason: "takeover" | "conflict",
+): Promise<string> {
+  const preservedAt = new Date().toISOString();
+  const id = `${sectionId}:${preservedAt}`;
+  await getDb().preservedEdits.put({ id, sectionId, content, reason, preservedAt });
+  return id;
+}
+
+export async function listPreservedEdits(): Promise<PreservedEditRow[]> {
+  return getDb().preservedEdits.toArray();
+}
+
+export async function removePreservedEdit(id: string): Promise<void> {
+  await getDb().preservedEdits.delete(id);
+}

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

package/src/lib/media-folders.ts

@@ -0,0 +1,232 @@
+import type { MediaFolder, MediaItem, MediaManifest } from "../media/types";
+
+export interface FolderTreeNode {
+  id: string;
+  name: string;
+  children: FolderTreeNode[];
+}
+
+export interface FolderUploadPlan {
+  /** New folder entities to merge into manifest.folders, keyed by new id. */
+  newFolders: Record<string, MediaFolder>;
+  /** Display-folder target per uploaded file (null = root). */
+  fileTargets: { file: File; folderId: string | null }[];
+}
+
+/** Display-folder id. NOT related to MediaItem.folder (the git storage dir). */
+export function createFolderId(): string {
+  const bytes = new Uint8Array(6);
+  crypto.getRandomValues(bytes);
+  return `f_${Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("")}`;
+}
+
+/** True when this folder's parent chain loops back to itself. */
+export function isCyclicFolder(folders: Record<string, MediaFolder>, id: string): boolean {
+  const max = Object.keys(folders).length;
+  let cursor = folders[id]?.parentId ?? null;
+  for (let steps = 0; cursor !== null && folders[cursor] && steps <= max; steps++) {
+    if (cursor === id) return true;
+    cursor = folders[cursor].parentId;
+  }
+  return false;
+}
+
+/**
+ * Effective parent for rendering: null (root) when the parent is missing,
+ * dangling, or `id` itself sits on a parent cycle. Cycle members re-root,
+ * which breaks the loop for their (kept) descendants — corrupt manifests
+ * always render, and healMediaManifest persists this view on save.
+ */
+export function effectiveParentId(folders: Record<string, MediaFolder>, id: string): string | null {
+  const parentId = folders[id]?.parentId ?? null;
+  if (parentId === null || !folders[parentId]) return null;
+  return isCyclicFolder(folders, id) ? null : parentId;
+}
+
+/** Direct children of `parentId`, alphabetically (case-insensitive). */
+export function childFolderIds(folders: Record<string, MediaFolder>, parentId: string | null): string[] {
+  return Object.keys(folders)
+    .filter((id) => effectiveParentId(folders, id) === parentId)
+    .sort((a, b) => folders[a].name.localeCompare(folders[b].name, undefined, { sensitivity: "base" }));
+}
+
+export function buildFolderTree(folders: Record<string, MediaFolder>): FolderTreeNode[] {
+  const build = (parentId: string | null): FolderTreeNode[] =>
+    childFolderIds(folders, parentId).map((id) => ({
+      id,
+      name: folders[id].name,
+      children: build(id),
+    }));
+  return build(null);
+}
+
+/** Names from root to `id` inclusive, cycle-safe. */
+export function folderPathNames(folders: Record<string, MediaFolder>, id: string): string[] {
+  const names: string[] = [];
+  let cursor: string | null = id;
+  while (cursor !== null && folders[cursor]) {
+    names.unshift(folders[cursor].name);
+    cursor = effectiveParentId(folders, cursor);
+  }
+  return names;
+}
+
+/** Folder ids from root to `id` inclusive, cycle-safe. */
+export function folderPathIds(folders: Record<string, MediaFolder>, id: string): string[] {
+  const ids: string[] = [];
+  let cursor: string | null = id;
+  while (cursor !== null && folders[cursor]) {
+    ids.unshift(cursor);
+    cursor = effectiveParentId(folders, cursor);
+  }
+  return ids;
+}
+
+/** All folders under `id` (by effective parent), INCLUDING `id` itself. */
+export function descendantFolderIds(folders: Record<string, MediaFolder>, id: string): Set<string> {
+  const result = new Set<string>([id]);
+  const ids = Object.keys(folders);
+  let grew = true;
+  while (grew) {
+    grew = false;
+    for (const fid of ids) {
+      if (result.has(fid)) continue;
+      const parent = effectiveParentId(folders, fid);
+      if (parent !== null && result.has(parent)) {
+        result.add(fid);
+        grew = true;
+      }
+    }
+  }
+  return result;
+}
+
+/** May `id` re-parent to `targetParentId`? Blocks self/descendant targets and no-ops. */
+export function canMoveFolder(
+  folders: Record<string, MediaFolder>,
+  id: string,
+  targetParentId: string | null,
+): boolean {
+  if (!folders[id]) return false;
+  if (targetParentId === null) return effectiveParentId(folders, id) !== null;
+  if (!folders[targetParentId]) return false;
+  if (descendantFolderIds(folders, id).has(targetParentId)) return false;
+  return effectiveParentId(folders, id) !== targetParentId;
+}
+
+/** Trimmed `desired`, auto-suffixed " (2)", " (3)"… on case-insensitive sibling collision. */
+export function uniqueFolderName(
+  folders: Record<string, MediaFolder>,
+  parentId: string | null,
+  desired: string,
+  excludeId?: string,
+): string {
+  const base = desired.trim();
+  const siblings = new Set(
+    childFolderIds(folders, parentId)
+      .filter((id) => id !== excludeId)
+      .map((id) => folders[id].name.toLowerCase()),
+  );
+  if (!siblings.has(base.toLowerCase())) return base;
+  for (let n = 2; ; n++) {
+    const candidate = `${base} (${n})`;
+    if (!siblings.has(candidate.toLowerCase())) return candidate;
+  }
+}
+
+/** The folder an item renders in: its folderId when it points at a real folder, else root. */
+export function itemFolderId(
+  folders: Record<string, MediaFolder>,
+  item: Pick<MediaItem, "folderId">,
+): string | null {
+  return item.folderId && folders[item.folderId] ? item.folderId : null;
+}
+
+/** Recursive item counts per folder id (an item counts toward every ancestor). */
+export function recursiveItemCounts(
+  folders: Record<string, MediaFolder>,
+  items: MediaItem[],
+): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const item of items) {
+    let cursor = itemFolderId(folders, item);
+    const seen = new Set<string>();
+    while (cursor !== null && !seen.has(cursor)) {
+      seen.add(cursor);
+      counts[cursor] = (counts[cursor] ?? 0) + 1;
+      cursor = effectiveParentId(folders, cursor);
+    }
+  }
+  return counts;
+}
+
+/** Pure heal: dangling folderIds dropped, orphan/cyclic folders re-rooted. */
+export function healMediaManifest(manifest: MediaManifest): MediaManifest {
+  const folders: Record<string, MediaFolder> = {};
+  for (const [id, f] of Object.entries(manifest.folders)) {
+    folders[id] = { ...f, parentId: effectiveParentId(manifest.folders, id) };
+  }
+  const images: MediaManifest["images"] = {};
+  for (const [id, entry] of Object.entries(manifest.images)) {
+    if (entry.folderId && !folders[entry.folderId]) {
+      const { folderId: _dropped, ...rest } = entry;
+      images[id] = rest;
+    } else {
+      images[id] = entry;
+    }
+  }
+  return { ...manifest, images, folders };
+}
+
+/**
+ * Save-time manifest assembly: merge uploaded pending items, apply deletions,
+ * preserve every other manifest key (folders!), then heal.
+ */
+export function assembleSavedManifest(
+  manifest: MediaManifest,
+  uploadedItems: MediaItem[],
+  deletedIds: string[],
+): MediaManifest {
+  const images = { ...manifest.images };
+  for (const entry of uploadedItems) images[entry.id] = entry;
+  for (const id of deletedIds) delete images[id];
+  return healMediaManifest({ ...manifest, images });
+}
+
+/**
+ * Map webkitRelativePath-style paths onto folder entities under
+ * `currentFolderId`, merging with existing folders by case-insensitive name.
+ */
+export function planFolderUpload(
+  files: { file: File; relativePath: string }[],
+  folders: Record<string, MediaFolder>,
+  currentFolderId: string | null,
+  newId: () => string = createFolderId,
+): FolderUploadPlan {
+  const newFolders: Record<string, MediaFolder> = {};
+  // (parentId, lowercased name) -> folder id, seeded from existing folders.
+  const byName = new Map<string, string>();
+  for (const [fid, f] of Object.entries(folders)) {
+    byName.set(`${effectiveParentId(folders, fid)}/${f.name.toLowerCase()}`, fid);
+  }
+  const ensureDir = (segments: string[]): string | null => {
+    let parent = currentFolderId;
+    for (const segment of segments) {
+      const key = `${parent}/${segment.toLowerCase()}`;
+      let fid = byName.get(key);
+      if (!fid) {
+        fid = newId();
+        newFolders[fid] = { name: segment, parentId: parent };
+        byName.set(key, fid);
+      }
+      parent = fid;
+    }
+    return parent;
+  };
+  const fileTargets = files.map(({ file, relativePath }) => {
+    const segments = relativePath.split("/").filter(Boolean);
+    segments.pop(); // filename
+    return { file, folderId: ensureDir(segments) };
+  });
+  return { newFolders, fileTargets };
+}

package/src/lib/registry.ts

@@ -109,6 +109,14 @@ export interface WrapperProps {
   mainStatus?: string | null;
   contentDiffersFromMain?: boolean;
   isLocalOnly?: boolean;
+  /** Collaboration: when another editor holds this section's lock, their identity.
+   *  Renders a lock badge, makes content inert, and suppresses mutation chrome. */
+  lockedBy?: { email: string } | null;
+  /** Collaboration: request the lock be stolen from the current holder. */
+  onTakeover?: () => void;
+  /** Collaboration: fired on focus-in to request the lock. Resolves false when
+   *  denied (caller keeps the section read-only via `lockedBy`). */
+  onEditIntent?: () => Promise<boolean>;
   children: React.ReactNode;
 }