canopycms 0.0.67 → 0.0.68-int.101

package/dist/editor/hooks/useBranchesData.js

@@ -13,6 +13,7 @@
  * `mutate()` to revalidate.
  */
 import useSWR from 'swr';
+import { isNonApiResponse } from '../../api/client.js';
 /** Cache key for the branches list. */
 export const BRANCHES_KEY = 'canopy:branches';
 /**
@@ -21,15 +22,20 @@ export const BRANCHES_KEY = 'canopy:branches';
  */
 export async function fetchBranches(apiClient) {
     const result = await apiClient.branches.list();
-    if (result.status === 404) {
+    if (result.status === 404 && !isNonApiResponse(result)) {
         // No branch endpoint available; stay branchless rather than erroring --
         // the branch dropdown stays clickable so the user can retry from there.
-        return { branches: [] };
+        // A proxy's 404 page means the API was not reached, so it is an error.
+        return { branches: [], receivedAt: Date.now() };
     }
     if (!result.ok) {
         throw new Error(result.error ?? `Failed to load branches: ${result.status}`);
     }
-    return { branches: result.data?.branches ?? [], defaultBranch: result.data?.defaultBranch };
+    return {
+        branches: result.data?.branches ?? [],
+        defaultBranch: result.data?.defaultBranch,
+        receivedAt: Date.now(),
+    };
 }
 /**
  * How often to re-poll while at least one branch is mid-flight, in ms.

package/dist/editor/hooks/useCommentSystem.js

@@ -4,6 +4,7 @@ import { notifications } from '@mantine/notifications';
 import { normalizeCanopyPath } from '../canopy-path.js';
 import { useApiClient } from '../context/index.js';
 import { resolveMessageOrigin } from '../preview-bridge.js';
+import { isSamePreviewPath } from '../preview-path.js';
 import { commentsKey, fetchComments, useCommentsData } from './useCommentsData.js';
 /**
  * Custom hook for managing the comment system.
@@ -112,6 +113,16 @@ export function useCommentSystem(options) {
     }, [activeCommentContext, options.selectedPath, options.branchName]);
     // Listen for field focus messages from preview frame
     useEffect(() => {
+        // Delayed undo steps (highlight restore, focus clear). Cleanup runs them early rather than
+        // dropping them, so an entry switch never leaves a field highlighted or focused.
+        const pending = new Map();
+        const later = (undo, ms) => {
+            const id = window.setTimeout(() => {
+                pending.delete(id);
+                undo();
+            }, ms);
+            pending.set(id, undo);
+        };
         const handleFocus = (event) => {
             // Only accept messages from the preview's origin (same-origin when previewSrc is
             // relative). Origin-only by design: this hook has no handle on the preview iframe
@@ -121,8 +132,11 @@ export function useCommentSystem(options) {
             const msg = event.data;
             if (msg?.type !== 'canopycms:preview:focus')
                 return;
+            const currentPath = options.currentEntry?.previewSrc ?? options.currentEntry?.path;
             if (msg.entryPath &&
-                msg.entryPath !== (options.currentEntry?.previewSrc ?? options.currentEntry?.path))
+                (typeof msg.entryPath !== 'string' ||
+                    currentPath === undefined ||
+                    !isSamePreviewPath(msg.entryPath, currentPath)))
                 return;
             const normalizedPath = msg.fieldPath ? normalizeCanopyPath(msg.fieldPath) : undefined;
             const target = normalizedPath
@@ -132,21 +146,26 @@ export function useCommentSystem(options) {
                 target.scrollIntoView({ behavior: 'smooth', block: 'center' });
                 const previous = target.style.boxShadow;
                 target.style.boxShadow = '0 0 0 3px rgba(79, 70, 229, 0.35)';
-                window.setTimeout(() => {
+                later(() => {
                     target.style.boxShadow = previous;
                 }, 1200);
                 // Set focused field path to trigger FieldWrapper auto-focus
                 if (normalizedPath) {
                     setFocusedFieldPath(normalizedPath);
                     // Clear after brief delay to allow FieldWrapper to detect the change
-                    window.setTimeout(() => {
-                        setFocusedFieldPath(undefined);
-                    }, 100);
+                    later(() => setFocusedFieldPath(undefined), 100);
                 }
             }
         };
         window.addEventListener('message', handleFocus);
-        return () => window.removeEventListener('message', handleFocus);
+        return () => {
+            window.removeEventListener('message', handleFocus);
+            for (const [id, undo] of pending) {
+                window.clearTimeout(id);
+                undo();
+            }
+            pending.clear();
+        };
     }, [options.currentEntry]);
     const handleJumpToField = (entryPath, canopyPath, threadId) => {
         if (entryPath !== options.selectedPath) {

package/dist/editor/hooks/useDraftManager.d.ts

@@ -8,13 +8,19 @@ export interface UseDraftManagerOptions {
     entries: EditorEntry[];
     initialValues?: Record<string, FormValue>;
     loadEntry: (entry: EditorEntry) => Promise<FormValue>;
+    /**
+     * Server read that records no OCC token (useEntryManager's `readEntryValue`),
+     * for checking restored drafts of unopened entries. Without it they stay
+     * unverified and count as dirty.
+     */
+    readEntryValue?: (entry: EditorEntry) => Promise<FormValue>;
     saveEntry: (entry: EditorEntry, value: FormValue) => Promise<FormValue>;
     /**
      * The OCC version token currently held for an entry on the branch being
      * shown (useEntryManager's `getEntryVersion`). Stamps each draft with the
      * version it was based on, and detects at save time that the token has
      * since moved on. Optional: without it no base versions are recorded and
-     * conflict detection falls back entirely to the server's 409.
+     * conflict detection falls back entirely to saveEntry's token check.
      */
     getEntryVersion?: (contentId: string) => number | undefined;
     setBusy: (busy: boolean) => void;
@@ -26,6 +32,11 @@ export interface UseDraftManagerOptions {
      */
     onSaved?: () => void;
 }
+/** The unsaved work a branch-level action would leave behind. `labels` names the entries (it may be shorter than `count`). */
+export interface UnsavedSummary {
+    count: number;
+    labels: string[];
+}
 export interface UseDraftManagerReturn {
     drafts: Record<string, FormValue>;
     setDrafts: React.Dispatch<React.SetStateAction<Record<string, FormValue>>>;
@@ -46,6 +57,10 @@ export interface UseDraftManagerReturn {
     isDirtyForEntry: (entryPath: string) => boolean;
     isSelectedDirty: () => boolean;
     isAnyDirty: () => boolean;
+    /** Resolves once restored drafts have been checked against the server (or a read failed), capped so a hung read cannot block. */
+    whenDraftsVerified: () => Promise<void>;
+    /** `whenDraftsVerified`, then the entries still counted dirty. */
+    resolveUnsaved: () => Promise<UnsavedSummary>;
     /**
      * Per-field validation errors for the selected entry, keyed by canonical
      * canopy path (e.g. `blocks[0].title`). Populated when a save is blocked by

package/dist/editor/hooks/useDraftManager.js

@@ -63,6 +63,9 @@ const parsePersistedDrafts = (raw) => {
         baseVersions[id] = null;
     return { drafts, baseVersions };
 };
+const VERIFY_CONCURRENCY = 4;
+/** How long `whenDraftsVerified` waits before answering with whatever is known. */
+const VERIFY_WAIT_CAP_MS = 3000;
 /**
  * Custom hook for managing draft state (localStorage persistence, save/discard).
  */
@@ -103,40 +106,79 @@ export function useDraftManager(options) {
     const loadedValue = currentId ? loadedValues[currentId] : undefined;
     const effectiveValue = selectedValue ?? loadedValue;
     const fieldErrors = useMemo(() => (errorState && errorState.entryId === currentId ? errorState.errors : {}), [errorState, currentId]);
-    // Number of draft entries that differ from their loaded server value.
+    // Server values read for restored drafts of unopened entries that differ from
+    // the draft. Not `loadedValues`: that map gates the entry load and OCC token.
+    const [verifiedBaselines, setVerifiedBaselines] = useState({});
+    // Ids whose verification read failed: still dirty, but no longer awaited.
+    const [unreadableIds, setUnreadableIds] = useState(() => new Set());
+    const requestedIdsRef = useRef(new Set());
+    const verifyQueueRef = useRef([]);
+    const verifyActiveRef = useRef(0);
+    const verifyWaitersRef = useRef([]);
+    const entryById = useMemo(() => new Map(options.entries.map((e) => [e.contentId, e])), [options.entries]);
+    // Empty while a branch switch loads, so only a non-empty list can say an entry is gone.
+    const entriesKnown = options.entries.length > 0;
+    // The draft ids that count as unsaved work:
     //
-    // Two intentional behaviors worth noting:
+    // 1. A draft with no baseline (loaded or verified value) counts as dirty: it
+    //    cannot be proven to match the server, and counting it keeps the
+    //    branch-switch guard from silently discarding restored drafts.
+    //    Verification (below) removes the ones that turn out pristine.
     //
-    // 1. A draft without a corresponding `loadedValues` entry (e.g. a localStorage-restored
-    //    draft whose entry has not been opened in this session) is counted as dirty. We
-    //    cannot prove such a draft matches server state, so we conservatively treat it
-    //    as unsaved work — this is what keeps the branch-switch guard from silently
-    //    discarding restored drafts.
+    // 2. A draft for an entry that no longer exists can never be loaded or saved,
+    //    so it is not counted. It stays in storage.
     //
-    // 2. The comparison uses `fast-deep-equal`, a value-based deep equality
-    //    check -- not property-order sensitive the way `JSON.stringify`
-    //    comparison was. A rehydrated draft whose keys were serialized in a
-    //    different order than the server-loaded object no longer shows as
-    //    dirty when the values are semantically identical.
-    const modifiedCount = useMemo(() => Object.keys(drafts).filter((id) => !loadedValues[id] || !equal(drafts[id], loadedValues[id]))
-        .length, [drafts, loadedValues]);
-    const editedFiles = useMemo(() => {
-        const draftIds = Object.keys(drafts);
-        if (draftIds.length === 0)
-            return [];
-        return draftIds
-            .map((id) => {
-            const entry = options.entries.find((e) => e.contentId === id);
-            return entry ? { path: entry.path, label: entry.label } : null;
-        })
-            .filter((x) => x !== null);
-    }, [drafts, options.entries]);
+    // 3. The comparison is `fast-deep-equal`, so key insertion order of a
+    //    rehydrated draft does not make it dirty.
+    const dirtyIds = useMemo(() => Object.keys(drafts).filter((id) => {
+        if (entriesKnown && !entryById.has(id))
+            return false;
+        const baseline = loadedValues[id] ?? verifiedBaselines[id];
+        return baseline === undefined || !equal(drafts[id], baseline);
+    }), [drafts, loadedValues, verifiedBaselines, entriesKnown, entryById]);
+    const modifiedCount = dirtyIds.length;
+    const editedFiles = useMemo(() => dirtyIds
+        .map((id) => {
+        const entry = entryById.get(id);
+        return entry ? { path: entry.path, label: entry.label } : null;
+    })
+        .filter((x) => x !== null), [dirtyIds, entryById]);
+    // Draft ids verification can still settle.
+    const unresolvedIds = useMemo(() => options.readEntryValue && entriesKnown
+        ? Object.keys(drafts).filter((id) => entryById.has(id) &&
+            loadedValues[id] === undefined &&
+            verifiedBaselines[id] === undefined &&
+            !unreadableIds.has(id))
+        : [], [
+        drafts,
+        loadedValues,
+        verifiedBaselines,
+        unreadableIds,
+        entriesKnown,
+        entryById,
+        options.readEntryValue,
+    ]);
+    // Async callbacks outlive the render that created them; these give them current values.
+    const latestRef = useRef({ drafts, loadedValues, unresolvedCount: 0, modifiedCount, editedFiles });
+    latestRef.current = {
+        drafts,
+        loadedValues,
+        unresolvedCount: unresolvedIds.length,
+        modifiedCount,
+        editedFiles,
+    };
+    const latestOptionsRef = useRef(options);
+    latestOptionsRef.current = options;
     // Clear drafts when branch changes (before localStorage restore)
     const prevBranchRef = useRef(options.branchName);
     useEffect(() => {
         if (prevBranchRef.current && prevBranchRef.current !== options.branchName) {
             setDrafts({});
             setLoadedValues({});
+            setVerifiedBaselines({});
+            setUnreadableIds(new Set());
+            requestedIdsRef.current = new Set();
+            verifyQueueRef.current = [];
             // Base versions are file mtimes, i.e. inherently per-branch -- carrying
             // them across a switch would compare one branch's version against
             // another's.
@@ -261,6 +303,102 @@ export function useDraftManager(options) {
             console.warn('Failed to persist drafts', err);
         }
     }, [drafts, storageKey]);
+    // A draft equal to its entry's loaded value is not an edit. Drops it so it
+    // neither counts as dirty nor lingers in storage.
+    useEffect(() => {
+        const redundant = Object.keys(drafts).filter((id) => loadedValues[id] !== undefined && equal(drafts[id], loadedValues[id]));
+        if (redundant.length === 0)
+            return;
+        setDrafts((prev) => {
+            const next = { ...prev };
+            let changed = false;
+            for (const id of redundant) {
+                if (id in next && equal(next[id], loadedValues[id])) {
+                    delete next[id];
+                    changed = true;
+                }
+            }
+            return changed ? next : prev;
+        });
+    }, [drafts, loadedValues]);
+    // Checks one restored draft against the server. The branch is re-read at
+    // settle time: a switch mid-read makes the result another branch's value.
+    const verifyDraft = async (job) => {
+        const id = job.entry.contentId;
+        const read = latestOptionsRef.current.readEntryValue;
+        if (!read)
+            return;
+        try {
+            const server = await read(job.entry);
+            if (latestOptionsRef.current.branchName !== job.branch)
+                return;
+            const { drafts: latestDrafts, loadedValues: latestLoaded } = latestRef.current;
+            // Gone, or the entry's own load has taken over as the baseline.
+            if (latestDrafts[id] === undefined || latestLoaded[id] !== undefined)
+                return;
+            if (equal(latestDrafts[id], server)) {
+                setDrafts((prev) => {
+                    if (!(id in prev) || !equal(prev[id], server))
+                        return prev;
+                    const next = { ...prev };
+                    delete next[id];
+                    return next;
+                });
+            }
+            else {
+                setVerifiedBaselines((prev) => ({ ...prev, [id]: server }));
+            }
+        }
+        catch {
+            // Stays unverified, so the draft keeps counting as dirty.
+            if (latestOptionsRef.current.branchName !== job.branch)
+                return;
+            setUnreadableIds((prev) => new Set(prev).add(id));
+        }
+    };
+    const pumpVerification = () => {
+        while (verifyActiveRef.current < VERIFY_CONCURRENCY && verifyQueueRef.current.length > 0) {
+            const job = verifyQueueRef.current.shift();
+            if (!job)
+                break;
+            verifyActiveRef.current++;
+            void verifyDraft(job).finally(() => {
+                verifyActiveRef.current--;
+                pumpVerification();
+            });
+        }
+    };
+    // Once per branch session, reads the server value of every restored draft
+    // whose entry has not loaded. The selected entry is left to its own load,
+    // which fills `loadedValues` and lets the effect above drop a pristine draft.
+    useEffect(() => {
+        if (!options.readEntryValue || !entriesKnown)
+            return;
+        // `drafts` lags a branch switch by a render (see draftsStorageKeyRef); reading
+        // the old branch's drafts under the new branch's name would be wrong.
+        if (draftsStorageKeyRef.current !== storageKey)
+            return;
+        const todo = unresolvedIds.filter((id) => id !== currentId && !requestedIdsRef.current.has(id));
+        if (todo.length === 0)
+            return;
+        for (const id of todo) {
+            requestedIdsRef.current.add(id);
+            const entry = entryById.get(id);
+            if (entry)
+                verifyQueueRef.current.push({ entry, branch: options.branchName });
+        }
+        pumpVerification();
+        // pumpVerification/verifyDraft only touch refs and stable setters.
+    }, [unresolvedIds, currentId, storageKey]);
+    // Wakes `whenDraftsVerified` callers once nothing is left to settle.
+    useEffect(() => {
+        if (unresolvedIds.length > 0)
+            return;
+        const waiters = verifyWaitersRef.current;
+        verifyWaitersRef.current = [];
+        for (const wake of waiters)
+            wake();
+    }, [unresolvedIds]);
     // Recomputes field errors as the user edits, or as the selected entry's
     // schema/format changes while it stays open, so each error clears when its
     // field is fixed or no longer required. Errors for a different entry are
@@ -316,7 +454,8 @@ export function useDraftManager(options) {
             return 'ok';
         const currentVersion = options.getEntryVersion?.(currentId);
         // No server version known for this entry at all -- nothing to compare
-        // against, so this check has no opinion (the server's 409 still applies).
+        // against, so this check has no opinion: saveEntry refuses a save without
+        // a token, and the server refuses a version-less update.
         if (currentVersion === undefined)
             return 'ok';
         const base = draftBaseVersionsRef.current[currentId];
@@ -406,9 +545,8 @@ export function useDraftManager(options) {
             // to become `saved` below, so removing the draft key is a no-op for
             // the rendered value while fixing the "phantom dirty" bug: a draft
             // that lingers forever is what made every fresh page load show Save
-            // enabled with zero real edits (see modifiedCount's doc comment above
-            // — a draft without a matching loadedValues entry is conservatively
-            // treated as dirty).
+            // enabled with zero real edits (see `dirtyIds` above: a draft with no
+            // baseline is conservatively treated as dirty).
             setDrafts((prev) => {
                 if (!(currentId in prev))
                     return prev;
@@ -627,7 +765,8 @@ export function useDraftManager(options) {
         const id = entry.contentId;
         if (!drafts[id])
             return false;
-        return !loadedValues[id] || !equal(drafts[id], loadedValues[id]);
+        const baseline = loadedValues[id] ?? verifiedBaselines[id];
+        return baseline === undefined || !equal(drafts[id], baseline);
     };
     const isSelectedDirty = () => {
         if (!currentId)
@@ -636,13 +775,29 @@ export function useDraftManager(options) {
             return false;
         return !loadedValues[currentId] || !equal(drafts[currentId], loadedValues[currentId]);
     };
-    // Returns true if ANY draft entry differs from its loaded value.
-    //
-    // Used for branch-switch guards so unsaved work in non-selected entries is not
-    // silently discarded. Derived from `modifiedCount`, so its semantics note
-    // above also applies: localStorage-restored drafts without a loaded value
-    // count as dirty.
+    // True if ANY counted draft is dirty (see `dirtyIds`). Used for branch-level
+    // guards so unsaved work in non-selected entries is not silently discarded.
     const isAnyDirty = () => modifiedCount > 0;
+    const whenDraftsVerified = () => {
+        if (latestRef.current.unresolvedCount === 0)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const wake = () => {
+                clearTimeout(timer);
+                resolve();
+            };
+            const timer = setTimeout(() => {
+                verifyWaitersRef.current = verifyWaitersRef.current.filter((w) => w !== wake);
+                resolve();
+            }, VERIFY_WAIT_CAP_MS);
+            verifyWaitersRef.current.push(wake);
+        });
+    };
+    const resolveUnsaved = async () => {
+        await whenDraftsVerified();
+        const { modifiedCount: count, editedFiles: files } = latestRef.current;
+        return { count, labels: files.map((f) => f.label) };
+    };
     return {
         drafts,
         setDrafts,
@@ -660,6 +815,8 @@ export function useDraftManager(options) {
         isDirtyForEntry,
         isSelectedDirty,
         isAnyDirty,
+        whenDraftsVerified,
+        resolveUnsaved,
         fieldErrors,
     };
 }

package/dist/editor/hooks/useEntriesData.js

@@ -40,7 +40,7 @@ export async function listAllEntries(apiClient, branch) {
             ...(cursor !== undefined ? { cursor } : {}),
         });
         if (!result.ok || !result.data)
-            throw new Error(`Refresh failed: ${result.status}`);
+            throw new Error(`Refresh failed: ${result.status}${result.error ? ` — ${result.error}` : ''}`);
         const data = result.data;
         for (const entry of data.entries)
             byPath.set(entry.logicalPath, entry);
@@ -60,7 +60,7 @@ export async function fetchEntriesAndSchema(apiClient, branch, params) {
     // Fetch schema from schema API
     const schemaResult = await apiClient.schema.get({ branch });
     if (!schemaResult.ok || !schemaResult.data) {
-        throw new Error(`Schema fetch failed: ${schemaResult.status}`);
+        throw new Error(`Schema fetch failed: ${schemaResult.status}${schemaResult.error ? ` — ${schemaResult.error}` : ''}`);
     }
     // Hydrate wire flatSchema: resolve schemaRef -> schema from entrySchemas dict
     const { entrySchemas } = schemaResult.data;
@@ -85,7 +85,7 @@ export async function fetchEntriesAndSchema(apiClient, branch, params) {
             entries: allEntries,
             pagination: { hasMore: false, limit: ENTRIES_PAGE_LIMIT },
         },
-        resolvePreviewSrc: (entry) => params.resolvePreviewSrc(entry) ?? '',
+        resolvePreviewSrc: params.resolvePreviewSrc,
         flatSchema: hydratedFlatSchema,
     });
     return { collections, entries, availableSchemas: Object.keys(entrySchemas) };

package/dist/editor/hooks/useEntryManager.d.ts

@@ -20,7 +20,6 @@ export interface UseEntryManagerOptions {
     initialSelectedId?: string;
     branchName: string;
     collections?: EditorCollection[];
-    previewBaseByCollection?: Record<string, string>;
     resolvePreviewSrc: (entry: Partial<EditorEntry>) => string | undefined;
     setBusy: (busy: boolean) => void;
 }
@@ -46,6 +45,8 @@ export interface UseEntryManagerReturn {
     handleCreateEntry: (collectionPath: LogicalPath, entryTypeName?: string) => Promise<void>;
     renameEntry: (path: string, newSlug: string) => Promise<void>;
     loadEntry: (entry: EditorEntry) => Promise<FormValue>;
+    /** Reads an entry's server value without recording the OCC token that `loadEntry` records. */
+    readEntryValue: (entry: EditorEntry) => Promise<FormValue>;
     saveEntry: (entry: EditorEntry, value: FormValue) => Promise<FormValue>;
     /**
      * The OCC version token currently held for `contentId` ON THE BRANCH BEING

package/dist/editor/hooks/useEntryManager.js

@@ -50,11 +50,9 @@ export function useEntryManager(options) {
     // case -- any first visit to a branch, for the whole duration of its fetch),
     // or a stale SWR slot. The editor then auto-selected one of those stale
     // entries (see the selection effect below), and a save could file its OCC
-    // token under one contentId and look it up under another, silently skipping
-    // conflict detection -- `content-store.ts` only compares mtimes when
-    // `expectedVersion !== undefined`, so the write became a blind overwrite.
-    // Deriving from a stamped record fixes that structurally instead of relying
-    // on every code path remembering to clear.
+    // token under one contentId and look it up under another. Deriving from a
+    // stamped record fixes that structurally instead of relying on every code
+    // path remembering to clear.
     const [view, setView] = useState(() => ({
         branch: options.branchName,
         entries: options.initialEntries,
@@ -86,6 +84,9 @@ export function useEntryManager(options) {
     // branch can repopulate the map after the branch-change clear() below and
     // poison the next save with the old branch's mtime — a deterministic 409
     // ("modified by another editor") on save-after-switch, proven by e2e trace.
+    // The contentId half matches how useDraftManager keys drafts and loaded
+    // values, so a form value and its token always belong to the same file even
+    // when a path is deleted and recreated; it also survives a rename.
     const entryVersionsRef = useRef(new Map());
     const versionKey = (branch, contentId) => `${branch}:${contentId}`;
     // PER-BRANCH monotonic tokens guarding every commit of the fetched
@@ -177,14 +178,11 @@ export function useEntryManager(options) {
             .filter((e) => e.collectionPath === createModalCollection.path && e.slug)
             .map((e) => e.slug));
     }, [entriesState, createModalCollection]);
-    const loadEntry = async (entry) => {
+    // The read both entry paths share; returns the raw payload so `loadEntry` can take its version.
+    const readEntryPayload = async (entry, requestBranch) => {
         if (!entry.collectionPath) {
             throw new Error('Entry missing collectionPath');
         }
-        // Pin the branch this request targets: if the user switches branches
-        // while the read is in flight, the token must be recorded under the
-        // branch that actually served it, not the current one.
-        const requestBranch = options.branchName;
         // Build path from collectionPath and slug (if it's a collection entry)
         const path = entry.slug ? `${entry.collectionPath}/${entry.slug}` : entry.collectionPath;
         const result = await apiClient.content.read({
@@ -192,13 +190,24 @@ export function useEntryManager(options) {
             path,
         });
         if (!result.ok)
-            throw new Error(`Load failed: ${result.status}`);
+            throw new Error(`Load failed: ${result.status}${result.error ? ` — ${result.error}` : ''}`);
+        return result.data;
+    };
+    const loadEntry = async (entry) => {
+        // Pin the branch this request targets: if the user switches branches
+        // while the read is in flight, the token must be recorded under the
+        // branch that actually served it, not the current one.
+        const requestBranch = options.branchName;
+        const data = await readEntryPayload(entry, requestBranch);
         // Capture OCC version token for next save
-        if (entry.contentId && typeof result.data?.version === 'number') {
-            entryVersionsRef.current.set(versionKey(requestBranch, entry.contentId), result.data.version);
+        if (entry.contentId && typeof data?.version === 'number') {
+            entryVersionsRef.current.set(versionKey(requestBranch, entry.contentId), data.version);
         }
-        return normalizeContentPayload(result.data);
+        return normalizeContentPayload(data);
     };
+    // The same read as `loadEntry`, minus the token capture. A value read this way can be
+    // compared against but never saved against: only `loadEntry` makes an entry saveable.
+    const readEntryValue = async (entry) => normalizeContentPayload(await readEntryPayload(entry, options.branchName));
     // Read side of the same branch-qualified token map `saveEntry` writes/reads.
     // Deliberately keyed off the CURRENT branch (not a pinned one): callers use
     // it to reason about the entry they are looking at right now.
@@ -220,18 +229,23 @@ export function useEntryManager(options) {
         };
         if (entry.entryType)
             writeParams.entryType = entry.entryType;
-        const expectedVersion = entry.contentId
-            ? entryVersionsRef.current.get(versionKey(requestBranch, entry.contentId))
-            : undefined;
+        const expectedVersion = entryVersionsRef.current.get(versionKey(requestBranch, entry.contentId));
+        // Every entry saved here already exists (creates go through handleCreateModalSubmit), so
+        // no token means this entry was never successfully read on this branch and nothing could check the save
+        // against other editors' work. Refused as a conflict; the server refuses it too.
+        if (expectedVersion === undefined) {
+            throw new SaveApiError(409, 'This entry has not been loaded from the server, so the save cannot be checked ' +
+                "against other editors' changes. Reload it and try again.");
+        }
         const writeBody = {
             ...payload,
-            ...(expectedVersion !== undefined ? { expectedVersion } : {}),
+            expectedVersion,
         };
         const result = await apiClient.content.write(writeParams, writeBody);
         if (!result.ok)
             throw new SaveApiError(result.status, result.error, result.fieldErrors);
         // Update stored version token from write response
-        if (entry.contentId && typeof result.data?.version === 'number') {
+        if (typeof result.data?.version === 'number') {
             entryVersionsRef.current.set(versionKey(requestBranch, entry.contentId), result.data.version);
         }
         // Warning-level issues from the adopter's validateEntry hook: saved, but surface them
@@ -558,6 +572,7 @@ export function useEntryManager(options) {
         handleCreateEntry,
         renameEntry,
         loadEntry,
+        readEntryValue,
         saveEntry,
         getEntryVersion,
         collectionByPath: collectionByPath,

package/dist/editor/media/AssetCard.d.ts

@@ -2,7 +2,7 @@ import React from 'react';
 import type { AssetRecord } from '../../api/index.js';
 export interface AssetCardProps {
     asset: AssetRecord;
-    /** `media.publicBaseUrl` - see AssetContext. */
+    /** `useAssetContext().baseUrl`, the authenticated raw route - see AssetContext. */
     baseUrl?: string;
     /** Present in picker mode - clicking the card selects the asset. */
     onSelect?: (asset: AssetRecord) => void;

package/dist/editor/media/crop-math.d.ts

@@ -16,10 +16,9 @@ export interface CropAreaPercent {
 }
 /**
  * Convert react-easy-crop's `onCropComplete(croppedArea, croppedAreaPixels)`
- * percentage area into a normalized `CropRect`, rounded to 4 decimals and
- * clamped to fit within bounds. Rounding can push `x+w`/`y+h` a hair over 1
- * (e.g. x=0.6667, w=0.3334 -> 1.0001) - shrink the extent to the remaining
- * space rather than reject a rect that was valid before rounding.
+ * percentage area into a normalized `CropRect`, clamped to [0,1] and then
+ * rounded by `roundCropRect` — the same rounding the transform URL's canonical
+ * form applies, so the stored crop is already canonical.
  *
  * Returns `null` if the input can't be coerced into a valid rect (e.g. a
  * zero-area selection).