@drawnagency/primitives 0.1.99 → 0.1.101

package/src/hooks/useDocumentUploads.ts

@@ -0,0 +1,336 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { DOCUMENT_CACHE_CONTROL } from "../storage/types";
+import { hashFileBuffer } from "../media/utils";
+import type { DocumentManifest, DocumentManifestEntry } from "../schemas/documents";
+import {
+  planDocumentUpload,
+  documentRejectionMessage,
+  documentGitPath,
+  documentBucketPath,
+  type DocumentRejectionReason,
+} from "../lib/document-uploads";
+import {
+  addPendingDocument,
+  clearPendingDocumentsByIds,
+  getPendingDocuments,
+} from "../lib/dexie";
+import type { PendingDocument } from "../components/shell/MediaLibraryContext";
+
+const REJECTION_CODES: ReadonlySet<string> = new Set([
+  "unsupported_type",
+  "too_large",
+  "too_small",
+  "no_documents_store",
+]);
+
+interface UseDocumentUploadsInput {
+  documentManifest: DocumentManifest;
+  setDocumentManifest: React.Dispatch<React.SetStateAction<DocumentManifest>>;
+  setLocalChangesExist: React.Dispatch<React.SetStateAction<boolean>>;
+  /** Drops a committed-but-locally-deleted id from the pipeline's
+   *  `pendingDocumentDeletions`. That list lives in useMediaPipeline and is
+   *  invisible here, so without this the dedup below cannot tell a live
+   *  document from a doomed one. No-op for an id that isn't doomed. */
+  undeleteDocument?: (id: string) => void;
+  /** Same channel the media pipeline uses — surfaces in UploadRejectionAlert. */
+  onUploadError?: (message: string) => void;
+}
+
+/**
+ * Document uploads. Deliberately a separate hook from useMediaPipeline: bytes
+ * pass through untouched (no rasterizer worker, no variants, no poster), the
+ * manifest is a sidecar, and every rejection is typed. Both tiers must (1) never
+ * throw to the caller, (2) call onUploadError exactly once on failure, and (3)
+ * leave no leaked progress entry.
+ */
+export function useDocumentUploads({
+  documentManifest,
+  setDocumentManifest,
+  setLocalChangesExist,
+  undeleteDocument,
+  onUploadError,
+}: UseDocumentUploadsInput) {
+  const [pendingDocuments, setPendingDocuments] = useState<PendingDocument[]>([]);
+  const [pendingDocumentUrls, setPendingDocumentUrls] = useState<Record<string, string>>({});
+  const [documentUploadProgress, setDocumentUploadProgress] = useState<Record<string, number>>({});
+
+  // Read inside uploadDocument's async body, where a state snapshot would be
+  // stale across an await.
+  const pendingRef = useRef<PendingDocument[]>(pendingDocuments);
+  useEffect(() => { pendingRef.current = pendingDocuments; }, [pendingDocuments]);
+  const manifestRef = useRef<DocumentManifest>(documentManifest);
+  useEffect(() => { manifestRef.current = documentManifest; }, [documentManifest]);
+
+  /** Restore documents staged in a previous session (Dexie survives reload). */
+  const hydratePendingDocuments = useCallback(async () => {
+    // Never throws: it runs from a mount effect, before/independently of the
+    // editor store being initialized, and a failed restore must not take the
+    // shell down.
+    let rows: Awaited<ReturnType<typeof getPendingDocuments>>;
+    try {
+      rows = await getPendingDocuments();
+    } catch (err) {
+      console.error("[useDocumentUploads] Failed to restore staged documents:", err);
+      return;
+    }
+    if (rows.length === 0) return;
+    setPendingDocuments(rows.map(({ id, entry }) => ({ id, entry })));
+    // The persisted `blob:` URL died with the session that minted it, so a
+    // git-tier row (which carries its bytes) gets a fresh object URL here.
+    // Bucket-tier rows have no blob and keep their stored URL — theirs is a real
+    // remote one. The fallback keeps this function's never-throws contract if a
+    // round-tripped row comes back as something createObjectURL rejects.
+    setPendingDocumentUrls(
+      Object.fromEntries(
+        rows.map(({ id, localUrl, blob }) => {
+          if (!blob) return [id, localUrl];
+          try {
+            return [id, URL.createObjectURL(blob)];
+          } catch (err) {
+            console.error(`[useDocumentUploads] Failed to re-mint a URL for "${id}":`, err);
+            return [id, localUrl];
+          }
+        }),
+      ),
+    );
+  }, []);
+
+  const stage = useCallback(
+    async (id: string, entry: DocumentManifestEntry, blob: Blob | null, localUrl: string, filename: string): Promise<boolean> => {
+      try {
+        await addPendingDocument({ id, entry, blob, localUrl });
+      } catch (err) {
+        console.error(`[useDocumentUploads] Failed to stage "${filename}":`, err);
+        URL.revokeObjectURL(localUrl);
+        onUploadError?.(`"${filename}" couldn't be stored locally — try again.`);
+        return false;
+      }
+      setPendingDocuments((prev) => [...prev, { id, entry }]);
+      setPendingDocumentUrls((prev) => ({ ...prev, [id]: localUrl }));
+      setLocalChangesExist(true);
+      return true;
+    },
+    [onUploadError, setLocalChangesExist],
+  );
+
+  const uploadDocument = useCallback(
+    async (file: File, onComplete?: (documentId: string) => void): Promise<void> => {
+      const plan = planDocumentUpload({ name: file.name, size: file.size, type: file.type });
+      if (plan.tier === "rejected") {
+        onUploadError?.(documentRejectionMessage(plan.reason, file.name));
+        return;
+      }
+
+      let hash: string;
+      try {
+        hash = await hashFileBuffer(await file.arrayBuffer());
+      } catch (err) {
+        console.error(`[useDocumentUploads] Failed to read "${file.name}":`, err);
+        onUploadError?.(`"${file.name}" couldn't be read — try again.`);
+        return;
+      }
+
+      // Same bytes already known: reuse the id rather than staging a duplicate.
+      // Only ever hits on the GIT tier, where the content hash IS the id —
+      // bucket-tier ids are server-minted, so re-picking a large file stages a
+      // second entry. Accepted: the manifest is correct either way, and the
+      // publish-time docs GC collects whichever object stops being referenced.
+      if (manifestRef.current[hash] || pendingRef.current.some((d) => d.id === hash)) {
+        // A committed document deleted but not yet saved is only DOOMED, never
+        // gone: its bytes and its manifest entry are still on the branch, and
+        // deletion deliberately leaves documentManifest alone. So re-adding one
+        // un-dooms it — otherwise the drop zone swallows the file silently, and
+        // the picker points a section at an id the save then deletes. Nothing to
+        // re-upload either way. Tier-agnostic on purpose: a bucket-tier id can
+        // only reach this branch already staged (its ids are server-minted, so
+        // re-picking the file mints a new one), and un-dooming is right there too.
+        undeleteDocument?.(hash);
+        onComplete?.(hash);
+        return;
+      }
+
+      if (plan.tier === "git") {
+        const entry: DocumentManifestEntry = {
+          filename: file.name,
+          size: file.size,
+          kind: plan.kind,
+          storage: "git",
+          path: documentGitPath(file.name, hash, plan.ext),
+        };
+        const localUrl = URL.createObjectURL(file);
+        if (await stage(hash, entry, file, localUrl, file.name)) onComplete?.(hash);
+        return;
+      }
+
+      // The id for a BUCKET-tier document is minted server-side and comes back
+      // from upload-intent — never the client hash (decision 4). It keys both
+      // the object and the manifest entry, so staging under anything else would
+      // point the manifest at bytes that are not there. Declared out here so
+      // the `finally` can clear the progress entry it keys.
+      let documentId = "";
+      try {
+        let uploadUrl: string;
+        let filename: string;
+        try {
+          const res = await fetch("/api/documents/upload-intent", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ name: file.name, size: file.size, contentType: file.type }),
+          });
+          if (!res.ok) {
+            const body = (await res.json().catch(() => ({}))) as { error?: string };
+            const reason: DocumentRejectionReason =
+              body.error && REJECTION_CODES.has(body.error)
+                ? (body.error as DocumentRejectionReason)
+                : "no_documents_store";
+            onUploadError?.(documentRejectionMessage(reason, file.name));
+            return;
+          }
+          const intent = (await res.json()) as {
+            uploadUrl?: unknown; path?: unknown; documentId?: unknown; filename?: unknown; storage?: unknown;
+          };
+          if (
+            typeof intent.uploadUrl !== "string" ||
+            typeof intent.path !== "string" ||
+            typeof intent.documentId !== "string" ||
+            !/^[a-f0-9]{32}$/.test(intent.documentId)
+          ) {
+            throw new Error("malformed upload-intent response");
+          }
+          uploadUrl = intent.uploadUrl;
+          documentId = intent.documentId;
+          filename = typeof intent.filename === "string" && intent.filename ? intent.filename : file.name;
+        } catch (err) {
+          onUploadError?.(`"${file.name}": couldn't start the upload — ${(err as Error).message}. Try again.`);
+          return;
+        }
+
+        try {
+          await new Promise<void>((resolvePut, rejectPut) => {
+            const xhr = new XMLHttpRequest();
+            xhr.open("PUT", uploadUrl);
+            xhr.setRequestHeader("Content-Type", file.type);
+            // The presign signs cache-control;content-type;host — BOTH headers
+            // must be sent byte-exact or R2 403s the PUT, and R2 omits CORS
+            // headers on errors, so the browser misreports it as a CORS block.
+            // (The video path sets ASSET_CACHE_CONTROL the same way.)
+            xhr.setRequestHeader("Cache-Control", DOCUMENT_CACHE_CONTROL);
+            xhr.upload.onprogress = (e) => {
+              if (e.lengthComputable) {
+                setDocumentUploadProgress((prev) => ({ ...prev, [documentId]: e.loaded / e.total }));
+              }
+            };
+            xhr.onload = () =>
+              xhr.status >= 200 && xhr.status < 300 ? resolvePut() : rejectPut(new Error(`upload ${xhr.status}`));
+            xhr.onerror = () => rejectPut(new Error("the storage request was blocked or interrupted"));
+            xhr.send(file);
+          });
+        } catch (err) {
+          onUploadError?.(`"${file.name}": upload failed — ${(err as Error).message}. Try again.`);
+          return;
+        }
+
+        const entry: DocumentManifestEntry = {
+          filename,
+          size: file.size,
+          kind: plan.kind,
+          storage: "bucket",
+          // SITE-RELATIVE, derived from the server's id — deliberately NOT the
+          // intent's `path`, which is the tenant-prefixed object key
+          // (sites/{siteId}/…). DocumentStore prepends that prefix itself, and
+          // the GC and the delete broker both match on the site-relative form.
+          path: documentBucketPath(documentId, plan.ext),
+        };
+        // Manifest-only: the bytes are in the bucket, never in Dexie or /api/save.
+        const localUrl = URL.createObjectURL(file);
+        if (await stage(documentId, entry, null, localUrl, file.name)) onComplete?.(documentId);
+      } finally {
+        setDocumentUploadProgress((prev) => {
+          if (!documentId || !(documentId in prev)) return prev;
+          const next = { ...prev };
+          delete next[documentId];
+          return next;
+        });
+      }
+    },
+    [onUploadError, stage, undeleteDocument],
+  );
+
+  /** Called after a save commits these ids: promote them into the manifest,
+   *  drop the staged rows, release the blob URLs. */
+  const publishDocuments = useCallback(
+    async (ids: string[]) => {
+      if (ids.length === 0) return;
+      const idSet = new Set(ids);
+      const promoted = pendingRef.current.filter((d) => idSet.has(d.id));
+      if (promoted.length > 0) {
+        setDocumentManifest((prev) => {
+          const next = { ...prev };
+          for (const { id, entry } of promoted) next[id] = entry;
+          return next;
+        });
+      }
+      setPendingDocuments((prev) => prev.filter((d) => !idSet.has(d.id)));
+      setPendingDocumentUrls((prev) => {
+        const next = { ...prev };
+        for (const id of ids) {
+          if (next[id]) {
+            URL.revokeObjectURL(next[id]);
+            delete next[id];
+          }
+        }
+        return next;
+      });
+      try {
+        await clearPendingDocumentsByIds(ids);
+      } catch (err) {
+        console.error("[useDocumentUploads] Failed to clear staged documents:", err);
+      }
+    },
+    [setDocumentManifest],
+  );
+
+  /** Drop staged-but-never-committed documents (the local-delete path): release
+   *  the blob URLs and the Dexie rows. Deliberately manifest-free — nothing was
+   *  ever committed, so a save has nothing to remove. A bucket-tier row's
+   *  already-PUT object is left where it is; the publish-time docs GC collects
+   *  whichever object stops being referenced (same acceptance as the re-pick
+   *  dedup case above). */
+  const unstageDocuments = useCallback(async (ids: string[]) => {
+    if (ids.length === 0) return;
+    const idSet = new Set(ids);
+    setPendingDocuments((prev) => prev.filter((d) => !idSet.has(d.id)));
+    setPendingDocumentUrls((prev) => {
+      const next = { ...prev };
+      for (const id of ids) {
+        if (next[id]) {
+          URL.revokeObjectURL(next[id]);
+          delete next[id];
+        }
+      }
+      return next;
+    });
+    try {
+      await clearPendingDocumentsByIds(ids);
+    } catch (err) {
+      console.error("[useDocumentUploads] Failed to clear staged documents:", err);
+    }
+  }, []);
+
+  // Memoized: useMediaPipeline lists this object in handleMediaUpload's and
+  // enqueueFile's dependency arrays, and those two callbacks sit in
+  // contextValue's deps — a fresh literal every render would defeat all three
+  // memos and re-render every MediaLibraryContext consumer on every keystroke.
+  return useMemo(
+    () => ({
+      pendingDocuments,
+      pendingDocumentUrls,
+      documentUploadProgress,
+      uploadDocument,
+      publishDocuments,
+      unstageDocuments,
+      hydratePendingDocuments,
+    }),
+    [pendingDocuments, pendingDocumentUrls, documentUploadProgress, uploadDocument, publishDocuments, unstageDocuments, hydratePendingDocuments],
+  );
+}

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";
 
@@ -114,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 {
@@ -150,6 +164,11 @@ export function useEditorPublish({
   saveChunkBudget,
   savingRef,
   getEditGeneration,
+  documentManifest = {},
+  pendingDocuments = [],
+  pendingDocumentDeletions = [],
+  onDocumentsPublished,
+  onDocumentsDeleted,
 }: PublishDeps) {
   const [publishAction, setPublishAction] = useState<PublishAction>("idle");
   const [publishFeedback, setPublishFeedback] = useState<string | null>(null);
@@ -228,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>;
@@ -237,6 +277,9 @@ 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<{
@@ -248,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(
@@ -265,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);
@@ -294,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;
@@ -342,6 +478,14 @@ 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
@@ -355,6 +499,8 @@ export function useEditorPublish({
         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
@@ -362,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;
     }
   }
@@ -400,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() {
@@ -413,6 +576,9 @@ 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,
     });
@@ -493,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 {
@@ -518,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);
@@ -533,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");
@@ -582,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");
@@ -621,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);
@@ -640,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 };
 }