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

package/dist/identity/carriers/postmessage.d.ts

@@ -0,0 +1,84 @@
+/**
+ * ADR-116 D2 — bidirectional session sync over postMessage.
+ *
+ * The iframe SDK posts `session-request` to `window.parent` at boot AND
+ * on every `disconnected → resolving-identity` recovery transition. The
+ * Studio side responds with `session-broadcast` (and also proactively
+ * broadcasts on every iframe `load` once `activeSessionIdRef.current`
+ * is non-null). Both messages converge into the resolver's D10
+ * replacement table : duplicates are idempotent, conflicting projectIds
+ * are rejected.
+ *
+ * targetOrigin policy : the SDK does NOT know the Studio origin until
+ * a broadcast lands. Outbound session-request uses `targetOrigin = '*'`
+ * (the only sensible default pre-handshake). Inbound broadcasts are
+ * validated by origin allowlist + envelope shape ; after the first
+ * confirmed broadcast the iframe locks the parent origin to
+ * `event.origin` and refuses subsequent envelopes from any other.
+ */
+import { type SessionRequestEnvelope } from '@storystick/transport-allowlist';
+import type { ProvisionalIdentity } from '../identity-types.js';
+/**
+ * Build a fresh `session-request` envelope. Pure — no side effects.
+ *
+ * The iframe does not yet know its sessionId, so the envelope carries
+ * an empty string for that field (legal exception in the validator
+ * for this type only).
+ */
+export declare function buildSessionRequest(args: {
+    projectId: string;
+    reason: 'boot' | 'recovery';
+    now?: () => number;
+    randomHex?: () => string;
+}): SessionRequestEnvelope;
+/**
+ * Inbound broadcast validator. Wraps the shared `validatePreviewEnvelope`
+ * plus a projectId tie-breaker so the carrier returns the
+ * `ProvisionalIdentity` directly without the caller doing its own type
+ * narrowing.
+ *
+ * `eventOrigin` is the postMessage `MessageEvent.origin`. The resolver
+ * locks the iframe's parent origin to this value on the first confirmed
+ * broadcast (D2 targetOrigin policy).
+ */
+export declare function parseInboundBroadcast(raw: unknown, eventOrigin: string, expectedProjectId: string): {
+    ok: true;
+    identity: ProvisionalIdentity;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Bind a `message` listener that forwards every well-formed
+ * `session-broadcast` envelope to the resolver callback. Returns the
+ * disposer. The caller MUST invoke the disposer on teardown (resolver
+ * stop, runtime dispose, framework HMR re-mount).
+ *
+ * The listener does NOT validate origin against an allowlist : that
+ * lookup lives Studio-side per ADR-087 §3.7 (projects.allowedOrigins).
+ * Iframe-side, the resolver locks `parentOrigin` to the first
+ * confirmed broadcast's origin and refuses subsequent broadcasts from
+ * any other origin. The lock is applied AFTER `parseInboundBroadcast`
+ * returns ok ; this function is a pure pipe.
+ */
+export declare function attachBroadcastListener(args: {
+    expectedProjectId: string;
+    onBroadcast: (identity: ProvisionalIdentity, eventOrigin: string) => void;
+    /** Optional override for the global window — tests pass a stub. */
+    win?: Window;
+}): () => void;
+/**
+ * Post a `session-request` envelope to `window.parent`. Returns true
+ * if a parent exists ; false in SSR / detached contexts. The envelope
+ * is sent with `targetOrigin = '*'` because the iframe does not yet
+ * know the Studio origin (chicken-and-egg with the broadcast that
+ * would teach it).
+ */
+export declare function postSessionRequest(args: {
+    projectId: string;
+    reason: 'boot' | 'recovery';
+    /** Optional override for `window.parent` — tests pass a stub. */
+    parent?: Window;
+    now?: () => number;
+    randomHex?: () => string;
+}): boolean;

package/dist/identity/carriers/postmessage.js

@@ -0,0 +1,177 @@
+/**
+ * ADR-116 D2 — bidirectional session sync over postMessage.
+ *
+ * The iframe SDK posts `session-request` to `window.parent` at boot AND
+ * on every `disconnected → resolving-identity` recovery transition. The
+ * Studio side responds with `session-broadcast` (and also proactively
+ * broadcasts on every iframe `load` once `activeSessionIdRef.current`
+ * is non-null). Both messages converge into the resolver's D10
+ * replacement table : duplicates are idempotent, conflicting projectIds
+ * are rejected.
+ *
+ * targetOrigin policy : the SDK does NOT know the Studio origin until
+ * a broadcast lands. Outbound session-request uses `targetOrigin = '*'`
+ * (the only sensible default pre-handshake). Inbound broadcasts are
+ * validated by origin allowlist + envelope shape ; after the first
+ * confirmed broadcast the iframe locks the parent origin to
+ * `event.origin` and refuses subsequent envelopes from any other.
+ */
+import { PREVIEW_NAMESPACE, PREVIEW_PROTOCOL_VERSION, validatePreviewEnvelope, } from '@storystick/transport-allowlist';
+// Re-imported here so the file can stay agnostic to where the helper
+// is exported from in the wider preview package.
+function defaultRandomHex() {
+    if (typeof globalThis.crypto !== 'undefined' &&
+        typeof globalThis.crypto.getRandomValues === 'function') {
+        const buf = new Uint8Array(16);
+        globalThis.crypto.getRandomValues(buf);
+        return Array.from(buf, (b) => b.toString(16).padStart(2, '0')).join('');
+    }
+    // Test fallback — production browsers always have crypto.getRandomValues.
+    let s = '';
+    for (let i = 0; i < 32; i += 1)
+        s += Math.floor(Math.random() * 16).toString(16);
+    return s;
+}
+/**
+ * Build a fresh `session-request` envelope. Pure — no side effects.
+ *
+ * The iframe does not yet know its sessionId, so the envelope carries
+ * an empty string for that field (legal exception in the validator
+ * for this type only).
+ */
+export function buildSessionRequest(args) {
+    const now = args.now ?? Date.now;
+    const rand = args.randomHex ?? defaultRandomHex;
+    return {
+        namespace: PREVIEW_NAMESPACE,
+        version: PREVIEW_PROTOCOL_VERSION,
+        type: 'storystick.preview.session-request',
+        // ADR-116 D2 — sessionId is empty pre-handshake. Validator allows
+        // this for session-request only.
+        sessionId: '',
+        projectId: args.projectId,
+        requestId: rand(),
+        nonce: rand(),
+        sentAt: now(),
+        payload: {
+            reason: args.reason,
+        },
+    };
+}
+/**
+ * Inbound broadcast validator. Wraps the shared `validatePreviewEnvelope`
+ * plus a projectId tie-breaker so the carrier returns the
+ * `ProvisionalIdentity` directly without the caller doing its own type
+ * narrowing.
+ *
+ * `eventOrigin` is the postMessage `MessageEvent.origin`. The resolver
+ * locks the iframe's parent origin to this value on the first confirmed
+ * broadcast (D2 targetOrigin policy).
+ */
+export function parseInboundBroadcast(raw, eventOrigin, expectedProjectId) {
+    const validated = validatePreviewEnvelope(raw);
+    if (!validated.ok) {
+        return { ok: false, reason: validated.reason };
+    }
+    const env = validated.message;
+    if (env.type !== 'storystick.preview.session-broadcast') {
+        return { ok: false, reason: 'not a session-broadcast envelope' };
+    }
+    // Now that we have a typed envelope, narrow to the broadcast shape.
+    const broadcast = env;
+    if (broadcast.projectId !== expectedProjectId) {
+        return { ok: false, reason: 'projectId mismatch' };
+    }
+    if (typeof eventOrigin !== 'string' || eventOrigin.length === 0) {
+        return { ok: false, reason: 'event.origin is empty' };
+    }
+    return {
+        ok: true,
+        identity: {
+            sessionId: broadcast.sessionId,
+            projectId: broadcast.projectId,
+            parentOrigin: broadcast.payload.parentOrigin,
+        },
+    };
+}
+/**
+ * Bind a `message` listener that forwards every well-formed
+ * `session-broadcast` envelope to the resolver callback. Returns the
+ * disposer. The caller MUST invoke the disposer on teardown (resolver
+ * stop, runtime dispose, framework HMR re-mount).
+ *
+ * The listener does NOT validate origin against an allowlist : that
+ * lookup lives Studio-side per ADR-087 §3.7 (projects.allowedOrigins).
+ * Iframe-side, the resolver locks `parentOrigin` to the first
+ * confirmed broadcast's origin and refuses subsequent broadcasts from
+ * any other origin. The lock is applied AFTER `parseInboundBroadcast`
+ * returns ok ; this function is a pure pipe.
+ */
+export function attachBroadcastListener(args) {
+    const target = args.win ?? (typeof window === 'undefined' ? undefined : window);
+    if (target === undefined)
+        return () => { };
+    const handler = (event) => {
+        const parsed = parseInboundBroadcast(event.data, event.origin, args.expectedProjectId);
+        if (!parsed.ok)
+            return;
+        args.onBroadcast(parsed.identity, event.origin);
+        // ADR-134 §9.T3 — bfcache liveness ack. Studio's bfcache handler
+        // posts a session-broadcast then waits 500ms for any iframe
+        // postMessage as a liveness proof. An authenticated + idle
+        // iframe doesn't naturally produce any reply postMessage when it
+        // receives a broadcast, so the alive path would false-negative
+        // (codex review R2 P2). Echo the broadcast back to Studio as a
+        // session-request envelope — handleSessionRequestEnvelope already
+        // routes session-requests for the queue-drain flow, and the
+        // existing 8/10s per-Window rate limiter caps the extra traffic.
+        // Origin policy : reply to `event.origin` (the broadcast's
+        // sender), not '*' — once the iframe has received a confirmed
+        // broadcast the parent origin is known.
+        try {
+            const reply = buildSessionRequest({
+                projectId: args.expectedProjectId,
+                reason: 'recovery',
+            });
+            // `event.source` is typed as MessageEventSource (Window | MessagePort | ServiceWorker)
+            // ; postMessage exists on Window. Defensive try/catch handles
+            // exotic source types without breaking the broadcast handler.
+            const source = event.source;
+            source?.postMessage(reply, event.origin);
+        }
+        catch {
+            /* defensive — telemetry path must not break broadcast handler */
+        }
+    };
+    target.addEventListener('message', handler);
+    return () => {
+        target.removeEventListener('message', handler);
+    };
+}
+/**
+ * Post a `session-request` envelope to `window.parent`. Returns true
+ * if a parent exists ; false in SSR / detached contexts. The envelope
+ * is sent with `targetOrigin = '*'` because the iframe does not yet
+ * know the Studio origin (chicken-and-egg with the broadcast that
+ * would teach it).
+ */
+export function postSessionRequest(args) {
+    const target = args.parent ?? (typeof window === 'undefined' ? undefined : window.parent);
+    if (target === undefined)
+        return false;
+    if (typeof window !== 'undefined' && target === window)
+        return false;
+    const envelope = buildSessionRequest({
+        projectId: args.projectId,
+        reason: args.reason,
+        now: args.now,
+        randomHex: args.randomHex,
+    });
+    try {
+        target.postMessage(envelope, '*');
+    }
+    catch {
+        return false;
+    }
+    return true;
+}

package/dist/identity/carriers/storage-state.d.ts

@@ -0,0 +1,41 @@
+/** Shared storage state and validated reads. Writers are loaded by Preview activation. */
+export declare const STORAGE_KEY = "__storystick_preview_identity__v1";
+export declare const STANDALONE_STORAGE_KEY = "__storystick_standalone_identity__v1";
+export declare const standaloneMemory: {
+    value: StoredIdentityV1 | null;
+};
+/**
+ * Embedded identity TTL — 5 minutes from last broadcast confirmation.
+ * Standalone hints survive for the tab lifetime; only the server grant
+ * authorizes their use, including after reload or suspension.
+ *
+ * Post-ADR-131 C7 Gap A fix (2026-05-26): reduced from 30min to 5min
+ * to align with the preview session row refresh rate. The longer
+ * window allowed sessionStorage to outlive `previewSessions` rows that
+ * had already been GC'd / replaced, surfacing as
+ * `INVALID_PREVIEW_SESSION` from preview-scoped follow-up calls when
+ * the iframe submitted with a stale cached sessionId.
+ */
+export declare const STORAGE_TTL_MS: number;
+/**
+ * Wire shape persisted in sessionStorage. Distinct from `PreviewIdentity`
+ * because the wire payload carries an explicit `expiresAt` for embedded
+ * freshness and a standalone marker for the tab-scoped carrier.
+ */
+export interface StoredIdentityV1 {
+    v: 1;
+    /** A server-validated top-level view persists for this tab's lifetime. */
+    standalone?: true;
+    studioUrl?: string;
+    /** Tab-local preference, never an authorization or a momentary Alt override. */
+    interactionMode?: 'edit' | 'browse';
+    sessionId: string;
+    projectId: string;
+    parentOrigin: string | null;
+    expiresAt: number;
+}
+export declare function getStorage(): Storage | null;
+/** Read raw stored entry (exposed for tests). */
+export declare function readStored(): StoredIdentityV1 | null;
+export declare function readStandaloneStored(): StoredIdentityV1 | null;
+export declare function safeStudioUrl(value: unknown): value is string;

package/dist/identity/carriers/storage-state.js

@@ -0,0 +1,99 @@
+/** Shared storage state and validated reads. Writers are loaded by Preview activation. */
+export const STORAGE_KEY = '__storystick_preview_identity__v1';
+// A Studio iframe and the previous autonomous page can share origin + tab
+// storage. Their view identities must never overwrite or resume one another.
+export const STANDALONE_STORAGE_KEY = '__storystick_standalone_identity__v1';
+export const standaloneMemory = { value: null };
+/**
+ * Embedded identity TTL — 5 minutes from last broadcast confirmation.
+ * Standalone hints survive for the tab lifetime; only the server grant
+ * authorizes their use, including after reload or suspension.
+ *
+ * Post-ADR-131 C7 Gap A fix (2026-05-26): reduced from 30min to 5min
+ * to align with the preview session row refresh rate. The longer
+ * window allowed sessionStorage to outlive `previewSessions` rows that
+ * had already been GC'd / replaced, surfacing as
+ * `INVALID_PREVIEW_SESSION` from preview-scoped follow-up calls when
+ * the iframe submitted with a stale cached sessionId.
+ */
+export const STORAGE_TTL_MS = 5 * 60 * 1000;
+export function getStorage() {
+    if (typeof window === 'undefined')
+        return null;
+    try {
+        return window.sessionStorage;
+    }
+    catch {
+        return null;
+    }
+}
+function safeGetItem(storage, key) {
+    try {
+        return storage.getItem(key);
+    }
+    catch {
+        return null;
+    }
+}
+function parseStored(raw) {
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof json !== 'object' || json === null)
+        return null;
+    const obj = json;
+    if (obj.v !== 1)
+        return null;
+    if (typeof obj.sessionId !== 'string' || obj.sessionId.length === 0) {
+        return null;
+    }
+    if (typeof obj.projectId !== 'string' || obj.projectId.length === 0) {
+        return null;
+    }
+    if (typeof obj.parentOrigin !== 'string' && obj.parentOrigin !== null) {
+        return null;
+    }
+    if (typeof obj.expiresAt !== 'number' || !Number.isFinite(obj.expiresAt)) {
+        return null;
+    }
+    return {
+        v: 1,
+        ...(obj.standalone === true ? { standalone: true, ...(safeStudioUrl(obj.studioUrl) ? { studioUrl: obj.studioUrl } : {}) } : {}),
+        ...(obj.standalone === true && (obj.interactionMode === 'edit' || obj.interactionMode === 'browse') ? { interactionMode: obj.interactionMode } : {}),
+        sessionId: obj.sessionId,
+        projectId: obj.projectId,
+        parentOrigin: obj.parentOrigin ?? null,
+        expiresAt: obj.expiresAt,
+    };
+}
+/** Read raw stored entry (exposed for tests). */
+export function readStored() {
+    return readEntry(STORAGE_KEY);
+}
+export function readStandaloneStored() {
+    return standaloneMemory.value ?? readEntry(STANDALONE_STORAGE_KEY);
+}
+function readEntry(key) {
+    const storage = getStorage();
+    if (storage === null)
+        return null;
+    const raw = safeGetItem(storage, key);
+    if (raw === null)
+        return null;
+    return parseStored(raw);
+}
+export function safeStudioUrl(value) {
+    if (typeof value !== 'string' || value.length > 8192)
+        return false;
+    try {
+        const url = new URL(value);
+        return (url.protocol === 'https:' || url.protocol === 'http:') && !url.username && !url.password;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/identity/carriers/storage.d.ts

@@ -0,0 +1,39 @@
+/**
+ * ADR-116 D7 — sessionStorage carrier (tier-2 persistence).
+ *
+ * Stores the resolved public identity inside the tab's sessionStorage so a
+ * hard navigation (raw `<a>` click, full reload, `window.location`
+ * assignment) re-bootstraps identity even before a live Studio
+ * broadcast lands.
+ *
+ * PR1 scope : full read/write/validate surface ; PR2 extends the
+ * tests + dogfood entries. The behaviour shipped here is sufficient
+ * for the resolver wiring to consume it.
+ *
+ * Key versioning : `__storystick_preview_identity__v1`. Future shape
+ * changes bump to `_v2` so stale-format reads are dropped instead of
+ * deserialised into an invalid runtime state.
+ */
+import type { Carrier, PreviewIdentity } from '../identity-types.js';
+export { STORAGE_KEY, STANDALONE_STORAGE_KEY, STORAGE_TTL_MS, readStored, readStandaloneStored } from './storage-state.js';
+export type { StoredIdentityV1 } from './storage-state.js';
+/**
+ * Write a fresh identity to sessionStorage (D7 A3 — fires on every
+ * confirmed `session-broadcast` envelope receipt). Wraps every storage
+ * call in try/catch so hardened/private modes never throw out of the
+ * resolver's hot path.
+ */
+export declare function writeStored(identity: PreviewIdentity, now?: () => number): boolean;
+export declare function writeStandaloneStored(identity: Pick<PreviewIdentity, 'sessionId' | 'projectId' | 'parentOrigin'>, now?: () => number): boolean;
+/** Called only after a server-authorized view response, never from URL input. */
+export declare function rememberStandaloneStudioUrl(identity: Pick<PreviewIdentity, 'sessionId' | 'projectId'>, studioUrl: string): void;
+/** A UI preference bound to the existing tab view; a new view starts in Select. */
+export declare function rememberStandaloneInteractionMode(identity: Pick<PreviewIdentity, 'sessionId' | 'projectId'>, interactionMode: 'edit' | 'browse'): void;
+/** Keep an autonomous recovery surface available after a refused cold boot.
+ * This hint carries no authority; Exit Preview explicitly removes it.
+ */
+export declare function clearStoredAfterAuthFailure(): void;
+/** Remove the stored identity (used on expired-storage clear per D10). */
+export declare function clearStored(): void;
+export declare function clearStandaloneStored(): void;
+export declare function createStorageCarrier(): Carrier;

package/dist/identity/carriers/storage.js

@@ -0,0 +1,182 @@
+/**
+ * ADR-116 D7 — sessionStorage carrier (tier-2 persistence).
+ *
+ * Stores the resolved public identity inside the tab's sessionStorage so a
+ * hard navigation (raw `<a>` click, full reload, `window.location`
+ * assignment) re-bootstraps identity even before a live Studio
+ * broadcast lands.
+ *
+ * PR1 scope : full read/write/validate surface ; PR2 extends the
+ * tests + dogfood entries. The behaviour shipped here is sufficient
+ * for the resolver wiring to consume it.
+ *
+ * Key versioning : `__storystick_preview_identity__v1`. Future shape
+ * changes bump to `_v2` so stale-format reads are dropped instead of
+ * deserialised into an invalid runtime state.
+ */
+import { detectPreviewSessionFromWindow } from '../preview-identity.js';
+import { standaloneMemory, getStorage, safeStudioUrl, STORAGE_KEY, STANDALONE_STORAGE_KEY, STORAGE_TTL_MS, readStored, readStandaloneStored, } from './storage-state.js';
+export { STORAGE_KEY, STANDALONE_STORAGE_KEY, STORAGE_TTL_MS, readStored, readStandaloneStored } from './storage-state.js';
+function safeSetItem(storage, key, value) {
+    try {
+        storage.setItem(key, value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function safeRemoveItem(storage, key) {
+    try {
+        storage.removeItem(key);
+    }
+    catch {
+        /* hardened mode — silent */
+    }
+}
+/**
+ * Write a fresh identity to sessionStorage (D7 A3 — fires on every
+ * confirmed `session-broadcast` envelope receipt). Wraps every storage
+ * call in try/catch so hardened/private modes never throw out of the
+ * resolver's hot path.
+ */
+export function writeStored(identity, now = Date.now) {
+    return writeEntry(identity, now, false);
+}
+export function writeStandaloneStored(identity, now = Date.now) {
+    return writeEntry(identity, now, true);
+}
+function writeEntry(identity, now, standalone) {
+    const storage = getStorage();
+    const previous = standalone ? readStandaloneStored() : null;
+    const studioUrl = previous?.standalone && previous.sessionId === identity.sessionId && previous.projectId === identity.projectId ? previous.studioUrl : undefined;
+    const interactionMode = previous?.standalone && previous.sessionId === identity.sessionId && previous.projectId === identity.projectId ? previous.interactionMode : undefined;
+    const wire = {
+        v: 1,
+        ...(standalone ? { standalone: true, ...(studioUrl ? { studioUrl } : {}) } : {}),
+        ...(interactionMode ? { interactionMode } : {}),
+        sessionId: identity.sessionId,
+        projectId: identity.projectId,
+        parentOrigin: identity.parentOrigin,
+        expiresAt: now() + STORAGE_TTL_MS,
+    };
+    if (standalone)
+        standaloneMemory.value = wire;
+    return storage !== null && safeSetItem(storage, standalone ? STANDALONE_STORAGE_KEY : STORAGE_KEY, JSON.stringify(wire));
+}
+/** Called only after a server-authorized view response, never from URL input. */
+export function rememberStandaloneStudioUrl(identity, studioUrl) {
+    if (!safeStudioUrl(studioUrl) || typeof window === 'undefined' || window.parent !== window)
+        return;
+    const stored = readStandaloneStored();
+    const storage = getStorage();
+    if (!stored?.standalone || stored.sessionId !== identity.sessionId || stored.projectId !== identity.projectId)
+        return;
+    standaloneMemory.value = { ...stored, studioUrl };
+    if (storage)
+        safeSetItem(storage, STANDALONE_STORAGE_KEY, JSON.stringify(standaloneMemory.value));
+}
+/** A UI preference bound to the existing tab view; a new view starts in Select. */
+export function rememberStandaloneInteractionMode(identity, interactionMode) {
+    if (typeof window === 'undefined' || window.parent !== window)
+        return;
+    const stored = readStandaloneStored();
+    if (!stored?.standalone || stored.sessionId !== identity.sessionId || stored.projectId !== identity.projectId)
+        return;
+    standaloneMemory.value = { ...stored, interactionMode };
+    const storage = getStorage();
+    if (storage)
+        safeSetItem(storage, STANDALONE_STORAGE_KEY, JSON.stringify(standaloneMemory.value));
+}
+/** Keep an autonomous recovery surface available after a refused cold boot.
+ * This hint carries no authority; Exit Preview explicitly removes it.
+ */
+export function clearStoredAfterAuthFailure() {
+    if (typeof window !== 'undefined' && window.parent === window)
+        return;
+    clearStored();
+}
+/** Remove the stored identity (used on expired-storage clear per D10). */
+export function clearStored() {
+    clearEntry(STORAGE_KEY);
+}
+export function clearStandaloneStored() {
+    standaloneMemory.value = null;
+    clearEntry(STANDALONE_STORAGE_KEY);
+}
+function clearEntry(key) {
+    const storage = getStorage();
+    if (storage === null)
+        return;
+    safeRemoveItem(storage, key);
+}
+/**
+ * Read the URL's `_ss_session` query param (the bootstrap signal
+ * Studio stamps when mounting the iframe at a fresh session). Returns
+ * `null` when no window is available, when the iframe is not nested,
+ * or when the param is absent / empty.
+ *
+ * Used by `createStorageCarrier` to invalidate stored identity on
+ * cross-session navigation (ADR-131 C7 Gap A — 2026-05-26).
+ */
+function readUrlSessionId() {
+    return detectPreviewSessionFromWindow().sessionId;
+}
+export function createStorageCarrier() {
+    return {
+        name: 'storage',
+        read(ctx) {
+            const autonomousTab = typeof window !== 'undefined' && window.parent === window;
+            const stored = autonomousTab ? readStandaloneStored() : readStored();
+            const clear = autonomousTab ? clearStandaloneStored : clearStored;
+            if (stored === null)
+                return { kind: 'miss' };
+            // Expired — clear and miss.
+            // An autonomous view is reauthorized on every boot by /token. A short
+            // iframe TTL must not silently turn off Preview after tab suspension.
+            if ((stored.standalone === true) !== autonomousTab)
+                return { kind: 'miss' };
+            if (!autonomousTab && stored.expiresAt <= ctx.now()) {
+                clear();
+                return { kind: 'miss' };
+            }
+            // ADR-131 C7 Gap A fix (2026-05-26): URL-sessionId vs stored-
+            // sessionId mismatch invalidates the stored identity.
+            //
+            // Symptom (Vercel-spike debug log §"Gap A"): the iframe boot
+            // sequence reads sessionStorage BEFORE the live broadcast
+            // arrives. Pre-fix the stored sessionId from a prior session
+            // (TTL 30min) could be returned even when the URL carried a
+            // FRESH `_ss_session` — the iframe then submitted preview-scoped
+            // requests against a session row Convex had already GC'd /
+            // replaced, surfacing as `INVALID_PREVIEW_SESSION`.
+            //
+            // The fix: if the URL carries a sessionId AND it differs from
+            // the stored sessionId, clear storage and return miss. The
+            // carrier chain then falls through to the URL tier (the
+            // authoritative bootstrap signal). When the URL carries no
+            // sessionId we leave storage alone (the stored entry is the
+            // best available bootstrap signal until the broadcast lands).
+            const urlSessionId = readUrlSessionId();
+            if (urlSessionId !== null && urlSessionId !== stored.sessionId) {
+                clear();
+                return { kind: 'miss' };
+            }
+            // Different project — drop and treat as miss. The expectedProjectId
+            // (from <Storystick projectId> prop) is authoritative ; a different
+            // value indicates a stale read from another preview session and
+            // must not poison the current iframe.
+            if (stored.projectId !== ctx.expectedProjectId) {
+                return { kind: 'miss' };
+            }
+            return {
+                kind: 'hit',
+                identity: {
+                    sessionId: stored.sessionId,
+                    projectId: stored.projectId,
+                    parentOrigin: stored.parentOrigin,
+                },
+            };
+        },
+    };
+}

package/dist/identity/carriers/url.d.ts

@@ -0,0 +1,19 @@
+/**
+ * ADR-116 D3 — URL carrier.
+ *
+ * Reads `_ss_session` from `window.location.search` at boot. This is
+ * the tier-3 carrier (lowest priority) ; the URL marker is a bootstrap
+ * signal only, never load-bearing post-init (D5 + D10).
+ *
+ * The URL does NOT carry a projectId — only sessionId. We trust the
+ * iframe's `<Storystick projectId>` prop as the projectId at boot ;
+ * a subsequent live broadcast confirms or replaces the identity (D10
+ * Confirm / Replace transitions).
+ *
+ * SSR / no-window contexts return `miss`. Hardened browser modes do
+ * not affect URL reads (window.location is always available where a
+ * window exists).
+ */
+import type { Carrier } from '../identity-types.js';
+export declare const URL_SESSION_PARAM = "_ss_session";
+export declare function createUrlCarrier(): Carrier;

package/dist/identity/carriers/url.js

@@ -0,0 +1,38 @@
+/**
+ * ADR-116 D3 — URL carrier.
+ *
+ * Reads `_ss_session` from `window.location.search` at boot. This is
+ * the tier-3 carrier (lowest priority) ; the URL marker is a bootstrap
+ * signal only, never load-bearing post-init (D5 + D10).
+ *
+ * The URL does NOT carry a projectId — only sessionId. We trust the
+ * iframe's `<Storystick projectId>` prop as the projectId at boot ;
+ * a subsequent live broadcast confirms or replaces the identity (D10
+ * Confirm / Replace transitions).
+ *
+ * SSR / no-window contexts return `miss`. Hardened browser modes do
+ * not affect URL reads (window.location is always available where a
+ * window exists).
+ */
+import { PREVIEW_SESSION_QUERY_PARAM, readPreviewSessionIdFromSearch, } from '../preview-identity.js';
+export const URL_SESSION_PARAM = PREVIEW_SESSION_QUERY_PARAM;
+export function createUrlCarrier() {
+    return {
+        name: 'url',
+        read(ctx) {
+            if (typeof window === 'undefined')
+                return { kind: 'miss' };
+            const sessionId = readPreviewSessionIdFromSearch(window.location.search, URL_SESSION_PARAM);
+            if (sessionId === null)
+                return { kind: 'miss' };
+            return {
+                kind: 'hit',
+                identity: {
+                    sessionId,
+                    projectId: ctx.expectedProjectId,
+                    parentOrigin: null,
+                },
+            };
+        },
+    };
+}