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

package/dist/router-subscriber.js

@@ -0,0 +1,44 @@
+const NOOP = () => {
+    /* default — no adapter registered */
+};
+function subscriberCell() {
+    const existing = globalThis.__storystick_preview_router_subscriber__;
+    if (existing)
+        return existing;
+    const created = { subscriber: null };
+    globalThis.__storystick_preview_router_subscriber__ = created;
+    return created;
+}
+/**
+ * Register the router subscriber. Replaces any previously registered
+ * subscriber. Pass `null` to reset to the default no-op.
+ */
+export function setRouterSubscriber(fn) {
+    subscriberCell().subscriber = fn;
+}
+/**
+ * Read the currently-registered subscriber. Returns `null` before any
+ * adapter has called `setRouterSubscriber`. Consumers gate their
+ * invocation on the non-null return.
+ */
+export function getRouterSubscriber() {
+    return subscriberCell().subscriber;
+}
+/**
+ * Convenience for `activate()`'s router-transition path: invoke the
+ * currently-registered subscriber if any, no-op otherwise. Centralises
+ * the null-check so callers don't repeat it.
+ */
+export function notifyRouterTransition(transition) {
+    if (typeof window !== 'undefined')
+        window.dispatchEvent(new CustomEvent('storystick.preview.location-committed', { detail: transition }));
+    const fn = subscriberCell().subscriber ?? NOOP;
+    fn(transition);
+}
+/**
+ * Test-only reset. Vitest isolates modules per file but multiple
+ * cases inside one file would otherwise share state.
+ */
+export function _resetRouterSubscriberForTests() {
+    subscriberCell().subscriber = null;
+}

package/dist/runtime/anchor-types.d.ts

@@ -0,0 +1,5 @@
+/** Conserved deliberately: PathAnchor carries keyed annotation-model hops. */
+export interface PathAnchor {
+    pathPrefix: string;
+    key: string;
+}

package/dist/runtime/anchor-types.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime/authority-store.d.ts

@@ -0,0 +1,31 @@
+import type { Client } from "@storystick/client";
+import type { ConvexReactClient } from "convex/react";
+import type { PreviewReadContext } from "@storystick/types/preview-query-targeting";
+/**
+ * The narrow Preview authority projection consumed by query runtimes.
+ *
+ * Keep this module value-import free: production query hooks can depend on it
+ * without pulling the Preview overlay, identity resolver, or grant coordinator
+ * into their bundle.
+ */
+export interface PreviewAuthoritySnapshot {
+    readonly client: ConvexReactClient | null;
+    readonly httpClient: Client | null;
+    readonly sessionId: string | null;
+    readonly previewToken: string | null;
+    readonly variantId: string | null;
+    readonly releaseId: string | null;
+    readonly readContext: PreviewReadContext | null;
+}
+interface PreviewAuthorityCell {
+    snapshot: PreviewAuthoritySnapshot;
+    listeners: Set<() => void>;
+}
+declare global {
+    var __storystick_preview_authority__: PreviewAuthorityCell | undefined;
+}
+export declare function getPreviewAuthority(): PreviewAuthoritySnapshot;
+export declare function subscribePreviewAuthority(listener: () => void): () => void;
+/** Runtime bridge. Publish a complete projection to avoid mixed authority. */
+export declare function publishPreviewAuthority(next: PreviewAuthoritySnapshot): void;
+export {};

package/dist/runtime/authority-store.js

@@ -0,0 +1,56 @@
+const EMPTY_AUTHORITY = Object.freeze({
+    client: null,
+    httpClient: null,
+    sessionId: null,
+    previewToken: null,
+    variantId: null,
+    releaseId: null,
+    readContext: null,
+});
+function authorityCell() {
+    const existing = globalThis.__storystick_preview_authority__;
+    if (existing) {
+        if (!(existing.listeners instanceof Set))
+            existing.listeners = new Set();
+        return existing;
+    }
+    const created = {
+        snapshot: EMPTY_AUTHORITY,
+        listeners: new Set(),
+    };
+    globalThis.__storystick_preview_authority__ = created;
+    return created;
+}
+export function getPreviewAuthority() {
+    return authorityCell().snapshot;
+}
+export function subscribePreviewAuthority(listener) {
+    const cell = authorityCell();
+    cell.listeners.add(listener);
+    return () => {
+        cell.listeners.delete(listener);
+    };
+}
+/** Runtime bridge. Publish a complete projection to avoid mixed authority. */
+export function publishPreviewAuthority(next) {
+    const cell = authorityCell();
+    const current = cell.snapshot;
+    if (current.client === next.client &&
+        current.httpClient === next.httpClient &&
+        current.sessionId === next.sessionId &&
+        current.previewToken === next.previewToken &&
+        current.variantId === next.variantId &&
+        current.releaseId === next.releaseId &&
+        current.readContext === next.readContext) {
+        return;
+    }
+    cell.snapshot = Object.freeze({ ...next });
+    for (const listener of cell.listeners) {
+        try {
+            listener();
+        }
+        catch {
+            /* defensive — one observer must not break the authority fan-out */
+        }
+    }
+}

package/dist/runtime/boot.d.ts

@@ -0,0 +1,52 @@
+/**
+ * ADR-131 Amendment 002 + chantier-decomposition.md §3 — iframe runtime
+ * boot orchestrator.
+ *
+ * Wires schema delivery and preview interaction listeners into a coherent
+ * runtime. Called
+ * by the iframe-side `<Storystick />` adapter (`@storystick/next`) in
+ * preview mode.
+ *
+ *   ┌────────────────────────────────────────────────────────────────┐
+ *   │ bootIframeRuntime(opts) — once per <Storystick /> mount        │
+ *   │                                                                │
+ *   │  bootSchema + retry loop                                       │
+ *   │                                                                 │
+ *   │  window.message → overlay / v2 handlers                        │
+ *   │                                                                 │
+ *   │ Returns teardown() — caller invokes on HMR / unmount.           │
+ *   └────────────────────────────────────────────────────────────────┘
+ *
+ * Idempotent : a second `bootIframeRuntime()` call is a noop while the
+ * first is still active (returns the same teardown).
+ */
+declare global {
+    interface Window {
+        __storystickPreviewOverlayMapOwner?: "boot";
+    }
+}
+export interface BootIframeRuntimeOpts {
+    /** Document under observation. Defaults to `window.document`. */
+    document?: Document;
+}
+export interface IframeRuntimeHandle {
+    /** Tear down the runtime and release listeners. */
+    teardown(): void;
+}
+/**
+ * Boot the iframe runtime. Idempotent — calling a second time before
+ * `teardown()` returns the existing handle. Concurrent first-time
+ * callers share a single boot promise (StrictMode double-mount safe).
+ *
+ * Returns `null` if any prerequisite is genuinely missing (no Document,
+ * no window). The `<Storystick />` adapter's preview mode is gated
+ * server-side, so this path only fires in environments where the
+ * window exists.
+ */
+export declare function bootIframeRuntime(opts?: BootIframeRuntimeOpts): Promise<IframeRuntimeHandle | null>;
+/**
+ * Test hook — clear the active handle, invoking teardown if present.
+ * Required when tests open + tear down many runtimes in sequence and
+ * need a clean module state.
+ */
+export declare function _resetBootForTestsOnly(): void;

package/dist/runtime/boot.js

@@ -0,0 +1,379 @@
+/**
+ * ADR-131 Amendment 002 + chantier-decomposition.md §3 — iframe runtime
+ * boot orchestrator.
+ *
+ * Wires schema delivery and preview interaction listeners into a coherent
+ * runtime. Called
+ * by the iframe-side `<Storystick />` adapter (`@storystick/next`) in
+ * preview mode.
+ *
+ *   ┌────────────────────────────────────────────────────────────────┐
+ *   │ bootIframeRuntime(opts) — once per <Storystick /> mount        │
+ *   │                                                                │
+ *   │  bootSchema + retry loop                                       │
+ *   │                                                                 │
+ *   │  window.message → overlay / v2 handlers                        │
+ *   │                                                                 │
+ *   │ Returns teardown() — caller invokes on HMR / unmount.           │
+ *   └────────────────────────────────────────────────────────────────┘
+ *
+ * Idempotent : a second `bootIframeRuntime()` call is a noop while the
+ * first is still active (returns the same teardown).
+ */
+import { bootSchema, startSchemaRetryLoop } from "./schema-store.js";
+import { previewRuntime } from "./store.js";
+import { applyPreviewOverlayMap, clearPreviewOverlayPaint, installPreviewEditInteractionGuard, revealPreviewV2SourceInIframe, } from "./preview-overlay-painter.js";
+import { installPreviewWorkspaceShortcuts } from "./workspace-shortcuts.js";
+import { installMomentaryNavigateKeyRelay } from "./momentary-navigate.js";
+import { validateOverlayClear, validateOverlayMap, validatePreviewV2RevealSource, } from "../validators.js";
+import { setInteractionMode } from "../interaction-mode.js";
+import { getReloadHandler } from "../nav-handler.js";
+import { PREVIEW_NAMESPACE, PREVIEW_PROTOCOL_VERSION, validatePreviewEnvelope, } from "@storystick/transport-allowlist";
+// ── Module-scoped singletons (forward-compat with HMR + StrictMode) ──
+let active = null;
+// Boot in-flight slot. Set SYNCHRONOUSLY at the start of bootIframeRuntime
+// (before the first await) so concurrent callers — StrictMode double-mount,
+// HMR re-mount — observe the same boot promise instead of racing to open
+// duplicate listeners. Released once boot resolves
+// (whether to a handle or null).
+let bootInFlight = null;
+function cryptoRandomHex() {
+    const bytes = new Uint8Array(16);
+    if (typeof crypto !== "undefined" &&
+        typeof crypto.getRandomValues === "function") {
+        crypto.getRandomValues(bytes);
+    }
+    else {
+        for (let index = 0; index < bytes.length; index++) {
+            bytes[index] = Math.floor(Math.random() * 256);
+        }
+    }
+    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function emitOverlayReady(view, payload) {
+    const identity = previewRuntime.getState().identity;
+    if (identity === null || identity.parentOrigin === null)
+        return;
+    const envelope = {
+        namespace: PREVIEW_NAMESPACE,
+        version: PREVIEW_PROTOCOL_VERSION,
+        type: "storystick.preview.overlay-ready",
+        sessionId: identity.sessionId,
+        projectId: identity.projectId,
+        requestId: cryptoRandomHex(),
+        nonce: cryptoRandomHex(),
+        sentAt: Date.now(),
+        payload,
+    };
+    view.parent.postMessage(envelope, identity.parentOrigin);
+}
+function emitOverlayClick(view, payload) {
+    const identity = previewRuntime.getState().identity;
+    if (identity === null || identity.parentOrigin === null)
+        return;
+    const envelope = {
+        namespace: PREVIEW_NAMESPACE,
+        version: PREVIEW_PROTOCOL_VERSION,
+        type: "storystick.preview.overlay-click",
+        sessionId: identity.sessionId,
+        projectId: identity.projectId,
+        requestId: cryptoRandomHex(),
+        nonce: cryptoRandomHex(),
+        sentAt: Date.now(),
+        payload,
+    };
+    view.parent.postMessage(envelope, identity.parentOrigin);
+}
+function emitIframeInteraction(view, payload) {
+    const identity = previewRuntime.getState().identity;
+    if (identity === null || identity.parentOrigin === null)
+        return;
+    const envelope = {
+        namespace: PREVIEW_NAMESPACE,
+        version: PREVIEW_PROTOCOL_VERSION,
+        type: "storystick.preview.iframe-interaction",
+        sessionId: identity.sessionId,
+        projectId: identity.projectId,
+        requestId: cryptoRandomHex(),
+        nonce: cryptoRandomHex(),
+        sentAt: Date.now(),
+        payload,
+    };
+    view.parent.postMessage(envelope, identity.parentOrigin);
+}
+function emitPreviewV2RevealResult(view, payload) {
+    const identity = previewRuntime.getState().identity;
+    if (identity === null || identity.parentOrigin === null)
+        return;
+    const envelope = {
+        namespace: PREVIEW_NAMESPACE,
+        version: PREVIEW_PROTOCOL_VERSION,
+        type: "storystick.preview.v2.reveal-result",
+        sessionId: identity.sessionId,
+        projectId: identity.projectId,
+        requestId: cryptoRandomHex(),
+        nonce: cryptoRandomHex(),
+        sentAt: Date.now(),
+        payload,
+    };
+    view.parent.postMessage(envelope, identity.parentOrigin);
+}
+/**
+ * Boot the iframe runtime. Idempotent — calling a second time before
+ * `teardown()` returns the existing handle. Concurrent first-time
+ * callers share a single boot promise (StrictMode double-mount safe).
+ *
+ * Returns `null` if any prerequisite is genuinely missing (no Document,
+ * no window). The `<Storystick />` adapter's preview mode is gated
+ * server-side, so this path only fires in environments where the
+ * window exists.
+ */
+export function bootIframeRuntime(opts) {
+    // Codex R1 fix — set the in-flight slot SYNCHRONOUSLY before any
+    // await so concurrent callers (StrictMode double-mount, HMR
+    // re-mount) share a single boot instead of racing to open duplicate
+    // caches / channels / listeners.
+    if (active !== null)
+        return Promise.resolve(active);
+    if (bootInFlight !== null)
+        return bootInFlight;
+    bootInFlight = (async () => {
+        // Preserve the in-flight slot's ordering now that boot has no I/O await:
+        // the caller must assign this promise before the finally block clears it.
+        await Promise.resolve();
+        let keepOverlayMapOwner = false;
+        let releaseOverlayMapOwner = () => {
+            /* unset until a Window is available */
+        };
+        try {
+            const doc = opts?.document ?? (typeof document !== "undefined" ? document : null);
+            if (doc === null)
+                return null;
+            const view = doc.defaultView ?? (typeof window !== "undefined" ? window : null);
+            if (view !== null) {
+                const previousOverlayMapOwner = view.__storystickPreviewOverlayMapOwner;
+                let released = false;
+                view.__storystickPreviewOverlayMapOwner = "boot";
+                releaseOverlayMapOwner = () => {
+                    if (released)
+                        return;
+                    released = true;
+                    if (previousOverlayMapOwner === undefined) {
+                        delete view.__storystickPreviewOverlayMapOwner;
+                    }
+                    else {
+                        view.__storystickPreviewOverlayMapOwner = previousOverlayMapOwner;
+                    }
+                };
+            }
+            // 1. Boot schema. Two cooperating mechanisms :
+            //    - An EAGER `bootSchema()` call : on a fresh iframe with an
+            //      already-fetched IDB cache (or a fast network), the schema
+            //      lands in the in-memory record within microseconds. The
+            //      retry orchestrator's attempt 1 at t=1s then sees the
+            //      cache hit and bails without any UI signal — fast path
+            //      preserved (codex R2 P2 fix).
+            //    - The retry orchestrator owns the full attempt cycle
+            //      (§9.T7) : 5 attempts at exponential backoff (1s, 2s,
+            //      4s, 8s, 16s — attempt 1 at t=1s, attempt 5 at t=31s),
+            //      with one warning emit at attempt 1 fail and one error
+            //      emit at attempt 5 fail. Counter resets on httpClient
+            //      or projectId change.
+            void bootSchema();
+            const teardownSchemaRetry = startSchemaRetryLoop();
+            let teardownEditInteractionGuard = null;
+            const ensureEditInteractionGuard = () => {
+                if (view === null || teardownEditInteractionGuard !== null)
+                    return;
+                teardownEditInteractionGuard = installPreviewEditInteractionGuard(view, {
+                    onInteraction: (payload) => emitIframeInteraction(view, payload),
+                });
+            };
+            if (previewRuntime.getState().identity?.parentOrigin !== null) {
+                ensureEditInteractionGuard();
+            }
+            const teardownWorkspaceShortcuts = view === null
+                ? () => { }
+                : installPreviewWorkspaceShortcuts(view, () => {
+                    const state = previewRuntime.getState();
+                    return state.previewEnded ? null : state.identity;
+                }, undefined, previewRuntime.subscribeIdentity);
+            const teardownMomentaryNavigateKeyRelay = view === null
+                ? null
+                : installMomentaryNavigateKeyRelay(view, {
+                    getTargetOrigin: () => previewRuntime.getState().identity?.parentOrigin ?? null,
+                });
+            // 2. Studio → iframe postMessage path.
+            const onMessage = (ev) => {
+                if (view === null)
+                    return;
+                const data = ev.data;
+                const rawType = data !== null && typeof data === "object"
+                    ? data.type
+                    : null;
+                if (rawType === "storystick.preview.interaction-mode") {
+                    const identity = previewRuntime.getState().identity;
+                    if (identity === null || identity.parentOrigin === null)
+                        return;
+                    const base = validatePreviewEnvelope(data);
+                    if (!base.ok ||
+                        base.message.type !== "storystick.preview.interaction-mode") {
+                        return;
+                    }
+                    if (ev.origin !== identity.parentOrigin)
+                        return;
+                    if (base.message.sessionId !== identity.sessionId)
+                        return;
+                    if (base.message.projectId !== identity.projectId)
+                        return;
+                    ensureEditInteractionGuard();
+                    setInteractionMode(base.message.payload.mode);
+                    return;
+                }
+                if (rawType === "storystick.preview.reload") {
+                    const identity = previewRuntime.getState().identity;
+                    if (identity === null || identity.parentOrigin === null)
+                        return;
+                    const base = validatePreviewEnvelope(data);
+                    if (!base.ok || base.message.type !== "storystick.preview.reload") {
+                        return;
+                    }
+                    if (ev.origin !== identity.parentOrigin)
+                        return;
+                    if (base.message.sessionId !== identity.sessionId)
+                        return;
+                    if (base.message.projectId !== identity.projectId)
+                        return;
+                    getReloadHandler()(base.message.payload.mode, {
+                        commandId: base.message.payload.commandId,
+                    });
+                    return;
+                }
+                if (rawType === "storystick.preview.overlay-map") {
+                    const identity = previewRuntime.getState().identity;
+                    if (identity === null || identity.parentOrigin === null)
+                        return;
+                    const overlayMap = validateOverlayMap(data, ev.origin, identity.sessionId, identity.projectId, identity.parentOrigin);
+                    if (!overlayMap.ok)
+                        return;
+                    ensureEditInteractionGuard();
+                    const result = applyPreviewOverlayMap(overlayMap.envelope.payload, view, {
+                        onClick: (payload) => emitOverlayClick(view, payload),
+                    });
+                    emitOverlayReady(view, {
+                        generation: result.generation,
+                        paintedCount: result.paintedCount,
+                        missingSnapshotItemKeys: result.missingSnapshotItemKeys,
+                        routeHash: overlayMap.envelope.payload.routeHash,
+                        codeVersion: overlayMap.envelope.payload.codeVersion,
+                        renderId: overlayMap.envelope.payload.renderId,
+                    });
+                    return;
+                }
+                if (rawType === "storystick.preview.overlay-clear") {
+                    const identity = previewRuntime.getState().identity;
+                    if (identity === null || identity.parentOrigin === null)
+                        return;
+                    const overlayClear = validateOverlayClear(data, ev.origin, identity.sessionId, identity.projectId, identity.parentOrigin);
+                    if (!overlayClear.ok)
+                        return;
+                    ensureEditInteractionGuard();
+                    clearPreviewOverlayPaint();
+                    return;
+                }
+                if (rawType === "storystick.preview.v2.reveal-source") {
+                    const identity = previewRuntime.getState().identity;
+                    if (identity === null || identity.parentOrigin === null)
+                        return;
+                    const revealSource = validatePreviewV2RevealSource(data, ev.origin, identity.sessionId, identity.projectId, identity.parentOrigin);
+                    if (!revealSource.ok)
+                        return;
+                    const result = revealPreviewV2SourceInIframe(revealSource.envelope.payload, view);
+                    emitPreviewV2RevealResult(view, {
+                        requestId: revealSource.envelope.payload.requestId,
+                        sourceKey: revealSource.envelope.payload.sourceKey,
+                        targetSelection: revealSource.envelope.payload.targetSelection,
+                        status: result.status,
+                        revealedCount: result.revealedCount,
+                    });
+                    return;
+                }
+                return;
+            };
+            if (view !== null) {
+                view.addEventListener("message", onMessage);
+            }
+            // Deliberate annotation seam: the iframe runtime never observes
+            // customer DOM output to infer ownership. It reads the annotations
+            // authored by SDK resolution functions.
+            const handle = {
+                teardown() {
+                    if (active !== handle)
+                        return;
+                    try {
+                        if (view !== null)
+                            view.removeEventListener("message", onMessage);
+                    }
+                    catch {
+                        /* defensive */
+                    }
+                    try {
+                        teardownEditInteractionGuard?.();
+                        teardownEditInteractionGuard = null;
+                    }
+                    catch {
+                        /* defensive */
+                    }
+                    try {
+                        teardownWorkspaceShortcuts();
+                        teardownMomentaryNavigateKeyRelay?.();
+                    }
+                    catch {
+                        /* defensive */
+                    }
+                    try {
+                        clearPreviewOverlayPaint();
+                    }
+                    catch {
+                        /* defensive */
+                    }
+                    releaseOverlayMapOwner();
+                    try {
+                        teardownSchemaRetry();
+                    }
+                    catch {
+                        /* defensive */
+                    }
+                    active = null;
+                },
+            };
+            active = handle;
+            keepOverlayMapOwner = true;
+            return handle;
+        }
+        finally {
+            if (!keepOverlayMapOwner) {
+                releaseOverlayMapOwner();
+            }
+            bootInFlight = null;
+        }
+    })();
+    return bootInFlight;
+}
+/**
+ * Test hook — clear the active handle, invoking teardown if present.
+ * Required when tests open + tear down many runtimes in sequence and
+ * need a clean module state.
+ */
+export function _resetBootForTestsOnly() {
+    if (active !== null) {
+        try {
+            active.teardown();
+        }
+        catch {
+            /* defensive */
+        }
+    }
+    active = null;
+    bootInFlight = null;
+}

package/dist/runtime/content-refresh.d.ts

@@ -0,0 +1,30 @@
+import { type PreviewContentRefreshDecision } from '../provenance/index.js';
+import type { PreviewQueryTargetingSignalV1 } from '@storystick/types/preview-query-targeting';
+export declare const PREVIEW_CONTENT_REFRESH_SOURCE = "preview-session-content-revision";
+export type PreviewContentRefreshReason = 'missed-initial-revision' | 'forward-revision-jump' | 'reactive-dependency-change';
+export interface PreviewContentRefreshEvent {
+    /**
+     * Contract owner for content refreshes. This intentionally names the
+     * Convex preview-session row, not postMessage: content refresh is a
+     * data-subscription signal consumed by the customer router adapter.
+     */
+    source: typeof PREVIEW_CONTENT_REFRESH_SOURCE;
+    revision: number;
+    previousRevision: number | null;
+    reason: PreviewContentRefreshReason;
+    refresh: boolean;
+    affectedFrameIds: readonly string[];
+    decisionReason: PreviewContentRefreshDecision['reason'];
+    /**
+     * Exact Content Plane source sequence committed before this invalidation.
+     * Framework adapters wait until the public projection covers it before
+     * replacing a valid server-rendered tree.
+     */
+    requiredProjectedThroughSeq?: number;
+    queryTargeting?: PreviewQueryTargetingSignalV1;
+}
+export interface ContentRevisionObservation {
+    observedRevision: number;
+    event: PreviewContentRefreshEvent | null;
+}
+export declare function observeContentRevision(previousRevision: number | null, nextRevision: number, decision?: PreviewContentRefreshDecision, requiredProjectedThroughSeq?: number, queryTargetingChanged?: boolean, queryTargeting?: PreviewQueryTargetingSignalV1): ContentRevisionObservation;

package/dist/runtime/content-refresh.js

@@ -0,0 +1,68 @@
+import { createPreviewContentRefreshDecision, } from '../provenance/index.js';
+export const PREVIEW_CONTENT_REFRESH_SOURCE = 'preview-session-content-revision';
+export function observeContentRevision(previousRevision, nextRevision, decision, requiredProjectedThroughSeq, queryTargetingChanged = false, queryTargeting) {
+    const refreshDecision = decision ?? createPreviewContentRefreshDecision({
+        refresh: true,
+        affectedFrameIds: [],
+        reason: 'legacy-refresh',
+    });
+    if (previousRevision === null) {
+        return {
+            observedRevision: nextRevision,
+            event: nextRevision > 0
+                ? {
+                    source: PREVIEW_CONTENT_REFRESH_SOURCE,
+                    revision: nextRevision,
+                    previousRevision: null,
+                    reason: 'missed-initial-revision',
+                    refresh: refreshDecision.refresh,
+                    affectedFrameIds: refreshDecision.affectedFrameIds,
+                    decisionReason: refreshDecision.reason,
+                    ...queryTargetingRequirement(queryTargeting),
+                    ...projectionRequirement(requiredProjectedThroughSeq),
+                }
+                : null,
+        };
+    }
+    if (nextRevision <= previousRevision) {
+        return {
+            observedRevision: previousRevision,
+            event: decision !== undefined &&
+                (refreshDecision.refresh || queryTargetingChanged)
+                ? {
+                    source: PREVIEW_CONTENT_REFRESH_SOURCE,
+                    revision: previousRevision,
+                    previousRevision,
+                    reason: 'reactive-dependency-change',
+                    refresh: refreshDecision.refresh,
+                    affectedFrameIds: refreshDecision.affectedFrameIds,
+                    decisionReason: refreshDecision.reason,
+                    ...queryTargetingRequirement(queryTargeting),
+                    ...projectionRequirement(requiredProjectedThroughSeq),
+                }
+                : null,
+        };
+    }
+    return {
+        observedRevision: nextRevision,
+        event: {
+            source: PREVIEW_CONTENT_REFRESH_SOURCE,
+            revision: nextRevision,
+            previousRevision,
+            reason: 'forward-revision-jump',
+            refresh: refreshDecision.refresh,
+            affectedFrameIds: refreshDecision.affectedFrameIds,
+            decisionReason: refreshDecision.reason,
+            ...queryTargetingRequirement(queryTargeting),
+            ...projectionRequirement(requiredProjectedThroughSeq),
+        },
+    };
+}
+function queryTargetingRequirement(value) {
+    return value === undefined ? {} : { queryTargeting: value };
+}
+function projectionRequirement(value) {
+    return Number.isSafeInteger(value) && value >= 0
+        ? { requiredProjectedThroughSeq: value }
+        : {};
+}