@pantheon-systems/puck-css 0.4.0

package/dist/editor/useP1Plugin.js

@@ -0,0 +1,112 @@
+/**
+ * useP1Plugin Hook
+ *
+ * Creates a referentially stable CSS plugin instance for Puck.
+ * Internally reads context values and wires them through a Proxy pattern
+ * so the plugin object never changes identity, avoiding Puck re-renders.
+ */
+import { useRef, useMemo } from 'react';
+import { useP1Puck } from '../core/P1PuckContext.js';
+import { createP1Plugin } from './plugin/P1Plugin.js';
+/**
+ * Creates a referentially stable CSS plugin for Puck.
+ *
+ * Reads branches, documents, and other state from P1PuckProvider context.
+ * The returned plugin object is stable across re-renders — it uses a Proxy
+ * pattern to always delegate to the latest options without changing identity.
+ *
+ * Must be used inside a P1PuckProvider.
+ *
+ * @param options - Optional customization (selection tracking, version display, etc.)
+ * @returns A stable PuckPlugin instance
+ *
+ * @example
+ * ```tsx
+ * function Editor() {
+ *   const plugin = useP1Plugin();
+ *   return <Puck plugins={[plugin]} config={config} data={data} />;
+ * }
+ * ```
+ */
+export function useP1Plugin(options = {}) {
+    const css = useP1Puck();
+    const fc = css.featureConfig ?? {
+        enableBranchSelector: true,
+        enableDocumentBrowser: true,
+        enableVersionHistory: true,
+        enableMergeControl: true,
+        enableAutoSave: true,
+        enablePublishButton: true,
+        enableCollaboratorAvatars: true,
+        enableAgentBanner: true,
+        enableFocusHighlighting: true,
+        enableRealtime: true,
+        presenceEnabled: true,
+        agentModeEnabled: false,
+    };
+    // Build the full plugin options from context + consumer options,
+    // gating features by the resolved featureConfig flags.
+    const pluginOptions = {
+        branches: fc.enableBranchSelector ? css.branches : [],
+        currentBranch: fc.enableBranchSelector ? css.currentBranch : null,
+        onBranchSwitch: fc.enableBranchSelector ? css.switchBranch : () => { },
+        getHasUnsavedChanges: css.getHasUnsavedChanges,
+        documents: fc.enableDocumentBrowser ? css.documents : [],
+        selectedDocumentPath: options.selectedDocumentPath ?? css.currentDocument?.path ?? null,
+        onDocumentSelect: fc.enableDocumentBrowser
+            ? (options.onDocumentSelect ?? css.loadDocument) : undefined,
+        onDocumentCreate: fc.enableDocumentBrowser
+            ? (options.onDocumentCreate ?? css.createDocument) : undefined,
+        onDocumentDelete: fc.enableDocumentBrowser
+            ? (options.onDocumentDelete ?? css.deleteDocument) : undefined,
+        documentsLoading: css.documentsLoading,
+        versions: fc.enableVersionHistory ? options.versions : undefined,
+        versionsLoading: fc.enableVersionHistory ? options.versionsLoading : false,
+        selectedVersionId: fc.enableVersionHistory ? options.selectedVersionId : undefined,
+        onVersionSelect: fc.enableVersionHistory ? options.onVersionSelect : undefined,
+        // Context-based sync is the default — no need for getter or legacy sync
+        useContextSync: true,
+        // Selection tracking
+        onSelectionChange: options.onSelectionChange,
+        // Merge comparison — gated by enableMergeControl
+        puckConfig: options.puckConfig,
+        onCompareWithLive: fc.enableMergeControl ? options.onCompareWithLive : undefined,
+        // Presence/Agent features — gated by featureConfig flags
+        showPresenceIndicator: fc.enableCollaboratorAvatars
+            ? options.showPresenceIndicator : false,
+        presence: fc.enableCollaboratorAvatars
+            ? (options.presence ?? css.presence?.actors) : undefined,
+        showAgentActivity: fc.enableAgentBanner ? options.showAgentActivity : false,
+        activeAgents: fc.enableAgentBanner
+            ? (options.activeAgents ?? css.presence?.agents?.filter(a => a.state === 'editing'))
+            : undefined,
+        showAgentActions: options.showAgentActions,
+        availableAgents: options.availableAgents,
+        onAgentAction: options.onAgentAction,
+        onStopAgent: css.stopAgent,
+        showFocusRegions: fc.enableFocusHighlighting ? options.showFocusRegions : false,
+        agentEditingRegions: options.agentEditingRegions,
+        // P1 Editor Header / Subheader
+        siteName: options.siteName,
+        siteMenuItems: options.siteMenuItems,
+        currentUser: options.currentUser,
+        onLogout: options.onLogout,
+        onPublish: fc.enablePublishButton ? options.onPublish : undefined,
+        onReviewAndPublish: options.onReviewAndPublish,
+        onCreateWorkstream: options.onCreateWorkstream,
+        onCreateBranch: options.onCreateBranch,
+    };
+    // Store options in a ref updated each render
+    const optionsRef = useRef(pluginOptions);
+    optionsRef.current = pluginOptions;
+    // Create a stable Proxy-backed options object that always reads from the ref
+    const stableOptions = useMemo(() => new Proxy({}, {
+        get(_target, prop) {
+            return optionsRef.current[prop];
+        },
+    }), []);
+    // Create plugin once with stable proxy options
+    const plugin = useMemo(() => createP1Plugin(stableOptions), [stableOptions]);
+    return plugin;
+}
+//# sourceMappingURL=useP1Plugin.js.map

package/dist/editor/useP1Plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useP1Plugin.js","sourceRoot":"","sources":["../../src/editor/useP1Plugin.ts"],"names":[],"mappings":"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"}

package/dist/editor/useRealtime.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Phase 3.2: useRealtime Hook
+ *
+ * React hook for real-time collaborative editing with Puck.
+ * Manages WebSocket connection and Yjs CRDT synchronization.
+ */
+import type { PuckData, ActorPresence, ActorState, PublishResult } from '@pantheon-systems/css-client';
+/**
+ * Parameters for the useRealtime hook.
+ */
+export interface UseRealtimeParams {
+    /** WebSocket base URL (ws:// or wss://) */
+    baseUrl: string;
+    /** API key for authentication */
+    apiKey?: string;
+    /** Site ID */
+    siteId: string;
+    /** Branch ID */
+    branchId: string;
+    /** Document path (null means no document loaded yet) */
+    documentPath: string | null;
+    /** Actor ID (user or agent ID) */
+    actorId: string;
+    /** Actor type */
+    actorType: 'user' | 'agent';
+    /**
+     * Session ID for agent authorization.
+     * Obtained from startEdit() response.
+     * When provided, enables server-side enforcement of Agent Politeness Protocol.
+     */
+    sessionId?: string;
+    /**
+     * Initial data to seed the Y.Doc with before connecting.
+     * When provided, the Y.Doc will be populated with this data before
+     * the WebSocket connects, allowing the server to send only a delta
+     * instead of the full CRDT state. This eliminates the redundant
+     * full-doc re-render on page load.
+     *
+     * Tracked via ref (not in effect deps) to avoid triggering reconnection
+     * when data changes during editing.
+     */
+    initialData?: PuckData | null;
+    /** Whether real-time is enabled */
+    enabled?: boolean;
+    /** Callback when remote changes arrive */
+    onRemoteUpdate?: (data: PuckData) => void;
+    /**
+     * Callback when presence update is received from server via WebSocket.
+     * Called with the full list of actors in the document.
+     */
+    onPresenceUpdate?: (actors: ActorPresence[]) => void;
+    /**
+     * Callback when another actor updates their focus regions.
+     * Called with the actor ID and their new focus regions.
+     */
+    onFocusRegionBroadcast?: (actorId: string, focusRegions: string[]) => void;
+    /**
+     * Optional token refresher for WebSocket reconnection.
+     * Called when the WebSocket connection closes unexpectedly.
+     * Should return a fresh token or null if the session cannot be refreshed.
+     */
+    tokenRefresher?: () => Promise<string | null>;
+}
+/**
+ * Return value from the useRealtime hook.
+ */
+export interface UseRealtimeReturn {
+    /** Whether currently connected to the real-time session */
+    connected: boolean;
+    /** Apply a local change (will be synced to other clients) */
+    applyLocalChange: (data: PuckData, actionMeta?: {
+        actionType: string;
+        actionMetadata: Record<string, unknown>;
+    }) => void;
+    /** Get the current snapshot from the Yjs document. Returns null if not connected. */
+    getSnapshot: () => PuckData | null;
+    /** Any error that occurred */
+    error: Error | null;
+    /**
+     * Send focus regions update to the server.
+     * @param regions - JSON paths the actor is focused on
+     * @returns true if message was sent, false if not connected
+     */
+    sendFocusRegions: (regions: string[]) => boolean;
+    /**
+     * Send a presence heartbeat to keep the connection alive.
+     * @param state - Optional state update (active, idle, editing)
+     */
+    sendHeartbeat: (state?: ActorState) => void;
+    /**
+     * Whether presence updates are available via WebSocket.
+     * Returns true when connected and able to send/receive presence messages.
+     */
+    presenceViaWebSocket: boolean;
+    /**
+     * The document path that the realtime connection is currently bound to.
+     * Captured at the moment of connection establishment. Returns null when
+     * disconnected or during connection transitions. Used by callers to verify
+     * that data being sent matches the active connection's document.
+     */
+    connectedDocumentPath: string | null;
+    /**
+     * Wait for the server to acknowledge that all preceding WebSocket messages
+     * have been processed. Used before publish to ensure the DO has the latest edits.
+     * @returns Promise that resolves when the server confirms delivery
+     * @throws Error if not connected or if timeout expires
+     */
+    waitForDelivery: () => Promise<void>;
+    /**
+     * Request the server to publish the current document via WebSocket.
+     * The Durable Object handles flush + publish internally, eliminating
+     * client-side orchestration and race conditions.
+     * @returns Promise that resolves with the publish result
+     * @throws Error if not connected or if timeout expires
+     */
+    requestPublish: () => Promise<PublishResult>;
+}
+/**
+ * Hook for real-time collaborative editing with Puck.
+ *
+ * @example
+ * ```tsx
+ * function Editor() {
+ *   const realtime = useRealtime({
+ *     baseUrl: 'wss://api.example.com',
+ *     siteId: 'site-123',
+ *     branchId: 'branch-456',
+ *     documentPath: 'pages/home',
+ *     actorId: 'user-789',
+ *     actorType: 'user',
+ *     enabled: true,
+ *     onRemoteUpdate: (data) => setPuckData(data),
+ *   });
+ *
+ *   return (
+ *     <Puck
+ *       data={puckData}
+ *       onChange={(data) => {
+ *         setPuckData(data);
+ *         realtime.applyLocalChange(data);
+ *       }}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export declare function useRealtime(params: UseRealtimeParams): UseRealtimeReturn;
+//# sourceMappingURL=useRealtime.d.ts.map

package/dist/editor/useRealtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRealtime.d.ts","sourceRoot":"","sources":["../../src/editor/useRealtime.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAMvG;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAEhB,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,cAAc;IACd,MAAM,EAAE,MAAM,CAAC;IAEf,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IAEjB,wDAAwD;IACxD,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5B,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAEhB,iBAAiB;IACjB,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IAE5B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IAE9B,mCAAmC;IACnC,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,0CAA0C;IAC1C,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAC;IAE1C;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,IAAI,CAAC;IAErD;;;OAGG;IACH,sBAAsB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAE3E;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC/C;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,2DAA2D;IAC3D,SAAS,EAAE,OAAO,CAAC;IAEnB,6DAA6D;IAC7D,gBAAgB,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,UAAU,CAAC,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,KAAK,IAAI,CAAC;IAEzH,qFAAqF;IACrF,WAAW,EAAE,MAAM,QAAQ,GAAG,IAAI,CAAC;IAEnC,8BAA8B;IAC9B,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAEpB;;;;OAIG;IACH,gBAAgB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC;IAEjD;;;OAGG;IACH,aAAa,EAAE,CAAC,KAAK,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC;IAE5C;;;OAGG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAE9B;;;;;OAKG;IACH,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;IAErC;;;;;OAKG;IACH,eAAe,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAErC;;;;;;OAMG;IACH,cAAc,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC;CAC9C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,iBAAiB,CAkPxE"}

package/dist/editor/useRealtime.js

@@ -0,0 +1,244 @@
+/**
+ * Phase 3.2: useRealtime Hook
+ *
+ * React hook for real-time collaborative editing with Puck.
+ * Manages WebSocket connection and Yjs CRDT synchronization.
+ */
+import { useState, useEffect, useLayoutEffect, useRef, useCallback } from 'react';
+import { RealtimeClient } from '@pantheon-systems/css-client';
+import { createPuckYjsBinding, } from './utils/puckYjsBinding.js';
+/**
+ * Hook for real-time collaborative editing with Puck.
+ *
+ * @example
+ * ```tsx
+ * function Editor() {
+ *   const realtime = useRealtime({
+ *     baseUrl: 'wss://api.example.com',
+ *     siteId: 'site-123',
+ *     branchId: 'branch-456',
+ *     documentPath: 'pages/home',
+ *     actorId: 'user-789',
+ *     actorType: 'user',
+ *     enabled: true,
+ *     onRemoteUpdate: (data) => setPuckData(data),
+ *   });
+ *
+ *   return (
+ *     <Puck
+ *       data={puckData}
+ *       onChange={(data) => {
+ *         setPuckData(data);
+ *         realtime.applyLocalChange(data);
+ *       }}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function useRealtime(params) {
+    const { baseUrl, apiKey, tokenRefresher, siteId, branchId, documentPath, actorId, actorType, sessionId, enabled = true, onRemoteUpdate, onPresenceUpdate, onFocusRegionBroadcast, } = params;
+    const [connected, setConnected] = useState(false);
+    const [error, setError] = useState(null);
+    const [presenceViaWebSocket, setPresenceViaWebSocket] = useState(false);
+    // Track the document path that the active connection is bound to.
+    // Captured at connection time, cleared on disconnect. Used to prevent
+    // cross-document state bleed: callers can compare this against their
+    // current document path before sending data through the binding.
+    const connectedDocumentPathRef = useRef(null);
+    // Refs to avoid recreating callbacks
+    const clientRef = useRef(null);
+    const bindingRef = useRef(null);
+    const onRemoteUpdateRef = useRef(onRemoteUpdate);
+    const onPresenceUpdateRef = useRef(onPresenceUpdate);
+    const onFocusRegionBroadcastRef = useRef(onFocusRegionBroadcast);
+    // Keep tokenRefresher in a ref so the RealtimeClient always calls the
+    // latest version without needing to be recreated on reference changes.
+    const tokenRefresherRef = useRef(tokenRefresher);
+    tokenRefresherRef.current = tokenRefresher;
+    const initialDataRef = useRef(params.initialData);
+    // Keep ref in sync but do NOT add to effect deps — changing data
+    // during editing must not trigger a WebSocket reconnection.
+    initialDataRef.current = params.initialData;
+    // Keep callback refs up to date
+    useEffect(() => {
+        onRemoteUpdateRef.current = onRemoteUpdate;
+    }, [onRemoteUpdate]);
+    useEffect(() => {
+        onPresenceUpdateRef.current = onPresenceUpdate;
+    }, [onPresenceUpdate]);
+    useEffect(() => {
+        onFocusRegionBroadcastRef.current = onFocusRegionBroadcast;
+    }, [onFocusRegionBroadcast]);
+    // Eagerly clean up binding and client refs when dependencies change.
+    // useLayoutEffect cleanup runs BEFORE regular useEffect callbacks (including
+    // children's effects like PuckDataSynchronizer). This prevents a race condition
+    // where PuckDataSynchronizer dispatches setData during a document switch, Puck
+    // fires onChange, and saveData sends data through a stale binding that still
+    // points to the previous document's Y.Doc — causing cross-document state bleed.
+    useLayoutEffect(() => {
+        return () => {
+            connectedDocumentPathRef.current = null;
+            bindingRef.current?.destroy();
+            bindingRef.current = null;
+            clientRef.current?.disconnect();
+            clientRef.current = null;
+        };
+    }, [baseUrl, apiKey, siteId, branchId, documentPath, actorId, actorType, sessionId, enabled]);
+    // Effect to manage connection lifecycle
+    useEffect(() => {
+        // Don't connect if disabled, no document path, or missing required params
+        if (!enabled || !documentPath || !branchId || !siteId) {
+            return;
+        }
+        // Create new client
+        // NOTE: We don't use RealtimeClient.onUpdate because it would cause double callbacks.
+        // The Puck-Yjs binding observer already handles remote updates properly by checking
+        // transaction origin to distinguish local vs remote changes.
+        const client = new RealtimeClient({
+            baseUrl,
+            apiKey,
+            // Use ref-wrapped refresher so the client always calls the latest version
+            // without needing to be recreated when the function reference changes.
+            tokenRefresher: tokenRefresherRef.current
+                ? () => {
+                    const refresher = tokenRefresherRef.current;
+                    return refresher ? refresher() : Promise.resolve(null);
+                }
+                : undefined,
+            onConnect: () => {
+                // Guard: ignore callbacks from stale clients.
+                // When dependencies change, the old client is destroyed and a new one
+                // created. The old WebSocket's close event fires asynchronously and may
+                // arrive AFTER the new client has already connected. Without this guard,
+                // the stale onDisconnect would overwrite the new client's connection
+                // state (connectedDocumentPathRef, connected, presenceViaWebSocket),
+                // permanently breaking sync in one direction and corrupting presence.
+                if (clientRef.current !== client)
+                    return;
+                // Capture the document path this connection is bound to.
+                // documentPath here is from the effect closure — it's the value
+                // that was current when this effect ran, which is the document
+                // the WebSocket was created for.
+                connectedDocumentPathRef.current = documentPath;
+                setConnected(true);
+                setPresenceViaWebSocket(true);
+                setError(null);
+            },
+            onDisconnect: () => {
+                // Guard: ignore callbacks from stale clients (see onConnect comment).
+                if (clientRef.current !== client)
+                    return;
+                connectedDocumentPathRef.current = null;
+                setConnected(false);
+                setPresenceViaWebSocket(false);
+            },
+            onError: (err) => {
+                setError(err);
+            },
+            // onUpdate intentionally omitted - binding handles this
+            onPresenceUpdate: (actors) => {
+                onPresenceUpdateRef.current?.(actors);
+            },
+            onFocusRegionBroadcast: (actorId, focusRegions) => {
+                onFocusRegionBroadcastRef.current?.(actorId, focusRegions);
+            },
+        });
+        clientRef.current = client;
+        // Create Puck-Yjs binding - this is the ONLY place that calls onRemoteUpdate
+        // The binding observes Yjs changes and filters out local changes (origin === 'local')
+        const binding = createPuckYjsBinding(client.getYDoc(), (data) => {
+            onRemoteUpdateRef.current?.(data);
+        });
+        bindingRef.current = binding;
+        // Seed Y.Doc with initial REST data before connecting.
+        // This populates the client's Y.Doc so the server can send a delta
+        // instead of the full CRDT state on initial connect.
+        // Safe because:
+        // - applyLocalChange uses LOCAL_ORIGIN (observer ignores local changes)
+        // - this.ws is null at this point (update listener won't try to send)
+        if (initialDataRef.current) {
+            binding.applyLocalChange(initialDataRef.current);
+        }
+        // Connect to the document session
+        client.connect({
+            siteId,
+            branchId,
+            documentPath,
+            actorId,
+            actorType,
+            sessionId,
+        });
+        // Cleanup on unmount or when dependencies change
+        return () => {
+            connectedDocumentPathRef.current = null;
+            binding.destroy();
+            bindingRef.current = null;
+            client.disconnect();
+            clientRef.current = null;
+            setConnected(false);
+            setPresenceViaWebSocket(false);
+        };
+    }, [baseUrl, apiKey, siteId, branchId, documentPath, actorId, actorType, sessionId, enabled]);
+    // Apply local change function
+    const applyLocalChange = useCallback((data, actionMeta) => {
+        if (bindingRef.current) {
+            // Set action metadata on the RealtimeClient before applying the change.
+            // The client's ydoc 'update' handler will send it after the CRDT update.
+            if (actionMeta && clientRef.current) {
+                clientRef.current.setActionMetadata(actionMeta);
+            }
+            bindingRef.current.applyLocalChange(data);
+        }
+    }, [connected]);
+    // Get current snapshot from Yjs document
+    const getSnapshot = useCallback(() => {
+        if (clientRef.current) {
+            const snapshot = clientRef.current.getSnapshot();
+            if (snapshot && (snapshot.content || snapshot.root)) {
+                return snapshot;
+            }
+        }
+        return null;
+    }, []);
+    // Send focus regions update to server
+    const sendFocusRegions = useCallback((regions) => {
+        if (clientRef.current) {
+            return clientRef.current.sendFocusRegions(regions);
+        }
+        return false;
+    }, []);
+    // Send presence heartbeat to server
+    const sendHeartbeat = useCallback((state) => {
+        if (clientRef.current) {
+            clientRef.current.sendHeartbeat(state);
+        }
+    }, []);
+    // Wait for delivery acknowledgment from server
+    const waitForDelivery = useCallback(() => {
+        if (clientRef.current) {
+            return clientRef.current.waitForDelivery();
+        }
+        return Promise.reject(new Error('Not connected'));
+    }, []);
+    // Request publish via WebSocket (DO handles flush + publish)
+    const requestPublish = useCallback(() => {
+        if (clientRef.current) {
+            return clientRef.current.requestPublish();
+        }
+        return Promise.reject(new Error('Not connected'));
+    }, []);
+    return {
+        connected,
+        applyLocalChange,
+        getSnapshot,
+        error,
+        sendFocusRegions,
+        sendHeartbeat,
+        presenceViaWebSocket,
+        connectedDocumentPath: connectedDocumentPathRef.current,
+        waitForDelivery,
+        requestPublish,
+    };
+}
+//# sourceMappingURL=useRealtime.js.map

package/dist/editor/useRealtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRealtime.js","sourceRoot":"","sources":["../../src/editor/useRealtime.ts"],"names":[],"mappings":"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"}

package/dist/editor/utils/buildThumbnailOverride.d.ts

@@ -0,0 +1,28 @@
+/**
+ * buildThumbnailOverride
+ *
+ * Builds a Puck `componentItem` override that shows a schematic SVG thumbnail
+ * alongside the component name and a drag-handle affordance.
+ *
+ * The caller provides a `thumbnailMap` — a plain record from component name to
+ * a zero-argument React function component that renders the SVG wireframe.
+ * Unknown names fall back to a generic line-stub placeholder so the drawer
+ * always looks consistent even if a thumbnail hasn't been designed yet.
+ *
+ * Layout: [thumbnail 48×32] [name — flex 1] [grip dots]
+ */
+import React from 'react';
+import type { PuckOverrides } from '../plugin/index.js';
+/** A zero-argument React component that renders a thumbnail SVG. */
+export type ThumbnailFC = React.FC;
+/** Map from Puck component name to its thumbnail component. */
+export type ThumbnailMap = Record<string, ThumbnailFC>;
+/**
+ * Returns a partial `PuckOverrides` object containing a `componentItem` override
+ * that renders a thumbnail, the component name, and a drag-handle affordance.
+ *
+ * Pass the result to `useP1Editor`'s `additionalOverrides` or merge it with
+ * your existing overrides.
+ */
+export declare function buildThumbnailOverride(thumbnailMap: ThumbnailMap): Partial<PuckOverrides>;
+//# sourceMappingURL=buildThumbnailOverride.d.ts.map

package/dist/editor/utils/buildThumbnailOverride.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildThumbnailOverride.d.ts","sourceRoot":"","sources":["../../../src/editor/utils/buildThumbnailOverride.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAIxD,oEAAoE;AACpE,MAAM,MAAM,WAAW,GAAG,KAAK,CAAC,EAAE,CAAC;AAEnC,+DAA+D;AAC/D,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AAkBvD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAiCzF"}

package/dist/editor/utils/buildThumbnailOverride.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { GenericThumbnailIcon } from '../icons/GenericThumbnailIcon.js';
+import { GripHandleIcon } from '../icons/GripHandleIcon.js';
+// ─── Thumbnail wrapper ─────────────────────────────────────────────────────────
+function Thumbnail({ name, thumbnailMap }) {
+    const ThumbnailFn = thumbnailMap[name] ?? GenericThumbnailIcon;
+    return (_jsx("div", { style: { width: 48, height: 32, flexShrink: 0, borderRadius: 3, overflow: 'hidden' }, "aria-label": `${name} layout preview`, children: _jsx(ThumbnailFn, {}) }));
+}
+// ─── Public builder ───────────────────────────────────────────────────────────
+/**
+ * Returns a partial `PuckOverrides` object containing a `componentItem` override
+ * that renders a thumbnail, the component name, and a drag-handle affordance.
+ *
+ * Pass the result to `useP1Editor`'s `additionalOverrides` or merge it with
+ * your existing overrides.
+ */
+export function buildThumbnailOverride(thumbnailMap) {
+    return {
+        drawerItem: ({ name }) => (_jsxs("div", { style: {
+                display: 'flex',
+                alignItems: 'center',
+                gap: 10,
+                width: '100%',
+                padding: '6px 8px',
+                borderRadius: 6,
+                cursor: 'grab',
+                boxSizing: 'border-box',
+            }, children: [_jsx(Thumbnail, { name: name, thumbnailMap: thumbnailMap }), _jsx("span", { style: {
+                        flex: 1,
+                        fontSize: 13,
+                        fontWeight: 500,
+                        color: 'inherit',
+                        overflow: 'hidden',
+                        textOverflow: 'ellipsis',
+                        whiteSpace: 'nowrap',
+                    }, children: name }), _jsx(GripHandleIcon, {})] })),
+    };
+}
+//# sourceMappingURL=buildThumbnailOverride.js.map

package/dist/editor/utils/buildThumbnailOverride.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildThumbnailOverride.js","sourceRoot":"","sources":["../../../src/editor/utils/buildThumbnailOverride.tsx"],"names":[],"mappings":";AAgBA,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAQ5D,kFAAkF;AAElF,SAAS,SAAS,CAAC,EAAE,IAAI,EAAE,YAAY,EAAgD;IACrF,MAAM,WAAW,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,oBAAoB,CAAC;IAC/D,OAAO,CACL,cACE,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,gBACxE,GAAG,IAAI,iBAAiB,YAEpC,KAAC,WAAW,KAAG,GACX,CACP,CAAC;AACJ,CAAC;AAED,iFAAiF;AAEjF;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,YAA0B;IAC/D,OAAO;QACL,UAAU,EAAE,CAAC,EAAE,IAAI,EAA+C,EAAE,EAAE,CAAC,CACrE,eACE,KAAK,EAAE;gBACL,OAAO,EAAE,MAAM;gBACf,UAAU,EAAE,QAAQ;gBACpB,GAAG,EAAE,EAAE;gBACP,KAAK,EAAE,MAAM;gBACb,OAAO,EAAE,SAAS;gBAClB,YAAY,EAAE,CAAC;gBACf,MAAM,EAAE,MAAM;gBACd,SAAS,EAAE,YAAY;aACxB,aAED,KAAC,SAAS,IAAC,IAAI,EAAE,IAAI,EAAE,YAAY,EAAE,YAAY,GAAI,EACrD,eACE,KAAK,EAAE;wBACL,IAAI,EAAE,CAAC;wBACP,QAAQ,EAAE,EAAE;wBACZ,UAAU,EAAE,GAAG;wBACf,KAAK,EAAE,SAAS;wBAChB,QAAQ,EAAE,QAAQ;wBAClB,YAAY,EAAE,UAAU;wBACxB,UAAU,EAAE,QAAQ;qBACrB,YAEA,IAAI,GACA,EACP,KAAC,cAAc,KAAG,IACd,CACP;KACF,CAAC;AACJ,CAAC"}