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

package/dist/identity/identity-state-machine.d.ts

@@ -0,0 +1,70 @@
+/**
+ * ADR-116 D4 + D10 — pure state machine + identity replacement table.
+ *
+ * The transition function is pure : input snapshot + event → output
+ * snapshot. No carriers, no postMessage, no timers, no DOM. The
+ * resolver (`resolver.ts`) wraps this with side effects.
+ *
+ * Per ADR-116 D10 the identity replacement table dispatches on
+ * (current identity, incoming identity) pairs. The full table is
+ * encoded in `transition()` below ; deviating from it produces ad-hoc
+ * bugs across boot / re-mint / cross-project / expired-storage edges.
+ */
+import type { IdentitySnapshot, PreviewIdentity, ProvisionalIdentity } from './identity-types.js';
+/**
+ * Maximum recovery attempts on `disconnected → resolving-identity`.
+ * Each retry MUST be paced by external backoff (the resolver applies
+ * exponential delay between attempts). After the budget is exhausted
+ * the resolver moves to `error`.
+ */
+export declare const MAX_RECOVERY_RETRIES = 3;
+export declare const INITIAL_SNAPSHOT: IdentitySnapshot;
+/**
+ * State machine events. Every event is dispatched by the resolver in
+ * response to either an external trigger (start, carrier hit, broadcast)
+ * or an internal one (timeout fire).
+ */
+export type IdentityEvent = {
+    type: 'start';
+} | {
+    type: 'carrier-hit';
+    /** Source carrier so the resolver tags the resolved identity. */
+    source: 'storage' | 'url';
+    identity: ProvisionalIdentity;
+    now: number;
+} | {
+    type: 'broadcast-received';
+    identity: ProvisionalIdentity;
+    now: number;
+} | {
+    type: 'carrier-timeout';
+} | {
+    type: 'auth-succeeded';
+} | {
+    type: 'auth-failed';
+    code: string;
+    message: string;
+} | {
+    type: 'disconnect';
+    code?: string;
+    message?: string;
+} | {
+    type: 'recovery-begin';
+} | {
+    type: 'recovery-exhausted';
+    code: string;
+    message: string;
+} | {
+    type: 'reset';
+};
+/**
+ * Pure transition. Illegal transitions are returned unchanged (the
+ * machine is defensive against misordered events from external
+ * sources). Throwing here would propagate to React render cycles ;
+ * the no-op pattern matches the existing PreviewAuthState reducer.
+ */
+export declare function transition(snap: IdentitySnapshot, event: IdentityEvent): IdentitySnapshot;
+/** True if a broadcast with the same identity is idempotent vs current. */
+export declare function isIdempotentBroadcast(current: PreviewIdentity | null, incoming: ProvisionalIdentity): boolean;
+/** True if a broadcast would be rejected by the projectId tie-breaker. */
+export declare function isRejectedBroadcast(current: PreviewIdentity | null, incoming: ProvisionalIdentity): boolean;

package/dist/identity/identity-state-machine.js

@@ -0,0 +1,244 @@
+/**
+ * ADR-116 D4 + D10 — pure state machine + identity replacement table.
+ *
+ * The transition function is pure : input snapshot + event → output
+ * snapshot. No carriers, no postMessage, no timers, no DOM. The
+ * resolver (`resolver.ts`) wraps this with side effects.
+ *
+ * Per ADR-116 D10 the identity replacement table dispatches on
+ * (current identity, incoming identity) pairs. The full table is
+ * encoded in `transition()` below ; deviating from it produces ad-hoc
+ * bugs across boot / re-mint / cross-project / expired-storage edges.
+ */
+/**
+ * Maximum recovery attempts on `disconnected → resolving-identity`.
+ * Each retry MUST be paced by external backoff (the resolver applies
+ * exponential delay between attempts). After the budget is exhausted
+ * the resolver moves to `error`.
+ */
+export const MAX_RECOVERY_RETRIES = 3;
+export const INITIAL_SNAPSHOT = Object.freeze({
+    state: 'idle',
+    identity: null,
+    error: null,
+    retryCount: 0,
+});
+/**
+ * Pure transition. Illegal transitions are returned unchanged (the
+ * machine is defensive against misordered events from external
+ * sources). Throwing here would propagate to React render cycles ;
+ * the no-op pattern matches the existing PreviewAuthState reducer.
+ */
+export function transition(snap, event) {
+    // `error` is terminal — only `reset` clears it.
+    if (snap.state === 'error' && event.type !== 'reset')
+        return snap;
+    switch (event.type) {
+        case 'start': {
+            if (snap.state !== 'idle' && snap.state !== 'disconnected')
+                return snap;
+            return { ...snap, state: 'resolving-identity' };
+        }
+        case 'reset': {
+            return { ...INITIAL_SNAPSHOT };
+        }
+        case 'carrier-hit': {
+            if (snap.state !== 'resolving-identity')
+                return snap;
+            const identity = {
+                ...event.identity,
+                source: event.source,
+                epoch: 0,
+                resolvedAt: event.now,
+                carrierAttempts: Object.freeze([
+                    { carrier: event.source, result: 'hit' },
+                ]),
+            };
+            return {
+                ...snap,
+                state: 'handshaking',
+                identity,
+            };
+        }
+        case 'broadcast-received': {
+            return applyBroadcast(snap, event.identity, event.now);
+        }
+        case 'carrier-timeout': {
+            // Only meaningful while still resolving. If a carrier hit fired
+            // before the timeout, the state already moved to handshaking and
+            // the timeout no-ops.
+            if (snap.state !== 'resolving-identity')
+                return snap;
+            return {
+                ...snap,
+                state: 'error',
+                error: {
+                    code: 'identity_carrier_timeout',
+                    message: 'Preview identity could not be established. Reopen the document in Storystick Studio to retry.',
+                },
+            };
+        }
+        case 'auth-succeeded': {
+            if (snap.state !== 'handshaking')
+                return snap;
+            return { ...snap, state: 'authenticated', retryCount: 0 };
+        }
+        case 'auth-failed': {
+            if (snap.state !== 'handshaking')
+                return snap;
+            return {
+                ...snap,
+                state: 'error',
+                error: { code: event.code, message: event.message },
+            };
+        }
+        case 'disconnect': {
+            // The resolver may decide to recover (transition recovery-begin).
+            // From a connected-ish state the disconnect always lands.
+            if (snap.state !== 'authenticated' &&
+                snap.state !== 'handshaking' &&
+                snap.state !== 'disconnected') {
+                return snap;
+            }
+            return {
+                ...snap,
+                state: 'disconnected',
+                error: event.code
+                    ? { code: event.code, message: event.message ?? event.code }
+                    : snap.error,
+            };
+        }
+        case 'recovery-begin': {
+            if (snap.state !== 'disconnected')
+                return snap;
+            if (snap.retryCount >= MAX_RECOVERY_RETRIES)
+                return snap;
+            return {
+                ...snap,
+                state: 'resolving-identity',
+                retryCount: snap.retryCount + 1,
+                error: null,
+            };
+        }
+        case 'recovery-exhausted': {
+            if (snap.state !== 'disconnected')
+                return snap;
+            return {
+                ...snap,
+                state: 'error',
+                error: { code: event.code, message: event.message },
+            };
+        }
+        default: {
+            // Exhaustiveness — TypeScript flags missing cases.
+            return snap;
+        }
+    }
+}
+/**
+ * ADR-116 D10 — identity replacement table for incoming Studio
+ * broadcasts. Encoded as a single function so the table is testable
+ * end-to-end and impossible to bypass.
+ *
+ *  | current identity                       | incoming                       | action      |
+ *  |----------------------------------------|--------------------------------|-------------|
+ *  | null (resolving-identity)              | broadcast                      | confirm     |
+ *  | matches sessionId + projectId          | broadcast                      | no-op       |
+ *  | same projectId, different sessionId    | broadcast                      | replace ++  |
+ *  | different projectId                    | broadcast                      | reject      |
+ *  | provisional storage/url, broadcast same| broadcast confirms             | promote     |
+ *
+ *  Atomicity (codex R6) : each call mutates the snapshot atomically.
+ *  No intermediate state where `identity.sessionId` is mismatched with
+ *  `state` is visible to subscribers.
+ */
+function applyBroadcast(snap, incoming, now) {
+    // Reject on idle/error (state machine is closed to broadcasts there).
+    if (snap.state === 'idle' || snap.state === 'error')
+        return snap;
+    const current = snap.identity;
+    if (current === null) {
+        // Confirm — first identity to arrive.
+        const identity = {
+            ...incoming,
+            source: 'broadcast',
+            epoch: 0,
+            resolvedAt: now,
+            carrierAttempts: Object.freeze([
+                { carrier: 'broadcast', result: 'hit' },
+            ]),
+        };
+        return {
+            ...snap,
+            // From `resolving-identity` → handshaking ; from disconnected
+            // (mid-recovery) → handshaking too.
+            state: 'handshaking',
+            identity,
+            error: null,
+        };
+    }
+    // Different projectId — reject. The `<Storystick projectId>` prop is
+    // authoritative ; a divergent projectId indicates either a Studio bug
+    // or a hostile origin that passed the allowlist. Keep current
+    // identity unchanged.
+    if (current.projectId !== incoming.projectId) {
+        return snap;
+    }
+    // Same sessionId + same projectId — idempotent no-op. The resolver
+    // refreshes the storage TTL externally (carrier-hit side effect).
+    if (current.sessionId === incoming.sessionId) {
+        // Promote provisional → broadcast-sourced for the audit trail. The
+        // tuple itself is unchanged so subscribers do not need to re-render
+        // identity-derived state. But if parentOrigin was null (came from
+        // storage/url) and the broadcast carries one, populate it.
+        if (current.source !== 'broadcast' ||
+            (current.parentOrigin === null && incoming.parentOrigin !== null)) {
+            const promoted = {
+                ...current,
+                parentOrigin: incoming.parentOrigin ?? current.parentOrigin,
+                source: 'broadcast',
+            };
+            return {
+                ...snap,
+                // Stay in current state ; promotion is a tag-only mutation
+                // when already past resolving-identity. If still resolving-
+                // identity (rare — provisional carrier hit then matching
+                // broadcast in the same boot), advance to handshaking.
+                state: snap.state === 'resolving-identity' ? 'handshaking' : snap.state,
+                identity: promoted,
+            };
+        }
+        return snap;
+    }
+    // Different sessionId, same projectId — REPLACE (new epoch).
+    const nextEpoch = {
+        ...incoming,
+        source: 'broadcast',
+        epoch: current.epoch + 1,
+        resolvedAt: now,
+        carrierAttempts: Object.freeze([
+            { carrier: 'broadcast', result: 'hit' },
+        ]),
+    };
+    return {
+        ...snap,
+        // Replace transitions the channel back to handshaking — the auth
+        // handshake must rerun against the new sessionId.
+        state: 'handshaking',
+        identity: nextEpoch,
+        error: null,
+    };
+}
+/** True if a broadcast with the same identity is idempotent vs current. */
+export function isIdempotentBroadcast(current, incoming) {
+    if (current === null)
+        return false;
+    return (current.sessionId === incoming.sessionId &&
+        current.projectId === incoming.projectId);
+}
+/** True if a broadcast would be rejected by the projectId tie-breaker. */
+export function isRejectedBroadcast(current, incoming) {
+    if (current === null)
+        return false;
+    return current.projectId !== incoming.projectId;
+}

package/dist/identity/identity-types.d.ts

@@ -0,0 +1,192 @@
+/**
+ * ADR-116 — Preview Identity Foundation v2.
+ *
+ * Framework-agnostic identity primitive consumed by every framework
+ * adapter. The URL marker `_ss_session` becomes a boot-bootstrap signal
+ * only ; identity itself is resolved via a carrier chain (live Studio
+ * broadcast > sessionStorage > URL marker) and persists for the iframe
+ * lifecycle.
+ *
+ * This module is pure : it imports no React, no Next, no Convex, no
+ * DOM. The carriers and resolver build on these types. The framework
+ * adapter contract (`FrameworkAdapter`) is intentionally brutally
+ * small — three methods — so future adapters (Astro, SvelteKit, Vue,
+ * plain HTML) can ship without rewriting the resolver.
+ *
+ * Why core, not adapter : every framework adapter needs the same
+ * answer to *"am I in preview + what is my session?"*. Putting the
+ * resolver here means future adapters consume the same answer with no
+ * duplication and the URL-marker assumption (load-bearing across 7
+ * sites pre-ADR-116) is eliminated by construction.
+ */
+/**
+ * Resolved preview identity for an iframe boot epoch.
+ *
+ * IMMUTABLE per `sessionId` (ADR-116 D1, refined per codex R6 #1). A
+ * new `sessionId` from Studio produces a new epoch with an incremented
+ * `epoch` counter. The identity is the single source of truth for the
+ * iframe lifetime — every consumer reads the same tuple.
+ */
+export interface PreviewIdentity {
+    /** Studio-minted preview session id (uuid-ish). */
+    sessionId: string;
+    /** Project shortId. Authoritative tie-breaker per D8. */
+    projectId: string;
+    /**
+     * Parent Studio origin. `null` during the bootstrap window when the
+     * identity came from the URL or sessionStorage carrier (carriers
+     * cannot know the parent's origin without postMessage exchange).
+     * Populated once a `session-broadcast` envelope arrives and the
+     * iframe locks the parent origin. The split between provisional vs
+     * connected channel surfaces here (codex R6 #1).
+     */
+    parentOrigin: string | null;
+    /** Which carrier produced this identity. */
+    source: 'broadcast' | 'request' | 'storage' | 'url';
+    /**
+     * Epoch counter, incremented on every Replace transition (D10).
+     * Forward-compat with the ADR-108 epoch follow-up — Studio
+     * dispatchers can correlate envelopes against the latest known
+     * epoch without protocol changes when that ADR lands.
+     */
+    epoch: number;
+    /** Wall-clock instant the identity was resolved (debug + audit). */
+    resolvedAt: number;
+    /**
+     * Per-carrier attempt outcomes from the resolver's read pass.
+     * Frozen at resolve time ; subsequent broadcasts do NOT mutate it
+     * (the audit trail is the boot story, not the full history).
+     */
+    carrierAttempts: ReadonlyArray<CarrierAttempt>;
+}
+export interface CarrierAttempt {
+    carrier: 'broadcast' | 'storage' | 'url';
+    result: 'hit' | 'miss' | 'error';
+}
+/**
+ * State machine values (ADR-116 D4). The runtime cell on `globalThis`
+ * (PR4 wiring) holds the latest state plus the immutable identity.
+ *
+ *  - `idle` — initial, no resolution attempted.
+ *  - `resolving-identity` — carriers being consulted ; envelope
+ *    listeners attached ; the carrier-miss timeout is armed.
+ *  - `handshaking` — identity resolved (provisional or live) ; auth
+ *    handshake in progress. PR4 wires `notifyAuthSucceeded()` to
+ *    transition to `authenticated`.
+ *  - `authenticated` — channel live ; ADR-108 envelope flow takes
+ *    over.
+ *  - `disconnected` — operational signal indicates parent connection
+ *    lost ; recovery attempts re-handshake (rate-limited).
+ *  - `error` — terminal ; recoverable only by full reload.
+ */
+export type IdentityResolverState = 'idle' | 'resolving-identity' | 'handshaking' | 'authenticated' | 'disconnected' | 'error';
+/**
+ * Resolver snapshot. Subscribers receive the full snapshot on every
+ * transition so they can render any state without separate lookups.
+ */
+export interface IdentitySnapshot {
+    state: IdentityResolverState;
+    identity: PreviewIdentity | null;
+    /** Populated only when `state === 'error'`. */
+    error: {
+        code: string;
+        message: string;
+    } | null;
+    /**
+     * Recovery retry budget consumed (0 on cold boot, up to 3). Visible
+     * for tests and the eventual UI surface ("preview reconnecting…").
+     */
+    retryCount: number;
+}
+/**
+ * Context handed to carriers when the resolver consults them. Pure
+ * values only — carriers don't reach into the resolver.
+ */
+export interface CarrierContext {
+    /**
+     * Authoritative projectId from the `<Storystick projectId>` prop.
+     * Carriers MUST reject identity for any other project. D8 tie-
+     * breaker.
+     */
+    expectedProjectId: string;
+    /** Wall clock — injectable for tests. */
+    now: () => number;
+}
+/** Result of a synchronous carrier read. */
+export type CarrierResult = {
+    kind: 'hit';
+    identity: ProvisionalIdentity;
+} | {
+    kind: 'miss';
+} | {
+    kind: 'error';
+    reason: string;
+};
+/**
+ * Identity shape carriers produce (no `epoch`, no `resolvedAt`, no
+ * `carrierAttempts` — those are stamped by the resolver).
+ */
+export interface ProvisionalIdentity {
+    sessionId: string;
+    projectId: string;
+    /** Carriers cannot know the parent origin until a broadcast lands. */
+    parentOrigin: string | null;
+}
+/**
+ * A carrier reads identity from one substrate (URL, sessionStorage,
+ * postMessage). The resolver consults them in strict precedence order
+ * (D3). The interface is synchronous because all known substrates are
+ * synchronous reads ; the resolver's async surface comes from the
+ * timeout window for broadcast arrival, not from carrier reads.
+ */
+export interface Carrier {
+    readonly name: 'broadcast' | 'storage' | 'url';
+    read(ctx: CarrierContext): CarrierResult;
+}
+/**
+ * Snapshot of the current location surface in framework-agnostic form.
+ * Used by the framework adapter contract.
+ */
+export interface FrameworkLocation {
+    readonly pathname: string;
+    readonly search: string;
+    readonly hash: string;
+}
+/**
+ * Framework adapter contract (ADR-116 D6). Brutally small — three
+ * methods — so future adapters (Astro / SvelteKit / Vue / plain HTML)
+ * can ship in 1–2 days each from the settled contract. The Next
+ * adapter implements this in PR4. The core test-adapter
+ * (`__test-adapter.ts`) implements it for unit tests.
+ *
+ * Adapters do NOT need a separate `dispose()` method (plan-eng-review
+ * A5) : the accumulated unsubscribes from `subscribeToLocation` plus
+ * the state machine's `disconnected` event are sufficient teardown
+ * signals.
+ */
+export interface FrameworkAdapter {
+    /**
+     * Same-origin absolute path. App Router → `router.replace` ; Pages
+     * Router → `router.replace` ; plain HTML → `location.assign` as
+     * fallback. `opts.refresh === true` invalidates the App Router
+     * client Router Cache via `router.refresh()` ; ignored by routers
+     * without an equivalent surface.
+     */
+    navigateTo(path: string, opts?: {
+        refresh?: boolean;
+    }): void;
+    /**
+     * Subscribe to client-side route changes. Returns an unsubscribe
+     * function. The resolver invokes the unsubscribe on teardown
+     * (transition to `disconnected`, runtime `dispose()`, framework HMR
+     * re-mount).
+     */
+    subscribeToLocation(cb: (loc: FrameworkLocation) => void): () => void;
+    /**
+     * Snapshot read for boot-time emission + reverse-channel echo
+     * classification.
+     */
+    getCurrentLocation(): FrameworkLocation;
+}
+/** Listener attached to the resolver via `subscribe`. */
+export type IdentityListener = (snapshot: IdentitySnapshot) => void;

package/dist/identity/identity-types.js

@@ -0,0 +1,22 @@
+/**
+ * ADR-116 — Preview Identity Foundation v2.
+ *
+ * Framework-agnostic identity primitive consumed by every framework
+ * adapter. The URL marker `_ss_session` becomes a boot-bootstrap signal
+ * only ; identity itself is resolved via a carrier chain (live Studio
+ * broadcast > sessionStorage > URL marker) and persists for the iframe
+ * lifecycle.
+ *
+ * This module is pure : it imports no React, no Next, no Convex, no
+ * DOM. The carriers and resolver build on these types. The framework
+ * adapter contract (`FrameworkAdapter`) is intentionally brutally
+ * small — three methods — so future adapters (Astro, SvelteKit, Vue,
+ * plain HTML) can ship without rewriting the resolver.
+ *
+ * Why core, not adapter : every framework adapter needs the same
+ * answer to *"am I in preview + what is my session?"*. Putting the
+ * resolver here means future adapters consume the same answer with no
+ * duplication and the URL-marker assumption (load-bearing across 7
+ * sites pre-ADR-116) is eliminated by construction.
+ */
+export {};

package/dist/identity/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * ADR-116 — preview identity foundation barrel.
+ *
+ * Re-exports the public surface so consumers (PR4 `<Storystick>` + PR5
+ * adapter migrations + future framework adapters) import from one
+ * place.
+ */
+export type { PreviewIdentity, ProvisionalIdentity, CarrierAttempt, Carrier, CarrierContext, CarrierResult, IdentityResolverState, IdentitySnapshot, IdentityListener, FrameworkAdapter, FrameworkLocation, } from './identity-types.js';
+export { INITIAL_SNAPSHOT, MAX_RECOVERY_RETRIES, transition, isIdempotentBroadcast, isRejectedBroadcast, type IdentityEvent, } from './identity-state-machine.js';
+export { createIdentityResolver, DEFAULT_CARRIER_TIMEOUT_MS, RECOVERY_BACKOFF_MS, STORAGE_KEY, type CreateResolverOpts, type IdentityResolver, } from './resolver.js';
+export { createUrlCarrier, URL_SESSION_PARAM } from './carriers/url.js';
+export { createStorageCarrier, readStored, writeStored, clearStored, STORAGE_TTL_MS, type StoredIdentityV1, } from './carriers/storage.js';
+export { buildSessionRequest, parseInboundBroadcast, attachBroadcastListener, postSessionRequest, } from './carriers/postmessage.js';
+export { createTestAdapter } from './__test-adapter.js';
+export type { TestAdapterPair, TestAdapterHarness } from './__test-adapter.js';
+export { PREVIEW_SESSION_QUERY_PARAM, PREVIEW_VARIANT_QUERY_PARAM, PREVIEW_RELEASE_QUERY_PARAM, hasPreviewSessionParam, detectPreviewSessionFromWindow, isPreviewIdentity, readPreviewIdentity, readPreviewIdentitySessionId, readPreviewIdentitySessionIdFromSource, readPreviewSessionIdFromSearch, readPreviewVariantIdFromSearch, normalizePreviewVariantId, readPreviewReleaseIdFromSearch, normalizePreviewReleaseId, type PreviewSessionDetection, type PreviewIdentitySource, } from './preview-identity.js';
+export { PreviewScopeConflictError, createPreviewScope, previewScopeKey, readPreviewScopeFromSearch, writePreviewScopeToSearchParams, type PreviewScope, } from './preview-scope.js';
+export { PREVIEW_DRAFT_QUERY_PARAM, readPreviewDraftDocumentId, previewDraftHref } from './preview-draft.js';

package/dist/identity/index.js

@@ -0,0 +1,16 @@
+/**
+ * ADR-116 — preview identity foundation barrel.
+ *
+ * Re-exports the public surface so consumers (PR4 `<Storystick>` + PR5
+ * adapter migrations + future framework adapters) import from one
+ * place.
+ */
+export { INITIAL_SNAPSHOT, MAX_RECOVERY_RETRIES, transition, isIdempotentBroadcast, isRejectedBroadcast, } from './identity-state-machine.js';
+export { createIdentityResolver, DEFAULT_CARRIER_TIMEOUT_MS, RECOVERY_BACKOFF_MS, STORAGE_KEY, } from './resolver.js';
+export { createUrlCarrier, URL_SESSION_PARAM } from './carriers/url.js';
+export { createStorageCarrier, readStored, writeStored, clearStored, STORAGE_TTL_MS, } from './carriers/storage.js';
+export { buildSessionRequest, parseInboundBroadcast, attachBroadcastListener, postSessionRequest, } from './carriers/postmessage.js';
+export { createTestAdapter } from './__test-adapter.js';
+export { PREVIEW_SESSION_QUERY_PARAM, PREVIEW_VARIANT_QUERY_PARAM, PREVIEW_RELEASE_QUERY_PARAM, hasPreviewSessionParam, detectPreviewSessionFromWindow, isPreviewIdentity, readPreviewIdentity, readPreviewIdentitySessionId, readPreviewIdentitySessionIdFromSource, readPreviewSessionIdFromSearch, readPreviewVariantIdFromSearch, normalizePreviewVariantId, readPreviewReleaseIdFromSearch, normalizePreviewReleaseId, } from './preview-identity.js';
+export { PreviewScopeConflictError, createPreviewScope, previewScopeKey, readPreviewScopeFromSearch, writePreviewScopeToSearchParams, } from './preview-scope.js';
+export { PREVIEW_DRAFT_QUERY_PARAM, readPreviewDraftDocumentId, previewDraftHref } from './preview-draft.js';

package/dist/identity/preview-cookie.d.ts

@@ -0,0 +1,9 @@
+/** Public names only. Neither the name nor the presence signal grants access. */
+export declare function scopedPreviewCookieName(prefix: string, scope: {
+    projectId: string;
+    requestOrigin: string;
+}): string;
+export declare function previewPresenceCookieName(scope: {
+    projectId: string;
+    requestOrigin: string;
+}): string;

package/dist/identity/preview-cookie.js

@@ -0,0 +1,12 @@
+/** Public names only. Neither the name nor the presence signal grants access. */
+export function scopedPreviewCookieName(prefix, scope) {
+    // Browser cookies do not partition ports; the name must do so explicitly.
+    const bytes = new TextEncoder().encode(JSON.stringify([scope.projectId, new URL(scope.requestOrigin).origin]));
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return `${prefix}_${btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '')}`;
+}
+export function previewPresenceCookieName(scope) {
+    return scopedPreviewCookieName('__storystick_preview_present', scope);
+}

package/dist/identity/preview-draft.d.ts

@@ -0,0 +1,6 @@
+/** Public request destination, never an authorization or a sticky view setting.
+ * Native links omit it; Back/Forward and reload retain the selected document. */
+export declare const PREVIEW_DRAFT_QUERY_PARAM = "_ss_draft";
+export declare function readPreviewDraftDocumentId(search: string): string | null;
+/** Sets the destination explicitly; never inherits the current page's draft. */
+export declare function previewDraftHref(pathname: string, documentId?: string | null): string;

package/dist/identity/preview-draft.js

@@ -0,0 +1,25 @@
+/** Public request destination, never an authorization or a sticky view setting.
+ * Native links omit it; Back/Forward and reload retain the selected document. */
+export const PREVIEW_DRAFT_QUERY_PARAM = '_ss_draft';
+export function readPreviewDraftDocumentId(search) {
+    const values = new URLSearchParams(search).getAll(PREVIEW_DRAFT_QUERY_PARAM);
+    if (values.length === 0)
+        return null;
+    if (values.length !== 1 || !/^[A-Za-z0-9_-]{1,180}$/.test(values[0])) {
+        throw new Error('PREVIEW_DRAFT_DESTINATION_INVALID');
+    }
+    return values[0];
+}
+/** Sets the destination explicitly; never inherits the current page's draft. */
+export function previewDraftHref(pathname, documentId) {
+    const url = new URL(pathname, 'https://preview.invalid');
+    if (!pathname.startsWith('/') || url.origin !== 'https://preview.invalid') {
+        throw new Error('PREVIEW_DESTINATION_INVALID');
+    }
+    url.searchParams.delete(PREVIEW_DRAFT_QUERY_PARAM);
+    if (documentId != null) {
+        url.searchParams.set(PREVIEW_DRAFT_QUERY_PARAM, documentId);
+        readPreviewDraftDocumentId(url.search);
+    }
+    return url.pathname + url.search + url.hash;
+}

package/dist/identity/preview-identity.d.ts

@@ -0,0 +1,28 @@
+export { PREVIEW_SESSION_QUERY_PARAM, readPreviewSessionIdFromSearch, hasPreviewSessionParam } from './session-query.js';
+import type { PreviewIdentity } from './identity-types.js';
+export declare const PREVIEW_VARIANT_QUERY_PARAM = "_ss_variant";
+export declare const PREVIEW_RELEASE_QUERY_PARAM = "_ss_release";
+export interface PreviewIdentitySource {
+    getIdentity?: () => PreviewIdentity | null | undefined;
+}
+export interface PreviewSessionDetection {
+    active: boolean;
+    sessionId: string | null;
+    variantId: string | null;
+    releaseId: string | null;
+}
+type PreviewWindowLike = {
+    parent: unknown;
+    location?: {
+        search?: string;
+    };
+};
+export declare function isPreviewIdentity(value: unknown): value is PreviewIdentity;
+export declare function readPreviewIdentitySessionId(identity: PreviewIdentity | null | undefined): string | null;
+export declare function readPreviewIdentity(source: PreviewIdentitySource | null | undefined): PreviewIdentity | null;
+export declare function readPreviewIdentitySessionIdFromSource(source: PreviewIdentitySource | null | undefined): string | null;
+export declare function readPreviewVariantIdFromSearch(search: string, paramName?: string): string | null;
+export declare function normalizePreviewVariantId(value: string | null | undefined): string | null;
+export declare function readPreviewReleaseIdFromSearch(search: string, paramName?: string): string | null;
+export declare function normalizePreviewReleaseId(value: string | null | undefined): string | null;
+export declare function detectPreviewSessionFromWindow(win?: PreviewWindowLike | null | undefined, paramName?: string): PreviewSessionDetection;