@drawnagency/primitives 0.1.113 → 0.1.115

package/src/hooks/useEditorPersistence.ts

@@ -1,12 +1,14 @@
-import { useCallback, useMemo, useRef, useEffect } from "react";
+import { useCallback, useMemo, useRef, useEffect, useState } from "react";
 import type { SectionContent } from "../schemas/sections";
 import type { SiteIndex, SiteConfig } from "../schemas/site-config";
-import { persistAll, persistSiteConfig, deleteSectionRows } from "../lib/dexie";
+import { persistAll, deleteSectionRows } from "../lib/dexie";
 
 interface PersistenceState {
   pendingSections: Map<string, SectionContent>;
   indexDirty: boolean;
   configDirty: boolean;
+  pendingConfig: SiteConfig | null;
+  pendingDeletedRows: Set<string>;
   // Durable "unsaved index structure exists" signal. Unlike indexDirty — which is
   // flush-PENDING state and self-clears ~500ms after an edit — this mirrors the
   // lifetime of the Dexie siteIndex row: set on every structural edit, NOT
@@ -43,6 +45,22 @@ interface PersistenceOptions {
   deletedSectionsRef?: React.RefObject<Set<string>>;
 }
 
+const PERSIST_FAILED_COPY = "Your latest edits couldn't be stored in this browser. Keep this tab open and try saving again.";
+// How long Save/Discard wait on an in-flight IndexedDB write before giving up.
+// A hung transaction (Safari private mode, a quota prompt) never settles.
+const FLUSH_WAIT_MS = 10_000;
+
+/** Resolves true once `flush` settles (either way), false if it is still running after FLUSH_WAIT_MS. */
+async function settlesInTime(flush: Promise<void>): Promise<boolean> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timedOut = new Promise<false>((resolve) => { timer = setTimeout(() => resolve(false), FLUSH_WAIT_MS); });
+  try {
+    return await Promise.race([flush.then(() => true, () => true), timedOut]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 export function useEditorPersistence(
   siteIndexRef: React.RefObject<SiteIndex>,
   options?: PersistenceOptions,
@@ -51,67 +69,130 @@ export function useEditorPersistence(
     pendingSections: new Map(),
     indexDirty: false,
     configDirty: false,
+    pendingConfig: null,
+    pendingDeletedRows: new Set(),
     unsavedIndex: false,
     generation: 0,
     indexGeneration: 0,
     sectionGenerations: new Map(),
   });
+  const [persistenceError, setPersistenceError] = useState<string | null>(null);
+  const activeFlush = useRef<Promise<void> | null>(null);
+  // Writes given up on after FLUSH_WAIT_MS; their late outcome must not touch state.
+  const abandonedFlushes = useRef(new WeakSet<Promise<void>>());
+  // Bumped by discardPending so an in-flight flush can't restore discarded edits.
+  const discardEpoch = useRef(0);
   const flushTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const onFlushRef = useRef(options?.onFlush);
   useEffect(() => { onFlushRef.current = options?.onFlush; });
   const deletedSectionsRef = useRef(options?.deletedSectionsRef);
   useEffect(() => { deletedSectionsRef.current = options?.deletedSectionsRef; });
 
-  const flushToDexie = useCallback(async () => {
+  const flushToDexie = useCallback(async (opts?: { exit?: boolean }) => {
+    // Saves wait for an already-running flush before reading Dexie; its failure
+    // restored its entries into state, so this flush retries them. A write that
+    // never settles is abandoned so the editor can recover without a reload.
+    // A tab-close flush can't wait: the unloading page may never resume it, and
+    // IndexedDB applies its later transaction after the in-flight one anyway.
+    while (!opts?.exit && activeFlush.current) {
+      const inFlight = activeFlush.current;
+      if (!(await settlesInTime(inFlight))) abandonedFlushes.current.add(inFlight);
+      if (activeFlush.current === inFlight) activeFlush.current = null;
+    }
     const s = state.current;
-    if (s.pendingSections.size === 0 && !s.indexDirty) return;
+    if (s.pendingSections.size === 0 && !s.indexDirty && !s.pendingConfig && !s.pendingDeletedRows.size) return;
 
     const entries = Array.from(s.pendingSections.entries()).map(([sectionId, content]) => ({
       sectionId,
       content,
     }));
+    const entryGenerations = new Map(s.sectionGenerations);
     const wasIndexDirty = s.indexDirty;
+    const config = s.pendingConfig;
+    const deletedRows = s.pendingDeletedRows;
+    const epoch = discardEpoch.current;
 
     // Clear optimistically so new edits during the await go into a fresh set
     s.pendingSections = new Map();
     s.indexDirty = false;
+    s.pendingConfig = null;
+    s.pendingDeletedRows = new Set();
 
-    try {
-      // The deletion set is cumulative in shell state (cleared only on save or
-      // discard), so every flush rewrites the whole current set — a later flush
-      // can never narrow an earlier record.
-      const pendingDeletions = deletedSectionsRef.current?.current;
-      await persistAll(
-        entries,
-        wasIndexDirty ? siteIndexRef.current : undefined,
-        pendingDeletions && pendingDeletions.size > 0 ? [...pendingDeletions] : undefined,
-      );
-      // Fire only after a successful persist — broadcasting an edit that failed
-      // to persist would let peers diverge from what this editor can recover.
-      onFlushRef.current?.(entries, wasIndexDirty);
-    } catch (err) {
-      // Restore: merge back any entries that weren't re-dirtied during the await
+    // Merge back what this flush took, unless Discard ran since (it would
+    // resurrect discarded edits) or a newer edit superseded it.
+    const restore = () => {
+      if (discardEpoch.current !== epoch) return;
       for (const { sectionId, content } of entries) {
-        if (!s.pendingSections.has(sectionId)) {
+        if (!s.pendingSections.has(sectionId) && s.sectionGenerations.get(sectionId) === entryGenerations.get(sectionId)) {
           s.pendingSections.set(sectionId, content);
         }
       }
       if (wasIndexDirty) s.indexDirty = true;
-      console.error("Failed to flush to Dexie:", err);
+      if (config && !s.pendingConfig) s.pendingConfig = config;
+      for (const id of deletedRows) s.pendingDeletedRows.add(id);
+    };
+
+    let pending: Promise<void>;
+    const write = async () => {
+      try {
+        if (deletedRows.size) await deleteSectionRows([...deletedRows]);
+        // The deletion set is cumulative in shell state (cleared only on save or
+        // discard), so every flush rewrites the whole current set — a later flush
+        // can never narrow an earlier record.
+        const pendingDeletions = deletedSectionsRef.current?.current;
+        await persistAll(
+          entries,
+          wasIndexDirty ? siteIndexRef.current : undefined,
+          pendingDeletions && pendingDeletions.size > 0 ? [...pendingDeletions] : undefined,
+          config ?? undefined,
+        );
+      } catch (err) {
+        console.error("Failed to flush to Dexie:", err);
+        // An abandoned write was already restored when it was given up on.
+        if (!abandonedFlushes.current.has(pending)) {
+          restore();
+          setPersistenceError(PERSIST_FAILED_COPY);
+        }
+        throw new Error(PERSIST_FAILED_COPY, { cause: err });
+      }
+      if (abandonedFlushes.current.has(pending)) return;
+      setPersistenceError(null);
+      // Fire only after a successful persist — broadcasting an edit that failed
+      // to persist would let peers diverge from what this editor can recover.
+      // Config-only and row-delete-only flushes have nothing to broadcast.
+      if (entries.length > 0 || wasIndexDirty) onFlushRef.current?.(entries, wasIndexDirty);
+    };
+    pending = write();
+    activeFlush.current = pending;
+    try {
+      if (!(await settlesInTime(pending))) {
+        abandonedFlushes.current.add(pending);
+        restore();
+        setPersistenceError(PERSIST_FAILED_COPY);
+        throw new Error(PERSIST_FAILED_COPY);
+      }
+      await pending;
+    } finally {
+      if (activeFlush.current === pending) activeFlush.current = null;
     }
   }, [siteIndexRef]);
 
+  // Background flushes surface their error in the banner; explicit saves reject.
+  const flushInBackground = useCallback(() => {
+    void flushToDexie().catch(() => {});
+  }, [flushToDexie]);
+
   const scheduleFlush = useCallback(() => {
     if (flushTimerRef.current) clearTimeout(flushTimerRef.current);
-    flushTimerRef.current = setTimeout(flushToDexie, 500);
-  }, [flushToDexie]);
+    flushTimerRef.current = setTimeout(flushInBackground, 500);
+  }, [flushInBackground]);
 
   useEffect(() => {
     return () => {
       if (flushTimerRef.current) clearTimeout(flushTimerRef.current);
-      void flushToDexie();
+      flushInBackground();
     };
-  }, [flushToDexie]);
+  }, [flushInBackground]);
 
   // Flush pending edits when the tab is hidden or unloaded. The unmount cleanup
   // above is fire-and-forget and does not reliably complete during real document
@@ -126,7 +207,7 @@ export function useEditorPersistence(
         clearTimeout(flushTimerRef.current);
         flushTimerRef.current = null;
       }
-      void flushToDexie();
+      void flushToDexie({ exit: true }).catch(() => {});
     };
     const onVisibilityChange = () => {
       if (document.visibilityState === "hidden") flushOnExit();
@@ -165,9 +246,7 @@ export function useEditorPersistence(
     state.current.unsavedIndex = true;
     state.current.indexGeneration = ++state.current.generation;
     state.current.sectionGenerations.delete(sectionId);
-    deleteSectionRows([sectionId]).catch((err) => {
-      console.error("Failed to delete section row from Dexie:", err);
-    });
+    state.current.pendingDeletedRows.add(sectionId);
     scheduleFlush();
   }, [scheduleFlush]);
 
@@ -190,8 +269,10 @@ export function useEditorPersistence(
 
   const persistConfig = useCallback(async (config: SiteConfig) => {
     state.current.configDirty = true;
-    await persistSiteConfig(config);
-  }, []);
+    state.current.pendingConfig = config;
+    // Resolves once written; a failure surfaces in the persistence banner.
+    await flushToDexie().catch(() => {});
+  }, [flushToDexie]);
 
   const cancelPendingFlush = useCallback(() => {
     if (flushTimerRef.current) {
@@ -200,6 +281,28 @@ export function useEditorPersistence(
     }
   }, []);
 
+  const discardPending = useCallback(async () => {
+    cancelPendingFlush();
+    discardEpoch.current++;
+    // Finish an in-flight write before the caller clears Dexie, or it could
+    // recreate the rows after Discard has removed them. A write that never
+    // settles is abandoned rather than hanging Discard; if it lands later it can
+    // still write discarded rows, which no browser API lets us cancel.
+    while (activeFlush.current) {
+      const inFlight = activeFlush.current;
+      if (!(await settlesInTime(inFlight))) abandonedFlushes.current.add(inFlight);
+      if (activeFlush.current === inFlight) activeFlush.current = null;
+    }
+    state.current.pendingSections.clear();
+    state.current.pendingConfig = null;
+    state.current.pendingDeletedRows.clear();
+    state.current.indexDirty = false;
+    state.current.configDirty = false;
+    state.current.unsavedIndex = false;
+    state.current.sectionGenerations.clear();
+    setPersistenceError(null);
+  }, [cancelPendingFlush]);
+
   const isConfigDirty = useCallback(() => state.current.configDirty, []);
   const clearConfigDirty = useCallback(() => { state.current.configDirty = false; }, []);
   // Reflects whether an index change is pending flush to Dexie. NOTE: this is
@@ -236,14 +339,16 @@ export function useEditorPersistence(
     [],
   );
 
-  // Memoized, and every member above is already identity-stable, so this object
-  // is too. A fresh literal per render changed `persistence`'s identity on every
+  // Memoized, and every member above is identity-stable except persistenceError,
+  // which changes only when a flush fails or recovers — so this object is stable
+  // across ordinary edits. A fresh literal per render changed `persistence`'s identity on every
   // EditorShell render — which churned onBlockMove, getEditIntent,
   // onSectionChange, onAddSection, performDeleteSection, onReorderSections and
   // all twelve page/nav handlers, and made EditorContent tear down and
   // re-register its atlaskit drag monitors on every keystroke.
   return useMemo(
     () => ({
+      persistenceError,
       markSectionDirty,
       markIndexDirty,
       removeSection,
@@ -252,6 +357,7 @@ export function useEditorPersistence(
       persistConfig,
       flushNow: flushToDexie,
       cancelPendingFlush,
+      discardPending,
       isConfigDirty,
       clearConfigDirty,
       isIndexDirty,
@@ -262,8 +368,8 @@ export function useEditorPersistence(
       sectionDirtiedAfter,
     }),
     [
-      markSectionDirty, markIndexDirty, removeSection, dropPendingSection, hasPendingSection,
-      persistConfig, flushToDexie, cancelPendingFlush, isConfigDirty, clearConfigDirty,
+      persistenceError, markSectionDirty, markIndexDirty, removeSection, dropPendingSection, hasPendingSection,
+      persistConfig, flushToDexie, cancelPendingFlush, discardPending, isConfigDirty, clearConfigDirty,
       isIndexDirty, hasUnsavedIndex, clearUnsavedIndex, noteUnsavedIndex, currentGeneration,
       sectionDirtiedAfter,
     ],

package/src/hooks/useEditorPublish.ts

@@ -1,4 +1,7 @@
-import { useState, useCallback, useRef, useEffect } from "react";
+import { useState, useCallback, useRef } from "react";
+import { useNotice } from "./useNotice";
+import { COPY } from "../components/shared/copy";
+import type { NoticeTone } from "../components/shared/Notice";
 import type { SiteIndex, SiteConfig } from "../schemas/site-config";
 import type { SectionContent } from "../schemas/sections";
 import type { LoadedSection } from "../lib/loader";
@@ -7,6 +10,7 @@ import { getDirtySectionRows, hasLocalChanges, discardSavedChanges, cacheContent
 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 { imageVariantPath } from "../lib/image-variant-plan";
 import { buildCommittedBaseline } from "../collab/recovery";
 
 function blobToBase64(blob: Blob): Promise<string> {
@@ -60,6 +64,9 @@ interface PublishDeps {
   clearConfigDirty: () => void;
   siteIndexRef: React.RefObject<SiteIndex>;
   siteConfig: SiteConfig | null;
+  /** This session's tags read was degraded; the cache re-primes record tags
+   *  as not loaded (see cacheContent). */
+  tagsDegraded: boolean;
   sections: LoadedSection[];
   deletedSectionIds?: string[];
   /** Receives the ids that were actually committed this save (so the caller can
@@ -81,7 +88,7 @@ interface PublishDeps {
   pendingMediaDeletions: string[];
   onMediaPublished: (publishedItems: MediaItem[], publishedDeletions: string[]) => void;
   onShasUpdated: (savedSha: string | null, mainSha: string | null) => void;
-  onPublishComplete?: () => void;
+  onPublishComplete?: (sha: string) => void;
   // The draft version this editor is based on (saved-branch head, or null when
   // no draft exists yet). Sent with saves so the server can 409 on a concurrent
   // edit instead of silently overwriting it. Read at save time (latest value).
@@ -145,6 +152,7 @@ export function useEditorPublish({
   clearConfigDirty,
   siteIndexRef,
   siteConfig,
+  tagsDegraded,
   sections,
   deletedSectionIds,
   onSuccess,
@@ -171,23 +179,10 @@ export function useEditorPublish({
   onDocumentsDeleted,
 }: PublishDeps) {
   const [publishAction, setPublishAction] = useState<PublishAction>("idle");
-  const [publishFeedback, setPublishFeedback] = useState<string | null>(null);
+  const { notice: publishFeedback, show: showFeedback, clear: clearPublishFeedback } = useNotice();
   const [saveProgress, setSaveProgress] = useState<string | null>(null);
-  const feedbackTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const inFlightRef = useRef(false);
 
-  useEffect(() => {
-    return () => {
-      if (feedbackTimerRef.current) clearTimeout(feedbackTimerRef.current);
-    };
-  }, []);
-
-  const showFeedback = useCallback((message: string, duration: number) => {
-    setPublishFeedback(message);
-    if (feedbackTimerRef.current) clearTimeout(feedbackTimerRef.current);
-    feedbackTimerRef.current = setTimeout(() => setPublishFeedback(null), duration);
-  }, []);
-
   async function gatherMediaPayload(
     pendingItems: MediaItem[],
     pendingDeletions: string[],
@@ -218,7 +213,7 @@ export function useEditorPublish({
           const ext = mimeExt[item.mimeType] ?? "bin";
           blobPayloads.push({ path: `assets/images/${item.folder}/original.${ext}`, base64 });
         } else {
-          blobPayloads.push({ path: `assets/images/${item.folder}/${key}.webp`, base64 });
+          blobPayloads.push({ path: imageVariantPath(item.folder, key), base64 });
         }
       }
 
@@ -591,7 +586,7 @@ export function useEditorPublish({
     recoveredRef.current = false;
     editTokenRef.current = getEditGeneration?.() ?? Number.MAX_SAFE_INTEGER;
     setPublishAction("saving");
-    setPublishFeedback(null);
+    clearPublishFeedback();
     return true;
   }
 
@@ -675,12 +670,13 @@ export function useEditorPublish({
     // M1 honesty: only claim the view was updated when recovery actually
     // rebased it this invocation (i.e. the RETRY 409'd). A failed/absent/
     // skipped recovery left the view untouched — say so.
+    const tone: NoticeTone = isConflict && recoveredRef.current ? "warning" : "error";
     const message = isConflict
       ? recoveredRef.current
         ? "Someone else saved while you were editing — your view has been updated; try saving again."
         : "This site was changed elsewhere — reload to get the latest, then re-apply your edits."
       : error instanceof Error && error.message ? error.message : `${failLabel} failed`;
-    showFeedback(message, isConflict ? 8000 : 6000);
+    showFeedback(tone, message, { ttlMs: isConflict ? 8000 : 6000 });
   }
 
   const handleSave = useCallback(async () => {
@@ -726,11 +722,11 @@ export function useEditorPublish({
         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);
+        showFeedback("warning", "Saved, but the local cache couldn't be updated — reload the editor.", { ttlMs: 8000 });
         return;
       }
 
-      showFeedback("Saved", 3000);
+      showFeedback("success", COPY.publish.saved, { ttlMs: 3000 });
     } catch (error) {
       reportSaveError(error, "Save");
     } finally {
@@ -748,7 +744,7 @@ export function useEditorPublish({
     if (inFlightRef.current) return;
     inFlightRef.current = true;
     setPublishAction("publishing");
-    setPublishFeedback(null);
+    clearPublishFeedback();
 
     try {
       const response = await fetch("/api/publish", {
@@ -772,10 +768,10 @@ export function useEditorPublish({
       // restored on a later cache hit. (Save & Publish already re-caches instead.)
       await clearContentCache();
       onShasUpdated(null, sha);
-      onPublishComplete?.();
+      onPublishComplete?.(sha);
     } catch (error) {
       console.error("Publish failed:", error);
-      showFeedback("Publish failed", 5000);
+      showFeedback("error", COPY.publish.publishFailed, { ttlMs: 5000 });
     } finally {
       inFlightRef.current = false;
       setPublishAction("idle");
@@ -824,7 +820,7 @@ export function useEditorPublish({
           await cacheContent(saved.sha, baselineSections, saved.sentIndex, siteConfig!, {
             media: saved.committedManifest,
             documents: saved.committedDocumentManifest,
-          });
+          }, tagsDegraded);
           finishSave(saved.uploadedItems, saved.savedSections.map((r) => r.sectionId));
           if (saved.committedDocumentIds.length > 0) onDocumentsPublished?.(saved.committedDocumentIds);
           if (saved.committedDocumentDeletions.length > 0) onDocumentsDeleted?.(saved.committedDocumentDeletions);
@@ -833,7 +829,7 @@ export function useEditorPublish({
           // top of unknown local state would compound it — stop and tell the
           // editor to reload.
           console.error("Save succeeded but local cleanup failed:", cleanupError);
-          showFeedback("Saved, but the local cache couldn't be updated — reload the editor before publishing.", 8000);
+          showFeedback("warning", "Saved, but the local cache couldn't be updated — reload the editor before publishing.", { ttlMs: 8000 });
           return;
         }
       }
@@ -866,18 +862,18 @@ export function useEditorPublish({
           await cacheContent(sha, baselineSections, sentIndex, siteConfig!, {
             media: committedManifest!,
             documents: committedDocumentManifest!,
-          });
+          }, tagsDegraded);
         } catch (cleanupError) {
           console.error("Publish succeeded but the cache re-key failed:", cleanupError);
           onShasUpdated(null, sha);
-          onPublishComplete?.();
-          showFeedback("Published, but the local cache couldn't be updated — reload the editor.", 8000);
+          onPublishComplete?.(sha);
+          showFeedback("warning", "Published, but the local cache couldn't be updated — reload the editor.", { ttlMs: 8000 });
           return;
         }
       }
 
       onShasUpdated(null, sha);
-      onPublishComplete?.();
+      onPublishComplete?.(sha);
     } catch (error) {
       reportSaveError(error, "Publish");
     } finally {
@@ -886,7 +882,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, pendingDocumentDeletions]);
+  }, [flushNow, cancelPendingFlush, isConfigDirty, clearConfigDirty, siteIndexRef, siteConfig, sections, deletedSectionIds, onSuccess, mediaManifest, manifestDirty, clearManifestDirty, pendingMediaItems, pendingMediaDeletions, onMediaPublished, onShasUpdated, showFeedback, onPublishComplete, recoverConflict, saveChunkBudget, getEditGeneration, pendingDocumentDeletions, tagsDegraded]);
 
   return { publishAction, publishFeedback, saveProgress, handleSave, handlePublish, handleSaveAndPublish };
 }

package/src/hooks/useMediaPipeline.ts

@@ -1,5 +1,6 @@
 import { useState, useCallback, useEffect, useRef, useMemo } from "react";
-import { hashFileBuffer, sanitizeMediaName } from "../media/utils";
+import { hashFileBuffer } from "../media/utils";
+import { mediaIdentity, imageManifestEntry } from "../lib/image-variant-plan";
 import { ProcessingQueue, type QueueItem, type QueueEvent } from "../media/queue";
 import type { MediaManifest, MediaItem as LibraryMediaItem } from "../media/types";
 import type { SiteConfig } from "../schemas/site-config";
@@ -12,7 +13,7 @@ import {
   markPendingMediaDeleted,
   removePendingMediaDeletion,
 } from "../lib/dexie";
-import { generateVideoPoster } from "../media/videoPoster";
+import { generateVideoPoster } from "../media/video-poster";
 import { ASSET_CACHE_CONTROL } from "../storage/types";
 import { tallyImageIds, collectImageIds, clearImageIds, applyLogoDeletion } from "../lib/image-refs";
 import { clearDocumentRefs, tallyDocumentIds } from "../lib/document-refs";
@@ -235,7 +236,16 @@ export function useMediaPipeline({
         if (event.type === "complete" && event.item.result) {
           const result = event.item.result;
           const kind = event.item.kind;
-          const sanitizedName = sanitizeMediaName(event.item.originalName);
+          // A still image's manifest entry comes only from the plan the worker
+          // rendered. One without a plan (a stale cached worker after a deploy)
+          // is a failed upload, never a quiet entry with no variants.
+          if (kind === "image" && !result.plan) {
+            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 — reload the editor and try again.`);
+            return;
+          }
 
           const finalize = async (
             localUrls: Record<string, string>,
@@ -245,23 +255,23 @@ export function useMediaPipeline({
           ) => {
             if (destroyedRef.current) return;
             const targetFolderId = uploadTargetsRef.current.get(event.item.hash) ?? null;
+            // A still image's entry comes from the plan the worker rendered;
+            // animated and video items have no variants, only the identity.
+            const base: LibraryMediaItem = result.plan
+              ? imageManifestEntry(result.plan, result.variants, result.primaryBlob.size)
+              : {
+                ...mediaIdentity(event.item.hash, event.item.originalName),
+                kind,
+                width,
+                height,
+                mimeType: event.item.mimeType,
+                size: result.primaryBlob.size,
+                variants: [],
+                alt: "",
+                storage: "github",
+              };
             const item: LibraryMediaItem = {
-              id: event.item.hash,
-              hash: event.item.hash,
-              kind,
-              originalName: sanitizedName,
-              width,
-              height,
-              mimeType: kind === "image" ? "image/webp" : event.item.mimeType,
-              size: result.primaryBlob.size,
-              folder: `${sanitizedName}-${event.item.hash}`,
-              variants: result.variants.map((v) => ({
-                width: v.width,
-                height: v.height,
-                size: v.size,
-              })),
-              alt: "",
-              storage: "github",
+              ...base,
               ...(targetFolderId ? { folderId: targetFolderId } : {}),
               ...(hiddenUploadsRef.current.get(event.item.hash) ? { hidden: true } : {}),
             };
@@ -408,17 +418,13 @@ export function useMediaPipeline({
 
       try {
         const { posterBlob, width, height, duration } = await generateVideoPoster(file, mediaConfig.quality);
-        const sanitizedName = sanitizeMediaName(file.name);
         const item: LibraryMediaItem = {
-          id: hash,
-          hash,
+          ...mediaIdentity(hash, file.name),
           kind: "video",
-          originalName: sanitizedName,
           width,
           height,
           mimeType: file.type,
           size: file.size,
-          folder: `${sanitizedName}-${hash}`,
           variants: [],
           alt: "",
           storage: "assets",

package/src/hooks/useNotice.ts

@@ -0,0 +1,45 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { NoticeTone } from "../components/shared/Notice";
+
+export interface NoticeState {
+  tone: NoticeTone;
+  message: string;
+}
+
+const DEFAULT_TTL_MS = 5000;
+
+/**
+ * One notice, one timer. `error` is sticky by default (no ttl) since it
+ * usually needs a deliberate dismiss; every other tone auto-clears.
+ * Call a second instance for a notice that must stay visible independently
+ * of another (e.g. toolbar feedback vs. a collab toast).
+ */
+export function useNotice() {
+  const [notice, setNotice] = useState<NoticeState | null>(null);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    return () => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+    };
+  }, []);
+
+  const clear = useCallback(() => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+    setNotice(null);
+  }, []);
+
+  const show = useCallback(
+    (tone: NoticeTone, message: string, options?: { ttlMs?: number }) => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+      setNotice({ tone, message });
+      const ttlMs = options?.ttlMs ?? (tone === "error" ? undefined : DEFAULT_TTL_MS);
+      if (ttlMs !== undefined) {
+        timerRef.current = setTimeout(() => setNotice(null), ttlMs);
+      }
+    },
+    [],
+  );
+
+  return { notice, show, clear };
+}

package/src/hooks/useSortableNavRow.ts

@@ -15,6 +15,17 @@ interface Options {
 const DRAG_TYPE = "nav-tree-row";
 
 /**
+ * One of three sibling drag-and-drop position hooks, split by location type
+ * rather than unified behind a generic `useSortable({ axis })`: this one
+ * (NavLocation — the Pages modal's group-aware nav tree), `useSortableRow`
+ * (flat index — section-ordering lists), and `useBlockDnd` (block/container id
+ * + index — the section canvas, root and nested). A fourth location type
+ * earns its own hook on the same shape (rowRef/handleRef, lazy atlaskit
+ * import, closest-edge state, a ref for the latest callback) rather than a
+ * parameter bag bolted onto an existing one — see docs/superpowers/specs/
+ * 2026-09-04-editor-ui-primitives-consolidation.md § D6 for why a shared
+ * `useSortable` was deferred.
+ *
  * Closest-edge drag wiring for one Pages-modal nav row. A sibling of
  * useSortableRow that speaks NavLocation instead of a flat index; the section
  * modal keeps using the original, so this cannot regress it.