@pantheon-systems/puck-css 0.11.1 → 0.13.0

package/dist/editor/P1PuckProvider.js

@@ -1,89 +1,31 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-/**
- * P1 Puck Provider
- *
- * React context provider for P1 Puck integration.
- */
 import { useState, useCallback, useMemo, useEffect, useRef } from 'react';
 import isEqual from 'lodash.isequal';
 import { P1PuckContext } from '../core/P1PuckContext.js';
 import { NotificationProvider, useNotifications } from '../core/NotificationContext.js';
 import { PresenceContext } from '../core/PresenceContext.js';
 import { debounce } from '../core/utils/debounce.js';
+import { describeRequestFailure } from '../core/utils/requestError.js';
 import { withRetry } from '../core/utils/retry.js';
 import { resolveFeatureConfig } from '../core/featureConfig.js';
 import { createPuckPermissions } from '../features/content-type-templates/permissions/createPuckPermissions.js';
 import { useTemplateList } from '../features/content-type-templates/hooks/useTemplateList.js';
 import { presenceIdentityKey } from '../collaboration/utils/presenceIdentity.js';
-import { DEFAULT_CSS_FEATURE_PLUGINS } from './defaultPlugins.js';
+import { DEFAULT_CCR_FEATURE_PLUGINS } from './defaultPlugins.js';
 import { resolveActivePlugins, composeProviders } from './composePlugins.js';
 import { snapshotToPuckData } from './utils/snapshotToPuckData.js';
 import { useDocuments } from './useDocuments.js';
 import { useRealtime } from './useRealtime.js';
-/**
- * Identity to record alongside a loaded payload.
- *
- * `branch` must be the branch the load was requested for, not the branch on the
- * returned version: for an inherited document the backend serves main's
- * published version, and recording main would make every consumer treat the
- * payload as belonging to another workstream.
- *
- * Returns a fresh object per call so consumers re-run even when two documents
- * share payload identity — snapshotToPuckData yields one shared constant for
- * every blank snapshot.
- */
 function originFor(doc, branch, versionId, historical) {
     return doc
         ? { branchId: branch, documentId: doc.id, documentPath: doc.path, versionId, historical }
         : null;
 }
-/**
- * Provider component for P1 Puck integration.
- *
- * Wraps your Puck editor to provide P1 functionality including:
- * - Auto-save with debouncing
- * - Document loading
- * - Checkpoint (publish) creation
- * - Branch switching
- * - Toast notifications for errors and success
- *
- * @example
- * ```tsx
- * import { P1PuckProvider, P1PuckEditor } from '@pantheon-systems/puck-css';
- * import { P1Client } from '@pantheon-systems/css-client';
- *
- * const client = new P1Client({
- *   baseUrl: 'http://localhost:8787',
- *   apiKey: 'your-api-key',
- * });
- *
- * function App() {
- *   return (
- *     <P1PuckProvider
- *       client={client}
- *       siteId="site-123"
- *       branchId="branch-456"
- *       userId="user-789"
- *     >
- *       <P1PuckEditor config={puckConfig} documentPath="/home" />
- *     </P1PuckProvider>
- *   );
- * }
- * ```
- */
 export function P1PuckProvider(props) {
     return (_jsx(NotificationProvider, { children: _jsx(P1PuckProviderInner, { ...props }) }));
 }
-/** Query param naming the workstream to open, set by the dashboard's "Open in visual editor". */
 const BRANCH_QUERY_PARAM = 'branch';
-/**
- * Rejected here rather than downstream: the value reaches API paths and the
- * realtime URL unescaped, so anything that could change a URL's shape ("/",
- * ".", "?", "#") must never get that far. refreshBranches still decides whether
- * a well-formed id actually exists.
- */
 const BRANCH_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
-/** Kept pure — the param is consumed in an effect, not while rendering. */
 function readDeepLinkBranchId() {
     if (typeof window === 'undefined')
         return '';
@@ -96,10 +38,6 @@ function readDeepLinkBranchId() {
         return '';
     }
 }
-/**
- * Left in place the param would re-apply on the next remount (this provider
- * remounts on route-param changes), silently undoing a manual workstream switch.
- */
 function stripDeepLinkBranchParam() {
     if (typeof window === 'undefined')
         return;
@@ -111,37 +49,30 @@ function stripDeepLinkBranchParam() {
         window.history.replaceState(window.history.state, '', `${url.pathname}${url.search}${url.hash}`);
     }
     catch {
-        // history/URL unavailable — the param is harmless if it stays
     }
 }
-/**
- * Inner provider component that has access to notification context.
- */
-function P1PuckProviderInner({ client, siteId, branchId: initialBranchId, userId, autoSaveDelay = 3000, maxRetries = 3, showErrorNotifications = true, enableRealtime = true, wsBaseUrl, realtimeApiKey, realtimeSyncInterval: _realtimeSyncInterval = 250, realtimeTokenRefresher, 
-// Phase 9: Presence props
-presenceEnabled = true, presencePollingInterval = 5000, userName: _userName, userAvatar: _userAvatar, userNameResolver, 
-// Phase 9: Agent mode props
-agentModeEnabled = false, agentId, agentTrigger: _agentTrigger, 
-// Phase 9: Callbacks
-onPresenceChange, onAgentConflict: _onAgentConflict, 
-// Plugin system props (B.4)
-featurePlugins, featureConfig, 
-// Content Type Templates (PROPOSAL-010)
-// Consumers should resolve the role via useResolveContentRole and pass it here.
-userRole = 'editor', children, }) {
-    // Access notification context
+function P1PuckProviderInner({ client, siteId, branchId: initialBranchId, userId, autoSaveDelay = 3000, maxRetries = 3, showErrorNotifications = true, enableRealtime = true, wsBaseUrl, realtimeApiKey, realtimeSyncInterval: _realtimeSyncInterval = 250, realtimeTokenRefresher, presenceEnabled = true, presencePollingInterval = 5000, userName: _userName, userAvatar: _userAvatar, userNameResolver, agentModeEnabled = false, agentId, agentTrigger: _agentTrigger, onPresenceChange, onAgentConflict: _onAgentConflict, featurePlugins, featureConfig, userRole = 'editor', children, }) {
     const notificationContext = useNotifications();
-    // Persist selected branch in sessionStorage so it survives provider remounts
-    // (e.g. when P1App is rendered per-page instead of in a shared layout).
-    const branchStorageKey = `css-branch-${siteId}`;
+    const branchStorageKey = `ccr-branch-${siteId}`;
+    const legacyBranchStorageKey = `css-branch-${siteId}`;
     const getPersistedBranchId = useCallback(() => {
         try {
-            return (typeof window !== 'undefined' && sessionStorage.getItem(branchStorageKey)) || '';
+            if (typeof window === 'undefined')
+                return '';
+            const persisted = sessionStorage.getItem(branchStorageKey);
+            if (persisted !== null)
+                return persisted;
+            const legacy = sessionStorage.getItem(legacyBranchStorageKey);
+            if (legacy !== null) {
+                sessionStorage.setItem(branchStorageKey, legacy);
+                sessionStorage.removeItem(legacyBranchStorageKey);
+            }
+            return legacy || '';
         }
         catch {
             return '';
         }
-    }, [branchStorageKey]);
+    }, [branchStorageKey, legacyBranchStorageKey]);
     const persistBranchId = useCallback((id) => {
         try {
             if (typeof window !== 'undefined') {
@@ -149,148 +80,70 @@ userRole = 'editor', children, }) {
             }
         }
         catch {
-            // sessionStorage may be unavailable (SSR, privacy mode)
         }
     }, [branchStorageKey]);
-    // Site name — fetched once on mount from the P1 API
     const [siteName, setSiteName] = useState(null);
     useEffect(() => {
         client.sites?.get(siteId)
             ?.then((site) => setSiteName(site.name))
             .catch(() => { });
     }, [client, siteId]);
-    // Outranks the prop (a build-time default) and sessionStorage (a previous
-    // visit): this names the workstream the user just asked for. refreshBranches
-    // validates it, so a stale or foreign id still falls back to main.
     const [deepLinkBranchId] = useState(readDeepLinkBranchId);
-    // Branch state - start with the deep link, initialBranchId, persisted branch,
-    // or empty (will be set to main)
     const [branchId, setBranchId] = useState(() => {
         if (deepLinkBranchId)
             return deepLinkBranchId;
         if (initialBranchId)
             return initialBranchId;
-        try {
-            return (typeof window !== 'undefined' && sessionStorage.getItem(branchStorageKey)) || '';
-        }
-        catch {
-            return '';
-        }
+        return getPersistedBranchId();
     });
     const [branches, setBranches] = useState([]);
+    const [branchResolutionError, setBranchResolutionError] = useState(null);
     const [currentBranch, setCurrentBranch] = useState(null);
     const [branchesLoading, setBranchesLoading] = useState(() => {
         if (deepLinkBranchId || initialBranchId)
             return false;
-        try {
-            return !(typeof window !== 'undefined' && sessionStorage.getItem(branchStorageKey));
-        }
-        catch {
-            return true;
-        }
+        return !getPersistedBranchId();
     });
-    // Persist before stripping: once the param is gone, a remount landing before
-    // the branch list resolves would otherwise fall back to a stale persisted
-    // branch. refreshBranches replaces this with a validated value.
     useEffect(() => {
         if (!deepLinkBranchId)
             return;
         persistBranchId(deepLinkBranchId);
         stripDeepLinkBranchParam();
     }, [deepLinkBranchId, persistBranchId]);
-    // Document state
     const [currentDocument, setCurrentDocument] = useState(null);
     const [currentData, setCurrentData] = useState(null);
     const [currentDataOrigin, setCurrentDataOrigin] = useState(null);
-    // True while loadDocument is in flight. Consumers use it to distinguish
-    // "no document while switching" (keep showing the old canvas) from
-    // "genuinely no document" (show the empty state).
     const [documentLoading, setDocumentLoading] = useState(false);
-    // Template state (PROPOSAL-010)
     const [currentTemplate, setCurrentTemplate] = useState(null);
-    // Save state
     const [saveStatus, setSaveStatus] = useState('idle');
     const [lastSaved, setLastSaved] = useState(null);
     const [saveError, setSaveError] = useState(null);
-    // Pending data for debounced save - use ref to avoid recreating debounce
     const pendingDataRef = useRef(null);
     const currentDocumentRef = useRef(null);
     const initializedRef = useRef(false);
-    // Track the latest Puck action metadata for inclusion in sync payloads.
-    // Buffered actions captured by handleAction (Puck's onAction callback)
-    // Array accumulates all structural actions during an edit session.
-    // Forwarded to backend on save for version history, then cleared.
     const pendingActionsRef = useRef([]);
-    // Tracks the document path that the current data in state belongs to.
-    // Set alongside every setCurrentData call to record the data's origin.
-    // Checked before every write (realtime or REST) to prevent cross-document
-    // corruption during rapid document switching.
     const currentDataDocumentPathRef = useRef(null);
     const currentDataOriginRef = useRef(null);
-    // Commit data and the identity it was loaded under in a single render pass.
-    //
-    // Path alone cannot distinguish two branches' copies of the same page, which
-    // is what let one workstream's data be published under another's sync key.
-    // Because both land in one commit, a consumer reading them together can never
-    // see a new identity beside old data.
     const commitCurrentData = useCallback((data, origin) => {
         currentDataDocumentPathRef.current = origin?.documentPath ?? null;
         currentDataOriginRef.current = origin;
         setCurrentDataOrigin(origin);
         setCurrentData(data);
     }, []);
-    // Snapshot of the data loadDocument just loaded. The first onChange after a
-    // load echoes this back; saveData drops that echo by structural compare
-    // (not a one-shot flag, which would swallow a lone genuine first edit like a
-    // pin toggle). Structural, not string: Puck re-normalizes key order.
     const suppressNextSaveRef = useRef(null);
-    // Monotonically increasing counter for stale loadDocument response detection.
-    // Each loadDocument call increments this and captures the current value.
-    // After each async operation, the captured value is compared to the current
-    // value — if they differ, a newer loadDocument call has started and the
-    // current one should bail out.
     const loadRequestIdRef = useRef(0);
-    // Track realtime connection state for use in performSave (avoids stale closure)
     const realtimeConnectedRef = useRef(false);
-    // Auto-save pause state
     const [autoSavePaused, setAutoSavePaused] = useState(false);
-    // Version viewing state
     const [viewingVersion, setViewingVersion] = useState(null);
-    // True while returnToLatest is fetching the latest version from the server,
-    // so the banner can show progress during the round trip.
     const [isReturningToLatest, setIsReturningToLatest] = useState(false);
-    // Last known "latest" snapshot — a write-only internal fallback for
-    // returnToLatest when no live Yjs snapshot is available and the server
-    // re-fetch fails. Backed by a ref (not state): nothing renders from it, so
-    // making it state would add a setState on every autosave and churn the
-    // context memo / returnToLatest identity for no consumer benefit.
     const latestVersionDataRef = useRef(null);
-    // Remote sync key - changes when remote updates arrive to trigger Puck sync
     const [remoteSyncKey, setRemoteSyncKey] = useState(null);
-    // Counter to track pending remote updates that will trigger onChange callbacks.
-    // When we receive a remote update and sync it to Puck via setData, Puck fires onChange.
-    // We need to skip the realtime send for that onChange to prevent bounce-back loops.
-    // Using a counter is more reliable than a timeout because it's synchronized with
-    // the actual number of remote updates received.
     const pendingRemoteUpdatesRef = useRef(0);
-    // Flag to track if we're currently applying a remote sync.
-    // This is set before setCurrentData and cleared after a short delay to ensure
-    // all related onChange events are skipped (there may be multiple: one from data
-    // prop change and one from setData dispatch).
-    // Pending remote data ref - stores latest data during debounce period
     const pendingRemoteDataRef = useRef(null);
-    // Debounce timer for remote sync - batches rapid updates to reduce flickering
     const remoteSyncTimerRef = useRef(null);
-    // Delay for debouncing remote sync updates (ms)
     const REMOTE_SYNC_DEBOUNCE_DELAY = 50;
-    // Ref to track viewingVersion for use in callbacks (avoids stale closure)
     const viewingVersionRef = useRef(null);
-    // Tracks the latest data seen by saveData when NOT viewing historical.
-    // Used by returnToLatest to restore unsaved edits that were in Puck's
-    // memory when the user navigated to a historical version.
     const latestLocalDataRef = useRef(null);
-    // Helper to cancel any pending remote sync - used when loading documents/versions
-    // This prevents race conditions where a pending remote update overrides loaded data
     const cancelPendingRemoteSync = useCallback(() => {
         if (remoteSyncTimerRef.current) {
             clearTimeout(remoteSyncTimerRef.current);
@@ -298,10 +151,8 @@ userRole = 'editor', children, }) {
         }
         pendingRemoteDataRef.current = null;
     }, []);
-    // WebSocket presence state - used when realtime is connected for instant presence updates
     const [wsPresenceActors, setWsPresenceActors] = useState([]);
     const [wsPresenceActive, setWsPresenceActive] = useState(false);
-    // Helper to enrich actors with display names from the resolver
     const enrichActorsWithNames = useCallback((actors) => {
         if (!userNameResolver)
             return actors;
@@ -310,7 +161,8 @@ userRole = 'editor', children, }) {
             return resolvedName ? { ...actor, name: resolvedName } : actor;
         });
     }, [userNameResolver]);
-    // Real-time collaboration hook
+    const [baselineResetKey, setBaselineResetKey] = useState(0);
+    const loadDocForResetRef = useRef(null);
     const realtime = useRealtime({
         baseUrl: wsBaseUrl ?? '',
         apiKey: realtimeApiKey,
@@ -322,47 +174,48 @@ userRole = 'editor', children, }) {
         actorType: 'user',
         enabled: enableRealtime && !!wsBaseUrl,
         initialData: currentData,
+        resetKey: baselineResetKey,
         onServerReload: () => {
             notificationContext.addInfo('Document is being refreshed by the server. Reconnecting...');
         },
-        // WebSocket presence callbacks - receive instant presence updates
+        onBaselineReset: () => {
+            notificationContext.addInfo('Your local changes could not be synced after a branch merge. Reconnecting with fresh content...');
+            const docPath = currentDocumentRef.current?.path;
+            if (!docPath)
+                return;
+            void loadDocForResetRef.current?.(docPath)
+                .then(() => {
+                setBaselineResetKey((k) => k + 1);
+            })
+                .catch(() => {
+                setBaselineResetKey((k) => k + 1);
+                notificationContext.addError('Could not reload content after a branch merge. Reconnecting — you may need to refresh if the editor stays blank.');
+            });
+        },
         onPresenceUpdate: (actors) => {
-            // Mark WebSocket presence as active (first update received)
             setWsPresenceActive(true);
-            // Filter out self, enrich with names, and update state
             const filtered = actors.filter((a) => a.actorId !== userId);
             const enriched = enrichActorsWithNames(filtered);
             setWsPresenceActors(enriched);
         },
         onFocusRegionBroadcast: (actorId, focusRegions) => {
-            // Update focus regions for the specific actor
             setWsPresenceActors((prev) => prev.map((a) => (a.actorId === actorId ? { ...a, focusRegions } : a)));
         },
         onRemoteUpdate: (data) => {
             if (viewingVersionRef.current !== null) {
                 return;
             }
-            // Reject empty data that would overwrite real editor content.
-            // During initial Yjs sync, the remote doc may be empty, producing
-            // { content: [], root: { props: {} } }. Applying this would clear
-            // the editor and trigger a save loop.
             const rootProps = data.root.props;
             if (data.content.length === 0 &&
                 (!rootProps || Object.keys(rootProps).length === 0) &&
                 !data.zones) {
                 return;
             }
-            // Store the latest data - will be used when debounce fires
             pendingRemoteDataRef.current = data;
-            // Clear any pending debounce timer
             if (remoteSyncTimerRef.current) {
                 clearTimeout(remoteSyncTimerRef.current);
             }
-            // Debounce the sync to batch rapid successive updates
-            // This prevents plugin recreation and flickering on every update
             remoteSyncTimerRef.current = setTimeout(() => {
-                // Double-check we're still not viewing a historical version
-                // (user might have switched while debounce was pending)
                 if (viewingVersionRef.current !== null) {
                     pendingRemoteDataRef.current = null;
                     remoteSyncTimerRef.current = null;
@@ -370,22 +223,10 @@ userRole = 'editor', children, }) {
                 }
                 const dataToSync = pendingRemoteDataRef.current;
                 if (dataToSync) {
-                    // Increment counter to skip the onChange echo(es) that will fire
-                    // when Puck processes the setCurrentData call below.
-                    // The content-based guards in puckDataToYMap and RealtimeClient
-                    // prevent actual echo loops at the Y.Doc/WebSocket layer.
                     pendingRemoteUpdatesRef.current += 1;
-                    // Update current data when remote changes arrive. Same document and
-                    // branch as whatever is loaded, but no longer a stored version — this
-                    // syncs through remoteSyncKey below, not the document-sync plugin.
                     commitCurrentData(dataToSync, originFor(currentDocumentRef.current, currentDataOriginRef.current?.branchId ?? null, null, currentDataOriginRef.current?.historical ?? false));
-                    // Update sync key to trigger Puck re-sync
                     setRemoteSyncKey(`remote-${Date.now()}`);
                     pendingRemoteDataRef.current = null;
-                    // Safety net: reset counter after React has processed the state updates.
-                    // If the remote data is identical to current editor state, Puck won't
-                    // fire onChange and the counter would never be decremented naturally.
-                    // Leaving it > 0 would cause subsequent local edits to be dropped.
                     setTimeout(() => {
                         pendingRemoteUpdatesRef.current = 0;
                     }, 100);
@@ -394,10 +235,8 @@ userRole = 'editor', children, }) {
             }, REMOTE_SYNC_DEBOUNCE_DELAY);
         },
     });
-    // Keep a stable ref to realtime for use in callbacks without dependency churn
     const realtimeRef = useRef(realtime);
     realtimeRef.current = realtime;
-    // Cleanup remote sync timer on unmount
     useEffect(() => {
         return () => {
             if (remoteSyncTimerRef.current) {
@@ -405,33 +244,16 @@ userRole = 'editor', children, }) {
             }
         };
     }, []);
-    // PuckDataCapture catch-up: detects data that Puck's onChange missed.
-    // Puck's onChange can miss the very last keystroke in a typing burst because
-    // createOnChange dispatches asynchronously (via resolveComponentData) and
-    // the Zustand subscriber may not fire for the final state update in time.
-    // PuckDataCapture subscribes to Puck's Zustand store independently via
-    // createUsePuck() and writes the true current data to this ref.
-    // The onDataChange callback debounces and compares with what saveData last
-    // sent — if they differ, it pushes the corrected data through realtime.
     const realtimeDataCaptureRef = useRef(null);
     const lastSentDataRef = useRef(null);
     const captureTimerRef = useRef(null);
-    // Track the last data sent via saveData so we can detect missed updates.
-    // Updated in saveData's realtime branch (the happy path).
     const trackSentData = useCallback((data) => {
         lastSentDataRef.current = JSON.stringify(data);
     }, []);
-    // Callback for PuckDataCapture.onDataChange — fires when Puck's store
-    // updates (may fire for changes that onChange misses).
     const handleRealtimeDataCapture = useCallback((data) => {
         if (!enableRealtime)
             return;
-        // Store the latest data in the ref for comparison when the timer fires.
-        // The ref always holds the most recent Zustand store snapshot.
         realtimeDataCaptureRef.current = data;
-        // Debounce: wait 800ms after the last store update to allow onChange
-        // to process normally. When the timer fires, compare the ref's current
-        // data (not the closure's stale copy) against what was last sent.
         if (captureTimerRef.current)
             clearTimeout(captureTimerRef.current);
         captureTimerRef.current = setTimeout(() => {
@@ -443,10 +265,8 @@ userRole = 'editor', children, }) {
             if (!currentData)
                 return;
             const dataJson = JSON.stringify(currentData);
-            // If saveData already sent this exact data, no catch-up needed
             if (dataJson === lastSentDataRef.current)
                 return;
-            // Data origin guard
             const currentPath = currentDocumentRef.current?.path ?? null;
             const dataOriginPath = currentDataDocumentPathRef.current;
             if (dataOriginPath !== currentPath)
@@ -455,31 +275,24 @@ userRole = 'editor', children, }) {
             lastSentDataRef.current = dataJson;
         }, 800);
     }, [enableRealtime]);
-    // Cleanup capture timer on unmount
     useEffect(() => {
         return () => {
             if (captureTimerRef.current)
                 clearTimeout(captureTimerRef.current);
         };
     }, []);
-    // Keep refs in sync with state
     useEffect(() => {
         currentDocumentRef.current = currentDocument;
     }, [currentDocument]);
     useEffect(() => {
         viewingVersionRef.current = viewingVersion;
     }, [viewingVersion]);
-    // Keep realtime connection ref in sync (used by performSave to avoid stale closure)
     useEffect(() => {
         realtimeConnectedRef.current = realtime.connected;
     }, [realtime.connected]);
-    // Create client with user principal
     const userClient = useMemo(() => client.withPrincipal({ id: userId, type: 'user' }), [client, userId]);
-    // Document list for current branch
-    const { documents: branchDocuments, loading: documentsLoading, create: createDocumentRaw, remove: removeDocumentRaw, refresh: refreshDocuments, } = useDocuments({ client: userClient, siteId, branchId });
-    // Template list for current branch
+    const { documents: branchDocuments, loading: documentsLoading, error: documentsError, create: createDocumentRaw, remove: removeDocumentRaw, refresh: refreshDocuments, } = useDocuments({ client: userClient, siteId, branchId });
     const { templates: branchTemplates, loading: templatesLoading, error: templatesError, refresh: refreshTemplates, } = useTemplateList(userClient, siteId, branchId);
-    // Stable document create/delete callbacks
     const branchIdRef = useRef(branchId);
     branchIdRef.current = branchId;
     const createDocumentRawRef = useRef(createDocumentRaw);
@@ -489,16 +302,10 @@ userRole = 'editor', children, }) {
             throw new Error('Cannot create document: no branch selected');
         }
         if (template) {
-            // The list endpoint carries no layout content; fetch the full template.
             const fullTemplate = await userClient.templates.get(siteId, branchIdRef.current, template.id);
-            // A template without a content array has no stored layout snapshot;
-            // creating a page from it would silently produce a blank page. An empty
-            // array is a legitimate empty layout and passes.
             if (!fullTemplate.content) {
                 throw new Error(`Template "${template.label || template.name}" has no layout yet. Open it in the editor and add components before creating pages from it.`);
             }
-            // The backend builds the initial version from the template, preserving
-            // each component's durable slot id; no client snapshot is sent.
             await createDocumentRawRef.current(path, undefined, {
                 templateId: fullTemplate.id,
                 templateVersion: fullTemplate.version,
@@ -509,14 +316,8 @@ userRole = 'editor', children, }) {
             await createDocumentRawRef.current(path, undefined, title ? { title } : undefined);
         }
     }, [userClient, siteId]);
-    // Stable update-template callback (template metadata: label/description/URL
-    // pattern). Used by the editor's template-mode right sidebar to persist details
-    // to the Template record, then refresh the list so the changes propagate.
     const refreshTemplatesRef = useRef(refreshTemplates);
     refreshTemplatesRef.current = refreshTemplates;
-    // Create a new template (empty layout, built in the template editor
-    // afterwards). Returns the created Template so callers can navigate to its
-    // editor. Used by the Create Page modal's "New template" flow.
     const stableCreateTemplate = useCallback(async (params) => {
         if (!branchIdRef.current) {
             throw new Error('Cannot create template: no branch selected');
@@ -530,7 +331,6 @@ userRole = 'editor', children, }) {
             throw new Error('Cannot update template: no branch selected');
         }
         const updated = await userClient.templates.update(siteId, branchIdRef.current, templateId, params);
-        // Keep the in-editor template in sync if it's the one being edited.
         setCurrentTemplate((prev) => (prev && prev.id === updated.id ? updated : prev));
         await refreshTemplatesRef.current();
     }, [userClient, siteId]);
@@ -542,78 +342,79 @@ userRole = 'editor', children, }) {
         }
         await removeDocumentRawRef.current(documentId);
     }, []);
-    // Load branches
     const refreshBranches = useCallback(async () => {
         try {
             setBranchesLoading(true);
+            setBranchResolutionError(null);
             const branchList = await userClient.branches.list(siteId);
             setBranches(branchList);
             let effectiveBranchId = branchIdRef.current;
-            // If no branchId set, try persisted branch, then default to main
             if (!effectiveBranchId) {
                 const persisted = getPersistedBranchId();
                 if (persisted && branchList.some((b) => b.id === persisted)) {
                     effectiveBranchId = persisted;
                 }
             }
-            // Validate that the branch exists in the list; fall back to main if not
             if (effectiveBranchId && !branchList.some((b) => b.id === effectiveBranchId)) {
                 const mainBranch = branchList.find((b) => b.isMain);
                 effectiveBranchId = mainBranch?.id ?? effectiveBranchId;
             }
-            // Default to main if still empty
             if (!effectiveBranchId) {
                 const mainBranch = branchList.find((b) => b.isMain);
                 if (mainBranch) {
                     effectiveBranchId = mainBranch.id;
                 }
             }
-            persistBranchId(effectiveBranchId);
-            setBranchId(effectiveBranchId);
+            if (!effectiveBranchId) {
+                setBranchResolutionError(new Error(`GET /api/sites/${siteId}/branches returned no usable branch. Check that the site id is correct and that the site has a main branch.`));
+            }
+            if (effectiveBranchId) {
+                persistBranchId(effectiveBranchId);
+                setBranchId(effectiveBranchId);
+            }
             setCurrentBranch(branchList.find((b) => b.id === effectiveBranchId) ?? null);
         }
         catch (error) {
+            setBranchResolutionError(describeRequestFailure(`GET /api/sites/${siteId}/branches`, error));
             console.error('Failed to load branches:', error);
+            if (showErrorNotifications && notificationContext?.addError) {
+                const message = error instanceof Error ? error.message : String(error);
+                notificationContext.addError(`Failed to load branches: ${message}`, () => void refreshBranchesRef.current?.());
+            }
         }
         finally {
             setBranchesLoading(false);
         }
-    }, [userClient, siteId, getPersistedBranchId, persistBranchId]);
+    }, [userClient, siteId, getPersistedBranchId, persistBranchId, showErrorNotifications, notificationContext]);
+    const refreshBranchesRef = useRef(refreshBranches);
+    refreshBranchesRef.current = refreshBranches;
     const createBranch = useCallback(async (name) => {
         const branch = await userClient.branches.create({ siteId, name });
         await refreshBranches();
         return branch;
     }, [userClient, siteId, refreshBranches]);
-    // Initial branch load - only once
     useEffect(() => {
         if (!initializedRef.current) {
             initializedRef.current = true;
             void refreshBranches();
         }
     }, [refreshBranches]);
-    // Perform save operation - uses refs to avoid dependency issues
     const performSave = useCallback(async (options) => {
         const dataToSave = pendingDataRef.current;
         const doc = currentDocumentRef.current;
         if (!dataToSave || !doc) {
             return;
         }
-        // Data origin guard: reject writes if data doesn't belong to current document
         if (currentDataDocumentPathRef.current !== doc.path) {
             pendingDataRef.current = null;
             return;
         }
-        // When realtime is connected, the DO handles persistence via WebSocket sync.
-        // Skip REST API save to avoid creating duplicate versions without CRDT state.
         if (enableRealtime && realtimeConnectedRef.current) {
-            // The data is already being sent via realtime.applyLocalChange in saveData.
-            // Mark as saved since the DO will persist it.
             pendingDataRef.current = null;
             setSaveStatus('saved');
             setLastSaved(new Date());
             return;
         }
-        // Fallback: REST API save when realtime is disabled or disconnected
         setSaveStatus('saving');
         setSaveError(null);
         try {
@@ -632,47 +433,33 @@ userRole = 'editor', children, }) {
                     : userClient.versions.create(siteId, params));
                 pendingActionsRef.current = [];
             }, { maxAttempts: maxRetries });
-            // Note: We intentionally do NOT call setCurrentData(dataToSave) here.
-            // The data is already in Puck's internal state (it came from Puck's onChange).
-            // Updating currentData would trigger a re-render cascade that recreates the
-            // p1Plugin, causing Puck to potentially re-render and flicker.
-            // currentData should only be updated when loading a document or switching versions.
             pendingDataRef.current = null;
             setSaveStatus('saved');
             setLastSaved(new Date());
-            // Keep the "latest" cache in sync with what was just persisted (REST
-            // success = confirmed persistence) so returning from a historical preview
-            // restores the correct content even if the on-return re-fetch fails.
             latestVersionDataRef.current = dataToSave;
         }
         catch (error) {
             setSaveStatus('error');
             const saveErr = error instanceof Error ? error : new Error(String(error));
             setSaveError(saveErr);
-            // Show error notification with retry action
             if (showErrorNotifications) {
                 notificationContext.addError(`Failed to save changes: ${saveErr.message}`, () => void performSave());
             }
         }
     }, [userClient, siteId, branchId, maxRetries, showErrorNotifications, notificationContext, enableRealtime]);
-    // Debounced save
     const debouncedSave = useMemo(() => debounce(() => {
         void performSave();
     }, autoSaveDelay), [performSave, autoSaveDelay]);
-    // Cleanup debounce on unmount
     useEffect(() => {
         return () => {
             debouncedSave.cancel();
         };
     }, [debouncedSave]);
-    // Best-effort flush of a pending debounced save when the tab is closed,
-    // navigated away from, or hidden.
     useEffect(() => {
         if (typeof window === 'undefined' || typeof document === 'undefined')
             return;
         const flushPendingSave = () => {
             if (pendingDataRef.current) {
-                // keepalive lets the POST finish after the page is discarded.
                 debouncedSave.cancel();
                 void performSave({ keepalive: true });
             }
@@ -691,19 +478,14 @@ userRole = 'editor', children, }) {
             document.removeEventListener('visibilitychange', handleVisibilityChange);
         };
     }, [debouncedSave, performSave]);
-    // Pause auto-save
     const pauseAutoSave = useCallback(() => {
         debouncedSave.pause();
         setAutoSavePaused(true);
     }, [debouncedSave]);
-    // Resume auto-save
     const resumeAutoSave = useCallback(() => {
         debouncedSave.resume();
         setAutoSavePaused(false);
     }, [debouncedSave]);
-    // Capture Puck action metadata from the onAction callback.
-    // This captures the action type and relevant metadata fields so they
-    // can be included in the sync payload for backend version storage.
     const handleAction = useCallback((action) => {
         const puckAction = {
             type: action.type || 'unknown',
@@ -728,28 +510,17 @@ userRole = 'editor', children, }) {
             pendingActionsRef.current = buffer.slice(-500);
         }
     }, []);
-    // Public save function (triggers debounce)
-    // Also resumes auto-save if paused, per user requirement
-    // Sends changes via WebSocket when realtime is enabled (but not for remote updates)
     const saveData = useCallback((data) => {
         if (suppressNextSaveRef.current !== null) {
             const loadedSnapshot = suppressNextSaveRef.current;
             suppressNextSaveRef.current = null;
-            // Drop only the echo; a structurally different first onChange is a real edit.
             if (isEqual(data, loadedSnapshot)) {
                 return;
             }
         }
-        // Only genuine user edits reach here — load/restore echoes arm
-        // suppressNextSaveRef before they fire and are returned early above.
         if (!viewingVersionRef.current) {
             latestLocalDataRef.current = data;
         }
-        // When realtime is enabled, detect whether this onChange came from a remote
-        // sync (Yjs update from another client) vs. a local user edit.
-        // Remote updates should NOT trigger a REST save — the DO handles persistence.
-        // Important: we must NOT set pendingDataRef for remote syncs, otherwise
-        // getHasUnsavedChanges() will incorrectly report unsaved changes.
         if (enableRealtime && realtime.connected) {
             if (pendingRemoteUpdatesRef.current > 0) {
                 pendingRemoteUpdatesRef.current -= 1;
@@ -760,26 +531,16 @@ userRole = 'editor', children, }) {
             }
             else {
                 const currentPath = currentDocumentRef.current?.path ?? null;
-                // Data origin guard: verify the data in state belongs to the
-                // current document. During rapid document switching, a stale
-                // loadDocument call can resolve and set data from document Y
-                // into state after currentDocument has been updated to X.
                 const dataOriginPath = currentDataDocumentPathRef.current;
                 if (dataOriginPath !== currentPath) {
                     console.warn('[P1PuckProvider] saveData SKIPPED: data origin mismatch.', 'dataOrigin:', dataOriginPath, 'currentDoc:', currentPath);
                     return;
                 }
-                // Connection identity guard: verify the realtime connection is
-                // bound to the same document we're currently editing.
                 const connectedPath = realtime.connectedDocumentPath;
                 if (currentPath !== connectedPath) {
                     console.warn('[P1PuckProvider] saveData SKIPPED: connection identity mismatch.', 'currentDoc:', currentPath, 'connectedDoc:', connectedPath);
                     return;
                 }
-                // Local user edit — send via WebSocket (DO handles persistence)
-                // Echo prevention is handled at lower layers:
-                // - puckDataToYMap no-ops when Y.Doc already has identical data
-                // - RealtimeClient.lastSentSnapshot drops sends matching last sent/received
                 const actions = pendingActionsRef.current;
                 if (actions.length > 0) {
                     realtime.applyLocalChange(data, actions);
@@ -789,21 +550,11 @@ userRole = 'editor', children, }) {
                 }
                 trackSentData(data);
                 pendingActionsRef.current = [];
-                // Data sent via WebSocket — DO handles persistence.
-                // Update save status directly (skip debouncedSave/performSave chain).
                 setSaveStatus('saved');
                 setLastSaved(new Date());
-                // NOTE: intentionally do NOT update latestVersionDataRef here. This
-                // is the optimistic local send, before the DO confirms persistence —
-                // caching it would assert content that may never be saved. Realtime
-                // returns use the live Yjs snapshot (or the server re-fetch), not
-                // this cache (PCC-3421).
                 return;
             }
         }
-        // Mirror the realtime guard: don't save when previewing a historical version.
-        // Without this, the PuckDataSynchronizer echo from loadVersion resumes the
-        // debounce and writes historical data to the server.
         if (viewingVersionRef.current !== null) {
             return;
         }
@@ -814,15 +565,12 @@ userRole = 'editor', children, }) {
         }
         debouncedSave();
     }, [debouncedSave, enableRealtime, realtime.connected, trackSentData]);
-    // Force immediate save
     const saveNow = useCallback(async () => {
         debouncedSave.cancel();
-        // When realtime is connected, ensure the latest data is sent via WebSocket
         if (enableRealtime && realtimeConnectedRef.current && pendingDataRef.current) {
             const currentPath = currentDocumentRef.current?.path ?? null;
             const dataOriginPath = currentDataDocumentPathRef.current;
             const connectedPath = realtime.connectedDocumentPath;
-            // Data origin + connection identity guards
             if (dataOriginPath === currentPath && currentPath === connectedPath) {
                 realtime.applyLocalChange(pendingDataRef.current);
                 pendingDataRef.current = null;
@@ -830,13 +578,9 @@ userRole = 'editor', children, }) {
                 setLastSaved(new Date());
                 return;
             }
-            // Fall through to REST save if mismatch
         }
         await performSave();
     }, [debouncedSave, performSave, enableRealtime]);
-    // Persist current in-memory edits as a REST version before a destructive operation.
-    // Realtime: confirms WebSocket delivery then snapshots latestLocalDataRef as a version.
-    // Non-realtime: delegates to performSave which creates a version from pendingDataRef.
     const persistCurrentEdits = useCallback(async () => {
         if (!enableRealtime || !realtimeConnectedRef.current) {
             await performSave();
@@ -862,55 +606,34 @@ userRole = 'editor', children, }) {
             }
         }
     }, [enableRealtime, realtime, performSave, userClient, siteId, branchId]);
-    // Load document by path
     const loadDocument = useCallback(async (path) => {
-        // Flush any pending debounced save while the outgoing document's
-        // identity is still current, then drop the pending buffer so a late
-        // debounce can never write one document's data into another.
         if (pendingDataRef.current) {
             debouncedSave.cancel();
             await performSave();
-            // performSave clears the buffer only on success; if it survived, the
-            // flush failed — abort the switch instead of discarding the edits.
             if (pendingDataRef.current) {
                 return;
             }
         }
         debouncedSave.cancel();
         pendingDataRef.current = null;
-        // Invalidate cached local edit so returnToLatest() doesn't treat it as unsaved.
         latestLocalDataRef.current = null;
-        // Cancel any pending remote sync to prevent race conditions
-        // where a stale remote update overrides the document we're loading
         cancelPendingRemoteSync();
-        // Increment load request counter and capture for staleness detection.
-        // If a newer loadDocument call starts before our awaits resolve, the
-        // counter will have been incremented again and our captured value
-        // will no longer match — signaling that our response is stale.
         loadRequestIdRef.current += 1;
         const thisRequestId = loadRequestIdRef.current;
         setDocumentLoading(true);
-        // Pre-clear the current document so nothing can save against the old
-        // one while the fetch is in flight. The canvas keeps showing the
-        // previous document — documentLoading suppresses the empty state.
         commitCurrentData(null, null);
         try {
-            const doc = await userClient.documents.getByPath(siteId, path.startsWith('/') ? path.slice(1) : path);
-            // Staleness check: a newer loadDocument call has started
+            const doc = await userClient.documents.getByPath(siteId, path.startsWith('/') ? path.slice(1) : path, branchId);
             if (thisRequestId !== loadRequestIdRef.current) {
                 console.debug('[P1PuckProvider] Stale loadDocument — skipping (after getByPath)');
                 return;
             }
-            // Use ID not path — paths may differ by normalization, causing a false disconnect.
-            // Same-doc keeps Yjs alive; cross-doc nulls out so useRealtime seeds a fresh Y.Doc.
             const isSameDocument = doc.id === currentDocumentRef.current?.id;
-            // Null data before identity update so useRealtime sees initialData=null.
             commitCurrentData(null, null);
             if (!isSameDocument) {
                 setCurrentDocument(null);
             }
             setCurrentDocument(doc);
-            // Fetch template if document is bound to one (PROPOSAL-010)
             if (doc.templateId) {
                 try {
                     if (!userClient.templates) {
@@ -927,81 +650,47 @@ userRole = 'editor', children, }) {
             else {
                 setCurrentTemplate(null);
             }
-            // Get latest version
             const version = await userClient.versions.getLatest(siteId, branchId, doc.id);
             const puckData = snapshotToPuckData(version.snapshot);
-            // Staleness check: a newer loadDocument call has started
             if (thisRequestId !== loadRequestIdRef.current) {
                 console.debug('[P1PuckProvider] Stale loadDocument — skipping (after getLatest)');
                 return;
             }
-            // Mark REST data as non-local to prevent the Puck onChange handler
-            // from echoing it back through the Y.Doc via applyLocalChange.
-            // This is critical after the Hibernatable WS migration because
-            // initializeIfNeeded() latency can invert the ordering of WebSocket
-            // initial state vs REST response, causing the remote-update guard
-            // (pendingRemoteUpdatesRef) to be bypassed.
             if (enableRealtime) {
                 pendingRemoteUpdatesRef.current += 1;
-                // Safety net: reset after React has processed the state updates.
-                // If Puck's data is identical to current editor state, onChange
-                // won't fire and the counter would never be decremented naturally.
-                // Leaving it > 0 would cause subsequent local edits to be dropped.
                 setTimeout(() => {
                     pendingRemoteUpdatesRef.current = 0;
                 }, 100);
             }
-            // IMPORTANT: Update the ref BEFORE state updates
-            // Setting to null allows remote updates after document loads
             viewingVersionRef.current = null;
-            // Cancel any pending PuckDataCapture catch-up timer and reset its
-            // ref before arming the data-origin guard below. Without this, the
-            // timer can fire in the window between currentDataDocumentPathRef
-            // being set to doc.path and the new document's first remote update
-            // arriving — passing the origin check while still carrying the
-            // previous document's Puck state.
             if (captureTimerRef.current) {
                 clearTimeout(captureTimerRef.current);
                 captureTimerRef.current = null;
             }
             realtimeDataCaptureRef.current = null;
             suppressNextSaveRef.current = puckData;
-            // branchId is the branch this load requested, deliberately not
-            // version.branchId: for an inherited document the backend serves main's
-            // published version, so the version names main while the payload is what
-            // the requested branch should display. Recording main here would make
-            // every consumer reject the payload as foreign.
             commitCurrentData(puckData, originFor(doc, branchId, version.id, false));
             latestVersionDataRef.current = puckData;
             setViewingVersion(null);
-            // Clear remoteSyncKey so document sync takes priority
             setRemoteSyncKey(null);
             pendingDataRef.current = null;
             setSaveStatus('idle');
             setSaveError(null);
         }
         catch (error) {
-            // Use warn, not error: callers handle this and console.error triggers
-            // the Next.js dev overlay unnecessarily.
             console.warn('[P1PuckProvider] loadDocument failed:', error);
-            // Unload the current document so VersionBannerOverride shows the empty
-            // state instead of the previous document's content.
             commitCurrentData(null, null);
             setCurrentDocument(null);
             throw error;
         }
         finally {
-            // Guarded so a stale call's completion can't clear the flag while a
-            // newer load is still in flight.
             if (thisRequestId === loadRequestIdRef.current) {
                 setDocumentLoading(false);
             }
         }
     }, [userClient, siteId, branchId, cancelPendingRemoteSync, enableRealtime, debouncedSave, performSave, commitCurrentData]);
-    // Load a specific version into the editor
+    loadDocForResetRef.current = loadDocument;
     const loadVersion = useCallback(async (version) => {
-        // Cancel any pending remote sync to prevent race conditions
-        // where a stale remote update overrides the version we're loading
         cancelPendingRemoteSync();
         try {
             const doc = currentDocumentRef.current;
@@ -1009,30 +698,19 @@ userRole = 'editor', children, }) {
                 throw new Error('No document loaded');
             }
             let versionToUse = version;
-            // If the version doesn't have snapshot data, try fetching it from the API
             if (!version.snapshot || Object.keys(version.snapshot).length === 0) {
                 try {
                     versionToUse = await userClient.versions.get(siteId, branchId, doc.id, version.id);
                 }
                 catch (fetchError) {
-                    // If fetching fails, log a warning and use the version as-is
                     console.warn('Could not fetch full version data, using version from list:', fetchError);
                 }
             }
-            // Parses a JSON-string snapshot and falls back to blank Puck data for
-            // an empty/invalid snapshot (e.g. version 1's initial blank state).
             const puckData = snapshotToPuckData(versionToUse.snapshot);
-            // IMPORTANT: Update the ref BEFORE state updates to block any incoming remote updates
-            // The effect that syncs viewingVersionRef runs AFTER render, which is too late
-            // Remote updates check this ref, so we need it set synchronously
             viewingVersionRef.current = versionToUse;
-            // Historical: the document-sync plugin must not push this into the
-            // canvas that owns the live undo stack — the version bridge handles it.
             commitCurrentData(puckData, originFor(doc, branchId, versionToUse.id, true));
             setViewingVersion(versionToUse);
-            // Clear remoteSyncKey so version sync takes priority
             setRemoteSyncKey(null);
-            // Pause auto-save when viewing historical version
             debouncedSave.pause();
             setAutoSavePaused(true);
             pendingDataRef.current = null;
@@ -1043,13 +721,8 @@ userRole = 'editor', children, }) {
             throw error;
         }
     }, [userClient, siteId, branchId, debouncedSave, cancelPendingRemoteSync, commitCurrentData]);
-    // Return to the latest version
     const returnToLatest = useCallback(async () => {
-        // Cancel any pending remote sync to prevent race conditions
-        // The latest data will be loaded fresh, then remote sync can resume
         cancelPendingRemoteSync();
-        // Get current state from Yjs if realtime is connected
-        // This ensures we get any changes made by other users while viewing history
         let dataToRestore = null;
         if (enableRealtime && realtime.connected) {
             const currentYjsData = realtime.getSnapshot();
@@ -1057,20 +730,12 @@ userRole = 'editor', children, }) {
                 dataToRestore = currentYjsData;
             }
         }
-        // 1. Edits typed inside the debounce window — cleared from pendingDataRef by loadVersion but still live here.
         const hadLocalEdits = !!latestLocalDataRef.current;
         dataToRestore ??= latestLocalDataRef.current;
-        latestLocalDataRef.current = null; // consume — prevents stale ref short-circuiting server fetch on next history visit
-        // Re-fetch the true latest from the server when no live Yjs snapshot is
-        // available. The cached latestVersionDataRef is only a last-resort fallback
-        // (e.g. no current document); it is NOT used on fetch failure — silently
-        // editing on a possibly-stale snapshot and resuming autosave is the exact
-        // data-loss path from PCC-3421. On failure we notify and abort instead,
-        // keeping the user in read-only preview so nothing is overwritten.
+        latestLocalDataRef.current = null;
         if (!dataToRestore) {
             const doc = currentDocumentRef.current;
             if (doc) {
-                // 2. Authoritative server state — the only source that reflects saves from other tabs, users, or agents.
                 setIsReturningToLatest(true);
                 try {
                     const version = await userClient.versions.getLatest(siteId, branchId, doc.id);
@@ -1088,16 +753,10 @@ userRole = 'editor', children, }) {
                     setIsReturningToLatest(false);
                 }
             }
-            // 3. No document context — can't fetch; use last value written by performSave.
             dataToRestore ??= latestVersionDataRef.current;
         }
         if (dataToRestore) {
-            // IMPORTANT: Update the ref BEFORE state updates
-            // Setting to null allows remote updates to resume
             viewingVersionRef.current = null;
-            // Suppress the PuckDataSynchronizer echo: setCurrentData triggers a setData
-            // dispatch and Puck fires onChange → saveData. Arm the ref so saveData drops
-            // that echo; we control the save explicitly below.
             suppressNextSaveRef.current = dataToRestore;
             if (enableRealtime) {
                 pendingRemoteUpdatesRef.current += 1;
@@ -1108,14 +767,9 @@ userRole = 'editor', children, }) {
             commitCurrentData(dataToRestore, originFor(currentDocumentRef.current, branchId, null, false));
             latestVersionDataRef.current = dataToRestore;
             setViewingVersion(null);
-            // Clear remoteSyncKey so latest version sync takes priority
             setRemoteSyncKey(null);
-            // Resume auto-save
             debouncedSave.resume();
             setAutoSavePaused(false);
-            // Only queue a save when restoring from local in-memory edits — those were
-            // never persisted. Data from the server fetch is already the latest saved
-            // version; queuing a save would create a spurious identical version.
             if (hadLocalEdits) {
                 pendingDataRef.current = dataToRestore;
                 debouncedSave();
@@ -1123,12 +777,7 @@ userRole = 'editor', children, }) {
             setSaveStatus('idle');
         }
     }, [debouncedSave, cancelPendingRemoteSync, enableRealtime, realtime, userClient, siteId, branchId, showErrorNotifications, notificationContext, commitCurrentData]);
-    // Computed property for whether viewing historical version
     const isViewingHistoricalVersion = viewingVersion !== null;
-    // =========================================================================
-    // Content Type Templates: Permission Resolution (PROPOSAL-010)
-    // =========================================================================
-    // Resolve template: either from document binding or registry path
     const resolvedTemplate = useMemo(() => {
         if (currentTemplate)
             return currentTemplate;
@@ -1140,17 +789,12 @@ userRole = 'editor', children, }) {
             return null;
         return branchTemplates.find((t) => t.name === match[1]) ?? null;
     }, [currentTemplate, currentDocument?.path, branchTemplates]);
-    // Create Puck permissions resolver based on current template and user role
     const resolvePermissions = useMemo(() => createPuckPermissions(resolvedTemplate, userRole, isViewingHistoricalVersion), [resolvedTemplate, userRole, isViewingHistoricalVersion]);
-    // Show notification when template list fails to load
     useEffect(() => {
         if (templatesError && showErrorNotifications && notificationContext?.addError) {
             notificationContext.addError(`Failed to load templates: ${templatesError.message}`, () => void refreshTemplates());
         }
     }, [templatesError]);
-    // =========================================================================
-    // Content Type Templates: Re-fetch template on tab focus (CUJ-15a)
-    // =========================================================================
     useEffect(() => {
         if (typeof document === 'undefined')
             return;
@@ -1169,37 +813,26 @@ userRole = 'editor', children, }) {
                 });
             }
             catch {
-                // Silently ignore — stale template is better than no template
             }
         };
         document.addEventListener('visibilitychange', handler);
         return () => document.removeEventListener('visibilitychange', handler);
     }, [siteId, userClient]);
-    // =========================================================================
-    // Phase 9: Presence & Agent Mode State
-    // =========================================================================
-    // Presence state (when presenceEnabled)
     const [presenceActors, setPresenceActors] = useState([]);
     const presenceInitializedRef = useRef(false);
-    // Track previous actors for onPresenceChange callback comparison
     const prevActorsRef = useRef([]);
-    // Conflict notifications state
     const [conflicts, setConflicts] = useState([]);
-    // Agent edit session state (when agentModeEnabled && agentId)
     const [agentSession, setAgentSession] = useState(null);
     const [agentEditLoading, setAgentEditLoading] = useState(false);
     const [agentEditError, setAgentEditError] = useState(null);
-    // Fetch presence data
     const fetchPresence = useCallback(async () => {
         if (!presenceEnabled || !branchId)
             return;
         try {
             const branchPresence = await userClient.presence.getBranchPresence(siteId, branchId);
-            // Filter out self and enrich with names
             const filteredActors = branchPresence.actors.filter((actor) => actor.actorId !== userId);
             const enrichedActors = enrichActorsWithNames(filteredActors);
             setPresenceActors(enrichedActors);
-            // Call onPresenceChange if actors changed
             if (onPresenceChange) {
                 const actorsChanged = JSON.stringify(enrichedActors.map((a) => a.id).sort()) !==
                     JSON.stringify(prevActorsRef.current.map((a) => a.id).sort());
@@ -1213,27 +846,19 @@ userRole = 'editor', children, }) {
             console.error('Failed to fetch presence:', error);
         }
     }, [presenceEnabled, branchId, siteId, userId, userClient, onPresenceChange, enrichActorsWithNames]);
-    // Keep fetchPresence in a ref to avoid restarting the interval when callback changes
     const fetchPresenceRef = useRef(fetchPresence);
     useEffect(() => {
         fetchPresenceRef.current = fetchPresence;
     }, [fetchPresence]);
-    // Initial presence fetch and polling
-    // HTTP polling is skipped when WebSocket presence is active and connected
     useEffect(() => {
         if (!presenceEnabled)
             return;
-        // Skip HTTP polling if WebSocket presence is handling updates
         const shouldSkipPolling = wsPresenceActive && realtime.connected;
-        // Initial fetch (only if WS isn't active yet)
         if (!presenceInitializedRef.current && !shouldSkipPolling) {
             presenceInitializedRef.current = true;
             void fetchPresenceRef.current();
         }
-        // Set up polling - use ref to avoid restarting interval when callback changes
-        // Skip polling when WebSocket is handling presence
         const intervalId = setInterval(() => {
-            // Check again at each interval - WS state may have changed
             if (!wsPresenceActive || !realtime.connected) {
                 void fetchPresenceRef.current();
             }
@@ -1242,29 +867,21 @@ userRole = 'editor', children, }) {
             clearInterval(intervalId);
         };
     }, [presenceEnabled, presencePollingInterval, realtime.connected]);
-    // Reset presence when disabled
     useEffect(() => {
         if (!presenceEnabled) {
             setPresenceActors([]);
             presenceInitializedRef.current = false;
         }
     }, [presenceEnabled]);
-    // Reset WebSocket presence state when disconnected so the UI falls back
-    // to HTTP-polled presence data. Without this, wsPresenceActive stays
-    // true after disconnect and the UI shows stale WebSocket presence
-    // (e.g. an agent that already completed its edit session still appears).
     useEffect(() => {
         if (!realtime.connected) {
             setWsPresenceActive(false);
             setWsPresenceActors([]);
         }
     }, [realtime.connected]);
-    // Compute derived presence values
-    // Prefer WebSocket presence when connected for instant updates
     const presenceState = useMemo(() => {
         if (!presenceEnabled)
             return null;
-        // Use WebSocket presence when active and connected, otherwise fall back to HTTP polling data
         const effectiveActors = wsPresenceActive && realtime.connected ? wsPresenceActors : presenceActors;
         const humans = effectiveActors.filter((actor) => actor.role === 'human');
         const agents = effectiveActors.filter((actor) => actor.role === 'agent');
@@ -1279,16 +896,10 @@ userRole = 'editor', children, }) {
             refresh: fetchPresence,
         };
     }, [presenceEnabled, presenceActors, wsPresenceActors, wsPresenceActive, realtime.connected, fetchPresence]);
-    // Keep presence in a ref so it can be read via getter without triggering
-    // context recreation. Presence changes frequently (focus region broadcasts)
-    // but shouldn't cause PuckDataSynchronizer or plugin re-renders.
     const presenceStateRef = useRef(presenceState);
     presenceStateRef.current = presenceState;
     const humanPresenceKey = presenceIdentityKey(presenceState?.humans);
     const agentPresenceKey = presenceIdentityKey(presenceState?.agents);
-    // =========================================================================
-    // Phase 9: Agent Edit Capabilities (when this client IS an agent)
-    // =========================================================================
     const agentEditCapabilities = useMemo(() => {
         if (!agentModeEnabled || !agentId)
             return null;
@@ -1395,11 +1006,7 @@ userRole = 'editor', children, }) {
         agentEditLoading,
         agentEditError,
     ]);
-    // =========================================================================
-    // Phase 9: Agent Trigger (for human users to trigger agents)
-    // =========================================================================
     const triggerAgentFn = useMemo(() => {
-        // Only available when agentModeEnabled but no agentId (human user)
         if (!agentModeEnabled || agentId)
             return null;
         const documentPath = currentDocument?.path ?? null;
@@ -1408,7 +1015,6 @@ userRole = 'editor', children, }) {
                 return { success: false, error: 'No document loaded' };
             }
             try {
-                // Check permission
                 const permission = await userClient.agentEdit.canEdit(siteId, branchId, documentPath, {
                     agentId: action.agentId,
                     trigger: 'human_requested',
@@ -1419,7 +1025,6 @@ userRole = 'editor', children, }) {
                 if (!permission.allowed) {
                     return { success: false, error: permission.reason };
                 }
-                // Start edit session
                 const session = await userClient.agentEdit.startEdit(siteId, branchId, documentPath, {
                     agentId: action.agentId,
                     trigger: 'human_requested',
@@ -1437,13 +1042,9 @@ userRole = 'editor', children, }) {
             }
         };
     }, [agentModeEnabled, agentId, currentDocument, siteId, branchId, userId, userClient]);
-    // =========================================================================
-    // Phase 9: Conflict Notifications
-    // =========================================================================
     const dismissConflict = useCallback((id) => {
         setConflicts((prev) => prev.filter((c) => c.id !== id));
     }, []);
-    // Stop an agent's edit session (human-initiated)
     const handleStopAgent = useCallback(async (agent) => {
         const documentPath = currentDocumentRef.current?.path;
         if (!documentPath) {
@@ -1453,7 +1054,6 @@ userRole = 'editor', children, }) {
         try {
             await userClient.agentEdit.stopAgent(siteId, branchId, documentPath, agent.actorId);
             notificationContext.addSuccess(`Agent "${agent.name}" has been stopped`);
-            // Refresh presence to reflect the agent's removal
             if (presenceEnabled) {
                 void fetchPresenceRef.current();
             }
@@ -1463,12 +1063,9 @@ userRole = 'editor', children, }) {
             notificationContext.addError(`Failed to stop agent: ${message}`);
         }
     }, [userClient, siteId, branchId, notificationContext, presenceEnabled]);
-    // Create checkpoint
     const createCheckpoint = useCallback(async (name) => {
-        // Save any pending changes first
         if (pendingDataRef.current) {
             if (enableRealtime && realtimeConnectedRef.current) {
-                // Data origin guard: only send if data belongs to current document
                 const currentPath = currentDocumentRef.current?.path ?? null;
                 if (currentDataDocumentPathRef.current === currentPath) {
                     realtime.applyLocalChange(pendingDataRef.current);
@@ -1480,8 +1077,6 @@ userRole = 'editor', children, }) {
                 await performSave();
             }
         }
-        // When realtime is connected, wait for the DO to acknowledge receipt of
-        // all preceding WebSocket messages before creating the checkpoint.
         if (enableRealtime && realtimeConnectedRef.current) {
             try {
                 await realtime.waitForDelivery();
@@ -1497,13 +1092,11 @@ userRole = 'editor', children, }) {
         });
         return checkpoint;
     }, [userClient, siteId, branchId, debouncedSave, performSave, enableRealtime, realtime]);
-    // Publish current document
     const publishDocument = useCallback(async () => {
         const doc = currentDocumentRef.current;
         if (!doc) {
             throw new Error('No document loaded to publish');
         }
-        // Send any pending changes before publish
         if (pendingDataRef.current) {
             if (enableRealtime && realtimeConnectedRef.current) {
                 const currentPath = currentDocumentRef.current?.path ?? null;
@@ -1517,10 +1110,6 @@ userRole = 'editor', children, }) {
                 await performSave();
             }
         }
-        // When realtime is connected, use WebSocket-driven publish.
-        // The DO handles the entire flow: flush CRDT to Postgres, then
-        // create the checkpoint. TCP ordering guarantees all preceding
-        // binary CRDT updates are processed before the publish_request.
         if (enableRealtime && realtimeConnectedRef.current) {
             const publishResult = await realtime.requestPublish();
             if (!publishResult.success) {
@@ -1531,61 +1120,29 @@ userRole = 'editor', children, }) {
             }
             return publishResult.checkpoint;
         }
-        // Fallback: HTTP publish when realtime is not connected
         const result = await userClient.documents.publish(siteId, branchId, doc.id);
         return result.checkpoint;
     }, [userClient, siteId, branchId, debouncedSave, performSave, enableRealtime, realtime]);
-    // Tracks the currently in-flight switchBranch flush (everything after the
-    // synchronous branch-selection commit), so a rapid re-selection can await
-    // the prior call instead of racing it. See switchBranch below.
     const switchBranchInFlightRef = useRef(null);
-    // Switch branch
     const switchBranch = useCallback(async (newBranchId) => {
-        // Commit the new workstream selection FIRST, synchronously, before the
-        // async save-flush below. The UI (WorkstreamSwitcher) fires this inside
-        // startTransition without awaiting it, so its "Switching..." busy state
-        // clears as soon as this function's synchronous portion returns — well
-        // before a save-flush of the outgoing document would resolve. If the
-        // user navigates to a different document in that window, this provider
-        // can remount (the editor route has no layout.tsx to shield it across
-        // param changes), and its branchId initializer re-reads sessionStorage.
-        // Persisting here — before the flush, not after — guarantees that read
-        // always sees the newly selected branch instead of a stale one,
-        // preventing the workstream selector from snapping back to Live/main.
         setBranchId(newBranchId);
         persistBranchId(newBranchId);
         const branch = branches.find((b) => b.id === newBranchId);
         setCurrentBranch(branch ?? null);
-        // Serialize the flush portion below against any switchBranch call
-        // still in flight. Because the branch commit above is synchronous but
-        // the flush is not, a rapid second call (the switcher fires onSwitch
-        // fire-and-forget, so its busy state clears well before the flush
-        // resolves) can otherwise start its own flush while pendingDataRef
-        // still holds the first call's outgoing edit — grabbing a performSave
-        // closure already pointed at the intermediate branch and saving that
-        // same edit a second time, to the wrong branch. Awaiting the prior
-        // in-flight flush first guarantees only one flush ever reads/clears
-        // pendingDataRef at a time, and that each flush's performSave targets
-        // the branch that was current when that flush actually started.
         const previousSwitch = switchBranchInFlightRef.current;
         const thisSwitch = (async () => {
             if (previousSwitch) {
-                // A prior switch's flush failure shouldn't block this one.
                 await previousSwitch.catch(() => undefined);
             }
-            // Cancel any pending remote sync - we're switching to a different branch
             cancelPendingRemoteSync();
-            // Save any pending changes on the outgoing document/branch first
             if (pendingDataRef.current) {
                 debouncedSave.cancel();
                 await performSave();
             }
-            // IMPORTANT: Update the ref BEFORE state updates
             viewingVersionRef.current = null;
             setCurrentDocument(null);
             commitCurrentData(null, null);
             setViewingVersion(null);
-            // Clear remoteSyncKey so new branch document sync takes priority
             setRemoteSyncKey(null);
             pendingDataRef.current = null;
             setSaveStatus('idle');
@@ -1601,7 +1158,6 @@ userRole = 'editor', children, }) {
             }
         }
     }, [branches, debouncedSave, performSave, cancelPendingRemoteSync, persistBranchId, commitCurrentData]);
-    // Presence context value (for hooks like useFocusRegionReporting)
     const presenceContextValue = useMemo(() => {
         if (!presenceEnabled)
             return null;
@@ -1621,8 +1177,6 @@ userRole = 'editor', children, }) {
                 ?.filter(a => a.state === 'editing')
                 ?.flatMap(a => a.focusRegions ?? []) ?? [],
             isAgentEditing: presenceState?.hasActiveAgents ?? false,
-            // Agent edit functions - placeholder implementations
-            // These are handled by agentEditCapabilities in the main context
             canEdit: async () => ({ allowed: true }),
             startEdit: async () => ({ sessionId: '' }),
             completeEdit: async () => ({ success: true }),
@@ -1639,13 +1193,6 @@ userRole = 'editor', children, }) {
         realtime.connected,
         presenceState,
     ]);
-    // =========================================================================
-    // Stable Callback Wrappers
-    // =========================================================================
-    // Wrap volatile callbacks in refs + stable wrappers so consumers don't need
-    // to stabilize them manually. The ref is updated inline during render (safe
-    // because it's a ref write, not a state write) and the stable wrapper
-    // delegates to ref.current, ensuring the latest implementation is always used.
     const saveDataRef = useRef(saveData);
     saveDataRef.current = saveData;
     const stableSaveData = useCallback((data) => saveDataRef.current(data), []);
@@ -1670,9 +1217,8 @@ userRole = 'editor', children, }) {
     const switchBranchRef = useRef(switchBranch);
     switchBranchRef.current = switchBranch;
     const stableSwitchBranch = useCallback((newBranchId) => switchBranchRef.current(newBranchId), []);
-    // Get pending actions for forwarding to backend
     const getPendingActions = useCallback(() => {
-        return [...pendingActionsRef.current]; // Return copy to prevent external mutation
+        return [...pendingActionsRef.current];
     }, []);
     const loadDocumentRef = useRef(loadDocument);
     loadDocumentRef.current = loadDocument;
@@ -1686,10 +1232,6 @@ userRole = 'editor', children, }) {
     const handleStopAgentRef = useRef(handleStopAgent);
     handleStopAgentRef.current = handleStopAgent;
     const stableStopAgent = useCallback((agent) => handleStopAgentRef.current(agent), []);
-    // =========================================================================
-    // Stable Getters (Items 2 & 3)
-    // =========================================================================
-    // Refs updated inline during render, exposed as stable getter callbacks.
     const saveStatusGetterRef = useRef(saveStatus);
     saveStatusGetterRef.current = saveStatus;
     const getSaveStatus = useCallback(() => saveStatusGetterRef.current, []);
@@ -1700,7 +1242,6 @@ userRole = 'editor', children, }) {
     saveErrorGetterRef.current = saveError;
     const getSaveError = useCallback(() => saveErrorGetterRef.current, []);
     const getHasUnsavedChanges = useCallback(() => pendingDataRef.current !== null, []);
-    // Data sync getters (Item 3)
     const currentDataGetterRef = useRef(currentData);
     currentDataGetterRef.current = currentData;
     const remoteSyncKeyGetterRef = useRef(remoteSyncKey);
@@ -1722,9 +1263,6 @@ userRole = 'editor', children, }) {
             return `doc-${doc.id}-latest`;
         return undefined;
     }, []);
-    // =========================================================================
-    // Plugin Composition (B.4)
-    // =========================================================================
     const resolvedFeatureConfig = useMemo(() => {
         if (featureConfig)
             return resolveFeatureConfig(featureConfig);
@@ -1735,7 +1273,7 @@ userRole = 'editor', children, }) {
         });
     }, [featureConfig, enableRealtime, presenceEnabled, agentModeEnabled]);
     const activePlugins = useMemo(() => {
-        const plugins = featurePlugins ?? DEFAULT_CSS_FEATURE_PLUGINS;
+        const plugins = featurePlugins ?? DEFAULT_CCR_FEATURE_PLUGINS;
         return resolveActivePlugins(plugins, resolvedFeatureConfig);
     }, [featurePlugins, resolvedFeatureConfig]);
     const pluginDeps = useMemo(() => ({
@@ -1746,16 +1284,12 @@ userRole = 'editor', children, }) {
         config: resolvedFeatureConfig,
     }), [userClient, siteId, branchId, userId, resolvedFeatureConfig]);
     const ComposedPluginProviders = useMemo(() => composeProviders(activePlugins, resolvedFeatureConfig, pluginDeps), [activePlugins, resolvedFeatureConfig, pluginDeps]);
-    // =========================================================================
-    // safeData (Item 4) — never null
-    // =========================================================================
     const EMPTY_PUCK_DATA = useMemo(() => ({ content: [], root: { props: {} } }), []);
     const lastGoodDataRef = useRef(EMPTY_PUCK_DATA);
     if (currentDocument && currentData) {
         lastGoodDataRef.current = currentData;
     }
     const safeData = lastGoodDataRef.current;
-    // Context value
     const contextValue = useMemo(() => ({
         client: userClient,
         notifications: notificationContext,
@@ -1777,16 +1311,13 @@ userRole = 'editor', children, }) {
         createCheckpoint: stableCreateCheckpoint,
         publishDocument: stablePublishDocument,
         switchBranch: stableSwitchBranch,
-        // Stable getters (Items 2, 3)
         getSaveStatus,
         getLastSaved,
         getSaveError,
         getHasUnsavedChanges,
         getSyncData,
         getDataSyncKey,
-        // safeData (Item 4)
         safeData,
-        // Documents (Item 8)
         documents: branchDocuments,
         documentsLoading,
         refreshDocuments,
@@ -1799,13 +1330,12 @@ userRole = 'editor', children, }) {
         refreshBranches,
         createBranch,
         branchesLoading,
+        branchResolutionError,
+        documentsError,
         autoSavePaused,
         pauseAutoSave: stablePauseAutoSave,
         resumeAutoSave: stableResumeAutoSave,
         viewingVersion,
-        // Exposed for type/back-compat only — nothing renders from it. Read from
-        // the ref; the memo already recomputes each save (via lastSaved), so this
-        // stays adequately fresh without being a reactive dependency.
         latestVersionData: latestVersionDataRef.current,
         isViewingHistoricalVersion,
         isReturningToLatest,
@@ -1814,16 +1344,9 @@ userRole = 'editor', children, }) {
         realtimeEnabled: enableRealtime,
         realtimeConnected: realtime.connected,
         remoteSyncKey,
-        // WebSocket presence - send focus regions via WebSocket when connected
         sendFocusRegions: realtime.sendFocusRegions,
-        // Puck action metadata capture - pass as onAction to <Puck>
         handleAction,
-        // Get pending actions for backend forwarding (PROPOSAL-010)
         getPendingActions,
-        // Phase 9: Presence & Agent values
-        // Use getter to avoid context recreation on every focus-region update.
-        // Expose humanPresenceCount/hasActiveHumans/hasActiveAgents directly so every
-        // join/leave triggers context re-renders and causes consumers to re-invoke the getter.
         get presence() { return presenceStateRef.current; },
         hasActiveHumans: presenceState?.hasActiveHumans ?? false,
         humanPresenceCount: presenceState?.humans.length ?? 0,
@@ -1833,12 +1356,9 @@ userRole = 'editor', children, }) {
         stopAgent: stableStopAgent,
         conflicts,
         dismissConflict,
-        // Feature configuration (Phase B.5)
         featureConfig: resolvedFeatureConfig,
-        // Internal: realtime data capture for catch-up (sends missed keystrokes)
         _realtimeDataCaptureRef: enableRealtime ? realtimeDataCaptureRef : null,
         _onRealtimeDataCapture: enableRealtime ? handleRealtimeDataCapture : null,
-        // Content Type Templates (PROPOSAL-010)
         userRole,
         templates: branchTemplates,
         templatesLoading,
@@ -1883,6 +1403,8 @@ userRole = 'editor', children, }) {
         currentBranch,
         refreshBranches,
         branchesLoading,
+        branchResolutionError,
+        documentsError,
         autoSavePaused,
         stablePauseAutoSave,
         stableResumeAutoSave,
@@ -1898,11 +1420,6 @@ userRole = 'editor', children, }) {
         handleAction,
         getPendingActions,
         handleRealtimeDataCapture,
-        // Phase 9 dependencies (full presenceState excluded — accessed via getter/ref,
-        // but humanPresenceCount/hasActiveHumans/hasActiveAgents are direct values so every
-        // join/leave triggers re-renders regardless of how many actors are present).
-        // The roster keys cover the changes a count cannot see: a same-frame join/leave of 
-        // two humans would keep the count the same but change the roster.
         humanPresenceKey,
         agentPresenceKey,
         presenceState?.humans.length,
@@ -1915,7 +1432,6 @@ userRole = 'editor', children, }) {
         dismissConflict,
         enableRealtime,
         resolvedFeatureConfig,
-        // Content Type Templates
         userRole,
         branchTemplates,
         templatesLoading,
@@ -1924,7 +1440,6 @@ userRole = 'editor', children, }) {
         currentTemplate,
         resolvePermissions,
     ]);
-    // Wrap with PresenceContext.Provider when presence is enabled
     const wrappedChildren = presenceContextValue ? (_jsx(PresenceContext.Provider, { value: presenceContextValue, children: children })) : (children);
     return (_jsx(P1PuckContext.Provider, { value: contextValue, children: _jsx(ComposedPluginProviders, { children: wrappedChildren }) }));
 }