@storystick/react 0.0.0-stage → 0.2.0-rc.1

package/dist/preview-host/preview-standalone-controls.d.ts

@@ -0,0 +1,18 @@
+import { type PreviewOverlayClickTarget } from '@storystick/preview/provenance';
+import type { PreviewReadContext } from '@storystick/types/preview-query-targeting';
+import type { PreviewAuthoringTarget } from '@storystick/preview/authoring/runtime-contract';
+import { type ReactElement } from 'react';
+import type { PreviewRuntimeAdapterSnapshot } from '@storystick/preview/framework/runtime-adapter-store';
+export interface PreviewStandaloneControlsProps {
+    projectId: string | null;
+    state: PreviewRuntimeAdapterSnapshot;
+    basePath?: string;
+    pathname?: string | null;
+    recovery?: {
+        error: string | null;
+        retry: () => void;
+    };
+}
+/** Minimal host: one sleeping bubble, one compact menu and one shared editor. */
+export declare function PreviewStandaloneControls({ state, projectId, recovery, basePath, pathname, }: PreviewStandaloneControlsProps): ReactElement | null;
+export declare function targetForOverlay(target: PreviewOverlayClickTarget, perspective: PreviewReadContext['perspective'] | null, presentationLocale?: string): PreviewAuthoringTarget | null;

package/dist/preview-host/preview-standalone-controls.js

@@ -0,0 +1,528 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useMomentaryPreviewInteractionOverride } from '@storystick/react/internal/use-momentary-preview-navigate-mode';
+import { PreviewPanelAction, PreviewPanelState } from '@storystick/react/internal/preview-panel-state';
+import { AuthoringPanelSkeleton } from '@storystick/react/internal/authoring-skeleton';
+import { useStandalonePresentation } from './use-standalone-presentation.js';
+import { PreviewInteractionControl } from '@storystick/react/internal/preview-interaction-control';
+import { PreviewToolbarShell, PreviewEditIcon as EditIcon, PreviewAssistantIcon as ChatIcon, PreviewStudioIcon as StudioIcon, } from '@storystick/react/internal/preview-toolbar-shell';
+import { readStandaloneStudioUrl, readStandaloneInteractionMode, rememberStandaloneInteractionMode, } from '@storystick/preview/identity/browser-context';
+import { readStandaloneOverlaySnapshot, revealStandaloneSource, revealStandaloneSlice, setStandaloneOverlayMode, setStandaloneOverlaySuspended, subscribeStandaloneOverlayIntent, subscribeStandaloneOverlaySnapshot, } from '@storystick/preview/runtime/standalone-overlays';
+import { overlayEditorTarget, overlayEditorLocale, } from '@storystick/preview/provenance';
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore, } from 'react';
+import { clearPreviewEditorNavigation, readPreviewEditorNavigation, rememberPreviewEditorNavigation, } from './preview-editor-continuation.js';
+import { previewPerspectivesEqual } from '@storystick/preview/runtime/preview-perspective-alignment';
+import { emptyPrimaryPagesSnapshot, previewCurrentPrimaryPage, previewStudioDestination, readPrimaryPagesSnapshot, subscribePrimaryPages, } from './preview-studio-destination.js';
+import { previewRuntime } from '@storystick/preview/runtime/store';
+import { STORYSTICK_PREVIEW_AUTHORING_ROUTE_PATH, storystickRouteForBasePath, } from '@storystick/preview/routes';
+import { authoringRuntimeUrl, loadPreviewAuthoringRuntime, requestPreviewAuthoringAdmission, } from './preview-authoring-client.js';
+import { readPreviewAssistantNavigation, rememberPreviewAssistantNavigation } from './preview-assistant-continuation.js';
+const EMPTY_OVERLAYS = Object.freeze({
+    mode: 'browse',
+    available: false,
+    generation: null,
+    rejections: [],
+});
+/** Minimal host: one sleeping bubble, one compact menu and one shared editor. */
+export function PreviewStandaloneControls({ state, projectId, recovery, basePath = '', pathname, }) {
+    const presentation = useStandalonePresentation(basePath);
+    const host = useRef(null);
+    const editorContainer = useRef(null);
+    const [headerLeading, setHeaderLeading] = useState(null);
+    const [headerTitle, setHeaderTitle] = useState(null);
+    const [headerTrailing, setHeaderTrailing] = useState(null);
+    const [contextContainer, setContextContainer] = useState(null);
+    const [interactionMode, setInteractionMode] = useState(() => readStandaloneInteractionMode(projectId, state.sessionId));
+    useEffect(() => {
+        setInteractionMode(readStandaloneInteractionMode(projectId, state.sessionId));
+    }, [projectId, state.sessionId]);
+    const chooseInteractionMode = (mode) => {
+        setInteractionMode(mode);
+        if (projectId && state.sessionId) {
+            rememberStandaloneInteractionMode({ projectId, sessionId: state.sessionId }, mode);
+        }
+    };
+    const isLocalPreviewEvent = useCallback((event) => !event.composedPath().includes(host.current), []);
+    const momentaryMode = useMomentaryPreviewInteractionOverride({
+        enabled: state.state === 'authenticated',
+        persistentMode: interactionMode,
+        isLocalPreviewEvent,
+    });
+    const effectiveMode = momentaryMode ?? interactionMode;
+    useEffect(() => {
+        setStandaloneOverlayMode(effectiveMode);
+    }, [effectiveMode]);
+    const runtimeHandle = useRef(null);
+    const runtimeOwner = useRef(null);
+    const admission = useRef(null);
+    const targetRef = useRef(null);
+    const [continuation, setContinuation] = useState(() => readPreviewEditorNavigation(projectId, state.sessionId));
+    const navigationHandoff = useRef(continuation);
+    const mounted = useRef(true);
+    const [root, setRoot] = useState(null);
+    const [assistantNavigation] = useState(() => readPreviewAssistantNavigation(projectId, state.sessionId));
+    const assistantThreadId = useRef(assistantNavigation?.threadId ?? null);
+    const activeSurface = useRef(null);
+    const [surface, setSurface] = useState(continuation ? 'editor' : assistantNavigation?.open ? 'assistant' : null);
+    const [menuOpen, setMenuOpen] = useState(false);
+    activeSurface.current = surface;
+    const [committedTarget, setCommittedTarget] = useState(null);
+    const rememberAssistant = useCallback((open) => {
+        if (projectId && state.sessionId)
+            rememberPreviewAssistantNavigation({ projectId, sessionId: state.sessionId, threadId: assistantThreadId.current, open });
+    }, [projectId, state.sessionId]);
+    useEffect(() => {
+        runtimeHandle.current?.setSurface(surface === 'editor' || surface === 'assistant' ? surface : null);
+        rememberAssistant(surface === 'assistant');
+    }, [surface, rememberAssistant]);
+    const [editorStatus, setEditorStatus] = useState('idle');
+    const [targetRequest, setTargetRequest] = useState(null);
+    const target = targetRequest?.target ?? null;
+    const [connectAttempt, setConnectAttempt] = useState(0);
+    const [error, setError] = useState(null);
+    useEffect(() => {
+        const next = readPreviewEditorNavigation(projectId, state.sessionId);
+        if (!next || runtimeHandle.current)
+            return;
+        navigationHandoff.current = next;
+        setContinuation(next);
+        setSurface('editor');
+    }, [projectId, state.sessionId]);
+    const evidence = useSyncExternalStore(subscribePrimaryPages, readPrimaryPagesSnapshot, emptyPrimaryPagesSnapshot);
+    const overlays = useSyncExternalStore(subscribeStandaloneOverlaySnapshot, readStandaloneOverlaySnapshot, () => EMPTY_OVERLAYS);
+    const browserPathname = typeof window === 'undefined' ? (pathname ?? '/') : window.location.pathname;
+    const destination = previewStudioDestination({
+        studioUrl: state.standaloneStudioUrl ??
+            readStandaloneStudioUrl(projectId, state.sessionId),
+        projectId,
+        sessionId: state.sessionId,
+        context: state.readContext,
+        authenticated: state.state === 'authenticated' && state.readContextStatus === 'active',
+        browserPathname,
+        basePath,
+        evidence,
+    });
+    const page = state.readContext === null
+        ? null
+        : previewCurrentPrimaryPage(evidence, state.sessionId, state.readContext, browserPathname, basePath);
+    const currentPageTarget = useMemo(() => page && state.readContext
+        ? targetForPage(page, state.readContext.perspective)
+        : null, [page, state.readContext]);
+    const studioUrl = state.standaloneStudioUrl ?? readStandaloneStudioUrl(projectId, state.sessionId);
+    const runtimeSource = studioUrl
+        ? authoringRuntimeUrl(studioUrl)
+        : null;
+    const authoringUrl = storystickRouteForBasePath(basePath, STORYSTICK_PREVIEW_AUTHORING_ROUTE_PATH);
+    const perspective = state.readContext?.perspective;
+    const rendered = state.readContext !== null &&
+        state.renderedReadContext?.contextId === state.readContext.contextId &&
+        state.renderedReadContext?.revision === state.readContext.revision;
+    const connected = state.state === 'authenticated' && state.readContextStatus === 'active';
+    const connectionNotice = state.state === 'error' || recovery?.error
+        ? 'Preview unavailable'
+        : !connected
+            ? 'Connecting to Preview…'
+            : null;
+    const notice = state.readContextNotice === 'release-published'
+        ? 'This release was published. Preview now follows Main, including its drafts.'
+        : state.readContextNotice === 'release-archived'
+            ? 'This release was archived. Preview now follows Main, including its drafts.'
+            : null;
+    const interactionSuspended = !connected || !rendered || presentation.transition.kind !== 'idle';
+    // Render proof protects page overlays. An accepted editor gesture can load
+    // and edit its target while the site catches up, under the shared admission.
+    const acceptedEditorContext = state.readContext != null &&
+        presentation.acceptedContext?.contextId === state.readContext.contextId &&
+        presentation.acceptedContext?.revision === state.readContext.revision;
+    const editorSuspended = !connected || (!rendered && !acceptedEditorContext);
+    const interactionSuspendedRef = useRef(interactionSuspended);
+    interactionSuspendedRef.current = interactionSuspended;
+    useEffect(() => {
+        setStandaloneOverlaySuspended(interactionSuspended);
+    }, [interactionSuspended]);
+    const canEdit = !interactionSuspended &&
+        connected &&
+        rendered &&
+        runtimeSource !== null &&
+        (currentPageTarget !== null || overlays.available);
+    const overlayNotice = overlays.rejections.length > 0
+        ? overlays.rejections.some(rejection => rejection.reason === 'edit-locator-variant-mismatch')
+            ? 'Element selection is unavailable because some elements do not match their editing context.'
+            : 'Element selection is unavailable because this page has incomplete or conflicting editing information.'
+        : null;
+    const shouldPreloadRuntime = canEdit && (interactionMode === 'edit' || menuOpen);
+    useEffect(() => {
+        if (!shouldPreloadRuntime || !runtimeSource)
+            return;
+        // Warm the common runtime; panel dependencies follow a specific intent.
+        // Admission and mounting stay separate from this shared code preparation.
+        void loadPreviewAuthoringRuntime(runtimeSource).catch(() => undefined);
+    }, [shouldPreloadRuntime, runtimeSource]);
+    const preloadPanel = useCallback((surface) => {
+        if (runtimeSource)
+            void loadPreviewAuthoringRuntime(runtimeSource, surface).catch(() => undefined);
+    }, [runtimeSource]);
+    const currentPage = useRef(page);
+    currentPage.current = page;
+    const presentationRef = useRef(presentation);
+    presentationRef.current = presentation;
+    const contextRef = useRef(state.readContext);
+    contextRef.current = state.readContext;
+    const sessionRef = useRef(state.sessionId);
+    sessionRef.current = state.sessionId;
+    const contextListeners = useRef(new Set());
+    useEffect(() => {
+        // The authoring controls observe both context and presentation. A locale
+        // or native page navigation can change without revising the read context.
+        contextListeners.current.forEach(listener => listener());
+    }, [state.readContext, page, presentation.acceptedContext, presentation.acceptedPresentation]);
+    const requestEditorTarget = useCallback((next) => {
+        setTargetRequest(next ? {
+            target: next,
+            context: contextRef.current,
+            sessionId: sessionRef.current,
+            location: window.location.href,
+        } : null);
+    }, []);
+    const observedPage = useRef(null);
+    const followedGeneration = useRef(0);
+    useEffect(() => {
+        if (presentation.transition.kind !== 'idle' || !navigationHandoff.current)
+            return;
+        // Only confirmed rendering consumes a successful hard-navigation hint.
+        // Acceptance alone is earlier than a potential document replacement.
+        if (presentation.completedGeneration > 0) {
+            clearPreviewEditorNavigation(navigationHandoff.current.id);
+            navigationHandoff.current = null;
+        }
+    }, [presentation.transition.kind, presentation.completedGeneration]);
+    useEffect(() => {
+        if (!page || !state.readContext || !rendered || presentation.isPending)
+            return;
+        const previous = observedPage.current;
+        observedPage.current = {
+            documentId: page.documentId,
+            locale: page.locale,
+            contextId: state.readContext.contextId,
+            revision: state.readContext.revision,
+        };
+        const ownTransition = followedGeneration.current !== presentation.completedGeneration;
+        followedGeneration.current = presentation.completedGeneration;
+        if (!previous ||
+            ownTransition ||
+            !runtimeHandle.current ||
+            !targetRef.current)
+            return;
+        const navigated = previous.documentId !== page.documentId || previous.locale !== page.locale;
+        const changedScope = previous.contextId !== state.readContext.contextId ||
+            previous.revision !== state.readContext.revision;
+        if (!navigated && !changedScope)
+            return;
+        const next = targetForPage(navigated ? page : { ...page,
+            documentId: targetRef.current.documentId,
+            locale: targetRef.current.locale,
+        }, state.readContext.perspective);
+        requestEditorTarget(next);
+    }, [
+        page,
+        state.readContext,
+        rendered,
+        presentation.isPending,
+        presentation.completedGeneration,
+        requestEditorTarget,
+    ]);
+    const closePanel = useCallback(() => {
+        if (navigationHandoff.current) {
+            clearPreviewEditorNavigation(navigationHandoff.current.id);
+            navigationHandoff.current = null;
+        }
+        setContinuation(null);
+        runtimeHandle.current?.setSurface(null);
+        setSurface(null);
+    }, []);
+    const openEditor = useCallback((next) => {
+        if (navigationHandoff.current) {
+            clearPreviewEditorNavigation(navigationHandoff.current.id);
+            navigationHandoff.current = null;
+        }
+        setContinuation(null);
+        setError(null);
+        setMenuOpen(false);
+        setSurface('editor');
+        runtimeHandle.current?.setSurface('editor');
+        requestEditorTarget(next);
+    }, [requestEditorTarget]);
+    useEffect(() => {
+        if (!continuation || !canEdit || !page || !perspective)
+            return;
+        if (page.documentId !== continuation.destination.documentId ||
+            page.locale !== continuation.destination.locale ||
+            !previewPerspectivesEqual(perspective, continuation.destination.perspective))
+            return;
+        // Restore only after the same render proof used by the live transition.
+        // The editor still obtains a fresh admission through its normal mount.
+        openEditor(continuation.target);
+    }, [continuation, canEdit, page, perspective, openEditor]);
+    useEffect(() => subscribeStandaloneOverlayIntent((intent) => {
+        if (interactionSuspendedRef.current)
+            return;
+        const next = targetForOverlay(intent, state.readContext?.perspective ?? null, page?.locale);
+        if (next)
+            openEditor(next);
+    }), [openEditor, state.readContext?.perspective, page?.locale]);
+    const wantsRuntime = surface !== null || menuOpen;
+    useEffect(() => {
+        if (!wantsRuntime ||
+            !connected ||
+            (surface === 'editor' && !targetRequest) ||
+            root === null ||
+            editorContainer.current === null ||
+            contextContainer === null || headerLeading === null || headerTitle === null || headerTrailing === null ||
+            runtimeSource === null ||
+            runtimeHandle.current !== null)
+            return;
+        let cancelled = false;
+        const container = editorContainer.current;
+        const requestedContext = contextRef.current;
+        const requestedSession = sessionRef.current;
+        const requestedLocation = window.location.href;
+        const connect = async () => {
+            setEditorStatus('connecting');
+            setError(null);
+            try {
+                const [runtime, initialAdmission] = await Promise.all([
+                    loadPreviewAuthoringRuntime(runtimeSource, surface),
+                    requestPreviewAuthoringAdmission({ url: authoringUrl }),
+                ]);
+                if (cancelled)
+                    return;
+                if ((surface === 'editor' && interactionSuspendedRef.current) ||
+                    requestedSession !== sessionRef.current ||
+                    requestedLocation !== window.location.href ||
+                    requestedContext?.contextId !== contextRef.current?.contextId ||
+                    requestedContext?.revision !== contextRef.current?.revision) {
+                    throw new Error('PREVIEW_PRESENTATION_SUPERSEDED');
+                }
+                admission.current = initialAdmission;
+                const owner = Symbol();
+                runtimeOwner.current = owner;
+                // This is the initial editor destination, before Convex authentication
+                // can report onTarget. Later requests only commit through onTarget.
+                targetRef.current = surface === 'editor' ? targetRequest.target : null;
+                const handle = runtime.mount({
+                    root,
+                    container,
+                    header: { leading: headerLeading, title: headerTitle, trailing: headerTrailing },
+                    target: targetRef.current ?? undefined,
+                    surface,
+                    assistantThreadId: assistantThreadId.current,
+                    onSurface: next => { if (runtimeOwner.current === owner) {
+                        setMenuOpen(false);
+                        setSurface(next);
+                    } },
+                    onAssistantThread: id => {
+                        if (runtimeOwner.current !== owner)
+                            return;
+                        assistantThreadId.current = id;
+                        rememberAssistant(activeSurface.current === 'assistant');
+                    },
+                    context: {
+                        container: contextContainer,
+                        getSnapshot: () => previewRuntime.getState().session?.readContext ?? null,
+                        subscribe: listener => {
+                            contextListeners.current.add(listener);
+                            return () => { contextListeners.current.delete(listener); };
+                        },
+                        change: next => presentationRef.current.changePerspective(next),
+                    },
+                    studioUrl: destination?.href,
+                    revealSource: revealStandaloneSource,
+                    revealSlice: revealStandaloneSlice,
+                    onTarget: (next) => {
+                        if (runtimeOwner.current !== owner)
+                            return;
+                        targetRef.current = next;
+                        setCommittedTarget(next);
+                    },
+                    getPresentation: () => {
+                        const hostPage = currentPage.current;
+                        const context = contextRef.current;
+                        const accepted = presentationRef.current;
+                        if (context && accepted.acceptedContext?.contextId === context.contextId &&
+                            accepted.acceptedContext.revision === context.revision &&
+                            accepted.acceptedPresentation)
+                            return accepted.acceptedPresentation;
+                        return hostPage && context
+                            ? {
+                                documentId: hostPage.documentId,
+                                locale: hostPage.locale,
+                                pathname: window.location.pathname.slice(basePath.length) || '/',
+                                perspective: context.perspective,
+                            }
+                            : null;
+                    },
+                    present: async (request, nextTarget) => {
+                        const handoff = projectId && state.sessionId && nextTarget
+                            ? rememberPreviewEditorNavigation(projectId, state.sessionId, basePath, request, nextTarget)
+                            : null;
+                        navigationHandoff.current = handoff;
+                        try {
+                            return await presentationRef.current.present(request);
+                        }
+                        catch (cause) {
+                            // A new browser document owns the handoff after pagehide.
+                            if (mounted.current && handoff) {
+                                clearPreviewEditorNavigation(handoff.id);
+                                if (navigationHandoff.current === handoff)
+                                    navigationHandoff.current = null;
+                            }
+                            throw cause;
+                        }
+                    },
+                    admission: initialAdmission,
+                    refreshAdmission: async () => {
+                        const next = await requestPreviewAuthoringAdmission({
+                            url: authoringUrl,
+                            previous: admission.current,
+                        });
+                        admission.current = next;
+                        return next;
+                    },
+                    closeAdmission: () => {
+                        admission.current = null;
+                    },
+                    onStatus: (status) => {
+                        if (runtimeOwner.current !== owner)
+                            return;
+                        if (status === 'disposed') {
+                            runtimeOwner.current = null;
+                            runtimeHandle.current = null;
+                            admission.current = null;
+                        }
+                        if (status === 'ready')
+                            setEditorStatus('ready');
+                        if (status === 'connecting')
+                            setEditorStatus('connecting');
+                        if (status === 'unauthorized') {
+                            setEditorStatus('error');
+                            setError('Editing access ended. Reopen Preview from Studio.');
+                        }
+                    },
+                });
+                if (cancelled) {
+                    if (runtimeOwner.current === owner)
+                        runtimeOwner.current = null;
+                    await handle.dispose();
+                    return;
+                }
+                runtimeHandle.current = handle;
+                handle.setSurface(surface === 'editor' || surface === 'assistant' ? surface : null);
+            }
+            catch (cause) {
+                if (!cancelled) {
+                    setEditorStatus('error');
+                    setError(authoringErrorMessage(cause));
+                }
+            }
+        };
+        void connect();
+        return () => {
+            cancelled = true;
+        };
+    }, [authoringUrl, connectAttempt, targetRequest, root, contextContainer, headerLeading, headerTitle, headerTrailing, runtimeSource, surface, wantsRuntime, connected]);
+    useEffect(() => {
+        if (!targetRequest || !runtimeHandle.current)
+            return;
+        const handle = runtimeHandle.current;
+        let current = true;
+        const isCurrent = () => current && runtimeHandle.current === handle &&
+            !interactionSuspendedRef.current &&
+            sessionRef.current === targetRequest.sessionId &&
+            targetRequest.context !== null &&
+            contextRef.current?.contextId === targetRequest.context.contextId &&
+            contextRef.current.revision === targetRequest.context.revision &&
+            window.location.href === targetRequest.location;
+        setEditorStatus('connecting');
+        void handle.open(targetRequest.target, isCurrent).then(() => {
+            // A cancelled opening leaves the retained editor usable. Its onTarget
+            // callback, not this transport status, owns the committed destination.
+            if (current)
+                setEditorStatus('ready');
+        }, (cause) => {
+            if (!isCurrent())
+                return;
+            setEditorStatus('error');
+            setError(authoringErrorMessage(cause));
+        });
+        return () => {
+            current = false;
+        };
+    }, [targetRequest]);
+    useEffect(() => {
+        mounted.current = true;
+        const dispose = () => {
+            mounted.current = false;
+            runtimeOwner.current = null;
+            void runtimeHandle.current?.dispose();
+            runtimeHandle.current = null;
+        };
+        window.addEventListener('pagehide', dispose);
+        return () => {
+            window.removeEventListener('pagehide', dispose);
+            dispose();
+        };
+    }, []);
+    return _jsx(PreviewToolbarShell, { hostRef: host, onRoot: setRoot, menuOpen: menuOpen, onMenuOpenChange: setMenuOpen, panelOpen: surface !== null, onPanelClose: closePanel, panelTitle: _jsx("span", { ref: setHeaderTitle, className: "panel-title", "data-placeholder": surface === "assistant" ? "Assistant" : "Edit content" }), panelLeading: _jsx("div", { ref: setHeaderLeading, "data-ss-surface": "" }), panelTrailing: _jsx("div", { ref: setHeaderTrailing, "data-ss-surface": "" }), panelLabel: surface === "assistant" ? "Assistant" : "Edit content", menu: _jsxs(_Fragment, { children: [_jsxs("div", { className: "menu-group", role: "group", "aria-label": "Site view", children: [_jsx("span", { className: "menu-group-label", children: "Site view" }), _jsxs("div", { className: "menu-group-content", children: [_jsx("div", { ref: setContextContainer, "data-ss-surface": "" }), editorStatus === 'connecting' ? _jsxs("div", { className: "menu-context-loading", role: "status", "aria-label": "Loading site view", children: [_jsx("span", {}), _jsx("span", {})] }) : null] })] }), _jsx("div", { className: "menu-separator", "aria-hidden": "true" }), _jsxs("div", { className: "menu-group", role: "group", "aria-label": "Interaction", children: [_jsx("span", { className: "menu-group-label", children: "Interaction" }), _jsx("div", { className: "menu-group-content", children: _jsx(PreviewInteractionControl, { interactionMode: effectiveMode, onChange: chooseInteractionMode }) })] }), _jsx("div", { className: "menu-separator", "aria-hidden": "true" }), _jsxs("button", { type: "button", className: "menu-action", disabled: !canEdit, onMouseEnter: () => { if (canEdit)
+                        preloadPanel('editor'); }, onFocus: () => { if (canEdit)
+                        preloadPanel('editor'); }, onClick: () => openEditor(currentPageTarget), children: [_jsx(EditIcon, {}), _jsx("span", { children: "Edit content" })] }), _jsxs("button", { type: "button", className: "menu-action", disabled: !connected || !runtimeSource, onMouseEnter: () => { if (connected)
+                        preloadPanel('assistant'); }, onFocus: () => { if (connected)
+                        preloadPanel('assistant'); }, onClick: () => { setError(null); setMenuOpen(false); setSurface('assistant'); }, children: [_jsx(ChatIcon, {}), _jsx("span", { children: "Assistant" })] }), destination && (_jsxs("a", { className: "menu-action", href: destination.href, children: [_jsx(StudioIcon, {}), _jsx("span", { children: "Open in Studio" })] })), (connectionNotice || notice ||
+                    overlayNotice ||
+                    (!rendered && connected) ||
+                    recovery?.error ||
+                    error) && (_jsxs("div", { className: "notices", children: [connectionNotice && _jsx("p", { role: "status", children: connectionNotice }), notice && _jsx("p", { children: notice }), overlayNotice && _jsx("p", { role: "status", children: overlayNotice }), connected && !rendered && (_jsxs("p", { children: ["This page has not confirmed its rendered perspective.", ' ', _jsx("button", { type: "button", onClick: () => window.location.reload(), children: "Reload" })] })), recovery?.error && (_jsxs("p", { role: "alert", children: [recovery.error, ' ', _jsx("button", { type: "button", onClick: recovery.retry, disabled: false, children: "Retry" })] })), error && _jsxs("p", { role: "alert", children: [error, ' ', editorStatus === 'error' && !runtimeHandle.current ? (_jsx("button", { type: "button", onClick: () => setConnectAttempt(value => value + 1), children: "Retry" })) : null] })] }))] }), panel: _jsxs(_Fragment, { children: [surface === 'editor' && target === null && committedTarget === null && !continuation && (_jsxs("div", { className: "editor-empty", children: [_jsx(EditIcon, {}), _jsx("strong", { children: "Select an element on the page" }), _jsx("p", { children: "The matching field will open here." })] })), (editorStatus === 'idle' || editorStatus === 'connecting') &&
+                    (surface === 'assistant' || target || continuation) && (_jsx("div", { className: "editor-loading", children: _jsx(AuthoringPanelSkeleton, { surface: surface === 'assistant' ? 'assistant' : 'editor' }) })), editorStatus === 'error' && error && (_jsx("div", { className: "panel-state-overlay", children: _jsx(PreviewPanelState, { title: surface === 'assistant' ? 'Assistant unavailable' : 'Editor unavailable', description: error, actions: _jsx(PreviewPanelAction, { onClick: () => {
+                                setError(null);
+                                if (runtimeHandle.current && (committedTarget ?? target))
+                                    requestEditorTarget({ ...(committedTarget ?? target) });
+                                else
+                                    setConnectAttempt((value) => value + 1);
+                            }, children: "Retry" }) }) })), surface === 'editor' && presentation.transition.kind === 'unconfirmed' && (_jsx("div", { className: "panel-state-overlay", children: _jsx(PreviewPanelState, { title: "Page not confirmed", description: "The site has not confirmed this page. Reload the preview if it does not catch up.", actions: _jsx(PreviewPanelAction, { onClick: () => window.location.reload(), children: "Reload preview" }) }) })), _jsx("div", { ref: editorContainer, className: "editor-mount", inert: (surface === 'editor' ? editorSuspended : !connected) || editorStatus !== 'ready', "aria-busy": (surface === 'editor' && editorSuspended) || editorStatus === 'connecting' })] }) });
+}
+function targetForPage(page, perspective) {
+    return {
+        documentId: page.documentId,
+        locale: page.locale,
+        ...(perspective.kind === 'published' ? { published: true } : perspective.kind === 'variant'
+            ? { variantId: perspective.variantId }
+            : perspective.kind === 'release'
+                ? { releaseId: perspective.releaseId }
+                : {}),
+    };
+}
+export function targetForOverlay(target, perspective, presentationLocale) {
+    const locale = overlayEditorLocale(target, presentationLocale);
+    if (!locale)
+        return null;
+    return {
+        documentId: target.documentId,
+        locale,
+        ...(perspective?.kind === 'published' ? { published: true } : perspective?.kind === 'variant'
+            ? { variantId: perspective.variantId }
+            : perspective?.kind === 'release'
+                ? { releaseId: perspective.releaseId }
+                : {}),
+        position: overlayEditorTarget(target),
+    };
+}
+function authoringErrorMessage(error) {
+    const code = error instanceof Error ? error.message : '';
+    console.warn('[storystick] Preview authoring connection failed:', /^[A-Z][A-Z0-9_]{0,80}$/.test(code) ? code : 'AUTHORING_RUNTIME_ERROR');
+    if (code.includes('AUTHORING_WRITE_FORBIDDEN')) {
+        return 'You do not have permission to edit this project.';
+    }
+    if (code.includes('CONTENT_SHAPE_RELOAD_REQUIRED')) {
+        return 'Reopen Preview from Studio after the site deployment changed.';
+    }
+    return 'Editing is unavailable. Reopen Preview from Studio and try again.';
+}

package/dist/preview-host/preview-studio-destination.d.ts

@@ -0,0 +1,20 @@
+import type { PreviewReadContext } from '@storystick/types/preview-query-targeting';
+import { type PreviewPrimaryPage } from '@storystick/preview/provenance';
+/** Render evidence is navigation metadata. Studio still authorizes every document. */
+export declare function previewStudioDestination(input: {
+    studioUrl: string | null;
+    projectId: string | null;
+    sessionId: string | null;
+    context: PreviewReadContext | null;
+    authenticated: boolean;
+    browserPathname: string;
+    basePath: string;
+    evidence: unknown;
+}): {
+    href: string;
+    kind: 'document' | 'project';
+} | null;
+export declare function previewCurrentPrimaryPage(evidence: unknown, sessionId: string | null, context: PreviewReadContext, browserPathname: string, basePath: string): PreviewPrimaryPage | null;
+export declare function readPrimaryPagesSnapshot(): unknown;
+export declare function subscribePrimaryPages(listener: () => void): () => void;
+export declare const emptyPrimaryPagesSnapshot: () => null;

package/dist/preview-host/preview-studio-destination.js

@@ -0,0 +1,55 @@
+import { isPreviewReadContext } from '@storystick/types/preview-query-targeting';
+import { selectPreviewPrimaryPage } from '@storystick/preview/provenance';
+/** Render evidence is navigation metadata. Studio still authorizes every document. */
+export function previewStudioDestination(input) {
+    if (!input.studioUrl || !input.projectId)
+        return null;
+    let url;
+    try {
+        url = new URL(input.studioUrl);
+    }
+    catch {
+        return null;
+    }
+    const [, prefix, project] = url.pathname.split('/');
+    if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password || prefix !== 'p' ||
+        !(project === input.projectId || project?.endsWith(`-${input.projectId}`)))
+        return null;
+    url.pathname = `/p/${project}`;
+    url.search = '';
+    url.hash = '';
+    const context = input.authenticated ? input.context : null;
+    if (context && input.sessionId)
+        url.searchParams.set('previewSource', input.sessionId);
+    if (context?.perspective.kind === 'published')
+        url.searchParams.set('perspective', 'published');
+    if (context?.perspective.kind === 'release')
+        url.searchParams.set('release', context.perspective.releaseId);
+    const page = context ? previewCurrentPrimaryPage(input.evidence, input.sessionId, context, input.browserPathname, input.basePath) : null;
+    if (page) {
+        url.pathname += `/d/${encodeURIComponent(page.documentId)}`;
+        url.searchParams.set('locale', page.locale);
+        url.searchParams.set('panel', 'preview');
+        if (context?.perspective.kind === 'variant')
+            url.searchParams.set('previewVariant', context.perspective.variantId);
+    }
+    return { href: url.href, kind: page ? 'document' : 'project' };
+}
+export function previewCurrentPrimaryPage(evidence, sessionId, context, browserPathname, basePath) {
+    if (!evidence || typeof evidence !== 'object')
+        return null;
+    const value = evidence;
+    if (!sessionId || value.sessionId !== sessionId || !isPreviewReadContext(value.readContext) ||
+        value.readContext.contextId !== context.contextId || value.readContext.revision !== context.revision ||
+        value.pathname !== browserPathname || !Array.isArray(value.pages))
+        return null;
+    return selectPreviewPrimaryPage(value.pages, browserPathname, basePath);
+}
+export function readPrimaryPagesSnapshot() {
+    return typeof window === 'undefined' ? null : window.__ssPreviewPrimaryPages ?? null;
+}
+export function subscribePrimaryPages(listener) {
+    window.addEventListener('storystick.preview.primary-pages', listener);
+    return () => window.removeEventListener('storystick.preview.primary-pages', listener);
+}
+export const emptyPrimaryPagesSnapshot = () => null;

package/dist/preview-host/use-standalone-presentation.d.ts

@@ -0,0 +1,15 @@
+import { type PreviewTransitionState } from '@storystick/preview/runtime/preview-transition-state';
+import type { PreviewAuthoringPresentation } from '@storystick/preview/authoring/runtime-contract';
+import type { PreviewPerspective, PreviewReadContext } from '@storystick/types/preview-query-targeting';
+/** Acceptance releases the editor; render proof releases the page overlays.
+ * No authoring credentials cross this port; the framework uses its Preview cookie. */
+export declare function useStandalonePresentation(basePath: string): {
+    present: (request: PreviewAuthoringPresentation) => Promise<PreviewReadContext>;
+    /** The project menu also exists on routes without an editable document. */
+    changePerspective(next: PreviewPerspective): Promise<PreviewReadContext>;
+    transition: PreviewTransitionState;
+    completedGeneration: number;
+    acceptedContext: PreviewReadContext | null;
+    acceptedPresentation: PreviewAuthoringPresentation | null;
+    isPending: boolean;
+};