/**
 * useP1Plugin Hook
 *
 * Creates a referentially stable P1 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 { DocumentLiveState, DocumentVersion, ActorPresence, RegisteredAgent, UnpublishDocumentOptions } from '@pantheon-systems/css-client';
import type { SiteMenuItem, CurrentUser } from '../pds/components/P1EditorHeader.js';
import type { TemplateSummary } from '../features/content-type-templates/types.js';
import type { PageNotFoundCanvasState, PuckPlugin } from './plugin/P1Plugin.js';
import type { DocumentSyncStore } from './plugin/document-sync-plugin.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;
    /** @deprecated No longer used by the editor UI. Will be removed in a future release. */
    publishedStatus?: 'published' | 'unpublished-changes' | 'draft';
    /** Currently selected version ID */
    selectedVersionId?: string;
    /** Callback when a version is selected */
    onVersionSelect?: (version: DocumentVersion) => void;
    /** Callback when user reverts to a previous version. Called by the plugin panel's revert button. */
    onRestoreVersion?: (version: DocumentVersion) => Promise<void>;
    /** Whether the current user is allowed to revert versions. */
    canRevert?: boolean;
    /** 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, template?: TemplateSummary | null, title?: string, locale?: string) => Promise<void>;
    /** Hand a "Generate with AI" brief (+ the new page's path/title) to the chatbot. */
    onGenerateWithAI?: (brief: string, page: {
        path: string;
        title: string;
    }) => void;
    /** Show the header's Zappy AI Assistant toggle. Pass the same flag that gates the chat plugin. */
    showAIPanelToggle?: boolean;
    /** Set by `useP1Editor` when the open path has no page. Not a consumer option. */
    pageNotFound?: PageNotFoundCanvasState | null;
    /** 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[];
    /** Site ID for linking to the P1 dashboard */
    siteId?: string;
    /** Base URL for the P1 dashboard (defaults to https://content.pantheon.io) */
    dashboardUrl?: string;
    /** Custom logo image URL for the editor header */
    logoUrl?: string;
    /** Currently authenticated user */
    currentUser?: CurrentUser;
    /** Callback when user logs out */
    onLogout?: () => void | Promise<void>;
    /** Message shown in the header when a logout attempt failed. */
    logoutError?: string | null;
    /** True while a logout is in flight; disables the menu item. */
    isLoggingOut?: boolean;
    /** @deprecated No longer used by the editor UI. Will be removed in a future release. */
    onCompareWithLive?: () => void;
    /** Callback for the publish action. When omitted, context's publishDocument is used. */
    onPublish?: () => Promise<void> | void;
    /**
     * Unpublishes the open page from live, sending its visitors to `redirectTo` when given. Adds Unpublish to the Live publish menu.
     * `options` carries `redirectTo` too, so it can be passed to `documents.unpublish` as it is.
     */
    onUnpublish?: (redirectTo?: string, options?: UnpublishDocumentOptions) => Promise<void>;
    /** Whether the open page is live. Main branch only. */
    liveState?: DocumentLiveState;
    /** Where visitors to the open page are redirected while it is unpublished. */
    unpublishRedirectTo?: string;
    /** Callback for the Review & Publish action */
    onReviewAndPublish?: () => void;
    /** Live URL of the current page, used by the publish popover's link, copy button and "View site". */
    siteUrl?: string;
    /** Shows the demo go-live screens. Set by the editor from LaunchDarkly. */
    goLiveStub?: boolean;
    /** Adds a "Go live: this page only" menu item when on a workstream. */
    onGoLivePage?: () => void;
    /**
     * Replaces the publish menu's "Create a new workstream" action. When omitted,
     * that action opens the workstream switcher's create form, so both entry
     * points share `onCreateBranch`.
     */
    onCreateWorkstream?: () => void;
    /**
     * Called when the user creates a new workstream, receiving its name.
     * Supplying this overrides the built-in create-and-switch behavior and is
     * always used. When omitted, the built-in control is shown only if the
     * workstream selector is enabled and the viewer has permission to create.
     */
    onCreateBranch?: (name: string) => Promise<void>;
    /** Called after a go-live deployment completes (success or failure) and the user dismisses the result screen. */
    onGoLiveComplete?: () => void;
    /**
     * Document-sync store shared with the document-sync plugin, so context-based
     * sync can leave document switches to it.
     */
    documentSyncStore?: Pick<DocumentSyncStore, 'getAppliedKey'>;
}
/**
 * Creates a referentially stable P1 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;