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

package/dist/index.js

@@ -0,0 +1,788 @@
+import { readStandalonePreviewSessionId } from './identity/browser-context.js';
+import { createPreviewRequestId } from './runtime/request-id.js';
+/**
+ * @storystick/preview — Visual editing overlay
+ *
+ * Framework-independent preview system for Storystick.
+ * Used by @storystick/react (and future @storystick/astro, etc.)
+ * via dynamic import — only loaded in preview mode.
+ *
+ * This package provides:
+ * - Proxy field tracking (wraps data, records field access)
+ * - DOM scanning (MutationObserver matches values to elements)
+ * - Overlay rendering (selection, drag handles, "+" buttons)
+ * - PostMessage bridge (iframe ↔ Studio communication)
+ * - Preview session management
+ */
+import { startSnapshotReporter, } from './runtime/snapshot-reporter.js';
+import { installPreviewWorkspaceShortcuts } from './runtime/workspace-shortcuts.js';
+import { previewRuntime } from './runtime/store.js';
+import { previewPerfNow, recordPreviewPerfMeasure, recordPreviewPerfMetric } from './runtime/perf-metrics.js';
+import { startStandaloneOverlayController } from './runtime/standalone-overlay-controller.js';
+/**
+ * SHA-256 hex of `routeUrl`, shared with the SDK document-observation
+ * tap and Studio route scoping.
+ *
+ * Web Crypto is the fast path. When `crypto.subtle` is unavailable —
+ * specifically in dev environments where the embedder chain is not a
+ * secure context (Studio on `http://storystick.dojo` embedding an
+ * iframe at `http://localhost` ; secure context inherits from the
+ * chain per W3C Secure Contexts §4.3) — we fall back to the pure-JS
+ * SHA-256 in `sha256-fallback.ts`. Output is byte-equivalent to Web
+ * Crypto's SHA-256 hex.
+ *
+ * The fallback is unit-tested for FIPS compliance ; it's a transcription
+ * of FIPS PUB 180-4 §6.2. Production paths (HTTPS↔HTTPS) always hit
+ * the Web Crypto branch.
+ */
+async function computeRouteHash(routeUrl) {
+    // crypto.subtle returns undefined in non-secure contexts ; guard
+    // explicitly rather than letting `crypto.subtle.digest` throw a
+    // `TypeError: Cannot read properties of undefined` every snapshot tick.
+    if (typeof crypto !== 'undefined' &&
+        crypto.subtle !== undefined &&
+        typeof crypto.subtle.digest === 'function') {
+        const bytes = new TextEncoder().encode(routeUrl);
+        const digest = await crypto.subtle.digest('SHA-256', bytes);
+        return Array.from(new Uint8Array(digest))
+            .map((b) => b.toString(16).padStart(2, '0'))
+            .join('');
+    }
+    const { sha256HexFallback } = await import('./sha256-fallback.js');
+    return sha256HexFallback(routeUrl);
+}
+import { startFormContractReporter, } from './runtime/form-contract-reporter.js';
+import { validateNavigate, validateOverlayClear, validateOverlayMap, } from './validators.js';
+import { applyPreviewOverlayMap, clearPreviewOverlayPaint, installPreviewEditInteractionGuard, } from './runtime/preview-overlay-painter.js';
+import { getAnchorFromPreviewClickEvent, installMomentaryNavigateKeyRelay, normalizeMomentaryNavigateLinkClick, } from './runtime/momentary-navigate.js';
+import { getNavigateHandler, getReloadHandler, hasNavigateHandler, } from './nav-handler.js';
+import { setRouterSubscriber, } from './router-subscriber.js';
+import { getInteractionMode, setInteractionMode } from './interaction-mode.js';
+import { PREVIEW_NAMESPACE, PREVIEW_PROTOCOL_VERSION, validatePreviewEnvelope, LOCATION_PATHNAME_MAX, LOCATION_SEARCH_MAX, LOCATION_HASH_MAX, ROUTE_RENDERED_CODE_VERSION_MAX, } from '@storystick/transport-allowlist';
+export { isIframeToStudio, isStudioToIframe } from './types.js';
+// ─────────────────────────────────────────────
+// Runtime — in-iframe SDK pieces (PR2', ADR-059 §Technical commitments)
+// ─────────────────────────────────────────────
+// ADR-129 — the atomic-snapshot reporter started by `activate()`.
+export { startSnapshotReporter, } from './runtime/snapshot-reporter.js';
+export { assembleSnapshot, } from './runtime/snapshot-assembly.js';
+export { startFormContractReporter, getStorystickViewport, FORM_PREVIEW_ATTR, } from './runtime/form-contract-reporter.js';
+export { getRenderMode, setRenderMode, subscribeRenderMode, debounceForRenderMode, } from './runtime/render-mode-state.js';
+// ─────────────────────────────────────────────
+// Preview grant lifecycle + control-plane surface
+// ─────────────────────────────────────────────
+//
+// The lifecycle, coordinator, validators, nav-handler, and session-subscriber
+// are split into their own
+// files (per-/plan-eng-review CQ1). The package re-exports the
+// public surface so `@storystick/react`'s provider has a single
+// import.
+export { validateNavigate, validateOverlayClear, validateOverlayMap, } from './validators.js';
+export { legacyPreviewAuthState, transitionPreviewGrantLifecycle, } from './grant-lifecycle.js';
+export { PREVIEW_TOKEN_ROUTE, PREVIEW_GRANT_RETRY_BACKOFF_MS, PreviewGrantRequestError, acquirePreviewBrowserGrant, createPreviewGrantCoordinator, } from './grant-coordinator.js';
+export { setNavigateHandler, getNavigateHandler, setReloadHandler, getReloadHandler, _resetNavigateHandlerForTests, } from './nav-handler.js';
+// ─── ADR-108 — router-subscriber + interaction-mode ──────────────
+export { setRouterSubscriber, getRouterSubscriber, notifyRouterTransition, _resetRouterSubscriberForTests, } from './router-subscriber.js';
+export { getInteractionMode, setInteractionMode, _resetInteractionModeForTests, } from './interaction-mode.js';
+export { subscribePreviewSession, mapPreviewSessionError, } from './session-subscriber.js';
+export { wrapWithProxy, getTrackedFields, clearTrackedFields, collectFieldModel, 
+// ADR-126 — RSC render-path field-model island plumbing.
+collectFieldModelFromRoots, registerIslandRoots, clearIslandRoots, isFieldTrackingActive, __setFieldTrackingForcedForTests, } from './runtime/field-proxy.js';
+// ─────────────────────────────────────────────
+// Activate — entry point for framework SDKs
+// ─────────────────────────────────────────────
+/**
+ * Activate the preview overlay system.
+ * Returns a cleanup function to tear down on unmount.
+ *
+ * Called by StorystickProvider when preview mode is detected.
+ * Auto-starts the in-iframe snapshot reporter so consumers get the
+ * postMessage bridge for free.
+ *
+ * Idempotency: a module-level refcount ensures repeated calls share
+ * a single reporter instance. The first activate() starts the
+ * reporter; subsequent calls only increment a counter. Each returned
+ * cleanup decrements; the reporter stops once the count reaches zero.
+ * This makes the function safe under React StrictMode's double-mount
+ * pattern and tolerant of accidental multi-Provider setups.
+ *
+ * A top-level page is eligible only when its scrubbed URL carries an explicit
+ * `_ss_session` selector. The reporter starts after the same-origin token route
+ * proves the HttpOnly capability; the public selector alone cannot paint
+ * overlays. In standalone mode the reporter stays local, without postMessage.
+ * Ordinary customer pages remain inert and do not load this package through
+ * the public adapter.
+ */
+let activeReporter = null;
+let activeFormContractReporter = null;
+let activeStandaloneOverlayCleanup = null;
+let activeRefCount = 0;
+// A document's Navigation Timing entry outlives activate/cleanup (including
+// StrictMode and grant renewal). Its initial history proof is considered once.
+let initialNavigationObserved = false;
+/**
+ * ADR-108 D1 — strip Storystick-internal preview params from a
+ * search string before serialising into a `location` envelope OR
+ * before comparing observed vs expected tuples for the
+ * pendingNavigate match. `_ss_session` is the load-bearing preview
+ * gate (drives `detectPreviewMode()`), `_ss_variant` is the
+ * variant-shadowing param. Customer-app params (`?utm=...`,
+ * `?id=42`) are preserved as-is so the chrome URL display and
+ * reverse doc lookup see the actual customer URL.
+ *
+ * Input: search WITHOUT the leading `?`. Output: same form, with
+ * the internal params removed. Empty string → empty string.
+ */
+function stripStorystickPreviewParams(search) {
+    if (search === '')
+        return '';
+    // Defensive: callers normalise to "no leading ?" but tolerate
+    // both for the comparison path.
+    const cleaned = search.startsWith('?') ? search.slice(1) : search;
+    if (cleaned === '')
+        return '';
+    const params = new URLSearchParams(cleaned);
+    for (const key of [...params.keys()]) {
+        // Includes the one-shot `_ss_activation` capability. It must never be
+        // reflected into Studio location state, navigation commands, or logs.
+        if (key.startsWith('_ss_'))
+            params.delete(key);
+    }
+    return params.toString();
+}
+function navigationStartPayloadFromBrowseClick(event, target, win = window) {
+    if (event.defaultPrevented)
+        return null;
+    if (event.button !== 0)
+        return null;
+    if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
+        return null;
+    }
+    if (target.hasAttribute('download'))
+        return null;
+    if (target.target.length > 0 && target.target !== '_self')
+        return null;
+    let url;
+    try {
+        url = new URL(target.href, win.location.href);
+    }
+    catch {
+        return null;
+    }
+    if (url.origin !== win.location.origin)
+        return null;
+    const search = stripStorystickPreviewParams(url.search.replace(/^\?/, ''));
+    const currentSearch = stripStorystickPreviewParams(win.location.search.replace(/^\?/, ''));
+    if (url.pathname === win.location.pathname &&
+        search === currentSearch) {
+        return null;
+    }
+    return {
+        pathname: url.pathname.slice(0, LOCATION_PATHNAME_MAX),
+        search: search.slice(0, LOCATION_SEARCH_MAX),
+        hash: url.hash.slice(0, LOCATION_HASH_MAX),
+        trigger: 'link-click',
+    };
+}
+/**
+ * PR-1 — best-effort read of the customer page's code-bundle version,
+ * mirroring the same window global the snapshot/overlay path reads
+ * (`__STORYSTICK_CODE_VERSION__`). Returns `undefined` when unset so
+ * the route-rendered payload omits the optional field rather than
+ * sending an empty string the validator would reject.
+ */
+function readCodeVersion() {
+    if (typeof window === 'undefined')
+        return undefined;
+    const v = window
+        .__STORYSTICK_CODE_VERSION__;
+    return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+export function activate(config) {
+    if (typeof window === 'undefined') {
+        return () => {
+            // No-op cleanup when there is no DOM (SSR).
+        };
+    }
+    const standalone = readStandalonePreviewSessionId(config.projectId) === config.sessionId && config.standaloneCapability === true;
+    if (window.parent === window && !standalone) {
+        return () => {
+            // No-op cleanup when not embedded — postMessage would loop.
+        };
+    }
+    if (standalone && activeStandaloneOverlayCleanup === null) {
+        activeStandaloneOverlayCleanup = startStandaloneOverlayController({
+            sessionId: config.sessionId,
+        });
+    }
+    if (!standalone && activeReporter === null) {
+        // ADR-129 — atomic slice/field snapshot reporting.
+        // The route hash is cached per href to avoid recomputing SHA-256 on
+        // every observer-driven publish.
+        let cachedRouteHash = null;
+        activeReporter = startSnapshotReporter({
+            routeHashRef: () => {
+                if (typeof window === 'undefined')
+                    return null;
+                const href = window.location.href;
+                if (cachedRouteHash !== null && cachedRouteHash.href === href) {
+                    return cachedRouteHash.hash;
+                }
+                // Compute lazily on the next microtask ; first publish under
+                // a brand-new URL will see null (no overlay) until the SHA
+                // resolves, then subsequent ones hit the cache.
+                void computeRouteHash(href).then((hash) => {
+                    cachedRouteHash = { href, hash };
+                    // Wake the reporter once routeHash settles so Studio receives
+                    // the scoped snapshot without waiting for another mutation.
+                    activeReporter?.kick('route-hash-ready');
+                });
+                return null;
+            },
+            routeUrlRef: () => typeof window !== 'undefined' ? window.location.href : null,
+        });
+    }
+    // ADR-119 D2/D3 — Form-preview viewport-contract reporter. Same
+    // refcount + iframe-gate as the siblings: every framework SDK gets
+    // the `data-storystick-form-preview` contract + height ACK for free.
+    if (!standalone && activeFormContractReporter === null) {
+        activeFormContractReporter = startFormContractReporter();
+    }
+    activeRefCount += 1;
+    // The postMessage channel is a secret-free control plane. Browser grants are
+    // acquired independently by runtime/store through the same-origin token route.
+    let controlCleanup = null;
+    let aborted = false;
+    if (!standalone && config.projectId) {
+        const projectId = config.projectId;
+        const parentOriginLock = config.parentOrigin ?? null;
+        let teardownEditInteractionGuard = null;
+        let teardownMomentaryNavigateKeyRelay = null;
+        const navigations = new Map();
+        let pendingNavigate = null;
+        let nativeNavigation = null;
+        let lastNavigateDispatch = null;
+        /**
+         * Emit a `storystick.preview.location` envelope to the parent
+         * Studio. Strips `_ss_session`, `_ss_variant`, and `_ss_release` from the search
+         * before sending (preview-channel internals, not customer-app
+         * query state). Defensive length-cap pre-truncation via slice —
+         * Studio also validates, this is belt-and-braces.
+         */
+        function emitLocation(pathname, search, hash, commandId) {
+            if (parentOriginLock === null)
+                return;
+            const sanitizedSearch = stripStorystickPreviewParams(search);
+            const envelope = {
+                namespace: PREVIEW_NAMESPACE,
+                version: PREVIEW_PROTOCOL_VERSION,
+                type: 'storystick.preview.location',
+                sessionId: config.sessionId,
+                projectId,
+                requestId: createPreviewRequestId(),
+                nonce: createPreviewRequestId(),
+                sentAt: Date.now(),
+                payload: {
+                    pathname: pathname.slice(0, LOCATION_PATHNAME_MAX),
+                    search: sanitizedSearch.slice(0, LOCATION_SEARCH_MAX),
+                    hash: hash.slice(0, LOCATION_HASH_MAX),
+                    ...(commandId !== undefined && { commandId }),
+                },
+            };
+            window.parent.postMessage(envelope, parentOriginLock);
+        }
+        function emitNavigationStart(payload) {
+            if (parentOriginLock === null)
+                return;
+            const envelope = {
+                namespace: PREVIEW_NAMESPACE,
+                version: PREVIEW_PROTOCOL_VERSION,
+                type: 'storystick.preview.navigation-start',
+                sessionId: config.sessionId,
+                projectId,
+                requestId: createPreviewRequestId(),
+                nonce: createPreviewRequestId(),
+                sentAt: Date.now(),
+                payload,
+            };
+            window.parent.postMessage(envelope, parentOriginLock);
+        }
+        /**
+         * PR-1 — emit a `storystick.preview.route-rendered` ack for a
+         * Studio-commanded navigation that has reached AND painted its
+         * destination. Always carries the matched `commandId` (the caller
+         * only invokes this when a commandId was attached). `aborted` +
+         * `parentOriginLock` guards mirror `emitLocation` so a deferred
+         * emit after teardown is a silent no-op.
+         */
+        function emitRouteRendered(commandId, presentation) {
+            if (aborted)
+                return;
+            if (lastNavigateDispatch?.commandId === commandId)
+                lastNavigateDispatch.rendered = true;
+            if (parentOriginLock === null)
+                return;
+            // codeVersion is optional telemetry. If the customer page set a
+            // pathologically long `__STORYSTICK_CODE_VERSION__`, including it
+            // would push the payload past the Studio validator's bound and
+            // DROP the whole envelope — losing the load-bearing commandId ack.
+            // Omit it instead so the confirmation signal always survives
+            // (codex PR-1 review §P2).
+            const codeVersionRaw = readCodeVersion();
+            const codeVersion = codeVersionRaw !== undefined &&
+                codeVersionRaw.length <= ROUTE_RENDERED_CODE_VERSION_MAX
+                ? codeVersionRaw
+                : undefined;
+            const envelope = {
+                namespace: PREVIEW_NAMESPACE,
+                version: PREVIEW_PROTOCOL_VERSION,
+                type: 'storystick.preview.route-rendered',
+                sessionId: config.sessionId,
+                projectId,
+                requestId: createPreviewRequestId(),
+                nonce: createPreviewRequestId(),
+                sentAt: Date.now(),
+                payload: {
+                    commandId,
+                    ...(presentation ? { presentation } : {}),
+                    ...(codeVersion !== undefined && { codeVersion }),
+                },
+            };
+            window.parent.postMessage(envelope, parentOriginLock);
+        }
+        /**
+         * Defer the route-rendered ack until after the browser has painted
+         * the committed route. Uses a DOUBLE rAF: the second callback runs
+         * after the paint of the frame the first callback observed, so the
+         * ack is post-paint REGARDLESS of how the adapter delivered the
+         * transition — from inside its own rAF (Next App Router), from a
+         * router event (Pages Router `routeChangeComplete`), or
+         * synchronously during a commit (a future adapter). A single rAF is
+         * post-paint ONLY when the transition was itself delivered from a
+         * prior rAF, so it could clear the stale mask pre-paint on the other
+         * delivery paths (codex PR-1 review §P1). SSR / jsdom-without-rAF
+         * emits synchronously so tests stay deterministic.
+         */
+        function scheduleRouteRenderedAck(commandId, presentation) {
+            if (parentOriginLock === null)
+                return;
+            if (typeof window === 'undefined' ||
+                typeof window.requestAnimationFrame !== 'function') {
+                emitRouteRendered(commandId, presentation);
+                return;
+            }
+            const startedAt = previewPerfNow(window);
+            window.requestAnimationFrame(() => {
+                window.requestAnimationFrame(() => {
+                    if (!aborted)
+                        recordPreviewPerfMeasure(window, 'preview.navigate.paintAck', startedAt, { hasPresentation: presentation !== undefined });
+                    emitRouteRendered(commandId, presentation);
+                });
+            });
+        }
+        function emitOverlayReady(payload) {
+            if (parentOriginLock === null)
+                return;
+            const envelope = {
+                namespace: PREVIEW_NAMESPACE,
+                version: PREVIEW_PROTOCOL_VERSION,
+                type: 'storystick.preview.overlay-ready',
+                sessionId: config.sessionId,
+                projectId,
+                requestId: createPreviewRequestId(),
+                nonce: createPreviewRequestId(),
+                sentAt: Date.now(),
+                payload,
+            };
+            window.parent.postMessage(envelope, parentOriginLock);
+        }
+        function emitOverlayClick(payload) {
+            if (parentOriginLock === null)
+                return;
+            const envelope = {
+                namespace: PREVIEW_NAMESPACE,
+                version: PREVIEW_PROTOCOL_VERSION,
+                type: 'storystick.preview.overlay-click',
+                sessionId: config.sessionId,
+                projectId,
+                requestId: createPreviewRequestId(),
+                nonce: createPreviewRequestId(),
+                sentAt: Date.now(),
+                payload,
+            };
+            window.parent.postMessage(envelope, parentOriginLock);
+        }
+        function emitIframeInteraction(payload) {
+            if (parentOriginLock === null)
+                return;
+            const envelope = {
+                namespace: PREVIEW_NAMESPACE,
+                version: PREVIEW_PROTOCOL_VERSION,
+                type: 'storystick.preview.iframe-interaction',
+                sessionId: config.sessionId,
+                projectId,
+                requestId: createPreviewRequestId(),
+                nonce: createPreviewRequestId(),
+                sentAt: Date.now(),
+                payload,
+            };
+            window.parent.postMessage(envelope, parentOriginLock);
+        }
+        let lastRouterLocation = {
+            pathname: window.location.pathname,
+            search: stripStorystickPreviewParams(window.location.search),
+            hash: window.location.hash,
+        };
+        function onRouterTransition(transition) {
+            const committed = {
+                pathname: transition.pathname,
+                search: stripStorystickPreviewParams(transition.search),
+                hash: transition.hash,
+            };
+            if (transition.commandId !== undefined) {
+                navigations.delete(transition.commandId);
+                if (pendingNavigate?.commandId === transition.commandId)
+                    pendingNavigate = null;
+                lastRouterLocation = committed;
+                emitLocation(transition.pathname, transition.search, transition.hash, transition.commandId);
+                scheduleRouteRenderedAck(transition.commandId, transition.presentation);
+                return;
+            }
+            const matchesNative = nativeNavigation !== null &&
+                (nativeNavigation.pathname === committed.pathname || nativeNavigation.pathname === transition.browserPathname) &&
+                nativeNavigation.search === committed.search &&
+                nativeNavigation.hash === committed.hash;
+            const matches = (command) => command.expectedPathname === committed.pathname &&
+                stripStorystickPreviewParams(command.expectedSearch) === committed.search &&
+                command.expectedHash === committed.hash;
+            const matched = matchesNative ? undefined :
+                [...navigations.values()].reverse().find(matches);
+            const command = matchesNative ? null : matched ?? pendingNavigate;
+            const commandId = command?.commandId;
+            if (matchesNative) {
+                // Browser gestures include a framework basePath; adapter commits use
+                // customer route coordinates. Correlate the normalized intent too.
+                if (nativeNavigation.pathname !== committed.pathname) {
+                    emitNavigationStart({ ...committed, trigger: nativeNavigation.trigger });
+                }
+                nativeNavigation = null;
+                pendingNavigate = null;
+            }
+            else if (matched?.commandId === pendingNavigate?.commandId) {
+                pendingNavigate = null;
+            }
+            if (matched !== undefined)
+                navigations.delete(matched.commandId);
+            const changed = committed.pathname !== lastRouterLocation.pathname ||
+                committed.search !== lastRouterLocation.search ||
+                committed.hash !== lastRouterLocation.hash;
+            lastRouterLocation = committed;
+            if (changed && commandId === undefined && !matchesNative) {
+                emitNavigationStart({ ...committed, trigger: 'router-transition' });
+            }
+            emitLocation(transition.pathname, transition.search, transition.hash, commandId);
+            // A redirect retains provenance but does not confirm the requested URL.
+            if (matched !== undefined)
+                scheduleRouteRenderedAck(matched.commandId);
+        }
+        setRouterSubscriber(onRouterTransition);
+        const onBrowseLinkClick = (event) => {
+            if (event.defaultPrevented)
+                return;
+            const target = getAnchorFromPreviewClickEvent(event, window);
+            if (target === null)
+                return;
+            if (getInteractionMode() !== 'browse')
+                return;
+            normalizeMomentaryNavigateLinkClick(event, target, window);
+            const navigationStart = navigationStartPayloadFromBrowseClick(event, target, window);
+            if (navigationStart !== null) {
+                nativeNavigation = navigationStart;
+                pendingNavigate = null;
+                emitNavigationStart(navigationStart);
+            }
+        };
+        window.document.addEventListener('click', onBrowseLinkClick, true);
+        const onHistoryNavigation = () => {
+            nativeNavigation = {
+                pathname: window.location.pathname,
+                search: stripStorystickPreviewParams(window.location.search),
+                hash: window.location.hash,
+                trigger: 'router-transition',
+            };
+            pendingNavigate = null;
+            emitNavigationStart(nativeNavigation);
+            // History already committed the browser URL. A restored React tree may
+            // not rerender, so no adapter callback is guaranteed to report it again.
+            emitLocation(nativeNavigation.pathname, nativeNavigation.search, nativeNavigation.hash, undefined);
+        };
+        window.addEventListener('popstate', onHistoryNavigation);
+        const onPageShow = (event) => {
+            if (event.persisted)
+                onHistoryNavigation();
+        };
+        window.addEventListener('pageshow', onPageShow);
+        teardownEditInteractionGuard = installPreviewEditInteractionGuard(window, {
+            onInteraction: emitIframeInteraction,
+        });
+        const teardownWorkspaceShortcuts = installPreviewWorkspaceShortcuts(window, () => {
+            const state = previewRuntime.getState();
+            return state.previewEnded ? null : state.identity;
+        }, undefined, previewRuntime.subscribeIdentity);
+        teardownMomentaryNavigateKeyRelay = installMomentaryNavigateKeyRelay(window, {
+            getTargetOrigin: () => parentOriginLock,
+        });
+        let initialHistoryNavigation = false;
+        if (!initialNavigationObserved && parentOriginLock !== null) {
+            initialNavigationObserved = true;
+            const navigation = window.performance.getEntriesByType?.('navigation')?.[0];
+            if (navigation?.type === 'back_forward') {
+                try {
+                    const loaded = new URL(navigation.name);
+                    // A late activation after SPA navigation cannot lend an older
+                    // document's history proof to its new address. Internal selectors
+                    // and the current fragment do not change the loaded document.
+                    initialHistoryNavigation = loaded.origin === window.location.origin &&
+                        loaded.pathname === window.location.pathname &&
+                        stripStorystickPreviewParams(loaded.search) === stripStorystickPreviewParams(window.location.search);
+                }
+                catch { /* An unavailable browser proof leaves boot observational. */ }
+            }
+        }
+        if (initialHistoryNavigation)
+            onHistoryNavigation();
+        else
+            emitLocation(window.location.pathname, window.location.search.replace(/^\?/, ''), window.location.hash, undefined);
+        // Listen for cross-frame `navigate` messages. The validator
+        // rejects pre-lock messages outright (codex Lane D round 1 P1
+        // fix) so a same-host script with a valid envelope shape can't
+        // drive `history.pushState` before the legitimate Studio
+        // handshake finishes.
+        //
+        // ADR-108 — same listener also routes `interaction-mode` envelopes
+        // (Studio→iframe click-routing flag).
+        const onMessage = (event) => {
+            const base = validatePreviewEnvelope(event.data);
+            if (base.ok &&
+                base.message.type === 'storystick.preview.session-broadcast' &&
+                parentOriginLock !== null &&
+                event.origin === parentOriginLock &&
+                base.message.sessionId === config.sessionId &&
+                base.message.projectId === projectId) {
+                config.onSessionBroadcast?.();
+                return;
+            }
+            if (window.__storystickPreviewOverlayMapOwner !== 'boot') {
+                const overlayMap = validateOverlayMap(event.data, event.origin, config.sessionId, projectId, parentOriginLock);
+                if (overlayMap.ok) {
+                    const result = applyPreviewOverlayMap(overlayMap.envelope.payload, window, {
+                        onClick: emitOverlayClick,
+                    });
+                    emitOverlayReady({
+                        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;
+                }
+                const overlayClear = validateOverlayClear(event.data, event.origin, config.sessionId, projectId, parentOriginLock);
+                if (overlayClear.ok) {
+                    clearPreviewOverlayPaint();
+                    return;
+                }
+            }
+            // ADR-108 D2 — interaction-mode envelope routed first because
+            // it has its own discriminator + parentOrigin lock guard. The
+            // `validateNavigate` path below short-circuits on the wrong
+            // type so this ordering doesn't conflict.
+            if (base.ok &&
+                base.message.type === 'storystick.preview.interaction-mode') {
+                if (parentOriginLock === null)
+                    return;
+                if (event.origin !== parentOriginLock)
+                    return;
+                if (base.message.sessionId !== config.sessionId)
+                    return;
+                if (base.message.projectId !== projectId)
+                    return;
+                setInteractionMode(base.message.payload.mode);
+                return;
+            }
+            if (base.ok && base.message.type === 'storystick.preview.reload') {
+                if (parentOriginLock === null)
+                    return;
+                if (event.origin !== parentOriginLock)
+                    return;
+                if (base.message.sessionId !== config.sessionId)
+                    return;
+                if (base.message.projectId !== projectId)
+                    return;
+                const handler = getReloadHandler();
+                handler(base.message.payload.mode, {
+                    commandId: base.message.payload.commandId,
+                });
+                // C3 — a soft reload is commonly implemented by framework
+                // adapters as `router.refresh()`. The displayed URL does not
+                // change in that case, so the router-location subscriber has no
+                // transition to report. Studio deliberately clears its observed
+                // renderer state before dispatching reload; explicitly re-observe
+                // the current route so a later overlay-ready ACK can be matched to
+                // the unchanged displayed epoch instead of being rejected as
+                // route-drift. This is route evidence only — paint readiness still
+                // requires the generation-scoped overlay-ready ACK.
+                if (base.message.payload.mode === 'soft') {
+                    emitLocation(window.location.pathname, window.location.search.replace(/^\?/, ''), window.location.hash, undefined);
+                }
+                return;
+            }
+            const check = validateNavigate(event.data, event.origin, config.sessionId, projectId, parentOriginLock);
+            if (!check.ok)
+                return;
+            // ADR-108 D3 — capture the expected-destination tuple BEFORE
+            // invoking the framework adapter's handler so the next
+            // observed router transition can match-and-attach. The
+            // navigate envelope's `pathname` may include `?...#...`
+            // (validator allows /path?q=1#h); split it into the three
+            // parts so the subscriber-reported tuple can be compared
+            // directly.
+            const rawPath = check.envelope.payload.pathname;
+            const hashIdx = rawPath.indexOf('#');
+            const hash = hashIdx >= 0 ? rawPath.slice(hashIdx) : '';
+            const pathWithQuery = hashIdx >= 0 ? rawPath.slice(0, hashIdx) : rawPath;
+            const queryIdx = pathWithQuery.indexOf('?');
+            const expectedPathname = queryIdx >= 0 ? pathWithQuery.slice(0, queryIdx) : pathWithQuery;
+            const expectedSearch = queryIdx >= 0 ? pathWithQuery.slice(queryIdx + 1) : '';
+            const handler = getNavigateHandler();
+            if (lastNavigateDispatch?.commandId === check.envelope.payload.commandId &&
+                lastNavigateDispatch.handler === handler) {
+                // A lost ACK may cause an already-rendered command to be delivered again.
+                // Re-ack it without re-arming a navigation that could capture a future Browse.
+                if (lastNavigateDispatch.rendered && lastRouterLocation.pathname === expectedPathname &&
+                    lastRouterLocation.search === stripStorystickPreviewParams(expectedSearch) &&
+                    lastRouterLocation.hash === hash) {
+                    emitLocation(lastRouterLocation.pathname, lastRouterLocation.search, hash, lastNavigateDispatch.commandId);
+                    scheduleRouteRenderedAck(lastNavigateDispatch.commandId);
+                }
+                return;
+            }
+            pendingNavigate = {
+                commandId: check.envelope.payload.commandId,
+                expectedPathname,
+                expectedSearch,
+                expectedHash: hash,
+            };
+            navigations.set(pendingNavigate.commandId, pendingNavigate);
+            while (navigations.size > 64)
+                navigations.delete(navigations.keys().next().value);
+            nativeNavigation = null;
+            // Studio retries until route-rendered because postMessage acceptance is
+            // not delivery proof. Do not restart a slow framework navigation for the
+            // same adapter; do retry when no adapter was ready yet or HMR installed a
+            // new handler function for the still-pending command.
+            if (!hasNavigateHandler())
+                return;
+            lastNavigateDispatch = {
+                commandId: check.envelope.payload.commandId,
+                handler,
+                rendered: false,
+            };
+            recordPreviewPerfMetric(window, { name: 'preview.navigate.received', detail: {
+                    refresh: check.envelope.payload.refresh === true,
+                    contextCommand: check.envelope.payload.contextCommand !== undefined,
+                } });
+            // ADR-111 — forward the optional `refresh` flag so App Router
+            // adapters can invalidate the client Router Cache on layout-
+            // preview-state changes. Validator guarantees `refresh` is a
+            // boolean when present; we coerce to a strict boolean here so
+            // adapters never see `undefined`-as-truthy.
+            const refresh = check.envelope.payload.refresh === true;
+            handler(check.envelope.payload.pathname, {
+                refresh,
+                scope: check.envelope.payload.scope,
+                commandId: check.envelope.payload.commandId,
+                ...(check.envelope.payload.contextCommand ? {
+                    contextCommand: check.envelope.payload.contextCommand,
+                } : {}),
+            });
+        };
+        window.addEventListener('message', onMessage);
+        controlCleanup = () => {
+            aborted = true;
+            window.removeEventListener('message', onMessage);
+            window.document.removeEventListener('click', onBrowseLinkClick, true);
+            window.removeEventListener('popstate', onHistoryNavigation);
+            window.removeEventListener('pageshow', onPageShow);
+            teardownWorkspaceShortcuts();
+            teardownMomentaryNavigateKeyRelay?.();
+            teardownMomentaryNavigateKeyRelay = null;
+            teardownEditInteractionGuard?.();
+            teardownEditInteractionGuard = null;
+            // ADR-108 — clear router subscriber so StrictMode remount or
+            // future activate() doesn't see a stale handler from the
+            // teardown lane.
+            setRouterSubscriber(null);
+        };
+    }
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        if (controlCleanup !== null) {
+            controlCleanup();
+            controlCleanup = null;
+        }
+        activeRefCount -= 1;
+        if (activeRefCount <= 0) {
+            activeRefCount = 0;
+            activeReporter?.stop();
+            activeReporter = null;
+            activeFormContractReporter?.stop();
+            activeFormContractReporter = null;
+            activeStandaloneOverlayCleanup?.();
+            activeStandaloneOverlayCleanup = null;
+            clearPreviewOverlayPaint();
+        }
+    };
+}
+/**
+ * Test-only hook to drop the singleton between cases. Vitest modules
+ * are isolated per file, but a single file with multiple `activate`
+ * calls would share state without this reset.
+ */
+export function _resetActivateForTests() {
+    activeReporter?.stop();
+    activeReporter = null;
+    activeFormContractReporter?.stop();
+    activeFormContractReporter = null;
+    activeStandaloneOverlayCleanup?.();
+    activeStandaloneOverlayCleanup = null;
+    clearPreviewOverlayPaint();
+    activeRefCount = 0;
+    initialNavigationObserved = false;
+}
+/**
+ * Emit a `PreviewNavMessage` to the parent Studio. No-op when not
+ * embedded (top-level window or SSR) — same guard as `activate`.
+ *
+ * Origin :
+ *   - When `targetOrigin` is omitted, defaults to `window.location.origin`.
+ *     Per ADR-041 the studio + preview share a cookie domain, which means
+ *     they share an origin in practice — same-origin posting works.
+ *   - Pass an explicit `targetOrigin` if a future deployment puts the
+ *     preview on a different origin (cross-domain) ; the studio listener
+ *     would then need a documented allowlist on its side.
+ */
+export function postNavigateToParent(msg, targetOrigin) {
+    if (typeof window === 'undefined')
+        return;
+    if (window.parent === window)
+        return;
+    const origin = targetOrigin ?? window.location.origin;
+    window.parent.postMessage(msg, origin);
+}
+// The Proxy tracking surface is implemented in `runtime/field-proxy.ts`
+// and re-exported near the top of this module.