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

package/dist/runtime/store.js

@@ -0,0 +1,1026 @@
+import { sendPreviewPerspectiveCommand } from '../context-command.js';
+import { isPreviewReadContext } from '@storystick/types/preview-query-targeting';
+/**
+ * `previewRuntime` — module-level singleton (ADR-099 D11 + ADR-116).
+ *
+ * Five concerns the Provider used to handle, ported to imperative
+ * methods on this singleton (D11.1) :
+ *
+ *  1. Convergent grant lifecycle with a compatibility projection for
+ *     framework adapters that still consume the historical state field.
+ *
+ *  2. `httpClient` (ConvexReactClient) lifecycle. Built on first JWT
+ *     arrival ; disposed via `dispose()`. HMR resets on module reload.
+ *
+ *  3. In-place Convex auth fetcher fed only by the same-origin grant route.
+ *
+ *  4. Session subscription gated on token presence (NOT
+ *     lifecycle state). Survives the `authenticated → refreshing →
+ *     authenticated` cycle. (Provider's codex Lane D round 10 P1.)
+ *
+ *  5. `contentRevision` driver. Listeners observe forward jumps and
+ *     fire `router.refresh()` (the `<Storystick />` Client Component
+ *     holds the `useRouter()` reference ; the singleton stays
+ *     framework-agnostic).
+ *
+ * ADR-116 (PR4) — the identity resolver replaces `defaultDetectPreview`.
+ * Boot path :
+ *
+ *   init(opts)
+ *     → compare-and-set (D5 invariant 1 — set inFlightInitPromise
+ *        BEFORE notify so a synchronous-reentrant init() observes the
+ *        slot populated)
+ *     → resolver.start() resolves the identity via carrier chain
+ *        (broadcast > storage > URL — ADR-116 D3)
+ *     → on first identity (provisional or live), start the same-origin grant
+ *        coordinator and secret-free control plane for that sessionId
+ *
+ * Full runtime cell persists on `globalThis.__storystick_preview_runtime__`
+ * (D5 invariant 2 — codex R6 #3). Persisting only `state` is INSUFFICIENT :
+ * Next Fast Refresh re-evaluates the module body but does NOT remount
+ * every `useSyncExternalStore` consumer ; old consumers stay subscribed
+ * to the OLD module's `listeners` Set. The full cell (state + listeners +
+ * revisionListeners + inFlightInitPromise + cleanups + identity resolver
+ * handles) on `globalThis` keeps emissions and subscriptions aligned
+ * across HMR.
+ *
+ * Per CSO-PREVIEW-11 — per-tab in-memory only. Module-level `let` state
+ * (and the `globalThis` cell) ; no SharedWorker / ServiceWorker /
+ * BroadcastChannel / localStorage. The new sessionStorage carrier (PR2)
+ * is tier-2 identity persistence within the iframe origin partition —
+ * distinct from cross-tab/process IPC.
+ */
+import { ConvexReactClient } from "convex/react";
+import { PREVIEW_NAMESPACE, PREVIEW_PROTOCOL_VERSION, } from "@storystick/transport-allowlist";
+import { activate } from "../index.js";
+import { createPreviewGrantCoordinator, } from "../grant-coordinator.js";
+import { legacyPreviewAuthState, } from "../grant-lifecycle.js";
+import { isTerminalPreviewSessionErrorCode, subscribePreviewContentSignal, subscribePreviewSession, } from "../session-subscriber.js";
+import { createIdentityResolver, } from "../identity/index.js";
+import { createUrlCarrier } from "../identity/carriers/url.js";
+import { createStorageCarrier, clearStored, clearStandaloneStored, writeStandaloneStored, rememberStandaloneStudioUrl } from "../identity/carriers/storage.js";
+import { observeContentRevision, } from "./content-refresh.js";
+import { publishPreviewAuthority } from "./authority-store.js";
+import { recordPreviewPerfMetric } from "./perf-metrics.js";
+const INITIAL_STATE = {
+    state: "idle",
+    lifecycle: null,
+    client: null,
+    previewToken: null,
+    cookieLifecycle: null,
+    error: null,
+    contentRevision: null,
+    sessionId: null,
+    session: null,
+    renderedReadContext: null,
+    variantId: null,
+    releaseId: null,
+    identity: null,
+    httpClient: null,
+};
+/**
+ * ADR-116 R7 fix — hydrate the cell defensively when an older SDK
+ * version (or an HMR intermediate that wrote a partial shape) already
+ * populated `globalThis.__storystick_preview_runtime__`. The default-
+ * value pattern with `||` only triggered when the slot was undefined ;
+ * a partial cell (e.g., one that predates `identityListeners` being
+ * added in PR4) would surface as runtime crashes on `.add()` of a
+ * `Set` that does not exist. Always backfill missing fields against
+ * the current shape before using the cell.
+ */
+function hydrateCell(existing) {
+    const defaults = {
+        state: { ...INITIAL_STATE },
+        listeners: new Set(),
+        revisionListeners: new Set(),
+        contentRefreshListeners: new Set(),
+        identityListeners: new Set(),
+        inFlightInitPromise: null,
+        cleanupActivate: null,
+        grantCoordinator: null,
+        grantGeneration: 0,
+        sessionSnapshotReady: false,
+        signalSnapshotReady: false,
+        cleanupSubscription: null,
+        subscriptionSessionId: null,
+        cleanupResolver: null,
+        lastObservedRevision: null,
+        lastQueryTargetingFingerprint: null,
+        pendingRevisionNotification: null,
+        pendingContentRefreshEvent: null,
+        terminal: false,
+        resolver: null,
+        authedSessionId: null,
+    };
+    if (!existing)
+        return defaults;
+    return {
+        state: { ...defaults.state, ...(existing.state ?? {}) },
+        listeners: existing.listeners instanceof Set ? existing.listeners : new Set(),
+        revisionListeners: existing.revisionListeners instanceof Set
+            ? existing.revisionListeners
+            : new Set(),
+        contentRefreshListeners: existing.contentRefreshListeners instanceof Set
+            ? existing.contentRefreshListeners
+            : new Set(),
+        identityListeners: existing.identityListeners instanceof Set
+            ? existing.identityListeners
+            : new Set(),
+        inFlightInitPromise: existing.inFlightInitPromise ?? null,
+        cleanupActivate: existing.cleanupActivate ?? null,
+        grantCoordinator: existing.grantCoordinator ?? null,
+        grantGeneration: existing.grantGeneration ?? 0,
+        sessionSnapshotReady: existing.sessionSnapshotReady ?? false,
+        signalSnapshotReady: existing.signalSnapshotReady ?? false,
+        cleanupSubscription: existing.cleanupSubscription ?? null,
+        cleanupRenderObservation: existing.cleanupRenderObservation,
+        subscriptionSessionId: existing.subscriptionSessionId ?? null,
+        cleanupResolver: existing.cleanupResolver ?? null,
+        lastObservedRevision: existing.lastObservedRevision ?? null,
+        lastQueryTargetingFingerprint: existing.lastQueryTargetingFingerprint ?? null,
+        pendingRevisionNotification: existing.pendingRevisionNotification ?? null,
+        pendingContentRefreshEvent: existing.pendingContentRefreshEvent ?? null,
+        terminal: existing.terminal ?? false,
+        resolver: existing.resolver ?? null,
+        authedSessionId: existing.authedSessionId ?? null,
+    };
+}
+function scopeFields(scope) {
+    return scope.kind === "variant"
+        ? { variantId: scope.variantId, releaseId: null }
+        : scope.kind === "release"
+            ? { variantId: null, releaseId: scope.releaseId }
+            : { variantId: null, releaseId: null };
+}
+const cell = hydrateCell(typeof globalThis !== "undefined"
+    ? globalThis.__storystick_preview_runtime__
+    : undefined);
+if (typeof globalThis !== "undefined") {
+    globalThis.__storystick_preview_runtime__ = cell;
+}
+function publishAuthorityFromState() {
+    publishPreviewAuthority({
+        client: cell.state.client,
+        httpClient: cell.state.httpClient,
+        sessionId: cell.state.sessionId,
+        previewToken: cell.state.previewToken,
+        variantId: cell.state.variantId,
+        releaseId: cell.state.releaseId,
+        readContext: cell.state.session?.readContext ?? null,
+    });
+}
+publishAuthorityFromState();
+let lastReadContextNotification = "";
+function notify() {
+    const notification = JSON.stringify([cell.state.sessionId, cell.state.session?.readContext,
+        cell.state.session?.readContextStatus, cell.state.state]);
+    if (notification !== lastReadContextNotification && typeof window !== "undefined") {
+        lastReadContextNotification = notification;
+        cell.state = { ...cell.state, renderedReadContext: null };
+        window.dispatchEvent(new CustomEvent("storystick.preview.read-context-changed"));
+    }
+    for (const l of cell.listeners) {
+        try {
+            l();
+        }
+        catch {
+            /* defensive — listener exceptions never break the fan-out */
+        }
+    }
+}
+function notifyIdentity(identity) {
+    for (const l of cell.identityListeners) {
+        try {
+            l(identity);
+        }
+        catch {
+            /* defensive */
+        }
+    }
+}
+/**
+ * Sticky-error double-defense (`provider.tsx:278-300` port).
+ *  - Layer (a) : synchronous flag flipped the moment `'error'` is
+ *    requested (BEFORE applying the partial).
+ *  - Layer (b) : assignment short-circuits when current
+ *    `state.state === 'error'`.
+ * Both layers MUST stay in place. (a) alone races on batched updates ;
+ * (b) alone misses callbacks captured before state reaches the
+ * listener fan-out.
+ */
+function _setStatePartial(partial) {
+    cell.state = { ...cell.state, ...partial };
+    cell.terminal = partial.state === "error";
+    publishAuthorityFromState();
+    notify();
+}
+function emitContentRefresh(event) {
+    if (cell.contentRefreshListeners.size === 0) {
+        cell.pendingContentRefreshEvent = event;
+    }
+    else {
+        cell.pendingContentRefreshEvent = null;
+        for (const cb of cell.contentRefreshListeners) {
+            try {
+                cb(event);
+            }
+            catch {
+                /* defensive */
+            }
+        }
+    }
+    const revision = event.revision;
+    if (cell.revisionListeners.size === 0) {
+        cell.pendingRevisionNotification = revision;
+        return;
+    }
+    cell.pendingRevisionNotification = null;
+    for (const cb of cell.revisionListeners) {
+        try {
+            cb(revision);
+        }
+        catch {
+            /* defensive */
+        }
+    }
+}
+function previewQueryTargetingFingerprint(value) {
+    if (!value)
+        return 'none';
+    return [
+        value.version,
+        value.service,
+        [...value.coveredQueryReceiptIds].sort().join(','),
+        [...value.affectedQueryReceiptIds].sort().join(','),
+    ].join('|');
+}
+// ─────────────────────────────────────────────
+// Identity resolver wiring
+// ─────────────────────────────────────────────
+function buildResolver(opts) {
+    return createIdentityResolver({
+        expectedProjectId: opts.projectId,
+        carriers: {
+            storage: createStorageCarrier(),
+            url: createUrlCarrier(),
+        },
+    });
+}
+/**
+ * React to resolver state transitions. Maps `IdentitySnapshot` to
+ * `PreviewRuntimeState` and kicks off `activate()` when identity
+ * first resolves (or a Replace transition produces a new sessionId).
+ */
+function randomEnvelopeId() {
+    const bytes = new Uint8Array(16);
+    if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+        crypto.getRandomValues(bytes);
+        return Array.from(bytes, (value) => value.toString(16).padStart(2, "0")).join("");
+    }
+    return `${Date.now().toString(16)}${Math.random().toString(16).slice(2)}`;
+}
+function getLifecycleSnapshot() {
+    const lifecycle = cell.state.lifecycle;
+    if (!lifecycle)
+        return null;
+    return {
+        ...(cell.state.session?.readContext ? { readContext: cell.state.session.readContext } : {}),
+        ...(cell.state.contextCommand ? { contextCommand: cell.state.contextCommand } : {}),
+        ...(cell.state.renderedReadContext ? { renderedReadContext: cell.state.renderedReadContext } : {}),
+        phase: lifecycle.phase,
+        attempt: lifecycle.attempt,
+        since: lifecycle.since,
+        ...(lifecycle.phase === "ready"
+            ? { lastReadyAt: lifecycle.readyAt }
+            : lifecycle.phase === "reconnecting"
+                ? { lastReadyAt: lifecycle.lastReadyAt }
+                : {}),
+        ...(lifecycle.phase === "blocked" ? { code: lifecycle.code } : {}),
+    };
+}
+function emitLifecycleSnapshot() {
+    const lifecycle = cell.state.lifecycle;
+    const identity = cell.state.identity;
+    if (lifecycle === null ||
+        identity === null ||
+        identity.parentOrigin === null ||
+        typeof window === "undefined" ||
+        window.parent === window) {
+        return;
+    }
+    const envelope = {
+        namespace: PREVIEW_NAMESPACE,
+        version: PREVIEW_PROTOCOL_VERSION,
+        type: "storystick.preview.lifecycle",
+        sessionId: lifecycle.sessionId,
+        projectId: identity.projectId,
+        requestId: randomEnvelopeId(),
+        nonce: randomEnvelopeId(),
+        sentAt: Date.now(),
+        payload: getLifecycleSnapshot(),
+    };
+    window.parent.postMessage(envelope, identity.parentOrigin);
+}
+function setLifecycle(lifecycle) {
+    _setStatePartial({
+        lifecycle,
+        state: legacyPreviewAuthState(lifecycle),
+        error: lifecycle.phase === "blocked"
+            ? { code: lifecycle.code, message: lifecycle.message }
+            : null,
+    });
+    if (lifecycle.phase === "ready") {
+        cell.resolver?.notifyAuthSucceeded();
+    }
+    else if (lifecycle.phase === "blocked") {
+        cell.resolver?.notifyAuthFailed({
+            code: lifecycle.code,
+            message: lifecycle.message,
+        });
+    }
+    emitLifecycleSnapshot();
+}
+function restartControlPlane(identity, opts) {
+    cell.cleanupActivate?.();
+    cell.cleanupActivate = activate({
+        endpoint: opts.gatewaySyncUrl,
+        sessionId: identity.sessionId,
+        projectId: opts.projectId,
+        parentOrigin: identity.parentOrigin,
+        ...(isStandalonePreviewContext() && cell.state.previewToken !== null
+            ? { standaloneCapability: true }
+            : {}),
+        onSessionBroadcast: emitLifecycleSnapshot,
+    });
+    emitLifecycleSnapshot();
+}
+function isStandalonePreviewContext() {
+    if (typeof window === "undefined")
+        return false;
+    try {
+        return window.parent === window;
+    }
+    catch {
+        return false;
+    }
+}
+function installGrant(grant, identity, opts, generation) {
+    if (cell.grantGeneration !== generation ||
+        cell.state.sessionId !== identity.sessionId) {
+        return;
+    }
+    let client = cell.state.client;
+    if (client === null) {
+        client = new ConvexReactClient(opts.gatewaySyncUrl, {
+            skipConvexDeploymentUrlCheck: true,
+            expectAuth: true,
+        });
+    }
+    if (isStandalonePreviewContext())
+        writeStandaloneStored(identity);
+    _setStatePartial({ client, previewToken: grant.token });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    client.setAuth(async () => cell.state.previewToken);
+    // A public `_ss_session` selector is not sufficient to paint overlays in a
+    // standalone tab. Start the local control plane only after the origin's
+    // HttpOnly preview capability has yielded a valid access token.
+    if (isStandalonePreviewContext() && cell.cleanupActivate === null) {
+        restartControlPlane(identity, opts);
+    }
+    wireSessionSubscription(identity.sessionId, client);
+}
+function startGrant(identity, opts) {
+    cell.grantCoordinator?.stop();
+    cell.grantCoordinator = null;
+    cell.cleanupSubscription?.();
+    cell.cleanupSubscription = null;
+    cell.subscriptionSessionId = null;
+    if (cell.state.client !== null) {
+        try {
+            void cell.state.client.close();
+        }
+        catch {
+            /* defensive */
+        }
+    }
+    cell.grantGeneration += 1;
+    const generation = cell.grantGeneration;
+    cell.authedSessionId = identity.sessionId;
+    cell.sessionSnapshotReady = false;
+    cell.signalSnapshotReady = false;
+    cell.lastObservedRevision = null;
+    cell.lastQueryTargetingFingerprint = null;
+    cell.pendingRevisionNotification = null;
+    cell.pendingContentRefreshEvent = null;
+    _setStatePartial({
+        client: null,
+        previewToken: null,
+        session: null,
+        contentRevision: null,
+        sessionId: identity.sessionId,
+        variantId: null,
+        releaseId: null,
+        contextCommand: undefined,
+    });
+    if (isStandalonePreviewContext()) {
+        cell.cleanupActivate?.();
+        cell.cleanupActivate = null;
+    }
+    else {
+        restartControlPlane(identity, opts);
+    }
+    const coordinator = createPreviewGrantCoordinator({
+        sessionId: identity.sessionId,
+        projectId: opts.projectId,
+        ...(opts.tokenRoute !== undefined ? { tokenRoute: opts.tokenRoute } : {}),
+        generation,
+        onGrant: (grant) => installGrant(grant, identity, opts, generation),
+        onLifecycle: (lifecycle) => {
+            if (cell.grantGeneration !== generation)
+                return;
+            setLifecycle(lifecycle);
+        },
+    });
+    cell.grantCoordinator = coordinator;
+    coordinator.start();
+}
+function onResolverSnapshot(snap, opts) {
+    const identity = snap.identity;
+    const previousIdentity = cell.state.identity;
+    if (identity !== previousIdentity) {
+        _setStatePartial({ identity, sessionId: identity?.sessionId ?? null });
+        notifyIdentity(identity);
+    }
+    if (snap.state === "error" && snap.error) {
+        _setStatePartial({ state: "error", error: snap.error });
+        return;
+    }
+    if (identity === null)
+        return;
+    if (cell.authedSessionId !== identity.sessionId) {
+        startGrant(identity, opts);
+        return;
+    }
+    if (previousIdentity?.parentOrigin !== identity.parentOrigin) {
+        if (!isStandalonePreviewContext() || cell.state.previewToken !== null) {
+            restartControlPlane(identity, opts);
+        }
+    }
+}
+async function init(opts) {
+    if (cell.state.previewEnded)
+        return;
+    if (!cell.cleanupRenderObservation && typeof window !== 'undefined') {
+        // Editable query provenance and the framework's server-render receipt
+        // attest the same context. An empty page may have only the latter.
+        let queryContext = null;
+        let frameworkContext = null;
+        const clear = () => { queryContext = null; frameworkContext = null; };
+        const observe = (event) => {
+            const detail = event.detail;
+            if (!detail || typeof detail !== 'object' || !('sessionId' in detail) ||
+                detail.sessionId !== cell.state.sessionId || !('readContext' in detail))
+                return;
+            const rendered = detail.readContext;
+            const accepted = cell.state.session?.readContext;
+            if (rendered !== null && (!isPreviewReadContext(rendered) ||
+                cell.state.state !== 'authenticated' || cell.state.session?.readContextStatus !== 'active' ||
+                rendered.contextId !== accepted?.contextId || rendered.revision !== accepted?.revision))
+                return;
+            if ('source' in detail && detail.source === 'framework') {
+                frameworkContext = rendered;
+            }
+            else {
+                queryContext = rendered;
+            }
+            _setStatePartial({ renderedReadContext: frameworkContext ?? queryContext });
+            emitLifecycleSnapshot();
+        };
+        window.addEventListener('storystick.preview.read-context-changed', clear);
+        window.addEventListener('storystick.preview.rendered-context', observe);
+        cell.cleanupRenderObservation = () => {
+            window.removeEventListener('storystick.preview.read-context-changed', clear);
+            window.removeEventListener('storystick.preview.rendered-context', observe);
+        };
+    }
+    // ADR-116 D5 invariant 1 — compare-and-set atomicity. Only the first
+    // caller transitions out of idle/error. Concurrent callers (StrictMode
+    // double-mount, HMR re-mount, two adapter mounts) observe
+    // `inFlightInitPromise` and await it.
+    const currentState = cell.state.state;
+    if (currentState !== "idle" && currentState !== "error") {
+        // Already past idle — return any in-flight promise OR resolved.
+        return cell.inFlightInitPromise ?? Promise.resolve();
+    }
+    // CRITICAL — assign inFlightInitPromise BEFORE any _setStatePartial
+    // → notify (codex R6 #2). A synchronous-reentrant listener observing
+    // `state !== 'idle'` must find the promise slot populated, not null,
+    // so it awaits the real work instead of returning Promise.resolve().
+    let resolveOuter = () => { };
+    const flight = new Promise((resolve) => {
+        resolveOuter = resolve;
+    });
+    cell.inFlightInitPromise = flight;
+    // Build resolver lazily (once per cell — survives HMR + StrictMode).
+    if (cell.resolver === null) {
+        cell.resolver = buildResolver(opts);
+    }
+    if (cell.cleanupResolver === null && cell.resolver !== null) {
+        const r = cell.resolver;
+        cell.cleanupResolver = r.subscribe((snap) => onResolverSnapshot(snap, opts));
+    }
+    // Resolve `flight` when state machine settles at `authenticated` or
+    // `error`. Auto-unsubscribes on completion.
+    const unsub = subscribe(() => {
+        const s = cell.state.state;
+        if (s === "authenticated" || s === "error") {
+            unsub();
+            cell.inFlightInitPromise = null;
+            resolveOuter();
+        }
+    });
+    // Drive the resolver. start() resolves when the resolver leaves
+    // resolving-identity (to handshaking or error). Carrier hits +
+    // synchronous broadcasts both flow through onResolverSnapshot.
+    void cell.resolver.start();
+    return flight;
+}
+function markGrantReadyWhenLive() {
+    if (!cell.sessionSnapshotReady || !cell.signalSnapshotReady)
+        return;
+    cell.grantCoordinator?.markReady();
+}
+function wireSessionSubscription(sessionId, client) {
+    if (cell.cleanupSubscription !== null &&
+        cell.subscriptionSessionId === sessionId) {
+        return;
+    }
+    const previousSubscriptionSessionId = cell.subscriptionSessionId;
+    const previousSessionId = cell.state.session?.sessionId ?? null;
+    if (cell.cleanupSubscription !== null) {
+        try {
+            cell.cleanupSubscription();
+        }
+        catch {
+            /* defensive */
+        }
+        cell.cleanupSubscription = null;
+        cell.subscriptionSessionId = null;
+    }
+    if (previousSubscriptionSessionId !== sessionId ||
+        (previousSessionId !== null && previousSessionId !== sessionId)) {
+        cell.lastObservedRevision = null;
+        cell.lastQueryTargetingFingerprint = null;
+        cell.pendingRevisionNotification = null;
+        cell.pendingContentRefreshEvent = null;
+        _setStatePartial({ contentRevision: null, session: null });
+    }
+    const subscribeToQuery = (queryName, args, onUpdate, onError) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const watch = client.watchQuery?.(
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        queryName, args);
+        if (!watch || typeof watch.onUpdate !== "function") {
+            return () => { };
+        }
+        const stop = watch.onUpdate(() => {
+            try {
+                const value = watch.localQueryResult();
+                if (value !== undefined)
+                    onUpdate(value);
+            }
+            catch (err) {
+                onError?.(err);
+            }
+        });
+        return typeof stop === "function" ? stop : () => { };
+    };
+    const subscriptionGeneration = cell.grantGeneration;
+    const subscriptionIsCurrent = () => cell.grantGeneration === subscriptionGeneration &&
+        cell.subscriptionSessionId === sessionId;
+    const cleanupSession = subscribePreviewSession({
+        sessionId,
+        mode: "routing-only",
+        subscribe: (args, onUpdate, onError) => {
+            return subscribeToQuery("sdkQueries:getPreviewSession", args, onUpdate, onError);
+        },
+        onUpdate: (data) => {
+            if (!subscriptionIsCurrent())
+                return;
+            const previous = cell.state.session?.readContext;
+            if (previous?.contextId === data.readContext.contextId && previous.revision > data.readContext.revision)
+                return;
+            if (cell.state.identity && data.standaloneStudioUrl)
+                rememberStandaloneStudioUrl(cell.state.identity, data.standaloneStudioUrl);
+            _setStatePartial({ session: data, ...scopeFields(data.readContext.perspective) });
+            cell.sessionSnapshotReady = true;
+            if (data.readContextStatus === 'ended')
+                return;
+            markGrantReadyWhenLive();
+            emitLifecycleSnapshot();
+        },
+        onError: (code, message) => {
+            if (!subscriptionIsCurrent())
+                return;
+            if (!isTerminalPreviewSessionErrorCode(code)) {
+                cell.sessionSnapshotReady = false;
+                cell.grantCoordinator?.reportTransientFailure("subscription");
+                return;
+            }
+            cell.grantCoordinator?.reportBlocked(code, message);
+        },
+    });
+    const cleanupSignal = subscribePreviewContentSignal({
+        sessionId,
+        subscribe: (args, onUpdate, onError) => {
+            return subscribeToQuery("sdkQueries:getPreviewContentSignal", args, onUpdate, onError);
+        },
+        onUpdate: (data) => {
+            if (!subscriptionIsCurrent())
+                return;
+            const targetingFingerprint = previewQueryTargetingFingerprint(data.queryTargeting);
+            const queryTargetingChanged = targetingFingerprint !== cell.lastQueryTargetingFingerprint;
+            const observation = observeContentRevision(cell.lastObservedRevision, data.contentRevision, data.contentRefreshDecision, data.requiredProjectedThroughSeq, queryTargetingChanged, data.queryTargeting);
+            cell.lastQueryTargetingFingerprint = targetingFingerprint;
+            if (observation.observedRevision !== cell.lastObservedRevision) {
+                cell.lastObservedRevision = observation.observedRevision;
+                _setStatePartial({ contentRevision: observation.observedRevision });
+                // C1: record observed revision for e2e latency stitching (correlates
+                // Studio saveCommit/revision bump to downstream refresh+ paint).
+                if (typeof window !== "undefined") {
+                    recordPreviewPerfMetric(window, {
+                        name: "preview.contentRevisionObserved",
+                        detail: {
+                            revision: observation.observedRevision,
+                            requiredProjectedThroughSeq: data.requiredProjectedThroughSeq ?? null,
+                        },
+                    });
+                }
+            }
+            if (observation.event !== null) {
+                // The first subscription value can arrive after Studio already
+                // patched the preview session. Since createSession starts at
+                // revision 0, a first observed value > 0 is a missed forward
+                // jump, not a harmless baseline.
+                emitContentRefresh(observation.event);
+            }
+            cell.signalSnapshotReady = true;
+            markGrantReadyWhenLive();
+        },
+        onError: (code, message) => {
+            if (!subscriptionIsCurrent())
+                return;
+            if (!isTerminalPreviewSessionErrorCode(code)) {
+                cell.signalSnapshotReady = false;
+                cell.grantCoordinator?.reportTransientFailure("subscription");
+                return;
+            }
+            cell.grantCoordinator?.reportBlocked(code, message);
+        },
+    });
+    cell.subscriptionSessionId = sessionId;
+    cell.cleanupSubscription = () => {
+        cleanupSignal();
+        cleanupSession();
+        if (cell.subscriptionSessionId === sessionId) {
+            cell.subscriptionSessionId = null;
+        }
+    };
+}
+function dispose(preserveSubscribers = false) {
+    cell.grantGeneration += 1;
+    cell.grantCoordinator?.stop();
+    cell.grantCoordinator = null;
+    cell.cleanupActivate?.();
+    cell.cleanupActivate = null;
+    cell.cleanupSubscription?.();
+    cell.cleanupSubscription = null;
+    cell.subscriptionSessionId = null;
+    cell.cleanupResolver?.();
+    cell.cleanupResolver = null;
+    cell.cleanupRenderObservation?.();
+    cell.cleanupRenderObservation = undefined;
+    if (cell.resolver) {
+        try {
+            cell.resolver.stop();
+        }
+        catch {
+            /* defensive */
+        }
+        cell.resolver = null;
+    }
+    if (cell.state.client) {
+        try {
+            void cell.state.client.close();
+        }
+        catch {
+            /* defensive */
+        }
+    }
+    cell.state = { ...INITIAL_STATE };
+    publishAuthorityFromState();
+    cell.terminal = false;
+    cell.lastObservedRevision = null;
+    cell.lastQueryTargetingFingerprint = null;
+    cell.pendingRevisionNotification = null;
+    cell.pendingContentRefreshEvent = null;
+    cell.inFlightInitPromise = null;
+    cell.authedSessionId = null;
+    cell.sessionSnapshotReady = false;
+    cell.signalSnapshotReady = false;
+    if (preserveSubscribers)
+        return;
+    cell.listeners.clear();
+    cell.revisionListeners.clear();
+    cell.contentRefreshListeners.clear();
+    cell.identityListeners.clear();
+}
+function deactivate() {
+    dispose(true);
+    if (isStandalonePreviewContext())
+        clearStandaloneStored();
+    else
+        clearStored();
+    cell.state = { ...cell.state, previewEnded: true };
+    notifyIdentity(null);
+    notify();
+}
+function reportEndedContextLifecycle(context, error) {
+    const current = cell.state.session;
+    if (current?.readContextStatus !== 'ended' ||
+        current.readContext.contextId !== context.contextId ||
+        current.readContext.revision !== context.revision)
+        return false;
+    if (cell.grantCoordinator === null) {
+        _setStatePartial({ state: 'error', error });
+        return false;
+    }
+    cell.grantCoordinator.reportBlocked(error.code, error.message);
+    return true;
+}
+function confirmContextEnded(context) {
+    return reportEndedContextLifecycle(context, {
+        code: 'PREVIEW_CONTEXT_ENDED',
+        message: 'The shared Preview context ended.',
+    });
+}
+function reportContextExitUnavailable(context) {
+    return reportEndedContextLifecycle(context, {
+        code: 'PREVIEW_CONTEXT_EXIT_UNAVAILABLE',
+        message: 'The ended Preview context could not be cleared locally.',
+    });
+}
+function getState() {
+    return cell.state;
+}
+function subscribe(listener) {
+    cell.listeners.add(listener);
+    return () => {
+        cell.listeners.delete(listener);
+    };
+}
+function reactiveClient() {
+    return cell.state.client;
+}
+function subscribeContentRevision(cb) {
+    cell.revisionListeners.add(cb);
+    const pendingRevision = cell.pendingRevisionNotification;
+    if (pendingRevision !== null) {
+        cell.pendingRevisionNotification = null;
+        try {
+            cb(pendingRevision);
+        }
+        catch {
+            /* defensive */
+        }
+    }
+    return () => {
+        cell.revisionListeners.delete(cb);
+    };
+}
+function subscribeContentRefresh(cb) {
+    cell.contentRefreshListeners.add(cb);
+    const pendingEvent = cell.pendingContentRefreshEvent;
+    if (pendingEvent !== null) {
+        cell.pendingContentRefreshEvent = null;
+        try {
+            cb(pendingEvent);
+        }
+        catch {
+            /* defensive */
+        }
+    }
+    return () => {
+        cell.contentRefreshListeners.delete(cb);
+    };
+}
+function subscribeIdentity(cb) {
+    cell.identityListeners.add(cb);
+    return () => {
+        cell.identityListeners.delete(cb);
+    };
+}
+function getIdentity() {
+    return cell.state.identity;
+}
+function getVariantId() {
+    return cell.state.variantId;
+}
+async function changePerspective(command, route) {
+    const generation = cell.grantGeneration;
+    try {
+        const result = await sendPreviewPerspectiveCommand(route, command);
+        if (generation !== cell.grantGeneration)
+            return null;
+        const current = cell.state.session;
+        const observed = current?.readContext;
+        // An older HTTP response must not roll back a newer subscription result.
+        if (observed && observed.contextId !== result.context.contextId) {
+            cell.sessionSnapshotReady = false;
+            cell.grantCoordinator?.retryNow();
+        }
+        else if (current && (!observed || observed.revision <= result.context.revision)) {
+            _setStatePartial({ session: { ...current, readContext: result.context,
+                    readContextStatus: result.ended ? 'ended' : 'active',
+                    activeVariantId: result.context.perspective.kind === 'variant' ? result.context.perspective.variantId : null,
+                    activeReleaseId: result.context.perspective.kind === 'release' ? result.context.perspective.releaseId : null,
+                }, ...scopeFields(result.context.perspective) });
+        }
+        _setStatePartial({ contextCommand: result.status === 'applied'
+                ? { commandId: command.commandId, status: result.status, contextId: result.context.contextId, appliedRevision: result.appliedRevision }
+                : { commandId: command.commandId, status: result.status } });
+        emitLifecycleSnapshot();
+        const accepted = cell.state.session?.readContext;
+        return result.status === 'applied' && !result.ended && accepted &&
+            accepted.contextId === result.context.contextId && accepted.revision === result.appliedRevision
+            ? accepted : null;
+    }
+    catch {
+        if (generation !== cell.grantGeneration)
+            return null;
+        _setStatePartial({ contextCommand: { commandId: command.commandId, status: 'unavailable' } });
+        emitLifecycleSnapshot();
+        return null;
+    }
+}
+function setHttpClient(client) {
+    // Field-only update — see PreviewRuntime.setHttpClient docstring for
+    // why this bypasses the sticky-error gate. We notify listeners so any
+    // useSyncExternalStore consumers that read `httpClient` re-render
+    // (today : the iframe runtime boot orchestrator's bootSchema retry
+    // loop ; tomorrow : any tier-2/3 consumer that observes the SDK
+    // arrival).
+    if (cell.state.httpClient === client)
+        return;
+    cell.state = { ...cell.state, httpClient: client };
+    publishAuthorityFromState();
+    notify();
+}
+function observeCookieLifecycle(event) {
+    if (event.type === "refresh-failed") {
+        const current = cell.state.cookieLifecycle;
+        if (current === null || !Number.isFinite(event.at))
+            return;
+        _setStatePartial({
+            cookieLifecycle: {
+                ...current,
+                lastRefreshOutcome: {
+                    status: "failure",
+                    at: event.at,
+                    code: event.code,
+                },
+            },
+        });
+        return;
+    }
+    if (!Number.isFinite(event.mintedAt) ||
+        !Number.isFinite(event.expiresAt) ||
+        event.expiresAt <= event.mintedAt) {
+        return;
+    }
+    _setStatePartial({
+        cookieLifecycle: {
+            mintedAt: event.mintedAt,
+            expiresAt: event.expiresAt,
+            lastRefreshOutcome: event.type === "refresh-succeeded"
+                ? { status: "success", at: event.mintedAt }
+                : null,
+        },
+    });
+}
+function reportCookieTerminalFailure(error) {
+    if (cell.grantCoordinator !== null) {
+        // The same-origin grant route is now the authority for both the browser
+        // grant and the server cookie. A legacy adapter scheduler failure is a
+        // reconnect signal, never a sticky terminal state.
+        cell.grantCoordinator.reportTransientFailure("grant");
+        return;
+    }
+    _setStatePartial({
+        state: "error",
+        error: { code: error.code, message: error.message },
+    });
+}
+const __test = {
+    reset() {
+        cell.grantCoordinator?.stop();
+        cell.grantCoordinator = null;
+        cell.cleanupActivate?.();
+        cell.cleanupActivate = null;
+        cell.cleanupSubscription?.();
+        cell.cleanupSubscription = null;
+        cell.subscriptionSessionId = null;
+        cell.cleanupResolver?.();
+        cell.cleanupResolver = null;
+        cell.cleanupRenderObservation?.();
+        cell.cleanupRenderObservation = undefined;
+        if (cell.resolver) {
+            try {
+                cell.resolver.stop();
+            }
+            catch {
+                /* defensive */
+            }
+            cell.resolver = null;
+        }
+        if (cell.state.client) {
+            try {
+                void cell.state.client.close();
+            }
+            catch {
+                /* defensive */
+            }
+        }
+        cell.state = { ...INITIAL_STATE };
+        publishAuthorityFromState();
+        cell.terminal = false;
+        cell.lastObservedRevision = null;
+        cell.lastQueryTargetingFingerprint = null;
+        cell.pendingRevisionNotification = null;
+        cell.pendingContentRefreshEvent = null;
+        cell.inFlightInitPromise = null;
+        cell.authedSessionId = null;
+        cell.grantGeneration += 1;
+        cell.sessionSnapshotReady = false;
+        cell.signalSnapshotReady = false;
+        cell.listeners.clear();
+        cell.revisionListeners.clear();
+        cell.contentRefreshListeners.clear();
+        cell.identityListeners.clear();
+    },
+    set(partial) {
+        cell.state = { ...cell.state, ...partial };
+        publishAuthorityFromState();
+        if (partial.state === "error")
+            cell.terminal = true;
+        if (partial.state !== undefined && partial.state !== "error") {
+            cell.terminal = false;
+        }
+        notify();
+        if (partial.identity !== undefined)
+            notifyIdentity(partial.identity);
+    },
+    setResolver(resolver) {
+        if (cell.cleanupResolver) {
+            cell.cleanupResolver();
+            cell.cleanupResolver = null;
+        }
+        if (cell.resolver && cell.resolver !== resolver) {
+            try {
+                cell.resolver.stop();
+            }
+            catch {
+                /* defensive */
+            }
+        }
+        cell.resolver = resolver;
+    },
+    wireSessionSubscription(sessionId, client) {
+        wireSessionSubscription(sessionId, client);
+    },
+    getSubscriptionSessionId() {
+        return cell.subscriptionSessionId;
+    },
+};
+export const previewRuntime = {
+    init,
+    dispose,
+    deactivate,
+    confirmContextEnded,
+    reportContextExitUnavailable,
+    refreshGrant: () => { cell.sessionSnapshotReady = false; cell.grantCoordinator?.retryNow(); },
+    getState,
+    getLifecycleSnapshot,
+    subscribe,
+    reactiveClient,
+    subscribeContentRevision,
+    subscribeContentRefresh,
+    subscribeIdentity,
+    getIdentity,
+    getVariantId,
+    changePerspective,
+    setHttpClient,
+    observeCookieLifecycle,
+    reportCookieTerminalFailure,
+    __test,
+};