canopycms 0.7.0 → 0.8.0

package/dist/editor/hooks/useBranchManager.js

@@ -8,13 +8,15 @@ import { openConfirm } from '../utils/confirm-modal.js';
 import { focusReturnProps } from '../utils/focus-return.js';
 import { EDITOR_ACTIONS } from '../copy.js';
 import { notifications } from '@mantine/notifications';
-import { useApiClient } from '../context/index.js';
+import { useApiClient, useBranchSegments } from '../context/index.js';
 import { BRANCHES_KEY, fetchBranches, useBranchesData } from './useBranchesData.js';
 // branch-name, NOT branch or the '../../paths' barrel: both of those pull
 // node:fs/promises + node:path at the top level (path RESOLUTION helpers),
 // which breaks adopters' production `next build` of the editor bundle.
 // paths/branch-name.ts is the dependency-free home of sanitizeBranchName.
 import { sanitizeBranchName } from '../../paths/branch-name.js';
+import { exactBranchName, exactBranchSegment } from '../../paths/validation.js';
+import { branchAddress, branchUrlName, displayBranchName, requestSegments, unlistedSegment, resolveListedBranch, } from '../branch-names.js';
 import { RetryToastMessage } from '../components/RetryToastMessage.js';
 import { isNonApiResponse } from '../../api/client.js';
 import { isGatewayFailure, isUnanswered, UnansweredError } from '../unanswered.js';
@@ -112,7 +114,7 @@ const showSubmitConfirmation = (branchName, unsaved, onConfirm, onDismiss, retur
     const leftOut = unsaved && unsaved.count > 0 ? unsaved : undefined;
     openConfirm({
         title: EDITOR_ACTIONS.submitForReview,
-        children: (_jsxs(Stack, { gap: "sm", children: [leftOut && (_jsxs(Alert, { color: "yellow", icon: _jsx(IconAlertTriangle, { size: 16 }), title: `${leftOut.count} ${leftOut.count === 1 ? "entry has unsaved changes that won't" : "entries have unsaved changes that won't"} be submitted`, "data-testid": "submit-unsaved-warning", children: [describeUnsaved(leftOut), " To include them, cancel and save first. If you submit now, those changes stay unsaved on this branch while it is in review."] })), _jsx(Text, { size: "sm", style: { whiteSpace: 'pre-line' }, children: `Submit "${branchName}" for review?\n\nThis will:\n• Create a pull request for review\n• Change the branch status to "In review"\n• Notify reviewers of pending changes` })] })),
+        children: (_jsxs(Stack, { gap: "sm", children: [leftOut && (_jsxs(Alert, { color: "yellow", icon: _jsx(IconAlertTriangle, { size: 16 }), title: `${leftOut.count} ${leftOut.count === 1 ? "entry has unsaved changes that won't" : "entries have unsaved changes that won't"} be submitted`, "data-testid": "submit-unsaved-warning", children: [describeUnsaved(leftOut), " To include them, cancel and save first. If you submit now, those changes stay unsaved on this branch while it is in review."] })), _jsx(Text, { size: "sm", style: { whiteSpace: 'pre-line' }, children: `Submit “${branchName}” for review?\n\nThis will:\n• Create a pull request for review\n• Change the branch status to “In review”\n• Notify reviewers of pending changes` })] })),
         labels: {
             confirm: leftOut ? 'Submit anyway' : EDITOR_ACTIONS.submitForReview,
             cancel: 'Cancel',
@@ -143,12 +145,12 @@ export function withdrawPullRequestBullet(pr) {
 const showWithdrawConfirmation = (branchName, pr, onConfirm, onDismiss, returnFocusTo) => {
     const bullets = [
         withdrawPullRequestBullet(pr),
-        'Change the branch status back to "editing"',
+        'Change the branch status back to “editing”',
         'Remove from review queue',
     ].filter((b) => b !== undefined);
     openConfirm({
         title: EDITOR_ACTIONS.withdrawFromReview,
-        children: (_jsx(Text, { size: "sm", style: { whiteSpace: 'pre-line' }, children: `Withdraw "${branchName}" from review?\n\nThis will:\n${bullets.map((b) => `• ${b}`).join('\n')}` })),
+        children: (_jsx(Text, { size: "sm", style: { whiteSpace: 'pre-line' }, children: `Withdraw “${branchName}” from review?\n\nThis will:\n${bullets.map((b) => `• ${b}`).join('\n')}` })),
         labels: { confirm: EDITOR_ACTIONS.withdrawFromReview, cancel: 'Cancel' },
         confirmProps: { color: 'orange', 'data-testid': 'confirm-withdraw-branch' },
         ...confirmModalHandlers(onConfirm, onDismiss),
@@ -201,7 +203,7 @@ const showDeleteConfirmation = (branchName, pr, onConfirm, onDismiss) => {
     ].filter((b) => b !== undefined);
     openConfirm({
         title: 'Delete branch',
-        children: (_jsx(Text, { size: "sm", style: { whiteSpace: 'pre-line' }, children: `Delete "${branchName}"?\n\nThis will:\n${bullets.map((b) => `• ${b}`).join('\n')}\n\nThis cannot be undone.` })),
+        children: (_jsx(Text, { size: "sm", style: { whiteSpace: 'pre-line' }, children: `Delete “${branchName}”?\n\nThis will:\n${bullets.map((b) => `• ${b}`).join('\n')}\n\nThis cannot be undone.` })),
         labels: { confirm: 'Delete branch', cancel: 'Cancel' },
         // data-testid is load-bearing, not decoration: the e2e helper
         // (apps/test-app/e2e/fixtures/branch-page.ts's deleteBranch) already
@@ -227,6 +229,15 @@ function mergePendingBranches(listed, pending) {
     const missing = pending.filter((p) => !listedNames.has(p.branch.name));
     return missing.length === 0 ? listed : [...listed, ...missing.map((p) => p.branch)];
 }
+/**
+ * What a request sends for `name`, a full name the listing no longer holds: the exact form when a
+ * listed short name is `name`, which would open that namespace branch instead, else as unlisted.
+ */
+function unlistedName(listed, name) {
+    return listed.some((b) => b.name !== name && displayBranchName(b) === name)
+        ? exactBranchSegment(name)
+        : unlistedSegment(name);
+}
 /**
  * Applies one received listing to the pending branches: drops those it arrived
  * past the grace window for, and takes the listing's copy of the rest. Written
@@ -258,10 +269,31 @@ function reconcilePendingBranches(pending, listed, receivedAt) {
 export function useBranchManager(options) {
     const apiClient = useApiClient();
     const { cache, mutate: globalMutate } = useSWRConfig();
-    const [branchName, setBranchName] = useState(options.initialBranch);
+    // The open branch. Once `exact`, `name` is the listed branch's full name, matched only by that
+    // name: a listing that changes which branch a short name opens never moves it. Until then
+    // `name` is what a URL, link, history entry or card gave, which `resolveListedBranch` resolves
+    // once a listing holds it.
+    const [open, setOpen] = useState({ name: options.initialBranch, exact: false });
+    const setBranchName = useCallback((name) => setOpen({ name, exact: false }), []);
+    const openExactly = useCallback((name) => setOpen({ name, exact: true }), []);
     const { data: branchesData, error: branchesError, isValidating: branchesIsValidating, } = useBranchesData(apiClient);
     const [pendingBranches, setPendingBranches] = useState([]);
     const branches = useMemo(() => mergePendingBranches(branchesData?.branches ?? [], pendingBranches), [branchesData, pendingBranches]);
+    const arriving = open.exact ? undefined : resolveListedBranch(branches, open.name);
+    const branchName = arriving?.name ?? open.name;
+    const resolved = open.exact || !!arriving;
+    const currentBranch = open.exact ? branches.find((b) => b.name === open.name) : arriving;
+    const currentBranchName = currentBranch?.name;
+    // A listed branch by `requestSegments`; the open branch, once the listing drops it, as
+    // `unlistedName` does; any other name by the client's own lookup (`unlistedSegment`).
+    const segments = useMemo(() => {
+        const table = requestSegments(branches);
+        if (resolved && branchName && !table.has(branchName)) {
+            table.set(branchName, unlistedName(branches, branchName));
+        }
+        return table;
+    }, [branches, resolved, branchName]);
+    useBranchSegments(segments);
     const addCreatedBranch = useCallback((branch) => {
         setPendingBranches((prev) => [
             ...prev.filter((p) => p.branch.name !== branch.name),
@@ -296,10 +328,9 @@ export function useBranchManager(options) {
     }, [branchesData]);
     // Adopt the server's default branch once data arrives, if nothing pinned one.
     useEffect(() => {
-        if (!branchName && branchesData?.defaultBranch) {
-            setBranchName(branchesData.defaultBranch);
-        }
-    }, [branchesData, branchName]);
+        if (!branchName && branchesData?.defaultBranch)
+            openExactly(branchesData.defaultBranch);
+    }, [branchesData, branchName, openExactly]);
     // One toast, replaced on each failure (a shown id ignores `show`); sticky because the editor
     // cannot function without the branch list.
     const showBranchesLoadFailed = (message) => {
@@ -334,18 +365,19 @@ export function useBranchManager(options) {
         options.setBusy(branchesIsValidating);
         // eslint-disable-next-line react-hooks/exhaustive-deps -- options is a new object every Editor.tsx render; only setBusy (a stable setState) matters here
     }, [branchesIsValidating, options.setBusy]);
-    // Exact match first; fall back to comparing sanitized forms so a legacy
-    // deep-link carrying the raw, unsanitized name (e.g. "?branch=feature%2Fx"
-    // from before a branch was created, or from an old bookmark) still
-    // resolves to the branch the server actually persisted (e.g. "feature-x").
-    const currentBranch = branches.find((b) => b.name === branchName) ??
-        branches.find((b) => b.name === sanitizeBranchName(branchName));
+    // Resolved once, as it arrives: from here the full name is the branch, and drafts, comments and
+    // everything else keyed per branch see one name for it.
+    useEffect(() => {
+        if (!open.exact && arriving)
+            openExactly(arriving.name);
+    }, [open, arriving, openExactly]);
     const branchSummaries = useMemo(() => {
         return branches.map((b) => {
-            const branchComments = b.name === branchName ? options.comments : [];
+            const branchComments = b.name === currentBranchName ? options.comments : [];
             const unresolvedCount = branchComments.filter((t) => !t.resolved).length;
             return {
                 name: b.name,
+                shortName: b.shortName,
                 status: b.status,
                 createdBy: b.createdBy,
                 updatedAt: b.updatedAt,
@@ -386,7 +418,7 @@ export function useBranchManager(options) {
                 submitBlocked: b.submitBlocked ?? true,
             };
         });
-    }, [branches, branchName, options.comments]);
+    }, [branches, currentBranchName, options.comments]);
     // Explicit reload: always issues a fresh, independent fetch (raw call, not
     // SWR's `mutate()` revalidate path) so callers requesting a reload right
     // after mount aren't coalesced against the still-in-flight automatic load
@@ -416,11 +448,38 @@ export function useBranchManager(options) {
     };
     // The confirm dialogs' handlers run long after the render that opened them, so they read
     // these at confirm time rather than from that render's closure.
-    const latest = useRef({ branchName, branches, branchesData });
-    latest.current = { branchName, branches, branchesData };
-    // A legacy deep link can carry the raw form of a listed name; the actions key, look up and
-    // send the listed name, resolved the way `currentBranch` resolves it.
-    const listedName = (name) => latest.current.branches.some((b) => b.name === name) ? name : sanitizeBranchName(name);
+    const latest = useRef({ branchName, resolved, branches, branchesData });
+    latest.current = { branchName, resolved, branches, branchesData };
+    // A card, deep link or URL can carry a short name, an exact form or the raw form of a listed
+    // name; the actions resolve it once, the way an arriving name resolves, then key, look up and
+    // send the listed name.
+    const listedBranch = (name) => resolveListedBranch(latest.current.branches, name);
+    const listedName = (name) => listedBranch(name)?.name ?? sanitizeBranchName(name);
+    // What an action sends for `name`, resolved when it was asked for: the listing can drop the
+    // branch while its dialog is open.
+    const sendName = (name) => {
+        const listed = latest.current.branches;
+        return listed.some((b) => b.name === name) ? name : unlistedName(listed, name);
+    };
+    // The listed name of the open branch: the state itself once resolved.
+    const openListedName = () => latest.current.resolved ? latest.current.branchName : listedName(latest.current.branchName);
+    const namesBranch = (name, branch) => {
+        const found = listedBranch(name);
+        return found ? found.name === branch : sanitizeBranchName(name) === sanitizeBranchName(branch);
+    };
+    // What a dialog or toast calls the listed branch `name`; the keys, lookups and requests keep `name`.
+    const shownName = (name) => {
+        const found = latest.current.branches.find((b) => b.name === name);
+        return found ? displayBranchName(found) : name;
+    };
+    // The `?branch=` value for `name`, a full name or a card's address: the URL form of the branch
+    // listed by that full name, else `name` as given.
+    const urlBranchName = (name) => {
+        const listed = latest.current.branches;
+        const full = exactBranchName(name) ?? name;
+        const found = listed.find((b) => b.name === full);
+        return found ? branchUrlName(listed, found) : name;
+    };
     const pullRequestOf = (name) => {
         const b = latest.current.branches.find((x) => x.name === name);
         return { pullRequestNumber: b?.pullRequestNumber, pullRequestState: b?.pullRequestState };
@@ -564,7 +623,7 @@ export function useBranchManager(options) {
         return singleFlight('submit', branchNameToSubmit, async () => {
             // Drafts belong to the open branch, so only its submit can leave edits behind. Without
             // that check the dialog opens in this same tick.
-            const checking = branchNameToSubmit === listedName(latest.current.branchName)
+            const checking = branchNameToSubmit === openListedName()
                 ? options.getUnsaved?.().catch((err) => {
                     console.error(err);
                     return undefined;
@@ -575,7 +634,7 @@ export function useBranchManager(options) {
                 options.setBusy(true);
             const unsaved = checking && (await checking.finally(() => options.setBusy(false)));
             return new Promise((resolve, reject) => {
-                showSubmitConfirmation(branchNameToSubmit, unsaved, async () => {
+                showSubmitConfirmation(shownName(branchNameToSubmit), unsaved, async () => {
                     // A listing that arrived while the dialog was open may show the branch already
                     // submitted; submitting it again would only fail.
                     const listed = latest.current.branches.find((b) => b.name === branchNameToSubmit);
@@ -589,13 +648,13 @@ export function useBranchManager(options) {
                     }
                     options.setBusy(true);
                     try {
-                        const result = await apiClient.workflow.submit({ branch: branchNameToSubmit }, 
+                        const result = await apiClient.workflow.submit({ branch: sendName(branchNameToSubmit) }, 
                         // The PR body links back here; the server checks the host (editor-url.ts).
                         { editorUrl: `${window.location.origin}${window.location.pathname}` });
                         if (!result.ok)
                             throw actionError(result, 'Failed to submit branch');
                         const stamped = result.data?.stamped;
-                        if (stamped && branchNameToSubmit === listedName(latest.current.branchName)) {
+                        if (stamped && branchNameToSubmit === openListedName()) {
                             options.onStamped?.(stamped);
                         }
                         notifications.show({
@@ -623,11 +682,11 @@ export function useBranchManager(options) {
     const handleWithdraw = (requested, returnFocusTo) => {
         const branchNameToWithdraw = listedName(requested);
         return singleFlight('withdraw', branchNameToWithdraw, () => new Promise((resolve, reject) => {
-            showWithdrawConfirmation(branchNameToWithdraw, pullRequestOf(branchNameToWithdraw), async () => {
+            showWithdrawConfirmation(shownName(branchNameToWithdraw), pullRequestOf(branchNameToWithdraw), async () => {
                 options.setBusy(true);
                 try {
                     const result = await apiClient.workflow.withdraw({
-                        branch: branchNameToWithdraw,
+                        branch: sendName(branchNameToWithdraw),
                     });
                     if (!result.ok)
                         throw actionError(result, 'Failed to withdraw branch');
@@ -649,11 +708,11 @@ export function useBranchManager(options) {
     const handleApprove = (requested, returnFocusTo) => {
         const branchNameToApprove = listedName(requested);
         return singleFlight('approve', branchNameToApprove, () => new Promise((resolve, reject) => {
-            showApproveConfirmation(branchNameToApprove, pullRequestOf(branchNameToApprove), async () => {
+            showApproveConfirmation(shownName(branchNameToApprove), pullRequestOf(branchNameToApprove), async () => {
                 options.setBusy(true);
                 try {
                     const result = await apiClient.workflow.approve({
-                        branch: branchNameToApprove,
+                        branch: sendName(branchNameToApprove),
                     });
                     if (!result.ok)
                         throw actionError(result, 'Failed to approve branch', true);
@@ -666,7 +725,7 @@ export function useBranchManager(options) {
                 catch (err) {
                     await reportReviewFailure(err, 'approve', branchNameToApprove, {
                         fallback: 'Failed to approve branch',
-                        label: `${EDITOR_ACTIONS.approve} "${branchNameToApprove}"`,
+                        label: `${EDITOR_ACTIONS.approve} “${shownName(branchNameToApprove)}”`,
                         retry: () => void handleApprove(branchNameToApprove, returnFocusTo).catch(() => { }),
                     });
                     reject(err);
@@ -682,7 +741,7 @@ export function useBranchManager(options) {
         // A draft is for the review cycle it was typed in; a branch already out of review starts clean.
         dropDraftsOutOfReview(latest.current.branches.filter((b) => b.name === branchNameForChanges));
         return singleFlight('request-changes', branchNameForChanges, () => new Promise((resolve) => {
-            showRequestChangesConfirmation(branchNameForChanges, pullRequestOf(branchNameForChanges), noteDrafts.current.get(branchNameForChanges) ?? '', (draft) => {
+            showRequestChangesConfirmation(shownName(branchNameForChanges), pullRequestOf(branchNameForChanges), noteDrafts.current.get(branchNameForChanges) ?? '', (draft) => {
                 if (draft)
                     noteDrafts.current.set(branchNameForChanges, draft);
                 else
@@ -690,7 +749,7 @@ export function useBranchManager(options) {
             }, async (note) => {
                 options.setBusy(true);
                 try {
-                    const result = await apiClient.workflow.requestChanges({ branch: branchNameForChanges }, { note: note.trim() || undefined });
+                    const result = await apiClient.workflow.requestChanges({ branch: sendName(branchNameForChanges) }, { note: note.trim() || undefined });
                     if (!result.ok)
                         throw actionError(result, 'Failed to request changes', true);
                     noteDrafts.current.delete(branchNameForChanges);
@@ -714,7 +773,7 @@ export function useBranchManager(options) {
                 catch (err) {
                     await reportReviewFailure(err, 'request-changes', branchNameForChanges, {
                         fallback: 'Failed to request changes',
-                        label: `${EDITOR_ACTIONS.requestChanges} on "${branchNameForChanges}"`,
+                        label: `${EDITOR_ACTIONS.requestChanges} on “${shownName(branchNameForChanges)}”`,
                         note: note.trim() || undefined,
                         retry: () => void handleRequestChanges(branchNameForChanges, returnFocusTo).catch(() => { }),
                         check: REQUEST_CHANGES_CHECK,
@@ -733,32 +792,38 @@ export function useBranchManager(options) {
             }, () => resolve(), returnFocusTo);
         }));
     };
-    /** After a delete: drop it from the created-branch overlay, and leave it if it is open. */
-    const leaveDeletedBranch = (deleted, fresh) => {
+    /**
+     * After a delete: drop it from the created-branch overlay, and leave it if it is open. A name
+     * still unresolved is resolved against the listing from before the delete (`listedBefore`),
+     * since the deleted branch is no longer listed to resolve against.
+     */
+    const leaveDeletedBranch = (deleted, listedBefore, fresh) => {
         forgetCreatedBranch(deleted);
-        // Matched the way `currentBranch` resolves a name, since the deleted branch is no longer
-        // listed to resolve against.
-        const open = latest.current.branchName;
-        if (open === deleted || sanitizeBranchName(open) === deleted) {
+        const { branchName: openName, resolved: openResolved } = latest.current;
+        const openListed = openResolved
+            ? openName
+            : (resolveListedBranch(listedBefore, openName)?.name ?? sanitizeBranchName(openName));
+        if (openListed === deleted) {
             // Nothing is left to keep, so no unsaved-changes prompt. With no default known yet, the
             // empty name lets the default-branch adoption effect pick it.
-            setBranchName(fresh?.defaultBranch ?? latest.current.branchesData?.defaultBranch ?? '');
+            openExactly(fresh?.defaultBranch ?? latest.current.branchesData?.defaultBranch ?? '');
         }
     };
     const handleDelete = (requested) => {
         const branchNameToDelete = listedName(requested);
+        const listedBefore = latest.current.branches;
         return singleFlight('delete', branchNameToDelete, () => new Promise((resolve) => {
-            showDeleteConfirmation(branchNameToDelete, pullRequestOf(branchNameToDelete), async () => {
+            showDeleteConfirmation(shownName(branchNameToDelete), pullRequestOf(branchNameToDelete), async () => {
                 options.setBusy(true);
                 try {
                     const result = await apiClient.branches.delete({
-                        branch: branchNameToDelete,
+                        branch: sendName(branchNameToDelete),
                     });
                     // The API's own 404: the branch is already gone, by an earlier unanswered delete or
                     // another user's.
                     if (!result.ok && result.status === 404 && !isNonApiResponse(result)) {
                         notifications.show({ message: 'Branch deleted', color: 'green' });
-                        leaveDeletedBranch(branchNameToDelete, await reloadBranches());
+                        leaveDeletedBranch(branchNameToDelete, listedBefore, await reloadBranches());
                         return;
                     }
                     if (!result.ok)
@@ -771,7 +836,7 @@ export function useBranchManager(options) {
                             autoClose: false,
                         }
                         : { message: 'Branch deleted', color: 'green' });
-                    leaveDeletedBranch(branchNameToDelete, await reloadBranches());
+                    leaveDeletedBranch(branchNameToDelete, listedBefore, await reloadBranches());
                 }
                 catch (err) {
                     if (!isUnanswered(err)) {
@@ -784,7 +849,7 @@ export function useBranchManager(options) {
                     const listed = mergePendingBranches(fresh?.branches ?? [], recent).some((b) => sanitizeBranchName(b.name) === sanitizeBranchName(branchNameToDelete));
                     if (fresh && !listed) {
                         notifications.show({ message: 'Branch deleted', color: 'green' });
-                        leaveDeletedBranch(branchNameToDelete, fresh);
+                        leaveDeletedBranch(branchNameToDelete, listedBefore, fresh);
                     }
                     else {
                         showOutcomeUnknown('Delete branch');
@@ -803,24 +868,47 @@ export function useBranchManager(options) {
     };
     // The editor's own page; a Back off it to a page of the host leaves that page's URL alone.
     const editorPathRef = useRef(typeof window === 'undefined' ? '' : window.location.pathname);
+    const shownBranch = currentBranch ? branchUrlName(branches, currentBranch) : undefined;
+    // Each Back or Forward, which can arrive at an entry naming this branch in another form.
+    const [historyMoves, setHistoryMoves] = useState(0);
     useEffect(() => {
         if (typeof window === 'undefined')
             return;
-        if (!branchName || window.location.pathname !== editorPathRef.current)
+        const moved = () => setHistoryMoves((n) => n + 1);
+        window.addEventListener('popstate', moved);
+        return () => window.removeEventListener('popstate', moved);
+    }, []);
+    const seenMovesRef = useRef(historyMoves);
+    // Written once the listing resolves the branch, so a link's own form stays until then; a form
+    // other than the shown one (the full name, a raw name) is replaced, never pushed. After a Back
+    // or Forward only a form of this branch is: one naming another is the entry manager's switch.
+    useEffect(() => {
+        const popped = seenMovesRef.current !== historyMoves;
+        seenMovesRef.current = historyMoves;
+        if (typeof window === 'undefined')
+            return;
+        if (!shownBranch || window.location.pathname !== editorPathRef.current)
             return;
         const url = new URL(window.location.href);
-        const current = url.searchParams.get('branch');
-        if (current !== branchName) {
-            url.searchParams.set('branch', branchName);
-            writeEditorUrl(url.toString(), false);
-        }
-    }, [branchName]);
+        const named = url.searchParams.get('branch');
+        if (named === shownBranch)
+            return;
+        if (popped && named !== null && listedBranch(named)?.name !== latest.current.branchName)
+            return;
+        url.searchParams.set('branch', shownBranch);
+        writeEditorUrl(url.toString(), false);
+    }, [shownBranch, historyMoves]);
     return {
         branchName,
         setBranchName,
         branches,
         branchSummaries,
         currentBranch,
+        currentAddress: currentBranch ? branchAddress(branches, currentBranch) : branchName,
+        listedBranch,
+        listedName,
+        namesBranch,
+        urlBranchName,
         branchesLoadFailed: !!branchesError && !branchesData,
         branchesLoaded: !!branchesData,
         addCreatedBranch,

package/dist/editor/hooks/useDraftManager.js

@@ -335,9 +335,13 @@ export function useDraftManager(options) {
     // Tracks which storage key the current in-memory `drafts` were loaded for.
     // Lags one render behind a branch switch (it only updates once `drafts`
     // itself has been reset/restored for the new key), which is what lets the
-    // persist effect below detect and skip the stale write.
-    const draftsStorageKeyRef = useRef(storageKey);
+    // persist effect below detect and skip the stale write. Null while `drafts` is
+    // still the empty set it started as, so a load stores nothing under its first key.
+    const initialDraftsRef = useRef(drafts);
+    const draftsStorageKeyRef = useRef(null);
     useEffect(() => {
+        if (drafts === initialDraftsRef.current && Object.keys(drafts).length === 0)
+            return;
         draftsStorageKeyRef.current = storageKey;
     }, [drafts]);
     // Keep the per-draft base versions in step with `drafts`.

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

@@ -42,10 +42,26 @@ export interface UseEntryManagerOptions {
     setBusy: (busy: boolean) => void;
     /** The bar's row: a failed load is toasted after 'loading' ends, and never on 'not-available'. */
     branchBarState?: BranchBarStatus['value'];
-    /** Switches to the branch a Back or Forward reached; rejects when the switch does not happen. */
-    switchBranch?: (branch: string) => Promise<void>;
+    /**
+     * Switches to the branch a Back or Forward reached; rejects when the switch does not happen,
+     * which it must not once `superseded()` holds: a later move has the URL.
+     */
+    switchBranch?: (branch: string, superseded: () => boolean) => Promise<void>;
+    /**
+     * Whether `url`, a `?branch=` value, opens the branch `branchName` names, as a short name opens
+     * its namespace branch. A change of `branchName` from a branch whose URL form opens the next one
+     * is no switch: the open entry stays. Defaults to comparing sanitized forms.
+     */
+    sameBranch?: (url: string, branchName: string) => boolean;
+    /** What `?branch=` carries for a branch (its short name); defaults to the name as given. */
+    urlBranchName?: (branch: string) => string;
     /** Called when a Back or Forward has opened another entry. */
     onHistoryRestore?: () => void;
+    /**
+     * Called as each explicit refresh starts: every save, create, rename, delete and schema change
+     * refreshes the entries, so what reads the same branch state reloads here.
+     */
+    onContentRefresh?: (branch: string) => void;
 }
 export interface UseEntryManagerReturn {
     selectedPath: string;

package/dist/editor/hooks/useEntryManager.js

@@ -1,7 +1,7 @@
 import { createElement, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import useSWR, { useSWRConfig } from 'swr';
 import { notifications } from '@mantine/notifications';
-import { buildWritePayload, normalizeContentPayload, resolveHomeEntry } from '../editor-utils.js';
+import { buildWritePayload, normalizeContentPayload, resolveHomeEntry, withPreviewBranch, } from '../editor-utils.js';
 import { isDataOnlyFormat } from '../../utils/format.js';
 import { withTitleAtPath } from '../../utils/title-field.js';
 import { getErrorMessage } from '../../utils/error.js';
@@ -49,6 +49,8 @@ export class EntrySchemaUnavailableError extends Error {
         this.name = 'EntrySchemaUnavailableError';
     }
 }
+/** A legacy name and its sanitized form are one branch. */
+const sameSanitizedName = (a, b) => sanitizeBranchName(a) === sanitizeBranchName(b);
 // 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
@@ -196,6 +198,11 @@ export function useEntryManager(options) {
     // the user switches mid-flight, which is exactly when the check matters).
     const currentBranchRef = useRef(options.branchName);
     currentBranchRef.current = options.branchName;
+    const sameBranchRef = useRef(options.sameBranch ?? sameSanitizedName);
+    sameBranchRef.current = options.sameBranch ?? sameSanitizedName;
+    const urlBranchNameRef = useRef(options.urlBranchName);
+    urlBranchNameRef.current = options.urlBranchName;
+    const urlBranchOf = (branch) => urlBranchNameRef.current?.(branch) ?? branch;
     // Read by the selection check, which runs only when the entries or the selection change.
     const resolvePreviewRouteRef = useRef(options.resolvePreviewRoute);
     resolvePreviewRouteRef.current = options.resolvePreviewRoute;
@@ -247,7 +254,16 @@ export function useEntryManager(options) {
         walk(collectionsState);
         return map;
     }, [collectionsState]);
-    const currentEntry = useMemo(() => entriesState.find((e) => e.path === selectedPath), [entriesState, selectedPath]);
+    // The entries keep the URL form of their fetch's time, which the listing can change since; the
+    // frame keys on `src`, so its branch is the current form.
+    const previewBranch = urlBranchOf(options.branchName);
+    const currentEntry = useMemo(() => {
+        const entry = entriesState.find((e) => e.path === selectedPath);
+        const previewSrc = entry?.previewSrc && previewBranch
+            ? withPreviewBranch(entry.previewSrc, previewBranch)
+            : entry?.previewSrc;
+        return entry && previewSrc !== entry.previewSrc ? { ...entry, previewSrc } : entry;
+    }, [entriesState, selectedPath, previewBranch]);
     // Slugs already used within the collection currently open in the create
     // modal. Collision is keyed on collectionPath + slug only (not entryType):
     // ContentStore resolves an existing entry by slug alone within a
@@ -441,6 +457,7 @@ export function useEntryManager(options) {
     const refreshContent = async (branch = options.branchName) => {
         if (!branch)
             return { entries: [], collections: [] };
+        options.onContentRefresh?.(branch);
         const seq = claimRefreshSeq(branch);
         const fetched = await fetchEntriesAndSchema(apiClient, branch, {
             resolvePreviewSrc: options.resolvePreviewSrc,
@@ -597,18 +614,28 @@ export function useEntryManager(options) {
     // Clear selection when branch changes (reactive pattern). Data loading
     // itself is handled below by the SWR-backed fetch -- this effect only
     // owns the "clear stale selection" side effect.
+    // The shown branch's URL form, refreshed while it stays shown: a full name can be another
+    // branch's short name, and only the URL form says which branch it is against a later listing.
+    const shownBranchRef = useRef({ name: options.branchName, url: urlBranchOf(options.branchName) });
+    if (shownBranchRef.current.name === options.branchName) {
+        shownBranchRef.current.url = urlBranchOf(options.branchName);
+    }
     useEffect(() => {
         if (!options.branchName)
             return;
+        const previous = shownBranchRef.current.url;
+        shownBranchRef.current = { name: options.branchName, url: urlBranchOf(options.branchName) };
         // On initial mount, preserve the initial selection from URL
-        // On subsequent branch changes, clear selection
+        // On a later switch to another branch, clear selection
         if (isInitialMount.current) {
             isInitialMount.current = false;
         }
-        else {
+        else if (!sameBranchRef.current(previous, options.branchName)) {
             const restored = entryAfterBranchChangeRef.current;
             entryAfterBranchChangeRef.current = undefined;
-            const entry = restored?.branch === options.branchName ? restored.entry : undefined;
+            const entry = restored && sameBranchRef.current(restored.branch, options.branchName)
+                ? restored.entry
+                : undefined;
             noEntryRequested.current = entry === '';
             setSelectedPath(entry ?? '');
             if (entry !== undefined) {
@@ -782,7 +809,7 @@ export function useEntryManager(options) {
             return;
         if (window.location.pathname !== editorPathRef.current)
             return;
-        writeEditorUrl(entryUrl(selectedPath, noEntryRequested.current, currentBranchRef.current), push);
+        writeEditorUrl(entryUrl(selectedPath, noEntryRequested.current, urlBranchOf(currentBranchRef.current)), push);
     }, [selectedPath]);
     const entriesRef = useRef(entriesState);
     entriesRef.current = entriesState;
@@ -803,8 +830,7 @@ export function useEntryManager(options) {
             const entry = params.get('entry');
             const branch = params.get('branch');
             const current = currentBranchRef.current;
-            // A legacy name and its sanitized form are one branch; a switch would key drafts by the other.
-            if (branch && sanitizeBranchName(branch) !== sanitizeBranchName(current)) {
+            if (branch && !sameBranchRef.current(branch, current)) {
                 const move = historyMovesRef.current;
                 const stay = () => {
                     if (move !== historyMovesRef.current)
@@ -812,7 +838,7 @@ export function useEntryManager(options) {
                     if (moved)
                         undoHistoryMove(moved);
                     else {
-                        const url = entryUrl(selectedPathRef.current, noEntryRequested.current, currentBranchRef.current);
+                        const url = entryUrl(selectedPathRef.current, noEntryRequested.current, urlBranchOf(currentBranchRef.current));
                         writeEditorUrl(url, false);
                     }
                 };
@@ -824,7 +850,7 @@ export function useEntryManager(options) {
                 entryAfterBranchChangeRef.current = { branch, entry };
                 if (!hasSyncedFromUrl.current)
                     initialUrlEntry.current = entry;
-                switchBranch(branch).catch(() => {
+                switchBranch(branch, () => move !== historyMovesRef.current).catch(() => {
                     if (move === historyMovesRef.current)
                         entryAfterBranchChangeRef.current = undefined;
                     stay();

package/dist/editor/utils/editor-errors.d.ts

@@ -1,7 +1,10 @@
 /** Where in the editor an error was caught, for the log line and the copied details. */
 export interface EditorErrorContext {
-    /** `editor` for the crash screen, `field` for a field boundary, `rich-text` for MDXEditor. */
-    boundary: 'editor' | 'field' | 'rich-text';
+    /**
+     * `editor` for the crash screen, `field` for a field boundary, `rich-text` for MDXEditor,
+     * `changes` for the "Show changes" drawer.
+     */
+    boundary: 'editor' | 'field' | 'rich-text' | 'changes';
     /** The field's canopy path, for a field or rich-text boundary. */
     fieldPath?: string;
     /** React's component stack, when React supplied one. */