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

package/dist/select-cursor.js

@@ -0,0 +1,23 @@
+/**
+ * Shared Select-mode cursor for both Studio-owned capture layers and the
+ * customer iframe interaction policy.
+ *
+ * The compact, softened arrow geometry adapts Hugeicons' `Cursor 02` in its
+ * stroke-rounded style. It is scaled inside the cursor canvas so its generous
+ * white under-stroke stays visible without clipping. The composed black
+ * silhouette receives a soft, nearly centered shadow that follows the rounded
+ * artwork rather than mimicking the sharper macOS pointer.
+ */
+const PREVIEW_SELECT_CURSOR_PATH = 'M9.80282 4.62973 15.8364 6.99069C19.3164 8.35243 21.0564 9.03329 20.9987 10.1133 20.941 11.1934 19.1251 11.6886 15.4933 12.6791 14.412 12.974 13.8713 13.1215 13.4964 13.4963 13.1215 13.8712 12.9741 14.4119 12.6791 15.4933 11.6887 19.125 11.1934 20.9409 10.1134 20.9986 9.03335 21.0563 8.35249 19.3163 6.99075 15.8363L4.62979 9.80276C3.20411 6.15934 2.49127 4.33764 3.41448 3.41442 4.3377 2.49121 6.15941 3.20405 9.80282 4.62973Z';
+const PREVIEW_SELECT_CURSOR_TRANSFORM = 'translate(0.75 0.75) scale(0.81)';
+const PREVIEW_SELECT_CURSOR_SVG = [
+    '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">',
+    '<defs><filter id="shadow" x="-4" y="-4" width="32" height="32" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB"><feDropShadow dx="0" dy="0.25" stdDeviation="1.05" flood-color="#000" flood-opacity="0.22"/></filter></defs>',
+    '<g filter="url(#shadow)">',
+    `<path transform="${PREVIEW_SELECT_CURSOR_TRANSFORM}" d="${PREVIEW_SELECT_CURSOR_PATH}" fill="none" stroke="#fff" stroke-width="5" stroke-linejoin="round"/>`,
+    `<path transform="${PREVIEW_SELECT_CURSOR_TRANSFORM}" d="${PREVIEW_SELECT_CURSOR_PATH}" fill="#000" stroke="#000" stroke-width="1.25" stroke-linejoin="round"/>`,
+    '</g>',
+    '</svg>',
+].join('');
+/** CSS cursor value, including the tip-aligned hotspot and native fallback. */
+export const PREVIEW_SELECT_CURSOR = `url("data:image/svg+xml,${encodeURIComponent(PREVIEW_SELECT_CURSOR_SVG)}") 4 4, pointer`;

package/dist/server/admission-cookie.d.ts

@@ -0,0 +1,38 @@
+/** Server-only, authenticated browser admissions. HTTP arrival order is not authority. */
+import { StorystickError } from '@storystick/client';
+import { type PreviewGrantCookie } from './grant.js';
+export interface PreviewCookieReader {
+    getAll(): Array<{
+        name: string;
+        value: string;
+    }>;
+}
+export type AdmissionScope = {
+    projectId: string;
+    requestOrigin: string;
+    apiKey: string;
+};
+export type PreviewAdmission = {
+    sequence: number;
+    expiresAt: number;
+} & ({
+    kind: 'active';
+    grant: PreviewGrantCookie;
+} | {
+    kind: 'closed';
+});
+export declare const PREVIEW_CLOSURE_TTL_MS: number;
+export declare function admissionCookieName(scope: AdmissionScope, admission: Pick<PreviewAdmission, 'kind' | 'sequence'>): Promise<string>;
+export declare function admissionPresenceName(scope: AdmissionScope, admission: Pick<PreviewAdmission, 'kind' | 'sequence'>): Promise<string>;
+export declare function encodePreviewAdmission(admission: PreviewAdmission, scope: AdmissionScope): Promise<string>;
+export declare function admissionError(code: string, message: string): StorystickError;
+export declare function admissionNames(reader: PreviewCookieReader, scope: AdmissionScope): Array<{
+    name: string;
+    sequence: number;
+    kind: 'active' | 'closed';
+    value: string;
+}>;
+export declare function readPreviewAdmission(reader: PreviewCookieReader, scope: AdmissionScope): Promise<PreviewAdmission | undefined>;
+/** Only fresh authenticated activation may collect invalid names. The unguessable
+ * name tag prevents a deletion response from addressing a future valid cookie. */
+export declare function invalidAdmissionNames(reader: PreviewCookieReader, scope: AdmissionScope): Promise<string[]>;

package/dist/server/admission-cookie.js

@@ -0,0 +1,122 @@
+/** Server-only, authenticated browser admissions. HTTP arrival order is not authority. */
+import { StorystickError } from '@storystick/client';
+import { previewPresenceCookieName } from '@storystick/preview/identity/preview-cookie';
+import { previewCapabilityCookieName } from './grant.js';
+const MAX_COOKIE_BYTES = 3000;
+// Also bounds parsing/HMAC work. Never silently choose an older admission on overflow.
+const MAX_ADMISSION_COOKIES = 16;
+export const PREVIEW_CLOSURE_TTL_MS = 24 * 60 * 60 * 1000;
+const encoder = new TextEncoder();
+function base64(bytes) {
+    return btoa(String.fromCharCode(...bytes)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+}
+function bytes(value) {
+    return Uint8Array.from(atob(value.replace(/-/g, '+').replace(/_/g, '/')), c => c.charCodeAt(0));
+}
+async function key(scope) {
+    if (!scope.apiKey)
+        throw new Error('Preview admission requires a server API key');
+    // Domain separation from every other use of the site's server credential.
+    const material = await crypto.subtle.digest('SHA-256', encoder.encode(`storystick:preview-admission:v1\0${scope.apiKey}`));
+    return crypto.subtle.importKey('raw', material, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign', 'verify']);
+}
+async function suffix(scope, admission) {
+    // An observed malformed name cannot coincide with a future valid write.
+    const tag = base64(new Uint8Array(await crypto.subtle.sign('HMAC', await key(scope), encoder.encode(`name:${admission.sequence}`)))).slice(0, 22);
+    return `_${admission.kind === 'active' ? 'a' : 'x'}${admission.sequence}_${tag}`;
+}
+export async function admissionCookieName(scope, admission) {
+    return previewCapabilityCookieName(scope) + await suffix(scope, admission);
+}
+export async function admissionPresenceName(scope, admission) {
+    return previewPresenceCookieName(scope) + await suffix(scope, admission);
+}
+export async function encodePreviewAdmission(admission, scope) {
+    // Do not persist the short-lived access JWT. Exchanges are cached server-side.
+    const payload = [1, admission.kind, admission.sequence, admission.expiresAt, scope.projectId, scope.requestOrigin,
+        ...(admission.kind === 'active' ? [admission.grant.grantId, admission.grant.grantToken,
+            admission.grant.contentShapeCapability, admission.grant.applicationBuildId ?? null] : [])];
+    const encoded = base64(encoder.encode(JSON.stringify(payload)));
+    const signature = base64(new Uint8Array(await crypto.subtle.sign('HMAC', await key(scope), encoder.encode(encoded))));
+    const result = `${encoded}.${signature}`;
+    if (result.length > MAX_COOKIE_BYTES)
+        throw admissionError('PREVIEW_ADMISSION_LIMIT', 'This Preview opening exceeds the browser cookie size limit.');
+    return result;
+}
+async function decode(value, scope) {
+    try {
+        if (value.length > MAX_COOKIE_BYTES)
+            throw new Error();
+        const [payload, signature, extra] = value.split('.');
+        if (!payload || !signature || extra !== undefined || !await crypto.subtle.verify('HMAC', await key(scope), bytes(signature), encoder.encode(payload)))
+            throw new Error();
+        const data = JSON.parse(new TextDecoder().decode(bytes(payload)));
+        if (!Array.isArray(data) || data[0] !== 1 || !Number.isSafeInteger(data[2]) || data[2] <= 0 ||
+            !Number.isSafeInteger(data[3]) || data[3] <= 0 || data[4] !== scope.projectId || data[5] !== scope.requestOrigin)
+            throw new Error();
+        const base = { sequence: data[2], expiresAt: data[3] };
+        if (data[1] === 'closed' && data.length === 6)
+            return { ...base, kind: 'closed' };
+        if (data[1] !== 'active' || data.length !== 10 || ![data[6], data[7], data[8]].every(v => typeof v === 'string' && v.length > 0) ||
+            !(data[9] === null || typeof data[9] === 'string'))
+            throw new Error();
+        return { ...base, kind: 'active', grant: {
+                v: 2, grantId: data[6], grantToken: data[7], grantExpiresAt: base.expiresAt,
+                projectId: scope.projectId, previewOrigin: scope.requestOrigin,
+                contentShapeCapability: data[8], ...(data[9] === null ? {} : { applicationBuildId: data[9] }),
+                accessToken: '', accessExpiresAt: 0,
+            } };
+    }
+    catch {
+        throw admissionError('PREVIEW_GRANT_MALFORMED', 'Preview admission is invalid. Open Preview from Studio again.');
+    }
+}
+export function admissionError(code, message) {
+    return new StorystickError(message, { code: `storystick/${code}`, category: 'auth', recoverable: true, retryable: false });
+}
+export function admissionNames(reader, scope) {
+    const prefix = previewCapabilityCookieName(scope);
+    return reader.getAll().flatMap(({ name, value }) => {
+        if (!name.startsWith(prefix + '_'))
+            return [];
+        const match = /^_([ax])([1-9]\d*)_([A-Za-z0-9_-]{22})$/.exec(name.slice(prefix.length));
+        const sequence = Number(match?.[2]);
+        if (!match || !Number.isSafeInteger(sequence))
+            throw admissionError('PREVIEW_GRANT_MALFORMED', 'Invalid Preview admission name.');
+        return [{ name, value, sequence, kind: match[1] === 'a' ? 'active' : 'closed' }];
+    });
+}
+export async function readPreviewAdmission(reader, scope) {
+    if (!scope.requestOrigin)
+        throw admissionError('PREVIEW_ORIGIN_MISMATCH', 'Preview requires a verified request origin.');
+    const candidates = admissionNames(reader, scope);
+    if (candidates.length > MAX_ADMISSION_COOKIES)
+        throw admissionError('PREVIEW_ADMISSION_LIMIT', 'Too many Preview openings. Open Preview from Studio again.');
+    candidates.sort((a, b) => b.sequence - a.sequence || Number(b.kind === 'closed') - Number(a.kind === 'closed'));
+    const latest = candidates[0];
+    if (!latest)
+        return undefined;
+    // Authenticate the winner, never filter invalid/expired/closed winners then fall back.
+    const admission = await decode(latest.value, scope);
+    if (admission.sequence !== latest.sequence || admission.kind !== latest.kind || latest.name !== await admissionCookieName(scope, admission))
+        throw admissionError('PREVIEW_GRANT_MALFORMED', 'Preview admission binding is invalid.');
+    return admission;
+}
+/** Only fresh authenticated activation may collect invalid names. The unguessable
+ * name tag prevents a deletion response from addressing a future valid cookie. */
+export async function invalidAdmissionNames(reader, scope) {
+    const prefix = previewCapabilityCookieName(scope);
+    const invalid = [];
+    for (const cookie of reader.getAll()) {
+        if (!cookie.name.startsWith(prefix + '_'))
+            continue;
+        try {
+            const admission = await decode(cookie.value, scope);
+            if (cookie.name === await admissionCookieName(scope, admission))
+                continue;
+        }
+        catch { /* no authority */ }
+        invalid.push(cookie.name);
+    }
+    return invalid;
+}

package/dist/server/control-client.d.ts

@@ -0,0 +1,29 @@
+/** Server-side Preview control uses public Storystick HTTP, never Convex RPC. */
+import type { PreviewPerspective } from '@storystick/types/preview-query-targeting';
+export declare function previewControlClient(endpoint: string, token: string): {
+    context: <T = unknown>(input?: {
+        sessionId?: string;
+        includeProjectionCheckpoint?: boolean;
+        includeRouting?: boolean;
+    }) => Promise<T>;
+    session: (input: {
+        sessionId: string;
+        mode?: "routing-only";
+    }) => Promise<unknown>;
+    draft: (input: {
+        sessionId: string;
+        draftDocumentId?: string;
+        locale?: string;
+        contextId: string;
+        revision: number;
+        fallbackPolicy?: "none" | "explicit";
+    }) => Promise<unknown>;
+    changeContext: (input: {
+        commandId: string;
+        expectedContextId: string;
+        expectedRevision: number;
+        perspective: PreviewPerspective | null;
+    }) => Promise<{
+        status: "applied" | "conflict";
+    }>;
+};

package/dist/server/control-client.js

@@ -0,0 +1,22 @@
+export function previewControlClient(endpoint, token) {
+    async function call(operation, input) {
+        const response = await fetch(`${endpoint.replace(/\/$/, '')}/api/preview/control`, {
+            method: 'POST', cache: 'no-store', redirect: 'error',
+            headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+            body: JSON.stringify({ operation, input }),
+        });
+        const body = await response.json();
+        if (!response.ok) {
+            const code = typeof body?.error?.code === 'string' ? body.error.code : 'PREVIEW_CONTROL_UNAVAILABLE';
+            // Keep the native preview error carrier consumed by mapPreviewSessionError.
+            throw Object.assign(new Error(code), { data: { code } });
+        }
+        return body;
+    }
+    return {
+        context: (input = {}) => call('context', input),
+        session: (input) => call('session', input),
+        draft: (input) => call('draft', input),
+        changeContext: (input) => call('change-context', input),
+    };
+}

package/dist/server/control-errors.d.ts

@@ -0,0 +1,22 @@
+import type { PreviewAdapterError } from "@storystick/preview/server/grant";
+export type PreviewRouteErrorCategory = "system" | "auth" | "validation" | "conflict" | "cancel";
+export type PreviewRouteError = {
+    status: number;
+    code: string;
+    message: string;
+    category: PreviewRouteErrorCategory;
+    recoverable: boolean;
+    retryable: boolean;
+};
+type ResponseError = PreviewAdapterError | PreviewRouteError;
+export declare function previewInitialRouteErrorResponse(request: Request, error: ResponseError): Response;
+export declare function previewErrorResponse(error: PreviewAdapterError): Response;
+export declare function previewErrorResponse(error: PreviewRouteError): Response;
+export declare function previewErrorResponse(status: number, code: string, message: string, opts?: {
+    category?: PreviewRouteErrorCategory;
+    recoverable?: boolean;
+    retryable?: boolean;
+}): Response;
+/** Preserve typed authorization failures; never expose upstream exception text. */
+export declare function previewControlErrorResponse(error: unknown): Response;
+export {};

package/dist/server/control-errors.js

@@ -0,0 +1,165 @@
+import { StorystickError } from "@storystick/client";
+import { mapPreviewSessionError } from "@storystick/preview/session-subscriber";
+export function previewInitialRouteErrorResponse(request, error) {
+    if (error.recoverable && requestAcceptsHtml(request)) {
+        return previewHtmlErrorResponse(error, new URL(request.url).searchParams.get("_ss_session"));
+    }
+    return previewErrorResponse(error);
+}
+export function previewErrorResponse(statusOrError, code, message, opts = {}) {
+    if (typeof statusOrError !== "number") {
+        return Response.json({
+            error: {
+                code: statusOrError.code,
+                message: statusOrError.message,
+                category: statusOrError.category,
+                recoverable: statusOrError.recoverable,
+                retryable: statusOrError.retryable,
+                ...('upstreamCode' in statusOrError && { upstreamCode: statusOrError.upstreamCode }),
+                ...('upstreamRef' in statusOrError && { upstreamRef: statusOrError.upstreamRef }),
+            },
+        }, {
+            status: statusOrError.status,
+            headers: { "Cache-Control": "no-store" },
+        });
+    }
+    return Response.json({
+        error: {
+            code: code,
+            message: message,
+            category: opts.category ?? "system",
+            recoverable: opts.recoverable ?? false,
+            retryable: opts.retryable ?? false,
+        },
+    }, {
+        status: statusOrError,
+        headers: { "Cache-Control": "no-store" },
+    });
+}
+function requestAcceptsHtml(request) {
+    const accept = request.headers.get("accept");
+    if (accept === null)
+        return false;
+    return accept
+        .split(",")
+        .map((part) => part.trim().toLowerCase().split(";", 1)[0])
+        .includes("text/html");
+}
+function previewHtmlErrorResponse(error, sessionId) {
+    return new Response(buildHtmlError(error, sessionId), {
+        status: error.status,
+        headers: {
+            "Cache-Control": "no-store",
+            "Content-Type": "text/html; charset=utf-8",
+        },
+    });
+}
+function buildHtmlError(error, sessionId) {
+    // Only structured, known activation failures cross this pre-runtime seam.
+    // The parent accepts them only from its addressed frame, origin and session.
+    const diagnosticCodes = ['PREVIEW_PROJECT_MISMATCH', 'PREVIEW_ACTIVATION_INVALID',
+        'PREVIEW_GRANT_EXPIRED', 'PREVIEW_GRANT_REVOKED', 'PREVIEW_ACCESS_REVOKED', 'PREVIEW_GRANT_FORBIDDEN'];
+    const diagnostic = sessionId && /^[A-Za-z0-9_-]{1,128}$/.test(sessionId) && diagnosticCodes.includes(error.code)
+        ? `<script>window.parent.postMessage(${JSON.stringify({ type: 'storystick.preview.activation-error', sessionId, code: error.code })}, '*');</script>`
+        : '';
+    const code = escapeHtml(error.code);
+    const message = escapeHtml(error.message);
+    const retryScript = error.retryable
+        ? `<script>
+    (() => {
+      const maxAttempts = 12;
+      let attempt = 0;
+      const retry = async () => {
+        attempt += 1;
+        try {
+          const response = await fetch(window.location.href, {
+            cache: 'no-store',
+            redirect: 'follow',
+            headers: { Accept: 'application/json' },
+          });
+          if (response.redirected || (response.ok && response.url !== window.location.href)) {
+            window.location.replace(response.url);
+            return;
+          }
+          if (response.ok) {
+            window.location.reload();
+            return;
+          }
+        } catch (_) {}
+        if (attempt >= maxAttempts) {
+          document.body.dataset.previewRecovery = 'stopped';
+          return;
+        }
+        const delay = Math.min(5000, Math.round(500 * Math.pow(1.5, attempt - 1)));
+        window.setTimeout(retry, delay);
+      };
+      window.setTimeout(retry, 500);
+    })();
+  </script>`
+        : "";
+    const title = error.retryable ? "Preview recovering" : "Preview unavailable";
+    const heading = error.retryable
+        ? "Preview reconnecting"
+        : error.code === "PREVIEW_PROJECT_MISMATCH" ? "Preview is connected to another project" : "Reopen this preview from Storystick Studio";
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${title}</title>
+  <style>
+    :root { color-scheme: light dark; font-family: system-ui, sans-serif; }
+    body { margin: 0; min-height: 100vh; display: grid; place-items: center; background: Canvas; color: CanvasText; }
+    main { max-width: 28rem; padding: 1.5rem; line-height: 1.5; }
+    h1 { font-size: 1rem; margin: 0 0 .5rem; }
+    p { margin: 0; color: color-mix(in srgb, CanvasText 70%, transparent); }
+    code { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: .8125rem; }
+  </style>
+</head>
+<body>
+  <main aria-live="polite">
+    <h1>${heading}</h1>
+    <p data-preview-error="${code}">${message}</p>
+  </main>
+  ${diagnostic}
+  ${retryScript}
+</body>
+</html>`;
+}
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (char) => {
+        switch (char) {
+            case "&":
+                return "&amp;";
+            case "<":
+                return "&lt;";
+            case ">":
+                return "&gt;";
+            case '"':
+                return "&quot;";
+            case "'":
+                return "&#39;";
+            default:
+                return char;
+        }
+    });
+}
+/** Preserve typed authorization failures; never expose upstream exception text. */
+export function previewControlErrorResponse(error) {
+    if (error instanceof StorystickError) {
+        return previewErrorResponse(error.category === 'auth' ? 401 : error.category === 'conflict' ? 409 : error.retryable ? 503 : 502, error.code?.replace(/^storystick\//, '') ?? 'PREVIEW_CONTEXT_UNAVAILABLE', 'Preview access is unavailable.', {
+            category: error.category, recoverable: error.recoverable, retryable: error.retryable,
+        });
+    }
+    const mapped = mapPreviewSessionError(error);
+    if (mapped.code === 'PREVIEW_ADMISSION_SUPERSEDED')
+        return previewErrorResponse(409, mapped.code, 'Preview changed. Reconnecting to the installed admission.', { category: 'conflict', recoverable: true, retryable: true });
+    if (mapped.code !== 'UNKNOWN') {
+        return previewErrorResponse(401, mapped.code, 'Preview access is no longer available.', {
+            category: 'auth', recoverable: true, retryable: false,
+        });
+    }
+    return previewErrorResponse(503, 'PREVIEW_CONTEXT_UNAVAILABLE', 'Preview is temporarily unavailable.', {
+        category: 'system', recoverable: true, retryable: true,
+    });
+}

package/dist/server/draft-route.d.ts

@@ -0,0 +1,12 @@
+import { type RequestLocaleContext, type LocaleRoutingSettings } from '@storystick/client';
+export declare function pathnameForPreviewDraft(document: {
+    readonly resolvedPathname?: unknown;
+    readonly fields?: unknown;
+}): string;
+export declare function previewDocumentSeo(document: {
+    readonly fields?: unknown;
+}): {
+    indexable: boolean;
+    canonicalUrl?: string;
+};
+export declare function localeContextForPreviewDraft(pathname: string | readonly string[] | undefined, settings: LocaleRoutingSettings): RequestLocaleContext | null;

package/dist/server/draft-route.js

@@ -0,0 +1,45 @@
+import { normalizePathname, resolveLocalePathname } from '@storystick/client';
+function isRecord(value) { return typeof value === 'object' && value !== null && !Array.isArray(value); }
+export function pathnameForPreviewDraft(document) {
+    const fields = isRecord(document.fields) ? document.fields : {};
+    const resolved = typeof document.resolvedPathname === 'string'
+        ? document.resolvedPathname
+        : typeof fields.resolvedPathname === 'string'
+            ? fields.resolvedPathname
+            : typeof fields.pathname === 'string'
+                ? fields.pathname
+                : '';
+    return normalizePathname(resolved);
+}
+export function previewDocumentSeo(document) {
+    const fields = isRecord(document.fields) ? document.fields : {};
+    const indexable = fields.noIndex !== true;
+    if (typeof fields.canonicalUrl !== 'string')
+        return { indexable };
+    try {
+        const canonicalUrl = new URL(fields.canonicalUrl.trim());
+        if ((canonicalUrl.protocol === 'http:' || canonicalUrl.protocol === 'https:') &&
+            canonicalUrl.username === '' &&
+            canonicalUrl.password === '') {
+            return { indexable, canonicalUrl: canonicalUrl.toString() };
+        }
+    }
+    catch {
+        // Draft metadata stays readable; strict publication returns a typed error.
+    }
+    return { indexable };
+}
+export function localeContextForPreviewDraft(pathname, settings) {
+    const route = resolveLocalePathname(pathname, settings);
+    if (!route.ok)
+        return null;
+    return {
+        locale: route.locale,
+        defaultLocale: settings.defaultLocale,
+        pathname: route.pathname,
+        publicPathname: route.publicPathname,
+        locales: settings.locales,
+        localeRouting: settings.localeRouting,
+        synthetic: settings.synthetic === true,
+    };
+}

package/dist/server/extract-token.d.ts

@@ -0,0 +1,30 @@
+import { type PreviewGrantCookie } from './grant.js';
+import { type AdmissionScope, type PreviewCookieReader } from './admission-cookie.js';
+export type CookieStoreLike = PreviewCookieReader;
+export interface ResolvePreviewGrantAccessOptions extends AdmissionScope {
+    endpoint: string;
+    applicationBuildId?: string;
+    now?: number;
+}
+export interface PreviewGrantAccessFields {
+    token: string;
+    tokenExpiresAt: number;
+    projectId: string;
+    previewOrigin: string;
+    grantId: string;
+    grantExpiresAt: number;
+    admissionSequence: number;
+    /** Server-only handles. Never serialize these into browser responses. */
+    grantToken: string;
+    contentShapeCapability: string;
+}
+type ReadyGrant = PreviewGrantCookie & {
+    contentShapeCapability: string;
+    admissionSequence: number;
+};
+export declare function readPreviewGrantCookie(cookieStore: CookieStoreLike, scope: AdmissionScope, now?: number): Promise<ReadyGrant | null | undefined>;
+export declare function primePreviewGrantAccess(grant: ReadyGrant, options: ResolvePreviewGrantAccessOptions): void;
+export declare function clearPreviewGrantAccessCache(): void;
+/** null is an explicitly closed admission, distinct from a missing credential. */
+export declare function resolvePreviewGrantAccess(cookieStore: CookieStoreLike, options: ResolvePreviewGrantAccessOptions): Promise<PreviewGrantAccessFields | null | undefined>;
+export {};

package/dist/server/extract-token.js

@@ -0,0 +1,98 @@
+import { StorystickError } from '@storystick/client';
+import { PreviewGrantExchangeError, classifyPreviewGrantError, exchangePreviewGrantForServer, } from './grant.js';
+import { readPreviewAdmission, admissionError } from './admission-cookie.js';
+export async function readPreviewGrantCookie(cookieStore, scope, now = Date.now()) {
+    const admission = await readPreviewAdmission(cookieStore, scope);
+    if (!admission)
+        return undefined;
+    if (admission.kind === 'closed')
+        return null;
+    if (admission.expiresAt <= now)
+        throw admissionError('PREVIEW_GRANT_EXPIRED', 'Preview grant expired. Open Preview from Studio again.');
+    return { ...admission.grant, contentShapeCapability: admission.grant.contentShapeCapability, admissionSequence: admission.sequence };
+}
+// A cache of short-lived credentials, not permissions: every downstream read
+// still validates the grant and human session. Keys include ALL server bindings.
+const accessCache = new Map();
+const exchanges = new Map();
+const MAX_ACCESS_CACHE = 64;
+function cacheKey(grant, options) {
+    return JSON.stringify([options.endpoint, options.apiKey, options.projectId, options.requestOrigin,
+        options.applicationBuildId, grant.admissionSequence, grant.grantToken, grant.contentShapeCapability]);
+}
+function remember(key, value) {
+    accessCache.delete(key);
+    accessCache.set(key, value);
+    while (accessCache.size > MAX_ACCESS_CACHE)
+        accessCache.delete(accessCache.keys().next().value);
+}
+export function primePreviewGrantAccess(grant, options) {
+    remember(cacheKey(grant, options), {
+        token: grant.accessToken, tokenExpiresAt: grant.accessExpiresAt,
+        grantId: grant.grantId, grantExpiresAt: grant.grantExpiresAt, grantToken: grant.grantToken,
+        projectId: grant.projectId, previewOrigin: grant.previewOrigin,
+        admissionSequence: grant.admissionSequence, contentShapeCapability: grant.contentShapeCapability,
+    });
+}
+export function clearPreviewGrantAccessCache() { accessCache.clear(); }
+/** null is an explicitly closed admission, distinct from a missing credential. */
+export async function resolvePreviewGrantAccess(cookieStore, options) {
+    const now = options.now ?? Date.now();
+    const grant = await readPreviewGrantCookie(cookieStore, options, now);
+    if (!grant)
+        return grant;
+    if (grant.applicationBuildId !== options.applicationBuildId) {
+        throw new StorystickError('Open Preview again from Studio after the application build changed.', {
+            code: 'storystick/CONTENT_SHAPE_RELOAD_REQUIRED', category: 'conflict', recoverable: true, retryable: false,
+        });
+    }
+    const key = cacheKey(grant, options);
+    const cached = accessCache.get(key);
+    if (cached && cached.tokenExpiresAt - 30_000 > now)
+        return cached;
+    accessCache.delete(key);
+    const pending = exchanges.get(key);
+    if (pending)
+        return pending;
+    const flight = exchangeGrant(grant, options, key, now);
+    // Bound shared bookkeeping; overflowing independent requests still authorize.
+    if (exchanges.size < MAX_ACCESS_CACHE)
+        exchanges.set(key, flight);
+    try {
+        return await flight;
+    }
+    finally {
+        if (exchanges.get(key) === flight)
+            exchanges.delete(key);
+    }
+}
+async function exchangeGrant(grant, options, key, now) {
+    try {
+        const exchange = await exchangePreviewGrantForServer({
+            endpoint: options.endpoint, apiKey: options.apiKey, applicationBuildId: options.applicationBuildId,
+            grantToken: grant.grantToken, requestOrigin: options.requestOrigin, contentShapeCapability: grant.contentShapeCapability,
+        });
+        if (exchange.projectId !== grant.projectId || exchange.previewOrigin !== grant.previewOrigin ||
+            exchange.grantId !== grant.grantId || exchange.admissionSequence !== grant.admissionSequence ||
+            exchange.grantExpiresAt !== grant.grantExpiresAt) {
+            throw admissionError('PREVIEW_GRANT_BINDING_MISMATCH', 'Preview exchange returned incompatible bindings.');
+        }
+        const fields = {
+            token: exchange.token, tokenExpiresAt: now + exchange.tokenExpiresIn * 1_000,
+            projectId: grant.projectId, previewOrigin: grant.previewOrigin, grantId: grant.grantId,
+            grantExpiresAt: grant.grantExpiresAt, grantToken: grant.grantToken,
+            admissionSequence: grant.admissionSequence, contentShapeCapability: grant.contentShapeCapability,
+        };
+        remember(key, fields);
+        return fields;
+    }
+    catch (error) {
+        if (!(error instanceof PreviewGrantExchangeError))
+            throw error;
+        const publicError = classifyPreviewGrantError(error, 'exchange');
+        throw new StorystickError(`${publicError.code} — ${publicError.message}`, {
+            code: `storystick/${publicError.code}`, ref: publicError.upstreamRef,
+            category: publicError.category, recoverable: publicError.recoverable, retryable: publicError.retryable,
+        });
+    }
+}