canopycms 0.0.68-int.98 → 0.1.0

package/dist/editor/hooks/useEntryManager.js

@@ -1,11 +1,16 @@
-import { useEffect, useMemo, useRef, useState } from 'react';
+import { createElement, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import useSWR, { useSWRConfig } from 'swr';
 import { notifications } from '@mantine/notifications';
 import { buildWritePayload, normalizeContentPayload } from '../editor-utils.js';
 import { isDataOnlyFormat } from '../../utils/format.js';
+import { withTitleAtPath } from '../../utils/title-field.js';
 import { getErrorMessage } from '../../utils/error.js';
 import { useApiClient } from '../context/index.js';
+import { SCHEMA_UNAVAILABLE_CODE } from '../unavailable-entry-type.js';
 import { entriesKey, fetchEntriesAndSchema } from './useEntriesData.js';
+import { RetryToastMessage } from '../components/RetryToastMessage.js';
+import { isGatewayFailure, isUnanswered, MayHaveLandedError, UnansweredError } from '../unanswered.js';
+const ENTRIES_LOAD_FAILED_TOAST_ID = 'canopy-entries-load-failed';
 // Re-exported so existing imports of `listAllEntries` from this module keep
 // working -- the implementation lives in useEntriesData.ts alongside the
 // other fetch/key/type pieces useEntryManager shares with the SWR layer.
@@ -18,13 +23,27 @@ export { listAllEntries } from './useEntriesData.js';
  * errors (when present) so the form can surface them next to the fields.
  */
 export class SaveApiError extends Error {
-    constructor(status, serverMessage, fieldErrors) {
+    constructor(status, 
+    /** The server's (or saveEntry's own) explanation, if any; `message` falls back to the status. */
+    serverMessage, fieldErrors, code) {
         super(serverMessage || `Save failed: ${status}`);
         this.status = status;
+        this.serverMessage = serverMessage;
         this.fieldErrors = fieldErrors;
+        this.code = code;
         this.name = 'SaveApiError';
     }
 }
+/**
+ * Thrown by a read for editing when the API answers `SCHEMA_UNAVAILABLE`: the entry's type
+ * names a schema the running code lacks, so the entry cannot be opened until that changes.
+ */
+export class EntrySchemaUnavailableError extends Error {
+    constructor(serverMessage) {
+        super(serverMessage || 'Entry type unavailable');
+        this.name = 'EntrySchemaUnavailableError';
+    }
+}
 // Module-level singletons for the derived-empty fallbacks. These must be
 // referentially stable: `collectionByPath` and `currentEntry` memoize on them,
 // and a fresh `[]` each render would invalidate both on every render while a
@@ -32,6 +51,11 @@ export class SaveApiError extends Error {
 const EMPTY_ENTRIES = [];
 const EMPTY_COLLECTIONS = [];
 const EMPTY_SCHEMAS = [];
+/**
+ * The URL's `entry`: a path; `''` for no entry and the navigator open (the crash screen's escape
+ * from an entry that crashes the editor); null opens the first entry.
+ */
+const readUrlEntry = () => typeof window === 'undefined' ? null : new URLSearchParams(window.location.search).get('entry');
 /**
  * Custom hook for managing editor entries (CRUD operations).
  */
@@ -74,7 +98,11 @@ export function useEntryManager(options) {
     };
     // Initialize with prop value or empty (URL sync happens in effect after mount)
     const [selectedPath, setSelectedPath] = useState(options.initialSelectedId ?? '');
-    const [navigatorOpen, setNavigatorOpen] = useState(false);
+    const selectedPathRef = useRef(selectedPath);
+    selectedPathRef.current = selectedPath;
+    // Counts selections through the returned setter, not this hook's own fallbacks.
+    const selectionsByCallerRef = useRef(0);
+    const [navigatorOpen, setNavigatorOpen] = useState(() => readUrlEntry() === '');
     const isInitialMount = useRef(true);
     const hasSyncedFromUrl = useRef(false);
     // OCC version tokens — captured on load, sent on save. Keyed by
@@ -148,11 +176,22 @@ export function useEntryManager(options) {
     const [createModalError, setCreateModalError] = useState(null);
     const [createModalCreating, setCreateModalCreating] = useState(false);
     // Store the URL entry param on mount (before any effects change the URL)
-    const initialUrlEntry = useRef(null);
-    if (typeof window !== 'undefined' && initialUrlEntry.current === null) {
-        const params = new URLSearchParams(window.location.search);
-        initialUrlEntry.current = params.get('entry');
+    const initialUrlEntry = useRef(undefined);
+    if (initialUrlEntry.current === undefined) {
+        initialUrlEntry.current = readUrlEntry();
     }
+    // Set by the URL's empty `entry` or by `closeEntry`; honoured until an entry is selected or the
+    // branch changes, after which a lost selection opens the first again.
+    const noEntryRequested = useRef(initialUrlEntry.current === '');
+    const selectEntryPath = useCallback((path) => {
+        selectionsByCallerRef.current += 1;
+        setSelectedPath(path);
+    }, []);
+    // No entry open, as the URL's empty `entry` asks, where a lost selection opens the first.
+    const closeEntry = useCallback(() => {
+        noEntryRequested.current = true;
+        selectEntryPath('');
+    }, [selectEntryPath]);
     const collectionByPath = useMemo(() => {
         const map = new Map();
         const walk = (collections) => {
@@ -178,32 +217,46 @@ 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({
             branch: requestBranch,
             path,
         });
-        if (!result.ok)
+        if (!result.ok) {
+            if (result.code === SCHEMA_UNAVAILABLE_CODE)
+                throw new EntrySchemaUnavailableError(result.error);
             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.
     const getEntryVersion = (contentId) => entryVersionsRef.current.get(versionKey(options.branchName, contentId));
+    const adoptEntryVersion = (contentId, version) => {
+        entryVersionsRef.current.set(versionKey(options.branchName, contentId), version);
+    };
     const saveEntry = async (entry, value) => {
         if (!entry.collectionPath) {
             throw new Error('Entry missing collectionPath');
@@ -226,16 +279,17 @@ export function useEntryManager(options) {
         // 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.");
+            throw new SaveApiError(409, "This entry hasn't finished loading, so it can't be saved yet. Reload it and try again (your unsaved edits will be lost).");
         }
         const writeBody = {
             ...payload,
             expectedVersion,
         };
         const result = await apiClient.content.write(writeParams, writeBody);
+        if (isGatewayFailure(result))
+            throw new UnansweredError();
         if (!result.ok)
-            throw new SaveApiError(result.status, result.error, result.fieldErrors);
+            throw new SaveApiError(result.status, result.error, result.fieldErrors, result.code);
         // Update stored version token from write response
         if (typeof result.data?.version === 'number') {
             entryVersionsRef.current.set(versionKey(requestBranch, entry.contentId), result.data.version);
@@ -265,6 +319,76 @@ export function useEntryManager(options) {
         }
         return normalizeContentPayload(result.data);
     };
+    // The branch's entries as the server lists them now, without replacing the list on screen.
+    const listEntriesUncommitted = async (branch) => (await fetchEntriesAndSchema(apiClient, branch, {
+        resolvePreviewSrc: options.resolvePreviewSrc,
+    })).entries;
+    // Commits a fresh list and opens what `pick` finds (returned either way), unless the user was
+    // off `fromPath` or chose another entry or branch since. Not judged after the refresh, which
+    // moves the selection off a vanished `fromPath` on its own.
+    const refreshAndOpen = async (branch, fromPath, pick) => {
+        const stillOnIt = selectedPathRef.current === fromPath;
+        const selections = selectionsByCallerRef.current;
+        const found = (await refreshEntries(branch)).find(pick);
+        if (!found || branch !== currentBranchRef.current)
+            return undefined;
+        if (stillOnIt && selections === selectionsByCallerRef.current)
+            setSelectedPath(found.path);
+        return found;
+    };
+    const followMovedEntry = async (entry) => {
+        const branch = options.branchName;
+        const movedHere = (e) => e.contentId === entry.contentId && e.path !== entry.path;
+        if (!(await listEntriesUncommitted(branch)).some(movedHere))
+            return undefined;
+        return refreshAndOpen(branch, entry.path, movedHere);
+    };
+    // After a create that landed, a failed refresh is "not listed yet", never a failed create.
+    const openCreated = (branch, fromPath, pick) => refreshAndOpen(branch, fromPath, pick).catch((err) => {
+        console.error(err);
+        return undefined;
+    });
+    const recreateEntry = async (entry, value) => {
+        if (!entry.collectionPath) {
+            throw new Error('Entry missing collectionPath');
+        }
+        const branch = options.branchName;
+        const path = entry.slug ? `${entry.collectionPath}/${entry.slug}` : entry.collectionPath;
+        const writeParams = { branch, path };
+        if (entry.entryType)
+            writeParams.entryType = entry.entryType;
+        // The new entry, not the gone one a lagging list may still show at that path.
+        const createdHere = (e) => e.path === entry.path && e.contentId !== entry.contentId;
+        let result;
+        try {
+            result = await apiClient.content.write(writeParams, {
+                ...buildWritePayload(entry, value),
+                expectedVersion: null,
+            });
+            if (isGatewayFailure(result))
+                throw new UnansweredError();
+        }
+        catch (err) {
+            // An unanswered create may have landed: if the list now has a new entry at the path, it did.
+            if (!isUnanswered(err))
+                throw err;
+            const listed = await listEntriesUncommitted(branch).catch(() => []);
+            if (!listed.some(createdHere))
+                throw err;
+            const landed = await openCreated(branch, entry.path, createdHere);
+            // No answer, so no version: read it, as a draft moved onto the entry needs it as its base.
+            if (landed)
+                await loadEntry(landed).catch(console.error);
+            return landed;
+        }
+        if (!result.ok)
+            throw new SaveApiError(result.status, result.error, result.fieldErrors, result.code);
+        const created = await openCreated(branch, entry.path, createdHere);
+        if (created && typeof result.data?.version === 'number') {
+            entryVersionsRef.current.set(versionKey(branch, created.contentId), result.data.version);
+        }
+        return created;
+    };
     // Explicit reload: always issues a fresh, independent fetch (never
     // deduped/coalesced against an in-flight automatic load) so callers that
     // just mutated content (save, create, rename, schema change) are
@@ -272,9 +396,9 @@ export function useEntryManager(options) {
     // refreshSeqRef doc comment above; also warms the SWR cache for `branch`
     // so a later automatic re-fetch of the same key (e.g. switching away and
     // back) can reuse it instead of refetching.
-    const refreshEntries = async (branch = options.branchName) => {
+    const refreshContent = async (branch = options.branchName) => {
         if (!branch)
-            return [];
+            return { entries: [], collections: [] };
         const seq = claimRefreshSeq(branch);
         const fetched = await fetchEntriesAndSchema(apiClient, branch, {
             resolvePreviewSrc: options.resolvePreviewSrc,
@@ -292,8 +416,9 @@ export function useEntryManager(options) {
                 setView({ branch, ...fetched });
             }
         }
-        return fetched.entries;
+        return fetched;
     };
+    const refreshEntries = async (branch = options.branchName) => (await refreshContent(branch)).entries;
     const handleCreateEntry = async (collectionPath, _) => {
         const col = collectionByPath.get(collectionPath);
         if (!col || col.type === 'entry') {
@@ -303,7 +428,7 @@ export function useEntryManager(options) {
         setCreateModalError(null);
         setCreateModalOpen(true);
     };
-    const handleCreateModalSubmit = async (slug, entryTypeName) => {
+    const handleCreateModalSubmit = async (slug, entryTypeName, title) => {
         if (!createModalCollection)
             return;
         setCreateModalCreating(true);
@@ -317,9 +442,10 @@ export function useEntryManager(options) {
             // already exist yet". The client always sends create intent here,
             // never a blind update, so a same-slug create cannot silently
             // overwrite existing content.
+            const data = title && selectedType?.titleField ? withTitleAtPath(selectedType.titleField, title) : {};
             const payload = isDataOnlyFormat(format)
-                ? { format: format, data: {}, expectedVersion: null }
-                : { format, data: {}, body: '', expectedVersion: null };
+                ? { format: format, data, expectedVersion: null }
+                : { format, data, body: '', expectedVersion: null };
             // Use collection path (e.g., "content/posts") not name (e.g., "posts")
             const path = `${createModalCollection.path}/${slug}`;
             const result = await apiClient.content.write({
@@ -327,6 +453,8 @@ export function useEntryManager(options) {
                 path,
                 entryType: entryTypeName,
             }, payload);
+            if (isGatewayFailure(result))
+                throw new UnansweredError();
             if (!result.ok) {
                 const errorMsg = 'error' in result ? result.error : `Create failed: ${result.status}`;
                 throw new Error(errorMsg);
@@ -352,6 +480,9 @@ export function useEntryManager(options) {
             console.error(err);
             const errorMessage = err instanceof Error ? err.message : 'Create failed';
             setCreateModalError(errorMessage);
+            // An unanswered create may have landed; the content tree then shows it.
+            if (isUnanswered(err))
+                void refreshEntries().catch(console.error);
         }
         finally {
             setCreateModalCreating(false);
@@ -364,32 +495,57 @@ export function useEntryManager(options) {
         setCreateModalCreating(false);
     };
     const renameEntry = async (path, newSlug) => {
+        const renaming = entriesState.find((e) => e.path === path);
+        const contentId = renaming?.contentId;
+        const label = renaming?.label ?? path;
+        // As `refreshAndOpen`: the new path opens only if the user is still on the entry and branch.
+        const branch = options.branchName;
+        const stillOnIt = selectedPathRef.current === path;
+        const selections = selectionsByCallerRef.current;
+        // The rename landed whatever the refresh does. The new path is selected only once the list
+        // holds it: before that, the selection check would find it missing and open the first entry.
+        const landed = async (newPath) => {
+            const listed = await refreshEntries().catch((err) => {
+                console.error(err);
+                return null;
+            });
+            if (newPath &&
+                listed?.some((e) => e.path === newPath) &&
+                stillOnIt &&
+                selections === selectionsByCallerRef.current &&
+                branch === currentBranchRef.current) {
+                setSelectedPath(newPath);
+            }
+            notifications.show({ message: 'Entry renamed', color: 'green' });
+        };
         options.setBusy(true);
         try {
             const result = await apiClient.content.renameEntry({
                 branch: options.branchName,
                 path,
             }, { newSlug });
+            if (isGatewayFailure(result))
+                throw new UnansweredError();
             if (!result.ok) {
                 const errorMsg = 'error' in result ? result.error : `Rename failed: ${result.status}`;
                 throw new Error(errorMsg);
             }
-            // Update the selected path if the renamed entry is currently selected
-            if (selectedPath === path && result.data) {
-                setSelectedPath(result.data.newPath);
-            }
-            // Refresh entries to get updated paths
-            await refreshEntries();
-            notifications.show({
-                message: 'Entry renamed successfully',
-                color: 'green',
-            });
+            await landed(result.data?.newPath);
         }
         catch (err) {
             console.error(err);
-            const errorMessage = err instanceof Error ? err.message : 'Rename failed';
-            notifications.show({ message: errorMessage, color: 'red' });
-            throw err;
+            if (!isUnanswered(err))
+                throw err;
+            // Re-listed by content ID, under the new slug it landed. Still at the old path proves
+            // nothing: past the client's deadline the server may still be working.
+            const listed = await listEntriesUncommitted(options.branchName).catch(() => null);
+            const now = contentId ? listed?.find((e) => e.contentId === contentId) : undefined;
+            if (now && now.path !== path && now.slug === newSlug) {
+                await landed(now.path);
+                return;
+            }
+            void refreshEntries().catch(console.error);
+            throw new MayHaveLandedError(`Renaming "${label}" may have gone through even though the server didn't answer. Check the "Content" panel before trying again.`);
         }
         finally {
             options.setBusy(false);
@@ -407,6 +563,7 @@ export function useEntryManager(options) {
             isInitialMount.current = false;
         }
         else {
+            noEntryRequested.current = false;
             setSelectedPath('');
             // Bound version-map growth across switches. Correctness no longer
             // depends on this clear: tokens are keyed by `${branch}:${contentId}`
@@ -500,21 +657,37 @@ export function useEntryManager(options) {
     const notifiedErrorBranchRef = useRef(null);
     useEffect(() => {
         if (!entriesError || !options.branchName) {
+            if (notifiedErrorBranchRef.current !== null)
+                notifications.hide(ENTRIES_LOAD_FAILED_TOAST_ID);
             notifiedErrorBranchRef.current = null;
             return;
         }
         if (notifiedErrorBranchRef.current === options.branchName)
             return;
-        notifiedErrorBranchRef.current = options.branchName;
+        const branch = options.branchName;
+        notifiedErrorBranchRef.current = branch;
         console.error(entriesError);
+        // A shown toast with this id ignores `show`, so another branch's would keep its Retry.
+        notifications.hide(ENTRIES_LOAD_FAILED_TOAST_ID);
         notifications.show({
+            id: ENTRIES_LOAD_FAILED_TOAST_ID,
             title: 'Could not load content',
-            message: getErrorMessage(entriesError),
+            message: createElement(RetryToastMessage, {
+                message: getErrorMessage(entriesError),
+                onRetry: () => {
+                    notifications.hide(ENTRIES_LOAD_FAILED_TOAST_ID);
+                    notifiedErrorBranchRef.current = null;
+                    void globalMutate(entriesKey(branch));
+                },
+            }),
             color: 'red',
+            autoClose: false,
         });
     }, [entriesError, options.branchName]);
     // Validate selected entry when entries change
     useEffect(() => {
+        if (selectedPath)
+            noEntryRequested.current = false;
         // Skip validation if entries haven't loaded yet
         if (entriesState.length === 0)
             return;
@@ -530,6 +703,8 @@ export function useEntryManager(options) {
         // If the selected entry exists, keep it
         if (entriesState.find((e) => e.path === selectedPath))
             return;
+        if (selectedPath === '' && noEntryRequested.current)
+            return;
         // Fall back to first entry
         setSelectedPath(entriesState[0]?.path ?? '');
     }, [entriesState, selectedPath]);
@@ -544,6 +719,10 @@ export function useEntryManager(options) {
         if (selectedPath) {
             url.searchParams.set('entry', selectedPath);
         }
+        else if (noEntryRequested.current) {
+            // Kept, so a reload still opens no entry.
+            url.searchParams.set('entry', '');
+        }
         else {
             url.searchParams.delete('entry');
         }
@@ -551,21 +730,28 @@ export function useEntryManager(options) {
     }, [selectedPath]);
     return {
         selectedPath,
-        setSelectedPath,
+        setSelectedPath: selectEntryPath,
+        closeEntry,
         entries: entriesState,
         setEntries,
         collections: collectionsState,
         currentEntry,
         availableSchemas,
         entriesInitializing,
+        entriesLoadFailed: Boolean(options.branchName) && Boolean(entriesError),
         navigatorOpen,
         setNavigatorOpen,
         refreshEntries,
+        refreshContent,
         handleCreateEntry,
         renameEntry,
         loadEntry,
+        readEntryValue,
         saveEntry,
         getEntryVersion,
+        adoptEntryVersion,
+        followMovedEntry,
+        recreateEntry,
         collectionByPath: collectionByPath,
         createModalOpen,
         createModalCollection,

package/dist/editor/hooks/useGroupManager.js

@@ -1,6 +1,8 @@
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { notifications } from '@mantine/notifications';
 import { useApiClient } from '../context/index.js';
+import { SETTINGS_CHANGED_CODE, SettingsChangedError } from '../settings-conflict.js';
+import { createUserMetadataBatcher } from './user-metadata-batcher.js';
 /**
  * Custom hook for managing internal groups (CRUD operations).
  */
@@ -39,10 +41,13 @@ export function useGroupManager(options) {
                 expectedContentVersion: versionRef.current,
             });
             if (!result.ok) {
-                throw new Error(result.error || 'Failed to save groups');
+                const message = result.error || 'Failed to save groups';
+                throw result.code === SETTINGS_CHANGED_CODE
+                    ? new SettingsChangedError(message)
+                    : new Error(message);
             }
             notifications.show({
-                title: 'Groups Saved',
+                title: 'Groups saved',
                 message: 'Internal groups have been updated',
                 color: 'green',
             });
@@ -50,7 +55,10 @@ export function useGroupManager(options) {
         }
         catch (err) {
             const message = err instanceof Error ? err.message : 'Failed to save groups';
-            notifications.show({ message, color: 'red' });
+            notifications.show({
+                message,
+                color: err instanceof SettingsChangedError ? 'yellow' : 'red',
+            });
             throw err;
         }
     }, []);
@@ -70,18 +78,7 @@ export function useGroupManager(options) {
             return [];
         }
     }, []);
-    const handleGetUserMetadata = useCallback(async (userId) => {
-        try {
-            const result = await apiClient.permissions.getUserMetadata({ userId });
-            if (!result.ok)
-                return null;
-            return result.data?.user ?? null;
-        }
-        catch (err) {
-            console.error('Get user metadata failed:', err);
-            return null;
-        }
-    }, []);
+    const handleGetUserMetadata = useMemo(() => createUserMetadataBatcher(apiClient), [apiClient]);
     const handleSearchExternalGroups = useCallback(async (query) => {
         try {
             const result = await apiClient.groups.searchExternal({ q: query });

package/dist/editor/hooks/usePermissionManager.js

@@ -1,6 +1,7 @@
-import { useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import { notifications } from '@mantine/notifications';
 import { useApiClient } from '../context/index.js';
+import { SETTINGS_CHANGED_CODE, SettingsChangedError } from '../settings-conflict.js';
 /**
  * Custom hook for managing path permissions (CRUD operations).
  */
@@ -42,10 +43,13 @@ export function usePermissionManager(options) {
                 expectedContentVersion: versionRef.current,
             });
             if (!result.ok) {
-                throw new Error(result.error || 'Failed to save permissions');
+                const message = result.error || 'Failed to save permissions';
+                throw result.code === SETTINGS_CHANGED_CODE
+                    ? new SettingsChangedError(message)
+                    : new Error(message);
             }
             notifications.show({
-                title: 'Permissions Saved',
+                title: 'Permissions saved',
                 message: 'Permissions have been updated',
                 color: 'green',
             });
@@ -53,7 +57,10 @@ export function usePermissionManager(options) {
         }
         catch (err) {
             const message = err instanceof Error ? err.message : 'Failed to save permissions';
-            notifications.show({ message, color: 'red' });
+            notifications.show({
+                message,
+                color: err instanceof SettingsChangedError ? 'yellow' : 'red',
+            });
             throw err;
         }
     };
@@ -64,13 +71,14 @@ export function usePermissionManager(options) {
     // an unreadable groups.json rendered as a silently empty picker with no
     // warning, which is the same failure class listGroupsHandler's deliberate
     // 500 exists to prevent.
-    const handleListGroups = async () => {
+    // Stable identity: useGroupsAndUsers reloads groups whenever this function changes.
+    const handleListGroups = useCallback(async () => {
         const result = await apiClient.permissions.listGroups();
         if (!result.ok) {
             throw new Error(result.error || 'Failed to load groups');
         }
         return result.data?.groups ?? [];
-    };
+    }, [apiClient]);
     useEffect(() => {
         if (options.isOpen) {
             loadPermissions();

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

@@ -0,0 +1,21 @@
+import type { FieldConfig } from '../../config/index.js';
+import type { PreviewMarks } from '../PreviewFrame.js';
+import { type InexactMark } from '../preview-marks.js';
+/**
+ * What the framed page reports of its marks while highlighting is on, kept for the `src` that
+ * said so: whether it marks nothing, and which marks name no field of the entry. Each such mark
+ * is a console warning once per page and path, since the toggle's note only counts them. A report
+ * is checked against the draft as it stood when the report arrived, not the draft since, and the
+ * page reports after each draft (`usePreviewHighlight`), so the two stay in step.
+ */
+export declare function usePreviewMarks({ src, highlightEnabled, fields, data, }: {
+    src: string | undefined;
+    highlightEnabled: boolean;
+    fields: readonly FieldConfig[];
+    data: unknown;
+}): {
+    onMarks: (reported: PreviewMarks) => void;
+    clearMarks: () => void;
+    marksNothing: boolean;
+    inexactMarks: InexactMark[];
+};

package/dist/editor/hooks/usePreviewMarks.js

@@ -0,0 +1,33 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { findInexactMarks } from '../preview-marks.js';
+const NO_MARKS = [];
+/**
+ * What the framed page reports of its marks while highlighting is on, kept for the `src` that
+ * said so: whether it marks nothing, and which marks name no field of the entry. Each such mark
+ * is a console warning once per page and path, since the toggle's note only counts them. A report
+ * is checked against the draft as it stood when the report arrived, not the draft since, and the
+ * page reports after each draft (`usePreviewHighlight`), so the two stay in step.
+ */
+export function usePreviewMarks({ src, highlightEnabled, fields, data, }) {
+    const [marks, setMarks] = useState(null);
+    const current = highlightEnabled && marks !== null && marks.src === src ? marks : null;
+    const latestData = useRef(data);
+    useEffect(() => {
+        latestData.current = data;
+    });
+    const inexactMarks = useMemo(() => (current?.paths ? findInexactMarks(fields, current.data, current.paths) : NO_MARKS), [current?.paths, current?.data, fields]);
+    const warned = useRef(new Set());
+    useEffect(() => {
+        for (const { path, nearest } of inexactMarks) {
+            const key = JSON.stringify([src, path]);
+            if (warned.current.has(key))
+                continue;
+            warned.current.add(key);
+            console.warn(`[canopycms] The preview marks "${path}", which names no field of this entry` +
+                (nearest ? `; its nearest field is "${nearest}".` : '.'));
+        }
+    }, [inexactMarks, src]);
+    const onMarks = useCallback((reported) => setMarks({ ...reported, src: src ?? '', data: latestData.current }), [src]);
+    const clearMarks = useCallback(() => setMarks(null), []);
+    return { onMarks, clearMarks, marksNothing: current?.count === 0, inexactMarks };
+}