@drawnagency/primitives 0.1.98 → 0.1.100

package/src/hooks/useEditorPublish.ts

@@ -3,8 +3,9 @@ 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, getCachedContent, getPendingMediaBlobs, clearPendingMediaByIds } from "../lib/dexie";
-import { packUploads, type MediaUploadPayload } from "../lib/save-chunks";
+import { getDirtySectionRows, hasLocalChanges, discardSavedChanges, cacheContent, clearContentCache, getCachedContent, getPendingMediaBlobs, clearPendingMediaByIds, getPendingDocumentBlob, clearPendingDocumentsByIds } from "../lib/dexie";
+import { packUploads, packDocumentUploads, type MediaUploadPayload, type DocumentUploadPayload } from "../lib/save-chunks";
+import type { DocumentManifest, DocumentManifestEntry } from "../schemas/documents";
 import { assembleSavedManifest } from "../lib/media-folders";
 import { buildCommittedBaseline } from "../collab/recovery";
 
@@ -24,7 +25,7 @@ function blobToBase64(blob: Blob): Promise<string> {
  *  is preserved verbatim; non-JSON bodies (platform-level rejections) get a
  *  status-coded fallback — or a size hint when the request body itself was
  *  near Netlify's ~6MB limit (should be unreachable once saves are chunked). */
-async function postSave(payload: object): Promise<{ sha: string }> {
+async function postSave(payload: object): Promise<{ sha: string; warnings?: string[] }> {
   const body = JSON.stringify(payload);
   let response: Response;
   try {
@@ -47,9 +48,9 @@ async function postSave(payload: object): Promise<{ sha: string }> {
       : `Save failed (HTTP ${response.status})`;
     throw Object.assign(new Error(serverMessage || fallback), { status: response.status });
   }
-  const data = await response.json().catch(() => null) as { sha?: string } | null;
+  const data = await response.json().catch(() => null) as { sha?: string; warnings?: string[] } | null;
   if (!data?.sha) throw new Error("Save response missing SHA");
-  return data as { sha: string };
+  return data as { sha: string; warnings?: string[] };
 }
 
 interface PublishDeps {
@@ -98,6 +99,11 @@ interface PublishDeps {
    *  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>;
+  /** Injected by EditorShell. Receives non-fatal server warnings from a
+   *  successful save (e.g. the nav.json replacement was declined by the
+   *  degraded-nav guard) so the shell can surface them instead of the save
+   *  reading as fully landed. */
+  onSaveWarnings?: (warnings: string[]) => 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
@@ -109,6 +115,19 @@ interface PublishDeps {
    *  collab wiring): the token degrades to MAX_SAFE_INTEGER, i.e. "nothing was
    *  edited after capture" — the pre-generation wholesale-clear behavior. */
   getEditGeneration?: () => number;
+  /** Committed document manifest, merged with the staged entries this save
+   *  commits. Optional so pre-documents callers keep compiling. */
+  documentManifest?: DocumentManifest;
+  pendingDocuments?: { id: string; entry: DocumentManifestEntry }[];
+  /** Ids of COMMITTED documents the editor has deleted but not yet saved. They
+   *  ride the final request as `deletedDocumentIds`; a staged-but-uncommitted
+   *  document deleted locally never appears here. */
+  pendingDocumentDeletions?: string[];
+  /** Receives the document ids this save actually committed. */
+  onDocumentsPublished?: (ids: string[]) => void;
+  /** Receives the deleted document ids the successful commit actually carried,
+   *  so the caller can clear exactly those from its pending list. */
+  onDocumentsDeleted?: (ids: string[]) => void;
 }
 
 interface GatheredMedia {
@@ -141,9 +160,15 @@ export function useEditorPublish({
   getBaseVersion,
   recoverConflict,
   onBaselineCommitted,
+  onSaveWarnings,
   saveChunkBudget,
   savingRef,
   getEditGeneration,
+  documentManifest = {},
+  pendingDocuments = [],
+  pendingDocumentDeletions = [],
+  onDocumentsPublished,
+  onDocumentsDeleted,
 }: PublishDeps) {
   const [publishAction, setPublishAction] = useState<PublishAction>("idle");
   const [publishFeedback, setPublishFeedback] = useState<string | null>(null);
@@ -222,6 +247,27 @@ export function useEditorPublish({
     return { mediaUploads, updatedManifest, hasMediaChanges };
   }
 
+  /** Read staged document bytes out of Dexie and merge their entries onto the
+   *  committed manifest. A row whose blob is gone (cleared storage) is skipped,
+   *  never written to the manifest — the same no-orphan rule as media. */
+  async function gatherDocumentPayload(
+    pending: { id: string; entry: DocumentManifestEntry }[],
+    manifest: DocumentManifest,
+  ): Promise<{ uploads: DocumentUploadPayload[]; entries: { id: string; entry: DocumentManifestEntry }[] }> {
+    const uploads: DocumentUploadPayload[] = [];
+    const entries: { id: string; entry: DocumentManifestEntry }[] = [];
+    for (const { id, entry } of pending) {
+      if (manifest[id]) continue; // already committed by another writer
+      if (entry.storage === "git") {
+        const blob = await getPendingDocumentBlob(id);
+        if (!blob) continue;
+        uploads.push({ id, path: entry.path, base64: await blobToBase64(blob) });
+      }
+      entries.push({ id, entry });
+    }
+    return { uploads, entries };
+  }
+
   async function performSave(args: {
     siteConfig: SiteConfig;
     siteIndexRef: React.RefObject<SiteIndex>;
@@ -231,7 +277,11 @@ export function useEditorPublish({
     pendingMediaDeletions: string[];
     mediaManifest: MediaManifest;
     manifestDirty: boolean;
+    documentManifest: DocumentManifest;
+    pendingDocuments: { id: string; entry: DocumentManifestEntry }[];
+    pendingDocumentDeletions: string[];
     saveChunkBudget?: number;
+    onSaveWarnings?: (warnings: string[]) => void;
   }): Promise<{
     sha: string;
     // sectionId+updatedAt for compare-and-clear cleanup, plus the SENT content —
@@ -241,6 +291,10 @@ export function useEditorPublish({
     uploadedItems: MediaItem[];
     // The index actually sent (deletions applied) — the committed index state.
     sentIndex: SiteIndex;
+    committedDocumentIds: string[];
+    // The deleted ids the final request actually carried — empty when nothing
+    // was staged, and never populated on a failure (see the catch below).
+    committedDocumentDeletions: string[];
   }> {
     const dirty = await getDirtySectionRows();
     const gathered = await gatherMediaPayload(
@@ -258,6 +312,17 @@ export function useEditorPublish({
       );
     }
 
+    const gatheredDocs = await gatherDocumentPayload(args.pendingDocuments, args.documentManifest);
+    const { chunks: docChunks, oversized: oversizedDocs } = packDocumentUploads(gatheredDocs.uploads);
+    if (oversizedDocs.length > 0) {
+      const names = oversizedDocs
+        .map((u) => `"${args.pendingDocuments.find((d) => d.id === u.id)?.entry.filename ?? u.path}"`)
+        .join(", ");
+      throw new Error(
+        `${names} ${oversizedDocs.length === 1 ? "is" : "are"} too large to save — remove the document and try again.`,
+      );
+    }
+
     let siteIndex = args.siteIndexRef.current;
     if (args.deletedSectionIds?.length) {
       const deleteSet = new Set(args.deletedSectionIds);
@@ -287,8 +352,86 @@ export function useEditorPublish({
     const finalUploads: MediaUploadPayload[] = chunks.length > 0 ? chunks[chunks.length - 1] : [];
     const committedImages: Record<string, MediaItem> = {};
     let sent = 0;
+    // Hoisted out of the try so the catch's leadChunksCommitted guard can read
+    // what the document phase already committed.
+    const committedDocuments: Record<string, DocumentManifestEntry> = {};
+    const committedDocumentIds: string[] = [];
+
+    // Every request's sidecar payload: the committed view plus what THIS save
+    // has committed so far, minus the ids it is deleting. The subtraction is
+    // what makes a mixed upload+delete save safe — content-ops merges the
+    // sidecar anti-clobber, and the deletion only rides the FINAL request, so a
+    // doomed entry re-asserted by an intermediate document chunk would be
+    // re-merged onto the branch and outlive the save.
+    const doomedDocumentIds = new Set(args.pendingDocumentDeletions);
+    const documentManifestToSend = (): DocumentManifest => {
+      const merged: DocumentManifest = { ...args.documentManifest, ...committedDocuments };
+      for (const id of doomedDocumentIds) delete merged[id];
+      return merged;
+    };
 
     try {
+      // Documents commit FIRST, in their own requests: one 2.5MiB document
+      // base64s to ~3.4MB, so it can never share a request with sections/index
+      // (or with another document) inside Netlify's body limit.
+      //
+      // WIRE SHAPE (reconciliation decision 1): bytes ride the existing
+      // `media.uploads[].blobs` array — content-ops' path guard was widened to
+      // accept assets/documents/ exactly so this works with no second code path
+      // — and the sidecar travels as the TOP-LEVEL `documentManifest` key.
+      // There is no `documents:` key. `media.manifest` is deliberately omitted:
+      // a document chunk must not rewrite image-manifest.json from a stale copy.
+      // Each request's manifest carries only entries whose bytes it commits;
+      // content-ops merges anti-clobber, so repeated merges are idempotent.
+      const uploadedIds = new Set(gatheredDocs.uploads.map((u) => u.id));
+      const entryById = new Map(gatheredDocs.entries.map((e) => [e.id, e.entry]));
+
+      for (const chunk of docChunks) {
+        for (const upload of chunk) {
+          const entry = entryById.get(upload.id);
+          if (entry) committedDocuments[upload.id] = entry;
+        }
+        const data = await postSave({
+          baseVersion,
+          media: {
+            uploads: chunk.map(({ id, path, base64 }) => ({
+              // content-ops ignores `item` for blob emission; the folder segment
+              // keeps the payload legible in a request log.
+              item: { id, folder: path.split("/")[2] },
+              blobs: [{ path, base64 }],
+            })),
+            deletions: [],
+          },
+          documentManifest: documentManifestToSend(),
+        });
+        baseVersion = data.sha;
+        committedDocumentIds.push(...chunk.map((u) => u.id));
+        try {
+          await clearPendingDocumentsByIds(chunk.map((u) => u.id));
+        } catch (promoteError) {
+          console.error("Failed to clear committed documents locally:", promoteError);
+        }
+      }
+
+      // Bucket-tier entries have no bytes to ship; they ride one manifest-only
+      // request (no `media` key at all) so the manifest never references an
+      // uncommitted object.
+      const manifestOnly = gatheredDocs.entries.filter((e) => !uploadedIds.has(e.id));
+      if (manifestOnly.length > 0) {
+        for (const { id, entry } of manifestOnly) committedDocuments[id] = entry;
+        const data = await postSave({
+          baseVersion,
+          documentManifest: documentManifestToSend(),
+        });
+        baseVersion = data.sha;
+        committedDocumentIds.push(...manifestOnly.map((e) => e.id));
+        try {
+          await clearPendingDocumentsByIds(manifestOnly.map((e) => e.id));
+        } catch (promoteError) {
+          console.error("Failed to clear committed documents locally:", promoteError);
+        }
+      }
+
       for (const chunk of leadChunks) {
         setSaveProgress(`Saving images ${sent + chunk.length}/${totalUploads}…`);
         for (const upload of chunk) committedImages[upload.item.id] = upload.item;
@@ -335,13 +478,29 @@ export function useEditorPublish({
             manifest: gathered.updatedManifest,
           },
         } : {}),
+        // Deletions ride ONLY this request — never a document chunk — so a
+        // failure anywhere leaves them entirely uncommitted and the caller's
+        // pending list intact for a retry. That is also why, unlike
+        // committedDocumentIds, they need no catch-path promotion below.
+        ...(args.pendingDocumentDeletions.length > 0 ? {
+          deletedDocumentIds: args.pendingDocumentDeletions,
+          documentManifest: documentManifestToSend(),
+        } : {}),
       });
 
+      // Surface server-side warnings (e.g. the degraded-nav guard declining to
+      // replace nav.json) — the save succeeded, but part of it was refused, and
+      // the editor believing it landed is exactly the silence the guard exists
+      // to break.
+      if (responseData.warnings?.length) args.onSaveWarnings?.(responseData.warnings);
+
       return {
         sha: responseData.sha,
         savedSections: dirty.map(({ sectionId, updatedAt, content }) => ({ sectionId, updatedAt, content })),
         uploadedItems: [...uploadedItems, ...finalUploads.map((u) => u.item)],
         sentIndex: siteIndex,
+        committedDocumentIds,
+        committedDocumentDeletions: args.pendingDocumentDeletions,
       };
     } catch (error) {
       // I2: once a lead chunk has committed (advancing the draft head), a 409
@@ -349,9 +508,25 @@ export function useEditorPublish({
       // 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") {
+      if ((sent > 0 || committedDocumentIds.length > 0) && error && typeof error === "object") {
         (error as { leadChunksCommitted?: boolean }).leadChunksCommitted = true;
       }
+      // Documents that DID commit are on the server, and their Dexie rows are
+      // already cleared — so promote them regardless of what failed afterwards.
+      // Without this their pendingDocuments entries never clear and
+      // hasPendingEdits() stays true forever: the retry skips the committed doc
+      // (gatherDocumentPayload finds no row), so nothing ever promotes them.
+      // Cannot double-promote: committedDocumentIds being non-empty sets
+      // leadChunksCommitted, which suppresses the 409 retry entirely — so at
+      // most one attempt per save ever reaches here with documents committed.
+      if (committedDocumentIds.length > 0) {
+        try {
+          onDocumentsPublished?.(committedDocumentIds);
+        } catch (promoteError) {
+          // Never let the promotion callback mask the real failure.
+          console.error("Failed to promote committed documents after a failed save:", promoteError);
+        }
+      }
       throw error;
     }
   }
@@ -387,8 +562,9 @@ export function useEditorPublish({
   async function hasPendingEdits(): Promise<boolean> {
     const hasChanges = await hasLocalChanges();
     const hasMediaChanges = pendingMediaItems.length > 0 || pendingMediaDeletions.length > 0 || manifestDirty;
+    const hasDocumentChanges = pendingDocuments.length > 0 || pendingDocumentDeletions.length > 0;
     const hasDeletedSections = (deletedSectionIds?.length ?? 0) > 0;
-    return hasChanges || isConfigDirty() || hasMediaChanges || hasDeletedSections;
+    return hasChanges || isConfigDirty() || hasMediaChanges || hasDocumentChanges || hasDeletedSections;
   }
 
   function runPerformSave() {
@@ -400,7 +576,11 @@ export function useEditorPublish({
       // Read through the ref (when the shell supplies one) so the 409 retry
       // below sees recoverConflict's rebased manifest, not this render's copy.
       mediaManifest: mediaManifestRef?.current ?? mediaManifest,
+      documentManifest,
+      pendingDocuments,
+      pendingDocumentDeletions,
       saveChunkBudget,
+      onSaveWarnings,
     });
   }
 
@@ -479,7 +659,7 @@ export function useEditorPublish({
         return;
       }
 
-      const { sha, savedSections, uploadedItems, sentIndex } = await saveWithConflictRecovery();
+      const { sha, savedSections, uploadedItems, sentIndex, committedDocumentIds, committedDocumentDeletions } = await saveWithConflictRecovery();
       onShasUpdated(sha, null);
 
       try {
@@ -504,6 +684,8 @@ export function useEditorPublish({
           });
         }
         finishSave(uploadedItems, savedSections.map((s) => s.sectionId));
+        if (committedDocumentIds.length > 0) onDocumentsPublished?.(committedDocumentIds);
+        if (committedDocumentDeletions.length > 0) onDocumentsDeleted?.(committedDocumentDeletions);
       } catch (cleanupError) {
         console.error("Save succeeded but local cleanup failed:", cleanupError);
         showFeedback("Saved, but the local cache couldn't be updated — reload the editor.", 8000);
@@ -519,7 +701,7 @@ export function useEditorPublish({
       setPublishAction("idle");
       setSaveProgress(null);
     }
-  }, [flushNow, cancelPendingFlush, isConfigDirty, clearConfigDirty, siteIndexRef, siteConfig, sections, deletedSectionIds, onSuccess, mediaManifest, manifestDirty, clearManifestDirty, pendingMediaItems, pendingMediaDeletions, onMediaPublished, onShasUpdated, showFeedback, recoverConflict, onBaselineCommitted, saveChunkBudget, getEditGeneration]);
+  }, [flushNow, cancelPendingFlush, isConfigDirty, clearConfigDirty, siteIndexRef, siteConfig, sections, deletedSectionIds, onSuccess, mediaManifest, manifestDirty, clearManifestDirty, pendingMediaItems, pendingMediaDeletions, onMediaPublished, onShasUpdated, showFeedback, recoverConflict, onBaselineCommitted, saveChunkBudget, getEditGeneration, pendingDocumentDeletions]);
 
   const handlePublish = useCallback(async () => {
     setPublishAction("publishing");
@@ -568,8 +750,10 @@ export function useEditorPublish({
       let savedSections: { sectionId: string; updatedAt: string; content: SectionContent }[] = [];
       let uploadedItems: MediaItem[] = [];
       let sentIndex: SiteIndex | null = null;
+      let committedDocumentIds: string[] = [];
+      let committedDocumentDeletions: string[] = [];
       if (hasLocalEdits) {
-        ({ savedSections, uploadedItems, sentIndex } = await saveWithConflictRecovery());
+        ({ savedSections, uploadedItems, sentIndex, committedDocumentIds, committedDocumentDeletions } = await saveWithConflictRecovery());
       }
 
       setPublishAction("publishing");
@@ -607,6 +791,8 @@ export function useEditorPublish({
           });
           await cacheContent(sha, baselineSections, sentIndex!, siteConfig!);
           finishSave(uploadedItems, savedSections.map((s) => s.sectionId));
+          if (committedDocumentIds.length > 0) onDocumentsPublished?.(committedDocumentIds);
+          if (committedDocumentDeletions.length > 0) onDocumentsDeleted?.(committedDocumentDeletions);
         } catch (cleanupError) {
           console.error("Publish succeeded but local cleanup failed:", cleanupError);
           onShasUpdated(null, sha);
@@ -626,7 +812,7 @@ export function useEditorPublish({
       setPublishAction("idle");
       setSaveProgress(null);
     }
-  }, [flushNow, cancelPendingFlush, isConfigDirty, clearConfigDirty, siteIndexRef, siteConfig, sections, deletedSectionIds, onSuccess, mediaManifest, manifestDirty, clearManifestDirty, pendingMediaItems, pendingMediaDeletions, onMediaPublished, onShasUpdated, showFeedback, onPublishComplete, recoverConflict, saveChunkBudget, getEditGeneration]);
+  }, [flushNow, cancelPendingFlush, isConfigDirty, clearConfigDirty, siteIndexRef, siteConfig, sections, deletedSectionIds, onSuccess, mediaManifest, manifestDirty, clearManifestDirty, pendingMediaItems, pendingMediaDeletions, onMediaPublished, onShasUpdated, showFeedback, onPublishComplete, recoverConflict, saveChunkBudget, getEditGeneration, pendingDocumentDeletions]);
 
   return { publishAction, publishFeedback, saveProgress, handleSave, handlePublish, handleSaveAndPublish };
 }

package/src/hooks/useMediaPipeline.ts

@@ -15,16 +15,21 @@ import {
 import { generateVideoPoster } from "../media/videoPoster";
 import { ASSET_CACHE_CONTROL } from "../storage/types";
 import { tallyImageIds, collectImageIds, clearImageIds, applyLogoDeletion } from "../lib/image-refs";
+import { clearDocumentRefs, tallyDocumentIds } from "../lib/document-refs";
 import {
   createFolderId, uniqueFolderName, effectiveParentId, canMoveFolder,
   descendantFolderIds, itemFolderId, planFolderUpload,
 } from "../lib/media-folders";
 import type { MediaFolder } from "../media/types";
+import { useDocumentUploads } from "./useDocumentUploads";
+import { DOCUMENT_MIME_TO_EXT, type DocumentManifest } from "../schemas/documents";
 
 interface UseMediaPipelineInput {
   siteConfig: SiteConfig | null;
   mediaManifest: MediaManifest;
   setMediaManifest: React.Dispatch<React.SetStateAction<MediaManifest>>;
+  documentManifest: DocumentManifest;
+  setDocumentManifest: React.Dispatch<React.SetStateAction<DocumentManifest>>;
   sections: LoadedSection[];
   setSections: React.Dispatch<React.SetStateAction<LoadedSection[]>>;
   setLocalChangesExist: React.Dispatch<React.SetStateAction<boolean>>;
@@ -47,6 +52,8 @@ export function useMediaPipeline({
   siteConfig,
   mediaManifest,
   setMediaManifest,
+  documentManifest,
+  setDocumentManifest,
   sections,
   setSections,
   setLocalChangesExist,
@@ -60,6 +67,10 @@ export function useMediaPipeline({
   const [pendingMediaItems, setPendingMediaItems] = useState<LibraryMediaItem[]>([]);
   const [pendingLocalUrls, setPendingLocalUrls] = useState<Record<string, string>>({});
   const [pendingDeletions, setPendingDeletions] = useState<string[]>([]);
+  // Committed documents deleted locally, awaiting the save that carries them as
+  // `deletedDocumentIds`. Staged-but-uncommitted documents never land here —
+  // they are simply unstaged.
+  const [pendingDocumentDeletions, setPendingDocumentDeletions] = useState<string[]>([]);
   // Direct-to-bucket large-video PUT progress, keyed by content hash (0..1).
   // Populated by uploadLargeVideo's XHR upload.onprogress, cleared on
   // completion or failure.
@@ -72,6 +83,34 @@ export function useMediaPipeline({
   // dropped when the editor DOES save in the same session.
   const [manifestDirty, setManifestDirty] = useState(false);
 
+  // Read inside the queue effect, whose deps are deliberately narrow — without
+  // the ref the error branch below would close over the first render's handler.
+  const onUploadErrorRef = useRef(onUploadError);
+  onUploadErrorRef.current = onUploadError;
+
+  // Read inside uploadDocument's async body, where a state snapshot taken at
+  // render time would be stale across the hash await.
+  const pendingDocumentDeletionsRef = useRef<string[]>(pendingDocumentDeletions);
+  pendingDocumentDeletionsRef.current = pendingDocumentDeletions;
+
+  /** Re-adding a document that is deleted-but-unsaved un-dooms it rather than
+   *  letting the upload dedup swallow it — the twin of the image pipeline's
+   *  `isDeleted` escape below. The ref is updated eagerly so two re-adds in one
+   *  tick can't both see the id as doomed. */
+  const undeleteDocument = useCallback((id: string) => {
+    if (!pendingDocumentDeletionsRef.current.includes(id)) return;
+    pendingDocumentDeletionsRef.current = pendingDocumentDeletionsRef.current.filter((d) => d !== id);
+    setPendingDocumentDeletions((prev) => prev.filter((d) => d !== id));
+  }, []);
+
+  const documents = useDocumentUploads({
+    documentManifest,
+    setDocumentManifest,
+    setLocalChangesExist,
+    undeleteDocument,
+    onUploadError,
+  });
+
   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
@@ -138,10 +177,22 @@ export function useMediaPipeline({
       onEvent: (event: QueueEvent) => {
         setProcessingItems((prev) => {
           const next = prev.filter((i) => i.id !== event.item.id);
-          if (event.item.state !== "complete") next.push(event.item);
+          // "error" must LEAVE the list too. Keeping it (the old `!== "complete"`
+          // test) is what left a failed item spinning forever in the toolbar.
+          if (event.item.state !== "complete" && event.item.state !== "error") next.push(event.item);
           return next;
         });
 
+        if (event.type === "error") {
+          uploadTargetsRef.current.delete(event.item.hash);
+          hiddenUploadsRef.current.delete(event.item.hash);
+          uploadCallbacksRef.current.delete(event.item.hash);
+          onUploadErrorRef.current?.(
+            `"${event.item.originalName}" couldn't be processed${event.item.error ? ` — ${event.item.error}` : ""}.`,
+          );
+          return;
+        }
+
         if (event.type === "complete" && event.item.result) {
           const result = event.item.result;
           const kind = event.item.kind;
@@ -359,6 +410,14 @@ export function useMediaPipeline({
 
     let alreadyExisting = 0;
     for (const file of files) {
+      // Documents never touch the rasterizer: their bytes must reach the repo
+      // or the bucket untransformed. Branch before every image-shaped gate
+      // below (size cap, hashing, queue.add).
+      if (file.type in DOCUMENT_MIME_TO_EXT) {
+        await documents.uploadDocument(file);
+        continue;
+      }
+
       if (file.size > mediaConfig.maxFileSize) {
         if (file.type === "video/mp4" || file.type === "video/webm") {
           // uploadLargeVideo already guarantees it never throws (see its own
@@ -406,7 +465,7 @@ export function useMediaPipeline({
           : `${alreadyExisting} files already exist in the library and were left where they are.`,
       );
     }
-  }, [siteConfig, mediaManifest, pendingMediaItems, pendingDeletions, onUploadError, onUploadNotice, uploadLargeVideo]);
+  }, [siteConfig, mediaManifest, pendingMediaItems, pendingDeletions, onUploadError, onUploadNotice, uploadLargeVideo, documents]);
 
   const handleMediaDelete = useCallback(async (ids: string[]) => {
     const idSet = new Set(ids);
@@ -462,6 +521,41 @@ export function useMediaPipeline({
     setLocalChangesExist(true);
   }, [pendingMediaItems, markSectionDirty, setSections, setDirtySectionIds, setLocalChangesExist, siteConfig, onSiteConfigChange]);
 
+  // Document deletion, the twin of handleMediaDelete. It lives here rather than
+  // in useDocumentUploads because the reference-repair pass needs the section
+  // state that hook cannot see; useDocumentUploads owns only the staged-row
+  // cleanup (unstageDocuments).
+  const handleDocumentDelete = useCallback(async (ids: string[]) => {
+    if (ids.length === 0) return;
+    const idSet = new Set(ids);
+    const stagedIds = documents.pendingDocuments.filter((d) => idSet.has(d.id)).map((d) => d.id);
+    // Only a COMMITTED document produces a deletion for the save to carry: a
+    // staged one has no manifest entry on the branch, so recording it would ask
+    // the server to remove something that was never written.
+    const committedIds = ids.filter((id) => id in documentManifest);
+
+    if (stagedIds.length > 0) await documents.unstageDocuments(stagedIds);
+    if (committedIds.length > 0) {
+      // No optimistic documentManifest mutation: the consumption points filter
+      // on this list, and the save co-sends the post-deletion manifest.
+      setPendingDocumentDeletions((prev) => [...prev, ...committedIds.filter((id) => !prev.includes(id))]);
+    }
+
+    setSections((prev) =>
+      prev.map((loaded) => {
+        const { changed, section } = clearDocumentRefs(loaded.section, idSet);
+        if (!changed) return loaded;
+        // A nested hit returns the rewritten CONTAINER — the section that owns
+        // the child's bytes, and so the one that gets dirtied and saved.
+        markSectionDirty(section.id, section as SectionContent);
+        setDirtySectionIds((dirty) => new Set(dirty).add(section.id));
+        return { ...loaded, section };
+      }),
+    );
+
+    setLocalChangesExist(true);
+  }, [documents, documentManifest, markSectionDirty, setSections, setDirtySectionIds, setLocalChangesExist]);
+
   const handleMediaAltChange = useCallback((id: string, alt: string) => {
     setMediaManifest((prev) => {
       const item = prev.images[id];
@@ -608,12 +702,33 @@ export function useMediaPipeline({
     return Object.fromEntries(counts);
   }, [sections, siteConfig]);
 
+  // The document twin of referenceCountMap, feeding the media modal's document
+  // usage pills and its delete confirmation. Unlike images, documents are never
+  // referenced by siteConfig — only by `document` sections, nested ones
+  // included (tallyDocumentIds recurses).
+  const documentReferenceCountMap = useMemo((): Record<string, number> => {
+    const counts = new Map<string, number>();
+    for (const { section } of sections) tallyDocumentIds(section, counts);
+    return Object.fromEntries(counts);
+  }, [sections]);
+
   // --- Unified enqueue ---
 
   const enqueueFile = useCallback((file: File, onComplete?: (imageId: string) => void, opts?: { hidden?: boolean }) => {
     if (!siteConfig) return;
     const mediaConfig = siteConfig.media;
-    if (file.size > mediaConfig.maxFileSize) return;
+    if (file.type in DOCUMENT_MIME_TO_EXT) {
+      void documents.uploadDocument(file, onComplete);
+      return;
+    }
+    if (file.size > mediaConfig.maxFileSize) {
+      // Previously a bare `return` — the file vanished with no spinner, no
+      // error, and no explanation.
+      onUploadError?.(
+        `"${file.name}" is larger than the ${Math.round(mediaConfig.maxFileSize / 1024 / 1024)}MB media limit.`,
+      );
+      return;
+    }
 
     const currentQueue = queueRef.current;
     (async () => {
@@ -645,7 +760,7 @@ export function useMediaPipeline({
         console.error(`[useMediaPipeline] Failed to enqueue file "${file.name}":`, err);
       }
     })();
-  }, [siteConfig, mediaManifest, pendingMediaItems, pendingDeletions]);
+  }, [siteConfig, mediaManifest, pendingMediaItems, pendingDeletions, onUploadError, documents]);
 
   // --- Context value ---
 
@@ -669,7 +784,13 @@ export function useMediaPipeline({
     pendingItems: pendingMediaItems,
     pendingLocalUrls: pendingLocalUrls,
     siteConfig,
-  }), [handleMediaUpload, enqueueFile, mediaManifest, pendingMediaItems, pendingLocalUrls, siteConfig]);
+    // Read by useResolvedDocument (DocumentSourceField's entry/missing lookup).
+    // Document blob URLs deliberately do NOT merge into pendingLocalUrls: their
+    // one consumer is the doc-file registry, which U6 feeds straight from the
+    // pipeline's pendingDocumentUrls — a context copy would be dead surface.
+    documentManifest,
+    pendingDocuments: documents.pendingDocuments,
+  }), [handleMediaUpload, enqueueFile, mediaManifest, pendingMediaItems, pendingLocalUrls, siteConfig, documentManifest, documents.pendingDocuments]);
 
   return {
     processingItems,
@@ -684,6 +805,9 @@ export function useMediaPipeline({
     uploadProgress,
     handleMediaUpload,
     handleMediaDelete,
+    handleDocumentDelete,
+    pendingDocumentDeletions,
+    setPendingDocumentDeletions,
     handleMediaAltChange,
     handleFolderCreate,
     handleFolderRename,
@@ -692,7 +816,14 @@ export function useMediaPipeline({
     handleMediaMove,
     handleFolderUpload,
     referenceCountMap,
+    documentReferenceCountMap,
     contextValue,
     enqueueFile,
+    pendingDocuments: documents.pendingDocuments,
+    pendingDocumentUrls: documents.pendingDocumentUrls,
+    documentUploadProgress: documents.documentUploadProgress,
+    uploadDocument: documents.uploadDocument,
+    publishDocuments: documents.publishDocuments,
+    hydratePendingDocuments: documents.hydratePendingDocuments,
   };
 }

package/src/hooks/useResolvedDocument.ts

@@ -0,0 +1,25 @@
+import { useMemo } from "react";
+import { useMediaLibrary } from "../components/shell/MediaLibraryContext";
+import type { DocumentManifestEntry } from "../schemas/documents";
+
+export interface ResolvedDocument {
+  entry: DocumentManifestEntry | null;
+  /** True only when an id WAS requested and nothing backs it — the editor-side
+   *  "file missing" state. No id (unconfigured section) is not missing. */
+  missing: boolean;
+}
+
+/** Document lookup. Deliberately separate from useResolvedMedia: documents are
+ *  zero-variant and dimensionless, never ride resolveManifestReferences, and
+ *  live in the sidecar manifest. */
+export function useResolvedDocument(documentId: string | undefined): ResolvedDocument {
+  const ctx = useMediaLibrary();
+
+  return useMemo(() => {
+    if (!documentId) return { entry: null, missing: false };
+    const committed = ctx?.documentManifest?.[documentId];
+    const pending = ctx?.pendingDocuments?.find((d) => d.id === documentId)?.entry;
+    const entry = committed ?? pending ?? null;
+    return { entry, missing: entry === null };
+  }, [documentId, ctx]);
+}