canopycms 0.0.68-int.98 → 0.1.0

package/dist/editor/hooks/useBranchesData.js

@@ -12,15 +12,17 @@
  * })` -- see the comment on `fetchBranches` for why it doesn't just call
  * `mutate()` to revalidate.
  */
-import useSWR from 'swr';
+import useSWR, { useSWRConfig } from 'swr';
 import { isNonApiResponse } from '../../api/client.js';
+import { seedUserProfiles } from './useUserMetadata.js';
 /** Cache key for the branches list. */
 export const BRANCHES_KEY = 'canopy:branches';
 /**
- * Fetch the branches list. Exported for direct testing and for the
- * imperative reload path.
+ * Fetch the branches list, writing the owners it names into the user-metadata cache before the
+ * listing lands, so owner badges render named. Exported for direct testing and for the imperative
+ * reload path.
  */
-export async function fetchBranches(apiClient) {
+export async function fetchBranches(apiClient, swr) {
     const result = await apiClient.branches.list();
     if (result.status === 404 && !isNonApiResponse(result)) {
         // No branch endpoint available; stay branchless rather than erroring --
@@ -31,6 +33,7 @@ export async function fetchBranches(apiClient) {
     if (!result.ok) {
         throw new Error(result.error ?? `Failed to load branches: ${result.status}`);
     }
+    await seedUserProfiles(swr, result.data?.users ?? []);
     return {
         branches: result.data?.branches ?? [],
         defaultBranch: result.data?.defaultBranch,
@@ -69,7 +72,8 @@ export function hasInFlightBranch(data) {
  * `refreshInterval`, and narrower than the pre-SWR behavior it replaces.
  */
 export function useBranchesData(apiClient) {
-    return useSWR(BRANCHES_KEY, () => fetchBranches(apiClient), {
+    const { cache, mutate } = useSWRConfig();
+    return useSWR(BRANCHES_KEY, () => fetchBranches(apiClient, { cache, mutate }), {
         refreshInterval: (data) => hasInFlightBranch(data) ? IN_FLIGHT_POLL_MS : 0,
     });
 }

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

@@ -1,4 +1,5 @@
 import type { CommentThread } from '../../comment-store.js';
+import type { UserSearchResult } from '../../auth/types.js';
 import type { EditorEntry } from '../Editor.js';
 export interface UseCommentSystemOptions {
     branchName: string;
@@ -8,10 +9,14 @@ export interface UseCommentSystemOptions {
     canResolveComments: boolean;
     setSelectedPath: (id: string) => void;
     setBranchManagerOpen: (open: boolean) => void;
+    /** Uncovers the form before anything here focuses one of its fields. */
+    onRevealForm?: () => void;
     onCommentsChange?: (comments: CommentThread[]) => void;
 }
 export interface UseCommentSystemReturn {
     comments: CommentThread[];
+    /** Resolves a user from the seeded cache, without email or a request (`useSeededUserResolver`). */
+    getCommentUser: (userId: string) => Promise<UserSearchResult | null>;
     focusedFieldPath: string | undefined;
     setFocusedFieldPath: (path: string | undefined) => void;
     highlightThreadId: string | undefined;
@@ -30,13 +35,20 @@ export interface UseCommentSystemReturn {
     } | null) => void;
     activeThreads: CommentThread[];
     activeContextLabel: string;
-    handleAddComment: (text: string, type: 'field' | 'entry' | 'branch', entryPath?: string, canopyPath?: string, threadId?: string) => Promise<void>;
+    /** `itemKeys`: for a new field thread, the keys of the list items on `canopyPath`. */
+    handleAddComment: (text: string, type: 'field' | 'entry' | 'branch', entryPath?: string, canopyPath?: string, threadId?: string, itemKeys?: string[]) => Promise<void>;
     handleResolveThread: (threadId: string) => Promise<void>;
-    loadComments: (branch: string) => Promise<void>;
+    loadComments: (branch: string) => Promise<CommentThread[] | undefined>;
     handleJumpToField: (entryPath: string, canopyPath: string, threadId: string) => void;
     handleJumpToEntry: (entryPath: string, threadId: string) => void;
     handleJumpToBranch: (threadId: string) => void;
 }
+/** @internal Exported for tests. */
+export declare const COMMENT_NOT_ADDED = "Couldn't add the comment. Try again.";
+/** @internal Exported for tests. */
+export declare const COMMENT_MAY_BE_ADDED = "The server didn't answer, and the comments don't show yours yet, but it may still be posted. Wait a moment and check before sending it again.";
+/** @internal Exported for tests. */
+export declare const THREAD_NOT_RESOLVED = "Couldn't resolve the thread. Try again.";
 /**
  * Custom hook for managing the comment system.
  */

package/dist/editor/hooks/useCommentSystem.js

@@ -1,17 +1,24 @@
 import { useEffect, useMemo, useState } from 'react';
 import { useSWRConfig } from 'swr';
-import { notifications } from '@mantine/notifications';
-import { normalizeCanopyPath } from '../canopy-path.js';
+import { findFieldTarget, whenRevealed } from '../field-target.js';
 import { useApiClient } from '../context/index.js';
+import { isGatewayFailure, isUnanswered, MayHaveLandedError } from '../unanswered.js';
 import { resolveMessageOrigin } from '../preview-bridge.js';
 import { isSamePreviewPath } from '../preview-path.js';
-import { commentsKey, fetchComments, useCommentsData } from './useCommentsData.js';
+import { commentsKey, fetchCommentsSeedingUsers, useCommentsData } from './useCommentsData.js';
+import { useSeededUserResolver } from './useUserMetadata.js';
+/** @internal Exported for tests. */
+export const COMMENT_NOT_ADDED = "Couldn't add the comment. Try again.";
+/** @internal Exported for tests. */
+export const COMMENT_MAY_BE_ADDED = "The server didn't answer, and the comments don't show yours yet, but it may still be posted. Wait a moment and check before sending it again.";
+/** @internal Exported for tests. */
+export const THREAD_NOT_RESOLVED = "Couldn't resolve the thread. Try again.";
 /**
  * Custom hook for managing the comment system.
  */
 export function useCommentSystem(options) {
     const apiClient = useApiClient();
-    const { mutate: globalMutate } = useSWRConfig();
+    const { cache, mutate: globalMutate } = useSWRConfig();
     const [focusedFieldPath, setFocusedFieldPath] = useState(undefined);
     const [highlightThreadId, setHighlightThreadId] = useState(undefined);
     const [commentsPanelOpen, setCommentsPanelOpen] = useState(false);
@@ -21,64 +28,81 @@ export function useCommentSystem(options) {
     // Mode's double effect invoke collapses to a single request). Switching
     // branches re-keys automatically, so no manual branch-change effect is
     // needed.
-    const { data: commentsData } = useCommentsData(apiClient, options.branchName);
+    const { data: commentsData, error: commentsError } = useCommentsData(apiClient, options.branchName);
     const comments = commentsData?.threads ?? [];
+    const getCommentUser = useSeededUserResolver();
     // Deliberately omits `options.onCommentsChange` from the deps: it's a
     // stable setState passthrough, and this file is plain .ts (not .tsx), so
     // the react-hooks/exhaustive-deps rule isn't active here anyway --
     // including it would refire this on every Editor.tsx render regardless.
+    // A branch whose comments never loaded reports none, not the previous branch's.
     useEffect(() => {
         if (commentsData)
             options.onCommentsChange?.(commentsData.threads);
-    }, [commentsData]);
+        else if (commentsError)
+            options.onCommentsChange?.([]);
+    }, [commentsData, commentsError]);
     // Explicit reload: always issues a fresh, independent fetch (raw call, not
     // SWR's `mutate()` revalidate path) so a caller requesting a reload right
     // after mount isn't coalesced against the still-in-flight automatic load
     // -- then writes the result into the shared cache so useCommentsData's
     // bound hook (and the effect above) pick it up.
+    // A failed reload logs and keeps the threads already shown. Resolves to the reloaded threads.
     const loadComments = async (branch) => {
         if (!branch)
-            return;
-        const fresh = await fetchComments(apiClient, branch);
+            return undefined;
+        let fresh;
+        try {
+            fresh = await fetchCommentsSeedingUsers(apiClient, { cache, mutate: globalMutate }, branch);
+        }
+        catch (err) {
+            console.error('Failed to load comments:', err);
+            return undefined;
+        }
         await globalMutate(commentsKey(branch), fresh, { revalidate: false });
+        return fresh.threads;
     };
-    const handleAddComment = async (text, type, entryPath, canopyPath, threadId) => {
-        if (!options.branchName)
+    // Both reject on failure, so the caller keeps the person's text and shows the error where they
+    // wrote it. Success shows itself in the thread, so it has no toast.
+    const handleAddComment = async (text, type, entryPath, canopyPath, threadId, itemKeys) => {
+        const branch = options.branchName;
+        if (!branch)
             return;
-        try {
-            const result = await apiClient.comments.add({ branch: options.branchName }, {
-                text,
-                threadId,
-                type,
-                entryPath,
-                canopyPath,
-            });
-            if (!result.ok)
-                throw new Error('Failed to add comment');
-            await loadComments(options.branchName);
-            // Branch summaries auto-update via useMemo watching comments
-            notifications.show({ message: 'Comment added', color: 'green' });
-        }
-        catch {
-            notifications.show({ message: 'Failed to add comment', color: 'red' });
+        // What was on screen at send, so only a comment that is new since can count as this one.
+        const loaded = commentsData !== undefined;
+        const shownComments = new Set(comments.flatMap((t) => t.comments.map((c) => c.id)));
+        const isThis = (c) => !shownComments.has(c.id) && c.userId === options.currentUser && c.text === text;
+        const result = await apiClient.comments
+            .add({ branch }, { text, threadId, type, entryPath, canopyPath, itemKeys })
+            .catch((err) => (isUnanswered(err) ? 'unanswered' : null));
+        if (result === 'unanswered' || (result && isGatewayFailure(result))) {
+            // Landed, it is a new comment of theirs: in the thread replied to, or opening one here.
+            const reloaded = await loadComments(branch);
+            const posted = loaded &&
+                reloaded?.some((t) => threadId
+                    ? t.id === threadId && t.comments.some(isThis)
+                    : t.type === type &&
+                        t.entryPath === entryPath &&
+                        t.canopyPath === canopyPath &&
+                        t.comments[0] !== undefined &&
+                        isThis(t.comments[0]));
+            if (posted)
+                return;
+            throw new MayHaveLandedError(COMMENT_MAY_BE_ADDED);
         }
+        if (!result?.ok)
+            throw new Error(COMMENT_NOT_ADDED);
+        await loadComments(branch);
     };
     const handleResolveThread = async (threadId) => {
         if (!options.branchName)
             return;
-        try {
-            const result = await apiClient.comments.resolve({
-                branch: options.branchName,
-                threadId,
-            });
-            if (!result.ok)
-                throw new Error('Failed to resolve thread');
-            await loadComments(options.branchName);
-            notifications.show({ message: 'Thread resolved', color: 'green' });
-        }
-        catch {
-            notifications.show({ message: 'Failed to resolve thread', color: 'red' });
-        }
+        const result = await apiClient.comments
+            .resolve({ branch: options.branchName, threadId })
+            .catch(() => null);
+        if (!result?.ok)
+            throw new Error(THREAD_NOT_RESOLVED);
+        await loadComments(options.branchName);
     };
     // Compute active comment threads for the thread panel
     const activeThreads = useMemo(() => {
@@ -87,7 +111,8 @@ export function useCommentSystem(options) {
         if (activeCommentContext.type === 'field' && activeCommentContext.canopyPath) {
             return comments.filter((t) => t.type === 'field' &&
                 t.entryPath === options.selectedPath &&
-                t.canopyPath === activeCommentContext.canopyPath);
+                t.canopyPath === activeCommentContext.canopyPath &&
+                !t.onRemovedItem);
         }
         else if (activeCommentContext.type === 'entry') {
             return comments.filter((t) => t.type === 'entry' && t.entryPath === options.selectedPath);
@@ -138,23 +163,19 @@ export function useCommentSystem(options) {
                     currentPath === undefined ||
                     !isSamePreviewPath(msg.entryPath, currentPath)))
                 return;
-            const normalizedPath = msg.fieldPath ? normalizeCanopyPath(msg.fieldPath) : undefined;
-            const target = normalizedPath
-                ? document.querySelector(`[data-canopy-field="${normalizedPath}"]`)
-                : null;
-            if (target) {
-                target.scrollIntoView({ behavior: 'smooth', block: 'center' });
+            const found = typeof msg.fieldPath === 'string' ? findFieldTarget(msg.fieldPath) : undefined;
+            if (found) {
+                const target = found.element;
+                whenRevealed(target, () => target.scrollIntoView({ behavior: 'smooth', block: 'center' }));
                 const previous = target.style.boxShadow;
                 target.style.boxShadow = '0 0 0 3px rgba(79, 70, 229, 0.35)';
                 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
-                    later(() => setFocusedFieldPath(undefined), 100);
-                }
+                options.onRevealForm?.();
+                // Cleared shortly after, once FieldWrapper has seen it and scrolled to the field.
+                setFocusedFieldPath(found.path);
+                later(() => setFocusedFieldPath(undefined), 100);
             }
         };
         window.addEventListener('message', handleFocus);
@@ -172,10 +193,11 @@ export function useCommentSystem(options) {
             options.setSelectedPath(entryPath);
         }
         window.setTimeout(() => {
-            const fieldElement = document.querySelector(`[data-canopy-field="${canopyPath}"]`);
-            if (fieldElement) {
-                fieldElement.scrollIntoView({ behavior: 'smooth', block: 'center' });
+            const target = findFieldTarget(canopyPath)?.element;
+            if (target) {
+                whenRevealed(target, () => target.scrollIntoView({ behavior: 'smooth', block: 'center' }));
             }
+            options.onRevealForm?.();
             setFocusedFieldPath(canopyPath);
             setHighlightThreadId(threadId);
             window.setTimeout(() => {
@@ -194,6 +216,7 @@ export function useCommentSystem(options) {
             if (formElement) {
                 formElement.scrollIntoView({ behavior: 'smooth', block: 'start' });
             }
+            options.onRevealForm?.();
             setHighlightThreadId(threadId);
             window.setTimeout(() => {
                 setHighlightThreadId(undefined);
@@ -209,6 +232,7 @@ export function useCommentSystem(options) {
     };
     return {
         comments,
+        getCommentUser,
         focusedFieldPath,
         setFocusedFieldPath,
         highlightThreadId,

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

@@ -6,23 +6,27 @@
  * its own branch-keyed effect. See useBranchesData.ts for the same pattern
  * applied to the branches list.
  */
-import { type SWRResponse } from 'swr';
+import { type Cache, type ScopedMutator, type SWRResponse } from 'swr';
 import type { ApiClient } from '../context/index.js';
 import type { CommentThread } from '../../comment-store.js';
+import type { UserProfile } from '../../auth/types.js';
 /** Cache key for a branch's comment threads. */
 export declare const commentsKey: (branch: string) => string;
 export interface CommentsData {
     threads: CommentThread[];
+    /** Who wrote or resolved `threads`: name and avatar, never email. */
+    users: UserProfile[];
 }
 /**
- * Fetch a branch's comment threads. Never throws -- matches the pre-SWR
- * `loadComments` behavior of logging and resolving to an empty list on
- * failure rather than surfacing an error state (comments have no error UI).
- * Exported for direct testing and for the imperative reload path.
+ * {@link fetchComments}, with the users it names written into the user-metadata cache before the
+ * threads that show them land, so their badges render named.
  */
-export declare function fetchComments(apiClient: Pick<ApiClient, 'comments'>, branch: string): Promise<CommentsData>;
+export declare function fetchCommentsSeedingUsers(apiClient: Pick<ApiClient, 'comments'>, swr: {
+    cache: Cache;
+    mutate: ScopedMutator;
+}, branch: string): Promise<CommentsData>;
 /**
  * SWR-backed read of a branch's comment threads. `branch` may be empty
  * (branchless start), in which case fetching is disabled entirely (null key).
  */
-export declare function useCommentsData(apiClient: Pick<ApiClient, 'comments'>, branch: string): SWRResponse<CommentsData, never>;
+export declare function useCommentsData(apiClient: Pick<ApiClient, 'comments'>, branch: string): SWRResponse<CommentsData, unknown>;

package/dist/editor/hooks/useCommentsData.js

@@ -7,33 +7,34 @@
  * its own branch-keyed effect. See useBranchesData.ts for the same pattern
  * applied to the branches list.
  */
-import useSWR from 'swr';
+import useSWR, { useSWRConfig } from 'swr';
+import { seedUserProfiles } from './useUserMetadata.js';
 /** Cache key for a branch's comment threads. */
 export const commentsKey = (branch) => `canopy:comments:${branch}`;
 /**
- * Fetch a branch's comment threads. Never throws -- matches the pre-SWR
- * `loadComments` behavior of logging and resolving to an empty list on
- * failure rather than surfacing an error state (comments have no error UI).
- * Exported for direct testing and for the imperative reload path.
+ * A branch's comment threads. Rejects when they can't be read, so a failed reload leaves the
+ * threads already shown in place rather than emptying them.
  */
-export async function fetchComments(apiClient, branch) {
-    try {
-        const result = await apiClient.comments.list({ branch });
-        if (!result.ok) {
-            console.error('Failed to load comments:', result.status);
-            return { threads: [] };
-        }
-        return { threads: result.data?.threads ?? [] };
-    }
-    catch (err) {
-        console.error('Failed to load comments:', err);
-        return { threads: [] };
-    }
+async function fetchComments(apiClient, branch) {
+    const result = await apiClient.comments.list({ branch });
+    if (!result.ok)
+        throw new Error(`Failed to load comments (HTTP ${result.status})`);
+    return { threads: result.data?.threads ?? [], users: result.data?.users ?? [] };
+}
+/**
+ * {@link fetchComments}, with the users it names written into the user-metadata cache before the
+ * threads that show them land, so their badges render named.
+ */
+export async function fetchCommentsSeedingUsers(apiClient, swr, branch) {
+    const data = await fetchComments(apiClient, branch);
+    await seedUserProfiles(swr, data.users);
+    return data;
 }
 /**
  * SWR-backed read of a branch's comment threads. `branch` may be empty
  * (branchless start), in which case fetching is disabled entirely (null key).
  */
 export function useCommentsData(apiClient, branch) {
-    return useSWR(branch ? commentsKey(branch) : null, () => fetchComments(apiClient, branch));
+    const { cache, mutate } = useSWRConfig();
+    return useSWR(branch ? commentsKey(branch) : null, () => fetchCommentsSeedingUsers(apiClient, { cache, mutate }, branch), { onError: (err) => console.error('Failed to load comments:', err) });
 }

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

@@ -1,6 +1,24 @@
 import type { EditorEntry } from '../Editor.js';
 import type { LogicalPath } from '../../paths/types.js';
 import type { FormValue } from '../FormRenderer.js';
+import type { StampedEntry } from '../../stamp-on-publish.js';
+import { type SaveAllProgress, type SaveAllResult } from './save-all.js';
+/** @internal Exported for tests. */
+export declare const SAVE_TIMED_OUT_MESSAGE = "Save didn't finish, and may not have gone through. Your changes are still here, so save again.";
+/** @internal Exported for tests. Shown when a save may already have landed, until a reload. */
+export declare const SAVE_MAY_HAVE_LANDED_MESSAGE = "Your last save may already have gone through. Before saving again, choose \"Refresh from server\" in the entry's menu, on its name; your unsaved edits will be lost.";
+/** @internal Exported for tests. A save refused because the entry was deleted. */
+export declare const ENTRY_DELETED_MESSAGE = "This entry was deleted since you opened it, so it was not saved. Your changes are still in the form until the content list next refreshes and closes it: choose \"Save as new entry\" to keep them.";
+/** @internal Exported for tests. A save refused because the entry was renamed; the editor has opened it. */
+export declare const ENTRY_RENAMED_MESSAGE = "This entry was renamed since you opened it, so it was not saved. Your changes moved with it and are still in the form: save again to keep them.";
+/** @internal Exported for tests. "Save as new entry" refused because an entry, possibly the user's own earlier attempt, now holds the path. */
+export declare const RECREATE_TAKEN_MESSAGE = "An entry with this entry's name already exists, perhaps from your own earlier attempt, so it was not saved as a new entry. Your changes are still in the form: copy what you want to keep into that entry.";
+/** @internal Exported for tests. The save was refused as gone, and the check for a rename failed. */
+export declare const ENTRY_GONE_UNCHECKED_MESSAGE = "This entry was deleted or renamed since you opened it, so it was not saved, and the editor could not check which. Your changes are still in the form until the content list next refreshes and closes it: copy what you want to keep.";
+/** @internal Exported for tests. "Save as new entry" landed, but the content list does not show it yet. */
+export declare const RECREATED_NOT_LISTED_MESSAGE = "Saved as a new entry, but the content list doesn't show it yet. Reload the page in a moment to open it.";
+/** @internal Exported for tests. "Save as new entry" got no answer. */
+export declare const RECREATE_TIMED_OUT_MESSAGE = "Saving as a new entry may have gone through even though the server didn't answer. Choose \"Save as new entry\" to try again: if it went through, you'll be told an entry with this name already exists.";
 export interface UseDraftManagerOptions {
     branchName: string;
     selectedPath: string;
@@ -8,6 +26,12 @@ 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
@@ -17,6 +41,8 @@ export interface UseDraftManagerOptions {
      * conflict detection falls back entirely to saveEntry's token check.
      */
     getEntryVersion?: (contentId: string) => number | undefined;
+    /** Holds a version the server moved an entry to itself (useEntryManager's `adoptEntryVersion`). */
+    adoptEntryVersion?: (contentId: string, version: number) => void;
     setBusy: (busy: boolean) => void;
     /**
      * Fired (fire-and-forget) after a successful save. Lets callers refresh
@@ -25,6 +51,23 @@ export interface UseDraftManagerOptions {
      * instead of the stale label from the last entries fetch.
      */
     onSaved?: () => void;
+    /** A save was refused for field errors, which the form now shows. */
+    onSaveBlocked?: () => void;
+    /**
+     * Fired when drafts are thrown away for the server's copy: Discard (one entry, or every entry
+     * when `contentId` is undefined) and Reload. Anything built on the discarded draft, such as an
+     * Undo, no longer applies.
+     */
+    onDraftsReset?: (contentId?: string) => void;
+    /** Finds an entry a save reported gone under its new name (useEntryManager's `followMovedEntry`). */
+    followMovedEntry?: (entry: EditorEntry) => Promise<EditorEntry | undefined>;
+    /** Creates a deleted entry again from its draft (useEntryManager's `recreateEntry`). */
+    recreateEntry?: (entry: EditorEntry, value: FormValue) => Promise<EditorEntry | undefined>;
+}
+/** 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>;
@@ -40,12 +83,39 @@ export interface UseDraftManagerReturn {
         label: string;
     }>;
     handleSave: () => Promise<void>;
-    handleDiscardDrafts: () => void;
-    handleDiscardFileDraft: () => void;
-    handleReload: () => Promise<void>;
+    /** The entry a single Save is writing, while it is in flight. */
+    singleSaving: {
+        branch: string;
+        contentId: string;
+    } | null;
+    /** The last Save that landed; its `seq` rises with each, and the Save button says "Saved". */
+    lastSaved: {
+        branch: string;
+        contentId: string;
+        seq: number;
+    } | null;
+    /**
+     * Saves every entry with unsaved changes on the branch, one at a time. Undefined when a run or
+     * a single Save is already in flight, or the branch changed or the editor unmounted meanwhile.
+     */
+    handleSaveAll: () => Promise<SaveAllResult | undefined>;
+    /** Set while Save all runs. */
+    saveAllProgress: SaveAllProgress | null;
+    /** Whether Save all is running now, read at the moment of a click rather than a render. */
+    isSaveAllRunning: () => boolean;
+    handleDiscardDrafts: (returnFocusTo?: () => HTMLElement | null) => void;
+    /** `announce` toasts the discard, for a draft the form isn't showing (a read-only branch's). */
+    handleDiscardFileDraft: (returnFocusTo?: () => HTMLElement | null, options?: {
+        announce?: boolean;
+    }) => void;
+    handleReload: (returnFocusTo?: () => HTMLElement | null) => Promise<void>;
     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
@@ -54,6 +124,10 @@ export interface UseDraftManagerReturn {
      * errors disappear as fields are fixed.
      */
     fieldErrors: Record<string, string>;
+    /** True while the last write of drafts to localStorage failed. */
+    draftStorageFailed: boolean;
+    /** Moves loaded values, tokens and drafts onto the versions a submit's stamps left. */
+    applySubmitStamps: (stamped: readonly StampedEntry[]) => void;
 }
 /**
  * Custom hook for managing draft state (localStorage persistence, save/discard).