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

package/dist/preview-nav.js

@@ -0,0 +1,523 @@
+'use client';
+import { createPreviewRequestId } from '@storystick/preview/runtime/request-id';
+import { previewRuntime } from '@storystick/preview/runtime/store';
+import { previewPerfNow, recordPreviewPerfMeasure, recordPreviewPerfMetric } from '@storystick/preview/runtime/perf-metrics';
+import { confirmPreviewRender, resetPreviewRenderFailure } from './preview-render-recovery.js';
+import { readPreviewRenderReceipt } from '@storystick/preview/framework/render-receipt';
+/**
+ * Next.js preview navigation adapter (ADR-087 Lane D').
+ *
+ * Wires the framework-agnostic `setNavigateHandler` exported by
+ * `@storystick/preview` (Lane D contract) to Next's router so a
+ * Studio-issued `storystick.preview.navigate` postMessage drives a
+ * client-side `router.replace(pathname)` inside the preview iframe.
+ *
+ * **Honest claim per ADR §3.2 / §7** : this is **best-effort CSR
+ * navigation**, NOT *"framework-agnostic navigation"*.
+ *
+ *   - **App Router (RSC)** : `router.replace(pathname)` triggers a CSR
+ *     transition. The preview selector is preserved and the destination
+ *     Server Components resolve their short-lived access token from the
+ *     durable HttpOnly PreviewGrant.
+ *   - **Pages Router** : `router.replace(pathname)` performs the usual
+ *     client-side transition. `getServerSideProps` re-runs and
+ *     preserves the Storystick preview selector in the destination URL.
+ *
+ * **Why no fully-automatic router auto-detect** : the brief's first
+ * draft tried calling `useRouter` from BOTH `next/navigation` and
+ * `next/router` unconditionally and picking the first non-null
+ * result, but Next's hooks throw outside their respective contexts
+ * (codex round 1 P0) — `next/navigation::useRouter` throws in Pages
+ * Router (Next 15 invariant E238), and `next/router::useRouter`
+ * throws in App Router. Detecting "which router context am I in?"
+ * without internal Next APIs is impossible inside a single hook.
+ *
+ * The robust fix : we use **`next/compat/router::useRouter`**, the
+ * Next-officially-supported universal hook that returns the Pages
+ * `NextRouter` instance when mounted inside Pages Router, returns
+ * `null` otherwise (App Router or no-router env), and **never
+ * throws**. App Router consumers pass their `useRouter()` instance
+ * (from `next/navigation`) explicitly as the optional `appRouter`
+ * argument. The hook prefers the explicit App Router argument when
+ * provided, otherwise falls back to the compat-detected Pages
+ * router.
+ *
+ * Usage — App Router :
+ *
+ * ```tsx
+ * 'use client'
+ * import { useRouter } from 'next/navigation'
+ * import { StorystickQueryProvider } from '@storystick/next'
+ * import { useStorystickPreviewNavigation } from '@storystick/next/preview-nav'
+ *
+ * export function Providers({ children }: { children: React.ReactNode }) {
+ *   const router = useRouter()
+ *   useStorystickPreviewNavigation(router)
+ *   return (
+ *     <StorystickQueryProvider projectId="..." publishableKey="...">
+ *       {children}
+ *     </StorystickQueryProvider>
+ *   )
+ * }
+ * ```
+ *
+ * Usage — Pages Router (no argument needed) :
+ *
+ * ```tsx
+ * import { StorystickQueryProvider } from '@storystick/next'
+ * import { useStorystickPreviewNavigation } from '@storystick/next/preview-nav'
+ *
+ * export function Providers({ children }: { children: React.ReactNode }) {
+ *   useStorystickPreviewNavigation()
+ *   return (
+ *     <StorystickQueryProvider projectId="..." publishableKey="...">
+ *       {children}
+ *     </StorystickQueryProvider>
+ *   )
+ * }
+ * ```
+ *
+ * **Why a separate subpath** : `@storystick/next` (root) is imported
+ * by Server Components for `fetchDocument` / `fetchQuery`. The
+ * preview hook drags `next/compat/router` and React client-only
+ * primitives, which would pollute the server module graph (codex
+ * Lane D' round 2 P1 fix). Keeping the hook at
+ * `@storystick/next/preview-nav` keeps the server entry pure.
+ *
+ * **Sentinel guard** : the hook is a no-op when not in preview mode.
+ * Preview mode = embedded iframe (`window.parent !== window`) AND a
+ * `_ss_session` URL parameter — same heuristic as `detectPreviewMode`
+ * in `@storystick/react`'s provider. Outside preview mode the hook
+ * never registers a handler and `setNavigateHandler` keeps its
+ * default no-op.
+ *
+ * **Cleanup** : on unmount the hook restores a surviving layout adapter,
+ * or the no-op default when none remains. External overrides stay intact.
+ *
+ * **Hook vs imperative** : `useRouter` from Next can ONLY be called
+ * inside React components, which forces the public surface to be a
+ * hook. Consumers place this hook in their root client component
+ * (typically the same component that renders `<StorystickQueryProvider>`).
+ */
+import { useEffect, useLayoutEffect, useRef, useState, useTransition } from 'react';
+import { useRouter as useCompatRouter } from 'next/compat/router';
+// ADR-116 FU2 — synchronous post-render commit avoids an HMR re-mount
+// race where a residual `activate()` listener delivers a navigate
+// envelope between the new mount's render and a passive `useEffect`
+// commit, dispatching to the no-op handler.
+const useIsoLayoutEffect = typeof window === 'undefined' ? useEffect : useLayoutEffect;
+import { setNavigateHandler, getNavigateHandler, setReloadHandler, getReloadHandler, } from '@storystick/preview/nav-handler';
+import { notifyRouterTransition } from '@storystick/preview/router-subscriber';
+import { isPreviewModeLatched, readPreviewSessionIdForNavigation, readPreviewVariantIdForNavigation, readPreviewReleaseIdForNavigation, setLatchedPreviewScope, } from './preview-mode-latch.js';
+import { beginPreviewNavigation, cancelPreviewRefreshCoordination, observePreviewNavigationCommit, } from './preview-refresh-coordinator.js';
+import { PREVIEW_SESSION_QUERY_PARAM, writePreviewScopeToSearchParams, } from '@storystick/preview/identity';
+// A nested error fallback may coexist with the layout adapter. When it leaves,
+// return control to the latest still-mounted adapter, never to a stale closure.
+const navigationAdapters = new Set();
+/**
+ * ADR-108 D6.bis — strip a configured basePath from a browser-form
+ * pathname. Pure function exported for tests.
+ *
+ *   stripBasePath('/admin', '/admin/page')      → '/page'
+ *   stripBasePath('/admin/', '/admin/page')     → '/page'  (trailing slash normalised)
+ *   stripBasePath('/admin', '/admin')           → '/'      (exact match → root)
+ *   stripBasePath('/admin', '/administrator')   → '/administrator'  (segment-boundary)
+ *   stripBasePath('', '/page')                  → '/page'  (no-op)
+ */
+export function stripBasePath(basePath, pathname) {
+    if (basePath === '' || basePath === '/')
+        return pathname;
+    // Normalise: ensure leading slash, drop trailing slash.
+    let bp = basePath;
+    if (!bp.startsWith('/'))
+        bp = '/' + bp;
+    if (bp.endsWith('/'))
+        bp = bp.replace(/\/+$/, '');
+    if (bp === '')
+        return pathname;
+    if (!pathname.startsWith(bp))
+        return pathname;
+    const rest = pathname.slice(bp.length);
+    // Path-segment boundary: rest must be empty (exact match) OR start
+    // with `/` (next segment). `/administrator` does NOT match
+    // basePath `/admin` because rest would be `istrator` (no leading
+    // slash) — bail out.
+    if (rest === '')
+        return '/';
+    if (!rest.startsWith('/'))
+        return pathname;
+    return rest;
+}
+/**
+ * Preserve the `_ss_session` URL parameter when navigating inside
+ * the preview iframe. Studio's `storystick.preview.navigate`
+ * envelope only carries the destination `pathname` ; if we push it
+ * raw, the current `?_ss_session=...` marker is dropped and
+ * `<StorystickQueryProvider>`'s `detectPreviewMode()` re-evaluates to
+ * false on the next render, tearing down the PreviewGrant-backed
+ * Convex preview subscription mid-session (codex Lane D' round 4
+ * P1).
+ *
+ * Source precedence (ADR-113 follow-up — codex R4 finding #2):
+ *   1. **Destination's own `_ss_session`**: if Studio explicitly put
+ *      a session id in the destination path, respect it and do not
+ *      overwrite.
+ *   2. **Latched preview session id**: the boot-time value captured
+ *      by `isPreviewModeLatched()`. Studio-authoritative, stable
+ *      across customer intra-iframe nav that strips the URL param.
+ *   3. **Live `window.location.search`**: fallback only. Useful when
+ *      the latch is empty (e.g. an old SDK build that didn't track
+ *      sessionId AND the URL never lost it) — the opportunistic
+ *      backfill in `isPreviewModeLatched()` normally upgrades the
+ *      latch before we get here.
+ *
+ * The exact variant/release selector is carried with the same destination so
+ * the request-owned read scope survives customer navigation. A trusted Studio
+ * command replaces the latched scope atomically; living clears both selectors.
+ *
+ * The pathname is already validated upstream as a same-origin
+ * absolute path (starts with `/`, not `//`) by
+ * `validatePreviewEnvelope`.
+ */
+function preservePreviewSession(pathname, explicitScope) {
+    if (typeof window === 'undefined')
+        return pathname;
+    // ADR-116 PR5 — preview identity facade owns the precedence chain:
+    // identity layer first, latch fallback second, live URL bootstrap
+    // last. Keep adapter code away from direct URL/storage/latch reads.
+    const currentSession = readPreviewSessionIdForNavigation();
+    if (currentSession === null)
+        return pathname;
+    const currentVariant = readPreviewVariantIdForNavigation();
+    const currentRelease = readPreviewReleaseIdForNavigation();
+    // Split the destination on `?` to merge query strings cleanly.
+    // The pathname may already include a query (e.g. `/about?foo=bar`)
+    // and/or a hash (e.g. `/about#section`). We preserve those.
+    const hashIndex = pathname.indexOf('#');
+    const hash = hashIndex >= 0 ? pathname.slice(hashIndex) : '';
+    const pathWithQuery = hashIndex >= 0 ? pathname.slice(0, hashIndex) : pathname;
+    const queryIndex = pathWithQuery.indexOf('?');
+    const path = queryIndex >= 0 ? pathWithQuery.slice(0, queryIndex) : pathWithQuery;
+    const existingQuery = queryIndex >= 0 ? pathWithQuery.slice(queryIndex + 1) : '';
+    const params = new URLSearchParams(existingQuery);
+    // If the destination already specifies `_ss_session`, respect it.
+    if (!params.has(PREVIEW_SESSION_QUERY_PARAM)) {
+        params.set(PREVIEW_SESSION_QUERY_PARAM, currentSession);
+    }
+    if (explicitScope !== undefined) {
+        // Studio navigation is authoritative. In particular, living scope must
+        // remove a variant/release left in the current tab URL instead of
+        // inheriting it accidentally.
+        writePreviewScopeToSearchParams(params, explicitScope);
+    }
+    else if (currentRelease !== null) {
+        writePreviewScopeToSearchParams(params, {
+            kind: 'release',
+            releaseId: currentRelease,
+        });
+    }
+    else if (currentVariant !== null) {
+        writePreviewScopeToSearchParams(params, {
+            kind: 'variant',
+            variantId: currentVariant,
+        });
+    }
+    const merged = params.toString();
+    return merged.length > 0 ? `${path}?${merged}${hash}` : `${path}${hash}`;
+}
+/**
+ * Wire `@storystick/preview`'s navigate handler to a Next router.
+ *
+ * @param appRouter — App Router instance from `next/navigation`'s
+ *   `useRouter()`. App Router consumers pass it explicitly (see
+ *   module JSDoc). Optional — when omitted, the hook falls back to
+ *   the Pages Router instance auto-detected via `next/compat/router`.
+ *
+ * No-op outside preview mode. On unmount, restores a surviving adapter or
+ * the default no-op handler, leaving no stale registration behind.
+ */
+export function useStorystickPreviewNavigation(appRouter, options) {
+    const [refreshPending, startRefresh] = useTransition();
+    const [refreshCommand, setRefreshCommand] = useState(null);
+    const navigationRevisionRef = useRef(0);
+    useEffect(() => {
+        if (refreshPending || refreshCommand === null || typeof window === 'undefined')
+            return;
+        const target = new URL(refreshCommand.destination, window.location.href);
+        const basePath = options?.basePath ?? '';
+        const receipt = readPreviewRenderReceipt();
+        recordPreviewPerfMeasure(window, 'next.navigate.refreshSettled', refreshCommand.startedAt, {
+            freshReceipt: receipt !== null && receipt.renderId !== refreshCommand.previousRenderId,
+        });
+        if (target.pathname === stripBasePath(basePath, window.location.pathname) && target.search === window.location.search && target.hash === window.location.hash && confirmPreviewRender()) {
+            // App Router location hooks do not fire when only the draft identity
+            // changes. React's transition settlement supplies that render boundary.
+            notifyRouterTransition({
+                pathname: target.pathname,
+                search: target.search.replace(/^\?/, ''), hash: target.hash,
+                commandId: refreshCommand.commandId,
+                ...(receipt && receipt.renderId !== refreshCommand.previousRenderId
+                    ? { presentation: { ...receipt, pathname: target.pathname } } : {}),
+            });
+        }
+        setRefreshCommand(null);
+    }, [refreshCommand, refreshPending, options?.basePath]);
+    // `next/compat/router::useRouter` is the only Next router hook
+    // that is safe to call unconditionally in BOTH App Router and
+    // Pages Router contexts (it returns `NextRouter | null` and never
+    // throws). The compat hook reads from Pages Router's
+    // `RouterContext`, which is null in App Router → returns null →
+    // we fall through to the explicit `appRouter` argument.
+    const pagesRouter = useCompatRouter();
+    // App Router argument wins when provided AND has a usable
+    // `replace` ; otherwise fall back to the auto-detected Pages
+    // router. If neither is available we leave `setNavigateHandler`
+    // untouched (default no-op).
+    const router = appRouter !== undefined &&
+        appRouter !== null &&
+        typeof appRouter.replace === 'function'
+        ? appRouter
+        : pagesRouter !== null && typeof pagesRouter.replace === 'function'
+            ? pagesRouter
+            : null;
+    useIsoLayoutEffect(() => {
+        // ADR-116 PR8 — register the handler UNCONDITIONALLY (gated only
+        // on `router !== null`). The preview-mode / identity gate moves
+        // INSIDE the handler body so dispatches fire correctly even after
+        // a hard navigation inside the iframe.
+        //
+        // Pre-PR8 the effect bailed at mount when `isPreviewModeLatched()`
+        // returned false. After a hard-nav the new realm boots with the
+        // URL stripped of `_ss_session` AND `globalThis` reset, so the
+        // synchronous latch read returned false. Identity arrived ~50-300ms
+        // later via the resolver's storage carrier / Studio session-broadcast
+        // (ADR-116 D3) but the `useEffect` deps `[router]` did NOT change,
+        // so the effect never re-ran → handler never registered → Studio's
+        // navigate envelopes silently dropped by the default no-op
+        // `getNavigateHandler()`. Forward channel dead post-hard-nav.
+        //
+        // The fix : register unconditionally, gate at dispatch time. The
+        // observable behaviour for non-preview mode is unchanged (handler
+        // bails immediately) but the post-recovery dispatch flows because
+        // the handler is already wired by the time identity arrives.
+        //
+        // ADR-113 latch seed (preserved side effect) — call
+        // `isPreviewModeLatched()` once at mount, ignoring the return
+        // value. The function's first invocation populates
+        // `globalThis.__storystick_preview_mode_latched__` from the boot
+        // URL state. Without this eager seed, the cache stays undefined
+        // until a customer intra-iframe nav (which can strip `_ss_session`
+        // from the URL) AND the first dispatch — which would then capture
+        // the post-strip URL state and lose the original sessionId. The
+        // dispatch-time `isPreviewModeLatched()` inside the handler reads
+        // the now-cached value, not the live URL.
+        isPreviewModeLatched();
+        if (router === null)
+            return;
+        // Hold the handler we register so the cleanup can verify that the
+        // currently-installed handler is still ours before clearing it.
+        // Without this guard, two adapters mounted concurrently would
+        // race : the second `setNavigateHandler` wins, but unmounting the
+        // FIRST adapter would then clear the second one's handler (codex
+        // Lane D' round 3 P2 fix).
+        const ourHandler = async (pathname, navigateOptions) => {
+            // ADR-116 PR8 dispatch-time gate. The handler is registered
+            // unconditionally at mount ; this check ensures we never call
+            // `router.replace()` outside preview mode. After hard-nav
+            // recovery, `isPreviewModeLatched()` reads through to
+            // `previewRuntime.getIdentity()` (PR5 read-through) and returns
+            // true once identity is restored.
+            if (!isPreviewModeLatched())
+                return;
+            // Pathname is already validated as a same-origin absolute
+            // path (starts with `/`, not `//`) by
+            // `validatePreviewEnvelope` in the foundation Lane C — see
+            // `nav-handler.ts` JSDoc. Trust the value here.
+            //
+            // We MUST preserve `_ss_session` across the replace,
+            // otherwise `<StorystickQueryProvider>`'s `detectPreviewMode()`
+            // re-evaluates to false on the next render and tears
+            // down the PreviewGrant-backed Convex preview subscription
+            // (codex Lane D' round 4 P1 fix).
+            //
+            // Studio retains its own history (replace). Explicit standalone selector
+            // gestures request push; both transports use this same framework adapter.
+            const revision = ++navigationRevisionRef.current;
+            let scope = previewRuntime.getState().session?.readContext?.perspective;
+            if (navigateOptions?.contextCommand && navigateOptions.commandId) {
+                const startedAt = previewPerfNow(window);
+                const context = await previewRuntime.changePerspective({
+                    ...navigateOptions.contextCommand, commandId: navigateOptions.commandId,
+                    perspective: navigateOptions.scope,
+                }, preservePreviewSession(`${options?.basePath ?? ''}/api/storystick/preview/context`));
+                recordPreviewPerfMeasure(window, 'next.navigate.context', startedAt, { accepted: context !== null });
+                if (!context || navigationRevisionRef.current !== revision)
+                    return;
+                scope = context.perspective;
+            }
+            const destination = preservePreviewSession(pathname, scope);
+            if (scope !== undefined) {
+                setLatchedPreviewScope(scope);
+                options?.onScopeChange?.(scope);
+            }
+            // ADR-111 still requires a root-layout refresh when Studio changed the
+            // preview target. It must not run concurrently with `replace()`: both
+            // start Flight transitions, and overlapping responses can corrupt the
+            // Next development client. The location adapter settles this intent
+            // after it observes the committed destination. Exact content refreshes
+            // arriving in the meantime are folded into that single post-commit call.
+            const shouldReplace = beginPreviewNavigation({
+                destination,
+                currentLocation: typeof window === 'undefined' ? destination :
+                    `${stripBasePath(options?.basePath ?? '', window.location.pathname)}${window.location.search}${window.location.hash}`,
+                ...(navigateOptions?.refresh === true &&
+                    typeof router.refresh === 'function'
+                    ? {
+                        refresh: () => { router.refresh?.(); },
+                        runRefresh: (refresh) => {
+                            if (navigationRevisionRef.current !== revision)
+                                return;
+                            recordPreviewPerfMetric(window, { name: 'next.navigate.refresh' });
+                            if (navigateOptions.commandId)
+                                setRefreshCommand({
+                                    destination, commandId: navigateOptions.commandId,
+                                    previousRenderId: readPreviewRenderReceipt()?.renderId,
+                                    startedAt: previewPerfNow(window),
+                                });
+                            // Reset and data refresh belong to the same transition.
+                            // Next otherwise keeps same-path errors latched (draft → home).
+                            startRefresh(() => { resetPreviewRenderFailure(); refresh(); });
+                        },
+                    }
+                    : {}),
+            });
+            if (shouldReplace || (navigateOptions?.refresh === true && typeof router.refresh !== 'function')) {
+                recordPreviewPerfMetric(window, { name: 'next.navigate.replace' });
+                // Pages Router has no refresh(). A private query revision forces its
+                // data navigation even for the exact same URL and fragment (which
+                // Next otherwise treats as a hash-only transition without new data).
+                if (navigateOptions?.refresh === true && typeof router.refresh !== 'function' && router === pagesRouter) {
+                    const refreshed = new URL(destination, 'https://preview.invalid');
+                    refreshed.searchParams.set('_ss_refresh', navigateOptions.commandId ?? createPreviewRequestId());
+                    startRefresh(() => {
+                        resetPreviewRenderFailure();
+                        router[navigateOptions?.history === 'push' ? 'push' : 'replace'](`${refreshed.pathname}${refreshed.search}${refreshed.hash}`);
+                    });
+                }
+                else
+                    startRefresh(() => {
+                        resetPreviewRenderFailure();
+                        if (navigateOptions?.history === 'push')
+                            router.push(destination);
+                        else
+                            router.replace(destination);
+                    });
+            }
+        };
+        setNavigateHandler(ourHandler);
+        const ourReloadHandler = (mode) => {
+            if (!isPreviewModeLatched())
+                return;
+            if (mode === 'soft') {
+                if (typeof router.refresh === 'function') {
+                    startRefresh(() => { resetPreviewRenderFailure(); router.refresh?.(); });
+                }
+                return;
+            }
+            if (typeof window !== 'undefined') {
+                window.location.reload();
+            }
+        };
+        setReloadHandler(ourReloadHandler);
+        const registration = { navigate: ourHandler, reload: ourReloadHandler };
+        navigationAdapters.add(registration);
+        return () => {
+            navigationRevisionRef.current += 1;
+            navigationAdapters.delete(registration);
+            const survivingAdapter = [...navigationAdapters].at(-1);
+            // Only restore a survivor/default when WE'RE still the registered
+            // handler. If another adapter (or override) installed
+            // its own handler after us, leave it alone — clearing
+            // would silently break that adapter.
+            if (getNavigateHandler() === ourHandler) {
+                setNavigateHandler(survivingAdapter?.navigate ?? null);
+                cancelPreviewRefreshCoordination();
+            }
+            if (getReloadHandler() === ourReloadHandler) {
+                setReloadHandler(survivingAdapter?.reload ?? null);
+            }
+        };
+        // The router reference from Next's hooks is stable across
+        // renders (Next memoises both instances internally), so
+        // depending on it here is safe.
+    }, [router, pagesRouter, options?.onScopeChange, options?.basePath]);
+    // ADR-108 D6 — Pages Router location-subscriber wiring. App Router
+    // consumers must additionally call `useStorystickPreviewLocation` —
+    // it lives in a separate module to avoid pulling `next/navigation`
+    // hooks into this entry's module graph.
+    //
+    // For Pages Router we attach `router.events.on('routeChangeComplete',
+    // cb)` and emit a transition tuple to the SDK's
+    // `notifyRouterTransition`. basePath: auto-default from
+    // `pagesRouter.basePath` (NextRouter public API). Hash is read from
+    // `window.location.hash` (events.on doesn't surface it).
+    //
+    // App Router consumers fall through this effect (the explicit
+    // `appRouter` argument wins above, leaving `pagesRouter` null when
+    // App context is in play), so no subscriber registration races
+    // with the App-side hook.
+    const explicitBasePath = options?.basePath;
+    useIsoLayoutEffect(() => {
+        // ADR-116 PR8 — same pattern as the navigate handler above : wire
+        // `events.on('routeChangeComplete', ...)` unconditionally and gate
+        // INSIDE the callback. Pre-PR8 the synchronous latch check at
+        // effect-start bailed on a fresh post-hard-nav realm, and the
+        // deps `[appRouter, pagesRouter, explicitBasePath]` did not
+        // include identity — so the subscriber was never wired and
+        // reverse-channel emissions from Pages Router customers died
+        // post-hard-nav.
+        isPreviewModeLatched(); // seed the globalThis latch eagerly
+        // Only wire the Pages Router events path when the resolved
+        // router IS the pagesRouter (i.e. no explicit appRouter was
+        // provided, OR appRouter was provided but unusable and we fell
+        // back to pages). Detecting via `pagesRouter !== null AND
+        // !appRouter` is the simplest invariant.
+        if (appRouter)
+            return;
+        if (pagesRouter === null)
+            return;
+        // Type-narrow the compat router instance to the Pages NextRouter
+        // shape we need: events.on/.off + a readable basePath. The
+        // compat router exposes both by spec, but the RouterReplaceable
+        // narrowed type doesn't include them — re-narrow locally.
+        const pr = pagesRouter;
+        if (!pr.events || typeof pr.events.on !== 'function')
+            return;
+        const basePath = explicitBasePath ?? pr.basePath ?? '';
+        const onRouteChange = (url) => {
+            // ADR-116 PR8 dispatch-time gate. Skip the emission when not in
+            // preview mode (top-level page, identity not yet restored, etc.).
+            if (!isPreviewModeLatched())
+                return;
+            // `url` is the Pages Router's "as" path (e.g.
+            // `/admin/page?x=1`); not the rewritten internal route.
+            // Split into pathname / search; hash is read separately.
+            const hashIdx = url.indexOf('#');
+            const beforeHash = hashIdx >= 0 ? url.slice(0, hashIdx) : url;
+            // events.on doesn't surface the hash (the Pages router
+            // doesn't fire on pure hash changes), but hash present on
+            // a route change is read from window.location.
+            const hash = typeof window !== 'undefined' ? window.location.hash : '';
+            const queryIdx = beforeHash.indexOf('?');
+            const rawPath = queryIdx >= 0 ? beforeHash.slice(0, queryIdx) : beforeHash;
+            const search = queryIdx >= 0 ? beforeHash.slice(queryIdx + 1) : '';
+            const pathname = stripBasePath(basePath, rawPath);
+            observePreviewNavigationCommit(`${pathname}${search ? `?${search}` : ''}${hash}`);
+            notifyRouterTransition({ pathname, search, hash, browserPathname: rawPath });
+        };
+        pr.events.on('routeChangeComplete', onRouteChange);
+        return () => {
+            pr.events?.off('routeChangeComplete', onRouteChange);
+        };
+    }, [appRouter, pagesRouter, explicitBasePath]);
+}

package/dist/preview-refresh-coordinator.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Serializes framework refreshes around App Router navigation commits.
+ *
+ * `router.replace()` and `router.refresh()` both start React Flight
+ * transitions. Issuing them back-to-back can make two responses race inside
+ * Next's Flight client. We therefore wait for the location hook to observe the
+ * committed destination, then issue at most one refresh. A projection-ready
+ * content refresh arriving meanwhile supersedes the navigation-only refresh.
+ */
+export declare const NAVIGATION_COMMIT_FALLBACK_MS = 8000;
+export declare function beginPreviewNavigation(input: {
+    readonly destination: string;
+    readonly currentLocation: string;
+    readonly refresh?: () => void;
+    /** Preserve command settlement when a content refresh replaces the physical refresh. */
+    readonly runRefresh?: (refresh: () => void) => void;
+}): boolean;
+/** Called by the framework location adapter after a destination commit. */
+export declare function observePreviewNavigationCommit(committedLocation: string): boolean;
+/**
+ * Run an exact content refresh now, or fold it into the navigation refresh
+ * that will run immediately after the destination commits.
+ */
+export declare function requestPreviewContentRefresh(refresh: () => void): void;
+export declare function cancelPreviewRefreshCoordination(): void;
+export declare function _resetPreviewRefreshCoordinatorForTests(): void;

package/dist/preview-refresh-coordinator.js

@@ -0,0 +1,93 @@
+/**
+ * Serializes framework refreshes around App Router navigation commits.
+ *
+ * `router.replace()` and `router.refresh()` both start React Flight
+ * transitions. Issuing them back-to-back can make two responses race inside
+ * Next's Flight client. We therefore wait for the location hook to observe the
+ * committed destination, then issue at most one refresh. A projection-ready
+ * content refresh arriving meanwhile supersedes the navigation-only refresh.
+ */
+export const NAVIGATION_COMMIT_FALLBACK_MS = 8_000;
+let pendingNavigation = null;
+let deferredContentRefresh = null;
+export function beginPreviewNavigation(input) {
+    clearPendingNavigation();
+    if (sameBrowserLocation(input.destination, input.currentLocation)) {
+        const refresh = deferredContentRefresh ?? input.refresh ?? null;
+        deferredContentRefresh = null;
+        if (refresh)
+            (input.runRefresh ?? ((run) => run()))(refresh);
+        return false;
+    }
+    const pending = {
+        destination: input.destination,
+        refresh: input.refresh ?? null,
+        runRefresh: input.runRefresh,
+        timer: setTimeout(() => {
+            if (pendingNavigation !== pending)
+                return;
+            settlePendingNavigation();
+        }, NAVIGATION_COMMIT_FALLBACK_MS),
+    };
+    pendingNavigation = pending;
+    return true;
+}
+/** Called by the framework location adapter after a destination commit. */
+export function observePreviewNavigationCommit(committedLocation) {
+    if (pendingNavigation === null ||
+        !sameBrowserLocation(pendingNavigation.destination, committedLocation)) {
+        return false;
+    }
+    settlePendingNavigation();
+    return true;
+}
+/**
+ * Run an exact content refresh now, or fold it into the navigation refresh
+ * that will run immediately after the destination commits.
+ */
+export function requestPreviewContentRefresh(refresh) {
+    if (pendingNavigation !== null) {
+        deferredContentRefresh = refresh;
+        return;
+    }
+    refresh();
+}
+export function cancelPreviewRefreshCoordination() {
+    clearPendingNavigation();
+    deferredContentRefresh = null;
+}
+function settlePendingNavigation() {
+    const pending = pendingNavigation;
+    if (pending === null)
+        return;
+    clearTimeout(pending.timer);
+    pendingNavigation = null;
+    const refresh = deferredContentRefresh ?? pending.refresh;
+    deferredContentRefresh = null;
+    if (refresh)
+        (pending.runRefresh ?? ((run) => run()))(refresh);
+}
+function clearPendingNavigation() {
+    if (pendingNavigation === null)
+        return;
+    clearTimeout(pendingNavigation.timer);
+    pendingNavigation = null;
+}
+function sameBrowserLocation(destination, currentLocation) {
+    try {
+        const current = new URL(currentLocation, 'https://preview.invalid');
+        const target = new URL(destination, current);
+        // Pages Router uses this private revision only to force a data load.
+        current.searchParams.delete('_ss_refresh');
+        target.searchParams.delete('_ss_refresh');
+        return (target.pathname === current.pathname &&
+            target.search === current.search &&
+            target.hash === current.hash);
+    }
+    catch {
+        return false;
+    }
+}
+export function _resetPreviewRefreshCoordinatorForTests() {
+    cancelPreviewRefreshCoordination();
+}

package/dist/preview-render-error.d.ts

@@ -0,0 +1,11 @@
+export declare const PREVIEW_READ_UNAVAILABLE_DIGEST = "storystick.preview.read-unavailable.v1";
+export declare const PREVIEW_CONTEXT_SUPERSEDED_DIGEST = "storystick.preview.context-superseded.v1";
+export declare const CUSTOMER_RENDER_ERROR = "runtime.customer_render_failed";
+export declare const PREVIEW_READ_UNAVAILABLE = "runtime.preview_read_unavailable";
+export declare function previewReadUnavailableDigest(retryAfterMs: number | undefined, now: number): string;
+export declare function previewRenderError(digest: string | undefined): {
+    retryNotBefore?: number | undefined;
+    code: string;
+    message: string;
+    retryable: boolean;
+};