@pantheon-systems/puck-css 0.7.0 → 0.9.0

package/dist/editor/P1PuckProvider.js

@@ -5,19 +5,21 @@ import { jsx as _jsx } from "react/jsx-runtime";
  * 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 isEqual from 'lodash.isequal';
 import { debounce } from '../core/utils/debounce.js';
 import { withRetry } from '../core/utils/retry.js';
-import { useRealtime } from './useRealtime.js';
-import { useDocuments } from './useDocuments.js';
 import { resolveFeatureConfig } from '../core/featureConfig.js';
-import { resolveActivePlugins, composeProviders } from './composePlugins.js';
-import { DEFAULT_CSS_FEATURE_PLUGINS } from './defaultPlugins.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 { resolveActivePlugins, composeProviders } from './composePlugins.js';
+import { snapshotToPuckData } from './utils/snapshotToPuckData.js';
+import { useDocuments } from './useDocuments.js';
+import { useRealtime } from './useRealtime.js';
 /**
  * Provider component for P1 Puck integration.
  *
@@ -126,6 +128,10 @@ userRole = 'editor', children, }) {
     // Document state
     const [currentDocument, setCurrentDocument] = useState(null);
     const [currentData, setCurrentData] = 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
@@ -192,6 +198,10 @@ userRole = 'editor', children, }) {
     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(() => {
@@ -394,14 +404,14 @@ userRole = 'editor', children, }) {
             // 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;
-            // scaffolding from it would silently create a blank page. An empty
+            // 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.`);
             }
-            const { scaffoldFromTemplate } = await import('../features/content-type-templates/editor/useTemplateScaffold.js');
-            const initialData = scaffoldFromTemplate(fullTemplate);
-            await createDocumentRawRef.current(path, initialData, {
+            // 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,
                 title,
@@ -642,6 +652,11 @@ userRole = 'editor', children, }) {
                 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.
@@ -698,6 +713,12 @@ userRole = 'editor', children, }) {
                 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;
+        }
         pendingDataRef.current = data;
         if (debouncedSave.isPaused()) {
             debouncedSave.resume();
@@ -725,6 +746,34 @@ userRole = 'editor', children, }) {
         }
         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();
+            return;
+        }
+        await realtime.waitForDelivery();
+        const latestData = latestLocalDataRef.current;
+        const doc = currentDocumentRef.current;
+        if (latestData && doc && currentDataDocumentPathRef.current === doc.path) {
+            setSaveStatus('saving');
+            try {
+                await userClient.versions.create(siteId, {
+                    documentId: doc.id,
+                    branchId,
+                    snapshot: latestData,
+                });
+                setSaveStatus('saved');
+                setLastSaved(new Date());
+            }
+            catch (err) {
+                setSaveStatus('error');
+                throw err;
+            }
+        }
+    }, [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
@@ -741,6 +790,8 @@ userRole = 'editor', children, }) {
         }
         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();
@@ -750,29 +801,28 @@ userRole = 'editor', children, }) {
         // will no longer match — signaling that our response is stale.
         loadRequestIdRef.current += 1;
         const thisRequestId = loadRequestIdRef.current;
-        // Pre-clear the current document immediately so the preview shows the
-        // empty state right away rather than stale content during the fetch.
+        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.
         currentDataDocumentPathRef.current = null;
         setCurrentData(null);
-        setCurrentDocument(null);
         try {
-            // Normalize path: strip leading slash if present
-            const normalizedPath = path.startsWith('/') ? path.slice(1) : path;
-            // Get document by path
-            const doc = await userClient.documents.getByPath(siteId, normalizedPath);
+            const doc = await userClient.documents.getByPath(siteId, path.startsWith('/') ? path.slice(1) : path);
             // Staleness check: a newer loadDocument call has started
             if (thisRequestId !== loadRequestIdRef.current) {
                 console.debug('[P1PuckProvider] Stale loadDocument — skipping (after getByPath)');
                 return;
             }
-            // Clear stale data BEFORE updating the document identity so that
-            // useRealtime's new useEffect sees initialData=null when it creates
-            // the fresh Y.Doc. Without this, currentData still holds the previous
-            // document's content when setCurrentDocument triggers the re-render,
-            // causing the new Y.Doc to be seeded with the wrong document's Yjs
-            // state — which the DO then commits as the first realtime version.
+            // 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.
             currentDataDocumentPathRef.current = null;
             setCurrentData(null);
+            if (!isSameDocument) {
+                setCurrentDocument(null);
+            }
             setCurrentDocument(doc);
             // Fetch template if document is bound to one (PROPOSAL-010)
             if (doc.templateId) {
@@ -793,7 +843,7 @@ userRole = 'editor', children, }) {
             }
             // Get latest version
             const version = await userClient.versions.getLatest(siteId, branchId, doc.id);
-            const puckData = version.snapshot;
+            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)');
@@ -851,6 +901,13 @@ userRole = 'editor', children, }) {
             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]);
     // Load a specific version into the editor
     const loadVersion = useCallback(async (version) => {
@@ -873,12 +930,9 @@ userRole = 'editor', children, }) {
                     console.warn('Could not fetch full version data, using version from list:', fetchError);
                 }
             }
-            let puckData = versionToUse.snapshot;
-            // If snapshot is empty or invalid, use blank Puck data
-            // This is expected for version 1 which represents the initial blank state
-            if (!puckData || (!puckData.content && !puckData.root)) {
-                puckData = { content: [], root: { props: {} } };
-            }
+            // 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
@@ -913,6 +967,10 @@ 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
@@ -922,8 +980,7 @@ userRole = 'editor', children, }) {
         if (!dataToRestore) {
             const doc = currentDocumentRef.current;
             if (doc) {
-                // Surface a loading state for the round trip — the editor is otherwise
-                // frozen on the historical snapshot with no indication.
+                // 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);
@@ -941,16 +998,16 @@ userRole = 'editor', children, }) {
                     setIsReturningToLatest(false);
                 }
             }
-        }
-        if (!dataToRestore) {
-            dataToRestore = latestVersionDataRef.current;
+            // 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 echo save so returning to latest does not itself create a
-            // duplicate version from the data we just loaded back in. 
+            // 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;
@@ -967,7 +1024,13 @@ userRole = 'editor', children, }) {
             // Resume auto-save
             debouncedSave.resume();
             setAutoSavePaused(false);
-            pendingDataRef.current = null;
+            // 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();
+            }
             setSaveStatus('idle');
         }
     }, [debouncedSave, cancelPendingRemoteSync, enableRealtime, realtime, userClient, siteId, branchId, showErrorNotifications, notificationContext]);
@@ -1132,6 +1195,8 @@ userRole = 'editor', children, }) {
     // 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)
     // =========================================================================
@@ -1381,31 +1446,72 @@ userRole = 'editor', children, }) {
         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) => {
-        // Cancel any pending remote sync - we're switching to a different branch
-        cancelPendingRemoteSync();
-        // Save any pending changes first
-        if (pendingDataRef.current) {
-            debouncedSave.cancel();
-            await performSave();
-        }
-        // IMPORTANT: Update the ref BEFORE state updates
-        viewingVersionRef.current = null;
+        // 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);
-        setCurrentDocument(null);
-        currentDataDocumentPathRef.current = null;
-        setCurrentData(null);
-        setViewingVersion(null);
-        // Clear remoteSyncKey so new branch document sync takes priority
-        setRemoteSyncKey(null);
-        pendingDataRef.current = null;
-        setSaveStatus('idle');
-        setSaveError(null);
-        // Update current branch
         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);
+            currentDataDocumentPathRef.current = null;
+            setCurrentData(null);
+            setViewingVersion(null);
+            // Clear remoteSyncKey so new branch document sync takes priority
+            setRemoteSyncKey(null);
+            pendingDataRef.current = null;
+            setSaveStatus('idle');
+            setSaveError(null);
+        })();
+        switchBranchInFlightRef.current = thisSwitch;
+        try {
+            await thisSwitch;
+        }
+        finally {
+            if (switchBranchInFlightRef.current === thisSwitch) {
+                switchBranchInFlightRef.current = null;
+            }
+        }
     }, [branches, debouncedSave, performSave, cancelPendingRemoteSync, persistBranchId]);
     // Presence context value (for hooks like useFocusRegionReporting)
     const presenceContextValue = useMemo(() => {
@@ -1458,6 +1564,9 @@ userRole = 'editor', children, }) {
     const saveNowRef = useRef(saveNow);
     saveNowRef.current = saveNow;
     const stableSaveNow = useCallback(() => saveNowRef.current(), []);
+    const persistCurrentEditsRef = useRef(persistCurrentEdits);
+    persistCurrentEditsRef.current = persistCurrentEdits;
+    const stablePersistCurrentEdits = useCallback(() => persistCurrentEditsRef.current(), []);
     const createCheckpointRef = useRef(createCheckpoint);
     createCheckpointRef.current = createCheckpoint;
     const stableCreateCheckpoint = useCallback((name) => createCheckpointRef.current(name), []);
@@ -1568,12 +1677,14 @@ userRole = 'editor', children, }) {
         userId,
         currentDocument,
         currentData,
+        documentLoading,
         saveStatus,
         lastSaved,
         saveError,
         loadDocument: stableLoadDocument,
         saveData: stableSaveData,
         saveNow: stableSaveNow,
+        persistCurrentEdits: stablePersistCurrentEdits,
         createCheckpoint: stableCreateCheckpoint,
         publishDocument: stablePublishDocument,
         switchBranch: stableSwitchBranch,
@@ -1654,12 +1765,14 @@ userRole = 'editor', children, }) {
         userId,
         currentDocument,
         currentData,
+        documentLoading,
         saveStatus,
         lastSaved,
         saveError,
         stableLoadDocument,
         stableSaveData,
         stableSaveNow,
+        stablePersistCurrentEdits,
         stableCreateCheckpoint,
         stablePublishDocument,
         stableSwitchBranch,
@@ -1697,7 +1810,11 @@ userRole = 'editor', children, }) {
         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)
+        // 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,
         presenceState?.hasActiveHumans,
         presenceState?.hasActiveAgents,