@pantheon-systems/puck-css 0.4.0

package/dist/editor/useP1Editor.js

@@ -0,0 +1,339 @@
+/**
+ * useP1Editor Hook
+ *
+ * All-in-one hook for setting up a P1-enabled Puck editor.
+ * Composes useP1Plugin and useP1Overrides internally, handles
+ * document loading, version management, historical version protection,
+ * and provides everything needed to render <Puck>.
+ */
+import { useState, useEffect, useRef, useMemo, useCallback } from 'react';
+import { useP1Puck } from '../core/P1PuckContext.js';
+import { useP1Plugin } from './useP1Plugin.js';
+import { useP1Overrides } from './useP1Overrides.js';
+import { useVersions } from '../versioning/useVersions.js';
+import { useComponentRegistry } from './useComponentRegistry.js';
+import { useP1Auth } from '../auth/index.js';
+import { buildThumbnailOverride } from './utils/buildThumbnailOverride.js';
+/**
+ * All-in-one hook for setting up a P1-enabled Puck editor.
+ *
+ * Handles document loading, version management, plugin/overrides creation,
+ * safe data, historical version protection, and plugin array assembly.
+ * Returns everything needed to render <Puck> with minimal boilerplate.
+ *
+ * Must be used inside a P1PuckProvider.
+ *
+ * @param options - Editor configuration
+ * @returns Loading state, puck props, and P1 context
+ *
+ * @example
+ * ```tsx
+ * function Editor() {
+ *   const { loading, error, puckProps } = useP1Editor({
+ *     documentPath: '/home',
+ *     puckConfig: config,
+ *   });
+ *
+ *   if (loading) return <Loading />;
+ *   if (error) return <Error error={error} />;
+ *
+ *   return <Puck {...puckProps} />;
+ * }
+ * ```
+ */
+export function useP1Editor(options) {
+    const { documentPath, puckConfig, additionalPlugins, additionalOverrides, thumbnails, overrideOptions, pluginOptions, onSelectionChange, onDocumentNotFound, } = options;
+    const css = useP1Puck();
+    const { user, logout } = useP1Auth();
+    // =========================================================================
+    // Document Loading
+    // =========================================================================
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const [needsRedirect, setNeedsRedirect] = useState(false);
+    const loadedPathRef = useRef(null);
+    // Reset loaded path when branch changes so document reloads on the new branch
+    const prevBranchRef = useRef(css.branchId);
+    if (prevBranchRef.current !== css.branchId) {
+        prevBranchRef.current = css.branchId;
+        loadedPathRef.current = null;
+    }
+    // Keep callback in a ref so the effect doesn't re-run when it changes
+    const onDocumentNotFoundRef = useRef(onDocumentNotFound);
+    onDocumentNotFoundRef.current = onDocumentNotFound;
+    useEffect(() => {
+        // Wait for branch resolution before loading documents
+        if (!css.branchId)
+            return;
+        // Skip if already loaded this path on this branch
+        if (loadedPathRef.current === documentPath)
+            return;
+        let cancelled = false;
+        setLoading(true);
+        setError(null);
+        css.loadDocument(documentPath)
+            .then(() => {
+            if (!cancelled) {
+                loadedPathRef.current = documentPath;
+                setNeedsRedirect(false);
+                setLoading(false);
+            }
+        })
+            .catch(async (err) => {
+            if (cancelled)
+                return;
+            const loadErr = err instanceof Error ? err : new Error(String(err));
+            // Give the consumer a chance to handle the error (e.g. auto-create)
+            if (onDocumentNotFoundRef.current) {
+                try {
+                    const shouldRetry = await onDocumentNotFoundRef.current(documentPath, loadErr);
+                    if (!cancelled && shouldRetry) {
+                        await css.loadDocument(documentPath);
+                        if (!cancelled) {
+                            loadedPathRef.current = documentPath;
+                            setNeedsRedirect(false);
+                            setLoading(false);
+                        }
+                        return;
+                    }
+                }
+                catch {
+                    // callback itself failed — fall through to unload
+                }
+            }
+            // Unload the editor; recovery effect will set an error if no docs exist
+            if (!cancelled) {
+                setNeedsRedirect(true);
+            }
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [documentPath, css.branchId, css.loadDocument]);
+    // Recovery: document not found on this branch — unload the editor and let
+    // the preview empty state guide the user to pick a page.
+    useEffect(() => {
+        if (!needsRedirect)
+            return;
+        if (css.documentsLoading)
+            return;
+        setNeedsRedirect(false);
+        if (css.documents.length === 0) {
+            setError(new Error('No documents found on this branch'));
+        }
+        setLoading(false);
+    }, [needsRedirect, css.documentsLoading, css.documents.length]);
+    // =========================================================================
+    // Version Management
+    // =========================================================================
+    const { versions, loading: versionsLoading, refresh: refreshVersions, } = useVersions({
+        client: css.client,
+        siteId: css.siteId,
+        branchId: css.branchId,
+        documentId: css.currentDocument?.id ?? null,
+    });
+    // Refresh versions when document changes
+    useEffect(() => {
+        if (css.currentDocument?.id)
+            void refreshVersions();
+    }, [css.currentDocument?.id, refreshVersions]);
+    // Select a version — latest returns to live editing, others load historical
+    const handleVersionSelect = useCallback((version) => {
+        const latestVersion = versions[0];
+        if (latestVersion && version.id === latestVersion.id) {
+            void css.returnToLatest();
+        }
+        else {
+            void css.loadVersion(version);
+        }
+    }, [versions, css.loadVersion, css.returnToLatest]);
+    // =========================================================================
+    // Published Status (derived from version data)
+    // =========================================================================
+    // The backend includes isPublished on each DocumentVersion via an EXISTS
+    // subquery against checkpoint_documents. No additional API calls needed.
+    const currentVersionId = css.viewingVersion?.id ?? versions[0]?.id;
+    const currentVersionIsPublished = versions.find(v => v.id === currentVersionId)?.isPublished ?? false;
+    const hasPublishedVersion = versions.some(v => v.isPublished);
+    // Look up the current document from the branch document list, which includes
+    // inherited and isPublished fields from the branch-level listing endpoint.
+    // css.currentDocument comes from the site-level getByPath endpoint and lacks these.
+    const branchDocument = css.documents.find(d => d.id === css.currentDocument?.id);
+    const inheritedAndPublished = branchDocument?.inherited && branchDocument?.isPublished;
+    const publishedStatus = versionsLoading
+        ? undefined
+        : inheritedAndPublished
+            ? 'published'
+            : currentVersionIsPublished
+                ? 'published'
+                : hasPublishedVersion
+                    ? 'unpublished-changes'
+                    : 'draft';
+    // =========================================================================
+    // Focus Region Reporting (outgoing — report local selection to server)
+    // =========================================================================
+    // Report selection changes to the presence system via WebSocket.
+    // Wraps the consumer's onSelectionChange so both reporting and
+    // the consumer callback are called.
+    const onSelectionChangeRef = useRef(onSelectionChange);
+    onSelectionChangeRef.current = onSelectionChange;
+    const handleSelectionChange = useCallback((path, itemId) => {
+        // Report to presence system via WebSocket (instant broadcast to other clients)
+        const regions = path ? [path] : [];
+        css.sendFocusRegions(regions);
+        // Forward to consumer callback
+        onSelectionChangeRef.current?.(path, itemId);
+    }, [css.sendFocusRegions]);
+    // =========================================================================
+    // Component Registry (runs at editor startup, writes descriptors to P1 backend)
+    // =========================================================================
+    useComponentRegistry({ puckConfig });
+    // =========================================================================
+    // Plugin & Overrides (composed hooks)
+    // =========================================================================
+    // Wrap publish to refresh version list and call consumer callback after success.
+    const consumerOnPublishSuccessRef = useRef(overrideOptions?.onPublishSuccess);
+    consumerOnPublishSuccessRef.current = overrideOptions?.onPublishSuccess;
+    const handlePublish = useCallback(async () => {
+        const checkpoint = await css.publishDocument();
+        void refreshVersions();
+        consumerOnPublishSuccessRef.current?.(checkpoint);
+    }, [css, refreshVersions]);
+    const p1Plugin = useP1Plugin({
+        onSelectionChange: handleSelectionChange,
+        currentUser: user ? { id: user.id, name: user.name, email: user.email, avatar: user.picture } : undefined,
+        onLogout: logout,
+        ...pluginOptions,
+        onPublish: handlePublish,
+        versions,
+        versionsLoading,
+        selectedVersionId: css.viewingVersion?.id ?? undefined,
+        onVersionSelect: handleVersionSelect,
+    });
+    const wrappedOnPublishSuccess = useCallback((checkpoint) => {
+        void refreshVersions();
+        consumerOnPublishSuccessRef.current?.(checkpoint);
+    }, [refreshVersions]);
+    const p1Overrides = useP1Overrides({
+        ...overrideOptions,
+        publishedStatus,
+        ...(overrideOptions?.onPublishSuccess ? { onPublishSuccess: wrappedOnPublishSuccess } : {}),
+    });
+    // =========================================================================
+    // Stable plugin array
+    // =========================================================================
+    const additionalPluginsRef = useRef(additionalPlugins);
+    additionalPluginsRef.current = additionalPlugins;
+    const pluginCount = additionalPlugins?.length ?? 0;
+    const plugins = useMemo(() => {
+        const result = [p1Plugin];
+        if (additionalPluginsRef.current) {
+            result.push(...additionalPluginsRef.current);
+        }
+        return result;
+    }, [p1Plugin, pluginCount]);
+    // =========================================================================
+    // Stable onChange (disabled for historical versions)
+    // =========================================================================
+    const isViewingHistoricalRef = useRef(css.isViewingHistoricalVersion);
+    isViewingHistoricalRef.current = css.isViewingHistoricalVersion;
+    const onChange = useCallback((data) => {
+        if (!isViewingHistoricalRef.current) {
+            css.saveData(data);
+        }
+    }, [css.saveData]);
+    // =========================================================================
+    // Permissions (read-only for historical versions)
+    // =========================================================================
+    const permissions = useMemo(() => {
+        if (css.isViewingHistoricalVersion) {
+            return { delete: false, drag: false, duplicate: false, edit: false, insert: false };
+        }
+        return undefined;
+    }, [css.isViewingHistoricalVersion]);
+    // =========================================================================
+    // Stable merged overrides
+    // =========================================================================
+    // Merge additional overrides (e.g. from media plugins) with P1 overrides.
+    // Uses ref pattern to keep the merge stable — only recomputes when
+    // p1Overrides changes, not when additionalOverrides reference changes
+    // (which would happen every render if the consumer doesn't memoize).
+    const additionalOverridesRef = useRef(additionalOverrides);
+    additionalOverridesRef.current = additionalOverrides;
+    // Thumbnail override — built from the thumbnails map and merged between
+    // p1Overrides and additionalOverrides so the site can still fully override
+    // componentItem if needed.
+    const thumbnailsRef = useRef(thumbnails);
+    thumbnailsRef.current = thumbnails;
+    const mergedOverrides = useMemo(() => {
+        // Layer order (last wins): p1Overrides → thumbnailOverride → additionalOverrides
+        const layers = [
+            p1Overrides,
+            thumbnailsRef.current ? buildThumbnailOverride(thumbnailsRef.current) : null,
+            additionalOverridesRef.current ?? null,
+        ];
+        const merged = {};
+        for (const layer of layers) {
+            if (!layer)
+                continue;
+            for (const [key, value] of Object.entries(layer)) {
+                const existing = merged[key];
+                if (existing && typeof existing === 'object' && !Array.isArray(existing) &&
+                    value && typeof value === 'object' && !Array.isArray(value)) {
+                    merged[key] = { ...existing, ...value };
+                }
+                else {
+                    merged[key] = value;
+                }
+            }
+        }
+        return merged;
+    }, [p1Overrides]);
+    // =========================================================================
+    // Assemble puckProps
+    // =========================================================================
+    // Key that forces Puck to remount on document switch, ensuring clean
+    // undo history, sidebar state, and no false onChange echo from setData.
+    const puckKey = `css-${css.currentDocument?.id ?? documentPath}`;
+    // Read persisted sidebar visibility from localStorage each time the Puck instance
+    // changes (puckKey changes on document/branch switch). The value is passed as the
+    // initial `ui` prop so Puck never initializes with wrong defaults.
+    const initialSidebarUi = useMemo(() => {
+        try {
+            const stored = localStorage.getItem(`p1-sidebar-${css.siteId}`);
+            if (!stored)
+                return {};
+            const parsed = JSON.parse(stored);
+            const ui = {};
+            if (parsed.left !== undefined)
+                ui.leftSideBarVisible = parsed.left;
+            if (parsed.right !== undefined)
+                ui.rightSideBarVisible = parsed.right;
+            return ui;
+        }
+        catch {
+            return {};
+        }
+    }, [puckKey, css.siteId]);
+    // Focus highlighting is handled via direct DOM manipulation in
+    // PresenceFocusBridge (P1App.tsx) — no config wrapping needed.
+    const puckProps = useMemo(() => ({
+        config: puckConfig,
+        data: css.safeData,
+        onChange,
+        plugins,
+        overrides: mergedOverrides,
+        ...(Object.keys(initialSidebarUi).length > 0 ? { ui: initialSidebarUi } : {}),
+        ...(permissions ? { permissions } : {}),
+    }), [puckConfig, css.safeData, onChange, plugins, mergedOverrides, initialSidebarUi, permissions]);
+    return {
+        loading,
+        error,
+        puckKey,
+        puckProps,
+        css,
+        /** @deprecated No longer emitted — editor now shows an empty state when a document is not found on the current branch. */
+        redirectPath: null,
+    };
+}
+//# sourceMappingURL=useP1Editor.js.map

package/dist/editor/useP1Editor.js.map

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

package/dist/editor/useP1Overrides.d.ts

@@ -0,0 +1,52 @@
+/**
+ * useP1Overrides Hook
+ *
+ * Creates referentially stable Puck overrides for P1 integration.
+ * Internally reads getters and callbacks from P1PuckProvider context
+ * and wires them to createP1Overrides with correct options.
+ */
+import type { PuckOverrides } from './plugin/createP1Overrides.js';
+import type { Checkpoint, ActorPresence } from '@pantheon-systems/css-client';
+/**
+ * Options consumers can pass to customize override behavior.
+ */
+export interface UseP1OverridesOptions {
+    /** Whether to show the default Puck publish button */
+    showDefaultPublish?: boolean;
+    /** Callback when publish succeeds */
+    onPublishSuccess?: (checkpoint: Checkpoint) => void;
+    /** Callback when publish fails */
+    onPublishError?: (error: Error) => void;
+    /** Callback when stop agent button is clicked */
+    onStopAgent?: (agent: ActorPresence) => void;
+    /** Whether to show collaborator avatars in header */
+    showCollaboratorAvatars?: boolean;
+    /** Whether to show agent activity banner in header */
+    showAgentActivityBanner?: boolean;
+    /** Published status for the header badge */
+    publishedStatus?: 'published' | 'unpublished-changes' | 'draft';
+}
+/**
+ * Creates referentially stable Puck overrides for P1 integration.
+ *
+ * Reads stable getters and callbacks from P1PuckProvider context and
+ * wires them to createP1Overrides. Uses a Proxy pattern to keep the
+ * overrides object referentially stable across re-renders.
+ *
+ * Must be used inside a P1PuckProvider.
+ *
+ * @param options - Optional customization
+ * @returns Stable PuckOverrides instance
+ *
+ * @example
+ * ```tsx
+ * function Editor() {
+ *   const overrides = useP1Overrides({
+ *     onPublishSuccess: (cp) => console.log('Published:', cp.name),
+ *   });
+ *   return <Puck overrides={overrides} config={config} data={data} />;
+ * }
+ * ```
+ */
+export declare function useP1Overrides(options?: UseP1OverridesOptions): PuckOverrides;
+//# sourceMappingURL=useP1Overrides.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useP1Overrides.d.ts","sourceRoot":"","sources":["../../src/editor/useP1Overrides.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAsB,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACvF,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAE9E;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,sDAAsD;IACtD,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,qCAAqC;IACrC,gBAAgB,CAAC,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,IAAI,CAAC;IACpD,kCAAkC;IAClC,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACxC,iDAAiD;IACjD,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAC7C,qDAAqD;IACrD,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,sDAAsD;IACtD,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,4CAA4C;IAC5C,eAAe,CAAC,EAAE,WAAW,GAAG,qBAAqB,GAAG,OAAO,CAAC;CACjE;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,qBAA0B,GAAG,aAAa,CAkDjF"}

package/dist/editor/useP1Overrides.js

@@ -0,0 +1,74 @@
+/**
+ * useP1Overrides Hook
+ *
+ * Creates referentially stable Puck overrides for P1 integration.
+ * Internally reads getters and callbacks from P1PuckProvider context
+ * and wires them to createP1Overrides with correct options.
+ */
+import { useRef, useMemo } from 'react';
+import { useP1Puck } from '../core/P1PuckContext.js';
+import { createP1Overrides } from './plugin/createP1Overrides.js';
+/**
+ * Creates referentially stable Puck overrides for P1 integration.
+ *
+ * Reads stable getters and callbacks from P1PuckProvider context and
+ * wires them to createP1Overrides. Uses a Proxy pattern to keep the
+ * overrides object referentially stable across re-renders.
+ *
+ * Must be used inside a P1PuckProvider.
+ *
+ * @param options - Optional customization
+ * @returns Stable PuckOverrides instance
+ *
+ * @example
+ * ```tsx
+ * function Editor() {
+ *   const overrides = useP1Overrides({
+ *     onPublishSuccess: (cp) => console.log('Published:', cp.name),
+ *   });
+ *   return <Puck overrides={overrides} config={config} data={data} />;
+ * }
+ * ```
+ */
+export function useP1Overrides(options = {}) {
+    const css = useP1Puck();
+    // Build the full overrides options from context + consumer options
+    const fc = css.featureConfig;
+    const overridesOptions = {
+        // Use getter-based API for performance (avoids overrides recreation)
+        getSaveStatus: css.getSaveStatus,
+        getLastSaved: css.getLastSaved,
+        getSaveError: css.getSaveError,
+        onRetrySave: css.saveNow,
+        showDefaultPublish: options.showDefaultPublish,
+        showSaveIndicator: fc?.enableAutoSave ?? true,
+        isViewingHistoricalVersion: css.isViewingHistoricalVersion,
+        viewingVersion: css.viewingVersion,
+        onReturnToLatest: css.returnToLatest,
+        // Presence/Agent features — gated by featureConfig flags
+        showCollaboratorAvatars: options.showCollaboratorAvatars
+            ?? ((fc?.enableCollaboratorAvatars ?? true) && css.presence !== null),
+        presence: (fc?.enableCollaboratorAvatars ?? true) ? css.presence?.actors : undefined,
+        showAgentActivityBanner: options.showAgentActivityBanner
+            ?? ((fc?.enableAgentBanner ?? true) && css.hasActiveAgents),
+        activeAgents: (fc?.enableAgentBanner ?? true)
+            ? css.presence?.agents?.filter(a => a.state === 'editing')
+            : undefined,
+        isAgentEditing: (fc?.enableAgentBanner ?? true) && css.hasActiveAgents,
+        onStopAgent: options.onStopAgent ?? css.stopAgent,
+        publishedStatus: options.publishedStatus,
+    };
+    // Store options in a ref updated each render
+    const optionsRef = useRef(overridesOptions);
+    optionsRef.current = overridesOptions;
+    // Create a stable Proxy-backed options object
+    const stableOptions = useMemo(() => new Proxy({}, {
+        get(_target, prop) {
+            return optionsRef.current[prop];
+        },
+    }), []);
+    // Create overrides once with stable proxy options
+    const overrides = useMemo(() => createP1Overrides(stableOptions), [stableOptions]);
+    return overrides;
+}
+//# sourceMappingURL=useP1Overrides.js.map

package/dist/editor/useP1Overrides.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useP1Overrides.js","sourceRoot":"","sources":["../../src/editor/useP1Overrides.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAwBlE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,cAAc,CAAC,UAAiC,EAAE;IAChE,MAAM,GAAG,GAAG,SAAS,EAAE,CAAC;IAExB,mEAAmE;IACnE,MAAM,EAAE,GAAG,GAAG,CAAC,aAAa,CAAC;IAE7B,MAAM,gBAAgB,GAAuB;QAC3C,qEAAqE;QACrE,aAAa,EAAE,GAAG,CAAC,aAAa;QAChC,YAAY,EAAE,GAAG,CAAC,YAAY;QAC9B,YAAY,EAAE,GAAG,CAAC,YAAY;QAC9B,WAAW,EAAE,GAAG,CAAC,OAAO;QACxB,kBAAkB,EAAE,OAAO,CAAC,kBAAkB;QAC9C,iBAAiB,EAAE,EAAE,EAAE,cAAc,IAAI,IAAI;QAC7C,0BAA0B,EAAE,GAAG,CAAC,0BAA0B;QAC1D,cAAc,EAAE,GAAG,CAAC,cAAc;QAClC,gBAAgB,EAAE,GAAG,CAAC,cAAc;QACpC,yDAAyD;QACzD,uBAAuB,EAAE,OAAO,CAAC,uBAAuB;eACnD,CAAC,CAAC,EAAE,EAAE,yBAAyB,IAAI,IAAI,CAAC,IAAI,GAAG,CAAC,QAAQ,KAAK,IAAI,CAAC;QACvE,QAAQ,EAAE,CAAC,EAAE,EAAE,yBAAyB,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,SAAS;QACpF,uBAAuB,EAAE,OAAO,CAAC,uBAAuB;eACnD,CAAC,CAAC,EAAE,EAAE,iBAAiB,IAAI,IAAI,CAAC,IAAI,GAAG,CAAC,eAAe,CAAC;QAC7D,YAAY,EAAE,CAAC,EAAE,EAAE,iBAAiB,IAAI,IAAI,CAAC;YAC3C,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC;YAC1D,CAAC,CAAC,SAAS;QACb,cAAc,EAAE,CAAC,EAAE,EAAE,iBAAiB,IAAI,IAAI,CAAC,IAAI,GAAG,CAAC,eAAe;QACtE,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,GAAG,CAAC,SAAS;QACjD,eAAe,EAAE,OAAO,CAAC,eAAe;KACzC,CAAC;IAEF,6CAA6C;IAC7C,MAAM,UAAU,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC;IAC5C,UAAU,CAAC,OAAO,GAAG,gBAAgB,CAAC;IAEtC,8CAA8C;IAC9C,MAAM,aAAa,GAAG,OAAO,CAC3B,GAAG,EAAE,CACH,IAAI,KAAK,CAAC,EAAwB,EAAE;QAClC,GAAG,CAAC,OAAO,EAAE,IAAY;YACvB,OAAQ,UAAU,CAAC,OAA8C,CAAC,IAAI,CAAC,CAAC;QAC1E,CAAC;KACF,CAAC,EACJ,EAAE,CACH,CAAC;IAEF,kDAAkD;IAClD,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,iBAAiB,CAAC,aAAa,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC;IAEnF,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/editor/useP1Plugin.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 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 type { PuckPlugin } from './plugin/P1Plugin.js';
+import type { DocumentVersion, ActorPresence, RegisteredAgent } from '@pantheon-systems/css-client';
+import type { SiteMenuItem, CurrentUser } from '../pds/components/P1EditorHeader.js';
+/**
+ * Options that consumers can pass to customize the plugin behavior.
+ * Context-derived values (branches, documents, versions, etc.) are
+ * automatically wired from P1PuckProvider context.
+ */
+export interface UseP1PluginOptions {
+    /** Callback when user selection changes in the Puck editor */
+    onSelectionChange?: (path: string | null, itemId: string | null) => void;
+    /** Puck config for rendering merge previews. Enables the built-in merge review overlay. */
+    puckConfig?: unknown;
+    /** List of versions for the current document */
+    versions?: DocumentVersion[];
+    /** Whether versions are loading */
+    versionsLoading?: boolean;
+    /** Currently selected version ID */
+    selectedVersionId?: string;
+    /** Callback when a version is selected */
+    onVersionSelect?: (version: DocumentVersion) => void;
+    /** Override document select handler (e.g., for URL-based routing). Defaults to context loadDocument. */
+    onDocumentSelect?: (path: string) => void;
+    /** Override selected document path (e.g., from URL params). Defaults to context currentDocument path. */
+    selectedDocumentPath?: string | null;
+    /** Callback to create a new document */
+    onDocumentCreate?: (path: string) => Promise<void>;
+    /** Callback to delete a document */
+    onDocumentDelete?: (documentId: string, path: string) => Promise<void>;
+    /** Whether to show presence indicator */
+    showPresenceIndicator?: boolean;
+    /** Current presence list (overrides context-derived presence) */
+    presence?: ActorPresence[];
+    /** Whether to show agent activity section */
+    showAgentActivity?: boolean;
+    /** Currently active agents */
+    activeAgents?: ActorPresence[];
+    /** Whether to show agent action trigger */
+    showAgentActions?: boolean;
+    /** Available agents for actions */
+    availableAgents?: RegisteredAgent[];
+    /** Callback when agent action is triggered */
+    onAgentAction?: (agentId: string, intent: string, targetRegions?: string[]) => void;
+    /** Whether to show focus regions */
+    showFocusRegions?: boolean;
+    /** Regions being edited by agents */
+    agentEditingRegions?: string[];
+    /** Site name displayed in the editor header */
+    siteName?: string;
+    /** Menu items shown in the site dropdown */
+    siteMenuItems?: SiteMenuItem[];
+    /** Currently authenticated user */
+    currentUser?: CurrentUser;
+    /** Callback when user logs out */
+    onLogout?: () => void;
+    /** Callback for Compare with Live action */
+    onCompareWithLive?: () => void;
+    /** Callback for the publish action. When omitted, context's publishDocument is used. */
+    onPublish?: () => Promise<void> | void;
+    /** Callback for the Review & Publish action */
+    onReviewAndPublish?: () => void;
+    /** Callback for the Create Workstream action */
+    onCreateWorkstream?: () => void;
+    /** Called when the user creates a new workstream. Receives the branch name. */
+    onCreateBranch?: (name: string) => Promise<void>;
+}
+/**
+ * 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 declare function useP1Plugin(options?: UseP1PluginOptions): PuckPlugin;
+//# sourceMappingURL=useP1Plugin.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useP1Plugin.d.ts","sourceRoot":"","sources":["../../src/editor/useP1Plugin.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAmB,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACxE,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AACpG,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC;AAErF;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,8DAA8D;IAC9D,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IACzE,2FAA2F;IAC3F,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;IAC7B,mCAAmC;IACnC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,oCAAoC;IACpC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,0CAA0C;IAC1C,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,CAAC;IACrD,wGAAwG;IACxG,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,yGAAyG;IACzG,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,wCAAwC;IACxC,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,oCAAoC;IACpC,gBAAgB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,yCAAyC;IACzC,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,iEAAiE;IACjE,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;IAC3B,6CAA6C;IAC7C,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,8BAA8B;IAC9B,YAAY,CAAC,EAAE,aAAa,EAAE,CAAC;IAC/B,2CAA2C;IAC3C,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,mCAAmC;IACnC,eAAe,CAAC,EAAE,eAAe,EAAE,CAAC;IACpC,8CAA8C;IAC9C,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IACpF,oCAAoC;IACpC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,qCAAqC;IACrC,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE/B,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,aAAa,CAAC,EAAE,YAAY,EAAE,CAAC;IAC/B,mCAAmC;IACnC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,4CAA4C;IAC5C,iBAAiB,CAAC,EAAE,MAAM,IAAI,CAAC;IAC/B,wFAAwF;IACxF,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACvC,+CAA+C;IAC/C,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAC;IAChC,gDAAgD;IAChD,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAC;IAChC,+EAA+E;IAC/E,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAClD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,UAAU,CA0FxE"}