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

package/dist/identity/preview-identity.js

@@ -0,0 +1,84 @@
+import { PREVIEW_SESSION_QUERY_PARAM, readPreviewSessionIdFromSearch, hasPreviewSessionParam } from './session-query.js';
+export { PREVIEW_SESSION_QUERY_PARAM, readPreviewSessionIdFromSearch, hasPreviewSessionParam } from './session-query.js';
+export const PREVIEW_VARIANT_QUERY_PARAM = '_ss_variant';
+export const PREVIEW_RELEASE_QUERY_PARAM = '_ss_release';
+export function isPreviewIdentity(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const identity = value;
+    return (typeof identity.sessionId === 'string' &&
+        identity.sessionId.length > 0 &&
+        typeof identity.projectId === 'string' &&
+        identity.projectId.length > 0 &&
+        (identity.parentOrigin === null ||
+            typeof identity.parentOrigin === 'string') &&
+        (identity.source === 'broadcast' ||
+            identity.source === 'request' ||
+            identity.source === 'storage' ||
+            identity.source === 'url') &&
+        typeof identity.epoch === 'number' &&
+        Number.isFinite(identity.epoch) &&
+        typeof identity.resolvedAt === 'number' &&
+        Number.isFinite(identity.resolvedAt));
+}
+export function readPreviewIdentitySessionId(identity) {
+    return isPreviewIdentity(identity) ? identity.sessionId : null;
+}
+export function readPreviewIdentity(source) {
+    if (source === null || source === undefined)
+        return null;
+    if (typeof source.getIdentity !== 'function')
+        return null;
+    try {
+        const identity = source.getIdentity();
+        return isPreviewIdentity(identity) ? identity : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function readPreviewIdentitySessionIdFromSource(source) {
+    return readPreviewIdentitySessionId(readPreviewIdentity(source));
+}
+export function readPreviewVariantIdFromSearch(search, paramName = PREVIEW_VARIANT_QUERY_PARAM) {
+    try {
+        const variantId = new URLSearchParams(search).get(paramName);
+        return normalizePreviewVariantId(variantId);
+    }
+    catch {
+        return null;
+    }
+}
+export function normalizePreviewVariantId(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+export function readPreviewReleaseIdFromSearch(search, paramName = PREVIEW_RELEASE_QUERY_PARAM) {
+    try {
+        const releaseId = new URLSearchParams(search).get(paramName);
+        return normalizePreviewReleaseId(releaseId);
+    }
+    catch {
+        return null;
+    }
+}
+export function normalizePreviewReleaseId(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+export function detectPreviewSessionFromWindow(win = typeof window === 'undefined' ? null : window, paramName = PREVIEW_SESSION_QUERY_PARAM) {
+    if (win === null || win === undefined) {
+        return { active: false, sessionId: null, variantId: null, releaseId: null };
+    }
+    const search = typeof win.location?.search === 'string' ? win.location.search : '';
+    return {
+        active: hasPreviewSessionParam(search, paramName),
+        sessionId: readPreviewSessionIdFromSearch(search, paramName),
+        variantId: readPreviewVariantIdFromSearch(search),
+        releaseId: readPreviewReleaseIdFromSearch(search),
+    };
+}

package/dist/identity/preview-scope.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The content perspective selected by one preview view.
+ *
+ * Authorization deliberately does not live here: a durable preview
+ * capability answers "may this browser read preview content?", while this
+ * value answers "which preview content should this tab render?".
+ */
+export type PreviewScope = {
+    kind: 'living';
+} | {
+    kind: 'published';
+} | {
+    kind: 'variant';
+    variantId: string;
+} | {
+    kind: 'release';
+    releaseId: string;
+};
+export declare class PreviewScopeConflictError extends Error {
+    constructor();
+}
+export declare function createPreviewScope(input: {
+    variantId?: string | null;
+    releaseId?: string | null;
+}): PreviewScope;
+export declare function readPreviewScopeFromSearch(search: string): PreviewScope;
+export declare function writePreviewScopeToSearchParams(params: URLSearchParams, scope: PreviewScope): void;
+export declare function previewScopeKey(scope: PreviewScope): string;

package/dist/identity/preview-scope.js

@@ -0,0 +1,47 @@
+import { PREVIEW_RELEASE_QUERY_PARAM, PREVIEW_VARIANT_QUERY_PARAM, normalizePreviewReleaseId, normalizePreviewVariantId, } from './preview-identity.js';
+export class PreviewScopeConflictError extends Error {
+    constructor() {
+        super('A preview view cannot select a variant and a release together.');
+        this.name = 'PreviewScopeConflictError';
+    }
+}
+export function createPreviewScope(input) {
+    const variantId = normalizePreviewVariantId(input.variantId);
+    const releaseId = normalizePreviewReleaseId(input.releaseId);
+    if (variantId && releaseId)
+        throw new PreviewScopeConflictError();
+    if (releaseId)
+        return { kind: 'release', releaseId };
+    if (variantId)
+        return { kind: 'variant', variantId };
+    return { kind: 'living' };
+}
+export function readPreviewScopeFromSearch(search) {
+    const params = new URLSearchParams(search);
+    return createPreviewScope({
+        variantId: params.get(PREVIEW_VARIANT_QUERY_PARAM),
+        releaseId: params.get(PREVIEW_RELEASE_QUERY_PARAM),
+    });
+}
+export function writePreviewScopeToSearchParams(params, scope) {
+    params.delete(PREVIEW_VARIANT_QUERY_PARAM);
+    params.delete(PREVIEW_RELEASE_QUERY_PARAM);
+    if (scope.kind === 'variant') {
+        params.set(PREVIEW_VARIANT_QUERY_PARAM, scope.variantId);
+    }
+    else if (scope.kind === 'release') {
+        params.set(PREVIEW_RELEASE_QUERY_PARAM, scope.releaseId);
+    }
+}
+export function previewScopeKey(scope) {
+    switch (scope.kind) {
+        case 'published':
+            return 'published';
+        case 'living':
+            return 'living';
+        case 'variant':
+            return `variant:${scope.variantId}`;
+        case 'release':
+            return `release:${scope.releaseId}`;
+    }
+}

package/dist/identity/resolver.d.ts

@@ -0,0 +1,110 @@
+/**
+ * ADR-116 D3 + D5 + D10 — preview identity resolver.
+ *
+ * Orchestrates the carrier chain (broadcast > storage > URL), the
+ * state machine (`identity-state-machine.ts`), and the side effects
+ * (storage writes on broadcast confirmation, postMessage listener
+ * attach/detach, carrier-miss timeout, recovery backoff).
+ *
+ * The resolver itself is framework-agnostic : it knows nothing about
+ * React, Next, Convex. The runtime store (PR4) is the framework-aware
+ * consumer that ties the resolver to the PreviewGrant + Convex client
+ * lifecycle.
+ *
+ * D5 invariants (codex R6) :
+ *  - `init()` is async + retriable, returns Promise<void>, never
+ *    rejects ; failure modes surface via `state === 'error'`.
+ *  - Compare-and-set on state transitions ; concurrent `start()` calls
+ *    resolve to "first wins, subsequent observe new state and bail".
+ *  - HMR-durability via the runtime cell (PR4 wires globalThis ; the
+ *    resolver itself is a single per-iframe instance owned by store.ts).
+ */
+import type { Carrier, IdentityListener, IdentitySnapshot, PreviewIdentity, ProvisionalIdentity } from './identity-types.js';
+import { STORAGE_KEY } from './carriers/storage.js';
+/** Default carrier-miss timeout (D5). 3 seconds matches the ADR. */
+export declare const DEFAULT_CARRIER_TIMEOUT_MS = 3000;
+/** Recovery backoff (ms) — exponential, capped. D4. */
+export declare const RECOVERY_BACKOFF_MS: readonly [200, 800, 2000];
+export interface CreateResolverOpts {
+    /** Authoritative projectId from the `<Storystick projectId>` prop. */
+    expectedProjectId: string;
+    /** Strict-precedence carriers. The broadcast carrier is reactive
+     *  (postMessage listener) and not part of the read-pass list. */
+    carriers: {
+        storage?: Carrier;
+        url?: Carrier;
+    };
+    /**
+     * Carrier-miss timeout (D5). When all carriers miss AND no broadcast
+     * arrives within this window, the resolver transitions to `error`.
+     * Test harnesses inject a small value (10ms) for deterministic
+     * timeout tests.
+     */
+    carrierTimeoutMs?: number;
+    /** Wall clock — injectable. */
+    now?: () => number;
+    /**
+     * Optional override for the `window` that receives broadcasts.
+     * Tests pass a jsdom stub. Production uses the global `window`.
+     */
+    win?: Window;
+    /**
+     * Optional override for `window.parent` that the resolver targets
+     * with session-request envelopes. Tests pass a stub.
+     */
+    parent?: Window;
+    /**
+     * Storage writer — fires on every confirmed broadcast (D7 A3 write
+     * timing). Defaults to the sessionStorage writer in `carriers/storage`.
+     * Test harnesses override with an in-memory spy.
+     */
+    storageWriter?: (identity: PreviewIdentity) => void;
+    /**
+     * Storage clearer — fires on identity invalidation (e.g. recovery
+     * exhausted, project mismatch). The default clears embedded storage and
+     * retains a standalone public hint for retry/exit, never an authority.
+     */
+    storageClearer?: () => void;
+}
+export interface IdentityResolver {
+    /**
+     * Begin carrier resolution. Idempotent — concurrent calls collapse
+     * to the in-flight promise. Returns `Promise<void>` that resolves
+     * once the state machine leaves `resolving-identity` (transition
+     * to `handshaking` or `error`). NEVER rejects ; failure surfaces
+     * via `state === 'error'`.
+     */
+    start(): Promise<void>;
+    /** Tear down listeners + clear pending timeouts. */
+    stop(): void;
+    /** Test-only reset to initial snapshot ; clears listeners. */
+    reset(): void;
+    getSnapshot(): IdentitySnapshot;
+    subscribe(listener: IdentityListener): () => void;
+    /**
+     * External notifications. The runtime store projects PreviewGrant and
+     * subscription readiness through the legacy identity state machine.
+     */
+    notifyAuthSucceeded(): void;
+    notifyAuthFailed(err: {
+        code: string;
+        message: string;
+    }): void;
+    /**
+     * Mark the channel as disconnected. The resolver attempts up to
+     * `MAX_RECOVERY_RETRIES` re-handshakes before transitioning to
+     * `error`.
+     */
+    notifyDisconnect(err?: {
+        code: string;
+        message: string;
+    }): void;
+    /**
+     * Inject a broadcast envelope (for test harnesses + direct unit
+     * tests). The resolver's attached `message` listener invokes this
+     * automatically on legitimate envelopes.
+     */
+    ingestBroadcast(identity: ProvisionalIdentity, eventOrigin: string): void;
+}
+export declare function createIdentityResolver(opts: CreateResolverOpts): IdentityResolver;
+export { STORAGE_KEY };

package/dist/identity/resolver.js

@@ -0,0 +1,334 @@
+/**
+ * ADR-116 D3 + D5 + D10 — preview identity resolver.
+ *
+ * Orchestrates the carrier chain (broadcast > storage > URL), the
+ * state machine (`identity-state-machine.ts`), and the side effects
+ * (storage writes on broadcast confirmation, postMessage listener
+ * attach/detach, carrier-miss timeout, recovery backoff).
+ *
+ * The resolver itself is framework-agnostic : it knows nothing about
+ * React, Next, Convex. The runtime store (PR4) is the framework-aware
+ * consumer that ties the resolver to the PreviewGrant + Convex client
+ * lifecycle.
+ *
+ * D5 invariants (codex R6) :
+ *  - `init()` is async + retriable, returns Promise<void>, never
+ *    rejects ; failure modes surface via `state === 'error'`.
+ *  - Compare-and-set on state transitions ; concurrent `start()` calls
+ *    resolve to "first wins, subsequent observe new state and bail".
+ *  - HMR-durability via the runtime cell (PR4 wires globalThis ; the
+ *    resolver itself is a single per-iframe instance owned by store.ts).
+ */
+import { INITIAL_SNAPSHOT, MAX_RECOVERY_RETRIES, transition, } from './identity-state-machine.js';
+import { attachBroadcastListener, postSessionRequest } from './carriers/postmessage.js';
+import { STORAGE_KEY, clearStoredAfterAuthFailure, writeStored, } from './carriers/storage.js';
+/** Default carrier-miss timeout (D5). 3 seconds matches the ADR. */
+export const DEFAULT_CARRIER_TIMEOUT_MS = 3_000;
+/** Recovery backoff (ms) — exponential, capped. D4. */
+export const RECOVERY_BACKOFF_MS = [200, 800, 2_000];
+export function createIdentityResolver(opts) {
+    const expectedProjectId = opts.expectedProjectId;
+    if (typeof expectedProjectId !== 'string' || expectedProjectId.length === 0) {
+        throw new Error('createIdentityResolver: expectedProjectId is required');
+    }
+    const now = opts.now ?? Date.now;
+    const carrierTimeoutMs = opts.carrierTimeoutMs ?? DEFAULT_CARRIER_TIMEOUT_MS;
+    const storageWriter = opts.storageWriter ?? ((id) => void writeStored(id, now));
+    const storageClearer = opts.storageClearer ?? clearStoredAfterAuthFailure;
+    // Resolver-local state cell. PR4's store.ts persists this on
+    // `globalThis` to survive HMR. For PR1 the resolver is a fresh per-
+    // creation instance ; tests that span HMR cycles construct a new
+    // resolver explicitly.
+    let snap = { ...INITIAL_SNAPSHOT };
+    let inFlightStartPromise = null;
+    let carrierTimeoutTimer = null;
+    let detachBroadcast = null;
+    let recoveryTimer = null;
+    // Locked parent origin after the first confirmed broadcast (D2).
+    let lockedParentOrigin = null;
+    // Listeners — Set so subscribe/unsubscribe is O(1).
+    const listeners = new Set();
+    function notify() {
+        const current = snap;
+        for (const listener of listeners) {
+            try {
+                listener(current);
+            }
+            catch {
+                // Defensive — a listener exception must not break the fan-out.
+            }
+        }
+    }
+    function dispatch(event) {
+        const prev = snap;
+        const next = transition(prev, event);
+        if (next === prev)
+            return;
+        snap = next;
+        notify();
+    }
+    function emitSessionRequest(reason) {
+        postSessionRequest({
+            projectId: expectedProjectId,
+            reason,
+            parent: opts.parent,
+            now,
+        });
+    }
+    function attachBroadcast() {
+        if (detachBroadcast !== null)
+            return;
+        detachBroadcast = attachBroadcastListener({
+            expectedProjectId,
+            win: opts.win,
+            onBroadcast: (identity, eventOrigin) => {
+                // Origin-lock — refuse subsequent broadcasts from any other
+                // origin (D2). The first confirmed broadcast wins.
+                if (lockedParentOrigin === null) {
+                    lockedParentOrigin = eventOrigin;
+                }
+                else if (lockedParentOrigin !== eventOrigin) {
+                    return;
+                }
+                ingestBroadcastInternal(identity);
+            },
+        });
+    }
+    function ingestBroadcastInternal(identity) {
+        // D10 reject path — projectId mismatch when an identity is already
+        // established. Bail BEFORE dispatching so the state machine never
+        // sees the rejected event AND the storage writer never fires.
+        if (snap.identity !== null &&
+            snap.identity.projectId !== identity.projectId) {
+            return;
+        }
+        // Dispatch and observe whether the state machine accepted the
+        // broadcast. Acceptance is detected by comparing post-dispatch
+        // identity tuple to the incoming one.
+        dispatch({ type: 'broadcast-received', identity, now: now() });
+        const after = snap;
+        const accepted = after.identity !== null &&
+            after.identity.sessionId === identity.sessionId &&
+            after.identity.projectId === identity.projectId;
+        if (accepted) {
+            // D7 A3 write timing — fires on every confirmed broadcast
+            // (Confirm / Promote / Replace AND idempotent no-ops so the TTL
+            // refreshes). Hardened mode storage exceptions are silent.
+            try {
+                storageWriter(after.identity);
+            }
+            catch {
+                /* hardened mode — silent */
+            }
+        }
+        // First broadcast = clear the carrier-miss timeout.
+        if (after.state !== 'resolving-identity' &&
+            carrierTimeoutTimer !== null) {
+            clearTimeout(carrierTimeoutTimer);
+            carrierTimeoutTimer = null;
+        }
+    }
+    function readCarrierChain() {
+        const ctx = { expectedProjectId, now };
+        // Storage first (tier-2), URL last (tier-3 bootstrap). Live
+        // broadcast (tier-1) is reactive ; it does not appear in this
+        // chain.
+        for (const carrierKey of ['storage', 'url']) {
+            const carrier = opts.carriers[carrierKey];
+            if (!carrier)
+                continue;
+            const result = carrier.read(ctx);
+            if (result.kind === 'hit') {
+                return { source: carrier.name, identity: result.identity };
+            }
+            // miss / error → continue to next carrier.
+        }
+        return null;
+    }
+    function start() {
+        // Compare-and-set : only the first caller transitions idle →
+        // resolving-identity. Concurrent callers (StrictMode double-mount,
+        // HMR re-mount) observe the in-flight promise and await it.
+        if (snap.state !== 'idle' && snap.state !== 'disconnected') {
+            return inFlightStartPromise ?? Promise.resolve();
+        }
+        // CRITICAL — set inFlightStartPromise BEFORE any notify() (codex
+        // R6 #2). A synchronous reentrancy via the listener fan-out must
+        // see the slot populated, not null.
+        const flight = new Promise((resolve) => {
+            const unsubscribe = subscribe((current) => {
+                if (current.state === 'handshaking' ||
+                    current.state === 'authenticated' ||
+                    current.state === 'error') {
+                    unsubscribe();
+                    inFlightStartPromise = null;
+                    resolve();
+                }
+            });
+        });
+        inFlightStartPromise = flight;
+        attachBroadcast();
+        dispatch({ type: 'start' });
+        // Carrier read-pass — synchronous.
+        const carrierHit = readCarrierChain();
+        if (carrierHit !== null) {
+            dispatch({
+                type: 'carrier-hit',
+                source: carrierHit.source,
+                identity: carrierHit.identity,
+                now: now(),
+            });
+            // ADR-131 C5 — URL / storage carriers do NOT carry parentOrigin
+            // (only the broadcast carrier does — `postmessage.ts` line 115).
+            // Without this emission the iframe's `identity.parentOrigin`
+            // stays `null` forever on the fast carrier-hit path, which
+            // breaks downstream preview message validators
+            // (validators reject unconditionally when
+            // parentOrigin === null). Emit a `session-request` so Studio
+            // sends back a broadcast that promotes identity with the locked
+            // parentOrigin (`identity-state-machine.ts:246` promotion
+            // branch). The Studio side already handles unsolicited drains
+            // via the queue+drain pattern in `use-preview-auth-bridge.ts` —
+            // the broadcast lands ~O(1ms) later, well before the first user
+            // edit triggers a build envelope.
+            emitSessionRequest('boot');
+        }
+        else {
+            // No carrier hit — arm the timeout AND post the session-request.
+            // Broadcast may still arrive within the window and resolve the
+            // identity ; if not, the timeout fires `error`.
+            emitSessionRequest('boot');
+            carrierTimeoutTimer = setTimeout(() => {
+                carrierTimeoutTimer = null;
+                dispatch({ type: 'carrier-timeout' });
+            }, carrierTimeoutMs);
+        }
+        return flight;
+    }
+    function stop() {
+        if (carrierTimeoutTimer !== null) {
+            clearTimeout(carrierTimeoutTimer);
+            carrierTimeoutTimer = null;
+        }
+        if (recoveryTimer !== null) {
+            clearTimeout(recoveryTimer);
+            recoveryTimer = null;
+        }
+        if (detachBroadcast !== null) {
+            detachBroadcast();
+            detachBroadcast = null;
+        }
+        inFlightStartPromise = null;
+    }
+    function reset() {
+        stop();
+        snap = { ...INITIAL_SNAPSHOT };
+        listeners.clear();
+        lockedParentOrigin = null;
+    }
+    function subscribe(listener) {
+        listeners.add(listener);
+        return () => {
+            listeners.delete(listener);
+        };
+    }
+    function notifyAuthSucceeded() {
+        dispatch({ type: 'auth-succeeded' });
+    }
+    function notifyAuthFailed(err) {
+        dispatch({ type: 'auth-failed', code: err.code, message: err.message });
+        if (snap.state === 'error') {
+            // Embedded failures invalidate the carrier. Autonomous views retain
+            // their public hint so a second reload can still offer Exit Preview.
+            try {
+                storageClearer();
+            }
+            catch {
+                /* hardened mode — silent */
+            }
+        }
+    }
+    function scheduleRecovery() {
+        if (recoveryTimer !== null)
+            return;
+        if (snap.retryCount >= MAX_RECOVERY_RETRIES) {
+            dispatch({
+                type: 'recovery-exhausted',
+                code: 'identity_recovery_exhausted',
+                message: 'Preview connection lost and recovery attempts exhausted. Reopen the document in Storystick Studio to retry.',
+            });
+            try {
+                storageClearer();
+            }
+            catch {
+                /* hardened mode — silent */
+            }
+            return;
+        }
+        // retryCount on the snapshot is incremented BY recovery-begin so the
+        // index for the backoff array is the current retryCount (0 → 200ms,
+        // 1 → 800ms, 2 → 2000ms).
+        const delay = RECOVERY_BACKOFF_MS[snap.retryCount] ??
+            RECOVERY_BACKOFF_MS[RECOVERY_BACKOFF_MS.length - 1];
+        recoveryTimer = setTimeout(() => {
+            recoveryTimer = null;
+            // Bail if state moved (e.g. broadcast already lifted us out of
+            // disconnected mid-backoff).
+            if (snap.state !== 'disconnected')
+                return;
+            dispatch({ type: 'recovery-begin' });
+            // After recovery-begin we are back in resolving-identity ; emit a
+            // recovery session-request and arm the carrier-miss timeout. We do
+            // NOT re-read storage/URL : on recovery, the identity should come
+            // from a fresh broadcast, not a stale tier-2 entry.
+            emitSessionRequest('recovery');
+            if (carrierTimeoutTimer !== null)
+                clearTimeout(carrierTimeoutTimer);
+            carrierTimeoutTimer = setTimeout(() => {
+                carrierTimeoutTimer = null;
+                dispatch({ type: 'carrier-timeout' });
+                // If carrier-timeout fired during recovery, we're now in error
+                // — clear storage to avoid auto-restoring on the next mount.
+                if (snap.state === 'error') {
+                    try {
+                        storageClearer();
+                    }
+                    catch {
+                        /* hardened mode */
+                    }
+                }
+            }, carrierTimeoutMs);
+        }, delay);
+    }
+    function notifyDisconnect(err) {
+        dispatch({ type: 'disconnect', code: err?.code, message: err?.message });
+        if (snap.state === 'disconnected') {
+            scheduleRecovery();
+        }
+    }
+    function ingestBroadcast(identity, eventOrigin) {
+        if (lockedParentOrigin === null) {
+            lockedParentOrigin = eventOrigin;
+        }
+        else if (lockedParentOrigin !== eventOrigin) {
+            return;
+        }
+        ingestBroadcastInternal(identity);
+    }
+    function getSnapshot() {
+        return snap;
+    }
+    return {
+        start,
+        stop,
+        reset,
+        getSnapshot,
+        subscribe,
+        notifyAuthSucceeded,
+        notifyAuthFailed,
+        notifyDisconnect,
+        ingestBroadcast,
+    };
+}
+// Re-export STORAGE_KEY for the namespace-pinning test.
+export { STORAGE_KEY };

package/dist/identity/session-query.d.ts

@@ -0,0 +1,4 @@
+/** Public URL hint parsing only; session admission remains server-owned. */
+export declare const PREVIEW_SESSION_QUERY_PARAM = "_ss_session";
+export declare function readPreviewSessionIdFromSearch(search: string, paramName?: string): string | null;
+export declare function hasPreviewSessionParam(search: string, paramName?: string): boolean;

package/dist/identity/session-query.js

@@ -0,0 +1,19 @@
+/** Public URL hint parsing only; session admission remains server-owned. */
+export const PREVIEW_SESSION_QUERY_PARAM = '_ss_session';
+export function readPreviewSessionIdFromSearch(search, paramName = PREVIEW_SESSION_QUERY_PARAM) {
+    try {
+        const sessionId = new URLSearchParams(search).get(paramName);
+        return sessionId !== null && sessionId.length > 0 ? sessionId : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function hasPreviewSessionParam(search, paramName = PREVIEW_SESSION_QUERY_PARAM) {
+    try {
+        return new URLSearchParams(search).has(paramName);
+    }
+    catch {
+        return false;
+    }
+}