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

package/dist/preview-mode-latch.js

@@ -0,0 +1,231 @@
+/**
+ * Preview identity latch (ADR-113 D2 + follow-up).
+ *
+ * Both customer SDK hooks (`useStorystickPreviewNavigation` and
+ * `useStorystickPreviewLocation`) plus the forward-path session
+ * preservation in `preview-nav.ts` need a stable answer to two
+ * questions:
+ *
+ *   1. *"Is this page running inside a Storystick preview iframe?"*
+ *      (boolean — gates whether to register handlers)
+ *   2. *"What is the active `_ss_session` identifier?"*
+ *      (string — appended to Studio-dispatched destinations so
+ *      subsequent App Router navigates stay inside the preview
+ *      session)
+ *
+ * The original heuristic — re-derive from `window.location.search` on
+ * every render — breaks the moment the customer's own intra-iframe
+ * nav drops `_ss_session` from the URL: the gate flips to false (PR5
+ * fix), and the destination injection loses the marker (this fix).
+ *
+ *   t0 boot:    /?_ss_session=X    → active=true,  sessionId=X
+ *   t1 nav:     /pricing           → active=true,  sessionId=X (cached)
+ *   t2 onward:  /pricing           → active=true,  sessionId=X (cached)
+ *
+ * The latch lives on `globalThis` (not module scope) so it survives
+ * HMR: Next/Fast Refresh re-evaluates modules but never replaces the
+ * `globalThis` object, so a module-scope `let` would be lost on HMR
+ * while a `globalThis.__storystick_preview_mode_latched__` write is
+ * preserved by construction.
+ *
+ * **Backward-compatible shape**: `sessionId` is OPTIONAL on the
+ * stored object. An older `@storystick/next` version that wrote just
+ * `{ active }` (pre-follow-up) is read by the new code as
+ * `existing.sessionId === undefined` — the new code then runs
+ * opportunistic backfill: if the URL currently has `_ss_session`, it
+ * upgrades the in-place latch object so subsequent reads pick up the
+ * id. Symmetric direction (new writer / old reader) is trivially
+ * safe — the old reader only ever inspected `.active`.
+ *
+ * **Why not bump the namespace key**: two `@storystick/next` versions
+ * in the same process MUST share the active-preview decision (the
+ * gate). Bumping the key would partition the gate too, reintroducing
+ * the pre-PR5 bug for the older copy. Codex R4 follow-up consult
+ * 2026-05-14: keep namespace, extend shape.
+ *
+ * **Tri-state via object presence**: a raw boolean cannot distinguish
+ * "latched and false" from "not latched yet". The `PreviewLatch`
+ * object is the sentinel: `existing !== undefined` means latched
+ * (active or not); the boolean inside carries the decision.
+ *
+ * **Namespace stability**: `__storystick_preview_mode_latched__` is
+ * the single, underscore-prefixed key. The literal-string grep test
+ * in `preview-mode-latch.test.ts` pins it; do not rename even if
+ * "mode" is now an under-description (the latch carries identity too).
+ */
+import { previewRuntime } from '@storystick/preview/runtime/store';
+import { detectPreviewSessionFromWindow, readPreviewIdentitySessionIdFromSource, } from '@storystick/preview/identity';
+/**
+ * ADR-116 PR5 — read the active identity from the preview runtime
+ * store. Returns `null` when :
+ *   - the runtime is mocked without `getIdentity` (legacy test mocks),
+ *   - the runtime has not been initialized yet (pre-boot),
+ *   - we are outside preview mode (identity is null).
+ *
+ * When non-null, the identity layer is authoritative — the
+ * `globalThis.__storystick_preview_mode_latched__` cache becomes a
+ * pre-init / cross-version fallback.
+ */
+function tryReadIdentitySessionId() {
+    return readPreviewIdentitySessionIdFromSource(previewRuntime);
+}
+/**
+ * Return whether the current page is running inside a Storystick
+ * preview iframe. Latches on first valid call: subsequent calls return
+ * the cached value even after the URL drops `_ss_session` (customer
+ * intra-iframe nav).
+ *
+ * Also performs opportunistic sessionId backfill: if the existing
+ * latch is missing `sessionId` (either old SDK shape or first mount
+ * happened mid-customer-nav) AND the URL currently carries
+ * `_ss_session`, the value is written into the latch in place so
+ * `getLatchedPreviewSessionId()` returns it on subsequent calls.
+ *
+ * SSR / no-`window` calls return false without latching — they cannot
+ * know yet, and we must not freeze the wrong answer for the eventual
+ * client hydration.
+ */
+export function isPreviewModeLatched() {
+    if (previewRuntime.getState?.().previewEnded)
+        return false;
+    // ADR-116 PR5 — identity layer is authoritative when populated.
+    // Fallback to the globalThis latch + URL path covers pre-init
+    // (synchronous render before init resolves) AND legacy test mocks.
+    if (tryReadIdentitySessionId() !== null)
+        return true;
+    if (typeof globalThis === 'undefined')
+        return false;
+    const existing = globalThis.__storystick_preview_mode_latched__;
+    if (existing !== undefined) {
+        // Opportunistic backfill: an old-shape latch (or a latch written
+        // when the URL happened to lack the param at first read) is
+        // upgraded in place if the URL has since regained `_ss_session`.
+        // Only attempted when active=true — top-level pages never carry
+        // a meaningful session id, so we don't capture URL noise.
+        if (existing.active &&
+            (existing.sessionId === undefined ||
+                existing.sessionId === null ||
+                existing.variantId === undefined ||
+                existing.releaseId === undefined) &&
+            typeof window !== 'undefined') {
+            const detected = detectPreviewSessionFromWindow(window);
+            if (detected.active &&
+                detected.sessionId !== null &&
+                (existing.sessionId === undefined || existing.sessionId === null)) {
+                existing.sessionId = detected.sessionId;
+            }
+            if (detected.active &&
+                detected.variantId !== null &&
+                existing.variantId === undefined) {
+                existing.variantId = detected.variantId;
+            }
+            if (detected.active &&
+                detected.releaseId !== null &&
+                existing.releaseId === undefined) {
+                existing.releaseId = detected.releaseId;
+            }
+        }
+        return existing.active;
+    }
+    if (typeof window === 'undefined')
+        return false;
+    const detected = detectPreviewSessionFromWindow(window);
+    globalThis.__storystick_preview_mode_latched__ = detected;
+    return detected.active;
+}
+/**
+ * Return the latched `_ss_session` identifier. `null` when the latch
+ * has not run, the page is not in preview mode, or the latch was
+ * captured before the param was available (an old SDK version, or a
+ * first read that happened mid-customer-nav).
+ *
+ * Callers in the SDK forward path (`preservePreviewSession`) use this
+ * as the primary source over `window.location.search`: the latch is
+ * Studio-authoritative (set at boot from the URL Studio constructed),
+ * while the live URL is customer-mutable surface that intra-iframe
+ * nav routinely strips.
+ *
+ * The caller is responsible for invoking `isPreviewModeLatched()`
+ * first (or otherwise gating on preview mode) before consuming this
+ * value — outside preview the latch is never written and this
+ * returns `null` unconditionally.
+ */
+export function getLatchedPreviewSessionId() {
+    if (previewRuntime.getState?.().previewEnded)
+        return null;
+    // ADR-116 PR5 — identity layer wins ; the globalThis latch becomes a
+    // fallback substrate for pre-init / legacy contexts.
+    const fromIdentity = tryReadIdentitySessionId();
+    if (fromIdentity !== null)
+        return fromIdentity;
+    if (typeof globalThis === 'undefined')
+        return null;
+    return globalThis.__storystick_preview_mode_latched__?.sessionId ?? null;
+}
+export function readPreviewSessionIdForNavigation() {
+    if (previewRuntime.getState?.().previewEnded)
+        return null;
+    const fromIdentity = tryReadIdentitySessionId();
+    if (fromIdentity !== null)
+        return fromIdentity;
+    const fromLatch = getLatchedPreviewSessionId();
+    if (fromLatch !== null)
+        return fromLatch;
+    if (typeof window === 'undefined')
+        return null;
+    return detectPreviewSessionFromWindow(window).sessionId;
+}
+export function readPreviewVariantIdForNavigation() {
+    if (typeof globalThis !== 'undefined') {
+        const latch = globalThis.__storystick_preview_mode_latched__;
+        if (latch?.active && latch.variantId !== undefined) {
+            return typeof latch.variantId === 'string' && latch.variantId.length > 0
+                ? latch.variantId
+                : null;
+        }
+    }
+    if (typeof window === 'undefined')
+        return null;
+    return detectPreviewSessionFromWindow(window).variantId;
+}
+export function readPreviewReleaseIdForNavigation() {
+    if (typeof globalThis !== 'undefined') {
+        const latch = globalThis.__storystick_preview_mode_latched__;
+        if (latch?.active && latch.releaseId !== undefined) {
+            return typeof latch.releaseId === 'string' && latch.releaseId.length > 0
+                ? latch.releaseId
+                : null;
+        }
+    }
+    if (typeof window === 'undefined')
+        return null;
+    return detectPreviewSessionFromWindow(window).releaseId;
+}
+/**
+ * Replace the latched request scope after a trusted Studio navigation.
+ * Living scope deliberately clears both selectors so a later customer-side
+ * navigation cannot resurrect an older variant or release from the boot URL.
+ */
+export function setLatchedPreviewScope(scope) {
+    if (typeof globalThis === 'undefined')
+        return;
+    const current = globalThis.__storystick_preview_mode_latched__;
+    if (current === undefined || !current.active)
+        return;
+    current.variantId = scope.kind === 'variant' ? scope.variantId : null;
+    current.releaseId = scope.kind === 'release' ? scope.releaseId : null;
+}
+/**
+ * Test-only reset. Vitest's module isolation re-imports modules between
+ * tests but `globalThis` is shared across the suite, so a latch set in
+ * test A would leak into test B. Tests call this in `beforeEach` to
+ * start each case with a fresh latch.
+ *
+ * Production code MUST NOT call this — clearing the latch reintroduces
+ * the very bug it exists to prevent.
+ */
+export function _resetPreviewModeLatchForTests() {
+    if (typeof globalThis !== 'undefined') {
+        globalThis.__storystick_preview_mode_latched__ = undefined;
+    }
+}

package/dist/preview-nav-location.d.ts

@@ -0,0 +1,12 @@
+import { type PreviewNavOptions } from './preview-nav.js';
+export declare function sanitizePreviewLocationSearch(searchParams: URLSearchParams): string;
+/**
+ * Register the App Router-side `subscribeRouter` adapter. The hook
+ * reads pathname + searchParams from `next/navigation` and emits a
+ * transition tuple on every change.
+ *
+ * @param options.basePath — `next.config.js` basePath. App Router
+ *   does not expose basePath publicly so customers using a configured
+ *   basePath MUST pass it here. Defaults to `''` (no stripping).
+ */
+export declare function useStorystickPreviewLocation(options?: PreviewNavOptions): void;

package/dist/preview-nav-location.js

@@ -0,0 +1,149 @@
+'use client';
+/**
+ * Next App Router preview-location adapter (ADR-108 D6).
+ *
+ * Companion to `useStorystickPreviewNavigation` — App Router consumers
+ * call BOTH hooks:
+ *
+ * ```tsx
+ * 'use client'
+ * import { useRouter } from 'next/navigation'
+ * import { useStorystickPreviewNavigation } from '@storystick/next/preview-nav'
+ * import { useStorystickPreviewLocation } from '@storystick/next/preview-nav-location'
+ *
+ * export function Providers({ children }) {
+ *   const router = useRouter()
+ *   useStorystickPreviewNavigation(router)
+ *   useStorystickPreviewLocation()
+ *   return <StorystickQueryProvider …>{children}</StorystickQueryProvider>
+ * }
+ * ```
+ *
+ * Why split: `usePathname` and `useSearchParams` from `next/navigation`
+ * throw in Pages Router context. Importing them at module scope is
+ * safe (no execution), but calling them must be gated on App Router.
+ * Splitting the hook into its own module makes the call site
+ * unambiguous: customers in App Router call it, Pages Router
+ * customers don't.
+ *
+ * For Pages Router, `useStorystickPreviewNavigation` itself wires
+ * `router.events.on('routeChangeComplete')` and reports transitions
+ * automatically — Pages consumers don't need this hook.
+ *
+ * **Hash handling**: `usePathname`/`useSearchParams` don't expose the
+ * fragment. We read `window.location.hash` synchronously inside the
+ * effect after the (pathname, search) tuple changes — Next App Router
+ * scrolls to the hash before our effect runs, so the hash we see is
+ * the post-navigation value.
+ *
+ * **rAF coalescing**: multiple synchronous transitions in a single
+ * frame collapse to a single emission (the last one). Mirror of the
+ * `section-bounds` reporter pattern.
+ */
+import { useEffect, useLayoutEffect } from 'react';
+import { usePathname, useSearchParams } from 'next/navigation';
+import { notifyRouterTransition } from '@storystick/preview/router-subscriber';
+import { recordPreviewPerfMetric } from '@storystick/preview/runtime/perf-metrics';
+import { stripBasePath } from './preview-nav.js';
+import { isPreviewModeLatched } from './preview-mode-latch.js';
+import { observePreviewNavigationCommit } from './preview-refresh-coordinator.js';
+import { confirmPreviewRender } from './preview-render-recovery.js';
+// ADR-116 FU2 — synchronous post-render commit avoids an HMR re-mount
+// race where a residual `activate()` listener fires before a passive
+// `useEffect` commits the new mount's wiring.
+const useIsoLayoutEffect = typeof window === 'undefined' ? useEffect : useLayoutEffect;
+export function sanitizePreviewLocationSearch(searchParams) {
+    const sanitized = new URLSearchParams(searchParams);
+    for (const key of [...sanitized.keys()]) {
+        if (key.startsWith('_ss_'))
+            sanitized.delete(key);
+    }
+    return sanitized.toString();
+}
+/**
+ * Register the App Router-side `subscribeRouter` adapter. The hook
+ * reads pathname + searchParams from `next/navigation` and emits a
+ * transition tuple on every change.
+ *
+ * @param options.basePath — `next.config.js` basePath. App Router
+ *   does not expose basePath publicly so customers using a configured
+ *   basePath MUST pass it here. Defaults to `''` (no stripping).
+ */
+export function useStorystickPreviewLocation(options) {
+    const pathname = usePathname();
+    const searchParams = useSearchParams();
+    const basePath = options?.basePath ?? '';
+    useIsoLayoutEffect(() => {
+        // ADR-116 PR8 — schedule the rAF tick UNCONDITIONALLY (gated only
+        // on pathname / searchParams being non-null). The preview-mode /
+        // identity gate moves INSIDE `tick()` so a post-hard-nav re-mount
+        // schedules its first emission against the current pathname AND
+        // re-evaluates the latch at emit time — by which point the resolver
+        // has typically restored identity via the storage carrier or Studio
+        // session-broadcast (ADR-116 D3). Pre-PR8 the synchronous latch
+        // check at effect-start bailed and the first post-recovery pathname
+        // emission was lost until the next router transition.
+        isPreviewModeLatched(); // seed the globalThis latch eagerly
+        if (pathname === null)
+            return;
+        // Codex R3 finding #1 — `useSearchParams()` returns `null` during
+        // the initial SSR/CSR hand-off (`?` value not yet hydrated).
+        // Emitting now would post an envelope with a stale empty search
+        // string before the real value lands; bail until the next render.
+        if (searchParams === null)
+            return;
+        let cancelled = false;
+        let rafId = null;
+        // rAF coalescing — multiple synchronous transitions collapse to
+        // the last value within a single frame. The customer's router
+        // sometimes fires `usePathname`/`useSearchParams` change twice
+        // on a single route change (Next 15 known quirk on transitions
+        // that change both segments and query); coalescing keeps Studio's
+        // listener from seeing duplicates.
+        const tick = () => {
+            rafId = null;
+            if (cancelled)
+                return;
+            // ADR-116 PR8 dispatch-time gate. Skip the emission when not in
+            // preview mode (top-level page, identity not yet restored, etc.).
+            // `notifyRouterTransition` is a NOOP without a registered
+            // subscriber AND `emitLocation` inside activate() additionally
+            // guards on `parentOriginLock === null`, but the explicit gate
+            // here keeps observable behaviour symmetric with the navigate
+            // handler and avoids the rAF + parse work in non-preview mode.
+            const strippedPath = stripBasePath(basePath, pathname);
+            const search = sanitizePreviewLocationSearch(searchParams);
+            const rawSearch = searchParams.toString();
+            // Hash is not surfaced by App Router hooks; read it from
+            // window.location. Next has already scrolled/applied the
+            // hash by the time this effect runs.
+            const hash = typeof window !== 'undefined' ? window.location.hash : '';
+            const committedLocation = `${strippedPath}${rawSearch ? `?${rawSearch}` : ''}${hash}`;
+            observePreviewNavigationCommit(committedLocation);
+            if (!isPreviewModeLatched() || !confirmPreviewRender())
+                return;
+            recordPreviewPerfMetric(window, { name: 'next.navigate.locationCommitted' });
+            notifyRouterTransition({
+                pathname: strippedPath,
+                browserPathname: `${basePath.replace(/\/$/, '')}${strippedPath}`,
+                search,
+                hash,
+            });
+        };
+        if (typeof window === 'undefined' ||
+            typeof window.requestAnimationFrame !== 'function') {
+            // SSR / jsdom-without-rAF — invoke synchronously.
+            tick();
+        }
+        else {
+            rafId = window.requestAnimationFrame(tick);
+        }
+        return () => {
+            cancelled = true;
+            if (rafId !== null && typeof window !== 'undefined') {
+                window.cancelAnimationFrame(rafId);
+                rafId = null;
+            }
+        };
+    }, [pathname, searchParams, basePath]);
+}

package/dist/preview-nav.d.ts

@@ -0,0 +1,94 @@
+import { type PreviewScope } from '@storystick/preview/identity';
+/**
+ * Minimal contract we need from the resolved router : a `replace`
+ * method that takes a same-origin absolute pathname. App Router's
+ * `AppRouterInstance` and Pages Router's `NextRouter` both satisfy
+ * this — we narrow to it explicitly so the rest of the hook stays
+ * router-agnostic.
+ *
+ * **ADR-101 D3** — the iframe-side adapter uses `replace`, not
+ * `push`, for every Studio-issued navigate envelope. Studio history
+ * is authoritative ; iframe history is suppressed so the editor's
+ * Back button steps through studio navigations (cross-doc swaps,
+ * route changes), never through per-keystroke pathname edits or
+ * variant-pathname shifts. Matches Sanity Visual Editing,
+ * Storyblok preview bridge, Builder.io, and Whatfix's published
+ * preview-bridge guidance.
+ *
+ * Customer-initiated nav (an end-user clicks an `<a>` inside the
+ * iframe during a content demo) does NOT go through this hook —
+ * the customer's framework router handles it directly. The flip
+ * here is scoped strictly to envelope-driven nav.
+ */
+interface RouterReplaceable {
+    replace: (pathname: string) => unknown;
+    push: (pathname: string) => unknown;
+    /**
+     * ADR-111 — optional. App Router exposes `router.refresh()`; the
+     * Pages Router does not. The adapter calls this when the envelope
+     * carries `payload.refresh === true` (layout preview state changed)
+     * so the client Router Cache invalidates and `resolvePreviewDraft()`
+     * re-runs against the new session row. On Pages Router the field
+     * is undefined and the call is skipped (Pages has no cached layout
+     * segment to invalidate — the published-vs-draft branch lives in
+     * `getServerSideProps`, which re-runs on every replace).
+     */
+    refresh?: () => unknown;
+}
+/**
+ * ADR-108 D6 — options accepted alongside the App Router argument.
+ * Currently exposes `basePath` for `next.config.js`-configured prefix
+ * stripping. Future fields (locale stripping, custom serialiser, etc.)
+ * extend this without bumping the hook signature.
+ */
+export interface PreviewNavOptions {
+    /**
+     * `next.config.js`-configured basePath. When set, the SDK strips
+     * the prefix (path-segment-boundary aware) from
+     * `window.location.pathname` BEFORE building the
+     * `storystick.preview.location` envelope.
+     *
+     * Pages Router: auto-defaults from `pagesRouter.basePath` (public
+     * API on `NextRouter`). Pass explicitly only to override.
+     *
+     * App Router: defaults to `''` because App Router does not expose
+     * basePath publicly. App Router customers using `next.config.js`
+     * basePath MUST pass it here.
+     *
+     * Stripping logic: segment-boundary aware. `'/admin'` strips
+     * `/admin/page` → `/page` but NOT `/administrator` (no leading
+     * `/strator` garbage). Trailing slash normalised: `'/admin/'` and
+     * `'/admin'` behave identically.
+     */
+    basePath?: string;
+    /**
+     * Internal runtime hook used to publish the exact Studio-selected
+     * perspective before the framework starts rendering the destination.
+     * Framework integrations may omit it; URL scope remains authoritative.
+     */
+    onScopeChange?: (scope: PreviewScope) => void;
+}
+/**
+ * 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 declare function stripBasePath(basePath: string, pathname: string): string;
+/**
+ * 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 declare function useStorystickPreviewNavigation(appRouter?: RouterReplaceable | null, options?: PreviewNavOptions): void;
+export {};