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

package/dist/use-generated-query.js

@@ -0,0 +1,308 @@
+'use client';
+import { useEffect, useLayoutEffect, useMemo, useSyncExternalStore } from 'react';
+import { QueryExecutionError, StorystickError } from '@storystick/client';
+import { prepareContentValues, rawContentValues, bindClientSchemaToAuthority, clientMatchesPreviewAuthority, getExecutableQueryDescriptor, getInternalClientRuntime, getPreviewQueryReceiptId, } from '@storystick/client/internal';
+import { getPreviewAuthority, subscribePreviewAuthority, } from '@storystick/preview/runtime/authority';
+import { getQueryPreviewState, subscribeQueryPreview, loadQueryPreview } from './query-preview-loader.js';
+import { createRefCountedObserver, convergeQueryProjection, previewQueryHasConfirmedCoverage, previewQueryIsAwaitingTargetedProjection, queryCacheKey, registerPreviewQueryReceipt, subscribeRefCounted, } from './query-cache.js';
+import { currentQueryContextEpoch, previewGenerationFor, } from './preview-generation.js';
+const AUTHORITY_IDENTITIES = new WeakMap();
+let nextAuthorityIdentity = 1;
+function authorityIdentity(client) {
+    const existing = AUTHORITY_IDENTITIES.get(client);
+    if (existing !== undefined)
+        return existing;
+    const created = nextAuthorityIdentity++;
+    AUTHORITY_IDENTITIES.set(client, created);
+    return created;
+}
+const SERVER_PENDING = Object.freeze({
+    status: 'pending',
+    data: undefined,
+    pageInfo: undefined,
+    error: null,
+    isFetching: false,
+    refetch: async () => {
+        throw new Error('storystick/QUERY_DISABLED: Cannot refetch before the query is enabled.');
+    },
+});
+export function useQuery(executableQuery, options = {}) {
+    const enabled = options.enabled !== false;
+    const compiled = executableQuery.compile();
+    const descriptor = getExecutableQueryDescriptor(executableQuery);
+    const client = descriptor.host.client;
+    if (!client || typeof client.projectId !== 'string') {
+        throw new TypeError('storystick/QUERY_INVALID: The executable query is not owned by a Client.');
+    }
+    const previewState = useSyncExternalStore(subscribePreviewAuthority, getPreviewAuthority, getPreviewAuthority);
+    const previewModules = useSyncExternalStore(subscribeQueryPreview, getQueryPreviewState, getQueryPreviewState);
+    useEffect(() => {
+        if (enabled && previewState.sessionId)
+            void loadQueryPreview();
+    }, [enabled, previewState.sessionId]);
+    const previewAuthority = previewState.httpClient &&
+        previewAuthorityMatchesState(previewState.httpClient, client, previewState)
+        ? previewState.httpClient
+        : null;
+    const hasExecutionAuthority = previewState.sessionId === null || previewAuthority !== null;
+    const executionClient = useMemo(() => previewAuthority
+        ? bindClientSchemaToAuthority(previewAuthority, client.schema)
+        : client, [client, previewAuthority]);
+    const contextEpoch = previewAuthority
+        ? `${currentQueryContextEpoch(client)}:authority:${authorityIdentity(previewAuthority)}`
+        : getInternalClientRuntime(client).contextEpoch;
+    const key = queryCacheKey(executionClient, compiled.canonical, compiled.query.locale.code, compiled.query.page?.after ?? null, contextEpoch);
+    const keyIdentity = JSON.stringify(key);
+    const store = useMemo(() => {
+        if (typeof window === 'undefined' || !enabled || !hasExecutionAuthority || (previewAuthority && !previewModules.runtime))
+            return disabledStore();
+        return deferredStore(() => {
+            const observer = createRefCountedObserver(executionClient, {
+                queryKey: key,
+                queryFn: ({ signal }) => {
+                    if (!executionAuthorityIsCurrent(previewAuthority, client)) {
+                        throw new StorystickError('The query authority changed before execution.', {
+                            code: 'storystick/QUERY_ABORTED',
+                            category: 'cancel',
+                            retryable: false,
+                        });
+                    }
+                    return getInternalClientRuntime(executionClient).executionHost.executeCompiled(compiled.query, compiled.canonical, { signal });
+                },
+                enabled: true,
+                retry: false,
+                staleTime: Infinity,
+                gcTime: 5 * 60 * 1_000,
+                refetchOnMount: false,
+                refetchOnWindowFocus: false,
+                refetchOnReconnect: false,
+            });
+            let previousCore = null;
+            let previousGenerationVersion = -1;
+            let previousTargetingState = '';
+            let previousSnapshot = null;
+            let previousLiveProjection = null;
+            let liveOverlayHandle = null;
+            let liveOverlayRetainCount = 0;
+            let paintProjection = null;
+            const generation = previewGenerationFor(client);
+            const currentQueryResult = () => observer.getCurrentResult().data;
+            const registerCommittedReceipt = () => {
+                if (executionClient === client)
+                    return;
+                registerPreviewQueryReceipt(client, executionClient, key, currentQueryResult());
+            };
+            const syncLiveQueryReceipt = () => {
+                liveOverlayHandle?.updateReceipt(getPreviewQueryReceiptId(currentQueryResult()));
+            };
+            const converge = () => {
+                const signal = generation.getSnapshot().signal;
+                if (signal?.status === 'ready' &&
+                    signal.projectionHash !== undefined &&
+                    !previewQueryHasConfirmedCoverage(executionClient, currentQueryResult())) {
+                    convergeQueryProjection(executionClient, key, signal.projectionHash);
+                }
+            };
+            const snapshot = () => {
+                const current = observer.getCurrentResult();
+                const generationSnapshot = generation.getSnapshot();
+                const hasConfirmedTargetingCoverage = previewQueryHasConfirmedCoverage(executionClient, current.data);
+                const isAwaitingTargetedProjection = previewQueryIsAwaitingTargetedProjection(executionClient, current.data);
+                const targetingState = [
+                    hasConfirmedTargetingCoverage,
+                    isAwaitingTargetedProjection,
+                ].join(':');
+                const liveProjection = liveOverlayHandle?.getSnapshot() ?? null;
+                if (current === previousCore &&
+                    generationSnapshot.version === previousGenerationVersion &&
+                    targetingState === previousTargetingState &&
+                    liveProjection === previousLiveProjection &&
+                    previousSnapshot)
+                    return previousSnapshot;
+                previousCore = current;
+                previousGenerationVersion = generationSnapshot.version;
+                previousTargetingState = targetingState;
+                previousLiveProjection = liveProjection;
+                const rawRead = rawContentValues(current.data);
+                const projectedRead = current.error === null && generationSnapshot.error === null
+                    ? (previewModules.runtime?.applyPreviewLiveQueryProjection(rawRead, liveProjection) ?? rawRead)
+                    : rawRead;
+                const visibleQueryResult = projectedRead === rawRead ? current.data : prepareContentValues(projectedRead, false, previewAuthority !== null);
+                paintProjection =
+                    visibleQueryResult !== current.data ? liveProjection : null;
+                previousSnapshot = toPublicSnapshot(current, observer, generationSnapshot.error, visibleQueryResult);
+                return previousSnapshot;
+            };
+            return {
+                subscribe: (listener) => {
+                    const onUpdate = () => {
+                        registerCommittedReceipt();
+                        syncLiveQueryReceipt();
+                        converge();
+                        listener();
+                    };
+                    // `useSyncExternalStore.getSnapshot` must stay pure. Register the
+                    // transport receipt only once React commits this subscription, then
+                    // keep it aligned with committed observer notifications.
+                    registerCommittedReceipt();
+                    if (executionClient !== client) {
+                        if (liveOverlayRetainCount === 0) {
+                            liveOverlayHandle = previewModules.runtime.previewLiveQueryOverlay.retain(keyIdentity);
+                        }
+                        liveOverlayRetainCount += 1;
+                        syncLiveQueryReceipt();
+                    }
+                    const stopLiveOverlay = liveOverlayHandle?.subscribe(onUpdate);
+                    const stopObserver = subscribeRefCounted(executionClient, observer, onUpdate, client);
+                    const stopGeneration = generation.subscribe(onUpdate);
+                    converge();
+                    return () => {
+                        stopLiveOverlay?.();
+                        if (liveOverlayRetainCount > 0) {
+                            liveOverlayRetainCount -= 1;
+                            if (liveOverlayRetainCount === 0) {
+                                liveOverlayHandle?.release();
+                                liveOverlayHandle = null;
+                                paintProjection = null;
+                            }
+                        }
+                        stopGeneration();
+                        stopObserver();
+                    };
+                },
+                snapshot,
+                paintProjection: () => paintProjection,
+            };
+        });
+        // The canonical identity deliberately replaces the ephemeral inline builder identity.
+    }, [client, enabled, executionClient, hasExecutionAuthority, keyIdentity, previewModules]);
+    const result = useSyncExternalStore(store.subscribe, store.snapshot, () => SERVER_PENDING);
+    const paintProjection = store.paintProjection?.() ?? null;
+    useLayoutEffect(() => {
+        if (paintProjection?.editorMutationAt === undefined ||
+            typeof window === 'undefined')
+            return;
+        const frame = window.requestAnimationFrame(() => {
+            const firstPaintOpportunity = window.performance.timeOrigin + window.performance.now();
+            previewModules.runtime?.recordPreviewPerfMetric(window, {
+                name: 'preview.liveQuery.firstPaintOpportunity',
+                durationMs: Math.max(0, firstPaintOpportunity - paintProjection.editorMutationAt),
+                detail: {
+                    queryInstanceId: paintProjection.queryInstanceId,
+                    sourceRevision: paintProjection.sourceRevision,
+                    payloadBytes: previewModules.runtime?.estimatePreviewPayloadBytes(window, paintProjection),
+                    projectionToPaintMs: paintProjection.projectedAt === undefined
+                        ? null
+                        : Math.max(0, firstPaintOpportunity - paintProjection.projectedAt),
+                },
+            });
+        });
+        return () => window.cancelAnimationFrame(frame);
+    }, [
+        paintProjection?.queryInstanceId,
+        paintProjection?.sourceEpoch,
+        paintProjection?.sourceRevision,
+    ]);
+    if (enabled && previewAuthority && previewModules.error) {
+        return { ...SERVER_PENDING, status: 'error', error: previewModules.error,
+            refetch: async () => {
+                await loadQueryPreview();
+                const failure = getQueryPreviewState().error;
+                if (failure)
+                    throw failure;
+                if (!executionAuthorityIsCurrent(previewAuthority, client)) {
+                    throw new StorystickError('The query authority changed before retry.', {
+                        code: 'storystick/QUERY_ABORTED', category: 'cancel', retryable: false,
+                    });
+                }
+                return getInternalClientRuntime(executionClient).executionHost.executeCompiled(compiled.query, compiled.canonical);
+            },
+        };
+    }
+    return result;
+}
+function previewAuthorityMatchesState(authority, owner, state) {
+    if (!state.sessionId || !state.previewToken)
+        return false;
+    return clientMatchesPreviewAuthority(authority, {
+        projectId: owner.projectId,
+        previewSessionId: state.sessionId,
+        previewObservationId: state.sessionId,
+        previewToken: state.previewToken,
+        readContext: state.readContext,
+        variantId: state.variantId,
+        releaseId: state.releaseId,
+    });
+}
+function executionAuthorityIsCurrent(previewAuthority, owner) {
+    const current = getPreviewAuthority();
+    if (current.sessionId === null)
+        return previewAuthority === null;
+    return previewAuthority !== null && previewAuthorityMatchesState(previewAuthority, owner, current);
+}
+function disabledStore() {
+    const snapshot = SERVER_PENDING;
+    return {
+        subscribe: () => () => { },
+        snapshot: () => snapshot,
+        paintProjection: () => null,
+    };
+}
+function toPublicSnapshot(current, observer, generationError, visibleQueryResult = current.data) {
+    const refetch = async () => {
+        const result = await observer.refetch();
+        if (result.error)
+            throw result.error;
+        if (!result.data)
+            throw new Error('storystick/QUERY_PROTOCOL: Refetch completed without a result.');
+        if (result.data.exactness !== 'exact')
+            throw new QueryExecutionError(result.data);
+        return result.data.data;
+    };
+    const visibleError = current.error ?? generationError;
+    if (visibleError) {
+        const last = visibleQueryResult?.exactness === 'exact' ? visibleQueryResult : undefined;
+        return {
+            status: 'error',
+            data: last?.data,
+            pageInfo: last?.pageInfo,
+            error: visibleError,
+            isFetching: current.isFetching,
+            refetch,
+        };
+    }
+    const result = visibleQueryResult;
+    if (!result) {
+        return {
+            status: 'pending', data: undefined, pageInfo: undefined,
+            error: null, isFetching: current.isFetching,
+            refetch,
+        };
+    }
+    if (result.exactness !== 'exact') {
+        return {
+            status: 'error', data: undefined, pageInfo: undefined,
+            error: new QueryExecutionError(result), isFetching: current.isFetching,
+            refetch,
+        };
+    }
+    return {
+        status: 'success', data: result.data, pageInfo: result.pageInfo,
+        error: null, isFetching: current.isFetching, refetch,
+    };
+}
+function deferredStore(create) {
+    let active = null;
+    let subscribers = 0;
+    return {
+        subscribe(listener) {
+            active ??= create();
+            subscribers++;
+            const stop = active.subscribe(listener);
+            return () => { stop(); if (--subscribers === 0)
+                active = null; };
+        },
+        snapshot: () => active?.snapshot() ?? SERVER_PENDING,
+        paintProjection: () => active?.paintProjection() ?? null,
+    };
+}

package/dist/use-momentary-preview-navigate-mode.d.ts

@@ -0,0 +1,11 @@
+import { type RefObject } from 'react';
+import { isMomentaryNavigateKeyDown } from '@storystick/preview/runtime/momentary-navigate';
+export { isMomentaryNavigateKeyDown };
+type InteractionMode = 'edit' | 'browse';
+interface UseMomentaryPreviewInteractionOverrideOptions {
+    enabled: boolean;
+    persistentMode: InteractionMode;
+    previewIframeRef?: RefObject<HTMLIFrameElement | null>;
+    isLocalPreviewEvent?: (event: Event) => boolean;
+}
+export declare function useMomentaryPreviewInteractionOverride({ enabled, persistentMode, previewIframeRef, isLocalPreviewEvent, }: UseMomentaryPreviewInteractionOverrideOptions): InteractionMode | null;

package/dist/use-momentary-preview-navigate-mode.js

@@ -0,0 +1,158 @@
+import { useEffect, useRef, useState } from 'react';
+import { isMomentaryNavigateKeyDown, isMomentaryNavigateKeySignal, } from '@storystick/preview/runtime/momentary-navigate';
+export { isMomentaryNavigateKeyDown };
+export function useMomentaryPreviewInteractionOverride({ enabled, persistentMode, previewIframeRef, isLocalPreviewEvent, }) {
+    const [shortcutActive, setShortcutActive] = useState(false);
+    const timerRef = useRef(null);
+    const lastPointerClientPositionRef = useRef(null);
+    const altDownRef = useRef(false);
+    const localEngaged = useRef(true);
+    useEffect(() => {
+        const cancelTimer = () => {
+            if (timerRef.current === null)
+                return;
+            clearTimeout(timerRef.current);
+            timerRef.current = null;
+        };
+        const schedule = (callback, delay) => {
+            cancelTimer();
+            timerRef.current = setTimeout(() => {
+                timerRef.current = null;
+                callback();
+            }, delay);
+        };
+        const clear = () => {
+            cancelTimer();
+            altDownRef.current = false;
+            setShortcutActive(false);
+        };
+        if (!enabled) {
+            clear();
+            return;
+        }
+        if (typeof window === 'undefined' || typeof document === 'undefined') {
+            clear();
+            return;
+        }
+        const getPreviewIframe = () => previewIframeRef?.current ?? null;
+        const isPointerInsidePreviewFrame = () => {
+            const iframe = getPreviewIframe();
+            const point = lastPointerClientPositionRef.current;
+            if (iframe === null || point === null)
+                return false;
+            const rect = iframe.getBoundingClientRect();
+            if (rect.width <= 0 || rect.height <= 0)
+                return false;
+            return (point.x >= rect.left &&
+                point.x <= rect.right &&
+                point.y >= rect.top &&
+                point.y <= rect.bottom);
+        };
+        const isPreviewFrameEngaged = () => {
+            const iframe = getPreviewIframe();
+            if (iframe === null)
+                return isLocalPreviewEvent ? localEngaged.current : false;
+            return isPointerInsidePreviewFrame() || document.activeElement === iframe;
+        };
+        const syncActiveFromScope = () => {
+            setShortcutActive(altDownRef.current && isPreviewFrameEngaged());
+        };
+        const onPointerMove = (event) => {
+            if (isLocalPreviewEvent)
+                localEngaged.current = isLocalPreviewEvent(event);
+            lastPointerClientPositionRef.current = {
+                x: event.clientX,
+                y: event.clientY,
+            };
+            syncActiveFromScope();
+        };
+        const onPointerOut = (event) => {
+            if (event.relatedTarget !== null)
+                return;
+            lastPointerClientPositionRef.current = null;
+            syncActiveFromScope();
+        };
+        const onKeyDown = (event) => {
+            if (!isMomentaryNavigateKeyDown(event))
+                return;
+            if (isLocalPreviewEvent && lastPointerClientPositionRef.current === null)
+                localEngaged.current = isLocalPreviewEvent(event);
+            altDownRef.current = true;
+            // Keyboard focus can remain in a Studio field while the pointer is
+            // over the iframe. The shortcut scope is the preview frame, not the
+            // currently focused parent-document input.
+            if (!isPreviewFrameEngaged())
+                return;
+            cancelTimer();
+            setShortcutActive(true);
+        };
+        const onKeyUp = (event) => {
+            if (event.key === 'Alt' || !event.altKey) {
+                altDownRef.current = false;
+                clear();
+            }
+        };
+        const onWindowBlur = () => {
+            schedule(() => {
+                const iframe = getPreviewIframe();
+                if (iframe !== null &&
+                    document.activeElement === iframe &&
+                    altDownRef.current) {
+                    setShortcutActive(true);
+                    iframe.blur();
+                    window.focus();
+                    return;
+                }
+                clear();
+            }, 0);
+        };
+        const onVisibilityChange = () => {
+            if (document.visibilityState !== 'visible')
+                clear();
+        };
+        const onMessage = (event) => {
+            if (!isMomentaryNavigateKeySignal(event.data))
+                return;
+            const iframe = getPreviewIframe();
+            if (iframe === null)
+                return;
+            const iframeWindow = iframe.contentWindow;
+            if (iframeWindow === null || event.source !== iframeWindow)
+                return;
+            if (event.data.active) {
+                altDownRef.current = true;
+                cancelTimer();
+                setShortcutActive(true);
+                return;
+            }
+            altDownRef.current = false;
+            clear();
+        };
+        document.addEventListener('pointermove', onPointerMove, true);
+        document.addEventListener('mousemove', onPointerMove, true);
+        document.addEventListener('pointerout', onPointerOut, true);
+        document.addEventListener('mouseout', onPointerOut, true);
+        document.addEventListener('keydown', onKeyDown, true);
+        document.addEventListener('keyup', onKeyUp, true);
+        window.addEventListener('blur', onWindowBlur);
+        window.addEventListener('message', onMessage);
+        document.addEventListener('visibilitychange', onVisibilityChange);
+        return () => {
+            cancelTimer();
+            altDownRef.current = false;
+            lastPointerClientPositionRef.current = null;
+            document.removeEventListener('pointermove', onPointerMove, true);
+            document.removeEventListener('mousemove', onPointerMove, true);
+            document.removeEventListener('pointerout', onPointerOut, true);
+            document.removeEventListener('mouseout', onPointerOut, true);
+            document.removeEventListener('keydown', onKeyDown, true);
+            document.removeEventListener('keyup', onKeyUp, true);
+            window.removeEventListener('blur', onWindowBlur);
+            window.removeEventListener('message', onMessage);
+            document.removeEventListener('visibilitychange', onVisibilityChange);
+        };
+    }, [enabled, previewIframeRef, isLocalPreviewEvent]);
+    if (!enabled || !shortcutActive)
+        return null;
+    return persistentMode === 'edit' ? 'browse' : 'edit';
+}

package/dist/use-preview-perspective-intent.d.ts

@@ -0,0 +1,53 @@
+import type { PreviewPerspectiveCommandResult } from '@storystick/preview';
+import type { PreviewPerspective, PreviewReadContext } from '@storystick/types/preview-query-targeting';
+import type { PreviewLifecyclePayload } from '@storystick/preview';
+import type { PreviewPerspectiveIntentObservation } from '@storystick/preview/runtime/preview-perspective-intent-state';
+type PreviewPerspectiveCommandStatus = PreviewPerspectiveCommandResult['status'];
+export type AcceptedPreviewPerspectiveIntentResult = {
+    readonly status: 'local-noop';
+    readonly context: PreviewReadContext;
+} | {
+    readonly status: Extract<PreviewPerspectiveCommandStatus, 'applied'>;
+    readonly commandId: string;
+    readonly context: PreviewReadContext;
+    readonly appliedRevision: number;
+};
+export type PreviewPerspectiveIntentResult = AcceptedPreviewPerspectiveIntentResult | {
+    readonly status: Extract<PreviewPerspectiveCommandStatus, 'conflict'>;
+    readonly commandId: string;
+    readonly context: PreviewReadContext;
+} | {
+    readonly status: 'unavailable' | 'superseded';
+    readonly commandId: string | null;
+};
+export declare function isAcceptedPreviewPerspectiveIntent(result: PreviewPerspectiveIntentResult): result is AcceptedPreviewPerspectiveIntentResult;
+interface PreviewPerspectiveIntentInputs<Command extends {
+    generation: number;
+}> {
+    readonly getSessionId: () => string | null;
+    readonly getReadContext: () => PreviewReadContext | null;
+    readonly beginTransition: (perspective: PreviewPerspective) => Command;
+    readonly dispatch: (perspective: PreviewPerspective) => Promise<{
+        commandId: string | null;
+    }>;
+    readonly registerCommand: (commandId: string, command: Command) => void;
+    readonly clearTransition: () => void;
+    readonly onTerminalFailure?: (status: 'conflict' | 'unavailable') => void;
+    /** Runs synchronously with acceptance, before React can reconcile effects. */
+    readonly onAccepted?: (context: PreviewReadContext) => void;
+    readonly onStateChange?: (observation: PreviewPerspectiveIntentObservation) => void;
+    readonly timeoutMs?: number;
+}
+export interface PreviewPerspectiveIntentLifecycle {
+    readonly cancelPending: () => void;
+    readonly changePerspective: (perspective: PreviewPerspective) => Promise<PreviewPerspectiveIntentResult>;
+    readonly observeLifecycle: (payload: PreviewLifecyclePayload) => boolean;
+}
+/**
+ * Event-owned lifecycle for an explicit perspective gesture. React effects
+ * may reconcile the accepted read context, but they never create this intent.
+ */
+export declare function usePreviewPerspectiveIntent<Command extends {
+    generation: number;
+}>(inputs: PreviewPerspectiveIntentInputs<Command>): PreviewPerspectiveIntentLifecycle;
+export {};