@pantheon-systems/puck-css 0.12.0 → 0.14.0

package/dist/editor/useP1Editor.js

@@ -1,18 +1,13 @@
 "use client";
-/**
- * useP1Editor Hook
- *
- * All-in-one hook for setting up a P1-enabled Puck editor.
- * Composes useP1Plugin and useP1Overrides internally, handles
- * document loading, version management, historical version protection,
- * and provides everything needed to render <Puck>.
- */
 import { useState, useEffect, useRef, useMemo, useCallback } from 'react';
 import { useP1Puck } from '../core/P1PuckContext.js';
 import { useVersions } from '../versioning/useVersions.js';
 import { useP1Auth } from '../auth/index.js';
+import { isDocumentGoneError, isDocumentNotFoundError } from '../data/utils.js';
+import { canCreatePages } from '../features/content-type-templates/permissions/role-permissions.js';
 import { useP1Plugin } from './useP1Plugin.js';
 import { useP1Overrides } from './useP1Overrides.js';
+import { withFreshFieldTypes } from './freshFieldTypes.js';
 import { useComponentRegistry } from './useComponentRegistry.js';
 import { buildThumbnailOverride } from './utils/buildThumbnailOverride.js';
 import { makeEagerVersionHandler } from './utils/makeEagerVersionHandler.js';
@@ -20,67 +15,45 @@ import { restoreDocumentVersion } from './utils/restoreDocumentVersion.js';
 import { initialPanelUi } from './useResponsivePanels.js';
 import { createDocumentSyncStore, createDocumentSyncPlugin, documentSyncKey, BLANK_SYNC_KEY, } from './plugin/document-sync-plugin.js';
 import { resolveLiveThumbnailDrawer } from './thumbnails/resolveLiveThumbnailDrawer.js';
-/**
- * All-in-one hook for setting up a P1-enabled Puck editor.
- *
- * Handles document loading, version management, plugin/overrides creation,
- * safe data, historical version protection, and plugin array assembly.
- * Returns everything needed to render <Puck> with minimal boilerplate.
- *
- * Must be used inside a P1PuckProvider.
- *
- * @param options - Editor configuration
- * @returns Loading state, puck props, and P1 context
- *
- * @example
- * ```tsx
- * function Editor() {
- *   const { loading, error, puckProps } = useP1Editor({
- *     documentPath: '/home',
- *     puckConfig: config,
- *   });
- *
- *   if (loading) return <Loading />;
- *   if (error) return <Error error={error} />;
- *
- *   return <Puck {...puckProps} />;
- * }
- * ```
- */
+function titleFromPath(path) {
+    const slug = path.split('/').filter(Boolean).pop();
+    if (!slug)
+        return 'Home';
+    const words = slug.replace(/[-_]+/g, ' ').trim();
+    return words.charAt(0).toUpperCase() + words.slice(1);
+}
 export function useP1Editor(options) {
     const { documentPath, puckConfig, additionalPlugins, additionalOverrides, thumbnails, liveThumbnailDrawer, overrideOptions, pluginOptions, onSelectionChange, onDocumentNotFound, } = options;
-    const css = useP1Puck();
+    const ccr = useP1Puck();
     const { user, logout } = useP1Auth();
-    // =========================================================================
-    // Document Loading
-    // =========================================================================
     const [loading, setLoading] = useState(true);
     const [error, setError] = useState(null);
     const [needsRedirect, setNeedsRedirect] = useState(false);
+    const [notFound, setNotFound] = useState(false);
+    const [loadAttempt, setLoadAttempt] = useState(0);
     const loadedPathRef = useRef(null);
-    // Reset loaded path when branch changes so document reloads on the new branch
-    const prevBranchRef = useRef(css.branchId);
-    if (prevBranchRef.current !== css.branchId) {
-        prevBranchRef.current = css.branchId;
+    const loadedBranchRef = useRef(null);
+    const prevBranchRef = useRef(ccr.branchId);
+    if (prevBranchRef.current !== ccr.branchId) {
+        prevBranchRef.current = ccr.branchId;
         loadedPathRef.current = null;
     }
-    // Keep callback in a ref so the effect doesn't re-run when it changes
     const onDocumentNotFoundRef = useRef(onDocumentNotFound);
     onDocumentNotFoundRef.current = onDocumentNotFound;
     useEffect(() => {
-        // Wait for branch resolution before loading documents
-        if (!css.branchId)
+        if (!ccr.branchId)
             return;
-        // Skip if already loaded this path on this branch
         if (loadedPathRef.current === documentPath)
             return;
         let cancelled = false;
         setLoading(true);
         setError(null);
-        css.loadDocument(documentPath)
+        setNotFound(false);
+        ccr.loadDocument(documentPath)
             .then(() => {
             if (!cancelled) {
                 loadedPathRef.current = documentPath;
+                loadedBranchRef.current = ccr.branchId;
                 setNeedsRedirect(false);
                 setLoading(false);
             }
@@ -89,101 +62,87 @@ export function useP1Editor(options) {
             if (cancelled)
                 return;
             const loadErr = err instanceof Error ? err : new Error(String(err));
-            // Give the consumer a chance to handle the error (e.g. auto-create)
+            if (isDocumentGoneError(loadErr)) {
+                setNeedsRedirect(true);
+                return;
+            }
             if (onDocumentNotFoundRef.current) {
                 try {
                     const shouldRetry = await onDocumentNotFoundRef.current(documentPath, loadErr);
                     if (!cancelled && shouldRetry) {
-                        await css.loadDocument(documentPath);
+                        await ccr.loadDocument(documentPath);
                         if (!cancelled) {
                             loadedPathRef.current = documentPath;
+                            loadedBranchRef.current = ccr.branchId;
                             setNeedsRedirect(false);
                             setLoading(false);
-                            void css.refreshDocuments();
+                            void ccr.refreshDocuments();
                         }
                         return;
                     }
                 }
                 catch {
-                    // callback itself failed — fall through to unload
                 }
             }
-            // Unload the editor; recovery effect will set an error if no docs exist
-            if (!cancelled) {
-                setNeedsRedirect(true);
+            if (cancelled)
+                return;
+            if (isDocumentNotFoundError(loadErr)) {
+                loadedPathRef.current = null;
+                setNotFound(true);
+                setLoading(false);
+                return;
             }
+            setNeedsRedirect(true);
         });
         return () => {
             cancelled = true;
         };
-    }, [documentPath, css.branchId, css.loadDocument]);
-    // No branch means nothing can be opened, so an unresolved branch is fatal.
-    // Derived rather than copied into state: a retry that clears the failure has
-    // to stop being reported, which a mirrored copy would keep showing.
-    const branchBootError = css.branchId ? null : css.branchResolutionError ?? null;
-    // Recovery: document not found on this branch — unload the editor and let
-    // the preview empty state guide the user to pick a page.
+    }, [documentPath, ccr.branchId, ccr.loadDocument, loadAttempt]);
+    const retry = useCallback(() => {
+        loadedPathRef.current = null;
+        setLoadAttempt((n) => n + 1);
+    }, []);
+    const branchBootError = ccr.branchId ? null : ccr.branchResolutionError ?? null;
     useEffect(() => {
         if (!needsRedirect)
             return;
-        if (css.documentsLoading)
+        if (ccr.documentsLoading)
             return;
         setNeedsRedirect(false);
-        if (css.documents.length === 0) {
-            // An empty list because the request was refused is a different story from
-            // a branch that genuinely holds nothing; saying "no documents" for the
-            // former is how the real failure stays hidden.
-            setError(css.documentsError ?? new Error('No documents found on this branch'));
+        if (ccr.documents.length === 0) {
+            setError(ccr.documentsError ?? new Error('No documents found on this branch'));
         }
         setLoading(false);
-    }, [needsRedirect, css.documentsLoading, css.documents.length, css.documentsError]);
-    // =========================================================================
-    // Version Management
-    // =========================================================================
+    }, [needsRedirect, ccr.documentsLoading, ccr.documents.length, ccr.documentsError]);
     const { versions, loading: versionsLoading, refresh: refreshVersions, } = useVersions({
-        client: css.client,
-        siteId: css.siteId,
-        branchId: css.branchId,
-        documentId: css.currentDocument?.id ?? null,
+        client: ccr.client,
+        siteId: ccr.siteId,
+        branchId: ccr.branchId,
+        documentId: ccr.currentDocument?.id ?? null,
     });
-    // Refresh versions when document changes; also reset eager-version flag so a
-    // stale post-publish signal from the previous document never fires on the new one.
     useEffect(() => {
         needsVersionRef.current = false;
-        if (css.currentDocument?.id)
+        if (ccr.currentDocument?.id)
             void refreshVersions();
-    }, [css.currentDocument?.id, refreshVersions]);
-    // Refresh versions after a successful save so the publish badge reflects the
-    // new unpublished draft (publishedStatus flips 'published' → 'unpublished-changes').
-    // Without this the badge would keep reading "Live" after an edit on the Live branch.
+    }, [ccr.currentDocument?.id, refreshVersions]);
     useEffect(() => {
-        if (css.saveStatus === 'saved')
+        if (ccr.saveStatus === 'saved')
             void refreshVersions();
-    }, [css.saveStatus, refreshVersions]);
-    // Select a version — latest returns to live editing, others load historical
+    }, [ccr.saveStatus, refreshVersions]);
     const handleVersionSelect = useCallback((version) => {
         const latestVersion = versions[0];
         if (latestVersion && version.id === latestVersion.id) {
-            void css.returnToLatest();
+            void ccr.returnToLatest();
         }
         else {
-            void css.loadVersion(version);
+            void ccr.loadVersion(version);
         }
-    }, [versions, css.loadVersion, css.returnToLatest]);
-    // Revert to a prior version.
-    const handleRestoreVersion = useCallback((version) => restoreDocumentVersion(version, css, refreshVersions, () => { }), [css, refreshVersions]);
-    // =========================================================================
-    // Published Status (derived from version data)
-    // =========================================================================
-    // The backend includes isPublished on each DocumentVersion via an EXISTS
-    // subquery against checkpoint_documents. No additional API calls needed.
-    const currentVersionId = css.viewingVersion?.id ?? versions[0]?.id;
+    }, [versions, ccr.loadVersion, ccr.returnToLatest]);
+    const handleRestoreVersion = useCallback((version) => restoreDocumentVersion(version, ccr, refreshVersions, () => { }), [ccr, refreshVersions]);
+    const currentVersionId = ccr.viewingVersion?.id ?? versions[0]?.id;
     const currentVersionIsPublished = versions.find(v => v.id === currentVersionId)?.isPublished ?? false;
     const hasPublishedVersion = versions.some(v => v.isPublished);
-    // Look up the current document from the branch document list, which includes
-    // inherited and isPublished fields from the branch-level listing endpoint.
-    // css.currentDocument comes from the site-level getByPath endpoint and lacks these.
-    const branchDocument = css.documents.find(d => d.id === css.currentDocument?.id);
+    const branchDocument = ccr.documents.find(d => d.id === ccr.currentDocument?.id);
     const inheritedAndPublished = branchDocument?.inherited && branchDocument?.isPublished;
     const publishedStatus = versionsLoading
         ? undefined
@@ -194,60 +153,68 @@ export function useP1Editor(options) {
                 : hasPublishedVersion
                     ? 'unpublished-changes'
                     : 'draft';
-    // =========================================================================
-    // Focus Region Reporting (outgoing — report local selection to server)
-    // =========================================================================
-    // Report selection changes to the presence system via WebSocket.
-    // Wraps the consumer's onSelectionChange so both reporting and
-    // the consumer callback are called.
     const onSelectionChangeRef = useRef(onSelectionChange);
     onSelectionChangeRef.current = onSelectionChange;
     const handleSelectionChange = useCallback((path, itemId) => {
-        // Report to presence system via WebSocket (instant broadcast to other clients)
         const regions = path ? [path] : [];
-        css.sendFocusRegions(regions);
-        // Forward to consumer callback
+        ccr.sendFocusRegions(regions);
         onSelectionChangeRef.current?.(path, itemId);
-    }, [css.sendFocusRegions]);
-    // =========================================================================
-    // Component Registry (runs at editor startup, writes descriptors to P1 backend)
-    // =========================================================================
+    }, [ccr.sendFocusRegions]);
     useComponentRegistry({ puckConfig });
-    // =========================================================================
-    // Plugin & Overrides (composed hooks)
-    // =========================================================================
-    // Set true after a successful publish; the next onChange fires the eager
-    // version create and clears this immediately.
     const needsVersionRef = useRef(false);
-    const eagerVersionParamsRef = useRef({ siteId: css.siteId, branchId: css.branchId, documentId: css.currentDocument?.id ?? null });
-    eagerVersionParamsRef.current = { siteId: css.siteId, branchId: css.branchId, documentId: css.currentDocument?.id ?? null };
-    // Wrap publish to refresh version list and call consumer callback after success.
+    const eagerVersionParamsRef = useRef({ siteId: ccr.siteId, branchId: ccr.branchId, documentId: ccr.currentDocument?.id ?? null });
+    eagerVersionParamsRef.current = { siteId: ccr.siteId, branchId: ccr.branchId, documentId: ccr.currentDocument?.id ?? null };
     const consumerOnPublishSuccessRef = useRef(overrideOptions?.onPublishSuccess);
     consumerOnPublishSuccessRef.current = overrideOptions?.onPublishSuccess;
     const handlePublish = useCallback(async () => {
-        const checkpoint = await css.publishDocument();
+        const checkpoint = await ccr.publishDocument();
         needsVersionRef.current = true;
         void refreshVersions();
         consumerOnPublishSuccessRef.current?.(checkpoint);
-    }, [css, refreshVersions]);
-    const canRevert = css.userRole === 'admin' || css.userRole === 'editor' || css.userRole === 'author';
-    // Pushes freshly loaded documents into the live Puck instance, replacing
-    // the remount-on-document-switch behavior the old document-scoped puckKey
-    // provided (see document-sync-plugin.tsx). Handed to the P1 plugin as well
-    // so its context sync defers document switches to this store.
+    }, [ccr, refreshVersions]);
+    const canRevert = ccr.userRole === 'admin' || ccr.userRole === 'editor' || ccr.userRole === 'author';
     const [documentSyncStore] = useState(createDocumentSyncStore);
+    const [logoutError, setLogoutError] = useState(null);
+    const [isLoggingOut, setIsLoggingOut] = useState(false);
+    const handleLogout = useCallback(async () => {
+        setIsLoggingOut(true);
+        setLogoutError(null);
+        try {
+            const outcome = await logout();
+            if (outcome.status === 'error') {
+                setLogoutError(outcome.message);
+                setIsLoggingOut(false);
+            }
+        }
+        catch (err) {
+            setLogoutError(err instanceof Error ? err.message : 'Logout failed');
+            setIsLoggingOut(false);
+        }
+    }, [logout]);
+    const pageNotFound = useMemo(() => notFound
+        ? {
+            canCreate: canCreatePages(ccr.userRole),
+            onCreate: async () => {
+                await ccr.createDocument(documentPath, null, titleFromPath(documentPath));
+                retry();
+            },
+        }
+        : null, [notFound, documentPath, ccr.userRole, ccr.createDocument, retry]);
     const p1Plugin = useP1Plugin({
         documentSyncStore,
+        pageNotFound,
         onSelectionChange: handleSelectionChange,
-        currentUser: user ? { id: css.userId, name: user.name, email: user.email, avatar: user.picture } : undefined,
-        onLogout: logout,
+        currentUser: user ? { id: ccr.userId, name: user.name, email: user.email, avatar: user.picture } : undefined,
+        onLogout: handleLogout,
+        logoutError,
+        isLoggingOut,
         puckConfig,
         ...pluginOptions,
         onPublish: handlePublish,
         versions,
         versionsLoading,
         publishedStatus,
-        selectedVersionId: css.viewingVersion?.id ?? undefined,
+        selectedVersionId: ccr.viewingVersion?.id ?? undefined,
         onVersionSelect: handleVersionSelect,
         onRestoreVersion: handleRestoreVersion,
         canRevert,
@@ -261,11 +228,7 @@ export function useP1Editor(options) {
         publishedStatus,
         ...(overrideOptions?.onPublishSuccess ? { onPublishSuccess: wrappedOnPublishSuccess } : {}),
     });
-    // =========================================================================
-    // Stable plugin array
-    // =========================================================================
     if (process.env.NODE_ENV === "development") {
-        // eslint-disable-next-line react-hooks/rules-of-hooks
         const prev = useRef(additionalPlugins);
         if (prev.current !== additionalPlugins) {
             const countChanged = (prev.current?.length ?? 0) !== (additionalPlugins?.length ?? 0);
@@ -280,77 +243,53 @@ export function useP1Editor(options) {
     additionalPluginsRef.current = additionalPlugins;
     const pluginCount = additionalPlugins?.length ?? 0;
     const documentSyncPlugin = useMemo(() => createDocumentSyncPlugin(documentSyncStore), [documentSyncStore]);
-    // Publish the loaded document into the live Puck instance.
-    //
-    // Both the key and the data come from the payload's own origin, so a key can
-    // never be paired with a different document's data. Keying off the live
-    // branchId instead published the incoming branch's key beside the outgoing
-    // branch's data the instant a switch began; the plugin applied that pairing,
-    // recorded the new key as applied, and then ignored the correct document when
-    // it arrived under the same key — leaving the canvas a workstream behind.
-    //
-    // safeData is read directly rather than through a ref: it only advances when
-    // the provider loads a document (saveData deliberately never touches
-    // currentData), so it cannot re-fire on every keystroke.
-    const currentDocumentId = css.currentDocument?.id;
-    const origin = css.currentDataOrigin;
+    const currentDocumentId = ccr.currentDocument?.id;
+    const origin = ccr.currentDataOrigin;
     useEffect(() => {
         if (loading || error || !origin)
             return;
-        // Historical versions sync through ContextSyncBridge, which does not reset
-        // the undo stack.
         if (origin.historical)
             return;
-        // Mid-switch the payload still belongs to the outgoing branch or document.
-        // Withholding it keeps the applied key naming what the canvas really shows.
-        if (origin.branchId !== css.branchId)
+        if (origin.branchId !== ccr.branchId)
             return;
         if (origin.documentId !== currentDocumentId)
             return;
         documentSyncStore.publish({
             syncKey: documentSyncKey(origin.branchId, origin.documentId),
-            data: css.safeData,
+            data: ccr.safeData,
         });
     }, [
         loading,
         error,
         origin,
-        css.safeData,
-        css.branchId,
+        ccr.safeData,
+        ccr.branchId,
         currentDocumentId,
         documentSyncStore,
     ]);
+    const featurePuckPlugins = ccr.featurePuckPlugins;
     const plugins = useMemo(() => {
         const result = [p1Plugin, documentSyncPlugin];
+        result.push(...featurePuckPlugins);
         if (additionalPluginsRef.current) {
             result.push(...additionalPluginsRef.current);
         }
         return result;
-    }, [p1Plugin, documentSyncPlugin, pluginCount]);
-    // =========================================================================
-    // Stable onChange (disabled for historical versions, guarded across
-    // document switches)
-    // =========================================================================
-    const isViewingHistoricalRef = useRef(css.isViewingHistoricalVersion);
-    isViewingHistoricalRef.current = css.isViewingHistoricalVersion;
-    // With Puck surviving document switches, onChange can fire while the canvas
-    // still shows the previous document but css already targets the new one
-    // (load in flight, or loaded but not yet pushed by the sync plugin). Saving
-    // then would write the old page's content into the new page — drop instead.
+    }, [p1Plugin, documentSyncPlugin, featurePuckPlugins, pluginCount]);
+    const isViewingHistoricalRef = useRef(ccr.isViewingHistoricalVersion);
+    isViewingHistoricalRef.current = ccr.isViewingHistoricalVersion;
     const saveTargetKeyRef = useRef(null);
-    saveTargetKeyRef.current = css.currentDocument?.id
-        ? documentSyncKey(css.branchId, css.currentDocument.id)
+    saveTargetKeyRef.current = ccr.currentDocument?.id
+        ? documentSyncKey(ccr.branchId, ccr.currentDocument.id)
         : null;
     const eagerVersionHandler = useMemo(() => makeEagerVersionHandler(needsVersionRef, () => eagerVersionParamsRef.current, {
-        createVersion: (siteId, params) => css.client.versions.create(siteId, params),
+        createVersion: (siteId, params) => ccr.client.versions.create(siteId, params),
         refreshVersions,
-    }), [css.client, refreshVersions]);
-    const { saveData } = css;
+    }), [ccr.client, refreshVersions]);
+    const { saveData } = ccr;
     const onChange = useCallback((data) => {
         if (isViewingHistoricalRef.current)
             return;
-        // The blank sentinel stays permissive so a consumer running without the
-        // document-sync plugin is not frozen read-only.
         const appliedKey = documentSyncStore.getAppliedKey();
         if (appliedKey !== BLANK_SYNC_KEY && appliedKey !== saveTargetKeyRef.current) {
             console.warn('[useP1Editor] save SKIPPED: canvas/document mismatch during switch.', 'canvas:', appliedKey, 'target:', saveTargetKeyRef.current);
@@ -359,44 +298,21 @@ export function useP1Editor(options) {
         eagerVersionHandler(data);
         saveData(data);
     }, [saveData, documentSyncStore, eagerVersionHandler]);
-    // =========================================================================
-    // Permissions (read-only for historical versions)
-    // =========================================================================
     const permissions = useMemo(() => {
-        if (css.isViewingHistoricalVersion) {
-            // Omit edit:false so page/root fields are never locked by Puck's own
-            // readonly rendering. Interaction is blocked by ReadOnlyFieldsGuard
-            // (inert attribute) instead, which also covers root fields without
-            // requiring resolvePermissions on config.root.
+        if (ccr.isViewingHistoricalVersion) {
             return { delete: false, drag: false, duplicate: false, insert: false };
         }
         return { delete: true, drag: true, duplicate: true, edit: true, insert: true };
-    }, [css.isViewingHistoricalVersion]);
-    // =========================================================================
-    // Stable merged overrides
-    // =========================================================================
-    // Merge additional overrides (e.g. from media plugins) with P1 overrides.
-    // Uses ref pattern to keep the merge stable — only recomputes when
-    // p1Overrides changes, not when additionalOverrides reference changes
-    // (which would happen every render if the consumer doesn't memoize).
+    }, [ccr.isViewingHistoricalVersion]);
     const additionalOverridesRef = useRef(additionalOverrides);
     additionalOverridesRef.current = additionalOverrides;
-    // Thumbnail override — built from the thumbnails map and merged between
-    // p1Overrides and additionalOverrides so the site can still fully override
-    // componentItem if needed.
     const thumbnailsRef = useRef(thumbnails);
     thumbnailsRef.current = thumbnails;
-    // Live thumbnail drawer — default ON for every consumer. Uses raw puckConfig
-    // (not configWithPermissions) so previews show all components regardless of
-    // role. Because useMemo deps on p1Overrides (stable after mount), changes to
-    // puckConfig or liveThumbnailDrawer after mount are not picked up.
     const puckConfigRef = useRef(puckConfig);
     puckConfigRef.current = puckConfig;
     const liveThumbnailDrawerRef = useRef(liveThumbnailDrawer);
     liveThumbnailDrawerRef.current = liveThumbnailDrawer;
     const mergedOverrides = useMemo(() => {
-        // Layer order (last wins):
-        //   p1Overrides → liveThumbnailDrawer → thumbnailOverride → additionalOverrides
         const layers = [
             p1Overrides,
             resolveLiveThumbnailDrawer(puckConfigRef.current, liveThumbnailDrawerRef.current),
@@ -418,35 +334,16 @@ export function useP1Editor(options) {
                 }
             }
         }
-        return merged;
+        return withFreshFieldTypes(merged);
     }, [p1Overrides]);
-    // =========================================================================
-    // Assemble puckProps
-    // =========================================================================
-    // Key that forces Puck to remount on role change (let puck internally manage the change on document change),
-    // ensuring clean undo history, sidebar state, and fresh permission cache.
-    // Puck caches resolvePermissions results per component instance — the
-    // cache is only invalidated when component data changes, not when the
-    // resolver function changes. Including userRole in the key forces a
-    // clean remount with an empty cache when roles switch.
-    const puckKey = `css-${css.userRole}`;
-    // Sidebar visibility for the initial mount. puckKey is the dependency on
-    // purpose even though it is not read here: a new key remounts Puck, which
-    // re-reads this as its initial `ui`, so the budget must be applied again.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
+    const puckKey = `p1-${ccr.userRole}`;
     const initialSidebarUi = useMemo(() => initialPanelUi(), [puckKey]);
-    // Focus highlighting is handled via direct DOM manipulation in
-    // PresenceFocusBridge (P1App.tsx) — no config wrapping needed.
-    // Inject per-component resolvePermissions into the Puck config.
-    // Puck doesn't have a top-level resolvePermissions prop — permissions
-    // must be resolved per-component via config[type].resolvePermissions.
-    const resolvePermsRef = useRef(css.resolvePermissions);
-    resolvePermsRef.current = css.resolvePermissions;
-    // Template mode: editing a template document (path `_registry/templates/<name>`).
-    const isTemplateMode = /^_registry\/templates\//.test(css.currentDocument?.path ?? '');
+    const resolvePermsRef = useRef(ccr.resolvePermissions);
+    resolvePermsRef.current = ccr.resolvePermissions;
+    const isTemplateMode = /^_registry\/templates\//.test(ccr.currentDocument?.path ?? '');
     const configWithPermissions = useMemo(() => {
         let cfg = puckConfig;
-        if (css.resolvePermissions) {
+        if (ccr.resolvePermissions) {
             const components = (cfg.components ?? {});
             const wrapped = {};
             for (const [name, comp] of Object.entries(components)) {
@@ -457,12 +354,6 @@ export function useP1Editor(options) {
                         if (!resolver)
                             return params.permissions;
                         const basePerms = resolver({ type: name, props: data?.props }, {});
-                        // Template-authoring mode: the context resolver only sees a
-                        // metadata summary (no pins), so the document's live _pinMap is the
-                        // pin source. On a bound page the resolver reads the live template
-                        // and already governs pins, so the page's own snapshot pinMap is
-                        // ignored — otherwise a stale pin would stay locked after the
-                        // template unpins it.
                         if (isTemplateMode) {
                             const pinMap = (params.appState?.data?.root?.props?._pinMap ?? {});
                             const compId = data?.props?.id;
@@ -476,31 +367,43 @@ export function useP1Editor(options) {
             }
             cfg = { ...cfg, components: wrapped };
         }
-        // In template mode, relabel the right-sidebar root header "Page" -> "Template".
-        // Puck derives that heading from `config.root.label` (no override hook exists).
         if (isTemplateMode) {
             const root = (cfg.root ?? {});
             cfg = { ...cfg, root: { ...root, label: 'Template' } };
         }
         return cfg;
-    }, [puckConfig, !!css.resolvePermissions, isTemplateMode]);
+    }, [puckConfig, !!ccr.resolvePermissions, isTemplateMode]);
     const puckProps = useMemo(() => ({
         config: configWithPermissions,
-        data: css.safeData,
+        data: ccr.safeData,
         onChange,
         plugins,
         overrides: mergedOverrides,
         ui: initialSidebarUi,
         permissions,
-        onAction: css.handleAction,
-    }), [configWithPermissions, css.safeData, onChange, plugins, mergedOverrides, initialSidebarUi, permissions, css.handleAction]);
+        onAction: ccr.handleAction,
+    }), [configWithPermissions, ccr.safeData, onChange, plugins, mergedOverrides, initialSidebarUi, permissions, ccr.handleAction]);
+    const inFlight = branchBootError === null && loading;
+    const lastGoodRef = useRef(null);
+    const settled = loadedPathRef.current === documentPath && loadedBranchRef.current === ccr.branchId;
+    if (settled && !inFlight && !error && !branchBootError) {
+        lastGoodRef.current = { puckKey, puckProps };
+    }
+    const retained = lastGoodRef.current;
+    const hasContent = retained !== null;
+    const reloadKind = loadedBranchRef.current !== null && loadedBranchRef.current !== ccr.branchId
+        ? 'branch'
+        : 'document';
     return {
-        loading: branchBootError === null && loading,
+        loading: inFlight && !hasContent,
+        reloading: inFlight && hasContent ? reloadKind : null,
+        hasContent,
         error: error ?? branchBootError,
-        puckKey,
-        puckProps,
-        css,
-        /** @deprecated No longer emitted — editor now shows an empty state when a document is not found on the current branch. */
+        notFound,
+        retry,
+        puckKey: retained?.puckKey ?? puckKey,
+        puckProps: retained?.puckProps ?? puckProps,
+        css: ccr,
         redirectPath: null,
     };
 }