canopycms 0.0.68-int.98 → 0.1.0

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

@@ -4,12 +4,19 @@ export interface UseReferenceResolutionOptions {
     value: FormValue;
     fields: EntrySchema;
     branch: string;
-    onResolvedValueChange?: (resolved: FormValue) => void;
-    onLoadingStateChange?: (loadingState: FormValue) => void;
+    /** Identifies the open entry; when it changes every cached target is fetched again. */
+    entryKey?: string;
 }
 export interface UseReferenceResolutionResult {
+    /** The draft with every reference replaced by its target, or `null` until it has one. */
     resolvedValue: FormValue;
+    /** `true` at each reference position still resolving; see `applyReferenceCache`. */
     loadingState: FormValue;
 }
-export declare function useReferenceResolution({ value, fields, branch, onResolvedValueChange, onLoadingStateChange, }: UseReferenceResolutionOptions): UseReferenceResolutionResult;
+/**
+ * The draft as live preview shows it. Computed during render from the cache, so the first value
+ * for a new entry or edit already has no bare ids; a debounced effect then fetches the ids the
+ * cache lacks, in batched requests, and re-renders when they arrive.
+ */
+export declare function useReferenceResolution({ value, fields, branch, entryKey, }: UseReferenceResolutionOptions): UseReferenceResolutionResult;
 export {};

package/dist/editor/hooks/useReferenceResolution.js

@@ -1,189 +1,46 @@
 import { useEffect, useMemo, useRef, useState } from 'react';
-import { resolveChangedReferences } from '../client-reference-resolver.js';
-import { flattenGroupFields } from '../../utils/flatten-group-fields.js';
+import { applyReferenceCache, expireReferences, fetchReferences, idsToFetch, storeReferences, } from '../client-reference-resolver.js';
 import { useOptionalApiClient } from '../context/index.js';
-export function useReferenceResolution({ value, fields, branch, onResolvedValueChange, onLoadingStateChange, }) {
-    // Context-provided client (configured with the deployment's basePath) when this hook is
-    // rendered inside an ApiClientProvider -- which it always is in the real Editor tree. `null`
-    // outside one (e.g. FormRenderer.stories.tsx, or this hook's own unwrapped unit tests);
-    // resolveChangedReferences falls back to a default-configured client in that case.
+/**
+ * The draft as live preview shows it. Computed during render from the cache, so the first value
+ * for a new entry or edit already has no bare ids; a debounced effect then fetches the ids the
+ * cache lacks, in batched requests, and re-renders when they arrive.
+ */
+export function useReferenceResolution({ value, fields, branch, entryKey, }) {
+    // The context client carries the deployment's basePath. `null` outside an ApiClientProvider
+    // (this hook's own unit tests); fetchReferences then falls back to a default client.
     const apiClient = useOptionalApiClient();
-    const resolvedCache = useRef(new Map());
-    const prevValueRef = useRef({}); // Track previous value for change detection
-    const lastNotifiedValueRef = useRef(''); // Track last notified value to prevent infinite loops
-    const [resolutionTrigger, setResolutionTrigger] = useState(0); // Trigger to force useMemo re-computation
-    // Monotonic token identifying the current debounced-resolve attempt.
-    // Clearing the setTimeout in the effect cleanup only cancels a resolve
-    // that HASN'T fired yet; once the 300ms elapses and the async callback
-    // below starts awaiting `resolveChangedReferences`, clearTimeout can no
-    // longer stop it. The generation check after that await catches the case
-    // clearTimeout can't: a newer value/branch superseding this attempt, or
-    // the component unmounting, while the network call was in flight.
-    const resolveGenerationRef = useRef(0);
-    const referenceFieldNames = useMemo(() => {
-        const names = new Set();
-        for (const field of flattenGroupFields(fields)) {
-            if (field.type === 'reference') {
-                names.add(field.name);
-            }
-        }
-        return names;
-    }, [fields]);
-    /**
-     * PHASE 1: SYNCHRONOUS RESOLUTION
-     *
-     * Compute resolved value by applying cached reference data to form value.
-     * This runs synchronously during render (useMemo), so there are no async gaps.
-     *
-     * For each reference field:
-     * - If ID is in cache: substitute full object
-     * - If ID not in cache: keep the ID (loading state)
-     *
-     * Dependencies include resolutionTrigger, which is incremented when cache updates,
-     * forcing this to re-run and pick up newly-resolved data.
-     */
-    const resolvedValue = useMemo(() => {
-        const result = { ...value };
-        for (const fieldName of referenceFieldNames) {
-            const fieldValue = value[fieldName];
-            if (fieldValue) {
-                if (Array.isArray(fieldValue)) {
-                    result[fieldName] = fieldValue.map((id) => {
-                        if (typeof id === 'string') {
-                            const cached = resolvedCache.current.get(`${branch}:${id}`);
-                            return cached || null;
-                        }
-                        return id;
-                    });
-                }
-                else if (typeof fieldValue === 'string') {
-                    const cached = resolvedCache.current.get(`${branch}:${fieldValue}`);
-                    result[fieldName] = cached || null;
-                }
-            }
-        }
-        return result;
-    }, [value, branch, resolutionTrigger, referenceFieldNames]);
-    /**
-     * Compute loading state that mirrors the data structure.
-     * For each reference field, track if it's currently loading (not in cache).
-     */
-    const loadingState = useMemo(() => {
-        const result = {};
-        for (const fieldName of referenceFieldNames) {
-            const fieldValue = value[fieldName];
-            if (fieldValue) {
-                if (Array.isArray(fieldValue)) {
-                    result[fieldName] = fieldValue.map((id) => {
-                        if (typeof id === 'string') {
-                            return !resolvedCache.current.has(`${branch}:${id}`);
-                        }
-                        return false;
-                    });
-                }
-                else if (typeof fieldValue === 'string') {
-                    result[fieldName] = !resolvedCache.current.has(`${branch}:${fieldValue}`);
-                }
-                else {
-                    result[fieldName] = false;
-                }
-            }
-            else {
-                result[fieldName] = false;
-            }
-        }
-        return result;
-    }, [value, branch, resolutionTrigger, referenceFieldNames]);
-    /**
-     * PHASE 2: BACKGROUND ASYNC RESOLUTION
-     *
-     * Find reference IDs that aren't in cache yet and fetch them from the API.
-     */
+    // One map per branch, so a request for a branch left behind stores into an orphaned map.
+    const cacheRef = useRef(new Map());
+    // The cache is a ref, so a fetch that fills it bumps this to recompute the memo below.
+    const [cacheVersion, setCacheVersion] = useState(0);
+    const { resolvedValue, loadingState } = useMemo(() => applyReferenceCache(fields, value, branch, cacheRef.current), [fields, value, branch, cacheVersion]);
+    // These two are declared before the fetch effect, so it sees their result in the same commit.
     useEffect(() => {
-        const uncachedIds = new Set();
-        for (const fieldName of referenceFieldNames) {
-            const fieldValue = value[fieldName];
-            if (fieldValue) {
-                const ids = Array.isArray(fieldValue) ? fieldValue : [fieldValue];
-                for (const id of ids) {
-                    if (typeof id === 'string' && !resolvedCache.current.has(`${branch}:${id}`)) {
-                        uncachedIds.add(id);
-                    }
-                }
-            }
-        }
-        if (uncachedIds.size === 0) {
-            prevValueRef.current = value;
+        cacheRef.current = new Map();
+        setCacheVersion((prev) => prev + 1);
+    }, [branch]);
+    useEffect(() => {
+        expireReferences(cacheRef.current);
+    }, [entryKey]);
+    // Asks for all the cache lacks, even ids still in flight; the next edit retries a failure.
+    useEffect(() => {
+        const cache = cacheRef.current;
+        const ids = idsToFetch(fields, value, branch, cache, Date.now());
+        if (ids.length === 0)
             return;
-        }
-        // Claim a generation for this attempt before scheduling the debounce, so
-        // the check below always compares against the token captured at the
-        // moment THIS attempt was scheduled -- not whatever the ref happens to
-        // hold when the callback resumes after its await.
-        const generation = ++resolveGenerationRef.current;
         const timeout = setTimeout(async () => {
             try {
-                const updates = await resolveChangedReferences(prevValueRef.current, value, fields, branch, resolvedCache.current, apiClient ?? undefined);
-                // A newer value/branch superseded this attempt, or the component
-                // unmounted, while the request above was in flight -- discard.
-                if (generation !== resolveGenerationRef.current)
-                    return;
-                for (const [fieldName, resolvedFieldValue] of Object.entries(updates)) {
-                    if (Array.isArray(resolvedFieldValue)) {
-                        resolvedFieldValue.forEach((obj, idx) => {
-                            const fieldValue = value[fieldName];
-                            if (Array.isArray(fieldValue)) {
-                                const id = fieldValue[idx];
-                                if (typeof obj === 'object' && obj !== null && typeof id === 'string') {
-                                    resolvedCache.current.set(`${branch}:${id}`, obj);
-                                }
-                            }
-                        });
-                    }
-                    else if (typeof resolvedFieldValue === 'object' && resolvedFieldValue !== null) {
-                        const id = value[fieldName];
-                        if (typeof id === 'string') {
-                            resolvedCache.current.set(`${branch}:${id}`, resolvedFieldValue);
-                        }
-                    }
-                }
-                setResolutionTrigger((prev) => prev + 1);
-                prevValueRef.current = value;
+                const found = await fetchReferences(ids, branch, apiClient ?? undefined);
+                // Keyed by branch and id, a result stays valid however the draft changed meanwhile.
+                storeReferences(cache, branch, found, Date.now());
+                setCacheVersion((prev) => prev + 1);
             }
             catch (error) {
                 console.error('Reference resolution failed:', error);
             }
-        }, 300); // 300ms debounce
-        return () => {
-            clearTimeout(timeout);
-            // Invalidate this attempt's generation on cleanup too, not just when a
-            // newer effect run claims the next one: cleanup is what fires on
-            // unmount, where there IS no next run to bump the counter otherwise.
-            ++resolveGenerationRef.current;
-        };
-    }, [value, fields, branch, referenceFieldNames, apiClient]);
-    useEffect(() => {
-        resolvedCache.current.clear();
-        setResolutionTrigger((prev) => prev + 1);
-    }, [branch]);
-    // Notify parent of resolved value changes (with infinite loop prevention)
-    useEffect(() => {
-        const serialized = JSON.stringify(resolvedValue);
-        if (serialized !== lastNotifiedValueRef.current) {
-            lastNotifiedValueRef.current = serialized;
-            onResolvedValueChange?.(resolvedValue);
-        }
-    }, [resolvedValue, onResolvedValueChange]);
-    const lastNotifiedLoadingRef = useRef('');
-    useEffect(() => {
-        const serialized = JSON.stringify(loadingState);
-        if (serialized !== lastNotifiedLoadingRef.current) {
-            lastNotifiedLoadingRef.current = serialized;
-            onLoadingStateChange?.(loadingState);
-        }
-    }, [loadingState, onLoadingStateChange]);
-    return {
-        resolvedValue,
-        loadingState,
-    };
+        }, 300);
+        return () => clearTimeout(timeout);
+    }, [value, fields, branch, entryKey, apiClient]);
+    return { resolvedValue, loadingState };
 }

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

@@ -1,4 +1,5 @@
 import type { CreateCollectionInput, UpdateCollectionInput, CreateEntryTypeInput, UpdateEntryTypeInput } from '../../api/index.js';
+import type { EntryReferencedBy } from '../../api/entries.js';
 import type { LogicalPath, ContentId } from '../../paths/types.js';
 export interface UseSchemaManagerOptions {
     branchName: string;
@@ -15,9 +16,28 @@ export interface UseSchemaManagerOptions {
  */
 export type SchemaOpResult = {
     ok: true;
-} | {
+} | SchemaOpFailure;
+/**
+ * `unanswered`: the write timed out or got a gateway's 5xx page, so it may have landed
+ * (`editor/unanswered.ts`); `onSchemaChange` has been called so the content tree shows which.
+ */
+type SchemaOpFailure = {
+    ok: false;
+    error: string;
+    unanswered?: true;
+};
+/** Takes down a collection create's or details save's unknown-outcome toast, once it landed. */
+export declare const hideCollectionOutcomeUnknown: () => void;
+/** @internal Exported for tests. */
+export declare const schemaChangeOutcomeUnknown: (action: string, check: string) => string;
+/**
+ * {@link SchemaOpResult}, or a refusal because other entries reference the one being deleted.
+ * That refusal shows no toast: the caller asks the user, then retries with `confirmReferenced`.
+ */
+type DeleteEntryResult = SchemaOpResult | {
     ok: false;
     error: string;
+    referencedBy: EntryReferencedBy;
 };
 /** Same shape as {@link SchemaOpResult}, plus a payload on success. */
 type CreateCollectionResult = {
@@ -26,10 +46,7 @@ type CreateCollectionResult = {
         collectionPath: LogicalPath;
         contentId: ContentId;
     };
-} | {
-    ok: false;
-    error: string;
-};
+} | SchemaOpFailure;
 export interface UseSchemaManagerReturn {
     createCollection: (input: CreateCollectionInput) => Promise<CreateCollectionResult>;
     updateCollection: (collectionPath: LogicalPath, updates: UpdateCollectionInput) => Promise<SchemaOpResult>;
@@ -38,7 +55,9 @@ export interface UseSchemaManagerReturn {
     updateEntryType: (collectionPath: LogicalPath, entryTypeName: string, updates: UpdateEntryTypeInput) => Promise<SchemaOpResult>;
     removeEntryType: (collectionPath: LogicalPath, entryTypeName: string) => Promise<SchemaOpResult>;
     updateOrder: (collectionPath: LogicalPath, order: string[]) => Promise<SchemaOpResult>;
-    deleteEntry: (entryPath: LogicalPath) => Promise<SchemaOpResult>;
+    deleteEntry: (entryPath: LogicalPath, options?: {
+        confirmReferenced?: boolean;
+    }) => Promise<DeleteEntryResult>;
     isLoading: boolean;
 }
 /**

package/dist/editor/hooks/useSchemaManager.js

@@ -2,6 +2,17 @@ import { useState, useCallback } from 'react';
 import { notifications } from '@mantine/notifications';
 import { useApiClient } from '../context/index.js';
 import { getErrorMessage } from '../../utils/error.js';
+import { isGatewayFailure, isUnanswered, UnansweredError } from '../unanswered.js';
+const SCHEMA_OUTCOME_UNKNOWN_TOAST_ID = 'canopy-schema-outcome-unknown';
+// A collection create or details save has its own, so settling one leaves another write's up.
+const COLLECTION_OUTCOME_UNKNOWN_TOAST_ID = 'canopy-collection-outcome-unknown';
+const CHECK_CONTENT_PANEL = 'Check the "Content" panel';
+/** Takes down a collection create's or details save's unknown-outcome toast, once it landed. */
+export const hideCollectionOutcomeUnknown = () => {
+    notifications.hide(COLLECTION_OUTCOME_UNKNOWN_TOAST_ID);
+};
+/** @internal Exported for tests. */
+export const schemaChangeOutcomeUnknown = (action, check) => `${action} may have gone through even though the server didn't answer. ${check} before trying again.`;
 /**
  * Hook for managing schema operations (collections, entry types, ordering).
  *
@@ -10,23 +21,50 @@ import { getErrorMessage } from '../../utils/error.js';
 export function useSchemaManager(options) {
     const apiClient = useApiClient();
     const [isLoading, setIsLoading] = useState(false);
-    // Toasts on every failure (relied on by fire-and-forget callers that ignore
-    // the returned result) and returns the underlying message so callers that
-    // do inspect the result can also surface it inline (e.g. in a modal).
-    const handleError = useCallback((message, error) => {
+    // Collection, order and entry operations toast each failure that reaches here
+    // (relied on by fire-and-forget callers that ignore the returned result).
+    // Entry-type operations pass `toast: false`: their only caller,
+    // CollectionEditor, shows each result inline. Both return the underlying
+    // message for callers that surface it themselves.
+    const handleError = useCallback((message, error, { toast = true } = {}) => {
         console.error(message, error);
         const errorMessage = getErrorMessage(error);
-        notifications.show({
-            title: 'Error',
-            message: `${message}: ${errorMessage}`,
-            color: 'red',
-        });
+        if (toast) {
+            notifications.show({
+                title: 'Error',
+                message: `${message}: ${errorMessage}`,
+                color: 'red',
+            });
+        }
         return errorMessage;
     }, []);
+    /**
+     * The failure result for a write. An unanswered one may have landed, so the content tree
+     * reloads, and its toast (only with `unknown`) says to check rather than that it failed.
+     */
+    const fail = useCallback((error, message, { toast = true, unknown, unknownId = SCHEMA_OUTCOME_UNKNOWN_TOAST_ID, } = {}) => {
+        if (!isUnanswered(error))
+            return { ok: false, error: handleError(message, error, { toast }) };
+        console.error(message, error);
+        void Promise.resolve(options.onSchemaChange?.()).catch(console.error);
+        if (unknown) {
+            notifications.hide(unknownId);
+            notifications.show({
+                id: unknownId,
+                message: unknown,
+                color: 'yellow',
+                autoClose: false,
+                withCloseButton: true,
+            });
+        }
+        return { ok: false, error: getErrorMessage(error), unanswered: true };
+    }, [options.onSchemaChange, handleError]);
     const createCollection = useCallback(async (input) => {
         setIsLoading(true);
         try {
             const result = await apiClient.schema.createCollection({ branch: options.branchName }, input);
+            if (isGatewayFailure(result))
+                throw new UnansweredError();
             if (!result.ok || !result.data) {
                 throw new Error(result.error || 'Failed to create collection');
             }
@@ -38,16 +76,21 @@ export function useSchemaManager(options) {
             return { ok: true, data: result.data };
         }
         catch (error) {
-            return { ok: false, error: handleError('Failed to create collection', error) };
+            return fail(error, 'Failed to create collection', {
+                unknown: schemaChangeOutcomeUnknown('Creating the collection', CHECK_CONTENT_PANEL),
+                unknownId: COLLECTION_OUTCOME_UNKNOWN_TOAST_ID,
+            });
         }
         finally {
             setIsLoading(false);
         }
-    }, [apiClient, options.branchName, options.onSchemaChange, handleError]);
+    }, [apiClient, options.branchName, options.onSchemaChange, fail]);
     const updateCollection = useCallback(async (collectionPath, updates) => {
         setIsLoading(true);
         try {
             const result = await apiClient.schema.updateCollection({ branch: options.branchName, collectionPath }, updates);
+            if (isGatewayFailure(result))
+                throw new UnansweredError();
             if (!result.ok) {
                 throw new Error(result.error || 'Failed to update collection');
             }
@@ -55,16 +98,20 @@ export function useSchemaManager(options) {
                 message: 'Collection updated',
                 color: 'green',
             });
-            await options.onSchemaChange?.();
+            // The write landed, so a failed refresh is logged rather than reported as its failure.
+            await Promise.resolve(options.onSchemaChange?.()).catch(console.error);
             return { ok: true };
         }
         catch (error) {
-            return { ok: false, error: handleError('Failed to update collection', error) };
+            return fail(error, 'Failed to update collection', {
+                unknown: schemaChangeOutcomeUnknown('Saving collection details', 'Reopen the collection to check'),
+                unknownId: COLLECTION_OUTCOME_UNKNOWN_TOAST_ID,
+            });
         }
         finally {
             setIsLoading(false);
         }
-    }, [apiClient, options.branchName, options.onSchemaChange, handleError]);
+    }, [apiClient, options.branchName, options.onSchemaChange, fail]);
     const deleteCollection = useCallback(async (collectionPath) => {
         setIsLoading(true);
         try {
@@ -72,6 +119,8 @@ export function useSchemaManager(options) {
                 branch: options.branchName,
                 collectionPath,
             });
+            if (isGatewayFailure(result))
+                throw new UnansweredError();
             if (!result.ok) {
                 throw new Error(result.error || 'Failed to delete collection');
             }
@@ -83,54 +132,52 @@ export function useSchemaManager(options) {
             return { ok: true };
         }
         catch (error) {
-            return { ok: false, error: handleError('Failed to delete collection', error) };
+            return fail(error, 'Failed to delete collection', {
+                unknown: schemaChangeOutcomeUnknown('Deleting the collection', CHECK_CONTENT_PANEL),
+            });
         }
         finally {
             setIsLoading(false);
         }
-    }, [apiClient, options.branchName, options.onSchemaChange, handleError]);
+    }, [apiClient, options.branchName, options.onSchemaChange, fail]);
     const addEntryType = useCallback(async (collectionPath, entryType) => {
         setIsLoading(true);
         try {
             const result = await apiClient.schema.addEntryType({ branch: options.branchName, collectionPath }, entryType);
+            if (isGatewayFailure(result))
+                throw new UnansweredError();
             if (!result.ok) {
                 throw new Error(result.error || 'Failed to add entry type');
             }
-            notifications.show({
-                message: `Entry type "${entryType.name}" added`,
-                color: 'green',
-            });
             options.onSchemaChange?.();
             return { ok: true };
         }
         catch (error) {
-            return { ok: false, error: handleError('Failed to add entry type', error) };
+            return fail(error, 'Failed to add entry type', { toast: false });
         }
         finally {
             setIsLoading(false);
         }
-    }, [apiClient, options.branchName, options.onSchemaChange, handleError]);
+    }, [apiClient, options.branchName, options.onSchemaChange, fail]);
     const updateEntryType = useCallback(async (collectionPath, entryTypeName, updates) => {
         setIsLoading(true);
         try {
             const result = await apiClient.schema.updateEntryType({ branch: options.branchName, collectionPath, entryTypeName }, updates);
+            if (isGatewayFailure(result))
+                throw new UnansweredError();
             if (!result.ok) {
                 throw new Error(result.error || 'Failed to update entry type');
             }
-            notifications.show({
-                message: 'Entry type updated',
-                color: 'green',
-            });
             options.onSchemaChange?.();
             return { ok: true };
         }
         catch (error) {
-            return { ok: false, error: handleError('Failed to update entry type', error) };
+            return fail(error, 'Failed to update entry type', { toast: false });
         }
         finally {
             setIsLoading(false);
         }
-    }, [apiClient, options.branchName, options.onSchemaChange, handleError]);
+    }, [apiClient, options.branchName, options.onSchemaChange, fail]);
     const removeEntryType = useCallback(async (collectionPath, entryTypeName) => {
         setIsLoading(true);
         try {
@@ -139,27 +186,27 @@ export function useSchemaManager(options) {
                 collectionPath,
                 entryTypeName,
             });
+            if (isGatewayFailure(result))
+                throw new UnansweredError();
             if (!result.ok) {
                 throw new Error(result.error || 'Failed to remove entry type');
             }
-            notifications.show({
-                message: `Entry type "${entryTypeName}" removed`,
-                color: 'green',
-            });
             options.onSchemaChange?.();
             return { ok: true };
         }
         catch (error) {
-            return { ok: false, error: handleError('Failed to remove entry type', error) };
+            return fail(error, 'Failed to remove entry type', { toast: false });
         }
         finally {
             setIsLoading(false);
         }
-    }, [apiClient, options.branchName, options.onSchemaChange, handleError]);
+    }, [apiClient, options.branchName, options.onSchemaChange, fail]);
     const updateOrder = useCallback(async (collectionPath, order) => {
         setIsLoading(true);
         try {
             const result = await apiClient.schema.updateOrder({ branch: options.branchName, collectionPath }, { order });
+            if (isGatewayFailure(result))
+                throw new UnansweredError();
             if (!result.ok) {
                 throw new Error(result.error || 'Failed to update order');
             }
@@ -168,19 +215,28 @@ export function useSchemaManager(options) {
             return { ok: true };
         }
         catch (error) {
-            return { ok: false, error: handleError('Failed to update order', error) };
+            return fail(error, 'Failed to update order', {
+                unknown: schemaChangeOutcomeUnknown('Reordering entries', CHECK_CONTENT_PANEL),
+            });
         }
         finally {
             setIsLoading(false);
         }
-    }, [apiClient, options.branchName, options.onSchemaChange, handleError]);
-    const deleteEntry = useCallback(async (entryPath) => {
+    }, [apiClient, options.branchName, options.onSchemaChange, fail]);
+    const deleteEntry = useCallback(async (entryPath, deleteOptions) => {
         setIsLoading(true);
         try {
             const result = await apiClient.entries.delete({
                 branch: options.branchName,
                 entryPath,
+                ...(deleteOptions?.confirmReferenced ? { confirmReferenced: 'true' } : {}),
             });
+            const referencedBy = result.data?.referencedBy;
+            if (!result.ok && referencedBy) {
+                return { ok: false, error: result.error ?? 'Entry is referenced', referencedBy };
+            }
+            if (isGatewayFailure(result))
+                throw new UnansweredError();
             if (!result.ok) {
                 throw new Error(result.error || 'Failed to delete entry');
             }
@@ -192,12 +248,14 @@ export function useSchemaManager(options) {
             return { ok: true };
         }
         catch (error) {
-            return { ok: false, error: handleError('Failed to delete entry', error) };
+            return fail(error, 'Failed to delete entry', {
+                unknown: schemaChangeOutcomeUnknown('Deleting the entry', CHECK_CONTENT_PANEL),
+            });
         }
         finally {
             setIsLoading(false);
         }
-    }, [apiClient, options.branchName, options.onSchemaChange, handleError]);
+    }, [apiClient, options.branchName, options.onSchemaChange, fail]);
     return {
         createCollection,
         updateCollection,

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

@@ -1,4 +1,5 @@
-import type { UserSearchResult } from '../../auth/types.js';
+import { type Cache, type ScopedMutator } from 'swr';
+import type { UserProfile, UserSearchResult } from '../../auth/types.js';
 import type { CanopyUserId } from '../../types.js';
 export interface UseUserMetadataResult {
     userMetadata: UserSearchResult | null;
@@ -6,8 +7,17 @@ export interface UseUserMetadataResult {
     error: Error | null;
 }
 /**
- * Fetches user metadata using the provided getter function.
- *
- * @param cachedUser - Optional: if provided, returns immediately without fetching
+ * Caches profiles a response carried, keeping a cached record's email. A profile matching the
+ * cached record is not written: any write makes SWR discard a lookup in flight, email included. A
+ * user with no record, or whose written record still has no email, is refetched once the writes
+ * settle, since the seed may have discarded a lookup; that refetch is detached, so the caller
+ * never waits on the directory.
  */
+export declare function seedUserProfiles(swr: {
+    cache: Cache;
+    mutate: ScopedMutator;
+}, users: readonly UserProfile[]): Promise<void>;
+/** Answers from the cache with no request and no email, for a reader who may not look users up. */
+export declare function useSeededUserResolver(): (userId: string) => Promise<UserSearchResult | null>;
+/** One user's metadata under a per-user SWR key, so every badge for that user shares a fetch. */
 export declare function useUserMetadata(userId: CanopyUserId, getUserMetadata: (userId: string) => Promise<UserSearchResult | null>, cachedUser?: UserSearchResult): UseUserMetadataResult;