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

package/dist/image-element.js

@@ -0,0 +1,68 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from 'react';
+/** Owns only the lifecycle required to remove a server-painted LQIP. */
+export function StorystickImageElement({ blurDataURL, ref, onLoad, onError, src, style, ...props }) {
+    const imageRef = React.useRef(null);
+    const mountedRef = React.useRef(false);
+    const srcKey = typeof src === 'string' ? src : '';
+    const currentSrcRef = React.useRef(srcKey);
+    currentSrcRef.current = srcKey;
+    const [settledSrc, setSettledSrc] = React.useState(null);
+    const showsPlaceholder = settledSrc !== srcKey;
+    const settle = React.useCallback(async (image) => {
+        const expectedSrc = srcKey;
+        if (typeof image.decode === 'function') {
+            try {
+                await image.decode();
+            }
+            catch {
+                // A failed decode must not leave the placeholder over native error UI.
+            }
+        }
+        if (!mountedRef.current || currentSrcRef.current !== expectedSrc)
+            return;
+        setSettledSrc(expectedSrc);
+    }, [srcKey]);
+    React.useEffect(() => {
+        mountedRef.current = true;
+        const image = imageRef.current;
+        if (image?.complete) {
+            void settle(image);
+        }
+        return () => {
+            mountedRef.current = false;
+        };
+    }, [settle]);
+    const setImageRef = React.useCallback((element) => {
+        imageRef.current = element;
+        const cleanup = typeof ref === 'function' ? ref(element) : undefined;
+        if (ref && typeof ref !== 'function')
+            ref.current = element;
+        return () => {
+            imageRef.current = null;
+            if (typeof cleanup === 'function')
+                cleanup();
+            else if (typeof ref === 'function')
+                ref(null);
+            else if (ref)
+                ref.current = null;
+        };
+    }, [ref]);
+    const placeholderStyle = showsPlaceholder
+        ? {
+            backgroundImage: `url(${JSON.stringify(blurDataURL)})`,
+            backgroundPosition: style?.objectPosition ?? 'center',
+            backgroundRepeat: 'no-repeat',
+            backgroundSize: 'cover',
+        }
+        : undefined;
+    return (_jsx("img", { ...props, ref: setImageRef, src: src, style: placeholderStyle ? { ...style, ...placeholderStyle } : style, onLoad: (event) => {
+            const image = event.currentTarget;
+            void settle(image);
+            onLoad?.(event);
+        }, onError: (event) => {
+            setSettledSrc(srcKey);
+            onError?.(event);
+        } }));
+}

package/dist/image.d.ts

@@ -0,0 +1,3 @@
+/** The media resolver owns both autonomous and explicitly sourced values. */
+export { resolveImage } from '@storystick/media';
+export { StorystickImage, type StorystickImageComponentProps, type StorystickImageFailure, type StorystickImageFallback, } from './image-component.js';

package/dist/image.js

@@ -0,0 +1,3 @@
+/** The media resolver owns both autonomous and explicitly sourced values. */
+export { resolveImage } from '@storystick/media';
+export { StorystickImage, } from './image-component.js';

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './rendering.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+// Rendering and typed client primitives. Reactive reads use @storystick/react/query.
+export * from './rendering.js';

package/dist/link-adapter.d.ts

@@ -0,0 +1,2 @@
+/** Framework adapter boundary. Application code should use StorystickLink. */
+export { StorystickLinkAdapter, type StorystickLinkAdapterProps, } from './link-component.js';

package/dist/link-adapter.js

@@ -0,0 +1,2 @@
+/** Framework adapter boundary. Application code should use StorystickLink. */
+export { StorystickLinkAdapter, } from './link-component.js';

package/dist/link-component.d.ts

@@ -0,0 +1,53 @@
+import { type LinkDocument as StorystickLinkDocument } from '@storystick/types';
+import * as React from 'react';
+import { type LinkOptions, type LinkValue } from '@storystick/types';
+export type StorystickLinkValue = LinkValue & {
+    readonly text?: React.ReactNode;
+    readonly title?: string | null;
+};
+type LinkSource = {
+    readonly link: StorystickLinkValue | null | undefined;
+    readonly document?: never;
+    readonly href?: never;
+};
+type DocumentSource = {
+    readonly link?: never;
+    readonly document: StorystickLinkDocument | null | undefined;
+    readonly href?: never;
+};
+export type { LinkDocument as StorystickLinkDocument } from '@storystick/types';
+type HrefSource = {
+    readonly link?: never;
+    readonly document?: never;
+    readonly href: string | null | undefined;
+};
+export type StorystickLinkOptions = LinkOptions & {
+    readonly fallbackLabel?: React.ReactNode;
+};
+type AnchorPassthroughProps = Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'children' | 'href' | 'rel' | 'target' | 'title' | 'suppressHydrationWarning'>;
+type RegularComposition = {
+    readonly asChild?: false;
+    readonly children?: React.ReactNode;
+};
+type ChildComposition = {
+    readonly asChild: true;
+    readonly children: React.ReactElement;
+};
+type StorystickLinkCommonProps = AnchorPassthroughProps & {
+    readonly options?: StorystickLinkOptions;
+    readonly title?: string | null;
+};
+export type StorystickLinkProps = StorystickLinkCommonProps & (LinkSource | DocumentSource | HrefSource) & (RegularComposition | ChildComposition);
+export type StorystickLinkAdapterProps = StorystickLinkProps & {
+    /** Router-aware component used only for resolved internal links. */
+    readonly internalComponent?: React.ElementType;
+    /** Adapter-owned props forwarded to the internal component. */
+    readonly internalComponentProps?: Readonly<Record<string, unknown>>;
+};
+/**
+ * Framework-neutral link renderer. Internal links use a native anchor unless
+ * a router adapter supplies `internalComponent`.
+ */
+export declare function StorystickLink(input: StorystickLinkProps): React.ReactElement;
+/** @internal Framework adapters may replace the renderer for internal links. */
+export declare function StorystickLinkAdapter(input: StorystickLinkAdapterProps): React.ReactElement;

package/dist/link-component.js

@@ -0,0 +1,97 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { resolveDocumentLink } from '@storystick/types';
+import { cleanPreviewAttributes } from '@storystick/types/internal/preview-provenance';
+import { stripPreviewProvenanceTextMarkers } from '@storystick/types/preview-provenance';
+import * as React from 'react';
+import { previewTextProps } from './preview-text-props.js';
+import { resolveLink, } from '@storystick/types';
+/**
+ * Framework-neutral link renderer. Internal links use a native anchor unless
+ * a router adapter supplies `internalComponent`.
+ */
+export function StorystickLink(input) {
+    return _jsx(StorystickLinkAdapter, { ...input });
+}
+/** @internal Framework adapters may replace the renderer for internal links. */
+export function StorystickLinkAdapter(input) {
+    const { asChild = false, children, options, title, internalComponent: InternalComponent = 'a', internalComponentProps, link: _link, document: _document, href: _href, ...anchorProps } = input;
+    const { fallbackLabel, ...linkOptions } = options ?? {};
+    const resolved = resolveInput(input, linkOptions);
+    const fieldLabel = 'link' in input ? input.link?.text : undefined;
+    const authoredTitle = 'link' in input ? input.link?.title : undefined;
+    const selectedTitle = Object.prototype.hasOwnProperty.call(input, 'title')
+        ? title
+        : authoredTitle;
+    const cleanTitle = cleanedTitle(selectedTitle);
+    const diagnosticStatus = linkDiagnosticStatus(resolved.status);
+    const { href: resolvedHref, ...resolvedAttrs } = resolved.props;
+    const commonProps = {
+        ...cleanPreviewAttributes(anchorProps),
+        ...resolvedAttrs,
+        'data-ss-e': resolved.props['data-ss-e'],
+        'data-ss-link-status': diagnosticStatus,
+        title: cleanTitle,
+        suppressHydrationWarning: true,
+    };
+    if (asChild) {
+        const child = React.Children.only(children);
+        const childProps = child.props;
+        const childLabel = childProps.children ?? fieldLabel ?? fallbackLabel;
+        const props = {
+            ...cleanPreviewAttributes({ ...childProps, ...anchorProps }),
+            ...resolvedAttrs,
+            href: resolvedHref,
+            'data-ss-e': resolved.props['data-ss-e'],
+            'data-ss-link-status': diagnosticStatus,
+            title: cleanTitle,
+            suppressHydrationWarning: true,
+        };
+        return React.cloneElement(child, { ...props, ...linkLabelProps(childLabel, props) });
+    }
+    const label = children ?? fieldLabel ?? fallbackLabel;
+    const labelProps = linkLabelProps(label, commonProps);
+    if (resolved.status === 'ok' || resolved.status === 'missing-anchor') {
+        return React.createElement(InternalComponent, {
+            ...internalComponentProps,
+            ...commonProps,
+            href: resolved.props.href,
+            ...labelProps,
+        });
+    }
+    if (resolved.status === 'external' || resolved.status === 'asset') {
+        return _jsx("a", { href: resolved.props.href, ...commonProps, ...labelProps });
+    }
+    return _jsx("a", { ...commonProps, ...labelProps });
+}
+function linkLabelProps(label, elementProps) {
+    if (typeof label !== 'string')
+        return { children: label };
+    const props = previewTextProps(label);
+    // The link/object field already owns this element when it has provenance.
+    // Cleaning its label must not add a competing text-field owner.
+    return elementProps['data-ss-e'] != null || elementProps['data-ss-p'] != null
+        ? { children: props.children }
+        : props;
+}
+function resolveInput(input, options) {
+    if ('link' in input)
+        return resolveLink(input.link, options);
+    if ('document' in input) {
+        if (!input.document)
+            return resolveLink(null, options);
+        return resolveDocumentLink(input.document, options);
+    }
+    return resolveLink(input.href === null || input.href === undefined
+        ? null
+        : { href: input.href }, options);
+}
+function cleanedTitle(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    return stripPreviewProvenanceTextMarkers(value) || undefined;
+}
+function linkDiagnosticStatus(status) {
+    return status === 'ok' || status === 'external' || status === 'asset'
+        ? undefined
+        : status;
+}

package/dist/link.d.ts

@@ -0,0 +1,3 @@
+/** One resolver for ordinary JS, React and framework adapters. */
+export { resolveLink } from '@storystick/types';
+export { StorystickLink, type StorystickLinkDocument, type StorystickLinkOptions, type StorystickLinkProps, type StorystickLinkValue, } from './link-component.js';

package/dist/link.js

@@ -0,0 +1,3 @@
+/** One resolver for ordinary JS, React and framework adapters. */
+export { resolveLink } from '@storystick/types';
+export { StorystickLink, } from './link-component.js';

package/dist/preview-generation.d.ts

@@ -0,0 +1,21 @@
+import type { Client, StorystickError as StorystickErrorType } from '@storystick/client';
+export interface ViewGenerationSignal {
+    readonly generation: number;
+    readonly status: 'ready' | 'stale' | 'rebuilding' | 'error';
+    readonly projectedThroughSeq?: number;
+    readonly projectionHash?: string;
+    readonly lensHash?: string;
+}
+interface PreviewGenerationSnapshot {
+    readonly version: number;
+    readonly epoch: string;
+    readonly signal: ViewGenerationSignal | null;
+    readonly error: StorystickErrorType | null;
+}
+interface PreviewCoordinator {
+    getSnapshot(): PreviewGenerationSnapshot;
+    subscribe(listener: () => void): () => void;
+}
+export declare function currentQueryContextEpoch(client: Client): string;
+export declare function previewGenerationFor(client: Client): PreviewCoordinator;
+export {};

package/dist/preview-generation.js

@@ -0,0 +1,134 @@
+import { getInternalClientRuntime } from '@storystick/client/internal';
+import { StorystickError } from '@storystick/client';
+import { getPreviewAuthority, subscribePreviewAuthority, } from '@storystick/preview/runtime/authority';
+const COORDINATORS = new WeakMap();
+export function currentQueryContextEpoch(client) {
+    const state = getPreviewAuthority();
+    if (!state.httpClient || !state.sessionId)
+        return getInternalClientRuntime(client).contextEpoch;
+    return previewEpoch(state.sessionId, state.variantId, state.releaseId) + `:${state.readContext?.contextId ?? ''}:${state.readContext?.revision ?? ''}`;
+}
+export function previewGenerationFor(client) {
+    const existing = COORDINATORS.get(client);
+    if (existing)
+        return existing;
+    let snapshot = Object.freeze({
+        version: 0,
+        epoch: currentQueryContextEpoch(client),
+        signal: null,
+        error: null,
+    });
+    const listeners = new Set();
+    let stopRuntime = null;
+    let stopWatch = null;
+    let watchIdentity = '';
+    const notify = (patch) => {
+        snapshot = Object.freeze({
+            version: snapshot.version + 1,
+            epoch: patch.epoch ?? snapshot.epoch,
+            signal: patch.signal,
+            error: patch.error,
+        });
+        for (const listener of listeners)
+            listener();
+    };
+    const stopCurrentWatch = () => {
+        if (stopWatch)
+            stopWatch();
+        stopWatch = null;
+        watchIdentity = '';
+    };
+    const syncRuntime = () => {
+        const state = getPreviewAuthority();
+        const nextEpoch = currentQueryContextEpoch(client);
+        if (nextEpoch !== snapshot.epoch) {
+            stopCurrentWatch();
+            notify({ epoch: nextEpoch, signal: null, error: null });
+        }
+        if (!state.client || !state.sessionId) {
+            stopCurrentWatch();
+            return;
+        }
+        const nextWatchIdentity = nextEpoch;
+        if (nextWatchIdentity === watchIdentity)
+            return;
+        stopCurrentWatch();
+        watchIdentity = nextWatchIdentity;
+        // ConvexReactClient exposes this imperative watcher underneath its React helpers.
+        const watch = state.client.watchQuery?.('sdkQueries:viewGeneration', { sessionId: state.sessionId });
+        if (!watch)
+            return;
+        const onUpdate = () => {
+            try {
+                const value = watch.localQueryResult();
+                if (value === null || value === undefined) {
+                    notify({ signal: null, error: null });
+                    return;
+                }
+                if (!isViewGenerationSignal(value)) {
+                    throw new Error('Invalid viewGeneration response.');
+                }
+                notify({
+                    signal: Object.freeze(value),
+                    error: value.status === 'error'
+                        ? new StorystickError('The preview projection is unavailable.', {
+                            code: 'storystick/DELIVERY_UNAVAILABLE',
+                            category: 'system',
+                            retryable: true,
+                        })
+                        : null,
+                });
+            }
+            catch (cause) {
+                notify({
+                    signal: snapshot.signal,
+                    error: new StorystickError('The preview projection signal failed.', {
+                        code: 'storystick/DELIVERY_UNAVAILABLE',
+                        category: 'system',
+                        retryable: true,
+                        payload: cause,
+                    }),
+                });
+            }
+        };
+        const cleanup = watch.onUpdate(onUpdate);
+        stopWatch = typeof cleanup === 'function' ? cleanup : null;
+        onUpdate();
+    };
+    const coordinator = {
+        getSnapshot: () => snapshot,
+        subscribe(listener) {
+            listeners.add(listener);
+            if (listeners.size === 1) {
+                stopRuntime = subscribePreviewAuthority(syncRuntime);
+                syncRuntime();
+            }
+            return () => {
+                listeners.delete(listener);
+                if (listeners.size === 0) {
+                    stopRuntime?.();
+                    stopRuntime = null;
+                    stopCurrentWatch();
+                }
+            };
+        },
+    };
+    COORDINATORS.set(client, coordinator);
+    return coordinator;
+}
+function previewEpoch(sessionId, variantId, releaseId) {
+    return `preview:${sessionId}:${variantId ?? ''}:${releaseId ?? ''}`;
+}
+function isViewGenerationSignal(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const input = value;
+    return Number.isSafeInteger(input.generation) &&
+        (input.status === 'ready' || input.status === 'stale' ||
+            input.status === 'rebuilding' || input.status === 'error') &&
+        (input.projectedThroughSeq === undefined ||
+            (Number.isSafeInteger(input.projectedThroughSeq) &&
+                input.projectedThroughSeq >= 0)) &&
+        (input.projectionHash === undefined || typeof input.projectionHash === 'string') &&
+        (input.lensHash === undefined || typeof input.lensHash === 'string');
+}

package/dist/preview-host/preview-assistant-continuation.d.ts

@@ -0,0 +1,9 @@
+export interface PreviewAssistantNavigation {
+    projectId: string;
+    sessionId: string;
+    threadId: string | null;
+    open: boolean;
+}
+export declare function readPreviewAssistantNavigation(projectId: string | null, sessionId: string | null): PreviewAssistantNavigation | null;
+export declare function rememberPreviewAssistantNavigation(value: PreviewAssistantNavigation): void;
+export declare function clearPreviewAssistantNavigation(): void;

package/dist/preview-host/preview-assistant-continuation.js

@@ -0,0 +1,39 @@
+/** Only navigation coordinates survive a reload, never a composer or attachment. */
+const KEY = '__storystick_assistant_navigation__';
+export function readPreviewAssistantNavigation(projectId, sessionId) {
+    if (!projectId || !sessionId || typeof window === 'undefined')
+        return null;
+    try {
+        const value = JSON.parse(window.sessionStorage.getItem(KEY) ?? 'null');
+        return value?.projectId === projectId &&
+            value.sessionId === sessionId &&
+            (value.threadId === null || typeof value.threadId === 'string') &&
+            typeof value.open === 'boolean'
+            ? { projectId, sessionId, threadId: value.threadId, open: value.open }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function rememberPreviewAssistantNavigation(value) {
+    try {
+        window.sessionStorage.setItem(KEY, JSON.stringify({
+            projectId: value.projectId,
+            sessionId: value.sessionId,
+            threadId: value.threadId,
+            open: value.open,
+        }));
+    }
+    catch {
+        /* Preview remains usable without storage. */
+    }
+}
+export function clearPreviewAssistantNavigation() {
+    try {
+        window.sessionStorage.removeItem(KEY);
+    }
+    catch {
+        /* No retained navigation. */
+    }
+}

package/dist/preview-host/preview-authoring-client.d.ts

@@ -0,0 +1,12 @@
+import { type PreviewAuthoringAdmission, type PreviewAuthoringRuntimeModule, type PreviewAuthoringSurface } from '@storystick/preview/authoring/runtime-contract';
+declare global {
+    interface Window {
+        StorystickAuthoringRuntime?: PreviewAuthoringRuntimeModule;
+    }
+}
+export declare function authoringRuntimeUrl(studioUrl: string): string | null;
+export declare function loadPreviewAuthoringRuntime(source: string, surface?: PreviewAuthoringSurface | null): Promise<PreviewAuthoringRuntimeModule>;
+export declare function requestPreviewAuthoringAdmission(args: {
+    url: string;
+    previous?: PreviewAuthoringAdmission | null;
+}): Promise<PreviewAuthoringAdmission>;

package/dist/preview-host/preview-authoring-client.js

@@ -0,0 +1,108 @@
+'use client';
+import { STORYSTICK_AUTHORING_RUNTIME_CONTRACT_VERSION, STORYSTICK_AUTHORING_RUNTIME_GLOBAL, STORYSTICK_AUTHORING_RUNTIME_PATH, isPreviewAuthoringAdmission, } from '@storystick/preview/authoring/runtime-contract';
+const loads = new Map();
+const attempts = new Map();
+export function authoringRuntimeUrl(studioUrl) {
+    try {
+        const studio = new URL(studioUrl);
+        if (!['http:', 'https:'].includes(studio.protocol))
+            return null;
+        return new URL(STORYSTICK_AUTHORING_RUNTIME_PATH, studio.origin).href;
+    }
+    catch {
+        return null;
+    }
+}
+export function loadPreviewAuthoringRuntime(source, surface) {
+    const pending = loadRuntimeModule(source);
+    // Code preparation never holds admission/authentication behind a panel's
+    // dependencies. Rendering uses the same imports and its own Suspense boundary.
+    if (surface)
+        void pending.then(runtime => runtime.preload(surface)).catch(() => undefined);
+    return pending;
+}
+function loadRuntimeModule(source) {
+    const installed = readRuntime();
+    if (installed)
+        return Promise.resolve(installed);
+    const existing = loads.get(source);
+    if (existing)
+        return existing;
+    const attempt = attempts.get(source) ?? 0;
+    attempts.set(source, attempt + 1);
+    const pending = new Promise((resolve, reject) => {
+        const script = document.createElement('script');
+        const url = new URL(source, document.baseURI);
+        url.searchParams.set('v', String(STORYSTICK_AUTHORING_RUNTIME_CONTRACT_VERSION));
+        // A failed or incompatible module is retained in the browser's module
+        // map. A deliberate retry needs a fresh entry URL to execute registration.
+        if (attempt > 0)
+            url.searchParams.set('retry', String(attempt));
+        script.src = url.href;
+        script.type = 'module';
+        script.crossOrigin = 'anonymous';
+        script.async = true;
+        script.dataset.storystickAuthoringRuntime = '';
+        script.onload = () => {
+            const runtime = readRuntime();
+            if (runtime)
+                resolve(runtime);
+            else {
+                script.remove();
+                reject(new Error('AUTHORING_RUNTIME_CONTRACT_MISMATCH'));
+            }
+        };
+        script.onerror = () => {
+            script.remove();
+            reject(new Error('AUTHORING_RUNTIME_UNAVAILABLE'));
+        };
+        document.head.append(script);
+    }).finally(() => {
+        if (!readRuntime())
+            loads.delete(source);
+    });
+    loads.set(source, pending);
+    return pending;
+}
+function readRuntime() {
+    const runtime = window[STORYSTICK_AUTHORING_RUNTIME_GLOBAL];
+    return runtime?.contractVersion ===
+        STORYSTICK_AUTHORING_RUNTIME_CONTRACT_VERSION
+        ? runtime
+        : null;
+}
+export async function requestPreviewAuthoringAdmission(args) {
+    const response = await fetch(args.url, {
+        method: 'POST',
+        credentials: 'same-origin',
+        cache: 'no-store',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(args.previous
+            ? {
+                admissionId: args.previous.connection.id,
+                fileDelegationId: args.previous.files.id,
+            }
+            : {}),
+    });
+    if (!response.ok)
+        throw await admissionError(response);
+    const admission = await response.json();
+    if (!isPreviewAuthoringAdmission(admission)) {
+        throw new Error('AUTHORING_ADMISSION_INVALID');
+    }
+    return admission;
+}
+async function admissionError(response) {
+    try {
+        const body = (await response.json());
+        const code = typeof body.error?.code === 'string'
+            ? body.error.code
+            : 'AUTHORING_ADMISSION_UNAVAILABLE';
+        const error = new Error(code);
+        error.name = code;
+        return error;
+    }
+    catch {
+        return new Error('AUTHORING_ADMISSION_UNAVAILABLE');
+    }
+}

package/dist/preview-host/preview-editor-continuation.d.ts

@@ -0,0 +1,13 @@
+import type { PreviewAuthoringPresentation, PreviewAuthoringTarget } from '@storystick/preview/authoring/runtime-contract';
+/** One navigation handoff, never a draft or an editing credential. */
+export interface PreviewEditorContinuation {
+    id: string;
+    projectId: string;
+    sessionId: string;
+    href: string;
+    destination: PreviewAuthoringPresentation;
+    target: PreviewAuthoringTarget;
+}
+export declare function rememberPreviewEditorNavigation(projectId: string, sessionId: string, basePath: string, destination: PreviewAuthoringPresentation, target: PreviewAuthoringTarget): PreviewEditorContinuation;
+export declare function readPreviewEditorNavigation(projectId: string | null, sessionId: string | null): PreviewEditorContinuation | null;
+export declare function clearPreviewEditorNavigation(id: string): void;

package/dist/preview-host/preview-editor-continuation.js

@@ -0,0 +1,68 @@
+import { previewDraftHref } from '@storystick/preview/identity';
+import { createPreviewRequestId } from '@storystick/preview/runtime/request-id';
+import { isPreviewPerspective } from '@storystick/types/preview-query-targeting';
+const STORAGE_KEY = '__storystick_editor_navigation__';
+let memory = null;
+export function rememberPreviewEditorNavigation(projectId, sessionId, basePath, destination, target) {
+    const entry = {
+        id: createPreviewRequestId(), projectId, sessionId,
+        href: basePath + previewDraftHref(destination.pathname, destination.draftDocumentId),
+        destination,
+        target: {
+            documentId: target.documentId, locale: target.locale,
+            ...(target.releaseId ? { releaseId: target.releaseId } : {}),
+            ...(target.variantId ? { variantId: target.variantId } : {}),
+        },
+    };
+    memory = entry;
+    try {
+        sessionStorage.setItem(STORAGE_KEY, JSON.stringify(entry));
+    }
+    catch { /* Storage may be unavailable. */ }
+    return entry;
+}
+export function readPreviewEditorNavigation(projectId, sessionId) {
+    if (!projectId || !sessionId || typeof window === 'undefined')
+        return null;
+    let entry = memory;
+    if (!entry) {
+        try {
+            const value = JSON.parse(sessionStorage.getItem(STORAGE_KEY) ?? 'null');
+            if (value && typeof value.id === 'string' && typeof value.href === 'string' &&
+                typeof value.destination?.documentId === 'string' &&
+                typeof value.destination?.locale === 'string' &&
+                isPreviewPerspective(value.destination?.perspective) &&
+                typeof value.target?.documentId === 'string' &&
+                typeof value.target?.locale === 'string' &&
+                (value.target.variantId === undefined || typeof value.target.variantId === 'string') &&
+                (value.target.releaseId === undefined || typeof value.target.releaseId === 'string'))
+                entry = value;
+        }
+        catch { /* Invalid or unavailable hints do not affect navigation. */ }
+    }
+    if (!entry || entry.projectId !== projectId || entry.sessionId !== sessionId)
+        return null;
+    // Only the destination of the editor gesture may resume its panel. Ignore
+    // session/refresh query parameters: they carry no document identity.
+    try {
+        const location = new URL(window.location.href);
+        const destination = new URL(entry.href, location.origin);
+        return destination.origin === location.origin &&
+            destination.pathname === location.pathname &&
+            destination.searchParams.get('_ss_draft') === location.searchParams.get('_ss_draft')
+            ? entry : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function clearPreviewEditorNavigation(id) {
+    if (memory?.id === id)
+        memory = null;
+    try {
+        if (JSON.parse(sessionStorage.getItem(STORAGE_KEY) ?? 'null')?.id === id) {
+            sessionStorage.removeItem(STORAGE_KEY);
+        }
+    }
+    catch { /* Nothing to clear when storage is unavailable. */ }
+}