canopycms 0.0.67 → 0.0.68-int.100

package/dist/editor/hooks/create-branch-request.js

@@ -0,0 +1,52 @@
+import { isCreatorsRecentBranch } from '../../api/branch-create-window.js';
+import { isNonApiResponse } from '../../api/client.js';
+import { sanitizeBranchName } from '../../paths/branch-name.js';
+/** @internal Exported for tests. Past the 60 s a Lambda behind CloudFront gets, so its 504 lands first. */
+export const CREATE_BRANCH_DEADLINE_MS = 90_000;
+/** @internal Exported for tests. */
+export const CREATE_TIMED_OUT_MESSAGE = "Creating the branch didn't finish (the server timed out). It's safe to try again.";
+const DEADLINE = Symbol('deadline');
+/**
+ * Create a branch. Past the deadline, after an error page from in front of the API, or after a
+ * busy 503 the branch may exist anyway, so the branch list decides; retrying is safe because a
+ * create publishes the whole branch or nothing. `userId` is the current user, the only creator
+ * whose listed branch can be this create's result.
+ */
+export async function requestBranchCreate(apiClient, body, userId, deadlineMs = CREATE_BRANCH_DEADLINE_MS) {
+    let timer;
+    const deadline = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(DEADLINE), deadlineMs);
+    });
+    const result = await Promise.race([apiClient.branches.create(body), deadline]).finally(() => clearTimeout(timer));
+    if (result === DEADLINE)
+        return settle(apiClient, body.branch, userId, CREATE_TIMED_OUT_MESSAGE);
+    if (result.ok)
+        return { kind: 'created', branch: result.data?.branch };
+    if (isNonApiResponse(result))
+        return settle(apiClient, body.branch, userId, CREATE_TIMED_OUT_MESSAGE);
+    const message = result.error || 'Failed to create branch';
+    return result.status === 503
+        ? settle(apiClient, body.branch, userId, message)
+        : { kind: 'failed', message };
+}
+/** A same-named branch the server would not answer this create with is a name conflict. */
+async function settle(apiClient, requested, userId, message) {
+    const listed = await findListedBranch(apiClient, requested);
+    if (!listed)
+        return { kind: 'failed', message };
+    if (isCreatorsRecentBranch(listed, userId))
+        return { kind: 'created', branch: listed };
+    return { kind: 'failed', message: `A branch named "${listed.name}" already exists` };
+}
+async function findListedBranch(apiClient, requested) {
+    const name = sanitizeBranchName(requested);
+    try {
+        const listing = await apiClient.branches.list();
+        if (!listing.ok)
+            return undefined;
+        return listing.data?.branches.find((branch) => sanitizeBranchName(branch.name) === name);
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -1,17 +1,28 @@
+import type { BranchListItem } from '../../api/branch.js';
+import type { UnsavedSummary } from './useDraftManager.js';
 export interface UseBranchActionsOptions {
     branchName: string;
     setBranchName: (name: string) => void;
-    isAnyDirty: () => boolean;
+    /** From useDraftManager's `resolveUnsaved`: what a branch-level action would leave behind. */
+    getUnsaved: () => Promise<UnsavedSummary>;
     onReloadBranches: () => Promise<void>;
+    /** Receives the branch the server just created, so it can be shown before any listing includes it. */
+    onBranchCreated: (branch: BranchListItem) => void;
     onBranchSwitch?: (branch: string) => void;
+    /** The current user; a create the server never answered adopts only a listed branch they made. */
+    userId?: string;
 }
 export interface UseBranchActionsReturn {
     handleBranchChange: (branch: string | null) => Promise<void>;
+    /** True when nothing is unsaved or the user accepted the warning. Run before any in-flight UI. */
+    confirmCreate: () => Promise<boolean>;
     handleCreateBranch: (branch: {
         name: string;
         title?: string;
         description?: string;
-    }) => Promise<void>;
+    }) => Promise<boolean>;
+    /** True while the unsaved-changes confirm is on screen. */
+    confirmOpen: boolean;
 }
 /**
  * Custom hook for branch navigation actions with dirty check support.

package/dist/editor/hooks/useBranchActions.js

@@ -1,13 +1,25 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
 import { modals } from '@mantine/modals';
 import { notifications } from '@mantine/notifications';
 import { Text } from '@mantine/core';
 import { useApiClient } from '../context/index.js';
+import { requestBranchCreate } from './create-branch-request.js';
+const MAX_LISTED_LABELS = 5;
+/** "Unsaved changes in: A, B." */
+const describeUnsaved = ({ labels }) => {
+    if (labels.length === 0)
+        return 'You have unsaved changes.';
+    const shown = labels.slice(0, MAX_LISTED_LABELS).join(', ');
+    const rest = labels.length - MAX_LISTED_LABELS;
+    return `Unsaved changes in: ${shown}${rest > 0 ? ` and ${rest} more` : ''}.`;
+};
 /**
  * Custom hook for branch navigation actions with dirty check support.
  */
 export function useBranchActions(options) {
     const apiClient = useApiClient();
+    const [confirmOpen, setConfirmOpen] = useState(false);
     const performBranchSwitch = (next) => {
         options.setBranchName(next);
         if (typeof window !== 'undefined') {
@@ -17,62 +29,81 @@ export function useBranchActions(options) {
         }
         options.onBranchSwitch?.(next);
     };
-    const confirmIfDirty = async (message) => {
-        if (!options.isAnyDirty())
+    const confirmIfDirty = async (question) => {
+        const unsaved = await options.getUnsaved();
+        if (unsaved.count === 0)
             return true;
         return new Promise((resolve) => {
+            const settle = (value) => {
+                // Mantine calls onClose and onCancel from its modals reducer, which runs while
+                // ModalsProvider renders, so a setState here must be deferred; resolving needs no deferral.
+                queueMicrotask(() => setConfirmOpen(false));
+                resolve(value);
+            };
+            setConfirmOpen(true);
             modals.openConfirmModal({
                 title: 'Unsaved Changes',
-                children: _jsx(Text, { size: "sm", children: message }),
+                // Drafts are stored per branch, so leaving does not lose them.
+                children: (_jsxs(Text, { size: "sm", children: [describeUnsaved(unsaved), " Your drafts stay on \u201C", options.branchName, "\u201D and come back when you return. ", question] })),
                 labels: { confirm: 'Continue Anyway', cancel: 'Cancel' },
                 confirmProps: { color: 'red' },
-                onCancel: () => resolve(false),
-                onConfirm: () => resolve(true),
+                onCancel: () => settle(false),
+                onConfirm: () => settle(true),
+                // Escape and overlay dismissals fire only onClose. Mantine also calls it
+                // right after onConfirm, which is harmless: a promise settles once.
+                onClose: () => settle(false),
             });
         });
     };
     const handleBranchChange = async (next) => {
         if (!next || next === options.branchName)
             return;
-        const confirmed = await confirmIfDirty('You have unsaved changes. Switch branches anyway?');
+        const confirmed = await confirmIfDirty('Switch branches anyway?');
         if (!confirmed)
             throw new Error('User cancelled branch switch');
         performBranchSwitch(next);
     };
+    const confirmCreate = () => confirmIfDirty('Create the new branch anyway?');
+    /** Resolves true when the branch was created and switched to, false when it was not. */
     const handleCreateBranch = async (branch) => {
-        const confirmed = await confirmIfDirty('Create new branch without saving changes?');
-        if (!confirmed)
-            return;
         try {
-            const result = await apiClient.branches.create({
+            const outcome = await requestBranchCreate(apiClient, {
                 branch: branch.name,
                 title: branch.title,
                 description: branch.description,
-            });
-            if (!result.ok) {
-                throw new Error(result.error || 'Failed to create branch');
+            }, options.userId);
+            if (outcome.kind === 'failed') {
+                throw new Error(outcome.message);
             }
+            const created = outcome.branch;
+            if (created)
+                options.onBranchCreated(created);
             // The server sanitizes the branch name (e.g. "feature/x" -> "feature-x")
             // before persisting it. Adopt the canonical name from the response so
             // the client doesn't end up stuck on a name the server never saved.
-            const createdName = result.data?.branch?.name ?? branch.name;
+            const createdName = created?.name ?? branch.name;
             notifications.show({
                 message: createdName === branch.name
                     ? `Branch "${createdName}" created`
                     : `Branch "${createdName}" created (renamed from "${branch.name}")`,
                 color: 'green',
             });
-            await options.onReloadBranches();
-            // Switch to new branch (already confirmed dirty check)
             performBranchSwitch(createdName);
+            // Not awaited: a listing can lag the create, and the switch must not wait
+            // on it. loadBranches reports its own failures and never rejects.
+            void options.onReloadBranches();
+            return true;
         }
         catch (err) {
             const message = err instanceof Error ? err.message : 'Failed to create branch';
             notifications.show({ message, color: 'red' });
+            return false;
         }
     };
     return {
         handleBranchChange,
+        confirmCreate,
         handleCreateBranch,
+        confirmOpen,
     };
 }

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

@@ -2,6 +2,15 @@ import type { ConflictStatus, PullRequestState, SyncStatus } from '../../types.j
 import type { OperatingMode } from '../../operating-mode/index.js';
 import type { CommentThread } from '../../comment-store.js';
 import type { BranchListItem } from '../../api/branch.js';
+/**
+ * How long a branch this session created stays overlaid on listings. Each warm
+ * server container caches the shared filesystem separately, so for its
+ * attribute/dentry cache window (~60s, see docs/concurrency.md window A) a
+ * listing can lack the branch even after another container's listing showed
+ * it. Twice that absorbs request latency; past it, listings alone decide.
+ * @internal Exported only for the test that pins it.
+ */
+export declare const CREATED_BRANCH_GRACE_MS = 120000;
 interface BranchSummary {
     name: string;
     status: string;
@@ -58,6 +67,8 @@ export interface UseBranchManagerReturn {
     branches: BranchListItem[];
     branchSummaries: BranchSummary[];
     currentBranch: BranchListItem | undefined;
+    /** Shows a branch the server just created before any listing includes it. */
+    addCreatedBranch: (branch: BranchListItem) => void;
     handleSubmit: (branchName: string) => Promise<void>;
     handleWithdraw: (branchName: string) => Promise<void>;
     handleRequestChanges: (branchName: string) => Promise<void>;

package/dist/editor/hooks/useBranchManager.js

@@ -1,6 +1,6 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useEffect, useMemo, useState } from 'react';
+import { useCallback, useEffect, useMemo, useState } from 'react';
 import { useSWRConfig } from 'swr';
 import { Text } from '@mantine/core';
 import { modals } from '@mantine/modals';
@@ -92,6 +92,46 @@ const showDeleteConfirmation = (branchName, onConfirm, onDismiss) => {
         ...confirmModalHandlers(onConfirm, onDismiss),
     });
 };
+/**
+ * How long a branch this session created stays overlaid on listings. Each warm
+ * server container caches the shared filesystem separately, so for its
+ * attribute/dentry cache window (~60s, see docs/concurrency.md window A) a
+ * listing can lack the branch even after another container's listing showed
+ * it. Twice that absorbs request latency; past it, listings alone decide.
+ * @internal Exported only for the test that pins it.
+ */
+export const CREATED_BRANCH_GRACE_MS = 120_000;
+/** The server listing plus any pending branches it lacks; the server's copy always wins. */
+function mergePendingBranches(listed, pending) {
+    const listedNames = new Set(listed.map((b) => b.name));
+    const missing = pending.filter((p) => !listedNames.has(p.branch.name));
+    return missing.length === 0 ? listed : [...listed, ...missing.map((p) => p.branch)];
+}
+/**
+ * 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
+ * so a listing with no arrival time (NaN) drops nothing.
+ */
+function reconcilePendingBranches(pending, listed, receivedAt) {
+    const listedByName = new Map(listed.map((b) => [b.name, b]));
+    let changed = false;
+    const next = [];
+    for (const p of pending) {
+        if (receivedAt - p.addedAt > CREATED_BRANCH_GRACE_MS) {
+            changed = true;
+            continue;
+        }
+        const listedCopy = listedByName.get(p.branch.name);
+        if (listedCopy && listedCopy !== p.branch) {
+            changed = true;
+            next.push({ branch: listedCopy, addedAt: p.addedAt });
+        }
+        else {
+            next.push(p);
+        }
+    }
+    return changed ? next : pending;
+}
 /**
  * Custom hook for managing git branches.
  */
@@ -100,7 +140,40 @@ export function useBranchManager(options) {
     const { mutate: globalMutate } = useSWRConfig();
     const [branchName, setBranchName] = useState(options.initialBranch);
     const { data: branchesData, error: branchesError, isValidating: branchesIsValidating, } = useBranchesData(apiClient);
-    const branches = useMemo(() => branchesData?.branches ?? [], [branchesData]);
+    const [pendingBranches, setPendingBranches] = useState([]);
+    const branches = useMemo(() => mergePendingBranches(branchesData?.branches ?? [], pendingBranches), [branchesData, pendingBranches]);
+    const addCreatedBranch = useCallback((branch) => {
+        setPendingBranches((prev) => [
+            ...prev.filter((p) => p.branch.name !== branch.name),
+            { branch, addedAt: Date.now() },
+        ]);
+    }, []);
+    const forgetCreatedBranch = (name) => {
+        setPendingBranches((prev) => {
+            const kept = prev.filter((p) => p.branch.name !== name);
+            return kept.length === prev.length ? prev : kept;
+        });
+    };
+    // After a workflow action, a pending branch's overlaid copy is stale. The
+    // server's returned copy replaces it, so a listing that still lacks the
+    // branch shows its new status instead of hiding it; without one, forgetting
+    // it fails closed rather than showing the pre-action state.
+    const updateCreatedBranch = (name, branch) => {
+        if (!branch) {
+            forgetCreatedBranch(name);
+            return;
+        }
+        setPendingBranches((prev) => prev.some((p) => p.branch.name === name)
+            ? prev.map((p) => (p.branch.name === name ? { ...p, branch } : p))
+            : prev);
+    };
+    // Each received listing is a new `branchesData` (see `BranchesData.receivedAt`);
+    // the grace window is measured to its arrival.
+    useEffect(() => {
+        if (!branchesData)
+            return;
+        setPendingBranches((prev) => reconcilePendingBranches(prev, branchesData.branches, branchesData.receivedAt));
+    }, [branchesData]);
     // Adopt the server's default branch once data arrives, if nothing pinned one.
     useEffect(() => {
         if (!branchName && branchesData?.defaultBranch) {
@@ -225,6 +298,7 @@ export function useBranchManager(options) {
                         message: 'Branch submitted for review',
                         color: 'green',
                     });
+                    updateCreatedBranch(branchNameToSubmit, result.data?.branch);
                     await loadBranches();
                     resolve();
                 }
@@ -257,6 +331,7 @@ export function useBranchManager(options) {
                         throw new Error(result.error || 'Failed to withdraw branch');
                     }
                     notifications.show({ message: 'Branch withdrawn', color: 'blue' });
+                    updateCreatedBranch(branchNameToWithdraw, result.data?.branch);
                     await loadBranches();
                     resolve();
                 }
@@ -279,6 +354,7 @@ export function useBranchManager(options) {
                 throw new Error(result.error || 'Failed to request changes');
             }
             notifications.show({ message: 'Changes requested', color: 'orange' });
+            updateCreatedBranch(branchNameForChanges, result.data?.branch);
             await loadBranches();
         }
         catch (err) {
@@ -301,6 +377,7 @@ export function useBranchManager(options) {
                         throw new Error(result.error || 'Failed to delete branch');
                     }
                     notifications.show({ message: 'Branch deleted', color: 'green' });
+                    forgetCreatedBranch(branchNameToDelete);
                     await loadBranches();
                 }
                 catch (err) {
@@ -338,6 +415,7 @@ export function useBranchManager(options) {
         branches,
         branchSummaries,
         currentBranch,
+        addCreatedBranch,
         handleSubmit,
         handleWithdraw,
         handleRequestChanges,

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

@@ -19,6 +19,12 @@ export declare const BRANCHES_KEY = "canopy:branches";
 export interface BranchesData {
     branches: BranchListItem[];
     defaultBranch?: string;
+    /**
+     * Client clock when this listing arrived. It makes listings fetched at
+     * different moments distinct `data` values even when their branches match,
+     * while a failed fetch (SWR keeps the previous `data`) changes nothing.
+     */
+    receivedAt: number;
 }
 /**
  * Fetch the branches list. Exported for direct testing and for the

package/dist/editor/hooks/useBranchesData.js

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

package/dist/editor/hooks/useCommentSystem.js

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

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

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