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

package/dist/grant-coordinator.js

@@ -0,0 +1,329 @@
+import { transitionPreviewGrantLifecycle, } from "./grant-lifecycle.js";
+import { previewPerfNow, recordPreviewPerfMeasure, recordPreviewPerfMetric } from './runtime/perf-metrics.js';
+export const PREVIEW_TOKEN_ROUTE = "/api/storystick/preview/token";
+export const PREVIEW_GRANT_RETRY_BACKOFF_MS = [
+    1_000, 2_000, 5_000, 10_000, 30_000,
+];
+const MIN_REFRESH_DELAY_MS = 1_000;
+export class PreviewGrantRequestError extends Error {
+    code;
+    retryable;
+    retryAfterMs;
+    constructor(args) {
+        super(args.message);
+        this.name = "PreviewGrantRequestError";
+        this.code = args.code;
+        this.retryable = args.retryable;
+        this.retryAfterMs = args.retryAfterMs ?? null;
+    }
+}
+export async function acquirePreviewBrowserGrant(args) {
+    const fetchFn = args.fetchFn ?? fetch;
+    const url = new URL(args.tokenRoute ?? PREVIEW_TOKEN_ROUTE, window.location.origin);
+    url.searchParams.set("_ss_session", args.sessionId);
+    let response;
+    try {
+        response = await fetchFn(url.toString(), {
+            method: "POST",
+            credentials: "same-origin",
+            cache: "no-store",
+            headers: { Accept: "application/json" },
+            signal: args.signal,
+        });
+    }
+    catch (error) {
+        if (args.signal.aborted)
+            throw error;
+        throw new PreviewGrantRequestError({
+            code: "PREVIEW_TOKEN_UNAVAILABLE",
+            message: error instanceof Error
+                ? error.message
+                : "Preview token route unavailable.",
+            retryable: true,
+        });
+    }
+    let body = null;
+    try {
+        body = await response.json();
+    }
+    catch {
+        body = null;
+    }
+    const record = typeof body === "object" && body !== null && !Array.isArray(body)
+        ? body
+        : null;
+    if (!response.ok) {
+        const errorRecord = typeof record?.error === "object" &&
+            record.error !== null &&
+            !Array.isArray(record.error)
+            ? record.error
+            : null;
+        const retryAfterHeader = response.headers.get("Retry-After");
+        const parsedRetryAfter = retryAfterHeader === null ? NaN : Number(retryAfterHeader);
+        const retryable = typeof errorRecord?.retryable === "boolean"
+            ? errorRecord.retryable
+            : typeof errorRecord?.recoverable === "boolean"
+                ? errorRecord.recoverable
+                : response.status === 408 ||
+                    response.status === 429 ||
+                    response.status >= 500;
+        throw new PreviewGrantRequestError({
+            code: typeof errorRecord?.code === "string"
+                ? errorRecord.code
+                : retryable
+                    ? "PREVIEW_TOKEN_UNAVAILABLE"
+                    : "PREVIEW_TOKEN_DENIED",
+            message: typeof errorRecord?.message === "string"
+                ? errorRecord.message
+                : retryable
+                    ? "Preview access is temporarily unavailable."
+                    : "Preview access was denied.",
+            retryable,
+            retryAfterMs: Number.isFinite(parsedRetryAfter)
+                ? Math.max(0, parsedRetryAfter * 1_000)
+                : null,
+        });
+    }
+    const responseKeys = record === null ? [] : Object.keys(record).sort();
+    if (record === null ||
+        responseKeys.join("\0") !==
+            ["expiresAt", "projectId", "refreshAfter", "sessionId", "token"]
+                .sort()
+                .join("\0") ||
+        typeof record.token !== "string" ||
+        record.token.length === 0 ||
+        typeof record.expiresAt !== "number" ||
+        !Number.isFinite(record.expiresAt) ||
+        typeof record.refreshAfter !== "number" ||
+        !Number.isFinite(record.refreshAfter) ||
+        record.sessionId !== args.sessionId ||
+        record.projectId !== args.projectId) {
+        throw new PreviewGrantRequestError({
+            code: "PREVIEW_TOKEN_PROTOCOL_INVALID",
+            message: "Preview token route returned an invalid response.",
+            retryable: false,
+        });
+    }
+    return {
+        token: record.token,
+        expiresAt: record.expiresAt,
+        refreshAfter: record.refreshAfter,
+        sessionId: record.sessionId,
+        projectId: record.projectId,
+    };
+}
+export function createPreviewGrantCoordinator(args) {
+    const now = args.now ?? Date.now;
+    const random = args.random ?? Math.random;
+    const setT = args.setTimeoutFn ?? setTimeout;
+    const clearT = args.clearTimeoutFn ?? clearTimeout;
+    const win = args.windowRef ?? (typeof window === "undefined" ? undefined : window);
+    const acquire = args.acquire ?? acquirePreviewBrowserGrant;
+    let lifecycle = transitionPreviewGrantLifecycle(null, {
+        type: "start",
+        sessionId: args.sessionId,
+        at: now(),
+    });
+    let stopped = false;
+    let timer = null;
+    let controller = null;
+    let flight = 0;
+    let hasGrant = false;
+    let announced = false;
+    let admissionInvalidated = false;
+    let supersededAttempts = 0;
+    let channel = null;
+    const publish = () => args.onLifecycle(lifecycle);
+    const clearTimer = () => {
+        if (timer === null)
+            return;
+        clearT(timer);
+        timer = null;
+    };
+    const schedule = (delayMs, callback) => {
+        clearTimer();
+        timer = setT(callback, Math.max(MIN_REFRESH_DELAY_MS, delayMs));
+    };
+    const retryDelay = (attempt, override) => {
+        if (override !== null)
+            return override;
+        const index = Math.min(Math.max(0, attempt - 1), PREVIEW_GRANT_RETRY_BACKOFF_MS.length - 1);
+        const base = PREVIEW_GRANT_RETRY_BACKOFF_MS[index];
+        return Math.round(base * (0.8 + random() * 0.4));
+    };
+    const attemptAcquire = () => {
+        if (stopped || controller !== null)
+            return;
+        const currentFlight = ++flight;
+        controller = new AbortController();
+        const signal = controller.signal;
+        const startedAt = win ? previewPerfNow(win) : 0;
+        let responseObserved = false;
+        if (win)
+            recordPreviewPerfMetric(win, { name: 'preview.grant.request' });
+        void acquire({
+            sessionId: args.sessionId,
+            projectId: args.projectId,
+            ...(args.tokenRoute !== undefined ? { tokenRoute: args.tokenRoute } : {}),
+            signal,
+        })
+            .then((grant) => {
+            responseObserved = true;
+            if (win)
+                recordPreviewPerfMeasure(win, 'preview.grant.response', startedAt, { ok: true, aborted: signal.aborted });
+            if (stopped || signal.aborted || currentFlight !== flight)
+                return;
+            controller = null;
+            if (admissionInvalidated) {
+                admissionInvalidated = false;
+                attemptAcquire();
+                return;
+            }
+            hasGrant = true;
+            supersededAttempts = 0;
+            args.onGrant(grant);
+            if (!announced) {
+                announced = true;
+                channel?.postMessage('admission-changed');
+            }
+            if (lifecycle.phase === "reconnecting" && lifecycle.cause === "grant") {
+                lifecycle = transitionPreviewGrantLifecycle(lifecycle, {
+                    type: "ready",
+                    at: now(),
+                    generation: args.generation,
+                });
+                publish();
+            }
+            schedule(grant.refreshAfter - now(), attemptAcquire);
+        })
+            .catch((error) => {
+            if (win && !responseObserved)
+                recordPreviewPerfMeasure(win, 'preview.grant.response', startedAt, { ok: false, aborted: signal.aborted });
+            if (stopped || signal.aborted || currentFlight !== flight)
+                return;
+            controller = null;
+            if (admissionInvalidated) {
+                admissionInvalidated = false;
+                attemptAcquire();
+                return;
+            }
+            const normalized = error instanceof PreviewGrantRequestError
+                ? error
+                : new PreviewGrantRequestError({
+                    code: "PREVIEW_TOKEN_UNAVAILABLE",
+                    message: error instanceof Error
+                        ? error.message
+                        : "Preview token unavailable.",
+                    retryable: true,
+                });
+            if (normalized.code === 'PREVIEW_ADMISSION_SUPERSEDED')
+                supersededAttempts++;
+            if (!normalized.retryable || supersededAttempts >= 3) {
+                lifecycle = transitionPreviewGrantLifecycle(lifecycle, {
+                    type: "blocked",
+                    at: now(),
+                    code: normalized.code,
+                    message: normalized.message,
+                });
+                publish();
+                return;
+            }
+            lifecycle = transitionPreviewGrantLifecycle(lifecycle, {
+                type: "retry",
+                at: now(),
+                cause: "grant",
+            });
+            publish();
+            schedule(retryDelay(lifecycle.attempt, normalized.retryAfterMs), attemptAcquire);
+        });
+    };
+    const retryNow = () => {
+        if (stopped || lifecycle.phase === "blocked")
+            return;
+        clearTimer();
+        if (controller === null)
+            attemptAcquire();
+    };
+    const onWake = () => retryNow();
+    return {
+        start() {
+            if (stopped)
+                return;
+            publish();
+            const Channel = win?.BroadcastChannel;
+            if (Channel) {
+                try {
+                    channel = new Channel(`storystick:preview:${args.projectId}`);
+                    channel.onmessage = () => {
+                        // Hints never grant access. Do not lose one while an older request is in flight.
+                        if (controller) {
+                            admissionInvalidated = true;
+                            return;
+                        }
+                        if (lifecycle.phase === 'blocked') {
+                            lifecycle = transitionPreviewGrantLifecycle(null, { type: 'start', sessionId: args.sessionId, at: now() });
+                            supersededAttempts = 0;
+                            publish();
+                        }
+                        retryNow();
+                    };
+                }
+                catch { /* Optional invalidation hint; waking/renewal still reacquires authority. */ }
+            }
+            win?.addEventListener("online", onWake);
+            win?.addEventListener("focus", onWake);
+            win?.addEventListener("pageshow", onWake);
+            attemptAcquire();
+        },
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            clearTimer();
+            controller?.abort();
+            controller = null;
+            channel?.close();
+            channel = null;
+            win?.removeEventListener("online", onWake);
+            win?.removeEventListener("focus", onWake);
+            win?.removeEventListener("pageshow", onWake);
+        },
+        markReady() {
+            if (stopped || !hasGrant || lifecycle.phase === "ready")
+                return;
+            lifecycle = transitionPreviewGrantLifecycle(lifecycle, {
+                type: "ready",
+                at: now(),
+                generation: args.generation,
+            });
+            publish();
+        },
+        reportTransientFailure(cause) {
+            if (stopped || lifecycle.phase === "blocked")
+                return;
+            lifecycle = transitionPreviewGrantLifecycle(lifecycle, {
+                type: "retry",
+                at: now(),
+                cause,
+            });
+            publish();
+            retryNow();
+        },
+        reportBlocked(code, message) {
+            if (stopped || lifecycle.phase === "blocked")
+                return;
+            lifecycle = transitionPreviewGrantLifecycle(lifecycle, {
+                type: "blocked",
+                at: now(),
+                code,
+                message,
+            });
+            publish();
+            clearTimer();
+            controller?.abort();
+            controller = null;
+        },
+        retryNow,
+        getLifecycle: () => lifecycle,
+    };
+}

package/dist/grant-lifecycle.d.ts

@@ -0,0 +1,52 @@
+import type { PreviewLifecyclePhase } from '@storystick/transport-allowlist';
+export type PreviewGrantFailureCause = 'grant' | 'transport' | 'subscription';
+/** Compatibility projection consumed by existing framework adapters. */
+export type LegacyPreviewAuthState = 'idle' | 'authenticating' | 'authenticated' | 'refreshing' | 'error';
+export type PreviewGrantLifecycle = {
+    phase: 'connecting';
+    sessionId: string;
+    attempt: number;
+    since: number;
+} | {
+    phase: 'ready';
+    sessionId: string;
+    attempt: 0;
+    since: number;
+    readyAt: number;
+    generation: number;
+} | {
+    phase: 'reconnecting';
+    sessionId: string;
+    attempt: number;
+    since: number;
+    lastReadyAt: number;
+    cause: PreviewGrantFailureCause;
+} | {
+    phase: 'blocked';
+    sessionId: string;
+    attempt: number;
+    since: number;
+    code: string;
+    message: string;
+};
+export type PreviewGrantLifecycleEvent = {
+    type: 'start';
+    sessionId: string;
+    at: number;
+} | {
+    type: 'retry';
+    at: number;
+    cause: PreviewGrantFailureCause;
+} | {
+    type: 'ready';
+    at: number;
+    generation: number;
+} | {
+    type: 'blocked';
+    at: number;
+    code: string;
+    message: string;
+};
+export declare function transitionPreviewGrantLifecycle(current: PreviewGrantLifecycle | null, event: PreviewGrantLifecycleEvent): PreviewGrantLifecycle;
+export declare function legacyPreviewAuthState(lifecycle: PreviewGrantLifecycle | null): LegacyPreviewAuthState;
+export declare function isPreviewLifecyclePhase(value: unknown): value is PreviewLifecyclePhase;

package/dist/grant-lifecycle.js

@@ -0,0 +1,74 @@
+export function transitionPreviewGrantLifecycle(current, event) {
+    if (event.type === 'start') {
+        return {
+            phase: 'connecting',
+            sessionId: event.sessionId,
+            attempt: 0,
+            since: event.at,
+        };
+    }
+    if (current === null) {
+        throw new Error(`Preview grant lifecycle received ${event.type} before start`);
+    }
+    if (event.type === 'blocked') {
+        return {
+            phase: 'blocked',
+            sessionId: current.sessionId,
+            attempt: current.attempt,
+            since: event.at,
+            code: event.code,
+            message: event.message,
+        };
+    }
+    if (event.type === 'ready') {
+        return {
+            phase: 'ready',
+            sessionId: current.sessionId,
+            attempt: 0,
+            since: event.at,
+            readyAt: event.at,
+            generation: event.generation,
+        };
+    }
+    const lastReadyAt = current.phase === 'ready'
+        ? current.readyAt
+        : current.phase === 'reconnecting'
+            ? current.lastReadyAt
+            : null;
+    if (lastReadyAt === null) {
+        return {
+            phase: 'connecting',
+            sessionId: current.sessionId,
+            attempt: current.attempt + 1,
+            since: current.since,
+        };
+    }
+    return {
+        phase: 'reconnecting',
+        sessionId: current.sessionId,
+        attempt: current.attempt + 1,
+        since: current.phase === 'reconnecting' ? current.since : event.at,
+        lastReadyAt,
+        cause: event.cause,
+    };
+}
+export function legacyPreviewAuthState(lifecycle) {
+    if (lifecycle === null)
+        return 'idle';
+    switch (lifecycle.phase) {
+        case 'connecting':
+            return 'authenticating';
+        case 'ready':
+            return 'authenticated';
+        case 'reconnecting':
+            return 'refreshing';
+        case 'blocked':
+            return 'error';
+    }
+}
+export function isPreviewLifecyclePhase(value) {
+    return (value === 'connecting' ||
+        value === 'ready' ||
+        value === 'reconnecting' ||
+        value === 'blocked');
+}

package/dist/identity/__test-adapter.d.ts

@@ -0,0 +1,34 @@
+/**
+ * ADR-116 D6 — fake framework adapter for core unit tests.
+ *
+ * Validates the contract (`navigateTo`, `subscribeToLocation`,
+ * `getCurrentLocation`) without pulling React / Next / TanStack. Tests
+ * use it to drive identity-resolver scenarios end-to-end.
+ *
+ * Public surface :
+ *  - `createTestAdapter()` returns a `{ adapter, harness }` pair.
+ *  - `harness.setLocation({pathname, search, hash})` rewrites the
+ *    current location and notifies subscribers (the framework adapter
+ *    contract's `subscribeToLocation` callback).
+ *  - `harness.replaceCalls` is the log of `navigateTo` invocations.
+ */
+import type { FrameworkAdapter, FrameworkLocation } from './identity-types.js';
+export interface TestAdapterHarness {
+    setLocation(loc: Partial<FrameworkLocation>): void;
+    replaceCalls: ReadonlyArray<{
+        path: string;
+        opts?: {
+            refresh?: boolean;
+        };
+    }>;
+    /**
+     * Number of currently-attached subscribers. Tests assert this returns
+     * to 0 after the resolver unsubscribes on teardown.
+     */
+    subscriberCount(): number;
+}
+export interface TestAdapterPair {
+    adapter: FrameworkAdapter;
+    harness: TestAdapterHarness;
+}
+export declare function createTestAdapter(initial?: Partial<FrameworkLocation>): TestAdapterPair;

package/dist/identity/__test-adapter.js

@@ -0,0 +1,59 @@
+/**
+ * ADR-116 D6 — fake framework adapter for core unit tests.
+ *
+ * Validates the contract (`navigateTo`, `subscribeToLocation`,
+ * `getCurrentLocation`) without pulling React / Next / TanStack. Tests
+ * use it to drive identity-resolver scenarios end-to-end.
+ *
+ * Public surface :
+ *  - `createTestAdapter()` returns a `{ adapter, harness }` pair.
+ *  - `harness.setLocation({pathname, search, hash})` rewrites the
+ *    current location and notifies subscribers (the framework adapter
+ *    contract's `subscribeToLocation` callback).
+ *  - `harness.replaceCalls` is the log of `navigateTo` invocations.
+ */
+export function createTestAdapter(initial = {}) {
+    let location = {
+        pathname: initial.pathname ?? '/',
+        search: initial.search ?? '',
+        hash: initial.hash ?? '',
+    };
+    const subscribers = new Set();
+    const replaceCalls = [];
+    const adapter = {
+        navigateTo(path, opts) {
+            replaceCalls.push({ path, opts });
+        },
+        subscribeToLocation(cb) {
+            subscribers.add(cb);
+            return () => {
+                subscribers.delete(cb);
+            };
+        },
+        getCurrentLocation() {
+            return location;
+        },
+    };
+    const harness = {
+        setLocation(loc) {
+            location = {
+                pathname: loc.pathname ?? location.pathname,
+                search: loc.search ?? location.search,
+                hash: loc.hash ?? location.hash,
+            };
+            for (const cb of subscribers) {
+                try {
+                    cb(location);
+                }
+                catch {
+                    /* defensive */
+                }
+            }
+        },
+        replaceCalls,
+        subscriberCount() {
+            return subscribers.size;
+        },
+    };
+    return { adapter, harness };
+}

package/dist/identity/browser-context-gate.d.ts

@@ -0,0 +1,4 @@
+/** Public bootstrap hint only. The same-origin token route still authorizes it. */
+export declare function readStandalonePreviewSessionId(expectedProjectId?: string): string | null;
+/** Small, framework-independent gate; never loads the authenticated runtime. */
+export declare function isPreviewBrowserContext(expectedProjectId?: string): boolean;

package/dist/identity/browser-context-gate.js

@@ -0,0 +1,22 @@
+import { readStandaloneStored } from './carriers/storage-state.js';
+import { PREVIEW_SESSION_QUERY_PARAM, readPreviewSessionIdFromSearch } from './session-query.js';
+/** Public bootstrap hint only. The same-origin token route still authorizes it. */
+export function readStandalonePreviewSessionId(expectedProjectId) {
+    if (typeof window === 'undefined' || window.parent !== window)
+        return null;
+    const search = window.location.search;
+    if (new URLSearchParams(search).has(PREVIEW_SESSION_QUERY_PARAM)) {
+        const sessionId = readPreviewSessionIdFromSearch(search);
+        return sessionId && /^[A-Za-z0-9_-]{1,180}$/.test(sessionId) ? sessionId : null;
+    }
+    const stored = readStandaloneStored();
+    if (!stored?.standalone || (expectedProjectId && stored.projectId !== expectedProjectId))
+        return null;
+    return /^[A-Za-z0-9_-]{1,180}$/.test(stored.sessionId) ? stored.sessionId : null;
+}
+/** Small, framework-independent gate; never loads the authenticated runtime. */
+export function isPreviewBrowserContext(expectedProjectId) {
+    if (typeof window === 'undefined')
+        return false;
+    return window.parent !== window || readStandalonePreviewSessionId(expectedProjectId) !== null;
+}

package/dist/identity/browser-context.d.ts

@@ -0,0 +1,13 @@
+/** Public return target only, retained for a refused cold boot of this view. */
+export declare function readStandaloneStudioUrl(projectId: string | null, sessionId: string | null): string | null;
+/** Called after an authenticated bootstrap response, never for a URL payload. */
+export declare function rememberStandaloneView(view: {
+    projectId: string;
+    sessionId: string;
+    parentOrigin: string;
+    studioUrl: string;
+}): void;
+/** Persistent interaction choice for this view only; access is authorized separately. */
+export declare function readStandaloneInteractionMode(projectId: string | null, sessionId: string | null): 'edit' | 'browse';
+export { rememberStandaloneInteractionMode } from './carriers/storage.js';
+export { readStandalonePreviewSessionId, isPreviewBrowserContext } from './browser-context-gate.js';

package/dist/identity/browser-context.js

@@ -0,0 +1,22 @@
+import { writeStandaloneStored, rememberStandaloneStudioUrl, readStandaloneStored, } from './carriers/storage.js';
+/** Public return target only, retained for a refused cold boot of this view. */
+export function readStandaloneStudioUrl(projectId, sessionId) {
+    if (!projectId || !sessionId || typeof window === 'undefined' || window.parent !== window)
+        return null;
+    const stored = readStandaloneStored();
+    return stored?.standalone && stored.projectId === projectId && stored.sessionId === sessionId ? stored.studioUrl ?? null : null;
+}
+/** Called after an authenticated bootstrap response, never for a URL payload. */
+export function rememberStandaloneView(view) {
+    writeStandaloneStored(view);
+    rememberStandaloneStudioUrl(view, view.studioUrl);
+}
+/** Persistent interaction choice for this view only; access is authorized separately. */
+export function readStandaloneInteractionMode(projectId, sessionId) {
+    const stored = readStandaloneStored();
+    return projectId && sessionId && stored?.standalone && stored.projectId === projectId && stored.sessionId === sessionId
+        ? stored.interactionMode ?? 'edit'
+        : 'edit';
+}
+export { rememberStandaloneInteractionMode } from './carriers/storage.js';
+export { readStandalonePreviewSessionId, isPreviewBrowserContext } from './browser-context-gate.js';